@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/render-spec.d.ts

@@ -0,0 +1,296 @@
+import { Config } from "./Config.js";
+import { StateCondition } from "@json-render/core";
+
+//#region src/framework/render-spec.d.ts
+/** A node in a flat render spec — json-render's own shape, which is what a canvas paints.
+ *
+ *  Distinct from {@link import('./validate-spec').SpecNode}, the NESTED form a design file authors
+ *  and `validateSpec` checks: that one is a tree of instances a person composed, this one is the
+ *  flat `elements` map a renderer walks. */
+interface RenderElement {
+  readonly type: string;
+  readonly props?: Record<string, unknown>;
+  readonly children?: string[];
+  /** json-render's own slot grammar: slot name → the element keys that fill it. */
+  readonly slots?: Record<string, string[]>;
+  /** json-render's own visibility grammar, borrowed rather than reinvented. Left `unknown` because a
+   *  json-render `Spec` is read through this type too, and its grammar has `$item`, `$index` and
+   *  `$and` arms the entity refuses. */
+  readonly visible?: unknown;
+}
+interface RenderSpec {
+  readonly root: string;
+  readonly elements: Record<string, RenderElement>;
+}
+/** What a build produces per component: the anatomy, and the tile a catalogue shows. */
+interface ComponentSpecs {
+  readonly render?: RenderSpec;
+  readonly preview?: RenderSpec;
+}
+/**
+ * The node a tree ENTERS at — the one nothing else claims as a child.
+ *
+ * A name can't answer this. `root` names the root LAYER, and a render is free to put a wrapper above
+ * that layer — a menu provider, a positioner, a portal — so the layer is somewhere in the middle of
+ * its own tree. Entering by name amputated every ancestor: the tree rendered without the provider
+ * that its own descendants read from, and those descendants threw on the first paint.
+ *
+ * Structure states it instead, and in a whole tree exactly one node is unclaimed. Two or more is a
+ * FOREST — a reader that couldn't finish, or a condition that left siblings with no parent — and then
+ * the component is whichever of them holds most of it: the strays get dropped either way, and
+ * dropping the real tree to render a stray leaf is the worse of the two. Nothing unclaimed at all
+ * (a cycle) falls back to the name, which is the best a malformed tree deserves.
+ */
+declare function entryKeyOf(nodes: Record<string, {
+  readonly children?: readonly string[];
+  readonly slots?: Record<string, string[]>;
+} | undefined>): string;
+/**
+ * A component's anatomy, projected to the json-render spec a canvas reads.
+ *
+ * The artifact's SOURCE changes and its shape does not: `element` becomes `type` and a ref
+ * serializes to its string form, while `children` / `visible` / `text` pass through, since those
+ * were borrowed from json-render's own vocabulary rather than invented.
+ *
+ * A component with no stored anatomy but ONE layer is still answered outright — it is one element,
+ * and that was always stated rather than run.
+ */
+declare function deriveSpec(config: Config, path: string): RenderSpec | undefined;
+/**
+ * ONE COMPONENT, as a spec — the instance form, and the only place the `component:` prefix is minted.
+ *
+ * A spec type is `kind:identity`, always: the emitted registry keys every entry that way and holds
+ * no bare names, so `Box` resolves to nothing while `component:Box` resolves to the module. That
+ * makes the prefix load-bearing rather than decorative, and something load-bearing spelled by
+ * string-concatenation at each site is a spelling waiting to drift — three places in this file did
+ * it, and a consumer that wanted the same shape had no choice but to add a fourth.
+ *
+ * So consumers ask for the SHAPE instead of assembling it, and the type itself comes from `ref` —
+ * the same maker `Component.ref` is bound to — rather than a template. A caller outside this
+ * package has no business knowing the prefix at all.
+ */
+declare function instanceSpec(path: string, props?: Record<string, unknown>): RenderSpec;
+/** A component's spec, and WHICH OF THE TWO it is. */
+interface ComponentSpec {
+  readonly spec: RenderSpec;
+  /**
+   * What `spec` describes — the component's own structure, or the component as one element.
+   *
+   * `'composition'` is its internal tree, so an editor may author it. `'leaf'` is the component
+   * itself, correct to paint but with no tree in it: an editor offering composition tools against one
+   * would be offering to restructure something it cannot see.
+   *
+   * Not a capability claim, because two different ones already read as that and neither is this.
+   * Whether a component ACCEPTS CHILDREN is `childrenPolicy` (`'none' | 'text' | 'nodes'`), and it is
+   * orthogonal — a `div`-rooted component with layers and no anatomy takes nodes while having no tree
+   * to show, and a void-rooted one can project a tree and accept nothing.
+   */
+  readonly kind: 'composition' | 'leaf';
+  /** Why the composition isn't shown, for a surface to say so. Absent when it is. */
+  readonly reason?: string;
+}
+/**
+ * The spec for a component, ALWAYS — the leaf form when its composition doesn't project.
+ *
+ * `deriveSpec` declines rather than guess, and that is right: a tree missing a node is worse than an
+ * admission that it can't be built. But a caller still has to paint something, and the honest thing to
+ * paint is the component ITSELF — one element, `component:<path>`, which the renderer resolves to the
+ * real module with whatever its render closes over intact. That is strictly better than the previous
+ * fallback (a spec captured by an earlier build), which showed a structure the config no longer
+ * describes and let an editor author against it.
+ *
+ * So the two answers are separated: what to RENDER (always available) and WHICH of the two it is. A
+ * surface reads `kind` to decide whether to offer composition tools, and `reason` to explain why not.
+ */
+declare function componentSpec(config: Config, path: string): ComponentSpec;
+/**
+ * A component as it is SHOWN — itself, in the example state its author wrote.
+ *
+ * The sibling above answers "what is this made of", and that is the question a layer panel and a
+ * variant matrix ask. A catalogue card, a palette card and a docs thumbnail ask the other one, and
+ * answering them with a composition is what left those tiles wrong: {@link deriveSpec} reads anatomy
+ * off the render's JSX STATICALLY, without the preview's props, so a prop-driven branch arrives as an
+ * unresolved `$state` condition and prop-driven text doesn't arrive at all. The tile painted the
+ * structure with its example content missing.
+ *
+ * One element, always, whatever the component is made of — because WHO DRAWS IT isn't this
+ * projection's call. A built component is in the renderer's registry, so the element resolves to its
+ * real module and is handed the example props directly. One created in Studio isn't, so
+ * {@link expandSpec} replaces it with the tree the config describes, resolving those same props'
+ * conditions and bound elements on the way. Both paths exist already; emitting the component and
+ * letting the renderer choose is what reaches them.
+ *
+ * Only the preview's props. A component's `defaultProps` are already folded into its layer's
+ * zero-specificity rule at build time, so seeding them here would re-apply as an instance's style
+ * props what the stylesheet has said once already.
+ *
+ * One stored preview value is not a prop yet: JSX such as `startIcon: <Icon/>` crosses config.json as
+ * a `PreviewElement` data marker. It is lowered here into the native `slots` + keyed-element form a
+ * spec authors directly. That makes this projection render-ready for every host instead of relying on
+ * a Studio-only registry wrapper to revive the marker later.
+ */
+declare function previewSpec(config: Config, path: string): RenderSpec | undefined;
+interface ExpandOptions {
+  /**
+   * The spec `type`s the renderer already has a component for — in practice the keys of the
+   * codegen-emitted registry.
+   *
+   * A component in this set is LEFT NAMED, deliberately: its emitted module is the real thing, with
+   * whatever its render closes over (a hook, a context, an event handler) intact, and re-deriving it
+   * from data would be a worse copy of something that already exists. Expansion is for what the
+   * registry CAN'T name — which is exactly a component whose structure is data and whose module was
+   * never built.
+   *
+   * Omitted, everything the config describes expands, which is what a test wants and what a caller
+   * with no registry to consult gets.
+   */
+  readonly rendered?: ReadonlySet<string>;
+}
+interface ExpansionResult {
+  readonly spec: RenderSpec;
+  /** Types left in place that neither the registry nor the config can draw — each would paint
+   *  nothing, so a caller can surface them instead of showing a hole. */
+  readonly unresolved: readonly string[];
+}
+/**
+ * Resolve every element's `visible` CONDITION against a prop bag, leaving a plain boolean.
+ *
+ * json-render evaluates the condition itself at render time, so this changes nothing about what
+ * paints. What it changes is what the spec can be ASKED: an unresolved `{ $state: '/startIcon' }`
+ * says only "it depends", where `false` says "this draws nothing", and a reader that has to decide
+ * whether a container is empty needs the second.
+ *
+ * That reader is the UDS renderer. A container whose children all draw nothing must fall back to its
+ * `props.children` label — and with the condition unresolved it could not tell, so every `Button`
+ * cell in the matrix rendered blank: the root lists `startIcon`/`endIcon`, and an unset icon is a
+ * node whose condition is false. `expandSpec` already resolves visibility for an INSTANCE; this is
+ * the same answer for a spec rendered as the component's own anatomy, where the caller supplies the
+ * state instead of an instance.
+ *
+ * A condition that does not resolve is left exactly as it was, so nothing is claimed about it.
+ */
+declare function specWithResolvedVisibility(spec: RenderSpec, state: Record<string, unknown>): RenderSpec;
+/** The comparison a `$state` test can make: json-render's own operator set, minus the state pointer
+ *  and the `not` modifier. Typed off the library so an operator it adds is a typecheck failure here
+ *  until {@link COMPARATORS} handles it. */
+type VisibilityOperator = Exclude<keyof StateCondition, '$state' | 'not'>;
+/** A value in json-render's `visible` grammar, resolved against a prop bag. `undefined` when this
+ *  reader can't settle it, which leaves the condition on the element for the renderer to judge. */
+declare function resolveVisibility(condition: unknown, state: Record<string, unknown>): boolean | undefined;
+/**
+ * Which PROPS a `visible` condition reads, in the order they appear.
+ *
+ * `resolveVisibility` answers "does this draw here"; this answers "what decides that" — the question
+ * an editor asks. A surface offering to bind visibility to a property needs to know whether one is
+ * already driving it, and a surface refusing an edit needs to name what to change instead of the
+ * layer. Both were guessing: the layers panel told an author to "switch to a matching cell" for a
+ * node gated on a slot being filled, where no cell in the matrix can ever match.
+ *
+ * Duplicates are collapsed, so a condition testing one prop twice reads as the one prop it is about.
+ */
+declare function visibilityStateProps(condition: unknown): string[];
+/** One test a `visible` condition makes, in the terms an editor phrases it with. */
+interface VisibilityTerm {
+  /** The prop the test reads, without the JSON-pointer slash. */
+  readonly prop: string;
+  /** `truthy` is the bare `{ $state }` form; the rest are json-render's comparison operators. */
+  readonly operator: VisibilityOperator | 'truthy';
+  /** The operand, absent for a truthiness test. */
+  readonly value?: unknown;
+  /** Whether the test carries `not: true`. */
+  readonly negated: boolean;
+  /** How this term joins the terms beside it: `and` for an array or `$and`, `or` inside `$or`. */
+  readonly junction: 'and' | 'or';
+  /** Which `$or` group the term belongs to. Members of one `$or` share an index; every term outside
+   *  one has its own, so two `$or` groups side by side stay apart. */
+  readonly group: number;
+}
+/**
+ * The tests a `visible` condition makes, in order, flattened to one list.
+ *
+ * `visibilityStateProps` names the props; this keeps what is asked of each one, so a surface can say
+ * "shows when `tone` is `danger`" rather than "follows `tone`". Grouping survives as `junction` and
+ * `group`: the stored grammar is an and-list whose entries are single tests or one `$or` each, so
+ * the two together are enough to read the condition back. A boolean or a shape this reader does not
+ * know yields no terms.
+ */
+declare function visibilityTerms(condition: unknown): VisibilityTerm[];
+/**
+ * A `visible` condition with every bare truthiness test of `prop` taken out.
+ *
+ * Three answers: `undefined` for a condition that makes no such test, so a caller leaves the field
+ * alone; `null` when nothing survives the removal, which is the value that clears it; otherwise the
+ * condition that remains, unwrapped when one term is left.
+ *
+ * Only the bare form goes — `{ $state: '/prop' }` with no comparison and no `not`, which is the test
+ * a value being present answers. A `$or` group holding one goes whole, since a true member settles
+ * the group; its other members go with it, and moving the fill out later does not bring them back,
+ * which is also true of a bare gate. `$state` is matched without its JSON-pointer slash, so both
+ * spellings are the same test.
+ */
+declare function withoutTruthyTerm({
+  condition,
+  prop
+}: {
+  condition: unknown;
+  prop: string;
+}): unknown;
+/**
+ * The type a BOUND element resolves to, given the value its prop was handed.
+ *
+ * This is the one thing json-render has no vocabulary for — `UIElement.type` is a plain string — so
+ * a stored spec can't hold it and `deriveSpec` declines. An expansion is a different position: the
+ * instance is right here, so the prop has a value, and the prop's own declaration says what domain
+ * that value is drawn from. `Icon` is the case that matters: one bound node, resolved per instance,
+ * rather than 51 conditioned siblings copying a library's index into every component that draws a
+ * glyph.
+ *
+ * Two ways the domain is known, in order: the prop DELEGATES it (`value` is a ref to the library,
+ * which is the shape that keeps 1,530 names in one place), or the prop enumerates its values and the
+ * member is found by asking which group declares it. The second exists because a config migrated
+ * from v1 spells an icon prop as an enumeration, and a glyph is no less resolvable for it.
+ */
+declare function boundElementType(config: Config, componentPath: string, prop: string, value: unknown): string | undefined;
+/** Where one slot prop's content lands. */
+interface SlotTarget {
+  /** The layer that holds the content. */
+  readonly layer: string;
+  /** The prop the content arrives as on the instance (`children`, `startIcon`). */
+  readonly from: string;
+  /** The prop it lands under on the layer — `children` unless the slot said otherwise. */
+  readonly into: string;
+}
+/**
+ * Where a component's slot props route their content, as the config states it.
+ *
+ * {@link expandInstance} has always known this; nothing outside this file could ask. A surface that
+ * needs the same answer had to guess from the spec's shape instead — "the one element carrying a
+ * string" — and a spec projected from the ANATOMY carries no strings at all, so the guess fell
+ * through to the root. For a component whose content slot NAMES its layer that is the wrong element
+ * AND an occupied one: the label lands beside the element children it was supposed to go inside, and
+ * the layer meant to hold it renders empty. Every one of Studio's own components shaped that way
+ * (`Badge`, `StudioButton`, `Toggle`, …) painted as an empty shell in the component editor.
+ *
+ * Exported so the answer has ONE owner. An untargeted slot still resolves to the root here — that is
+ * `slotTargets`' rule, not a caller's assumption, and it is the same rule the expansion renders by.
+ */
+declare function slotTargetsOf(config: Config, path: string): SlotTarget[];
+/**
+ * Expand every component element the renderer can't name into the tree it is made of.
+ *
+ * The spec's own keys are KEPT — an expanded instance's root is emitted under the key it already
+ * had, so a `slots` entry, a selection marker, or anything else that names an element by key
+ * still resolves. Only the nodes an expansion adds get new keys, namespaced under the instance they
+ * belong to.
+ */
+declare function expandSpec(config: Config, spec: RenderSpec, options?: ExpandOptions): ExpansionResult;
+/**
+ * One component instance, expanded from nothing but the config — what a canvas paints for a
+ * component created in Studio.
+ *
+ * The single-element spec this starts from is what a design-file node amounts to, so this is
+ * {@link expandSpec} with the ceremony removed.
+ */
+declare function expandComponent(config: Config, path: string, props?: Record<string, unknown>, options?: ExpandOptions): ExpansionResult;
+//#endregion
+export { ComponentSpec, ComponentSpecs, ExpandOptions, ExpansionResult, RenderElement, RenderSpec, SlotTarget, VisibilityOperator, VisibilityTerm, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, previewSpec, resolveVisibility, slotTargetsOf, specWithResolvedVisibility, visibilityStateProps, visibilityTerms, withoutTruthyTerm };