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

package/src/layout/parser/ir.ts

@@ -0,0 +1,80 @@
+/**
+ * LayoutIR — the intermediate representation produced by the Tailwind →
+ * Figma layout parser. The split parsers (flex, grid, spacing, alignment,
+ * sizing, responsive) all read class lists and write into a single LayoutIR
+ * instance via small `parseX(classes, ir)` helpers. The orchestrator in
+ * `layout-parser.ts` (`LayoutParser.parseToIR`) calls them in order and
+ * hands the result to `LayoutParser.applyToFrame`.
+ *
+ * This file owns:
+ *   - the `LayoutIR` shape itself
+ *   - the `SizingMode` enum reused on width / height axes
+ *   - the IR factory `makeEmptyIR()` so each parser starts from a known
+ *     baseline rather than each call site repeating the defaults
+ */
+
+/**
+ * Sizing mode for a single axis (width or height).
+ * - FIXED: explicit pixel size (w-20, h-10)
+ * - HUG: shrink to content (default for text, no size class)
+ * - FILL: expand to fill available space (flex-1, w-full inside a flex parent)
+ */
+export type SizingMode = 'FIXED' | 'HUG' | 'FILL';
+
+/**
+ * Captures the Tailwind layout intent before any Figma node is touched.
+ */
+export interface LayoutIR {
+  // Container properties
+  layoutMode: 'HORIZONTAL' | 'VERTICAL' | 'NONE';
+  wrap: boolean;
+  gap: number;
+  gapX?: number;
+  gapY?: number;
+
+  // Padding
+  paddingTop: number;
+  paddingRight: number;
+  paddingBottom: number;
+  paddingLeft: number;
+
+  // Alignment (for containers)
+  mainAlign: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN';
+  crossAlign: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'BASELINE';
+
+  // Sizing (resolved based on context)
+  widthMode: SizingMode;
+  heightMode: SizingMode;
+  fixedWidth?: number;
+  fixedHeight?: number;
+  widthFraction?: number; // 0.0-1.0 for fractional widths (w-1/2, w-1/3, etc.)
+  heightFraction?: number; // 0.0-1.0 for fractional heights
+  minWidth?: number; // pixel floor from `min-w-N` / `min-w-[Npx]`
+  minHeight?: number; // pixel floor from `min-h-N` / `min-h-[Npx]`
+
+  // Child-specific (applied when this node is a child of a flex parent)
+  grow: number; // 0 = don't grow, 1 = grow
+  shrinkZero?: boolean; // `shrink-0` / `flex-shrink-0` — force layoutGrow = 0
+  selfAlign?: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH';
+}
+
+/**
+ * Default IR — every parser-side function mutates this in place rather
+ * than constructing partial objects, so the shape stays consistent.
+ */
+export function makeEmptyIR(): LayoutIR {
+  return {
+    layoutMode: 'NONE',
+    wrap: false,
+    gap: 0,
+    paddingTop: 0,
+    paddingRight: 0,
+    paddingBottom: 0,
+    paddingLeft: 0,
+    mainAlign: 'MIN',
+    crossAlign: 'MIN',
+    widthMode: 'HUG',
+    heightMode: 'HUG',
+    grow: 0,
+  };
+}

package/src/layout/parser/layout-mode.ts

