@instruments/materia-ui 0.1.0

package/dist/compositions/sidebar/sidebar-resize-handle.js

@@ -0,0 +1,159 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useRef } from "react";
+import { usePointerDrag } from "../../hooks/use-pointer-drag.js";
+import { SIDEBAR_WIDTH_COLLAPSE_THRESHOLD_PX, SIDEBAR_WIDTH_DEFAULT_PX, SIDEBAR_WIDTH_EXPAND_THRESHOLD_PX, SIDEBAR_WIDTH_ICON_PX, SIDEBAR_WIDTH_MAX_PX, SIDEBAR_WIDTH_MIN_PX, SIDEBAR_WIDTH_STEP_PX, } from "../sidebar/sidebar-constants.js";
+import { useSidebar, useSidebarResize } from "../sidebar/sidebar-provider.js";
+/** How much slower than the pointer the collapsed rail stretches (rubber-band). */
+const STRETCH_RESISTANCE = 0.5;
+/** Keyboard resize: ←/→ step by a fixed amount, Home/End jump to min/max. */
+const getResizeKeyHandler = (side, setWidth) => (event) => {
+    // On the left side ← shrinks and → grows; mirror on the right.
+    const shrink = side === "left" ? "ArrowLeft" : "ArrowRight";
+    const grow = side === "left" ? "ArrowRight" : "ArrowLeft";
+    switch (event.key) {
+        case shrink: {
+            event.preventDefault();
+            setWidth((current) => current - SIDEBAR_WIDTH_STEP_PX);
+            break;
+        }
+        case grow: {
+            event.preventDefault();
+            setWidth((current) => current + SIDEBAR_WIDTH_STEP_PX);
+            break;
+        }
+        case "Home": {
+            event.preventDefault();
+            setWidth(SIDEBAR_WIDTH_MIN_PX);
+            break;
+        }
+        case "End": {
+            event.preventDefault();
+            setWidth(SIDEBAR_WIDTH_MAX_PX);
+            break;
+        }
+        default: {
+            break;
+        }
+    }
+};
+/**
+ * Hairline drag handle on the sidebar's inner edge (desktop only).
+ *
+ * Dragging never flips state mid-drag - past the limits the panel rubber-bands
+ * (tracks the pointer with resistance); the snap decision happens on RELEASE:
+ *
+ * - Expanded: drag to resize (clamped + cookie-persisted). Below the minimum
+ *   the panel compresses with resistance; release past the collapse threshold
+ *   snaps collapsed with a wobble, otherwise it wobbles back to the minimum.
+ * - Collapsed (icon rail): drag out and the rail stretches with resistance;
+ *   release past the expand threshold restores the expanded state with a
+ *   wobble, otherwise it wobbles back to the rail. A plain click expands
+ *   without the bounce.
+ * - Keyboard: ←/→ resize by a step, Home/End jump to min/max; double-click
+ *   resets to the default width.
+ *
+ * The drag mechanism (window-level listeners so the release always lands even
+ * as the handle reflows) lives in {@link usePointerDrag}; this component owns
+ * only the sidebar policy - thresholds, rubber-banding, and the magnetic snap.
+ */
+export const SidebarResizeHandle = ({ side }) => {
+    const { open, setOpen } = useSidebar();
+    const { setWidth, setIsResizing, setIsMagneticSnap, setStretchWidth, width } = useSidebarResize();
+    // The sidebar container's fixed edge, captured at drag start so width is
+    // measured from it (the container may be offset by centered/inset layouts).
+    const anchorRef = useRef(0);
+    // Whether this drag has actually moved (vs a click) - a collapsed click just
+    // expands without a stretch/bounce.
+    const movedRef = useRef(false);
+    // The expanded width at drag start. An inward drag commits shrinking widths as
+    // it passes towards the collapse threshold; if the gesture ends in a collapse
+    // we restore this snapshot so re-expanding returns to the width the user had
+    // (their default), not the narrow value the collapse motion swept through.
+    const startWidthRef = useRef(width);
+    const rawWidthFrom = (clientX) => side === "left" ? clientX - anchorRef.current : anchorRef.current - clientX;
+    const { isDragging, dragHandlers } = usePointerDrag({
+        cursor: "col-resize",
+        onStart: (event) => {
+            const container = event.currentTarget.closest('[data-slot="sidebar-container"]');
+            if (!container) {
+                return false;
+            }
+            const rect = container.getBoundingClientRect();
+            anchorRef.current = side === "left" ? rect.left : rect.right;
+            movedRef.current = false;
+            startWidthRef.current = width;
+            setIsResizing(true);
+            return true;
+        },
+        onMove: (event) => {
+            movedRef.current = true;
+            const raw = rawWidthFrom(event.clientX);
+            if (open) {
+                if (raw < SIDEBAR_WIDTH_MIN_PX) {
+                    // Below the clamp minimum: rubber-band compression - the panel keeps
+                    // shrinking, but slower than the pointer. No flip until release.
+                    const compressed = SIDEBAR_WIDTH_MIN_PX -
+                        (SIDEBAR_WIDTH_MIN_PX - raw) * STRETCH_RESISTANCE;
+                    setStretchWidth(Math.max(SIDEBAR_WIDTH_ICON_PX, compressed));
+                    return;
+                }
+                setStretchWidth(null);
+                setWidth(raw);
+                return;
+            }
+            // Collapsed: rubber-band stretch out of the rail, slower than the pointer.
+            const stretched = SIDEBAR_WIDTH_ICON_PX +
+                Math.max(0, raw - SIDEBAR_WIDTH_ICON_PX) * STRETCH_RESISTANCE;
+            setStretchWidth(stretched);
+        },
+        onEnd: (event) => {
+            const raw = rawWidthFrom(event.clientX);
+            if (open) {
+                // Released past the collapse threshold → snap collapsed with the wobble;
+                // otherwise wobble back to the clamped width.
+                if (movedRef.current && raw < SIDEBAR_WIDTH_COLLAPSE_THRESHOLD_PX) {
+                    setIsMagneticSnap(true);
+                    setOpen(false);
+                    // Undo the shrinking the collapse gesture committed so re-expanding
+                    // restores the pre-drag width (invisible now - the rail shows 72px).
+                    setWidth(startWidthRef.current);
+                }
+                else if (movedRef.current && raw < SIDEBAR_WIDTH_MIN_PX) {
+                    setIsMagneticSnap(true);
+                }
+            }
+            else if (movedRef.current) {
+                // Released past the expand threshold → snap expanded with the wobble;
+                // otherwise wobble back to the rail.
+                setIsMagneticSnap(true);
+                if (raw > SIDEBAR_WIDTH_EXPAND_THRESHOLD_PX) {
+                    setOpen(true);
+                }
+            }
+            else {
+                // A plain click on the collapsed rail expands (no bounce).
+                setOpen(true);
+            }
+            setStretchWidth(null);
+            setIsResizing(false);
+        },
+    });
+    const onKeyDown = getResizeKeyHandler(side, setWidth);
+    return (_jsx("button", { "aria-label": open ? "Resize sidebar" : "Expand sidebar", "aria-orientation": "vertical", "aria-valuemax": SIDEBAR_WIDTH_MAX_PX, "aria-valuemin": SIDEBAR_WIDTH_MIN_PX, "aria-valuenow": width, className: cn(
+        // A 16px hit zone Centred on the sidebar's inner edge (half over the
+        // panel, half over the content) so it's easy to grab from either side -
+        // with a centred hairline that gains contrast on hover/drag/focus. Desktop
+        // only. `-translate-x-1/2` (left) / `translate-x-1/2` (right) straddles
+        // the edge that `left-full` / `right-full` pins to.
+        "absolute inset-y-0 z-20 hidden w-4 cursor-col-resize touch-none border-0 bg-transparent p-0 select-none focus-visible:outline-none md:block", side === "left"
+            ? "left-full -translate-x-1/2"
+            : "right-full translate-x-1/2", "before:duration-quick before:absolute before:inset-y-0 before:left-1/2 before:w-px before:-translate-x-1/2 before:transition-colors", isDragging
+            ? "before:bg-foreground/20"
+            : "hover:before:bg-foreground/10 focus-visible:before:bg-foreground/20 before:bg-transparent"), "data-component": "sidebar-resize-handle", "data-slot": "sidebar-resize-handle", onDoubleClick: () => {
+            setWidth(SIDEBAR_WIDTH_DEFAULT_PX);
+        }, onKeyDown: onKeyDown, ...dragHandlers, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- a focusable window splitter; `<hr>` cannot take focus or pointer handlers without failing other a11y rules
+        role: "separator", title: "Drag to resize \u00B7 double-click to reset", type: "button" }));
+};

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

