@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/sidebar/sidebar.meta.md

@@ -1,17 +1,18 @@
 ---
 id: sidebar
 name: Sidebar
+displayName: 侧边栏
 type: component
-category: navigation
+category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Sidebar
+# Sidebar 侧边栏
 
-侧边导航栏 — shadcn 风格复合组件,**对应 antd `Layout.Sider + Menu`**。
-**精简版**(MVP):涵盖 Provider + 折叠状态 + Header/Footer/Content + Menu + Trigger。
-**未含**(留 v0.x):mobile sheet 自动切换、cookie 持久化、Rail(可拖拽折叠杆)、富 SubMenu 嵌套。
+侧边导航栏 — shadcn 完整版 25 primitives 复合,**对应 antd `Layout.Sider + Menu` + 移动端 `Drawer`**。
+
+**已含**:Provider(open 受控/cookie 持久化/Cmd+B 快捷键/mobile 自动切 Sheet)、Sidebar(`variant=sidebar|floating|inset` × `side=left|right` × `collapsible=offcanvas|icon|none`)、Trigger / Rail / Inset / Input、Header / Footer / Separator / Content、Group / GroupLabel / GroupAction / GroupContent、Menu / MenuItem / MenuButton(cva variant+size + 折叠态自动 Tooltip)/ MenuAction / MenuBadge / MenuSkeleton、MenuSub / MenuSubItem / MenuSubButton。
 
 ## When to use
 
@@ -32,10 +33,9 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `side` | `'left' \| 'right'` | `"left"` | – | 侧边方向。 |
-| `collapsible` | `'icon' \| 'offcanvas' \| 'none'` | `"icon"` | – | 折叠模式 — `icon` 折叠后只剩图标列(64px);`offcanvas` 完全收起(0px)。 |
-| `width` | `string` | `"16rem"` | – | 展开宽度。 |
-| `collapsedWidth` | `string` | `"3rem"` | – | 折叠后宽度(`collapsible="icon"` 时生效)。 |
+| `side` | `'left' \| 'right'` | – | – | – |
+| `variant` | `'sidebar' \| 'floating' \| 'inset'` | – | – | – |
+| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | – | – | – |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -50,8 +50,13 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
 | `separator` | component | 分隔线 — Radix Separator + antd Divider 的 dashed / 中间装饰文本 |
+| `sheet` | component | 侧边面板 — Radix Dialog + side(left/right/top/bottom) + size(sm/md/lg/xl) + --radius-dialog 圆角,对齐 antd Drawer 全能力集 |
+| `tooltip` | component | 文字提示气泡 — Radix Tooltip + antd arrow/placement(side) 并集 + cloud-design Balloon 双变体(default 深底 / light 白底) + 一行 wrapper API |
+| `skeleton` | component | 骨架屏 — shadcn pulse 单元素 + antd Avatar/Image/Button/Input/Paragraph 子家族,自动 motion-reduce |
+| `input` | component | 单行文本输入 — clearable / showCount / size(sm 24 / md 32 / lg 36,与 Button 同档)/ error 四档内建能力。前缀/后缀/addon 等复合形态已拆出独立 InputGroup;多行已拆出独立 Textarea |
+| `use-mobile` | hook | 检测视口是否为移动尺寸(< 768px) — Sidebar 在 mobile 视口切 Sheet 抽屉的判定依据 |
 
 ### npm 依赖
 
@@ -62,24 +67,38 @@ pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-reac
 ```
 <!-- auto:deps:end -->
 
-> 完整子组件:`SidebarProvider`(Context 容器,必装)/ `Sidebar`(主侧边栏)/ `SidebarHeader` / `SidebarFooter` / `SidebarContent`(中间滚动区)/ `SidebarGroup` + `SidebarGroupLabel` / `SidebarMenu` + `SidebarMenuItem` + `SidebarMenuButton`(支持 `isActive` / `asChild`)/ `SidebarSeparator` / `SidebarTrigger`(切换按钮)/ `SidebarInset`(主内容区)+ `useSidebar()` hook。
-
 ## AI 生成纪律
 
-- **必装 SidebarProvider**:Sidebar 上下层任何子组件都依赖 Context;通常在 Layout 顶层包裹
+- **必装 SidebarProvider**:Sidebar 上下层任何子组件都依赖 Context;通常在 Layout 顶层包裹。Provider 内置 `TooltipProvider`,无需额外挂
 - **`SidebarMenuButton` 配 `asChild`**:wrap React Router / Next.js Link
+- **`SidebarMenuButton` 折叠态 tooltip**:`collapsible="icon"` 时务必传 `tooltip="导航名"`,否则折叠后只剩 icon 无法识别
 - **`isActive` 由路由判断**:不要用 useState 自管;`pathname === href`
 - **`collapsible="icon"` 默认**:折叠后保留图标列;`offcanvas` 完全收起;`none` 静态宽度
+- **`variant`**:`sidebar`(默认贴边)/ `floating`(浮起圆角阴影)/ `inset`(主内容区圆角内嵌,Sidebar 留白)
 - **`SidebarInset` 与 Sidebar 配对**:`<SidebarProvider><Sidebar/><SidebarInset>main content</SidebarInset></SidebarProvider>`
-- **菜单图标 first**:`<SidebarMenuButton><Icon /> 文字</SidebarMenuButton>`,顺序固定
+- **`SidebarMenuSub` 二级菜单**:与 `Collapsible`(`@/components/ui/collapsible`)组合实现展开/收起;sub 在折叠态自动隐藏
+- **`SidebarMenuBadge`** 用于未读数 / 状态徽章;**`SidebarMenuAction`**(`showOnHover` 默认 false,设 true 仅 hover 显示)用于行内操作
+- **`SidebarMenuSkeleton`** 用于异步加载占位,`showIcon` 控制是否显示左侧 icon 骨架
+- **`SidebarRail`** 是替代 Trigger 的可拖拽收合区;放在 `<Sidebar>` 内最后即可
+- **菜单图标 first**:`<SidebarMenuButton><Icon /> <span>文字</span></SidebarMenuButton>`,顺序固定
+- **mobile 自动切 Sheet**:`useIsMobile` 检测 < 768px 时 Sidebar 自动切为 Sheet 抽屉,无需消费方做媒体查询
 
 ## Examples
 
 ```tsx
 import {
-  SidebarProvider, Sidebar, SidebarHeader, SidebarContent,
-  SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuItem,
-  SidebarMenuButton, SidebarFooter, SidebarTrigger, SidebarInset,
+  SidebarProvider,
+  Sidebar,
+  SidebarHeader,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarFooter,
+  SidebarTrigger,
+  SidebarInset,
 } from '@/components/ui/sidebar';
 import { Home, Settings, Inbox, Users } from 'lucide-react';