view-contracts 0.3.5 → 0.4.1

package/renderers/react/preview/vocabulary.tsx

@@ -0,0 +1,75 @@
+/**
+ * Preview vocabulary stubs — React components for authoring/preview only.
+ * Production apps use compile-time HTML lowering (lowerToJsx), not these stubs.
+ *
+ * All element names and style property lists come from dsl-catalog (SSoT).
+ */
+import type { FormEvent, ReactElement, ReactNode } from 'react';
+import { dispatchPreviewAction } from '../runtime/actionRuntime.js';
+import { isHidden, toneClass } from '../runtime/style.js';
+import { foldLiteralsToCss } from '../style/foldLiterals.js';
+import { ELEMENT_CATALOG, LOWERING_STYLE_PROPERTIES } from '../../../src/schema/dsl-catalog.js';
+import type { Action } from '../runtime/types.js';
+
+function componentToKebab(name: string): string {
+  return name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+function previewClassName(elementName: string, props: Record<string, unknown>): string {
+  const kebab = componentToKebab(elementName);
+  const parts = [`vc-${kebab}`];
+  if (typeof props.level === 'number') {
+    parts.push(`vc-${kebab}-${props.level}`);
+  }
+  const variant = props.variant ?? props.tone;
+  if (typeof variant === 'string') {
+    parts.push(`vc-${kebab}--${variant}`);
+    if (props.tone) parts.push(toneClass(variant));
+  }
+  return parts.join(' ');
+}
+
+function previewStyleProps(props: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (LOWERING_STYLE_PROPERTIES.has(key)) out[key] = value;
+  }
+  return out;
+}
+
+function vocabularyStub(elementName: string) {
+  return function VocabularyElement(props: Record<string, unknown>): ReactElement | null {
+    if (isHidden(props)) return null;
+    const { children, action, onClick, onSubmit, label } = props;
+    const clickAction = (action ?? onClick) as Action | undefined;
+    const submitAction = (action ?? onSubmit) as Action | undefined;
+    const onClickHandler = clickAction
+      ? () => { void dispatchPreviewAction(clickAction); }
+      : undefined;
+    const onSubmitHandler = submitAction
+      ? (event: FormEvent<HTMLDivElement>) => {
+          event.preventDefault();
+          void dispatchPreviewAction(submitAction);
+        }
+      : undefined;
+    const content = (children as ReactNode) ?? (typeof label === 'string' ? label : null);
+    const inlineStyle = foldLiteralsToCss(previewStyleProps(props));
+    return (
+      <div
+        data-vc-element={elementName}
+        className={previewClassName(elementName, props)}
+        style={Object.keys(inlineStyle).length > 0 ? inlineStyle : undefined}
+        onClick={onClickHandler}
+        onSubmit={onSubmitHandler}
+      >
+        {content}
+      </div>
+    );
+  };
+}
+
+/** All vocabulary stubs keyed by element name, derived from ELEMENT_CATALOG. */
+export const vocabularyStubs: Record<string, ReturnType<typeof vocabularyStub>> =
+  Object.fromEntries(
+    Object.keys(ELEMENT_CATALOG).map((name) => [name, vocabularyStub(name)]),
+  );

package/renderers/react/runtime/structural.css

