@dannote/figma-use 0.5.0 → 0.5.2

package/packages/cli/src/render/component-set.tsx

@@ -0,0 +1,138 @@
+/**
+ * ComponentSet (variants) support
+ * 
+ * ## How ComponentSet works in Figma's multiplayer protocol
+ * 
+ * ComponentSet is NOT a separate node type - it's a FRAME with special fields:
+ *   - type = FRAME (4)
+ *   - isStateGroup = true (field 225)
+ *   - stateGroupPropertyValueOrders (field 238) = [{property: "variant", values: ["A", "B"]}]
+ * 
+ * Children are SYMBOL (Component) nodes with names like "variant=Primary, size=Large".
+ * Figma auto-generates componentPropertyDefinitions from these names.
+ * 
+ * ## Why Instances are created via Plugin API
+ * 
+ * IMPORTANT: Instance nodes with symbolData.symbolID CANNOT be created via multiplayer
+ * when linking to components in the same batch. Figma reassigns GUIDs on receive,
+ * breaking the symbolID references.
+ * 
+ * Example: We send SYMBOL with localID=100, Instance with symbolData.symbolID=100.
+ * Figma receives and assigns new IDs: SYMBOL becomes 200, but Instance still
+ * references 100 → broken link.
+ * 
+ * This works for defineComponent() because Component and first Instance are adjacent
+ * in the node tree, but fails for ComponentSet where variant components are created
+ * first, then instances are created as siblings of the ComponentSet.
+ * 
+ * Solution: Create the ComponentSet and variant Components via multiplayer (fast),
+ * then create Instances via Plugin API in trigger-layout (correct linking).
+ * The pendingComponentSetInstances array passes instance specs to the plugin.
+ * 
+ * Discovered through protocol sniffing - see scripts/sniff-ws.ts
+ */
+
+import * as React from 'react'
+
+type VariantDef = Record<string, readonly string[]>
+type VariantProps<V extends VariantDef> = { [K in keyof V]: V[K][number] }
+
+interface ComponentSetDef<V extends VariantDef> {
+  name: string
+  variants: V
+  render: (props: VariantProps<V>) => React.ReactElement
+  symbol: symbol
+}
+
+const componentSetRegistry = new Map<symbol, ComponentSetDef<VariantDef>>()
+
+export function resetComponentSetRegistry() {
+  componentSetRegistry.clear()
+}
+
+export function getComponentSetRegistry() {
+  return componentSetRegistry
+}
+
+/**
+ * Define a component with variants (ComponentSet)
+ * 
+ * @example
+ * const Button = defineComponentSet('Button', {
+ *   variant: ['Primary', 'Secondary'] as const,
+ *   size: ['Small', 'Large'] as const,
+ * }, ({ variant, size }) => (
+ *   <Frame style={{ padding: size === 'Large' ? 16 : 8 }}>
+ *     <Text>{variant}</Text>
+ *   </Frame>
+ * ))
+ * 
+ * <Button variant="Primary" size="Large" />
+ */
+export function defineComponentSet<V extends VariantDef>(
+  name: string,
+  variants: V,
+  render: (props: VariantProps<V>) => React.ReactElement
+): React.FC<Partial<VariantProps<V>> & { style?: Record<string, unknown> }> {
+  const sym = Symbol(name)
+  componentSetRegistry.set(sym, { name, variants, render, symbol: sym } as ComponentSetDef<VariantDef>)
+  
+  const VariantInstance: React.FC<Partial<VariantProps<V>> & { style?: Record<string, unknown> }> = (props) => {
+    const { style, ...variantProps } = props
+    return React.createElement('__component_set_instance__', {
+      __componentSetSymbol: sym,
+      __componentSetName: name,
+      __variantProps: variantProps,
+      style,
+    })
+  }
+  VariantInstance.displayName = name
+  
+  return VariantInstance
+}
+
+/**
+ * Generate all variant combinations
+ */
+export function generateVariantCombinations<V extends VariantDef>(
+  variants: V
+): Array<VariantProps<V>> {
+  const keys = Object.keys(variants) as (keyof V)[]
+  if (keys.length === 0) return [{}] as Array<VariantProps<V>>
+  
+  const result: Array<VariantProps<V>> = []
+  
+  function combine(index: number, current: Partial<VariantProps<V>>) {
+    if (index === keys.length) {
+      result.push(current as VariantProps<V>)
+      return
+    }
+    
+    const key = keys[index]
+    for (const value of variants[key]) {
+      combine(index + 1, { ...current, [key]: value })
+    }
+  }
+  
+  combine(0, {})
+  return result
+}
+
+/**
+ * Build variant name string for Figma component (e.g., "variant=Primary, size=Large")
+ */
+export function buildVariantName(props: Record<string, string>): string {
+  return Object.entries(props)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(', ')
+}
+
+/**
+ * Build stateGroupPropertyValueOrders for ComponentSet
+ */
+export function buildStateGroupPropertyValueOrders(variants: VariantDef): Array<{property: string, values: string[]}> {
+  return Object.entries(variants).map(([property, values]) => ({
+    property,
+    values: [...values]
+  }))
+}

package/packages/cli/src/render/components.tsx

