@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/checkbox/checkbox.meta.md

@@ -2,12 +2,13 @@
 id: checkbox
 name: Checkbox
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 复选框
 ---
 
-# Checkbox
+# Checkbox 复选框
 
 复选框 — Radix Checkbox(原生支持 indeterminate)+ antd `Checkbox.Group`(`options` 数组驱动)。
 
@@ -28,7 +29,16 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-_(no props)_
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean \| 'indeterminate'` | – | – | 受控选中状态(等价 antd `checked`)。 取值 `true` / `false` / `'indeterminate'`(半选,只影响视觉,不改变 checked 语义)。 与 `defaultChecked` 二选一。 |
+| `defaultChecked` | `boolean \| 'indeterminate'` | `false` | – | 非受控初始选中态(等价 antd `defaultChecked`)。 |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | – | – | 选中状态变化回调 — Radix 命名,等价 antd `onChange(checked)`。 业务侧迁移自 antd 时把 `onChange={(e) => fn(e.target.checked)}` 改为 `onCheckedChange={fn}`。 |
+| `disabled` | `boolean` | `false` | – | 禁用整个 checkbox(灰化 + 不响应交互)。 |
+| `required` | `boolean` | `false` | – | 必填 — 设置 HTML 原生 `required`,表单层校验依赖此值。 |
+| `name` | `string` | – | – | 表单字段名(原生 `<input name>`,提交表单时使用)。 |
+| `value` | `string` | – | – | 表单字段值(勾选时随表单提交)。 |
+| `id` | `string` | – | – | id 属性,配合 `<label htmlFor>` 关联标签。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -53,16 +63,18 @@ pnpm add @radix-ui/react-checkbox@^1.1.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 透传 Radix Checkbox.Root 所有 props(`checked` / `defaultChecked` / `onCheckedChange` / `disabled` / `required` / `name` / `value` 等)。
-> 子组件 `CheckboxGroup` 的 props 详见 [`checkbox.tsx`](./checkbox.tsx) 的 `CheckboxGroupProps`。
+> 透传 Radix Checkbox.Root 所有 props（`checked` / `defaultChecked` / `onCheckedChange` / `disabled` / `required` / `name` / `value` 等）。
 
 ## AI 生成纪律
 
 - **`checked="indeterminate"` 不是布尔**:Radix 用字面量 `'indeterminate'` 表示半选,**不要**传 number 或其他值
-- **全选 + 半选模式**:列表全选场景 — 全选用 `checked={all}`,部分选用 `checked="indeterminate"`,父级 onCheckedChange 触发批量选/全清
+- **全选 + 半选模式**:列表全选场景 — 全选用 `checked={all}`,部分选用 `checked="indeterminate"`,父级 onCheckedChange 触发批量选/全清。完整 demo 见 [`SelectAll` Story](./checkbox.stories.tsx)
 - **必带 Label**:Checkbox 单独无文字,必须 `<label>...<Checkbox /></label>` 或 `<Checkbox id /> + <Label htmlFor>`
 - **`CheckboxGroup` options 必须有稳定的 `value`**:不要用 index 或动态值;否则 controlled diff 失效
 - **disabled 优先级**:整组 `disabled={true}` 会覆盖单项的 `disabled={false}`
+- **对钩视觉居中**:Indicator 内部使用 `flex items-center justify-center size-full` + `<Check className="size-3.5" strokeWidth={3} />`(`strokeWidth` prop 避免 `stroke-[\*]` arbitrary value),**不要随意改回 `size-3`**(会因 lucide Check viewBox 偏上出现视觉偏离中线)
+- **hover 反馈用 `enabled:` 前缀**(ADR 0024):`enabled:hover:border-primary` / `data-[state=unchecked]:enabled:hover:bg-primary/5` / checked 态用 `data-[state=checked]:enabled:hover:bg-primary/90` 加深;disabled 态不响应 hover
+- **激活态视觉自管,不被 scoped CSS 染灰**(ADR 0024):`data-state="checked"` / `"indeterminate"` 态由组件自身 `border-primary` + `bg-primary` 控制,uni-manager scoped CSS 已统一在 `:not()` 链里排除;新增激活态视觉时确保 scoped CSS 排除链覆盖
 
 ## Examples
 
@@ -97,3 +109,59 @@ const [v, setV] = React.useState(['apple']);
 // Group 纵向
 <CheckboxGroup orientation="vertical" options={...} defaultValue={[]} />
 ```
