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

package/src/design-system/symbol-source.ts

@@ -0,0 +1,172 @@
+import { splitClassName } from '../tailwind';
+import { MASTER_ICON_NAME_KEY } from '../components/component-instance';
+import { getThemeContext } from './theme-context';
+import { buildCvaClassesWithSelection } from './cva-utils';
+import {
+  normalizeComponentName,
+  findBestStoryElementForClasses,
+  getStoriesWithJsxTree,
+  countClassOverlap,
+  findMatchingInstance,
+} from './story-tree-search';
+import type { StoryBuilderContext } from './story-builder-context';
+
+/**
+ * Builders for the source nodes that wrap each variant of a generated CVA
+ * component set. Given a story's JSX tree and a target variant selection,
+ * `buildCvaSymbolSourceNode` finds the best-matching element, overrides
+ * its className with the resolved variant classes (so the master renders
+ * the exact variant), and renders it through `ctx.renderJsxTree`.
+ *
+ * `buildNonCvaSymbolSourceNode` (state / simple / compound masters) still
+ * lives in story-builder.ts because it depends on createStateStoryFrame /
+ * createSimpleStoryFrame — those move out together in phase 6b.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function renderStoryElementAsSymbolSource(node: any, theme: string, ctx: StoryBuilderContext): any | null {
+  if (!node || node.type !== 'element') return null;
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  return ctx.renderJsxTree(node, colorGroup, radiusGroup, theme, 0, {
+    parentLayout: 'VERTICAL',
+  });
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getCvaVariantValueForStory(def: any, story: any, variantKey: string): string {
+  const instance = findMatchingInstance(def, story);
+  const props = instance && instance.props ? instance.props : {};
+  if (props[variantKey] != null && String(props[variantKey]) !== '') {
+    return String(props[variantKey]);
+  }
+  if (def && def.defaultVariants && def.defaultVariants[variantKey] != null) {
+    return String(def.defaultVariants[variantKey]);
+  }
+  const variants = def && def.variants ? def.variants : {};
+  if (variants[variantKey] && variants[variantKey][0] != null) {
+    return String(variants[variantKey][0]);
+  }
+  return '';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function storyMatchesCvaSelection(def: any, story: any, selection: Record<string, string>): boolean {
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return false;
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    const storyValue = getCvaVariantValueForStory(def, story, key);
+    const selectionValue = selection[key] != null ? String(selection[key]) : '';
+    if (selectionValue && storyValue !== selectionValue) return false;
+  }
+  return true;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function overrideClassNameForCvaTarget(node: any, def: any, targetClasses: string[]): any {
+  if (!node || node.type !== 'element') return node;
+  const existing = splitClassName(node.props && node.props.className);
+  const existingSet = new Set(existing);
+  let identical = existing.length === targetClasses.length;
+  if (identical) {
+    for (let i = 0; i < targetClasses.length; i++) {
+      if (!existingSet.has(targetClasses[i])) { identical = false; break; }
+    }
+  }
+  if (identical) return node;
+  const nextProps = Object.assign({}, node.props || {});
+  nextProps.className = targetClasses.join(' ');
+  // Also strip CVA variant prop values from the scanned node — the target
+  // classes already encode the variant, so leaving stale variant props can
+  // confuse downstream class inference.
+  const variantKeys = Object.keys((def && def.variants) || {});
+  for (let i = 0; i < variantKeys.length; i++) delete nextProps[variantKeys[i]];
+  return Object.assign({}, node, { props: nextProps });
+}
+
+export function buildCvaSymbolSourceNode(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: any,
+  selection: Record<string, string>,
+  theme: string,
+  ctx: StoryBuilderContext
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any | null {
+  const stories = getStoriesWithJsxTree(def);
+  if (stories.length === 0) return null;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const orderedStories = stories.slice().sort(function(a: any, b: any): number {
+    const aScore = storyMatchesCvaSelection(def, a, selection) ? 0 : 1;
+    const bScore = storyMatchesCvaSelection(def, b, selection) ? 0 : 1;
+    return aScore - bScore;
+  });
+  const targetClasses = buildCvaClassesWithSelection(def, selection, '');
+  const targetSet = new Set(targetClasses);
+  const selfName = normalizeComponentName(def && def.name ? def.name : '');
+
+  for (let i = 0; i < orderedStories.length; i++) {
+    const story = orderedStories[i];
+    const tree = story && story.jsxTree;
+    if (!tree || tree.type !== 'element') continue;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let nodeToRender: any | null = null;
+    const candidate = findBestStoryElementForClasses(tree, targetClasses);
+    const candidateIsSelfComponent = !!(
+      candidate
+      && candidate.type === 'element'
+      && candidate.isComponent
+      && normalizeComponentName(candidate.tagName) === selfName
+    );
+    if (candidate && candidate.type === 'element' && !candidateIsSelfComponent) {
+      nodeToRender = candidate;
+    } else {
+      const rootClasses = splitClassName(tree.props && tree.props.className);
+      const overlap = countClassOverlap(rootClasses, targetSet);
+      const minOverlap = Math.max(1, Math.min(4, Math.floor(targetClasses.length * 0.35)));
+      if (overlap >= minOverlap) {
+        nodeToRender = tree;
+      }
+    }
+    if (!nodeToRender) continue;
+
+    // If the picked element isn't an exact match for this variant+size
+    // selection (e.g. Outline button from the Variants story, which is at
+    // default size), override its className with the target variant's
+    // resolved classes so the master's component for this variant renders
+    // at the right size/style. Otherwise the structure comes from a
+    // mismatched source and the variant says "Sm" but renders at h-9.
+    const nodeForRender = overrideClassNameForCvaTarget(nodeToRender, def, targetClasses);
+    const sourceNode = renderStoryElementAsSymbolSource(nodeForRender, theme, ctx);
+    if (sourceNode) {
+      // Stamp the icon name on the rendered source node so the master
+      // variant Component (built in cva-master.ts) can propagate it. The
+      // CVA-instance creator reads this to decide whether per-instance
+      // element children (e.g. icons) match the master and can reuse it,
+      // or differ and need frame-rendering fall-back.
+      const iconName = findFirstElementChildTagName(nodeForRender);
+      if (iconName) {
+        try { sourceNode.setPluginData(MASTER_ICON_NAME_KEY, iconName); } catch (_e) { /* ignore */ }
+      }
+      return sourceNode;
+    }
+  }
+
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function findFirstElementChildTagName(node: any): string | null {
+  if (!node || typeof node !== 'object') return null;
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    if (c && c.type === 'element' && typeof c.tagName === 'string' && c.tagName.length > 0) {
+      return c.tagName;
+    }
+  }
+  return null;
+}

