@tmorrow/cre8-wc 2.0.7 → 2.1.0

package/a2ui/generate-catalog.mjs

@@ -6,11 +6,56 @@ import { dirname, resolve } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const manifestPath = resolve(__dirname, '..', 'mcp-manifest.json');
 const outPath = resolve(__dirname, 'catalog.json');
+const compactOutPath = resolve(__dirname, 'catalog.compact.json');
 
 const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
 
 const QUOTED_LITERAL = /^"([^"]*)"$/;
 
+/**
+ * Native DOM events, bindable on every component.
+ *
+ * Emitted into the catalog as `x-native-events` so the runtime validator can
+ * read it from there rather than keeping its own copy. Two lists that must stay
+ * equal is exactly the drift this pipeline is supposed to prevent, so there is
+ * one list and it lives here, next to the schema it produces.
+ *
+ * A component's `@fires` tags describe only what it dispatches itself, so these
+ * can never be discovered from source — binding `click` to a button is both the
+ * most common thing an agent does and undocumentable by the analyzer.
+ */
+const NATIVE_DOM_EVENTS = [
+  'click', 'dblclick', 'contextmenu',
+  'mousedown', 'mouseup', 'mouseenter', 'mouseleave', 'mouseover', 'mouseout', 'mousemove',
+  'pointerdown', 'pointerup', 'pointerenter', 'pointerleave',
+  'touchstart', 'touchend', 'touchmove', 'touchcancel',
+  'keydown', 'keyup', 'keypress',
+  'focus', 'blur', 'focusin', 'focusout',
+  'input', 'change', 'submit', 'reset', 'invalid', 'select',
+  'scroll', 'wheel', 'resize',
+  'copy', 'cut', 'paste',
+  'drag', 'dragstart', 'dragend', 'dragenter', 'dragleave', 'dragover', 'drop',
+  'load', 'error',
+];
+
+/** Mirrors the `EventBinding` union in types.ts. */
+const EVENT_BINDING_SCHEMA = {
+  description: 'A handler name, or an object naming the handler plus dispatch options.',
+  oneOf: [
+    { type: 'string', minLength: 1 },
+    {
+      type: 'object',
+      required: ['handler'],
+      additionalProperties: false,
+      properties: {
+        handler: { type: 'string', minLength: 1 },
+        stopPropagation: { type: 'boolean' },
+        preventDefault: { type: 'boolean' },
+      },
+    },
+  ],
+};
+
 const SELECT_OPTION_SCHEMA = {
   type: 'object',
   required: ['label', 'value'],
@@ -31,6 +76,112 @@ const SELECT_OPTION_GROUP_SCHEMA = {
   },
 };
 
