@neynar/ui 0.1.1

package/src/components/ui/sidebar.tsx

@@ -0,0 +1,2211 @@
+import * as React from "react";
+import { useCallback } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { PanelLeftIcon } from "lucide-react";
+
+import { useIsMobile } from "@/hooks/use-mobile";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Separator } from "@/components/ui/separator";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet";
+import { Skeleton } from "@/components/ui/skeleton";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+
+const SIDEBAR_COOKIE_NAME = "sidebar_state";
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+const SIDEBAR_WIDTH = "16rem";
+const SIDEBAR_WIDTH_MOBILE = "18rem";
+const SIDEBAR_WIDTH_ICON = "3rem";
+const SIDEBAR_KEYBOARD_SHORTCUT = "b";
+
+type SidebarContextProps = {
+  state: "expanded" | "collapsed";
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  openMobile: boolean;
+  setOpenMobile: (open: boolean) => void;
+  isMobile: boolean;
+  toggleSidebar: () => void;
+};
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null);
+
+/**
+ * Hook to access sidebar state and control functions
+ *
+ * Provides access to the sidebar's state management including expanded/collapsed states,
+ * mobile-specific behavior, and toggle functions. This hook must be used within a
+ * SidebarProvider component tree to function properly.
+ *
+ * @returns {SidebarContextProps} Object containing sidebar state and control functions:
+ *   - `state`: "expanded" | "collapsed" - Current sidebar state
+ *   - `open`: boolean - Whether sidebar is open (desktop)
+ *   - `setOpen`: (open: boolean) => void - Function to control sidebar open state
+ *   - `openMobile`: boolean - Whether sidebar is open on mobile
+ *   - `setOpenMobile`: (open: boolean) => void - Function to control mobile sidebar state
+ *   - `isMobile`: boolean - Whether current viewport is considered mobile
+ *   - `toggleSidebar`: () => void - Function to toggle sidebar state
+ *
+ * @throws {Error} When used outside of SidebarProvider context
+ *
+ * @example
+ * ```tsx
+ * // Basic usage for toggle button
+ * function ToggleButton() {
+ *   const { state, toggleSidebar } = useSidebar()
+ *   return (
+ *     <button onClick={toggleSidebar}>
+ *       {state === "expanded" ? "Collapse" : "Expand"}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditional rendering based on state
+ * function ConditionalContent() {
+ *   const { state, isMobile } = useSidebar()
+ *   if (isMobile) return <MobileOnlyContent />
+ *   return state === "expanded" ? <FullContent /> : <CompactContent />
+ * }
+ * ```
+ *
+ * @see {@link SidebarProvider} - Required context provider
+ * @since 1.0.0
+ */
+function useSidebar() {
+  const context = React.useContext(SidebarContext);
+  if (!context) {
+    throw new Error("useSidebar must be used within a SidebarProvider.");
+  }
+
+  return context;
+}
+
+/**
+ * Context provider for comprehensive sidebar state management
+ *
+ * The SidebarProvider is the foundational component that manages all sidebar behavior
+ * including state persistence, responsive design, keyboard shortcuts, and mobile handling.
+ * It provides context to all sidebar-related components and should wrap your entire
+ * application or the section containing the sidebar.
+ *
+ * @component
+ *
+ * @param {boolean} [defaultOpen=true] - Initial open state when uncontrolled
+ * @param {boolean} [open] - Controlled open state (makes component controlled)
+ * @param {(open: boolean) => void} [onOpenChange] - Callback for open state changes
+ * @param {string} [className] - Additional CSS classes for wrapper
+ * @param {React.CSSProperties} [style] - Inline styles including CSS variables
+ * @param {React.ReactNode} children - Child components
+ *
+ * @example
+ * ```tsx
+ * // Basic uncontrolled usage
+ * <SidebarProvider>
+ *   <Sidebar />
+ *   <SidebarInset>
+ *     <main>Your content</main>
+ *   </SidebarInset>
+ * </SidebarProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled usage with custom state
+ * function App() {
+ *   const [sidebarOpen, setSidebarOpen] = useState(false)
+ *   return (
+ *     <SidebarProvider open={sidebarOpen} onOpenChange={setSidebarOpen}>
+ *       <Sidebar />
+ *       <SidebarInset>Content</SidebarInset>
+ *     </SidebarProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom width with CSS variables
+ * <SidebarProvider
+ *   style={{
+ *     "--sidebar-width": "20rem",
+ *     "--sidebar-width-mobile": "18rem"
+ *   }}
+ * >
+ *   <Sidebar />
+ * </SidebarProvider>
+ * ```
+ *
+ * @features
+ * - State persistence via cookies
+ * - Keyboard shortcut (Cmd/Ctrl+B) support
+ * - Responsive mobile behavior
+ * - CSS variable-based theming
+ * - Tooltip provider integration
+ *
+ * @accessibility
+ * - Keyboard shortcuts for power users
+ * - Mobile-optimized touch interactions
+ * - Focus management for modal-like mobile behavior
+ *
+ * @see {@link useSidebar} - Hook to access provided context
+ * @see {@link Sidebar} - Main sidebar component
+ * @since 1.0.0
+ */
+function SidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange: setOpenProp,
+  className,
+  style,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}) {
+  const isMobile = useIsMobile();
+  const [openMobile, setOpenMobile] = React.useState(false);
+
+  // This is the internal state of the sidebar.
+  // We use openProp and setOpenProp for control from outside the component.
+  const [_open, _setOpen] = React.useState(defaultOpen);
+  const open = openProp ?? _open;
+  const setOpen = useCallback(
+    (value: boolean | ((value: boolean) => boolean)) => {
+      const openState = typeof value === "function" ? value(open) : value;
+      if (setOpenProp) {
+        setOpenProp(openState);
+      } else {
+        _setOpen(openState);
+      }
+
+      // This sets the cookie to keep the sidebar state.
+      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
+    },
+    [setOpenProp, _setOpen, open],
+  );
+
+  // Helper to toggle the sidebar.
+  const toggleSidebar = useCallback(() => {
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
+  }, [isMobile, setOpenMobile, setOpen]);
+
+  // Adds a keyboard shortcut to toggle the sidebar.
+  React.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      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";
+
+  const contextValue: SidebarContextProps = {
+    state,
+    open,
+    setOpen,
+    isMobile,
+    openMobile,
+    setOpenMobile,
+    toggleSidebar,
+  };
+
+  return (
+    <SidebarContext.Provider value={contextValue}>
+      <TooltipProvider delayDuration={0}>
+        <div
+          data-slot="sidebar-wrapper"
+          style={
+            {
+              "--sidebar-width": SIDEBAR_WIDTH,
+              "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+              ...style,
+            } as React.CSSProperties
+          }
+          className={cn(
+            "group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar flex min-h-svh w-full",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </div>
+      </TooltipProvider>
+    </SidebarContext.Provider>
+  );
+}
+
+/**
+ * Flexible and responsive navigation sidebar component
+ *
+ * The Sidebar component is the main container for navigation content, supporting multiple
+ * visual variants, collapsible behaviors, and responsive design patterns. It automatically
+ * adapts between desktop layouts and mobile sheet overlays based on viewport size.
+ *
+ * @component
+ *
+ * @param {"left" | "right"} [side="left"] - Which side of the screen the sidebar appears on
+ * @param {"sidebar" | "floating" | "inset"} [variant="sidebar"] - Visual variant:
+ *   - `sidebar`: Standard full-height sidebar
+ *   - `floating`: Sidebar with padding, rounded corners, and shadow
+ *   - `inset`: Sidebar with margin that affects main content layout
+ * @param {"offcanvas" | "icon" | "none"} [collapsible="offcanvas"] - Collapse behavior:
+ *   - `offcanvas`: Slides completely off-screen when collapsed
+ *   - `icon`: Collapses to icon-only width, hiding text labels
+ *   - `none`: Cannot be collapsed, always visible
+ * @param {string} [className] - Additional CSS classes
+ * @param {React.ReactNode} children - Sidebar content (Header, Content, Footer)
+ *
+ * @example
+ * ```tsx
+ * // Standard navigation sidebar
+ * <SidebarProvider>
+ *   <Sidebar>
+ *     <SidebarHeader>
+ *       <h2>My Application</h2>
+ *     </SidebarHeader>
+ *     <SidebarContent>
+ *       <SidebarGroup>
+ *         <SidebarGroupLabel>Main</SidebarGroupLabel>
+ *         <SidebarGroupContent>
+ *           <SidebarMenu>
+ *             <SidebarMenuItem>
+ *               <SidebarMenuButton asChild>
+ *                 <Link href="/dashboard">
+ *                   <Home />
+ *                   <span>Dashboard</span>
+ *                 </Link>
+ *               </SidebarMenuButton>
+ *             </SidebarMenuItem>
+ *           </SidebarMenu>
+ *         </SidebarGroupContent>
+ *       </SidebarGroup>
+ *     </SidebarContent>
+ *     <SidebarFooter>
+ *       <SidebarMenu>
+ *         <SidebarMenuItem>
+ *           <SidebarMenuButton>
+ *             <Settings />
+ *             <span>Settings</span>
+ *           </SidebarMenuButton>
+ *         </SidebarMenuItem>
+ *       </SidebarMenu>
+ *     </SidebarFooter>
+ *   </Sidebar>
+ *   <SidebarInset>
+ *     <main>Main content area</main>
+ *   </SidebarInset>
+ * </SidebarProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Icon-collapsible sidebar with tooltips
+ * <SidebarProvider>
+ *   <Sidebar collapsible="icon">
+ *     <SidebarContent>
+ *       <SidebarGroup>
+ *         <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ *         <SidebarGroupContent>
+ *           <SidebarMenu>
+ *             <SidebarMenuItem>
+ *               <SidebarMenuButton tooltip="Go to Dashboard">
+ *                 <Home />
+ *                 <span>Dashboard</span>
+ *               </SidebarMenuButton>
+ *             </SidebarMenuItem>
+ *           </SidebarMenu>
+ *         </SidebarGroupContent>
+ *       </SidebarGroup>
+ *     </SidebarContent>
+ *   </Sidebar>
+ * </SidebarProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Floating variant with custom styling
+ * <SidebarProvider>
+ *   <Sidebar variant="floating">
+ *     <SidebarHeader>
+ *       <SidebarTrigger />
+ *       <h2>Floating Sidebar</h2>
+ *     </SidebarHeader>
+ *     <SidebarContent>
+ *       // Navigation content
+ *     </SidebarContent>
+ *   </Sidebar>
+ * </SidebarProvider>
+ * ```
+ *
+ * @accessibility
+ * - Keyboard shortcut: Cmd/Ctrl+B to toggle visibility
+ * - Full keyboard navigation support within sidebar
+ * - ARIA attributes indicate current state (expanded/collapsed)
+ * - Screen reader announcements for state changes
+ * - Mobile: Sheet overlay with proper focus management
+ * - Desktop: Seamless keyboard navigation between sidebar and main content
+ *
+ * @responsive
+ * - **Desktop**: Fixed-position sidebar with smooth width transitions
+ * - **Mobile**: Sheet overlay that slides in from the side
+ * - **Tablet**: Responsive breakpoints adapt behavior automatically
+ *
+ * @see {@link SidebarProvider} - Required context provider
+ * @see {@link SidebarHeader} - Header section component
+ * @see {@link SidebarContent} - Scrollable content area
+ * @see {@link SidebarFooter} - Footer section component
+ * @see {@link SidebarTrigger} - Toggle button component
+ * @see {@link SidebarRail} - Interactive resize handle
+ * @see {@link https://ui.shadcn.com/docs/components/sidebar} - shadcn/ui Sidebar documentation
+ * @since 1.0.0
+ */
+function Sidebar({
+  side = "left",
+  variant = "sidebar",
+  collapsible = "offcanvas",
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  side?: "left" | "right";
+  variant?: "sidebar" | "floating" | "inset";
+  collapsible?: "offcanvas" | "icon" | "none";
+}) {
+  const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
+
+  if (collapsible === "none") {
+    return (
+      <div
+        data-slot="sidebar"
+        className={cn(
+          "bg-sidebar text-sidebar-foreground flex h-full w-(--sidebar-width) flex-col",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  }
+
+  if (isMobile) {
+    return (
+      <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+        <SheetContent
+          data-sidebar="sidebar"
+          data-slot="sidebar"
+          data-mobile="true"
+          className="bg-sidebar text-sidebar-foreground w-(--sidebar-width) p-0 [&>button]:hidden"
+          style={
+            {
+              "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
+            } as React.CSSProperties
+          }
+          side={side}
+        >
+          <SheetHeader className="sr-only">
+            <SheetTitle>Sidebar</SheetTitle>
+            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+          </SheetHeader>
+          <div className="flex h-full w-full flex-col">{children}</div>
+        </SheetContent>
+      </Sheet>
+    );
+  }
+
+  return (
+    <div
+      className="group peer text-sidebar-foreground hidden md:block"
+      data-state={state}
+      data-collapsible={state === "collapsed" ? collapsible : ""}
+      data-variant={variant}
+      data-side={side}
+      data-slot="sidebar"
+    >
+      {/* This is what handles the sidebar gap on desktop */}
+      <div
+        data-slot="sidebar-gap"
+        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",
+          variant === "floating" || variant === "inset"
+            ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)",
+        )}
+      />
+      <div
+        data-slot="sidebar-container"
+        className={cn(
+          "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex",
+          side === "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)]",
+          // Adjust the padding for floating and inset variants.
+          variant === "floating" || variant === "inset"
+            ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+          className,
+        )}
+        {...props}
+      >
+        <div
+          data-sidebar="sidebar"
+          data-slot="sidebar-inner"
+          className="bg-sidebar group-data-[variant=floating]:border-sidebar-border flex h-full w-full flex-col group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:shadow-sm"
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Interactive button component for toggling sidebar visibility
+ *
+ * A pre-styled button that toggles the sidebar between expanded and collapsed states
+ * on desktop, or opens/closes the mobile sheet overlay on smaller screens. Features
+ * a panel icon and proper accessibility attributes.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {(event: React.MouseEvent) => void} [onClick] - Additional click handler
+ * @param {...React.ComponentProps<typeof Button>} props - All Button component props
+ *
+ * @example
+ * ```tsx
+ * // Basic usage in header
+ * <header className="flex items-center gap-2 p-4">
+ *   <SidebarTrigger />
+ *   <h1>My Application</h1>
+ * </header>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom click handler
+ * <SidebarTrigger
+ *   onClick={(e) => {
+ *     console.log('Sidebar toggled')
+ *     // Additional logic here
+ *   }}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Screen reader label: "Toggle Sidebar"
+ * - Keyboard accessible (Enter and Space keys)
+ * - Focus visible indicator for keyboard navigation
+ * - ARIA attributes for assistive technology
+ *
+ * @see {@link useSidebar} - Hook for custom toggle implementations
+ * @see {@link SidebarProvider} - Required context provider
+ * @since 1.0.0
+ */
+function SidebarTrigger({
+  className,
+  onClick,
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { toggleSidebar } = useSidebar();
+
+  return (
+    <Button
+      data-sidebar="trigger"
+      data-slot="sidebar-trigger"
+      variant="ghost"
+      size="icon"
+      className={cn("size-7", className)}
+      onClick={(event) => {
+        onClick?.(event);
+        toggleSidebar();
+      }}
+      {...props}
+    >
+      <PanelLeftIcon />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  );
+}
+
+/**
+ * Interactive rail component for sidebar edge interaction
+ *
+ * Provides a subtle interactive area along the sidebar edge that users can click
+ * to toggle the sidebar state. The rail is positioned at the sidebar boundary and
+ * includes hover states for discoverability. Only visible on desktop viewports.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"button">} props - All button element props
+ *
+ * @example
+ * ```tsx
+ * // Basic usage (typically placed at end of Sidebar)
+ * <Sidebar>
+ *   <SidebarHeader>Header content</SidebarHeader>
+ *   <SidebarContent>Navigation content</SidebarContent>
+ *   <SidebarFooter>Footer content</SidebarFooter>
+ *   <SidebarRail />
+ * </Sidebar>
+ * ```
+ *
+ * @accessibility
+ * - ARIA label: "Toggle Sidebar"
+ * - Keyboard accessible but with tabIndex={-1} to avoid tab trap
+ * - Hover and focus states for discoverability
+ * - Cursor changes based on sidebar state and side
+ *
+ * @see {@link SidebarTrigger} - Alternative toggle button
+ * @since 1.0.0
+ */
+function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+  const { toggleSidebar } = useSidebar();
+
+  return (
+    <button
+      data-sidebar="rail"
+      data-slot="sidebar-rail"
+      aria-label="Toggle Sidebar"
+      tabIndex={-1}
+      onClick={toggleSidebar}
+      title="Toggle Sidebar"
+      className={cn(
+        "hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] sm:flex",
+        "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
+        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+        "hover:group-data-[collapsible=offcanvas]:bg-sidebar group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full",
+        "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+        "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Main content container that adapts to sidebar layout
+ *
+ * The SidebarInset component serves as the primary content area that automatically
+ * adjusts its layout and spacing based on the sidebar's state and variant. It provides
+ * proper margins, responsive behavior, and styling coordination with the sidebar.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"main">} props - All main element props
+ *
+ * @example
+ * ```tsx
+ * // Standard layout with header and content
+ * <SidebarProvider>
+ *   <Sidebar>Sidebar content</Sidebar>
+ *   <SidebarInset>
+ *     <header className="flex h-16 items-center gap-2 px-4">
+ *       <SidebarTrigger />
+ *       <h1>Page Title</h1>
+ *     </header>
+ *     <main className="flex-1 p-4">
+ *       <p>Your main content goes here</p>
+ *     </main>
+ *   </SidebarInset>
+ * </SidebarProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With inset variant coordination
+ * <SidebarProvider>
+ *   <Sidebar variant="inset">Sidebar</Sidebar>
+ *   <SidebarInset>
+ *     // Content automatically gets proper spacing
+ *     <div>Content with proper inset margins</div>
+ *   </SidebarInset>
+ * </SidebarProvider>
+ * ```
+ *
+ * @features
+ * - Automatic layout adjustment based on sidebar state
+ * - Responsive margin and padding coordination
+ * - Proper spacing for different sidebar variants
+ * - Smooth transitions when sidebar state changes
+ *
+ * @see {@link Sidebar} - Main sidebar component
+ * @see {@link SidebarProvider} - Required context provider
+ * @since 1.0.0
+ */
+function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+  return (
+    <main
+      data-slot="sidebar-inset"
+      className={cn(
+        "bg-background relative flex w-full flex-1 flex-col",
+        "md:peer-data-[variant=inset]:m-2 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-2",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Input component optimized for sidebar usage
+ *
+ * A pre-styled input field designed to integrate seamlessly within sidebar layouts.
+ * Commonly used for search functionality, filters, or other input needs within
+ * the sidebar context. Features appropriate sizing and styling for sidebar use.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<typeof Input>} props - All Input component props
+ *
+ * @example
+ * ```tsx
+ * // Search input in sidebar header
+ * <SidebarHeader>
+ *   <h2>Navigation</h2>
+ *   <SidebarInput
+ *     placeholder="Search..."
+ *     onChange={(e) => handleSearch(e.target.value)}
+ *   />
+ * </SidebarHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Filter input with icon
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Filter Options</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     <SidebarInput
+ *       type="search"
+ *       placeholder="Filter items"
+ *       className="mb-2"
+ *     />
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @see {@link Input} - Base input component
+ * @since 1.0.0
+ */
+function SidebarInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof Input>) {
+  return (
+    <Input
+      data-slot="sidebar-input"
+      data-sidebar="input"
+      className={cn("bg-background h-8 w-full shadow-none", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Header section container for sidebar content
+ *
+ * A flexible container for sidebar header content such as logos, application titles,
+ * user information, or action buttons. The header remains visible even when the sidebar
+ * is collapsed to icon mode, making it ideal for persistent branding or key actions.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Simple header with title
+ * <SidebarHeader>
+ *   <h2 className="text-lg font-semibold">My Application</h2>
+ * </SidebarHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header with trigger and search
+ * <SidebarHeader>
+ *   <div className="flex items-center justify-between">
+ *     <h2>Navigation</h2>
+ *     <SidebarTrigger />
+ *   </div>
+ *   <SidebarInput placeholder="Search..." className="mt-2" />
+ * </SidebarHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header with user menu
+ * <SidebarHeader>
+ *   <SidebarMenu>
+ *     <SidebarMenuItem>
+ *       <DropdownMenu>
+ *         <DropdownMenuTrigger asChild>
+ *           <SidebarMenuButton>
+ *             <Avatar />
+ *             <span>John Doe</span>
+ *             <ChevronDown className="ml-auto" />
+ *           </SidebarMenuButton>
+ *         </DropdownMenuTrigger>
+ *         <DropdownMenuContent>
+ *           <DropdownMenuItem>Profile</DropdownMenuItem>
+ *           <DropdownMenuItem>Settings</DropdownMenuItem>
+ *           <DropdownMenuItem>Logout</DropdownMenuItem>
+ *         </DropdownMenuContent>
+ *       </DropdownMenu>
+ *     </SidebarMenuItem>
+ *   </SidebarMenu>
+ * </SidebarHeader>
+ * ```
+ *
+ * @see {@link SidebarFooter} - Footer section component
+ * @see {@link SidebarContent} - Main scrollable content area
+ * @since 1.0.0
+ */
+function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-header"
+      data-sidebar="header"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Footer section container for sidebar content
+ *
+ * A container positioned at the bottom of the sidebar for footer content such as
+ * user profiles, settings links, logout buttons, or help resources. The footer
+ * remains anchored to the bottom regardless of content height.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Simple footer with settings link
+ * <SidebarFooter>
+ *   <SidebarMenu>
+ *     <SidebarMenuItem>
+ *       <SidebarMenuButton>
+ *         <Settings />
+ *         <span>Settings</span>
+ *       </SidebarMenuButton>
+ *     </SidebarMenuItem>
+ *   </SidebarMenu>
+ * </SidebarFooter>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Footer with user profile and actions
+ * <SidebarFooter>
+ *   <SidebarMenu>
+ *     <SidebarMenuItem>
+ *       <SidebarMenuButton>
+ *         <Avatar className="h-6 w-6" />
+ *         <div className="flex flex-col text-left">
+ *           <span className="text-sm">John Doe</span>
+ *           <span className="text-xs text-muted-foreground">john@example.com</span>
+ *         </div>
+ *       </SidebarMenuButton>
+ *       <SidebarMenuAction>
+ *         <LogOut />
+ *       </SidebarMenuAction>
+ *     </SidebarMenuItem>
+ *   </SidebarMenu>
+ * </SidebarFooter>
+ * ```
+ *
+ * @see {@link SidebarHeader} - Header section component
+ * @see {@link SidebarContent} - Main content area
+ * @since 1.0.0
+ */
+function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-footer"
+      data-sidebar="footer"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Visual separator for organizing sidebar sections
+ *
+ * A horizontal divider component used to visually separate different sections
+ * within the sidebar content. Helps organize navigation groups and improve
+ * visual hierarchy and readability.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<typeof Separator>} props - All Separator component props
+ *
+ * @example
+ * ```tsx
+ * // Separating navigation groups
+ * <SidebarContent>
+ *   <SidebarGroup>
+ *     <SidebarGroupLabel>Main Navigation</SidebarGroupLabel>
+ *     <SidebarGroupContent>
+ *       // Main nav items
+ *     </SidebarGroupContent>
+ *   </SidebarGroup>
+ *
+ *   <SidebarSeparator />
+ *
+ *   <SidebarGroup>
+ *     <SidebarGroupLabel>Settings</SidebarGroupLabel>
+ *     <SidebarGroupContent>
+ *       // Settings items
+ *     </SidebarGroupContent>
+ *   </SidebarGroup>
+ * </SidebarContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Between header and content
+ * <Sidebar>
+ *   <SidebarHeader>
+ *     <h2>Application</h2>
+ *   </SidebarHeader>
+ *   <SidebarSeparator />
+ *   <SidebarContent>
+ *     // Navigation content
+ *   </SidebarContent>
+ * </Sidebar>
+ * ```
+ *
+ * @see {@link Separator} - Base separator component
+ * @since 1.0.0
+ */
+function SidebarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="sidebar-separator"
+      data-sidebar="separator"
+      className={cn("bg-sidebar-border mx-2 w-auto", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Scrollable main content area of the sidebar
+ *
+ * The primary content container that houses navigation groups, menus, and other
+ * sidebar content. Provides automatic scrolling when content exceeds available
+ * height and handles overflow behavior when the sidebar is collapsed.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Basic content with navigation groups
+ * <SidebarContent>
+ *   <SidebarGroup>
+ *     <SidebarGroupLabel>Main</SidebarGroupLabel>
+ *     <SidebarGroupContent>
+ *       <SidebarMenu>
+ *         <SidebarMenuItem>
+ *           <SidebarMenuButton>
+ *             <Home />
+ *             <span>Dashboard</span>
+ *           </SidebarMenuButton>
+ *         </SidebarMenuItem>
+ *       </SidebarMenu>
+ *     </SidebarGroupContent>
+ *   </SidebarGroup>
+ * </SidebarContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple groups with separators
+ * <SidebarContent>
+ *   <SidebarGroup>
+ *     <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ *     <SidebarGroupContent>
+ *       // Navigation items
+ *     </SidebarGroupContent>
+ *   </SidebarGroup>
+ *
+ *   <SidebarSeparator />
+ *
+ *   <SidebarGroup>
+ *     <SidebarGroupLabel>Projects</SidebarGroupLabel>
+ *     <SidebarGroupContent>
+ *       // Project items
+ *     </SidebarGroupContent>
+ *   </SidebarGroup>
+ * </SidebarContent>
+ * ```
+ *
+ * @features
+ * - Automatic scrolling for overflow content
+ * - Responsive to sidebar collapse states
+ * - Flexible gap spacing between child elements
+ * - Overflow hidden when collapsed to icon mode
+ *
+ * @see {@link SidebarGroup} - Content organization component
+ * @see {@link SidebarMenu} - Menu container component
+ * @since 1.0.0
+ */
+function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-content"
+      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}
+    />
+  );
+}
+
+/**
+ * Container for organizing related sidebar navigation items
+ *
+ * Groups related navigation items together with optional labels and actions,
+ * providing visual organization and hierarchy for complex navigation structures.
+ * Groups can include labels, action buttons, and any combination of menu items.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Basic group with label and menu
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     <SidebarMenu>
+ *       <SidebarMenuItem>
+ *         <SidebarMenuButton>
+ *           <Home />
+ *           <span>Dashboard</span>
+ *         </SidebarMenuButton>
+ *       </SidebarMenuItem>
+ *     </SidebarMenu>
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Group with action button
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Projects</SidebarGroupLabel>
+ *   <SidebarGroupAction>
+ *     <Plus className="h-4 w-4" />
+ *     <span className="sr-only">Add Project</span>
+ *   </SidebarGroupAction>
+ *   <SidebarGroupContent>
+ *     // Project items
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @see {@link SidebarGroupLabel} - Group label component
+ * @see {@link SidebarGroupAction} - Group action button
+ * @see {@link SidebarGroupContent} - Group content container
+ * @since 1.0.0
+ */
+function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group"
+      data-sidebar="group"
+      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Label component for sidebar groups
+ *
+ * Displays a descriptive label for a group of sidebar items, providing clear
+ * categorization and hierarchy. The label automatically hides when the sidebar
+ * is collapsed to icon mode to maintain clean visual presentation.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {boolean} [asChild=false] - Render as child element (using Slot)
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Standard text label
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Main Navigation</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     // Menu items
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom element using asChild
+ * <SidebarGroup>
+ *   <SidebarGroupLabel asChild>
+ *     <h3 className="custom-heading">Projects</h3>
+ *   </SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     // Project items
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @features
+ * - Automatic hide/show based on sidebar collapse state
+ * - Smooth opacity and margin transitions
+ * - Focus management for keyboard navigation
+ * - Support for custom elements via asChild prop
+ *
+ * @see {@link SidebarGroup} - Parent group container
+ * @see {@link SidebarGroupAction} - Associated action button
+ * @since 1.0.0
+ */
+function SidebarGroupLabel({
+  className,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"div"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : "div";
+
+  return (
+    <Comp
+      data-slot="sidebar-group-label"
+      data-sidebar="group-label"
+      className={cn(
+        "text-sidebar-foreground/70 ring-sidebar-ring flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium outline-hidden transition-[margin,opacity] duration-200 ease-linear focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        "group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Action button positioned within sidebar groups
+ *
+ * A compact action button positioned at the top-right of a sidebar group,
+ * typically used for group-specific actions such as adding new items, editing
+ * group settings, or accessing group options. Automatically hidden when collapsed.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {boolean} [asChild=false] - Render as child element (using Slot)
+ * @param {...React.ComponentProps<"button">} props - All button element props
+ *
+ * @example
+ * ```tsx
+ * // Add button for projects group
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Projects</SidebarGroupLabel>
+ *   <SidebarGroupAction>
+ *     <Plus className="h-4 w-4" />
+ *     <span className="sr-only">Add Project</span>
+ *   </SidebarGroupAction>
+ *   <SidebarGroupContent>
+ *     // Project items
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom action with asChild
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Settings</SidebarGroupLabel>
+ *   <SidebarGroupAction asChild>
+ *     <Button variant="ghost" size="sm">
+ *       <MoreHorizontal className="h-4 w-4" />
+ *     </Button>
+ *   </SidebarGroupAction>
+ *   <SidebarGroupContent>
+ *     // Settings items
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @accessibility
+ * - Increased touch target on mobile devices
+ * - Keyboard accessible with focus management
+ * - Screen reader support with descriptive labels
+ *
+ * @see {@link SidebarGroup} - Parent group container
+ * @see {@link SidebarGroupLabel} - Associated group label
+ * @since 1.0.0
+ */
+function SidebarGroupAction({
+  className,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="sidebar-group-action"
+      data-sidebar="group-action"
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground absolute top-3.5 right-3 flex aspect-square w-5 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",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Content container for sidebar group items
+ *
+ * Houses the actual navigation items, menus, and content within a sidebar group.
+ * Provides consistent spacing and organization for group content while maintaining
+ * proper typography and layout coordination.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Basic content with menu items
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     <SidebarMenu>
+ *       <SidebarMenuItem>
+ *         <SidebarMenuButton>
+ *           <Home />
+ *           <span>Dashboard</span>
+ *         </SidebarMenuButton>
+ *       </SidebarMenuItem>
+ *       <SidebarMenuItem>
+ *         <SidebarMenuButton>
+ *           <Settings />
+ *           <span>Settings</span>
+ *         </SidebarMenuButton>
+ *       </SidebarMenuItem>
+ *     </SidebarMenu>
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple menus in group content
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Projects</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     <SidebarMenu>
+ *       // Recent projects
+ *     </SidebarMenu>
+ *     <SidebarSeparator />
+ *     <SidebarMenu>
+ *       // Archived projects
+ *     </SidebarMenu>
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @see {@link SidebarGroup} - Parent group container
+ * @see {@link SidebarMenu} - Menu container component
+ * @since 1.0.0
+ */
+function SidebarGroupContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group-content"
+      data-sidebar="group-content"
+      className={cn("w-full text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Navigation menu container for organizing sidebar items
+ *
+ * An unordered list container that holds and organizes SidebarMenuItem components.
+ * Provides consistent spacing, layout, and semantic structure for navigation items
+ * within sidebar groups or sections.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"ul">} props - All ul element props
+ *
+ * @example
+ * ```tsx
+ * // Basic navigation menu
+ * <SidebarMenu>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton>
+ *       <Home />
+ *       <span>Dashboard</span>
+ *     </SidebarMenuButton>
+ *   </SidebarMenuItem>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton>
+ *       <Settings />
+ *       <span>Settings</span>
+ *     </SidebarMenuButton>
+ *   </SidebarMenuItem>
+ * </SidebarMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Menu with badges and actions
+ * <SidebarMenu>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton>
+ *       <Inbox />
+ *       <span>Messages</span>
+ *     </SidebarMenuButton>
+ *     <SidebarMenuBadge>3</SidebarMenuBadge>
+ *   </SidebarMenuItem>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuButton>
+ *       <Archive />
+ *       <span>Archive</span>
+ *     </SidebarMenuButton>
+ *     <SidebarMenuAction>
+ *       <MoreHorizontal />
+ *     </SidebarMenuAction>
+ *   </SidebarMenuItem>
+ * </SidebarMenu>
+ * ```
+ *
+ * @accessibility
+ * - Semantic ul/li structure for screen readers
+ * - Proper navigation landmarks
+ * - Keyboard navigation support
+ *
+ * @see {@link SidebarMenuItem} - Individual menu item component
+ * @see {@link SidebarMenuButton} - Interactive menu button
+ * @since 1.0.0
+ */
+function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu"
+      data-sidebar="menu"
+      className={cn("flex w-full min-w-0 flex-col gap-1", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual menu item container for sidebar navigation
+ *
+ * A list item container that wraps a single navigation item, typically containing
+ * a SidebarMenuButton along with optional components like SidebarMenuAction,
+ * SidebarMenuBadge, or SidebarMenuSub for hierarchical navigation.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"li">} props - All li element props
+ *
+ * @example
+ * ```tsx
+ * // Simple menu item with button
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Home />
+ *     <span>Dashboard</span>
+ *   </SidebarMenuButton>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Menu item with badge
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Inbox />
+ *     <span>Messages</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuBadge>5</SidebarMenuBadge>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Menu item with action button
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Folder />
+ *     <span>Projects</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuAction showOnHover>
+ *     <Plus />
+ *   </SidebarMenuAction>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Menu item with submenu
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Folder />
+ *     <span>Projects</span>
+ *     <ChevronRight className="ml-auto" />
+ *   </SidebarMenuButton>
+ *   <SidebarMenuSub>
+ *     <SidebarMenuSubItem>
+ *       <SidebarMenuSubButton>Web App</SidebarMenuSubButton>
+ *     </SidebarMenuSubItem>
+ *   </SidebarMenuSub>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @see {@link SidebarMenu} - Parent menu container
+ * @see {@link SidebarMenuButton} - Interactive button component
+ * @see {@link SidebarMenuAction} - Action button component
+ * @see {@link SidebarMenuBadge} - Badge indicator component
+ * @since 1.0.0
+ */
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-item"
+      data-sidebar="menu-item"
+      className={cn("group/menu-item relative", className)}
+      {...props}
+    />
+  );
+}
+
+const sidebarMenuButtonVariants = cva(
+  "peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm outline-hidden 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",
+    },
+  },
+);
+
+/**
+ * Interactive navigation button for sidebar menu items
+ *
+ * The primary interactive element for sidebar navigation, offering a flexible button
+ * component that supports active states, multiple visual variants, tooltip integration
+ * for collapsed modes, and composition patterns through the asChild prop. Automatically
+ * adapts its appearance based on sidebar state and provides smooth hover/focus transitions.
+ *
+ * @component
+ *
+ * @param {boolean} [asChild=false] - Render as child element using Slot composition
+ * @param {boolean} [isActive=false] - Whether this menu item is currently active
+ * @param {"default" | "outline"} [variant="default"] - Visual variant:
+ *   - `default`: Standard button appearance with hover states
+ *   - `outline`: Button with border and background on hover
+ * @param {"default" | "sm" | "lg"} [size="default"] - Button size variant:
+ *   - `default`: Standard height (h-8)
+ *   - `sm`: Small height (h-7)
+ *   - `lg`: Large height (h-12)
+ * @param {string | React.ComponentProps<typeof TooltipContent>} [tooltip] - Tooltip content shown when sidebar is collapsed
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"button">} props - All button element props
+ *
+ * @example
+ * ```tsx
+ * // Basic navigation button
+ * <SidebarMenuButton>
+ *   <Home className="h-4 w-4" />
+ *   <span>Dashboard</span>
+ * </SidebarMenuButton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Active state with Link composition
+ * <SidebarMenuButton asChild isActive={pathname === '/dashboard'}>
+ *   <Link href="/dashboard">
+ *     <Home className="h-4 w-4" />
+ *     <span>Dashboard</span>
+ *   </Link>
+ * </SidebarMenuButton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With tooltip for collapsed mode
+ * <SidebarMenuButton tooltip="Go to Dashboard">
+ *   <Home className="h-4 w-4" />
+ *   <span>Dashboard</span>
+ * </SidebarMenuButton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Different variants and sizes
+ * <SidebarMenuButton variant="outline" size="lg">
+ *   <Settings className="h-4 w-4" />
+ *   <span>Settings</span>
+ * </SidebarMenuButton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom tooltip with props
+ * <SidebarMenuButton
+ *   tooltip={{
+ *     children: "Dashboard Overview",
+ *     side: "right",
+ *     sideOffset: 10
+ *   }}
+ * >
+ *   <Home className="h-4 w-4" />
+ *   <span>Dashboard</span>
+ * </SidebarMenuButton>
+ * ```
+ *
+ * @accessibility
+ * - Full keyboard navigation support (Enter, Space)
+ * - Focus visible ring for keyboard users
+ * - Active state indication for screen readers
+ * - Tooltip automatically shown/hidden based on sidebar state
+ * - Proper contrast ratios for all states
+ * - Support for screen reader announcements
+ *
+ * @responsive
+ * - Automatically adapts to collapsed sidebar (icon-only mode)
+ * - Tooltip integration for collapsed state
+ * - Touch-friendly sizing on mobile devices
+ * - Smooth transitions between states
+ *
+ * @see {@link SidebarMenuItem} - Parent menu item container
+ * @see {@link SidebarMenuAction} - Secondary action button
+ * @see {@link SidebarMenuBadge} - Badge component for notifications
+ * @see {@link useSidebar} - Hook for sidebar state
+ * @since 1.0.0
+ */
+function SidebarMenuButton({
+  asChild = false,
+  isActive = false,
+  variant = "default",
+  size = "default",
+  tooltip,
+  className,
+  ...props
+}: React.ComponentProps<"button"> & {
+  asChild?: boolean;
+  isActive?: boolean;
+  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
+} & VariantProps<typeof sidebarMenuButtonVariants>) {
+  const Comp = asChild ? Slot : "button";
+  const { isMobile, state } = useSidebar();
+
+  const button = (
+    <Comp
+      data-slot="sidebar-menu-button"
+      data-sidebar="menu-button"
+      data-size={size}
+      data-active={isActive}
+      className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
+
+  if (!tooltip) {
+    return button;
+  }
+
+  if (typeof tooltip === "string") {
+    tooltip = {
+      children: tooltip,
+    };
+  }
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent
+        side="right"
+        align="center"
+        hidden={state !== "collapsed" || isMobile}
+        {...tooltip}
+      />
+    </Tooltip>
+  );
+}
+
+/**
+ * Secondary action button for sidebar menu items
+ *
+ * A compact action button positioned on the right side of menu items, providing
+ * secondary actions like edit, delete, or more options. Can be configured to show
+ * only on hover for cleaner interfaces or remain always visible for important actions.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {boolean} [asChild=false] - Render as child element using Slot composition
+ * @param {boolean} [showOnHover=false] - Only show button on menu item hover
+ * @param {...React.ComponentProps<"button">} props - All button element props
+ *
+ * @example
+ * ```tsx
+ * // Always visible action button
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Folder />
+ *     <span>Projects</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuAction>
+ *     <MoreHorizontal className="h-4 w-4" />
+ *   </SidebarMenuAction>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Show only on hover
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <File />
+ *     <span>Document</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuAction showOnHover>
+ *     <Trash2 className="h-4 w-4" />
+ *   </SidebarMenuAction>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom action with asChild
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Star />
+ *     <span>Favorites</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuAction asChild>
+ *     <DropdownMenu>
+ *       <DropdownMenuTrigger>
+ *         <MoreVertical className="h-4 w-4" />
+ *       </DropdownMenuTrigger>
+ *       <DropdownMenuContent>
+ *         <DropdownMenuItem>Edit</DropdownMenuItem>
+ *         <DropdownMenuItem>Delete</DropdownMenuItem>
+ *       </DropdownMenuContent>
+ *     </DropdownMenu>
+ *   </SidebarMenuAction>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @accessibility
+ * - Increased touch target area on mobile devices
+ * - Keyboard accessible with proper focus management
+ * - Hidden from screen readers when showOnHover and not focused
+ * - Proper contrast ratios for visibility
+ *
+ * @see {@link SidebarMenuItem} - Parent menu item
+ * @see {@link SidebarMenuButton} - Primary menu button
+ * @since 1.0.0
+ */
+function SidebarMenuAction({
+  className,
+  asChild = false,
+  showOnHover = false,
+  ...props
+}: React.ComponentProps<"button"> & {
+  asChild?: boolean;
+  showOnHover?: boolean;
+}) {
+  const Comp = asChild ? Slot : "button";
+
+  return (
+    <Comp
+      data-slot="sidebar-menu-action"
+      data-sidebar="menu-action"
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground peer-hover/menu-button:text-sidebar-accent-foreground absolute top-1.5 right-1 flex aspect-square w-5 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",
+        "peer-data-[size=sm]/menu-button:top-1",
+        "peer-data-[size=default]/menu-button:top-1.5",
+        "peer-data-[size=lg]/menu-button:top-2.5",
+        "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}
+    />
+  );
+}
+
+/**
+ * Badge indicator component for menu items
+ *
+ * Displays count indicators, status badges, or notification markers on menu items.
+ * Positioned on the right side of menu items and automatically coordinates with
+ * menu button states and sidebar collapse behavior.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Unread count badge
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Inbox />
+ *     <span>Messages</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuBadge>12</SidebarMenuBadge>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Status indicator
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Activity />
+ *     <span>System Status</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuBadge className="bg-green-500">●</SidebarMenuBadge>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Dynamic badge with state
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Bell />
+ *     <span>Notifications</span>
+ *   </SidebarMenuButton>
+ *   {notificationCount > 0 && (
+ *     <SidebarMenuBadge>{notificationCount}</SidebarMenuBadge>
+ *   )}
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @features
+ * - Automatic positioning relative to menu button size
+ * - Hidden when sidebar is collapsed to icon mode
+ * - Tabular numbers for consistent numeric display
+ * - Pointer events disabled to prevent interference
+ *
+ * @accessibility
+ * - Non-interactive (pointer-events-none)
+ * - Proper color contrast for readability
+ * - Screen reader friendly with appropriate text
+ *
+ * @see {@link SidebarMenuItem} - Parent menu item
+ * @see {@link SidebarMenuButton} - Associated menu button
+ * @since 1.0.0
+ */
+function SidebarMenuBadge({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-menu-badge"
+      data-sidebar="menu-badge"
+      className={cn(
+        "text-sidebar-foreground pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums select-none",
+        "peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[active=true]/menu-button:text-sidebar-accent-foreground",
+        "peer-data-[size=sm]/menu-button:top-1",
+        "peer-data-[size=default]/menu-button:top-1.5",
+        "peer-data-[size=lg]/menu-button:top-2.5",
+        "group-data-[collapsible=icon]:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Loading skeleton placeholder for menu items
+ *
+ * Displays an animated loading placeholder while menu items are being fetched
+ * or loaded. Features random width variation to simulate realistic content
+ * and optional icon placeholder for more accurate representation.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {boolean} [showIcon=false] - Whether to show icon placeholder
+ * @param {...React.ComponentProps<"div">} props - All div element props
+ *
+ * @example
+ * ```tsx
+ * // Basic skeleton without icon
+ * <SidebarMenu>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuSkeleton />
+ *   </SidebarMenuItem>
+ *   <SidebarMenuItem>
+ *     <SidebarMenuSkeleton />
+ *   </SidebarMenuItem>
+ * </SidebarMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Skeleton with icon placeholder
+ * <SidebarMenu>
+ *   {Array.from({ length: 5 }).map((_, index) => (
+ *     <SidebarMenuItem key={index}>
+ *       <SidebarMenuSkeleton showIcon />
+ *     </SidebarMenuItem>
+ *   ))}
+ * </SidebarMenu>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Loading state with React Suspense
+ * <SidebarGroup>
+ *   <SidebarGroupLabel>Projects</SidebarGroupLabel>
+ *   <SidebarGroupContent>
+ *     <SidebarMenu>
+ *       <React.Suspense
+ *         fallback={
+ *           <>
+ *             <SidebarMenuItem><SidebarMenuSkeleton showIcon /></SidebarMenuItem>
+ *             <SidebarMenuItem><SidebarMenuSkeleton showIcon /></SidebarMenuItem>
+ *             <SidebarMenuItem><SidebarMenuSkeleton showIcon /></SidebarMenuItem>
+ *           </>
+ *         }
+ *       >
+ *         <ProjectsList />
+ *       </React.Suspense>
+ *     </SidebarMenu>
+ *   </SidebarGroupContent>
+ * </SidebarGroup>
+ * ```
+ *
+ * @features
+ * - Random width variation (50-90%) for realistic appearance
+ * - Optional icon skeleton placeholder
+ * - Smooth loading animation
+ * - Proper sizing to match actual menu items
+ *
+ * @see {@link SidebarMenuItem} - Container for skeleton
+ * @see {@link SidebarMenu} - Parent menu container
+ * @see {@link Skeleton} - Base skeleton component
+ * @since 1.0.0
+ */
+function SidebarMenuSkeleton({
+  className,
+  showIcon = false,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showIcon?: boolean;
+}) {
+  // Random width between 50 to 90%.
+  const width = `${Math.floor(Math.random() * 40) + 50}%`;
+
+  return (
+    <div
+      data-slot="sidebar-menu-skeleton"
+      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>
+  );
+}
+
+/**
+ * Submenu container for hierarchical navigation
+ *
+ * A specialized container for nested navigation items that provides visual hierarchy
+ * through indentation and connecting border lines. Perfect for organizing complex
+ * navigation structures with parent-child relationships.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"ul">} props - All ul element props
+ *
+ * @example
+ * ```tsx
+ * // Collapsible submenu with parent item
+ * <SidebarMenuItem>
+ *   <Collapsible>
+ *     <CollapsibleTrigger asChild>
+ *       <SidebarMenuButton>
+ *         <Folder />
+ *         <span>Projects</span>
+ *         <ChevronRight className="ml-auto transition-transform group-data-[state=open]:rotate-90" />
+ *       </SidebarMenuButton>
+ *     </CollapsibleTrigger>
+ *     <CollapsibleContent>
+ *       <SidebarMenuSub>
+ *         <SidebarMenuSubItem>
+ *           <SidebarMenuSubButton>Web Application</SidebarMenuSubButton>
+ *         </SidebarMenuSubItem>
+ *         <SidebarMenuSubItem>
+ *           <SidebarMenuSubButton>Mobile App</SidebarMenuSubButton>
+ *         </SidebarMenuSubItem>
+ *         <SidebarMenuSubItem>
+ *           <SidebarMenuSubButton>Documentation</SidebarMenuSubButton>
+ *         </SidebarMenuSubItem>
+ *       </SidebarMenuSub>
+ *     </CollapsibleContent>
+ *   </Collapsible>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Always expanded submenu
+ * <SidebarMenuItem>
+ *   <SidebarMenuButton>
+ *     <Settings />
+ *     <span>Settings</span>
+ *   </SidebarMenuButton>
+ *   <SidebarMenuSub>
+ *     <SidebarMenuSubItem>
+ *       <SidebarMenuSubButton>General</SidebarMenuSubButton>
+ *     </SidebarMenuSubItem>
+ *     <SidebarMenuSubItem>
+ *       <SidebarMenuSubButton>Privacy</SidebarMenuSubButton>
+ *     </SidebarMenuSubItem>
+ *     <SidebarMenuSubItem>
+ *       <SidebarMenuSubButton>Security</SidebarMenuSubButton>
+ *     </SidebarMenuSubItem>
+ *   </SidebarMenuSub>
+ * </SidebarMenuItem>
+ * ```
+ *
+ * @features
+ * - Visual hierarchy with left border and indentation
+ * - Automatic hiding when sidebar is collapsed
+ * - Proper spacing and alignment with parent items
+ * - Seamless integration with collapsible components
+ *
+ * @accessibility
+ * - Semantic ul/li structure for screen readers
+ * - Proper nesting hierarchy for navigation
+ * - Keyboard navigation support
+ *
+ * @see {@link SidebarMenuSubItem} - Individual submenu item
+ * @see {@link SidebarMenuSubButton} - Submenu button component
+ * @see {@link SidebarMenuItem} - Parent menu item
+ * @since 1.0.0
+ */
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu-sub"
+      data-sidebar="menu-sub"
+      className={cn(
+        "border-sidebar-border mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l px-2.5 py-0.5",
+        "group-data-[collapsible=icon]:hidden",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual item container within submenu navigation
+ *
+ * A list item container for single nested navigation items within a submenu,
+ * providing the structural foundation for hierarchical navigation elements.
+ *
+ * @component
+ *
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"li">} props - All li element props
+ *
+ * @example
+ * ```tsx
+ * // Basic submenu item
+ * <SidebarMenuSub>
+ *   <SidebarMenuSubItem>
+ *     <SidebarMenuSubButton asChild>
+ *       <Link href="/projects/web-app">
+ *         <span>Web Application</span>
+ *       </Link>
+ *     </SidebarMenuSubButton>
+ *   </SidebarMenuSubItem>
+ * </SidebarMenuSub>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Submenu item with active state
+ * <SidebarMenuSub>
+ *   <SidebarMenuSubItem>
+ *     <SidebarMenuSubButton
+ *       isActive={pathname === '/settings/general'}
+ *       asChild
+ *     >
+ *       <Link href="/settings/general">
+ *         <span>General Settings</span>
+ *       </Link>
+ *     </SidebarMenuSubButton>
+ *   </SidebarMenuSubItem>
+ * </SidebarMenuSub>
+ * ```
+ *
+ * @see {@link SidebarMenuSub} - Parent submenu container
+ * @see {@link SidebarMenuSubButton} - Interactive button component
+ * @since 1.0.0
+ */
+function SidebarMenuSubItem({
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-sub-item"
+      data-sidebar="menu-sub-item"
+      className={cn("group/menu-sub-item relative", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Interactive button component for submenu navigation
+ *
+ * The primary interactive element for nested navigation items within submenus,
+ * featuring support for active states, different sizes, and composition patterns.
+ * Designed specifically for hierarchical navigation with appropriate styling and spacing.
+ *
+ * @component
+ *
+ * @param {boolean} [asChild=false] - Render as child element using Slot composition
+ * @param {"sm" | "md"} [size="md"] - Button size variant:
+ *   - `sm`: Small size with text-xs
+ *   - `md`: Medium size with text-sm
+ * @param {boolean} [isActive=false] - Whether this submenu item is currently active
+ * @param {string} [className] - Additional CSS classes
+ * @param {...React.ComponentProps<"a">} props - All anchor element props
+ *
+ * @example
+ * ```tsx
+ * // Basic submenu button
+ * <SidebarMenuSubItem>
+ *   <SidebarMenuSubButton>
+ *     <span>Documentation</span>
+ *   </SidebarMenuSubButton>
+ * </SidebarMenuSubItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Link composition with active state
+ * <SidebarMenuSubItem>
+ *   <SidebarMenuSubButton
+ *     asChild
+ *     isActive={pathname === '/projects/mobile'}
+ *   >
+ *     <Link href="/projects/mobile">
+ *       <span>Mobile Application</span>
+ *     </Link>
+ *   </SidebarMenuSubButton>
+ * </SidebarMenuSubItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Small size variant
+ * <SidebarMenuSubItem>
+ *   <SidebarMenuSubButton size="sm">
+ *     <span>API Reference</span>
+ *   </SidebarMenuSubButton>
+ * </SidebarMenuSubItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon and custom styling
+ * <SidebarMenuSubItem>
+ *   <SidebarMenuSubButton className="gap-3">
+ *     <File className="h-3 w-3" />
+ *     <span>README.md</span>
+ *   </SidebarMenuSubButton>
+ * </SidebarMenuSubItem>
+ * ```
+ *
+ * @accessibility
+ * - Full keyboard navigation support
+ * - Focus visible indicators
+ * - Active state indication for screen readers
+ * - Proper contrast ratios for all states
+ * - Support for assistive technology navigation
+ *
+ * @features
+ * - Automatic hiding when parent sidebar is collapsed
+ * - Smooth hover and focus transitions
+ * - Consistent spacing with parent menu items
+ * - Overflow text truncation for long labels
+ *
+ * @see {@link SidebarMenuSubItem} - Parent submenu item container
+ * @see {@link SidebarMenuSub} - Submenu container
+ * @see {@link SidebarMenuButton} - Parent menu button
+ * @since 1.0.0
+ */
+function SidebarMenuSubButton({
+  asChild = false,
+  size = "md",
+  isActive = false,
+  className,
+  ...props
+}: React.ComponentProps<"a"> & {
+  asChild?: boolean;
+  size?: "sm" | "md";
+  isActive?: boolean;
+}) {
+  const Comp = asChild ? Slot : "a";
+
+  return (
+    <Comp
+      data-slot="sidebar-menu-sub-button"
+      data-sidebar="menu-sub-button"
+      data-size={size}
+      data-active={isActive}
+      className={cn(
+        "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground [&>svg]:text-sidebar-accent-foreground flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 outline-hidden focus-visible:ring-2 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}
+    />
+  );
+}
+
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
+  SidebarTrigger,
+  useSidebar,
+};