openuispec 0.1.0

package/examples/taskflow/openuispec.yaml

@@ -0,0 +1,144 @@
+# ============================================================
+# TaskFlow — OpenUISpec v0.1 Example Application
+# ============================================================
+# A task management app demonstrating all 7 contract families,
+# theming, navigation flows, adaptive layout, and the formal
+# action system and data binding model.
+# ============================================================
+
+spec_version: "0.1"
+
+project:
+  name: "TaskFlow"
+  description: "A simple task management app for individuals and small teams"
+  icon: "checkmark_circle"
+  
+includes:
+  tokens: "./tokens/"
+  contracts: "./contracts/"
+  screens: "./screens/"
+  flows: "./flows/"
+  platform: "./platform/"
+  locales: "./locales/"
+
+custom_contracts:
+  - "./contracts/x_media_player.yaml"
+
+i18n:
+  default_locale: "en"
+  supported_locales: [en]
+  fallback_strategy: "default"
+
+generation:
+  targets: [ios, android, web]
+  output_format:
+    ios: { language: swift, framework: swiftui, min_version: "17.0" }
+    android: { language: kotlin, framework: compose, min_sdk: 26 }
+    web: { language: typescript, framework: react, bundler: vite }
+
+# ============================================================
+# Custom formatters & mappers (see spec Section 10.5)
+# ============================================================
+formatters:
+  greeting:
+    input: time_of_day
+    output: string
+    mapping:
+      morning: "morning"
+      afternoon: "afternoon"
+      evening: "evening"
+    # Used as key suffix in $t:home.greeting.{time_of_day | format:greeting}
+
+  status_label:
+    input: enum
+    output: string
+    mapping:
+      todo: "$t:status.todo"
+      in_progress: "$t:status.in_progress"
+      done: "$t:status.done"
+
+  priority_label:
+    input: enum
+    output: string
+    mapping:
+      low: "$t:priority.low"
+      medium: "$t:priority.medium"
+      high: "$t:priority.high"
+      urgent: "$t:priority.urgent"
+
+mappers:
+  status_severity:
+    todo: neutral
+    in_progress: info
+    done: success
+
+  priority_to_severity:
+    low: neutral
+    medium: info
+    high: warning
+    urgent: error
+
+# ============================================================
+# Data model
+# ============================================================
+data_model:
+  task:
+    id: { type: string, format: uuid }
+    title: { type: string, max_length: 200 }
+    description: { type: string, required: false }
+    status: { type: enum, values: [todo, in_progress, done] }
+    priority: { type: enum, values: [low, medium, high, urgent] }
+    due_date: { type: date, required: false }
+    project_id: { type: string, required: false }
+    assignee: { type: user, required: false }
+    tags: { type: "list<string>", default: [] }
+    created_at: { type: datetime }
+    updated_at: { type: datetime }
+
+  project:
+    id: { type: string, format: uuid }
+    name: { type: string, max_length: 100 }
+    color: { type: color_ref }
+    icon: { type: icon_ref }
+    task_count: { type: int }
+    
+  user:
+    id: { type: string, format: uuid }
+    name: { type: string }
+    first_name: { type: string }
+    avatar: { type: media_ref, required: false }
+    email: { type: string, format: email }
+
+# ============================================================
+# API endpoints (informational — helps AI generators produce
+# correct API client code)
+# ============================================================
+api:
+  base_url: "/api/v1"
+  auth: "bearer_token"
+  
+  endpoints:
+    tasks:
+      list: { method: GET, path: "/tasks", params: [filter, sort, search] }
+      getById: { method: GET, path: "/tasks/:id" }
+      create: { method: POST, path: "/tasks", body: "task" }
+      update: { method: PUT, path: "/tasks/:id", body: "task" }
+      delete: { method: DELETE, path: "/tasks/:id" }
+      toggleStatus: { method: PATCH, path: "/tasks/:id/status" }
+      assignTo: { method: PATCH, path: "/tasks/:id/assign", body: { user_id: string } }
+      counts: { method: GET, path: "/tasks/counts" }
+    projects:
+      list: { method: GET, path: "/projects" }
+      getById: { method: GET, path: "/projects/:id" }
+      create: { method: POST, path: "/projects", body: "project" }
+    users:
+      list: { method: GET, path: "/users", params: [search] }
+    auth:
+      currentUser: { method: GET, path: "/auth/me" }
+      updateProfile: { method: PATCH, path: "/auth/me", body: { name: string, email: string } }
+      deleteAccount: { method: DELETE, path: "/auth/account" }
+    preferences:
+      get: { method: GET, path: "/preferences" }
+      update: { method: PATCH, path: "/preferences", body: { key: string, value: any } }
+    data:
+      export: { method: POST, path: "/data/export" }

