@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/textarea/textarea.meta.md

@@ -2,71 +2,72 @@
 id: textarea
 name: Textarea
 type: component
-category: form
-since: 0.1.0
+category: data-entry
+since: 0.2.0
 package: '@teamix-evo/ui'
 displayName: 多行文本框
 ---
 
 # Textarea 多行文本框
 
-多行文本输入 — shadcn 简洁基底 + antd 的 `autoSize / showCount`。
+多行文本输入 — shadcn 简洁基底 + antd `Input.TextArea` 的 `autoSize` / `showCount` 并集。从 v0.2 起作为**独立 entry**,与 [`Input`](../input/input.meta.md) 拆开(对齐 shadcn 2025-10 拆分粒度)。
+
+`size` 三档字号与 Input 对齐(高度由 `rows` / `autoSize` 决定,**不受 size 影响**)。
 
 ## When to use
 
 - 多行内容输入(评论 / 反馈 / 描述 / 备注)
-- 配 `autoSize` 给"动态高度"输入
+- 配 `autoSize={{ minRows, maxRows }}` 给"动态高度"输入
 - 配 `showCount + maxLength` 控制长度
 
 ## When NOT to use
 
-- 单行 → `Input`
-- 富文本编辑 → 用 Tiptap / Lexical 等编辑器(超出本组件库范围)
+- 单行文本 → `Input`
+- 输入 + 发送按钮(聊天框 / 评论框)→ `InputGroup` + `InputGroupTextarea` + `InputGroupAddon variant="button"`
+- @提及输入 → `Mentions`
 
 ## Props
 
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-| 名称           | 类型                                                | 默认值  | 必填 | 说明                                                                                                                            |
-| -------------- | --------------------------------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `autoSize`     | `boolean \| { minRows?: number; maxRows?: number }` | `false` | –    | 自动高度。`true` 时无上下限;传 `{ minRows, maxRows }` 时受限。 实现:监听 input 事件,把 textarea 设为 auto 后再读 scrollHeight。 |
-| `showCount`    | `boolean`                                           | `false` | –    | 显示字符计数(antd `showCount` 并集);需配合 `maxLength`。                                                                        |
-| `value`        | `string`                                            | –       | –    | 受控值。                                                                                                                        |
-| `defaultValue` | `string`                                            | –       | –    | uncontrolled 初始值。                                                                                                           |
-| `rows`         | `number`                                            | `3`     | –    | 行数(autoSize 关闭时生效)。                                                                                                     |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `autoSize` | `boolean \| { minRows?: number; maxRows?: number }` | `false` | – | 自动高度。`true` 时无上下限;传 `{ minRows, maxRows }` 时受限。 实现:监听 input 事件,把 textarea 设为 auto 后再读 scrollHeight。 |
+| `showCount` | `boolean` | `false` | – | 显示字符计数(antd `showCount` 并集);需配合 `maxLength`。 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `"md"` | – | 字号档位,与 `Input` 三档对齐:`sm`(text-xs) / `md`(text-xs,默认) / `lg`(text-sm)。 高度由 `rows` / `autoSize` 决定,不受 size 影响。 |
+| `error` | `boolean` | `false` | – | 错误态(快捷开关),会同时设置 `aria-invalid`,渲染 destructive 边框 / ring。 |
+| `value` | `string` | – | – | 受控值。 |
+| `defaultValue` | `string` | – | – | uncontrolled 初始值。 |
+| `rows` | `number` | `3` | – | 行数(autoSize 关闭时生效)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add textarea` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
-
 <!-- auto:deps:end -->
 
-> 透传所有 `<textarea>` 原生属性(`name` / `placeholder` / `disabled` / `onChange` / ...)。
+> 透传所有 `<textarea>` 原生属性(`name` / `id` / `placeholder` / `aria-*` / `onChange` / ...)。
 
 ## AI 生成纪律
 
-- **`autoSize` 替代 `rows`**:autoSize 启用后 rows 被忽略;两者不要同时传
-- **autoSize 配 `maxRows` 防止失控**:不限的 autoSize 在长内容下会撑爆容器,推荐 `{ minRows: 3, maxRows: 8 }`
-- **`showCount` 必须配 `maxLength`**:无 maxLength 时 showCount 不显示
-- **粘贴长内容时 ResizeObserver**:autoSize 用 effect 监听 value 触发,粘贴大文本会自动调整;无需业务侧介入
+- **`autoSize` 替代 `rows`** —— autoSize 启用后 rows 被忽略,两者不要同时传
+- **autoSize 配 `maxRows` 防止失控** —— 不限的 autoSize 在长内容下会撑爆容器,推荐 `{ minRows: 3, maxRows: 8 }`
+- **`showCount` 必须配 `maxLength`** —— 无 maxLength 时 showCount 不显示
+- **粘贴长内容时 effect 监听 value 自动 resize** —— 无需业务侧介入
+- **错误态走 `error` prop** —— 自动反映 `aria-invalid="true"`,**不要**手动拼 `border-destructive`
+- **不要硬编码颜色** —— `bg-background` / `border-input` / `placeholder:text-muted-foreground` 都是 design token
 
 ## Examples
 
@@ -76,13 +77,23 @@ import { Textarea } from '@/components/ui/textarea';
 // 基础
 <Textarea placeholder="留下你的反馈..." />
 
-// 自动高度
+// 自动高度(推荐配 maxRows)
 <Textarea autoSize={{ minRows: 3, maxRows: 8 }} placeholder="..." />
 
 // 字数统计
 <Textarea showCount maxLength={500} placeholder="不超过 500 字" />
 
-// 受控
-const [v, setV] = React.useState('');
-<Textarea value={v} onChange={(e) => setV(e.target.value)} />
+// 错误态
+<Textarea error defaultValue="非法内容" />
 ```
