@instruments/materia-ui 0.1.0

package/dist/components/scrim/scrim-variants.js

@@ -0,0 +1,33 @@
+import { cva } from "class-variance-authority";
+/**
+ * A directional gradient overlay that darkens one edge of its container,
+ * fading to transparent towards the opposite edge - keeps light-on-image text
+ * (captions, labels, stats) legible over a photo. Always fills its container
+ * (`inset-0`); for a caption band rather than the whole box, wrap it in a
+ * smaller positioned container sized by its own content/padding.
+ *
+ * - `direction` - which edge holds the dark stop; the gradient fades towards
+ *   the opposite edge.
+ * - `intensity` - token stop set for the dark stop's opacity (and, for
+ *   `hero`, a held mid-stop for content that needs a longer readable band).
+ */
+export const scrimVariants = cva("pointer-events-none absolute inset-0", {
+    defaultVariants: {
+        direction: "bottom",
+        intensity: "medium",
+    },
+    variants: {
+        direction: {
+            bottom: "bg-linear-to-t",
+            left: "bg-linear-to-r",
+            right: "bg-linear-to-l",
+            top: "bg-linear-to-b",
+        },
+        intensity: {
+            hero: "from-black/70 via-black/30 to-transparent",
+            medium: "from-black/70 to-transparent",
+            soft: "from-black/50 to-transparent",
+            strong: "from-black/80 to-transparent",
+        },
+    },
+});

package/dist/components/scrim.d.ts

@@ -0,0 +1,3 @@
+export { Scrim, type ScrimProps } from "./scrim/scrim-root.js";
+export type { ScrimDirection, ScrimIntensity } from "./scrim/scrim-variants.js";
+export { scrimVariants } from "./scrim/scrim-variants.js";

package/dist/components/scrim.js

@@ -0,0 +1,2 @@
+export { Scrim } from "./scrim/scrim-root.js";
+export { scrimVariants } from "./scrim/scrim-variants.js";

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

