@yahoo/uds-v5-wip 1.61.0 → 1.62.0

package/dist/config/dist/AssetGroup.d.ts

@@ -0,0 +1,75 @@
+import { AssetKind } from "./asset-kind.js";
+import { IconAssetMember, IconAssetMetadata } from "./defineAssetGroup.js";
+import { FontAssetMember, SerializedAssetGroup } from "./types.js";
+
+//#region ../config/dist/AssetGroup.d.ts
+//#region src/AssetGroup.d.ts
+declare class AssetGroup {
+  #private;
+  /** The slug — the `registerAssetGroups` record key. */
+  readonly name: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly assetKind: AssetKind;
+  /** Member names — the `${assetName}` segment of each asset's id. */
+  readonly assetNames: readonly string[];
+  /** Icon class only — named size → px (picker options = keys). */
+  readonly sizes?: Readonly<Record<string, number>>;
+  /** Icon class only — group-level variant superset. */
+  readonly variants?: readonly string[];
+  /**
+   * Icon class only — the component that authors this group's members
+   * (`'Icon'`). One declaration covers both rendering and export: a placed
+   * member draws on the canvas by rendering through this component, and a
+   * placed asset node serializes to `<Icon name="Trophy" … />` and
+   * round-trips back. Absent for a component-less group, whose members
+   * render bare and export to the bare member tag.
+   */
+  readonly component?: string;
+  /**
+   * Live members keyed by asset name. Present when registered from
+   * code; absent on icon groups hydrated from JSON (the serialized
+   * icon form is a name list).
+   */
+  readonly members?: Readonly<Record<string, IconAssetMember | FontAssetMember>>;
+  /** Icon class only — per-member harvested `.metadata`. Not serialized (yet). */
+  readonly memberMetadata?: Readonly<Record<string, IconAssetMetadata>>;
+  constructor(args: {
+    name: string;
+    label: string;
+    description?: string;
+    assetKind: AssetKind;
+    assetNames: readonly string[];
+    sizes?: Readonly<Record<string, number>>;
+    variants?: readonly string[];
+    component?: string;
+    members?: Readonly<Record<string, IconAssetMember | FontAssetMember>>;
+    memberMetadata?: Readonly<Record<string, IconAssetMetadata>>;
+    /** Live getter so the namespace resolves correctly regardless of
+     *  `configure({ namespace })` / registration ordering. */
+    namespaceGetter?: () => string | undefined;
+  });
+  /** The owning system's registry namespace at read time. */
+  get namespace(): string | undefined;
+  /**
+   * Per-asset identity — `${namespace}:asset:${slug}/${assetName}`
+   * (`uds:asset:icons/Trophy`). Mirrors `Component.registryKey`: an
+   * un-namespaced config produces the bare `asset:${slug}/${name}`
+   * form. This string is the spec `type` and the render-registry key;
+   * it must NEVER route through `Config.getComponent` (which splits on
+   * the first `:` and would silently miss) — resolution is
+   * registry-key lookup only.
+   */
+  assetType(assetName: string): string;
+  toJSON(): SerializedAssetGroup & {
+    name: string;
+  };
+  /**
+   * Rebuild from the wire format. Icon groups hydrate without live
+   * members (names only); font groups hydrate with their full records
+   * — they are the serialized form.
+   */
+  static fromJSON(name: string, json: SerializedAssetGroup, namespaceGetter?: () => string | undefined): AssetGroup;
+} //#endregion
+//#endregion
+export { AssetGroup };

package/dist/config/dist/AssetGroup.js

