@teamix-evo/ui 0.2.0 → 0.3.0

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

@@ -3,16 +3,16 @@ id: sidebar
 name: Sidebar
 displayName: 侧边栏
 type: component
-category: navigation
+category: layout
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
 
 # 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
 
@@ -31,31 +31,11 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `Sidebar` 主容器 props。
 
 <!-- auto:props:begin -->
-
-#### Sidebar
-
-| 名称             | 类型                              | 默认值    | 必填 | 说明                                                                 |
-| ---------------- | --------------------------------- | --------- | ---- | -------------------------------------------------------------------- |
-| `side`           | `'left' \| 'right'`               | `"left"`  | –    | 侧边方向。                                                           |
-| `collapsible`    | `'icon' \| 'offcanvas' \| 'none'` | `"icon"`  | –    | 折叠模式 — `icon` 折叠后只剩图标列(64px);`offcanvas` 完全收起(0px)。 |
-| `width`          | `string`                          | `"16rem"` | –    | 展开宽度。                                                           |
-| `collapsedWidth` | `string`                          | `"3rem"`  | –    | 折叠后宽度(`collapsible="icon"` 时生效)。                            |
-
-#### SidebarProvider
-
-| 名称           | 类型                      | 默认值 | 必填 | 说明                |
-| -------------- | ------------------------- | ------ | ---- | ------------------- |
-| `open`         | `boolean`                 | –      | –    | 受控 open 状态。    |
-| `defaultOpen`  | `boolean`                 | `true` | –    | 非受控初始状态。    |
-| `onOpenChange` | `(open: boolean) => void` | –      | –    | open 状态变化回调。 |
-
-#### SidebarMenuButton
-
-| 名称       | 类型      | 默认值 | 必填 | 说明                                  |
-| ---------- | --------- | ------ | ---- | ------------------------------------- |
-| `isActive` | `boolean` | –      | –    | 当前激活态(高亮显示)。                |
-| `asChild`  | `boolean` | –      | –    | 用 Slot 渲染为子元素(配合路由 Link)。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `side` | `'left' \| 'right'` | – | – | – |
+| `variant` | `'sidebar' \| 'floating' \| 'inset'` | – | – | – |
+| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | – | – | – |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -63,16 +43,20 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add sidebar` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry       | 类型      | 描述                                                                                    |
-| ----------- | --------- | --------------------------------------------------------------------------------------- |
-| `cn`        | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                      |
-| `button`    | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
-| `separator` | component | 分隔线 — Radix Separator + antd Divider 的 dashed / 中间装饰文本                        |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `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 依赖
 
@@ -81,17 +65,23 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## 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