@stackone/malachite 2.101.1 → 2.103.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/COMPONENTS.md CHANGED
@@ -31,7 +31,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
31
31
  - **`Modal`** — Centred dialog over a scrim, with header slots (icon/title/subtitle/extra), a scrolling body and a pinned footer. Locks background scroll and dismisses on ESC, the close button, or a scrim click unless `closeOnOverlayClick` is off; `busy` suppresses the two pointer routes while a request is in flight and sets `aria-busy`, so a stray click cannot tear the dialog down mid-write — but never ESC, which is the only guaranteed keyboard exit from a focus trap and so always reaches `onClose`. ESC, the Tab focus trap and `aria-modal` all apply to the topmost overlay only, so these may be stacked — a dialog opened from a panel keeps Tab to itself and the panel stops claiming to be modal. The Tab trap follows focus into a malachite popup portaled out of the dialog’s own tree — a `MultiSelect` listbox or a `Popover` opened from the body — and traps Tab within that popup while it holds focus, so Tab walks and wraps that popup’s own stops rather than being yanked back to the dialog’s first control or escaping the dialog altogether. A `Dropdown` list or an `ActionMenu` is dismissed by Tab rather than trapping it: it closes and focus returns to its trigger, so Tab carries on from there. A consumer’s own portaled popup is not known to the trap and Tab will pull focus out of it. Set `role="alertdialog"` for a consequential choice, which asks assistive tech to announce the body and not just the name, and point `aria-describedby` at whichever element carries it. Width comes from the `size` union (`small` 420px | `medium` 612px | `large` 760px | `fullscreen`, which fills the window in both directions) rather than a raw pixel prop. `titleAdornment` sits immediately after the title behind a hairline divider, for naming the thing being acted on — distinct from `headerExtra`, which pins to the far right. `tray` paints a tinted plate around the card and hangs a `caption` beneath it; the plate is the dialog element itself, so that caption stays inside the `aria-modal` subtree rather than being stranded outside it by the visual nesting, and it is added to `aria-describedby` automatically because it says what the dialog is asking. It takes a tone (`neutral` | `warning` | `error` | `success`) rather than a colour, so no consumer can paint it off-palette — and the tone sets the plate and its caption colour together, so the two cannot disagree. The caption is a `{ label?, message }` pair rather than a node, because its row height, type scale and colour belong to the plate. `size` names the card, and the plate’s 4px ring is added on top. Like `SidePanel` it sits in a z-index band from 1000 — one step per stacked overlay, so what paints on top is what holds the keyboard — and stays out of the browser top layer, so a host app’s own dialogs can still cover it. `callouts` stacks full-bleed `Alert` bands at the top of the body, as on `SidePanel`; they ignore `bodyPadding` and lead `aria-describedby`, ahead of the consumer’s own description and the tray caption. For a confirmation use `ConfirmationDialog`, which is a preset over this. _Key props:_ `open`, `onClose`, `title`, `subtitle`, `icon`, `headerExtra`, `titleAdornment`, `tray`, `callouts`, `renderLink`, `headerDivider`, `footer`, `size`, `showCloseButton`, `closeOnOverlayClick`, `bodyPadding`, `bodyHeight` (`auto` | `tall` — 600px, or the viewport less 160px when smaller, for an embedded iframe at `height: 100%`), `busy`, `role` (`dialog` | `alertdialog`), `aria-label`, `aria-labelledby`, `aria-describedby`.
32
32
  - **`SidePanel`** — Right-hand slide-in overlay panel (drawer) with header slots (back/icon/title/subtitle/extra), scrollable body and optional footer. `subtitlePlacement="below"` stacks the subtitle on its own line under the title row, so neither truncates the other in a narrow panel. `toolbar` pins content between the header and the scrolling body (16px sides, 16px above, 8px below, no divider), such as a Search over the list it filters. Locks background scroll and dismisses on ESC, an overlay click or close. ESC and the Tab focus trap apply to the topmost overlay only, so a `Modal` may be stacked over it. The Tab trap follows focus into a malachite popup portaled out of the panel’s own tree — a `MultiSelect` listbox or a `Popover` opened from the body — and traps Tab within that popup while it holds focus, so Tab walks and wraps that popup’s own stops rather than being yanked back to the panel’s first control or escaping the panel altogether. A `Dropdown` list or an `ActionMenu` is dismissed by Tab rather than trapping it: it closes and focus returns to its trigger, so Tab carries on from there. A consumer’s own portaled popup is not known to the trap and Tab will pull focus out of it. `callouts` stacks full-bleed `Alert` bands at the top of the body, above `children` and unaffected by `bodyPadding` — the same band `ConfirmationDialog` gives its `callout` — and `renderLink` routes their root-relative markdown links through the app’s router. The callouts are announced as the panel’s description, ahead of `description`. `aside` opens a full-height column to the left, as wide again as `maxWidth`, for help that sits beside the content — a setup guide beside a form. The panel’s own header, body and footer keep their width and place, and the aside’s `title` (with an optional `headerExtra`, such as a `Stepper`) and `footer` line up with the panel’s header and footer; `bodyPadding` works as the panel’s does. The aside is never narrower than 360px, so a window too narrow for both columns scrolls the panel sideways. `onSubmit` makes the header, body and footer one `<form>` (`noValidate`, default prevented), so Enter in a field submits through a `type="submit"` footer button, as `FormActions` gives, the way a browser form does: not from a textarea, not mid-composition, and not while that button is disabled. Enter in the `toolbar` never submits, and the submit does not reach a form the panel is rendered inside.