@@ -0,0 +1,38 @@
+import * as m from "motion/react-m";
+import type React from "react";
+type SidebarProps = Omit<React.ComponentProps<typeof m.div>, "onDrag" | "children"> & {
+    children?: React.ReactNode;
+    /**
+     * The brand row, lifted out of the sidebar into the shell's chrome layer on
+     * desktop: it sits above the shell's overlays (a mega menu, a search
+     * panel), which cover the sidebar's nav beneath it. It tracks the sidebar's
+     * width and collapse. On mobile and in a static sidebar it heads the column
+     * as an ordinary first child would. Pass a `SidebarHeader`.
+     */
+    header?: React.ReactNode;
+    /** Edge the sidebar docks to. @default "left" */
+    side?: "left" | "right";
+    /** Shell style: standard, floating (inset card), or inset (offset content). @default "sidebar" */
+    variant?: "sidebar" | "floating" | "inset";
+    /** Collapse behavior: slide off-canvas, shrink to icon rail, or never collapse. @default "offcanvas" */
+    collapsible?: "offcanvas" | "icon" | "none";
+    /**
+     * Show a drag handle on the sidebar's inner edge to resize its expanded
+     * width (desktop only). Width is clamped, cookie-persisted, and dragging past
+     * the collapse threshold magnetically snaps to collapsed. @default false
+     */
+    resizable?: boolean;
+};
+/**
+ * The sidebar shell. Reads open/collapsed state from {@link useSidebar}, so it
+ * must render inside a {@link SidebarProvider}.
+ *
+ * Adapts by viewport and `collapsible`: an animated docked shell on desktop, a
+ * slide-in `Sheet` on mobile, or a static column when `collapsible="none"`.
+ *
+ * @bestPractice Render `Sidebar` inside a `SidebarProvider` - it reads open/collapsed state from `useSidebar` and cannot work outside one.
+ * @bestPractice Choose `collapsible` deliberately: `offcanvas` slides fully away, `icon` shrinks to a rail, `none` is a static column that never adapts to the mobile `Sheet`.
+ * @category navigation
+ */
+export declare const Sidebar: ({ side, variant, collapsible, resizable, className, children, header, ...props }: SidebarProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,156 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from "@instruments/materia-ui/components/sheet";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { cssVariables } from "../../utils/css-variables.js";
+import { SIDEBAR_WIDTH_ICON, SIDEBAR_WIDTH_ICON_PX, SIDEBAR_WIDTH_MOBILE, } from "../sidebar/sidebar-constants.js";
+import { SIDEBAR_MAGNETIC_TRANSITION, SIDEBAR_TRANSITION, } from "../sidebar/sidebar-motion-config.js";
+import { useSidebar, useSidebarResize } from "../sidebar/sidebar-provider.js";
+import { SidebarResizeHandle } from "../sidebar/sidebar-resize-handle.js";
+const getSidebarGapWidth = (collapsible, state, variant, expandedWidth, stretchWidth) => {
+    if (collapsible === "offcanvas" && state === "collapsed") {
+        return "0px";
+    }
+    // Transient rubber-band width while dragging the resize handle (stretching
+    // out of the rail, or compressing below the expanded minimum).
+    if (stretchWidth !== null) {
+        return `${stretchWidth}px`;
+    }
+    if (state === "collapsed") {
+        if (variant === "floating") {
+            return `calc(${SIDEBAR_WIDTH_ICON} + 1rem)`;
+        }
+        return SIDEBAR_WIDTH_ICON;
+    }
+    return expandedWidth;
+};
+const getSidebarContainerWidth = (collapsible, state, variant, expandedWidth, stretchWidth) => {
+    // Transient rubber-band width while dragging (see getSidebarGapWidth).
+    if (stretchWidth !== null && collapsible !== "offcanvas") {
+        return `${stretchWidth}px`;
+    }
+    if (collapsible === "icon" && state === "collapsed") {
+        if (variant === "floating") {
+            return `calc(${SIDEBAR_WIDTH_ICON} + 1rem + 2px)`;
+        }
+        return SIDEBAR_WIDTH_ICON;
+    }
+    return expandedWidth;
+};
+const getSidebarOffcanvasPosition = (collapsible, state, side, expandedWidth) => {
+    if (collapsible !== "offcanvas") {
+        return {};
+    }
+    const offset = state === "collapsed" ? `calc(${expandedWidth} * -1)` : "0px";
+    if (side === "left") {
+        return { left: offset };
+    }
+    return { right: offset };
+};
+const getSidebarContainerClassName = (variant) => {
+    if (variant === "floating") {
+        return "p-2";
+    }
+    if (variant === "inset") {
+        return "";
+    }
+    // The edge rule is drawn over the rail rather than as a border, so the
+    // collapsed rail keeps its full width and its icons sit on a whole-pixel
+    // centre line.
+    return "after:bg-sidebar-border after:pointer-events-none after:absolute after:inset-y-0 after:w-px group-data-[side=left]:after:right-0 group-data-[side=right]:after:left-0";
+};
+/**
+ * Where the lifted brand row sits. Its surface is laid out at the widest the
+ * sidebar can be and clipped to the sidebar's current width, and an
+ * off-canvas sidebar slides it away, so it moves in step with the column
+ * without animating its width. Its content takes the sidebar's settled
+ * width at once, so anything centred in it centres on the rail.
+ */
+const getSidebarChromeGeometry = (collapsible, state, side, variant, expandedWidthPx, stretchWidth) => {
+    const laidOutPx = Math.max(expandedWidthPx, stretchWidth ?? 0);
+    let shownPx = stretchWidth ?? expandedWidthPx;
+    if (stretchWidth === null &&
+        state === "collapsed" &&
+        collapsible === "icon") {
+        // The floating rail carries its card's padding and border.
+        shownPx =
+            variant === "floating"
+                ? SIDEBAR_WIDTH_ICON_PX + 18
+                : SIDEBAR_WIDTH_ICON_PX;
+    }
+    const hiddenPx = laidOutPx - shownPx;
+    const offcanvas = collapsible === "offcanvas" && state === "collapsed";
+    const slidePx = offcanvas ? laidOutPx : 0;
+    const motion = side === "left"
+        ? {
+            clipPath: `inset(0px ${hiddenPx}px 0px 0px)`,
+            transform: `translateX(${-slidePx}px)`,
+        }
+        : {
+            clipPath: `inset(0px 0px 0px ${hiddenPx}px)`,
+            transform: `translateX(${slidePx}px)`,
+        };
+    return { laidOutPx, motion, shownPx };
+};
+/** The lifted brand row: the sidebar's part of the shell's chrome layer. */
+const SidebarChrome = ({ children, collapsible, expandedWidthPx, side, state, stretchWidth, transition, variant, }) => {
+    const { laidOutPx, motion, shownPx } = getSidebarChromeGeometry(collapsible, state, side, variant, expandedWidthPx, stretchWidth);
+    return (_jsx(m.div, { animate: motion, className: cn("h-header bg-background fixed top-0 z-40 hidden md:flex", side === "left" ? "left-0 justify-start" : "right-0 justify-end"), "data-component": "sidebar-chrome", "data-slot": "sidebar-chrome", initial: false, style: { width: laidOutPx }, ...(transition === undefined ? {} : { transition }), children: _jsx(Flex, { className: "h-full shrink-0", direction: "column", style: { width: shownPx }, children: children }) }));
+};
+/** Desktop (md+) sidebar shell with the animated gap and fixed container. */
+const SidebarDesktop = ({ children, className, collapsible, expandedWidth, expandedWidthPx, header, props, resizable, resizeHandle, side, state, stretchWidth, toggleSidebar, transition, variant, }) => (_jsxs("div", { className: "group group/sidebar peer text-sidebar-foreground hidden md:block", "data-collapsible": state === "collapsed" ? collapsible : "", "data-component": "sidebar", "data-side": side, "data-slot": "sidebar", "data-state": state, "data-variant": variant, children: [_jsx(m.div, { animate: {
+                // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the width change has to push the page content, which a transform cannot do
+                width: getSidebarGapWidth(collapsible, state, variant, expandedWidth, stretchWidth),
+            }, className: cn("relative bg-transparent", "group-data-[side=right]:rotate-180"), "data-component": "sidebar-gap", "data-slot": "sidebar-gap", initial: false, ...(transition === undefined ? {} : { transition }) }), _jsx(m.div, { animate: {
+                // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the width change has to push the page content, which a transform cannot do
+                width: getSidebarContainerWidth(collapsible, state, variant, expandedWidth, stretchWidth),
+                ...getSidebarOffcanvasPosition(collapsible, state, side, expandedWidth),
+            }, className: cn("fixed bottom-0 z-10 hidden md:flex", 
+            // With a lifted header the column starts beneath it, so nothing of
+            // the sidebar's own layer sits behind the chrome.
+            header === undefined ? "top-0" : "top-header", side === "left" ? "left-0" : "right-0", state === "collapsed" &&
+                collapsible === "icon" &&
+                (resizable ? "cursor-col-resize" : "cursor-e-resize"), 
+            // A lifted brand row joins one bar across the top, so the column
+            // beneath it takes no edge rule: the rule would start from nothing.
+            header === undefined && getSidebarContainerClassName(variant), className), "data-component": "sidebar-container", "data-slot": "sidebar-container", initial: false, ...(transition === undefined ? {} : { transition }), ...props, children: _jsxs("div", { className: "relative size-full", children: [state === "collapsed" && collapsible === "icon" ? (_jsx("button", { "aria-label": "Expand sidebar", className: cn("absolute inset-0 z-0 rounded-none", resizable ? "cursor-col-resize" : "cursor-e-resize"), "data-slot": "sidebar-expand-hitarea", onClick: toggleSidebar, type: "button" })) : null, _jsx(Flex, { className: "group-data-[variant=floating]:border-sidebar-border pointer-events-none size-full overflow-hidden group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:shadow-sm", "data-component": "sidebar-inner", "data-sidebar": "sidebar", "data-slot": "sidebar-inner", direction: "column", children: _jsx(Flex, { className: "pointer-events-auto size-full", direction: "column", children: children }) }), resizeHandle] }) }), header === undefined ? null : (_jsx(SidebarChrome, { collapsible: collapsible, expandedWidthPx: expandedWidthPx, side: side, state: state, stretchWidth: stretchWidth, transition: transition, variant: variant, children: header }))] }));
+/**
+ * The sidebar shell. Reads open/collapsed state from {@link useSidebar}, so it
+ * must render inside a {@link SidebarProvider}.
+ *
+ * Adapts by viewport and `collapsible`: an animated docked shell on desktop, a
+ * slide-in `Sheet` on mobile, or a static column when `collapsible="none"`.
+ *
+ * @bestPractice Render `Sidebar` inside a `SidebarProvider` - it reads open/collapsed state from `useSidebar` and cannot work outside one.
+ * @bestPractice Choose `collapsible` deliberately: `offcanvas` slides fully away, `icon` shrinks to a rail, `none` is a static column that never adapts to the mobile `Sheet`.
+ * @category navigation
+ */
+export const Sidebar = ({ side = "left", variant = "sidebar", collapsible = "offcanvas", resizable = false, className, children, header, ...props }) => {
+    const { isMobile, state, openMobile, setOpenMobile, toggleSidebar, hasHydrated, } = useSidebar();
+    const { width, isResizing, isMagneticSnap, stretchWidth } = useSidebarResize();
+    const expandedWidth = `${width}px`;
+    // Resize tracks the pointer instantly; the magnetic snap bounces; ordinary
+    // collapse/expand uses the calm spring (and no animation before hydration).
+    let transition = { duration: 0 };
+    if (isResizing) {
+        transition = { duration: 0 };
+    }
+    else if (isMagneticSnap) {
+        transition = SIDEBAR_MAGNETIC_TRANSITION;
+    }
+    else if (hasHydrated) {
+        transition = SIDEBAR_TRANSITION;
+    }
+    if (collapsible === "none") {
+        return (_jsxs(Flex, { className: cn("w-sidebar bg-background text-sidebar-foreground h-full", className), "data-component": "sidebar", "data-slot": "sidebar", direction: "column", children: [header, children] }));
+    }
+    if (isMobile) {
+        return (_jsx(Sheet, { onOpenChange: setOpenMobile, open: openMobile, children: _jsxs(SheetContent, { className: "w-sidebar bg-background text-sidebar-foreground p-0 [&>button]:hidden", "data-component": "sidebar", "data-mobile": "true", "data-sidebar": "sidebar", "data-slot": "sidebar", side: side, style: cssVariables({ "--sidebar-width": SIDEBAR_WIDTH_MOBILE }), children: [_jsxs(SheetHeader, { className: "sr-only", children: [_jsx(SheetTitle, { children: "Sidebar" }), _jsx(SheetDescription, { children: "Displays the mobile sidebar." })] }), _jsxs(Flex, { className: "size-full", direction: "column", children: [header, children] })] }) }));
+    }
+    return (_jsx(SidebarDesktop, { ...(className === undefined ? {} : { className }), collapsible: collapsible, expandedWidth: expandedWidth, expandedWidthPx: width, ...(header === undefined ? {} : { header }), props: props, resizable: resizable, resizeHandle: 
+        // Rendered while expanded (resize / drag-in-to-collapse) and while
+        // icon-collapsed (drag-out-to-expand). Off-canvas hides the container.
+        resizable && (state === "expanded" || collapsible === "icon") ? (_jsx(SidebarResizeHandle, { side: side })) : null, side: side, state: state, stretchWidth: stretchWidth, toggleSidebar: toggleSidebar, transition: transition, variant: variant, children: children }));
+};

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

@@ -0,0 +1,9 @@
+import { Separator } from "@instruments/materia-ui/components/separator";
+import type React from "react";
+type SidebarSeparatorProps = React.ComponentProps<typeof Separator> & {
+    /** Whether to show the border line. Defaults to true. */
+    showBorder?: boolean;
+};
+/** Divider between sidebar sections; `showBorder={false}` keeps the spacing while hiding the line. */
+export declare const SidebarSeparator: ({ className, showBorder, ...props }: SidebarSeparatorProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Separator } from "@instruments/materia-ui/components/separator";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Divider between sidebar sections; `showBorder={false}` keeps the spacing while hiding the line. */
+export const SidebarSeparator = ({ className, showBorder = true, ...props }) => (_jsx(Separator, { className: cn("w-auto", showBorder ? "bg-sidebar-border" : "bg-transparent", className), "data-component": "sidebar-separator", "data-sidebar": "separator", "data-slot": "sidebar-separator", ...props }));

package/dist/compositions/sidebar/sidebar-skip-link.d.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+/**
+ * The canonical "skip to content" link (WCAG 2.4.1). Visually hidden until
+ * focused, then pinned top-left. Rendered as the first child of `SidebarProvider`
+ * by default; apps with several providers can render it once at the root layout
+ * and pass `skipLink={false}` to each provider.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export declare const SidebarSkipLink: ({ label, targetId, className, children, ...props }: Omit<React.ComponentProps<"a">, "href"> & {
+    /** Link text. @default "Skip to content" */
+    label?: string;
+    /** Id of the target `<main>`. @default "main-content" */
+    targetId?: string;
+}) => React.JSX.Element;

