@stackone/malachite 2.1.1 → 2.2.1

package/COMPONENTS.md

@@ -34,7 +34,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 - **`PreviewTreeRow`** — A single labelled row within a PreviewTree. _Key props:_ `label`.
 - **`Tabs`** — Tabbed navigation switching between content panels. _Key props:_ `TabItem[]`.
 - **`Breadcrumbs`** — Breadcrumb trail with caret separators, an optional back button (shown only when there is more than one crumb AND the parent — the second-to-last — carries a `url` to target) and a right-aligned `actions` row. A lone crumb marked `isRoot` switches to title mode: plain emphasised text, no trail chrome, but the `actions` row still renders. Renders as a `nav`/`ol` with `aria-current="page"` on the last crumb. Pass `renderLink` to route crumbs through the app's own router instead of a plain `<a>`. Used by `PageLayout`, but standalone too. _Key props:_ `links[]` (`name`, `url`, `isRoot`), `actions[]`, `renderLink`, `className`, `style`.
-- **`ActionMenu`** — Dropdown menu of actions (kebab/overflow style). _Key props:_ `ActionMenuItem[]`.
+- **`ActionMenu`** — Dropdown menu of actions (kebab/overflow style). The trigger is an icon-only `Button`, so `size` draws exactly the square a `Button` of that size draws beside it: `xsmall` is Figma's 20px "Button Element - Square (X-Small)", `small` the 28px rung above it. Both squares are fixed rather than read off the `controlHeights` tokens, so re-theming those does not resize the trigger. A supplied `triggerIcon` is held to the tier's glyph size — 11px at `xsmall`, 16px at `small`. At 20px the `xsmall` trigger meets WCAG 2.5.8 through the *Spacing* exception rather than the 24px minimum, so keep at least 4px between adjacent triggers. _Key props:_ `ActionMenuItem[]`, `size`, `label`, `triggerIcon`, `minWidth`.
 - **`FooterNav`** — Footer navigation bar of links. _Key props:_ `FooterNavLink[]`.
 - **`FooterLinks`** — Inline list of footer links (e.g. terms, privacy, support).
 - **`StepTabs`** — Header for a short, ordered flow — a two-step drawer or wizard panel. Each step is a button carrying `aria-current="step"`, not a tab: the body beneath is the step’s form, so it keeps the normal tab order instead of adopting a `tablist`’s arrow-key contract. States are current / complete (a check, still reachable so the user can go back) / upcoming. For a read-only progress readout use `Stepper`. _Key props:_ `items` (`key`, `label`, `hint`, `disabled`), `activeKey`, `completedKeys`, `onChange`, `aria-label`, `aria-labelledby`, `className`.
@@ -46,15 +46,18 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 - **`Form`** — Form container coordinating field layout and submission.
 - **`FormItem`** — Labelled form field wrapper (label, help text, error).
 - **`BaseFormComponent`** — Low-level base used by form controls; rarely used directly.
