Ordo UI
组件Layout & Shells

Sidebar

@mox-hub/ui 组件 · Layout & Shells · canonical

sidebar@mox-hub/uiLayout & Shellscanonicalsrc/components/sidebar.tsx

变体轴

side
startend逻辑方向,RTL 下自动镜像
variant
sidebarfloatinginset
collapsible
offcanvasiconnone
变体演示sidebar
收件箱

点击左上角按钮或按 Ctrl/Cmd + B 折叠侧栏。

窄屏自动切换为 Sheet;展开状态写入 localStorage。

Props API

Prop类型默认值说明
className*string——
children*ReactNode——

源码

packages/ui/src/components/sidebar.tsx
"use client"

import * as React from "react"
import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { PanelLeftIcon } from "lucide-react"

import { useDirection, useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Button } from "./button"
import { Input } from "./input"
import { Separator } from "./separator"
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetHeader,
  SheetTitle,
} from "./sheet"
import { Skeleton } from "./skeleton"
import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"

const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365
const SIDEBAR_MOBILE_BREAKPOINT = 768

type SidebarSide = "start" | "end"
type SidebarVariant = "sidebar" | "floating" | "inset"
type SidebarCollapsible = "offcanvas" | "icon" | "none"
type SidebarPersistence = "local" | "cookie" | false

interface SidebarContextValue {
  state: "expanded" | "collapsed"
  open: boolean
  setOpen: (open: boolean) => void
  openMobile: boolean
  setOpenMobile: React.Dispatch<React.SetStateAction<boolean>>
  isMobile: boolean
  toggleSidebar: () => void
  side: SidebarSide
  variant: SidebarVariant
  collapsible: SidebarCollapsible
  sidebarId: string
}

const SidebarContext = React.createContext<SidebarContextValue | null>(null)

function useSidebar() {
  const context = React.useContext(SidebarContext)
  if (!context) {
    throw new Error("useSidebar must be used within a SidebarProvider.")
  }
  return context
}

function useIsMobile() {
  const [isMobile, setIsMobile] = React.useState(false)

  React.useEffect(() => {
    if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
      return
    }

    const query = window.matchMedia(
      `(max-width: ${SIDEBAR_MOBILE_BREAKPOINT - 1}px)`
    )
    const onChange = () => setIsMobile(query.matches)

    onChange()
    if (typeof query.addEventListener === "function") {
      query.addEventListener("change", onChange)
      return () => query.removeEventListener("change", onChange)
    }

    // Safari < 14 / jsdom 的旧 matchMedia 实现
    query.addListener(onChange)
    return () => query.removeListener(onChange)
  }, [])

  return isMobile
}

function readPersisted(
  key: string,
  persistence: Exclude<SidebarPersistence, false>
): boolean | null {
  try {
    if (persistence === "local") {
      const value = window.localStorage.getItem(key)
      return value === null ? null : value === "true"
    }

    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
    const match = document.cookie.match(
      new RegExp(`(?:^|; )${escaped}=([^;]*)`)
    )
    return match ? match[1] === "true" : null
  } catch {
    return null
  }
}

function writePersisted(
  key: string,
  persistence: Exclude<SidebarPersistence, false>,
  open: boolean
) {
  try {
    if (persistence === "local") {
      window.localStorage.setItem(key, String(open))
      return
    }

    document.cookie = `${key}=${open}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}; samesite=lax`
  } catch {
    // 隐私模式 / 禁 cookie 时静默降级为会话内状态
  }
}

interface SidebarProviderProps extends React.ComponentProps<"div"> {
  defaultOpen?: boolean
  open?: boolean
  onOpenChange?: (open: boolean) => void
  side?: SidebarSide
  variant?: SidebarVariant
  collapsible?: SidebarCollapsible
  /** 展开宽度;number 按 px 处理。 */
  width?: string | number
  /** 折叠为图标轨时的宽度;number 按 px 处理。 */
  widthIcon?: string | number
  persistence?: SidebarPersistence
  storageKey?: string
  /** 是否启用 Ctrl/Cmd+B 切换。 */
  keyboardShortcut?: boolean
}

