ionbase-ui 0.59.0 → 0.70.0

package/dist/meta/SegmentedControl.json

@@ -0,0 +1,217 @@
+{
+  "name": "SegmentedControl",
+  "source": "src/components/SegmentedControl.tsx",
+  "propsType": "SegmentedControlProps",
+  "description": "SegmentedControl — pick one of a few options, and see all of them.\n\nNOT TABS, ALTHOUGH IT LOOKS LIKE THE PILL TYPE, and the difference is the\ncontract. Tabs switch between panels: `tablist`, `tab`, `tabpanel`, and each\ntab controls a region. This sets a VALUE — a view mode, a time range, a\nunit — and controls no panel. It is a `radiogroup`, so it has one tab stop,\narrow keys move and select, and it submits with a form like any radio.\n\nBuilt from real radio inputs, visually hidden, not from buttons with\n`aria-pressed`. A row of toggle buttons is a tab stop per option and no\nmutual exclusion that assistive tech can announce; radios give \"2 of 3,\nselected\" for free.\n\nThe look is Tabs' pill track, token for token, so the two cannot drift\napart visually — which is exactly why the intent file spends its words on\nwhen to use which.",
+  "import": "import { SegmentedControl } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Pick one of two to five options, all visible at once. A radio group drawn as a segmented track — it sets a value and controls no panel.",
+  "useWhen": [
+    "switching how the same content is shown — List / Board / Calendar",
+    "a short, fixed set of mutually exclusive settings — Day / Week / Month, °C / °F",
+    "a filter with a few exclusive choices where seeing every option matters"
+  ],
+  "useInstead": [
+    {
+      "when": "each option shows a different panel of content",
+      "use": "Tabs",
+      "why": "Tabs wires each tab to its panel with tablist/tabpanel semantics. A SegmentedControl controls no region, so a screen-reader user is never told which content changed"
+    },
+    {
+      "when": "there are more than five options, or the labels are long",
+      "use": "Select",
+      "why": "segments do not wrap; a track that overflows hides the options it exists to show"
+    },
+    {
+      "when": "the choice sits in a form with a visible question and descriptions per option",
+      "use": "RadioGroup",
+      "why": "same semantics, but room for a label and helper text on each option"
+    },
+    {
+      "when": "the setting is a single on/off",
+      "use": "Toggle"
+    },
+    {
+      "when": "the options trigger actions rather than set a value — Bold, Italic",
+      "use": "Button",
+      "why": "an action is not a selection; a radio group announces a state that does not exist"
+    }
+  ],
+  "composition": {
+    "order": [
+      "SegmentedControl",
+      "SegmentedControlItem"
+    ],
+    "example": "<SegmentedControl label=\"View\" defaultValue=\"list\"><SegmentedControlItem value=\"list\">List</SegmentedControlItem><SegmentedControlItem value=\"board\">Board</SegmentedControlItem></SegmentedControl>"
+  },
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "toolbars and dense panel headers"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a primary view switch at the top of a page"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "SegmentedControlItem",
+      "note": "two to five. One item is not a choice; six is a Select"
+    }
+  },
+  "a11y": {
+    "role": "radiogroup / radio",
+    "requires": [
+      "`label` — the group's accessible name. Hidden by default; `showLabel` renders it above the track"
+    ],
+    "guarantees": [
+      "one tab stop for the whole control; arrow keys move and select, skipping disabled segments",
+      "built from real radio inputs, so it announces \"2 of 3, selected\" and submits with a form under `name`",
+      "a disabled selected segment keeps its selected surface — a disabled control still has a value"
+    ],
+    "notes": [
+      "it looks exactly like Tabs' pill type on purpose, and behaves differently on purpose. Choose by what changes, not by how it looks"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a SegmentedControl that swaps the panel below it",
+      "do": "<Tabs type=\"pill\">",
+      "why": "the panel relationship is exactly what tabpanel semantics announce; without it the content changes silently"
+    },
+    {
+      "dont": "no defaultValue or value",
+      "why": "a segmented track with nothing selected reads as broken, not as a choice still to make"
+    },
+    {
+      "dont": "icon-only segments with no aria-label",
+      "do": "<SegmentedControlItem value=\"grid\" icon={<Grid />} aria-label=\"Grid view\" />",
+      "why": "each segment is a radio, and an unnamed radio is announced as just \"radio button\""
+    }
+  ],
+  "stylesheet": "src/styles/segmented-control.css",
+  "tokens": [
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-segmented-font-size",
+    "--ion-segmented-icon-size",
+    "--ion-segmented-item-gap",
+    "--ion-segmented-item-height",
+    "--ion-segmented-item-padding-x",
+    "--ion-segmented-line-height",
+    "--radius-lg",
+    "--radius-md",
+    "--ring-focus",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-40",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-muted",
+    "--surface-page",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "The accessible name of the group. Required: \"List, Board, Calendar\" means\nnothing until something says they are views."
+    },
+    "showLabel": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show `label` above the control, as a form field does. Hidden by default.",
+      "default": false
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled selected value. Pass `onChange` with it."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled starting value. One option should always be selected — a\nsegmented control with nothing chosen reads as broken, not as \"no choice\"."
+    },
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "size": {
+      "type": "SegmentedControlSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "isFullWidth": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Stretch to the container, with equal-width segments.",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "default": false
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Submitted with a form under this name."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`SegmentedControlItem` elements. Two to five of them."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 11,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/SegmentedControlItem.json

@@ -0,0 +1,122 @@
+{
+  "name": "SegmentedControlItem",
+  "source": "src/components/SegmentedControl.tsx",
+  "propsType": "SegmentedControlItemProps",
+  "import": "import { SegmentedControlItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One segment: a radio drawn as part of the track, with an optional icon.",
+  "useWhen": [
+    "inside a SegmentedControl, once per option"
+  ],
+  "useInstead": [
+    {
+      "when": "outside a segmented track",
+      "use": "Radio"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "one or two words. Segments do not wrap, and a long label truncates"
+    },
+    "icon": {
+      "accepts": "Icon",
+      "note": "decorative beside a label; with no label, pass aria-label"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`aria-label` when the segment has an icon and no text — the accessible name otherwise comes from its children"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "using it outside SegmentedControl",
+      "why": "it reads its selection state from the group, and throws without one"
+    }
+  ],
+  "stylesheet": "src/styles/segmented-control.css",
+  "tokens": [
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-segmented-font-size",
+    "--ion-segmented-icon-size",
+    "--ion-segmented-item-gap",
+    "--ion-segmented-item-height",
+    "--ion-segmented-item-padding-x",
+    "--ion-segmented-line-height",
+    "--radius-lg",
+    "--radius-md",
+    "--ring-focus",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-40",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-muted",
+    "--surface-page",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "The value this segment selects."
+    },
+    "icon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Icon before the label. `aria-hidden` is applied for you."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Required when the segment has no visible text — an icon-only segment is\notherwise announced as an unnamed radio button."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "default": false
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/Sidebar.json

@@ -0,0 +1,150 @@
+{
+  "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"
+    }
+  ],
+  "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
+  }
+}

