@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/tree-select/meta.md

@@ -0,0 +1,78 @@
+# TreeSelect
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+树选择 TreeSelect
+树形结构数据的下拉选择控件，基于 Popover + 内嵌 Tree 渲染。支持单选 / 多选（父子联动 / 独立勾选）、
+内置或外部接管的搜索、受控开合等业界主流能力。
+
+## 使用场景
+
+- 组织架构选择（部门 / 团队）
+- 分类目录的层级选择
+- 需要树形展示的下拉单选 / 多选
+- 多选场景下需要父子联动勾选并按策略回填值时
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `treeData` | `TreeSelectNode[]` | – | ✓ | 树形数据源。 |
+| `value` | `string \| string[]` | – | – | 选中值（受控）：单选为 string，多选为 string[]。 |
+| `defaultValue` | `string \| string[]` | – | – | 默认选中值（非受控）。 |
+| `onChange` | `( value: string \| string[], info: { selectedNodes: TreeSelectNode[] }, ) => void` | – | – | 选择回调。 - 单选 → value 为 string，selectedNodes 为单元素数组 - 多选 → value 为 string[]，按 showCheckedStrategy 过滤 |
+| `placeholder` | `string` | – | – | 占位文本。@default '请选择' |
+| `disabled` | `boolean` | – | – | 是否禁用。@default false |
+| `size` | `'sm' \| 'default' \| 'lg'` | – | – | 触发器尺寸：sm 28px / default 32px / lg 36px，对齐 Button、Input、Select 三档规范。 |
+| `multiple` | `boolean` | – | – | 是否多选。@default false |
+| `checkStrictly` | `boolean` | `false` | – | 多选下父子节点勾选是否独立（不联动），仅在 multiple=true 时生效。 |
+| `showCheckedStrategy` | `'parent' \| 'child' \| 'all'` | `'parent'` | – | 多选回填策略： - 'parent' 父级全选时仅返回父级（默认） - 'child' 仅返回叶子节点 - 'all' 全量返回 仅在 multiple=true 且 checkStrictly=false 时生效。 |
+| `allowClear` | `boolean` | `true` | – | 是否允许清空：有选中且非 disabled / loading 时，右侧 chevron 切为 × 按钮。 与 Select 一致：右侧图标优先级 loading > clear > chevron，三者互斥占同一位置。 |
+| `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 data-loading="true" 供外部样式穿透。 |
+| `showSearch` | `boolean` | – | – | 是否显示弹层内置搜索框。@default false |
+| `onSearch` | `(keyword: string) => void` | – | – | 搜索回调；提供后内部不再做本地过滤，由外部接管 treeData。 |
+| `treeNodeFilterProp` | `'label' \| 'value'` | – | – | 内置搜索的过滤字段。@default 'label' |
+| `defaultExpandAll` | `boolean` | – | – | 默认展开所有节点。@default false |
+| `defaultExpandedKeys` | `string[]` | – | – | 默认展开节点 value 列表。 |
+| `open` | `boolean` | – | – | 受控开合。 |
+| `defaultOpen` | `boolean` | – | – | 默认开合（非受控）。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 开合变化回调。 |
+| `notFoundContent` | `React.ReactNode` | – | – | 无数据时显示内容。@default '暂无数据' |
+| `popoverProps` | `React.ComponentProps<typeof PopoverPrimitive.Content>` | – | – | 透传到 PopoverContent。 |
+
+## 示例
+
+### CheckStrictly
+
+父子独立勾选：勾选父级不影响子级，反之亦然。
+
+```tsx
+<TreeSelect treeData={treeData} multiple checkStrictly defaultExpandAll />
+```
+
+### Sizes
+
+三档尺寸：sm / default / lg，对齐 Button、Input、Select。
+
+```tsx
+<div className="flex items-center gap-3">
+  <TreeSelect treeData={treeData} size="sm" defaultExpandAll />
+  <TreeSelect treeData={treeData} defaultExpandAll />
+  <TreeSelect treeData={treeData} size="lg" defaultExpandAll />
+</div>
+```
+
+### WithClear
+
+已选时右侧 chevron 切为 ×，点击清空 value；chevron 与 × 占同一位置、互斥。
+
+```tsx
+<TreeSelect
+  treeData={treeData}
+  defaultValue="fe-1"
+  defaultExpandAll
+  allowClear
+/>
+```

package/src/components/tree-select/stories.tsx

@@ -0,0 +1,234 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { TreeSelect } from './index';
+import type { TreeSelectNode } from './index';
+
+const treeData: TreeSelectNode[] = [
+  {
+    value: 'engineering',
+    label: '工程部',
+    children: [
+      {
+        value: 'frontend',
+        label: '前端团队',
+        children: [
+          { value: 'fe-1', label: '张三' },
+          { value: 'fe-2', label: '李四' },
+        ],
+      },
+      {
+        value: 'backend',
+        label: '后端团队',
+        children: [
+          { value: 'be-1', label: '王五' },
+          { value: 'be-2', label: '赵六', disabled: true },
+        ],
+      },
+    ],
+  },
+  {
+    value: 'design',
+    label: '设计部',
+    children: [
+      { value: 'ux-1', label: '小明' },
+      { value: 'ux-2', label: '小红' },
+    ],
+  },
+  { value: 'hr', label: '人事部' },
+];
+
+const meta: Meta<typeof TreeSelect> = {
+  title: '数据录入 · Data Entry/TreeSelect 树选择',
+  component: TreeSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      source: { type: 'dynamic' },
+      description: {
+        component:
+          '树形结构的下拉选择，支持单选 / 多选（父子联动 / 独立勾选）、内置或外部接管的搜索、受控开合等业界主流能力。',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础单选 + treeData。 */
+export const Default: Story = {
+  render: () => <TreeSelect treeData={treeData} defaultExpandAll />,
+};
+
+/** 多选模式：父子联动勾选，半选状态由 indeterminate 表达。 */
+export const Multiple: Story = {
+  render: () => <TreeSelect treeData={treeData} multiple defaultExpandAll />,
+};
+
+/** 父子独立勾选：勾选父级不影响子级，反之亦然。 */
+export const CheckStrictly: Story = {
+  render: () => (
+    <TreeSelect treeData={treeData} multiple checkStrictly defaultExpandAll />
+  ),
+};
+
+/** 三种回填策略对比：parent / child / all。 */
+export const CheckedStrategy: Story = {
+  render: () => {
+    const [parentVal, setParentVal] = React.useState<string[]>([]);
+    const [childVal, setChildVal] = React.useState<string[]>([]);
+    const [allVal, setAllVal] = React.useState<string[]>([]);
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex items-center gap-2">
+          <span className="w-16 text-xs text-muted-foreground">parent</span>
+          <TreeSelect
+            treeData={treeData}
+            multiple
+            showCheckedStrategy="parent"
+            value={parentVal}
+            onChange={(v) => setParentVal(v as string[])}
+            defaultExpandAll
+          />
+          <span className="text-xs text-muted-foreground">
+            出参：{JSON.stringify(parentVal)}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="w-16 text-xs text-muted-foreground">child</span>
+          <TreeSelect
+            treeData={treeData}
+            multiple
+            showCheckedStrategy="child"
+            value={childVal}
+            onChange={(v) => setChildVal(v as string[])}
+            defaultExpandAll
+          />
+          <span className="text-xs text-muted-foreground">
+            出参：{JSON.stringify(childVal)}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="w-16 text-xs text-muted-foreground">all</span>
+          <TreeSelect
+            treeData={treeData}
+            multiple
+            showCheckedStrategy="all"
+            value={allVal}
+            onChange={(v) => setAllVal(v as string[])}
+            defaultExpandAll
+          />
+          <span className="text-xs text-muted-foreground">
+            出参：{JSON.stringify(allVal)}
+          </span>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** 内置搜索：按 label 字段本地过滤。 */
+export const WithSearch: Story = {
+  render: () => <TreeSelect treeData={treeData} showSearch defaultExpandAll />,
+};
+
+/** 异步搜索：提供 onSearch 由外部接管 treeData，组件不再做本地过滤。 */
+export const AsyncSearch: Story = {
+  render: () => {
+    const [data, setData] = React.useState<TreeSelectNode[]>([
+      {
+        value: 'zhejiang',
+        label: '浙江',
+        children: [{ value: 'sx', label: '绍兴' }],
+      },
+    ]);
+    const timer = React.useRef<ReturnType<typeof setTimeout>>();
+    return (
+      <TreeSelect
+        treeData={data}
+        showSearch
+        defaultExpandAll
+        onSearch={(kw) => {
+          if (timer.current) clearTimeout(timer.current);
+          if (!kw) {
+            setData([
+              {
+                value: 'zhejiang',
+                label: '浙江',
+                children: [{ value: 'sx', label: '绍兴' }],
+              },
+            ]);
+            return;
+          }
+          timer.current = setTimeout(() => {
+            setData([{ value: kw, label: kw }]);
+          }, 300);
+        }}
+      />
+    );
+  },
+};
+
+/** 三档尺寸：sm / default / lg，对齐 Button、Input、Select。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <TreeSelect treeData={treeData} size="sm" defaultExpandAll />
+      <TreeSelect treeData={treeData} defaultExpandAll />
+      <TreeSelect treeData={treeData} size="lg" defaultExpandAll />
+    </div>
+  ),
+};
+
+/** 已选时右侧 chevron 切为 ×，点击清空 value；chevron 与 × 占同一位置、互斥。 */
+export const WithClear: Story = {
+  render: () => (
+    <TreeSelect
+      treeData={treeData}
+      defaultValue="fe-1"
+      defaultExpandAll
+      allowClear
+    />
+  ),
+};
+
+/** 加载态：把右侧图标替换为旋转 spinner，与 Select 行为一致。 */
+export const Loading: Story = {
+  render: () => <TreeSelect treeData={treeData} loading />,
+};
+
+/** 整体禁用。 */
+export const Disabled: Story = {
+  render: () => <TreeSelect treeData={treeData} disabled defaultValue="fe-1" />,
+};
+
+/** 错误态：通过 aria-invalid 触发 destructive 边框与 ring。 */
+export const Invalid: Story = {
+  render: () => <TreeSelect treeData={treeData} aria-invalid />,
+};
+
+/** 受控 value + 受控 open。 */
+export const Controlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<string[]>(['fe-1', 'be-1']);
+    const [open, setOpen] = React.useState(false);
+    return (
+      <div className="flex flex-col items-start gap-2">
+        <TreeSelect
+          treeData={treeData}
+          multiple
+          value={value}
+          onChange={(v) => setValue(v as string[])}
+          open={open}
+          onOpenChange={setOpen}
+          defaultExpandAll
+        />
+        <span className="text-xs text-muted-foreground">
+          value: {JSON.stringify(value)} · open: {String(open)}
+        </span>
+      </div>
+    );
+  },
+};

package/src/components/typography/index.tsx

@@ -0,0 +1,290 @@
+/* eslint-disable teamix-evo/no-arbitrary-tw-value -- Prose uses child selectors with em-relative sizes that are not tokenizable */
+/**
+ * 排版 Typography
+ *
+ * 基础文本排版组件集：Title / Paragraph / Text / Link + Prose 富文本容器。
+ * 对齐 antd Typography 的 `type`/`strong`/`delete`/`disabled`/`code`/`ellipsis`/`copyable`/`italic`/`underline`/`mark`/`keyboard` 能力。
+ *
+ * @when
+ * - 文章 / 博客 / 笔记中展示标题与正文
+ * - 需要可复制 / 可省略 / 带语义色的文本
+ * - Markdown / CMS 富文本渲染产物套排版样式
+ */
+import * as React from 'react';
+import { Check, Copy } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Color System ────────────────────────────────────────────────────────────
+
+/**
+ * 语义色 6 档 — 对齐 ADR 0021。
+ * antd `type` 迁移：`secondary` → `muted`、`danger` → `destructive`。
+ */
+type TypographyColor =
+  | 'default'
+  | 'muted'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'destructive';
+
+const colorClass: Record<TypographyColor, string> = {
+  default: 'text-foreground',
+  muted: 'text-muted-foreground',
+  primary: 'text-primary',
+  success: 'text-success',
+  warning: 'text-warning',
+  destructive: 'text-destructive',
+};
+
+// ─── Prose Container ─────────────────────────────────────────────────────────
+
+interface ProseProps extends React.ComponentProps<'div'> {}
+
+/**
+ * Prose 容器 — 给原始 HTML（Markdown 渲染产物 / CMS 富文本）套上一致排版样式。
+ * 内部自动应用标题字号 / 段落行高 / 列表样式 / 链接 / 代码块 / 引用。
+ * 不依赖 `@tailwindcss/typography` 插件，手写 selector 确保与 design tokens 对齐。
+ */
+function Prose({ className, ...props }: ProseProps) {
+  return (
+    <div
+      data-slot="prose"
+      className={cn(
+        'max-w-prose text-sm text-foreground',
+        // headings
+        '[&_h1]:mt-8 [&_h1]:mb-4 [&_h1]:text-3xl [&_h1]:font-bold [&_h1]:tracking-tight',
+        '[&_h2]:mt-6 [&_h2]:mb-3 [&_h2]:text-2xl [&_h2]:font-semibold',
+        '[&_h3]:mt-5 [&_h3]:mb-2 [&_h3]:text-xl [&_h3]:font-semibold',
+        '[&_h4]:mt-4 [&_h4]:mb-2 [&_h4]:text-lg [&_h4]:font-medium',
+        // paragraphs / lists
+        '[&_p]:my-3 [&_p]:leading-7',
+        '[&_ul]:my-3 [&_ul]:list-disc [&_ul]:pl-6',
+        '[&_ol]:my-3 [&_ol]:list-decimal [&_ol]:pl-6',
+        '[&_li]:my-1',
+        // inline
+        '[&_a]:text-primary',
+        '[&_strong]:font-semibold',
+        '[&_em]:italic',
+        // code
+        '[&_code]:rounded [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.875em]',
+        '[&_pre]:my-4 [&_pre]:overflow-x-auto [&_pre]:rounded-md [&_pre]:bg-muted [&_pre]:p-4',
+        '[&_pre_code]:bg-transparent [&_pre_code]:p-0',
+        // blockquote / hr
+        '[&_blockquote]:my-4 [&_blockquote]:border-l-4 [&_blockquote]:border-border [&_blockquote]:pl-4 [&_blockquote]:italic [&_blockquote]:text-muted-foreground',
+        '[&_hr]:my-6 [&_hr]:border-border',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── Title ───────────────────────────────────────────────────────────────────
+
+const titleSizes = {
+  1: 'text-3xl font-bold tracking-tight',
+  2: 'text-2xl font-semibold tracking-tight',
+  3: 'text-xl font-semibold',
+  4: 'text-lg font-medium',
+  5: 'text-base font-medium',
+} as const;
+
+interface TitleProps extends React.ComponentProps<'h1'> {
+  /**
+   * 层级（1~5），决定字号 / 粗细；同时映射为 `<h1>~<h5>` 标签。
+   * @default 1
+   */
+  level?: 1 | 2 | 3 | 4 | 5;
+}
+
+function Title({ level = 1, className, ...props }: TitleProps) {
+  const Comp = `h${level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5';
+  return (
+    <Comp
+      data-slot="title"
+      className={cn(titleSizes[level], className)}
+      {...props}
+    />
+  );
+}
+
+// ─── Paragraph ───────────────────────────────────────────────────────────────
+
+interface ParagraphProps extends React.ComponentProps<'p'> {
+  /** 语义色。@default "default" */
+  color?: TypographyColor;
+}
+
+function Paragraph({ color = 'default', className, ...props }: ParagraphProps) {
+  return (
+    <p
+      data-slot="paragraph"
+      className={cn('text-xs leading-6', colorClass[color], className)}
+      {...props}
+    />
+  );
+}
+
+// ─── Text ────────────────────────────────────────────────────────────────────
+
+interface CopyableConfig {
+  /** 要复制的文本（默认使用 children 的纯文本） */
+  text?: string;
+  /** 自定义复制按钮的 tooltip：[复制提示, 已复制提示] */
+  tooltips?: [string, string];
+}
+
+interface TextProps extends React.ComponentProps<'span'> {
+  /**
+   * 语义色 — 6 档枚举，对齐 OpenTrek tokens（ADR 0021）。
+   * antd `type` 迁移：`secondary` → `muted`、`danger` → `destructive`。
+   * @default "default"
+   */
+  color?: TypographyColor;
+  /** 删除线。@default false */
+  delete?: boolean;
+  /** 不可用（灰色 + 不可选）。@default false */
+  disabled?: boolean;
+  /** 加粗。@default false */
+  strong?: boolean;
+  /** 斜体。@default false */
+  italic?: boolean;
+  /** 下划线。@default false */
+  underline?: boolean;
+  /** 高亮标记。@default false */
+  mark?: boolean;
+  /** 键盘样式。@default false */
+  keyboard?: boolean;
+  /** 行内代码样式。@default false */
+  code?: boolean;
+  /**
+   * 单行省略（CSS truncate）。
+   * @default false
+   */
+  ellipsis?: boolean;
+  /**
+   * 可复制 — 末尾追加复制图标按钮。
+   * 传对象时可指定要复制的文本；传 `true` 用 children。
+   * @default false
+   */
+  copyable?: boolean | CopyableConfig;
+}
+
+function Text({
+  color = 'default',
+  delete: del = false,
+  disabled = false,
+  strong = false,
+  italic = false,
+  underline = false,
+  mark = false,
+  keyboard = false,
+  code = false,
+  ellipsis = false,
+  copyable = false,
+  className,
+  children,
+  ...props
+}: TextProps) {
+  const [copied, setCopied] = React.useState(false);
+
+  const handleCopy = () => {
+    const text =
+      typeof copyable === 'object' && copyable.text
+        ? copyable.text
+        : typeof children === 'string'
+        ? children
+        : '';
+    void navigator.clipboard?.writeText(text).then(() => {
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
+  // Build content with semantic wrappers
+  let content: React.ReactNode = children;
+  if (mark) content = <mark className="bg-warning/20 px-0.5">{content}</mark>;
+  if (keyboard)
+    content = (
+      <kbd className="rounded border border-border bg-muted px-1 py-0.5 font-mono text-xs">
+        {content}
+      </kbd>
+    );
+
+  const cls = cn(
+    'text-xs',
+    colorClass[color],
+    strong && 'font-semibold',
+    del && 'line-through',
+    italic && 'italic',
+    underline && 'underline underline-offset-4',
+    disabled && 'cursor-not-allowed select-none opacity-50',
+    ellipsis && 'inline-block max-w-full truncate align-bottom',
+    code && 'rounded bg-muted px-1.5 py-0.5 font-mono text-[0.875em]',
+    className,
+  );
+
+  if (copyable) {
+    return (
+      <span data-slot="text" className="inline-flex items-center gap-1">
+        <span className={cls} {...props}>
+          {content}
+        </span>
+        <button
+          type="button"
+          onClick={handleCopy}
+          aria-label={copied ? '已复制' : '复制'}
+          className="cursor-pointer rounded-sm p-0.5 text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        >
+          {copied ? (
+            <Check className="size-3.5 text-success" />
+          ) : (
+            <Copy className="size-3.5" />
+          )}
+        </button>
+      </span>
+    );
+  }
+
+  return (
+    <span data-slot="text" className={cls} {...props}>
+      {content}
+    </span>
+  );
+}
+
+// ─── Link ────────────────────────────────────────────────────────────────────
+
+interface LinkProps extends React.ComponentProps<'a'> {
+  /** 语义色。@default "primary" */
+  color?: TypographyColor;
+}
+
+function Link({ className, color = 'primary', ...props }: LinkProps) {
+  return (
+    <a
+      data-slot="link"
+      className={cn(
+        'cursor-pointer text-xs transition-colors',
+        colorClass[color],
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+export { Prose, Title, Paragraph, Text, Link };
+export type {
+  ProseProps,
+  TitleProps,
+  ParagraphProps,
+  TextProps,
+  LinkProps,
+  TypographyColor,
+  CopyableConfig,
+};