@teamix-evo/ui 0.1.1 → 0.2.0

package/src/components/tabs/tabs.meta.md

@@ -1,13 +1,14 @@
 ---
 id: tabs
 name: Tabs
+displayName: 标签页
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Tabs
+# Tabs 标签页
 
 标签页 — Radix Tabs + antd `type` (line/card) + `tabBarExtraContent`(`extra`) 并集。
 两种风格切换:`type="card"`(shadcn 默认胶囊),`type="line"`(antd 默认下划线)。
@@ -29,10 +30,12 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `TabsList` 的 props;`Tabs`(Root)透传 Radix `value / defaultValue / onValueChange / orientation / activationMode`。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `type` | `'line' \| 'card'` | `"card"` | – | 视觉风格(antd `type` 并集)。`card` 是 shadcn 默认胶囊;`line` 是 antd 默认下划线。 |
-| `extra` | `React.ReactNode` | – | – | 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `type="line"` 显式支持(布局灵活)。 用法:把节点放进来即可,组件用 `flex justify-between` 自动撑开。 |
+
+| 名称    | 类型               | 默认值   | 必填 | 说明                                                                                                                                              |
+| ------- | ------------------ | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`  | `'line' \| 'card'` | `"card"` | –    | 视觉风格(antd `type` 并集)。`card` 是 shadcn 默认胶囊;`line` 是 antd 默认下划线。                                                                 |
+| `extra` | `React.ReactNode`  | –        | –    | 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `type="line"` 显式支持(布局灵活)。 用法:把节点放进来即可,组件用 `flex justify-between` 自动撑开。 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -40,13 +43,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add tabs` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -55,6 +59,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add @radix-ui/react-tabs@^1.1.0 class-variance-authority@^0.7.0
 ```
+
 <!-- auto:deps:end -->
 
 > 子组件:`Tabs` / `TabsList` / `TabsTrigger` / `TabsContent`。

package/src/components/tabs/tabs.stories.tsx

@@ -7,6 +7,14 @@ const meta: Meta<typeof TabsList> = {
   title: '导航 · Navigation/Tabs',
   component: TabsList,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '标签页 — Radix Tabs + antd type(line/card) + tabBarExtraContent(extra) 并集。胶囊风格(card) 适合嵌入场景,下划线风格(line) 适合页面级切换。',
+      },
+    },
+  },
   argTypes: {
     type: { control: 'inline-radio', options: ['card', 'line'] },
   },

package/src/components/tag/tag.meta.md

@@ -1,13 +1,14 @@
 ---
 id: tag
 name: Tag
+displayName: 标签
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Tag
+# Tag 标签
 
 标签 — antd 独有补足。**与 Badge 区别**:Tag 偏向**用户可关闭的关键词标签**(分类 / 标签 / 筛选条件),支持 `closable` + 6 种语义色;Badge 偏向**状态徽标**(数字 / 红点 / 状态条)。
 
@@ -23,22 +24,49 @@ package: "@teamix-evo/ui"
 - 切换按钮 → `Toggle` / `ToggleGroup`
 - 选择类输入 → `Combobox` / `Select`
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `"default"` | – | 语义颜色(antd `color` 并集) — 与 Badge 不同,Tag 偏向**用户可关闭的标签**(关键词 / 分类),Badge 偏向状态徽标。 |
-| `closable` | `boolean` | `false` | – | 显示关闭按钮(antd `closable` 并集)。 |
-| `onClose` | `() => void` | – | – | 关闭回调。 |
+
+#### Tag
+
+| 名称       | 类型                                                                    | 默认值      | 必填 | 说明                                                                                                         |
+| ---------- | ----------------------------------------------------------------------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------ |
+| `color`    | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `"default"` | –    | 语义颜色(antd `color` 并集) — 与 Badge 不同,Tag 偏向**用户可关闭的标签**(关键词 / 分类),Badge 偏向状态徽标。 |
+| `closable` | `boolean`                                                               | `false`     | –    | 显示关闭按钮(antd `closable` 并集)。                                                                         |
+| `onClose`  | `() => void`                                                            | –           | –    | 关闭回调。                                                                                                   |
+
+#### CheckableTag
+
+| 名称       | 类型                      | 默认值 | 必填 | 说明             |
+| ---------- | ------------------------- | ------ | ---- | ---------------- |
+| `checked`  | `boolean`                 | –      | ✓    | 是否选中(受控)。 |
+| `onChange` | `(next: boolean) => void` | –      | –    | 选中态变化回调。 |
+| `disabled` | `boolean`                 | –      | –    | 禁用。           |
+
+#### CheckableTagGroup
+
+| 名称           | 类型                        | 默认值 | 必填 | 说明                  |
+| -------------- | --------------------------- | ------ | ---- | --------------------- |
+| `options`      | `CheckableTagGroupOption[]` | –      | ✓    | 候选项数组。          |
+| `value`        | `string[]`                  | –      | –    | 受控选中 value 集合。 |
+| `defaultValue` | `string[]`                  | –      | –    | 非受控初值。          |
+| `onChange`     | `(next: string[]) => void`  | –      | –    | 选中变化回调。        |
+| `disabled`     | `boolean`                   | –      | –    | 整组禁用。            |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add tag` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -47,6 +75,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/tag/tag.stories.tsx

