@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,13 +1,14 @@
 ---
 id: data-table
 name: DataTable
+displayName: 数据表格
 type: component
 category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# DataTable
+# DataTable 数据表格
 
 数据表 — 基于 [`@tanstack/react-table`](https://tanstack.com/table) + 基础 `Table` primitives + `SimplePagination`。
 **等价 antd `Table` 的核心交互合集**:`sorter` + `filter` + `pagination` + `rowSelection`,声明式 `columns + data` 即可。
@@ -102,8 +103,8 @@ const columns: ColumnDef<User>[] = [
           table.getIsAllPageRowsSelected()
             ? true
             : table.getIsSomePageRowsSelected()
-              ? 'indeterminate'
-              : false
+            ? 'indeterminate'
+            : false
         }
         onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
       />
@@ -145,5 +146,5 @@ const columns: ColumnDef<User>[] = [
   data={users}
   pagination={{ pageSize: 10 }}
   onRowSelectionChange={(selected) => console.log(selected)}
-/>
+/>;
 ```

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';
@@ -19,8 +19,7 @@ const data: User[] = Array.from({ length: 35 }).map((_, i) => ({
   name: ['Alice', 'Bob', 'Carol', 'David', 'Eve'][i % 5] + ' ' + (i + 1),
   email: `user${i + 1}@example.com`,
   status:
-    (['active', 'invited', 'disabled'] as const)[i % 3] ??
-    ('active' as const),
+    (['active', 'invited', 'disabled'] as const)[i % 3] ?? ('active' as const),
   amount: Math.round(Math.random() * 1000),
 }));
 
@@ -33,8 +32,8 @@ const columns: ColumnDef<User>[] = [
           table.getIsAllPageRowsSelected()
             ? true
             : table.getIsSomePageRowsSelected()
-              ? 'indeterminate'
-              : false
+            ? 'indeterminate'
+            : false
         }
         onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
         aria-label="全选"
@@ -99,7 +98,15 @@ const meta: Meta<typeof DataTable<User, unknown>> = {
   title: '数据展示 · Data Display/DataTable',
   component: DataTable,
   tags: ['autodocs'],
-  parameters: { layout: 'fullscreen' },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '数据表 — 基于 TanStack Table + 基础 Table 原语 + SimplePagination。声明式 columns + data 即可实现排序 / 筛选 / 分页 / 多选，等价 antd `Table` 的核心交互合集。',
+      },
+    },
+  },
 };
 
 export default meta;

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

@@ -1,31 +1,34 @@
 ---
 id: date-picker
 name: DatePicker
+displayName: 日期选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# DatePicker
+# DatePicker 日期选择
 
 日期选择器 — `Calendar + Popover` 复合,提供两种形态:
+
 - `<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
 
@@ -34,14 +37,24 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `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`)。 |
+| `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 -->
 
 ## 依赖
@@ -56,9 +69,10 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `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 并集 |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
+| `time-picker` | component | 时间选择 — Popover + 滚动列(TimeColumn)面板,含 TimePicker / TimeRangePicker / TimePickerPanel(对齐 antd TimePicker / TimePicker.RangePicker) |
 
 ### npm 依赖
 
@@ -69,14 +83,13 @@ pnpm add date-fns@^3.0.0 react-day-picker@^9.0.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> `DateRangePicker` 的 props 详见 [`date-picker.tsx`](./date-picker.tsx) 的 `DateRangePickerProps` interface。
-
 ## 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
@@ -103,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，视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '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={['起始时间', '结束时间']}
+      />
+    );
+  },
+};