package/dist/compositions/sidebar/sidebar-skip-link.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { SIDEBAR_INSET_ID } from "./sidebar-constants.js";
+/**
+ * The canonical "skip to content" link (WCAG 2.4.1). Visually hidden until
+ * focused, then pinned top-left. Rendered as the first child of `SidebarProvider`
+ * by default; apps with several providers can render it once at the root layout
+ * and pass `skipLink={false}` to each provider.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export const SidebarSkipLink = ({ label = "Skip to content", targetId = SIDEBAR_INSET_ID, className, children, ...props }) => (_jsx("a", { className: cn("focus:bg-primary focus:text-primary-foreground sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-50 focus:rounded-md focus:px-4 focus:py-2", className), "data-component": "sidebar-skip-link", "data-slot": "sidebar-skip-link", href: `#${targetId}`, ...props, children: children ?? label }));

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

@@ -0,0 +1,12 @@
+import { Button } from "@instruments/materia-ui/components/button";
+import type React from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+type SidebarTriggerProps = Omit<React.ComponentProps<typeof Button>, "icon"> & {
+    /** Icon to display. Defaults to PanelLeftCloseIcon. */
+    icon?: IconComponent;
+};
+/** Icon button that toggles the sidebar open/collapsed via {@link useSidebar}; must render inside a {@link SidebarProvider}. Any `onClick` runs before the toggle. */
+export declare const SidebarTrigger: ({ className, emphasis, onClick, icon, ...props }: SidebarTriggerProps) => React.JSX.Element;
+/** Thin hit-target strip along the sidebar's outer edge that toggles collapse on click; excluded from the tab order. */
+export declare const SidebarRail: ({ className, ...props }: React.ComponentProps<"button">) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { PanelLeftCloseIcon } from "lucide-react";
+import { useSidebar } from "../sidebar/sidebar-provider.js";
+/** Icon button that toggles the sidebar open/collapsed via {@link useSidebar}; must render inside a {@link SidebarProvider}. Any `onClick` runs before the toggle. */
+export const SidebarTrigger = ({ className, emphasis = "ghost", onClick, icon = PanelLeftCloseIcon, ...props }) => {
+    const { toggleSidebar } = useSidebar();
+    return (_jsx(Button, { "aria-label": "Toggle sidebar", className: cn(className), "data-component": "sidebar-trigger", "data-sidebar": "trigger", "data-slot": "sidebar-trigger", icon: icon, onClick: (event) => {
+            onClick?.(event);
+            toggleSidebar();
+        }, pressed: false, radius: "full", size: "icon-base", square: true, emphasis: emphasis, ...props }));
+};
+/** Thin hit-target strip along the sidebar's outer edge that toggles collapse on click; excluded from the tab order. */
+export const SidebarRail = ({ className, ...props }) => {
+    const { toggleSidebar } = useSidebar();
+    return (_jsx("button", { "aria-label": "Toggle sidebar", className: cn("hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-colors ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-0.5 sm:flex", "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize", "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize", "hover:group-data-[collapsible=offcanvas]:bg-sidebar group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full", "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2", "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2", className), "data-component": "sidebar-rail", "data-sidebar": "rail", "data-slot": "sidebar-rail", onClick: toggleSidebar, tabIndex: -1, title: "Toggle sidebar", type: "button", ...props }));
+};

