@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/entities/system/defineComponent.d.ts

@@ -0,0 +1,428 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { Authored } from "../../framework/authoring.js";
+import { StyleValue } from "./style-bag.js";
+import { VariantValues } from "./Component.js";
+import { ComponentPropsWithoutRef, JSX, ReactNode } from "react";
+
+//#region src/entities/system/defineComponent.d.ts
+/**
+ * Enough of another component to BE a layer's element — the handle `defineComponent` returns, with
+ * its declarations forgotten so a builder of any shape fits.
+ *
+ * Named separately from `AuthoredComponent` because that one fixes the declarations at their widest,
+ * and a layer must keep the ones the referenced component actually made: they're where its props come
+ * from. `ComponentBuilder<{root:'button'}, …>` satisfies this; it does not satisfy `AuthoredComponent`.
+ */
+interface ComponentElement extends Authored {
+  readonly kind: 'component';
+  readonly path?: string;
+}
+/**
+ * A PACKAGE element — a component imported from a package (`import { View } from 'react-native'`).
+ * TypeScript sees the real package's own component type here, so a typo'd export is a compile
+ * error against the package's actual surface; at config runtime the loader binds the import to
+ * the `package:` ref the config stores. The shape is broad on purpose: which function/class shape
+ * a package exports is its business, and the check that matters (does this export exist) already
+ * ran at compile time against the real types.
+ */
+type PackageElement = ((...args: never[]) => unknown) | (abstract new (...args: never[]) => unknown);
+/**
+ * A layer IS its element: a native tag, another component, a ref to one, or a package export.
+ *
+ * The component and the ref to it are the same thing stored — `toStored` turns the first into the
+ * second. They differ only in what a COMPILER can see: a ref is a string, so the props the component
+ * it names exposes are gone by the time anything could read them, and a component built on `Pressable`
+ * typed `onClick` as nothing at all.
+ */
+type LayerElement = string | ComponentElement | Ref | PackageElement;
+/**
+ * A component's layers. `root` is REQUIRED and is the element a consumer addresses: its React props
+ * are the component's props, and a component that doesn't declare one has no element to be.
+ *
+ * That requirement is what removes a decision. Without it the addressable element had to be named
+ * separately, and a component whose root was a wrapper (`Input`'s root a `div`, its `input` on an
+ * inner layer) typed `onChange` against the wrong element. The answer is to author the root as the
+ * element being addressed, not to add a second way of saying which one it is.
+ */
+type LayerMap = {
+  root: LayerElement;
+} & Record<string, LayerElement>;
+/**
+ * A `<layer>/<prop>` address into one of a component's OWN layers — what a forward routes into.
+ *
+ * The whole reason `.props()` used to take a callback: `layerRef('icon')` is a free function over
+ * `string`, so it could name a layer that doesn't exist. Handed to the props parameter as a TYPE
+ * instead, the same check applies to a plain object, and the helper it existed to type has nothing
+ * left to do.
+ *
+ * Falls back to `string` where the layers aren't known — a body read back from the config, or the
+ * erased builder the callable form returns.
+ */
+type LayerPath<L extends LayerMap = LayerMap> = `${keyof L & string}/${string}`;
+/**
+ * A CONTENT HOLE — a prop the render places itself, carrying no route.
+ *
+ * It used to carry `target`/`into` as well, which made one type mean two things: a hole, and a prop
+ * piped into a layer. That second meaning IS a forward — it routes this prop into another prop, and
+ * the target happening to be a slot is incidental — so it lives there now and this type is only the
+ * hole. `{ type: 'forward', target: 'label/children' }`, which produced a targeted slot, is `{ type: 'forward', target:
+ * 'label/children' }`.
+ *
+ * Named as its own interface, rather than inlined in {@link PropDecl}, so `ValueOf` can tell a slot
+ * from anything else: a widened union left a slot prop inferring as `unknown` where the same prop
+ * written by hand stayed a `ReactNode`.
+ */
+interface SlotDecl {
+  type: 'slot';
+  /**
+   * What may FILL this hole, as refs. Two shapes, both in this repo:
+   *
+   *   - an icon LIBRARY — `Button.startIcon` accepts `Icon.ref('phosphor')`, so any glyph that library
+   *     registers can be dropped in
+   *   - a COMPONENT — `PanelSegment` accepts `Component.ref('studio/PanelSegment/PanelSegmentCell')`
+   *
+   * Both reach the same picker; they differ in what gets written (a glyph name versus a placed element).
+   *
+   * Meaningful only where content lands, which is why a route carries it too — but only when it routes
+   * into a hole. A route into a value prop has nothing to narrow: which values are valid is that prop's
+   * own declaration.
+   */
+  accepts?: Ref | Ref[];
+  text?: boolean;
+  required?: boolean;
+}
+/**
+ * A prop routed to a prop of one of the component's own layers — `<Field disabled />` setting the
+ * `input` layer's `disabled`, instead of a caller reaching through `layerProps`.
+ *
+ * Named separately from {@link SlotDecl} because a slot carries CONTENT and owns `accepts` / `text`,
+ * and because a slot may be a plain hole the render places itself. A forward has no meaning except
+ * as a route, so both halves are required.
+ */
+/**
+ * What one layer forwards — `'*'` for every prop that layer's element exposes, or the names of the
+ * props to take.
+ *
+ * Authored as NAMES and stored as member refs (`component:Input#props/disabled`), the same
+ * normalization {@link ForwardDecl}'s `into` gets: a name is invisible to the dependency graph, so
+ * storing refs is what makes a rename cascade and a delete refuse.
+ */
+type Forwarded = '*' | readonly string[];
+/**
+ * A prop ROUTED into a prop of one of this component's own layers — `<Field disabled />` setting the
+ * `input` layer's `disabled`, `<Button>text</Button>` filling the `label` layer's `children`. One
+ * declaration for both, because they are the same act: this prop becomes that one.
+ *
+ * AUTHORED as a single `<layer>/<prop>` path, typed against the layers just declared. STORED as the
+ * pair the readers want — the layer as a `layerRef`, and the target prop as a MEMBER ref, so the
+ * dependency graph sees the edge and a rename of that prop cascades into this declaration.
+ */
+interface ForwardDecl<Path extends string = string> {
+  type: 'forward';
+  /** `<layer>/<prop>` as authored; a `layerRef` once stored, with the prop moved to `into`. */
+  target: Path | Ref;
+  /** STORED only — a member ref at the prop on that layer's element
+   *  (`component:Input#props/disabled`). Minted at registration, when the layer's element has a path. */
+  into?: string | Ref;
+  /** Only where this route LANDS on a hole — it means exactly what {@link SlotDecl.accepts} means.
+   *  That the target is a hole is computed from it (`routesContent`), so the rule is checked rather
+   *  than trusted, and a route into a value prop is refused by name. */
+  accepts?: Ref | Ref[];
+  text?: boolean;
+  required?: boolean;
+}
+/**
+ * One prop's declaration, in both the form it is AUTHORED in and the form it is STORED in.
+ *
+ * Written out rather than taken from the schema (`AuthoredPropBody` is exactly that) for one reason:
+ * a variant's rendered prop should be the union of its values, and that needs the literal tuple an
+ * author wrote — `['sm','lg'] as const` — which a zod-inferred `string[]` has already widened away.
+ * So the two coexist and {@link SchemaAccepts} pins this one to what the schema takes, which is the
+ * part that could otherwise drift.
+ *
+ * A variant's `value` therefore has three forms: the list an author writes, the keyed collection it
+ * is stored as (each value a member with a name, an order and a body), and a ref that delegates the
+ * whole domain to whatever owns it.
+ *
+ * `required` is on every arm because the SCHEMA has always accepted it on every arm — a slot can be
+ * mandatory (a Card that makes no sense without its content) exactly as a variant can. It was spelled
+ * on `variant` alone, so a consumer reading a stored prop had to widen the exported type by hand to
+ * see a field the config was already storing.
+ */
+type PropDecl<Path extends string = string> = SlotDecl | ForwardDecl<Path> | {
+  type: 'variant';
+  value: readonly string[] | VariantValues | Ref;
+  required?: boolean;
+} | {
+  type: 'styleProperty';
+  value: Ref;
+  required?: boolean;
+} | {
+  type: 'composite';
+  value: Ref;
+  required?: boolean;
+} | {
+  type: 'motion';
+  required?: boolean;
+} | {
+  type: 'string' | 'number' | 'boolean';
+  required?: boolean;
+};
+/**
+ * One prop as AUTHORED — a declaration, or one of the two bare forms that already say what they are:
+ *
+ *   `bg: StyleProperty.ref('bg')`   a bare REF. It names a kind, so a `type` beside it would say the
+ *                                   same thing twice; `toStored` derives the tag from that kind.
+ *   `size: ['sm', 'lg']`            a bare LIST — an enumerated variant. The values ARE the
+ *                                   declaration.
+ *
+ * Only authoring is widened: the STORED form is always the tagged {@link PropDecl}, which is what
+ * every reader switches on. (v1 did the same in its authoring adapter — it just assumed every bare ref
+ * was a style property, where this reads the kind.)
+ */
+type AuthoredProp<Path extends string = string> = PropDecl<Path> | Ref | readonly string[];
+/**
+ * A component's prop declarations. `null` is the OMIT tombstone the stored schema already accepts: a
+ * component that `.forwards({ root: '*' })` drops one of the base's props by declaring it `null`, which is
+ * how `Image` extends a `Box` and still refuses children.
+ */
+type PropMap<Path extends string = string> = Record<string, AuthoredProp<Path> | null>;
+/** The arm of a declaration union whose `type` this body claims — so exactness below is judged against
+ *  ONE shape rather than against the intersection of every arm's fields. */
+type ArmFor<D, U> = D extends {
+  type: infer T;
+} ? Extract<U, {
+  type: T;
+}> : never;
+/**
+ * `D`, with every key its own arm does not declare BANNED.
+ *
+ * Necessary because `.props()` takes a generic (`const P extends PropMap<…>`), and a generic constraint
+ * is an assignability check — excess property checking never runs, so a field the arm doesn't declare
+ * is simply invisible. That let `{ type: 'slot', target: 'icon/children' }` compile on a component with
+ * no `icon` layer, and a misspelt `txt: true` compile as nothing at all.
+ *
+ * Mapping the stray keys to `never` is what makes them errors: the value written there — a string, an
+ * object — is not assignable to `never`. Generic over the union, so it holds for every arm rather than
+ * naming the fields one shape happens to forbid.
+ *
+ * A body with no `type` (a bare ref, a bare list of variant values, the `null` tombstone) selects no
+ * arm and is handed back untouched — those forms say what they are by their shape.
+ */
+type Exact<D, U> = [ArmFor<D, U>] extends [never] ? D : D & { [K in Exclude<keyof D, keyof ArmFor<D, U>>]: never };
+/** A style rule: what to apply, and the prop values it applies under. */
+interface StyleRuleInput<L extends LayerMap> {
+  /** Prop → value, all of which must hold. Absent means unconditional. A value is whatever the prop
+   *  it names offers, so a boolean prop's condition is a boolean. */
+  readonly when?: Record<string, string | number | boolean>;
+  /** Per layer — and only a layer this component declared. */
+  readonly layers: Partial<Record<keyof L & string, Record<string, StyleValue>>>;
+}
+/** The TS type one prop declaration produces on the rendered component. */
+type ValueOf<D> = D extends readonly (infer Member)[] ? Member : D extends {
+  type: 'variant';
+  value: infer V;
+} ? V extends readonly (infer Member)[] ? Member : V extends VariantValues ? keyof V & string : string : D extends {
+  type: 'string';
+} ? string : D extends {
+  type: 'number';
+} ? number : D extends {
+  type: 'boolean';
+} ? boolean : D extends {
+  type: 'slot';
+} ? ReactNode : D extends {
+  type: 'forward';
+  target: `${string}/children`;
+} ? ReactNode : unknown;
+/**
+ * A prop type's DECLARED props — everything but its index signature.
+ *
+ * A component's props end in `Record<string, unknown>`, so `keyof` them is `string`, and anything
+ * key-driven downstream sees that one open key instead of the declared ones. `Omit` is the case that
+ * matters: it's how a component's own props shadow the ones it takes from its element, and over an
+ * open type it kept everything as `unknown` — a component built on `Pressable` typed `onClick`'s
+ * parameter as `any` and accepted any value at all for `tone`.
+ */
+type Declared<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+/** What a prop map really exposes: each declaration's value type, with the `null` tombstones — the
+ *  props it DROPS from what it inherits — gone from the surface entirely. */
+type DeclaredProps<P> = { [K in keyof P as P[K] extends null ? never : K]: ValueOf<P[K]> };
+/**
+ * The props the rendered ELEMENT contributes.
+ *
+ * That element's React props are part of the component's surface — `<Pressable onClick={e => …}>`
+ * types `e` because `Pressable` renders a `button`. Left out, every handler a consumer passed fell
+ * into the open index signature and its parameter had no contextual type, which turned ~75 untouched
+ * call sites into implicit-`any` errors.
+ */
+type ElementPropsOf<Element> = Element extends keyof JSX.IntrinsicElements ? ComponentPropsWithoutRef<Element> : Element extends ((props: infer PropsOfComponent) => unknown) ? Declared<PropsOfComponent> : Record<never, never>;
+/**
+ * Which element that is: the one a `defaultProps.as` FIXES, else the root layer.
+ *
+ * Two ways of saying it because they say different things. A root layer is what the component is
+ * ARRANGED from — it may be another component, and then the element is whatever that one renders.
+ * `as` is what a component PINS: `Input` is a Box in every other respect and an `<input>` in this
+ * one, so the layer stays the component it extends while `as` names the tag. Reading only the layer
+ * typed `Input`'s `onChange` against a `div` and lost `event.target.value` at every call site.
+ */
+type ElementOf<L extends LayerMap, D> = D extends {
+  as: infer As;
+} ? As : L['root'];
+/**
+ * The props a consumer may pass — the declared ones, the rendered element's, and the style props.
+ *
+ * The element contributes only what the component didn't already name, because a name the component
+ * declares is a REDEFINITION of it. Intersected instead, the two meanings met and cancelled:
+ * `Input`'s `size` offers `'xs' | 'sm' | 'md' | 'lg'` while `<input size>` is a `number`, so
+ * `size="sm"` failed with "string is not assignable to undefined" — an empty intersection, which is
+ * the type saying no value could ever satisfy both.
+ *
+ * Open at the end on purpose: a component's style-prop surface is the system's, not this file's.
+ */
+type ComponentPropsOf<L extends LayerMap, P extends PropMap, D = Record<never, never>, E = Record<never, never>, F extends string = never> = Partial<DeclaredProps<P>> & Partial<E> & Omit<ElementPropsOf<ElementOf<L, D>>, keyof P | keyof E> & Omit<ForwardedPropsOf<L, F>, keyof P | keyof E> & Record<string, unknown>;
+/**
+ * The props a component picks up from the layers it FORWARDS.
+ *
+ * `Partial`, and permissive about which forwarded layer a prop came from: the surface is already open
+ * at the end (`Record<string, unknown>`), so this changes no assignability — what it changes is that a
+ * forwarded prop is DISCOVERABLE on the handle instead of vanishing into the tail.
+ *
+ * Root is excluded here because {@link ElementOf} already contributes the element a consumer really
+ * addresses. Counting root again is not harmless when `defaultProps.as` pins a different element:
+ * Input is Box-backed but renders an input, and intersecting both event surfaces makes every handler
+ * accept `HTMLDivElement | HTMLInputElement` instead of the input it actually receives.
+ */
+type NonRootForward<L extends LayerMap, F extends string> = Exclude<F, 'root'> & keyof L;
+type ForwardedPropsOf<L extends LayerMap, F extends string> = [NonRootForward<L, F>] extends [never] ? Record<never, never> : Partial<ElementPropsOf<L[NonRootForward<L, F>]>>;
+/**
+ * Defaults a component applies with nothing set — its declared props, typed, plus the style props it
+ * may also default.
+ *
+ * The open half is `unknown`, not `StyleValue`. Intersected with `Record<string, StyleValue>` every
+ * DECLARED prop had to satisfy both, so a slot defaulting to an element was rejected for not being a
+ * style value — which is the intersection checking the wrong half.
+ */
+type DefaultsOf<P extends PropMap> = Partial<DeclaredProps<P>> & {
+  [key: string]: unknown;
+};
+/** What a render receives: the generated per-layer bundle, plus the props the component declared. */
+type RenderArgs<L extends LayerMap, P extends PropMap> = {
+  readonly props: Record<keyof L & string, Record<string, unknown>>;
+} & DeclaredProps<P> & Record<string, unknown>;
+interface ComponentBuilder<L extends LayerMap, P extends PropMap,
+/** Props the RENDER takes that the config doesn't describe — React handlers, mostly (`onPress`).
+ *  They're part of the component's surface but not of its data, which is why they're declared at
+ *  `.render()` rather than in `.props()`. */
+E = Record<never, never>,
+/** The defaults as AUTHORED, kept because one of them decides the type of every other prop: an
+ *  `as` fixes which element this renders. See {@link ElementOf}. */
+D = Record<never, never>,
+/** The layers this component FORWARDS from, as a union of their names. Accumulates through
+ *  `.forwards()` so `ComponentPropsOf` can union each forwarded layer's element props — `root` is
+ *  already covered structurally by {@link ElementOf}, so for a root-only forward this changes no
+ *  inferred type, which is what makes replacing `inherits` a no-op at every call site. */
+F extends string = never> extends Authored {
+  /**
+   * A phantom call signature — the authored value is NEVER rendered (the build substitutes the
+   * emitted module), but `export type ButtonProps = ComponentProps<typeof Button>` is how a consumer
+   * names its props, and that reads this type.
+   */
+  (props: ComponentPropsOf<L, P, D, E, F>): null;
+  readonly kind: 'component';
+  /** The authored body, readable so codegen can pair it with the render found in the source. */
+  readonly body: Record<string, unknown>;
+  readonly path?: string;
+  layers<const L2 extends LayerMap>(layers: L2): ComponentBuilder<L2, P, E, D, F>;
+  /**
+   * This component's props.
+   *
+   * A plain object, typed against the layers just declared: a forward's `target` must be a
+   * `<layer>/<prop>` of THIS component, which is the one check the `.props()` callback existed to
+   * provide. The callback and its `layer`/`bind` helpers are gone — they only ever split a path string
+   * that the parameter's own type now checks.
+   */
+  props<const P2 extends PropMap<LayerPath<L>>>(props: P2 & NoInfer<{ [K in keyof P2]: Exact<P2[K], AuthoredProp<LayerPath<L>>> }>): ComponentBuilder<L, P2, E, D, F>;
+  styles(rules: readonly StyleRuleInput<L>[]): ComponentBuilder<L, P, E, D, F>;
+  /**
+   * What this component applies with nothing set.
+   *
+   * Typed against the props just declared, so a default names a real prop and takes a value that
+   * prop accepts — `{ size: 'md' }` is an error when `size` offers `'sm' | 'lg'`. Style props stay
+   * open, since a component's style-prop surface is the system's, not this file's.
+   *
+   * `const`, so an `as` keeps its literal type: without it `{ as: 'input' }` widens to `string` and
+   * there's no tag left to resolve the element's props against.
+   */
+  defaultProps<const D2 extends DefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F>;
+  /**
+   * The layers whose element props this component ALSO exposes, keyed by layer.
+   *
+   * The CONFIG props those layers' components expose, not their element props — those come from the
+   * element this renders. `'*'` takes the whole surface; a list of names takes those props only, and
+   * is an ALLOWLIST: dropping a forwarded prop is `.props({ x: null })`.
+   *
+   * One call taking a record, not a repeatable per-layer call, because `emit-config` writes authoring
+   * source FROM stored config — every keyed collection there is one call with a record literal, and a
+   * second authored form would make generated source drift from what a person writes.
+   */
+  forwards<const F2 extends Readonly<Partial<Record<keyof L & string, Forwarded>>>>(forwards: F2): ComponentBuilder<L, P, E, D, F | (keyof F2 & string)>;
+  /**
+   * What a person is told about this component: the label a picker shows, and what it's for.
+   * `guidance` is for a model composing with it, in the imperative voice of a rule; the guidance
+   * document collects it into its Components topic. `hidden` and `deprecated` retire it short of
+   * deleting it, the same two flags every entity carries.
+   */
+  metadata(meta: {
+    label?: string;
+    description?: string;
+    guidance?: string;
+    hidden?: boolean;
+    deprecated?: boolean;
+  }): ComponentBuilder<L, P, E, D, F>;
+  /**
+   * The anatomy: which elements this component renders, in what order and nesting.
+   *
+   * Never called and never stored. A component's data says what its layers ARE; only this says how
+   * they're arranged, and that is CODE — it can read a context or declare a handler. The build reads
+   * it from the source and copies it verbatim, so what it returns is irrelevant; declaring it is
+   * what puts it in the file.
+   */
+  render<E2 = E>(fn: (args: RenderArgs<L, P> & E2) => unknown): ComponentBuilder<L, P, E2, D, F>;
+  /**
+   * An optional browser-canvas anatomy for a native component.
+   *
+   * Native components normally reuse {@link render} through React Native Web on the design canvas.
+   * Use this only when the phone anatomy is a poor fit for a browser canvas (a full-screen safe-area
+   * wrapper, for example). Like `render`, it is source-read build input and stores no config data.
+   */
+  renderCanvas<E2 extends E = E>(fn: (args: RenderArgs<L, P> & E2) => unknown): ComponentBuilder<L, P, E, D, F>;
+  /**
+   * What a preview of this component STARTS from — the props a single tile is rendered with.
+   *
+   * Only `defaultProps`, because the grid itself is derived: every axis a matrix could sweep is
+   * already declared in `styles`, as the conditions the rules apply under, and the modifier columns
+   * are the `_hover`/`_active` blocks those rules contain. An authored matrix restated all of it and
+   * could disagree with it — a variant added to `styles` and forgotten in the matrix simply never
+   * appeared. See `previewMatrix`.
+   */
+  preview(spec: {
+    defaultProps?: DefaultsOf<P>;
+  }): ComponentBuilder<L, P, E, D, F>;
+  toStored(): Record<string, unknown>;
+  assignPath(path: string): void;
+}
+/** A component under authorship, with its declarations forgotten — what a registry holds. */
+type AuthoredComponent = ComponentBuilder<LayerMap, PropMap, unknown, unknown>;
+interface DefineComponent {
+  /** The one-layer form: the element IS the component. */
+  <const El extends LayerElement>(element: El): ComponentBuilder<{
+    root: El;
+  }, Record<never, never>>;
+  /** The whole body at once, for a component with nothing to narrow step by step. */
+  (body?: Record<string, unknown>): AuthoredComponent;
+  layers<const L extends LayerMap>(layers: L): ComponentBuilder<L, Record<never, never>>;
+  props<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
+}
+declare const defineComponent: DefineComponent;
+//#endregion
+export { AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, LayerElement, LayerMap, PropDecl, PropMap, RenderArgs, StyleRuleInput, defineComponent };