@teamix-evo/ui 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/ui",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Source-injected UI components for Teamix Evo (shadcn-based, antd capabilities)",
   "type": "module",
   "files": [
@@ -41,11 +41,12 @@
     "@radix-ui/react-toggle": "^1",
     "@radix-ui/react-toggle-group": "^1",
     "@radix-ui/react-tooltip": "^1",
-    "@storybook/addon-essentials": "^8",
-    "@storybook/react": "^8",
-    "@storybook/react-vite": "^8",
+    "@storybook/addon-docs": "^10.4.1",
+    "@storybook/react": "^10.4.1",
+    "@storybook/react-vite": "^10.4.1",
     "@tailwindcss/vite": "^4",
     "@tanstack/react-table": "^8",
+    "@types/node": "^20.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
@@ -55,6 +56,7 @@
     "date-fns": "^3",
     "embla-carousel-react": "^8",
     "eslint": "^9.0.0",
+    "eslint-plugin-storybook": "10.4.1",
     "input-otp": "^1",
     "lucide-react": "^0.460.0",
     "react": "^18.3.0",
@@ -63,7 +65,7 @@
     "react-hook-form": "^7",
     "react-resizable-panels": "^2",
     "sonner": "^1",
-    "storybook": "^8",
+    "storybook": "^10.4.1",
     "tailwind-merge": "^2.5.0",
     "tailwindcss": "^4",
     "ts-morph": "^22",
@@ -72,9 +74,16 @@
     "vite": "^5.4.0",
     "vite-tsconfig-paths": "^6.1.1",
     "zod": "^3",
-    "@teamix-evo/eslint-config": "0.1.0",
-    "@teamix-evo/registry": "0.2.0",
-    "@teamix-evo/design": "^0.2.0"
+    "@teamix-evo/tokens": "^0.5.0",
+    "@teamix-evo/eslint-config": "0.2.1",
+    "@teamix-evo/registry": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@tanstack/react-virtual": "^3.13.26"
   },
   "scripts": {
     "validate": "tsx scripts/validate-entries.ts",
@@ -84,7 +93,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "build": "echo 'pure resource package, no build needed'",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "gen:theme-overrides": "tsx .storybook/gen-theme-overrides.ts",
+    "storybook": "pnpm gen:theme-overrides && storybook dev -p 6006",
+    "build-storybook": "pnpm gen:theme-overrides && storybook build"
   }
 }

package/src/components/accordion/accordion.meta.md

@@ -1,13 +1,14 @@
 ---
 id: accordion
 name: Accordion
+displayName: 折叠面板
 type: component
-category: navigation
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Accordion
+# Accordion 折叠面板
 
 折叠面板 — Radix Accordion + antd Collapse 的 `accordion` 模式(`type="single"` 即单展开)。
 **与 Collapsible 区别**:Accordion 是**多 item 列表**,可单展开 / 多展开;Collapsible 是单个区域的展开收起。
