@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,94 @@
+import * as React from 'react';
+import { Clock } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface TimePickerProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    'onChange' | 'value' | 'defaultValue' | 'type' | 'size'
+  > {
+  /** 受控值(`HH:mm` 或 `HH:mm:ss`)— 空串表示未选。 */
+  value?: string;
+  /** uncontrolled 初值。 */
+  defaultValue?: string;
+  /** 值变化回调(实时,跟随原生 input)。 */
+  onChange?: (value: string) => void;
+  /**
+   * 是否显示秒(antd `showSeconds` 并集)— 关闭时原生 input 仅显示 HH:mm。
+   * @default false
+   */
+  showSeconds?: boolean;
+  /**
+   * 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。
+   * @default 60
+   */
+  step?: number;
+  /**
+   * 尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+const sizeMap = {
+  sm: 'h-8 text-xs',
+  default: 'h-9 text-sm',
+  lg: 'h-10 text-base',
+} as const;
+
+/**
+ * 时间选择 — antd 独有补足。**等价 antd `TimePicker`** 基本能力。
+ * 当前实现是**原生 `<input type="time">` 的样式封装**(零 JS,移动端友好);
+ * 复杂场景(范围选择 / disabledTime / 自定义面板)可后续基于 Popover + Listbox 升级。
+ */
+const TimePicker = React.forwardRef<HTMLInputElement, TimePickerProps>(
+  (
+    {
+      value,
+      defaultValue,
+      onChange,
+      showSeconds = false,
+      step = 60,
+      size = 'default',
+      disabled,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    return (
+      <div
+        className={cn(
+          'relative inline-flex w-fit items-center',
+          disabled && 'cursor-not-allowed opacity-50',
+        )}
+      >
+        <Clock
+          aria-hidden="true"
+          className="pointer-events-none absolute left-3 size-4 text-muted-foreground"
+        />
+        <input
+          ref={ref}
+          type="time"
+          value={value}
+          defaultValue={defaultValue}
+          step={showSeconds ? step : undefined}
+          disabled={disabled}
+          onChange={(e) => onChange?.(e.target.value)}
+          className={cn(
+            'w-full rounded-md border border-input bg-background pl-9 pr-3 text-foreground shadow-sm',
+            'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+            'disabled:cursor-not-allowed',
+            sizeMap[size],
+            className,
+          )}
+          {...props}
+        />
+      </div>
+    );
+  },
+);
+TimePicker.displayName = 'TimePicker';
+
+export { TimePicker };

package/src/components/timeline/timeline.meta.md

@@ -0,0 +1,102 @@
+---
+id: timeline
+name: Timeline
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Timeline
+
+时间轴 — antd 独有补足。**等价 antd `Timeline`**。垂直时间流(操作历史 / 物流轨迹 / 进度记录),支持 `left` / `right` / `alternate` 三种布局、5 种圆点颜色、自定义圆点节点、反向、尾部 `pending` 占位(配 Spinner 表示进行中)。
+
+## When to use
+
+- 操作历史 / 审计日志(谁在什么时候做了什么)
+- 物流 / 订单 / 项目进度轨迹
+- 个人主页 / 简历的时间线
+- 配 `pending` 表达"流程仍在进行中"
+
+## When NOT to use
+
+- 离散流程步骤 → `Steps`(强调阶段而非时间)
+- 数据表 → `Table` / `DataTable`
+- 不带时间属性的事件列表 → `List` / `Item` + `ItemGroup`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `items` | `TimelineItem[]` | – | ✓ | 节点列表。 |
+| `mode` | `'left' \| 'right' \| 'alternate'` | `"left"` | – | 布局模式 — `left`(默认 antd `mode`)左侧时间轴;`right` 右侧;`alternate` 两侧交替。 |
+| `reverse` | `boolean` | `false` | – | 反向(antd `reverse` 并集) — 最新条目排在最上。 |
+| `pending` | `React.ReactNode` | – | – | 在尾部追加一个"未结束"占位(antd `pending` 并集) — 通常配 `<Spinner>` 显示加载中。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add timeline` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **每项必须有 `children`** — `label` 仅用于时间 / 副标签(`left` 模式下也会渲染在主标题上方)
+- **`mode="alternate"`** 适合非密集长内容,适合两栏对照("时间 ↔ 事件")
+- **`color` 是语义色**:`error` 用于真错误,`success` 用于完成态;**不要**用 `warning` 表示"普通节点"
+- **自定义 `dot`**:用 lucide icon 节点,**尺寸控制在 12px(`size-3`)** 与默认圆点对齐
+- **`pending`** 配 `<Spinner size="sm" />` 是经典组合 — 表示"流程未结束,有新事件在路上"
+- **`reverse`**:数据天然按时间升序时用,**不要**先在外面 reverse 数据再传(直接用 prop 更明确)
+- **节点 > 20 个**建议折叠为分页 / Collapsible — Timeline 长得过深会失去时间感
+
+## Examples
+
+```tsx
+import { Timeline } from '@/components/ui/timeline';
+import { Spinner } from '@/components/ui/spinner';
+import { CheckCircle2 } from 'lucide-react';
+
+// 基础
+<Timeline
+  items={[
+    { children: '订单已创建', label: '2026-05-01 10:00' },
+    { children: '已发货', label: '2026-05-02 14:30', color: 'primary' },
+    { children: '已签收', label: '2026-05-04 09:15', color: 'success' },
+  ]}
+/>
+
+// 带 pending(进行中)
+<Timeline
+  items={[
+    { children: '订单已创建', color: 'success' },
+    { children: '正在打包', color: 'primary' },
+  ]}
+  pending={<><Spinner size="sm" tone="muted" /> 等待发货...</>}
+/>
+
+// 自定义 dot
+<Timeline
+  items={[
+    { children: '部署到 staging', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
+    { children: '回滚到 v1.2', color: 'error' },
+  ]}
+/>
+
+// alternate 布局
+<Timeline
+  mode="alternate"
+  items={[
+    { label: '2026-01', children: '项目启动' },
+    { label: '2026-03', children: 'beta 发布' },
+    { label: '2026-05', children: 'GA 发布' },
+  ]}
+/>
+```

package/src/components/timeline/timeline.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CheckCircle2 } from 'lucide-react';
+import { Timeline } from './timeline';
+import { Spinner } from '@/components/spinner/spinner';
+
+const meta: Meta<typeof Timeline> = {
+  title: '数据展示 · Data Display/Timeline',
+  component: Timeline,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '时间轴 — 垂直时间流(操作历史 / 物流轨迹 / 进度记录)。3 种布局(left / right / alternate)+ 5 种圆点语义色 + 自定义 dot + pending 进行中占位。等价 antd `Timeline`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Timeline>;
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80">
+      <Timeline
+        items={[
+          { children: '订单已创建', label: '2026-05-01 10:00' },
+          { children: '已发货', label: '2026-05-02 14:30', color: 'primary' },
+          { children: '已签收', label: '2026-05-04 09:15', color: 'success' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const WithPending: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80">
+      <Timeline
+        items={[
+          { children: '订单已创建', color: 'success' },
+          { children: '正在打包', color: 'primary' },
+        ]}
+        pending={
+          <span className="inline-flex items-center gap-1">
+            <Spinner size="sm" tone="muted" />
+            等待发货...
+          </span>
+        }
+      />
+    </div>
+  ),
+};
+
+export const CustomDots: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-96">
+      <Timeline
+        items={[
+          { children: '部署到 staging 成功', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
+          { children: 'staging 验证通过', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
+          { children: '回滚到 v1.2', color: 'error' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const Alternate: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-[28rem]">
+      <Timeline
+        mode="alternate"
+        items={[
+          { label: '2026-01', children: '项目启动' },
+          { label: '2026-03', children: 'beta 内部测试' },
+          { label: '2026-05', children: 'GA 正式发布' },
+          { label: '2026-07', children: 'v2 规划' },
+        ]}
+      />
+    </div>
+  ),
+};
+
+export const Reverse: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80">
+      <Timeline
+        reverse
+        items={[
+          { children: '订单已创建', label: '2026-05-01 10:00', color: 'default' },
+          { children: '已发货', label: '2026-05-02 14:30', color: 'primary' },
+          { children: '已签收', label: '2026-05-04 09:15', color: 'success' },
+        ]}
+      />
+    </div>
+  ),
+};

package/src/components/timeline/timeline.tsx

@@ -0,0 +1,147 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+
+export type TimelineDotColor =
+  | 'default'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'error';
+
+const dotColorMap: Record<TimelineDotColor, string> = {
+  default: 'bg-muted-foreground',
+  primary: 'bg-primary',
+  success: 'bg-emerald-500',
+  warning: 'bg-amber-500',
+  error: 'bg-destructive',
+};
+
+export interface TimelineItem {
+  /** 节点内容(主体)。 */
+  children: React.ReactNode;
+  /** 左侧时间 / 标签(antd `label` 并集 — 仅 `mode="alternate"` / 左侧布局时显式渲染)。 */
+  label?: React.ReactNode;
+  /**
+   * 圆点颜色(antd `color` 并集) — 也可传 `dot` 完全自定义。
+   * @default "default"
+   */
+  color?: TimelineDotColor;
+  /**
+   * 自定义圆点节点(antd `dot` 并集) — 传节点(如 icon)替换默认圆点。
+   */
+  dot?: React.ReactNode;
+}
+
+export interface TimelineProps extends React.HTMLAttributes<HTMLOListElement> {
+  /** 节点列表。 */
+  items: TimelineItem[];
+  /**
+   * 布局模式 — `left`(默认 antd `mode`)左侧时间轴;`right` 右侧;`alternate` 两侧交替。
+   * @default "left"
+   */
+  mode?: 'left' | 'right' | 'alternate';
+  /**
+   * 反向(antd `reverse` 并集) — 最新条目排在最上。
+   * @default false
+   */
+  reverse?: boolean;
+  /**
+   * 在尾部追加一个"未结束"占位(antd `pending` 并集) — 通常配 `<Spinner>` 显示加载中。
+   */
+  pending?: React.ReactNode;
+}
+
+const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
+  (
+    { items, mode = 'left', reverse = false, pending, className, ...props },
+    ref,
+  ) => {
+    const finalItems = reverse ? [...items].reverse() : items;
+
+    const renderDot = (it: TimelineItem) =>
+      it.dot ? (
+        <span className="flex size-3 items-center justify-center text-primary">
+          {it.dot}
+        </span>
+      ) : (
+        <span
+          className={cn(
+            'size-3 rounded-full ring-2 ring-background',
+            dotColorMap[it.color ?? 'default'],
+          )}
+        />
+      );
+
+    return (
+      <ol
+        ref={ref}
+        className={cn('relative flex flex-col gap-6', className)}
+        {...props}
+      >
+        {finalItems.map((it, i) => {
+          const isLast = i === finalItems.length - 1 && !pending;
+          const sideRight = mode === 'right' || (mode === 'alternate' && i % 2 === 1);
+          return (
+            <li
+              key={i}
+              className={cn(
+                'relative grid items-start gap-3',
+                mode === 'alternate'
+                  ? 'grid-cols-[1fr_auto_1fr]'
+                  : sideRight
+                    ? 'grid-cols-[1fr_auto]'
+                    : 'grid-cols-[auto_1fr]',
+              )}
+            >
+              {/* left slot */}
+              {mode === 'alternate' || mode === 'right' ? (
+                <div className={cn('min-w-0 text-sm', sideRight ? '' : 'text-right')}>
+                  {!sideRight ? it.children : it.label}
+                </div>
+              ) : null}
+
+              {/* center: dot + line */}
+              <div className="relative flex flex-col items-center">
+                {renderDot(it)}
+                {!isLast ? (
+                  <span
+                    aria-hidden="true"
+                    className="absolute top-3 h-[calc(100%+1.5rem)] w-px bg-border"
+                  />
+                ) : null}
+              </div>
+
+              {/* right slot */}
+              {mode === 'alternate' ? (
+                <div className="min-w-0 text-sm">
+                  {sideRight ? it.children : it.label}
+                </div>
+              ) : mode === 'left' ? (
+                <div className="min-w-0">
+                  {it.label ? (
+                    <div className="mb-0.5 text-xs text-muted-foreground">{it.label}</div>
+                  ) : null}
+                  <div className="text-sm">{it.children}</div>
+                </div>
+              ) : (
+                <div className="min-w-0 text-sm">
+                  {sideRight ? it.children : null}
+                </div>
+              )}
+            </li>
+          );
+        })}
+        {pending ? (
+          <li className="grid grid-cols-[auto_1fr] items-start gap-3">
+            <span className="size-3 rounded-full bg-muted-foreground/50 ring-2 ring-background" />
+            <div className="text-sm text-muted-foreground">{pending}</div>
+          </li>
+        ) : null}
+      </ol>
+    );
+  },
+);
+Timeline.displayName = 'Timeline';
+
+export { Timeline };

package/src/components/toggle/toggle.meta.md

@@ -0,0 +1,88 @@
+---
+id: toggle
+name: Toggle
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Toggle
+
+二元状态按钮 — Radix Toggle 包装。**shadcn-only**(antd 无独立对标,与 Switch 形态不同)。
+
+形态上更接近一个"按钮",按下后保持按下视觉,常用于工具栏的图标级开关(Bold / Italic / 视图切换等)。
+
+## When to use
+
+- 工具栏图标按钮组(配 `ToggleGroup`)
+- 保留视觉状态的图标级二元切换(开/关 + 图标变化)
+- 视图切换(Grid / List)
+
+## When NOT to use
+
+- 立即生效的设置项 → 用 `Switch`(语义更清晰)
+- 表单提交项 → 用 `Checkbox`
+- 多个互斥选项 → 用 `RadioGroup` 或 `ToggleGroup`(v0.x)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline'` | `"default"` | – | 视觉风格。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add toggle` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-toggle@^1.1.0 class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 Radix Toggle.Root props(`pressed` / `defaultPressed` / `onPressedChange` / `disabled` 等)。
+
+## AI 生成纪律
+
+- **图标按钮必带 `aria-label`**:Toggle 仅有图标无文字时,无障碍语义不足
+- **不要嵌套交互**:Toggle 内不要放 button / link
+- **`outline` variant 用在浅色面板**:default 在白底容易"看不见未按下态",必要时切 outline
+
+## Examples
+
+```tsx
+import { Toggle } from '@/components/ui/toggle';
+import { Bold } from 'lucide-react';
+
+// 图标按钮
+<Toggle aria-label="加粗">
+  <Bold />
+</Toggle>
+
+// outline + 文字
+<Toggle variant="outline">视图切换</Toggle>
+
+// 受控
+const [bold, setBold] = React.useState(false);
+<Toggle pressed={bold} onPressedChange={setBold} aria-label="加粗">
+  <Bold />
+</Toggle>
+```

package/src/components/toggle/toggle.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Bold, Italic, Underline } from 'lucide-react';
+import { Toggle } from './toggle';
+
+const meta: Meta<typeof Toggle> = {
+  title: '表单与输入 · Form/Toggle',
+  component: Toggle,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '切换按钮 — 二状态 (开 / 关) 按钮，常用于富文本编辑器工具栏 (加粗 / 斜体 / 下划线) 等场景。Radix Toggle 实现， shadcn 专有（antd 未提供对应原子组件，antd 逻辑上以 Radio.Button + Switch 组合表达）。支持 `variant`（default / outline）与 `size`（sm / default / lg）。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['default', 'outline'] },
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    disabled: { control: 'boolean' },
+  },
+  args: { variant: 'default', size: 'default', disabled: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Toggle>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Toggle {...args} aria-label="加粗">
+      <Bold />
+    </Toggle>
+  ),
+};
+
+export const Variants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Toggle aria-label="加粗">
+        <Bold />
+      </Toggle>
+      <Toggle variant="outline" aria-label="斜体">
+        <Italic />
+      </Toggle>
+      <Toggle variant="outline">显示图例</Toggle>
+    </div>
+  ),
+};
+
+export const Toolbar: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-1 rounded-md border p-1">
+      <Toggle size="sm" aria-label="加粗">
+        <Bold />
+      </Toggle>
+      <Toggle size="sm" aria-label="斜体">
+        <Italic />
+      </Toggle>
+      <Toggle size="sm" aria-label="下划线">
+        <Underline />
+      </Toggle>
+    </div>
+  ),
+};

package/src/components/toggle/toggle.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import * as TogglePrimitive from '@radix-ui/react-toggle';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const toggleVariants = cva(
+  'inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'bg-transparent',
+        outline:
+          'border border-input bg-transparent hover:bg-accent hover:text-accent-foreground',
+      },
+      size: {
+        sm: 'h-8 px-2 min-w-8',
+        default: 'h-9 px-3 min-w-9',
+        lg: 'h-10 px-4 min-w-10',
+      },
+    },
+    defaultVariants: { variant: 'default', size: 'default' },
+  },
+);
+
+export interface ToggleProps
+  extends React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root>,
+    VariantProps<typeof toggleVariants> {
+  /**
+   * 视觉风格。
+   * @default "default"
+   */
+  variant?: 'default' | 'outline';
+  /**
+   * 尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+const Toggle = React.forwardRef<
+  React.ElementRef<typeof TogglePrimitive.Root>,
+  ToggleProps
+>(({ className, variant, size, ...props }, ref) => (
+  <TogglePrimitive.Root
+    ref={ref}
+    className={cn(toggleVariants({ variant, size }), className)}
+    {...props}
+  />
+));
+Toggle.displayName = TogglePrimitive.Root.displayName;
+
+export { Toggle, toggleVariants };