openuispec 0.1.27 → 0.1.29

package/examples/taskflow/generated/web/TaskFlow/src/utils.ts

@@ -0,0 +1,78 @@
+import type { Filter, Project, Task } from "./types";
+
+export function matchesFilter(task: Task, filter: Filter) {
+  const due = task.dueDate ? new Date(task.dueDate) : null;
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  if (filter === "all") return true;
+  if (filter === "done") return task.status === "done";
+  if (filter === "today") return Boolean(due && due.toDateString() === today.toDateString() && task.status !== "done");
+  return Boolean(due && due > today && task.status !== "done");
+}
+
+export function matchesQuery(task: Task, projects: Project[], query: string) {
+  if (!query.trim()) return true;
+  const projectName = projects.find((project) => project.id === task.projectId)?.name ?? "";
+  return [task.title, task.description ?? "", projectName, task.tags.join(" ")]
+    .join(" ")
+    .toLowerCase()
+    .includes(query.toLowerCase());
+}
+
+export function buildCounts(tasks: Task[]) {
+  return {
+    all: tasks.length,
+    today: tasks.filter((task) => matchesFilter(task, "today")).length,
+    upcoming: tasks.filter((task) => matchesFilter(task, "upcoming")).length,
+    done: tasks.filter((task) => task.status === "done").length
+  };
+}
+
+export function parseTags(value: string) {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function initials(name: string) {
+  return name
+    .split(" ")
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+}
+
+export function relativeDate(value: string) {
+  const date = new Date(value);
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const target = new Date(date);
+  target.setHours(0, 0, 0, 0);
+  const diff = Math.round((target.getTime() - today.getTime()) / 86400000);
+  if (diff === 0) return "Today";
+  if (diff === 1) return "Tomorrow";
+  if (diff === -1) return "Yesterday";
+  if (diff > 1) return `in ${diff} days`;
+  return `${Math.abs(diff)} days ago`;
+}
+
+export function formatDate(value: string) {
+  return new Date(value).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric"
+  });
+}
+
+export function addDays(days: number) {
+  const next = new Date();
+  next.setDate(next.getDate() + days);
+  return next.toISOString();
+}
+
+export function daysAgo(days: number) {
+  const previous = new Date();
+  previous.setDate(previous.getDate() - days);
+  return previous.toISOString();
+}

package/examples/taskflow/generated/web/TaskFlow/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": []
+}

package/examples/taskflow/generated/web/TaskFlow/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()]
+});

package/examples/taskflow/openuispec/README.md

@@ -0,0 +1,54 @@
+# TaskFlow — OpenUISpec
+
+This directory contains the **OpenUISpec** semantic UI specification for **TaskFlow**.
+
+**Start here:** read `openuispec.yaml` — it defines the project structure, data model, API endpoints, and generation targets (**ios, android, web**).
+
+## Directory structure
+
+| Directory | Contents |
+|-----------|----------|
+| `tokens/` | Design tokens — colors, typography, spacing, elevation, motion, icons, themes |
+| `screens/` | Screen definitions — one YAML file per screen |
+| `flows/` | Navigation flows — multi-step user journeys |
+| `contracts/` | Component contracts — standard extensions and custom (`x_` prefixed) |
+| `platform/` | Platform overrides — per-target (iOS, Android, Web) behaviors |
+| `locales/` | Localization — i18n strings (JSON, ICU MessageFormat) |
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read these reference files before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
+3. `examples/taskflow/openuispec/` — complete working example with all file types
+4. `schema/` — JSON Schemas for validation
+
+## CLI commands
+
+```bash
+openuispec validate             # Validate spec files against schemas
+openuispec validate semantic    # Check semantic cross-references
+openuispec validate screens     # Validate only screens
+openuispec configure-target ios [--defaults] # Configure target stack defaults
+openuispec status               # Show which targets are behind
+openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
+openuispec prepare --target ios           # Build the target work bundle
+openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios output exists
+```
+
+The target work bundle has two modes:
+- `bootstrap` when no snapshot exists yet, for first-time generation
+- `update` after a snapshot exists, for drift-based target updates
+
+## Learn more
+
+Docs: https://openuispec.rsteam.uz

package/examples/taskflow/{openuispec.yaml → openuispec/openuispec.yaml}

@@ -31,6 +31,8 @@ i18n:
 
 generation:
   targets: [ios, android, web]