package/dist/meta/SidebarItem.json

@@ -0,0 +1,184 @@
+{
+  "name": "SidebarItem",
+  "source": "src/components/Sidebar.tsx",
+  "propsType": "SidebarItemProps",
+  "import": "import { SidebarItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One sidebar row: a link or a button, with an icon, a count, actions revealed on hover or focus, and nested items that expand.",
+  "useWhen": [
+    "inside a SidebarSection, or nested inside another SidebarItem"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a link in a header bar",
+      "use": "NavItem",
+      "why": "NavItem recolours on hover without a fill, as measured for the header; sidebar rows fill"
+    },
+    {
+      "when": "it is a row in a dropdown",
+      "use": "MenuItem"
+    }
+  ],
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "decorative; label names the row"
+    },
+    "badge": {
+      "accepts": "text",
+      "note": "a count or short status, trailing"
+    },
+    "actions": {
+      "accepts": "Button",
+      "note": "icon-only Buttons with aria-label, or a Menu trigger for more. Keep to two"
+    },
+    "children": {
+      "accepts": "SidebarItem",
+      "note": "nested items; their presence makes the row expandable"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` — the row's name, and the name of its expand button when it has children"
+    ],
+    "guarantees": [
+      "`isCurrent` sets aria-current=\"page\" on the link",
+      "a row with `href` and children renders the link and a separate expand button beside it — a button cannot be nested in a link",
+      "a row with children and no `href` is a single button with aria-expanded",
+      "a row whose subtree holds the current page starts expanded",
+      "actions stay in the tab order and become visible when focus reaches them; they are always visible on touch screens"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "onClick on a row to navigate",
+      "do": "href",
+      "why": "a real link opens in a new tab, shows its address and is announced as a link"
+    },
+    {
+      "dont": "actions nested inside the label or icon",
+      "do": "the actions prop",
+      "why": "interactive content inside a link is invalid and unreachable by keyboard in most browsers"
+    },
+    {
+      "dont": "marking a parent isCurrent because a child page is open",
+      "why": "only the page the user is on is current; its ancestors are opened for them instead"
+    }
+  ],
+  "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": "The item's text. A string, because it also names the expand button of an\nitem that has children."
+    },
+    "icon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Leading icon. Decorative — `label` names the item."
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Where it goes. Omit for an item that only groups its children."
+    },
+    "onPress": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "For an item that acts rather than navigates. Ignored with `href`."
+    },
+    "isCurrent": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The page the user is on. Marked `aria-current=\"page\"`."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "badge": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Trailing text — a count, a shortcut, a status."
+    },
+    "actions": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Controls for this row — `…` and `+`. Revealed on hover and whenever focus\nis inside the row; always shown on touch screens. Icon-only buttons need\ntheir own `aria-label`."
+    },
+    "defaultExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled: whether the children start open. Defaults to open when the\ncurrent page is somewhere inside."
+    },
+    "isExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled: whether the children are open."
+    },
+    "onExpandedChange": {
+      "type": "((isExpanded: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Nested `SidebarItem`s. Their presence is what makes the item expandable."
+    }
+  },
+  "propCounts": {
+    "own": 12,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}