@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,38 +1,78 @@
 ---
 id: time-picker
 name: TimePicker
+displayName: 时间选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# TimePicker
+# 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` | – | – | 受控值(`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"` | – | 尺寸。 |
+| `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 -->
 
+## TimeRangePicker Props
+
+`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]`                  | `["请选择时间","请选择时间"]` | –    | 起始 / 结束占位文本。                        |
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -41,6 +81,8 @@ package: "@teamix-evo/ui"
 | 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 依赖
 
@@ -53,31 +95,81 @@ pnpm add lucide-react@^0.460.0
 
 ## 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 字段
+- **`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 />
+<TimePicker value={t} onChange={setT} clearable />
+
+// 只显示时:分
+<TimePicker format="HH:mm" defaultValue="09:30" />
+
+// 5 分钟一档,禁用工作时间外
+<TimePicker
+  minuteStep={5}
+  disabledHours={() => [0, 1, 2, 3, 4, 5, 6, 7, 8, 19, 20, 21, 22, 23]}
+/>
+
+// 错误态
+<TimePicker error defaultValue="09:00:00" />
 
-// 15 分钟一档
-<TimePicker step={15 * 60} />
+// 范围
+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"`，自动隐藏秒列                                                     |

package/src/components/time-picker/time-picker.stories.tsx

@@ -1,32 +1,42 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { TimePicker } from './time-picker';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { TimePicker, TimeRangePicker } from './time-picker';
 
 const meta: Meta<typeof TimePicker> = {
-  title: '表单与输入 · Form/TimePicker',
+  title: '数据录入 · Data Entry/TimePicker',
   component: TimePicker,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '时间选择 — 基于原生 input[type=time] 样式封装(零 JS、移动端友好、SSR safe)。等价 antd `TimePicker` 基础能力,复杂禁用规则需自实现。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          'TimePicker 时间选择 —— 选择一个时间点或一段时间区间。Radix Popover 容器 + 自研 TimeColumn 滚动列(对齐 antd `TimePicker` / `TimePicker.RangePicker`,shadcn 未提供原子,本组件做并集补足):关键 prop 包括 `format` / `hourStep` / `minuteStep` / `secondStep` / `disabledHours` / `disabledMinutes` / `disabledSeconds` / `hasClear` / `size` / `error`。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
   argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
-    showSeconds: { control: 'boolean' },
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
+    format: { control: 'text' },
     disabled: { control: 'boolean' },
+    hasClear: { control: 'boolean' },
+    error: { control: 'boolean' },
+    placeholder: { control: 'text' },
+  },
+  args: {
+    size: 'md',
+    format: 'HH:mm:ss',
+    disabled: false,
+    hasClear: true,
+    error: false,
+    placeholder: '请选择时间',
   },
-  args: { size: 'default', showSeconds: false, disabled: false },
 };
 
 export default meta;
 type Story = StoryObj<typeof TimePicker>;
 
 export const Playground: Story = {
-  render: (args) => <TimePicker {...args} defaultValue="09:30" />,
+  render: (args) => <TimePicker {...args} defaultValue="09:30:00" />,
 };
 
 export const Controlled: Story = {
@@ -35,25 +45,85 @@ export const Controlled: Story = {
     const [t, setT] = React.useState('09:30:00');
     return (
       <div className="flex items-center gap-3">
-        <TimePicker value={t} onChange={setT} showSeconds />
-        <span className="text-sm text-muted-foreground tabular-nums">{t || '(空)'}</span>
+        <TimePicker value={t} onChange={setT} />
+        <span className="text-sm text-muted-foreground tabular-nums">
+          {t || '(空)'}
+        </span>
       </div>
     );
   },
 };
 
-export const QuarterHourStep: Story = {
+export const HourMinute: Story = {
+  name: '只显示时:分',
+  parameters: { controls: { disable: true } },
+  render: () => <TimePicker format="HH:mm" defaultValue="09:30" />,
+};
+
+export const StepFiveMinutes: Story = {
+  name: '5 分钟一档',
   parameters: { controls: { disable: true } },
-  render: () => <TimePicker showSeconds step={15 * 60} defaultValue="10:00:00" />,
+  render: () => (
+    <TimePicker minuteStep={5} secondStep={10} defaultValue="10:00:00" />
+  ),
+};
+
+export const DisabledHours: Story = {
+  name: '禁用工作时间外',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TimePicker
+      defaultValue="09:00:00"
+      disabledHours={() => [
+        ...Array.from({ length: 9 }, (_, i) => i), // 0-8
+        ...Array.from({ length: 5 }, (_, i) => 19 + i), // 19-23
+      ]}
+    />
+  ),
 };
 
 export const Sizes: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex items-center gap-3">
-      <TimePicker size="sm" defaultValue="09:00" />
-      <TimePicker size="default" defaultValue="09:00" />
-      <TimePicker size="lg" defaultValue="09:00" />
+      <TimePicker size="sm" defaultValue="09:00:00" />
+      <TimePicker size="md" defaultValue="09:00:00" />
+      <TimePicker size="lg" defaultValue="09:00:00" />
     </div>
   ),
 };
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <TimePicker disabled defaultValue="09:00:00" />,
+};
+
+export const ErrorState: Story = {
+  name: '错误态',
+  parameters: { controls: { disable: true } },
+  render: () => <TimePicker error defaultValue="09:00:00" />,
+};
+
+export const RangePlayground: StoryObj<typeof TimeRangePicker> = {
+  name: 'Range / 范围选择',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [r, setR] = React.useState<[string, string]>(['', '']);
+    return (
+      <div className="flex flex-col gap-3">
+        <TimeRangePicker value={r} onChange={setR} />
+        <span className="text-sm text-muted-foreground tabular-nums">
+          {r[0] && r[1] ? `${r[0]} ~ ${r[1]}` : '(未选)'}
+        </span>
+      </div>
+    );
+  },
+};
+
+export const RangeHourMinute: StoryObj<typeof TimeRangePicker> = {
+  name: 'Range · 时:分',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TimeRangePicker defaultValue={['09:00', '18:00']} format="HH:mm" />
+  ),
+};