zkit-ui 1.0.0

package/src/ui/DatePicker/README.md

@@ -0,0 +1,117 @@
+# DatePicker
+
+DatePicker 是日期语义组件，底层复用 Picker 的三端滚轮与 Sheet 生命周期，但公共 API 不暴露滚轮细节。它支持空值、受控/非受控值、受控/非受控弹层、年/月/日精度、边界限制、提交事件和草稿事件。
+
+## 设计取舍
+
+- `value/defaultValue/onChange` 表示已提交日期；滚轮移动使用 `onDraftChange`，避免把临时草稿误当成表单值。
+- `value={null}` 表示受控空值；未提供 `defaultValue` 时组件默认不选中日期，打开后定位到 `defaultPickerValue` 或今天。
+- `min/max` 使用日期语义边界；`max="2026-02"` 表示可选到 2026 年 2 月末。
+- 输出值始终跟随 `precision`：`year => YYYY`、`month => YYYY-MM`、`day => YYYY-MM-DD`。
+
+## 基础用法
+
+```tsx
+import * as React from 'react';
+import { Button, DatePicker } from 'zkit-ui';
+
+export function Demo() {
+  const [value, setValue] = React.useState<string | null>(null);
+
+  return (
+    <DatePicker value={value} onChange={setValue}>
+      {({ label, placeholder }) => (
+        <Button>{label || placeholder}</Button>
+      )}
+    </DatePicker>
+  );
+}
+```
+
+## 限制范围
+
+```tsx
+<DatePicker
+  value={value}
+  onChange={setValue}
+  min="2020-01-01"
+  max="2035-12-31"
+/>
+```
+
+## 月份选择
+
+```tsx
+<DatePicker
+  precision="month"
+  value="2026-04"
+  min="2020-01"
+  max="2035-12"
+  labelFormat="YYYY 年 MM 月"
+  onChange={(next) => {
+    // next: '2026-04'
+  }}
+/>
+```
+
+## 禁用部分日期
+
+```tsx
+<DatePicker
+  min="2026-01-01"
+  max="2026-12-31"
+  isDateDisabled={(date) => date.day() === 0 || date.day() === 6}
+  onChange={(next, selection) => {
+    console.log(next, selection.date);
+  }}
+/>
+```
+
+## Props
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | `string \| null` | - | 受控已提交值；`null` 表示空值 |
+| defaultValue | `string \| null` | `null` | 非受控初始已提交值 |
+| onChange | `(value, payload) => void` | - | 用户确认后触发 |
+| open | `boolean` | - | 受控弹层开关 |
+| defaultOpen | `boolean` | `false` | 非受控初始弹层状态 |
+| onOpenChange | `(open: boolean) => void` | - | 弹层开关变化 |
+| precision | `'year' \| 'month' \| 'day'` | `'day'` | 选择精度与输出格式 |
+| min | `string \| Date \| Dayjs` | `1900-01-01` | 最小可选日期 |
+| max | `string \| Date \| Dayjs` | `2100-12-31` | 最大可选日期 |
+| defaultPickerValue | `string \| Date \| Dayjs` | 今天 | 空值打开时滚轮定位 |
+| isDateDisabled | `(date, context) => boolean` | - | 禁用某个可选日期、月份或年份 |
+| title | `string` | i18n | 弹层标题 |
+| placeholder | `string` | i18n | 空值触发器占位文本 |
+| cancelText / confirmText / emptyText | `string` | i18n | 弹层文案 |
+| labelFormat | `string \| (selection) => string` | 同 `value` | 触发器和 payload 的展示文案 |
+| columnLabels | `Partial<Record<'year' \| 'month' \| 'day', string>>` | i18n | 列头文案 |
+| renderColumnHeader | `(context) => ReactNode` | - | 自定义列头 |
+| lazyContent | `boolean` | `true` | 延迟挂载滚轮内容 |
+| sheetHeight | `number \| 'auto'` | `'auto'` | 弹层高度 |
+| disabled | `boolean` | `false` | 禁用打开和交互 |
+| onCancel | `() => void` | - | 取消事件 |
+| onConfirm | `(payload) => void` | - | 确认事件 |
+| onDraftChange | `(payload) => void` | - | 滚轮草稿变化事件 |
+| children | `ReactNode \| (context) => ReactNode` | - | 触发器 |
+
+## Payload
+
+```ts
+type DatePickerSelection = {
+  value: string;
+  date: Dayjs;
+  precision: 'year' | 'month' | 'day';
+  parts: { year: number; month?: number; day?: number };
+  values: number[];
+  label: string;
+  labels: string[];
+  items: DatePickerOption[];
+  columns: DatePickerOption[][];
+  indices: number[];
+  isComplete: boolean;
+};
+```
+
+`date` 会归一到当前精度的起点：年为 1 月 1 日，月为 1 日，日为当天零点。

