@neynar/ui 0.4.0 → 1.0.0

package/src/components/ui/sidebar.tsx

@@ -1,10 +1,10 @@
+"use client";
+
 import * as React from "react";
-import { useCallback } from "react";
-import { Slot } from "@radix-ui/react-slot";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
 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";
@@ -20,9 +20,10 @@ import { Skeleton } from "@/components/ui/skeleton";
 import {
   Tooltip,
   TooltipContent,
-  TooltipProvider,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
+import { useIsMobile } from "@/hooks/use-mobile";
+import { PanelLeftIcon } from "lucide-react";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
@@ -31,366 +32,6 @@ const SIDEBAR_WIDTH_MOBILE = "18rem";
 const SIDEBAR_WIDTH_ICON = "3rem";
 const SIDEBAR_KEYBOARD_SHORTCUT = "b";
 
-/**
- * Context props for sidebar state management (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace inferred context types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarContextDocsProps = {
-  /** Current visual state of the sidebar */
-  state: "expanded" | "collapsed";
-  /** Whether sidebar is open on desktop */
-  open: boolean;
-  /** Function to control desktop sidebar open state */
-  setOpen: (open: boolean) => void;
-  /** Whether sidebar is open on mobile (sheet overlay) */
-  openMobile: boolean;
-  /** Function to control mobile sidebar open state */
-  setOpenMobile: (open: boolean) => void;
-  /** Whether current viewport is considered mobile */
-  isMobile: boolean;
-  /** Function to toggle sidebar state (responsive) */
-  toggleSidebar: () => void;
-};
-
-/**
- * Props for SidebarProvider component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarProviderDocsProps = {
-  /** Initial open state when uncontrolled @default true */
-  defaultOpen?: boolean;
-  /** Controlled open state (makes component controlled) */
-  open?: boolean;
-  /** Callback fired when open state changes */
-  onOpenChange?: (open: boolean) => void;
-  /** Child components */
-  children?: React.ReactNode;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for Sidebar component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarDocsProps = {
-  /**
-   * Which side of the screen the sidebar appears on @default "left"
-   *
-   * Controls the horizontal positioning and slide direction of the sidebar.
-   * Affects the direction of collapse animations and the positioning of
-   * the interactive rail component.
-   */
-  side?: "left" | "right";
-  /** Visual appearance variant @default "sidebar" */
-  variant?: "sidebar" | "floating" | "inset";
-  /** Collapse behavior mode @default "offcanvas" */
-  collapsible?: "offcanvas" | "icon" | "none";
-  /** Additional CSS classes */
-  className?: string;
-  /** Sidebar content components */
-  children?: React.ReactNode;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarTrigger component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarTriggerDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-  /** Additional click handler called before toggle */
-  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
-} & Omit<React.ComponentProps<typeof Button>, "onClick">;
-
-/**
- * Props for SidebarRail component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarRailDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"button">;
-
-/**
- * Props for SidebarInset component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarInsetDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"main">;
-
-/**
- * Props for SidebarInput component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarInputDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<typeof Input>;
-
-/**
- * Props for SidebarHeader component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarHeaderDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarFooter component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarFooterDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarSeparator component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarSeparatorDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<typeof Separator>;
-
-/**
- * Props for SidebarContent component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarContentDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarGroup component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarGroupDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarGroupLabel component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarGroupLabelDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-  /**
-   * Render as child element using Radix UI Slot composition pattern @default false
-   *
-   * When true, the component will not render its default element,
-   * instead merging its props with its immediate child. This enables
-   * composition with custom elements (like Link components) while
-   * preserving the component's behavior and styling.
-   */
-  asChild?: boolean;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarGroupAction component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarGroupActionDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-  /**
-   * Render as child element using Radix UI Slot composition pattern @default false
-   *
-   * When true, the component will not render its default element,
-   * instead merging its props with its immediate child. This enables
-   * composition with custom elements (like Link components) while
-   * preserving the component's behavior and styling.
-   */
-  asChild?: boolean;
-} & React.ComponentProps<"button">;
-
-/**
- * Props for SidebarGroupContent component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarGroupContentDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarMenu component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"ul">;
-
-/**
- * Props for SidebarMenuItem component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuItemDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"li">;
-
-/**
- * Props for SidebarMenuButton component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuButtonDocsProps = {
-  /**
-   * Render as child element using Radix UI Slot composition pattern @default false
-   *
-   * When true, the component will not render its default element,
-   * instead merging its props with its immediate child. This enables
-   * composition with custom elements (like Link components) while
-   * preserving the component's behavior and styling.
-   */
-  asChild?: boolean;
-  /** Whether this menu item is currently active @default false */
-  isActive?: boolean;
-  /** Visual appearance variant @default "default" */
-  variant?: "default" | "outline";
-  /** Button size variant @default "default" */
-  size?: "default" | "sm" | "lg";
-  /**
-   * Tooltip content shown when sidebar is collapsed to icon mode
-   *
-   * Can be either a string for simple text or a full TooltipContent props object
-   * for advanced configuration. Tooltip is automatically shown/hidden based on
-   * sidebar state and is never displayed on mobile devices.
-   *
-   * @example Simple string tooltip
-   * ```tsx
-   * <SidebarMenuButton tooltip=\"Dashboard\">
-   *   <Home />Dashboard
-   * </SidebarMenuButton>
-   * ```
-   *
-   * @example Advanced tooltip with props
-   * ```tsx
-   * <SidebarMenuButton tooltip={{
-   *   children: \"Go to Dashboard\",
-   *   side: \"right\",
-   *   sideOffset: 10
-   * }}>
-   *   <Home />Dashboard
-   * </SidebarMenuButton>
-   * ```
-   */
-  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"button">;
-
-/**
- * Props for SidebarMenuAction component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuActionDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-  /**
-   * Render as child element using Radix UI Slot composition pattern @default false
-   *
-   * When true, the component will not render its default element,
-   * instead merging its props with its immediate child. This enables
-   * composition with custom elements (like Link components) while
-   * preserving the component's behavior and styling.
-   */
-  asChild?: boolean;
-  /** Only show button on menu item hover @default false */
-  showOnHover?: boolean;
-} & React.ComponentProps<"button">;
-
-/**
- * Props for SidebarMenuBadge component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuBadgeDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarMenuSkeleton component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuSkeletonDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-  /** Whether to show icon placeholder @default false */
-  showIcon?: boolean;
-} & React.ComponentProps<"div">;
-
-/**
- * Props for SidebarMenuSub component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuSubDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"ul">;
-
-/**
- * Props for SidebarMenuSubItem component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuSubItemDocsProps = {
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"li">;
-
-/**
- * Props for SidebarMenuSubButton component (Documentation only - NOT used in component implementation)
- * These types are for documentation generation and should not replace React.ComponentProps inferred types
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SidebarMenuSubButtonDocsProps = {
-  /**
-   * Render as child element using Radix UI Slot composition pattern @default false
-   *
-   * When true, the component will not render its default element,
-   * instead merging its props with its immediate child. This enables
-   * composition with custom elements (like Link components) while
-   * preserving the component's behavior and styling.
-   */
-  asChild?: boolean;
-  /** Button size variant @default "md" */
-  size?: "sm" | "md";
-  /** Whether this submenu item is currently active @default false */
-  isActive?: boolean;
-  /** Additional CSS classes */
-  className?: string;
-} & React.ComponentProps<"a">;
-
-// Internal context type (inferred from implementation)
 type SidebarContextProps = {
   state: "expanded" | "collapsed";
   open: boolean;
@@ -404,48 +45,8 @@ type SidebarContextProps = {
 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
+ * Hook to access sidebar context including state, mobile state, and toggle functions.
+ * Must be used within SidebarProvider.
  */
 function useSidebar() {
   const context = React.useContext(SidebarContext);
@@ -456,76 +57,18 @@ function useSidebar() {
   return context;
 }
 
+type SidebarProviderProps = React.ComponentProps<"div"> & {
+  /** Initial open state on desktop. @default true */
+  defaultOpen?: boolean;
+  /** Controlled open state for desktop. */
+  open?: boolean;
+  /** Callback when open state changes. Persists state in cookie. */
+  onOpenChange?: (open: boolean) => void;
+};
+
 /**
- * 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
+ * Root provider for sidebar with state management, keyboard shortcuts (⌘B), and mobile detection.
+ * Manages collapsed/expanded state and persists preference in cookie.
  */
 function SidebarProvider({
   defaultOpen = true,
@@ -535,12 +78,7 @@ function SidebarProvider({
   style,
   children,
   ...props
-}: {
-  defaultOpen?: boolean;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  children?: React.ReactNode;
-} & React.ComponentProps<"div">) {
+}: SidebarProviderProps) {
   const isMobile = useIsMobile();
   const [openMobile, setOpenMobile] = React.useState(false);
 
@@ -548,7 +86,7 @@ function SidebarProvider({
   // We use openProp and setOpenProp for control from outside the component.
   const [_open, _setOpen] = React.useState(defaultOpen);
   const open = openProp ?? _open;
-  const setOpen = useCallback(
+  const setOpen = React.useCallback(
     (value: boolean | ((value: boolean) => boolean)) => {
       const openState = typeof value === "function" ? value(open) : value;
       if (setOpenProp) {
@@ -560,13 +98,13 @@ function SidebarProvider({
       // 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],
+    [setOpenProp, open],
   );
 
   // Helper to toggle the sidebar.
-  const toggleSidebar = useCallback(() => {
+  const toggleSidebar = React.useCallback(() => {
     return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open);
-  }, [isMobile, setOpenMobile, setOpen]);
+  }, [isMobile, setOpen, setOpenMobile]);
 
   // Adds a keyboard shortcut to toggle the sidebar.
   React.useEffect(() => {
@@ -588,165 +126,54 @@ function SidebarProvider({
   // 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,
-  };
+  const contextValue = React.useMemo<SidebarContextProps>(
+    () => ({
+      state,
+      open,
+      setOpen,
+      isMobile,
+      openMobile,
+      setOpenMobile,
+      toggleSidebar,
+    }),
+    [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>
+      <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>
     </SidebarContext.Provider>
   );
 }
 
+type SidebarProps = React.ComponentProps<"div"> & {
+  /** Which side to display sidebar. @default "left" */
+  side?: "left" | "right";
+  /** Visual variant. @default "sidebar" */
+  variant?: "sidebar" | "floating" | "inset";
+  /** Collapse behavior. @default "offcanvas" */
+  collapsible?: "offcanvas" | "icon" | "none";
+};
+
 /**
- * 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
+ * Sidebar container with responsive behavior. Renders as Sheet on mobile.
+ * Use with SidebarProvider for state management.
  */
 function Sidebar({
   side = "left",
@@ -755,13 +182,7 @@ function Sidebar({
   className,
   children,
   ...props
-}: {
-  side?: "left" | "right";
-  variant?: "sidebar" | "floating" | "inset";
-  collapsible?: "offcanvas" | "icon" | "none";
-  className?: string;
-  children?: React.ReactNode;
-} & React.ComponentProps<"div">) {
+}: SidebarProps) {
   const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
 
   if (collapsible === "none") {
@@ -817,7 +238,7 @@ function Sidebar({
       <div
         data-slot="sidebar-gap"
         className={cn(
-          "relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear",
+          "transition-[width] duration-200 ease-linear relative w-(--sidebar-width) bg-transparent",
           "group-data-[collapsible=offcanvas]:w-0",
           "group-data-[side=right]:rotate-180",
           variant === "floating" || variant === "inset"
@@ -843,7 +264,7 @@ function Sidebar({
         <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"
+          className="bg-sidebar group-data-[variant=floating]:ring-sidebar-border group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 flex size-full flex-col"
         >
           {children}
         </div>
@@ -852,57 +273,12 @@ function Sidebar({
   );
 }
 
+type SidebarTriggerProps = React.ComponentProps<typeof Button>;
+
 /**
- * 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
+ * Button to toggle sidebar open/closed. Shows hamburger icon.
  */
-function SidebarTrigger({
-  className,
-  onClick,
-  ...props
-}: {
-  className?: string;
-  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
-} & Omit<React.ComponentProps<typeof Button>, "onClick">) {
+function SidebarTrigger({ className, onClick, ...props }: SidebarTriggerProps) {
   const { toggleSidebar } = useSidebar();
 
   return (
@@ -910,8 +286,8 @@ function SidebarTrigger({
       data-sidebar="trigger"
       data-slot="sidebar-trigger"
       variant="ghost"
-      size="icon"
-      className={cn("size-7", className)}
+      size="icon-sm"
+      className={cn(className)}
       onClick={(event) => {
         onClick?.(event);
         toggleSidebar();
@@ -924,44 +300,12 @@ function SidebarTrigger({
   );
 }
 
+type SidebarRailProps = React.ComponentProps<"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
+ * Invisible rail element on sidebar edge for drag-to-resize interaction.
  */
-function SidebarRail({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"button">) {
+function SidebarRail({ className, ...props }: SidebarRailProps) {
   const { toggleSidebar } = useSidebar();
 
   return (
@@ -986,69 +330,17 @@ function SidebarRail({
   );
 }
 
+type SidebarInsetProps = React.ComponentProps<"main">;
+
 /**
- * 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
+ * Main content area that sits beside the sidebar. Automatically adjusts margins based on sidebar state.
  */
-function SidebarInset({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"main">) {
+function SidebarInset({ className, ...props }: SidebarInsetProps) {
   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",
+        "bg-background 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 relative flex w-full flex-1 flex-col",
         className,
       )}
       {...props}
@@ -1056,54 +348,12 @@ function SidebarInset({
   );
 }
 
+type SidebarInputProps = React.ComponentProps<typeof Input>;
+
 /**
- * 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
+ * Styled input for sidebar search/filter functionality.
  */
-function SidebarInput({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<typeof Input>) {
+function SidebarInput({ className, ...props }: SidebarInputProps) {
   return (
     <Input
       data-slot="sidebar-input"
@@ -1114,208 +364,44 @@ function SidebarInput({
   );
 }
 
+type SidebarHeaderProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Top section of sidebar for branding, app switcher, or global actions.
  */
-function SidebarHeader({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+function SidebarHeader({ className, ...props }: SidebarHeaderProps) {
   return (
     <div
       data-slot="sidebar-header"
       data-sidebar="header"
-      className={cn("flex flex-col gap-2 p-2", className)}
+      className={cn("gap-2 p-2 flex flex-col", className)}
       {...props}
     />
   );
 }
 
+type SidebarFooterProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Bottom section of sidebar for user profile, settings, or secondary actions.
  */
-function SidebarFooter({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+function SidebarFooter({ className, ...props }: SidebarFooterProps) {
   return (
     <div
       data-slot="sidebar-footer"
       data-sidebar="footer"
-      className={cn("flex flex-col gap-2 p-2", className)}
+      className={cn("gap-2 p-2 flex flex-col", className)}
       {...props}
     />
   );
 }
 
+type SidebarSeparatorProps = React.ComponentProps<typeof Separator>;
+
 /**
- * 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
+ * Horizontal divider between sidebar sections.
  */
-function SidebarSeparator({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<typeof Separator>) {
+function SidebarSeparator({ className, ...props }: SidebarSeparatorProps) {
   return (
     <Separator
       data-slot="sidebar-separator"
@@ -1326,82 +412,18 @@ function SidebarSeparator({
   );
 }
 
+type SidebarContentProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Scrollable main content area of sidebar. Contains SidebarGroup components.
  */
-function SidebarContent({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+function SidebarContent({ className, ...props }: SidebarContentProps) {
   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",
+        "no-scrollbar gap-2 flex min-h-0 flex-1 flex-col overflow-auto group-data-[collapsible=icon]:overflow-hidden",
         className,
       )}
       {...props}
@@ -1409,452 +431,123 @@ function SidebarContent({
   );
 }
 
+type SidebarGroupProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Container for grouped menu items with optional label.
  */
-function SidebarGroup({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+function SidebarGroup({ className, ...props }: SidebarGroupProps) {
   return (
     <div
       data-slot="sidebar-group"
       data-sidebar="group"
-      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      className={cn("p-2 relative flex w-full min-w-0 flex-col", className)}
       {...props}
     />
   );
 }
 
+type SidebarGroupLabelProps = useRender.ComponentProps<"div"> &
+  React.ComponentProps<"div">;
+
 /**
- * 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
+ * Label heading for a sidebar group. Fades out when sidebar collapses to icon mode.
  */
 function SidebarGroupLabel({
   className,
-  asChild = false,
+  render,
   ...props
-}: {
-  className?: string;
-  asChild?: boolean;
-} & React.ComponentProps<"div">) {
-  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}
-    />
-  );
+}: SidebarGroupLabelProps) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(
+          "text-sidebar-foreground/70 ring-sidebar-ring h-8 rounded-md px-2 text-xs font-medium transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 flex shrink-0 items-center outline-hidden [&>svg]:shrink-0",
+          className,
+        ),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-label",
+      sidebar: "group-label",
+    },
+  });
 }
 
+type SidebarGroupActionProps = useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button">;
+
 /**
- * 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
+ * Action button displayed in top-right of group (e.g., add, expand all).
  */
 function SidebarGroupAction({
   className,
-  asChild = false,
+  render,
   ...props
-}: {
-  className?: string;
-  asChild?: boolean;
-} & React.ComponentProps<"button">) {
-  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}
-    />
-  );
+}: SidebarGroupActionProps) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(
+          "text-sidebar-foreground ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground absolute top-3.5 right-3 w-5 rounded-md p-0 focus-visible:ring-2 [&>svg]:size-4 flex aspect-square items-center justify-center outline-hidden transition-transform [&>svg]:shrink-0 after:absolute after:-inset-2 md:after:hidden group-data-[collapsible=icon]:hidden",
+          className,
+        ),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-action",
+      sidebar: "group-action",
+    },
+  });
 }
 
+type SidebarGroupContentProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Container for menu items within a group.
  */
 function SidebarGroupContent({
   className,
   ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+}: SidebarGroupContentProps) {
   return (
     <div
       data-slot="sidebar-group-content"
       data-sidebar="group-content"
-      className={cn("w-full text-sm", className)}
+      className={cn("text-sm w-full", className)}
       {...props}
     />
   );
 }
 
+type SidebarMenuProps = React.ComponentProps<"ul">;
+
 /**
- * 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
+ * Unordered list container for sidebar menu items.
  */
-function SidebarMenu({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"ul">) {
+function SidebarMenu({ className, ...props }: SidebarMenuProps) {
   return (
     <ul
       data-slot="sidebar-menu"
       data-sidebar="menu"
-      className={cn("flex w-full min-w-0 flex-col gap-1", className)}
+      className={cn("gap-1 flex w-full min-w-0 flex-col", className)}
       {...props}
     />
   );
 }
 
+type SidebarMenuItemProps = React.ComponentProps<"li">;
+
 /**
- * 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
+ * List item wrapper for a single menu entry.
  */
-function SidebarMenuItem({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"li">) {
+function SidebarMenuItem({ className, ...props }: SidebarMenuItemProps) {
   return (
     <li
       data-slot="sidebar-menu-item"
@@ -1865,24 +558,14 @@ function SidebarMenuItem({
   );
 }
 
-/**
- * SidebarMenuButton variant configuration for visual appearances and sizes
- *
- * @variant default - Standard menu button with subtle hover states
- * @variant outline - Button with border background that highlights on interaction
- *
- * @size default - Standard button height (h-8) with text-sm
- * @size sm - Compact button height (h-7) with text-xs for dense layouts
- * @size lg - Large button height (h-12) with text-sm, collapses to icon padding when sidebar is collapsed
- */
 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",
+  "ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground active:bg-sidebar-accent active:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground gap-2 rounded-md p-2 text-left text-sm transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! focus-visible:ring-2 data-active:font-medium peer/menu-button flex w-full items-center overflow-hidden outline-hidden group/menu-button 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",
   {
     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))]",
+          "bg-background hover:bg-sidebar-accent hover:text-sidebar-accent-foreground shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
       },
       size: {
         default: "h-8 text-sm",
@@ -1897,133 +580,46 @@ const sidebarMenuButtonVariants = cva(
   },
 );
 
+type SidebarMenuButtonProps = useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    /** Mark as active/current page. */
+    isActive?: boolean;
+    /** Tooltip content shown when sidebar is collapsed. */
+    tooltip?: string | React.ComponentProps<typeof TooltipContent>;
+  } & VariantProps<typeof sidebarMenuButtonVariants>;
+
 /**
- * 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
+ * Clickable button for sidebar menu item. Supports variants, sizes, active state, and tooltips.
  */
 function SidebarMenuButton({
-  asChild = false,
+  render,
   isActive = false,
   variant = "default",
   size = "default",
   tooltip,
   className,
   ...props
-}: {
-  asChild?: boolean;
-  isActive?: boolean;
-  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
-  className?: string;
-} & VariantProps<typeof sidebarMenuButtonVariants> &
-  React.ComponentProps<"button">) {
-  const Comp = asChild ? Slot : "button";
+}: SidebarMenuButtonProps) {
   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}
-    />
-  );
+  const comp = useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(sidebarMenuButtonVariants({ variant, size }), className),
+      },
+      props,
+    ),
+    render: !tooltip ? render : TooltipTrigger,
+    state: {
+      slot: "sidebar-menu-button",
+      sidebar: "menu-button",
+      size,
+      active: isActive,
+    },
+  });
 
   if (!tooltip) {
-    return button;
+    return comp;
   }
 
   if (typeof tooltip === "string") {
@@ -2034,7 +630,7 @@ function SidebarMenuButton({
 
   return (
     <Tooltip>
-      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      {comp}
       <TooltipContent
         side="right"
         align="center"
@@ -2045,195 +641,54 @@ function SidebarMenuButton({
   );
 }
 
+type SidebarMenuActionProps = useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    /** Only show on hover/focus. @default false */
+    showOnHover?: boolean;
+  };
+
 /**
- * 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
+ * Secondary action button for menu item (e.g., delete, edit). Positioned on right side.
  */
 function SidebarMenuAction({
   className,
-  asChild = false,
+  render,
   showOnHover = false,
   ...props
-}: {
-  className?: string;
-  asChild?: boolean;
-  showOnHover?: boolean;
-} & React.ComponentProps<"button">) {
-  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}
-    />
-  );
+}: SidebarMenuActionProps) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        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 aspect-square w-5 rounded-md p-0 peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 focus-visible:ring-2 [&>svg]:size-4 flex items-center justify-center outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 md:after:hidden [&>svg]:shrink-0",
+          showOnHover &&
+            "peer-data-active/menu-button:text-sidebar-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-open:opacity-100 md:opacity-0",
+          className,
+        ),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-action",
+      sidebar: "menu-action",
+    },
+  });
 }
 
+type SidebarMenuBadgeProps = React.ComponentProps<"div">;
+
 /**
- * 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
+ * Badge/counter displayed on right side of menu item (e.g., notification count).
  */
-function SidebarMenuBadge({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"div">) {
+function SidebarMenuBadge({ className, ...props }: SidebarMenuBadgeProps) {
   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",
+        "text-sidebar-foreground peer-hover/menu-button:text-sidebar-accent-foreground peer-data-active/menu-button:text-sidebar-accent-foreground pointer-events-none absolute right-1 flex h-5 min-w-5 rounded-md px-1 text-xs font-medium peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 flex items-center justify-center tabular-nums select-none group-data-[collapsible=icon]:hidden",
         className,
       )}
       {...props}
@@ -2241,94 +696,29 @@ function SidebarMenuBadge({
   );
 }
 
+type SidebarMenuSkeletonProps = React.ComponentProps<"div"> & {
+  /** Show icon skeleton. @default false */
+  showIcon?: boolean;
+};
+
 /**
- * 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
+ * Loading skeleton placeholder for menu item with randomized width.
  */
 function SidebarMenuSkeleton({
   className,
   showIcon = false,
   ...props
-}: {
-  className?: string;
-  showIcon?: boolean;
-} & React.ComponentProps<"div">) {
+}: SidebarMenuSkeletonProps) {
   // Random width between 50 to 90%.
-  const width = `${Math.floor(Math.random() * 40) + 50}%`;
+  const [width] = React.useState(() => {
+    return `${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)}
+      className={cn("h-8 gap-2 rounded-md px-2 flex items-center", className)}
       {...props}
     >
       {showIcon && (
@@ -2350,98 +740,18 @@ function SidebarMenuSkeleton({
   );
 }
 
+type SidebarMenuSubProps = React.ComponentProps<"ul">;
+
 /**
- * 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
+ * Nested submenu list with indented border. Place inside SidebarMenuItem.
  */
-function SidebarMenuSub({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"ul">) {
+function SidebarMenuSub({ className, ...props }: SidebarMenuSubProps) {
   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",
+        "border-sidebar-border mx-3.5 translate-x-px gap-1 border-l px-2.5 py-0.5 group-data-[collapsible=icon]:hidden flex min-w-0 flex-col",
         className,
       )}
       {...props}
@@ -2449,58 +759,12 @@ function SidebarMenuSub({
   );
 }
 
+type SidebarMenuSubItemProps = React.ComponentProps<"li">;
+
 /**
- * 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
+ * List item wrapper for submenu entry.
  */
-function SidebarMenuSubItem({
-  className,
-  ...props
-}: {
-  className?: string;
-} & React.ComponentProps<"li">) {
+function SidebarMenuSubItem({ className, ...props }: SidebarMenuSubItemProps) {
   return (
     <li
       data-slot="sidebar-menu-sub-item"
@@ -2511,118 +775,43 @@ function SidebarMenuSubItem({
   );
 }
 
+type SidebarMenuSubButtonProps = useRender.ComponentProps<"a"> &
+  React.ComponentProps<"a"> & {
+    /** Size variant. @default "md" */
+    size?: "sm" | "md";
+    /** Mark as active/current page. */
+    isActive?: boolean;
+  };
+
 /**
- * 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
+ * Link button for submenu item. Defaults to anchor tag.
  */
 function SidebarMenuSubButton({
-  asChild = false,
+  render,
   size = "md",
   isActive = false,
   className,
   ...props
-}: {
-  asChild?: boolean;
-  size?: "sm" | "md";
-  isActive?: boolean;
-  className?: string;
-} & React.ComponentProps<"a">) {
-  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}
-    />
-  );
+}: SidebarMenuSubButtonProps) {
+  return useRender({
+    defaultTagName: "a",
+    props: mergeProps<"a">(
+      {
+        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 data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground h-7 gap-2 rounded-md px-2 focus-visible:ring-2 data-[size=md]:text-sm data-[size=sm]:text-xs [&>svg]:size-4 flex min-w-0 -translate-x-px items-center overflow-hidden outline-hidden group-data-[collapsible=icon]:hidden disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:shrink-0",
+          className,
+        ),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-sub-button",
+      sidebar: "menu-sub-button",
+      size,
+      active: isActive,
+    },
+  });
 }
 
 export {
@@ -2650,4 +839,27 @@ export {
   SidebarSeparator,
   SidebarTrigger,
   useSidebar,
+  type SidebarProps,
+  type SidebarContentProps,
+  type SidebarFooterProps,
+  type SidebarGroupProps,
+  type SidebarGroupActionProps,
+  type SidebarGroupContentProps,
+  type SidebarGroupLabelProps,
+  type SidebarHeaderProps,
+  type SidebarInputProps,
+  type SidebarInsetProps,
+  type SidebarMenuProps,
+  type SidebarMenuActionProps,
+  type SidebarMenuBadgeProps,
+  type SidebarMenuButtonProps,
+  type SidebarMenuItemProps,
+  type SidebarMenuSkeletonProps,
+  type SidebarMenuSubProps,
+  type SidebarMenuSubButtonProps,
+  type SidebarMenuSubItemProps,
+  type SidebarProviderProps,
+  type SidebarRailProps,
+  type SidebarSeparatorProps,
+  type SidebarTriggerProps,
 };