@@ -0,0 +1,57 @@
+/**
+ * Detect the LayoutIR `layoutMode` from Tailwind display + direction
+ * utilities. Spans flex AND grid because both end up writing to the
+ * same IR field — Figma auto-layout has only HORIZONTAL / VERTICAL /
+ * NONE, with no separate flex/grid distinction.
+ *
+ * Inputs handled:
+ *   - `flex` / `inline-flex` → HORIZONTAL (CSS default flex-direction: row)
+ *   - `flex-col` / `flex-col-reverse` → VERTICAL
+ *   - `flex-row` / `flex-row-reverse` → HORIZONTAL
+ *   - `grid` / `inline-grid` → VERTICAL by default; HORIZONTAL when a
+ *     `grid-cols-N` class is also present (the columns wrap children
+ *     horizontally; the actual column count is applied later by
+ *     `markGridColumnsNode`, not in the IR itself)
+ *
+ * Class-order semantics matter: a later utility overrides earlier ones,
+ * which is what makes responsive variants like
+ * `flex flex-col sm:flex-row` work — the `sm:` prefix is stripped at the
+ * breakpoint resolver, leaving `flex flex-col flex-row` at the `sm`
+ * pass. Trailing `flex-row` then wins.
+ *
+ * Behaviour preserved 1:1 from the original `parseLayoutMode` static
+ * method on `LayoutParser`. Locked in by the layout-mode regression test.
+ */
+
+export function parseLayoutMode(classes: string[]): 'HORIZONTAL' | 'VERTICAL' | 'NONE' {
+  let mode: 'HORIZONTAL' | 'VERTICAL' | 'NONE' = 'NONE';
+  // Track whether flex-direction was explicitly set: in real CSS,
+  // `display:flex` does not reset `flex-direction`, so a trailing bare
+  // `flex` after `flex-col` must not override the direction back to row.
+  let directionSet = false;
+  for (const cls of classes) {
+    if (cls === 'flex' || cls === 'inline-flex') {
+      if (!directionSet) mode = 'HORIZONTAL'; // default flex direction is row
+      continue;
+    }
+    if (cls === 'grid' || cls === 'inline-grid') {
+      // grid without grid-cols-N is a single-column layout (like flex-col).
+      // grid WITH grid-cols-N wraps horizontally — the column count is
+      // applied later by markGridColumnsNode, not stored in the IR.
+      const hasColumns = classes.some(c => /^grid-cols-\d+$/.test(c));
+      mode = hasColumns ? 'HORIZONTAL' : 'VERTICAL';
+      directionSet = true;
+      continue;
+    }
+    if (cls === 'flex-col' || cls === 'flex-col-reverse') {
+      mode = 'VERTICAL';
+      directionSet = true;
+      continue;
+    }
+    if (cls === 'flex-row' || cls === 'flex-row-reverse') {
+      mode = 'HORIZONTAL';
+      directionSet = true;
+    }
+  }
+  return mode;
+}

package/src/layout/parser/sizing.ts