package/examples/taskflow/platform/android.yaml

@@ -0,0 +1,32 @@
+# TaskFlow — Android Platform Adaptation
+
+android:
+  framework: compose
+  min_sdk: 26
+  target_sdk: 35
+
+  overrides:
+    nav_container:
+      tab_bar: { height: 56, uses_NavigationBar: true }
+    surface:
+      sheet: { uses_ModalBottomSheet: true, skip_partial_collapse: false }
+    feedback:
+      snackbar: { uses_system_snackbar: true }
+    action_trigger:
+      primary: { ripple: true }
+    collection:
+      list: { edge_to_edge_items: true }
+
+  behaviors:
+    material_you: true
+    predictive_back: true
+    edge_to_edge: true
+    dynamic_color: true
+
+  generation:
+    dependencies:
+      - "material3"
+      - "navigation-compose"
+      - "lifecycle-viewmodel-compose"
+    architecture: "MVVM with ViewModel + StateFlow"
+    naming: "Kotlin conventions"

package/examples/taskflow/platform/ios.yaml

@@ -0,0 +1,39 @@
+# TaskFlow — iOS Platform Adaptation
+
+ios:
+  framework: swiftui
+  min_version: "17.0"
+
+  overrides:
+    nav_container:
+      tab_bar: { height: 49, uses_system_tab_bar: true }
+    surface:
+      sheet: { detents: [.medium, .large], drag_indicator: true }
+      modal: { prefers_sheet: true }
+    feedback:
+      toast: { position: "top" }
+    input_field:
+      date: { uses_system_picker: true, style: "graphical" }
+    collection:
+      list: { uses_system_list_style: ".insetGrouped" }
+
+    x_media_player:
+      inline:
+        uses_native_player: true
+        pip_enabled: true
+
+  behaviors:
+    haptics: true
+    large_title_scroll: true
+    swipe_back: true
+    safe_area_respect: true
+    dynamic_type: true
+    swipe_actions:
+      task_list_item:
+        leading: { action: "toggleStatus", color: "color.semantic.success", icon: "checkmark" }
+        trailing: { action: "delete", color: "color.semantic.danger", icon: "trash" }
+
+  generation:
+    imports: ["SwiftUI", "Foundation"]
+    architecture: "MVVM with @Observable"
+    naming: "Swift conventions"

package/examples/taskflow/platform/web.yaml

@@ -0,0 +1,35 @@
+# TaskFlow — Web Platform Adaptation
+
+web:
+  framework: react
+  language: typescript
+
+  overrides:
+    # Navigation uses layout.size_classes (defined in tokens/layout.yaml)
+    # No need for ad-hoc variant_responsive here — the adaptive key
+    # on the nav_container in home.yaml handles this.
+
+    surface:
+      sheet: { falls_back_to: "modal" }
+    feedback:
+      dialog: { uses_native_dialog_element: true }
+
+  behaviors:
+    prefers_color_scheme: true
+    keyboard_navigation: true
+
+    # Breakpoints now reference layout.size_classes
+    # compact: max 600px, regular: 601-1024px, expanded: 1025px+
+    # These are defined in tokens/layout.yaml and applied globally.
+
+    keyboard_shortcuts:
+      new_task: { key: "n", modifier: "cmd/ctrl" }
+      search: { key: "k", modifier: "cmd/ctrl" }
+      toggle_sidebar: { key: "b", modifier: "cmd/ctrl" }
+
+  generation:
+    bundler: "vite"
+    css: "tailwind"
+    routing: "react_router"
+    state: "zustand"
+    naming: "React conventions"