@@ -78,7 +79,7 @@ import {
   </AccordionItem>
   <AccordionItem value="item-2">
     <AccordionTrigger>如何安装?</AccordionTrigger>
-    <AccordionContent>npx teamix-evo design init opentrek</AccordionContent>
+    <AccordionContent>npx teamix-evo tokens init opentrek</AccordionContent>
   </AccordionItem>
 </Accordion>
 

package/src/components/accordion/accordion.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Accordion,
   AccordionItem,
@@ -7,9 +7,17 @@ import {
 } from './accordion';
 
 const meta: Meta<typeof Accordion> = {
-  title: '导航 · Navigation/Accordion',
+  title: '数据展示 · Data Display/Accordion',
   component: Accordion,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '折叠面板 — Radix Accordion + antd Collapse accordion 模式。支持单展开(collapsible) / 多展开,每项自带 ChevronDown 箭头翻转动画。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -21,14 +29,15 @@ export const Single: Story = {
       <AccordionItem value="item-1">
         <AccordionTrigger>什么是 Teamix Evo?</AccordionTrigger>
         <AccordionContent>
-          面向产品研发场景的 AI Coding 套件,提供设计体系、技能、组件、文档等可装配资产。
+          面向产品研发场景的 AI Coding
+          套件,提供设计体系、技能、组件、文档等可装配资产。
         </AccordionContent>
       </AccordionItem>
       <AccordionItem value="item-2">
         <AccordionTrigger>如何安装?</AccordionTrigger>
         <AccordionContent>
           <code className="rounded bg-muted px-1.5 py-0.5">
-            npx teamix-evo design init opentrek
+            npx teamix-evo tokens init opentrek
           </code>
         </AccordionContent>
       </AccordionItem>
@@ -45,11 +54,7 @@ export const Single: Story = {
 export const Multiple: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Accordion
-      type="multiple"
-      defaultValue={['a', 'b']}
-      className="w-96"
-    >
+    <Accordion type="multiple" defaultValue={['a', 'b']} className="w-96">
       <AccordionItem value="a">
         <AccordionTrigger>分组 A</AccordionTrigger>
         <AccordionContent>分组 A 的内容</AccordionContent>

package/src/components/accordion/accordion.tsx

@@ -4,10 +4,103 @@ import { ChevronDown } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
-const Accordion = AccordionPrimitive.Root;
-export type AccordionProps = React.ComponentPropsWithoutRef<
-  typeof AccordionPrimitive.Root
->;
+// ─── AccordionProps(ADR 0025 合规:显式声明交互 props)─────────────────────
+
+interface AccordionBaseProps {
+  /**
+   * 排列方向(antd 未提供,shadcn 独有扩展) — 竖直为默认手风琴;水平适用 FAQ 横排。
+   * @default "vertical"
+   */
+  orientation?: 'vertical' | 'horizontal';
+  /**
+   * 禁用整组交互(灰化 + 所有 Trigger 不可点)。
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+export interface AccordionSingleProps
+  extends Omit<
+      React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>,
+      | 'type'
+      | 'value'
+      | 'defaultValue'
+      | 'onValueChange'
+      | 'collapsible'
+      | 'orientation'
+      | 'disabled'
+    >,
+    AccordionBaseProps {
+  /**
+   * 模式 — `single` 同时只展开一项(互斥);`multiple` 可展开任意多项。
+   */
+  type: 'single';
+  /**
+   * 受控当前展开 item 的 value(仅 `type="single"` 时为 string)。
+   */
+  value?: string;
+  /**
+   * 非受控初始展开项。
+   * @default ""
+   */
+  defaultValue?: string;
+  /**
+   * 展开状态变化回调(`type="single"` 时返回单个 value string)。
+   */
+  onValueChange?: (value: string) => void;
+  /**
+   * 是否允许全部收起(antd `accordion` 模式下默认不可收起,此属性允许) — 仅 `type="single"` 有效。
+   * @default false
+   */
+  collapsible?: boolean;
+}
+
+export interface AccordionMultipleProps
+  extends Omit<
+      React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root>,
+      | 'type'
+      | 'value'
+      | 'defaultValue'
+      | 'onValueChange'
+      | 'collapsible'
+      | 'orientation'
+      | 'disabled'
+    >,
+    AccordionBaseProps {
+  /**
+   * 模式 — `multiple` 可展开任意多项。
+   */
+  type: 'multiple';
+  /**
+   * 受控当前展开项 value 数组(`type="multiple"` 时为 string[])。
+   */
+  value?: string[];
+  /**
+   * 非受控初始展开项(数组)。
+   * @default []
+   */
+  defaultValue?: string[];
+  /**
+   * 展开状态变化回调(`type="multiple"` 时返回 string[])。
+   */
+  onValueChange?: (value: string[]) => void;
+}
+
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+
+const Accordion = React.forwardRef<
+  React.ElementRef<typeof AccordionPrimitive.Root>,
+  AccordionProps
+>(({ className, ...props }, ref) => (
+  <AccordionPrimitive.Root
+    ref={ref}
+    className={cn(className)}
+    {...(props as React.ComponentPropsWithoutRef<
+      typeof AccordionPrimitive.Root
+    >)}
+  />
+));
+Accordion.displayName = 'Accordion';
 
 const AccordionItem = React.forwardRef<
   React.ElementRef<typeof AccordionPrimitive.Item>,
@@ -15,7 +108,7 @@ const AccordionItem = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <AccordionPrimitive.Item
     ref={ref}
-    className={cn('border-b', className)}
+    className={cn('border-b border-b-border', className)}
     {...props}
   />
 ));
@@ -29,13 +122,16 @@ const AccordionTrigger = React.forwardRef<
     <AccordionPrimitive.Trigger
       ref={ref}
       className={cn(
-        'flex flex-1 items-center justify-between py-4 text-sm font-medium transition-all hover:underline text-left [&[data-state=open]>svg]:rotate-180',
+        'group flex cursor-pointer flex-1 items-center justify-between gap-3 rounded-sm py-4 text-xs font-medium text-left transition-colors',
+        'hover:text-primary focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        '[&[data-state=open]>svg]:rotate-180',
         className,
       )}
       {...props}
     >
       {children}
-      <ChevronDown className="size-4 shrink-0 text-muted-foreground transition-transform duration-200" />
+      <ChevronDown className="size-4 shrink-0 text-muted-foreground transition-transform duration-200 group-hover:text-primary" />
     </AccordionPrimitive.Trigger>
   </AccordionPrimitive.Header>
 ));
