@teamix-evo/ui 0.2.0 → 0.4.0

package/src/components/sidebar/sidebar.tsx

@@ -1,38 +1,94 @@
+/**
+ * Sidebar — shadcn 完整版 25 primitives.
+ *
+ * **arbitrary value 豁免说明**:本组件少量使用 Tailwind arbitrary value
+ * (`w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]` 等),原因:
+ *
+ * 1. Sidebar 折叠态需要在 `group-data-[collapsible=icon]` 选择器下响应父级 data
+ *    属性 — 这只能通过 Tailwind selector 实现,无法 inline `style` 替代;
+ * 2. floating/inset variant 的 gap/container 宽度是 `--sidebar-width-icon + p-2`
+ *    的合成值,Tailwind 标尺无法直接表达;
+ * 3. MenuButton outline variant 用 `box-shadow: 0 0 0 1px ...` 模拟 1px 边框
+ *    避免占用尺寸,这是 shadcn outline 风格的核心实现技术。
+ *
+ * 这些 arbitrary value 是 Sidebar 复合组件的结构性必要,与 ADR 0008 视觉规则
+ * 的本意(避免任意像素值/任意色值)相符 — 此处的值都是 token 引用,不是
+ * 硬编码像素或色值。本文件单独豁免 `teamix-evo/no-arbitrary-tw-value`。
+ */
+/* eslint-disable teamix-evo/no-arbitrary-tw-value */
 import * as React from 'react';
 import { Slot } from '@radix-ui/react-slot';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { PanelLeft } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
+import { useIsMobile } from '@/hooks/use-mobile';
 import { Button } from '@/components/button/button';
+import { Input } from '@/components/input/input';
 import { Separator } from '@/components/separator/separator';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from '@/components/sheet/sheet';
+import { Skeleton } from '@/components/skeleton/skeleton';
+import {
+  TooltipContent,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+} from '@/components/tooltip/tooltip';
 
-// ─── Context + Provider ──────────────────────────────────────────────────────
+const SIDEBAR_COOKIE_NAME = 'sidebar_state';
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+const SIDEBAR_WIDTH = '16rem';
+const SIDEBAR_WIDTH_MOBILE = '18rem';
+const SIDEBAR_WIDTH_ICON = '3rem';
+const SIDEBAR_KEYBOARD_SHORTCUT = 'b';
 
 interface SidebarContextValue {
+  state: 'expanded' | 'collapsed';
   open: boolean;
   setOpen: (open: boolean) => void;
-  toggle: () => void;
+  openMobile: boolean;
+  setOpenMobile: (open: boolean) => void;
+  isMobile: boolean;
+  toggleSidebar: () => void;
+  /**
+   * 嵌入模式 — true 时 Sidebar 的 sidebar-container 用 `position: relative; height: 100%`
+   * 替代默认的 `position: fixed; inset-y-0; height: 100svh`,让 sidebar 跟外层 header / 横向 flex
+   * 容器共存(常用于 PageShell 内嵌)。
+   * @default false
+   */
+  embedded: boolean;
 }
 
 const SidebarContext = React.createContext<SidebarContextValue | null>(null);
 
