ionbase-ui 0.76.0 → 0.81.0

package/dist/meta/components.json

@@ -1,9 +1,10 @@
 {
   "package": "ionbase-ui",
-  "version": "0.76.0",
+  "version": "0.81.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useAgentRun",
+    "useTableSort",
     "useToast"
   ],
   "helpers": [
@@ -2665,6 +2666,159 @@
         "other": 0
       }
     },
+    "Card": {
+      "name": "Card",
+      "source": "src/components/Card.tsx",
+      "propsType": "CardProps",
+      "description": "Card — a bordered surface that groups one part of a page.\n\nPromoted from the demo app, where the same surface was hand-written as\n`.demo-panel` in nine screens: a settings group, a chart panel, a runs log,\nthe danger zone. For a feature row with media use FullCard; for one\nheadline figure use StatTile.\n\nTHE TITLE DECIDES THE ELEMENT\n\nA titled card is a `<section aria-labelledby>` — a named region, so a\nscreen reader user can jump between cards the way a sighted one scans\nthem. An untitled card is a `<div>`: a `<section>` with no name is not a\nlandmark at all, and pretending otherwise only adds noise.\n\nNo `'use client'`: `useId` resolves on the server, and nothing here is\ninteractive. Interactive parts arrive through `action` and `children`.",
+      "import": "import { Card } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.77.0",
+      "summary": "A bordered surface that groups one part of a page, with an optional title row. A titled card is a named region; an untitled one is a plain surface.",
+      "useWhen": [
+        "a page is several distinct groups — settings sections, dashboard panels, a log beside a chart",
+        "a group needs a title, a one-line description or a single action like \"All runs\"",
+        "a loading placeholder needs the same frame as the content it stands in for"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a feature row with a headline, text and a media panel",
+          "use": "FullCard"
+        },
+        {
+          "when": "it is one headline figure and how it moved",
+          "use": "StatTile"
+        },
+        {
+          "when": "the content is a list of settings, each with a label and a control",
+          "use": "SettingRow"
+        },
+        {
+          "when": "the message needs the user's attention now rather than a place on the page",
+          "use": "Alert"
+        }
+      ],
+      "composition": {
+        "note": "The title row is built from props — `title`, `description`, `action` — so every card lays it out the same way. The body is `children`, spaced 12 apart by the card's grid.",
+        "example": "<Card title=\"Recent runs\" action={<Link variant=\"standalone\" href=\"/runs\">All runs</Link>}><Table aria-label=\"Recent runs\">…</Table></Card>"
+      },
+      "variants": {
+        "intent": {
+          "default": {
+            "use": "every card that is not a danger zone"
+          },
+          "danger": {
+            "use": "a card of irreversible actions — delete the workspace, transfer ownership. The rule turns red; the title must still say what is at stake"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "a titled card renders a <section> named by its heading, so it is a landmark a screen reader can jump to",
+          "an untitled card renders a <div>, never an unnamed <section>",
+          "the danger intent is a border colour only, so the meaning stays in the words"
+        ],
+        "requires": [
+          "the right `headingLevel` for where the card sits in the page outline",
+          "`isRegion={false}` when the card's only content is a landmark named by the same words, such as a Table labelled by the card's title"
+        ],
+        "notes": [
+          "`headingLevel` takes 2-6 and defaults to 2. It is a number rather than a variant because it is an outline decision, not a visual one: the title looks the same at every level.",
+          "`description` renders only under a `title`. An untitled card has no title row to put it in."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a heading passed in `children` instead of `title`",
+          "why": "the card does not become a named region, and the title row loses its layout for `description` and `action`"
+        },
+        {
+          "dont": "several buttons in `action`",
+          "why": "the title row wraps and the card reads as a toolbar; `action` is for one control — put the rest in the body"
+        },
+        {
+          "dont": "relying on `intent=\"danger\"` alone to warn",
+          "why": "a red border is not read aloud and is easy to miss; the title and the button labels must say what cannot be undone"
+        },
+        {
+          "dont": "cards nested inside cards",
+          "why": "border inside border reads as a mistake; group the inner content with a heading or a Divider instead"
+        }
+      ],
+      "stylesheet": "src/styles/card.css",
+      "tokens": [
+        "--border-error-subtle",
+        "--border-subtle",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-semibold",
+        "--radius-lg",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-8",
+        "--surface-default",
+        "--text-default",
+        "--text-secondary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-h6",
+        "--type-h6-line-height"
+      ],
+      "props": {
+        "title": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The card's heading. With a title the card is a `<section>` named by it;\nwithout one it is a plain surface — a `<div>`, for skeletons and for\ncontent that already has its own heading."
+        },
+        "headingLevel": {
+          "type": "CardHeadingLevel | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Heading element for the title. Defaults to `h2`: most cards are the\nfirst level of section under the page's `h1`. The outline is the page's\ndecision, so it is a prop, not a constant."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "One line under the title — what the card holds or when changes apply."
+        },
+        "action": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "One control at the end of the title row: a standalone Link (\"All runs\")\nor a small Button. More than one belongs in the body."
+        },
+        "intent": {
+          "type": "CardIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "`danger` for a card of irreversible actions — the danger zone.",
+          "values": [
+            "default",
+            "danger"
+          ]
+        },
+        "isRegion": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether a titled card is a landmark. Defaults to `true`. Set `false`\nwhen the card's only content is itself a landmark named by the same\nwords — a Table's scroll region — or the page gets two regions with one\nname. The heading still renders; only the `<section>` becomes a `<div>`."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 7,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
     "ChartLegend": {
       "name": "ChartLegend",
       "source": "src/components/Chart.tsx",
@@ -3076,8 +3230,8 @@
           "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
           "values": [
             "neutral",
-            "brand",
-            "danger"
+            "danger",
+            "brand"
           ],
           "default": "brand"
         },
