@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/data-table/data-table.meta.md

@@ -30,18 +30,16 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-| 名称                   | 类型                                                      | 默认值 | 必填 | 说明                                                                                                                                         |
-| ---------------------- | --------------------------------------------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `columns`              | `ColumnDef<TData, TValue>[]`                              | –      | ✓    | 列定义(TanStack ColumnDef)。                                                                                                                 |
-| `data`                 | `TData[]`                                                 | –      | ✓    | 行数据。                                                                                                                                     |
-| `pagination`           | `boolean \| { pageSize?: number; siblingCount?: number }` | `true` | –    | 是否启用分页(antd `pagination` 并集)。 传 `true` 用默认配置;传对象自定义 pageSize / siblingCount。                                           |
-| `sorting`              | `boolean`                                                 | `true` | –    | 是否启用排序(列定义里的 `enableSorting` 也要打开;默认列已开)。                                                                               |
-| `filtering`            | `boolean`                                                 | `true` | –    | 是否启用列过滤(每列 `header` 配 input 单独使用;此 flag 控制 columnFilters 状态)。                                                            |
-| `onRowSelectionChange` | `(selectedRows: TData[]) => void`                         | –      | –    | 行选择回调(antd `rowSelection.onChange` 并集)。传入即启用 selection。 Selected rows 的原始 data 通过 `getRowId(row)` 推断,默认是 row.index。 |
-| `emptyText`            | `React.ReactNode`                                         | –      | –    | 空数据时显示的内容。                                                                                                                         |
-| `className`            | `string`                                                  | –      | –    | 容器 className。                                                                                                                             |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `columns` | `ColumnDef<TData, TValue>[]` | – | ✓ | 列定义(TanStack ColumnDef)。 |
+| `data` | `TData[]` | – | ✓ | 行数据。 |
+| `pagination` | `boolean \| { pageSize?: number; siblingCount?: number }` | `true` | – | 是否启用分页(antd `pagination` 并集)。 传 `true` 用默认配置;传对象自定义 pageSize / siblingCount。 |
+| `sorting` | `boolean` | `true` | – | 是否启用排序(列定义里的 `enableSorting` 也要打开;默认列已开)。 |
+| `filtering` | `boolean` | `true` | – | 是否启用列过滤(每列 `header` 配 input 单独使用;此 flag 控制 columnFilters 状态)。 |
+| `onRowSelectionChange` | `(selectedRows: TData[]) => void` | – | – | 行选择回调(antd `rowSelection.onChange` 并集)。传入即启用 selection。 Selected rows 的原始 data 通过 `getRowId(row)` 推断,默认是 row.index。 |
+| `emptyText` | `React.ReactNode` | – | – | 空数据时显示的内容。 |
+| `className` | `string` | – | – | 容器 className。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -49,15 +47,14 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add data-table` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry        | 类型      | 描述                                                                                                            |
-| ------------ | --------- | --------------------------------------------------------------------------------------------------------------- |
-| `cn`         | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                                              |
-| `table`      | component | 基础表格 — 原生 HTML 元素薄包装(视觉骨架,无交互,交互见 DataTable)                                               |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `table` | component | 基础表格 — 原生 HTML 元素薄包装(视觉骨架,无交互,交互见 DataTable) |
 | `pagination` | component | 分页 — shadcn primitives + 高阶 SimplePagination(antd 风格 total/pageSize/current/onChange,自动页码窗口 + 折叠) |
 
 ### npm 依赖
@@ -67,7 +64,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add @tanstack/react-table@^8.0.0
 ```
-
 <!-- auto:deps:end -->
 
 > 透传 TanStack Table 的核心能力。需要更精细控制(可控 state、virtualizer、column visibility / resizing 等),请直接用 `useReactTable` + 基础 `Table` primitives 自行拼装。

package/src/components/data-table/data-table.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ArrowUpDown } from 'lucide-react';
 import { DataTable, type ColumnDef } from './data-table';
 import { Button } from '@/components/button/button';

package/src/components/data-table/data-table.tsx

