@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,360 @@
+/**
+ * 数字输入框 InputNumber
+ *
+ * 通过步进按钮、键盘或滚轮精确录入数值，支持范围夹紧、精度控制、自定义格式化与反解析。
+ *
+ * @when
+ * - 需要用户输入精确数值时（价格、数量、年龄、占比等）
+ * - 需要范围约束（min/max）与精度（precision）自动订正时
+ * - 需要步进按钮、键盘 ↑↓、滚轮等多种调值方式时
+ * - 需要展示百分号 / 千分位 / 货币等自定义格式时（formatter + parser）
+ * - 需要装饰位（前后缀图标、单位标签）时请改用 [InputGroup](../input-group/index.tsx) 或 [Field](../field/index.tsx)
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ChevronDown, ChevronUp, Minus, Plus } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Variants ───────────────────────────────────────────────────────────────
+
+const inputNumberVariants = cva(
+  [
+    'inline-flex w-full min-w-0 items-stretch overflow-hidden rounded-md border border-input bg-transparent transition-colors',
+    'focus-within:border-ring focus-within:ring-1 focus-within:ring-ring',
+    'has-[input:disabled]:cursor-not-allowed has-[input:disabled]:bg-input/50 has-[input:disabled]:opacity-50',
+    'has-[input[aria-invalid=true]]:border-destructive has-[input[aria-invalid=true]]:ring-1 has-[input[aria-invalid=true]]:ring-destructive/20',
+  ].join(' '),
+  {
+    variants: {
+      size: {
+        sm: 'h-6 text-xs',
+        default: 'h-8 text-xs',
+        lg: 'h-9 text-sm',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+export type InputNumberSize = NonNullable<
+  VariantProps<typeof inputNumberVariants>['size']
+>;
+export type InputNumberVariant = 'default' | 'inline';
+
+// ─── Props ──────────────────────────────────────────────────────────────────
+
+export interface InputNumberProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    | 'onChange'
+    | 'value'
+    | 'defaultValue'
+    | 'min'
+    | 'max'
+    | 'step'
+    | 'type'
+    | 'size'
+  > {
+  /** 形态。`default` 右侧叠加上下箭头；`inline` 两侧加减按钮。 @default default */
+  variant?: InputNumberVariant;
+  /** 尺寸。 @default default */
+  size?: InputNumberSize;
+  /** 受控值。`null` 等价空输入。 */
+  value?: number | string | null;
+  /** 非受控初值。 */
+  defaultValue?: number | string | null;
+  /** 大数/高精度字符串模式。开启后 value/onChange 使用 string。 @default false */
+  stringMode?: boolean;
+  /** 值变化回调，输入清空时传 `null`。 */
+  onChange?: (value: number | string | null) => void;
+  /** 最小值。 */
+  min?: number;
+  /** 最大值。 */
+  max?: number;
+  /** 步长。 @default 1 */
+  step?: number;
+  /** 数值精度（小数位数）。 */
+  precision?: number;
+  /** 是否渲染步进按钮。 @default true */
+  controls?: boolean;
+  /** 是否启用键盘 ↑↓ 步进。 @default true */
+  keyboard?: boolean;
+  /** 是否启用滚轮调整（仅在聚焦时生效）。 @default false */
+  changeOnWheel?: boolean;
+  /** 是否仅在 blur/Enter 时提交 onChange。关闭后输入即触发。 @default true */
+  changeOnBlur?: boolean;
+  /** 只读：可聚焦/复制但不可编辑、不可步进。 */
+  readOnly?: boolean;
+  /** 显示格式化器。返回值用于显示，不影响内部数值。 */
+  formatter?: (value: number | null) => string;
+  /** 输入文本反解析（清洗千分位、单位、百分号等），返回纯数字字符串。 */
+  parser?: (text: string) => string;
+  /** 回车提交回调，会先订正并 commit。 */
+  onPressEnter?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function defaultFormat(raw: number | null, precision?: number): string {
+  if (raw === null || Number.isNaN(raw)) return '';
+  return precision !== undefined ? raw.toFixed(precision) : String(raw);
+}
+
+function defaultParse(raw: string): string {
+  // 保守清洗：保留数字、负号、小数点
+  return raw.replace(/[^\d.\-]/g, '');
+}
+
+function toNumber(v: number | string | null | undefined): number | null {
+  if (v === null || v === undefined || v === '') return null;
+  const n = typeof v === 'string' ? parseFloat(v) : v;
+  return Number.isNaN(n) ? null : n;
+}
+
+// ─── InputNumber ────────────────────────────────────────────────────────────
+
+const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
+  (
+    {
+      variant = 'default',
+      size = 'default',
+      value,
+      defaultValue,
+      stringMode = false,
+      onChange,
+      min,
+      max,
+      step = 1,
+      precision,
+      controls = true,
+      keyboard = true,
+      changeOnWheel = false,
+      changeOnBlur = true,
+      readOnly = false,
+      formatter,
+      parser,
+      disabled,
+      className,
+      onBlur,
+      onKeyDown,
+      onWheel,
+      onPressEnter,
+      ...props
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<number | null>(
+      toNumber(defaultValue),
+    );
+    const current = isControlled ? toNumber(value) : internal;
+    const [editing, setEditing] = React.useState<string | null>(null);
+
+    const display =
+      editing !== null
+        ? editing
+        : formatter
+        ? formatter(current)
+        : defaultFormat(current, precision);
+
+    const clamp = React.useCallback(
+      (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;
+      },
+      [min, max, precision],
+    );
+
+    const commit = React.useCallback(
+      (next: number | null) => {
+        if (!isControlled) setInternal(next);
+        if (stringMode) {
+          onChange?.(next === null ? null : String(next));
+        } else {
+          onChange?.(next);
+        }
+      },
+      [isControlled, stringMode, onChange],
+    );
+
+    const parse = React.useCallback(
+      (raw: string): number | null => {
+        const cleaned = parser ? parser(raw) : defaultParse(raw);
+        if (cleaned === '' || cleaned === '-' || cleaned === '.') return null;
+        const n = Number(cleaned);
+        return Number.isNaN(n) ? null : n;
+      },
+      [parser],
+    );
+
+    const handleInput = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const raw = e.target.value;
+      setEditing(raw);
+      if (!changeOnBlur) {
+        const parsed = parse(raw);
+        if (parsed !== null) commit(clamp(parsed));
+        else if (raw === '') commit(null);
+      }
+    };
+
+    const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+      setEditing(null);
+      const raw = e.target.value;
+      if (raw === '') {
+        commit(null);
+      } else {
+        const parsed = parse(raw);
+        commit(parsed === null ? current : clamp(parsed));
+      }
+      onBlur?.(e);
+    };
+
+    const stepBy = (sign: 1 | -1) => {
+      if (disabled || readOnly) return;
+      const base = current ?? 0;
+      commit(clamp(base + sign * step));
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (keyboard && (e.key === 'ArrowUp' || e.key === 'ArrowDown')) {
+        e.preventDefault();
+        stepBy(e.key === 'ArrowUp' ? 1 : -1);
+      } else if (e.key === 'Enter') {
+        // 回车主动提交：把 editing 解析并订正
+        const raw = e.currentTarget.value;
+        setEditing(null);
+        if (raw === '') {
+          commit(null);
+        } else {
+          const parsed = parse(raw);
+          commit(parsed === null ? current : clamp(parsed));
+        }
+        onPressEnter?.(e);
+      }
+      onKeyDown?.(e);
+    };
+
+    const handleWheel = (e: React.WheelEvent<HTMLInputElement>) => {
+      if (
+        changeOnWheel &&
+        !disabled &&
+        !readOnly &&
+        document.activeElement === e.currentTarget
+      ) {
+        e.preventDefault();
+        stepBy(e.deltaY < 0 ? 1 : -1);
+      }
+      onWheel?.(e);
+    };
+
+    const stepBtnClass =
+      'flex cursor-pointer items-center justify-center text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30 disabled:hover:bg-transparent disabled:hover:text-muted-foreground';
+
+    const upDisabled =
+      disabled ||
+      readOnly ||
+      (typeof max === 'number' && (current ?? -Infinity) >= max);
+    const downDisabled =
+      disabled ||
+      readOnly ||
+      (typeof min === 'number' && (current ?? Infinity) <= min);
+
+    return (
+      <div
+        data-slot="input-number"
+        data-variant={variant}
+        data-size={size}
+        data-disabled={disabled ? '' : undefined}
+        data-readonly={readOnly ? '' : undefined}
+        className={cn(inputNumberVariants({ size }), className)}
+      >
+        {controls && variant === 'inline' ? (
+          <button
+            type="button"
+            tabIndex={-1}
+            disabled={downDisabled}
+            onClick={() => stepBy(-1)}
+            aria-label="减少"
+            data-slot="input-number-decrement"
+            className={cn(stepBtnClass, 'border-r border-input px-2')}
+          >
+            <Minus className="size-3.5" />
+          </button>
+        ) : null}
+        <input
+          ref={ref}
+          type="text"
+          inputMode="decimal"
+          role="spinbutton"
+          aria-valuenow={current ?? undefined}
+          aria-valuemin={min}
+          aria-valuemax={max}
+          aria-readonly={readOnly || undefined}
+          value={display}
+          disabled={disabled}
+          readOnly={readOnly}
+          onChange={handleInput}
+          onBlur={handleBlur}
+          onKeyDown={handleKeyDown}
+          onWheel={handleWheel}
+          data-slot="input-number-control"
+          className={cn(
+            'w-full bg-transparent px-2.5 text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed read-only:cursor-default',
+            variant === 'inline' && 'text-center',
+          )}
+          {...props}
+        />
+        {controls && variant === 'inline' ? (
+          <button
+            type="button"
+            tabIndex={-1}
+            disabled={upDisabled}
+            onClick={() => stepBy(1)}
+            aria-label="增加"
+            data-slot="input-number-increment"
+            className={cn(stepBtnClass, 'border-l border-input px-2')}
+          >
+            <Plus className="size-3.5" />
+          </button>
+        ) : null}
+        {controls && variant === 'default' ? (
+          <div
+            data-slot="input-number-handlers"
+            className="flex flex-col border-l border-input"
+          >
+            <button
+              type="button"
+              tabIndex={-1}
+              disabled={upDisabled}
+              onClick={() => stepBy(1)}
+              aria-label="增加"
+              data-slot="input-number-increment"
+              className={cn(stepBtnClass, 'h-1/2 px-1.5')}
+            >
+              <ChevronUp className="size-3.5" />
+            </button>
+            <button
+              type="button"
+              tabIndex={-1}
+              disabled={downDisabled}
+              onClick={() => stepBy(-1)}
+              aria-label="减少"
+              data-slot="input-number-decrement"
+              className={cn(stepBtnClass, 'h-1/2 border-t border-input px-1.5')}
+            >
+              <ChevronDown className="size-3.5" />
+            </button>
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);
+InputNumber.displayName = 'InputNumber';
+
+export { InputNumber, inputNumberVariants };

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

@@ -0,0 +1,156 @@
+# InputNumber
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+数字输入框 InputNumber
+通过步进按钮、键盘或滚轮精确录入数值，支持范围夹紧、精度控制、自定义格式化与反解析。
+
+## 使用场景
+
+- 需要用户输入精确数值时（价格、数量、年龄、占比等）
+- 需要范围约束（min/max）与精度（precision）自动订正时
+- 需要步进按钮、键盘 ↑↓、滚轮等多种调值方式时
+- 需要展示百分号 / 千分位 / 货币等自定义格式时（formatter + parser）
+- 需要装饰位（前后缀图标、单位标签）时请改用 [InputGroup](../input-group/index.tsx) 或 [Field](../field/index.tsx)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `InputNumberVariant` | `default` | – | 形态。`default` 右侧叠加上下箭头；`inline` 两侧加减按钮。 |
+| `size` | `InputNumberSize` | `default` | – | 尺寸。 |
+| `value` | `number \| string \| null` | – | – | 受控值。`null` 等价空输入。 |
+| `defaultValue` | `number \| string \| null` | – | – | 非受控初值。 |
+| `stringMode` | `boolean` | `false` | – | 大数/高精度字符串模式。开启后 value/onChange 使用 string。 |
+| `onChange` | `(value: number \| string \| null) => void` | – | – | 值变化回调，输入清空时传 `null`。 |
+| `min` | `number` | – | – | 最小值。 |
+| `max` | `number` | – | – | 最大值。 |
+| `step` | `number` | `1` | – | 步长。 |
+| `precision` | `number` | – | – | 数值精度（小数位数）。 |
+| `controls` | `boolean` | `true` | – | 是否渲染步进按钮。 |
+| `keyboard` | `boolean` | `true` | – | 是否启用键盘 ↑↓ 步进。 |
+| `changeOnWheel` | `boolean` | `false` | – | 是否启用滚轮调整（仅在聚焦时生效）。 |
+| `changeOnBlur` | `boolean` | `true` | – | 是否仅在 blur/Enter 时提交 onChange。关闭后输入即触发。 |
+| `readOnly` | `boolean` | – | – | 只读：可聚焦/复制但不可编辑、不可步进。 |
+| `formatter` | `(value: number \| null) => string` | – | – | 显示格式化器。返回值用于显示，不影响内部数值。 |
+| `parser` | `(text: string) => string` | – | – | 输入文本反解析（清洗千分位、单位、百分号等），返回纯数字字符串。 |
+| `onPressEnter` | `(event: React.KeyboardEvent<HTMLInputElement>) => void` | – | – | 回车提交回调，会先订正并 commit。 |
+
+## 示例
+
+### Sizes
+
+通过 `size` 控制尺寸，两种 `variant` 都支持。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-3">
+    <InputNumber size="sm" placeholder="小" className="w-40" />
+    <InputNumber placeholder="中（默认）" className="w-40" />
+    <InputNumber size="lg" placeholder="大" className="w-40" />
+  </div>
+  <div className="flex items-center gap-3">
+    <InputNumber
+      size="sm"
+      variant="inline"
+      defaultValue={3}
+      className="w-32"
+    />
+    <InputNumber variant="inline" defaultValue={3} className="w-32" />
+    <InputNumber
+      size="lg"
+      variant="inline"
+      defaultValue={3}
+      className="w-32"
+    />
+  </div>
+</div>
+```
+
+### MinMax
+
+通过 `min` / `max` 限制输入范围，超出时自动夹紧；步进按钮在边界自动禁用。
+
+```tsx
+<InputNumber min={0} max={100} defaultValue={50} className="w-40" />
+```
+
+### StepPrecision
+
+`step` 控制每次步进增量，`precision` 控制小数位。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <InputNumber
+    step={0.01}
+    precision={2}
+    defaultValue={1.0}
+    className="w-40"
+  />
+  <InputNumber step={5} defaultValue={0} className="w-40" />
+</div>
+```
+
+### Formatter
+
+`formatter` 自定义显示，`parser` 反解析输入文本。可表达百分号、千分位、货币等场景。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <InputNumber
+    defaultValue={85}
+    min={0}
+    max={100}
+    formatter={(v) => (v === null ? '' : `${v}%`)}
+    parser={(t) => t.replace(/%/g, '')}
+    className="w-40"
+  />
+  <InputNumber
+    defaultValue={1234567.89}
+    precision={2}
+    formatter={(v) =>
+      v === null ? '' : new Intl.NumberFormat('en-US').format(v)
+    }
+    parser={(t) => t.replace(/,/g, '')}
+    className="w-48"
+  />
+  <InputNumber
+    defaultValue={2999}
+    formatter={(v) => (v === null ? '' : `¥ ${v}`)}
+    parser={(t) => t.replace(/[^\d.\-]/g, '')}
+    className="w-40"
+  />
+</div>
+```
+
+### Inline
+
+`variant="inline"` 两侧加减按钮，适合紧凑场景。
+
+```tsx
+<InputNumber
+  variant="inline"
+  min={1}
+  max={10}
+  defaultValue={3}
+  className="w-32"
+/>
+```
+
+### NoControls
+
+设置 `controls={false}` 隐藏步进按钮，键盘 ↑↓ 仍可用。
+
+```tsx
+<InputNumber controls={false} placeholder="纯输入" className="w-40" />
+```
+
+### Keyboard
+
+`keyboard={false}` 关闭键盘 ↑↓ 步进。
+
+```tsx
+<InputNumber keyboard={false} defaultValue={0} className="w-40" />
+```

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

@@ -0,0 +1,187 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { InputNumber } from './index';
+
+const meta: Meta<typeof InputNumber> = {
+  title: '数据录入 · Data Entry/InputNumber 数字输入框',
+  component: InputNumber,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => <InputNumber placeholder="请输入数字" className="w-40" />,
+};
+
+/** 通过 `size` 控制尺寸，两种 `variant` 都支持。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-3">
+        <InputNumber size="sm" placeholder="小" className="w-40" />
+        <InputNumber placeholder="中（默认）" className="w-40" />
+        <InputNumber size="lg" placeholder="大" className="w-40" />
+      </div>
+      <div className="flex items-center gap-3">
+        <InputNumber
+          size="sm"
+          variant="inline"
+          defaultValue={3}
+          className="w-32"
+        />
+        <InputNumber variant="inline" defaultValue={3} className="w-32" />
+        <InputNumber
+          size="lg"
+          variant="inline"
+          defaultValue={3}
+          className="w-32"
+        />
+      </div>
+    </div>
+  ),
+};
+
+/** 通过 `min` / `max` 限制输入范围，超出时自动夹紧；步进按钮在边界自动禁用。 */
+export const MinMax: Story = {
+  render: () => (
+    <InputNumber min={0} max={100} defaultValue={50} className="w-40" />
+  ),
+};
+
+/** `step` 控制每次步进增量，`precision` 控制小数位。 */
+export const StepPrecision: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <InputNumber
+        step={0.01}
+        precision={2}
+        defaultValue={1.0}
+        className="w-40"
+      />
+      <InputNumber step={5} defaultValue={0} className="w-40" />
+    </div>
+  ),
+};
+
+/** `formatter` 自定义显示，`parser` 反解析输入文本。可表达百分号、千分位、货币等场景。 */
+export const Formatter: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <InputNumber
+        defaultValue={85}
+        min={0}
+        max={100}
+        formatter={(v) => (v === null ? '' : `${v}%`)}
+        parser={(t) => t.replace(/%/g, '')}
+        className="w-40"
+      />
+      <InputNumber
+        defaultValue={1234567.89}
+        precision={2}
+        formatter={(v) =>
+          v === null ? '' : new Intl.NumberFormat('en-US').format(v)
+        }
+        parser={(t) => t.replace(/,/g, '')}
+        className="w-48"
+      />
+      <InputNumber
+        defaultValue={2999}
+        formatter={(v) => (v === null ? '' : `¥ ${v}`)}
+        parser={(t) => t.replace(/[^\d.\-]/g, '')}
+        className="w-40"
+      />
+    </div>
+  ),
+};
+
+/** `readOnly` 只读：可聚焦/复制但不可编辑、不可步进。 */
+export const ReadOnly: Story = {
+  render: () => <InputNumber readOnly defaultValue={42} className="w-40" />,
+};
+
+/** `variant="inline"` 两侧加减按钮，适合紧凑场景。 */
+export const Inline: Story = {
+  render: () => (
+    <InputNumber
+      variant="inline"
+      min={1}
+      max={10}
+      defaultValue={3}
+      className="w-32"
+    />
+  ),
+};
+
+/** 设置 `controls={false}` 隐藏步进按钮，键盘 ↑↓ 仍可用。 */
+export const NoControls: Story = {
+  render: () => (
+    <InputNumber controls={false} placeholder="纯输入" className="w-40" />
+  ),
+};
+
+/** `changeOnBlur={false}` 让 onChange 在每次有效输入时触发，否则仅 blur/Enter 提交。 */
+export const ChangeOnBlur: Story = {
+  render: function ChangeOnBlurDemo() {
+    const [a, setA] = useState<number | string | null>(0);
+    const [b, setB] = useState<number | string | null>(0);
+    return (
+      <div className="flex flex-col gap-3 text-xs">
+        <div className="flex items-center gap-3">
+          <InputNumber value={a} onChange={setA} className="w-40" />
+          <span className="text-muted-foreground">
+            默认（仅 blur/Enter 触发）：{String(a)}
+          </span>
+        </div>
+        <div className="flex items-center gap-3">
+          <InputNumber
+            value={b}
+            onChange={setB}
+            changeOnBlur={false}
+            className="w-40"
+          />
+          <span className="text-muted-foreground">实时触发：{String(b)}</span>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** `changeOnWheel` 启用滚轮调整（仅在聚焦时生效，默认关闭防误触）。 */
+export const ChangeOnWheel: Story = {
+  render: () => <InputNumber changeOnWheel defaultValue={0} className="w-40" />,
+};
+
+/** `keyboard={false}` 关闭键盘 ↑↓ 步进。 */
+export const Keyboard: Story = {
+  render: () => (
+    <InputNumber keyboard={false} defaultValue={0} className="w-40" />
+  ),
+};
+
+/** `aria-invalid` 视觉与 Input 一致。 */
+export const Invalid: Story = {
+  render: () => <InputNumber aria-invalid defaultValue={42} className="w-40" />,
+};
+
+/** 禁用状态。 */
+export const Disabled: Story = {
+  render: () => <InputNumber disabled defaultValue={42} className="w-40" />,
+};
+
+/** 受控模式。 */
+export const Controlled: Story = {
+  render: function ControlledDemo() {
+    const [val, setVal] = useState<number | string | null>(10);
+    return (
+      <div className="flex items-center gap-3">
+        <InputNumber value={val} onChange={setVal} className="w-40" />
+        <span className="text-xs text-muted-foreground">值: {String(val)}</span>
+      </div>
+    );
+  },
+};