openuispec 0.1.0

package/examples/taskflow/contracts/x_media_player.yaml

@@ -0,0 +1,185 @@
+# ============================================================
+# 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/taskflow/flows/create_task.yaml

@@ -0,0 +1,171 @@
+# ============================================================
+# TaskFlow — Create Task Flow
+# ============================================================
+# Exercises: input_field (text, multiline, select, date, toggle),
+#            action_trigger, feedback (toast, banner), surface
+# ============================================================
+
+create_task:
+  semantic: "Multi-step flow to create a new task"
+
+  entry: "task_form"
+
+  # Single-screen flow presented as a sheet
+  screens:
+    task_form:
+      screen_inline:
+        semantic: "Task creation form with all input types"
+
+        state:
+          is_submitting: { type: bool, default: false }
+
+        layout:
+          type: scroll_vertical
+          safe_area: true
+          padding: "spacing.page_margin"
+
+          sections:
+            # ---------- Sheet header ----------
+            - id: header
+              layout: { type: row, justify: "space-between", align: "center" }
+              children:
+                - contract: action_trigger
+                  variant: ghost
+                  size: sm
+                  props: { label: "$t:common.cancel" }
+                  action: { type: dismiss }
+
+                - contract: data_display
+                  variant: inline
+                  props:
+                    title: "$t:create_task.title"
+                  tokens_override:
+                    title_style: "typography.heading_sm"
+
+                - contract: action_trigger
+                  variant: primary
+                  size: sm
+                  props:
+                    label: "$t:create_task.save"
+                    loading_label: "$t:create_task.saving"
+                  state_binding:
+                    loading: "state.is_submitting"
+                  action:
+                    type: submit_form
+                    form_id: "task_form"
+
+            # ---------- Form fields ----------
+            - id: form
+              form_id: "task_form"
+              margin_top: "spacing.lg"
+              layout: { type: stack, spacing: "spacing.md" }
+              children:
+                # Title (text)
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:create_task.field_title"
+                    placeholder: "$t:create_task.field_title_placeholder"
+                    required: true
+                    max_length: 200
+                  validate:
+                    min_length: { value: 3, message: "$t:validation.min_length" }
+                  data_binding: "form.title"
+
+                # Description (multiline)
+                - contract: input_field
+                  input_type: multiline
+                  props:
+                    label: "$t:create_task.field_description"
+                    placeholder: "$t:create_task.field_description_placeholder"
+                    required: false
+                  data_binding: "form.description"
+                  tokens_override:
+                    min_height: 100
+
+                # Project (select)
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:create_task.field_project"
+                    placeholder: "$t:create_task.field_project_placeholder"
+                    options:
+                      source: "api.projects.list"
+                      value_key: "id"
+                      label_key: "name"
+                      icon_key: "icon"
+                    required: false
+                  data_binding: "form.project_id"
+
+                # Priority (select)
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:create_task.field_priority"
+                    options:
+                      - { value: "low", label: "$t:priority.low", icon: "flag", color: "color.priority.low" }
+                      - { value: "medium", label: "$t:priority.medium", icon: "flag_fill", color: "color.priority.medium" }
+                      - { value: "high", label: "$t:priority.high", icon: "flag_fill", color: "color.priority.high" }
+                      - { value: "urgent", label: "$t:priority.urgent", icon: "exclamationmark_triangle", color: "color.priority.urgent" }
+                    required: true
+                  data_binding: "form.priority"
+
+                # Due date (date picker)
+                - contract: input_field
+                  input_type: date
+                  props:
+                    label: "$t:create_task.field_due_date"
+                    placeholder: "$t:create_task.field_due_date_placeholder"
+                    required: false
+                  data_binding: "form.due_date"
+
+                # Tags (text with tokenization)
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:create_task.field_tags"
+                    placeholder: "$t:create_task.field_tags_placeholder"
+                    helper_text: "$t:create_task.field_tags_helper"
+                    required: false
+                  validate:
+                    pattern: { regex: "^[a-zA-Z0-9_,\\-\\s]+$", message: "$t:validation.tag_format" }
+                  data_binding: "form.tags"
+                  behavior:
+                    tokenize_on: [",", "Enter"]
+                    display_as: chips
+
+                # Assign to me toggle
+                - contract: input_field
+                  input_type: toggle
+                  props:
+                    label: "$t:create_task.field_assign_to_me"
+                    value: true
+                  data_binding: "form.assign_to_self"
+
+          # ---------- Form submission ----------
+          on_submit:
+            type: sequence
+            actions:
+              - { type: set_state, is_submitting: true }
+              - type: api_call
+                endpoint: "api.tasks.create"
+                body: "form"
+                on_success:
+                  type: sequence
+                  actions:
+                    - { type: set_state, is_submitting: false }
+                    - { type: feedback, variant: toast, message: "$t:create_task.success", severity: success, icon: "checkmark_circle", duration: 3000 }
+                    - { type: dismiss }
+                    - { type: refresh, target: "screens/home.tasks" }
+                on_error:
+                  type: sequence
+                  actions:
+                    - { type: set_state, is_submitting: false }
+                    - { type: feedback, variant: banner, title: "$t:create_task.error_title", message: "{error.message}", severity: error }
+
+      transitions: {}                   # single screen, no transitions
+
+  platform_hints:
+    ios: { presentation: "sheet", detents: [large] }
+    android: { presentation: "bottom_sheet", fullscreen: false }
+    web: { presentation: "modal", size: "md" }