package/examples/taskflow/screens/calendar.yaml

@@ -0,0 +1,23 @@
+# ============================================================
+# TaskFlow — Calendar Screen (stub)
+# ============================================================
+# Not yet implemented in v0.1. Referenced by home.yaml nav.
+# Planned contracts: collection (grid/list), data_display, surface
+# ============================================================
+
+calendar:
+  semantic: "Calendar view of tasks organized by date"
+  status: stub
+
+  layout:
+    type: scroll_vertical
+    safe_area: true
+    padding: "spacing.page_margin"
+
+    sections:
+      - id: placeholder
+        contract: data_display
+        variant: hero
+        props:
+          title: "$t:calendar.title"
+          subtitle: "$t:calendar.coming_soon"

package/examples/taskflow/screens/home.yaml

@@ -0,0 +1,220 @@
+# ============================================================
+# TaskFlow — Home Screen (Task List)
+# ============================================================
+# Exercises: nav_container, collection, data_display,
+#            action_trigger, input_field (search),
+#            adaptive layout (size-class-aware sections)
+# ============================================================
+
+home:
+  semantic: "Main task list with filtering, search, and quick actions"
+
+  data:
+    tasks:
+      source: "api.tasks.list"
+      params:
+        filter: "state.active_filter"
+        sort: "state.sort_order"
+    projects:
+      source: "api.projects.list"
+    task_counts:
+      source: "api.tasks.counts"
+
+  state:
+    active_filter:
+      type: enum
+      values: [all, today, upcoming, done]
+      default: today
+    sort_order:
+      type: enum
+      values: [due_date, priority, created_at]
+      default: due_date
+    search_query: { type: string, default: "" }
+
+  # --- Navigation shell (adaptive) ---
+  navigation:
+    contract: nav_container
+    props:
+      items:
+        - id: "home"
+          label: "$t:nav.tasks"
+          icon: "checkmark_list"
+          icon_active: "checkmark_list_fill"
+          destination: "screens/home"
+          badge: { count: "task_counts.today", severity: "info" }
+        - id: "projects"
+          label: "$t:nav.projects"
+          icon: "folder"
+          icon_active: "folder_fill"
+          destination: "screens/projects"
+        - id: "calendar"
+          label: "$t:nav.calendar"
+          icon: "calendar"
+          icon_active: "calendar_fill"
+          destination: "screens/calendar"
+        - id: "settings"
+          label: "$t:nav.settings"
+          icon: "gear"
+          icon_active: "gear_fill"
+          destination: "screens/settings"
+      selected: "home"
+    # Adaptive: nav variant changes with screen size
+    adaptive:
+      compact: { variant: tab_bar }
+      regular: { variant: rail }
+      expanded: { variant: sidebar, collapsed: false }
+
+  # --- Screen-level adaptive layout ---
+  layout:
+    adaptive:
+      compact:
+        type: scroll_vertical
+        safe_area: true
+      expanded:
+        type: split_view
+        primary_width: 0.38
+        primary: { sections: [header, search, filters, task_list] }
+        secondary: { sections: ["screens/task_detail"], params_from: "selected_task" }
+        collapse_at: compact
+
+    sections:
+      # ---------- Header ----------
+      - id: header
+        layout: { type: stack, spacing: "spacing.sm" }
+        padding: "spacing.page_margin"
+        children:
+          - contract: data_display
+            variant: inline
+            props:
+              title: "$t:home.greeting.{time_of_day | format:greeting}"
+              subtitle: "$t:home.task_count"
+              t_params:
+                name: "user.first_name"
+                count: "task_counts.today"
+              emphasis: default
+            tokens_override:
+              title_style: "typography.heading_lg"
+              subtitle_style: "typography.body_sm"
+            # Adaptive: larger title on expanded screens
+            adaptive:
+              expanded:
+                tokens_override:
+                  title_style: "typography.display"
+
+      # ---------- Search bar ----------
+      - id: search
+        padding_h: "spacing.page_margin"
+        contract: input_field
+        input_type: text
+        props:
+          label: "$t:home.search_label"
+          placeholder: "$t:home.search_placeholder"
+          value: "state.search_query"
+          icon: { ref: "search", position: leading }
+          clearable: true
+        tokens_override:
+          background: "color.surface.secondary"
+          border: { width: 0 }
+          radius: "spacing.sm"
+        # Adaptive: constrain search width on large screens
+        adaptive:
+          expanded:
+            max_width: 480
+
+      # ---------- Filter chips ----------
+      - id: filters
+        margin_top: "spacing.sm"
+        padding_h: "spacing.page_margin"
+        contract: collection
+        variant: chips
+        props:
+          data:
+            - { id: "all", label: "$t:home.filter.all", count: "task_counts.all" }
+            - { id: "today", label: "$t:home.filter.today", count: "task_counts.today" }
+            - { id: "upcoming", label: "$t:home.filter.upcoming", count: "task_counts.upcoming" }
+            - { id: "done", label: "$t:home.filter.done", count: "task_counts.done" }
+          item_contract: action_trigger
+          item_variant: ghost
+          item_props_map:
+            label: "{item.label} ({item.count})"
+          selectable: true
+          selection_mode: single
+          selected: "state.active_filter"
+        action:
+          type: set_state
+          target: "state.active_filter"
+          value: "item.id"
+
+      # ---------- Task list ----------
+      - id: task_list
+        margin_top: "spacing.md"
+        contract: collection
+        variant: list
+        props:
+          data: "tasks"
+          item_contract: data_display
+          item_variant: compact
+          item_props_map:
+            title: "item.title"
+            subtitle: "{item.project.name} · {item.due_date | format:date_relative}"
+            leading:
+              contract: input_field
+              input_type: checkbox
+              props:
+                value: "item.status == done"
+                label: "$t:home.mark_complete"
+                t_params:
+                  title: "item.title"
+              action:
+                type: api_call
+                endpoint: "api.tasks.toggleStatus"
+                params: { id: "item.id" }
+            trailing:
+              contract: data_display
+              variant: inline
+              props:
+                badge:
+                  dot: true
+                  severity: "{item.priority | map:priority_to_severity}"
+            metadata:
+              priority: "item.priority"
+              status: "item.status"
+          interactive: true
+          selectable: false
+          pull_to_refresh: true
+          searchable: false
+
+          empty_state:
+            icon: "checkmark_circle_fill"
+            title: "$t:home.empty_title"
+            body: "$t:home.empty_body"
+
+        action:
+          type: navigate
+          destination: "screens/task_detail"
+          params: { task_id: "item.id" }
+
+      # ---------- Floating action button ----------
+      - id: fab
+        position: "floating-bottom-trailing"
+        contract: action_trigger
+        variant: primary
+        size: lg
+        props:
+          label: "$t:home.new_task"
+          icon: "plus"
+        tokens_override:
+          radius: 28
+          shadow: "elevation.lg"
+        action:
+          type: navigate
+          destination: "flows/create_task"
+          presentation: "sheet"
+        # Adaptive: FAB becomes inline button on expanded
+        adaptive:
+          expanded:
+            position: "inline"
+            size: md
+            tokens_override:
+              radius: "spacing.sm"
+              shadow: none