33
33
  - **`useHasOpenOverlay`** — Hook reporting whether any modal-type overlay - `SidePanel` or `Modal` - is open anywhere in the app. For host chrome that has to get out of an overlay’s way, a floating support widget being the case it was added for: overlays render through a portal, so a host has no DOM signal of its own to read, and reading the library’s internal markers would couple it to something it does not own. Dropdowns and tooltips are deliberately not counted - they do not trap focus, and chrome does not need to move for them. _Key props:_ No arguments. Returns a boolean.
34
- - **`SidePanelNavFooter`** — Keyboard-hint footer for SidePanel: up/down keycaps to step between records and an esc-to-close hint, with an optional right-aligned actions slot.
34
+ - **`SidePanelNavFooter`** — Keyboard-hint footer for SidePanel: up/down keycaps to step between records, optional left/right keycaps to switch tabs, and an esc-to-close hint, with an optional right-aligned actions slot.
35
35
 
36
36
  ## Feedback & status
37
37
 
@@ -76,7 +76,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
76
76
  - **`DatePicker`** — Picks one day, or one instant with `precision="minute"` or `"second"`, from Figma's calendar in a popover. Day precision commits on click; a time precision adds hour/minute(/second) columns and holds a draft until Apply, which Escape or an outside click discards. `timeZone="utc"` draws the UTC calendar day and suffixes times with "UTC" whatever the browser's zone, as the logs pages need. Values are `Date`s; ISO strings are accepted (a string without an offset, such as `2025-01-20` or `2025-01-20T10:00`, is read in `timeZone`), and a `formControl` field seeded with a string is written back as an ISO string. `min`/`max` bound the instant (days and times outside are disabled, as are month arrows and keyboard paging that would leave them; a value clamped up to `min` rounds up to the precision, so on `min`'s own day a day-precision value is `min` itself) and `isDateDisabled` rules out single days. The grid is an ARIA grid with a roving tab stop: arrows move by day and week, PageUp/PageDown by month (Shift for a year), Home/End to the week's ends, Enter or Space picks; every day of a range is `aria-selected`, and a hidden live line asks for the end date once the start is picked. The trigger sits on the 28/32/42 control ladder with Dropdown's chrome; `clearable` adds a clear control reported as `onChange(null)`. Colours come from `text`, `accent` and `card`, so a rebrand repaints the picker; the derived states (hover, outside-month text, selected fill, today ring, range band, pressed opacity) can each be overridden through the `datePicker` theme group (`applyTheme({ colors: { datePicker: { selectedBackground } } })`). _Key props:_ `value`, `defaultValue`, `onChange`, `precision` (`day` | `minute` | `second`), `minuteStep`, `timeZone` (`local` | `utc`), `weekStartsOn`, `min`, `max`, `isDateDisabled`, `presets`, `clearable`, `tag` (`{ label, type }` status beside the value), `tone` (`default` | `chosen` | `pending`, paint only), `placeholder`, `size`, `fullWidth`, `width`, `label`, `description`, `hint`, `tooltip`, `helperText`, `required`, `requiredIndicator`, `formControl`, `error`, `disabled`, `loading`, `id`, `aria-label`, `aria-labelledby`.
77
77
  - **`DateRangePicker`** — `DatePicker`'s range form, with the same props and a `{ start, end }` value. The second click completes a day range; a click before the start restarts it. The end always covers the whole of its last unit (`23:59:59.999` for a picked day, the last millisecond of the picked minute or second), so a filter on the range keeps its final minutes. In a `formControl` field a cleared range writes `null`. With a time precision a Start/End switch picks which end the time columns edit, end times before the start are not offered, and Apply waits for both ends. `presets` list beside the calendar and apply at once; pass a function (`value: () => ({ start, end })`) for a relative preset such as "Past 1 hour", so it is measured when clicked rather than when the page loaded. _Key props:_ `value` / `defaultValue` (`{ start, end }`), `onChange`, `presets` (`DateRangePreset[]`), plus every `DatePicker` prop.
78
78
  - **`MultiSelect`** — Multi-select dropdown. `width` fixes the trigger, as `Dropdown` and `Search` take it, so a toolbar can put its controls on one width — and, as with those two, a container narrower than the value still wins; the menu fills the trigger and left-aligns under it, so that one prop sizes both; `minWidth` raises the 160px floor a narrow trigger falls back to. An option label too long for the menu ellipsises, and hovering it shows the full label — above the description in `hover` mode — as `Dropdown` does for its options. `requiredIndicator` follows the same three-way convention the single-select controls do, so a form choosing asterisks does not get "(Optional)" on one of its fields. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`, `width`, `minWidth`, `label`, `searchable`, `inlineSearch`, `chips`, `chipsRemovable`, `required`, `requiredIndicator`, `aria-label`, `aria-labelledby`, `id`.
79
- - **`FilterSearch`** — One search field that filters across several categories. Clicking lists the filters, each with its description and an example; picking one lists its values behind a `Filters > Name` breadcrumb, and typing before picking searches the values of every filter at once, tagging each match with the filter it belongs to. Select All / Deselect All act on whatever the query matches. Each filter becomes a chip (`Connector: Notion`, or `Connector: (Notion, Attio)`) that reopens its values when clicked; Backspace in an empty field removes the last one. `onQueryChange` reports the text in the field, for analytics or a server-side search. With `textFilter` (`{ value, label }`, under a `value` no filter uses) the typed text is itself the first row while searching (`Search "acme"`); committing it adds a `Search: acme` chip whose selection is `{ filter: textFilter.value, items: [text] }`, replacing any earlier text, so a free-text search can sit in the URL beside the filters, and clicking that chip puts the text back in the field. Controlled: `onChange` gets the next selection and the `changes` that produced it, an empty `items` meaning the filter was removed, so a URL-backed selection writes back only what moved. Chips keep the order filters were added in even when `value` comes back reordered, and keep their labels while `filters` reloads. _Key props:_ `filters`, `value`, `onChange`, `onClear`, `onActiveFilterChange`, `onQueryChange`, `textFilter`, `placeholder`, `size`, `width`, `loading`, `disabled`, `clearable`, `maxVisibleChips`, `aria-label`, `aria-labelledby`, `id`.
79
+ - **`FilterSearch`** — One search field that filters across several categories. Clicking lists the filters, each with its description and an example; picking one lists its values behind a `Filters > Name` breadcrumb, and typing before picking searches the values of every filter at once, tagging each match with the filter it belongs to. Select All / Deselect All act on whatever the query matches. Each filter becomes a segmented chip, its name then its values (`Connector | Notion, Attio +2`), that reopens its values when clicked; an item `icon` is drawn in its menu row and in the chip, and `chipLabel: false` on a filter drops its name from the chip (`Configured only`); Backspace in an empty field removes the last one. `onQueryChange` reports the text in the field, for analytics or a server-side search. With `textFilter` (`{ value, label }`, under a `value` no filter uses) the typed text is itself the first row while searching (`Search "acme"`); committing it adds a `Search: acme` chip whose selection is `{ filter: textFilter.value, items: [text] }`, replacing any earlier text, so a free-text search can sit in the URL beside the filters, and clicking that chip puts the text back in the field. Controlled: `onChange` gets the next selection and the `changes` that produced it, an empty `items` meaning the filter was removed, so a URL-backed selection writes back only what moved. Chips keep the order filters were added in even when `value` comes back reordered, and keep their labels while `filters` reloads. `filtersButton` puts a Filters button, with the applied count, at the right end of the bar that opens the filter list, right-aligned beneath it; clicking the field then leaves the list shut until something is typed, while the arrow keys and Enter open it as the button does. _Key props:_ `filters`, `value`, `onChange`, `onClear`, `onActiveFilterChange`, `onQueryChange`, `textFilter`, `filtersButton`, `placeholder`, `size`, `width`, `loading`, `disabled`, `clearable`, `maxVisibleChips`, `aria-label`, `aria-labelledby`, `id`.
80
80
  - **`QueryInput`** — A textbox with inline syntax colouring and a suggestion menu anchored to the caret. It carries no grammar of its own: the consumer parses the value, hands back `tokens` to colour and `suggestions` to offer, so the vocabulary lives in the consuming app rather than here. _Key props:_ `value`, `onChange`, `tokens`, `suggestions`, `activeRange`, `onAccept`, `onQueryContextChange`, `onSubmit`, `placeholder`, `size`, `disabled`, `loading`, `emptyMessage`, `className`, `style`, `aria-label`, `aria-labelledby`.
81
81
  - **`SettingRow`** — One setting: a labelled row with its control on the trailing edge, and the sentence that explains it underneath. `control` may be a render prop receiving the label’s id, so a control that no `<label htmlFor>` can reach — `Toggle` renders a `<button role="switch">` — still names itself via `aria-labelledby`. _Key props:_ `label`, `badge`, `description`, `control`, `className`.
82
82