@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,9 @@
+import * as m from "motion/react-m";
+import type React from "react";
+type SidebarMenuLabelProps = React.ComponentProps<typeof m.span> & {
+    /** Delay (seconds) before the expand/collapse fade, for staggering labels. @default 0 */
+    delay?: number;
+};
+/** Animated label for sidebar menu buttons - syncs with sidebar collapse/expand */
+export declare const SidebarMenuLabel: ({ className, children, delay, ...props }: SidebarMenuLabelProps) => React.JSX.Element;
+export type { SidebarMenuLabelProps };

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

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { SIDEBAR_TRANSITION } from "../sidebar/sidebar-motion-config.js";
+import { useSidebar } from "../sidebar/sidebar-provider.js";
+/** Animated label for sidebar menu buttons - syncs with sidebar collapse/expand */
+export const SidebarMenuLabel = ({ className, children, delay = 0, ...props }) => {
+    const { state, isMobile } = useSidebar();
+    const isCollapsed = state === "collapsed" && !isMobile;
+    return (_jsx(AnimatePresence, { children: !isCollapsed && (_jsx(m.span, { animate: { opacity: 1 }, className: cn("shrink-0 whitespace-nowrap", className), "data-component": "sidebar-menu-label", "data-slot": "sidebar-menu-label", exit: { opacity: 0 }, initial: false, transition: {
+                ...SIDEBAR_TRANSITION,
+                delay,
+            }, ...props, children: children })) }));
+};

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

@@ -0,0 +1,10 @@
+import type React from "react";
+type SidebarMenuSkeletonProps = React.ComponentProps<"div"> & {
+    /** Also render a leading icon placeholder. @default false */
+    showIcon?: boolean;
+    /** Index for deterministic width (prevents SSR hydration mismatch) */
+    index?: number;
+};
+/** Loading placeholder mirroring a menu row; text width is seeded deterministically to avoid hydration mismatch. */
+export declare const SidebarMenuSkeleton: ({ className, showIcon, index, ...props }: SidebarMenuSkeletonProps) => React.JSX.Element;
+export type { SidebarMenuSkeletonProps };

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

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Skeleton } from "@instruments/materia-ui/components/skeleton";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useId, useMemo } from "react";
+import { cssVariables } from "../../utils/css-variables.js";
+const SKELETON_WIDTH_BASE = 50;
+const SKELETON_WIDTH_SPREAD = 40;
+/**
+ * Generate a deterministic pseudo-random width based on a seed.
+ * Uses a simple hash to get consistent values between server and client.
+ */
+const getSeededWidth = (seed) => {
+    const hash = Math.abs((seed * 1_103_515_245 + 12_345) % 2_147_483_647) % 100;
+    return `${SKELETON_WIDTH_BASE + (hash % SKELETON_WIDTH_SPREAD)}%`;
+};
+/** Loading placeholder mirroring a menu row; text width is seeded deterministically to avoid hydration mismatch. */
+export const SidebarMenuSkeleton = ({ className, showIcon = false, index, ...props }) => {
+    // Use React's useId for stable seed when index not provided
+    const id = useId();
+    const width = useMemo(() => {
+        if (index !== undefined) {
+            return getSeededWidth(index);
+        }
+        // Hash the id string to get a numeric seed
+        let idSeed = 0;
+        for (const char of id) {
+            idSeed += char.codePointAt(0) ?? 0;
+        }
+        return getSeededWidth(idSeed);
+    }, [index, id]);
+    return (_jsxs(Flex, { align: "center", className: cn("h-8 rounded-md px-2", className), gap: "xs", "data-component": "sidebar-menu-skeleton", "data-sidebar": "menu-skeleton", "data-slot": "sidebar-menu-skeleton", ...props, children: [showIcon && (_jsx(Skeleton, { className: "size-4 rounded-md", "data-sidebar": "menu-skeleton-icon" })), _jsx(Skeleton, { className: "h-4 max-w-(--skeleton-width) flex-1", "data-sidebar": "menu-skeleton-text", style: cssVariables({ "--skeleton-width": width }) })] }));
+};

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

