view-contracts 0.3.2 → 0.3.3

package/README.md

@@ -78,19 +78,17 @@ A `.view.tsx` file defines:
 - component hierarchy
 - layout structure
 - visual composition
+- `variant` names (appearance resolved from `views/design/theme.yaml`)
 
-Example:
+### Design tokens and theme own appearance
 
-```tsx
-export default screen<AdminDashboardViewModel>(({ vm }) => (
-  <Page id={vm.screenId} title={vm.title}>
-    <Heading level={1}>{vm.title}</Heading>
-    <Table rows={vm.projects} />
-  </Page>
-));
-```
+Color, spacing, typography, and component variants are defined in project YAML — not in view source:
 
-The view describes **structure only** — not API calls, routing logic, or styling implementation details.
+- `views/design/tokens.yaml` — DTCG design tokens
+- `views/design/theme.yaml` — `Button.primary`, `Text.muted`, etc.
+- `views/design/extensions.css` — optional `ext-*` styles for extension components
+
+See [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md).
 
 ### Compile instead of hand-coding
 
@@ -112,8 +110,10 @@ The generated output is deterministic.
 
 ### Supported
 
-- React generation (`generated/react/`, `generated/components/`)
-- DSL preview runtime (`src/preview/`)
+- React generation (`generated/react/`, `generated/components/`, `generated/theme.css`)
+- Design tokens + theme variants (`views/design/tokens.yaml`, `theme.yaml`)
+- Live DSL preview (`dev:preview`) with `views/preview/*.mock.yaml` sample data
+- Extension registry (`extensions.yaml`) with plain HTML/CSS implementations
 - In-memory View IR compilation
 - Standalone app scaffold (`.vite/` per example project)
 
@@ -138,7 +138,9 @@ flowchart TB
   end
 
   subgraph design ["Visual design"]
-    viewTsx["views/*.view.tsx<br/>layout · composition"]
+    viewTsx["views/*.view.tsx<br/>layout · composition · variant names"]
+    tokens["views/design/tokens.yaml"]
+    theme["views/design/theme.yaml"]
   end
 
   openapi --> microContracts["micro-contracts generate"]
@@ -146,6 +148,8 @@ flowchart TB
 
   openapi --> bindings["view-bindings.yaml"]
   viewTsx --> bindings
+  tokens --> build
+  theme --> build
 
   contractsTs -->|"imports ViewModel type<br/>validates vm.* and operationId"| viewTsx
 
@@ -154,14 +158,15 @@ flowchart TB
 
   build --> viewIr["View IR (in-memory)"]
   viewIr --> reactRenderer["renderComponents"]
+  reactRenderer --> generatedReact["generated/react/*.generated.tsx"]
   build --> runtimeCopy["renderRuntime → generated/"]
   build --> bridgeGen["render bridge"]
-
-  reactRenderer --> generatedReact["generated/react/*.generated.tsx"]
+  runtimeCopy --> generatedTheme["generated/theme.css"]
   bridgeGen --> bridgeTs["generated/view-bridge.generated.ts"]
   runtimeCopy --> generatedRuntime["generated/components + runtime/"]
 
   generatedReact --> app["Standalone app (src/main.tsx)"]
