ionbase-ui 0.76.0 → 0.81.0

package/dist/meta/CommandPalette.json

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

package/dist/meta/DatePicker.json

@@ -29,8 +29,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": {

package/dist/meta/Kbd.json

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

package/dist/meta/Radio.json

@@ -148,8 +148,8 @@
       "origin": "own",
       "values": [
         "neutral",
-        "brand",
-        "danger"
+        "danger",
+        "brand"
       ]
     },
     "isDisabled": {

package/dist/meta/RadioGroup.json

@@ -177,8 +177,8 @@
       "origin": "own",
       "values": [
         "neutral",
-        "brand",
-        "danger"
+        "danger",
+        "brand"
       ]
     },
     "isDisabled": {

package/dist/meta/Table.json

@@ -86,6 +86,7 @@
     "--font-family-sans",
     "--font-weight-medium",
     "--font-weight-regular",
+    "--icon-default",
     "--icon-interactive",
     "--icon-secondary",
     "--icon-size-sm",
@@ -93,6 +94,8 @@
     "--ion-duration-base",
     "--ion-ease-out",
     "--radius-md",
+    "--radius-xs",
+    "--ring-focus",
     "--spacing-16",
     "--spacing-20",
     "--spacing-6",
@@ -114,8 +117,8 @@
       "origin": "own",
       "description": "Matches Figma's `Density` variant on `Table Cell` / `Table Row`.",
       "values": [
-        "compact",
         "default",
+        "compact",
         "relaxed"
       ]
     },

package/dist/meta/TableBody.json

@@ -48,6 +48,7 @@
     "--font-family-sans",
     "--font-weight-medium",
     "--font-weight-regular",
+    "--icon-default",
     "--icon-interactive",
     "--icon-secondary",
     "--icon-size-sm",
@@ -55,6 +56,8 @@
     "--ion-duration-base",
     "--ion-ease-out",
     "--radius-md",
+    "--radius-xs",
+    "--ring-focus",
     "--spacing-16",
     "--spacing-20",
     "--spacing-6",

package/dist/meta/TableCell.json

@@ -49,6 +49,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": {
@@ -67,10 +78,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": [
@@ -85,6 +101,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",
@@ -96,6 +120,7 @@
     "--font-family-sans",
     "--font-weight-medium",
     "--font-weight-regular",
+    "--icon-default",
     "--icon-interactive",
     "--icon-secondary",
     "--icon-size-sm",
@@ -103,6 +128,8 @@
     "--ion-duration-base",
     "--ion-ease-out",
     "--radius-md",
+    "--radius-xs",
+    "--ring-focus",
     "--spacing-16",
     "--spacing-20",
     "--spacing-6",
@@ -147,13 +174,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": {
@@ -173,6 +200,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,
@@ -180,7 +224,7 @@
     }
   },
   "propCounts": {
-    "own": 8,
+    "own": 10,
     "aria": 0,
     "dom": 284,
     "other": 0

package/dist/meta/TableHead.json

@@ -51,6 +51,7 @@
     "--font-family-sans",
     "--font-weight-medium",
     "--font-weight-regular",
+    "--icon-default",
     "--icon-interactive",
     "--icon-secondary",
     "--icon-size-sm",
@@ -58,6 +59,8 @@
     "--ion-duration-base",
     "--ion-ease-out",
     "--radius-md",
+    "--radius-xs",
+    "--ring-focus",
     "--spacing-16",
     "--spacing-20",
     "--spacing-6",

package/dist/meta/TableRow.json

@@ -58,6 +58,7 @@
     "--font-family-sans",
     "--font-weight-medium",
     "--font-weight-regular",
+    "--icon-default",
     "--icon-interactive",
     "--icon-secondary",
     "--icon-size-sm",
@@ -65,6 +66,8 @@
     "--ion-duration-base",
     "--ion-ease-out",
     "--radius-md",
+    "--radius-xs",
+    "--ring-focus",
     "--spacing-16",
     "--spacing-20",
     "--spacing-6",

package/dist/meta/Tag.json

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