-export function useSidebar() {
+export function useSidebar(): SidebarContextValue {
   const ctx = React.useContext(SidebarContext);
   if (!ctx) {
-    throw new Error('useSidebar must be used within <SidebarProvider>');
+    throw new Error('useSidebar must be used within a SidebarProvider.');
   }
   return ctx;
 }
 
+// ─── Provider ──────────────────────────────────────────────────────────────
+
 export interface SidebarProviderProps
   extends React.HTMLAttributes<HTMLDivElement> {
-  /** 受控 open 状态。 */
-  open?: boolean;
-  /** uncontrolled 初始状态。 @default true */
   defaultOpen?: boolean;
-  /** open 状态变化回调。 */
+  open?: boolean;
   onOpenChange?: (open: boolean) => void;
+  /**
+   * 嵌入模式 — true 时下游 `<Sidebar>` 的 sidebar-container 走 `position: relative + h-full`,
+   * 让 sidebar 嵌入到外层布局(如 PageShell 的 header 下 + 横向 flex 容器内),而不是默认贴
+   * viewport 全屏。默认 false(保留原版"贴 viewport 边" shadcn 行为)。
+   * @default false
+   */
+  embedded?: boolean;
 }
 
 const SidebarProvider = React.forwardRef<HTMLDivElement, SidebarProviderProps>(
@@ -40,129 +96,323 @@ const SidebarProvider = React.forwardRef<HTMLDivElement, SidebarProviderProps>(
     {
       defaultOpen = true,
       open: openProp,
-      onOpenChange,
+      onOpenChange: setOpenProp,
+      embedded = false,
       className,
+      style,
       children,
       ...props
     },
     ref,
   ) => {
-    const [internal, setInternal] = React.useState(defaultOpen);
-    const isControlled = openProp !== undefined;
-    const open = isControlled ? (openProp as boolean) : internal;
+    const isMobile = useIsMobile();
+    const [openMobile, setOpenMobile] = React.useState(false);
 
+    const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+    const open = openProp ?? internalOpen;
     const setOpen = React.useCallback(
-      (next: boolean) => {
-        if (!isControlled) setInternal(next);
-        onOpenChange?.(next);
+      (value: boolean | ((value: boolean) => boolean)) => {
+        const openState = typeof value === 'function' ? value(open) : value;
+        if (setOpenProp) {
+          setOpenProp(openState);
+        } else {
+          setInternalOpen(openState);
+        }
+        document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`;
       },
-      [isControlled, onOpenChange],
+      [setOpenProp, open],
     );
-    const toggle = React.useCallback(() => setOpen(!open), [open, setOpen]);
 
-    const value = React.useMemo<SidebarContextValue>(
-      () => ({ open, setOpen, toggle }),
-      [open, setOpen, toggle],
+    const toggleSidebar = React.useCallback(() => {
+      return isMobile
+        ? setOpenMobile((current) => !current)
+        : setOpen((current) => !current);
+    }, [isMobile, setOpen, setOpenMobile]);
+
+    React.useEffect(() => {
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (
+          event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+          (event.metaKey || event.ctrlKey)
+        ) {
+          event.preventDefault();
+          toggleSidebar();
+        }
+      };
+      window.addEventListener('keydown', handleKeyDown);
+      return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [toggleSidebar]);
+
+    const state: 'expanded' | 'collapsed' = open ? 'expanded' : 'collapsed';
+
+    const contextValue = React.useMemo<SidebarContextValue>(
+      () => ({
+        state,
+        open,
+        setOpen,
+        isMobile,
+        openMobile,
+        setOpenMobile,
+        toggleSidebar,
+        embedded,
+      }),
+      [
+        state,
+        open,
+        setOpen,
+        isMobile,
+        openMobile,
+        setOpenMobile,
+        toggleSidebar,
+        embedded,
+      ],
     );
 
     return (
-      <SidebarContext.Provider value={value}>
-        <div
-          ref={ref}
-          data-state={open ? 'expanded' : 'collapsed'}
-          className={cn(
-            'group/sidebar-wrapper flex min-h-svh w-full',
-            className,
-          )}
-          {...props}
-        >
-          {children}
-        </div>
+      <SidebarContext.Provider value={contextValue}>
+        <TooltipProvider delayDuration={0}>
+          <div
+            ref={ref}
+            data-slot="sidebar-wrapper"
+            style={
+              {
+                '--sidebar-width': SIDEBAR_WIDTH,
+                '--sidebar-width-icon': SIDEBAR_WIDTH_ICON,
+                ...style,
+              } as React.CSSProperties
+            }
+            className={cn(
+              'group/sidebar-wrapper has-data-[variant=inset]:bg-sidebar flex min-h-svh w-full',
+              className,
+            )}
+            {...props}
+          >
+            {children}
+          </div>
+        </TooltipProvider>
       </SidebarContext.Provider>
     );
   },
 );
 SidebarProvider.displayName = 'SidebarProvider';
 
-// ─── Main Sidebar container ───────────────────────────────────────────────────
+// ─── Main Sidebar container ────────────────────────────────────────────────
 
-const sidebarVariants = cva(
-  'flex h-svh shrink-0 flex-col border-r bg-background transition-[width] duration-200 ease-linear',
-  {
-    variants: {
-      side: {
-        left: 'border-r',
-        right: 'border-l border-r-0 order-last',
-      },
-    },
-    defaultVariants: { side: 'left' },
-  },
-);
-
-export interface SidebarProps
-  extends React.HTMLAttributes<HTMLElement>,
-    VariantProps<typeof sidebarVariants> {
-  /**
-   * 侧边方向。
-   * @default "left"
-   */
+export interface SidebarProps extends React.HTMLAttributes<HTMLDivElement> {
   side?: 'left' | 'right';
-  /**
-   * 折叠模式 — `icon` 折叠后只剩图标列(64px);`offcanvas` 完全收起(0px)。
-   * @default "icon"
-   */
-  collapsible?: 'icon' | 'offcanvas' | 'none';
-  /** 展开宽度。 @default "16rem" */
-  width?: string;
-  /** 折叠后宽度(`collapsible="icon"` 时生效)。 @default "3rem" */
-  collapsedWidth?: string;
+  variant?: 'sidebar' | 'floating' | 'inset';
+  collapsible?: 'offcanvas' | 'icon' | 'none';
 }
 
-const Sidebar = React.forwardRef<HTMLElement, SidebarProps>(
+const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
   (
     {
       side = 'left',
-      collapsible = 'icon',
-      width = '16rem',
-      collapsedWidth = '3rem',
+      variant = 'sidebar',
+      collapsible = 'offcanvas',
       className,
-      style,
       children,
       ...props
     },
     ref,
   ) => {
-    const { open } = useSidebar();
-    const w =
-      collapsible === 'none'
-        ? width
-        : open
-          ? width
-          : collapsible === 'icon'
-            ? collapsedWidth
-            : '0px';
+    const { isMobile, state, openMobile, setOpenMobile, embedded } =
+      useSidebar();
+
+    if (collapsible === 'none') {
+      return (
+        <div
+          ref={ref}
+          data-slot="sidebar"
+          className={cn(
+            'bg-sidebar text-sidebar-foreground flex h-full w-(--sidebar-width) flex-col',
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </div>
+      );
+    }
+
+    if (isMobile) {
+      return (
+        <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+          <SheetContent
+            data-sidebar="sidebar"
+            data-slot="sidebar"
+            data-mobile="true"
+            className="bg-sidebar text-sidebar-foreground w-(--sidebar-width) p-0 [&>button]:hidden"
+            style={
+              {
+                '--sidebar-width': SIDEBAR_WIDTH_MOBILE,
+              } as React.CSSProperties
+            }
+            side={side}
+          >
+            <SheetHeader className="sr-only">
+              <SheetTitle>Sidebar</SheetTitle>
+              <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+            </SheetHeader>
+            <div className="flex h-full w-full flex-col">{children}</div>
+          </SheetContent>
+        </Sheet>
+      );
+    }
+
     return (
-      <aside
+      <div
         ref={ref}
-        data-state={open ? 'expanded' : 'collapsed'}
-        data-collapsible={collapsible}
+        className="group peer text-sidebar-foreground hidden md:block"
+        data-state={state}
+        data-collapsible={state === 'collapsed' ? collapsible : ''}
+        data-variant={variant}
         data-side={side}
-        style={{ width: w, ...style }}
-        className={cn(
-          sidebarVariants({ side }),
-          collapsible === 'offcanvas' && !open && 'overflow-hidden',
-          className,
-        )}
-        {...props}
+        data-slot="sidebar"
       >
-        {children}
-      </aside>
+        {/* sidebar gap on desktop — 仅 fixed 模式需要;embedded 模式下 sidebar-container
+            自身参与横向 flex,无需占位 */}
+        {!embedded && (
+          <div
+            data-slot="sidebar-gap"
+            className={cn(
+              'relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear',
+              'group-data-[collapsible=offcanvas]:w-0',
+              'group-data-[side=right]:rotate-180',
+              variant === 'floating' || variant === 'inset'
+                ? 'group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]'
+                : 'group-data-[collapsible=icon]:w-(--sidebar-width-icon)',
+            )}
+          />
+        )}
+        <div
+          data-slot="sidebar-container"
+          data-side={side}
+          className={cn(
+            embedded
+              ? [
+                  'relative hidden h-full w-(--sidebar-width) transition-[width] duration-200 ease-linear md:flex',
+                  // embedded 模式无 fixed,offcanvas 折叠改用宽度收 0(fixed 版本是滑走)
+                  'group-data-[collapsible=offcanvas]:w-0 overflow-hidden',
+                ]
+              : [
+                  'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear md:flex',
+                  'data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]',
+                  'data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)]',
+                ],
+            variant === 'floating' || variant === 'inset'
+              ? 'p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]'
+              : 'group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l border-sidebar-border',
+            className,
+          )}
+          {...props}
+        >
+          <div
+            data-sidebar="sidebar"
+            data-slot="sidebar-inner"
+            className="bg-sidebar group-data-[variant=floating]:border-sidebar-border group-data-[variant=floating]:ring-sidebar-border flex size-full flex-col group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:border group-data-[variant=floating]:shadow-sm"
+          >
+            {children}
+          </div>
+        </div>
+      </div>
     );
   },
 );
 Sidebar.displayName = 'Sidebar';
 
-// ─── Sub-components ──────────────────────────────────────────────────────────
+// ─── Trigger / Rail / Inset / Input ────────────────────────────────────────
+
+const SidebarTrigger = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentProps<typeof Button>
+>(({ className, onClick, ...props }, ref) => {
+  const { toggleSidebar } = useSidebar();
+  return (
+    <Button
+      ref={ref}
+      data-sidebar="trigger"
+      data-slot="sidebar-trigger"
+      variant="ghost"
+      size="icon"
+      className={cn('size-7', className)}
+      onClick={(event) => {
+        onClick?.(event);
+        toggleSidebar();
+      }}
+      aria-label="Toggle Sidebar"
+      {...props}
+    >
+      <PanelLeft />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  );
+});
+SidebarTrigger.displayName = 'SidebarTrigger';
+
+const SidebarRail = React.forwardRef<
+  HTMLButtonElement,
+  React.ButtonHTMLAttributes<HTMLButtonElement>
+>(({ className, ...props }, ref) => {
+  const { toggleSidebar } = useSidebar();
+  return (
+    <button
+      ref={ref}
+      type="button"
+      data-sidebar="rail"
+      data-slot="sidebar-rail"
+      aria-label="Toggle Sidebar"
+      tabIndex={-1}
+      onClick={toggleSidebar}
+      title="Toggle Sidebar"
+      className={cn(
+        'hover:after:bg-sidebar-border absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 sm:flex',
+        'after:absolute after:inset-y-0 after:start-1/2 after:w-0.5',
+        'in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize',
+        '[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize',
+        'group-data-[collapsible=offcanvas]:hover:bg-sidebar group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full',
+        '[[data-side=left][data-collapsible=offcanvas]_&]:-right-2',
+        '[[data-side=right][data-collapsible=offcanvas]_&]:-left-2',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+SidebarRail.displayName = 'SidebarRail';
+
+const SidebarInset = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, ...props }, ref) => (
+  <main
+    ref={ref}
+    data-slot="sidebar-inset"
+    className={cn(
+      'bg-background relative flex w-full flex-1 flex-col',
+      'md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2',
+      className,
+    )}
+    {...(props as React.HTMLAttributes<HTMLElement>)}
+  />
+));
+SidebarInset.displayName = 'SidebarInset';
+
+const SidebarInput = React.forwardRef<
+  HTMLInputElement,
+  React.ComponentProps<typeof Input>
+>(({ className, ...props }, ref) => (
+  <Input
+    ref={ref}
+    data-slot="sidebar-input"
+    data-sidebar="input"
+    className={cn('bg-background h-8 w-full shadow-none', className)}
+    {...props}
+  />
+));
+SidebarInput.displayName = 'SidebarInput';
+
+// ─── Header / Footer / Separator / Content ──────────────────────────────────
 
 const SidebarHeader = React.forwardRef<
   HTMLDivElement,
@@ -170,6 +420,8 @@ const SidebarHeader = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
+    data-slot="sidebar-header"
+    data-sidebar="header"
     className={cn('flex flex-col gap-2 p-2', className)}
     {...props}
   />
@@ -182,7 +434,9 @@ const SidebarFooter = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('mt-auto flex flex-col gap-2 p-2', className)}
+    data-slot="sidebar-footer"
+    data-sidebar="footer"
+    className={cn('flex flex-col gap-2 p-2', className)}
     {...props}
   />
 ));
@@ -194,7 +448,9 @@ const SidebarSeparator = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <Separator
     ref={ref}
-    className={cn('mx-2 w-auto bg-border', className)}
+    data-slot="sidebar-separator"
+    data-sidebar="separator"
+    className={cn('bg-sidebar-border mx-2 w-auto', className)}
     {...props}
   />
 ));
@@ -206,8 +462,10 @@ const SidebarContent = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
+    data-slot="sidebar-content"
+    data-sidebar="content"
     className={cn(
-      'flex min-h-0 flex-1 flex-col gap-2 overflow-auto p-2',
+      'no-scrollbar flex min-h-0 flex-1 flex-col gap-0 overflow-auto group-data-[collapsible=icon]:overflow-hidden',
       className,
     )}
     {...props}
@@ -215,29 +473,39 @@ const SidebarContent = React.forwardRef<
 ));
 SidebarContent.displayName = 'SidebarContent';
 
+// ─── Group / GroupLabel / GroupAction / GroupContent ────────────────────────
+
 const SidebarGroup = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement>
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex w-full min-w-0 flex-col gap-1', className)}
+    data-slot="sidebar-group"
+    data-sidebar="group"
+    className={cn('relative flex w-full min-w-0 flex-col p-2', className)}
     {...props}
   />
 ));
 SidebarGroup.displayName = 'SidebarGroup';
 
+export interface SidebarGroupLabelProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  asChild?: boolean;
+}
+
 const SidebarGroupLabel = React.forwardRef<
   HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => {
-  const { open } = useSidebar();
+  SidebarGroupLabelProps
+>(({ className, asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : 'div';
   return (
-    <div
+    <Comp
       ref={ref}
+      data-slot="sidebar-group-label"
+      data-sidebar="group-label"
       className={cn(
-        'flex h-8 shrink-0 items-center px-2 text-xs font-medium text-muted-foreground',
-        !open && 'opacity-0',
+        'text-sidebar-foreground/70 ring-sidebar-ring flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium transition-[margin,opacity] duration-200 ease-linear outline-hidden group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0',
         className,
       )}
       {...props}
@@ -246,12 +514,56 @@ const SidebarGroupLabel = React.forwardRef<
 });
 SidebarGroupLabel.displayName = 'SidebarGroupLabel';
 
+export interface SidebarGroupActionProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  asChild?: boolean;
+}
+
+const SidebarGroupAction = React.forwardRef<
+  HTMLButtonElement,
+  SidebarGroupActionProps
+>(({ className, asChild = false, ...props }, ref) => {
+  const Comp = asChild ? Slot : 'button';
+  return (
+    <Comp
+      ref={ref}
+      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 transition-transform outline-hidden focus-visible:ring-2 group-data-[collapsible=icon]:hidden [&>svg]:size-4 [&>svg]:shrink-0',
+        'after:absolute after:-inset-2 md:after:hidden',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+SidebarGroupAction.displayName = 'SidebarGroupAction';
+
+const SidebarGroupContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="sidebar-group-content"
+    data-sidebar="group-content"
+    className={cn('w-full text-xs', className)}
+    {...props}
+  />
+));
+SidebarGroupContent.displayName = 'SidebarGroupContent';
+
+// ─── Menu / MenuItem / MenuButton ──────────────────────────────────────────
+
 const SidebarMenu = React.forwardRef<
   HTMLUListElement,
   React.HTMLAttributes<HTMLUListElement>
 >(({ className, ...props }, ref) => (
   <ul
     ref={ref}
+    data-slot="sidebar-menu"
+    data-sidebar="menu"
     className={cn('flex w-full min-w-0 flex-col gap-1', className)}
     {...props}
   />
@@ -262,90 +574,280 @@ const SidebarMenuItem = React.forwardRef<
   HTMLLIElement,
   React.HTMLAttributes<HTMLLIElement>
 >(({ className, ...props }, ref) => (
-  <li ref={ref} className={cn('group/menu-item', className)} {...props} />
+  <li
+    ref={ref}
+    data-slot="sidebar-menu-item"
+    data-sidebar="menu-item"
+    className={cn('group/menu-item relative', className)}
+    {...props}
+  />
 ));
 SidebarMenuItem.displayName = 'SidebarMenuItem';
 
+const sidebarMenuButtonVariants = cva(
+  'peer/menu-button group/menu-button 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:font-medium data-active:text-sidebar-accent-foreground data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-xs outline-hidden transition-[width,height,padding] focus-visible:ring-2 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 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! [&>span:last-child]:truncate [&_svg]:size-4 [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+        outline:
+          'bg-background 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-xs',
+        sm: 'h-7 text-xs',
+        lg: 'h-12 text-sm group-data-[collapsible=icon]:p-0!',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  },
+);
+
 export interface SidebarMenuButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  /** 当前激活态(高亮显示)。 */
-  isActive?: boolean;
-  /** 用 Slot 渲染为子元素(配合 router Link)。 */
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof sidebarMenuButtonVariants> {
   asChild?: boolean;
+  isActive?: boolean;
+  tooltip?: string | React.ComponentProps<typeof TooltipContent>;
 }
 
 const SidebarMenuButton = React.forwardRef<
   HTMLButtonElement,
   SidebarMenuButtonProps
->(({ className, isActive, asChild, ...props }, ref) => {
+>(
+  (
+    {
+      asChild = false,
+      isActive = false,
+      variant = 'default',
+      size = 'default',
+      tooltip,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp = asChild ? Slot : 'button';
+    const { isMobile, state } = useSidebar();
+
+    const button = (
+      <Comp
+        ref={ref}
+        data-slot="sidebar-menu-button"
+        data-sidebar="menu-button"
+        data-size={size}
+        data-active={isActive ? 'true' : undefined}
+        className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+        {...props}
+      />
+    );
+
+    if (!tooltip) {
+      return button;
+    }
+
+    const tooltipProps =
+      typeof tooltip === 'string' ? { children: tooltip } : tooltip;
+
+    return (
+      <TooltipRoot>
+        <TooltipTrigger asChild>{button}</TooltipTrigger>
+        <TooltipContent
+          side="right"
+          align="center"
+          hidden={state !== 'collapsed' || isMobile}
+          {...tooltipProps}
+        />
+      </TooltipRoot>
+    );
+  },
+);
+SidebarMenuButton.displayName = 'SidebarMenuButton';
+
+// ─── MenuAction / MenuBadge / MenuSkeleton ─────────────────────────────────
+
+export interface SidebarMenuActionProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  asChild?: boolean;
+  showOnHover?: boolean;
+}
+
+const SidebarMenuAction = React.forwardRef<
+  HTMLButtonElement,
+  SidebarMenuActionProps
+>(({ className, asChild = false, showOnHover = false, ...props }, ref) => {
   const Comp = asChild ? Slot : 'button';
   return (
     <Comp
       ref={ref}
-      data-active={isActive ? 'true' : undefined}
+      data-slot="sidebar-menu-action"
+      data-sidebar="menu-action"
       className={cn(
-        'flex h-8 w-full items-center gap-2 overflow-hidden rounded-md px-2 text-left text-sm outline-none ring-ring transition hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0',
+        '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 transition-transform outline-hidden focus-visible:ring-2 group-data-[collapsible=icon]:hidden [&>svg]:size-4 [&>svg]:shrink-0',
+        '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',
+        showOnHover &&
+          'peer-data-active/menu-button:text-sidebar-accent-foreground group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 aria-expanded:opacity-100 md:opacity-0',
         className,
       )}
       {...props}
     />
   );
 });
-SidebarMenuButton.displayName = 'SidebarMenuButton';
+SidebarMenuAction.displayName = 'SidebarMenuAction';
 
-// ─── Trigger ─────────────────────────────────────────────────────────────────
+const SidebarMenuBadge = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="sidebar-menu-badge"
+    data-sidebar="menu-badge"
+    className={cn(
+      '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 items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums select-none group-data-[collapsible=icon]: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',
+      className,
+    )}
+    {...props}
+  />
+));
+SidebarMenuBadge.displayName = 'SidebarMenuBadge';
 
-const SidebarTrigger = React.forwardRef<
-  HTMLButtonElement,
-  React.ComponentPropsWithoutRef<typeof Button>
->(({ className, onClick, ...props }, ref) => {
-  const { toggle } = useSidebar();
+export interface SidebarMenuSkeletonProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  showIcon?: boolean;
+}
+
+const SidebarMenuSkeleton = React.forwardRef<
+  HTMLDivElement,
+  SidebarMenuSkeletonProps
+>(({ className, showIcon = false, ...props }, ref) => {
+  // Stable but varied widths so a stack of skeletons doesn't look uniform.
+  const [width] = React.useState(
+    () => `${Math.floor(Math.random() * 40) + 50}%`,
+  );
   return (
-    <Button
+    <div
       ref={ref}
-      variant="ghost"
-      size="icon"
-      className={cn('size-7', className)}
-      onClick={(e) => {
-        onClick?.(e);
-        toggle();
-      }}
-      aria-label="Toggle Sidebar"
+      data-slot="sidebar-menu-skeleton"
+      data-sidebar="menu-skeleton"
+      className={cn('flex h-8 items-center gap-2 rounded-md px-2', className)}
       {...props}
     >
-      <PanelLeft />
-      <span className="sr-only">Toggle Sidebar</span>
-    </Button>
+      {showIcon && (
+        <Skeleton
+          className="size-4 rounded-md"
+          data-sidebar="menu-skeleton-icon"
+        />
+      )}
+      <Skeleton
+        className="h-4 max-w-(--skeleton-width) flex-1"
+        data-sidebar="menu-skeleton-text"
+        style={
+          {
+            '--skeleton-width': width,
+          } as React.CSSProperties
+        }
+      />
+    </div>
   );
 });
-SidebarTrigger.displayName = 'SidebarTrigger';
+SidebarMenuSkeleton.displayName = 'SidebarMenuSkeleton';
 
-// ─── Inset(主内容区,与 Sidebar 配合)─────────────────────────────────────
+// ─── MenuSub / MenuSubItem / MenuSubButton ─────────────────────────────────
 
-const SidebarInset = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
+const SidebarMenuSub = React.forwardRef<
+  HTMLUListElement,
+  React.HTMLAttributes<HTMLUListElement>
 >(({ className, ...props }, ref) => (
-  <main
+  <ul
     ref={ref}
-    className={cn('relative flex min-h-svh flex-1 flex-col bg-background', className)}
-    {...(props as React.HTMLAttributes<HTMLElement>)}
+    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 border-l-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden',
+      className,
+    )}
+    {...props}
   />
 ));
-SidebarInset.displayName = 'SidebarInset';
+SidebarMenuSub.displayName = 'SidebarMenuSub';
+
+const SidebarMenuSubItem = React.forwardRef<
+  HTMLLIElement,
+  React.HTMLAttributes<HTMLLIElement>
+>(({ className, ...props }, ref) => (
+  <li
+    ref={ref}
+    data-slot="sidebar-menu-sub-item"
+    data-sidebar="menu-sub-item"
+    className={cn('group/menu-sub-item relative', className)}
+    {...props}
+  />
+));
+SidebarMenuSubItem.displayName = 'SidebarMenuSubItem';
+
+export interface SidebarMenuSubButtonProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  asChild?: boolean;
+  size?: 'sm' | 'md';
+  isActive?: boolean;
+}
+
+const SidebarMenuSubButton = React.forwardRef<
+  HTMLAnchorElement,
+  SidebarMenuSubButtonProps
+>(
+  (
+    { className, asChild = false, size = 'md', isActive = false, ...props },
+    ref,
+  ) => {
+    const Comp = asChild ? Slot : 'a';
+    return (
+      <Comp
+        ref={ref}
+        data-slot="sidebar-menu-sub-button"
+        data-sidebar="menu-sub-button"
+        data-size={size}
+        data-active={isActive ? 'true' : undefined}
+        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 data-active:bg-sidebar-accent data-active: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 group-data-[collapsible=icon]:hidden aria-disabled:pointer-events-none aria-disabled:opacity-50 [&>span:last-child]:truncate [&>svg]:text-sidebar-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0',
+          'data-[size=sm]:text-xs data-[size=md]:text-xs',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+SidebarMenuSubButton.displayName = 'SidebarMenuSubButton';
 
 export {
-  SidebarProvider,
   Sidebar,
-  SidebarHeader,
-  SidebarFooter,
-  SidebarSeparator,
   SidebarContent,
+  SidebarFooter,
   SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
   SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
   SidebarMenu,
-  SidebarMenuItem,
+  SidebarMenuAction,
+  SidebarMenuBadge,
   SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
   SidebarTrigger,
-  SidebarInset,
 };