@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/breadcrumb/breadcrumb.meta.md

@@ -10,7 +10,8 @@ package: '@teamix-evo/ui'
 
 # Breadcrumb 面包屑
 
-面包屑 — 纯组合组件 + antd `separator` 自定义并集。
+在多层级页面中显示当前位置并提供回溯路径。默认分隔符 lucide `ChevronRight`,字号 `text-sm`,普通项 `text-muted-foreground` / 当前项 `text-foreground` / 链接 hover 升至 `text-foreground`,能力 = shadcn 原子 ∪ antd `separator`,不收 antd `routes` / `itemRender`。
+
 **与 antd Breadcrumb 的差异**:antd 用 `routes` 数组配置;本组件走 shadcn 的**组合式**(每项手写 `<BreadcrumbItem>`),配 React Router / Next.js Link 时更灵活。
 
 ## When to use
@@ -30,19 +31,9 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-#### Breadcrumb
-
-| 名称        | 类型              | 默认值 | 必填 | 说明                                                                                                                            |
-| ----------- | ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `separator` | `React.ReactNode` | –      | –    | 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`, 通过设置 children 可全局覆盖。 |
-
-#### BreadcrumbLink
-
-| 名称      | 类型      | 默认值 | 必填 | 说明                                                       |
-| --------- | --------- | ------ | ---- | ---------------------------------------------------------- |
-| `asChild` | `boolean` | –      | –    | 用 Slot 渲染为子元素(常配合 React Router / Next.js Link)。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `separator` | `React.ReactNode` | `<ChevronRight />` | – | 自定义全局分隔符(antd `separator` 并集)。仅作类型层占位 — 实际渲染由 `<BreadcrumbSeparator>` 控制,默认 lucide `ChevronRight`, 通过 `<BreadcrumbSeparator>{节点}</BreadcrumbSeparator>` 覆盖单个分隔符。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -50,14 +41,13 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add breadcrumb` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -66,17 +56,36 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add @radix-ui/react-slot@^1.1.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
+- **默认分隔符是箭头**(`ChevronRight`),不要手写 `/` / `>` / `·` 字符 — 需覆盖时传入 `<BreadcrumbSeparator>{customNode}</BreadcrumbSeparator>`
+- **字号走 token**:所有项默认 `text-sm`(14px),不要在业务层覆写 `text-base` / `text-xs`,跨面包屑不一致会破坏顶部导航识别度
+- **颜色走 semantic**:普通项 `text-muted-foreground` / 当前项 `text-foreground` / 链接 hover 升至 `text-foreground`。不要用 `text-primary` / `text-blue-*` 手动上色
 - **当前页用 `BreadcrumbPage`**,不是 `BreadcrumbLink`(语义 + 视觉都不同)
 - **配路由用 `asChild`**:`<BreadcrumbLink asChild><Link to="/x">...</Link></BreadcrumbLink>`
-- **每两项之间必有 Separator**:不要手写 `>` 字符
+- **每两项之间必有 Separator**:不要手写文本分隔
 - **过长路径用 Ellipsis**:超过 4 级时中间收成 `<BreadcrumbEllipsis />`(可配 DropdownMenu 展开完整列表)
 - **路径文字简短**:每段 ≤ 6 字 / 12 字符,过长导致换行视觉破碎
 
