diff --git a/.spec/planning/live_ui/README.md b/.spec/planning/live_ui/README.md index 1e106bed..9a79d70c 100644 --- a/.spec/planning/live_ui/README.md +++ b/.spec/planning/live_ui/README.md @@ -35,8 +35,11 @@ The plan aligns to: 10. [Phase 10 - Documentation, Validation, and Release Readiness for Style Realization](./phase-10-documentation-validation-and-release-readiness-for-style-realization.md): finish the rollout with migration guidance, validation gates, hardening, and release-readiness coverage for browser-realized canonical styling. 11. [Phase 11 - Widget LiveComponent Contract and Runtime Backbone Realignment](./phase-11-widget-livecomponent-contract-and-runtime-backbone-realignment.md): establish the shared widget LiveComponent contract, stable widget identity and routing model, and the runtime backbone needed to make widgets real mountable component boundaries. 12. [Phase 12 - Foundational, Input, Navigation, and Form Widget Component Migration](./phase-12-foundational-input-navigation-and-form-widget-component-migration.md): migrate the foundational widget families, forms, and navigation surfaces onto the new widget-component architecture while keeping the direct-use API ergonomic. -13. [Phase 13 - Advanced Widget Component Migration and Canonical Renderer Convergence](./phase-13-advanced-widget-component-migration-and-canonical-renderer-convergence.md): migrate advanced data, feedback, overlay, operational, and display widgets and make canonical rendering target the same widget component boundaries. -14. [Phase 14 - Tooling, Demo, Validation, and Release Readiness for Widget Components](./phase-14-tooling-demo-validation-and-release-readiness-for-widget-components.md): finish the widget-component transition with demo/example upgrades, tooling visibility, validation gates, documentation, and cleanup of legacy helper-only paths. +13. [Phase 13 - Data and Feedback Widget Component Migration](./phase-13-data-and-feedback-widget-component-migration.md): migrate structured data, document, and feedback surfaces onto the shared widget-component architecture. +14. [Phase 14 - Overlay, Operational, and Display Widget Component Migration](./phase-14-overlay-operational-and-display-widget-component-migration.md): migrate overlay, operational, and display widgets onto the widget-component model. +15. [Phase 15 - Canonical Renderer Convergence](./phase-15-canonical-renderer-convergence.md): finish the convergence work so canonical `UnifiedIUR` rendering targets the same widget component boundaries used by direct native screens. +16. [Phase 16 - Advanced Widget Integration Tests](./phase-16-advanced-widget-integration-tests.md): validate the complete widget-component architecture end to end across all widget families. +17. [Phase 17 - Tooling, Demo, Validation, and Release Readiness for Widget Components](./phase-17-tooling-demo-validation-and-release-readiness-for-widget-components.md): finish the widget-component transition with demo/example upgrades, tooling visibility, validation gates, documentation, and cleanup of legacy helper-only paths. ## Shared Conventions - Numbering: diff --git a/.spec/planning/live_ui/phase-13-advanced-widget-component-migration-and-canonical-renderer-convergence.md b/.spec/planning/live_ui/phase-13-advanced-widget-component-migration-and-canonical-renderer-convergence.md deleted file mode 100644 index 5def229d..00000000 --- a/.spec/planning/live_ui/phase-13-advanced-widget-component-migration-and-canonical-renderer-convergence.md +++ /dev/null @@ -1,101 +0,0 @@ -# Phase 13 - Advanced Widget Component Migration and Canonical Renderer Convergence - -Back to index: [README](./README.md) - -## Relevant Shared APIs / Interfaces -- `LiveUi.Widgets.List` -- `LiveUi.Widgets.Table` -- `LiveUi.Widgets.TreeView` -- `LiveUi.Widgets.MarkdownViewer` -- `LiveUi.Widgets.LogViewer` -- `LiveUi.Widgets.Status` -- `LiveUi.Widgets.Progress` -- `LiveUi.Widgets.Gauge` -- `LiveUi.Widgets.InlineFeedback` -- `LiveUi.Widgets.Sparkline` -- `LiveUi.Widgets.BarChart` -- `LiveUi.Widgets.LineChart` -- `LiveUi.Widgets.OverlaySurface` -- `LiveUi.Widgets.Dialog` -- `LiveUi.Widgets.AlertDialog` -- `LiveUi.Widgets.ContextMenu` -- `LiveUi.Widgets.Toast` -- `LiveUi.Widgets.StreamWidget` -- `LiveUi.Widgets.ProcessMonitor` -- `LiveUi.Widgets.SupervisionTreeViewer` -- `LiveUi.Widgets.ClusterDashboard` -- `LiveUi.Widgets.Viewport` -- `LiveUi.Widgets.ScrollBar` -- `LiveUi.Widgets.SplitPane` -- `LiveUi.Widgets.Canvas` -- `LiveUi.Renderer` - -## Relevant Assumptions / Defaults -- Phases 11 and 12 have established the shared widget-component contract and migrated the most common widget families. -- Advanced widget families must converge on the same widget-component architecture rather than keeping a second tier of helper-only or markup-only implementations. -- Canonical rendering must target the same advanced widget component boundaries that direct-native usage targets. -- Some advanced surfaces may remain visually minimal at first, but they still need to respect the widget-component contract and event/lifecycle boundaries. - -[ ] 13 Phase 13 - Advanced Widget Component Migration and Canonical Renderer Convergence - Migrate advanced widget families onto explicit widget component boundaries and finish the renderer convergence work so canonical `UnifiedIUR` always targets the same widget architecture as direct-native `live_ui`. - - [ ] 13.1 Section - Data and Feedback Widget Component Migration - Migrate structured data, document, and feedback surfaces onto the shared widget-component architecture. - - [ ] 13.1.1 Task - Convert data and document widgets to explicit component boundaries - Migrate collection and document surfaces so they stop relying on passive markup-only implementations. - - [ ] 13.1.1.1 Subtask - Convert `list`, `table`, `tree_view`, `markdown_viewer`, and `log_viewer` to widget component implementations with explicit lifecycle and event semantics. - [ ] 13.1.1.2 Subtask - Ensure collection-item identity, selection semantics, and canonical item attributes remain stable through mounted widget component boundaries. - [ ] 13.1.1.3 Subtask - Add tests that prove data and document widgets preserve continuity across server updates and canonical rerenders. - - [ ] 13.1.2 Task - Convert feedback and chart widgets to explicit component boundaries - Migrate feedback and chart surfaces so they share the same widget-component runtime contract even when their initial rendering remains visually simple. - - [ ] 13.1.2.1 Subtask - Convert `status`, `progress`, `gauge`, `inline_feedback`, `sparkline`, `bar_chart`, and `line_chart` to widget component implementations. - [ ] 13.1.2.2 Subtask - Ensure state variants, style realization, and canonical renderer behavior continue to work after the migration. - [ ] 13.1.2.3 Subtask - Add tests that prove feedback and chart widgets remain deterministic across direct-native and canonical paths. - - [ ] 13.2 Section - Overlay, Operational, and Display Widget Component Migration - Migrate the more stateful widget families that most benefit from explicit widget-local lifecycle boundaries. - - [ ] 13.2.1 Task - Convert overlay widget surfaces to explicit component boundaries - Migrate dialogs, overlays, and transient overlay surfaces so their bounded local lifecycle becomes explicit and testable. - - [ ] 13.2.1.1 Subtask - Convert `overlay_surface`, `dialog`, `alert_dialog`, `context_menu`, and `toast` to widget component implementations. - [ ] 13.2.1.2 Subtask - Define how open, close, focus, anchor, placement, and dismissal behavior use bounded widget-local state without violating server authority. - [ ] 13.2.1.3 Subtask - Add tests that prove overlay lifecycle behavior remains aligned across direct-native and canonical usage. - - [ ] 13.2.2 Task - Convert operational and display-system widgets to explicit component boundaries - Migrate stream, monitoring, viewport, split, scroll, and canvas surfaces onto the widget-component model. - - [ ] 13.2.2.1 Subtask - Convert `stream_widget`, `process_monitor`, `supervision_tree_viewer`, and `cluster_dashboard` to widget component implementations. - [ ] 13.2.2.2 Subtask - Convert `viewport`, `scroll_bar`, `split_pane`, and `canvas` to widget component implementations where they need lifecycle or event boundaries. - [ ] 13.2.2.3 Subtask - Add tests that prove advanced widget-local lifecycle remains bounded and renderer continuity is preserved. - - [ ] 13.3 Section - Canonical Renderer Convergence - Finish the convergence work so canonical `UnifiedIUR` rendering targets the same widget component boundaries used by direct native screens for every supported construct. - - [ ] 13.3.1 Task - Retarget canonical rendering to the migrated widget component architecture - Remove remaining renderer-only widget paths and make the canonical renderer a thin adapter onto the native widget component set. - - [ ] 13.3.1.1 Subtask - Update `LiveUi.Renderer` so every advanced canonical widget maps into the same widget component boundary used by direct-native usage. - [ ] 13.3.1.2 Subtask - Remove or isolate any remaining renderer-only markup generation paths that bypass widget component boundaries. - [ ] 13.3.1.3 Subtask - Add tests that prove equivalent native and canonical widget trees converge on the same component boundaries and event semantics. - - [ ] 13.4 Section - Phase 13 Integration Tests - Validate the advanced widget migrations and canonical renderer convergence end to end. - - [ ] 13.4.1 Task - Advanced widget family integration scenarios - Verify advanced widgets now behave as real widget components across representative direct-native and canonical flows. - - [ ] 13.4.1.1 Subtask - Verify data, feedback, overlay, operational, and display widgets preserve identity and bounded local state through mounted component boundaries. - [ ] 13.4.1.2 Subtask - Verify advanced widget event routing remains correct for collection, overlay, and viewport-style interactions. - [ ] 13.4.1.3 Subtask - Verify visually minimal advanced widgets still respect the widget-component contract even before richer rendering improvements land. - - [ ] 13.4.2 Task - Canonical renderer convergence integration scenarios - Verify canonical `UnifiedIUR` rendering now targets the same widget component architecture across the supported advanced surface. - - [ ] 13.4.2.1 Subtask - Verify equivalent direct-native and canonical advanced widgets converge on the same widget component boundaries. - [ ] 13.4.2.2 Subtask - Verify canonical event lowering and transport still work after renderer-only paths are removed or isolated. - [ ] 13.4.2.3 Subtask - Verify advanced widget continuity remains deterministic across rerenders, boundary translation, and browser-hosted demo review. diff --git a/.spec/planning/live_ui/phase-13-data-and-feedback-widget-component-migration.md b/.spec/planning/live_ui/phase-13-data-and-feedback-widget-component-migration.md new file mode 100644 index 00000000..d9f68a2f --- /dev/null +++ b/.spec/planning/live_ui/phase-13-data-and-feedback-widget-component-migration.md @@ -0,0 +1,57 @@ +# Phase 13 - Data and Feedback Widget Component Migration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `LiveUi.Widgets.List` +- `LiveUi.Widgets.Table` +- `LiveUi.Widgets.TreeView` +- `LiveUi.Widgets.MarkdownViewer` +- `LiveUi.Widgets.LogViewer` +- `LiveUi.Widgets.Status` +- `LiveUi.Widgets.Progress` +- `LiveUi.Widgets.Gauge` +- `LiveUi.Widgets.InlineFeedback` +- `LiveUi.Widgets.Sparkline` +- `LiveUi.Widgets.BarChart` +- `LiveUi.Widgets.LineChart` +- `LiveUi.Component` +- `LiveUi.Widget.Identity` + +## Relevant Assumptions / Defaults +- Phases 11 and 12 have established the shared widget-component contract and migrated foundational, input, navigation, and form widget families. +- Data and feedback widgets must converge on the same widget-component architecture. +- Some advanced surfaces may remain visually minimal at first, but they still need to respect the widget-component contract and event/lifecycle boundaries. + +[ ] 13 Phase 13 - Data and Feedback Widget Component Migration + Migrate structured data, document, and feedback surfaces onto the shared widget-component architecture. + + [ ] 13.1 Section - Data and Document Widget Component Migration + Migrate collection and document surfaces so they stop relying on passive markup-only implementations. + + [ ] 13.1.1 Task - Convert data and document widgets to explicit component boundaries + Migrate collection and document widgets to widget component implementations with explicit lifecycle and event semantics. + + [ ] 13.1.1.1 Subtask - Convert `list`, `table`, `tree_view`, `markdown_viewer`, and `log_viewer` to widget component implementations. + [ ] 13.1.1.2 Subtask - Ensure collection-item identity, selection semantics, and canonical item attributes remain stable through mounted widget component boundaries. + [ ] 13.1.1.3 Subtask - Add tests that prove data and document widgets preserve continuity across server updates and canonical rerenders. + + [ ] 13.2 Section - Feedback and Chart Widget Component Migration + Migrate feedback and chart surfaces so they share the same widget-component runtime contract. + + [ ] 13.2.1 Task - Convert feedback and chart widgets to explicit component boundaries + Migrate feedback and chart surfaces to widget component implementations. + + [ ] 13.2.1.1 Subtask - Convert `status`, `progress`, `gauge`, `inline_feedback`, `sparkline`, `bar_chart`, and `line_chart` to widget component implementations. + [ ] 13.2.1.2 Subtask - Ensure state variants, style realization, and canonical renderer behavior continue to work after the migration. + [ ] 13.2.1.3 Subtask - Add tests that prove feedback and chart widgets remain deterministic across direct-native and canonical paths. + + [ ] 13.3 Section - Phase 13 Integration Tests + Validate the data and feedback widget migrations end to end. + + [ ] 13.3.1 Task - Data and feedback widget integration scenarios + Verify data and feedback widgets now behave as real widget components across representative direct-native and canonical flows. + + [ ] 13.3.1.1 Subtask - Verify data, document, feedback, and chart widgets preserve identity and bounded local state through mounted component boundaries. + [ ] 13.3.1.2 Subtask - Verify collection widget event routing remains correct for selection, pagination, and item interactions. + [ ] 13.3.1.3 Subtask - Verify visually minimal widgets still respect the widget-component contract even before richer rendering improvements land. diff --git a/.spec/planning/live_ui/phase-14-overlay-operational-and-display-widget-component-migration.md b/.spec/planning/live_ui/phase-14-overlay-operational-and-display-widget-component-migration.md new file mode 100644 index 00000000..03146106 --- /dev/null +++ b/.spec/planning/live_ui/phase-14-overlay-operational-and-display-widget-component-migration.md @@ -0,0 +1,68 @@ +# Phase 14 - Overlay, Operational, and Display Widget Component Migration + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `LiveUi.Widgets.OverlaySurface` +- `LiveUi.Widgets.Dialog` +- `LiveUi.Widgets.AlertDialog` +- `LiveUi.Widgets.ContextMenu` +- `LiveUi.Widgets.Toast` +- `LiveUi.Widgets.StreamWidget` +- `LiveUi.Widgets.ProcessMonitor` +- `LiveUi.Widgets.SupervisionTreeViewer` +- `LiveUi.Widgets.ClusterDashboard` +- `LiveUi.Widgets.Viewport` +- `LiveUi.Widgets.ScrollBar` +- `LiveUi.Widgets.SplitPane` +- `LiveUi.Widgets.Canvas` +- `LiveUi.Component` +- `LiveUi.Widget.Identity` + +## Relevant Assumptions / Defaults +- Phases 11, 12, and 13 have established the widget-component contract across foundational, input, navigation, form, data, and feedback widget families. +- Overlay and operational widgets are more stateful and benefit significantly from explicit widget-local lifecycle boundaries. +- Display system widgets need explicit event boundaries for viewport, scroll, split, and canvas interactions. + +[ ] 14 Phase 14 - Overlay, Operational, and Display Widget Component Migration + Migrate the more stateful widget families that most benefit from explicit widget-local lifecycle boundaries. + + [ ] 14.1 Section - Overlay Widget Component Migration + Migrate dialogs, overlays, and transient overlay surfaces so their bounded local lifecycle becomes explicit and testable. + + [ ] 14.1.1 Task - Convert overlay widget surfaces to explicit component boundaries + Migrate overlay widgets to widget component implementations. + + [ ] 14.1.1.1 Subtask - Convert `overlay_surface`, `dialog`, `alert_dialog`, `context_menu`, and `toast` to widget component implementations. + [ ] 14.1.1.2 Subtask - Define how open, close, focus, anchor, placement, and dismissal behavior use bounded widget-local state without violating server authority. + [ ] 14.1.1.3 Subtask - Add tests that prove overlay lifecycle behavior remains aligned across direct-native and canonical usage. + + [ ] 14.2 Section - Operational Widget Component Migration + Migrate stream, monitoring, and dashboard widgets onto the widget-component model. + + [ ] 14.2.1 Task - Convert operational widgets to explicit component boundaries + Migrate operational widgets to widget component implementations. + + [ ] 14.2.1.1 Subtask - Convert `stream_widget`, `process_monitor`, `supervision_tree_viewer`, and `cluster_dashboard` to widget component implementations. + [ ] 14.2.1.2 Subtask - Ensure streaming, monitoring, and dashboard state management works through bounded widget-local state. + [ ] 14.2.1.3 Subtask - Add tests that prove operational widgets preserve real-time updates and bounded local state. + + [ ] 14.3 Section - Display System Widget Component Migration + Migrate viewport, scroll, split, and canvas widgets onto the widget-component model. + + [ ] 14.3.1 Task - Convert display system widgets to explicit component boundaries + Migrate display system widgets to widget component implementations. + + [ ] 14.3.1.1 Subtask - Convert `viewport`, `scroll_bar`, `split_pane`, and `canvas` to widget component implementations where they need lifecycle or event boundaries. + [ ] 14.3.1.2 Subtask - Ensure viewport, scroll, split, and canvas interactions use proper event routing through widget boundaries. + [ ] 14.3.1.3 Subtask - Add tests that prove display system widgets preserve interaction semantics through component boundaries. + + [ ] 14.4 Section - Phase 14 Integration Tests + Validate the overlay, operational, and display widget migrations end to end. + + [ ] 14.4.1 Task - Overlay and operational widget integration scenarios + Verify overlay and operational widgets now behave as real widget components. + + [ ] 14.4.1.1 Subtask - Verify overlay widgets preserve lifecycle, focus, and dismissal behavior through mounted component boundaries. + [ ] 14.4.1.2 Subtask - Verify operational widgets preserve real-time updates and bounded local state. + [ ] 14.4.1.3 Subtask - Verify display system widgets preserve interaction semantics through component boundaries. diff --git a/.spec/planning/live_ui/phase-15-canonical-renderer-convergence.md b/.spec/planning/live_ui/phase-15-canonical-renderer-convergence.md new file mode 100644 index 00000000..c5d39ea1 --- /dev/null +++ b/.spec/planning/live_ui/phase-15-canonical-renderer-convergence.md @@ -0,0 +1,48 @@ +# Phase 15 - Canonical Renderer Convergence + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- `LiveUi.Renderer` +- `LiveUi.Component` +- `LiveUi.Widget.Identity` +- `UnifiedIUR.Element` +- `UnifiedIUR.Layout` + +## Relevant Assumptions / Defaults +- Phases 11-14 have migrated all widget families to the widget-component architecture. +- The canonical renderer must target the same widget component boundaries used by direct-native usage. +- Remaining renderer-only markup generation paths must be removed or isolated. + +[ ] 15 Phase 15 - Canonical Renderer Convergence + Finish the convergence work so canonical `UnifiedIUR` rendering targets the same widget component boundaries used by direct native screens for every supported construct. + + [ ] 15.1 Section - Retarget Canonical Rendering to Widget Components + Remove remaining renderer-only widget paths and make the canonical renderer a thin adapter onto the native widget component set. + + [ ] 15.1.1 Task - Update canonical renderer to use migrated widget components + Make the canonical renderer target widget component boundaries for all constructs. + + [ ] 15.1.1.1 Subtask - Update `LiveUi.Renderer` so every canonical widget maps into the same widget component boundary used by direct-native usage. + [ ] 15.1.1.2 Subtask - Remove or isolate any remaining renderer-only markup generation paths that bypass widget component boundaries. + [ ] 15.1.1.3 Subtask - Add tests that prove equivalent native and canonical widget trees converge on the same component boundaries and event semantics. + + [ ] 15.2 Section - Canonical Event Transport Alignment + Ensure canonical event lowering and transport work through widget component boundaries. + + [ ] 15.2.1 Task - Align event handling for canonical rendering + Make canonical events route through widget component boundaries correctly. + + [ ] 15.2.1.1 Subtask - Verify canonical event lowering and transport still work after renderer-only paths are removed or isolated. + [ ] 15.2.1.2 Subtask - Ensure event routing preserves widget identity and bounded local state across canonical/native boundary. + [ ] 15.2.1.3 Subtask - Add tests that prove canonical events route correctly through widget component boundaries. + + [ ] 15.3 Section - Phase 15 Integration Tests + Validate canonical renderer convergence end to end. + + [ ] 15.3.1 Task - Canonical renderer convergence integration scenarios + Verify canonical `UnifiedIUR` rendering targets the same widget component architecture. + + [ ] 15.3.1.1 Subtask - Verify equivalent direct-native and canonical widgets converge on the same widget component boundaries. + [ ] 15.3.1.2 Subtask - Verify canonical event lowering and transport work through widget component boundaries. + [ ] 15.3.1.3 Subtask - Verify widget continuity remains deterministic across rerenders and boundary translation. diff --git a/.spec/planning/live_ui/phase-16-advanced-widget-integration-tests.md b/.spec/planning/live_ui/phase-16-advanced-widget-integration-tests.md new file mode 100644 index 00000000..5af25856 --- /dev/null +++ b/.spec/planning/live_ui/phase-16-advanced-widget-integration-tests.md @@ -0,0 +1,54 @@ +# Phase 16 - Advanced Widget Integration Tests + +Back to index: [README](./README.md) + +## Relevant Shared APIs / Interfaces +- All migrated widget components from Phases 11-15 +- `LiveUi.Runtime` +- `LiveUi.Component` +- `LiveUi.Widget.Identity` + +## Relevant Assumptions / Defaults +- Phases 11-15 have migrated all widget families to the widget-component architecture. +- The canonical renderer converges on the same widget component boundaries as direct-native usage. +- Comprehensive integration tests are needed to validate the complete widget-component architecture. + +[ ] 16 Phase 16 - Advanced Widget Integration Tests + Validate the complete widget-component architecture end to end across all widget families. + + [ ] 16.1 Section - Advanced Widget Family Integration Scenarios + Verify all advanced widgets behave as real widget components across representative direct-native and canonical flows. + + [ ] 16.1.1 Task - Data and feedback widget integration scenarios + Verify data, document, feedback, and chart widgets work correctly through widget component boundaries. + + [ ] 16.1.1.1 Subtask - Verify data and document widgets preserve identity and bounded local state through mounted component boundaries. + [ ] 16.1.1.2 Subtask - Verify collection widget event routing remains correct for selection, pagination, and item interactions. + [ ] 16.1.1.3 Subtask - Verify visually minimal widgets still respect the widget-component contract. + + [ ] 16.1.2 Task - Overlay and operational widget integration scenarios + Verify overlay, operational, and display widgets work correctly through widget component boundaries. + + [ ] 16.1.2.1 Subtask - Verify overlay widgets preserve lifecycle, focus, and dismissal behavior through mounted component boundaries. + [ ] 16.1.2.2 Subtask - Verify operational widgets preserve real-time updates and bounded local state. + [ ] 16.1.2.3 Subtask - Verify display system widgets preserve interaction semantics through component boundaries. + + [ ] 16.2 Section - Cross-Family Widget Composition Scenarios + Verify widgets from different families compose correctly through widget component boundaries. + + [ ] 16.2.1 Task - Multi-family widget composition tests + Verify complex screens with widgets from multiple families work correctly. + + [ ] 16.2.1.1 Subtask - Create realistic screen scenarios combining foundational, input, navigation, data, feedback, overlay, and operational widgets. + [ ] 16.2.1.2 Subtask - Verify event routing, state management, and widget identity preservation across complex compositions. + [ ] 16.2.1.3 Subtask - Verify canonical rendering of complex screens converges on the same widget component boundaries. + + [ ] 16.3 Section - Native/Canonical Parity Scenarios + Verify native and canonical paths converge on the same widget component architecture. + + [ ] 16.3.1 Task - Native/canonical parity integration scenarios + Verify native and canonical rendering paths produce equivalent widget component boundaries. + + [ ] 16.3.1.1 Subtask - Verify equivalent direct-native and canonical widgets converge on the same widget component boundaries. + [ ] 16.3.1.2 Subtask - Verify canonical event lowering and transport work through widget component boundaries. + [ ] 16.3.1.3 Subtask - Verify widget continuity remains deterministic across rerenders and boundary translation. diff --git a/.spec/planning/live_ui/phase-14-tooling-demo-validation-and-release-readiness-for-widget-components.md b/.spec/planning/live_ui/phase-17-tooling-demo-validation-and-release-readiness-for-widget-components.md similarity index 66% rename from .spec/planning/live_ui/phase-14-tooling-demo-validation-and-release-readiness-for-widget-components.md rename to .spec/planning/live_ui/phase-17-tooling-demo-validation-and-release-readiness-for-widget-components.md index 5817e771..53503fce 100644 --- a/.spec/planning/live_ui/phase-14-tooling-demo-validation-and-release-readiness-for-widget-components.md +++ b/.spec/planning/live_ui/phase-17-tooling-demo-validation-and-release-readiness-for-widget-components.md @@ -1,4 +1,4 @@ -# Phase 14 - Tooling, Demo, Validation, and Release Readiness for Widget Components +# Phase 17 - Tooling, Demo, Validation, and Release Readiness for Widget Components Back to index: [README](./README.md) @@ -21,73 +21,73 @@ Back to index: [README](./README.md) - The browser-hosted demo and maintained examples should become proof that widgets are real component boundaries rather than passive HTML surfaces. - Release readiness requires removing or clearly isolating helper-only legacy paths that no longer match the new specs. -[ ] 14 Phase 14 - Tooling, Demo, Validation, and Release Readiness for Widget Components +[ ] 17 Phase 17 - Tooling, Demo, Validation, and Release Readiness for Widget Components Finish the widget-component transition by making the new architecture visible in tooling and demos, tightening validation and docs around the new contract, and cleaning up legacy implementation paths that no longer match the package specs. - [ ] 14.1 Section - Tooling and Inspection for Widget Components + [ ] 17.1 Section - Tooling and Inspection for Widget Components Upgrade package tooling so maintainers can inspect widget component boundaries, identity, local state, and renderer convergence directly. - [ ] 14.1.1 Task - Expose widget-component boundaries in inspection and preview tooling + [ ] 17.1.1 Task - Expose widget-component boundaries in inspection and preview tooling Make widget-component architecture visible instead of leaving it implicit in rendered HTML. - [ ] 14.1.1.1 Subtask - Extend inspection and preview tooling to show widget component identity, family, lifecycle boundary, and relevant local-state diagnostics. - [ ] 14.1.1.2 Subtask - Add renderer comparison output that shows whether native and canonical flows target the same widget component boundaries. - [ ] 14.1.1.3 Subtask - Add tests that prove tooling output remains readable while exposing the richer widget-component architecture. + [ ] 17.1.1.1 Subtask - Extend inspection and preview tooling to show widget component identity, family, lifecycle boundary, and relevant local-state diagnostics. + [ ] 17.1.1.2 Subtask - Add renderer comparison output that shows whether native and canonical flows target the same widget component boundaries. + [ ] 17.1.1.3 Subtask - Add tests that prove tooling output remains readable while exposing the richer widget-component architecture. - [ ] 14.1.2 Task - Add migration and misuse diagnostics + [ ] 17.1.2 Task - Add migration and misuse diagnostics Help maintainers spot paths that still bypass the intended widget-component contract. - [ ] 14.1.2.1 Subtask - Add diagnostics that flag renderer-only, helper-only, or ad hoc HTML paths that bypass widget component boundaries. - [ ] 14.1.2.2 Subtask - Add package-facing summaries that distinguish true widget-component coverage from compatibility wrappers. - [ ] 14.1.2.3 Subtask - Add tests that prove misuse diagnostics fail clearly when new code bypasses the widget-component architecture. + [ ] 17.1.2.1 Subtask - Add diagnostics that flag renderer-only, helper-only, or ad hoc HTML paths that bypass widget component boundaries. + [ ] 17.1.2.2 Subtask - Add package-facing summaries that distinguish true widget-component coverage from compatibility wrappers. + [ ] 17.1.2.3 Subtask - Add tests that prove misuse diagnostics fail clearly when new code bypasses the widget-component architecture. - [ ] 14.2 Section - Demo and Maintained Example Realignment + [ ] 17.2 Section - Demo and Maintained Example Realignment Make the maintained demo and example catalog prove the widget-component architecture directly. - [ ] 14.2.1 Task - Upgrade the maintained demo to showcase mounted widget components + [ ] 17.2.1 Task - Upgrade the maintained demo to showcase mounted widget components Ensure the browser-hosted `live_ui` demo visibly exercises real widget component boundaries and not just browser-rendered markup. - [ ] 14.2.1.1 Subtask - Update the demo workbench so representative widget examples demonstrate mounted widget behavior, bounded local state, and canonical/native convergence. - [ ] 14.2.1.2 Subtask - Add demo-facing diagnostics or review affordances that show widget identity and event routing without overwhelming the UI. - [ ] 14.2.1.3 Subtask - Add regression tests that prove the demo is no longer relying on helper-only widget paths for representative examples. + [ ] 17.2.1.1 Subtask - Update the demo workbench so representative widget examples demonstrate mounted widget behavior, bounded local state, and canonical/native convergence. + [ ] 17.2.1.2 Subtask - Add demo-facing diagnostics or review affordances that show widget identity and event routing without overwhelming the UI. + [ ] 17.2.1.3 Subtask - Add regression tests that prove the demo is no longer relying on helper-only widget paths for representative examples. - [ ] 14.2.2 Task - Realign maintained examples with the new widget-component contract + [ ] 17.2.2 Task - Realign maintained examples with the new widget-component contract Ensure the package’s native, canonical, and mixed examples all reflect the new intended architecture. - [ ] 14.2.2.1 Subtask - Update maintained examples so representative native and canonical flows use the same widget component boundaries. - [ ] 14.2.2.2 Subtask - Add paired comparison scenarios that verify component identity and event-routing continuity across native and canonical paths. - [ ] 14.2.2.3 Subtask - Add tests that catch regressions when maintained examples drift back toward helper-only or renderer-only widget paths. + [ ] 17.2.2.1 Subtask - Update maintained examples so representative native and canonical flows use the same widget component boundaries. + [ ] 17.2.2.2 Subtask - Add paired comparison scenarios that verify component identity and event-routing continuity across native and canonical paths. + [ ] 17.2.2.3 Subtask - Add tests that catch regressions when maintained examples drift back toward helper-only or renderer-only widget paths. - [ ] 14.3 Section - Documentation, Validation, and Cleanup + [ ] 17.3 Section - Documentation, Validation, and Cleanup Make the new architecture the official package story and remove or isolate implementation leftovers that contradict it. - [ ] 14.3.1 Task - Update documentation and validation around the widget-component contract + [ ] 17.3.1 Task - Update documentation and validation around the widget-component contract Bring the package docs and validation gates into line with the new specs and ADR. - [ ] 14.3.1.1 Subtask - Update package guides, README content, and maintainer workflows to describe widgets as real mountable component boundaries inside the shared runtime. - [ ] 14.3.1.2 Subtask - Extend `mix live_ui.validate` and related checks so they fail when widgets bypass the intended component architecture. - [ ] 14.3.1.3 Subtask - Add release-readiness checks that verify native and canonical paths still converge on the same widget boundaries. + [ ] 17.3.1.1 Subtask - Update package guides, README content, and maintainer workflows to describe widgets as real mountable component boundaries inside the shared runtime. + [ ] 17.3.1.2 Subtask - Extend `mix live_ui.validate` and related checks so they fail when widgets bypass the intended component architecture. + [ ] 17.3.1.3 Subtask - Add release-readiness checks that verify native and canonical paths still converge on the same widget boundaries. - [ ] 14.3.2 Task - Clean up or isolate legacy helper-only paths + [ ] 17.3.2 Task - Clean up or isolate legacy helper-only paths Finish the transition by removing or clearly isolating paths that no longer reflect the intended widget architecture. - [ ] 14.3.2.1 Subtask - Remove redundant helper-only rendering paths that duplicate widget component behavior without adding real compatibility value. - [ ] 14.3.2.2 Subtask - Isolate any remaining compatibility wrappers behind clear boundaries and maintainer-facing documentation. - [ ] 14.3.2.3 Subtask - Add tests that prove cleanup work does not regress canonical renderer coverage, browser styling, or event transport. + [ ] 17.3.2.1 Subtask - Remove redundant helper-only rendering paths that duplicate widget component behavior without adding real compatibility value. + [ ] 17.3.2.2 Subtask - Isolate any remaining compatibility wrappers behind clear boundaries and maintainer-facing documentation. + [ ] 17.3.2.3 Subtask - Add tests that prove cleanup work does not regress canonical renderer coverage, browser styling, or event transport. - [ ] 14.4 Section - Phase 14 Integration Tests + [ ] 17.4 Section - Phase 17 Integration Tests Validate tooling, demos, validation gates, and release-readiness behavior for the widget-component architecture end to end. - [ ] 14.4.1 Task - Tooling and demo integration scenarios + [ ] 17.4.1 Task - Tooling and demo integration scenarios Verify maintainers can inspect, review, and demonstrate the widget-component architecture through the package’s supported workflows. - [ ] 14.4.1.1 Subtask - Verify tooling surfaces show widget component identity, bounded local state, and native/canonical convergence clearly. - [ ] 14.4.1.2 Subtask - Verify the maintained demo and examples prove mounted widget behavior rather than passive HTML-only rendering. - [ ] 14.4.1.3 Subtask - Verify misuse diagnostics catch new paths that bypass widget component boundaries. + [ ] 17.4.1.1 Subtask - Verify tooling surfaces show widget component identity, bounded local state, and native/canonical convergence clearly. + [ ] 17.4.1.2 Subtask - Verify the maintained demo and examples prove mounted widget behavior rather than passive HTML-only rendering. + [ ] 17.4.1.3 Subtask - Verify misuse diagnostics catch new paths that bypass widget component boundaries. - [ ] 14.4.2 Task - Release-readiness integration scenarios + [ ] 17.4.2 Task - Release-readiness integration scenarios Verify the package is ready to treat the widget-component architecture as the supported `live_ui` contract. - [ ] 14.4.2.1 Subtask - Verify validation gates fail when native or canonical flows stop converging on the same widget component boundaries. - [ ] 14.4.2.2 Subtask - Verify documentation, maintainer workflows, and validation tooling all tell the same architectural story. - [ ] 14.4.2.3 Subtask - Verify compatibility wrappers and cleanup boundaries remain explicit and do not silently reintroduce helper-only widget implementations. + [ ] 17.4.2.1 Subtask - Verify validation gates fail when native or canonical flows stop converging on the same widget component boundaries. + [ ] 17.4.2.2 Subtask - Verify documentation, maintainer workflows, and validation tooling all tell the same architectural story. + [ ] 17.4.2.3 Subtask - Verify compatibility wrappers and cleanup boundaries remain explicit and do not silently reintroduce helper-only widget implementations. diff --git a/packages/live_ui/test/live_ui/data_widgets_test.exs b/packages/live_ui/test/live_ui/data_widgets_test.exs new file mode 100644 index 00000000..b91d6316 --- /dev/null +++ b/packages/live_ui/test/live_ui/data_widgets_test.exs @@ -0,0 +1,368 @@ +defmodule LiveUi.DataWidgetsTest do + use ExUnit.Case, async: true + + import Phoenix.LiveViewTest + + alias LiveUi.Component + alias LiveUi.Widget.Identity + + @moduledoc """ + Regression tests for data and document widgets to verify they preserve + identity, styling, slots, and event semantics through the widget + component architecture. + """ + + describe "list widget" do + test "has mountable component boundary" do + metadata = Component.metadata(LiveUi.Widgets.List) + + assert metadata.mountable? + assert metadata.component_module == LiveUi.Widgets.List.Component + assert metadata.family == :data + assert metadata.name == :list + end + + test "list component renders with widget boundary attributes" do + html = + render_component(&LiveUi.Widgets.List.component/1, %{ + id: "test-list", + items: [ + %{id: "item-1", label: "Item 1"}, + %{id: "item-2", label: "Item 2"} + ] + }) + + assert html =~ ~s(data-live-ui-widget-boundary="list") + assert html =~ "Item 1" + assert html =~ "Item 2" + end + + test "list component supports ordered mode" do + html = + render_component(&LiveUi.Widgets.List.component/1, %{ + id: "ordered-list", + items: [ + %{id: "item-1", label: "First"}, + %{id: "item-2", label: "Second"} + ], + ordered: true + }) + + assert html =~ ~s(data-live-ui-widget-boundary="list") + assert html =~ "