@teamix-evo/ui 0.1.1

package/src/components/input-number/input-number.meta.md

@@ -0,0 +1,91 @@
+---
+id: input-number
+name: InputNumber
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# InputNumber
+
+数字输入 — antd 独有补足。**等价 antd `InputNumber`**。区别于原生 `<input type="number">`:步进按钮显隐可配、范围裁剪与精度由组件保证、千分位展示、键盘 ↑↓ 步进、支持空状态(`value=null`)。
+
+## When to use
+
+- 价格 / 数量 / 度量等数值输入(配 `min` / `max` / `step` 范围限制)
+- 需要精度控制的小数(`precision={2}`)
+- 大数展示千分位(`groupSeparator`)
+- 移动端友好的数字键盘(已设 `inputMode="decimal"`)
+
+## When NOT to use
+
+- 滑动选择 → `Slider`
+- 多档枚举 → `Segmented` / `RadioGroup`
+- 普通文本输入 → `Input`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| null` | – | – | 受控值 — `null` 等价空输入。 |
+| `defaultValue` | `number \| null` | – | – | uncontrolled 初值。 |
+| `onChange` | `(value: number \| null) => void` | – | – | 值变化回调 — 输入清空时传 `null`,正常输入 / 步进传 `number`。 |
+| `min` | `number` | – | – | 最小值(antd `min` 并集)。 |
+| `max` | `number` | – | – | 最大值(antd `max` 并集)。 |
+| `step` | `number` | `1` | – | 步长(antd `step` 并集) — 增 / 减按钮以及键盘 ↑↓ 都按此步长。 |
+| `precision` | `number` | – | – | 数值精度(antd `precision` 并集) — 保留小数位数(超出会四舍五入)。 |
+| `groupSeparator` | `boolean` | `false` | – | 千分位分隔展示(仅展示用,实际 value 仍是 number)。 |
+| `controls` | `boolean` | `true` | – | 是否显示右侧上下步进按钮(antd `controls` 并集) — `false` 时隐藏。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add input-number` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **空状态 = `null`**(不要用 `0` 代表"空") — `onChange(null)` 时表单层应视为未填
+- **`min` / `max` 自动夹紧**:用户输入越界值,blur 时组件会自动 clamp;**不要**在外层再做边界校验
+- **`precision`** 控制保留小数位:超出位数会四舍五入展示,**实际 onChange 值也是 toFixed 后的 number**
+- **`groupSeparator`** 仅展示用:实际 value 仍是裸 number,不会带逗号
+- **`controls=false`** 仅在需要嵌入 InputGroup / 紧凑表格时关闭;默认带步进按钮更直观
+- **键盘 ↑↓ 已实现** — 不要再监听 keydown 加自定义步进
+- **不要传 `type="number"`** — 组件用 `type="text"` 才能支持千分位与精确控制
+
+## Examples
+
+```tsx
+import { InputNumber } from '@/components/ui/input-number';
+import * as React from 'react';
+
+// 基础
+<InputNumber defaultValue={10} min={0} max={100} />
+
+// 精度 + 千分位
+<InputNumber defaultValue={12345.67} precision={2} groupSeparator />
+
+// 受控
+const [v, setV] = React.useState<number | null>(1);
+<InputNumber value={v} onChange={setV} step={0.5} min={0} max={5} />
+
+// 隐藏步进按钮(配合 InputGroup 使用)
+<InputNumber controls={false} defaultValue={1} className="rounded-none" />
+
+// 小尺寸
+<InputNumber size="sm" defaultValue={0} />
+```

package/src/components/input-number/input-number.stories.tsx

@@ -0,0 +1,87 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { InputNumber } from './input-number';
+
+const meta: Meta<typeof InputNumber> = {
+  title: '表单与输入 · Form/InputNumber',
+  component: InputNumber,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '数字输入框 — 区别于原生 type=number:步进按钮显隐可配、范围裁剪与精度由组件保证、千分位展示、键盘 ↑↓ 步进、支持空状态。等价 antd `InputNumber`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    controls: { control: 'boolean' },
+    groupSeparator: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  args: { size: 'default', controls: true, groupSeparator: false, disabled: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof InputNumber>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <InputNumber {...args} defaultValue={10} min={0} max={100} className="w-40" />
+  ),
+};
+
+export const Precision: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <InputNumber
+      defaultValue={12345.67}
+      precision={2}
+      groupSeparator
+      step={0.01}
+      className="w-48"
+    />
+  ),
+};
+
+export const Controlled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState<number | null>(1.5);
+    return (
+      <div className="flex items-center gap-3">
+        <InputNumber
+          value={v}
+          onChange={setV}
+          step={0.5}
+          min={0}
+          max={5}
+          precision={1}
+          className="w-40"
+        />
+        <span className="text-sm text-muted-foreground tabular-nums">
+          值: {v === null ? '空' : v}
+        </span>
+      </div>
+    );
+  },
+};
+
+export const NoControls: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <InputNumber controls={false} defaultValue={1} className="w-32" />
+  ),
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <InputNumber size="sm" defaultValue={0} className="w-28" />
+      <InputNumber size="default" defaultValue={0} className="w-32" />
+      <InputNumber size="lg" defaultValue={0} className="w-36" />
+    </div>
+  ),
+};

