view-contracts 0.3.5 → 0.4.0

package/renderers/swiftui/README.md

@@ -1,15 +1,53 @@
-# SwiftUI renderer scaffold
+# SwiftUI Renderer
 
-**Not implemented yet** beyond theme / screen stubs. View IR lowering and modifier emission are future work.
+Compiles View IR into native SwiftUI code at build time.
 
-SwiftUI `ViewModifier` chains are **compositional** (not CSS-style override). view-contracts may later introduce a separate **modifier pipeline** concept (wrapper-style transforms, analogous to nested HTML layout shells) — that is **out of scope for the current phase**. When styling is implemented, defaults + variant + instance props will be **folded at compile time** into resolved values, not chained for cascade-like override. See [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) § Native renderers.
+## Capabilities
 
-- Maps: `elements.yaml`, `properties.yaml` (hand-maintained under this directory)
-- Routes: `routes.yaml`
-- Templates: `templates/`
-- Theme codegen spec: [../NATIVE_THEME_EMIT.md](../NATIVE_THEME_EMIT.md)
+- **Full DSL element coverage** — all core elements (Box, Stack, Row, Table, Form, Button, Text, etc.) map to SwiftUI views via `elements.yaml`
+- **Theme codegen** — `VcTheme.swift` is generated from the design token / theme IR, supporting static and dynamic variant resolution
+- **Modifier cascade** — DSL visual properties are folded at compile time into SwiftUI modifier chains following the correct order: foreground/font → padding → background → clipShape → shadow → overlay → frame → opacity
+- **Padding shorthand** — `"24px 18px"` style shorthand is parsed into `.padding(.vertical, N)` + `.padding(.horizontal, N)`
+- **Dynamic variants** — `IrConcat` expressions (e.g. `` `badge-${row.statusTone}` ``) are lowered to runtime `VcTheme.resolve()` calls with a pre-built theme dictionary
+- **Table layout** — `Table` / `TableHeader` / `TableRow` / `TableColumn` / `TableCell` with fixed widths, flex columns, and configurable `separator` / `separatorColor`
+- **justify="between"** — `Row` elements with `justify="between"` emit `Spacer()` between children
+- **Mock data SSoT** — `mock.yaml` is converted to `SampleData.json` and bundled into the Xcode project; Swift ViewModels decode via `JSONDecoder` (no hand-written sample data)
 
-Implement SwiftUI code generation by reading View IR + renderer maps.
-Theme is emitted at build time via `src/design/emit/swiftui.ts` and `templates/theme/*.hbs` — same Token IR + Theme IR as React `theme.css`, not runtime JSON.
+## Files
 
-Extend vocabulary via `spec/ui-dsl.schema.json` (from `ui-dsl-*.csv`), then update renderer maps.
+| File | Role |
+|---|---|
+| `elements.yaml` | DSL element → SwiftUI view mapping |
+| `elementMap.ts` | TypeScript loader for elements.yaml |
+| `renderRuntime.ts` | Build orchestrator (theme, components, sample data JSON) |
+| `renderComponents.ts` | Entry point for per-component Swift file generation |
+| `renderTheme.ts` | `VcTheme.swift` generator (variant dictionary + `applyVcStyle`) |
+| `lowering/lowerToSwiftUI.ts` | IR → SwiftUI body code |
+| `lowering/modifiers.ts` | Visual property set → SwiftUI modifier chain |
+| `templates/` | Handlebars templates for boilerplate Swift files |
+
+## Usage
+
+Generated files are placed in `<project>/generated/swiftui/` during `view-contracts build`:
+
+```
+generated/swiftui/
+├── VcTheme.swift                    # Theme + variant dictionary
+├── AdminDashboard.generated.swift   # Screen view
+├── KpiCard.generated.swift          # Partial views
+├── ...
+└── AdminDashboard.SampleData.json   # Mock data from YAML SSoT
+```
+
+## iOS Preview App
+
+See `examples/admin-dashboard/ios-preview/` for a working SwiftUI preview app:
+
+```bash
+cd examples/admin-dashboard/ios-preview
+xcodegen generate   # generates .xcodeproj from project.yml
+# Open VcPreview.xcodeproj in Xcode, or build from CLI:
+xcodebuild -scheme VcPreview -destination 'platform=iOS Simulator,...' build
+```
+
+The preview app loads `SampleData.json` from the bundle and decodes it into typed `Codable` ViewModels.

package/renderers/swiftui/elementMap.ts

