Line
Version next
Search GitHub

You are reading the unreleased docs (next). See latest (v0.9)

packages/engine/scopeLinks

Scope/binding link graph: for ONE element of a page, which of the page's in-scope names (destructured props, useState values/setters) flow into which of that element's props, and which props the child component declar...

Engine, next. Source: packages/engine/scopeLinks.mjs.

Functions#

buildScopeLinks(pageSource, nodeId, options?): any

Defined in: packages/engine/scopeLinks.mjs:241

Build the scope/binding graph for element nodeId.

Returns {nodeId, tag, isCustomComponent, scope, links, spreads, childProps, undeclared, suggestions, unusedScope, childPropsResolved}:

  • scope: [{name, kind: 'prop'|'state'|'setter'|'provider'|'unit-output'}] page declarations available to the element -- 'provider' (a reachable Provider's exposed field, , only added when providerSources resolves it) and 'unit-output' (a name already destructured from an already-called tracked-state hook) alongside the original 'prop'/'state'/'setter' set.
  • links: one per named attribute {prop, valueKind, text, from: [{name, kind}]}; valueKind is 'literal' | 'identifier' | 'expression'. from is empty when the value uses no scope name.
  • spreads: [{text, from}] for {...x} attributes.
  • childProps: (only when the child's declared props are a closed, known set) [{name, status}], status 'bound' (passed), 'spread' (maybe covered by a spread) or 'unbound'; else null.
  • undeclared: passed props the (closed) child doesn't declare.
  • suggestions: unbound child props with a same-named in-scope declaration (an auto-map candidate).
  • unusedScope: scope names referenced by no element's attributes anywhere in the page.
  • scopeTypes/childPropTypes: {name: typeText} maps, sibling fields (never folded into scope/childProps' own item shape, so the original arrays stay byte-for-byte what every existing caller/test already expects) giving a best-effort, purely-syntactic type for a scope name / declared child prop where one could be read off source text -- a name absent from the map means "type not known", never a guess. A 'setter'-kind name always gets '(value) => void' (the one thing always true of every useState setter, not an inference). Throws an Error with code: 'NO_SUCH_NODE' for an unknown id.

Parameters#

pageSource

string

Source of the page.

nodeId

string

Id of the JSX element (from the JSX tree).

options?

Source of the child component, so its declared props can be checked; providerSources maps a reachable Provider hook import's source path OR its imported hook name to that hook's own file source, so its exposed fields can be resolved -- omitted or unresolved entries simply add no 'provider' scope for that import, exactly like an unresolved childSource leaves childProps null.

childSource?

string

providerSources?

Record<string, string>

Returns#

any

The scope and binding graph described above.

Throws#

With code: 'NO_SUCH_NODE' for an unknown id.

importOfTag()#

importOfTag(pageSource, tag): object

Defined in: packages/engine/scopeLinks.mjs:55

The import backing a tag's root name ({source, isDefault}) or null -- for callers that must fetch the child component's source before calling buildScopeLinks.

Parameters#

pageSource

string

Source of the page.

tag

string

JSX tag, possibly dotted (Ui.Button); its root name is looked up.

Returns#

object

The import that backs the tag, or null for a local or unimported name.

isDefault

isDefault: boolean

source

source: string

providerExposedFields()#

providerExposedFields(hookSource, hookName): object[]

Defined in: packages/engine/scopeLinks.mjs:119

The field names a Provider hook exposes via useProvider(), read from the hook's own file source: finds defineProvider<Props, Value>(...)'s second type argument (following a local const XProvider = defineProvider<...>(...) binding when the export is export const use<Name>Provider = XProvider.useProvider, or the inline call directly), then that Value type's member names (findTypeMembers, the same TS-compiler-API introspection declaredPropNames already uses for a child component's Props). type is that member's own type annotation text, null when it has none.

Parameters#

hookSource

string

Source of the file the Provider hook is exported from.

hookName

string

The hook's exported name (use<Name>Provider).

Returns#

object[]

Fields, or null when the hook/its Value type can't be resolved (unknown shape, open/index-signature type) -- callers treat null as "don't add sources".

providerHookImports()#

providerHookImports(ast): object[]

Defined in: packages/engine/scopeLinks.mjs:78

Provider hooks reachable from the page's own top-level imports: one {source, hookName} per specifier, from a hooks?/ path, whose imported name is a real Provider hook name (use<Name>Provider) -- the same reachability boundary PAGE-006 already enforces. Exported so a caller resolving providerSources across files (ui/server's getScopeLinks) can reuse this exact detection instead of re-deriving the naming-convention check a third time.

Parameters#

ast

any

The page's parsed AST (parseJsx(pageSource)).

Returns#

object[]

One entry per reachable Provider hook import.