@@ -3676,6 +3830,184 @@
         "other": 0
       }
     },
+    "CommandPalette": {
+      "name": "CommandPalette",
+      "source": "src/components/CommandPalette.tsx",
+      "propsType": "CommandPaletteProps",
+      "description": "CommandPalette — every action in the product, one search away.\n\n⌘K (Ctrl+K elsewhere) opens it from anywhere; typing filters; Enter runs.\nMount it once, near the root, and hand it every command the product has.\n\nWHY NOT A MODAL WITH A COMBOBOX IN IT\n\nA Combobox's list is a popover that opens and closes on its own rules, and\nit SELECTS a value that stays selected. A palette's list is always open and\neach row is RUN, once, and the palette goes away. The ARIA shape is the same\n— a combobox driving a listbox through `aria-activedescendant` — so this\nuses it, without the parts of Combobox that exist for choosing a value.\n\nNOT A NAVIGATION MENU\n\nEverything in the palette must also be reachable without it. It is a faster\nroute for people who know what they want, and a shortcut nobody told you\nabout is not a route at all.",
+      "import": "import { CommandPalette } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.81.0",
+      "summary": "A searchable list of every command in the product, opened with ⌘K / Ctrl+K from anywhere, that runs the chosen command and closes.",
+      "useWhen": [
+        "the product has more actions and destinations than its navigation shows at once",
+        "people who use it daily want to reach anything without the pointer",
+        "mounted once, near the root, with every command the product has"
+      ],
+      "useInstead": [
+        {
+          "when": "the user picks a value that stays chosen — an assignee, a country",
+          "use": "Combobox",
+          "why": "a combobox selects and keeps a value in a form; a palette runs a command once and goes away"
+        },
+        {
+          "when": "a few actions belong to one object — a row's Edit, Duplicate, Delete",
+          "use": "Menu",
+          "why": "those actions belong beside the thing they act on, where people look for them"
+        },
+        {
+          "when": "the search is over records — agents, runs — shown as a page of results",
+          "use": "Input",
+          "why": "a filtered table is a page with its own URL, and a palette is gone the moment it is used"
+        }
+      ],
+      "a11y": {
+        "role": "dialog",
+        "guarantees": [
+          "a modal dialog named by `label`: focus is trapped, the page behind is hidden from assistive tech, Escape and a scrim click close it, and focus returns to what had it",
+          "focus stays in the search field, a combobox whose always-open listbox is driven by aria-activedescendant — typing and choosing never compete for focus",
+          "sections are role=group, named by their heading",
+          "disabled commands are listed with aria-disabled, skipped by the arrow keys, and do nothing on click",
+          "the number of matches is announced through a polite live region as the query changes",
+          "`onAction` runs after the palette has closed and handed focus back, so an action that moves focus keeps it",
+          "shortcut hints are read as key names — \"Command Shift N\" — not as symbols"
+        ],
+        "requires": [
+          "every command also reachable without the palette — it is a faster route, never the only one",
+          "a visible way to open it for people who do not know the shortcut, such as a header button showing the keys"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "showing a `shortcut` on a command without binding that shortcut yourself",
+          "why": "the palette displays a command's shortcut and does not listen for it; a hint for a key that does nothing is worse than no hint"
+        },
+        {
+          "dont": "moving focus from inside a command's handler by running it before closing, or wrapping onAction to close the palette first",
+          "why": "onAction already runs after close. While the dialog is mounted its focus scope pulls focus back to the search field"
+        },
+        {
+          "dont": "rendering <CommandPalette> only when a state flag is true",
+          "do": "mount it always and drive `isOpen`, or let it open itself on the shortcut",
+          "why": "unmounted, it cannot listen for ⌘K"
+        },
+        {
+          "dont": "labels that are nouns — \"Agents\", \"Dark mode\"",
+          "do": "start with a verb — \"Go to Agents\", \"Switch to dark theme\"",
+          "why": "a row says what pressing Enter will do; a noun leaves the reader guessing whether it opens, toggles or deletes"
+        },
+        {
+          "dont": "two palettes on one page, or a second listener for ⌘K",
+          "why": "both toggle on the same key press and cancel each other out"
+        }
+      ],
+      "slots": {
+        "emptyLabel": {
+          "expects": "what to show when nothing matches"
+        }
+      },
+      "stylesheet": "src/styles/command-palette.css",
+      "tokens": [
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--icon-size-md",
+        "--icon-size-sm",
+        "--ion-shadow-shadow-xl",
+        "--radius-sm",
+        "--radius-xl",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-32",
+        "--spacing-4",
+        "--spacing-40",
+        "--spacing-48",
+        "--spacing-8",
+        "--spacing-96",
+        "--surface-hover",
+        "--surface-overlay",
+        "--surface-scrim",
+        "--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",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "commands": {
+          "type": "readonly CommandPaletteItem[]",
+          "required": true,
+          "origin": "own",
+          "description": "Every command. Filtering happens here, against what is typed."
+        },
+        "onAction": {
+          "type": "(id: string) => void",
+          "required": true,
+          "origin": "own",
+          "description": "Runs the chosen command. Called AFTER the palette has closed and handed\nfocus back, so an action that moves focus — to a search field, into a\nform — keeps it."
+        },
+        "isOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "defaultOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onOpenChange": {
+          "type": "((isOpen: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "openShortcut": {
+          "type": "string | null | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The shortcut that opens it from anywhere on the page, and closes it again.\nDefaults to `mod+k` — ⌘K on a Mac, Ctrl+K elsewhere. `null` turns it off,\nfor a page that opens the palette some other way."
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Names the dialog and the search field."
+        },
+        "placeholder": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "emptyLabel": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in place of the list when nothing matches."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 10,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
     "ConfidenceIndicator": {
       "name": "ConfidenceIndicator",
       "source": "src/components/ConfidenceIndicator.tsx",
@@ -3822,8 +4154,8 @@
         },
         {
           "when": "a time of day is part of the value",
-          "use": "Input",
-          "why": "this picker is fixed to day granularity; a time picker is not yet in this system"
+          "use": "TimeField",
+          "why": "this picker is fixed to day granularity; put a TimeField beside it — the two share one box and one set of states"
         }
       ],
       "variants": {
@@ -6131,32 +6463,129 @@
         "other": 0
       }
     },