package/examples/taskflow/screens/profile_edit.yaml

@@ -0,0 +1,70 @@
+# ============================================================
+# TaskFlow — Profile Edit Screen (stub)
+# ============================================================
+# Referenced by settings.yaml profile card.
+# ============================================================
+
+profile_edit:
+  semantic: "Edit user profile (name, email, avatar)"
+  status: stub
+
+  data:
+    user: { source: "api.auth.currentUser" }
+
+  layout:
+    type: scroll_vertical
+    safe_area: true
+    padding: "spacing.page_margin"
+
+    sections:
+      - id: avatar
+        layout: { type: stack, align: "center", spacing: "spacing.md" }
+        children:
+          - contract: data_display
+            variant: inline
+            props:
+              leading:
+                media: "user.avatar"
+                fallback: { initials: "user.name", background: "color.brand.primary" }
+                size: 80
+                radius: 40
+          - contract: action_trigger
+            variant: tertiary
+            size: sm
+            props: { label: "$t:profile.change_photo" }
+
+      - id: form
+        margin_top: "spacing.lg"
+        layout: { type: stack, spacing: "spacing.md" }
+        children:
+          - contract: input_field
+            input_type: text
+            props:
+              label: "$t:profile.field_name"
+              value: "user.name"
+              required: true
+            data_binding: "form.name"
+
+          - contract: input_field
+            input_type: email
+            props:
+              label: "$t:profile.field_email"
+              value: "user.email"
+              required: true
+            data_binding: "form.email"
+
+      - id: save
+        margin_top: "spacing.lg"
+        contract: action_trigger
+        variant: primary
+        full_width: true
+        props: { label: "$t:profile.save" }
+        action:
+          type: api_call
+          endpoint: "api.auth.updateProfile"
+          body: "form"
+          on_success:
+            type: sequence
+            actions:
+              - { type: navigate, destination: "$back" }
+              - { type: feedback, variant: toast, message: "$t:profile.success", severity: success }

