@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,24 @@
+import { SIDEBAR_COOKIE_MAX_AGE } from "../sidebar/sidebar-constants.js";
+/**
+ * Persist a sidebar cookie through the Cookie Store API. Where the API is
+ * absent the state simply isn't persisted; pass `defaultOpen` from the server
+ * for full control.
+ */
+export const persistSidebarCookie = (name, value) => {
+    if ("cookieStore" in window) {
+        void (async () => {
+            try {
+                await window.cookieStore.set({
+                    expires: Date.now() + SIDEBAR_COOKIE_MAX_AGE * 1000,
+                    name,
+                    path: "/",
+                    sameSite: "lax",
+                    value,
+                });
+            }
+            catch {
+                // Best-effort; the live state is authoritative for this session.
+            }
+        })();
+    }
+};

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

@@ -0,0 +1,6 @@
+import * as m from "motion/react-m";
+import type React from "react";
+type SidebarFooterProps = Omit<React.ComponentProps<typeof m.div>, "onDrag">;
+/** Footer region pinned to the bottom of the sidebar (e.g. account menu); reads collapsed state from {@link useSidebar}. */
+export declare const SidebarFooter: ({ className, ...props }: SidebarFooterProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { SIDEBAR_TRANSITION } from "../sidebar/sidebar-motion-config.js";
+import { useSidebar } from "../sidebar/sidebar-provider.js";
+/** Footer region pinned to the bottom of the sidebar (e.g. account menu); reads collapsed state from {@link useSidebar}. */
+export const SidebarFooter = ({ className, ...props }) => {
+    const { state } = useSidebar();
+    const isCollapsed = state === "collapsed";
+    return (_jsx(m.div, { animate: {
+            x: isCollapsed ? -0 : 0,
+        }, className: cn("flex group-data-[collapsible=icon]:px-1", className), "data-component": "sidebar-footer", "data-sidebar": "footer", "data-slot": "sidebar-footer", initial: false, transition: SIDEBAR_TRANSITION, ...props }));
+};

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

@@ -0,0 +1,14 @@
+import { useRender } from "@base-ui/react/use-render";
+import type React from "react";
+import { Button } from "../../components/button.js";
+/** A titled section of the sidebar grouping a label, optional action, and menu content. */
+export declare const SidebarGroup: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;
+/** Heading for a {@link SidebarGroup}; fades out (keeping layout) when collapsed to an icon rail. Pass `render` to use a custom element. */
+export declare const SidebarGroupLabel: ({ className, render, ...props }: useRender.ComponentProps<"div">) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+/** Icon button pinned to a group's top-right corner (defaults to a `+`); hidden when collapsed unless `showWhenCollapsed`. */
+export declare const SidebarGroupAction: ({ className, icon, size, radius, emphasis, showWhenCollapsed, ...props }: React.ComponentProps<typeof Button> & {
+    /** Show the action button even when sidebar is collapsed */
+    showWhenCollapsed?: boolean;
+}) => React.JSX.Element;
+/** Content wrapper inside a {@link SidebarGroup}, typically holding a {@link SidebarMenu}. */
+export declare const SidebarGroupContent: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

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

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Plus } from "lucide-react";
+import { Button } from "../../components/button.js";
+/** A titled section of the sidebar grouping a label, optional action, and menu content. */
+export const SidebarGroup = ({ className, ...props }) => (_jsx(Flex, { className: cn("relative w-full min-w-0 px-3 py-4", className), "data-component": "sidebar-group", "data-sidebar": "group", "data-slot": "sidebar-group", direction: "column", ...props }));
+/** Heading for a {@link SidebarGroup}; fades out (keeping layout) when collapsed to an icon rail. Pass `render` to use a custom element. */
+export const SidebarGroupLabel = ({ className, render, ...props }) => {
+    const baseProps = {
+        className: cn("text-sidebar-foreground/70 ring-sidebar-ring duration-normal text-caption flex shrink-0 items-center rounded-md py-2 pr-2 pl-3 font-medium outline-hidden transition-opacity ease-out focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0", 
+        // Fade out when collapsed, keep layout
+        "group-data-[collapsible=icon]:pointer-events-none group-data-[collapsible=icon]:opacity-0", className),
+        "data-component": "sidebar-group-label",
+        "data-sidebar": "group-label",
+        "data-slot": "sidebar-group-label",
+    };
+    return useRender({
+        defaultTagName: "div",
+        props: mergeProps(baseProps, props),
+        render,
+    });
+};
+/** Icon button pinned to a group's top-right corner (defaults to a `+`); hidden when collapsed unless `showWhenCollapsed`. */
+export const SidebarGroupAction = ({ className, icon = Plus, size = "icon-sm", radius = "full", emphasis = "ghost", showWhenCollapsed = false, ...props }) => (_jsx(Button, { emphasis: emphasis, className: cn("text-sidebar-foreground ring-sidebar-ring hover:text-sidebar-accent-foreground duration-normal absolute top-3.5 right-4 transition-colors hover:bg-white", 
+    // Increases the hit area of the button on mobile.
+    "after:absolute after:-inset-2 md:after:hidden", 
+    // When collapsed: center the button if showing, otherwise hide
+    showWhenCollapsed
+        ? "group-data-[collapsible=icon]:right-1/2 group-data-[collapsible=icon]:translate-x-[55%]"
+        : "group-data-[collapsible=icon]:hidden", className), "data-component": "sidebar-group-action", "data-sidebar": "group-action", "data-slot": "sidebar-group-action", icon: icon, radius: radius, size: size, ...props }));
+/** Content wrapper inside a {@link SidebarGroup}, typically holding a {@link SidebarMenu}. */
+export const SidebarGroupContent = ({ className, ...props }) => (_jsx("div", { className: cn("text-paragraph-sm w-full", className), "data-component": "sidebar-group-content", "data-sidebar": "group-content", "data-slot": "sidebar-group-content", ...props }));

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

