ionbase-ui 0.51.0 → 0.69.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/Select.json

@@ -13,7 +13,8 @@
   "useInstead": [
     {
       "when": "the list is long enough to need search or type-ahead beyond the native behaviour",
-      "use": "a combobox — not yet in this system"
+      "use": "Combobox",
+      "why": "a native <select> list is the browser's, and cannot be filtered"
     },
     {
       "when": "the rows need icons, avatars or two lines of text",
@@ -126,10 +127,10 @@
       "default": "md"
     },
     "options": {
-      "type": "SelectOption[] | undefined",
+      "type": "readonly SelectOption[] | undefined",
       "required": false,
       "origin": "own",
-      "description": "The options to render. Omit and pass `children` for grouped options."
+      "description": "The options to render. Omit and pass `children` for grouped options.\n\n`readonly` because an options list is almost always a module-level constant,\nand `as const` on one produces a readonly array that a mutable parameter\nrejects. The component only ever maps over it, so demanding a mutable array\nbought nothing and cost callers a spread or a cast."
     },
     "placeholder": {
       "type": "string | undefined",

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
+  }
+}

package/dist/meta/SidebarSection.json

@@ -0,0 +1,131 @@
+{
+  "name": "SidebarSection",
+  "source": "src/components/Sidebar.tsx",
+  "propsType": "SidebarSectionProps",
+  "import": "import { SidebarSection } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A group of sidebar items under an optional title, which can fold away and carry its own actions.",
+  "useWhen": [
+    "inside a Sidebar, once per group — the untitled top group, then Favorites, Spaces"
+  ],
+  "useInstead": [
+    {
+      "when": "the grouping is one item and its children",
+      "use": "SidebarItem",
+      "why": "an item with nested items already expands; a section per parent doubles the structure"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "SidebarItem",
+      "note": "items only — the section renders a list"
+    },
+    "actions": {
+      "accepts": "Button",
+      "note": "beside the title — a + to create in this group. Icon-only buttons need aria-label"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "a titled section's list is named by its title, so a screen reader announces \"Spaces, list, 4 items\"",
+      "a collapsible title is a button with aria-expanded and aria-controls; the folded list is hidden, not unmounted"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "isCollapsible with no title",
+      "why": "there is nothing to press; the prop is ignored"
+    },
+    {
+      "dont": "collapsing the section that holds the current page by default",
+      "why": "the user's location is hidden on arrival — leave it open, or open it when the page is inside"
+    }
+  ],
+  "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": {
+    "title": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The group's name — \"Spaces\", \"Favorites\". Omit for the top group."
+    },
+    "isCollapsible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Lets the title fold the section away. Needs a `title`."
+    },
+    "defaultExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled: whether a collapsible section starts open."
+    },
+    "isExpanded": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled: whether a collapsible section is open."
+    },
+    "onExpandedChange": {
+      "type": "((isExpanded: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "actions": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Controls beside the title — a `+` Button to create a space. Icon-only\nbuttons need their own `aria-label`."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`SidebarItem`s only — the section renders a list."
+    }
+  },
+  "propCounts": {
+    "own": 7,
+    "aria": 0,
+    "dom": 276,
+    "other": 0
+  }
+}