@stackone/malachite 2.84.1 → 2.85.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
@@ -64,7 +64,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
64
64
  - **`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`.
65
65
  - **`ActionMenu`** — Dropdown menu of actions (kebab/overflow style). The trigger is an icon-only `Button` by default, 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. `showLabel` draws `label` beside the icon instead of leaving it to the accessible name — for a menu that is the point of its corner rather than an overflow for a row that already says what it acts on — and `variant` puts the trigger on any `Button` variant, so a menu handing work to the assistant can wear the assistant ground rather than the overflow-kebab outline. An item's `icon` leads its label: every caller's names the action itself — copy, open, delete — and an icon that is part of an item's identity belongs where the eye starts rather than right-aligned, where it reads as a status column. The menu is Figma's `Dropdown Component - Options List`: a fixed sized to its widest item between a 180px floor and the 280px Figma draws, by default under the trigger's right edge, 14px below it, flipping above or clamping sideways when the viewport has no room, rounding at the library's 12px and padding wider (8px) than the menu a `Dropdown` opens. Items read in the primary text colour, or the secondary one with `tone="muted"` (e.g. a sidebar's menus); destructive ones in red; `danger: 'hover'` keeps an item in its normal colour and turns it destructive (red text on a light red ground) only on hover or keyboard focus, for an action like signing out. A ceiling rather than a flat width: taken literally it gave a menu of four short verbs 130px of air and made every kebab in an app the same width whatever it held. `minWidth` only raises it above that ceiling, so it is the one way to go past 280px, and a label too long for the box truncates rather than wrapping. _Key props:_ `ActionMenuItem[]`, `size`, `label`, `triggerIcon`, `minWidth`, `showLabel`, `variant`, `tone` (`default` | `muted`), `trigger` (your own control in place of the kebab, cloned with the menu's ref and aria state), `highlightChoices`, `placement` (`bottom-end` default | `bottom-start` | `right-start` | `top-start` | `top-center`), `offset` (`small` 8px | `medium` 12px | `large` 14px; applies to every placement; without it the default `bottom-end` keeps the options menu's 14px and the others use 8px). An item's `tag` (e.g. an "Early access" `Tag`) follows its label in a lazily loaded shadow host of its own, since the menu renders into `document.body`, and joins its accessible name; `current: true` marks the item for the page the user is on (`aria-current="page"` and the selected row paint; a `danger` item keeps its red text). An item with an `href` is a link: Cmd/Ctrl-click or a middle click opens it in a new tab and closes the menu, while a plain click runs `onClick` in its place when one is given (so a router can navigate in-app); Enter and Space both activate it. `target: '_blank'` opens it in a new tab, adds `noopener noreferrer` and tells screen readers it opens a new tab. An item with `checked` is one of a set of choices: a `menuitemradio` with `aria-checked` and a trailing check while true; picking it still runs `onClick` and closes. Give the choices of one set the same `group` and, where they sit next to each other, they share a `role="group"` named by it, so a screen reader can tell where the set ends; choices with the same `group` split by another item form separate groups. `description` adds a quieter second line under the label, announced as the item's description rather than its name. `intent` colours the label and icon: `warning` (amber) for undoing choices already made, `accent` (green) for a way forward; a disabled item drops it, and `danger` or `current` wins over it. `highlightChoices` styles the menu as a picker: the checked choice of each `group` sits on a light green row (a Dropdown selected option's ground) with a green check (a danger, intent, disabled or current choice keeps its own colours), and a text row whose label is a set's `group` name sits a notch smaller, as its heading. An item with `type: 'text'` is context rather than an action (an account's email above its actions): secondary text the arrow keys skip. Opened from the keyboard, focus lands on the first item, or on the checked choice in a menu of choices; Up/Down/Home/End move through enabled items, Tab closes the menu and moves on as usual; Escape or a picked item returns focus to the trigger.
66
66
  - **`NavItem`** — A row in an app's side navigation. Idle rows read secondary and take the list hover; the `active` row wears the accent tint and sets `aria-current="page"` on a link. `collapsed` shrinks it to a 36px icon tile whose label becomes the accessible name and a right-hand tooltip, with any `badge` pinned to the tile's corner. `variant="subitem"` indents a child row behind a dot instead of an icon; `disclosure` makes a group header button with `aria-expanded` and a rotating chevron, and `hasActiveChild` colours its text while a child is current. Renders an `<a>` with `href`, the element passed with `asChild` (a router `Link`), or a `<button>`, and forwards its ref and extra attributes so it can be a `Popover` or `ActionMenu` trigger. `disabled` keeps the row a tab stop with `aria-disabled`, drops its hover and pointer, and ignores clicks, Enter and Space; a `Popover` or `ActionMenu` it triggers stays shut on press, hover, focus and arrow keys, while other keys still reach a passed `onKeyDown` so arrow navigation through a list keeps working; a disabled `href` row renders as a button so it cannot be followed. `disabledReason` explains it in a right-hand tooltip on hover and focus and is the row's accessible description from the first focus. Not with `asChild`, whose child would still navigate. _Key props:_ `label`, `icon`, `active`, `hasActiveChild`, `collapsed`, `variant` (`item` | `subitem`), `danger`, `trailing`, `badge`, `disclosure` (`expanded` | `collapsed`), `tooltip`, `accessibleLabel` (overrides the accessible name; collapsed it defaults to the tooltip text plus `badgeLabel`), `href`, `target`, `rel`, `onClick`, `asChild` + `children`, `className`, `size` (`medium` | `small`, the tighter row for lists inside a popover), `tag` (beside the label, e.g. early access), `badgeLabel` (read in place of the badge and added to the collapsed name), `disabled`, `disabledReason`. A passed `aria-expanded` (e.g. from a `Popover`) wins over `disclosure`, and a button row forwards a passed `aria-current`.
