openuispec 0.2.12 → 0.2.14

package/spec/{openuispec-v0.1.md → openuispec-v0.2.md}

@@ -1,11 +1,11 @@
-# OpenUISpec v0.1
+# OpenUISpec v0.2
 
 > A single source of truth design language for AI-native, platform-native app development.
 
-**Status:** Draft  
-**Version:** 0.1  
-**Authors:** Rustam Samandarov  
-**Last updated:** 2026-03-13
+**Status:** Draft
+**Version:** 0.2
+**Authors:** Rustam Samandarov
+**Last updated:** 2026-03-19
 
 ---
 
@@ -19,7 +19,7 @@ OpenUISpec is a shared UI sync language for native products, optimized for solo
 
 1. **Semantic over visual.** The spec defines behavioral intent, not pixel layouts. A "primary action trigger" maps to `Button` in SwiftUI, `Button` in Compose, and `<button>` in HTML — the spec never says "button."
 2. **Constrained freedom.** Tokens use ranges, not exact values. Close enough to be recognizably the same brand; loose enough for each platform to feel native.
-3. **Contract-driven.** Every component is a behavioral contract with typed props, a state machine, and accessibility requirements. If a state exists in the spec, the generated code must handle it.
+3. **Contract-driven.** Every UI component is a reusable contract with typed props, UI interaction states (pressed, disabled, loading, error — not business logic states), and accessibility requirements. If a UI state exists in the spec, the generated code must handle it.
 4. **AI-first authoring.** The spec is structured for machine consumption: strongly typed, validatable, with generation hints that tell AI what it must, should, and may produce.
 5. **Platform respect.** iOS should feel like iOS. Android should feel like Android. Web should feel like the web. The spec preserves platform identity; it does not erase it.
 
@@ -49,6 +49,8 @@ project/
 │   ├── surface.yaml
 │   ├── collection.yaml
 │   └── x_media_player.yaml    # Custom contract (Section 12)
+├── components/
+│   └── media_player.yaml      # Component composition (Section 15)
 ├── screens/
 │   ├── home.yaml
 │   ├── order_detail.yaml
@@ -68,7 +70,7 @@ project/
 
 ```yaml
 # openuispec.yaml
-spec_version: "0.1"
+spec_version: "0.2"
 project:
   name: "MyApp"
   description: "A sample application defined in OpenUISpec"
@@ -555,7 +557,7 @@ The `custom` section follows the same shape as `registry` categories. App-specif
 
 ## 4. Component contracts
 
-Each contract defines a **behavioral family** — a category of UI elements that share the same role, props shape, state machine, and accessibility pattern. The AI maps each contract to the most appropriate native widget per platform.
+Each contract defines a **reusable UI component family** — a category of UI elements that share the same role, props shape, UI interaction states, and accessibility pattern. The AI maps each contract to the most appropriate native widget per platform. Contracts describe how components look and respond to user interaction — they are UI rendering specifications, not business logic or domain state machines.
 
 ### Contract anatomy
 
@@ -565,7 +567,7 @@ Every contract contains:
 |---------|---------|----------|
 | `semantic` | Human-readable description of what this family does | Yes |
 | `props` | Typed inputs the component accepts | Yes |
-| `states` | Finite state machine with valid transitions | Yes |
+| `states` | UI interaction states (e.g. idle, pressed, disabled, loading, error) with valid transitions | Yes |
 | `a11y` | Accessibility role, label pattern, focus behavior | Yes |
 | `tokens` | Visual token bindings per variant | Yes |
 | `platform_mapping` | Default native widget per platform | Yes |
@@ -1765,7 +1767,7 @@ When omitted, the item contract's default variant is used.
 
 #### `state_binding`
 
-Binds a contract's state machine states to data paths. This allows screen-level data to drive contract states declaratively, without requiring an explicit action.
+Binds a contract's UI interaction states to data paths. This allows screen-level data to drive contract states declaratively, without requiring an explicit action.
 
 ```yaml
 - contract: action_trigger