package/examples/taskflow/flows/edit_task.yaml

@@ -0,0 +1,131 @@
+# ============================================================
+# TaskFlow — Edit Task Flow (stub)
+# ============================================================
+# Referenced by task_detail.yaml. Same form as create_task
+# but pre-populated with existing task data.
+# ============================================================
+
+edit_task:
+  semantic: "Edit an existing task"
+  status: stub
+
+  params:
+    task_id: { type: string, required: true }
+
+  entry: "task_form"
+
+  screens:
+    task_form:
+      screen_inline:
+        semantic: "Task edit form pre-populated with existing data"
+
+        data:
+          task:
+            source: "api.tasks.getById"
+            params: { id: "params.task_id" }
+
+        state:
+          is_submitting: { type: bool, default: false }
+
+        layout:
+          type: scroll_vertical
+          safe_area: true
+          padding: "spacing.page_margin"
+
+          sections:
+            - id: header
+              layout: { type: row, justify: "space-between", align: "center" }
+              children:
+                - contract: action_trigger
+                  variant: ghost
+                  size: sm
+                  props: { label: "$t:common.cancel" }
+                  action: { type: dismiss }
+
+                - contract: data_display
+                  variant: inline
+                  props:
+                    title: "$t:edit_task.title"
+                  tokens_override:
+                    title_style: "typography.heading_sm"
+
+                - contract: action_trigger
+                  variant: primary
+                  size: sm
+                  props:
+                    label: "$t:edit_task.save"
+                    loading_label: "$t:edit_task.saving"
+                  state_binding:
+                    loading: "state.is_submitting"
+                  action:
+                    type: submit_form
+                    form_id: "edit_task_form"
+
+            - id: form
+              form_id: "edit_task_form"
+              margin_top: "spacing.lg"
+              layout: { type: stack, spacing: "spacing.md" }
+              children:
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:edit_task.field_title"
+                    value: "task.title"
+                    required: true
+                    max_length: 200
+                  data_binding: "form.title"
+
+                - contract: input_field
+                  input_type: multiline
+                  props:
+                    label: "$t:edit_task.field_description"
+                    value: "task.description"
+                  data_binding: "form.description"
+
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:edit_task.field_priority"
+                    value: "task.priority"
+                    options:
+                      - { value: "low", label: "$t:priority.low", icon: "flag", color: "color.priority.low" }
+                      - { value: "medium", label: "$t:priority.medium", icon: "flag_fill", color: "color.priority.medium" }
+                      - { value: "high", label: "$t:priority.high", icon: "flag_fill", color: "color.priority.high" }
+                      - { value: "urgent", label: "$t:priority.urgent", icon: "exclamationmark_triangle", color: "color.priority.urgent" }
+                    required: true
+                  data_binding: "form.priority"
+
+                - contract: input_field
+                  input_type: date
+                  props:
+                    label: "$t:edit_task.field_due_date"
+                    value: "task.due_date"
+                  data_binding: "form.due_date"
+
+          on_submit:
+            type: sequence
+            actions:
+              - { type: set_state, is_submitting: true }
+              - type: api_call
+                endpoint: "api.tasks.update"
+                params: { id: "params.task_id" }
+                body: "form"
+                on_success:
+                  type: sequence
+                  actions:
+                    - { type: set_state, is_submitting: false }
+                    - { type: feedback, variant: toast, message: "$t:edit_task.success", severity: success }
+                    - { type: dismiss }
+                    - { type: refresh, target: "screens/task_detail.task" }
+                on_error:
+                  type: sequence
+                  actions:
+                    - { type: set_state, is_submitting: false }
+                    - { type: feedback, variant: banner, title: "$t:edit_task.error_title", message: "{error.message}", severity: error }
+
+      transitions: {}
+
+  platform_hints:
+    ios: { presentation: "sheet", detents: [large] }
+    android: { presentation: "bottom_sheet", fullscreen: false }
+    web: { presentation: "modal", size: "md" }