function SidebarProvider({
  defaultOpen = true,
  open: openProp,
  onOpenChange,
  side = "start",
  variant = "sidebar",
  collapsible = "offcanvas",
  width = "16rem",
  widthIcon = "3rem",
  persistence = "local",
  storageKey = "ordo-sidebar",
  keyboardShortcut = true,
  className,
  style,
  children,
  ...props
}: SidebarProviderProps) {
  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen)
  const [openMobile, setOpenMobile] = React.useState(false)
  const [hydrated, setHydrated] = React.useState(false)
  const isMobile = useIsMobile()
  const sidebarId = React.useId()

  const controlled = openProp !== undefined
  const open = controlled ? openProp : uncontrolledOpen

  const setOpen = React.useCallback(
    (next: boolean) => {
      if (!controlled) setUncontrolledOpen(next)
      onOpenChange?.(next)
    },
    [controlled, onOpenChange]
  )

  const toggleSidebar = React.useCallback(() => {
    if (isMobile) {
      setOpenMobile((value) => !value)
      return
    }
    setOpen(!open)
  }, [isMobile, open, setOpen])

  React.useEffect(() => {
    if (persistence === false) {
      setHydrated(true)
      return
    }

    const stored = readPersisted(storageKey, persistence)
    if (stored !== null && !controlled) setUncontrolledOpen(stored)
    setHydrated(true)
  }, [controlled, persistence, storageKey])

  React.useEffect(() => {
    if (!hydrated || persistence === false || controlled) return
    writePersisted(storageKey, persistence, open)
  }, [controlled, hydrated, open, persistence, storageKey])

  React.useEffect(() => {
    if (!keyboardShortcut) return

    const onKeyDown = (event: KeyboardEvent) => {
      if (
        event.defaultPrevented ||
        event.repeat ||
        event.key.toLowerCase() !== "b" ||
        !(event.metaKey || event.ctrlKey)
      ) {
        return
      }

      const target = event.target as HTMLElement | null
      if (
        target?.isContentEditable ||
        target?.tagName === "INPUT" ||
        target?.tagName === "TEXTAREA" ||
        target?.tagName === "SELECT"
      ) {
        return
      }

      event.preventDefault()
      toggleSidebar()
    }

    window.addEventListener("keydown", onKeyDown)
    return () => window.removeEventListener("keydown", onKeyDown)
  }, [keyboardShortcut, toggleSidebar])

  const context = React.useMemo<SidebarContextValue>(
    () => ({
      state:
        collapsible === "none" ? "expanded" : open ? "expanded" : "collapsed",
      open,
      setOpen,
      openMobile,
      setOpenMobile,
      isMobile,
      toggleSidebar,
      side,
      variant,
      collapsible,
      sidebarId,
    }),
    [
      open,
      setOpen,
      openMobile,
      isMobile,
      toggleSidebar,
      side,
      variant,
      collapsible,
      sidebarId,
    ]
  )

  const widthValue = typeof width === "number" ? `${width}px` : width
  const widthIconValue =
    typeof widthIcon === "number" ? `${widthIcon}px` : widthIcon

  return (
    <SidebarContext.Provider value={context}>
      <div
        data-slot="sidebar-wrapper"
        data-state={
          collapsible === "none" ? "expanded" : open ? "expanded" : "collapsed"
        }
        data-side={side}
        data-variant={variant}
        className={cn(
          // 视口高度约束(审计 P1-13):默认钉住一屏,侧栏内容区自行滚动;
          // 嵌入型 demo / 小窗可用 className 的 h-* 覆写。
          "group/sidebar-wrapper flex h-svh max-h-svh min-h-0 w-full overflow-hidden data-[variant=inset]:bg-sidebar",
          className
        )}
        style={
          {
            "--sidebar-width": widthValue,
            "--sidebar-width-icon": widthIconValue,
            ...style,
          } as React.CSSProperties
        }
        {...props}
      >
        {children}
      </div>
    </SidebarContext.Provider>
  )
}

