@teamix-evo/ui 0.2.0 → 0.3.0

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

@@ -1,22 +1,27 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { Mail, Search } from 'lucide-react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Search } from 'lucide-react';
 import { Input } from './input';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@/components/input-group/input-group';
 
 const meta: Meta<typeof Input> = {
-  title: '表单与输入 · Form/Input',
+  title: '数据录入 · Data Entry/Input',
   component: Input,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '输入框 — 文本 / 邮箱 / 密码 / 搜索等单行输入。shadcn 原生 `<input>` 风格 + antd 扩展：`size` 三档、`prefix` / `suffix` 前后缀、`addonBefore` / `addonAfter` 外联组、`clearable` 一键清空、`showCount` + `maxLength` 字数统计。',
+          '输入框 — shadcn 简洁基底 + antd 并集中保留为内建逻辑能力的:`size` 三档(sm/md/lg,与 `Button` 同档)、`clearable` 一键清空、`showCount` + `maxLength` 字数统计、`error` / `aria-invalid` 错误态。**前后缀 / 单位 / 协议头 / 内嵌按钮**等"装饰类"形态请用同库 `InputGroup` 复合插槽(见下方 `WithInputGroup` 示例)— 单一职责更清晰,与 shadcn 2025-10 拆分对齐(ADR 0029)。',
       },
     },
   },
   argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
     type: {
       control: 'select',
       options: ['text', 'email', 'password', 'search', 'tel', 'url'],
@@ -24,15 +29,17 @@ const meta: Meta<typeof Input> = {
     clearable: { control: 'boolean' },
     showCount: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
     placeholder: { control: 'text' },
     maxLength: { control: 'number' },
   },
   args: {
-    size: 'default',
+    size: 'md',
     type: 'text',
     clearable: false,
     showCount: false,
     disabled: false,
+    error: false,
     placeholder: '请输入...',
   },
   decorators: [
@@ -53,35 +60,9 @@ export const Sizes: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex flex-col gap-3">
-      <Input size="sm" placeholder="Small" />
-      <Input size="default" placeholder="Default" />
-      <Input size="lg" placeholder="Large" />
-    </div>
-  ),
-};
-
-export const PrefixSuffix: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Input prefix={<Search />} placeholder="搜索..." />
-      <Input type="email" suffix={<Mail />} placeholder="you@example.com" />
-      <Input prefix="¥" suffix="USD" placeholder="0.00" />
-    </div>
-  ),
-};
-
-export const Addon: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Input
-        addonBefore="https://"
-        defaultValue="teamix-evo"
-        addonAfter=".com"
-      />
-      <Input addonBefore="@" placeholder="username" />
-      <Input addonAfter="kg" defaultValue="42" />
+      <Input size="sm" placeholder="Small (h-6 / text-xs / 24px)" />
+      <Input size="md" placeholder="Medium (h-8 / text-xs / 32px)" />
+      <Input size="lg" placeholder="Large (h-9 / text-sm / 36px)" />
     </div>
   ),
 };
@@ -106,6 +87,16 @@ export const ShowCount: Story = {
   render: () => <Input showCount maxLength={140} placeholder="发布动态" />,
 };
 
+export const Error: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Input error placeholder="必填" />
+      <Input error defaultValue="非法值" />
+    </div>
+  ),
+};
+
 export const Disabled: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -115,3 +106,39 @@ export const Disabled: Story = {
     </div>
   ),
 };
+
+/**
+ * 想加图标 / 单位 / 协议头?用 `InputGroup` 复合插槽 — 不再用已废弃的
+ * `prefix` / `suffix` / `addonBefore` / `addonAfter` 快捷 prop(ADR 0029)。
+ *
+ * 详细演示与 API 见 `数据录入 · Data Entry/InputGroup` 故事集。
+ */
+export const WithInputGroup: Story = {
+  name: '配合 InputGroup(替代旧 prefix/suffix/addon)',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-80 flex-col gap-3">
+      {/* 图标前缀(替代旧 prefix={<Search />}) */}
+      <InputGroup>
+        <InputGroupAddon position="before" variant="icon">
+          <Search className="size-4" />
+        </InputGroupAddon>
+        <InputGroupInput placeholder="搜索..." />
+      </InputGroup>
+
+      {/* URL 协议头/后缀(替代旧 addonBefore="https://" addonAfter=".com") */}
+      <InputGroup>
+        <InputGroupAddon position="before">https://</InputGroupAddon>
+        <InputGroupInput defaultValue="example" />
+        <InputGroupAddon position="after">.com</InputGroupAddon>
+      </InputGroup>
+
+      {/* 金额/单位(替代旧 prefix="¥" suffix="USD") */}
+      <InputGroup>
+        <InputGroupAddon position="before">¥</InputGroupAddon>
+        <InputGroupInput type="number" defaultValue={199} />
+        <InputGroupAddon position="after">/ 月</InputGroupAddon>
+      </InputGroup>
+    </div>
+  ),
+};