@@ -1783,7 +1785,7 @@ Binds a contract's state machine states to data paths. This allows screen-level
 - Values must be data paths that resolve to `bool`
 - When the bound value is `true`, the contract transitions to that state
 - When the bound value returns to `false`, the contract transitions back to `default`
-- If multiple state bindings are `true` simultaneously, priority follows the contract's state machine (e.g., `loading` takes precedence over `disabled`)
+- If multiple state bindings are `true` simultaneously, priority follows the contract's state priority order (e.g., `loading` takes precedence over `disabled`)
 
 ---
 
@@ -2966,7 +2968,7 @@ props:
 condition: "tasks.$empty"
 ```
 
-Collection contracts handle `$loading`, `$error`, and `$empty` automatically via their state machines (see Section 4.7). For non-collection data, screens can use `condition:` to show appropriate UI.
+Collection contracts handle `$loading`, `$error`, and `$empty` automatically via their built-in UI states (see Section 4.7). For non-collection data, screens can use `condition:` to show appropriate UI.
 
 ### 10.9 AI generation requirements
 
@@ -3161,12 +3163,14 @@ Custom contracts allow spec authors to define domain-specific component families
 Use a custom contract when the component:
 
 - Has domain-specific behavior that doesn't map cleanly to any built-in family
-- Requires a dedicated state machine (e.g., play/pause/seek for media)
+- Requires dedicated UI interaction states (e.g., play/pause/seek for media)
 - Needs platform-specific libraries or frameworks not covered by core contracts
 - Would clutter the core spec if included as a built-in
 
 Do **not** use a custom contract when a built-in family with the right variant already covers the use case. A data card is `data_display`, not `x_data_card`.
 
+> **Prefer components over custom contracts** when the UI block is a composition of multiple contracts (e.g., a media player with play button, scrubber, and time label). Components (Section 15) provide named slots, states, variants, and screen-level overrides. Reserve `x_` custom contracts for truly atomic, domain-specific widgets that don't decompose into smaller contracts.
+
 ### 12.2 Naming
 
 Custom contract names **MUST**:
@@ -3271,7 +3275,7 @@ Custom contracts are registered in the root manifest via the `custom_contracts`
 
 ```yaml
 # openuispec.yaml
-spec_version: "0.1"
+spec_version: "0.2"
 project:
   name: "MyApp"
 
@@ -3327,7 +3331,7 @@ ios:
 
 **MUST:**
 - Read and parse all registered custom contract definitions before generating code
-- Handle every declared state in the state machine
+- Handle every declared UI interaction state
 - Apply `platform_mapping` to select the correct native component
 - Include all `dependencies` in the generated project configuration (Package.swift, build.gradle, package.json)
 - Implement all items listed in `generation.must_handle`
