inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/scanner/component-sections-regression.ts

@@ -0,0 +1,198 @@
+import assert from 'node:assert/strict';
+import {
+  COMPONENT_SECTION_ORDER,
+  getComponentSectionName,
+  groupComponentDefs,
+  inferComponentSection,
+} from '../src/design-system/component-sections';
+import type { ComponentDef } from '../src/components';
+
+/**
+ * Regression: component-section classification + grouping is the routing
+ * logic that decides which heading each component lands under in the
+ * generated Figma Design System page. It runs on every preflight + render,
+ * so silent drift here scrambles the page layout for every consumer.
+ *
+ * The rules are a cascade — explicit `kind` short-circuits everything,
+ * then heuristics on `type`, `isLeaf`, `usesCount`, `usedByCount`,
+ * `hasStory` decide the bucket. Lock the cascade in so refactors don't
+ * silently flip atoms into molecules or vice versa.
+ *
+ * Extracted from `src/design-system/story-builder.ts` (was the named refactor
+ * target in `.ai/index.md`) into `src/design-system/component-sections.ts`.
+ */
+
+function def(overrides: Partial<ComponentDef> & { name: string }): ComponentDef {
+  return {
+    type: 'simple',
+    stories: [],
+    ...overrides,
+  } as ComponentDef;
+}
+
+// ---------------------------------------------------------------------------
+// Section order + section name format
+// ---------------------------------------------------------------------------
+{
+  const keys = COMPONENT_SECTION_ORDER.map((s) => s.key);
+  assert.deepEqual(
+    keys,
+    ['atoms', 'molecules', 'organisms', 'utilities', 'other'],
+    'COMPONENT_SECTION_ORDER drifted — atomic ordering atoms→molecules→organisms→utilities→other is canonical',
+  );
+
+  const atom = COMPONENT_SECTION_ORDER[0];
+  assert.equal(
+    getComponentSectionName(atom),
+    'Section / Atoms',
+    'getComponentSectionName must format with the `Section / ` prefix — that prefix is what the page-builder finds frames by',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Explicit `kind` short-circuits the heuristic
+// ---------------------------------------------------------------------------
+{
+  const cases: Array<{ kind: string; expectedKey: string }> = [
+    { kind: 'atom', expectedKey: 'atoms' },
+    { kind: 'molecule', expectedKey: 'molecules' },
+    { kind: 'organism', expectedKey: 'organisms' },
+    { kind: 'utility', expectedKey: 'utilities' },
+    { kind: 'other', expectedKey: 'other' },
+    { kind: 'ATOM', expectedKey: 'atoms' }, // case-insensitive
+  ];
+  for (const { kind, expectedKey } of cases) {
+    // Stack the heuristic against the kind to prove kind wins. usesCount=5 +
+    // usedByCount=0 + type='compound' would otherwise route to organisms.
+    const d = def({
+      name: 'X',
+      kind,
+      type: 'compound',
+      usesCount: 5,
+      usedByCount: 0,
+    });
+    assert.equal(
+      inferComponentSection(d).key,
+      expectedKey,
+      `explicit kind="${kind}" must short-circuit to ${expectedKey}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fallback heuristic cascade (no kind)
+// ---------------------------------------------------------------------------
+
+// !hasStory + usedByCount=0 + isLeaf → utilities (orphan leaf with no story)
+assert.equal(
+  inferComponentSection(
+    def({ name: 'OrphanLeaf', hasStory: false, isLeaf: true, usedByCount: 0 }),
+  ).key,
+  'utilities',
+  'leaf without story or consumers must land in utilities (cn(), helpers, etc.)',
+);
+
+// type='cva' → atoms (regardless of leaf/usedBy)
+assert.equal(
+  inferComponentSection(def({ name: 'Button', type: 'cva', usesCount: 0, usedByCount: 8 })).key,
+  'atoms',
+  'CVA components are always atoms — they own variant matrices',
+);
+
+// type='state' → atoms (input, switch, checkbox)
+assert.equal(
+  inferComponentSection(def({ name: 'Input', type: 'state', isLeaf: true })).key,
+  'atoms',
+  'state-based components are always atoms — they own hover/focus/disabled matrices',
+);
+
+// isLeaf + usedByCount>0 → atoms (leaf used somewhere = primitive)
+assert.equal(
+  inferComponentSection(def({ name: 'Icon', isLeaf: true, usedByCount: 4 })).key,
+  'atoms',
+  'a leaf used by others is a primitive — atom',
+);
+
+// usesCount>=2 → organisms (composes multiple subcomponents)
+assert.equal(
+  inferComponentSection(def({ name: 'PageHeader', usesCount: 3, usedByCount: 0 })).key,
+  'organisms',
+  'component composing 2+ subcomponents is an organism',
+);
+
+// type='compound' → molecules
+assert.equal(
+  inferComponentSection(def({ name: 'Card', type: 'compound', usesCount: 1 })).key,
+  'molecules',
+  'compound components (one slot/sub-component) are molecules',
+);
+
+// usesCount=1 → molecules
+assert.equal(
+  inferComponentSection(def({ name: 'IconButton', usesCount: 1 })).key,
+  'molecules',
+  'component using exactly one subcomponent is a molecule',
+);
+
+// usedByCount>0 (with usesCount=0, no kind, no special type) → molecules
+assert.equal(
+  inferComponentSection(def({ name: 'UsedThing', usesCount: 0, usedByCount: 2, isLeaf: false })).key,
+  'molecules',
+  'component used by others but not a leaf falls into molecules',
+);
+
+// isLeaf with no other signals → atoms
+assert.equal(
+  inferComponentSection(def({ name: 'BareLeaf', isLeaf: true, usedByCount: 0 })).key,
+  'atoms',
+  'a bare leaf with no other signal is an atom',
+);
+
+// Nothing matches → other
+assert.equal(
+  inferComponentSection(def({ name: 'Mystery', isLeaf: false, usesCount: 0, usedByCount: 0 })).key,
+  'other',
+  'a non-leaf with no uses and no consumers and no kind/type defaults to other',
+);
+
+// ---------------------------------------------------------------------------
+// groupComponentDefs: ordering, omission of empty sections, alphabetical sort
+// ---------------------------------------------------------------------------
+{
+  const defs: ComponentDef[] = [
+    def({ name: 'Zebra', kind: 'atom' }),
+    def({ name: 'Antelope', kind: 'atom' }),
+    def({ name: 'Lemur', kind: 'molecule' }),
+    def({ name: 'Bison', kind: 'organism' }),
+  ];
+
+  const grouped = groupComponentDefs(defs);
+
+  // Canonical order — atoms before molecules before organisms; utilities + other absent because empty.
+  assert.deepEqual(
+    grouped.map((g) => g.section.key),
+    ['atoms', 'molecules', 'organisms'],
+    'groupComponentDefs must return sections in canonical order, omitting empty ones',
+  );
+
+  // Within atoms: alphabetical sort (Antelope before Zebra).
+  assert.deepEqual(
+    grouped[0].defs.map((d: ComponentDef) => d.name),
+    ['Antelope', 'Zebra'],
+    'defs within a section must be sorted alphabetically by name',
+  );
+
+  // Single-entry sections have one item.
+  assert.equal(grouped[1].defs.length, 1);
+  assert.equal(grouped[1].defs[0].name, 'Lemur');
+  assert.equal(grouped[2].defs[0].name, 'Bison');
+}
+
+// Empty input → empty result (no sections rendered).
+assert.deepEqual(
+  groupComponentDefs([]),
+  [],
+  'empty input must produce empty grouping (no headers for sections without content)',
+);
+
+console.log('component-sections-regression: PASS');

package/scanner/compound-classes-lookup-regression.ts

@@ -0,0 +1,163 @@
+import assert from 'node:assert/strict';
+
+import { getCompoundClasses } from '../src/tailwind/class-utils';
+import type { ComponentDef } from '../src/components/scanner-types';
+
+/**
+ * Regression: `getCompoundClasses(def, tagName)` uses a STRICT lowercase
+ * compare — `<DialogPrimitive.Trigger>` must NOT match a subComponent
+ * registered as `DialogTrigger`.
+ *
+ * History: an earlier attempt used the same elaborate normalization as
+ * `getComponentDefByName` so that `<AvatarPrimitive.Image>` would
+ * resolve to the `AvatarImage` subComponent and get flattened to a div
+ * (so the renderer's image branch could pick up its `src` prop). That
+ * change shipped, fixed Avatar's image render, and silently broke every
+ * portal-using component (Dialog / Sheet / Select / Accordion-open /
+ * Mobile-Nav) — their portal primitives (`<DialogPrimitive.Trigger>`,
+ * `<SheetPrimitive.Content>`, ...) suddenly matched a subComponent,
+ * got flattened to `kind: 'element'`, and were routed through the
+ * wrapper-frame path instead of the kind-'component' path that knows
+ * how to position portals as overlays. The user saw trigger + gray
+ * content rendered side-by-side instead of trigger + portal panel.
+ *
+ * AvatarPrimitive.Image is unaffected by the strict match because the
+ * image branch in ui-builder (`isLeafImageLike`) accepts BOTH
+ * `kind: 'element'` and `kind: 'component'` and gates only on the
+ * presence of a `src` prop. The primitive stays `kind: 'component'`
+ * after the strict lookup but still renders correctly.
+ *
+ * This file locks the strict-match behavior so a future "let's
+ * normalize this lookup" doesn't re-break portals.
+ */
+
+function compoundDef(): ComponentDef {
+  return {
+    type: 'compound',
+    name: 'Avatar',
+    subComponents: [
+      { name: 'Avatar', slot: 'container', classes: ['relative', 'flex', 'size-10'] },
+      { name: 'AvatarImage', slot: 'container', classes: ['aspect-square', 'size-full'] },
+      { name: 'AvatarFallback', slot: 'container', classes: ['flex', 'size-full', 'bg-muted'] },
+    ],
+  } as unknown as ComponentDef;
+}
+
+function dialogDef(): ComponentDef {
+  return {
+    type: 'compound',
+    name: 'Dialog',
+    subComponents: [
+      { name: 'Dialog', slot: 'container', classes: [] },
+      { name: 'DialogTrigger', slot: 'container', classes: [] },
+      { name: 'DialogContent', slot: 'container', classes: ['fixed', 'top-1/2', 'left-1/2'] },
+      { name: 'DialogHeader', slot: 'container', classes: [] },
+    ],
+  } as unknown as ComponentDef;
+}
+
+// ---------------------------------------------------------------------------
+// Exact-name matches: the everyday case still works.
+// ---------------------------------------------------------------------------
+
+{
+  const def = compoundDef();
+  assert.deepEqual(
+    getCompoundClasses(def, 'AvatarImage'),
+    ['aspect-square', 'size-full'],
+    'exact-name match: AvatarImage → its registered classes',
+  );
+  assert.deepEqual(
+    getCompoundClasses(def, 'AvatarFallback'),
+    ['flex', 'size-full', 'bg-muted'],
+    'exact-name match: AvatarFallback → its registered classes',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Portal-primitive tags MUST NOT match by normalization.
+// `<DialogPrimitive.Trigger>` and friends must stay `kind: 'component'`
+// so the portal-aware render path positions them as overlays. If a
+// future change re-introduces normalization here, this assertion fires
+// and the matrix of portal regressions surfaces at test time instead
+// of "trigger + gray bar in every Dialog story".
+// ---------------------------------------------------------------------------
+
+{
+  const def = dialogDef();
+  assert.deepEqual(
+    getCompoundClasses(def, 'DialogPrimitive.Trigger'),
+    [],
+    'DialogPrimitive.Trigger must NOT match DialogTrigger via normalization',
+  );
+  assert.deepEqual(
+    getCompoundClasses(def, 'DialogPrimitive.Content'),
+    [],
+    'DialogPrimitive.Content must NOT match DialogContent via normalization',
+  );
+  assert.deepEqual(
+    getCompoundClasses(def, 'DialogPrimitive.Root'),
+    [],
+    'DialogPrimitive.Root must NOT match Dialog via normalization',
+  );
+}
+
+{
+  const def = compoundDef();
+  // Same rule for Avatar's primitive form — strict miss is the desired
+  // behavior here, the image branch will pick up the src prop without
+  // needing the subComponent classes merged in.
+  assert.deepEqual(
+    getCompoundClasses(def, 'AvatarPrimitive.Image'),
+    [],
+    'AvatarPrimitive.Image strictly misses — image branch handles it via src prop',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Root-fallback: the def's own name resolves to the container subComponent.
+// ---------------------------------------------------------------------------
+
+{
+  const def = compoundDef();
+  assert.deepEqual(
+    getCompoundClasses(def, 'Avatar'),
+    ['relative', 'flex', 'size-10'],
+    'the root name resolves to the container subComponent (first-match returns AvatarImage’s `slot: container` — guarded by exact-name match above)',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Negative cases — unrelated tags don't match.
+// ---------------------------------------------------------------------------
+
+{
+  const def = compoundDef();
+  assert.deepEqual(
+    getCompoundClasses(def, 'SomeOtherImage'),
+    [],
+    'a tag that shares only a suffix must not match',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Defensive cases — empty / non-compound defs.
+// ---------------------------------------------------------------------------
+
+assert.deepEqual(
+  getCompoundClasses(null as unknown as ComponentDef, 'X'),
+  [],
+  'null def → []',
+);
+assert.deepEqual(
+  getCompoundClasses({ type: 'cva', name: 'Button' } as unknown as ComponentDef, 'Button'),
+  [],
+  'non-compound def → [] (this helper is compound-only)',
+);
+assert.deepEqual(
+  getCompoundClasses({ type: 'compound', name: 'X', subComponents: [] } as unknown as ComponentDef, 'X'),
+  [],
+  'empty subComponents → []',
+);
+
+console.log('compound-classes-lookup-regression: PASS (2 exact + 4 portal-miss + 1 root + 1 negative + 3 defensive cases)');

package/scanner/css-token-reader-regression.ts

@@ -14,16 +14,17 @@ function testRootAndThemeSelectors(): void {
     .dark {
       --primary: oklch(70% 0.14 150);
     }
-    :root[data-theme="secondary"] {
+    .secondary {
       --primary: oklch(62% 0.17 250);
     }
   `;
-  const map = parseCssTokenMap(css, 'src/app/globals.css', 'auto');
+  const map = parseCssTokenMap(css, 'src/app/globals.css', 'css' as const);
   assert.equal(map.mode, 'css');
   assert.equal(map.colors.primary, 'oklch(62% 0.17 149)');
   assert.equal(map.radius.base, 8);
   assert.equal(map.fonts.sans, '"Open Sans", sans-serif');
-  assert.equal(map.themes.dark?.colors.primary, 'oklch(70% 0.14 150)');
+  // .dark {} is a dark-mode override, not a brand theme — should not appear
+  assert.equal(map.themes.dark, undefined);
   assert.equal(map.themes.secondary?.colors.primary, 'oklch(62% 0.17 250)');
 }
 
@@ -35,7 +36,7 @@ function testTailwindV4ThemeBlock(): void {
       --text-xl: 1.25rem;
     }
   `;
-  const map = parseCssTokenMap(css, 'src/app/globals.css', 'auto');
+  const map = parseCssTokenMap(css, 'src/app/globals.css', 'css' as const);
   assert.equal(map.colors.primary, 'oklch(0.7 0.2 150)');
   assert.equal(map.spacing.md, 16);
   assert.equal(map.fontSize.xl, 20);
@@ -49,7 +50,7 @@ function testShadowAndColorPrefixes(): void {
       --color-background: oklch(1 0 0);
     }
   `;
-  const map = parseCssTokenMap(css, 'src/app/tokens.css', 'auto');
+  const map = parseCssTokenMap(css, 'src/app/tokens.css', 'css' as const);
   assert.equal(map.shadows.DEFAULT, '0 1px 2px rgba(0,0,0,.1)');
   assert.equal(map.shadows.md, '0 8px 16px rgba(0,0,0,.2)');
   assert.equal(map.colors.background, 'oklch(1 0 0)');
@@ -74,7 +75,7 @@ function testImportedCssSourceResolution(): void {
       'utf8'
     );
 
-    const map = readTokenSourceMap({ projectRoot: tmpRoot, tokenSourceMode: 'auto' });
+    const map = readTokenSourceMap({ projectRoot: tmpRoot, tokenSourceMode: 'css' as const });
     assert.equal(map.mode, 'css');
     assert.equal(map.source.replace(/\\/g, '/'), 'src/theme/brand.css');
     assert.equal(map.colors.primary, 'oklch(0.62 0.19 250)');