package/src/design-system/table-helpers.ts

@@ -0,0 +1,56 @@
+import { getBaseClass } from '../tailwind';
+import type { NodeIR } from '../tailwind';
+
+/**
+ * Helpers for rendering semantic HTML table primitives (table / thead /
+ * tbody / tfoot / tr / td / th) into Figma's auto-layout model. Borders
+ * are cleared selectively to avoid the double-border seam that two
+ * adjacent cells would otherwise produce.
+ */
+
+/**
+ * True when `classes` contains a width override that should bypass the
+ * default "fill the row" behaviour of a table cell — e.g. an explicit
+ * `w-32`, `flex-1`, or `min-w-*`.
+ */
+export function hasTableCellSizeOverride(classes: string[]): boolean {
+  for (const cls of classes) {
+    const base = getBaseClass(cls);
+    if (!base) continue;
+    if (base === 'flex-1' || base === 'grow' || base === 'grow-0') return true;
+    if (base.startsWith('w-') || base.startsWith('min-w-') || base.startsWith('max-w-')) return true;
+  }
+  return false;
+}
+
+export function getNumericColSpan(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.max(1, Math.floor(value));
+  if (typeof value === 'string') {
+    const parsed = parseInt(value, 10);
+    if (Number.isFinite(parsed)) return Math.max(1, parsed);
+  }
+  return 1;
+}
+
+export function isSemanticTableContainer(node: NodeIR): boolean {
+  if (node.kind !== 'element' && node.kind !== 'component') return false;
+  return node.tagLower === 'table' || node.tagLower === 'thead' || node.tagLower === 'tbody' || node.tagLower === 'tfoot';
+}
+
+export function clearTopBorder(node: SceneNode): void {
+  if (!('strokeTopWeight' in node)) return;
+  try {
+    node.strokeTopWeight = 0;
+  } catch (_err) {
+    // ignore if unsupported on this specific subtype
+  }
+}
+
+export function clearBottomBorder(node: SceneNode): void {
+  if (!('strokeBottomWeight' in node)) return;
+  try {
+    node.strokeBottomWeight = 0;
+  } catch (_err) {
+    // ignore if unsupported on this specific subtype
+  }
+}

