openuispec 0.1.25 → 0.1.27

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

@@ -1,10 +1,8 @@
-# Todo Orbit — OpenUISpec
+# todo-orbit — OpenUISpec
 
-This directory contains the **OpenUISpec** semantic UI specification for **Todo Orbit**.
+This directory contains the **OpenUISpec** semantic UI specification for **todo-orbit**.
 
-OpenUISpec is a YAML-based format that describes your app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). The spec is the single source of truth across all platforms.
-
-Todo Orbit is a bilingual productivity sample that exercises task management, analytics, settings, and recurring-rule workflows across iOS, Android, and web targets.
+**Start here:** read `openuispec.yaml` — it defines the project structure, data model, API endpoints, and generation targets (**ios, android, web**).
 
 ## Directory structure
 
@@ -13,146 +11,41 @@ Todo Orbit is a bilingual productivity sample that exercises task management, an
 | `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 (variants, tokens) and custom (`x_` prefixed) |
+| `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) |
 
-All directory paths are configured in `openuispec.yaml` under `includes:` and support relative paths. For example, to share locales across projects:
-```yaml
-includes:
-  locales: "../../shared/locales"   # resolved relative to openuispec.yaml
-```
-
-## Getting started
-
-**Start here:** read `openuispec.yaml` — it's the root manifest that defines the project structure, data model, API endpoints, and generation targets.
-
-### New project (no existing UI code)
-
-1. Define your data model and API endpoints in `openuispec.yaml`
-2. Create token files in `tokens/` (colors, typography, spacing)
-3. Create screen specs in `screens/` (one YAML per screen)
-4. Create navigation flows in `flows/`
-5. Ask AI to generate native code from the spec
-
-### Existing project (adopting OpenUISpec)
-
-1. Scan the codebase for existing UI screens
-2. Create a stub for each screen in `screens/`:
-   ```yaml
-   screen_name:
-     semantic: "Brief description of what this screen does"
-     status: stub
-     layout:
-       type: scroll_vertical
-   ```
-3. Extract design tokens (colors, fonts, spacing) into `tokens/`
-4. Fill in `data_model` and `api.endpoints` in `openuispec.yaml`
-5. Spec screens incrementally: `stub` → `draft` → `ready`
+## IMPORTANT — Read the specification before working with spec files
 
-## Screen and flow status
+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.
 
-- `stub` — placeholder, not yet specced. Drift detection skips these.
-- `draft` — actively being specced. Tracked by drift.
-- `ready` — fully specified (default if omitted). Tracked by drift.
+**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)
 