+
+## Checkbox 形态 — 旧库 API → 新映射
+
+> 决策:**不新增独立组件**,直接用 `Checkbox` + `CheckboxGroup` 承接 cloud-design `Checkbox` / `Checkbox.Group` 全部用法。本章节是从旧库平滑迁移的查表索引,与 [上面的 Props 表](#props) 互补。
+
+### 命名映射
+
+| cloud-design 旧库                               | `@teamix-evo/ui`                                             | 说明                                               |
+| ----------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
+| `Checkbox`                                      | `Checkbox`                                                   | 等价 — Radix Root,原生支持 indeterminate           |
+| `Checkbox.Group`(命名空间子组件)                | `CheckboxGroup`(独立 named export)                           | shadcn 风格命名,可独立 import / tree-shake         |
+| `<Checkbox.Group dataSource={[{label,value}]}>` | `<CheckboxGroup options={[{label,value}]}>`                  | `dataSource` → `options`(对齐 antd 通用命名)       |
+| `<Checkbox.Group direction="hor\|ver">`         | `<CheckboxGroup orientation="horizontal\|vertical">`         | 完整单词,与 Radix `orientation` 命名一致           |
+| `<Checkbox.Group value={[]} onChange={fn}>`     | `<CheckboxGroup value={[]} onChange={fn}>`                   | 同名同语义,签名 `(next: string[]) => void`         |
+| `<Checkbox.Group defaultValue={[]}>`            | `<CheckboxGroup defaultValue={[]}>`                          | 同名                                               |
+| `<Checkbox.Group disabled>`                     | `<CheckboxGroup disabled>`                                   | 整组禁用,覆盖单项                                  |
+| `<Checkbox indeterminate>`                      | `<Checkbox checked="indeterminate">`                         | Radix 用字面量代替布尔 prop,行为等价               |
+| 全选联动(旧库手动)                              | 父框 `checked={all ? true : some ? 'indeterminate' : false}` | 双方都需手动实现,新库示意见上面 Indeterminate 示例 |
+
+### Breaking Changes(从旧库迁移时需改写)
+
+1. `Checkbox.Group` → `CheckboxGroup`(import 路径变动:`import { CheckboxGroup }`)
+2. `direction` → `orientation`(取值同时从缩写 `hor/ver` 改为完整 `horizontal/vertical`)
+3. `dataSource` → `options`(签名一致,只是 prop 名)
+4. `indeterminate` boolean → `checked="indeterminate"` 字面量(与 Radix 对齐)
+
+## cd hybridcloud 视觉对齐(本组件已落地)
+
+> 对齐 cd hybridcloud `--checkbox-*` token,本次落地。token 真值取自 `node_modules/@alicloudfe/components/lib/theme/hybridcloud/css-var-definition.scss`。
+
+| 状态 | cd token / 真值 | 我们的 className | 备注 |
+| --- | --- | --- | --- |
+| default border | `--checkbox-border-color: #cccccc`(中性灰) | `border-input`(uni-manager `#d9d9d9`) | 视觉等价 |
+| default bg | `--checkbox-bg-color: #FFFFFF` | `bg-background` | ✓ |
+| hover border | `--checkbox-hovered-border-color: #589ADB`(浅蓝) | `enabled:hover:border-primary` | 取主色更聚焦,enabled-only |
+| hover bg | `--checkbox-hovered-bg-color: #F0F7FF`(超浅蓝) | `data-[state=unchecked]:enabled:hover:bg-primary/5` | 极浅主色 5% 透明 |
+| checked bg | `--checkbox-checked-bg-color: #0064C8`(primary) | `data-[state=checked]:bg-primary` | ✓ |
+| checked-hover bg | `--checkbox-checked-hovered-bg-color: #0057AD`(深蓝) | `data-[state=checked]:enabled:hover:bg-primary/90` | 主色 90% 透明 |
+| checked border | `--checkbox-checked-border-color: transparent` | `data-[state=checked]:border-primary` | 视觉等价(主色 bg + 主色 border 边缘融合) |
+| indeterminate | 与 checked 相同 + 横线 indicator | `data-[state=indeterminate]:bg-primary` + `<Minus />` | ✓ |
+| 圆角 | `--checkbox-border-radius: 2px`(corner-1) | `rounded-md`(uni-manager `--radius-md: 2px`) | ✓ |
+| disabled | `opacity-50` 整体淡化 + 不响应 hover | `disabled:opacity-50` + 所有 hover 加 `enabled:` 前缀 | ADR 0024 |
+
+### 不修复 / 后续工序清单
+
+- ~~**圆角微调**(2px → 3px)~~:本波次已落地 — `rounded-md` 在 uni-manager 即 2px(`--radius-md`),与 cd `corner-1` 一致
+- **disabled 灰色 vs opacity:0.5**:全局策略,报告 §5 已列入 "保留新库优势",**不修复**
+- **全选联动内置 prop**:旧库也需手动,本次保持手动模式(API 简洁优先);如有强需求未来可加 `<CheckboxGroupAll>` slot
+
+### Checkbox 专项 AI 生成纪律
+
+- `CheckboxGroup` 独立导入:`import { CheckboxGroup } from '@/components/ui/checkbox'`,**不要**写 `Checkbox.Group`(命名空间访问会编译错)
+- 半选状态用字面量 `'indeterminate'`,**不要**传 `boolean | null` 或自造常量
+- `options[].value` 必须稳定唯一(string),**不要**用 index / 动态 ID,否则 controlled diff 失效
+- 整组 `disabled` 优先级最高,会覆盖单项 `options[].disabled = false`(旧库行为一致)
+- `onChange` 签名是 `(next: string[]) => void`,**不要**期待事件对象第二参数

package/src/components/checkbox/checkbox.stories.tsx

@@ -1,16 +1,16 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Checkbox, CheckboxGroup } from './checkbox';
 
 const meta: Meta<typeof Checkbox> = {
-  title: '表单与输入 · Form/Checkbox',
+  title: '数据录入 · Data Entry/Checkbox',
   component: Checkbox,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '复选框 — 在一组选项中进行多选，或单独切换某个布尔状态。基于 Radix Checkbox(原生可访问 + indeterminate 三态) + antd `Checkbox.Group` 批量管理；支持受控 / 非受控、`disabled`、中间态。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '复选框 — 在一组选项中进行多选，或单独切换某个布尔状态。基于 Radix Checkbox（原生可访问 + indeterminate 三态）+ antd `Checkbox.Group` 批量管理；支持受控 / 非受控、`disabled`、中间态。',
       },
     },
   },