package/src/components/input-number/input-number.tsx

@@ -0,0 +1,210 @@
+import * as React from 'react';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface InputNumberProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    'onChange' | 'value' | 'defaultValue' | 'min' | 'max' | 'step' | 'type' | 'size'
+  > {
+  /** 受控值 — `null` 等价空输入。 */
+  value?: number | null;
+  /** uncontrolled 初值。 */
+  defaultValue?: number | null;
+  /**
+   * 值变化回调 — 输入清空时传 `null`,正常输入 / 步进传 `number`。
+   */
+  onChange?: (value: number | null) => void;
+  /** 最小值(antd `min` 并集)。 */
+  min?: number;
+  /** 最大值(antd `max` 并集)。 */
+  max?: number;
+  /**
+   * 步长(antd `step` 并集) — 增 / 减按钮以及键盘 ↑↓ 都按此步长。
+   * @default 1
+   */
+  step?: number;
+  /**
+   * 数值精度(antd `precision` 并集) — 保留小数位数(超出会四舍五入)。
+   */
+  precision?: number;
+  /**
+   * 千分位分隔展示(仅展示用,实际 value 仍是 number)。
+   * @default false
+   */
+  groupSeparator?: boolean;
+  /**
+   * 是否显示右侧上下步进按钮(antd `controls` 并集) — `false` 时隐藏。
+   * @default true
+   */
+  controls?: boolean;
+  /**
+   * 尺寸。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+function format(
+  raw: number | null,
+  precision: number | undefined,
+  groupSeparator: boolean,
+): string {
+  if (raw === null || Number.isNaN(raw)) return '';
+  const fixed = precision !== undefined ? raw.toFixed(precision) : String(raw);
+  if (!groupSeparator) return fixed;
+  const [intPart, decPart] = fixed.split('.');
+  const grouped = intPart!.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return decPart !== undefined ? `${grouped}.${decPart}` : grouped;
+}
+
+const sizeMap = {
+  sm: 'h-8 text-xs',
+  default: 'h-9 text-sm',
+  lg: 'h-10 text-base',
+} as const;
+
+/**
+ * 数字输入框 — antd 独有补足。**等价 antd `InputNumber`**。区别于原生 `<input type="number">`:
+ *   - 步进按钮可自定义显隐
+ *   - 范围裁剪与 precision 由组件保证(超出 min/max 自动夹紧)
+ *   - 千分位展示(仅 UI)
+ *   - 支持空状态(value=null)
+ */
+const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
+  (
+    {
+      value,
+      defaultValue,
+      onChange,
+      min,
+      max,
+      step = 1,
+      precision,
+      groupSeparator = false,
+      controls = true,
+      size = 'default',
+      disabled,
+      className,
+      onBlur,
+      onKeyDown,
+      ...props
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<number | null>(
+      defaultValue ?? null,
+    );
+    const current = isControlled ? value! : internal;
+    const [editing, setEditing] = React.useState<string | null>(null);
+
+    const display = editing !== null ? editing : format(current, precision, groupSeparator);
+
+    const clamp = (n: number): number => {
+      let v = n;
+      if (typeof min === 'number') v = Math.max(min, v);
+      if (typeof max === 'number') v = Math.min(max, v);
+      if (typeof precision === 'number') v = Number(v.toFixed(precision));
+      return v;
+    };
+
+    const commit = (next: number | null) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    };
+
+    const handleInput = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const raw = e.target.value;
+      // Allow free typing of intermediate states ("-", "1.").
+      setEditing(raw);
+      if (raw === '' || raw === '-' || raw === '.') return;
+      const parsed = Number(raw.replace(/,/g, ''));
+      if (!Number.isNaN(parsed)) commit(clamp(parsed));
+    };
+
+    const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+      setEditing(null);
+      const raw = e.target.value;
+      if (raw === '' || raw === '-' || raw === '.') {
+        commit(null);
+      } else {
+        const parsed = Number(raw.replace(/,/g, ''));
+        commit(Number.isNaN(parsed) ? null : clamp(parsed));
+      }
+      onBlur?.(e);
+    };
+
+    const step1 = (sign: 1 | -1) => {
+      if (disabled) return;
+      const base = current ?? 0;
+      commit(clamp(base + sign * step));
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        step1(1);
+      } else if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        step1(-1);
+      }
+      onKeyDown?.(e);
+    };
+
+    return (
+      <div
+        className={cn(
+          'inline-flex items-stretch overflow-hidden rounded-md border border-input bg-background shadow-sm',
+          'focus-within:ring-1 focus-within:ring-ring',
+          disabled && 'cursor-not-allowed opacity-50',
+          className,
+        )}
+      >
+        <input
+          ref={ref}
+          type="text"
+          inputMode="decimal"
+          value={display}
+          disabled={disabled}
+          onChange={handleInput}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          className={cn(
+            'w-full bg-transparent px-3 text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed',
+            sizeMap[size],
+          )}
+          {...props}
+        />
+        {controls ? (
+          <div className="flex flex-col border-l">
+            <button
+              type="button"
+              tabIndex={-1}
+              disabled={disabled || (typeof max === 'number' && (current ?? -Infinity) >= max)}
+              onClick={() => step1(1)}
+              aria-label="增加"
+              className="flex h-1/2 items-center justify-center px-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30"
+            >
+              <ChevronUp className="size-3" />
+            </button>
+            <button
+              type="button"
+              tabIndex={-1}
+              disabled={disabled || (typeof min === 'number' && (current ?? Infinity) <= min)}
+              onClick={() => step1(-1)}
+              aria-label="减少"
+              className="flex h-1/2 items-center justify-center border-t px-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30"
+            >
+              <ChevronDown className="size-3" />
+            </button>
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);
+InputNumber.displayName = 'InputNumber';
+
+export { InputNumber };

package/src/components/input-otp/input-otp.meta.md

@@ -0,0 +1,105 @@
+---
+id: input-otp
+name: InputOTP
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# InputOTP
+
+OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/input-otp)。**shadcn-only**(antd 无对标组件)。
+4~8 位短验证码常见场景:登录、二步验证、支付确认。
+
+## When to use
+
+- 短信 / 邮件验证码输入
+- 二步验证(TOTP / 短信)
+- 支付密码 / PIN
+
+## When NOT to use
+
+- 长密码输入 → `Input type="password"`
+- 富文本 / 自由格式 → `Input` / `Textarea`
+- 银行卡号 → `Input` + `format` 函数
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`InputOTP` 透传 `input-otp` 的所有 props。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | – | – | 输入框 className,作用在隐藏的真实 input 上;通常无需关心。 |
+| `containerClassName` | `string` | – | – | 容器 className,作用在 slot 列表外层 wrapper 上, 用于覆盖默认的 `flex items-center gap-2`。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add input-otp` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add input-otp@^1.2.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 子组件:`InputOTP`(Root)/ `InputOTPGroup`(slot 容器)/ `InputOTPSlot`(单 slot,需 `index`)/ `InputOTPSeparator`(分隔符,如 4-4 数字之间的点)。
+
+## AI 生成纪律
+
+- **`maxLength` 必传**:声明位数(常见 4 / 6 / 8)
+- **每个 Slot 必传 `index`**:0-based,与 maxLength 对应
+- **`pattern` 限制字符类**:数字 OTP 用 `pattern={REGEXP_ONLY_DIGITS}`(从 `input-otp` 导入),避免用户粘贴混合字符
+- **多 Group 用 Separator**:6 位时分 3-3 或 4-2 提升可读性
+- **复制粘贴自带**:input-otp 自动处理,不需要再监听 paste
+
+## Examples
+
+```tsx
+import {
+  InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator,
+} from '@/components/ui/input-otp';
+import { REGEXP_ONLY_DIGITS } from 'input-otp';
+
+// 6 位
+<InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
+  <InputOTPGroup>
+    {[0, 1, 2, 3, 4, 5].map((i) => <InputOTPSlot key={i} index={i} />)}
+  </InputOTPGroup>
+</InputOTP>
+
+// 6 位,3-3 分组
+<InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+
+// 受控
+const [v, setV] = React.useState('');
+<InputOTP maxLength={6} value={v} onChange={setV}>
+  <InputOTPGroup>...</InputOTPGroup>
+</InputOTP>
+```

package/src/components/input-otp/input-otp.stories.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { REGEXP_ONLY_DIGITS } from 'input-otp';
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+  InputOTPSeparator,
+} from './input-otp';
+
+const meta: Meta<typeof InputOTP> = {
+  title: '表单与输入 · Form/InputOTP',
+  component: InputOTP,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof InputOTP>;
+
+export const SixDigits: Story = {
+  render: () => {
+    const [v, setV] = React.useState('');
+    return (
+      <InputOTP
+        maxLength={6}
+        pattern={REGEXP_ONLY_DIGITS}
+        value={v}
+        onChange={setV}
+      >
+        <InputOTPGroup>
+          {[0, 1, 2, 3, 4, 5].map((i) => (
+            <InputOTPSlot key={i} index={i} />
+          ))}
+        </InputOTPGroup>
+      </InputOTP>
+    );
+  },
+};
+
+export const Grouped: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
+      <InputOTPGroup>
+        <InputOTPSlot index={0} />
+        <InputOTPSlot index={1} />
+        <InputOTPSlot index={2} />
+      </InputOTPGroup>
+      <InputOTPSeparator />
+      <InputOTPGroup>
+        <InputOTPSlot index={3} />
+        <InputOTPSlot index={4} />
+        <InputOTPSlot index={5} />
+      </InputOTPGroup>
+    </InputOTP>
+  ),
+};

package/src/components/input-otp/input-otp.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import { OTPInput, OTPInputContext } from 'input-otp';
+import { Dot } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+/**
+ * InputOTP 自身的可定制属性。底层 `OTPInput` 的所有 props
+ * (`maxLength` / `pattern` / `value` / `onChange` / `onComplete` /
+ *  `children` / `render` / ...)由 input-otp 透传。
+ */
+export interface InputOTPProps {
+  /**
+   * 输入框 className,作用在隐藏的真实 input 上;通常无需关心。
+   */
+  className?: string;
+  /**
+   * 容器 className,作用在 slot 列表外层 wrapper 上,
+   * 用于覆盖默认的 `flex items-center gap-2`。
+   */
+  containerClassName?: string;
+}
+
+function InputOTP({
+  className,
+  containerClassName,
+  ...props
+}: InputOTPProps & React.ComponentPropsWithoutRef<typeof OTPInput>) {
+  return (
+    <OTPInput
+      containerClassName={cn(
+        'flex items-center gap-2 has-[:disabled]:opacity-50',
+        containerClassName,
+      )}
+      className={cn('disabled:cursor-not-allowed', className)}
+      {...props}
+    />
+  );
+}
+InputOTP.displayName = 'InputOTP';
+
+const InputOTPGroup = React.forwardRef<
+  React.ElementRef<'div'>,
+  React.ComponentPropsWithoutRef<'div'>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn('flex items-center', className)} {...props} />
+));
+InputOTPGroup.displayName = 'InputOTPGroup';
+
+export interface InputOTPSlotProps
+  extends React.ComponentPropsWithoutRef<'div'> {
+  /** Slot 索引(必传)。OTP 的 slots 数组下标。 */
+  index: number;
+}
+
+const InputOTPSlot = React.forwardRef<
+  React.ElementRef<'div'>,
+  InputOTPSlotProps
+>(({ index, className, ...props }, ref) => {
+  const inputOTPContext = React.useContext(OTPInputContext);
+  const slot = inputOTPContext.slots[index];
+  const char = slot?.char;
+  const hasFakeCaret = slot?.hasFakeCaret;
+  const isActive = slot?.isActive;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'relative flex size-10 items-center justify-center border-y border-r border-input text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md',
+        isActive && 'z-10 ring-1 ring-ring',
+        className,
+      )}
+      {...props}
+    >
+      {char}
+      {hasFakeCaret ? (
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+          <div className="h-4 w-px animate-caret-blink bg-foreground duration-1000" />
+        </div>
+      ) : null}
+    </div>
+  );
+});
+InputOTPSlot.displayName = 'InputOTPSlot';
+
+const InputOTPSeparator = React.forwardRef<
+  React.ElementRef<'div'>,
+  React.ComponentPropsWithoutRef<'div'>
+>(({ ...props }, ref) => (
+  <div ref={ref} role="separator" {...props}>
+    <Dot className="size-4" />
+  </div>
+));
+InputOTPSeparator.displayName = 'InputOTPSeparator';
+
+export { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator };