@mihcm/ui 0.14.1

package/src/Sidebar.tsx

@@ -0,0 +1,956 @@
+'use client';
+
+/**
+ * Sidebar (web-only — React DOM).
+ *
+ * A composable, collapsible sidebar with mobile sheet support,
+ * keyboard shortcuts (Ctrl/Cmd+B), and cookie persistence.
+ *
+ * Composes: Button, Sheet, Separator, Skeleton, Tooltip, Input.
+ *
+ *   <SidebarProvider>
+ *     <Sidebar>
+ *       <SidebarHeader />
+ *       <SidebarContent>
+ *         <SidebarGroup>
+ *           <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ *           <SidebarGroupContent>
+ *             <SidebarMenu>
+ *               <SidebarMenuItem>
+ *                 <SidebarMenuButton>Dashboard</SidebarMenuButton>
+ *               </SidebarMenuItem>
+ *             </SidebarMenu>
+ *           </SidebarGroupContent>
+ *         </SidebarGroup>
+ *       </SidebarContent>
+ *       <SidebarFooter />
+ *     </Sidebar>
+ *     <SidebarInset>…main content…</SidebarInset>
+ *   </SidebarProvider>
+ *
+ * Wiki: docs/components/Sidebar.md
+ */
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type AnchorHTMLAttributes,
+  type ButtonHTMLAttributes,
+  type ComponentProps,
+  type HTMLAttributes,
+} from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+import { Button } from './Button.js';
+import { Sheet, SheetContent } from './Sheet.js';
+import { Separator } from './Separator.js';
+import { Skeleton } from './Skeleton.js';
+import { Tooltip } from './Tooltip.js';
+import { Input } from './Input.js';
+
+type SidebarSide = 'left' | 'right';
+type SidebarVariant = 'sidebar' | 'floating' | 'inset';
+type SidebarCollapsible = 'offcanvas' | 'icon' | 'none';
+type SidebarPosition = 'contained' | 'fixed';
+
+/* ── Inline icon (avoids a lucide-react dep on the ui package) ───── */
+
+function PanelLeftIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="h-4 w-4"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M9 3v18" />
+    </svg>
+  );
+}
+
+function PanelRightIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="h-4 w-4"
+    >
+      <rect width="18" height="18" x="3" y="3" rx="2" />
+      <path d="M15 3v18" />
+    </svg>
+  );
+}
+
+/* ── Constants ─────────────────────────────────────────────────────── */
+
+const SIDEBAR_COOKIE_NAME = 'sidebar_state';
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7; // 7 days
+const SIDEBAR_WIDTH = '16rem';
+const SIDEBAR_WIDTH_ICON = '3rem';
+const SIDEBAR_WIDTH_MOBILE = '18rem';
+const SIDEBAR_KEYBOARD_SHORTCUT = 'b';
+const SIDEBAR_MOBILE_BREAKPOINT = 768;
+
+/* ── useIsMobile (inline) ──────────────────────────────────────────── */
+
+function useIsMobile(breakpoint: number) {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== 'function') {
+      return;
+    }
+
+    const mql = window.matchMedia(`(max-width: ${breakpoint}px)`);
+    const onChange = () => setIsMobile(mql.matches);
+    onChange();
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, [breakpoint]);
+
+  return isMobile;
+}
+
+/* ── Context ───────────────────────────────────────────────────────── */
+
+interface SidebarContextValue {
+  state: 'expanded' | 'collapsed';
+  open: boolean;
+  setOpen: (open: boolean | ((prev: boolean) => boolean)) => void;
+  openMobile: boolean;
+  setOpenMobile: (open: boolean | ((prev: boolean) => boolean)) => void;
+  isMobile: boolean;
+  side: SidebarSide;
+  variant: SidebarVariant;
+  collapsible: SidebarCollapsible;
+  position: SidebarPosition;
+  toggleSidebar: () => void;
+}
+
+const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+export function useSidebar() {
+  const ctx = useContext(SidebarContext);
+  if (!ctx) {
+    throw new Error('useSidebar must be used within a <SidebarProvider>.');
+  }
+  return ctx;
+}
+
+/* ── SidebarProvider ───────────────────────────────────────────────── */
+
+export interface SidebarProviderProps extends HTMLAttributes<HTMLDivElement> {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Initial mobile Sheet open state. Useful for examples and forced mobile previews. */
+  defaultOpenMobile?: boolean;
+  /** Controlled mobile Sheet open state. */
+  openMobile?: boolean;
+  /** Called when mobile Sheet open state changes. */
+  onOpenMobileChange?: (open: boolean) => void;
+  side?: SidebarSide;
+  variant?: SidebarVariant;
+  collapsible?: SidebarCollapsible;
+  position?: SidebarPosition;
+  /** Force mobile behavior for previews/tests. When omitted, matchMedia decides. */
+  mobile?: boolean;
+  /** Breakpoint in px where the sidebar switches to mobile Sheet mode. */
+  mobileBreakpoint?: number;
+  /** Expanded desktop width. */
+  width?: string;
+  /** Collapsed icon-rail width. */
+  iconWidth?: string;
+  /** Mobile Sheet width. */
+  mobileWidth?: string;
+}
+
+export const SidebarProvider = forwardRef<HTMLDivElement, SidebarProviderProps>(
+  function SidebarProvider(
+    {
+      defaultOpen = true,
+      open: openProp,
+      onOpenChange: setOpenProp,
+      defaultOpenMobile = false,
+      openMobile: openMobileProp,
+      onOpenMobileChange: setOpenMobileProp,
+      side = 'left',
+      variant = 'sidebar',
+      collapsible = 'offcanvas',
+      position = 'contained',
+      mobile,
+      mobileBreakpoint = SIDEBAR_MOBILE_BREAKPOINT,
+      width = SIDEBAR_WIDTH,
+      iconWidth = SIDEBAR_WIDTH_ICON,
+      mobileWidth = SIDEBAR_WIDTH_MOBILE,
+      className,
+      style,
+      children,
+      ...props
+    },
+    ref,
+  ) {
+    const detectedMobile = useIsMobile(mobileBreakpoint);
+    const isMobile = mobile ?? detectedMobile;
+    const [_openMobile, _setOpenMobile] = useState(defaultOpenMobile);
+
+    // Start from props so server and initial client render match.
+    const [_open, _setOpen] = useState(defaultOpen);
+
+    const open = openProp ?? _open;
+    const openMobile = openMobileProp ?? _openMobile;
+
+    useEffect(() => {
+      if (openProp !== undefined) return;
+
+      const cookie = document.cookie
+        .split('; ')
+        .find((row) => row.startsWith(`${SIDEBAR_COOKIE_NAME}=`));
+      if (!cookie) return;
+
+      const nextOpen = cookie.split('=')[1] === 'true';
+      let cancelled = false;
+      queueMicrotask(() => {
+        if (!cancelled) {
+          _setOpen(nextOpen);
+        }
+      });
+
+      return () => {
+        cancelled = true;
+      };
+    }, [openProp]);
+
+    const setOpen = useCallback(
+      (value: boolean | ((prev: boolean) => boolean)) => {
+        const next = typeof value === 'function' ? value(open) : value;
+        if (setOpenProp) {
+          setOpenProp(next);
+        } else {
+          _setOpen(next);
+        }
+        if (typeof document !== 'undefined') {
+          document.cookie = `${SIDEBAR_COOKIE_NAME}=${next}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
+        }
+      },
+      [setOpenProp, open],
+    );
+
+    const setOpenMobile = useCallback(
+      (value: boolean | ((prev: boolean) => boolean)) => {
+        const next = typeof value === 'function' ? value(openMobile) : value;
+        if (setOpenMobileProp) {
+          setOpenMobileProp(next);
+        } else {
+          _setOpenMobile(next);
+        }
+      },
+      [openMobile, setOpenMobileProp],
+    );
+
+    const toggleSidebar = useCallback(() => {
+      if (collapsible === 'none') return;
+
+      if (isMobile) {
+        setOpenMobile((prev) => !prev);
+      } else {
+        setOpen((prev) => !prev);
+      }
+    }, [collapsible, isMobile, setOpen]);
+
+    // Keyboard shortcut: Ctrl+B / Cmd+B
+    useEffect(() => {
+      const handleKeyDown = (e: KeyboardEvent) => {
+        if (e.key === SIDEBAR_KEYBOARD_SHORTCUT && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          toggleSidebar();
+        }
+      };
+      window.addEventListener('keydown', handleKeyDown);
+      return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [toggleSidebar]);
+
+    const state = open ? 'expanded' : 'collapsed';
+
+    const value = useMemo<SidebarContextValue>(
+      () => ({
+        state,
+        open,
+        setOpen,
+        isMobile,
+        openMobile,
+        setOpenMobile,
+        side,
+        variant,
+        collapsible,
+        position,
+        toggleSidebar,
+      }),
+      [
+        state,
+        open,
+        setOpen,
+        isMobile,
+        openMobile,
+        setOpenMobile,
+        side,
+        variant,
+        collapsible,
+        position,
+        toggleSidebar,
+      ],
+    );
+
+    return (
+      <SidebarContext.Provider value={value}>
+        <div
+          ref={ref}
+          style={
+            {
+              '--sidebar-width': width,
+              '--sidebar-width-icon': iconWidth,
+              '--sidebar-width-mobile': mobileWidth,
+              ...style,
+            } as React.CSSProperties
+          }
+          className={cn(
+            'group/sidebar-wrapper flex min-h-svh w-full',
+            side === 'right' && 'flex-row-reverse',
+            variant === 'inset' && 'bg-sidebar',
+            className,
+          )}
+          data-sidebar="provider"
+          data-state={state}
+          data-collapsible={state === 'collapsed' ? collapsible : ''}
+          data-variant={variant}
+          data-side={side}
+          data-position={position}
+          {...props}
+        >
+          {children}
+        </div>
+      </SidebarContext.Provider>
+    );
+  },
+);
+
+/* ── Sidebar ───────────────────────────────────────────────────────── */
+
+export interface SidebarProps extends HTMLAttributes<HTMLElement> {
+  side?: SidebarSide;
+  variant?: SidebarVariant;
+  collapsible?: SidebarCollapsible;
+  position?: SidebarPosition;
+}
+
+export const Sidebar = forwardRef<HTMLElement, SidebarProps>(function Sidebar(
+  { side, variant, collapsible, position, className, children, ...props },
+  ref,
+) {
+  const context = useSidebar();
+  const { isMobile, state, openMobile, setOpenMobile } = context;
+  const currentSide = side ?? context.side;
+  const currentVariant = variant ?? context.variant;
+  const currentCollapsible = collapsible ?? context.collapsible;
+  const currentPosition = position ?? context.position;
+  const isCollapsed = state === 'collapsed';
+  const isFloating = currentVariant === 'floating' || currentVariant === 'inset';
+  const isOffcanvasCollapsed = isCollapsed && currentCollapsible === 'offcanvas';
+  const isIconCollapsed = isCollapsed && currentCollapsible === 'icon';
+  const sidebarEdgeBorder = currentSide === 'right'
+    ? 'border-l border-sidebar-border'
+    : 'border-r border-sidebar-border';
+
+  if (currentCollapsible === 'none') {
+    return (
+      <nav
+        ref={ref}
+        aria-label={props['aria-label'] ?? 'Sidebar'}
+        data-sidebar="sidebar"
+        data-state={state}
+        data-collapsible=""
+        data-variant={currentVariant}
+        data-side={currentSide}
+        data-position={currentPosition}
+        className={cn(
+          'flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground',
+          isFloating ? 'rounded-lg border border-sidebar-border shadow' : sidebarEdgeBorder,
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </nav>
+    );
+  }
+
+  if (isMobile) {
+    return (
+      <Sheet open={openMobile} onOpenChange={setOpenMobile}>
+        <SheetContent
+          data-sidebar="sidebar"
+          data-mobile="true"
+          className={cn(
+            'w-(--sidebar-width-mobile) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden',
+            className,
+          )}
+          side={currentSide}
+          {...props}
+        >
+          <nav aria-label={props['aria-label'] ?? 'Sidebar'} className="flex h-full w-full flex-col">
+            {children}
+          </nav>
+        </SheetContent>
+      </Sheet>
+    );
+  }
+
+  if (currentPosition === 'contained') {
+    return (
+      <div
+        data-sidebar="sidebar-container"
+        className={cn(
+          'group peer relative hidden h-full shrink-0 overflow-hidden text-sidebar-foreground transition-[width] duration-200 ease-linear md:flex',
+          isOffcanvasCollapsed
+            ? 'w-0'
+            : isIconCollapsed
+              ? isFloating
+                ? 'w-[calc(var(--sidebar-width-icon)+theme(spacing.4))]'
+                : 'w-(--sidebar-width-icon)'
+              : 'w-(--sidebar-width)',
+          isFloating && !isOffcanvasCollapsed && 'p-2',
+          className,
+        )}
+        data-state={state}
+        data-collapsible={isCollapsed ? currentCollapsible : ''}
+        data-variant={currentVariant}
+        data-side={currentSide}
+        data-position={currentPosition}
+      >
+        <nav
+          ref={ref}
+          aria-label={props['aria-label'] ?? 'Sidebar'}
+          data-sidebar="sidebar"
+          className={cn(
+            'flex h-full w-full min-w-0 flex-col bg-sidebar',
+            isFloating ? 'rounded-lg border border-sidebar-border shadow' : sidebarEdgeBorder,
+          )}
+          {...props}
+        >
+          {children}
+        </nav>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-sidebar="sidebar-container"
+      className="group peer hidden md:block text-sidebar-foreground"
+      data-state={state}
+      data-collapsible={isCollapsed ? currentCollapsible : ''}
+      data-variant={currentVariant}
+      data-side={currentSide}
+      data-position={currentPosition}
+    >
+      {/* Gap element — occupies space so the main content shifts */}
+      <div
+        className={cn(
+          'relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear',
+          'group-data-[collapsible=offcanvas]:w-0',
+          'group-data-[side=right]:rotate-180',
+          isFloating
+            ? 'group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+theme(spacing.4))]'
+            : 'group-data-[collapsible=icon]:w-(--sidebar-width-icon)',
+        )}
+      />
+      <div
+        className={cn(
+          'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex',
+          currentSide === 'left'
+            ? 'left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]'
+            : 'right-0 group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]',
+          isFloating
+            ? 'p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+theme(spacing.4)+2px)]'
+            : cn(
+                'group-data-[collapsible=icon]:w-(--sidebar-width-icon)',
+                'border-sidebar-border',
+                currentSide === 'right' ? 'group-data-[variant=sidebar]:border-l' : 'group-data-[variant=sidebar]:border-r',
+              ),
+          className,
+        )}
+        {...props}
+      >
+        <nav
+          ref={ref}
+          aria-label={props['aria-label'] ?? 'Sidebar'}
+          data-sidebar="sidebar"
+          className={cn(
+            'flex h-full w-full flex-col bg-sidebar group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-sidebar-border group-data-[variant=floating]:shadow',
+          )}
+        >
+          {children}
+        </nav>
+      </div>
+    </div>
+  );
+});
+
+/* ── SidebarTrigger ────────────────────────────────────────────────── */
+
+export const SidebarTrigger = forwardRef<
+  HTMLButtonElement,
+  ComponentProps<typeof Button>
+>(function SidebarTrigger({ className, disabled, onClick, ...props }, ref) {
+  const { isMobile, open, openMobile, collapsible, side, toggleSidebar } = useSidebar();
+  const expanded = collapsible === 'none' ? true : isMobile ? openMobile : open;
+  const isDisabled = disabled || collapsible === 'none';
+
+  return (
+    <Button
+      ref={ref}
+      data-sidebar="trigger"
+      aria-expanded={expanded}
+      aria-disabled={isDisabled || undefined}
+      disabled={isDisabled}
+      variant="ghost"
+      size="icon"
+      className={cn('size-7', className)}
+      onClick={(e) => {
+        onClick?.(e);
+        if (collapsible === 'none') return;
+        toggleSidebar();
+      }}
+      {...props}
+    >
+      {side === 'right' ? <PanelRightIcon /> : <PanelLeftIcon />}
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  );
+});
+
+/* ── SidebarRail ───────────────────────────────────────────────────── */
+
+export const SidebarRail = forwardRef<HTMLButtonElement, HTMLAttributes<HTMLButtonElement>>(
+  function SidebarRail({ className, ...props }, ref) {
+    const { toggleSidebar } = useSidebar();
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="rail"
+        aria-label="Toggle Sidebar"
+        tabIndex={-1}
+        onClick={toggleSidebar}
+        title="Toggle Sidebar"
+        className={cn(
+          'absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] group-data-[side=left]:-right-4 group-data-[side=left]:-translate-x-1/2 group-data-[side=right]:-left-4 group-data-[side=right]:translate-x-1/2 sm:flex',
+          'hover:after:bg-sidebar-border',
+          '[[data-side=left]_&]:cursor-w-resize [[data-side=right]_&]:cursor-e-resize',
+          '[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize',
+          'group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-sidebar',
+          '[[data-side=left][data-collapsible=offcanvas]_&]:-right-2 [[data-side=left][data-collapsible=offcanvas]_&]:translate-x-0',
+          '[[data-side=right][data-collapsible=offcanvas]_&]:-left-2 [[data-side=right][data-collapsible=offcanvas]_&]:translate-x-0',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── SidebarInset ──────────────────────────────────────────────────── */
+
+export const SidebarInset = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarInset({ className, ...props }, ref) {
+    return (
+      <main
+        ref={ref}
+        className={cn(
+          'relative flex min-h-svh flex-1 flex-col bg-background',
+          'peer-data-[variant=inset]:min-h-[calc(100svh-theme(spacing.4))] md:peer-data-[variant=inset]:m-2 md:peer-data-[side=left]:peer-data-[variant=inset]:ml-0 md:peer-data-[side=right]:peer-data-[variant=inset]:mr-0 md:peer-data-[side=left]:peer-data-[state=collapsed]:peer-data-[variant=inset]:ml-2 md:peer-data-[side=right]:peer-data-[state=collapsed]:peer-data-[variant=inset]:mr-2 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── SidebarInput ──────────────────────────────────────────────────── */
+
+export const SidebarInput = forwardRef<
+  HTMLInputElement,
+  ComponentProps<typeof Input>
+>(function SidebarInput({ className, ...props }, ref) {
+  return (
+    <Input
+      ref={ref}
+      data-sidebar="input"
+      className={cn(
+        'h-8 w-full bg-background shadow-none focus-within:ring-2 focus-within:ring-sidebar-ring',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── Layout sections ───────────────────────────────────────────────── */
+
+export const SidebarHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarHeader({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="header"
+        className={cn('flex flex-col gap-2 p-2', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarFooter = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarFooter({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="footer"
+        className={cn('flex flex-col gap-2 p-2', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarContent = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarContent({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="content"
+        className={cn(
+          'flex min-h-0 flex-1 flex-col gap-2 overflow-auto group-data-[collapsible=icon]:overflow-hidden',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── SidebarSeparator ──────────────────────────────────────────────── */
+
+export const SidebarSeparator = forwardRef<
+  HTMLDivElement,
+  ComponentProps<typeof Separator>
+>(function SidebarSeparator({ className, ...props }, ref) {
+  return (
+    <Separator
+      ref={ref}
+      data-sidebar="separator"
+      className={cn('mx-2 w-auto bg-sidebar-border', className)}
+      {...props}
+    />
+  );
+});
+
+/* ── Group ─────────────────────────────────────────────────────────── */
+
+export const SidebarGroup = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarGroup({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="group"
+        className={cn('relative flex w-full min-w-0 flex-col p-2', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarGroupLabel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement> & { asChild?: boolean }>(
+  function SidebarGroupLabel({ className, asChild: _asChild, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="group-label"
+        className={cn(
+          'flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 outline-none ring-sidebar-ring transition-[margin,opacity] duration-200 ease-linear focus-visible:ring-2',
+          'group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarGroupAction = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement> & { asChild?: boolean }>(
+  function SidebarGroupAction({ className, asChild: _asChild, ...props }, ref) {
+    return (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="group-action"
+        className={cn(
+          'absolute right-3 top-3.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground outline-none ring-sidebar-ring transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0',
+          'after:absolute after:-inset-2 after:md:hidden',
+          'group-data-[collapsible=icon]:hidden',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarGroupContent = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarGroupContent({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="group-content"
+        className={cn('w-full text-sm', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── Menu ──────────────────────────────────────────────────────────── */
+
+export const SidebarMenu = forwardRef<HTMLUListElement, HTMLAttributes<HTMLUListElement>>(
+  function SidebarMenu({ className, ...props }, ref) {
+    return (
+      <ul
+        ref={ref}
+        data-sidebar="menu"
+        className={cn('flex w-full min-w-0 flex-col gap-1', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarMenuItem = forwardRef<HTMLLIElement, HTMLAttributes<HTMLLIElement>>(
+  function SidebarMenuItem({ className, ...props }, ref) {
+    return (
+      <li
+        ref={ref}
+        data-sidebar="menu-item"
+        className={cn('group/menu-item relative', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── SidebarMenuButton ─────────────────────────────────────────────── */
+
+export const sidebarMenuButtonVariants = cva(
+  'peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm outline-none ring-sidebar-ring transition-[width,height,padding] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pr-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground data-[state=open]:hover:bg-sidebar-accent data-[state=open]:hover:text-sidebar-accent-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+        outline:
+          'bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]',
+      },
+      size: {
+        default: 'h-8 text-sm',
+        sm: 'h-7 text-xs',
+        lg: 'h-12 text-sm group-data-[collapsible=icon]:p-0!',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
+export interface SidebarMenuButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof sidebarMenuButtonVariants> {
+  asChild?: boolean;
+  isActive?: boolean;
+  tooltip?: string | ComponentProps<typeof Tooltip>;
+}
+
+export const SidebarMenuButton = forwardRef<HTMLButtonElement, SidebarMenuButtonProps>(
+  function SidebarMenuButton(
+    { asChild: _asChild, isActive = false, variant, size, tooltip, className, ...props },
+    ref,
+  ) {
+    useSidebar();
+
+    const button = (
+      <button
+        ref={ref}
+        type="button"
+        data-sidebar="menu-button"
+        data-size={size}
+        data-active={isActive}
+        className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+        {...props}
+      />
+    );
+
+    if (!tooltip) return button;
+
+    const tooltipProps: ComponentProps<typeof Tooltip> =
+      typeof tooltip === 'string' ? { content: tooltip } : tooltip;
+
+    return (
+      <Tooltip {...tooltipProps} side="right">
+        {button}
+      </Tooltip>
+    );
+  },
+);
+
+/* ── SidebarMenuAction ─────────────────────────────────────────────── */
+
+export const SidebarMenuAction = forwardRef<
+  HTMLButtonElement,
+  ButtonHTMLAttributes<HTMLButtonElement> & { asChild?: boolean; showOnHover?: boolean }
+>(function SidebarMenuAction({ className, asChild: _asChild, showOnHover = false, ...props }, ref) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      data-sidebar="menu-action"
+      className={cn(
+        'absolute right-1 top-1.5 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground outline-none ring-sidebar-ring transition-transform hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 peer-hover/menu-button:text-sidebar-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0',
+        'after:absolute after:-inset-2 after:md:hidden',
+        'group-data-[collapsible=icon]:hidden',
+        showOnHover &&
+          'peer-data-[active=true]/menu-button:text-sidebar-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 md:opacity-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── SidebarMenuBadge ──────────────────────────────────────────────── */
+
+export const SidebarMenuBadge = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function SidebarMenuBadge({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-sidebar="menu-badge"
+        className={cn(
+          'pointer-events-none absolute right-1 flex h-5 min-w-5 select-none items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums text-sidebar-foreground',
+          'peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[active=true]/menu-button:text-sidebar-accent-foreground',
+          'group-data-[collapsible=icon]:hidden',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+/* ── SidebarMenuSkeleton ───────────────────────────────────────────── */
+
+export interface SidebarMenuSkeletonProps extends HTMLAttributes<HTMLDivElement> {
+  showIcon?: boolean;
+}
+
+export const SidebarMenuSkeleton = forwardRef<HTMLDivElement, SidebarMenuSkeletonProps>(
+  function SidebarMenuSkeleton({ className, showIcon = false, ...props }, ref) {
+    // Fixed skeleton width — visual variety comes from multiple instances
+    const width = '70%';
+
+    return (
+      <div
+        ref={ref}
+        data-sidebar="menu-skeleton"
+        className={cn('flex h-8 items-center gap-2 rounded-md px-2', className)}
+        {...props}
+      >
+        {showIcon && <Skeleton className="size-4 rounded-md" data-sidebar="menu-skeleton-icon" />}
+        <Skeleton
+          className="h-4 max-w-(--skeleton-width) flex-1"
+          data-sidebar="menu-skeleton-text"
+          style={{ '--skeleton-width': width } as React.CSSProperties}
+        />
+      </div>
+    );
+  },
+);
+
+/* ── Sub-menu ──────────────────────────────────────────────────────── */
+
+export const SidebarMenuSub = forwardRef<HTMLUListElement, HTMLAttributes<HTMLUListElement>>(
+  function SidebarMenuSub({ className, ...props }, ref) {
+    return (
+      <ul
+        ref={ref}
+        data-sidebar="menu-sub"
+        className={cn(
+          'mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5',
+          'group-data-[collapsible=icon]:hidden',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+export const SidebarMenuSubItem = forwardRef<HTMLLIElement, HTMLAttributes<HTMLLIElement>>(
+  function SidebarMenuSubItem({ ...props }, ref) {
+    return <li ref={ref} {...props} />;
+  },
+);
+
+export interface SidebarMenuSubButtonProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  asChild?: boolean;
+  size?: 'sm' | 'md';
+  isActive?: boolean;
+}
+
+export const SidebarMenuSubButton = forwardRef<HTMLAnchorElement, SidebarMenuSubButtonProps>(
+  function SidebarMenuSubButton({ asChild: _asChild, size = 'md', isActive, className, ...props }, ref) {
+    return (
+      <a
+        ref={ref}
+        data-sidebar="menu-sub-button"
+        data-size={size}
+        data-active={isActive}
+        className={cn(
+          'flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0',
+          'data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground',
+          size === 'sm' && 'text-xs',
+          size === 'md' && 'text-sm',
+          'group-data-[collapsible=icon]:hidden',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);