@stackone/malachite 0.47.1 → 0.49.0

package/COMPONENTS.md

@@ -6,7 +6,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 
 ## Layout & containers
 
-- **`Surface`** — Rounded, bordered card container with the standard elevation shadow. _Key props:_ `children`, `className`, `style`.
+- **`Surface`** — Rounded, bordered card container with the standard elevation shadow. Set `overflow="visible"` when a descendant must escape the card box (e.g. a sticky row). _Key props:_ `children`, `padding`, `overflow`, `className`, `style`.
 - **`SurfaceRow`** — A full-bleed row inside a Surface (used as `Surface.Row`). Owns hover highlight, colour transition and an optional bottom divider. Pass `onClick`/`href` to make the whole row clickable (renders as a real button/anchor, so keyboard nav works). For a selectable row use `role="radio"` + `selected` and put a presentational `<Radio>` inside as the indicator. _Key props:_ `divider`, `disabled`, `onClick`, `href`, `selected`, `role`, `className`, `style`.
 - **`Card`** — Generic content card.
 - **`SplitScreenLayout`** — Two-pane full-screen layout (content + preview/aside) with an optional dismiss button.
@@ -20,7 +20,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 ## Lists, rows & navigation
 
 - **`ButtonList`** — Vertical list of pill-style button/link rows with built-in hover/focus/active states. _Key props:_ `buttons[]` (`key`, `children`, `onClick`, `href`), `compact`.
-- **`Accordion`** — Expand/collapse section with a clickable header (disclosure arrow + title/header + trailing slot). Use `header` for rich content and `trailing` for an interactive control (e.g. a Checkbox) — trailing sits outside the toggle button, so a selectable+expandable row is just an Accordion. Controlled or uncontrolled. _Key props:_ `title` or `header`, `trailing`, `disabled`, `isExpanded`/`defaultExpanded`, `onToggle`.
+- **`Accordion`** — Expand/collapse section with a clickable header (disclosure arrow + title/header + trailing slot). Use `header` for rich content and `trailing` for an interactive control (e.g. a Checkbox) — trailing sits outside the toggle button, so a selectable+expandable row is just an Accordion. Controlled or uncontrolled. Pass `stickyHeader` (+ optional `stickyTopOffset`) to pin the header while the body scrolls — needs an unclipped scroll ancestor (e.g. `<Surface overflow="visible">`); `roundTop`/`roundBottom` round the first/last row inside such a Surface. _Key props:_ `title` or `header`, `trailing`, `disabled`, `isExpanded`/`defaultExpanded`, `onToggle`, `stickyHeader`, `stickyTopOffset`, `roundTop`, `roundBottom`, `animate`.
 - **`DefinitionRow`** — Row showing an icon, label, optional tag and description — for definition/detail lists. _Key props:_ `icon`, `label`, `tag`, `description`.
 - **`PreviewTree`** — Nested, indented tree for previewing hierarchical structure.
 - **`PreviewTreeRow`** — A single labelled row within a PreviewTree. _Key props:_ `label`.
