openuispec 0.1.18 → 0.1.20

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

@@ -0,0 +1,139 @@
+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"

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

@@ -0,0 +1,253 @@
+create_recurring_rule:
+  semantic: "Validation-heavy flow for creating recurring task rules"
+  status: ready
+
+  entry: "rule_form"
+
+  screens:
+    rule_form:
+      screen_inline:
+        semantic: "Recurring rule form with field dependencies, async validation, and cross-field checks"
+
+        data:
+          preferences:
+            source: "api.preferences.get"
+
+        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:recurring_rule.title"
+                    subtitle: "$t:recurring_rule.subtitle"
+                  tokens_override:
+                    title_style: "typography.heading_sm"
+                    subtitle_style: "typography.body_sm"
+
+                - contract: action_trigger
+                  variant: primary
+                  size: sm
+                  props:
+                    label: "$t:recurring_rule.save"
+                    loading_label: "$t:recurring_rule.saving"
+                  state_binding:
+                    loading: "state.is_submitting"
+                  action:
+                    type: submit_form
+                    form_id: "recurring_rule_form"
+                    on_validation_error:
+                      type: feedback
+                      variant: toast
+                      message: "$t:validation.fix_errors"
+                      severity: warning
+                      duration: 2800
+
+            - id: form
+              form_id: "recurring_rule_form"
+              margin_top: "spacing.lg"
+              layout: { type: stack, spacing: "spacing.md" }
+              children:
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:recurring_rule.field_name"
+                    placeholder: "$t:recurring_rule.field_name_placeholder"
+                    required: true
+                    max_length: 80
+                  validate:
+                    min_length: { value: 4, message: "$t:validation.rule_name_min_length" }
+                    custom:
+                      expression: "$value != 'Default'"
+                      message: "$t:validation.rule_name_reserved"
+                    async:
+                      endpoint: "api.recurring.checkName"
+                      debounce: 450
+                      message: "$t:validation.rule_name_taken"
+                  validate_trigger: on_change
+                  data_binding: "form.name"
+
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:recurring_rule.field_confirm_name"
+                    placeholder: "$t:recurring_rule.field_confirm_name_placeholder"
+                    required: true
+                  validate:
+                    match_field:
+                      field: "form.name"
+                      message: "$t:validation.match_field"
+                  validate_trigger: on_blur
+                  data_binding: "form.confirm_name"
+
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:recurring_rule.field_cadence"
+                    required: true
+                    options:
+                      - { value: "daily", label: "$t:recurring_rule.cadence_daily" }
+                      - { value: "weekly", label: "$t:recurring_rule.cadence_weekly" }
+                      - { value: "monthly", label: "$t:recurring_rule.cadence_monthly" }
+                  data_binding: "form.cadence"
+
+                - contract: input_field
+                  input_type: number
+                  props:
+                    label: "$t:recurring_rule.field_interval"
+                    helper_text: "$t:recurring_rule.field_interval_helper"
+                    required: true
+                  validate:
+                    min: { value: 1, message: "$t:validation.min_value" }
+                    max: { value: 30, message: "$t:validation.max_value" }
+                  data_binding: "form.interval"
+
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:recurring_rule.field_weekday"
+                    options:
+                      - { value: "mon", label: "$t:weekday.mon" }
+                      - { value: "tue", label: "$t:weekday.tue" }
+                      - { value: "wed", label: "$t:weekday.wed" }
+                      - { value: "thu", label: "$t:weekday.thu" }
+                      - { value: "fri", label: "$t:weekday.fri" }
+                      - { value: "sat", label: "$t:weekday.sat" }
+                      - { value: "sun", label: "$t:weekday.sun" }
+                  condition: "form.cadence == 'weekly'"
+                  required_when: "form.cadence == 'weekly'"
+                  enabled_when: "form.cadence == 'weekly'"
+                  data_binding: "form.weekday"
+
+                - contract: input_field
+                  input_type: number
+                  props:
+                    label: "$t:recurring_rule.field_month_day"
+                    helper_text: "$t:recurring_rule.field_month_day_helper"
+                  condition: "form.cadence == 'monthly'"
+                  required_when: "form.cadence == 'monthly'"
+                  enabled_when: "form.cadence == 'monthly'"
+                  validate:
+                    min: { value: 1, message: "$t:validation.min_value" }
+                    max: { value: 28, message: "$t:validation.month_day_max" }
+                  data_binding: "form.month_day"
+
+                - contract: input_field
+                  input_type: date
+                  props:
+                    label: "$t:recurring_rule.field_start_date"
+                    required: true
+                  data_binding: "form.start_date"
+
+                - contract: input_field
+                  input_type: toggle
+                  props:
+                    label: "$t:recurring_rule.field_has_end_date"
+                    helper_text: "$t:recurring_rule.field_has_end_date_helper"
+                    value: false
+                  data_binding: "form.has_end_date"
+
+                - contract: input_field
+                  input_type: date
+                  props:
+                    label: "$t:recurring_rule.field_end_date"
+                  required_when: "form.has_end_date == true"
+                  enabled_when: "form.has_end_date == true"
+                  validate:
+                    custom:
+                      expression: "$value >= form.start_date"
+                      message: "$t:validation.end_date_after_start"
+                  data_binding: "form.end_date"
+
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:recurring_rule.field_remind_at"
+                    placeholder: "$t:recurring_rule.field_remind_at_placeholder"
+                    helper_text: "$t:recurring_rule.field_remind_at_helper"
+                  condition: "preferences.reminders_enabled == true"
+                  required_when: "preferences.reminders_enabled == true"
+                  enabled_when: "preferences.reminders_enabled == true"
+                  validate:
+                    pattern:
+                      regex: "^([01]\\d|2[0-3]):[0-5]\\d$"
+                      message: "$t:validation.time_format"
+                  validate_trigger: on_submit
+                  data_binding: "form.remind_at"
+
+                - contract: input_field
+                  input_type: toggle
+                  props:
+                    label: "$t:recurring_rule.field_enable_summary"
+                    helper_text: "$t:recurring_rule.field_enable_summary_helper"
+                    value: false
+                  data_binding: "form.enable_summary"
+
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:recurring_rule.field_summary_channel"
+                    options:
+                      - { value: "push", label: "$t:recurring_rule.summary_push" }
+                      - { value: "email", label: "$t:recurring_rule.summary_email" }
+                  condition: "form.enable_summary == true"
+                  required_when: "form.enable_summary == true"
+                  enabled_when: "form.enable_summary == true"
+                  data_binding: "form.summary_channel"
+
+            - id: preview
+              margin_top: "spacing.xl"
+              contract: x_schedule_preview
+              variant: detail
+              condition: "form.cadence != ''"
+              props:
+                title: "$t:recurring_preview.title"
+                cadence: "form.cadence"
+                interval: "form.interval"
+                weekday: "form.weekday"
+                month_day: "form.month_day"
+                start_date: "form.start_date"
+                end_date: "form.end_date"
+                preview_count: 4
+                empty_message: "$t:recurring_preview.empty"
+                invalid_message: "$t:recurring_preview.invalid"
+
+          on_submit:
+            type: sequence
+            actions:
+              - { type: set_state, target: "state.is_submitting", value: true }
+              - type: api_call
+                endpoint: "api.recurring.create"
+                body: "form"
+                on_success:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: false }
+                    - { type: feedback, variant: toast, message: "$t:recurring_rule.success", severity: success, duration: 2500 }
+                    - { type: dismiss }
+                on_error:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: false }
+                    - { type: feedback, variant: banner, title: "$t:recurring_rule.error_title", message: "{error.message}", severity: error }
+
+      transitions: {}
+
+  platform_hints:
+    ios: { presentation: "sheet", detents: [large] }
+    android: { presentation: "bottom_sheet", fullscreen: true }
+    web: { presentation: "modal", size: "lg" }

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

