@instruments/materia-ui 0.4.8 → 0.4.10

package/agent-docs.md

@@ -14,7 +14,7 @@ Do and don't guidance for coding agents, one section per component, taken from `
 - Import icons through `Icon` and primitives through these components, never from `lucide-react` or `@base-ui/react` directly.
 - Check your work with the `materia-ui-lint` class scanner (`--all` for every rule). The Oxlint preset is `@instruments/materia-ui/lint/oxlint`.
 
-Documented components: 197
+Documented components: 198
 
 ## AccordionRoot
 
@@ -88,7 +88,7 @@ Constrains its content to a fixed width-to-height ratio, sizing itself to the av
 
 AttributeCard UI component. Import from "@instruments/materia-ui/compositions/attribute-card".
 
-- Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+- Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
 - Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
 - This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
 
@@ -1478,6 +1478,8 @@ A scrolling region that shows where there is more: each edge fades only while co
 - Give a vertical frame a bounded height (`className="h-80"`); a horizontal one needs only a bounded width, which a flex child with `min-w-0` already has.
 - Match `fadeTheme` to the surface behind the frame (`card` inside a Card). Over an image or a blur, use `fadeMode="mask"` instead.
 - For a horizontal strip used with a mouse, add `dragScroll` and `controls`; both stand aside on touch screens, and each control hides at the end it points to.
+- Every scrolling region in an app is a `ScrollFrame`, not a hand-rolled `overflow-y-auto` div: a pane, a list in a popover, a wide table (`orientation="both"`). A frame capped by `max-h-*` alone scrolls once its content passes the cap.
+- Hand a virtualiser the scrolling element through `viewportRef`.
 
 ## SearchInput
 
@@ -1688,7 +1690,7 @@ Root component for a sidepanel. Wraps Base UI Dialog.Root.
 
 `@instruments/materia-ui/components/sidepanel`
 
-The scrolling region between a `SidepanelHeader` and `SidepanelFooter`: takes the remaining height of `SidepanelBody`, scrolls on its own and carries the panel's standard inset, so header and footer stay put while it moves.
+The scrolling region between a `SidepanelHeader` and `SidepanelFooter`, a `ScrollFrame`: takes the remaining height of `SidepanelBody`, scrolls on its own and carries the panel's standard inset, so header and footer stay put while it moves.
 
 - Put exactly one `SidepanelScroll` inside `SidepanelBody`, between the header and footer, rather than a hand-rolled `flex-1 overflow-y-auto` div.
 
@@ -1780,6 +1782,15 @@ Orchestrates staggered entrance animations for child `StaggerItem` components. U
 - Tune rhythm with `stagger` (gap between items) and `delay` (lead-in) on the parent, rather than hand-setting per-child transition delays.
 - Needs `ReducedMotionProvider` in the tree so the orchestrated entrance both runs and honours the reduced-motion setting.
 
+## Stat
+
+`@instruments/materia-ui/components/stat`
+
+A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a page's figures match without setting a size or weight at the call site. Import from "@instruments/materia-ui/components/stat".
+
+- Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+- Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+
 ## Stepper
 
 `@instruments/materia-ui/components/stepper`
@@ -1887,7 +1898,7 @@ Renders a toggle switch for boolean on/off states.
 
 `@instruments/materia-ui/components/table`
 