@@ -0,0 +1,39 @@
+import type { MenuItemProps } from "@instruments/materia-ui/components/menu-item";
+import type React from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { Tone } from "../../tokens/tone.js";
+type SidebarMenuSubProps = React.ComponentProps<"ul">;
+/** The `<ul>` container for a nested submenu under a menu item; hidden when the sidebar collapses to an icon rail. */
+export declare const SidebarMenuSub: ({ className, ...props }: SidebarMenuSubProps) => React.JSX.Element;
+type SidebarMenuSubScrollAreaProps = React.ComponentProps<"div"> & {
+    /** Add a bottom gradient fade hinting at scrollable overflow. @default false */
+    fade?: boolean;
+    /** Cap the height: unconstrained, or clamped to the shared dropdown max. @default "none" */
+    maxHeight?: "none" | "dropdown";
+};
+/**
+ * Scroll viewport for sidebar submenu content inside floating surfaces.
+ * Keeps menu list scrolling, scrollbar styling, and bottom fade treatment centralised.
+ */
+export declare const SidebarMenuSubScrollArea: ({ children, className, fade, maxHeight, ...props }: SidebarMenuSubScrollAreaProps) => React.JSX.Element;
+type SidebarMenuSubItemProps = React.ComponentProps<"li">;
+/** The `<li>` wrapper for a single submenu row. */
+export declare const SidebarMenuSubItem: ({ className, ...props }: SidebarMenuSubItemProps) => React.JSX.Element;
+type SidebarMenuSubButtonProps = Omit<MenuItemProps, "icon" | "dot"> & {
+    /** Dot indicator in the left column (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
+    dot?: boolean | Tone;
+    /** Icon to display in the left icon column */
+    icon?: IconComponent;
+    /** Additional className for the icon */
+    iconClassName?: string;
+};
+/**
+ * SidebarMenuSubButton UI component.
+ * Thin wrapper around MenuItem with sidebar-specific defaults.
+ * Always reserves space for an icon on the left to maintain alignment.
+ * Uses size-4 (16px) icon space to match parent SidebarMenuButton.
+ * Renders as a button by default. Use `render` with Link for navigation.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export declare const SidebarMenuSubButton: ({ size, variant, radius, className, dot, icon, iconClassName, active, children, ...props }: SidebarMenuSubButtonProps) => React.JSX.Element;
+export type { SidebarMenuSubButtonProps, SidebarMenuSubItemProps, SidebarMenuSubProps, };

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

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Center } from "@instruments/materia-ui/components/center";
+import { Dot } from "@instruments/materia-ui/components/dot";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { MenuItem } from "@instruments/materia-ui/components/menu-item";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { isString } from "../../utils/type-guards.js";
+/** The `<ul>` container for a nested submenu under a menu item; hidden when the sidebar collapses to an icon rail. */
+export const SidebarMenuSub = ({ className, ...props }) => (_jsx(Flex, { as: "ul", className: cn("min-w-0 py-0.5", "group-data-[collapsible=icon]:hidden", className), "data-component": "sidebar-menu-sub", "data-sidebar": "menu-sub", "data-slot": "sidebar-menu-sub", direction: "column", gap: "3xs", ...props }));
+/**
+ * Scroll viewport for sidebar submenu content inside floating surfaces.
+ * Keeps menu list scrolling, scrollbar styling, and bottom fade treatment centralised.
+ */
+export const SidebarMenuSubScrollArea = ({ children, className, fade = false, maxHeight = "none", ...props }) => (_jsxs("div", { className: cn("relative min-h-0", className), "data-component": "sidebar-menu-sub-scroll-area", "data-slot": "sidebar-menu-sub-scroll-area", ...props, children: [_jsx("div", { className: cn("scrollbar-menu overflow-x-hidden overflow-y-auto", maxHeight === "dropdown" && "max-h-menu-sidebar-list"), children: children }), fade ? (_jsx("div", { "aria-hidden": true, className: "to-popover pointer-events-none absolute inset-x-0 bottom-0 h-24 bg-linear-to-b from-transparent" })) : null] }));
+/** The `<li>` wrapper for a single submenu row. */
+export const SidebarMenuSubItem = ({ className, ...props }) => (_jsx("li", { className: cn("group/menu-sub-item relative", className), "data-component": "sidebar-menu-sub-item", "data-sidebar": "menu-sub-item", "data-slot": "sidebar-menu-sub-item", ...props }));
+/**
+ * SidebarMenuSubButton UI component.
+ * Thin wrapper around MenuItem with sidebar-specific defaults.
+ * Always reserves space for an icon on the left to maintain alignment.
+ * Uses size-4 (16px) icon space to match parent SidebarMenuButton.
+ * Renders as a button by default. Use `render` with Link for navigation.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export const SidebarMenuSubButton = ({ size = "xl", variant = "input", radius = "full", className, dot, icon, iconClassName, active, children, ...props }) => {
+    // Always reserve icon space (16px to match parent icon size)
+    // Priority: dot > icon
+    let iconContent = null;
+    if (dot !== false && dot !== undefined) {
+        iconContent = _jsx(Dot, { size: "sm", tone: isString(dot) ? dot : undefined });
+    }
+    else if (icon) {
+        iconContent = _jsx(Icon, { className: cn("size-4", iconClassName), icon: icon });
+    }
+    const iconPlaceholder = (_jsx(Center, { as: "span", className: "size-4 shrink-0", children: iconContent }));
+    // Wrap in a single span for MenuItem
+    const wrappedContent = (_jsxs(Flex, { align: "center", as: "span", className: "min-w-0 flex-1", gap: "xs", children: [iconPlaceholder, _jsx("span", { className: "min-w-0 flex-1 truncate", children: children })] }));
+    return (_jsx(MenuItem, { className: cn("group-data-[collapsible=icon]:hidden", className), "data-component": "sidebar-menu-sub-button", "data-sidebar": "menu-sub-button", "data-slot": "sidebar-menu-sub-button", ...(active === undefined ? {} : { active }), radius: radius, size: size, variant: variant, ...props, children: wrappedContent }));
+};

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

@@ -0,0 +1,11 @@
+import type React from "react";
+export { SidebarMenuAction, type SidebarMenuActionProps, } from "../sidebar/sidebar-menu-action.js";
+export { SidebarMenuBadge, type SidebarMenuBadgeProps, } from "../sidebar/sidebar-menu-badge.js";
+export { SidebarMenuButton, type SidebarMenuButtonProps, } from "../sidebar/sidebar-menu-button.js";
+export { SidebarMenuLabel, type SidebarMenuLabelProps, } from "../sidebar/sidebar-menu-label.js";
+export { SidebarMenuSkeleton, type SidebarMenuSkeletonProps, } from "../sidebar/sidebar-menu-skeleton.js";
+export { SidebarMenuSub, SidebarMenuSubButton, type SidebarMenuSubButtonProps, SidebarMenuSubItem, type SidebarMenuSubItemProps, type SidebarMenuSubProps, SidebarMenuSubScrollArea, } from "../sidebar/sidebar-menu-sub.js";
+/** The `<ul>` list container for sidebar menu items. */
+export declare const SidebarMenu: ({ className, ...props }: React.ComponentProps<"ul">) => React.JSX.Element;
+/** The `<li>` wrapper for a single menu row; establishes the hover/focus group for actions and badges. */
+export declare const SidebarMenuItem: ({ className, ...props }: React.ComponentProps<"li">) => React.JSX.Element;

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

