view-contracts 0.1.0 → 0.3.0

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Contract-first UI design toolchain. Compiles restricted view-contract TSX to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
 
-**Version:** 0.1.0
+**Version:** 0.3.0
 
 ## Table of Contents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-contracts",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
   "type": "module",
   "workspaces": [
@@ -12,7 +12,8 @@
   "files": [
     "dist/view-contracts.bundle.mjs",
     "dist/view-contracts.bundle.mjs.map",
-    "src/renderer/react/runtime",
+    "renderers/react/runtime",
+    "renderers/react/defaults",
     "src/generated/schema",
     "spec",
     "renderers",
@@ -43,7 +44,10 @@
     "contracts:check": "tsx src/cli.ts contracts check -c examples/admin-dashboard/view-contracts.config.yaml",
     "schema:generate": "tsx scripts/schema-generate.ts",
     "cli-contracts:validate": "cli-contracts validate",
-    "test:ci": "node dist/view-contracts.bundle.mjs --version && node dist/view-contracts.bundle.mjs --help",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:smoke": "node dist/view-contracts.bundle.mjs --version && node dist/view-contracts.bundle.mjs --help",
+    "test:ci": "npm run test:unit && npm run build:publish && npm run test:smoke",
     "version": "node -e \"const fs=require('fs');const f='cli-contract.yaml';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace(/^  version: .*/m,'  version: '+process.env.npm_package_version))\" && git add cli-contract.yaml",
     "prepublishOnly": "npm run build:publish && npm run test:ci"
   },
@@ -73,6 +77,7 @@
   },
   "dependencies": {
     "commander": "^14.0.3",
+    "handlebars": "^4.7.9",
     "js-yaml": "^4.1.1",
     "micro-contracts": "^0.17.10",
     "react": "^19.2.0",
@@ -80,6 +85,7 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
+    "@types/handlebars": "^4.1.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.19.21",
     "@types/react": "^19.2.17",
@@ -88,7 +94,11 @@
     "ajv": "^8.18.0",
     "cli-contracts": "^0.33.13",
     "esbuild": "^0.28.0",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.61.0",
+    "pngjs": "^7.0.0",
     "tsx": "^4.21.0",
-    "vite": "^6.4.1"
+    "vite": "^6.4.1",
+    "vitest": "^4.1.9"
   }
 }

package/renderers/compose/templates/Screen.kt.hbs

@@ -0,0 +1,15 @@
+// {{screenName}} — Jetpack Compose scaffold (Phase 5)
+// Theme IR: {{themeJsonPath}}
+// Token IR: {{tokensJsonPath}}
+//
+// TODO(Phase C): Load theme.json and emit Modifier.primaryButton(), vcTextMuted(), etc.
+
+package {{packageName}}
+
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+
+@Composable
+fun {{screenName}}Screen() {
+    Text("{{screenName}} — Compose scaffold")
+}

package/renderers/compose/templates/VcTheme.kt.hbs

@@ -0,0 +1,19 @@
+// VcTheme — Compose theme scaffold (Phase 5)
+// Load Token IR + Theme IR from assets:
+//   {{tokensJsonPath}}
+//   {{themeJsonPath}}
+//
+// TODO(Phase C): Map Theme IR variants to Modifier extensions and ColorScheme.
+
+package {{packageName}}
+
+import android.content.Context
+
+object VcTheme {
+    const val TOKENS_ASSET = "{{tokensJsonPath}}"
+    const val THEME_ASSET = "{{themeJsonPath}}"
+
+    /** Placeholder — read theme.json from assets in Phase C. */
+    fun loadThemeJson(context: Context): String? =
+        context.assets.open(THEME_ASSET).bufferedReader().use { it.readText() }
+}

package/renderers/react/README.md

@@ -3,8 +3,24 @@
 Per-target mapping for view-contracts UI DSL → React.
 
 - `routes.yaml` — generated output file routing
-- `elements.yaml` — element → React component (hand-maintained)
-- `properties.yaml` — property → style/attr (hand-maintained)
+- `elements.yaml` — vocabulary element → HTML tag (SSoT for compile-time lowering)
+- `element-config.meta.json` — shape of `elements.yaml` entries (drives schema codegen)
+- `templates/*.hbs` — Handlebars templates for generated runtime files (dispatch, types, theme, etc.)
+- `renderComponents.ts` / `renderRuntime.ts` — compile-time codegen (IR → JSX, runtime bundle)
+- `lowering/lowerToJsx.ts` — element-map-driven JSX emission
+- `runtime/` — preview/toolchain primitives (style, dispatch) — **not** copied to `generated/`
 
 Vocabulary (elements/properties) is defined in `spec/ui-dsl.schema.json` (from `ui-dsl-*.csv`).
