view-contracts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foo-log-inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# view-contracts
+
+**Contract-first UI development for AI-native applications.**
+
+view-contracts is a UI definition system that separates:
+
+- **Screen semantics** → OpenAPI
+- **Visual structure** → Restricted TSX
+
+Instead of mixing API contracts, business logic, and UI implementation inside React components, view-contracts treats UI as a **compilable contract**.
+
+---
+
+## Why?
+
+Modern UI development has a structural problem.
+
+```txt
+React Component
+ ├─ API knowledge
+ ├─ ViewModel mapping
+ ├─ Business rules
+ ├─ Layout
+ └─ Styling
+```
+
+As applications grow:
+
+- UI becomes difficult to regenerate
+- AI-generated code drifts from design rules
+- Multi-platform support becomes expensive
+- Design systems become guidelines instead of contracts
+
+view-contracts introduces a contract-first approach:
+
+```txt
+OpenAPI
+    ↓
+Screen Contract
+Restricted TSX
+    ↓
+View Definition
+Compiler
+    ↓
+Generated UI
+```
+
+The goal is to make UI generation **deterministic**.
+
+---
+
+## Core Concepts
+
+### OpenAPI owns semantics
+
+OpenAPI defines:
+
+- screens
+- actions
+- navigation
+- ViewModels
+
+Example:
+
+```yaml
+/admin/dashboard:
+  get:
+    operationId: getAdminDashboard
+    x-screen-id: SCR-ADMIN-DASHBOARD
+```
+
+This is the source of truth for screen behavior.
+
+### TSX owns layout
+
+A `.view.tsx` file defines:
+
+- component hierarchy
+- layout structure
+- visual composition
+
+Example:
+
+```tsx
+export default screen<AdminDashboardViewModel>(({ vm }) => (
+  <Page id={vm.screenId} title={vm.title}>
+    <Heading level={1}>{vm.title}</Heading>
+    <Table rows={vm.projects} />
+  </Page>
+));
+```
+
+The view describes **structure only** — not API calls, routing logic, or styling implementation details.
+
+### Compile instead of hand-coding
+
+```txt
+.view.tsx
+    ↓
+Compiler (in-memory View IR)
+    ↓
+Renderer
+    ↓
+generated/react/*.tsx + generated/runtime/
+```
+
+The generated output is deterministic.
+
+---
+
+## Current Status
+
+### Supported
+
+- React generation (`generated/react/`, `generated/components/`)
+- DSL preview runtime (`src/preview/`)
+- In-memory View IR compilation
+- Standalone app scaffold (`.vite/` per example project)
+- Static catalog generation
+
+### Planned
+
+- SwiftUI renderer
+- Jetpack Compose renderer
+- PDF renderer
+
+The contract model is designed for multi-target generation, but the first production target is React.
+
+---
+
+## Architecture
+
+Two sources of truth converge through **bindings**, **type-checking**, and **View IR**.
+
+```mermaid
+flowchart TB
+  subgraph ia ["Information architecture"]
+    openapi["contracts/openapi.yaml<br/>screens · ViewModels · actions"]
+  end
+
+  subgraph design ["Visual design"]
+    viewTsx["views/*.view.tsx<br/>layout · composition"]
+  end
+
+  openapi --> microContracts["micro-contracts generate"]
+  microContracts --> contractsTs["generated/contracts.ts"]
+  microContracts --> mockTs["generated/mock.ts"]
+
+  openapi --> bindings["view-bindings.yaml"]
+  viewTsx --> bindings
+
+  contractsTs -->|"imports ViewModel type<br/>validates vm.* and operationId"| viewTsx
+
+  bindings -->|"screen ↔ view mapping"| build["view-contracts build"]
+  viewTsx --> build
+
+  build --> viewIr["View IR (in-memory)"]
+  viewIr --> reactRenderer["renderComponents"]
+  build --> runtimeCopy["renderRuntime → generated/"]
+  build --> bridgeGen["render bridge"]
+
+  reactRenderer --> generatedReact["generated/react/*.generated.tsx"]
+  bridgeGen --> bridgeTs["generated/view-bridge.generated.ts"]
+  runtimeCopy --> generatedRuntime["generated/components + runtime/"]
+
+  generatedReact --> app["Standalone app (src/main.tsx)"]
+  bridgeTs --> app
+  generatedRuntime --> app
+```
+
+**Where the two designs meet**
+
+| Stage | What merges | Output |
+| --- | --- | --- |
+| Authoring | OpenAPI types flow into `.view.tsx` via `generated/contracts.ts` | Type-safe view source |
+| Binding | `view-bindings.yaml` links a screen (`operationId`, `ViewModel`) to a view file | No schema duplication |
+| Compilation | Compiler reads layout from TSX and lowers `vm.*` / `action` to language-neutral IR | In-memory View IR |
+| Generation | Renderer copies runtime + emits React from IR + bridge registry | `generated/` (no `@view-contracts` imports) |
+
+### Preview path (no compile step)
+
+```mermaid
+flowchart LR
+  openapi["openapi.yaml"] --> microContracts["micro-contracts"]
+  microContracts --> contractsTs["contracts.ts"]
+  microContracts --> mockTs["mock.ts"]
+
+  contractsTs --> viewTsx["*.view.tsx"]
+  viewTsx --> preview["src/preview/"]
+  mockTs --> preview
+
+  preview --> reactDev["Vite dev server<br/>design verification"]
+```
+
+Designers and developers validate layouts **without running the full build**. The preview still consumes OpenAPI-derived ViewModel types and mock data.
+
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and [docs/SPEC_COVERAGE.md](./docs/SPEC_COVERAGE.md) for implementation details.
+
+---
+
+## Quick Start
+
+```bash
+npm install
+npm run build:views   # compile + generate + scaffold .vite/
+npm run dev           # preview (5173) + dev app (5174)
+```
+
+| URL | Purpose |
+| --- | --- |
+| http://localhost:5173/.vite/preview.html | DSL preview — `views/*.view.tsx` only |
+| http://localhost:5174/.vite/index.html | Dev app — `generated/` + `src/main.tsx` |
+
+Ports are fixed in `examples/admin-dashboard/dev.ports.ts` (`strictPort: true`).
+
+Other useful commands:
+
+```bash
+npm run dev:preview     # preview only
+npm run dev:app         # standalone dev app only
+npm run check:both      # build + preview dev + production bundle (4174)
+npm run build:catalog   # static gallery HTML
+```
+
+---
+
+## Example Project
+
+The repository includes an example admin dashboard:
+
+```txt
+examples/admin-dashboard/
+├── views/              # restricted .view.tsx (may import @view-contracts/*)
+├── src/                # app wiring, extension components, handlers
+├── generated/          # build output (standalone — no @view-contracts imports)
+├── contracts/          # OpenAPI + micro-contracts config
+├── dev.ports.ts        # fixed dev server ports
+├── scripts/            # dev-both.sh, check-both.sh, ports.sh
+└── .vite/              # auto-generated Vite configs (gitignored)
+```
+
+See [examples/admin-dashboard/README.md](./examples/admin-dashboard/README.md) for local verification steps.
+
+---
+
+## Project Layout
+
+```txt
+src/
+├── compiler/           # TSX → View IR
+├── renderer/
+│   └── react/
+│       ├── renderComponents.ts   # IR → generated/react/*.tsx
+│       ├── renderRuntime.ts      # runtime SSoT → example/generated/
+│       └── runtime/              # React primitives (@view-contracts/components SSoT)
+├── preview/            # DSL preview helpers (@view-contracts/preview)
+├── scaffold/           # .vite/ + package.json for example projects
+├── catalog/            # static catalog builder
+└── commands/           # CLI handlers (build orchestrator)
+
+packages/
+├── core/               # screen(), types (@view-contracts/core)
+└── runtime/            # action dispatcher (@view-contracts/runtime)
+
+renderers/
+├── react/              # element/property maps, routes.yaml
+├── swiftui/            # (planned)
+└── compose/            # (planned)
+```
+
+---
+
+## Vision
+
+UI should be treated like an API contract.
+
+The long-term goal of view-contracts is to make UI:
+
+- **deterministic**
+- **compilable**
+- **AI-friendly**
+- **portable** across platforms
+
+while keeping designers and developers working from the same source of truth.
+
+view-contracts is not a React replacement — it is **contract-first UI** for the AI era.
+
+---
+
+## npm
+
+```bash
+npm install -D view-contracts
+npx view-contracts build -c view-contracts.config.yaml
+```
+
+Releases are published to npm when a [GitHub Release](https://github.com/foo-log-inc/view-contracts/releases) is published (`v*` tag).

package/cli-contract.yaml

@@ -0,0 +1,201 @@
+# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
+cli_contracts: 0.1.0
+
+info:
+  title: view-contracts CLI
+  version: 0.1.0
+  description: >-
+    Contract-first UI design toolchain. Compiles restricted view-contract TSX
+    to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
+
+artifact_slots:
+  openapi-specs:
+    direction: read
+    description: OpenAPI screen contracts
+  view-sources:
+    direction: read
+    description: Restricted .view.tsx design definitions
+  generated-react:
+    direction: write
+    description: Generated React components
+  bindings:
+    direction: read
+    description: view-bindings.yaml bridge registry input
+
+command_sets:
+  view-contracts:
+    summary: View contract compiler and renderer toolchain.
+    executable: view-contracts
+
+    global_options:
+      - name: help
+        aliases: [h]
+        description: Show help and exit.
+        schema:
+          type: boolean
+
+      - name: version
+        aliases: [V]
+        description: Print version and exit.
+        schema:
+          type: boolean
+
+    commands:
+      compile:
+        summary: Compile .view.tsx files to View IR.
+        description: >-
+          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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              media_type: application/yaml
+              encoding: utf-8
+        exits:
+          '0':
+            description: Compilation succeeded.
+          '1':
+            description: Compilation failed.
+
+      render.react:
+        summary: Generate React components from View IR.
+        description: 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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+        exits:
+          '0':
+            description: Render succeeded.
+          '1':
+            description: Render failed.
+
+      render.bridge:
+        summary: Generate view ↔ ViewModel bridge registry.
+        description: 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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+        exits:
+          '0':
+            description: Bridge registry generated.
+          '1':
+            description: Generation failed.
+
+      build:
+        summary: Full view pipeline (compile + render runtime + render react + bridge).
+        description: >-
+          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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+        exits:
+          '0':
+            description: Build succeeded.
+          '1':
+            description: Build failed.
+
+      contracts.generate:
+        summary: Generate ViewModel types from OpenAPI via micro-contracts.
+        description: 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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+        exits:
+          '0':
+            description: Generation succeeded.
+          '1':
+            description: Generation failed.
+
+      contracts.check:
+        summary: Lint OpenAPI screen contracts via micro-contracts.
+        description: Delegates to micro-contracts lint.
+        usage:
+          - view-contracts contracts check
+          - view-contracts contracts check -c view-contracts.config.yaml
+        options:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+        exits:
+          '0':
+            description: Lint passed.
+          '1':
+            description: Lint failed.
+
+      catalog.build:
+        summary: Build static catalog HTML for design review.
+        description: >-
+          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:
+          - name: config
+            aliases: [c]
+            description: Path to view-contracts.config.yaml (discovered upward from cwd when omitted).
+            value_name: path
+            schema:
+              type: string
+          - name: output
+            aliases: [o]
+            description: Output HTML path (defaults to dist/catalog.html next to bindings).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: write
+              media_type: text/html
+              encoding: utf-8
+        exits:
+          '0':
+            description: Catalog built.
+            files:
+              - path: dist/catalog.html
+                required: false
+                media_type: text/html
+                encoding: utf-8
+          '1':
+            description: Build failed.