@yahoo/uds-create-config 2.45.0 → 3.0.0

package/README.md

@@ -0,0 +1,129 @@
+# @yahoo/uds-create-config
+
+The UDS config layer. A `uds.config.ts` authors one **`Config`** — the single surface both the
+author (`new System().register({ … })`) and every consumer (codegen, Studio, the pipeline)
+read. There are no per-entity `derived` getters and no `CodegenConfig` subclass: group
+enumeration, the dependency graph, the folder/file tree, validation, and the flat wire format
+are all first-class on `Config`, and derived projections are free functions that work on any
+config.
+
+## What this fixes from v1
+
+"v1" is the config layer this replaced — a bespoke class per entity, projections hanging off
+`.derived` getters, parallel `*Group` entities. The differences:
+
+- **Projections are free functions, not per-entity `.derived` getters.** In v1 every
+  entity (`Token`, `Component`, `Mode`, `StyleProp`, …) exposed a `.derived` sub-object of
+  engine-computed projections that reached cross-entity state through an injected sibling
+  lookup / parent-`Config` back-ref and recomputed on each access. All of that is now free
+  functions over a plain `Config` (`cssVar`, `className`, `resolveTokenValue`) — no `.derived`
+  on entities, no injected back-refs, and they work on any config.
+- **A group is a path prefix, not a Group class.** v1 had explicit `TokenGroup`,
+  `ComponentGroup`, `AssetGroup` classes (each with its own `.derived`). Now a kind stores
+  one flat, path-keyed record and a group is simply a prefix of it — membership is emergent,
+  so there are no parallel Group entities to keep in sync. A group node carries only the
+  folder's own metadata, and a prefix with no metadata needs no node at all.
+- **A kind is one zod schema, not a hand-written class.** v1 had a bespoke class per
+  entity plus `define*` factories and caller-path capture. `defineEntity({ kind, fields })`
+  derives the typed constructors, the kind-bound `ref`, the create/update schemas, and the
+  operation set from a single field schema. A config TYPE names the kinds it owns, so what a
+  config can hold depends on what was registered into it rather than on import order. The
+  base `Entity` owns hydration and serialization, so a new kind adds no constructor or
+  `toJSON`.
+- **Identity *is* the qualified path.** `color/brand` is the identity; no caller-path
+  capture or separately-tracked namespace. A bare value at an item key is shorthand for the
+  kind's primary field, so `Token.item('#1167f4')` skips the object wrapper.
+- **`Config` is the single home for derived structure.** Emergent grouping, the dependency
+  graph, the folder/file tree, validation, and the flat wire format are first-class methods
+  on `Config` rather than spread across entity getters and helper modules.
+- **Downstream projections read the live config.** The pipeline owns no operation
+  definitions and no build-time snapshots — CRUD, MCP tools, and the AI prompt are derived
+  at runtime from the current `Config`, so a mutation is reflected immediately (see
+  `apps/studio/src/ai/config-v2`).
+
+## Authoring
+
+```ts
+import { System, Token } from '@yahoo/uds-create-config';
+
+export default new System()
+  .register({
+    settings: { css: { prefix: 'uds' } }, //         one body, no path: settings is a singleton kind
+    tokens: {
+      color: Token.group({
+        label: 'Color',
+        items: {
+          brand: Token.item('#1167f4'), //                 bare value = the primary field
+          primary: Token.item(Token.ref('color/brand')), // a ref, chased at projection time
+        },
+      }),
+    },
+  });
+```
+
+**A deep path is authored as a group, with `item` leaves.** The stored form is flat and
+path-keyed — identity IS the qualified path (`color/brand`) — but the authored form nests,
+because that is what says which prefixes are folders and lets one carry a label or a
+`cssPrefix`. A flat `'color/brand'` key registers the same item and leaves the folder
+emergent, which is a different artifact. Two shapes keep the flat key, since a group cannot
+express either: an owner path (`Card/Header`, a PART of the `Card` item) and a name that
+contains a slash (`w/1/2`, the fraction). The full rule, with the failure modes, is
+`.claude/rules/config-authoring.md`.
+
+## Defining an entity
+
+`defineEntity({ kind, fields, groupFields })` is the whole authoring toolkit for one kind,
+derived from its `z.object` field schema. Declare the fields; get the typed `item`/`group`
+constructors, the kind-bound `ref`, and a typed `get`. Registration lives on
+`Config.register`, so the config file reads as a fluent chain.
+
+```ts
+export const Token = defineEntity({
+  kind: 'token',
+  fields: z.object({ value: z.string() /* … */ }),
+});
+export const { ref: token } = Token;
+```
+
+The kind's metadata — field names, create/update schemas, operation set — is built once and
+hangs off the returned class as `kindDef`. A config TYPE names the kind in its `entities`
+map, and `register` copies that metadata into the config instance it is loading, which is
+what `Config` hydrates and validates against. `Token.extend({ … })` makes a VARIANT that
+takes the base's slot, so a config authors through whichever variant it registers.
+
+## Entities
+
+Concrete kinds live in `src/entities/system/`: `Token`, `StyleProperty`, `Component`,
+`Composite`, `Mode`, `Modifier`, `Motion`, `Font`, `Icon`, `Package`, `Guidance`, `CanvasRole`,
+`GlobalStyle`, `Device`, `LinkedSystem`, plus the derived `Operation` and `Tool`.
+`src/entities/native/` holds the native variants a `ReactNativeSystem` registers in their place
+(`NativeToken`, `NativeMode`, `NativeModifier`, `NativeStyleProperty`).
+
+Components are authored with the exported `defineComponent`
+(`src/entities/system/defineComponent.ts`) — see `packages/minimal-template/components/`.
+`src/authoring/define-component.ts` is an unexported **prototype** of a different chaining
+shape for the same job; nothing consumes it.
+
+## Projections
+
+CSS var names, class names, and chased token literals are exported as **free functions**
+over a plain `Config` (`cssVar`, `cssVarRef`, `className`, `resolveTokenValue`) — not methods
+on a subclass. So codegen and Studio get projections that work on any config without wrapping,
+and the base `Config` stays clean. A projection shared by more than one surface is memoized on
+the snapshot SLICES it reads (`createSliceMemo`), never on the config — a `Config` is immutable,
+so keying on one misses on every edit.
+
+## What this package owns vs. what reads it
+
+This package owns the config model and its projections. It does **not** own operations
+downstream: `@yahoo/uds-create-codegen` emits CSS from a `Config`, and
+`apps/studio/src/ai/config-v2` derives the CRUD facade, MCP tools, and AI prompt from it.
+Both just read a `Config`.
+
+## Develop
+
+```sh
+cd packages/config
+bun test          # bun:test
+bun run typecheck  # tsc --noEmit
+```