@@ -0,0 +1,16 @@
+"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";
+export { SidebarMenuAction, } from "../sidebar/sidebar-menu-action.js";
+export { SidebarMenuBadge, } from "../sidebar/sidebar-menu-badge.js";
+// Re-export all sidebar menu components
+export { SidebarMenuButton, } from "../sidebar/sidebar-menu-button.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";
+// Base menu components
+/** The `<ul>` list container for sidebar menu items. */
+export const SidebarMenu = ({ className, ...props }) => (_jsx(Flex, { as: "ul", className: cn("w-full min-w-0", className), "data-component": "sidebar-menu", "data-sidebar": "menu", "data-slot": "sidebar-menu", direction: "column", gap: "2xs", ...props }));
+/** The `<li>` wrapper for a single menu row; establishes the hover/focus group for actions and badges. */
+export const SidebarMenuItem = ({ className, ...props }) => (_jsx("li", { className: cn("group/menu-item relative", className), "data-component": "sidebar-menu-item", "data-sidebar": "menu-item", "data-slot": "sidebar-menu-item", ...props }));

package/dist/compositions/sidebar/sidebar-motion-config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SIDEBAR_TRANSITION shared constant for Sidebar: the standard spring, for
+ * opening and closing.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export declare const SIDEBAR_TRANSITION: {
+    readonly type: "spring";
+    readonly visualDuration: 0.3;
+    readonly bounce: 0;
+};
+/**
+ * The magnetic drag-snap (collapse when dragged past the threshold, or expand
+ * when dragged back out). The drag throws the panel, so it earns the settle
+ * spring's small overshoot; ordinary open and close stay on
+ * {@link SIDEBAR_TRANSITION}.
+ */
+export declare const SIDEBAR_MAGNETIC_TRANSITION: {
+    readonly type: "spring";
+    readonly visualDuration: 0.35;
+    readonly bounce: 0.15;
+};

