openuispec 0.2.13 → 0.2.15

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
 
 ---
 
@@ -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"
@@ -3167,6 +3169,8 @@ Use a custom contract when the component:
 
 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"
 
@@ -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"

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

@@ -1,139 +0,0 @@
-x_task_trend_chart:
-  semantic: "Visualizes task creation and completion trends over time for productivity analysis"
-
-  props:
-    series: { type: "list<trend_point>", required: true, description: "Ordered trend points for the selected period" }
-    metric:
-      type: enum
-      values: [completed, created, completion_rate]
-      required: true
-      description: "Primary metric emphasized in the chart"
-    period:
-      type: enum
-      values: [week, month, quarter]
-      required: true
-      description: "Time range represented by the chart"
-    variant:
-      type: enum
-      values: [compact, detail]
-      default: compact
-      description: "Chart presentation density"
-    highlighted_index: { type: int, required: false, description: "Optional highlighted datapoint" }
-    show_legend: { type: bool, default: true, description: "Whether to render a legend for created/completed series" }
-    empty_message: { type: string, required: false, description: "Message to show when series is empty" }
-
-  states:
-    idle:
-      semantic: "Chart has not loaded data yet"
-      transitions_to: [loading]
-      visual: "Reserved chart frame with no plotted data"
-    loading:
-      semantic: "Trend data is loading"
-      transitions_to: [ready, empty, error]
-      feedback: "Skeleton chart and loading copy shown"
-      visual: "Placeholder bars or line skeleton"
-    ready:
-      semantic: "Trend data is available and rendered"
-      transitions_to: [highlighted, loading, error]
-      behavior: "Chart axes, series, and legend are visible"
-    highlighted:
-      semantic: "One datapoint is emphasized"
-      transitions_to: [ready]
-      behavior: "Highlighted datapoint shows stronger color and tooltip/callout"
-    empty:
-      semantic: "No trend points available"
-      transitions_to: [loading]
-      feedback: "Empty analytics message displayed"
-      visual: "Empty state in chart container"
-    error:
-      semantic: "Trend data failed to load"
-      transitions_to: [loading]
-      feedback: "Inline error with retry affordance"
-      visual: "Error indicator in chart container"
-
-  a11y:
-    role: "img"
-    label: "Analytics trend chart"
-    traits:
-      loading: { announces: "Loading analytics chart" }
-      empty: { announces: "No analytics data available" }
-      error: { announces: "Analytics chart failed to load" }
-    focus:
-      keyboard:
-        next_point: "ArrowRight"
-        previous_point: "ArrowLeft"
-        details: "Enter"
-
-  tokens:
-    compact:
-      min_height: 220
-      padding: "spacing.md"
-      background: "color.surface.secondary"
-      border: { width: 1, color: "color.border.default" }
-      radius: "spacing.sm"
-      axis_color: "color.text.tertiary"
-      completed_color: "color.brand.primary"
-      created_color: "color.brand.secondary"
-      grid_color: "color.border.default"
-      label_style: "typography.caption"
-    detail:
-      min_height: 320
-      padding: "spacing.lg"
-      background: "color.surface.primary"
-      border: { width: 1, color: "color.border.default" }
-      radius: "spacing.sm"
-      axis_color: "color.text.tertiary"
-      completed_color: "color.brand.primary"
-      created_color: "color.brand.secondary"
-      grid_color: "color.border.default"
-      label_style: "typography.body_sm"
-
-  platform_mapping:
-    ios:
-      compact: { component: "Chart", framework: "Swift Charts" }
-      detail: { component: "Chart", framework: "Swift Charts" }
-    android:
-      compact: { component: "Canvas chart composable", library: "custom compose drawing" }
-      detail: { component: "Canvas chart composable", library: "custom compose drawing" }
-    web:
-      compact: { component: "SVG chart component" }
-      detail: { component: "SVG chart component" }
-
-  dependencies:
-    ios:
-      frameworks: ["Charts"]
-    android:
-      libraries: []
-    web:
-      packages: []
-
-  generation:
-    must_handle:
-      - "Render completed and created series for the supplied period"
-      - "Respect compact and detail variants with different density"
-      - "Provide accessible summary text for the focused datapoint"
-      - "Handle loading, empty, and error states in the chart container"
-    should_handle:
-      - "Animate transitions when highlighted_index changes"
-      - "Render a legend when show_legend is true"
-      - "Support touch and pointer hover highlighting"
-    may_handle:
-      - "Tooltips for datapoints"
-      - "Trend delta badges and annotations"
-
-  test_cases:
-    - id: ready_state_renders_series
-      description: "Chart renders series lines or bars when data is present"
-      given: "Chart receives 7 trend points for period week"
-      when: "The component enters ready state"
-      then: "Both created and completed series are visible with labels and axes"
-    - id: empty_state_message
-      description: "Chart shows an empty message when no data exists"
-      given: "Chart receives an empty series"
-      when: "The component enters empty state"
-      then: "The empty_message or default empty copy is rendered in the chart frame"
-    - id: highlighted_point
-      description: "Highlighted point receives emphasis"
-      given: "Chart is in ready state with highlighted_index set"
-      when: "The highlighted datapoint is rendered"
-      then: "That datapoint is visually emphasized and exposed to accessibility"