@jay-framework/jay-stack-cli 0.12.0 → 0.13.0

package/lib/vendors/figma/README.md

@@ -0,0 +1,396 @@
+# Figma Vendor
+
+Converts Figma documents to Jay HTML with full contract binding support.
+
+## Overview
+
+The Figma vendor implements the complete conversion pipeline from Figma design documents to Jay-HTML, handling:
+
+- **Data bindings** - Contract tags bound to UI elements
+- **Interactive refs** - Button clicks, input fields, etc.
+- **Attribute bindings** - src, value, href, etc.
+- **Variant permutations** - Figma component variants to Jay if conditions
+- **Repeater contexts** - forEach loops with proper path scoping
+- **Plugin contracts** - Multi-component plugin support
+
+## Architecture
+
+### Conversion Pipeline
+
+```
+FigmaVendorDocument
+    ↓
+1. Extract bindings from pluginData
+    ↓
+2. Analyze bindings (type, paths, context)
+    ↓
+3. Validate binding rules
+    ↓
+4. Route to appropriate converter
+    ↓
+   - Repeater → convertRepeaterNode()
+   - Variant → convertVariantNode()
+   - Regular → convertRegularNode()
+    ↓
+Jay-HTML output
+```
+
+### Key Files
+
+- **`index.ts`** - Main vendor implementation, conversion pipeline
+- **`binding-analysis.ts`** - Binding analysis, path resolution, validation
+- **`types.ts`** - Type definitions for bindings and context
+- **`utils.ts`** - CSS conversion utilities
+- **`converters/`** - Node-specific converters (text, rectangle, etc.)
+- **`pageContractPath.ts`** - Contract path utilities
+
+## Binding Types
+
+### 1. Dynamic Content (Data)
+
+**Figma Binding:**
+
+```json
+{
+  "tagPath": ["productPage", "name"],
+  "pageContractPath": { ... }
+}
+```
+
+**Jay-HTML:**
+
+```html
+<div>{productPage.name}</div>
+```
+
+### 2. Interactive Ref
+
+**Figma Binding:**
+
+```json
+{
+  "tagPath": ["submitButton"],
+  "pageContractPath": { ... }
+}
+```
+
+**Jay-HTML:**
+
+```html
+<button ref="submitButton">Submit</button>
+```
+
+### 3. Dual Binding (Data + Interactive)
+
+**Figma Binding:**
+
+```json
+{
+  "tagPath": ["email"],
+  "pageContractPath": { ... }
+}
+```
+
+**Jay-HTML:**
+
+```html
+<input ref="email" value="{email}" />
+```
+
+### 4. Attribute Binding
+
+**Figma Binding:**
+
+```json
+{
+  "tagPath": ["product", "imageUrl"],
+  "attribute": "src",
+  "pageContractPath": { ... }
+}
+```
+
+**Jay-HTML:**
+
+```html
+<img src="{product.imageUrl}" alt="..." />
+```
+
+**Supported Attributes:**
+
+- `src` - Image sources (requires `semanticHtml: 'img'`)
+- `href` - Link destinations (requires `semanticHtml: 'a'`)
+- `value` - Input field values (requires `semanticHtml: 'input'`)
+- `alt` - Image alt text
+- `placeholder` - Input placeholders
+
+#### Image Conversion (Semantic HTML: `img`)
+
+When a node has `semanticHtml: 'img'` in its plugin data:
+
+**Bound Image** (with `src` attribute binding):
+
+```html
+<img src="{productPage.imageUrl}" alt="{productPage.imageAlt}" data-figma-id="..." />
+```
+
+**Static Image** (no bindings, uses Figma fills):
+
+```html
+<img src="/assets/images/product-hero.png" alt="Product Hero" data-figma-id="..." />
+```
+
+For static images, the plugin must export and save the image:
+
+```typescript
+// In plugin serialization for IMAGE fills:
+if (fill.type === 'IMAGE' && fill.imageHash) {
+  const imageBytes = await figma.getImageByHash(fill.imageHash)?.getBytesAsync();
+  if (imageBytes) {
+    const imageUrl = await saveImageToAssets(imageBytes, node.id);
+    serializedFill.imageUrl = imageUrl; // ← Add this!
+  }
+}
+```
+
+### 5. Property Binding (Variants)
+
+**Figma Bindings:**
+
+```json
+[
+  { "property": "mediaType", "tagPath": ["productPage", "mediaType"] },
+  { "property": "selected", "tagPath": ["productPage", "isSelected"] }
+]
+```
+
+**Jay-HTML:**
+
+```html
+<div if="productPage.mediaType == IMAGE && productPage.isSelected == true">
+  <!-- IMAGE + selected variant -->
+</div>
+<div if="productPage.mediaType == VIDEO && productPage.isSelected == true">
+  <!-- VIDEO + selected variant -->
+</div>
+<!-- ... other permutations -->
+```
+
+**Pseudo-CSS Variants:**
+
+Variant values containing `:` (like `image:hover`, `:active`, `:disabled`) are automatically filtered out from Jay-HTML `if` conditions. These are pseudo-CSS class variants that should be handled via CSS display toggling instead:
+
+```css
+/* Pseudo-variant CSS (handled separately, not in conversion) */
+.mediaType_hover {
+  display: none;
+}
+.mediaType:hover .mediaType_hover {
+  display: block;
+}
+```
+
+This filtering prevents invalid expressions like `if="media == image:hover"` from being generated.
+
+### 6. Repeater
+
+**Figma Binding:**
+
+```json
+{
+  "tagPath": ["productPage", "items"],
+  "pageContractPath": { ... }
+}
+```
+
+**Contract:**
+
+```yaml
+- tag: items
+  type: subContract
+  repeated: true
+  trackBy: id
+```
+
+**Jay-HTML:**
+
+```html
+<div forEach="productPage.items" trackBy="id">
+  <div>{title}</div>
+  <!-- Context-relative path -->
+</div>
+```
+
+**Important:** Only the **first child** of a repeater node is converted. This first child serves as the template that gets repeated for each item in the array. Other sibling nodes are ignored as they are not part of the repeater pattern.
+
+## Repeater Context
+
+Repeaters change the path context for their children:
+
+**Full Paths:**
+
+- Repeater: `productPage.products`
+- Child: `productPage.products.title`
+
+**In Jay-HTML:**
+
+```html
+<div forEach="productPage.products" trackBy="id">
+  <div>{title}</div>
+  <!-- Not productPage.products.title -->
+</div>
+```
+
+**Nested Repeaters:**
+
+```html
+<div forEach="compKey.items" trackBy="id">
+  <div forEach="subItems" trackBy="id">
+    <!-- No prefix -->
+    <div>{name}</div>
+    <!-- Relative to subItems -->
+  </div>
+</div>
+```
+
+## Validation Rules
+
+1. **Property bindings are exclusive** - If ANY binding has a property, ALL must have properties
+2. **Attributes + dynamic content allowed** - Multiple attribute bindings + dynamic content is valid
+3. **Interactive must be pure** - Interactive bindings cannot have attribute or property
+4. **One ref per node** - Only one interactive binding per node
+
+## Vendor Document Type
+
+The Figma vendor uses the `FigmaVendorDocument` type defined in `@jay-framework/editor-protocol`. This is the **single source of truth** for the document structure.
+
+### For Figma Plugin Developers
+
+Import the type from the editor protocol:
+
+```typescript
+import { FigmaVendorDocument } from '@jay-framework/editor-protocol';
+
+// Your Figma plugin code
+const vendorDoc: FigmaVendorDocument = {
+  type: selectedNode.type,
+  name: selectedNode.name,
+  children: selectedNode.children,
+  pluginData: {
+    'jpage': 'true',
+    'jay-layer-bindings': JSON.stringify([
+      {
+        pageContractPath: { ... },
+        tagPath: ['productPage', 'name'],
+        jayPageSectionId: '...'
+      }
+    ])
+  },
+  // ... other Figma node properties
+};
+
+await editorProtocol.export({
+  vendorId: 'figma',
+  pageUrl: '/products/:slug',
+  vendorDoc,
+});
+```
+
+### Plugin Data Format
+
+**`jay-layer-bindings`** - Array of LayerBinding:
+
+```typescript
+type LayerBinding = {
+  pageContractPath: PageContractPath;
+  jayPageSectionId: string;
+  tagPath: string[];
+  attribute?: string;
+  property?: string;
+};
+```
+
+**`jpage`** - Marks top-level section as a Jay Page:
+
+```typescript
+pluginData: {
+  'jpage': 'true',
+  'urlRoute': '/products/:slug'
+}
+```
+
+**`semanticHtml`** - Specifies HTML tag:
+
+```typescript
+pluginData: {
+  'semanticHtml': 'img'  // or 'button', 'input', etc.
+}
+```
+
+## Usage Example
+
+```typescript
+import { figmaVendor } from './vendors/figma';
+
+const result = await figmaVendor.convertToBodyHtml(
+  vendorDoc,
+  '/products/:slug',
+  projectPage,
+  plugins,
+);
+
+console.log(result.bodyHtml);
+// <div data-figma-id="...">
+//   <div>{productPage.name}</div>
+//   <img src="{productPage.image}" />
+//   <div forEach="productPage.items" trackBy="id">
+//     <div>{title}</div>
+//   </div>
+// </div>
+```
+
+## Extending the Vendor
+
+### Adding a New Binding Type
+
+1. Update `BindingAnalysis` type in `types.ts`
+2. Add analysis logic in `analyzeBindings()` in `binding-analysis.ts`
+3. Add validation rules in `validateBindings()`
+4. Handle new type in `convertRegularNode()` or create new converter
+
+### Adding Node Type Support
+
+1. Create converter in `converters/` (e.g., `my-node.ts`)
+2. Import and call from `convertRegularNode()` in `index.ts`
+3. Handle node-specific styling in converter
+
+### Extending Path Resolution
+
+Modify `resolveBinding()` in `binding-analysis.ts` to handle:
+
+- New contract sources
+- Custom path transformations
+- Additional context types
+
+## Known Limitations
+
+1. **Variant Components:** Requires `componentPropertyDefinitions` in `FigmaVendorDocument`
+2. **Page Contracts:** Page contract resolution not fully implemented
+3. **Mixed Fonts:** Only single font per text node supported
+4. **Error Recovery:** Logs warnings but doesn't have graceful fallbacks
+
+## Testing
+
+_To be added - See design-log/67 for test plan_
+
+## Design Documentation
+
+See `design-log/67 - Figma Vendor Conversion Algorithm` for:
+
+- Complete design rationale
+- Implementation details
+- Examples and edge cases
+- Trade-off decisions
+
+---
+
+**Last Updated:** January 12, 2026

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,14 +24,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.12.0",
-    "@jay-framework/compiler-shared": "^0.12.0",
-    "@jay-framework/dev-server": "^0.12.0",
-    "@jay-framework/editor-server": "^0.12.0",
-    "@jay-framework/fullstack-component": "^0.12.0",
-    "@jay-framework/logger": "^0.12.0",
-    "@jay-framework/plugin-validator": "^0.12.0",
-    "@jay-framework/stack-server-runtime": "^0.12.0",
+    "@jay-framework/compiler-jay-html": "^0.13.0",
+    "@jay-framework/compiler-shared": "^0.13.0",
+    "@jay-framework/dev-server": "^0.13.0",
+    "@jay-framework/editor-server": "^0.13.0",
+    "@jay-framework/fullstack-component": "^0.13.0",
+    "@jay-framework/logger": "^0.13.0",
+    "@jay-framework/plugin-validator": "^0.13.0",
+    "@jay-framework/stack-server-runtime": "^0.13.0",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -40,7 +40,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.12.0",
+    "@jay-framework/dev-environment": "^0.13.0",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",

