ionbase-ui 0.76.0 → 0.81.0

package/dist/meta/index.json

@@ -1,9 +1,10 @@
 {
   "package": "ionbase-ui",
-  "version": "0.76.0",
+  "version": "0.81.0",
   "usage": "Pick a component here, then read dist/meta/<Name>.json for its full contract.",
   "hooks": [
     "useAgentRun",
+    "useTableSort",
     "useToast"
   ],
   "helpers": [
@@ -248,6 +249,18 @@
       "detail": "dist/meta/Button.json",
       "hasIntent": true
     },
+    "Card": {
+      "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.",
+      "status": "stable",
+      "variants": {
+        "intent": [
+          "default",
+          "danger"
+        ]
+      },
+      "detail": "dist/meta/Card.json",
+      "hasIntent": true
+    },
     "ChartLegend": {
       "summary": "Which colour is which series, for a chart drawn with visx. The swatch reads the same token as the series.",
       "status": "stable",
@@ -278,8 +291,8 @@
         ],
         "intent": [
           "neutral",
-          "brand",
-          "danger"
+          "danger",
+          "brand"
         ]
       },
       "detail": "dist/meta/Checkbox.json",
@@ -324,6 +337,13 @@
       "detail": "dist/meta/Combobox.json",
       "hasIntent": true
     },
+    "CommandPalette": {
+      "summary": "A searchable list of every command in the product, opened with ⌘K / Ctrl+K from anywhere, that runs the chosen command and closes.",
+      "status": "stable",
+      "variants": {},
+      "detail": "dist/meta/CommandPalette.json",
+      "hasIntent": true
+    },
     "ConfidenceIndicator": {
       "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
       "status": "stable",
@@ -477,6 +497,18 @@
       "detail": "dist/meta/Input.json",
       "hasIntent": true
     },
+    "Kbd": {
+      "summary": "A key, or a keyboard shortcut, drawn as keycaps in the reader's platform's own symbols and read aloud by name.",
+      "status": "stable",
+      "variants": {
+        "platform": [
+          "mac",
+          "other"
+        ]
+      },
+      "detail": "dist/meta/Kbd.json",
+      "hasIntent": true
+    },
     "Link": {
       "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
       "status": "stable",
@@ -667,8 +699,8 @@
         ],
         "intent": [
           "neutral",
-          "brand",
-          "danger"
+          "danger",
+          "brand"
         ]
       },
       "detail": "dist/meta/Radio.json",
@@ -685,8 +717,8 @@
         ],
         "intent": [
           "neutral",
-          "brand",
-          "danger"
+          "danger",
+          "brand"
         ]
       },
       "detail": "dist/meta/RadioGroup.json",
@@ -859,8 +891,8 @@
       "status": "stable",
       "variants": {
         "density": [
-          "compact",
           "default",
+          "compact",
           "relaxed"
         ]
       },
@@ -890,8 +922,13 @@
           "trailing"
         ],
         "variant": [
-          "link",
-          "default"
+          "default",
+          "link"
+        ],
+        "sortDirection": [
+          "none",
+          "ascending",
+          "descending"
         ]
       },
       "detail": "dist/meta/TableCell.json",
@@ -932,6 +969,25 @@
       "detail": "dist/meta/Tabs.json",
       "hasIntent": true
     },
+    "Tag": {
+      "summary": "One tag in a TagGroup. Re-exported from react-stately's collection Item — `key` identifies it, children are its label.",
+      "status": "stable",
+      "variants": {},
+      "detail": "dist/meta/Tag.json",
+      "hasIntent": true
+    },
+    "TagGroup": {
+      "summary": "Labels a person applied and can take away: active filters, the labels on a record, recipients. Neutral and removable, unlike Badge.",
+      "status": "stable",
+      "variants": {
+        "size": [
+          "sm",
+          "md"
+        ]
+      },
+      "detail": "dist/meta/TagGroup.json",
+      "hasIntent": true
+    },
     "Textarea": {
       "summary": "A multi-line text field. Every size and state is Input's; it wraps and it resizes vertically.",
       "status": "stable",
@@ -953,6 +1009,24 @@
       "detail": "dist/meta/Textarea.json",
       "hasIntent": true
     },