+
+## Migration · 从旧 `@/components/input/input` 迁移
+
+v0.2 起 Textarea 拆为独立 entry,import 路径变化:
+
+```diff
+- import { Textarea } from '@/components/input/input';
++ import { Textarea } from '@/components/textarea/textarea';
+```
+
+CLI 命令:`teamix-evo ui add textarea`(单独安装,不再需要先装 input)。组件 API 完全保持不变。

package/src/components/textarea/textarea.stories.tsx

@@ -1,34 +1,39 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
 import { Textarea } from './textarea';
 
 const meta: Meta<typeof Textarea> = {
-  title: '表单与输入 · Form/Textarea',
+  title: '数据录入 · Data Entry/Textarea',
   component: Textarea,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '多行文本输入 — 用于输入多行文本信息。shadcn `Textarea` 原子 + antd `Input.TextArea` 的并集能力：支持 `autoSize`（传 `{ minRows, maxRows }` 随内容自适应高度）、`showCount` 发表字数计数、`maxLength` 限制。',
+          'Textarea 多行文本框 —— shadcn 简洁基底 + antd `Input.TextArea` 的 `autoSize` / `showCount` 并集。`size` 三档字号与 Input 对齐(高度由 `rows` / `autoSize` 决定,**不受 size 影响**)。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
   argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
     rows: { control: 'number' },
-    maxLength: { control: 'number' },
     showCount: { control: 'boolean' },
+    error: { control: 'boolean' },
     disabled: { control: 'boolean' },
     placeholder: { control: 'text' },
+    maxLength: { control: 'number' },
   },
   args: {
+    size: 'md',
     rows: 3,
-    placeholder: '请输入...',
     showCount: false,
+    error: false,
     disabled: false,
+    placeholder: '请输入...',
   },
   decorators: [
     (Story) => (
-      <div className="w-80">
+      <div className="w-96">
         <Story />
       </div>
     ),
@@ -40,6 +45,7 @@ type Story = StoryObj<typeof Textarea>;
 
 export const Playground: Story = {};
 
+/** 自动高度 —— `autoSize={{ minRows, maxRows }}` 让高度随内容生长,粘贴大段文本不撑爆容器。 */
 export const AutoSize: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -50,6 +56,7 @@ export const AutoSize: Story = {
   ),
 };
 
+/** 字数统计 —— `showCount` 必须配 `maxLength`,缺一不显示。 */
 export const ShowCount: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -57,6 +64,25 @@ export const ShowCount: Story = {
   ),
 };
 