@@ -128,3 +128,161 @@ export const VerticalGroup: Story = {
     />
   ),
 };
+
+/**
+ * cd hybridcloud 视觉对齐 — 默认中性灰边 / hover 主色边 + 极浅蓝底 / checked 主色填充 /
+ * checked-hover 加深 / disabled opacity-50 + 不响应 hover。规则细节见 [ADR 0024](../../../../docs/adr/0024-scoped-css-radix-state-conflict.md)。
+ */
+export const CdAlignment: Story = {
+  name: 'cd hybridcloud 视觉对齐',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-4 text-sm">
+      <div className="flex items-center gap-6">
+        <label className="flex items-center gap-2">
+          <Checkbox /> default(中性灰边)
+        </label>
+        <label className="flex items-center gap-2">
+          <Checkbox defaultChecked /> checked(主色填充)
+        </label>
+        <label className="flex items-center gap-2">
+          <Checkbox checked="indeterminate" /> indeterminate(主色 + 横线)
+        </label>
+      </div>
+      <div className="flex items-center gap-6">
+        <label className="flex items-center gap-2 opacity-100">
+          <Checkbox disabled /> disabled(不响应 hover)
+        </label>
+        <label className="flex items-center gap-2 opacity-100">
+          <Checkbox disabled defaultChecked /> disabled checked
+        </label>
+        <label className="flex items-center gap-2 opacity-100">
+          <Checkbox disabled checked="indeterminate" /> disabled indeterm.
+        </label>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Hover 任意可交互项观察 — enabled 态边框转主色 + 极浅蓝底色;
+        disabled 态(opacity-50)无 hover 视觉变化。
+      </p>
+    </div>
+  ),
+};
+
+/**
+ * 表单集成 — Checkbox 跟 Label 一体的常见模式;主标签 + 辅助说明文本,
+ * 用 `flex flex-col gap` 而非 `space-y` 做布局(ADR / preference)。
+ */
+export const WithDescription: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <label
+        htmlFor="cb-marketing"
+        className="flex cursor-pointer items-start gap-3"
+      >
+        <Checkbox id="cb-marketing" defaultChecked className="mt-0.5" />
+        <span className="flex flex-col gap-0.5">
+          <span className="text-sm font-medium leading-none">订阅产品营销邮件</span>
+          <span className="text-xs text-muted-foreground">
+            每月不超过两封,介绍重大版本更新与最佳实践,可随时取消订阅。
+          </span>
+        </span>
+      </label>
+      <label
+        htmlFor="cb-tos"
+        className="flex cursor-pointer items-start gap-3"
+      >
+        <Checkbox id="cb-tos" required className="mt-0.5" />
+        <span className="flex flex-col gap-0.5">
+          <span className="text-sm font-medium leading-none">
+            我已阅读并同意 <a className="underline">用户协议</a> 和 <a className="underline">隐私政策</a>
+            <span className="text-destructive"> *</span>
+          </span>
+          <span className="text-xs text-muted-foreground">
+            必填项 — 未勾选时表单提交会校验失败。
+          </span>
+        </span>
+      </label>
+    </div>
+  ),
+};
+
+/**
+ * 长标签换行 — Checkbox 与 label 用 `items-start` 顶对齐,标签自然换行不影响勾选框位置。
+ */
+export const LongLabelWrap: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-72 flex-col gap-3">
+      <label className="flex cursor-pointer items-start gap-2 text-sm">
+        <Checkbox className="mt-1 shrink-0" />
+        <span>
+          这是一条非常长的文案,主要用来演示 Checkbox 与多行标签的对齐方式 —
+          建议外层用 `items-start` + 给 Checkbox 加 `mt-1` 让它对齐到第一行文字基线。
+        </span>
+      </label>
+    </div>
+  ),
+};
+
+/**
+ * 全选联动(完整版) — 父框 indeterminate 半选 + 全选切换 + 子项独立切换 +
+ * disabled 子项不参与计数。这是 cd hybridcloud Checkbox.Group 全选模式的等价写法。
+ */
+export const SelectAll: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [items, setItems] = React.useState([
+      { id: 'cn', label: '中国', checked: true, disabled: false },
+      { id: 'jp', label: '日本', checked: false, disabled: false },
+      { id: 'us', label: '美国', checked: false, disabled: false },
+      { id: 'kr', label: '韩国(暂不支持)', checked: false, disabled: true },
+    ]);
+    const enabledItems = items.filter((i) => !i.disabled);
+    const allChecked = enabledItems.every((i) => i.checked);
+    const someChecked = enabledItems.some((i) => i.checked);
+
+    return (
+      <div className="flex flex-col gap-3 text-sm">
+        <label className="flex items-center gap-2 font-medium">
+          <Checkbox
+            checked={
+              allChecked ? true : someChecked ? 'indeterminate' : false
+            }
+            onCheckedChange={(c) =>
+              setItems(
+                items.map((it) =>
+                  it.disabled ? it : { ...it, checked: c === true },
+                ),
+              )
+            }
+          />
+          全选 {someChecked && !allChecked
+            ? `(已选 ${enabledItems.filter((i) => i.checked).length} / ${enabledItems.length})`
+            : ''}
+        </label>
+        <div className="ml-6 flex flex-col gap-2">
+          {items.map((it) => (
+            <label
+              key={it.id}
+              className={`flex items-center gap-2 ${it.disabled ? 'opacity-60' : ''}`}
+            >
+              <Checkbox
+                disabled={it.disabled}
+                checked={it.checked}
+                onCheckedChange={(c) =>
+                  setItems(
+                    items.map((x) =>
+                      x.id === it.id ? { ...x, checked: c === true } : x,
+                    ),
+                  )
+                }
+              />
+              {it.label}
+            </label>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};

package/src/components/checkbox/checkbox.tsx

@@ -5,7 +5,50 @@ import { Check, Minus } from 'lucide-react';
 import { cn } from '@/utils/cn';
 
 export interface CheckboxProps
-  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root> {}
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+    | 'checked'
+    | 'defaultChecked'
+    | 'onCheckedChange'
+    | 'disabled'
+    | 'required'
+    | 'name'
+    | 'value'
+    | 'id'
+  > {
+  /**
+   * 受控选中状态(等价 antd `checked`)。
+   * 取值 `true` / `false` / `'indeterminate'`(半选,只影响视觉,不改变 checked 语义)。
+   * 与 `defaultChecked` 二选一。
+   */
+  checked?: boolean | 'indeterminate';
+  /**
+   * 非受控初始选中态(等价 antd `defaultChecked`)。
+   * @default false
+   */
+  defaultChecked?: boolean | 'indeterminate';
+  /**
+   * 选中状态变化回调 — Radix 命名,等价 antd `onChange(checked)`。
+   * 业务侧迁移自 antd 时把 `onChange={(e) => fn(e.target.checked)}` 改为 `onCheckedChange={fn}`。
+   */
+  onCheckedChange?: (checked: boolean | 'indeterminate') => void;
+  /**
+   * 禁用整个 checkbox(灰化 + 不响应交互)。
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * 必填 — 设置 HTML 原生 `required`,表单层校验依赖此值。
+   * @default false
+   */
+  required?: boolean;
+  /** 表单字段名(原生 `<input name>`,提交表单时使用)。 */
+  name?: string;
+  /** 表单字段值(勾选时随表单提交)。 */
+  value?: string;
+  /** id 属性,配合 `<label htmlFor>` 关联标签。 */
+  id?: string;
+}
 
 const Checkbox = React.forwardRef<
   React.ElementRef<typeof CheckboxPrimitive.Root>,
@@ -14,19 +57,37 @@ const Checkbox = React.forwardRef<
   <CheckboxPrimitive.Root
     ref={ref}
     className={cn(
-      'peer size-4 shrink-0 rounded-sm border border-primary shadow-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground',
+      // 视觉对齐 cd hybridcloud(--checkbox-* tokens):
+      //   default     : border #cccccc / bg #FFFFFF        → border-input + bg-background
+      //   hover       : border #589ADB / bg #F0F7FF        → hover:border-primary + hover:bg-primary/5
+      //   checked     : bg #0064C8 (primary) / tick white  → bg-primary + text-primary-foreground
+      //   ck-hovered  : bg #0057AD (deeper)                → data-[state=checked]:hover:bg-primary/90
+      //   indeterm.   : 同 checked,只是 indicator 换成 minus
+      //   border-radius: 2px (corner-1)                    → rounded-md(uni-manager 2px / opentrek 6px)
+      'peer size-4 shrink-0 cursor-pointer rounded-md border border-input bg-background shadow-sm transition-colors',
+      // hover 反馈用 `enabled:` 前缀 — disabled 态不触发 hover 样式(border/bg 变化)
+      'enabled:hover:border-primary data-[state=unchecked]:enabled:hover:bg-primary/5',
+      'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+      'disabled:cursor-not-allowed disabled:opacity-50',
+      'data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:enabled:hover:bg-primary/90',
+      'data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground data-[state=indeterminate]:enabled:hover:bg-primary/90',
       className,
     )}
     {...props}
   >
     <CheckboxPrimitive.Indicator
-      className={cn('flex items-center justify-center text-current')}
+      className={cn(
+        // 视觉居中:lucide Check / Minus 的笔画在 viewBox 内偏上,
+        // 配合 stroke-[3] 加粗与 size-3.5 略大于父框 (size-4) 的视觉补偿,
+        // 让对钩与减号在 16x16 框内呈现机械居中 + 视觉居中。
+        'pointer-events-none flex size-full items-center justify-center text-current',
+      )}
     >
       {/* Radix sets data-state="indeterminate" automatically when checked === "indeterminate" */}
       {props.checked === 'indeterminate' ? (
-        <Minus className="size-3" />
+        <Minus className="size-3" strokeWidth={3} />
       ) : (
-        <Check className="size-3" />
+        <Check className="size-3.5" strokeWidth={3} />
       )}
     </CheckboxPrimitive.Indicator>
   </CheckboxPrimitive.Root>
@@ -42,7 +103,10 @@ export interface CheckboxGroupOption {
 }
 
 export interface CheckboxGroupProps
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  extends Omit<
+    React.HTMLAttributes<HTMLDivElement>,
+    'onChange' | 'defaultValue'
+  > {
   /** 选项数据。 */
   options: CheckboxGroupOption[];
   /** 受控值;`string[]` 表示当前选中的 value 集合。 */
@@ -78,11 +142,15 @@ const CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(
     ref,
   ) => {
     const isControlled = value !== undefined;
-    const [internal, setInternal] = React.useState<string[]>(defaultValue ?? []);
+    const [internal, setInternal] = React.useState<string[]>(
+      defaultValue ?? [],
+    );
     const current = isControlled ? value! : internal;
 
     const toggle = (val: string, checked: boolean) => {
-      const next = checked ? [...current, val] : current.filter((v) => v !== val);
+      const next = checked
+        ? [...current, val]
+        : current.filter((v) => v !== val);
       if (!isControlled) setInternal(next);
       onChange?.(next);
     };
@@ -102,7 +170,7 @@ const CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(
           <label
             key={opt.value}
             className={cn(
-              'flex items-center gap-2 text-sm',
+              'flex items-center gap-2 text-xs',
               (disabled || opt.disabled) && 'cursor-not-allowed opacity-60',
             )}
           >

package/src/components/collapsible/collapsible.meta.md

@@ -2,12 +2,13 @@
 id: collapsible
 name: Collapsible
 type: component
-category: navigation
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 折叠面板
 ---
 
-# Collapsible
+# Collapsible 折叠面板
 
 单区域展开收起 — Radix Collapsible 薄包装。**shadcn-only**(antd Collapse 单 item 也可以模拟,但语义粗糙)。
 
@@ -27,7 +28,12 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`Collapsible` 是 `CollapsibleRoot` 别名,接受 Radix 的 `open / defaultOpen / onOpenChange / disabled`。
 
 <!-- auto:props:begin -->
-_(组件无 `<Name>Props` interface — props 详见 [`collapsible.tsx`](./collapsible.tsx))_
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控展开状态(等价 antd Collapse `activeKey` 单项模式)。 与 `defaultOpen` 二选一,不同时传。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始展开态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 展开状态变化回调 — Radix 命名。 |
+| `disabled` | `boolean` | `false` | – | 禁用展开/收起交互(灰化 Trigger + 不响应点击)。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -60,7 +66,9 @@ pnpm add @radix-ui/react-collapsible@^1.1.0
 
 ```tsx
 import {
-  Collapsible, CollapsibleTrigger, CollapsibleContent,
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
 } from '@/components/ui/collapsible';
 import { Button } from '@/components/ui/button';
 import { ChevronsUpDown } from 'lucide-react';
@@ -76,5 +84,5 @@ import { ChevronsUpDown } from 'lucide-react';
     <p className="text-sm text-muted-foreground">高级配置 1</p>
     <p className="text-sm text-muted-foreground">高级配置 2</p>
   </CollapsibleContent>
-</Collapsible>
+</Collapsible>;
 ```

package/src/components/collapsible/collapsible.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ChevronsUpDown } from 'lucide-react';
 import {
   Collapsible,
@@ -8,9 +8,17 @@ import {
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Collapsible> = {
-  title: '导航 · Navigation/Collapsible',
+  title: '数据展示 · Data Display/Collapsible',
   component: Collapsible,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '折叠面板 — 单区域展开收起，常用于“查看更多 / 收起”、表单高级选项开关等场景。Radix Collapsible 实现，shadcn 专有（antd Collapse 单 item 可模拟但语义粗糙）。',
+      },
+    },
+  },
 };
 
 export default meta;

package/src/components/collapsible/collapsible.tsx

@@ -1,5 +1,36 @@
+import * as React from 'react';
 import * as CollapsiblePrimitive from '@radix-ui/react-collapsible';
 
+import { cn } from '@/utils/cn';
+
+// ─── CollapsibleProps(ADR 0025 合规:显式声明交互 props)─────────────────
+
+export interface CollapsibleProps
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof CollapsiblePrimitive.Root>,
+    'open' | 'defaultOpen' | 'onOpenChange' | 'disabled'
+  > {
+  /**
+   * 受控展开状态(等价 antd Collapse `activeKey` 单项模式)。
+   * 与 `defaultOpen` 二选一,不同时传。
+   */
+  open?: boolean;
+  /**
+   * 非受控初始展开态。
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * 展开状态变化回调 — Radix 命名。
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 禁用展开/收起交互(灰化 Trigger + 不响应点击)。
+   * @default false
+   */
+  disabled?: boolean;
+}
+
 /**
  * 单区域展开 / 收起 — Radix Collapsible 的薄包装。
  *
@@ -8,11 +39,67 @@ import * as CollapsiblePrimitive from '@radix-ui/react-collapsible';
  *
  * shadcn-only(antd Collapse 单 item 也可以模拟,但语义粗糙)。
  */
-const Collapsible = CollapsiblePrimitive.Root;
-const CollapsibleTrigger = CollapsiblePrimitive.CollapsibleTrigger;
-const CollapsibleContent = CollapsiblePrimitive.CollapsibleContent;
+const Collapsible = React.forwardRef<
+  React.ElementRef<typeof CollapsiblePrimitive.Root>,
+  CollapsibleProps
+>(({ className, ...props }, ref) => (
+  <CollapsiblePrimitive.Root ref={ref} className={cn(className)} {...props} />
+));
+Collapsible.displayName = 'Collapsible';
+
+// ─── CollapsibleTrigger ─────────────────────────────────────────────────
+
+export interface CollapsibleTriggerProps
+  extends Omit<
+    React.ComponentPropsWithoutRef<
+      typeof CollapsiblePrimitive.CollapsibleTrigger
+    >,
+    'asChild'
+  > {
+  /**
+   * Slot 模式 — 子元素作为 trigger(不额外包裹 DOM)。
+   * @default false
+   */
+  asChild?: boolean;
+}
+
+const CollapsibleTrigger = React.forwardRef<
+  React.ElementRef<typeof CollapsiblePrimitive.CollapsibleTrigger>,
+  CollapsibleTriggerProps
+>(({ className, ...props }, ref) => (
+  <CollapsiblePrimitive.CollapsibleTrigger
+    ref={ref}
+    className={cn('cursor-pointer', className)}
+    {...props}
+  />
+));
+CollapsibleTrigger.displayName =
+  CollapsiblePrimitive.CollapsibleTrigger.displayName;
+
+// ─── CollapsibleContent ─────────────────────────────────────────────────
+
+export interface CollapsibleContentProps
+  extends React.ComponentPropsWithoutRef<
+    typeof CollapsiblePrimitive.CollapsibleContent
+  > {
+  /**
+   * 强制挂载(即使收起也保留 DOM,利于 SEO 或保持内部组件状态)。
+   * @default false
+   */
+  forceMount?: true;
+}
+
+const CollapsibleContent = React.forwardRef<
+  React.ElementRef<typeof CollapsiblePrimitive.CollapsibleContent>,
+  CollapsibleContentProps
+>(({ className, ...props }, ref) => (
+  <CollapsiblePrimitive.CollapsibleContent
+    ref={ref}
+    className={cn(className)}
+    {...props}
+  />
+));
+CollapsibleContent.displayName =
+  CollapsiblePrimitive.CollapsibleContent.displayName;
 
 export { Collapsible, CollapsibleTrigger, CollapsibleContent };
-export type CollapsibleProps = React.ComponentPropsWithoutRef<
-  typeof CollapsiblePrimitive.Root
->;