-Sample-only preview helpers (Sidebar, Card, etc.) are **not** part of the vocabulary.
+Preview vocabulary stubs are generated to `src/generated/preview/vocabulary.tsx`.
+Sample-only preview helpers (Sidebar, Card, etc.) are **not** part of the vocabulary — they live in project `src/components/extensions.tsx`.
+
+Generic renderer utilities (template engine, YAML element-map validation) live under `src/renderer/`.
+
+## Compile-time lowering
+
+`renderComponents.ts` reads `elements.yaml` and emits native HTML/JSX into `generated/react/*.generated.tsx`.
+`renderers/react/runtime/` is **not** copied to `generated/`.
+
+## Template customization
+
+Set `rendererTemplatesDir` in `view-contracts.config.yaml` to override default templates.

package/renderers/react/defaults/theme.yaml

@@ -0,0 +1,41 @@
+# Default theme variants — component appearance via .vc-{element}--{variant} rules.
+variants:
+  Button:
+    primary:
+      background: "{ui.primary}"
+      foreground: "{ui.on-primary}"
+    secondary:
+      background: "{ui.button-secondary}"
+      foreground: "{ui.text}"
+    ghost:
+      background: "{ui.transparent}"
+      foreground: "{ui.text}"
+    danger:
+      background: "{ui.danger}"
+      foreground: "{ui.on-primary}"
+  Text:
+    muted:
+      foreground: "{ui.text-muted}"
+  Card:
+    default:
+      background: "{ui.surface}"
+  Badge:
+    default:
+      background: "{ui.surface-muted}"
+    primary:
+      background: "{ui.primary-weak}"
+    success:
+      background: "{ui.success-weak}"
+    warning:
+      background: "{ui.warning-weak}"
+    danger:
+      background: "{ui.danger-weak}"
+  Alert:
+    default:
+      background: "{ui.surface}"
+    success:
+      background: "{ui.success-weak}"
+    warning:
+      background: "{ui.warning-weak}"
+    danger:
+      background: "{ui.danger-weak}"

package/renderers/react/defaults/tokens.yaml

@@ -0,0 +1,59 @@
+# Default design tokens — mirrors renderers/react/runtime/theme.css :root variables.
+ui:
+  bg:
+    $type: color
+    $value: "#f6f8fb"
+  surface:
+    $type: color
+    $value: "#ffffff"
+  surface-muted:
+    $type: color
+    $value: "#f8fafc"
+  text:
+    $type: color
+    $value: "#111827"
+  text-muted:
+    $type: color
+    $value: "#6b7280"
+  primary:
+    $type: color
+    $value: "#2563eb"
+  primary-weak:
+    $type: color
+    $value: "#dbeafe"
+  success:
+    $type: color
+    $value: "#047857"
+  success-weak:
+    $type: color
+    $value: "#d1fae5"
+  warning:
+    $type: color
+    $value: "#b45309"
+  warning-weak:
+    $type: color
+    $value: "#fef3c7"
+  danger:
+    $type: color
+    $value: "#dc2626"
+  danger-weak:
+    $type: color
+    $value: "#fee2e2"
+  on-primary:
+    $type: color
+    $value: "#ffffff"
+  button-secondary:
+    $type: color
+    $value: "#eef2f7"
+  transparent:
+    $type: color
+    $value: "transparent"
+  border:
+    $type: color
+    $value: "#e5e7eb"
+  shadow:
+    $type: shadow
+    $value: "0 10px 30px rgba(15, 23, 42, 0.08)"
+  font:
+    $type: typography
+    $value: 'Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'

package/renderers/react/element-config.meta.json

@@ -0,0 +1,22 @@
+{
+  "description": "Per-element fields allowed in renderers/react/elements.yaml (React HTML lowering config — not UI DSL vocabulary).",
+  "fields": {
+    "tag": { "type": "string", "required": true },
+    "className": { "type": "string" },
+    "ariaLabel": { "type": "boolean" },
+    "ariaHidden": { "type": "boolean" },
+    "flex": { "type": "enum", "values": ["row", "column"] },
+    "wrapProp": { "type": "string" },
+    "flexGrowProp": { "type": "string" },
+    "void": { "type": "boolean" },
+    "levelProp": { "type": "string" },
+    "defaultLevel": { "type": "number" },
+    "actionEvent": { "type": "enum", "values": ["onClick", "onSubmit"] },
+    "fieldWrap": { "type": "boolean" },
+    "inputType": { "type": "string" },
+    "sizeClass": { "type": "string" },
+    "optionsProp": { "type": "string" },
+    "checkbox": { "type": "boolean" },
+    "defaultRole": { "type": "string" }
+  }
+}

package/renderers/react/elementMap.ts