+    "TimeField": {
+      "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.",
+      "status": "stable",
+      "variants": {
+        "size": [
+          "sm",
+          "md",
+          "lg"
+        ],
+        "granularity": [
+          "hour",
+          "minute",
+          "second"
+        ]
+      },
+      "detail": "dist/meta/TimeField.json",
+      "hasIntent": true
+    },
     "Toast": {
       "summary": "A transient notification on neutral chrome. Intent is carried by the icon, not by a tinted panel.",
       "status": "stable",
@@ -994,8 +1068,8 @@
         ],
         "intent": [
           "neutral",
-          "brand",
-          "danger"
+          "danger",
+          "brand"
         ]
       },
       "detail": "dist/meta/Toggle.json",

package/dist/meta/patterns/DataTable.json

@@ -15,14 +15,21 @@
     "Button",
     "Badge",
     "Alert",
-    "Input"
+    "Input",
+    "TagGroup"
   ],
   "structure": [
     "A toolbar above the table: a search Input, filter controls, and the bulk-action Buttons that appear once something is selected.",
+    "Under the toolbar, once any filter is applied: a TagGroup of the active filters, each removable on its own, beside a Clear all Button. When the last one goes the row goes with it, so move focus to the search Input.",
     "Table with a TableHead whose first cell carries the select-all Checkbox, and a TableBody whose rows each carry their own.",
+    "Sortable columns: every header that sorts gets `sortDirection` — the current direction on the sorted column, `none` on the others — so each shows it can be sorted before anyone tries.",
     "One region below the table for pagination or a load-more Button.",
     "The table region is replaced — not overlaid — by the empty, loading and error states."
   ],
+  "drivenBy": {
+    "hook": "useTableSort",
+    "note": "It holds which column the rows are sorted by and which way, and `sortProps(column)` gives each sortable header TableCell its `sortDirection` and `onSort`. Choosing a new column sorts it in its `firstDirection` (ascending unless set — pass `descending` for dates and amounts); choosing it again reverses it. It does not reorder rows: sort them yourself from `sort`, or send it to the server when the table is paged. Only the sorted column gets `aria-sort`."
+  },
   "states": {
     "loading": {
       "must": "Render the table's header row and a fixed number of skeleton rows, keeping the column widths.",
@@ -56,7 +63,9 @@
     "TableCell": [
       "scope",
       "align",
-      "variant"
+      "variant",
+      "sortDirection",
+      "onSort"
     ],
     "Checkbox": [
       "isIndeterminate",
@@ -73,6 +82,11 @@
     ],
     "Input": [
       "leadingIcon"
+    ],
+    "TagGroup": [
+      "label",
+      "items",
+      "onRemove"
     ]
   },
   "variantsUsed": {
@@ -99,7 +113,8 @@
       "`aria-label` on Table — it names the scroll region, which is keyboard reachable",
       "`scope=\"col\"` on every header cell",
       "an `aria-label` on every row-selection Checkbox, and `isIndeterminate` on the select-all when the selection is partial",
-      "a live region announcing the row count after a filter or search changes it — otherwise a screen-reader user has no idea the table changed"
+      "a live region announcing the row count after a filter or search changes it — otherwise a screen-reader user has no idea the table changed",
+      "a sortable header's label is its accessible name — the button inside the <th> reads the column name, and `aria-sort` on the sorted <th> says the direction"
     ],
     "notes": [
       "Bulk-action Buttons appearing on selection is a change of available actions, not just of styling. Announce it."
@@ -128,6 +143,15 @@
     {
       "dont": "wrapping Table in your own scroll container",
       "why": "Table already owns one and makes it keyboard reachable; a second is unreachable"
+    },
+    {
+      "dont": "a sortable column with no indicator until it is clicked",
+      "do": "`sortDirection=\"none\"` on every sortable header, so the neutral arrows show which columns sort",
+      "why": "a header that sorts but looks like plain text is only found by accident"
+    },
+    {
+      "dont": "sorting only the current page of a paged table",
+      "why": "the reader sees \"A–Z\" and takes it as the whole list; send the sort to the server, which knows every row"
     }
   ]
 }

package/dist/meta/patterns/PageShell.json

@@ -16,14 +16,17 @@
     "Avatar",
     "Button",
     "Divider",
