@teamix-evo/ui 0.3.0 → 0.5.0

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

@@ -0,0 +1,102 @@
+# TimePicker
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+时间选择器 TimePicker
+通过滚动列选择时分秒，支持单值与范围两种模式；可作为 DatePicker showTime 模式的内嵌面板复用。
+
+## 使用场景
+
+- 需要用户精确选择时间（时:分:秒）时
+- 需要选择时间范围（起止时间）时
+- 在 DatePicker showTime 模式中作为内嵌面板复用时
+- 组合结构：TimePicker / TimeRangePicker（独立使用）；TimePickerPanel + TimeColumn（面板与单列，供高级组合）
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控值。空串表示未选。 |
+| `defaultValue` | `string` | – | – | 非受控初值 |
+| `onChange` | `(value: string) => void` | – | – | 值变化回调 |
+| `format` | `string` | `"HH:mm:ss"` | – | 时间格式。 |
+| `hourStep` | `number` | `1` | – | 小时步长。 |
+| `minuteStep` | `number` | `1` | – | 分钟步长。 |
+| `secondStep` | `number` | `1` | – | 秒步长。 |
+| `disabledHours` | `() => number[]` | – | – | 不可选小时集合 |
+| `disabledMinutes` | `(hour: number) => number[]` | – | – | 给定小时下不可选分钟集合 |
+| `disabledSeconds` | `(hour: number, minute: number) => number[]` | – | – | 给定时分下不可选秒集合 |
+| `placeholder` | `string` | `"请选择时间"` | – | 占位文本。 |
+| `disabled` | `boolean` | – | – | 禁用 |
+| `size` | `TriggerSize` | `"default"` | – | 触发器尺寸。 |
+| `hasClear` | `boolean` | `true` | – | 显示清除按钮。 |
+| `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"`。 优先级：loading > clear > Clock，三者互斥占同一位置。 |
+| `className` | `string` | – | – | 自定义类名（应用于 trigger 容器） |
+| `id` | `string` | – | – | 输入框 id（用于 label htmlFor 关联） |
+| `status` | `'default' \| 'error'` | `"default"` | – | 校验状态（驱动 trigger 边框/聚焦环颜色）。 |
+| `open` | `boolean` | – | – | 受控弹层显隐 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹层显隐变化回调 |
+| `inputReadOnly` | `boolean` | `false` | – | 输入框只读（仅通过面板选择）。 |
+| `ref` | `React.Ref<HTMLInputElement>` | – | – | 转发到内部 input 元素的 ref |
+| `values` | `number[]` | – | ✓ | 列内可选数字集合 |
+| `value` | `number` | – | ✓ | 当前选中的数字 |
+| `onChange` | `(v: number) => void` | – | ✓ | 选中数字时的回调 |
+| `disabledValues` | `number[]` | – | – | 禁用的数字集合 |
+| `ariaLabel` | `string` | – | – | 列的无障碍标签（屏幕阅读器） |
+| `padZero` | `boolean` | `true` | – | 是否补零展示。 |
+| `hasSelection` | `boolean` | `true` | – | 是否高亮选中项（用户尚未选择时为 false 不高亮）。 |
+| `value` | `TimeParts` | – | ✓ | 当前时间值 |
+| `onChange` | `(next: TimeParts) => void` | – | ✓ | 时间变更回调 |
+| `format` | `string` | `"HH:mm:ss"` | – | 时间格式（决定渲染列数）。 |
+| `hourStep` | `number` | `1` | – | 小时步长。 |
+| `minuteStep` | `number` | `1` | – | 分钟步长。 |
+| `secondStep` | `number` | `1` | – | 秒步长。 |
+| `disabledHours` | `() => number[]` | – | – | 不可选小时集合 |
+| `disabledMinutes` | `(hour: number) => number[]` | – | – | 给定小时下不可选分钟集合 |
+| `disabledSeconds` | `(hour: number, minute: number) => number[]` | – | – | 给定时分下不可选秒集合 |
+| `padZero` | `boolean` | `true` | – | 是否补零展示。 |
+| `hasSelection` | `boolean` | `true` | – | 是否高亮选中态（未确认选择时为 false 表示无选中）。 |
+| `className` | `string` | – | – | 自定义类名 |
+| `value` | `TimeRangeValue` | – | – | 受控范围值。每位空串表示未选。 |
+| `defaultValue` | `TimeRangeValue` | – | – | 非受控初值 |
+| `onChange` | `(value: TimeRangeValue) => void` | – | – | 范围变更回调（关闭弹层或点击"确定"时触发） |
+| `placeholders` | `[string, string]` | `["请选择时间","请选择时间"]` | – | 起止两端占位文本。 |
+| `ref` | `React.Ref<HTMLInputElement>` | – | – | 转发到起始 input 元素的 ref |
+
+## 示例
+
+### Sizes
+
+通过 `size` 属性控制触发器尺寸。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <TimePicker size="sm" placeholder="小" />
+  <TimePicker placeholder="中（默认）" />
+  <TimePicker size="lg" placeholder="大" />
+</div>
+```
+
+### Loading
+
+加载态：右侧图标替换为 spinner，loading > clear > Clock 互斥。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <TimePicker loading placeholder="加载中" />
+  <TimeRangePicker loading />
+</div>
+```
+
+### DisabledHours
+
+禁用不可选时段（0-8 点与 22-23 点）
+
+```tsx
+<TimePicker
+  placeholder="仅可选 9-21 点"
+  disabledHours={() => [0, 1, 2, 3, 4, 5, 6, 7, 8, 22, 23]}
+/>
+```

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