@@ -0,0 +1,3 @@
+import type React from "react";
+/** Sidebar header section - a simple container with consistent height */
+export declare const SidebarHeader: ({ className, children, ...props }: React.ComponentProps<"div">) => React.JSX.Element;

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

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Sidebar header section - a simple container with consistent height */
+export const SidebarHeader = ({ className, children, ...props }) => (_jsx(Flex, { align: "center", className: cn("h-header relative px-4 group-data-[collapsible=icon]:px-1", className), "data-component": "sidebar-header", "data-sidebar": "header", "data-slot": "sidebar-header", ...props, children: children }));

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

@@ -0,0 +1,4 @@
+import { Input } from "@instruments/materia-ui/components/input";
+import type React from "react";
+/** An {@link Input} styled for placement inside the sidebar (full width, flat background). */
+export declare const SidebarInput: ({ className, ...props }: React.ComponentProps<typeof Input>) => React.JSX.Element;

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

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Input } from "@instruments/materia-ui/components/input";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** An {@link Input} styled for placement inside the sidebar (full width, flat background). */
+export const SidebarInput = ({ className, ...props }) => (_jsx(Input, { className: cn("bg-background w-full shadow-none", className), "data-component": "sidebar-input", "data-sidebar": "input", "data-slot": "sidebar-input", ...props }));

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

@@ -0,0 +1,7 @@
+/**
+ * Landmark guard: warns when more than one `<main>` exists on the page.
+ * Compound-children frames can't enforce a single `<main>` at the type
+ * level, so this catches the mistake at runtime (it only reports when the invariant
+ * is actually violated). Renders nothing.
+ */
+export declare const SidebarInsetGuard: () => null;

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

@@ -0,0 +1,18 @@
+"use client";
+import { useEffect } from "react";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Landmark guard: warns when more than one `<main>` exists on the page.
+ * Compound-children frames can't enforce a single `<main>` at the type
+ * level, so this catches the mistake at runtime (it only reports when the invariant
+ * is actually violated). Renders nothing.
+ */
+export const SidebarInsetGuard = () => {
+    useEffect(() => {
+        const count = document.querySelectorAll("main").length;
+        if (count > 1) {
+            reportDevIssue(`[SidebarInset] Found ${count} <main> landmarks on the page - there should be exactly one. Nested or sibling <main> elements break landmark navigation. Render exactly one SidebarInset per page.`);
+        }
+    }, []);
+    return null;
+};

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

