{
  "name": "Sidebar",
  "source": "src/components/Sidebar.tsx",
  "propsType": "SidebarProps",
  "description": "Sidebar — an application's navigation, as a column.\n\nDISCLOSURE NAVIGATION, NOT `role=\"tree\"`\n\nA file-tree look invites the tree role, and the tree role is wrong here.\nA treeview takes the arrow keys, allows one tab stop for the whole widget,\nand does not permit interactive content inside an item — so the `…` and `+`\nbuttons on a row, which are half the point of a workspace sidebar, could not\nexist in it. This is the WAI-ARIA disclosure navigation pattern instead:\nnested lists of links, each expandable level behind a real button with\n`aria-expanded`, and everything reachable with Tab.\n\nAN ITEM THAT IS A LINK AND HAS CHILDREN GETS TWO CONTROLS\n\nA button cannot sit inside a link. So a row that navigates AND expands\nrenders the link and a separate chevron button beside it; a row with no\n`href` is one button that expands. The actions slot is a sibling of both,\nnever nested inside either.\n\nTHE CURRENT PAGE IS NEVER FOLDED AWAY\n\nAn item whose subtree contains the current page starts open. A sidebar that\nloads with the user's location collapsed inside a closed group tells a\nsighted user nothing and a screen-reader user less.\n\nExpansion is per item, controlled or not. Remembering it across visits is the\ncaller's job — this component cannot know where that state should live.",
  "import": "import { Sidebar } from 'ionbase-ui';",
  "status": "stable",
  "summary": "An application's navigation as a column: pinned header and footer that take any component, a scrolling body of titled, collapsible sections, and nested items that expand.",
  "useWhen": [
    "an app has more destinations than fit in a header — workspaces, projects, saved views",
    "the navigation is hierarchical and users need to see where they are inside it",
    "rows need their own actions — create inside this space, rename, favourite"
  ],
  "useInstead": [
    {
      "when": "there are five or fewer top-level destinations and no hierarchy",
      "use": "Header",
      "why": "a sidebar spends a column of width on what a header row carries in its height"
    },
    {
      "when": "the hierarchy describes the current page's position rather than offering destinations",
      "use": "Breadcrumb"
    },
    {
      "when": "sections of content collapse, not destinations",
      "use": "Accordion",
      "why": "Accordion's headings belong to the document outline; a sidebar is a navigation landmark"
    },
    {
      "when": "the hierarchy is data to browse or pick from — folders of files, teams in departments — not the app's pages",
      "use": "TreeView",
      "why": "a sidebar row is a link to a place; a tree row is an item, selected or opened in place, with a level and a position the tree announces"
    }
  ],
  "composition": {
    "order": [
      "Sidebar",
      "SidebarSection",
      "SidebarItem"
    ],
    "note": "Items always go inside a section, because a section renders the list. Anything that is not an item — a Divider, a promotional Alert — goes directly in Sidebar between sections, or in `header` / `footer`. On narrow screens, put the Sidebar inside a Drawer; it does not collapse itself.",
    "example": "<Sidebar label=\"Workspace\" header={<WorkspaceMenu />} footer={<Button>Invite</Button>}><SidebarSection><SidebarItem label=\"Home\" href=\"/\" isCurrent /></SidebarSection><Divider /><SidebarSection title=\"Spaces\" isCollapsible><SidebarItem label=\"Team Space\" href=\"/team\"><SidebarItem label=\"Projects\" href=\"/team/projects\" /></SidebarItem></SidebarSection></Sidebar>"
  },
  "slots": {
    "header": {
      "accepts": "Menu",
      "note": "pinned above the scroll — a workspace switcher, search, icon Buttons"
    },
    "footer": {
      "accepts": "Button",
      "note": "pinned below the scroll — Invite, Help, a trial notice in an Alert"
    },
    "children": {
      "accepts": "SidebarSection",
      "note": "and Divider or other non-item content between sections"
    }
  },
  "a11y": {
    "role": "navigation",
    "requires": [
      "`label` — the accessible name of the navigation landmark. Pages with a sidebar usually have a second nav, and two unnamed ones cannot be told apart"
    ],
    "guarantees": [
      "only the body scrolls; the header and footer stay reachable at any scroll position"
    ],
    "notes": [
      "it is disclosure navigation, not a treeview: everything is reachable with Tab, and rows can hold buttons. The tree role forbids interactive content inside items and would have ruled out row actions"
    ]
  },
  "antiPatterns": [
    {
      "dont": "role=\"tree\" on a sidebar with row actions",
      "why": "a treeview item cannot contain buttons, and its arrow-key model hides every action from Tab"
    },
    {
      "dont": "a SidebarItem placed directly in Sidebar, outside a section",
      "do": "wrap it in an untitled <SidebarSection>",
      "why": "the item renders an <li>, which is only valid inside the list a section provides"
    },
    {
      "dont": "a sidebar that is only ever a hamburger menu on desktop",
      "why": "hierarchical navigation that is hidden by default is navigation nobody uses; hide it only where the width forces it"
    }
  ],
  "stylesheet": "src/styles/sidebar.css",
  "tokens": [
    "--border-focus",
    "--border-subtle",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-medium",
    "--icon-disabled",
    "--icon-primary",
    "--icon-secondary",
    "--icon-size-sm",
    "--icon-tertiary",
    "--ion-duration-base",
    "--ion-ease-out",
    "--radius-md",
    "--radius-sm",
    "--radius-xs",
    "--spacing-12",
    "--spacing-16",
    "--spacing-2",
    "--spacing-24",
    "--spacing-32",
    "--spacing-4",
    "--spacing-8",
    "--surface-default",
    "--surface-hover",
    "--surface-selected",
    "--surface-selected-hover",
    "--text-default",
    "--text-disabled",
    "--text-secondary",
    "--text-tertiary",
    "--type-body-sm",
    "--type-body-sm-line-height",
    "--type-caption",
    "--type-caption-line-height"
  ],
  "props": {
    "label": {
      "type": "string",
      "required": true,
      "origin": "own",
      "description": "Names the navigation landmark. Required: a page with a sidebar usually has\na second `<nav>` too, and \"navigation, navigation\" tells nobody which is\nwhich."
    },
    "header": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Pinned above the scrolling body — a workspace switcher, a search trigger,\nicon buttons. Any component."
    },
    "footer": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Pinned below the scrolling body — an Invite button, help, a trial notice.\nAny component."
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "`SidebarSection`s, and anything that sits between them — a `Divider`, a\npromotional card. Items themselves always go inside a section."
    }
  },
  "propCounts": {
    "own": 4,
    "aria": 0,
    "dom": 277,
    "other": 0
  }
}