@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/mentions/index.tsx

@@ -0,0 +1,369 @@
+/**
+ * 提及 Mentions
+ *
+ * 在多行文本输入中通过特定前缀（如 `@` / `#`）触发候选浮层，选中后将提及插入文本。
+ *
+ * @when
+ * - 评论 / 聊天中 @某人
+ * - 文档 / 工单中 #话题、#工单号 引用
+ * - 任何在长文本中需要快速引用某个实体并保留可解析标记的场景
+ */
+'use client';
+
+import * as React from 'react';
+import { Loader2 } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Textarea, type TextareaSize } from '@/components/textarea';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface MentionsOption {
+  /** 插入文本中的 value（不含前缀） */
+  value: string;
+  /** 候选列表显示文本，不传则用 value */
+  label?: React.ReactNode;
+  /** 禁用此选项 */
+  disabled?: boolean;
+}
+
+export type MentionsPrefix = string | string[];
+
+export type MentionsStatus = 'error' | 'warning';
+
+export type MentionsPlacement = 'top' | 'bottom';
+
+export interface MentionsProps
+  extends Omit<
+    React.ComponentProps<'textarea'>,
+    'onChange' | 'value' | 'defaultValue' | 'onSelect' | 'prefix' | 'size'
+  > {
+  /** 候选选项列表 */
+  options: MentionsOption[];
+  /** 受控值 */
+  value?: string;
+  /** 非受控初始值 */
+  defaultValue?: string;
+  /** 文本变化回调 */
+  onChange?: (value: string) => void;
+  /**
+   * 触发前缀字符，可传单个或多个
+   * @default "@"
+   */
+  prefix?: MentionsPrefix;
+  /**
+   * 选中候选项后插入文本的尾随分隔符
+   * @default " "
+   */
+  split?: string;
+  /**
+   * 自定义候选过滤；传 `false` 关闭本地过滤（用于 onSearch 受控候选）
+   * @default 模糊匹配 value
+   */
+  filterOption?: false | ((input: string, option: MentionsOption) => boolean);
+  /** 校验前缀后输入文本是否仍处于有效搜索态（返回 false 则关闭浮层） */
+  validateSearch?: (text: string, prefix: string) => boolean;
+  /** prefix 后输入时的搜索回调，用于异步刷新 options */
+  onSearch?: (text: string, prefix: string) => void;
+  /** 选中候选项回调 */
+  onSelect?: (option: MentionsOption, prefix: string) => void;
+  /**
+   * 候选下拉空状态文案
+   * @default "无匹配"
+   */
+  notFoundContent?: React.ReactNode;
+  /** 候选下拉加载态 */
+  loading?: boolean;
+  /** 校验状态 */
+  status?: MentionsStatus;
+  /**
+   * Textarea 尺寸
+   * @default "default"
+   */
+  size?: TextareaSize;
+  /**
+   * Textarea 行数
+   * @default 3
+   */
+  rows?: number;
+  /**
+   * 候选浮层相对 textarea 的位置
+   * @default "bottom"
+   */
+  placement?: MentionsPlacement;
+  /** 只读 */
+  readOnly?: boolean;
+  /** 禁用 */
+  disabled?: boolean;
+}
+
+interface TriggerCtx {
+  /** prefix 字符在文本中的起始位置 */
+  start: number;
+  /** prefix 后已输入的搜索文本 */
+  query: string;
+  /** 实际命中的 prefix 字符 */
+  prefix: string;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function toPrefixList(prefix: MentionsPrefix): string[] {
+  return Array.isArray(prefix) ? prefix : [prefix];
+}
+
+function defaultFilter(input: string, option: MentionsOption): boolean {
+  if (!input) return true;
+  return option.value.toLowerCase().includes(input.toLowerCase());
+}
+
+function getTriggerContext(
+  value: string,
+  caret: number,
+  prefixes: string[],
+): TriggerCtx | null {
+  if (caret <= 0) return null;
+  for (let i = caret - 1; i >= 0; i--) {
+    const ch = value[i];
+    if (ch === undefined) return null;
+    if (prefixes.includes(ch)) {
+      const prev = i === 0 ? '' : value[i - 1] ?? '';
+      if (prev === '' || /\s/.test(prev)) {
+        return {
+          start: i,
+          query: value.slice(i + 1, caret),
+          prefix: ch,
+        };
+      }
+      return null;
+    }
+    if (/\s/.test(ch)) return null;
+  }
+  return null;
+}
+
+// ─── Mentions ───────────────────────────────────────────────────────────────
+
+function Mentions({
+  options,
+  value,
+  defaultValue,
+  onChange,
+  prefix = '@',
+  split = ' ',
+  filterOption,
+  validateSearch,
+  onSearch,
+  onSelect,
+  notFoundContent = '无匹配',
+  loading = false,
+  status,
+  size,
+  rows = 3,
+  placement = 'bottom',
+  readOnly,
+  disabled,
+  className,
+  onKeyDown,
+  onBlur,
+  ref,
+  ...props
+}: MentionsProps & { ref?: React.Ref<HTMLTextAreaElement> }) {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = React.useState<string>(defaultValue ?? '');
+  const current = isControlled ? value! : internal;
+
+  const innerRef = React.useRef<HTMLTextAreaElement | null>(null);
+  React.useImperativeHandle(
+    ref as React.Ref<HTMLTextAreaElement>,
+    () => innerRef.current as HTMLTextAreaElement,
+  );
+
+  const [ctx, setCtx] = React.useState<TriggerCtx | null>(null);
+  const [activeIdx, setActiveIdx] = React.useState(0);
+
+  const prefixes = React.useMemo(() => toPrefixList(prefix), [prefix]);
+
+  const filtered = React.useMemo(() => {
+    if (!ctx) return [];
+    if (filterOption === false) return options;
+    const fn =
+      typeof filterOption === 'function' ? filterOption : defaultFilter;
+    return options.filter((o) => fn(ctx.query, o));
+  }, [ctx, options, filterOption]);
+
+  React.useEffect(() => {
+    setActiveIdx(0);
+  }, [ctx?.query, ctx?.prefix]);
+
+  const update = (next: string) => {
+    if (!isControlled) setInternal(next);
+    onChange?.(next);
+  };
+
+  const closeDropdown = () => setCtx(null);
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const next = e.target.value;
+    update(next);
+    const caret = e.target.selectionStart ?? next.length;
+    const t = getTriggerContext(next, caret, prefixes);
+    if (t && validateSearch && !validateSearch(t.query, t.prefix)) {
+      closeDropdown();
+      return;
+    }
+    setCtx(t);
+    if (t) onSearch?.(t.query, t.prefix);
+  };
+
+  const insertOption = (opt: MentionsOption) => {
+    if (!ctx || opt.disabled) return;
+    const el = innerRef.current;
+    const before = current.slice(0, ctx.start);
+    const after = current.slice(
+      el?.selectionStart ?? ctx.start + 1 + ctx.query.length,
+    );
+    const inserted = `${ctx.prefix}${opt.value}${split}`;
+    const next = `${before}${inserted}${after}`;
+    update(next);
+    onSelect?.(opt, ctx.prefix);
+    closeDropdown();
+    window.requestAnimationFrame(() => {
+      if (!el) return;
+      const pos = (before + inserted).length;
+      el.focus();
+      el.setSelectionRange(pos, pos);
+    });
+  };
+
+  const dropdownOpen =
+    !!ctx &&
+    !disabled &&
+    !readOnly &&
+    (loading || filtered.length > 0 || !!notFoundContent);
+  const hasSelectableItem = filtered.some((o) => !o.disabled);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (dropdownOpen && hasSelectableItem) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setActiveIdx((i) => {
+          const len = filtered.length;
+          for (let k = 1; k <= len; k++) {
+            const idx = (i + k) % len;
+            if (!filtered[idx]?.disabled) return idx;
+          }
+          return i;
+        });
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActiveIdx((i) => {
+          const len = filtered.length;
+          for (let k = 1; k <= len; k++) {
+            const idx = (i - k + len) % len;
+            if (!filtered[idx]?.disabled) return idx;
+          }
+          return i;
+        });
+        return;
+      }
+      if (e.key === 'Enter' || e.key === 'Tab') {
+        const opt = filtered[activeIdx];
+        if (opt && !opt.disabled) {
+          e.preventDefault();
+          insertOption(opt);
+          return;
+        }
+      }
+    }
+    if (dropdownOpen && e.key === 'Escape') {
+      e.preventDefault();
+      closeDropdown();
+      return;
+    }
+    onKeyDown?.(e);
+  };
+
+  return (
+    <div data-slot="mentions" className={cn('relative', className)}>
+      <Textarea
+        ref={innerRef}
+        value={current}
+        rows={rows}
+        size={size}
+        disabled={disabled}
+        readOnly={readOnly}
+        aria-invalid={status === 'error' ? true : undefined}
+        data-status={status}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onBlur={(e) => {
+          window.setTimeout(() => closeDropdown(), 120);
+          onBlur?.(e);
+        }}
+        {...props}
+      />
+      {dropdownOpen && (
+        <div
+          data-slot="mentions-dropdown"
+          data-placement={placement}
+          role="listbox"
+          className={cn(
+            'absolute left-0 z-50 max-h-60 w-56 overflow-auto rounded-md border border-border bg-popover p-1 text-xs text-popover-foreground shadow-md',
+            placement === 'bottom' && 'top-full mt-1',
+            placement === 'top' && 'bottom-full mb-1',
+          )}
+        >
+          {loading ? (
+            <div
+              data-slot="mentions-loading"
+              className="flex items-center justify-center gap-1.5 px-2 py-3 text-muted-foreground"
+            >
+              <Loader2 className="size-3.5 animate-spin" />
+              <span>加载中</span>
+            </div>
+          ) : filtered.length > 0 ? (
+            filtered.map((opt, i) => (
+              <div
+                key={opt.value}
+                role="option"
+                aria-selected={i === activeIdx}
+                aria-disabled={opt.disabled || undefined}
+                data-slot="mentions-item"
+                data-active={i === activeIdx ? '' : undefined}
+                data-disabled={opt.disabled ? '' : undefined}
+                onMouseDown={(e) => {
+                  e.preventDefault();
+                  insertOption(opt);
+                }}
+                onMouseEnter={() => {
+                  if (!opt.disabled) setActiveIdx(i);
+                }}
+                className={cn(
+                  'cursor-pointer rounded-sm px-2 py-1.5 outline-none',
+                  i === activeIdx &&
+                    !opt.disabled &&
+                    'bg-accent text-accent-foreground',
+                  opt.disabled && 'cursor-not-allowed opacity-50',
+                )}
+              >
+                {opt.label ?? opt.value}
+              </div>
+            ))
+          ) : (
+            <div
+              data-slot="mentions-empty"
+              className="px-2 py-3 text-center text-muted-foreground"
+            >
+              {notFoundContent}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export { Mentions };

package/src/components/mentions/meta.md

@@ -0,0 +1,118 @@
+# Mentions
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+提及 Mentions
+在多行文本输入中通过特定前缀（如 `@` / `#`）触发候选浮层，选中后将提及插入文本。
+
+## 使用场景
+
+- 评论 / 聊天中 @某人
+- 文档 / 工单中 #话题、#工单号 引用
+- 任何在长文本中需要快速引用某个实体并保留可解析标记的场景
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `MentionsOption[]` | – | ✓ | 候选选项列表 |
+| `value` | `string` | – | – | 受控值 |
+| `defaultValue` | `string` | – | – | 非受控初始值 |
+| `onChange` | `(value: string) => void` | – | – | 文本变化回调 |
+| `prefix` | `MentionsPrefix` | `"@"` | – | 触发前缀字符，可传单个或多个 |
+| `split` | `string` | `" "` | – | 选中候选项后插入文本的尾随分隔符 |
+| `filterOption` | `false \| ((input: string, option: MentionsOption) => boolean)` | `模糊匹配 value` | – | 自定义候选过滤；传 `false` 关闭本地过滤（用于 onSearch 受控候选） |
+| `validateSearch` | `(text: string, prefix: string) => boolean` | – | – | 校验前缀后输入文本是否仍处于有效搜索态（返回 false 则关闭浮层） |
+| `onSearch` | `(text: string, prefix: string) => void` | – | – | prefix 后输入时的搜索回调，用于异步刷新 options |
+| `onSelect` | `(option: MentionsOption, prefix: string) => void` | – | – | 选中候选项回调 |
+| `notFoundContent` | `React.ReactNode` | `"无匹配"` | – | 候选下拉空状态文案 |
+| `loading` | `boolean` | – | – | 候选下拉加载态 |
+| `status` | `MentionsStatus` | – | – | 校验状态 |
+| `size` | `TextareaSize` | `"default"` | – | Textarea 尺寸 |
+| `rows` | `number` | `3` | – | Textarea 行数 |
+| `placement` | `MentionsPlacement` | `"bottom"` | – | 候选浮层相对 textarea 的位置 |
+| `readOnly` | `boolean` | – | – | 只读 |
+| `disabled` | `boolean` | – | – | 禁用 |
+
+## 示例
+
+### MultiPrefix
+
+单组件同时支持多个触发前缀。
+
+```tsx
+<Mentions
+  options={[...users, ...topics]}
+  prefix={['@', '#']}
+  placeholder="输入 @ 提及用户，输入 # 引用话题"
+  className="max-w-sm"
+/>
+```
+
+### Sizes
+
+三档尺寸对齐 Textarea。
+
+```tsx
+<div className="flex w-full max-w-sm flex-col gap-3">
+  <Mentions size="sm" options={users} placeholder="sm" />
+  <Mentions size="default" options={users} placeholder="default" />
+  <Mentions size="lg" options={users} placeholder="lg" />
+</div>
+```
+
+### PlacementTop
+
+浮层向上展开，适合靠近底部的输入区。
+
+```tsx
+<div className="flex min-h-64 max-w-sm flex-col justify-end">
+  <Mentions
+    options={users}
+    placement="top"
+    placeholder="输入 @ 提及用户（浮层向上）"
+  />
+</div>
+```
+
+### NotFound
+
+候选无匹配时展示自定义空态。
+
+```tsx
+<Mentions
+  options={users}
+  notFoundContent="没有找到匹配的成员"
+  placeholder="试试输入 @zzz"
+  className="max-w-sm"
+/>
+```
+
+### Status
+
+校验失败状态，外观与 Textarea `aria-invalid` 一致。
+
+```tsx
+<div className="flex w-full max-w-sm flex-col gap-3">
+  <Mentions options={users} status="error" placeholder="error" />
+  <Mentions options={users} status="warning" placeholder="warning" />
+</div>
+```
+
+### Disabled
+
+只读 / 禁用。
+
+```tsx
+<div className="flex w-full max-w-sm flex-col gap-3">
+  <Mentions
+    options={users}
+    readOnly
+    defaultValue="@alice 这是只读状态"
+    placeholder="只读"
+  />
+  <Mentions options={users} disabled placeholder="已禁用" />
+</div>
+```

package/src/components/mentions/stories.tsx

@@ -0,0 +1,153 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Mentions, type MentionsOption } from './index';
+
+const meta: Meta<typeof Mentions> = {
+  title: '数据展示 · Data Display/Mentions 提及',
+  component: Mentions,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ minHeight: 280 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const users: MentionsOption[] = [
+  { value: 'alice', label: 'Alice' },
+  { value: 'bob', label: 'Bob' },
+  { value: 'carol', label: 'Carol' },
+  { value: 'dave', label: 'Dave', disabled: true },
+];
+
+const topics: MentionsOption[] = [
+  { value: 'frontend', label: '前端' },
+  { value: 'backend', label: '后端' },
+  { value: 'design', label: '设计' },
+];
+
+/** 输入 `@` 触发候选列表，选中后插入到光标位置。 */
+export const Default: Story = {
+  render: () => (
+    <Mentions
+      options={users}
+      placeholder="输入 @ 提及用户"
+      className="max-w-sm"
+    />
+  ),
+};
+
+/** 单组件同时支持多个触发前缀。 */
+export const MultiPrefix: Story = {
+  render: () => (
+    <Mentions
+      options={[...users, ...topics]}
+      prefix={['@', '#']}
+      placeholder="输入 @ 提及用户，输入 # 引用话题"
+      className="max-w-sm"
+    />
+  ),
+};
+
+/** 三档尺寸对齐 Textarea。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex w-full max-w-sm flex-col gap-3">
+      <Mentions size="sm" options={users} placeholder="sm" />
+      <Mentions size="default" options={users} placeholder="default" />
+      <Mentions size="lg" options={users} placeholder="lg" />
+    </div>
+  ),
+};
+
+/** 通过 `onSearch` 配合 `filterOption={false}` 实现服务端搜索。 */
+export const AsyncSearch: Story = {
+  render: () => {
+    const all: MentionsOption[] = [
+      { value: 'alice' },
+      { value: 'bob' },
+      { value: 'carol' },
+      { value: 'dave' },
+      { value: 'eve' },
+      { value: 'frank' },
+    ];
+    const [opts, setOpts] = React.useState<MentionsOption[]>([]);
+    const [loading, setLoading] = React.useState(false);
+    const timer = React.useRef<number | null>(null);
+    const handleSearch = (text: string) => {
+      if (timer.current) window.clearTimeout(timer.current);
+      setLoading(true);
+      timer.current = window.setTimeout(() => {
+        setOpts(
+          all.filter((o) => o.value.toLowerCase().includes(text.toLowerCase())),
+        );
+        setLoading(false);
+      }, 400);
+    };
+    return (
+      <Mentions
+        options={opts}
+        loading={loading}
+        filterOption={false}
+        onSearch={handleSearch}
+        placeholder="输入 @ 远程搜索用户"
+        className="max-w-sm"
+      />
+    );
+  },
+};
+
+/** 浮层向上展开，适合靠近底部的输入区。 */
+export const PlacementTop: Story = {
+  render: () => (
+    <div className="flex min-h-64 max-w-sm flex-col justify-end">
+      <Mentions
+        options={users}
+        placement="top"
+        placeholder="输入 @ 提及用户（浮层向上）"
+      />
+    </div>
+  ),
+};
+
+/** 候选无匹配时展示自定义空态。 */
+export const NotFound: Story = {
+  render: () => (
+    <Mentions
+      options={users}
+      notFoundContent="没有找到匹配的成员"
+      placeholder="试试输入 @zzz"
+      className="max-w-sm"
+    />
+  ),
+};
+
+/** 校验失败状态，外观与 Textarea `aria-invalid` 一致。 */
+export const Status: Story = {
+  render: () => (
+    <div className="flex w-full max-w-sm flex-col gap-3">
+      <Mentions options={users} status="error" placeholder="error" />
+      <Mentions options={users} status="warning" placeholder="warning" />
+    </div>
+  ),
+};
+
+/** 只读 / 禁用。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex w-full max-w-sm flex-col gap-3">
+      <Mentions
+        options={users}
+        readOnly
+        defaultValue="@alice 这是只读状态"
+        placeholder="只读"
+      />
+      <Mentions options={users} disabled placeholder="已禁用" />
+    </div>
+  ),
+};