view-contracts 0.1.0

package/docs/cli-reference.md

@@ -0,0 +1,239 @@
+# view-contracts CLI
+
+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
+
+## Table of Contents
+
+- [view-contracts](#view-contracts)
+  - [compile](#view-contracts-compile)
+  - [render.react](#view-contracts-render-react)
+  - [render.bridge](#view-contracts-render-bridge)
+  - [build](#view-contracts-build)
+  - [contracts.generate](#view-contracts-contracts-generate)
+  - [contracts.check](#view-contracts-contracts-check)
+  - [catalog.build](#view-contracts-catalog-build)
+
+---
+
+## view-contracts
+
+View contract compiler and renderer toolchain.
+
+### Global Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--help` | -h | No |  | Show help and exit. |
+| `--version` | -V | No |  | Print version and exit. |
+
+### compile
+
+Compile .view.tsx files to View IR.
+
+Parses restricted view-contract TSX via the TypeScript AST, validates allowed components and expressions, and holds View IR in memory.
+
+**Usage:**
+
+```
+view-contracts compile
+```
+```
+view-contracts compile -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Compilation succeeded.
+
+**Exit 1:** Compilation failed.
+
+---
+
+### render.react
+
+Generate React components from View IR.
+
+Compiles views in memory and emits production React to generated/react/.
+
+**Usage:**
+
+```
+view-contracts render react
+```
+```
+view-contracts render react -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Render succeeded.
+
+**Exit 1:** Render failed.
+
+---
+
+### render.bridge
+
+Generate view ↔ ViewModel bridge registry.
+
+Emits src/generated/view-bridge.generated.ts from view-bindings.yaml.
+
+**Usage:**
+
+```
+view-contracts render bridge
+```
+```
+view-contracts render bridge -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Bridge registry generated.
+
+**Exit 1:** Generation failed.
+
+---
+
+### build
+
+Full view pipeline (compile + render runtime + render react + bridge).
+
+Compiles views in memory, copies React runtime to generated/, emits React components and bridge registry, and scaffolds .vite/ dev files.
+
+**Usage:**
+
+```
+view-contracts build
+```
+```
+view-contracts build -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Build succeeded.
+
+**Exit 1:** Build failed.
+
+---
+
+### contracts.generate
+
+Generate ViewModel types from OpenAPI via micro-contracts.
+
+Delegates to micro-contracts generate using micro-contracts.config.yaml.
+
+**Usage:**
+
+```
+view-contracts contracts generate
+```
+```
+view-contracts contracts generate -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Generation succeeded.
+
+**Exit 1:** Generation failed.
+
+---
+
+### contracts.check
+
+Lint OpenAPI screen contracts via micro-contracts.
+
+Delegates to micro-contracts lint.
+
+**Usage:**
+
+```
+view-contracts contracts check
+```
+```
+view-contracts contracts check -c view-contracts.config.yaml
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+
+#### Exit Codes
+
+**Exit 0:** Lint passed.
+
+**Exit 1:** Lint failed.
+
+---
+
+### catalog.build
+
+Build static catalog HTML for design review.
+
+Renders all registered views with mock ViewModels into a single HTML file for design review, screenshot baselines, and accessibility checks.
+
+**Usage:**
+
+```
+view-contracts catalog build
+```
+```
+view-contracts catalog build -c view-contracts.config.yaml
+```
+```
+view-contracts catalog build -o dist/catalog.html
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` | -c | No |  | Path to view-contracts.config.yaml (discovered upward from cwd when omitted). |
+| `--output` | -o | No |  | Output HTML path (defaults to dist/catalog.html next to bindings). |
+
+#### Exit Codes
+
+**Exit 0:** Catalog built.
+
+- **Generated files:**
+  - `dist/catalog.html` (text/html) *(optional)*
+
+**Exit 1:** Build failed.
+
+---

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "view-contracts",
+  "version": "0.1.0",
+  "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "view-contracts": "dist/view-contracts.bundle.mjs"
+  },
+  "files": [
+    "dist/view-contracts.bundle.mjs",
+    "dist/view-contracts.bundle.mjs.map",
+    "src/renderer/react/runtime",
+    "src/generated/schema",
+    "spec",
+    "renderers",
+    "cli-contract.yaml",
+    "docs/cli-reference.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "generate": "cli-contracts generate",
+    "dev": "npm run build:views && npm run dev:both --prefix examples/admin-dashboard",
+    "dev:preview": "npm run dev:preview --prefix examples/admin-dashboard",
+    "dev:app": "npm run dev:app --prefix examples/admin-dashboard",
+    "dev:both": "npm run build:views && npm run dev:both --prefix examples/admin-dashboard",
+    "check:both": "npm run check:both --prefix examples/admin-dashboard",
+    "serve:built": "npm run serve:built --prefix examples/admin-dashboard",
+    "build": "npm run build:cli && npm run build:views && tsc -b",
+    "build:cli": "npm run generate && tsc -p tsconfig.cli.json",
+    "build:publish": "npm run build:cli && npm run bundle:min",
+    "bundle": "node esbuild.bundle.mjs",
+    "bundle:min": "node esbuild.bundle.mjs --minify",
+    "build:views": "tsx src/cli.ts build -c examples/admin-dashboard/view-contracts.config.yaml",
+    "build:catalog": "tsx src/cli.ts catalog build -c examples/admin-dashboard/view-contracts.config.yaml",
+    "build:example": "vite build --config examples/admin-dashboard/.vite/vite.config.ts",
+    "compile": "tsx src/cli.ts compile -c examples/admin-dashboard/view-contracts.config.yaml",
+    "render:react": "tsx src/cli.ts render react -c examples/admin-dashboard/view-contracts.config.yaml",
+    "contracts:generate": "tsx src/cli.ts contracts generate -c examples/admin-dashboard/view-contracts.config.yaml",
+    "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",
+    "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"
+  },
+  "keywords": [
+    "ui",
+    "contract-first",
+    "tsx",
+    "view-model",
+    "code-generation",
+    "react",
+    "openapi",
+    "design-system",
+    "ai-development"
+  ],
+  "author": "foo-log-inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foo-log-inc/view-contracts.git"
+  },
+  "homepage": "https://github.com/foo-log-inc/view-contracts#readme",
+  "bugs": {
+    "url": "https://github.com/foo-log-inc/view-contracts/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1",
+    "micro-contracts": "^0.17.10",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.19.21",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
+    "ajv": "^8.18.0",
+    "cli-contracts": "^0.33.13",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.21.0",
+    "vite": "^6.4.1"
+  }
+}

package/renderers/compose/README.md

@@ -0,0 +1,8 @@
+# Compose renderer scaffold
+
+- Maps: `elements.yaml`, `properties.yaml` (hand-maintained under this directory)
+- Routes: `routes.yaml`
+- Templates: `templates/`
+
+Implement Compose code generation by reading View IR + renderer maps.
+Vocabulary: `spec/ui-dsl.schema.json` (from `ui-dsl-*.csv`).

package/renderers/react/README.md

@@ -0,0 +1,10 @@
+# React renderer
+
+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)
+
+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.

package/renderers/react/routes.yaml

@@ -0,0 +1,27 @@
+# Renderer output routing — separate from element/property mapping.
+# Vocabulary: spec/ui-dsl.schema.json. Per-target maps: renderers/{target}/elements.yaml
+
+react:
+  description: Production / preview React components via project componentsModule
+  importFrom: '@view-contracts/components'
+  themeCss: theme.css
+  outputs:
+    screen:
+      pattern: '{{projectRoot}}/generated/react/{{screenName}}.generated.tsx'
+  preview:
+    entry: views/preview.entry.tsx
+    generatedEntry: src/main.tsx
+
+swiftui:
+  description: SwiftUI renderer (scaffold — implement using elements.map.yaml + properties.map.yaml)
+  outputs:
+    screen:
+      pattern: '{{projectRoot}}/generated/swiftui/{{screenName}}.swift'
+      template: templates/Screen.swift.hbs
+
+compose:
+  description: Jetpack Compose renderer (scaffold)
+  outputs:
+    screen:
+      pattern: '{{projectRoot}}/generated/compose/{{screenName}}Screen.kt'
+      template: templates/Screen.kt.hbs

package/renderers/swiftui/README.md

@@ -0,0 +1,8 @@
+# SwiftUI renderer scaffold
+
+- Maps: `elements.yaml`, `properties.yaml` (hand-maintained under this directory)
+- Routes: `routes.yaml`
+- Templates: `templates/`
+
+Implement SwiftUI code generation by reading View IR + renderer maps.
+Extend vocabulary via `spec/ui-dsl.schema.json` (from `ui-dsl-*.csv`), then update renderer maps.

package/spec/ui-dsl.linter-rules.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "view-contracts UI DSL linter rules",
+  "description": "Structural constraints not expressible in ui-dsl.schema.json alone. Validated by schema linter, not JSON Schema.",
+  "rules": [
+    {
+      "id": "spacer-parent",
+      "severity": "error",
+      "description": "Spacer must be a direct child of Row or Column",
+      "element": "Spacer",
+      "parent": ["Row", "Column"]
+    },
+    {
+      "id": "scroll-area-single-child",
+      "severity": "error",
+      "description": "ScrollArea must contain exactly one child",
+      "element": "ScrollArea",
+      "children": { "count": 1 }
+    },
+    {
+      "id": "list-listitem-only",
+      "severity": "error",
+      "description": "List children must be ListItem elements only",
+      "element": "List",
+      "children": { "allowed": ["ListItem"] }
+    },
+    {
+      "id": "icon-button-label-required",
+      "severity": "error",
+      "description": "IconButton requires label for accessibility",
+      "element": "IconButton",
+      "requiredProperties": ["label"]
+    },
+    {
+      "id": "image-src-required",
+      "severity": "error",
+      "description": "Image requires src",
+      "element": "Image",
+      "requiredProperties": ["src"]
+    },
+    {
+      "id": "icon-name-required",
+      "severity": "error",
+      "description": "Icon requires name (icon token)",
+      "element": "Icon",
+      "requiredProperties": ["name"]
+    },
+    {
+      "id": "heading-level-required",
+      "severity": "error",
+      "description": "Heading requires headingLevel for semantic hierarchy",
+      "element": "Heading",
+      "requiredProperties": ["headingLevel"]
+    },
+    {
+      "id": "form-no-onclick",
+      "severity": "error",
+      "description": "Form must use onSubmit, not onClick",
+      "element": "Form",
+      "forbiddenProperties": ["onClick"]
+    },
+    {
+      "id": "field-single-input",
+      "severity": "error",
+      "description": "Field must contain exactly one input element",
+      "element": "Field",
+      "children": {
+        "allowed": ["TextInput", "TextArea", "Select", "Checkbox", "Radio", "Switch"],
+        "count": 1
+      }
+    },
+    {
+      "id": "modal-placement",
+      "severity": "error",
+      "description": "Modal must be a direct child of Page or an overlay host",
+      "element": "Modal",
+      "parent": ["Page", "App"]
+    },
+    {
+      "id": "button-label-or-children",
+      "severity": "error",
+      "description": "Button requires label or text/icon children; when both exist, label is the accessibility name",
+      "element": "Button",
+      "oneOf": [
+        { "requiredProperties": ["label"] },
+        { "hasChildren": true }
+      ]
+    }
+  ]
+}

package/spec/ui-dsl.meta.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://view-contracts.dev/schema/ui-dsl.meta.json",
+  "title": "view-contracts UI DSL vocabulary document",
+  "description": "JSON Schema for spec/ui-dsl.schema.json. Vocabulary is derived from ui-dsl-*.csv.",
+  "type": "object",
+  "required": ["tokens", "properties", "elements"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" },
+        "minItems": 1
+      }
+    },
+    "properties": {
+      "type": "object",
+      "description": "Shared DSL attributes (from ui-dsl-properties.csv).",
+      "additionalProperties": { "$ref": "#/$defs/propertyDef" }
+    },
+    "elements": {
+      "type": "object",
+      "description": "DSL elements (from ui-dsl-elements.csv).",
+      "additionalProperties": { "$ref": "#/$defs/elementDef" }
+    }
+  },
+  "$defs": {
+    "propertyDef": {
+      "type": "object",
+      "required": ["type", "x-category"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "oneOf": [
+            { "type": "string", "enum": ["string", "number", "boolean", "array", "action"] },
+            { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+          ]
+        },
+        "enum": { "type": "string", "description": "Token set name in tokens" },
+        "description": { "type": "string" },
+        "x-category": {
+          "type": "string",
+          "enum": [
+            "identity", "state", "size", "spacing", "alignment", "direction", "overflow",
+            "visual", "text", "image", "interaction", "data", "validation"
+          ]
+        },
+        "x-appliesTo": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "x-notes": { "type": "string" }
+      }
+    },
+    "propertyRef": {
+      "type": "object",
+      "required": ["$ref"],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": {
+          "type": "string",
+          "pattern": "^#/properties/[A-Za-z][A-Za-z0-9]*$"
+        }
+      }
+    },
+    "elementProperty": {
+      "oneOf": [
+        { "$ref": "#/$defs/propertyDef" },
+        { "$ref": "#/$defs/propertyRef" }
+      ]
+    },
+    "elementDef": {
+      "type": "object",
+      "required": ["x-tier", "x-category", "description", "properties", "_children"],
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "x-tier": {
+          "type": "string",
+          "enum": ["core", "optional", "extension"]
+        },
+        "x-category": {
+          "type": "string",
+          "enum": ["structure", "layout", "scroll", "text", "media", "input", "form", "overlay", "feedback"]
+        },
+        "x-notes": { "type": "string" },
+        "properties": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/elementProperty" }
+        },
+        "_children": { "$ref": "#/$defs/childrenConstraint" }
+      }
+    },
+    "childrenConstraint": {
+      "type": "object",
+      "required": ["x-kind"],
+      "additionalProperties": false,
+      "properties": {
+        "x-kind": {
+          "type": "string",
+          "enum": ["any", "none", "single", "text", "list"]
+        },
+        "x-items": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}