inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

package/scanner/story-args-resolution-regression.ts

@@ -0,0 +1,311 @@
+import assert from 'node:assert/strict';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { ComponentScanner } from './component-scanner';
+
+/**
+ * Regression: story `args` resolution must handle three shapes that
+ * commonly appear in real consumer stories but were silently dropped or
+ * mis-parsed before:
+ *
+ * 1. **Spread of a shared base** (`...BASE_ARGS`) — the canonical pattern
+ *    for stories that mostly share args and only override one field:
+ *
+ *        const BASE_ARGS = { marketSymbol: "SOL", activeSide: "long", ... };
+ *        export const WithLegend = { args: { ...BASE_ARGS, markers: [...] } };
+ *
+ *    Previously the scanner only walked `Node.isPropertyAssignment`,
+ *    silently skipping `Node.isSpreadAssignment`. Every BASE_ARGS field
+ *    went missing from `argsContext`, so the component body saw
+ *    `marketSymbol = undefined` and rendered blank.
+ *
+ * 2. **`null` / `undefined` keyword literals** as story arg values —
+ *    e.g. `error: null` in BASE_ARGS. `parseLiteralValue` previously
+ *    fell through to `val.getText()` and returned the STRING `"null"`,
+ *    which is truthy. Conditionals like `{error && <Banner>{error}</Banner>}`
+ *    then rendered the banner with literal "null" text.
+ *
+ * 3. **Array literal property values** (`markers: [{...}, {...}]`) —
+ *    `resolveExpressionValue` doesn't handle ArrayLiteralExpression, so
+ *    the story-args loop set the arg to `undefined`. Inside the component
+ *    `{markers.length ? <Legend/> : null}` then evaluated `undefined.length`
+ *    → undefined → both branches skipped → legend missing. Fix: fall back
+ *    to `parseLiteralValue` (already used by `extractPropsFromNode` for
+ *    the JSX-prop equivalent).
+ *
+ * These fixes are exercised against an on-disk fixture project so the
+ * test models the production scan path (`pnpm inkbridge:scan`), not a
+ * synthetic in-memory variant.
+ */
+
+interface JsxNodeLike {
+  type: 'element' | 'text';
+  tagName?: string;
+  content?: string;
+  props?: Record<string, unknown>;
+  children?: JsxNodeLike[];
+}
+
+interface StoryShape {
+  name: string;
+  jsxTree?: JsxNodeLike;
+}
+
+interface ScannedShape {
+  name: string;
+  stories?: StoryShape[];
+}
+
+function findElement(node: JsxNodeLike | undefined | null, tag: string): JsxNodeLike | null {
+  if (!node || node.type !== 'element') return null;
+  if (node.tagName === tag) return node;
+  for (const child of node.children || []) {
+    const found = findElement(child, tag);
+    if (found) return found;
+  }
+  return null;
+}
+
+function findAllElements(node: JsxNodeLike | undefined | null, tag: string, out: JsxNodeLike[] = []): JsxNodeLike[] {
+  if (!node || node.type !== 'element') return out;
+  if (node.tagName === tag) out.push(node);
+  for (const child of node.children || []) findAllElements(child, tag, out);
+  return out;
+}
+
+function collectText(node: JsxNodeLike | undefined | null, out: string[] = []): string[] {
+  if (!node) return out;
+  if (node.type === 'text') {
+    if (typeof node.content === 'string') out.push(node.content);
+    return out;
+  }
+  for (const child of node.children || []) collectText(child, out);
+  return out;
+}
+
+const FIXTURE_DIR = path.resolve(
+  process.cwd(),
+  'tools/figma-plugin/scanner/__fixtures__/story-args-resolution'
+);
+
+// Write fixture files to disk. The scanner discovers components via glob,
+// so in-memory ts-morph files aren't enough — we need real files. Cleaned
+// up at end of run so re-runs are idempotent.
+function writeFixtures(): void {
+  fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+  fs.writeFileSync(
+    path.join(FIXTURE_DIR, 'Card.tsx'),
+    `
+      export interface CardProps {
+        title: string;
+        subtitle: string;
+        error: string | null;
+        activeSide: "long" | "short";
+        items: Array<{ id: string; label: string }>;
+      }
+      export function Card({ title, subtitle, error, activeSide, items }: CardProps) {
+        return (
+          <div>
+            <h1>{title}</h1>
+            <p>{subtitle}</p>
+            {error && <div data-role="error-banner">{error}</div>}
+            <button data-active={activeSide === "long" ? "true" : "false"}>{activeSide}</button>
+            {items.length ? (
+              <ul>
+                {items.map((it) => <li data-id={it.id}>{it.label}</li>)}
+              </ul>
+            ) : null}
+          </div>
+        );
+      }
+    `,
+    'utf-8'
+  );
+  fs.writeFileSync(
+    path.join(FIXTURE_DIR, 'Card.stories.tsx'),
+    `
+      import { Card } from "./Card";
+      const meta = { component: Card };
+      export default meta;
+
+      const BASE_ARGS = {
+        title: "Hello",
+        subtitle: "from base",
+        error: null,
+        activeSide: "long" as const,
+        items: [],
+      };
+
+      // Case 1: spread of base + override with array literal. Exercises
+      // the SpreadAssignment branch AND the ArrayLiteralExpression fallback
+      // in the PropertyAssignment branch.
+      export const WithItems = {
+        args: {
+          ...BASE_ARGS,
+          items: [{ id: "a", label: "Alpha" }, { id: "b", label: "Beta" }],
+        },
+      };
+
+      // Case 2: spread that includes a \`null\` keyword literal. The base's
+      // \`error: null\` MUST NOT become the string "null" (which is truthy
+      // and would render the error banner).
+      export const NoError = {
+        args: { ...BASE_ARGS },
+      };
+
+      // Case 3: explicit override that flips a value. Verifies args
+      // ordering — properties after the spread win.
+      export const ShortSide = {
+        args: { ...BASE_ARGS, activeSide: "short" as const },
+      };
+
+      // Case 4: direct \`null\` PropertyAssignment (no spread). Mirrors
+      // the real PerpsHeader story shape: \`viewingWalletLabel: null\`
+      // written inline. The args-extraction path uses
+      // \`extractStringValue\`, which stringifies the null keyword to
+      // "null" — \`buildArgsPropsContext\` must drop that so the
+      // conditional \`{viewingWalletLabel ? ... : null}\` resolves
+      // falsy and the wallet div doesn't render.
+      export const DirectNoError = {
+        args: {
+          title: "Direct",
+          subtitle: "no spread",
+          error: null,
+          activeSide: "long" as const,
+          items: [],
+        },
+      };
+    `,
+    'utf-8'
+  );
+}
+
+function cleanupFixtures(): void {
+  try {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+async function run(): Promise<void> {
+  writeFixtures();
+
+  const scanner = new ComponentScanner({
+    componentPaths: [FIXTURE_DIR],
+    filePattern: '*.tsx',
+    exclude: [],
+  });
+
+  const results = (await scanner.scanAll()) as unknown as ScannedShape[];
+  const card = results.find((r) => r.name === 'Card');
+  assert.ok(card, `must find the Card component; got names: ${results.map((r) => r.name).join(', ')}`);
+  const stories = card.stories || [];
+  const byName = (n: string) => stories.find((s) => s.name === n || s.name.replace(/\s+/g, '') === n);
+
+  // -------------------------------------------------------------------------
+  // Case 1: WithItems — spread + array literal override
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('WithItems');
+    assert.ok(story?.jsxTree, 'WithItems story must produce a jsxTree');
+    const h1 = findElement(story.jsxTree, 'h1');
+    const h1Text = collectText(h1).join('');
+    assert.ok(
+      h1Text.includes('Hello'),
+      `WithItems should inherit title="Hello" from BASE_ARGS via spread; got "${h1Text}"`,
+    );
+    const items = findAllElements(story.jsxTree, 'li');
+    assert.equal(
+      items.length,
+      2,
+      `WithItems should render 2 <li> from the array-literal override; got ${items.length}`,
+    );
+    const ids = items.map((it) => it.props?.['data-id']).join(',');
+    assert.equal(
+      ids,
+      'a,b',
+      `array-literal story-arg must preserve object keys; got "${ids}"`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Case 2: NoError — spread including `error: null`
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('NoError');
+    assert.ok(story?.jsxTree, 'NoError story must produce a jsxTree');
+    // The error banner is the only nested <div> with data-role="error-banner".
+    function findByRole(n: JsxNodeLike | undefined, role: string): JsxNodeLike | null {
+      if (!n || n.type !== 'element') return null;
+      if (n.props?.['data-role'] === role) return n;
+      for (const c of n.children || []) {
+        const f = findByRole(c, role);
+        if (f) return f;
+      }
+      return null;
+    }
+    const errBanner = findByRole(story.jsxTree, 'error-banner');
+    assert.equal(
+      errBanner,
+      null,
+      `null literal must not be coerced to truthy string "null" — error banner should be absent`,
+    );
+    // h1 still resolves the title from the base.
+    const h1 = findElement(story.jsxTree, 'h1');
+    const h1Text = collectText(h1).join('');
+    assert.ok(h1Text.includes('Hello'), `NoError should inherit title from BASE_ARGS; got "${h1Text}"`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Case 3: ShortSide — explicit override after spread wins
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('ShortSide');
+    assert.ok(story?.jsxTree, 'ShortSide story must produce a jsxTree');
+    const btn = findElement(story.jsxTree, 'button');
+    const btnText = collectText(btn).join('');
+    assert.ok(
+      btnText.includes('short'),
+      `explicit override should win over base; got button text "${btnText}"`,
+    );
+    assert.equal(
+      btn?.props?.['data-active'],
+      'false',
+      `activeSide override should flip the ternary; expected data-active="false" got "${btn?.props?.['data-active']}"`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Case 4: DirectNoError — direct PropertyAssignment of a `null` literal
+  // (no spread). Mirrors PerpsHeader's `viewingWalletLabel: null`.
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('DirectNoError');
+    assert.ok(story?.jsxTree, 'DirectNoError story must produce a jsxTree');
+    function findByRole2(n: JsxNodeLike | undefined, role: string): JsxNodeLike | null {
+      if (!n || n.type !== 'element') return null;
+      if (n.props?.['data-role'] === role) return n;
+      for (const c of n.children || []) {
+        const f = findByRole2(c, role);
+        if (f) return f;
+      }
+      return null;
+    }
+    const errBanner = findByRole2(story.jsxTree, 'error-banner');
+    assert.equal(
+      errBanner,
+      null,
+      `direct PropertyAssignment of \`null\` must drop the prop — error banner should be absent (was the PerpsHeader "null" bug)`,
+    );
+  }
+
+  console.log('story-args-resolution-regression: PASS (4 cases)');
+}
+
+run()
+  .catch((err) => {
+    cleanupFixtures();
+    throw err;
+  })
+  .then(cleanupFixtures);

package/scanner/story-dimensioning-regression.ts

@@ -8,7 +8,7 @@ import {
   treeHasDescendantClass,
   treeHasPortalWithFullHeight,
 } from '../src/design-system/story-dimensioning';
-import type { JsxNode } from '../src/tailwind';
+import { findAnyMaxWidthInTree, type JsxNode } from '../src/tailwind';
 import type { ComponentStory } from '../src/components';
 
 /**
@@ -295,4 +295,79 @@ assert.equal(
   'null tree falls back to layoutClasses scan',
 );
 
+// ---------------------------------------------------------------------------
+// findAnyMaxWidthInTree — looser fallback for portal-mounted dialogs
+// ---------------------------------------------------------------------------
+//
+// The strict `extractLeadingContainerMaxWidthFromTree` walks only the
+// single-child spine AND requires `w-full` on the same node. shadcn
+// DialogContent has `sm:max-w-lg` but no `w-full`, and its parent Dialog
+// usually has multi-child fan-out (overlay + content). So the strict helper
+// returns null and the story falls back to the generic 900px width, making
+// the dialog preview look much wider than it would in the browser.
+// `findAnyMaxWidthInTree` is the looser fallback wired in
+// `resolveStoryLayoutWidth` for that case.
+
+// Single-child spine with max-w → picks it up (parity with the strict helper).
+assert.equal(
+  findAnyMaxWidthInTree(el({ className: 'max-w-lg' })),
+  512,
+  'max-w-lg on root returns 512 (lg = 32rem)',
+);
+
+// Variant-prefixed (sm:max-w-lg) is honoured — extractMaxWidth already
+// handles responsive variants after the Pass-2 extractor fix.
+assert.equal(
+  findAnyMaxWidthInTree(el({ className: 'sm:max-w-lg grid' })),
+  512,
+  'variant-prefixed sm:max-w-lg resolves to 512 — covers shadcn DialogContent',
+);
+
+// Multi-child parent doesn't block the walk — the helper descends every branch.
+{
+  const tree = el({}, [
+    el({ className: 'overlay fixed inset-0' }),
+    el({ className: 'sm:max-w-lg grid' }, [el({ className: 'p-6' })]),
+  ]);
+  assert.equal(
+    findAnyMaxWidthInTree(tree),
+    512,
+    'multi-child parent (Dialog overlay + content) does not block the walk',
+  );
+}
+
+// Without `w-full` the strict helper bails — this looser one does not.
+assert.equal(
+  findAnyMaxWidthInTree(el({ className: 'max-w-sm' })),
+  384,
+  'lack of w-full does not prevent picking up max-w-* — sm = 24rem = 384',
+);
+
+// Picks the SMALLEST max-w-* when multiple appear in the tree (most
+// restrictive constraint wins as the story-width hint).
+{
+  const tree = el({ className: 'max-w-4xl' }, [
+    el({ className: 'max-w-md' }),
+  ]);
+  assert.equal(
+    findAnyMaxWidthInTree(tree),
+    448,
+    'when multiple max-w-* appear, the smallest wins (md = 28rem = 448)',
+  );
+}
+
+// No max-w anywhere → null (so callers can fall through to 900px default).
+assert.equal(
+  findAnyMaxWidthInTree(el({ className: 'flex flex-col p-4' })),
+  null,
+  'tree with no max-w-* returns null — caller decides the fallback',
+);
+
+// Null tree is tolerated.
+assert.equal(
+  findAnyMaxWidthInTree(undefined),
+  null,
+  'undefined tree returns null without throwing',
+);
+
 console.log('story-dimensioning-regression: PASS');

package/scanner/style-map.ts

@@ -35,6 +35,57 @@ async function loadStylesheet(id: string, base: string): Promise<{ path: string;
   return { path: filePath, base: path.dirname(filePath), content };
 }
 
+/**
+ * Resolve a Tailwind v4 `@plugin "..."` directive to a JS module.
+ *
+ * Tailwind v4's `compile()` invokes this whenever it encounters
+ * `@plugin "foo"` in CSS. The directive points at a node_modules
+ * package whose default export is a Tailwind plugin (e.g.
+ * `@tailwindcss/typography`). Without this option, `compile()` throws
+ * "No `loadModule` function provided" the moment any `@plugin` line
+ * exists in the consumer's CSS.
+ *
+ * We don't actually USE the plugin's generated classes for the style
+ * map (typography utilities like `prose` are matched separately if at
+ * all), but the compile call has to succeed for the rest of the
+ * scan-time CSS lookup to work.
+ */
+async function loadModule(
+  id: string,
+  base: string,
+  _resourceHint: 'plugin' | 'config'
+): Promise<{ path: string; base: string; module: unknown }> {
+  const root = process.cwd();
+  // Resolve the bare package id against the consumer's node_modules.
+  // Use Node's createRequire so we honour the consumer's resolution
+  // (pnpm hoisting, peer deps, etc.) without forcing a path shape.
+  const { createRequire } = await import('node:module');
+  const require = createRequire(path.join(root, 'package.json'));
+  let resolved: string;
+  try {
+    resolved = require.resolve(id, { paths: [root, base] });
+  } catch (_e) {
+    // Plugin not installed — return a no-op plugin so compile doesn't
+    // crash. The scan won't expand that plugin's utilities, but the
+    // rest of the CSS still resolves.
+    return { path: id, base, module: () => ({}) };
+  }
+  const imported = await import(resolved);
+  // Tailwind v4's loadModule contract wants the Plugin or Config OBJECT,
+  // not the ESM namespace. ESM modules (`export default plugin(...)`)
+  // surface the plugin under `.default`; CJS interop sometimes
+  // double-wraps (`{ default: { default: pluginFn } }`). Unwrap once or
+  // twice until we hit something that isn't a plain namespace object.
+  let mod: unknown = imported;
+  if (mod && typeof mod === 'object' && 'default' in (mod as object)) {
+    mod = (mod as { default: unknown }).default;
+  }
+  if (mod && typeof mod === 'object' && 'default' in (mod as object)) {
+    mod = (mod as { default: unknown }).default;
+  }
+  return { path: resolved, base: path.dirname(resolved), module: mod };
+}
+
 function extractClassName(selector: string): string | null {
   const dot = selector.indexOf('.');
   if (dot === -1) return null;
@@ -134,9 +185,15 @@ export async function buildStyleMap(classes: string[]): Promise<StyleMap> {
   if (unique.length === 0) return {};
 
   const css = fs.readFileSync(path.resolve(process.cwd(), 'src/app/globals.css'), 'utf-8');
+  // Cast `loadModule` to the compile() type. Our internal return type uses
+  // `module: unknown` because we accept any user-provided plugin / config
+  // shape; Tailwind's exported `Plugin | UserConfig` is narrower than what
+  // we can statically guarantee, so a structural cast here is safer than
+  // forcing the loader to assert against the narrow union.
   const compiled = await compile(css, {
     base: process.cwd(),
     loadStylesheet,
+    loadModule: loadModule as never,
   });
 
   const cssOutput = compiled.build(unique);