inkhouse 0.1.0-beta.0

package/scanner/types.ts

@@ -0,0 +1,298 @@
+/**
+ * Component Scanner Types
+ *
+ * Defines the data structures for analyzed components that the Figma plugin
+ * will use to generate design system components.
+ */
+
+// ============================================================================
+// Component Analysis Types
+// ============================================================================
+
+export type ComponentType = 'cva' | 'compound' | 'state' | 'simple';
+
+/**
+ * Base interface for all component analyses
+ */
+export interface BaseComponentAnalysis {
+  type: ComponentType;
+  name: string;
+  filePath: string;
+  /** Whether a co-located *.stories.tsx file exists */
+  hasStory?: boolean;
+  /** Parsed stories from the co-located story file */
+  stories?: StoryInfo[];
+}
+
+/**
+ * A single Storybook story extracted from *.stories.tsx
+ */
+export interface StoryInfo {
+  /** Story export name (e.g., "Default", "Variants", "Sizes") */
+  name: string;
+  /** Args passed to the component (for args-based stories) */
+  args?: Record<string, string>;
+  /** Component instances found in the story's render function or args (flat) */
+  instances: ComponentInstance[];
+  /** Container layout classes (e.g., ["flex", "flex-wrap", "gap-3"]) */
+  layoutClasses?: string[];
+  /** Full JSX tree for recursive rendering */
+  jsxTree?: JsxNode;
+}
+
+/**
+ * A single component usage found in a story (flat extraction)
+ */
+export interface ComponentInstance {
+  /** Component tag name (e.g., "Button", "Card") */
+  componentName: string;
+  /** Props on the component (e.g., { variant: "default", size: "sm" }) */
+  props: Record<string, any>;
+  /** Text content children */
+  children?: string;
+}
+
+// ============================================================================
+// JSX Tree Types (for recursive content extraction)
+// ============================================================================
+
+/**
+ * A node in the JSX tree - either an element or text
+ */
+export type JsxNode = JsxElement | JsxText;
+
+/**
+ * An element node (HTML tag or React component)
+ */
+export interface JsxElement {
+  type: 'element';
+  /** Tag name (e.g., "div", "Button", "h1") */
+  tagName: string;
+  /** Whether this is a React component (starts with uppercase) */
+  isComponent: boolean;
+  /** Props/attributes on the element */
+  props: Record<string, string>;
+  /** Child nodes */
+  children: JsxNode[];
+}
+
+/**
+ * A text node
+ */
+export interface JsxText {
+  type: 'text';
+  /** The text content */
+  content: string;
+}
+
+/**
+ * CVA-based components (Button, Badge, Alert)
+ * These have explicit variants defined via class-variance-authority
+ */
+export interface CVAComponentAnalysis extends BaseComponentAnalysis {
+  type: 'cva';
+  baseClasses: string[];
+  variants: Record<string, string[]>;  // { variant: ["default", "destructive", ...] }
+  defaultVariants: Record<string, string>;
+  variantClasses: Record<string, Record<string, string[]>>;  // { variant: { default: [...classes], destructive: [...] } }
+}
+
+/**
+ * Compound components (Card, Dialog)
+ * These consist of multiple sub-components with their own classes
+ */
+export interface CompoundComponentAnalysis extends BaseComponentAnalysis {
+  type: 'compound';
+  subComponents: SubComponentInfo[];
+}
+
+export interface SubComponentInfo {
+  name: string;
+  classes: string[];
+  slot: 'container' | 'header' | 'title' | 'description' | 'content' | 'footer' | 'trigger' | 'item';
+}
+
+/**
+ * State-based components (Input, Checkbox)
+ * These have states defined via Tailwind modifiers
+ */
+export interface StateComponentAnalysis extends BaseComponentAnalysis {
+  type: 'state';
+  baseClasses: string[];
+  states: Record<string, StateInfo>;
+}
+
+export interface StateInfo {
+  classes: string[];
+  trigger: string;  // e.g., "focus-visible:", "aria-invalid:", "disabled:"
+}
+
+/**
+ * Simple components with static classes
+ */
+export interface SimpleComponentAnalysis extends BaseComponentAnalysis {
+  type: 'simple';
+  classes: string[];
+  /** JSX tree structure for components with decorative elements */
+  jsxTree?: JsxNode;
+}
+
+/**
+ * Layout information inferred from Tailwind classes
+ */
+export interface LayoutInfo {
+  display: 'flex' | 'grid' | 'block' | 'inline' | 'hidden' | 'table' | 'contents' | null;
+  direction: 'row' | 'col' | null;
+  gap?: number;       // pixels
+  padding?: { x?: number; y?: number; all?: number };
+  alignment?: string; // e.g., 'center', 'start', 'end'
+  justification?: string;
+  wrap?: boolean;
+}
+
+/**
+ * Responsive variant information for a component
+ */
+export interface ResponsiveInfo {
+  /** Classes grouped by breakpoint */
+  breakpoints: Record<string, string[]>;
+  /** Whether the component has responsive visibility changes */
+  hasResponsiveVisibility: boolean;
+}
+
+/**
+ * Color scheme variant information
+ */
+export interface ColorSchemeInfo {
+  light: string[];
+  dark: string[];
+}
+
+export type ComponentAnalysis =
+  | CVAComponentAnalysis
+  | CompoundComponentAnalysis
+  | StateComponentAnalysis
+  | SimpleComponentAnalysis;
+
+// ============================================================================
+// Parsed Tailwind Class Types
+// ============================================================================
+
+export interface ParsedTailwindClass {
+  original: string;       // The full class string
+  modifier?: string;      // Combined modifier string (all stacked modifiers joined)
+  modifiers: string[];    // Individual modifier layers (e.g. ['sm:', 'hover:'])
+  utility: string;        // The actual utility class (after stripping modifiers)
+  value?: string;         // Value if present (e.g., "4" in "p-4")
+  responsive?: string;    // Responsive breakpoint modifier if present (e.g., "sm:")
+  pseudo?: string;        // Pseudo-element/class modifier if present (e.g., "placeholder:")
+  state?: string;         // State modifier if present (e.g., "hover:")
+  isDark?: boolean;       // Whether this class has a dark: modifier
+  opacity?: number;       // Opacity modifier if present (e.g., 50 from "bg-muted/50")
+  arbitrary?: string;     // Arbitrary value if present (e.g., "13px" from "text-[13px]")
+  lineHeight?: string;    // Line-height slash notation (e.g., "6" from "text-sm/6")
+}
+
+export interface ColorMapping {
+  tailwindClass: string;  // e.g., "bg-primary"
+  tokenName: string;      // e.g., "primary"
+  property: 'background' | 'text' | 'border' | 'ring';
+}
+
+export interface SizeMapping {
+  tailwindClass: string;  // e.g., "h-9"
+  property: 'height' | 'width' | 'padding' | 'gap';
+  value: number;          // Value in pixels
+}
+
+// ============================================================================
+// Scanner Configuration
+// ============================================================================
+
+export interface ScannerConfig {
+  /** Paths to scan for components (relative to project root) */
+  componentPaths: string[];
+
+  /** Glob pattern for component files */
+  filePattern: string;
+
+  /** Components to exclude from scanning */
+  exclude: string[];
+
+  /** Design tokens file path */
+  tokensPath?: string;
+
+  /** If true, only include components that have a co-located *.stories.tsx file */
+  onlyWithStories?: boolean;
+
+  /**
+   * npm package names (or prefixes ending with '/') to treat as icon libraries.
+   * Imports from these packages are collected and rendered to SVG for the icon registry.
+   * Prefix matching: 'react-icons/' matches 'react-icons/hi', 'react-icons/fa', etc.
+   * Exact matching: 'lucide-react' matches only 'lucide-react'.
+   * Defaults to ['lucide-react', 'react-icons/'].
+   */
+  iconPackages?: string[];
+}
+
+// ============================================================================
+// Generated Output (for Figma plugin)
+// ============================================================================
+
+export interface ComponentDefinitions {
+  /** Contract/schema version for plugin compatibility checks. */
+  schemaVersion: number;
+
+  /** Version for cache invalidation */
+  version: string;
+
+  /** When the definitions were generated */
+  generatedAt: string;
+
+  /** All analyzed components */
+  components: EnrichedComponentAnalysis[];
+
+  /** Tailwind spacing scale (px values) */
+  spacingScale: Record<string, number>;
+
+  /** Color token names used in components */
+  colorTokens: string[];
+
+  /** Palette token -> color value map (e.g. "green-600" -> "#16a34a") */
+  paletteTokens?: Record<string, string>;
+
+  /** React icon name -> svg mapping */
+  iconRegistry?: Record<string, IconRegistryEntry>;
+
+  /** Tailwind class -> CSS declaration map */
+  styleMap?: Record<string, StyleRuleEntry[]>;
+}
+
+export interface StyleRuleEntry {
+  declarations: Record<string, string>;
+  media?: string;
+}
+
+export interface IconImportSpec {
+  module: string;
+  exportName: string;
+}
+
+export interface IconRegistryEntry extends IconImportSpec {
+  svg: string;
+}
+
+/**
+ * Enriched component analysis with layout, responsive, and color-scheme info.
+ * Produced by the CLI after scanning.
+ */
+export interface EnrichedComponentAnalysis {
+  /** The base analysis */
+  analysis: ComponentAnalysis;
+  /** Inferred layout from base classes */
+  layout: LayoutInfo;
+  /** Responsive breakpoint groupings */
+  responsive: ResponsiveInfo;
+  /** Light/dark mode class split */
+  colorScheme: ColorSchemeInfo;
+}

