@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,100 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FadeOverlay } from "@instruments/materia-ui/components/fade-overlay";
+import { easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { useEffect, useState } from "react";
+const PEAK_ALPHA = 0.35;
+const ANGLE = "-20deg";
+const WIDTH_PERCENT = 28;
+const DEFAULT_SWEEP_DURATION_SECONDS = 1.4;
+/** Faster one-shot for entrance choreography - snappy, not sluggish. */
+const ONCE_SWEEP_DURATION_SECONDS = 0.7;
+const INTERVAL_SECONDS = 6;
+const FADE_OUT_MS = 450;
+const buildSweepGradient = () => {
+    const halfWidth = WIDTH_PERCENT / 2;
+    const start = 50 - halfWidth;
+    const end = 50 + halfWidth;
+    const peak = `rgba(255, 255, 255, ${PEAK_ALPHA})`;
+    return [
+        `linear-gradient(${ANGLE},`,
+        "transparent 0%,",
+        `transparent ${start}%,`,
+        `${peak} 50%,`,
+        `transparent ${end}%,`,
+        "transparent 100%",
+        ")",
+    ].join(" ");
+};
+const ShineSweep = ({ radius, className, playOnce, duration, onSweepComplete, }) => {
+    const gradient = buildSweepGradient();
+    const repeatDelay = playOnce ? 0 : Math.max(0, INTERVAL_SECONDS - duration);
+    return (_jsx("div", { "aria-hidden": true, className: cn("pointer-events-none absolute inset-0 overflow-hidden", className), "data-slot": "shine", style: { borderRadius: radius, mixBlendMode: "soft-light" }, children: _jsx(m.div, { animate: { backgroundPosition: ["150% 150%", "-50% -50%"] }, className: "absolute inset-0", onAnimationComplete: () => {
+                if (playOnce) {
+                    onSweepComplete?.();
+                }
+            }, style: {
+                background: gradient,
+                backgroundRepeat: "no-repeat",
+                backgroundSize: "300% 300%",
+            }, transition: {
+                duration,
+                ease: easings.out,
+                repeat: playOnce ? 0 : Number.POSITIVE_INFINITY,
+                repeatDelay,
+            } }) }));
+};
+/**
+ * A subtle diagonal specular sweep for drawing attention to interactive
+ * surfaces. Unlike a skeleton shimmer, Shine runs as an occasional flick
+ * with rest between passes - one quick highlight every few seconds - so it
+ * reads as "this surface is alive" rather than "content is loading".
+ *
+ * Pass `playOnce` for a single entrance sweep (then it fades out).
+ *
+ * Two usage shapes:
+ *   1. Wrapper - pass `children` and Shine wraps them in a relative box.
+ *   2. Overlay - render without children inside an existing relative parent.
+ *
+ * Uses `mix-blend-mode: soft-light` so the highlight harmonizes with the
+ * underlying colour instead of painting pure white.
+ *
+ * Honours `prefers-reduced-motion` - renders nothing when motion is reduced
+ * (a static band would read as a permanent artefact, not a cue). When
+ * `visible` flips to `false`, the sweep fades out then unmounts so its rAF
+ * loop stops.
+ *
+ * @bestPractice Use `Shine` for a periodic "this surface is alive" flick on an interactive element - not for loading; a continuous text sweep is `Shimmer` and a content placeholder is `Skeleton`.
+ * @bestPractice Use `playOnce` for entrance choreography that should not loop.
+ * @bestPractice Either pass `children` (Shine wraps them in a relative box) or render it bare inside an existing `position: relative` parent - otherwise the sweep has nothing to overlay.
+ * @bestPractice Needs `ReducedMotionProvider`; under reduced motion it renders nothing (a static band would look like a permanent artefact), so don't rely on it as persistent decoration.
+ * @category motion
+ */
+export const Shine = ({ visible = true, radius = 9999, className, children, playOnce = false, onPlayComplete, duration, }) => {
+    const sweepDuration = duration ??
+        (playOnce ? ONCE_SWEEP_DURATION_SECONDS : DEFAULT_SWEEP_DURATION_SECONDS);
+    /** Only used for playOnce - marks the sweep finished so FadeOverlay can exit. */
+    const [onceFinished, setOnceFinished] = useState(false);
+    const overlayVisible = playOnce ? visible && !onceFinished : visible;
+    const handleSweepComplete = () => {
+        if (playOnce) {
+            setOnceFinished(true);
+        }
+    };
+    useEffect(() => {
+        if (!onceFinished) {
+            return () => {
+                // sweep still running; nothing to report yet
+            };
+        }
+        const timeoutId = window.setTimeout(() => {
+            onPlayComplete?.();
+        }, FADE_OUT_MS);
+        return () => {
+            window.clearTimeout(timeoutId);
+        };
+    }, [onceFinished, onPlayComplete]);
+    return (_jsx(FadeOverlay, { ...(className === undefined ? {} : { className }), overlay: _jsx(ShineSweep, { duration: sweepDuration, playOnce: playOnce, radius: radius, onSweepComplete: handleSweepComplete }), radius: radius, visible: overlayVisible, children: children }));
+};

package/dist/components/shine.d.ts

@@ -0,0 +1,2 @@
+export type { ShineProps } from "./shine/shine-root.js";
+export { Shine } from "./shine/shine-root.js";

package/dist/components/shine.js

@@ -0,0 +1 @@
+export { Shine } from "./shine/shine-root.js";

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

@@ -0,0 +1,5 @@
+/**
+ * sidepanelAnatomy helper for Sidepanel.
+ * Import from "@instruments/materia-ui/components/sidepanel".
+ */
+export declare const sidepanelAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

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

@@ -0,0 +1,61 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * sidepanelAnatomy helper for Sidepanel.
+ * Import from "@instruments/materia-ui/components/sidepanel".
+ */
+export const sidepanelAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Element that opens the panel",
+            label: "SidepanelTrigger",
+            slot: "sidepanel-trigger",
+        },
+        {
+            description: "Backdrop shown behind the panel in modal mode",
+            label: "SidepanelOverlay",
+            slot: "sidepanel-overlay",
+        },
+        {
+            children: [
+                {
+                    children: [
+                        {
+                            description: "Panel heading",
+                            label: "SidepanelTitle",
+                            slot: "sidepanel-title",
+                        },
+                        {
+                            description: "Supporting summary beneath the title",
+                            label: "SidepanelDescription",
+                            slot: "sidepanel-description",
+                        },
+                        {
+                            description: "Left and right button clusters in the header",
+                            label: "SidepanelControls",
+                            slot: "sidepanel-controls",
+                        },
+                    ],
+                    description: "Header area with title, description, and controls",
+                    label: "SidepanelHeader",
+                    slot: "sidepanel-header",
+                },
+                {
+                    description: "Scrollable main content region",
+                    label: "SidepanelBody",
+                    slot: "sidepanel-body",
+                },
+                {
+                    description: "Footer for primary actions",
+                    label: "SidepanelFooter",
+                    slot: "sidepanel-footer",
+                },
+            ],
+            description: "The sliding panel surface",
+            label: "SidepanelContent",
+            slot: "sidepanel-content",
+        },
+    ],
+    description: "Root controlling open state for the slide-out panel",
+    label: "Sidepanel",
+    slot: "sidepanel",
+});

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

