@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/affix/affix.stories.tsx

@@ -1,134 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Affix } from './affix';
-import { Button } from '@/components/button/button';
-
-const meta: Meta<typeof Affix> = {
-  title: '导航 · Navigation/Affix',
-  component: Affix,
-  tags: ['autodocs'],
-  // 全局 preview.layout='centered' 会让 iframe 不产生可滚动的 window,
-  // Affix 默认监听 window 时无法触发吸顶。改为 'padded' 让 stories 各自掌控
-  // 内部滚动容器,并统一通过 `container` prop 指向自身,行为可观测、可复现。
-  parameters: {
-    layout: 'padded',
-    docs: {
-      description: {
-        component:
-          'Affix 固钉 —— 在页面滚动超出指定偏移时，把 children 切为 `position: fixed`(默认监听 window) 或 `position: absolute`(传 `container` 时以自定义滚动容器为定位上下文)，同时保留原占位避免页面跳动。**原生 scroll + getBoundingClientRect 实现、无依赖**，**等价 antd `Affix`** 能力(`offsetTop` / `offsetBottom` / `container`(对齐 antd `target`) / `onAffixChange`(对齐 antd `onChange`))，shadcn 未提供对应原子。视觉走 OpenTrek semantic tokens（吸附后 shadow-sm 同 tokens 一致），所有样式来自 `@teamix-evo/tokens`，无 mock。',
-      },
-    },
-  },
-  argTypes: {
-    offsetTop: { control: 'number' },
-  },
-  args: { offsetTop: 0 },
-};
-
-export default meta;
-type Story = StoryObj<typeof Affix>;
-
-/**
- * 在内层容器内吸顶 — Storybook 的 `Docs` / `Canvas` iframe 不一定提供可滚动的 window,
- * 因此所有 Affix Story 都用 `container={() => ref.current}` 把吸附逻辑挂到自身的
- * `overflow:auto` 容器上(容器 `position: relative`,吸附后切 `position: absolute`)。
- * 业务侧最常见用法仍是 `Affix offsetTop={64}`(默认 window),不用传 container。
- */
-export const Playground: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const ref = React.useRef<HTMLDivElement | null>(null);
-    return (
-      <div
-        ref={ref}
-        className="relative h-96 overflow-auto rounded-md border border-border bg-muted/20 p-4"
-      >
-        <div className="flex flex-col gap-3">
-          <div className="rounded-md border border-border bg-card p-4 text-sm text-muted-foreground">
-            ↓ 在本容器内向下滚动以触发吸顶
-          </div>
-          <div className="h-40 rounded-md border border-border bg-card p-4">占位 1</div>
-          <Affix
-            offsetTop={0}
-            container={() => ref.current as HTMLElement}
-            onAffixChange={(a) => console.log('[Playground] affixed:', a)}
-          >
-            <div className="rounded-md border border-border bg-card p-3 shadow-sm">
-              <Button>吸顶按钮</Button>
-            </div>
-          </Affix>
-          <div className="h-[800px] rounded-md border border-border bg-card p-4">长占位</div>
-        </div>
-      </div>
-    );
-  },
-};
-
-export const Bottom: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const ref = React.useRef<HTMLDivElement | null>(null);
-    return (
-      <div
-        ref={ref}
-        className="relative h-96 overflow-auto rounded-md border border-border bg-muted/20 p-4"
-      >
-        <div className="flex flex-col gap-3">
-          <div className="h-[500px] rounded-md border border-border bg-card p-4">向下滚动</div>
-          <Affix offsetBottom={16} container={() => ref.current as HTMLElement}>
-            <div className="rounded-md border border-border bg-card p-3 shadow-sm">
-              <Button block>立即提交(吸底)</Button>
-            </div>
-          </Affix>
-          <div className="h-[500px] rounded-md border border-border bg-card p-4">滚到底</div>
-        </div>
-      </div>
-    );
-  },
-};
-
-export const InContainer: Story = {
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      description: {
-        story:
-          '显式传 `container` 把 Affix 挂到内层 `overflow:auto` 容器(对话框 / 抽屉 / 自定义滚动区) — 容器需 `position: relative`,吸附后元素切 `position: absolute`。',
-      },
-    },
-  },
-  render: () => {
-    const ref = React.useRef<HTMLDivElement | null>(null);
-    return (
-      <div
-        ref={ref}
-        className="relative h-80 overflow-auto rounded-md border border-border bg-muted/20 p-4"
-      >
-        <div className="flex flex-col gap-3">
-          <div className="text-sm text-muted-foreground">
-            ↓ 在内层容器(非 window)中滚动 — Affix 跟随该容器吸顶
-          </div>
-          <div className="h-32 rounded-md border border-border bg-card p-3">占位 1</div>
-          <Affix
-            offsetTop={0}
-            container={() => ref.current as HTMLElement}
-          >
-            <div className="rounded-md border border-border bg-card p-3 shadow-sm">
-              <Button>容器内吸顶</Button>
-            </div>
-          </Affix>
-          <div className="h-[600px] rounded-md border border-border bg-card p-3">长占位</div>
-        </div>
-      </div>
-    );
-  },
-};
-
-// ─── 关于"默认 window 模式"的说明 ─────────────────────────────────────────────
-//
-// 默认形态 `<Affix offsetTop={64}>`(不传 `container`)监听 `window` 并切
-// `position: fixed`,在**真实业务页面上零配置即可工作**。Storybook autodocs 受
-// iframe 限制(共享 canvas 不暴露独立 window scroll;`inline:false` 独立 iframe
-// 又拿不到 toolbar 切换后的 globals.theme,导致主题回退),无法稳定演示该形态;
-// 因此本组件仅在 Storybook 中演示 container 模式(三件 sticky stories),
-// 默认 window 模式以 meta.md 文档 + 业务侧实测为准。

