/** * A mapping *profile* is pure data describing how a dspack contract's components * correspond to A2UI catalog components. The transform engine (mapping.ts) is * source-agnostic and reads only this profile + the dspack document — never any * framework code. Retargeting a different design system = writing a new profile. * * The profile below targets the shadcn/ui dspack contract. Two kinds of components * are emitted: * - `components`: derived from dspack component entries. * - `synthesized`: A2UI structural/content primitives (Text, Column) that dspack * does NOT contain. dspack describes a component *library*, not a layout system * (its `layout` block is descriptive: breakpoints/grid/spacing, not renderable * components). A2UI surfaces need primitives to be composable/renderable, so we * synthesize them and record that as a fidelity finding. * * `casualtyComponents` are dspack components with no faithful A2UI representation; * they are documented and warned about, not emitted. */ import type { FidelityClass, Json } from "../types.js"; export interface Profile { catalogTitle: string; catalogDescription: string; /** Versioned catalogId/$id is built from this base + `//catalog.json`. */ catalogIdBase: string; /** v1.0 optional top-level `instructions`. */ instructions: string; /** Which dspack token (category.name) supplies theme.primaryColor. */ primaryColorToken: { category: string; name: string }; components: ComponentPlan[]; synthesized: ComponentPlan[]; casualtyComponents: CasualtyComponent[]; /** dspack component ids deliberately left out (not mapped, not a casualty). */ intentionallyOmitted?: string[]; /** * Which synthesized A2UI primitives the surface emitter uses when a dspack * surface needs structure the source vocabulary does not express: text * leaves become `textComponent` instances; multiple children in a * single-child slot are wrapped in `wrapComponent`. */ surfaceSynthesis: { textComponent: string; textProp: string; wrapComponent: string; wrapChildrenProp: string; }; } export interface ComponentPlan { a2ui: string; /** dspack component id this is derived from; omitted for pure synthesized primitives. */ dspackId?: string; /** Overrides dspack description; if omitted and dspackId set, dspack description is used. */ description?: string; /** Inlined `$defs` to compose via allOf (ComponentCommon is always included). */ commons: string[]; /** A2UI-native structural slots — synthesis, not dspack props. */ structural: Record; /** dspack prop name -> A2UI property mapping. */ propMap?: Record; /** A2UI required property names (the `component` const is added automatically). */ required: string[]; /** How the surface emitter projects a dspack-surface node onto this component. */ surfacePlan?: SurfacePlanDirectives; } /** * Data-only directives for projecting a dspack-surface (CSR) node onto an * emitted A2UI component instance. Compound composition that A2UI cannot * represent is flattened here, per the documented casualty mapping in * MAPPING.md — the emitter consumes the node's whole subtree when sub-content * directives (`subText`/`subButtonText`) are present. */ export interface SurfacePlanDirectives { /** Descendant sub-component id -> A2UI prop receiving that node's `text`. */ subText?: Record; /** * Descendant sub-component id -> A2UI prop receiving the `text` of the first * label-bearing component under that sub-component — a component whose own * surface plan projects text as a child label via `textChildProp` (e.g. * AlertDialogTrigger's button label -> triggerLabel). Incidental text on * other descendants is never picked up. The label-bearer's own props are a * documented casualty. */ subButtonText?: Record; /** Synthesize a declarative A2UI Action into this prop (event name is a deterministic slug). */ actionProp?: string; /** Node `text` becomes a synthesized text-primitive child referenced by this ComponentId prop. */ textChildProp?: string; /** Node `text` becomes this DynamicString prop directly. */ textProp?: string; /** Children emit as components; exactly one child id in this prop (>1 children are wrapped). */ childProp?: string; /** Children emit as components; their ids form a ChildList in this prop. */ childrenProp?: string; /** CSR props copied verbatim into same-named structural slots (e.g. Table columns/rows). */ structuralPassthrough?: string[]; } export interface StructuralSlot { schema: Json; description: string; synthNote: string; } export interface PropPlan { a2ui: string; kind: "enum" | "string" | "boolean" | "number"; /** Target (A2UI) enum vocabulary written into the catalog. */ targetEnum?: string[]; /** Source-value -> target-value projection. Many-to-one => lossy. */ valueMap?: Record; default?: string; description?: string; } export interface CasualtyComponent { dspackId: string; attempted: string; class: FidelityClass; reason: string; } const DynStr = { $ref: "#/$defs/DynamicString" }; const CompId = { $ref: "#/$defs/ComponentId" }; export const shadcnProfile: Profile = { catalogTitle: "shadcn/ui — A2UI catalog (compiled from dspack)", catalogDescription: "A2UI catalog compiled from the shadcn/ui dspack v0.2 contract. Component shapes, " + "variant enums, and the primary design token are projected onto the A2UI basic " + "component vocabulary. See MAPPING.md for per-field fidelity.", catalogIdBase: "https://rdombrowski.dev/catalogs/shadcn-ui", instructions: "For layout, use the Column component to organize other components.", primaryColorToken: { category: "color", name: "primary" }, surfaceSynthesis: { textComponent: "Text", textProp: "text", wrapComponent: "Column", wrapChildrenProp: "children", }, components: [ { a2ui: "Button", dspackId: "button", commons: ["ComponentCommon", "Checkable"], structural: { child: { schema: CompId, description: "The ID of the child component to render inside the button (e.g. a Text). " + "Referenced by ID; not defined inline.", synthNote: "A2UI Buttons render a child component by ID; dspack Button has no equivalent " + "slot (children are arbitrary React nodes).", }, action: { schema: { $ref: "#/$defs/Action" }, description: "The interaction dispatched when the button is activated.", synthNote: "A2UI requires a declarative action; dspack expresses this as an onClick handler prop, " + "which is not representable in a declarative catalog.", }, }, propMap: { variant: { a2ui: "variant", kind: "enum", targetEnum: ["default", "primary", "borderless"], valueMap: { default: "primary", destructive: "default", outline: "default", secondary: "default", ghost: "borderless", link: "borderless", }, default: "primary", description: "Button style hint, projected from shadcn variants onto the A2UI basic vocabulary.", }, }, required: ["child", "action"], surfacePlan: { textChildProp: "child", actionProp: "action" }, }, { a2ui: "Card", dspackId: "card", commons: ["ComponentCommon"], structural: { child: { schema: CompId, description: "The ID of the single child component. Wrap multiple elements in a Column and pass its ID.", synthNote: "A2UI Card takes exactly one child by ID; dspack Card composes via sub-components " + "(CardHeader/CardContent/CardFooter), which collapse to a single child slot.", }, }, required: ["child"], surfacePlan: { childProp: "child" }, }, { a2ui: "TextField", dspackId: "input", commons: ["ComponentCommon", "Checkable"], structural: { label: { schema: DynStr, description: "The text label for the input field.", synthNote: "A2UI TextField owns its label; dspack Input relies on an external