openuispec 0.1.18 → 0.1.19

package/examples/todo-orbit/generated/web/Todo Orbit/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["src"]
+}

package/examples/todo-orbit/generated/web/Todo Orbit/vite.config.ts

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

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

@@ -0,0 +1,158 @@
+# Todo Orbit — OpenUISpec
+
+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.
+
+## 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 (variants, tokens) 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`
+
+## Screen and flow status
+
+- `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.
+
+## 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
+
+## CLI commands
+
+```bash
+openuispec validate             # Validate spec files against schemas
+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
+```
+
+## 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`.
+
+## 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`

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

@@ -0,0 +1,28 @@
+action_trigger:
+  tokens:
+    primary:
+      background: "color.brand.primary"
+      text: "color.brand.primary.on_color"
+      border: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+    ghost:
+      background: "color.surface.secondary"
+      text: "color.text.primary"
+      border: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+  platform_mapping:
+    ios:
+      primary: { shape: "CutCornerShape", clip: true, style: ".plain" }
+      ghost: { shape: "CutCornerShape", clip: true, style: ".plain" }
+    android:
+      primary: { shape: "CutCornerShape" }
+      ghost: { shape: "CutCornerShape" }
+    web:
+      primary: { style: "clip-path" }
+      ghost: { style: "clip-path" }
+  generation:
+    must_handle:
+      - "Cut top-left and bottom-right corners by cut_size for primary and ghost"
+      - "Preserve button hit area and loading state inside the cut shape"
+    should_handle:
+      - "Animate press/focus feedback without breaking the cut outline"

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

@@ -0,0 +1,32 @@
+collection:
+  tokens:
+    list:
+      item_min_height: 52
+      separator_color: "color.border.default"
+      separator_inset: "spacing.md"
+      content_padding: "spacing.none"
+    chips:
+      gap: "spacing.sm"
+      item_height: 36
+      item_padding_h: "spacing.md"
+      item_radius: 0
+      item_background: "color.surface.secondary"
+      item_background_selected: "color.brand.primary"
+  platform_mapping:
+    ios:
+      list: { widget: "List or LazyVStack", style: ".plain" }
+      chips: { widget: "ScrollView(.horizontal) + HStack" }
+    android:
+      list: { composable: "LazyColumn" }
+      chips: { composable: "LazyRow" }
+    web:
+      list: { element: "ul", class: "todo-list" }
+      chips: { element: "div", class: "chip-row" }
+  generation:
+    must_handle:
+      - "Preserve empty_state and pull_to_refresh behavior for task lists"
+      - "Render chips as single-select filters bound to state.active_filter"
+      - "Keep list item leading/trailing slots aligned across long task titles"
+    should_handle:
+      - "Use horizontal scrolling for chips on compact screens"
+      - "Apply selected chip styling with strong contrast against brand color"

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

@@ -0,0 +1,38 @@
+data_display:
+  tokens:
+    inline:
+      title_style: "typography.heading_lg"
+      subtitle_style: "typography.body_sm"
+      padding: "spacing.xs"
+    compact:
+      min_height: 52
+      padding_v: "spacing.sm"
+      padding_h: "spacing.md"
+      title_style: "typography.body"
+      subtitle_style: "typography.caption"
+      separator: { color: "color.border.default", inset_leading: "spacing.md" }
+    card:
+      background: "color.surface.secondary"
+      border: { width: 1, color: "color.border.default" }
+      radius: "spacing.sm"
+      padding: "spacing.md"
+      title_style: "typography.heading_sm"
+      subtitle_style: "typography.body_sm"
+  platform_mapping:
+    ios:
+      compact: { container: "HStack inside List row", emphasis: "rounded grouped inset" }
+      inline: { container: "VStack(alignment: .leading)" }
+    android:
+      compact: { composable: "ListItem", style: "supportingContent" }
+      inline: { composable: "Column" }
+    web:
+      compact: { element: "li", class: "todo-row" }
+      inline: { element: "div", class: "section-heading" }
+  generation:
+    must_handle:
+      - "Render compact task rows with clear title/subtitle hierarchy"
+      - "Support inline title/subtitle blocks for section headers"
+      - "Place leading and trailing subcomponents without collapsing text layout"
+    should_handle:
+      - "Use truncation for long titles while preserving priority/status indicators"
+      - "Keep compact rows visually aligned with checkbox leading controls"

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