package/dist/compositions/sidebar/use-sidebar-open-state.d.ts

@@ -0,0 +1,14 @@
+import type { StateUpdate } from "../../utils/resolve-state-update.js";
+/**
+ * Controlled-or-uncontrolled open state for the sidebar. `openProp` (with
+ * `onOpenChange`) controls it from outside; otherwise it is held here. Every
+ * change is persisted to the open cookie.
+ */
+export declare const useSidebarOpenState: ({ defaultOpen, onOpenChange, open: openProp, }: {
+    defaultOpen: boolean;
+    onOpenChange: ((open: boolean) => void) | undefined;
+    open: boolean | undefined;
+}) => {
+    open: boolean;
+    setOpen: (value: StateUpdate<boolean>) => void;
+};

package/dist/compositions/sidebar/use-sidebar-open-state.js

@@ -0,0 +1,25 @@
+"use client";
+import { useCallback, useState } from "react";
+import { resolveStateUpdate } from "../../utils/resolve-state-update.js";
+import { SIDEBAR_COOKIE_NAME } from "../sidebar/sidebar-constants.js";
+import { persistSidebarCookie } from "../sidebar/sidebar-cookie.js";
+/**
+ * Controlled-or-uncontrolled open state for the sidebar. `openProp` (with
+ * `onOpenChange`) controls it from outside; otherwise it is held here. Every
+ * change is persisted to the open cookie.
+ */
+export const useSidebarOpenState = ({ defaultOpen, onOpenChange, open: openProp, }) => {
+    const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+    const open = openProp ?? uncontrolledOpen;
+    const setOpen = useCallback((value) => {
+        const openState = resolveStateUpdate(value, open);
+        if (onOpenChange) {
+            onOpenChange(openState);
+        }
+        else {
+            setUncontrolledOpen(openState);
+        }
+        persistSidebarCookie(SIDEBAR_COOKIE_NAME, String(openState));
+    }, [onOpenChange, open]);
+    return { open, setOpen };
+};