67
- - **`Sidebar`** — An app's left navigation shell, pinned to the viewport's left edge: 260px wide, 60px `collapsed`, on the sunken page background. Composed from `Sidebar.Header` (a 56px band for `Sidebar.Switcher`, the logo + workspace + parent trigger), `Sidebar.Body` (the part that scrolls), `Sidebar.Notices`, `Sidebar.Search`, `Sidebar.Section` (rows of `NavItem`s at the gutter), `Sidebar.Group` + `Sidebar.GroupItems` (a disclosure header and its sub-items), `Sidebar.Divider`, `Sidebar.Usage` (a `UsageCard` placed at the sidebar's gutter) and `Sidebar.Footer` holding `Sidebar.Account`. Popovers opened from it (with `padding="none"`) wrap their body in `Sidebar.Panel`, sized so the popover comes to `SIDEBAR_POPOVER_WIDTH_PX`, and build it from the `Popover` parts. `onToggleCollapse` adds the edge toggle, shown in CSS while the pointer is over the sidebar or a keyboard focus is inside it, and always on a touch screen, which has no hover to reveal it. A workspace, organization or account name cut off in the expanded sidebar shows in full on hover. Notices, the divider and the usage card hide while collapsed. Render it inside `<MalachiteContext layer="sidebar">`, or the page paints over the edge toggle. _Key props:_ `collapsed`, `onToggleCollapse`, `expandLabel`, `collapseLabel`, `aria-label`; `Sidebar.Switcher`: `logo`, `title`, `subtitle`, `titleTooltip`/`subtitleTooltip` (shown when the name is cut off, the name by default; pass a node to wrap it, e.g. to keep it out of session recordings) + button attributes; `Sidebar.Account`: `avatar` or `initials` (a small chip when there is no photo), `name`, `tooltip` (on the collapsed rail, and expanded when the name is cut off; `name` by default; pass a node to wrap it) + button attributes; `Sidebar.Usage`: the `UsageCard` props; `Sidebar.Notices`: `aria-label` (required); `Sidebar.Panel`: `width` (`SIDEBAR_POPOVER_WIDTH_PX` by default). `useSidebarCollapsed()` reads the state from inside; `SIDEBAR_WIDTH_PX` gives the page its offset beside the sidebar; `SIDEBAR_TOOLTIP_DELAY_S` is the 0.2s delay its name and rail tooltips use, for tooltips a consumer adds inside it.
67
+ - **`Sidebar`** — An app's left navigation shell, pinned to the viewport's left edge: 260px wide, 60px `collapsed`, on the sunken page background. Composed from `Sidebar.Header` (a 56px band for `Sidebar.Switcher`, the logo + workspace + parent trigger), `Sidebar.Body` (the part that scrolls), `Sidebar.Notices`, `Sidebar.Search`, `Sidebar.Section` (rows of `NavItem`s at the gutter), `Sidebar.Group` + `Sidebar.GroupItems` (a disclosure header and its sub-items), `Sidebar.Divider`, `Sidebar.Usage` (a `UsageCard` placed at the sidebar's gutter) and `Sidebar.Footer` holding `Sidebar.Account`. Popovers opened from it (with `padding="none"`) wrap their body in `Sidebar.Panel`, sized so the popover comes to `SIDEBAR_POPOVER_WIDTH_PX`, and build it from the `Popover` parts. `onToggleCollapse` adds the edge toggle, shown in CSS while the pointer is over the sidebar or a keyboard focus is inside it, and always on a touch screen, which has no hover to reveal it. A workspace, organization or account name cut off in the expanded sidebar shows in full on hover. Notices, the divider and the usage card hide while collapsed. Render it inside `<MalachiteContext layer="sidebar">`, or the page paints over the edge toggle. On a viewport narrower than `SIDEBAR_OVERLAY_BREAKPOINT_PX` (768px) pass `overlay`, collapse it on entering overlay mode, and keep the page at the collapsed offset. Collapsed, it is the plain rail and takes no focus. Expanded from that rail, it floats over the page as a modal drawer, behind a scrim, with Escape, a focus trap and scroll lock, and a click on the scrim or Escape collapses it through `onToggleCollapse`. Expanded on mount or across the breakpoint it stays a plain sidebar, so it never takes focus from the page, and expanded under an open dialog it becomes the drawer once that dialog closes. _Key props:_ `collapsed`, `onToggleCollapse`, `overlay`, `expandLabel`, `collapseLabel`, `aria-label`; `Sidebar.Switcher`: `logo`, `title`, `subtitle`, `titleTooltip`/`subtitleTooltip` (shown when the name is cut off, the name by default; pass a node to wrap it, e.g. to keep it out of session recordings) + button attributes; `Sidebar.Account`: `avatar` or `initials` (a small chip when there is no photo), `name`, `tooltip` (on the collapsed rail, and expanded when the name is cut off; `name` by default; pass a node to wrap it) + button attributes; `Sidebar.Usage`: the `UsageCard` props; `Sidebar.Notices`: `aria-label` (required); `Sidebar.Panel`: `width` (`SIDEBAR_POPOVER_WIDTH_PX` by default). `useSidebarCollapsed()` reads the state from inside; `SIDEBAR_WIDTH_PX` gives the page its offset beside the sidebar; `SIDEBAR_TOOLTIP_DELAY_S` is the 0.2s delay its name and rail tooltips use, for tooltips a consumer adds inside it.
68
68
  - **`SearchTrigger`** — A button drawn as a filled search field, for opening a command palette or search dialog from app chrome such as a sidebar. It is not an input — typing happens in what it opens. `shortcut` draws flat `<kbd>` chips at the end (not `Keycap`, whose raised shadow reads as a second button inside a filled field), kept out of the accessible name; `iconOnly` makes a 36px icon tile matching a collapsed `NavItem`, named by `label`. _Key props:_ `label` (default `Search`), `shortcut` (`ReactNode[]`), `iconOnly`, `aria-label`, `className`, plus native button attributes (`onClick`, `aria-haspopup`, `aria-expanded`, `aria-keyshortcuts`).
69
69
  - **`FooterNav`** — Footer navigation bar of links. _Key props:_ `FooterNavLink[]`.
70
70
  - **`FooterLinks`** — Inline list of footer links (e.g. terms, privacy, support).
@@ -89,7 +89,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
89
89
  - **`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`.
90
90
  - **`SegmentedControl`** — A rounded 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. An option `icon` sits before the label in a fixed 16px slot, and an option `badge` follows the label at whatever width it needs, for a mark such as a compact `Tag` naming a saving; it renders inside the segment button, so it must not be interactive. Restyle via the `segmentedControl` theme tokens. _Key props:_ `options` (`value`, `label`, `icon`, `badge`, `disabled`), `value`, `onChange`, `SegmentedControlSize` (`small` | `medium` | `large`), `fullWidth`, `disabled`, `aria-label`, `aria-labelledby`, `className`.
91
91
  - **`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. Forwards a ref to its root element, so it can anchor an `InlineConfirm`. _Key props:_ `checked`, `onChange`, `disabled`, `ToggleSize` (`small` | `medium`), `ToggleTone` (`default` | `pending`), `label`, `ToggleVariant` (`pill` | `button`), `bordered`, `aria-label`, `aria-labelledby`, `aria-describedby`, `id`.
92
- - **`Dropdown`** — Single-select dropdown. `DropdownSize` is `small` (28px) | `medium` (32px) | `large` (42px), matching Button; `fullWidth` fills the container instead of sizing to content, which is what a table cell or a toolbar slot needs — without it the field column sizes to its content, so a consumer has to compute a width; `width` fixes that width outright, the way `MultiSelect` does, for a toolbar lining the two up rather than letting each hug its own label — a narrower container still wins, since the width clamps to it; Until this release a `search` trigger could not go below the intrinsic width of its bare `input`, so a `width` under roughly 200px was ignored; it now shrinks with the rest. The open menu fills the trigger and left-aligns under it, as Figma draws every tier of `Dropdown Component - Standard`, so `width` sizes both — the menu is the width of the control that opened it and does not widen for a long option, which ellipsises instead, so a row of controls and their open menus stay on one set of edges; below 160px the menu keeps that floor rather than shrinking to a chip nobody can read, and `minWidth` raises that floor without widening the trigger — for a picker a column pins narrow whose options carry a subtitle the trigger never shows; `menuAlign="end"` lines a menu wider than its trigger up with the trigger's right edge instead, so a control at the right of a card opens its menu inwards rather than past the card; near a viewport edge it anchors to the trigger's other side before falling back to the viewport, so the two share an edge wherever one fits; `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 — one line either way, ellipsised rather than wrapped, so inline a sentence-length subtitle is cut back to a few words. Every option row carries a tooltip for whatever it had to cut, across all three of label, subtitle and `rightSideText`, so nothing the row hides is unreadable. 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. An item's `subtitle` renders inline markdown in the option, trigger and tooltip, with links drawn but inert, since the option is itself the click target; a subtitle with no markdown syntax stays a plain text node. An item's `badge` (e.g. a `Tag`) sits at the right end of its option in the open menu, after any `rightSideText`, and never shows in the closed trigger or the search input; it does not shrink, and the option is still named by its label alone. _Key props:_ `DropdownItem[]` (items take `badge`), `DropdownSize`, `fullWidth`, `width`, `minWidth`, `menuAlign` (`start` | `end`), `value`, `defaultValue`, `label`, `search`, `showSubtitleInTrigger`, `subtitleLayout`, `clearable`, `required`, `requiredIndicator`, `error`, `helperText`, `loading`, `formControl`, `aria-label`, `aria-labelledby`, `id`.
92
+ - **`Dropdown`** — Single-select dropdown. `DropdownSize` is `small` (28px) | `medium` (32px) | `large` (42px), matching Button; `fullWidth` fills the container instead of sizing to content, which is what a table cell or a toolbar slot needs — without it the field column sizes to its content, so a consumer has to compute a width; `width` fixes that width outright, the way `MultiSelect` does, for a toolbar lining the two up rather than letting each hug its own label — a narrower container still wins, since the width clamps to it; Until this release a `search` trigger could not go below the intrinsic width of its bare `input`, so a `width` under roughly 200px was ignored; it now shrinks with the rest. The open menu fills the trigger and left-aligns under it, as Figma draws every tier of `Dropdown Component - Standard`, so `width` sizes both — the menu is the width of the control that opened it and does not widen for a long option, which ellipsises instead, so a row of controls and their open menus stay on one set of edges; below 160px the menu keeps that floor rather than shrinking to a chip nobody can read, and `minWidth` raises that floor without widening the trigger — for a picker a column pins narrow whose options carry a subtitle the trigger never shows; `menuAlign="end"` lines a menu wider than its trigger up with the trigger's right edge instead, so a control at the right of a card opens its menu inwards rather than past the card; near a viewport edge it anchors to the trigger's other side before falling back to the viewport, so the two share an edge wherever one fits; `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 — one line either way, ellipsised rather than wrapped, so inline a sentence-length subtitle is cut back to a few words. Every option row carries a tooltip for whatever it had to cut, across all three of label, subtitle and `rightSideText`, so nothing the row hides is unreadable. 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. An item's `subtitle` renders inline markdown in the option, trigger and tooltip, with links drawn but inert, since the option is itself the click target; a subtitle with no markdown syntax stays a plain text node. An item's `badge` (e.g. a `Tag`) sits at the right end of its option in the open menu, after any `rightSideText`, and never shows in the closed trigger or the search input; it does not shrink, and the option is still named by its label alone. _Key props:_ `DropdownItem[]` (items take `badge`), `DropdownSize`, `fullWidth`, `width`, `minWidth`, `menuAlign` (`start` | `end`), `value`, `defaultValue`, `label`, `search`, `onSearchChange` (search mode only: the query as typed, and an empty string once a pick, a clear, Escape or a click outside empties it, for offering the typed text as an item of its own; items are still filtered by the query, so the label of that item must contain it, and it must stay in `items` once picked or the trigger shows the placeholder), `showSubtitleInTrigger`, `subtitleLayout`, `clearable`, `required`, `requiredIndicator`, `error`, `helperText`, `loading`, `formControl`, `aria-label`, `aria-labelledby`, `id`.
93
93
  - **`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`.
94
94
  - **`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.
95
95
  - **`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`.
@@ -1,82 +1,83 @@
1
1
  import { jsx as e, jsxs as a } from "react/jsx-runtime";
2
- import { useId as k } from "react";
3
- import w from "./CustomIcons/ArrowUpRightIcon.js";
4
- import F from "./CustomIcons/InfoFilledIcon.js";
5
- import { FormItem as $ } from "./FormItem.js";
6
- import { Link as y } from "./Link.js";
7
- import x from "./Spacer.js";
8
- import O from "./Tooltip.js";
9
- import _ from "./Typography/MarkdownBlock.js";
2
+ import { useId as w } from "react";
3
+ import F from "./CustomIcons/ArrowUpRightIcon.js";
4
+ import $ from "./CustomIcons/InfoFilledIcon.js";
5
+ import { FormItem as y } from "./FormItem.js";
6
+ import { Link as O } from "./Link.js";
7
+ import u from "./Spacer.js";
8
+ import _ from "./Tooltip.js";
9
+ import H from "./Typography/MarkdownBlock.js";
10
10
  import h from "./Typography/Text.js";
11
- import { FOCUS_RING as u } from "./focusRing.js";
12
- import { renderFormItemChildren as H, NO_FIELD_ERROR as R } from "./formItemState.js";
13
- import { safeHref as L } from "./safeHref.js";
14
- const T = 0.5, q = ({
11
+ import { FOCUS_RING as v } from "./focusRing.js";
12
+ import { renderFormItemChildren as R, NO_FIELD_ERROR as L } from "./formItemState.js";
13
+ import { safeHref as T } from "./safeHref.js";
14
+ const j = 0.5, ee = ({
15
15
  id: r,
16
16
  label: t,
17
17
  description: o,
18
- hint: l,
19
- helperText: s = !1
18
+ hint: i,
19
+ helperText: n = !1
20
20
  }) => {
21
- const i = `mal-${k().replace(/[^a-zA-Z0-9_-]/g, "")}-`, p = r ?? `${i}control`, f = t ? `${i}label` : void 0, n = o ? `${i}description` : void 0, m = l ? `${i}hint` : void 0, c = s ? `${i}helper` : void 0, d = [n, m, c].filter(Boolean).join(" ") || void 0;
22
- return { controlId: p, labelId: f, descriptionId: n, hintId: m, helperTextId: c, describedBy: d };
23
- }, ee = ({
21
+ const l = `mal-${w().replace(/[^a-zA-Z0-9_-]/g, "")}-`, s = r ?? `${l}control`, p = t ? `${l}label` : void 0, d = o ? `${l}description` : void 0, m = i ? `${l}hint` : void 0, c = n ? `${l}helper` : void 0, f = [d, m, c].filter(Boolean).join(" ") || void 0;
22
+ return { controlId: s, labelId: p, descriptionId: d, hintId: m, helperTextId: c, describedBy: f };
23
+ }, re = ({
24
24
  label: r,
25
25
  hint: t,
26
- rightSideContent: o,
27
- tooltip: l,
28
- name: s,
29
- description: i,
26
+ hintIcon: o,
27
+ rightSideContent: i,
28
+ tooltip: n,
29
+ name: l,
30
+ description: s,
30
31
  required: p = !1,
31
- requiredIndicator: f = "optional-suffix",
32
- loading: n = !1,
33
- formControl: m,
34
- loadingComponent: c,
35
- children: d,
36
- controlId: v,
37
- labelId: b,
38
- descriptionId: I,
39
- hintId: N,
40
- fullWidth: g = !1
32
+ requiredIndicator: d = "optional-suffix",
33
+ loading: m = !1,
34
+ formControl: c,
35
+ loadingComponent: f,
36
+ children: x,
37
+ controlId: b,
38
+ labelId: I,
39
+ descriptionId: N,
40
+ hintId: g,
41
+ fullWidth: z = !1
41
42
  }) => {
42
- const z = m ? /* @__PURE__ */ e($, { control: m, name: s, children: d }) : H(d, R);
43
- return /* @__PURE__ */ a(x, { direction: "vertical", size: 6, align: "stretch", fullWidth: g, children: [
44
- (r || t || i || o) && /* @__PURE__ */ a(x, { direction: "vertical", size: 4, align: "stretch", children: [
43
+ const k = c ? /* @__PURE__ */ e(y, { control: c, name: l, children: x }) : R(x, L);
44
+ return /* @__PURE__ */ a(u, { direction: "vertical", size: 6, align: "stretch", fullWidth: z, children: [
45
+ (r || t || s || i) && /* @__PURE__ */ a(u, { direction: "vertical", size: 4, align: "stretch", children: [
45
46
  /* @__PURE__ */ a("div", { className: "flex justify-between items-start", children: [
46
47
  /* @__PURE__ */ e(
47
- E,
48
+ A,
48
49
  {
49
50
  text: r,
50
51
  required: p,
51
- requiredIndicator: f,
52
- tooltip: l,
53
- id: b,
54
- htmlFor: n ? void 0 : v
52
+ requiredIndicator: d,
53
+ tooltip: n,
54
+ id: I,
55
+ htmlFor: m ? void 0 : b
55
56
  }
56
57
  ),
57
- (t || o) && /* @__PURE__ */ a("div", { className: "flex items-start gap-2", children: [
58
- t && /* @__PURE__ */ e(B, { text: t, id: N }),
59
- o && /* @__PURE__ */ e(j, { ...o })
58
+ (t || i) && /* @__PURE__ */ a("div", { className: "flex items-start gap-2", children: [
59
+ t && /* @__PURE__ */ e(D, { text: t, icon: o, id: g }),
60
+ i && /* @__PURE__ */ e(B, { ...i })
60
61
  ] })
61
62
  ] }),
62
- i && /* @__PURE__ */ e(D, { text: i, id: I })
63
+ s && /* @__PURE__ */ e(E, { text: s, id: N })
63
64
  ] }),
64
- n ? c : z
65
+ m ? f : k
65
66
  ] });
66
- }, j = (r) => {
67
+ }, B = (r) => {
67
68
  if (r.type === "button")
68
69
  return /* @__PURE__ */ e(
69
70
  "button",
70
71
  {
71
72
  type: "button",
72
73
  onClick: r.onClick,
73
- className: `relative top-[3px] shrink-0 cursor-pointer whitespace-nowrap border-0 bg-transparent p-0 text-[length:var(--malachite-font-size-xsmall)] font-medium text-[var(--malachite-accent-foreground)] hover:underline ${u}`,
74
+ className: `relative top-[3px] shrink-0 cursor-pointer whitespace-nowrap border-0 bg-transparent p-0 text-[length:var(--malachite-font-size-xsmall)] font-medium text-[var(--malachite-accent-foreground)] hover:underline ${v}`,
74
75
  children: r.text
75
76
  }
76
77
  );
77
- const t = L(r.href);
78
+ const t = T(r.href);
78
79
  return t ? /* @__PURE__ */ a(
79
- y,
80
+ O,
80
81
  {
81
82
  href: t,
82
83
  target: "_blank",
@@ -87,19 +88,22 @@ const T = 0.5, q = ({
87
88
  className: "shrink-0 whitespace-nowrap inline-flex items-center gap-1 relative top-[3px]",
88
89
  children: [
89
90
  r.text,
90
- /* @__PURE__ */ e(w, { size: 13 })
91
+ /* @__PURE__ */ e(F, { size: 13 })
91
92
  ]
92
93
  }
93
94
  ) : null;
94
- }, B = ({ text: r, id: t }) => /* @__PURE__ */ e("span", { id: t, children: /* @__PURE__ */ e(h, { size: "xsmall", color: "dimmed", className: "pr-2 relative top-[3px]", children: r }) }), D = ({ text: r, id: t }) => /* @__PURE__ */ e("div", { className: "pl-2 text-left", id: t, children: /* @__PURE__ */ e(_, { color: "dimmed", size: "small", text: r ?? "", omitMargin: !0 }) }), E = ({
95
+ }, D = ({ text: r, icon: t, id: o }) => /* @__PURE__ */ a("span", { id: o, className: "inline-flex items-center gap-1 relative top-[3px] pr-2", children: [
96
+ t && /* @__PURE__ */ e("span", { "aria-hidden": "true", className: "inline-flex text-[var(--malachite-text-dimmed)]", children: t }),
97
+ /* @__PURE__ */ e(h, { size: "xsmall", color: "dimmed", children: r })
98
+ ] }), E = ({ text: r, id: t }) => /* @__PURE__ */ e("div", { className: "pl-2 text-left", id: t, children: /* @__PURE__ */ e(H, { color: "dimmed", size: "small", text: r ?? "", omitMargin: !0 }) }), A = ({
95
99
  text: r,
96
100
  required: t,
97
101
  requiredIndicator: o,
98
- tooltip: l,
99
- id: s,
100
- htmlFor: i
102
+ tooltip: i,
103
+ id: n,
104
+ htmlFor: l
101
105
  }) => r ? /* @__PURE__ */ a("div", { className: "flex items-center", children: [
102
- /* @__PURE__ */ e("label", { id: s, htmlFor: i, children: /* @__PURE__ */ e(h, { size: "xsmall", color: "primary", fontWeight: "semi-bold", className: "pl-2", children: r }) }),
106
+ /* @__PURE__ */ e("label", { id: n, htmlFor: l, children: /* @__PURE__ */ e(h, { size: "xsmall", color: "primary", fontWeight: "semi-bold", className: "pl-2", children: r }) }),
103
107
  o === "optional-suffix" && !t && /* @__PURE__ */ e("span", { "aria-hidden": "true", children: /* @__PURE__ */ e(h, { size: "xsmall", color: "dimmed", className: "ml-1", children: "(Optional)" }) }),
104
108
  o === "asterisk" && t && /* @__PURE__ */ e(
105
109
  "span",
@@ -109,18 +113,18 @@ const T = 0.5, q = ({
109
113
  children: "*"
110
114
  }
111
115
  ),
112
- l && /* @__PURE__ */ e(O, { text: l, placement: "right", delay: T, children: /* @__PURE__ */ e(
116
+ i && /* @__PURE__ */ e(_, { text: i, placement: "right", delay: j, children: /* @__PURE__ */ e(
113
117
  "button",
114
118
  {
115
119
  type: "button",
116
120
  "aria-label": `More information about ${r}`,
117
- className: `ml-1 -mt-[2px] inline-flex items-center text-[var(--malachite-text-dimmed)] cursor-help ${u}`,
118
- children: /* @__PURE__ */ e(F, { size: 14 })
121
+ className: `ml-1 -mt-[2px] inline-flex items-center text-[var(--malachite-text-dimmed)] cursor-help ${v}`,
122
+ children: /* @__PURE__ */ e($, { size: 14 })
119
123
  }
120
124
  ) })
121
125
  ] }) : /* @__PURE__ */ e("div", {});
122
126
  export {
123
- ee as default,
124
- q as useFormFieldIds
127
+ re as default,
128
+ ee as useFormFieldIds
125
129
  };
126
130
  //# sourceMappingURL=BaseFormComponent.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"BaseFormComponent.js","sources":["../../src/components/BaseFormComponent.tsx"],"sourcesContent":["import React, { useId } from 'react';\nimport type { Control, FieldPath, FieldValues } from 'react-hook-form';\nimport ArrowUpRightIcon from './CustomIcons/ArrowUpRightIcon';\nimport InfoFilledIcon from './CustomIcons/InfoFilledIcon';\nimport FormItem from './FormItem';\nimport Link from './Link';\nimport Spacer from './Spacer';\nimport Tooltip from './Tooltip';\nimport MarkdownBlock from './Typography/MarkdownBlock';\nimport Text from './Typography/Text';\nimport { FOCUS_RING } from './focusRing';\nimport { type FormItemChildren, NO_FIELD_ERROR, renderFormItemChildren } from './formItemState';\nimport { safeHref } from './safeHref';\n\n/** Tooltip's own default of 1s reads as broken; 0.5 matches the rest of the library. */\nconst TOOLTIP_DELAY_SECONDS = 0.5;\n\n/** The ids that wire a form field's label / description / hint to its control. */\nexport interface FormFieldIds {\n controlId: string;\n labelId?: string;\n descriptionId?: string;\n hintId?: string;\n helperTextId?: string;\n describedBy?: string;\n}\n\ninterface FormFieldIdOptions {\n /** A caller-supplied id always wins, so consumers can label the control themselves. */\n id?: string;\n label?: string;\n description?: string;\n hint?: string;\n helperText?: boolean;\n}\n\n/**\n * Generates the stable ids a form field needs to be announced correctly. Shared by\n * `Input`, `TextArea`, `Dropdown` and `MultiSelect` so all four wire up identically.\n */\nexport const useFormFieldIds = ({\n id,\n label,\n description,\n hint,\n helperText = false,\n}: FormFieldIdOptions): FormFieldIds => {\n // useId() emits \":r0:\", and a colon is invalid in a CSS id selector, so a consumer's\n // querySelector(`#${id}`) throws. Stripping only the delimiters keeps ids unique.\n const generatedId = `mal-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}-`;\n const controlId = id ?? `${generatedId}control`;\n const labelId = label ? `${generatedId}label` : undefined;\n const descriptionId = description ? `${generatedId}description` : undefined;\n const hintId = hint ? `${generatedId}hint` : undefined;\n const helperTextId = helperText ? `${generatedId}helper` : undefined;\n const describedBy =\n [descriptionId, hintId, helperTextId].filter(Boolean).join(' ') || undefined;\n\n return { controlId, labelId, descriptionId, hintId, helperTextId, describedBy };\n};\n\ninterface BaseFormComponentProps {\n label?: string;\n description?: string;\n hint?: string;\n rightSideContent?: RightSideContent;\n tooltip?: string;\n required?: boolean;\n requiredIndicator?: RequiredIndicator;\n name: FieldPath<FieldValues>;\n defaultValue?: string;\n loading?: boolean;\n formControl?: Control<FieldValues, unknown>;\n loadingComponent: React.ReactNode;\n children?: FormItemChildren;\n /** Accessibility wiring, from `useFormFieldIds` — see `FormFieldIds`. */\n controlId?: string;\n labelId?: string;\n descriptionId?: string;\n hintId?: string;\n fullWidth?: boolean;\n}\n\nconst BaseFormComponent: React.FC<BaseFormComponentProps> = ({\n label,\n hint,\n rightSideContent,\n tooltip,\n name,\n description,\n required = false,\n requiredIndicator = 'optional-suffix',\n loading = false,\n formControl,\n loadingComponent,\n children,\n controlId,\n labelId,\n descriptionId,\n hintId,\n fullWidth = false,\n}) => {\n const finalComponent = formControl ? (\n <FormItem control={formControl} name={name}>\n {children}\n </FormItem>\n ) : (\n renderFormItemChildren(children, NO_FIELD_ERROR)\n );\n\n const topHeader = () => (\n <Spacer direction=\"vertical\" size={4} align=\"stretch\">\n <div className=\"flex justify-between items-start\">\n <Label\n text={label}\n required={required}\n requiredIndicator={requiredIndicator}\n tooltip={tooltip}\n id={labelId}\n // No control is rendered while loading, so an htmlFor would be an orphan.\n htmlFor={loading ? undefined : controlId}\n />\n {(hint || rightSideContent) && (\n <div className=\"flex items-start gap-2\">\n {hint && <Hint text={hint} id={hintId} />}\n {rightSideContent && <RightSide {...rightSideContent} />}\n </div>\n )}\n </div>\n {description && <Description text={description} id={descriptionId} />}\n </Spacer>\n );\n\n const showHeader = label || hint || description || rightSideContent;\n\n return (\n <Spacer direction=\"vertical\" size={6} align=\"stretch\" fullWidth={fullWidth}>\n {showHeader && topHeader()}\n {!loading ? finalComponent : loadingComponent}\n </Spacer>\n );\n};\n\n/**\n * What sits at the far end of a field's label row. Data rather than a node, so nothing\n * arbitrary reaches the row; discriminated so a further kind is additive. Plain text is\n * already `hint`.\n */\nexport type RightSideContent =\n | {\n type?: 'link';\n text: string;\n href: string;\n }\n | {\n /** An action on the form itself, such as showing a panel of help beside it. */\n type: 'button';\n text: string;\n onClick: () => void;\n };\n\nconst RightSide = (content: RightSideContent) => {\n if (content.type === 'button') {\n return (\n <button\n type=\"button\"\n onClick={content.onClick}\n className={`relative top-[3px] shrink-0 cursor-pointer whitespace-nowrap border-0 bg-transparent p-0 text-[length:var(--malachite-font-size-xsmall)] font-medium text-[var(--malachite-accent-foreground)] hover:underline ${FOCUS_RING}`}\n >\n {content.text}\n </button>\n );\n }\n\n const safe = safeHref(content.href);\n\n if (!safe) {\n return null;\n }\n\n return (\n <Link\n href={safe}\n target=\"_blank\"\n rel=\"noopener noreferrer\"\n color=\"dimmed\"\n size=\"xsmall\"\n underline={false}\n className=\"shrink-0 whitespace-nowrap inline-flex items-center gap-1 relative top-[3px]\"\n >\n {content.text}\n <ArrowUpRightIcon size={13} />\n </Link>\n );\n};\n\nconst Hint = ({ text, id }: { text?: string; id?: string }) => {\n return (\n <span id={id}>\n <Text size=\"xsmall\" color=\"dimmed\" className=\"pr-2 relative top-[3px]\">\n {text}\n </Text>\n </span>\n );\n};\n\nconst Description = ({ text, id }: { text?: string; id?: string }) => {\n return (\n <div className=\"pl-2 text-left\" id={id}>\n <MarkdownBlock color=\"dimmed\" size=\"small\" text={text ?? ''} omitMargin={true} />\n </div>\n );\n};\n\nexport type RequiredIndicator = 'optional-suffix' | 'asterisk' | 'none';\n\nconst Label = ({\n text,\n required,\n requiredIndicator,\n tooltip,\n id,\n htmlFor,\n}: {\n text?: string;\n required: boolean;\n requiredIndicator: RequiredIndicator;\n tooltip?: string;\n id?: string;\n htmlFor?: string;\n}) => {\n return text ? (\n <div className=\"flex items-center\">\n <label id={id} htmlFor={htmlFor}>\n <Text size=\"xsmall\" color=\"primary\" fontWeight=\"semi-bold\" className=\"pl-2\">\n {text}\n </Text>\n </label>\n {/* Sibling of the <label>, not a child: Testing Library's getByLabelText matches\n on textContent, so a marker inside it breaks getByLabelText('<label>'). */}\n {requiredIndicator === 'optional-suffix' && !required && (\n <span aria-hidden=\"true\">\n <Text size=\"xsmall\" color=\"dimmed\" className=\"ml-1\">\n (Optional)\n </Text>\n </span>\n )}\n {requiredIndicator === 'asterisk' && required && (\n <span\n aria-hidden=\"true\"\n className=\"ml-1 text-[var(--malachite-destructive-foreground,rgb(196,62,62))]\"\n >\n *\n </span>\n )}\n {tooltip && (\n <Tooltip text={tooltip} placement=\"right\" delay={TOOLTIP_DELAY_SECONDS}>\n <button\n type=\"button\"\n aria-label={`More information about ${text}`}\n className={`ml-1 -mt-[2px] inline-flex items-center text-[var(--malachite-text-dimmed)] cursor-help ${FOCUS_RING}`}\n >\n <InfoFilledIcon size={14} />\n </button>\n </Tooltip>\n )}\n </div>\n ) : (\n <div />\n );\n};\n\nexport default BaseFormComponent;\n"],"names":["TOOLTIP_DELAY_SECONDS","useFormFieldIds","id","label","description","hint","helperText","generatedId","useId","controlId","labelId","descriptionId","hintId","helperTextId","describedBy","BaseFormComponent","rightSideContent","tooltip","name","required","requiredIndicator","loading","formControl","loadingComponent","children","fullWidth","finalComponent","jsx","FormItem","renderFormItemChildren","NO_FIELD_ERROR","jsxs","Spacer","Label","Hint","RightSide","Description","content","FOCUS_RING","safe","safeHref","Link","ArrowUpRightIcon","text","Text","MarkdownBlock","htmlFor","Tooltip","InfoFilledIcon"],"mappings":"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"}
1
+ {"version":3,"file":"BaseFormComponent.js","sources":["../../src/components/BaseFormComponent.tsx"],"sourcesContent":["import React, { useId } from 'react';\nimport type { Control, FieldPath, FieldValues } from 'react-hook-form';\nimport ArrowUpRightIcon from './CustomIcons/ArrowUpRightIcon';\nimport InfoFilledIcon from './CustomIcons/InfoFilledIcon';\nimport FormItem from './FormItem';\nimport Link from './Link';\nimport Spacer from './Spacer';\nimport Tooltip from './Tooltip';\nimport MarkdownBlock from './Typography/MarkdownBlock';\nimport Text from './Typography/Text';\nimport { FOCUS_RING } from './focusRing';\nimport { type FormItemChildren, NO_FIELD_ERROR, renderFormItemChildren } from './formItemState';\nimport { safeHref } from './safeHref';\n\n/** Tooltip's own default of 1s reads as broken; 0.5 matches the rest of the library. */\nconst TOOLTIP_DELAY_SECONDS = 0.5;\n\n/** The ids that wire a form field's label / description / hint to its control. */\nexport interface FormFieldIds {\n controlId: string;\n labelId?: string;\n descriptionId?: string;\n hintId?: string;\n helperTextId?: string;\n describedBy?: string;\n}\n\ninterface FormFieldIdOptions {\n /** A caller-supplied id always wins, so consumers can label the control themselves. */\n id?: string;\n label?: string;\n description?: string;\n hint?: string;\n helperText?: boolean;\n}\n\n/**\n * Generates the stable ids a form field needs to be announced correctly. Shared by\n * `Input`, `TextArea`, `Dropdown` and `MultiSelect` so all four wire up identically.\n */\nexport const useFormFieldIds = ({\n id,\n label,\n description,\n hint,\n helperText = false,\n}: FormFieldIdOptions): FormFieldIds => {\n // useId() emits \":r0:\", and a colon is invalid in a CSS id selector, so a consumer's\n // querySelector(`#${id}`) throws. Stripping only the delimiters keeps ids unique.\n const generatedId = `mal-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}-`;\n const controlId = id ?? `${generatedId}control`;\n const labelId = label ? `${generatedId}label` : undefined;\n const descriptionId = description ? `${generatedId}description` : undefined;\n const hintId = hint ? `${generatedId}hint` : undefined;\n const helperTextId = helperText ? `${generatedId}helper` : undefined;\n const describedBy =\n [descriptionId, hintId, helperTextId].filter(Boolean).join(' ') || undefined;\n\n return { controlId, labelId, descriptionId, hintId, helperTextId, describedBy };\n};\n\ninterface BaseFormComponentProps {\n label?: string;\n description?: string;\n hint?: string;\n /** Decorative, so it stays out of the accessible name; shown only with a `hint`. */\n hintIcon?: React.ReactNode;\n rightSideContent?: RightSideContent;\n tooltip?: string;\n required?: boolean;\n requiredIndicator?: RequiredIndicator;\n name: FieldPath<FieldValues>;\n defaultValue?: string;\n loading?: boolean;\n formControl?: Control<FieldValues, unknown>;\n loadingComponent: React.ReactNode;\n children?: FormItemChildren;\n /** Accessibility wiring, from `useFormFieldIds` — see `FormFieldIds`. */\n controlId?: string;\n labelId?: string;\n descriptionId?: string;\n hintId?: string;\n fullWidth?: boolean;\n}\n\nconst BaseFormComponent: React.FC<BaseFormComponentProps> = ({\n label,\n hint,\n hintIcon,\n rightSideContent,\n tooltip,\n name,\n description,\n required = false,\n requiredIndicator = 'optional-suffix',\n loading = false,\n formControl,\n loadingComponent,\n children,\n controlId,\n labelId,\n descriptionId,\n hintId,\n fullWidth = false,\n}) => {\n const finalComponent = formControl ? (\n <FormItem control={formControl} name={name}>\n {children}\n </FormItem>\n ) : (\n renderFormItemChildren(children, NO_FIELD_ERROR)\n );\n\n const topHeader = () => (\n <Spacer direction=\"vertical\" size={4} align=\"stretch\">\n <div className=\"flex justify-between items-start\">\n <Label\n text={label}\n required={required}\n requiredIndicator={requiredIndicator}\n tooltip={tooltip}\n id={labelId}\n // No control is rendered while loading, so an htmlFor would be an orphan.\n htmlFor={loading ? undefined : controlId}\n />\n {(hint || rightSideContent) && (\n <div className=\"flex items-start gap-2\">\n {hint && <Hint text={hint} icon={hintIcon} id={hintId} />}\n {rightSideContent && <RightSide {...rightSideContent} />}\n </div>\n )}\n </div>\n {description && <Description text={description} id={descriptionId} />}\n </Spacer>\n );\n\n const showHeader = label || hint || description || rightSideContent;\n\n return (\n <Spacer direction=\"vertical\" size={6} align=\"stretch\" fullWidth={fullWidth}>\n {showHeader && topHeader()}\n {!loading ? finalComponent : loadingComponent}\n </Spacer>\n );\n};\n\n/**\n * What sits at the far end of a field's label row. Data rather than a node, so nothing\n * arbitrary reaches the row; discriminated so a further kind is additive. Plain text is\n * already `hint`.\n */\nexport type RightSideContent =\n | {\n type?: 'link';\n text: string;\n href: string;\n }\n | {\n /** An action on the form itself, such as showing a panel of help beside it. */\n type: 'button';\n text: string;\n onClick: () => void;\n };\n\nconst RightSide = (content: RightSideContent) => {\n if (content.type === 'button') {\n return (\n <button\n type=\"button\"\n onClick={content.onClick}\n className={`relative top-[3px] shrink-0 cursor-pointer whitespace-nowrap border-0 bg-transparent p-0 text-[length:var(--malachite-font-size-xsmall)] font-medium text-[var(--malachite-accent-foreground)] hover:underline ${FOCUS_RING}`}\n >\n {content.text}\n </button>\n );\n }\n\n const safe = safeHref(content.href);\n\n if (!safe) {\n return null;\n }\n\n return (\n <Link\n href={safe}\n target=\"_blank\"\n rel=\"noopener noreferrer\"\n color=\"dimmed\"\n size=\"xsmall\"\n underline={false}\n className=\"shrink-0 whitespace-nowrap inline-flex items-center gap-1 relative top-[3px]\"\n >\n {content.text}\n <ArrowUpRightIcon size={13} />\n </Link>\n );\n};\n\nconst Hint = ({ text, icon, id }: { text?: string; icon?: React.ReactNode; id?: string }) => {\n return (\n <span id={id} className=\"inline-flex items-center gap-1 relative top-[3px] pr-2\">\n {icon && (\n <span aria-hidden=\"true\" className=\"inline-flex text-[var(--malachite-text-dimmed)]\">\n {icon}\n </span>\n )}\n <Text size=\"xsmall\" color=\"dimmed\">\n {text}\n </Text>\n </span>\n );\n};\n\nconst Description = ({ text, id }: { text?: string; id?: string }) => {\n return (\n <div className=\"pl-2 text-left\" id={id}>\n <MarkdownBlock color=\"dimmed\" size=\"small\" text={text ?? ''} omitMargin={true} />\n </div>\n );\n};\n\nexport type RequiredIndicator = 'optional-suffix' | 'asterisk' | 'none';\n\nconst Label = ({\n text,\n required,\n requiredIndicator,\n tooltip,\n id,\n htmlFor,\n}: {\n text?: string;\n required: boolean;\n requiredIndicator: RequiredIndicator;\n tooltip?: string;\n id?: string;\n htmlFor?: string;\n}) => {\n return text ? (\n <div className=\"flex items-center\">\n <label id={id} htmlFor={htmlFor}>\n <Text size=\"xsmall\" color=\"primary\" fontWeight=\"semi-bold\" className=\"pl-2\">\n {text}\n </Text>\n </label>\n {/* Sibling of the <label>, not a child: Testing Library's getByLabelText matches\n on textContent, so a marker inside it breaks getByLabelText('<label>'). */}\n {requiredIndicator === 'optional-suffix' && !required && (\n <span aria-hidden=\"true\">\n <Text size=\"xsmall\" color=\"dimmed\" className=\"ml-1\">\n (Optional)\n </Text>\n </span>\n )}\n {requiredIndicator === 'asterisk' && required && (\n <span\n aria-hidden=\"true\"\n className=\"ml-1 text-[var(--malachite-destructive-foreground,rgb(196,62,62))]\"\n >\n *\n </span>\n )}\n {tooltip && (\n <Tooltip text={tooltip} placement=\"right\" delay={TOOLTIP_DELAY_SECONDS}>\n <button\n type=\"button\"\n aria-label={`More information about ${text}`}\n className={`ml-1 -mt-[2px] inline-flex items-center text-[var(--malachite-text-dimmed)] cursor-help ${FOCUS_RING}`}\n >\n <InfoFilledIcon size={14} />\n </button>\n </Tooltip>\n )}\n </div>\n ) : (\n <div />\n );\n};\n\nexport default BaseFormComponent;\n"],"names":["TOOLTIP_DELAY_SECONDS","useFormFieldIds","id","label","description","hint","helperText","generatedId","useId","controlId","labelId","descriptionId","hintId","helperTextId","describedBy","BaseFormComponent","hintIcon","rightSideContent","tooltip","name","required","requiredIndicator","loading","formControl","loadingComponent","children","fullWidth","finalComponent","jsx","FormItem","renderFormItemChildren","NO_FIELD_ERROR","jsxs","Spacer","Label","Hint","RightSide","Description","content","FOCUS_RING","safe","safeHref","Link","ArrowUpRightIcon","text","icon","Text","MarkdownBlock","htmlFor","Tooltip","InfoFilledIcon"],"mappings":"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"}