Skip to content

Implement canonical navigation modal stack phases #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pcharbon70 merged 13 commits into from
May 14, 2026
Merged

Implement canonical navigation modal stack phases #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a033a48
Implement canonical navigation action vocabulary
pcharbon70 May 14, 2026
7d8747c
Expose canonical navigation diagnostics
pcharbon70 May 14, 2026
0dc8e6b
Add canonical navigation authoring examples
pcharbon70 May 14, 2026
d458aa3
Cover canonical navigation integration paths
pcharbon70 May 14, 2026
9a7a3d5
Cover compiler navigation lowering
pcharbon70 May 14, 2026
5d6e8b2
Extend IUR navigation modal stack fixtures
pcharbon70 May 14, 2026
d7b1579
Align navigation transport modal stack semantics
pcharbon70 May 14, 2026
7ec53c1
Cover canonical navigation compiler transport integration
pcharbon70 May 14, 2026
5872963
Refine shared modal stack boundary summaries
pcharbon70 May 14, 2026
df63b20
Align web runtime modal stack navigation
pcharbon70 May 14, 2026
ab31e9b
Align desktop and terminal modal stack navigation
pcharbon70 May 14, 2026
e77aef1
Add modal stack navigation review examples
pcharbon70 May 14, 2026
cc4e7e6
Cover runtime modal stack integration gates
pcharbon70 May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 43 additions & 43 deletions ...tion/phase-01-unified-ui-authored-navigation-surface-and-descriptor-backbone.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,93 +22,93 @@ Back to index: [README](./README.md)
- In-screen destination changes may remain authored as local navigation intent
without being treated as host-style route changes.

[ ] 1 Phase 1 - UnifiedUi Authored Navigation Surface and Descriptor Backbone
[x] 1 Phase 1 - UnifiedUi Authored Navigation Surface and Descriptor Backbone
Implement the authored screen-transition model inside `unified_ui` so
developers can declare cross-runtime navigation intent without leaking host
routing syntax into the DSL.

[ ] 1.1 Section - Authored Navigation Action Vocabulary
[x] 1.1 Section - Authored Navigation Action Vocabulary
Implement the canonical navigation vocabulary and target-intent shape that
developers use when declaring top-level screen transitions.

[ ] 1.1.1 Task - Define the canonical authored transition fields
[x] 1.1.1 Task - Define the canonical authored transition fields
Establish the authored descriptor fields and allowed action set for
top-level screen-transition intent.

[ ] 1.1.1.1 Subtask - Define how `action`, `screen`, `params`, `metadata`, and modal-oriented target fields appear in authored `target_intent` values.
[ ] 1.1.1.2 Subtask - Define which actions require a symbolic `screen` target and which actions, such as `go_back` or `close_modal`, are targetless.
[ ] 1.1.1.3 Subtask - Define how modal transitions and replacement transitions are distinguished from ordinary history-push transitions.
[ ] 1.1.1.4 Subtask - Define modal stack authoring rules for `open_modal` push behavior, targetless top-modal `close_modal`, optional named modal close, and the absence of required structural modal containment.
[x] 1.1.1.1 Subtask - Define how `action`, `screen`, `params`, `metadata`, and modal-oriented target fields appear in authored `target_intent` values.
[x] 1.1.1.2 Subtask - Define which actions require a symbolic `screen` target and which actions, such as `go_back` or `close_modal`, are targetless.
[x] 1.1.1.3 Subtask - Define how modal transitions and replacement transitions are distinguished from ordinary history-push transitions.
[x] 1.1.1.4 Subtask - Define modal stack authoring rules for `open_modal` push behavior, targetless top-modal `close_modal`, optional named modal close, and the absence of required structural modal containment.

[ ] 1.1.2 Task - Distinguish screen transitions from in-screen navigation
[x] 1.1.2 Task - Distinguish screen transitions from in-screen navigation
Keep local destination changes available without conflating them with
cross-screen transition semantics.

[ ] 1.1.2.1 Subtask - Define the authored distinction between in-screen destination updates, such as tab or section changes, and top-level screen transitions.
[ ] 1.1.2.2 Subtask - Ensure canonical navigation examples demonstrate both local destination changes and top-level screen transitions without blurring their semantics.
[ ] 1.1.2.3 Subtask - Define how existing generic interaction descriptors continue to work when no top-level screen transition is intended.
[x] 1.1.2.1 Subtask - Define the authored distinction between in-screen destination updates, such as tab or section changes, and top-level screen transitions.
[x] 1.1.2.2 Subtask - Ensure canonical navigation examples demonstrate both local destination changes and top-level screen transitions without blurring their semantics.
[x] 1.1.2.3 Subtask - Define how existing generic interaction descriptors continue to work when no top-level screen transition is intended.