+  code_roots:
+    backend: "../backend/"
   output_format:
     ios: { language: swift, framework: swiftui, min_version: "17.0" }
     android: { language: kotlin, framework: compose, min_sdk: 26 }

package/examples/todo-orbit/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.23 -->
+<!-- openuispec-rules-version: 0.1.28 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -20,7 +20,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root wrapper keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -55,33 +55,59 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
        type: scroll_vertical
    ```
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
-
-## Making UI changes
-1. Read the relevant spec files before modifying any UI code.
-2. If the change requires a spec update, modify the spec FIRST, then update code.
-3. Never modify generated code without updating the spec.
-4. When adding a new screen, create the corresponding spec file.
-5. When removing a screen, remove the spec file and update flow references.
-
-## After modifying spec files
-1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec validate semantic`.
-3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
-4. Run `openuispec prepare --target <target>` to build the target update bundle.
-5. **Update the generated code** for each affected platform to match the new spec.
-6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
-8. Run `openuispec status` to see which other targets are still behind.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
+
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the target work bundle for that target. In `bootstrap` mode it provides first-generation constraints; in `update` mode it provides drift-based update scope.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
 - `openuispec validate semantic` — run semantic cross-reference linting
+- `openuispec configure-target <t> [--defaults]` — configure target stack defaults
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
-- `openuispec drift --snapshot --target <t>` — snapshot current state
-- `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
+- `openuispec prepare --target <t>` — build the target work bundle
+- `openuispec status` — show cross-target baseline/drift status
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->

package/examples/todo-orbit/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.23 -->
+<!-- openuispec-rules-version: 0.1.28 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -20,7 +20,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root wrapper keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -55,33 +55,59 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
        type: scroll_vertical
    ```
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
-
-## Making UI changes
-1. Read the relevant spec files before modifying any UI code.
-2. If the change requires a spec update, modify the spec FIRST, then update code.
-3. Never modify generated code without updating the spec.
-4. When adding a new screen, create the corresponding spec file.
-5. When removing a screen, remove the spec file and update flow references.
-
-## After modifying spec files
-1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec validate semantic`.
-3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
-4. Run `openuispec prepare --target <target>` to build the target update bundle.
-5. **Update the generated code** for each affected platform to match the new spec.
-6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
-8. Run `openuispec status` to see which other targets are still behind.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
+
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the target work bundle for that target. In `bootstrap` mode it provides first-generation constraints; in `update` mode it provides drift-based update scope.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
 - `openuispec validate semantic` — run semantic cross-reference linting
+- `openuispec configure-target <t> [--defaults]` — configure target stack defaults
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
-- `openuispec drift --snapshot --target <t>` — snapshot current state
-- `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
+- `openuispec prepare --target <t>` — build the target work bundle
+- `openuispec status` — show cross-target baseline/drift status
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->

package/examples/todo-orbit/backend/.gitkeep

@@ -0,0 +1 @@
+

package/examples/todo-orbit/openuispec/README.md

@@ -27,9 +27,9 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
 
 **Reference files inside the package (read in this order):**
-1. `README.md` — schema tables, file format reference, root keys
+1. `README.md` — schema tables, file format reference, root wrapper keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for validation
 
 ## CLI commands
@@ -38,12 +38,17 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Check semantic cross-references
 openuispec validate screens     # Validate only screens
+openuispec configure-target ios [--defaults] # Configure target stack defaults
 openuispec status               # Show which targets are behind
 openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
-openuispec prepare --target ios           # Build an AI-ready ios update bundle
-openuispec drift --snapshot --target ios  # Snapshot current state + git baseline
+openuispec prepare --target ios           # Build the target work bundle
+openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios output exists
 ```
 
+The target work bundle has two modes:
+- `bootstrap` when no snapshot exists yet, for first-time generation
+- `update` after a snapshot exists, for drift-based target updates
+
 If a target snapshot was created before baseline metadata was added, `--explain` and `status` will ask you to re-run `openuispec drift --snapshot --target <target>` for that target.
 
 ## Learn more

package/examples/todo-orbit/openuispec/openuispec.yaml

@@ -29,6 +29,8 @@ generation:
   #   ios: "../ios-app/"                  # relative to this file
   #   android: "../android-app/"
   #   web: "../web-ui/"
+  code_roots:
+    backend: "../backend/"
   output_format:
     ios: { language: swift, framework: swiftui, min_version: "17.0" }
     android: { language: kotlin, framework: compose, min_sdk: 26 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",