+## Breadcrumb 形态 — 旧库 API → 新库映射
+
+旧库(Teamix 1.0 / `@alifd/next`)走数据驱动的 `Breadcrumb.Item` + `maxNode`,新库走 shadcn 的**纯组合**(`BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis`)。下表给出旧库 API 到新库写法的逐项映射。
+
+| 旧库 API | 新库写法 | 备注 |
+| --- | --- | --- |
+| `<Breadcrumb>` 容器 | `<Breadcrumb><BreadcrumbList>...</BreadcrumbList></Breadcrumb>` | 容器 + List 双层是 `nav > ol` 语义,无障碍更准 |
+| `<Breadcrumb.Item link="/x">label</Breadcrumb.Item>` | `<BreadcrumbItem><BreadcrumbLink href="/x">label</BreadcrumbLink></BreadcrumbItem>` | Item 与 Link 拆开,Link 可单独控制 hover / focus 样式 |
+| 末项(当前页) | `<BreadcrumbItem><BreadcrumbPage>label</BreadcrumbPage></BreadcrumbItem>` | `aria-current="page"` 自动注入 |
+| `separator="/"` | `<BreadcrumbSeparator>{customNode}</BreadcrumbSeparator>` | 默认 lucide `ChevronRight`,组件化覆盖更可控 |
+| `maxNode={3}` 自动折叠 | 业务自切片 + `<BreadcrumbEllipsis />` 配 `<DropdownMenu>` 弹出 | 见 `MaxNodeCollapse` Story —— 折叠 UI 完全由你控制(Dropdown / Tooltip / Popover 任选) |
+| `showHiddenItems` 弹层展开 | 同上,用 `<DropdownMenu>` 触发器包 `<BreadcrumbEllipsis />` | — |
+| `popupContainer` / `popupProps` | DropdownMenu 自身的 `modal` / `onOpenChange` | 弹层细节转交 DropdownMenu |
+| `component="span"` 自定义根标签 | 不修复 — 固定 `<nav>`(无障碍语义) | — |
+| `prefix` CSS 前缀 | 不修复 — Tailwind 无 CSS prefix 概念 | — |
+| 路由集成 | `<BreadcrumbLink asChild><Link to="/x">...</Link></BreadcrumbLink>` | shadcn 的 `asChild`(Slot),适配任意路由组件 |
+
 ## Examples
 
 ```tsx

package/src/components/breadcrumb/breadcrumb.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Slash } from 'lucide-react';
 import {
   Breadcrumb,
@@ -9,6 +9,12 @@ import {
   BreadcrumbSeparator,
   BreadcrumbEllipsis,
 } from './breadcrumb';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/dropdown-menu/dropdown-menu';
 
 const meta: Meta<typeof Breadcrumb> = {
   title: '导航 · Navigation/Breadcrumb',
@@ -18,7 +24,7 @@ const meta: Meta<typeof Breadcrumb> = {
     docs: {
       description: {
         component:
-          '面包屑 — 纯组合组件 + antd separator 自定义并集。支持 asChild 配合 React Router / Next.js Link,支持长路径省略(Ellipsis)。',
+          '面包屑 —— 在多层级页面中显示当前位置并提供回溯路径。shadcn 纯组合原子(`Breadcrumb` / `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis`) + 对齐 antd `Breadcrumb` 的 `separator` 自定义并集,差异点是不收 antd `routes` / `itemRender` 数组式 API,改走 children 组合 + `asChild` 适配 React Router / Next.js `<Link>`:`asChild`、`separator`(默认 `ChevronRight`)、`BreadcrumbEllipsis` 折叠。视觉走 OpenTrek semantic tokens,字号 `text-sm`、普通项 `text-muted-foreground`、当前项 `text-foreground`、链接 hover 升至 `text-foreground`,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -48,7 +54,15 @@ export const Default: Story = {
 };
 
 export const CustomSeparator: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '通过 `<BreadcrumbSeparator>` 的 children 覆盖默认 `ChevronRight`,可换为 `Slash` / 文字 / 任意 ReactNode。',
+      },
+    },
+  },
   render: () => (
     <Breadcrumb>
       <BreadcrumbList>
@@ -58,6 +72,12 @@ export const CustomSeparator: Story = {
         <BreadcrumbSeparator>
           <Slash />
         </BreadcrumbSeparator>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/projects">项目</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator>
+          <span>·</span>
+        </BreadcrumbSeparator>
         <BreadcrumbItem>
           <BreadcrumbPage>当前页</BreadcrumbPage>
         </BreadcrumbItem>
@@ -66,8 +86,16 @@ export const CustomSeparator: Story = {
   ),
 };
 
-export const Ellipsis: Story = {
-  parameters: { controls: { disable: true } },
+export const Collapsed: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '层级超过 4 级时使用 `<BreadcrumbEllipsis />` 折叠中间项,避免横向空间撑爆;可叠加 `DropdownMenu` 在悬停时展开完整路径。',
+      },
+    },
+  },
   render: () => (
     <Breadcrumb>
       <BreadcrumbList>
@@ -90,3 +118,90 @@ export const Ellipsis: Story = {
     </Breadcrumb>
   ),
 };
+
+export const MaxNodeCollapse: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '对齐旧库 `maxNode` 自动折叠能力 — 把 `<BreadcrumbEllipsis />` 包到 `<DropdownMenu>` 触发器里,点击 `…` 弹出被折叠层级列表(单击跳转)。组合优于专门 prop:可任意控制弹层位置 / 触发方式 / 自定义弹出 UI。',
+      },
+    },
+  },
+  render: () => {
+    const all = [
+      { label: '首页', href: '/' },
+      { label: 'Whatever', href: '/whatever' },
+      { label: 'All Categories', href: '/all' },
+      { label: "Women's Clothing", href: '/women' },
+      { label: 'Blouses & Shirts', href: '/blouses' },
+    ];
+    const head = all[0]!;
+    const middle = all.slice(1, -1);
+    return (
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href={head.href}>{head.label}</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <DropdownMenu>
+              <DropdownMenuTrigger
+                aria-label="展开折叠层级"
+                className="rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+              >
+                <BreadcrumbEllipsis />
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start">
+                {middle.map((it) => (
+                  <DropdownMenuItem key={it.href} asChild>
+                    <a href={it.href}>{it.label}</a>
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>T-shirts</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    );
+  },
+};
+
+export const WithRouterLink: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '通过 `asChild` 把 `BreadcrumbLink` 替换为路由组件(此处用 `<a>` 演示),保持视觉与无障碍语义一致。',
+      },
+    },
+  },
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/">首页</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/orgs">组织</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>成员管理</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+};

package/src/components/breadcrumb/breadcrumb.tsx

@@ -6,14 +6,19 @@ import { cn } from '@/utils/cn';
 
 export interface BreadcrumbProps extends React.ComponentPropsWithoutRef<'nav'> {
   /**
-   * 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`,
-   * 通过设置 children 可全局覆盖。
+   * 自定义全局分隔符(antd `separator` 并集)。仅作类型层占位 —
+   * 实际渲染由 `<BreadcrumbSeparator>` 控制,默认 lucide `ChevronRight`,
+   * 通过 `<BreadcrumbSeparator>{节点}</BreadcrumbSeparator>` 覆盖单个分隔符。
+   * @default <ChevronRight />
    */
   separator?: React.ReactNode;
 }
 
 const Breadcrumb = React.forwardRef<HTMLElement, BreadcrumbProps>(
-  ({ ...props }, ref) => <nav ref={ref} aria-label="breadcrumb" {...props} />,
+  // separator 仅作 API 占位,不下传到 DOM,避免触发未知属性警告。
+  ({ separator: _separator, ...props }, ref) => (
+    <nav ref={ref} aria-label="breadcrumb" {...props} />
+  ),
 );
 Breadcrumb.displayName = 'Breadcrumb';
 