package/dist/compositions/sidebar/sidebar-motion-config.js

@@ -0,0 +1,14 @@
+import { springs } from "@instruments/materia-ui/tokens/motion";
+/**
+ * SIDEBAR_TRANSITION shared constant for Sidebar: the standard spring, for
+ * opening and closing.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ */
+export const SIDEBAR_TRANSITION = springs.standard;
+/**
+ * The magnetic drag-snap (collapse when dragged past the threshold, or expand
+ * when dragged back out). The drag throws the panel, so it earns the settle
+ * spring's small overshoot; ordinary open and close stay on
+ * {@link SIDEBAR_TRANSITION}.
+ */
+export const SIDEBAR_MAGNETIC_TRANSITION = springs.settle;

package/dist/compositions/sidebar/sidebar-panel-guard.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Dev-only guard for `SidebarPanel variant="gutter"`. A gutter reserves space
+ * for a docked overlay and therefore drops its children, so passing children is
+ * a mistake. The panel renders this client sub-part only when a gutter is given
+ * non-empty children; it warns once on mount (local dev browsers only) and
+ * renders nothing, keeping the main part server-compatible.
+ */
+export declare const SidebarPanelGuard: () => null;

package/dist/compositions/sidebar/sidebar-panel-guard.js

@@ -0,0 +1,16 @@
+"use client";
+import { useEffect } from "react";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Dev-only guard for `SidebarPanel variant="gutter"`. A gutter reserves space
+ * for a docked overlay and therefore drops its children, so passing children is
+ * a mistake. The panel renders this client sub-part only when a gutter is given
+ * non-empty children; it warns once on mount (local dev browsers only) and
+ * renders nothing, keeping the main part server-compatible.
+ */
+export const SidebarPanelGuard = () => {
+    useEffect(() => {
+        reportDevIssue('[SidebarPanel] `variant="gutter"` reserves space for a docked overlay and renders no children - the children you passed were dropped. Render panel content in a docked, `modal={false}` Sidepanel, or use `variant="inline"` to render in-flow.');
+    }, []);
+    return null;
+};

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