+
+/**
+ * Schemas for the flattened compound APIs.
+ *
+ * These are keyed by TypeScript type expression rather than by component, so a
+ * type used twice is described once — the same reason the select-option entry
+ * below is shaped this way. Without them the analyzer reports a bare interface
+ * name, `mapAttrPlain` falls back to `type: "string"`, and the catalog then
+ * *rejects* the very array the component is built to take.
+ */
+const TABLE_COLUMN_SCHEMA = {
+  type: 'object',
+  properties: {
+    label: { type: 'string' },
+    key: { type: 'string' },
+    width: { type: 'string' },
+  },
+  required: ['label'],
+  additionalProperties: false,
+};
+
+const TABLE_ROW_SCHEMA = {
+  oneOf: [
+    { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+    { type: 'array', items: { type: ['string', 'number'] } },
+  ],
+};
+
+/** `{ text }` and friends: one string field plus optional flags. */
+const textItem = (extra = {}, required = ['text'], key = 'text') => ({
+  type: 'object',
+  properties: { [key]: { type: 'string' }, ...extra },
+  required,
+  additionalProperties: false,
+});
+
+const FLATTENED_ITEM_SCHEMAS = {
+  'Cre8TableColumn[]': { type: 'array', items: TABLE_COLUMN_SCHEMA },
+  'Cre8TableRowData[]': { type: 'array', items: TABLE_ROW_SCHEMA },
+  'Cre8ListItemData[]': { type: 'array', items: textItem() },
+  'Cre8DropdownItemData[]': { type: 'array', items: textItem({ ariaLabel: { type: 'string' } }) },
+  'Cre8BreadcrumbData[]': { type: 'array', items: textItem({ href: { type: 'string' } }) },
+  'Cre8LinkData[]': {
+    type: 'array',
+    items: textItem({ href: { type: 'string' }, isActive: { type: 'boolean' } }, ['text', 'href']),
+  },
+  'Cre8TagData[]': {
+    type: 'array',
+    items: textItem({
+      variant: { type: 'string', enum: ['neutral', 'branded', 'neutral-hybrid'] },
+      shape: { type: 'string', enum: ['square', 'round'] },
+      type: { type: 'string', enum: ['checkbox', 'radio'] },
+      disabled: { type: 'boolean' },
+    }),
+  },
+  'Cre8TabItemData[]': {
+    type: 'array',
+    items: textItem({ content: { type: 'string' } }, ['label'], 'label'),
+  },
+  'Cre8AccordionItemData[]': {
+    type: 'array',
+    items: {
+      type: 'object',
+      properties: {
+        heading: { type: 'string' },
+        content: { type: 'string' },
+        isActive: { type: 'boolean' },
+        headingTagVariant: { type: 'string', enum: ['h1', 'h2', 'h3', 'h4'] },
+      },
+      required: ['heading', 'content'],
+      additionalProperties: false,
+    },
+  },
+  'Cre8ProgressStepData[]': {
+    type: 'array',
+    items: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        message: { type: 'string' },
+        state: { type: 'string', enum: ['error', 'warning', 'complete', 'current'] },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+};
+
+const choiceItem = {
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      label: { type: 'string' },
+      value: { type: 'string' },
+      checked: { type: 'boolean' },
+      disabled: { type: 'boolean' },
+      required: { type: 'boolean' },
+    },
+    required: ['label'],
+    additionalProperties: false,
+  },
+};
+FLATTENED_ITEM_SCHEMAS['Cre8CheckboxItemData[]'] = choiceItem;
+FLATTENED_ITEM_SCHEMAS['Cre8RadioItemData[]'] = choiceItem;
+
 const TS_TYPE_RESOLVERS = {
   Cre8ChartType: {
     type: 'string',
@@ -38,17 +189,24 @@ const TS_TYPE_RESOLVERS = {
   },
   Color: { type: 'string', enum: ['neutral', 'branded', 'neutral-hybrid'] },
   Shape: { type: 'string', enum: ['round', 'square'] },
-  status: { type: 'string', enum: ['error', 'warning', 'success'] },
+  // No entry for the bare type name `status`: it existed only because
+  // `cre8-progress-meter` carried an `@attr {status}` JSDoc tag that overrode
+  // its literal union back to an unresolvable alias. The tag is gone and the
+  // union now flows through on its own.
   '(Cre8SelectOption | Cre8SelectOptionGroup)[]': {
     type: 'array',
     items: { oneOf: [SELECT_OPTION_SCHEMA, SELECT_OPTION_GROUP_SCHEMA] },
   },
+  ...FLATTENED_ITEM_SCHEMAS,
 };
 
 const PROP_OVERRIDES = {
   'cre8-chart.data': { type: 'object', description: 'Chart.js data object with labels and datasets arrays.' },
   'cre8-chart.options': { type: 'object', description: 'Chart.js options object.' },
-  'cre8-chart.colors': { type: 'array', items: { type: 'string' }, description: 'Dataset colors.' },
+  // No entry for `cre8-chart.colors`: the manifest type is plain `string[]`,
+  // which mapAttrPlain already resolves to the identical schema. Only add an
+  // override when the manifest type is unresolvable (an interface name, an
+  // imported alias, or a union TypeScript truncated with "... N more ...").
   'cre8-heading.type': {
     type: 'string',
     enum: [
@@ -62,7 +220,7 @@ const PROP_OVERRIDES = {
       'title-default',
       'title-small',
       'label-large',
-      'label',
+      'label-default',
       'label-small',
       'meta-large',
       'meta-default',
@@ -178,7 +336,7 @@ function buildComponent(c) {
     def.properties.children = {
       type: 'array',
       description: (rawSlots.default?.description || '').trim() || 'Child instances rendered into the default slot.',
-      items: { $ref: '#/$defs/Component' },
+      items: { $ref: '#/$defs/Child' },
     };
   } else if (hasSlots) {
     const slotProps = {};
@@ -188,7 +346,7 @@ function buildComponent(c) {
       slotProps[name] = {
         type: 'array',
         description: (slot.description || '').trim(),
-        items: { $ref: '#/$defs/Component' },
+        items: { $ref: '#/$defs/Child' },
       };
       slotDescriptions[name] = (slot.description || '').trim();
     }
@@ -203,6 +361,24 @@ function buildComponent(c) {
 
   if (Object.keys(events).length) def['x-events'] = events;
 
+  // Events are declared under `properties`, alongside props and slots, rather
+  // than living only in `x-events` metadata. Previously the component defs were
+  // `additionalProperties: false` with no `events` key at all, so events were
+  // documented but second-class — and an invented event name validated cleanly.
+  // Native events are always permitted; declared custom events are added on top.
+  def.properties.events = {
+    type: 'object',
+    description:
+      'Event bindings. Each key is an event name; the value names the handler to emit.',
+    // Native names are `$ref`'d rather than inlined. Repeating all 46 on each of
+    // 85 components cost ~57 KB and made the catalog a third larger for no
+    // information gain.
+    propertyNames: Object.keys(events).length
+      ? { anyOf: [{ $ref: '#/$defs/NativeEventName' }, { enum: Object.keys(events).sort() }] }
+      : { $ref: '#/$defs/NativeEventName' },
+    additionalProperties: { $ref: '#/$defs/EventBinding' },
+  };
+
   return def;
 }
 
@@ -219,6 +395,9 @@ const catalog = {
   $id: `https://cre8.dev/a2ui/catalogs/cre8-wc/${manifest.version}`,
   title: 'cre8-wc A2UI Catalog',
   description: manifest.description,
+  // Single source of truth for the native-event allowlist. The runtime validator
+  // reads it from here instead of keeping a second copy that could drift.
+  'x-native-events': NATIVE_DOM_EVENTS,
   'x-a2ui': {
     catalogId: 'cre8-wc',
     library: manifest.library,
@@ -236,6 +415,24 @@ const catalog = {
       description: 'A component instance in the cre8-wc catalog.',
       oneOf: componentRefs,
     },
+    // Slot content is a component *or* literal text. `renderer.ts` has always
+    // turned a bare string into a text node, but the schema never said so, and
+    // that gap is load-bearing rather than cosmetic: 56 of 85 components carry
+    // no text-bearing prop, so their entire visible content arrives this way. A
+    // schema-constrained generator — guided decoding, or any JSON-Schema-
+    // constrained model — could not give those components any content at all.
+    //
+    // `root` stays a Component deliberately: a document cannot be bare text.
+    Child: {
+      description:
+        'Slot content: either a nested component instance or literal text, which renders as a text node.',
+      oneOf: [{ $ref: '#/$defs/Component' }, { type: 'string' }],
+    },
+    EventBinding: EVENT_BINDING_SCHEMA,
+    NativeEventName: {
+      description: 'A native DOM event, bindable on any component.',
+      enum: [...NATIVE_DOM_EVENTS].sort(),
+    },
     components,
   },
 };
@@ -244,3 +441,57 @@ writeFileSync(outPath, JSON.stringify(catalog, null, 2) + '\n');
 console.log(
   `Wrote ${outPath} (${manifest.components.length} components, ${(JSON.stringify(catalog).length / 1024).toFixed(1)} KB)`
 );
+
+// The compact projection: the minimum a model needs to emit valid A2UI. Prose is
+// ~90% of the catalog's bytes and none of its decoding constraint, so dropping it
+// is what lets a small-context model see the design system at all.
+//
+// Emitted here rather than in a separate script so it cannot drift from the
+// catalog it projects.
+function compactProps(propsNode) {
+  const out = {};
+  for (const [name, spec] of Object.entries(propsNode?.properties ?? {})) {
+    out[name] = spec.enum ? { enum: spec.enum } : { type: spec.type ?? 'string' };
+  }
+  return out;
+}
+
+const compactComponents = Object.entries(components)
+  .map(([name, def]) => {
+    const props = def.properties ?? {};
+    const entry = { name, category: def['x-category'] ?? 'Uncategorized' };
+
+    if (props.props) {
+      entry.props = compactProps(props.props);
+      if (props.props.required?.length) entry.required = props.props.required;
+    }
+    // Containment is expressed two ways and consumers need both: `children` for
+    // plain containers, `slots` for named regions. Dropping either makes a
+    // container look like a leaf.
+    if (props.children) entry.acceptsChildren = true;
+    if (props.slots) entry.slots = Object.keys(props.slots.properties ?? {});
+    // Events live under `x-events`, not under `properties`, which makes them easy
+    // to miss — the studio's hand-rolled summary looked for them in the wrong
+    // place and so showed the model none of the 22 events the library emits.
+    const events = Object.keys(def['x-events'] ?? {});
+    if (events.length) entry.events = events;
+    return entry;
+  })
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+const compact = {
+  contractVersion: 1,
+  sourceCatalog: catalog.$id,
+  libraryVersion: manifest.version,
+  componentCount: compactComponents.length,
+  components: compactComponents,
+};
+
+writeFileSync(compactOutPath, JSON.stringify(compact, null, 2) + '\n');
+
+const fullBytes = JSON.stringify(components).length;
+const compactBytes = JSON.stringify(compact).length;
+console.log(
+  `Wrote ${compactOutPath} (${compactComponents.length} components, ` +
+    `${(compactBytes / 1024).toFixed(1)} KB, ${(fullBytes / compactBytes).toFixed(1)}x smaller)`
+);

package/a2ui/inert-props.json

@@ -0,0 +1,32 @@
+{
+  "$comment": "Generated by a2ui/render-audit.mjs. Props that are declared in the catalog but never reach the DOM — confirmed twice, by rendering under jsdom and by reading the component source. Setting one validates cleanly and does nothing.",
+  "libraryVersion": "2.0.7",
+  "components": {
+    "cre8-link-list-item": {
+      "text": {
+        "reason": "Documented as \"The link text\"; render() never reads it. The label comes from the default slot."
+      }
+    },
+    "cre8-field": {
+      "errorText": {
+        "reason": "Declared with a default of \"Error\" and never read. The message that renders is `fieldNote`, shown in the error style by `isError`."
+      },
+      "successText": {
+        "reason": "Declared with a default of \"Success\" and never read. Use `fieldNote` with `isSuccess`."
+      }
+    },
+    "cre8-date-picker": {
+      "errorText": {
+        "reason": "Declared and never read. Use `fieldNote` with `isError`."
+      },
+      "successText": {
+        "reason": "Declared and never read. Use `fieldNote` with `isSuccess`."
+      }
+    },
+    "cre8-modal": {
+      "closeButtonText": {
+        "reason": "Declared and never read; the close control takes its label from elsewhere."
+      }
+    }
+  }
+}

package/a2ui/registry.js

@@ -87,6 +87,17 @@ function describeType(v) {
         return 'array';
     return typeof v;
 }
+/**
+ * Native DOM events, bindable on any component.
+ *
+ * Read from the catalog's `x-native-events` rather than kept here, so there is
+ * one list rather than two that must be held equal. A component's `@fires` tags
+ * describe only what it dispatches itself, so these can never be derived from
+ * source — `click` on a button is legitimate and undocumentable.
+ */
+function nativeEvents(catalog) {
+    return new Set(catalog.schema['x-native-events'] ?? []);
+}
 export function validateSpec(spec, catalog, path = '$') {
     if (!spec || typeof spec !== 'object') {
         throw new Error(`${path}: spec must be an object`);
@@ -131,7 +142,24 @@ export function validateSpec(spec, catalog, path = '$') {
         if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
             throw new Error(`${path}.events: must be an object`);
         }
+        // Custom event *names* are checked against the catalog, the same way props
+        // and slots are. Previously only the binding shape was validated, so an
+        // invented event bound cleanly and then silently never fired — the worst
+        // failure mode available, since the UI renders and simply does nothing.
+        //
+        // Native DOM events are always allowed: `addEventListener` handles them on
+        // any element, and `@fires` documents only what a component dispatches
+        // itself. `click` on a button is legitimate and undocumented by design.
+        const declaredEvents = new Set(Object.keys(def['x-events'] ?? {}));
+        const native = nativeEvents(catalog);
         for (const [evtName, binding] of Object.entries(s.events)) {
+            if (!native.has(evtName) && !declaredEvents.has(evtName)) {
+                const available = [...declaredEvents].sort().join(', ');
+                throw new Error(`${path}.events.${evtName}: not a declared event on ${s.component}. ` +
+                    (available
+                        ? `Custom events available: ${available}`
+                        : `${s.component} declares no custom events`));
+            }
             if (typeof binding === 'string')
                 continue;
             if (!binding || typeof binding !== 'object') {

package/a2ui/registry.ts

@@ -100,6 +100,18 @@ function describeType(v: unknown): string {
   return typeof v;
 }
 
+/**
+ * Native DOM events, bindable on any component.
+ *
+ * Read from the catalog's `x-native-events` rather than kept here, so there is
+ * one list rather than two that must be held equal. A component's `@fires` tags
+ * describe only what it dispatches itself, so these can never be derived from
+ * source — `click` on a button is legitimate and undocumentable.
+ */
+function nativeEvents(catalog: RegisteredCatalog): Set<string> {
+  return new Set(catalog.schema['x-native-events'] ?? []);
+}
+
 export function validateSpec(spec: unknown, catalog: RegisteredCatalog, path = '$'): asserts spec is ComponentSpec {
   if (!spec || typeof spec !== 'object') {
     throw new Error(`${path}: spec must be an object`);
@@ -147,7 +159,26 @@ export function validateSpec(spec: unknown, catalog: RegisteredCatalog, path = '
     if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
       throw new Error(`${path}.events: must be an object`);
     }
+    // Custom event *names* are checked against the catalog, the same way props
+    // and slots are. Previously only the binding shape was validated, so an
+    // invented event bound cleanly and then silently never fired — the worst
+    // failure mode available, since the UI renders and simply does nothing.
+    //
+    // Native DOM events are always allowed: `addEventListener` handles them on
+    // any element, and `@fires` documents only what a component dispatches
+    // itself. `click` on a button is legitimate and undocumented by design.
+    const declaredEvents = new Set(Object.keys(def['x-events'] ?? {}));
+    const native = nativeEvents(catalog);
     for (const [evtName, binding] of Object.entries(s.events as Record<string, unknown>)) {
+      if (!native.has(evtName) && !declaredEvents.has(evtName)) {
+        const available = [...declaredEvents].sort().join(', ');
+        throw new Error(
+          `${path}.events.${evtName}: not a declared event on ${s.component}. ` +
+            (available
+              ? `Custom events available: ${available}`
+              : `${s.component} declares no custom events`)
+        );
+      }
       if (typeof binding === 'string') continue;
       if (!binding || typeof binding !== 'object') {
         throw new Error(`${path}.events.${evtName}: must be a string or { handler } object`);