@@ -0,0 +1,118 @@
+create_task:
+  semantic: "Single-screen flow for creating a new todo item"
+  status: ready
+
+  entry: "task_form"
+
+  screens:
+    task_form:
+      screen_inline:
+        semantic: "Task creation form with fields for title, notes, priority, and due date"
+
+        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:create_task.title"
+                  tokens_override:
+                    title_style: "typography.heading"
+
+                - 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"
+
+            - id: form
+              form_id: "task_form"
+              margin_top: "spacing.lg"
+              layout: { type: stack, spacing: "spacing.md" }
+              children:
+                - contract: input_field
+                  input_type: text
+                  props:
+                    label: "$t:create_task.field_title"
+                    placeholder: "$t:create_task.field_title_placeholder"
+                    required: true
+                    max_length: 160
+                  validate:
+                    min_length: { value: 2, message: "$t:validation.min_length" }
+                  data_binding: "form.title"
+
+                - contract: input_field
+                  input_type: multiline
+                  props:
+                    label: "$t:create_task.field_notes"
+                    placeholder: "$t:create_task.field_notes_placeholder"
+                    required: false
+                  data_binding: "form.notes"
+                  tokens_override:
+                    min_height: 96
+
+                - contract: input_field
+                  input_type: select
+                  props:
+                    label: "$t:create_task.field_priority"
+                    options:
+                      - { value: "low", label: "$t:priority.low", icon: "flag" }
+                      - { value: "medium", label: "$t:priority.medium", icon: "flag_fill" }
+                      - { value: "high", label: "$t:priority.high", icon: "flag_fill" }
+                    required: true
+                  data_binding: "form.priority"
+
+                - 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"
+
+          on_submit:
+            type: sequence
+            actions:
+              - { type: set_state, target: "state.is_submitting", value: true }
+              - type: api_call
+                endpoint: "api.tasks.create"
+                body: "form"
+                on_success:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: false }
+                    - { type: feedback, variant: toast, message: "$t:create_task.success", severity: success, duration: 2500 }
+                    - { type: dismiss }
+                    - { type: refresh, target: "screens/home.tasks" }
+                on_error:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: false }
+                    - { type: feedback, variant: banner, title: "$t:create_task.error_title", message: "{error.message}", severity: error }
+
+      transitions: {}
+
+  platform_hints:
+    ios: { presentation: "sheet", detents: [medium, large] }
+    android: { presentation: "bottom_sheet", fullscreen: false }
+    web: { presentation: "modal", size: "md" }

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