package/dist/ai-lanes.d.ts

@@ -0,0 +1,23 @@
+//#region src/ai-lanes.d.ts
+/**
+ * The AI lanes — the coarse, user-facing generation workflows a system's AI runs in. One shared
+ * vocabulary so the three surfaces that name a lane agree and can be joined: a guidance topic's
+ * `appliesTo` (which lane its rules are fed to), an `AiFlow`'s `lane` (which lane produced a canvas
+ * node), and a cost-ledger row's `lane` (which lane a model call served).
+ *
+ * A lane is not an `AiFlow` `origin` (the gesture that started it — `paste`, `duplicate`, `sidebar`
+ * carry an origin but run no prompt, so they are not lanes), nor a `multiAgentMode` (how the agents
+ * were arranged), nor a `feature` (the per-route telemetry tag). One entry per workflow, not per route.
+ */
+declare const AI_LANES: readonly ["chat", "comment", "huddle", "paint-style", "figma-import", "workspace", "mcp"];
+type AiLane = (typeof AI_LANES)[number];
+/**
+ * The subset of lanes a guidance topic can be scoped to — the lanes that actually derive a
+ * guidance-filtered prompt today. Drawn from {@link AI_LANES} (every member is an {@link AiLane}) so
+ * guidance and the flow/ledger read one vocabulary; a lane joins this set when it starts deriving
+ * guidance, and each entry is described in Studio's `WORKFLOWS` map.
+ */
+declare const GUIDANCE_LANES: readonly ["chat", "huddle", "paint-style", "figma-import"];
+type GuidanceLane = (typeof GUIDANCE_LANES)[number];
+//#endregion
+export { AI_LANES, AiLane, GUIDANCE_LANES, GuidanceLane };

package/dist/ai-lanes.js

@@ -0,0 +1,34 @@
+//#region src/ai-lanes.ts
+/**
+* The AI lanes — the coarse, user-facing generation workflows a system's AI runs in. One shared
+* vocabulary so the three surfaces that name a lane agree and can be joined: a guidance topic's
+* `appliesTo` (which lane its rules are fed to), an `AiFlow`'s `lane` (which lane produced a canvas
+* node), and a cost-ledger row's `lane` (which lane a model call served).
+*
+* A lane is not an `AiFlow` `origin` (the gesture that started it — `paste`, `duplicate`, `sidebar`
+* carry an origin but run no prompt, so they are not lanes), nor a `multiAgentMode` (how the agents
+* were arranged), nor a `feature` (the per-route telemetry tag). One entry per workflow, not per route.
+*/
+const AI_LANES = [
+	"chat",
+	"comment",
+	"huddle",
+	"paint-style",
+	"figma-import",
+	"workspace",
+	"mcp"
+];
+/**
+* The subset of lanes a guidance topic can be scoped to — the lanes that actually derive a
+* guidance-filtered prompt today. Drawn from {@link AI_LANES} (every member is an {@link AiLane}) so
+* guidance and the flow/ledger read one vocabulary; a lane joins this set when it starts deriving
+* guidance, and each entry is described in Studio's `WORKFLOWS` map.
+*/
+const GUIDANCE_LANES = [
+	"chat",
+	"huddle",
+	"paint-style",
+	"figma-import"
+];
+//#endregion
+export { AI_LANES, GUIDANCE_LANES };