@@ -119,8 +119,8 @@ function DataTable<TData, TValue>({
   const total = table.getFilteredRowModel().rows.length;
 
   return (
-    <div className={cn('space-y-3', className)}>
-      <div className="rounded-md border">
+    <div className={cn('flex flex-col gap-3', className)}>
+      <div className="rounded-md border border-border">
         <Table>
           <TableHeader>
             {table.getHeaderGroups().map((headerGroup) => (

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

@@ -3,7 +3,7 @@ id: date-picker
 name: DatePicker
 displayName: 日期选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -15,53 +15,46 @@ package: '@teamix-evo/ui'
 - `<DatePicker />` — 单日(对应 antd `DatePicker`)
 - `<DateRangePicker />` — 范围(对应 antd `DatePicker.RangePicker`)
 
-格式化用 `date-fns`(轻量、模块化、tree-shake 友好)。
+通过 `showTime` 可在右侧追加 `TimePickerPanel`,组合出日期 + 时间选择器(对齐 antd `DatePicker showTime`)。格式化用 `date-fns`(轻量、模块化、tree-shake 友好)。
 
 ## When to use
 
 - 表单中的单日 / 范围选择
 - 报表 / 数据筛选的时间维度
 - 预约 / 计划 / 日程
+- 需要精确到时分秒的时间戳 → `showTime`
 
 ## When NOT to use
 
 - 仅显示日期(只读)→ `<time>{format(d, '...')}</time>`
 - 内联日历 → 直接用 `Calendar`
-- 时间选择(含时分秒)→ 配 `Input type="time"` 或 v0.x TimePicker
+- 仅时间(无日期)→ `TimePicker`
 
 ## Props
 
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-#### DatePicker
-
-| 名称            | 类型                                 | 默认值         | 必填 | 说明                                                 |
-| --------------- | ------------------------------------ | -------------- | ---- | ---------------------------------------------------- |
-| `value`         | `Date`                               | –              | –    | 受控值 — 当前选中日期。                              |
-| `onChange`      | `(value: Date \| undefined) => void` | –              | –    | 选中日期变化回调。                                   |
-| `placeholder`   | `string`                             | `"选择日期"`   | –    | 占位文本（未选时）。                                 |
-| `format`        | `string`                             | `"yyyy-MM-dd"` | –    | date-fns format 字符串。                             |
-| `size`          | `'sm' \| 'default' \| 'lg'`          | –              | –    | 触发器尺寸。                                         |
-| `className`     | `string`                             | –              | –    | 触发器 className（传给底层 Button）。                |
-| `disabled`      | `boolean`                            | –              | –    | 触发器是否禁用。                                     |
-| `disabledDates` | `(date: Date) => boolean`            | –              | –    | 不可选日期 predicate（透传到 Calendar `disabled`）。 |
-
-#### DateRangePicker
-
-| 名称             | 类型                                      | 默认值           | 必填 | 说明                     |
-| ---------------- | ----------------------------------------- | ---------------- | ---- | ------------------------ |
-| `value`          | `DateRange`                               | –                | –    | 受控值 — 当前选中范围。  |
-| `onChange`       | `(value: DateRange \| undefined) => void` | –                | –    | 范围变化回调。           |
-| `placeholder`    | `string`                                  | `"选择日期范围"` | –    | 占位文本。               |
-| `format`         | `string`                                  | `"yyyy-MM-dd"`   | –    | date-fns format 字符串。 |
-| `size`           | `'sm' \| 'default' \| 'lg'`               | –                | –    | 触发器尺寸。             |
-| `className`      | `string`                                  | –                | –    | 触发器 className。       |
-| `disabled`       | `boolean`                                 | –                | –    | 是否禁用。               |
-| `disabledDates`  | `(date: Date) => boolean`                 | –                | –    | 不可选日期 predicate。   |
-| `numberOfMonths` | `number`                                  | `2`              | –    | 同时显示几个月历。       |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `picker` | `'date' \| 'month' \| 'year'` | `"date"` | – | 选择粒度(antd `picker` 并集) — 决定弹出面板类型: - `'date'`(默认) — 日历面板(选择具体日期) - `'month'` — 月份网格(选择到月) - `'year'` — 年份网格(选择到年) |
+| `value` | `Date` | – | – | 受控值 — 当前选中日期(`showTime` 时含时间)。 |
+| `defaultValue` | `Date` | – | – | 非受控初始值(对齐 antd / cd `defaultValue`)。仅在未传 `value` 时生效。 |
+| `onChange` | `(value: Date \| undefined) => void` | – | – | 选中变化回调。`showTime` 时点击「确定」才触发,否则点击日期立即触发。 |
+| `placeholder` | `string` | `"选择日期"` | – | 占位文本。 |
+| `format` | `string` | `"yyyy-MM-dd"` | – | 显示格式(date-fns 语法)。`showTime` 时建议含时间 token,如 `yyyy-MM-dd HH:mm:ss`。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"md"` | – | 触发器尺寸。 |
+| `className` | `string` | – | – | 触发器 className。 |
+| `disabled` | `boolean` | – | – | 是否禁用。 |
+| `disabledDates` | `(date: Date) => boolean` | – | – | 不可选日期 predicate。 |
+| `showTime` | `boolean \| ShowTimeConfig` | `false` | – | 显示时间选择器(antd `showTime` 并集)。 - `true` — 启用,使用默认 `HH:mm:ss` 格式 - `ShowTimeConfig` — 详细配置(format / 默认值 / 步长 / 禁用回调) - `false` / 缺省 — 仅日期(默认行为,向后兼容) |
+| `presets` | `boolean \| DatePickerPreset[]` | `false` | – | 弹层底部快捷 preset 链接(对齐 antd / cloud-design DatePicker2 的 `presets` 能力)。 - `true` — 启用内置默认集(今天 / 昨天) - `DatePickerPreset[]` — 自定义集 - `false` / 缺省 — 不显示 |
+| `hasClear` | `boolean` | `true` | – | 显示清除按钮(antd `allowClear` 并集);有值时显示 X 替代日历图标,点击清空 value。 |
+| `status` | `'default' \| 'error' \| 'warning'` | `"default"` | – | 校验状态(对齐 antd `status`) — 控制触发器边框 / 字体颜色: - `'error'` — 红色 destructive 边框 + `aria-invalid="true"` - `'warning'` — 警告色边框 - `'default'` / 缺省 — 中性边框 |
+| `open` | `boolean` | – | – | 受控弹层显隐(对齐 antd `open`)。 业务侧需要"程序化打开 / 关闭"时使用;不传则组件内部自管。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹层显隐变化回调(对齐 antd `onOpenChange`)。 |
+| `footer` | `React.ReactNode` | – | – | 弹层底部自定义 footer(对齐 antd `footer / renderExtraFooter`)。 与 `presets` 共存时,footer 渲染在 presets 之下。 |
+| `inputReadOnly` | `boolean` | `false` | – | 输入框只读 — 仅能通过点击弹层选择,不能直接键入(对齐 antd `inputReadOnly`)。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -69,17 +62,17 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add date-picker` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry      | 类型      | 描述                                                                                    |
-| ---------- | --------- | --------------------------------------------------------------------------------------- | -------- | --------------------------- |
-| `cn`       | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                      |
-| `button`   | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
-| `calendar` | component | 日期选择面板 — react-day-picker,mode=single                                             | multiple | range,与 design tokens 对齐 |
-| `popover`  | component | 可交互浮层 — Radix Popover + antd arrow 并集                                            |
+| 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)。 |
+| `calendar` | component | 日期选择面板 — react-day-picker,mode=single|multiple|range,与 design tokens 对齐 |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
+| `time-picker` | component | 时间选择 — Popover + 滚动列(TimeColumn)面板,含 TimePicker / TimeRangePicker / TimePickerPanel(对齐 antd TimePicker / TimePicker.RangePicker) |
 
 ### npm 依赖
 
@@ -88,15 +81,15 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add date-fns@^3.0.0 react-day-picker@^9.0.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
 - **`format` 用 date-fns 字符串**:`yyyy-MM-dd` / `yyyy 年 M 月 d 日` 等;**不要**用旧 moment 写法(`YYYY-MM-DD` 大写在 date-fns 是年的"week year",非"calendar year")
+- **`showTime` 启用后默认 `format` 自动变为 `yyyy-MM-dd HH:mm:ss`**:如自定义 `showTime={{ format: 'HH:mm' }}`,记得**同时**调整外层 `format`,否则触发器显示 `:00` 秒位
+- **`showTime` 模式下点「确定」才触发 `onChange`**:面板内调整日期/时间只更新内部 draft;关闭等价于「取消」(对齐 antd 行为)
 - **`disabledDates` 而非外部过滤**:把禁用判断 push 给 Calendar,避免选完再被刷掉的尴尬
-- **范围选择默认 2 个月**:`numberOfMonths={2}` 是行业惯例(antd / shadcn / Material 都是)
-- **小尺寸的范围选择需要更宽容器**:`<DateRangePicker />` 默认 w-72,不够的话 className 加宽
+- **范围选择默认 2 个月**:`numberOfMonths={2}` 是行业惯例(antd / shadcn / Material 都是);`showTime` 时建议 `numberOfMonths={1}` 节省横向空间
 - **空态文案**:`placeholder` 简短,**不要**写 "请选择 / Please select" 之类无信息词;直接 "选择日期" / "下单时间"
 
 ## Examples
@@ -123,4 +116,60 @@ import { startOfDay } from 'date-fns';
 // 范围
 const [r, setR] = React.useState<{ from?: Date; to?: Date }>();
 <DateRangePicker value={r} onChange={setR} placeholder="选择范围" />
+
+// showTime — 日期 + 时间
+const [dt, setDt] = React.useState<Date>();
+<DatePicker value={dt} onChange={setDt} showTime />
+
+// showTime 自定义时间格式 + 步长
+<DatePicker
+  value={dt}
+  onChange={setDt}
+  showTime={{ format: 'HH:mm', minuteStep: 5 }}
+  format="yyyy-MM-dd HH:mm"
+/>
+
+// 范围 + showTime
+<DateRangePicker value={r} onChange={setR} showTime numberOfMonths={1} />
 ```
+
+---
+
+## DatePicker 形态 — 旧库 API → 新映射
+
+> 旧库 `DatePicker2`(hybridcloud,含 MonthPicker / YearPicker / RangePicker 子组件) → 新库 `DatePicker` + `DateRangePicker`(独立导出)。
+> 新库用 `react-day-picker v9` + `date-fns`，不依赖 moment / dayjs。
+
+### 命名 & 结构映射
+
+| 旧库                                    | 新库                                      | 说明                       |
+| --------------------------------------- | ----------------------------------------- | -------------------------- |
+| `DatePicker2`                           | `DatePicker`                              | 组件名简化                 |
+| `DatePicker.RangePicker`                | `DateRangePicker`                         | 独立导出(非挂载)           |
+| `MonthPicker / YearPicker / WeekPicker` | _(未来 P1: picker prop)_                  | MVP 仅支持 date mode       |
+| `value` (Dayjs)                         | `value` (Date)                            | 类型变更，无日期库依赖     |
+| `onChange(Dayjs, strVal)`               | `onChange(Date \| undefined)`             | 去掉字符串参数             |
+| `format` (YYYY-MM-DD)                   | `format` (yyyy-MM-dd)                     | date-fns 语法(小写 y/d)    |
+| `size: small/medium/large`              | `size: 'sm' \| 'md' \| 'default' \| 'lg'` | md = medium = default      |
+| `disabledDate(d)`                       | `disabledDates(d)`                        | 复数                       |
+| `preset`                                | `presets` (boolean \| array)              | 复数 + 支持 true 用内置集  |
+| `showTime`                              | `showTime` (boolean \| ShowTimeConfig)    | API 对齐，细节配置结构一致 |
+| `hasClear`                              | `hasClear`                                | 命名保留                   |
+| `visible / onVisibleChange`             | _(未来 P2: open / onOpenChange)_          | MVP 不含弹层受控           |
+| `state`                                 | _(未来 P2: status)_                       | MVP 无校验状态             |
+| `dateCellRender`                        | _(未来 P3)_                               | MVP 无自定义单元格         |
+| `footerRender`                          | _(未来 P2: footer)_                       | MVP 无自定义页脚           |
+| `inputReadOnly`                         | _(未来 P2)_                               | MVP 输入框可编辑           |
+| `outputFormat`                          | 不复刻                                    | 应用层自行 format          |
+| `popupTriggerType="hover"`              | 不复刻                                    | hover 触发不合理           |
+| `isPreview / renderPreview`             | 不复刻                                    | 新库无预览态               |
+
+### 迁移 FAQ
+
+| 问题                       | 回答                                                                    |
+| -------------------------- | ----------------------------------------------------------------------- |
+| Dayjs → Date 怎么转?       | `dayjs.toDate()` 即可;反向 `dayjs(date)`                                |
+| format 大小写区别?         | moment `YYYY` = date-fns `yyyy`; moment `DD` = date-fns `dd`; `MM` 相同 |
+| RangePicker 值结构?        | 旧: `[Dayjs, Dayjs]` → 新: `{ from?: Date, to?: Date }`                 |
+| 怎么实现 MonthPicker?      | MVP 暂不支持;待 picker prop 迭代;当前可用 Select 替代                   |
+| showTime 的“确定”按钮在哪? | 面板底部自带“确定”按钮;仅 showTime 模式有(对齐 antd)                    |

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

@@ -1,27 +1,27 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import type { DateRange } from 'react-day-picker';
 import { DatePicker, DateRangePicker } from './date-picker';
 
 const meta: Meta<typeof DatePicker> = {
-  title: '表单与输入 · Form/DatePicker',
+  title: '数据录入 · Data Entry/DatePicker',
   component: DatePicker,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '日期选择器 — 输入框式触发器 + 弹层日历的组合，支持单日(`DatePicker`)和范围(`DateRangePicker`)两种模式。Popover + Calendar(react-day-picker v9)封装，日期格式由 `format` 控制(date-fns 语法)，`size` 三档对齐 Input。能力对齐 antd DatePicker。',
+          'DatePicker 日期选择 —— 在面板上选取一个日期或日期区间,可选附带时间。Calendar(react-day-picker v9 实现)+ Popover 容器 + TimePickerPanel(showTime 模式复用):对齐 antd `DatePicker` / `DatePicker.RangePicker`(并集补足 `showTime`),关键 prop 包括 `value` / `format` / `disabledDates` / `numberOfMonths` / `showTime`。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
   argTypes: {
     placeholder: { control: 'text' },
     format: { control: 'text' },
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    size: { control: 'inline-radio', options: ['sm', 'md', 'default', 'lg'] },
     disabled: { control: 'boolean' },
   },
-  args: { placeholder: '选择日期', format: 'yyyy-MM-dd', size: 'default' },
+  args: { placeholder: '选择日期', format: 'yyyy-MM-dd', size: 'md' },
 };
 
 export default meta;
@@ -49,6 +49,39 @@ export const ChineseFormat: Story = {
   },
 };
 
+export const WithTime: Story = {
+  name: 'showTime / 日期 + 时间',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [d, setD] = React.useState<Date | undefined>();
+    return (
+      <DatePicker
+        value={d}
+        onChange={setD}
+        showTime
+        placeholder="选择日期时间"
+      />
+    );
+  },
+};
+
+export const WithTimeHourMinute: Story = {
+  name: 'showTime · 时:分',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [d, setD] = React.useState<Date | undefined>();
+    return (
+      <DatePicker
+        value={d}
+        onChange={setD}
+        showTime={{ format: 'HH:mm' }}
+        format="yyyy-MM-dd HH:mm"
+        placeholder="选择日期时间"
+      />
+    );
+  },
+};
+
 export const Range: StoryObj<typeof DateRangePicker> = {
   parameters: { controls: { disable: true } },
   render: () => {
@@ -56,3 +89,20 @@ export const Range: StoryObj<typeof DateRangePicker> = {
     return <DateRangePicker value={r} onChange={setR} />;
   },
 };
+
+export const RangeWithTime: StoryObj<typeof DateRangePicker> = {
+  name: 'Range · showTime',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [r, setR] = React.useState<DateRange | undefined>();
+    return (
+      <DateRangePicker
+        value={r}
+        onChange={setR}
+        showTime
+        numberOfMonths={1}
+        placeholders={['起始时间', '结束时间']}
+      />
+    );
+  },
+};