package/src/ui/DatePicker/index.tsx

@@ -0,0 +1,295 @@
+import * as React from 'react';
+import { Text } from '../Text';
+import {
+  Picker,
+  type PickerChangePayload,
+  type PickerConfirmPayload,
+  type PickerDraftChangePayload,
+  type PickerTriggerContext,
+} from '../Picker';
+import { useI18n } from '../../i18n/useI18n';
+import {
+  buildDatePickerOptions,
+  createDatePickerSelection,
+  createDatePickerSelectionFromDate,
+  DATE_PICKER_COLUMNS,
+  dateFromOption,
+  getColumnCount,
+  normalizePrecision,
+  pathFromDate,
+  resolveCommittedDate,
+  resolveDatePickerBounds,
+  resolvePickerDate,
+} from './utils';
+import type {
+  DatePickerColumn,
+  DatePickerColumnHeaderContext,
+  DatePickerHandle,
+  DatePickerOption,
+  DatePickerProps,
+  DatePickerRenderContext,
+} from './types';
+
+export type {
+  DatePickerChangePayload,
+  DatePickerColumn,
+  DatePickerColumnHeaderContext,
+  DatePickerConfirmPayload,
+  DatePickerDisableContext,
+  DatePickerDraftChangePayload,
+  DatePickerHandle,
+  DatePickerInput,
+  DatePickerLabelFormat,
+  DatePickerOption,
+  DatePickerParts,
+  DatePickerPrecision,
+  DatePickerProps,
+  DatePickerRenderContext,
+  DatePickerSelection,
+  DatePickerValue,
+} from './types';
+
+function createEmptyRenderContext(
+  precision: DatePickerRenderContext['precision'],
+  pickerContext: PickerTriggerContext<DatePickerOption>,
+  placeholder: string
+): DatePickerRenderContext {
+  return {
+    value: null,
+    date: null,
+    precision,
+    parts: null,
+    values: [],
+    label: '',
+    labels: [],
+    items: [],
+    isComplete: false,
+    open: pickerContext.open,
+    close: pickerContext.close,
+    isOpen: pickerContext.isOpen,
+    disabled: pickerContext.disabled,
+    placeholder,
+  };
+}
+
+function createRenderContext(
+  selection: ReturnType<typeof createDatePickerSelectionFromDate> | null,
+  precision: DatePickerRenderContext['precision'],
+  pickerContext: PickerTriggerContext<DatePickerOption>,
+  placeholder: string
+): DatePickerRenderContext {
+  if (!selection) return createEmptyRenderContext(precision, pickerContext, placeholder);
+
+  return {
+    value: selection.value,
+    date: selection.date,
+    precision,
+    parts: selection.parts,
+    values: selection.values,
+    label: selection.label,
+    labels: selection.labels,
+    items: selection.items,
+    isComplete: selection.isComplete,
+    open: pickerContext.open,
+    close: pickerContext.close,
+    isOpen: pickerContext.isOpen,
+    disabled: pickerContext.disabled,
+    placeholder,
+  };
+}
+
+export const DatePicker = React.forwardRef<DatePickerHandle, DatePickerProps>(function DatePicker(
+  {
+    value: valueProp,
+    defaultValue = null,
+    onChange,
+    open,
+    defaultOpen,
+    onOpenChange,
+    onDismissComplete,
+    precision: precisionProp = 'day',
+    min,
+    max,
+    defaultPickerValue,
+    isDateDisabled,
+    title,
+    placeholder,
+    cancelText,
+    confirmText,
+    emptyText,
+    labelFormat,
+    columnLabels,
+    renderColumnHeader,
+    lazyContent = true,
+    sheetHeight = 'auto',
+    disabled = false,
+    onCancel,
+    onConfirm,
+    onDraftChange,
+    children,
+  },
+  ref
+) {
+  const { t } = useI18n();
+  const precision = normalizePrecision(precisionProp);
+  const placeholderText = placeholder ?? t('datePicker.placeholder');
+  const isValueControlled = valueProp !== undefined;
+  const [innerValue, setInnerValue] = React.useState<DatePickerProps['value']>(defaultValue);
+  const committedValue = isValueControlled ? valueProp : innerValue;
+
+  const bounds = React.useMemo(() => resolveDatePickerBounds(min, max), [max, min]);
+  const options = React.useMemo(
+    () => buildDatePickerOptions({ bounds, precision, isDateDisabled }),
+    [bounds, isDateDisabled, precision]
+  );
+  const committedDate = React.useMemo(
+    () => resolveCommittedDate(committedValue, bounds, precision),
+    [bounds, committedValue, precision]
+  );
+  const pickerDate = React.useMemo(
+    () => resolvePickerDate(committedDate, defaultPickerValue, bounds, precision),
+    [bounds, committedDate, defaultPickerValue, precision]
+  );
+  const pickerValue = React.useMemo(() => pathFromDate(pickerDate, precision), [pickerDate, precision]);
+  const committedSelection = React.useMemo(
+    () =>
+      committedDate
+        ? createDatePickerSelectionFromDate(committedDate, precision, options, labelFormat)
+        : null,
+    [committedDate, labelFormat, options, precision]
+  );
+
+  const resolveSelection = React.useCallback(
+    (
+      selection:
+        | PickerChangePayload<DatePickerOption>
+        | PickerConfirmPayload<DatePickerOption>
+        | PickerDraftChangePayload<DatePickerOption>
+    ) => createDatePickerSelection(selection, precision, labelFormat, selection.label),
+    [labelFormat, precision]
+  );
+
+  const handlePickerChange = React.useCallback(
+    (_next: unknown, selection: PickerChangePayload<DatePickerOption>) => {
+      const nextSelection = resolveSelection(selection);
+      if (!nextSelection) return;
+
+      if (!isValueControlled) {
+        setInnerValue(nextSelection.value);
+      }
+
+      onChange?.(nextSelection.value, nextSelection);
+    },
+    [isValueControlled, onChange, resolveSelection]
+  );
+
+  const handlePickerConfirm = React.useCallback(
+    (selection: PickerConfirmPayload<DatePickerOption>) => {
+      const nextSelection = resolveSelection(selection);
+      if (!nextSelection) return;
+      onConfirm?.(nextSelection);
+    },
+    [onConfirm, resolveSelection]
+  );
+
+  const handlePickerDraftChange = React.useCallback(
+    (selection: PickerDraftChangePayload<DatePickerOption>) => {
+      const nextSelection = resolveSelection(selection);
+      if (!nextSelection) return;
+      onDraftChange?.(nextSelection);
+    },
+    [onDraftChange, resolveSelection]
+  );
+
+  const formatPickerLabel = React.useCallback(
+    (selection: PickerConfirmPayload<DatePickerOption>) =>
+      createDatePickerSelection(selection, precision, labelFormat)?.label ?? selection.label,
+    [labelFormat, precision]
+  );
+
+  const resolvedColumnLabels = React.useMemo(
+    () => ({
+      year: columnLabels?.year ?? t('datePicker.year'),
+      month: columnLabels?.month ?? t('datePicker.month'),
+      day: columnLabels?.day ?? t('datePicker.day'),
+    }),
+    [columnLabels?.day, columnLabels?.month, columnLabels?.year, t]
+  );
+
+  const handleRenderColumnHeader = React.useCallback(
+    (context: {
+      columnIndex: number;
+      columnCount: number;
+      options: DatePickerOption[];
+      selectedItem?: DatePickerOption;
+      selectedValue?: string | number;
+      selectedLabel?: string;
+    }) => {
+      const column = DATE_PICKER_COLUMNS[context.columnIndex] as DatePickerColumn;
+      const selectedDate = dateFromOption(context.selectedItem, precision);
+      const headerContext: DatePickerColumnHeaderContext = {
+        column,
+        columnIndex: context.columnIndex,
+        columnCount: context.columnCount,
+        options: context.options,
+        selectedItem: context.selectedItem,
+        selectedValue: typeof context.selectedValue === 'number' ? context.selectedValue : undefined,
+        selectedLabel: context.selectedLabel,
+        selectedDate,
+        selectedParts: context.selectedItem
+          ? {
+              year: context.selectedItem.year,
+              month: context.selectedItem.month,
+              day: context.selectedItem.day,
+            }
+          : undefined,
+      };
+
+      if (renderColumnHeader) return renderColumnHeader(headerContext);
+
+      return (
+        <Text variant="label" size="sm" weight="semibold" tone="muted">
+          {resolvedColumnLabels[column]}
+        </Text>
+      );
+    },
+    [precision, renderColumnHeader, resolvedColumnLabels]
+  );
+
+  const pickerChildren = React.useMemo(() => {
+    if (typeof children !== 'function') return children;
+
+    return (pickerContext: PickerTriggerContext<DatePickerOption>) =>
+      children(createRenderContext(committedSelection, precision, pickerContext, placeholderText));
+  }, [children, committedSelection, placeholderText, precision]);
+
+  return (
+    <Picker<DatePickerOption>
+      ref={ref}
+      options={options}
+      value={pickerValue}
+      onChange={handlePickerChange}
+      valueMode="path"
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      onDismissComplete={onDismissComplete}
+      title={title ?? t('datePicker.title')}
+      placeholder={placeholderText}
+      cancelText={cancelText}
+      confirmText={confirmText}
+      emptyText={emptyText}
+      formatLabel={formatPickerLabel}
+      renderColumnHeader={handleRenderColumnHeader}
+      maxColumns={getColumnCount(precision)}
+      lazyContent={lazyContent}
+      sheetHeight={sheetHeight}
+      disabled={disabled}
+      onCancel={onCancel}
+      onConfirm={handlePickerConfirm}
+      onDraftChange={handlePickerDraftChange}
+    >
+      {pickerChildren}
+    </Picker>
+  );
+});