package/dist/authoring/define-component.d.ts

@@ -0,0 +1,85 @@
+/**
+ * PROTOTYPE — typed component authoring in the original `defineComponent` shape, wired to
+ * the bridge so its output feeds a live `Config` (see `framework/authoring.ts`):
+ *
+ *   const Button = defineComponent
+ *     .layers({ root: 'button', text: Text })          // name → element (tag OR component)
+ *     .config(({ slot, variant, styleProperty }) => ({
+ *       props: { children: slot(), fill: styleProperty('color/bg'), size: variant({...}) },
+ *       base:  { root: { bg: 'brand', _hover: { bg: 'primary' } } },   // style props + modifiers
+ *     }));
+ *
+ * `.layers` names elements only; per-layer styling is `config`'s `base` (once). Props are
+ * markers; `styleProperty(name)` = `StyleProperty.ref`. No path arg — identity is assigned at
+ * `Config.author`. A layer's bag is narrowed to the keys its element allows (an inner
+ * component's exposed props, or the derived style-prop union), and modifier keys
+ * (`_hover`, `_disabled`, …) to a derived modifier union — all via `keyof`, no codegen.
+ * The returned handle is a ref AND an `Authored`, so it composes into other components and
+ * registers through the generic bridge.
+ */
+import type { Authored } from '../framework/authoring';
+import { type Ref } from '../framework/utils/refs';
+/** A component handle — a ref (import/reference it), an `Authored` (register it), and a
+ *  carrier of `Exposed` (its prop names) so another component styling it gets them. */
+export interface ComponentHandle<Exposed extends string = string> extends Ref, Authored {
+    readonly exposes?: Exposed;
+}
+type Element = string | ComponentHandle;
+/** A style bag: style-prop keys (value = a token/keyword/ref) plus modifier keys (value =
+ *  a nested style-prop bag). Both key groups are DERIVED unions — a bad key won't compile. */
+type StyleBag<SP extends string, MOD extends string> = {
+    [K in SP | MOD]?: K extends MOD ? Partial<Record<SP, unknown>> : unknown;
+};
+/** The bag a layer allows: an inner component's exposed props (element is a handle) or a
+ *  full style bag (element is a tag). */
+type LayerBag<El, SP extends string, MOD extends string> = El extends ComponentHandle<infer E> ? Partial<Record<E, unknown>> : StyleBag<SP, MOD>;
+type LayerOverrides<L, SP extends string, MOD extends string> = {
+    [K in keyof L]?: LayerBag<L[K], SP, MOD>;
+};
+/** `target` is `<layer>/<prop>` — where the content lands. Absent for a hole the render places. */
+export type SlotProp = {
+    readonly kind: 'slot';
+    readonly target?: string;
+};
+export type VariantProp = {
+    readonly kind: 'variant';
+    readonly values: Record<string, unknown>;
+};
+export type ControlProp = {
+    readonly kind: 'control';
+    readonly control: 'boolean' | 'string' | 'number';
+};
+export type PropMarker = SlotProp | VariantProp | ControlProp | Ref;
+interface Helpers<L, SP extends string, MOD extends string> {
+    slot(target?: string): SlotProp;
+    /** Per-variant-value, per-layer overrides — F-bounded so a non-layer key won't compile. */
+    variant<V extends {
+        [Value in keyof V]: LayerOverrides<L, SP, MOD>;
+    }>(values: V): VariantProp;
+    boolean(): ControlProp;
+    string(): ControlProp;
+    number(): ControlProp;
+    /** Bind a registered style prop by name (i.e. `StyleProperty.ref`), exposing the prop. */
+    styleProperty(name: string): Ref;
+}
+interface Body<L, SP extends string, MOD extends string, P extends Record<string, PropMarker>> {
+    props?: P;
+    base?: LayerOverrides<L, SP, MOD>;
+    compoundProps?: Array<{
+        when: Record<string, string>;
+        layers: LayerOverrides<L, SP, MOD>;
+    }>;
+    defaultProps?: Record<string, unknown>;
+    label?: string;
+    description?: string;
+}
+/**
+ * Bind the style-prop and modifier unions (both derived via `keyof` the config's
+ * registrations), then author components in the fluent `.layers(...).config(...)` shape.
+ */
+export declare function componentAuthoring<SP extends string, MOD extends string = never>(): {
+    layers<L extends Record<string, Element>>(layers: L): {
+        config<P extends Record<string, PropMarker>>(build: (h: Helpers<L, SP, MOD>) => Body<L, SP, MOD, P>): ComponentHandle<Extract<keyof P, string>>;
+    };
+};
+export {};