@@ -0,0 +1,38 @@
+/* DSL structural layer — layout/control mechanics only; no visual token values. */
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--ui-bg); color: var(--ui-text); font-family: var(--ui-font); font-size: var(--ui-space-font-body); }
+button, input, textarea, select { font: inherit; }
+
+.vc-page { min-height: 100vh; min-width: 0; }
+.vc-box { display: block; min-width: 0; }
+.vc-column { display: flex; flex-direction: column; min-width: 0; }
+.vc-stack { display: flex; flex-direction: column; min-width: 0; }
+.vc-row { display: flex; flex-direction: row; min-width: 0; }
+.vc-wrap { flex-wrap: wrap; }
+.vc-spacer { min-width: 0; min-height: 0; }
+
+.vc-heading { margin: 0; line-height: 1.2; letter-spacing: -0.02em; }
+.vc-text { margin: 0; line-height: 1.6; }
+.vc-link { color: var(--ui-primary); text-decoration: none; }
+.vc-link:hover { text-decoration: underline; }
+.vc-divider { border: 0; border-top: 1px solid var(--ui-border); width: 100%; }
+
+.vc-button { border: 0; cursor: pointer; }
+
+.vc-form { display: flex; flex-direction: column; min-width: 0; }
+.vc-field { display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+
+.vc-text-input, .vc-text-area, .vc-select { outline: none; }
+.vc-text-input:focus, .vc-text-area:focus, .vc-select:focus { border-color: var(--ui-primary); box-shadow: 0 0 0 3px var(--ui-primary-weak); }
+.vc-select { appearance: none; -webkit-appearance: none; -moz-appearance: none; cursor: pointer; background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M4 6l4 4 4-4' stroke='%236b7280' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E"); background-repeat: no-repeat; background-position: right 12px center; background-size: 16px; }
+.vc-text-area { resize: vertical; }
+
+.vc-checkbox { display: inline-flex; align-items: center; gap: 8px; }
+.vc-list { margin: 0; padding-left: 20px; }
+.vc-list-item { margin: 0; padding: 2px 0; }
+
+.vc-table { width: 100%; display: flex; flex-direction: column; min-width: 0; }
+.vc-table-header { display: flex; align-items: center; min-width: 0; }
+.vc-table-column { display: flex; align-items: center; text-align: left; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+.vc-table-row { display: flex; align-items: center; border-top: 1px solid var(--ui-border); min-width: 0; }
+.vc-table-cell { display: flex; align-items: center; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0; }

package/renderers/react/style/foldLiterals.ts

@@ -39,13 +39,23 @@ export function foldLiteralsToCss(literals: Record<string, unknown>): FoldedCss
   const style: FoldedCss = {};
   const width = literals.width;
   if (typeof width === 'number') style.width = len(width);
-  else if (typeof width === 'string' && width !== 'wrap' && width !== 'fill') style.width = width;
+  else if (width === 'fill') style.width = '100%';
+  else if (typeof width === 'string' && width !== 'wrap') style.width = width;
 
   if (typeof literals.minWidth === 'number') style.minWidth = len(literals.minWidth);
-  if (typeof literals.maxWidth === 'number') style.maxWidth = len(literals.maxWidth);
-  if (typeof literals.height === 'number') style.height = len(literals.height);
+  const maxWidth = literals.maxWidth;
+  if (typeof maxWidth === 'number') style.maxWidth = len(maxWidth);
+  else if (maxWidth === 'fill') style.maxWidth = '100%';
+
+  const height = literals.height;
+  if (typeof height === 'number') style.height = len(height);
+  else if (height === 'fill') style.height = '100%';
+  else if (typeof height === 'string' && height !== 'wrap') style.height = height;
+
   if (typeof literals.minHeight === 'number') style.minHeight = len(literals.minHeight);
-  if (typeof literals.maxHeight === 'number') style.maxHeight = len(literals.maxHeight);
+  const maxHeight = literals.maxHeight;
+  if (typeof maxHeight === 'number') style.maxHeight = len(maxHeight);
+  else if (maxHeight === 'fill') style.maxHeight = '100%';
   if (literals.aspectRatio !== undefined) style.aspectRatio = String(literals.aspectRatio);
 
   const weight = literals.weight;
@@ -116,6 +126,17 @@ export function foldLiteralsToCss(literals: Record<string, unknown>): FoldedCss
     if (mapped) style.justifyContent = mapped;
   }
 
+  if (typeof literals.display === 'string') style.display = literals.display;
+  if (typeof literals.gridTemplateColumns === 'string') style.gridTemplateColumns = literals.gridTemplateColumns;
+  if (typeof literals.flexDirection === 'string') style.flexDirection = literals.flexDirection;
+  if (typeof literals.alignItems === 'string') style.alignItems = literals.alignItems;
+
+  const borderColor = literals.borderColor;
+  if (typeof borderColor === 'string') style.borderColor = tokenRefToCssVar(borderColor) ?? borderColor;
+
+  const flex = literals.flex;
+  if (typeof flex === 'number') style.flex = flex;
+
   return style;
 }
 

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';