@@ -47,7 +143,7 @@ const AccordionContent = React.forwardRef<
 >(({ className, children, ...props }, ref) => (
   <AccordionPrimitive.Content
     ref={ref}
-    className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+    className="overflow-hidden text-xs data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
     {...props}
   >
     <div className={cn('pb-4 pt-0', className)}>{children}</div>

package/src/components/affix/affix.meta.md

@@ -1,13 +1,14 @@
 ---
 id: affix
 name: Affix
+displayName: 固钉
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Affix
+# Affix 固钉
 
 滚动吸顶 / 吸底 — antd 独有补足。**等价 antd `Affix`**。当容器滚出指定偏移时,把 children 切换为 `position: fixed`,保留原占位避免页面跳动。监听 `scroll` 事件 + `getBoundingClientRect()`,无第三方依赖。
 
@@ -24,14 +25,19 @@ package: "@teamix-evo/ui"
 - 弹窗内的吸附 → Drawer / Sheet 已有内置
 - 一页超过 1 个 Affix:容易形成"漂浮屏",有损可读性
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
 | `offsetTop` | `number` | `0` | – | 滚动到此偏移量(相对视口顶部)时开始吸顶,单位 px。 |
 | `offsetBottom` | `number` | – | – | 滚动到此偏移量(相对视口底部)时开始吸底 — 与 `offsetTop` 互斥。 |
+| `container` | `() => HTMLElement \| Window` | `() => window` | – | 滚动容器(antd `target` 并集) — 返回需要监听 `scroll` / `resize` 事件的滚动容器, 默认 `window`。常见场景:在内层 `overflow:auto` 容器(对话框 / 抽屉 / 自定义滚动区)中 让 Affix 跟随该容器滚动,而非主视口。 切到自定义容器后,内部使用 `position: sticky` 由浏览器原生处理"吸附后跟随容器视口顶部" (无需手动算 scrollTop 偏移),容器只需保证未被 `overflow: hidden` 切割。 |
 | `onAffixChange` | `(affixed: boolean) => void` | – | – | 吸附状态变化回调(antd `onChange` 并集)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -53,6 +59,18 @@ _无 — 本组件不依赖任何 npm 包。_
 - **优先用 Tailwind `sticky top-N`** — 大部分"吸附顶部"用 sticky 就够,只有需要"超出容器边界仍跟随视口"才用 Affix
 - **不要让 Affix 包裹复杂动态高度内容** — width / height 是按初次渲染算的,内容剧烈变化会失同步
 - **`zIndex` 默认 10** — 与 Sonner toast(z=9999)、Dialog(z=50)等级别错开;如需更高自行 className 覆盖
+- **`container` 自定义容器时,内部走 `position: sticky`** — 容器只需保证 `overflow: auto/scroll`(不能是 `hidden`),且祖先链不能有 `transform` / `filter` 等限定 stacking context 的属性。无需手动设 `position: relative`(浏览器原生托管)
+- **Storybook 中默认 window 模式不可演示** — Storybook 8 autodocs iframe 不暴露稳定的 window scroll + toolbar globals 不刷新,但**业务真实页面上 `<Affix offsetTop={64}>` 零配置即可工作**;在文档站验证时请用 container 模式(三件 sticky stories 已就位)
+
+## Affix 形态 — 旧库 API → 新库映射
+
+| 旧库 (Teamix 1.0 / antd `Affix`) | 新库 (`@teamix-evo/ui` `Affix`) | 备注 |
+| --- | --- | --- |
+| `offsetTop` | `offsetTop` | 行为一致 |
+| `offsetBottom` | `offsetBottom` | 行为一致;与 `offsetTop` 互斥(同传时 `offsetBottom` 优先) |
+| `onAffix` | `onAffixChange` | 重命名;签名一致 `(affixed: boolean) => void` |
+| `target` | `container` | 重命名;返回 `HTMLElement \| Window`,默认 `window` |
+| `useAbsolute` | — | 不修复 — 内部根据 `container` 是否传入自动切 `fixed`/`absolute` |
 
 ## Examples
 

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

@@ -1,4 +1,5 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Affix } from './affix';
 import { Button } from '@/components/button/button';
 
@@ -6,11 +7,15 @@ 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:
-          '滚动吸顶 / 吸底 — 当容器滚出指定偏移时把 children 切换为 position: fixed,保留原占位。基于 scroll 事件 + getBoundingClientRect。等价 antd `Affix`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '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。',
       },
     },
   },