@@ -0,0 +1,125 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import {
+  TimePicker,
+  TimePickerPanel,
+  TimeRangePicker,
+  type TimeParts,
+} from './index';
+
+const meta: Meta<typeof TimePicker> = {
+  title: '数据录入 · Data Entry/TimePicker 时间选择器',
+  component: TimePicker,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <TimePicker placeholder="请选择时间" />,
+};
+
+/** 通过 `size` 属性控制触发器尺寸。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <TimePicker size="sm" placeholder="小" />
+      <TimePicker placeholder="中（默认）" />
+      <TimePicker size="lg" placeholder="大" />
+    </div>
+  ),
+};
+
+/** 受控模式 */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = useState('09:30:00');
+    return (
+      <div className="flex flex-col gap-2">
+        <TimePicker value={value} onChange={setValue} />
+        <p className="text-xs text-muted-foreground">
+          当前值: {value || '(空)'}
+        </p>
+      </div>
+    );
+  },
+};
+
+/** 仅小时和分钟 */
+export const HourMinute: Story = {
+  render: () => <TimePicker format="HH:mm" placeholder="时:分" />,
+};
+
+/** 步长:15 分钟间隔 */
+export const MinuteStep: Story = {
+  render: () => <TimePicker minuteStep={15} placeholder="15分钟步长" />,
+};
+
+/** 禁用状态 */
+export const Disabled: Story = {
+  render: () => <TimePicker defaultValue="14:30:00" disabled />,
+};
+
+/** 错误状态 */
+export const ErrorStatus: Story = {
+  render: () => <TimePicker status="error" placeholder="校验失败" />,
+};
+
+/** 加载态：右侧图标替换为 spinner，loading > clear > Clock 互斥。 */
+export const Loading: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <TimePicker loading placeholder="加载中" />
+      <TimeRangePicker loading />
+    </div>
+  ),
+};
+
+/** 禁用不可选时段（0-8 点与 22-23 点） */
+export const DisabledHours: Story = {
+  render: () => (
+    <TimePicker
+      placeholder="仅可选 9-21 点"
+      disabledHours={() => [0, 1, 2, 3, 4, 5, 6, 7, 8, 22, 23]}
+    />
+  ),
+};
+
+/** 独立使用 TimePickerPanel（可嵌入任意弹层或 DatePicker showTime） */
+export const Panel: Story = {
+  render: () => {
+    const [parts, setParts] = useState<TimeParts>({ h: 9, m: 30, s: 0 });
+    return (
+      <div className="inline-flex rounded-md border border-border">
+        <TimePickerPanel value={parts} onChange={setParts} />
+      </div>
+    );
+  },
+};
+
+/** 时间范围选择器 */
+export const Range: Story = {
+  render: () => <TimeRangePicker />,
+};
+
+/** 时间范围 - 受控 */
+export const RangeControlled: Story = {
+  render: () => {
+    const [value, setValue] = useState<[string, string]>([
+      '09:00:00',
+      '18:00:00',
+    ]);
+    return (
+      <div className="flex flex-col gap-2">
+        <TimeRangePicker value={value} onChange={setValue} />
+        <p className="text-xs text-muted-foreground">
+          {value[0] || '(空)'} ~ {value[1] || '(空)'}
+        </p>
+      </div>
+    );
+  },
+};

package/src/components/timeline/index.tsx

