name: Nav

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? }"

example: |
  <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 nav for actions such as Logout: `$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.