@teamix-evo/ui 0.3.0 → 0.5.0

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

@@ -0,0 +1,103 @@
+# DatePicker
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+日期选择器 DatePicker
+通过日历面板选择日期或日期范围，支持时间选择、快捷 preset 和月/年粒度。
+
+## 使用场景
+
+- 需要用户选择单个日期时（表单、筛选器）
+- 需要选择日期范围时（报表区间、日志查询）
+- 需要同时选择日期 + 时间时（工单创建时间、定时任务）
+
+## 组合结构
+
+```
+- `DatePicker` 单日期 / 月份 / 年份选择
+- `DateRangePicker` 日期范围 + 可选时间
+- showTime 模式内嵌 `TimePickerPanel`（来自 time-picker，对齐 antd showTime）
+```
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `picker` | `'date' \| 'month' \| 'year'` | `"date"` | – | 选择粒度。 |
+| `value` | `Date` | – | – | 受控值 |
+| `defaultValue` | `Date` | – | – | 非受控初始值 |
+| `onChange` | `(value: Date \| undefined) => void` | – | – | 值变化回调 |
+| `placeholder` | `string` | `按 picker 自动选择` | – | 占位符。 |
+| `format` | `string` | – | – | date-fns 格式（不传则按 picker / showTime 自动选择） |
+| `size` | `TriggerSize` | `"default"` | – | trigger 尺寸。 |
+| `className` | `string` | – | – | trigger 自定义类名 |
+| `disabled` | `boolean` | – | – | 禁用 |
+| `disabledDates` | `(date: Date) => boolean` | – | – | 自定义日期禁用规则 |
+| `showTime` | `boolean \| ShowTimeConfig` | – | – | 是否启用时间选择（仅 picker="date" 生效） |
+| `presets` | `boolean \| DatePickerPreset[]` | – | – | 快捷选项：`true` 使用内置 today/yesterday |
+| `hasClear` | `boolean` | `true` | – | 是否显示清除按钮。 |
+| `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"`。 优先级：loading > clear > CalendarIcon，三者互斥占同一位置。 |
+| `status` | `'default' \| 'error'` | `"default"` | – | 校验状态（驱动 trigger 边框/聚焦环颜色）。 |
+| `open` | `boolean` | – | – | 受控弹层显隐 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹层显隐变化回调 |
+| `footer` | `React.ReactNode` | – | – | 弹层底部自定义节点 |
+| `inputReadOnly` | `boolean` | `false` | – | 输入框只读（仍可打开弹层，禁用键盘录入）。 |
+| `ref` | `React.Ref<HTMLInputElement>` | – | – | 输入框 ref |
+| `value` | `DateRange` | – | – | 受控值 |
+| `defaultValue` | `DateRange` | – | – | 非受控初始值 |
+| `onChange` | `(value: DateRange \| undefined) => void` | – | – | 值变化回调（弹层关闭或确定时触发） |
+| `format` | `string` | `"yyyy-MM-dd"（showTime 时为 "yyyy-MM-dd HH:mm:ss"）` | – | date-fns 格式。 |
+| `size` | `TriggerSize` | `"default"` | – | trigger 尺寸。 |
+| `className` | `string` | – | – | trigger 自定义类名 |
+| `disabled` | `boolean` | – | – | 禁用 |
+| `disabledDates` | `(date: Date) => boolean` | – | – | 自定义日期禁用规则 |
+| `numberOfMonths` | `number` | `2` | – | 同时显示的月份数（非 showTime 模式下生效）。 |
+| `placeholders` | `[string, string]` | `["起始日期","结束日期"]` | – | 起止占位符。 |
+| `showTime` | `boolean \| ShowTimeConfig` | – | – | 是否启用时间选择 |
+| `presets` | `boolean \| DateRangePreset[]` | – | – | 快捷范围：`true` 使用内置今天/昨天/本周/上周/本月/上月 |
+| `hasClear` | `boolean` | `true` | – | 是否显示清除按钮。 |
+| `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"`。 优先级：loading > clear > CalendarIcon，三者互斥占同一位置。 |
+| `status` | `'default' \| 'error'` | `"default"` | – | 校验状态（驱动 trigger 边框/聚焦环颜色）。 |
+| `open` | `boolean` | – | – | 受控弹层显隐 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹层显隐变化回调 |
+| `footer` | `React.ReactNode` | – | – | 弹层底部自定义节点 |
+| `inputReadOnly` | `boolean` | `false` | – | 输入框只读。 |
+| `ref` | `React.Ref<HTMLInputElement>` | – | – | 起始输入框 ref |
+
+## 示例
+
+### Sizes
+
+尺寸
+
+```tsx
+<div className="flex flex-col gap-3">
+  <DatePicker size="sm" placeholder="小" />
+  <DatePicker placeholder="中（默认）" />
+  <DatePicker size="lg" placeholder="大" />
+</div>
+```
+
+### DisabledDates
+
+禁用部分日期
+
+```tsx
+<DatePicker
+  disabledDates={(d) => d.getDay() === 0 || d.getDay() === 6}
+  placeholder="不可选周末"
+/>
+```
+
+### Loading
+
+加载态：右侧图标替换为 spinner，loading > clear > CalendarIcon 互斥。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <DatePicker loading placeholder="加载中" />
+  <DateRangePicker loading />
+</div>
+```

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

@@ -0,0 +1,125 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { type DateRange } from 'react-day-picker';
+import { DatePicker, DateRangePicker } from './index';
+
+const meta: Meta<typeof DatePicker> = {
+  title: '数据录入 · Data Entry/DatePicker 日期选择器',
+  component: DatePicker,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <DatePicker />,
+};
+
+/** 尺寸 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <DatePicker size="sm" placeholder="小" />
+      <DatePicker placeholder="中（默认）" />
+      <DatePicker size="lg" placeholder="大" />
+    </div>
+  ),
+};
+
+/** 受控 */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<Date | undefined>(new Date());
+    return (
+      <div className="flex flex-col gap-2">
+        <DatePicker value={value} onChange={setValue} />
+        <p className="text-xs text-muted-foreground">
+          {value?.toLocaleDateString() ?? '(空)'}
+        </p>
+      </div>
+    );
+  },
+};
+
+/** 带时间选择 */
+export const WithShowTime: Story = {
+  render: () => <DatePicker showTime placeholder="选择日期时间" />,
+};
+
+/** 月份选择 */
+export const MonthPicker: Story = {
+  render: () => <DatePicker picker="month" />,
+};
+
+/** 年份选择 */
+export const YearPicker: Story = {
+  render: () => <DatePicker picker="year" />,
+};
+
+/** 快捷选项 */
+export const WithPresets: Story = {
+  render: () => <DatePicker presets />,
+};
+
+/** 禁用部分日期 */
+export const DisabledDates: Story = {
+  render: () => (
+    <DatePicker
+      disabledDates={(d) => d.getDay() === 0 || d.getDay() === 6}
+      placeholder="不可选周末"
+    />
+  ),
+};
+
+/** 错误状态 */
+export const ErrorStatus: Story = {
+  render: () => <DatePicker status="error" placeholder="请选择日期" />,
+};
+
+/** 加载态：右侧图标替换为 spinner，loading > clear > CalendarIcon 互斥。 */
+export const Loading: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <DatePicker loading placeholder="加载中" />
+      <DateRangePicker loading />
+    </div>
+  ),
+};
+
+/** 日期范围选择器 */
+export const Range: Story = {
+  render: () => <DateRangePicker />,
+};
+
+/** 日期范围 - 受控 */
+export const RangeControlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<DateRange | undefined>({
+      from: new Date(),
+      to: new Date(Date.now() + 7 * 86400000),
+    });
+    return (
+      <div className="flex flex-col gap-2">
+        <DateRangePicker value={value} onChange={setValue} />
+        <p className="text-xs text-muted-foreground">
+          {value?.from?.toLocaleDateString()} ~{' '}
+          {value?.to?.toLocaleDateString()}
+        </p>
+      </div>
+    );
+  },
+};
+
+/** 日期范围 + 时间 */
+export const RangeWithTime: Story = {
+  render: () => <DateRangePicker showTime />,
+};
+
+/** 日期范围 + 快捷选项 */
+export const RangeWithPresets: Story = {
+  render: () => <DateRangePicker presets />,
+};