@@ -0,0 +1,114 @@
+import { compact } from "./entity-utils.js";
+//#region ../config/dist/AssetGroup.js
+var AssetGroup = class AssetGroup {
+	/** The slug — the `registerAssetGroups` record key. */
+	name;
+	label;
+	description;
+	assetKind;
+	/** Member names — the `${assetName}` segment of each asset's id. */
+	assetNames;
+	/** Icon class only — named size → px (picker options = keys). */
+	sizes;
+	/** Icon class only — group-level variant superset. */
+	variants;
+	/**
+	* Icon class only — the component that authors this group's members
+	* (`'Icon'`). One declaration covers both rendering and export: a placed
+	* member draws on the canvas by rendering through this component, and a
+	* placed asset node serializes to `<Icon name="Trophy" … />` and
+	* round-trips back. Absent for a component-less group, whose members
+	* render bare and export to the bare member tag.
+	*/
+	component;
+	/**
+	* Live members keyed by asset name. Present when registered from
+	* code; absent on icon groups hydrated from JSON (the serialized
+	* icon form is a name list).
+	*/
+	members;
+	/** Icon class only — per-member harvested `.metadata`. Not serialized (yet). */
+	memberMetadata;
+	#namespaceGetter;
+	constructor(args) {
+		this.name = args.name;
+		this.label = args.label;
+		this.description = args.description;
+		this.assetKind = args.assetKind;
+		this.assetNames = args.assetNames;
+		this.sizes = args.sizes;
+		this.variants = args.variants;
+		this.component = args.component;
+		this.members = args.members;
+		this.memberMetadata = args.memberMetadata;
+		this.#namespaceGetter = args.namespaceGetter;
+	}
+	/** The owning system's registry namespace at read time. */
+	get namespace() {
+		return this.#namespaceGetter?.();
+	}
+	/**
+	* Per-asset identity — `${namespace}:asset:${slug}/${assetName}`
+	* (`uds:asset:icons/Trophy`). Mirrors `Component.registryKey`: an
+	* un-namespaced config produces the bare `asset:${slug}/${name}`
+	* form. This string is the spec `type` and the render-registry key;
+	* it must NEVER route through `Config.getComponent` (which splits on
+	* the first `:` and would silently miss) — resolution is
+	* registry-key lookup only.
+	*/
+	assetType(assetName) {
+		const bare = `asset:${this.name}/${assetName}`;
+		const namespace = this.namespace;
+		return namespace === void 0 ? bare : `${namespace}:${bare}`;
+	}
+	toJSON() {
+		if (this.assetKind === "font") return {
+			name: this.name,
+			assetKind: "font",
+			label: this.label,
+			...compact({ description: this.description }),
+			members: this.members ?? {}
+		};
+		return {
+			name: this.name,
+			assetKind: "icon",
+			label: this.label,
+			...compact({ description: this.description }),
+			sizes: this.sizes ?? {},
+			variants: this.variants ?? [],
+			members: this.assetNames,
+			...compact({ component: this.component }),
+			...compact({ memberMetadata: this.memberMetadata && Object.keys(this.memberMetadata).length > 0 ? this.memberMetadata : void 0 })
+		};
+	}
+	/**
+	* Rebuild from the wire format. Icon groups hydrate without live
+	* members (names only); font groups hydrate with their full records
+	* — they are the serialized form.
+	*/
+	static fromJSON(name, json, namespaceGetter) {
+		if (json.assetKind === "font") return new AssetGroup({
+			name,
+			label: json.label,
+			description: json.description,
+			assetKind: "font",
+			assetNames: Object.keys(json.members),
+			members: json.members,
+			namespaceGetter
+		});
+		return new AssetGroup({
+			name,
+			label: json.label,
+			description: json.description,
+			assetKind: "icon",
+			assetNames: json.members,
+			sizes: json.sizes,
+			variants: json.variants,
+			component: json.component,
+			memberMetadata: json.memberMetadata,
+			namespaceGetter
+		});
+	}
+};
+//#endregion
+export { AssetGroup };

package/dist/config/dist/Component.d.ts

