@stackone/malachite 0.38.1 → 0.40.0

package/COMPONENTS.md

@@ -0,0 +1,84 @@
+<!-- GENERATED by `npm run docs:components` from scripts/component-catalog.mjs. Do not edit by hand. -->
+
+# Malachite components
+
+The catalog of components exported from `@stackone/malachite`. **Reach for one of these before hand-rolling UI** — see `CLAUDE.md` for why. Open the demo app and pick a component from the sidebar to see it live.
+
+## Layout & containers
+
+- **`Surface`** — Rounded, bordered card container with the standard elevation shadow. _Key props:_ `children`, `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.
+- **`WizardLayout`** — Full-screen wizard scaffold: top bar (back button, right-aligned stepper, trailing slot), centered content column, pinned footer. _Key props:_ `showBack`, `onBack`, `stepper`, `trailing`, `footer`, `center`, `contentWidth`, `minWidth`.
+- **`Flex`** — Flexbox layout helper with semantic direction/align/justify/gap props. _Key props:_ `FlexDirection`, `FlexAlign`, `FlexJustify`, `FlexGapSize`.
+- **`Padded`** — Padding wrapper applying consistent design-system spacing.
+- **`Spacer`** — Empty element that adds fixed spacing between siblings.
+- **`Divider`** — Horizontal/vertical separator; supports a dashed line style. _Key props:_ `lineStyle="solid" | "dashed"`, `DividerVariant`, `SpacingSize`, `PaddingSize`.
+- **`OverflowRow`** — Horizontal row that collapses items that do not fit into an overflow affordance.
+
+## 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`.
+- **`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`.
+- **`Tabs`** — Tabbed navigation switching between content panels. _Key props:_ `TabItem[]`.
+- **`ActionMenu`** — Dropdown menu of actions (kebab/overflow style). _Key props:_ `ActionMenuItem[]`.
+- **`FooterNav`** — Footer navigation bar of links. _Key props:_ `FooterNavLink[]`.
+- **`FooterLinks`** — Inline list of footer links (e.g. terms, privacy, support).
+
+## Forms & inputs
+
+- **`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.
+- **`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`.
+- **`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. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`.
+
+## Buttons & actions
+
+- **`Button`** — Primary button. Variants: `filled`, `outline`, `destructive`, `success`, `warning`, `error`, `ghost`, `no-style`. Supports `iconOnly`, `loading`, `tooltip`. _Key props:_ `variant`, `size`, `icon`, `iconOnly`, `loading`, `disabled`, `fill`, `tooltip`.
+- **`PillButton`** — Pill-shaped button, often used for filters/toggleable chips.
+- **`Link`** — Styled anchor/link text. _Key props:_ `LinkProps`.
+
+## Feedback & status
+
+- **`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. _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).
+- **`TruncatedTooltip`** — Shows a tooltip only when its text is truncated.
+- **`Confetti`** — Celebratory confetti burst for success moments. _Key props:_ `pieces`.
+
+## Data display
+
+- **`Table`** — Data table with columns, sizing, pagination and row selection. _Key props:_ `TableColumns`, `TableSize`, `TableType`, `TableRowSelection`, `TablePaginationPosition`.
+- **`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"`.
+- **`ConnectionHeader`** — Two tilted logo tiles (from → to) showing a connection between apps. _Key props:_ `from`, `to` (`ConnectionEndpoint`: `icon`, `label`, `background`).
+- **`CodeBlock`** — Syntax-styled code block. _Key props:_ `code`.
+- **`Stepper`** — Progress dots/segments for a multi-step flow; optionally clickable. _Key props:_ `steps`, `active`, `onChange`.
+- **`Swatch`** — Colour swatch preview.
+
+## Typography
+
+- **`Typography`** — Text primitives — use these instead of raw colour tokens on `<span>`s. Includes `Typography.Text`, `Typography.SecondaryText`, `Typography.EllipsisText`, etc., with size/weight/color props.
+
+## Theming & utility
+
+- **`MalachiteContext`** — Wraps a subtree in the shadow root + theme context. Wrap groups of components in this.
+- **`CustomIcons`** — Namespace of all built-in icons (`CustomIcons.<Name>Icon`), coloured via `currentColor`.
+- **`ShadowEscape`** — Renders children into the document (escaping the shadow root) for portals/overlays.

package/dist/index.d.ts

@@ -10,16 +10,33 @@ import { UseFormReturn } from 'react-hook-form';
 
 export declare const Accordion: default_2.FC<AccordionProps>;
 