interface SidebarProps extends React.ComponentProps<"div"> {
  /**
   * 不属于 `Sidebar`:折叠模式统一在 `<SidebarProvider collapsible=…>` 配置。
   * 传在 Sidebar 上会被忽略,开发环境会打印告警。
   */
  collapsible?: never
  /** 不属于 `Sidebar`:在 `<SidebarProvider variant=…>` 配置。 */
  variant?: never
  /** 不属于 `Sidebar`:在 `<SidebarProvider side=…>` 配置。 */
  side?: never
}

function Sidebar({ className, children, ...props }: SidebarProps) {
  const {
    isMobile,
    openMobile,
    setOpenMobile,
    state,
    side,
    variant,
    collapsible,
    sidebarId,
  } = useSidebar()
  const M = useMessages()
  const direction = useDirection()

  if (process.env.NODE_ENV !== "production") {
    const misplaced = ["collapsible", "variant", "side"].filter((key) =>
      Object.prototype.hasOwnProperty.call(props, key)
    )
    if (misplaced.length > 0) {
      console.warn(
        `[Sidebar] Ignoring ${misplaced.join(
          ", "
        )}: these belong to <SidebarProvider>. Move them to <SidebarProvider collapsible=… variant=… side=…>.`
      )
    }
  }

  if (isMobile) {
    const physicalSide =
      side === "start"
        ? direction === "rtl"
          ? "right"
          : "left"
        : direction === "rtl"
          ? "left"
          : "right"

    return (
      <Sheet open={openMobile} onOpenChange={setOpenMobile}>
        <SheetContent
          data-sidebar="sidebar"
          data-mobile="true"
          side={physicalSide}
          showCloseButton={false}
          className="w-[var(--sidebar-width)] max-w-[calc(100vw-2rem)] bg-sidebar p-0 text-sidebar-foreground"
        >
          <SheetHeader className="sr-only">
            <SheetTitle>{M.sidebar.label}</SheetTitle>
            <SheetDescription>{M.sidebar.description}</SheetDescription>
          </SheetHeader>
          <div
            id={sidebarId}
            role="navigation"
            aria-label={M.sidebar.label}
            className="flex h-full w-full flex-col"
          >
            {children}
          </div>
        </SheetContent>
      </Sheet>
    )
  }

  const isFloating = variant === "floating" || variant === "inset"
  const expandedWidth = isFloating
    ? "w-[calc(var(--sidebar-width)+var(--spacing-4))]"
    : "w-[var(--sidebar-width)]"
  const iconWidth = isFloating
    ? "w-[calc(var(--sidebar-width-icon)+var(--spacing-4))]"
    : "w-[var(--sidebar-width-icon)]"

  const widthClass =
    state === "collapsed"
      ? collapsible === "offcanvas"
        ? "w-0 border-0 p-0"
        : collapsible === "icon"
          ? iconWidth
          : expandedWidth
      : expandedWidth

  const innerWidth =
    state === "collapsed" && collapsible === "icon"
      ? "w-[var(--sidebar-width-icon)]"
      : "w-[var(--sidebar-width)]"

  return (
    <div
      data-slot="sidebar"
      data-state={state}
      data-collapsible={state === "collapsed" ? collapsible : undefined}
      data-variant={variant}
      data-side={side}
      className={cn(
        "group peer sticky top-0 hidden h-full max-h-full min-h-0 shrink-0 flex-col text-sidebar-foreground transition-[width] duration-slow ease-standard md:flex",
        "data-[collapsible=offcanvas]:overflow-hidden",
        isFloating ? "bg-transparent p-2" : "bg-sidebar",
        !isFloating && (side === "start" ? "border-e" : "border-s"),
        !isFloating && "border-sidebar-border",
        widthClass,
        className
      )}
      {...props}
    >
      <div
        id={sidebarId}
        data-sidebar="sidebar"
        role="navigation"
        aria-label={M.sidebar.label}
        className={cn(
          "flex h-full w-full flex-col overflow-hidden bg-sidebar transition-[width] duration-slow ease-standard",
          innerWidth,
          isFloating && "rounded-lg border border-sidebar-border shadow-xs"
        )}
      >
        {children}
      </div>
    </div>
  )
}