@@ -23,35 +28,107 @@ const meta: Meta<typeof Affix> = {
 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: () => (
-    <div className="space-y-3">
-      <div className="rounded-md border p-4 text-sm text-muted-foreground">
-        ↓ 在 Storybook 容器内滚动以触发吸顶
-      </div>
-      <div className="h-64 rounded-md border bg-muted/30 p-4">占位 1</div>
-      <Affix offsetTop={0}>
-        <div className="rounded-md border bg-card p-3 shadow-sm">
-          <Button>吸顶按钮</Button>
+  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>
-      </Affix>
-      <div className="h-[800px] rounded-md border bg-muted/30 p-4">长占位</div>
-    </div>
-  ),
+      </div>
+    );
+  },
 };
 
 export const Bottom: Story = {
   parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="space-y-3">
-      <div className="h-[600px] rounded-md border bg-muted/30 p-4">向下滚动</div>
-      <Affix offsetBottom={24}>
-        <div className="rounded-md border bg-card p-3 shadow-sm">
-          <Button block>立即提交(吸底)</Button>
+  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>
-      </Affix>
-      <div className="h-[600px] rounded-md border bg-muted/30 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

@@ -12,17 +12,36 @@ export interface AffixProps extends React.HTMLAttributes<HTMLDivElement> {
    * 滚动到此偏移量(相对视口底部)时开始吸底 — 与 `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`**。
- * 当容器滚出指定偏移时,把 children 切换为 `position: fixed`,保留原占位避免页面跳动。
  *
- * 实现:监听 `scroll` 事件 + 节点 `getBoundingClientRect()`,无依赖。
+ * 实现分两路:
+ * - **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>(
@@ -30,6 +49,7 @@ const Affix = React.forwardRef<HTMLDivElement, AffixProps>(
     {
       offsetTop = 0,
       offsetBottom,
+      container,
       onAffixChange,
       className,
       style,
@@ -41,18 +61,38 @@ const Affix = React.forwardRef<HTMLDivElement, AffixProps>(
     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 });
+    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
-          ? window.innerHeight - rect.bottom < (offsetBottom ?? 0)
-          : rect.top < offsetTop;
+          ? bottom < (offsetBottom ?? 0)
+          : top < offsetTop;
+
         if (shouldAffix !== affixed) {
           setAffixed(shouldAffix);
           onAffixChange?.(shouldAffix);
@@ -61,14 +101,40 @@ const Affix = React.forwardRef<HTMLDivElement, AffixProps>(
       };
 
       compute();
-      window.addEventListener('scroll', compute, { passive: true });
+      target.addEventListener('scroll', compute, { passive: true });
       window.addEventListener('resize', compute);
       return () => {
-        window.removeEventListener('scroll', compute);
+        target.removeEventListener('scroll', compute);
         window.removeEventListener('resize', compute);
       };
-    }, [affixed, offsetBottom, offsetTop, onAffixChange]);
+    }, [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',
@@ -85,7 +151,11 @@ const Affix = React.forwardRef<HTMLDivElement, AffixProps>(
         style={{ ...style, height: affixed ? size.h : undefined }}
         className={className}
       >
-        <div style={fixedStyle} className={cn(affixed && 'shadow-sm')} {...props}>
+        <div
+          style={fixedStyle}
+          className={cn(affixed && 'shadow-sm')}
+          {...props}
+        >
           {children}
         </div>
       </div>