@@ -0,0 +1,32 @@
+feedback:
+  tokens:
+    toast:
+      background: "color.surface.primary"
+      border: { width: 1, color: "color.border.default" }
+      radius: "spacing.sm"
+      padding: "spacing.md"
+      shadow: "elevation.md"
+      message_style: "typography.body_sm"
+    banner:
+      padding_v: "spacing.sm"
+      padding_h: "spacing.md"
+      border_leading: { width: 3, color_from: "severity" }
+      message_style: "typography.body_sm"
+  platform_mapping:
+    ios:
+      toast: { pattern: "custom overlay", position: "top" }
+      banner: { pattern: "inline error banner" }
+    android:
+      toast: { pattern: "custom composable", position: "top" }
+      banner: { pattern: "inline error banner" }
+    web:
+      toast: { pattern: "toast container", position: "top-right" }
+      banner: { element: "div", role: "alert", position: "inline-top" }
+  generation:
+    must_handle:
+      - "Map success and error feedback to distinct visuals and live-region behavior"
+      - "Auto-dismiss toast feedback after the declared duration"
+      - "Render banner feedback inline without shifting focus unexpectedly"
+    should_handle:
+      - "Stack multiple toasts without overlap"
+      - "Keep destructive/error banners visually anchored near the active form"

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

@@ -0,0 +1,52 @@
+input_field:
+  tokens:
+    text:
+      background: "color.surface.secondary"
+      border: { width: 2, color: "color.brand.primary" }
+      border_focused: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+    multiline:
+      background: "color.surface.secondary"
+      border: { width: 2, color: "color.brand.primary" }
+      border_focused: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+    select:
+      background: "color.surface.secondary"
+      border: { width: 2, color: "color.brand.primary" }
+      border_focused: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+    date:
+      background: "color.surface.secondary"
+      border: { width: 2, color: "color.brand.primary" }
+      border_focused: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+    number:
+      background: "color.surface.secondary"
+      border: { width: 2, color: "color.brand.primary" }
+      border_focused: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.sm"
+  platform_mapping:
+    ios:
+      text: { shape: "CutCornerShape", clip: true }
+      multiline: { shape: "CutCornerShape", clip: true }
+      select: { shape: "CutCornerShape", clip: true }
+      date: { shape: "CutCornerShape", clip: true }
+      number: { shape: "CutCornerShape", clip: true }
+    android:
+      text: { shape: "CutCornerShape" }
+      multiline: { shape: "CutCornerShape" }
+      select: { shape: "CutCornerShape" }
+      date: { shape: "CutCornerShape" }
+      number: { shape: "CutCornerShape" }
+    web:
+      text: { style: "clip-path" }
+      multiline: { style: "clip-path" }
+      select: { style: "clip-path" }
+      date: { style: "clip-path" }
+      number: { style: "clip-path" }
+  generation:
+    must_handle:
+      - "Cut top-left and bottom-right corners by cut_size for text-like inputs"
+      - "Keep focus, error, and disabled borders aligned with the cut shape"
+    should_handle:
+      - "Animate the emphasized border on focus without clipping content"

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