package/src/blob-placement.ts

@@ -0,0 +1,111 @@
+export type BlobDimensions = {
+  vectorWidth: number;
+  vectorHeight: number;
+};
+
+export type BlobPlacement = {
+  layoutLeft: number;
+  desiredCenterX: number;
+  desiredCenterY: number;
+  cssRotateDeg: number;
+  topOffset: number;
+  hasTranslateXHalf: boolean;
+};
+
+const LEFT_CALC_REGEX = /^left-\[calc\(50%([+-]\d+(?:\.\d+)?rem)?\)\]$/;
+const WIDTH_REGEX = /^w-(\d+(?:\.\d+)?)$/;
+const ASPECT_REGEX = /^aspect-(\d+)\/(\d+)$/;
+const TOP_REGEX = /^(-?)top-(\d+(?:\.\d+)?)$/;
+const ROTATE_SIMPLE_REGEX = /^(-?)rotate-(\d+(?:\.\d+)?)$/;
+const ROTATE_ARBITRARY_REGEX = /^(-?)rotate-\[(-?\d+(?:\.\d+)?)deg\]$/;
+
+function findLastClass(classes: string[], predicate: (cls: string) => boolean): string | null {
+  for (let i = classes.length - 1; i >= 0; i--) {
+    if (predicate(classes[i])) return classes[i];
+  }
+  return null;
+}
+
+export function parseRotateDegreesFromClasses(classes: string[]): number {
+  for (let i = classes.length - 1; i >= 0; i--) {
+    const cls = classes[i];
+    const simple = cls.match(ROTATE_SIMPLE_REGEX);
+    if (simple) {
+      const sign = simple[1] === '-' ? -1 : 1;
+      return sign * parseFloat(simple[2]);
+    }
+    const arbitrary = cls.match(ROTATE_ARBITRARY_REGEX);
+    if (arbitrary) {
+      const sign = arbitrary[1] === '-' ? -1 : 1;
+      return sign * parseFloat(arbitrary[2]);
+    }
+  }
+  return 0;
+}
+
+export function resolveBlobDimensions(
+  activeClasses: string[],
+  defaults: BlobDimensions = { vectorWidth: 578, vectorHeight: 340 },
+): BlobDimensions {
+  let vectorWidth = defaults.vectorWidth;
+  let vectorHeight = defaults.vectorHeight;
+
+  const widthClass = findLastClass(activeClasses, cls => WIDTH_REGEX.test(cls));
+  if (widthClass) {
+    const widthMatch = widthClass.match(WIDTH_REGEX);
+    if (widthMatch) {
+      vectorWidth = parseFloat(widthMatch[1]) * 4;
+    }
+  }
+
+  const aspectClass = findLastClass(activeClasses, cls => ASPECT_REGEX.test(cls));
+  if (aspectClass) {
+    const aspectMatch = aspectClass.match(ASPECT_REGEX);
+    if (aspectMatch) {
+      const ratio = parseFloat(aspectMatch[1]) / parseFloat(aspectMatch[2]);
+      vectorHeight = vectorWidth / ratio;
+    }
+  }
+
+  return { vectorWidth, vectorHeight };
+}
+
+export function resolveBlobPlacement(
+  activeClasses: string[],
+  containerWidth: number,
+  vectorWidth: number,
+  vectorHeight: number,
+): BlobPlacement {
+  const hasTranslateXHalf = activeClasses.includes('-translate-x-1/2');
+
+  let layoutLeft = 0;
+  const leftClass = findLastClass(activeClasses, cls => LEFT_CALC_REGEX.test(cls));
+  if (leftClass) {
+    const leftMatch = leftClass.match(LEFT_CALC_REGEX);
+    const remOffset = leftMatch && leftMatch[1] ? parseFloat(leftMatch[1]) * 16 : 0;
+    layoutLeft = containerWidth * 0.5 + remOffset;
+  }
+
+  let topOffset = 0;
+  const topClass = findLastClass(activeClasses, cls => TOP_REGEX.test(cls));
+  if (topClass) {
+    const topMatch = topClass.match(TOP_REGEX);
+    if (topMatch) {
+      const sign = topMatch[1] === '-' ? -1 : 1;
+      topOffset = parseFloat(topMatch[2]) * 4 * sign;
+    }
+  }
+
+  const desiredCenterX = hasTranslateXHalf ? layoutLeft : (layoutLeft + vectorWidth / 2);
+  const desiredCenterY = vectorHeight / 2;
+  const cssRotateDeg = parseRotateDegreesFromClasses(activeClasses);
+
+  return {
+    layoutLeft,
+    desiredCenterX,
+    desiredCenterY,
+    cssRotateDeg,
+    topOffset,
+    hasTranslateXHalf,
+  };
+}