@@ -0,0 +1,309 @@
+import { BaseStyles, ComponentDefinition, ComponentMetadata, ComponentMotionValue, CompoundPropsEntry, LayerInput, PreviewDefinition, PropBinding, SerializedComponent } from "./types.js";
+import { SlotValueType } from "./markers.js";
+import { ComponentClassNames } from "../../utils/dist/string-utils/componentClassName.js";
+
+//#region ../config/dist/Component.d.ts
+//#region src/Component.d.ts
+/**
+ * Terminal prop value kinds — what a JSX value actually resolves to at
+ * render time. Used both as the discriminant of non-slot `PropInfo`
+ * variants and as a slot's `valueType` after walking its forward chain
+ * to the terminal binding.
+ */
+type PrimitivePropKind = 'string' | 'number' | 'boolean' | 'variant' | 'function';
+/**
+ * Slot value kinds — primitives, `'ReactNode'` for children-style slots, and
+ * `'composite'` when the forward chain bottoms out at a `composite(...)` ref
+ * (so a slot forwarding to a layer's composite prop renders like one).
+ */
+type SlotValueKind = PrimitivePropKind | 'ReactNode' | 'composite';
+/** Discriminant for top-level prop bindings (the `kind` field of `PropInfo`). */
+type PropKind = PrimitivePropKind | 'styleProp' | 'slot';
+/**
+ * Authoring shape of a component — how it was built, which decides how to
+ * author a new one like it:
+ *  - `primitive` — single layer, no `extendsFrom`, no render fn (`Box`).
+ *  - `extends` — value-extends another component via `defineComponent(Parent)`
+ *    (`extendsFrom` is set); inherits the parent's prop surface (`Text`).
+ *  - `multi-layer` — composed from `.layers({...})` and/or a custom `.render`
+ *    (more than one layer, or a render fn) (`StudioListItem`, `Accordion`).
+ */
+type ComponentKind = 'primitive' | 'extends' | 'multi-layer';
+/** Common fields every `PropInfo` variant carries. */
+interface PropBase {
+  /** JSX prop name. */
+  name: string;
+  /** Authored marker had `.required()` (slot/variant markers only carry this). */
+  required: boolean;
+}
+/** Payload for `kind: 'variant'` props. */
+interface VariantInfo {
+  /** Declared variant values in authored order. */
+  values: readonly (string | number | boolean)[];
+}
+/** Payload for `kind: 'styleProp'` props. */
+interface StylePropInfo {
+  /** Style-prop registry key — `'bg'`, `'padding'`, etc. */
+  stylePropName: string;
+}
+/** Payload for `kind: 'function'` props. */
+interface FunctionInfo {
+  /** Function is an event handler (forwards to an `on*` prop). */
+  isEventHandler: boolean;
+}
+/** Payload for `kind: 'composite'` props — bound via `composite('elevation')`. */
+interface CompositeInfo {
+  /** Composite-style registry key — `'elevation'`, `'textVariant'`, etc. */
+  compositeName: string;
+  /** Target layer (defaults to `'root'`). */
+  layer?: string;
+}
+/**
+ * Payload for `kind: 'slot'` props. `layer` undefined ⇒ open slot
+ * (`slot()` with no path). `layerProp` defaults to `'children'` when
+ * only a layer name is given. `accepts` is inherited through the
+ * forward chain — outer `.accepts()` wins; otherwise the innermost
+ * descendant slot's accepts is adopted. `valueType` reports what the
+ * JSX value resolves to at render time after walking the forward chain
+ * to a non-slot binding.
+ *
+ * `authoredType` is the kind the author declared via `slot({ type })`
+ * (absent when undeclared). It records intent independent of resolution:
+ * `derived.acceptsChildNodes` keys on it (a `children` slot the author
+ * tagged `'string'` is a text label, not a node-drop target), and it holds
+ * even when the forward chain can't resolve `valueType` to a primitive.
+ * `valueType` itself now follows a `children` ref into its target and reports
+ * what that resolves to — a Text leaf's `'string'`, a node container's
+ * `'ReactNode'`. Codegen-emitted prop types come from the JSX markers, not
+ * `valueType`, so they never narrow.
+ */
+interface SlotInfo {
+  layer?: string;
+  layerProp: string;
+  accepts?: readonly string[];
+  /**
+   * Slug of the placeable asset group this slot accepts (`slot().accepts(icons)`
+   * → `'icons'`), kept separate from the component-name `accepts` list so the
+   * designer panel can look the group up in `Config.assetGroups` and show its
+   * picker (an icon picker for icon-class groups) instead of the generic
+   * component picker. Absent for component-only slots. The config-load guard
+   * rejects non-placeable groups, so a slug here is always placeable.
+   */
+  acceptsAssetGroup?: string;
+  valueType: SlotValueKind;
+  authoredType?: SlotValueType;
+  /**
+   * Selectable values when the forward chain bottoms out at a `variant`
+   * binding (e.g. forwarding to an inner component's `variant` prop). Lets
+   * editing tools render the forwarded prop as a dropdown of the target's
+   * variant values instead of a bare string input. Absent for non-variant
+   * terminals.
+   */
+  valueOptions?: readonly (string | number | boolean)[];
+  /**
+   * Composite-style registry key when the forward chain bottoms out at a
+   * `composite(...)` ref (e.g. `slot('root/textVariant')` → an `Anchor` layer's
+   * `textVariant: composite('textVariant')`). Mirrors a directly-authored
+   * `kind: 'composite'` prop's `compositeName`, so editing tools render the
+   * same composite control (and the `textVariant` typography special-case)
+   * for the forwarded prop. Absent for non-composite terminals.
+   */
+  compositeName?: string;
+}
+type PropInfo = (PropBase & {
+  kind: 'variant';
+} & VariantInfo) | (PropBase & {
+  kind: 'boolean';
+}) | (PropBase & {
+  kind: 'string';
+}) | (PropBase & {
+  kind: 'number';
+}) | (PropBase & {
+  kind: 'styleProp';
+} & StylePropInfo) | (PropBase & {
+  kind: 'composite';
+} & CompositeInfo) | (PropBase & {
+  kind: 'function';
+} & FunctionInfo) | (PropBase & {
+  kind: 'slot';
+} & SlotInfo);
+type ResolvedCompoundOverrides = Record<string, Record<string, unknown>>;
+declare class Layer {
+  readonly name: string;
+  readonly tag?: LayerInput;
+  readonly base?: BaseStyles;
+  constructor(args: {
+    name: string;
+    tag?: LayerInput;
+    base?: BaseStyles;
+  });
+  /**
+   * What this layer renders, normalized across the tag's representations:
+   *  - `{ kind: 'component', ref }` — renders a registered component (`Box`,
+   *    `Text`), so the layer takes that component's prop surface. The identity
+   *    survives both in memory (a non-enumerable `__componentName` stamp on the
+   *    builder) and on the wire (`{ __kind: 'component', ref }` from `fromJSON`).
+   *  - `{ kind: 'tag', ref }` — renders a bare HTML element (`'div'`).
+   *  - `undefined` — an inline anonymous builder with no registered identity.
+   */
+  get renders(): {
+    kind: 'component' | 'tag';
+    ref: string;
+  } | undefined;
+  toJSON(): {
+    name: string;
+    tag?: LayerInput;
+    base?: BaseStyles;
+  };
+}
+declare class Component {
+  #private;
+  readonly name: string;
+  readonly layers: ReadonlyMap<string, Layer>;
+  readonly props: Readonly<Record<string, PropBinding>>;
+  readonly base?: BaseStyles;
+  readonly defaultProps?: Record<string, unknown>;
+  readonly compoundProps?: readonly CompoundPropsEntry[];
+  readonly motion?: ComponentMotionValue;
+  readonly preview?: PreviewDefinition;
+  readonly metadata?: ComponentMetadata;
+  /**
+   * Absolute path of the file that called `defineComponent('Name', …)`.
+   * Captured via the stack walk in `captureCallerPath` and stashed
+   * non-enumerably on the authored definition; lifted onto the class
+   * here so codegen consumers don't have to thread a separate
+   * `componentSourceMap`. `undefined` when the component was hydrated
+   * from JSON (no original define call) or built outside the `define*`
+   * helpers.
+   */
+  readonly sourceFilePath?: string;
+  /**
+   * `true` when the authored definition chained `.render(fn)` — the
+   * non-enumerable `__hasRenderFn` flag set by the builder. Codegen
+   * needs this to classify single-layer components that ship a custom
+   * render fn (e.g. Accordion) into the transform path rather than
+   * the inline primitive emitter, so the two paths don't both emit a
+   * wrapper FC with the same name.
+   */
+  readonly hasRenderFn: boolean;
+  /**
+   * The actual `.render(fn)` callback when `hasRenderFn` is `true`.
+   * Lifted from the seed's non-enumerable `__renderFn` so the spec
+   * extractor can invoke it under the mock-react plugin to capture
+   * the component's internal structure as a Spec. Not used at
+   * production render time — the codegen-emitted per-file FC handles
+   * that path.
+   */
+  readonly renderFn?: unknown;
+  /**
+   * Name of the component this one value-extends from
+   * (`defineComponent(Box)` → `'Box'`). Resolved from the non-
+   * enumerable `__extendsFrom.__componentName` chain stamped by
+   * `defineComponent`'s value-extend branch and `Config.registerComponents`'
+   * registration loop. `undefined` for primitives, brace-ref shorthand
+   * forms, and JSON-hydrated configs (the wire format doesn't carry
+   * this relationship).
+   */
+  readonly extendsFrom?: string;
+  /**
+   * Globally-unique lookup key — the spec `type` string a renderer
+   * resolves against the registry. When the owning `Config` has a
+   * namespace set (`Config.configure({ namespace: 'uds' })`), this is
+   * `<namespace>:<name>` (`uds:Badge`); otherwise it's the bare `name`
+   * (un-namespaced configs). Read live via a getter so it reflects the
+   * namespace regardless of whether `configure` ran before or after the
+   * component was registered — mirrors the lazy `prefixGetter` pattern
+   * used for token CSS vars.
+   *
+   * `name` stays the bare authored/display/export identifier; codegen
+   * emits a bare-name alias alongside the canonical key so existing
+   * specs referencing the bare `name` keep resolving.
+   */
+  get registryKey(): string;
+  constructor(args: {
+    name: string;
+    definition: ComponentDefinition;
+    componentGroup?: string;
+    subcomponentOf?: string;
+    subcomponents?: readonly string[];
+    /** Live getter for the owning Config's namespace — keeps
+     *  `registryKey` correct regardless of chain-method ordering. */
+    namespaceGetter?: () => string | undefined;
+    /** Live getter for the owning Config's class-name prefix — feeds
+     *  `derived.classNames` so emitted CSS selectors + generated TSX
+     *  classNames share the config's namespace. Read lazily so it
+     *  reflects `configure({ prefix })` regardless of chain ordering. */
+    prefixGetter?: () => string;
+    /** Resolves a registered component by name against the owning Config.
+     *  Lets a slot's forward chain follow a layer that renders another
+     *  registered component (`{ __kind: 'component', ref }`) into that
+     *  component's prop surface — without it, the chain can't see the
+     *  inner props (e.g. after a `fromJSON` round-trip, where layer tags
+     *  are component refs) and falls back to a `string` value type. */
+    componentResolver?: (ref: string) => Component | undefined;
+    /** Resolves a `(styleProp, value)` shorthand to a qualified token name
+     *  (`bg`, `'tertiary'` → `'bg/tertiary'`) against the owning Config's
+     *  style-prop registry + token groups, or `undefined` when the value
+     *  isn't a token of one of that prop's groups (a keyword or arbitrary
+     *  literal). Lets `derived.tokenRefs` capture shorthand token usage
+     *  structurally — the component knows its style props, but the
+     *  prop→token-group link lives on the registry. */
+    resolveStylePropValueToken?: (styleProp: string, value: string) => string | undefined;
+    /** Whether a style key names a registered style prop — gates
+     *  `derived.stylePropKeywords` so layer keys and marker internals don't
+     *  read as style-prop keyword values. */
+    isStyleProp?: (name: string) => boolean;
+  });
+  get derived(): {
+    readonly layers: readonly Layer[];
+    readonly classNames: ComponentClassNames;
+    readonly compoundOverrides: ResolvedCompoundOverrides;
+    readonly componentGroup?: string;
+    readonly subcomponentOf?: string;
+    readonly subcomponents?: readonly string[];
+    readonly props: readonly PropInfo[];
+    readonly stylePropNames: readonly string[];
+    /** Qualified token names (`bg/tertiary`, `color/brand`) this component
+     *  references anywhere in its styling — base, variant styles, and
+     *  compound overrides, recursing modifier sub-objects and color
+     *  expressions. Both structured `token(...)` refs and shorthand
+     *  style-prop values (`bg: 'tertiary'`) are captured, resolved through
+     *  the registry, so the edge is structural — no CSS-var/string matching.
+     *  The reverse direction is `Config.getTokenDependents`. */
+    readonly tokenRefs: readonly string[];
+    /** `(styleProp, token)` pairs — which style prop a referenced token sits
+     *  under (`bg` → `color/brand`, including refs nested in a color
+     *  expression). The "actually used with a value from this group" edge that
+     *  `Config.getTokenGroupUsage` reads, distinct from the registry "allowed
+     *  in" relation (`getTokenGroupDependents`). */
+    readonly stylePropTokenUsages: readonly StylePropTokenUsage[];
+    /** The non-token keyword values this component uses (`display`/`flex`,
+     *  `flexDirection`/`col`) — disjoint from `tokenRefs`, excluding arbitrary
+     *  bracket literals. Tracks keyword removal-impact; the reverse direction
+     *  is `dependentsOf({ kind: 'styleProp', name, value })`. */
+    readonly stylePropKeywords: readonly StylePropKeyword[];
+    readonly kind: ComponentKind;
+    readonly acceptsChildren: boolean;
+    readonly acceptsChildNodes: boolean;
+    prop(propName: string): PropInfo | undefined;
+  };
+  toJSON(opts?: {
+    projectRoot?: string;
+  }): SerializedComponent & {
+    name: string;
+  };
+}
+/** Which style prop a referenced token sits under — `{ styleProp: 'bg',
+ *  token: 'color/brand' }`. See `Component.derived.stylePropTokenUsages`. */
+interface StylePropTokenUsage {
+  readonly styleProp: string;
+  readonly token: string;
+}
+/** A non-token keyword value a style prop carries — `{ styleProp: 'display',
+ *  value: 'flex' }`. See `Component.derived.stylePropKeywords`. */
+interface StylePropKeyword {
+  readonly styleProp: string;
+  readonly value: string;
+} //#endregion
+//#endregion
+export { Component, ComponentKind, CompositeInfo, FunctionInfo, Layer, PrimitivePropKind, PropBase, PropInfo, PropKind, ResolvedCompoundOverrides, SlotInfo, SlotValueKind, StylePropInfo, StylePropKeyword, StylePropTokenUsage, VariantInfo };