@@ -0,0 +1,241 @@
+/**
+ * Tailwind sizing utilities → LayoutIR.
+ * Owns: w-*, h-*, size-*, w-full, h-full, h-screen, min-h-screen,
+ * fractional w/h (w-1/2, w-2/3, h-1/3, …), arbitrary `[Xpx/rem/em]`,
+ * named max-w (xs, sm, …, 7xl, prose, screen-*).
+ *
+ * Behaviour preserved 1:1 from the original `parseSizing` static method
+ * on `LayoutParser`. Locked in by the sizing regression test.
+ */
+
+import type { LayoutIR } from './ir';
+import { resolveSpacing } from './spacing-scale';
+
+/**
+ * Tailwind fractional width/height utilities — map to a 0..1 fraction.
+ * In Figma we materialize fractions as proportional grow on the parent's
+ * primary axis (see `parseSizing` setting `widthMode: 'FILL'` + `widthFraction`).
+ */
+const FRACTIONAL_SIZES: Record<string, number> = {
+  // Halves
+  '1/2': 0.5,
+  // Thirds
+  '1/3': 1 / 3,
+  '2/3': 2 / 3,
+  // Quarters
+  '1/4': 0.25,
+  '2/4': 0.5,
+  '3/4': 0.75,
+  // Fifths
+  '1/5': 0.2,
+  '2/5': 0.4,
+  '3/5': 0.6,
+  '4/5': 0.8,
+  // Sixths
+  '1/6': 1 / 6,
+  '2/6': 2 / 6,
+  '3/6': 0.5,
+  '4/6': 4 / 6,
+  '5/6': 5 / 6,
+  // Twelfths
+  '1/12': 1 / 12,
+  '2/12': 2 / 12,
+  '3/12': 0.25,
+  '4/12': 4 / 12,
+  '5/12': 5 / 12,
+  '6/12': 0.5,
+  '7/12': 7 / 12,
+  '8/12': 8 / 12,
+  '9/12': 0.75,
+  '10/12': 10 / 12,
+  '11/12': 11 / 12,
+  // Full
+  'full': 1.0,
+};
+
+/**
+ * Tailwind named max-width tokens (default theme).
+ * Treated as fixed widths — Figma has no "max" constraint that maps
+ * cleanly onto a frame, so the closest faithful render is to pin the
+ * frame at the named max value.
+ */
+const NAMED_MAX_WIDTHS: Record<string, number> = {
+  'xs': 320, 'sm': 384, 'md': 448, 'lg': 512, 'xl': 576,
+  '2xl': 672, '3xl': 768, '4xl': 896, '5xl': 1024, '6xl': 1152, '7xl': 1280,
+  'prose': 640,
+  'screen-sm': 640, 'screen-md': 768, 'screen-lg': 1024, 'screen-xl': 1280, 'screen-2xl': 1536,
+};
+
+/**
+ * Parse sizing utilities into `ir.widthMode/heightMode/fixedWidth/
+ * fixedHeight/widthFraction/heightFraction`. Mutates the IR in place.
+ */
+export function parseSizing(classes: string[], ir: LayoutIR): void {
+  for (const cls of classes) {
+    // Fixed width: w-20 (scale), w-[100px] (arbitrary)
+    const wScaleMatch = cls.match(/^w-(\d+(?:\.\d+)?)$/);
+    if (wScaleMatch) {
+      const val = resolveSpacing(wScaleMatch[1]);
+      if (val > 0) {
+        ir.widthMode = 'FIXED';
+        ir.fixedWidth = val;
+      }
+      continue;
+    }
+
+    const wArbitraryMatch = cls.match(/^w-\[(\d+(?:\.\d+)?)(px|rem|em)?\]$/);
+    if (wArbitraryMatch) {
+      let val = parseFloat(wArbitraryMatch[1]);
+      const unit = wArbitraryMatch[2] || 'px';
+      if (unit === 'rem' || unit === 'em') val *= 16;
+      ir.widthMode = 'FIXED';
+      ir.fixedWidth = val;
+      continue;
+    }
+
+    // Arbitrary percentage width: `w-[60%]` → parent-relative fraction.
+    // Used by the shadcn Progress adapter (indicator inside track) and by
+    // any consumer who writes percent widths directly in className.
+    const wPercentMatch = cls.match(/^w-\[(\d+(?:\.\d+)?)%\]$/);
+    if (wPercentMatch) {
+      const pct = parseFloat(wPercentMatch[1]);
+      if (Number.isFinite(pct) && pct >= 0) {
+        ir.widthMode = 'FILL';
+        ir.widthFraction = Math.max(0, Math.min(1, pct / 100));
+      }
+      continue;
+    }
+
+    // Fractional width: w-1/2, w-1/3, w-2/3, etc.
+    const wFractionMatch = cls.match(/^w-(\d+\/\d+)$/);
+    if (wFractionMatch) {
+      const fraction = FRACTIONAL_SIZES[wFractionMatch[1]];
+      if (fraction !== undefined) {
+        ir.widthMode = 'FILL';
+        ir.widthFraction = fraction;
+      }
+      continue;
+    }
+
+    // Fixed height: h-20 (scale), h-[100px] (arbitrary)
+    const hScaleMatch = cls.match(/^h-(\d+(?:\.\d+)?)$/);
+    if (hScaleMatch) {
+      const val = resolveSpacing(hScaleMatch[1]);
+      if (val > 0) {
+        ir.heightMode = 'FIXED';
+        ir.fixedHeight = val;
+      }
+      continue;
+    }
+
+    const hArbitraryMatch = cls.match(/^h-\[(\d+(?:\.\d+)?)(px|rem|em)?\]$/);
+    if (hArbitraryMatch) {
+      let val = parseFloat(hArbitraryMatch[1]);
+      const unit = hArbitraryMatch[2] || 'px';
+      if (unit === 'rem' || unit === 'em') val *= 16;
+      ir.heightMode = 'FIXED';
+      ir.fixedHeight = val;
+      continue;
+    }
+
+    // Arbitrary percentage height: `h-[40%]` — mirror of `w-[N%]`.
+    const hPercentMatch = cls.match(/^h-\[(\d+(?:\.\d+)?)%\]$/);
+    if (hPercentMatch) {
+      const pct = parseFloat(hPercentMatch[1]);
+      if (Number.isFinite(pct) && pct >= 0) {
+        ir.heightMode = 'FILL';
+        ir.heightFraction = Math.max(0, Math.min(1, pct / 100));
+      }
+      continue;
+    }
+
+    // Fractional height: h-1/2, h-1/3, h-2/3, etc.
+    const hFractionMatch = cls.match(/^h-(\d+\/\d+)$/);
+    if (hFractionMatch) {
+      const fraction = FRACTIONAL_SIZES[hFractionMatch[1]];
+      if (fraction !== undefined) {
+        ir.heightMode = 'FILL';
+        ir.heightFraction = fraction;
+      }
+      continue;
+    }
+
+    // Size (both dimensions): size-20
+    const sizeMatch = cls.match(/^size-(\d+(?:\.\d+)?)$/);
+    if (sizeMatch) {
+      const val = resolveSpacing(sizeMatch[1]);
+      if (val > 0) {
+        ir.widthMode = 'FIXED';
+        ir.heightMode = 'FIXED';
+        ir.fixedWidth = val;
+        ir.fixedHeight = val;
+      }
+      continue;
+    }
+
+    // Fill width / height (resolved later in applyChildProperties).
+    if (cls === 'w-full') {
+      ir.widthMode = 'FILL';
+    }
+    if (cls === 'h-full' || cls === 'h-screen' || cls === 'min-h-screen') {
+      // h-screen / min-h-screen behave like h-full once resolveStoryLayoutHeight
+      // pins the story frame's primary axis to a fixed viewport height.
+      ir.heightMode = 'FILL';
+    }
+
+    // Min-height (scale): `min-h-20` → 80px floor on frame height.
+    // Used by shadcn Textarea (`min-h-20`), tall hero containers, etc.
+    const minHScaleMatch = cls.match(/^min-h-(\d+(?:\.\d+)?)$/);
+    if (minHScaleMatch) {
+      const val = resolveSpacing(minHScaleMatch[1]);
+      if (val > 0) ir.minHeight = val;
+      continue;
+    }
+    const minHArbitraryMatch = cls.match(/^min-h-\[(\d+(?:\.\d+)?)(px|rem|em)?\]$/);
+    if (minHArbitraryMatch) {
+      let val = parseFloat(minHArbitraryMatch[1]);
+      const unit = minHArbitraryMatch[2] || 'px';
+      if (unit === 'rem' || unit === 'em') val *= 16;
+      if (val > 0) ir.minHeight = val;
+      continue;
+    }
+
+    // Min-width — mirror of min-h-*.
+    const minWScaleMatch = cls.match(/^min-w-(\d+(?:\.\d+)?)$/);
+    if (minWScaleMatch) {
+      const val = resolveSpacing(minWScaleMatch[1]);
+      if (val > 0) ir.minWidth = val;
+      continue;
+    }
+    const minWArbitraryMatch = cls.match(/^min-w-\[(\d+(?:\.\d+)?)(px|rem|em)?\]$/);
+    if (minWArbitraryMatch) {
+      let val = parseFloat(minWArbitraryMatch[1]);
+      const unit = minWArbitraryMatch[2] || 'px';
+      if (unit === 'rem' || unit === 'em') val *= 16;
+      if (val > 0) ir.minWidth = val;
+      continue;
+    }
+
+    // Max-width with fixed scale value
+    const maxWMatch = cls.match(/^max-w-(\d+(?:\.\d+)?)$/);
+    if (maxWMatch) {
+      const val = resolveSpacing(maxWMatch[1]);
+      if (val > 0) {
+        ir.widthMode = 'FIXED';
+        ir.fixedWidth = val;
+      }
+      continue;
+    }
+
+    // Named max-width (max-w-xl, max-w-2xl, …)
+    const maxWNamedMatch = cls.match(/^max-w-(xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|prose|screen-sm|screen-md|screen-lg|screen-xl|screen-2xl)$/);
+    if (maxWNamedMatch) {
+      const val = NAMED_MAX_WIDTHS[maxWNamedMatch[1]];
+      if (val) {
+        ir.widthMode = 'FIXED';
+        ir.fixedWidth = val;
+      }
+      continue;
+    }
+  }
+}