-    "Link": {
-      "name": "Link",
-      "source": "src/components/Link.tsx",
-      "propsType": "LinkProps",
-      "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
-      "import": "import { Link } from 'ionbase-ui';",
+    "Kbd": {
+      "name": "Kbd",
+      "source": "src/components/Kbd.tsx",
+      "propsType": "KbdProps",
+      "description": "Kbd — a key, or a keyboard shortcut, as printed on the keyboard.\n\n`<kbd>` is the element HTML has for this, and a combination is a `<kbd>` of\n`<kbd>`s — the spec's own shape for \"press these together\".\n\nWHAT A SCREEN READER HEARS\n\nThe symbols do not survive being read aloud: VoiceOver says \"⌘\" as \"place of\ninterest sign\" in some voices and \"⇧\" as \"upwards white arrow\". So a\nshortcut's drawn keys are hidden and a visually hidden copy spells them out\n— \"Command K\", \"Control Shift P\".",
+      "import": "import { Kbd } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
+      "since": "0.81.0",
+      "summary": "A key, or a keyboard shortcut, drawn as keycaps in the reader's platform's own symbols and read aloud by name.",
       "useWhen": [
-        "the interaction takes the user to a different page, view or resource",
-        "the destination should support middle-click, open-in-new-tab and copy-link"
+        "telling people a shortcut exists — beside a button, in a tooltip, in a command palette row",
+        "instructions that name a key: \"press Esc to cancel\""
       ],
       "useInstead": [
         {
-          "when": "the interaction changes something rather than going somewhere",
-          "use": "Button",
-          "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
-        },
-        {
-          "when": "it is a primary navigation destination in a header or sidebar",
-          "use": "NavItem"
+          "when": "the text is code, a file name or a value",
+          "use": "render it directly",
+          "why": "Kbd means keys to press; `<code>` is the element for code"
         }
       ],
-      "variants": {
-        "variant": {
-          "inline": {
+      "a11y": {
+        "guarantees": [
+          "a combination is a <kbd> of <kbd>s, the HTML spec's shape for keys pressed together",
+          "the drawn symbols are hidden and a visually hidden copy spells the keys out — \"Command K\", \"Control Shift P\" — because ⌘ and ⇧ are read as symbol names or not at all",
+          "`mod` resolves to ⌘ on Apple platforms and Ctrl elsewhere; server rendering shows Ctrl and corrects after hydration without a mismatch"
+        ],
+        "requires": [
+          "the shortcut to be bound somewhere — Kbd shows a key, it does not listen for one"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "writing `ctrl+k` or `cmd+k` for the platform's command key",
+          "do": "write `mod+k`",
+          "why": "`ctrl` shows a Mac user a key they do not press for it; `cmd` shows everyone else a key they do not have"
+        },
+        {
+          "dont": "children like \"⌘K\" or \"Ctrl+K\"",
+          "do": "`shortcut=\"mod+k\"`",
+          "why": "hand-typed symbols are wrong on the other platform and are read aloud as symbol names"
+        },
+        {
+          "dont": "setting `platform`",
+          "why": "it overrides detection, so half the readers see the other platform's keys; it exists for docs that compare the two"
+        }
+      ],
+      "stylesheet": "src/styles/kbd.css",
+      "tokens": [
+        "--border-default",
+        "--border-width-default",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--radius-xs",
+        "--spacing-2",
+        "--spacing-20",
+        "--spacing-4",
+        "--surface-subtle",
+        "--text-secondary",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "shortcut": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "A whole shortcut, `+`-joined: `mod+k`, `mod+shift+p`, `esc`. `mod` is ⌘\non a Mac and Ctrl elsewhere, so write `mod` rather than guessing. Drawn as\none key per part, in the platform's order."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "One key, as printed: `K`, `Esc`, `/`. Use `shortcut` for a combination."
+        },
+        "platform": {
+          "type": "KbdPlatform | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Leave it out: the reader's platform is detected. Set it only to show a\nspecific platform's keys — a docs page comparing the two.",
+          "values": [
+            "mac",
+            "other"
+          ]
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "Link": {
+      "name": "Link",
+      "source": "src/components/Link.tsx",
+      "propsType": "LinkProps",
+      "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
+      "import": "import { Link } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
+      "useWhen": [
+        "the interaction takes the user to a different page, view or resource",
+        "the destination should support middle-click, open-in-new-tab and copy-link"
+      ],
+      "useInstead": [
+        {
+          "when": "the interaction changes something rather than going somewhere",
+          "use": "Button",
+          "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
+        },
+        {
+          "when": "it is a primary navigation destination in a header or sidebar",
+          "use": "NavItem"
+        }
+      ],
+      "variants": {
+        "variant": {
+          "inline": {
             "use": "the default — a link inside a paragraph. Underlined in every state, because a link in body copy must not rely on colour alone (WCAG 1.4.1)"
           },
           "standalone": {
@@ -9108,8 +9537,8 @@
           "origin": "own",
           "values": [
             "neutral",
-            "brand",
-            "danger"
+            "danger",
+            "brand"
           ]
         },
         "isDisabled": {
@@ -9318,8 +9747,8 @@
           "origin": "own",
           "values": [
             "neutral",
-            "brand",
-            "danger"
+            "danger",
+            "brand"
           ]
         },
         "isDisabled": {
@@ -11588,6 +12017,7 @@
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
+        "--icon-default",
         "--icon-interactive",
         "--icon-secondary",
         "--icon-size-sm",
@@ -11595,6 +12025,8 @@
         "--ion-duration-base",
         "--ion-ease-out",
         "--radius-md",
+        "--radius-xs",
+        "--ring-focus",
         "--spacing-16",
         "--spacing-20",
         "--spacing-6",
@@ -11616,8 +12048,8 @@
           "origin": "own",
           "description": "Matches Figma's `Density` variant on `Table Cell` / `Table Row`.",
           "values": [
-            "compact",
             "default",
+            "compact",
             "relaxed"
           ]
         },
@@ -11685,6 +12117,7 @@
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
+        "--icon-default",
         "--icon-interactive",
         "--icon-secondary",
         "--icon-size-sm",
@@ -11692,6 +12125,8 @@
         "--ion-duration-base",
         "--ion-ease-out",
         "--radius-md",
+        "--radius-xs",
+        "--ring-focus",
         "--spacing-16",
         "--spacing-20",
         "--spacing-6",
@@ -11765,6 +12200,17 @@
           "link": {
             "use": "recolours the content to `text/link` / `icon/primary` for a cell whose content navigates"
           }
+        },
+        "sortDirection": {
+          "ascending": {
+            "use": "the column the rows are sorted by, smallest or earliest first"
+          },
+          "descending": {
+            "use": "the column the rows are sorted by, largest or newest first"
+          },
+          "none": {
+            "use": "a column that can be sorted but is not the current sort — it shows the neutral indicator"
+          }
         }
       },
       "slots": {
@@ -11783,10 +12229,15 @@
       "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"
+          "`header` decides the element directly rather than a `type` prop that could disagree with where the cell sits",
+          "a sortable header renders a real <button> inside the <th>, so it is focusable and answers Enter and Space, and the header keeps its column-header role",
+          "`aria-sort` is set on the sorted header only, never `none` on the rest"
         ],
         "requires": [
           "`scope=\"col\"` on header cells — inferred inside TableHead, but explicit for a header rendered outside it"
+        ],
+        "notes": [
+          "`useTableSort` returns `sortDirection` and `onSort` for each column. The table never reorders rows itself: they may be one page of a server's thousands."
         ]
       },
       "antiPatterns": [
@@ -11801,6 +12252,14 @@
         {
           "dont": "`showDivider` on every cell",
           "why": "it is a column rule, not a row rule — on every cell it becomes a grid"
+        },
+        {
+          "dont": "`onSort` on a header without `sortDirection`",
+          "why": "the cell stays plain text, so nothing can be clicked; `sortDirection` is what makes it a sort control — pass `none` for an unsorted column"
+        },
+        {
+          "dont": "`trailingIcon` on a sortable header",
+          "why": "the sort indicator takes the trailing slot; the icon is not rendered"
         }
       ],
       "stylesheet": "src/styles/table.css",
@@ -11812,6 +12271,7 @@
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
+        "--icon-default",
         "--icon-interactive",
         "--icon-secondary",
         "--icon-size-sm",
@@ -11819,6 +12279,8 @@
         "--ion-duration-base",
         "--ion-ease-out",
         "--radius-md",
+        "--radius-xs",
+        "--ring-focus",
         "--spacing-16",
         "--spacing-20",
         "--spacing-6",
@@ -11863,13 +12325,13 @@
           ]
         },
         "variant": {
-          "type": "\"link\" | \"default\" | undefined",
+          "type": "\"default\" | \"link\" | undefined",
           "required": false,
           "origin": "own",
           "description": "Figma's `Type=Link` — recolours the content to `text/link` /\n`icon/primary` rather than the body defaults.",
           "values": [
-            "link",
-            "default"
+            "default",
+            "link"
           ]
         },
         "showDivider": {
@@ -11889,6 +12351,23 @@
           "required": false,
           "origin": "own"
         },
+        "sortDirection": {
+          "type": "TableSortDirection | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Makes a header cell a sort control. Set it on every sortable column:\n`ascending` or `descending` on the one the rows are sorted by, `none` on\nthe rest. Header cells only — ignored on a body cell. `useTableSort`\nreturns this and `onSort` for each column.",
+          "values": [
+            "none",
+            "ascending",
+            "descending"
+          ]
+        },
+        "onSort": {
+          "type": "(() => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Called when the header is activated. The table does not reorder rows:\nsorting is the caller's, since only it knows whether the data is local\nor paged from a server."
+        },
         "children": {
           "type": "React.ReactNode",
           "required": false,
@@ -11896,7 +12375,7 @@
         }
       },
       "propCounts": {
-        "own": 8,
+        "own": 10,
         "aria": 0,
         "dom": 284,
         "other": 0
@@ -11955,6 +12434,7 @@
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
+        "--icon-default",
         "--icon-interactive",
         "--icon-secondary",
         "--icon-size-sm",
@@ -11962,6 +12442,8 @@
         "--ion-duration-base",
         "--ion-ease-out",
         "--radius-md",
+        "--radius-xs",
+        "--ring-focus",
         "--spacing-16",
         "--spacing-20",
         "--spacing-6",
@@ -12044,6 +12526,7 @@
         "--font-family-sans",
         "--font-weight-medium",
         "--font-weight-regular",
+        "--icon-default",
         "--icon-interactive",
         "--icon-secondary",
         "--icon-size-sm",
@@ -12051,6 +12534,8 @@
         "--ion-duration-base",
         "--ion-ease-out",
         "--radius-md",
+        "--radius-xs",
+        "--ring-focus",
         "--spacing-16",
         "--spacing-20",
         "--spacing-6",
@@ -12361,6 +12846,271 @@
         "other": 4
       }
     },
+    "Tag": {
+      "name": "Tag",
+      "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 { Tag } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.79.0",
+      "summary": "One tag in a TagGroup. Re-exported from react-stately's collection Item — `key` identifies it, children are its label.",
+      "useWhen": [
+        "a child of TagGroup — it is not usable anywhere else"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a status label on its own",
+          "use": "Badge"
+        }
+      ],
+      "composition": {
+        "order": [
+          "TagGroup",
+          "Tag"
+        ],
+        "note": "A collection item, not a rendered component: TagGroup 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 `textValue` are the collection's API.",
+        "example": "<Tag key=\"team:finance\">Team: Finance</Tag>"
+      },
+      "a11y": {
+        "guarantees": [
+          "the row, cell and remove-button roles and names are supplied by TagGroup, not by this element"
+        ],
+        "requires": [
+          "a stable `key` — it is what `onRemove` hands back",
+          "`textValue` when the label is not plain text, so type-ahead and the remove button's name have words to use"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "array indexes as keys in a list that shrinks",
+          "why": "removing the first tag renumbers the rest, and the next removal drops the wrong one"
+        },
+        {
+          "dont": "wrapping Tag in a <div> or a fragment inside TagGroup",
+          "why": "TagGroup reads the collection from its direct children; a wrapper makes the tag invisible to it"
+        }
+      ],
+      "stylesheet": null,
+      "tokens": [],
+      "props": {},
+      "propCounts": {
+        "own": 0,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "TagGroup": {
+      "name": "TagGroup",
+      "source": "src/components/TagGroup.tsx",
+      "propsType": "TagGroupProps",
+      "description": "TagGroup — labels a person applied and can take away: active filters, the\nlabels on a record, the recipients of a message.\n\nNOT A BADGE\n\nA Badge reports a state the system decided — Failing, Paid. A Tag is a\nchoice someone made, which is why it is removable and why it is neutral:\ncolouring tags by intent would make \"Status: Failing\" as a filter look like\nthe agent is failing.\n\nWHAT REACT ARIA GIVES IT\n\n`useTagGroup` makes the group one tab stop with arrow keys between tags, a\nremove button per tag named \"Remove <tag>\", and Delete / Backspace to remove\nthe focused one. When a tag goes, focus moves to its neighbour. The one case\nReact Aria leaves open is the last tag: focus would fall to <body>, so the\ngroup takes it instead and reads out `emptyLabel`.\n\nNo selection: a chip that toggles on and off is a SegmentedControl or a\nCheckbox, which already say \"selected\" the way a screen reader expects.",
+      "import": "import { TagGroup } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.79.0",
+      "summary": "Labels a person applied and can take away: active filters, the labels on a record, recipients. Neutral and removable, unlike Badge.",
+      "useWhen": [
+        "showing which filters are applied, each removable on its own",
+        "the labels or categories someone attached to a record",
+        "a set of chosen values — recipients, assignees — shown after they are picked"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a status the system reports — Failing, Paid, Draft",
+          "use": "Badge"
+        },
+        {
+          "when": "the chips toggle on and off rather than being removed",
+          "use": "SegmentedControl"
+        },
+        {
+          "when": "several options can be switched on at once from a fixed list",
+          "use": "Checkbox"
+        }
+      ],
+      "composition": {
+        "order": [
+          "TagGroup",
+          "Tag"
+        ],
+        "note": "Tag is react-stately's collection Item: `key` identifies it and is what `onRemove` hands back, children are its label. Pass `items` and a render function for a list that changes.",
+        "example": "<TagGroup label=\"Active filters\" onRemove={(keys) => drop(keys)}><Tag key=\"status\">Status: Failing</Tag><Tag key=\"team\">Team: Finance</Tag></TagGroup>"
+      },
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "the default — filter rows, table toolbars, dense record headers"
+          },
+          "md": {
+            "use": "a group that is the main content of its area, or sits beside md controls"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the group is one tab stop; arrow keys move between tags",
+          "each remove button is named \"Remove\" plus the tag's label, so a screen reader hears which one",
+          "Delete or Backspace on a focused tag removes it, and focus moves to its neighbour",
+          "removing the last tag moves focus to the group, which reads `emptyLabel`, instead of dropping it to the page"
+        ],
+        "requires": [
+          "a `label` or `aria-label` — it names the group, so \"Remove Finance\" is heard as a filter being removed",
+          "`textValue` on a Tag whose children are not plain text",
+          "`onRemove` to drop the keys from your own list; the group removes nothing itself"
+        ],
+        "notes": [
+          "No selection. A chip that toggles is a SegmentedControl or a Checkbox, which already announce \"selected\" the way screen readers expect."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "using a TagGroup for statuses",
+          "why": "tags are neutral and removable; a status is neither — use Badge"
+        },
+        {
+          "dont": "`onRemove` that does not remove the tag",
+          "why": "the button says \"Remove\", focus moves on, and the tag is still there — the one thing the control promised did not happen"
+        },
+        {
+          "dont": "a filter row with no way to clear everything at once",
+          "why": "removing six filters one by one is six targets; pair the group with a \"Clear filters\" Button"
+        }
+      ],
+      "stylesheet": "src/styles/tag-group.css",
+      "tokens": [
+        "--border-disabled",
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-default",
+        "--icon-disabled",
+        "--icon-secondary",
+        "--icon-size-2xs",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-md",
+        "--radius-sm",
+        "--radius-xs",
+        "--ring-focus",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-disabled",
+        "--surface-hover",
+        "--surface-subtle",
+        "--text-default",
+        "--text-disabled",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "onRemove": {
+          "type": "((keys: Set<Key>) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Called with the keys of the tags to remove — from a tag's × button, or\nDelete / Backspace on a focused tag. Pass it and every tag shows a remove\nbutton; leave it out and the tags are read-only labels. The group does\nnot remove anything itself: drop the keys from your own list."
+        },
+        "size": {
+          "type": "TagGroupSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Size`. Set once here, so every tag in a group matches.",
+          "values": [
+            "sm",
+            "md"
+          ],
+          "default": "sm"
+        },
+        "emptyLabel": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in place of the tags when there are none — \"No filters applied\".\nWithout it an empty group renders nothing but its label."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+        },
+        "aria-describedby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that describes the object."
+        },
+        "aria-details": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+        },
+        "aria-label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Defines a string value that labels the current element."
+        },
+        "aria-labelledby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that labels the current element."
+        },
+        "children": {
+          "type": "CollectionChildren<T>",
+          "required": true,
+          "origin": "aria",
+          "description": "The contents of the collection."
+        },
+        "description": {
+          "type": "ReactNode",
+          "required": false,
+          "origin": "aria",
+          "description": "A description for the field. Provides a hint such as specific requirements for what to choose."
+        },
+        "label": {
+          "type": "ReactNode",
+          "required": false,
+          "origin": "aria",
+          "description": "The content to display as the label."
+        },
+        "items": {
+          "type": "Iterable<T> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Item objects in the collection."
+        },
+        "disabledKeys": {
+          "type": "Iterable<Key> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise\ninteracted with."
+        }
+      },
+      "propCounts": {
+        "own": 4,
+        "aria": 10,
+        "dom": 0,
+        "other": 0
+      }
+    },
     "Textarea": {
       "name": "Textarea",
       "source": "src/components/Textarea.tsx",
@@ -12881,6 +13631,230 @@
         "other": 0
       }
     },