@@ -24,7 +29,7 @@ const BreadcrumbList = React.forwardRef<
   <ol
     ref={ref}
     className={cn(
-      'flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground sm:gap-2.5',
+      'flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground sm:gap-2.5',
       className,
     )}
     {...props}
@@ -46,7 +51,10 @@ BreadcrumbItem.displayName = 'BreadcrumbItem';
 
 export interface BreadcrumbLinkProps
   extends React.ComponentPropsWithoutRef<'a'> {
-  /** 用 Slot 渲染为子元素(常配合 React Router / Next.js Link)。 */
+  /**
+   * 用 Slot 渲染为子元素(常配合 React Router `<Link>` / Next.js `<Link>`)。
+   * @default false
+   */
   asChild?: boolean;
 }
 
@@ -56,7 +64,10 @@ const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
     return (
       <Comp
         ref={ref}
-        className={cn('transition-colors hover:text-foreground', className)}
+        className={cn(
+          'text-xs text-muted-foreground transition-colors hover:text-foreground',
+          className,
+        )}
         {...props}
       />
     );
@@ -73,7 +84,7 @@ const BreadcrumbPage = React.forwardRef<
     role="link"
     aria-disabled="true"
     aria-current="page"
-    className={cn('font-normal text-foreground', className)}
+    className={cn('text-xs font-normal text-foreground', className)}
     {...props}
   />
 ));
@@ -87,7 +98,10 @@ const BreadcrumbSeparator = ({
   <li
     role="presentation"
     aria-hidden="true"
-    className={cn('[&>svg]:size-3.5', className)}
+    className={cn(
+      'inline-flex items-center text-muted-foreground [&>svg]:size-3.5',
+      className,
+    )}
     {...props}
   >
     {children ?? <ChevronRight />}