@@ -0,0 +1,55 @@
+import { resolve } from 'node:path';
+import { ALLOWED_COMPONENTS } from '../../src/generated/schema/allowed-components.js';
+import type { ReactElementMapFile, ReactRendererElementConfig } from '../../src/generated/schema/react-renderer-element-config.js';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+import {
+  loadYamlFile,
+  validateMapEntryFields,
+  validateVocabularyElementNames,
+} from '../../src/renderer/elementMapValidation.js';
+import { loadUiDslSchema } from '../../src/schema/loadSchema.js';
+
+export type { ReactElementMapFile, ReactRendererElementConfig };
+export type ReactElementMap = ReactElementMapFile;
+export type ElementMapEntry = ReactRendererElementConfig;
+
+const SOURCE_LABEL = 'renderers/react/elements.yaml';
+
+let cachedMap: ReactElementMapFile | null = null;
+
+function validateElementMap(map: ReactElementMapFile): void {
+  validateVocabularyElementNames(Object.keys(map.elements), ALLOWED_COMPONENTS, SOURCE_LABEL);
+  validateMapEntryFields(map.elements, ['tag'], SOURCE_LABEL);
+}
+
+export async function loadReactElementMap(customPath?: string): Promise<ReactElementMapFile> {
+  if (!customPath && cachedMap) return cachedMap;
+  const mapPath = customPath ?? resolve(packageRoot(), 'renderers/react/elements.yaml');
+  const raw = await loadYamlFile<ReactElementMapFile>(mapPath);
+  validateElementMap(raw);
+  if (!customPath) cachedMap = raw;
+  return raw;
+}
+
+/** DSL vocabulary element with a React HTML lowering entry (excludes project extensions). */
+export function isLowerableVocabularyElement(
+  name: string,
+  map: ReactElementMapFile,
+  allowlistExtra: string[] = [],
+): boolean {
+  return ALLOWED_COMPONENTS.has(name) && !allowlistExtra.includes(name) && name in map.elements;
+}
+
+export async function assertElementMapCoversImplementedVocabulary(customPath?: string): Promise<void> {
+  const [schema, map] = await Promise.all([loadUiDslSchema(), loadReactElementMap(customPath)]);
+  const missing = Object.keys(schema.elements).filter((name) => !(name in map.elements));
+  if (missing.length > 0) {
+    console.warn(
+      `${SOURCE_LABEL}: ${missing.length} DSL element(s) have no React HTML map yet: ${missing.join(', ')}`,
+    );
+  }
+}
+
+export function isVocabularyElement(name: string, map: ReactElementMapFile, allowlistExtra: string[] = []): boolean {
+  return name in map.elements && !allowlistExtra.includes(name);
+}

package/renderers/react/elements.yaml

@@ -0,0 +1,86 @@
+# React renderer element → HTML lowering map (SSoT).
+# Vocabulary from spec/ui-dsl.schema.json. Extension components are project-specific
+# (allowlistExtra) and stay as React component imports — not listed here.
+
+elements:
+  Page:
+    tag: main
+    className: vc-page
+    ariaLabel: true
+  Box:
+    tag: div
+    className: vc-box
+    ariaLabel: true
+  Column:
+    tag: div
+    className: vc-column
+    flex: column
+    ariaLabel: true
+  Row:
+    tag: div
+    className: vc-row
+    flex: row
+    wrapProp: wrap
+    ariaLabel: true
+  Stack:
+    tag: div
+    className: vc-stack
+    ariaLabel: true
+  Spacer:
+    tag: div
+    className: vc-spacer
+    ariaHidden: true
+    flexGrowProp: weight
+  Divider:
+    tag: hr
+    className: vc-divider
+    void: true
+  Heading:
+    tag: dynamic-heading
+    className: vc-heading
+    levelProp: level
+    defaultLevel: 2
+  Text:
+    tag: p
+    className: vc-text
+  Link:
+    tag: a
+    className: vc-link
+    actionEvent: onClick
+  Button:
+    tag: button
+    className: vc-button
+    actionEvent: onClick
+  Form:
+    tag: form
+    className: vc-form
+    actionEvent: onSubmit
+    ariaLabel: true
+  TextInput:
+    tag: input
+    className: vc-text-input
+    fieldWrap: true
+    inputType: text
+    sizeClass: vc-field
+  TextArea:
+    tag: textarea
+    className: vc-text-area
+    fieldWrap: true
+  Select:
+    tag: select
+    className: vc-select
+    fieldWrap: true
+    sizeClass: vc-field
+    optionsProp: options
+  Checkbox:
+    tag: label
+    className: vc-checkbox
+    checkbox: true
+  List:
+    tag: ul
+    className: vc-list
+    defaultRole: list
+  ListItem:
+    tag: li
+    className: vc-list-item
+    defaultRole: listitem

package/renderers/react/index.ts

@@ -0,0 +1,2 @@
+export { renderReactFromIr, renderReactComponent } from './renderComponents.js';
+export { renderReactRuntime } from './renderRuntime.js';