@@ -0,0 +1,155 @@
+/**
+ * Figma-like React components
+ * 
+ * API inspired by react-figma but outputs JSON instead of Figma nodes
+ */
+
+import * as React from 'react'
+
+// Re-export defineVars for use in .figma.tsx files
+export { 
+  defineVars, 
+  figmaVar, 
+  isVariable, 
+  loadVariablesIntoRegistry,
+  isRegistryLoaded,
+  type FigmaVariable 
+} from './vars.ts'
+
+// Component registry - tracks defined components and their instances
+interface ComponentDef {
+  name: string
+  element: React.ReactElement
+  guid?: string // Set after first render creates the component
+}
+
+const componentRegistry = new Map<symbol, ComponentDef>()
+
+export function resetComponentRegistry() {
+  componentRegistry.clear()
+}
+
+export function getComponentRegistry() {
+  return componentRegistry
+}
+
+/**
+ * Define a reusable Figma component
+ * 
+ * @example
+ * const Button = defineComponent('Button',
+ *   <Frame style={{ padding: 12, backgroundColor: "#3B82F6" }}>
+ *     <Text style={{ color: "#FFF" }}>Click</Text>
+ *   </Frame>
+ * )
+ * 
+ * export default () => (
+ *   <Frame>
+ *     <Button />
+ *     <Button />
+ *   </Frame>
+ * )
+ */
+export function defineComponent<P extends BaseProps = BaseProps>(
+  name: string,
+  element: React.ReactElement
+): React.FC<P> {
+  const sym = Symbol(name)
+  componentRegistry.set(sym, { name, element })
+  
+  // Return a component that renders as a special marker
+  const ComponentInstance: React.FC<P> = (props) => {
+    return React.createElement('__component_instance__', {
+      __componentSymbol: sym,
+      __componentName: name,
+      ...props,
+    })
+  }
+  ComponentInstance.displayName = name
+  
+  return ComponentInstance
+}
+
+// Style types
+interface Style {
+  width?: number | string
+  height?: number | string
+  x?: number
+  y?: number
+  flexDirection?: 'row' | 'column'
+  justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between'
+  alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch'
+  gap?: number
+  padding?: number
+  paddingTop?: number
+  paddingRight?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  backgroundColor?: string
+  opacity?: number
+  borderRadius?: number
+  borderTopLeftRadius?: number
+  borderTopRightRadius?: number
+  borderBottomLeftRadius?: number
+  borderBottomRightRadius?: number
+  borderWidth?: number
+  borderColor?: string
+}
+
+interface TextStyle extends Style {
+  fontSize?: number
+  fontFamily?: string
+  fontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
+  fontStyle?: 'normal' | 'italic'
+  color?: string
+  textAlign?: 'left' | 'center' | 'right'
+  lineHeight?: number
+  letterSpacing?: number
+}
+
+interface BaseProps {
+  name?: string
+  style?: Style
+  children?: React.ReactNode
+}
+
+interface TextProps extends Omit<BaseProps, 'style'> {
+  style?: TextStyle
+}
+
+interface StarProps extends BaseProps {
+  pointCount?: number
+}
+
+interface PolygonProps extends BaseProps {
+  pointCount?: number
+}
+
+interface InstanceProps extends BaseProps {
+  componentId?: string
+}
+
+// Component factory - creates intrinsic element wrapper
+const c = <T extends BaseProps>(type: string): React.FC<T> => 
+  (props) => React.createElement(type, props)
+
+// Components
+export const Frame = c<BaseProps>('frame')
+export const Rectangle = c<BaseProps>('rectangle')
+export const Ellipse = c<BaseProps>('ellipse')
+export const Text = c<TextProps>('text')
+export const Line = c<BaseProps>('line')
+export const Star = c<StarProps>('star')
+export const Polygon = c<PolygonProps>('polygon')
+export const Vector = c<BaseProps>('vector')
+export const Component = c<BaseProps>('component')
+export const Instance = c<InstanceProps>('instance')
+export const Group = c<BaseProps>('group')
+export const Page = c<BaseProps>('page')
+export const View = Frame
+
+// All component names for JSX transform
+export const INTRINSIC_ELEMENTS = [
+  'Frame', 'Rectangle', 'Ellipse', 'Text', 'Line', 'Star', 
+  'Polygon', 'Vector', 'Component', 'Instance', 'Group', 'Page', 'View'
+] as const

package/packages/cli/src/render/index.ts

@@ -0,0 +1,47 @@
+/**
+ * React → Figma Renderer
+ */
+
+export { 
+  renderToNodeChanges, 
+  resetRenderedComponents,
+  getPendingComponentSetInstances,
+  clearPendingComponentSetInstances,
+  type RenderOptions, 
+  type RenderResult,
+  type PendingComponentSetInstance,
+} from './reconciler.ts'
+export { 
+  Frame, 
+  Rectangle, 
+  Ellipse, 
+  Text, 
+  Line, 
+  Star, 
+  Polygon, 
+  Vector,
+  Component,
+  Instance,
+  Group,
+  Page,
+  View,
+  INTRINSIC_ELEMENTS,
+  // Variable bindings (StyleX-inspired)
+  defineVars,
+  figmaVar,
+  isVariable,
+  loadVariablesIntoRegistry,
+  isRegistryLoaded,
+  type FigmaVariable,
+  // Component definitions
+  defineComponent,
+  resetComponentRegistry,
+  getComponentRegistry,
+} from './components.tsx'
+
+export {
+  // ComponentSet (variants)
+  defineComponentSet,
+  resetComponentSetRegistry,
+  getComponentSetRegistry,
+} from './component-set.tsx'