package/src/layout/parser/spacing-scale.ts

@@ -0,0 +1,78 @@
+/**
+ * Tailwind spacing scale (in px) and the resolver function.
+ * Shared by the spacing parser (gap, padding) and the sizing parser
+ * (w-*, h-* in scale units). Pure: no Figma dependency, no IR mutation.
+ *
+ * Based on Tailwind v3+ docs: 1rem = 16px, scale base unit 0.25rem (4px).
+ */
+
+const SPACING_SCALE: Record<string, number> = {
+  'px': 1, // Special 1px value
+  '0': 0,
+  '0.5': 2, // 0.125rem
+  '1': 4,
+  '1.5': 6,
+  '2': 8,
+  '2.5': 10,
+  '3': 12,
+  '3.5': 14,
+  '4': 16,
+  '5': 20,
+  '6': 24,
+  '7': 28,
+  '8': 32,
+  '9': 36,
+  '10': 40,
+  '11': 44,
+  '12': 48,
+  '14': 56,
+  '16': 64,
+  '20': 80,
+  '24': 96,
+  '28': 112,
+  '32': 128,
+  '36': 144,
+  '40': 160,
+  '44': 176,
+  '48': 192,
+  '52': 208,
+  '56': 224,
+  '60': 240,
+  '64': 256,
+  '72': 288,
+  '80': 320,
+  '96': 384,
+};
+
+/**
+ * Resolve a single spacing token value to its pixel size.
+ * Accepts:
+ *   - Tailwind scale values: '4' → 16, '0.5' → 2, 'px' → 1
+ *   - Arbitrary values: '[12px]', '[1.5rem]', '[1em]' (rem/em → px at 16px base)
+ *   - Bare numbers not in the scale: parsed and multiplied by 4 (Tailwind default unit)
+ *   - Unknown: 0
+ */
+export function resolveSpacing(value: string): number {
+  // Arbitrary value [Xpx] / [Xrem] / [Xem]
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1);
+    const match = inner.match(/^(\d+(?:\.\d+)?)(px|rem|em)?$/);
+    if (match) {
+      let num = parseFloat(match[1]);
+      const unit = match[2] || 'px';
+      if (unit === 'rem' || unit === 'em') num *= 16;
+      return num;
+    }
+  }
+
+  if (SPACING_SCALE[value] !== undefined) {
+    return SPACING_SCALE[value];
+  }
+
+  const num = parseFloat(value);
+  if (!isNaN(num)) {
+    return num * 4;
+  }
+
+  return 0;
+}

