@stackone/malachite 0.48.0 → 0.50.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. Use `overflow="clip"` to keep the rounded clipping while letting a `position: sticky` descendant still pin (`hidden` would trap it); `visible` disables clipping. _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 a scroll ancestor that clips without trapping sticky (e.g. `<Surface overflow="clip">`). `animate={false}` opens instantly. _Key props:_ `title` or `header`, `trailing`, `disabled`, `isExpanded`/`defaultExpanded`, `onToggle`, `stickyHeader`, `stickyTopOffset`, `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,11 +37,11 @@ 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`.
-- **`MultiSelect`** — Multi-select dropdown with chips, inline search, keyboard navigation, and per-option descriptions. Supports controlled (`value`) and uncontrolled (`defaultValue`) modes. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`, `chips`, `chipsRemovable`, `chipsMax`, `inlineSearch`, `defaultValue`, `name`, `description`, `tooltip`, `required`, `formControl`. _Base props:_ `options`, `value`, `onChange` (optional), `placeholder`, `searchable`, `size`, `width`, `disabled`, `error`, `loading`, `label`. _Option props:_ `disabled` (locked/non-removable), `badge` (right-aligned ReactNode in dropdown only), `description`, `descriptionMode` (`icon` | `subtitle` | `hover`), `descriptionIcon`, `descriptionMaxLines`.
+- **`MultiSelect`** — Multi-select dropdown. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`.
 
 ## Buttons & actions
 
@@ -54,12 +54,12 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
 - **`Alert`** — Inline alert/callout (info, success, warning, error).
 - **`StatusBadge`** — Large status indicator (e.g. success checkmark) for terminal/confirmation screens. _Key props:_ `type`.
 - **`StatBadge`** — Pill showing a numeric value with a label (e.g. "3 accounts selected"). _Key props:_ `count`, `label`.
-- **`Tag`** — Small status/label tag. Types: success, error, warning, default, primary, secondary, emphasis. _Key props:_ `value`, `type`, `paddingSize`, `textTransform`, `WidthSize`, `onRemove` (renders × close icon), `bordered`, `shadow`, `icon`, `iconPosition`.
+- **`Tag`** — Small status/label tag. Types: success, error, warning, default. _Key props:_ `value`, `type`, `paddingSize`, `textTransform`, `WidthSize`.
 - **`NumberTag`** — Compact numeric badge/counter.
 - **`Progress`** — Progress bar.
 - **`Spinner`** — Loading spinner.
 - **`Skeleton`** — Loading placeholders. Includes `Skeleton.Avatar` and `Skeleton.Input`.
-- **`Tooltip`** — Hover/focus tooltip; also works on disabled controls (see CLAUDE.md). _Key props:_ `text`, `delay`, `placement`, `maxWidth`, `wrapChildren`, `isShrinkable`, `fill`.
+- **`Tooltip`** — Hover/focus tooltip; also works on disabled controls (see CLAUDE.md).
 - **`TruncatedTooltip`** — Shows a tooltip only when its text is truncated.
 - **`Confetti`** — Celebratory confetti burst for success moments. _Key props:_ `pieces`.
 

package/dist/index.d.ts

@@ -23,6 +23,20 @@ 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 a scroll ancestor that clips without
+     * trapping sticky — e.g. a `<Surface overflow="clip">` (`overflow: hidden` traps it).
+     */
+    stickyHeader?: boolean;
+    /** Offset (px) from the top of the scroll container when `stickyHeader` is set. */
+    stickyTopOffset?: number;
+    /**
+     * 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 +252,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;
@@ -1388,6 +1409,13 @@ 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. Use `clip` to keep the rounded clipping WITHOUT creating a scroll
+     * container — so a `position: sticky` descendant still pins (unlike `hidden`,
+     * which traps it). `visible` disables clipping entirely.
+     */
+    overflow?: 'hidden' | 'visible' | 'clip';
     role?: default_2.AriaRole;
     'aria-label'?: string;
     'aria-labelledby'?: string;
@@ -1733,6 +1761,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). */