# Menu

## Essence

Private navigation tree owner used only inside `Component Page Template Menu Container`.

`Menu` owns the composition of collapsible groups and leaf menu items. It is the only place where `Menu Item` and `Collapsible Menu Item` should be assembled into a navigable tree.

## Hook

Use when `Component Page Template Menu Container` needs structured side navigation with one or more groups, nested groups, and selectable leaf items.

## Internal Rules

- Uses `--space-8` for top and bottom padding.

- Owns menu navigation composition.
- Used only inside `Component Page Template Menu Container`.
- Can contain one or more `Collapsible Menu Item` groups.
- Can indirectly contain `Menu Item` leaves through `MenuBranch`.
- Supports nested `Collapsible Menu Item` branches in any order and amount.
- Width is 100% of `Component Page Template Menu Container`.
- Height is constrained by the parent.
- If content is taller than available height, Menu scrolls vertically.
- Menu scroll should be independent from page/content scroll.
- Menu is the sole vertical scroll owner for its complete nested navigation tree.
- `Collapsible Menu Item` and nested submenu content must not create internal scrollbars.
- Uses `aria-label` to describe the navigation region.
- Does not own page content, page title, preview area, or component documentation content.

## Use When

- A page needs side navigation.
- Navigation has grouped sections.
- Navigation has nested groups.
- Navigation must preserve active/current item state.
- Navigation content may overflow vertically.

## Do Not Use When

- Only one inline text link is needed; use `Link`.
- A single menu leaf is needed inside an existing menu; use `Menu Item`.
- A single expandable group is needed inside an existing menu; use `Collapsible Menu Item`.
- The content is not navigation.
- The navigation is outside `Component Page Template Menu Container`.

## Edge Cases

- Keep the menu tree shallow unless nested structure is needed.
- Keep labels short enough for scanning.
- Active item state must remain visible after hash navigation.
- Scrollbars should appear only when menu content exceeds available vertical space.
- Do not wrap Menu in extra cards or decorative containers when used as page navigation.

## Accessibility Notes

- Render as a `nav` landmark.
- Provide a meaningful `aria-label`.
- Keep focus states visible inside the scrollable menu area.
- Nested interactive elements must remain independently focusable.
- Disabled child items should be removed from tab order by their owning child component.

## Related Components And Patterns

- `Collapsible Menu Item`: group or nested branch inside Menu.
- `Menu Item`: leaf navigation item inside Menu.
- `Disclosure Icon Button`: indirect child used by clickable collapsible groups.
- `Component Page Template Menu Container`: the only owner allowed to contain Menu.
- `Component Page Template`: consumes Menu indirectly through Menu Container.

## Code Paths

- `packages/design-system/src/components/Menu.astro`
- `packages/design-system/src/components/MenuBranch.astro`
- `packages/design-system/src/components/CollapsibleMenuItem.astro`
- `packages/design-system/src/components/MenuItem.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`