@@ -10,7 +10,7 @@ const meta: Meta<typeof Tag> = {
     docs: {
       description: {
         component:
-          '标签 — 用户可关闭的关键词 / 分类标签(分类、筛选条件、博客标签)。6 种语义色 + closable + onClose。OpenTrek tokens 适配,等价 antd Tag(与 Badge 互补,Badge 偏状态徽标)。',
+          '标签 — 用户可关闭的关键词 / 分类标签（分类、筛选条件、博客标签）。6 种语义色 + closable + onClose。等价 antd Tag（与 Badge 互补，Badge 偏状态徽标）。',
       },
     },
   },
@@ -46,7 +46,12 @@ export const Colors: Story = {
 export const Closable: Story = {
   parameters: { controls: { disable: true } },
   render: () => {
-    const [tags, setTags] = React.useState(['React', 'Vue', 'Angular', 'Svelte']);
+    const [tags, setTags] = React.useState([
+      'React',
+      'Vue',
+      'Angular',
+      'Svelte',
+    ]);
     return (
       <div className="flex flex-wrap gap-2">
         {tags.map((t) => (

package/src/components/tag/tag.tsx

@@ -11,10 +11,10 @@ const tagVariants = cva(
       color: {
         default: 'border-border bg-muted text-foreground',
         primary: 'border-primary/30 bg-primary/10 text-primary',
-        success: 'border-emerald-200 bg-emerald-50 text-emerald-700',
-        warning: 'border-amber-200 bg-amber-50 text-amber-700',
+        success: 'border-success-border/30 bg-success-subtle text-success',
+        warning: 'border-warning-border/30 bg-warning-subtle text-warning',
         error: 'border-destructive/30 bg-destructive/10 text-destructive',
-        info: 'border-blue-200 bg-blue-50 text-blue-700',
+        info: 'border-info-border/30 bg-info-subtle text-info',
       },
     },
     defaultVariants: { color: 'default' },

package/src/components/textarea/textarea.meta.md

@@ -4,10 +4,11 @@ name: Textarea
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 多行文本框
 ---
 
-# Textarea
+# Textarea 多行文本框
 
 多行文本输入 — shadcn 简洁基底 + antd 的 `autoSize / showCount`。
 
@@ -27,13 +28,15 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `autoSize` | `boolean \| { minRows?: number; maxRows?: number }` | `false` | – | 自动高度。`true` 时无上下限;传 `{ minRows, maxRows }` 时受限。 实现:监听 input 事件,把 textarea 设为 auto 后再读 scrollHeight。 |
-| `showCount` | `boolean` | `false` | – | 显示字符计数(antd `showCount` 并集);需配合 `maxLength`。 |
-| `value` | `string` | – | – | 受控值。 |
-| `defaultValue` | `string` | – | – | uncontrolled 初始值。 |
-| `rows` | `number` | `3` | – | 行数(autoSize 关闭时生效)。 |
+
+| 名称           | 类型                                                | 默认值  | 必填 | 说明                                                                                                                            |
+| -------------- | --------------------------------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `autoSize`     | `boolean \| { minRows?: number; maxRows?: number }` | `false` | –    | 自动高度。`true` 时无上下限;传 `{ minRows, maxRows }` 时受限。 实现:监听 input 事件,把 textarea 设为 auto 后再读 scrollHeight。 |
+| `showCount`    | `boolean`                                           | `false` | –    | 显示字符计数(antd `showCount` 并集);需配合 `maxLength`。                                                                        |
+| `value`        | `string`                                            | –       | –    | 受控值。                                                                                                                        |
+| `defaultValue` | `string`                                            | –       | –    | uncontrolled 初始值。                                                                                                           |
+| `rows`         | `number`                                            | `3`     | –    | 行数(autoSize 关闭时生效)。                                                                                                     |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -41,17 +44,19 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add textarea` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 > 透传所有 `<textarea>` 原生属性(`name` / `placeholder` / `disabled` / `onChange` / ...)。

package/src/components/textarea/textarea.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Textarea> = {
     docs: {
       description: {
         component:
-          '多行文本输入 — 用于输入多行文本信息。shadcn `Textarea` 原子 + antd `Input.TextArea` 的并集能力：支持 `autoSize`（传 `{ minRows, maxRows }` 随内容自适应高度）、`showCount` 发表字数计数、`maxLength` 限制。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '多行文本输入 — 用于输入多行文本信息。shadcn `Textarea` 原子 + antd `Input.TextArea` 的并集能力：支持 `autoSize`（传 `{ minRows, maxRows }` 随内容自适应高度）、`showCount` 发表字数计数、`maxLength` 限制。',
       },
     },
   },

package/src/components/textarea/textarea.tsx

@@ -88,7 +88,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         onChange={handleChange}
         className={cn(
           'flex w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
-          autoSize ? 'resize-none' : 'min-h-[80px]',
+          autoSize ? 'resize-none' : 'min-h-textarea',
           className,
         )}
         {...props}

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

@@ -1,13 +1,14 @@
 ---
 id: time-picker
 name: TimePicker
+displayName: 时间选择
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# TimePicker
+# TimePicker 时间选择
 
 时间选择 — antd 独有补足。**等价 antd `TimePicker`** 的基础能力,基于原生 `<input type="time">` 样式封装(零 JS、移动端友好、SSR safe)。配 `DatePicker` 完成日期 + 时间填写。
 
@@ -22,25 +23,37 @@ package: "@teamix-evo/ui"
 - 日期 → `DatePicker`(日期 + 时间二合一也可在 DatePicker 上拓展)
 - 复杂禁用规则 / 自定义面板:当前实现走原生,**不支持** `disabledHours` / `disabledMinutes` 等 antd 高级 API — 需要时基于 Popover + ListBox 自实现
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `value` | `string` | – | – | 受控值(`HH:mm` 或 `HH:mm:ss`)— 空串表示未选。 |
-| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
-| `onChange` | `(value: string) => void` | – | – | 值变化回调(实时,跟随原生 input)。 |
-| `showSeconds` | `boolean` | `false` | – | 是否显示秒(antd `showSeconds` 并集)— 关闭时原生 input 仅显示 HH:mm。 |
-| `step` | `number` | `60` | – | 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+
+| 名称           | 类型                        | 默认值         | 必填 | 说明                                                                 |
+| -------------- | --------------------------- | -------------- | ---- | -------------------------------------------------------------------- |
+| `value`        | `string`                    | –              | –    | 受控值(`HH:mm` 或 `HH:mm:ss`)— 空串表示未选。                        |
+| `defaultValue` | `string`                    | –              | –    | uncontrolled 初值。                                                  |
+| `onChange`     | `(value: string) => void`   | –              | –    | 值变化回调(实时,跟随原生 input)。                                    |
+| `showSeconds`  | `boolean`                   | `false`        | –    | 是否显示秒(antd `showSeconds` 并集)— 关闭时原生 input 仅显示 HH:mm。 |
+| `step`         | `number`                    | `60`           | –    | 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。         |
+| `size`         | `'sm' \| 'default' \| 'lg'` | `"default"`    | –    | 尺寸。                                                               |
+| `min`          | `string`                    | –              | –    | 最小可选时间(antd `minDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。       |
+| `max`          | `string`                    | –              | –    | 最大可选时间(antd `maxDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。       |
+| `allowClear`   | `boolean`                   | `false`        | –    | 是否显示清除按钮(antd `allowClear` 并集)。                           |
+| `status`       | `'error' \| 'warning'`      | –              | –    | 校验状态,影响边框颜色(antd `status` 并集)。                          |
+| `placeholder`  | `string`                    | `"请选择时间"` | –    | 占位文本。                                                           |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add time-picker` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -49,6 +62,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
@@ -58,6 +72,9 @@ pnpm add lucide-react@^0.460.0
 - **`step`** 单位是**秒**(原生规范) — `step=900` 表示 15 分钟一档
 - **空状态用空字符串** `""`,不要传 `null` / `undefined`(原生 input 不接受 null)
 - **当前实现不支持 12 小时制 / AM-PM** — 浏览器根据系统 locale 自动决定显示格式;**不要**手动加 AM/PM 字段
+- **`allowClear` 仅在受控模式下有意义** — 点击清除会触发 `onChange('')`
+- **`status` 配 `Form` 使用** — 校验失败时传 `status="error"`,不要手动写 `className="border-destructive"`
+- **`min` / `max` 是原生约束** — 浏览器会阻止选择范围外的时间,但手动输入仍可绕过,严格场景需配 zod 校验
 
 ## Examples
 
@@ -68,13 +85,19 @@ import * as React from 'react';
 // 基础(HH:mm)
 <TimePicker defaultValue="09:30" />
 
-// 受控 + 秒
+// 受控 + 秒 + 可清除
 const [t, setT] = React.useState('09:30:00');
-<TimePicker value={t} onChange={setT} showSeconds />
+<TimePicker value={t} onChange={setT} showSeconds allowClear />
 
 // 15 分钟一档
 <TimePicker step={15 * 60} />
 
+// 限制工作时间范围
+<TimePicker defaultValue="09:00" min="09:00" max="18:00" />
+
+// 校验状态
+<TimePicker defaultValue="09:00" status="error" />
+
 // 与 DatePicker 配对
 <div className="flex gap-2">
   <DatePicker />

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

@@ -10,7 +10,7 @@ const meta: Meta<typeof TimePicker> = {
     docs: {
       description: {
         component:
-          '时间选择 — 基于原生 input[type=time] 样式封装(零 JS、移动端友好、SSR safe)。等价 antd `TimePicker` 基础能力,复杂禁用规则需自实现。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '时间选择 — 基于原生 input[type=time] 样式封装（零 JS、移动端友好、SSR safe）。图标在右侧（suffix 位置，对齐 antd），有值时可清除。等价 antd `TimePicker` 基础能力，复杂禁用规则需自实现。',
       },
     },
   },
@@ -18,15 +18,25 @@ const meta: Meta<typeof TimePicker> = {
     size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
     showSeconds: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    allowClear: { control: 'boolean' },
+    status: {
+      control: 'inline-radio',
+      options: [undefined, 'error', 'warning'],
+    },
+  },
+  args: {
+    size: 'default',
+    showSeconds: true,
+    disabled: false,
+    allowClear: true,
   },
-  args: { size: 'default', showSeconds: false, disabled: false },
 };
 
 export default meta;
 type Story = StoryObj<typeof TimePicker>;
 
 export const Playground: Story = {
-  render: (args) => <TimePicker {...args} defaultValue="09:30" />,
+  render: (args) => <TimePicker {...args} defaultValue="09:30:00" />,
 };
 
 export const Controlled: Story = {
@@ -35,8 +45,10 @@ export const Controlled: Story = {
     const [t, setT] = React.useState('09:30:00');
     return (
       <div className="flex items-center gap-3">
-        <TimePicker value={t} onChange={setT} showSeconds />
-        <span className="text-sm text-muted-foreground tabular-nums">{t || '(空)'}</span>
+        <TimePicker value={t} onChange={setT} showSeconds allowClear />
+        <span className="text-sm text-muted-foreground tabular-nums">
+          {t || '(空)'}
+        </span>
       </div>
     );
   },
@@ -44,7 +56,9 @@ export const Controlled: Story = {
 
 export const QuarterHourStep: Story = {
   parameters: { controls: { disable: true } },
-  render: () => <TimePicker showSeconds step={15 * 60} defaultValue="10:00:00" />,
+  render: () => (
+    <TimePicker showSeconds step={15 * 60} defaultValue="10:00:00" />
+  ),
 };
 
 export const Sizes: Story = {
@@ -57,3 +71,27 @@ export const Sizes: Story = {
     </div>
   ),
 };
+
+export const AllowClear: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [t, setT] = React.useState('14:30');
+    return <TimePicker value={t} onChange={setT} allowClear />;
+  },
+};
+
+export const MinMax: Story = {
+  name: 'Min / Max 限制',
+  parameters: { controls: { disable: true } },
+  render: () => <TimePicker defaultValue="09:00" min="09:00" max="18:00" />,
+};
+
+export const Status: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <TimePicker defaultValue="09:00" status="error" />
+      <TimePicker defaultValue="09:00" status="warning" />
+    </div>
+  ),
+};

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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Clock } from 'lucide-react';
+import { Clock, X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
@@ -21,6 +21,7 @@ export interface TimePickerProps
   showSeconds?: boolean;
   /**
    * 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。
+   * 当 showSeconds=true 且未手动指定时,默认为 1(启用秒级选择)。
    * @default 60
    */
   step?: number;
@@ -29,6 +30,28 @@ export interface TimePickerProps
    * @default "default"
    */
   size?: 'sm' | 'default' | 'lg';
+  /**
+   * 最小可选时间(antd `minDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。
+   */
+  min?: string;
+  /**
+   * 最大可选时间(antd `maxDate` 并集),格式 `HH:mm` 或 `HH:mm:ss`。
+   */
+  max?: string;
+  /**
+   * 是否显示清除按钮(antd `allowClear` 并集)。
+   * @default false
+   */
+  allowClear?: boolean;
+  /**
+   * 校验状态,影响边框颜色(antd `status` 并集)。
+   */
+  status?: 'error' | 'warning';
+  /**
+   * 占位文本。
+   * @default "请选择时间"
+   */
+  placeholder?: string;
 }
 
 const sizeMap = {
@@ -42,6 +65,11 @@ const sizeMap = {
  * 当前实现是**原生 `<input type="time">` 的样式封装**(零 JS,移动端友好);
  * 复杂场景(范围选择 / disabledTime / 自定义面板)可后续基于 Popover + Listbox 升级。
  */
+const statusStyles = {
+  error: 'border-destructive focus-visible:ring-destructive/30',
+  warning: 'border-warning focus-visible:ring-warning/30',
+} as const;
+
 const TimePicker = React.forwardRef<HTMLInputElement, TimePickerProps>(
   (
     {
@@ -49,42 +77,78 @@ const TimePicker = React.forwardRef<HTMLInputElement, TimePickerProps>(
       defaultValue,
       onChange,
       showSeconds = false,
-      step = 60,
+      step,
       size = 'default',
+      min,
+      max,
+      allowClear = false,
+      status,
+      placeholder = '请选择时间',
       disabled,
       className,
       ...props
     },
     ref,
   ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    React.useImperativeHandle(ref, () => inputRef.current!);
+
+    const showClear = allowClear && !disabled && !!value;
+
+    // showSeconds 时 step 默认为 1(启用秒级选择),否则不设置 step(仅 HH:mm)
+    const resolvedStep = showSeconds ? step ?? 1 : undefined;
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.preventDefault();
+      onChange?.('');
+      inputRef.current?.focus();
+    };
+
     return (
       <div
         className={cn(
-          'relative inline-flex w-fit items-center',
+          'group/tp 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}
+          ref={inputRef}
           type="time"
           value={value}
           defaultValue={defaultValue}
-          step={showSeconds ? step : undefined}
+          min={min}
+          max={max}
+          step={resolvedStep}
           disabled={disabled}
+          placeholder={placeholder}
           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',
+            'w-full rounded-md border border-input bg-background px-3 pr-8 text-foreground shadow-sm',
             'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
             'disabled:cursor-not-allowed',
+            status && statusStyles[status],
             sizeMap[size],
             className,
           )}
           {...props}
         />
+        {/* Suffix: clear button (on hover/value) or clock icon */}
+        {showClear ? (
+          <button
+            type="button"
+            tabIndex={-1}
+            aria-label="清除时间"
+            onClick={handleClear}
+            className="absolute right-2 flex items-center justify-center rounded-full p-0.5 text-muted-foreground hover:text-foreground"
+          >
+            <X className="size-3.5" />
+          </button>
+        ) : (
+          <Clock
+            aria-hidden="true"
+            className="pointer-events-none absolute right-2.5 size-4 text-muted-foreground"
+          />
+        )}
       </div>
     );
   },