package/src/change-detection.ts

@@ -0,0 +1,204 @@
+import { COMPONENT_DEFS } from './tokens';
+import { extractFrameProperties, propsToTailwindClasses } from './tailwind';
+
+interface ComponentFrame {
+  frame: any;
+  componentName: string;
+  variant: string;
+  state: string;
+  props: any;
+}
+
+interface ChangeDetail {
+  property: string;
+  figma: string;
+  code: string;
+  newClasses: string[];
+}
+
+interface ComponentChange {
+  name: string;
+  type: string;
+  file: string;
+  changes: ChangeDetail[];
+  figmaProps: any;
+  suggestedClasses: string[];
+}
+
+interface ClassUpdate {
+  property: string;
+  remove: string[];
+  add: string[];
+}
+
+interface ComponentPatch {
+  component: string;
+  file: string;
+  classUpdates: ClassUpdate[];
+}
+
+export function findComponentFrames(): ComponentFrame[] {
+  let dsPage: any = null;
+  for (let i = 0; i < (figma as any).root.children.length; i++) {
+    if ((figma as any).root.children[i].name === 'Design System') {
+      dsPage = (figma as any).root.children[i];
+      break;
+    }
+  }
+
+  if (!dsPage) {
+    return [];
+  }
+
+  const components: ComponentFrame[] = [];
+
+  // Find component frames by name pattern: "ComponentName/variant/state" or "ComponentName States"
+  function searchFrames(node: any, depth: number): void {
+    if (depth > 5) return; // Limit depth
+
+    if (node.type === 'FRAME' || node.type === 'COMPONENT') {
+      // Check if this looks like a component instance
+      const nameParts = node.name.split('/');
+      if (nameParts.length >= 2) {
+        // This is a variant frame like "Button/default/hover"
+        components.push({
+          frame: node,
+          componentName: nameParts[0],
+          variant: nameParts[1],
+          state: nameParts[2] || 'default',
+          props: extractFrameProperties(node)
+        });
+      }
+    }
+
+    if ('children' in node) {
+      for (let i = 0; i < node.children.length; i++) {
+        searchFrames(node.children[i], depth + 1);
+      }
+    }
+  }
+
+  searchFrames(dsPage, 0);
+  return components;
+}
+
+/**
+ * Compare Figma component properties with code definitions
+ * Returns list of changed components with their differences
+ */
+export function detectComponentChanges(): { changes?: ComponentChange[]; error?: string } {
+  const figmaComponents = findComponentFrames();
+  const changes: ComponentChange[] = [];
+
+  // Group Figma frames by component name
+  const figmaByComponent: Record<string, ComponentFrame[]> = {};
+  for (let i = 0; i < figmaComponents.length; i++) {
+    const comp = figmaComponents[i];
+    if (!figmaByComponent[comp.componentName]) {
+      figmaByComponent[comp.componentName] = [];
+    }
+    figmaByComponent[comp.componentName].push(comp);
+  }
+
+  // Compare with code definitions
+  if (!COMPONENT_DEFS || !(COMPONENT_DEFS as any).components) {
+    return { error: 'No component definitions loaded. Start dev server and refresh.' };
+  }
+
+  for (let j = 0; j < (COMPONENT_DEFS as any).components.length; j++) {
+    const codeDef = (COMPONENT_DEFS as any).components[j];
+    const figmaFrames = figmaByComponent[codeDef.name] || [];
+
+    if (figmaFrames.length === 0) {
+      continue; // Component not found in Figma
+    }
+
+    // Get the first frame as representative (usually default state)
+    const figmaFrame = figmaFrames[0];
+    const figmaProps = figmaFrame.props;
+    const figmaClasses = propsToTailwindClasses(figmaProps);
+
+    // Get code classes
+    let codeClasses: string[] = [];
+    if (codeDef.type === 'cva' && codeDef.baseClasses) {
+      codeClasses = codeDef.baseClasses;
+    } else if (codeDef.type === 'state' && codeDef.baseClasses) {
+      codeClasses = codeDef.baseClasses;
+    } else if (codeDef.type === 'simple' && codeDef.classes) {
+      codeClasses = codeDef.classes;
+    }
+
+    // Find spacing/radius classes in code
+    const codeSpacingClasses = codeClasses.filter(function(cls: string) {
+      return /^(p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|rounded)/.test(cls);
+    });
+
+    // Compare
+    let hasChanges = false;
+    const changeDetails: ChangeDetail[] = [];
+
+    // Check padding changes
+    const figmaPadding = figmaClasses.filter(function(c: string) { return c.startsWith('p'); });
+    const codePadding = codeSpacingClasses.filter(function(c: string) { return c.startsWith('p'); });
+
+    if (figmaPadding.join(' ') !== codePadding.join(' ')) {
+      hasChanges = true;
+      changeDetails.push({
+        property: 'padding',
+        figma: figmaPadding.join(' ') || 'none',
+        code: codePadding.join(' ') || 'none',
+        newClasses: figmaPadding
+      });
+    }
+
+    // Check radius changes
+    const figmaRadius = figmaClasses.filter(function(c: string) { return c.startsWith('rounded'); });
+    const codeRadius = codeSpacingClasses.filter(function(c: string) { return c.startsWith('rounded'); });
+
+    if (figmaRadius.join(' ') !== codeRadius.join(' ')) {
+      hasChanges = true;
+      changeDetails.push({
+        property: 'borderRadius',
+        figma: figmaRadius.join(' ') || 'none',
+        code: codeRadius.join(' ') || 'none',
+        newClasses: figmaRadius
+      });
+    }
+
+    if (hasChanges) {
+      changes.push({
+        name: codeDef.name,
+        type: codeDef.type,
+        file: codeDef.file,
+        changes: changeDetails,
+        figmaProps: figmaProps,
+        suggestedClasses: figmaClasses
+      });
+    }
+  }
+
+  return { changes: changes };
+}
+
+/**
+ * Generate code patch for a component
+ * Returns the class changes that need to be made
+ */
+export function generateComponentPatch(componentChange: ComponentChange): ComponentPatch {
+  const patch: ComponentPatch = {
+    component: componentChange.name,
+    file: componentChange.file,
+    classUpdates: []
+  };
+
+  for (let i = 0; i < componentChange.changes.length; i++) {
+    const change = componentChange.changes[i];
+    patch.classUpdates.push({
+      property: change.property,
+      remove: change.code.split(' ').filter(Boolean),
+      add: change.newClasses
+    });
+  }
+
+  return patch;
+}