package/dist/compositions/sidebar/use-sidebar-resize-state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Volatile resize state, split into its own context so it can update on every
+ * pointermove during a drag WITHOUT re-rendering the many `useSidebar`
+ * consumers (menu buttons, triggers, groups). Only the shell, header, and
+ * resize handle subscribe here.
+ */
+export interface SidebarResizeContextProps {
+    /** Current expanded width in px (resizable). */
+    width: number;
+    /** Set the expanded width in px; clamped and persisted to a cookie. */
+    setWidth: (px: number | ((prev: number) => number)) => void;
+    /** True while the user is dragging the resize handle (disables width animation). */
+    isResizing: boolean;
+    /** Set the resizing flag (called by the resize handle on drag start/end). */
+    setIsResizing: (resizing: boolean) => void;
+    /** True for one collapse/expand caused by the magnetic drag-snap (applies the bounce). */
+    isMagneticSnap: boolean;
+    /** Flag the next collapse/expand as a magnetic snap (bounce). Auto-resets. */
+    setIsMagneticSnap: (snap: boolean) => void;
+    /**
+     * Transient width (px) applied while dragging the handle OUT of the collapsed
+     * state - a rubber-band "stretch" past the icon rail before the expand snap.
+     * `null` when not stretching (the normal collapsed width applies).
+     */
+    stretchWidth: number | null;
+    /** Set the transient collapsed-stretch width (or `null` to clear). */
+    setStretchWidth: (px: number | null) => void;
+}
+/**
+ * Owns the sidebar's resize state: the clamped expanded width, the drag and
+ * magnetic-snap flags, and the transient rubber-band width. Returns the
+ * memoised value for the resize context.
+ */
+export declare const useSidebarResizeState: (defaultWidth: number) => SidebarResizeContextProps;