package/src/ui/DatePicker/types.ts

@@ -0,0 +1,115 @@
+import type * as React from 'react';
+import type { Dayjs } from 'dayjs';
+import type { PickerHandle, PickerOption } from '../Picker';
+
+export type DatePickerHandle = PickerHandle;
+
+export type DatePickerPrecision = 'year' | 'month' | 'day';
+export type DatePickerColumn = DatePickerPrecision;
+export type DatePickerValue = string;
+export type DatePickerInput = DatePickerValue | Date | Dayjs;
+
+export type DatePickerParts = {
+  year: number;
+  month?: number;
+  day?: number;
+};
+
+export type DatePickerDisableContext = {
+  precision: DatePickerPrecision;
+  column: DatePickerColumn;
+  parts: DatePickerParts;
+};
+
+export type DatePickerOption = PickerOption<number> & {
+  column: DatePickerColumn;
+  year: number;
+  month?: number;
+  day?: number;
+  children?: DatePickerOption[];
+};
+
+export type DatePickerSelection = {
+  value: DatePickerValue;
+  date: Dayjs;
+  precision: DatePickerPrecision;
+  parts: DatePickerParts;
+  values: number[];
+  label: string;
+  labels: string[];
+  items: DatePickerOption[];
+  columns: DatePickerOption[][];
+  indices: number[];
+  isComplete: boolean;
+};
+
+export type DatePickerChangePayload = DatePickerSelection;
+export type DatePickerConfirmPayload = DatePickerSelection;
+export type DatePickerDraftChangePayload = DatePickerSelection;
+
+export type DatePickerRenderContext = {
+  value: DatePickerValue | null;
+  date: Dayjs | null;
+  precision: DatePickerPrecision;
+  parts: DatePickerParts | null;
+  values: number[];
+  label: string;
+  labels: string[];
+  items: DatePickerOption[];
+  isComplete: boolean;
+  open: () => void;
+  close: () => void;
+  isOpen: boolean;
+  disabled: boolean;
+  placeholder: string;
+};
+
+export type DatePickerColumnHeaderContext = {
+  column: DatePickerColumn;
+  columnIndex: number;
+  columnCount: number;
+  options: DatePickerOption[];
+  selectedItem?: DatePickerOption;
+  selectedValue?: number;
+  selectedLabel?: string;
+  selectedDate?: Dayjs;
+  selectedParts?: DatePickerParts;
+};
+
+export type DatePickerLabelFormat = string | ((selection: DatePickerSelection) => string);
+
+export type DatePickerProps = {
+  value?: DatePickerValue | null;
+  defaultValue?: DatePickerValue | null;
+  onChange?: (value: DatePickerValue, payload: DatePickerChangePayload) => void;
+
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  onDismissComplete?: () => void;
+
+  precision?: DatePickerPrecision;
+  min?: DatePickerInput;
+  max?: DatePickerInput;
+  defaultPickerValue?: DatePickerInput;
+  isDateDisabled?: (date: Dayjs, context: DatePickerDisableContext) => boolean;
+
+  title?: string;
+  placeholder?: string;
+  cancelText?: string;
+  confirmText?: string;
+  emptyText?: string;
+  labelFormat?: DatePickerLabelFormat;
+  columnLabels?: Partial<Record<DatePickerColumn, string>>;
+  renderColumnHeader?: (context: DatePickerColumnHeaderContext) => React.ReactNode;
+
+  lazyContent?: boolean;
+  sheetHeight?: number | 'auto';
+  disabled?: boolean;
+
+  onCancel?: () => void;
+  onConfirm?: (payload: DatePickerConfirmPayload) => void;
+  onDraftChange?: (payload: DatePickerDraftChangePayload) => void;
+
+  children?: React.ReactNode | ((context: DatePickerRenderContext) => React.ReactNode);
+};