@@ -0,0 +1,126 @@
+edit_task:
+  semantic: "Single-screen flow for editing an existing task"
+  status: ready
+
+  params:
+    task_id: { type: string, required: true }
+
+  entry: "task_form"
+
+  screens:
+    task_form:
+      screen_inline:
+        semantic: "Task edit form pre-populated with existing task 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"
+
+                - 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: 160
+                  validate:
+                    min_length: { value: 2, message: "$t:validation.min_length" }
+                  data_binding: "form.title"
+
+                - contract: input_field
+                  input_type: multiline
+                  props:
+                    label: "$t:edit_task.field_notes"
+                    value: "task.notes"
+                  data_binding: "form.notes"
+                  tokens_override:
+                    min_height: 96
+
+                - 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" }
+                      - { value: "medium", label: "$t:priority.medium", icon: "flag_fill" }
+                      - { value: "high", label: "$t:priority.high", icon: "flag_fill" }
+                    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, target: "state.is_submitting", value: true }
+              - type: api_call
+                endpoint: "api.tasks.update"
+                params: { id: "params.task_id" }
+                body: "form"
+                on_success:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: false }
+                    - { type: feedback, variant: toast, message: "$t:edit_task.success", severity: success, duration: 2500 }
+                    - { type: dismiss }
+                    - { type: refresh, target: "screens/task_detail.task" }
+                on_error:
+                  type: sequence
+                  actions:
+                    - { type: set_state, target: "state.is_submitting", value: 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" }