From 6f6000759b5ec62a9524c94b3d004bccf70f2001 Mon Sep 17 00:00:00 2001 From: Pascal Charbonneau Date: Thu, 19 Mar 2026 06:52:35 -0600 Subject: [PATCH] Add phased implementation plan for Ash UI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create 8-phase planning structure following jido_os pattern: - Phase 1: Core Ash Resource Integration (UI.Screen, UI.Element, UI.Binding) - Phase 2: IUR Adapter and Canonical Conversion (Ash IUR → unified_iur) - Phase 3: Data Binding and Signal Mapping (Ash → unified-ui signals) - Phase 4: Runtime and LiveView Integration (mount_ui_screen, lifecycle) - Phase 5: Authorization and Policy Enforcement (Ash policies) - Phase 6: Compiler and DSL Integration (unified-ui compiler) - Phase 7: Renderer Package Integration (live_ui, web_ui, desktop_ui) - Phase 8: Governance Gates and Release Readiness (CI, conformance) Each phase includes: - Section descriptions - Task and subtask breakdown with checkboxes - Integration test sections Total: 8 phases, 42 sections, ~300 subtasks --- specs/planning/README.md | 39 ++++ .../phase-01-core-ash-resource-integration.md | 172 +++++++++++++++ ...02-iur-adapter-and-canonical-conversion.md | 155 +++++++++++++ ...hase-03-data-binding-and-signal-mapping.md | 165 ++++++++++++++ ...ase-04-runtime-and-liveview-integration.md | 165 ++++++++++++++ ...05-authorization-and-policy-enforcement.md | 161 ++++++++++++++ .../phase-06-compiler-and-dsl-integration.md | 145 +++++++++++++ .../phase-07-renderer-package-integration.md | 157 ++++++++++++++ ...-governance-gates-and-release-readiness.md | 204 ++++++++++++++++++ 9 files changed, 1363 insertions(+) create mode 100644 specs/planning/README.md create mode 100644 specs/planning/phase-01-core-ash-resource-integration.md create mode 100644 specs/planning/phase-02-iur-adapter-and-canonical-conversion.md create mode 100644 specs/planning/phase-03-data-binding-and-signal-mapping.md create mode 100644 specs/planning/phase-04-runtime-and-liveview-integration.md create mode 100644 specs/planning/phase-05-authorization-and-policy-enforcement.md create mode 100644 specs/planning/phase-06-compiler-and-dsl-integration.md create mode 100644 specs/planning/phase-07-renderer-package-integration.md create mode 100644 specs/planning/phase-08-governance-gates-and-release-readiness.md diff --git a/specs/planning/README.md b/specs/planning/README.md new file mode 100644 index 00000000..964bff7a --- /dev/null +++ b/specs/planning/README.md @@ -0,0 +1,39 @@ +# Ash UI Architecture Execution Plan Index + +This directory contains a phased implementation plan for executing the Ash UI architecture baseline aligned with the unified-ui ecosystem. + +The plan aligns to: +- `rfcs/RFC-0002-ash-ui-unified-integration.md` +- `specs/topology.md` +- `specs/contracts/*` +- `specs/conformance/*` + +## Phase Files +1. [Phase 1 - Core Ash Resource Integration](./phase-01-core-ash-resource-integration.md): implement Ash Resources for storing unified-ui DSL definitions with Ash actions and policies. +2. [Phase 2 - IUR Adapter and Canonical Conversion](./phase-02-iur-adapter-and-canonical-conversion.md): implement Ash IUR to canonical unified_iur conversion. +3. [Phase 3 - Data Binding and Signal Mapping](./phase-03-data-binding-and-signal-mapping.md): implement Ash resource data binding to unified-ui signals. +4. [Phase 4 - Runtime and LiveView Integration](./phase-04-runtime-and-liveview-integration.md): implement LiveView mount/unmount and screen lifecycle. +5. [Phase 5 - Authorization and Policy Enforcement](./phase-05-authorization-and-policy-enforcement.md): implement Ash policy integration for UI access control. +6. [Phase 6 - Compiler and DSL Integration](./phase-06-compiler-and-dsl-integration.md): integrate unified-ui compiler with Ash Resource loading. +7. [Phase 7 - Renderer Package Integration](./phase-07-renderer-package-integration.md): implement live_ui/web_ui/desktop_ui package integration. +8. [Phase 8 - Governance Gates and Release Readiness](./phase-08-governance-gates-and-release-readiness.md): finalize CI gates, conformance tests, and rollout readiness. + +## Shared Conventions +- Numbering: + - Phases: `N` + - Sections: `N.M` + - Tasks: `N.M.K` + - Subtasks: `N.M.K.L` +- Tracking: + - Every phase, section, task, and subtask uses Markdown checkboxes (`[ ]`). +- Description requirement: + - Every phase, section, and task starts with a short description paragraph. +- Integration-test requirement: + - Each phase ends with a final integration-testing section. + +## Shared Assumptions and Defaults +- Ash UI remains an Ash Framework integration layer for unified-ui +- UI definitions are stored as Ash Resources in the database +- unified-ui packages provide widgets, layouts, compilation, and rendering +- Ash policies control access to UI resources +- Data flows from Ash resources → Ash IUR → canonical IUR → renderer output diff --git a/specs/planning/phase-01-core-ash-resource-integration.md b/specs/planning/phase-01-core-ash-resource-integration.md new file mode 100644 index 00000000..105b4d76 --- /dev/null +++ b/specs/planning/phase-01-core-ash-resource-integration.md @@ -0,0 +1,172 @@ +# Phase 1 - Core Ash Resource Integration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Resource` +- `AshUI.Resource.DSL` +- `Ash.Resource` +- `Ash.Domain` +- `Ash.DataLayer` +- `Ash.Query` + +## Relevant Assumptions / Defaults +- UI definitions are stored as Ash Resources with PostgreSQL data layer +- unified-ui DSL is stored as a map attribute on Ash Resources +- Ash actions provide CRUD operations on UI definitions +- Ash policies authorize UI access and modification + +[ ] 1 Phase 1 - Core Ash Resource Integration + Implement Ash Resources for storing unified-ui DSL definitions with database persistence, Ash actions, and policy-based authorization. + + [ ] 1.1 Section - UI Screen Resource + Implement the UI.Screen Ash Resource for storing unified-ui screen definitions. + + [ ] 1.1.1 Task - Define UI.Screen resource schema + Create the Ash Resource for screen definitions with unified-ui DSL storage. + + [ ] 1.1.1.1 Subtask - Implement `AshUI.Screen` resource with `use Ash.Resource` + [ ] 1.1.1.2 Subtask - Add `id` (UUID primary key), `name` (string), `unified_dsl` (map) attributes + [ ] 1.1.1.3 Subtask - Add `layout` (atom), `route` (string), `metadata` (map) attributes + [ ] 1.1.1.4 Subtask - Add `version` (integer) for optimistic locking and timestamps + [ ] 1.1.1.5 Subtask - Configure `AshPostgres.DataLayer` with `table: "ui_screens"` + + [ ] 1.1.2 Task - Define UI.Screen actions + Implement standard Ash actions for screen CRUD operations. + + [ ] 1.1.2.1 Subtask - Add default actions: `:read`, `:create`, `:update`, `:destroy` + [ ] 1.1.2.2 Subtask - Implement `:mount` action with `user_id` and `params` arguments + [ ] 1.1.2.3 Subtask - Implement `:unmount` action for cleanup + [ ] 1.1.2.4 Subtask - Add action return types and error handling + + [ ] 1.1.3 Task - Define UI.Screen relationships + Establish relationships to elements and bindings. + + [ ] 1.1.3.1 Subtask - Add `has_many :elements` relationship to `AshUI.Element` + [ ] 1.1.3.2 Subtask - Add `has_many :bindings` relationship to `AshUI.Binding` + [ ] 1.1.3.3 Subtask - Configure cascade delete for child elements and bindings + + [ ] 1.1.4 Task - Add UI.Screen DSL extension + Create the `ui_screen` DSL block for screen-specific configuration. + + [ ] 1.1.4.1 Subtask - Implement `AshUI.Resource.DSL.Screen` extension + [ ] 1.1.4.2 Subtask - Add `layout/1`, `route/1`, `metadata/1` DSL functions + [ ] 1.1.4.3 Subtask - Validate DSL options at compile time + [ ] 1.1.4.4 Subtask - Store DSL options in resource attributes + + [ ] 1.2 Section - UI Element Resource + Implement the UI.Element Ash Resource for storing unified-ui element definitions. + + [ ] 1.2.1 Task - Define UI.Element resource schema + Create the Ash Resource for element definitions with unified-ui widget storage. + + [ ] 1.2.1.1 Subtask - Implement `AshUI.Element` resource with `use Ash.Resource` + [ ] 1.2.1.2 Subtask - Add `id` (UUID), `type` (atom), `props` (map) attributes + [ ] 1.2.1.3 Subtask - Add `variants` (list of atoms), `position` (integer) attributes + [ ] 1.2.1.4 Subtask - Add `metadata` (map) and timestamps + [ ] 1.2.1.5 Subtask - Configure `AshPostgres.DataLayer` with `table: "ui_elements"` + + [ ] 1.2.2 Task - Define UI.Element relationships + Establish relationships to screen and bindings. + + [ ] 1.2.2.1 Subtask - Add `belongs_to :screen` relationship to `AshUI.Screen` + [ ] 1.2.2.2 Subtask - Add `has_many :bindings` relationship to `AshUI.Binding` + [ ] 1.2.2.3 Subtask - Add foreign key `screen_id` attribute + + [ ] 1.2.3 Task - Add UI.Element DSL extension + Create the `ui_element` DSL block for element-specific configuration. + + [ ] 1.2.3.1 Subtask - Implement `AshUI.Resource.DSL.Element` extension + [ ] 1.2.3.2 Subtask - Add `type/1`, `props/1`, `variants/1` DSL functions + [ ] 1.2.3.3 Subtask - Validate `type` against known unified-ui widget types + [ ] 1.2.3.4 Subtask - Store element definition in resource attributes + + [ ] 1.3 Section - UI Binding Resource + Implement the UI.Binding Ash Resource for data binding definitions. + + [ ] 1.3.1 Task - Define UI.Binding resource schema + Create the Ash Resource for binding Ash data to UI elements. + + [ ] 1.3.1.1 Subtask - Implement `AshUI.Binding` resource with `use Ash.Resource` + [ ] 1.3.1.2 Subtask - Add `id` (UUID), `source` (string), `target` (string) attributes + [ ] 1.3.1.3 Subtask - Add `binding_type` (atom), `transform` (map) attributes + [ ] 1.3.1.4 Subtask - Add `metadata` (map) and timestamps + [ ] 1.3.1.5 Subtask - Configure `AshPostgres.DataLayer` with `table: "ui_bindings"` + + [ ] 1.3.2 Task - Define UI.Binding relationships + Establish relationships to element and screen. + + [ ] 1.3.2.1 Subtask - Add `belongs_to :element` relationship to `AshUI.Element` + [ ] 1.3.2.2 Subtask - Add `belongs_to :screen` relationship to `AshUI.Screen` + [ ] 1.3.2.3 Subtask - Add foreign keys `element_id` and `screen_id` + + [ ] 1.3.3 Task - Add UI.Binding DSL extension + Create the `ui_binding` DSL block for binding configuration. + + [ ] 1.3.3.1 Subtask - Implement `AshUI.Resource.DSL.Binding` extension + [ ] 1.3.3.2 Subtask - Add `source/1`, `target/1`, `binding_type/1` DSL functions + [ ] 1.3.3.3 Subtask - Add `transform/1` DSL function for transformations + [ ] 1.3.3.4 Subtask - Validate binding type is one of `:value`, `:list`, `:action` + + [ ] 1.4 Section - Ash Domain Configuration + Implement the AshUI domain with all resources and authorization. + + [ ] 1.4.1 Task - Create AshUI.Domain + Define the domain containing all Ash UI resources. + + [ ] 1.4.1.1 Subtask - Implement `AshUI.Domain` with `use Ash.Domain` + [ ] 1.4.1.2 Subtask - Register `AshUI.Screen`, `AshUI.Element`, `AshUI.Binding` resources + [ ] 1.4.1.3 Subtask - Configure domain-level authorization with `Ash.Policy.Authorizer` + + [ ] 1.4.2 Task - Configure resource validations + Add validations for UI resource attributes. + + [ ] 1.4.2.1 Subtask - Validate `unified_dsl` is a valid map structure + [ ] 1.4.2.2 Subtask - Validate `binding_type` is in allowed list + [ ] 1.4.2.3 Subtask - Validate `source` format matches Ash resource paths + [ ] 1.4.2.4 Subtask - Add custom validations with `validate/1` + + [ ] 1.5 Section - Database Migrations + Create Ecto migrations for UI resource tables. + + [ ] 1.5.1 Task - Generate migration files + Create Ecto migrations for all UI resource tables. + + [ ] 1.5.1.1 Subtask - Generate migration for `ui_screens` table + [ ] 1.5.1.2 Subtask - Generate migration for `ui_elements` table + [ ] 1.5.1.3 Subtask - Generate migration for `ui_bindings` table + [ ] 1.5.1.4 Subtask - Add foreign key constraints and indexes + + [ ] 1.5.2 Task - Add unique constraints and indexes + Optimize queries with proper indexes. + + [ ] 1.5.2.1 Subtask - Add unique index on `ui_screens.name` + [ ] 1.5.2.2 Subtask - Add index on `ui_elements.screen_id` + [ ] 1.5.2.3 Subtask - Add composite index on `ui_bindings.element_id` and `screen_id` + + [ ] 1.6 Section - Phase 1 Integration Tests + Validate Ash Resource CRUD, relationships, and DSL behavior end-to-end. + + [ ] 1.6.1 Task - Resource CRUD integration scenarios + Verify create, read, update, and destroy operations work correctly. + + [ ] 1.6.1.1 Subtask - Verify screen creation with unified_dsl storage + [ ] 1.6.1.2 Subtask - Verify element creation with screen association + [ ] 1.6.1.3 Subtask - Verify binding creation with element and screen associations + [ ] 1.6.1.4 Subtask - Verify cascade delete from screen to elements and bindings + + [ ] 1.6.2 Task - DSL and validation integration scenarios + Verify DSL extensions and validations work correctly. + + [ ] 1.6.2.1 Subtask - Verify `ui_screen` DSL creates valid resource attributes + [ ] 1.6.2.2 Subtask - Verify `ui_element` DSL validates widget types + [ ] 1.6.2.3 Subtask - Verify `ui_binding` DSL validates binding types + [ ] 1.6.2.4 Subtask - Verify invalid DSL options produce validation errors + + [ ] 1.6.3 Task - Relationship and query integration scenarios + Verify relationships and queries work correctly. + + [ ] 1.6.3.1 Subtask - Verify loading screen with preloaded elements + [ ] 1.6.3.2 Subtask - Verify loading element with preloaded bindings + [ ] 1.6.3.3 Subtask - Verify querying elements by screen association + [ ] 1.6.3.4 Subtask - Verify querying bindings by element or screen associations diff --git a/specs/planning/phase-02-iur-adapter-and-canonical-conversion.md b/specs/planning/phase-02-iur-adapter-and-canonical-conversion.md new file mode 100644 index 00000000..5af50975 --- /dev/null +++ b/specs/planning/phase-02-iur-adapter-and-canonical-conversion.md @@ -0,0 +1,155 @@ +# Phase 2 - IUR Adapter and Canonical Conversion + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Compilation.IUR` +- `AshUI.Rendering.IURAdapter` +- `UnifiedIUR` (unified_iur package) +- `UnifiedIUR.Screen` +- `UnifiedIUR.Element` +- `UnifiedIUR.Signal` + +## Relevant Assumptions / Defaults +- Ash UI compiles Ash Resources to Ash-internal IUR format +- IUR Adapter converts Ash IUR to canonical unified_iur format +- unified_iur package provides canonical data structures +- Renderer packages consume canonical IUR, not Ash-specific formats + +[ ] 2 Phase 2 - IUR Adapter and Canonical Conversion + Implement the conversion layer from Ash Resources through Ash IUR to canonical unified_iur format for renderer consumption. + + [ ] 2.1 Section - Ash IUR Compilation + Implement compilation from Ash Resources to Ash-internal IUR format. + + [ ] 2.1.1 Task - Define Ash IUR data structures + Create the internal IUR representation used during compilation. + + [ ] 2.1.1.1 Subtask - Implement `AshUI.Compilation.IUR` struct with `id`, `type`, `name` fields + [ ] 2.1.1.2 Subtask - Add `attributes` (map), `children` (list), `bindings` (list) fields + [ ] 2.1.1.3 Subtask - Add `metadata` (map) and `version` (string) fields + [ ] 2.1.1.4 Subtask - Implement `@enforce_keys` for required fields + + [ ] 2.1.2 Task - Implement Resource to IUR compiler + Create the compiler that converts Ash Resources to IUR structures. + + [ ] 2.1.2.1 Subtask - Implement `AshUI.Compiler.compile/2` for screen resources + [ ] 2.1.2.2 Subtask - Convert screen attributes to IUR root element + [ ] 2.1.2.3 Subtask - Load and convert associated elements as IUR children + [ ] 2.1.2.4 Subtask - Load and convert associated bindings as IUR bindings + + [ ] 2.1.3 Task - Implement IUR validation + Ensure compiled IUR structures are valid before conversion. + + [ ] 2.1.3.1 Subtask - Validate IUR has required fields and correct types + [ ] 2.1.3.2 Subtask - Validate children references exist + [ ] 2.1.3.3 Subtask - Validate binding references are resolvable + [ ] 2.1.3.4 Subtask - Return structured errors for invalid IUR + + [ ] 2.2 Section - Canonical IUR Adapter + Implement conversion from Ash IUR to canonical unified_iur format. + + [ ] 2.2.1 Task - Define adapter interface + Create the adapter contract for IUR conversion. + + [ ] 2.2.1.1 Subtask - Implement `AshUI.Rendering.IURAdapter.to_canonical/1` function + [ ] 2.2.1.2 Subtask - Return `{:ok, UnifiedIUR.Screen.t()}` or `{:error, term()}` + [ ] 2.2.1.3 Subtask - Implement `compatible?/2` to check renderer compatibility + [ ] 2.2.1.4 Subtask - Add telemetry events for conversion success/failure + + [ ] 2.2.2 Task - Implement element type mapping + Map Ash UI element types to unified-ui widget types. + + [ ] 2.2.2.1 Subtask - Create type mapping table (button, input, text, image, etc.) + [ ] 2.2.2.2 Subtask - Convert Ash element `type` to unified widget `type` + [ ] 2.2.2.3 Subtask - Handle unknown element types with error or fallback + [ ] 2.2.2.4 Subtask - Document supported element types + + [ ] 2.2.3 Task - Implement props mapping + Map Ash element props to unified-ui widget attributes. + + [ ] 2.2.3.1 Subtask - Convert Ash `props` map to unified widget attributes + [ ] 2.2.3.2 Subtask - Handle prop name conversions (e.g., `onClick` → `on_click`) + [ ] 2.2.3.3 Subtask - Filter out Ash-specific props from canonical IUR + [ ] 2.2.3.4 Subtask - Apply prop transformations for type compatibility + + [ ] 2.2.4 Task - Implement layout mapping + Convert Ash screen layout to unified-ui layout constructs. + + [ ] 2.2.4.1 Subtask - Map Ash `layout` attribute to unified layout type + [ ] 2.2.4.2 Subtask - Convert children to unified container structure + [ ] 2.2.4.3 Subtask - Handle nested layouts and layering constructs + [ ] 2.2.4.4 Subtask - Preserve layout metadata in canonical IUR + + [ ] 2.3 Section - Signal Conversion + Convert Ash UI bindings to unified-ui signal format. + + [ ] 2.3.1 Task - Define signal mapping + Create the mapping from Ash bindings to unified signals. + + [ ] 2.3.1.1 Subtask - Implement `AshUI.Signal.to_canonical/1` function + [ ] 2.3.1.2 Subtask - Convert binding source to unified signal source format + [ ] 2.3.1.3 Subtask - Convert binding target to unified signal target format + [ ] 2.3.1.4 Subtask - Map binding type to unified signal type + + [ ] 2.3.2 Task - Implement binding type conversion + Map Ash binding types to unified signal types. + + [ ] 2.3.2.1 Subtask - Convert `:value` binding to bidirectional signal + [ ] 2.3.2.2 Subtask - Convert `:list` binding to collection signal + [ ] 2.3.2.3 Subtask - Convert `:action` binding to event signal + [ ] 2.3.2.4 Subtask - Handle transformation rules in signal definition + + [ ] 2.3.3 Task - Implement signal source resolution + Resolve Ash resource paths in binding sources. + + [ ] 2.3.3.1 Subtask - Parse binding source path (Domain.Resource.Attribute) + [ ] 2.3.3.2 Subtask - Validate source exists in Ash resource definitions + [ ] 2.3.3.3 Subtask - Convert source path to unified signal reference + [ ] 2.3.3.4 Subtask - Handle nested paths and relationship traversal + + [ ] 2.4 Section - Error Handling and Validation + Implement error handling for IUR conversion failures. + + [ ] 2.4.1 Task - Define error types + Create structured error types for conversion failures. + + [ ] 2.4.1.1 Subtask - Implement `AshUI.Rendering.ConversionError` exception + [ ] 2.4.1.2 Subtask - Add error fields: `phase`, `element_id`, `reason` + [ ] 2.4.1.3 Subtask - Implement error formatting for user display + [ ] 2.4.1.4 Subtask - Add error telemetry with correlation IDs + + [ ] 2.4.2 Task - Implement validation checks + Add validation at each conversion stage. + + [ ] 2.4.2.1 Subtask - Validate Ash IUR before canonical conversion + [ ] 2.4.2.2 Subtask - Validate canonical IUR structure after conversion + [ ] 2.4.2.3 Subtask - Collect all validation errors before returning + [ ] 2.4.2.4 Subtask - Provide detailed error location information + + [ ] 2.5 Section - Phase 2 Integration Tests + Validate IUR compilation and canonical conversion end-to-end. + + [ ] 2.5.1 Task - Compilation integration scenarios + Verify Ash Resource to IUR compilation works correctly. + + [ ] 2.5.1.1 Subtask - Verify screen resource compiles to valid IUR structure + [ ] 2.5.1.2 Subtask - Verify elements are compiled as IUR children + [ ] 2.5.1.3 Subtask - Verify bindings are compiled as IUR bindings + [ ] 2.5.1.4 Subtask - Verify invalid resources produce compilation errors + + [ ] 2.5.2 Task - Canonical conversion integration scenarios + Verify Ash IUR to canonical IUR conversion works correctly. + + [ ] 2.5.2.1 Subtask - Verify simple element converts to canonical widget + [ ] 2.5.2.2 Subtask - Verify layout converts to canonical layout structure + [ ] 2.5.2.3 Subtask - Verify binding converts to canonical signal + [ ] 2.5.2.4 Subtask - Verify complex nested screen converts fully + + [ ] 2.5.3 Task - Error handling integration scenarios + Verify errors are handled gracefully. + + [ ] 2.5.3.1 Subtask - Verify invalid IUR produces structured error + [ ] 2.5.3.2 Subtask - Verify unknown element type produces clear error + [ ] 2.5.3.3 Subtask - Verify invalid binding source produces resolution error + [ ] 2.5.3.4 Subtask - Verify partial failures don't crash adapter diff --git a/specs/planning/phase-03-data-binding-and-signal-mapping.md b/specs/planning/phase-03-data-binding-and-signal-mapping.md new file mode 100644 index 00000000..c625a90a --- /dev/null +++ b/specs/planning/phase-03-data-binding-and-signal-mapping.md @@ -0,0 +1,165 @@ +# Phase 3 - Data Binding and Signal Mapping + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Binding` +- `AshUI.Signal` +- `AshUI.Runtime.BindingEvaluator` +- `UnifiedIUR.Signal` +- Ash Resource actions (`read`, `create`, `update`, `destroy`) + +## Relevant Assumptions / Defaults +- Bindings connect UI elements to Ash resource data +- Signals use Jido.Signal format per unified-ui signal transport spec +- Bidirectional bindings support read and write operations +- Action bindings trigger Ash actions on UI events + +[ ] 3 Phase 3 - Data Binding and Signal Mapping + Implement reactive data binding from Ash resources to UI elements through unified-ui signal format. + + [ ] 3.1 Section - Binding Evaluation + Implement runtime evaluation of bindings against Ash resource data. + + [ ] 3.1.1 Task - Implement binding evaluator + Create the evaluator that resolves bindings to actual values. + + [ ] 3.1.1.1 Subtask - Implement `AshUI.Runtime.BindingEvaluator.evaluate/3` + [ ] 3.1.1.2 Subtask - Accept binding, context (user_id, params), and socket assigns + [ ] 3.1.1.3 Subtask - Return `{:ok, value}` or `{:error, reason}` + [ ] 3.1.1.4 Subtask - Cache evaluated values for performance + + [ ] 3.1.2 Task - Implement source path resolution + Resolve binding source paths to Ash resource attributes. + + [ ] 3.1.2.1 Subtask - Parse source path (Domain.Resource.Attribute) + [ ] 3.1.2.2 Subtask - Load resource using `Ash.get/3` with proper authorization + [ ] 3.1.2.3 Subtask - Extract attribute value from loaded resource + [ ] 3.1.2.4 Subtask - Handle relationship traversal (e.g., `user.profile.name`) + + [ ] 3.1.3 Task - Implement transformation application + Apply transformation rules to resolved values. + + [ ] 3.1.3.1 Subtask - Apply `format` transformations (e.g., date formatting) + [ ] 3.1.3.2 Subtask - Apply `compute` transformations (e.g., calculated fields) + [ ] 3.1.3.3 Subtask - Apply `default` transformations when source is nil + [ ] 3.1.3.4 Subtask - Apply `validate` transformations and return errors + + [ ] 3.2 Section - Bidirectional Value Bindings + Implement two-way data binding for `:value` type bindings. + + [ ] 3.2.1 Task - Implement read direction + Flow data from Ash resources to UI elements. + + [ ] 3.2.1.1 Subtask - Subscribe to Ash resource changes + [ ] 3.2.1.2 Subtask - Re-evaluate binding on resource change + [ ] 3.2.1.3 Subtask - Update LiveView assigns on value change + [ ] 3.2.1.4 Subtask - Handle loading and error states + + [ ] 3.2.2 Task - Implement write direction + Flow data from UI elements to Ash resources. + + [ ] 3.2.2.1 Subtask - Capture user input events from LiveView + [ ] 3.2.2.2 Subtask - Validate input data before writing + [ ] 3.2.2.3 Subtask - Call `Ash.update/3` with new value + [ ] 3.2.2.4 Subtask - Handle update errors and display to user + + [ ] 3.2.3 Task - Implement conflict resolution + Handle concurrent updates to shared data. + + [ ] 3.2.3.1 Subtask - Detect stale data with optimistic locking + [ ] 3.2.3.2 Subtask - Retry on conflict with backoff + [ ] 3.2.3.3 Subtask - Present conflict UI to user for resolution + [ ] 3.2.3.4 Subtask - Emit conflict telemetry events + + [ ] 3.3 Section - List Bindings + Implement collection binding for `:list` type bindings. + + [ ] 3.3.1 Task - Implement collection loading + Load and bind collections of resources to UI elements. + + [ ] 3.3.1.1 Subtask - Resolve collection source path + [ ] 3.3.1.2 Subtask - Use `Ash.read/2` to load collection + [ ] 3.3.1.3 Subtask - Apply pagination and filtering + [ ] 3.3.1.4 Subtask - Handle empty collections + + [ ] 3.3.2 Task - Implement collection reactivity + Update UI when collection data changes. + + [ ] 3.3.2.1 Subtask - Subscribe to collection changes + [ ] 3.3.2.2 Subtask - Re-render list on collection modification + [ ] 3.3.2.3 Subtask - Handle insert, update, delete operations + [ ] 3.3.2.4 Subtask - Maintain scroll position during updates + + [ ] 3.4 Section - Action Bindings + Implement event-driven binding for `:action` type bindings. + + [ ] 3.4.1 Task - Implement action execution + Execute Ash actions in response to UI events. + + [ ] 3.4.1.1 Subtask - Parse action source (Domain.Resource.action_name) + [ ] 3.4.1.2 Subtask - Call `Ash.action/3` with event data + [ ] 3.4.1.3 Subtask - Check authorization before execution + [ ] 3.4.1.4 Subtask - Return action result to UI + + [ ] 3.4.2 Task - Implement action event wiring + Connect UI events to action bindings. + + [ ] 3.4.2.1 Subtask - Generate event handler from binding definition + [ ] 3.4.2.2 Subtask - Wire handler to LiveView `handle_event/3` + [ ] 3.4.2.3 Subtask - Pass event data to action parameters + [ ] 3.4.2.4 Subtask - Handle action errors and display feedback + + [ ] 3.5 Section - Signal Format Conversion + Convert Ash bindings to unified-ui signal format. + + [ ] 3.5.1 Task - Define signal structure + Create the signal structure matching unified-ui spec. + + [ ] 3.5.1.1 Subtask - Implement `AshUI.Signal` struct with `id`, `source`, `target` fields + [ ] 3.5.1.2 Subtask - Add `type`, `transform`, `metadata` fields + [ ] 3.5.1.3 Subtask - Implement signal creation helpers + [ ] 3.5.1.4 Subtask - Add signal validation + + [ ] 3.5.2 Task - Convert to Jido.Signal format + Ensure signals are compatible with unified signal transport. + + [ ] 3.5.2.1 Subtask - Wrap Ash signals in Jido.Signal structure + [ ] 3.5.2.2 Subtask - Use CloudEvents-compatible event format + [ ] 3.5.2.3 Subtask - Include required CloudEvents fields (id, source, type) + [ ] 3.5.2.4 Subtask - Add signal metadata for tracing + + [ ] 3.6 Section - Phase 3 Integration Tests + Validate binding evaluation and reactivity end-to-end. + + [ ] 3.6.1 Task - Value binding integration scenarios + Verify bidirectional value bindings work correctly. + + [ ] 3.6.1.1 Subtask - Verify binding reads from Ash resource on mount + [ ] 3.6.1.2 Subtask - Verify binding updates on resource change + [ ] 3.6.1.3 Subtask - Verify user input writes back to Ash resource + [ ] 3.6.1.4 Subtask - Verify transformation rules apply correctly + + [ ] 3.6.2 Task - List binding integration scenarios + Verify collection bindings work correctly. + + [ ] 3.6.2.1 Subtask - Verify list loads and displays collection + [ ] 3.6.2.2 Subtask - Verify list updates on collection changes + [ ] 3.6.2.3 Subtask - Verify pagination and filtering work + [ ] 3.6.2.4 Subtask - Verify empty list state displays correctly + + [ ] 3.6.3 Task - Action binding integration scenarios + Verify action bindings execute correctly. + + [ ] 3.6.3.1 Subtask - Verify button click triggers Ash action + [ ] 3.6.3.2 Subtask - Verify action passes event data correctly + [ ] 3.6.3.3 Subtask - Verify authorization is checked + [ ] 3.6.3.4 Subtask - Verify action errors display to user + + [ ] 3.6.4 Task - Error handling integration scenarios + Verify binding errors are handled gracefully. + + [ ] 3.6.4.1 Subtask - Verify invalid source produces clear error + [ ] 3.6.4.2 Subtask - Verify unauthorized access is blocked + [ ] 3.6.4.3 Subtask - Verify transformation errors are surfaced + [ ] 3.6.4.4 Subtask - Verify action execution errors display feedback diff --git a/specs/planning/phase-04-runtime-and-liveview-integration.md b/specs/planning/phase-04-runtime-and-liveview-integration.md new file mode 100644 index 00000000..0b3f5140 --- /dev/null +++ b/specs/planning/phase-04-runtime-and-liveview-integration.md @@ -0,0 +1,165 @@ +# Phase 4 - Runtime and LiveView Integration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Runtime.Session` +- `AshUI.LiveView` +- `AshUI.Runtime.Lifecycle` +- `Phoenix.LiveView` +- `Phoenix.LiveView.Socket` + +## Relevant Assumptions / Defaults +- LiveView provides the runtime session boundary +- Screen lifecycle maps to LiveView mount/update/unmount +- Each LiveView session has isolated state +- Events flow through LiveView `handle_event/3` and `handle_info/2` + +[ ] 4 Phase 4 - Runtime and LiveView Integration + Implement the LiveView integration layer that manages screen lifecycle, session state, and event handling. + + [ ] 4.1 Section - LiveView Mount Integration + Implement screen mounting through LiveView `mount/3` callback. + + [ ] 4.1.1 Task - Implement mount_ui_screen helper + Create the helper function for mounting UI screens in LiveView. + + [ ] 4.1.1.1 Subtask - Implement `AshUI.LiveView.mount_ui_screen/3` + [ ] 4.1.1.2 Subtask - Accept socket, screen identifier, and params + [ ] 4.1.1.3 Subtask - Load screen resource by name or ID + [ ] 4.1.1.4 Subtask - Return `{:ok, socket}` with screen state assigned + + [ ] 4.1.2 Task - Implement screen authorization on mount + Check Ash policies before allowing screen access. + + [ ] 4.1.2.1 Subtask - Load current user from socket assigns + [ ] 4.1.2.2 Subtask - Check `:mount` action policy for screen resource + [ ] 4.1.2.3 Subtask - Redirect to login on authorization failure + [ ] 4.1.2.4 Subtask - Emit authorization failure telemetry + + [ ] 4.1.3 Task - Compile screen on mount + Compile the screen resource to IUR on initial mount. + + [ ] 4.1.3.1 Subtask - Call compiler with screen resource + [ ] 4.1.3.2 Subtask - Convert to canonical IUR + [ ] 4.1.3.3 Subtask - Store compiled IUR in socket assigns + [ ] 4.1.3.4 Subtask - Handle compilation errors gracefully + + [ ] 4.1.4 Task - Evaluate bindings on mount + Resolve all data bindings for initial render. + + [ ] 4.1.4.1 Subtask - Load all bindings for screen and elements + [ ] 4.1.4.2 Subtask - Evaluate bindings against current data + [ ] 4.1.4.3 Subtask - Store binding values in socket assigns + [ ] 4.1.4.4 Subtask - Handle binding evaluation errors + + [ ] 4.2 Section - LiveView Update Integration + Implement reactive updates through LiveView `handle_info/2` callback. + + [ ] 4.2.1 Task - Subscribe to data changes + Subscribe to Ash resource change notifications. + + [ ] 4.2.1.1 Subtask - Subscribe to `Ash.Notifier` for resource changes + [ ] 4.2.1.2 Subtask - Filter notifications to bound resources + [ ] 4.2.1.3 Subtask - Handle subscription messages in `handle_info/2` + [ ] 4.2.1.4 Subtask - Unsubscribe on unmount + + [ ] 4.2.2 Task - Re-render on data changes + Update LiveView when bound data changes. + + [ ] 4.2.2.1 Subtask - Re-evaluate affected bindings on notification + [ ] 4.2.2.2 Subtask - Update socket assigns with new values + [ ] 4.2.2.3 Subtask - Trigger LiveView re-render + [ ] 4.2.2.4 Subtask - Batch multiple updates for performance + + [ ] 4.3 Section - Event Handling Integration + Implement UI event handling through LiveView `handle_event/3` callback. + + [ ] 4.3.1 Task - Implement event routing + Route UI events to appropriate handlers. + + [ ] 4.3.1.1 Subtask - Parse event name and target from UI + [ ] 4.3.1.2 Subtask - Match event to binding or action + [ ] 4.3.1.3 Subtask - Route to appropriate handler module + [ ] 4.3.1.4 Subtask - Handle unknown events gracefully + + [ ] 4.3.2 Task - Implement value change events + Handle input value changes from form elements. + + [ ] 4.3.2.1 Subtask - Capture `phx-blur` or `phx-change` events + [ ] 4.3.2.2 Subtask - Update socket assigns with new value + [ ] 4.3.2.3 Subtask - Write value to Ash resource for `:value` bindings + [ ] 4.3.2.4 Subtask - Handle validation errors + + [ ] 4.3.3 Task - Implement action events + Handle button clicks and other action triggers. + + [ ] 4.3.3.1 Subtask - Capture `phx-click` events from buttons + [ ] 4.3.3.2 Subtask - Extract action binding from event target + [ ] 4.3.3.3 Subtask - Execute Ash action with parameters + [ ] 4.3.3.4 Subtask - Return action result to UI + + [ ] 4.4 Section - Screen Lifecycle Management + Implement screen lifecycle hooks and state management. + + [ ] 4.4.1 Task - Implement lifecycle hooks + Add hooks for screen lifecycle events. + + [ ] 4.4.1.1 Subtask - Implement `on_mount` hook for initialization + [ ] 4.4.1.2 Subtask - Implement `on_update` hook for state changes + [ ] 4.4.1.3 Subtask - Implement `on_unmount` hook for cleanup + [ ] 4.4.1.4 Subtask - Allow user-defined lifecycle callbacks + + [ ] 4.4.2 Task - Implement state isolation + Ensure each LiveView session has isolated state. + + [ ] 4.4.2.1 Subtask - Store screen state in socket assigns + [ ] 4.4.2.2 Subtask - Use session-specific identifiers for state + [ ] 4.4.2.3 Subtask - Prevent state leakage between sessions + [ ] 4.4.2.4 Subtask - Clean up session state on disconnect + + [ ] 4.5 Section - Error Handling and Recovery + Implement error handling for runtime failures. + + [ ] 4.5.1 Task - Handle compilation errors + Gracefully handle screen compilation failures. + + [ ] 4.5.1.1 Subtask - Display user-friendly error message + [ ] 4.5.1.2 Subtask - Log detailed error for debugging + [ ] 4.5.1.3 Subtask - Provide retry option for transient errors + [ ] 4.5.1.4 Subtask - Emit error telemetry + + [ ] 4.5.2 Task - Handle binding errors + Gracefully handle binding evaluation failures. + + [ ] 4.5.2.1 Subtask - Display placeholder or error state in UI + [ ] 4.5.2.2 Subtask - Continue rendering despite failed bindings + [ ] 4.5.2.3 Subtask - Log binding errors with context + [ ] 4.5.2.4 Subtask - Retry binding evaluation on recovery + + [ ] 4.6 Section - Phase 4 Integration Tests + Validate LiveView integration and lifecycle management end-to-end. + + [ ] 4.6.1 Task - Mount lifecycle integration scenarios + Verify screen mounting and initialization. + + [ ] 4.6.1.1 Subtask - Verify screen mounts with valid user + [ ] 4.6.1.2 Subtask - Verify screen redirects on unauthorized access + [ ] 4.6.1.3 Subtask - Verify bindings are evaluated on mount + [ ] 4.6.1.4 Subtask - Verify compilation errors are handled + + [ ] 4.6.2 Task - Event handling integration scenarios + Verify UI events are handled correctly. + + [ ] 4.6.2.1 Subtask - Verify button clicks trigger Ash actions + [ ] 4.6.2.2 Subtask - Verify input changes update Ash resources + [ ] 4.6.2.3 Subtask - Verify action errors display feedback + [ ] 4.6.2.4 Subtask - Verify event handlers receive correct parameters + + [ ] 4.6.3 Task - Reactivity integration scenarios + Verify reactive updates work correctly. + + [ ] 4.6.3.1 Subtask - Verify UI updates when bound data changes + [ ] 4.6.3.2 Subtask - Verify multiple sessions don't interfere + [ ] 4.6.3.3 Subtask - Verify updates are batched efficiently + [ ] 4.6.3.4 Subtask - Verify subscriptions clean up on unmount diff --git a/specs/planning/phase-05-authorization-and-policy-enforcement.md b/specs/planning/phase-05-authorization-and-policy-enforcement.md new file mode 100644 index 00000000..d83e4e93 --- /dev/null +++ b/specs/planning/phase-05-authorization-and-policy-enforcement.md @@ -0,0 +1,161 @@ +# Phase 5 - Authorization and Policy Enforcement + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `Ash.Policy.Authorizer` +- `Ash.Policy.Check` +- `AshUI.Resource` +- Ash policy DSL (`policy`, `authorize_if`, `forbid_if`) + +## Relevant Assumptions / Defaults +- Ash policies control access to UI resources +- Policies are checked on mount and for each action +- Unauthorized access returns user-friendly errors +- Policy failures emit telemetry events + +[ ] 5 Phase 5 - Authorization and Policy Enforcement + Implement Ash policy integration for UI resource access control and action authorization. + + [ ] 5.1 Section - Policy Definitions + Define Ash policies for UI resources. + + [ ] 5.1.1 Task - Define UI.Screen policies + Add policies to screen resource for access control. + + [ ] 5.1.1.1 Subtask - Add `policies` block to `AshUI.Screen` resource + [ ] 5.1.1.2 Subtask - Define `:read` policy for screen viewing + [ ] 5.1.1.3 Subtask - Define `:mount` policy for screen mounting + [ ] 5.1.1.4 Subtask - Define `:create`, `:update`, `:destroy` policies + + [ ] 5.1.2 Task - Define UI.Element policies + Add policies to element resource for access control. + + [ ] 5.1.2.1 Subtask - Add `policies` block to `AshUI.Element` resource + [ ] 5.1.2.2 Subtask - Define element visibility policies + [ ] 5.1.2.3 Subtask - Define element modification policies + [ ] 5.1.2.4 Subtask - Inherit screen policies where appropriate + + [ ] 5.1.3 Task - Define UI.Binding policies + Add policies to binding resource for access control. + + [ ] 5.1.3.1 Subtask - Add `policies` block to `AshUI.Binding` resource + [ ] 5.1.3.2 Subtask - Define binding evaluation policies + [ ] 5.1.3.3 Subtask - Define binding modification policies + [ ] 5.1.3.4 Subtask - Check data source access in binding policies + + [ ] 5.1.4 Task - Define common policy checks + Create reusable policy checks for UI resources. + + [ ] 5.1.4.1 Subtask - Implement `user_active` check + [ ] 5.1.4.2 Subtask - Implement `user_role` check with roles + [ ] 5.1.4.3 Subtask - Implement `screen_owner` check + [ ] 5.1.4.4 Subtask - Implement `environment` check (dev/prod) + + [ ] 5.2 Section - Runtime Authorization + Implement policy checking at runtime. + + [ ] 5.2.1 Task - Check policies on mount + Verify authorization when screen is mounted. + + [ ] 5.2.1.1 Subtask - Extract user from LiveView session + [ ] 5.2.1.2 Subtask - Call `Ash.can?/3` for mount action + [ ] 5.2.1.3 Subtask - Redirect on authorization failure + [ ] 5.2.1.4 Subtask - Emit authorization attempt telemetry + + [ ] 5.2.2 Task - Check policies on actions + Verify authorization before executing actions. + + [ ] 5.2.2.1 Subtask - Check policy before Ash action execution + [ ] 5.2.2.2 Subtask - Return user-friendly error on denial + [ ] 5.2.2.3 Subtask - Log authorization failures + [ ] 5.2.2.4 Subtask - Include policy details in error message + + [ ] 5.2.3 Task - Check data source access + Verify access to bound Ash resources. + + [ ] 5.2.3.1 Subtask - Check `:read` policy on binding source resource + [ ] 5.2.3.2 Subtask - Check `:update` policy for write bindings + [ ] 5.2.3.3 Subtask - Handle unauthorized data access gracefully + [ ] 5.2.3.4 Subtask - Redact sensitive data when unauthorized + + [ ] 5.2.4 Task - Implement policy caching + Cache policy results for performance. + + [ ] 5.2.4.1 Subtask - Cache policy checks per user/resource + [ ] 5.2.4.2 Subtask - Invalidate cache on resource change + [ ] 5.2.4.3 Subtask - Invalidate cache on role change + [ ] 5.2.4.4 Subtask - Configure cache TTL + + [ ] 5.3 Section - Policy DSL Extensions + Create DSL extensions for common UI authorization patterns. + + [ ] 5.3.1 Task - Create UI policy DSL + Add convenience functions for UI policies. + + [ ] 5.3.1.1 Subtask - Implement `visible_if/2` policy helper + [ ] 5.3.1.2 Subtask - Implement `editable_if/2` policy helper + [ ] 5.3.1.3 Subtask - Implement `accessible_if/2` policy helper + [ ] 5.3.1.4 Subtask - Document policy DSL usage + + [ ] 5.3.2 Task - Create resource-level policies + Add policies for accessing bound resources. + + [ ] 5.3.2.1 Subtask - Implement `can_read_source/1` policy + [ ] 5.3.2.2 Subtask - Implement `can_write_source/1` policy + [ ] 5.3.2.3 Subtask - Implement `can_access_field/2` policy + [ ] 5.3.2.4 Subtask - Implement `can_execute_action/2` policy + + [ ] 5.4 Section - Error Handling + Implement user-friendly authorization errors. + + [ ] 5.4.1 Task - Define error types + Create structured error types for authorization failures. + + [ ] 5.4.1.1 Subtask - Implement `AshUI.AuthorizationError` exception + [ ] 5.4.1.2 Subtask - Add fields: `resource`, `action`, `policy`, `reason` + [ ] 5.4.1.3 Subtask - Implement error formatting for display + [ ] 5.4.1.4 Subtask - Add error translation support + + [ ] 5.4.2 Task - Display authorization errors + Present authorization errors to users. + + [ ] 5.4.2.1 Subtask - Show clear "access denied" message + [ ] 5.4.2.2 Subtask - Suggest login link for unauthenticated users + [ ] 5.4.2.3 Subtask - Show required permissions for authorized users + [ ] 5.4.2.4 Subtask - Support custom error pages per resource + + [ ] 5.5 Section - Phase 5 Integration Tests + Validate authorization and policy enforcement end-to-end. + + [ ] 5.5.1 Task - Mount authorization scenarios + Verify screen mount authorization works correctly. + + [ ] 5.5.1.1 Subtask - Verify authorized user can mount screen + [ ] 5.5.1.2 Subtask - Verify unauthorized user is redirected + [ ] 5.5.1.3 Subtask - Verify unauthenticated user redirects to login + [ ] 5.5.1.4 Subtask - Verify policy changes affect access immediately + + [ ] 5.5.2 Task - Action authorization scenarios + Verify action authorization works correctly. + + [ ] 5.5.2.1 Subtask - Verify authorized action executes successfully + [ ] 5.5.2.2 Subtask - Verify unauthorized action returns error + [ ] 5.5.2.3 Subtask - Verify action errors include policy details + [ ] 5.5.2.4 Subtask - Verify partial authorization (some fields allowed) + + [ ] 5.5.3 Task - Data source authorization scenarios + Verify binding data source authorization. + + [ ] 5.5.3.1 Subtask - Verify authorized binding shows data + [ ] 5.5.3.2 Subtask - Verify unauthorized binding shows placeholder + [ ] 5.5.3.3 Subtask - Verify unauthorized binding doesn't leak data + [ ] 5.5.3.4 Subtask - Verify cross-resource authorization works + + [ ] 5.5.4 Task - Policy caching scenarios + Verify policy caching behavior. + + [ ] 5.5.4.1 Subtask - Verify repeated checks use cache + [ ] 5.5.4.2 Subtask - Verify cache invalidates on resource change + [ ] 5.5.4.3 Subtask - Verify cache invalidates on role change + [ ] 5.5.4.4 Subtask - Verify cache TTL is respected diff --git a/specs/planning/phase-06-compiler-and-dsl-integration.md b/specs/planning/phase-06-compiler-and-dsl-integration.md new file mode 100644 index 00000000..fd7a520a --- /dev/null +++ b/specs/planning/phase-06-compiler-and-dsl-integration.md @@ -0,0 +1,145 @@ +# Phase 6 - Compiler and DSL Integration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Compiler` +- `unified-ui` compiler +- `AshUI.Resource.DSL` +- unified-ui DSL + +## Relevant Assumptions / Defaults +- unified-ui provides the canonical UI DSL +- Ash UI stores unified-ui DSL in Ash Resources +- Compiler loads DSL from database and compiles to IUR +- Compilation is cached for performance + +[ ] 6 Phase 6 - Compiler and DSL Integration + Integrate the unified-ui compiler with Ash Resource loading to enable database-driven UI definitions. + + [ ] 6.1 Section - Unified-UI DSL Storage + Store unified-ui DSL definitions in Ash Resource attributes. + + [ ] 6.1.1 Task - Define DSL storage format + Create the format for storing unified-ui DSL in database. + + [ ] 6.1.1.1 Subtask - Define `unified_dsl` map attribute structure + [ ] 6.1.1.2 Subtask - Store root element definition in DSL map + [ ] 6.1.1.3 Subtask - Store children array in DSL map + [ ] 6.1.1.4 Subtask - Store signals array in DSL map + + [ ] 6.1.2 Task - Create DSL builder helpers + Provide helper functions for building unified-ui DSL. + + [ ] 6.1.2.1 Subtask - Implement `AshUI.DSL.root/2` macro + [ ] 6.1.2.2 Subtask - Implement `AshUI.DSL.row/1`, `column/1` layout macros + [ ] 6.1.2.3 Subtask - Implement `AshUI.DSL.text/1`, `button/1` widget macros + [ ] 6.1.2.4 Subtask - Implement `AshUI.DSL.signal/3` for bindings + + [ ] 6.1.3 Task - Validate DSL at write time + Ensure stored DSL is valid unified-ui format. + + [ ] 6.1.3.1 Subtask - Validate DSL structure before database write + [ ] 6.1.3.2 Subtask - Check widget types against unified-ui catalog + [ ] 6.1.3.3 Subtask - Check signal references are valid + [ ] 6.1.3.4 Subtask - Return validation errors for invalid DSL + + [ ] 6.2 Section - Compiler Integration + Integrate unified-ui compiler with Ash Resource loading. + + [ ] 6.2.1 Task - Implement AshUI.Compiler + Create the compiler that loads and compiles UI definitions. + + [ ] 6.2.1.1 Subtask - Implement `AshUI.Compiler.compile_screen/2` + [ ] 6.2.1.2 Subtask - Load screen resource from database + [ ] 6.2.1.3 Subtask - Extract `unified_dsl` from resource + [ ] 6.2.1.4 Subtask - Pass DSL to unified-ui compiler + + [ ] 6.2.2 Task - Integrate unified-ui compiler + Call unified-ui compiler to produce IUR. + + [ ] 6.2.2.1 Subtask - Add `unified_ui` as dependency + [ ] 6.2.2.2 Subtask - Call `UnifiedUI.Compiler.compile/1` + [ ] 6.2.2.3 Subtask - Handle compilation errors from unified-ui + [ ] 6.2.2.4 Subtask - Return Ash IUR or error + + [ ] 6.2.3 Task - Implement compilation caching + Cache compiled IUR for performance. + + [ ] 6.2.3.1 Subtask - Generate cache key from resource ID and version + [ ] 6.2.3.2 Subtask - Store compiled IUR in ETS cache + [ ] 6.2.3.3 Subtask - Invalidate cache on resource update + [ ] 6.2.3.4 Subtask - Configure cache size and TTL + + [ ] 6.3 Section - Incremental Compilation + Support efficient recompilation when resources change. + + [ ] 6.3.1 Task - Track resource dependencies + Track which resources depend on which. + + [ ] 6.3.1.1 Subtask - Record element-to-screen dependencies + [ ] 6.3.1.2 Subtask - Record binding-to-element dependencies + [ ] 6.3.1.3 Subtask - Detect circular dependencies + [ ] 6.3.1.4 Subtask - Maintain dependency graph + + [ ] 6.3.2 Task - Implement selective recompilation + Only recompile affected resources when things change. + + [ ] 6.3.2.1 Subtask - On element change, recompile parent screen + [ ] 6.3.2.2 Subtask - On binding change, recompile affected elements + [ ] 6.3.2.3 Subtask - Use cached IUR for unchanged resources + [ ] 6.3.2.4 Subtask - Batch recompilation for multiple changes + + [ ] 6.4 Section - Compiler Extensions + Support custom widget and layout extensions. + + [ ] 6.4.1 Task - Implement custom widget registration + Allow registration of custom unified-ui widgets. + + [ ] 6.4.1.1 Subtask - Implement `AshUI.Compiler.register_widget/2` + [ ] 6.4.1.2 Subtask - Validate widget against unified-ui spec + [ ] 6.4.1.3 Subtask - Add widget to compiler catalog + [ ] 6.4.1.4 Subtask - Document widget registration API + + [ ] 6.4.2 Task - Implement custom layout registration + Allow registration of custom unified-ui layouts. + + [ ] 6.4.2.1 Subtask - Implement `AshUI.Compiler.register_layout/2` + [ ] 6.4.2.2 Subtask - Validate layout against unified-ui spec + [ ] 6.4.2.3 Subtask - Add layout to compiler catalog + [ ] 6.4.2.4 Subtask - Document layout registration API + + [ ] 6.5 Section - Phase 6 Integration Tests + Validate compiler and DSL integration end-to-end. + + [ ] 6.5.1 Task - DSL storage and retrieval scenarios + Verify DSL is stored and retrieved correctly. + + [ ] 6.5.1.1 Subtask - Verify DSL builder creates valid structure + [ ] 6.5.1.2 Subtask - Verify DSL persists to database correctly + [ ] 6.5.1.3 Subtask - Verify DSL loads from database correctly + [ ] 6.5.1.4 Subtask - Verify invalid DSL is rejected + + [ ] 6.5.2 Task - Compilation scenarios + Verify compilation pipeline works correctly. + + [ ] 6.5.2.1 Subtask - Verify simple screen compiles successfully + [ ] 6.5.2.2 Subtask - Verify complex nested screen compiles successfully + [ ] 6.5.2.3 Subtask - Verify compilation errors are reported clearly + [ ] 6.5.2.4 Subtask - Verify cache hit returns cached IUR + + [ ] 6.5.3 Task - Incremental compilation scenarios + Verify incremental recompilation works correctly. + + [ ] 6.5.3.1 Subtask - Verify element change triggers screen recompile + [ ] 6.5.3.2 Subtask - Verify unchanged resources use cache + [ ] 6.5.3.3 Subtask - Verify dependency tracking works + [ ] 6.5.3.4 Subtask - Verify circular dependencies are detected + + [ ] 6.5.4 Task - Extension scenarios + Verify custom widgets and layouts work. + + [ ] 6.5.4.1 Subtask - Verify custom widget can be registered + [ ] 6.5.4.2 Subtask - Verify custom widget compiles correctly + [ ] 6.5.4.3 Subtask - Verify custom layout can be registered + [ ] 6.5.4.4 Subtask - Verify custom layout compiles correctly diff --git a/specs/planning/phase-07-renderer-package-integration.md b/specs/planning/phase-07-renderer-package-integration.md new file mode 100644 index 00000000..185d91a7 --- /dev/null +++ b/specs/planning/phase-07-renderer-package-integration.md @@ -0,0 +1,157 @@ +# Phase 7 - Renderer Package Integration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `AshUI.Rendering.IURAdapter` +- `LiveUI.Renderer` (live_ui package) +- `WebUI.Renderer` (web_ui package) +- `DesktopUI.Renderer` (desktop_ui package) +- `UnifiedIUR` (unified_iur package) + +## Relevant Assumptions / Defaults +- Renderer packages are external dependencies +- Application selects which renderer to use +- Canonical IUR is passed to selected renderer +- Renderers produce platform-specific output + +[ ] 7 Phase 7 - Renderer Package Integration + Integrate with external unified renderer packages (live_ui, web_ui, desktop_ui) for final output generation. + + [ ] 7.1 Section - Package Dependencies + Add and configure unified renderer packages as dependencies. + + [ ] 7.1.1 Task - Add renderer packages to mix.exs + Include renderer packages as optional dependencies. + + [ ] 7.1.1.1 Subtask - Add `unified_iur` to deps + [ ] 7.1.1.2 Subtask - Add `live_ui` as optional dependency + [ ] 7.1.1.3 Subtask - Add `web_ui` as optional dependency + [ ] 7.1.1.4 Subtask - Add `desktop_ui` as optional dependency + + [ ] 7.1.2 Task - Create renderer configuration + Configure which renderer package to use. + + [ ] 7.1.2.1 Subtask - Add `:renderer` config to application config + [ ] 7.1.2.2 Subtask - Support `:liveview`, `:html`, `:desktop` options + [ ] 7.1.2.3 Subtask - Validate selected renderer is available + [ ] 7.1.2.4 Subtask - Provide default renderer selection + + [ ] 7.1.3 Task - Implement renderer registry + Track available renderer packages. + + [ ] 7.1.3.1 Subtask - Implement `AshUI.Rendering.Registry` + [ ] 7.1.3.2 Subtask - Register available renderers at startup + [ ] 7.1.3.3 Subtask - Provide `list_renderers/0` function + [ ] 7.1.3.4 Subtask - Provide `get_renderer/1` lookup function + + [ ] 7.2 Section - LiveUI Integration + Integrate with live_ui renderer for LiveView output. + + [ ] 7.2.1 Task - Implement LiveUI renderer adapter + Create adapter for calling LiveUI renderer. + + [ ] 7.2.1.1 Subtask - Implement `AshUI.Rendering.LiveUIAdapter` + [ ] 7.2.1.2 Subtask - Accept canonical IUR and options + [ ] 7.2.1.3 Subtask - Call `LiveUI.Renderer.render/2` + [ ] 7.2.1.4 Subtask - Return HEEx template string + + [ ] 7.2.2 Task - Handle LiveUI-specific features + Support LiveUI-specific rendering features. + + [ ] 7.2.2.1 Subtask - Configure LiveView event bindings + [ ] 7.2.2.2 Subtask - Configure LiveView hooks + [ ] 7.2.2.3 Subtask - Handle LiveView assigns for reactivity + [ ] 7.2.2.4 Subtask - Support LiveView patch optimizations + + [ ] 7.3 Section - WebUI Integration + Integrate with web_ui renderer for static HTML output. + + [ ] 7.3.1 Task - Implement WebUI renderer adapter + Create adapter for calling WebUI renderer. + + [ ] 7.3.1.1 Subtask - Implement `AshUI.Rendering.WebUIAdapter` + [ ] 7.3.1.2 Subtask - Accept canonical IUR and options + [ ] 7.3.1.3 Subtask - Call `WebUI.Renderer.render/2` + [ ] 7.3.1.4 Subtask - Return static HTML string + + [ ] 7.3.2 Task - Handle WebUI-specific features + Support WebUI-specific rendering features. + + [ ] 7.3.2.1 Subtask - Configure Elm client integration + [ ] 7.3.2.2 Subtask - Configure asset references + [ ] 7.3.2.3 Subtask - Handle SEO meta tags + [ ] 7.3.2.4 Subtask - Support static site generation + + [ ] 7.4 Section - DesktopUI Integration + Integrate with desktop_ui renderer for native desktop output. + + [ ] 7.4.1 Task - Implement DesktopUI renderer adapter + Create adapter for calling DesktopUI renderer. + + [ ] 7.4.1.1 Subtask - Implement `AshUI.Rendering.DesktopUIAdapter` + [ ] 7.4.1.2 Subtask - Accept canonical IUR and options + [ ] 7.4.1.3 Subtask - Call `DesktopUI.Renderer.render/2` + [ ] 7.4.1.4 Subtask - Return native desktop UI instructions + + [ ] 7.4.2 Task - Handle DesktopUI-specific features + Support DesktopUI-specific rendering features. + + [ ] 7.4.2.1 Subtask - Configure SDL2 window properties + [ ] 7.4.2.2 Subtask - Configure native menu bar + [ ] 7.4.2.3 Subtask - Handle platform-specific features + [ ] 7.4.2.4 Subtask - Support desktop event handling + + [ ] 7.5 Section - Renderer Selection + Implement automatic renderer selection based on context. + + [ ] 7.5.1 Task - Implement runtime renderer selection + Select renderer based on request context. + + [ ] 7.5.1.1 Subtask - Detect LiveView request → use live_ui + [ ] 7.5.1.2 Subtask - Detect HTTP request → use web_ui + [ ] 7.5.1.3 Subtask - Support explicit renderer override + [ ] 7.5.1.4 Subtask - Handle unavailable renderer gracefully + + [ ] 7.5.2 Task - Implement renderer fallback + Provide fallback when selected renderer is unavailable. + + [ ] 7.5.2.1 Subtask - Fallback to alternative renderer if configured + [ ] 7.5.2.2 Subtask - Display error if no fallback available + [ ] 7.5.2.3 Subtask - Log fallback events for monitoring + [ ] 7.5.2.4 Subtask - Support per-environment renderer selection + + [ ] 7.6 Section - Phase 7 Integration Tests + Validate renderer package integration end-to-end. + + [ ] 7.6.1 Task - LiveUI integration scenarios + Verify live_ui renderer works correctly. + + [ ] 7.6.1.1 Subtask - Verify canonical IUR renders to valid HEEx + [ ] 7.6.1.2 Subtask - Verify events are wired correctly + [ ] 7.6.1.3 Subtask - Verify reactive updates work + [ ] 7.6.1.4 Subtask - Verify LiveView patches work + + [ ] 7.6.2 Task - WebUI integration scenarios + Verify web_ui renderer works correctly. + + [ ] 7.6.2.1 Subtask - Verify canonical IUR renders to valid HTML + [ ] 7.6.2.2 Subtask - Verify Elm client integration works + [ ] 7.6.2.3 Subtask - Verify static assets are referenced correctly + [ ] 7.6.2.4 Subtask - Verify SEO tags are present + + [ ] 7.6.3 Task - Renderer selection scenarios + Verify renderer selection works correctly. + + [ ] 7.6.3.1 Subtask - Verify LiveView request uses live_ui + [ ] 7.6.3.2 Subtask - Verify HTTP request uses web_ui + [ ] 7.6.3.3 Subtask - Verify explicit override is respected + [ ] 7.6.3.4 Subtask - Verify unavailable renderer shows error + + [ ] 7.6.4 Task - Cross-renderer scenarios + Verify UI works across different renderers. + + [ ] 7.6.4.1 Subtask - Verify same IUR renders on all renderers + [ ] 7.6.4.2 Subtask - Verify renderer-specific features are isolated + [ ] 7.6.4.3 Subtask - Verify fallback behavior works + [ ] 7.6.4.4 Subtask - Verify renderer switching works diff --git a/specs/planning/phase-08-governance-gates-and-release-readiness.md b/specs/planning/phase-08-governance-gates-and-release-readiness.md new file mode 100644 index 00000000..998e411d --- /dev/null +++ b/specs/planning/phase-08-governance-gates-and-release-readiness.md @@ -0,0 +1,204 @@ +# Phase 8 - Governance Gates and Release Readiness + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- CI/CD pipeline configuration +- Conformance test scenarios +- Governance validation scripts +- Telemetry and observability + +## Relevant Assumptions / Defaults +- All phases must pass before merging to main +- Conformance tests validate spec compliance +- CI enforces governance rules automatically +- Release requires all acceptance criteria to pass + +[ ] 8 Phase 8 - Governance Gates and Release Readiness + Finalize CI gates, conformance tests, and rollout readiness checks for production deployment. + + [ ] 8.1 Section - CI/CD Pipeline Setup + Implement automated governance gates in CI pipeline. + + [ ] 8.1.1 Task - Create specs validation workflow + Add GitHub Actions workflow for specs validation. + + [ ] 8.1.1.1 Subtask - Create `.github/workflows/specs-governance.yml` + [ ] 8.1.1.2 Subtask - Run `scripts/validate_specs_governance.sh` + [ ] 8.1.1.3 Subtask - Check on push to main and PRs + [ ] 8.1.1.4 Subtask - Fail build if validation fails + + [ ] 8.1.2 Task - Create RFC validation workflow + Add GitHub Actions workflow for RFC validation. + + [ ] 8.1.2.1 Subtask - Create `.github/workflows/rfc-governance.yml` + [ ] 8.1.2.2 Subtask - Run `scripts/validate_rfc_governance.sh` + [ ] 8.1.2.3 Subtask - Check RFC metadata completeness + [ ] 8.1.2.4 Subtask - Verify RFC traceability links + + [ ] 8.1.3 Task - Create guides validation workflow + Add GitHub Actions workflow for guides validation. + + [ ] 8.1.3.1 Subtask - Create `.github/workflows/guides-governance.yml` + [ ] 8.1.3.2 Subtask - Run `scripts/validate_guides_governance.sh` + [ ] 8.1.3.3 Subtask - Check guide metadata completeness + [ ] 8.1.3.4 Subtask - Verify guide diagram requirements + + [ ] 8.1.4 Task - Create conformance test workflow + Add GitHub Actions workflow for conformance testing. + + [ ] 8.1.4.1 Subtask - Create `.github/workflows/conformance.yml` + [ ] 8.1.4.2 Subtask - Run all conformance scenarios + [ ] 8.1.4.3 Subtask - Generate conformance report + [ ] 8.1.4.4 Subtask - Upload report as artifact + + [ ] 8.2 Section - Conformance Test Implementation + Implement automated conformance tests for all requirements. + + [ ] 8.2.1 Task - Implement resource contract tests + Create tests for REQ-RES-* requirements. + + [ ] 8.2.1.1 Subtask - Implement tests for REQ-RES-001 through REQ-RES-008 + [ ] 8.2.1.2 Subtask - Test resource definition and attributes + [ ] 8.2.1.3 Subtask - Test relationships and actions + [ ] 8.2.1.4 Subtask - Test authorization and validation + + [ ] 8.2.2 Task - Implement screen contract tests + Create tests for REQ-SCREEN-* requirements. + + [ ] 8.2.2.1 Subtask - Implement tests for REQ-SCREEN-001 through REQ-SCREEN-010 + [ ] 8.2.2.2 Subtask - Test screen lifecycle and state transitions + [ ] 8.2.2.3 Subtask - Test element composition and bindings + [ ] 8.2.2.4 Subtask - Test routing and session isolation + + [ ] 8.2.3 Task - Implement binding contract tests + Create tests for REQ-BIND-* requirements. + + [ ] 8.2.3.1 Subtask - Implement tests for REQ-BIND-001 through REQ-BIND-010 + [ ] 8.2.3.2 Subtask - Test binding types and source resolution + [ ] 8.2.3.3 Subtask - Test transformation and reactivity + [ ] 8.2.3.4 Subtask - Test bidirectional updates and actions + + [ ] 8.2.4 Task - Implement rendering contract tests + Create tests for REQ-RENDER-* requirements. + + [ ] 8.2.4.1 Subtask - Implement tests for REQ-RENDER-001 through REQ-RENDER-012 + [ ] 8.2.4.2 Subtask - Test canonical IUR conversion + [ ] 8.2.4.3 Subtask - Test renderer package integration + [ ] 8.2.4.4 Subtask - Test error handling and observability + + [ ] 8.3 Section - Observability and Telemetry + Implement comprehensive telemetry for monitoring. + + [ ] 8.3.1 Task - Define telemetry events + Create standard telemetry event definitions. + + [ ] 8.3.1.1 Subtask - Define `[:ash_ui, :screen, :mount]` event + [ ] 8.3.1.2 Subtask - Define `[:ash_ui, :screen, :unmount]` event + [ ] 8.3.1.3 Subtask - Define `[:ash_ui, :binding, :evaluate]` event + [ ] 8.3.1.4 Subtask - Define `[:ash_ui, :render, :complete]` event + + [ ] 8.3.2 Task - Implement telemetry handlers + Attach telemetry to all major operations. + + [ ] 8.3.2.1 Subtask - Attach telemetry to screen operations + [ ] 8.3.2.2 Subtask - Attach telemetry to binding evaluation + [ ] 8.3.2.3 Subtask - Attach telemetry to compilation + [ ] 8.3.2.4 Subtask - Attach telemetry to rendering + + [ ] 8.3.3 Task - Create dashboards + Create observability dashboards for monitoring. + + [ ] 8.3.3.1 Subtask - Create screen performance dashboard + [ ] 8.3.3.2 Subtask - Create error rate dashboard + [ ] 8.3.3.3 Subtask - Create authorization failure dashboard + [ ] 8.3.3.4 Subtask - Create renderer usage dashboard + + [ ] 8.4 Section - Documentation Completeness + Ensure all documentation is complete and up-to-date. + + [ ] 8.4.1 Task - Complete user guides + Finish all user-facing documentation. + + [ ] 8.4.1.1 Subtask - Complete UG-0001 Getting Started guide + [ ] 8.4.1.2 Subtask - Create UG-0002 Resources guide + [ ] 8.4.1.3 Subtask - Create UG-0003 Data Binding guide + [ ] 8.4.1.4 Subtask - Create UG-0004 Authorization guide + + [ ] 8.4.2 Task - Complete developer guides + Finish all developer documentation. + + [ ] 8.4.2.1 Subtask - Update DG-0001 Architecture Overview + [ ] 8.4.2.2 Subtask - Create DG-0002 Contributing guide + [ ] 8.4.2.3 Subtask - Create DG-0003 Testing guide + [ ] 8.4.2.4 Subtask - Create DG-0004 Release process guide + + [ ] 8.4.3 Task - Update README and examples + Ensure entry-level documentation is clear. + + [ ] 8.4.3.1 Subtask - Update root README with quick start + [ ] 8.4.3.2 Subtask - Create example application + [ ] 8.4.3.3 Subtask - Add code examples to guides + [ ] 8.4.3.4 Subtask - Create migration guide from v0 to v1 + + [ ] 8.5 Section - Release Checklist + Create final checklist for release readiness. + + [ ] 8.5.1 Task - Define release criteria + Establish what must pass before release. + + [ ] 8.5.1.1 Subtask - All conformance tests must pass + [ ] 8.5.1.2 Subtask - All CI workflows must pass + [ ] 8.5.1.3 Subtask - Code coverage must meet threshold + [ ] 8.5.1.4 Subtask - No critical bugs outstanding + + [ ] 8.5.2 Task - Create release process + Define the steps for cutting a release. + + [ ] 8.5.2.1 Subtask - Update version numbers + [ ] 8.5.2.2 Subtask - Generate CHANGELOG + [ ] 8.5.2.3 Subtask - Create git tag + [ ] 8.5.2.4 Subtask - Publish to Hex (if applicable) + + [ ] 8.5.3 Task - Create rollback plan + Define rollback procedures if issues arise. + + [ ] 8.5.3.1 Subtask - Define rollback criteria + [ ] 8.5.3.2 Subtask - Document rollback steps + [ ] 8.5.3.3 Subtask - Create rollback communication template + [ ] 8.5.3.4 Subtask - Test rollback procedure + + [ ] 8.6 Section - Phase 8 Integration Tests + Validate end-to-end system behavior across all phases. + + [ ] 8.6.1 Task - Full stack integration scenarios + Test complete user workflows end-to-end. + + [ ] 8.6.1.1 Subtask - Verify user can define, mount, and interact with screen + [ ] 8.6.1.2 Subtask - Verify data bindings work bidirectionally + [ ] 8.6.1.3 Subtask - Verify actions execute with authorization + [ ] 8.6.1.4 Subtask - Verify rendering works across all renderers + + [ ] 8.6.2 Task - Conformance coverage scenarios + Verify all requirements have test coverage. + + [ ] 8.6.2.1 Subtask - Verify all REQ-* have corresponding SCN-* + [ ] 8.6.2.2 Subtask - Verify traceability matrix is complete + [ ] 8.6.2.3 Subtask - Verify all SCN-* have passing tests + [ ] 8.6.2.4 Subtask - Generate conformance report + + [ ] 8.6.3 Task - Performance and resilience scenarios + Verify system meets performance and resilience targets. + + [ ] 8.6.3.1 Subtask - Verify screen mount time under 100ms + [ ] 8.6.3.2 Subtask - Verify update render time under 50ms + [ ] 8.6.3.3 Subtask - Verify system handles 100 concurrent sessions + [ ] 8.6.3.4 Subtask - Verify graceful degradation on errors + + [ ] 8.6.4 Task - Release readiness scenarios + Verify all release criteria are met. + + [ ] 8.6.4.1 Subtask - Verify CI gates all pass + [ ] 8.6.4.2 Subtask - Verify documentation is complete + [ ] 8.6.4.3 Subtask - Verify telemetry is configured + [ ] 8.6.4.4 Subtask - Verify rollback procedure works