[ ] 1.2 Section - Validation, Diagnostics, and Introspection
[x] 1.2 Section - Validation, Diagnostics, and Introspection
Implement the validation and inspection surfaces that keep the authored
navigation contract explicit, deterministic, and reviewable.

[ ] 1.2.1 Task - Validate authored screen-transition intent
[x] 1.2.1 Task - Validate authored screen-transition intent
Reject malformed or host-specific navigation declarations at authoring
time.

[ ] 1.2.1.1 Subtask - Reject URLs, Phoenix route helpers, browser-history instructions, and runtime-module identifiers in canonical screen-transition declarations.
[ ] 1.2.1.2 Subtask - Reject malformed action names, missing required screen targets, and invalid modal-target combinations.
[ ] 1.2.1.3 Subtask - Emit actionable diagnostics that explain whether the author attempted a top-level screen transition, a local destination change, or an unsupported host-specific route declaration.
[ ] 1.2.1.4 Subtask - Validate modal stack descriptors so targetless `close_modal` is accepted as top-modal close, targeted `close_modal` remains symbolic, and stack behavior never requires runtime-local stack identifiers.
[x] 1.2.1.1 Subtask - Reject URLs, Phoenix route helpers, browser-history instructions, and runtime-module identifiers in canonical screen-transition declarations.
[x] 1.2.1.2 Subtask - Reject malformed action names, missing required screen targets, and invalid modal-target combinations.
[x] 1.2.1.3 Subtask - Emit actionable diagnostics that explain whether the author attempted a top-level screen transition, a local destination change, or an unsupported host-specific route declaration.
[x] 1.2.1.4 Subtask - Validate modal stack descriptors so targetless `close_modal` is accepted as top-modal close, targeted `close_modal` remains symbolic, and stack behavior never requires runtime-local stack identifiers.

[ ] 1.2.2 Task - Expose navigation inspection helpers
[x] 1.2.2 Task - Expose navigation inspection helpers
Make authored navigation intent visible through package tooling before a
runtime is involved.

[ ] 1.2.2.1 Subtask - Update inspection helpers to show canonical navigation actions, symbolic screen targets, params, and modal-oriented targets.
[ ] 1.2.2.2 Subtask - Expose helper surfaces that list the supported navigation actions and their required authored fields.
[ ] 1.2.2.3 Subtask - Ensure navigation descriptors remain deterministic in inspection and export output so diffs stay stable and review-friendly.
[x] 1.2.2.1 Subtask - Update inspection helpers to show canonical navigation actions, symbolic screen targets, params, and modal-oriented targets.
[x] 1.2.2.2 Subtask - Expose helper surfaces that list the supported navigation actions and their required authored fields.
[x] 1.2.2.3 Subtask - Ensure navigation descriptors remain deterministic in inspection and export output so diffs stay stable and review-friendly.

[ ] 1.3 Section - Author-Facing Examples and Guidance
[x] 1.3 Section - Author-Facing Examples and Guidance
Implement maintained examples and guidance that teach developers how to use
the new authored navigation contract correctly.

[ ] 1.3.1 Task - Add maintained navigation authoring examples
[x] 1.3.1 Task - Add maintained navigation authoring examples
Provide canonical examples that demonstrate the supported authored
navigation patterns.

[ ] 1.3.1.1 Subtask - Add an example that shows an in-screen destination change, such as a tab switch, without using screen-transition fields.
[ ] 1.3.1.2 Subtask - Add an example that shows a top-level screen transition using a symbolic screen id and params.
[ ] 1.3.1.3 Subtask - Add an example that shows modal open and close transitions as canonical navigation actions.
[ ] 1.3.1.4 Subtask - Add an authored stacked-modal example that opens a second modal from an existing modal and closes the topmost modal without declaring nested modal containment.
[x] 1.3.1.1 Subtask - Add an example that shows an in-screen destination change, such as a tab switch, without using screen-transition fields.
[x] 1.3.1.2 Subtask - Add an example that shows a top-level screen transition using a symbolic screen id and params.
[x] 1.3.1.3 Subtask - Add an example that shows modal open and close transitions as canonical navigation actions.
[x] 1.3.1.4 Subtask - Add an authored stacked-modal example that opens a second modal from an existing modal and closes the topmost modal without declaring nested modal containment.

