@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/input/index.tsx

@@ -0,0 +1,63 @@
+/**
+ * 输入框 Input
+ *
+ * 通过键盘输入内容，是最基础的表单域包装。
+ *
+ * @when
+ * - 需要用户输入单行文本时（用户名、搜索关键词、URL 等）
+ * - 需要配合表单进行数据收集时
+ * - 需要前后缀装饰 / 清除按钮 / 密码切换 / 字符计数等复合形态时，请改用 [InputGroup](../input-group/index.tsx)
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+
+// ─── Input cva ──────────────────────────────────────────────────────────────
+
+const inputVariants = cva(
+  'w-full min-w-0 cursor-text rounded-md border border-input bg-transparent font-normal transition-colors outline-none file:inline-flex file:cursor-pointer file:border-0 file:bg-transparent file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20',
+  {
+    variants: {
+      size: {
+        sm: 'h-6 px-2 text-xs file:h-4 file:text-xs',
+        default: 'h-8 px-2.5 text-xs file:h-6 file:text-xs',
+        lg: 'h-9 px-3 text-sm file:h-7 file:text-sm',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+    },
+  },
+);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type InputSize = 'sm' | 'default' | 'lg';
+
+export interface InputProps
+  extends Omit<React.ComponentProps<'input'>, 'size'>,
+    VariantProps<typeof inputVariants> {
+  /** 尺寸。 @default default */
+  size?: InputSize;
+}
+
+// ─── Input ──────────────────────────────────────────────────────────────────
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, size, ...props }, ref) => {
+    return (
+      <input
+        ref={ref}
+        type={type}
+        data-slot="input"
+        className={cn(inputVariants({ size, className }))}
+        {...props}
+      />
+    );
+  },
+);
+Input.displayName = 'Input';
+
+export { Input, inputVariants };

package/src/components/input/meta.md