package/src/design-system/tag-predicates.ts

@@ -0,0 +1,99 @@
+/**
+ * Pure tag-name predicates for the Radix / Base UI primitive components
+ * the plugin recognises (Accordion, Tabs, Select, RadioGroup, Portal-rooted
+ * popover panels). Used by ui-builder and any future renderer that needs
+ * to branch on component family without inlining the string lists.
+ *
+ * No Figma dependencies, no shared state — pure string matching.
+ */
+
+export function isAccordionRootTag(tagName: string): boolean {
+  return tagName === 'Accordion' || tagName === 'AccordionPrimitive.Root';
+}
+
+export function isAccordionItemTag(tagName: string): boolean {
+  return tagName === 'AccordionItem' || tagName === 'AccordionPrimitive.Item';
+}
+
+export function isAccordionContentTag(tagName: string): boolean {
+  return tagName === 'AccordionContent' || tagName === 'AccordionPrimitive.Content';
+}
+
+export function isAccordionHeaderTag(tagName: string): boolean {
+  return tagName === 'AccordionHeader' || tagName === 'AccordionPrimitive.Header';
+}
+
+export function isRadioGroupRootTag(tagName: string): boolean {
+  return tagName === 'RadioGroup' || tagName === 'RadioGroupPrimitive' || tagName === 'RadioGroupPrimitive.Root';
+}
+
+export function isRadioGroupItemTag(tagName: string): boolean {
+  return tagName === 'RadioGroupItem' || tagName === 'RadioPrimitive.Root' || tagName === 'RadioGroupPrimitive.Item';
+}
+
+export function isRadioGroupIndicatorTag(tagName: string): boolean {
+  return tagName === 'RadioPrimitive.Indicator' || tagName === 'RadioGroupPrimitive.Indicator';
+}
+
+export function isTabsRootTag(tagName: string): boolean {
+  return tagName === 'Tabs' || tagName === 'TabsPrimitive.Root';
+}
+
+export function isTabsTriggerTag(tagName: string): boolean {
+  return tagName === 'TabsTrigger' || tagName === 'TabsPrimitive.Trigger' || tagName === 'TabsPrimitive.Tab';
+}
+
+export function isTabsListTag(tagName: string): boolean {
+  return tagName === 'TabsList' || tagName === 'TabsPrimitive.List';
+}
+
+export function isTabsContentTag(tagName: string): boolean {
+  return tagName === 'TabsContent' || tagName === 'TabsPrimitive.Content' || tagName === 'TabsPrimitive.Panel';
+}
+
+export function isSelectRootTag(tagName: string): boolean {
+  return tagName === 'Select' || tagName === 'SelectPrimitive.Root';
+}
+
+export function isSelectContentTag(tagName: string): boolean {
+  return tagName === 'SelectContent' || tagName === 'SelectPrimitive.Content';
+}
+
+export function isSelectTriggerTag(tagName: string): boolean {
+  return tagName === 'SelectTrigger' || tagName === 'SelectPrimitive.Trigger';
+}
+
+export function isSelectValueTag(tagName: string): boolean {
+  return tagName === 'SelectValue' || tagName === 'SelectPrimitive.Value';
+}
+
+export function isSelectItemTag(tagName: string): boolean {
+  return tagName === 'SelectItem' || tagName === 'SelectPrimitive.Item';
+}
+
+export function isSelectItemIndicatorTag(tagName: string): boolean {
+  return tagName === 'SelectPrimitive.ItemIndicator' || tagName === 'SelectItemIndicator';
+}
+
+/**
+ * Radix & Base UI portal components (Popover/Tooltip/DropdownMenu/HoverCard/Menu)
+ * expose an `Arrow` subcomponent that visually points at the trigger. In
+ * Figma the panel isn't anchored to the trigger, so the arrow is noise.
+ */
+export function isPortalArrowTag(tagName: string): boolean {
+  if (!tagName) return false;
+  const lower = tagName.toLowerCase();
+  return lower.endsWith('.arrow')
+    || lower === 'popoverarrow'
+    || lower === 'tooltiparrow'
+    || lower === 'dropdownmenuarrow'
+    || lower === 'hovercardarrow'
+    || lower === 'menuarrow';
+}
+
+export function isSelectScrollButtonTag(tagName: string): boolean {
+  return tagName === 'SelectScrollUpButton'
+    || tagName === 'SelectPrimitive.ScrollUpButton'
+    || tagName === 'SelectScrollDownButton'
+    || tagName === 'SelectPrimitive.ScrollDownButton';
+}