-## Learning OpenUISpec — where to find the docs
-
-All documentation is included in the installed `openuispec` package. Search for it in this order:
-1. **Local:** `node_modules/openuispec/` (if installed as a project dependency)
-2. **Global:** run `npm root -g` to find the global prefix, then look in `<prefix>/openuispec/`
-3. **Online fallback:** if the package is not installed at all, fetch from:
-   - `https://openuispec.rsteam.uz/llms-full.txt` — complete spec + all JSON schemas in one file
-   - `https://openuispec.rsteam.uz/llms.txt` — concise summary with links
-
-Inside the package:
-- **Full specification:** `spec/openuispec-v0.1.md`
-- **Example app:** `examples/taskflow/`
-- **JSON Schemas:** `schema/`
-
-## Token file structure — root wrapper key required
-
-Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
-
-```yaml
-# ✅ Correct — tokens/typography.yaml
-typography:
-  font_family: ...
-  scale: ...
-
-# ❌ Wrong — missing root wrapper key
-font_family: ...
-scale: ...
-```
-
-Root keys: `color`, `typography`, `spacing`, `elevation`, `motion`, `layout`, `themes`, `icons`.
-
-## File formats and schemas
-
-**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Do not guess the file format.
-
-| File | Schema | Root key |
-|------|--------|----------|
-| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` |
-| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` |
-| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` |
-| `platform/*.yaml` | `platform.schema.json` | `platform` |
-| `locales/*.json` | `locale.schema.json` | (object) |
-| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` |
-| `tokens/color.yaml` | `tokens/color.schema.json` | `color` |
-| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` |
-| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` |
-| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` |
-| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` |
-| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` |
-| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` |
-| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` |
-
-All schemas are in `schema/` inside the installed package. Shared type definitions (actions, data-binding, adaptive, validation, common) are in `schema/defs/`.
-
-**Workflow:** read the schema → read an example from `examples/taskflow/` → create the YAML → run `openuispec validate`.
-
-## Spec format quick reference
-
-- **7 contract families:** nav_container, surface, action_trigger, input_field, data_display, collection, feedback
-- **Custom contracts:** prefixed with `x_` (e.g., `x_media_player`)
-- **Data binding:** `$data:`, `$state:`, `$param:`, `$t:` prefixes
-- **Actions:** typed objects — navigate, api_call, set_state, confirm, sequence, feedback, etc.
-- **Adaptive layout:** size classes (compact, regular, expanded) with per-section overrides
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
+3. `examples/taskflow/` — 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 drift --target ios    # Check for spec drift
-openuispec drift --snapshot --target ios  # Snapshot current state
-openuispec drift --all          # Include stubs in drift check
+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
 ```
 
-## Targets and output directories
-
-This project generates native code for: **ios, android, web**
-
-By default, drift stores state in `generated/<target>/<project>/`. To point targets to your actual code directories, add `output_dir` to `openuispec.yaml`:
-
-```yaml
-generation:
-  targets: [ios, android, web]
-  output_dir:
-    web: "../web-ui/"
-    android: "../kmp-ui/"
-    ios: "../kmp-ui/iosApp/"
-```
-
-Paths are relative to `openuispec.yaml`.
+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
 
-All docs and examples are in the installed `openuispec` package — check `node_modules/openuispec/` or run `npm root -g` for the global install path.
-
-- Full spec: `spec/openuispec-v0.1.md`
-- Example app: `examples/taskflow/`
-- JSON Schemas: `schema/`
-- Online reference: `https://openuispec.rsteam.uz/llms-full.txt`
+Docs: https://openuispec.rsteam.uz

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

@@ -96,6 +96,7 @@ create_recurring_rule:
 
                 - contract: input_field
                   input_type: select
+                  render_hint: segmented
                   props:
                     label: "$t:recurring_rule.field_cadence"
                     required: true
@@ -118,6 +119,7 @@ create_recurring_rule:
 
                 - contract: input_field
                   input_type: select
+                  render_hint: dropdown
                   props:
                     label: "$t:recurring_rule.field_weekday"
                     options:
@@ -199,6 +201,7 @@ create_recurring_rule:
 
                 - contract: input_field
                   input_type: select
+                  render_hint: segmented
                   props:
                     label: "$t:recurring_rule.field_summary_channel"
                     options:

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

@@ -73,6 +73,7 @@ create_task:
 
                 - contract: input_field
                   input_type: select
+                  render_hint: segmented
                   props:
                     label: "$t:create_task.field_priority"
                     options:

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

@@ -80,6 +80,7 @@ edit_task:
 
                 - contract: input_field
                   input_type: select
+                  render_hint: segmented
                   props:
                     label: "$t:edit_task.field_priority"
                     value: "task.priority"

package/examples/todo-orbit/openuispec/locales/en.json

@@ -33,6 +33,7 @@
   "analytics.empty_overdue": "No overdue tasks",
   "analytics.empty_overdue_body": "Everything important is on track.",
   "task_detail.status": "Status",
+  "task_detail.title": "Task details",
   "task_detail.priority": "Priority",
   "task_detail.notes": "Notes",
   "task_detail.due_date": "Due date",

package/examples/todo-orbit/openuispec/locales/ru.json

@@ -33,6 +33,7 @@
   "analytics.empty_overdue": "Просроченных задач нет",
   "analytics.empty_overdue_body": "Все важные задачи идут по плану.",
   "task_detail.status": "Статус",
+  "task_detail.title": "Детали задачи",
   "task_detail.priority": "Приоритет",
   "task_detail.notes": "Заметки",
   "task_detail.due_date": "Срок",

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

@@ -1,5 +1,6 @@
 task_detail:
   semantic: "Displays full task information with edit, status, and destructive actions"
+  title: "$t:task_detail.title"
   status: ready
 
   params:

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

@@ -27,6 +27,12 @@ icons:
           ios: "plus"
           android: "add"
           web: "plus"
+      pencil:
+        semantic: "Edit an existing task or item"
+        platform:
+          ios: "pencil"
+          android: "edit"
+          web: "pencil"
       search:
         semantic: "Search tasks"
         platform:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",
@@ -12,6 +12,8 @@
   "files": [
     "cli/",
     "drift/",
+    "prepare/",
+    "status/",
     "schema/",
     "spec/",
     "docs/",
@@ -23,6 +25,7 @@
     "openuispec": "./cli/index.ts"
   },
   "scripts": {
+    "test": "node --import tsx --test tests/*.test.ts",
     "validate": "tsx schema/validate.ts",
     "validate:manifest": "tsx schema/validate.ts manifest",
     "validate:tokens": "tsx schema/validate.ts tokens",
@@ -32,6 +35,8 @@
     "validate:locales": "tsx schema/validate.ts locales",
     "drift": "tsx drift/index.ts",
     "drift:snapshot": "tsx drift/index.ts --snapshot --target",
+    "prepare:target": "tsx prepare/index.ts",
+    "status": "tsx status/index.ts",
     "postinstall": "echo \"\\n  ✓ openuispec installed — if upgrading, run: openuispec update-rules\\n\""
   },
   "dependencies": {