-    "ToastProvider"
+    "ToastProvider",
+    "CommandPalette",
+    "Kbd"
   ],
   "structure": [
     "Header at the top with the brand in `brand`, primary navigation in `center` and account actions in `end`.",
     "One <main> content region, named, holding the page's own heading as its h1.",
     "ToastProvider mounted once around the whole shell, not per route.",
     "Breadcrumbs, when present, sit inside <main> above the h1 — they describe where the content is, not where the chrome is.",
-    "When navigation is hierarchical or longer than a header row holds, a Sidebar replaces the NavItems in Header's `center`: Header keeps the brand and account actions, and the Sidebar sits beside <main> as the primary navigation. Below the tablet breakpoint the same Sidebar moves into a Drawer opened by Header's own toggle with `menuType=\"dialog\"` — one copy, not two, and one menu button."
+    "When navigation is hierarchical or longer than a header row holds, a Sidebar replaces the NavItems in Header's `center`: Header keeps the brand and account actions, and the Sidebar sits beside <main> as the primary navigation. Below the tablet breakpoint the same Sidebar moves into a Drawer opened by Header's own toggle with `menuType=\"dialog\"` — one copy, not two, and one menu button.",
+    "A CommandPalette, when the product has one, is mounted once inside the shell beside ToastProvider, not per route. Header's `end` carries a Search button showing <Kbd shortcut=\"mod+k\" /> — the visible door for anyone who does not know the shortcut, and the only one on a phone. Everything in the palette is also reachable from the navigation."
   ],
   "states": {
     "loading": {
@@ -89,6 +92,16 @@
     "LogoMark": [
       "size",
       "label"
+    ],
+    "CommandPalette": [
+      "commands",
+      "onAction",
+      "isOpen",
+      "onOpenChange",
+      "label"
+    ],
+    "Kbd": [
+      "shortcut"
     ]
   },
   "variantsUsed": {

package/dist/meta/patterns/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.76.0",
+  "version": "0.81.0",
   "usage": "A pattern is a documented composition of components, not a component. Read one here, then read the contracts of what it composes.",
   "patterns": {
     "AgentRun": {
@@ -55,8 +55,10 @@
         "Button",
         "Badge",
         "Alert",
-        "Input"
+        "Input",
+        "TagGroup"
       ],
+      "drivenBy": "useTableSort",
       "states": [
         "loading",
         "empty",
@@ -137,7 +139,9 @@
         "Avatar",
         "Button",
         "Divider",
-        "ToastProvider"
+        "ToastProvider",
+        "CommandPalette",
+        "Kbd"
       ],
       "states": [
         "loading",

package/dist/styles/agent-activity.css

@@ -1,8 +1,10 @@
 /*
  * AgentActivity
  *
- * NOT DRAWN IN FIGMA. The rail-and-body layout is Alert's, one step down in
- * scale; colours are the status roles used everywhere else in the system.
+ * Drawn in Figma as `Agent Activity` (1162:246) and `Agent Activity Step`
+ * (1161:287), Status × Show Detail. The rail-and-body layout is Alert's, one
+ * step down in scale; colours are the status roles used everywhere else in
+ * the system.
  */
 .ion-agent-activity {
   display: flex;

package/dist/styles/approval-gate.css

@@ -1,9 +1,10 @@
 /*
  * ApprovalGate
  *
- * NOT DRAWN IN FIGMA. Structure is Alert's — icon rail, body, one variable per
- * colour slot — so that when Figma draws it, this file needs values changed
- * rather than rewriting. The action row borrows Button's ramp.
+ * Drawn in Figma as `Approval Gate` (1160:423), Risk × Status. Structure is
+ * Alert's — icon rail, body, one variable per colour slot — which is why
+ * drawing it needed values checked here rather than a rewrite. The action row
+ * borrows Button's ramp.
  *
  * RISK CHANGES EMPHASIS, NOT MEANING
  *

package/dist/styles/card.css

@@ -0,0 +1,75 @@
+/*
+ * Card
+ *
+ * Promoted from the demo app's `.demo-panel`, which nine screens used
+ * unchanged — the measurements are the ones StatTile already settled: a
+ * `surface/default` card with a `border/subtle` rule and the `lg` radius,
+ * 16 of padding, 12 between the parts.
+ *
+ *   title         the H6 text style, `text/default`
+ *   description   body-sm, `text/secondary`, 2 under the title
+ *   action        end of the title row; wraps under it below ~12rem of title
+ *   danger        the rule turns `border/error-subtle`; nothing else changes,
+ *                 so the warning stays in the card's words and not its colour
+ *
+ * The block carries its own background, so the contrast gate measures the
+ * title and description against the card rather than the page behind it.
+ */
+.ion-card {
+  display: grid;
+  align-content: start;
+  gap: var(--spacing-12);
+  min-width: 0;
+  padding: var(--spacing-16);
+  border: var(--border-width-default) solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  background-color: var(--surface-default);
+  color: var(--text-default);
+  font-family: var(--font-family-sans);
+}
+
+.ion-card--danger {
+  border-color: var(--border-error-subtle);
+}
+
+.ion-card__header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--spacing-8) var(--spacing-12);
+}
+
+/*
+ * A 12rem basis, not the title's own width: a long title shrinks and wraps
+ * beside the action, the way Figma's FILL heading does, and the action only
+ * drops to its own line when the card is too narrow for both.
+ */
+.ion-card__heading {
+  display: grid;
+  flex: 1 1 12rem;
+  gap: var(--spacing-2);
+  min-width: 0;
+}
+
+.ion-card__title {
+  margin: 0;
+  color: var(--text-default);
+  font-size: var(--type-h6);
+  line-height: var(--type-h6-line-height);
+  font-weight: var(--font-weight-semibold);
+}
+
+.ion-card__description {
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: var(--type-body-sm);
+  line-height: var(--type-body-sm-line-height);
+}
+
+.ion-card__action {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--spacing-8);
+}

package/dist/styles/citation.css

@@ -1,8 +1,10 @@
 /*
  * Citation
  *
- * NOT DRAWN IN FIGMA. The inline marker borrows Badge's pill geometry at the
- * smallest size; the footer list borrows the Table's row rhythm.
+ * Drawn in Figma as `Citation` (1167:247), `Citation List` (1168:246) and
+ * `Citation List Item` (1168:241). The inline marker borrows Badge's pill
+ * geometry at the smallest size; the footer list borrows the Table's row
+ * rhythm.
  */
 .ion-citation {
   display: inline-flex;

package/dist/styles/command-palette.css

@@ -0,0 +1,250 @@
+/*
+ * CommandPalette
+ *
+ * Drawn in Figma as `Command Palette` on its own page, with `Kbd`.
+ *
+ *   panel     640 wide, radius/xl, surface/overlay, 1px border/subtle,
+ *             shadow-xl — Modal's panel, without Modal's padding
+ *   search    52 tall, 16 across, icon/secondary search glyph, a
+ *             border/subtle rule below
+ *   list      8 around, capped at 22rem, then it scrolls
+ *   row       40 tall, 8 / 12, gap 12, radius/sm; the active row is
+ *             surface/hover — the same highlight Combobox uses
+ *   heading   caption, text/tertiary, 8 / 12
+ *   footer    caption, text/tertiary, a border/subtle rule above
+ *
+ * TOP-ANCHORED, NOT CENTRED
+ *
+ * Modal centres its panel. A palette's panel changes height with every
+ * keystroke, and a centred one would jump up and down under the reader's eyes
+ * while they type. Pinned 96 from the top, only its bottom edge moves.
+ */
+.ion-command-palette__scrim {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: var(--spacing-96) var(--spacing-16) var(--spacing-16);
+  background-color: var(--surface-scrim);
+}
+
+.ion-command-palette {
+  display: flex;
+  flex-direction: column;
+  width: 640px;
+  max-width: 100%;
+  max-height: 100%;
+  overflow: hidden;
+  background-color: var(--surface-overlay);
+  border: var(--border-width-default) solid var(--border-subtle);
+  border-radius: var(--radius-xl);
+  box-shadow: var(--ion-shadow-shadow-xl);
+  font-family: var(--font-family-sans);
+}
+
+.ion-command-palette:focus {
+  outline: none;
+}
+
+.ion-command-palette__search {
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--spacing-12);
+  height: calc(var(--spacing-48) + var(--spacing-4));
+  padding-inline: var(--spacing-16);
+  border-bottom: var(--border-width-default) solid var(--border-subtle);
+}
+
+.ion-command-palette__search-icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: var(--icon-secondary);
+}
+
+.ion-command-palette__search-icon svg {
+  width: var(--icon-size-md);
+  height: var(--icon-size-md);
+}
+
+/*
+ * No outline on the field: it is the only thing in the panel that ever has
+ * focus, focus lands there on open, and the caret already says so. A ring
+ * would sit inside a panel that is itself the focus context.
+ */
+.ion-command-palette__input {
+  flex: 1 1 auto;
+  min-width: 0;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--text-default);
+  font-family: inherit;
+  font-size: var(--type-body-lg);
+  line-height: var(--type-body-lg-line-height);
+  outline: none;
+}
+
+.ion-command-palette__input::placeholder {
+  color: var(--text-tertiary);
+}
+
+.ion-command-palette__list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+  max-height: 22rem;
+  padding: var(--spacing-8);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* An empty listbox still pads; collapse it so the empty message sits alone. */
+.ion-command-palette__list:empty {
+  display: none;
+}
+
+.ion-command-palette__section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+}
+
+.ion-command-palette__section + .ion-command-palette__section,
+.ion-command-palette__option + .ion-command-palette__section {
+  margin-top: var(--spacing-8);
+}
+
+.ion-command-palette__heading {
+  padding: var(--spacing-8) var(--spacing-12) var(--spacing-4);
+  color: var(--text-tertiary);
+  font-size: var(--type-caption);
+  line-height: var(--type-caption-line-height);
+  font-weight: var(--font-weight-medium);
+}
+
+/*
+ * The highlight is `data-focused` — Combobox's name for the same virtual
+ * focus — never :hover or :focus — focus stays in the
+ * field and the row is only ever the active descendant. Pointer movement sets
+ * the same attribute, so the mouse and the keyboard cannot highlight two rows.
+ */
+.ion-command-palette__option {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-12);
+  min-height: var(--spacing-40);
+  padding: var(--spacing-8) var(--spacing-12);
+  border-radius: var(--radius-sm);
+  background-color: var(--surface-overlay);
+  color: var(--text-default);
+  font-size: var(--type-body);
+  line-height: var(--type-body-line-height);
+  cursor: pointer;
+  user-select: none;
+}
+
+.ion-command-palette__option[data-focused='true'] {
+  background-color: var(--surface-hover);
+}
+
+.ion-command-palette__option[data-disabled='true'] {
+  color: var(--text-disabled);
+  cursor: default;
+}
+
+.ion-command-palette__icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: var(--icon-secondary);
+}
+
+.ion-command-palette__icon svg {
+  width: var(--icon-size-sm);
+  height: var(--icon-size-sm);
+}
+
+.ion-command-palette__option[data-disabled='true'] .ion-command-palette__icon {
+  color: var(--icon-disabled);
+}
+
+.ion-command-palette__text {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.ion-command-palette__label,
+.ion-command-palette__description {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ion-command-palette__description {
+  color: var(--text-tertiary);
+  font-size: var(--type-body-sm);
+  line-height: var(--type-body-sm-line-height);
+}
+
+.ion-command-palette__option[data-disabled='true']
+  .ion-command-palette__description {
+  color: var(--text-disabled);
+}
+
+.ion-command-palette__shortcut {
+  flex-shrink: 0;
+}
+
+.ion-command-palette__empty {
+  padding: var(--spacing-32) var(--spacing-16);
+  color: var(--text-tertiary);
+  font-size: var(--type-body);
+  line-height: var(--type-body-line-height);
+  text-align: center;
+}
+
+.ion-command-palette__footer {
+  display: flex;
+  flex-shrink: 0;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--spacing-16);
+  padding: var(--spacing-8) var(--spacing-16);
+  border-top: var(--border-width-default) solid var(--border-subtle);
+  color: var(--text-tertiary);
+  font-size: var(--type-caption);
+  line-height: var(--type-caption-line-height);
+}
+
+.ion-command-palette__hint {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-4);
+}
+
+/*
+ * A phone has no ⌘K and usually no arrow keys, so the hints are for nobody;
+ * the list gets the room instead.
+ */
+@media (width <= 40rem) {
+  .ion-command-palette__scrim {
+    padding-top: var(--spacing-16);
+  }
+
+  .ion-command-palette__footer {
+    display: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .ion-command-palette__option[data-focused='true'] {
+    outline: var(--border-width-thick) solid Highlight;
+    outline-offset: calc(-1 * var(--border-width-thick));
+  }
+}