@@ -0,0 +1,47 @@
+nav_container:
+  tokens:
+    tab_bar:
+      height: 56
+      background: "color.surface.primary"
+      border_top: { width: 1, color: "color.border.default" }
+      icon_size: 22
+      label_style: "typography.caption"
+      active_color: "color.brand.primary"
+      inactive_color: "color.text.tertiary"
+    rail:
+      width: 76
+      background: "color.surface.secondary"
+      icon_size: 22
+      label_style: "typography.caption"
+      active_color: "color.brand.primary"
+    sidebar:
+      width: { collapsed: 72, expanded: 240 }
+      background: "color.surface.secondary"
+      item_height: 48
+      item_radius: "spacing.sm"
+      item_padding_h: "spacing.md"
+      active_background: "color.brand.primary"
+      active_text: "color.brand.primary.on_color"
+      icon_size: 20
+      label_style: "typography.body_sm"
+  platform_mapping:
+    ios:
+      tab_bar: { widget: "TabView" }
+      rail: { widget: "NavigationSplitView sidebar (compact rail)" }
+      sidebar: { widget: "NavigationSplitView sidebar" }
+    android:
+      tab_bar: { composable: "NavigationBar" }
+      rail: { composable: "NavigationRail" }
+      sidebar: { composable: "PermanentNavigationDrawer" }
+    web:
+      tab_bar: { element: "nav", pattern: "bottom fixed bar" }
+      rail: { element: "aside", pattern: "icon rail" }
+      sidebar: { element: "aside", pattern: "collapsible sidebar" }
+  generation:
+    must_handle:
+      - "Switch between tab_bar, rail, and sidebar according to adaptive screen config"
+      - "Keep the selected item visually distinct with active icon/text treatment"
+      - "Preserve keyboard navigation and accessible navigation landmarks"
+    should_handle:
+      - "Animate rail/sidebar transitions without layout jump"
+      - "Respect safe-area insets for bottom navigation on mobile targets"

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

@@ -0,0 +1,28 @@
+surface:
+  tokens:
+    sheet:
+      background: "color.surface.primary"
+      border: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.md"
+      shadow: "elevation.lg"
+    modal:
+      background: "color.surface.primary"
+      border: { width: 2, color: "color.brand.primary" }
+      cut_size: "spacing.md"
+      shadow: "elevation.lg"
+  platform_mapping:
+    ios:
+      sheet: { shape: "CutCornerShape", clip: true }
+      modal: { shape: "CutCornerShape", clip: true }
+    android:
+      sheet: { shape: "CutCornerShape" }
+      modal: { shape: "CutCornerShape" }
+    web:
+      sheet: { style: "clip-path" }
+      modal: { style: "clip-path" }
+  generation:
+    must_handle:
+      - "Apply the cut-corner silhouette to sheet and modal surfaces"
+      - "Maintain shadows and overlays without square corners bleeding through"
+    should_handle:
+      - "Preserve drag indicators and detents for sheets with the custom shape"

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