@@ -0,0 +1,55 @@
+import type * as React from "react";
+export type SidebarPanelProps = React.ComponentProps<"div"> & {
+    /**
+     * Which edge the panel docks to. Positioning comes from DOM order (place the
+     * panel before or after `SidebarInset` in the row); this only sets `data-side`
+     * for styling hooks. @default "right"
+     */
+    side?: "left" | "right";
+    /**
+     * `"inline"`: an in-flow, sticky column that renders its children. `"gutter"`:
+     * an empty, width-animated spacer that reserves room for a docked overlay
+     * (children are dropped and it is `aria-hidden`). @default "inline"
+     */
+    variant?: "inline" | "gutter";
+    /**
+     * `gutter` animates its width between 0 and the panel width (`lg:` 300ms
+     * ease-out); `inline` is hidden when closed. @default true
+     */
+    open?: boolean;
+    /**
+     * Panel width - sets `--sidebar-panel-width` (a number is treated as px).
+     * Falls back to `var(--sidepanel-footprint)` (464px) for `gutter` and `25rem`
+     * for `inline`.
+     */
+    width?: number | string;
+};
+/**
+ * A flex-item region beside `SidebarInset`, in two variants. `inline` is an in-flow
+ * sticky column that renders your content beside `SidebarInset`; `gutter` is an
+ * empty width-animated spacer that reserves room for a docked overlay (e.g. a
+ * `modal={false}` Sidepanel) - it drops its children and is `aria-hidden`, so the
+ * panel *is* the reservation with no app state crossing into the design system.
+ * Place it as a sibling of `SidebarInset` inside `SidebarProvider`; `SidebarInset`'s
+ * `flex-1 min-w-0` absorbs the remaining width. Styles itself off the provider's
+ * `data-height`, so it stays a server component.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ *
+ * @example
+ * // Inline sticky column (in-flow, renders children)
+ * <SidebarInset>…</SidebarInset>
+ * <SidebarPanel side="left" open={showFilters}>
+ *   <Filters />
+ * </SidebarPanel>
+ *
+ * @example
+ * // Gutter reserving space for a docked overlay (empty spacer)
+ * <SidebarInset>…</SidebarInset>
+ * <SidebarPanel variant="gutter" side="right" open={docked} />
+ *
+ * @bestPractice Pair a `gutter` with a docked, `modal={false}` Sidepanel driven by the same `open` state; keep `open` true through the Sidepanel's exit animation so the reservation holds until it leaves.
+ * @bestPractice A `gutter` reserves room from `lg`, where `SidepanelContent` turns from a full-bleed overlay into the floating card; keep any panel you dock into it on the same breakpoint.
+ * @bestPractice A `gutter` needs a row context: `SidebarProvider` lays out as a row, so a panel placed beside `SidebarInset` sits on its right.
+ * @bestPractice Render at most one panel per side; use `side` to keep left/right reservations independent.
+ */
+export declare const SidebarPanel: ({ side, variant, open, width, className, style, children, ...props }: SidebarPanelProps) => React.JSX.Element;

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

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cssVariables } from "../../utils/css-variables.js";
+import { hasChildNodes } from "../../utils/has-child-nodes.js";
+import { isNumber } from "../../utils/type-guards.js";
+import { SidebarPanelGuard } from "./sidebar-panel-guard.js";
+const toWidthVar = (width) => {
+    if (width === undefined) {
+        return undefined;
+    }
+    return isNumber(width) ? `${width}px` : width;
+};
+const gutterClasses = (open) => cn("lg:transition-width lg:duration-normal shrink-0 lg:ease-out", 
+// The reservation starts at lg, the same breakpoint at which
+// `SidepanelContent` becomes the floating 440px card. Below lg the docked
+// panel is a full-bleed overlay, so reserving a 464px column would only
+// crush the content (a tablet beside the sidebar has no room for both).
+open ? "w-0 lg:w-(--sidebar-panel-width,var(--sidepanel-footprint))" : "w-0");
+const inlineClasses = (open) => cn("w-(--sidebar-panel-width,25rem) shrink-0 self-start", "group-data-[height=auto]/sidebar-wrapper:top-header group-data-[height=auto]/sidebar-wrapper:max-h-below-header group-data-[height=auto]/sidebar-wrapper:sticky group-data-[height=auto]/sidebar-wrapper:z-10", 
+// A sticky header in an inset frame is shorter by the card's top and
+// bottom gap, so the column sticks flush beneath it rather than 16px low.
+"group-has-data-[variant=inset]/sidebar-wrapper:group-has-data-[position=sticky]/sidebar-wrapper:group-data-[height=auto]/sidebar-wrapper:top-(--sidebar-inset-header-height)", "group-data-[height=fill]/sidebar-wrapper:sticky group-data-[height=fill]/sidebar-wrapper:top-0 group-data-[height=fill]/sidebar-wrapper:min-h-0", !open && "hidden");
+/**
+ * A flex-item region beside `SidebarInset`, in two variants. `inline` is an in-flow
+ * sticky column that renders your content beside `SidebarInset`; `gutter` is an
+ * empty width-animated spacer that reserves room for a docked overlay (e.g. a
+ * `modal={false}` Sidepanel) - it drops its children and is `aria-hidden`, so the
+ * panel *is* the reservation with no app state crossing into the design system.
+ * Place it as a sibling of `SidebarInset` inside `SidebarProvider`; `SidebarInset`'s
+ * `flex-1 min-w-0` absorbs the remaining width. Styles itself off the provider's
+ * `data-height`, so it stays a server component.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ *
+ * @example
+ * // Inline sticky column (in-flow, renders children)
+ * <SidebarInset>…</SidebarInset>
+ * <SidebarPanel side="left" open={showFilters}>
+ *   <Filters />
+ * </SidebarPanel>
+ *
+ * @example
+ * // Gutter reserving space for a docked overlay (empty spacer)
+ * <SidebarInset>…</SidebarInset>
+ * <SidebarPanel variant="gutter" side="right" open={docked} />
+ *
+ * @bestPractice Pair a `gutter` with a docked, `modal={false}` Sidepanel driven by the same `open` state; keep `open` true through the Sidepanel's exit animation so the reservation holds until it leaves.
+ * @bestPractice A `gutter` reserves room from `lg`, where `SidepanelContent` turns from a full-bleed overlay into the floating card; keep any panel you dock into it on the same breakpoint.
+ * @bestPractice A `gutter` needs a row context: `SidebarProvider` lays out as a row, so a panel placed beside `SidebarInset` sits on its right.
+ * @bestPractice Render at most one panel per side; use `side` to keep left/right reservations independent.
+ */
+export const SidebarPanel = ({ side = "right", variant = "inline", open = true, width, className, style, children, ...props }) => {
+    const isGutter = variant === "gutter";
+    const widthVar = toWidthVar(width);
+    const mergedStyle = widthVar === undefined
+        ? style
+        : cssVariables({ "--sidebar-panel-width": widthVar }, style);
+    const warnDroppedChildren = isGutter && hasChildNodes(children);
+    return (_jsxs("div", { "aria-hidden": isGutter ? true : undefined, className: cn(isGutter ? gutterClasses(open) : inlineClasses(open), className), "data-component": "sidebar-panel", "data-side": side, "data-slot": "sidebar-panel", "data-state": open ? "open" : "closed", "data-variant": variant, style: mergedStyle, ...props, children: [isGutter ? null : children, warnDroppedChildren ? _jsx(SidebarPanelGuard, {}) : null] }));
+};

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

