# Feature: Navigation Runtime

## Intent

Problem: navigation styling does not provide mobile drawer disclosure, trigger state, Escape/outside dismissal, or focus restoration.
Users or stakeholders: application teams, QA, keyboard users, mobile users, and framework package maintainers.
Desired outcome: implement navigation drawer/mobile behavior while preserving static desktop navigation.
Non-goals: implement routing, active-route detection, authorization, or product-specific navigation trees.

## Scope

In scope: mobile drawer open/close, trigger wiring, submenu disclosure hooks, Escape/outside dismissal, ARIA state, focus restoration, and cleanup.
Out of scope: route management, menu content generation, CSS breakpoints, and application permissions.

## Markup Hooks

- Navigation root: `[data-sui-navigation]` or `[data-sui-component="navigation"]`.
- Drawer: `[data-sui-navigation-drawer]`.
- Trigger: `[data-sui-trigger="navigation"]` with `data-sui-target`.
- Disclosure: `[data-sui-navigation-disclosure]` or `[data-sui-trigger="navigation-disclosure"]`.

## Behavior

1. Opening a drawer dispatches `sui:navigation:before-open`; cancellation blocks the open.
2. Closing dispatches `sui:navigation:before-close`; cancellation blocks the close.
3. Successful state changes dispatch `sui:navigation:open` and `sui:navigation:close`.
4. Trigger state updates `aria-expanded`, controlled drawer hidden state, and `data-sui-state`.
5. Escape and outside pointer close an open drawer.
6. Focus returns to the trigger on close.
7. Static desktop navigation remains usable without runtime hooks.

## Accessibility

Prefer native navigation landmarks and buttons. Runtime behavior must not remove list/link semantics from navigation markup.

## Acceptance Examples

Scenario: mobile drawer
Given a navigation trigger controls a drawer
When the trigger is activated
Then the drawer opens and trigger ARIA state is synchronized.

Scenario: static desktop fallback
Given navigation markup has no runtime hooks
When the runtime initializes
Then links remain unchanged.