-- **`Input`** — Single-line text input. _Key props:_ `label`, `type`, `InputSize`, `InputVariant` (`default` | `ghost`), `required`, `error`, `helperText`, `loading`, `formControl`, `showCopyButton`, `showPasswordToggle`, `aria-label`, `aria-labelledby`, `id`.
-- **`TextArea`** — Multi-line text input. _Key props:_ `label`, `rows`, `maxLength`, `resize`, `required`, `error`, `loading`, `formControl`, `aria-label`, `aria-labelledby`, `id`.
+- **`FormSectionHeading`** — Names a group of fields and rules off the space beside it, the way a long panel or settings page separates what it is asking for into parts. The label never shrinks — letting it flex clips the name long before the rule runs out of room — and it carries the same 8px inset a field label does, so a section name and the labels beneath it stand on one line. Quieter than `Typography.FormSectionTitle`, which titles a form rather than dividing one. `rule={false}` drops the rule, and it announces as a heading at `level`, so a long form can be navigated by section. _Key props:_ `children`, `rule`, `level` (2-6, default 3), `className`, `style`.
+- **`FieldGroup`** — Fields that follow from an answer given above them — the credentials a chosen authentication type asks for, say — drawn as its children: indented, with a rule down the side of the group. Stretches them to its own width, since a field left to size itself takes only the width of its content. _Key props:_ `children`, `gap` (default 40), `className`, `style`.
+- **`FieldBlock`** — Something a form has to show but does not ask for — a computed list, a generated value — wearing a field’s anatomy: label, optional `badge` beside it and `action` at the end of the row, content, then helper text, all on a field’s own metrics and inset. A real control brings its anatomy with it; this is for everything that has no control to bring one. _Key props:_ `label`, `badge`, `action`, `helperText`, `children`, `className`, `style`.
+- **`Input`** — Single-line text input. Passing `formControl` is enough to show validation: the resolver's message renders on its own line beneath the field in the destructive colour, politely announced, with `aria-invalid` and `aria-describedby` wired and the in-field error icon standing down once the message carries the meaning, and the control reports its edits back so a rejection clears as the customer fixes the field rather than standing until the next submit. Given a `formControl` the form owns the value: the field paints an explicit `value` first, then the value the form holds, then `defaultValue`, then empty — the ladder react-hook-form's own `useController` computes — so `reset()` and `setValue()` repaint the field and the text on screen cannot drift from the value being validated, which had put a rejection under a field the customer could see was filled. Passing `defaultValue` to a bound field warns in development, naming the component and the field: where the form has an entry for it, it is ignored, and where it has none it paints text the form will never submit. Set it through `useForm({ defaultValues })` instead. A consumer's own `helperText` keeps its line above it and stays dimmed, since it explains the field rather than reporting the fault — replacing one with the other left a field ringed in red with nothing saying what was wrong. An explicit `error` still wins, for a rejection the resolver knows nothing about, and `error={false}` suppresses the resolver outright, message included. `requiredIndicator` switches the label between the library default of naming the optional fields, an `asterisk` on the required ones for designs drawn that way, and `none` for a field whose value is supplied rather than asked for — a locked control is still required, but a marker only sends the reader looking for something to fill in. Visual only: `aria-required` is set from `required` whichever is chosen. _Key props:_ `label`, `type`, `InputSize`, `InputVariant` (`default` | `ghost`), `required`, `requiredIndicator`, `error`, `helperText`, `loading`, `formControl`, `value`, `defaultValue`, `showCopyButton`, `showPasswordToggle`, `aria-label`, `aria-labelledby`, `id`.
+- **`TextArea`** — Multi-line text input. Shows resolver validation from `formControl` on exactly the same terms as `Input`: the message gets its own line beneath any `helperText`, which keeps its own, and the value climbs the same ladder — an explicit `value`, then the value the form holds, then `defaultValue`, then empty — a disabled field included, which used to show `defaultValue` whatever the form or the consumer had said. `requiredIndicator` switches the label between the library default of naming the optional fields, an `asterisk` on the required ones for designs drawn that way, and `none` for a field whose value is supplied rather than asked for — a locked control is still required, but a marker only sends the reader looking for something to fill in. Visual only: `aria-required` is set from `required` whichever is chosen. _Key props:_ `label`, `rows`, `maxLength`, `resize`, `required`, `requiredIndicator`, `error`, `helperText`, `loading`, `formControl`, `value`, `defaultValue`, `aria-label`, `aria-labelledby`, `id`.
 - **`Search`** — Search input with a leading icon; `filled` and `muted` variants. _Key props:_ `value`, `onChange`, `placeholder`, `variant`, `size`, `disabled`.
 - **`Checkbox`** — Checkbox supporting checked/indeterminate/disabled. Pass `presentational` to render a visual-only, non-focusable indicator for use inside a clickable row/card. _Key props:_ `checked`, `indeterminate`, `disabled`, `onChange`, `presentational`.
 - **`Radio`** — Single radio control with hover state; parent manages the group. Pass `presentational` to render a visual-only, non-focusable indicator for use inside a clickable row/card. _Key props:_ `checked`, `onChange`, `disabled`, `size`, `presentational`.
 - **`SegmentedControl`** — A pill track of mutually-exclusive options — the segmented “one of these” control. Owns the track background, the selected-thumb chrome and the `radiogroup` semantics, so consumers never hand-roll a track around `PillButton` (whose `default` variant tokens are tuned for standalone filter pills, not a sunken track). Single tab stop with arrow-key move-and-select; selection is conveyed via `aria-checked` and a foreground change, not background colour alone. Restyle via the `segmentedControl` theme tokens. _Key props:_ `options` (`value`, `label`, `icon`, `disabled`), `value`, `onChange`, `SegmentedControlSize` (`small` | `medium` | `large`), `fullWidth`, `disabled`, `aria-label`, `aria-labelledby`, `className`.
 - **`Toggle`** — On/off switch. Add `label` for a visible caption, and `variant` to give it standalone toolbar-filter chrome — pick the family it sits beside: `pill` matches the filter-bar inputs (`Search`, `MultiSelect`), `button` renders the whole control as an outline `Button` with the switch as its trailing icon. `bordered` is shorthand for `variant="pill"`. `tone="pending"` paints the checked track amber, for a switch whose change has not been written yet — pair it with a `SelectionBar` reporting the same diff. The unchecked track never changes: nothing is pending about a switch that is off. _Key props:_ `checked`, `onChange`, `disabled`, `ToggleSize` (`small` | `medium`), `ToggleTone` (`default` | `pending`), `label`, `ToggleVariant` (`pill` | `button`), `bordered`, `aria-label`, `aria-labelledby`, `aria-describedby`, `id`.