function SidebarTrigger({
  className,
  onClick,
  ...props
}: React.ComponentProps<typeof Button>) {
  const { toggleSidebar, state, isMobile, openMobile, sidebarId } = useSidebar()
  const M = useMessages()
  const expanded = isMobile ? openMobile : state === "expanded"

  return (
    <Button
      data-slot="sidebar-trigger"
      data-sidebar="trigger"
      variant="ghost"
      size="icon-2sm"
      className={cn("pointer-coarse:size-11", className)}
      aria-label={M.sidebar.toggle}
      aria-expanded={expanded}
      aria-controls={isMobile && !openMobile ? undefined : sidebarId}
      onClick={(event) => {
        onClick?.(event)
        toggleSidebar()
      }}
      {...props}
    >
      <PanelLeftIcon className="rtl:-scale-x-100" />
      <span className="sr-only">{M.sidebar.toggle}</span>
    </Button>
  )
}

function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
  const { toggleSidebar, side, collapsible, state } = useSidebar()
  const M = useMessages()
  const direction = useDirection()

  if (collapsible === "none") return null
  // rail 挂在 -end-4 / -start-4 上,中心对齐需要向容器内平移半宽;
  // 平移方向由「side 与书写方向是否同向」决定,不是恒定 -translate-x-1/2。
  const railTranslate =
    (side === "start") === (direction === "rtl")
      ? "translate-x-1/2"
      : "-translate-x-1/2"

  return (
    <button
      data-slot="sidebar-rail"
      data-sidebar="rail"
      type="button"
      tabIndex={-1}
      aria-hidden="true"
      title={state === "expanded" ? M.sidebar.collapse : M.sidebar.expand}
      onClick={toggleSidebar}
      className={cn(
        "absolute inset-y-0 z-dropdown hidden w-4 cursor-col-resize after:absolute after:inset-y-0 after:start-1/2 after:w-0.5 after:transition-colors after:duration-fast hover:after:bg-sidebar-border sm:flex",
        railTranslate,
        side === "start" ? "-end-4" : "-start-4",
        className
      )}
      {...props}
    />
  )
}

function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
  return (
    <main
      data-slot="sidebar-inset"
      className={cn(
        "relative flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto overscroll-contain bg-background",
        "md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-xs",
        className
      )}
      {...props}
    />
  )
}

function SidebarInput({
  className,
  ...props
}: React.ComponentProps<typeof Input>) {
  return (
    <Input
      data-slot="sidebar-input"
      data-sidebar="input"
      controlSize="sm"
      className={cn("w-full bg-background shadow-none pointer-coarse:h-11", className)}
      {...props}
    />
  )
}

function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-header"
      data-sidebar="header"
      className={cn("flex flex-col gap-2 p-2", className)}
      {...props}
    />
  )
}

function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-footer"
      data-sidebar="footer"
      className={cn("flex flex-col gap-2 p-2", className)}
      {...props}
    />
  )
}

function SidebarSeparator({
  className,
  ...props
}: React.ComponentProps<typeof Separator>) {
  return (
    <Separator
      data-slot="sidebar-separator"
      data-sidebar="separator"
      className={cn("mx-2 w-auto bg-sidebar-border", className)}
      {...props}
    />
  )
}

function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-content"
      data-sidebar="content"
      className={cn(
        "flex min-h-0 flex-1 flex-col gap-2 overflow-auto overscroll-contain group-data-[collapsible=icon]:overflow-hidden",
        className
      )}
      {...props}
    />
  )
}

function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-group"
      data-sidebar="group"
      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
      {...props}
    />
  )
}

function SidebarGroupLabel({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-group-label"
      data-sidebar="group-label"
      className={cn(
        "flex h-control-sm shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground ring-sidebar-ring outline-none transition-[margin,opacity] duration-normal ease-standard focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
        className
      )}
      {...props}
    />
  )
}