-export declare interface AccordionProps {
-    title: string;
+declare interface AccordionBaseProps {
     className?: string;
     children?: default_2.ReactNode;
+    /**
+     * Content pinned to the right of the header, OUTSIDE the toggle button — so it may
+     * be interactive (e.g. a Checkbox) without nesting a button inside a button.
+     */
     trailing?: default_2.ReactNode;
     defaultExpanded?: boolean;
     isExpanded?: boolean;
     onToggle?: (expanded: boolean) => void;
+    /** Disables the toggle (and its hover). Trailing controls manage their own state. */
+    disabled?: boolean;
 }
 
+/**
+ * Requires at least one of `title` (simple text header) or `header` (rich ReactNode
+ * content for the toggle area, e.g. avatar + badges) so the toggle is never empty.
+ */
+export declare type AccordionProps = AccordionBaseProps & ({
+    title: string;
+    header?: default_2.ReactNode;
+} | {
+    title?: string;
+    header: default_2.ReactNode;
+});
+
 /**
  * ActionMenu is a kebab-style overflow action menu. The trigger renders a
  * three-dot icon button; on click, a popover appears with the given items.
@@ -86,6 +103,26 @@ export declare function applyLightTheme(): void;
  */
 export declare function applyTheme(theme: PartialMalachiteTheme): void;
 
+/**
+ * A logo/initial avatar. Renders `src` when available, otherwise a coloured tile
+ * with the first letter of `name`. Encapsulates the fallback colour so consumers
+ * never hand-roll it.
+ */
+export declare const Avatar: default_2.FC<AvatarProps>;
+
+export declare interface AvatarProps {
+    /** Image URL (logo/photo). Falls back to the initial of `name` when missing or it fails to load. */
+    src?: string;
+    /** Used for the initial fallback and as the image alt / accessible label. */
+    name?: string;
+    /** Pixel size of the (square) avatar. */
+    size?: number;
+    shape?: AvatarShape;
+    className?: string;
+}
+
+export declare type AvatarShape = 'square' | 'circle';
+
 export declare const BaseFormComponent: default_2.FC<BaseFormComponentProps>;
 
 declare interface BaseFormComponentProps {
@@ -1083,9 +1120,16 @@ export declare const Radio: default_2.FC<RadioProps>;
 
 export declare interface RadioProps {
     checked: boolean;
-    onChange: (checked: boolean) => void;
+    /** Optional when `presentational` — a presentational radio 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 radio. 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;
@@ -1284,7 +1328,11 @@ export declare interface StepperProps {
     'aria-label'?: string;
 }
 
-export declare const Surface: default_2.FC<SurfaceProps>;
+export declare const Surface: SurfaceComponent;
+
+declare interface SurfaceComponent extends default_2.FC<SurfaceProps> {
+    Row: default_2.FC<SurfaceRowProps>;
+}
 
 export declare interface SurfaceProps {
     children?: default_2.ReactNode;
@@ -1292,6 +1340,41 @@ export declare interface SurfaceProps {
     style?: default_2.CSSProperties;
 }
 
+/**
+ * A single full-bleed row inside a <Surface>. Owns the row chrome — hover
+ * highlight, colour transition and an optional bottom divider — so consumers
+ * compose their own content inside without re-implementing design-system styling.
+ * Pass `onClick`/`href` to make the entire row clickable (rendered as a real
+ * button/anchor, so keyboard navigation works natively).
+ */
+export declare const SurfaceRow: default_2.FC<SurfaceRowProps>;
+
+export declare interface SurfaceRowProps {
+    children?: default_2.ReactNode;
+    /** Renders a bottom divider — omit on the last row in a Surface. */
+    divider?: boolean;
+    /** Removes the hover affordance / disables the control (e.g. while loading/busy). */
+    disabled?: boolean;
+    /**
+     * When provided, the whole row becomes clickable: it renders as a `<button>`
+     * (or `<a>` when `href` is set), so the entire row is the click target with
+     * native focus + Enter/Space — no manual tabIndex/key handlers. For a
+     * selectable row, put a presentational `<Radio>`/`<Checkbox>` inside as the
+     * visual indicator; do NOT nest an interactive control (invalid + double tab stop).
+     */
+    onClick?: (event: default_2.MouseEvent) => void;
+    /** Renders the clickable row as an anchor instead of a button. */
+    href?: string;
+    /** Selected state. Drives `aria-checked` when `role` is `radio`/`checkbox`. */
+    selected?: boolean;
+    /** ARIA role for a clickable row, e.g. `radio`/`checkbox` (wrap the list in a `radiogroup`). */
+    role?: default_2.AriaRole;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    className?: string;
+    style?: default_2.CSSProperties;
+}
+
 export declare const Swatch: default_2.FC<SwatchProps>;
 
 export declare interface SwatchProps {