@@ -0,0 +1,134 @@
+x_schedule_preview:
+  semantic: "Previews upcoming occurrences for a recurring schedule based on the current form values"
+
+  props:
+    title: { type: string, required: false, description: "Optional title shown above the preview list" }
+    cadence:
+      type: enum
+      values: [daily, weekly, monthly]
+      required: true
+      description: "Schedule cadence used to compute upcoming dates"
+    interval: { type: int, required: true, description: "Gap between occurrences in cadence units" }
+    weekday:
+      type: enum
+      values: [mon, tue, wed, thu, fri, sat, sun]
+      required: false
+      description: "Weekday used for weekly schedules"
+    month_day: { type: int, required: false, description: "Day of month used for monthly schedules" }
+    start_date: { type: date, required: true, description: "Date from which occurrences begin" }
+    end_date: { type: date, required: false, description: "Optional date after which no occurrences are shown" }
+    preview_count: { type: int, default: 4, description: "Maximum number of upcoming occurrences to render" }
+    empty_message: { type: string, required: false, description: "Message shown when no occurrences can be produced" }
+    invalid_message: { type: string, required: false, description: "Message shown when the schedule is incomplete or invalid" }
+
+  states:
+    idle:
+      semantic: "Preview has not received enough input to compute occurrences"
+      transitions_to: [loading, invalid, ready]
+      visual: "Muted placeholder frame with instructional copy"
+    loading:
+      semantic: "Preview is recomputing the next occurrences"
+      transitions_to: [ready, invalid, empty]
+      duration: "motion.fast"
+      feedback: "Skeleton dates shown while the schedule is being recomputed"
+      visual: "Placeholder rows in the preview panel"
+    ready:
+      semantic: "Upcoming occurrences are available"
+      transitions_to: [loading, invalid, empty]
+      behavior: "Renders an ordered list of upcoming dates derived from the current props"
+      visual: "Date chips or list rows with the next occurrences"
+    invalid:
+      semantic: "The schedule is incomplete or contradictory"
+      transitions_to: [loading, ready]
+      feedback: "Inline guidance explains which fields must be completed"
+      visual: "Notice style with invalid_message copy"
+    empty:
+      semantic: "The schedule is technically valid but yields no future occurrences"
+      transitions_to: [loading, ready]
+      feedback: "Empty schedule message displayed"
+      visual: "Neutral empty state inside the preview panel"
+
+  a11y:
+    role: "group"
+    label: "props.title"
+    traits:
+      loading: { announces: "Refreshing recurring schedule preview" }
+      invalid: { announces: "Recurring schedule preview needs more information" }
+      empty: { announces: "No upcoming occurrences available" }
+    focus:
+      keyboard:
+        next_item: "ArrowDown"
+        previous_item: "ArrowUp"
+
+  tokens:
+    compact:
+      min_height: 132
+      padding: "spacing.md"
+      background: "color.surface.secondary"
+      border: { width: 1, color: "color.border.default" }
+      radius: "spacing.sm"
+      title_style: "typography.caption"
+      item_style: "typography.body_sm"
+      item_background: "color.surface.primary"
+      item_border: { width: 1, color: "color.border.default" }
+    detail:
+      min_height: 184
+      padding: "spacing.lg"
+      background: "color.surface.primary"
+      border: { width: 1, color: "color.brand.secondary" }
+      radius: "spacing.sm"
+      title_style: "typography.heading_sm"
+      item_style: "typography.body"
+      item_background: "color.surface.secondary"
+      item_border: { width: 1, color: "color.border.default" }
+
+  platform_mapping:
+    ios:
+      compact: { component: "SchedulePreviewCard", framework: "SwiftUI" }
+      detail: { component: "SchedulePreviewPanel", framework: "SwiftUI" }
+    android:
+      compact: { component: "SchedulePreviewCard", library: "compose foundation" }
+      detail: { component: "SchedulePreviewPanel", library: "compose foundation" }
+    web:
+      compact: { component: "SchedulePreviewCard", implementation: "react component" }
+      detail: { component: "SchedulePreviewPanel", implementation: "react component" }
+
+  dependencies:
+    ios:
+      frameworks: ["SwiftUI", "Foundation"]
+    android:
+      libraries: []
+    web:
+      packages: []
+
+  generation:
+    must_handle:
+      - "Derive the next preview_count schedule occurrences from cadence, interval, and start_date"
+      - "Respect weekday for weekly schedules and month_day for monthly schedules"
+      - "Transition to invalid when required inputs are missing or end_date is earlier than start_date"
+      - "Update the preview reactively as props change"
+      - "Render loading, ready, invalid, and empty states inside the same container"
+    should_handle:
+      - "Format preview dates using the active locale"
+      - "Highlight the nearest upcoming occurrence"
+      - "Animate list updates when the schedule changes"
+    may_handle:
+      - "Relative labels such as Today or Tomorrow when locale rules allow it"
+      - "Secondary captions describing the cadence in natural language"
+
+  test_cases:
+    - id: weekly_preview_generation
+      description: "Weekly schedules produce future dates on the selected weekday"
+      given: "cadence=weekly, interval=1, weekday=mon, start_date=2026-03-16"
+      when: "The preview enters ready state"
+      then: "The next preview_count Mondays from the start date are rendered in order"
+    - id: monthly_preview_generation
+      description: "Monthly schedules use the selected day of month"
+      given: "cadence=monthly, interval=1, month_day=15, start_date=2026-03-01"
+      when: "The preview enters ready state"
+      then: "The 15th of upcoming months is rendered until preview_count is reached"
+    - id: invalid_when_end_before_start
+      description: "Contradictory date ranges show invalid state"
+      given: "start_date is after end_date"
+      when: "The preview recomputes"
+      then: "The component enters invalid state and shows invalid_message"