@@ -0,0 +1,17 @@
+import type { ComponentProps } from "react";
+type SidepanelBodyProps = ComponentProps<"div">;
+/**
+ * Body container for sidepanel content. Provides vertical flex layout
+ * for header, scrollable content, and footer.
+ */
+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.
+ *
+ * @bestPractice Put exactly one `SidepanelScroll` inside `SidepanelBody`, between the header and footer, rather than a hand-rolled `flex-1 overflow-y-auto` div.
+ */
+declare const SidepanelScroll: ({ className, ...props }: SidepanelScrollProps) => import("react").JSX.Element;
+export { SidepanelBody, type SidepanelBodyProps, SidepanelScroll, type SidepanelScrollProps, };

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

@@ -0,0 +1,20 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Body container for sidepanel content. Provides vertical flex layout
+ * for header, scrollable content, and footer.
+ */
+const SidepanelBody = ({ className, ...props }) => (_jsx(Flex, { className: cn("flex-1 overflow-hidden", 
+    // 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.
+ *
+ * @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 }));
+export { SidepanelBody, SidepanelScroll, };

package/dist/components/sidepanel/sidepanel-close-button.d.ts

@@ -0,0 +1,19 @@
+import type { ButtonProps } from "../button.js";
+export interface SidepanelCloseButtonProps extends Omit<ButtonProps, "children" | "emphasis" | "icon" | "size"> {
+    /** Accessible label. Defaults to "Close panel". */
+    "aria-label"?: string;
+}
+/**
+ * Ghost icon button that closes a sidepanel: the one close-button look for the
+ * family. Generic and imperative: it calls the supplied `onClick` rather than
+ * reaching into any store or context, so it works with the store-wired app
+ * provider and with Base UI-controlled panels alike.
+ *
+ * `SidepanelClose` renders this same button wired to Base UI's `Dialog.Close`.
+ *
+ * @example
+ * ```tsx
+ * <SidepanelCloseButton onClick={closeSidepanel} />
+ * ```
+ */
+export declare const SidepanelCloseButton: ({ "aria-label": ariaLabel, ...props }: SidepanelCloseButtonProps) => import("react").JSX.Element;

package/dist/components/sidepanel/sidepanel-close-button.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { Button } from "../button.js";
+/**
+ * Ghost icon button that closes a sidepanel: the one close-button look for the
+ * family. Generic and imperative: it calls the supplied `onClick` rather than
+ * reaching into any store or context, so it works with the store-wired app
+ * provider and with Base UI-controlled panels alike.
+ *
+ * `SidepanelClose` renders this same button wired to Base UI's `Dialog.Close`.
+ *
+ * @example
+ * ```tsx
+ * <SidepanelCloseButton onClick={closeSidepanel} />
+ * ```
+ */
+export const SidepanelCloseButton = ({ "aria-label": ariaLabel = "Close panel", ...props }) => (_jsx(Button, { "aria-label": ariaLabel, emphasis: "ghost", icon: X, size: "icon-sm", ...props }));

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

@@ -0,0 +1,13 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SidepanelCloseProps = Omit<ComponentProps<typeof DialogPrimitive.Close>, "className"> & {
+    className?: string;
+};
+/**
+ * Closes the sidepanel when activated. With no children it renders
+ * `SidepanelCloseButton` (the ghost X icon button, labelled "Close"); with
+ * children it renders a ghost `Button` around them. Pass `render` to supply
+ * your own button.
+ */
+declare const SidepanelClose: ({ children, render, ...props }: SidepanelCloseProps) => import("react").JSX.Element;
+export { SidepanelClose, type SidepanelCloseProps };

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

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { Button } from "../button.js";
+import { SidepanelCloseButton } from "./sidepanel-close-button.js";
+/**
+ * Closes the sidepanel when activated. With no children it renders
+ * `SidepanelCloseButton` (the ghost X icon button, labelled "Close"); with
+ * children it renders a ghost `Button` around them. Pass `render` to supply
+ * your own button.
+ */
+const SidepanelClose = ({ children, render, ...props }) => {
+    const hasChildren = children !== undefined && children !== null;
+    const defaultRender = hasChildren ? (_jsx(Button, { emphasis: "ghost", size: "sm" })) : (_jsx(SidepanelCloseButton, { "aria-label": "Close" }));
+    return (_jsx(DialogPrimitive.Close, { "data-component": "sidepanel-close", "data-slot": "sidepanel-close", render: render ?? defaultRender, ...props, children: children }));
+};
+export { SidepanelClose };

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

@@ -0,0 +1,39 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SidepanelWidth = "default" | "full";
+type SidepanelContentProps = Omit<ComponentProps<typeof DialogPrimitive.Popup>, "className" | "render"> & {
+    /** Extra classes for the panel surface. */
+    className?: string;
+    /** Whether the sidepanel is open (required for exit animations) */
+    open?: boolean;
+    /** Panel width: "default" (440px inset) or "full" (full viewport) */
+    width?: SidepanelWidth;
+    /**
+     * The panel's accessible name when it renders no visible `SidepanelTitle`.
+     * A mounted `SidepanelTitle` takes over, so the panel never has two titles.
+     */
+    title?: string;
+    /** Whether to show the backdrop overlay (default: true). Hiding it also stops outside presses from dismissing the panel. */
+    showOverlay?: boolean;
+    /** Whether a nested panel is currently open (triggers scale/shift effect) */
+    nestedOpen?: boolean;
+};
+/**
+ * Main content area of the sidepanel.
+ * Includes portal and overlay automatically.
+ *
+ * - `width="default"`: Fixed 440px width, inset from edges with rounded corners
+ * - `width="full"`: Full viewport coverage with safe area padding (mobile-first)
+ *
+ * When `nestedOpen` is true, the panel shifts left and scales down
+ * to create a stacking effect (only applies to default width).
+ *
+ * On open, a keyboard user lands on the panel's first control; a pointer,
+ * touch or programmatic open focuses the panel itself, so no focus ring shows
+ * on first paint. Pass `initialFocus` to choose otherwise.
+ *
+ * @bestPractice Open the panel from a `SidepanelTrigger` where you can: Base UI then knows a keyboard opened it and moves focus to the first control. Opened from app state, it focuses the panel surface, which still announces the panel's name.
+ * @bestPractice Name the panel once: render a visible `SidepanelTitle`, or pass `title` when the design has no visible heading.
+ */
+declare const SidepanelContent: ({ className, children, open, width, title, showOverlay, nestedOpen, initialFocus, ...props }: SidepanelContentProps) => import("react").JSX.Element;
+export { SidepanelContent, type SidepanelContentProps, type SidepanelWidth };

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

@@ -0,0 +1,68 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { springs } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { use, useCallback, useEffect, useRef, useState } from "react";
+import { SidepanelOverlayHiddenContext } from "./sidepanel-dismiss.js";
+import { SidepanelTitleRegistryContext } from "./sidepanel-title-context.js";
+const popupSurfaceClasses = (isFullWidth) => cn("fixed z-50", "bg-card flex flex-col overflow-hidden outline-none", isFullWidth
+    ? "pt-safe inset-0"
+    : [
+        // Full viewport below `lg`. The floating 440px inset card starts at
+        // `lg`, the same breakpoint at which `SidebarPanel variant="gutter"`
+        // reserves its column. Below `lg` the panel can't sit beside content
+        // without crushing it (a 464px footprint beside a 256px sidebar
+        // leaves a tablet almost nothing), so it overlays full-bleed.
+        "pt-safe inset-0",
+        "lg:inset-y-6 lg:right-6 lg:left-auto lg:pt-0",
+        "lg:w-110",
+        "lg:origin-right",
+        "lg:rounded-4xl lg:border lg:shadow-lg dark:lg:shadow-none",
+    ]);
+/**
+ * Main content area of the sidepanel.
+ * Includes portal and overlay automatically.
+ *
+ * - `width="default"`: Fixed 440px width, inset from edges with rounded corners
+ * - `width="full"`: Full viewport coverage with safe area padding (mobile-first)
+ *
+ * When `nestedOpen` is true, the panel shifts left and scales down
+ * to create a stacking effect (only applies to default width).
+ *
+ * On open, a keyboard user lands on the panel's first control; a pointer,
+ * touch or programmatic open focuses the panel itself, so no focus ring shows
+ * on first paint. Pass `initialFocus` to choose otherwise.
+ *
+ * @bestPractice Open the panel from a `SidepanelTrigger` where you can: Base UI then knows a keyboard opened it and moves focus to the first control. Opened from app state, it focuses the panel surface, which still announces the panel's name.
+ * @bestPractice Name the panel once: render a visible `SidepanelTitle`, or pass `title` when the design has no visible heading.
+ */
+const SidepanelContent = ({ className, children, open = true, width = "default", title = "Side panel", showOverlay = true, nestedOpen = false, initialFocus, ...props }) => {
+    const isFullWidth = width === "full";
+    const setOverlayHidden = use(SidepanelOverlayHiddenContext);
+    const [visibleTitles, setVisibleTitles] = useState(0);
+    const popupRef = useRef(null);
+    useEffect(() => {
+        setOverlayHidden?.(!showOverlay);
+    }, [setOverlayHidden, showOverlay]);
+    const registerTitle = useCallback((present) => {
+        setVisibleTitles((count) => count + (present ? 1 : -1));
+    }, []);
+    // Keyboard opens keep Base UI's default (the first tabbable control); every
+    // other open, including a controlled one with no known interaction, focuses
+    // the popup so a programmatic focus on page load paints no ring.
+    const pointerSafeInitialFocus = (openType) => openType === "keyboard" ? true : popupRef.current;
+    return (_jsx(AnimatePresence, { children: open && (_jsxs(DialogPrimitive.Portal, { keepMounted: true, children: [_jsx(DialogPrimitive.Backdrop, { forceRender: true, hidden: false, render: _jsx(m.div, { animate: { opacity: showOverlay ? 1 : 0 }, className: cn("fixed inset-0 z-50 bg-black/40", !showOverlay && "pointer-events-none"), exit: { opacity: 0 }, initial: { opacity: 0 }, transition: springs.standard }) }), _jsx(DialogPrimitive.Popup, { "aria-label": visibleTitles > 0 ? undefined : title, hidden: false, initialFocus: initialFocus ?? pointerSafeInitialFocus, render: _jsx(m.div
+                    // Base UI merges the render element's ref with its own and the
+                    // caller's, so the popup is reachable for initial focus.
+                    , { 
+                        // Base UI merges the render element's ref with its own and the
+                        // caller's, so the popup is reachable for initial focus.
+                        ref: popupRef, animate: {
+                            scale: nestedOpen && !isFullWidth ? 0.96 : 1,
+                            x: nestedOpen && !isFullWidth ? -32 : 0,
+                        }, className: cn(popupSurfaceClasses(isFullWidth), className), exit: { x: "calc(100% + 1.5rem)" }, initial: { x: "calc(100% + 1.5rem)" }, transition: springs.standard }), "data-component": "sidepanel-content", "data-sidepanel-wrapper": "", "data-slot": "sidepanel-content", ...props, children: _jsx(SidepanelTitleRegistryContext, { value: registerTitle, children: children }) })] }, "portal")) }));
+};
+export { SidepanelContent };

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

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+export interface SidepanelControlsProps {
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * Groups sidepanel control buttons with consistent spacing. Typically placed
+ * on the left and right of a `SidepanelHeader variant="bar"` to produce a
+ * space-between toolbar.
+ *
+ * @example
+ * ```tsx
+ * <SidepanelHeader variant="bar">
+ *   <SidepanelControls>
+ *     <Button emphasis="ghost" icon={ArrowLeft} size="icon-sm" />
+ *   </SidepanelControls>
+ *   <SidepanelControls>
+ *     <Button emphasis="ghost" icon={Heart} size="icon-sm" />
+ *     <SidepanelCloseButton onClick={close} />
+ *   </SidepanelControls>
+ * </SidepanelHeader>
+ * ```
+ */
+export declare const SidepanelControls: ({ children, className, }: SidepanelControlsProps) => import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { HStack } from "../stack.js";
+/**
+ * Groups sidepanel control buttons with consistent spacing. Typically placed
+ * on the left and right of a `SidepanelHeader variant="bar"` to produce a
+ * space-between toolbar.
+ *
+ * @example
+ * ```tsx
+ * <SidepanelHeader variant="bar">
+ *   <SidepanelControls>
+ *     <Button emphasis="ghost" icon={ArrowLeft} size="icon-sm" />
+ *   </SidepanelControls>
+ *   <SidepanelControls>
+ *     <Button emphasis="ghost" icon={Heart} size="icon-sm" />
+ *     <SidepanelCloseButton onClick={close} />
+ *   </SidepanelControls>
+ * </SidepanelHeader>
+ * ```
+ */
+export const SidepanelControls = ({ children, className, }) => (_jsx(HStack, { align: "center", className: className, gap: "xs", children: children }));

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

@@ -0,0 +1,10 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SidepanelDescriptionProps = ComponentProps<typeof DialogPrimitive.Description>;
+/**
+ * Description element for the sidepanel. Provides accessible description.
+ */
+declare const SidepanelDescription: ({ className: incoming, ...props }: Omit<Omit<import("@base-ui/react").DialogDescriptionProps, "ref"> & import("react").RefAttributes<HTMLParagraphElement>, "className"> & {
+    className?: string;
+}) => import("react").ReactElement;
+export { SidepanelDescription, type SidepanelDescriptionProps };

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

@@ -0,0 +1,12 @@
+"use client";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { OVERLAY_DESCRIPTION } from "../../tokens/overlay-styles.js";
+import { makeOverlayDescription } from "../overlay-primitives.js";
+/**
+ * Description element for the sidepanel. Provides accessible description.
+ */
+const SidepanelDescription = makeOverlayDescription(DialogPrimitive.Description, {
+    className: OVERLAY_DESCRIPTION,
+    slot: "sidepanel-description",
+});
+export { SidepanelDescription };

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

@@ -0,0 +1,14 @@
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+/**
+ * Lets `SidepanelContent` tell its root that the scrim is hidden
+ * (`showOverlay={false}`): the panel is then a non-blocking surface, so outside
+ * presses must not dismiss it.
+ */
+export declare const SidepanelOverlayHiddenContext: import("react").Context<((hidden: boolean) => void) | null>;
+/**
+ * Dialog root for the sidepanel family. Vetoes outside-press and focus-out
+ * dismissal while the content has its scrim hidden, then forwards every other
+ * change to the caller's `onOpenChange`.
+ */
+export declare const SidepanelDialogRoot: ({ onOpenChange, ...props }: ComponentProps<typeof DialogPrimitive.Root>) => import("react").JSX.Element;

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

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { createContext, useState } from "react";
+/**
+ * Lets `SidepanelContent` tell its root that the scrim is hidden
+ * (`showOverlay={false}`): the panel is then a non-blocking surface, so outside
+ * presses must not dismiss it.
+ */
+export const SidepanelOverlayHiddenContext = createContext(null);
+/**
+ * Dialog root for the sidepanel family. Vetoes outside-press and focus-out
+ * dismissal while the content has its scrim hidden, then forwards every other
+ * change to the caller's `onOpenChange`.
+ */
+export const SidepanelDialogRoot = ({ onOpenChange, ...props }) => {
+    const [overlayHidden, setOverlayHidden] = useState(false);
+    return (_jsx(SidepanelOverlayHiddenContext, { value: setOverlayHidden, children: _jsx(DialogPrimitive.Root, { onOpenChange: (open, eventDetails) => {
+                if (overlayHidden &&
+                    (eventDetails.reason === "outside-press" ||
+                        eventDetails.reason === "focus-out")) {
+                    eventDetails.cancel();
+                    return;
+                }
+                onOpenChange?.(open, eventDetails);
+            }, ...props }) }));
+};

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

@@ -0,0 +1,7 @@
+import type { ComponentProps } from "react";
+type SidepanelFooterProps = ComponentProps<"div">;
+/**
+ * Footer section of the sidepanel. Typically contains action buttons.
+ */
+declare const SidepanelFooter: ({ className, ...props }: SidepanelFooterProps) => import("react").JSX.Element;
+export { SidepanelFooter, type SidepanelFooterProps };

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

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Footer section of the sidepanel. Typically contains action buttons.
+ */
+const SidepanelFooter = ({ className, ...props }) => (_jsx(Flex, { className: cn("mt-auto border-t px-6 py-4", className), "data-component": "sidepanel-footer", "data-slot": "sidepanel-footer", direction: "column", gap: "xs", ...props }));
+export { SidepanelFooter };

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

@@ -0,0 +1,21 @@
+import type { ComponentProps } from "react";
+/**
+ * Header layout:
+ * - `default` - a stacked title/description region with a bottom border,
+ *   for the accessible name of a Base UI-driven panel.
+ * - `bar` - a floating, space-between control toolbar pinned to the top of the
+ *   panel (the app's product-detail / cart / order sidepanel header). Pair with
+ *   two `SidepanelControls` groups for left/right button clusters. Transparent
+ *   by design: the panel content shows through behind the (self-backed) control
+ *   pills. Consumers wanting a solid backdrop can pass one via `className`.
+ */
+type SidepanelHeaderVariant = "bar" | "default";
+type SidepanelHeaderProps = ComponentProps<"div"> & {
+    variant?: SidepanelHeaderVariant;
+};
+/**
+ * Header section of the sidepanel. See {@link SidepanelHeaderVariant} for the
+ * available layouts.
+ */
+declare const SidepanelHeader: ({ className, variant, ...props }: SidepanelHeaderProps) => import("react").JSX.Element;
+export { SidepanelHeader, type SidepanelHeaderProps, type SidepanelHeaderVariant, };

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

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const HEADER_CLASSES = {
+    // Absolute positioning ignores the panel's pt-safe padding, so the bar
+    // offsets itself by the top safe-area inset (0 everywhere but notched
+    // phones, where the full-bleed panel would otherwise put it under the
+    // status bar).
+    bar: "absolute inset-x-0 top-[env(safe-area-inset-top,0px)] z-10 flex h-18 items-center justify-between px-6",
+    default: "flex flex-col gap-1.5 border-b px-6 py-4",
+};
+/**
+ * Header section of the sidepanel. See {@link SidepanelHeaderVariant} for the
+ * available layouts.
+ */
+const SidepanelHeader = ({ className, variant = "default", ...props }) => (_jsx("div", { className: cn(HEADER_CLASSES[variant], className), "data-component": "sidepanel-header", "data-slot": "sidepanel-header", "data-variant": variant, ...props }));
+export { SidepanelHeader, };

package/dist/components/sidepanel/sidepanel-nested-root.d.ts

@@ -0,0 +1,12 @@
+import type { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SidepanelNestedRootProps = ComponentProps<typeof DialogPrimitive.Root>;
+/**
+ * Nested root component for stacking sidepanels.
+ * Creates a stacking effect where the parent panel shifts and scales.
+ *
+ * @param props.open - Controlled open state
+ * @param props.onOpenChange - Callback when open state changes, with Base UI's `(open, eventDetails)` signature
+ */
+declare const SidepanelNestedRoot: (props: SidepanelNestedRootProps) => import("react").JSX.Element;
+export { SidepanelNestedRoot, type SidepanelNestedRootProps };

package/dist/components/sidepanel/sidepanel-nested-root.js

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SidepanelDialogRoot } from "./sidepanel-dismiss.js";
+/**
+ * Nested root component for stacking sidepanels.
+ * Creates a stacking effect where the parent panel shifts and scales.
+ *
+ * @param props.open - Controlled open state
+ * @param props.onOpenChange - Callback when open state changes, with Base UI's `(open, eventDetails)` signature
+ */
+const SidepanelNestedRoot = (props) => (_jsx(SidepanelDialogRoot, { "data-component": "sidepanel-nested", "data-slot": "sidepanel-nested", ...props }));
+export { SidepanelNestedRoot };

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

@@ -0,0 +1,18 @@
+import type { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { ComponentProps } from "react";
+type SidepanelRootProps = ComponentProps<typeof DialogPrimitive.Root>;
+/**
+ * Root component for a sidepanel. Wraps Base UI Dialog.Root.
+ *
+ * @param props.open - Controlled open state (pair with onOpenChange)
+ * @param props.defaultOpen - Uncontrolled initial open state
+ * @param props.onOpenChange - Callback when open state changes, with Base UI's `(open, eventDetails)` signature
+ * @param props.modal - Whether the background is inert (default: true)
+ * @param props.disablePointerDismissal - Keep the panel open on outside presses
+ *
+ * @bestPractice Reach for `Sidepanel` when you need nested sub-panels or a non-modal panel (`modal={false}`) that leaves the page interactive; a single focused edge panel is a `Sheet`.
+ * @bestPractice Compose nested panels with `SidepanelNestedRoot`, and always render a `SidepanelTitle` for the accessible name.
+ * @category overlays
+ */
+declare const SidepanelRoot: (props: SidepanelRootProps) => import("react").JSX.Element;
+export { SidepanelRoot, type SidepanelRootProps };