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

package/src/design-system/cva-master.ts

@@ -0,0 +1,427 @@
+import { splitClassName, applyTailwindStylesToFrame, tailwindClassesToStyle, type TailwindStyle } from '../tailwind';
+import { parseColor, bindColorVariable } from '../tokens';
+import { createTextNode } from '../text';
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible, enforceFixedBoxSizingAfterLayout } from '../layout';
+import { MASTER_ICON_NAME_KEY } from '../components/component-instance';
+import { findChildByName, getFrameHash, setFrameHash, hashString, hashDef } from '../cache';
+import { RENDER_ENGINE_VERSION } from '../render-engine-version';
+import { tagGeneratedNode } from './generated-node';
+import { getThemeContext } from './theme-context';
+import {
+  ENABLE_SYMBOL_MASTERS,
+  toFigmaVariantPropertyName,
+  toFigmaVariantPropertyValue,
+  ensureThemeComponentLibrary,
+} from './master-shared';
+import { buildCvaClassesWithSelection } from './cva-utils';
+import { getPreviewTypography } from './typography';
+import { buildCvaSymbolSourceNode } from './symbol-source';
+import type { StoryBuilderContext } from './story-builder-context';
+
+/**
+ * CVA-master logic: enumerating Class-Variance-Authority variant
+ * combinations and producing a Figma component set per design-token theme.
+ *
+ * Shared concepts live in sibling utility modules so this file can import
+ * its dependencies directly without callback indirection:
+ *   - buildCvaClassesWithSelection → cva-utils.ts
+ *   - getPreviewTypography → typography.ts
+ *   - buildCvaSymbolSourceNode → symbol-source.ts
+ *
+ * Re-exported here for back-compat with story-builder's existing imports.
+ */
+export { buildCvaClassesWithSelection };
+
+export const MAX_CVA_MASTER_COMBINATIONS = 96;
+
+export function applyStyleToFrame(frame: FrameNode, style: TailwindStyle, theme: string): void {
+  if (!style) return;
+
+  if (style.bg) {
+    const bgBound = style.bgToken && bindColorVariable(frame, style.bgToken, 'fill', theme);
+    if (bgBound) {
+      if (style.bgOpacity != null && Array.isArray(frame.fills) && frame.fills.length > 0) {
+        const nextFills = JSON.parse(JSON.stringify(frame.fills));
+        nextFills[0].opacity = style.bgOpacity;
+        frame.fills = nextFills;
+      }
+    } else {
+      const bg = parseColor(style.bg);
+      const bgOpacity = style.bgOpacity != null ? style.bgOpacity : (bg.a == null ? 1 : bg.a);
+      frame.fills = [{ type: 'SOLID', color: { r: bg.r, g: bg.g, b: bg.b }, opacity: bgOpacity }];
+    }
+  }
+
+  if (style.border) {
+    const borderBound = style.borderToken && bindColorVariable(frame, style.borderToken, 'stroke', theme);
+    if (!borderBound) {
+      const borderColor = parseColor(style.border);
+      frame.strokes = [{ type: 'SOLID', color: { r: borderColor.r, g: borderColor.g, b: borderColor.b } }];
+    }
+    frame.strokeWeight = 1;
+  }
+
+  if (style.opacity != null) {
+    frame.opacity = style.opacity;
+  }
+}
+
+function normalizeVariantLookupValue(rawValue: unknown): string {
+  return String(rawValue == null ? '' : rawValue).trim().toLowerCase();
+}
+
+function normalizeVariantOptionValue(rawValue: unknown): string {
+  let value = String(rawValue == null ? '' : rawValue).trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"'))
+    || (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1).trim();
+  }
+  return value.toLowerCase();
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveCvaVariantValue(def: any, variantKey: string, candidate: unknown): string | null {
+  const values = def && def.variants && def.variants[variantKey];
+  if (!Array.isArray(values) || values.length === 0) return null;
+  const normalizedCandidate = normalizeVariantLookupValue(candidate);
+  if (!normalizedCandidate) return null;
+  for (let i = 0; i < values.length; i++) {
+    const option = values[i];
+    if (
+      normalizeVariantLookupValue(option) === normalizedCandidate
+      || normalizeVariantOptionValue(option) === normalizedCandidate
+    ) {
+      return String(option);
+    }
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getDefaultCvaVariantValue(def: any, variantKey: string): string | null {
+  const fromDefault = resolveCvaVariantValue(
+    def,
+    variantKey,
+    def && def.defaultVariants ? def.defaultVariants[variantKey] : undefined
+  );
+  if (fromDefault) return fromDefault;
+  const values = def && def.variants && def.variants[variantKey];
+  if (!Array.isArray(values) || values.length === 0) return null;
+  return String(values[0]);
+}
+
+export function isTruthyVariantValue(rawValue: unknown): boolean {
+  const lowered = normalizeVariantLookupValue(rawValue);
+  return lowered === 'true' || lowered === '1' || lowered === 'yes' || lowered === 'on';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function inferCvaVariantValueFromClassName(def: any, variantKey: string, className: unknown): string | null {
+  const classTokens = splitClassName(className == null ? '' : String(className));
+  if (classTokens.length === 0) return null;
+  const present: Record<string, boolean> = {};
+  for (let i = 0; i < classTokens.length; i++) {
+    present[classTokens[i]] = true;
+  }
+
+  const values = def && def.variants && def.variants[variantKey];
+  if (!Array.isArray(values) || values.length === 0) return null;
+
+  let bestValue: string | null = null;
+  let bestScore = 0;
+  let tied = false;
+
+  for (let i = 0; i < values.length; i++) {
+    const value = String(values[i]);
+    const valueClasses = def && def.variantClasses && def.variantClasses[variantKey] && def.variantClasses[variantKey][value];
+    if (!Array.isArray(valueClasses) || valueClasses.length === 0) continue;
+
+    let score = 0;
+    for (let j = 0; j < valueClasses.length; j++) {
+      const token = String(valueClasses[j] || '').trim();
+      if (!token) continue;
+      if (present[token]) score++;
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestValue = value;
+      tied = false;
+    } else if (score > 0 && score === bestScore) {
+      tied = true;
+    }
+  }
+
+  if (bestScore <= 0 || tied || !bestValue) return null;
+  return bestValue;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getCvaSelectionFromInstance(def: any, instance: any): Record<string, string> {
+  const props = instance && instance.props ? instance.props : {};
+  const selection: Record<string, string> = {};
+  const variantKeys = Object.keys((def && def.variants) || {});
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    const resolved =
+      resolveCvaVariantValue(def, key, props[key])
+      || inferCvaVariantValueFromClassName(def, key, props.className)
+      || getDefaultCvaVariantValue(def, key);
+    if (resolved) selection[key] = resolved;
+  }
+  return selection;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function countCvaVariantCombinations(def: any): number {
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return 0;
+  let total = 1;
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    const values = def && def.variants && def.variants[key];
+    if (!Array.isArray(values) || values.length === 0) return 0;
+    total *= values.length;
+  }
+  return total;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function enumerateCvaVariantSelections(def: any): Record<string, string>[] {
+  const variantKeys = Object.keys((def && def.variants) || {});
+  const out: Record<string, string>[] = [];
+  if (variantKeys.length === 0) return out;
+
+  function walk(index: number, current: Record<string, string>): void {
+    if (index >= variantKeys.length) {
+      out.push(Object.assign({}, current));
+      return;
+    }
+    const key = variantKeys[index];
+    const values = def && def.variants && def.variants[key];
+    if (!Array.isArray(values) || values.length === 0) return;
+    for (let i = 0; i < values.length; i++) {
+      current[key] = String(values[i]);
+      walk(index + 1, current);
+    }
+    delete current[key];
+  }
+
+  walk(0, {});
+  return out;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildCvaMasterHash(def: any, theme: string): string {
+  const themeContext = getThemeContext(theme);
+  return hashString(
+    hashDef(def)
+      + ':'
+      + theme
+      + ':cva-master-v3:'
+      + RENDER_ENGINE_VERSION
+      + ':'
+      + JSON.stringify({
+        colorGroup: themeContext.colorGroup,
+        radiusGroup: themeContext.radiusGroup,
+      })
+  );
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function shouldCreateCvaMaster(def: any): boolean {
+  if (!def || def.type !== 'cva') return false;
+  if (def.symbolCandidate === false) return false;
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return false;
+  const combinations = countCvaVariantCombinations(def);
+  return combinations > 0 && combinations <= MAX_CVA_MASTER_COMBINATIONS;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getCvaSymbolFallbackReason(def: any, instance: any): string {
+  const props = instance && instance.props ? instance.props : {};
+  if (splitClassName(props.className).length > 0) return 'class_override';
+  if (def && def.symbolCandidate === false) return 'symbol_candidate_disabled';
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return 'missing_variants';
+  const combinations = countCvaVariantCombinations(def);
+  if (combinations <= 0) return 'invalid_variant_combinations';
+  if (combinations > MAX_CVA_MASTER_COMBINATIONS) return 'variant_combination_limit';
+  return 'component_set_or_instance_unavailable';
+}
+
+export function ensureCvaComponentSet(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: any,
+  theme: string,
+  ctx: StoryBuilderContext
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any | null {
+  if (!ENABLE_SYMBOL_MASTERS) return null;
+  if (!def || def.type !== 'cva') return null;
+  if (def.symbolCandidate === false) return null;
+
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return null;
+
+  const combinationCount = countCvaVariantCombinations(def);
+  if (combinationCount <= 0 || combinationCount > MAX_CVA_MASTER_COMBINATIONS) {
+    return null;
+  }
+
+  const themeLibrary = ensureThemeComponentLibrary(theme);
+  if (!themeLibrary) return null;
+
+  const setName = def.name + ' [' + theme + ']';
+  const masterHash = buildCvaMasterHash(def, theme);
+  const existing = findChildByName(themeLibrary, setName);
+  if (existing && existing.type === 'COMPONENT_SET' && getFrameHash(existing) === masterHash) {
+    return existing;
+  }
+  if (existing) {
+    existing.remove();
+  }
+
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const selections = enumerateCvaVariantSelections(def);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const components: any[] = [];
+
+  for (let i = 0; i < selections.length; i++) {
+    const selection = selections[i];
+    const classes = buildCvaClassesWithSelection(def, selection, '');
+
+    const comp = figma.createComponent();
+    comp.name = variantKeys
+      .map(function(key: string) {
+        return toFigmaVariantPropertyName(key) + '=' + toFigmaVariantPropertyValue(selection[key]);
+      })
+      .join(', ');
+    comp.primaryAxisSizingMode = 'AUTO';
+    comp.counterAxisSizingMode = 'AUTO';
+    comp.counterAxisAlignItems = 'CENTER';
+    comp.primaryAxisAlignItems = 'CENTER';
+    comp.itemSpacing = 8;
+    comp.fills = [];
+    comp.strokes = [];
+    // ComponentNode and FrameNode share the auto-layout / fills / strokes
+    // members these helpers touch. Cast deliberately at the call boundary.
+    ctx.applyClipBehavior(comp as unknown as FrameNode, classes);
+
+    const storyNode = buildCvaSymbolSourceNode(def, selection, theme, ctx);
+    if (storyNode) {
+      comp.layoutMode = 'VERTICAL';
+      comp.primaryAxisSizingMode = 'AUTO';
+      comp.counterAxisSizingMode = 'AUTO';
+      comp.counterAxisAlignItems = 'MIN';
+      comp.primaryAxisAlignItems = 'MIN';
+      comp.itemSpacing = 0;
+      comp.appendChild(storyNode);
+      // Propagate the icon name (stamped by buildCvaSymbolSourceNode) from
+      // the rendered sourceNode up to the master variant Component. The
+      // CVA-instance creator reads this in `tryCreateCvaComponentInstance`
+      // to decide whether an instance with element children (an icon)
+      // matches the master and can safely reuse it.
+      try {
+        const iconName = typeof (storyNode as SceneNode).getPluginData === 'function'
+          ? (storyNode as SceneNode).getPluginData(MASTER_ICON_NAME_KEY)
+          : '';
+        if (iconName) {
+          comp.setPluginData(MASTER_ICON_NAME_KEY, iconName);
+        }
+      } catch (_e) {
+        // ignore plugin-data access errors
+      }
+      // Set the inner storyNode to "Fill" horizontally so that when an
+      // instance of this master is resized by a stretching parent (e.g.
+      // shadcn DialogFooter's mobile `flex flex-col-reverse`, which gives
+      // children CSS `align-items: stretch`), the visible button pill
+      // follows the instance's new width. Equivalent to a designer
+      // manually switching the inner frame's W sizing to "Fill" in Figma's
+      // auto-layout panel. `layoutSizingHorizontal = 'FILL'` is the modern
+      // Figma API that the UI "Fill" toggle uses; `layoutAlign = 'STRETCH'`
+      // is the legacy equivalent and doesn't always propagate through HUG
+      // comp parents. Masters still hug at rest because the comp's
+      // counter-axis remains AUTO — FILL only activates width propagation
+      // when something pins the outer comp to an explicit size.
+      try {
+        if ('layoutSizingHorizontal' in storyNode) {
+          storyNode.layoutSizingHorizontal = 'FILL';
+        } else if ('layoutAlign' in storyNode) {
+          storyNode.layoutAlign = 'STRETCH';
+        }
+      } catch (_err) {
+        // ignore if plugin runtime rejects the assignment
+      }
+    } else {
+      // applyTailwindStylesToFrame / markRingNode / applyStyleToFrame all
+      // touch the shared frame mixins (fills, strokes, opacity, layout). Cast
+      // ComponentNode → FrameNode at the boundary; no `any`.
+      const compFrame = comp as unknown as FrameNode;
+      applyTailwindStylesToFrame(compFrame, classes, colorGroup, radiusGroup, theme);
+      const disabledVariantKey = variantKeys.find(function(key: string) {
+        return key.toLowerCase() === 'disabled';
+      });
+      const state = disabledVariantKey && isTruthyVariantValue(selection[disabledVariantKey])
+        ? 'disabled'
+        : 'default';
+      const style = tailwindClassesToStyle(classes, state, colorGroup);
+      applyStyleToFrame(compFrame, style, theme);
+
+      const typography = getPreviewTypography(classes);
+      const textColor = style.text
+        ? parseColor(style.text)
+        : (colorGroup.foreground ? parseColor(colorGroup.foreground) : { r: 0, g: 0, b: 0 });
+      const text = createTextNode(def.name, {
+        bold: typography.bold,
+        fontSize: typography.fontSize,
+        fill: textColor,
+      });
+      if (style.underline && text.textDecoration !== undefined) {
+        text.textDecoration = 'UNDERLINE';
+      }
+      comp.appendChild(text);
+      const ringInfo = getRingInfoFromClasses(classes, colorGroup);
+      if (ringInfo) markRingNode(compFrame, ringInfo);
+    }
+
+    enforceFixedBoxSizingAfterLayout(comp, classes);
+
+    // combineAsVariants expects components to exist in the document tree.
+    themeLibrary.appendChild(comp);
+    // Comp is now in the theme library and its sizing has been finalised by
+    // `enforceFixedBoxSizingAfterLayout` — apply the (marked) ring overlay.
+    applyRingIfPossible(comp as unknown as FrameNode, themeLibrary);
+    components.push(comp);
+  }
+
+  if (components.length === 0) {
+    return null;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let componentSet: any = null;
+  try {
+    componentSet = figma.combineAsVariants(components, themeLibrary);
+  } catch (_error) {
+    for (let i = 0; i < components.length; i++) {
+      try {
+        components[i].remove();
+      } catch (_cleanupError) {
+        // ignore cleanup errors
+      }
+    }
+    return null;
+  }
+
+  componentSet.name = setName;
+  componentSet.visible = false;
+  setFrameHash(componentSet, masterHash);
+  tagGeneratedNode(componentSet, 'cva-component-set:' + def.name + ':' + theme);
+  return componentSet;
+}

package/src/design-system/cva-utils.ts

@@ -0,0 +1,29 @@
+import { splitClassName } from '../tailwind';
+
+/**
+ * Pure CVA-class assembly. Takes a component def, a variant selection,
+ * and an optional className override; returns the resolved class list.
+ *
+ * Lifted out of cva-master.ts so symbol-source.ts can import it without
+ * cycling back through cva-master (which imports buildCvaSymbolSourceNode
+ * from symbol-source.ts).
+ */
+export function buildCvaClassesWithSelection(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: any,
+  selection: Record<string, string>,
+  extraClassName: unknown
+): string[] {
+  let classes = def && def.baseClasses ? def.baseClasses.slice() : [];
+  const variantKeys = Object.keys((def && def.variants) || {});
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    const value = selection[key];
+    if (!value) continue;
+    if (def && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+      classes = classes.concat(def.variantClasses[key][value]);
+    }
+  }
+  classes = classes.concat(splitClassName(extraClassName == null ? undefined : String(extraClassName)));
+  return classes;
+}