-Semantic `<table>` primitive, wrapped in a horizontally scrollable container so wide tables overflow rather than break layout. Compose with the exported `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, and `TableCaption` parts.
+Semantic `<table>` primitive, wrapped in a horizontal `ScrollFrame` so wide tables overflow rather than break layout. Compose with the exported `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableFooter`, and `TableCaption` parts.
 
 - Use `Table` for a small, static, hand-authored table; reach for `DataGrid` once you need sorting, filtering, pagination, column pinning/visibility, or row virtualisation - `Table` has no data model.
 - Include a `TableCaption` describing the table's contents - it is the accessible name screen readers announce for the `<table>`.

package/dist/components/code/code-root.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 export interface CodeProps extends React.ComponentProps<"code"> {
     /**
      * Render a multi-line block (`<pre><code>`) instead of inline `<code>`. The
-     * block scrolls horizontally rather than wrapping. @default false
+     * block scrolls horizontally, in a `ScrollFrame`, rather than wrapping. @default false
      */
     block?: boolean;
 }

package/dist/components/code/code-root.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import * as React from "react";
+import { ScrollFrame } from "../scroll-frame.js";
 /**
  * Monospace code - inline `<code>` by default (a muted, rounded chip sized to
  * surrounding text), or a scrollable `<pre><code>` block when `block` is set.
@@ -11,7 +12,9 @@ import * as React from "react";
  */
 export const Code = ({ block = false, className, children, ...props }) => {
     if (block) {
-        return (_jsx("pre", { className: cn("border-border bg-muted text-paragraph-sm overflow-x-auto rounded-lg border p-4 font-mono", className), "data-block": "true", "data-component": "code", children: _jsx("code", { ...props, children: children }) }));
+        // The block is as wide as its longest line, so a long line scrolls the frame and the padding travels with it;
+        // with `whitespace-pre-wrap` it is the frame's width and wraps.
+        return (_jsx(ScrollFrame, { className: "border-border bg-muted rounded-lg border", contentClassName: "min-w-0!", fadeTheme: "muted", orientation: "horizontal", children: _jsx("pre", { className: cn("text-paragraph-sm w-fit min-w-full p-4 font-mono", className), "data-block": "true", "data-component": "code", children: _jsx("code", { ...props, children: children }) }) }));
     }
     return (_jsx("code", { className: cn("bg-muted text-paragraph-sm rounded-sm px-1 py-0.5 font-mono", className), "data-component": "code", ...props, children: children }));
 };

package/dist/components/combobox/combobox-root.js

@@ -10,6 +10,7 @@ import { CheckIcon, ChevronsUpDownIcon, SearchIcon } from "lucide-react";
 import { useImperativeHandle, useRef, useState } from "react";
 import { useControllableState } from "../../hooks/use-controllable-state.js";
 import { POPOVER_CONTENT_ANIMATION, POPOVER_SURFACE, } from "../../tokens/overlay-styles.js";
+import { ScrollFrame } from "../scroll-frame.js";
 const OPTION_CLASSES = "data-highlighted:bg-muted data-highlighted:text-accent-foreground relative flex w-full cursor-default items-center rounded-full py-2.5 pr-8 pl-4 text-paragraph-sm outline-hidden select-none";
 /** A single selectable option row, shared by virtualised and plain lists. */
 const ComboboxOption = ({ item, className, ...props }) => (_jsxs(ComboboxPrimitive.Item, { className: cn(OPTION_CLASSES, className), "data-slot": "combobox-item", value: item, ...props, children: [item.label, _jsx(ComboboxPrimitive.ItemIndicator, { className: "absolute right-2 flex size-4 items-center justify-center", children: _jsx(Icon, { icon: CheckIcon, size: "xs" }) })] }));
@@ -33,7 +34,7 @@ const VirtualizedOptions = ({ virtualization, virtualizerRef, }) => {
         overscan: virtualization.overscan ?? 8,
     });
     useImperativeHandle(virtualizerRef, () => rowVirtualizer);
-    return (_jsx("div", { className: "overflow-y-auto overscroll-contain", ref: setScrollEl, role: "presentation", style: { maxHeight: virtualization.maxHeightPx ?? 300 }, children: _jsx("div", { className: "relative w-full", role: "presentation", style: { height: rowVirtualizer.getTotalSize() }, children: rowVirtualizer.getVirtualItems().map((virtualRow) => {
+    return (_jsx(ScrollFrame, { fadeTheme: "popover", fades: "end", role: "presentation", style: { maxHeight: virtualization.maxHeightPx ?? 300 }, viewportRef: setScrollEl, children: _jsx("div", { className: "relative w-full", role: "presentation", style: { height: rowVirtualizer.getTotalSize() }, children: rowVirtualizer.getVirtualItems().map((virtualRow) => {
                 const item = filteredItems[virtualRow.index];
                 if (!item) {
                     return null;
@@ -105,6 +106,5 @@ export const Combobox = ({ items, value, onValueChange, placeholder = "Select…
             // It renders the kit's Button, a native <button>.
             , { 
                 // It renders the kit's Button, a native <button>.
-                nativeButton: true, render: _jsx(ComboboxTriggerButton, { className: buttonClassName, "data-testid": dataTestId, size: size }), children: selected?.label ?? placeholder }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsxs(ComboboxPrimitive.Popup, { "aria-label": placeholder, className: cn(`${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-(--anchor-width) min-w-32 origin-(--transform-origin) rounded-3xl`, contentClassName), "data-component": "combobox-content", "data-slot": "combobox-content", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", "data-slot": "combobox-input-wrapper", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: SearchIcon, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden disabled:cursor-not-allowed disabled:opacity-50", "data-slot": "combobox-input", placeholder: "Search\u2026" })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", "data-slot": "combobox-empty", children: "No results found." }), _jsx(ComboboxPrimitive.List, { className: cn("p-1 empty:p-0", !shouldVirtualize &&
-                                    "max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto"), children: shouldVirtualize && virtualization ? (_jsx(VirtualizedOptions, { virtualization: virtualization, virtualizerRef: virtualizerRef })) : ((item) => (_jsx(ComboboxOption, { item: item }, item.value))) })] }) }) })] }));
+                nativeButton: true, render: _jsx(ComboboxTriggerButton, { className: buttonClassName, "data-testid": dataTestId, size: size }), children: selected?.label ?? placeholder }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsxs(ComboboxPrimitive.Popup, { "aria-label": placeholder, className: cn(`${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-(--anchor-width) min-w-32 origin-(--transform-origin) rounded-3xl`, contentClassName), "data-component": "combobox-content", "data-slot": "combobox-content", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", "data-slot": "combobox-input-wrapper", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: SearchIcon, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden disabled:cursor-not-allowed disabled:opacity-50", "data-slot": "combobox-input", placeholder: "Search\u2026" })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", "data-slot": "combobox-empty", children: "No results found." }), shouldVirtualize && virtualization ? (_jsx(ComboboxPrimitive.List, { className: "p-1 empty:p-0", children: _jsx(VirtualizedOptions, { virtualization: virtualization, virtualizerRef: virtualizerRef }) })) : (_jsx(ScrollFrame, { className: "max-h-75", fadeTheme: "popover", fades: "end", children: _jsx(ComboboxPrimitive.List, { className: "scroll-py-1 p-1 empty:p-0", children: (item) => (_jsx(ComboboxOption, { item: item }, item.value)) }) }))] }) }) })] }));
 };

package/dist/components/command/command-list.d.ts

@@ -1,7 +1,7 @@
 import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
 import type * as React from "react";
 /**
- * CommandList is the scrollable container for a Command's filtered items.
+ * CommandList is the scrolling container for a Command's filtered items, in a `ScrollFrame` capped at 300px.
  * Pass a function child: it receives each filtered item (or group, for grouped
  * `items`) and returns a `CommandItem` (or `CommandGroup`).
  * Import from "@instruments/materia-ui/components/command".

package/dist/components/command/command-list.js

@@ -2,10 +2,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
 import { cn } from "@instruments/materia-ui/utils/cn";
+import { ScrollFrame } from "../scroll-frame.js";
 /**
- * CommandList is the scrollable container for a Command's filtered items.
+ * CommandList is the scrolling container for a Command's filtered items, in a `ScrollFrame` capped at 300px.
  * Pass a function child: it receives each filtered item (or group, for grouped
  * `items`) and returns a `CommandItem` (or `CommandGroup`).
  * Import from "@instruments/materia-ui/components/command".
  */
-export const CommandList = ({ className, ...props }) => (_jsx(AutocompletePrimitive.List, { className: cn("max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain empty:hidden", className), "data-component": "command-list", "data-slot": "command-list", ...props }));
+export const CommandList = ({ className, ...props }) => (_jsx(ScrollFrame, { className: "max-h-75 shrink-0", fadeTheme: "popover", fades: "end", children: _jsx(AutocompletePrimitive.List, { className: cn("scroll-py-1 empty:hidden", className), "data-component": "command-list", "data-slot": "command-list", ...props }) }));

package/dist/components/location-input/location-input-root.js

@@ -9,6 +9,7 @@ import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
 import { Button } from "../button.js";
 import { Icon } from "../icon.js";
 import { MenuItem } from "../menu-item.js";
+import { ScrollFrame } from "../scroll-frame.js";
 import { useLocationInput } from "./use-location-input.js";
 /** Default LocationInput size. */
 const DEFAULT_LOCATION_INPUT_SIZE = "xl";
@@ -34,6 +35,11 @@ export const LOCATION_INPUT_SIZE_CLASSES = {
 };
 const inputWrapperVariants = cva(INPUT_WRAPPER);
 const inputVariants = cva(INPUT_CONTROL_RESET);
+/** The suggestions under the field, in a frame that scrolls past ten or so. */
+const Suggestions = ({ onSelect, predictions, }) => (_jsx(ScrollFrame, { className: "bg-popover absolute inset-x-0 top-full z-50 max-h-60 rounded-3xl border shadow-xs", fadeTheme: "popover", fades: "end", children: _jsx("ul", { className: "m-0 list-none p-0", children: predictions.map((prediction) => (_jsx("li", { children: _jsx(MenuItem, { className: "hover:bg-muted hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground rounded-full px-4 py-2.5", onClick: () => {
+                    onSelect(prediction.placeId);
+                }, children: _jsxs("span", { children: [_jsx("span", { className: "font-medium", children: prediction.mainText }), prediction.secondaryText !== undefined &&
+                            prediction.secondaryText !== "" ? (_jsx("span", { className: "text-muted-foreground ml-1", children: prediction.secondaryText })) : null] }) }) }, prediction.placeId))) }) }));
 /**
  * Location autocomplete input with a dropdown of suggestions for city or
  * address search. The geocoder is injected: pass `search` (query to
@@ -79,8 +85,7 @@ export const LocationInput = ({ value, onChange, mode = "city", placeholder, siz
                 // Mirrors focusInput() default in focus-within form (see token JSDoc).
                 "focus-within:border-ring overflow-hidden rounded-md focus-within:ring-3 focus-within:ring-gray-500/80", hasError === true && hasErrorInput, disabled === true && "pointer-events-none opacity-50"), "data-component": "location-input", "data-testid": testId, children: [_jsx(Icon, { className: "text-muted-foreground shrink-0", icon: MapPin, size: "xs" }), _jsx("input", { "aria-label": "Search location", className: cn(inputVariants(), getResponsiveSizeClasses(size, LOCATION_INPUT_SIZE_CLASSES, DEFAULT_LOCATION_INPUT_SIZE)), disabled: disabled, id: id, onChange: (event) => {
                             handleInputChange(event.target.value);
-                        }, onFocus: handleFocus, placeholder: effectivePlaceholder, type: "text", value: query }), hasValue && disabled !== true ? (_jsx(Button, { "aria-label": "Clear location", className: "text-muted-foreground hover:text-foreground", emphasis: "ghost", icon: X, onClick: handleClear, radius: "rounded", size: "icon-2xs", square: true, tone: "neutral", type: "button" })) : null, isLoading ? (_jsx("span", { className: "text-muted-foreground text-caption shrink-0", children: "\u2026" })) : null] }), isOpen && disabled !== true && predictions.length > 0 ? (_jsx("ul", { className: "bg-popover absolute inset-x-0 top-full z-50 m-0 max-h-60 list-none overflow-auto rounded-3xl border p-0 shadow-xs", children: predictions.map((prediction) => (_jsx("li", { children: _jsx(MenuItem, { className: "hover:bg-muted hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground rounded-full px-4 py-2.5", onClick: () => {
-                            void select(prediction.placeId);
-                        }, children: _jsxs("span", { children: [_jsx("span", { className: "font-medium", children: prediction.mainText }), prediction.secondaryText !== undefined &&
-                                    prediction.secondaryText !== "" ? (_jsx("span", { className: "text-muted-foreground ml-1", children: prediction.secondaryText })) : null] }) }) }, prediction.placeId))) })) : null] }));
+                        }, onFocus: handleFocus, placeholder: effectivePlaceholder, type: "text", value: query }), hasValue && disabled !== true ? (_jsx(Button, { "aria-label": "Clear location", className: "text-muted-foreground hover:text-foreground", emphasis: "ghost", icon: X, onClick: handleClear, radius: "rounded", size: "icon-2xs", square: true, tone: "neutral", type: "button" })) : null, isLoading ? (_jsx("span", { className: "text-muted-foreground text-caption shrink-0", children: "\u2026" })) : null] }), isOpen && disabled !== true && predictions.length > 0 ? (_jsx(Suggestions, { onSelect: (placeId) => {
+                    void select(placeId);
+                }, predictions: predictions })) : null] }));
 };

package/dist/components/scroll-frame/scroll-frame-root.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentSize } from "@instruments/materia-ui/tokens/size";
-import type { ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import type { Orientation } from "../../tokens/orientation.js";
 import type { ScrollFadeProps } from "../scroll-fade/scroll-fade-root.js";
 /** Which edges may fade. */
@@ -11,11 +11,20 @@ export type ScrollFrameFades = "both" | "end" | "none" | "start";
  * match.
  */
 export type ScrollFrameFadeMode = "color" | "mask";
-export interface ScrollFrameProps {
+/** Which way the frame scrolls: one axis, or both, as for a wide table. */
+export type ScrollFrameOrientation = Orientation | "both";
+export interface ScrollFrameProps extends Omit<ComponentPropsWithoutRef<"div">, "aria-label" | "children" | "className"> {
     /** Names the frame; it becomes a labelled region. */
     "aria-label"?: string | undefined;
     children: ReactNode;
     className?: string | undefined;
+    /**
+     * Classes for the element holding the children, inside the scrolling one.
+     * A vertical frame's content is already as wide as the frame, so text wraps
+     * and `w-full` children fill it; a horizontal or two-way frame's content is
+     * as wide as its widest child.
+     */
+    contentClassName?: string | undefined;
     /**
      * Previous and next buttons at the edges, each shown while there is more
      * that way. They step most of a viewport, and stay hidden on touch screens,
@@ -56,12 +65,14 @@ export interface ScrollFrameProps {
      */
     hideScrollbar?: boolean | undefined;
     /**
-     * Scroll axis: `vertical` scrolls up and down, `horizontal` left and right, as for a row of chips.
+     * Scroll axis: `vertical` scrolls up and down, `horizontal` left and right, as for a row of chips, and `both` either way, as for a wide table. Controls and drag follow the vertical axis when both scroll.
      * @default "vertical"
      */
-    orientation?: Orientation | undefined;
+    orientation?: ScrollFrameOrientation | undefined;
     /** Classes for the scrolling element. */
     viewportClassName?: string | undefined;
+    /** The scrolling element, for a virtualiser or anything else that reads or sets its scroll position. */
+    viewportRef?: Ref<HTMLDivElement | null> | undefined;
 }
 /**
  * A scrolling region that shows where there is more: each edge fades only
@@ -80,6 +91,8 @@ export interface ScrollFrameProps {
  * @bestPractice Give a vertical frame a bounded height (`className="h-80"`); a horizontal one needs only a bounded width, which a flex child with `min-w-0` already has.
  * @bestPractice Match `fadeTheme` to the surface behind the frame (`card` inside a Card). Over an image or a blur, use `fadeMode="mask"` instead.
  * @bestPractice For a horizontal strip used with a mouse, add `dragScroll` and `controls`; both stand aside on touch screens, and each control hides at the end it points to.
+ * @bestPractice Every scrolling region in an app is a `ScrollFrame`, not a hand-rolled `overflow-y-auto` div: a pane, a list in a popover, a wide table (`orientation="both"`). A frame capped by `max-h-*` alone scrolls once its content passes the cap.
+ * @bestPractice Hand a virtualiser the scrolling element through `viewportRef`.
  * @category layout
  */
-export declare const ScrollFrame: ({ "aria-label": ariaLabel, children, className, controls, dragScroll, fadeMode, fades, fadeSize, fadeTheme, hideScrollbar, orientation, viewportClassName, }: ScrollFrameProps) => import("react").JSX.Element;
+export declare const ScrollFrame: ({ "aria-label": ariaLabel, children, className, contentClassName, controls, dragScroll, fadeMode, fades, fadeSize, fadeTheme, hideScrollbar, orientation, viewportClassName, viewportRef, ...props }: ScrollFrameProps) => import("react").JSX.Element;

package/dist/components/scroll-frame/scroll-frame-root.js

@@ -4,7 +4,7 @@ import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
 import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { ChevronDown, ChevronLeft, ChevronRight, ChevronUp, } from "lucide-react";
-import { useState } from "react";
+import { useImperativeHandle, useState } from "react";
 import { useDragScroll } from "../../hooks/use-drag-scroll.js";
 import { useScrollEdges } from "../../hooks/use-scroll-edges.js";
 import { Button } from "../button.js";
@@ -23,12 +23,15 @@ const FADE_LENGTH = {
     xs: "0.75rem",
 };
 const fadesEdge = (fades, edge) => fades === "both" || fades === edge;
-const maskStyle = (orientation, length, start, end) => {
-    const direction = orientation === "horizontal" ? "to right" : "to bottom";
+/** The axes a frame scrolls along. */
+const axesOf = (orientation) => orientation === "both" ? ["vertical", "horizontal"] : [orientation];
+/** The one axis that controls and drag move: vertical when both scroll. */
+const leadAxis = (orientation) => orientation === "horizontal" ? "horizontal" : "vertical";
+const maskRamp = (axis, length, start, end) => {
+    const direction = axis === "horizontal" ? "to right" : "to bottom";
     const from = start ? length : "0px";
     const to = end ? length : "0px";
-    const image = `linear-gradient(${direction}, transparent, black ${from}, black calc(100% - ${to}), transparent)`;
-    return { WebkitMaskImage: image, maskImage: image };
+    return `linear-gradient(${direction}, transparent, black ${from}, black calc(100% - ${to}), transparent)`;
 };
 const prefersReducedMotion = () => globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
 const CONTROL_ICONS = {
@@ -60,20 +63,39 @@ const moreOf = (edges) => ({
     end: edges.scrollable && !edges.atEnd,
     start: edges.scrollable && !edges.atStart,
 });
-/** The viewport's mask in mask mode; nothing in colour mode. */
-const frameMask = (fadeMode, orientation, fadeSize, fades, more) => fadeMode === "mask"
-    ? maskStyle(orientation, FADE_LENGTH[fadeSize], more.start && fadesEdge(fades, "start"), more.end && fadesEdge(fades, "end"))
-    : undefined;
+/** The viewport's mask in mask mode, one ramp per axis intersected; nothing in colour mode. */
+const frameMask = (fadeMode, orientation, fadeSize, fades, more) => {
+    if (fadeMode !== "mask") {
+        return undefined;
+    }
+    const image = axesOf(orientation)
+        .map((axis) => maskRamp(axis, FADE_LENGTH[fadeSize], more[axis].start && fadesEdge(fades, "start"), more[axis].end && fadesEdge(fades, "end")))
+        .join(", ");
+    return orientation === "both"
+        ? {
+            maskComposite: "intersect",
+            maskImage: image,
+            WebkitMaskComposite: "source-in",
+            WebkitMaskImage: image,
+        }
+        : { maskImage: image, WebkitMaskImage: image };
+};
 /** The colour fades, each shown while there is more beyond its edge. */
-const Fades = ({ fades, fadeSize, fadeTheme, more, orientation, }) => EDGES.filter((edge) => fadesEdge(fades, edge)).map((edge) => (_jsx(ScrollFade, { className: cn("duration-normal transition-opacity motion-reduce:transition-none", !more[edge] && "opacity-0"), "data-slot": "scroll-frame-fade", orientation: orientation, position: edge, size: fadeSize, theme: fadeTheme }, edge)));
+const Fades = ({ fades, fadeSize, fadeTheme, more, orientation, }) => axesOf(orientation).flatMap((axis) => EDGES.filter((edge) => fadesEdge(fades, edge)).map((edge) => (_jsx(ScrollFade, { className: cn("duration-normal transition-opacity motion-reduce:transition-none", !more[axis][edge] && "opacity-0"), "data-slot": "scroll-frame-fade", orientation: axis, position: edge, size: fadeSize, theme: fadeTheme }, `${axis}-${edge}`))));
 /** Previous and next, each shown while there is more its way. */
 const Controls = ({ more, orientation, viewport, }) => EDGES.map((edge) => (_jsx(Button, { "aria-label": edge === "start" ? "Scroll back" : "Scroll on", className: cn("duration-normal absolute z-20 transition-opacity after:absolute after:-inset-1.5 motion-reduce:transition-none pointer-coarse:hidden", CONTROL_PLACEMENT[orientation][edge], !more[edge] && "pointer-events-none opacity-0"), "data-slot": "scroll-frame-control", emphasis: "outline", icon: CONTROL_ICONS[orientation][edge], onClick: () => {
         stepBy(viewport, orientation, edge);
     }, radius: "full", size: "icon-sm", square: true, tabIndex: more[edge] ? undefined : -1, tone: "neutral", type: "button" }, edge)));
 /** The scrolling element and its content, which a mouse can drag. */
-const Viewport = ({ children, className, dragScroll, mask, onViewport, orientation, scrollable, viewport, }) => {
-    const drag = useDragScroll(viewport, orientation, { enabled: dragScroll });
-    return (_jsx(ScrollAreaPrimitive.Viewport, { className: cn(focusRing(), "rounded-inherit size-full focus-visible:ring-inset", className), "data-slot": "scroll-frame-viewport", ref: onViewport, style: mask, children: _jsx(ScrollAreaPrimitive.Content, { className: cn(dragScroll && scrollable && "cursor-grab", drag.dragging && "cursor-grabbing select-none"), "data-dragging": drag.dragging ? "" : undefined, ...drag.handlers, children: children }) }));
+const Viewport = ({ children, className, contentClassName, dragScroll, mask, onViewport, orientation, scrollable, viewport, }) => {
+    const drag = useDragScroll(viewport, leadAxis(orientation), {
+        enabled: dragScroll,
+    });
+    return (_jsx(ScrollAreaPrimitive.Viewport, { className: cn(focusRing(), 
+        // A frame sized only by max-height still scrolls: the viewport takes that cap as its own.
+        "rounded-inherit size-full max-h-[inherit] focus-visible:ring-inset", className), "data-slot": "scroll-frame-viewport", ref: onViewport, style: mask, children: _jsx(ScrollAreaPrimitive.Content, { className: cn(
+            // Base UI sizes the content to its widest child; a vertical frame lays out at its own width.
+            orientation === "vertical" && "min-w-0!", dragScroll && scrollable && "cursor-grab", drag.dragging && "cursor-grabbing select-none", contentClassName), "data-dragging": drag.dragging ? "" : undefined, ...drag.handlers, children: children }) }));
 };
 /**
  * A scrolling region that shows where there is more: each edge fades only
@@ -92,11 +114,21 @@ const Viewport = ({ children, className, dragScroll, mask, onViewport, orientati
  * @bestPractice Give a vertical frame a bounded height (`className="h-80"`); a horizontal one needs only a bounded width, which a flex child with `min-w-0` already has.
  * @bestPractice Match `fadeTheme` to the surface behind the frame (`card` inside a Card). Over an image or a blur, use `fadeMode="mask"` instead.
  * @bestPractice For a horizontal strip used with a mouse, add `dragScroll` and `controls`; both stand aside on touch screens, and each control hides at the end it points to.
+ * @bestPractice Every scrolling region in an app is a `ScrollFrame`, not a hand-rolled `overflow-y-auto` div: a pane, a list in a popover, a wide table (`orientation="both"`). A frame capped by `max-h-*` alone scrolls once its content passes the cap.
+ * @bestPractice Hand a virtualiser the scrolling element through `viewportRef`.
  * @category layout
  */
-export const ScrollFrame = ({ "aria-label": ariaLabel, children, className, controls = false, dragScroll = false, fadeMode = "color", fades = "both", fadeSize = "base", fadeTheme = "background", hideScrollbar = false, orientation = "vertical", viewportClassName, }) => {
+export const ScrollFrame = ({ "aria-label": ariaLabel, children, className, contentClassName, controls = false, dragScroll = false, fadeMode = "color", fades = "both", fadeSize = "base", fadeTheme = "background", hideScrollbar = false, orientation = "vertical", viewportClassName, viewportRef, ...props }) => {
     const [viewport, setViewport] = useState(null);
-    const edges = useScrollEdges(viewport, orientation);
-    const more = moreOf(edges);
-    return (_jsxs(ScrollAreaPrimitive.Root, { "aria-label": ariaLabel, className: cn("relative min-w-0 overflow-hidden", className), "data-component": "scroll-frame", "data-orientation": orientation, "data-slot": "scroll-frame", role: ariaLabel === undefined ? undefined : "region", children: [_jsx(Viewport, { className: viewportClassName, dragScroll: dragScroll, mask: frameMask(fadeMode, orientation, fadeSize, fades, more), onViewport: setViewport, orientation: orientation, scrollable: edges.scrollable, viewport: viewport, children: children }), hideScrollbar ? null : _jsx(ScrollBar, { orientation: orientation }), fadeMode === "color" ? (_jsx(Fades, { fadeSize: fadeSize, fadeTheme: fadeTheme, fades: fades, more: more, orientation: orientation })) : null, controls ? (_jsx(Controls, { more: more, orientation: orientation, viewport: viewport })) : null] }));
+    const vertical = useScrollEdges(viewport, "vertical");
+    const horizontal = useScrollEdges(viewport, "horizontal");
+    const more = {
+        horizontal: moreOf(horizontal),
+        vertical: moreOf(vertical),
+    };
+    const lead = leadAxis(orientation);
+    useImperativeHandle(viewportRef, () => viewport, [viewport]);
+    return (_jsxs(ScrollAreaPrimitive.Root, { ...props, "aria-label": ariaLabel, className: cn("relative min-w-0 overflow-hidden", className), "data-component": "scroll-frame", "data-orientation": orientation, "data-slot": "scroll-frame", role: ariaLabel === undefined ? undefined : "region", children: [_jsx(Viewport, { className: viewportClassName, contentClassName: contentClassName, dragScroll: dragScroll, mask: frameMask(fadeMode, orientation, fadeSize, fades, more), onViewport: setViewport, orientation: orientation, scrollable: (lead === "vertical" ? vertical : horizontal).scrollable, viewport: viewport, children: children }), hideScrollbar
+                ? null
+                : axesOf(orientation).map((axis) => (_jsx(ScrollBar, { orientation: axis }, axis))), orientation === "both" ? _jsx(ScrollAreaPrimitive.Corner, {}) : null, fadeMode === "color" ? (_jsx(Fades, { fadeSize: fadeSize, fadeTheme: fadeTheme, fades: fades, more: more, orientation: orientation })) : null, controls ? (_jsx(Controls, { more: more[lead], orientation: lead, viewport: viewport })) : null] }));
 };

package/dist/components/scroll-frame.d.ts

@@ -1 +1 @@
-export { ScrollFrame, type ScrollFrameFadeMode, type ScrollFrameFades, type ScrollFrameProps, } from "./scroll-frame/scroll-frame-root.js";
+export { ScrollFrame, type ScrollFrameFadeMode, type ScrollFrameFades, type ScrollFrameOrientation, type ScrollFrameProps, } from "./scroll-frame/scroll-frame-root.js";

package/dist/components/sidepanel/sidepanel-body.d.ts

@@ -7,9 +7,10 @@ type SidepanelBodyProps = ComponentProps<"div">;
 declare const SidepanelBody: ({ className, ...props }: SidepanelBodyProps) => import("react").JSX.Element;
 type SidepanelScrollProps = ComponentProps<"div">;
 /**
- * The scrolling region between a `SidepanelHeader` and `SidepanelFooter`:
- * takes the remaining height of `SidepanelBody`, scrolls on its own and carries
- * the panel's standard inset, so header and footer stay put while it moves.
+ * The scrolling region between a `SidepanelHeader` and `SidepanelFooter`, a
+ * `ScrollFrame`: takes the remaining height of `SidepanelBody`, scrolls on its
+ * own and carries the panel's standard inset, so header and footer stay put
+ * while it moves.
  *
  * @bestPractice Put exactly one `SidepanelScroll` inside `SidepanelBody`, between the header and footer, rather than a hand-rolled `flex-1 overflow-y-auto` div.
  */

package/dist/components/sidepanel/sidepanel-body.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Flex } from "@instruments/materia-ui/components/flex";
 import { cn } from "@instruments/materia-ui/utils/cn";
+import { ScrollFrame } from "../scroll-frame.js";
 /**
  * Body container for sidepanel content. Provides vertical flex layout
  * for header, scrollable content, and footer.
@@ -10,11 +11,12 @@ const SidepanelBody = ({ className, ...props }) => (_jsx(Flex, { className: cn("
     // Allow text selection in the body, even inside a swipe-dismissable surface
     "select-text", className), "data-component": "sidepanel-body", "data-slot": "sidepanel-body", direction: "column", ...props }));
 /**
- * The scrolling region between a `SidepanelHeader` and `SidepanelFooter`:
- * takes the remaining height of `SidepanelBody`, scrolls on its own and carries
- * the panel's standard inset, so header and footer stay put while it moves.
+ * The scrolling region between a `SidepanelHeader` and `SidepanelFooter`, a
+ * `ScrollFrame`: takes the remaining height of `SidepanelBody`, scrolls on its
+ * own and carries the panel's standard inset, so header and footer stay put
+ * while it moves.
  *
  * @bestPractice Put exactly one `SidepanelScroll` inside `SidepanelBody`, between the header and footer, rather than a hand-rolled `flex-1 overflow-y-auto` div.
  */
-const SidepanelScroll = ({ className, ...props }) => (_jsx(Flex, { className: cn("min-h-0 flex-1 overflow-y-auto px-6 py-4", className), "data-component": "sidepanel-scroll", "data-slot": "sidepanel-scroll", direction: "column", gap: "base", ...props }));
+const SidepanelScroll = ({ className, ...props }) => (_jsx(ScrollFrame, { className: "min-h-0 flex-1", fades: "end", children: _jsx(Flex, { className: cn("px-6 py-4", className), "data-component": "sidepanel-scroll", "data-slot": "sidepanel-scroll", direction: "column", gap: "base", ...props }) }));
 export { SidepanelBody, SidepanelScroll, };

package/dist/components/stat/stat-root.d.ts

@@ -0,0 +1,32 @@
+import type * as React from "react";
+/** The sizes a Stat comes in: `base` sits among other content, `lg` leads a page or a section. */
+export declare const STAT_SIZES: readonly ["base", "lg"];
+/** A size a Stat comes in; see {@link STAT_SIZES}. */
+export type StatSize = (typeof STAT_SIZES)[number];
+interface StatProps {
+    /** CSS class name */
+    className?: string;
+    /** What the value measures, set under it. */
+    label?: React.ReactNode;
+    /** Where the value comes from, set small and muted under the label. */
+    note?: React.ReactNode;
+    /**
+     * `base` for a figure among other content (a table cell, a side panel); `lg` for one that leads a page or section.
+     * @default "base"
+     */
+    size?: StatSize;
+    /** The figure itself: a number, a percentage, a ratio. */
+    value: React.ReactNode;
+}
+/**
+ * A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a
+ * page's figures match without setting a size or weight at the call site.
+ * Import from "@instruments/materia-ui/components/stat".
+ *
+ * @bestPractice Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+ * @bestPractice Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+ * @category data
+ */
+declare const Stat: ({ value, label, note, size, className }: StatProps) => React.JSX.Element;
+export type { StatProps };
+export { Stat };

package/dist/components/stat/stat-root.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Stack } from "../stack.js";
+import { Text } from "../text.js";
+/** The sizes a Stat comes in: `base` sits among other content, `lg` leads a page or a section. */
+export const STAT_SIZES = ["base", "lg"];
+/** The value's role at each size. `heading-lg` is past the sizes Text takes, so the value sets its own role. */
+const VALUE_CLASSES = {
+    base: "text-subheading-lg",
+    lg: "text-heading-lg",
+};
+/** The label's role at each size. */
+const LABEL_SIZES = {
+    base: "paragraph-sm",
+    lg: "paragraph",
+};
+const isSet = (node) => node !== undefined && node !== null && node !== "";
+/**
+ * A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a
+ * page's figures match without setting a size or weight at the call site.
+ * Import from "@instruments/materia-ui/components/stat".
+ *
+ * @bestPractice Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.
+ * @bestPractice Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.
+ * @category data
+ */
+const Stat = ({ value, label, note, size = "base", className }) => (_jsxs(Stack, { className: className, "data-component": "stat", "data-slot": "stat", gap: "xs", children: [_jsx("p", { className: cn("trim-both font-medium text-pretty", VALUE_CLASSES[size]), "data-slot": "stat-value", children: value }), isSet(label) && (_jsx(Text, { "data-slot": "stat-label", size: LABEL_SIZES[size], children: label })), isSet(note) && (_jsx(Text, { "data-slot": "stat-note", size: "caption", variant: "muted", children: note }))] }));
+export { Stat };

package/dist/components/stat.d.ts

@@ -0,0 +1,2 @@
+export type { StatProps, StatSize } from "./stat/stat-root.js";
+export { STAT_SIZES, Stat } from "./stat/stat-root.js";

package/dist/components/stat.js

@@ -0,0 +1 @@
+export { STAT_SIZES, Stat } from "./stat/stat-root.js";

package/dist/components/table/table-root.d.ts

@@ -1,6 +1,6 @@
 import type * as React from "react";
 /**
- * Semantic `<table>` primitive, wrapped in a horizontally scrollable container
+ * Semantic `<table>` primitive, wrapped in a horizontal `ScrollFrame`
  * so wide tables overflow rather than break layout. Compose with the exported
  * `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`,
  * `TableFooter`, and `TableCaption` parts.

package/dist/components/table/table-root.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@instruments/materia-ui/utils/cn";
+import { ScrollFrame } from "../scroll-frame.js";
 /**
- * Semantic `<table>` primitive, wrapped in a horizontally scrollable container
+ * Semantic `<table>` primitive, wrapped in a horizontal `ScrollFrame`
  * so wide tables overflow rather than break layout. Compose with the exported
  * `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`,
  * `TableFooter`, and `TableCaption` parts.
@@ -12,7 +13,7 @@ import { cn } from "@instruments/materia-ui/utils/cn";
  * @bestPractice Compose real `TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell` parts (semantic `thead`/`tbody`/`th`/`td`); don't fake rows with styled divs or you lose the table semantics.
  * @category data
  */
-const Table = ({ className, ...props }) => (_jsx("div", { className: "relative w-full overflow-auto", "data-component": "table-wrapper", "data-slot": "table-wrapper", children: _jsx("table", { className: cn("text-foreground text-paragraph-sm w-full caption-bottom", className), "data-component": "table", "data-slot": "table", ...props }) }));
+const Table = ({ className, ...props }) => (_jsx(ScrollFrame, { className: "w-full", contentClassName: "min-w-0!", orientation: "horizontal", children: _jsx("table", { className: cn("text-foreground text-paragraph-sm w-full caption-bottom", className), "data-component": "table", "data-slot": "table", ...props }) }));
 /** table header section */
 const TableHeader = ({ className, ...props }) => (_jsx("thead", { className: cn("[&_tr]:border-b", className), "data-component": "table-header", "data-slot": "table-header", ...props }));
 /**

package/dist/compositions/attribute-card.d.ts

@@ -16,7 +16,7 @@ interface AttributeCardProps {
  * AttributeCard UI component.
  * Import from "@instruments/materia-ui/compositions/attribute-card".
  *
- * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
  * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
  * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
  * @category catalogue

package/dist/compositions/attribute-card.js

@@ -7,7 +7,7 @@ import { Icon } from "../components/icon.js";
  * AttributeCard UI component.
  * Import from "@instruments/materia-ui/compositions/attribute-card".
  *
- * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.
  * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
  * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
  * @category catalogue

package/dist/compositions/data-grid-column-filter/data-grid-column-filter-root.js

@@ -6,6 +6,7 @@ import { Button } from "@instruments/materia-ui/components/button";
 import { Center } from "@instruments/materia-ui/components/center";
 import { Flex } from "@instruments/materia-ui/components/flex";
 import { Icon } from "@instruments/materia-ui/components/icon";
+import { ScrollFrame } from "@instruments/materia-ui/components/scroll-frame";
 import { Separator } from "@instruments/materia-ui/components/separator";
 import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
 import { cn } from "@instruments/materia-ui/utils/cn";
@@ -57,6 +58,6 @@ const DataGridColumnFilter = ({ column, title, options, }) => {
             // It renders the kit's Button, a native <button>.
             , { 
                 // It renders the kit's Button, a native <button>.
-                nativeButton: true, "aria-label": title, render: _jsx(Button, { tone: "neutral", emphasis: "outline", "data-component": "data-grid-column-filter", pressed: false, size: "sm" }), children: [_jsx(Icon, { icon: CirclePlus, size: "xs" }), title, _jsx(FilterTriggerBadges, { options: options, selectedValues: selectedValues })] }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsx(ComboboxPrimitive.Popup, { "aria-label": title, className: `${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-50 origin-(--transform-origin) rounded-3xl`, "data-slot": "data-grid-column-filter-content", children: _jsxs(Flex, { className: "bg-popover text-popover-foreground size-full overflow-hidden rounded-lg border shadow-xs", direction: "column", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden", placeholder: title })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", children: "No results found." }), _jsx(ComboboxPrimitive.List, { className: "max-h-75 scroll-py-1 overflow-x-hidden overflow-y-auto overscroll-contain p-1 empty:hidden", children: (option) => (_jsx(FilterOptionItem, { count: facets?.get(option.value) ?? 0, isSelected: selectedValues.has(option.value), option: option }, option.value)) }), selectedValues.size > 0 && (_jsx("div", { className: "border-t p-1", children: _jsx("button", { className: cn(focusRing(), "hover:bg-accent hover:text-accent-foreground text-paragraph-sm flex w-full cursor-default items-center justify-center rounded-sm px-2.5 py-1.5 select-none"), onClick: () => column?.setFilterValue(undefined), type: "button", children: "Clear filters" }) }))] }) }) }) })] }));
+                nativeButton: true, "aria-label": title, render: _jsx(Button, { tone: "neutral", emphasis: "outline", "data-component": "data-grid-column-filter", pressed: false, size: "sm" }), children: [_jsx(Icon, { icon: CirclePlus, size: "xs" }), title, _jsx(FilterTriggerBadges, { options: options, selectedValues: selectedValues })] }), _jsx(ComboboxPrimitive.Portal, { children: _jsx(ComboboxPrimitive.Positioner, { align: "start", className: "z-50", sideOffset: 4, children: _jsx(ComboboxPrimitive.Popup, { "aria-label": title, className: `${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-50 origin-(--transform-origin) rounded-3xl`, "data-slot": "data-grid-column-filter-content", children: _jsxs(Flex, { className: "bg-popover text-popover-foreground size-full overflow-hidden rounded-lg border shadow-xs", direction: "column", children: [_jsxs(Flex, { align: "center", className: "h-9 border-b px-3", gap: "xs", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(ComboboxPrimitive.Input, { className: "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full bg-transparent py-3 outline-hidden", placeholder: title })] }), _jsx(ComboboxPrimitive.Empty, { className: "text-paragraph-sm py-6 text-center empty:p-0", children: "No results found." }), _jsx(ScrollFrame, { className: "max-h-75", fadeTheme: "popover", fades: "end", children: _jsx(ComboboxPrimitive.List, { className: "scroll-py-1 p-1 empty:hidden", children: (option) => (_jsx(FilterOptionItem, { count: facets?.get(option.value) ?? 0, isSelected: selectedValues.has(option.value), option: option }, option.value)) }) }), selectedValues.size > 0 && (_jsx("div", { className: "border-t p-1", children: _jsx("button", { className: cn(focusRing(), "hover:bg-accent hover:text-accent-foreground text-paragraph-sm flex w-full cursor-default items-center justify-center rounded-sm px-2.5 py-1.5 select-none"), onClick: () => column?.setFilterValue(undefined), type: "button", children: "Clear filters" }) }))] }) }) }) })] }));
 };
 export { DataGridColumnFilter };

package/dist/compositions/data-grid-table/data-grid-table-root.js

@@ -3,6 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { DataGridFilterableHeader, useDataGrid, } from "@instruments/materia-ui/compositions/data-grid";
 import { Fragment } from "react";
 import { Center } from "../../components/center.js";
+import { ScrollFrame } from "../../components/scroll-frame.js";
 import { Spinner } from "../../components/spinner/spinner-root.js";
 import { DataGridTableBody, DataGridTableBodyRow, DataGridTableBodyRowCell, DataGridTableBodyRowExpandded, DataGridTableBodyRowSkeleton, DataGridTableBodyRowSkeletonCell, DataGridTableEmpty, DataGridTableRowSpacer, flexRender, } from "../data-grid-table/data-grid-table-body.js";
 import { DataGridTableBase, DataGridTableHead, DataGridTableHeadRow, DataGridTableHeadRowCell, DataGridTableHeadRowCellResize, } from "../data-grid-table/data-grid-table-header.js";
@@ -100,7 +101,7 @@ const DataGridTable = () => {
         rowHeight,
         rows,
     });
-    return (_jsx("div", { className: "overflow-auto", ref: tableContainerRef, style: { maxHeight: "calc(100vh - 8rem)" }, children: _jsxs(DataGridTableBase, { children: [_jsx(DataGridTableHeadContent, { context: context }), (props.tableLayout?.striped === true ||
+    return (_jsx(ScrollFrame, { contentClassName: "min-w-0!", fades: "none", orientation: "both", style: { maxHeight: "calc(100vh - 8rem)" }, viewportRef: tableContainerRef, children: _jsxs(DataGridTableBase, { children: [_jsx(DataGridTableHeadContent, { context: context }), (props.tableLayout?.striped === true ||
                     props.tableLayout?.rowBorder !== true) && _jsx(DataGridTableRowSpacer, {}), _jsx(DataGridTableBody, { children: _jsx(DataGridTableBodyContent, { context: context, measureRow: measureRow, paddingBottom: paddingBottom, paddingTop: paddingTop, pageSize: pagination.pageSize, renderedRowIndexes: renderedRowIndexes, rows: rows }) })] }) }));
 };
 export { DataGridTableBody, DataGridTableBodyRow, DataGridTableBodyRowCell, DataGridTableBodyRowExpandded, DataGridTableBodyRowSkeleton, DataGridTableBodyRowSkeletonCell, DataGridTableEmpty, DataGridTableLoader, DataGridTableRowSelect, DataGridTableRowSelectAll, DataGridTableRowSpacer, } from "../data-grid-table/data-grid-table-body.js";

package/dist/compositions/mega-menu/mega-menu-content.js

@@ -3,6 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Box } from "@instruments/materia-ui/components/box";
 import { Grid } from "@instruments/materia-ui/components/grid";
 import { PopoverBackdrop, PopoverContent, } from "@instruments/materia-ui/components/popover";
+import { ScrollFrame } from "@instruments/materia-ui/components/scroll-frame";
 import { cn } from "@instruments/materia-ui/utils/cn";
 // The window's top edge. The panel hangs from it, full width, in the shell's
 // overlay layer: above the sidebar's nav and the page, beneath the chrome
@@ -33,6 +34,6 @@ const BACKDROP_MOTION = [
 export const MegaMenuContent = ({ "aria-label": ariaLabel, children, className, ...props }) => (_jsxs(_Fragment, { children: [_jsx(PopoverBackdrop, { className: cn("z-30 bg-black/20 backdrop-blur-sm", BACKDROP_MOTION) }), _jsx(PopoverContent, { align: "start", anchor: WINDOW_TOP, 
             // It runs edge to edge across the window, so it is never nudged in from
             // the viewport's edge.
-            collisionPadding: 0, className: cn("bg-background max-h-svh w-(--anchor-width) overflow-y-auto overscroll-contain rounded-none p-0 shadow-xl", PANEL_MOTION, className), "data-component": "mega-menu-content", "data-slot": "mega-menu-content", 
+            collisionPadding: 0, className: cn("bg-background max-h-svh w-(--anchor-width) overflow-hidden rounded-none p-0 shadow-xl", PANEL_MOTION, className), "data-component": "mega-menu-content", "data-slot": "mega-menu-content", 
             // Beneath the chrome's layer, above the sidebar's.
-            positionerClassName: "z-30", side: "bottom", sideOffset: 0, ...props, children: _jsx(Box, { "aria-label": ariaLabel, as: "nav", className: "pt-header @container", children: _jsx(Grid, { align: "flex-start", className: "px-page-gutter pt-6 pb-10", columns: { base: 2, lg: 3 }, "data-slot": "mega-menu-grid", responsiveMode: "container", xGap: "2xl", yGap: "lg", children: children }) }) })] }));
+            positionerClassName: "z-30", side: "bottom", sideOffset: 0, ...props, children: _jsx(ScrollFrame, { className: "max-h-svh", fades: "none", children: _jsx(Box, { "aria-label": ariaLabel, as: "nav", className: "pt-header @container", children: _jsx(Grid, { align: "flex-start", className: "px-page-gutter pt-6 pb-10", columns: { base: 2, lg: 3 }, "data-slot": "mega-menu-grid", responsiveMode: "container", xGap: "2xl", yGap: "lg", children: children }) }) }) })] }));

package/dist/compositions/sidebar/sidebar-content.d.ts

@@ -1,3 +1,3 @@
 import type React from "react";
-/** Scrollable main region of the sidebar, between header and footer; overflow is clipped when collapsed to an icon rail. */
+/** The sidebar's main region between header and footer, in a `ScrollFrame`; it stops scrolling when collapsed to an icon rail. */
 export declare const SidebarContent: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

package/dist/compositions/sidebar/sidebar-content.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Flex } from "@instruments/materia-ui/components/flex";
+import { ScrollFrame } from "@instruments/materia-ui/components/scroll-frame";
 import { cn } from "@instruments/materia-ui/utils/cn";
-/** Scrollable main region of the sidebar, between header and footer; overflow is clipped when collapsed to an icon rail. */
-export const SidebarContent = ({ className, ...props }) => (_jsx(Flex, { className: cn("min-h-0 flex-1 overflow-auto group-data-[collapsible=icon]:overflow-hidden", className), "data-component": "sidebar-content", "data-sidebar": "content", "data-slot": "sidebar-content", direction: "column", ...props }));
+/** The sidebar's main region between header and footer, in a `ScrollFrame`; it stops scrolling when collapsed to an icon rail. */
+export const SidebarContent = ({ className, ...props }) => (_jsx(ScrollFrame, { className: "min-h-0 flex-1", fadeTheme: "gray", fades: "none", viewportClassName: "group-data-[collapsible=icon]:overflow-hidden!", children: _jsx(Flex, { className: cn("min-h-full", className), "data-component": "sidebar-content", "data-sidebar": "content", "data-slot": "sidebar-content", direction: "column", ...props }) }));

package/dist/compositions/sidebar/sidebar-menu-sub.d.ts

@@ -6,7 +6,7 @@ type SidebarMenuSubProps = React.ComponentProps<"ul">;
 /** The `<ul>` container for a nested submenu under a menu item; hidden when the sidebar collapses to an icon rail. */
 export declare const SidebarMenuSub: ({ className, ...props }: SidebarMenuSubProps) => React.JSX.Element;
 type SidebarMenuSubScrollAreaProps = React.ComponentProps<"div"> & {
-    /** Add a bottom gradient fade hinting at scrollable overflow. @default false */
+    /** Fade the bottom edge while more of the list is below. @default false */
     fade?: boolean;
     /** Cap the height: unconstrained, or clamped to the shared dropdown max. @default "none" */
     maxHeight?: "none" | "dropdown";

package/dist/compositions/sidebar/sidebar-menu-sub.js

@@ -5,6 +5,7 @@ import { Dot } from "@instruments/materia-ui/components/dot";
 import { Flex } from "@instruments/materia-ui/components/flex";
 import { Icon } from "@instruments/materia-ui/components/icon";
 import { MenuItem } from "@instruments/materia-ui/components/menu-item";
+import { ScrollFrame } from "@instruments/materia-ui/components/scroll-frame";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { isString } from "../../utils/type-guards.js";
 /** The `<ul>` container for a nested submenu under a menu item; hidden when the sidebar collapses to an icon rail. */
@@ -13,7 +14,7 @@ export const SidebarMenuSub = ({ className, ...props }) => (_jsx(Flex, { as: "ul
  * Scroll viewport for sidebar submenu content inside floating surfaces.
  * Keeps menu list scrolling, scrollbar styling, and bottom fade treatment centralised.
  */
-export const SidebarMenuSubScrollArea = ({ children, className, fade = false, maxHeight = "none", ...props }) => (_jsxs("div", { className: cn("relative min-h-0", className), "data-component": "sidebar-menu-sub-scroll-area", "data-slot": "sidebar-menu-sub-scroll-area", ...props, children: [_jsx("div", { className: cn("scrollbar-menu overflow-x-hidden overflow-y-auto", maxHeight === "dropdown" && "max-h-menu-sidebar-list"), children: children }), fade ? (_jsx("div", { "aria-hidden": true, className: "to-popover pointer-events-none absolute inset-x-0 bottom-0 h-24 bg-linear-to-b from-transparent" })) : null] }));
+export const SidebarMenuSubScrollArea = ({ children, className, fade = false, maxHeight = "none", ...props }) => (_jsx(ScrollFrame, { ...props, className: cn("min-h-0", maxHeight === "dropdown" && "max-h-menu-sidebar-list", className), "data-component": "sidebar-menu-sub-scroll-area", "data-slot": "sidebar-menu-sub-scroll-area", fadeSize: "3xl", fadeTheme: "popover", fades: fade ? "end" : "none", children: children }));
 /** The `<li>` wrapper for a single submenu row. */
 export const SidebarMenuSubItem = ({ className, ...props }) => (_jsx("li", { className: cn("group/menu-sub-item relative", className), "data-component": "sidebar-menu-sub-item", "data-sidebar": "menu-sub-item", "data-slot": "sidebar-menu-sub-item", ...props }));
 /**

package/dist/compositions/tag-selector/tag-selector-list.js

@@ -7,6 +7,7 @@ import { Plus } from "lucide-react";
 import { useMemo } from "react";
 import { Button } from "../../components/button.js";
 import { Flex } from "../../components/flex.js";
+import { ScrollFrame } from "../../components/scroll-frame.js";
 import { TagSelectorColorSwatches } from "../tag-selector/tag-selector-color-swatches.js";
 import { useTagSelectorContext } from "../tag-selector/tag-selector-context.js";
 import { TagSelectorItem } from "../tag-selector/tag-selector-item.js";
@@ -94,7 +95,7 @@ export const TagSelectorList = ({ emptyMessage = "No tags found.", className, })
     const exactMatch = tags.some((tag) => tag.label.toLowerCase() === searchQuery.toLowerCase());
     const showCreateOption = allowCreate && searchQuery !== "" && !exactMatch;
     const selectedIds = new Set(value.map((t) => t.id));
-    return (_jsx(Flex, { className: cn("max-h-75 overflow-y-auto p-1", className), "data-component": "tag-selector-list", "data-slot": "tag-selector-list", direction: "column", id: listboxId, 
-        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- this is a custom listbox widget whose children are interactive TagSelectorItem rows, a drag-to-reorder DndContext, and a "Create" affordance with a colour palette; <datalist>/<select> can only hold plain <option>s, so they cannot represent this content.
-        role: "listbox", children: filteredTags.length === 0 && !showCreateOption ? (_jsx("div", { className: "text-muted-foreground text-paragraph-sm py-6 text-center", children: emptyMessage })) : (_jsxs(_Fragment, { children: [showCreateOption && _jsx(TagSelectorCreateOption, {}), _jsx(TagSelectorItems, { filteredTags: filteredTags, selectedIds: selectedIds })] })) }));
+    return (_jsx(ScrollFrame, { className: cn("max-h-75", className), fadeTheme: "popover", fades: "end", children: _jsx(Flex, { className: "p-1", "data-component": "tag-selector-list", "data-slot": "tag-selector-list", direction: "column", id: listboxId, 
+            // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- this is a custom listbox widget whose children are interactive TagSelectorItem rows, a drag-to-reorder DndContext, and a "Create" affordance with a colour palette; <datalist>/<select> can only hold plain <option>s, so they cannot represent this content.
+            role: "listbox", children: filteredTags.length === 0 && !showCreateOption ? (_jsx("div", { className: "text-muted-foreground text-paragraph-sm py-6 text-center", children: emptyMessage })) : (_jsxs(_Fragment, { children: [showCreateOption && _jsx(TagSelectorCreateOption, {}), _jsx(TagSelectorItems, { filteredTags: filteredTags, selectedIds: selectedIds })] })) }) }));
 };

package/dist/data/docs-manifest.d.ts

@@ -74,5 +74,5 @@ export interface DocsManifest {
     storybook: DocsStorybookInventory;
 }
 /** The slug of every documented component and composition. */
-export type DocsUnitSlug = "accordion" | "alert" | "alert-dialog" | "anchor" | "animated-number" | "aspect-ratio" | "attribute-card" | "avatar" | "badge" | "border-beam" | "box" | "breadcrumb" | "button" | "button-group" | "calendar" | "card" | "card-grid" | "carousel" | "center" | "chart" | "checkbox" | "checkbox-card" | "checkbox-field" | "code" | "collapsible" | "color-palette" | "color-wheel" | "combobox" | "command" | "container" | "context-menu" | "cookie-banner" | "country-combobox" | "country-select" | "data-grid" | "data-grid-column-filter" | "data-grid-column-header" | "data-grid-column-visibility" | "data-grid-pagination" | "data-grid-table" | "delivery-banner" | "description-list" | "dialog" | "document-list" | "dot" | "dot-matrix-loader" | "drawer" | "dropdown-menu" | "easing-curve" | "editorial-card" | "empty" | "empty-state" | "error-boundary" | "error-state" | "expand-button" | "expandable-text" | "fade-overlay" | "field" | "file-upload" | "flex" | "folder-tile" | "gallery" | "grid" | "group" | "heading" | "hotspot-indicator" | "hover-card" | "icon" | "icon-box" | "icon-card" | "icon-morph" | "identified-surface" | "input" | "input-card" | "input-group" | "input-otp" | "item" | "kbd" | "label" | "loading-state" | "location-input" | "logo" | "logotype" | "marquee-text" | "media-frame" | "mega-menu" | "menu-item" | "menubar" | "mobile-navigation" | "month-year-picker" | "morph-dialog" | "motion-config" | "native-select" | "navigation-menu" | "page-header" | "page-toolbar" | "pagination" | "phone-input" | "pill" | "pixel-loader" | "popover" | "product-card" | "product-specifications-selector" | "progress" | "progress-dots" | "prompt-panel" | "quantity-control" | "quick-view" | "radio" | "radio-card" | "radio-group" | "requirement-item" | "resizable" | "scrim" | "scroll-area" | "scroll-fade" | "scroll-frame" | "search-input" | "section" | "section-header" | "segmented-control" | "select" | "separator" | "settings-card" | "sheet" | "shimmer" | "shine" | "sidebar" | "sidepanel" | "simple-grid" | "site-footer" | "skeleton" | "slider" | "social-icon" | "space" | "spinner" | "stack" | "stagger" | "stepper" | "streaming-text" | "sub-navigation" | "success-tick-ripple" | "swatch" | "swatch-fan" | "swatch-group" | "swatch-selector" | "switch" | "tab-navigation" | "table" | "tabs" | "tag" | "tag-selector" | "text" | "textarea" | "thinking-loader" | "thinking-orb" | "thinking-trace" | "time-slot-picker" | "toast" | "toggle" | "toggle-group" | "tooltip" | "variant-selector" | "verge" | "visually-hidden" | "voice";
+export type DocsUnitSlug = "accordion" | "alert" | "alert-dialog" | "anchor" | "animated-number" | "aspect-ratio" | "attribute-card" | "avatar" | "badge" | "border-beam" | "box" | "breadcrumb" | "button" | "button-group" | "calendar" | "card" | "card-grid" | "carousel" | "center" | "chart" | "checkbox" | "checkbox-card" | "checkbox-field" | "code" | "collapsible" | "color-palette" | "color-wheel" | "combobox" | "command" | "container" | "context-menu" | "cookie-banner" | "country-combobox" | "country-select" | "data-grid" | "data-grid-column-filter" | "data-grid-column-header" | "data-grid-column-visibility" | "data-grid-pagination" | "data-grid-table" | "delivery-banner" | "description-list" | "dialog" | "document-list" | "dot" | "dot-matrix-loader" | "drawer" | "dropdown-menu" | "easing-curve" | "editorial-card" | "empty" | "empty-state" | "error-boundary" | "error-state" | "expand-button" | "expandable-text" | "fade-overlay" | "field" | "file-upload" | "flex" | "folder-tile" | "gallery" | "grid" | "group" | "heading" | "hotspot-indicator" | "hover-card" | "icon" | "icon-box" | "icon-card" | "icon-morph" | "identified-surface" | "input" | "input-card" | "input-group" | "input-otp" | "item" | "kbd" | "label" | "loading-state" | "location-input" | "logo" | "logotype" | "marquee-text" | "media-frame" | "mega-menu" | "menu-item" | "menubar" | "mobile-navigation" | "month-year-picker" | "morph-dialog" | "motion-config" | "native-select" | "navigation-menu" | "page-header" | "page-toolbar" | "pagination" | "phone-input" | "pill" | "pixel-loader" | "popover" | "product-card" | "product-specifications-selector" | "progress" | "progress-dots" | "prompt-panel" | "quantity-control" | "quick-view" | "radio" | "radio-card" | "radio-group" | "requirement-item" | "resizable" | "scrim" | "scroll-area" | "scroll-fade" | "scroll-frame" | "search-input" | "section" | "section-header" | "segmented-control" | "select" | "separator" | "settings-card" | "sheet" | "shimmer" | "shine" | "sidebar" | "sidepanel" | "simple-grid" | "site-footer" | "skeleton" | "slider" | "social-icon" | "space" | "spinner" | "stack" | "stagger" | "stat" | "stepper" | "streaming-text" | "sub-navigation" | "success-tick-ripple" | "swatch" | "swatch-fan" | "swatch-group" | "swatch-selector" | "switch" | "tab-navigation" | "table" | "tabs" | "tag" | "tag-selector" | "text" | "textarea" | "thinking-loader" | "thinking-orb" | "thinking-trace" | "time-slot-picker" | "toast" | "toggle" | "toggle-group" | "tooltip" | "variant-selector" | "verge" | "visually-hidden" | "voice";
 export declare const docsManifest: DocsManifest;

package/dist/data/docs-manifest.js

@@ -2403,7 +2403,7 @@ export const docsManifest = {
                             type: "boolean",
                             required: false,
                             defaultValue: "false",
-                            description: "Render a multi-line block (`<pre><code>`) instead of inline `<code>`. The\nblock scrolls horizontally rather than wrapping.",
+                            description: "Render a multi-line block (`<pre><code>`) instead of inline `<code>`. The\nblock scrolls horizontally, in a `ScrollFrame`, rather than wrapping.",
                         },
                     ],
                 },
@@ -2418,7 +2418,7 @@ export const docsManifest = {
                 "`block` renders `<pre><code>` that scrolls horizontally; add `whitespace-pre-wrap` via `className` only when wrapping beats scrolling (long prose-like messages).",
             ],
             keywords: [],
-            uses: [],
+            uses: ["scroll-frame"],
             usedBy: [],
         },
         {
@@ -2634,7 +2634,7 @@ export const docsManifest = {
                 "Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.",
             ],
             keywords: ["autocomplete", "typeahead", "searchable select"],
-            uses: ["button", "flex", "icon"],
+            uses: ["button", "flex", "icon", "scroll-frame"],
             usedBy: ["country-combobox"],
         },
         {
@@ -2845,7 +2845,7 @@ export const docsManifest = {
                 "A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.",
             ],
             keywords: ["command palette", "spotlight", "cmd+k", "quick search"],
-            uses: ["dialog", "flex", "icon"],
+            uses: ["dialog", "flex", "icon", "scroll-frame"],
             usedBy: [],
             anatomy: {
                 children: [
@@ -6914,7 +6914,7 @@ export const docsManifest = {
                 'Pick `mode="city"` vs `"address"` to scope the geocoding; drive it controlled via the `Location` `value` + `onChange` (which also fires on clear).',
             ],
             keywords: [],
-            uses: ["button", "icon", "menu-item"],
+            uses: ["button", "icon", "menu-item", "scroll-frame"],
             usedBy: [],
         },
         {
@@ -9480,6 +9480,12 @@ export const docsManifest = {
                             type: "string | undefined",
                             required: false,
                         },
+                        {
+                            name: "contentClassName",
+                            type: "string | undefined",
+                            required: false,
+                            description: "Classes for the element holding the children, inside the scrolling one.\nA vertical frame's content is already as wide as the frame, so text wraps\nand `w-full` children fill it; a horizontal or two-way frame's content is\nas wide as its widest child.",
+                        },
                         {
                             name: "controls",
                             type: "boolean | undefined",
@@ -9531,10 +9537,10 @@ export const docsManifest = {
                         },
                         {
                             name: "orientation",
-                            type: "Orientation | undefined",
+                            type: "ScrollFrameOrientation | undefined",
                             required: false,
                             defaultValue: '"vertical"',
-                            description: "Scroll axis: `vertical` scrolls up and down, `horizontal` left and right, as for a row of chips.",
+                            description: "Scroll axis: `vertical` scrolls up and down, `horizontal` left and right, as for a row of chips, and `both` either way, as for a wide table. Controls and drag follow the vertical axis when both scroll.",
                         },
                         {
                             name: "viewportClassName",
@@ -9542,6 +9548,12 @@ export const docsManifest = {
                             required: false,
                             description: "Classes for the scrolling element.",
                         },
+                        {
+                            name: "viewportRef",
+                            type: "Ref<HTMLDivElement | null> | undefined",
+                            required: false,
+                            description: "The scrolling element, for a virtualiser or anything else that reads or sets its scroll position.",
+                        },
                     ],
                 },
                 {
@@ -9554,6 +9566,11 @@ export const docsManifest = {
                     kind: "type",
                     props: [],
                 },
+                {
+                    name: "ScrollFrameOrientation",
+                    kind: "type",
+                    props: [],
+                },
                 {
                     name: "ScrollFrameProps",
                     kind: "interface",
@@ -9565,10 +9582,25 @@ export const docsManifest = {
                 'Give a vertical frame a bounded height (`className="h-80"`); a horizontal one needs only a bounded width, which a flex child with `min-w-0` already has.',
                 'Match `fadeTheme` to the surface behind the frame (`card` inside a Card). Over an image or a blur, use `fadeMode="mask"` instead.',
                 "For a horizontal strip used with a mouse, add `dragScroll` and `controls`; both stand aside on touch screens, and each control hides at the end it points to.",
+                'Every scrolling region in an app is a `ScrollFrame`, not a hand-rolled `overflow-y-auto` div: a pane, a list in a popover, a wide table (`orientation="both"`). A frame capped by `max-h-*` alone scrolls once its content passes the cap.',
+                "Hand a virtualiser the scrolling element through `viewportRef`.",
             ],
             keywords: [],
             uses: ["button", "scroll-area", "scroll-fade"],
-            usedBy: ["page-toolbar"],
+            usedBy: [
+                "code",
+                "combobox",
+                "command",
+                "data-grid-column-filter",
+                "data-grid-table",
+                "location-input",
+                "mega-menu",
+                "page-toolbar",
+                "sidebar",
+                "sidepanel",
+                "table",
+                "tag-selector",
+            ],
         },
         {
             slug: "search-input",
@@ -10759,7 +10791,7 @@ export const docsManifest = {
                 "Compose nested panels with `SidepanelNestedRoot`, and always render a `SidepanelTitle` for the accessible name.",
             ],
             keywords: [],
-            uses: ["button", "flex", "stack"],
+            uses: ["button", "flex", "scroll-frame", "stack"],
             usedBy: [],
             anatomy: {
                 children: [
@@ -11371,6 +11403,7 @@ export const docsManifest = {
                 "sidepanel",
                 "site-footer",
                 "skeleton",
+                "stat",
             ],
         },
         {
@@ -11433,6 +11466,74 @@ export const docsManifest = {
             uses: [],
             usedBy: [],
         },
+        {
+            slug: "stat",
+            module: "components/stat",
+            title: "Stat",
+            category: "data",
+            description: 'A figure, what it measures and where it comes from, value first. The component owns the type of all three, so a\npage\'s figures match without setting a size or weight at the call site.\nImport from "@instruments/materia-ui/components/stat".',
+            exports: [
+                {
+                    name: "Stat",
+                    kind: "component",
+                    props: [
+                        {
+                            name: "className",
+                            type: "string",
+                            required: false,
+                            description: "CSS class name",
+                        },
+                        {
+                            name: "label",
+                            type: "React.ReactNode",
+                            required: false,
+                            description: "What the value measures, set under it.",
+                        },
+                        {
+                            name: "note",
+                            type: "React.ReactNode",
+                            required: false,
+                            description: "Where the value comes from, set small and muted under the label.",
+                        },
+                        {
+                            name: "size",
+                            type: '"base" | "lg"',
+                            required: false,
+                            defaultValue: '"base"',
+                            description: "`base` for a figure among other content (a table cell, a side panel); `lg` for one that leads a page or section.",
+                        },
+                        {
+                            name: "value",
+                            type: "React.ReactNode",
+                            required: true,
+                            description: "The figure itself: a number, a percentage, a ratio.",
+                        },
+                    ],
+                },
+                {
+                    name: "STAT_SIZES",
+                    kind: "const",
+                    props: [],
+                },
+                {
+                    name: "StatProps",
+                    kind: "interface",
+                    props: [],
+                },
+                {
+                    name: "StatSize",
+                    kind: "type",
+                    props: [],
+                },
+            ],
+            bestPractices: [
+                "Use `Stat` for a bare figure in running layout (a row of results, a cover, beside a chart); for a label-first tile in its own card reach for `AttributeCard`.",
+                'Keep `value` to the figure alone ("24", "1,284", "3–5") and put the sentence in `label`; `note` is for the source or date window, not a second label.',
+            ],
+            keywords: [],
+            uses: ["stack", "text"],
+            usedBy: [],
+        },
         {
             slug: "stepper",
             module: "components/stepper",
@@ -12334,7 +12435,7 @@ export const docsManifest = {
             module: "components/table",
             title: "Table",
             category: "data",
-            description: "Semantic `<table>` primitive, wrapped in a horizontally scrollable container\nso wide tables overflow rather than break layout. Compose with the exported\n`TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`,\n`TableFooter`, and `TableCaption` parts.",
+            description: "Semantic `<table>` primitive, wrapped in a horizontal `ScrollFrame`\nso wide tables overflow rather than break layout. Compose with the exported\n`TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`,\n`TableFooter`, and `TableCaption` parts.",
             exports: [
                 {
                     name: "Table",
@@ -12383,7 +12484,7 @@ export const docsManifest = {
                 "Compose real `TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell` parts (semantic `thead`/`tbody`/`th`/`td`); don't fake rows with styled divs or you lose the table semantics.",
             ],
             keywords: [],
-            uses: [],
+            uses: ["scroll-frame"],
             usedBy: [],
         },
         {
@@ -12807,6 +12908,7 @@ export const docsManifest = {
                 "section-header",
                 "site-footer",
                 "slider",
+                "stat",
                 "streaming-text",
                 "thinking-trace",
             ],
@@ -13844,7 +13946,7 @@ export const docsManifest = {
                 },
             ],
             bestPractices: [
-                "Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.",
+                "Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead, and for a bare figure without a card, `Stat`.",
                 "Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.",
                 "This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.",
             ],
@@ -14811,7 +14913,15 @@ export const docsManifest = {
                 "The typed search survives each pick, so several matches can be ticked from one query; it resets when the popup closes.",
             ],
             keywords: [],
-            uses: ["badge", "button", "center", "flex", "icon", "separator"],
+            uses: [
+                "badge",
+                "button",
+                "center",
+                "flex",
+                "icon",
+                "scroll-frame",
+                "separator",
+            ],
             usedBy: [],
         },
         {
@@ -15275,7 +15385,7 @@ export const docsManifest = {
                 "Use `DataGridTable` for a data-driven grid; for a small static table with hand-authored `<TableRow>`s reach for `Table` instead - no virtualisation or TanStack instance needed.",
             ],
             keywords: [],
-            uses: ["center", "data-grid", "flex", "spinner"],
+            uses: ["center", "data-grid", "flex", "scroll-frame", "spinner"],
             usedBy: [],
         },
         {
@@ -16728,7 +16838,15 @@ export const docsManifest = {
                 "Keep it to navigation. Every entry is a `MegaMenuLink`, which closes the menu as it navigates; actions belong in a `DropdownMenu`.",
             ],
             keywords: [],
-            uses: ["anchor", "box", "grid", "heading", "popover", "stack"],
+            uses: [
+                "anchor",
+                "box",
+                "grid",
+                "heading",
+                "popover",
+                "scroll-frame",
+                "stack",
+            ],
             usedBy: [],
         },
         {
@@ -21963,7 +22081,7 @@ export const docsManifest = {
                             type: "boolean",
                             required: false,
                             defaultValue: "false",
-                            description: "Add a bottom gradient fade hinting at scrollable overflow.",
+                            description: "Fade the bottom edge while more of the list is below.",
                         },
                         {
                             name: "maxHeight",
@@ -22277,6 +22395,7 @@ export const docsManifest = {
                 "input",
                 "kbd",
                 "menu-item",
+                "scroll-frame",
                 "separator",
                 "sheet",
                 "skeleton",
@@ -23275,6 +23394,7 @@ export const docsManifest = {
                 "popover",
                 "scroll-area",
                 "scroll-fade",
+                "scroll-frame",
                 "tag",
             ],
             usedBy: [],
@@ -23784,7 +23904,7 @@ export const docsManifest = {
     storybook: {
         addons: ["@storybook/addon-docs", "@storybook/react-vite"],
         anatomyFiles: 31,
-        storyFiles: 172,
+        storyFiles: 173,
         storiesWithPlay: 63,
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materia-ui",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Materia design system: React components, tokens and Tailwind v4 styles.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -462,6 +462,10 @@
       "types": "./dist/components/stagger.d.ts",
       "default": "./dist/components/stagger.js"
     },
+    "./components/stat": {
+      "types": "./dist/components/stat.d.ts",
+      "default": "./dist/components/stat.js"
+    },
     "./components/stepper": {
       "types": "./dist/components/stepper.d.ts",
       "default": "./dist/components/stepper.js"