ionbase-ui 0.18.1 → 0.19.0

package/dist/meta/TabItem.json

@@ -3,6 +3,48 @@
   "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Item.d.ts",
   "propsType": null,
   "import": "import { TabItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One tab and its panel. Re-exported from react-stately's collection Item — `title` is the tab label, children are the panel.",
+  "useWhen": [
+    "a child of Tabs — it is not usable anywhere else"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a row in a dropdown list",
+      "use": "MenuItem"
+    },
+    {
+      "when": "it is a navigation destination",
+      "use": "NavItem"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Tabs",
+      "TabItem"
+    ],
+    "note": "A collection item, not a rendered component: Tabs reads it to build the collection, so it never appears in the DOM itself. That is why it exposes no props of its own here — `key` and `title` are the collection's API.",
+    "example": "<TabItem key=\"billing\" title=\"Billing\">Billing panel content</TabItem>"
+  },
+  "a11y": {
+    "guarantees": [
+      "the tab/panel roles, ids and aria-controls pairing are supplied by Tabs, not by this element"
+    ],
+    "requires": [
+      "a stable `key` — it identifies the tab across renders and is what selection is expressed in",
+      "a `title` that reads as a label on its own"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "wrapping TabItem in a <div> or a fragment inside Tabs",
+      "why": "Tabs reads the collection from its direct children; a wrapper makes the item invisible to it"
+    },
+    {
+      "dont": "conditionally rendering TabItems with array indexes as keys",
+      "why": "selection is tracked by key, so the selected tab silently becomes a different tab"
+    }
+  ],
   "stylesheet": null,
   "tokens": [],
   "props": {},

package/dist/meta/TableBody.json

@@ -3,6 +3,42 @@
   "source": "src/components/Table.tsx",
   "propsType": null,
   "import": "import { TableBody } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The <tbody> section. Takes no props — it places the data rows and gives their cells body context.",