package/dist/compositions/sidebar/use-sidebar-resize-state.js

@@ -0,0 +1,62 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { resolveStateUpdate } from "../../utils/resolve-state-update.js";
+import { SIDEBAR_WIDTH_COOKIE_NAME, SIDEBAR_WIDTH_MAX_PX, SIDEBAR_WIDTH_MIN_PX, } from "../sidebar/sidebar-constants.js";
+import { persistSidebarCookie } from "../sidebar/sidebar-cookie.js";
+const MAGNETIC_SNAP_RESET_MS = 600;
+const clampWidth = (px) => Math.min(SIDEBAR_WIDTH_MAX_PX, Math.max(SIDEBAR_WIDTH_MIN_PX, px));
+/**
+ * Owns the sidebar's resize state: the clamped expanded width, the drag and
+ * magnetic-snap flags, and the transient rubber-band width. Returns the
+ * memoised value for the resize context.
+ */
+export const useSidebarResizeState = (defaultWidth) => {
+    const [isResizing, setIsResizing] = useState(false);
+    const [isMagneticSnap, setIsMagneticSnap] = useState(false);
+    const [stretchWidth, setStretchWidth] = useState(null);
+    const [width, setWidth] = useState(() => clampWidth(defaultWidth));
+    const setClampedWidth = useCallback((update) => {
+        setWidth((prev) => clampWidth(resolveStateUpdate(update, prev)));
+    }, []);
+    // Persist the resized width to its cookie - but ONLY when a drag settles, not
+    // on every intermediate width during the drag (writing to cookieStore ~60×/s
+    // janks the main thread). The effect keys on `isResizing`: while dragging it
+    // does nothing; when the drag ends it writes the final width once. Skips the
+    // initial value (which came FROM the cookie via defaultWidth).
+    const widthPersistReadyRef = useRef(false);
+    useEffect(() => {
+        if (!widthPersistReadyRef.current) {
+            widthPersistReadyRef.current = true;
+            return;
+        }
+        if (isResizing) {
+            return;
+        }
+        persistSidebarCookie(SIDEBAR_WIDTH_COOKIE_NAME, String(width));
+    }, [width, isResizing]);
+    // The magnetic-snap flag applies the bounce to exactly one collapse/expand;
+    // clear it once the bounce has run so ordinary toggles stay calm.
+    useEffect(() => {
+        let timer;
+        if (isMagneticSnap) {
+            timer = setTimeout(() => {
+                setIsMagneticSnap(false);
+            }, MAGNETIC_SNAP_RESET_MS);
+        }
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [isMagneticSnap]);
+    // Changes on every pointermove during a drag. Only the shell, header, and
+    // resize handle subscribe (via useSidebarResize).
+    return useMemo(() => ({
+        isMagneticSnap,
+        isResizing,
+        setIsMagneticSnap,
+        setIsResizing,
+        setStretchWidth,
+        setWidth: setClampedWidth,
+        stretchWidth,
+        width,
+    }), [width, setClampedWidth, isResizing, isMagneticSnap, stretchWidth]);
+};

package/dist/compositions/sidebar.d.ts

@@ -0,0 +1,29 @@
+export { sidebarAnatomy } from "./sidebar/sidebar-anatomy.js";
+export { CONTENT_COLUMN_CLASS, HEADER_HEIGHT, SIDEBAR_COOKIE_MAX_AGE, SIDEBAR_COOKIE_NAME, SIDEBAR_INSET_GAP, SIDEBAR_INSET_ID, SIDEBAR_KEYBOARD_SHORTCUT, SIDEBAR_MOBILE_BREAKPOINT_PX, SIDEBAR_WIDTH, SIDEBAR_WIDTH_COOKIE_NAME, SIDEBAR_WIDTH_DEFAULT_PX, SIDEBAR_WIDTH_ICON, SIDEBAR_WIDTH_MAX_PX, SIDEBAR_WIDTH_MIN_PX, SIDEBAR_WIDTH_MOBILE, } from "./sidebar/sidebar-constants.js";
+export { SidebarContent } from "./sidebar/sidebar-content.js";
+export { SidebarFooter } from "./sidebar/sidebar-footer.js";
+export { SidebarGroup } from "./sidebar/sidebar-group.js";
+export { SidebarHeader } from "./sidebar/sidebar-header.js";
+export { SidebarInput } from "./sidebar/sidebar-input.js";
+export { SidebarInset } from "./sidebar/sidebar-inset.js";
+export { SidebarLayoutHeader, SidebarLayoutHeaderActions, SidebarLayoutHeaderSearch, } from "./sidebar/sidebar-layout-header.js";
+export { SidebarMenu } from "./sidebar/sidebar-menu.js";
+export { SIDEBAR_TRANSITION } from "./sidebar/sidebar-motion-config.js";
+export { SidebarProvider, useSidebar, useSidebarResize, } from "./sidebar/sidebar-provider.js";
+export { Sidebar } from "./sidebar/sidebar-root.js";
+export { SidebarSeparator } from "./sidebar/sidebar-separator.js";
+export { SidebarTrigger } from "./sidebar/sidebar-trigger.js";
+export { SidebarGroupAction } from "./sidebar/sidebar-group.js";
+export { SidebarGroupContent } from "./sidebar/sidebar-group.js";
+export { SidebarGroupLabel } from "./sidebar/sidebar-group.js";
+export type { SidebarPanelProps } from "./sidebar/sidebar-panel.js";
+export { SidebarPanel } from "./sidebar/sidebar-panel.js";
+export { SidebarSkipLink } from "./sidebar/sidebar-skip-link.js";
+export { SidebarMenuAction } from "./sidebar/sidebar-menu-action.js";
+export { SidebarMenuBadge } from "./sidebar/sidebar-menu-badge.js";
+export { SidebarMenuButton } from "./sidebar/sidebar-menu-button.js";
+export { SidebarMenuItem } from "./sidebar/sidebar-menu.js";
+export { SidebarMenuLabel } from "./sidebar/sidebar-menu-label.js";
+export { SidebarMenuSkeleton } from "./sidebar/sidebar-menu-skeleton.js";
+export { SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarMenuSubScrollArea, } from "./sidebar/sidebar-menu-sub.js";
+export { SidebarRail } from "./sidebar/sidebar-trigger.js";