@@ -3822,7 +3826,7 @@ A drift detector compares:
 - **Spec → Code**: Does the generated code match what the spec describes? (e.g., a button's action type, a screen's data sources, a flow's step order)
 - **Code → Spec**: Does the current platform code contain UI decisions not reflected in the spec? (e.g., a new field added to a form, a navigation path changed)
 
-Drift detection is scoped to the semantic layer — it compares behavioral intent (contracts, props, state machines, data bindings), not visual details (padding values, animation curves). Platform-specific polish is expected to diverge from the spec; behavioral contracts are not.
+Drift detection is scoped to the semantic layer — it compares behavioral intent (contracts, props, UI interaction states, data bindings), not visual details (padding values, animation curves). Platform-specific polish is expected to diverge from the spec; behavioral contracts are not.
 
 Resolution strategies:
 - **Update spec** — The code change is intentional; update the spec to match
@@ -3841,6 +3845,259 @@ This is the spec's primary value beyond code generation: it gives cross-platform
 
 ---
 
+## 15. Component composition
+
+Components fill the gap between atomic contracts and full-page screens. A component is a **reusable composition of contracts with named slots** — think of a media player composed of a play button, scrubber, time label, and volume control, each backed by a base contract.
+
+```
+Tokens → Contracts → Components → Screens → Flows
+         (atomic)    (composed)   (full page)
+```
+
+Components live in the `components/` directory referenced by `includes.components` in the manifest.
+
+### 15.1 Component definition format
+
+Each YAML file contains a single root key — the component name — mapping to a `component_def`:
+
+```yaml
+# components/media_player.yaml
+media_player:
+  semantic: "Plays audio and video media with transport controls"
+
+  props:
+    source: { type: string, required: true }
+    media_type: { type: enum, values: [audio, video], required: true }
+    title: { type: string }
+
+  slots:
+    play_button:
+      contract: action_trigger
+      variant: icon
+      props: { label: "$t:media_player.play", icon: play }
+      hideable: true
+    scrubber:
+      contract: input_field
+      input_type: slider
+      props: { label: "$t:media_player.progress" }
+      hideable: true
+    time_label:
+      contract: data_display
+      variant: caption
+      hideable: true
+    volume_control:
+      contract: input_field
+      input_type: slider
+      hideable: true
+
+  layout:
+    type: stack
+    spacing: "spacing.sm"
+    sections:
+      - slot: play_button
+      - slot: scrubber
+      - layout:
+          type: row
+          sections:
+            - slot: time_label
+            - slot: volume_control
+
+  states:
+    idle: { semantic: "No media loaded" }
+    loading:
+      semantic: "Buffering"
+      hide_slots: [scrubber, volume_control]
+    playing:
+      semantic: "Actively playing"
+      slot_overrides:
+        play_button: { props: { icon: pause } }
+    paused:
+      semantic: "Paused at position"
+      slot_overrides:
+        play_button: { props: { icon: play } }
+
+  variants:
+    mini:
+      semantic: "Compact player for persistent bottom bar"
+      hide_slots: [volume_control]
+      layout:
+        type: row
+        sections:
+          - slot: play_button
+          - slot: scrubber
+          - slot: time_label
+    fullscreen:
+      semantic: "Full-screen immersive player"
+      tokens: { background: "#000000" }
+
+  tokens:
+    background: "color.surface.secondary"
+    radius: "spacing.md"
+    padding: "spacing.md"
+
+  a11y:
+    role: "group"
+    label: "props.title"
+
+  platform_mapping:
+    ios: { component: "VideoPlayer", framework: "AVKit" }
+    android: { component: "PlayerView", library: "androidx.media3" }
+    web: { element: "div", role: "region" }
+
+  generation:
+    must_handle: ["All slots must render with correct contract types"]
+```
+
+### 15.2 Anatomy
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| `semantic` | Human-readable description of what this component does | Yes |
+| `slots` | Named contract instances that make up the component | Yes |
+| `props` | Typed inputs the component accepts (passed via data binding) | No |
+| `layout` | Spatial arrangement of slots using layout primitives | No |
+| `states` | Composite states that control slot visibility and props | No |
+| `variants` | Named presets that hide slots, change layout, or override tokens | No |
+| `tokens` | Visual token bindings for the component container | No |
+| `a11y` | Accessibility role and label pattern | No |
+| `platform_mapping` | Per-platform native component hints | No |
+| `dependencies` | Platform-specific library requirements | No |
+| `generation` | AI generation hints (must_handle, should_handle, may_handle) | No |
+| `test_cases` | Behavioral verification scenarios | No |
+
+### 15.3 Slots
+
+A **slot** is a named position within a component that renders a base contract. Each slot specifies:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `contract` | `contract_ref` | Yes | The base contract family (e.g. `action_trigger`, `data_display`) |
+| `variant` | `string` | No | Default variant for the contract |
+| `input_type` | `string` | No | Input type (for `input_field` contracts) |
+| `props` | `object` | No | Default props passed to the contract |
+| `hideable` | `bool` | No | Whether this slot can be hidden from screens or by states |
+| `tokens_override` | `object` | No | Token overrides for this slot |
+
+Slots reference **base contracts only** — components cannot nest other components (v1 keeps it flat).
+
+### 15.4 States
+
+Component states are **composite states** that control slot visibility and override slot props. They differ from contract states (Section 4): contract states describe UI interaction states of a single widget (pressed, disabled, loading); component states describe the state of the entire composition (playing, paused, buffering).
+
+Each state can specify:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `semantic` | `string` | What this state means |
+| `hide_slots` | `string[]` | Slots to hide when this state is active |
+| `slot_overrides` | `object` | Per-slot prop/variant overrides |
+| `transitions_to` | `string[]` | Valid next states |
+
+### 15.5 Variants
+
+Variants are named presets that change the component's appearance or slot arrangement:
+
+```yaml
+variants:
+  mini:
+    semantic: "Compact player for persistent bottom bar"
+    hide_slots: [volume_control]
+    layout:
+      type: row
+      sections:
+        - slot: play_button
+        - slot: scrubber
+        - slot: time_label
+```
+
+A variant can specify:
+- `semantic` — What this variant is for
+- `hide_slots` — Slots to remove in this variant
+- `layout` — Alternative slot arrangement
+- `tokens` — Token overrides for this variant
+- `slot_overrides` — Per-slot prop/variant overrides
+
+### 15.6 Slot resolution order
+
+When a component is rendered, slot properties are resolved by layering overrides from most general to most specific:
+
+```
+slot default → variant override → state override → screen-level override
+```
+
+Most specific wins. Screen-level overrides always have final say. If a slot is hidden at any level (variant `hide_slots`, state `hide_slots`, or screen-level `hidden: true`), it is not rendered.
+
+### 15.7 Usage in screens
+
+Components are used in screens via the `component` key (instead of `contract`):
+
+```yaml
+# screens/task_detail.yaml
+- component: media_player
+  variant: mini
+  props:
+    source: "{task.attachment.url}"
+    media_type: "{task.attachment.media_type}"
+  slots:
+    volume_control: { hidden: true }
+    play_button:
+      variant: branded
+      tokens_override: { background: "color.brand.primary" }
+```
+
+**Screen-level slot overrides** can:
+- Change the slot's `variant`
+- Override `props`
+- Apply `tokens_override`
+- Set `hidden: true` to suppress the slot (only if the slot is declared `hideable: true`)
+
+### 15.8 Components vs. custom contracts
+
+| Aspect | Component | Custom contract (`x_`) |
+|--------|-----------|----------------------|
+| Structure | Composition of base contracts via slots | Single atomic widget |
+| Customization | Slots can be restyled, repositioned, swapped, or hidden | Props and tokens only |
+| States | Composite states controlling slot visibility | UI interaction states (pressed, loading, error) |
+| Layout | Defines spatial arrangement of slots | Opaque — platform decides layout |
+| Use when | The UI block decomposes into smaller contracts | The widget is truly atomic and domain-specific |
+| Examples | Media player, wizard, conversation timeline | Status badge, SLA indicator, sparkline chart |
+
+### 15.9 Registration
+
+Components are registered in the manifest's `includes` section:
+
+```yaml
+# openuispec.yaml
+includes:
+  tokens: "./tokens/"
+  contracts: "./contracts/"
+  components: "./components/"
+  screens: "./screens/"
+  # ...
+```
+
+Each `.yaml` file in the components directory defines one component. The file must contain exactly one root key matching the component name (no `x_` prefix — that is reserved for custom contracts).
+
+### 15.10 AI generation requirements
+
+**MUST:**
+- Read all component definitions before generating code
+- Render every non-hidden slot with the correct base contract type
+- Apply the slot resolution order (Section 15.6) correctly
+- Support variant selection from screens
+- Include `dependencies` in generated project configuration
+
+**SHOULD:**
+- Implement component states with correct slot visibility transitions
+- Apply component-level and slot-level token overrides
+- Generate accessibility support matching the `a11y` definition
+
+**MAY:**
+- Generate test code based on `test_cases`
+- Add platform-specific enhancements via `platform_mapping`
+
+---
+
 ## Appendix A: Type reference
 
 | Type | Description | Example |
@@ -3853,6 +4110,7 @@ This is the spec's primary value beyond code generation: it gives cross-platform
 | `media_ref` | Image/video reference | `"assets/hero.jpg"` |
 | `color_ref` | Token path | `"color.brand.primary"` |
 | `component_ref` | Inline contract instance | `{ contract: data_display, ... }` |
+| `composed_component_ref` | Component name from `components/` | `"media_player"` |
 | `contract_ref` | Contract family name | `"action_trigger"` |
 | `screen_ref` | Screen identifier | `"screens/order_detail"` |
 | `action` | Action definition (see Section 9) | `{ type: navigate, destination: "..." }` |
@@ -3884,4 +4142,4 @@ This is the spec's primary value beyond code generation: it gives cross-platform
 
 ---
 
-*OpenUISpec v0.1 — Draft specification. Subject to revision.*
+*OpenUISpec v0.2 — Draft specification. Subject to revision.*

package/examples/taskflow/openuispec/contracts/x_media_player.yaml

@@ -1,185 +0,0 @@
-# ============================================================
-# Custom Contract: x_media_player
-# ============================================================
-# A media playback contract for audio and video content.
-# Demonstrates the custom contract extension mechanism
-# (see spec Section 12).
-# ============================================================
-
-x_media_player:
-  semantic: "Plays audio and video media with transport controls, state management, and platform-native playback"
-
-  props:
-    source: { type: string, required: true, description: "Media URL or asset path" }
-    media_type:
-      type: enum
-      values: [audio, video]
-      required: true
-      description: "Type of media content"
-    variant:
-      type: enum
-      values: [inline, fullscreen, mini]
-      default: inline
-      description: "Player presentation style"
-    autoplay: { type: bool, default: false, description: "Begin playback automatically when source loads" }
-    loop: { type: bool, default: false, description: "Restart playback when media ends" }
-    show_controls: { type: bool, default: true, description: "Display transport controls" }
-    poster: { type: media_ref, required: false, description: "Preview image shown before playback (video only)" }
-    title: { type: string, required: false, description: "Media title for display and accessibility" }
-    subtitle: { type: string, required: false, description: "Secondary text (artist, channel, etc.)" }
-    playback_rate: { type: enum, values: ["0.5", "0.75", "1", "1.25", "1.5", "2"], default: "1", description: "Playback speed multiplier" }
-    muted: { type: bool, default: false, description: "Start with audio muted" }
-
-  states:
-    idle:
-      semantic: "No media loaded or playback not started"
-      transitions_to: [loading]
-      visual: "Shows poster image or placeholder; controls hidden or minimal"
-    loading:
-      semantic: "Media source is buffering"
-      transitions_to: [playing, error]
-      duration: "motion.standard"
-      feedback: "Loading indicator visible"
-      visual: "Spinner or progress bar overlaid on poster"
-    playing:
-      semantic: "Media is actively playing"
-      transitions_to: [paused, ended, loading, error]
-      behavior: "Progress bar advances, elapsed time updates"
-      visual: "Active playback with visible progress and controls"
-    paused:
-      semantic: "Playback is paused at current position"
-      transitions_to: [playing, loading]
-      visual: "Frozen frame (video) or paused waveform (audio); play button prominent"
-    ended:
-      semantic: "Playback reached the end of the media"
-      transitions_to: [playing, loading]
-      behavior: "If loop is true, transitions to playing automatically"
-      visual: "Replay button visible; poster or last frame shown"
-    error:
-      semantic: "Media failed to load or playback encountered an error"
-      transitions_to: [loading]
-      feedback: "Error message displayed with retry option"
-      visual: "Error icon and message; retry button visible"
-
-  a11y:
-    role: "media"
-    label: "props.title"
-    traits:
-      playing: { announces: "Playing" }
-      paused: { announces: "Paused" }
-      loading: { announces: "Loading media" }
-      error: { announces: "Media playback error" }
-    focus:
-      keyboard:
-        play_pause: "Space"
-        seek_forward: "ArrowRight"
-        seek_backward: "ArrowLeft"
-        volume_up: "ArrowUp"
-        volume_down: "ArrowDown"
-        fullscreen: "f"
-        mute: "m"
-
-  tokens:
-    inline:
-      min_height: [200, 280]
-      radius: "spacing.md"
-      background: "color.surface.secondary"
-      controls_background: "rgba(0, 0, 0, 0.5)"
-      controls_color: "#FFFFFF"
-      progress_active: "color.brand.primary"
-      progress_inactive: "rgba(255, 255, 255, 0.3)"
-      progress_height: [3, 4]
-      title_style: "typography.caption"
-      subtitle_style: "typography.small"
-    fullscreen:
-      background: "#000000"
-      controls_background: "rgba(0, 0, 0, 0.6)"
-      controls_color: "#FFFFFF"
-      progress_active: "color.brand.primary"
-      progress_inactive: "rgba(255, 255, 255, 0.3)"
-      progress_height: [4, 6]
-      title_style: "typography.subtitle"
-      subtitle_style: "typography.body"
-    mini:
-      height: [48, 64]
-      radius: "spacing.sm"
-      background: "color.surface.secondary"
-      progress_active: "color.brand.primary"
-      progress_height: [2, 3]
-      title_style: "typography.caption"
-
-  platform_mapping:
-    ios:
-      inline: { component: "VideoPlayer", framework: "AVKit" }
-      fullscreen: { component: "AVPlayerViewController", framework: "AVKit" }
-      mini: { component: "Custom mini player view", framework: "AVKit" }
-      audio: { component: "Custom audio player", framework: "AVFoundation" }
-    android:
-      inline: { component: "PlayerView", library: "androidx.media3" }
-      fullscreen: { component: "PlayerView (fullscreen activity)", library: "androidx.media3" }
-      mini: { component: "Custom mini player composable", library: "androidx.media3" }
-      audio: { component: "PlayerView (audio mode)", library: "androidx.media3" }
-    web:
-      inline: { element: "video", fallback: "audio" }
-      fullscreen: { element: "video", api: "Fullscreen API" }
-      mini: { element: "Custom mini player component" }
-      audio: { element: "audio" }
-
-  dependencies:
-    ios:
-      frameworks: [AVKit, AVFoundation]
-    android:
-      libraries: ["androidx.media3:media3-ui", "androidx.media3:media3-exoplayer"]
-    web:
-      packages: []
-
-  generation:
-    must_handle:
-      - "All 6 states (idle, loading, playing, paused, ended, error) with correct transitions"
-      - "Keyboard shortcuts for accessibility (Space, arrows, f, m)"
-      - "Poster/placeholder display in idle state"
-      - "Error state with retry action"
-      - "Platform-native player component per platform_mapping"
-    should_handle:
-      - "Playback rate selection UI"
-      - "Progress bar with seek interaction"
-      - "Volume control"
-      - "Elapsed / remaining time display"
-      - "Mini variant with compact controls"
-    may_handle:
-      - "Picture-in-picture support (iOS, web)"
-      - "AirPlay / Cast integration"
-      - "Subtitle / closed caption support"
-      - "Background audio playback"
-      - "Gesture controls (swipe to seek, pinch to zoom)"
-
-  test_cases:
-    - id: play_pause_toggle
-      description: "Tapping play starts playback; tapping pause freezes it"
-      given: "Player is in idle state with a valid source"
-      when: "User taps the play button"
-      then: "State transitions to loading, then playing; tapping pause transitions to paused"
-
-    - id: error_retry
-      description: "Failed media shows error with retry"
-      given: "Player source URL is unreachable"
-      when: "Player attempts to load the media"
-      then: "State transitions to error; retry button is visible; tapping retry transitions to loading"
-
-    - id: ended_loop
-      description: "Loop restarts playback at end"
-      given: "Player is playing with loop=true"
-      when: "Media reaches the end"
-      then: "State transitions to playing from the beginning without user interaction"
-
-    - id: keyboard_controls
-      description: "Keyboard shortcuts control playback"
-      given: "Player is focused and in playing state"
-      when: "User presses Space"
-      then: "State transitions to paused; pressing Space again transitions to playing"
-
-    - id: fullscreen_variant
-      description: "Fullscreen variant fills the viewport"
-      given: "Player variant is fullscreen"
-      when: "Player renders"
-      then: "Player fills the screen with black background; controls overlay the content"