package/src/components/input/input.tsx

@@ -1,19 +1,58 @@
 import * as React from 'react';
+import { cva } from 'class-variance-authority';
 import { X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
+// ─── shared sizing(对齐 Button 三档:24 / 32 / 36px) ────────────────────────
+//
+// 高度 24/32/36px 与 Button / Select 同档;
+// 这里直接用对应的 Tailwind 高度刻度 `h-6 / h-8 / h-9`,字号档位与 Button 同步。
+const SIZE_TO_HEIGHT = {
+  sm: 'h-6 text-xs',
+  // medium 字号对齐 cd hybridcloud --form-element-medium-font-size: 12px (ADR 0027)
+  md: 'h-8 text-xs',
+  lg: 'h-9 text-sm',
+  /** @deprecated 兼容旧调用,等价于 `md`。 */
+  default: 'h-8 text-xs',
+} as const;
+
+/**
+ * Input 主体(无 affix 时直接使用此变体)。
+ * 高度 `h-6 / h-8 / h-9`(24 / 32 / 36px,与 Button / Select 同档);
+ * 圆角走 Tailwind v4 标准 namespace `--radius-md`(uni-manager 2px / opentrek 6px),
+ * 与 Button 同档 — 同行混排时视觉自动对齐。
+ *
+ * **前后缀 / addon 不再内置** — 需要前后缀图标 / 文本 / 按钮请用同库 `InputGroup`
+ * + `InputGroupAddon` + `InputGroupInput` 复合 API(自由嵌套 icon / button / text)。
+ * 字符计数 `showCount` + 一键清空 `clearable` 仍保留为 Input 的内建逻辑能力。
+ */
+const inputVariants = cva(
+  'flex w-full rounded-md border border-input bg-background px-3 py-1 shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive',
+  {
+    variants: { size: SIZE_TO_HEIGHT },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+/**
+ * Input 包壳容器(`clearable` 启用时承载 border + ring,把内部 input 的边框转移到外层)。
+ */
+const inputWrapperVariants = cva(
+  'flex w-full items-center gap-2 rounded-md border border-input bg-background px-3 shadow-sm transition-colors focus-within:ring-1 focus-within:ring-ring aria-invalid:border-destructive aria-invalid:focus-within:ring-destructive',
+  {
+    variants: { size: SIZE_TO_HEIGHT },
+    defaultVariants: { size: 'md' },
+  },
+);
+
 export interface InputProps
-  extends Omit<
-    React.InputHTMLAttributes<HTMLInputElement>,
-    'size' | 'prefix' | 'suffix'
-  > {
-  /** 输入框前置图标 / 文本(antd `prefix` 并集)。 */
-  prefix?: React.ReactNode;
-  /** 输入框后置图标 / 文本(antd `suffix` 并集)。 */
-  suffix?: React.ReactNode;
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'prefix'> {
   /**
    * 显示清除按钮,有内容时点击清空(antd `allowClear` 并集)。
+   *
+   * 注:仅"快捷一键清空"逻辑保留为 Input 内建能力 — 复合的前后缀(图标 / 文本 / 按钮)
+   * 请用 `InputGroup` 系列。
    * @default false
    */
   clearable?: boolean;
@@ -22,38 +61,58 @@ export interface InputProps
    * @default false
    */
   showCount?: boolean;
-  /** 输入框前置标签(antd `addonBefore` 并集),与外层组合形成 input-group。 */
-  addonBefore?: React.ReactNode;
-  /** 输入框后置标签(antd `addonAfter` 并集)。 */
-  addonAfter?: React.ReactNode;
   /**
-   * 尺寸。
-   * @default "default"
+   * 尺寸三档,与 `Button` 同档:`sm`(24px) / `md`(32px,默认) / `lg`(36px)。
+   * `"default"` 为兼容旧调用的别名,等价于 `"md"`,新代码请用 `"md"`。
+   * @default "md"
+   */
+  size?: 'sm' | 'md' | 'lg' | 'default';
+  /**
+   * 错误态(快捷开关),会同时设置 `aria-invalid`,渲染 destructive 边框 / ring。
+   * 也可以直接传 `aria-invalid` 原生属性达到同效果。
+   * @default false
    */
-  size?: 'sm' | 'default' | 'lg';
+  error?: boolean;
   /** 受控值,用于 clearable / showCount 的逻辑;未传时回退到 uncontrolled 行为。 */
   value?: string;
   /** uncontrolled 初始值。 */
   defaultValue?: string;
 }
 
+/**
+ * Input 单行文本输入 — shadcn 简洁基底 + antd `clearable` / `showCount` / `size` / `error` 并集。
+ *
+ * **想加图标 / 单位 / 按钮 / 协议头?用 InputGroup 复合插槽:**
+ * ```tsx
+ * import { InputGroup, InputGroupAddon, InputGroupInput } from '@/components/input-group/input-group';
+ * // 搜索图标 + 输入
+ * <InputGroup>
+ *   <InputGroupAddon position="before" variant="icon"><Search /></InputGroupAddon>
+ *   <InputGroupInput placeholder="搜索..." />
+ * </InputGroup>
+ * // URL(text 前后缀)
+ * <InputGroup>
+ *   <InputGroupAddon position="before">https://</InputGroupAddon>
+ *   <InputGroupInput defaultValue="example" />
+ *   <InputGroupAddon position="after">.com</InputGroupAddon>
+ * </InputGroup>
+ * ```
+ */
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
   (
     {
       className,
       type = 'text',
-      prefix,
-      suffix,
       clearable = false,
       showCount = false,
-      addonBefore,
-      addonAfter,
-      size = 'default',
+      size = 'md',
+      error = false,
       value,
       defaultValue,
       onChange,
       maxLength,
       disabled,
+      'aria-invalid': ariaInvalidProp,
       ...props
     },
     ref,
@@ -67,15 +126,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
     const innerRef = React.useRef<HTMLInputElement | null>(null);
     React.useImperativeHandle(ref, () => innerRef.current as HTMLInputElement);
 
-    const h =
-      size === 'sm'
-        ? 'h-8 text-xs'
-        : size === 'lg'
-        ? 'h-10 text-base'
-        : 'h-9 text-sm';
-
-    const hasAffix = prefix != null || suffix != null || clearable;
-    const hasAddon = addonBefore != null || addonAfter != null;
+    const ariaInvalid = ariaInvalidProp ?? (error ? true : undefined);
 
     const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
       if (!isControlled) setInternal(e.target.value);
@@ -84,7 +135,6 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
 
     const handleClear = () => {
       if (!isControlled) setInternal('');
-      // Synthetic event for callers wiring onChange to a setter
       const target = innerRef.current;
       if (target) {
         const proto = Object.getPrototypeOf(target);
@@ -94,26 +144,18 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
       }
     };
 
-    // Inner input + (optional) prefix/suffix wrapper
-    // 当存在 addon 时，外层 addonWrapper 持有 border + rounded + focus-within ring，
-    // 内层 wrapper / input 完全去掉自身的 border / shadow / ring，避免出现
-    // "内部输入框单独一圈黑框" 的视觉。
-    const innerInput = hasAffix ? (
+    const showClearBtn =
+      clearable && current && current.length > 0 && !disabled;
+
+    const innerInput = clearable ? (
       <div
+        aria-invalid={ariaInvalid}
         className={cn(
-          'flex items-center gap-2 rounded-md border border-input bg-background px-3 shadow-sm transition-colors focus-within:ring-1 focus-within:ring-ring',
-          h,
+          inputWrapperVariants({ size }),
           disabled && 'cursor-not-allowed opacity-50',
-          hasAddon &&
-            'min-w-0 flex-1 rounded-none border-0 shadow-none transition-none focus-within:ring-0',
-          !hasAddon && className,
+          className,
         )}
       >
-        {prefix ? (
-          <span className="flex shrink-0 items-center text-muted-foreground [&_svg]:size-4">
-            {prefix}
-          </span>
-        ) : null}
         <input
           ref={innerRef}
           type={type}
@@ -121,25 +163,21 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
           defaultValue={!isControlled ? defaultValue : undefined}
           maxLength={maxLength}
           disabled={disabled}
+          aria-invalid={ariaInvalid}
           onChange={handleChange}
           className="grow bg-transparent outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed"
           {...props}
         />
-        {clearable && current && current.length > 0 && !disabled ? (
+        {showClearBtn ? (
           <button
             type="button"
             onClick={handleClear}
             aria-label="Clear"
-            className="shrink-0 rounded-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            className="shrink-0 cursor-pointer rounded-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
           >
             <X className="size-4" />
           </button>
         ) : null}
-        {suffix ? (
-          <span className="flex shrink-0 items-center text-muted-foreground [&_svg]:size-4">
-            {suffix}
-          </span>
-        ) : null}
       </div>
     ) : (
       <input
@@ -149,69 +187,26 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
         defaultValue={!isControlled ? defaultValue : undefined}
         maxLength={maxLength}
         disabled={disabled}
+        aria-invalid={ariaInvalid}
         onChange={handleChange}
-        className={cn(
-          'flex w-full rounded-md border border-input bg-background px-3 py-1 shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
-          h,
-          hasAddon &&
-            'min-w-0 flex-1 rounded-none border-0 shadow-none transition-none focus-visible:ring-0',
-          !hasAddon && className,
-        )}
+        className={cn(inputVariants({ size }), className)}
         {...props}
       />
     );
 
-    // Wrap with addons if any.
-    // addonWrapper 是带 addon 时的统一外壳：持有 border + rounded + shadow +
-    // focus-within ring；addon 自身只用浅灰分隔边 (border-input)，input 主体
-    // 不再持有任何边框 / ring，避免内部 "双重黑框" 视觉。
-    const addonWrapper = hasAddon ? (
-      <div
-        className={cn(
-          'flex w-full overflow-hidden rounded-md border border-input bg-background shadow-sm transition-colors focus-within:ring-1 focus-within:ring-ring',
-          disabled && 'cursor-not-allowed opacity-50',
-          className,
-        )}
-      >
-        {addonBefore ? (
-          <span
-            className={cn(
-              'inline-flex shrink-0 items-center border-r border-input bg-muted px-3 text-muted-foreground',
-              h,
-            )}
-          >
-            {addonBefore}
-          </span>
-        ) : null}
-        {innerInput}
-        {addonAfter ? (
-          <span
-            className={cn(
-              'inline-flex shrink-0 items-center border-l border-input bg-muted px-3 text-muted-foreground',
-              h,
-            )}
-          >
-            {addonAfter}
-          </span>
-        ) : null}
-      </div>
-    ) : (
-      innerInput
-    );
-
     if (showCount && maxLength) {
       return (
-        <div className="space-y-1">
-          {addonWrapper}
+        <div className="flex flex-col gap-1">
+          {innerInput}
           <div className="text-right text-xs text-muted-foreground tabular-nums">
             {current?.length ?? 0} / {maxLength}
           </div>
         </div>
       );
     }
-    return addonWrapper;
+    return innerInput;
   },
 );
 Input.displayName = 'Input';
 
-export { Input };
+export { Input, inputVariants };

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

@@ -2,73 +2,69 @@
 id: input-group
 name: InputGroup
 type: component
-category: form
-since: 0.1.0
+category: data-entry
+since: 0.2.0
 package: '@teamix-evo/ui'
 displayName: 输入框组
 ---
 
 # InputGroup 输入框组
 
-输入框 + addon 统一容器 — shadcn 2025-10 新增。**等价 antd `Input` 的 `prefix` / `suffix` / `addonBefore` / `addonAfter` 集合**,但拆为更通用的复合插槽:`InputGroupAddon`(图标 / 文本 / 按钮)+ `InputGroupInput` / `InputGroupTextarea`(主体)。
+输入框 + addon 统一容器 — **shadcn 2025-10 新增**。等价 antd `Input` 的 `prefix` / `suffix` / `addonBefore` / `addonAfter` 集合,**单独一个 entry**,与 [`Input`](../input/input.meta.md) 拆开管理(对齐 shadcn 2025-10 拆分粒度)。
+
+复合插槽:`<InputGroupAddon position variant>` + `<InputGroupInput>` / `<InputGroupTextarea>`,自由嵌套图标 / 按钮 / 文本(URL / 金额 / 搜索 / Send 等形态)。容器外壳承担 border + ring + focus-within,内部全部去边框 — 与 Input / Button / Select 同档高度(32px)。
 
 ## When to use
 
-- 输入框需要前 / 后缀(`https://` `.com`、`$`、`/月`)
-- 输入框 + 操作按钮(搜索、清空、复制)
-- 输入框 + 图标(搜索图标、loading spinner)
-- Textarea + 上传 / 录音类辅助按钮
+- 输入框需要**前 / 后缀**(`https://` `.com`、`¥`、`/ 月`)
+- 输入框 + 操作按钮(搜索、清空、复制、Send)
+- 输入框 + 图标(搜索、loading spinner、状态指示)
+- Textarea + 上传 / 录音 / 发送类辅助按钮
 
 ## When NOT to use
 
-- 仅需输入框 → `Input`
-- 仅需 textarea → `Textarea`
-- 多个按钮拼接 → `ButtonGroup`
+- 仅"一键清空" → `Input` 自带 `clearable`,无需 InputGroup 包裹
+- 字符计数 → `Input` 自带 `showCount` + `maxLength`
+- @提及输入 → `Mentions`
+- 多个**独立**输入框横排(姓 / 名 / 中间名)→ 用 `Flex` 直接 gap 排列,不要套 InputGroup(InputGroup 的"统一外壳"语义不适用)
 
 ## Props
 
-<!-- auto:props:begin -->
-
-#### InputGroup
-
-| 名称       | 类型      | 默认值 | 必填 | 说明                                                                  |
-| ---------- | --------- | ------ | ---- | --------------------------------------------------------------------- |
-| `disabled` | `boolean` | –      | –    | 整组禁用样式（子项请单独传 `disabled`，这里仅影响视觉上的 opacity）。 |
-
-#### InputGroupAddon
-
-| 名称       | 类型                           | 默认值     | 必填 | 说明                                                                                                             |
-| ---------- | ------------------------------ | ---------- | ---- | ---------------------------------------------------------------------------------------------------------------- |
-| `position` | `'before' \| 'after'`          | `"before"` | –    | 位于输入框的哪一侧。                                                                                             |
-| `variant`  | `'text' \| 'icon' \| 'button'` | `"text"`   | –    | `text` = 默认 muted 文本背景 / `icon` = 紧凑、透明背景（图标专用）/ `button` = 用于嵌入 `<Button>`（去内边距）。 |
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | – | – | 整组禁用样式(子项请单独传 `disabled`,这里仅影响视觉上的 opacity)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
-<!-- auto:deps:begin -->
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
+<!-- auto:deps:begin -->
 ### 同库依赖
 
 > `teamix-evo ui add input-group` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
-- **顺序按 JSX 写**:`<InputGroup>` 内的子节点顺序就是渲染顺序 — `<Addon position="before" />` 必须在 `<Input />` 前面,反之亦然
-- **不要在 InputGroupAddon 里再放 Input** — addon 是辅助槽,主输入必须用 `InputGroupInput` / `InputGroupTextarea`
+- **顺序按 JSX 写**:`<InputGroup>` 内的子节点顺序就是渲染顺序 —— `<InputGroupAddon position="before" />` 必须在主体前
+- **不要在 `InputGroupAddon` 里再放 Input** —— addon 是辅助槽,主输入必须用 `InputGroupInput` / `InputGroupTextarea`
 - **`variant="icon"`** 给图标用(无背景、紧凑);**`variant="text"`** 给纯文本前后缀(muted 背景);**`variant="button"`** 给嵌入 Button(去内边距 + 去圆角,避免双重边线)
-- **disabled**:整组传 `disabled` 仅影响外观;子项的真实 disabled 需要单独传(防止误整组禁用)
-- **嵌入 `Button`**:用 `<InputGroupAddon variant="button">` 包,Button 自身 `variant="ghost"` 效果最自然
+- **嵌入 `Button`**:用 `<InputGroupAddon variant="button">` 包,Button 自身 `variant="ghost"` 或 `size="icon"` 效果最自然
+- **不要套两层** —— `<InputGroup>` 内不要再嵌 `<Input>`(主输入用 `<InputGroupInput>`,因为 Input 自带 border 会与外壳冲突 1px 几何)
+- **error 态走子项 `aria-invalid`** —— InputGroup 不直接支持 `error` prop,把 `aria-invalid` 写在 `InputGroupInput` 上即可触发外壳的 destructive 边框
+- **不要硬编码颜色** —— `bg-background` / `border-input` / `bg-muted` 都是 design token
 
 ## Examples
 
@@ -82,29 +78,47 @@ import {
 import { Button } from '@/components/ui/button';
 import { Search, Send } from 'lucide-react';
 
-// 前缀图标 + 后缀按钮
+// 搜索图标 + 输入(替代旧 <Input prefix={<Search />} />)
 <InputGroup>
   <InputGroupAddon position="before" variant="icon">
     <Search className="size-4" />
   </InputGroupAddon>
   <InputGroupInput placeholder="搜索文档..." />
-  <InputGroupAddon position="after" variant="button">
-    <Button variant="ghost" size="sm">搜索</Button>
-  </InputGroupAddon>
 </InputGroup>
 
-// 前后缀文本(URL 输入)
+// URL 输入(替代旧 <Input addonBefore="https://" addonAfter=".com" />)
 <InputGroup>
   <InputGroupAddon position="before">https://</InputGroupAddon>
   <InputGroupInput defaultValue="example" />
   <InputGroupAddon position="after">.com</InputGroupAddon>
 </InputGroup>
 
-// Textarea + 发送按钮
+// 金额输入
 <InputGroup>
+  <InputGroupAddon position="before">¥</InputGroupAddon>
+  <InputGroupInput type="number" defaultValue={199} />
+  <InputGroupAddon position="after">/ 月</InputGroupAddon>
+</InputGroup>
+
+// Textarea + 发送按钮
+<InputGroup className="items-end">
   <InputGroupTextarea rows={3} placeholder="发表评论..." />
   <InputGroupAddon position="after" variant="button">
     <Button size="icon" icon={<Send />} aria-label="发送" />
   </InputGroupAddon>
 </InputGroup>
 ```
+
+## Migration · 从旧 `Input` 快捷 prop 迁移
+
+> v0.2 起 `<Input>` 的 `prefix` / `suffix` / `addonBefore` / `addonAfter` 已**移除**。请改用 InputGroup 复合 API(更灵活、可嵌任意子节点)。
+
+| 旧用法(已移除)                      | 新用法                                                                                                                                                      |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Input prefix={<Search />} />`     | `<InputGroup><InputGroupAddon position="before" variant="icon"><Search /></InputGroupAddon><InputGroupInput /></InputGroup>`                                |
+| `<Input suffix={<Mail />} />`       | `<InputGroup><InputGroupInput /><InputGroupAddon position="after" variant="icon"><Mail /></InputGroupAddon></InputGroup>`                                   |
+| `<Input addonBefore="https://" />`  | `<InputGroup><InputGroupAddon position="before">https://</InputGroupAddon><InputGroupInput /></InputGroup>`                                                 |
+| `<Input addonAfter=".com" />`       | `<InputGroup><InputGroupInput /><InputGroupAddon position="after">.com</InputGroupAddon></InputGroup>`                                                      |
+| `<Input prefix="¥" suffix="USD" />` | `<InputGroup><InputGroupAddon position="before">¥</InputGroupAddon><InputGroupInput /><InputGroupAddon position="after">USD</InputGroupAddon></InputGroup>` |
+
+> 保留在 Input 的快捷能力:`clearable`(逻辑) / `showCount`(下方计数)/ `size` / `error` —— 这些与"前后缀"语义无关,继续作为 Input 的内建逻辑能力。