@@ -0,0 +1,45 @@
+import { resolve } from 'node:path';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+import { loadYamlFile } from '../../src/renderer/elementMapValidation.js';
+
+export interface SwiftUIElementConfig {
+  container?: 'group' | 'vstack' | 'hstack' | 'navstack' | 'scrollview' | 'field' | 'cellgroup' | 'tablestack';
+  leaf?: 'text' | 'button' | 'textfield' | 'texteditor' | 'picker' | 'spacer' | 'divider' | 'image' | 'progressview' | 'toggle';
+  spacingProp?: string;
+}
+
+export interface SwiftUIElementMap {
+  elements: Record<string, SwiftUIElementConfig>;
+}
+
+const SOURCE_LABEL = 'renderers/swiftui/elements.yaml';
+
+let cachedMap: SwiftUIElementMap | null = null;
+
+function validateSwiftUIElementMap(map: SwiftUIElementMap): void {
+  for (const [name, entry] of Object.entries(map.elements)) {
+    const hasContainer = entry.container !== undefined && entry.container !== null;
+    const hasLeaf = entry.leaf !== undefined && entry.leaf !== null;
+    if (hasContainer === hasLeaf) {
+      throw new Error(
+        `${SOURCE_LABEL}: element "${name}" must have exactly one of "container" or "leaf"`,
+      );
+    }
+    if ((entry.container === 'vstack' || entry.container === 'hstack') && entry.spacingProp === undefined) {
+      // spacingProp is optional for hstack/vstack containers without a DSL gap prop (e.g. TableHeader)
+    }
+  }
+}
+
+export async function loadSwiftUIElementMap(customPath?: string): Promise<SwiftUIElementMap> {
+  if (!customPath && cachedMap) return cachedMap;
+  const mapPath = customPath ?? resolve(packageRoot(), 'renderers/swiftui/elements.yaml');
+  const raw = await loadYamlFile<SwiftUIElementMap>(mapPath);
+  validateSwiftUIElementMap(raw);
+  if (!customPath) cachedMap = raw;
+  return raw;
+}
+
+export function isSwiftUIVocabulary(name: string, map: SwiftUIElementMap, allowlistExtra: string[] = []): boolean {
+  return name in map.elements && !allowlistExtra.includes(name);
+}

package/renderers/swiftui/elements.yaml

@@ -0,0 +1,82 @@
+# SwiftUI renderer element map — maps DSL elements to SwiftUI views.
+
+elements:
+  Page:
+    container: navstack
+  Box:
+    container: group
+  Stack:
+    container: vstack
+    spacingProp: gap
+  Row:
+    container: hstack
+    spacingProp: gap
+  Column:
+    container: vstack
+    spacingProp: gap
+  Text:
+    leaf: text
+  Button:
+    leaf: button
+  Form:
+    container: vstack
+    spacingProp: gap
+  Field:
+    container: field
+  TextInput:
+    leaf: textfield
+  TextArea:
+    leaf: texteditor
+  Select:
+    leaf: picker
+  Table:
+    container: tablestack
+  TableHeader:
+    container: hstack
+  TableColumn:
+    container: cellgroup
+  TableRow:
+    container: hstack
+  TableCell:
+    container: cellgroup
+  Spacer:
+    leaf: spacer
+  Divider:
+    leaf: divider
+  Image:
+    leaf: image
+  Icon:
+    leaf: image
+  ScrollArea:
+    container: scrollview
+  List:
+    container: vstack
+    spacingProp: gap
+  ListItem:
+    container: group
+  Link:
+    leaf: text
+  Modal:
+    container: group
+  Progress:
+    leaf: progressview
+  Checkbox:
+    leaf: toggle
+  Switch:
+    leaf: toggle
+  Radio:
+    leaf: picker
+  IconButton:
+    leaf: button
+  Badge:
+    leaf: text
+  Chip:
+    leaf: text
+  Avatar:
+    leaf: image
+  Card:
+    container: group
+  SafeArea:
+    container: group
+  App:
+    container: group

package/renderers/swiftui/index.ts

@@ -0,0 +1,5 @@
+export { loadSwiftUIElementMap, isSwiftUIVocabulary } from './elementMap.js';
+export type { SwiftUIElementConfig, SwiftUIElementMap } from './elementMap.js';
+export { renderSwiftComponent } from './renderComponents.js';
+export { mergeVisualProps } from '../../src/renderer/style/mergeVisualProps.js';
+export { visualPropSetToModifiers } from './lowering/modifiers.js';