@@ -0,0 +1,46 @@
+import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area";
+import type { LayoutElement } from "../../tokens/element.js";
+import type { Orientation } from "../../tokens/orientation.js";
+type ScrollAreaProps = Omit<ScrollAreaPrimitive.Root.Props, "className"> & {
+    className?: string;
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Ref
+     * and event-handler types remain the default element's.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <ScrollArea as="section" />
+     */
+    as?: LayoutElement;
+    /** Allow content to visually overflow the root container. */
+    allowOverflow?: boolean;
+    /** Orientation of the scrollbar. Defaults to "vertical". Set to "horizontal" for horizontal scrolling. */
+    orientation?: Orientation;
+    /** Hide the scrollbar completely while maintaining scroll functionality */
+    hideScrollbar?: boolean;
+    /** Additional classes for the viewport (scrolling container) */
+    viewportClassName?: string;
+};
+/**
+ * Custom-styled scrollbar with draggable thumb. `ScrollArea` renders one for you;
+ * use this directly only when composing a Base UI scroll area by hand.
+ * Import from "@instruments/materia-ui/components/scroll-area".
+ */
+declare const ScrollBar: ({ className, orientation, ...props }: Omit<ScrollAreaPrimitive.Scrollbar.Props, "className"> & {
+    className?: string;
+}) => import("react").JSX.Element;
+/**
+ * Scrollable container with custom design-system scrollbars. `children` are
+ * placed inside a Base UI viewport, so give the root (or `viewportClassName`) an
+ * explicit height/width for scrolling to engage.
+ * Import from "@instruments/materia-ui/components/scroll-area".
+ *
+ * @bestPractice Give the root (or `viewportClassName`) an explicit height/width - without a bounded size the content never overflows and the custom scrollbar never engages.
+ * @bestPractice `ScrollArea` renders its own `ScrollBar`; reach for `ScrollBar` directly only when hand-composing a Base UI scroll area.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+declare const ScrollArea: ({ as, className, children, allowOverflow, orientation, hideScrollbar, render, viewportClassName, ...props }: ScrollAreaProps) => import("react").JSX.Element;
+export { ScrollArea, ScrollBar };

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

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Custom-styled scrollbar with draggable thumb. `ScrollArea` renders one for you;
+ * use this directly only when composing a Base UI scroll area by hand.
+ * Import from "@instruments/materia-ui/components/scroll-area".
+ */
+const ScrollBar = ({ className, orientation = "vertical", ...props }) => (_jsx(ScrollAreaPrimitive.Scrollbar, { className: cn("pointer-events-none flex touch-none p-px opacity-0 transition-opacity select-none data-hovering:pointer-events-auto data-hovering:opacity-100 data-scrolling:pointer-events-auto data-scrolling:opacity-100", orientation === "vertical" &&
+        "h-full w-2.5 border-l border-l-transparent", orientation === "horizontal" &&
+        "h-2.5 flex-col border-t border-t-transparent", className), "data-component": "scroll-area-scrollbar", "data-slot": "scroll-area-scrollbar", orientation: orientation, ...props, children: _jsx(ScrollAreaPrimitive.Thumb, { className: cn("bg-border rounded-full", orientation === "vertical" ? "w-full" : "h-full"), "data-component": "scroll-area-thumb", "data-slot": "scroll-area-thumb" }) }));
+/**
+ * Scrollable container with custom design-system scrollbars. `children` are
+ * placed inside a Base UI viewport, so give the root (or `viewportClassName`) an
+ * explicit height/width for scrolling to engage.
+ * Import from "@instruments/materia-ui/components/scroll-area".
+ *
+ * @bestPractice Give the root (or `viewportClassName`) an explicit height/width - without a bounded size the content never overflows and the custom scrollbar never engages.
+ * @bestPractice `ScrollArea` renders its own `ScrollBar`; reach for `ScrollBar` directly only when hand-composing a Base UI scroll area.
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+const ScrollArea = ({ as, className, children, allowOverflow = false, orientation = "vertical", hideScrollbar = false, render, viewportClassName, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("ScrollArea: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const Tag = as;
+    return (_jsxs(ScrollAreaPrimitive.Root, { className: cn("relative", orientation === "horizontal" &&
+            (allowOverflow
+                ? "overflow-x-hidden overflow-y-visible"
+                : "overflow-hidden"), className), "data-component": "scroll-area", "data-slot": "scroll-area", render: render ?? (Tag === undefined ? undefined : _jsx(Tag, {})), ...props, children: [_jsx(ScrollAreaPrimitive.Viewport, { className: cn(focusRing(), "rounded-inherit size-full", "transition-color-shadow focus-visible:ring-inset", viewportClassName), "data-component": "scroll-area-viewport", "data-slot": "scroll-area-viewport", children: _jsx(ScrollAreaPrimitive.Content, { children: children }) }), !hideScrollbar && _jsx(ScrollBar, { orientation: orientation }), _jsx(ScrollAreaPrimitive.Corner, {})] }));
+};
+export { ScrollArea, ScrollBar };

package/dist/components/scroll-area/scroll-area.test-d.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type-level surface guards for ScrollArea's closed `as` vocabulary and `render` prop.
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { ScrollArea } from "./scroll-area-root.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as ScrollArea props. */
+type Accepts<V> = V extends ComponentProps<typeof ScrollArea> ? true : false;
+export type SectionAccepted = Expect<Accepts<{
+    as: "section";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export type ArgsNonNever = Expect<Not<[ComponentProps<typeof ScrollArea>] extends [never] ? true : false>>;
+export {};

package/dist/components/scroll-area/scroll-area.test-d.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export { ScrollArea, ScrollBar } from "./scroll-area/scroll-area-root.js";

package/dist/components/scroll-area.js

@@ -0,0 +1 @@
+export { ScrollArea, ScrollBar } from "./scroll-area/scroll-area-root.js";

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

@@ -0,0 +1,37 @@
+import type { ComponentSize } from "@instruments/materia-ui/tokens/size";
+import type { VariantProps } from "class-variance-authority";
+import type * as React from "react";
+declare const scrollFadeVariants: (props?: ({
+    size?: "2xl" | "2xs" | "3xl" | "base" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+    orientation?: "horizontal" | "vertical" | null | undefined;
+    position?: "end" | "start" | null | undefined;
+    theme?: "background" | "card" | "gray" | "muted" | "popover" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface ScrollFadeProps extends Omit<React.ComponentProps<"div">, "children">, Omit<VariantProps<typeof scrollFadeVariants>, "size"> {
+    /**
+     * Thickness of the fade gradient - height when vertical, width when horizontal.
+     * @default "base"
+     */
+    size?: ComponentSize;
+}
+/**
+ * A gradient fade overlay for scroll containers.
+ * Place inside a relatively positioned container to indicate more content.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative">
+ *   <ScrollArea className="h-64">
+ *     {content}
+ *   </ScrollArea>
+ *   <ScrollFade position="end" theme="card" />
+ * </div>
+ * ```
+ *
+ * @bestPractice Drop `ScrollFade` inside a `position: relative` scroll container instead of hand-writing a gradient - it renders the masked scrim for you (it's `aria-hidden`, purely decorative).
+ * @bestPractice Match `theme` to the container's actual background (`card`/`popover`/…) - the scrim fades to that colour, so a mismatch leaves a visible seam.
+ * @bestPractice Set `position` (`start`/`end`) and `orientation` to the edge with hidden content - `end`+`vertical` is the common "more below" bottom fade.
+ * @category motion
+ */
+export declare const ScrollFade: ({ className, size, orientation, position, theme, style, ...props }: ScrollFadeProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,135 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+const scrollFadeVariants = cva("after:bg-hatch pointer-events-none absolute isolate z-10 overflow-hidden after:absolute after:inset-0 after:opacity-40", {
+    compoundVariants: [
+        // Vertical orientation sizes (height)
+        { class: "h-2", orientation: "vertical", size: "2xs" },
+        { class: "h-3", orientation: "vertical", size: "xs" },
+        { class: "h-4", orientation: "vertical", size: "sm" },
+        { class: "h-6", orientation: "vertical", size: "base" },
+        { class: "h-8", orientation: "vertical", size: "lg" },
+        { class: "h-10", orientation: "vertical", size: "xl" },
+        { class: "h-12", orientation: "vertical", size: "2xl" },
+        { class: "h-16", orientation: "vertical", size: "3xl" },
+        // Horizontal orientation sizes (width)
+        { class: "w-2", orientation: "horizontal", size: "2xs" },
+        { class: "w-3", orientation: "horizontal", size: "xs" },
+        { class: "w-4", orientation: "horizontal", size: "sm" },
+        { class: "w-6", orientation: "horizontal", size: "base" },
+        { class: "w-8", orientation: "horizontal", size: "lg" },
+        { class: "w-10", orientation: "horizontal", size: "xl" },
+        { class: "w-12", orientation: "horizontal", size: "2xl" },
+        { class: "w-16", orientation: "horizontal", size: "3xl" },
+        // Vertical + start = top fade, gradient goes down (transparent at bottom, opaque at top)
+        {
+            class: "top-0",
+            orientation: "vertical",
+            position: "start",
+        },
+        // Vertical + end = bottom fade, gradient goes down (transparent at top, opaque at bottom)
+        {
+            class: "bottom-0",
+            orientation: "vertical",
+            position: "end",
+        },
+        // Horizontal + start = left fade, gradient goes left (transparent at right, opaque at left)
+        {
+            class: "left-0",
+            orientation: "horizontal",
+            position: "start",
+        },
+        // Horizontal + end = right fade, gradient goes right (transparent at left, opaque at right)
+        {
+            class: "right-0",
+            orientation: "horizontal",
+            position: "end",
+        },
+    ],
+    defaultVariants: {
+        orientation: "vertical",
+        position: "end",
+        size: "base",
+        theme: "background",
+    },
+    variants: {
+        /**
+         * Size of the fade gradient
+         */
+        size: {
+            "2xs": "",
+            xs: "",
+            sm: "",
+            base: "",
+            lg: "",
+            xl: "",
+            "2xl": "",
+            "3xl": "",
+        },
+        /**
+         * Orientation of the gradient
+         */
+        orientation: {
+            vertical: "inset-x-0",
+            horizontal: "inset-y-0",
+        },
+        /**
+         * Position/direction of the fade
+         * - start: top for vertical, left for horizontal
+         * - end: bottom for vertical, right for horizontal
+         */
+        position: {
+            start: "",
+            end: "",
+        },
+        /**
+         * Background theme the gradient fades to
+         */
+        theme: {
+            card: "bg-card",
+            background: "bg-background",
+            popover: "bg-popover",
+            muted: "bg-muted",
+            gray: "bg-gray-100",
+        },
+    },
+});
+/**
+ * A gradient fade overlay for scroll containers.
+ * Place inside a relatively positioned container to indicate more content.
+ *
+ * @example
+ * ```tsx
+ * <div className="relative">
+ *   <ScrollArea className="h-64">
+ *     {content}
+ *   </ScrollArea>
+ *   <ScrollFade position="end" theme="card" />
+ * </div>
+ * ```
+ *
+ * @bestPractice Drop `ScrollFade` inside a `position: relative` scroll container instead of hand-writing a gradient - it renders the masked scrim for you (it's `aria-hidden`, purely decorative).
+ * @bestPractice Match `theme` to the container's actual background (`card`/`popover`/…) - the scrim fades to that colour, so a mismatch leaves a visible seam.
+ * @bestPractice Set `position` (`start`/`end`) and `orientation` to the edge with hidden content - `end`+`vertical` is the common "more below" bottom fade.
+ * @category motion
+ */
+export const ScrollFade = ({ className, size = "base", orientation = "vertical", position = "end", theme = "background", style, ...props }) => {
+    const easedScrimStops = "rgb(0 0 0 / 0) 0%, rgb(0 0 0 / 0.008) 8%, rgb(0 0 0 / 0.025) 18%, rgb(0 0 0 / 0.06) 32%, rgb(0 0 0 / 0.14) 50%, rgb(0 0 0 / 0.28) 68%, rgb(0 0 0 / 0.52) 82%, rgb(0 0 0 / 0.8) 93%, rgb(0 0 0 / 1) 100%";
+    let maskDirection = "to bottom";
+    if (orientation === "horizontal") {
+        maskDirection = position === "end" ? "to right" : "to left";
+    }
+    else if (position === "start") {
+        maskDirection = "to top";
+    }
+    const maskImage = `linear-gradient(${maskDirection}, ${easedScrimStops})`;
+    const scrimStyle = {
+        WebkitMaskImage: maskImage,
+        WebkitMaskRepeat: "no-repeat",
+        maskImage,
+        maskRepeat: "no-repeat",
+        ...style,
+    };
+    return (_jsx("div", { "aria-hidden": "true", className: cn(scrollFadeVariants({ orientation, position, size, theme }), className), "data-component": "scroll-fade", "data-slot": "scroll-fade", style: scrimStyle, ...props }));
+};

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

@@ -0,0 +1 @@
+export { ScrollFade, type ScrollFadeProps, } from "./scroll-fade/scroll-fade-root.js";

package/dist/components/scroll-fade.js

@@ -0,0 +1 @@
+export { ScrollFade, } from "./scroll-fade/scroll-fade-root.js";

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

@@ -0,0 +1,79 @@
+import type { ComponentSize } from "@instruments/materia-ui/tokens/size";
+import type { ReactNode } from "react";
+import type { Orientation } from "../../tokens/orientation.js";
+import type { ScrollFadeProps } from "../scroll-fade/scroll-fade-root.js";
+/** Which edges may fade. */
+export type ScrollFrameFades = "both" | "end" | "none" | "start";
+/**
+ * How the fades are drawn. `"color"` lays a gradient of `fadeTheme` over the
+ * content, right on a solid surface. `"mask"` fades the content itself to
+ * transparent, right over an image, a blur or any backdrop a colour can't
+ * match.
+ */
+export type ScrollFrameFadeMode = "color" | "mask";
+export interface ScrollFrameProps {
+    /** Names the frame; it becomes a labelled region. */
+    "aria-label"?: string | undefined;
+    children: ReactNode;
+    className?: 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,
+     * where a swipe does the job.
+     * @default false
+     */
+    controls?: boolean | undefined;
+    /**
+     * Drag the content with a mouse. A press on a chip or link inside stays a
+     * click until the pointer travels; past that it drags and the click is
+     * swallowed. Touch keeps its native swipe.
+     * @default false
+     */
+    dragScroll?: boolean | undefined;
+    /** @default "color" */
+    fadeMode?: ScrollFrameFadeMode | undefined;
+    /**
+     * Which edges fade. An edge fades only while there is more beyond it.
+     * @default "both"
+     */
+    fades?: ScrollFrameFades | undefined;
+    /**
+     * Length of the fade.
+     * @default "base"
+     */
+    fadeSize?: ComponentSize | undefined;
+    /**
+     * The surface the colour fades blend into. Match the frame's background.
+     * @default "background"
+     */
+    fadeTheme?: ScrollFadeProps["theme"] | undefined;
+    /**
+     * Keep scrolling but draw no scrollbar.
+     * @default false
+     */
+    hideScrollbar?: boolean | undefined;
+    /** @default "vertical" */
+    orientation?: Orientation | undefined;
+    /** Classes for the scrolling element. */
+    viewportClassName?: string | undefined;
+}
+/**
+ * A scrolling region that shows where there is more: each edge fades only
+ * while content runs on past it, and optional buttons step through it.
+ * Adapted from @patternmode/scrollframe.
+ * Import from "@instruments/materia-ui/components/scroll-frame".
+ *
+ * @example
+ * ```tsx
+ * <ScrollFrame aria-label="Finishes" hideScrollbar orientation="horizontal">
+ *   <Flex gap="xs">{chips}</Flex>
+ * </ScrollFrame>
+ * ```
+ *
+ * @bestPractice Reach for `ScrollFrame` whenever a strip or a panel can overflow - a row of filters, a list in a fixed-height card. Plain `ScrollArea` gives no sign that anything is hidden.
+ * @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.
+ * @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;

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

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { useDragScroll } from "../../hooks/use-drag-scroll.js";
+import { useScrollEdges } from "../../hooks/use-scroll-edges.js";
+import { Button } from "../button.js";
+import { ScrollBar } from "../scroll-area.js";
+import { ScrollFade } from "../scroll-fade/scroll-fade-root.js";
+const EDGES = ["start", "end"];
+/** The fade lengths, matching `ScrollFade`'s own sizes. */
+const FADE_LENGTH = {
+    "2xl": "3rem",
+    "2xs": "0.5rem",
+    "3xl": "4rem",
+    base: "1.5rem",
+    lg: "2rem",
+    sm: "1rem",
+    xl: "2.5rem",
+    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";
+    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 };
+};
+const prefersReducedMotion = () => globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+const CONTROL_ICONS = {
+    horizontal: { end: ChevronRight, start: ChevronLeft },
+    vertical: { end: ChevronDown, start: ChevronUp },
+};
+const CONTROL_PLACEMENT = {
+    horizontal: {
+        end: "top-1/2 right-1 -translate-y-1/2",
+        start: "top-1/2 left-1 -translate-y-1/2",
+    },
+    vertical: {
+        end: "bottom-1 left-1/2 -translate-x-1/2",
+        start: "top-1 left-1/2 -translate-x-1/2",
+    },
+};
+const stepBy = (viewport, orientation, edge) => {
+    if (viewport === null) {
+        return;
+    }
+    const size = orientation === "horizontal" ? viewport.clientWidth : viewport.clientHeight;
+    const distance = Math.max(1, size * 0.85) * (edge === "end" ? 1 : -1);
+    viewport.scrollBy({
+        behavior: prefersReducedMotion() ? "auto" : "smooth",
+        [orientation === "horizontal" ? "left" : "top"]: distance,
+    });
+};
+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 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)));
+/** 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 }) }));
+};
+/**
+ * A scrolling region that shows where there is more: each edge fades only
+ * while content runs on past it, and optional buttons step through it.
+ * Adapted from @patternmode/scrollframe.
+ * Import from "@instruments/materia-ui/components/scroll-frame".
+ *
+ * @example
+ * ```tsx
+ * <ScrollFrame aria-label="Finishes" hideScrollbar orientation="horizontal">
+ *   <Flex gap="xs">{chips}</Flex>
+ * </ScrollFrame>
+ * ```
+ *
+ * @bestPractice Reach for `ScrollFrame` whenever a strip or a panel can overflow - a row of filters, a list in a fixed-height card. Plain `ScrollArea` gives no sign that anything is hidden.
+ * @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.
+ * @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, }) => {
+    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] }));
+};

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

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

package/dist/components/scroll-frame.js

@@ -0,0 +1 @@
+export { ScrollFrame, } from "./scroll-frame/scroll-frame-root.js";

package/dist/components/search-input/search-input-root.d.ts

@@ -0,0 +1,73 @@
+import type * as React from "react";
+import type { Radius } from "../../tokens/radius.js";
+import type { ResponsiveSize } from "../../tokens/size.js";
+export type SearchInputProps = Omit<React.ComponentProps<"input">, "size" | "type" | "value" | "defaultValue" | "onChange"> & {
+    /**
+     * Size of the search input, its icon, and its clear button - a single token
+     * or a per-breakpoint object like `{ base: "sm", md: "lg" }`. @default "xl"
+     */
+    size?: ResponsiveSize;
+    /** Border radius style. */
+    radius?: Radius;
+    /** Show error styling. */
+    hasError?: boolean;
+    /** Controlled value. Omit to let SearchInput manage its own state. */
+    value?: string;
+    /** Initial value when uncontrolled. */
+    defaultValue?: string;
+    /** Called with the next value on every keystroke and on clear. */
+    onChange?: (value: string) => void;
+    /** Called when the built-in clear button is pressed. */
+    onClear?: () => void;
+    /**
+     * Keyboard shortcut hint (e.g. "⌘K") rendered as a `Kbd` while the field
+     * is empty. Replaced by the clear button once the field has a value.
+     */
+    shortcutHint?: string;
+    /**
+     * Cycling placeholder suggestions, animated over the field while it is empty
+     * (e.g. `["white dove", "alabaster", …]`). SearchInput owns the overlay,
+     * alignment, and native-placeholder blanking - just pass the strings. When
+     * set, the static `placeholder` is suppressed.
+     */
+    suggestions?: readonly string[];
+    /** Static prefix shown before each cycling suggestion. @default "Try:" */
+    suggestionPrefix?: string;
+    /** Rotation interval for the suggestions in ms. @default 5000 */
+    suggestionIntervalMs?: number;
+    /** Test ID for testing. */
+    testId?: string;
+};
+/**
+ * Search input over InputGroup: a search icon, a built-in clear button that
+ * appears once the field has a value, and an optional keyboard-shortcut hint
+ * shown while it's empty. Pass `suggestions` for an animated "Try: …"
+ * placeholder that cycles while the field is empty.
+ * Import from "@instruments/materia-ui/components/search-input".
+ *
+ * @example
+ * ```tsx
+ * <SearchInput
+ *   onChange={setQuery}
+ *   placeholder="Search products..."
+ *   shortcutHint="⌘K"
+ *   value={query}
+ * />
+ * ```
+ *
+ * @example Animated suggestions
+ * ```tsx
+ * <SearchInput
+ *   onChange={setQuery}
+ *   suggestions={["white dove", "alabaster", "naval"]}
+ *   value={query}
+ * />
+ * ```
+ *
+ * @bestPractice Use `SearchInput` for search/filter fields - it supplies the search icon, a clear button, and (via `shortcutHint`) a `Kbd` hint; don't rebuild these on a plain `Input`.
+ * @bestPractice `onChange` receives the next string on every keystroke and on clear (not a DOM event) - pass `value` for controlled use or `defaultValue` for uncontrolled.
+ * @bestPractice Pass cycling placeholder ideas via `suggestions` (which suppresses the static `placeholder`); `shortcutHint` shows only while empty and is swapped for the clear button once the field has a value.
+ * @bestPractice Pill (`radius="full"`) at the 48px `xl` default is the search signature - so leave both defaults alone in standard search/filter placements; pass `size` explicitly for compact embedded contexts (popovers, table headers).
+ * @category forms
+ */
+export declare const SearchInput: ({ className, size, radius, hasError, disabled, value, defaultValue, onChange, onClear, shortcutHint, placeholder, suggestions, suggestionPrefix, suggestionIntervalMs, testId, ...props }: SearchInputProps) => React.JSX.Element;