@@ -37,7 +37,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 - **`Input`** — Single-line text input.
 - **`TextArea`** — Multi-line text input.
 - **`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. _Key props:_ `checked`, `indeterminate`, `disabled`, `onChange`.
+- **`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`.
 - **`Toggle`** — On/off switch.
 - **`Dropdown`** — Single-select dropdown. _Key props:_ `DropdownItem[]`, `DropdownSize`.

package/dist/index.d.ts

@@ -23,6 +23,24 @@ declare interface AccordionBaseProps {
     onToggle?: (expanded: boolean) => void;
     /** Disables the toggle (and its hover). Trailing controls manage their own state. */
     disabled?: boolean;
+    /**
+     * Pin the header row to the top of the nearest scroll container so it stays
+     * reachable while the body scrolls. Needs an unclipped scroll ancestor — e.g. a
+     * `<Surface overflow="visible">`, since `overflow: hidden` traps sticky.
+     */
+    stickyHeader?: boolean;
+    /** Offset (px) from the top of the scroll container when `stickyHeader` is set. */
+    stickyTopOffset?: number;
+    /** Round the top corners — for the first row inside an `overflow="visible"` Surface. */
+    roundTop?: boolean;
+    /** Round the bottom corners — for the last row inside an `overflow="visible"` Surface. */
+    roundBottom?: boolean;
+    /**
+     * Animate the expand/collapse height (default `true`). Set `false` for an instant
+     * open — the body isn't clipped, so a `position: sticky` child pins immediately with
+     * no post-animation settle.
+     */
+    animate?: boolean;
 }
 
 /**
@@ -238,9 +256,16 @@ export declare interface CheckboxProps {
     checked: boolean;
     /** Tri-state "partial" look — overrides the checked tick with a square. */
     indeterminate?: boolean;
-    onChange: (checked: boolean) => void;
+    /** Optional when `presentational` — a presentational checkbox is a visual indicator only. */
+    onChange?: (checked: boolean) => void;
     disabled?: boolean;
     size?: number;
+    /**
+     * Render a visual-only indicator (a non-interactive, non-focusable `<span>`,
+     * `aria-hidden`) instead of an interactive checkbox. Use this inside a clickable
+     * row/card whose wrapper is the real control, so there's a single tab stop.
+     */
+    presentational?: boolean;
     'aria-label'?: string;
     'aria-labelledby'?: string;
     className?: string;
@@ -977,16 +1002,13 @@ declare interface MarkdownProps {
 
 export declare const MultiSelect: default_2.FC<MultiSelectProps>;
 
-export declare interface MultiSelectOption {
-    value: string;
-    label: default_2.ReactNode;
-    searchText?: string;
-}
-
-export declare interface MultiSelectProps {
+declare interface MultiSelectBaseProps {
     options: MultiSelectOption[];
-    value: string[];
-    onChange: (next: string[]) => void;
+    /** Controlled value. When provided, component is fully controlled. */
+    value?: string[];
+    /** Initial value for uncontrolled usage (like Dropdown's defaultValue). */
+    defaultValue?: string[];
+    onChange?: (next: string[]) => void;
     placeholder?: string;
     renderTrigger?: (selected: MultiSelectOption[]) => default_2.ReactNode;
     searchable?: boolean;
@@ -997,10 +1019,48 @@ export declare interface MultiSelectProps {
     error?: boolean;
     loading?: boolean;
     label?: string;
+    description?: string;
+    tooltip?: string;
+    hint?: string;
+    required?: boolean;
+    /** Show selected values as chips instead of "N selected" text */
+    chips?: boolean;
+    /** Show × button on each chip to remove it (only when chips=true) */
+    chipsRemovable?: boolean;
+    /** Max visible chips. 'auto' = show all chips. Number = hard limit with "+N" badge */
+    chipsMax?: number | 'auto';
+    /** Search input inside the trigger field instead of external search bar */
+    inlineSearch?: boolean;
     className?: string;
     style?: default_2.CSSProperties;
 }
 
+export declare interface MultiSelectOption {
+    value: string;
+    label: default_2.ReactNode;
+    searchText?: string;
+    /** Prevent toggling or removing this option — used for mandatory/locked selections */
+    disabled?: boolean;
+    /** Right-aligned badge shown in the dropdown only (not in chips) */
+    badge?: default_2.ReactNode;
+    /** Description text for this option */
+    description?: string;
+    /** How description renders — 'icon': info icon with tooltip, 'subtitle': text below label, 'hover': tooltip on label. Default: 'icon' */
+    descriptionMode?: 'icon' | 'subtitle' | 'hover';
+    /** Custom icon for 'icon' mode. Default: built-in ⓘ */
+    descriptionIcon?: default_2.ReactNode;
+    /** Truncate subtitle after N lines. Only applies to 'subtitle' mode */
+    descriptionMaxLines?: number;
+}
+
+export declare type MultiSelectProps = (MultiSelectBaseProps & {
+    formControl: Control<FieldValues, unknown>;
+    name: string;
+}) | (MultiSelectBaseProps & {
+    formControl?: undefined;
+    name?: string;
+});
+
 export declare type MultiSelectSize = 'small' | 'medium';
 
 export declare const NumberTag: default_2.FC<NumberTagProps>;
@@ -1353,6 +1413,12 @@ declare interface SurfaceComponent extends default_2.FC<SurfaceProps> {
 export declare interface SurfaceProps {
     children?: default_2.ReactNode;
     padding?: boolean;
+    /**
+     * Content overflow. Defaults to `hidden` so children are clipped to the rounded
+     * corners. Set to `visible` when a descendant needs to escape the card box —
+     * e.g. a `position: sticky` row, which `overflow: hidden` would otherwise trap.
+     */
+    overflow?: 'hidden' | 'visible';
     role?: default_2.AriaRole;
     'aria-label'?: string;
     'aria-labelledby'?: string;
@@ -1542,6 +1608,7 @@ export declare interface TagProps {
     iconColor?: TextColor;
     pointerType?: 'pointer' | 'default';
     onClick?: () => void;
+    onRemove?: (e: default_2.MouseEvent) => void;
     className?: string;
 }
 
@@ -1649,6 +1716,8 @@ declare interface TooltipProps {
     placement?: 'top' | 'bottom' | 'left' | 'right';
     isShrinkable?: boolean;
     fill?: boolean;
+    /** Max width of tooltip. Default: 320px */
+    maxWidth?: number | string;
 }
 
 /**
@@ -1695,6 +1764,12 @@ export declare interface WizardLayoutProps {
     stepper?: default_2.ReactNode;
     /** Far-right top-bar slot — e.g. a theme toggle. */
     trailing?: default_2.ReactNode;
+    /**
+     * Pinned below the top bar and always visible while the content scrolls —
+     * e.g. connection logos + a step title. Rendered in the same centred column
+     * as the content (`contentWidth`).
+     */
+    header?: default_2.ReactNode;
     /** Pinned to the bottom of the screen — typically a <FooterNav />. */
     footer?: default_2.ReactNode;
     /** Vertically centre the content (used for terminal/success screens). */