openuispec 0.1.0

package/drift/index.ts

@@ -0,0 +1,398 @@
+#!/usr/bin/env tsx
+/**
+ * Hash-based drift detection for OpenUISpec projects.
+ *
+ * Tracks spec changes via content hashes so you know what to
+ * re-generate or review after editing spec files.
+ *
+ * Usage:
+ *   npm run drift -- --target ios           # check drift for ios
+ *   npm run drift                           # check all targets with snapshots
+ *   npm run drift -- --snapshot --target ios # snapshot for ios
+ *   npm run drift -- --json --target ios    # machine-readable output
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, join, relative, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import YAML from "yaml";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const REPO_ROOT = resolve(__dirname, "..");
+const PROJECT_DIR = resolve(REPO_ROOT, "examples", "taskflow");
+const GENERATED_DIR = resolve(REPO_ROOT, "generated");
+const STATE_FILE = ".openuispec-state.json";
+
+// ── types ─────────────────────────────────────────────────────────────
+
+interface StateFile {
+  spec_version: string;
+  snapshot_at: string;
+  target: string;
+  files: Record<string, string>;
+}
+
+interface DriftResult {
+  changed: string[];
+  added: string[];
+  removed: string[];
+  unchanged: string[];
+}
+
+// ── helpers ───────────────────────────────────────────────────────────
+
+function listFiles(dir: string, ext: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(ext))
+      .sort()
+      .map((f) => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+function hashFile(filePath: string): string {
+  const content = readFileSync(filePath);
+  const hash = createHash("sha256").update(content).digest("hex");
+  return `sha256:${hash}`;
+}
+
+function discoverSpecFiles(projectDir: string): string[] {
+  const manifest = join(projectDir, "openuispec.yaml");
+  if (!existsSync(manifest)) {
+    console.error(`Error: No openuispec.yaml found in ${projectDir}`);
+    process.exit(1);
+  }
+
+  const doc = YAML.parse(readFileSync(manifest, "utf-8"));
+  const includes = doc.includes ?? {};
+  const files: string[] = [manifest];
+
+  // Tokens
+  if (includes.tokens) {
+    files.push(...listFiles(resolve(projectDir, includes.tokens), ".yaml"));
+  }
+
+  // Screens
+  if (includes.screens) {
+    files.push(...listFiles(resolve(projectDir, includes.screens), ".yaml"));
+  }
+
+  // Flows
+  if (includes.flows) {
+    files.push(...listFiles(resolve(projectDir, includes.flows), ".yaml"));
+  }
+
+  // Platform
+  if (includes.platform) {
+    files.push(...listFiles(resolve(projectDir, includes.platform), ".yaml"));
+  }
+
+  // Locales
+  if (includes.locales) {
+    files.push(...listFiles(resolve(projectDir, includes.locales), ".json"));
+  }
+
+  // Custom contracts
+  if (includes.contracts) {
+    files.push(...listFiles(resolve(projectDir, includes.contracts), ".yaml"));
+  }
+
+  return files;
+}
+
+function categorize(relPath: string): string {
+  if (relPath === "openuispec.yaml") return "Manifest";
+  const dir = dirname(relPath);
+  if (dir === "tokens") return "Tokens";
+  if (dir === "screens") return "Screens";
+  if (dir === "flows") return "Flows";
+  if (dir === "platform") return "Platform";
+  if (dir === "locales") return "Locales";
+  if (dir === "contracts") return "Contracts";
+  return "Other";
+}
+
+function resolveOutputDir(target: string): string {
+  return resolve(GENERATED_DIR, target, "TaskFlow");
+}
+
+function stateFilePath(target: string): string {
+  return join(resolveOutputDir(target), STATE_FILE);
+}
+
+/** Discover all targets that have an existing snapshot. */
+function discoverTargets(): string[] {
+  if (!existsSync(GENERATED_DIR)) return [];
+  try {
+    return readdirSync(GENERATED_DIR)
+      .filter((entry) => existsSync(stateFilePath(entry)))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+// ── snapshot ──────────────────────────────────────────────────────────
+
+function snapshot(projectDir: string, target: string): void {
+  const outDir = resolveOutputDir(target);
+  if (!existsSync(outDir)) {
+    console.error(
+      `Error: Output directory not found: ${relative(REPO_ROOT, outDir)}\n` +
+        `Run code generation for "${target}" first.`
+    );
+    process.exit(1);
+  }
+
+  const files = discoverSpecFiles(projectDir);
+  const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+
+  const hashes: Record<string, string> = {};
+  for (const f of files) {
+    const rel = relative(projectDir, f);
+    hashes[rel] = hashFile(f);
+  }
+
+  const state: StateFile = {
+    spec_version: doc.spec_version ?? "0.1",
+    snapshot_at: new Date().toISOString(),
+    target,
+    files: hashes,
+  };
+
+  const outPath = stateFilePath(target);
+  writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
+  console.log(`Snapshot saved: ${relative(REPO_ROOT, outPath)}`);
+  console.log(`  ${Object.keys(hashes).length} files hashed`);
+  console.log(`  target: ${target}`);
+}
+
+// ── check ─────────────────────────────────────────────────────────────
+
+function check(projectDir: string, target: string, jsonOutput: boolean): void {
+  const statePath = stateFilePath(target);
+  if (!existsSync(statePath)) {
+    console.error(
+      `No snapshot found for target "${target}".\n` +
+        `Run: npm run drift -- --snapshot --target ${target}`
+    );
+    process.exit(1);
+  }
+
+  const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
+  const files = discoverSpecFiles(projectDir);
+
+  const currentHashes: Record<string, string> = {};
+  for (const f of files) {
+    currentHashes[relative(projectDir, f)] = hashFile(f);
+  }
+
+  const result: DriftResult = {
+    changed: [],
+    added: [],
+    removed: [],
+    unchanged: [],
+  };
+
+  // Check current files against snapshot
+  for (const [rel, hash] of Object.entries(currentHashes)) {
+    if (!(rel in state.files)) {
+      result.added.push(rel);
+    } else if (state.files[rel] !== hash) {
+      result.changed.push(rel);
+    } else {
+      result.unchanged.push(rel);
+    }
+  }
+
+  // Check for removed files
+  for (const rel of Object.keys(state.files)) {
+    if (!(rel in currentHashes)) {
+      result.removed.push(rel);
+    }
+  }
+
+  if (jsonOutput) {
+    printJson(state, result);
+  } else {
+    printReport(projectDir, state, result);
+  }
+
+  const hasDrift =
+    result.changed.length > 0 ||
+    result.added.length > 0 ||
+    result.removed.length > 0;
+  process.exit(hasDrift ? 1 : 0);
+}
+
+function checkAll(projectDir: string, jsonOutput: boolean): void {
+  const targets = discoverTargets();
+  if (targets.length === 0) {
+    console.error(
+      "No snapshots found. Run: npm run drift -- --snapshot --target <target>"
+    );
+    process.exit(1);
+  }
+
+  let anyDrift = false;
+
+  for (const target of targets) {
+    const statePath = stateFilePath(target);
+    const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
+    const files = discoverSpecFiles(projectDir);
+
+    const currentHashes: Record<string, string> = {};
+    for (const f of files) {
+      currentHashes[relative(projectDir, f)] = hashFile(f);
+    }
+
+    const result: DriftResult = {
+      changed: [],
+      added: [],
+      removed: [],
+      unchanged: [],
+    };
+
+    for (const [rel, hash] of Object.entries(currentHashes)) {
+      if (!(rel in state.files)) {
+        result.added.push(rel);
+      } else if (state.files[rel] !== hash) {
+        result.changed.push(rel);
+      } else {
+        result.unchanged.push(rel);
+      }
+    }
+
+    for (const rel of Object.keys(state.files)) {
+      if (!(rel in currentHashes)) {
+        result.removed.push(rel);
+      }
+    }
+
+    if (jsonOutput) {
+      printJson(state, result);
+    } else {
+      printReport(projectDir, state, result);
+    }
+
+    const hasDrift =
+      result.changed.length > 0 ||
+      result.added.length > 0 ||
+      result.removed.length > 0;
+    if (hasDrift) anyDrift = true;
+
+    if (targets.length > 1 && target !== targets[targets.length - 1]) {
+      console.log("");
+    }
+  }
+
+  process.exit(anyDrift ? 1 : 0);
+}
+
+// ── output ────────────────────────────────────────────────────────────
+
+function printJson(state: StateFile, result: DriftResult): void {
+  console.log(
+    JSON.stringify(
+      {
+        snapshot_at: state.snapshot_at,
+        target: state.target,
+        ...result,
+      },
+      null,
+      2
+    )
+  );
+}
+
+function printReport(
+  projectDir: string,
+  state: StateFile,
+  result: DriftResult
+): void {
+  const doc = YAML.parse(
+    readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
+  );
+  const projectName = doc.project?.name ?? basename(projectDir);
+
+  console.log("OpenUISpec Drift Check");
+  console.log("======================");
+  console.log(`Project: ${projectName}`);
+  console.log(`Snapshot: ${state.snapshot_at}`);
+  console.log(`Target: ${state.target}`);
+
+  // Group all files by category
+  const allFiles = new Set([
+    ...result.unchanged,
+    ...result.changed,
+    ...result.added,
+    ...result.removed,
+  ]);
+
+  const categories = new Map<string, string[]>();
+  for (const f of allFiles) {
+    const cat = categorize(f);
+    if (!categories.has(cat)) categories.set(cat, []);
+    categories.get(cat)!.push(f);
+  }
+
+  const order = [
+    "Manifest",
+    "Tokens",
+    "Screens",
+    "Flows",
+    "Platform",
+    "Locales",
+    "Contracts",
+    "Other",
+  ];
+
+  for (const cat of order) {
+    const files = categories.get(cat);
+    if (!files) continue;
+    files.sort();
+
+    console.log(`\n${cat}`);
+    for (const f of files) {
+      const name = basename(f);
+      if (result.changed.includes(f)) {
+        console.log(`  ✗  ${name} (changed)`);
+      } else if (result.added.includes(f)) {
+        console.log(`  +  ${name} (added)`);
+      } else if (result.removed.includes(f)) {
+        console.log(`  -  ${name} (removed)`);
+      } else {
+        console.log(`  ✓  ${name}`);
+      }
+    }
+  }
+
+  console.log(
+    `\nSummary: ${result.changed.length} changed, ${result.added.length} added, ${result.removed.length} removed`
+  );
+}
+
+// ── main ──────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const isSnapshot = args.includes("--snapshot");
+const isJson = args.includes("--json");
+
+const targetIdx = args.indexOf("--target");
+const target = targetIdx !== -1 && args[targetIdx + 1] ? args[targetIdx + 1] : null;
+
+if (isSnapshot) {
+  if (!target) {
+    console.error("Error: --target is required for --snapshot");
+    console.error("Usage: npm run drift -- --snapshot --target <target>");
+    process.exit(1);
+  }
+  snapshot(PROJECT_DIR, target);
+} else if (target) {
+  check(PROJECT_DIR, target, isJson);
+} else {
+  checkAll(PROJECT_DIR, isJson);
+}

package/examples/taskflow/README.md

@@ -0,0 +1,103 @@
+# TaskFlow — OpenUISpec Example Application
+
+A complete task management app defined entirely in OpenUISpec v0.1, demonstrating how a single source of truth generates native iOS, Android, and Web applications.
+
+## What this demonstrates
+
+### All 7 contract families in use
+
+| Contract | Where it's used | Variants exercised |
+|----------|----------------|-------------------|
+| `action_trigger` | FAB, form buttons, destructive delete, ghost cancel | primary, secondary, tertiary, destructive, ghost |
+| `data_display` | Task items, stat cards, hero header, profile card, settings rows | card, compact, hero, stat, inline |
+| `input_field` | Search, task form (text, multiline, select, date, toggle, checkbox) | text, multiline, select, date, toggle, checkbox |
+| `nav_container` | Main tab bar (4 tabs with badge), adaptive rail/sidebar | tab_bar, rail, sidebar |
+| `feedback` | Success toasts, error banners, delete confirmation dialog | toast, banner, dialog |
+| `surface` | Assignee picker sheet/panel, new project modal, create task sheet | sheet, modal, panel |
+| `collection` | Task list, filter chips, project grid, settings list, tag chips | list, grid, chips |
+
+### Adaptive layout
+
+- **Navigation**: tab_bar (compact) → rail (regular) → sidebar (expanded)
+- **Task detail**: stacked stat cards → horizontal row, stacked buttons → inline row
+- **Projects**: 1-column grid → 2-column → 3-column
+- **Surfaces**: assignee picker renders as sheet (compact) or side panel (expanded)
+- **Home**: single-column scroll (compact) → split_view master-detail (expanded)
+
+### Action system
+
+- **navigate**: push to detail, present sheet/modal, `$back` destination
+- **api_call**: with `on_success`/`on_error` handlers, optimistic updates on toggle
+- **confirm**: destructive delete with confirmation dialog
+- **sequence**: dismiss + feedback + refresh composed in order
+- **feedback**: success toasts, error banners as side-effect actions
+- **set_state**: filter changes, form submission loading state
+
+### Data binding
+
+- **API sources**: `api.tasks.list`, `api.auth.currentUser`, etc.
+- **Local state**: `state.active_filter`, `state.search_query`, `state.is_submitting`
+- **Format expressions**: `{task.due_date | format:date_relative}`, `{item.priority | map:priority_to_severity}`
+- **Computed expressions**: `{task.status == done ? 'Reopen task' : 'Mark complete'}`
+- **Two-way binding**: `data_binding: "form.title"` on input fields
+- **Conditional rendering**: `condition: "task.description != null"`
+
+### Token system
+
+- **7 token categories**: color, typography, spacing, elevation, motion, layout, themes
+- **Constrained ranges**: Every token uses Level 2 (range-based) constraints
+- **Platform flex**: ±15% spacing adaptation, system font fallbacks, dynamic color support
+
+### Platform adaptation
+
+- **iOS**: System tab bar, `.insetGrouped` list style, haptics, swipe actions, sheet detents
+- **Android**: Material 3 NavigationBar, ripple, predictive back, edge-to-edge, dynamic color
+- **Web**: Keyboard shortcuts (⌘N, ⌘K, ⌘B), native `<dialog>`, CSS custom properties
+
+## File structure
+
+```
+taskflow/
+├── openuispec.yaml              # Root manifest + data model + formatters + API endpoints
+├── tokens/
+│   ├── color.yaml               # Brand + semantic + status colors
+│   ├── typography.yaml          # Font family + 9-step type scale
+│   ├── spacing.yaml             # 4px base unit, 10-step scale
+│   ├── elevation.yaml           # 4-level elevation (none/sm/md/lg)
+│   ├── motion.yaml              # Durations, easings, patterns
+│   ├── layout.yaml              # Size classes, primitives, reflow rules
+│   └── themes.yaml              # Light, dark, warm variants
+├── contracts/                   # 7 contract family stubs (see spec Section 4)
+├── screens/
+│   ├── home.yaml                # Task list with search, filters, FAB, adaptive nav
+│   ├── task_detail.yaml         # Full task view with actions + assignee sheet
+│   ├── projects.yaml            # Project grid + new project dialog
+│   ├── project_detail.yaml      # Single project with task list (stub)
+│   ├── settings.yaml            # Preferences, toggles, account management
+│   └── calendar.yaml            # Calendar view (stub)
+├── flows/
+│   └── create_task.yaml         # Task creation form (sheet presentation)
+└── platform/
+    ├── ios.yaml                 # SwiftUI overrides + behaviors
+    ├── android.yaml             # Compose overrides + behaviors
+    └── web.yaml                 # React overrides + responsive rules
+```
+
+## How to use this with AI
+
+Pass the entire `taskflow/` directory as context to an AI code generator with the prompt:
+
+> Generate a native {ios|android|web} application from this OpenUISpec. Follow all contract state machines, apply token ranges for the target platform, and implement the navigation flows as defined. Use the platform adaptation file for target-specific overrides.
+
+The AI should produce:
+1. Compilable platform code (Swift/Kotlin/TypeScript)
+2. All screens with correct contract-to-widget mapping
+3. Navigation wiring matching the flow definitions
+4. Theme support (light/dark at minimum)
+5. Accessibility labels and roles per contract a11y specs
+6. Loading, empty, and error states for all collections
+7. Adaptive layout responding to size class changes
+
+---
+
+*TaskFlow is a reference implementation of OpenUISpec v0.1, not a production application.*

package/examples/taskflow/contracts/README.md

@@ -0,0 +1,18 @@
+# TaskFlow — Contract Files
+
+These files define the 7 standard OpenUISpec contract families used by TaskFlow.
+They are extracted from the OpenUISpec v0.1 specification (Section 4) for use as
+standalone, machine-readable contract definitions.
+
+For the full specification of each contract including generation hints and test cases,
+see `spec/openuispec-v0.1.md` Section 4.
+
+| File | Contract | Section |
+|------|----------|---------|
+| `action_trigger.yaml` | Initiates actions | 4.1 |
+| `data_display.yaml` | Presents read-only info | 4.2 |
+| `input_field.yaml` | Captures user input | 4.3 |
+| `nav_container.yaml` | Persistent navigation | 4.4 |
+| `feedback.yaml` | System status messages | 4.5 |
+| `surface.yaml` | Contains other components | 4.6 |
+| `collection.yaml` | Repeating data sets | 4.7 |

package/examples/taskflow/contracts/action_trigger.yaml

@@ -0,0 +1,7 @@
+# action_trigger contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: action_trigger
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/collection.yaml

@@ -0,0 +1,7 @@
+# collection contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: collection
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/data_display.yaml

@@ -0,0 +1,7 @@
+# data_display contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: data_display
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/feedback.yaml

@@ -0,0 +1,7 @@
+# feedback contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: feedback
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/input_field.yaml

@@ -0,0 +1,7 @@
+# input_field contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: input_field
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/nav_container.yaml

@@ -0,0 +1,7 @@
+# nav_container contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: nav_container
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"

package/examples/taskflow/contracts/surface.yaml

@@ -0,0 +1,7 @@
+# surface contract — see spec Section 4 for full definition
+# This file serves as a machine-readable reference for AI generators.
+# The canonical definition lives in spec/openuispec-v0.1.md.
+
+contract: surface
+spec_section: "4"
+source: "spec/openuispec-v0.1.md"