package/src/components/affix/affix.tsx

@@ -1,167 +0,0 @@
-import * as React from 'react';
-
-import { cn } from '@/utils/cn';
-
-export interface AffixProps extends React.HTMLAttributes<HTMLDivElement> {
-  /**
-   * 滚动到此偏移量(相对视口顶部)时开始吸顶,单位 px。
-   * @default 0
-   */
-  offsetTop?: number;
-  /**
-   * 滚动到此偏移量(相对视口底部)时开始吸底 — 与 `offsetTop` 互斥。
-   */
-  offsetBottom?: number;
-  /**
-   * 滚动容器(antd `target` 并集) — 返回需要监听 `scroll` / `resize` 事件的滚动容器,
-   * 默认 `window`。常见场景:在内层 `overflow:auto` 容器(对话框 / 抽屉 / 自定义滚动区)中
-   * 让 Affix 跟随该容器滚动,而非主视口。
-   *
-   * 切到自定义容器后,内部使用 `position: sticky` 由浏览器原生处理"吸附后跟随容器视口顶部"
-   * (无需手动算 scrollTop 偏移),容器只需保证未被 `overflow: hidden` 切割。
-   * @default () => window
-   */
-  container?: () => HTMLElement | Window;
-  /**
-   * 吸附状态变化回调(antd `onChange` 并集)。
-   */
-  onAffixChange?: (affixed: boolean) => void;
-}
-
-const isWindow = (target: HTMLElement | Window): target is Window =>
-  target === window;
-
-/**
- * 滚动吸顶 / 吸底 — antd 独有补足。**等价 antd `Affix`**。
- *
- * 实现分两路:
- * - **window 模式**(不传 `container`):监听 `window` 滚动 + `position: fixed` + 占位高度,
- *   保持页面布局稳定,吸顶后元素脱离文档流跟随视口
- * - **container 模式**(传 `container`):用 `position: sticky` 由浏览器原生托管,
- *   滚动监听仅用于触发 `onAffixChange` 与 `shadow-sm` 视觉反馈;
- *   容器需保证非 `overflow: hidden`(`overflow: auto/scroll` 即可),
- *   且祖先链中不能有 `transform` / `filter` 等 stacking context 限定
- *
- * **务必慎用** — 滥用 Affix 会让页面充满浮动元素,通常一页 ≤ 1 个。
- */
-const Affix = React.forwardRef<HTMLDivElement, AffixProps>(
-  (
-    {
-      offsetTop = 0,
-      offsetBottom,
-      container,
-      onAffixChange,
-      className,
-      style,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    const wrapperRef = React.useRef<HTMLDivElement | null>(null);
-    React.useImperativeHandle(ref, () => wrapperRef.current as HTMLDivElement);
-    const [affixed, setAffixed] = React.useState(false);
-    const [size, setSize] = React.useState<{ w: number; h: number }>({
-      w: 0,
-      h: 0,
-    });
-
-    React.useEffect(() => {
-      const el = wrapperRef.current;
-      if (!el) return;
-
-      const target = container ? container() : window;
-      const useCustomContainer = !isWindow(target);
-
-      const compute = () => {
-        const rect = el.getBoundingClientRect();
-        const useBottom = typeof offsetBottom === 'number';
-
-        let top: number;
-        let viewport: number;
-        if (useCustomContainer) {
-          const cRect = (target as HTMLElement).getBoundingClientRect();
-          top = rect.top - cRect.top;
-          viewport = cRect.height;
-        } else {
-          top = rect.top;
-          viewport = window.innerHeight;
-        }
-
-        const bottom = viewport - (top + rect.height);
-        const shouldAffix = useBottom
-          ? bottom < (offsetBottom ?? 0)
-          : top < offsetTop;
-
-        if (shouldAffix !== affixed) {
-          setAffixed(shouldAffix);
-          onAffixChange?.(shouldAffix);
-        }
-        setSize({ w: rect.width, h: rect.height });
-      };
-
-      compute();
-      target.addEventListener('scroll', compute, { passive: true });
-      window.addEventListener('resize', compute);
-      return () => {
-        target.removeEventListener('scroll', compute);
-        window.removeEventListener('resize', compute);
-      };
-    }, [affixed, offsetBottom, offsetTop, onAffixChange, container]);
-
-    // ─── Container 模式:position: sticky 由浏览器原生托管 ─────────────────────
-    if (container) {
-      const stickyStyle: React.CSSProperties = {
-        position: 'sticky',
-        top: typeof offsetBottom === 'number' ? undefined : offsetTop,
-        bottom: typeof offsetBottom === 'number' ? offsetBottom : undefined,
-        zIndex: 10,
-        ...style,
-      };
-      return (
-        <div
-          ref={wrapperRef}
-          style={stickyStyle}
-          className={cn(
-            'transition-shadow',
-            affixed && 'shadow-sm',
-            className,
-          )}
-          {...props}
-        >
-          {children}
-        </div>
-      );
-    }
-
-    // ─── Window 模式:position: fixed + 占位高度 ─────────────────────────────
-    const fixedStyle: React.CSSProperties | undefined = affixed
-      ? {
-          position: 'fixed',
-          top: typeof offsetBottom === 'number' ? undefined : offsetTop,
-          bottom: typeof offsetBottom === 'number' ? offsetBottom : undefined,
-          width: size.w,
-          zIndex: 10,
-        }
-      : undefined;
-
-    return (
-      <div
-        ref={wrapperRef}
-        style={{ ...style, height: affixed ? size.h : undefined }}
-        className={className}
-      >
-        <div
-          style={fixedStyle}
-          className={cn(affixed && 'shadow-sm')}
-          {...props}
-        >
-          {children}
-        </div>
-      </div>
-    );
-  },
-);
-Affix.displayName = 'Affix';
-
-export { Affix };

package/src/components/alert/alert.meta.md

@@ -1,132 +0,0 @@
----
-id: alert
-name: Alert
-displayName: 警告提示
-type: component
-category: feedback
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Alert 警告提示
-
-静态提示条 — shadcn 简约视觉 + antd 的 `showIcon / closable / banner` 并集。在 [ADR 0021](../../../../docs/adr/0021-semantic-color-api-unification.md) 六档语义色基础上,为内联信息提示专门補上 `neutral`(中性灰,纯文本提示),合计六档 `color`:`primary | info | success | warning | destructive | neutral`。
-**inline 形态**,与对话框 / Toast 不同,常驻在页面上方或表单上方。视觉走 OpenTrek tokens —— **无边框、靠 `*-subtle` 浅底块与卡片底色对比分界、面性(filled) 状态图标**。
-
-## When to use
-
-- 表单提交前的提示(必填项 / 操作不可逆)
-- 页面级公告(banner 模式)
-- 长任务的状态提示(开始 / 进行中 / 失败)
-
-## When NOT to use
-
-- 短暂提示 → 用 `Sonner`(Toast,自动消失)
-- 阻断式确认 → 用 `AlertDialog`
-- 表单字段错误 → 字段下方 `<p className="text-destructive text-sm">...</p>`
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `color` | `'primary' \| 'info' \| 'success' \| 'warning' \| 'destructive' \| 'neutral'` | `"primary"` | – | 语义色 — 控制配色与默认图标。 - `primary` 主色(默认,中性提示) - `info` 信息蓝(强调"知会"语义) - `success` 成功 - `warning` 警告 - `destructive` 错误(对齐 ADR 0021,禁用 `error` / `danger` 别名) - `neutral` 中性灰(纯文本提示,不带语义压力) |
-| `showIcon` | `boolean` | `true` | – | 是否显示图标(antd `showIcon` 并集)。 |
-| `closable` | `boolean` | `false` | – | 是否可关闭,显示右侧 X 按钮(antd `closable` 并集)。 |
-| `onClose` | `() => void` | – | – | 关闭按钮点击回调。 |
-| `banner` | `boolean` | `false` | – | Banner 模式 — 去除横向圆角,沿屏幕宽度铺满,常用于全局公告条。 |
-| `title` | `React.ReactNode` | – | – | 标题(粗体行)。 |
-| `description` | `React.ReactNode` | – | – | 描述(标题下方主体内容)。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add alert` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **`color` 反映业务语义**:`destructive` 仅用于真正错误,**不要**滥用红色制造紧张感;一般提示用 `primary` / `info`,纯文本提示用 `neutral`(不带语义压力)
-- **`info` vs `primary`**:`info` 强调"知会"(蓝色信息脚本),`primary` 强调"引导"(主色/品牌色);遵循 OpenTrek tokens 语义,不要随意互换
-- **`title` + `description` 一对**:无 title 直接 description 是反模式(仅 `description` 可用于表单内提示);一个 Alert 至少要有 title 让用户判断重要性
-- **`closable` 配 `onClose` 持久化**:用户关闭后下次刷新别再出现 — 用 localStorage 记忆
-- **`banner` 模式只放页面顶部**:不要在卡片内 banner
-- **不嵌套 button 链接**:Alert 内放交互链接用 `<a className="underline">`,不要塞 Button — 视觉过重
-- **不要手动加边框**:`border-0` 是刚性规范,透过 `className` 加 `border` 会与克制美学冲突;需要分隔请换用 `Card` 或依赖页面间距
-- **面性图标不可覆盖**:组件已统一处理 lucide `CircleCheck` / `TriangleAlert` / `CircleX` / `Info` 的 `fill-* + text-*-foreground` 组合,顺着语义色自动切换;不要在 `children` 里手写 svg 覆盖
-
-## Examples
-
-```tsx
-import { Alert } from '@/components/ui/alert';
-
-// 基本
-<Alert color="primary" title="提示" description="数据将在 10 分钟后刷新。" />
-
-// 信息蓝(新 —— 强调知会语义)
-<Alert color="info" title="新功能上线" description="试试新版本的智能搜索。" />
-
-// 成功
-<Alert color="success" title="保存成功" />
-
-// 警告 + 可关闭
-<Alert color="warning" title="账号即将过期" description="请在 7 天内续费。" closable />
-
-// 错误
-<Alert color="destructive" title="提交失败" description="请检查网络连接后重试。" />
-
-// 中性(新 —— 纯文本提示,不带语义压力)
-<Alert color="neutral" title="说明" description="该功能仅对管理员开放。" />
-
-// 仅描述(无标题)
-<Alert color="info" description="操作完成后请刷新页面。" />
-
-// 无图标
-<Alert color="primary" showIcon={false} description="纯文本提示" />
-
-// Banner 全局公告
-<Alert
-  color="warning"
-  banner
-  title="系统维护"
-  description="本站将于 02:00 起暂停服务 30 分钟。"
-  closable
-/>
-```
-
----
-
-## Alert 形态 — 旧库 Message(inline) → 新映射
-
-> 旧库 `Message shape='inline'` → 新库 `Alert`(独立组件)。
-> 旧库命令式 toast 部分请看 `sonner` 组件的形态映射。
-
-### 命名映射
-
-| 旧库                                    | 新库                            | 说明                |
-| --------------------------------------- | ------------------------------- | ------------------- |
-| `Message shape='inline' type='success'` | `<Alert color="success" />`     | type → color        |
-| `Message shape='inline' type='error'`   | `<Alert color="destructive" />` | error → destructive |
-| `Message shape='inline' type='warning'` | `<Alert color="warning" />`     | 直接映射            |
-| `Message shape='inline' type='notice'`  | `<Alert color="info" />`        | notice → info       |
-| `closeable`                             | `closable`                      | 拼写修正            |
-| `title + children`                      | `title + description`           | prop 更名           |

package/src/components/alert/alert.stories.tsx

@@ -1,138 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Alert } from './alert';
-
-const meta: Meta<typeof Alert> = {
-  title: '反馈 · Feedback/Alert',
-  component: Alert,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '警告提示 —— 在不打断用户操作的前提下,inline 形态展示重要信息(提示 / 公告 / 错误)。能力对齐 antd `Alert` 并集(`showIcon` / `closable` / `banner`),六档语义色 `primary | info | success | warning | destructive | neutral` 对齐 ADR 0021 与 OpenTrek tokens,**无边框**,依靠 `*-subtle` 浅底块与卡片底色对比,搭配面性(filled)状态图标。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
-      },
-    },
-  },
-  argTypes: {
-    color: {
-      control: 'select',
-      options: [
-        'primary',
-        'info',
-        'success',
-        'warning',
-        'destructive',
-        'neutral',
-      ],
-    },
-    showIcon: { control: 'boolean' },
-    closable: { control: 'boolean' },
-    banner: { control: 'boolean' },
-    title: { control: 'text' },
-    description: { control: 'text' },
-  },
-  args: {
-    color: 'primary',
-    showIcon: true,
-    closable: false,
-    banner: false,
-    title: '提示',
-    description: '数据将在 10 分钟后刷新。',
-  },
-  decorators: [
-    (Story) => (
-      <div className="w-96">
-        <Story />
-      </div>
-    ),
-  ],
-};
-
-export default meta;
-type Story = StoryObj<typeof Alert>;
-
-export const Playground: Story = {};
-
-/**
- * 六档语义色 —— 对齐 ADR 0021 + Alert 专有 `neutral`(纯文本提示)。
- * 全部使用面性图标,卡片无边框、靠浅底块分界。
- */
-export const Colors: Story = {
-  parameters: { controls: { disable: true } },
-  decorators: [(Story) => <div className="w-96">{Story()}</div>],
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Alert color="primary" title="主色提示" description="数据将在 10 分钟后刷新。" />
-      <Alert color="info" title="信息" description="新功能已上线,试试看。" />
-      <Alert color="success" title="成功" description="所有更改已生效。" />
-      <Alert color="warning" title="警告" description="账号 7 天后过期。" />
-      <Alert
-        color="destructive"
-        title="错误"
-        description="提交失败,请检查网络后重试。"
-      />
-      <Alert color="neutral" title="说明" description="该功能仅对管理员开放。" />
-    </div>
-  ),
-};
-
-/**
- * 仅描述(无标题) —— 极简形态,常用于表单内提示。
- */
-export const DescriptionOnly: Story = {
-  parameters: { controls: { disable: true } },
-  decorators: [(Story) => <div className="w-96">{Story()}</div>],
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <Alert color="info" description="操作完成后请刷新页面以查看最新结果。" />
-      <Alert color="neutral" description="提示:Cmd+S 可以快速保存。" />
-    </div>
-  ),
-};
-
-/**
- * 无图标 —— 纯文本提示形态。
- */
-export const NoIcon: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <Alert
-      color="primary"
-      showIcon={false}
-      title="纯文本提示"
-      description="不显示状态图标,文字密度更高。"
-    />
-  ),
-};
-
-/**
- * 可关闭 —— 右上角 X 按钮,关闭时触发 `onClose`。
- */
-export const Closable: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <Alert
-      color="warning"
-      title="账号即将过期"
-      description="请在 7 天内续费,以免影响服务。"
-      closable
-    />
-  ),
-};
-
-/**
- * Banner 模式 —— 横向铺满、无圆角,常用于页面顶部全局公告。
- */
-export const Banner: Story = {
-  parameters: { controls: { disable: true } },
-  decorators: [(Story) => <div className="w-[600px]">{Story()}</div>],
-  render: () => (
-    <Alert
-      color="warning"
-      banner
-      title="系统维护"
-      description="本站将于 02:00 起暂停服务 30 分钟。"
-      closable
-    />
-  ),
-};