+/** 三档字号 —— 高度仍由 rows 决定,只有字号变化(text-xs / text-xs / text-sm)。 */
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Textarea size="sm" placeholder="Small (text-xs)" />
+      <Textarea size="md" placeholder="Medium (text-xs)" />
+      <Textarea size="lg" placeholder="Large (text-sm)" />
+    </div>
+  ),
+};
+
+/** 错误态 —— `error` 自动设置 `aria-invalid="true"` + destructive 边框 / ring。 */
+export const Error: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Textarea error defaultValue="非法内容" />,
+};
+
+/** 禁用态。 */
 export const Disabled: Story = {
   parameters: { controls: { disable: true } },
   render: () => <Textarea disabled defaultValue="这是只读的内容,不可编辑。" />,

package/src/components/textarea/textarea.tsx

@@ -2,8 +2,16 @@ import * as React from 'react';
 
 import { cn } from '@/utils/cn';
 
+// ─── Textarea ───────────────────────────────────────────────────────────────
+//
+// 多行文本输入。高度由 `rows` / `autoSize` 决定,`size` 仅控制字号档位与 Input 一致。
+// 与 Input 拆分独立 entry(对齐 shadcn 2025-10 拆分粒度)。
+
 export interface TextareaProps
-  extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'rows'> {
+  extends Omit<
+    React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+    'rows' | 'size'
+  > {
   /**
    * 自动高度。`true` 时无上下限;传 `{ minRows, maxRows }` 时受限。
    * 实现:监听 input 事件,把 textarea 设为 auto 后再读 scrollHeight。
@@ -15,6 +23,17 @@ export interface TextareaProps
    * @default false
    */
   showCount?: boolean;
+  /**
+   * 字号档位,与 `Input` 三档对齐:`sm`(text-xs) / `md`(text-xs,默认) / `lg`(text-sm)。
+   * 高度由 `rows` / `autoSize` 决定,不受 size 影响。
+   * @default "md"
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /**
+   * 错误态(快捷开关),会同时设置 `aria-invalid`,渲染 destructive 边框 / ring。
+   * @default false
+   */
+  error?: boolean;
   /** 受控值。 */
   value?: string;
   /** uncontrolled 初始值。 */
@@ -29,19 +48,23 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       className,
       autoSize = false,
       showCount = false,
+      size = 'md',
+      error = false,
       value,
       defaultValue,
       rows = 3,
       onChange,
       maxLength,
+      'aria-invalid': ariaInvalidProp,
       ...props
     },
     ref,
   ) => {
+    const ariaInvalid = ariaInvalidProp ?? (error ? true : undefined);
+    const sizeClass =
+      size === 'sm' ? 'text-xs' : size === 'lg' ? 'text-sm' : 'text-xs';
     const isControlled = value !== undefined;
-    const [internal, setInternal] = React.useState<string>(
-      defaultValue ?? '',
-    );
+    const [internal, setInternal] = React.useState<string>(defaultValue ?? '');
     const current = isControlled ? value : internal;
 
     const innerRef = React.useRef<HTMLTextAreaElement | null>(null);
@@ -62,8 +85,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       el.style.height = 'auto';
       const next = el.scrollHeight;
       const opts = typeof autoSize === 'object' ? autoSize : {};
-      const minH =
-        (opts.minRows ?? 0) * lineHeight + padTop + padBottom;
+      const minH = (opts.minRows ?? 0) * lineHeight + padTop + padBottom;
       const maxH = opts.maxRows
         ? opts.maxRows * lineHeight + padTop + padBottom
         : Number.POSITIVE_INFINITY;
@@ -85,9 +107,11 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         value={isControlled ? value : undefined}
         defaultValue={!isControlled ? defaultValue : undefined}
         maxLength={maxLength}
+        aria-invalid={ariaInvalid}
         onChange={handleChange}
         className={cn(
-          'flex w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+          'flex w-full rounded-md border border-input bg-background px-3 py-2 shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive',
+          sizeClass,
           autoSize ? 'resize-none' : 'min-h-textarea',
           className,
         )}
@@ -97,7 +121,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
 
     if (showCount && maxLength) {
       return (
-        <div className="space-y-1">
+        <div className="flex flex-col gap-1">
           {textarea}
           <div className="text-right text-xs text-muted-foreground tabular-nums">
             {current?.length ?? 0} / {maxLength}

package/src/components/time-picker/time-picker.meta.md

@@ -3,57 +3,86 @@ id: time-picker
 name: TimePicker
 displayName: 时间选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
 
 # TimePicker 时间选择
 
-时间选择 — antd 独有补足。**等价 antd `TimePicker`** 的基础能力,基于原生 `<input type="time">` 样式封装(零 JS、移动端友好、SSR safe)。配 `DatePicker` 完成日期 + 时间填写。
+时间选择 — 输入框 + 滚动列面板。提供两种形态:
+
+- `<TimePicker />` — 单值(对应 antd `TimePicker`)
+- `<TimeRangePicker />` — 范围(对应 antd `TimePicker.RangePicker`)
+
+内核为 Radix Popover + 自研 `TimeColumn` 滚动列(每列单独滚动、点选高亮、自动 scroll into view),完全替换原 `<input type="time">` 实现以贴合 OpenTrek 设计语言。
 
 ## When to use
 
-- 表单字段需要时分(可选秒)输入(会议预约、闹钟、营业时间)
-- 配 `DatePicker` 完整时间戳填写(日期 + 时间)
+- 表单需要时分(可选秒)精确输入(会议预约、闹钟、营业时间)
+- 需要时间区间(开始-结束)→ 用 `TimeRangePicker`
+- 配 `DatePicker` 的 `showTime` 完成日期 + 时间填写
 
 ## When NOT to use
 
-- 时间区间(开始 - 结束)→ 用两个 TimePicker 并排,或后续基于 Popover 自实现 RangeTimePicker
-- 日期 → `DatePicker`(日期 + 时间二合一也可在 DatePicker 上拓展)
-- 复杂禁用规则 / 自定义面板:当前实现走原生,**不支持** `disabledHours` / `disabledMinutes` 等 antd 高级 API — 需要时基于 Popover + ListBox 自实现
+- 仅需日期 → `DatePicker`(纯日期模式)
+- 不需要面板交互、SSR safe 优先、移动端原生体验 → 直接用原生 `<input type="time">`
 
 ## Props
 
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控值(由 `format` 决定字面)。空串表示未选。 |
+| `defaultValue` | `string` | – | – | 非受控初值。 |
+| `onChange` | `(value: string) => void` | – | – | 值变化回调(选中或清除时触发)。 |
+| `format` | `string` | `"HH:mm:ss"` | – | 时间格式(date-fns / antd 风格 token):支持 `HH/H/mm/m/ss/s`。 不含 `s` token 时不渲染秒列。 |
+| `hourStep` | `number` | `1` | – | 小时步长(antd 并集)。 |
+| `minuteStep` | `number` | `1` | – | 分钟步长。 |
+| `secondStep` | `number` | `1` | – | 秒步长。 |
+| `disabledHours` | `() => number[]` | – | – | 禁用小时回调,返回禁用的小时数组。 |
+| `disabledMinutes` | `(hour: number) => number[]` | – | – | 禁用分钟回调,接收当前选中小时。 |
+| `disabledSeconds` | `(hour: number, minute: number) => number[]` | – | – | 禁用秒回调,接收当前选中小时/分钟。 |
+| `placeholder` | `string` | `"请选择时间"` | – | 占位文本。 |
+| `disabled` | `boolean` | – | – | 是否禁用。 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `"md"` | – | 触发器尺寸(对齐 Input)。 |
+| `error` | `boolean` | `false` | – | 错误态(同时设置 `aria-invalid`)。 |
+| `hasClear` | `boolean` | `true` | – | 显示清除按钮(antd `allowClear` 并集)。有值时显示 X,空值还原为时钟 icon。 |
+| `className` | `string` | – | – | 触发器 className。 |
+| `id` | `string` | – | – | 触发器 id(用于 label htmlFor)。 |
+| `status` | `'default' \| 'error' \| 'warning'` | `"default"` | – | 校验状态(对齐 antd `status`)— `'error'` / `'warning'` / `'default'`。 与 `error` 并存时,`status='error'` 优先。 |
+| `open` | `boolean` | – | – | 受控弹层显隐(对齐 antd `open`)。 业务侧需要"程序化打开 / 关闭"时使用;不传则组件内部自管。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹层显隐变化回调。 |
+| `inputReadOnly` | `boolean` | `false` | – | 输入框只读 — 仅能通过点击弹层选择,不能直接键入(对齐 antd `inputReadOnly`)。 |
+<!-- auto:props:end -->
 
-| 名称           | 类型                        | 默认值         | 必填 | 说明                                                                 |
-| -------------- | --------------------------- | -------------- | ---- | -------------------------------------------------------------------- |
-| `value`        | `string`                    | –              | –    | 受控值(`HH:mm` 或 `HH:mm:ss`)— 空串表示未选。                        |
-| `defaultValue` | `string`                    | –              | –    | uncontrolled 初值。                                                  |
-| `onChange`     | `(value: string) => void`   | –              | –    | 值变化回调(实时,跟随原生 input)。                                    |
-| `showSeconds`  | `boolean`                   | `false`        | –    | 是否显示秒(antd `showSeconds` 并集)— 关闭时原生 input 仅显示 HH:mm。 |
-| `step`         | `number`                    | `60`           | –    | 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。         |
-| `size`         | `'sm' \| 'default' \| 'lg'` | `"default"`    | –    | 尺寸。                                                               |
-| `min`          | `string`                    | –              | –    | 最小可选时间(antd `minDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。       |
-| `max`          | `string`                    | –              | –    | 最大可选时间(antd `maxDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。       |
-| `allowClear`   | `boolean`                   | `false`        | –    | 是否显示清除按钮(antd `allowClear` 并集)。                           |
-| `status`       | `'error' \| 'warning'`      | –              | –    | 校验状态,影响边框颜色(antd `status` 并集)。                          |
-| `placeholder`  | `string`                    | `"请选择时间"` | –    | 占位文本。                                                           |
+## TimeRangePicker Props
 
-<!-- auto:props:end -->
+`TimeRangePicker` 共享 `TimePicker` 的所有 prop(format / hourStep / minuteStep / secondStep / disabledHours / disabledMinutes / disabledSeconds / size / disabled / error / clearable / className / id),并增加:
+
+| 名称           | 类型                                | 默认值                        | 必填 | 说明                                         |
+| -------------- | ----------------------------------- | ----------------------------- | ---- | -------------------------------------------- |
+| `value`        | `[string, string]`                  | –                             | –    | 受控值(`[起始, 结束]`)。空串表示对应端未选。 |
+| `defaultValue` | `[string, string]`                  | –                             | –    | 非受控初值。                                 |
+| `onChange`     | `(value: [string, string]) => void` | –                             | –    | 值变化回调(点击「确定」时触发)。             |
+| `placeholders` | `[string, string]`                  | `["请选择时间","请选择时间"]` | –    | 起始 / 结束占位文本。                        |
 
 ## 依赖
 
-<!-- auto:deps:begin -->
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
+<!-- auto:deps:begin -->
 ### 同库依赖
 
 > `teamix-evo ui add time-picker` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
 
 ### npm 依赖
 
@@ -62,45 +91,85 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
-- **value 格式必为 `HH:mm` 或 `HH:mm:ss`** — 与原生 input[type=time] 一致,**不要**传 ISO 字符串
-- **`showSeconds=true` 才会显示秒** — 默认隐藏,绝大多数场景不需要秒
-- **`step`** 单位是**秒**(原生规范) — `step=900` 表示 15 分钟一档
-- **空状态用空字符串** `""`,不要传 `null` / `undefined`(原生 input 不接受 null)
-- **当前实现不支持 12 小时制 / AM-PM** — 浏览器根据系统 locale 自动决定显示格式;**不要**手动加 AM/PM 字段
-- **`allowClear` 仅在受控模式下有意义** — 点击清除会触发 `onChange('')`
-- **`status` 配 `Form` 使用** — 校验失败时传 `status="error"`,不要手动写 `className="border-destructive"`
-- **`min` / `max` 是原生约束** — 浏览器会阻止选择范围外的时间,但手动输入仍可绕过,严格场景需配 zod 校验
+- **`format` 决定列的显隐**:有 `s/ss` 才显示秒列,没有 `m/mm` 时不显示分钟列。**默认 "HH:mm:ss"** —— 单纯需要时分用 `format="HH:mm"`,**不要**为了"隐藏秒"而魔改样式
+- **value 必须能被 `parseTime` 解析**:格式宽松,按非数字切分;但**强烈建议**与 `format` 保持一致,避免来回 round-trip 时丢失字段
+- **`hourStep` / `minuteStep` / `secondStep` 是渲染步长**:仅决定可选项粒度,**不会**自动把已有值往档位上对齐(由消费方负责)
+- **`disabledHours` / `disabledMinutes` / `disabledSeconds` 是高阶函数**:`disabledMinutes(hour)` 接收当前选中小时;切换小时后自动重新计算可选分钟。**不要**手动写 useState 维护可选集
+- **空状态用空字符串** `""`,不要传 `null` / `undefined`(受控模式时类型即不允许)
+- **Range 模式点「确定」才触发 `onChange`**:面板内的滚动调整只更新内部 draft;关闭面板等价于"取消"
+- **`error` 是布尔开关**(对齐 Input);消费方可以直接 `aria-invalid` 也能达到同效果
+- **`clearable` 仅在有值时显示**:点击清除会触发 `onChange('')` / `onChange(['', ''])`
 
 ## Examples
 
 ```tsx
-import { TimePicker } from '@/components/ui/time-picker';
+import { TimePicker, TimeRangePicker } from '@/components/ui/time-picker';
 import * as React from 'react';
 
-// 基础(HH:mm)
-<TimePicker defaultValue="09:30" />
+// 基础(默认 HH:mm:ss)
+<TimePicker defaultValue="09:30:00" />
 
-// 受控 + 秒 + 可清除
+// 受控 + 可清除
 const [t, setT] = React.useState('09:30:00');
-<TimePicker value={t} onChange={setT} showSeconds allowClear />
+<TimePicker value={t} onChange={setT} clearable />
+
+// 只显示时:分
+<TimePicker format="HH:mm" defaultValue="09:30" />
 
-// 15 分钟一档
-<TimePicker step={15 * 60} />
+// 5 分钟一档,禁用工作时间外
+<TimePicker
+  minuteStep={5}
+  disabledHours={() => [0, 1, 2, 3, 4, 5, 6, 7, 8, 19, 20, 21, 22, 23]}
+/>
 
-// 限制工作时间范围
-<TimePicker defaultValue="09:00" min="09:00" max="18:00" />
+// 错误态
+<TimePicker error defaultValue="09:00:00" />
 
-// 校验状态
-<TimePicker defaultValue="09:00" status="error" />
+// 范围
+const [r, setR] = React.useState<[string, string]>(['09:00', '18:00']);
+<TimeRangePicker value={r} onChange={setR} format="HH:mm" clearable />
 
-// 与 DatePicker 配对
-<div className="flex gap-2">
-  <DatePicker />
-  <TimePicker />
-</div>
+// 与 DatePicker.showTime 配对(走 DatePicker)
+<DatePicker showTime />
 ```
+
+---
+
+## TimePicker 形态 — 旧库 API → 新映射
+
+> 旧库 `TimePicker2`(hybridcloud) → 新库 `TimePicker` + `TimeRangePicker`(独立导出)。
+> 新库值类型为 `string`(如 `"09:30:00"`)，不依赖 moment / dayjs。
+
+### 命名 & 结构映射
+
+| 旧库                             | 新库                                        | 说明                           |
+| -------------------------------- | ------------------------------------------- | ------------------------------ |
+| `TimePicker2`                    | `TimePicker`                                | 组件名简化                     |
+| `TimePicker2.RangePicker`        | `TimeRangePicker`                           | 独立导出(非挂载)               |
+| `value` (Dayjs)                  | `value` (string)                            | 类型变更，无日期库依赖         |
+| `onChange(Dayjs, string)`        | `onChange(string)`                          | 签名简化，直接返回格式化字符串 |
+| `size: large/medium/small`       | `size: 'sm' \| 'md' \| 'lg'`                | md = medium                    |
+| `state="error"`                  | `error={true}`                              | 布尔开关(对齐 Input)           |
+| `format` (HH:mm:ss)              | `format` (HH:mm:ss)                         | 相同语法                       |
+| `disabledHours(i) => bool`       | `disabledHours() => number[]`               | 返回禁用数组(对齐 antd v5)     |
+| `disabledMinutes(h,i) => bool`   | `disabledMinutes(hour) => number[]`         | 返回禁用数组                   |
+| `disabledSeconds(h,m,i) => bool` | `disabledSeconds(hour, minute) => number[]` | 返回禁用数组                   |
+| `hasClear`                       | `hasClear`                                  | 命名保留                       |
+| `visible / onVisibleChange`      | _(未来 P2)_                                 | MVP 内部管理                   |
+| `ranges` (快捷值)                | _(未来 P2: presets)_                        | MVP 不含预设                   |
+| `label`                          | 不复刻                                      | 用外部 FormItem label          |
+| `hasBorder`                      | 不复刻                                      | className 覆盖                 |
+| `isPreview / renderPreview`      | 不复刻                                      | 新库无预览态                   |
+
+### 迁移 FAQ
+
+| 问题                    | 回答                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| Dayjs → string 怎么转?  | `dayjs.format('HH:mm:ss')` 即可;反向 `dayjs(str, 'HH:mm:ss')`                      |
+| disabledHours 签名差异? | 旧: `(hour) => boolean` 返回单项是否禁用;新: `() => number[]` 返回所有禁用小时数组 |
+| Range 值结构?           | 旧: `[Dayjs, Dayjs]` → 新: `[string, string]`，如 `['09:00', '18:00']`             |
+| 只要时分怎么办?         | `format="HH:mm"`，自动隐藏秒列                                                     |