package/src/design-system/theme-context.ts

@@ -0,0 +1,52 @@
+import { TOKENS, getThemeColors, getThemeRadius } from '../tokens';
+
+/**
+ * Per-theme rendering context, cached so the design-system page builder
+ * doesn't re-resolve TOKENS on every story it renders.
+ */
+export type ThemeContext = {
+  theme: string;
+  colorGroup: Record<string, string>;
+  radiusGroup: Record<string, string> | null;
+};
+
+const THEME_CONTEXT_CACHE: Record<string, ThemeContext> = {};
+
+export function getThemeContext(theme: string): ThemeContext {
+  if (THEME_CONTEXT_CACHE[theme]) return THEME_CONTEXT_CACHE[theme];
+  const colorGroup = getThemeColors(TOKENS, theme);
+  const radiusGroup = getThemeRadius(TOKENS, theme);
+  const ctx: ThemeContext = {
+    theme: theme,
+    colorGroup: colorGroup,
+    radiusGroup: radiusGroup,
+  };
+  THEME_CONTEXT_CACHE[theme] = ctx;
+  return ctx;
+}
+
+/**
+ * Spacing constants for the Design System page layout. Used by both
+ * story-builder and preview-builder so column widths, axis gaps, and
+ * matrix paddings stay consistent across boards.
+ */
+export const BOARD_LAYOUT = {
+  boardGap: 96,
+  sectionPaddingX: 64,
+  sectionPaddingY: 64,
+  columnsGap: 320,
+  columnGap: 144,
+  columnPaddingX: 0,
+  columnPaddingY: 160,
+  sectionGroupGap: 176,
+  sectionTitleGap: 48,
+  componentBlockGap: 128,
+  componentTitleGap: 48,
+  storyGap: 32,
+  showcaseGap: 128,
+  stateMatrixGap: 40,
+  stateMatrixAxisGap: 64,
+  responsiveBlockGap: 32,
+  responsiveColumnGap: 64,
+  responsiveLabelGap: 20,
+};

package/src/design-system/typography.ts