package/src/layout/parser/spacing.ts

@@ -0,0 +1,134 @@
+/**
+ * Tailwind spacing utilities → LayoutIR.
+ * Owns: gap-*, gap-x-*, gap-y-*, space-x-*, space-y-*, p-*, px-*, py-*,
+ * pt-*, pr-*, pb-*, pl-*.
+ *
+ * Each parser function reads a class list and mutates the IR in place.
+ * Behaviour is preserved 1:1 from the original parseGap / parsePadding
+ * methods on `LayoutParser`. Locked in by the spacing regression test.
+ */
+
+import type { LayoutIR } from './ir';
+import { resolveSpacing } from './spacing-scale';
+
+/**
+ * Parse gap and space utilities into `ir.gap`, `ir.gapX`, `ir.gapY`.
+ * `space-x-*` / `space-y-*` map onto gap on the matching axis (Tailwind
+ * uses sibling margins; Figma auto-layout has no margin so we collapse
+ * the intent into the parent's gap).
+ */
+export function parseGap(classes: string[], ir: LayoutIR): void {
+  for (const cls of classes) {
+    // gap-* (both axes)
+    const gapMatch = cls.match(/^gap-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (gapMatch) {
+      const val = resolveSpacing(gapMatch[1]);
+      ir.gap = val;
+      ir.gapX = val;
+      ir.gapY = val;
+      continue;
+    }
+
+    // gap-x-*
+    const gapXMatch = cls.match(/^gap-x-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (gapXMatch) {
+      ir.gapX = resolveSpacing(gapXMatch[1]);
+      if (ir.layoutMode === 'HORIZONTAL') {
+        ir.gap = ir.gapX;
+      }
+      continue;
+    }
+
+    // gap-y-*
+    const gapYMatch = cls.match(/^gap-y-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (gapYMatch) {
+      ir.gapY = resolveSpacing(gapYMatch[1]);
+      if (ir.layoutMode === 'VERTICAL') {
+        ir.gap = ir.gapY;
+      }
+      continue;
+    }
+
+    // space-x-* → gap on horizontal layouts only. Negative form
+    // (`-space-x-2`) drives overlap (Avatar groups, badge clusters); maps to
+    // a negative item-spacing in Figma's auto-layout.
+    const spaceXMatch = cls.match(/^(-)?space-x-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (spaceXMatch && ir.layoutMode === 'HORIZONTAL') {
+      const sign = spaceXMatch[1] ? -1 : 1;
+      ir.gap = sign * resolveSpacing(spaceXMatch[2]);
+      continue;
+    }
+
+    // space-y-* → gap on vertical layouts only. Negative form mirrors -space-x-*.
+    const spaceYMatch = cls.match(/^(-)?space-y-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (spaceYMatch && ir.layoutMode === 'VERTICAL') {
+      const sign = spaceYMatch[1] ? -1 : 1;
+      ir.gap = sign * resolveSpacing(spaceYMatch[2]);
+      continue;
+    }
+  }
+}
+
+/**
+ * Parse padding utilities into `ir.paddingTop / Right / Bottom / Left`.
+ */
+export function parsePadding(classes: string[], ir: LayoutIR): void {
+  for (const cls of classes) {
+    const pMatch = cls.match(/^p-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (pMatch) {
+      const val = resolveSpacing(pMatch[1]);
+      ir.paddingTop = val;
+      ir.paddingRight = val;
+      ir.paddingBottom = val;
+      ir.paddingLeft = val;
+      continue;
+    }
+
+    const pxMatch = cls.match(/^px-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (pxMatch) {
+      const val = resolveSpacing(pxMatch[1]);
+      ir.paddingLeft = val;
+      ir.paddingRight = val;
+      continue;
+    }
+
+    const pyMatch = cls.match(/^py-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (pyMatch) {
+      const val = resolveSpacing(pyMatch[1]);
+      ir.paddingTop = val;
+      ir.paddingBottom = val;
+      continue;
+    }
+
+    const ptMatch = cls.match(/^pt-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (ptMatch) {
+      ir.paddingTop = resolveSpacing(ptMatch[1]);
+      continue;
+    }
+    const prMatch = cls.match(/^pr-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (prMatch) {
+      ir.paddingRight = resolveSpacing(prMatch[1]);
+      continue;
+    }
+    const pbMatch = cls.match(/^pb-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (pbMatch) {
+      ir.paddingBottom = resolveSpacing(pbMatch[1]);
+      continue;
+    }
+    const plMatch = cls.match(/^pl-(\d+(?:\.\d+)?|\[.+\])$/);
+    if (plMatch) {
+      ir.paddingLeft = resolveSpacing(plMatch[1]);
+      continue;
+    }
+  }
+}
+
+/**
+ * Orchestrator helper — calls parseGap and parsePadding in order.
+ * Provided for callers that want a single entrypoint for "all the
+ * spacing utilities in one go".
+ */
+export function parseSpacing(classes: string[], ir: LayoutIR): void {
+  parseGap(classes, ir);
+  parsePadding(classes, ir);
+}