@@ -0,0 +1,38 @@
+import { useRender } from "@base-ui/react/use-render";
+type SidebarInsetProps = useRender.ComponentProps<"main"> & {
+    /**
+     * Pad under fixed chrome in `height="auto"` frames. `"header"` clears the
+     * fixed `SidebarLayoutHeader` (and the mobile app bar below md); `"app-bar"`
+     * clears only the mobile app bar, for frames whose desktop header is a
+     * sticky `SidebarLayoutHeader` inside the inset.
+     * @default "none"
+     */
+    offset?: "header" | "app-bar" | "none";
+    /**
+     * Apply the shared horizontal page gutter (`--page-gutter`). Opt-in so apps
+     * that own their own gutter are unaffected.
+     * @default false
+     */
+    gutter?: boolean;
+};
+/**
+ * The content column beside the sidebar, and the page's single `<main>`
+ * landmark: it carries the skip-link target id and is focusable so the link can
+ * move focus here. Put your page `<header>` and content inside it, as in
+ * shadcn's sidebar blocks. In a `height="fill"` provider it scrolls internally
+ * (make the header `sticky top-0`).
+ *
+ * `min-w-0` (not `w-full`) is essential: without it flex's default
+ * `min-width: auto` stops the column shrinking below its content, so a wide
+ * child pushes the page past the sidebar and creates horizontal overflow.
+ * With `variant="inset"` the column becomes a rounded card.
+ *
+ * Pass `render={<div />}` (and your own `id`) when the page already owns its
+ * `<main>`, as in an embedded demo. A dev warning fires when more than one
+ * `<main>` is on the page.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ *
+ * @bestPractice Render exactly one `SidebarInset` per page; for a second content region use a plain `<div>`.
+ */
+export declare const SidebarInset: ({ className, offset, gutter, children, render, ...props }: SidebarInsetProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

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

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CONTENT_COLUMN_CLASS, SIDEBAR_INSET_ID } from "./sidebar-constants.js";
+import { SidebarInsetGuard } from "./sidebar-inset-guard.js";
+/**
+ * The content column beside the sidebar, and the page's single `<main>`
+ * landmark: it carries the skip-link target id and is focusable so the link can
+ * move focus here. Put your page `<header>` and content inside it, as in
+ * shadcn's sidebar blocks. In a `height="fill"` provider it scrolls internally
+ * (make the header `sticky top-0`).
+ *
+ * `min-w-0` (not `w-full`) is essential: without it flex's default
+ * `min-width: auto` stops the column shrinking below its content, so a wide
+ * child pushes the page past the sidebar and creates horizontal overflow.
+ * With `variant="inset"` the column becomes a rounded card.
+ *
+ * Pass `render={<div />}` (and your own `id`) when the page already owns its
+ * `<main>`, as in an embedded demo. A dev warning fires when more than one
+ * `<main>` is on the page.
+ * Import from "@instruments/materia-ui/compositions/sidebar".
+ *
+ * @bestPractice Render exactly one `SidebarInset` per page; for a second content region use a plain `<div>`.
+ */
+export const SidebarInset = ({ className, offset = "none", gutter = false, children, render, ...props }) => {
+    const baseProps = {
+        children: (_jsxs(_Fragment, { children: [children, _jsx(SidebarInsetGuard, {})] })),
+        className: cn(CONTENT_COLUMN_CLASS, ...focusRing(), "focus-visible:ring-inset", offset === "header" &&
+            // Clears the fixed header: header height plus the top safe-area inset on
+            // mobile, header height from md up (env resolves to 0 without a notch).
+            "md:group-data-[height=auto]/sidebar-wrapper:pt-header group-data-[height=auto]/sidebar-wrapper:pt-safe-18", offset === "app-bar" &&
+            // Clears the mobile app bar only; from md up the sticky desktop header
+            // sits in flow inside the inset, so there is nothing to pad under.
+            "group-data-[height=auto]/sidebar-wrapper:pt-safe-18 md:group-data-[height=auto]/sidebar-wrapper:pt-0", gutter && "px-page-gutter", "group-data-[height=fill]/sidebar-wrapper:min-h-0 group-data-[height=fill]/sidebar-wrapper:overflow-y-auto", 
+        // `variant="inset"` sidebars float the content as a rounded card.
+        // The gap is the provider's `--sidebar-inset-gap`, which the sticky
+        // header also reads to line its row up with the sidebar header.
+        "md:peer-data-[variant=inset]:bg-background md:peer-data-[variant=inset]:m-(--sidebar-inset-gap) md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-(--sidebar-inset-gap)", className),
+        "data-component": "sidebar-inset",
+        "data-slot": "sidebar-inset",
+        id: SIDEBAR_INSET_ID,
+        tabIndex: -1,
+    };
+    return useRender({
+        defaultTagName: "main",
+        props: mergeProps(baseProps, props),
+        render,
+    });
+};

package/dist/compositions/sidebar/sidebar-layout-header.d.ts