+  generatedTheme --> app
   bridgeTs --> app
   generatedRuntime --> app
 ```
@@ -173,6 +178,7 @@ flowchart TB
 | 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 |
+| Design | `tokens.yaml` + `theme.yaml` validate and emit `generated/theme.css` | CSS variables + `.vc-*` variant rules |
 | Generation | Renderer copies runtime + emits React from IR + bridge registry | `generated/` (no `@view-contracts` imports) |
 
 ### Preview path (no compile step)
@@ -192,7 +198,7 @@ flowchart LR
 
 Designers and developers validate layouts **without running the full build**. Preview loads sample ViewModels from `views/preview/*.mock.yaml` (not from `generated/`). Production apps load real data via `operationId` in view-bindings.
 
-See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) (including [conditional display patterns](./docs/ARCHITECTURE.md#conditional-display-non-goals-and-patterns)) and [docs/SPEC_COVERAGE.md](./docs/SPEC_COVERAGE.md) for implementation details.
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md), [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md), [docs/extensions.md](./docs/extensions.md), and [docs/SPEC_COVERAGE.md](./docs/SPEC_COVERAGE.md).
 
 ---
 
@@ -227,10 +233,13 @@ 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
+├── views/              # restricted .view.tsx (preview compiles live)
+│   ├── design/         # tokens.yaml, theme.yaml, extensions.css
+│   └── preview/        # *.mock.yaml — preview sample ViewModels only
+├── src/                # app wiring, extension components (HTML/CSS), handlers
 ├── generated/          # build output (standalone — no @view-contracts imports)
 ├── contracts/          # OpenAPI + micro-contracts config
+├── extensions.yaml     # extension registry (Grid, Table, …)
 ├── dev.ports.ts        # fixed dev server ports
 ├── scripts/            # dev-both.sh, check-both.sh, ports.sh
 └── .vite/              # auto-generated Vite configs (gitignored)
@@ -238,7 +247,9 @@ examples/admin-dashboard/
 
 See [examples/admin-dashboard/README.md](./examples/admin-dashboard/README.md) for local verification steps.
 
-Project-specific extension components (e.g. `Grid`, `Table`) are declared in `extensions.yaml` and documented in [docs/extensions.md](./docs/extensions.md). Vocabulary elements come from `spec/ui-dsl.schema.json`; extensions are React-only pass-through components.
+**Extensions** (`Grid`, `Table`, …) are declared in `extensions.yaml` and implemented in `src/components/extensions.tsx` with plain HTML/CSS — not DSL. See [docs/extensions.md](./docs/extensions.md).
+
+**Appearance** for vocabulary elements comes from `views/design/theme.yaml` and `tokens.yaml`. See [docs/design-tokens-and-theme.md](./docs/design-tokens-and-theme.md).
 
 ---
 
@@ -247,23 +258,26 @@ Project-specific extension components (e.g. `Grid`, `Table`) are declared in `ex
 ```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)
+├── design/             # tokens/theme parse, validate, CSS emit
+├── extensions/         # extension registry load + validation
+├── preview/            # Vite plugins (live views, theme, mock YAML)
 ├── scaffold/           # .vite/ + package.json for example projects
 └── commands/           # CLI handlers (build orchestrator)
 
 packages/
 ├── core/               # screen(), types (@view-contracts/core)
-└── runtime/            # action dispatcher (@view-contracts/runtime)
+└── runtime/            # legacy preview shim
 
 renderers/
-├── react/              # element/property maps, routes.yaml
+├── react/              # lowering, element map, runtime, templates
 ├── swiftui/            # (planned)
 └── compose/            # (planned)
+
+docs/
+├── design-tokens-and-theme.md
+├── extensions.md
+├── ARCHITECTURE.md
+└── SPEC_COVERAGE.md    # auto-generated vocabulary reference
 ```
 
 ---

package/cli-contract.yaml

@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
 
 info:
   title: view-contracts CLI
-  version: 0.3.2
+  version: 0.3.3
   description: >-
     Contract-first UI design toolchain. Compiles restricted view-contract TSX
     to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).

package/dist/view-contracts.bundle.mjs

@@ -60,7 +60,7 @@ cli_contracts: 0.1.0
 
 info:
   title: view-contracts CLI
-  version: 0.3.2
+  version: 0.3.3
   description: >-
     Contract-first UI design toolchain. Compiles restricted view-contract TSX
     to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
@@ -223,7 +223,7 @@ command_sets:
   "cli_contracts": "0.1.0",
   "info": {
     "title": "view-contracts CLI",
-    "version": "0.3.2",
+    "version": "0.3.3",
     "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": {
@@ -748,7 +748,7 @@ export default defineConfig({
 `}async function gg(t,e,r){let n=$e(t),i=Ue(n,".vite");await Ys(i,{recursive:!0});let s=Ue(n,"package.json");await Ll(s)?await rt(s,`${mg}
 `,"utf-8"):await rt(s,`${mg}
 `,"utf-8"),await rt(Ue(i,"index.html"),_C,"utf-8"),await rt(Ue(i,"preview.html"),wC,"utf-8"),await rt(Ue(i,"preview-main.tsx"),bC(r),"utf-8"),await rt(Ue(i,"app-main.tsx"),vC,"utf-8"),await rt(Ue(i,"vite.config.ts"),kC(),"utf-8"),await rt(Ue(i,"vite.preview.config.ts"),xC(),"utf-8"),await rt(Ue(n,"dev.ports.ts"),$C(),"utf-8");let o=Ue(n,"scripts");await Ys(o,{recursive:!0}),await rt(Ue(o,"ports.sh"),CC(),"utf-8");let a=Ue(n,"src/main.tsx");await Ll(a)||(await Ys(hg(a),{recursive:!0}),await rt(a,SC(r),"utf-8"));let l=Ue(n,"src/runtime/handlers.ts");await Ll(l)||(await Ys(hg(l),{recursive:!0}),await rt(l,EC,"utf-8")),console.log(`  scaffold \u2192 ${i}/`)}import{mkdir as yg,writeFile as Xs}from"node:fs/promises";import{relative as vg,resolve as pt}from"node:path";function _g(){return pt(Xe(),"renderers/swiftui/templates")}function wg(){return pt(Xe(),"renderers/compose/templates")}async function bg(t,e,r){let n=$e(t),i=pt(e.generated.reactDir,"../theme"),s=vg(n,pt(i,"theme.json")).replace(/\\/g,"/"),o=vg(n,pt(i,"tokens.json")).replace(/\\/g,"/"),a=pt(e.generated.reactDir,"../swiftui"),l=pt(e.generated.reactDir,"../compose");await yg(a,{recursive:!0}),await yg(l,{recursive:!0});let u={themeJsonPath:s,tokensJsonPath:o};await Xs(pt(a,"VcTheme.swift"),await Be(_g(),"VcTheme.swift.hbs",u),"utf-8"),await Xs(pt(l,"VcTheme.kt"),await Be(wg(),"VcTheme.kt.hbs",{...u,packageName:"generated.compose"}),"utf-8");for(let d of r.views){if(d.targets.includes("swiftui")){let f=pt(a,`${d.screenName}.swift`);await Xs(f,await Be(_g(),"Screen.swift.hbs",{...u,screenName:d.screenName}),"utf-8"),console.log(`  swiftui \u2192 ${f}`)}if(d.targets.includes("compose")){let f=pt(l,`${d.screenName}Screen.kt`);await Xs(f,await Be(wg(),"Screen.kt.hbs",{...u,screenName:d.screenName,packageName:"generated.compose"}),"utf-8"),console.log(`  compose \u2192 ${f}`)}}console.log(`  native theme hooks \u2192 ${a}/VcTheme.swift, ${l}/VcTheme.kt`)}async function Cg(t){if(!t.extensions)return{allowlistExtra:t.allowlistExtra??[]};let e=await Hp(t.extensions),r=[...new Set([...t.allowlistExtra??[],...Object.keys(e.extensions)])];return{extensionRegistry:e,allowlistExtra:r}}async function Sg(t){await new Promise((e,r)=>{let n=RC("npx",["micro-contracts",...t],{stdio:"inherit"});n.on("error",r),n.on("close",i=>{i===0?e():r(new Error(`micro-contracts exited with code ${i}`))})})}async function jl(t){let e=await Jt(t),r=await un(e.bindings),{extensionRegistry:n,allowlistExtra:i}=await Cg(e),s=$e(t),o=await pu(r.views.map(a=>({sourcePath:Dl(s,a.source),exportName:a.exportName,screenName:a.screenName})),{allowlistExtra:i,extensionRegistry:n});return new Map(r.views.map((a,l)=>[a.screenName,o[l]]))}async function Eg(t,e){let r=await Jt(t),{allowlistExtra:n}=await Cg(r),i=await un(r.bindings);for(let s of i.views){if(!s.targets.includes("react"))continue;let o=e.get(s.screenName);if(!o)throw new Error(`Missing View IR for ${s.screenName}`);let a=Nu(r,s),l=Mu(t,r,a);await nh(o,a,{componentsImportFrom:l,allowlistExtra:n}),console.log(`  ${s.exportName} \u2192 ${a}`)}}async function $g(t){let e=await Jt(t),r=await un(e.bindings),n=$e(t),s=["// Auto-generated view bridge registry \u2014 DO NOT EDIT",`// Generated from ${Lu(n,e.bindings)}`,"","export const viewBridgeRegistry = {"];for(let o of r.views)s.push(`  ${o.screenConst}: {`),s.push(`    id: ${JSON.stringify(o.id)},`),s.push(`    screenId: ${JSON.stringify(o.screenId)},`),s.push(`    screenName: ${JSON.stringify(o.screenName)},`),s.push(`    route: ${JSON.stringify(o.route)},`),s.push(`    operationId: ${JSON.stringify(o.operationId)},`),s.push(`    viewModel: ${JSON.stringify(o.viewModel)},`),s.push(`    source: ${JSON.stringify(o.source)},`),s.push(`    targets: ${JSON.stringify(o.targets)},`),s.push("  },");s.push("} as const;",""),s.push("export type ViewBridgeKey = keyof typeof viewBridgeRegistry;",""),await OC(AC(Dl(e.generated.bridge)),{recursive:!0}),await PC(Dl(e.generated.bridge),s.join(`
-`),"utf-8"),console.log(`Bridge registry \u2192 ${e.generated.bridge} (${r.views.length} view(s))`)}var kg={compile:async(t,e)=>{let r=await jl(await Kt(t.config));console.log(`Compiled ${r.size} view(s) to View IR (in-memory)`)},renderReact:async(t,e)=>{let r=await Kt(t.config),n=await jl(r);await Eg(r,n)},renderBridge:async(t,e)=>{await $g(await Kt(t.config))},build:async(t,e)=>{let r=await Kt(t.config),n=await Jt(r),i=await un(n.bindings),s=await jl(r);console.log(`Compiled ${s.size} view(s) to View IR (in-memory)`);let{tokensPath:o,themePath:a}=wr(n),{themeIR:l}=await Hr(o,a);await zn(n,r),qc(s.values(),l),await pg(r,n),await Eg(r,s),await $g(r),await bg(r,n,i),await gg(r,n,i)},contractsGenerate:async(t,e)=>{let r=await Jt(await Kt(t.config));await Sg(["generate","-c",r.microContractsConfig]),console.log("Contracts generated via micro-contracts")},contractsCheck:async(t,e)=>{let r=await Jt(await Kt(t.config));await Sg(["lint","-c",r.microContractsConfig])}};var IC={version:"0.3.2"};nu(kg,IC.version).parseAsync(process.argv).catch(t=>{console.error(t instanceof Error?t.message:t),process.exit(1)});
+`),"utf-8"),console.log(`Bridge registry \u2192 ${e.generated.bridge} (${r.views.length} view(s))`)}var kg={compile:async(t,e)=>{let r=await jl(await Kt(t.config));console.log(`Compiled ${r.size} view(s) to View IR (in-memory)`)},renderReact:async(t,e)=>{let r=await Kt(t.config),n=await jl(r);await Eg(r,n)},renderBridge:async(t,e)=>{await $g(await Kt(t.config))},build:async(t,e)=>{let r=await Kt(t.config),n=await Jt(r),i=await un(n.bindings),s=await jl(r);console.log(`Compiled ${s.size} view(s) to View IR (in-memory)`);let{tokensPath:o,themePath:a}=wr(n),{themeIR:l}=await Hr(o,a);await zn(n,r),qc(s.values(),l),await pg(r,n),await Eg(r,s),await $g(r),await bg(r,n,i),await gg(r,n,i)},contractsGenerate:async(t,e)=>{let r=await Jt(await Kt(t.config));await Sg(["generate","-c",r.microContractsConfig]),console.log("Contracts generated via micro-contracts")},contractsCheck:async(t,e)=>{let r=await Jt(await Kt(t.config));await Sg(["lint","-c",r.microContractsConfig])}};var IC={version:"0.3.3"};nu(kg,IC.version).parseAsync(process.argv).catch(t=>{console.error(t instanceof Error?t.message:t),process.exit(1)});
 /*! Bundled license information:
 
 js-yaml/dist/js-yaml.mjs: