@tmorrow/cre8-wc 2.0.7 → 2.1.0

package/a2ui/check-layer-parity.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * Asserts that every layer describing the component library agrees.
+ *
+ *   node a2ui/check-layer-parity.mjs
+ *
+ * The library is described six times over — the source that registers the
+ * elements, the MCP manifest, the A2UI catalog, the compact projection, the
+ * React manifest, and custom-elements.json — each generated by a different
+ * script from a different glob. Nothing forced them to agree, and they didn't:
+ * an analyzer glob one level too shallow dropped five components from all five
+ * derived layers at once, silently, for months.
+ *
+ * This is the check that makes that unmergeable. It compares the layers against
+ * each other rather than against a hardcoded expectation, so it keeps working as
+ * components are added.
+ *
+ * Deliberate omissions are legal but must be declared: `internalElements` in the
+ * manifest is the single place they live, and every one is re-verified here.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WC = join(HERE, '..');
+const REPO = join(WC, '..', '..');
+
+const read = (p) => JSON.parse(readFileSync(p, 'utf8'));
+
+const failures = [];
+const notes = [];
+function check(name, fn) {
+  try {
+    const note = fn();
+    if (note) notes.push(`  ok  ${name} — ${note}`);
+    else notes.push(`  ok  ${name}`);
+  } catch (err) {
+    failures.push(`FAIL  ${name}\n      ${err.message}`);
+  }
+}
+
+function assertSameSet(label, a, b, aName, bName) {
+  const missingFromB = [...a].filter((x) => !b.has(x)).sort();
+  const missingFromA = [...b].filter((x) => !a.has(x)).sort();
+  if (missingFromB.length || missingFromA.length) {
+    const parts = [];
+    if (missingFromB.length) parts.push(`in ${aName} but not ${bName}: ${missingFromB.join(', ')}`);
+    if (missingFromA.length) parts.push(`in ${bName} but not ${aName}: ${missingFromA.join(', ')}`);
+    throw new Error(`${label}\n      ${parts.join('\n      ')}`);
+  }
+}
+
+// ── Load every layer ─────────────────────────────────────────────────
+
+const manifest = read(join(WC, 'mcp-manifest.json'));
+const catalog = read(join(WC, 'a2ui', 'catalog.json'));
+const compact = read(join(WC, 'a2ui', 'catalog.compact.json'));
+
+const registered = new Set(
+  execSync(`grep -rho "customElements.define('[^']*'" "${join(WC, 'components')}" --include='*.ts' || true`)
+    .toString()
+    .split('\n')
+    .map((line) => (line.match(/'([^']+)'/) || [])[1])
+    .filter(Boolean)
+);
+
+const internal = new Set(manifest.internalElements ?? []);
+const publicSource = new Set([...registered].filter((n) => !internal.has(n)));
+
+const manifestNames = new Set(manifest.components.map((c) => c.name));
+const catalogNames = new Set(Object.keys(catalog.$defs.components));
+const compactNames = new Set(compact.components.map((c) => c.name));
+
+// ── Component-set parity ─────────────────────────────────────────────
+
+check('every registered element is accounted for', () => {
+  if (!registered.size) throw new Error('found no customElements.define calls — the grep is broken');
+  const unaccounted = [...registered].filter((n) => !manifestNames.has(n) && !internal.has(n));
+  if (unaccounted.length) {
+    throw new Error(
+      `element(s) register but appear in no layer and are not declared internal:\n` +
+        `      ${unaccounted.join(', ')}\n` +
+        `      Either export them, or add them to INTERNAL_ELEMENTS in scripts/generate-mcp-manifest.ts.`
+    );
+  }
+  return `${registered.size} registered, ${internal.size} declared internal`;
+});
+
+check('declared internals actually exist', () => {
+  const ghosts = [...internal].filter((n) => !registered.has(n));
+  if (ghosts.length) {
+    throw new Error(`declared internal but no longer registered: ${ghosts.join(', ')} — stale entry`);
+  }
+  const leaked = [...internal].filter((n) => manifestNames.has(n));
+  if (leaked.length) throw new Error(`declared internal but present in the manifest: ${leaked.join(', ')}`);
+  return internal.size ? [...internal].join(', ') : 'none';
+});
+
+check('source (minus internals) == manifest', () =>
+  assertSameSet('component sets differ', publicSource, manifestNames, 'source', 'manifest'));
+
+check('manifest == catalog', () =>
+  assertSameSet('component sets differ', manifestNames, catalogNames, 'manifest', 'catalog'));
+
+check('catalog == compact', () =>
+  assertSameSet('component sets differ', catalogNames, compactNames, 'catalog', 'compact'));
+
+const reactPath = join(WC, 'react-manifest.json');
+check('catalog == react manifest', () => {
+  if (!existsSync(reactPath)) throw new Error('react-manifest.json is missing');
+  const react = read(reactPath);
+  const names = new Set((react.components ?? []).map((c) => c.tagName ?? c.name));
+  assertSameSet('component sets differ', catalogNames, names, 'catalog', 'react');
+});
+
+const cemPath = join(REPO, 'custom-elements.json');
+check('catalog == custom-elements.json', () => {
+  if (!existsSync(cemPath)) throw new Error('custom-elements.json is missing');
+  const cem = read(cemPath);
+  const names = new Set(
+    (cem.modules ?? []).flatMap((m) => (m.declarations ?? []).map((d) => d.tagName).filter(Boolean))
+  );
+  assertSameSet(
+    'component sets differ (note: build:custom-elements.json uses a shallower glob than build:mcp-manifest)',
+    catalogNames,
+    names,
+    'catalog',
+    'custom-elements.json'
+  );
+});
+
+// ── Field-level parity ───────────────────────────────────────────────
+
+check('catalog and compact agree on every prop and enum', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const catProps = def.properties?.props?.properties ?? {};
+    const cmpProps = compactByName.get(name)?.props ?? {};
+    assertSameSet(`${name}: prop sets differ`, new Set(Object.keys(catProps)), new Set(Object.keys(cmpProps)), 'catalog', 'compact');
+    for (const [prop, spec] of Object.entries(catProps)) {
+      const a = spec.enum ?? null;
+      const b = cmpProps[prop]?.enum ?? null;
+      if (JSON.stringify(a) !== JSON.stringify(b)) {
+        throw new Error(`${name}.${prop}: enum differs — catalog ${JSON.stringify(a)} vs compact ${JSON.stringify(b)}`);
+      }
+    }
+  }
+  const total = Object.values(catalog.$defs.components).reduce(
+    (n, d) => n + Object.keys(d.properties?.props?.properties ?? {}).length, 0);
+  return `${total} props`;
+});
+
+check('catalog and compact agree on containment', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const cmp = compactByName.get(name);
+    const catChildren = def.properties?.children !== undefined;
+    if (catChildren !== (cmp.acceptsChildren === true)) {
+      throw new Error(`${name}: catalog children=${catChildren} vs compact acceptsChildren=${cmp.acceptsChildren === true}`);
+    }
+    const catSlots = new Set(Object.keys(def.properties?.slots?.properties ?? {}));
+    assertSameSet(`${name}: slot sets differ`, catSlots, new Set(cmp.slots ?? []), 'catalog', 'compact');
+  }
+});
+
+check('manifest, catalog metadata, catalog schema and compact agree on events', () => {
+  const compactByName = new Map(compact.components.map((c) => [c.name, c]));
+  const native = new Set(catalog['x-native-events'] ?? []);
+  if (!native.size) throw new Error('catalog declares no x-native-events — the validator reads that list from here');
+
+  let total = 0;
+  for (const component of manifest.components) {
+    const fromManifest = new Set(Object.keys(component.events ?? {}));
+    const def = catalog.$defs.components[component.name];
+    const fromMetadata = new Set(Object.keys(def['x-events'] ?? {}));
+    const fromCompact = new Set(compactByName.get(component.name)?.events ?? []);
+
+    assertSameSet(`${component.name}: events differ`, fromManifest, fromMetadata, 'manifest', 'catalog x-events');
+    assertSameSet(`${component.name}: events differ`, fromMetadata, fromCompact, 'catalog x-events', 'compact');
+
+    // The validatable schema must admit every declared event, and must not
+    // invent any. Compared by admission rather than by set equality because a
+    // component may declare a custom event that shadows a native name —
+    // `cre8-tag` dispatches its own `change` — in which case the native branch
+    // legitimately absorbs it.
+    const names = def.properties?.events?.propertyNames;
+    if (!names) throw new Error(`${component.name}: no properties.events — events are not schema-validated`);
+    const branches = names.anyOf ?? [names];
+    const explicit = new Set(branches.flatMap((b) => b.enum ?? []));
+    const refsNative = branches.some((b) => b.$ref === '#/$defs/NativeEventName');
+    const admits = (n) => explicit.has(n) || (refsNative && native.has(n));
+
+    const unadmitted = [...fromMetadata].filter((n) => !admits(n));
+    if (unadmitted.length) {
+      throw new Error(`${component.name}: declared but not admitted by properties.events: ${unadmitted.join(', ')}`);
+    }
+    const invented = [...explicit].filter((n) => !fromMetadata.has(n) && !native.has(n));
+    if (invented.length) {
+      throw new Error(`${component.name}: properties.events admits undeclared event(s): ${invented.join(', ')}`);
+    }
+    total += fromManifest.size;
+  }
+  return `${total} events across ${manifest.components.length} components, ${native.size} native`;
+});
+
+check('the schema and the renderer agree on text children', () => {
+  const renderer = readFileSync(join(WC, 'a2ui', 'renderer.ts'), 'utf8');
+  const rendersText = /typeof\s+child\s*===\s*['"]string['"]/.test(renderer);
+  const child = catalog.$defs.Child;
+  const schemaAllowsText = !!child?.oneOf?.some((b) => b.type === 'string');
+
+  if (rendersText && !schemaAllowsText) {
+    throw new Error(
+      'renderer.ts turns string children into text nodes, but the schema does not permit them.\n' +
+        '      Text renders yet fails validation, and no schema-constrained generator can emit it.'
+    );
+  }
+  if (!rendersText && schemaAllowsText) {
+    throw new Error('the schema permits text children but the renderer no longer handles them');
+  }
+
+  // Every containment point must route through Child, or the ones that don't
+  // silently keep the old behaviour.
+  const offenders = [];
+  for (const [name, def] of Object.entries(catalog.$defs.components)) {
+    const children = def.properties?.children;
+    if (children && children.items?.$ref !== '#/$defs/Child') offenders.push(`${name}.children`);
+    for (const [slot, spec] of Object.entries(def.properties?.slots?.properties ?? {})) {
+      if (spec.items?.$ref !== '#/$defs/Child') offenders.push(`${name}.slots.${slot}`);
+    }
+  }
+  if (offenders.length) {
+    throw new Error(`containment not routed through $defs/Child: ${offenders.slice(0, 5).join(', ')}`);
+  }
+
+  // A document root is a component; bare text is not a document.
+  if (catalog.properties?.root?.$ref !== '#/$defs/Component') {
+    throw new Error('the document root must be a Component, not a Child');
+  }
+  return `${offenders.length === 0 ? 'all containment routed through Child' : ''}`;
+});
+
+check('the runtime validator reads its native-event list from the catalog', () => {
+  const source = readFileSync(join(WC, 'a2ui', 'registry.ts'), 'utf8');
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+  if (!/x-native-events/.test(code)) {
+    throw new Error('registry.ts no longer reads x-native-events — it has grown a second copy of the list');
+  }
+  if (/const\s+NATIVE_DOM_EVENTS\s*=\s*new Set\(\[/.test(code)) {
+    throw new Error('registry.ts hardcodes a native-event list again; read catalog["x-native-events"] instead');
+  }
+});
+
+check('the catalog matches the manifest it was generated from', () => {
+  if (catalog['x-a2ui']?.libraryVersion !== manifest.version) {
+    throw new Error(
+      `catalog was built from version ${catalog['x-a2ui']?.libraryVersion}, manifest is ${manifest.version} — regenerate with build:a2ui:catalog`
+    );
+  }
+  if (compact.libraryVersion !== manifest.version) {
+    throw new Error(`compact was built from version ${compact.libraryVersion}, manifest is ${manifest.version}`);
+  }
+  return `all at ${manifest.version}`;
+});
+
+// ── Report ───────────────────────────────────────────────────────────
+
+for (const note of notes) console.log(note);
+if (failures.length) {
+  console.error('\n' + failures.join('\n'));
+  console.error(`\n${failures.length} layer(s) out of parity`);
+  process.exit(1);
+}
+console.log(`\nok — ${notes.length} parity checks passed; every layer agrees`);

package/a2ui/examples/compound-families.json

@@ -0,0 +1,298 @@
+{
+  "component": "cre8-layout-container",
+  "children": [
+    {
+      "component": "cre8-heading",
+      "props": {
+        "tagVariant": "h1",
+        "type": "headline-large"
+      },
+      "children": [
+        "Compound components, worked"
+      ]
+    },
+    {
+      "component": "cre8-text-passage",
+      "children": [
+        "Every family below is nested the way its Storybook story nests it. This spec exists so get_composition can answer from ground truth rather than from a naming rule."
+      ]
+    },
+    {
+      "component": "cre8-accordion",
+      "props": {
+        "borderType": "rounded",
+        "hasDivider": true
+      },
+      "children": [
+        {
+          "component": "cre8-accordion-item",
+          "props": {
+            "heading": "What is a surface?",
+            "headingTagVariant": "h3",
+            "isActive": true
+          },
+          "slots": {
+            "default": [
+              {
+                "component": "cre8-text-passage",
+                "children": [
+                  "A region of UI an agent builds up over time while someone watches it happen."
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "component": "cre8-accordion-item",
+          "props": {
+            "heading": "How do patches address a node?",
+            "headingTagVariant": "h3"
+          },
+          "slots": {
+            "default": [
+              {
+                "component": "cre8-text-passage",
+                "children": [
+                  "By the position path the renderer already emits on events: $.slots.footer[0]."
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-tag-list",
+      "props": {
+        "label": "Topics",
+        "fieldId": "topics"
+      },
+      "children": [
+        {
+          "component": "cre8-tag",
+          "props": {
+            "text": "Design tokens",
+            "type": "checkbox",
+            "variant": "neutral",
+            "shape": "round",
+            "name": "topics"
+          }
+        },
+        {
+          "component": "cre8-tag",
+          "props": {
+            "text": "Streaming UI",
+            "type": "checkbox",
+            "variant": "neutral",
+            "shape": "round",
+            "name": "topics"
+          }
+        },
+        {
+          "component": "cre8-tag",
+          "props": {
+            "text": "Accessibility",
+            "type": "checkbox",
+            "variant": "neutral",
+            "shape": "round",
+            "name": "topics"
+          }
+        },
+        {
+          "component": "cre8-tag",
+          "props": {
+            "text": "Web components",
+            "type": "checkbox",
+            "variant": "neutral",
+            "shape": "round",
+            "name": "topics"
+          }
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-checkbox-field",
+      "props": {
+        "label": "Notify me about",
+        "fieldNote": "You can change this later."
+      },
+      "children": [
+        {
+          "component": "cre8-checkbox-field-item",
+          "props": {
+            "label": "Catalog changes",
+            "name": "notify",
+            "value": "catalog",
+            "checked": true
+          }
+        },
+        {
+          "component": "cre8-checkbox-field-item",
+          "props": {
+            "label": "Breaking spec changes",
+            "name": "notify",
+            "value": "breaking"
+          }
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-list",
+      "children": [
+        {
+          "component": "cre8-list-item",
+          "children": [
+            "Validate before returning a spec."
+          ]
+        },
+        {
+          "component": "cre8-list-item",
+          "children": [
+            "Look up children-vs-slots; it cannot be guessed."
+          ]
+        },
+        {
+          "component": "cre8-list-item",
+          "children": [
+            "Stream tokens with appendText, not by resending the tree."
+          ]
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-link-list",
+      "props": {
+        "behavior": "responsive"
+      },
+      "children": [
+        {
+          "component": "cre8-link-list-item",
+          "props": {
+            "href": "/docs/kb"
+          },
+          "slots": {
+            "default": [
+              "Knowledge base"
+            ]
+          }
+        },
+        {
+          "component": "cre8-link-list-item",
+          "props": {
+            "href": "/a2ui/catalog"
+          },
+          "slots": {
+            "default": [
+              "A2UI catalog"
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-progress-steps",
+      "children": [
+        {
+          "component": "cre8-progress-steps-item",
+          "props": {
+            "name": "Open surface",
+            "message": "Returned a URL",
+            "state": "complete"
+          }
+        },
+        {
+          "component": "cre8-progress-steps-item",
+          "props": {
+            "name": "Stream ops",
+            "message": "Patching live",
+            "state": "current"
+          }
+        },
+        {
+          "component": "cre8-progress-steps-item",
+          "props": {
+            "name": "Await events",
+            "message": "Waiting on a click"
+          }
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-breadcrumbs",
+      "props": {
+        "navAriaLabel": "Breadcrumb"
+      },
+      "children": [
+        {
+          "component": "cre8-breadcrumbs-item",
+          "children": [
+            {
+              "component": "cre8-text-link",
+              "props": {
+                "href": "/docs"
+              },
+              "slots": {
+                "default": [
+                  "Docs"
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "component": "cre8-breadcrumbs-item",
+          "children": [
+            "Streaming UI"
+          ]
+        }
+      ]
+    },
+    {
+      "component": "cre8-divider"
+    },
+    {
+      "component": "cre8-dropdown",
+      "props": {
+        "buttonText": "Theme"
+      },
+      "children": [
+        {
+          "component": "cre8-dropdown-item",
+          "props": {
+            "ariaLabel": "Use the cre8 brand"
+          },
+          "children": [
+            "cre8"
+          ]
+        },
+        {
+          "component": "cre8-dropdown-item",
+          "props": {
+            "ariaLabel": "Use the a2ui brand"
+          },
+          "children": [
+            "cre8-a2ui"
+          ]
+        }
+      ]
+    }
+  ]
+}