-- **`Dropdown`** — Single-select dropdown. `DropdownSize` is `small` (28px) | `medium` (32px) | `large` (42px), matching Button; `small` is the chip that sits beside a page title and rounds tighter (10px) than the taller sizes. These names each moved up a tier in 0.71 — the old `xsmall`/`small`/`medium` are now `small`/`medium`/`large`. Pass `value` for a controlled selection whose source of truth lives elsewhere (URL or app state): the trigger follows it without the consumer remounting via `key`, which used to discard focus mid-interaction. `defaultValue` keeps the uncontrolled behaviour. `clearable` adds a clear control to the trigger once something is selected and reports it as `onItemSelected(undefined)` — without it a selection cannot be undone, so filter bars had to invent a sentinel "any" item to carry that meaning. _Key props:_ `DropdownItem[]`, `DropdownSize`, `value`, `defaultValue`, `label`, `search`, `clearable`, `required`, `error`, `helperText`, `loading`, `formControl`, `aria-label`, `aria-labelledby`, `id`.
-- **`MultiSelect`** — Multi-select dropdown. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`, `label`, `searchable`, `inlineSearch`, `chips`, `chipsRemovable`, `required`, `aria-label`, `aria-labelledby`, `id`.
+- **`Dropdown`** — Single-select dropdown. `DropdownSize` is `small` (28px) | `medium` (32px) | `large` (42px), matching Button; `small` is the chip that sits beside a page title and rounds tighter (10px) than the taller sizes. These names each moved up a tier in 0.71 — the old `xsmall`/`small`/`medium` are now `small`/`medium`/`large`. Pass `value` for a controlled selection whose source of truth lives elsewhere (URL or app state): the trigger follows it without the consumer remounting via `key`, which used to discard focus mid-interaction. `defaultValue` keeps the uncontrolled behaviour. `clearable` adds a clear control to the trigger once something is selected and reports it as `onItemSelected(undefined)` — without it a selection cannot be undone, so filter bars had to invent a sentinel "any" item to carry that meaning. `requiredIndicator` switches the label between the library default of naming the optional fields, an `asterisk` on the required ones for designs drawn that way, and `none` for a field whose value is supplied rather than asked for — a locked control is still required, but a marker only sends the reader looking for something to fill in. Visual only: `aria-required` is set from `required` whichever is chosen. `showSubtitleInTrigger` promotes the selected item's `subtitle` into the closed trigger, on one line under the value, so the consequence of a choice stays on screen once the menu shuts — the trigger trades its fixed height for a floor and grows by that line, and either line too long for it ellipsises, with a single tooltip carrying whichever lines are cut off, value first. It does not combine with `search`, whose trigger is a single-line text input with nowhere to put a second line, so the type rejects the pair rather than letting a consumer ask for a subtitle and get none. `subtitleLayout` decides how a subtitle sits in the open menu: the default `inline` keeps it on the label's row after a divider, which suits a short qualifier, while `stacked` gives it its own line beneath the label, clamped to two — inline, a sentence-length subtitle is ellipsised away to a few words. Passing `formControl` is enough to show validation on the same terms as `Input`, though only validation: the trigger still paints `value` or `defaultValue`, never the value the form holds. The resolver's message renders on its own line beneath the field in the destructive colour, politely announced, with `aria-invalid` and `aria-describedby` wired, while an explicit `helperText` keeps its own line above it and stays dimmed, and `error={false}` suppresses the resolver outright. _Key props:_ `DropdownItem[]`, `DropdownSize`, `value`, `defaultValue`, `label`, `search`, `showSubtitleInTrigger`, `subtitleLayout`, `clearable`, `required`, `requiredIndicator`, `error`, `helperText`, `loading`, `formControl`, `aria-label`, `aria-labelledby`, `id`.
+- **`MultiSelect`** — Multi-select dropdown. `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`, `label`, `searchable`, `inlineSearch`, `chips`, `chipsRemovable`, `required`, `requiredIndicator`, `aria-label`, `aria-labelledby`, `id`.
 - **`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`.
 
 ## Buttons & actions
@@ -75,7 +78,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 - **`LoadingBar`** — Indeterminate full-width loading line; the variant colour sweeps across a pale track for work of unknown duration. Toggle `active` rather than unmounting, so the reserved height prevents layout shift. _Key props:_ `active`, `LoadingBarVariant` (`default` | `warning` | `error`), `LoadingBarSize` (`small` | `medium` | `large`), `aria-label`, `aria-labelledby`, `className`, `style`.
 - **`Spinner`** — Loading spinner.
 - **`Skeleton`** — Loading placeholders. Includes `Skeleton.Avatar` and `Skeleton.Input`.
-- **`Tooltip`** — Hover/focus tooltip; also works on disabled controls (see CLAUDE.md).
+- **`Tooltip`** — Hover/focus tooltip; also works on disabled controls (see CLAUDE.md). It describes its trigger once shown, so `describesTrigger={false}` where the same sentence is already on screen and referenced — otherwise a screen reader reads it twice. _Key props:_ `text`, `placement`, `delay`, `maxWidth`, `shouldShow`, `triggerAs`, `describesTrigger`, `isShrinkable`, `fill`, `wrapChildren`.
 - **`TruncatedTooltip`** — Shows a tooltip only when its text is truncated.
 - **`Confetti`** — Celebratory confetti burst for success moments. _Key props:_ `pieces`.
 
@@ -86,7 +89,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 
 ## Data display
 
-- **`Table`** — Data table with columns, sizing, pagination and row selection. _Key props:_ `TableColumns`, `TableSize`, `TableType`, `TableRowSelection`, `TablePaginationPosition`.
+- **`Table`** — Data table with columns, sizing, pagination and row selection. `column.align` places a column's header as well as its cells. What lands on the aligned edge is the last thing in the header row rather than the title: the sort caret on a sortable column, the info icon on one carrying `info` without a sorter. `headerVariant` picks the header layout, and only `inline` lines header and body up exactly, because both are cells of one `<table>`. `detached` builds them from flex rows, where a sortable header cell is 32px narrower than a non-sortable one — its padding sits on the inner button rather than on the flex item — so its header cells sit 15–17px off their column at any alignment; reach for `inline` where exact alignment matters. _Key props:_ `TableColumns` (incl. `align`), `TableSize`, `TableType`, `TableRowSelection`, `TablePaginationPosition`, `headerVariant`.
 - **`Statistic`** — Displays a statistic value with a label; primary/secondary sizes. _Key props:_ `StatisticValueSize`.
 - **`Avatar`** — Logo/initial avatar. Renders the image when available, otherwise a coloured tile with the first letter of `name`. Encapsulates the fallback colour. _Key props:_ `src`, `name`, `size`, `shape="square" | "circle"`.
 - **`AppLogo`** — A connector's mark, optionally with its name and version tag. Builds on `Avatar`, so a missing or broken logo falls back to a coloured initial. The gap tightens below 18px so the mark and label still read as one unit. _Key props:_ `src`, `name`, `showName`, `size`, `nameSize`, `nameWeight`, `version`, `truncate`, `className`.

package/dist/{CodeBlockHighlighter-DY5GoVYV.js → CodeBlockHighlighter-C7MpgFqR.js}

@@ -1,5 +1,5 @@
 import { jsx as Oe } from "react/jsx-runtime";
-import { _ as un, a as sn, C as re, b as fn } from "./index-CrkMcfzV.js";
+import { _ as un, a as sn, C as re, b as fn } from "./index-BX79s-B-.js";
 import H from "react";
 function dn(e, n) {
   if (e == null) return {};
@@ -2781,4 +2781,4 @@ const ht = {
 export {
   bt as default
 };
-//# sourceMappingURL=CodeBlockHighlighter-DY5GoVYV.js.map
+//# sourceMappingURL=CodeBlockHighlighter-C7MpgFqR.js.map