package/examples/taskflow/screens/project_detail.yaml

@@ -0,0 +1,65 @@
+# ============================================================
+# TaskFlow — Project Detail Screen (stub)
+# ============================================================
+# Referenced by projects.yaml and task_detail.yaml.
+# Planned: project header, filtered task list, project settings.
+# ============================================================
+
+project_detail:
+  semantic: "Displays a single project with its tasks"
+  status: stub
+
+  params:
+    project_id: { type: string, required: true }
+
+  data:
+    project:
+      source: "api.projects.getById"
+      params: { id: "params.project_id" }
+    tasks:
+      source: "api.tasks.list"
+      params: { project_id: "params.project_id" }
+
+  layout:
+    type: scroll_vertical
+    safe_area: true
+    padding: "spacing.page_margin"
+
+    sections:
+      - id: header
+        contract: data_display
+        variant: hero
+        props:
+          title: "{project.name}"
+          subtitle: "$t:project_detail.task_count"
+          t_params:
+            count: "project.task_count"
+          leading:
+            icon: "{project.icon}"
+            color: "{project.color}"
+
+      - id: task_list
+        margin_top: "spacing.md"
+        contract: collection
+        variant: list
+        props:
+          data: "tasks"
+          item_contract: data_display
+          item_variant: compact
+          item_props_map:
+            title: "item.title"
+            subtitle: "{item.due_date | format:date_relative}"
+            trailing:
+              badge:
+                dot: true
+                severity: "{item.priority | map:priority_to_severity}"
+          interactive: true
+          pull_to_refresh: true
+          empty_state:
+            icon: "checkmark_circle_fill"
+            title: "$t:project_detail.empty_title"
+            body: "$t:project_detail.empty_body"
+        action:
+          type: navigate
+          destination: "screens/task_detail"
+          params: { task_id: "item.id" }