+  "useWhen": [
+    "every Table — the data rows go here"
+  ],
+  "useInstead": [
+    {
+      "when": "the row names the columns",
+      "use": "TableHead"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Table",
+      "TableBody",
+      "TableRow",
+      "TableCell"
+    ],
+    "note": "Zebra striping is read from each row's position inside this section rather than a prop repeated on every TableRow.",
+    "example": "<TableBody><TableRow><TableCell>Ada</TableCell></TableRow></TableBody>"
+  },
+  "a11y": {
+    "guarantees": [
+      "cells inside it default to <td>, and `scope` is inferred as `row` when a cell is marked `header`"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "rendering rows directly under Table with no TableBody",
+      "why": "the browser inserts a tbody anyway, but the head-or-body context does not exist, so cells cannot infer their scope"
+    },
+    {
+      "dont": "an empty TableBody with no empty state",
+      "why": "an empty table looks like a broken one — Table has no empty state of its own, so it is the caller's"
+    }
+  ],
   "stylesheet": "src/styles/table.css",
   "tokens": [
     "--border-default",

package/dist/meta/TableCell.json

@@ -4,6 +4,89 @@
   "propsType": "TableCellProps",
   "description": "One component covers Figma's `Table Cell` + `Cell Text`: the two are never\nused apart in the design (`Table Cell` always wraps exactly one `Cell\nText`), so splitting them into two exported components would only add API\nsurface for a composition nothing ever varies independently.\n\n`header` decides `<th>` vs `<td>` directly rather than a `type` prop that\ncould disagree with where the cell actually sits — a `<th>` rendered inside\n`<tbody>` is still a header cell to the browser and to CSS either way.",
   "import": "import { TableCell } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One cell, covering Figma's Table Cell and Cell Text together. `header` decides <th> versus <td>.",
+  "useWhen": [
+    "every cell in a Table, header or data"
+  ],
+  "useInstead": [
+    {
+      "when": "the content is a status label",
+      "use": "Badge",
+      "why": "put it inside the cell — the cell is the container, not the label"
+    }
+  ],
+  "variants": {
+    "scope": {
+      "col": {
+        "use": "a column header — inferred inside TableHead"
+      },
+      "row": {
+        "use": "a row header, e.g. the name column — inferred for a `header` cell in TableBody"
+      },
+      "colgroup": {
+        "use": "a header spanning several columns, with colspan"
+      },
+      "rowgroup": {
+        "use": "a header spanning several rows, with rowspan"
+      }
+    },
+    "align": {
+      "leading": {
+        "use": "the default — text, names, identifiers"
+      },
+      "trailing": {
+        "use": "numbers, currency and dates, so digits line up column-wise"
+      },
+      "center": {
+        "use": "icons, short status marks, checkboxes"
+      }
+    },
+    "variant": {
+      "default": {
+        "use": "the default — body text and icon colours"
+      },
+      "link": {
+        "use": "recolours the content to `text/link` / `icon/primary` for a cell whose content navigates"
+      }
+    }
+  },
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "leading icon; omit its `label`"
+    },
+    "trailingIcon": {
+      "accepts": "Icon",
+      "note": "trailing icon; same rule"
+    },
+    "children": {
+      "accepts": "any"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "`scope` is inferred when omitted — `col` in TableHead, `row` in TableBody — and can be set explicitly when the inference is wrong",
+      "`header` decides the element directly rather than a `type` prop that could disagree with where the cell sits"
+    ],
+    "requires": [
+      "`scope=\"col\"` on header cells — inferred inside TableHead, but explicit for a header rendered outside it"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`variant=\"link\"` on a cell with no link in it",
+      "why": "link-coloured text that does nothing is the clearest possible false affordance"
+    },
+    {
+      "dont": "leading-aligning a numeric column",
+      "why": "digits stop lining up, so the column can no longer be scanned for magnitude"
+    },
+    {
+      "dont": "`showDivider` on every cell",
+      "why": "it is a column rule, not a row rule — on every cell it becomes a grid"
+    }
+  ],
   "stylesheet": "src/styles/table.css",
   "tokens": [
     "--border-default",

package/dist/meta/TableHead.json

@@ -3,6 +3,45 @@
   "source": "src/components/Table.tsx",
   "propsType": null,
   "import": "import { TableHead } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The <thead> section. Takes no props — it places the header row and gives its cells their head-or-body context.",
+  "useWhen": [
+    "every Table with column headers, which is every data table"
+  ],
+  "useInstead": [
+    {
+      "when": "the rows are data",
+      "use": "TableBody"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Table",
+      "TableHead",
+      "TableRow",
+      "TableCell"
+    ],
+    "note": "Exists so TableRow and TableCell can tell head from body through context, rather than the caller repeating a prop that has to stay in sync with where the row actually sits.",
+    "example": "<TableHead><TableRow><TableCell scope=\"col\">Name</TableCell></TableRow></TableHead>"
+  },
+  "a11y": {
+    "guarantees": [
+      "cells inside it default to <th scope=\"col\">, and a row-selection cell becomes the select-all header"
+    ],
+    "requires": [
+      "a header row for every data table — without one, no data cell has a column to be associated with"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a data table with no TableHead",
+      "why": "a screen-reader user hears values with no field names"
+    },
+    {
+      "dont": "styling a first TableBody row to look like a header",
+      "why": "it looks like a header and announces as data"
+    }
+  ],
   "stylesheet": "src/styles/table.css",
   "tokens": [
     "--border-default",

package/dist/meta/TableRow.json

@@ -4,6 +4,51 @@
   "propsType": "TableRowProps",
   "description": "A plain `<tr>`. Hover is CSS-only (`:hover` plus a `data-hovered` escape\nhatch, matching the rest of the system) rather than React Aria's\n`useHover`: a row is not itself an interactive element — nothing about it\ntakes focus or fires a click — so there is no keyboard-vs-pointer\ndistinction to track. A clickable row is a link or button inside a cell,\nthe same accessible pattern Menu and Table Cell's own link variant use;\nnesting an interactive role on `<tr>` itself is not valid HTML.",
   "import": "import { TableRow } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A plain <tr>. Hover is CSS-only; a row is not itself interactive.",
+  "useWhen": [
+    "every row, in either TableHead or TableBody"
+  ],
+  "useInstead": [
+    {
+      "when": "the whole row should be clickable",
+      "use": "Link",
+      "why": "put the link or Button in a cell — nesting an interactive role on <tr> is not valid HTML"
+    }
+  ],
+  "slots": {
+    "selection": {
+      "accepts": "Checkbox props",
+      "note": "renders a leading Checkbox cell — a <th scope=\"col\"> select-all inside TableHead, a <td> inside TableBody. Takes the checkbox's own props rather than a boolean, since a selectable row needs `checked`/`onChange` wiring"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "hover comes from CSS `:hover` plus a `data-hovered` escape hatch, not React Aria — a row takes no focus and fires no click, so there is no keyboard-versus-pointer distinction to track",
+      "the selection cell's element follows the section it sits in"
+    ],
+    "requires": [
+      "every row-selection Checkbox to be labelled — those boxes have no visible label by design, so see Checkbox's own contract",
+      "`isSelected` alongside a checked selection checkbox, so the row's state is not carried by colour alone"
+    ],
+    "notes": [
+      "TableRow itself is never named — a <tr> is not an interactive element and takes no accessible name. The naming requirement above belongs to the Checkbox inside it."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`onClick` on TableRow",
+      "why": "it takes no focus, so a keyboard user can never fire it"
+    },
+    {
+      "dont": "`selection={{ checked }}` with no `onChange`",
+      "why": "a checkbox that cannot be changed reads as broken rather than as disabled"
+    },
+    {
+      "dont": "`isSelected` without a selection checkbox",
+      "why": "the row is tinted with nothing announcing why"
+    }
+  ],
   "stylesheet": "src/styles/table.css",
   "tokens": [
     "--border-default",

package/dist/meta/Tabs.json

@@ -3,6 +3,91 @@
   "source": "src/components/Tabs.tsx",
   "propsType": "TabsProps",
   "import": "import { Tabs } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A tab list and its panels, built on react-aria's tab collection. Children are TabItem.",
+  "useWhen": [
+    "one region of the page shows one of several peer views, and only one at a time",
+    "the views are peers — no ordering, no progression between them"
+  ],
+  "useInstead": [
+    {
+      "when": "the steps must be completed in order",
+      "use": "Button",
+      "why": "tabs imply peers you may visit in any order; a wizard is a sequence"
+    },
+    {
+      "when": "the sections should all be readable at once, or printable",
+      "use": "Divider",
+      "why": "tabs hide everything but the active panel, including from Ctrl-F"
+    },
+    {
+      "when": "it is navigation between pages rather than panels within one",
+      "use": "NavItem"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Tabs",
+      "TabItem"
+    ],
+    "note": "TabItem comes from react-stately's collection Item — it takes no props of its own beyond `title` (the tab label) and `key`; its children are the panel.",
+    "example": "<Tabs aria-label=\"Account\"><TabItem key=\"profile\" title=\"Profile\">…</TabItem><TabItem key=\"billing\" title=\"Billing\">…</TabItem></Tabs>"
+  },
+  "variants": {
+    "type": {
+      "pill": {
+        "use": "the default — a filled track, for switching views inside a panel or card"
+      },
+      "underline": {
+        "use": "a rule under the active tab, for page-level sections"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "dense panels and toolbars"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "page-level section switching"
+      }
+    },
+    "orientation": {
+      "horizontal": {
+        "use": "the default"
+      },
+      "vertical": {
+        "use": "a stacked track with up/down arrow keys",
+        "caveat": "keyboard and ARIA are complete, but the decoration is not — the underline rule and the pill track's padding are still written for the horizontal axis. Figma has not specified the vertical drawing"
+      }
+    }
+  },
+  "a11y": {
+    "role": "tablist / tab / tabpanel",
+    "guarantees": [
+      "roving tabindex, arrow-key navigation and the aria-controls/aria-labelledby pairing between each tab and its panel come from react-aria",
+      "the focus ring shows for keyboard focus only, and hover does not latch on touch"
+    ],
+    "requires": [
+      "`aria-label` or `aria-labelledby` on Tabs — the tab list is a named region",
+      "a stable `key` on every TabItem"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "tabs whose panels the user must read in order",
+      "why": "the role announces peers, and nothing stops a user landing on the last one first"
+    },
+    {
+      "dont": "hiding required form fields behind a tab",
+      "why": "a validation error in an inactive panel is invisible; the user is told the form is invalid with nothing on screen to fix"
+    },
+    {
+      "dont": "one tab",
+      "why": "a tablist with a single tab is chrome with no choice in it"
+    }
+  ],
   "stylesheet": "src/styles/tabs.css",
   "tokens": [
     "--border-default",

package/dist/meta/Toast.json

@@ -4,6 +4,87 @@
   "propsType": "ToastProps",
   "description": "Toast — Figma `Toast` (820:1655).\n\nNeutral chrome on `surface/raised`; the intent is carried by the icon alone.\nA tinted panel floating over unknown content competes with whatever is\nbehind it, and makes Toast and Alert indistinguishable at a glance.\n\nAUTO-DISMISS PAUSES ON HOVER AND FOCUS. A toast that keeps counting down\nwhile being read or while its action has keyboard focus takes the action\naway mid-reach — WCAG 2.2.1 asks for exactly this. The timer restarts rather\nthan resumes, which is the forgiving direction.",
   "import": "import { Toast } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A transient notification on neutral chrome. Intent is carried by the icon, not by a tinted panel.",
+  "useWhen": [
+    "confirming that something the user just did succeeded or failed",
+    "the message is short, transient, and not required to complete a task"
+  ],
+  "useInstead": [
+    {
+      "when": "the message must stay until the condition is resolved",
+      "use": "Alert",
+      "why": "a toast disappears, and anything the user must act on should not"
+    },
+    {
+      "when": "the message belongs to one field",
+      "use": "Input",
+      "why": "Input's error text sits with the field it is about"
+    },
+    {
+      "when": "you need a decision from the user",
+      "use": "Modal",
+      "why": "a toast offers one action and takes it away on a timer"
+    }
+  ],
+  "variants": {
+    "intent": {
+      "neutral": {
+        "use": "a plain fact with no status attached"
+      },
+      "primary": {
+        "use": "brand-flavoured confirmations"
+      },
+      "success": {
+        "use": "the action completed"
+      },
+      "warning": {
+        "use": "it completed with a caveat worth knowing"
+      },
+      "error": {
+        "use": "it failed — pair with a way to retry"
+      },
+      "information": {
+        "use": "the default — a neutral update"
+      }
+    }
+  },
+  "slots": {
+    "title": {
+      "accepts": "text"
+    },
+    "message": {
+      "accepts": "text"
+    },
+    "action": {
+      "accepts": "{ label, onPress }",
+      "note": "exactly one action. A second choice belongs in a Modal, which will still be there"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "auto-dismiss pauses on hover and on focus, and restarts rather than resumes — WCAG 2.2.1, and the forgiving direction",
+      "announcement comes from ToastProvider's live region, which is always present rather than appearing with its content"
+    ],
+    "requires": [
+      "rendering inside a ToastProvider — a Toast on its own is not in a live region",
+      "`duration={null}` when the message carries an action the user genuinely needs"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a toast for an error the user must fix",
+      "why": "it vanishes; the fix does not"
+    },
+    {
+      "dont": "two actions in one toast",
+      "why": "a timed choice is not a choice"
+    },
+    {
+      "dont": "stacking several toasts for one operation",
+      "why": "the stack covers the page and the last one is the only one read"
+    }
+  ],
   "stylesheet": "src/styles/toast.css",
   "tokens": [
     "--border-subtle",

package/dist/meta/ToastProvider.json

@@ -4,6 +4,63 @@
   "propsType": "ToastProviderProps",
   "description": "Renders the queue and supplies `useToast`.\n\nThe live region is the CONTAINER, declared once and always present. A region\nthat appears at the same moment as its content is not reliably announced —\nassistive tech has to be watching the node before the text lands in it.",
   "import": "import { ToastProvider } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Renders the toast queue and supplies the `useToast` hook. Mount once, near the app root.",
+  "useWhen": [
+    "the app shows toasts anywhere — this is the only way to get `useToast`"
+  ],
+  "useInstead": [
+    {
+      "when": "you only need one persistent in-page message",
+      "use": "Alert",
+      "why": "no provider, no queue, and it stays put"
+    }
+  ],
+  "variants": {
+    "placement": {
+      "top-left": {
+        "use": "rare — for RTL layouts or where the top-right is occupied"
+      },
+      "top-right": {
+        "use": "the common desktop choice, out of the way of primary content"
+      },
+      "bottom-left": {
+        "use": "keeps toasts clear of a right-hand panel"
+      },
+      "bottom-right": {
+        "use": "close to where a save or submit action usually sits"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "any",
+      "note": "your app — the provider wraps it"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the live region is the container, declared once and always present — a region that appears at the same moment as its content is not reliably announced",
+      "`limit` drops the oldest toasts, so the stack can never cover the page"
+    ],
+    "requires": [
+      "mounting exactly one ToastProvider — a second live region competes with the first"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "mounting a ToastProvider per route or per page",
+      "why": "toasts queued before the switch are unmounted mid-announcement, and two live regions announce over each other"
+    },
+    {
+      "dont": "placing it inside a Modal",
+      "why": "the toasts are removed from the tree when the modal closes, and hidden from assistive tech while it is open"
+    },
+    {
+      "dont": "raising `limit` to keep everything",
+      "why": "an unbounded stack covers the content the toasts are about"
+    }
+  ],
   "stylesheet": "src/styles/toast.css",
   "tokens": [
     "--border-subtle",

package/dist/meta/Toggle.json

@@ -4,6 +4,82 @@
   "propsType": "ToggleProps",
   "description": "Toggle is a checkbox with `role=\"switch\"`.\n\nNot a button with aria-pressed: a switch is a form value, and the checkbox\ngives form association and `:checked` for free. `role=\"switch\"` changes only\nhow it is announced — \"on/off\" rather than \"checked/unchecked\" — which is\nwhat Figma's On/Off states describe.\n\nThe visual difference from Checkbox is entirely in CSS; this component and\nCheckbox are near-identical by design rather than by accident, and are kept\napart because Figma models them as separate components with separate size\nramps.",
   "import": "import { Toggle } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A switch — a checkbox with role=\"switch\", announced as on/off.",
+  "useWhen": [
+    "the change takes effect immediately: a setting, a feature flag, a preference"
+  ],
+  "useInstead": [
+    {
+      "when": "the value is collected and submitted with a form",
+      "use": "Checkbox",
+      "why": "a switch reads as taking effect now; a checkbox reads as a value being gathered"
+    },
+    {
+      "when": "there are more than two states",
+      "use": "RadioGroup"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense settings rows and table filters"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent single settings"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "a setting with no positive or negative reading — display and layout preferences"
+      },
+      "danger": {
+        "use": "turning on something destructive or hard to undo"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the visible label; omit for a bare switch and supply `aria-label`"
+    }
+  },
+  "a11y": {
+    "role": "switch",
+    "guarantees": [
+      "a real <input type=\"checkbox\"> underneath, so form association, label clicking and `:checked` come from the platform",
+      "`role=\"switch\"` changes only the announcement — \"on/off\" rather than \"checked/unchecked\""
+    ],
+    "requires": [
+      "`children`, or `aria-label` when there is no visible label"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Toggle with a Save button beside it",
+      "why": "a switch says the change is already applied; if it needs saving it is a Checkbox"
+    },
+    {
+      "dont": "labelling a Toggle \"Enable dark mode?\" as a question",
+      "why": "a switch label names the thing being switched, not a question about it"
+    },
+    {
+      "dont": "a button with `aria-pressed` for a setting",
+      "why": "a switch is a form value; the checkbox gives form association and `:checked` for free"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/toggle.css",
   "tokens": [
     "--border-disabled",