@@ -0,0 +1,422 @@
+/**
+ * 时间轴 Timeline
+ *
+ * 垂直展示事件流 / 操作历史 / 进度时间线，由 composable 子组件组合使用。
+ *
+ * @when
+ * - 展示操作日志 / 变更历史 / 物流轨迹
+ * - 流程进度可视化（审批流、部署流水线）
+ * - 通知 / 公告时间线
+ *
+ * 组合结构：Timeline > TimelineItem > TimelineSeparator(TimelineDot + TimelineConnector) + TimelineContent(TimelineHeader(TimelineTitle + TimelineTime) + TimelineDescription) + TimelineOppositeContent
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+// ─── Types & Context ─────────────────────────────────────────────────────────
+
+export type TimelineMode = 'left' | 'right' | 'alternate';
+export type TimelineState = 'done' | 'process' | 'error' | 'success';
+export type TimelinePosition = 'left' | 'right';
+
+interface TimelineContextValue {
+  mode: TimelineMode;
+}
+const TimelineContext = React.createContext<TimelineContextValue>({
+  mode: 'left',
+});
+
+interface TimelineItemContextValue {
+  state: TimelineState;
+  /** 当前项在父容器中的索引（用于 alternate 推导）。 */
+  index: number;
+  /** 显式 position 覆盖。 */
+  position?: TimelinePosition;
+  /** 解析后的当侧（对 alternate 已结合 index 计算）。 */
+  resolvedSide: TimelinePosition;
+  /** 是否最后一项（连接线 fallback 隐藏依据）。 */
+  isLast: boolean;
+}
+const TimelineItemContext =
+  React.createContext<TimelineItemContextValue | null>(null);
+
+function useTimelineItem(): TimelineItemContextValue {
+  const ctx = React.useContext(TimelineItemContext);
+  if (!ctx) {
+    throw new Error('TimelineItem 子组件必须放在 <TimelineItem> 内使用');
+  }
+  return ctx;
+}
+
+// ─── Timeline (root) ─────────────────────────────────────────────────────────
+
+/** Timeline 根容器 — 控制布局模式与反向排列。 */
+export interface TimelineProps extends React.ComponentProps<'ul'> {
+  /** 布局模式：left 内容在右、right 内容在左、alternate 双侧交替。 @default "left" */
+  mode?: TimelineMode;
+  /** 反向排列 — 最新条目排在最上。 @default false */
+  reverse?: boolean;
+}
+
+function Timeline({
+  className,
+  mode = 'left',
+  reverse = false,
+  children,
+  ...props
+}: TimelineProps) {
+  // 把 children 包成数组以便注入 index / isLast 上下文
+  const items = React.Children.toArray(children).filter(React.isValidElement);
+  return (
+    <TimelineContext.Provider value={{ mode }}>
+      <ul
+        data-slot="timeline"
+        data-mode={mode}
+        className={cn(
+          'flex list-none flex-col',
+          reverse && 'flex-col-reverse',
+          className,
+        )}
+        {...props}
+      >
+        {items.map((child, index) => {
+          // reverse 下视觉末项是 DOM index 0，isLast 需按视觉顺序计算
+          const isLast = reverse ? index === 0 : index === items.length - 1;
+          return React.cloneElement(
+            child as React.ReactElement<TimelineItemProps>,
+            {
+              // @ts-expect-error 内部注入元数据
+              __timelineIndex: index,
+              __timelineIsLast: isLast,
+              key: (child as React.ReactElement).key ?? index,
+            },
+          );
+        })}
+      </ul>
+    </TimelineContext.Provider>
+  );
+}
+
+// ─── TimelineItem ────────────────────────────────────────────────────────────
+
+/** Timeline 单个节点 — 包裹 Separator、Content 及可选 OppositeContent。 */
+export interface TimelineItemProps extends React.ComponentProps<'li'> {
+  /** 节点状态语义。 @default "done" */
+  state?: TimelineState;
+  /** 显式覆盖该项在 alternate 模式下的归位侧。 */
+  position?: TimelinePosition;
+}
+
+interface InternalTimelineItemProps extends TimelineItemProps {
+  /** @internal 由 Timeline 注入 */
+  __timelineIndex?: number;
+  /** @internal 由 Timeline 注入 */
+  __timelineIsLast?: boolean;
+}
+
+function TimelineItem({
+  className,
+  state = 'done',
+  position,
+  children,
+  ...rest
+}: TimelineItemProps) {
+  const {
+    __timelineIndex: index = 0,
+    __timelineIsLast: isLast = false,
+    ...props
+  } = rest as InternalTimelineItemProps;
+  const { mode } = React.useContext(TimelineContext);
+
+  // 推导 resolvedSide
+  let resolvedSide: TimelinePosition;
+  if (position) {
+    resolvedSide = position;
+  } else if (mode === 'right') {
+    resolvedSide = 'left';
+  } else if (mode === 'alternate') {
+    resolvedSide = index % 2 === 0 ? 'right' : 'left';
+  } else {
+    resolvedSide = 'right';
+  }
+
+  const itemCtx: TimelineItemContextValue = {
+    state,
+    index,
+    position,
+    resolvedSide,
+    isLast,
+  };
+
+  // grid 模板：alternate / right 三列（opposite | separator | content），left 两列
+  const gridCols =
+    mode === 'alternate' || mode === 'right'
+      ? 'grid-cols-[1fr_auto_1fr]'
+      : 'grid-cols-[auto_1fr]';
+
+  return (
+    <TimelineItemContext.Provider value={itemCtx}>
+      <li
+        data-slot="timeline-item"
+        data-state={state}
+        data-side={resolvedSide}
+        className={cn(
+          // grid-flow-row-dense：alternate 下 OppositeContent/Separator/Content 的 DOM 顺序与 col-start 不一致，
+          // 默认 auto-flow 会把后面的子节点挤到下一行，dense 会倒填空格保证三个子节点同行
+          'grid grid-flow-row-dense items-stretch gap-x-3',
+          gridCols,
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </li>
+    </TimelineItemContext.Provider>
+  );
+}
+
+// ─── TimelineSeparator ───────────────────────────────────────────────────────
+
+/** Separator 列 — 承载 TimelineDot 与 TimelineConnector，渲染于中间分隔列。 */
+export interface TimelineSeparatorProps extends React.ComponentProps<'div'> {}
+
+function TimelineSeparator({
+  className,
+  children,
+  ...props
+}: TimelineSeparatorProps) {
+  const { mode } = React.useContext(TimelineContext);
+  // 3 列模式（right / alternate）下显式锁定到第 2 列，避免 auto-flow 错位
+  const isThreeCol = mode === 'right' || mode === 'alternate';
+  return (
+    <div
+      data-slot="timeline-separator"
+      data-mode={mode}
+      className={cn(
+        // pt-1 让 dot 中心从 6px 下移到 10px，对齐首行 text-* leading-5 的文字中心
+        'flex flex-col items-center pt-1',
+        isThreeCol && 'col-start-2',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ─── TimelineDot ─────────────────────────────────────────────────────────────
+
+const timelineDotVariants = cva(
+  'inline-flex shrink-0 items-center justify-center rounded-full ring-2 ring-background transition-colors',
+  {
+    variants: {
+      state: {
+        done: 'size-3 bg-muted-foreground/40',
+        process: 'size-3 bg-primary outline outline-3 outline-primary/20',
+        error: 'size-3 bg-destructive',
+        success: 'size-3 bg-success',
+      },
+    },
+    defaultVariants: { state: 'done' },
+  },
+);
+
+/** 节点圆点 — 默认按 state 渲染语义色块；asChild 模式下可替换为 lucide 图标。 */
+export interface TimelineDotProps
+  extends React.ComponentProps<'span'>,
+    VariantProps<typeof timelineDotVariants> {
+  /** 使用 Slot 模式 — 把样式作用到子元素（例如 lucide 图标）。 @default false */
+  asChild?: boolean;
+}
+
+function TimelineDot({
+  className,
+  state,
+  asChild = false,
+  ...props
+}: TimelineDotProps) {
+  const itemCtx = React.useContext(TimelineItemContext);
+  const resolvedState: TimelineState = state ?? itemCtx?.state ?? 'done';
+  const Comp: React.ElementType = asChild ? Slot.Root : 'span';
+
+  // asChild 时去掉默认背景色，仅保留尺寸 / ring；交由用户子元素自行控色
+  const isCustom = asChild;
+
+  return (
+    <Comp
+      data-slot="timeline-dot"
+      data-state={resolvedState}
+      className={cn(
+        isCustom
+          ? 'inline-flex size-4 shrink-0 items-center justify-center rounded-full bg-background text-foreground ring-2 ring-background [&_svg]:size-4 [&_svg]:shrink-0'
+          : timelineDotVariants({ state: resolvedState }),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TimelineConnector ───────────────────────────────────────────────────────
+
+/** 连接线 — 衔接相邻 dot；视觉末项自动隐藏。 */
+export interface TimelineConnectorProps extends React.ComponentProps<'span'> {}
+
+function TimelineConnector({ className, ...props }: TimelineConnectorProps) {
+  const itemCtx = React.useContext(TimelineItemContext);
+  // 最后一项默认隐藏连接线（视觉收尾），用户也可显式覆盖 className。
+  if (itemCtx?.isLast) return null;
+  return (
+    <span
+      aria-hidden="true"
+      data-slot="timeline-connector"
+      className={cn('mt-1 w-px flex-1 bg-border', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── TimelineContent ─────────────────────────────────────────────────────────
+
+/** 主内容区 — 渲染标题 / 时间 / 描述等核心信息。 */
+export interface TimelineContentProps extends React.ComponentProps<'div'> {}
+
+function TimelineContent({ className, ...props }: TimelineContentProps) {
+  const { mode } = React.useContext(TimelineContext);
+  const itemCtx = useTimelineItem();
+  const isAlternate = mode === 'alternate';
+  const isRight = mode === 'right';
+  return (
+    <div
+      data-slot="timeline-content"
+      data-side={itemCtx.resolvedSide}
+      className={cn(
+        // leading-5 锁定首行高度 20px → 文字中心 10px，与 Separator pt-1 后的 dot 中心对齐
+        'min-w-0 pb-6 text-xs leading-5',
+        // right：内容固定在第 3 列
+        isRight && 'col-start-3',
+        // alternate：根据 resolvedSide 切换列；在左侧时 text-right 让文本贴近分隔列
+        isAlternate && itemCtx.resolvedSide === 'right' && 'col-start-3',
+        isAlternate &&
+          itemCtx.resolvedSide === 'left' &&
+          'col-start-1 text-right',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TimelineOppositeContent ─────────────────────────────────────────────────
+
+/** 对侧内容区 — 渲染于分隔列对侧，常用于时间标签；mode='left' 时不渲染。 */
+export interface TimelineOppositeContentProps
+  extends React.ComponentProps<'div'> {}
+
+function TimelineOppositeContent({
+  className,
+  ...props
+}: TimelineOppositeContentProps) {
+  const { mode } = React.useContext(TimelineContext);
+  const itemCtx = useTimelineItem();
+  // mode=left 时不渲染对侧内容（留作可选时间标签）
+  if (mode === 'left') return null;
+  const isAlternate = mode === 'alternate';
+  const isRight = mode === 'right';
+  return (
+    <div
+      data-slot="timeline-opposite"
+      data-side={itemCtx.resolvedSide === 'left' ? 'right' : 'left'}
+      className={cn(
+        // leading-5 与 Content / dot 中心对齐
+        'min-w-0 pb-6 text-xs leading-5 text-muted-foreground',
+        // right：对侧固定在第 1 列，文本右对齐使之贴近分隔列
+        isRight && 'col-start-1 text-right',
+        // alternate：content 在右时对侧在第 1 列右对齐；content 在左时对侧在第 3 列左对齐
+        isAlternate &&
+          itemCtx.resolvedSide === 'right' &&
+          'col-start-1 text-right',
+        isAlternate && itemCtx.resolvedSide === 'left' && 'col-start-3',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TimelineHeader / Title / Time / Description ─────────────────────────────
+
+/** Header — 横向并排放置 Title 与 Time。 */
+export interface TimelineHeaderProps extends React.ComponentProps<'div'> {}
+
+function TimelineHeader({ className, ...props }: TimelineHeaderProps) {
+  return (
+    <div
+      data-slot="timeline-header"
+      className={cn('flex items-center gap-2', className)}
+      {...props}
+    />
+  );
+}
+
+/** 标题 — 节点主标题，默认 text-sm font-medium。 */
+export interface TimelineTitleProps extends React.ComponentProps<'div'> {}
+
+function TimelineTitle({ className, ...props }: TimelineTitleProps) {
+  return (
+    <div
+      data-slot="timeline-title"
+      className={cn('text-sm font-medium text-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+/** 时间标签 — 渲染为语义 <time> 元素，可传 dateTime 属性。 */
+export interface TimelineTimeProps extends React.ComponentProps<'time'> {}
+
+function TimelineTime({ className, ...props }: TimelineTimeProps) {
+  return (
+    <time
+      data-slot="timeline-time"
+      className={cn('text-xs text-muted-foreground tabular-nums', className)}
+      {...props}
+    />
+  );
+}
+
+/** 描述 — 节点辅助文案，默认 text-xs muted。 */
+export interface TimelineDescriptionProps extends React.ComponentProps<'div'> {}
+
+function TimelineDescription({
+  className,
+  ...props
+}: TimelineDescriptionProps) {
+  return (
+    <div
+      data-slot="timeline-description"
+      className={cn('mt-1 text-xs text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Timeline,
+  TimelineItem,
+  TimelineSeparator,
+  TimelineDot,
+  TimelineConnector,
+  TimelineContent,
+  TimelineOppositeContent,
+  TimelineHeader,
+  TimelineTitle,
+  TimelineTime,
+  TimelineDescription,
+  timelineDotVariants,
+};