@@ -0,0 +1,54 @@
+import * as m from "motion/react-m";
+import type React from "react";
+type SidebarLayoutHeaderProps = Omit<React.ComponentProps<typeof m.div>, "onDrag"> & {
+    /**
+     * `"fixed"` pins the bar to the viewport and animates its left edge to track
+     * the sidebar. `"sticky"` renders it in flow as the first child of
+     * `SidebarInset`: it inherits the column's width, so it follows the sidebar
+     * and any `SidebarPanel` gutter by layout alone, and works the same in
+     * `height="auto"` and `height="fill"` frames. @default "fixed"
+     */
+    position?: "fixed" | "sticky";
+    /**
+     * Apply the shared page gutter (`--page-gutter`) on both sides, so the bar's
+     * contents line up with a `PageHeader` and page content below it.
+     * @default false
+     */
+    gutter?: boolean;
+    /** Right padding when sidepanel or other overlay is open (`fixed` only). */
+    rightOffset?: string;
+};
+/**
+ * The desktop (md+) top header beside the sidebar. Fixed by default, its left
+ * offset animating to track the sidebar's width; pass `position="sticky"` to
+ * put it in flow inside `SidebarInset`, where it shares the content column's
+ * gutter and edges with no measurement. Compose `SidebarLayoutHeaderSearch`
+ * and `SidebarLayoutHeaderActions` inside it.
+ *
+ * @example
+ * <SidebarInset>
+ *   <SidebarLayoutHeader gutter position="sticky">
+ *     <SidebarLayoutHeaderSearch><SearchInput /></SidebarLayoutHeaderSearch>
+ *     <SidebarLayoutHeaderActions><Button icon={ShoppingBag} /></SidebarLayoutHeaderActions>
+ *   </SidebarLayoutHeader>
+ *   <PageHeader>…</PageHeader>
+ * </SidebarInset>
+ *
+ * @bestPractice Prefer `position="sticky"` with `gutter` inside `SidebarInset`: search, page heading and content then share one left edge, and a docked `SidebarPanel` gutter pushes the header's actions clear of the panel without any offset plumbing.
+ * @bestPractice In a `variant="inset"` sidebar frame the sticky bar takes `--sidebar-inset-header-height` (the header height less the card's top and bottom gap), so search and the sidebar's brand row share a centre line; don't re-pad it to match.
+ * @bestPractice Pair a sticky header with `SidebarInset offset="app-bar"` so only the mobile app bar is cleared; `offset="header"` is for the fixed header.
+ */
+export declare const SidebarLayoutHeader: ({ className, gutter, position, rightOffset, ...props }: SidebarLayoutHeaderProps) => React.JSX.Element;
+/**
+ * The growing search slot of a `SidebarLayoutHeader`: takes the room left by
+ * the actions, capped at a readable measure so a wide screen doesn't stretch
+ * the field edge to edge.
+ */
+export declare const SidebarLayoutHeaderSearch: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;
+/**
+ * The trailing action cluster of a `SidebarLayoutHeader` (cart, account,
+ * notifications). Pinned to the bar's end edge, so it sits on the content
+ * column's right gutter.
+ */
+export declare const SidebarLayoutHeaderActions: ({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element;
+export {};

package/dist/compositions/sidebar/sidebar-layout-header.js

@@ -0,0 +1,94 @@
+"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";
+import * as m from "motion/react-m";
+import { SIDEBAR_WIDTH_ICON } 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";
+/**
+ * The desktop (md+) top header beside the sidebar. Fixed by default, its left
+ * offset animating to track the sidebar's width; pass `position="sticky"` to
+ * put it in flow inside `SidebarInset`, where it shares the content column's
+ * gutter and edges with no measurement. Compose `SidebarLayoutHeaderSearch`
+ * and `SidebarLayoutHeaderActions` inside it.
+ *
+ * @example
+ * <SidebarInset>
+ *   <SidebarLayoutHeader gutter position="sticky">
+ *     <SidebarLayoutHeaderSearch><SearchInput /></SidebarLayoutHeaderSearch>
+ *     <SidebarLayoutHeaderActions><Button icon={ShoppingBag} /></SidebarLayoutHeaderActions>
+ *   </SidebarLayoutHeader>
+ *   <PageHeader>…</PageHeader>
+ * </SidebarInset>
+ *
+ * @bestPractice Prefer `position="sticky"` with `gutter` inside `SidebarInset`: search, page heading and content then share one left edge, and a docked `SidebarPanel` gutter pushes the header's actions clear of the panel without any offset plumbing.
+ * @bestPractice In a `variant="inset"` sidebar frame the sticky bar takes `--sidebar-inset-header-height` (the header height less the card's top and bottom gap), so search and the sidebar's brand row share a centre line; don't re-pad it to match.
+ * @bestPractice Pair a sticky header with `SidebarInset offset="app-bar"` so only the mobile app bar is cleared; `offset="header"` is for the fixed header.
+ */
+export const SidebarLayoutHeader = ({ className, gutter = false, position = "fixed", rightOffset = "0px", ...props }) => {
+    const { state, hasHydrated, isMobile } = useSidebar();
+    const { width, isResizing, isMagneticSnap, stretchWidth } = useSidebarResize();
+    if (position === "sticky") {
+        return (_jsx(m.div, { className: cn("h-header bg-background sticky top-0 z-40 hidden shrink-0 items-center gap-3 md:flex", 
+            // Inside an inset frame's content card, which starts one
+            // `--sidebar-inset-gap` down the canvas, the bar loses that gap top
+            // and bottom so its row centres level with the sidebar header.
+            "group-has-data-[variant=inset]/sidebar-wrapper:h-(--sidebar-inset-header-height)", gutter && "px-page-gutter", className), "data-component": "sidebar-layout-header", "data-position": "sticky", "data-slot": "sidebar-layout-header", ...props }));
+    }
+    // Track the sidebar's motion exactly: instant while dragging, the magnetic
+    // bounce on a drag-snap, the calm spring otherwise (none before hydration).
+    let transition = {
+        duration: 0,
+    };
+    if (isResizing) {
+        transition = { duration: 0 };
+    }
+    else if (isMagneticSnap) {
+        transition = SIDEBAR_MAGNETIC_TRANSITION;
+    }
+    else if (hasHydrated) {
+        transition = SIDEBAR_TRANSITION;
+    }
+    const getLeftOffset = () => {
+        if (isMobile) {
+            return "0px";
+        }
+        // Rubber-band width while dragging the resize handle.
+        if (stretchWidth !== null) {
+            return `${stretchWidth}px`;
+        }
+        if (state === "collapsed") {
+            return SIDEBAR_WIDTH_ICON;
+        }
+        return `${width}px`;
+    };
+    const leftOffset = getLeftOffset();
+    // With `gutter` the bar's right edge lines up with the page content below
+    // it: the page gutter, plus any reserved `rightOffset` (a docked panel).
+    // Without it, 2rem when nothing is reserved, else the offset itself.
+    let paddingRight = rightOffset === "0px" ? "2rem" : rightOffset;
+    if (gutter) {
+        paddingRight =
+            rightOffset === "0px"
+                ? "var(--page-gutter)"
+                : `calc(${rightOffset} + var(--page-gutter))`;
+    }
+    return (_jsx(m.div
+    // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the width change has to push the page content, which a transform cannot do
+    , { 
+        // oxlint-disable-next-line react-doctor/no-layout-property-animation -- the width change has to push the page content, which a transform cannot do
+        animate: { left: leftOffset, paddingRight }, className: cn("h-header fixed top-0 right-0 z-40 hidden items-center pl-8 md:flex", gutter && "pl-page-gutter", className), "data-component": "sidebar-layout-header", "data-position": "fixed", "data-slot": "sidebar-layout-header", initial: false, transition: transition, ...props }));
+};
+/**
+ * The growing search slot of a `SidebarLayoutHeader`: takes the room left by
+ * the actions, capped at a readable measure so a wide screen doesn't stretch
+ * the field edge to edge.
+ */
+export const SidebarLayoutHeaderSearch = ({ className, ...props }) => (_jsx("div", { className: cn("max-w-2xl min-w-0 flex-1", className), "data-component": "sidebar-layout-header-search", "data-slot": "sidebar-layout-header-search", ...props }));
+/**
+ * The trailing action cluster of a `SidebarLayoutHeader` (cart, account,
+ * notifications). Pinned to the bar's end edge, so it sits on the content
+ * column's right gutter.
+ */
+export const SidebarLayoutHeaderActions = ({ className, ...props }) => (_jsx(Flex, { align: "center", className: cn("ml-auto shrink-0", className), "data-component": "sidebar-layout-header-actions", "data-slot": "sidebar-layout-header-actions", gap: "xs", ...props }));

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

@@ -0,0 +1,8 @@
+import { useRender } from "@base-ui/react/use-render";
+type SidebarMenuActionProps = useRender.ComponentProps<"button"> & {
+    /** Reveal only on row hover/focus (or when open) instead of always. @default false */
+    showOnHover?: boolean;
+};
+/** Action button (e.g. "more" menu) absolutely positioned at a menu item's trailing edge; hidden when collapsed to an icon rail. */
+export declare const SidebarMenuAction: ({ className, render, showOnHover, ...props }: SidebarMenuActionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type { SidebarMenuActionProps };

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

@@ -0,0 +1,21 @@
+"use client";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Action button (e.g. "more" menu) absolutely positioned at a menu item's trailing edge; hidden when collapsed to an icon rail. */
+export const SidebarMenuAction = ({ className, render, showOnHover = false, ...props }) => {
+    const baseProps = {
+        className: cn("text-muted-foreground ring-ring peer-hover/menu-button:text-accent-foreground hover:bg-accent hover:text-accent-foreground absolute top-1/2 right-2.5 flex aspect-square w-5 -translate-y-1/2 items-center justify-center rounded-md p-0 outline-hidden transition-transform focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0", 
+        // Increases the hit area of the button on mobile.
+        "after:absolute after:-inset-2 md:after:hidden", "group-data-[collapsible=icon]:hidden", showOnHover &&
+            "peer-data-[active=true]/menu-button:text-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-popup-open:opacity-100 md:opacity-0", className),
+        "data-component": "sidebar-menu-action",
+        "data-sidebar": "menu-action",
+        "data-slot": "sidebar-menu-action",
+    };
+    return useRender({
+        defaultTagName: "button",
+        props: mergeProps(baseProps, props),
+        render,
+    });
+};

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

@@ -0,0 +1,5 @@
+import type React from "react";
+type SidebarMenuBadgeProps = React.ComponentProps<"div">;
+/** Non-interactive count/status badge pinned to a menu item's trailing edge; fades out when collapsed to an icon rail. */
+export declare const SidebarMenuBadge: ({ className, ...props }: SidebarMenuBadgeProps) => React.JSX.Element;
+export type { SidebarMenuBadgeProps };

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

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Center } from "@instruments/materia-ui/components/center";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Non-interactive count/status badge pinned to a menu item's trailing edge; fades out when collapsed to an icon rail. */
+export const SidebarMenuBadge = ({ className, ...props }) => (_jsx(Center, { className: cn("text-muted-foreground text-caption pointer-events-none absolute top-1/2 right-2.5 h-5 min-w-5 -translate-y-1/2 rounded-md px-1 font-medium tabular-nums select-none", "peer-hover/menu-button:text-accent-foreground peer-data-[active=true]/menu-button:text-accent-foreground", "duration-normal transition-opacity ease-out group-data-[collapsible=icon]:opacity-0", className), "data-component": "sidebar-menu-badge", "data-sidebar": "menu-badge", "data-slot": "sidebar-menu-badge", ...props }));

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

@@ -0,0 +1,38 @@
+import { useRender } from "@base-ui/react/use-render";
+import { TooltipContent } from "@instruments/materia-ui/components/tooltip";
+import type React from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { ComponentSize } from "../../tokens/size.js";
+type SidebarMenuButtonProps = Omit<useRender.ComponentProps<"button">, "children"> & {
+    /** Marks the row as the current/selected item (sets `data-active`). */
+    active?: boolean;
+    /** Tooltip content shown only when the sidebar is collapsed; also becomes the collapsed `aria-label`. */
+    tooltip?: string | React.ComponentProps<typeof TooltipContent>;
+    /** Control tooltip visibility. Use `false` to hide tooltip (e.g., when a dropdown is open). */
+    tooltipOpen?: boolean;
+    size?: ComponentSize;
+    variant?: "default" | "input" | "outline";
+    icon?: IconComponent;
+    /** Icon to show when sidebar is collapsed (overrides icon) */
+    collapsedIcon?: IconComponent;
+    /** Custom content to show when sidebar is collapsed (e.g., Avatar). Takes precedence over collapsedIcon. */
+    collapsedContent?: React.ReactNode;
+    suffixIcon?: IconComponent;
+    /** Keep label/suffix visible even when the sidebar provider is collapsed. */
+    forceExpanded?: boolean;
+    kbd?: string[];
+    children?: React.ReactNode;
+};
+/**
+ * The primary interactive row of a sidebar menu - a leading icon plus label,
+ * optional suffix icon and keyboard-shortcut hint.
+ *
+ * Collapses to icon-only when the sidebar collapses (swapping in `collapsedIcon`
+ * /`collapsedContent` and revealing the `tooltip`), unless `forceExpanded`.
+ * Reads collapsed state from {@link useSidebar}; pass `render` to render a
+ * `<Link>` or other element as the button.
+ *
+ * @bestPractice In an icon-collapsible sidebar use `size="xl"`: the icon rail is sized for an `xl` row, so its collapsed square centres on the rail and the icon stays put as the sidebar folds.
+ */
+export declare const SidebarMenuButton: ({ render, active, variant, size, icon, collapsedIcon, collapsedContent, suffixIcon, forceExpanded, kbd, tooltip, tooltipOpen, className, children, style, ...props }: SidebarMenuButtonProps) => React.JSX.Element;
+export type { SidebarMenuButtonProps };

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

@@ -0,0 +1,135 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { Kbd, KbdGroup } from "@instruments/materia-ui/components/kbd";
+import { MENU_ITEM_ICON_SIZES, MENU_ITEM_KBD_SIZES, menuItemVariants, } from "@instruments/materia-ui/components/menu-item";
+import { Tooltip, TooltipContent, TooltipTrigger, } from "@instruments/materia-ui/components/tooltip";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { isString } from "../../utils/type-guards.js";
+import { SIDEBAR_TRANSITION } from "../sidebar/sidebar-motion-config.js";
+import { useSidebar } from "../sidebar/sidebar-provider.js";
+/**
+ * Button height in pixels per size. Collapsed to the icon rail, the button
+ * narrows to a square of this size.
+ */
+const COLLAPSED_HEIGHT_PX = {
+    "2xl": 48,
+    "2xs": 24,
+    "3xl": 56,
+    base: 36,
+    lg: 40,
+    sm: 32,
+    xl: 44,
+    xs: 28,
+};
+const getCollapsedAriaLabel = (isCollapsed, tooltip) => isCollapsed && isString(tooltip) && tooltip !== "" ? tooltip : undefined;
+/** Trailing keyboard-shortcut group, hidden when collapsed, when a suffix icon is shown, or when empty. */
+const SidebarMenuKbd = ({ isCollapsed, kbd, kbdSize, suffixIcon, }) => {
+    if (isCollapsed || suffixIcon || kbd === undefined || kbd.length === 0) {
+        return null;
+    }
+    return (_jsx(KbdGroup, { className: "ml-auto shrink-0", ...(kbdSize === undefined ? {} : { size: kbdSize }), children: kbd.map((key) => (_jsx(Kbd, { emphasis: "soft", children: key }, key))) }));
+};
+/** Animated label wrapper, hidden (removed from DOM) when the sidebar collapses. */
+const SidebarMenuLabel = ({ children, isCollapsed, }) => (_jsx(AnimatePresence, { children: !isCollapsed && (_jsx(m.span, { animate: { opacity: 1 }, className: "flex min-w-0 flex-1 items-center overflow-hidden", exit: { opacity: 0 }, initial: false, transition: SIDEBAR_TRANSITION, children: children })) }));
+/** Leading icon/content. Priority when collapsed: collapsedContent > collapsedIcon > icon. */
+const SidebarMenuButtonIcon = ({ collapsedContent, collapsedIcon, icon, iconSize, isCollapsed, }) => {
+    if (collapsedContent !== undefined && collapsedContent !== null) {
+        if (isCollapsed) {
+            return _jsx("span", { className: "shrink-0", children: collapsedContent });
+        }
+        // When expanded, show icon if provided, otherwise nothing
+        return icon ? (_jsx(Icon, { className: "shrink-0", icon: icon, ...(iconSize === undefined ? {} : { size: iconSize }) })) : null;
+    }
+    const activeIcon = isCollapsed && collapsedIcon ? collapsedIcon : icon;
+    return activeIcon ? (_jsx(Icon, { className: "shrink-0", icon: activeIcon, ...(iconSize === undefined ? {} : { size: iconSize }) })) : null;
+};
+/** Wraps the button in a Tooltip when a tooltip is configured; otherwise returns it as-is. */
+const SidebarMenuButtonTooltip = ({ button, isMobile, state, tooltip, tooltipOpen, }) => {
+    if (tooltip === undefined || tooltip === "") {
+        return button;
+    }
+    const tooltipProps = isString(tooltip) ? { children: tooltip } : tooltip;
+    return (_jsxs(Tooltip, { ...(tooltipOpen === false ? { open: false } : {}), children: [_jsx(TooltipTrigger, { render: button }), _jsx(TooltipContent, { align: "center", hidden: state !== "collapsed" || isMobile, side: "right", ...tooltipProps })] }));
+};
+/** Icon, label, suffix icon and shortcut hint, in row order. */
+/** Leading icon width in pixels per size (see MENU_ITEM_ICON_SIZES). */
+const ICON_PX = {
+    "2xl": 20,
+    "2xs": 12,
+    "3xl": 20,
+    base: 16,
+    lg: 18,
+    sm: 16,
+    xl: 16,
+    xs: 12,
+};
+const SidebarMenuButtonContent = ({ children, collapsedContent, collapsedIcon, icon, iconSize, isCollapsed, kbd, kbdSize, suffixIcon, }) => (_jsxs(_Fragment, { children: [_jsx(SidebarMenuButtonIcon, { collapsedContent: collapsedContent, ...(collapsedIcon === undefined ? {} : { collapsedIcon }), ...(icon === undefined ? {} : { icon }), iconSize: iconSize, isCollapsed: isCollapsed }), children !== null && children !== undefined ? (_jsx(SidebarMenuLabel, { isCollapsed: isCollapsed, children: children })) : null, suffixIcon ? (_jsx(Icon, { className: "shrink-0 group-data-[collapsible=icon]:hidden", icon: suffixIcon, ...(iconSize === undefined ? {} : { size: iconSize }) })) : null, _jsx(SidebarMenuKbd, { isCollapsed: isCollapsed, ...(kbd === undefined ? {} : { kbd }), kbdSize: kbdSize, ...(suffixIcon === undefined ? {} : { suffixIcon }) })] }));
+/**
+ * The `input` surface is white in light mode, which vanishes on the white
+ * sidebar; the sidebar's own accent keeps hover and active visible in both themes.
+ */
+const SURFACE_OVERRIDE = {
+    default: "",
+    input: "hover:bg-sidebar-accent focus:bg-sidebar-accent focus-visible:bg-sidebar-accent data-[active=true]:bg-sidebar-accent",
+    outline: "",
+};
+/**
+ * The primary interactive row of a sidebar menu - a leading icon plus label,
+ * optional suffix icon and keyboard-shortcut hint.
+ *
+ * Collapses to icon-only when the sidebar collapses (swapping in `collapsedIcon`
+ * /`collapsedContent` and revealing the `tooltip`), unless `forceExpanded`.
+ * Reads collapsed state from {@link useSidebar}; pass `render` to render a
+ * `<Link>` or other element as the button.
+ *
+ * @bestPractice In an icon-collapsible sidebar use `size="xl"`: the icon rail is sized for an `xl` row, so its collapsed square centres on the rail and the icon stays put as the sidebar folds.
+ */
+export const SidebarMenuButton = ({ render, active = false, variant = "input", size = "base", icon, collapsedIcon, collapsedContent, suffixIcon, forceExpanded = false, kbd, tooltip, tooltipOpen, className, children, style, ...props }) => {
+    const { isMobile, state } = useSidebar();
+    const isCollapsed = !forceExpanded && state === "collapsed" && !isMobile;
+    const iconSize = MENU_ITEM_ICON_SIZES[size];
+    const kbdSize = MENU_ITEM_KBD_SIZES[size];
+    const collapsedHeightPx = COLLAPSED_HEIGHT_PX[size];
+    // When collapsed, text content is removed from the DOM.
+    // Derive an aria-label from the tooltip so screen readers still identify the element.
+    const collapsedAriaLabel = getCollapsedAriaLabel(isCollapsed, tooltip);
+    // The icon is inset by half the space it leaves in the collapsed square, in
+    // both states: collapsing only narrows the row, so the icon never moves and
+    // ends centred in the square.
+    const buttonStyle = {
+        minHeight: collapsedHeightPx,
+        paddingInlineStart: (collapsedHeightPx - ICON_PX[size]) / 2,
+        width: isCollapsed ? collapsedHeightPx : "100%",
+        ...style,
+    };
+    const buttonClassName = cn(menuItemVariants({
+        radius: "full",
+        size,
+        variant,
+    }), SURFACE_OVERRIDE[variant], "transition-width duration-normal overflow-hidden ease-out", isCollapsed && "pr-0", className);
+    const baseProps = {
+        "aria-label": collapsedAriaLabel,
+        className: buttonClassName,
+        "data-active": active,
+        "data-component": "sidebar-menu-button",
+        "data-sidebar": "menu-button",
+        "data-size": size,
+        "data-slot": "sidebar-menu-button",
+        style: buttonStyle,
+        type: render === undefined ? "button" : undefined,
+    };
+    const button = useRender({
+        defaultTagName: "button",
+        props: mergeProps(baseProps, {
+            ...props,
+            children: (_jsx(SidebarMenuButtonContent, { collapsedContent: collapsedContent, ...(collapsedIcon === undefined ? {} : { collapsedIcon }), ...(icon === undefined ? {} : { icon }), iconSize: iconSize, isCollapsed: isCollapsed, ...(kbd === undefined ? {} : { kbd }), kbdSize: kbdSize, ...(suffixIcon === undefined ? {} : { suffixIcon }), children: children })),
+        }),
+        render,
+    });
+    return (_jsx(SidebarMenuButtonTooltip, { button: button, isMobile: isMobile, state: state, tooltip: tooltip, ...(tooltipOpen === undefined ? {} : { tooltipOpen }) }));
+};