function SidebarGroupAction({
  className,
  ...props
}: ButtonPrimitive.Props) {
  return (
    <ButtonPrimitive
      data-slot="sidebar-group-action"
      data-sidebar="group-action"
      className={cn(
        "absolute top-3.5 end-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-none transition-colors duration-fast hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 pointer-coarse:after:-inset-3 pointer-fine:after:hidden group-data-[collapsible=icon]:hidden",
        className
      )}
      {...props}
    />
  )
}

function SidebarGroupContent({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-group-content"
      data-sidebar="group-content"
      className={cn("w-full text-sm", className)}
      {...props}
    />
  )
}

function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
  return (
    <ul
      data-slot="sidebar-menu"
      data-sidebar="menu"
      className={cn("flex w-full min-w-0 flex-col gap-1", className)}
      {...props}
    />
  )
}

function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
  return (
    <li
      data-slot="sidebar-menu-item"
      data-sidebar="menu-item"
      className={cn("group/menu-item relative", className)}
      {...props}
    />
  )
}

const sidebarMenuButtonVariants = cva(
  "peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md px-2 py-1 text-start text-sm ring-sidebar-ring outline-none transition-[width,height,padding,color,background-color] duration-fast ease-standard pointer-coarse:min-h-11 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 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-control-sm! group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:p-2! group-data-[collapsible=icon]:[&>span]:hidden [&>span:last-child]:truncate [&>span:not([data-slot]):has(~[data-slot])]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
  {
    variants: {
      variant: {
        default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
        outline:
          "border border-sidebar-border bg-background shadow-xs hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
      },
      size: {
        default: "h-control-sm text-sm",
        sm: "h-control-2xs text-xs",
        lg: "h-control-xl text-sm",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

interface SidebarMenuButtonProps
  extends ButtonPrimitive.Props,
    VariantProps<typeof sidebarMenuButtonVariants> {
  isActive?: boolean
  /** 仅当该条目明确对应当前页面时传 true;isActive 只负责视觉态 */
  current?: boolean
  tooltip?: string | React.ReactNode
  /**
   * 行尾徽标槽:传数字/字符串时使用内建计数胶囊样式,传节点时原样渲染。
   * 折叠为图标轨(collapsible="icon")时自动隐藏。
   */
  badge?: React.ReactNode
  /**
   * 行尾自定义槽(快捷键、状态点、箭头等),排在 badge 之后。
   * 折叠为图标轨(collapsible="icon")时自动隐藏。
   */
  trailing?: React.ReactNode
}

function SidebarMenuButton({
  className,
  variant = "default",
  size = "default",
  isActive,
  current,
  tooltip,
  badge,
  trailing,
  children,
  render,
  ...props
}: SidebarMenuButtonProps) {
  const { isMobile, state, side } = useSidebar()
  const direction = useDirection()
  const collapsed = !isMobile && state === "collapsed"

  const button = (
    <ButtonPrimitive
      data-slot="sidebar-menu-button"
      data-sidebar="menu-button"
      data-size={size}
      data-active={isActive ? "true" : undefined}
      aria-current={current ? "page" : undefined}
      aria-label={
        collapsed && typeof tooltip === "string" ? tooltip : undefined
      }
      className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
      render={render}
      {...props}
    >
      {children}
      {badge != null ? (
        <span
          data-slot="sidebar-menu-button-badge"
          data-sidebar="menu-button-badge"
          className="ms-auto flex shrink-0 items-center justify-center group-data-[collapsible=icon]:hidden"
        >
          {typeof badge === "string" || typeof badge === "number" ? (
            <span className="inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-sidebar-accent px-1.5 text-2xs font-medium tabular-nums text-sidebar-accent-foreground">
              {badge}
            </span>
          ) : (
            badge
          )}
        </span>
      ) : null}
      {trailing != null ? (
        <span
          data-slot="sidebar-menu-button-trailing"
          data-sidebar="menu-button-trailing"
          className={cn(
            "flex shrink-0 items-center gap-1 group-data-[collapsible=icon]:hidden",
            badge == null && "ms-auto"
          )}
        >
          {trailing}
        </span>
      ) : null}
    </ButtonPrimitive>
  )

  if (!tooltip || !collapsed) return button

  const tooltipSide =
    side === "start"
      ? direction === "rtl"
        ? "left"
        : "right"
      : direction === "rtl"
        ? "right"
        : "left"

  return (
    <Tooltip>
      <TooltipTrigger render={button} />
      <TooltipContent side={tooltipSide}>{tooltip}</TooltipContent>
    </Tooltip>
  )
}

interface SidebarMenuActionProps extends ButtonPrimitive.Props {
  showOnHover?: boolean
}

function SidebarMenuAction({
  className,
  showOnHover = false,
  ...props
}: SidebarMenuActionProps) {
  return (
    <ButtonPrimitive
      data-slot="sidebar-menu-action"
      data-sidebar="menu-action"
      className={cn(
        "absolute top-1.5 end-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-none transition-colors duration-fast hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 pointer-coarse:after:-inset-3 pointer-fine:after:hidden 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",
        showOnHover &&
          "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-sidebar-accent-foreground md:opacity-0",
        className
      )}
      {...props}
    />
  )
}

function SidebarMenuBadge({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="sidebar-menu-badge"
      data-sidebar="menu-badge"
      className={cn(
        "pointer-events-none absolute end-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[active=true]/menu-button:text-sidebar-accent-foreground group-data-[collapsible=icon]:hidden",
        className
      )}
      {...props}
    />
  )
}

function SidebarMenuSkeleton({
  className,
  showIcon = false,
  width = "70%",
  ...props
}: React.ComponentProps<"div"> & {
  showIcon?: boolean
  width?: string
}) {
  return (
    <div
      data-slot="sidebar-menu-skeleton"
      data-sidebar="menu-skeleton"
      className={cn("flex h-control-sm items-center gap-2 rounded-md px-2", className)}
      {...props}
    >
      {showIcon && (
        <Skeleton
          data-sidebar="menu-skeleton-icon"
          className="size-4 rounded-md"
        />
      )}
      <Skeleton
        data-sidebar="menu-skeleton-text"
        className="h-4 max-w-[var(--skeleton-width)] flex-1"
        style={{ "--skeleton-width": width } as React.CSSProperties}
      />
    </div>
  )
}

function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
  return (
    <ul
      data-slot="sidebar-menu-sub"
      data-sidebar="menu-sub"
      className={cn(
        "mx-3.5 flex min-w-0 flex-col gap-1 border-s border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
        className
      )}
      {...props}
    />
  )
}

function SidebarMenuSubItem({
  className,
  ...props
}: React.ComponentProps<"li">) {
  return (
    <li
      data-slot="sidebar-menu-sub-item"
      data-sidebar="menu-sub-item"
      className={cn("group/menu-sub-item relative", className)}
      {...props}
    />
  )
}

interface SidebarMenuSubButtonProps extends ButtonPrimitive.Props {
  size?: "sm" | "md"
  isActive?: boolean
  /** 仅当该子条目明确对应当前页面时传 true;isActive 只负责视觉态 */
  current?: boolean
}

function SidebarMenuSubButton({
  className,
  size = "md",
  isActive,
  current,
  ...props
}: SidebarMenuSubButtonProps) {
  return (
    <ButtonPrimitive
      data-slot="sidebar-menu-sub-button"
      data-sidebar="menu-sub-button"
      data-size={size}
      data-active={isActive ? "true" : undefined}
      aria-current={current ? "page" : undefined}
      className={cn(
        "flex h-control-2xs min-w-0 items-center gap-2 overflow-hidden rounded-md px-2 text-start text-sidebar-foreground transition-colors duration-fast pointer-coarse:min-h-11 ring-sidebar-ring outline-none hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground data-[size=md]:text-sm data-[size=sm]:text-xs [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground group-data-[collapsible=icon]:hidden",
        className
      )}
      {...props}
    />
  )
}

export {
  Sidebar,
  SidebarContent,
  SidebarContext,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupAction,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInput,
  SidebarInset,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSkeleton,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarSeparator,
  SidebarTrigger,
  sidebarMenuButtonVariants,
  useSidebar,
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

应用侧栏,由 SidebarProvider、Sidebar、SidebarInset 组合;side/variant/collapsible/宽度/持久化全部配置在 SidebarProvider,Sidebar 只负责结构(传错在 TS 报错、开发环境告警);支持 offcanvas/icon 折叠、移动端 Sheet、Ctrl/Cmd+B、localStorage 或 cookie 持久化;side 用 start/end 以适配 RTL;SidebarMenuButton 的 badge/trailing 行尾槽内建折叠隐藏。

配置位置(先读)

side / variant / collapsible / width / widthIcon / persistence / storageKey / keyboardShortcut 都是 <SidebarProvider> 的 props,不是 <Sidebar> 的。<Sidebar> 只负责结构(Header / Content / Menu / Footer / Rail)。

// ✅ 正确:配置统一放在 Provider
<SidebarProvider collapsible="icon" variant="inset" side="start">
  <Sidebar>{/* 结构 */}</Sidebar>
</SidebarProvider>

// ❌ 错误:collapsible 不是 Sidebar 的 prop
// TypeScript 会报错;JS 消费方会在开发环境控制台看到告警
<Sidebar collapsible="icon">{/* 结构 */}</Sidebar>

快速接入

import {
  Sidebar,
  SidebarInset,
  SidebarProvider,
  SidebarTrigger,
} from "@mox-hub/ui";

<SidebarProvider>
  <Sidebar>{/* SidebarHeader / Content / Menu / Footer */}</Sidebar>
  <SidebarInset>
    <SidebarTrigger />
    {/* 页面内容 */}
  </SidebarInset>
</SidebarProvider>;

Provider 配置

Prop取值默认说明
sidestart / endstart逻辑方向;RTL 下自动镜像,不用写 left/right
variantsidebar / floating / insetsidebar贴边、浮动卡片或内嵌式侧栏
collapsibleoffcanvas / icon / noneoffcanvas收起为 0 宽、图标轨或不可收起
defaultOpenbooleantrue非受控初始展开状态
openboolean—受控展开状态
onOpenChange(open: boolean) => void—受控状态回调
persistencelocal / cookie / falselocal展开状态持久化方式
storageKeystringordo-sidebar持久化键名
keyboardShortcutbooleantrueCtrl/Cmd+B 切换;输入框、文本域内不劫持
widthstring / number16rem展开宽度,number 按 px 处理
widthIconstring / number3rem图标轨宽度,number 按 px 处理
  • 视口小于 768px 时自动切换为 Sheet;SidebarTrigger 可放在 SidebarInset 的页头。
  • SidebarMenuButton 在 collapsible="icon" 下自动居中图标,并通过 tooltip 显示名称。
  • SidebarRail 提供侧栏边缘的拖拽式点击热区;useSidebar() 可在业务组件里读取 state、isMobile 与 toggleSidebar。
  • SidebarProvider 默认就是 h-svh max-h-svh overflow-hidden 的应用壳,侧栏内容区(SidebarContent)与 SidebarInset 各自滚动;嵌入到卡片/弹窗时可传 className="h-[420px]" 覆写高度。

行尾徽标与自定义槽

SidebarMenuButton 提供 badge / trailing 两个行尾槽,均内建折叠隐藏(collapsible="icon" 时自动消失),不需要再手写 group-data-[collapsible=icon]:hidden。

<SidebarMenuButton tooltip="待办" badge={4}>
  <ListTodo />
  <span>待办</span>
</SidebarMenuButton>

<SidebarMenuButton
  tooltip="搜索"
  trailing={<span className="text-2xs text-sidebar-foreground">⌘K</span>}
>
  <Search />
  <span>搜索</span>
</SidebarMenuButton>
  • badge 传数字/字符串时使用内建计数胶囊;传 ReactNode 时原样渲染(例如自定义 <Badge>)。
  • trailing 排在 badge 之后,适合快捷键、状态点、展开箭头等非计数内容。
  • 两个槽都参与行尾布局(ms-auto),长标题仍会正常截断。