package/examples/taskflow/locales/en.json

@@ -0,0 +1,158 @@
+{
+  "$locale": "en",
+  "$direction": "ltr",
+
+  "nav.tasks": "Tasks",
+  "nav.projects": "Projects",
+  "nav.calendar": "Calendar",
+  "nav.settings": "Settings",
+
+  "home.greeting.morning": "Good morning, {name}",
+  "home.greeting.afternoon": "Good afternoon, {name}",
+  "home.greeting.evening": "Good evening, {name}",
+  "home.task_count": "{count, plural, =0 {No tasks today} one {# task today} other {# tasks today}}",
+  "home.search_label": "Search tasks",
+  "home.search_placeholder": "Search by title, tag, or project...",
+  "home.filter.all": "All",
+  "home.filter.today": "Today",
+  "home.filter.upcoming": "Upcoming",
+  "home.filter.done": "Done",
+  "home.empty_title": "All caught up!",
+  "home.empty_body": "No tasks match this filter. Tap + to add one.",
+  "home.new_task": "New task",
+  "home.mark_complete": "Mark {title} complete",
+
+  "task_detail.status": "Status",
+  "task_detail.priority": "Priority",
+  "task_detail.due": "Due",
+  "task_detail.description": "Description",
+  "task_detail.details": "Details",
+  "task_detail.project": "Project",
+  "task_detail.assignee": "Assignee",
+  "task_detail.unassigned": "Unassigned",
+  "task_detail.tags": "Tags",
+  "task_detail.created": "Created",
+  "task_detail.edit": "Edit task",
+  "task_detail.toggle_status": "{is_done, select, true {Reopen task} other {Mark complete}}",
+  "task_detail.delete": "Delete task",
+  "task_detail.delete_title": "Delete task?",
+  "task_detail.delete_message": "This action cannot be undone. The task \"{title}\" will be permanently removed.",
+  "task_detail.task_updated": "Task updated",
+  "task_detail.update_error": "Couldn't update status",
+  "task_detail.task_deleted": "Task deleted",
+  "task_detail.assign_to": "Assign to",
+  "task_detail.search_people": "Search people",
+  "task_detail.search_people_placeholder": "Name or email...",
+
+  "create_task.title": "New task",
+  "create_task.save": "Save",
+  "create_task.saving": "Saving...",
+  "create_task.field_title": "Title",
+  "create_task.field_title_placeholder": "What needs to be done?",
+  "create_task.field_description": "Description",
+  "create_task.field_description_placeholder": "Add details, notes, or context...",
+  "create_task.field_project": "Project",
+  "create_task.field_project_placeholder": "Select a project",
+  "create_task.field_priority": "Priority",
+  "create_task.field_due_date": "Due date",
+  "create_task.field_due_date_placeholder": "No due date",
+  "create_task.field_tags": "Tags",
+  "create_task.field_tags_placeholder": "Add tags separated by commas",
+  "create_task.field_tags_helper": "Press comma or Enter to add a tag",
+  "create_task.field_assign_to_me": "Assign to me",
+  "create_task.success": "Task created",
+  "create_task.error_title": "Couldn't create task",
+
+  "edit_task.title": "Edit task",
+  "edit_task.save": "Save",
+  "edit_task.saving": "Saving...",
+  "edit_task.field_title": "Title",
+  "edit_task.field_description": "Description",
+  "edit_task.field_priority": "Priority",
+  "edit_task.field_due_date": "Due date",
+  "edit_task.success": "Task updated",
+  "edit_task.error_title": "Couldn't update task",
+
+  "projects.title": "Projects",
+  "projects.new_project": "New project",
+  "projects.task_count": "{count, plural, =0 {No tasks} one {# task} other {# tasks}}",
+  "projects.empty_title": "No projects yet",
+  "projects.empty_body": "Create a project to organize your tasks.",
+  "projects.dialog_title": "New project",
+  "projects.field_name": "Project name",
+  "projects.field_name_placeholder": "e.g., Product Launch",
+  "projects.field_color": "Color",
+  "projects.field_icon": "Icon",
+  "projects.created": "Project created",
+
+  "project_detail.task_count": "{count, plural, =0 {No tasks} one {# task} other {# tasks}}",
+  "project_detail.empty_title": "No tasks in this project",
+  "project_detail.empty_body": "Add a task to get started.",
+
+  "settings.preferences": "Preferences",
+  "settings.theme": "Theme",
+  "settings.theme_system": "System",
+  "settings.theme_light": "Light",
+  "settings.theme_dark": "Dark",
+  "settings.theme_warm": "Warm",
+  "settings.default_priority": "Default priority",
+  "settings.notifications": "Push notifications",
+  "settings.reminders": "Due date reminders",
+  "settings.reminders_helper": "Get notified 1 hour before a task is due",
+  "settings.data": "Data",
+  "settings.export": "Export data",
+  "settings.export_success": "Export sent to your email",
+  "settings.delete_account": "Delete account",
+  "settings.delete_title": "Delete your account?",
+  "settings.delete_message": "This will permanently delete your account and all your data. This action cannot be undone.",
+  "settings.delete_confirm": "Delete my account",
+  "settings.app_version": "TaskFlow v1.0.0",
+  "settings.app_credit": "Built with OpenUISpec",
+
+  "profile.change_photo": "Change photo",
+  "profile.field_name": "Name",
+  "profile.field_email": "Email",
+  "profile.save": "Save changes",
+  "profile.success": "Profile updated",
+
+  "calendar.title": "Calendar",
+  "calendar.coming_soon": "Coming in a future version",
+
+  "priority.low": "Low",
+  "priority.medium": "Medium",
+  "priority.high": "High",
+  "priority.urgent": "Urgent",
+
+  "status.todo": "To do",
+  "status.in_progress": "In progress",
+  "status.done": "Done",
+
+  "media_player.loading": "Loading media…",
+  "media_player.play": "Play",
+  "media_player.pause": "Pause",
+  "media_player.replay": "Replay",
+  "media_player.retry": "Retry",
+  "media_player.error": "Unable to play media",
+  "media_player.fullscreen": "Full screen",
+  "media_player.exit_fullscreen": "Exit full screen",
+  "media_player.mute": "Mute",
+  "media_player.unmute": "Unmute",
+  "media_player.playback_rate": "Playback speed",
+
+  "validation.required": "This field is required",
+  "validation.min_length": "Must be at least {min} characters",
+  "validation.max_length": "Must be no more than {max} characters",
+  "validation.min_value": "Must be at least {min}",
+  "validation.max_value": "Must be no more than {max}",
+  "validation.pattern": "Invalid format",
+  "validation.format.email": "Enter a valid email address",
+  "validation.format.url": "Enter a valid URL",
+  "validation.format.phone": "Enter a valid phone number",
+  "validation.match_field": "Fields do not match",
+  "validation.tag_format": "Tags may only contain letters, numbers, and hyphens",
+  "validation.checking": "Checking…",
+
+  "common.cancel": "Cancel",
+  "common.delete": "Delete",
+  "common.create": "Create"
+}