+    "TimeField": {
+      "name": "TimeField",
+      "source": "src/components/TimeField.tsx",
+      "propsType": "TimeFieldProps",
+      "description": "TimeField — a time of day, typed into segments.\n\nDatePicker's text half, for times: hour, minute and, where the locale uses\none, AM/PM — each a spinbutton that takes digits or arrow keys. The order,\nthe separator and the 12 or 24-hour clock come from the reader's locale, so\n\"2:30 PM\" and \"14:30\" are the same field and the same value.\n\nWHY NOT A TEXT INPUT OR `<input type=\"time\">`\n\nFree text means guessing whether \"2:30\" is afternoon. The native control\ncannot be styled to match the other fields, and Safari's has no picker at\nall. Segments cannot hold a time that does not exist, and every browser\ndraws them the same.\n\nNo dropdown of times. A list of 96 quarter-hours is slower to scan than two\ndigits are to type, and it makes 09:07 impossible. Where only a few times\nare allowed, that is a Select, not a TimeField.",
+      "import": "import { TimeField } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.80.0",
+      "summary": "A time of day typed into hour, minute and AM/PM segments in the reader's own format, taking and returning a 24-hour HH:MM string.",
+      "useWhen": [
+        "the user sets a time of day — a schedule, a reminder, the start of a window",
+        "any minute is allowed, so a list of choices would be long or would leave times out",
+        "beside a DatePicker when the value is a date and a time; the two sit side by side and share one box"
+      ],
+      "useInstead": [
+        {
+          "when": "only a handful of times are allowed — delivery slots, office hours",
+          "use": "Select",
+          "why": "picking from four slots is a choice from a list, and a field that accepts any minute invites times the product will refuse"
+        },
+        {
+          "when": "the value is a duration — 30 minutes, 2 hours",
+          "use": "NumberInput",
+          "why": "a duration is an amount, not a time of day; 02:00 as a length reads as two in the morning"
+        },
+        {
+          "when": "the value is a calendar date",
+          "use": "DatePicker"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms, table filters"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "prominent single-field forms"
+          }
+        },
+        "granularity": {
+          "hour": {
+            "use": "on-the-hour schedules — the minute segment is not shown"
+          },
+          "minute": {
+            "use": "the default — almost every time of day a person sets"
+          },
+          "second": {
+            "use": "logs and precise triggers; the value becomes HH:MM:SS"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "each segment is a spinbutton that announces its own name, value and bounds — 'hour, 2, minimum 1, maximum 12' — and takes digits or arrow keys",
+          "each editable segment is its own tab stop, like DatePicker and the native time input; the separator is not",
+          "the 12 or 24-hour clock, the separator and the AM/PM wording come from the reader's locale, so '2:30 PM' and '14:30' are the same field and the same value",
+          "the segments sit in one labelled group, so the name is announced once on entry",
+          "a time that does not exist cannot be typed",
+          "a time outside `minValue`/`maxValue` turns the field invalid and names the bound in the reader's own format, without `isInvalid` — the value is kept, not silently clamped"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when no visible label is rendered",
+          "a `description` saying which timezone the time is in, whenever the reader could be in a different one from the thing being scheduled"
+        ],
+        "notes": [
+          "`value` is a wall-clock time with no date and no zone. Keep the timezone as its own field or setting; a time pinned to a `Date` drifts an hour at every daylight-saving change.",
+          "The clock icon is decorative. There is no dropdown of times: two digits are faster to type than 96 quarter-hours are to scan, and a list makes 09:07 impossible."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "passing a Date, a timestamp or a locale-formatted string such as \"2:30 PM\" as `value`",
+          "why": "the value is 24-hour HH:MM. A malformed value throws with the prop name rather than rendering an empty field"
+        },
+        {
+          "dont": "forcing `hourCycle={12}` for everyone",
+          "why": "a reader whose locale uses 24 hours has to translate every value, which is the misreading the segments exist to prevent. Leave it to the locale"
+        },
+        {
+          "dont": "a schedule time with no timezone anywhere on the form",
+          "why": "\"09:00\" is nine o'clock somewhere; if the reader and the workspace are in different zones, they will each assume their own"
+        },
+        {
+          "dont": "using `minValue` and `maxValue` for a window that crosses midnight",
+          "why": "22:00 to 02:00 has a minimum later than its maximum, so every time is refused; validate the window yourself and set `isInvalid`"
+        }
+      ],
+      "stylesheet": "src/styles/time-field.css",
+      "tokens": [],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Field label. Required for a usable control — see `a11y.requires`."
+        },
+        "aria-label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Names the field when there is no visible `label`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Helper text below the field — \"In the workspace's timezone\"."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Replaces the helper text when `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isReadOnly": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "size": {
+          "type": "TimeFieldSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "value": {
+          "type": "string | null | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The time as `HH:MM` (or `HH:MM:SS`), 24-hour, whatever the reader sees.\n`null` means no time is chosen. A wall-clock reading — no date, no\ntimezone. A malformed value throws rather than rendering an empty field."
+        },
+        "defaultValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The initial time, for an uncontrolled field."
+        },
+        "onChange": {
+          "type": "((value: IsoTime | null) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Fires with `HH:MM` (`HH:MM:SS` at second granularity), or `null` when cleared."
+        },
+        "minValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Earliest allowed time, `HH:MM`. Later is not wrapped past midnight."
+        },
+        "maxValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Latest allowed time, `HH:MM`."
+        },
+        "granularity": {
+          "type": "TimeFieldGranularity | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Defaults to `minute`. `second` adds a seconds segment and value.",
+          "values": [
+            "hour",
+            "minute",
+            "second"
+          ]
+        },
+        "hourCycle": {
+          "type": "12 | 24 | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "12 or 24-hour display. Leave it out: the reader's locale already knows,\nand forcing 12-hour on a 24-hour reader is the misreading this field\nexists to prevent. The value is 24-hour either way."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Posts the value under this name, for an uncontrolled form."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 20,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
     "Toast": {
       "name": "Toast",
       "source": "src/components/Toast.tsx",
@@ -13357,8 +14331,8 @@
           "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
           "values": [
             "neutral",
-            "brand",
-            "danger"
+            "danger",
+            "brand"
           ],
           "default": "brand"
         },