name: Nav
purpose: Render horizontal or vertical navigation from declarative brand and item data.

attributes:
  vertical:
    type: boolean

state:
  brand: "{ image?, icon?, label? }"
  list: Array of navigation item objects; bind with `$.state.list="navItems"`.
  value: Selected item `name`.
  openName: Open dropdown name in vertical mode.

item_types:
  label: Non-clickable text.
  button: Selectable navigation item.
  dropdown: Group of label, button, or switch items.
  fill: Horizontal spacer item.

events:
  change:
    detail: Selected item name. Fires only when the selected value changes.
  nav:
    detail: '{ item, name, selected } or { item, name, selected, open } for vertical dropdown changes. Fires for every activated button, including noselect action items.'

item_shape: "{ type, name?, label?, icon?, items?, bind?, class?, width? }"

examples:
  basic: |
    <script>
      const navBrand = { image: '/res/apiGo.min.svg' }
      const navItems = [
        { type: 'button', name: 'home', label: 'Home', icon: 'house' },
        { type: 'dropdown', name: 'admin', label: 'Admin', icon: 'shield', items: [
          { type: 'label', label: 'Manage' },
          { type: 'button', name: 'users', label: 'Users', icon: 'people' },
          { type: 'switch', name: 'alerts', label: 'Alerts', bind: { alerts: true } }
        ] },
        { type: 'fill' },
        { type: 'button', name: 'settings', label: 'Settings', icon: 'gear' }
      ]
    </script>
    <Nav class="border-end" $.state.brand="navBrand" $.state.list="navItems" $bind="Hash.nav" vertical></Nav>

rules:
  - Bind `$bind="Hash.nav"` when the selected navigation item must survive a page refresh.
  - Use `noselect: true` and nav for actions such as Logout, including buttons inside dropdowns: `$onnav="if(event.detail.name==='logout') logout()"`. Use change only for selected-page state.
  - Use the same `navItems` data for horizontal and vertical navigation when comparing layouts.
  - Selected items use the same neutral secondary surface in horizontal and vertical modes; selection must not depend on the application primary color.

tests:
  - Nav.test.html