[ ] 1.3.2 Task - Update foundational navigation guidance
[x] 1.3.2 Task - Update foundational navigation guidance
Document the authored mental model so developers understand what the DSL
owns and what runtimes still own.

[ ] 1.3.2.1 Subtask - Explain that `UnifiedUi` owns screen-transition intent rather than router tables or URL semantics.
[ ] 1.3.2.2 Subtask - Explain the difference between `screen` targets, local destinations, and host-runtime route resolution.
[ ] 1.3.2.3 Subtask - Explain how authored canonical navigation remains portable across web, desktop, and terminal runtimes.
[ ] 1.3.2.4 Subtask - Explain that stacked modal flows are ordered modal transitions and that focus trapping, backdrop treatment, and terminal degradation remain runtime concerns.
[x] 1.3.2.1 Subtask - Explain that `UnifiedUi` owns screen-transition intent rather than router tables or URL semantics.
[x] 1.3.2.2 Subtask - Explain the difference between `screen` targets, local destinations, and host-runtime route resolution.
[x] 1.3.2.3 Subtask - Explain how authored canonical navigation remains portable across web, desktop, and terminal runtimes.
[x] 1.3.2.4 Subtask - Explain that stacked modal flows are ordered modal transitions and that focus trapping, backdrop treatment, and terminal degradation remain runtime concerns.

[ ] 1.4 Section - Phase 1 Integration Tests
[x] 1.4 Section - Phase 1 Integration Tests
Validate the authored navigation surface, diagnostics, and inspection
output end to end inside `unified_ui`.

[ ] 1.4.1 Task - Authored descriptor and validation scenarios
[x] 1.4.1 Task - Authored descriptor and validation scenarios
Verify `unified_ui` accepts valid canonical transitions and rejects
host-specific navigation leakage deterministically.

[ ] 1.4.1.1 Subtask - Verify authored `navigate_to`, `replace_with`, `go_back`, `go_forward`, `open_modal`, and `close_modal` descriptors validate successfully with the expected field requirements.
[ ] 1.4.1.2 Subtask - Verify screen-transition descriptors reject URLs, route helpers, browser-history directives, and runtime-module identifiers.
[ ] 1.4.1.3 Subtask - Verify invalid action and target combinations fail with actionable diagnostics that distinguish malformed screen transitions from local destination changes.
[ ] 1.4.1.4 Subtask - Verify stacked modal descriptors accept repeated `open_modal` transitions and targetless top-modal `close_modal` without requiring modal nesting metadata.
[x] 1.4.1.1 Subtask - Verify authored `navigate_to`, `replace_with`, `go_back`, `go_forward`, `open_modal`, and `close_modal` descriptors validate successfully with the expected field requirements.
[x] 1.4.1.2 Subtask - Verify screen-transition descriptors reject URLs, route helpers, browser-history directives, and runtime-module identifiers.
[x] 1.4.1.3 Subtask - Verify invalid action and target combinations fail with actionable diagnostics that distinguish malformed screen transitions from local destination changes.
[x] 1.4.1.4 Subtask - Verify stacked modal descriptors accept repeated `open_modal` transitions and targetless top-modal `close_modal` without requiring modal nesting metadata.

[ ] 1.4.2 Task - Inspection and example scenarios
[x] 1.4.2 Task - Inspection and example scenarios
Verify maintained examples and tooling reflect canonical navigation
intent clearly before runtime mapping begins.

[ ] 1.4.2.1 Subtask - Verify inspection and export helpers report navigation action, symbolic screen target, params, and modal target fields deterministically.
[ ] 1.4.2.2 Subtask - Verify the maintained examples cover in-screen destination changes, top-level screen transitions, and modal transitions.
[ ] 1.4.2.3 Subtask - Verify foundational guidance stays aligned with the actual authored navigation surface and does not describe host-router semantics as part of the DSL.
[ ] 1.4.2.4 Subtask - Verify the stacked-modal example and inspection output make topmost close behavior visible without renderer-local stack identifiers.
[x] 1.4.2.1 Subtask - Verify inspection and export helpers report navigation action, symbolic screen target, params, and modal target fields deterministically.
[x] 1.4.2.2 Subtask - Verify the maintained examples cover in-screen destination changes, top-level screen transitions, and modal transitions.
[x] 1.4.2.3 Subtask - Verify foundational guidance stays aligned with the actual authored navigation surface and does not describe host-router semantics as part of the DSL.
[x] 1.4.2.4 Subtask - Verify the stacked-modal example and inspection output make topmost close behavior visible without renderer-local stack identifiers.
Loading
Loading