Navigation

12.1 Navigation Patterns

Pattern	How it works
Tab-based root	Wrap the app root in a tab component. Each direct child module becomes one tab. Set _tabTitle and _tabImage in the child module’s context.
Push via link	Embed a link component. Set its destination to a module. Tapping pushes the module onto the navigation stack.
Push via navigate action	Use the navigate action with operation: "push" to imperatively push a component. The component is referenced by a source string (dp:// or file://) — not inline.
Pop via navigate action	Use operation: "pop" to dismiss the top screen, or supply moduleId to pop back to a specific screen. Use operation: "popToRoot" to return to the root in one step.
Modal / sheet	Use style.modal on any component. isPresented binds to a state boolean. Supported types: alert, popover, sheet, fullScreenCover.
Navigation title	Set style.navigation.navigationTitle, or the public context key navigationTitle, on any component inside a navigation container.
Toolbar items	Set style.navigation.toolbarLeading and toolbarTrailing to embed button components in the navigation bar.

12.2 Navigation Contract

Imperative navigation (the navigate action) requires only a navigation component in the ancestor hierarchy.

// 1. navigation component — no _path context required
{ "id": "root_nav", "type": "navigation",
  "children": [ ... ] }

// 2. navigate action — operation-based
{ "navigate": { "id": "push_detail",
  "input": { "operation": "push", "source": "dp://detail_module" } } }

{ "navigate": { "id": "go_back",
  "input": { "operation": "pop" } } }

{ "navigate": { "id": "go_home",
  "input": { "operation": "popToRoot" } } }

Contract rules:

• The navigate action MUST be triggered from within a component that is a descendant of a navigation component (directly or through the module hierarchy). The action is automatically propagated to the nearest owning navigation scope. open is exempt: it leaves the navigation stack untouched and needs no navigation ancestor.
• input.operation MUST be one of push, pop, popToRoot, or open.
• input.source is REQUIRED when operation is push. It must be a dp:// or file:// source string pointing to the component to push — not an inline object.
• link components do not use the navigate action. Their destination is an inline component object and navigation is handled automatically.