package/test/vendors/figma/fixtures/README.md

@@ -0,0 +1,164 @@
+# Figma Vendor Test Fixtures
+
+This directory contains fixture-based integration tests for the Figma vendor converter.
+
+## Structure
+
+Each fixture is a directory containing:
+
+- **`page.figma.json`** - Input Figma document (serialized from Figma plugin)
+- **`page.jay-contract`** - Contract defining data bindings and structure
+- **`expected.jay-html`** - Expected HTML output after conversion
+
+## Current Fixtures
+
+### 1. `basic-text/` ✅ **Working**
+
+Tests basic text rendering with multiple text nodes and font families.
+
+**Features tested:**
+
+- Static text conversion
+- Font family collection (Inter)
+- Font weight and size
+- Text alignment
+- Color conversion
+- Basic FRAME container with children
+
+---
+
+### 2. `button-with-variants/` ✅ **Working**
+
+Tests variant components with multiple properties.
+
+**Features tested:**
+
+- COMPONENT_SET with variants
+- Boolean variants (disabled: true/false)
+- Enum variants (variant: primary/secondary)
+- Property bindings
+- Variant permutation generation
+- Conditional rendering with `if` attributes
+
+---
+
+### 3. `repeater-list/` ✅ **Working**
+
+Tests repeater (forEach) functionality with nested bindings.
+
+**Features tested:**
+
+- Frame with repeater binding
+- `forEach` attribute generation
+- `trackBy` attribute
+- Nested data bindings (items.title, items.description)
+- Repeater context management
+- Sub-contract with repeated items
+
+---
+
+### 4. `complex-page/` ✅ **Working**
+
+Tests a realistic product page with multiple features combined.
+
+**Features tested:**
+
+- Dynamic text content bindings (product.name, product.price)
+- Nested repeater (product.reviews)
+- Parameterized route (/products/:id)
+- Multiple font families (Roboto)
+- Complex contract structure with nested sub-contracts
+
+---
+
+## Adding New Fixtures
+
+1. **Create a directory** under `fixtures/`:
+
+   ```bash
+   mkdir test/vendors/figma/fixtures/my-new-test
+   ```
+
+2. **Add required files**:
+
+   - `page.figma.json` - Figma document structure
+   - `expected.jay-html` - Expected HTML output
+   - `page.jay-contract` OR `page.conf.yaml` - Contract or plugin config
+
+3. **Add fixture content** - You can:
+
+   - Export a real Figma document using the plugin
+   - Hand-craft a test case
+   - Copy and modify an existing fixture
+
+4. **Run the test** to generate `actual-output.jay-html`:
+
+   ```bash
+   npm test -- test/vendors/figma/fixtures.test.ts -t "my-new-test"
+   ```
+
+5. **Review and copy** actual output to `expected.jay-html` if correct
+
+6. **That's it!** The test automatically discovers all fixture directories - no code changes needed!
+
+## Running Tests
+
+Run all fixture tests (auto-discovers all fixture directories):
+
+```bash
+npm test -- test/vendors/figma/fixtures.test.ts
+```
+
+Run a specific fixture (via filtering):
+
+```bash
+npm test -- test/vendors/figma/fixtures.test.ts -t "basic-text"
+```
+
+The test runner **automatically discovers** all directories under `fixtures/` - you don't need to manually register new fixtures!
+
+## Tips
+
+### Debugging Failed Tests
+
+When a test fails, check the `actual-output.jay-html` file saved in the fixture directory.
+
+### Contract Requirements
+
+- Use `type: sub-contract` (not `subContract`)
+- Include all fields referenced by `trackBy` attributes
+- Check console warnings for validation errors
+
+### Normalizing HTML
+
+The test normalizes HTML before comparison to handle:
+
+- Whitespace differences
+- Comment removal
+- Line break variations
+
+## Test Coverage
+
+Current fixtures cover:
+
+- ✅ Static text rendering (basic-text)
+- ✅ Font collection (basic-text)
+- ✅ FRAME containers with layout (basic-text)
+- ✅ Dynamic content bindings (repeater-list, complex-page, plugin-product-card)
+- ✅ Variant components (button-with-variants)
+- ✅ Repeaters with trackBy (repeater-list, complex-page)
+- ✅ Nested sub-contracts (complex-page)
+- ✅ Conditional rendering (button-with-variants)
+- ✅ Plugin-based pages (plugin-product-card)
+- ✅ Headless components (plugin-product-card)
+
+**Current Status:** 5 fixtures fully working (22 passing tests total in vendor suite)
+
+Missing coverage (potential future fixtures):
+
+- ⬜ Interactive bindings (ref)
+- ⬜ Dual bindings (data + interactive)
+- ⬜ Error cases (invalid bindings, missing contracts)
+- ⬜ Images with dynamic src bindings
+- ⬜ Attribute bindings beyond variants
+- ⬜ NPM-installed plugins (currently only local plugins tested)