@@ -0,0 +1,100 @@
+import { parseUtilityClass } from '../tailwind';
+
+/**
+ * Tailwind text-* utility → Figma font-size (px). Shared lookup; importers
+ * read it directly when matching raw classes (the parsed-utility variants
+ * `getPreviewTypography` handles via `parseUtilityClass` first).
+ */
+export const TEXT_SIZE_PX: Record<string, number> = {
+  'text-xs': 12,
+  'text-sm': 14,
+  'text-base': 16,
+  'text-lg': 18,
+  'text-xl': 20,
+  'text-2xl': 24,
+  'text-3xl': 30,
+  'text-4xl': 36,
+  'text-5xl': 48,
+};
+
+/**
+ * Numeric ordering of `font-*` weight utilities. Used to decide
+ * "≥ semibold = bold" without enumerating the seven matching utilities.
+ */
+export const FONT_WEIGHT_RANK: Record<string, number> = {
+  'font-thin': 1,
+  'font-extralight': 2,
+  'font-light': 3,
+  'font-normal': 4,
+  'font-medium': 5,
+  'font-semibold': 6,
+  'font-bold': 7,
+  'font-extrabold': 8,
+  'font-black': 9,
+};
+
+/**
+ * Tailwind weight class → Figma font-style string. Used by the renderer
+ * when assigning a font's style face (`Inter:Medium`, `Open Sans:Bold`, …).
+ */
+export const FONT_WEIGHT_TO_STYLE: Record<string, string> = {
+  'font-thin': 'Thin',
+  'font-extralight': 'ExtraLight',
+  'font-light': 'Light',
+  'font-normal': 'Regular',
+  'font-medium': 'Medium',
+  'font-semibold': 'SemiBold',
+  'font-bold': 'Bold',
+  'font-extrabold': 'ExtraBold',
+  'font-black': 'Black',
+};
+
+/**
+ * Resolves Tailwind text-* and font-* classes to Figma typography defaults
+ * (font size in px, bold flag). Shared by preview-builder, cva-master and
+ * the story-instance render paths so they all surface identical typography
+ * for the same class set.
+ */
+export function getPreviewTypography(classes: string[]): { fontSize: number; bold: boolean } {
+  let fontSize = 14;
+  let bold = false;
+  for (let i = 0; i < classes.length; i++) {
+    const atom = parseUtilityClass(classes[i]);
+    const utility = atom.utility || '';
+    if (TEXT_SIZE_PX[utility] != null) fontSize = TEXT_SIZE_PX[utility];
+    if (utility === 'font-bold' || utility === 'font-semibold') bold = true;
+    if (utility === 'font-normal' || utility === 'font-light' || utility === 'font-extralight') bold = false;
+  }
+  return { fontSize: fontSize, bold: bold };
+}
+
+export function getFontStyleFromClasses(classes: string[], fallback?: string): string | undefined {
+  let found: string | undefined;
+  for (const cls of classes) {
+    const style = FONT_WEIGHT_TO_STYLE[cls];
+    if (style) { found = style; }
+  }
+  if (found == null && fallback == null) return undefined;
+  return found != null ? found : fallback;
+}
+
+export function getResolvedTextSizeFromClasses(classes: string[], fallback?: number): number | undefined {
+  let resolved = fallback;
+  for (const cls of classes) {
+    if (TEXT_SIZE_PX[cls] != null) resolved = TEXT_SIZE_PX[cls];
+  }
+  return resolved;
+}
+
+export function getResolvedBoldFromClasses(classes: string[], fallback?: boolean): boolean | undefined {
+  let rank = fallback ? 7 : 4;
+  let seenWeight = false;
+  for (const cls of classes) {
+    if (FONT_WEIGHT_RANK[cls] != null) {
+      rank = FONT_WEIGHT_RANK[cls];
+      seenWeight = true;
+    }
+  }
+  if (!seenWeight && fallback == null) return undefined;
+  return rank >= FONT_WEIGHT_RANK['font-semibold'];
+}