@@ -0,0 +1,70 @@
+import type React from "react";
+import type { SidebarResizeContextProps } from "../sidebar/use-sidebar-resize-state.js";
+interface SidebarContextProps {
+    /** Whether the sidebar has completed initial hydration (for animation control) */
+    hasHydrated: boolean;
+    /** Is mobile */
+    isMobile: boolean;
+    /** Whether open */
+    open: boolean;
+    /** Whether open */
+    openMobile: boolean;
+    /** Set open */
+    setOpen: (open: boolean) => void;
+    /** Set open mobile */
+    setOpenMobile: (open: boolean) => void;
+    state: "expanded" | "collapsed";
+    /** Toggle sidebar */
+    toggleSidebar: () => void;
+}
+/**
+ * Reads the sidebar's open/collapsed state and controls (`toggleSidebar`,
+ * `setOpen`, mobile variants) from context. Throws if used outside a
+ * {@link SidebarProvider}.
+ */
+export declare const useSidebar: () => SidebarContextProps;
+/**
+ * Reads the sidebar's live resize state (`width`, `stretchWidth`, `isResizing`,
+ * the magnetic-snap flag, and their setters) from a context separate from
+ * {@link useSidebar}. Kept apart so per-frame width updates during a drag only
+ * re-render subscribers of this hook - not every {@link useSidebar} consumer.
+ * Throws if used outside a {@link SidebarProvider}.
+ */
+export declare const useSidebarResize: () => SidebarResizeContextProps;
+type SidebarProviderProps = React.ComponentProps<"div"> & {
+    /** Initial open state when uncontrolled. @default true */
+    defaultOpen?: boolean;
+    /**
+     * Initial expanded width in px, typically read from the width cookie
+     * server-side so the resized width is applied before paint (no flash).
+     * @default 256
+     */
+    defaultWidth?: number;
+    /**
+     * Scroll model. `"auto"` grows with the page (`min-h-svh`, like shadcn);
+     * `"fill"` pins the frame to the viewport and `SidebarInset` scrolls
+     * internally. @default "auto"
+     */
+    height?: "auto" | "fill";
+    /**
+     * Render the skip-to-content link first, targeting `SidebarInset`. Set `false`
+     * when the app root already renders one `SidebarSkipLink`. @default true
+     */
+    skipLink?: boolean;
+    /** Skip-link text. @default "Skip to content" */
+    skipLinkLabel?: string;
+    /** Controlled open state - pair with `onOpenChange`. */
+    open?: boolean;
+    /** Called with the next open state on toggle; required for controlled use. */
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * Root context provider owning the sidebar's open/collapsed state. Required
+ * ancestor for every sidebar part and {@link useSidebar}.
+ *
+ * Uncontrolled by default (`defaultOpen`, persisted to a cookie); pass
+ * `open` + `onOpenChange` to control it. Registers a Cmd/Ctrl+B toggle
+ * shortcut and wraps children in a `TooltipProvider`.
+ */
+export declare const SidebarProvider: ({ defaultOpen, defaultWidth, height, skipLink, skipLinkLabel, open: openProp, onOpenChange: setOpenProp, className, style, children, ...props }: SidebarProviderProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,120 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { TooltipProvider } from "@instruments/materia-ui/components/tooltip";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { createContext, use, useCallback, useEffect, useMemo, useState, useSyncExternalStore, } from "react";
+import { useMediaQuery } from "usehooks-ts";
+import { cssVariables } from "../../utils/css-variables.js";
+import { HEADER_HEIGHT, SIDEBAR_INSET_GAP, SIDEBAR_KEYBOARD_SHORTCUT, SIDEBAR_MOBILE_BREAKPOINT_PX, SIDEBAR_WIDTH_DEFAULT_PX, SIDEBAR_WIDTH_ICON, } from "../sidebar/sidebar-constants.js";
+import { SidebarSkipLink } from "../sidebar/sidebar-skip-link.js";
+import { useSidebarOpenState } from "../sidebar/use-sidebar-open-state.js";
+import { useSidebarResizeState } from "../sidebar/use-sidebar-resize-state.js";
+const SidebarContext = createContext(null);
+const SidebarResizeContext = createContext(null);
+const subscribeToHydration = () => () => {
+    // Hydration status never changes after mount; no subscription needed.
+};
+/**
+ * Reads the sidebar's open/collapsed state and controls (`toggleSidebar`,
+ * `setOpen`, mobile variants) from context. Throws if used outside a
+ * {@link SidebarProvider}.
+ */
+export const useSidebar = () => {
+    const context = use(SidebarContext);
+    if (!context) {
+        throw new Error("useSidebar must be used within a SidebarProvider.");
+    }
+    return context;
+};
+/**
+ * Reads the sidebar's live resize state (`width`, `stretchWidth`, `isResizing`,
+ * the magnetic-snap flag, and their setters) from a context separate from
+ * {@link useSidebar}. Kept apart so per-frame width updates during a drag only
+ * re-render subscribers of this hook - not every {@link useSidebar} consumer.
+ * Throws if used outside a {@link SidebarProvider}.
+ */
+export const useSidebarResize = () => {
+    const context = use(SidebarResizeContext);
+    if (!context) {
+        throw new Error("useSidebarResize must be used within a SidebarProvider.");
+    }
+    return context;
+};
+/**
+ * Root context provider owning the sidebar's open/collapsed state. Required
+ * ancestor for every sidebar part and {@link useSidebar}.
+ *
+ * Uncontrolled by default (`defaultOpen`, persisted to a cookie); pass
+ * `open` + `onOpenChange` to control it. Registers a Cmd/Ctrl+B toggle
+ * shortcut and wraps children in a `TooltipProvider`.
+ */
+export const SidebarProvider = ({ defaultOpen = true, defaultWidth = SIDEBAR_WIDTH_DEFAULT_PX, height = "auto", skipLink = true, skipLinkLabel, open: openProp, onOpenChange: setOpenProp, className, style, children, ...props }) => {
+    const isMobile = useMediaQuery(`(max-width: ${SIDEBAR_MOBILE_BREAKPOINT_PX - 1}px)`, {
+        defaultValue: false,
+        initializeWithValue: false,
+    });
+    const [openMobile, setOpenMobile] = useState(false);
+    const resizeValue = useSidebarResizeState(defaultWidth);
+    // Mark as hydrated after initial mount to control animations.
+    // useSyncExternalStore returns the server snapshot (false) during SSR and the
+    // initial hydration render, then the client snapshot (true) afterwards.
+    const hasHydrated = useSyncExternalStore(subscribeToHydration, () => true, () => false);
+    // This is the internal state of the sidebar.
+    // We use openProp and setOpenProp for control from outside the component.
+    const { open, setOpen } = useSidebarOpenState({
+        defaultOpen,
+        onOpenChange: setOpenProp,
+        open: openProp,
+    });
+    // Helper to toggle the sidebar.
+    const toggleSidebar = useCallback(() => {
+        if (isMobile) {
+            setOpenMobile((prev) => !prev);
+        }
+        else {
+            setOpen((prev) => !prev);
+        }
+    }, [isMobile, setOpen]);
+    // Adds a keyboard shortcut to toggle the sidebar.
+    useEffect(() => {
+        // Make header height available to portaled UI (sidepanel, dialogs, etc.).
+        document.documentElement.style.setProperty("--header-height", HEADER_HEIGHT);
+        const handleKeyDown = (event) => {
+            if (event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+                (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                toggleSidebar();
+            }
+        };
+        window.addEventListener("keydown", handleKeyDown);
+        return () => {
+            window.removeEventListener("keydown", handleKeyDown);
+        };
+    }, [toggleSidebar]);
+    // We add a state so that we can do data-state="expanded" or "collapsed".
+    // This makes it easier to style the sidebar with Tailwind classes.
+    const state = open ? "expanded" : "collapsed";
+    // Stable context: identity only changes on genuine open/collapse or viewport
+    // changes - NOT during a resize drag - so menu buttons, triggers, and groups
+    // never re-render while the width is being dragged.
+    const contextValue = useMemo(() => ({
+        hasHydrated,
+        isMobile,
+        open,
+        openMobile,
+        setOpen,
+        setOpenMobile,
+        state,
+        toggleSidebar,
+    }), [state, open, setOpen, isMobile, openMobile, toggleSidebar, hasHydrated]);
+    return (_jsx(SidebarContext.Provider, { value: contextValue, children: _jsx(SidebarResizeContext.Provider, { value: resizeValue, children: _jsx(TooltipProvider, { delay: 0, children: _jsxs(Flex, { className: cn("group/sidebar-wrapper has-data-[variant=inset]:bg-muted min-h-svh w-full overflow-visible", height === "fill" && "h-svh max-h-svh overflow-hidden", className), "data-component": "sidebar-wrapper", "data-height": height, "data-slot": "sidebar-wrapper", style: cssVariables({
+                        "--header-height": HEADER_HEIGHT,
+                        "--sidebar-inset-gap": SIDEBAR_INSET_GAP,
+                        "--sidebar-inset-header-height": "calc(var(--header-height) - 2 * var(--sidebar-inset-gap))",
+                        "--sidebar-width": `${resizeValue.width}px`,
+                        "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+                    }, style), ...props, children: [skipLink ? (_jsx(SidebarSkipLink, { ...(skipLinkLabel === undefined
+                                ? {}
+                                : { label: skipLinkLabel }) })) : null, children] }) }) }) }));
+};

package/dist/compositions/sidebar/sidebar-resize-handle.d.ts

@@ -0,0 +1,24 @@
+import type React from "react";
+/**
+ * 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 declare const SidebarResizeHandle: ({ side }: {
+    side: "left" | "right";
+}) => React.JSX.Element;