@teamix-evo/ui 0.7.0 → 0.7.2

package/src/components/sidebar/meta.md

@@ -12,3 +12,386 @@
 - 管理后台布局侧边导航
 - 需要可收缩的菜单导航
 - 配合 SidebarProvider 与页面布局使用
+
+## 示例
+
+### CollapsibleIcon
+
+折叠态 + 自动 Tooltip：默认收起，hover icon 弹出文字
+
+```tsx
+<SidebarProvider open={!collapsed} onOpenChange={(o) => setCollapsed(!o)}>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            {navItems.map((it) => (
+              <SidebarMenuItem key={it.title}>
+                <SidebarMenuButton asChild tooltip={it.title}>
+                  <a href={it.url} onClick={(e) => e.preventDefault()}>
+                    <it.icon />
+                    <span>{it.title}</span>
+                  </a>
+                </SidebarMenuButton>
+              </SidebarMenuItem>
+            ))}
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    <p>
+      当前折叠状态：<strong>{collapsed ? '已折叠' : '已展开'}</strong>
+    </p>
+    <p className="mt-2">
+      折叠后 hover 任一 icon，会看到 Tooltip 弹出对应文字。
+    </p>
+  </MainContent>
+</SidebarProvider>
+```
+
+### WithSubMenus
+
+二级菜单：配合 Collapsible 实现展开/收起，折叠态自动隐藏
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild tooltip="首页">
+              <a href="#home" onClick={(e) => e.preventDefault()}>
+                <Home />
+                <span>首页</span>
+              </a>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+          {/* 知识库 + 二级 */}
+          <Collapsible defaultOpen asChild className="group/collapsible">
+            <SidebarMenuItem>
+              <CollapsibleTrigger asChild>
+                <SidebarMenuButton tooltip="知识库">
+                  <BookOpen />
+                  <span>知识库</span>
+                  <ChevronRight className="ml-auto transition-transform group-data-[state=open]/collapsible:rotate-90" />
+                </SidebarMenuButton>
+              </CollapsibleTrigger>
+              <CollapsibleContent>
+                <SidebarMenuSub>
+                  {kbSubItems.map((s) => (
+                    <SidebarMenuSubItem key={s.title}>
+                      <SidebarMenuSubButton
+                        href={s.url}
+                        isActive={s.url === '#kb-public'}
+                        onClick={(e) => e.preventDefault()}
+                      >
+                        <span>{s.title}</span>
+                      </SidebarMenuSubButton>
+                    </SidebarMenuSubItem>
+                  ))}
+                </SidebarMenuSub>
+              </CollapsibleContent>
+            </SidebarMenuItem>
+          </Collapsible>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild tooltip="设置">
+              <a href="#settings" onClick={(e) => e.preventDefault()}>
+                <Settings />
+                <span>设置</span>
+              </a>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    知识库展开后，折叠 Sidebar — 二级菜单会自动隐藏。
+  </MainContent>
+</SidebarProvider>
+```
+
+### WithBadgeAndAction
+
+徽标 + hover 操作：MenuBadge 显示数字，MenuAction 仅 hover 浮现
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          {navItems.map((it) => (
+            <SidebarMenuItem key={it.title}>
+              <SidebarMenuButton asChild tooltip={it.title}>
+                <a href={it.url} onClick={(e) => e.preventDefault()}>
+                  <it.icon />
+                  <span>{it.title}</span>
+                </a>
+              </SidebarMenuButton>
+              {it.title === '收件箱' && (
+                <SidebarMenuBadge>5</SidebarMenuBadge>
+              )}
+              <SidebarMenuAction
+                showOnHover
+                aria-label="更多"
+                onClick={(e) => e.preventDefault()}
+              >
+                <MoreHorizontal />
+              </SidebarMenuAction>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    鼠标移到菜单项 — 右侧浮现「⋯」操作按钮；收件箱有未读徽标。
+  </MainContent>
+</SidebarProvider>
+```
+
+### VariantFloating
+
+浮起变体：Sidebar 脱离边缘，带圆角和阴影
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          {navItems.map((it) => (
+            <SidebarMenuItem key={it.title}>
+              <SidebarMenuButton asChild tooltip={it.title}>
+                <a href={it.url} onClick={(e) => e.preventDefault()}>
+                  <it.icon />
+                  <span>{it.title}</span>
+                </a>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    variant=&quot;floating&quot; — 浮起、圆角、阴影。
+  </MainContent>
+</SidebarProvider>
+```
+
+### VariantInset
+
+内嵌变体：主内容区圆角内缩
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          {navItems.map((it) => (
+            <SidebarMenuItem key={it.title}>
+              <SidebarMenuButton asChild tooltip={it.title}>
+                <a href={it.url} onClick={(e) => e.preventDefault()}>
+                  <it.icon />
+                  <span>{it.title}</span>
+                </a>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    variant=&quot;inset&quot; — 主内容区域圆角内嵌。
+  </MainContent>
+</SidebarProvider>
+```
+
+### WithRail
+
+Rail 拖拽收合：Sidebar 右边缘 hover 出线条，点击切换
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          {navItems.map((it) => (
+            <SidebarMenuItem key={it.title}>
+              <SidebarMenuButton asChild tooltip={it.title}>
+                <a href={it.url} onClick={(e) => e.preventDefault()}>
+                  <it.icon />
+                  <span>{it.title}</span>
+                </a>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+  <MainContent>
+    鼠标移到 Sidebar 右边缘 — 出现窄拖拽柄，点击切换折叠。
+  </MainContent>
+</SidebarProvider>
+```
+
+### WithInputAndGroupAction
+
+搜索输入 + 分组操作：SidebarInput + GroupAction
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+      <SidebarInput placeholder="搜索…" />
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航</SidebarGroupLabel>
+        <SidebarMenu>
+          {navItems.slice(0, 3).map((it) => (
+            <SidebarMenuItem key={it.title}>
+              <SidebarMenuButton asChild tooltip={it.title}>
+                <a href={it.url} onClick={(e) => e.preventDefault()}>
+                  <it.icon />
+                  <span>{it.title}</span>
+                </a>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+
+      <SidebarSeparator />
+
+      <SidebarGroup>
+        <SidebarGroupLabel>收藏</SidebarGroupLabel>
+        <SidebarGroupAction
+          aria-label="管理收藏"
+          onClick={(e) => e.preventDefault()}
+        >
+          <MoreHorizontal />
+        </SidebarGroupAction>
+        <SidebarMenu>
+          {favoriteItems.map((f) => (
+            <SidebarMenuItem key={f.title}>
+              <SidebarMenuButton asChild tooltip={f.title} size="sm">
+                <a href={f.url} onClick={(e) => e.preventDefault()}>
+                  <Star />
+                  <span>{f.title}</span>
+                </a>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>
+    顶部 SidebarInput 搜索 + 收藏分组头部「⋯」管理操作。
+  </MainContent>
+</SidebarProvider>
+```
+
+### LoadingSkeleton
+
+加载骨架：异步数据 ready 前的占位
+
+```tsx
+<SidebarProvider>
+  <Sidebar {...args}>
+    <SidebarHeader>
+      <div className="flex items-center group-data-[collapsible=icon]:justify-center">
+        <h1 className="flex-1 px-2 text-sm font-semibold group-data-[collapsible=icon]:hidden">
+          Teamix Evo
+        </h1>
+        <SidebarTrigger />
+      </div>
+    </SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>导航（加载中）</SidebarGroupLabel>
+        <SidebarMenu>
+          {Array.from({ length: 5 }).map((_, i) => (
+            <SidebarMenuItem key={i}>
+              <SidebarMenuSkeleton showIcon />
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <MainContent>真实业务中骨架会在数据 ready 后切换为 Menu。</MainContent>
+</SidebarProvider>
+```

package/src/components/skeleton/meta.md

@@ -99,6 +99,19 @@ pulse / none 两种动画对照。
 </div>
 ```
 
+### Loading
+
+loading + children 条件渲染：loading=false 时直接显示真实内容。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Button onClick={() => setLoading((v) => !v)}>切换</Button>
+  <Skeleton loading={loading} className="h-8 w-64">
+    <span className="text-xs text-foreground">真实内容已加载</span>
+  </Skeleton>
+</div>
+```
+
 ### Avatar
 
 头像骨架：三档尺寸 + 两种形状。

package/src/components/slider/index.tsx

@@ -215,7 +215,7 @@ function Slider({
         >
           <SliderPrimitive.Range
             data-slot="slider-range"
-            className="absolute bg-primary group-data-[reverse=true]/slider:bg-muted select-none data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full"
+            className="absolute bg-primary select-none group-data-[reverse=true]/slider:bg-muted data-[orientation=horizontal]:h-full data-[orientation=vertical]:w-full"
           />
           {parsedMarks.map((m) => (
             <span
@@ -235,7 +235,7 @@ function Slider({
               key={`label-${m.value}`}
               data-slot="slider-mark-label"
               style={labelStyle(m.value)}
-              className="pointer-events-none absolute whitespace-nowrap text-xs text-muted-foreground"
+              className="pointer-events-none absolute text-xs whitespace-nowrap text-muted-foreground"
             >
               {m.label}
             </span>

package/src/components/sonner/meta.md

@@ -111,6 +111,27 @@
 </>
 ```
 
+### PromiseToast
+
+Promise 链式更新 — 一次声明 loading / success / error 三态文案，自动跟随 Promise 状态。
+
+```tsx
+<>
+  <Button
+    onClick={() =>
+      toast.promise(mockRequest(), {
+        loading: '正在提交订单...',
+        success: (data) => `${data.name} 已提交`,
+        error: (err: Error) => `提交失败：${err.message}`,
+      })
+    }
+  >
+    触发
+  </Button>
+  <Toaster />
+</>
+```
+
 ### Duration
 
 持续时长 — `duration` 控制关闭延迟，`Infinity` 持久不关。对应 cloud-design `duration: 0`。
@@ -137,6 +158,30 @@
 </div>
 ```
 
+### Placement
+
+容器位置 — `placement` 6 档形态，对应 cloud-design `Notification.config({ placement })`。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex flex-wrap gap-2">
+    {placements.map((p) => (
+      <Button
+        key={p}
+        variant={p === placement ? 'default' : 'outline'}
+        onClick={() => {
+          setPlacement(p);
+          toast.success(`位置：${p}`);
+        }}
+      >
+        {p}
+      </Button>
+    ))}
+  </div>
+  <Toaster placement={placement} />
+</div>
+```
+
 ### Custom
 
 自定义渲染 — `toast.custom` 完全接管节点，用于嵌入富内容卡片。
@@ -170,3 +215,44 @@
   <Toaster />
 </>
 ```
+
+### DismissProgrammatic
+
+主动关闭 — `toast.dismiss(id)` 关闭指定通知，`toast.dismiss()` 清空全部。
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <Button
+    onClick={() => {
+      idRef.current = toast('一条可被定向关闭的通知', {
+        description: '保留这条 id，再点“关闭它”按钮。',
+        duration: Infinity,
+      });
+    }}
+  >
+    打开 1 条
+  </Button>
+  <Button
+    variant="outline"
+    onClick={() => {
+      for (let i = 0; i < 3; i += 1) {
+        toast.info(`批量通知 ${i + 1}`);
+      }
+    }}
+  >
+    打开 3 条
+  </Button>
+  <Button
+    variant="destructive"
+    onClick={() => {
+      if (idRef.current !== undefined) toast.dismiss(idRef.current);
+    }}
+  >
+    关闭它（按 id）
+  </Button>
+  <Button variant="destructive" onClick={() => toast.dismiss()}>
+    全部关闭
+  </Button>
+  <Toaster />
+</div>
+```

package/src/components/spinner/meta.md

@@ -136,6 +136,37 @@ tip 位置：right(行内) 与 bottom(堆叠)。
 </div>
 ```
 
+### OverlayControlled
+
+受控 visible + 100ms 防闪：短任务 (800ms) 不闪烁，长任务 (2000ms) 正常展示。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Button
+    onClick={() => {
+      setVisible1(true);
+      setVisible2(true);
+      setTimeout(() => setVisible1(false), 800);
+      setTimeout(() => setVisible2(false), 2000);
+    }}
+  >
+    开始加载
+  </Button>
+  <div className="flex gap-6">
+    <SpinnerOverlay visible={visible1} tip="800ms 快任务">
+      <div className="h-20 w-40 rounded border border-border p-4 text-xs">
+        面板 1
+      </div>
+    </SpinnerOverlay>
+    <SpinnerOverlay visible={visible2} tip="2000ms 慢任务">
+      <div className="h-20 w-40 rounded border border-border p-4 text-xs">
+        面板 2
+      </div>
+    </SpinnerOverlay>
+  </div>
+</div>
+```
+
 ### OverlayCustomIndicator
 
 自定义 indicator 替换默认 Spinner。
@@ -148,6 +179,21 @@ tip 位置：right(行内) 与 bottom(堆叠)。
 </SpinnerOverlay>
 ```
 
+### Fullscreen
+
+全屏遮罩 + Portal 投放 + Esc 关闭。
+
+```tsx
+<div>
+  <Button onClick={() => setVisible(true)}>打开全屏 Loading</Button>
+  <SpinnerFullscreen
+    visible={visible}
+    tip="加载中，按 Esc 关闭"
+    onVisibleChange={setVisible}
+  />
+</div>
+```
+
 ### DotsDefault
 
 SpinnerDots 三档尺寸：四点沿弧线轨道位移动画。

package/src/components/spinner/stories.tsx

@@ -113,7 +113,7 @@ export const OverlayTipAlign: Story = {
 
 /** 受控 visible + 100ms 防闪：短任务 (800ms) 不闪烁，长任务 (2000ms) 正常展示。 */
 export const OverlayControlled: Story = {
-  render: function OverlayControlledRender() {
+  render: () => {
     const [visible1, setVisible1] = React.useState(false);
     const [visible2, setVisible2] = React.useState(false);
     return (
@@ -158,7 +158,7 @@ export const OverlayCustomIndicator: Story = {
 
 /** 全屏遮罩 + Portal 投放 + Esc 关闭。 */
 export const Fullscreen: Story = {
-  render: function FullscreenRender() {
+  render: () => {
     const [visible, setVisible] = React.useState(false);
     return (
       <div>

package/src/components/steps/meta.md

@@ -197,6 +197,26 @@ labelPlacement="horizontal"——标签在指示器右侧水平排列。
 </div>
 ```
 
+### Clickable
+
+可点击步骤——传入 onChange 后步骤可交互切换。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Steps
+    shape="circle"
+    current={current}
+    onChange={setCurrent}
+    items={[
+      { title: '选择类型', description: '点击可跳转' },
+      { title: '填写内容', description: '点击可跳转' },
+      { title: '确认发布', description: '点击可跳转' },
+    ]}
+  />
+  <p className="text-xs text-muted-foreground">当前步骤：{current + 1}</p>
+</div>
+```
+
 ### AllStatuses
 
 所有状态一览。

package/src/components/steps/stories.tsx

@@ -221,7 +221,7 @@ export const Small: Story = {
 
 /** 可点击步骤——传入 onChange 后步骤可交互切换。 */
 export const Clickable: Story = {
-  render: function ClickableSteps() {
+  render: () => {
     const [current, setCurrent] = useState(0);
     return (
       <div className="flex flex-col gap-6">

package/src/components/switch/index.tsx

@@ -23,7 +23,7 @@ import { cn } from '@/lib/utils';
 // ─── cva ────────────────────────────────────────────────────────────────────
 
 const switchVariants = cva(
-  'peer group/switch relative inline-flex shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-ring/20 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-50 data-[loading=true]:pointer-events-none data-[loading=true]:opacity-70',
+  'peer group/switch relative inline-flex shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-ring/20 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-disabled:cursor-not-allowed data-disabled:opacity-50 data-[loading=true]:pointer-events-none data-[loading=true]:opacity-70 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
   {
     variants: {
       size: {
@@ -80,7 +80,7 @@ const thumbVariants = cva(
 
 const textVariants = cva(
   // padding 与 order 跟随 root data-state 切换：满足"thumb 紧贴边缘"规范（root 不加 px）
-  'inline-flex select-none items-center justify-center whitespace-nowrap leading-none transition-colors group-data-[state=checked]/switch:order-1 group-data-[state=checked]/switch:text-primary-foreground group-data-[state=unchecked]/switch:order-2 group-data-[state=unchecked]/switch:text-muted-foreground',
+  'inline-flex items-center justify-center leading-none whitespace-nowrap transition-colors select-none group-data-[state=checked]/switch:order-1 group-data-[state=checked]/switch:text-primary-foreground group-data-[state=unchecked]/switch:order-2 group-data-[state=unchecked]/switch:text-muted-foreground',
   {
     variants: {
       size: {