@@ -0,0 +1,57 @@
+# Input
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+输入框 Input
+通过键盘输入内容，是最基础的表单域包装。
+
+## 使用场景
+
+- 需要用户输入单行文本时（用户名、搜索关键词、URL 等）
+- 需要配合表单进行数据收集时
+- 需要前后缀装饰 / 清除按钮 / 密码切换 / 字符计数等复合形态时，请改用 [InputGroup](../input-group/index.tsx)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `InputSize` | `default` | – | 尺寸。 |
+
+## 示例
+
+### Sizes
+
+可以通过设置 `size` 属性控制输入框的尺寸，可选值为 `sm` `default` `lg`。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Input size="sm" placeholder="小 Small 24px" />
+  <Input placeholder="中 Default 32px" />
+  <Input size="lg" placeholder="大 Large 36px" />
+</div>
+```
+
+### Disabled
+
+添加 `disabled` 属性即可让输入框处于不可用状态。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Input placeholder="不可编辑" disabled />
+  <Input placeholder="不可编辑" disabled value="已填内容" />
+</div>
+```
+
+### Widths
+
+Input 默认宽度为 100%，可通过 `className` 控制宽度。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Input className="w-48" placeholder="w-48" />
+  <Input className="w-64" placeholder="w-64" />
+  <Input className="w-full" placeholder="w-full (默认)" />
+</div>
+```

package/src/components/input/stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Input } from './index';
+
+const meta: Meta<typeof Input> = {
+  title: '数据录入 · Data Entry/Input 输入框',
+  component: Input,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '极薄的原生 `<input>` 包装：仅提供 size 三档与 aria-invalid 错误态。需要前后缀图标 / 清除按钮 / 密码切换 / 字符计数等复合形态时，请改用 [InputGroup](/docs/数据录入-·-data-entry-inputgroup-输入框组合--docs)。',
+      },
+      source: { type: 'dynamic' },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { placeholder: '请输入内容' },
+};
+
+/** 可以通过设置 `size` 属性控制输入框的尺寸，可选值为 `sm` `default` `lg`。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Input size="sm" placeholder="小 Small 24px" />
+      <Input placeholder="中 Default 32px" />
+      <Input size="lg" placeholder="大 Large 36px" />
+    </div>
+  ),
+};
+
+/** 添加 `disabled` 属性即可让输入框处于不可用状态。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Input placeholder="不可编辑" disabled />
+      <Input placeholder="不可编辑" disabled value="已填内容" />
+    </div>
+  ),
+};
+
+/** 通过 `aria-invalid` 属性标记错误状态，通常用于表单校验失败时。 */
+export const Invalid: Story = {
+  render: () => <Input placeholder="请输入邮箱" aria-invalid="true" />,
+};
+
+/** Input 默认宽度为 100%，可通过 `className` 控制宽度。 */
+export const Widths: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Input className="w-48" placeholder="w-48" />
+      <Input className="w-64" placeholder="w-64" />
+      <Input className="w-full" placeholder="w-full (默认)" />
+    </div>
+  ),
+};
+
+/** `readOnly` 属性让输入框只读，用户可复制但无法编辑。 */
+export const ReadOnly: Story = {
+  render: () => <Input readOnly value="只读内容，可复制" />,
+};

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

@@ -0,0 +1,292 @@
+/**
+ * 输入组 InputGroup
+ *
+ * 将输入框与前后缀装饰（图标、按钮、文字）组合为一个视觉整体。
+ *
+ * @when
+ * - 需要为输入框添加前后缀图标或文字时（搜索图标、金额单位）
+ * - 需要在输入框内嵌入按钮时（密码可见切换、清除）
+ * - 需要文本字符计数 / 越界提示时（InputGroupShowCount）
+ * - Input 单独使用无法满足复合布局需求时
+ *
+ * 组合结构：InputGroup > InputGroupAddon + (InputGroupInput | InputGroupTextarea)
+ * helper 原子：InputGroupClear / InputGroupPasswordToggle / InputGroupShowCount
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { EyeIcon, EyeOffIcon, XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+import { Input, type InputProps } from '@/components/input';
+import { Textarea } from '@/components/textarea';
+
+const InputGroup = React.forwardRef<
+  HTMLDivElement,
+  React.ComponentProps<'div'>
+>(({ className, ...props }, ref) => {
+  return (
+    <div
+      ref={ref}
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        'group/input-group relative flex h-8 w-full min-w-0 items-center rounded-md border border-input transition-colors outline-none has-disabled:bg-input/50 has-disabled:opacity-50 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-1 has-[[data-slot=input-group-control]:focus-visible]:ring-ring has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-1 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+InputGroup.displayName = 'InputGroup';
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-xs font-normal text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-sm [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        'inline-start':
+          'order-first pl-2 has-[>button]:-ml-1 has-[>kbd]:-ml-0.5',
+        'inline-end': 'order-last pr-2 has-[>button]:-mr-1 has-[>kbd]:-mr-0.5',
+        'block-start':
+          'order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2',
+        'block-end':
+          'order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2',
+      },
+    },
+    defaultVariants: {
+      align: 'inline-start',
+    },
+  },
+);
+
+function InputGroupAddon({
+  className,
+  align = 'inline-start',
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest('button')) {
+          return;
+        }
+        e.currentTarget.parentElement?.querySelector('input')?.focus();
+      }}
+      {...props}
+    />
+  );
+}
+
+const inputGroupButtonVariants = cva(
+  'flex items-center gap-2 text-sm shadow-none',
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-sm px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: '',
+        'icon-xs': 'size-6 rounded-sm p-0 has-[>svg]:p-0',
+        'icon-sm': 'size-8 p-0 has-[>svg]:p-0',
+      },
+    },
+    defaultVariants: {
+      size: 'xs',
+    },
+  },
+);
+
+function InputGroupButton({
+  className,
+  type = 'button',
+  variant = 'ghost',
+  size = 'xs',
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, 'size'> &
+  VariantProps<typeof inputGroupButtonVariants>) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  );
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-xs font-normal text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function InputGroupInput({ className, ...props }: InputProps) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        'flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<'textarea'>) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        'flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── InputGroupClear ──────────────────────────────────────────────────────────────
+
+export interface InputGroupClearProps
+  extends Omit<
+    React.ComponentProps<typeof InputGroupButton>,
+    'children' | 'aria-label'
+  > {
+  /** 是否显示。受控用法下一般绑定 `value.length > 0`。 @default true */
+  visible?: boolean;
+  /** 无障碍 label。 @default '清除' */
+  'aria-label'?: string;
+}
+
+/**
+ * `InputGroupClear` 清除按钮，默认右侧插槽。
+ * 在 `<InputGroupAddon align="inline-end">` 中使用；onClick 由外部控制 value 清零。
+ */
+function InputGroupClear({
+  visible = true,
+  className,
+  'aria-label': ariaLabel = '清除',
+  ...props
+}: InputGroupClearProps) {
+  if (!visible) return null;
+  return (
+    <InputGroupButton
+      data-slot="input-group-clear"
+      size="icon-xs"
+      aria-label={ariaLabel}
+      className={cn(
+        'text-muted-foreground hover:bg-transparent hover:text-foreground',
+        className,
+      )}
+      {...props}
+    >
+      <XIcon />
+    </InputGroupButton>
+  );
+}
+
+// ─── InputGroupPasswordToggle ───────────────────────────────────────────────────────
+
+export interface InputGroupPasswordToggleProps
+  extends Omit<
+    React.ComponentProps<typeof InputGroupButton>,
+    'children' | 'onClick'
+  > {
+  /** 当前密码是否可见。 */
+  visible: boolean;
+  /** 切换可见性，由父级同步修改 `<InputGroupInput type>` 。 */
+  onVisibleChange: (visible: boolean) => void;
+}
+
+/**
+ * `InputGroupPasswordToggle` 密码可见性切换按钮。
+ * 受控级别：visible 必填，由父级同时控制 input 的 `type` 与此 prop。
+ */
+function InputGroupPasswordToggle({
+  visible,
+  onVisibleChange,
+  className,
+  ...props
+}: InputGroupPasswordToggleProps) {
+  return (
+    <InputGroupButton
+      data-slot="input-group-password-toggle"
+      size="icon-xs"
+      aria-label={visible ? '隐藏密码' : '显示密码'}
+      aria-pressed={visible}
+      onClick={() => onVisibleChange(!visible)}
+      className={cn(
+        'text-muted-foreground hover:bg-transparent hover:text-foreground',
+        className,
+      )}
+      {...props}
+    >
+      {visible ? <EyeOffIcon /> : <EyeIcon />}
+    </InputGroupButton>
+  );
+}
+
+// ─── InputGroupShowCount ─────────────────────────────────────────────────────────
+
+export interface InputGroupShowCountProps extends React.ComponentProps<'span'> {
+  /** 当前长度（从 value.length 或自定义计算传入。不耦合 value）。 */
+  current: number;
+  /** 最大长度，对齐 `<input maxLength>`。不传时仅显示当前长度。 */
+  max?: number;
+}
+
+/**
+ * `InputGroupShowCount` 字符计数提示。
+ * - 形式：传 max 时显示 `current/max`，否则仅显示 `current`。
+ * - 越界样式：自动加 `data-overflow` 并变为 destructive 色。
+ * - 位置：高频与 `<InputGroupAddon align="block-end">` 配合用于 textarea。
+ */
+function InputGroupShowCount({
+  current,
+  max,
+  className,
+  ...props
+}: InputGroupShowCountProps) {
+  const overflow = typeof max === 'number' && current > max;
+  return (
+    <span
+      data-slot="input-group-show-count"
+      data-overflow={overflow || undefined}
+      className={cn(
+        'flex items-center text-xs tabular-nums text-muted-foreground select-none',
+        'data-[overflow]:text-destructive',
+        className,
+      )}
+      {...props}
+    >
+      {typeof max === 'number' ? `${current}/${max}` : current}
+    </span>
+  );
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+  InputGroupClear,
+  InputGroupPasswordToggle,
+  InputGroupShowCount,
+};

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

@@ -0,0 +1,108 @@
+# InputGroupClear
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+输入组 InputGroup
+将输入框与前后缀装饰（图标、按钮、文字）组合为一个视觉整体。
+
+## 使用场景
+
+- 需要为输入框添加前后缀图标或文字时（搜索图标、金额单位）
+- 需要在输入框内嵌入按钮时（密码可见切换、清除）
+- 需要文本字符计数 / 越界提示时（InputGroupShowCount）
+- Input 单独使用无法满足复合布局需求时
+- 组合结构：InputGroup > InputGroupAddon + (InputGroupInput | InputGroupTextarea)
+- helper 原子：InputGroupClear / InputGroupPasswordToggle / InputGroupShowCount
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `visible` | `boolean` | `true` | – | 是否显示。受控用法下一般绑定 `value.length > 0`。 |
+| `'aria-label'` | `string` | `'清除'` | – | 无障碍 label。 |
+| `visible` | `boolean` | – | ✓ | 当前密码是否可见。 |
+| `onVisibleChange` | `(visible: boolean) => void` | – | ✓ | 切换可见性，由父级同步修改 `<InputGroupInput type>` 。 |
+| `current` | `number` | – | ✓ | 当前长度（从 value.length 或自定义计算传入。不耦合 value）。 |
+| `max` | `number` | – | – | 最大长度，对齐 `<input maxLength>`。不传时仅显示当前长度。 |
+
+## 示例
+
+### WithLeadingIcon
+
+前置图标插槽，聚焦时整体高亮。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupAddon>
+    <InputGroupText>
+      <SearchIcon />
+    </InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="搜索..." />
+</InputGroup>
+```
+
+### Email
+
+邮箱输入：左侧邮件图标 + 右侧域名后缀文本。
+
+```tsx
+<InputGroup className="w-80">
+  <InputGroupAddon>
+    <InputGroupText>
+      <MailIcon />
+    </InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="username" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>@example.com</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Loading
+
+校验中：右侧旋转 loading 图标，对齐 cloud-design `state="loading"`。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupInput placeholder="校验中..." defaultValue="abc@" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>
+      <Loader2Icon className="animate-spin" />
+    </InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Disabled
+
+禁用状态的输入框组合。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupAddon>
+    <InputGroupText>
+      <SearchIcon />
+    </InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="不可编辑" disabled />
+</InputGroup>
+```
+
+### Invalid
+
+错误态：内部 `InputGroupInput` 透传 `aria-invalid`，整体边框转 destructive 色。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupAddon>
+    <InputGroupText>
+      <MailIcon />
+    </InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="请输入邮箱" aria-invalid="true" />
+</InputGroup>
+```