# Menu Navigation

## Essence

Private mobile navigation control used only inside `Component Page`.

It sits above `Component Detail Body` on Mobile breakpoint and controls whether the mobile menu overlay is visible. When the menu is hidden it shows `Component list`; when the menu is visible it shows `Back`.

## Hook

Use when `Component Page` needs a mobile-only control that opens or closes the menu overlay while staying outside the scrollable menu area.

## Status

Private

## Aliases

- Component page menu navigation
- Mobile component list control
- Former `Menu Container Header`

## Contract

- Used only inside `Component Page`.
- Visible only on Mobile breakpoint.
- Rendered above `Component Detail Body`.
- Stays outside `Menu Container`.
- Stays outside the scrollable `Menu` area.
- Stays visible when the menu overlay is open.
- Uses `Icon and Label Button` internally.
- Has state `Menu visible = false | true`.
- If `Menu visible = false`, shows `Component list` with the List icon.
- If `Menu visible = true`, shows `Back` with the Chevron Left icon.
- Does not own menu content, menu scrolling, selected state, or route state.
- Does not own overlay state; `Component Page` owns the state.

## Ownership

| Owner | Responsibilities |
| --- | --- |
| Component | Owns the visible mobile navigation bar, state-specific label/icon, background, and bottom separator. |
| Component Page | Owns mobile overlay state and places Menu Navigation above Component Detail Body. |
| Icon and Label Button | Owns icon + label button visuals and interaction states. |
| Menu Container | Owns menu scroll/resize container only; it does not use this component. |

## Public Props

- `menuVisible`: boolean state that switches the visible action.

## Preview-Only Context

- `Menu visible` switcher demonstrates `false` and `true` states.

## Internal Rules

- Keep this component private to `Component Page`.
- Do not render this component inside `Menu Container`.
- Render `Icon and Label Button` directly inside the navigation area.
- Use List icon for `Menu visible = false`.
- Use Chevron Left icon for `Menu visible = true`.
- Keep background as `--color-surface`.
- Keep bottom separator as `--color-line`.
- Height matches the current Header height assumption: `3.5rem`.
- On Mobile overlay, keep this component sticky/visible while the menu content scrolls below it.

## Non-Goals

- Does not replace `Header`.
- Does not replace `Menu Container`.
- Does not replace `Menu`.
- Does not define route selection.
- Does not own menu scroll behavior.

## Use When

- `Component Page` is in Mobile mode and needs a way to open the component list.
- `Component Page` menu overlay is open and needs a visible Back action.

## Do Not Use When

- Rendering a standalone page header.
- Rendering a menu item inside `Menu`.
- Rendering inside `Menu Container`.
- A component needs a generic icon + label action outside Component Page.

## Edge Cases

- If `Component Page` overlay behavior changes, this component state mapping must be reviewed.
- If Header height becomes a token, this component should consume that token instead of relying on `3.5rem`.
- If menu navigation needs route-aware labels later, route state must stay in the parent.

## Accessibility Notes

- The visible label carries the accessible name.
- The icon is decorative.
- `Component list` exposes the open action.
- `Back` exposes the close action.
- `Component Page` owns focus handoff when opening or closing the overlay.

## Token Dependencies

- `--color-surface`
- `--color-line`
- `--space-4`
- `3.5rem` Header height assumption

## Related Components And Patterns

| Item | Relationship | Direction | Notes |
| --- | --- | --- | --- |
| `Component Page` | Used By | Parent -> Child | Component Page renders this above Component Detail Body on Mobile. |
| `Component Detail Body` | Adjacent | Component <-> Component | Menu Navigation sits above it on Mobile. |
| `Menu Container` | Adjacent | Component <-> Component | Menu Container scrolls below it; it does not use Menu Navigation. |
| `Icon and Label Button` | Composes | Component -> Child | Provides the visible action. |

## Change Impact

| Change | Risk | Review Needed |
| --- | --- | --- |
| Changing state names | Medium | Check Component Page preview controls and behavior docs. |
| Changing height | Medium | Check mobile overlay top offset and sticky behavior. |
| Moving into Menu Container | High | Violates ownership and scroll-area separation. |

## Source Of Truth

| Source | Path / Link | Notes |
| --- | --- | --- |
| Component implementation | `packages/design-system/src/components/MenuNavigation.astro` | Primary layout source. |
| Parent component | `packages/design-system/src/components/ComponentPage.astro` | Real placement and overlay state owner. |
| DS page | `apps/portfolio-site/src/pages/design-system/index.astro` | Visible documentation and preview. |
| Relationship map | `docs/design-system/maps/component-relationship-map.md` | Component relationships. |

## Rule Confidence

| Rule | Evidence | Confidence |
| --- | --- | --- |
| Private to Component Page | User explicitly asked to move it out of Menu Container into Component Page. | High |
| Menu visible state | User explicitly requested `Menu visible = true, false`. | High |
| Not part of scrollable area | User explicitly requested this. | High |
| Menu Container must not use it | User explicitly requested this. | High |

## Open Questions

- Should the visible label be `Component list` or a shorter final name later?

## Code Paths

- `packages/design-system/src/components/MenuNavigation.astro`
- `packages/design-system/src/components/ComponentPage.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/pages/design-system/essences/[slug].md.ts`
- `docs/design-system/maps/component-relationship-map.md`

## Validation Checklist

- [x] Canonical name is clear
- [x] Aliases are captured
- [x] Contract is explicit
- [x] Ownership is separated
- [x] Public props are separated from preview-only context
- [x] Token dependencies are listed
- [x] Related items use typed relationships
- [x] Accessibility notes are present
- [x] Change impact is described
- [x] Code paths are listed
- [x] DS page link is updated
- [x] Route slug is updated
- [x] Relationship map is updated