# 瑚琏 Hulian (`@hulianui/ui`) — 全量组件使用文档

> 颜值 + 好用的 React 设计系统（Base UI + Tailwind v4 + Motion） · v0.5.0 · 353 个组件文档（自包含，供 AI 一次性消费）

安装 `npm i @hulianui/ui @hulianui/tokens`（tokens 提供主题 CSS，必装）；所有组件从根 barrel 导入 `import { X } from "@hulianui/ui"`。


# ━━━━━━━━ 布局 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# AdminLayout

> 中后台骨架 · 侧栏(品牌+NavMenu可折叠) + 顶栏(折叠/面包屑/扩展区) + 多页签导航(开/切/关·关闭其他/全部·受控接路由或菜单点击自动维护) + 内容区(复用 NavMenu/ScrollArea/Popover·企业应用外壳) · layout/container

## 何时用

要快速搭一个完整中后台外壳——侧栏菜单 + 顶栏 + 多页签 keep-alive 导航开箱即用——用 AdminLayout，只需喂 `menuItems` 和 `children`。若想自己掌控每一块布局（不要内置页签逻辑、要更原子的拼装），下沉到 [Layout](https://hulianui.haloritual.com/components/layout)。

## 导入
```ts
import { AdminLayout } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| menuItems* | `NavMenuNode[]` | — | 侧边菜单数据（复用 NavMenu）。 |
| selectedKey | `string` | — | 受控菜单选中 key。 |
| defaultSelectedKey | `string` | — | 非受控初始选中 key。 |
| openKeys | `string[]` | — | 受控展开的子菜单 key。 |
| defaultOpenKeys | `string[]` | — | 非受控初始展开。 |
| collapsed | `boolean` | — | 受控侧栏折叠态。 |
| defaultCollapsed | `boolean` | — | 非受控初始折叠态。 |
| showTabs | `boolean` | `true` | 是否显示多页签条。 |
| tabs | `AdminTab[]` | — | 受控页签列表；不传则由菜单点击自动维护（非受控）。 |
| activeKey | `string` | — | 受控当前激活页签 key。 |
| defaultActiveKey | `string` | — | 非受控初始激活页签（亦决定首屏自动打开的页签）。 |
| fitViewport | `boolean` | `true` | 是否自占满视口高度。整页应用骨架保持 true（固定 100dvh、内容区内部滚动）；嵌入有固定高度的容器预览时置 false，改用 `h-full` 跟随父容器。 |
| className | `string` | — | 根容器类名。 |
| contentClassName | `string` | — | 内容区类名。 |

`AdminTab`：`{ key: string; label: ReactNode; closable?: boolean }`，`closable` 缺省为「打开页签 >1 时可关，最后一个不可关」。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onMenuSelect | `(key: string, item: NavMenuItem) => void` | 点击菜单叶子项触发。 |
| onOpenChange | `(openKeys: string[]) => void` | 子菜单展开变化回调。 |
| onCollapsedChange | `(collapsed: boolean) => void` | 侧栏折叠变化回调。 |
| onTabChange | `(key: string) => void` | 切换页签回调。 |
| onTabClose | `(key: string) => void` | 关闭页签回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 主内容（当前激活页内容，由上层按 activeKey 决定）。 |
| logo | `ReactNode` | 品牌区（展开态）。 |
| logoCollapsed | `ReactNode` | 品牌区（收起态，默认复用 logo）。 |
| breadcrumb | `ReactNode` | 顶栏面包屑区。 |
| headerExtra | `ReactNode` | 顶栏右侧扩展区（用户菜单 / 通知 / 主题切换等）。 |

## 示例
```tsx
const [active, setActive] = useState("dashboard");

<AdminLayout
  menuItems={menu}
  logo={<span className="font-bold text-primary">瑚琏 Admin</span>}
  logoCollapsed={<span className="font-bold text-primary">瑚</span>}
  defaultActiveKey="dashboard"
  defaultSelectedKey="dashboard"
  defaultOpenKeys={["users"]}
  onTabChange={setActive}
  breadcrumb={<span className="text-sm text-muted">首页 / {active}</span>}
  headerExtra={<Avatar fallback="瑚" />}
>
  <Page k={active} />
</AdminLayout>
```

## 禁忌 / 坑

- **`fitViewport` 决定撑高方式**：整页用默认 `true`（自钉 100dvh），别再外面套 `h-dvh` wrapper；嵌入文档示例卡等固定高度容器时务必传 `false`，否则整页滚动而非内容区滚动。详见 [[hulian-adminlayout-fitviewport]]。
- **页签受控/非受控二选一**：不传 `tabs` 时页签由菜单点击自动维护（非受控）；一旦传 `tabs` 即受控，须自行配 `onTabChange`/`onTabClose` 维护数组与 `activeKey`。
- `children` 只渲染「当前激活页」，keep-alive 的多页内容缓存需上层按 `activeKey` 自行管理，组件不替你缓存各页 DOM。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)

<!-- ════════════════════════════════════════════════════════ -->
# AspectRatio

> 比例容器 · CSS aspect-ratio 锁宽高比 + 图片/视频自动铺满(零依赖·RSC) · layout/container

## 何时用

要把图片/视频/卡片锁成固定宽高比（16/9、1/1、4/3）、随宽度自适应高度且不抖动时用。它只锁比例（纯 CSS、可 RSC）；要按容器宽度重排布局用 [Viewport](https://hulianui.haloritual.com/components/viewport)，要把固定设计稿等比缩放铺满用 [FitScreen](https://hulianui.haloritual.com/components/fit-screen)。

## 导入
```ts
import { AspectRatio } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| ratio | `number` | `1` | 宽高比（宽 / 高），如 `16/9`、`1`、`4/3`。 |

继承 `HTMLAttributes<HTMLDivElement>`。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子元素（通常 img/video），自动铺满容器。 |

## 示例
```tsx
// 16:9 媒体容器，宽度由外层决定，高度自动
<div className="w-64">
  <AspectRatio ratio={16 / 9}>
    <img src="..." alt="..." />
  </AspectRatio>
</div>
```

```tsx
// 1:1 头像/缩略图
<div className="w-40">
  <AspectRatio ratio={1}>
    <Fill label="1 / 1" />
  </AspectRatio>
</div>
```

## 禁忌 / 坑

- **`ratio` 是数字不是字符串**：传 `16 / 9` 这种除式或 `1.7778`，不要传 `"16/9"`。
- **宽度由外层给**：容器宽度自适应父级，高度据 ratio 推导；外层不限宽时会撑满可用宽度。子元素无需自己写 `w-full h-full`，组件已让其铺满。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)

<!-- ════════════════════════════════════════════════════════ -->
# Container

> 内容容器 · 限制最大宽度(sm/md/lg/xl/full) + 居中 + 左右安全内距 + as 多态(收口全站 mx-auto max-w-Nxl px-6 样板·零依赖·RSC) · layout/container

## 何时用

页面/区块需要限制内容最大宽度并水平居中、留出左右安全内距时用 Container——收口全站重复的 `mx-auto max-w-Nxl px-6` 样板。它只管宽度约束与居中，不排列子项；子项的方向/间距交给 [Layout](https://hulianui.haloritual.com/components/layout) 或 Stack。需要整页骨架（侧栏+顶栏+多页签）用 [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)。

## 导入
```ts
import { Container } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"xl"` | 最大宽度档：sm=2xl / md=3xl / lg=4xl / xl=5xl / full=不限 |
| padded | `boolean` | `true` | 是否水平居中并加左右安全内距 |
| as | `ElementType` | `"div"` | 渲染标签（语义/布局解耦，如 section/main/article） |

其余 `HTMLAttributes<HTMLElement>` 属性（className/style 等）透传。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子内容 |

## 示例
```tsx
// 各档最大宽度
<Container size="lg">
  <Box>内容限制在 4xl 宽度内并居中</Box>
</Container>

// 用语义标签承载
<Container as="main" size="xl">
  {children}
</Container>
```

## 禁忌 / 坑

暂无已知坑。`size` 档位映射的是 Tailwind `max-w-*`（sm=2xl 而非 sm），勿按字面理解。候选坑列表（affix/dialog-portal/dnd-kit/flex-mx-auto/recharts/scrollspy/sticky-glass/vant-toast）均为各自具体场景的容器问题，与本通用宽度容器无直接关系，已剔除。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)

<!-- ════════════════════════════════════════════════════════ -->
# Divider

> 带文字分隔 · orientation 左/中/右 + dashed/plain + 行内垂直(纯皮肤·零依赖·RSC·与 Separator 互补) · layout/arrange

## 何时用

需要在分隔线中嵌入文字标题（如「最近更新」「更多」），或要虚线样式、行内竖线时用 Divider。纯几何分隔、无文字、要 ARIA `role="separator"` 语义则用 [Separator](https://hulianui.haloritual.com/components/separator)——二者互补：Divider 偏内容装饰，Separator 偏结构语义。

## 导入
```ts
import { Divider } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| type | `"horizontal" \| "vertical"` | `"horizontal"` | 方向。vertical 为行内分隔（嵌在一行文本/元素之间） |
| orientation | `"left" \| "center" \| "right"` | `"center"` | 嵌入文字的水平位置（仅 horizontal + 有文字时生效） |
| dashed | `boolean` | `false` | 虚线 |
| plain | `boolean` | `false` | 文字常规字重（默认加粗一档） |
| className | `string` | — | 额外类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 嵌入分隔线中的文字；不传则为纯分隔线 |

## 示例
```tsx
// 纯分隔线
<p>上段内容</p>
<Divider />
<p>下段内容</p>

// 带文字 + 偏左
<Divider orientation="left">最近更新</Divider>

// 行内竖线
<div className="flex items-center">
  <span>文档</span>
  <Divider type="vertical" />
  <span>组件</span>
</div>
```

## 禁忌 / 坑

暂无已知坑。`orientation` 仅在 `type="horizontal"` 且有 children 时生效；`type="vertical"` 用作行内竖线，需放在 flex 行内且依赖父级行高。

## 相关
[Stack](https://hulianui.haloritual.com/components/stack) · [Grid](https://hulianui.haloritual.com/components/grid) · [Spacer](https://hulianui.haloritual.com/components/spacer) · [Separator](https://hulianui.haloritual.com/components/separator) · [Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)

<!-- ════════════════════════════════════════════════════════ -->
# FitScreen

> 大屏适配 · 固定设计尺寸(默认 1920×1080)等比缩放铺满父容器并居中 + fit/cover/stretch 三模式(纯函数 computeFit 可测·ResizeObserver 监听·SSR 安全·数据可视化大屏刚需) · layout/container

## 何时用

按固定设计稿（如 1920×1080）画好的大屏内容，要整体等比缩放铺满任意父容器并居中时用——典型是数据可视化驾驶舱。它缩放的是「固定设计尺寸」；要按容器宽度重排（不缩放、内容自适应）用 [Viewport](https://hulianui.haloritual.com/components/viewport)，只锁单元素宽高比用 [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)。

## 导入
```ts
import { FitScreen, computeFit } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| designWidth | `number` | `1920` | 设计稿宽。 |
| designHeight | `number` | `1080` | 设计稿高。 |
| mode | `"fit" \| "cover" \| "stretch"` | `"fit"` | fit=取 min(等比不裁切，四周可能留黑边)；cover=取 max(等比铺满，可能裁切)；stretch=非等比拉满(可能变形)。 |
| className | `string` | — | 外层容器类名。 |

`computeFit(input: FitInput)`：纯函数（`{ outerW, outerH, designW, designH, mode }` → 缩放结果），可单测，组件内部据 ResizeObserver 测量后调用它。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 你的固定设计尺寸大屏内容。 |

## 示例
```tsx
// 1920×1080 驾驶舱，等比不裁切铺满父容器
<FitScreen designWidth={1920} designHeight={1080} mode="fit">
  {/* 你的大屏内容，按 1920×1080 绝对布局 */}
</FitScreen>
```

```tsx
// 铺满不留黑边（可能裁切边缘）
<FitScreen mode="cover">
  <DesignBoard />
</FitScreen>
```

## 禁忌 / 坑

- **内部用 transform: scale 缩放**：headless/CDP 截图工具下，缩放后的几何坐标可能与真实点击错位，验证视觉/交互需注意（参见 [[recharts-headless-screenshot-blank-clippath-animation-starved]]、[[turbopack-dev-cold-route-blank-cdp-screenshot-warm-first]] 这类 headless 验证坑），FitScreen 下真实 click 失准时改用 `dispatchEvent`。
- **ref + style 写入的脱档崩溃**：组件在 effect 里向 ref 写 transform，遇 StrictMode 双挂载/`<Activity>`/Offscreen 重连时 `ref.current` 可能 truthy 但 `.style` 已脱档而崩 —— 见 [[react-offscreen-reconnect-detached-ref-style-crash]]，写前应 `if (!el?.style) return` 把守。
- 设计稿尺寸（designWidth/Height）须与 children 的实际绝对布局尺寸一致，否则缩放比算错、内容溢出或留白。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)

<!-- ════════════════════════════════════════════════════════ -->
# Grid

> 栅格布局 · grid 原语 cols/gap + GridItem 跨列跨行(零依赖·RSC) · layout/arrange

## 何时用

需要二维行列对齐——固定列数、卡片网格、跨列跨行的局部布局时用 Grid，配 GridItem 控制单元的 `colSpan`/`rowSpan`。只需单轴线性排列（一行或一列）用 [Stack](https://hulianui.haloritual.com/components/stack) 更轻；只想插入定向留白用 [Spacer](https://hulianui.haloritual.com/components/spacer)。

## 导入
```ts
import { Grid, GridItem } from "@hulianui/ui"
```

## Props

### Grid

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| cols | `number \| ResponsiveCols` | `1` | 列数。数字=固定列数（任意值，走 inline style）；`{base,sm,md,lg}`=响应式（静态类） |
| rows | `number` | — | 行数（不填则按内容自动） |
| gap | `number` | `0` | 行列间距（× 0.25rem） |
| colGap | `number` | — | 列间距，覆盖 gap（× 0.25rem） |
| rowGap | `number` | — | 行间距，覆盖 gap（× 0.25rem） |
| inline | `boolean` | `false` | 用 inline-grid 而非 grid |
| as | `ElementType` | `"div"` | 渲染的元素标签 |

### GridItem

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colSpan | `number` | — | 跨列数 |
| rowSpan | `number` | — | 跨行数 |
| as | `ElementType` | `"div"` | 渲染的元素标签 |

两者其余 `HTMLAttributes<HTMLElement>` 属性透传。

## Slots

### Grid

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子元素 |

### GridItem

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子元素 |

## 示例
```tsx
// 3 列等宽网格
<Grid cols={3} gap={3} className="w-72">
  {["1", "2", "3", "4", "5", "6"].map((n) => <Box key={n}>{n}</Box>)}
</Grid>

// 跨列
<Grid cols={3} gap={3}>
  <GridItem colSpan={2}><Box>跨 2 列</Box></GridItem>
  <Box>3</Box>
</Grid>
```

## 禁忌 / 坑

暂无已知坑。`cols` 传数字走 inline style 支持任意列数；传 `{base,sm,md,lg}` 才走静态响应式类。候选坑 body-grid-place-items-center / grid-card-button-tail-row / nested-collapsible-css-grid-rows 均针对各自具体布局场景，与本通用栅格原语无直接关系，已剔除。

## 相关
[Stack](https://hulianui.haloritual.com/components/stack) · [Spacer](https://hulianui.haloritual.com/components/spacer) · [Divider](https://hulianui.haloritual.com/components/divider) · [Separator](https://hulianui.haloritual.com/components/separator) · [Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)

<!-- ════════════════════════════════════════════════════════ -->
# Layout

> 整页布局 · 复合 Header/Sider/Content/Footer + Sider 可折叠(受控/断点/trigger) + 宽度过渡(零依赖·尽量 RSC·复用 ScrollArea) · layout/container

## 何时用

需要 Header/Sider/Content/Footer 这种通用页面骨架、且自己掌控菜单与页签逻辑时用 Layout（更原子、更自由）。若要开箱即用的中后台外壳（品牌 + NavMenu + 多页签 keep-alive 已内置），直接用 [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)，它就是基于本组件的成品装配。

## 导入
```ts
import { Layout, LayoutHeader, LayoutSider, LayoutContent, LayoutFooter } from "@hulianui/ui"
```

## Props

### Layout（也可用 `Layout.Sider` 等点访问）
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| hasSider | `boolean` | 自动探测 | 强制横向(含侧栏)布局。缺省按直接子元素是否含 `Layout.Sider` 判定：含则横向 row，否则纵向 col。异步/条件渲染 Sider 时用它兜底。 |

继承 `HTMLAttributes<HTMLDivElement>`。

### LayoutHeader
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sticky | `boolean` | `false` | 吸顶（sticky top-0）。 |

### LayoutSider
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number` | `240` | 展开态宽度（px）。 |
| collapsedWidth | `number` | `64` | 收起态宽度（px），留出 icon-only 菜单。 |
| collapsible | `boolean` | `false` | 是否可折叠（显示底部 trigger 折叠按钮）。 |
| collapsed | `boolean` | — | 受控收起态。传入即受控，须配合 onCollapse 回写。 |
| defaultCollapsed | `boolean` | `false` | 非受控初始收起态。 |
| breakpoint | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| number` | — | 响应式断点：视口 ≤ 该宽度自动收起，> 时展开。 |

### LayoutContent / LayoutFooter
纯 `HTMLAttributes<HTMLElement>`，无专属 prop。

## Events

### LayoutSider
| 事件 | 类型 | 说明 |
|------|------|------|
| onCollapse | `(collapsed: boolean, type: "clickTrigger" \| "responsive") => void` | 收起态变化回调（点 trigger 或命中断点时触发）。 |

## Slots

### LayoutSider
| 插槽 | 类型 | 说明 |
|------|------|------|
| trigger | `ReactNode` | 底部折叠触发器内容。`undefined`=默认 chevron；`null`=不渲染触发器（即便 collapsible）；传节点=自定义触发器内容（仍由本件包裹为可点按钮）。 |

## 示例
```tsx
// 经典：左 Sider（可折叠）+ 右(Header 顶 / Content 中 / Footer 底)
<Layout>
  <Layout.Sider collapsible>
    {/* 品牌 + 菜单 */}
  </Layout.Sider>
  <Layout>
    <Layout.Header sticky>顶栏</Layout.Header>
    <Layout.Content>内容</Layout.Content>
    <Layout.Footer>底栏</Layout.Footer>
  </Layout>
</Layout>
```

```tsx
// 受控折叠：自管 collapsed，trigger/断点回写本地态后驱动菜单 mode
function Shell() {
  const [collapsed, setCollapsed] = useState(false);
  return (
    <Layout.Sider
      collapsible
      collapsed={collapsed}
      breakpoint="md"
      onCollapse={(c) => setCollapsed(c)}
    >
      <NavMenu items={menu} mode={collapsed ? "collapsed" : "inline"} />
    </Layout.Sider>
  );
}
```

## 禁忌 / 坑

- **受控/非受控二选一**：`Layout.Sider` 传了 `collapsed` 即进入受控，必须配 `onCollapse` 回写，否则 trigger/断点点了不动；只想非受控用 `defaultCollapsed`。
- **横/纵布局靠子元素探测**：嵌套子 `Layout` 是否横排取决于其直接子是否含 `Layout.Sider`。Sider 异步/条件渲染、或被包装进自定义组件（如 `<AppSider/>` 内部才渲染 `Layout.Sider`）时探测会落空，须显式给 `hasSider`。
- 收起态切窄宽用菜单的 `mode="collapsed"`（dogfood NavMenu 自带 icon-only 轨），不要手搓「窄宽裁切 label」。

## 相关
[AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)

<!-- ════════════════════════════════════════════════════════ -->
# Masonry

> 瀑布流布局 · 确定性 round-robin 分列(item[i]→第 i%列·SSR 安全·顺序稳定·非 CSS columns 抖动) + 响应式列数(base/sm/md/lg·首帧 base 防 hydration mismatch·挂载后 matchMedia 调整) + 列内外统一 gap(泛型·token 主题) · layout/container

## 何时用

要把一组不等高卡片（图片墙、动态流、产物画廊）铺成参差瀑布流、且要 SSR 安全 + 顺序稳定时用。它走确定性 round-robin 分列（非原生 CSS columns），避免填谷重排导致的顺序脱节与 hydration mismatch。要等比锁单元素用 [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)，要规整等宽布局直接用 grid。

## 导入
```ts
import { Masonry } from "@hulianui/ui"
```

## Props

`Masonry<T>` 泛型组件。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `T[]` | — | 数据源，按源顺序 round-robin 分列。 |
| columns | `number \| { base?: number; sm?: number; md?: number; lg?: number }` | `3` | 列数。传数字固定；传对象按断点响应式（base 为 SSR/首帧值，挂载后 matchMedia 切换）。 |
| gap | `number` | `16` | 列间 & 列内 item 间距（像素）。 |
| className | `string` | — | 根容器类名。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem* | `(item: T, index: number) => ReactNode` | 渲染函数：渲染单个 item，返回节点会被包进列内格子。 |

## 示例
```tsx
// 固定 3 列
<Masonry items={tiles} columns={3} gap={16} renderItem={(t) => <Tile tile={t} />} />
```

```tsx
// 响应式列数（base 为首帧/SSR 值）
<Masonry
  items={photos}
  columns={{ base: 1, sm: 2, md: 3, lg: 4 }}
  gap={16}
  renderItem={(photo) => <img src={photo.url} alt={photo.alt} />}
/>
```

## 禁忌 / 坑

- **响应式 columns 首帧用 base**：传对象时 SSR/首帧固定用 `base`，挂载后才按 `matchMedia` 切到当前断点列数——这是为防 hydration mismatch 的刻意设计，别期望首屏就拿到 lg 列数。
- **不做等高填谷**：round-robin 是纯下标取模（`item[i] → 第 i%列`），换来 SSR 一致与顺序稳定，代价是各列高度可能略不平衡；需要严格等高填谷的场景本组件不适用。
- 断点（sm/md/lg=640/768/1024）与 Tailwind 默认对齐，命中最大满足断点否则回落 base。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)

<!-- ════════════════════════════════════════════════════════ -->
# Resizable

> 拖拽分栏 · 复合 PanelGroup/Panel/Handle + 横竖向 + min/max + 键盘微调(零依赖·role=separator) · layout/container

## 何时用

要让用户拖动手柄实时改变相邻面板尺寸（IDE 三栏、聊天列表+详情等）时用。它是用户可交互调宽的分栏；若只是按容器宽度自动重排布局用 [Viewport](https://hulianui.haloritual.com/components/viewport)，整页固定骨架用 [Layout](https://hulianui.haloritual.com/components/layout)。

## 导入
```ts
import { ResizablePanelGroup, ResizablePanel, ResizableHandle, applyResize, splitEqually } from "@hulianui/ui"
```

## Props

### ResizablePanelGroup
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| direction | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal=面板横排(分隔符竖直)；vertical=面板竖排(分隔符水平)。 |
| sizes | `number[]` | — | 受控尺寸（百分比数组，一项一面板），须配 onSizesChange。 |
| defaultSizes | `number[]` | 均分 | 非受控初始尺寸；缺省按面板数均分。 |

继承 `HTMLAttributes<HTMLDivElement>`（除 onChange）。

### ResizablePanel
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| min | `number` | `10` | 最小尺寸百分比下限。 |
| max | `number` | `100` | 最大尺寸百分比上限。 |

继承 `HTMLAttributes<HTMLDivElement>`。

### ResizableHandle
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| keyboardStep | `number` | `5` | 键盘方向键每次微调的百分点（role=separator，可聚焦键控）。 |

继承 `HTMLAttributes<HTMLDivElement>`（除 aria-orientation）。

### 工具函数
- `splitEqually(n)` — 生成 n 个面板均分的尺寸数组。
- `applyResize(...)` — 受控模式下据拖拽增量计算新尺寸数组（含 min/max 钳制）。

## Events

### ResizablePanelGroup
| 事件 | 类型 | 说明 |
|------|------|------|
| onSizesChange | `(sizes: number[]) => void` | 尺寸变化回调。 |

## Slots

### ResizablePanelGroup
| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | Panel 与 Handle 交替排列。 |

## 示例
```tsx
// 横向三栏：文件树 / 编辑器 / 预览
<ResizablePanelGroup direction="horizontal" defaultSizes={[24, 46, 30]}>
  <ResizablePanel min={15}><FileTree /></ResizablePanel>
  <ResizableHandle />
  <ResizablePanel min={25}><Editor /></ResizablePanel>
  <ResizableHandle />
  <ResizablePanel min={18}><Preview /></ResizablePanel>
</ResizablePanelGroup>
```

```tsx
// 竖向两栏
<ResizablePanelGroup direction="vertical" defaultSizes={[55, 45]}>
  <ResizablePanel min={20}><ChatLog /></ResizablePanel>
  <ResizableHandle />
  <ResizablePanel min={20}><LogPanel /></ResizablePanel>
</ResizablePanelGroup>
```

## 禁忌 / 坑

- **Panel 与 Handle 必须交替排列**：每两个 `ResizablePanel` 之间放一个 `ResizableHandle`，组件按手柄两侧定位相邻面板做尺寸再分配；漏放或多放会错位。
- **受控时尺寸数组长度须等于面板数**：`sizes`/`defaultSizes` 是百分比数组，一项对应一面板；用 `splitEqually(n)` 起步、`applyResize` 算增量更稳。
- 受控模式记得在 `onSizesChange` 回写 `sizes`，否则拖不动。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)

<!-- ════════════════════════════════════════════════════════ -->
# ScrollArea

> 滚动区 · Base UI 自定义细滚动条 + 竖/横/双向 · layout/container

## 何时用

需要在限定高/宽的区域内滚动、且想要跨平台一致的细滚动条（替代浏览器默认粗条）时用。它只管「滚动条样式 + 方向」；要拖拽改变区域大小用 [Resizable](https://hulianui.haloritual.com/components/resizable)，要按设备宽度做容器查询用 [Viewport](https://hulianui.haloritual.com/components/viewport)。

## 导入
```ts
import { ScrollArea } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| orientation | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | 滚动方向；`both` 时双向滚动条 + corner。 |
| className | `string` | — | 限高/限宽由消费者经此给 Root（如 `h-48` / `w-64`），否则不会出现滚动。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 滚动内容。 |

## 示例
```tsx
// 竖向滚动：必须经 className 给出限高
<ScrollArea className="h-48 w-72 border border-border bg-surface p-4">
  {/* 长内容 */}
</ScrollArea>
```

```tsx
// 横向滚动
<ScrollArea orientation="horizontal" className="w-72">
  <div className="flex gap-3">{/* 横排卡片 */}</div>
</ScrollArea>
```

## 禁忌 / 坑

- **不给限高/限宽就不滚**：组件不自带尺寸，必须经 `className` 给 Root 限定 `h-*` / `w-*`（横向则限 `w-*`），否则内容撑开容器、滚动条永不出现。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [Viewport](https://hulianui.haloritual.com/components/viewport) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)

<!-- ════════════════════════════════════════════════════════ -->
# Separator

> 分隔线 · Base UI role=separator + 横/竖几何 · layout/arrange

## 何时用

需要一条带 ARIA `role="separator"` 语义的纯几何分隔线（横线或竖线）时用 Separator——结构性分组、菜单/列表分段。要在分隔线里嵌文字、虚线或左右偏移文字标题则用 [Divider](https://hulianui.haloritual.com/components/divider)。

## 导入
```ts
import { Separator } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 水平（h-px 横线）/ 垂直（w-px 竖线，需父容器有高度） |
| className | `string` | — | 额外类名 |

## 示例
```tsx
// 水平分隔
<p>瑚琏设计系统</p>
<Separator className="my-3" />
<p>吸取式聚合组件库</p>

// 垂直分隔（父容器须有高度）
<div className="flex h-6 items-center gap-3">
  <span>文档</span>
  <Separator orientation="vertical" />
  <span>组件</span>
</div>
```

## 禁忌 / 坑

暂无已知坑。`orientation="vertical"` 的竖线靠 `w-px` + 高度撑开，父容器必须有确定高度（如 flex 行 `h-6`），否则竖线高度为 0 不可见。

## 相关
[Stack](https://hulianui.haloritual.com/components/stack) · [Grid](https://hulianui.haloritual.com/components/grid) · [Spacer](https://hulianui.haloritual.com/components/spacer) · [Divider](https://hulianui.haloritual.com/components/divider) · [Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)

<!-- ════════════════════════════════════════════════════════ -->
# Spacer

> 间距 · x/y × 0.25rem 布局留白 + aria-hidden + RSC · layout/arrange

## 何时用

在两个相邻元素之间塞一段固定的定向留白（水平/垂直）时用 Spacer，自带 `aria-hidden` 不进无障碍树。若是给一整组子项统一加间距，优先用 [Stack](https://hulianui.haloritual.com/components/stack)/[Grid](https://hulianui.haloritual.com/components/grid) 的 `gap`（无需逐个插 Spacer）；需要可见分隔线用 [Divider](https://hulianui.haloritual.com/components/divider)/[Separator](https://hulianui.haloritual.com/components/separator)。

## 导入
```ts
import { Spacer } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| x | `number` | — | 水平间距（× 0.25rem，同 Tailwind spacing 刻度） |
| y | `number` | — | 垂直间距（× 0.25rem） |
| className | `string` | — | 额外类名 |

## 示例
```tsx
// 横向留白
<span className="inline-flex items-center">
  <Box>A</Box>
  <Spacer x={8} />
  <Box>B</Box>
</span>

// 纵向留白
<span className="inline-flex flex-col">
  <Box>上</Box>
  <Spacer y={6} />
  <Box>下</Box>
</span>
```

## 禁忌 / 坑

暂无已知坑。`x`/`y` 是 Tailwind 刻度倍数（`x={8}` = 2rem）。容器为 flex 行时用 `x`、为 flex 列时用 `y`；方向与父容器主轴不匹配时留白不会生效。

## 相关
[Stack](https://hulianui.haloritual.com/components/stack) · [Grid](https://hulianui.haloritual.com/components/grid) · [Divider](https://hulianui.haloritual.com/components/divider) · [Separator](https://hulianui.haloritual.com/components/separator) · [Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)

<!-- ════════════════════════════════════════════════════════ -->
# Stack

> 弹性布局 · flex 原语 direction/gap/align/justify/wrap + as 多态(零依赖·RSC) · layout/arrange

## 何时用

把一组子元素按单一主轴（横/纵）排开并统一间距时用 Stack——一维线性排列、需要 gap/对齐/换行控制的场景。需要二维行列对齐（同时控制列数与跨列跨行）改用 [Grid](https://hulianui.haloritual.com/components/grid)；只想在两个元素间塞一段定向留白用 [Spacer](https://hulianui.haloritual.com/components/spacer)。

## 导入
```ts
import { Stack } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| direction | `StackDirection \| ResponsiveDirection` | `"column"` | 主轴方向。传字符串=固定；传 `{base,sm,md,lg}`=按断点响应式 |
| gap | `number` | `0` | 子项间距（× 0.25rem，同 Tailwind spacing 刻度） |
| align | `"start" \| "center" \| "end" \| "stretch" \| "baseline"` | — | 交叉轴对齐 |
| justify | `"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"` | — | 主轴对齐 |
| wrap | `boolean` | `false` | 是否换行（仅 row 有意义） |
| inline | `boolean` | `false` | 用 inline-flex 而非 flex（随内容收缩、可与文字基线排列） |
| as | `ElementType` | `"div"` | 渲染的元素标签 |

`StackDirection = "row" \| "column"`；其余 `HTMLAttributes<HTMLElement>` 属性（className/style/事件等）透传。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子元素 |

## 示例
```tsx
// 横向排列，间距 3
<Stack direction="row" gap={3}>
  <Box>A</Box>
  <Box>B</Box>
  <Box>C</Box>
</Stack>

// 两端对齐
<Stack direction="row" justify="between" className="w-64">
  <Box>左</Box>
  <Box>右</Box>
</Stack>
```

## 禁忌 / 坑

暂无已知坑。`gap` 是 Tailwind 刻度倍数而非像素（`gap={3}` = 0.75rem）；`wrap`/`justify` 仅在 `direction="row"` 下有实际意义。候选坑 multi-card-stack-trace / swiftui-text-css-font-stack 与本组件无关，已剔除。

## 相关
[Grid](https://hulianui.haloritual.com/components/grid) · [Spacer](https://hulianui.haloritual.com/components/spacer) · [Divider](https://hulianui.haloritual.com/components/divider) · [Separator](https://hulianui.haloritual.com/components/separator) · [Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout)

<!-- ════════════════════════════════════════════════════════ -->
# Viewport

> 响应式容器 · container-type 容器查询上下文 + web/平板/手机 预设宽度(可 width 覆盖) + 可选设备切换器(dogfood Segmented) · 内部组件用 @md/@5xl 等容器变体按【容器宽度】自适应而非页面视口(跨设备同套布局自动重排) · layout/container

## 何时用

要让同一套布局按「容器宽度」而非「页面视口」重排时用——内部子组件写 `@md:`/`@5xl:` 容器变体即可自适应，并能用内置设备切换器预览 web/平板/手机三态。它建立的是容器查询上下文 + 宽度边框；要锁宽高比用 [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio)，要等比缩放固定设计稿用 [FitScreen](https://hulianui.haloritual.com/components/fit-screen)。

## 导入
```ts
import { Viewport } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| device | `"web" \| "tablet" \| "phone"` | — | 设备预设宽度（受控）：web 满宽自适应 / tablet 768px / phone 390px。 |
| defaultDevice | `"web" \| "tablet" \| "phone"` | `"web"` | 非受控初始设备。 |
| controls | `boolean` | `false` | 顶部显示设备切换器（dogfood Segmented）。 |
| width | `number \| string` | — | 自定义宽度，覆盖 device 预设（数字=px 或任意 CSS 长度）。 |
| name | `string` | — | 具名容器，用于 `@md/name:` 具名容器查询；缺省匿名容器（用 `@md:`）。 |
| framed | `boolean` | `true` | tablet/phone 加设备感边框；web 恒细边框。 |
| height | `number \| string` | 随内容 | 固定容器高度（数字=px 或 CSS）。 |
| className | `string` | — | 根容器类名。 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onDeviceChange | `(device: "web" \| "tablet" \| "phone") => void` | 设备变化回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 容器内容，内部用 `@md:`/`@5xl:` 等容器变体按本容器宽度自适应。 |

## 示例
```tsx
// 设备切换器：点 web/平板/手机，看容器内布局重排
<Viewport controls defaultDevice="phone">
  {/* 内部用 @md/@5xl 等容器变体即按容器宽度自适应 */}
  <div className="grid grid-cols-1 @md:grid-cols-2 @5xl:grid-cols-3">…</div>
</Viewport>
```

```tsx
// 自定义宽度，不要设备边框
<Viewport width={600} framed={false}>
  <ResponsiveDemo />
</Viewport>
```

## 禁忌 / 坑

- **容器变体 ≠ 屏幕断点**：子组件要写 `@md:`/`@5xl:`（容器查询前缀），不是 Tailwind 默认的 `md:`/`5xl:`（页面视口断点）；写错了响应的是浏览器窗口而非本容器宽度。
- 多个并存且要区分时用 `name` 建具名容器并以 `@md/name:` 命中，避免嵌套容器误命中最近祖先。

## 相关
[Layout](https://hulianui.haloritual.com/components/layout) · [AdminLayout](https://hulianui.haloritual.com/components/admin-layout) · [ScrollArea](https://hulianui.haloritual.com/components/scroll-area) · [Resizable](https://hulianui.haloritual.com/components/resizable) · [AspectRatio](https://hulianui.haloritual.com/components/aspect-ratio) · [FitScreen](https://hulianui.haloritual.com/components/fit-screen)


# ━━━━━━━━ 排版 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# AnimatedGradientText

> 渐变文字 · 行内 chart 渐变流动 + RSC · typography/text · #animated

## 何时用

给一小段行内文字加流动渐变着色，随文排版（inline），默认吃瑚琏 chart token。要文字内部极光/大标题质感用 [AuroraText](https://hulianui.haloritual.com/components/aurora-text)（二者都基于 chart 渐变，AuroraText 偏标题级面积、本组件偏行内嵌入）；要横扫高光徽标用 [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)。

## 导入
```ts
import { AnimatedGradientText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | 瑚琏 chart token | 渐变停靠色数组 |
| speed | `number` | `1` | 流动速度倍率 |

继承 `ComponentPropsWithoutRef<"span">`（除 `color`），如 `className` / `style`。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 要渲染的文字 |

## 示例
```tsx
<AnimatedGradientText className="text-2xl">🎉 全新瑚琏组件库</AnimatedGradientText>
```

## 禁忌 / 坑

- 行内 `<span>`，靠字号/前景裁切显色，空内容或无字号无可见效果。
- 自定义 `colors` 用瑚琏 token 时须带 `--color-` 前缀才能在渐变里解析（见 hulian token 规范）。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# AnimatedShinyText

> 高光文字 · 横扫高光 + 徽标气质 + RSC · typography/text · #animated

## 何时用

给小段文字加一道横扫高光，常用于 pill 徽标 / "Introducing" 提示条这类轻量营销点缀。要彩色极光渐变文字用 [AuroraText](https://hulianui.haloritual.com/components/aurora-text)；要行内流动渐变用 [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)；普通文本用 [Text](https://hulianui.haloritual.com/components/text)。

## 导入
```ts
import { AnimatedShinyText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| shimmerWidth | `number` | `100` | 高光带宽度（px） |

继承 `ComponentPropsWithoutRef<"span">`（`children` / `className` / `style` 等）。

## 示例
```tsx
<div className="rounded-full border border-border bg-surface px-4 py-1.5">
  <AnimatedShinyText className="text-sm">✨ Introducing 瑚琏 Hulian</AnimatedShinyText>
</div>
```

## 禁忌 / 坑

- 高光靠遮罩横扫文字本体，需要文字有可见前景色才看得出来；放在过亮/过暗背景上高光带可能不明显，配合徽标容器（border + bg-surface）效果最佳。
- 渲染为 `<span>`，无字号/无内容时无可见效果。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# ASCIIText

> 把文字渲染成 ASCII 字符画 · canvas2d 逐像素亮度采样映射字符 + 正弦波动位移 + 鼠标驱动 hue-rotate 色相（零依赖去 three.js·token·reduced-motion） · typography/text · #animated

## 何时用

Hero / 404 / 极客风装饰位想把一句短文渲染成跳动的字符画时用。要的是平滑渐变发光质感（AuroraText）或闪过的高光（AnimatedShinyText）就用那两个；ASCIIText 是把字形彻底拆成字符网格的重特效，仅适合短文本、装饰位。

## 导入
```ts
import { ASCIIText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | `"瑚琏"` | 要转成字符画的文本，先渲染到离屏 canvas 再按像素亮度逐格映射字符 |
| asciiFontSize | `number` | `8` | 字符画字号(px)，决定网格密度；越小越密越费算力，建议 6–14 |
| textFontSize | `number` | `160` | 离屏源文本字号(px)，越大采样分辨率越高；与 asciiFontSize 比值≈字符列数 |
| textColor | `string` | `var(--color-foreground)` | 源文本填充色，喂给 canvas fillStyle，须可被 canvas 解析 |
| enableWaves | `boolean` | `true` | 字符网格按行做正弦相位偏移营造飘动；reduced-motion 下强制静止 |
| enableHue | `boolean` | `true` | 指针相对中心的角度驱动 hue-rotate 色相旋转；关闭则保持单一色相 |
| charset | `string` | 经典 70 级 ramp | 字符亮度坡道(暗→亮)，索引越大代表越亮的像素，可传自定义风格化 |
| className | `string` | — | 透传根容器额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 默认：波动 + 鼠标色相，主色字符
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <ASCIIText text="瑚琏" className="text-[color:var(--color-chart-1)]" />
</div>

// 静态：关波动、关色相，高密度细节
<ASCIIText text="代码" enableWaves={false} enableHue={false} asciiFontSize={6} textFontSize={200} />
```

## 禁忌 / 坑

- canvas2d 重绘：仅适合短文本装饰位，长串字符会让网格列数暴涨、逐帧采样吃满算力。
- textColor 喂的是 canvas fillStyle，须是 canvas 能解析的颜色值；想随主题变可走默认 token，自定义传裸值不会随明暗切换。
- reduced-motion 下波动强制静止（DOM 不变，仅停动画），别依赖动画状态做判断。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# AuroraText

> 极光文字 · bg-clip 流动渐变 + chart token + RSC · typography/text · #animated

## 何时用

给一小段标题/品牌词加极光流动渐变（bg-clip 文字裁切），默认吃 4 个瑚琏 chart token 随明暗主题切换。要横扫高光徽标气质用 [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)；要行内随文流动的渐变用 [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)；普通文本用 [Text](https://hulianui.haloritual.com/components/text)，不要给大段正文套动效。

## 导入
```ts
import { AuroraText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | 4 个瑚琏 chart token | 渐变停靠色数组（自动吃明暗主题） |
| speed | `number` | `1` | 流动速度倍率，越大越快 |

继承 `ComponentPropsWithoutRef<"span">`（除 `color`），如 `className` / `style`。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 要渲染的文字 |

## 示例
```tsx
<AuroraText className="text-4xl font-bold">瑚琏 Hulian</AuroraText>
```

加速：
```tsx
<AuroraText className="text-4xl font-bold" speed={2}>Aurora</AuroraText>
```

## 禁忌 / 坑

- 渲染为 `<span>`，效果靠 `text-*`/`font-*` 等字号样式撑出可见面积，给空 children 或无字号时看不到流光。
- 自定义 `colors` 须用可解析的 CSS 颜色值；用 token 时注意瑚琏 token 需带 `--color-` 前缀才在 SVG/渐变里解析（见 hulian token 规范）。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# BlurText

> 模糊解析 · 各词从模糊+位移解析到清晰 + 滚入视口触发(motion · top/bottom 方向 · aria-label 整段 · reduced-motion 直呈清晰) · typography/text · #animated

## 何时用

标题/段落滚入视口时让每段从「模糊+位移」解析到清晰，比纯位移淡入更有镜头对焦质感。只要逐段位移淡入（不模糊）用 [SplitText](https://hulianui.haloritual.com/components/split-text)；要随滚动进度持续逐词显影用 [ScrollReveal](https://hulianui.haloritual.com/components/scroll-reveal)；普通静态标题用 [Heading](https://hulianui.haloritual.com/components/heading)。

## 导入
```ts
import { BlurText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text * | `string` | — | 要逐段模糊浮现的文本 |
| splitType | `"char" \| "word"` | `"word"` | 切分粒度：word 逐词（按空白切）/ char 逐字（中文友好） |
| direction | `"top" \| "bottom"` | `"top"` | 进场方向，伴随 y 位移与中段过冲 |
| delay | `number` | `120` | 相邻段错峰毫秒，越大波浪推进越慢 |
| blur | `number` | `8` | 起始模糊像素，解析到 0 时清晰 |
| stepDuration | `number` | `0.5` | 单段从起始到清晰的整体时长（秒），内部分两步 |
| threshold | `number` | `0.3` | 触发动画的视口可见比例（useInView amount），0~1 |

其余 `<p>` 原生属性透传；`onDrag/onDragStart/onDragEnd/onAnimationStart` 因与 motion 签名冲突被剔除。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onAnimationComplete | `() => void` | 末段动画结束回调（整句浮现完成时触发一次） |

## 示例
```tsx
<BlurText text="Isn't this so cool?!" className="text-3xl font-bold text-foreground" />

<BlurText
  text="清晰浮现的瑚琏标题"
  splitType="char"
  direction="bottom"
  className="text-3xl font-bold text-primary"
/>
```

## 禁忌 / 坑

- `text` 只收纯字符串，不能塞 JSX。
- 中文用 `splitType="word"` 会因无空白而整段一次浮现；逐字效果需显式传 `splitType="char"`。
- 进场只触发一次（基于视口可见比例 `threshold`）；反复观察需更换 `key` 强制 remount。
- 尊重 `prefers-reduced-motion`：开启减弱动效时直呈清晰终态。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# CircularText

> 环形文字 · 每字按等分角排到圆周 + 整体匀速自转 + 悬停调速(加速/减速/暂停/抓狂 · 颜色继承 currentColor · reduced-motion 静态) · typography/text · #animated

## 何时用

徽章/印章/旋转 logo 场景把文本按等分角排到圆周并匀速自转，悬停可调速。要做平铺逐字进场用 [SplitText](https://hulianui.haloritual.com/components/split-text)；要故障撕裂用 [GlitchText](https://hulianui.haloritual.com/components/glitch-text)；普通静态标题用 [Heading](https://hulianui.haloritual.com/components/heading)。

## 导入
```ts
import { CircularText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text * | `string` | — | 环绕排布的文本，建议尾部加分隔符（如 `✦`）让首尾衔接更顺 |
| spinDuration | `number` | `20` | 转一圈秒数 |
| onHover | `"speedUp" \| "slow" \| "pause" \| "goBonkers"` | `"speedUp"` | 悬停行为：加速 / 减速 / 暂停 / 抓狂 |
| radius | `number` | `80` | 文字所在圆半径像素 |

其余 `<div>` 原生属性透传。文字颜色继承 `currentColor`，用 `text-*` 工具类着色。

## 示例
```tsx
<CircularText
  text="瑚琏 · HULIAN UI · 设计系统 · "
  className="text-sm font-semibold tracking-widest text-primary"
/>

<CircularText
  text="★ HULIAN ★ STUDIO ★ "
  spinDuration={14}
  onHover="goBonkers"
  radius={64}
  className="text-xs font-bold tracking-[0.2em] text-background"
/>
```

## 禁忌 / 坑

- `text` 首尾会衔接成环：结尾建议补分隔符（` · ` / `✦` / `★`），否则末字与首字直接相贴。
- 颜色继承 `currentColor`，必须靠 `text-*` 类或父级 color 着色，没有独立颜色 prop。
- 尊重 `prefers-reduced-motion`：开启减弱动效时静止不自转。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# Code

> 行内代码 · <code> 等宽皮肤 + tone(default/primary/danger) + RSC · typography/code

## 何时用

正文中嵌入行内代码片段（命令、标识符、路径），等宽皮肤 + tone 着色，可在 RSC 直接渲染。多行/带语法高亮的代码块用 [CodeBlock](https://hulianui.haloritual.com/components/code-block)；带复制按钮的命令片段用 [Snippet](https://hulianui.haloritual.com/components/snippet)；展示键盘按键用 [Kbd](https://hulianui.haloritual.com/components/kbd)。

## 导入
```ts
import { Code, codeVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"default" \| "primary" \| "danger"` | `"default"` | 配色语气：默认 / 主色（强调）/ 危险（破坏性命令） |

其余 `<code>`（HTMLElement）原生属性透传。`codeVariants` 为 CVA 样式函数，可在自定义元素上复用皮肤类名。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 代码内容 |

## 示例
```tsx
<span className="text-sm text-foreground">运行 <Code>pnpm install</Code> 安装依赖</span>

<Code tone="danger">rm -rf</Code>
```

## 禁忌 / 坑

暂无已知坑。

## 相关
[CodeBlock](https://hulianui.haloritual.com/components/code-block) · [Snippet](https://hulianui.haloritual.com/components/snippet) · [CodeDiff](https://hulianui.haloritual.com/components/code-diff) · [Kbd](https://hulianui.haloritual.com/components/kbd) · [Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading)

<!-- ════════════════════════════════════════════════════════ -->
# CodeBlock

> 代码块 · 多行 <pre> + 一键复制(剪贴板+反馈) + 可选语言标签 · typography/code

## 何时用

展示多行代码片段，自带语法着色、右上角语言标签与一键复制。单行命令/内联标识用 [Snippet](https://hulianui.haloritual.com/components/snippet)；只是一段内联 `code` 文字用 [Code](https://hulianui.haloritual.com/components/code)；展示前后差异用 [CodeDiff](https://hulianui.haloritual.com/components/code-diff)。

## 导入
```ts
import { CodeBlock, HighlightedCode, tokenizeCode, type CodeToken, type CodeTokenType } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| code* | `string` | — | 代码文本，多行用 `\n` |
| lang | `string` | — | 右上角语言标签（如 `"tsx"`），同时决定着色规则走 JS 家族还是 Shell |
| copyable | `boolean` | `true` | 是否显示复制按钮 |
| highlight | `boolean` | `true` | 是否语法着色；关掉则纯文本 |
| className | `string` | — | 容器类名 |

## 示例
```tsx
<CodeBlock code={`import { Button } from "@hulianui/ui";`} lang="tsx" />

// Shell 走 Shell 着色规则
<CodeBlock code={`pnpm add @hulianui/ui`} lang="bash" />
```

## 禁忌 / 坑

暂无已知坑。

## 相关
[Code](https://hulianui.haloritual.com/components/code) · [Snippet](https://hulianui.haloritual.com/components/snippet) · [CodeDiff](https://hulianui.haloritual.com/components/code-diff) · [Kbd](https://hulianui.haloritual.com/components/kbd) · [Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading)

<!-- ════════════════════════════════════════════════════════ -->
# CodeDiff

> 代码对比 · 零依赖行级 LCS diff(纯函数 diffLines 可测) + unified 单栏/split 双栏 + 增绿删红行底色 + 双行号槽 + filename 头条与 +/− 摘要 · agent 改动/PR 评审 · typography/code

## 何时用

展示两段文本的行级差异（PR 评审、agent 改动回放、配置变更对比），增绿删红、双行号、可挂行级批注。只展示静态代码用 [CodeBlock](https://hulianui.haloritual.com/components/code-block)；单行命令用 [Snippet](https://hulianui.haloritual.com/components/snippet)。`diffLines`/`diffStat` 是纯函数，可单独用于自定义渲染或统计。

## 导入
```ts
import { CodeDiff, diffLines, diffStat } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| oldText* | `string` | — | 旧文本 |
| newText* | `string` | — | 新文本 |
| mode | `"unified" ｜ "split"` | `"unified"` | unified 单栏 / split 双栏对照 |
| filename | `string` | — | 头部文件名条；省略则不渲染头部 |
| showLineNumbers | `boolean` | `true` | 显示行号槽 |
| annotations | `CodeDiffAnnotation[]` | — | 行锚定批注：在匹配行渲染 gutter 标记 + 行下方插入整宽 content 槽（仅 unified 模式插 content） |
| className | `string` | — | 容器类名 |

`CodeDiffAnnotation`：`{ side?: "old"｜"new"（默认 "new"）; line: number（1-based）; gutter?: ReactNode; content?: ReactNode }`。

## 示例
```tsx
<CodeDiff filename="greet.ts" oldText={OLD} newText={NEW} />

// 双栏对照
<CodeDiff mode="split" filename="greet.ts" oldText={OLD} newText={NEW} />
```

## 禁忌 / 坑

- `annotations` 的 `content` 槽**仅在 unified 模式**插入；split 模式只渲染 gutter 标记。需要在差异行下方挂 CodeReviewThread 等内容时用 `mode="unified"`。
- `annotations[].line` 是 1-based 行号，按 `side` 对应旧文件或新文件，别和数组下标混淆。

## 相关
[Code](https://hulianui.haloritual.com/components/code) · [CodeBlock](https://hulianui.haloritual.com/components/code-block) · [Snippet](https://hulianui.haloritual.com/components/snippet) · [Kbd](https://hulianui.haloritual.com/components/kbd) · [Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading)

<!-- ════════════════════════════════════════════════════════ -->
# CurvedLoop

> 沿二次贝塞尔曲线无缝循环滚动的弧形跑马灯文字 · SVG textPath + rAF 续滚 + 可拖拽拨动(零依赖·token/currentColor·reduced-motion) · typography/text · #animated

## 何时用

页眉 / 区块分隔带想要弯曲弧形走向的跑马灯横幅时用。需要随页面滚动加速变向的多行平排跑马灯用 ScrollVelocity；只要一条沿曲线无缝循环、还能手动拨动的弧形文字带就用 CurvedLoop。

## 导入
```ts
import { CurvedLoop } from "@hulianui/ui"
```

## Props

继承 `SVGProps<SVGSVGElement>`（去 `ref`），常用如下：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | — | 跑马灯文案，内部去尾部空白并补不间断空格作词间隔，首尾无缝拼接铺满曲线 |
| speed | `number` | `2` | 滚动速度(px/帧，约 60fps)，越大越快 |
| curveAmount | `number` | `320` | 弯曲量(二次贝塞尔控制点垂直偏移，viewBox 像素)，正值向下弯/负值向上弯/0 近直线 |
| direction | `"left" \| "right"` | `"left"` | 自动滚动方向 |
| interactive | `boolean` | `true` | 是否允许鼠标/触控拖拽拨动文字(松手后沿拖拽方向续滚) |
| className | `string` | — | 文字颜色 token 类名(如 text-primary)；默认 fill 走 currentColor，可由父级 text-* 控制 |

## 示例
```tsx
// 默认：向下弯、左滚
<CurvedLoop text="瑚琏 · HULIAN · " className="text-white" />

// 向上弯(curveAmount 负值) + 主色
<CurvedLoop text="ENTERPRISE UI · " curveAmount={-220} className="text-[var(--color-chart-1)]" />

// 右滚高速、纯展示不可拖
<CurvedLoop text="瑚琏组件库 · " direction="right" speed={4} interactive={false} />
```

## 禁忌 / 坑

- 文案末尾习惯带分隔符（如 `" · "`），内部会补不间断空格做词间隔再首尾拼接，缺分隔符会让循环接缝读起来粘连。
- 颜色走 currentColor：用 className 的 `text-*` 控制色，不要直接传 `fill`。
- reduced-motion 下停止自动滚动；交互拨动仍可用，别用动画做核心信息载体。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# DecryptedText

> 乱码解码 · 字符翻滚后逐位解码到明文 + view/hover 触发(随机仅客户端 effect 避 hydration mismatch · 等宽 tabular-nums 防抖 · aria-label 明文) · typography/text · #animated

## 何时用

科技/安全/黑客感场景里让文本先翻滚乱码再逐位解码到明文，强调「解密揭示」的戏剧性。要做平滑的模糊对焦用 [BlurText](https://hulianui.haloritual.com/components/blur-text)；要做 RGB 错位故障撕裂用 [GlitchText](https://hulianui.haloritual.com/components/glitch-text)；普通逐字进场用 [SplitText](https://hulianui.haloritual.com/components/split-text)。

## 导入
```ts
import { DecryptedText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text * | `string` | — | 目标明文 |
| speed | `number` | `55` | 每次乱码刷新间隔毫秒 |
| animateOn | `"view" \| "hover"` | `"view"` | 触发方式：view 滚入视口一次性解码 / hover 悬停解码、移出复位 |
| characters | `string` | 大小写字母+数字+符号 | 乱码取样字符集 |

其余 `<span>` 原生属性透传。

## 示例
```tsx
<DecryptedText text="Decrypting access..." className="text-2xl font-semibold text-foreground" />

<DecryptedText
  text="Hover to decrypt"
  animateOn="hover"
  className="text-2xl font-semibold text-primary"
/>
```

## 禁忌 / 坑

- 乱码取样是随机的，仅在客户端 effect 里跑，避免 SSR/hydration mismatch（服务端首帧呈明文）。
- 内部用等宽 `tabular-nums` 防止翻滚时宽度抖动；自定义 `className` 别覆盖等宽设定，否则字符乱跳。
- 暂无其他已知坑。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# FallingText

> 文字按词散落物理特效 · 触发后逐词受重力下落/撞墙反弹堆叠 + 指针拖拽抛掷(零依赖 RAF 自写二维刚体·token·reduced-motion) · typography/text · #animated

## 何时用

落地页彩蛋 / 互动 banner 想让一句话按词「散架掉落」并可拖拽抛玩时用。要平滑入场浮现/错峰用 ScrollFloat、Reveal；FallingText 是把每个词当独立刚体做重力碰撞的重交互特效，仅适合短句、装饰互动位。

## 导入
```ts
import { FallingText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | `""` | 整段文本，按空格切「词块」，每词一个独立刚体下落 |
| highlightWords | `string[]` | `[]` | 需高亮的词(前缀匹配：词 startsWith 任一即高亮) |
| highlightClass | `string` | `"text-primary font-semibold"` | 高亮词额外 className(叠加在词块上) |
| trigger | `"auto" \| "scroll" \| "click" \| "hover"` | `"auto"` | 掉落时机：挂载即播/滚入视口/点击容器/指针移入 |
| gravity | `number` | `1` | 向下加速度系数，越大下落越快堆叠越急，建议 0.3–3 |
| bounce | `number` | `0.6` | 落地/撞墙反弹系数(0 不弹，1 全弹) |
| fontSize | `string` | `"1.5rem"` | 文本字号(CSS 长度，传入根 fontSize) |
| className | `string` | — | 透传根容器额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 默认：自动掉落 + 高亮词
<FallingText
  text="瑚琏 组件库 企业级 高质量 原生适配 token 主题"
  highlightWords={["瑚琏", "token"]}
  className="text-white/90"
  fontSize="1.5rem"
/>

// 点击触发 + 高重力低反弹(迅速堆叠)
<FallingText text="点我 让 文字 散落 下来" trigger="click" gravity={2.4} bounce={0.2} />
```

## 禁忌 / 坑

- 词块按空格切分：中文要靠手动空格分词（如 `"瑚琏 组件库 企业级"`），不空格会整段当一个刚体。
- highlightWords 是前缀匹配（startsWith），不是全等，注意误命中相同前缀的词。
- 默认 `text=""` 不渲染任何词，忘传 text 会得到空舞台。
- reduced-motion 下不做物理掉落动画；别把它当核心内容的唯一呈现方式。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# FuzzyText

> 信号噪点模糊标题 · canvas2d 逐行/逐列随机错位扫描 + 悬停增强抖动(零依赖·token·reduced-motion 退静态帧) · typography/text · #animated

## 何时用

404 / 故障页 / 极客风大标题想要信号噪点、扫描错位的「毛刺」质感时用。要逐字翻滚乱码的悬停文字用 ScrambledText；要平滑发光渐变用 AuroraText；FuzzyText 是把字形按行/列像素错位做扫描噪点，适合厚重短标题。

## 导入
```ts
import { FuzzyText } from "@hulianui/ui"
```

## Props

继承 `CanvasHTMLAttributes<HTMLCanvasElement>`（去 `color`/`children`/`style`），核心如下：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| fontSize | `number \| string` | `"clamp(2rem, 10vw, 10rem)"` | 数字按 px、字符串按任意 CSS 长度(含 clamp)，自适应视口 |
| fontWeight | `number \| string` | `900` | 字重，厚笔画下噪点更醒目 |
| fontFamily | `string` | `"inherit"` | 字体族，inherit 读 canvas computed font-family |
| color | `string` | `var(--color-foreground)` | 填充色，随明暗主题；可传任意 CSS 颜色(含 var()/currentColor，内部经 computed style 解析)；style.color 优先级更高 |
| enableHover | `boolean` | `true` | 指针在文字范围内时抖动加剧 |
| baseIntensity | `number` | `0.18` | 静息态噪点强度(0–1)，越大越「毛」 |
| hoverIntensity | `number` | `0.5` | 悬停态噪点强度(0–1) |
| fuzzRange | `number` | `30` | 每行/列最大像素位移幅度，决定噪点散开范围 |
| direction | `"horizontal" \| "vertical" \| "both"` | `"horizontal"` | 抖动方向：按行左右/按列上下/两者叠加 |
| className | `string` | — | 透传 canvas 额外 className |
| style | `CSSProperties` | — | 透传 canvas 内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 要渲染的文字(仅纯文本，会被拼成一行) |

## 示例
```tsx
// 默认：横向扫描噪点
<FuzzyText fontSize="clamp(2rem, 8vw, 5rem)">瑚琏</FuzzyText>

// 404：高位移 + 主色
<FuzzyText fontSize="clamp(3rem, 14vw, 8rem)" fuzzRange={42} baseIntensity={0.3} color="var(--color-chart-1)">
  404
</FuzzyText>
```

## 禁忌 / 坑

- 渲染目标是 `<canvas>`：children 仅支持纯文本，传嵌套元素会被拼接为一行字符串。
- color 喂的是经 computed style 解析的颜色：可传 `var(--color-*)`/`currentColor`，但纯 canvas 不吃 Tailwind 工具类，给颜色走 color prop 或 style.color。
- reduced-motion 下退化为静态帧（保留可读文字），别依赖抖动作为唯一视觉反馈。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# GlitchText

> 故障撕裂 · 双伪元素 RGB 错位 + clip-path 切片抖动(纯 CSS 零依赖 RSC · 撕裂色吃 chart token · enableOnHover 门控 · motion-reduce 退普通文本) · typography/text · #animated

## 何时用

赛博朋克/科技感标题做 RGB 错位+切片抖动的故障撕裂效果，纯 CSS 零依赖、可在 RSC 直接渲染。要做乱码逐位解码用 [DecryptedText](https://hulianui.haloritual.com/components/decrypted-text)；要做模糊对焦用 [BlurText](https://hulianui.haloritual.com/components/blur-text)；普通静态标题用 [Heading](https://hulianui.haloritual.com/components/heading)。

## 导入
```ts
import { GlitchText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `number` | `2.5` | 撕裂周期秒数，越小越狂躁 |
| enableOnHover | `boolean` | `false` | 仅悬停时故障，静息为普通文本；默认常驻故障 |

其余 `<span>` 原生属性透传。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | `string` | 要做撕裂故障效果的文本，必须是纯字符串（供伪元素 `attr(data-text)` 复制） |

## 示例
```tsx
<GlitchText className="text-4xl font-extrabold tracking-tight">HULIAN</GlitchText>

<GlitchText enableOnHover className="text-4xl font-extrabold tracking-tight">
  GLITCH
</GlitchText>
```

## 禁忌 / 坑

- `children` 必须是纯字符串：伪元素靠 `attr(data-text)` 复制文本制造错位层，传入 JSX/元素会让撕裂层为空。
- 撕裂色吃 chart token（`var(--color-chart-*)`），随主题切换；自定义颜色须带 `--color-` 前缀或合法 CSS 颜色，裸 `var(--primary)` 在本 Tailwind v4 设定下不解析。
- 尊重 `prefers-reduced-motion`：开启减弱动效时退化为普通文本、不抖动。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# Heading

> 标题 · 1-6 级语义标签 + size/weight + as 多态(纯皮肤·零依赖·RSC) · typography/text

## 何时用

需要语义标题（自动渲染为 h1–h6）并控制视觉尺寸/字重时用 Heading；支持视觉与语义解耦（如语义是 h2、视觉用 lg），以及用 `as` 把标题样式套到非标题标签上。正文、说明文本用 [Text](https://hulianui.haloritual.com/components/text)；整段富文本排版用 [Prose](https://hulianui.haloritual.com/components/prose)。

## 导入
```ts
import { Heading } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| level | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | 标题级别，决定语义标签 `h{level}` 与默认视觉尺寸 |
| as | `ElementType` | `h{level}` | 覆盖渲染标签（视觉/语义解耦，如 level=1 样式渲染为 div） |
| size | `"xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl"` | 按 level 派生 | 覆盖视觉尺寸（独立于 level） |
| weight | `"normal" \| "medium" \| "semibold" \| "bold"` | `"semibold"` | 字重 |
| balance | `boolean` | `false` | 启用 text-balance 平衡换行（多行标题更匀称） |

继承 `HTMLAttributes<HTMLHeadingElement>`（已 Omit `color`）。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 标题文本 |

## 示例
```tsx
// 语义标签 + 默认尺寸
<Heading level={1}>一级标题</Heading>

// 视觉/语义解耦：语义 h2，视觉 lg
<Heading level={2} size="lg">语义是 h2，视觉是 lg</Heading>

// 用 div 承载大标题样式 + 平衡换行
<Heading level={1} as="div" balance>大号视觉标题</Heading>
```

## 禁忌 / 坑

暂无已知坑。`level` 同时决定语义标签和默认尺寸——要保留语义标签但改视觉，用 `size` 覆盖，别为了视觉乱改 `level`（会破坏文档大纲）。注意 Heading 无 `size="md"` 档（只有 base，无 md），来自历史踩坑。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# Kbd

> 按键 · <kbd> 等宽皮肤 + 组合键并排 + RSC · typography/code

## 何时用

标注单个键位/快捷键（`Esc`、`⌘`、`K`），等宽键帽皮肤。组合键由多个 Kbd 并排手动组合（见示例）。它是 RSC，可在服务端组件直接用。展示代码片段用 [CodeBlock](https://hulianui.haloritual.com/components/code-block)/[Snippet](https://hulianui.haloritual.com/components/snippet)。

## 导入
```ts
import { Kbd } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| ...HTMLAttributes | `HTMLAttributes<HTMLElement>` | — | 透传 `<kbd>` 原生属性（className、style 等） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 键位内容 |

## 示例
```tsx
<Kbd>Esc</Kbd>

// 组合键：多个 Kbd 并排
<span className="inline-flex items-center gap-1">
  <Kbd>⌘</Kbd>
  <span className="text-muted">+</span>
  <Kbd>K</Kbd>
</span>
```

## 禁忌 / 坑

- 单个 Kbd 只渲染一个键帽，组合键需自行用多个 Kbd 并排拼装，组件不内置 `+` 分隔。

## 相关
[Code](https://hulianui.haloritual.com/components/code) · [CodeBlock](https://hulianui.haloritual.com/components/code-block) · [Snippet](https://hulianui.haloritual.com/components/snippet) · [CodeDiff](https://hulianui.haloritual.com/components/code-diff) · [Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading)

<!-- ════════════════════════════════════════════════════════ -->
# Markdown

> 只读 Markdown 渲染 · 零依赖块级解析(标题/代码块/列表/引用/行内粗斜码链) · 套 Prose 排版 + 围栏代码块委托 CodeBlock · 区别 MarkdownEditor 可编辑 · RSC 安全 · typography/text

## 何时用

把一段 Markdown 源字符串只读渲染成排版好的富文本（标题/围栏代码块/列表/引用/行内粗斜码链）。需要可编辑用 [MarkdownEditor]；已经是 HTML/JSX 而非 Markdown 源用 [Prose](https://hulianui.haloritual.com/components/prose) 直接包裹；单段原子文本用 [Text](https://hulianui.haloritual.com/components/text)。`parseBlocks` 导出供需要拿块级 AST 自定义渲染的场景。

## 导入
```ts
import { Markdown, parseBlocks } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" \| "base"` | `"base"` | 排版尺寸基准，透传给内部 Prose |
| className | `string` | — | 透传容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `string` | Markdown 源文本（只读渲染；编辑用 MarkdownEditor） |

## 示例
```tsx
<div className="max-w-2xl">
  <Markdown>{`## 快速排序

\`\`\`js
function quickSort(arr) { /* ... */ }
\`\`\`

平均复杂度 **O(n log n)**，行内 \`代码\` 与[外链](https://mdn.io)正常渲染。

> 引用块整体排版吃 Prose 语义 token。`}</Markdown>
</div>
```

## 禁忌 / 坑

- 零依赖块级解析输出 JSX（非 `dangerouslySetInnerHTML`/`innerHTML`），不走原生 HTML sink，故无 [[dompurify-vhtml-markdown-sanitize]] 那类存储型 XSS 风险；但若后续改造成「直接注入 HTML」或扩展支持原始 HTML 标签，必须经 DOMPurify 等清洗后再渲染，不要把不可信源直接喂进 innerHTML。
- 只读组件，不接受编辑回调；需要双向编辑改用 MarkdownEditor。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# Prose

> 排版容器 · 富文本/markdown 后代选择器统一吃语义 token(纯皮肤·零依赖·RSC) · typography/text

## 何时用

包裹一段渲染好的富文本（markdown→HTML、MDX 输出或手写 JSX），用后代选择器把标题/段落/列表/链接/行内代码/引用统一接管为一致阅读排版、自动适配明暗主题。内容已是 Markdown 源字符串时用 [Markdown](https://hulianui.haloritual.com/components/markdown)（它内部就套 Prose）；单段/单个标题等原子文本用 [Text](https://hulianui.haloritual.com/components/text) / [Heading](https://hulianui.haloritual.com/components/heading)，不要为一句话套 Prose。

## 导入
```ts
import { Prose } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| as | `ElementType` | `"article"` | 渲染的容器标签 |
| size | `"sm" \| "base"` | `"base"` | 整体排版尺寸基准；`sm` 把基准字号降到 text-sm，适合侧栏/卡片内长文 |

继承 `HTMLAttributes<HTMLElement>`（`className` / `style` 等）。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 富文本内容（HTML/JSX） |

## 示例
```tsx
<Prose className="max-w-2xl">
  <h1>瑚琏排版容器 Prose</h1>
  <p>把渲染好的富文本统一接管为一致阅读排版，<a href="#">链接</a> 与 <code>行内代码</code> 全吃语义 token。</p>
  <blockquote>排版即沉默的设计——容器统一规则，内容只管语义。</blockquote>
</Prose>
```

紧凑场景：
```tsx
<Prose size="sm" className="max-w-2xl">{/* 侧栏说明、卡片内富文本 */}</Prose>
```

## 禁忌 / 坑

- 见 [[chat-bubble-max-w-prose-overflows-narrow-column]]：`max-w-prose`（65ch≈398px）是绝对值、不感知父容器可用宽度，放进移动端窄 flex 列会横向溢出/裁切。约束宽度用 `max-w-[min(65ch,100%)]`，且父链 flex 项加 `min-w-0`；不要叠 `max-w-prose max-w-full`（同属性二选一由 CSS 顺序决定不可靠）。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# ScrambledText

> 指针靠近文字逐字翻滚乱码再收敛的悬停文字特效 · 半径内越近翻滚越久 + 可自定字符集/速度（零依赖 RAF·reduced-motion） · typography/text · #animated

## 何时用

整段文字想要「指针扫过逐字解码」的悬停互动时用。要的是像素扫描错位的故障质感用 FuzzyText；要平滑入场用 ScrollFloat / Reveal；ScrambledText 适合一段可读正文/小标题，靠鼠标半径触发逐字符乱码翻滚再收敛。

## 导入
```ts
import { ScrambledText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| radius | `number` | `100` | 指针生效半径(px)，落在某字符中心此半径内才触发该字翻滚 |
| duration | `number` | `1.2` | 单字乱码翻滚最长时间(秒)，离指针越近越接近此值 |
| speed | `number` | `0.5` | 翻滚速度(0~1)，越大每帧切换乱码越频繁、收敛越快 |
| scrambleChars | `string` | `".:"` | 乱码随机替换用的字符集，逐字符循环取样 |
| className | `string` | — | 透传根元素额外类名(cn 合并) |
| style | `CSSProperties` | — | 透传根元素内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 要逐字打乱的文本(仅纯文本，内部拆成单字符 span) |

## 示例
```tsx
// 默认：.: 字符集
<ScrambledText>把指针移到这段文字上 — Hover scrambles the glyphs.</ScrambledText>

// 大半径 + 全角符号集
<ScrambledText radius={160} scrambleChars="█▓▒░">
  HULIAN UI · Scramble On Hover
</ScrambledText>
```

## 禁忌 / 坑

- children 仅支持纯文本：内部按字符拆 span，传嵌套元素的结构会被打散。
- 半径基于字符中心：超长段落里离指针远的字几乎不动，这是设计预期而非 bug。
- reduced-motion 下不做翻滚动画，直接显示原文。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# ScrollFloat

> 滚动浮现标题：随容器滚过视口逐字符从「下沉 + 纵向拉伸横向压扁 + 透明」拔起到正常 · useScroll 绑进度 + 每字符 useTransform 派生 opacity/y/scaleX/scaleY（去 gsap·吃 text-foreground token·reduced-motion 直出清晰标题） · typography/text · #animated

## 何时用

长页面区块标题想随滚动逐字符「拔起」浮现时用。要通用块级（非逐字）入场用 Reveal；要平滑发光渐变标题用 AuroraText；ScrollFloat 专做随滚动进度逐字符变形浮现的大标题。

## 导入
```ts
import { ScrollFloat } from "@hulianui/ui"
```

## Props

继承 `h2` props（去 `children` 与 motion 冲突的 onDrag*/onAnimationStart）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| scrollContainerRef | `RefObject<HTMLElement \| null>` | 自动探测 | 自定义滚动容器；不传时优先绑最近可滚动祖先，其次视口，完全无滚动上下文则降级为进入视口自动浮现 |
| offset | `[string, string]` | `["start 0.9", "start 0.35"]` | 进度映射区间(对应 useScroll offset)：顶进视口 90% 处开始、35% 处完成 |
| stagger | `number` | `0.4` | 字符间错峰强度(0~1)，每字符进度窗口相对整体的偏移比例 |
| yPercent | `number` | `120` | 初始下沉位移百分比(相对字高)，随进度回 0 |
| scaleY | `number` | `2.3` | 初始纵向拉伸倍率，随进度回 1 |
| scaleX | `number` | `0.7` | 初始横向压扁倍率，随进度回 1 |
| containerClassName | `string` | — | 外层容器类名(裁切溢出的滚动浮现) |
| textClassName | `string` | — | 文本层类名(控制字号/字重/对齐) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `string` | 逐字符滚动浮现的文本(仅字符串，非字符串忽略为空) |

## 示例
```tsx
// 默认：在可滚动区域内逐字符拔起(组件自动绑最近可滚动祖先)
<div className="max-h-72 overflow-auto p-6">
  <div className="h-40" />
  <ScrollFloat>瑚琏组件库</ScrollFloat>
  <div className="h-56" />
</div>

// 强错峰 + 主色大标题
<ScrollFloat stagger={0.7} textClassName="text-primary text-3xl md:text-5xl">HULIAN</ScrollFloat>
```

## 禁忌 / 坑

- children 必须是字符串：传入非字符串会被忽略为空，逐字符拆分依赖纯文本。
- 需要可滚动上下文才有「随滚动浮现」效果：组件会自动绑最近可滚动祖先；完全没有滚动容器时降级为进入视口自动浮现（不会卡在 0 进度隐形态），但要逐字符随滚动播放仍需父级可滚动。
- reduced-motion 下直出清晰标题，不做变形动画。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# ScrollReveal

> 滚动显影 · 整段随容器滚过视口逐词 opacity+blur 解析(motion useScroll/useTransform · 每词独立进度区间 · reduced-motion 直呈可读) · typography/text · #animated

## 何时用

长文段落随页面滚动进度逐词从模糊/低透明度解析到清晰，营造「读到哪亮到哪」的阅读节奏。要进场一次性逐词淡入（不绑滚动进度）用 [SplitText](https://hulianui.haloritual.com/components/split-text)；要进场一次性模糊解析用 [BlurText](https://hulianui.haloritual.com/components/blur-text)；普通静态段落用 [Prose](https://hulianui.haloritual.com/components/prose)。

## 导入
```ts
import { ScrollReveal } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| baseOpacity | `number` | `0.12` | 静息（未滚入解析区间）时每词的基础透明度，0~1；越小入场对比越强 |
| baseRotation | `number` | `3` | 整段进入时的初始旋转角（deg），随进度回正到 0；设 0 关闭 |
| enableBlur | `boolean` | `true` | 是否伴随模糊解析：未揭示词带模糊随进度消散 |
| blurStrength | `number` | `4` | `enableBlur` 为真时词的起始模糊半径（px），随进度降到 0 |

其余 `<p>` 原生属性透传；`onDrag/onDragStart/onDragEnd/onAnimationStart` 因与 motion 签名冲突被剔除。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | `string` | 要随滚动逐词显影的整段文本，仅字符串（内部按空白拆词并保留分隔符） |

## 示例
```tsx
<ScrollReveal className="text-xl font-semibold">
  When you scroll this block the words resolve from blur to focus one by one.
</ScrollReveal>

<ScrollReveal enableBlur={false} baseRotation={6} className="text-xl font-semibold">
  纯透明度与旋转 适合追求克制质感的标题段落
</ScrollReveal>
```

## 禁忌 / 坑

- 效果由滚动进度驱动：组件必须处在可滚动上下文里、上下留出滚动空间才能看到逐词显影；放在不滚动的容器里只会停在静息态。
- `children` 只收纯字符串，不能塞 JSX。
- 尊重 `prefers-reduced-motion`：开启减弱动效时直呈完全可读（不模糊不变透明）。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# ScrollVelocity

> 滚动速度跑马灯文字 · 多行交替方向视差 + 随页面滚动加速/变向、静止匀速漂移(motion 速度值驱动·零额外依赖·reduced-motion 冻结自走帧保留 DOM) · typography/text · #animated

## 何时用

页面区块想要多行平排、随页面滚动加速变向的视差跑马灯横幅时用。要单条沿曲线弯曲走向的跑马灯用 CurvedLoop；ScrollVelocity 专做多行交替方向、速度跟随滚动的水平滚动文字带。

## 导入
```ts
import { ScrollVelocity } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| texts | `string[]` | `[]` | 多行滚动文本，每行独立跑马灯；偶数行左移/奇数行右移形成视差 |
| velocity | `number` | `100`（showcase 演示 `80`） | 基础速度(px/秒)，静止也匀速漂移；负值整体反向 |
| damping | `number` | `50` | 弹簧阻尼，速度变化的黏滞感；越大越慢越稳 |
| stiffness | `number` | `400` | 弹簧刚度，速度跟手的劲道；越大越紧绷 |
| numCopies | `number` | `6` | 每行复制份数(无缝循环铺满)；文本越短需越多份 |
| velocityMapping | `{ input: [number, number]; output: [number, number] }` | `{ input: [0,1000], output: [0,5] }` | 滚动速度→加速因子映射(clamp:false 允许外推) |
| scrollContainerRef | `RefObject<HTMLElement \| null>` | window | 自定义滚动容器；不传监听 window 滚动 |
| className | `string` | — | 透传每行文本 span 的 className(字号/字色/字重) |
| containerClassName | `string` | — | 透传根 section 的 className |
| parallaxStyle | `CSSProperties` | — | 透传每行外层(parallax)容器内联样式 |
| scrollerStyle | `CSSProperties` | — | 透传每行滚动轨(scroller)内联样式 |

## 示例
```tsx
// 单行匀速漂移
<ScrollVelocity texts={["瑚琏组件库"]} velocity={80} />

// 双行交替方向(视差)
<ScrollVelocity texts={["企业级 · 高质量", "原生适配 · 主题感知"]} velocity={70} />
```

## 禁忌 / 坑

- 文本越短越要调大 numCopies：份数不足时铺不满视口宽度会露出空隙。
- 字色/字号走 `className`（作用于每行文本 span），容器整体样式走 `containerClassName`，别混用。
- 默认监听 window 滚动：内嵌在自定义可滚动区时要传 scrollContainerRef，否则速度感应绑错滚动源。
- reduced-motion 下冻结跟滚加速、保留匀速自走帧与 DOM，文本仍可读。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# Shuffle

> 逐字「洗牌解密」文本动画 · 字位先滚乱码再按方向顺序锁定真字 + 视口/悬停/循环触发(零依赖 rAF·reduced-motion 直落终态·token 着色) · typography/text · #animated

## 何时用

需要标题/短句以「乱码滚动→逐字解密」入场（终端、解密、黑客风）时用。要逐字符随鼠标距离形变用 [TextPressure](https://hulianui.haloritual.com/components/text-pressure)；要彩色渐变流光用 [AuroraText](https://hulianui.haloritual.com/components/aurora-text)；只是普通排版文字用 [Text](https://hulianui.haloritual.com/components/text)。

## 导入
```ts
import { Shuffle } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text* | `string` | — | 最终呈现的文本（解析目标） |
| duration | `number` | `0.6` | 整段洗牌时长（秒）；每字解析点 = 字索引/总字数 × duration |
| shuffleDirection | `"left" \| "right"` | `"right"` | 字符解析顺序；left 从右往左定、right 从左往右定 |
| scrambleCharset | `string` | 大写字母+数字+少量符号 | 解析前每字位随机取字闪烁的乱码字符集 |
| loop | `boolean` | `false` | 解析完成后是否清空重洗循环 |
| loopDelay | `number` | `1` | 循环间隔（秒，仅 loop 时生效） |
| triggerOnView | `boolean` | `true` | 是否进入视口才触发（IntersectionObserver） |
| triggerOnce | `boolean` | `true` | triggerOnView 时进入视口是否只触发一次 |
| triggerOnHover | `boolean` | `false` | 鼠标移入时重新洗牌（动画空闲才响应） |
| tag | `"p" \| "span" \| "div" \| "h1" \| "h2" \| "h3" \| "h4"` | `"p"` | 渲染标签 |
| textAlign | `CSSProperties["textAlign"]` | `"center"` | 文本对齐 |
| className | `string` | — | 合并到根元素的类名 |
| style | `CSSProperties` | — | 行内样式（与 textAlign 合并） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onShuffleComplete | `() => void` | 解析完成回调（loop 时每轮结束都触发） |

## 示例
```tsx
// 悬停重洗（关掉视口触发，靠 hover 主动触发）
<Shuffle
  text="HULIAN"
  triggerOnView={false}
  triggerOnHover
  className="text-3xl font-semibold tracking-wide"
/>

// 循环 + 自定义字符集（十六进制感）
<Shuffle
  text="0xC0FFEE"
  loop
  loopDelay={1.2}
  scrambleCharset="0123456789ABCDEF"
  duration={0.7}
  triggerOnView={false}
/>
```

## 禁忌 / 坑

- `triggerOnView` 默认 `true`：组件不在视口内永远不会播放。在固定可见的舞台里调试时记得关掉它（`triggerOnView={false}`），否则会以为没生效。
- `triggerOnHover` 仅在动画空闲时响应，洗牌进行中再移入不会打断重洗。
- reduced-motion 下直接落到终态文本，不播放洗牌——无障碍友好，但视觉演示需注意系统设置。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# Snippet

> 代码片段 · 命令提示符 + 一键复制(剪贴板+反馈) · typography/code

## 何时用

展示单行命令/代码片段，前置提示符 + 一键复制，适合安装命令、CLI 指令。多行代码块用 [CodeBlock](https://hulianui.haloritual.com/components/code-block)；纯内联标识文字用 [Code](https://hulianui.haloritual.com/components/code)。

## 导入
```ts
import { Snippet } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | — | 复制到剪贴板的文本；缺省时取 children（仅当为字符串时） |
| symbol | `string ｜ null` | `"$"` | 命令提示符；传 `null` 不显示，适合非命令片段 |
| lang | `string` | — | 语法着色语言（如 `"tsx"`/`"bash"`），仅 children 为字符串时生效 |
| highlight | `boolean` | `true` | 是否语法着色，仅 children 为字符串时生效 |
| className | `string` | — | 容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 显示内容（字符串或节点） |

## 示例
```tsx
<Snippet>pnpm add @hulianui/ui</Snippet>

// 非命令片段，去掉提示符
<Snippet symbol={null}>const theme = useTheme()</Snippet>
```

## 禁忌 / 坑

- `text`/`lang`/`highlight` 的着色与复制兜底仅在 `children` 为**字符串**时生效；传入节点时只能手动给 `text` 指定复制内容。

## 相关
[Code](https://hulianui.haloritual.com/components/code) · [CodeBlock](https://hulianui.haloritual.com/components/code-block) · [CodeDiff](https://hulianui.haloritual.com/components/code-diff) · [Kbd](https://hulianui.haloritual.com/components/kbd) · [Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading)

<!-- ════════════════════════════════════════════════════════ -->
# SparklesText

> 星闪文字 · 随机小星脉冲(客户端生成) + token · typography/text · #animated

## 何时用

给一小段标题/品牌词围绕随机小星脉冲点缀（客户端随机生成星位）。要文字本体彩色流动用 [AuroraText](https://hulianui.haloritual.com/components/aurora-text) / [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)；要横扫高光徽标用 [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)；静态文本用 [Text](https://hulianui.haloritual.com/components/text)。客户端组件（随机星位 + 动画），源文件已含 `"use client"`。

## 导入
```ts
import { SparklesText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `[primary, chart-1]` token | 星色数组 |
| sparklesCount | `number` | `8` | 星星数量 |

继承 `ComponentPropsWithoutRef<"span">`（除 `color`），如 `className` / `style`。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 要渲染的文字 |

## 示例
```tsx
<SparklesText className="text-4xl font-bold text-foreground">瑚琏 Hulian</SparklesText>
```

## 禁忌 / 坑

- 星位在客户端随机生成，不要期待 SSR 与首帧水合后位置一致；本身是 `"use client"` 组件，作为子组件可嵌进 server 页，但不能当纯 RSC 用。
- 自定义 `colors` 用瑚琏 token 时须带 `--color-` 前缀才能在星点着色里解析（见 hulian token 规范）。
- 星数过大（`sparklesCount` 偏高）会增加动画节点数，小面积文字上密集星点可能显得杂乱。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# SplitText

> 切字进场 · 文本切字/词 + 滚入视口逐段错峰位移淡入(motion · useInView 触发一次 · aria-label 整段读屏友好 · reduced-motion 直呈终态) · typography/text · #animated

## 何时用

标题/Hero 文案首次滚入视口时做逐字（或逐词）错峰位移淡入，强调登场感。要逐段「从模糊解析到清晰」用 [BlurText](https://hulianui.haloritual.com/components/blur-text)；要随滚动进度持续逐词显影（而非进场一次）用 [ScrollReveal](https://hulianui.haloritual.com/components/scroll-reveal)；只要普通静态标题用 [Heading](https://hulianui.haloritual.com/components/heading)。

## 导入
```ts
import { SplitText } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text * | `string` | — | 要逐段进场的文本 |
| splitType | `"char" \| "word"` | `"char"` | 切分粒度：char 逐字（中文友好）/ word 逐词（按空白切） |
| from | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | 进场方向，每段从该方向位移入场 |
| delay | `number` | `40` | 相邻段错峰毫秒，越大波浪推进越慢 |
| duration | `number` | `0.5` | 单段动画时长（秒） |

其余 `<span>` 原生属性（`className` 等）透传；`onDrag/onDragStart/onDragEnd/onAnimationStart` 因与 motion 签名冲突被剔除。

## 示例
```tsx
<SplitText text="让开发更快更稳更美" className="text-3xl font-bold text-foreground" />

<SplitText
  text="Build faster with 瑚琏"
  splitType="word"
  from="left"
  className="text-3xl font-bold text-primary"
/>
```

## 禁忌 / 坑

- `useInView` 只触发一次：进场动画播完不再重放。文档里反复观察需更换 `key` 强制 remount。
- `text` 只收纯字符串（非 children），不能塞 JSX。
- 尊重 `prefers-reduced-motion`：用户开启减弱动效时直呈终态、不播位移淡入。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# Text

> 文本 · size/tone/weight + 单行省略/多行截断 + as 多态(纯皮肤·零依赖·RSC) · typography/text

## 何时用

正文、辅助说明、行内文本——需要统一字号/语义色调/字重并支持单行省略或多行截断时用 Text。标题层级（h1–h6 语义 + 标题尺寸）用 [Heading](https://hulianui.haloritual.com/components/heading)；整段富文本/Markdown 排版用 [Prose](https://hulianui.haloritual.com/components/prose)。

## 导入
```ts
import { Text } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| as | `ElementType` | `"p"` | 渲染的元素标签 |
| size | `"xs" \| "sm" \| "base" \| "lg" \| "xl"` | `"base"` | 字号 |
| tone | `"default" \| "muted" \| "primary" \| "danger"` | `"default"` | 语义色调（明暗自适配） |
| weight | `"normal" \| "medium" \| "semibold" \| "bold"` | `"normal"` | 字重 |
| truncate | `boolean` | `false` | 单行省略号截断 |
| lineClamp | `number` | — | 多行截断（最多 n 行后省略号）；设置后优先于 truncate |

继承 `HTMLAttributes<HTMLElement>`（已 Omit `color`，色调走 tone）。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 文本内容 |

## 示例
```tsx
// 语义色调
<Text tone="muted">辅助说明</Text>
<Text tone="danger">危险提示</Text>

// 多行截断
<div className="max-w-xs">
  <Text lineClamp={2}>{longText}</Text>
</div>
```

## 禁忌 / 坑

暂无已知坑。`truncate`（单行省略）依赖容器有确定宽度才会触发；`lineClamp` 与 `truncate` 同设时 `lineClamp` 优先。候选坑列表（bff-refresh/cjk-tokenizer/menubar/pdf/regex/sliding-pill/swiftui 各项）均与本纯皮肤文本组件无关，已剔除。

## 相关
[Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text) · [AnimatedGradientText](https://hulianui.haloritual.com/components/animated-gradient-text)

<!-- ════════════════════════════════════════════════════════ -->
# TextCursor

> 光标拖尾文字特效组件 · 在容器内移动光标时沿轨迹按间距落下一串字形并随机微浮动淡出回收（沿方向旋转 / emoji / 自定义间距上限）(零依赖·motion 运行时·reduced-motion 去浮动) · typography/text · #animated

## 何时用

需要鼠标在某区域内划过时留下一串字形/emoji 拖尾（趣味落地页、hero 互动区）时用。它是「光标在容器内移动」的拖尾，要做光标本身的果冻形态用 [BlobCursor](https://hulianui.haloritual.com/components/blob-cursor)；要逐字符压感形变用 [TextPressure](https://hulianui.haloritual.com/components/text-pressure)。

## 导入
```ts
import { TextCursor } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLDivElement>, "children">`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | `"瑚"` | 跟随光标拖出的字形；可传短字符串或 emoji（如 `"✨"`） |
| spacing | `number` | `80` | 相邻字形最小像素间距；光标每移动满 spacing 才落一个新字形，越小越密 |
| followMouseDirection | `boolean` | `true` | 字形是否沿移动方向旋转对齐（atan2）；关则保持水平 |
| randomFloat | `boolean` | `true` | 字形落定后随机微浮动（位移+轻旋呼吸）；reduced-motion 下自动停用仅保留淡出 |
| exitDuration | `number` | `0.5` | 字形淡出秒数（opacity 过渡时长） |
| removalInterval | `number` | `30` | 拖尾消减轮询间隔（ms）；光标静止 ~100ms 后每隔该值从队首移除一个字形 |
| maxPoints | `number` | `5` | 同时存在的字形上限，超出丢弃最旧 |
| fontSize | `string` | `"1.875rem"` | 字号（任意 CSS 长度） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 容器内居中内容（提示语/标题），不影响拖尾层 |

## 示例
```tsx
// 默认：在区域内移动光标即留「瑚」字拖尾
<div className="relative h-64 overflow-hidden rounded-xl">
  <TextCursor>
    <p className="text-sm text-muted">在此区域内移动光标 →</p>
  </TextCursor>
</div>

// emoji + 大间距（稀疏拖尾）
<TextCursor text="✨" spacing={130} />
```

## 禁忌 / 坑

- 父容器必须有明确高度且 `overflow-hidden`、自身是定位上下文：拖尾层是绝对定位铺满容器，无高度则不可见。
- 拖尾只在「容器内」移动光标时落字，光标移出容器即停止并逐渐回收。
- reduced-motion 下去掉随机浮动，字形落定后仅做淡出。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# TextPressure

> 逐字符"压感"标题 · 字形随鼠标距离实时插值字重/宽度/倾斜 + 透明度(零依赖 RAF·token 配色·reduced-motion·系统字体兜底) · typography/text · #animated

## 何时用

需要大标题随鼠标靠近做逐字字重/宽度/倾斜「压感」形变（hero 主标题、互动品牌字）时用。它响应「距离」做轴插值；要随鼠标距离插值可变字体轴并支持容器坐标系/三档衰减用 [VariableProximity](https://hulianui.haloritual.com/components/variable-proximity)；要乱码解密入场用 [Shuffle](https://hulianui.haloritual.com/components/shuffle)。

## 导入
```ts
import { TextPressure } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text | `string` | `"Compressa"` | 渲染文字（逐字符响应鼠标压力形变） |
| fontFamily | `string` | 系统无衬线栈 | 字体族；系统字体下用 scaleX+font-weight+opacity 模拟压感，传入真可变字体则驱动 font-variation-settings |
| fontUrl | `string` | — | 自定义 @font-face 字体 URL；默认不注入远程字体（遵守禁远程资源门禁），仅显式传本地/自托管地址时注入 |
| width | `boolean` | `true` | 是否驱动 wdth 轴 + scaleX 模拟横向挤压 |
| weight | `boolean` | `true` | 是否驱动 wght 轴 / font-weight 随接近度变粗 |
| italic | `boolean` | `true` | 是否驱动 ital 轴（仅可变字体生效） |
| alpha | `boolean` | `false` | 是否驱动 opacity（接近时更不透明） |
| flex | `boolean` | `true` | 是否用 flex space-between 横向铺满字符 |
| stroke | `boolean` | `false` | 是否描边（字心透明 + token 描边色，空心轮廓） |
| scale | `boolean` | `false` | 是否纵向拉伸字块填满容器高度 |
| textColor | `string` | `var(--color-foreground)` | 文字颜色（明暗自适配） |
| strokeColor | `string` | `var(--color-primary)` | 描边颜色（stroke=true 时生效） |
| minFontSize | `number` | `24` | 最小字号（px），容器较窄时下限 |
| className | `string` | — | 透传到根 div（cn 合并） |

## 示例
```tsx
// 默认：移入鼠标看逐字压感
<TextPressure text="Compressa" className="flex items-center" />

// 描边空心（token primary 描边）
<TextPressure
  text="Hulian"
  stroke
  strokeColor="var(--color-primary)"
  className="flex items-center"
/>
```

## 禁忌 / 坑

- `width`/`italic` 轴需真正的可变字体（含 wght/wdth/ital 轴）才有完整效果；系统字体下 width 退化为 scaleX 模拟、italic 基本无效。这是字体能力限制，不是 bug。
- 喂给 `strokeColor`/`textColor` 的 token 必须带 `--color-` 前缀（如 `var(--color-primary)`），裸 `var(--primary)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- 默认不注入远程字体；要用自托管可变字体须显式传 `fontUrl`。
- reduced-motion 下不随鼠标形变。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# TrueFocus

> 真实焦点 · 句中一词清晰余词模糊 + 焦点循环移动 + 四角框跟随(测量 rect 定位 · 角框吃 chart token · manualMode 悬停聚焦 · reduced-motion 全清晰) · typography/text · #animated

## 何时用

短句逐词聚焦：当前词清晰、其余模糊，四角括号框跟随焦点循环移动，强调「逐词扫读」。要逐词从模糊解析到清晰（不带焦点框、不循环）用 [BlurText](https://hulianui.haloritual.com/components/blur-text)；要随滚动进度显影用 [ScrollReveal](https://hulianui.haloritual.com/components/scroll-reveal)；普通标题用 [Heading](https://hulianui.haloritual.com/components/heading)。

## 导入
```ts
import { TrueFocus } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sentence | `string` | `"True Focus"` | 整句文本，按 `separator` 切词后逐词聚焦 |
| separator | `string` | `" "` | 切词分隔符（传给 `String.prototype.split`） |
| blurAmount | `number` | `5` | 失焦词的模糊半径（px） |
| borderColor | `string` | `"var(--color-chart-1)"` | 四角括号描边色（CSS color，建议吃 token），须带 `--color-` 前缀或合法 CSS 颜色 |
| animationDuration | `number` | `1.2` | 单次对焦切换的动画 / 停留秒数 |
| pauseBetweenAnimations | `number` | `0.6` | 自动模式下两次切换之间的停顿（秒） |
| manualMode | `boolean` | `false` | 为 true 时不自动轮播，改由鼠标悬停某词来对焦 |

其余 `<div>` 原生属性透传。

## 示例
```tsx
<TrueFocus sentence="True Focus Effect" className="text-3xl font-bold text-foreground" />

<TrueFocus
  sentence="瑚琏 真实 焦点"
  borderColor="var(--color-primary)"
  blurAmount={6}
  className="text-3xl font-bold text-foreground"
/>
```

## 禁忌 / 坑

- 角框靠测量各词 rect 定位：父容器需给足布局空间（建议固定高度容器），避免换行/挤压让框错位。
- `borderColor` 须带 `--color-` 前缀或合法 CSS 颜色；裸 `var(--primary)` 在本 Tailwind v4 设定下不解析。
- 尊重 `prefers-reduced-motion`：开启减弱动效时全词清晰、不循环聚焦。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# TypingAnimation

> 打字机 · 逐字 + 闪烁光标 + 进入视口触发 · typography/text · #animated

## 何时用

逐字"打"出一段文本，带闪烁光标，默认进入视口才开始（适合首屏标语 / hero 文案）。要在固定句式里循环换词用 [WordRotate](https://hulianui.haloritual.com/components/word-rotate)；静态文本用 [Text](https://hulianui.haloritual.com/components/text)。客户端组件（用 state + IntersectionObserver），源文件已含 `"use client"`。

## 导入
```ts
import { TypingAnimation } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text* | `string` | — | 要逐字打出的文本 |
| duration | `number` | `80` | 每字毫秒 |
| delay | `number` | `0` | 开始前延迟毫秒 |
| startOnView | `boolean` | `true` | 进入视口才开始；设 `false` 立即开始 |
| showCursor | `boolean` | `true` | 显示闪烁光标 |

继承 `ComponentPropsWithoutRef<"span">`（除 `children`），如 `className` / `style`。

## 示例
```tsx
<TypingAnimation
  text="瑚琏 Hulian — 吸取式聚合设计系统"
  className="text-2xl font-semibold text-foreground"
/>
```

立即开始（不等进入视口，常用于已在首屏内）：
```tsx
<TypingAnimation text="瑚琏 Hulian" startOnView={false} duration={60} />
```

## 禁忌 / 坑

- `startOnView` 默认 `true`：若组件初始就在视口外且页面不滚动（如截图/headless 验收），打字永不触发、看似空白——验收/首屏内场景显式传 `startOnView={false}`。
- 客户端组件，含 `"use client"`；可作为子组件嵌进 server 页，但不能当纯 RSC 用。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# VariableProximity

> 鼠标邻近驱动的逐字可变字体文本 · 按距离插值 font-variation-settings（wght/opsz 等轴）+ linear/exponential/gaussian 三档衰减（零依赖 RAF · reduced-motion 定格 from · sr-only 完整朗读） · typography/text · #animated

## 何时用

需要文字按鼠标到每个字形的距离实时插值可变字体轴（wght/opsz 等），且要指定容器坐标系与衰减曲线时用。它面向「可变字体轴插值」，支持 from/to 任意轴；要更轻量的压感标题（系统字体兜底、scaleX 模拟）用 [TextPressure](https://hulianui.haloritual.com/components/text-pressure)；要乱码解密入场用 [Shuffle](https://hulianui.haloritual.com/components/shuffle)。

## 导入
```ts
import { VariableProximity } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| label* | `string` | — | 渲染文本（按词与字拆分，空格保留为不可断词隙）；sr-only 副本完整朗读 |
| fromFontVariationSettings* | `string` | — | 鼠标远端时的可变轴设置，如 `"'wght' 400, 'opsz' 9"`（需可变字体才有视觉变化） |
| toFontVariationSettings* | `string` | — | 鼠标贴近时的目标轴设置，逐轴向此插值；缺省轴回退到 from 值 |
| containerRef | `RefObject<HTMLElement \| null>` | — | 计算鼠标相对坐标的参照容器；缺省回退到视口坐标 |
| radius | `number` | `50` | 影响半径（px）；超出则恢复 from 设置 |
| falloff | `"linear" \| "exponential" \| "gaussian"` | `"linear"` | 衰减曲线；exponential 更陡、gaussian 中心更聚拢柔和 |
| className | `string` | — | 合并到根 span 的额外类名 |
| style | `CSSProperties` | — | 合并到根 span 的内联样式 |

> 注：showcase controls 默认演示用 `radius={90}`，但接口默认值为 `50`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `React.MouseEventHandler<HTMLSpanElement>` | 点击根 span 的回调 |

## 示例
```tsx
function Demo() {
  const ref = useRef<HTMLDivElement>(null);
  return (
    <div ref={ref} className="relative flex items-center justify-center">
      <VariableProximity
        label="把鼠标移到这里 Hover me"
        fromFontVariationSettings="'wght' 400, 'opsz' 9"
        toFontVariationSettings="'wght' 900, 'opsz' 40"
        containerRef={ref}
        radius={90}
        falloff="linear"
        className="text-3xl font-medium"
      />
    </div>
  );
}
```

## 禁忌 / 坑

- 视觉变化依赖真正的可变字体：`from/to` 里写的轴（如 `wght`/`opsz`）必须是当前字体真实支持的轴，否则鼠标靠近无变化。这是字体能力限制，不是组件 bug。
- `containerRef` 决定距离坐标系：不传则按视口坐标算距离，文字在页面中部时手感会偏；通常应指向包裹本组件的盒子。
- `toFontVariationSettings` 只插值 `from` 中出现的轴，from 没列的轴不会变。
- reduced-motion 下定格在 from 设置，不随鼠标插值。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)

<!-- ════════════════════════════════════════════════════════ -->
# WordRotate

> 轮换词 · motion 进出场 + reduced-motion · typography/text · #animated

## 何时用

在一句固定文案里循环切换若干词（"让开发 更快/更稳/更美"），用 motion 进出场动画。要逐字打字效果用 [TypingAnimation](https://hulianui.haloritual.com/components/typing-animation)；静态文本用 [Text](https://hulianui.haloritual.com/components/text)。本组件是客户端组件（用 motion + state），源文件已含 `"use client"`。

## 导入
```ts
import { WordRotate } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| words* | `string[]` | — | 轮换的词数组 |
| duration | `number` | `2500` | 每词停留毫秒 |

继承 `ComponentPropsWithoutRef<"span">`（除 `children` 及 motion 冲突的 `onDrag`/`onDragStart`/`onDragEnd`/`onAnimationStart`），如 `className` / `style`。

## 示例
```tsx
<div className="text-3xl font-bold text-foreground">
  让开发 <WordRotate words={["更快", "更稳", "更美", "瑚琏"]} className="text-primary" />
</div>
```

## 禁忌 / 坑

- 透传给 `motion.span`，故公开类型剔除了 `onDrag`/`onDragStart`/`onDragEnd`/`onAnimationStart`（motion 12 把它们重定义为手势/动画签名，与 DOM 同名 handler 冲突）——别尝试传这几个。
- 客户端组件，不能在纯 RSC 边界直接当 server 组件用；放进 server 页时它本身带 `"use client"` 可正常作为子组件渲染。
- 尊重 `prefers-reduced-motion`，用户开启减弱动效时进出场会退化。

## 相关
[Text](https://hulianui.haloritual.com/components/text) · [Heading](https://hulianui.haloritual.com/components/heading) · [Prose](https://hulianui.haloritual.com/components/prose) · [Markdown](https://hulianui.haloritual.com/components/markdown) · [AuroraText](https://hulianui.haloritual.com/components/aurora-text) · [AnimatedShinyText](https://hulianui.haloritual.com/components/animated-shiny-text)


# ━━━━━━━━ 表单 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# Button

> 按钮 · CVA 变体 + press 动效 · forms/button

## 何时用

最常用的操作按钮，含 solid/outline/ghost/link 变体、brand/danger 色调、loading 态与 press 缩放动效。需要特效吸睛 CTA 用 [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)/[RainbowButton](https://hulianui.haloritual.com/components/rainbow-button)/[PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button)；多按钮成组用 [ButtonGroup](https://hulianui.haloritual.com/components/button-group)；只要按钮样式不要 `<button>` 语义用 `buttonVariants(...)` 拿 className。

## 导入
```ts
import { Button, buttonVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"solid" ｜ "outline" ｜ "ghost" ｜ "link"` | `"solid"` | 视觉变体 |
| tone | `"brand" ｜ "danger"` | `"brand"` | 语义色调 |
| size | `"sm" ｜ "md" ｜ "lg" ｜ "icon" ｜ "iconSm"` | `"md"` | 尺寸；icon/iconSm 为正方形图标按钮 |
| loading | `boolean` | `false` | 加载态，显示 spinner 并自动禁用 |
| ...ButtonHTMLAttributes | `ButtonHTMLAttributes<HTMLButtonElement>` | — | 透传原生属性（disabled、type 等） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 点击回调，经 `ButtonHTMLAttributes` 透传 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮文案 |
| render | `ReactElement` | 渲染为自定义元素（如 `<a>`/Next `<Link>`），用于按钮样式的链接 CTA；样式与 `aria-disabled` 合并进该元素 |

## 示例
```tsx
<Button>默认</Button>
<Button variant="outline">描边</Button>
<Button tone="danger">危险</Button>
<Button loading>加载中</Button>
```

## 禁忌 / 坑

- `render` 模式为降低风险**不套 motion**，故无 press 缩放动效（颜色/hover 过渡仍在）；文案优先取 Button 的 children。
- `loading` 会自动禁用按钮，无需再手动加 `disabled`。
- 自定义往按钮里塞图标+文字（尤其在特效按钮里）若图标掉到下一行，是 Tailwind Preflight 把 `svg{display:block}` 撑成块级所致，见 [[tailwind-preflight-svg-block-breaks-icon-text-in-nonflex-button]]——容器要 `inline-flex`，本 Button 已处理，自搓 wrapper 时注意。

## 相关
[ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# ButtonGroup

> 按钮组 · 把若干 Button 连排成一体(抹内侧圆角/合并相邻边框/hover 项抬层) 或分离编组 + 横竖向 · 工具栏分段/拆分按钮/步进器(纯布局壳·不接管子按钮变体) · forms/button

## 何时用

把多个相关 [Button](https://hulianui.haloritual.com/components/button) 编为一组：工具栏分段、拆分按钮（主操作 + 更多）、步进器（减/数/加）。`attached`（默认）让子按钮贴合成一体；想要语义分组但保留间距用 `attached={false}`。它只是纯布局壳，不接管子按钮的 `variant`/`size`——子按钮变体仍各自传。单个独立按钮直接用 Button。

## 导入
```ts
import { ButtonGroup } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| orientation | `"horizontal" ｜ "vertical"` | `"horizontal"` | 主轴方向 |
| attached | `boolean` | `true` | true=子按钮贴合成一体（抹内侧圆角/合并边框/hover 抬层）；false=留 gap 仅作语义分组 |
| gap | `"sm" ｜ "md"` | `"sm"` | 子项间距档（仅 `attached={false}` 生效） |
| className | `string` | — | 透传根节点类名 |
| aria-label | `string` | — | 组的无障碍标签 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 一般放若干 `<Button>`；也可混入 Dropdown/Tooltip 包裹的按钮 |

## 示例
```tsx
<ButtonGroup aria-label="对齐方式">
  <Button variant="outline" size="icon" aria-label="左对齐"><AlignLeft className="size-4" /></Button>
  <Button variant="outline" size="icon" aria-label="居中"><AlignCenter className="size-4" /></Button>
  <Button variant="outline" size="icon" aria-label="右对齐"><AlignRight className="size-4" /></Button>
</ButtonGroup>
```
```tsx
{/* 拆分按钮：主操作 + 更多 */}
<ButtonGroup aria-label="保存">
  <Button>保存</Button>
  <Button size="icon" aria-label="更多保存选项"><ChevronDown className="size-4" /></Button>
</ButtonGroup>
```

## 禁忌 / 坑

暂无已知坑。注意 `gap` 仅在 `attached={false}` 时生效；连排态（`attached`）由组件自行抹圆角/合并边框，不要再给子按钮加外边距。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# Calendar

> 日历 · MUI X 桥(DateCalendar) + 对外 ISO 字符串受控 + 瑚琏 token · forms/datetime · MUI 桥

## 何时用

需要在页面内**常驻铺开**一个月历面板让用户挑日期时用（如日程、筛选侧栏）。若想要点击触发、弹层选日期且带输入框，用 [DatePicker](https://hulianui.haloritual.com/components/date-picker)；要选一段区间用 [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker)；要连时间一起选用 [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker)。

## 导入
```ts
import { Calendar } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| null` | — | ISO 字符串受控值；传入即受控 |
| defaultValue | `string` | — | ISO 字符串非受控默认值 |
| minDate | `string` | — | 可选最早日期（ISO），早于此禁选 |
| maxDate | `string` | — | 可选最晚日期（ISO），晚于此禁选 |
| disabled | `boolean` | `false` | 整体禁用 |
| readOnly | `boolean` | `false` | 只读：可查看不可改 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(iso: string \| null) => void` | 受控回调，回传 ISO 或 null（替代 MUI 的 onChange） |

## 示例
```tsx
function Demo() {
  const [v, setV] = useState<string | null>("2026-06-03");
  return <Calendar value={v} onValueChange={setV} />;
}
```
```tsx
<Calendar defaultValue="2026-06-15" />
```

## 禁忌 / 坑

- 受控/非受控二选一：给了 `value` 就走受控、必须配 `onValueChange` 才能改动；只想要初值用 `defaultValue`，别同时给。
- 对外值恒为 ISO 字符串（非 Date 对象），回调 `onValueChange` 也回传 ISO 或 null，跨组件传值直接用字符串即可。

## 相关
[DatePicker](https://hulianui.haloritual.com/components/date-picker) · [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker) · [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker) · [TimeField](https://hulianui.haloritual.com/components/time-field) · [Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)

<!-- ════════════════════════════════════════════════════════ -->
# Cascader

> 级联选择 · 触发器 + Popover 横向逐级面板列 + 路径数组受控 + click/hover 展开 + changeOnSelect · 复用树引擎核 · forms/advanced

## 何时用

省/市/区、分类/子类、组织层级等「有父子层级、要逐级下钻选一条完整路径」的场景用。值是从根到所选节点的 `key` 路径数组。默认须选到叶子；开 `changeOnSelect` 允许任意层提交。若数据是扁平的单层选项，用 [Combobox](https://hulianui.haloritual.com/components/combobox)/[Listbox](https://hulianui.haloritual.com/components/listbox) 即可，不必引入级联。

## 导入
```ts
import { Cascader, flattenLeafPaths, filterLeafPaths, type CascaderLeafPath } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes* | `TreeNode[]` | — | 层级数据（复用 tree-core 的 `TreeNode`，含 `key`/`label`/`children`/`disabled`） |
| value | `string[]` | — | 受控路径（从根到所选节点的 key 数组） |
| defaultValue | `string[]` | — | 非受控初始路径 |
| expandTrigger | `"click" \| "hover"` | `"click"` | 逐级展开触发方式 |
| changeOnSelect | `boolean` | `false` | 任意层节点都可提交（非仅叶子） |
| showSearch | `boolean` | — | 浮层顶部出搜索框：扁平成叶子路径模糊匹配，命中行选中即提交全路径 |
| searchPlaceholder | `string` | — | 搜索框占位符 |
| placeholder | `string` | — | 触发器占位符 |
| disabled | `boolean` | — | 禁用 |
| invalid | `boolean` | — | 校验失败态 |
| size | `"sm" \| "md" \| "lg"` | — | 触发器尺寸 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(path: string[], nodes: TreeNode[]) => void` | 选中变化，回传 key 路径与对应节点链 |

## 示例
```tsx
const [value, setValue] = useState<string[]>([]);
<Cascader
  nodes={nodes}
  expandTrigger="click"
  value={value}
  onChange={(path) => setValue(path)}
/>
```

任意层可提交（如选到省或市即可）：
```tsx
<Cascader nodes={nodes} changeOnSelect value={value} onChange={(path) => setValue(path)} />
```

## 禁忌 / 坑

- `value` 是**完整 key 路径数组**（如 `["zhejiang","hangzhou","xihu"]`），不是单个叶子 key；回填时要给全路径，否则展开列对不上。
- `disabled` 的节点不可选、其子树也不会因它而展开。
- `onChange` 第二参是节点链（`TreeNode[]`），需要 label 做回显时取它而非自己再查表。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Checkbox

> 复选框 · 三态(含半选) + Base UI · forms/basic

## 何时用

单个布尔勾选（同意条款、记住我），或带半选（`indeterminate`）的「全选」父框。多个互相协调的复选项用 [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) 包裹（值数组统一管理）；二选一的开关用 [Switch](https://hulianui.haloritual.com/components/switch)；互斥单选用 [Radio](https://hulianui.haloritual.com/components/radio)。

## 导入
```ts
import { Checkbox } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| checked | `boolean` | — | 受控勾选态 |
| defaultChecked | `boolean` | — | 非受控初始勾选态 |
| indeterminate | `boolean` | `false` | 第三态：半选（Base UI 原生 indeterminate） |
| disabled | `boolean` | `false` | 禁用 |
| required | `boolean` | `false` | 必填 |
| name | `string` | — | 表单字段名 |
| value | `string` | — | 表单值；放进 CheckboxGroup 时按此 value 匹配成员 |
| id | `string` | — | 关联 label 的 id |
| className | `string` | — | 落在 Checkbox.Root |
| tabIndex | `number` | — | 透传到 Checkbox.Root（树场景置 -1 退出 Tab 序，焦点由容器 roving 接管） |
| aria-label | `string` | — | 无 label 时的无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCheckedChange | `(checked: boolean) => void` | 勾选变化回调（瑚琏收敛签名，丢 eventDetails） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 盒右 inline label（`<label>` 原生关联） |

## 示例
```tsx
<Checkbox defaultChecked label="记住我" />
```
```tsx
{/* 受控半选消解 */}
<Checkbox
  checked={checked}
  indeterminate={indeterminate}
  onCheckedChange={(c) => { setChecked(c); setIndeterminate(false); }}
/>
```

## 禁忌 / 坑

- 放进 [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) 时必须给每个 Checkbox 传 `value`（不是 `name`）——见 [[base-ui-checkbox-group-matches-members-by-value-not-name]]：Base UI rc.0 按 `value` 匹配组成员，传 `name` 会让 defaultValue/value/onValueChange 全部静默失效（框照常渲染但勾选/回调全空）。
- `indeterminate` 是独立第三态，点击后通常应手动消解为确定态（`setIndeterminate(false)`）。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# CheckboxGroup

> 复选组 · Base UI 值数组协调 + 复用瑚琏 Checkbox · forms/basic

## 何时用

一组相关复选项，需用一个 value 数组统一管理勾选状态（多选筛选、兴趣标签）。单个独立勾选用 [Checkbox](https://hulianui.haloritual.com/components/checkbox)；互斥单选用 [Radio](https://hulianui.haloritual.com/components/radio)；下拉式多选用 [Select](https://hulianui.haloritual.com/components/select)。子项放瑚琏 [Checkbox](https://hulianui.haloritual.com/components/checkbox)，每个带 `value`，组按 value 匹配成员。

## 导入
```ts
import { CheckboxGroup } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string[]` | — | 受控：已勾选项的 value 数组 |
| defaultValue | `string[]` | — | 非受控初始勾选项 |
| disabled | `boolean` | `false` | 下发禁用到组内全部 Checkbox |
| orientation | `"vertical" ｜ "horizontal"` | `"vertical"` | 排列方向 |
| className | `string` | — | 透传根节点类名 |
| aria-label | `string` | — | 组的无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string[]) => void` | 勾选变化回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 子项为瑚琏 Checkbox（每个带 value） |

## 示例
```tsx
<CheckboxGroup defaultValue={["apple"]}>
  <Checkbox value="apple" label="苹果" />
  <Checkbox value="banana" label="香蕉" />
  <Checkbox value="cherry" label="樱桃" />
</CheckboxGroup>
```
```tsx
{/* 受控 */}
const [v, setV] = useState<string[]>(["apple"]);
<CheckboxGroup value={v} onValueChange={setV} orientation="horizontal">
  <Checkbox value="apple" label="苹果" />
  <Checkbox value="banana" label="香蕉" />
</CheckboxGroup>
```

## 禁忌 / 坑

- 每个子 Checkbox 必须传 `value`（不是 `name`）——见 [[base-ui-checkbox-group-matches-members-by-value-not-name]]：Base UI rc.0 CheckboxGroup 按子项 `value` 匹配成员，用 `name` 会让 defaultValue/value/onValueChange 全部静默失效（框渲染正常但勾选/回调全空，极易误判已装好）。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [Radio](https://hulianui.haloritual.com/components/radio) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# Choicebox

> 卡片选择 · 复合 ChoiceboxGroup/Choicebox(标题/描述/图标卡片) · 单选(radio)/多选(checkbox)对称 + 受控非受控 + 网格列数 · 隐藏原生 input 承载键盘与 a11y(单选方向键漫游/多选空格切换) · 套餐/支付方式/订阅档位 · forms/advanced

## 何时用

每个选项需要标题+描述+图标的卡片化呈现时用（订阅套餐、支付方式、主题档位）。若选项只是一行文字用普通 Radio/Checkbox；若是色块用 [ColorSwatchPicker](https://hulianui.haloritual.com/components/color-swatch-picker)。

## 导入
```ts
import { ChoiceboxGroup, Choicebox } from "@hulianui/ui"
```

## Props

### ChoiceboxGroup

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| string[]` | — | 受控值。单选为 string，多选为 string[] |
| defaultValue | `string \| string[]` | — | 非受控初值 |
| multiple | `boolean` | `false` | true=多选(checkbox 语义) / false=单选(radio 语义) |
| name | `string` | 自动生成 | radio 分组 name（单选用） |
| columns | `number` | `1` | 网格列数 |
| disabled | `boolean` | `false` | 整组禁用 |
| className | `string` | — | 透传到容器 |
| aria-label | `string` | — | 无障碍标签 |

### Choicebox

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `string` | — | 选项值（组内唯一） |
| disabled | `boolean` | `false` | 单项禁用 |
| className | `string` | — | 透传到卡片 |

## Events

### ChoiceboxGroup

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string \| string[]) => void` | 变更回调；单选回传 string，多选回传 string[] |

## Slots

### ChoiceboxGroup

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 一组 Choicebox |

### Choicebox

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 主标题 |
| description | `ReactNode` | 副描述 |
| icon | `ReactNode` | 左侧图标 |
| children | `ReactNode` | 标题/描述外的附加内容（价格、标签等） |

## 示例
```tsx
// 单选套餐卡（受控）
const [v, setV] = useState<string | string[]>("pro");
<ChoiceboxGroup value={v} onValueChange={setV} aria-label="订阅套餐">
  <Choicebox value="free" icon={<Zap />} title="基础版" description="个人项目 · 永久免费">
    <div className="mt-1 font-semibold">¥0</div>
  </Choicebox>
  <Choicebox value="pro" icon={<Rocket />} title="专业版" description="小团队 · 含全部组件" />
</ChoiceboxGroup>

// 多选 + 两列网格
<ChoiceboxGroup multiple columns={2} defaultValue={["a"]}>
  <Choicebox value="a" title="选项 A" description="…" />
  <Choicebox value="b" title="选项 B" description="…" />
</ChoiceboxGroup>
```

## 禁忌 / 坑

- `value`/`defaultValue` 类型随 `multiple`：单选传 `string`，多选传 `string[]`，搞反会导致选中态错乱。
- 在 Choicebox 的 `children` 里放删除/操作钮等交互元素时，会与卡片整体的选中点击冲突，需对子元素阻断冒泡（或用绝对定位让它脱离单选环的点击区）。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# ColorPicker

> 颜色选择 · react-colorful 内核 + HEX/RGB/HSL 多格式输出与切换器(零依赖派生) + 瑚琏 token 皮肤 · forms/advanced

## 何时用

需要让用户从色域面板自由取任意颜色、并能在 HEX/RGB/HSL 间切换输出格式时用。若只是从一组预设色块里单选用更轻的 [ColorSwatchPicker](https://hulianui.haloritual.com/components/color-swatch-picker)。

## 导入
```ts
import { ColorPicker, parseColor, rgbToHex, rgbToHsl, formatColor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string` | — | 受控颜色值。接受 hex / rgb() / hsl() 串，内部统一规范为 hex 作单一真源 |
| defaultValue | `string` | `"#3b82f6"` | 非受控初值 |
| format | `"hex" \| "rgb" \| "hsl"` | — | 受控的输出/展示格式，传入即进入格式受控模式 |
| defaultFormat | `"hex" \| "rgb" \| "hsl"` | `"hex"` | 非受控初始格式 |
| disabled | `boolean` | `false` | 禁用：罩层 + 屏蔽交互 |
| showInput | `boolean` | `true` | 是否显示文本输入 |
| showFormatSwitcher | `boolean` | `true` | 是否显示 HEX/RGB/HSL 格式切换器 |
| className | `string` | — | 透传到外壳 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string) => void` | 变更回调，参数为**当前所选格式**的字符串；切换格式也会触发 |
| onFormatChange | `(format: ColorFormat) => void` | 格式切换回调 |

## 示例
```tsx
// 受控（注意 onValueChange 给的是当前格式串）
const [v, setV] = useState("#3b82f6");
<ColorPicker value={v} onValueChange={setV} />

// 固定 RGB 输出、隐藏切换器
<ColorPicker defaultValue="#3b82f6" defaultFormat="rgb" showFormatSwitcher={false} />
```

## 禁忌 / 坑

- `onValueChange` 回传的是**当前所选格式**的字符串（hex/rgb/hsl），且切换格式本身也会触发回调——别假设永远是 hex。内部以 hex 为真源，但回调按 format 输出。
- 受控 `value` 可传任意 hex/rgb()/hsl() 串，组件内部归一为 hex 再渲染，回写时再转回所选格式。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# ColorSwatchPicker

> 预设色块单选 · base-ui RadioGroup 换皮(方向键 a11y) + 选中 ring + mix-blend 勾(零依赖) · forms/advanced

## 何时用

从一组固定预设色（品牌色板、标签颜色）里单选一个时用，本质是 RadioGroup 的色块皮肤，自带方向键漫游。若需自由取任意颜色用 [ColorPicker](https://hulianui.haloritual.com/components/colorpicker)。

## 导入
```ts
import { ColorSwatchPicker } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors* | `string[]` | — | 预设色块列表，任意 CSS 颜色串（hex / rgb / hsl / 具名色） |
| value | `string` | — | 受控选中值（须与 colors 中某项严格相等） |
| defaultValue | `string` | — | 非受控初始选中值 |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 色块尺寸 |
| disabled | `boolean` | `false` | 整组禁用 |
| className | `string` | — | 透传到容器 |
| aria-label | `string` | — | 无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(color: string) => void` | 选中变更回调 |

## 示例
```tsx
const PALETTE = ["#ef4444", "#f97316", "#eab308", "#22c55e", "#3b82f6", "#8b5cf6"];
const [v, setV] = useState("#3b82f6");
<ColorSwatchPicker colors={PALETTE} value={v} onValueChange={setV} />

// 非受控
<ColorSwatchPicker colors={PALETTE} defaultValue="#3b82f6" size="lg" />
```

## 禁忌 / 坑

- 受控 `value` 必须与 `colors` 中某项**严格字符串相等**才会高亮；`"#FFF"` 与 `"#ffffff"`、`"#3b82f6"` 与 `"rgb(59,130,246)"` 视为不同值。统一大小写与写法。
- 仅支持单选；多选场景不在本组件范围内。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Combobox

> 自动补全 · 触发按钮 + 弹层内搜索(图4 范式)，亦支持内联输入；浮层锚到字段等宽 · forms/advanced

## 何时用

选项较多需边打字边过滤（自动补全/可搜索下拉）时用；支持单选、`multiple` 多选 chips、触发按钮式弹层内搜索，以及内联输入直接过滤三种范式。选项少且全可见用 [Select](https://hulianui.haloritual.com/components/select)；纯展示已有密钥用 [SecretField](https://hulianui.haloritual.com/components/secret-field)；@提及场景用 [Mentions](https://hulianui.haloritual.com/components/mentions)。

## 导入
```ts
import { Combobox, ComboboxInput, ComboboxTrigger, ComboboxContent, ComboboxItem, ComboboxChips, ComboboxChip } from "@hulianui/ui"
```

## Props

`Combobox`（透传 Base UI `Combobox.Root<ComboboxItemData, Multiple>`，下表为瑚琏常用项）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `ComboboxItemData[]` | — | 选项数据 `{value,label}`，自动以 label 显示、value 提交 |
| value | `ComboboxItemData｜ComboboxItemData[]` | — | 受控选中（multiple 时为数组） |
| defaultValue | 同上 | — | 非受控初始选中 |
| multiple | `boolean` | `false` | true 时 value/onValueChange 自动变数组 |
| disabled | `boolean` | `false` | 禁用 |

`ComboboxTrigger`（图4 范式：显示已选 label / placeholder，点击展开弹层内搜索）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm"｜"md"｜"lg"` | `"md"` | 尺寸 |
| placeholder | `string` | — | 未选中时占位文案 |
| invalid | `boolean` | `false` | 独立使用（非 Field 内）时手动置无效态皮肤 |
| className | `string` | — | — |

`ComboboxInput`（内联自动补全：输入框本身即可见字段）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm"｜"md"｜"lg"` | `"md"` | 尺寸 |
| placeholder | `string` | — | 占位 |
| invalid | `boolean` | `false` | 手动置无效态皮肤 |
| clearable | `boolean` | `false` | 有值时渲染清除按钮 |
| className | `string` | — | — |

`ComboboxContent`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| searchPlaceholder | `string` | — | 设置后在浮层顶部渲染搜索框（图4 范式，配合 Trigger）；不设则为内联补全态 |
| side | `"top"｜"bottom"` | — | 浮层方位 |
| align | `"start"｜"center"｜"end"` | — | 浮层对齐 |
| sideOffset | `number` | — | 偏移 |
| className | `string` | — | — |

`ComboboxItem`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value * | `ComboboxItemData` | — | 选项 `{value,label}` 对象 |
| disabled | `boolean` | `false` | 禁用该项 |
| className | `string` | — | — |

`ComboboxChips`（多选 chips 外壳）：`size`、`invalid`、`placeholder`、`className`（外加 `children` 插槽，见 Slots）。
`ComboboxChip`（单个已选 chip）：`className`（外加 `children` 插槽，见 Slots）。

## Events

`Combobox`（透传 Base UI `Combobox.Root`）

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value) => void` | 选中变化回调（multiple 时 value 为数组） |

## Slots

`Combobox`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内放 Trigger/Input + Content |

`ComboboxContent`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | `(item, index) => ReactNode` | 渲染函数，List 自动遍历已过滤项调用 |
| emptyMessage | `ReactNode` | 无匹配时文案 |

`ComboboxItem`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | `ReactNode` | 渲染内容 |

`ComboboxChips`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内含 chip 列 + 输入框 |

`ComboboxChip`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | `ReactNode` | chip 内容 |

## 示例

触发按钮 + 弹层内搜索（图4 范式）：
```tsx
<Combobox items={FRUITS}>
  <ComboboxTrigger placeholder="选择水果" />
  <ComboboxContent searchPlaceholder="搜索水果…">
    {(item) => (
      <ComboboxItem key={item.value} value={item}>
        {item.label}
      </ComboboxItem>
    )}
  </ComboboxContent>
</Combobox>
```

内联自动补全（输入框即字段）：
```tsx
<Combobox items={FRUITS}>
  <ComboboxInput placeholder="搜索水果…" clearable />
  <ComboboxContent>
    {(item) => (
      <ComboboxItem key={item.value} value={item}>
        {item.label}
      </ComboboxItem>
    )}
  </ComboboxContent>
</Combobox>
```

## 禁忌 / 坑

- `ComboboxItem` 的 `value` 是整个 `{value,label}` 对象（非字符串）——render fn 里直接传 `value={item}`，Base UI 自动派生 label/value。
- 浮层内搜索框由 `ComboboxContent` 的 `searchPlaceholder` 触发：配 `ComboboxTrigger` 用就给它（图4 范式），配 `ComboboxInput` 内联补全则不设（输入框本身即搜索）。
- `multiple` 一开 value/onValueChange 即变数组，受控时 state 类型要跟着变。
- `invalid` 仅用于「非 Field 内」独立使用时手动置无效皮肤；在 Field 内由 Field 接管，不用手传。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# CountrySelect

> 国家/地区选择 · 内置 250 国(旗+中英文名+区号) + 单/多选 chips + 中英文/码/区号搜索 · dogfood Combobox(新增多选) · forms/advanced

## 何时用

选国家/地区时用，250 国数据（国旗 emoji + 中英文名 + 区号）已内置，支持中英文名/ISO 码/区号搜索。若选项是自定义扁平列表用 [Combobox](https://hulianui.haloritual.com/components/combobox)；若是中国省市区用 [RegionCascader](https://hulianui.haloritual.com/components/region-cascader)。

## 导入
```ts
import { CountrySelect, getCountry, flagEmoji, countrySearchText, filterCountries, countries } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| string[]` | — | 受控值：单选为 ISO2 码字符串；多选为码数组 |
| defaultValue | `string \| string[]` | — | 非受控初值 |
| multiple | `boolean` | `false` | 多选（chips） |
| showEnglish | `boolean` | `true` | 选项行是否显示英文名 |
| showDialCode | `boolean` | `false` | 选项行是否显示国际区号 |
| placeholder | `string` | — | 触发器占位文案 |
| searchPlaceholder | `string` | — | 搜索框占位文案 |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 触发器尺寸 |
| disabled | `boolean` | `false` | 禁用 |
| invalid | `boolean` | `false` | 无效态 |
| className | `string` | — | 透传到触发器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(next: string \| string[]) => void` | 选择变更回调；单选回传 string，多选回传 string[] |

## 示例
```tsx
// 单选
const [code, setCode] = useState("");
<CountrySelect value={code} onChange={(v) => setCode(v as string)} showDialCode />

// 多选（chips）
const [codes, setCodes] = useState<string[]>([]);
<CountrySelect multiple value={codes} onChange={(v) => setCodes(v as string[])} />
```

## 禁忌 / 坑

- `value`/`onChange` 入参在单选与多选下类型不同（`string` vs `string[]`），onChange 回调拿到的是联合类型，需按 `multiple` 用 `as` 收窄，别直接当数组用。
- value 存的是 ISO2 码（如 `"CN"`），不是中文名；展示名用 `getCountry(code)` 现取。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# DatePicker

> 日期选择 · MUI X 桥(输入+弹层日历) + ISO 受控 + min/max · forms/datetime · MUI 桥

## 何时用

表单里选**单个日期**、要带输入框 + 弹层日历时用。需要月历常驻铺开（无输入框）用 [Calendar](https://hulianui.haloritual.com/components/calendar)；选一段区间用 [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker)；连时间一起选用 [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker)。

## 导入
```ts
import { DatePicker } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| null` | — | ISO 字符串受控值；传入即受控 |
| defaultValue | `string` | — | ISO 字符串非受控默认值 |
| minDate | `string` | — | 可选最早日期（ISO） |
| maxDate | `string` | — | 可选最晚日期（ISO） |
| label | `string` | `"选择日期"` | 输入框 label |
| disabled | `boolean` | `false` | 禁用 |
| readOnly | `boolean` | `false` | 只读 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(iso: string \| null) => void` | 受控回调，回传 ISO 或 null（替代 MUI 的 onChange） |

## 示例
```tsx
function Demo() {
  const [v, setV] = useState<string | null>("2026-06-03");
  return <DatePicker label="选择日期" value={v} onValueChange={setV} />;
}
```
```tsx
<DatePicker label="到期日" defaultValue="2026-06-15" />
```

## 禁忌 / 坑

- 受控/非受控二选一：给 `value` 走受控须配 `onValueChange`；只想要初值用 `defaultValue`，别同时给。
- 对外值恒为 ISO 字符串（非 Date），回调也回传 ISO 或 null。

## 相关
[Calendar](https://hulianui.haloritual.com/components/calendar) · [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker) · [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker) · [TimeField](https://hulianui.haloritual.com/components/time-field) · [Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)

<!-- ════════════════════════════════════════════════════════ -->
# DateRangePicker

> 日期区间 · 自研零依赖双月范围日历(避开 MUI Pro 收费) + Popover 引擎 + 快捷预设/min-max/disabledDate · ISO 数组受控 · forms/datetime

## 何时用

选一段**日期区间**（起止两端）时用，自带双月并排 + 快捷预设（今天/最近7天/30天/本月）。选单个日期用 [DatePicker](https://hulianui.haloritual.com/components/date-picker)；连时间一起选用 [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker)；月历常驻铺开用 [Calendar](https://hulianui.haloritual.com/components/calendar)。本组件零依赖自研，不引 MUI Pro。

## 导入
```ts
import { DateRangePicker } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `[string, string] \| null` | — | 受控值 `[start, end]`（ISO `YYYY-MM-DD`）；`null` = 已清空；传入即受控 |
| defaultValue | `[string, string] \| null` | — | 非受控初始值 |
| minDate | `string` | — | 最早可选日（ISO），早于此禁选 |
| maxDate | `string` | — | 最晚可选日（ISO），晚于此禁选 |
| disabledDate | `(isoDate: string) => boolean` | — | 自定义禁用某天，入参为 ISO `YYYY-MM-DD` |
| presets | `boolean \| DateRangePreset[]` | `true` | 快捷预设：`true`/省略 = 默认四项；数组 = 自定义；`false` = 隐藏 |
| placeholder | `[string, string]` | `["开始日期","结束日期"]` | 占位文案 [开始, 结束] |
| displayFormat | `string` | `"YYYY-MM-DD"` | 展示格式（dayjs format）；对外受控值始终为 ISO `YYYY-MM-DD` |
| disabled | `boolean` | `false` | 禁用 |
| readOnly | `boolean` | `false` | 只读：可打开查看，无端点选择/无预设/无清除 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(range: [string, string] \| null) => void` | 区间变化（含清空 → null） |

`DateRangePreset`：`{ label: string; getValue: () => [string, string] }`，点击时调用、可基于"今天"动态计算。

## 示例
```tsx
function Demo() {
  const [v, setV] = useState<[string, string] | null>(null);
  return <DateRangePicker value={v} onValueChange={setV} />;
}
```
```tsx
<DateRangePicker
  defaultValue={["2026-06-10", "2026-06-12"]}
  minDate="2026-06-01"
  maxDate="2026-06-30"
  disabledDate={(iso) => {
    const day = new Date(iso + "T00:00:00").getDay();
    return day === 0 || day === 6; // 禁用周末
  }}
/>
```

## 禁忌 / 坑

- 受控/非受控二选一：给 `value` 走受控须配 `onValueChange`；只想要初值用 `defaultValue`，别同时给。
- 对外受控值恒为 ISO `YYYY-MM-DD` 数组（不是 Date）；`displayFormat` 只改输入框展示，回传值不变。
- `disabledDate` 入参是 ISO 字符串，自己拼 `new Date(iso + "T00:00:00")` 算 getDay 时注意时区，别直接 `new Date(iso)`（会按 UTC 解析偏一天）。

## 相关
[Calendar](https://hulianui.haloritual.com/components/calendar) · [DatePicker](https://hulianui.haloritual.com/components/date-picker) · [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker) · [TimeField](https://hulianui.haloritual.com/components/time-field) · [Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)

<!-- ════════════════════════════════════════════════════════ -->
# DateTimePicker

> 日期时间选择 · MUI X 桥(年月日+时钟一体弹层) + ISO 受控 + 步进/秒 · forms/datetime · MUI 桥

## 何时用

需要在一个弹层里**同时选日期 + 时间**时用（预约、起止时间戳）。只选日期用 [DatePicker](https://hulianui.haloritual.com/components/date-picker)；只选时间（HH:mm）用 [TimeField](https://hulianui.haloritual.com/components/time-field)；选日期区间用 [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker)。

## 导入
```ts
import { DateTimePicker } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| null` | — | ISO 字符串受控值（含日期+时间）；传入即受控 |
| defaultValue | `string` | — | ISO 字符串非受控默认值 |
| minDateTime | `string` | — | 可选最早日期时间（ISO） |
| maxDateTime | `string` | — | 可选最晚日期时间（ISO） |
| minutesStep | `number` | — | 时间步进分钟数（如 5、15、30） |
| withSeconds | `boolean` | `false` | 是否启用秒（默认仅到分钟） |
| label | `string` | `"选择日期时间"` | 输入框 label |
| disabled | `boolean` | `false` | 禁用 |
| readOnly | `boolean` | `false` | 只读 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(iso: string \| null) => void` | 受控回调，回传 ISO 或 null（替代 MUI 的 onChange） |

## 示例
```tsx
function Demo() {
  const [v, setV] = useState<string | null>("2026-06-03T14:30:00");
  return <DateTimePicker label="选择日期时间" value={v} onValueChange={setV} />;
}
```
```tsx
<DateTimePicker label="预约时间" defaultValue="2026-06-15T09:00:00" minutesStep={15} />
```

## 禁忌 / 坑

- 受控/非受控二选一：给 `value` 走受控须配 `onValueChange`；只想要初值用 `defaultValue`，别同时给。
- 对外值恒为 ISO 字符串（含时间，非 Date），回调也回传 ISO 或 null。
- 默认只到分钟，要秒级须显式开 `withSeconds`；`minutesStep` 只约束分钟轮的步进，不会自动对齐 `defaultValue`。

## 相关
[Calendar](https://hulianui.haloritual.com/components/calendar) · [DatePicker](https://hulianui.haloritual.com/components/date-picker) · [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker) · [TimeField](https://hulianui.haloritual.com/components/time-field) · [Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)

<!-- ════════════════════════════════════════════════════════ -->
# ElasticSlider

> 橡皮筋音量滑块 · 拖到两端轨道横拉纵压 + 图标回弹位移 + hover 整体放大、松手 spring 弹回(motion·零新依赖·reduced-motion) · forms/basic · #animated

## 何时用

需要一个带玩味动效的单值滑块时用（音量、亮度等连续量调节）。要表单标准化校验、键盘 a11y、与 Input/Select 同列对齐的常规录入，用普通滑块/[Input](https://hulianui.haloritual.com/components/input)；本组件是非受控数值反馈型装饰滑块，强调拖拽手感而非表单语义。

## 导入
```ts
import { ElasticSlider } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| defaultValue | `number` | `50` | 初始值（非受控）。组件内部维护数值，仅在挂载与该 prop 变化时同步进内部 state |
| startingValue | `number` | `0` | 量程下界（轨道最左对应数值） |
| maxValue | `number` | `100` | 量程上界（轨道最右对应数值） |
| isStepped | `boolean` | `false` | 是否吸附到步长（拖动时按 stepSize 取整） |
| stepSize | `number` | `1` | 吸附步长，仅 isStepped 为 true 时生效 |
| showValue | `boolean` | `true` | 是否显示当前值数字指示（轨道上方居中） |
| className | `string` | — | 透传到根容器的额外 className（merge via cn） |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: number) => void` | 拖动产生新值时回调，供消费方接管/上报数值 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| leftIcon | `ReactNode` | 左侧图标（轨道左端），拖动越界到最左时随回弹做位移+放大 |
| rightIcon | `ReactNode` | 右侧图标（轨道右端），拖动越界到最右时随回弹做位移+放大 |

## 示例
```tsx
// 默认音量滑块
<ElasticSlider defaultValue={40} />
```
```tsx
// 自定义图标 + 量程 + 步长吸附
<ElasticSlider
  defaultValue={65}
  startingValue={-50}
  maxValue={50}
  isStepped
  stepSize={10}
  leftIcon={<SunDim className="size-5" aria-hidden />}
  rightIcon={<Sun className="size-5" aria-hidden />}
/>
```

## 禁忌 / 坑

- **非受控**：`defaultValue` 只在挂载与 prop 变化时同步进内部 state，不能当受控值每帧回灌。要持续读数走 `onValueChange` 自存。
- 拖到两端会有橡皮筋横拉纵压溢出，外层容器需留出 overflow 空间（别用 `overflow-hidden` 紧贴裁掉）。
- 暂无其他已知坑。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# EmojiPicker

> 表情选择器 · 内联 emoji 数据集(7 分类·中英关键词) + 关键词搜索 + 分类页签 + 最近使用(受控/内部) · 搜索框 dogfood Input · onSelect 回传 emoji(零依赖·聊天/评论) · forms/advanced

## 何时用

聊天/评论输入框旁需要插入表情时用，emoji 数据（7 分类 + 中英关键词）内置、零依赖、支持搜索。本身只是表情面板，浮层弹出/定位需自配 [Popover](https://hulianui.haloritual.com/components/popover) 等容器。

## 导入
```ts
import { EmojiPicker, EMOJI_CATEGORIES, ALL_EMOJI } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| columns | `number` | `8` | 网格列数 |
| searchable | `boolean` | `true` | 是否显示搜索框 |
| defaultCategory | `string` | 第一个分类 | 初始分类 key |
| recent | `string[]` | — | 受控「最近使用」列表；省略则组件内部维护 |
| searchPlaceholder | `string` | — | 搜索框 placeholder |
| className | `string` | — | 透传到容器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(emoji: string) => void` | 选中某个 emoji 的回调，参数为 emoji 字符 |

## 示例
```tsx
// 追加到输入
const [text, setText] = useState("");
<EmojiPicker onSelect={(e) => setText((t) => t + e)} />

// 受控最近使用 + 隐藏搜索 + 紧凑 6 列
<EmojiPicker columns={6} searchable={false} recent={["🔥", "💯", "👍", "🎉", "❤️"]} onSelect={insert} />
```

## 禁忌 / 坑

- `recent` 一旦传入即进入受控模式，组件不再自行追加最近使用，需自己在 `onSelect` 里维护并回写；省略才走内部自动维护。
- 组件只是面板，不含触发器/浮层定位；要做弹出式表情按钮需自己套 [Popover](https://hulianui.haloritual.com/components/popover)。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Field

> 字段包装 · label/help/error a11y 串联 · forms/framework

## 何时用

给单个输入控件（Input/Textarea 等）套 label + 帮助文案 + 错误提示，并自动把三者用 `aria-describedby`/`aria-invalid` 串好无障碍关系时用。它是表单的最小积木——[Form](https://hulianui.haloritual.com/components/form)/[ProForm](https://hulianui.haloritual.com/components/pro-form) 内部就靠它布字段；你手搓一行字段、或在 [StepsForm](https://hulianui.haloritual.com/components/steps-form) 各步里放控件时也直接用它。

## 导入
```ts
import { Field } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| invalid | `boolean` | `false` | 显式覆盖 invalid；缺省时由 error 是否非空推导 |
| disabled | `boolean` | `false` | 禁用 |
| name | `string` | — | 提交标识，透传 Field.Root |
| colSpan | `"full"` | — | 在 ProForm columns 栅格中跨整行；栅格外无副作用 |
| className | `string` | — | 落在 Field.Root（纵向布局容器） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 控件（hulian Input / Textarea，= Field.Control） |
| label | `ReactNode` | 标签 |
| description | `ReactNode` | help 文案 |
| error | `ReactNode` | 错误文案；**非空即隐含 invalid 并强制显错** |

## 示例
```tsx
// 基础
<Field label="邮箱" description="我们不会公开你的邮箱">
  <Input placeholder="you@work.com" />
</Field>

// 带错误（error 非空自动标红 + 显错 + 串 aria）
<Field label="邮箱" error="邮箱格式不正确">
  <Input defaultValue="not-an-email" />
</Field>
```

## 禁忌 / 坑

- `error` 字符串非空时已隐含 `invalid`，无需再传 `invalid`；想强制无错状态下也标红才单独传 `invalid`。
- 底层是 Base UI Field，错误文本通过 `match={true}` 强制渲染——别在 Field 外另起一个 `<p>` 写错误，会丢失自动的 `aria-describedby` 串联。详见 [[base-ui-field-error-match-true-for-external-controlled-error]]：外部受控 error 不走 Base UI 校验时，默认分支会让错误文本「框红字没」。
- 若 children 是 Textarea，注意 render-as 的类型问题，见 [[base-ui-field-control-render-textarea-type-safe]]。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# Form

> 表单容器 · Base UI 结构化提交 + errors 按 name + 与 Field 协同 · forms/framework

## 何时用

页面内布置一组字段、自己管提交与校验时用。`Form` 是结构化提交容器（按原生 name 收集 values）；`useForm` 是更强的校验/联动控制器（规则引擎 + 字段依赖 + register/submit）；`FormList` 管动态增删行。需要弹窗/抽屉里提交用 [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog)；要自带 footer + 栅格的内联表单用 [ProForm](https://hulianui.haloritual.com/components/pro-form)；纯查询条件用 [SearchForm](https://hulianui.haloritual.com/components/search-form)。

## 导入
```ts
import { Form, useForm, validateValue, FormList } from "@hulianui/ui"
```

## Props

`Form`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| validationMode | `"onSubmit" \| "onBlur" \| "onChange"` | `"onSubmit"` | 校验时机 |
| errors | `Record<string, string \| string[]>` | — | 外部/服务端校验错误，按 `<Field name>` 映射（展示需 Field 内有 Field.Error） |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onFormSubmit | `(formValues: Record<string, unknown>) => void` | 提交时拿到结构化 values（已 preventDefault 原生提交） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 字段内容 |

`useForm` 控制器用法（详见示例）：`form.register(name, { rules, dependencies })`、`form.submit(onValid, onInvalid)`、`form.resetFields()`。

## 示例
```tsx
<Form className="w-72" onFormSubmit={(v) => console.log(v)}>
  <Field label="邮箱" name="email">
    <Input name="email" type="email" required />
  </Field>
  <Button type="submit" size="sm">提交</Button>
</Form>
```
```tsx
// useForm：规则引擎 + 字段联动
const form = useForm({ initialValues: { pwd: "", confirm: "" } });
const pwd = form.register("pwd", { rules: [{ required: true, min: 6, message: "至少 6 位" }] });
const confirm = form.register("confirm", {
  dependencies: ["pwd"],
  rules: [{ validator: (v, values) => { if (v !== values.pwd) throw new Error("两次密码不一致"); } }],
});
<form onSubmit={form.submit((values) => save(values))} noValidate>
  <Field label="密码" error={pwd.error}>
    <Input type="password" value={pwd.value as string} onChange={pwd.onChange} onBlur={pwd.onBlur} />
  </Field>
  <Field label="确认密码" error={confirm.error}>
    <Input type="password" value={confirm.value as string} onChange={confirm.onChange} onBlur={confirm.onBlur} />
  </Field>
</form>
```

## 禁忌 / 坑

- `validator` 报错靠 `throw new Error("...")` 抛出，不是 return false；联动字段记得在 `dependencies` 里声明被依赖字段，否则不会重算。
- `errors`（外部/服务端错误）要显示出来，对应 `Field` 内必须有 `Field.Error`，且 key 与 `<Field name>` 严格对齐。
- 用 `useForm` 时给原生 `<form>` 加 `noValidate`，避免浏览器原生校验抢在规则引擎前弹气泡。

## 相关
[ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [Field](https://hulianui.haloritual.com/components/field) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# ImageCropper

> 图片裁剪 · 固定比例框(默认证件照 5:7) + 触屏双指捏合/拖拽对位 + 缩放滑杆 + canvas 出 Blob(尺寸/质量/字节上限可配·react-easy-crop MIT) · forms/advanced

## 何时用

头像、证件照、封面图等「上传前要按固定比例裁一刀并控尺寸/体积」的场景用。给定图片源 + 比例，用户拖拽缩放对位后 `onCropped` 产出目标尺寸的 Blob。通常接在 [Upload](https://hulianui.haloritual.com/components/upload) 选完文件之后（把 File 转 object URL 喂给 `image`）。

## 导入
```ts
import { ImageCropper, cropImageToBlob } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| image* | `string` | — | 图片源：object URL / data URL / 同源地址 |
| aspect | `number` | `5/7` | 裁剪框宽高比（证件照 1 寸/2 寸同比例） |
| outputWidth | `number` | `413` | 输出位图宽（px），高按 aspect 推导取整（2 寸 @300DPI） |
| outputType | `string` | `"image/jpeg"` | 输出 mime |
| quality | `number` | `0.9` | 编码质量 0–1 |
| maxBytes | `number` | — | 输出字节上限（如 `200*1024`）：超限降质重试一次 |
| maxZoom | `number` | `3` | 最大缩放倍数 |
| cropAreaClassName | `string` | `h-64 sm:h-80` | 裁剪画布区高度 class |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCropped* | `(blob: Blob) => void` | 确认裁剪：产出目标尺寸 Blob |
| onCancel | `() => void` | 取消按钮点击（不传则不渲染取消按钮） |
| onError | `(error: unknown) => void` | 画布导出失败（极旧浏览器 / canvas 受限） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| confirmLabel | `ReactNode` | 确认按钮文案（默认 `"确认"`） |
| cancelLabel | `ReactNode` | 取消按钮文案（默认 `"取消"`） |

## 示例
```tsx
<ImageCropper
  image={objectUrl}
  aspect={5 / 7}
  maxBytes={200 * 1024}
  onCropped={(blob) => /* 存储/上传 */}
  onCancel={() => /* 关闭 */}
/>
```

方形头像：
```tsx
<ImageCropper image={objectUrl} aspect={1} onCropped={save} />
```

## 禁忌 / 坑

- `image` 必须**同源可被 canvas 读取**（object URL / data URL / 同源地址）；跨域无 CORS 头的图会污染画布导致导出抛错（走 `onError`）。
- `maxBytes` 是「尽力而为」：首次超限只降质重试一次（quality×0.72，下限 0.5），仍超限会原样输出，不保证一定达标。
- 不传 `onCancel` 就不渲染取消按钮（单动作场景）。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Input

> 输入框 · Base UI Field + 前后缀 + invalid · forms/basic

## 何时用

单行文本输入。多行文本用 [Textarea](https://hulianui.haloritual.com/components/textarea)；从固定选项里选一项用 [Select](https://hulianui.haloritual.com/components/select)；布尔/多选/单选分别用 [Switch](https://hulianui.haloritual.com/components/switch) / [Checkbox](https://hulianui.haloritual.com/components/checkbox) / [Radio](https://hulianui.haloritual.com/components/radio)。放进 hulian Field 内会自动接管 label/error/aria 关联。

## 导入
```ts
import { Input, inputShellVariants } from "@hulianui/ui"
```

## Props

继承原生 `<input>` 属性（除 `size`/`prefix` 被下方覆盖外，如 `value`/`onChange`/`type`/`placeholder`/`disabled`…）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" ｜ "md" ｜ "lg"` | `"md"` | 尺寸（CVA 变体，覆盖原生 size） |
| invalid | `boolean` | `false` | 独立使用时标红；在 hulian Field 内由 Field.Root invalid 自动驱动，无需重复传 |
| disabled | `boolean` | `false` | 禁用 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(e: ChangeEvent<HTMLInputElement>) => void` | 透传原生输入回调（受控时配合 `value` 使用） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| prefix | `ReactNode` | 前缀内容（如 `¥`） |
| suffix | `ReactNode` | 后缀内容（如 `.00`） |

## 示例
```tsx
<Input placeholder="请输入…" className="w-64" />
```
```tsx
{/* 前后缀 */}
<Input prefix="¥" suffix=".00" placeholder="0" className="w-64" />
```

## 禁忌 / 坑

在 hulian Field 内时不要重复传 `invalid`——Field.Root 的 invalid 会自动驱动标红，手动再传会冲突。`invalid` 只在脱离 Field 独立使用时手动传。

## 相关
[Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# InputOTP

> 验证码输入 · 分段自动跳格/退格回退/整段粘贴(零依赖) · forms/advanced

## 何时用

短信/邮箱验证码、PIN、二次验证码这类「定长、分格、填满即提交」的输入用。不要用普通文本框拼正则——本组件内置分段跳格、退格回退、整段粘贴拆分与 `onComplete`。需要任意长度自由文本请用普通 Input/[SecretField](https://hulianui.haloritual.com/components/secret-field)。

## 导入
```ts
import { InputOTP } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| length | `number` | `6` | 分段数量 |
| value | `string` | — | 受控值 |
| defaultValue | `string` | — | 非受控初始值 |
| type | `"numeric" \| "text"` | `"numeric"` | 仅数字（默认）或任意字符 |
| disabled | `boolean` | — | 禁用 |
| invalid | `boolean` | `false` | 校验失败态 |
| groupGap | `boolean` | — | 中间插入横线分隔符（3-3 分组视觉，如 XXX–XXX） |
| className | `string` | — | 容器类名 |
| aria-label | `string` | — | 无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(value: string) => void` | 值变化回调 |
| onComplete | `(value: string) => void` | 填满时回调 |

## 示例
```tsx
const [otp, setOtp] = useState("");
<InputOTP
  length={6}
  type="numeric"
  value={otp}
  onChange={setOtp}
  onComplete={verify}
/>
```

3-3 分组：
```tsx
<InputOTP length={6} groupGap value={otp} onChange={setOtp} />
```

## 禁忌 / 坑

- `onComplete` 仅在填满最后一格瞬间触发一次，验证逻辑放这里；不要在 `onChange` 里判 `value.length === length` 重复触发。
- 受控用 `value` 须配 `onChange`，否则格子无法输入。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [Rating](https://hulianui.haloritual.com/components/rating) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# Listbox

> 可选列表 · WAI-ARIA roving tabindex + 单/多/纯动作 + typeahead(零依赖) · forms/advanced

## 何时用

需要一段「就地可见、键盘可达」的选项列表（菜单项、设置项、命令列表）时用。要单/多选受控选中态走 `selectionMode="single"/"multiple"`；只想点了就触发动作（不持有选中态）走 `selectionMode="none"` + `onAction`。和 [Combobox](https://hulianui.haloritual.com/components/combobox) 的区别：Combobox 带输入框与浮层、适合海量可搜索选项；Listbox 是常驻的扁平列表，无输入、无弹层。

## 导入
```ts
import { Listbox } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `ListboxItemData[]` | — | 列表项；每项含 `key`/`label`，可带 `description`/`startContent`/`endContent`/`disabled` |
| selectionMode | `"none" \| "single" \| "multiple"` | `"single"` | none=纯动作列表（不持有选中态）；single/multiple=可选 |
| selectedKeys | `string[]` | — | 受控选中键 |
| defaultSelectedKeys | `string[]` | — | 非受控初始选中键 |
| disabledKeys | `string[]` | — | 额外禁用键（与 `item.disabled` 合并） |
| className | `string` | — | 容器类名 |
| aria-label | `string` | — | 无可见标题时的无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelectionChange | `(keys: string[]) => void` | 选中变化回调 |
| onAction | `(key: string) => void` | 任意项激活都触发（含 none 模式），用于命令式动作 |

## 示例
```tsx
const [keys, setKeys] = useState<string[]>(["profile"]);
<Listbox
  items={items}
  selectionMode="single"
  selectedKeys={keys}
  onSelectionChange={setKeys}
/>
```

纯动作列表（不持选中态）：
```tsx
<Listbox items={items} selectionMode="none" onAction={(key) => run(key)} aria-label="动作列表" />
```

## 禁忌 / 坑

- `selectionMode="none"` 时组件不持有选中态，要响应点击必须接 `onAction`；`onSelectionChange` 在该模式下不会有意义的输出。
- 无可见标题时务必传 `aria-label`，否则屏幕阅读器读不出列表用途。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# LoginForm

> 登录模板 · 自管 useForm(账号/密码必填+记住我) + 提交 loading + logo/footer 插槽(复用 Field/Input/Checkbox/Button·文案接 i18n) · forms/framework

## 何时用

直接落地后台/应用的登录页时用：账号 + 密码 + 记住我的表单状态、必填校验、提交 loading 都由它内部托管，你只接 `onFinish`。与 [Form](https://hulianui.haloritual.com/components/form)/[ProForm](https://hulianui.haloritual.com/components/pro-form) 的区别：那两个是通用表单骨架，需要自己拼字段；LoginForm 是开箱即用的成品模板，登录场景之外不用它。

## 导入
```ts
import { LoginForm } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| loading | `boolean` | — | 外部 loading 覆盖（父层托管提交态时用） |
| showRemember | `boolean` | `true` | 是否显示「记住我」 |
| className | `string` | — | 根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onFinish | `(values: LoginValues) => void \| Promise<void>` | 校验通过后提交；返回 Promise → 提交按钮 loading |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题（默认 `locale.loginForm.title`） |
| subtitle | `ReactNode` | 副标题（标题下方引导文案，左对齐·muted） |
| logo | `ReactNode` | 品牌 logo（头部左上） |
| footer | `ReactNode` | 底部附加区（忘记密码 / 注册链接等） |

`LoginValues = { username: string; password: string; remember: boolean }`。

## 示例
```tsx
<LoginForm
  logo={<Logo />}
  subtitle="欢迎回来，请登录你的管理后台"
  onFinish={async ({ username, password, remember }) => {
    await api.login(username, password, remember);
  }}
  footer={
    <div className="flex justify-between text-sm">
      <Link href="/forgot">忘记密码</Link>
      <Link href="/signup">注册账号</Link>
    </div>
  }
/>
```

## 禁忌 / 坑

- 表单状态由组件内部托管，外部拿不到 username/password 的实时值——只能在 `onFinish` 拿到最终 `values`。若父层自己也在管提交态（如全局 loading），用 `loading` prop 覆盖内置 loading，别另写一份。
- `onFinish` 返回 Promise 时提交按钮自动转 loading 并禁用，无需手动 disable。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [Field](https://hulianui.haloritual.com/components/field) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# MarkdownEditor

> Markdown 编辑器 · WYSIWYG 罩 TipTap + 值进出 markdown 字符串 + 隐藏 input 桥 Field + 标准集工具栏 · forms/advanced

## 何时用

需要所见即所得地编辑长文本（订单备注、文章详情、富文本说明）且最终存 markdown 字符串时用。值进出都是 markdown 串，可经 `name` 桥接原生表单 / [Field](https://hulianui.haloritual.com/components/field)。纯短文本用普通输入框；只需 @ 提及用 [Mentions](https://hulianui.haloritual.com/components/mentions)。

## 导入
```ts
import { MarkdownEditor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string` | — | 受控 markdown 字符串 |
| defaultValue | `string` | — | 非受控初值 |
| name | `string` | — | 桥给原生表单 / Field 的隐藏 input name |
| placeholder | `string` | `"输入 markdown…"` | 空内容占位文案 |
| invalid | `boolean` | `false` | 校验失败态：外壳变 danger（也可由外层 Field 经 data-invalid 驱动） |
| disabled | `boolean` | `false` | 禁用 |
| minRows | `number` | `6` | 内容区最小高度（行） |
| className | `string` | — | 透传到外壳 |
| aria-label | `string` | — | 无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(markdown: string) => void` | 内容变化回调，参数为 markdown 字符串 |

## 示例
```tsx
// 受控
const [md, setMd] = useState("# 标题");
<MarkdownEditor value={md} onChange={setMd} />

// 桥接 Field（隐藏 input 承载表单值与校验）
<Field label="订单详情（必填）" error="详情不能为空" className="w-[32rem]">
  <MarkdownEditor name="detail" invalid placeholder="必填" />
</Field>
```

## 禁忌 / 坑

- 值进出是 markdown 字符串而非 TipTap 文档 JSON；不要把内部富文本结构当 value 传入。
- 放进 [Field](https://hulianui.haloritual.com/components/field) 校验时，`invalid` 既可自传、也可由外层 Field 的 `data-invalid` 驱动，二选一即可，不必两边都设。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Mentions

> @提及输入 · 复用 Textarea 皮肤 + 触发符唤起候选(镜像 div 测光标像素坐标) + aria-activedescendant 虚拟焦点(零依赖) · forms/advanced

## 何时用

多行评论/工单/动态里需要 @ 某人、# 关联工单这类「键入触发符 → 弹候选 → 插入」场景时用。它本质是带候选浮层的 Textarea。和 [Combobox](https://hulianui.haloritual.com/components/combobox) 的区别：Combobox 选「单值」整体替换输入框；Mentions 在自由文本中插入一个个提及片段，候选只在触发符后唤起，正文仍是普通多行文本。

## 导入
```ts
import { Mentions, MentionText, type MentionTextProps, findTrigger, insertMention, defaultFilter, segmentMentions, type MentionSegment } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| options* | `MentionOption[]` | — | 候选清单；每项 `value`/`label`，可带 `description`/`startContent`/`disabled` |
| value | `string` | — | 受控文本值（与 onChange 配套） |
| defaultValue | `string` | — | 非受控初始值（不传 value 时生效） |
| prefix | `string` | `"@"` | 触发符，可配多字符如 `"@@"`/`"#"`；其前为行首或空白时唤起候选 |
| filter | `false \| ((option, query) => boolean)` | 内置子串匹配 | `false`=关闭本地过滤交给 onSearch；函数=自定义；缺省=大小写不敏感子串（label/value） |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 文本域皮肤尺寸（复用 Textarea 的 size 变体） |
| invalid | `boolean` | `false` | 独立使用时标红 |
| placeholder | `string` | — | 占位符（透传 textarea） |
| rows | `number` | — | 文本域行数（透传 textarea） |
| disabled | `boolean` | `false` | 禁用 |
| className | `string` | — | 容器类名 |
| popupClassName | `string` | — | 候选浮层额外类名 |

> 还透传 `Textarea` 的原生属性（除被 Omit 的 `size`/`value`/`defaultValue`/`onChange`/`onSelect`/`prefix`）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(value: string) => void` | 文本变化回调（受控必接） |
| onSearch | `(query: string) => void` | 查询变化通知（外部/异步过滤用，本身不返回结果） |
| onSelect | `(option: MentionOption) => void` | 选中候选回调（回传整条 option） |

## 示例
```tsx
<Mentions
  options={people}
  defaultValue="提醒 "
  placeholder="输入 @ 提及同事…"
  onSelect={(o) => console.log(o)}
/>
```

自定义触发符 `#` 关联工单：
```tsx
<Mentions prefix="#" options={tickets} placeholder="输入 # 关联工单…" />
```

## 禁忌 / 坑

- 受控用法 `value` 必须配 `onChange`，否则文本无法编辑（与原生受控 textarea 同理）。
- 插入文本是 `prefix + label + " "`，`label` 即可见名也是写入正文的字面量；要展示和插入不一致请自行用 `onSelect` 接管。
- 外部/异步过滤时设 `filter={false}` 并在 `onSearch` 里刷新 `options`，否则内置子串过滤会再过滤一遍父级已筛好的结果。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# ModalForm / DrawerForm

> 弹窗/抽屉表单 · 列表页新增/编辑编排件(复用 Dialog/Drawer + useForm + Button footer) · 提交前自动 validate · async onFinish 成功关闭/失败保持 · 文案接 i18n · forms/framework

## 何时用

列表页点「新增/编辑」弹出表单时用：`ModalForm` 居中弹窗、`DrawerForm` 贴边抽屉，二者 API 一致（抽屉多一个 `side`）。它把 Dialog/Drawer + 提交按钮 footer + 校验编排好了。页面内常驻表单用 [ProForm](https://hulianui.haloritual.com/components/pro-form)；裸表单容器用 [Form](https://hulianui.haloritual.com/components/form)；多步向导用 [StepsForm](https://hulianui.haloritual.com/components/steps-form)。

## 导入
```ts
import { ModalForm, DrawerForm } from "@hulianui/ui"
```

## Props

公共（`ModalForm` = `FormDialogBaseProps`；`DrawerForm` 在此基础上加 `side`）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| title * | `string` | — | 标题（a11y label） |
| open | `boolean` | — | 受控开关 |
| defaultOpen | `boolean` | — | 非受控初始开关 |
| form | `FormInstance` | — | useForm 实例：提供则提交前自动 `validate()`，校验不过保持打开 |
| submitText | `string` | `locale.modalForm.submit` | 提交按钮文案 |
| cancelText | `string` | `locale.modalForm.cancel` | 取消按钮文案 |
| className | `string` | — | 容器类名（控宽度等） |
| side | `DrawerSide` | `"right"` | 仅 `DrawerForm`：抽屉贴边方向 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange | `(open: boolean) => void` | 开关变化回调 |
| onFinish | `(values: FormValues) => void \| boolean \| Promise<void \| boolean>` | 提交回调；返回 Promise → 按钮 loading；resolve(非 false) 自动关闭；reject 或返回 false 保持打开 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| trigger | `ReactElement` | 触发元素（非受控打开用）；受控时可省 |
| children | `ReactNode` | 表单字段 |

## 示例
```tsx
const form = useForm({ initialValues: { name: "" } });
const name = form.register("name", { rules: [{ required: true, message: "请输入姓名" }] });

<ModalForm
  title="新增员工"
  form={form}
  trigger={<Button>新增</Button>}
  onFinish={async (values) => { await api.create(values); }} // 校验通过+成功后自动关闭
>
  <Field label="姓名" error={name.error}>
    <Input value={name.value} onChange={name.onChange} onBlur={name.onBlur} />
  </Field>
</ModalForm>
```

## 禁忌 / 坑

- 关/不关由 `onFinish` 返回值决定：resolve 非 false → 自动关；想留在原地（如自处理错误）reject 或 return false。别在 onFinish 里手动调 onOpenChange(false) 跟自动关闭打架。
- 传了 `form` 才会提交前自动 `validate()` 并在校验不过时保持打开；不传 form 则不校验、直接把 values 交给 onFinish。
- 提交成功后想清空字段需自己调 `form.resetFields()`，组件不会替你重置。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [Field](https://hulianui.haloritual.com/components/field) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# NumberField

> 数字步进 · Base UI ±按钮 + 键盘步进 + min/max · forms/basic

## 何时用

需精确录入数字并带 ± 步进按钮、min/max 边界（数量、份数、阈值）时用。只需大致量级、拖动选值用 [Slider](https://hulianui.haloritual.com/components/slider)；非数字的任意文本录入用 [Input](https://hulianui.haloritual.com/components/input)。

## 导入
```ts
import { NumberField } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `number｜null` | — | 受控值（null=空） |
| defaultValue | `number` | — | 非受控初始值 |
| min | `number` | — | 最小值 |
| max | `number` | — | 最大值 |
| step | `number` | `1` | 步进量 |
| disabled | `boolean` | `false` | 禁用 |
| readOnly | `boolean` | `false` | 只读 |
| required | `boolean` | — | 表单必填 |
| name | `string` | — | 原生表单 name |
| id | `string` | — | — |
| className | `string` | — | — |
| aria-label | `string` | — | 无可见标题时提供 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: number｜null) => void` | 变化回调（瑚琏收敛签名，丢 Base UI eventDetails） |

## 示例
```tsx
<NumberField aria-label="数量" defaultValue={3} min={0} max={5} />
```

受控（值可为空）：
```tsx
const [v, setV] = useState<number | null>(2);
<NumberField aria-label="数量" value={v} onValueChange={setV} min={0} max={10} />
```

## 禁忌 / 坑

- 受控值类型是 `number | null`——清空时回调拿到 `null`，state 须用 `useState<number | null>`，别假设永远是 number。
- 用 `value`/`onValueChange` 即受控，须自管 state；非受控只给 `defaultValue`。
- 无可见标题时给 `aria-label`，否则读屏无名。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# ProForm

> 内联表单编排 · useForm + 自动 footer(提交/重置) + async onFinish loading + 自定义 footer(ModalForm 的内联姊妹件·文案接 i18n) · forms/framework

## 何时用

页面内**常驻**一个表单、要自带提交/重置 footer 和响应式栅格时用（详情页编辑、设置页）。它是 [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) 的内联姊妹件——同样 useForm + 自动 footer，只是不弹层。要弹窗/抽屉提交用 ModalForm/DrawerForm；只要裸容器、自己管 footer 用 [Form](https://hulianui.haloritual.com/components/form)；查询条件用 [SearchForm](https://hulianui.haloritual.com/components/search-form)。

## 导入
```ts
import { ProForm } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| form | `FormInstance` | — | useForm 实例：提供则提交前自动 `validate()`，重置走 `form.resetFields()` |
| submitText | `string` | `locale.proForm.submit` | 提交按钮文案 |
| resetText | `string` | `locale.proForm.reset` | 重置按钮文案 |
| showReset | `boolean` | `true` | 是否显示重置按钮（需 form 才有意义） |
| columns | `1 \| 2 \| 3` | `1` | 字段栅格列数；≥2 时按容器宽度自适应（窄塌单列），跨整行用 `<Field colSpan="full">` |
| footerAlign | `"left" \| "right"` | `"left"` | 底部操作区对齐 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onFinish | `(values: FormValues) => void \| boolean \| Promise<void \| boolean>` | 提交回调；返回 Promise → 提交按钮 loading；reject 不抛断（错误反馈交消费者） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| footer | `ReactNode` | 自定义底部操作区（覆盖默认提交/重置按钮） |
| children | `ReactNode` | 表单字段 |

## 示例
```tsx
const form = useForm({ initialValues: { name: "", email: "" } });
const name = form.register("name", { rules: [{ required: true, message: "请输入姓名" }] });
const email = form.register("email", { rules: [{ pattern: /@/, message: "邮箱需含 @" }] });

<ProForm form={form} onFinish={async (v) => { await api.save(v); }}>
  <Field label="姓名" error={name.error}>
    <Input value={name.value as string} onChange={name.onChange} onBlur={name.onBlur} />
  </Field>
  <Field label="邮箱" error={email.error}>
    <Input value={email.value as string} onChange={email.onChange} onBlur={email.onBlur} />
  </Field>
</ProForm>
```
```tsx
// 响应式栅格：columns 走容器查询(窄自动塌单列)，跨行字段用 colSpan="full"
<ProForm form={form} columns={2} submitText="保存" onFinish={() => {}}>
  <Field label="名"><Input {...bind(reg.first)} /></Field>
  <Field label="姓"><Input {...bind(reg.last)} /></Field>
  <Field label="详细地址" colSpan="full"><Input {...bind(reg.addr)} /></Field>
</ProForm>
```

## 禁忌 / 坑

- `columns` 是**容器查询**自适应（按表单容器实际宽度塌列），不是视口断点；别再手搓 grid + media query，跨整行字段用 `<Field colSpan="full">`。
- 与 ModalForm 不同，ProForm 的 `onFinish` reject **不抛断**——错误反馈（toast 等）由消费者自己处理。
- 重置按钮只有传了 `form` 才有意义（走 `form.resetFields()`）；用 `footer` 自定义底部会**覆盖**默认提交/重置按钮，此时需自己接提交逻辑。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [Field](https://hulianui.haloritual.com/components/field) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# PulsatingButton

> 脉冲按钮 · 外扩光环(box-shadow) + RSC · forms/button · #animated

## 何时用

用一圈外扩脉冲光环引导用户注意的 CTA（订阅、提交等）。普通操作用 [Button](https://hulianui.haloritual.com/components/button)；边缘游走火花用 [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)；彩虹流光底用 [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button)。

## 导入
```ts
import { PulsatingButton } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| pulseColor | `string` | `var(--color-primary)` 的 70% | 脉冲光环色 |
| duration | `string` | `1.5s` | 一轮脉冲秒数 |
| ...buttonProps | `ComponentPropsWithoutRef<"button">` | — | 透传原生 button 属性 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 点击回调，经 `ComponentPropsWithoutRef<"button">` 透传 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮文案，经原生 button 属性透传 |

## 示例
```tsx
<PulsatingButton>立即订阅</PulsatingButton>

// 放慢脉冲
<PulsatingButton duration="2.5s">立即订阅</PulsatingButton>
```

## 禁忌 / 坑

- 自定义往按钮塞图标+文字若图标掉行，是 Tailwind Preflight `svg{display:block}` 所致，见 [[tailwind-preflight-svg-block-breaks-icon-text-in-nonflex-button]]——确保文案容器是 `inline-flex`。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# Radio

> 单选 · RadioGroup 单选组 + 键盘方向键 · forms/basic

## 何时用

一组互斥选项里选且只选一个、且选项数少（约 2–6 个）需全部直接可见时用。选项多需收起或搜索改用 [Select](https://hulianui.haloritual.com/components/select)；多选共存改用 [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group)；横向二三段且要滑块视觉用 [Segmented](https://hulianui.haloritual.com/components/segmented)。

## 导入
```ts
import { RadioGroup, Radio } from "@hulianui/ui"
```

## Props

`RadioGroup`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string` | — | 受控选中值 |
| defaultValue | `string` | — | 非受控初始选中值 |
| disabled | `boolean` | `false` | 整组禁用 |
| required | `boolean` | — | 表单必选 |
| name | `string` | — | 原生表单 name |
| orientation | `"vertical"｜"horizontal"` | `"vertical"` | 仅控布局 |
| className | `string` | — | — |
| aria-label | `string` | — | 无可见标题时提供 |

`Radio`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value * | `string` | — | 必填，标识该选项 |
| disabled | `boolean` | `false` | 单项禁用 |
| id | `string` | — | — |
| className | `string` | — | 落在 Radio.Root |

## Events

`RadioGroup`

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string) => void` | 选中变化回调 |

## Slots

`RadioGroup`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内放 `Radio` 项 |

`Radio`

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 可选 inline label（点右，原生 `<label>` 关联） |

## 示例
```tsx
<RadioGroup defaultValue="b" aria-label="选项">
  <Radio value="a" label="选项一" />
  <Radio value="b" label="选项二" />
  <Radio value="c" label="选项三(禁用)" disabled />
</RadioGroup>
```

横向 + 受控：
```tsx
const [value, setValue] = useState("standard");
<RadioGroup value={value} onValueChange={setValue} orientation="horizontal" aria-label="套餐">
  <Radio value="standard" label="标准" />
  <Radio value="pro" label="专业" />
</RadioGroup>
```

## 禁忌 / 坑

- 选中值统一由 `RadioGroup` 管，`Radio` 不自带选中态——别在 `Radio` 上找 `checked`。
- 用 `value`/`onValueChange` 即受控，须自管 state；只给初值用 `defaultValue`，二者不要混用。
- 无可见标题的单选组要给 `aria-label`，否则无障碍读屏无名。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# RainbowButton

> 彩虹按钮 · chart 流光底 + 模糊光晕 + RSC · forms/button · #animated

## 何时用

需要最强吸睛的英雄 CTA，底部 chart 色彩流动 + 模糊光晕。普通操作用 [Button](https://hulianui.haloritual.com/components/button)；单道边缘火花用 [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)；外扩脉冲光环用 [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button)。

## 导入
```ts
import { RainbowButton } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `string` | `3s` | 彩虹流动一轮秒数 |
| ...buttonProps | `ComponentPropsWithoutRef<"button">` | — | 透传原生 button 属性 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 点击回调，经 `ComponentPropsWithoutRef<"button">` 透传 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮文案，经原生 button 属性透传 |

## 示例
```tsx
<RainbowButton>Get Started</RainbowButton>

// 放慢流动
<RainbowButton speed="5s">Get Started</RainbowButton>
```

## 禁忌 / 坑

- 自定义往按钮塞图标+文字若图标掉行，是 Tailwind Preflight `svg{display:block}` 所致，见 [[tailwind-preflight-svg-block-breaks-icon-text-in-nonflex-button]]——确保文案容器是 `inline-flex`。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# Rating

> 评分 · MUI 桥(emotion theme 读瑚琏 token) + 受控星级 · forms/advanced · MUI 桥

## 何时用

需要星级打分/满意度采集，或只读展示已有评分时用。基于 MUI Rating 的桥接组件，emotion 主题读瑚琏 token，可换图标（心/火苗等）和颜色。纯只读且只需展示分值文字的场景可直接用文本，不必引入本组件。

## 导入
```ts
import { Rating } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `number` | — | 受控当前分值 |
| defaultValue | `number` | — | 非受控初始分值 |
| max | `number` | — | 星数上限 |
| readOnly | `boolean` | `false` | 只读（不可交互） |
| disabled | `boolean` | — | 禁用 |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸 |
| color | `string` | `var(--color-primary)` | 星色（任意 CSS 颜色或 token var()）；hover 自动派生 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: number \| null) => void` | 瑚琏命名受控回调（替代 MUI `onChange(e,v)`）；清空时回传 `null` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 自定义图标，如 `<Heart />`（默认实心五角星） |
| emptyIcon | `ReactNode` | 自定义空状态图标，缺省时复用 icon（同形状走空色） |

## 示例
```tsx
const [v, setV] = useState<number | null>(3);
<Rating value={v ?? 0} onValueChange={setV} />
```

只读 + 换图标/颜色：
```tsx
<Rating value={4} readOnly />
<Rating defaultValue={3} color="var(--color-danger)" icon={<Heart size="1em" fill="currentColor" />} />
```

## 禁忌 / 坑

- 回调是 `onValueChange`（瑚琏命名），不是 MUI 原生 `onChange(e, value)`；清空评分时回传 `null`，受控时记得处理。
- `color` 传 token 须带前缀写 `var(--color-primary)`，裸 `var(--primary)` 不解析 —— 见 [[hulian-token-color-var-needs-color-prefix]]。
- 自定义 `icon` 想填充实色须自带 `fill="currentColor"`（如示例），否则只描边。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# RegionCascader

> 中国省市区级联 · 内置全量行政区划(国家统计局口径·3级) + 浮层搜索直达 + onChange 同回码与名 · dogfood Cascader · forms/advanced

## 何时用

需要让用户选中国省/市/区县时用，行政区划数据已内置（`cnDivisions`），无需自备数据源。若是通用任意层级树选择用 [TreeSelect](https://hulianui.haloritual.com/components/tree-select)；若选国家/地区用 [CountrySelect](https://hulianui.haloritual.com/components/country-select)。

## 导入
```ts
import { RegionCascader, sliceLevel, cnDivisions } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string[]` | — | 受控值：行政区划 code 路径，如 `["11","1101","110101"]` |
| defaultValue | `string[]` | — | 非受控初值 |
| level | `2 \| 3` | `3` | 联动层级：3=省/市/区县；2=省/市 |
| showSearch | `boolean` | `true` | 浮层内搜索框，输"浦东"直达 |
| changeOnSelect | `boolean` | — | 允许选到中间级即提交（不必到末级） |
| placeholder | `string` | — | 触发器占位文案 |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 触发器尺寸 |
| disabled | `boolean` | `false` | 禁用 |
| invalid | `boolean` | `false` | 无效态 |
| className | `string` | — | 透传到触发器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(codes: string[], names: string[]) => void` | 变更回调，同时给 code 路径与名称路径（表单常存名称） |

## 示例
```tsx
const [codes, setCodes] = useState<string[]>([]);
const [names, setNames] = useState<string[]>([]);
<RegionCascader
  value={codes}
  onChange={(c, n) => { setCodes(c); setNames(n); }}
  showSearch
/>

// 默认值回显（北京/东城区）+ 两级
<RegionCascader level={2} defaultValue={["44", "4401"]} />
```

## 禁忌 / 坑

- `onChange` 给两个数组：code 路径与 name 路径。表单存名称时取第二参，但受控 `value` 要回传的是 **code 路径**（第一参），两者别搞反。
- `value` 必须是合法的 code 链路（每级 code 是上级的子项），否则浮层无法定位回显。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# RippleButton

> 波纹按钮 · 点击落点扩散(Material) + reduced-motion · forms/button · #animated

## 何时用

需要 Material 风格「点击落点扩散波纹」反馈的按钮。普通操作用 [Button](https://hulianui.haloritual.com/components/button)；只想要视觉特效（流光/彩虹/脉冲）而非点击涟漪时用 [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) / [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) / [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button)。

## 导入
```ts
import { RippleButton } from "@hulianui/ui"
```

## Props

继承全部原生 `<button>` 属性（`disabled`/`type`…）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| rippleColor | `string` | `var(--color-primary-foreground)` | 波纹颜色 |
| duration | `string` | `"600ms"` | 单次波纹动画时长 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 透传原生点击回调（点击同时触发波纹扩散） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮内容（文案/图标） |

## 示例
```tsx
<RippleButton>点我看波纹</RippleButton>
```
```tsx
<RippleButton duration="900ms">点我看波纹</RippleButton>
```

## 禁忌 / 坑

暂无已知坑。波纹动画在 `prefers-reduced-motion: reduce` 下自动抑制，无需手动处理。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# SearchForm

> 查询筛选表单 · 中后台列表页顶部条件区 · fields 配置 + 固定列栅格 + 一行折叠 + 查询/重置(dogfood Grid/Field/Input/Select/Button·零依赖) · forms/framework

## 何时用

中后台列表页顶部的条件筛选区——用 `fields` 配置数组声明若干查询项，组件按固定列栅格排布、字段多时一行折叠、自带「查询/重置」。区别于 [Form](https://hulianui.haloritual.com/components/form)/[ProForm](https://hulianui.haloritual.com/components/pro-form)（录入提交业务数据）：SearchForm 专做「筛选参数 → onSearch」。通常不单独用，而是作为 [ProTable](https://hulianui.haloritual.com/components/pro-table) 的 `search` 区集成进列表页。

## 导入
```ts
import { SearchForm, planLayout, canCollapse, totalSpan } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| fields* | `SearchField[]` | — | 字段配置数组 |
| values | `Record<string, unknown>` | — | 受控值；缺省走内部 state |
| columns | `number` | `3` | 桌面列数 |
| gap | `number` | `4` | 行列间距（× 0.25rem） |
| collapsible | `boolean` | `true` | 字段填不满一行时自动失效 |
| defaultCollapsed | `boolean` | `true` | 初始折叠 |
| loading | `boolean` | `false` | 查询按钮 loading 态 |
| className | `string` | — | 根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSearch* | `(values: Record<string, unknown>) => void` | 查询 / 回车提交 |
| onChange | `(values: Record<string, unknown>) => void` | 任一字段编辑触发（受控回填） |
| onReset | `(values: Record<string, unknown>) => void` | 重置（values = 各字段 default 后的值） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| submitText | `ReactNode` | 主按钮文案（默认 `"查询"`） |
| resetText | `ReactNode` | 重置按钮文案（默认 `"重置"`） |

`SearchField` 是判别联合（按 `type`/`render` 区分，缺省即 `input`）。公共字段：`name*`（值 key）、`label*`、`placeholder?`、`colSpan?`（默认 1，封顶 columns）、`defaultValue?`。各形态：
- `type?: "input"` + `inputType?: string`
- `type: "select"` + `options: { value: string; label: ReactNode }[]`
- `type: "date"` / `type: "date-range"`
- `render: (ctx: { name; value; onChange }) => ReactNode`（逃生舱，自渲染控件）

## 示例
```tsx
const fields: SearchField[] = [
  { name: "keyword", label: "关键词", placeholder: "订单号 / 客户名" },
  { name: "status", label: "状态", type: "select", placeholder: "全部",
    options: [
      { value: "pending", label: "待处理" },
      { value: "done", label: "已完成" },
    ] },
  { name: "range", label: "创建时间", type: "date-range", colSpan: 2 },
];

<SearchForm
  fields={fields}
  values={values}
  onChange={setValues}
  onSearch={(v) => fetchList(v)}
  onReset={() => fetchList({})}
/>
```

## 禁忌 / 坑

- 受控用法（传 `values`）必须同时接 `onChange` 回填，否则字段无法编辑。
- `collapsible` 只在字段总跨度超过一行时才真正出现「展开/收起」；少字段时自动失效，不用手动关。
- `onReset` 回调收到的 values 是「各字段 default 后的值」而非空对象——重置后重新查询应用它而不是 `{}`，以保留默认筛选。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [StepsForm](https://hulianui.haloritual.com/components/steps-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [Field](https://hulianui.haloritual.com/components/field)

<!-- ════════════════════════════════════════════════════════ -->
# SecretField

> 密钥掩码字段 · sk-abc…wxyz 掩码(full/prefix-suffix) + 眼睛 toggle 显形 + 一键复制原值(同 Snippet idiom·1.5s 反馈) + 尾部动作槽(重置/吊销) + 受控 revealed(API key 管理刚需·复用 _icons Eye/Copy) · forms/advanced

## 何时用

展示已存在的敏感值（API key、token、密钥）——默认掩码、点眼睛显形、一键复制原值，并可挂重置/吊销动作。用于「展示+复制已有密钥」而非录入；录入密码用普通 [Input](https://hulianui.haloritual.com/components/input)（type=password）；多选输入挑选用 [Combobox](https://hulianui.haloritual.com/components/combobox)。

## 导入
```ts
import { SecretField, maskSecret } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value * | `string` | — | 密钥原值 |
| revealed | `boolean` | — | 受控显形态；不传则组件自管 |
| maskStrategy | `"full"｜"prefix-suffix"` | `"prefix-suffix"` | full 全掩 / prefix-suffix 保留首尾 |
| copyable | `boolean` | `true` | 是否显示复制按钮 |
| readOnly | `boolean` | `false` | 只读外观（去掉交互态描边） |
| size | `"sm"｜"md"` | `"md"` | — |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onRevealedChange | `(revealed: boolean) => void` | 显形态变化回调（受控时用） |
| onCopy | `(value: string) => void` | 复制回调（拿到原值） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| actions | `ReactNode` | 尾部动作槽（重置 / 吊销等） |

另导出 `maskSecret(value, strategy)` 工具函数，单独按策略生成掩码串。

## 示例
```tsx
<SecretField value={apiKey} maskStrategy="prefix-suffix" />
```

全掩 + 不可复制 + 受控显形：
```tsx
const [revealed, setRevealed] = useState(false);
<SecretField
  value={apiKey}
  maskStrategy="full"
  copyable={false}
  revealed={revealed}
  onRevealedChange={setRevealed}
/>
```

## 禁忌 / 坑

- `value` 是必填的原值（明文）——掩码只是展示层，组件内部持有真实值用于复制，别把已掩码的串喂进来。
- 不传 `revealed` 时组件自管显形态；要外部控制（如统一收起）才传 `revealed`+`onRevealedChange`，二者配套。
- `copyable` 默认 true，敏感场景按需 `copyable={false}` 关掉复制。

## 相关
[Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating) · [Upload](https://hulianui.haloritual.com/components/upload)

<!-- ════════════════════════════════════════════════════════ -->
# Segmented

> 分段控制器 · 自研 radio 语义(方向键漫游) + active-tab CSS 变量滑块(零依赖) · forms/basic

## 何时用

横向一排互斥选项（约 2–5 段，如「日/周/月」「网格/列表/地图」「按月/按年付费」）需滑块高亮当前段时用，items 数组驱动、单值互斥。选项纵向排列或语义偏表单单选用 [Radio](https://hulianui.haloritual.com/components/radio)；切换页面级视图区块用 Tabs；选项多需收起用 [Select](https://hulianui.haloritual.com/components/select)。

## 导入
```ts
import { Segmented } from "@hulianui/ui"
```

## Props

`Segmented`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items * | `SegmentedItem[]` | — | 段定义数组 |
| value | `string` | — | 受控选中值 |
| defaultValue | `string` | 首个未禁用段 | 非受控初始选中值 |
| disabled | `boolean` | `false` | 整体禁用 |
| size | `"sm"｜"md"` | `"md"` | — |
| className | `string` | — | — |
| aria-label | `string` | — | 无可见标题时提供 |

`SegmentedItem`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value * | `string` | — | 该段唯一值（也是选中标识） |
| ariaLabel | `string` | — | label 为富节点（图标/徽标）时必填，否则降级取 value |
| disabled | `boolean` | `false` | 单段禁用 |

## Events

`Segmented`

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string) => void` | 选中变化（单值，radio 语义互斥） |

## Slots

`SegmentedItem`

| 插槽 | 类型 | 说明 |
|------|------|------|
| label * | `ReactNode` | 段内容（文字或图标） |

## 示例
```tsx
<Segmented
  items={[
    { value: "day", label: "日" },
    { value: "week", label: "周" },
    { value: "month", label: "月" },
  ]}
  defaultValue="week"
  aria-label="周期"
/>
```

图标段（每段给 ariaLabel）：
```tsx
<Segmented
  items={[
    { value: "grid", ariaLabel: "网格视图", label: <LayoutGrid className="size-4" /> },
    { value: "list", ariaLabel: "列表视图", label: <List className="size-4" /> },
  ]}
  defaultValue="grid"
  aria-label="视图"
/>
```

## 禁忌 / 坑

- 段 `label` 是图标/徽标等富节点时必须给该段 `ariaLabel`，否则读屏会读英文 `value`（念读不友好）。
- 用 `value`/`onValueChange` 即受控，须自管 state；非受控只给 `defaultValue`。
- 选中是单值互斥，没有多选——多选共存改用 [ToggleGroup](https://hulianui.haloritual.com/components/toggle)。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# Select

> 下拉选择 · Base UI overlay 单选 + items 自动 label · forms/basic

## 何时用

从一组固定选项里单选一项（选项较多、需要收纳成下拉）。选项少且需全部可见用 [Radio](https://hulianui.haloritual.com/components/radio)；多选用 [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group)；自由文本用 [Input](https://hulianui.haloritual.com/components/input)。给 `items`（`{value,label}` 数组）让 Trigger 显示选中项 label 而非 raw value。

## 导入
```ts
import { Select, SelectTrigger, SelectContent, SelectItem } from "@hulianui/ui"
```

## Props

`Select` 继承 Base UI `Select.Root` 属性（除 `items` 被下方覆盖外，如 `value`/`defaultValue`/`onValueChange`/`disabled`…）。

### Select
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `ReadonlyArray<{ value: string ｜ null; label: ReactNode }>` | — | 选项数据；Base UI 据此让 Trigger 显示选中项 label |
| placeholder | `ReactNode` | — | 无选中值时的占位文本（瑚琏注入 value:null 项实现，rc.0 无 Value.placeholder prop） |

### SelectTrigger
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" ｜ "md" ｜ "lg"` | `"md"` | 尺寸 |
| invalid | `boolean` | `false` | 独立使用（非 Field 内）时手动置无效态皮肤 |
| className | `string` | — | 透传类名 |

### SelectContent
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top" ｜ "bottom"` | `"bottom"` | 弹出方向 |
| align | `"start" ｜ "center" ｜ "end"` | — | 对齐 |
| sideOffset | `number` | — | 偏移量 |

### SelectItem
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `string` | — | 选项值（本批仅 string 值） |
| disabled | `boolean` | `false` | 禁用此项 |

## Events

`Select` 透传 Base UI `Select.Root` 的常用事件。

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string ｜ null, eventDetails) => void` | 选中值变化回调（透传 Base UI `Select.Root`） |
| onOpenChange | `(open: boolean, eventDetails) => void` | 下拉开合变化回调（透传 Base UI `Select.Root`） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| SelectContent.children* | `ReactNode` | 一组 `SelectItem` |
| SelectItem.children* | `ReactNode` | 选项展示内容 |

## 示例
```tsx
const FONTS = [
  { value: "sans", label: "无衬线 Sans" },
  { value: "serif", label: "衬线 Serif" },
  { value: "mono", label: "等宽 Mono" },
];

<Select items={FONTS} placeholder="请选择字体" defaultValue="serif">
  <SelectTrigger />
  <SelectContent>
    {FONTS.map((f) => (
      <SelectItem key={f.value} value={f.value}>{f.label}</SelectItem>
    ))}
  </SelectContent>
</Select>
```

## 禁忌 / 坑

- 占位文本通过 `Select` 的 `placeholder` prop 传，**不要**给 `Select.Value` 传 placeholder——见 [[base-ui-select-rc0-no-value-placeholder-prop-inject-null-item]]：本项目锁 Base UI rc.0，其 `Select.Value` 没有 placeholder prop（那是 v1.2+），瑚琏靠注入一个 `value:null` 的 items 项实现占位 label。`items` 与 `SelectItem` 的 value 要对应，否则 Trigger 显示 raw value 而非 label。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# ShimmerButton

> 微光按钮 · 边缘游走火花(conic) + token + RSC · forms/button · #animated

## 何时用

需要吸睛的主 CTA，边缘有一道游走的 conic 火花高光。普通操作用 [Button](https://hulianui.haloritual.com/components/button)；彩虹流光底用 [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button)；外扩脉冲光环用 [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button)。

## 导入
```ts
import { ShimmerButton } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| shimmerColor | `string` | `var(--color-primary-foreground)` | 火花高光色 |
| shimmerSize | `string` | `0.05em` | 火花宽度 |
| borderRadius | `string` | `var(--radius)` | 圆角 |
| shimmerDuration | `string` | `3s` | 一轮火花秒数 |
| background | `string` | `var(--color-primary)` | 按钮底色 |
| ...buttonProps | `ComponentPropsWithoutRef<"button">` | — | 透传原生 button 属性 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 点击回调，经 `ComponentPropsWithoutRef<"button">` 透传 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮文案，经原生 button 属性透传 |
| render | `ReactElement` | 渲染为自定义元素（如 `<a>`/Next `<Link>`），样式/内部火花结构合并进该元素；文案仍取 children |

## 示例
```tsx
<ShimmerButton>开始使用 瑚琏</ShimmerButton>

// 换底色
<ShimmerButton background="var(--color-danger)">删除</ShimmerButton>
```

## 禁忌 / 坑

- 颜色类 prop 应传 token CSS 变量（如 `var(--color-danger)`）以随主题切换，别硬编码裸色值。
- 自定义往按钮塞图标+文字若图标掉行，是 Tailwind Preflight `svg{display:block}` 所致，见 [[tailwind-preflight-svg-block-breaks-icon-text-in-nonflex-button]]——确保文案容器是 `inline-flex`。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group) · [SocialButton](https://hulianui.haloritual.com/components/social-button)

<!-- ════════════════════════════════════════════════════════ -->
# Slider

> 滑块 · Base UI 单值/range + 键盘步进 · forms/basic

## 何时用

在连续/分档区间内拖选一个数值或一个范围（音量、价格区间、百分比）、且大致量级比精确数字更重要时用。需精确录入数字并带 ±步进按钮用 [NumberField](https://hulianui.haloritual.com/components/number-field)；离散少量挡位也可用 [Segmented](https://hulianui.haloritual.com/components/segmented)。

## 导入
```ts
import { Slider } from "@hulianui/ui"
```

## Props

透传 Base UI `Slider.Root`（除 `render`/`children`），下表为常用项；`value` 为 `number` 时单值、为 `number[]` 时自动走 range。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `number｜readonly number[]` | — | 受控值（数组=range） |
| defaultValue | `number｜readonly number[]` | — | 非受控初始值 |
| min | `number` | `0` | 最小值 |
| max | `number` | `100` | 最大值 |
| step | `number` | `1` | 步进量 |
| disabled | `boolean` | `false` | 禁用 |
| showValue | `boolean` | `false` | 在轨道上方显示当前数值读出（Slider.Value） |
| className | `string` | — | Root wrapper className |

> 其余 Base UI `Slider.Root` 的 prop（`name`、`orientation` 等）原样透传。

## Events

透传 Base UI `Slider.Root`，下表为常用项（签名照上游）。

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: number｜number[], eventDetails) => void` | 值变化回调（单值传 number、range 传 number[]） |
| onValueCommitted | `(value: number｜number[], eventDetails) => void` | 拖动结束/提交时回调 |

## 示例
```tsx
<Slider defaultValue={60} showValue className="w-64" />
```

范围（range）：
```tsx
<Slider defaultValue={[25, 75]} showValue className="w-64" />
```

## 禁忌 / 坑

- 单值传 `number`、范围传 `number[]`——传数组即自动 range，别再找单独的 range prop。
- 想看到数值读出需显式 `showValue`（默认不显示）。
- `className` 落在 Root wrapper；宽度需自己给（如 `w-64`），否则可能塌成内容宽。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# SocialButton

> 第三方登录按钮 · 微信/支付宝/QQ/微博 + GitHub/Google/Apple/X 品牌 logo(内联 simple-icons·零依赖) + outline/solid 变体 + 纯 logo 方钮 + loading · 黑白系品牌 solid 随主题前景避暗色不可见 · forms/button

## 何时用

第三方账号登录/绑定入口（微信、支付宝、QQ、微博、GitHub、Google、Apple、X）。内置品牌 logo、默认文案与品牌色，无需自己接 simple-icons。普通操作按钮用 [Button](https://hulianui.haloritual.com/components/button)；需要把多个登录方式编成一组用 [ButtonGroup](https://hulianui.haloritual.com/components/button-group) 包裹。

## 导入
```ts
import { SocialButton } from "@hulianui/ui"
```

## Props

继承原生 `<button>` 属性（除 `children` 受控覆盖外）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| provider* | `"wechat" ｜ "alipay" ｜ "qq" ｜ "weibo" ｜ "github" ｜ "google" ｜ "apple" ｜ "x"` | — | 第三方平台，决定 logo、默认文案与品牌色 |
| variant | `"solid" ｜ "outline"` | `"outline"` | solid=品牌色填充（黑白品牌随主题前景）；outline=描边中性底 + 品牌色 logo（推荐） |
| shape | `"button" ｜ "icon"` | `"button"` | button=带文案；icon=纯 logo 方钮 |
| size | `"sm" ｜ "md" ｜ "lg"` | `"md"` | 尺寸 |
| loading | `boolean` | `false` | 提交中：logo 替换为转圈并禁用 |
| className | `string` | — | 透传根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | 透传原生点击回调（发起第三方登录/绑定） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖默认文案（如「使用微信登录」→「微信」） |

## 示例
```tsx
<SocialButton provider="wechat" />
<SocialButton provider="github" variant="solid" />
```
```tsx
{/* 纯 logo 方钮 + 加载态 */}
<SocialButton provider="alipay" shape="icon" />
<SocialButton provider="github" loading />
```

## 禁忌 / 坑

暂无已知坑。`loading` 会自动禁用按钮，无需额外传 `disabled`。github/x/apple 黑白系品牌的 solid 态会跟随主题前景色，避免在暗色下不可见——不要硬写品牌黑覆盖。

## 相关
[Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button) · [RainbowButton](https://hulianui.haloritual.com/components/rainbow-button) · [PulsatingButton](https://hulianui.haloritual.com/components/pulsating-button) · [RippleButton](https://hulianui.haloritual.com/components/ripple-button) · [ButtonGroup](https://hulianui.haloritual.com/components/button-group)

<!-- ════════════════════════════════════════════════════════ -->
# StepsForm

> 分步表单 · 复用 Steps 指示器 + 上一步/下一步/提交导航 + onStepValidate 逐步校验 + 跨步保值(消费者 useForm 持有·文案接 i18n) · forms/framework

## 何时用

向导式录入（注册、开户、导入流程）需要把长表单切成多步、逐步校验时用。和 [Form](https://hulianui.haloritual.com/components/form)/[ProForm](https://hulianui.haloritual.com/components/pro-form) 的区别：后者一屏铺所有字段、一次提交；StepsForm 只渲染当前步、按步前进。值由**消费者自己的 useForm 持有**（本组件不托管表单状态），所以跨步切换不丢值。

## 导入
```ts
import { StepsForm } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| steps* | `StepsFormStep[]` | — | 步骤数组，每项含 `title`/`description`/`content`/`nextDisabled`/`nextText`/`showNav` |
| current | `number` | — | 受控当前步（0 起） |
| defaultCurrent | `number` | — | 非受控初始步 |
| direction | `"horizontal" \| "vertical"` | — | Steps 指示器方向 |
| className | `string` | — | 根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCurrentChange | `(current: number) => void` | 步骤变化回调 |
| onStepValidate | `(currentStep: number) => boolean \| Promise<boolean>` | 前进/提交前校验，收到即将离开的步号；返回 false 或 reject 阻止前进；pending 期间前进按钮 loading 防重复点击 |
| onFinish | `() => void \| Promise<void>` | 最后一步提交；返回 Promise → 提交按钮 loading |

`StepsFormStep` 字段：`title: ReactNode`（必填）、`description?`、`content: ReactNode`（必填，仅当前步渲染）、`nextDisabled?`（默认 false，禁本步前进）、`nextText?`（本步前进按钮文案，缺省走 locale）、`showNav?`（默认 true，false 时不渲染本步底部导航，用于结果步自带操作）。

## 示例
```tsx
const form = useForm({ initialValues: { name: "", company: "" } });
const name = form.register("name", { rules: [{ required: true, message: "请输入姓名" }] });

<StepsForm
  onStepValidate={async (step) => {
    if (step === 0) return (await form.validateField("name")) == null;
    return true;
  }}
  onFinish={async () => {
    const r = await form.validate();
    if (r.ok) await api.save(r.values);
  }}
  steps={[
    { title: "基本信息", content: (
        <Field label="姓名" error={name.error}>
          <Input value={name.value as string} onChange={name.onChange} onBlur={name.onBlur} />
        </Field>
      ) },
    { title: "公司信息", content: <Field label="公司">{/* ... */}</Field> },
  ]}
/>
```

## 禁忌 / 坑

- 本组件**不持有字段值**——必须由消费者的 `useForm` 持有，否则切步会丢输入。`onStepValidate` 里只校验本步字段（用 `form.validateField`），别一上来 `form.validate()` 全量校验把后续步的空字段也判错。
- `current` 受控时务必同时接 `onCurrentChange`，否则点导航不动步。
- 结果步要自带「再来一遍」之类操作时，给该步 `showNav: false` 关掉内置上一步/下一步。

## 相关
[Form](https://hulianui.haloritual.com/components/form) · [ModalForm / DrawerForm](https://hulianui.haloritual.com/components/form-dialog) · [ProForm](https://hulianui.haloritual.com/components/pro-form) · [LoginForm](https://hulianui.haloritual.com/components/login-form) · [Field](https://hulianui.haloritual.com/components/field) · [SearchForm](https://hulianui.haloritual.com/components/search-form)

<!-- ════════════════════════════════════════════════════════ -->
# Switch

> 开关 · Base UI 受控 + ARIA · forms/basic

## 何时用

切换一个即时生效的布尔开关（如「开启通知」），改动立刻应用、无需提交按钮时用。需在两个互斥选项间二选一且语义对等用 [Radio](https://hulianui.haloritual.com/components/radio)；提交表单时勾选的布尔项（如「同意条款」）用 [Checkbox](https://hulianui.haloritual.com/components/checkbox)。

## 导入
```ts
import { Switch } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| checked | `boolean` | — | 受控开关态 |
| defaultChecked | `boolean` | `false` | 非受控初始态 |
| disabled | `boolean` | `false` | 禁用 |
| id | `string` | — | — |
| className | `string` | — | — |
| aria-label | `string` | — | 无可见标题时提供 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCheckedChange | `(checked: boolean) => void` | 开关变化回调 |

## 示例
```tsx
<Switch defaultChecked aria-label="开启通知" />
```

受控：
```tsx
const [on, setOn] = useState(false);
<Switch checked={on} onCheckedChange={setOn} aria-label="开启通知" />
```

## 禁忌 / 坑

- 用 `checked`/`onCheckedChange` 即受控，须自管 state；只给初值用 `defaultChecked`，二者不要混用。
- 无可见标题时务必给 `aria-label`，否则读屏无名。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# Textarea

> 多行输入 · 自适应高度 · forms/basic

## 何时用

多行文本输入（备注、描述、留言）。单行输入用 [Input](https://hulianui.haloritual.com/components/input)；从固定选项选一项用 [Select](https://hulianui.haloritual.com/components/select)。开 `autoResize` 让高度随内容增长，`rows` 作为下限。放进 hulian Field 内会自动接管 label/error/aria 关联。

## 导入
```ts
import { Textarea, textareaVariants } from "@hulianui/ui"
```

## Props

继承原生 `<textarea>` 属性（除 `size` 被覆盖外，如 `value`/`onChange`/`rows`/`placeholder`/`disabled`…）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" ｜ "md" ｜ "lg"` | `"md"` | 尺寸（CVA 变体，覆盖原生 size） |
| invalid | `boolean` | `false` | 独立使用时标红；在 hulian Field 内由 Field.Root invalid 自动驱动 |
| autoResize | `boolean` | `false` | 随内容自适应高度（JS scrollHeight，`rows` 为下限） |
| rows | `number` | `3` | 初始/最小行高 |
| disabled | `boolean` | `false` | 禁用 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(e: ChangeEvent<HTMLTextAreaElement>) => void` | 透传原生输入回调（受控时配合 `value` 使用） |

## 示例
```tsx
<Textarea placeholder="写点什么…" className="w-64" />
```
```tsx
{/* 自适应高度 */}
<Textarea autoResize defaultValue={"随内容长高\n第二行\n第三行"} className="w-64" />
```

## 禁忌 / 坑

- 实现/扩展 field-aware Textarea 时见 [[base-ui-field-control-render-textarea-type-safe]]：Base UI Field 无 Textarea 原语，textarea 专属 props（ref/rows/onInput）要放在 `render` 元素上而非 `Field.Control`，否则 TS 报 ref 类型错或静默丢 Field a11y 接线。
- 在 hulian Field 内不要重复传 `invalid`，由 Field.Root 自动驱动。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio) · [Switch](https://hulianui.haloritual.com/components/switch)

<!-- ════════════════════════════════════════════════════════ -->
# TimeField

> 时间输入 · MUI X 桥(分段编辑 HH:mm 24h) + ISO 受控 · forms/datetime · MUI 桥

## 何时用

只选**时间**（HH:mm 24 小时制分段输入、无弹层）时用。要日期 + 时间一体弹层用 [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker)；只选日期用 [DatePicker](https://hulianui.haloritual.com/components/date-picker)。

## 导入
```ts
import { TimeField } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string \| null` | — | ISO 字符串受控值；传入即受控 |
| defaultValue | `string` | — | ISO 字符串非受控默认值 |
| label | `string` | `"选择时间"` | 输入框 label |
| disabled | `boolean` | `false` | 禁用 |
| readOnly | `boolean` | `false` | 只读 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(iso: string \| null) => void` | 受控回调，回传 ISO 或 null（替代 MUI 的 onChange） |

## 示例
```tsx
function Demo() {
  const [v, setV] = useState<string | null>("2026-06-03T09:30:00");
  return <TimeField label="选择时间" value={v} onValueChange={setV} />;
}
```
```tsx
<TimeField label="起始时间" defaultValue="2026-06-03T08:00:00" />
```

## 禁忌 / 坑

- 受控/非受控二选一：给 `value` 走受控须配 `onValueChange`；只想要初值用 `defaultValue`，别同时给。
- 对外值仍是完整 ISO 字符串（带日期部分，只是时间可编辑），不是裸 `HH:mm`；回调回传 ISO 或 null。

## 相关
[Calendar](https://hulianui.haloritual.com/components/calendar) · [DatePicker](https://hulianui.haloritual.com/components/date-picker) · [DateTimePicker](https://hulianui.haloritual.com/components/date-time-picker) · [DateRangePicker](https://hulianui.haloritual.com/components/date-range-picker) · [Button](https://hulianui.haloritual.com/components/button) · [ShimmerButton](https://hulianui.haloritual.com/components/shimmer-button)

<!-- ════════════════════════════════════════════════════════ -->
# Toggle

> 切换按钮 · Base UI pressed 态 + ToggleGroup 单/多选 · forms/basic

## 何时用

带按下态的图标/文字按钮（工具栏加粗、对齐、AI 工具栏「深度思考」开关）用 Toggle；多个 Toggle 互斥单选或多选共存用 ToggleGroup。语义是「开关一个设置」而非「按钮态」时用 [Switch](https://hulianui.haloritual.com/components/switch)；纯单选一组对等选项用 [Radio](https://hulianui.haloritual.com/components/radio)。

## 导入
```ts
import { Toggle, ToggleGroup, toggleVariants } from "@hulianui/ui"
```

## Props

`Toggle`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| pressed | `boolean` | — | 受控按下态 |
| defaultPressed | `boolean` | `false` | 非受控初始按下态 |
| disabled | `boolean` | `false` | 禁用 |
| value | `string` | — | 在 ToggleGroup 内标识该项 |
| variant | `"default"｜"outline"｜"pill"` | `"default"` | default=灰底软选中 / outline=主色实心 / pill=圆角描边 + soft 主色选中（AI 工具栏开关风） |
| size | `"sm"｜"md"` | `"md"` | — |
| className | `string` | — | — |
| aria-label | `string` | — | 仅图标时必填 |

`ToggleGroup`

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string[]` | — | 受控：已按下项 value 数组 |
| defaultValue | `string[]` | — | 非受控初始按下项数组 |
| disabled | `boolean` | `false` | 整组禁用 |
| multiple | `boolean` | `false` | true=多选共存；false=单选互斥 |
| orientation | `"horizontal"｜"vertical"` | `"horizontal"` | — |
| className | `string` | — | — |

## Events

`Toggle`

| 事件 | 类型 | 说明 |
|------|------|------|
| onPressedChange | `(pressed: boolean) => void` | 按下态变化（瑚琏收敛签名，丢 Base UI eventDetails） |

`ToggleGroup`

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string[]) => void` | 变化回调 |

## Slots

`Toggle`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 图标 / 文字 |

`ToggleGroup`

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内放 `Toggle` 项 |

## 示例

单个 toggle（受控）：
```tsx
const [on, setOn] = useState(false);
<Toggle pressed={on} onPressedChange={setOn} aria-label="加粗">
  <Bold className="size-4" />
</Toggle>
```

互斥单选组：
```tsx
<ToggleGroup defaultValue={["center"]}>
  <Toggle value="left" aria-label="左对齐"><AlignLeft className="size-4" /></Toggle>
  <Toggle value="center" aria-label="居中"><AlignCenter className="size-4" /></Toggle>
  <Toggle value="right" aria-label="右对齐"><AlignRight className="size-4" /></Toggle>
</ToggleGroup>
```

## 禁忌 / 坑

- 即便在 `ToggleGroup` 内，选中态也以 value 数组管理——`multiple={false}` 时数组里只会有 0 或 1 个元素。
- 仅渲染图标（无文字）的 `Toggle` 必须给 `aria-label`，否则读屏无名。
- 用 `pressed`/`onPressedChange`（或 group 的 `value`/`onValueChange`）即受控，须自管 state；非受控只给 `defaultPressed`/`defaultValue`。

## 相关
[Input](https://hulianui.haloritual.com/components/input) · [Textarea](https://hulianui.haloritual.com/components/textarea) · [Select](https://hulianui.haloritual.com/components/select) · [Checkbox](https://hulianui.haloritual.com/components/checkbox) · [CheckboxGroup](https://hulianui.haloritual.com/components/checkbox-group) · [Radio](https://hulianui.haloritual.com/components/radio)

<!-- ════════════════════════════════════════════════════════ -->
# Transfer

> 穿梭框 · 左右双 listbox 面板 + 移动按钮(选中/全部) + 可选搜索 + 空态(零依赖·复用 Listbox/Empty) · forms/advanced

## 何时用

权限分配、可见字段、白名单等「从全集里挑一批进目标集」且两侧都要可见可搜的场景用。当候选项有几十上百条、要批量勾选并能两边对照时比多选 [Listbox](https://hulianui.haloritual.com/components/listbox) 直观。如果只是单列多选、不需要「已选/未选」分栏对照，用 Listbox `multiple` 即可。

## 导入
```ts
import { Transfer } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| dataSource* | `TransferItem[]` | — | 全量数据源；每项 `key`/`label`，可带 `description`/`disabled` |
| targetKeys | `string[]` | — | 受控：右侧（目标）面板的键集合 |
| defaultTargetKeys | `string[]` | — | 非受控初始目标键 |
| searchable | `boolean` | `false` | 每个面板顶部显示搜索框 |
| searchPlaceholder | `string` | `"搜索"` | 搜索框占位符 |
| filterOption | `(input: string, item: TransferItem) => boolean` | label 包含匹配 | 自定义过滤（默认大小写不敏感子串） |
| disabled | `boolean` | `false` | 整体禁用（两侧列表与移动按钮全失效） |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(targetKeys: string[], direction: "left" \| "right", movedKeys: string[]) => void` | 移动后回调，`direction` 为 `"right"`（入选）/`"left"`（移出） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| titles | `[ReactNode, ReactNode]` | 左右面板标题（默认 `["源列表","已选"]`） |

## 示例
```tsx
const [target, setTarget] = useState<string[]>(["dashboard", "orders"]);
<Transfer
  dataSource={modules}
  targetKeys={target}
  onChange={setTarget}
  titles={["全部功能模块", "已授权"]}
  searchable
/>
```

## 禁忌 / 坑

- `onChange` 首参就是移动后的完整目标键集合，直接 `setTarget` 即可（无需自己合并 `movedKeys`）；后两参 `direction`/`movedKeys` 用于审计/差量提示。
- `disabled` 的 item 不可勾选、也**不随「全部移入/移出」按钮移动**——设计如此，用于冻结历史项。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# TreeSelect

> 树选择器 · 触发器 + Popover 浮层内嵌 Tree + 单选/多选(checkable)对称 + 树内搜索 · 复用树引擎核 · forms/advanced

## 何时用

数据源本身是层级结构（组织架构、分类目录、地区），需要在收拢的触发器里选一个或多个节点时用。若选项是扁平列表用 [Combobox](https://hulianui.haloritual.com/components/combobox)/[Listbox](https://hulianui.haloritual.com/components/listbox)；若是固定的省市区级联用 [RegionCascader](https://hulianui.haloritual.com/components/region-cascader)。

## 导入
```ts
import { TreeSelect } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes* | `TreeNode[]` | — | 树数据源（含 key/label/children），从 `../tree/tree-core` 复用 |
| value | `string \| string[]` | — | 受控值；单选为 string，多选为 string[] |
| defaultValue | `string \| string[]` | — | 非受控初值 |
| multiple | `boolean` | `false` | 多选（checkable，父子级联勾选） |
| placeholder | `string` | — | 触发器占位文案 |
| disabled | `boolean` | `false` | 禁用 |
| invalid | `boolean` | `false` | 无效态（外壳变 danger） |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 触发器尺寸 |
| searchable | `boolean` | `true` | 浮层内树搜索框，多层命中跳转 |
| showLine | `boolean` | — | 显示树连接线 |
| className | `string` | — | 透传到触发器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(value: string \| string[]) => void` | 选择变更回调；单选回传 string，多选回传 string[] |

## 示例
```tsx
// 单选 + 搜索
const [v, setV] = useState<string | string[]>("");
<TreeSelect nodes={NODES} value={v} onChange={setV} placeholder="选择归属部门" searchable />

// 多选：父级勾选级联到叶，取消单叶父级落半选
const [v, setV] = useState<string | string[]>(["fe-web", "fe-mini"]);
<TreeSelect nodes={NODES} multiple value={v} onChange={setV} placeholder="勾选可见部门" />
```

## 禁忌 / 坑

- `value` 受控时 `multiple` 切换会改变值的类型（string ↔ string[]），onChange 回调的入参类型随 `multiple` 而变，消费侧需按当前模式分支处理，不要混存。
- 多选下 `value` 只需传叶子/已选 key，父级半选态由组件依树结构派生，不要手动塞入半选父 key。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)

<!-- ════════════════════════════════════════════════════════ -->
# Upload

> 文件上传 · 拖拽落区/按钮形态 + accept/maxSize 校验 + 受控文件列表(状态/进度)，零依赖自研只发 onSelect · forms/advanced

## 何时用

需要选/拖文件并展示带状态进度的文件列表时用。注意：组件**不做网络传输**，它只在通过 `accept`/`maxSize` 校验后回 `onSelect`，真正上传、进度回填由消费者完成（受控 `files`）。落区形态用 `variant="dropzone"`，紧凑场景用 `variant="button"`。图片选完要裁剪请配合 [ImageCropper](https://hulianui.haloritual.com/components/image-cropper)。

## 导入
```ts
import { Upload, matchesAccept } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| accept | `string` | — | 原生 accept（如 `"image/*,.pdf"`）；同时用于落区校验 |
| multiple | `boolean` | `false` | 是否允许多选 |
| disabled | `boolean` | `false` | 禁用 |
| maxSize | `number` | — | 单文件字节上限；超限进 `onReject(reason="size")` |
| variant | `"dropzone" \| "button"` | `"dropzone"` | 形态：拖拽落区 / 单按钮 |
| files | `UploadFile[]` | — | 受控展示的文件列表（含状态/进度）；不传则不渲染列表 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(files: File[]) => void` | 通过校验的文件被选中（点击选择或拖入） |
| onReject | `(rejections: UploadRejection[]) => void` | 被校验拒绝的文件（类型/大小） |
| onRemove | `(id: string) => void` | 列表项移除按钮点击 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 落区主文案 |
| hint | `ReactNode` | 落区辅助说明（格式/大小限制提示） |
| buttonLabel | `ReactNode` | button 形态的按钮文案（默认 `"选择文件"`） |
| children | `ReactNode` | 自定义落区内容（覆盖 label/hint） |

> `UploadFile`：`{ id; name; size?; status?: "ready"\|"uploading"\|"success"\|"error"; progress?; error? }`，`progress` 仅 `status="uploading"` 时展示进度条。

## 示例
```tsx
const [files, setFiles] = useState<UploadFile[]>([]);
<Upload
  multiple
  maxSize={5 * 1024 * 1024}
  hint="支持任意格式，单文件 ≤ 5MB"
  files={files}
  onSelect={(picked) => /* 上传并回填 files */}
  onRemove={(id) => /* 移除 */}
/>
```

按钮形态 + 仅图片：
```tsx
<Upload variant="button" accept="image/*" files={files} onSelect={add} onRemove={remove} />
```

## 禁忌 / 坑

- 组件只发 `onSelect`，**不会自己上传**。进度条/成功/失败态全靠消费者把 `UploadFile.status`/`progress`/`error` 回填到受控 `files`。
- 想知道某文件为何被拒（类型 vs 大小）接 `onReject`，`reason` 区分 `"size"`/`"type"`。
- 暂无其它已知坑。

## 相关
[SecretField](https://hulianui.haloritual.com/components/secret-field) · [Combobox](https://hulianui.haloritual.com/components/combobox) · [Listbox](https://hulianui.haloritual.com/components/listbox) · [Mentions](https://hulianui.haloritual.com/components/mentions) · [InputOTP](https://hulianui.haloritual.com/components/input-otp) · [Rating](https://hulianui.haloritual.com/components/rating)


# ━━━━━━━━ 数据展示 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# AnimatedList

> 动效列表 · 子项逐个淡入上移入场(motion + 进入视口) · data-display/collection · #animated

## 何时用

进入视口时让一组子项逐个淡入上移入场，用于通知流、动态 feed、特性条目等需要「依次出现」节奏的列表。只要静态列表无需入场动画就别用它（省掉 motion + 视口监听）；要拖拽排序用 [Sortable](https://hulianui.haloritual.com/components/sortable)。

## 导入
```ts
import { AnimatedList } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| stagger | number | — | 相邻子项入场间隔（秒） |
| className | string | — | 容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | ReactNode | 列表子项（每个子项依次入场） |

## 示例
```tsx
<AnimatedList className="w-72">
  <Row t="新订单" d="¥128 · 刚刚" />
  <Row t="付款成功" d="¥99 · 1 分钟前" />
  <Row t="新评价" d="★★★★★ · 3 分钟前" />
</AnimatedList>
```

## 禁忌 / 坑

- 入场由「进入视口」触发（motion），是客户端组件；元素在视口外时保持初始隐藏态，依赖 SSR 首屏可见的内容慎用。
- 子项依赖渲染顺序逐个 stagger，动态增删子项会重新编排顺序——稳定 key 必给。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Avatar

> 头像 · Base UI 图片+fallback · data-display/info

## 何时用

展示单个用户头像，图片加载失败/缺省时回退到 fallback（首字母等）。需要头像 + 名称/描述组合用 [[User](https://hulianui.haloritual.com/components/user)]；多人堆叠头像组用 AvatarCircles。

## 导入
```ts
import { Avatar } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" \| "md" \| "lg"` | `"md"` | 圆直径档位（CVA 变体）。 |
| src | `string` | — | 头像图片 URL；加载失败回退到 fallback。 |
| alt | `string` | — | 图片替代文本。 |
| className | `string` | — | — |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | 无图/加载失败时显示（通常为首字母）。 |

## 示例
```tsx
<Avatar src="/demo/avatar-12.jpg" alt="瑚琏" fallback="ZS" />
```
```tsx
// 无图回退
<Avatar size="lg" fallback="瑚" />
```

## 禁忌 / 坑

- 基于 Base UI Avatar，`src` 失败时才显示 `fallback`；务必给 `fallback` 否则失败/无图时空白。
- `size` 是受限档位（sm/md/lg），自定义尺寸用 `className` 覆盖。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# AvatarCircles

> 堆叠头像组 · 重叠 + ring + +N 计数(扩 Avatar·RSC) · data-display/info

## 何时用

紧凑展示一组参与者/成员头像（重叠堆叠 + 末尾「+N」计数）。单个头像用 [[Avatar](https://hulianui.haloritual.com/components/avatar)]；带名称/描述的单用户卡用 User。

## 导入
```ts
import { AvatarCircles, avatarCirclesItemVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| avatars* | `AvatarCirclesItem[]` | — | 头像列表（按序堆叠，后者压前者）。每项 `{ src: string; alt?: string }`。 |
| extraCount | `number` | — | 额外人数，渲染为末尾 "+N" 圆。 |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 圆直径档位。 |
| className | `string` | — | — |

## 示例
```tsx
const avatars = [
  { src: "/demo/avatar-1.jpg", alt: "u1" },
  { src: "/demo/avatar-2.jpg", alt: "u2" },
  { src: "/demo/avatar-3.jpg", alt: "u3" },
]
<AvatarCircles avatars={avatars} extraCount={9} />
```
```tsx
<AvatarCircles avatars={avatars} size="lg" />
```

## 禁忌 / 坑

- 每个 `avatars` 项要求 `src`（与单个 Avatar 不同，这里没有 fallback 槽）；列表项无图会留空圆。
- `extraCount` 仅渲染计数标记，不会自动从列表长度推算，按真实溢出人数手动传。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Badge

> 计数角标 · count/max 溢出 + dot + 自定义内容 + 包裹叠加(四角/offset) · data-display/info

## 何时用

在图标/头像等宿主上叠加未读计数、红点或小勾时用（消息数、在线点、绿勾认证）。它表达「数量/有无」并叠加到宿主四角；要表达「分类/状态文字标签且可移除」用 [Chip](https://hulianui.haloritual.com/components/chip)；只要一个独立的语义状态圆点用 [Dot](https://hulianui.haloritual.com/components/dot)。

## 导入
```ts
import { Badge } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| count | `number` | — | 数字计数；为 0 时默认隐藏（除非 showZero）。 |
| max | `number` | `99` | 超过则显示 `max+`。 |
| dot | `boolean` | `false` | 仅显示小圆点不显示数字（优先级高于 count）。 |
| showZero | `boolean` | `false` | count=0 仍显示。 |
| invisible | `boolean` | — | 强制隐藏角标，保留被包裹子元素。 |
| tone | `"neutral"｜"brand"｜"success"｜"warning"｜"danger"` | `danger` | 语气色（默认通知红）。 |
| size | `"sm"｜"md"` | `md` | 尺寸。 |
| placement | `"top-right"｜"top-left"｜"bottom-right"｜"bottom-left"` | `top-right` | 有 children 时角标叠加的角位。 |
| offset | `[number, number]` | — | 角标位置微调 [x, y] px（正值=右/下），圆形宿主常用来外推贴边。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| content | `ReactNode` | 自定义角标内容（如图标 ✓），优先级最高，覆盖 count/dot。 |
| children | `ReactNode` | 被叠加的宿主元素；不传则角标独立渲染。 |

## 示例
```tsx
// 独立计数 + 溢出
<Badge count={1000} max={99} />

// 头像右下角在线点
<Badge dot tone="success" placement="bottom-right">
  <Avatar fallback="瑚" />
</Badge>
```

## 禁忌 / 坑

暂无已知坑。优先级链记牢：`content` > `dot` > `count`——同时传只生效最高者。`count=0` 默认隐藏整个角标，要显示「0」须显式 `showZero`。圆形宿主（头像）四角贴边常需 `offset` 外推几像素。候选坑 `workflow-badge-denominator-numerator-alignment` 讲的是工作流进度「分子/分母」对齐，与本计数角标无关，不适用。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# BentoGrid

> 错落栅格 · BentoGrid/BentoCard 复合 + 跨列跨行 + hover CTA(纯 CSS·RSC) · data-display/collection

## 何时用

用错落响应式栅格展示一组特性/能力卡片（落地页特性区、产品亮点墙），靠 `className` 上的 `sm:col-span-2` 等让卡片跨列跨行形成「便当盒」节奏。要纯数据二维表格用 [Table](https://hulianui.haloritual.com/components/table)；要列表页查询区+工具栏的企业表格用 [ProTable](https://hulianui.haloritual.com/components/pro-table)。

## 导入
```ts
import { BentoGrid, BentoCard } from "@hulianui/ui"
```

## Props

### BentoGrid
继承 `HTMLAttributes<HTMLDivElement>`，无自有 prop——容器，靠 `className` 调栅格列数。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| ...div | HTMLAttributes\<HTMLDivElement\> | — | 透传（`className` 控列数等） |

### BentoCard
继承 `Omit<HTMLAttributes<HTMLDivElement>, "title">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| ...div | Omit\<HTMLAttributes\<HTMLDivElement\>, "title"\> | — | 透传（用 `className="sm:col-span-2"` 跨列） |

## Slots

### BentoGrid

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | ReactNode | 一组 `BentoCard` |

### BentoCard

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | ReactNode | 卡片标题 |
| description | ReactNode | 描述 |
| icon | ReactNode | 左上图标/装饰 |
| cta | ReactNode | 底部行动区（按钮/链接） |
| children | ReactNode | 自定义卡片内容 |

## 示例
```tsx
import { Zap, Shield } from "lucide-react";

<BentoGrid className="w-full max-w-2xl">
  <BentoCard
    className="sm:col-span-2"
    icon={<Zap />}
    title="极速"
    description="纯 CSS 优先，零运行时开销"
  />
  <BentoCard icon={<Shield />} title="可靠" description="WAI-ARIA + 测试覆盖" />
</BentoGrid>
```

## 禁忌 / 坑

- 跨列/跨行靠卡片自身 `className`（如 `sm:col-span-2`），不是 props——别去找 `span` 这类 prop。
- `BentoCard` 的 `title` 被 `Omit` 掉了原生 `title` 属性，传 `title` 即卡片标题节点，不会渲染成 HTML tooltip。
- 纯 CSS + RSC，无客户端依赖，可直接在 Server Component 里用。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Book3D

> 3D 立体书 · CSS 3D transform 透视书体(前封/书脊/页块/后封) + 渐变或图封面 + 封面标题副标 + 角标缎带 + hover 翻正(纯 transform·GPU 合成·reduced-motion 降级) · 作品集书架/封面墙 · data-display/collection · #animated

## 何时用

作品集/书架/封面墙这类需要立体书视觉的展示场景用，hover 时书体翻正、可选翻开内页。它是纯装饰展示卡，和本组下的数据型组件（[Table](https://hulianui.haloritual.com/components/table)/[PricingTable](https://hulianui.haloritual.com/components/pricing-table)）无关；要规整网格卡片用 [List](https://hulianui.haloritual.com/components/list)。

## 导入
```ts
import { Book3D } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| cover | `string` | — | 封面图 url；提供时覆盖 coverColor 渐变 |
| logo | `string` | — | 封面中心叠加的产品 logo / app icon（图 url），标题落底部 |
| coverColor | `{ from: string; to: string }` | 品牌渐变 | 封面渐变色 |
| spineColor | `string` | 浅纸色 | 书脊/页厚颜色（CSS color） |
| thickness | `string` | `"2.25rem"` | 书脊厚度（CSS 长度） |
| ribbon | `string` | — | 角标缎带文字（如 "NEW" / "N°1"） |
| ribbonTone | `"brand" \| "danger" \| "success"` | `"danger"` | 缎带语气 |
| href | `string` | — | 提供则整本书是链接 |
| target | `string` | — | 外链是否新窗（href 时生效） |
| className | `string` | — | 根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `() => void` | 无 href 时提供则整本书是按钮 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 封面主标题（如 "CSS" / "JS"） |
| subtitle | `ReactNode` | 封面副标题（如 "转换" / "FUNCTION"） |
| inside | `ReactNode` | 内页内容；提供则 hover 时前封绕书脊翻开露出内页 |

## 示例
```tsx
// 书架（多本并排，hover 翻正）
<div className="flex flex-wrap gap-8">
  <Book3D title="CSS" subtitle="转换" ribbon="NEW" coverColor={{ from: "#f7b733", to: "#e0992b" }} />
  <Book3D title="JS" subtitle="FUNCTION" coverColor={{ from: "#5aa6e0", to: "#3f7fc0" }} />
  <Book3D title="HTML" subtitle="5" ribbon="N°1" ribbonTone="danger" coverColor={{ from: "#e0654a", to: "#c14a32" }} />
</div>

// 品牌渐变（默认 coverColor）
<Book3D title="瑚琏" subtitle="hulianui" />
```

## 禁忌 / 坑

- `cover`（图封面）会覆盖 `coverColor`（渐变），二者同传以图为准。
- hover 翻正/翻开是纯 CSS transform 动画，`prefers-reduced-motion` 下自动降级——不要再额外包 JS 动画。
- `href` 和 `onClick` 二选一：有 href 整本是 `<a>`，否则有 onClick 是 `<button>`。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# BounceCards

> 一叠卡片扇形铺开的入场弹跳组件 · 逐张 scale 0 弹性弹入 + hover 推挤让位（零依赖去 gsap·motion 弹簧·reduced-motion） · data-display/collection · #animated

## 何时用

需要把一小撮图片/卡片扇形叠放、入场逐张弹入并支持 hover 推挤的展示位时用，多见于营销页 hero 区、相册预览。要自动循环洗牌的 3D 卡堆用 [CardSwap](https://hulianui.haloritual.com/components/card-swap)；要光标聚光揭示的卡片墙用 [ChromaGrid](https://hulianui.haloritual.com/components/chroma-grid)；要规整的多行数据用 [Table](https://hulianui.haloritual.com/components/table)。`images` 与 `children` 互斥，传 `children` 时优先用自定义卡片内容。

## 导入
```ts
import { BounceCards } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| images | `string[]` | — | 卡片图片地址数组，按下标对应 `transformStyles`；与 `children` 互斥 |
| containerWidth | `number` | `400` | 容器宽度（px） |
| containerHeight | `number` | `400` | 容器高度（px） |
| animationDelay | `number` | `0.5` | 入场起始延迟（秒），卡片从 scale 0 弹入前的整体等待 |
| animationStagger | `number` | `0.06` | 入场逐张错峰间隔（秒），越大时间差越明显 |
| transformStyles | `string[]` | 五张牌的旋转+横移 | 每张卡片扇形铺开的 transform，按下标对齐；超出数组的卡片回退无变换。例 `'rotate(10deg) translate(-170px)'` |
| enableHover | `boolean` | `true` | 是否开启 hover 推挤（悬停某张时它回正、两侧向外让位） |
| pushDistance | `number` | `160` | hover 时两侧卡片向外让位的横向位移（px） |
| className | `string` | — | 透传根容器类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode[]` | 自定义卡片内容数组，覆盖 `images` 的 `<img>` 渲染；数量决定卡片张数，与 `transformStyles` 按下标对齐 |

## 示例
```tsx
<BounceCards containerWidth={460} containerHeight={240}>
  {[
    <Swatch key="1" label="01" />,
    <Swatch key="2" label="02" />,
    <Swatch key="3" label="03" />,
  ]}
</BounceCards>
```

三张 + 自定义扇形角度、关闭 hover：
```tsx
<BounceCards
  enableHover={false}
  transformStyles={[
    "rotate(8deg) translate(-110px)",
    "rotate(-2deg)",
    "rotate(-8deg) translate(110px)",
  ]}
>
  {cards}
</BounceCards>
```

## 禁忌 / 坑

- `images` 与 `children` 互斥，同时给以 `children` 为准；卡片张数由实际使用的那一组数组长度决定。
- `transformStyles` 按下标对齐卡片，长度不足时多出的卡片无 transform 会全叠在原点，自定义张数时要补齐对应的扇形 transform。
- `animationDelay` / `animationStagger` 单位是**秒**不是毫秒，别误填 500。
- reduced-motion 下跳过弹跳入场直接显示，属预期降级。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Card

> 卡片 · Header/Body/Footer 插槽 · data-display/collection

## 何时用

把一组相关内容圈进带边框/阴影的容器——信息块、统计项、表单分区、列表卡片。需要条目流用 [List](https://hulianui.haloritual.com/components/list)(其 `grid` 态本身就是卡片栅格)；展示键值对详情用 [Descriptions](https://hulianui.haloritual.com/components/descriptions)。本组件只是纯容器外壳 + 三段插槽，不含业务逻辑。

## 导入
```ts
import { Card, CardHeader, CardBody, CardFooter } from "@hulianui/ui"
```

## Props

`CardProps` 继承原生 `HTMLAttributes<HTMLDivElement>`，外加 CVA 变体：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"outline" \| "elevated" \| "featured"` | `"outline"` | 外观：描边 / 投影抬升 / 强调 |

`CardHeader` / `CardBody` / `CardFooter` 均为插槽容器，接收原生 div 属性 + `children`。

## 示例
```tsx
<Card variant="elevated" className="w-64">
  <CardHeader>瑚琏卡片</CardHeader>
  <CardBody>宗庙玉器，至美又大用。</CardBody>
  <CardFooter>footer 区</CardFooter>
</Card>
```

## 禁忌 / 坑

- 别用 Card 包 loading 骨架屏——参见 [[loading-skeletons-are-chromeless-dont-wrap-in-card]]：骨架按惯例是无边框无阴影的纯 shimmer 块，套 Card 会显得过重。
- 列表/侧栏里 Card 末行(时间戳/meta 行)若设了外层 `min-height` 又用 flex 撑高，meta 行可能漏到卡片背景外——参见 [[grid-card-button-tail-row-leaks-outside-when-outer-min-height]]。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# CardSwap

> 3D 透视卡片自动洗牌组件 · 最前卡下坠 → 其余递进 → 绕回队尾循环 + 复合 CardSwap.Card 默认皮肤（去 gsap·motion useAnimate·reduced-motion） · data-display/collection · #animated

## 何时用

需要一摞 3D 透视卡片自动循环轮播（最前卡下坠、其余递进、回到队尾）的展示位时用，多见于营销页贴边构图（`placement="bottom-right"`）或画廊居中展示（`placement="center"`）。要扇形铺开+入场弹跳的静态叠卡用 [BounceCards](https://hulianui.haloritual.com/components/bounce-cards)；要光标聚光揭示的卡片墙用 [ChromaGrid](https://hulianui.haloritual.com/components/chroma-grid)。子项用 `<CardSwap.Card>` 自带默认皮肤，也可塞任意元素；至少 2 张才轮换。

## 导入
```ts
import { CardSwap } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number` | `380` | 单张卡片宽度（px），整体以右下角为锚点 |
| height | `number` | `280` | 单张卡片高度（px） |
| cardDistance | `number` | `56` | 相邻卡片水平+纵深（X/Z）错位距离（px），越大越散 |
| verticalDistance | `number` | `64` | 相邻卡片垂直（Y）错位距离（px），台阶高度 |
| delay | `number` | `5000` | 自动轮换间隔（ms） |
| pauseOnHover | `boolean` | `false` | 鼠标悬停是否暂停轮换 |
| skewAmount | `number` | `5` | 卡片倾斜角（deg, skewY）制造纵深；`0` 即正视 |
| easing | `"elastic" \| "smooth"` | `"elastic"` | 缓动风格；`smooth` 顺滑无回弹更克制 |
| placement | `"bottom-right" \| "center"` | `"bottom-right"` | 堆叠定位；`bottom-right` 右下锚定外溢（贴边营销），`center` 整摞居中完整可见（画廊/普通容器） |
| className | `string` | — | 透传根容器类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCardClick | `(index: number) => void` | 点击某卡回调，参数为该卡在 children 中的原始索引 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 堆叠卡片内容，建议用 `<CardSwap.Card>`；至少 2 张才轮换 |

## 示例
```tsx
<div className="relative h-96 overflow-hidden rounded-xl">
  <CardSwap width={300} height={200} delay={3000} placement="center" pauseOnHover>
    <CardSwap.Card>
      <p className="text-sm font-semibold">实时同步</p>
      <p className="mt-2 text-xs">毫秒级状态推送，跨端一致。</p>
    </CardSwap.Card>
    <CardSwap.Card>...</CardSwap.Card>
    <CardSwap.Card>...</CardSwap.Card>
  </CardSwap>
</div>
```

顺滑缓动 + 企业克制节奏：
```tsx
<CardSwap easing="smooth" skewAmount={4} placement="center" delay={2600}>
  {cards}
</CardSwap>
```

## 禁忌 / 坑

- 默认 `placement="bottom-right"` 会向外溢出 5%/18% 贴边，普通/画廊容器里整摞看不全，请改 `placement="center"`（showcase 全用 center）。
- 至少 2 张子卡片才会轮换，单张静止。
- `delay` 单位是毫秒；根容器需要 `relative + overflow-hidden` 承托透视堆叠。
- reduced-motion 下停止自动轮换，属预期降级。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Carousel

> 轮播 · 自研零依赖 scroll-snap + 箭头/圆点/autoplay/loop + 拖拽/键盘(reduced-motion) · data-display/collection

## 何时用

水平翻播一组等宽幻灯片——首页营销 Banner、图集、特性轮播。每个顶层 child 渲染为一张占满视口的卡片。静态多卡片栅格用 [Card](https://hulianui.haloritual.com/components/card)/[List](https://hulianui.haloritual.com/components/list) `grid`；本组件专攻"一次只看一张、可翻页/自动播放"的场景，自带 scroll-snap、拖拽、键盘与 reduced-motion 兼容。

## 导入
```ts
import { Carousel } from "@hulianui/ui"
```

## Props

`CarouselProps` 继承原生 div 属性(omit `onSelect`/`children`)：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| current | `number` | — | 受控当前索引(传入即受控) |
| defaultCurrent | `number` | `0` | 非受控初始索引 |
| autoplay | `boolean` | `false` | 自动播放(reduced-motion 下强制关闭) |
| autoplayInterval | `number` | `4000` | 自动播放间隔(毫秒) |
| loop | `boolean` | `false` | 循环：末尾再下一张回到首张 |
| showArrows | `boolean` | `true` | 显示左右切换箭头 |
| showDots | `boolean` | `true` | 显示圆点指示器 |
| aria-label | `string` | `"轮播"` | region 无障碍标签 |
| slideClassName | `string` | — | 每张幻灯片容器的额外类名(如固定高度/圆角) |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(index: number) => void` | 选中变化回调(箭头/圆点/键盘/autoplay/拖拽停靠均触发) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 幻灯片内容(每个顶层 child 一张) |

## 示例
```tsx
// 营销 Banner（箭头 + 圆点 / 可拖拽 / ←→ 键盘）
<Carousel className="w-96" aria-label="首页促销 Banner">
  {slides.map((s) => <Slide key={s.title} {...s} />)}
</Carousel>

// 自动播放 + 循环
<Carousel autoplay loop>
  {slides.map((s) => <Slide key={s.title} {...s} />)}
</Carousel>
```

## 禁忌 / 坑

- 受控/非受控对称：传 `current` 即受控(须配 `onSelect` 回写)，否则用 `defaultCurrent`。
- `autoplay` 在 `prefers-reduced-motion` 下被强制关闭——无障碍/测试环境别依赖它自动翻页。
- 每张幻灯片占满视口宽度，给幻灯片固定高度走 `slideClassName` 而非内层 div，否则各张高度不一致会抖动。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Chart

> 图表 · recharts 直裹 + chart token 皮肤(Area/Bar) · data-display/stat

## 何时用

仪表盘里画趋势/分布/对比图（面积、柱、线、饼、环、雷达、径向），自动套瑚琏 chart token 配色。要展示单个 KPI 数字用 [Stat](https://hulianui.haloritual.com/components/stat)/[Statistic](https://hulianui.haloritual.com/components/statistic)；要轻量内联趋势走 [Sparkline]；本组件是完整的多序列坐标图，基于 recharts。

## 导入
```ts
import { AreaChart, BarChart, LineChart, PieChart, RadarChart, RadialChart, chartColor } from "@hulianui/ui"
```

## Props

### AreaChart / BarChart / LineChart / RadarChart（笛卡尔类）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data* | `TDatum[]` | — | 行数据数组 |
| series* | `ChartSeries[]` | — | 序列定义 `{ key, label?, color? }`；color 缺省按 index 取 `var(--color-chart-N)`，可传语义色名/CSS 颜色覆盖 |
| xKey* | `string` | — | 横轴字段名 |
| height | `number` | `280` | 高度（SSR 安全：宽走 ResponsiveContainer，高需显式值） |
| stacked | `boolean` | `false` | 多序列堆叠（Area/Bar 生效） |
| horizontal | `boolean` | `false` | **BarChart 专属**：横向柱状 |
| className | `string` | — | 透传类名（宽度在此设，如 `w-[32rem]`） |

### PieChart / RadialChart（扁平数据类）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data* | `ChartDatum[]` | — | 扁平数据点 `{ name, value, color? }` |
| donut | `boolean` | `false` | **PieChart**：环形图（中心挖空） |
| height | `number` | `280` | 高度 |
| className | `string` | — | 透传类名 |

## 示例
```tsx
// 多序列面积图（颜色自动取 chart token）
const data = [{ month: "1月", revenue: 42, orders: 168 }, { month: "2月", revenue: 55, orders: 142 }];
<AreaChart data={data} series={[{ key: "revenue", label: "营收" }, { key: "orders", label: "订单" }]} xKey="month" className="w-[32rem]" />

// 环形图
<PieChart donut data={[{ name: "搜索", value: 420 }, { name: "直接", value: 280 }]} className="w-[32rem]" />
```

## 禁忌 / 坑
- 宽度交给父容器 / className，**高度必须显式**（`height` 默认 280）——宽走 ResponsiveContainer 但高拿不到会塌成 0。
- 在收缩的 flex 容器里 ResponsiveContainer 可能量不到宽，需给容器显式宽度，见 [[recharts-responsive-container-needs-explicit-width-in-shrink-flex]]。
- headless 截图常出现「只剩坐标轴、数据区空白」——不是 bug，是入场动画的 clipPath 被 rAF 饿死，设 `prefers-reduced-motion: reduce` 再截即显，见 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Statistic](https://hulianui.haloritual.com/components/statistic) · [Meter](https://hulianui.haloritual.com/components/meter) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# Chip

> 标签 · 可移除(onClose×) + dot + tone×variant(区别 Badge 计数) · data-display/info

## 何时用

展示一个分类/筛选/选中标签，常带可移除（×）、前导点、头像或图标。它表达「一个带文字的标签实体且可被移除」；要叠加到宿主四角的未读计数/红点用 [Badge](https://hulianui.haloritual.com/components/badge)；只要一个纯状态圆点用 [Dot](https://hulianui.haloritual.com/components/dot)。

## 导入
```ts
import { Chip, chipVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"solid"｜"soft"｜"outline"` | `soft` | 视觉风格。 |
| tone | `"brand"｜"danger"｜"neutral"` | `brand` | 语气色。 |
| size | `"sm"｜"md"` | `md` | 尺寸。 |
| dot | `boolean` | — | 前导小圆点（状态指示）。 |
| isDisabled | `boolean` | — | 禁用：降透明度、屏蔽指针事件、关闭按钮不可点。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClose | `() => void` | 提供则渲染关闭(×)按钮并触发回调（区别于 Badge：Chip 可移除）。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| avatar | `ReactNode` | 前导头像（贴左边缘，按 size 约束为正方形）。 |
| startContent | `ReactNode` | 起始内容槽（图标等），avatar 存在时不渲染。 |
| endContent | `ReactNode` | 结尾内容槽，位于 children 之后、关闭按钮之前。 |
| children | `ReactNode` | 标签文字。 |

## 示例
```tsx
// soft 三色
<Chip tone="brand">品牌</Chip>
<Chip tone="danger">危险</Chip>

// 可移除标签组
{items.map((t) => (
  <Chip key={t} onClose={() => remove(t)}>{t}</Chip>
))}
```

## 禁忌 / 坑

暂无已知坑。前导内容互斥优先级为 `avatar > startContent > dot`——三者同传只渲染 avatar。要出现 × 关闭按钮必须传 `onClose`（即便回调为空函数）。`isDisabled` 会屏蔽整片指针事件，连 × 也点不动。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# ChromaGrid

> 光标聚光揭示的卡片墙 · 整片灰度暗化、光标圈内透出全彩 + 单卡 hover 径向高光（弹性跟随·reduced-motion） · data-display/collection · #animated

## 何时用

需要一面卡片墙、整体灰度暗化、靠光标聚光圈在指针附近透出全彩的展示位时用，多见于团队/成员墙、作品集封面墙。要 3D 自动洗牌的卡堆用 [CardSwap](https://hulianui.haloritual.com/components/card-swap)；要扇形铺开+入场弹跳用 [BounceCards](https://hulianui.haloritual.com/components/bounce-cards)；要规整数据表格用 [Table](https://hulianui.haloritual.com/components/table)。卡片色彩通过每项 `borderColor` / `gradient` 喂 chart token 定制。

## 导入
```ts
import { ChromaGrid } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `ChromaGridItem[]` | 内置占位 demo | 卡片数据数组，缺省回退占位便于空状态预览 |
| radius | `number` | `300` | 聚光揭示半径（px），此半径内全彩、外侧渐隐为灰度 |
| columns | `number` | `3` | 栅格列数（桌面端），窄屏自动回落单列 |
| damping | `number` | `0.45` | 光标跟随阻尼（0~1，越大越黏/越慢）；reduced-motion 下忽略直接吸附 |
| fadeOut | `number` | `0.6` | 光标移出后灰度遮罩恢复全覆盖的淡出秒数 |
| className | `string` | — | 透传根容器类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

`ChromaGridItem`：`{ image?; title?; subtitle?; handle?; location?; borderColor?; gradient?; url?; children? }`。`borderColor` / `gradient` 建议喂 `var(--color-chart-1)`~`var(--color-chart-5)`；`url` 提供时卡片可点击（新标签打开）；`children` 覆盖默认 image+文字布局。

## 示例
```tsx
<ChromaGrid
  columns={2}
  radius={260}
  items={[
    {
      title: "林屿",
      subtitle: "全栈工程师",
      handle: "@linyu",
      borderColor: "var(--color-chart-1)",
      gradient: "linear-gradient(145deg, var(--color-chart-1), transparent)",
    },
    {
      title: "陈墨",
      subtitle: "DevOps 工程师",
      handle: "@chenmo",
      borderColor: "var(--color-chart-2)",
      gradient: "linear-gradient(210deg, var(--color-chart-2), transparent)",
    },
  ]}
/>
```

不传 items 时用内置占位卡预览：
```tsx
<ChromaGrid columns={3} />
```

## 禁忌 / 坑

- 卡片色彩 token 必须带 `--color-` 前缀（如 `var(--color-chart-1)`）；裸 `var(--chart-1)` 在渐变/描边里不解析。
- 揭示效果靠灰度对比，深色底容器观感最佳（showcase 用 `oklch(0.16 0.02 255)`）。
- reduced-motion 下光标弹性跟随退化为直接吸附，属预期。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# CircularGallery

> ogl 弧形图片画廊 · 卡片沿圆弧弯曲倾斜排开 + 滚轮/拖拽惯性平移首尾无缝循环(ogl·圆角SDF·token化标题·reduced-motion 降级静态轨道) · data-display/collection · #animated

## 何时用

需要一条 WebGL 弧形图片轨道、滚轮/拖拽惯性平移且首尾无缝循环的画廊时用，多见于作品集横向浏览、品牌矩阵展示。要球面 3D 图库（拖拽旋转半球内壁）用 [DomeGallery](https://hulianui.haloritual.com/components/dome-gallery)；要光标聚光揭示的卡片墙用 [ChromaGrid](https://hulianui.haloritual.com/components/chroma-grid)；要规整数据表格用 [Table](https://hulianui.haloritual.com/components/table)。基于 ogl，是客户端组件，缺图时用 chart token 程序化生成离线占位图。

## 导入
```ts
import { CircularGallery } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `CircularGalleryItem[]` | 内置占位卡 | 画廊条目数组（图片+标题），不传/空数组用 chart token 程序化渐变占位（无远程资源） |
| bend | `number` | `3` | 弧形弯曲强度；`0`=平直，正值向下凹、负值向上凸，建议 -6~6 |
| textColor | `string` | `var(--color-foreground)` | 标题文字颜色，接受任意 CSS 颜色或 `var(--color-*)` token（运行时解析为实色喂 canvas） |
| borderRadius | `number` | `0.05` | 卡片圆角（归一化 0–0.5），`0`=直角，`0.5`=胶囊/圆 |
| scrollSpeed | `number` | `2` | 滚动/拖拽灵敏度，越大单次跨度越大 |
| scrollEase | `number` | `0.05` | 惯性 lerp 系数（0–1），越小越"重"越顺滑 |
| font | `string` | `bold 30px ui-sans-serif, system-ui, sans-serif` | 标题字体（canvas font 简写）；默认用系统字体栈，离线/RSC 安全 |
| className | `string` | — | 透传根容器类名 |

`CircularGalleryItem`：`{ image?; text }`，`image` 留空则用 chart token 程序化渐变占位图。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `React.ReactNode` | reduced-motion / 无 WebGL 时的降级槽位（渲染在静态占位层之上） |

## 示例
```tsx
<div className="relative h-72 overflow-hidden rounded-xl">
  <CircularGallery
    items={[
      { text: "瀚枢" },
      { text: "瀚舵" },
      { text: "瀚舰" },
      { text: "瀚付" },
    ]}
  />
</div>
```

平直排列 + 自定义标题色：
```tsx
<CircularGallery bend={0} textColor="var(--color-chart-2)" items={items} />
```

## 禁忌 / 坑

- 基于 ogl 的 WebGL 组件，是客户端组件，需放进有明确高度 + `overflow-hidden` 的承托容器；在 SSR/RSC 下注意只在客户端渲染。
- `textColor` 喂主题色用 `var(--color-*)` 前缀 token，组件会运行时解析为实色再喂 canvas；裸 token 在 canvas 取色处不解析。
- reduced-motion / 无 WebGL 时降级为静态轨道（配合 `fallback` 槽位），属预期。
- headless 截图可能因 WebGL/动画首帧未驱动而偏空白，验视觉需真实浏览器或先暖帧。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# CodeReviewThread

> 代码审查评论线程 · severity 左边色条(四级语气) + AI/人类作者 + 内嵌建议修改 diff 可采纳 + 回复/标记已解决·误报 + 折叠 · 嵌 code-diff annotations 槽或独立用·复用 Avatar/Tag/CodeDiff · data-display/collection

## 何时用

渲染一条围绕某段代码的审查讨论（AI/人类多轮评论 + 严重度 + 内嵌建议 diff + 解决/误报状态）时用。它是「一个话题的整条线程」；要展示纯代码增删行差异用 [CodeDiff]，要做通用富文本评论列表（无 severity/采纳建议语义）则自行用 Avatar + 列表组合。

## 导入
```ts
import { CodeReviewThread, severityStyle, SEVERITY } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| comments* | `ReviewComment[]` | — | 线程内评论数组（含作者 kind、severity、body、可选 suggestion）。 |
| status | `"open"｜"resolved"｜"wontfix"` | `open`（内部自管） | 线程状态；受控，传则由外部托管。 |
| replyable | `boolean` | `true` | 是否显示回复框。 |
| defaultCollapsed | `boolean` | `false` | 非受控初始折叠态。 |
| collapsed | `boolean` | — | 受控折叠（优先于 defaultCollapsed）。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onStatusChange | `(s: ReviewThreadStatus) => void` | 状态变更回调（status 受控时回写）。 |
| onReply | `(text: string) => void` | 提交回复回调。 |
| onAdoptSuggestion | `(commentId: string) => void` | 采纳某条建议修改回调。 |
| onCollapsedChange | `(v: boolean) => void` | 折叠态变更回调（collapsed 受控时回写）。 |

## 示例
```tsx
const comments = [
  {
    id: "c1",
    author: { name: "AI 审查官", kind: "ai" },
    severity: "critical",
    body: "未对 user 可能为 null 的情况做防御，登出态会崩溃。",
    time: "刚刚",
    suggestion: {
      oldText: "const name = user.profile.name;",
      newText: 'const name = user?.profile?.name ?? "";',
    },
  },
];

<CodeReviewThread comments={comments} />
```

已解决态：
```tsx
<CodeReviewThread comments={comments} status="resolved" />
```

## 禁忌 / 坑

暂无已知坑。`status` 与 `collapsed` 均为「传则受控、不传则内部自管」：受控时必须配 `onStatusChange` / `onCollapsedChange` 回写，否则交互无效。`collapsed` 优先级高于 `defaultCollapsed`，两者勿同时当真值传。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Comment

> 评论 · 嵌套回复缩进 + 可选连接线 + 操作区 + comment/log 类型(复用 Avatar/Link·RSC) · data-display/info

## 何时用

讨论线程 / 工单评论 / 系统操作日志的混排（嵌套回复缩进 + 操作区）。`type="comment"` 渲气泡正文，`type="log"` 渲弱化单行日志。作者区可直接塞 [[User](https://hulianui.haloritual.com/components/user)]；纯时间戳用 RelativeTime。

## 导入
```ts
import { Comment, CommentActions, CommentAction, commentActionVariants } from "@hulianui/ui"
```

## Props

### Comment

**Props**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| avatar | `AvatarProps` | — | 透传瑚琏 Avatar（src/alt/fallback/size）；type=log 时忽略，改渲系统点标记。 |
| type | `"comment" \| "log"` | `"comment"` | 评论类型。 |
| connector | `boolean` | `false` | 子评论区是否画左侧连接线（默认仅缩进）。 |
| className | `string` | — | 其余 `HTMLAttributes<HTMLElement>`（已 Omit `content`/`title`）。 |

**Slots**

| 插槽 | 类型 | 说明 |
|------|------|------|
| author* | `ReactNode` | 作者名（必填）；可传 User 组合件。 |
| datetime | `ReactNode` | 时间戳（相对/绝对皆可）。 |
| content | `ReactNode` | 正文：comment 渲为下方段落；log 内联在作者后。 |
| actions | `ReactNode` | 操作区（点赞/回复等），建议用 CommentAction 组合。 |
| children | `ReactNode` | 嵌套子评论（递归 Comment）；自动缩进 + 可选左侧连接线。 |

### CommentAction

**Props**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| href | `string` | — | 传则渲为瑚琏 Link（链接型操作，如「回复」跳锚点）；否则 `<button>`。 |

**Slots**

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 操作内容；其余透传 button 属性。 |

## 示例
```tsx
const actions = (
  <>
    <CommentAction>👍 赞 12</CommentAction>
    <CommentAction href="#reply">回复</CommentAction>
  </>
)
<Comment author="瑚琏" datetime="2 小时前" avatar={{ fallback: "瑚" }} content="工单已分配，请跟进。" actions={actions} connector>
  <Comment author="李四" datetime="1 小时前" avatar={{ fallback: "李" }} content="收到，正在排查。" />
</Comment>
```
```tsx
// 系统日志混排
<Comment type="log" author="系统" content="将工单状态改为「处理中」" datetime="昨天 14:25" />
```

## 禁忌 / 坑

- `type="log"` 会忽略 `avatar`（改渲系统点标记）、`content` 内联在作者后；想要头像气泡正文用默认 `comment`。
- 嵌套靠 `children` 放子 `Comment` 递归实现，缩进自动；`connector` 连接线默认关，需显式开。
- `CommentAction` 有无 `href` 决定渲染成 Link 还是 button，跳锚点回复传 href，纯交互（点赞）不传。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Coupon

> 优惠券 · 撕票造型(中缝虚线+上下半圆穿孔·纯CSS) + 满减/折扣/包邮三类 + 可领/已领/已用/过期四态 + 选券高亮(电商标配·只消费 token) · data-display/info

## 何时用

电商/营销场景展示一张优惠券（满减/折扣/包邮），含领取、去用、结算选券等动作。需要纯文本状态徽记用 [[Badge]] 或 Tag，本组件是带面额区与操作区的完整票据卡片。

## 导入
```ts
import { Coupon } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| kind | `"amount" \| "discount" \| "shipping"` | `"amount"` | 券类型：满减额 / 折扣 / 包邮，决定左侧面额区主视觉。 |
| amount | `number` | — | 面额（满减额，单位元）。kind=amount 时显示 ¥{amount}。 |
| discount | `number` | — | 折扣（如 8.5 显示 8.5 折）。kind=discount 时使用。 |
| threshold | `number` | — | 使用门槛（满 X 元可用）。0 / 省略 = 无门槛。 |
| status | `"available" \| "claimed" \| "used" \| "expired"` | `"available"` | 券状态，驱动操作区文案与置灰。 |
| tone | `"brand" \| "danger" \| "neutral"` | `"brand"` | 配色。 |
| size | `"sm" \| "md"` | `"md"` | 尺寸。 |
| shine | `boolean` | `false` | 面额区周期性扫光引导领取；建议仅对 available 券开启，已用/过期券自动不播。 |
| selected | `boolean` | — | 选中态（结算页选券高亮 ring）。 |
| actionLabel | `string` | — | 覆盖操作区按钮文案。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClaim | `() => void` | 领取回调（status=available 时操作按钮触发）。 |
| onUse | `() => void` | 使用 / 去凑单回调（status=claimed 时操作按钮触发）。 |
| onSelect | `() => void` | 整券可点（结算选券），点击触发；与右侧按钮独立。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 券标题（如「全场通用券」）。 |
| scope | `ReactNode` | 适用范围 / 副说明（如「仅限数码品类」）。 |
| validUntil | `ReactNode` | 有效期文案（如「2026.06.30 前有效」）。 |

## 示例
```tsx
// 三类券
<Coupon kind="amount" amount={50} threshold={299} title="全场通用满减券" scope="支持全部品类" validUntil="2026.06.30 前有效" onClaim={() => {}} />
<Coupon kind="discount" discount={8.5} threshold={199} tone="danger" title="数码专享折扣券" scope="仅限数码 3C" onClaim={() => {}} />
<Coupon kind="shipping" tone="neutral" title="全国包邮券" scope="偏远地区除外" onClaim={() => {}} />
```
```tsx
// 结算选券（受控高亮）
<Coupon kind="amount" amount={30} threshold={199} title="结算选券" status="claimed" selected onSelect={() => {}} />
```

## 禁忌 / 坑

- `status="used" | "expired"` 时操作区自动置灰、`shine` 扫光不播；不必额外手动禁用。
- 撕票穿孔/中缝是纯 CSS 伪元素绘制，外层不要再裹会裁剪溢出的 `overflow-hidden` 容器，否则半圆穿孔被切。
- `onClaim`/`onUse`/`onSelect` 三类回调对应不同 status 与点击区，互相独立——结算选券走 `onSelect`（整券），领取走 `onClaim`（右侧按钮）。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# CreditCard

> 银行卡展示 · 卡号前缀识别品牌(visa/mastercard/amex/银联/jcb/discover) + 分组格式化/打码(纯函数可测) + token 渐变卡面 + 芯片/品牌字标 + 正反面(磁条/CVC) · 结算确认/钱包(纯展示·RSC) · data-display/info

## 何时用

在结算确认、钱包、绑卡管理处展示一张银行卡卡面（品牌识别 + 卡号打码 + 正反面）。纯展示组件，不做表单录入；要采集卡号请用表单输入控件，本组件只负责把已有卡信息可视化成一张卡。

## 导入
```ts
import { CreditCard, detectBrand, formatCardNumber, maskCardNumber } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| number* | `string` | — | 卡号，可含空格，内部归一；空串渲染占位卡 |
| holder | `string` | — | 持卡人姓名 |
| expiry | `string` | — | 有效期 MM/YY |
| brand | `"visa" \| "mastercard" \| "amex" \| "unionpay" \| "discover" \| "jcb" \| "unknown"` | 自动识别 | 强制品牌；省略则由卡号前缀自动识别 |
| masked | `boolean` | `true` | 仅显示后 4 位，其余打码 |
| flipped | `boolean` | `false` | 翻到背面（磁条 + CVC） |
| cvc | `string` | — | 背面 CVC |
| className | `string` | — | 透传类名 |

## 示例
```tsx
// 品牌按卡号前缀自动识别 + 默认打码
<CreditCard number="4111111111111111" holder="ZHANG SAN" expiry="12/28" />

// 受控翻面查看背面 CVC
const [flipped, setFlipped] = useState(false);
<CreditCard number="5500005555555559" holder="LI LEI" expiry="08/27" cvc="321" flipped={flipped} />
```

## 禁忌 / 坑
暂无已知坑。`detectBrand` / `formatCardNumber` / `maskCardNumber` 是导出的纯函数，可在卡面外独立复用与单测。`flipped` 是受控 prop，需自行管理翻面状态。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Danmaku

> 弹幕引擎 · 轨道分配防重叠(等速模型·第二条入场后发车永不追尾) · scroll 滚动/top 顶部/bottom 底部三模式 + 轨道数/速度/密度(low/normal/high)/占屏比/透明度/暂停 + pointer-events none 穿透到底层视频 · 几何抽纯函数(allocateTrack/scrollDuration/estimateWidth)带单测 · 直播旗舰 · data-display/collection · #animated

## 何时用

直播/视频画面上覆盖飘动弹幕。绝对定位铺满父容器且 pointer-events 穿透，配合 [LivePlayer](https://hulianui.haloritual.com/components/live-player) 的 `overlay` 插槽使用。要弹幕就用本组件；要消息列表/公屏滚动用 [LiveChat](https://hulianui.haloritual.com/components/live-chat)。

## 导入
```ts
import { Danmaku, allocateTrack, densityGap, estimateWidth, leastBusyTrack, scrollDuration, trackFreeTime } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `DanmakuItem[]` | — | 受控弹幕流，只增不改既有项；新增项自动入场（内部按 `item.id` 去重，仅对未上屏的入场） |
| tracks | `number` | `4` | 滚动轨道数 |
| speed | `number` | `100` | 滚动速度 px/s |
| density | `"low" \| "normal" \| "high"` | `"normal"` | 密度：决定轨道安全间隙 + 无空闲轨道时是否强挤 |
| area | `number` | `1` | 弹幕占用容器高度比 0–1，1=满屏 |
| opacity | `number` | `1` | 整体不透明度 |
| paused | `boolean` | `false` | 暂停所有动画 |
| className | `string` | — | 容器自定义类 |

`DanmakuItem`：`{ id: string; text: ReactNode; mode?: "scroll"｜"top"｜"bottom"; color?: string; size?: "sm"｜"md"｜"lg"; bold?: boolean }`。`mode` 默认 `scroll`，`size` 默认 `md`，`color` 默认继承前景 token。

## 示例
```tsx
<div className="relative aspect-video">
  <video src="/stream.mp4" muted autoPlay loop className="absolute inset-0 h-full w-full" />
  <Danmaku items={items} tracks={4} speed={100} density="normal" />
</div>
```

`items` 为受控数组，只追加不修改既有项即可让新弹幕入场：
```tsx
setItems((p) => [...p.slice(-60), { id: `d${i}`, text: "前排围观", mode: "scroll" }]);
```

## 禁忌 / 坑

- `items` 是只增受控流：组件内部记录已上屏 id，**只对「新增且未上屏」的项入场**。改写既有项不会重新触发动画；要让同一条再飞一次须换新 `id`。
- 长直播务必裁剪 `items`（如 `slice(-60)`），否则数组无限膨胀；组件只对新项做动画，旧项留在数组不影响渲染但占内存。
- 组件铺满父容器且 `pointer-events: none` 穿透，父容器需 `position: relative` + `overflow: hidden`。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# DecayCard

> 鼠标驱动的「湍流溶解」图片卡 · SVG feTurbulence+feDisplacementMap 随鼠标速度融化图像 + 带阻尼的视差倾斜平移（零依赖去 gsap·RAF 缓动·reduced-motion） · data-display/collection · #animated

## 何时用

要一张图片卡随鼠标快速划过"融化/溶解"的高表现力视觉（艺术化封面、hero 单图）时用。本组件聚焦**单张图片的湍流溶解 + 视差平移**；要悬停指针 3D 倾斜的通用卡用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)，要像素波纹背景卡用 [PixelCard](https://hulianui.haloritual.com/components/pixel-card)。

## 导入
```ts
import { DecayCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number` | `300` | 卡片宽度（px） |
| height | `number` | `400` | 卡片高度（px） |
| image | `string` | 灰度占位图 | 卡片主图地址，鼠标快速划过时被湍流位移溶解；生产请替换为业务图 |
| alt | `string` | `""` | 图片 alt 文本（默认空，按纯装饰图） |
| baseFrequency | `number` | `0.015` | feTurbulence 基础频率，越大噪声越密、溶解颗粒越细，建议 0.005–0.05 |
| numOctaves | `number` | `5` | feTurbulence 倍频层数，越多细节越丰富也越耗 |
| seed | `number` | `4` | 湍流随机种子，换数字即换一套溶解纹理 |
| maxDisplacement | `number` | `400` | 位移上限（feDisplacementMap scale 峰值），鼠标越快溶解越剧烈 |
| movementBound | `number` | `50` | 卡片随鼠标平移软边界（px），超出后按 0.2 系数推进形成弹性阻尼手感 |
| className | `string` | — | 透传到根容器的额外 className |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在卡底的文字内容，层叠在图片之上、不受溶解影响 |

## 示例
```tsx
<DecayCard image="/cover.jpg" alt="封面">
  瑚琏
  <br />
  溶解卡片
</DecayCard>

// 细颗粒溶解（高频 + 多倍频）
<DecayCard image="/cover.jpg" baseFrequency={0.04} numOctaves={6} seed={11}>
  细噪
</DecayCard>
```

## 禁忌 / 坑

- 溶解只在**鼠标快速划过**时明显（按鼠标速度驱动 displacement），静止/触屏几乎无溶解，不要依赖它表达关键信息。
- `numOctaves` / 大 `maxDisplacement` 越高，SVG 滤镜每帧重算越耗，低端设备易掉帧；按需调低。
- 默认 `image` 是占位灰度图，生产务必替换；`alt` 默认空（装饰图），若图片承载信息须显式传 `alt`。
- SVG `feTurbulence`/`feDisplacementMap` 滤镜，零依赖；reduced-motion 下停溶解动画退化静态图。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# DeployStatus

> 部署/构建生命周期态 · 排队/构建中(转圈)/已上线/失败/已取消/已跳过 六态(→success/danger/primary/neutral 软填充) · badge 徽标/dot 圆点(building 脉冲)/icon 紧凑三形态 · 区别健康态 StatusDot 语义 · CI/CD/Pages/流水线刚需(纯CSS·RSC) · data-display/info

## 何时用

表达一次部署/构建的**生命周期阶段**（排队 → 构建中 → 上线/失败/取消/跳过）。与表达「在线/降级/离线」健康态的 StatusDot 区分：本组件是「这次构建走到哪一步」，StatusDot 是「服务此刻是否健康」。CI/CD、Pages、流水线列表用本组件。

## 导入
```ts
import { DeployStatus } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| status* | `"queued" \| "building" \| "ready" \| "error" \| "canceled" \| "skipped"` | — | 生命周期状态 |
| variant | `"badge" \| "dot" \| "icon"` | `"badge"` | 形态：badge 软填充徽标 / dot 圆点+文字 / icon 仅图标（紧凑表格单元格） |
| size | `"sm" \| "md"` | `"md"` | 尺寸 |
| spin | `boolean` | `true` | building 态图标是否旋转 |
| className | `string` | — | 透传类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 覆盖默认中文文案 |

## 示例
```tsx
// 默认徽标
<DeployStatus status="ready" />

// 圆点+文字（building 态自动脉冲）/ 紧凑表格单元格仅图标
<DeployStatus status="building" variant="dot" />
<DeployStatus status="error" variant="icon" size="sm" />
```

## 禁忌 / 坑
暂无已知坑。注意语义边界：本组件是部署生命周期态，不要拿它当服务健康指示灯（那是 StatusDot）。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Descriptions

> 描述列表 · 详情页键值对 + horizontal/vertical + bordered + span 跨列(纯皮肤·RSC) · data-display/collection

## 何时用

详情页/详情抽屉里展示一组只读键值对——用户资料、订单详情、合同信息。深层嵌套的 JSON 树用 [JsonViewer](https://hulianui.haloritual.com/components/json-viewer)；需要列表流/操作按钮用 [List](https://hulianui.haloritual.com/components/list)。本组件专攻"标准多列对齐的扁平字段表"，纯皮肤可在 RSC 直接渲染。

## 导入
```ts
import { Descriptions, DescriptionsItem } from "@hulianui/ui"
```

## Props

`DescriptionsProps`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| column | `number` | `3` | 每行列数 |
| layout | `"horizontal" \| "vertical"` | `"horizontal"` | horizontal=键左值右；vertical=键上值下 |
| bordered | `boolean` | `false` | 带边框分隔的表格态 |
| items | `DescriptionsItemData[]` | — | 数据驱动备选；提供时优先于 `DescriptionsItem` 子节点 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题(左上) |
| extra | `ReactNode` | 右上操作区 |

`DescriptionsItem` / `DescriptionsItemData`：`label`(键名，text-muted) / `children`(值，text-foreground) / `span`(跨列数，默认 1，超过 `column` 时钳制到 `column`)

## 示例
```tsx
// 子节点模式
<Descriptions title="用户信息">
  <DescriptionsItem label="姓名">张三</DescriptionsItem>
  <DescriptionsItem label="性别">男</DescriptionsItem>
  <DescriptionsItem label="备注" span={3}>VIP 客户，优先处理售后工单</DescriptionsItem>
</Descriptions>

// 数据驱动 + 边框表格态
<Descriptions
  bordered
  title="订单详情"
  extra={<a href="#edit">编辑</a>}
  items={[
    { label: "用户名", children: "zhangsan" },
    { label: "地址", children: "广东省广州市天河区某某路 88 号", span: 3 },
  ]}
/>
```

## 禁忌 / 坑

- `bordered` 表格态要求每行 `span` 之和恰好填满 `column`，否则会留空缺；用 `span` 让长字段(如地址、备注)整行占满。
- `items` 与 `DescriptionsItem` 子节点同时给时，`items` 优先(子节点被忽略)。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# DiffStat

> 改动统计条 · +N −M 绿红格子条按比例填充(纯函数 splitBlocks 可测) + A/M/D/R 状态徽标 · 代码审查/PR 列表刚需·零依赖·RSC · data-display/info

## 何时用

PR/提交列表里展示单文件改动量：`+N −M` 数字 + 绿红比例格子条 + 改动状态徽标。本组件是 git diff 统计的微件（零依赖、可 RSC）；要趋势折线用 [Sparkline](https://hulianui.haloritual.com/components/sparkline)，要文件改动状态角标的层级树用 [FileTree](https://hulianui.haloritual.com/components/file-tree)。

## 导入
```ts
import { DiffStat, splitBlocks } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| additions* | `number` | — | 新增行数 |
| deletions* | `number` | — | 删除行数 |
| status | `"added" \| "modified" \| "deleted" \| "renamed"` | — | 文件状态徽标（可选） |
| blocks | `number` | `5` | 绿红格子条总格数 |
| showCounts | `boolean` | `true` | 是否显示 +N −M 数字 |
| size | `"sm" \| "md"` | `"md"` | 尺寸 |
| className | `string` | — | 自定义类 |

## 示例
```tsx
<DiffStat additions={24} deletions={6} status="modified" />
<DiffStat additions={142} deletions={0} status="added" />
```

仅格子条（不显示数字）：
```tsx
<DiffStat additions={7} deletions={2} showCounts={false} size="sm" />
```

## 禁忌 / 坑

暂无已知坑。格子条按 `additions:deletions` 比例填充 `blocks` 格（纯函数 `splitBlocks`），二者全 0 时为空条。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# DocumentSheet

> 单据纸张 · A4 居中纸面(白底/暗色近黑纸·shadow·210mm 宽) + 打印态隔离(工具栏/阴影/外边距 print:hidden·data-document-sheet 钩子) + 内置打印按钮(onPrint ?? window.print) + 子件 Header(左右抬头)/Section(带小标题段)/Footer(签章位) · 报价单/发票等单据容器 · data-display/collection

## 何时用

需要一张「可打印的正式单据纸面」时用——报价单、发票、合同、对账单。屏幕上居中显示 A4 纸张，打印时自动隐藏工具栏/阴影/外边距。只展示结构化表格数据用 [Table]/[ProTable]；DocumentSheet 是纸张容器，配合内置子件组装抬头/明细段/签章。

## 导入
```ts
import { DocumentSheet, DocumentSheetHeader, DocumentSheetSection, DocumentSheetFooter, DocumentSheetSignature } from "@hulianui/ui"
```

## Props

DocumentSheet（继承 `HTMLAttributes<HTMLDivElement>`）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"a4" \| "auto"` | `"a4"` | a4 固定 210mm 宽纸面 / auto 自适应容器宽 |
| printable | `boolean` | `true` | 是否渲染内置打印按钮 |
| className | `string` | — | 纸面类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onPrint | `() => void` | 打印按钮回调，缺省走 `window.print()` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| toolbar | `ReactNode` | 纸面上方工具栏内容（挂 `print:hidden`，打印时消失） |
| children* | `ReactNode` | 纸面内容（通常由下列子件组装） |

DocumentSheetSection：`title?: ReactNode`（段小标题）+ children。
DocumentSheetSignature：`label?: ReactNode`（签章说明）+ `lineWidth?: number \| string`（签名线宽，默认 `"11rem"`）。
DocumentSheetHeader / DocumentSheetFooter：仅排版容器，透传 div 属性。

## 示例
```tsx
<DocumentSheet size="a4" className="text-sm">
  <DocumentSheetHeader>
    <div className="text-lg font-bold">瑚琏设计工作室</div>
    <div className="text-right text-xl font-bold">报 价 单</div>
  </DocumentSheetHeader>

  <DocumentSheetSection title="服务明细">
    <table className="w-full">{/* … 明细行 … */}</table>
  </DocumentSheetSection>

  <DocumentSheetFooter>
    <div className="flex items-end justify-between gap-8">
      <p className="text-xs">备注：报价有效期 30 天。</p>
      <DocumentSheetSignature label="授权代表（签章）" />
    </div>
  </DocumentSheetFooter>
</DocumentSheet>
```

## 禁忌 / 坑

- 打印态靠 `print:hidden` + `data-document-sheet` 钩子隔离工具栏/阴影/外边距；自己往纸面里加的悬浮控件若不希望被打印，也要自行挂 `print:hidden`。
- 暗色主题下纸面是「近黑纸」而非白纸——若放固定深色文字会看不清，正文颜色用 token（`text-foreground`/`text-muted`）跟随主题。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# DomeGallery

> 球面图库：图片瓦片贴在 CSS 3D 半球内壁，拖拽旋转浏览、点击放大查看 · 原生 PointerEvents 自搓拖拽+RAF 惯性 + motion 灯箱(零依赖·token·reduced-motion) · data-display/collection · #animated

## 何时用

需要把一组图片贴在 3D 半球内壁、拖拽旋转浏览并点击放大查看的沉浸式图库时用，多见于品牌氛围墙、作品集首屏。要弧形横向轨道（滚轮平移、无缝循环）用 [CircularGallery](https://hulianui.haloritual.com/components/circular-gallery)；要光标聚光揭示的卡片墙用 [ChromaGrid](https://hulianui.haloritual.com/components/chroma-grid)；要规整数据表格用 [Table](https://hulianui.haloritual.com/components/table)。纯 CSS 3D + 原生 PointerEvents，零外部依赖。

## 导入
```ts
import { DomeGallery } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| images | `DomeGalleryImage[]` | 内置占位渐变瓦片 | 贴球面的图片集合（字符串或 `{ src, alt }`）；数量不足循环铺满，超出尾部不显示 |
| segments | `number` | `24` | 球面经向分段数（横向密度），越大瓦片越密越小 |
| fit | `number` | `0.5` | 球半径相对容器尺寸比例，越小曲率越大越「贴脸」（受 min/maxRadius 钳制） |
| minRadius | `number` | `380` | 半径下限（px），防小容器球面塌缩 |
| maxRadius | `number` | `1600` | 半径上限（px），防大屏球面过平 |
| maxVerticalRotationDeg | `number` | `6` | 纵向（rotateX）最大摆动角，限制上下翻转避免看到球两极 |
| dragSensitivity | `number` | `18` | 拖拽灵敏度：像素位移 ÷ 该值 = 旋转角，越大越迟钝 |
| dragDampening | `number` | `0.55` | 松手后惯性阻尼（0~1），越大滑行越久 |
| grayscale | `boolean` | `true` | 瓦片是否灰度滤镜（放大后恢复彩色） |
| imageBorderRadius | `string` | `"16px"` | 瓦片圆角（CSS 长度） |
| openedImageBorderRadius | `string` | `"24px"` | 放大查看时图片圆角（CSS 长度） |
| overlayColor | `string` | `"var(--color-background)"` | 边缘渐隐/中心遮罩底色，传 token 以匹配容器背景 |
| enlargeTransitionMs | `number` | `320` | 放大查看/自动旋转过渡时长（ms） |
| autoRotate | `boolean` | `false` | 无拖拽时自动缓慢自转（展示/壁纸场景） |
| className | `string` | — | 透传根元素类名 |
| style | `CSSProperties` | — | 透传根元素内联样式 |

`DomeGalleryImage`：`string` 或 `{ src: string; alt?: string }`。

## 示例
```tsx
<div className="relative h-80 overflow-hidden rounded-xl bg-background">
  <DomeGallery
    images={[
      { src: "/a.jpg", alt: "封面 A" },
      { src: "/b.jpg", alt: "封面 B" },
    ]}
  />
</div>
```

壁纸级自动自转 + 彩色瓦片：
```tsx
<DomeGallery autoRotate grayscale={false} segments={20} />
```

## 禁忌 / 坑

- 需放进有明确高度 + `overflow-hidden` 的承托容器；小容器靠 `minRadius` 兜底防球面塌缩。
- `overlayColor` 应与容器背景一致（默认 `var(--color-background)`），否则边缘渐隐处会露出色差接缝。
- `images` 数量不足会循环铺满全部瓦片，超出可用瓦片数则尾部图片不显示——按 `segments` 估算瓦片总数再配图。
- reduced-motion 下惯性/自转降级，属预期。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Dot

> 状态圆点 · 5 语气状态色 + sm/md/lg + 呼吸 pulse(在线/进行中) + a11y label(role=status)(Tag/Chip 内嵌点的独立原语·纯CSS·RSC) · data-display/info

## 何时用

需要一个最小的语义状态圆点（在线/处理中/错误）时用，可内嵌进 Tag/Chip 或独立放在文字前。它是纯展示原语；要的是「健康态四语义 + 状态文字 + 延迟数值」的成品行用 [StatusDot](https://hulianui.haloritual.com/components/status-dot)；要叠加到图标四角并带计数用 [Badge](https://hulianui.haloritual.com/components/badge)。

## 导入
```ts
import { Dot } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"neutral"｜"brand"｜"success"｜"warning"｜"danger"` | `neutral` | 语气色：neutral 默认 / brand 处理中 / success 在线/成功 / warning 警告 / danger 离线/错误。 |
| size | `"sm"｜"md"｜"lg"` | `md` | 尺寸。 |
| pulse | `boolean` | `false` | 呼吸扩散动画（在线/进行中等活跃态语义）。 |
| label | `string` | — | 提供则 `role=status` + aria-label（表意圆点）；不提供则 aria-hidden（纯装饰）。 |

## 示例
```tsx
// 纯装饰状态点
<Dot tone="success" />

// 在线点：呼吸 + 屏读播报
<Dot tone="success" pulse label="在线" />
```

## 禁忌 / 坑

暂无已知坑。`label` 决定无障碍语义：表意圆点（真在传达状态）务必传 `label`，否则它被 `aria-hidden` 当装饰，屏读用户读不到。候选坑 `tauri-2-event-name-no-dot-character-set-restriction`（Tauri 事件命名）与 `timeline-dot-aligns-to-content-via-order-flip-not-pixel-push`（时间线圆点对齐）均与本组件无关，不适用。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# EditableTable

> 行内编辑表格 · 行级编辑(草稿副本/保存校验/取消还原) + 自定义编辑器(editor 逃生舱) + 增删行 + 列对齐/宽度(企业录入场景·文案接 i18n) · data-display/collection

## 何时用

需要在表格里直接行内编辑、增删行的录入场景——报价单、账单明细、人员配置。只读展示用 [Table](https://hulianui.haloritual.com/components/table)；带查询区/工具栏/分页的完整列表页用 [ProTable](https://hulianui.haloritual.com/components/pro-table)。本组件聚焦"逐行编辑保存"这一窄能力。

## 导入
```ts
import { EditableTable } from "@hulianui/ui"
```

## Props

`EditableTableProps<T>`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| columns* | `EditableColumn<T>[]` | — | 列定义(见下表) |
| data* | `T[]` | — | 数据数组(受控数据源) |
| rowKey* | `(row: T) => string` | — | 行稳定 key |
| addable | `boolean` | `false` | 显示「新增一行」按钮(需配合 `newRow`) |
| newRow | `() => T` | — | 新行工厂(返回新行数据)；新增后该行自动进入编辑态 |
| deletable | `boolean` | `false` | 每行可删除 |
| validateRow | `(row: T) => boolean` | — | 保存前校验整行，返回错误(falsy)则拦截保存(行内提示由消费者自理) |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(next: T[]) => void` | 任一提交/删除/新增后回传完整新数据 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| summary | `(data: T[]) => ReactNode` | 渲染函数——合计页脚：返回 tfoot 内容，消费者自备 `<tr><td colSpan=…>` 控制跨列对齐 |

`EditableColumn<T>`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| key* | `keyof T & string` | — | 数据键 |
| title* | `ReactNode` | — | 列标题 |
| editable | `boolean` | `false` | 是否可编辑(false=只读列，编辑态也展示原值) |
| render | `(value, row) => ReactNode` | — | 展示态渲染(默认直接渲染该键的值) |
| editor | `(value, onChange, row) => ReactNode` | — | 编辑态编辑器(默认文本 Input)，`onChange` 写回草稿对应键 |
| width | `number` | — | 列宽(px) |
| align | `"left" \| "center" \| "right"` | `"left"` | 单元格对齐 |

## 示例
```tsx
const [data, setData] = useState(rows);
const columns: EditableColumn<Row>[] = [
  { key: "name", title: "姓名", editable: true, width: 160 },
  { key: "salary", title: "月薪", editable: true, align: "right",
    render: (v) => `¥${Number(v).toLocaleString()}`,
    editor: (v, onChange) => (
      <input type="number" value={v as number}
        onChange={(e) => onChange(Number(e.target.value))} />
    ) },
];

<EditableTable<Row>
  columns={columns}
  data={data}
  rowKey={(r) => String(r.id)}
  onChange={setData}
  addable
  deletable
  newRow={() => ({ id: Date.now(), name: "", salary: 0 })}
/>
```

## 禁忌 / 坑

- 数据源**受控**：必须把 `onChange` 回传的 `next` 写回 state，否则保存/增删后界面不更新。
- `validateRow` 只负责"阻断保存"，不渲染错误提示——行内报错文案要消费者自己在 `editor` 里处理。
- `summary` 不自动管对齐：内容是 raw tfoot，跨列对齐(`colSpan`/列宽)由消费者自己掌控。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# Empty

> 空状态 · 图标+标题+描述+操作槽 + 内置空箱图标 + sm/md(零依赖·RSC) · data-display/placeholder

## 何时用

列表/表格/搜索结果无数据时用，给用户「为什么空 + 下一步做什么」（通过 `children` 放操作按钮）。它表达「已加载完但没内容」——加载中的占位用 [Skeleton](https://hulianui.haloritual.com/components/skeleton)；防泄密遮罩用 [Watermark](https://hulianui.haloritual.com/components/watermark)；表格自带空态可直接用 [Table](https://hulianui.haloritual.com/components/table)/[ProTable](https://hulianui.haloritual.com/components/pro-table)。

## 导入
```ts
import { Empty } from "@hulianui/ui"
```

## Props

继承 `div` 的所有原生属性（`title` 除外，已重定义为 ReactNode）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm" \| "md"` | `"md"` | 尺寸 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 自定义插画/图标。默认内置空箱图标，传 `null` 则不渲染图标区 |
| title | `ReactNode` | 主标题 |
| description | `ReactNode` | 辅助描述 |
| children | `ReactNode` | 操作区（按钮等），渲染在描述下方 |

## 示例
```tsx
// 默认
<Empty title="暂无数据" description="当前列表还没有任何内容" />

// 带操作
<Empty title="还没有项目" description="创建第一个项目开始使用">
  <Button size="sm">新建项目</Button>
</Empty>
```

## 禁忌 / 坑

- 别把「整个列表区是否渲染」和 Empty 绑死成 `if (!data.length) return <Empty/>`——若同区域有需保活的持久子组件（如已挂载的滚动容器、表单），条件 return 会把它们卸载重挂。参见 [[conditional-empty-return-unmounts-persistent-children]]。

## 相关
[Skeleton](https://hulianui.haloritual.com/components/skeleton) · [Watermark](https://hulianui.haloritual.com/components/watermark) · [Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table)

<!-- ════════════════════════════════════════════════════════ -->
# FileTree

> 文件树 · 递归 nodes(file/folder) + 文件夹展开折叠(defaultExpanded) + 改动状态角标 A/M/D/U/R 着色(纯函数 statusMeta 可测·git status 语义) + selectedPath 受控高亮 + onSelect 回传 node+path · 复用 _icons Folder/File(新补)·devtools 左栏 · data-display/collection

## 何时用

渲染递归文件/文件夹树（IDE/devtools 左栏、PR 改动文件列表），带 git status 风格的 A/M/D/U/R 改动角标、展开折叠、选中高亮、内置搜索。本组件是层级文件结构专用；要任意层级数据树用 [Tree]，要二维表格用 [Table](https://hulianui.haloritual.com/components/table)。

## 导入
```ts
import { FileTree, fileStatusMeta, filterFileTree } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes* | `FileNode[]` | — | 树数据（递归 file/folder） |
| selectedPath | `string` | — | 受控高亮当前选中（按拼接 path 匹配） |
| expandedPaths | `string[]` | — | 受控展开的 folder path 集合（传入即受控） |
| defaultExpandedPaths | `string[]` | — | 非受控初始展开（与各 folder 的 defaultExpanded 合并） |
| searchable | `boolean` | `false` | 树内搜索框（过滤 + 命中祖先自动展开） |
| searchPlaceholder | `string` | `"搜索文件"` | 搜索框占位符 |
| className | `string` | — | 自定义类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(node: FileNode, path: string) => void` | 点击文件/文件夹回调，回传节点与拼接 path |
| onContextMenu | `(node: FileNode, path: string, e: React.MouseEvent) => void` | 行右键回调（消费者配 ContextMenu 锚光标弹菜单） |
| onExpandedChange | `(paths: string[]) => void` | 展开变化回调（受控/非受控都回调） |

`FileNode`：`{ name: string; type: "file"｜"folder"; status?: FileStatus; children?: FileNode[]; defaultExpanded?: boolean }`。
`FileStatus`：`"added"｜"modified"｜"deleted"｜"untracked"｜"renamed"`（渲染为右侧 A/M/D/U/R 着色字母角标）。

## 示例
```tsx
const [sel, setSel] = useState("src/index.ts");
<FileTree
  nodes={[
    { name: "src", type: "folder", defaultExpanded: true, children: [
      { name: "index.ts", type: "file", status: "modified" },
      { name: "legacy.ts", type: "file", status: "deleted" },
    ]},
    { name: "README.md", type: "file", status: "renamed" },
  ]}
  selectedPath={sel}
  onSelect={(node, path) => setSel(path)}
/>
```

## 禁忌 / 坑

- 选中/展开都按「拼接 path」（如 `src/components/button.tsx`）匹配，不是 `name`——`selectedPath` 与 `onSelect` 回传的 path 是同一套拼接规则。
- 展开两态：传 `expandedPaths` 即受控（须配 `onExpandedChange` 回写）；否则用 `defaultExpandedPaths` + 各 folder 的 `defaultExpanded` 合并的非受控态。
- `status` 仅对 file 有 git 语义；`children` 仅 folder 有意义。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Flow

> 节点画布编排器 · 零依赖原生 Pointer Events + SVG 贝塞尔连线 · 拖节点/拖桩连线/平移缩放/适配视图 + 受控 nodes/edges(onNodesChange/onConnect/删点删线) + renderNode 自定义节点内容 · 几何抽纯函数带单测 · AI 工作流/流程编排旗舰 · data-display/collection

## 何时用

节点画布式可视化编排（AI 工作流、流程/DAG 编辑、节点连线图），受控 `nodes`/`edges` + 拖节点/拖桩连线/平移缩放/适配视图。只需多列卡片流转用 [Kanban](https://hulianui.haloritual.com/components/kanban)；单列表排序用 [Sortable](https://hulianui.haloritual.com/components/sortable)。

## 导入
```ts
import { Flow, bezierPath, clampZoom, fitViewport, handleOffsetRatio, handlePoint, nodesBounds, screenToCanvas, zoomAtPoint } from "@hulianui/ui"
```

## Props

`FlowProps<T>` 泛型。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes * | FlowNode\<T\>[] | — | 受控节点数组（`{ id, position, data, width? }`） |
| edges * | FlowEdge[] | — | 受控连线数组（`{ id, source, target, sourceHandle?, targetHandle? }`） |
| getHandles * | (node: FlowNode\<T\>) => FlowHandleSpec[] | — | 声明每节点连接桩（左 target/右 source，按返回顺序在该侧均分纵向位置） |
| selectedId | string ｜ null | — | 单选受控：当前选中节点 id |
| defaultNodeWidth | number | 240 | 默认节点宽度（px，画布坐标） |
| minZoom | number | 0.35 | 缩放下限 |
| maxZoom | number | 2 | 缩放上限 |
| controls | boolean | true | 是否显示右下角缩放/适配工具条 |
| isEdgeAnimated | (edge: FlowEdge) => boolean | — | 某条连线是否走流光动画（如运行中链路） |
| className | string | — | 画布外层类名（须有确定高度，组件填满） |
| apiRef | MutableRefObject\<FlowApi ｜ null\> | — | 命令式句柄（fitView / zoomIn / zoomOut / reset / autoLayout） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onNodesChange | (nodes: FlowNode\<T\>[]) => void | 节点拖动后回吐整组新位置（组件不直接改 data） |
| onConnect | (connection: FlowConnection) => void | 从输出桩拖到合法输入桩成功 → 新连接（无 id，你补 id 并去重） |
| onEdgesDelete | (ids: string[]) => void | 删除连线（选中后点 × 或按 Delete） |
| onNodeDelete | (id: string) => void | 删除节点（选中后点 × 或按 Delete） |
| onSelectNode | (id: string ｜ null) => void | 选中变化（点节点=id，点空白=null） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderNode * | (node: FlowNode\<T\>, state: { selected: boolean }) => ReactNode | 渲染节点内容的渲染函数（外框/桩/选中态由组件负责） |
| background | ReactNode ｜ false | 画布底纹（false 关闭）；默认内置点阵 |

## 示例
```tsx
const [nodes, setNodes] = useState(initialNodes);
const [edges, setEdges] = useState(initialEdges);
const [selected, setSelected] = useState<string | null>(null);

<div className="h-[420px] w-full overflow-hidden rounded border border-border">
  <Flow<NodeData>
    nodes={nodes}
    edges={edges}
    getHandles={getHandles}
    selectedId={selected}
    onSelectNode={setSelected}
    onNodesChange={setNodes}
    onConnect={(c) => setEdges((p) => [...p, { id: `e${Date.now()}`, ...c }])}
    onEdgesDelete={(ids) => setEdges((p) => p.filter((e) => !ids.includes(e.id)))}
    onNodeDelete={(id) => {
      setNodes((p) => p.filter((n) => n.id !== id));
      setEdges((p) => p.filter((e) => e.source !== id && e.target !== id));
    }}
    renderNode={(n) => <div className="px-3.5 py-2.5">{n.data.title}</div>}
  />
</div>
```

## 禁忌 / 坑

- 外层 `className` **必须有确定高度**（如 `h-[420px]` 或父级撑满），画布按外层尺寸填充——高度塌缩则画布不可见。
- 全受控：`onConnect` 回吐的连接**无 id**，你要自己补 id 并去重；`onNodeDelete` 只给节点 id，关联连线要你自己一并清掉（否则留下悬空 edge）。
- 客户端组件（原生 Pointer Events），必须在 client 上下文用。
- 候选坑 `base-ui-navigation-menu-content-must-stay-in-flow-for-popup-size-measure` 仅因「flow」字面匹配，讲的是 Base UI 导航菜单布局，与本组件无关，不引用。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# FlyingPosters

> WebGL 海报飞行长廊 · 一列海报随滚轮/拖拽无限循环上下飞过，顶点着色器按 distortion 翻折"飞起"·离屏循环复用 + 透视相机景深(ogl·懒加载·StrictMode 安全·reduced-motion 静态海报网格 fallback·去 gsap 改 RAF lerp) · data-display/collection · #animated

## 何时用

需要把一组同比例海报/封面做成沉浸式的滚动飞行长廊（落地页 hero、画廊入口）时用。要的是"真 3D 倾斜翻折 + 透视景深"用本组件（WebGL/ogl）；只想要 2D 平面卡片的鼠标悬停倾斜用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)，要滚动逐张钉住堆叠用 [ScrollStack](https://hulianui.haloritual.com/components/scroll-stack)。

## 导入
```ts
import { FlyingPosters } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `string[]` | `[]` | 海报图片地址数组，按顺序首尾相接无限循环。建议同比例图，shader 内 cover 裁切不变形；空数组只渲空画布不抛错 |
| planeWidth | `number` | `320` | 单张海报平面宽度（世界单位），与 planeHeight 共定比例与密度 |
| planeHeight | `number` | `320` | 单张海报平面高度（世界单位） |
| distortion | `number` | `3` | 卷动时弯折扭曲强度，越大翻折越夸张；建议 1–6，0 近似平移 |
| scrollEase | `number` | `0.01` | 卷动缓动系数（0–1），越小越"重"惯性越长（showcase 默认演示用 0.05） |
| cameraFov | `number` | `45` | 透视相机视场角（度），越大透视越强、飞入飞出弧度越明显 |
| cameraZ | `number` | `20` | 相机 Z 轴距离，越大画面越远、可见海报越多 |
| autoScroll | `boolean` | `true` | 无交互时是否自动缓慢卷动；reduced-motion 下强制关闭 |
| autoScrollSpeed | `number` | `0.6` | 自动卷动速度（世界单位/秒），autoScroll 为真时生效 |
| className | `string` | — | 透传到根容器的额外 className |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion 或无 WebGL 时，静态备用层中央展示的内容 |

## 示例
```tsx
// 根容器需自带尺寸（组件填满父级），通常 absolute inset-0 铺满定位容器
<div className="relative h-80 w-full overflow-hidden rounded-xl">
  <FlyingPosters items={posters} className="absolute inset-0" />
</div>

// 强翻折 + 广角透视
<FlyingPosters items={posters} distortion={5} cameraFov={70} cameraZ={26} />
```

## 禁忌 / 坑

- 根容器**必须有明确尺寸**（如 `absolute inset-0` 铺满一个定高的相对定位父级）；否则画布为 0 不可见。
- WebGL 仅客户端可用：组件内部已懒加载 ogl 并做 SSR/StrictMode 安全降级，但仍应放在客户端渲染路径，无 WebGL/reduced-motion 时回退 `fallback` 静态层。
- [[webgl-canvas-loseContext-poisons-strictmode-remount]]：cleanup 调 loseContext 会永久毒化 canvas，StrictMode 双挂载复用即崩白屏——本组件应每次挂载新建 canvas，不要在外层缓存复用其 canvas 节点。
- [[mcp-browser-busy-launch-isolated-chromium-via-executablepath]] / [[recharts-headless-screenshot-blank-clippath-animation-starved]]：headless 截图验证时 WebGL 入场动画可能停在第 0 帧显空白，属正常现象，用真实浏览器或设 reduced-motion 再验。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Folder

> 点击展开的 3D 文件夹 · 三层纸张扇形铺开 + 展开后磁吸跟随鼠标(零依赖纯 CSS transform·token 派生·reduced-motion) · data-display/collection · #animated

## 何时用

需要一个有趣味交互的「文件夹」展示控件——点击展开、最多 3 张纸扇形铺开、展开后磁吸跟随鼠标时用，适合作品集/文件分组/装饰性入口。要做真实的多层级文件树导航请用 FileTree/Tree；要做表格化数据展示用 [Table](https://hulianui.haloritual.com/components/table)。

## 导入
```ts
import { Folder } from "@hulianui/ui"
```

## Props

继承 `<div>` 属性（已 `Omit` 掉 `color`/`onClick`，由下表重定义）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-primary)` | 文件夹主体色，接受任意 CSS 颜色，推荐喂 token；showcase 备选 `chart-1/2/4` |
| size | `number` | `1` | 整体缩放倍数（基准 100×80px） |
| open | `boolean` | — | 受控展开态；提供时组件受控，须配 `onOpenChange` |
| defaultOpen | `boolean` | `false` | 默认展开态（非受控） |
| disableMagnet | `boolean` | `false` | 关闭磁吸跟随（展开后纸张不再随鼠标偏移） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `MouseEventHandler<HTMLButtonElement>` | 点击文件夹（触发展开/收起）时回调 |
| onOpenChange | `(open: boolean) => void` | 展开态变化回调（受控/非受控均触发） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| items | `ReactNode[]` | 最多 3 张纸张内容（多余截断、不足补空），展开后扇形铺开并磁吸跟随 |

## 示例

```tsx
// 默认（点击展开）
<Folder />

// 带 3 张纸内容
<Folder
  size={1.4}
  items={[
    <span key="1">文档</span>,
    <span key="2">图片</span>,
    <span key="3">视频</span>,
  ]}
/>
```

## 禁忌 / 坑

- `items` 超过 3 张会被截断、不足会补空白纸，不要指望它渲染任意数量内容。
- 受控用法须同时给 `open` + `onOpenChange`，只给 `open` 不给回调会导致点击无法切换状态。
- 颜色 token 须带 `--color-` 前缀，裸 `var(--primary)` 不解析。
- 候选坑 [[nextjs-app-router-underscore-private-folder-404]] 讲的是 Next.js `_folder` 私有目录路由，与本组件无关，不适用。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Funnel

> 漏斗图 · 阶段宽度按 value 比例 + 级间转化率徽标(本级/上一级) · 纵/横双向 + per-stage tone + renderStage 自定义 · computeFunnel 纯函数(不除零)带单测 · 任务漏斗/转化漏斗/留存(零依赖) · data-display/collection

## 何时用

可视化「单一线性流程逐级流失/转化」时用——访问→注册→付费、任务涌入→完成、留存衰减。要表达跨多层的有向分流（一节点流向多去向）用 Sankey；只列扁平数值用 [Table]。Funnel 专门表达「每级相对上一级的转化率」。

## 导入
```ts
import { Funnel, computeFunnel } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| stages* | `FunnelStage[]` | — | 阶段数组。`{id, label, value, tone?}`；漏斗宽/高按 value 比例缩放 |
| orientation | `"vertical" \| "horizontal"` | `"vertical"` | vertical 每级一行按宽度比 / horizontal 每列按高度比 |
| showConversion | `boolean` | `true` | 是否显示级间转化率徽标 |
| className | `string` | — | 外层类名 |

FunnelStage.tone：`"neutral" \| "brand" \| "success" \| "warning" \| "danger"`，缺省 `brand`（同 Tag 的 tone 语义，吃 token）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onStageClick | `(stage) => void` | 点击某一级回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderStage | `(stage, ctx: FunnelRenderCtx) => ReactNode` | 渲染函数：自定义阶段内容（替换默认 label + value）。ctx 含 `widthRatio`/`conversion`(首级 null)/`index` |

## 示例
```tsx
<Funnel
  stages={[
    { id: "in", label: "涌入", value: 1240, tone: "brand" },
    { id: "route", label: "路由", value: 1080, tone: "brand" },
    { id: "exec", label: "执行", value: 860, tone: "warning" },
    { id: "done", label: "完成", value: 720, tone: "success" },
  ]}
  orientation="vertical"
  showConversion
  onStageClick={(s) => console.log(s.id)}
/>
```

## 禁忌 / 坑

- tone 是固定语义枚举（neutral/brand/success/warning/danger），不接受任意 CSS 颜色——要自定义配色走 `renderStage`。
- `computeFunnel` 纯函数对首级 `conversion` 返回 `null`（无上一级可比），且不除零；自定义渲染时务必判 `conversion == null`。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Gantt

> 甘特图(只读) · 项目排期可视化 · 左固定列(按 group 分组小标题) + 右时间轴(day/week/month 刻度) · CSS grid + 百分比定位条形 + progress 深色填充层 + today 竖线 · 自带 UTC 日期数学(零依赖) · 横向滚动 · data-display/collection

## 何时用

只读展示「项目排期/工序时间线」时用——施工排期、迭代计划、含进度的任务条。条形不可拖拽改期（纯展示）；要拖拽编辑日期/时长用 Scheduler（事件日历）。要看依赖流向用 Flow。Gantt 胜在零依赖、自带 UTC 日期数学、CSS grid 渲染。

## 导入
```ts
import { Gantt } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`（除 children）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tasks* | `GanttTask[]` | — | 任务列表（只读，不可拖拽改期） |
| rangeStart | `string` | — | 时间轴起点 `"YYYY-MM-DD"`；省略自动取最早 start 并向前留 padding |
| rangeEnd | `string` | — | 时间轴终点 `"YYYY-MM-DD"`；省略自动取最晚 end 并向后留 padding |
| unit | `"day" \| "week" \| "month"` | `"day"` | 表头刻度密度（week 周一起）；仅影响刻度，不改条形定位 |
| today | `string` | — | 今日竖线日期 `"YYYY-MM-DD"`；落在范围内才绘制 |
| rowHeight | `number` | `36` | 每行高度（px） |
| className | `string` | — | 外层类名 |

GanttTask：`{id, name, start, end, progress?, group?, color?}`。start/end 为 `"YYYY-MM-DD"` 闭区间（含首尾两端）；progress 0-100 驱动条内深色填充层；相同 group 在左列以小标题聚拢；color 为 CSS 颜色（token var() 或 hex），省略走主题 primary。

## 示例
```tsx
const tasks: GanttTask[] = [
  { id: "t1", name: "现场勘测", start: "2026-06-01", end: "2026-06-05", progress: 100, group: "前期" },
  { id: "t3", name: "主体施工", start: "2026-06-08", end: "2026-06-24", progress: 60, group: "施工" },
  { id: "t5", name: "竣工验收", start: "2026-07-01", end: "2026-07-06", progress: 0, group: "收尾" },
];

<Gantt tasks={tasks} unit="week" today="2026-06-18" />
```

## 禁忌 / 坑

- 日期字符串是闭区间 `"YYYY-MM-DD"`，组件用 UTC 日期数学避开时区漂移——别传带时分或本地时区偏移的 ISO datetime（那是 Scheduler 的输入）。
- color 用 token 变量时须带 `--color-` 前缀（`var(--color-chart-2)`），裸变量不解析，见 [[hulian-token-color-var-needs-color-prefix]]。
- 时间轴可能比容器宽，组件靠横向滚动——外层给确定宽度（如 `w-[680px] max-w-full`）才有滚动条。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# GitCommit

> git 提交引用 · 分支 chip(GitBranch) + 短哈希等宽(纯函数 shortSha 可测·可定制位数/href 跳链) + 提交信息单行截断 + 作者头像槽 · inline 单行/stacked 两行(表格单元格) · 部署列表/PR 列表/活动流「Source」列刚需(零依赖·RSC) · data-display/info

## 何时用

在部署列表、PR 列表、活动流的「Source / 提交」列展示一条 git 提交引用（分支 + 短哈希 + 信息 + 作者）。它是纯展示的单条引用：要展示部署/构建的生命周期态用 [DiffStat](https://hulianui.haloritual.com/components/diff-stat)/[DeployStatus]，要呈现一组按时间排列的事件流用 [Timeline]；本组件只负责「一行提交」的标准化排版。

## 导入
```ts
import { GitCommit, shortSha, branchTone, type BranchTone } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sha* | `string` | — | commit SHA，完整或短哈希均可，显示时按 `shaLength` 截短 |
| branch | `string` | — | 分支名；提供则前置分支图标 chip |
| author | `string` | — | 作者名 |
| href | `string` | — | 短哈希跳转链接，去 commit 详情 |
| shaLength | `number` | `7` | 短哈希显示位数 |
| colorBranch | `boolean` | `true` | 给分支名加色值标识（按分支名稳定取色的 soft badge），不同分支一眼可分 |
| layout | `"inline" \| "stacked"` | `"inline"` | inline 单行 / stacked 两行（信息在上、引用在下，列表/表格单元格刚需） |
| size | `"sm" \| "md"` | `"md"` | 尺寸 |
| className | `string` | — | 透传类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| message | `ReactNode` | 提交信息标题，单行截断；stacked 下作主行 |
| avatar | `ReactNode` | 作者头像槽，传 `<Avatar/>` 或任意节点，不与库强耦合 |

## 示例
```tsx
// inline 单行
<GitCommit sha="10577b9aaaa" branch="master" message="fix(www,mocks): ai-chat 部署站无响应" />

// stacked 两行（表格/列表单元格，带作者头像 + 可点击短哈希）
<GitCommit
  layout="stacked"
  sha="36e347faaa"
  branch="master"
  message="feat(www): 全局路由进度条"
  author="瑚琏"
  avatar={<Avatar>瑚</Avatar>}
  href="#36e347f"
/>
```

## 禁忌 / 坑
暂无已知坑。`shortSha` / `branchTone` 是导出的纯函数（截哈希 / 按分支名取色），可在表格 cell 渲染外复用与单测。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Heatmap

> 热力图 · 网格色阶映射(value→bucket→primary 透明度档·纯函数 buildMatrix/bucketize 可测) + 行列标签 + 原生 hover 提示 + 点击下钻 · 代码热点/贡献活动/覆盖率·库内首个热力图 · data-display/collection

## 何时用

把稀疏的 `{x, y, value}` 点集按二维网格展开、用色阶强度表达数值密度时用（贡献活动墙、模块×时间问题热点、覆盖率矩阵）。需要可排序、可分页、单元格内放富内容的表格走 [Table](https://hulianui.haloritual.com/components/table) / [ProTable](https://hulianui.haloritual.com/components/pro-table)；这里只做「强度即颜色」的密度可视化。

## 导入
```ts
import { Heatmap, buildMatrix, bucketize } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data* | `HeatCell[]` | — | 稀疏点集 `{x, y, value}`。 |
| xLabels | `(string｜number)[]` | 从 data 推导 | 显式列标签。 |
| yLabels | `(string｜number)[]` | 从 data 推导 | 显式行标签。 |
| colorScale | `number` | `5` | 色阶档数。 |
| max | `number` | 数据最大值 | 满值（决定色阶顶档）。 |
| cellSize | `number` | `14` | 格子边长 px。 |
| gap | `number` | `3` | 格间距 px。 |
| showLabels | `boolean` | `true` | 是否显示行/列标签。 |
| formatTooltip | `(cell: HeatmapCellInfo) => string` | — | 悬停原生提示文案（返回字符串）。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCellClick | `(cell: HeatmapCellInfo) => void` | 点击格子下钻。 |

## 示例
```tsx
const data = MODULES.flatMap((m, mi) =>
  WEEKDAYS.map((d, di) => ({ x: d, y: m, value: (mi * 7 + di * 3 + 2) % 10 })),
);

<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} cellSize={18} />
```

无标签紧凑模式：
```tsx
<Heatmap data={data} xLabels={WEEKDAYS} yLabels={MODULES} showLabels={false} cellSize={12} />
```

## 禁忌 / 坑

暂无已知坑。注意 `data` 的 `value` 应为确定性数据：showcase 用伪随机公式而非 `Math.random()` 生成，避免 SSR/CSR 首帧色阶不一致。色阶顶档由 `max`（缺省取数据最大值）决定，跨多张图对比时建议显式传同一 `max` 才能横向可比。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Image

> 图片 · 加载淡入 + 失败回退/占位 + isZoomed hover 放大 + radius · data-display/collection

## 何时用

替代原生 `<img>` 展示需要加载淡入、失败回退占位、圆角、hover 放大的图片（封面、头像、内容图）。只是装饰性 logo 滚动墙用 [Marquee](https://hulianui.haloritual.com/components/marquee)；要全屏看大图/缩放预览用 ImageViewer。

## 导入
```ts
import { Image, imageVariants } from "@hulianui/ui"
```

## Props

继承 `Omit<ImgHTMLAttributes<HTMLImageElement>, "width" | "height">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| src * | string | — | 图片地址 |
| alt | string | — | 替代文本 |
| width | number ｜ string | — | 宽（数字或 CSS 长度） |
| height | number ｜ string | — | 高（数字或 CSS 长度） |
| radius | `"none"｜"sm"｜"md"｜"lg"｜"full"` | `"md"` | 圆角刻度 |
| isZoomed | boolean | false | hover 放大（外壳裁切溢出） |
| fallbackSrc | string | — | 加载失败时回退图；缺省则显示占位底 |
| className | string | — | 外壳 className（控制尺寸/圆角区域） |
| imgClassName | string | — | `<img>` 自身 className |
| ...img | Omit\<ImgHTMLAttributes, "width"｜"height"\> | — | 透传其余原生 img 属性 |

## 示例
```tsx
<Image src="/photo.jpg" alt="风景" width={220} height={140} />

// hover 放大
<Image src="/photo.jpg" alt="风景" width={200} height={130} isZoomed />

// 加载失败回退
<Image src="https://invalid.example/none.png" fallbackSrc="/photo.jpg" alt="回退" width={200} height={130} />
```

## 禁忌 / 坑

- `isZoomed` 的放大效果靠外壳 `overflow` 裁切，外壳尺寸由 `width/height`/`className` 决定——别给 `<img>`（`imgClassName`）单独设溢出。
- 圆角分两层：`radius` 作用于外壳；要单独调 `<img>` 走 `imgClassName`。`radius="full"` 配等宽高做圆形头像。
- 候选坑 skill（`dark-image-page-bg-seam-converge-same-color` / `image-enhancer` 等）均为业务/工具场景，与本组件无关，不引用。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# ImageViewer

> 图片查看器 · 全屏 Lightbox(portal+锁滚复用 dialog) · 受控 index 翻页(箭头/← →/序号) + 滚轮指针锚定缩放/双击 1x↔2x/拖拽平移(切图重置) + 底部缩略图条 + role=dialog aria-modal/Esc 关闭(仅渲当前图·零依赖) · data-display/info

## 何时用

需要点开缩略图进入「全屏看大图 + 翻页 + 缩放平移」时用——相册、工作照片、附件预览。只内联展示趋势小图用 [Sparkline]；展示商品卡用 [LiveProductCard]。ImageViewer 是全屏 Lightbox，受控 open/index，零依赖自带缩放平移。

## 导入
```ts
import { ImageViewer } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| open* | `boolean` | — | 受控开关 |
| images* | `ImageViewerImage[]` | — | 图片数组。`{src, alt?, caption?}` |
| index* | `number` | — | 受控当前页（组件不自管，翻页/点缩略图都回调出去） |
| className | `string` | — | 面板类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange* | `(open: boolean) => void` | 开关回调（Esc / 点遮罩 / 关闭按钮触发） |
| onIndexChange* | `(index: number) => void` | 翻页回调（箭头/← →/点缩略图触发） |

## 示例
```tsx
const [open, setOpen] = useState(false);
const [index, setIndex] = useState(0);

<ImageViewer
  open={open}
  onOpenChange={setOpen}
  images={[
    { src: "/a.jpg", alt: "A", caption: "说明" },
    { src: "/b.jpg", alt: "B" },
  ]}
  index={index}
  onIndexChange={setIndex}
/>
```

## 禁忌 / 坑

- 全受控：open 与 index 都由外部持有，组件不自管当前页——翻页/点缩略图通过 `onIndexChange` 回调，必须 setState 才会动。
- 缩放/平移是「视图态」，切图（index 变）和开关（open 变）时组件内部自动归零；不要在外部缓存 scale/offset 想跨图保留。
- 只渲染当前 index 的大图（缩略图条用小尺寸 src），images 很多也不卡；打开前记得把 index 复位到目标图。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# InfiniteMenu

> 可拖拽旋转的菜单球，菜单项围绕球面分布、正对镜头者贴靠为激活项并显覆盖层标题/描述+动作箭头 · 松手惯性衰减 + 自动自旋（零依赖 CSS-3D/RAF·reduced-motion） · data-display/collection · #animated

## 何时用

把一组导航入口/画廊项做成可拖拽探索的球面菜单（创意首页、作品集导航）时用。要的是"球面分布 + 拖拽旋转 + 贴靠激活"的探索式导航用本组件；只展示一组海报飞行长廊用 [FlyingPosters](https://hulianui.haloritual.com/components/flying-posters)，单卡 3D 倾斜用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)。

## 导入
```ts
import { InfiniteMenu } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `InfiniteMenuItem[]` | `[]` | 菜单项数组，沿球面 Fibonacci 均匀分布；正对镜头的项为激活项并在覆盖层显其标题/描述。空数组渲占位球 |
| scale | `number` | `1` | 球体缩放系数，越大球越近、单卡越大 |
| itemSize | `number` | `88` | 单张卡片直径（px） |
| autoRotate | `number` | `6` | 自动旋转角速度（度/秒，绕 Y 轴），0 关闭；拖拽时暂停，松手惯性衰减后恢复；reduced-motion 下强制为 0 |
| className | `string` | — | 透传到根容器的额外类名 |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onActiveItemChange | `(item: InfiniteMenuItem, index: number) => void` | 激活项变化回调（拖拽停止贴靠到最前项后触发） |
| onItemActivate | `(item: InfiniteMenuItem, index: number) => void \| false` | 点击激活项动作箭头回调，返回 `false` 阻止默认 `window.open` |

`InfiniteMenuItem`：`{ image?: string; title?: string; description?: string; link?: string }` —— `link` 以 http 开头则 `window.open` 新标签，否则交给 `onItemActivate` 处理；`image` 省略时仅显示标题首字。

## 示例
```tsx
const items = [
  { title: "概览", description: "项目全局视图", link: "https://example.com" },
  { title: "任务", description: "进行中的工作流" },
  { title: "成员", description: "团队与权限" },
];

// 根容器需有固定尺寸，组件填满
<div className="relative h-80 w-full overflow-hidden rounded-xl">
  <InfiniteMenu items={items} />
</div>

// 关闭自动旋转，仅拖拽
<InfiniteMenu items={items} autoRotate={0} />
```

## 禁忌 / 坑

- 根容器需有明确尺寸（球按容器测量布局），否则球不可见或塌缩。
- `link` 不以 http 开头时**不会自动跳转**，须自行在 `onItemActivate` 里处理（如 `router.push`）。
- 纯 CSS-3D + RAF 零依赖，但仍是交互动效组件：reduced-motion 下自动停自旋；headless 截图可能停在某一帧，验交互态用真实浏览器。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# InfiniteScroll

> 无限滚动 · IntersectionObserver 底部哨兵 + 自动定位可滚祖先作 root + 加载锁防重入 + hasMore 完结态(零依赖·分页加载) · data-display/collection

## 何时用

滚动接近底部时自动拉取下一页、直到 `hasMore=false` 显示完结文案。零依赖、包住已渲染列表即可。当列表行数大到全量 DOM 卡顿，应改用 [VirtualList](https://hulianui.haloritual.com/components/virtual-list)（仅渲染可见区）并用其 `onReachEnd` 触发加载；本组件适合行数中等、无需虚拟化的场景。

## 导入
```ts
import { InfiniteScroll } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| hasMore* | `boolean` | — | 是否还有更多；false 时停止观察并显示完结文案。 |
| threshold | `number` | `100` | 距底多少 px 提前触发（IntersectionObserver rootMargin）。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onLoadMore* | `() => Promise<void>｜void` | 触底加载回调；返回 Promise 期间不重复触发。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 已渲染的列表内容。 |
| loadingText | `ReactNode` | 加载中文案。 |
| finishedText | `ReactNode` | 完结文案。 |

## 示例
```tsx
function Feed() {
  const [items, setItems] = useState(() => Array.from({ length: 15 }, (_, i) => i + 1));
  const hasMore = items.length < 45;
  const loadMore = () =>
    fetchNextPage().then((page) => setItems((prev) => [...prev, ...page]));

  return (
    <div className="h-72 overflow-y-auto">
      <InfiniteScroll onLoadMore={loadMore} hasMore={hasMore}>
        {items.map((n) => <Row key={n} data={n} />)}
      </InfiniteScroll>
    </div>
  );
}
```

## 禁忌 / 坑

暂无已知坑。`onLoadMore` 务必返回 Promise（异步加载）——组件靠这个 Promise 的 pending 期做加载锁防重入；返回 void 同步加载则失去防抖，快速滚动可能多次触发。哨兵自动向上寻找可滚动祖先作 IntersectionObserver 的 root，故外层需有明确的 `overflow-y-auto` 滚动容器，否则退化到视口监听。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# JsonViewer

> 折叠 JSON 树(只读) · 递归零依赖 + 语法着色(key/string/number/bool/null) + 行级展开折叠 + 折叠态 {…} N keys/[…] N items + depth<阈值初始展开/大对象懒展开 + hover 复制节点值与 JSON path(网关请求/响应日志检查器刚需·导出 valueType/jsonPath 纯函数) · data-display/collection

## 何时用

只读检视任意 JSON 结构时用——网关请求/响应日志、API 调试器、配置预览。需要把 JSON 喂进表单做编辑用别的；纯键值对详情页(扁平、无嵌套)用 [Descriptions](https://hulianui.haloritual.com/components/descriptions) 更合适，本组件专攻深层嵌套的可折叠树。

## 导入
```ts
import { JsonViewer, valueType, jsonPath } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data* | `unknown` | — | 任意 JSON 值 |
| rootName | `string` | — | 根节点标签(如 `"response"`) |
| defaultExpandedDepth | `number` | `1` | 初始展开深度：嵌套节点 `depth < defaultExpandedDepth` 时初始展开(根的直接子节点 depth=1) |
| maxAutoExpandKeys | `number` | `50` | 大对象/数组懒展开阈值：子项数超过则初始折叠保护 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCopyPath | `(path: string) => void` | 复制节点 JSON path 回调(同时把节点值复制到剪贴板) |

## 示例
```tsx
<JsonViewer data={response} />

// 多层全展开
<JsonViewer data={usage} defaultExpandedDepth={3} />
```

## 禁忌 / 坑

- 只读组件，不接受编辑回调；`onCopyPath` 只是 hover 复制 path/值，不改 `data`。
- 超过 `maxAutoExpandKeys`(默认 50)子项的大对象会初始折叠以保护性能，需要手动展开——别误以为数据没渲染出来。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [EditableTable](https://hulianui.haloritual.com/components/editable-table) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# Kanban

> 看板 · @dnd-kit headless 多容器 + 跨列/列内拖拽 + 键盘可拖 + 列头统计槽 + 空列占位 · 受控 onMove(消费者改业务字段) · 商机看板/任务流转旗舰 · data-display/collection

## 何时用

多列拖拽流转（商机看板、任务流、工单状态推进），卡片跨列/列内重排，受控数据 + `onMove` 回吐落定事件由你改业务字段。单列表内排序用 [Sortable](https://hulianui.haloritual.com/components/sortable)；节点连线画布用 [Flow](https://hulianui.haloritual.com/components/flow)。

## 导入
```ts
import { Kanban, resolveKanbanMove } from "@hulianui/ui"
```

## Props

`KanbanProps<T>` 泛型。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| columns * | KanbanColumn[] | — | 列定义（顺序即展示顺序）。每列 `{ id, title, header?, footer? }` |
| items * | T[] | — | 受控卡片数组；组件按 getColumnId 分桶，列内顺序 = 数组原始顺序 |
| getId * | (item: T) => string | — | 取卡片稳定 id（全局唯一且稳定） |
| getColumnId * | (item: T) => string | — | 取卡片当前所属列 id |
| className | string | — | 容器类名 |
| columnClassName | string | — | 单列类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onMove * | (e: KanbanMoveEvent) => void | 拖拽落定回调；组件不直接改 T，由你据此改状态 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem * | (item: T, state: { dragging: boolean }) => ReactNode | 渲染单张卡片的渲染函数；`state.dragging` 表示正被拖拽 |
| renderColumnHeader | (column: KanbanColumn, items: T[]) => ReactNode | 自定义列头的渲染函数（拿该列卡片做统计）；缺省渲染 `column.header ?? column.title` |

`KanbanMoveEvent`：`{ id, fromColumn, toColumn, toIndex }`。`toIndex` = 目标列内（已剔除被拖卡片后）的插入下标。

## 示例
```tsx
const [cards, setCards] = useState(initial);

<Kanban
  items={cards}
  columns={columns}
  getId={(c) => c.id}
  getColumnId={(c) => c.status}
  onMove={(e) => setCards((prev) => applyMove(prev, e))}
  renderColumnHeader={(col, its) => (
    <div className="flex items-center justify-between">
      <span className="text-sm font-semibold text-foreground">{col.title}</span>
      <Tag tone="neutral" size="sm">{its.length}</Tag>
    </div>
  )}
  renderItem={(c) => <Card>{c.title}</Card>}
/>
```

## 禁忌 / 坑

- 受控且组件**不替你改卡片**：`onMove` 只回吐事件，你要在回调里改卡片的列字段并按 `toIndex` 插回（可用导出的 `resolveKanbanMove` 辅助）。这是有意为之——避免组件越界写你的业务字段。
- `toIndex` 是「剔除被拖卡片后」目标列的插入下标，落库逻辑要照此剔除再插入，否则跨列同列重排会算偏。
- `getId` 须全局唯一且稳定（不仅列内唯一）；卡片含交互子元素时同样要防拖拽拦截点击（[[dnd-kit-draggable-container-guard-interactive-children]]）。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# List

> 数据列表 · 复合 List/ListItem/ListItem.Meta + actions/size/bordered/split/grid + 空态/分页/加载更多(零依赖·复用 Empty/Pagination/Avatar/User) · data-display/collection

## 何时用

渲染同构条目流——团队成员、消息、设置项、资源卡片。带表头列/排序/可编辑用 [Table](https://hulianui.haloritual.com/components/table)/[EditableTable](https://hulianui.haloritual.com/components/editable-table)；本组件是更轻的"每行一条 + 头像/标题/描述/操作"垂直列表，开 `grid` 即变卡片栅格。

## 导入
```ts
import { List, ListItem, ListItemMeta } from "@hulianui/ui"
```

## Props

`ListProps<T>`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `T[]` | — | 数据数组(数据驱动模式，配合 `renderItem`) |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 尺寸(影响行内边距) |
| bordered | `boolean` | `false` | 外层边框 + 圆角容器(栅格态下忽略) |
| inset | `boolean` | 跟随 `bordered` | 行/头尾插槽水平内边距(与 bordered 解耦)；放进侧栏等已有容器时设 `inset` 让内容不贴边 |
| split | `boolean` | `true` | 行分隔线(栅格态下忽略) |
| grid | `boolean \| ListGridConfig` | — | 栅格卡片态(复用 Grid)；传 `true` 用默认配置(3 列) |
| loadMore | `ListLoadMore` | — | 「加载更多」配置(底部按钮 + loading) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem | `(item: T, index: number) => ReactNode` | 渲染函数——渲染每一项；建议返回 `<ListItem>`。不传则把 item 当 ReactNode 直接渲染 |
| children | `ReactNode` | 组合模式：直接放 `<ListItem>` 子元素(与 `items` 二选一，`items` 优先) |
| header | `ReactNode` | 头部插槽 |
| footer | `ReactNode` | 底部插槽(渲染在最底部) |
| empty | `ReactNode` | 空态内容(不传用内置 `<Empty>`) |
| pagination | `ReactNode` | 分页槽(放 `<Pagination>`)，渲染在列表下方 |

`ListGridConfig`：`cols`(默认 3) / `gap`(默认 4，×0.25rem) / `colGap` / `rowGap` / `rows`
`ListLoadMore`：`onLoadMore*` / `loading` / `hasMore`(默认 true，false 时不渲染按钮) / `text`(默认 "加载更多")

`ListItemProps`：`actions?: ReactNode[]`(行右侧操作区，多项间自动加分隔线) / `children`
`ListItemMetaProps`：`avatar` / `title` / `description`

## 示例
```tsx
<List
  bordered
  items={people}
  renderItem={(p) => (
    <ListItem actions={[<Button key="e" variant="ghost" size="sm">编辑</Button>]}>
      <ListItem.Meta avatar={<Avatar fallback={p.initials} />} title={p.name} description={p.role} />
    </ListItem>
  )}
  header={<span>团队成员</span>}
/>

// 卡片栅格态
<List grid={{ cols: 2, gap: 4 }} items={people}
  renderItem={(p) => <ListItem>…</ListItem>} />
```

## 禁忌 / 坑

- `items` 与 `children` 二选一，同时给则 `items` 优先；数据驱动用 `items + renderItem`，静态布局直接放 `<ListItem>` children。
- `grid` 态下 `bordered` / `split` 被忽略(边框由卡片自带)。
- `ListLoadMore.hasMore=false` 时整个加载更多按钮不渲染，别等它消失才发现没传完。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# LiveChat

> 直播公屏 · 高频自动滚消息流 + message/enter(进场)/gift(送礼)/follow(关注)/system(系统)五类型默认皮肤 + 等级牌/身份徽标 + 置顶区 + 上滚查看历史时浮出「N 条新消息」恢复钮(贴底判定) + maxItems 窗口限流 + renderItem 逃生舱 + overlay 浅色态(叠加深色视频上白字) · 区别 AI 轮次制 Conversation · data-display/collection

## 何时用

直播间公屏：高频追加多类型消息（发言/进场/送礼/关注/系统公告）并自动贴底滚动。需要叠在视频上时开 `overlay`。本组件是单向广播式滚动流；要 AI 多轮问答用 [Conversation](https://hulianui.haloritual.com/components/conversation)，要纯日志着色用 [LogViewer](https://hulianui.haloritual.com/components/log-viewer)。

## 导入
```ts
import { LiveChat } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `LiveChatItem[]` | — | 消息流（受控，追加） |
| pinned | `LiveChatItem[]` | — | 顶部置顶区（公告/规则） |
| autoScroll | `boolean` | `true` | 自动滚到底；用户上滚时暂停并浮出「N 条新消息」恢复钮 |
| maxItems | `number` | `200` | 滚动窗保留上限（性能） |
| overlay | `boolean` | `false` | 叠在深色视频上的浅色态（文字改白/半透白 + 文字阴影） |
| className | `string` | — | 容器自定义类 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem | `(item: LiveChatItem) => ReactNode` | 渲染函数：自定义单条消息渲染（逃生舱） |

`LiveChatItem`：`{ id: string; type: "message"｜"enter"｜"gift"｜"follow"｜"system"; user?: LiveChatUser; text?: ReactNode; gift?: { name; icon?; combo? }; at?: string }`。
`LiveChatUser`：`{ name: string; avatar?: string; level?: number; badge?: ReactNode }`（`level` 渲染等级牌，`badge` 渲染房管/铁粉等身份徽标）。

## 示例
```tsx
<LiveChat
  items={items}
  pinned={[{ id: "p1", type: "system", text: "今晚 8 点抽奖，关注不迷路" }]}
  className="h-full"
/>
```

不同 `type` 自动套对应皮肤：
```tsx
const item: LiveChatItem =
  r === 0 ? { id, type: "enter", user: { name } }
  : r === 3 ? { id, type: "gift", user: { name }, gift: { name: "小心心", icon: "💖", combo: 3 } }
  : { id, type: "message", user: { name, level: 12 }, text: "求链接" };
```

## 禁忌 / 坑

- 自动贴底依赖「当前是否贴底」判定：用户上滚查看历史时 `autoScroll` 暂停，浮出「N 条新消息」钮，点它才恢复贴底——不要在外部强行 scrollTo 干扰。
- `items` 须给容器固定高度（如 `className="h-full"` + 父容器定高），否则滚动区无法形成。
- 高频追加时靠 `maxItems` 截断窗口；不要把全量历史塞进 `items`。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# LivePlayer

> 直播播放器壳 · 自带极简 muted/loop/autoPlay video(非 VOD scrubber chrome·与 Video 互补) 或 surface 自定义画面 + LIVE 呼吸徽标(ping 红点) + 在线人数(dogfood NumberTicker 跳数) + 清晰度切换菜单 + 主播条(头像/名/关注钮) + overlay 弹幕飘心层与 footer 互动栏插槽 + 竖/横屏(9:16 / 16:9) · data-display/collection

## 何时用

直播间播放器外壳：极简无进度条 chrome + LIVE 徽标/在线数/清晰度/主播条/弹幕飘心层/互动栏。要带进度条拖拽的点播播放器用 [Video](https://hulianui.haloritual.com/components/video)；本组件专为「直播」语义（无 scrubber、强调 LIVE 与互动叠层）。`overlay` 常配 [Danmaku](https://hulianui.haloritual.com/components/danmaku)，footer 常配互动栏。

## 导入
```ts
import { LivePlayer } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| src | `string` | — | 本地视频源（内部固定 muted/loop/autoPlay/playsInline） |
| poster | `string` | — | 视频封面 |
| live | `boolean` | `true` | 显示 LIVE 呼吸徽标 |
| viewers | `number` | — | 在线人数（NumberTicker 跳数） |
| qualities | `string[]` | — | 清晰度档位列表 |
| quality | `string` | — | 当前清晰度（受控） |
| host | `LivePlayerHost` | — | 顶部主播条 |
| orientation | `"portrait" \| "landscape"` | `"landscape"` | 朝向 |
| aspectRatio | `string` | — | CSS aspect-ratio；不传按 orientation（landscape=16/9，portrait=9/16），传 `"fill"` 则不锁比例铺满父容器 |
| className | `string` | — | 容器自定义类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onQualityChange | `(q: string) => void` | 切换清晰度回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| surface | `ReactNode` | 自定义画面（程序化场景等）；存在时优先于 `src` |
| overlay | `ReactNode` | 画面之上、操作条之下的覆盖层（弹幕/飘心/礼物） |
| footer | `ReactNode` | 底部互动栏插槽 |

`LivePlayerHost`：`{ name: string; avatar?: string; followed?: boolean; onFollow?: () => void; meta?: ReactNode }`（不传 `onFollow` 则不显示关注钮）。

## 示例
```tsx
<LivePlayer
  src="/stream.mp4"
  viewers={12840}
  qualities={["蓝光", "超清", "高清"]}
  quality={quality}
  onQualityChange={setQuality}
  host={{ name: "主播阿楠", meta: "粉丝 28.6w", followed, onFollow: () => setFollowed(true) }}
  overlay={<Danmaku items={items} />}
  footer={<InteractionBar />}
/>
```

## 禁忌 / 坑

- `quality` 是受控的：传了 `quality` 就必须配 `onQualityChange` 回写，否则菜单选了不变。
- 关注钮以 `host.onFollow` 是否存在决定显隐——纯展示场景不传即可隐藏。
- `surface` 优先于 `src`：两者都传时只渲染 `surface`（用于程序化/Canvas 画面）。
- 内置 `<video>` 固定 muted/autoPlay/loop/playsInline，不暴露播放控制；要进度条/音量等点播 chrome 请改用 Video。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# LiveProductCard

> 小黄车讲解卡 · 序号链接角标 + 现价/划线原价 + 讲解中脉冲徽标 + 库存/已售 + 秒杀限量角标 + 抢购按钮插槽 + row 列表行/card 网格卡两布局(直播带货标配·只消费 token·区别通用 Card) · data-display/info

## 何时用

直播带货「小黄车」商品卡：序号链接、现价/划线原价、讲解中脉冲、库存已售、秒杀角标、抢购钮。中控弹层列表用 `layout="row"`，商品橱窗网格用 `layout="card"`。本组件是带货专用皮肤；要通用容器卡片用 [Card]，要价目对比用 [PricingTable](https://hulianui.haloritual.com/components/pricing-table)。

## 导入
```ts
import { LiveProductCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| image* | `string` | — | 商品图 URL |
| price* | `number` | — | 现价（秒杀价） |
| index | `number` | — | 第 N 号链接徽标 |
| originalPrice | `number` | — | 划线原价 |
| explaining | `boolean` | — | 「讲解中」脉冲徽标 |
| stock | `number` | — | 剩余库存 |
| sold | `number` | — | 已售数 |
| currency | `string` | `"¥"` | 货币符号 |
| layout | `"row" \| "card"` | `"row"` | 布局：row=列表行（中控/弹层），card=网格卡 |
| className | `string` | — | 自定义类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `() => void` | 点击回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 商品标题 |
| tag | `ReactNode` | 角标，如「秒杀」「限量」 |
| action | `ReactNode` | 抢购按钮（调用方传 Button 等） |

## 示例
```tsx
<LiveProductCard
  index={1}
  image={url}
  title="冬季加厚羊羔绒外套 直播专享"
  price={129}
  originalPrice={399}
  explaining
  tag="秒杀"
  stock={86}
  sold={1240}
  action={<Button tone="danger">去抢购</Button>}
/>
```

网格卡布局：
```tsx
<LiveProductCard layout="card" index={3} image={url} title="无线蓝牙耳机" price={199} originalPrice={499} tag="限量" sold={920} action={Buy} />
```

## 禁忌 / 坑

- `action` 是插槽，组件不内置按钮——抢购钮由调用方传入（Button 等），便于挂自己的下单逻辑。
- 划线原价仅在 `originalPrice` 存在时渲染；`currency` 同时作用于现价与原价。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# LogoLoop

> 无缝无限滚动的 logo 跑马灯 · RAF 速度低通平滑 + 序列复制无缝回卷 · 横纵四向/悬停变速暂停/单项放大/两端渐隐(零依赖·token·reduced-motion) · data-display/collection · #animated

## 何时用

「合作伙伴 / 集成 / 技术栈 logo 墙」这种需要无限滚动跑马灯展示一排徽标时用。它只负责无缝滚动一组 logo；如果是结构化数据列表/表格，用 [Table](https://hulianui.haloritual.com/components/table)/[ProTable](https://hulianui.haloritual.com/components/pro-table)；要纯展示价格矩阵用 [PricingTable](https://hulianui.haloritual.com/components/pricing-table)。

## 导入
```ts
import { LogoLoop } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| logos * | `LogoItem[]` | — | logo 列表，可混用图片型(`{src,...}`)与节点型(`{node,...}`)；复制整序列实现无限滚动 |
| speed | `number` | `120` | 滚动速度（px/s），负值反转方向 |
| direction | `"left" \| "right" \| "up" \| "down"` | `"left"` | 滚动方向，up/down 为纵向 |
| width | `number \| string` | `"100%"` | 容器宽度，数字按 px、字符串原样 |
| logoHeight | `number` | `28` | 单个 logo 高度（px） |
| gap | `number` | `32` | logo 之间间距（px） |
| pauseOnHover | `boolean` | `undefined`（等价 true） | 悬停是否暂停（速度归零）；与 hoverSpeed 共存时以 hoverSpeed 优先 |
| hoverSpeed | `number` | — | 悬停时目标速度（px/s），可做减速而非全停 |
| fadeOut | `boolean` | `false` | 两端是否加渐隐遮罩（吃 bg-surface token，自动明暗适配） |
| fadeOutColor | `string` | `var(--color-surface)` | 渐隐遮罩颜色，可传任意 CSS 颜色覆盖 |
| scaleOnHover | `boolean` | `false` | 悬停是否放大单个 logo（scale 1.2） |
| ariaLabel | `string` | `"合作伙伴 logo"` | 根容器无障碍标签 |
| className | `string` | — | 透传根容器额外类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

> `LogoItem` 二选一：图片型 `{ src, srcSet?, sizes?, width?, height?, alt?, title?, href? }` 或节点型 `{ node, ariaLabel?, title?, href? }`；带 `href` 时整项包裹为链接。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem | `(item: LogoItem, index: number) => ReactNode` | 渲染函数：自定义渲染单项，覆盖默认图片/节点逻辑 |

## 示例
```tsx
const logos = [
  { node: <HexagonIcon />, ariaLabel: "Hexagon" },
  { node: <CloudIcon />, ariaLabel: "Cloud" },
];

// 默认向左 + 两端渐隐
<LogoLoop logos={logos} fadeOut />

// 向右 + 悬停暂停并放大
<LogoLoop logos={logos} direction="right" fadeOut pauseOnHover scaleOnHover />
```

## 禁忌 / 坑

- 纵向滚动（`direction="up"/"down"`）需要父容器有明确高度，否则没有滚动空间。
- 图片型 `LogoItem` 的 `alt` 缺省退化为空串，作为有意义内容时记得补 alt 以保无障碍。
- `pauseOnHover` 与 `hoverSpeed` 同时给时以 `hoverSpeed` 为准（不会全停而是切到该速度）。
- reduced-motion 下自动停止滚动。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# LogViewer

> 日志查看器 · 数据驱动行 lines(level/message/timestamp/source) + info/warn/error/debug/success 级别着色(纯函数 levelClass 可测) + autoScroll 新行贴底(复用 Conversation 法) + showTimestamp + wrap 折行/横滚 · 区别 Terminal mockup·真·流式输出 · data-display/collection

## 何时用

渲染结构化日志行（构建/CI/运行时流式输出）：按 level 着色、可选时间戳、新行自动贴底。本组件是数据驱动的真日志列表；要纯装饰性终端外壳（打字机动画演示）用 Terminal mockup；要 AI 对话用 [Conversation](https://hulianui.haloritual.com/components/conversation)。

## 导入
```ts
import { LogViewer, levelClass } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| lines* | `LogLine[]` | — | 日志行（数据驱动） |
| showTimestamp | `boolean` | `false` | 显示每行时间戳（渲染在行首） |
| autoScroll | `boolean` | `true` | 新行自动贴底（流式日志刚需） |
| wrap | `boolean` | `false` | 长行折行；false 时长行横向滚动 |
| height | `number \| string` | `320` | 滚动区高度 |
| className | `string` | — | 自定义类 |

`LogLine`：`{ level?: LogLevel; message: ReactNode; timestamp?: string; source?: string }`。
`LogLevel`：`"info"｜"warn"｜"error"｜"debug"｜"success"｜"command"`（默认 `info`；`command` 高亮被执行的命令/提示符行；`source` 如 `"[build]"` 弱化渲染在 message 前）。

## 示例
```tsx
<LogViewer
  lines={[
    { level: "command", timestamp: "12:00:01", message: "▸ npm run build" },
    { level: "warn", timestamp: "12:00:05", source: "[ts]", message: "unused var 'x'" },
    { level: "error", timestamp: "12:00:10", source: "[lint]", message: "2 problems" },
    { level: "success", timestamp: "12:00:09", message: "✓ compiled in 8.1s" },
  ]}
  showTimestamp
  height={220}
/>
```

流式追加只需不断换新 `lines`，组件负责贴底：
```tsx
<LogViewer lines={STREAM.slice(0, n)} showTimestamp height={220} />
```

## 禁忌 / 坑

- 流式运行逻辑（计时/追加）留在消费侧，组件只负责按 `lines` 渲染并贴底——不要期待它自己产生日志。
- `autoScroll` 默认开；用户手动上滚查看历史时仍会被新行拉回底部，需要保留滚动位置的场景请自行关掉。
- `wrap=false`（默认）时超长行横向滚动而非折行；窄容器读全文须开 `wrap`。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# MagicBento

> 魔法便当卡片网格 · 光标跟随径向聚光 + 描边光呼吸 + 可选 3D 倾斜(零依赖·token·reduced-motion) · data-display/collection · #animated

## 何时用

落地页/控制台首屏要一组大小不一、带光标聚光高光的特性卡网格（bento 布局）时用。要的是"成组网格 + 聚光/描边光"用本组件；只对**单张**卡做指针 3D 倾斜用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)，要悬停像素波纹用 [PixelCard](https://hulianui.haloritual.com/components/pixel-card)。

## 导入
```ts
import { MagicBento } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `MagicBentoItem[]` | 内置示例 | 卡片数据数组，不传时渲染一组内置示例卡 |
| columns | `number` | `4` | 网格列数（grid-template-columns 份数），各卡再用 colSpan/rowSpan 跨格 |
| glowColor | `string` | `var(--color-primary)` | 发光主色，喂给径向光晕/描边光；须用带 `--color-` 前缀的 token（裸 `var(--primary)` 不解析） |
| spotlightRadius | `number` | `280` | 聚光半径（px），越大光斑越大越柔 |
| enableSpotlight | `boolean` | `true` | 是否开启跟随光标的径向聚光 |
| enableBorderGlow | `boolean` | `true` | 是否开启描边光（边框随光标接近点亮） |
| enableTilt | `boolean` | `false` | 是否开启 3D 倾斜（卡片随光标轻微 tilt） |
| disableAnimations | `boolean` | `false` | 强制关闭所有动画/交互（等价 reduced-motion）；组件也自动尊重系统 prefers-reduced-motion |
| className | `string` | — | 透传到根网格容器的额外 className |
| style | `CSSProperties` | — | 透传到根网格容器的内联样式 |

`MagicBentoItem`：`{ label?, title?, description?: ReactNode; children?: ReactNode; colSpan?: number; rowSpan?: number }` —— 传 `children` 即覆盖 label/title/description 默认布局，自定义卡内结构。

## 示例
```tsx
const items = [
  { label: "Insights", title: "数据洞察", description: "追踪用户行为与漏斗", colSpan: 2 },
  { label: "Overview", title: "总览面板", description: "集中式数据视图" },
  { label: "Teamwork", title: "团队协作", description: "无缝实时协同" },
];

<MagicBento items={items} />

// 自定义发光色（须 --color- 前缀）+ 大聚光
<MagicBento items={items} glowColor="var(--color-chart-2)" spotlightRadius={420} />
```

## 禁忌 / 坑

- [[hulian-token-color-var-needs-color-prefix]]：`glowColor` 必须用 `var(--color-primary)` / `var(--color-chart-2)` 这类带 `--color-` 前缀的真名，裸 `var(--primary)` 在 Tailwind v4 下不解析、光晕变黑或不显。
- `colSpan`/`rowSpan` 受 `columns` 约束，单卡 colSpan 大于 columns 会溢出错位。
- 纯交互动效，无 WebGL；reduced-motion 或 `disableAnimations` 下退化为静态网格。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# MagicCard

> 魔法卡片 · 鼠标跟随径向高光(motion) + surface token · data-display/collection · #animated

## 何时用

给单张卡片加鼠标跟随的径向高光，用于落地页/特性墙里需要一点交互质感的容器。要一组错落特性卡片用 [BentoGrid](https://hulianui.haloritual.com/components/bento-grid)；要静态信息卡片直接用普通 Card 即可，不必引入这个带运动监听的组件。

## 导入
```ts
import { MagicCard } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gradientSize | number | 200 | 高光半径（px） |
| gradientColor | string | `var(--color-primary)` | 高光色 |
| gradientOpacity | number | 0.15 | 高光不透明度 |
| ...div | ComponentPropsWithoutRef\<"div"\> | — | 透传（`className` 控尺寸） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | ReactNode | 卡片内容 |

## 示例
```tsx
<MagicCard className="h-44 w-72">
  <div className="flex h-full flex-col items-center justify-center gap-1 p-6">
    <span className="text-lg font-semibold text-foreground">Magic Card</span>
    <span className="text-sm text-muted">把鼠标移上来看高光</span>
  </div>
</MagicCard>
```

## 禁忌 / 坑

- 依赖鼠标 `pointermove`（motion 驱动），是客户端组件——在纯触屏/无指针环境高光不会触发，仅作渐进增强。
- 高光色默认 `var(--color-primary)`；若自定义 `gradientColor` 走裸 `var(...)`，注意瑚琏色彩 token 须带 `--color-` 前缀才解析（[[hulian-token-color-var-needs-color-prefix]]）。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Marquee

> 跑马灯 · 纯 CSS 无缝循环 + hover 暂停 + 方向 · data-display/collection · #animated

## 何时用

纯 CSS 无缝循环滚动一排内容（logo 墙、技术栈 chip、口碑条），支持横/竖向、渐隐遮罩、hover 暂停。要进入视口逐项淡入的列表用 [AnimatedList](https://hulianui.haloritual.com/components/animated-list)；要用户能拖拽改顺序用 [Sortable](https://hulianui.haloritual.com/components/sortable)。

## 导入
```ts
import { Marquee } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| direction | `"left"｜"right"` | `"left"` | 滚动方向；`"right"` 经 `animation-direction: reverse` |
| duration | number | 40 | 单轮时长（秒），越大越慢 |
| gap | string | `"1rem"` | 子项间距（CSS 长度） |
| pauseOnHover | boolean | false | 鼠标悬停暂停 |
| repeat | number | 4 | 子项复制份数（窄内容也铺满不露缝） |
| vertical | boolean | false | 竖向滚动；竖向时 `direction="left"` 视为向上、`"right"` 向下 |
| fade | boolean | false | 两端渐隐遮罩（mask-image），适合 logo/图标墙 |
| fadeWidth | string | `"15%"` | 渐隐区宽度（CSS 长度），仅 `fade` 为真时生效 |
| ...div | ComponentPropsWithoutRef\<"div"\> | — | 透传（`className` 控宽/高） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children * | ReactNode | 滚动子项 |

> 注：showcase controls 里 `duration` 默认演示值为 20、`pauseOnHover`/`fade` 默认演示为 true，仅展示用；组件实际默认值以上表（接口 JSDoc）为准。

## 示例
```tsx
// 横向 · hover 暂停
<Marquee className="w-80" pauseOnHover>
  {items.map((c) => <Chip key={c}>{c}</Chip>)}
</Marquee>

// 图标墙 · 渐隐
<Marquee className="w-80" fade pauseOnHover gap="1.25rem">
  {logos.map((Icon, i) => <LogoTile key={i}><Icon className="size-6" /></LogoTile>)}
</Marquee>

// 竖向
<Marquee className="h-56" vertical fade pauseOnHover>
  {items.map((c) => <Chip key={c}>{c}</Chip>)}
</Marquee>
```

## 禁忌 / 坑

- 横向给外壳定宽（`w-*`）、竖向给定高（`h-*`），否则无可视窗口、循环看不出来。
- 子项过窄时靠 `repeat` 复制铺满才无缝；内容本身很少时调大 `repeat` 防止露缝。
- 纯 CSS 动画，无运行时；`fadeWidth` 只在 `fade` 开启时才生效。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Meter

> 度量条 · Base UI role=meter(静态量占比，区别 Progress) · data-display/stat

## 何时用

展示一个**静态量在区间内的占比**（磁盘用量、电量、配额）。区别于 Progress：Progress 表达「任务推进进度（会动）」，Meter 表达「此刻某个量占满量的多少」。语义上是 `role="meter"`。

## 导入
```ts
import { Meter } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `number` | — | 当前值 |
| min | `number` | `0` | 下限 |
| max | `number` | `100` | 上限 |
| showValue | `boolean` | `false` | 是否显示格式化数值 |
| className | `string` | — | 透传类名（宽度在此设，如 `w-64`） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 可选标签（如「磁盘用量」） |

## 示例
```tsx
// 带标签 + 数值
<div className="w-64"><Meter value={72} label="磁盘用量" showValue /></div>

// 仅条
<div className="w-64"><Meter value={64} /></div>
```

## 禁忌 / 坑
暂无已知坑。表达「会推进的任务进度」请用 Progress 而非 Meter；条宽由父容器决定，记得给宽度。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Statistic](https://hulianui.haloritual.com/components/statistic) · [Chart](https://hulianui.haloritual.com/components/chart) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# NumberTicker

> 数字滚动 · 进入视口 tween 到目标值 + reduced-motion · data-display/stat · #animated

## 何时用

需要把一个数字以动效从起点滚到目标值（KPI 大屏、统计卡进场）时用。只渲染纯数字动画，没有标签/趋势箭头/前后缀语义——要带「标题 + 单位 + 同比」用 [Stat](https://hulianui.haloritual.com/components/stat)，要带 CountUp 之外的格式化与趋势用 [Statistic](https://hulianui.haloritual.com/components/statistic)。

## 导入
```ts
import { NumberTicker, formatTicker } from "@hulianui/ui"
```

## Props

继承 `span` 的所有原生属性（`children` 除外）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `number` | — | 目标值。进入视口后从 `startValue` 滚到此值 |
| startValue | `number` | `0` | 起始值。`startValue > value` 即自然向下滚（无需单独 direction prop） |
| decimalPlaces | `number` | `0` | 小数位，驱动 `Intl.NumberFormat` 的 min/maxFractionDigits |
| duration | `number` | `1.2` | 滚动时长（秒），曲线固定复用 `motionEase.out`（瑚琏签名） |
| delay | `number` | `0` | 进入视口后延迟开始（秒） |

## 示例
```tsx
// 整数千分位
<NumberTicker value={12345} className="text-4xl font-semibold" />

// 百分比（1 位小数）
<NumberTicker value={99.9} decimalPlaces={1} className="text-4xl font-semibold" />

// 向下计数
<NumberTicker startValue={100} value={0} className="text-4xl font-semibold" />
```

## 禁忌 / 坑

- 动画由 IntersectionObserver 触发、rAF 驱动 tween。headless 截图会停在第 0 帧（只显示起始值），不是 bug——验证视觉用真机或开 reduced-motion 直出终值。参见 [[verify-sub-second-web-animation-via-headless-screenshot]]。
- `prefers-reduced-motion: reduce` 下直接显示终值不做滚动，无障碍友好。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Statistic](https://hulianui.haloritual.com/components/statistic) · [Chart](https://hulianui.haloritual.com/components/chart) · [Meter](https://hulianui.haloritual.com/components/meter) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# PixelCard

> canvas2d 像素卡片 · 悬停/聚焦时像素自中心波纹生长+闪烁、离开收缩消散 · 4 变体/可定制 gap·speed·colors(零依赖 RAF·token 配色·reduced-motion 静止) · data-display/collection · #animated

## 何时用

给卡片加"悬停时像素自中心波纹生长"的复古/科技感装饰背景时用，内容叠在像素层之上。要的是**像素动画背景**用本组件；要指针 3D 倾斜用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)，要光标聚光网格用 [MagicBento](https://hulianui.haloritual.com/components/magic-bento)。

## 导入
```ts
import { PixelCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"default" \| "blue" \| "pink" \| "amber"` | `"default"` | 预设变体，决定默认 gap/speed/colors/noFocus 组合（default 中性灰白 / blue chart-2 / pink chart-5 默认关焦点 / amber chart-3 暖橙更密）。单独传下方 prop 可覆盖对应项 |
| gap | `number` | 变体默认 | 像素网格间距（px），越小越密数量越多（性能开销越大），建议 3–12 |
| speed | `number` | 变体默认 | 动画速度（0–100 整数标度），0 等价禁用动画 |
| colors | `string[]` | 变体默认（token） | 像素配色数组，每像素随机取一；默认取瑚琏 token，可传任意 CSS 颜色 |
| noFocus | `boolean` | 变体默认 | true 时仅鼠标悬停触发、根容器不可聚焦（禁键盘焦点触发） |
| className | `string` | — | 透传到根容器的额外 className（控尺寸/圆角/边框） |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在像素层上方的内容（relative 层叠在 canvas 背景之上） |

## 示例
```tsx
// 用 className 给容器定尺寸；children 叠在像素背景上
<PixelCard variant="blue" className="h-48 w-64">
  <div className="flex flex-col items-center gap-1 px-6 text-center">
    <p className="text-base font-semibold text-foreground">Pixel Card</p>
    <p className="text-xs text-muted">悬停 / 聚焦触发像素动画</p>
  </div>
</PixelCard>

// 自定义配色 + 慢速（覆盖变体默认）
<PixelCard colors={["var(--color-chart-5)", "var(--color-chart-1)"]} gap={5} speed={18} className="h-48 w-64" />
```

## 禁忌 / 坑

- **尺寸靠 `className`/`style` 给**（如 `h-48 w-64`），不给尺寸 canvas 为 0 不可见。
- `gap` 越小像素越多、RAF 重绘开销越大，大卡片配小 gap 易掉帧；按需折中。
- [[hulian-token-color-var-needs-color-prefix]]：`colors` 用 token 时须带 `--color-` 前缀（`var(--color-chart-2)`），裸 `var(--chart-2)` 在 canvas fillStyle 下不解析。
- canvas2d 动画，reduced-motion 下静止（不波纹）；`speed=0` 同样禁用动画。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# PricingTable

> 定价对比矩阵 · 行列转置(列=被比项/模型·行=属性/价目) + 列高亮描边 + 角标(推荐/最佳性价比) + 表头吸顶 + 窄屏横滚(复用 ScrollArea·区别 Table 行=记录·模型市场定价对照刚需) · data-display/collection

## 何时用

横向对比若干「被比项」的属性矩阵——典型如模型/套餐定价对照（列 = 模型，行 = 输入价/上下文/视觉…），可高亮某列并打「推荐」角标。与 [Table](https://hulianui.haloritual.com/components/table) 的本质区别：Table 一行 = 一条记录、纵向罗列；PricingTable 行列转置、列才是主体，专做对比。

## 导入
```ts
import { PricingTable } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| columns* | `PricingColumn[]` | — | 被比项列定义 |
| rows* | `PricingRow[]` | — | 属性/价目行定义 |
| stickyHeader | `boolean` | `true` | 表头吸顶 |
| className | `string` | — | 根节点类名 |

`PricingColumn`：`key*`（与 row.values 的键对应）、`title*`（列标题）、`highlight?`（高亮列：描边 + 角标位）、`badge?`（高亮角标如「推荐」）、`header?`（列头富内容，提供则替换 title 区）。
`PricingRow`：`key*`、`label*`（首列属性名）、`values: Record<string, ReactNode>`（各列单元格，键为 column.key）。

## 示例
```tsx
const columns: PricingColumn[] = [
  { key: "gpt", title: "GPT-5.5" },
  { key: "opus", title: "Claude Opus 4.7", highlight: true, badge: "推荐" },
  { key: "deepseek", title: "DeepSeek V4" },
];

const rows: PricingRow[] = [
  { key: "in",  label: "输入价 / 1M", values: { gpt: "$5.00",  opus: "$5.00",  deepseek: "$0.55" } },
  { key: "out", label: "输出价 / 1M", values: { gpt: "$30.00", opus: "$25.00", deepseek: "$2.20" } },
  { key: "ctx", label: "上下文窗口",  values: { gpt: "256K",   opus: "200K",   deepseek: "128K" } },
];

<PricingTable columns={columns} rows={rows} />
```

## 禁忌 / 坑

- `row.values` 的键必须与 `column.key` 一一对应，缺键的格子会空——新增列记得同步补全所有行的 values。
- 高亮角标位由 `highlight: true` 撑出，`badge` 只在 highlight 列上有意义。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# ProfileCard

> 指针倾斜 + 全息炫彩名片卡 · RAF 阻尼弹簧驱动 3D 旋转/光晕（零依赖）+ chart token 全息渐变 + 无头像落首字母占位（reduced-motion 静态降级） · data-display/collection · #animated

## 何时用

做个人/成员名片（作品集、团队页、社交卡）且要全息炫彩+指针倾斜的高级感时用。本组件是**有结构语义的名片**（姓名/职位/handle/状态/联系按钮 + 底部毛玻璃信息条）；只要一张通用图片做指针倾斜用 [TiltedCard](https://hulianui.haloritual.com/components/tilted-card)，要悬停像素动画卡用 [PixelCard](https://hulianui.haloritual.com/components/pixel-card)。

## 导入
```ts
import { ProfileCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| avatarUrl | `string` | — | 头像地址，未提供时回退为姓名首字母占位块（不引外链） |
| name | `string` | `"瑚琏"` | 姓名，底部主标题；无头像时据此生成首字母占位 |
| title | `string` | `"前端工程师"` | 职位/副标题，姓名下方 |
| handle | `string` | `"hulianui"` | 用户 handle（@xxx），底部信息条左侧 |
| status | `string` | `"在线"` | 状态文案，handle 下方 |
| contactText | `string` | `"联系"` | 联系按钮文案 |
| showUserInfo | `boolean` | `true` | 是否显示底部毛玻璃信息条（handle/状态/联系按钮） |
| enableTilt | `boolean` | `true` | 是否开启指针倾斜 + 全息光泽；关闭后为静态卡；reduced-motion 自动降级静态 |
| glowColor | `string` | `var(--color-chart-1)` | 全息高光主色，须用带 `--color-` 前缀的 token，也可传任意 CSS 颜色 |
| aspectRatio | `number` | `0.74` | 卡片宽高比（width/height），默认接近实体卡 |
| className | `string` | — | 透传到根容器的额外 className |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onContactClick | `() => void` | 点击联系按钮回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 自定义卡片正面叠加内容（头像层之上、信息条之下） |

## 示例
```tsx
// 最小用法：无头像自动落首字母占位
<ProfileCard name="林屿" title="独立开发者" handle="linyu" />

// 自定义光晕 + 状态 + 联系回调
<ProfileCard
  name="苏晚"
  title="产品设计师"
  handle="suwan"
  status="忙碌"
  glowColor="var(--color-chart-3)"
  onContactClick={() => router.push("/contact")}
/>
```

## 禁忌 / 坑

- [[hulian-token-color-var-needs-color-prefix]]：`glowColor` 须用 `var(--color-chart-1)` 等带 `--color-` 前缀的真名，裸 `var(--chart-1)` / `var(--primary)` 在 Tailwind v4 下不解析、全息高光失色。
- 纯 RAF 弹簧零依赖，无 WebGL；`enableTilt={false}` 或 reduced-motion 下退化为静态卡（仍有渐变与信息条），不要依赖倾斜传递信息。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# ProTable

> 高级表格 · 列表页编排层(复用 Table/SearchForm/Pagination) · 查询区 + 工具栏(密度/列设置/刷新/全屏) + 行选择 + 集成分页(企业中后台列表页旗舰) · data-display/collection

## 何时用

企业中后台「一整个列表页」的旗舰组件：顶部查询区（SearchForm）+ 工具栏（密度/列设置/刷新/全屏）+ 主表（Table）+ 底部分页一套打包。只要列表 + 服务端分页/排序/筛选，优先用它。区别于 [Table](https://hulianui.haloritual.com/components/table)：Table 是裸表皮，要自己拼查询区、工具栏、分页、请求生命周期；ProTable 的「托管模式」（传 `request`）连这些都自管。

## 导入
```ts
import { ProTable } from "@hulianui/ui"
```

## Props

继承 `Omit<TableProps<TData>, "data">`（即 Table 的 columns/enableSorting/enableRowSelection/density/getRowId/rowClassName… 全可用），并新增：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data | `TData[]` | — | 展示模式必传；托管模式由 request 提供，忽略此项 |
| request | `(params: ProTableRequestParams) => Promise<ProTableRequestResult<TData>>` | — | 传则进「托管模式」：自管 page/pageSize/sort/filters/loading/data/选择，忽略 data/pagination/loading |
| paginationMode | `"page" \| "cursor"` | `"page"` | 托管分页协议：page=返回 `{data,total}` 数字分页；cursor=入参带 cursor、返回 `{data,nextCursor,hasMore}` 上下页 |
| defaultPageSize | `number` | `10` | 托管模式初始每页条数 |
| pageSizeOptions | `number[]` | — | 提供则渲染「每页条数」切换器（如 [10,20,50,100]） |
| pagination | `ProTablePagination` | — | 展示模式集成分页（底部）；`{page,pageSize,total,onPageChange,showFirstLast?,onPageSizeChange?}` |
| search | `Omit<SearchFormProps,"onSearch"> & { onSearch? }` | — | 集成查询区（复用 SearchForm）；托管模式下 onSearch 可省 |
| toolbar | `boolean \| ProTableToolbarFeatures` | `true` | true=全开 / false=不渲染 / 对象逐项开关（reload/density/columnSetting/fullscreen） |
| loading | `boolean` | — | 加载态：刷新图标旋转 |
| actionRef | `Ref<ProTableActions>` | — | 命令式句柄：`reload()` 重新请求 / `clearSelection()` 清选 |
| rootClassName | `string` | — | 外层容器类名（区别透传 Table 的 className） |

## Events

继承的 Table 事件（onSortingChange / onRowSelectionChange / onExpandedChange / onColumnFiltersChange）随 `Omit<TableProps,"data">` 一并可用。ProTable 自有：

| 事件 | 类型 | 说明 |
|------|------|------|
| onReload | `() => void` | 点工具栏刷新图标触发 |
| onRequestError | `(error: unknown) => void` | 托管 request 失败回调（默认 `console.error`）；失败时 loading 复位、保留上次数据 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 卡片标题（工具栏左侧） |
| toolbarActions | `ReactNode` | 工具栏右侧自定义操作（新增按钮等），位于内置图标按钮左侧 |
| batchActions | `(ctx: ProTableBatchCtx) => ReactNode` | 渲染函数；选中行时渲染批量操作区（需 enableRowSelection） |

## 示例
```tsx
// 展示模式：自己管数据 + 受控分页
<ProTable
  title="员工列表"
  columns={columns}
  data={pageData}
  enableRowSelection
  onReload={reload}
  toolbarActions={<Button size="sm">+ 新增</Button>}
  search={{ fields, onSearch, onReset }}
  pagination={{ page, pageSize, total, onPageChange: setPage }}
/>

// 托管模式：传 request，分页/排序/筛选/loading 全自管
<ProTable<Row>
  title="员工列表"
  columns={columns}
  request={async ({ page, pageSize, sort, filters }) => {
    const { rows, total } = await api.list({ page, pageSize, sort, filters });
    return { data: rows, total };
  }}
  getRowId={(r) => String(r.id)}
  search={{ fields: searchFields }}
  pageSizeOptions={[10, 20, 50]}
/>
```

## 禁忌 / 坑

- 托管模式（传 `request`）下 `data`/`pagination`/`loading` 三个 prop 被忽略——别两种模式混用。cursor 分页无 total/不能随机跳页，且 filters/sort/pageSize 任一变化会自动重置回第 1 页。
- 托管模式必须给 `getRowId`，否则行选择/批量在翻页后 key 不稳。
- `request` reject 默认走 `console.error` 兜底（保证不 unhandled），生产里接 `onRequestError` 弹 toast / 上报。
- `batchActions` 需配合 `enableRowSelection` 且有选中行才显示警示条。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# QRCode

> 二维码 · 编码内核 qrcode-generator + 瑚琏自渲 SVG(暗块合 path/crispEdges) + currentColor 吃主题 + UTF-8 中文 + 纠错级别 + 中心 logo(可 RSC) · data-display/info

## 何时用

把 URL/文本编码为可扫二维码（自渲 SVG，吃主题色，支持中文与中心 logo）。展示静态信息码用本组件；本批其余组件不涉及编码生成。

## 导入
```ts
import { QRCode } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `string` | — | 编码内容（URL/文本，UTF-8）。 |
| size | `number` | `160` | 边长 px。 |
| level | `"L" \| "M" \| "Q" \| "H"` | `"M"` | 纠错级别（带 logo 建议 H）。 |
| margin | `number` | `2` | 静默区模块数。 |
| color | `string` | `currentColor` | 暗块颜色（默认继承 text-foreground）。 |
| background | `string` | 透明 | 背景色。 |
| logo | `QRCodeLogo` | — | 中心 logo，`{ src: string; size?: number }`；务必配 `level="H"` 留足纠错冗余。 |
| aria-label | `string` | 取 value | 无障碍标签。 |
| className | `string` | — | — |

## 示例
```tsx
<QRCode value="https://hulian.dev" size={160} level="M" />
```
```tsx
// 吃主题主色（暗块用 text-primary）
<QRCode value="https://hulian.dev" size={140} className="text-primary" />
```

## 禁忌 / 坑

- 暗块默认 `currentColor`，靠外层文字色控制；要染色用 `className="text-primary"` 或显式 `color`，背景默认透明需自备底色保证扫码对比度。
- 加 `logo` 必须同时 `level="H"`，否则 logo 遮挡导致纠错冗余不足、扫不出。
- 中文/长文本会抬高二维码版本（更密），扫描距离与 size 要相应放大。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# QueueLane

> 优先级泳道队列板 · 横向泳道 + 道头聚合队列指标(深度/平均等待/吞吐) · 只读队列监视器(区别 Kanban 拖拽工作流·FIFO+aging) + maxVisible 折叠「还有 N 条」 + onItemClick · groupByLane 保序分组纯函数带单测 · 任务总线/优先级队列(零依赖) · data-display/collection

## 何时用

监视「按优先级/分类划分的多条有序队列」时用——任务总线、调度队列、按 P0-P3 排队。队列顺序由调度器决定（FIFO），用户不能拖拽改序；要人工拖拽改状态/改顺序的工作流看板用 Kanban。QueueLane 是只读监视器，胜在道头能聚合队列指标。

## 导入
```ts
import { QueueLane, groupByLane } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| lanes* | `QueueLaneDef[]` | — | 泳道定义，顺序即展示顺序。`{id, label, tone?, meta?}`；tone 为 CSS 颜色/token 变量，原样写入 inline style 不做枚举映射 |
| items* | `T[]` | — | 受控队列项数组，按 laneId 分组，道内顺序 = 数组原始顺序（FIFO）。每项须含 `{id, laneId}`；laneId 未命中任一 lane 则该项被丢弃 |
| maxVisible | `number` | — | 每道最多直显条数，超出折叠为「还有 N 条」。缺省不折叠（全显） |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 泳道排布方向。horizontal：泳道横向并列，每道竖向排队 |
| className | `string` | — | 外层类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onItemClick | `(item: T) => void` | 点击队列项回调（卡片只读，仅查看/下钻，不改队列顺序） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem* | `(item: T, index: number) => ReactNode` | 渲染函数：渲染单个队列项；index 为该项在所属道内的队列位次（0 = 队首） |
| renderLaneHeader | `(lane: QueueLaneDef, items: T[]) => ReactNode` | 渲染函数：自定义道头（拿该道队列做指标聚合）。缺省渲染 label + 条数 + lane.meta |

## 示例
```tsx
interface Job extends QueueItem { title: string; wait: string; executor: string }

const lanes: QueueLaneDef[] = [
  { id: "p0", label: "P0 紧急", tone: "var(--color-chart-3)", meta: "均等 0.4s" },
  { id: "p1", label: "P1 高", tone: "var(--color-chart-4)", meta: "均等 1.2s" },
];
const jobs: Job[] = [
  { id: "t1", laneId: "p0", title: "实时风控审批", wait: "0.2s", executor: "Sonnet 4.6" },
  { id: "t3", laneId: "p1", title: "工单意图分类", wait: "0.9s", executor: "Haiku 4.5" },
];

<QueueLane<Job>
  lanes={lanes}
  items={jobs}
  maxVisible={5}
  onItemClick={(job) => console.log(job.id)}
  renderItem={(job, index) => (
    <div>#{index + 1} {job.title} · 等 {job.wait}</div>
  )}
/>
```

## 禁忌 / 坑

- items 是受控、FIFO 顺序即数组顺序，组件本身不排序也不允许拖拽——排序/aging 逻辑在调用方完成后再喂进来。
- `item.laneId` 必须命中某条 lane.id，否则该项被静默丢弃（不报错）；新增 lane 时记得同步 laneId 映射。
- lane.tone 原样写入 inline style，可用任意 CSS 颜色；若用 token 变量须带 `--color-` 前缀，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# ReflectiveCard

> 金属反光证件卡 · 对角高光横扫 + 磨砂噪点 + 渐变发丝边框(纯 CSS 零依赖·token·RSC 安全·reduced-motion)，内容可插槽化 · data-display/collection · #animated

## 何时用

需要一张有金属质感、自带高光横扫动画的「证件卡 / 会员卡 / 名片」展示块时用，内置标题/副标题/卡头徽标/卡尾键值的证件版式，传 `children` 可整体替换为自定义内容。要做普通信息卡用 Card；要做定价对比表用 [PricingTable](https://hulianui.haloritual.com/components/pricing-table)；要做可翻页的书本展示用 [Book3D](https://hulianui.haloritual.com/components/book-3d)。

## 导入
```ts
import { ReflectiveCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sheenColor | `string` | `var(--color-foreground)` | 金属高光主色，喂反光层渐变，可传任意 CSS 颜色 |
| baseColor | `string` | `var(--color-chart-1)` | 卡片底色基调，决定金属表面暗部色 |
| speed | `number` | `6` | 高光横扫一轮时长（秒），越大越慢越细腻 |
| roughness | `number` | `0.35` | 表面噪点强度 0–1，0=镜面无颗粒，1=重磨砂 |
| metalness | `number` | `1` | 反光层整体不透明度 0–1，调低让卡面更内敛 |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 大字号主标题（人名/卡名），留空不渲染标题行 |
| subtitle | `ReactNode` | 标题下方小字说明（职位/等级） |
| badge | `ReactNode` | 卡头左侧徽标文案（默认配锁图标），传 `null` 隐藏整个卡头徽标区 |
| footerLabel | `ReactNode` | 卡尾左侧标注小灰字（如 "ID NUMBER"） |
| footerValue | `ReactNode` | 卡尾左侧的值（等宽字体，如 "8901-2345-6789"） |
| children | `ReactNode` | 自定义主体，传入后完全替换内置证件版式，仅保留反光背景层与边框 |

## 示例

```tsx
// 默认金属证件卡
<ReflectiveCard />

// 暖金色会员卡
<ReflectiveCard
  sheenColor="oklch(0.85 0.16 85)"
  baseColor="var(--color-chart-3)"
  title="JANE SMITH"
  subtitle="PLATINUM MEMBER"
  footerLabel="MEMBER NO."
  footerValue="0042-7781-1190"
/>
```

## 禁忌 / 坑

- 高光与噪点需在较暗背景上才看得清楚；放在浅色容器里效果会变弱，建议外层给暗底舞台。
- 传 `children` 后内置 `title/subtitle/badge/footerLabel/footerValue` 全部失效（仅保留背景与边框），二者不要混用。
- 颜色 token 务必带 `--color-` 前缀（如 `var(--color-chart-1)`），裸 `var(--primary)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# RelativeTime

> 相对时间 · 时间戳→「3分钟前/昨天/2个月后」+ 自动 tick 刷新(可设间隔/受控基准) + 中英 locale · 纯函数 formatRelative/formatAbsolute 可测 · <time> 语义 + title 绝对时间 + SSR 安全(suppressHydrationWarning) · data-display/info

## 何时用

把时间戳渲染为「3 分钟前 / 昨天 / 2 个月后」并自动随时间刷新，悬停看绝对时间。需要纯字符串格式化（非渲染）时直接用导出的 `formatRelative`/`formatAbsolute`。评论/动态流时间戳的标配。

## 导入
```ts
import { RelativeTime, formatRelative, formatAbsolute } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `Date \| string \| number` | — | 目标时间：Date / ISO 字符串 / 毫秒时间戳。 |
| base | `Date \| string \| number` | — | 参照的「现在」。传则固定不走实时 tick（SSR 确定性 / 测试 / 列表统一基准）；省略则取实时 `new Date()` 并按 updateInterval 刷新。 |
| updateInterval | `number` | `60000` | 自动刷新间隔(ms)，每分钟。设 0 关闭刷新。 |
| locale | `"zh" \| "en"` | `"zh"` | 语言。 |
| withTitle | `boolean` | `true` | 悬停 title 显示绝对时间。 |
| className | `string` | — | — |

## 示例
```tsx
// 实时刷新（无 base，每分钟自动更新，悬停看绝对时间）
<RelativeTime value={publishedAt} />
```
```tsx
// 列表/SSR 统一基准（固定 base，不漂移）
<RelativeTime value={item.createdAt} base={now} locale="en" />
```

## 禁忌 / 坑

- 不传 `base` = 走实时 tick（client 刷新）；要 SSR 确定性 / 测试可复现 / 列表统一基准就传固定 `base`，否则各行各自取 `new Date()` 抖动。
- 组件已用 `<time>` + `suppressHydrationWarning` 处理 SSR 水合差异，按需在 server 渲染无需额外包装。
- 大量同页实例默认每个都开 60s tick，超长列表可设 `updateInterval={0}` 或统一传 `base` 降低重渲染。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Sankey

> 桑基图(库内首个) · 多层流向/分配比例 · 零依赖 SVG ribbon · 拓扑自动分层(未给 layer 按 links 推) + 节点高度/流宽按 value 占比 + 跨层一致比例尺(值域守恒) · hover 高亮关联链路 tooltip + 点击节点/连线下钻 · 调度流向/流量来源/预算分配/转化路径旗舰 · data-display/collection

## 何时用

需要可视化「多层之间的流量分配/转化」时用——如任务调度流向、预算在能力域间的分摊、转化路径。要看单一漏斗各级的流失用 [PricingTable] 旁的 Funnel；只展示扁平表格数据用 [Table]/[ProTable]，Sankey 专门表达「跨层守恒的有向流」。

## 导入
```ts
import { Sankey, assignLayers, computeSankeyLayout } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes* | `SankeyNode[]` | — | 节点。`{id, label?, layer?, tone?}`；不给 layer 按 links 拓扑推导（source 层 < target 层）；tone 为 CSS 颜色或 token 变量如 `var(--color-chart-3)` |
| links* | `SankeyLink[]` | — | 连线。`{source, target, value, tone?}`；流宽按 value 占比 |
| height | `number` | `320` | 容器高 |
| nodeWidth | `number` | `16` | 节点矩形宽 |
| nodePadding | `number` | `12` | 同层节点间垂直间隔 |
| linkOpacity | `number` | `0.35` | ribbon 描边透明度（hover 提至 0.6） |
| className | `string` | — | 外层类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onNodeClick | `(node: SankeyLaidNode) => void` | 点击节点下钻 |
| onLinkClick | `(link: SankeyLaidLink) => void` | 点击连线下钻 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderNodeLabel | `(node: SankeyLaidNode) => ReactNode` | 渲染函数：自定义节点标签 |
| renderTooltip | `(item: {type:"node";node} \| {type:"link";link}) => ReactNode` | 渲染函数：自定义 hover tooltip |

## 示例
```tsx
const nodes: SankeyNode[] = [
  { id: "text", label: "文本生成", tone: "var(--color-chart-1)" },
  { id: "router", label: "智能路由器", tone: "var(--color-primary)" },
  { id: "haiku", label: "Haiku 池", tone: "var(--color-chart-4)" },
];
const links: SankeyLink[] = [
  { source: "text", target: "router", value: 42 },
  { source: "router", target: "haiku", value: 38 },
];

<Sankey
  nodes={nodes}
  links={links}
  height={300}
  renderTooltip={(item) =>
    item.type === "node" ? (
      <span>{item.node.label}</span>
    ) : (
      <span>{item.link.source} → {item.link.target}：{item.link.value}</span>
    )
  }
/>
```

## 禁忌 / 坑

- tone 喂给 SVG 的 fill/stroke 必须带 `--color-` 前缀（`var(--color-chart-3)`），裸 `var(--chart-3)`/`var(--primary)` 在 Tailwind v4 下不解析会渲染成黑色/无色，见 [[hulian-token-color-var-needs-color-prefix]]。
- nodes/links 受控：几何由纯函数 `computeSankeyLayout` 算出带坐标的 laid* 形态，`assignLayers` 负责拓扑分层；不要往里传环路 links（拓扑分层假设有向无环）。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Scheduler

> 事件日历/排班 · 库首个事件日历件 · 月/周/日/资源四视图(横轴资源·纵轴时间) + 时间轴网格事件块 + 重叠并排 + 当前时间红线 · 零依赖原生 PointerEvents 拖空白建预约/拖事件改期/拖下缘改时长(全 snap 到 slot) · 受控 events/view/date(onEventsChange/onSlotDragCreate/onEventClick) + 内置 toolbar(前/今/后 + Segmented 视图) + renderEvent 自定义事件块 · 几何抽纯函数带单测 · 预约/排班旗舰 · data-display/collection

## 何时用

需要可交互的「事件日历/排班台」时用——预约、诊室排班、资源时间线，支持拖空白建预约、拖事件改期、拖下缘改时长。只读展示项目工序排期用 Gantt（不可拖拽）；纯月历选日期用 Calendar/DatePicker。Scheduler 是带时间轴网格 + 拖拽编辑的旗舰排班件。

## 导入
```ts
import { Scheduler, dateOf, dayColumns, eventRect, hourLines, layoutColumns, minutesOfDay, minutesToISO, monthMatrix, resourceColumns, snap, startOfWeekISO, weekColumns, yToMinutes } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| events* | `SchedulerEvent[]` | — | 受控事件数组。`{id, title, start, end, resourceId?, tone?, subtitle?}`；start/end 为 ISO datetime（含时分，本地时区） |
| view* | `"month" \| "week" \| "day" \| "resource"` | — | 受控视图 |
| date* | `string` | — | 受控焦点日（ISO），决定哪周/哪天/哪月 |
| resources | `SchedulerResource[]` | — | resource 视图必填。`{id, title, subtitle?}` |
| dayStartHour | `number` | `8` | 时间轴起始小时 |
| dayEndHour | `number` | `20` | 时间轴结束小时 |
| slotMinutes | `number` | `30` | 吸附粒度（分钟） |
| hourHeight | `number` | `56` | 每小时像素高 |
| toolbar | `boolean` | `true` | 内置头部工具条（标题 + 前/今/后 + Segmented 视图） |
| className | `string` | — | 外层类名（须有确定高度，组件填满时间轴可滚） |

SchedulerEvent.tone：`"primary" \| "success" \| "warning" \| "danger" \| "neutral"`，默认 primary（仅用已定义语义 token）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onViewChange | `(v: SchedulerView) => void` | 视图切换（内置 toolbar Segmented） |
| onDateChange | `(iso: string) => void` | 焦点日切换（前/今/后、点月视图某天） |
| onEventsChange | `(events: SchedulerEvent[]) => void` | 拖移/拖改时长提交：回吐整组新 events（照 Kanban 受控范式） |
| onSlotDragCreate | `(slot: SchedulerSlot) => void` | 空白竖拖创建（拖出一段时间） |
| onSlotClick | `(slot: SchedulerSlot) => void` | 点空白格（无拖动）创建 |
| onEventClick | `(event: SchedulerEvent) => void` | 点事件块 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderEvent | `(event: SchedulerEvent) => ReactNode` | 渲染函数：自定义事件块内容（外框/定位/拖拽手柄由组件负责） |

## 示例
```tsx
const [events, setEvents] = useState<SchedulerEvent[]>(INITIAL);
const [view, setView] = useState<SchedulerView>("week");
const [date, setDate] = useState("2026-06-15");

<div className="h-[520px] w-full">
  <Scheduler
    className="h-full"
    events={events}
    view={view}
    date={date}
    resources={resources}
    onViewChange={setView}
    onDateChange={setDate}
    onEventsChange={setEvents}
    onSlotDragCreate={(slot) =>
      setEvents((prev) => [
        ...prev,
        { id: `n-${slot.start}`, title: "新预约", start: slot.start, end: slot.end, resourceId: slot.resourceId ?? "d1", tone: "primary" },
      ])
    }
  />
</div>
```

## 禁忌 / 坑

- 全受控：events/view/date 由消费者持有，拖拽不会自动改 state——必须接 `onEventsChange` 回吐整组并 setState，否则拖完弹回原位（照 Kanban 范式）。
- 外层须给确定高度（如 `h-[520px]` + `className="h-full"`），时间轴靠容器高度填满后才内部滚动；不给高度会塌缩。
- tone 只接受 5 个语义枚举，刻意避开未定义色的静默回退；要任意配色走 `renderEvent`。
- start/end 是含时分的 ISO datetime（本地时区解释），区别于 Gantt 的纯日期闭区间。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# ScoreRing

> 评分环 · 半径仪表盘 + A-F 等级带(value→grade tone 映射·纯函数 resolveGrade 可测) + 环心分值/等级 · 区别线性 Meter/Progress·SVG dasharray 非 transform·RSC · data-display/info

## 何时用

把一个分值（质量分/健康度/评级）显示成圆环仪表盘，按 value 落入 A–F 等级带自动着色，环心显示分值与等级。要圆环用本组件；要线性进度/容量用 [Meter]/[Progress]；要趋势用 [Sparkline](https://hulianui.haloritual.com/components/sparkline)。可 RSC（SVG dasharray 渲染，非 transform 动画）。

## 导入
```ts
import { ScoreRing, resolveGrade, DEFAULT_GRADES } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `number` | — | 当前分值 |
| max | `number` | `100` | 满分 |
| grades | `Grade[]` | — | 等级带（不传用默认 A-F，即 `DEFAULT_GRADES`） |
| size | `number` | `96` | 直径 px |
| thickness | `number` | `8` | 环宽 px |
| showGrade | `boolean` | `true` | 是否显示等级字 |
| className | `string` | — | 自定义类 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 环心副标签（如「质量分」） |

## 示例
```tsx
<ScoreRing value={95} label="质量分" />
<ScoreRing value={42} label="质量分" />
```

迷你尺寸、不显等级字：
```tsx
<ScoreRing value={88} size={48} thickness={5} showGrade={false} />
```

## 禁忌 / 坑

暂无已知坑。等级颜色由 `resolveGrade(value, max, grades)` 纯函数映射；自定义评级体系传 `grades` 覆盖默认 A–F。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [Badge](https://hulianui.haloritual.com/components/badge) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# ScrollStack

> 滚动驱动的卡片堆叠组件 · 逐张钉住 + 缩放递进 + 可选旋转/景深模糊(零依赖原生滚动+RAF·token 皮肤·reduced-motion 静态平铺) · data-display/collection · #animated

## 何时用

做"随页面滚动逐张卡片钉住堆叠、后压前层层递进"的叙事区块（特性介绍、流程步骤）时用。要的是**滚动驱动的纵深堆叠**用本组件；要球面拖拽探索用 [InfiniteMenu](https://hulianui.haloritual.com/components/infinite-menu)，要海报飞行长廊用 [FlyingPosters](https://hulianui.haloritual.com/components/flying-posters)。

## 导入
```ts
import { ScrollStack, ScrollStackItem } from "@hulianui/ui"
```

## Props

`ScrollStack`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| itemDistance | `number` | `100` | 相邻卡片初始垂直间距（px），越大未堆叠时铺得越开 |
| itemScale | `number` | `0.03` | 每张相对前一张的缩放增量，形成后压前层层递进的纵深 |
| itemStackDistance | `number` | `30` | 卡片被钉住时彼此错开的垂直距离（px），决定露出的"卡边"高度 |
| stackPosition | `string` | `"20%"` | 触发钉住的位置（容器高度百分比或像素值），卡顶滚到此处开始钉住 |
| scaleEndPosition | `string` | `"10%"` | 缩放结束位置，卡顶越过此处缩放达目标值 |
| baseScale | `number` | `0.85` | 首张（最底层）卡的基础缩放，后续卡按 itemScale 递增 |
| rotationAmount | `number` | `0` | 每层堆叠旋转增量（deg），正值产生扑克牌式扇形错位 |
| blurAmount | `number` | `0` | 被压下方卡片的模糊增量（px），>0 越靠下越模糊；reduced-motion 下自动关闭 |
| className | `string` | — | 追加到滚动容器根节点的类名 |
| style | `CSSProperties` | — | 透传到滚动容器根节点的内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onStackComplete | `() => void` | 最后一张进入钉住区时触发，可联动后续动效 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 卡片内容，建议每张用 `ScrollStackItem` 包裹（组件自动识别 `data-scroll-stack-card` 标记的元素参与堆叠） |

`ScrollStackItem`：`{ children?: ReactNode; itemClassName?: string }` —— `itemClassName` 追加到单张卡外层。

## 示例
```tsx
// 必须包在一个固定高度 + overflow-hidden 的滚动窗口里，钉住才可见
<div className="h-[28rem] overflow-hidden rounded-xl border border-border">
  <ScrollStack>
    <ScrollStackItem>卡片 1</ScrollStackItem>
    <ScrollStackItem>卡片 2</ScrollStackItem>
    <ScrollStackItem>卡片 3</ScrollStackItem>
  </ScrollStack>
</div>

// 扇形旋转 + 景深模糊
<ScrollStack rotationAmount={3} blurAmount={2}>{/* ... */}</ScrollStack>
```

## 禁忌 / 坑

- **外层必须是定高 + `overflow-hidden` 的滚动窗口**，否则没有滚动行程、卡片不会钉住堆叠。
- 卡片须用 `ScrollStackItem` 包裹（或带 `data-scroll-stack-card`），否则不参与堆叠计算。
- reduced-motion 下退化为静态平铺，`blurAmount` 自动关闭，不要依赖堆叠动画传递关键信息。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Skeleton

> 骨架屏 · shimmer 高光占位(text/circle/rect) + 无边框组合预设 CardSkeleton/ListSkeleton/TableSkeleton · data-display/placeholder

## 何时用

数据加载中、需要给页面留出与真实内容同形的占位时用 `Skeleton`，列表/卡片/表格场景直接用对应预设少写排版。它表达「正在加载」——加载完成但确实没数据用 [Empty](https://hulianui.haloritual.com/components/empty)；表格本体用 [Table](https://hulianui.haloritual.com/components/table)/[ProTable](https://hulianui.haloritual.com/components/pro-table)，加载态再叠 `TableSkeleton`。

## 导入
```ts
import { Skeleton, TableSkeleton, CardSkeleton, ListSkeleton } from "@hulianui/ui"
```

## Props

`Skeleton` 继承 `div` 原生属性（`style` 除外），并带 CVA 变体：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| shape | `"text" \| "circle" \| "rect"` | `"text"` | 占位形状 |

预设组件 `ListSkeleton` / `CardSkeleton` 用各自的计数 prop（`rows` / `count`）控制数量，尺寸靠外层 `className` 约束。

## 示例
```tsx
// 基础三形状（尺寸由 className 控制）
<Skeleton className="w-32" />
<Skeleton shape="circle" className="size-10" />
<Skeleton shape="rect" className="h-16 w-32" />

// 组合预设
<div className="w-72"><ListSkeleton rows={3} /></div>
<div className="w-full max-w-md"><CardSkeleton count={2} /></div>
```

## 禁忌 / 坑

- 骨架本身是「无 chrome」的占位，预设（Card/List/Table）不自带边框/卡片容器；别再外层套一层 Card 造成双重边框。
- shimmer 是纯 CSS 动画，与图表/canvas 那类 rAF 动画不同，headless 截图能正常显形，无需特殊处理。

## 相关
[Empty](https://hulianui.haloritual.com/components/empty) · [Watermark](https://hulianui.haloritual.com/components/watermark) · [Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table)

<!-- ════════════════════════════════════════════════════════ -->
# Sortable

> 拖拽排序 · @dnd-kit headless + 键盘可拖(Space 抓起/方向键移动) + 手柄/整项两式 + 横竖向 · 受控 onChange(arrayMove) · data-display/collection

## 何时用

单列表内拖拽改顺序（表格列设置、标签排序、表单字段排序），受控数据 + `onChange` 回吐 arrayMove 后的新数组。要跨多列流转（看板/任务流）用 [Kanban](https://hulianui.haloritual.com/components/kanban)；要节点画布连线编排用 [Flow](https://hulianui.haloritual.com/components/flow)。

## 导入
```ts
import { Sortable } from "@hulianui/ui"
```

## Props

`SortableProps<T>` 泛型。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items * | T[] | — | 受控数据数组；拖拽后由你据 onChange 写回 state |
| getId | (item: T) => UniqueIdentifier | 读 `item.id` | 取每项稳定 id，须列表内唯一且稳定 |
| orientation | `"vertical"｜"horizontal"` | `"vertical"` | 排列方向 |
| handle | boolean | false | true=仅左侧手柄可拖（触屏/含交互元素的行推荐）；false=整项可拖 |
| className | string | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange * | (items: T[]) => void | 顺序变化回调（拖拽或键盘移动均触发），参数是 arrayMove 后的新数组 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem * | (item: T, state: { dragging: boolean }) => ReactNode | 渲染单项的渲染函数；`state.dragging` 表示该项正被拖拽 |

## 示例
```tsx
const [items, setItems] = useState(fields);

<Sortable
  items={items}
  onChange={setItems}
  handle
  renderItem={(f) => (
    <div className="flex items-center justify-between gap-3">
      <span className="font-medium text-foreground">{f.label}</span>
      <span className="shrink-0 text-xs text-muted">{f.hint}</span>
    </div>
  )}
/>

// 横向
<Sortable items={tags} orientation="horizontal" onChange={setTags}
  renderItem={(t) => <span>{t.name}</span>} />
```

## 禁忌 / 坑

- 受控组件：`onChange` 不会替你改 state，必须自己把新数组写回（`onChange={setItems}`）。
- `getId` 返回的 id 必须稳定唯一；用数组下标当 id 会在重排后错乱。
- 行内含按钮/链接等交互元素时设 `handle`，否则整项可拖会拦截子元素的点击/拖拽（参考 [[dnd-kit-draggable-container-guard-interactive-children]]）。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Sparkline

> 内联趋势迷你图 · 无轴无网格的极简趋势 · line/area/bar 三态 + highlightLast 末点圆点 + 原生 SVG <title> tooltip(RSC 安全零 JS) · 几何抽纯函数(归一化/path/柱矩形)带单测 · 表格内联/KPI 卡/负载趋势(零依赖) · data-display/info

## 何时用

在表格单元格、KPI 卡、列表行内嵌一条「极简趋势」时用——无轴无网格、随文本流。需要带坐标轴/图例/交互 tooltip 的完整图表用 Chart（recharts）；只展示单值用 [Stat]/[Badge]。Sparkline 胜在零依赖、RSC 安全、可内联。

## 导入
```ts
import { Sparkline, normalize, linePath, areaPath, barRects } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| data* | `SparkDatum[]` | — | 纯数字序列或 `{x,y}` 点（取 y） |
| variant | `"line" \| "area" \| "bar"` | `"line"` | 渲染形态：折线 / 面积 / 柱 |
| width | `number` | `80` | 视口宽 |
| height | `number` | `24` | 视口高 |
| tone | `string` | `var(--color-primary)` | 描边/填充色。可传语义色名（`"primary"`/`"success"`/`"danger"`/`"chart-2"`，经 resolveTone 解析为 `var(--color-*)`）、任意 CSS 颜色或变量 |
| highlightLast | `boolean` | `false` | 在末点画强调圆点 |
| min | `number` | — | 归一化下界，不传从数据推 |
| max | `number` | — | 归一化上界，不传从数据推 |
| className | `string` | — | 外层类名 |

继承 `SVGProps<SVGSVGElement>`（除 `data`）。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderTooltip | `(value: number, index: number) => ReactNode` | 渲染函数：逐点原生 tooltip，返回字符串渲染为 SVG `<title>`（零 JS，RSC 安全） |

## 示例
```tsx
// 表格内联趋势 + 末点强调 + 原生逐点 tooltip
<Sparkline
  data={[8, 9, 7, 11, 10, 13, 12, 15]}
  variant="line"
  tone="var(--color-primary)"
  highlightLast
  width={96}
  height={22}
  renderTooltip={(v, i) => `第 ${i + 1} 周期：${v}`}
/>

// 面积形态，语义色
<Sparkline data={series} variant="area" tone="chart-2" width={140} height={36} />
```

## 禁忌 / 坑

- tone 既接受语义色名（`"primary"`/`"chart-2"`，经 resolveTone 解析）也接受裸 CSS 变量；若手写 `var(...)` 给 SVG fill/stroke 须带 `--color-` 前缀，见 [[hulian-token-color-var-needs-color-prefix]]。
- renderTooltip 走原生 `<title>`，是浏览器悬停气泡（有延迟、不可定制样式），不是 JS 浮层——换取的是 RSC 安全、零客户端 JS。

## 相关
[ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge) · [Dot](https://hulianui.haloritual.com/components/dot)

<!-- ════════════════════════════════════════════════════════ -->
# Stat

> 指标卡 · KPI 数值/标签/升降趋势(无图表库) · data-display/stat

## 何时用

仪表盘里展示单个 KPI 指标卡：标签 + 数值 + 环比升降 + 可选图标/sparkline 插槽。要纯文本格式化数值（千分位/前后缀/倒计时）而非整张卡用 [Statistic](https://hulianui.haloritual.com/components/statistic)；要画趋势曲线/分布用 [Chart](https://hulianui.haloritual.com/components/chart)；要表达占比量条用 [Meter](https://hulianui.haloritual.com/components/meter)。

## 导入
```ts
import { Stat } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| delta | `number` | — | 环比百分比，>=0 升(text-primary) / <0 降(text-danger)；不传则不渲染趋势 |
| …HTMLAttributes | `HTMLAttributes<HTMLDivElement>` | — | 透传 div 原生属性（含 className） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label* | `ReactNode` | 指标标签 |
| value* | `ReactNode` | 指标数值（自行格式化好的字符串/节点） |
| deltaLabel | `ReactNode` | 趋势旁说明文案（如「较上月」） |
| icon | `ReactNode` | 角标图标 |
| chart | `ReactNode` | 图表插槽（如 KPI 趋势 sparkline），渲染在数值行下方、delta 上方 |

## 示例
```tsx
// 上升趋势
<Stat label="本月 GMV" value="¥128,400" delta={12.5} deltaLabel="较上月" icon={<Activity className="size-4" />} className="w-64" />

// 无趋势
<Stat label="注册用户" value="8,021" icon={<Users className="size-4" />} className="w-64" />
```

## 禁忌 / 坑
暂无已知坑。`delta` 不传则整块趋势不渲染；正负号由数值符号决定颜色，无需自己加箭头。`value` 不做格式化，需自己传格式化后的内容（要自动千分位/前后缀走 [Statistic](https://hulianui.haloritual.com/components/statistic)）。

## 相关
[Statistic](https://hulianui.haloritual.com/components/statistic) · [Chart](https://hulianui.haloritual.com/components/chart) · [Meter](https://hulianui.haloritual.com/components/meter) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# Statistic

> 统计数值 · 千分位/precision/前后缀/valueStyle + 可选 NumberTicker 入场滚动 + Statistic.Countdown 倒计时(SSR 安全·零依赖·与 Stat 互补) · data-display/stat

## 何时用

格式化展示一个统计数值（自动千分位、小数位、前后缀），或用 `Statistic.Countdown` 展示倒计时。与 [Stat](https://hulianui.haloritual.com/components/stat) 互补：Stat 是「标签 + 值 + 升降趋势」的整张指标卡，本组件专注「数值本身的格式化」（你自己拼标签）。

## 导入
```ts
import { Statistic, formatStatistic, formatCountdown } from "@hulianui/ui"
```

## Props

### Statistic

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value* | `number \| string` | — | string 原样输出，number 走千分位 + precision 格式化 |
| precision | `number` | — | 小数位数（仅 value 为 number 时生效） |
| groupSeparator | `boolean` | `true` | 千分位分组 |
| animate | `boolean` | `false` | 接 NumberTicker 入场滚动（仅 number；动效路径恒带千分位） |
| valueStyle | `CSSProperties` | — | 数值行内联样式（自定义颜色/字号） |
| align | `"start" \| "center" \| "end"` | `"start"` | 水平对齐；数值行是 flex，className text-center 无效，须用此 prop |
| className | `string` | — | 透传类名 |

### Statistic.Countdown

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| deadline* | `number` | — | 截止时间戳（毫秒，与 Date.now() 同基准） |
| format | `string` | `"HH:mm:ss"` | 格式化模板，支持 D/H/HH/m/mm/s/ss/S/SS/SSS |
| valueStyle | `CSSProperties` | — | 数值行内联样式 |
| className | `string` | — | 透传类名 |

## Events

### Statistic.Countdown

| 事件 | 类型 | 说明 |
|------|------|------|
| onFinish | `() => void` | 倒计时归零回调（只触发一次） |

## Slots

### Statistic

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 数值上方说明标题 |
| prefix | `ReactNode` | 数值前缀（货币符号/图标等） |
| suffix | `ReactNode` | 数值后缀（单位等） |

### Statistic.Countdown

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题 |
| prefix | `ReactNode` | 前缀 |
| suffix | `ReactNode` | 后缀 |

## 示例
```tsx
// 小数 + 前缀，自动千分位
<Statistic title="账户余额" value={89234.56} precision={2} prefix="￥" />

// 倒计时：deadline 用 useState 初始化器固定一次，避免 SSR/render 漂移
const [deadline] = useState(() => Date.now() + 1000 * 60 * 60);
<Statistic.Countdown title="距活动结束" deadline={deadline} format="D 天 HH:mm:ss" />
```

## 禁忌 / 坑
- 倒计时 `deadline` 务必用 `useState(() => Date.now() + …)` 初始化器固定一次，直接在 render 里算会每次漂移、且导致 SSR/CSR hydration mismatch。
- 数值行是 flex 布局，靠 `className="text-center"` 居中无效，须用 `align` prop。
- `precision` / 千分位仅在 `value` 为 number 时生效；传 string 则原样输出。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Chart](https://hulianui.haloritual.com/components/chart) · [Meter](https://hulianui.haloritual.com/components/meter) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# StatusDot

> 健康状态点 · 在线/降级/离线/维护四语义态(→success/warning/danger/neutral 映射) + 默认仅在线脉冲 + 状态文字 + 尾部数值槽(延迟/成功率)(封装 Dot·网关渠道健康墙刚需·纯CSS·RSC) · data-display/info

## 何时用

展示一个渠道/模型/服务的健康态成品行（圆点 + 状态文字 + 延迟/成功率数值）时用，典型场景是网关渠道健康墙。它在 [Dot](https://hulianui.haloritual.com/components/dot) 之上封装了「四语义态映射 + 文字 + 尾槽」；只要一个裸状态圆点（自定 tone）用 Dot；要的是计数角标用 [Badge](https://hulianui.haloritual.com/components/badge)。

## 导入
```ts
import { StatusDot } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| status* | `"online"｜"degraded"｜"offline"｜"maintenance"` | — | 健康态：在线/降级/离线/维护（内部映射 success/warning/danger/neutral）。 |
| pulse | `boolean` | 仅 online 自动脉冲 | 呼吸脉冲；可显式覆盖默认。 |
| size | `"sm"｜"md"｜"lg"` | `md` | 尺寸。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| label | `ReactNode` | 状态文字（如「在线」），提供则随圆点一起播报。 |
| extra | `ReactNode` | 尾部数值槽（如延迟「128ms」）。 |

## 示例
```tsx
// 在线 + 延迟
<StatusDot status="online" label="在线" extra="86ms" />

// 降级 + 高延迟
<StatusDot status="degraded" label="降级" extra="412ms" />
```

## 禁忌 / 坑

暂无已知坑。`pulse` 默认只有 `online` 态自动呼吸，其余态静止；要让降级态也脉冲须显式 `pulse`。候选坑均不适用：`status-enum-whitelist-negate-filter`、`multi-identity-bind-status-authoritative-field`、`batch-loop-break-terminal-status-overwritten-by-finalizer` 讲后端状态枚举/字段权威性，`menubarextra-app-body-observation-tears-down-status-item` 讲 macOS 菜单栏，与本展示组件无关。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Table

> 表格 · TanStack headless + 列排序 + 空态 · data-display/collection

## 何时用

展示结构化二维数据（用户列表、明细表等）且需要排序/行选择/树形/虚拟滚动等表格能力时用。列定义直接复用 TanStack 的 `ColumnDef`，不发明平行 API。它是底层表格皮肤——需要查询区 + 工具栏 + 集成分页的完整列表页用 [ProTable](https://hulianui.haloritual.com/components/pro-table)（它内部就包了 Table）；单元格可编辑用 [EditableTable](https://hulianui.haloritual.com/components/editable-table)；纯垂直列表用 [List](https://hulianui.haloritual.com/components/list)。

## 导入
```ts
import { Table } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| columns* | `ColumnDef<TData, any>[]` | — | TanStack 列定义（accessorKey/header/cell/meta.sticky/meta.filterable…） |
| data* | `TData[]` | — | 行数据 |
| enableSorting | `boolean` | `true` | false 则表头不可点、无排序箭头、不写 aria-sort |
| sorting | `SortingState` | — | 受控排序态；不传走内部非受控 |
| striped | `boolean` | `true` | 偶数行斑马纹 |
| bordered | `boolean` | `true` | 外层描边 + 圆角；被 ProTable 卡片包裹时置 false 避免双框 |
| density | `"default" \| "middle" \| "compact"` | `"default"` | 行密度（仅调单元格内边距） |
| getRowId | `(row: TData, index: number) => string` | 按 index | 行稳定 key |
| rowClassName | `(row: TData, index: number) => string \| undefined` | — | 行级附加 className（与斑马/选中类合并，不覆盖） |
| enableRowSelection | `boolean \| ((row: Row<TData>) => boolean)` | 关 | 开行选择，自动前插复选框列（含全选）；函数可限定可选行 |
| rowSelection | `RowSelectionState` | — | 受控选择态 |
| getRowCanExpand | `(row: Row<TData>) => boolean` | — | 限定可展开行 |
| getSubRows | `(row: TData) => TData[] \| undefined` | — | 提供则启用树形（按 row.depth 缩进） |
| indent | `number` | `16` | 树形/明细每级缩进像素 |
| expanded | `ExpandedState` | — | 受控展开态（树形 + 明细共用） |
| columnFilters | `ColumnFiltersState` | — | 受控列筛选态 |
| virtual | `VirtualOptions` | 关 | 虚拟滚动（需 @tanstack/react-virtual）：`{ enabled; rowHeight?=44; height?=480; overscan?=8 }` |
| className | `string` | — | 根节点类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSortingChange | `OnChangeFn<SortingState>` | 排序变化回调 |
| onRowSelectionChange | `OnChangeFn<RowSelectionState>` | 选择变化回调 |
| onExpandedChange | `OnChangeFn<ExpandedState>` | 展开变化回调（树形 + 明细共用） |
| onColumnFiltersChange | `OnChangeFn<ColumnFiltersState>` | 列筛选变化回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderExpandedRow | `(row: Row<TData>) => ReactNode` | 渲染函数；提供则前插展开器列，展开行下渲染整宽明细面板 |
| emptyText | `ReactNode` | 空态文案（默认 `locale.table.empty`） |
| renderEmpty | `() => ReactNode` | 渲染函数；完全自定义空态（优先级高于 emptyText） |

列 meta 增量（写在 `ColumnDef.meta`）：`sticky?: "left" \| "right"`（固定列贴左/右）、`filterable?: boolean`（表头渲染内置文本筛选框）。

## 示例
```tsx
const columns: ColumnDef<DemoUser, any>[] = [
  { accessorKey: "name", header: "姓名" },
  { accessorKey: "email", header: "邮箱" },
  { accessorKey: "role", header: "角色" },
];

// 基础（默认可排序 + 斑马纹）
<Table columns={columns} data={users} />

// 行选择（自动前插复选框列 + 全选）
<Table columns={columns} data={users} enableRowSelection />
```

## 禁忌 / 坑

- 固定列（`meta.sticky`）的 offset 靠 TanStack 列宽推算，务必给相关列显式 `size`，否则贴左/右偏移不准；同时内容要够宽触发横滚才看得到效果。
- `virtual` 是可选依赖（@tanstack/react-virtual），需手动安装；仅推荐大数据平铺表，不建议与树形/明细面板同开。
- `bordered` 默认 true 自带外框——嵌进 ProTable 或其他卡片容器时置 `false`，否则双层描边。
- 排序/选择/展开/筛选均「不传受控 prop 即内部非受控」；要受控就成对接上 `xxx` + `onXxxChange`。

## 相关
[Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table) · [List](https://hulianui.haloritual.com/components/list)

<!-- ════════════════════════════════════════════════════════ -->
# Tag

> 状态标签 · 5 语气状态色 + 状态圆点/呼吸进行态(pulse) + 图标 + 可关闭(企业状态标记·区别 Chip 令牌) · data-display/info

## 何时用

表达对象状态/类别的小标记（运行中、待审核、已驳回等），支持状态圆点与呼吸动画表达进行态。展示数值/计数徽记用 [[Badge]]；可输入/可移除的过滤令牌用 Chip，本组件偏只读状态标记。

## 导入
```ts
import { Tag, tagVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"soft" \| "solid" \| "outline"` | `"soft"` | 视觉变体：soft 浅底（最常用于状态标签）/ solid 实底 / outline 描边。 |
| tone | `"neutral" \| "brand" \| "success" \| "warning" \| "danger"` | `"neutral"` | 语气色。 |
| size | `"sm" \| "md"` | `"md"` | 尺寸。 |
| dot | `boolean` | `false` | 前导状态圆点（颜色随 tone）。与 icon 互斥：icon 优先于 dot。 |
| pulse | `boolean` | `false` | 圆点呼吸动画（进行态语义）。仅在 dot 为真时生效。 |
| isDisabled | `boolean` | `false` | 禁用：降透明度、屏蔽指针事件、关闭按钮不可点。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClose | `() => void` | 提供则渲染关闭(×)按钮，点击触发该回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 前导图标槽；存在时不渲染 dot。 |
| children | `ReactNode` | 标签文本。 |

## 示例
```tsx
// 状态语气
<Tag>默认</Tag>
<Tag tone="success">成功</Tag>
<Tag tone="danger">错误</Tag>
```
```tsx
// 呼吸圆点表达进行态 + 可关闭
<Tag dot pulse tone="brand">部署中</Tag>
<Tag onClose={() => remove(id)}>待审核</Tag>
```

## 禁忌 / 坑

- `pulse` 只在 `dot` 为真时生效，单独传 `pulse` 无动画。
- `icon` 与 `dot` 互斥，同传时只渲染 `icon`——想要圆点就别传 icon。
- `onClose` 列表场景需自行维护移除后的状态（受控数组 filter），组件本身不删元素。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# TiltedCard

> 指针驱动的 3D 倾斜卡片 · perspective + rotateX/Y 弹簧倾斜 + 悬停放大 + 跟随指针的浮动提示气泡（motion 弹簧·零新依赖·reduced-motion） · data-display/collection · #animated

## 何时用

给任意一张图片/内容卡加"悬停指针 3D 倾斜 + 放大 + 浮动提示"的通用交互时用，是最轻量的单卡倾斜原语。要的是**有姓名/职位语义的名片**用 [ProfileCard](https://hulianui.haloritual.com/components/profile-card)，要悬停像素波纹卡用 [PixelCard](https://hulianui.haloritual.com/components/pixel-card)，要成组聚光网格用 [MagicBento](https://hulianui.haloritual.com/components/magic-bento)。

## 导入
```ts
import { TiltedCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| imageSrc | `string` | — | 卡面图片地址，传了即渲染铺满的 `<img>`；也可只用 children 自定义卡面 |
| altText | `string` | — | 图片 alt 文案（无障碍） |
| containerHeight | `CSSProperties["height"]` | `"300px"` | 外层透视容器高度 |
| containerWidth | `CSSProperties["width"]` | `"100%"` | 外层透视容器宽度 |
| cardHeight | `CSSProperties["height"]` | `"300px"` | 倾斜卡面高度 |
| cardWidth | `CSSProperties["width"]` | `"300px"` | 倾斜卡面宽度 |
| scaleOnHover | `number` | `1.1` | 悬停时整体放大倍数 |
| rotateAmplitude | `number` | `14` | 倾斜最大角度（度），越大越立体 |
| showTooltip | `boolean` | `true` | 是否渲染跟随指针的浮动提示气泡 |
| displayOverlayContent | `boolean` | `false` | 是否显示 overlayContent |
| className | `string` | — | 合并到外层 `<figure>` 的额外类名 |
| style | `CSSProperties` | — | 额外内联样式（合并到外层透视容器） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| captionText | `ReactNode` | 跟随指针的浮动提示文案，为空则不渲染提示气泡 |
| overlayContent | `ReactNode` | 浮于卡面之上、随倾斜一同 3D 抬升的叠加内容（角标/标题） |
| children | `ReactNode` | 卡面内容（与 imageSrc 二选一或叠加，置于图片之上、overlay 之下） |

## 示例
```tsx
// 内容卡 + 浮动提示
<TiltedCard
  cardWidth="240px" cardHeight="240px"
  containerWidth="240px" containerHeight="240px"
  captionText="悬停我"
>
  <div className="flex h-full flex-col items-center justify-center gap-2 p-6">
    <p className="text-lg font-semibold text-foreground">瑚琏组件库</p>
  </div>
</TiltedCard>

// 图片卡 + 抬升角标
<TiltedCard
  imageSrc="/cover.jpg" altText="封面"
  displayOverlayContent
  overlayContent={<span className="absolute left-3 top-3 rounded-full bg-primary px-2.5 py-1 text-xs text-primary-foreground">NEW</span>}
/>
```

## 禁忌 / 坑

- 倾斜需鼠标悬停触发：触屏/无指针环境不产生倾斜，关键内容不要只靠倾斜表达。
- `containerWidth/Height` 与 `cardWidth/Height` 是两套尺寸（透视容器 vs 倾斜卡面），二者不一致时卡面会在容器内偏移，通常应配套设同值。
- 基于 motion 弹簧、零新依赖；reduced-motion 下自动停倾斜。[[motion-v12-interrupted-animation-promise-never-settles]]：若在它之上再编排被打断的 motion 动画链，注意被中断的动画 promise 可能永不 settle。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Timeline

> 时间线 · 复合 Timeline/Item + items 数组 + 彩色节点/自定义 dot + left/right/alternate + pending 加载态(纯皮肤·零依赖·RSC) · data-display/stat

## 何时用

按时间顺序展示一串事件（审批流、物流轨迹、操作历史），每项一个彩色节点 + 内容 + 元信息。要展示单条 git 提交引用用 [GitCommit]（本批近邻 info 组），要展示分步骤的可推进流程用 Steps；本组件是「带连线的纵向事件流」。

## 导入
```ts
import { Timeline, TimelineItem } from "@hulianui/ui"
```

## Props

### Timeline

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `TimelineItemProps[]` | — | 数据驱动：等价于每项渲染 `<TimelineItem {...item} />`；与 children 二选一 |
| mode | `"left" \| "right" \| "alternate"` | `"left"` | 布局方向：left=节点在左/内容在右，right=镜像，alternate=逐项左右交替（中轴） |
| …HTMLAttributes | `Omit<HTMLAttributes<HTMLOListElement>, "children">` | — | 透传 ol 原生属性 |

### TimelineItem

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `"default" \| "primary" \| "success" \| "danger" \| "warning"` | `"default"` | 默认圆点的语气色；自定义 dot 时忽略 |
| pending | `boolean` | — | 标记进行中：默认圆点变加载态（旋转环）；连入此项的竖线由 Timeline 自动转虚线 |
| className | `string` | — | 透传类名 |

## Slots

### Timeline

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 复合用法：直接传若干 `<TimelineItem>`；与 items 二选一 |
| pending | `boolean \| ReactNode` | 末尾追加一个进行中幽灵项（加载态圆点）；true=仅图标，传 ReactNode 作其内容 |

### TimelineItem

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 主内容 |
| dot | `ReactNode` | 自定义节点（如图标）；省略则渲染按 color 着色的默认圆点 |
| label | `ReactNode` | 次要标签（时间戳/元信息），渲染在主内容下方、中性弱化；圆点对齐主内容首行 |

## 示例
```tsx
// 数据驱动（最常见）：审批流，彩色语气
const approval = [
  { label: "09:12", children: "员工提交报销申请", color: "primary" },
  { label: "10:40", children: "直属经理审批通过", color: "success" },
];
<Timeline items={approval} pending="财务复核中" />

// 复合用法：自定义图标节点
<Timeline>
  <TimelineItem label="步骤一" color="success" dot={CheckIcon}>账号注册完成</TimelineItem>
  <TimelineItem label="步骤二" color="primary">绑定收款账户（进行中）</TimelineItem>
</Timeline>
```

## 禁忌 / 坑
- `items` 与 `children` 二选一，不要同时传。
- `label` 是次要元信息（时间戳），渲染在主内容**下方**且圆点对齐主内容首行——不要把正文塞 label。
- `dot` 自定义节点会覆盖 `color`，二者同传时 color 被忽略。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Statistic](https://hulianui.haloritual.com/components/statistic) · [Chart](https://hulianui.haloritual.com/components/chart) · [Meter](https://hulianui.haloritual.com/components/meter) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker) · [WorldMap](https://hulianui.haloritual.com/components/world-map)

<!-- ════════════════════════════════════════════════════════ -->
# Tree

> 递归树 · 自研零依赖引擎 + WAI-ARIA tree(roving/方向键/typeahead) + checkable 父子级联半选 + 连接线 + 树内搜索 + grid-rows 高度过渡 · data-display/collection

## 何时用

展示并操作层级结构——文件目录、组织架构、分类导航、权限勾选树。扁平条目流用 [List](https://hulianui.haloritual.com/components/list)；只读 JSON 结构用 [JsonViewer](https://hulianui.haloritual.com/components/json-viewer)。本组件提供完整 WAI-ARIA tree 交互(方向键/typeahead)与 checkable 父子级联半选，适合需要键盘可达或勾选汇总的场景。

## 导入
```ts
import { Tree, buildIndex, flattenVisible, getNodePath, toggleChecked, getCheckState, normalizeCheckedToLeaves, computeChecked, filterTree, type FlatRow, type TreeIndex, type CheckState } from "@hulianui/ui"
```

## Props

`TreeProps`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| nodes* | `TreeNode[]` | — | 树数据(`{ key, label, icon?, children?, disabled? }`) |
| expandedKeys | `string[]` | — | 受控展开集 |
| defaultExpandedKeys | `string[]` | — | 非受控初始展开集 |
| selectable | `boolean` | `true` | 单选高亮(非 checkable 模式) |
| selectedKeys | `string[]` | — | 受控选中集 |
| defaultSelectedKeys | `string[]` | — | 非受控初始选中集 |
| checkable | `boolean` | `false` | 复选模式(行前 checkbox) |
| checkedKeys | `string[]` | — | 受控勾选集 |
| defaultCheckedKeys | `string[]` | — | 非受控初始勾选集 |
| showLine | `boolean` | `false` | 显示连接线 |
| searchable | `boolean` | `false` | 树内搜索框 |
| searchPlaceholder | `string` | — | 搜索框占位 |
| className | `string` | — | — |
| aria-label | `string` | — | 树的无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onExpandedChange | `(keys: string[]) => void` | 展开变化回调 |
| onSelect | `(keys: string[], node: TreeNode) => void` | 选中回调 |
| onCheck | `(info: { checkedKeys: string[]; halfCheckedKeys: string[] }, node: TreeNode) => void` | 勾选回调(含半选集) |

## 示例
```tsx
// 单选 · 默认展开两枝
<Tree nodes={NODES} defaultExpandedKeys={["design", "components"]} defaultSelectedKeys={["theme"]} />

// 复选(父子级联半选) + 搜索
<Tree nodes={NODES} checkable searchable searchPlaceholder="搜索组件"
  onCheck={({ checkedKeys, halfCheckedKeys }) => save(checkedKeys)} />
```

## 禁忌 / 坑

- 展开/选中/勾选三组状态各自**受控/非受控对称**：传 `xxxKeys` 即受控(须配 `onXxx` 回写)，否则用 `defaultXxxKeys`。混用同一组的受控与非受控会失效。
- `selectable` 默认 `true`；`checkable` 模式下走勾选，`onCheck` 回调里 `checkedKeys` 与 `halfCheckedKeys` 分开返回，半选父节点不在 `checkedKeys` 里。
- `nodes` 每项需稳定 `key`；`disabled` 节点不可选/不可勾。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# User

> 用户卡 · Avatar + 名称/描述组合(复用瑚琏 Avatar) + RSC · data-display/info

## 何时用

把头像 + 主名称 + 次级描述（邮箱/角色/@handle）组合成一个用户行/卡。只要头像用 [[Avatar](https://hulianui.haloritual.com/components/avatar)]；多人堆叠用 AvatarCircles；评论场景的作者区可直接传本组件给 Comment 的 author。

## 导入
```ts
import { User } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| avatarProps | `AvatarProps` | — | 透传给内置 Avatar（src/alt/fallback/size）。 |
| className | `string` | — | — |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| name* | `ReactNode` | 主名称（必填）。 |
| description | `ReactNode` | 次级描述（邮箱/角色/@handle 等）。 |

## 示例
```tsx
<User
  name="瑚琏"
  description="zhangzhiwei@hulian.dev"
  avatarProps={{ src: "/demo/avatar-12.jpg", alt: "瑚琏" }}
/>
```
```tsx
// 无图回退首字母
<User name="李四" description="产品经理" avatarProps={{ fallback: "李" }} />
```

## 禁忌 / 坑

- 头像通过 `avatarProps` 透传，没有图就传 `fallback`（同 Avatar）；否则失败/无图空白。
- `description` 可省略，省略时只渲染单行名称。

## 相关
[Sparkline](https://hulianui.haloritual.com/components/sparkline) · [ImageViewer](https://hulianui.haloritual.com/components/image-viewer) · [LiveProductCard](https://hulianui.haloritual.com/components/live-product-card) · [DiffStat](https://hulianui.haloritual.com/components/diff-stat) · [ScoreRing](https://hulianui.haloritual.com/components/score-ring) · [Badge](https://hulianui.haloritual.com/components/badge)

<!-- ════════════════════════════════════════════════════════ -->
# Video

> 视频播放器 · Vidstack 引擎 + 瑚琏 token 自搓皮肤(播放/进度/音量/倍速/PiP/全屏) + 文件/HLS + 章节标记/续播/结束屏 · data-display/collection

## 何时用

播放视频文件或 HLS 流并需要瑚琏风格控件——课程视频、产品演示、直播回放。本组件用 Vidstack 作引擎、自搓皮肤(播放/进度/音量/倍速/PiP/全屏)，并支持章节标记、续播定位、结束屏。相关组件里没有同类播放器，纯静态封面用 [Card](https://hulianui.haloritual.com/components/card) 即可。

## 导入
```ts
import { Video, formatTime, normalizeSrc, chapterMarkers, DEFAULT_PLAYBACK_RATES } from "@hulianui/ui"
```

## Props

`VideoProps`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| src* | `string \| { src: string; type? }[]` | — | 文件 URL / HLS `.m3u8` / 多源数组 |
| poster | `string` | — | 海报图 |
| title | `string` | — | 无障碍标题，也用于内部 aria |
| autoPlay | `boolean` | — | 自动播放 |
| muted | `boolean` | — | 静音 |
| loop | `boolean` | — | 循环 |
| crossOrigin | `boolean \| string` | — | 透传给底层 media 的 crossorigin |
| aspectRatio | `string` | `"16/9"` | CSS aspect-ratio |
| playbackRates | `number[]` | `DEFAULT_PLAYBACK_RATES`(0.5–2) | 倍速档位 |
| chapters | `VideoChapter[]` | — | 章节分段(`{ time, title }`)：进度条按 time/duration 渲染 tick，hover 显示标题 |
| startTime | `number` | — | 续播：可播放后 seek 到此秒(仅初始一次，>0 才生效) |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onPlay | `() => void` | 开始播放回调 |
| onPause | `() => void` | 暂停回调 |
| onEnded | `() => void` | 播放结束回调 |
| onTimeUpdate | `(currentTime: number) => void` | 播放进度回调(秒) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| endScreen | `ReactNode` | 播完浮现的结束屏内容(如「下一节」卡片)；为空则只给重播按钮 |
| children | `ReactNode` | v1 预留扩展位，未实现 |

> 导出的 `formatTime` / `chapterMarkers` / `normalizeSrc` / `DEFAULT_PLAYBACK_RATES` 为辅助纯函数/常量。

## 示例
```tsx
// 文件 + 海报
<Video src="/demo/sample.mp4" poster="/demo/poster.jpg" title="演示视频" className="w-full max-w-2xl" />

// HLS 流 + 章节标记 + 续播
<Video
  src="/demo/hls/stream.m3u8"
  title="带章节"
  startTime={4}
  chapters={[
    { time: 0, title: "开场介绍" },
    { time: 6, title: "实战演示" },
  ]}
/>
```

## 禁忌 / 坑

- 依赖 Vidstack 引擎，是 **client-only** 组件——在 Next.js RSC 里须放进 `"use client"` 边界，别在 server component 直接渲染。
- `startTime` 只在媒体首次可播放时 seek 一次且需 `>0`；运行中改它不会重新定位。
- `chapters` 的 tick 位置靠 `time/duration` 计算，`duration` 未知(0/NaN)时不渲染标记——海报态/未加载时看不到 tick 属正常。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# VirtualList

> 虚拟滚动 · 包 @tanstack/react-virtual 仅渲染可见区 + 定高/变高(measureElement)双模 + initialRect 首帧可算 + 末行触发 onReachEnd(万行列表/长列表刚需) · data-display/collection

## 何时用

列表上千行、DOM 全量渲染卡顿时用：只渲染视口可见的几十行。配合 `onReachEnd` 可叠加无限加载。需要「滚到底自动拉下一页」而行数不大（无虚拟化）走 [InfiniteScroll](https://hulianui.haloritual.com/components/infinite-scroll)；二者可组合（VirtualList 管渲染、onReachEnd 触发分页）。

## 导入
```ts
import { VirtualList } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `T[]` | — | 数据数组（泛型）。 |
| itemHeight* | `number｜((index: number) => number)` | — | 定高 px，或返回估算高度的函数（变高，按实测校正）。 |
| height | `number｜string` | `360` | 视口高度，px 或 CSS 长度。 |
| overscan | `number` | `5` | 预渲染屏外条数。 |
| getKey | `(item: T, index: number) => string｜number` | 用下标 | 行 key 提取。 |
| className | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onReachEnd | `() => void` | 末行进入视口时回调（配合无限加载）。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| renderItem* | `(item: T, index: number) => ReactNode` | 行渲染函数。 |

## 示例
```tsx
const rows = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: `数据行 ${i + 1}` }));

<VirtualList
  items={rows}
  itemHeight={44}
  height={320}
  getKey={(r) => r.id}
  renderItem={(r) => <Row data={r} />}
/>
```

## 禁忌 / 坑

暂无已知坑。`itemHeight` 传函数为变高模式：返回值只是估算，实际高度由 `measureElement` 实测校正，因此函数返回的近似值越准首帧抖动越小。变高行内容动态变化时务必保证 `getKey` 稳定，否则量测缓存错位。候选坑 `alicloud-oss-s3-compat-list-requires-virtual-host` 属对象存储 List 语义，与本组件无关，不适用。

## 相关
[Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table) · [JsonViewer](https://hulianui.haloritual.com/components/json-viewer) · [EditableTable](https://hulianui.haloritual.com/components/editable-table)

<!-- ════════════════════════════════════════════════════════ -->
# Watermark

> 水印 · 自研 canvas 平铺 + MutationObserver 防篡改 + 高清 DPR(零依赖·防截图泄密) · data-display/placeholder

## 何时用

需要在敏感内容区铺一层防截图泄密水印（文字/图片）时用，包裹 `children` 即可全区覆盖。它是「内容遮罩层」——空数据占位用 [Empty](https://hulianui.haloritual.com/components/empty)，加载占位用 [Skeleton](https://hulianui.haloritual.com/components/skeleton)。

## 导入
```ts
import { Watermark } from "@hulianui/ui"
```

## Props

继承 `div` 的所有原生属性（`content` 除外，已重定义为字符串/数组）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| content | `string \| string[]` | — | 水印文字，传数组渲染多行。与 `image` 二选一（同传 image 优先） |
| image | `string` | — | 图片水印源（dataURL/链接）。设置后忽略 content |
| width | `number` | `120` | 图片宽度（px），仅 image 模式生效 |
| height | `number` | 按原始宽高比 | 图片高度（px），仅 image 模式生效 |
| rotate | `number` | `-22` | 旋转角度（度） |
| gap | `number \| [number, number]` | `100` | 水印间距（px）。单值作用 x/y，或传 `[x, y]` |
| fontSize | `number` | `16` | 文字字号（px） |
| fontFamily | `string` | `sans-serif` | 字体族 |
| fontWeight | `number \| string` | `normal` | 字重 |
| color | `string` | `--color-muted` | 水印颜色，不传读语义 token 随明暗自适应 |
| opacity | `number` | `0.15` | 整体不透明度 |
| zIndex | `number` | `9` | 水印层 z-index（pointer-events:none 不挡交互） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 被水印覆盖的内容区 |

## 示例
```tsx
// 单行文字
<Watermark content="瑚琏 · 机密">
  <Sheet />
</Watermark>

// 多行 + 自定义颜色密度
<Watermark content={["瑚琏机密", "zhangzhiwei"]} gap={48} rotate={-30} color="var(--color-danger)">
  <Sheet />
</Watermark>

// 图片水印
<Watermark image={logoDataUri} width={84}>
  <Sheet />
</Watermark>
```

## 禁忌 / 坑

- 自定义 `color` 走 SVG/canvas 着色，必须用带 `--color-` 前缀的 token（`var(--color-danger)`），裸 `var(--danger)` 解析不出。参见 [[hulian-token-color-var-needs-color-prefix]]。
- 水印层是 canvas 平铺 + MutationObserver 防篡改，依赖客户端环境；纯 SSR 静态导出截图时水印层可能未绘制，验证视觉需真机。
- `content` 与 `image` 同传时 image 优先；想用文字别误传 image。

## 相关
[Empty](https://hulianui.haloritual.com/components/empty) · [Skeleton](https://hulianui.haloritual.com/components/skeleton) · [Table](https://hulianui.haloritual.com/components/table) · [Book3D](https://hulianui.haloritual.com/components/book-3d) · [ProTable](https://hulianui.haloritual.com/components/pro-table) · [PricingTable](https://hulianui.haloritual.com/components/pricing-table)

<!-- ════════════════════════════════════════════════════════ -->
# WorldMap

> 点阵世界地图 · 预烘点阵(零依赖·吃主题) + 经纬度动画弧线(pathLength 画入 + 端点脉冲) + 独立节点 points(value 分大小/可选标签) + onPointClick 可点击键盘下钻(交互态放开 aria-hidden) + flyingMarker 沿飞线移动标记(✈️飞机/光点彗尾/箭头·offset-path 动效自动转向) · data-display/stat · #animated

## 何时用

需要在世界点阵底图上画跨地域连线/节点分布（全球 PoP、调度指挥中心、流量大屏）时用。它是经纬度驱动的「装饰性可视化」，不是精确地理统计——要 GeoJSON 行政区填色/数据地图请用专门的地图库；纯数字滚动用 [NumberTicker](https://hulianui.haloritual.com/components/number-ticker)，常规图表用 [Chart](https://hulianui.haloritual.com/components/chart)。

## 导入
```ts
import { WorldMap } from "@hulianui/ui"
```

## Props

`WorldMapDot` = `{ start: WorldMapPoint; end: WorldMapPoint; color?: string }`；`WorldMapPoint` = `{ lat; lng; label? }`；`WorldMapNode` = `WorldMapPoint & { id?; value?; color? }`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| dots | `WorldMapDot[]` | — | 要画的连线对（经纬度）。不传/空数组则只显示点阵底图 |
| flyingMarker | `"plane" \| "comet" \| "arrow"` | — | 沿每条飞线循环移动的标记。plane/arrow 自动转向贴合飞行方向，用各自连线色 |
| points | `WorldMapNode[]` | — | 独立节点（节点分布）。与 dots 互不依赖，可单独使用。`value` 按当前 points 范围归一化映射半径 |
| showLabels | `boolean` | `false` | 是否渲染节点标签文字 |
| lineColor | `string` | chart token | 弧线颜色（CSS 颜色）。逐条可用 `dot.color` 覆盖 |
| dotColor | `string` | border token | 点阵颜色（CSS 颜色） |
| duration | `number` | — | 单条弧线画入时长（秒） |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onPointClick | `(node: WorldMapNode, index: number) => void` | 传入则节点可点击/键盘聚焦下钻，同时 svg 放开 aria-hidden 暴露交互节点 |

## 示例
```tsx
// 单条连线：北京 → 纽约
<WorldMap dots={[{ start: { lat: 39.9, lng: 116.4 }, end: { lat: 40.7, lng: -74 } }]} />

// 节点分布 + 可点击下钻（value 驱动大小）
<WorldMap
  points={[
    { id: "sh", lat: 31.2, lng: 121.5, label: "上海", value: 92 },
    { id: "sg", lat: 1.35, lng: 103.8, label: "新加坡", value: 64 },
  ]}
  showLabels
  onPointClick={(n) => console.log("下钻", n.label)}
/>

// 飞线 + 飞机标记
<WorldMap dots={dots} flyingMarker="plane" />
```

## 禁忌 / 坑

- 颜色 prop 喂给 SVG `stroke`/`fill`，必须用带 `--color-` 前缀的 token（`var(--color-chart-1)`），裸 `var(--chart-1)` 在 Tailwind v4 下解析不出会变黑/透明。参见 [[hulian-token-color-var-needs-color-prefix]]。
- 弧线是 pathLength 画入 + 端点脉冲动画，headless 截图会停在动画起始帧（线画不出来），不是 bug；验证视觉用真机或 reduced-motion。参见 [[verify-sub-second-web-animation-via-headless-screenshot]]、[[recharts-headless-screenshot-blank-clippath-animation-starved]]。
- 不传 `onPointClick` 时 svg 整体 `aria-hidden`（纯装饰）；传了才暴露可聚焦节点，键盘可达。

## 相关
[Stat](https://hulianui.haloritual.com/components/stat) · [Statistic](https://hulianui.haloritual.com/components/statistic) · [Chart](https://hulianui.haloritual.com/components/chart) · [Meter](https://hulianui.haloritual.com/components/meter) · [Timeline](https://hulianui.haloritual.com/components/timeline) · [NumberTicker](https://hulianui.haloritual.com/components/number-ticker)


# ━━━━━━━━ 导航 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# Accordion

> 手风琴 · Base UI 单/多开 + 高度过渡 · navigation/action

## 何时用

多组「标题 + 可折叠内容」并列（FAQ、设置分组、文档目录）时用，默认单开互斥、可切多开。只有单块内容要折叠用 [Collapsible](https://hulianui.haloritual.com/components/collapsible)；不需要折叠、只是导航跳转用 [Command](https://hulianui.haloritual.com/components/command)。

## 导入
```ts
import { Accordion, AccordionItem, AccordionTrigger, AccordionPanel } from "@hulianui/ui"
```

## Props

`Accordion` / `AccordionItem` / `AccordionTrigger` / `AccordionPanel` 均为 Base UI 对应原语的薄包，透传其全部 props。常用如下：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `Accordion.multiple` | `boolean` | `false` | 是否允许同时展开多项；`false` 时为单开互斥 |
| `Accordion.defaultValue` | `string[]` | — | 非受控初始展开的 item value 数组 |
| `Accordion.value` | `string[]` | — | 受控展开态 |
| `Accordion.className` | `string` | — | 容器类名 |
| `AccordionItem.value` * | `string` | — | 该项唯一标识，与 `value`/`defaultValue` 对应 |
| `AccordionItem.disabled` | `boolean` | `false` | 禁用该项（不可展开/收起） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `Accordion.onValueChange` | `(value: string[]) => void` | 展开态变化回调（透传 Base UI Root），受控时配合 `value` 使用 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `AccordionTrigger.children` | `ReactNode` | 标题行内容 |
| `AccordionPanel.children` | `ReactNode` | 折叠区内容 |

## 示例
```tsx
<Accordion defaultValue={["ship"]}>
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit，trunk-based，三道门全绿即可。</AccordionPanel>
  </AccordionItem>
  <AccordionItem value="token">
    <AccordionTrigger>颜色怎么适配明暗？</AccordionTrigger>
    <AccordionPanel>只消费语义 token，Tailwind v4 dark variant 自动换肤。</AccordionPanel>
  </AccordionItem>
</Accordion>
```

多开：

```tsx
<Accordion multiple defaultValue={["ship", "token"]}>{/* …items */}</Accordion>
```

## 禁忌 / 坑

- 高度展开/收起过渡走 Base UI 暴露的 `--accordion-panel-height` CSS 变量做纯 CSS transition，**不要**自己 `useLayoutEffect` 测 `scrollHeight`、也别上 framer-motion；padding 要放 Panel 内层 div 否则收起塌不到 0。详见 [[base-ui-accordion-panel-height-css-var-pure-css-transition]]。
- 受控与非受控二选一：传了 `value` 就别再传 `defaultValue`。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [Link](https://hulianui.haloritual.com/components/link) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)

<!-- ════════════════════════════════════════════════════════ -->
# Affix

> 固钉 · 自研零依赖滚动吸附 + offsetTop/offsetBottom + 占位防跳动 + 自定义容器 · navigation/inpage

## 何时用

滚动越过阈值后让某块内容（操作栏、目录、表单提交条）切到 `position:fixed` 吸附停留，原位用等高占位元素撑住防布局跳动。需要在页内「跳转」到锚点用 [Anchor](https://hulianui.haloritual.com/components/anchor)；只想要一颗回到顶部的按钮用 [BackTop](https://hulianui.haloritual.com/components/back-top)；Affix 是把任意 children 钉在视口某位置。

## 导入
```ts
import { Affix } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| offsetTop | `number` | `0` | 距容器顶部多少 px 时吸顶固定。 |
| offsetBottom | `number` | — | 距容器底部多少 px 时吸底固定。仅在未给 offsetTop 时生效（同时给则 offsetTop 优先）。 |
| target | `HTMLElement \| Window \| null \| (() => HTMLElement \| Window \| null)` | `window` | 滚动监听容器，可传元素 / Window / getter。 |
| affixedClassName | `string` | — | 吸附时附加到固定元素的类名（如阴影 `shadow-lg`）。 |

> 另继承 `HTMLAttributes<HTMLDivElement>`（除 `children` / `onChange`）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(affixed: boolean) => void` | 吸附态变化回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 被固定的内容。 |

## 示例
```tsx
const ref = useRef<HTMLDivElement>(null);

<div ref={ref} className="h-64 overflow-auto">
  <Affix target={() => ref.current} offsetTop={8} affixedClassName="shadow-lg">
    <div className="rounded bg-primary px-4 py-2 text-bg">操作栏</div>
  </Affix>
  {/* …长内容… */}
</div>
```

## 禁忌 / 坑

- 当真正滚动的不是 window 而是某个中间层滚动容器（如 `<main class="overflow-y-auto">`）时，必须把容器经 `target` 传入；自研实现用 capture 阶段监听 window 滚动来兜住中间层，否则吸附条会停在过期视口坐标飘出容器。详见 [[affix-fixed-must-capture-scroll-for-intermediate-container]]。
- 文档/预览这类 window 不滚动的场景，务必用 `target` 指向真实滚动框，否则永远不吸附。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [BackTop](https://hulianui.haloritual.com/components/back-top) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# Anchor

> 锚点导航 · 自研零依赖 scrollspy(IntersectionObserver) + 平滑滚动 + active CSS 变量滑动指示条 + offsetTop/二级项 · navigation/inpage

## 何时用

「左侧目录 + 右侧长文」型阅读页：API 文档、隐私协议、产品说明、分节设置表单。随滚动高亮当前章节，点击平滑滚动到目标。同层内容互斥切换用 [Tabs](https://hulianui.haloritual.com/components/tabs)；表达层级位置用 [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb)；滚动时把目录钉在视口用 [Affix](https://hulianui.haloritual.com/components/affix) 包裹本组件。

## 导入
```ts
import { Anchor, flattenAnchorItems } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `AnchorItem[]` | — | 锚点项数组，支持一层 children 形成二级 |
| offsetTop | `number` | `0` | 滚动定位时目标顶部预留的偏移(px)，避开固定页头；同时收缩 scrollspy 观测区上沿 |
| getContainer | `() => HTMLElement \| null` | `undefined`(window) | 自定义滚动容器；页面真正的滚动体不是 window 时**必须传** |

`AnchorItem`：`{ href: string; title: ReactNode; children?: AnchorItem[] }`，`href` 形如 `"#section-id"`，与页面元素 id 一一对应。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(href: string) => void` | 激活锚点变化回调（点击或滚动驱动均触发，同值不重复触发） |

## 示例
```tsx
<Anchor
  items={[
    { href: "#sec-overview", title: "概述" },
    {
      href: "#sec-guide",
      title: "快速上手",
      children: [
        { href: "#sec-install", title: "安装" },
        { href: "#sec-usage", title: "基础用法" },
      ],
    },
    { href: "#sec-faq", title: "常见问题" },
  ]}
/>
```

内层 `overflow-y-auto` 容器滚动时：
```tsx
<Anchor items={items} getContainer={() => document.querySelector("main")} />
```

## 禁忌 / 坑

- [[scrollspy-anchor-hardcoded-window-scroll-breaks-in-inner-container]]：页面真正的滚动体若是内层元素（如 app shell 里 `<main class="overflow-y-auto">` 或 `Layout.Content`）而非 window，必须传 `getContainer` 指向它，否则点击目录不滚动、高亮也不跟随 —— 因为 scrollspy 的 IntersectionObserver root 与点击滚动都会落到该容器。
- 二级以内是刻意约束：超过两层目录在窄侧栏迅速失去可读性，改用可折叠树形导航。
- 组件带 `"use client"`，可在 RSC 页面里作客户端孤岛直接用。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# AnimatedThemeToggler

> 主题切换 · View Transitions 圆形揭示明暗(复用瑚琏 useTheme + 降级) · navigation/action · #animated

## 何时用

需要一个带圆形揭示动画的明暗主题切换按钮时用（顶栏/设置区），点击从按钮位置径向扩散切换主题。只想要无动画的纯切换、或自定义控件请直接用 `useTheme()` 自行搭。

## 导入
```ts
import { AnimatedThemeToggler } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `duration` | `number` | — | 圆形揭示动画时长(ms) |
| `className` | `string` | — | 按钮类名 |
| `aria-label` | `string` | — | 无障碍标签 |

## 示例
```tsx
<AnimatedThemeToggler aria-label="切换明暗主题" />
```

## 禁忌 / 坑

- 依赖 View Transitions API 做圆形揭示，浏览器不支持时自动降级为瞬时切换（无动画），切换本身仍生效。
- 内部用 `useTheme` 读写主题、点击时读按钮位置算扩散圆心，属客户端组件；在 RSC 树里使用须确保父级有 `"use client"` 边界。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [Link](https://hulianui.haloritual.com/components/link)

<!-- ════════════════════════════════════════════════════════ -->
# BackTop

> 回顶 · 监听滚动容器超 visibilityHeight 淡入 + scrollTo smooth + prefers-reduced-motion 降级 auto(零依赖) · navigation/inpage

## 何时用

长页面滚动超过一定高度后，在右下角淡入一颗悬浮按钮，点击平滑回到顶部。只想要回顶单一动作时用它；需要把任意内容钉在视口某处用 [Affix](https://hulianui.haloritual.com/components/affix)；需要页内锚点跳转用 [Anchor](https://hulianui.haloritual.com/components/anchor)。

## 导入
```ts
import { BackTop } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| target | `() => HTMLElement \| Window \| null` | `window` | 滚动监听 & 回顶的目标容器（返回容器元素或 window）。 |
| visibilityHeight | `number` | `400` | 滚动超过该高度(px)才淡入显示。 |
| className | `string` | — | 默认 `fixed` 贴视口右下；可覆盖为 `absolute` 收进局部容器。 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `() => void` | 点击回顶后的回调（在滚动触发之后）。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 自定义悬浮按钮内容。默认上箭头图标。 |

## 示例
```tsx
// 默认：监听 window，滚动超 400px 出现
<BackTop visibilityHeight={400} />

// 收进局部滚动框：target 指向该框，className 覆盖 fixed→absolute
const ref = useRef<HTMLDivElement>(null);
<div className="relative">
  <div ref={ref} className="h-44 overflow-y-auto">{/* …内容… */}</div>
  <BackTop target={() => ref.current} visibilityHeight={80} className="absolute bottom-3 right-3" />
</div>
```

## 禁忌 / 坑

- 默认 `fixed` 贴整页视口右下；放进局部滚动区时必须同时传 `target`（指向该容器）并用 `className` 覆盖为 `absolute`，否则按钮会飘到整页角落、且监听的是 window 滚动而非容器滚动。
- 已内置 `prefers-reduced-motion` 降级（smooth → auto），无需消费侧处理。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# BeianFooter

> 备案页脚 · ICP 备案号(可多个·默认链 miit) + 公网安备(警徽 icon·默认链 mps) + 版权行 · 中国大陆合规底栏(发丝边卡片·语义 token·外链新窗·RSC) · navigation/global

## 何时用

中国大陆站点需要在页脚展示 ICP 备案号 + 公网安备 + 版权行（合规要求）时用，备案号默认自动链到 miit/mps 官方查询页。它专管「合规底栏」——顶部全局导航用 [Navbar](https://hulianui.haloritual.com/components/navbar)，侧边树菜单用 [NavMenu](https://hulianui.haloritual.com/components/nav-menu)。

## 导入
```ts
import { BeianFooter } from "@hulianui/ui"
```

## Props

`IcpRecord` = `{ number: string; href?: string }`；`PoliceRecord` 同形。`href` 不传则用默认官方链接。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| icp | `IcpRecord[]` | — | ICP 备案号，可多个（如主体下多站 -1/-2）。默认链 beian.miit.gov.cn |
| police | `PoliceRecord` | — | 公网安备号，带警徽图标。默认链 beian.mps.gov.cn |
| className | `string` | — | 类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icpLabel | `ReactNode` | 备案前缀文案，默认 `"ICP备案"` |
| copyright | `ReactNode` | 版权/补充行 |

## 示例
```tsx
// 完整：多 ICP + 公网安备 + 版权
<BeianFooter
  icp={[{ number: "闽ICP备2024073556号-1" }, { number: "闽ICP备2024073556号-2" }]}
  police={{ number: "闽公网安备35030302900030号" }}
  copyright="© 2026 瑚琏 · Abel"
/>

// 仅单个 ICP
<BeianFooter icp={[{ number: "闽ICP备2024073556号-1" }]} />
```

## 禁忌 / 坑

- 备案号文本须与工信部/公安备案系统登记的完全一致（含「号-N」后缀），否则外链查询页对不上。
- 暂无其他已知坑（纯 RSC，外链统一新窗打开）。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# Breadcrumb

> 面包屑 · 纯皮肤静态 + aria-current 当前页语义 · navigation/inpage

## 何时用

表达当前页在站点层级中的位置（首页 / 组件 / 面包屑），并提供逐级回退链接。同层内容互斥切换用 [Tabs](https://hulianui.haloritual.com/components/tabs)；翻页用 [Pagination](https://hulianui.haloritual.com/components/pagination)；有序流程用 [Stepper](https://hulianui.haloritual.com/components/stepper)。

## 导入
```ts
import { Breadcrumb } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `BreadcrumbItem[]` | — | 路径项数组，从根到当前页自左向右 |

`BreadcrumbItem`：`{ label: ReactNode; href?: string; current?: boolean }`。`href` 省略则该项不可点（当前页或不可导航的祖先）；`current` 显式标记当前页，缺省时数组末项即当前页。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| separator | `ReactNode` | 分隔符，默认 `"/"`，可换 chevron 等（装饰位自动 aria-hidden） |

## 示例
```tsx
<Breadcrumb
  items={[
    { label: "首页", href: "/" },
    { label: "组件", href: "/components" },
    { label: "面包屑" }, // 末项无 href = 当前页
  ]}
/>
```

换 chevron 分隔符：
```tsx
<Breadcrumb items={items} separator={<ChevronIcon />} />
```

## 禁忌 / 坑

暂无已知坑。注意中间项省略 `href` 即渲染为不可点的纯文本（如「归档」这类无独立页面的祖先）。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# BubbleMenu

> 气泡导航菜单 · logo 气泡 + 汉堡切换钮，点开整屏铺一组错落旋转胶囊导航 · 胶囊弹性 scale 入场 + 标签上滑淡入按序错峰(motion·零 gsap·reduced-motion) · navigation/global · #animated

## 何时用

营销站/作品集这类需要花哨全屏遮罩式主导航时用：点汉堡铺开一组错落旋转的胶囊链接。它是炫技型一级导航；要规范的多级下拉/横向导航条用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)/[NavMenu](https://hulianui.haloritual.com/components/nav-menu)，要标准应用顶栏用 [Navbar](https://hulianui.haloritual.com/components/navbar)，要展开成卡片的那种用 [CardNav](https://hulianui.haloritual.com/components/card-nav)。

## 导入
```ts
import { BubbleMenu } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `BubbleMenuItem[]` | 内置示例项 | 菜单项列表，缺省用内置示例 |
| menuAriaLabel | `string` | — | 切换按钮无障碍标签 |
| useFixedPosition | `boolean` | `false` | true=fixed（贴视口），false=absolute（贴最近定位父级） |
| animationDuration | `number` | `0.5` | 单个胶囊弹入动画时长（秒） |
| staggerDelay | `number` | `0.12` | 相邻胶囊入场错峰延迟（秒） |
| className | `string` | — | 透传根 nav 额外类名 |
| style | `CSSProperties` | — | 透传根 nav 内联样式 |

> `BubbleMenuItem`: `{ label, href, ariaLabel?, rotation?, hoverStyles? }`；`rotation` 是桌面端胶囊旋转角（移动端归零），`hoverStyles` 为 `{ bgColor?, textColor? }` 悬停反色。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onMenuClick | `(isOpen: boolean) => void` | 开合状态回调，参数为下一状态是否打开 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| logo | `ReactNode` | 左上角 logo 气泡内容：字符串当图片 src，ReactNode 直接渲染 |

## 示例
```tsx
// 默认内置项
<div className="relative h-96 overflow-hidden rounded-xl">
  <BubbleMenu logo={<span>瑚琏</span>} />
</div>

// 自定义项 + chart token 反色
const items = [
  { label: "首页", href: "#", rotation: -6, hoverStyles: { bgColor: "var(--color-chart-1)", textColor: "var(--color-primary-foreground)" } },
  { label: "文档", href: "#", rotation: 6, hoverStyles: { bgColor: "var(--color-chart-2)", textColor: "var(--color-primary-foreground)" } },
];
<BubbleMenu logo={<span>瑚琏</span>} items={items} />
```

## 禁忌 / 坑

- `useFixedPosition={false}`（默认）时根 nav 为 absolute，须有 `position: relative` 的定位父级（否则贴到更外层）；做真实站点顶栏一般要 `useFixedPosition` 或自行控制定位上下文。
- 父容器需 `overflow-hidden` 收住展开时铺满的气泡层。
- 颜色走 token 用 `--color-` 前缀。reduced-motion 下入场动效降级。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# CardNav

> 卡片导航：胶囊顶栏汉堡点击后整条高度展开，内部卡片逐张错峰 y 位移淡入 · 受控/非受控开合 + token 卡片色(motion 去 gsap·reduced-motion) · navigation/global · #animated

## 何时用

营销站顶栏需要点开后向下展开成几张分组卡片（每张含一组链接）的导航时用。它是「展开成卡片」的一级导航；要全屏铺开错落胶囊的炫技导航用 [BubbleMenu](https://hulianui.haloritual.com/components/bubble-menu)，要规范多级下拉用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)/[NavMenu](https://hulianui.haloritual.com/components/nav-menu)，要标准应用顶栏用 [Navbar](https://hulianui.haloritual.com/components/navbar)。

## 导入
```ts
import { CardNav } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items * | `CardNavItem[]` | — | 卡片数据，展开后渲染为一排（移动端一列），最多取前 3 张 |
| duration | `number` | `0.4` | 展开/收起动画时长（秒），reduced-motion 下自动归零 |
| open | `boolean` | — | 受控展开态，传入则由外部接管开合（配合 onOpenChange） |
| className | `string` | — | 透传根容器额外类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

> `CardNavItem`: `{ label, links?, bgColor?, textColor? }`；`links` 为 `CardNavLink[]`（`{ label, href?, ariaLabel? }`），`bgColor` 缺省吃 bg-surface，建议用 `var(--color-chart-1..5)` 做品牌色块。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCtaClick | `() => void` | CTA 按钮点击回调 |
| onOpenChange | `(open: boolean) => void` | 展开态变更回调（受控/非受控均触发） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| brand | `ReactNode` | 品牌区内容（logo/标题），居中显示在顶栏 |
| ctaLabel | `ReactNode` | 右侧 CTA 按钮文案（默认 `"Get Started"`）；传空串或 null 隐藏按钮 |

## 示例
```tsx
const items = [
  { label: "产品", bgColor: "var(--color-chart-1)", textColor: "var(--color-primary-foreground)",
    links: [{ label: "概览", href: "#overview" }, { label: "定价", href: "#pricing" }] },
  { label: "公司", bgColor: "var(--color-chart-2)", textColor: "var(--color-primary-foreground)",
    links: [{ label: "关于我们", href: "#about" }] },
];

// 非受控（内部管开合）
<CardNav brand="瑚琏 UI" items={items} ctaLabel="开始使用" />

// 受控
const [open, setOpen] = useState(false);
<CardNav brand="瑚琏 UI" items={items} open={open} onOpenChange={setOpen} />
```

## 禁忌 / 坑

- 受控/非受控二选一：传 `open` 即进入受控模式，必须配 `onOpenChange` 回写，否则点汉堡不会动；只想内部自管就别传 `open`。
- `items` 超过 3 张只取前 3 张（对齐原作），多的会被丢弃。
- 隐藏 CTA 用 `ctaLabel={null}` 或空串，别留默认 `"Get Started"`。
- reduced-motion 下展开动效归零但 DOM 两态一致。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# Collapsible

> 折叠区 · Base UI collapsible 薄包 + 高度过渡(复用 Accordion --collapsible-panel-height) · navigation/action

## 何时用

单块「标题 + 可折叠内容」需要展开/收起时用（详情展开、查看更多、可选高级配置）。多组并列、需要互斥单开用 [Accordion](https://hulianui.haloritual.com/components/accordion)；纯导航跳转用 [Command](https://hulianui.haloritual.com/components/command)。

## 导入
```ts
import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `Collapsible.open` | `boolean` | — | 受控展开态 |
| `Collapsible.defaultOpen` | `boolean` | `false` | 非受控初始展开态 |
| `Collapsible.disabled` | `boolean` | `false` | 禁用，不可展开 |
| `Collapsible.className` | `string` | — | 容器类名 |
| `CollapsibleTrigger.disabled` | `boolean` | `false` | 单独禁用触发器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `Collapsible.onOpenChange` | `(open: boolean) => void` | 展开态变化回调（瑚琏收敛签名，丢 Base UI eventDetails，同 Switch/Toggle 风格） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `Collapsible.children` | `ReactNode` | 包含 Trigger + Panel |
| `CollapsibleTrigger.children` | `ReactNode` | 标题行内容 |
| `CollapsiblePanel.children` | `ReactNode` | 折叠区内容 |

## 示例
```tsx
<Collapsible className="w-80">
  <CollapsibleTrigger>展开查看详情</CollapsibleTrigger>
  <CollapsiblePanel>这里是默认折叠起来的补充内容，点击标题即可展开。</CollapsiblePanel>
</Collapsible>
```

默认展开：

```tsx
<Collapsible defaultOpen className="w-80">
  <CollapsibleTrigger>收起详情</CollapsibleTrigger>
  <CollapsiblePanel>这里是默认展开的补充内容。</CollapsiblePanel>
</Collapsible>
```

## 禁忌 / 坑

- 高度过渡复用 Base UI 暴露的 `--collapsible-panel-height` CSS 变量做纯 CSS transition，padding 放 Panel 内层 div 否则收起塌不到 0；别手测 `scrollHeight` 或上动画库。详见 [[base-ui-accordion-panel-height-css-var-pure-css-transition]]。
- 受控用 `open` + `onOpenChange`，非受控用 `defaultOpen`，二者不要混用。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Link](https://hulianui.haloritual.com/components/link) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)

<!-- ════════════════════════════════════════════════════════ -->
# Command

> 命令面板 · ⌘K 模态(复用 Dialog 引擎) + 实时过滤 + 分组 + 键盘漫游(零依赖) · navigation/action

## 何时用

⌘K 召唤的命令面板：跨页跳转、操作触发、主题切换汇于一处，带实时过滤、分组与键盘漫游。需要常驻可见的一排按钮用 [Toolbar](https://hulianui.haloritual.com/components/toolbar)；需要右键弹出的上下文动作用 [ContextMenu](https://hulianui.haloritual.com/components/context-menu)；Command 是搜索式、模态、数据驱动的全局命令入口。

## 导入
```ts
import { Command, useCommandShortcut } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| open* | `boolean` | — | 受控开合。 |
| groups* | `CommandGroupData[]` | — | 命令分组（每组可带 heading）。 |
| placeholder | `string` | — | 搜索框占位符。 |
| filter | `(item: CommandItemData, query: string) => boolean` | 默认子串匹配 | 自定义过滤，返回 true 保留。默认大小写不敏感匹配 `keywords` + 字符串型 `label` + `value`。 |
| closeOnSelect | `boolean` | `true` | 执行项后是否自动关闭面板。 |
| shortcut | `boolean` | `false` | 内置 ⌘K / Ctrl+K 全局快捷键切换开合。 |
| className | `string` | — | — |
| aria-label | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange* | `(open: boolean) => void` | 开合变化回调。 |
| onSelectItem | `(value: string) => void` | 任意项执行后回调（在 `item.onSelect` 之后触发，拿到 value）。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| emptyMessage | `ReactNode` | 无匹配项时的空态文案。 |

**CommandGroupData**：`heading?: ReactNode` / `items: CommandItemData[]`。

**CommandItemData**

| 字段 | 类型 | 说明 |
|------|------|------|
| value* | `string` | 唯一值（回调入参 + key + 过滤兜底文本）。 |
| label* | `ReactNode` | 显示标题。 |
| keywords | `string` | 参与过滤的关键词（label 非字符串时建议补）。 |
| description | `ReactNode` | label 下方 muted 小字。 |
| icon | `ReactNode` | 行首图标插槽。 |
| shortcut | `ReactNode` | 行尾快捷键/标记插槽。 |
| disabled | `boolean` | — |
| onSelect | `(value: string) => void` | 该项被执行（Enter / 点击）时回调。 |

## 示例
```tsx
const groups = [
  {
    heading: "快速跳转",
    items: [
      { value: "go-orders", label: "订单管理", keywords: "order 订单 dd", icon: <ShoppingCart />, onSelect: () => router.push("/orders") },
      { value: "new-order", label: "新建订单", icon: <Plus />, shortcut: "⌘N" },
    ],
  },
];

const [open, setOpen] = useState(false);
<Command open={open} onOpenChange={setOpen} groups={groups} shortcut placeholder="输入命令或搜索…" />
```

## 禁忌 / 坑

- 始终受控：必须同时提供 `open` + `onOpenChange`。
- `label` 不是字符串时默认过滤匹配不到它，需为该项补 `keywords`（否则只能靠 `value` 命中）。
- 内置快捷键用 `shortcut` 一键开启；若想在面板外自绑触发逻辑，改用 `useCommandShortcut`，别同时开 `shortcut`。

## 相关
[ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [Link](https://hulianui.haloritual.com/components/link) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)

<!-- ════════════════════════════════════════════════════════ -->
# ContextMenu

> 右键菜单 · Base UI context-menu 原语薄包(锚到光标) + 复用 Menu 皮肤/data-highlighted + danger · navigation/action

## 何时用

在某区域右键（或长按）弹出锚到光标的上下文菜单：编辑/复制/删除、级联子菜单、分组。需要全局搜索式命令入口用 [Command](https://hulianui.haloritual.com/components/command)；需要常驻可见按钮排用 [Toolbar](https://hulianui.haloritual.com/components/toolbar)；ContextMenu 是绑定到目标区域、按需弹出的动作清单。复用 Menu 皮肤，支持 `variant="danger"` 危险项。

## 导入
```ts
import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent } from "@hulianui/ui"
```

## Props

**ContextMenuItem**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| disabled | `boolean` | — | — |
| closeOnClick | `boolean` | `true` | 点击后是否关闭菜单。 |
| label | `string` | — | 键盘 type-ahead 用文案覆盖（children 非纯文本时补）。 |
| variant | `"default" \| "danger"` | `"default"` | danger 用危险色（删除等）。 |
| className | `string` | — | — |

**ContextMenuSubTrigger**：Props `disabled` / `label` / `variant?: "default" \| "danger"` / `className`；Slots `children`。
**ContextMenuContent / ContextMenuSubContent**：Props `className`；Slots `children`。
**ContextMenuTrigger / Group / GroupLabel / Separator / Sub**：结构性组件（薄包 Base UI 原语，透传 children / className）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `MouseEventHandler<HTMLElement>` | `ContextMenuItem` 点击回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | `ContextMenuItem` 菜单项内容。 |

## 示例
```tsx
<ContextMenu>
  <ContextMenuTrigger className="flex h-28 items-center justify-center border border-dashed">
    右键点击此区域
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>编辑</ContextMenuItem>
    <ContextMenuItem disabled>归档（禁用）</ContextMenuItem>
    <ContextMenuSub>
      <ContextMenuSubTrigger>移动到</ContextMenuSubTrigger>
      <ContextMenuSubContent>
        <ContextMenuItem>项目 A</ContextMenuItem>
        <ContextMenuItem>项目 B</ContextMenuItem>
      </ContextMenuSubContent>
    </ContextMenuSub>
    <ContextMenuSeparator />
    <ContextMenuItem variant="danger">删除</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## 禁忌 / 坑

- 分组项必须包在 `ContextMenuGroup` 里、配 `ContextMenuGroupLabel` 才有正确分组语义；裸放 Item 则是无标题平铺列。
- `ContextMenuItem` 的 children 非纯文本（如带图标）时，补 `label` 供键盘 type-ahead 搜索。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [Link](https://hulianui.haloritual.com/components/link) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)

<!-- ════════════════════════════════════════════════════════ -->
# Dock

> 放大坞 · macOS 式按鼠标距离放大图标(motion 弹簧 + context 下发 mouseX) · navigation/global

## 何时用

页面底部/侧边的悬浮快捷入口栏，鼠标靠近时图标按距离弹性放大，营造 macOS Dock 观感，多用于个人站、作品集、桌面风格 demo。常规站点导航用 [Navbar](https://hulianui.haloritual.com/components/navbar)；功能性下拉/菜单条用 [Menu](https://hulianui.haloritual.com/components/menu) / [Menubar](https://hulianui.haloritual.com/components/menubar)。

## 导入
```ts
import { Dock, DockIcon } from "@hulianui/ui"
```

## Props

### Dock
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| magnification | `number` | — | 鼠标靠近时图标放大到的峰值尺寸(px) |
| distance | `number` | — | 放大影响范围半径(px) |
| iconSize | `number` | — | 静息图标尺寸(px) |
| className | `string` | — | — |

### DockIcon
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| className | `string` | — | — |

## Slots

### Dock
| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 一组 `DockIcon` |

### DockIcon
| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 单个图标内容 |

## 示例
```tsx
<Dock>
  <DockIcon><Home className="size-5" /></DockIcon>
  <DockIcon><Search className="size-5" /></DockIcon>
  <DockIcon><Settings className="size-5" /></DockIcon>
</Dock>
```

## 禁忌 / 坑

- 候选坑 skill（macos-dock-icon-needs-baked-squircle-margin、tauri-macos-hide-to-tray）均针对原生 macOS / Tauri 的系统 Dock，与本 React 组件无关，不适用。
- 放大依赖随鼠标移动下发的 `mouseX`（context + motion 弹簧），是纯客户端交互；图标统一用固定尺寸（如 `size-5`）以便放大动画一致。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# FlowingMenu

> 竖排流动菜单 · 指针近边缘判进/离向揭幕 + 循环跑马灯(文字/图片)(零依赖去 gsap·CSS keyframes + transition·token·reduced-motion) · navigation/global · #animated

## 何时用

需要一组竖排大字菜单项、悬停某项时从指针进入方向揭出一条文字/图片跑马灯的壁纸级炫技导航时用，适合作品集/品牌站的全屏目录。它是「逐项揭幕跑马灯」风格；要全屏铺开胶囊用 [BubbleMenu](https://hulianui.haloritual.com/components/bubble-menu)，要展开成卡片用 [CardNav](https://hulianui.haloritual.com/components/card-nav)，要规范多级导航用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)/[NavMenu](https://hulianui.haloritual.com/components/nav-menu)。

## 导入
```ts
import { FlowingMenu } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items * | `FlowingMenuItem[]` | — | 菜单项列表 |
| speed | `number` | `18` | 跑马灯走完一整屏的秒数，越大越慢 |
| repeat | `number` | `4` | 单个文字块里重复的份数（撑满并保证无缝循环） |

> `FlowingMenuItem`: `{ link, text, image? }`；`text` 同时作主标题与揭幕跑马灯文字，`image` 留空则只跑文字不渲染图片块。
> 还继承 `ComponentPropsWithoutRef<"nav">`（除 `children`），可透传 `className`/`style` 等。

## 示例
```tsx
// 带图片的揭幕跑马灯
<div className="h-80 overflow-hidden rounded-xl border border-border">
  <FlowingMenu
    items={[
      { link: "#discover", text: "Discover", image: "/a.jpg" },
      { link: "#build", text: "Build", image: "/b.jpg" },
    ]}
  />
</div>

// 纯文字 + 慢速大字
<FlowingMenu items={[{ link: "#home", text: "首页" }]} speed={30} repeat={6} />
```

## 禁忌 / 坑

- 根 nav 需放在有明确高度且 `overflow-hidden` 的容器里，逐项揭幕才有纵向空间且跑马灯不溢出。
- reduced-motion 下跑马灯/揭幕动效降级。
- 暂无其他已知坑。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# GooeyNav

> 胶质导航条 · 切换时白色药丸 motion 弹簧滑到目标 + 迸射一圈彩色粒子经 blur/contrast 熔成黏稠液滴(零依赖 CSS 关键帧·token 取色·受控/非受控·reduced-motion) · navigation/global · #animated

## 何时用

需要一条强动效、有"切换迸射"仪式感的水平导航条时用，多见于营销首页 / 作品集顶栏。要常规站点导航（下拉、多级、键盘可达性优先）用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) 或 [NavMenu](https://hulianui.haloritual.com/components/nav-menu)；要纯结构性站点头部布局用 [Navbar](https://hulianui.haloritual.com/components/navbar)；只要"滑动药丸"不要粒子可设 `particleCount={0}`，效果接近 [PillNav](https://hulianui.haloritual.com/components/pill-nav)。

## 导入
```ts
import { GooeyNav } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `GooeyNavItem[]` | — | 导航项数组，每项含 `label`（必填）+ `href`（可选，默认 `"#"`），至少 1 项 |
| initialActiveIndex | `number` | `0` | 初始选中下标，仅非受控（未传 `activeIndex`）时生效 |
| activeIndex | `number` | — | 受控选中下标，传入即受控，高亮位置由父级驱动 |
| animationTime | `number` | `600` | 单次迸射基准时长（ms），越大整体节奏越缓 |
| particleCount | `number` | `14` | 每次切换迸射的粒子数；`0` 关闭粒子仅保留药丸滑动 |
| particleDistances | `[number, number]` | `[86, 12]` | 粒子飞行的 [起始爆开半径, 回落收束半径]（px） |
| colors | `number[]` | `[1, 2, 3, 1, 4]` | 粒子调色板，取 chart token 序号（1..5），随机取色，吃明暗主题 |
| className | `string` | — | 透传根容器类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(index: number) => void` | 选中变化回调，点击 / 键盘 Enter\|Space 均触发 |

## 示例
```tsx
<GooeyNav
  items={[
    { label: "首页", href: "#" },
    { label: "产品", href: "#" },
    { label: "文档", href: "#" },
    { label: "关于", href: "#" },
  ]}
/>
```

仅药丸滑动、不要粒子：
```tsx
<GooeyNav items={items} particleCount={0} />
```

## 禁忌 / 坑

- 受控/非受控二选一：传了 `activeIndex` 即进入受控，组件内部不再自行改高亮，必须配合 `onChange` 回写父级 state，否则点击无反应。
- 容器需要深色底 + `overflow-hidden`：药丸与粒子靠 blur/contrast 熔色，浅底或裁切不当观感会差（showcase 用 `oklch(0.16 0.02 265)` 深底承托）。
- reduced-motion 下粒子与弹簧动画自动跳过，仅保留瞬时切换，属预期降级。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# Link

> 链接 · tone×underline + external 自动 target/rel/图标 + RSC · navigation/action

## 何时用

需要文字跳转（站内/站外链接、行内引用）时用，自带 tone 语调、下划线策略与外链安全属性。需要按钮样式的可点击操作（提交、打开弹窗）用 Button，别把 Link 当按钮使。

## 导入
```ts
import { Link, linkVariants } from "@hulianui/ui"
```

## Props

继承 `<a>` 的全部原生属性（`href`、`target`、`onClick` 等，但剔除原生 `color`）。新增：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `tone` | `"primary" \| "foreground" \| "danger"` | `"primary"` | 文字语调色 |
| `underline` | `"always" \| "hover" \| "none"` | `"hover"` | 下划线显示策略 |
| `external` | `boolean` | `false` | 外链：自动加 `target="_blank"` + `rel="noopener noreferrer"` + 尾随外链图标 |
| `href` | `string` | — | 跳转地址（原生属性） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onClick` | `(e: MouseEvent<HTMLAnchorElement>) => void` | 点击回调（透传原生 `<a>` 事件，其余 `onXxx` 同理） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `children` | `ReactNode` | 链接文字 |

## 示例
```tsx
<Link href="/docs">瑚琏文档</Link>
<Link href="https://base-ui.com" external>Base UI 官网</Link>
<Link href="#" underline="always" tone="danger">删除说明</Link>
```

## 禁忌 / 坑

- 设了 `external` 就不必再手写 `target`/`rel`，组件已自动注入安全属性并补外链图标；手写反而可能与之冲突。
- 这是原生 `<a>` 的薄包、RSC 友好，不做客户端路由拦截；接入 Next.js 路由需自行用 `<Link asChild>` 思路或包一层框架 Link（本组件未内置）。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Toolbar](https://hulianui.haloritual.com/components/toolbar) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)

<!-- ════════════════════════════════════════════════════════ -->
# Menu

> 下拉菜单 · Base UI 命令式 + Item/分隔/分组 + danger · navigation/global

## 何时用

点击触发器弹出的一组操作项（编辑/复制/删除等），适合表格行操作、卡片更多按钮、头像账号菜单。需要 hover 展开的 mega 站点导航用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)；多个顶层菜单横排成 File/Edit/View 菜单条用 [Menubar](https://hulianui.haloritual.com/components/menubar)。

## 导入
```ts
import { Menu, MenuTrigger, MenuContent, MenuItem, MenuSeparator, MenuGroup, MenuGroupLabel, menuItemVariants } from "@hulianui/ui"
```

## Props

### MenuContent
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | 弹出方位 |
| align | `"start" \| "center" \| "end"` | `"start"` | 沿触发器的对齐 |
| sideOffset | `number` | — | 与触发器的间距(px) |
| className | `string` | — | — |

### MenuItem
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| disabled | `boolean` | `false` | 禁用 |
| closeOnClick | `boolean` | `true` | 点击后是否关闭菜单 |
| label | `string` | — | 键盘 type-ahead 的文案覆盖 |
| variant | `"default" \| "danger"` | `"default"` | danger 为危险操作（红色） |
| className | `string` | — | — |

`MenuTrigger` 用 `render={<Button />}` 把任意元素作触发器。

## Events

### MenuItem
| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `MouseEventHandler<HTMLElement>` | 点击回调 |

## Slots

### MenuContent
| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 菜单项 |

### MenuItem
| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 项内容 |

## 示例
```tsx
<Menu>
  <MenuTrigger render={<Button>菜单</Button>} />
  <MenuContent side="bottom" align="start">
    <MenuItem>编辑</MenuItem>
    <MenuItem disabled>归档（禁用）</MenuItem>
    <MenuSeparator />
    <MenuItem variant="danger">删除</MenuItem>
  </MenuContent>
</Menu>
```

含分组（`MenuGroupLabel` 必须裹在 `MenuGroup` 内）：
```tsx
<MenuContent>
  <MenuGroup>
    <MenuGroupLabel>操作</MenuGroupLabel>
    <MenuItem>编辑</MenuItem>
    <MenuItem>复制</MenuItem>
  </MenuGroup>
</MenuContent>
```

## 禁忌 / 坑

- [[base-ui-menu-group-label-requires-menu-group-wrapper]]：`MenuGroupLabel` 直接放进 `MenuContent`（不裹 `MenuGroup`）会在「点开菜单」那一刻抛 `MenuGroupRootContext is missing`，触发器渲染正常但点击崩页 —— 分组标签必须包在 `MenuGroup` 里。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menubar](https://hulianui.haloritual.com/components/menubar) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# Menubar

> 菜单条 · Base UI menubar 薄包(File/Edit/View 顶层项+下拉) + dogfood Menu 皮肤 + 键盘切换/方向键漫游 · navigation/global

## 何时用

桌面应用式的水平菜单条：多个顶层入口（文件/编辑/视图）各带下拉，方向键可在顶层间漫游、相邻菜单自动接力展开。只有单个触发器弹一组操作用 [Menu](https://hulianui.haloritual.com/components/menu)；站点主导航 mega 面板用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)。

## 导入
```ts
import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem, MenubarSeparator, MenubarGroup, MenubarGroupLabel } from "@hulianui/ui"
```

## Props

根 `Menubar` 透传 Base UI `Menubar`，叠加 `className`；`MenubarMenu`/`MenubarTrigger` 透传 Base UI Menu 对应部件。下拉项部件（Item/Separator/Group/GroupLabel）复用 [Menu](https://hulianui.haloritual.com/components/menu) 皮肤，用法一致（如 `MenubarItem` 支持 `variant="danger"`）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| modal | `boolean` | `true` | 模态（打开时背景不可交互） |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 菜单条方向 |
| loopFocus | `boolean` | `true` | 方向键漫游到末项后回环 |
| disabled | `boolean` | `false` | 禁用整条 |
| className | `string` | — | — |

`MenubarMenu` 透传 Base UI Menu.Root（`open`/`defaultOpen`/`onOpenChange` 等）；`MenubarTrigger` 透传 Menu.Trigger。

## Events

### MenubarMenu
| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange | `(open: boolean) => void` | 顶层菜单展开/收起回调（透传 Base UI `Menu.Root`） |

## 示例
```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>文件</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>新建窗口</MenubarItem>
      <MenubarSeparator />
      <MenubarItem variant="danger">退出</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
  {/* 更多顶层菜单… */}
</Menubar>
```

## 禁忌 / 坑

- 同 [Menu](https://hulianui.haloritual.com/components/menu)：`MenubarGroupLabel` 须裹在 `MenubarGroup` 内，否则打开菜单时抛缺 GroupRootContext。
- 顶层只放 `MenubarTrigger` + `MenubarContent`，菜单项放在 Content 内，别把 `MenubarItem` 直接挂到 `Menubar` 上。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# Navbar

> 导航栏 · 复合 Brand/Content/Item/MenuToggle + sticky + 移动端切换 · navigation/global

## 何时用

页面顶部全局导航条（品牌 + 主菜单 + 移动端汉堡切换）用。它是横向顶栏复合件——左侧纵向 Sider 树菜单用 [NavMenu](https://hulianui.haloritual.com/components/nav-menu)，带下拉面板的多级导航用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)，页脚备案行用 [BeianFooter](https://hulianui.haloritual.com/components/beian-footer)。

## 导入
```ts
import { Navbar, NavbarBrand, NavbarContent, NavbarItem, NavbarMenuToggle } from "@hulianui/ui"
```

## Props

各子件均继承对应原生元素属性。

**Navbar**（`<nav>`）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sticky | `boolean` | — | 是否 sticky 吸顶 |
| bordered | `boolean` | — | 是否显示底部分隔边框 |

**NavbarContent**（`<ul>`）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| justify | `"start" \| "center" \| "end"` | — | 内容对齐方向 |

**NavbarItem**（`<li>`）

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| isActive | `boolean` | — | 当前激活项（aria-current + 高亮） |

**NavbarMenuToggle**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| isOpen | `boolean` | — | 受控展开态 |
| aria-label | `string` | 按 isOpen 切换 | 无障碍标签 |
| className | `string` | — | 类名 |

`NavbarBrand` 为纯容器，无专属 prop。

## Events

**NavbarMenuToggle**

| 事件 | 类型 | 说明 |
|------|------|------|
| onToggle | `() => void` | 切换回调 |

## Slots

`Navbar` / `NavbarContent` / `NavbarItem` / `NavbarBrand` 均接受 `children`。

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 各容器子件的子内容 |

## 示例
```tsx
function Header() {
  const [open, setOpen] = useState(false);
  return (
    <Navbar sticky bordered>
      <NavbarMenuToggle isOpen={open} onToggle={() => setOpen((v) => !v)} />
      <NavbarBrand>瑚琏</NavbarBrand>
      <NavbarContent justify="end" className="hidden sm:flex">
        <NavbarItem isActive>组件</NavbarItem>
        <NavbarItem>文档</NavbarItem>
        <NavbarItem>主题</NavbarItem>
      </NavbarContent>
    </Navbar>
  );
}
```

## 禁忌 / 坑

- `NavbarMenuToggle` 是受控件，`isOpen`/`onToggle` 由你自己维护 state，移动端展开菜单也需你按 `open` 自行条件渲染（组件不替你管面板开合）。
- 暂无其他已知坑。

## 相关
[BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# NavigationMenu

> 导航菜单 · Base UI navigation-menu 薄包(mega 面板/共享 Viewport 尺寸形变) + 触发器/内容/链接 + chevron 旋转 · navigation/global

## 何时用

站点顶部主导航，需要把多个入口归到「产品 / 资源」等下拉里，且下拉内容是 mega 面板（多列卡片、图标+描述）时用。纯链接横排不带下拉用 [Navbar](https://hulianui.haloritual.com/components/navbar)；点击触发的指令式下拉菜单（编辑/删除等动作）用 [Menu](https://hulianui.haloritual.com/components/menu)；桌面应用的 File/Edit/View 菜单条用 [Menubar](https://hulianui.haloritual.com/components/menubar)。

## 导入
```ts
import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink } from "@hulianui/ui"
```

## Props

根 `NavigationMenu` 透传 Base UI `NavigationMenu.Root`，各子件透传对应 Base UI 部件，均叠加 `className`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `any` | — | 受控：当前展开项的 value |
| defaultValue | `any` | — | 非受控初始展开项 |
| delay | `number` | `100` | 悬停到开启的延迟(ms)，`0` 为 hover 即开 |
| closeDelay | `number` | — | 移出到关闭的延迟(ms) |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 菜单条方向 |
| className | `string` | — | 根容器样式 |

子件（`NavigationMenuItem` 需 `value`；`NavigationMenuLink` 透传 `href` 等锚点属性）均接受 `className` 并透传 Base UI 同名部件属性。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value) => void` | 展开项变化回调（透传 Base UI `NavigationMenu.Root`） |

## 示例
```tsx
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem value="products">
      <NavigationMenuTrigger>产品</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="grid grid-cols-2 gap-1">{/* NavigationMenuLink 列表 */}</div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem value="pricing">
      <NavigationMenuLink href="/pricing">价格</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

## 禁忌 / 坑

- [[base-ui-navigation-menu-content-must-stay-in-flow-for-popup-size-measure]]：别给激活的 `NavigationMenuContent` 加 `position: absolute`。Base UI 靠测量内容的自然尺寸来驱动共享 Viewport 的 `--popup-width/height` 形变；脱离文档流会让自然尺寸变 0，面板塌成 ~2×2px 看不见（构建和单测都过、屏上却空白）。
- 纯链接项（无下拉）直接在 `NavigationMenuItem` 里放 `NavigationMenuLink`，不要套 Trigger/Content。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# NavMenu

> 侧边导航菜单 · 自研零依赖 · inline 手风琴/collapsed 图标飞出 + 树形 items + 选中/展开受控 + 纯 CSS grid 高度过渡 + WAI-ARIA tree 键盘漫游 · navigation/global

## 何时用

中后台左侧 Sider 树形导航（多级菜单、可收起、可受控选中/展开）用，数据驱动 `items`，支持 inline 手风琴与 collapsed 图标飞出两种形态，还能给每行挂行尾操作（如会话列表的删除）。横向顶栏用 [Navbar](https://hulianui.haloritual.com/components/navbar)，带下拉面板的导航用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu)，右键/上下文菜单用 [Menu](https://hulianui.haloritual.com/components/menu)。

## 导入
```ts
import { NavMenu } from "@hulianui/ui"
```

## Props

`items` 元素为 `NavMenuNode = NavMenuItem | NavMenuGroup`。`NavMenuItem` = `{ key; label; icon?; href?; disabled?; actions?; children? }`（有 `children` 即可展开父项，有 `href` 渲染 `<a>` 否则 `<button>`）；`NavMenuGroup` = `{ type:"group"; key; label; children }`（不可折叠小标题，key 不进选中/展开态）。继承 `<nav>` 原生属性（`onSelect` 除外）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `NavMenuNode[]` | — | 树形菜单数据 |
| mode | `"inline" \| "collapsed"` | `"inline"` | inline=手风琴内联展开；collapsed=Sider 收起态图标 + 悬浮飞出子菜单 |
| selectedKeys | `string[]` | — | 选中态（受控） |
| defaultSelectedKeys | `string[]` | — | 选中态（非受控初值） |
| openKeys | `string[]` | — | 展开态（受控） |
| defaultOpenKeys | `string[]` | — | 展开态（非受控初值） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(key: string, item: NavMenuItem) => void` | 点击叶子项触发 |
| onOpenChange | `(openKeys: string[]) => void` | 展开态变化回调 |

## 示例
```tsx
// 受控选中 + 行尾删除（actions 槽用 group-hover/nav-row 钩子做 hover 才显）
function ConvoNav() {
  const [sel, setSel] = useState<string[]>(["c1"]);
  return (
    <NavMenu
      items={[
        {
          type: "group",
          key: "today",
          label: "今天",
          children: [
            { key: "c1", label: "瑚琏组件库怎么接入", actions: <DeleteAction /> },
            { key: "c2", label: "帮我润色一封周报", actions: <DeleteAction /> },
          ],
        },
      ]}
      selectedKeys={sel}
      onSelect={(k) => setSel([k])}
    />
  );
}
```

## 禁忌 / 坑

- 行尾操作放 `actions` 槽，组件会渲在 treeitem 按钮/链接【之外】（绝对覆盖行右侧）。**别把 `<button>` 等交互元素直接塞进 `label`**——嵌进 treeitem 按钮是非法 HTML，会触发 hydration 报错。`actions` 仅 inline 态生效。
- 高度过渡用纯 CSS `grid-template-rows` 0fr→1fr，不靠 JS 测高，嵌套展开也不抖。参见 [[nested-collapsible-height-via-css-grid-rows-not-js-measure]]。
- 选中/展开态可受控（`selectedKeys`/`openKeys` + 回调）或非受控（`default*`），勿混用同一维度。
- SCAFFOLD 列的 menubar/SwiftUI/Tauri 原生菜单类坑均不适用本组件（它是纯 React WAI-ARIA tree，非系统托盘菜单）。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar) · [Dock](https://hulianui.haloritual.com/components/dock)

<!-- ════════════════════════════════════════════════════════ -->
# PageHeader

> 页头骨架 · 返回/面包屑/标题/标签/操作区/Tabs 页脚(dogfood 复用·零依赖·可 RSC) · navigation/inpage

## 何时用

详情页 / 管理页顶部的页头骨架：统一安放返回箭头、面包屑、主标题、状态标签、右侧操作区和底部 Tabs。各槽位直接 dogfood 传入瑚琏 [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) / Chip / [Tabs](https://hulianui.haloritual.com/components/tabs)；只需要面包屑导航本身用 Breadcrumb，PageHeader 是把整块页头排版好。不传 `onBack` 时可保持 RSC（无回调）。

## 导入
```ts
import { PageHeader } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| backLabel | `string` | `"返回"` | 返回按钮的无障碍标签。 |
| bordered | `boolean` | `false` | 是否在页头底部渲染分隔线（复用 `<Separator/>`）。 |

> 另继承 `HTMLAttributes<HTMLElement>`（除 `title`，因其类型被改为 ReactNode）。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onBack | `() => void` | 提供则在标题左侧渲染返回箭头按钮，点击触发该回调（带回调 → 消费侧为 client）。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 主标题。 |
| subTitle | `ReactNode` | 副标题，内联于标题右侧，中性弱化色。 |
| breadcrumb | `ReactNode` | 面包屑区（标题行上方），传入瑚琏 `<Breadcrumb/>`。 |
| tags | `ReactNode` | 状态标签区（贴标题右侧），传入 `<Chip/>`/`<Badge/>` 等。 |
| extra | `ReactNode` | 右侧操作区（按钮组等），窄屏自动换行到标题下方。 |
| footer | `ReactNode` | 底部附加区，常放 `<Tabs/>`。 |

## 示例
```tsx
// 极简：仅标题 + 操作（可 RSC，无 onBack）
<PageHeader title="用户管理" extra={<Button variant="solid" size="sm">新建用户</Button>} />

// 完整页头
<PageHeader
  onBack={() => router.back()}
  breadcrumb={<Breadcrumb items={[{ label: "首页", href: "/" }, { label: "订单详情" }]} />}
  title="订单 #20260603-8821"
  subTitle="共 6 件商品"
  tags={<Chip tone="brand" variant="soft" size="sm">进行中</Chip>}
  extra={<Button variant="solid" size="sm">编辑</Button>}
  footer={<Tabs defaultValue="detail"><TabsList><TabsTab value="detail">详情</TabsTab></TabsList></Tabs>}
  bordered
/>
```

## 禁忌 / 坑

- `title` 为 ReactNode，与 `HTMLAttributes.title?: string` 冲突，类型已 `Omit<"title">`——别再往 DOM 透传字符串 title。
- 传 `onBack` 即引入回调，该消费组件必须是 client；纯展示页头不传 onBack 可保持 server 组件。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top)

<!-- ════════════════════════════════════════════════════════ -->
# Pagination

> 分页器 · 纯皮肤受控 + 页码区间算法(省略号) · navigation/inpage

## 何时用

列表/表格分页切换，已知总页数、点页码或上下页跳转。表达层级位置用 [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb)；同层内容互斥切换用 [Tabs](https://hulianui.haloritual.com/components/tabs)。需要纯算法拿可见页码序列（自己渲染）可单独用导出的 `getPaginationRange`。

## 导入
```ts
import { Pagination, getPaginationRange } from "@hulianui/ui"
```

## Props

分页器**受控 only**：必须由外部 state 持有 `page` 并在 `onPageChange` 里 setState。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| page* | `number` | — | 当前页（1 起），受控 |
| total* | `number` | — | 总页数 |
| siblingCount | `number` | `1` | 当前页左右各显示的页码数 |
| showFirstLast | `boolean` | `false` | 是否显示「跳首页/末页」按钮 |
| disabled | `boolean` | `false` | 禁用整个分页器 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onPageChange* | `(page: number) => void` | 页码变更回调（点击页码/上下页/首末页时触发，已夹紧到 `[1, total]`） |

## 示例
```tsx
function Demo() {
  const [page, setPage] = useState(1);
  return <Pagination page={page} total={20} onPageChange={setPage} />;
}
```

带首末页跳转 + 更宽窗口：
```tsx
<Pagination page={page} total={20} onPageChange={setPage} siblingCount={2} showFirstLast />
```

## 禁忌 / 坑

- [[pagination-range-single-gap-fill-not-ellipsis]]：页码序列由 `getPaginationRange` 生成 —— 当两个展示页之间**只隐藏了 1 页**时直接补出那个页码，而不是显示「…」（省略号仅在 gap > 1 时出现），避免出现 `1 … 3` 这种只藏一页还占省略号的丑态。模型同 MUI usePagination。
- 组件不持有内部页码态，忘了在 `onPageChange` 里更新 `page` 会点不动。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# PillNav

> 胶囊导航条 · 悬停底部圆涨满 + 文案翻转反相 + 激活指示圆点(纯 CSS·零依赖·RSC 安全·reduced-motion) · navigation/global · #animated

## 何时用

需要一条轻量、纯 CSS、可在 server component 直接渲染的胶囊式站点头部导航时用，常配左侧品牌 logo。要切换时迸射粒子的更强动效用 [GooeyNav](https://hulianui.haloritual.com/components/gooey-nav)；要常规多级 / 下拉菜单用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) 或 [NavMenu](https://hulianui.haloritual.com/components/nav-menu)；要纯结构性站点头部用 [Navbar](https://hulianui.haloritual.com/components/navbar)。本组件只渲染 `<a>`，激活态由 `activeHref` 字符串匹配驱动而非下标。

## 导入
```ts
import { PillNav } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLElement>, "children">`（透传到根 `<nav>`）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `PillNavItem[]` | — | 导航项列表，每项 `{ href, label, ariaLabel? }`，每项渲染为一颗胶囊 |
| activeHref | `string` | — | 当前激活项的 href，命中后胶囊常驻反相态 + 底部点亮指示圆点 |
| logoHref | `string` | `items[0].href` → `"#"` | logo 区链接地址 |
| logoAriaLabel | `string` | `"Home"` | logo 区无障碍标签 |
| initialLoadAnimation | `boolean` | `true` | 首次加载入场动画（logo 弹入 + 胶囊展开），reduced-motion 下自动跳过 |
| className | `string` | — | 合并到根 `<nav>` 的类名 |

`PillNavItem`：`{ href: string; label: string; ariaLabel?: string }`，`ariaLabel` 缺省回退到 `label`。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| logo | `React.ReactNode` | 左侧圆形 logo 区内容（通常放 `<img>` 或图标），悬停旋转一圈；不传则不渲染 logo 区 |

## 示例
```tsx
<PillNav
  items={[
    { href: "#home", label: "Home" },
    { href: "#features", label: "Features" },
    { href: "#pricing", label: "Pricing" },
    { href: "#docs", label: "Docs" },
  ]}
  activeHref="#home"
  logo={<Mark />}
/>
```

无 logo 的纯导航：
```tsx
<PillNav items={items} activeHref="#features" />
```

## 禁忌 / 坑

- 激活靠 href 字面匹配：`activeHref` 必须与某个 `items[].href` **完全相等**才会点亮，站内路由要保证传入的当前路径与配置的 href 字符串一致（含锚点/斜杠）。
- 参见 [[sliding-pill-indicator-inverted-text-lives-in-pill-z-above]]：滑动药丸 + 选中项反相文字这类结构，反相文字必须活在药丸内、z 轴位于药丸之上，否则会出现"高亮先到、文字才变白"或浅色主题下激活态丢色；本组件已内置正确叠层。
- 参见 [[flex-row-pill-offset-from-inline-child-in-block-wrapper]]：胶囊排成 `flex items-center` 一行时，若某颗（如带定位包裹的 logo）是 inline 元素套普通 block `<div>`，会因继承行高使其按行盒基线下沉、与兄弟胶囊错位几像素；包裹层用 `flex items-center` + `leading-none` 即可对齐。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# StaggeredMenu

> 侧滑分层导航菜单 · 触发按钮（菜单↔关闭文字滚动 + 加号旋转 225°）唤起面板 · 多层色层错峰滑入做叠纸质感 + 主条目自下而上带旋转依次入场 + 序号/社交链接尾随淡入（motion 去 gsap·token·reduced-motion） · navigation/global · #animated

## 何时用

需要一个有强叠纸/错峰仪式感的侧滑全屏（或全容器）抽屉式导航时用，常见于品牌站 / 作品集的汉堡菜单。要水平常驻导航条用 [PillNav](https://hulianui.haloritual.com/components/pill-nav) 或 [GooeyNav](https://hulianui.haloritual.com/components/gooey-nav)；要功能性下拉/多级菜单用 [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) 或 [Menu](https://hulianui.haloritual.com/components/menu)。本组件内部 `absolute` 定位，需放进 `relative + 固定高度 + overflow-hidden` 的承托容器；整页罩层场景设 `isFixed`。

## 导入
```ts
import { StaggeredMenu } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `StaggeredMenuItem[]` | — | 主条目列表，空数组渲染占位「No items」 |
| socialItems | `StaggeredMenuSocial[]` | — | 社交链接列表，配合 `displaySocials` 在面板底部展示 |
| position | `"left" \| "right"` | `"right"` | 面板与色层滑出方向 |
| colors | `string[]` | chart-4 / chart-1 两层 | 面板背后多层色层颜色（错峰滑入），最多取前 4 个；建议喂 `var(--color-chart-*)` token |
| displaySocials | `boolean` | `true` | 是否展示底部社交区（仅 `socialItems` 非空才实际渲染） |
| displayItemNumbering | `boolean` | `true` | 是否给主条目展示前缀序号（01 / 02 …） |
| accentColor | `string` | `var(--color-primary)` | 强调色（序号 / 社交标题 / 条目 hover） |
| isFixed | `boolean` | `false` | 是否 `fixed` 铺满视口（整页罩层）；否则相对父容器铺满 |
| closeOnClickAway | `boolean` | `true` | 点击面板外区域是否关闭 |
| className | `string` | — | 透传根容器类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

`StaggeredMenuItem`：`{ label; link?; ariaLabel? }`（`link` 缺省渲染为不可跳转 span）。`StaggeredMenuSocial`：`{ label; link }`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onMenuOpen | `() => void` | 菜单打开回调 |
| onMenuClose | `() => void` | 菜单关闭回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| brand | `ReactNode` | 触发按钮旁的品牌槽（通常放 logo 文字或图标），缺省渲染默认文字「瑚琏」 |

## 示例
```tsx
<div className="relative h-96 overflow-hidden rounded-xl border border-border bg-background">
  <StaggeredMenu
    items={[
      { label: "首页", link: "#home" },
      { label: "产品", link: "#product" },
      { label: "关于", link: "#about" },
    ]}
    socialItems={[
      { label: "GitHub", link: "https://github.com" },
      { label: "知乎", link: "https://zhihu.com" },
    ]}
  />
</div>
```

整页罩层 + 左侧滑入：
```tsx
<StaggeredMenu isFixed position="left" items={items} socialItems={socials} brand="HULIAN" />
```

## 禁忌 / 坑

- 非 `isFixed` 时必须放进 `relative + 固定高度 + overflow-hidden` 容器：组件内部 `absolute` 定位，缺承托会塌缩或溢出（showcase 用 `relative h-96 overflow-hidden`）。
- `displaySocials` 为 `true` 但 `socialItems` 为空时底部社交区不渲染，二者需同时给。
- 色层 `colors` 喂主题色请用 `var(--color-chart-*)` 这类带 `--color-` 前缀的 token；裸 `var(--primary)` 在 SVG/canvas 取色处可能不解析。
- reduced-motion 下错峰入场退化为直接显示，属预期。

## 相关
[Navbar](https://hulianui.haloritual.com/components/navbar) · [BeianFooter](https://hulianui.haloritual.com/components/beian-footer) · [NavMenu](https://hulianui.haloritual.com/components/nav-menu) · [NavigationMenu](https://hulianui.haloritual.com/components/navigation-menu) · [Menu](https://hulianui.haloritual.com/components/menu) · [Menubar](https://hulianui.haloritual.com/components/menubar)

<!-- ════════════════════════════════════════════════════════ -->
# Stepper

> 步骤条 · MUI 桥 + active/completed 走瑚琏 token · navigation/inpage · MUI 桥

## 何时用

基于 MUI 的极简横向步骤条，仅 `steps` + `activeStep` 受控展示当前进度。新代码优先用零依赖、功能更全（垂直/状态派生/可点击/描述/图标）的 [Steps](https://hulianui.haloritual.com/components/steps)；本组件保留作 MUI 桥过渡，需要 MUI 主题一致性时才用。

## 导入
```ts
import { Stepper } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| steps* | `StepItem[]` | — | 步骤数组，每项 `{ label: ReactNode }`。 |
| activeStep* | `number` | — | 受控当前步（0-based）。值 ≥ steps.length 表示全部完成。 |
| className | `string` | — | — |

## 示例
```tsx
const steps = [{ label: "下单" }, { label: "付款" }, { label: "发货" }, { label: "完成" }];

<Stepper steps={steps} activeStep={1} />
```

## 禁忌 / 坑

- `activeStep` 是纯受控、0-based；index < activeStep 显示为已完成，== 为进行中。要表达「全部完成」传 `activeStep={steps.length}`。
- 它是 MUI 桥（取非 overlay 件），样式经 emotion theme 读瑚琏 token；功能远弱于 Steps，能用 Steps 就别用它。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top)

<!-- ════════════════════════════════════════════════════════ -->
# Steps

> 步骤条(原生) · 零依赖数据驱动 items + 水平/垂直 + wait/process/finish/error 状态派生 + 可点击受控(替代 MUI Stepper 桥 · 分步表单/审批流) · navigation/inpage

## 何时用

零依赖、数据驱动的步骤条，用于分步表单、订单流转、审批流的进度展示，支持水平/垂直、状态派生、可点击受控、描述/图标。是 [Stepper](https://hulianui.haloritual.com/components/stepper)（MUI 桥）的首选替代——新代码一律用 Steps，功能更全且不引 MUI。

## 导入
```ts
import { Steps } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `StepsItem[]` | — | 步骤数组，见下表。 |
| current | `number` | `0` | 当前步骤索引（从 0 起），用于派生各步状态。 |
| status | `"process" \| "finish" \| "error"` | `"process"` | 当前步（index===current）的状态。 |
| direction | `"horizontal" \| "vertical"` | `"horizontal"` | 排布方向。 |
| size | `"sm" \| "md"` | `"md"` | 尺寸。 |
| className | `string` | — | — |

**StepsItem**

| 字段 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 步骤标题。 |
| description | `ReactNode` | 标题下方次要文案。 |
| icon | `ReactNode` | 自定义指示器内容（覆盖默认序号/状态图标）。 |
| status | `"wait" \| "process" \| "finish" \| "error"` | 显式状态，覆盖由 current 派生的状态。 |
| disabled | `boolean` | 禁用：不可点击、降透明度。 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(index: number) => void` | 提供则每步可点击，点击非禁用步触发（index）。 |

## 示例
```tsx
const ORDER = [
  { title: "提交申请", description: "填写报销单据" },
  { title: "部门审批", description: "主管复核金额" },
  { title: "财务打款", description: "对公转账" },
  { title: "完成", description: "归档结案" },
];

// 静态进度
<Steps items={ORDER} current={1} />

// 可点击 + 受控
const [current, setCurrent] = useState(1);
<Steps items={ORDER} current={current} onChange={setCurrent} />
```

## 禁忌 / 坑

- 步状态默认由 `current` 派生：index < current → finish，== current → `status`（默认 process），> current → wait；要单独标某步可在该 `StepsItem.status` 显式覆盖。
- 传了 `onChange` 才可点击；点击禁用步（`disabled`）不触发回调。

## 相关
[Tabs](https://hulianui.haloritual.com/components/tabs) · [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top)

<!-- ════════════════════════════════════════════════════════ -->
# Tabs

> 选项卡 · Base UI 无浮层 + underline/solid 滑块 · navigation/inpage

## 何时用

同一区域内切换若干并列内容面板（账户/密码/团队），内容互斥、平级、无层级。表达页面在站点中的位置用 [Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb)；长文内随阅读进度高亮的目录用 [Anchor](https://hulianui.haloritual.com/components/anchor)；有序步骤流程用 [Stepper](https://hulianui.haloritual.com/components/stepper)。

## 导入
```ts
import { Tabs, TabsList, TabsTab, TabsPanel, tabsListVariants } from "@hulianui/ui"
```

## Props

`Tabs` 透传 Base UI `Tabs.Root`（`value`/`defaultValue`/`onValueChange`/`orientation`），默认非受控。皮肤变体在 `TabsList` 上。

### Tabs（根）
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `any` | — | 受控当前 tab |
| defaultValue | `any` | — | 非受控初始 tab |
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 方向 |

### TabsList
| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"underline" \| "solid"` | `"underline"` | 皮肤：下划滑块 / 实心药丸 |
| className | `string` | — | — |

`TabsTab` 接 `value`（必填）、`disabled`、`className`；`TabsPanel` 接 `value`、`className`。

## Events

### Tabs（根）
| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value) => void` | 切换回调（透传 Base UI `Tabs.Root`） |

## 示例
```tsx
<Tabs defaultValue="account" className="w-80">
  <TabsList variant="underline">
    <TabsTab value="account">账户</TabsTab>
    <TabsTab value="password">密码</TabsTab>
    <TabsTab value="team" disabled>团队</TabsTab>
  </TabsList>
  <TabsPanel value="account">管理你的账户资料与偏好设置。</TabsPanel>
  <TabsPanel value="password">在这里修改登录密码。</TabsPanel>
  <TabsPanel value="team">邀请成员、分配角色。</TabsPanel>
</Tabs>
```

## 禁忌 / 坑

- [[base-ui-tabs-indicator-slider-via-active-tab-css-vars]]：滑块靠 Base UI 写在 indicator 上的 `--active-tab-*` CSS 变量 + 纯 CSS transition 实现，不引动画库。坑点：激活态钩子是 `data-active` 而非 `data-selected`，写错样式不生效；jsdom 单测无 ResizeObserver 也能跑（指示条几何不会真渲染）。

## 相关
[Breadcrumb](https://hulianui.haloritual.com/components/breadcrumb) · [Pagination](https://hulianui.haloritual.com/components/pagination) · [Anchor](https://hulianui.haloritual.com/components/anchor) · [Affix](https://hulianui.haloritual.com/components/affix) · [BackTop](https://hulianui.haloritual.com/components/back-top) · [Stepper](https://hulianui.haloritual.com/components/stepper)

<!-- ════════════════════════════════════════════════════════ -->
# Toolbar

> 工具栏 · Base UI role=toolbar + 键盘漫游 + Button/Group/Separator · navigation/action

## 何时用

一排相关的操作控件（富文本格式、对齐、分享等）横/竖排，带 `role=toolbar` 与方向键漫游焦点。需要点击弹出的命令清单用 [ContextMenu](https://hulianui.haloritual.com/components/context-menu)；需要 ⌘K 搜索式命令面板用 [Command](https://hulianui.haloritual.com/components/command)；Toolbar 是常驻可见的一排按钮/开关。

## 导入
```ts
import { Toolbar, ToolbarButton, ToolbarToggle, ToolbarGroup, ToolbarSeparator } from "@hulianui/ui"
```

## Props

**Toolbar**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 排布方向。 |
| disabled | `boolean` | — | 整条禁用。 |
| loopFocus | `boolean` | `true` | 键盘导航到末端时是否回环。 |
| aria-label | `string` | — | 工具栏无障碍标签。 |
| className | `string` | — | — |

**ToolbarButton**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| disabled | `boolean` | — | — |
| aria-label | `string` | — | 图标按钮需补无障碍标签。 |
| className | `string` | — | — |

**ToolbarToggle**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| pressed | `boolean` | — | 受控选中态（按下=开）。 |
| defaultPressed | `boolean` | `false` | 非受控初始选中态。 |
| disabled | `boolean` | — | — |
| aria-label | `string` | — | — |
| className | `string` | — | — |

**ToolbarGroup**：Props `disabled` / `aria-label` / `className`；Slots `children`。
**ToolbarSeparator**：Props `orientation?: "horizontal" \| "vertical"` / `className`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `(e: MouseEvent<HTMLButtonElement>) => void` | `ToolbarButton` 点击回调。 |
| onPressedChange | `(pressed: boolean) => void` | `ToolbarToggle` 选中态变化回调。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | `Toolbar` / `ToolbarButton` / `ToolbarToggle` / `ToolbarGroup` 各自的子内容。 |

## 示例
```tsx
<Toolbar aria-label="文本格式">
  <ToolbarGroup>
    <ToolbarToggle aria-label="加粗" defaultPressed><Bold className="size-4" /></ToolbarToggle>
    <ToolbarToggle aria-label="斜体"><Italic className="size-4" /></ToolbarToggle>
  </ToolbarGroup>
  <ToolbarSeparator />
  <ToolbarButton aria-label="分享"><Share2 className="size-4" />分享</ToolbarButton>
</Toolbar>
```

## 禁忌 / 坑

- 纯图标的 `ToolbarButton`/`ToolbarToggle` 必须补 `aria-label`，否则屏幕阅读器读不出。
- `ToolbarToggle` 受控（`pressed`）与非受控（`defaultPressed`）二选一，混用会导致状态不一致。

## 相关
[Command](https://hulianui.haloritual.com/components/command) · [ContextMenu](https://hulianui.haloritual.com/components/context-menu) · [Accordion](https://hulianui.haloritual.com/components/accordion) · [Collapsible](https://hulianui.haloritual.com/components/collapsible) · [Link](https://hulianui.haloritual.com/components/link) · [AnimatedThemeToggler](https://hulianui.haloritual.com/components/animated-theme-toggler)


# ━━━━━━━━ 反馈 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# Alert

> 提示条 · tone×variant 皮肤 + a11y role · feedback/message

## 何时用

页面/区块内的静态提示卡片（表单校验汇总、状态说明、内联警告），常驻直到调用方移除。横贯容器顶部全宽公告 bar 用 [Banner](https://hulianui.haloritual.com/components/banner)；命令式自动消失的轻提示用 [Toast](https://hulianui.haloritual.com/components/toast)；四角弹出的富通知用 [Notification](https://hulianui.haloritual.com/components/notification)。

## 导入
```ts
import { Alert, alertVariants } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`（除 `title`）+ `alertVariants` 的变体：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"neutral"｜"info"｜"success"｜"warning"｜"danger"` | `"info"` | 语气色 |
| variant | `"soft"｜"outline"` | `"soft"` | soft=浅底 / outline=描边 |
| closeLabel | `string` | `"关闭"` | 关闭按钮的无障碍标签 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClose | `() => void` | 传入则渲染右上角关闭按钮，点击触发回调（关闭/消隐由调用方控制） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 可选图标 slot（调用方自带 SVG/emoji；设计系统不绑图标库） |
| title | `ReactNode` | 标题（可选）；children 为正文 description |
| action | `ReactNode` | 右侧动作 slot（如 `<Button>Retry</Button>`），与关闭按钮并排 |

## 示例
```tsx
<Alert tone="success" icon={SuccessIcon} title="操作成功">
  个人资料已保存。
</Alert>

<Alert tone="danger" title="无法连接服务器" onClose={() => setShown(false)} action={<Button>重试</Button>}>
  出现连接问题，请稍后重试。
</Alert>
```

## 禁忌 / 坑

- `onClose` 只触发回调、不自行消隐，是否移除/隐藏由调用方控制（受控）；不传 `onClose` 则不渲染关闭按钮。
- 不绑图标库，`icon` 须调用方自带 SVG/emoji。
- 接口已 `Omit<…, "title">` 避开 HTML 原生 title 属性与 ReactNode title 冲突，直接传 `title` 即为标题。

## 相关
[Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# AlertDialog

> 确认对话框 · Base UI 强制决策(不点遮罩/Esc 关) + Dialog 引擎 · feedback/overlay

## 何时用

破坏性/不可逆操作前强制用户明确决策时用（删除、清空、退出未保存），点遮罩和 Esc **不会**关闭，必须点取消或确认。普通可随手关的对话框用 [Dialog](https://hulianui.haloritual.com/components/dialog)；一行命令式确认用 [Modal](https://hulianui.haloritual.com/components/modal)。

## 导入
```ts
import { AlertDialog, AlertDialogTrigger, AlertDialogClose, AlertDialogContent } from "@hulianui/ui"
```

## Props

`AlertDialog` / `AlertDialogTrigger` / `AlertDialogClose` 为 Base UI AlertDialog 对应原语薄包（Trigger/Close 可传 `className` 或 `render` 接管元素）。`AlertDialogContent` 为瑚琏皮肤：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `AlertDialogContent.className` | `string` | — | 内容容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `AlertDialog.onOpenChange` | `(open: boolean) => void` | 开关态变化回调（透传 Base UI AlertDialog Root） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `AlertDialogContent.title` * | `ReactNode` | 标题（a11y label，必填） |
| `AlertDialogContent.description` | `ReactNode` | 说明文案 |
| `AlertDialogContent.children` | `ReactNode` | 底部操作区，放「取消 / 确认」按钮（取消用 `AlertDialogClose`） |

## 示例
```tsx
<AlertDialog>
  <AlertDialogTrigger className="…">删除项目</AlertDialogTrigger>
  <AlertDialogContent title="删除项目？" description="此操作不可撤销，项目数据将被永久删除。">
    <AlertDialogClose className="…">取消</AlertDialogClose>
    <AlertDialogClose className="…">删除</AlertDialogClose>
  </AlertDialogContent>
</AlertDialog>
```

## 禁忌 / 坑

- 故意不响应点遮罩/Esc 关闭——这是 AlertDialog 的设计意图（强制决策）；想要可随手关闭就改用 Dialog，别在这里恢复轻关闭行为。
- 取消按钮必须用 `AlertDialogClose` 才能关闭弹窗；确认按钮通常也用 `AlertDialogClose` 包裹并在其 onClick 执行操作。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# Banner

> 公告条 · 横贯容器顶部全宽 bar(站点维护/促销/版本更新) · 6 语气×soft/solid + 前导图标/操作区/可关闭 + 居中或左对齐 + 长文案 dogfood Marquee 单行无缝滚动 · 区别 Alert(局部卡片)/Notification(命令式四角) · feedback/message

## 何时用

横贯容器顶部的全宽公告 bar（站点维护、促销、版本更新），全局级、横向铺满。局部区块内的静态提示卡片用 [Alert](https://hulianui.haloritual.com/components/alert)；命令式自动消失的轻提示用 [Toast](https://hulianui.haloritual.com/components/toast)；四角弹出的富通知用 [Notification](https://hulianui.haloritual.com/components/notification)。

## 导入
```ts
import { Banner } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"neutral"｜"info"｜"brand"｜"success"｜"warning"｜"danger"` | `"info"` | 语气色 |
| variant | `"soft"｜"solid"` | `"soft"` | soft=浅底 / solid=实色填充（更醒目，适合促销/重大公告） |
| align | `"start"｜"center"` | `"center"` | 内容对齐 |
| scrollable | `boolean` | `false` | 文案过长时单行无缝滚动（纯 CSS marquee·hover 暂停） |
| closeLabel | `string` | — | 关闭按钮无障碍标签 |
| className | `string` | — | 额外类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClose | `() => void` | 传入则渲染关闭按钮 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 前导图标（传入 svg；随 tone 自动着色） |
| children | `ReactNode` | 文案主体 |
| action | `ReactNode` | 右侧操作区（如「查看详情」链接/按钮） |

## 示例
```tsx
<Banner tone="success" icon={<Rocket />}>部署成功，服务已切换到新版本</Banner>

<Banner
  variant="solid"
  tone="brand"
  icon={<Sparkles />}
  action={<Link href="#" className="text-current underline">立即查看</Link>}
  onClose={() => setOpen(false)}
>
  双十一大促开启，全场组件五折
</Banner>
```

## 禁忌 / 坑

- `onClose` 只触发回调、不自管显隐，显示/隐藏由调用方 state 控制（受控）；不传则不渲染关闭按钮。
- `scrollable` 走纯 CSS marquee（hover 暂停），仅用于单行长文案；多行内容别开。
- `solid` 变体下 `action` 里的链接用 `text-current` 跟随实色底的前景色，别硬编码颜色。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# Dialog

> 对话框 · Base UI Portal + focus trap · feedback/overlay

## 何时用

需要打断当前流程、在遮罩层上承载表单/详情/确认内容时用，自带 Portal + 焦点锁 + Esc 关闭。命令式一行弹（confirm/info/success）用 [Modal](https://hulianui.haloritual.com/components/modal)；强制决策不让点遮罩关用 [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog)；侧滑面板用 [Drawer](https://hulianui.haloritual.com/components/drawer)。

## 导入
```ts
import { Dialog, DialogTrigger, DialogClose, DialogContent } from "@hulianui/ui"
```

## Props

`Dialog` / `DialogTrigger` / `DialogClose` 为 Base UI Dialog 对应原语薄包（`Dialog` 透传 Root 的 `open`/`defaultOpen`/`onOpenChange` 等；`DialogTrigger`/`DialogClose` 支持 `render` 接管渲染元素）。`DialogContent` 为瑚琏皮肤：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `DialogContent.title` * | `string` | — | 标题（a11y label） |
| `DialogContent.description` | `string` | — | 说明文案 |
| `DialogContent.className` | `string` | — | 内容容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `Dialog.onOpenChange` | `(open: boolean) => void` | 开关态变化回调（透传 Base UI Dialog Root） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `DialogContent.footer` | `ReactNode` | 底部操作区，渲染在正文下方，顶部分隔线 + 右对齐，与 DrawerContent 对齐 |
| `DialogContent.children` | `ReactNode` | 正文内容 |

## 示例
```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline">打开对话框</Button>} />
  <DialogContent
    title="瑚琏对话框"
    description="Tab 不出框，Esc 关闭，焦点归还触发按钮。"
  >
    <div className="flex justify-end gap-2">
      <DialogClose render={<Button variant="ghost">取消</Button>} />
      <DialogClose render={<Button>确定</Button>} />
    </div>
  </DialogContent>
</Dialog>
```

## 禁忌 / 坑

- `DialogTrigger` / `DialogClose` 用 `render={<Button…/>}` 把自家行为合并到目标元素上，**不要**再额外包一层按钮，否则会出现嵌套交互元素 / 双重 onClick。
- 操作按钮优先放 `footer` 槽（带分隔线、右对齐），正文 `children` 留给主内容。

## 相关
[Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# Drawer

> 抽屉 · Base UI Dialog 引擎 + 四向侧滑 · feedback/overlay

## 何时用

需要从屏幕某一边滑入的面板（筛选器、详情、表单、移动端菜单）时用，正文可独立滚动、操作按钮钉底。居中弹出的对话框用 [Dialog](https://hulianui.haloritual.com/components/dialog)；强制决策用 [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog)；锚定小浮层用 [Popover](https://hulianui.haloritual.com/components/popover)。

## 导入
```ts
import { Drawer, DrawerTrigger, DrawerClose, DrawerContent, drawerVariants } from "@hulianui/ui"
```

## Props

`Drawer` 透传 Base UI Dialog Root（`open`/`defaultOpen`/`onOpenChange` 等）；`DrawerTrigger`/`DrawerClose` 支持 `render` 接管元素。`DrawerContent` 为瑚琏皮肤：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `DrawerContent.side` | `"left" \| "right" \| "top" \| "bottom"` | `"right"` | 贴边方向 + 对应滑入方向 |
| `DrawerContent.container` | `Element \| Ref` | — | 就地挂载目标；提供后 portal 进该容器并改用 absolute 贴其边（容器须 `position:relative` + `overflow-hidden`），用于手机框预览等局部容器 |
| `DrawerContent.className` | `string` | — | 内容容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `Drawer.onOpenChange` | `(open: boolean) => void` | 开关态变化回调（透传 Base UI Dialog Root） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `DrawerContent.title` | `ReactNode` | 提供则渲 Dialog.Title 作 a11y label |
| `DrawerContent.description` | `ReactNode` | 说明文案 |
| `DrawerContent.footer` | `ReactNode` | 钉底操作区（带分隔线，正文独立滚动，footer 始终可见） |
| `DrawerContent.children` | `ReactNode` | 正文内容 |

## 示例
```tsx
<Drawer>
  <DrawerTrigger render={<Button variant="outline">打开抽屉</Button>} />
  <DrawerContent
    side="right"
    title="设置面板"
    description="Esc / 点遮罩 / 关闭按钮均可收起；焦点锁在抽屉内。"
    footer={
      <>
        <DrawerClose render={<Button variant="outline">取消</Button>} />
        <DrawerClose render={<Button>保存</Button>} />
      </>
    }
  >
    {/* 长正文自动滚动，footer 钉底 */}
  </DrawerContent>
</Drawer>
```

## 禁忌 / 坑

- Base UI rc.0 没有独立 Drawer 原语，本组件是 Dialog（Portal+Backdrop+Popup）重皮、靠 `transform: translateX/Y` 按 `side` 侧滑；Dialog 没有 Positioner，定位别按 Tooltip/Popover 那套想。详见 [[base-ui-dialog-drawer-side-slide-via-transform]]。
- 「取消 / 保存 / 关闭」放 `footer` 槽而非正文末尾，否则正文滚动后按钮会滚出可视区。
- 用 `container` 收进局部容器（如手机框）时，容器必须 `position:relative` + `overflow-hidden`，否则抽屉会逃逸出框、遮罩盖满整屏。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# FloatingReactions

> 飘心点赞 · 命令式 ref.emit(content,{count}) 从底部喷射上浮表情 + 随机起点/横向漂移/缩放/时长扰动 + 上浮渐隐(keyframe)动画结束自移除 + palette 随机池 + rise/drift/duration 可调(forwardRef+useImperativeHandle·pointer-events none·可复用于任意点赞钮) · feedback/message · #animated

## 何时用

点赞/互动时从底部喷射上浮飘心表情的特效层用它：命令式 `ref.emit()` 触发，随机起点/漂移/缩放、上浮渐隐后自移除。它是**叠加特效层**（`pointer-events:none`），只管单个表情上浮动画；要做礼物连击合并计数横幅用 [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)。

## 导入
```ts
import { FloatingReactions } from "@hulianui/ui"
```

## Props

通过 `ref` 取 `FloatingReactionsHandle`，命令式调用 `emit(content?, opts?: { count?: number })`（不传 content 时从 palette 随机取）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| palette | `ReactNode[]` | 一组心 | 不传 content 时随机取的表情池 |
| rise | `number` | `220` | 上浮高度 px |
| drift | `number` | `40` | 横向漂移幅度 px（左右随机） |
| duration | `number` | `2200` | 单个动画时长 ms |
| size | `number` | `24` | 字号 px |
| className | `string` | — | 容器类名 |

## 示例
```tsx
const ref = useRef<FloatingReactionsHandle>(null);

<div className="relative h-72 w-64 overflow-hidden">
  <button onClick={() => ref.current?.emit("❤️", { count: 3 })}>点赞 ❤</button>
  <FloatingReactions ref={ref} />
</div>
```

## 禁忌 / 坑

- 命令式 API：必须经 `ref` 调 `emit`，没有 props 控制触发。容器须 `position:relative` 且建议 `overflow-hidden`，否则上浮表情会溢出可视区。
- 表情元素 `pointer-events:none`，不会拦截点击；放在按钮上方安全。
- 暂无其它已知坑。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result)

<!-- ════════════════════════════════════════════════════════ -->
# GiftFeed

> 礼物连击 · 受控礼物事件流 + 同 id 连击合并 combo ×N 滚动弹跳计数(纯函数 applyGiftEvent 可测) + 横幅左滑入/自动消散计时(每连击重置) + max 同屏上限挤旧 + dogfood Avatar · 直播打赏特效(pointer-events none) · feedback/message · #animated

## 何时用

直播间/互动场景展示打赏礼物连击横幅时用：同一用户对同一礼物快速连点合并为 `combo ×N` 弹跳计数、自动消散、同屏上限挤旧。它是**叠在内容之上的特效层**（`pointer-events:none`）；通用结果反馈用 [Result](https://hulianui.haloritual.com/components/result)，普通通知用 [Notification](https://hulianui.haloritual.com/components/notification)。配合 [FloatingReactions](https://hulianui.haloritual.com/components/floating-reactions) 做点赞飘心。

## 导入
```ts
import { GiftFeed, applyGiftEvent } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| events* | `GiftEvent[]` | — | 受控礼物事件流（追加）。`GiftEvent` = `{id, user:{name,avatar?}, gift:{name,icon?,color?}, combo?}`，同 `id` 再次传入视为同一连击 |
| max | `number` | `3` | 同时显示横幅上限（超出挤掉最旧） |
| duration | `number` | `4000` | 单条无新连击后停留 ms |
| className | `string` | — | 容器类名 |

`applyGiftEvent` 为纯函数：把一个 `GiftEvent` 归并进当前在屏横幅数组（同 id 合并、combo 递增、超 max 挤旧），可单独单元测试。

## 示例
```tsx
const [events, setEvents] = useState<GiftEvent[]>([]);

// 收到打赏时追加事件（combo 由调用方维护）
function onGift(g: GiftEvent) {
  setEvents((prev) => [...prev.slice(-30), g]);
}

<div className="relative h-72 w-80">
  <GiftFeed events={events} max={3} duration={4000} className="w-full" />
</div>
```

## 禁忌 / 坑

- `events` 是「追加流」语义：靠 `id` 区分是否同一连击，同 id 才合并 combo。不同礼物务必给不同 `id`，否则会被误并为连击。
- `combo` 由调用方维护并递增（组件只负责动画呈现）；不传则按出现次数自增。
- 注意 `events` 数组无限增长会占内存，示例里用 `.slice(-30)` 截断；生产同理别让它无界累积。
- 暂无其它已知坑。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result)

<!-- ════════════════════════════════════════════════════════ -->
# Glimpse

> 链接预览 · dogfood HoverCard 引擎换皮成「封面图+标题+描述+域名」预览卡(维基式 hover preview) · 触发器随 href 渲染外链 a 或纯 span 保持行内排版 · 描述多行截断 · feedback/overlay

## 何时用

行文中悬停链接/术语时弹出「封面图 + 标题 + 描述 + 域名」预览卡（维基式 hover preview），不打断阅读。需要完全自定义卡片内容用底层 [HoverCard](https://hulianui.haloritual.com/components/hover-card)；纯文本短提示用 [Tooltip](https://hulianui.haloritual.com/components/tooltip)。传 `href` 则触发器渲染为新标签页外链并在卡底显示域名，不传则渲染纯 `span` 保持行内排版。

## 导入
```ts
import { Glimpse } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| image | `string` | — | 预览图 URL（顶部封面） |
| href | `string` | — | 链接地址；传入则触发器渲染为新标签页外链，卡底显示域名 |
| side | `"top"｜"right"｜"bottom"｜"left"` | `"bottom"` | 浮层方位 |
| align | `"start"｜"center"｜"end"` | — | 对齐 |
| openDelay | `number` | `300` | 悬停打开延迟(ms) |
| closeDelay | `number` | `150` | 移出关闭延迟(ms) |
| className | `string` | — | 触发器额外类名 |
| contentClassName | `string` | — | 预览卡片额外类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 触发元素（行内链接文字/缩略词） |
| title | `ReactNode` | 预览标题 |
| description | `ReactNode` | 预览描述（多行截断） |

## 示例
```tsx
<p className="max-w-md leading-7 text-foreground">
  我们的设计系统基于{" "}
  <Glimpse
    href="https://hulian.example.com/tokens"
    image={cover}
    title="瑚琏设计 Token"
    description="一套语义化的颜色 / 间距 / 圆角变量，明暗模式开箱即用。"
  >
    语义 token
  </Glimpse>{" "}
  构建，悬停链接即可预览。
</p>
```

## 禁忌 / 坑

- 文档站门禁禁外链图片，`image` 在 showcase/demo 里用本地资源或 SVG data-uri 占位，别引远程图片。
- 不传 `href` 时触发器是纯 `span`（无跳转语义），只做术语释义；要可点击跳转必须给 `href`。
- 基于 HoverCard 引擎，hover 防误触延迟由 `openDelay`/`closeDelay` 控，别设 0。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip)

<!-- ════════════════════════════════════════════════════════ -->
# HeroVideoDialog

> 视频弹层 · 缩略图+播放钮→Portal 模态(Esc/遮罩关 + 锁滚) · feedback/overlay

## 何时用

落地页/营销页放一张视频缩略图 + 播放钮，点击后弹出 Portal 模态播放嵌入视频（YouTube/Bilibili embed），支持 Esc/遮罩关闭并锁背景滚动。需要通用模态承载任意内容用 [Dialog](https://hulianui.haloritual.com/components/dialog)；需要原生播放器全套控制（进度/倍速/PiP）用 Video 播放器组件。

## 导入
```ts
import { HeroVideoDialog } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| thumbnailSrc* | `string` | — | 缩略图地址 |
| thumbnailAlt | `string` | — | 缩略图 alt 文本 |
| videoSrc* | `string` | — | 视频嵌入地址（iframe src，如 youtube/bilibili embed） |
| className | `string` | — | 额外类名（控制缩略图尺寸等） |

## 示例
```tsx
<HeroVideoDialog
  thumbnailSrc="/cover.jpg"
  thumbnailAlt="预览"
  videoSrc="https://www.youtube.com/embed/dQw4w9WgXcQ"
  className="w-80"
/>
```

## 禁忌 / 坑

- `videoSrc` 必须是 iframe **embed** 地址（`.../embed/...`），不是普通观看页 URL，否则模态内 iframe 加载失败。
- 缩略图尺寸靠 `className`（如 `w-80`）控制，组件本身不设固定宽度。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip)

<!-- ════════════════════════════════════════════════════════ -->
# HoverCard

> 悬停卡片 · Popover 引擎自研 hover 开/移出延迟关(复刻 Tooltip delay 范式) + 富内容 · feedback/overlay

## 何时用

hover 触发展开的富内容卡片（用户名片、术语释义、链接预览），带开/关延迟避免误触。纯文本短提示用 [Tooltip](https://hulianui.haloritual.com/components/tooltip)；click 触发 + 操作按钮用 [Popover](https://hulianui.haloritual.com/components/popover)；专做「封面图 + 标题 + 域名」链接预览用 [Glimpse](https://hulianui.haloritual.com/components/glimpse)。

## 导入
```ts
import { HoverCard, HoverCardTrigger, HoverCardContent } from "@hulianui/ui"
```

## Props

`HoverCard`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| openDelay | `number` | `300` | 悬停多少毫秒后打开 |
| closeDelay | `number` | `150` | 移出多少毫秒后关闭 |

`HoverCardContent`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top"｜"right"｜"bottom"｜"left"` | `"bottom"` | 浮层方位 |
| align | `"start"｜"center"｜"end"` | `"center"` | 对齐 |
| sideOffset | `number` | — | 与触发器的间距 |
| className | `string` | — | 额外类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `HoverCard` children | `ReactNode` | Trigger + Content |
| `HoverCardContent` children | `ReactNode` | 卡片内容 |

`HoverCardTrigger` 用 `render` prop 接管触发元素（行内链接/按钮）。

## 示例
```tsx
<HoverCard>
  <HoverCardTrigger
    render={<button type="button" className="font-medium text-primary underline">@瑚琏设计系统</button>}
  />
  <HoverCardContent side="bottom" align="center">
    <div className="flex gap-3">
      <div className="flex size-10 items-center justify-center rounded-full bg-primary/12 text-primary">瑚</div>
      <div className="space-y-1">
        <p className="text-sm font-semibold text-foreground">瑚琏设计系统</p>
        <p className="text-xs text-muted">悬停展开 · 移出延迟关闭</p>
      </div>
    </div>
  </HoverCardContent>
</HoverCard>
```

## 禁忌 / 坑

- 本组件已按 [[hovercard-on-focus-managing-popover-flickers-set-initial-final-focus-false]] 把焦点交还语义关掉（不在打开时夺取焦点），避免 hover + focus 在 focus-managing popover 上 ping-pong 无限闪烁；若 fork 改造别重新打开焦点托管。
- 用 `openDelay`/`closeDelay` 调防误触，别把 `closeDelay` 设 0，否则光标在 trigger 与卡片间移动的瞬间会闪关。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip)

<!-- ════════════════════════════════════════════════════════ -->
# Modal

> 命令式对话框 · confirm/info/success/error/warning 函数式 API + Dialog 引擎 · feedback/overlay

## 何时用

逻辑流程里需要一行代码弹确认/提示（删除确认、操作结果反馈）时用，无需在 JSX 里铺 Trigger/Content。需要复杂自定义内容 / 表单的声明式弹窗用 [Dialog](https://hulianui.haloritual.com/components/dialog)；强制决策的破坏性确认用 [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog)。

## 导入
```ts
import { modal, ModalProvider, hulianModalManager } from "@hulianui/ui"
```

## API / Options

调用入口：`modal.confirm(opts)` / `modal.info` / `modal.success` / `modal.error` / `modal.warning`，返回 `ModalInstance`。语调由入口隐含。`ModalProvider` 需在应用根挂一次（同 Toast 范式）。

`ModalOptions` Props：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `type` | `"confirm" \| "info" \| "success" \| "error" \| "warning"` | — | 语调；命令式入口已隐含，一般无需显式传 |

`ModalOptions` Events：

| 事件 | 类型 | 说明 |
|------|------|------|
| `onOk` | `() => void \| Promise<unknown>` | 点确定回调；返回 Promise 时确定键进 loading，resolve → 自动关闭，reject → 保持打开 |
| `onCancel` | `() => void` | 点取消 / Esc / 点遮罩关闭时回调 |

`ModalOptions` Slots：

| 插槽 | 类型 | 说明 |
|------|------|------|
| `title` | `ReactNode` | 标题（加粗主行） |
| `content` | `ReactNode` | 正文内容 |
| `okText` | `ReactNode` | 确定按钮文案，默认 `"确定"` |
| `cancelText` | `ReactNode` | 取消按钮文案，默认 `"取消"`（仅 confirm 渲染取消键） |

`ModalInstance`：`destroy()` 立即关闭销毁；`update(next)` 更新已打开对话框配置。

## 示例
```tsx
// 根布局挂一次
<ModalProvider />

// 任意逻辑处调用
modal.confirm({
  title: "确认删除该记录？",
  content: "删除后无法恢复。",
  onOk: () => {},
});

// 异步确定：确定键自动 loading，resolve 后关闭
modal.confirm({
  title: "提交订单？",
  content: "点确定将发起请求。",
  onOk: () => fetch("/api/order", { method: "POST" }),
});
```

## 禁忌 / 坑

- 必须在应用根挂一次 `ModalProvider`，否则命令式调用无处渲染；showcase 里也是 layout 单挂、触发按钮里只调 `modal.*`（同 Toast）。
- `onOk` 返回 Promise 时：resolve 才自动关闭，reject 会保持打开（由调用方提示错误）——别在 reject 分支里又手动 `destroy`。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# Notification

> 通知 · 四角堆叠卡片 + 图标/操作区/位置 + 命令式 API(比 Toast 重) · feedback/message

## 何时用

需要在四角弹出**带标题+描述+操作按钮**的较重通知卡片时用（比如「收到好友请求 / 上传失败可重试」）。比 [Toast](https://hulianui.haloritual.com/components/toast) 信息量大、可常驻、可带操作；只需一行短反馈、自动消失时用 Toast。命令式调用，无需在 JSX 里挂节点（但 `NotificationProvider` 须由 layout 单挂一次）。

## 导入
```ts
import { notification, NotificationProvider, hulianNotificationManager } from "@hulianui/ui"
```

## Props

`notification.success/error/info/warning/open(options)` 接收 `NotificationOptions`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| type | `"open"｜"success"｜"error"｜"info"｜"warning"` | — | 经方法名隐含（`open` 为中性无图标）；派生左侧色条 + 默认图标，token 同 Alert（info→primary） |
| duration | `number` | `4500` | 自动关闭毫秒数；`0` = 不自动关（常驻） |
| placement | `"topRight"｜"topLeft"｜"bottomRight"｜"bottomLeft"` | `"topRight"` | 弹出位置（四角） |

调用返回 `NotificationInstance`，含 `destroy(): void` 立即关闭该通知。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClose | `() => void` | 关闭时回调（自动/手动/编程关闭均触发一次） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题（加粗主行） |
| description | `ReactNode` | 描述（次行，恒 text-muted） |
| icon | `ReactNode` | 自定义图标，覆盖默认（不传按类型派生） |
| btn | `ReactNode` | 操作区（按钮等），渲染在描述下方 |

## 示例
```tsx
// 普通成功通知（4.5s 自动关闭）
notification.success({ title: "保存成功", description: "更改已同步。" })

// 带操作按钮 + 常驻（duration:0）
notification.open({
  title: "收到一条好友请求",
  description: "来自 设计部·小琏",
  duration: 0,
  btn: <Button size="sm" onClick={() => {}}>查看</Button>,
})
```

## 禁忌 / 坑

- `NotificationProvider` 须在 layout 单挂一次（同 Toast/Modal 范式），不要在每个调用点或 showcase 里挂 Provider，否则通知无处渲染。
- `duration: 0` 才是常驻；不传 duration 默认 4500ms 自动关，需要用户必看的通知务必显式置 0。
- 命令式触发的副作用通知，注意「触发即忘」的回调语义——`onClose` 仅保证触发一次，别在其中做依赖外部最新状态的操作。参见 [[fire-and-forget-side-effect-notification]]。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# Popconfirm

> 气泡确认 · dogfood Popover 引擎 + 危险操作就地确认(标题/图标/确认取消) + async onConfirm loading + 受控开合 · feedback/message

## 何时用

危险/不可逆操作（删除、归档）需要就地二次确认时用：锚定到触发器旁弹出气泡，含标题/描述/确认取消按钮。比 [Toast](https://hulianui.haloritual.com/components/toast) 重、比全屏 Dialog 轻；需要居中、信息量大的确认弹窗用 Modal/AlertDialog，本组件适合表格行内、按钮旁的轻量确认。

## 导入
```ts
import { Popconfirm } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| danger | `boolean` | `false` | 危险操作：确认按钮 tone=danger + 默认图标转 text-danger |
| open | `boolean` | — | 受控打开态，须配合 onOpenChange |
| defaultOpen | `boolean` | `false` | 非受控初始打开态 |
| side | `"top"｜"right"｜"bottom"｜"left"` | `"top"` | 浮层方位 |
| align | `"start"｜"center"｜"end"` | `"center"` | 浮层对齐 |
| sideOffset | `number` | `8` | 浮层与触发器间距 |
| disabled | `boolean` | `false` | 禁用：触发器照常渲染但不唤起浮层 |
| className | `string` | — | 透传到浮层 Popup 的类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onConfirm | `() => void \| Promise<void>` | 点确认回调。返回 Promise 时按钮进 loading，resolve 后自动关闭；reject 保持打开并清 loading |
| onCancel | `() => void` | 仅显式点取消按钮触发（点外部/Esc 走 onOpenChange，不触发此回调） |
| onOpenChange | `(open: boolean) => void` | 打开态变化回调（含点外部/Esc/确认/取消） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 确认主问句，串 `aria-labelledby` |
| description | `ReactNode` | 次要说明，串 `aria-describedby` |
| icon | `ReactNode` | `undefined`=默认警示三角；`null`=不渲染；ReactNode=自定义。默认色随 danger 切换 |
| okText | `ReactNode` | 确认按钮文案（默认「确认」） |
| cancelText | `ReactNode` | 取消按钮文案（默认「取消」） |
| children* | `ReactElement` | 触发器（单个元素，浮层锚定到它） |

## 示例
```tsx
// 危险删除确认
<Popconfirm title="确定删除该条记录？" description="删除后不可恢复。" danger onConfirm={() => {}}>
  <Button variant="outline" tone="danger" size="sm">删除</Button>
</Popconfirm>

// 异步确认（loading 后自动关闭）
<Popconfirm
  title="确认归档？"
  okText="归档"
  onConfirm={async () => { await api.archive(id); }}
>
  <Button variant="outline" size="sm">归档</Button>
</Popconfirm>
```

## 禁忌 / 坑

- `onConfirm` 返回 Promise 时：resolve 才自动关闭，reject **保持打开并清 loading**，错误反馈（如弹 Toast）须由调用方自己负责。
- `onCancel` 只在显式点「取消」按钮时触发；点外部/按 Esc 关闭只走 `onOpenChange`，别在 onCancel 里做必跑的清理。
- `children` 必须是**单个 ReactElement**（浮层要锚定它），不能传文本或 Fragment。
- 受控用法须 `open` + `onOpenChange` 成对；只传 `open` 不传 onOpenChange 会卡死无法关闭。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result)

<!-- ════════════════════════════════════════════════════════ -->
# Popover

> 气泡卡片 · click 触发 + 标题/描述/Close · feedback/overlay

## 何时用

click 触发的轻量浮层，承载标题/描述/少量操作（确认、快捷设置、表单片段），点外部或 Esc 关闭。需要纯文本提示用 [Tooltip](https://hulianui.haloritual.com/components/tooltip)（hover 触发）；需要 hover 展开富内容卡片用 [HoverCard](https://hulianui.haloritual.com/components/hover-card)；需要遮罩 + 焦点锁定的强中断流程用 [Dialog](https://hulianui.haloritual.com/components/dialog)。

## 导入
```ts
import { Popover, PopoverTrigger, PopoverClose, PopoverContent } from "@hulianui/ui"
```

## Props

`PopoverContent`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top"｜"right"｜"bottom"｜"left"` | `"bottom"` | 浮层方位 |
| align | `"start"｜"center"｜"end"` | `"center"` | 对齐 |
| sideOffset | `number` | — | 与触发器的间距 |
| className | `string` | — | 额外类名 |

## Slots

`PopoverContent`：

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题 |
| description | `ReactNode` | 描述 |
| children | `ReactNode` | 正文/操作区内容 |

`PopoverTrigger` / `PopoverClose` 用 `render` prop 接管自定义触发/关闭元素（如 `render={<Button>…</Button>}`）。

## 示例
```tsx
<Popover>
  <PopoverTrigger render={<Button>打开弹层</Button>} />
  <PopoverContent side="bottom" align="center" title="确认操作" description="点击外部或 Esc 关闭。">
    <div className="flex justify-end gap-2">
      <PopoverClose render={<Button variant="ghost">取消</Button>} />
      <PopoverClose render={<Button>确定</Button>} />
    </div>
  </PopoverContent>
</Popover>
```

## 禁忌 / 坑

- 触发/关闭走 `render` prop 注入元素，别再在 `PopoverTrigger` 里二次嵌套交互元素，避免 `<button>` 套 `<button>`。
- 若手搓 hover 开 + focus 关叠加在这类 focus-managing popover 上会无限闪烁，见 [[hovercard-on-focus-managing-popover-flickers-set-initial-final-focus-false]]：popover 打开时把焦点移入浮层会触发 trigger 的 onBlur 关闭，关闭又把焦点还给 trigger 触发 onFocus 打开 → ping-pong。本组件默认 click 语义不踩，但若改造成 hover 触发需把 `initialFocus`/`finalFocus` 设 false。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Tooltip](https://hulianui.haloritual.com/components/tooltip) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# Progress

> 进度条 · linear/circular + 不定态 · 几何自有(reduced-motion) · feedback/loading

## 何时用

表达「确定进度」（已知 value/max 的任务百分比，如上传、表单步进、配额占用）或「不定态加载」（省略 value）。需要可量化进度时用本组件；只是表达「忙碌中」无具体进度，用 [Spin](https://hulianui.haloritual.com/components/spin) / [Spinner](https://hulianui.haloritual.com/components/spinner)。

## 导入
```ts
import { Progress, progressPercent, dashOffset } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `number` | — | 当前值；省略/undefined → indeterminate 不定态 |
| max | `number` | `100` | 最大值 |
| variant | `"linear" \| "circular"` | `"linear"` | 形态 |
| tone | `"primary" \| "danger" \| "success" \| "warning"` | `"primary"` | 进度色调 |
| size | `number` | `40` | circular 直径 px（linear 忽略） |
| thickness | `number` | `4` | circular 描边 px（linear 忽略） |
| showValue | `boolean` | `false` | 显示百分比标签（circular 居中 / linear 右侧）；indeterminate 不显示 |

> 继承 `HTMLAttributes<HTMLDivElement>`（`className` 等）。linear 形态需自给宽度（如 `className="w-64"`）。

## 示例
```tsx
<Progress value={60} showValue className="w-64" />
<Progress variant="circular" value={75} showValue />
<Progress className="w-64" />            {/* 不定态：省略 value */}
```

## 禁忌 / 坑

- circular 形态内部用 SVG ring 实现：弧线从 12 点起始、明暗自适应均依赖 SVG `transform="rotate(…)"` 属性而非 CSS transform——改造其几何时见 [[svg-circular-progress-ring-rotate-via-svg-attr-not-css]]（CSS transform-origin 对 SVG geometry 元素失效）。
- 不定态（省略 value）下 `showValue` 不生效，无百分比可显。

## 相关
[Spin](https://hulianui.haloritual.com/components/spin) · [Spinner](https://hulianui.haloritual.com/components/spinner) · [Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer)

<!-- ════════════════════════════════════════════════════════ -->
# Result

> 结果页 · 7 状态(success/error/info/warning/403/404/500)内置图标+语义色 + 标题/副标题/详情/操作槽(零依赖·RSC) · feedback/message

## 何时用

整页/整块展示一次操作的最终结果或异常页时用（支付成功、提交失败、403/404/500 错误页），居中大图标 + 标题 + 操作按钮。它是**占满区域的结果反馈**；行内/局部的轻量提示用 [Alert](https://hulianui.haloritual.com/components/alert)，瞬时反馈用 [Toast](https://hulianui.haloritual.com/components/toast)。零依赖、可作 RSC。

## 导入
```ts
import { Result } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLDivElement>, "title" | "content">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| status | `"success"｜"error"｜"info"｜"warning"｜"403"｜"404"｜"500"` | `"info"` | 状态，决定内置图标与语义色 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 自定义图标覆盖内置（不传按 status 派生）；传 `null` 则不渲染图标区 |
| title | `ReactNode` | 主标题 |
| subTitle | `ReactNode` | 副标题/辅助说明 |
| content | `ReactNode` | 详情内容区（如错误堆栈），渲染在标题下方、操作区上方 |
| children | `ReactNode` | 操作区（按钮等），渲染在最下方 |

## 示例
```tsx
// 成功结果 + 操作按钮
<Result status="success" title="支付成功" subTitle="订单 #2024-0612 已完成，预计 3 天内发货。">
  <Button size="sm">查看订单</Button>
  <Button size="sm" variant="outline">返回首页</Button>
</Result>

// 失败 + 详情内容
<Result
  status="error"
  title="提交失败"
  subTitle="请检查并修改以下信息后重试。"
  content="账户名包含非法字符；手机号格式不正确。"
>
  <Button size="sm">返回修改</Button>
</Result>
```

## 禁忌 / 坑

- `status` 的 `"403"/"404"/"500"` 是字符串字面量，别写成数字 `404`。
- `icon={null}` 才彻底不渲染图标区；不传 `icon` 会按 status 用内置图标。
- 暂无其它已知坑。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# ServiceMessage

> 服务通知卡片 · 复刻微信「服务通知」会话内消息卡(模板/订阅消息) · 头部(头像+来源+⋯)/正文(标题+键值字段或自定义 children)/底部(引导文字+小程序入口) · 数据驱动 fields + onMore/onAction 交互 + footer/action 可定制 · 区别 Notification(命令式四角 toast) · 复用 Avatar/_icons·全吃 token 明暗自适配 · feedback/message

## 何时用

在「消息流 / 会话内」展示服务方下发的模板/订阅消息卡片时用（取餐提醒、物流签收、审批结果等）：头部来源、正文键值字段、底部小程序入口三段式。它是**声明式静态卡片**，渲染在内容流里；要弹出短暂反馈用 [Notification](https://hulianui.haloritual.com/components/notification)（命令式四角 toast）或 [Toast](https://hulianui.haloritual.com/components/toast)。

## 导入
```ts
import { ServiceMessage } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLDivElement>, "title">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| avatar | `AvatarProps` | — | 头部头像（复用瑚琏 Avatar 的 props，如 `{src, fallback}`） |
| fields | `ServiceMessageField[]` | — | 正文键值对字段（`{label, value}` 左标右值）；children 提供时被覆盖 |
| action | `ServiceMessageAction` | label `"小程序"` | 底部右侧动作（`{label?, icon?}` + chevron） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onMore | `() => void` | 头部右侧「更多」回调；提供则渲染 ⋯ 按钮 |
| onAction | `() => void` | 底部行点击回调；提供则整行成为可点击 button |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| source | `ReactNode` | 头部来源名称，如「luckincoffee 瑞幸咖啡」 |
| title | `ReactNode` | 正文主标题，如「商品领取提醒」 |
| children | `ReactNode` | 自定义正文（覆盖 fields），用于非键值结构内容 |
| footer | `ReactNode` | 底部左侧引导文字（默认「进入小程序查看」）；传 `null` 隐藏整个底部 |

## 示例
```tsx
// 数据驱动键值字段
<ServiceMessage
  avatar={{ fallback: "瑞", className: "bg-primary/10 text-primary" }}
  source="luckincoffee 瑞幸咖啡"
  onMore={() => {}}
  title="商品领取提醒"
  fields={[
    { label: "取餐号", value: "361" },
    { label: "商品数量", value: "1" },
    { label: "商品详情", value: "橙C冰茶" },
  ]}
  action={{ icon: <LayoutGrid className="size-3.5 text-primary" /> }}
  onAction={() => {}}
/>

// 自定义正文 children（覆盖 fields）+ 自定义动作文字
<ServiceMessage
  avatar={{ fallback: "顺", className: "bg-warning/15 text-warning" }}
  source="顺丰速运"
  title="您的包裹已签收"
  footer="查看物流详情"
  action={{ label: "详情" }}
  onAction={() => {}}
>
  <p className="text-sm text-foreground">您的快件已由本人签收。</p>
</ServiceMessage>
```

## 禁忌 / 坑

- `children` 与 `fields` 互斥：传了 `children` 则 `fields` 被忽略，二选一。
- 不传 `onMore` 就不渲染 ⋯ 按钮；不传 `onAction` 则底部行不可点击——交互按需挂回调，别给空函数误以为生效。
- `footer={null}` 会隐藏**整个底部**（含右侧 action），不只是引导文字。
- 暂无其它已知坑。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Toast](https://hulianui.haloritual.com/components/toast) · [Notification](https://hulianui.haloritual.com/components/notification) · [Result](https://hulianui.haloritual.com/components/result) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# Spin

> 加载遮罩 · 覆盖内容区 + tip + delay 防闪 + fullscreen · feedback/loading

## 何时用

给一块内容区盖上加载遮罩（异步刷新表格/卡片时半透明蒙层 + 旋转器 + 文案）用它，遮罩期内容 `pointer-events:none`。它带遮罩/包裹/整页能力；只需一个裸旋转图标（按钮内、行内）用 [Spinner](https://hulianui.haloritual.com/components/spinner)；已知进度百分比用 [Progress](https://hulianui.haloritual.com/components/progress)。

## 导入
```ts
import { Spin } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| spinning | `boolean` | `true` | 是否处于加载态 |
| delay | `number` | `0` | 延迟显示 ms：spinning 持续超过 delay 才显遮罩（防快速完成时闪烁） |
| size | `"sm"｜"md"｜"lg"` | `"md"` | 尺寸，透传内部 Spinner |
| fullscreen | `boolean` | `false` | 整页遮罩（fixed 覆盖视口），忽略 children |
| className | `string` | — | 容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| tip | `ReactNode` | 加载文案，居中显示在 Spinner 下方 |
| children | `ReactNode` | 被包裹内容；不传则作纯指示器 |

## 示例
```tsx
// 包裹内容区，加载时盖遮罩
<Spin spinning={loading} tip="加载中…">
  <ReportTable />
</Spin>

// 整页遮罩（忽略 children）
{busy && <Spin fullscreen tip="加载中…" />}
```

## 禁忌 / 坑

- `fullscreen` 会**忽略 children**（fixed 覆盖整个视口），它和「包裹内容」是两种互斥用法，别同时指望它既盖整页又包内容。
- 用 `delay` 防快速完成时的闪烁（请求 < delay 完成就不显遮罩）；长耗时加载置 0 立即显。
- 不传 children 时退化为纯指示器（等价于一个带 tip 的 Spinner）。
- 暂无其它已知坑。

## 相关
[Spinner](https://hulianui.haloritual.com/components/spinner) · [Progress](https://hulianui.haloritual.com/components/progress) · [Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer)

<!-- ════════════════════════════════════════════════════════ -->
# Spinner

> 加载旋转器 · 纯 CSS animate-spin SVG 环 + role=status + RSC · feedback/loading

## 何时用

需要一个裸的加载旋转图标时用（按钮内、行内、空状态占位）：纯 CSS `animate-spin` SVG 环，带 `role=status`，零交互、可作 RSC。需要遮罩/包裹内容区/整页加载用 [Spin](https://hulianui.haloritual.com/components/spin)；已知进度用 [Progress](https://hulianui.haloritual.com/components/progress)。

## 导入
```ts
import { Spinner, spinnerVariants } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `"sm"｜"md"｜"lg"` | `"md"` | 尺寸 |
| tone | `"primary"｜"current"｜"muted"` | `"primary"` | 配色（`current`=继承 currentColor，适合放进彩色按钮内） |
| label | `string` | `"加载中"` | a11y 文案（role=status 读屏播报） |
| className | `string` | — | 容器类名 |

## 示例
```tsx
// 默认
<Spinner />

// 放进主色按钮内（继承文字色）
<Button>
  <Spinner size="sm" tone="current" />
  提交中
</Button>
```

## 禁忌 / 坑

- `tone="current"` 才继承 `currentColor`——放进彩色按钮/链接内想随文字色变时用它，默认 `primary` 是固定主色。
- 它无 `spinning` 开关，渲染即转；要按状态控制显隐自行 `{loading && <Spinner />}`，或用 [Spin](https://hulianui.haloritual.com/components/spin) 的 `spinning` prop。
- 暂无其它已知坑。

## 相关
[Spin](https://hulianui.haloritual.com/components/spin) · [Progress](https://hulianui.haloritual.com/components/progress) · [Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer)

<!-- ════════════════════════════════════════════════════════ -->
# Toast

> 命令式轻提示 · 自动消失 + 队列堆叠 + 手动关闭 · feedback/message

## 何时用

操作后命令式弹出的轻提示（已保存、已复制、保存失败），自动消失、队列堆叠（limit 3）。静态常驻的区块内提示用 [Alert](https://hulianui.haloritual.com/components/alert)；横贯顶部的公告 bar 用 [Banner](https://hulianui.haloritual.com/components/banner)；需要展开操作/富内容的通知用 [Notification](https://hulianui.haloritual.com/components/notification)。`ToastProvider` 在应用/段落 layout 单挂一次，业务侧只调 `toast()`。

## 导入
```ts
import { toast, ToastProvider } from "@hulianui/ui"
```

## Props

`toast(options)` 的 `ToastOptions`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"info"｜"danger"｜"neutral"` | `"neutral"` | 语调，驱动左边条 + 标题着色（复用 Alert 语义，无 success：token 无） |
| timeout | `number` | `5000` | 自动消失毫秒数；`0` = 不自动消失（手动关闭）；缺省取 Provider 默认 |

## Slots

`toast(options)` 的 `ToastOptions`：

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 标题（加粗主行） |
| description | `ReactNode` | 描述（次行，恒 text-muted） |

`ToastProvider` 在根/段落 layout 单挂，承接命令式渲染。

## 示例
```tsx
// 应用根布局挂一次
<ToastProvider>{children}</ToastProvider>

// 业务侧命令式调用
toast({ tone: "info", title: "有新版本", description: "点击刷新以更新。" })
toast({ tone: "danger", title: "保存失败", description: "网络异常，请重试。" })
toast({ title: "需手动关闭", timeout: 0 }) // 0 = 常驻，点 × 才消失
```

## 禁忌 / 坑

- `ToastProvider` 全应用只挂一次（在段落 layout），别在 showcase/页面里重复挂，否则命令式渲染会重复。
- 无 `success` 语调（token 无），成功态用 `info` 或 `neutral`。
- 测试该组件时注意 Base UI Toast 的几个坑见 [[base-ui-toast-close-aria-hidden-query-dom-not-role]]：未聚焦的 Close 按钮带 `aria-hidden` 致 `getByRole("button")` 找不到（改查 DOM）、aria-live 公告会让标题文本重复匹配、全局 manager 持久化致 toast 跨测试泄漏需清理。

## 相关
[Alert](https://hulianui.haloritual.com/components/alert) · [Banner](https://hulianui.haloritual.com/components/banner) · [Notification](https://hulianui.haloritual.com/components/notification) · [ServiceMessage](https://hulianui.haloritual.com/components/service-message) · [Result](https://hulianui.haloritual.com/components/result) · [GiftFeed](https://hulianui.haloritual.com/components/gift-feed)

<!-- ════════════════════════════════════════════════════════ -->
# Tooltip

> 提示浮层 · Base UI Positioner + 箭头 + hover 触发 · feedback/overlay

## 何时用

hover/focus 触发的纯文本短提示（图标含义、截断文字全文、操作说明）。承载富内容（头像 + 简介卡片）用 [HoverCard](https://hulianui.haloritual.com/components/hover-card)；click 触发 + 带操作按钮用 [Popover](https://hulianui.haloritual.com/components/popover)。`delay` / `closeDelay` 在 `TooltipProvider` 上，不在 `Tooltip` 上。

## 导入
```ts
import { Tooltip, TooltipTrigger, TooltipProvider, TooltipContent } from "@hulianui/ui"
```

## Props

`TooltipContent`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top"｜"right"｜"bottom"｜"left"` | `"top"` | 浮层方位 |
| align | `"start"｜"center"｜"end"` | `"center"` | 对齐 |
| sideOffset | `number` | — | 与触发器的间距 |
| className | `string` | — | 额外类名 |

`TooltipProvider` 接 `delay` / `closeDelay`（ms）控制开合延迟。

## Slots

`TooltipContent`：

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 提示文案 |

`TooltipTrigger` 用 `render` prop 接管触发元素。

## 示例
```tsx
<TooltipProvider delay={0} closeDelay={0}>
  <Tooltip>
    <TooltipTrigger render={<Button variant="outline">悬停查看</Button>} />
    <TooltipContent side="top" align="center">瑚琏提示</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

## 禁忌 / 坑

- `delay`/`closeDelay` 写在 `TooltipProvider` 而非 `Tooltip`；截图/稳态验收时把两者设 0 让 hover 即开。
- 在 flex 行内（带 `text-overflow:ellipsis` + `min-w-0`）用 Tooltip 包裹文本时，触发器 wrapper 若是 `inline-block` 会按内容固有宽撑开、绕过父级宽度约束破坏截断（同类问题见 [[heroui-tooltip-trigger-inline-block-breaks-flex-truncation]]）；本组件用 `render` 注入元素时确保触发元素本身保持 `block; min-w-0`。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [HoverCard](https://hulianui.haloritual.com/components/hover-card)

<!-- ════════════════════════════════════════════════════════ -->
# Tour

> 漫游引导 · 自研零依赖 SVG mask 镂空高亮 + 自定位气泡卡(标题/描述/上一步/下一步/跳过/进度) + resize/scroll 重算 · feedback/guide

## 何时用

新手引导 / 功能上线导览：逐步高亮页面上的真实 DOM 元素并附气泡讲解。需要「逐步串联多个页面元素」用本组件；只是悬停/点击单个元素的提示用 [Tooltip](https://hulianui.haloritual.com/components/tooltip) / [Popover](https://hulianui.haloritual.com/components/popover)；阻断式确认流程用 [Dialog](https://hulianui.haloritual.com/components/dialog) / [Modal](https://hulianui.haloritual.com/components/modal)。

## 导入
```ts
import { Tour, resolveTarget, computeSpotlight, computeCardPosition, type Rect } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| steps* | `TourStep[]` | — | 引导步骤列表（见下） |
| open* | `boolean` | — | 是否打开（受控） |
| current* | `number` | — | 当前步索引（受控，从 0 起） |
| maskClosable | `boolean` | `false` | 点击遮罩是否关闭（默认不允许误触关闭） |
| spotlightPadding | `number` | `8` | 高亮镂空在目标四周的留白 px |
| spotlightRadius | `number` | `8` | 镂空圆角 px |
| gap | `number` | `12` | 气泡卡与目标的间距 px |
| zIndex | `number` | `100` | 遮罩 z-index |

**TourStep**：
| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
| target | `(() => Element \| null) \| string \| null` | — | 高亮目标：函数（`() => ref.current`，DOM 动态时最稳）/ CSS 选择器字符串 / null 省略（气泡居中，适合开场收尾） |
| title | `ReactNode` | — | 步骤标题 |
| description | `ReactNode` | — | 步骤描述 |
| placement | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | 气泡方位（放不下自动翻到对侧）；无目标时忽略 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onChange | `(current: number) => void` | 当前步变化（点上一步/下一步） |
| onClose | `() => void` | 关闭（跳过/Esc/末步完成且未传 onFinish） |
| onFinish | `() => void` | 末步「完成」回调；不传则走 onClose |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| prevText | `ReactNode` | 「上一步」按钮文案覆盖 |
| nextText | `ReactNode` | 「下一步」按钮文案覆盖 |
| skipText | `ReactNode` | 「跳过」按钮文案覆盖 |
| finishText | `ReactNode` | 「完成」按钮文案覆盖 |

> TourStep 内的 `title` / `description` 亦为 `ReactNode`，见上方 TourStep 表。

## 示例
```tsx
const [open, setOpen] = useState(false);
const [current, setCurrent] = useState(0);

<Tour
  open={open}
  current={current}
  onChange={setCurrent}
  onClose={() => setOpen(false)}
  steps={[
    { title: "欢迎", description: "开场居中…" },
    { target: () => searchRef.current, title: "全局搜索", description: "…", placement: "bottom" },
    { target: "#new-btn", title: "新建一条", description: "…", placement: "left" },
  ]}
/>
```

## 禁忌 / 坑

- 完全受控：`open` 与 `current` 必须由消费者 state 持有，上一步/下一步只触发 `onChange`，本组件不自管步索引——忘记在 `onChange` 里回写 `current` 会导致引导卡在第一步。
- `target` 用函数（`() => ref.current`）比 CSS 选择器更稳，尤其目标 DOM 动态挂载/卸载时。
- 全屏 overlay 经 Portal 挂到 body；截图/可视验证须「先点开始触发 open 再截」（同 Drawer/Popover/Toast）。

## 相关
[Dialog](https://hulianui.haloritual.com/components/dialog) · [Modal](https://hulianui.haloritual.com/components/modal) · [AlertDialog](https://hulianui.haloritual.com/components/alert-dialog) · [Drawer](https://hulianui.haloritual.com/components/drawer) · [Popover](https://hulianui.haloritual.com/components/popover) · [Tooltip](https://hulianui.haloritual.com/components/tooltip)


# ━━━━━━━━ AI 智能体 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# AgentPlan

> 执行计划 · 数据驱动任务清单 + 状态图标(空心环待办/Spinner进行·行高亮/Check完成删除线/X失败) + 每步右侧 meta 槽(耗时) + bare 内嵌 · 复用 Spinner·纯皮肤RSC · ai/agent

## 何时用

数据驱动地展示 agent 的多步任务清单（每步带状态、描述、耗时）。单次工具调用用 [ToolCall](https://hulianui.haloritual.com/components/tool-call)，自由文本推理用 [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block)；这里是结构化的步骤进度。

## 导入
```ts
import { AgentPlan } from "@hulianui/ui"
```

## Props

`AgentPlanProps`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tasks * | `AgentTask[]` | — | 任务清单（数据驱动） |
| bare | `boolean` | `false` | 去掉外层边框/底色/内边距，仅渲染列表，供内嵌复用（如 TaskRunner） |
| strikeDone | `boolean` | `true` | done 任务是否加删除线：计划清单语义=true；执行日志语义=false 保留实色 |
| className | `string` | — | 容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 头部标题（默认 `"执行计划"`）；传 null 隐藏 |

`AgentTask`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| title | `ReactNode` | — | 任务标题 |
| status | `"pending" ｜ "running" ｜ "done" ｜ "error"` | `"pending"` | pending 待办(空心环) / running 进行中(转圈·行高亮) / done 完成(勾·删除线) / error 失败(叉) |
| detail | `ReactNode` | — | 次要描述（标题下方弱化） |
| meta | `ReactNode` | — | 行右侧 trailing 槽（右对齐弱化）：放耗时(如 180ms)/小标记 |

## 示例
```tsx
<AgentPlan
  tasks={[
    { title: "读取现有 page.tsx", status: "done", detail: "仅用了 Button" },
    { title: "逐块替换为 @hulianui/ui", status: "running" },
    { title: "截图验证明暗双主题", status: "pending" },
  ]}
/>
```

## 禁忌 / 坑

- `tasks` 是必填的纯数据数组，组件本身不维护状态——进度推进靠消费侧更新数组重渲染。
- 内嵌到别的卡片（如 TaskRunner）里时传 `bare` 去掉外层边框底色；执行日志语义下传 `strikeDone={false}` 避免完成项加删除线。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# Artifact

> 工件卡 · 智能体产出物(文档/简历/代码)对话内承载：头部(图标+标题+版本Chip+操作槽) + 折叠限高+底部渐隐遮罩 + 展开/收起(受控/非受控) · dogfood Chip · ai/agent

## 何时用

承载 agent 生成的成型产出物（文档、简历、代码块），需要标题/版本/导出操作并对长内容折叠限高时用。相关里 [Dossier](https://hulianui.haloritual.com/components/dossier) 偏多字段案卷展示；纯文本流式增长用 [StreamingText](https://hulianui.haloritual.com/components/streaming-text)；本组件是「最终成品」的容器卡，强调头部元信息 + 限高折叠。

## 导入
```ts
import { Artifact } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| collapsedHeight | `number` | `240` | 折叠态内容限高 px；`<=0` 表示不折叠 |
| defaultExpanded | `boolean` | `false` | 非受控初始展开态 |
| expanded | `boolean` | — | 受控展开态（与 onExpandedChange 配对） |
| className | `string` | — | 容器附加类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onExpandedChange | `(expanded: boolean) => void` | 受控展开态变化回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 头部标题 |
| icon | `ReactNode` | 标题前图标 |
| version | `ReactNode` | 版本标识，渲染为小 chip（如 `"v2"`） |
| actions | `ReactNode` | 头部右侧操作区（如导出按钮） |
| expandLabel | `ReactNode` | 折叠时展开按钮文字（默认 `"展开全文"`） |
| collapseLabel | `ReactNode` | 展开时收起按钮文字（默认 `"收起"`） |
| children | `ReactNode` | 工件正文 |

## 示例
```tsx
<Artifact
  title="简历草稿 · 林晚晴"
  icon={<File className="size-4" />}
  version="v2"
  actions={<Button size="sm" variant="ghost">导出</Button>}
>
  {longBody}
</Artifact>

// 不折叠（内容很短时）
<Artifact title="简短产出" collapsedHeight={0}>
  <p className="text-sm">一段不需要折叠的简短内容。</p>
</Artifact>
```

## 禁忌 / 坑

- 受控/非受控二选一：传了 `expanded` 就必须配 `onExpandedChange` 自管状态，否则展开钮点了不动；只想要默认态用 `defaultExpanded`。
- `collapsedHeight<=0` 关闭折叠后不会渲染渐隐遮罩与展开按钮，内容全量铺开——内容很长时别这么设。
- 候选坑 [[release-pipeline-stale-artifact-picked-by-readdir-find]] 讲 CI 发布流水线选错构建产物，与本 UI 工件卡无关，不适用。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# ChatMessage

> 对话气泡 · user右(primary)/assistant左(surface)/system居中 + 头像(复用Avatar)/名称/时间 + loading态(TypingDots) + 操作槽·纯皮肤RSC · ai/conversation

## 何时用

渲染单条对话气泡（用户/助手/系统通告）。多条气泡的滚动堆叠交给 [Conversation](https://hulianui.haloritual.com/components/conversation)；气泡下方的操作按钮用 MessageActions 放进 `actions` 槽。

## 导入
```ts
import { ChatMessage } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLDivElement>, "title">`。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| role * | `"user" ｜ "assistant" ｜ "system"` | `"assistant"`(showcase) | user 右对齐(primary 底) / assistant 左对齐(surface 底) / system 居中弱化通告 |
| loading | `boolean` | `false` | 加载态：正文位置显示 TypingDots（agent 生成中） |
| status | `"sending" ｜ "sent" ｜ "read"` | — | 已读回执：仅 role=user 渲染。sending 转圈 / sent 单勾 / read 双蓝勾 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 正文；markdown 建议外层包 `<Prose/>`，纯文本直接传 |
| avatar | `ReactNode` | 头像槽（传瑚琏 `<Avatar/>`）；不传用角色默认字符 fallback。system 不渲染头像 |
| name | `ReactNode` | 发送者名称（正文上方） |
| timestamp | `ReactNode` | 时间戳（名称右侧，弱化色） |
| actions | `ReactNode` | 底部操作区槽（放 `<MessageActions/>`，仅气泡下方） |

## 示例
```tsx
<ChatMessage role="user" name="我" timestamp="刚刚">
  帮我把首页重写成 100% dogfood
</ChatMessage>

<ChatMessage role="assistant" name="瑚琏 AI" loading>占位</ChatMessage>
```

## 禁忌 / 坑

- `status` 已读回执仅在 `role="user"`（右气泡）渲染，传给 assistant/system 不显示。
- `loading` 为真时正文被 TypingDots 替换，`children` 仅作占位不展示。

## 相关
[Conversation](https://hulianui.haloritual.com/components/conversation) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input) · [TypingDots](https://hulianui.haloritual.com/components/typing-dots) · [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)

<!-- ════════════════════════════════════════════════════════ -->
# Citation

> 引用来源 · 序号角标 + 标题/来源 + href 新标签页外链 · 内联标注 agent 回答信息出处 · 纯皮肤RSC · ai/assist

## 何时用

在 agent 回答正文内联标注信息出处（序号角标 + 来源标题 + 可点外链）时用。本组件是内联的单条引用标记，适合穿插在文字流中；与 [MessageActions](https://hulianui.haloritual.com/components/message-actions)（消息级操作）正交。纯皮肤 RSC，无交互状态。

## 导入
```ts
import { Citation } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLElement>, "title">`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| index | `number` | `1`(showcase) | 引用序号（如 1 → `[1]` 角标） |
| href | `string` | — | 外链 URL；提供则渲染为新标签页链接 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 来源标题（必填；showcase 初值 `"瑚琏设计系统文档"`） |
| source | `ReactNode` | 来源名（域名/站点，标题右侧弱化；showcase 初值 `"hulian.dev"`） |

> showcase 初值仅为画廊控件初值，组件本身除 `title` 外无内置默认。

## 示例
```tsx
// 外链 + 序号 + 来源
<Citation index={1} title="Base UI 文档" href="https://base-ui.com" source="base-ui.com" />

// 正文内联多条
<p className="text-sm leading-loose">
  瑚琏的可达性来自 Base UI
  <Citation index={1} title="Base UI" href="https://base-ui.com" source="base-ui.com" />
  ，表格能力来自 TanStack
  <Citation index={2} title="TanStack Table" href="https://tanstack.com/table" source="tanstack.com" />
  。
</p>
```

## 禁忌 / 坑

- `title` 被从原生 HTMLAttributes 中 Omit 重定义为来源标题（非原生 tooltip title）。
- 不传 `href` 时渲染为非链接的本地来源标记；传了才是 target=_blank 外链。
- 暂无其它已知坑。

## 相关
[StreamingText](https://hulianui.haloritual.com/components/streaming-text) · [PromptSuggestions](https://hulianui.haloritual.com/components/prompt-suggestions) · [MessageActions](https://hulianui.haloritual.com/components/message-actions) · [Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input)

<!-- ════════════════════════════════════════════════════════ -->
# ConfirmCard

> 确认卡 · human-in-the-loop 标准件：结构化字段摘要(dl) + 确认/修正双动作 + acted 锁定态(已确认/修改中) · dogfood Button · ai/agent

## 何时用

agent 执行高风险动作前需要人工核对结构化字段并确认/修正（human-in-the-loop）时用。区别于 [Artifact](https://hulianui.haloritual.com/components/artifact)（承载产出物内容）与 [Dossier](https://hulianui.haloritual.com/components/dossier)（纯展示案卷），本组件核心是 label/value 字段摘要 + 双动作按钮 + 操作后锁定态。

## 导入
```ts
import { ConfirmCard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `ConfirmCardItem[]` | — | 字段摘要数组，每项 `{ label, value }`，渲染为 dl |
| acted | `"confirmed" \| "edited" \| null` | `null` | 已操作结果：锁定双钮并标记所选项 |
| className | `string` | — | 容器附加类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onConfirm | `() => void` | 点击确认回调 |
| onEdit | `() => void` | 点击修改回调；**未提供则不渲染修改钮**（单动作场景） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 卡头标题（默认 `"请确认以下信息"`） |
| confirmText | `ReactNode` | 确认按钮文字（默认 `"确认无误"`） |
| editText | `ReactNode` | 修改按钮文字（默认 `"需要修改"`） |

`ConfirmCardItem`：`{ label: ReactNode; value: ReactNode }`

## 示例
```tsx
const [acted, setActed] = useState<"confirmed" | "edited" | null>(null);

<ConfirmCard
  title="案卷摘要 · 请确认"
  items={[
    { label: "基本信息", value: "林晚晴 · 138-0000-0000" },
    { label: "求职意向", value: "云栖科技 · 总裁私人秘书" },
  ]}
  acted={acted}
  onConfirm={() => setActed("confirmed")}
  onEdit={() => setActed("edited")}
/>
```

## 禁忌 / 坑

- 缺省 `onEdit` 时不渲染修改钮（commit daa1e09 修复，避免单动作场景出现点了无反应的死按钮）；想要双动作必须两个回调都传。
- `acted` 是受控锁定态：操作后需由父级 setState 写回 `acted`，否则按钮不会进入锁定/标记态。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# Conversation

> 消息流容器 · 纵向堆叠 ChatMessage + 内容增长自动贴底(新消息/流式 token)·消费侧给高度获独立滚动区 · ai/conversation

## 何时用

聊天/对话界面里包裹一串 [ChatMessage](https://hulianui.haloritual.com/components/chat-message)，需要新消息或流式 token 追加时自动滚到底的滚动容器。它只管「消息流的滚动与堆叠」；单条气泡用 ChatMessage，底部输入用 [PromptInput](https://hulianui.haloritual.com/components/prompt-input)。

## 导入
```ts
import { Conversation } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`（含 `className`、`children` 等）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| autoScroll | `boolean` | `true` | 内容变化时自动滚到底（贴合聊天流 / 流式 token 追加） |
| hideScrollbar | `boolean` | `false` | 隐藏滚动条（内容仍可滚动，ChatGPT 式沉浸聊天区） |

## 示例
```tsx
<Conversation className="h-72 w-full max-w-lg rounded-[var(--radius)] border border-border p-4">
  <ChatMessage role="user" name="我">瑚琏支持暗色吗？</ChatMessage>
  <ChatMessage role="assistant" name="瑚琏 AI">支持，明暗双主题 0 闪烁。</ChatMessage>
</Conversation>
```

## 禁忌 / 坑

- 容器本身不带高度——必须由消费侧给定高度（如 `h-72` / `h-dvh`）才能形成独立滚动区与触发自动贴底，否则随父容器无限撑高、`autoScroll` 失效。

## 相关
[ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input) · [TypingDots](https://hulianui.haloritual.com/components/typing-dots) · [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)

<!-- ════════════════════════════════════════════════════════ -->
# Dossier

> 案卷面板 · 智能体槽位填充进度可视化：分域清单 + 三态(空心环/半填充/Check) + 当前采集域高亮 + 域内容摘要 + 自动进度(已归档 n/m·可选域不计分母) + bare 内嵌 · 纯皮肤RSC · ai/agent

## 何时用

可视化 agent 按域（slot）逐步采集信息的案卷填充进度：每个域有空/部分/完成三态、当前域高亮、自动算「已归档 n/m」。线性任务步骤用 [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)；这里是分域槽位填充（如访谈逐项收集）。

## 导入
```ts
import { Dossier } from "@hulianui/ui"
```

## Props

`DossierProps`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sections * | `DossierSection[]` | — | 分域清单（数据驱动） |
| bare | `boolean` | `false` | 去掉容器边框背景，内嵌用 |
| className | `string` | — | 容器类名 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 头部标题（默认 `"案卷"`） |
| progress | `ReactNode` | 头部右侧进度文案，缺省自动算「已归档 n/m」（m 不含 optional 域） |

`DossierSection`：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| key * | `string` | — | 域唯一标识 |
| label * | `ReactNode` | — | 域名称 |
| status | `"empty" ｜ "partial" ｜ "done"` | `"empty"` | 空(空心环) / 半填充 / 完成(勾) |
| optional | `boolean` | `false` | 可选域：不计入进度分母，empty 时弱化并标注「可选」 |
| summary | `ReactNode` | — | 已归档内容摘要（一两行） |
| active | `boolean` | `false` | 当前正在采集的域，高亮 |

## 示例
```tsx
<Dossier
  sections={[
    { key: "basic", label: "基本信息", status: "done", summary: "林晚晴 · 138-0000-0000" },
    { key: "education", label: "教育背景", status: "partial", active: true, summary: "待补专业理由" },
    { key: "experience", label: "工作经历", status: "empty" },
    { key: "extras", label: "可选补充", status: "empty", optional: true },
  ]}
/>
```

## 禁忌 / 坑

- 自动进度分母不含 `optional` 域；想让某域参与计数就别标 optional。
- `sections` 纯数据驱动，进度推进靠消费侧更新数组重渲染；内嵌别的卡片里时传 `bare`。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# MessageActions

> 消息操作条 · 复制(剪贴板+Check反馈)/重新生成/赞/踩 · 各键按需渲染 · 复用内联图标 · 挂 ChatMessage actions 槽 · ai/assist

## 何时用

挂在已生成的 assistant 消息下，提供复制/重新生成/赞/踩等操作时用（通常填进 [ChatMessage](https://hulianui.haloritual.com/components/chat-message) 的 actions 槽）。区别于 [PromptSuggestions](https://hulianui.haloritual.com/components/prompt-suggestions)（引导下一步提问），本组件针对「这条消息」的反馈与复用。各按钮按相应回调/content 是否提供而按需渲染。

## 导入
```ts
import { MessageActions } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| content | `string` | — | 复制目标文本；提供则显示复制键（点后 Check 反馈 1.5s） |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onCopy | `() => void` | 复制后回调（与内置剪贴板并行） |
| onRegenerate | `() => void` | 提供则显示重新生成键 |
| onLike | `() => void` | 提供则显示赞键 |
| onDislike | `() => void` | 提供则显示踩键 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 追加自定义操作键 |

## 示例
```tsx
// 全套，挂进 ChatMessage
<ChatMessage
  role="assistant"
  name="瑚琏 AI"
  actions={
    <MessageActions
      content="支持，明暗双主题 0 闪烁。"
      onRegenerate={regen}
      onLike={up}
      onDislike={down}
    />
  }
>
  支持，明暗双主题 0 闪烁。
</ChatMessage>
```

## 禁忌 / 坑

- 每个按钮按需渲染：复制键看 `content`，其余看对应回调是否传入——不传就不显示，无需额外开关。
- 复制内置剪贴板写入 + Check 反馈 1.5s，`onCopy` 是并行附加回调（埋点/toast），不需要你自己再写 `navigator.clipboard`。
- 暂无其它已知坑。

## 相关
[StreamingText](https://hulianui.haloritual.com/components/streaming-text) · [PromptSuggestions](https://hulianui.haloritual.com/components/prompt-suggestions) · [Citation](https://hulianui.haloritual.com/components/citation) · [Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input)

<!-- ════════════════════════════════════════════════════════ -->
# PromptInput

> 提示输入 · 自增高Textarea + 发送/停止键 + Enter提交/Shift+Enter换行/IME合成保护 + 受控非受控两用 + 左侧操作槽 · ai/conversation

## 何时用

聊天界面底部的消息输入框：自增高、Enter 提交、生成中切停止键。对话流上方的消息渲染用 [Conversation](https://hulianui.haloritual.com/components/conversation) + [ChatMessage](https://hulianui.haloritual.com/components/chat-message)；这里只管输入与提交。

## 导入
```ts
import { PromptInput } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| value | `string` | — | 受控值（配 onValueChange） |
| defaultValue | `string` | `""` | 非受控初值 |
| placeholder | `string` | `"发消息…"` | 占位提示 |
| loading | `boolean` | `false` | 生成中：发送键变停止键、屏蔽提交 |
| disabled | `boolean` | `false` | 禁用 |
| maxRows | `number` | `8` | 自增高最大行数（超出滚动） |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onValueChange | `(value: string) => void` | 值变化回调 |
| onSubmit | `(value: string) => void` | 提交（Enter 或点发送）；收到 trim 后的当前文本。非受控时内部自动清空 |
| onStop | `() => void` | 点停止回调（loading 时显示停止键） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| actions | `ReactNode` | 底部工具栏左侧操作槽（深度思考 / 智能搜索等开关 chip） |
| trailing | `ReactNode` | 底部工具栏右侧、发送键之前的尾随槽（附件 / 语音等图标按钮） |

## 示例
```tsx
<PromptInput onSubmit={(v) => send(v)} />

// 生成中：发送键变停止键
<PromptInput loading defaultValue="正在生成回答…" onStop={stop} />
```

## 禁忌 / 坑

- 受控/非受控二选一：传 `value` 必须配 `onValueChange` 自己管状态；非受控（仅 `defaultValue`）时提交后内部自动清空，别再外部清。
- `loading` 时屏蔽提交、发送键变停止键，配套传 `onStop` 否则停止键无响应。
- Enter 提交、Shift+Enter 换行，且内部已做 IME 合成保护（中文输入回车选词不会误提交）。

## 相关
[Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [TypingDots](https://hulianui.haloritual.com/components/typing-dots) · [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)

<!-- ════════════════════════════════════════════════════════ -->
# PromptSuggestions

> 建议提示 · 可点击 pill 列表 + string/{label,value} 两式 + onSelect 回传 value 填充输入或发起对话 · ai/assist

## 何时用

在对话输入区上方给出一组可点击的引导提示 pill（点击后填充输入框或直接发起对话）时用。区别于 [MessageActions](https://hulianui.haloritual.com/components/message-actions)（针对已生成消息的操作），本组件面向「下一步问什么」的引导；点选回传 value 由消费侧决定填充还是发送。

## 导入
```ts
import { PromptSuggestions } from "@hulianui/ui"
```

## Props

继承 `Omit<HTMLAttributes<HTMLDivElement>, "onSelect" | "title">`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| suggestions* | `Suggestion[]` | — | 建议列表 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(value: string) => void` | 点击某项回调（回传其 value） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 可选标题（列表上方弱化） |

`Suggestion`：`string`（label 即 value）或 `{ label: ReactNode; value?: string }`（分离展示文案与回传值）。

## 示例
```tsx
<PromptSuggestions
  title="你可以试试"
  suggestions={["帮我重写首页文案", "解释这段代码", { label: "翻译成英文", value: "translate" }]}
  onSelect={(v) => fillInput(v)}
/>
```

## 禁忌 / 坑

- `onSelect` 与 `title` 已从原生 HTMLAttributes 中 Omit 重定义——别误以为是原生 DOM 事件/属性签名。
- 用 `{ label, value }` 式时若省略 `value`，回传的是 label（ReactNode）派生值；需要稳定标识符就显式给 `value`。
- 暂无其它已知坑。

## 相关
[StreamingText](https://hulianui.haloritual.com/components/streaming-text) · [MessageActions](https://hulianui.haloritual.com/components/message-actions) · [Citation](https://hulianui.haloritual.com/components/citation) · [Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input)

<!-- ════════════════════════════════════════════════════════ -->
# StreamingText

> 流式文本 · 渲染父级累积 text(随token增长) + 流式中尾随闪烁光标(hulian-blink) · 区别 TypingAnimation 自驱定时 · 纯皮肤RSC · ai/assist · #animated

## 何时用

渲染由 SSE/fetch stream 驱动、随 token 到达不断增长的累积文本，并在进行中显示尾随闪烁光标时用。区别于 TypingAnimation（内部自驱定时逐字打字），本组件不自己造字——只渲染父级传入的 `text`，光标由 `streaming` 控制。

## 导入
```ts
import { StreamingText } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLElement>`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| text* | `string` | — | 当前累积文本（随 token 到达由父级增长） |
| streaming | `boolean` | — | 流式进行中：尾随闪烁光标；done 后去除光标 |
| as | `ElementType` | `"span"` | 渲染标签 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| cursor | `ReactNode` | 自定义光标节点（默认闪烁竖线） |

## 示例
```tsx
// 实战：text 由流式接口推进，done 时关 streaming
<StreamingText text={text} streaming={!done} />

// 静态片段 + 常驻光标（如「正在思考」占位）
<StreamingText text="正在思考你的问题" streaming />
```

## 禁忌 / 坑

- 纯皮肤组件：不自己造字。`text` 必须由父级累积增长（SSE/stream），传静态全文不会有逐字效果。
- 流式结束务必把 `streaming` 置 false，否则光标一直闪。
- 暂无其它已知坑。

## 相关
[PromptSuggestions](https://hulianui.haloritual.com/components/prompt-suggestions) · [MessageActions](https://hulianui.haloritual.com/components/message-actions) · [Citation](https://hulianui.haloritual.com/components/citation) · [Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input)

<!-- ════════════════════════════════════════════════════════ -->
# TaskRunner

> 任务运行卡 · dogfood AgentPlan(bare)步骤列表 + Progress顶部进度 + Tag标签 + Dot状态徽标 · idle/running/success/error四态派生 + 每步耗时(meta)/running行高亮/pending空心环 + progress省略按完成比派生 + 累计耗时footer + headerExtra/footerExtra送掣 · 纯展示RSC(计时驱动留消费侧) · ai/agent

## 何时用

展示一组按序执行的任务步骤及整体运行状态（沙箱启动、部署流水线等），需要顶部进度条、每步耗时、running 高亮、累计耗时页脚时用。区别于 [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)（纯计划/勾选清单），本组件多了运行态徽标 + 进度 + 计时框架。本组件是纯展示 RSC，计时/状态推进逻辑留在消费侧。

## 导入
```ts
import { TaskRunner, resolveProgress, statusMeta } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| steps* | `AgentTask[]` | — | 步骤清单（复用 AgentTask：title/status/detail/meta，耗时放 meta） |
| status | `"idle" \| "running" \| "success" \| "error"` | `"idle"` | 整体运行状态：驱动头部徽标色 + 进度条 tone |
| progress | `number` | — | 顶部进度 0-100；省略则按 steps 完成(done)比自动派生 |
| className | `string` | — | 容器附加类 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title* | `ReactNode` | 卡头标题（如 `"Sandbox"`） |
| tag | `ReactNode` | 标题旁标签（如 `"node26"`），渲染为浅底 Tag |
| statusLabel | `ReactNode` | 头部徽标文字覆盖；省略时按 status 派生（Idle/Running/Done/Failed） |
| elapsed | `ReactNode` | 底部左侧累计耗时（如 `"3.12s"`） |
| footerStatus | `ReactNode` | 底部右侧状态文字；footerExtra 存在时被其替换 |
| headerExtra | `ReactNode` | 头部右侧追加（按钮/菜单等） |
| footerExtra | `ReactNode` | 替换底部右侧内容 |

`AgentTask` 步骤项 `status`：`"done"`（已完成，meta 显耗时）/ `"running"`（高亮）/ `"pending"`（空心环）/ `"error"`。

## 示例
```tsx
const SANDBOX_STEPS: AgentTask[] = [
  { title: "Allocate microVM", status: "done", meta: "180ms" },
  { title: "Boot runtime · Node 26", status: "done", meta: "1082ms" },
  { title: "Execute main.js", status: "running", meta: "…" },
  { title: "Reclaim sandbox", status: "pending" },
];

<TaskRunner
  title="Sandbox"
  tag="node26"
  status="running"
  steps={SANDBOX_STEPS}
  progress={58}
  elapsed="3.12s"
  footerStatus="Executing…"
/>
```

## 禁忌 / 坑

- 纯展示组件：不自带计时器/步骤推进。运行驱动（setInterval 推进 status、累计 elapsed）放消费侧，把派生出的 steps/status/elapsed 喂进来。
- `progress` 省略时按 steps 中 done 占比自动派生；想要平滑的非整步进度（如 58%）须显式传 `progress`。
- `footerExtra` 会覆盖 `footerStatus`，二者不要指望同时显示。
- 暂无其它已知坑。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card)

<!-- ════════════════════════════════════════════════════════ -->
# ThinkingBlock

> 思考折叠块 · dogfood Collapsible(自带chevron+平滑高度) + thinking态(转圈+AnimatedShinyText高光+默认展开) + 耗时标记·收起隐藏 chain-of-thought · ai/agent · #animated

## 何时用

折叠展示 agent 的 chain-of-thought 推理过程，思考中转圈高光、完成后可收起。结构化的步骤清单用 [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)，单次工具调用用 [ToolCall](https://hulianui.haloritual.com/components/tool-call)；这里是自由文本推理。

## 导入
```ts
import { ThinkingBlock } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| thinking | `boolean` | `false` | 进行态：标题转圈 + 高光流动，且默认展开（agent 正在推理） |
| defaultOpen | `boolean` | 随 thinking | 非受控初始展开态 |
| open | `boolean` | — | 受控展开态 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange | `(open: boolean) => void` | 展开态变化回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 头部标题（默认「思考过程」） |
| duration | `ReactNode` | 耗时标记（标题右侧弱化，如「思考 3s」） |
| children | `ReactNode` | 推理正文（markdown 建议外包 `<Prose/>`） |

## 示例
```tsx
<ThinkingBlock duration="思考 3s">{reasoning}</ThinkingBlock>

// 推理中：转圈 + 高光 + 默认展开
<ThinkingBlock thinking>{reasoning}</ThinkingBlock>
```

## 禁忌 / 坑

- 受控/非受控二选一：传 `open` 须配 `onOpenChange` 自己管；只想给初值用 `defaultOpen`。
- 不传 `defaultOpen`/`open` 时展开态默认随 `thinking`（思考中展开、完成收起）。

## 相关
[ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# ThreadList

> 会话历史列表 · ChatGPT 式智能体侧栏：标题+meta 双行条目 + active 高亮 + 删除按钮(stopPropagation 不触发选中) + 头部动作槽(新对话) + 空态占位 + bare 内嵌 · ai/agent

## 何时用

智能体侧栏的会话历史列表（标题+相对时间双行、active 高亮、删除）时用。本组件管的是「切换/删除历史会话」，不是消息流本身；单条消息的操作条用 [MessageActions](https://hulianui.haloritual.com/components/message-actions)。需要去边框内嵌进自有侧栏布局时传 `bare`。

## 导入
```ts
import { ThreadList } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `ThreadListItem[]` | — | 会话条目数组 |
| bare | `boolean` | `false` | 去掉容器边框背景，内嵌用 |
| className | `string` | — | 容器附加类 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onSelect | `(id: string) => void` | 点击条目回调 |
| onDelete | `(id: string) => void` | 提供则每项渲染删除按钮（点击 stopPropagation，不触发 onSelect） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| title | `ReactNode` | 头部标题（默认 `"历史"`） |
| action | `ReactNode` | 头部右侧动作槽（如「新对话」按钮） |
| empty | `ReactNode` | items 为空时的占位（默认 `"暂无历史"`） |

`ThreadListItem`：`{ id: string; title: ReactNode; meta?: ReactNode; active?: boolean }`（meta 为次行元信息，active 标当前打开会话）

## 示例
```tsx
const [items, setItems] = useState(seed);
const [activeId, setActiveId] = useState("a");

<ThreadList
  items={items.map((it) => ({ ...it, active: it.id === activeId }))}
  onSelect={setActiveId}
  onDelete={(id) => setItems((cur) => cur.filter((it) => it.id !== id))}
  action={
    <Button size="sm" variant="ghost">
      <Plus className="size-3.5" aria-hidden />
      新对话
    </Button>
  }
/>
```

## 禁忌 / 坑

- `active` 高亮由 item 上的 `active` 字段驱动，不是组件内部维护——需父级在 map 时按 activeId 计算写入。
- 删除钮仅在传了 `onDelete` 时渲染；其点击已内置 stopPropagation，不会顺带触发 onSelect。
- 暂无其它已知坑。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card)

<!-- ════════════════════════════════════════════════════════ -->
# ToolCall

> 工具调用卡 · dogfood Collapsible + Dot状态色 + Spinner(运行中) · pending/running/success/error 四态 + 参数/结果折叠面板 + 工具图标 · ai/agent

## 何时用

可视化 agent 的单次工具调用（名称 + 状态 + 折叠的入参/结果）。多步任务编排用 [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)，自由文本推理用 [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block)；这里聚焦一次 tool call 的输入输出。

## 导入
```ts
import { ToolCall } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| status | `"pending" ｜ "running" ｜ "success" ｜ "error"` | `"success"` | pending 等待 / running 运行中(转圈) / success 完成 / error 失败 |
| defaultOpen | `boolean` | — | 非受控初始展开态 |
| open | `boolean` | — | 受控展开态 |
| className | `string` | — | 容器类名 |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onOpenChange | `(open: boolean) => void` | 展开态变化回调 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| name * | `ReactNode` | 工具名（等宽呈现，如 search_web） |
| icon | `ReactNode` | 工具图标槽（默认扳手 Wrench） |
| input | `ReactNode` | 入参（建议传 `<CodeBlock/>` 或 JSON 文本） |
| output | `ReactNode` | 结果（建议传 `<CodeBlock/>` / `<Prose/>` 或文本） |
| children | `ReactNode` | 自定义面板内容（替代 input/output） |

## 示例
```tsx
<ToolCall
  name="search_web"
  status="success"
  defaultOpen
  input={<CodeBlock lang="json" code={'{ "query": "瑚琏 设计系统" }'} />}
  output="找到 3 条相关结果，已综合。"
/>

<ToolCall name="run_code" status="running" />
```

## 禁忌 / 坑

- 受控/非受控二选一：传 `open` 须配 `onOpenChange`；只想给初值用 `defaultOpen`。
- `children` 会替代 `input`/`output` 面板，二者择一传。

## 相关
[ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan) · [Dossier](https://hulianui.haloritual.com/components/dossier) · [Artifact](https://hulianui.haloritual.com/components/artifact) · [ConfirmCard](https://hulianui.haloritual.com/components/confirm-card) · [ThreadList](https://hulianui.haloritual.com/components/thread-list)

<!-- ════════════════════════════════════════════════════════ -->
# TypingDots

> 打字指示 · 三点交错弹跳(纯CSS·RSC) + reduced-motion停 + role=status·配 ChatMessage loading · ai/agent · #animated

## 何时用

「对方/agent 正在输入」的三点弹跳指示。气泡内的生成态通常直接用 [ChatMessage](https://hulianui.haloritual.com/components/chat-message) 的 `loading` 即可（内部就是它）；需要在自定义容器里单放时才直接用本组件。

## 导入
```ts
import { TypingDots } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLSpanElement>`（含 `className` 等）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| label | `string` | `"正在输入"` | 无障碍标签（读屏播报，`role=status`） |

## 示例
```tsx
<TypingDots />

// 气泡内
<span className="inline-flex rounded-[var(--radius)] bg-surface px-3.5 py-2.5">
  <TypingDots />
</span>
```

## 禁忌 / 坑

- 纯 CSS 动画，已响应 `prefers-reduced-motion`（用户关动效时三点停止跳动）；无需自己加判断。

## 相关
[Conversation](https://hulianui.haloritual.com/components/conversation) · [ChatMessage](https://hulianui.haloritual.com/components/chat-message) · [PromptInput](https://hulianui.haloritual.com/components/prompt-input) · [ThinkingBlock](https://hulianui.haloritual.com/components/thinking-block) · [ToolCall](https://hulianui.haloritual.com/components/tool-call) · [AgentPlan](https://hulianui.haloritual.com/components/agent-plan)


# ━━━━━━━━ 装饰 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# AnimatedBeam

> 动效光束 · 连接两元素的流光曲线(motion 渐变 + SVG + ResizeObserver) · decoration/overlay-fx · #animated

## 何时用

想在画布里把两个 DOM 节点用一条会流光的曲线连接起来（架构图、集成示意、AI 数据流、"汇聚到中枢"动效）时用。它靠 `containerRef`/`fromRef`/`toRef` 测量端点几何并画 SVG 曲线，可叠多条组合成网络。要绕单个容器边框的光点用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；要图标沿圆周公转用 [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)。

## 导入
```ts
import { AnimatedBeam } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| containerRef* | `RefObject<HTMLElement \| null>` | — | 定位基准容器，须 `position:relative` |
| fromRef* | `RefObject<HTMLElement \| null>` | — | 起点元素 ref |
| toRef* | `RefObject<HTMLElement \| null>` | — | 终点元素 ref |
| curvature | `number` | `0` | 曲率（>0 上凸） |
| reverse | `boolean` | `false` | 光束反向流动 |
| duration | `number` | — | 一趟时长(s) |
| delay | `number` | — | 起始延迟 |
| pathColor | `string` | border token | 底线颜色 |
| pathWidth | `number` | — | 底线宽度 |
| pathOpacity | `number` | — | 底线不透明度 |
| gradientStartColor | `string` | chart token | 流光渐变起色 |
| gradientStopColor | `string` | chart token | 流光渐变止色 |
| startXOffset / startYOffset | `number` | — | 起点偏移 |
| endXOffset / endYOffset | `number` | — | 终点偏移 |
| className | `string` | — | 透传 className |

## 示例

```tsx
"use client";
function Demo() {
  const container = useRef<HTMLDivElement>(null);
  const from = useRef<HTMLDivElement>(null);
  const to = useRef<HTMLDivElement>(null);
  return (
    <div ref={container} className="relative flex items-center justify-between">
      <div ref={from} className="size-12 rounded-full bg-surface" />
      <div ref={to} className="size-12 rounded-full bg-surface" />
      {/* 流向用 reverse 控制：false=左→右、true=右→左 */}
      <AnimatedBeam containerRef={container} fromRef={from} toRef={to} reverse={false} />
    </div>
  );
}
```

## 禁忌 / 坑

- 客户端组件，依赖 ref 测量，必须 `"use client"`；`containerRef` 容器必须 `position:relative`，否则曲线坐标错位。
- 流光扫描方向由 `reverse` 决定（沿容器水平方向，与 path 端点顺序无关）：`false` 左→右、`true` 右→左；做"四周汇聚到中枢"时需让右侧光束 `reverse`。
- 颜色 prop 喂 token 需带 `--color-` 前缀——参见 [[hulian-token-color-var-needs-color-prefix]]。
- 端点元素与光束同处容器，记得给端点 `z-10` 之类层级使其压在光束上。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# Antigravity

> 反重力粒子吸附背景 · 光标靠近把漂浮粒子吸入环绕轨道(波动+脉冲+取向)，离开缓回原位 · 磁吸半径/环半径/形状/自动巡游可调(canvas2d 零依赖·token 配色·reduced-motion 静态点阵) · decoration/overlay-fx · #animated

## 何时用

需要整片粒子背景，光标靠近把粒子吸入环绕轨道、离开缓回（hero 区、大屏装饰）时用。它是 canvas2d 粒子吸附；要光标本身的果冻拖尾用 [BlobCursor](https://hulianui.haloritual.com/components/blob-cursor)，要点击迸发火花用 [ClickSpark](https://hulianui.haloritual.com/components/click-spark)，要边框流光描边用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)。

## 导入
```ts
import { Antigravity } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| count | `number` | `240` | 粒子数量；越多越费性能，移动端建议 ≤ 200 |
| magnetRadius | `number` | `130` | 磁吸半径（px）；光标进入此范围的粒子被吸入轨道 |
| ringRadius | `number` | `56` | 环绕轨道基础半径（px） |
| waveSpeed | `number` | `0.4` | 环上波动速度（轨道半径随角度/时间起伏快慢） |
| waveAmplitude | `number` | `10` | 环上波动幅度（px），越大轨道越毛糙有机 |
| particleSize | `number` | `4` | 粒子基础尺寸（px）；dot=直径 / square=边长 / bar=长度 |
| lerpSpeed | `number` | `0.12` | 粒子追踪目标的缓动系数（0–1），越大越紧跟 |
| color | `string` | `var(--color-chart-1)` | 粒子颜色（自动明暗适配），可传任意 CSS 颜色 |
| autoAnimate | `boolean` | `false` | 光标静止 2s 后是否自动巡游（无人操作也动） |
| rotationSpeed | `number` | `0` | 整环随时间旋转角速度（rad/s），0=不自转 |
| pulseSpeed | `number` | `3` | 粒子脉冲缩放速度（被吸住时大小呼吸快慢） |
| shape | `"dot" \| "square" \| "bar"` | `"bar"` | 粒子形状 |
| className | `string` | — | 透传到根容器（canvas 包裹层 / fallback） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion 或无 canvas2d 时的自定义静态备用内容 |

## 示例
```tsx
// 默认短棒粒子，铺满定位父级
<div className="relative h-64 overflow-hidden rounded-xl">
  <Antigravity className="absolute inset-0" />
</div>

// 自动巡游 + 方块 + token 配色
<Antigravity
  className="absolute inset-0"
  autoAnimate
  rotationSpeed={0.4}
  shape="square"
  color="var(--color-chart-2)"
/>
```

## 禁忌 / 坑

- 客户端组件（canvas2d）：父级须为定位上下文且有明确高度，组件用 `absolute inset-0` 铺满。
- `color` 用 token 必须带 `--color-` 前缀（`var(--color-chart-1)`），canvas 喂裸 `var(--chart-1)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- `count` 直接影响性能，移动端/低端机控制在 ≤ 200。
- reduced-motion 或无 canvas2d 环境降级为静态点阵，可用 `fallback` 自定义。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Aurora

> 极光渐变背景 · 双层 repeating-linear-gradient 横移干涉 + 径向 mask 聚焦 + chart token(纯 CSS·RSC) · decoration/backdrop · #animated

## 何时用

需要柔和流动的彩色渐变背景（Hero / 登录页 / 营销区块）时用。纯 CSS 实现、可作为 RSC 直接服务端渲染、无 canvas/WebGL 开销，是首选的低成本动态背景；若要逐颗粒子或鼠标交互，用 [Particles](https://hulianui.haloritual.com/components/particles)；若要质感更强的丝绸/虹彩光泽，用 [Silk](https://hulianui.haloritual.com/components/silk) / [Iridescence](https://hulianui.haloritual.com/components/iridescence)（但它们依赖 WebGL）。

## 导入
```ts
import { Aurora } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | string[] | `["var(--color-chart-1)","var(--color-chart-2)","var(--color-chart-4)"]` | 极光色带，任意 CSS 颜色字符串（hex/oklch/var）。默认吃 chart token 自动明暗适配 |
| blur | number | 30 | 极光层模糊半径（px），建议 10–80；过小边缘硬，过大效果消散 |
| speed | number | 20 | 完整一轮动画时长（秒），越大越慢越细腻 |
| showRadialMask | boolean | true | 径向渐隐 mask（聚焦中部四角淡出），关闭则铺满容器无渐隐 |
| className | string | — | 透传到极光层 div（可调透明度/混合模式） |
| style | CSSProperties | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | ReactNode | 覆盖在极光上方的内容（relative 层叠） |

## 示例
```tsx
// 深色底上叠极光，内容层用 relative 自然层叠在背景之上
<div className="relative h-56 overflow-hidden rounded-xl">
  <Aurora className="absolute inset-0 opacity-80">
    <div className="flex h-full items-center justify-center text-white/80">Aurora</div>
  </Aurora>
</div>
```
```tsx
// 自定义暖橙色带 + 更慢更柔
<Aurora
  colors={["var(--color-chart-3)", "var(--color-chart-1)", "oklch(0.72 0.22 30)"]}
  blur={40}
  speed={25}
  className="absolute inset-0 opacity-75"
/>
```

## 禁忌 / 坑

- 父容器需 `relative` + `overflow-hidden`，否则横移的渐变层会溢出。
- 极光透明度建议靠 `className` 上的 `opacity-*` 控制（showcase 全用 `opacity-60~90`）；直接铺满不透明会盖死下层内容。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Balatro

> 螺旋油彩 WebGL 背景 · 像素旋涡 + 5 次正弦迭代油画混色 + 可选鼠标交互/自转(ogl·三色吃 chart token·reduced-motion conic 兜底) · decoration/backdrop · #animated #webgl

## 何时用

需要浓墨油画质感、有旋涡流动感的满铺背景时用（登录页、Hero、卡片底纹）。要规则几何点阵/网格底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要轻量纯色光晕用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；Balatro 是重 GPU 的有机色块旋涡，适合做主视觉而非细节装饰。

## 导入
```ts
import { Balatro } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| spinRotation | `number` | `-2.0` | 旋涡静态旋转量（isRotate=false 时生效），正负决定旋向 |
| spinSpeed | `number` | `7.0` | 油彩内部流动速度因子，越大旋涡翻涌越剧烈 |
| offset | `[number, number]` | `[0, 0]` | 旋涡中心相对屏幕中点的偏移 [x, y] |
| color1 | `string` | `--color-chart-1` | 主色（旋涡亮带），CSS 颜色字符串，默认取主题色明暗自适应 |
| color2 | `string` | `--color-chart-2` | 次色（旋涡中段），CSS 颜色字符串 |
| color3 | `string` | `--color-chart-5` | 底色（旋涡暗部/缝隙），CSS 颜色字符串 |
| contrast | `number` | `3.5` | 对比度，越大三色分界越锐利 |
| lighting | `number` | `0.4` | 高光强度，越大旋涡峰值越亮；0=无额外高光 |
| spinAmount | `number` | `0.25` | 旋转随半径的衰减量，越大螺旋拖尾越明显 |
| pixelFilter | `number` | `745` | 像素化强度，越大像素块越小（越精细），越小越复古马赛克 |
| spinEase | `number` | `1.0` | 旋转缓动系数，整体缩放旋转量与速度作微调 |
| isRotate | `boolean` | `false` | 是否随时间持续自转；true 时 spinRotation 改为驱动旋转速度 |
| mouseInteraction | `boolean` | `true` | 是否开启鼠标交互；关闭后 pointer-events-none |
| className | `string` | — | 透传到根容器（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认 conic 旋涡兜底） |

## 示例
```tsx
// 满铺背景：放在 relative 容器内，组件自带 absolute inset-0 z-0
<div className="relative h-64 overflow-hidden rounded-xl">
  <Balatro />
  <div className="relative z-10 flex h-full items-center justify-center text-white">
    Balatro
  </div>
</div>
```
```tsx
// 自定义暖橙旋涡 + 持续自转
<Balatro
  color1="oklch(0.72 0.2 40)"
  color2="oklch(0.6 0.18 25)"
  color3="oklch(0.18 0.04 30)"
  isRotate
  spinSpeed={5}
  lighting={0.6}
/>
```

## 禁忌 / 坑

- **WebGL 客户端渲染**：组件依赖 ogl + WebGL，须在客户端挂载（`"use client"` 链路），SSR 阶段降级到 `fallback`（conic-gradient 兜底）。Next.js 服务端文件勿直接导入到 server component 树顶。
- **token 颜色须带 `--color-` 前缀**：自定义 color1/2/3 传 CSS 变量时必须写完整名（如 `var(--color-chart-1)`），裸 `var(--chart-1)` 不解析 → 旋涡变黑。见 [[hulian-token-color-var-needs-color-prefix]]。
- 父容器须 `relative` + `overflow-hidden`，否则 `absolute inset-0` 铺不住或溢出。
- 持续自转 + 大 `lighting` 在低端设备上吃 GPU，慎在长列表里多实例叠加。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Ballpit

> 一坑彩色小球的可交互物理球池 · 重力下落+墙壁回弹+球球弹性碰撞+光标排斥(零依赖 canvas2d·chart token·reduced-motion) · decoration/backdrop · #animated #webgl

## 何时用

需要俏皮、可触碰的物理交互背景时用（落地页 Hero、空状态、品牌玩味区）。要静态规则底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要油彩流场用 [Balatro](https://hulianui.haloritual.com/components/balatro)；Ballpit 是 canvas2d 实时物理模拟（O(n²) 碰撞），强调交互而非细腻纹理，球多了会掉帧。

## 导入
```ts
import { Ballpit } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| count | `number` | `80` | 小球数量上限；实际随容器面积自适应缩减。碰撞 O(n²)，建议 ≤ 200 |
| colors | `string[]` | chart token ×5 | 小球配色，按索引循环分配；可传任意 CSS 颜色字符串，默认吃明暗主题 |
| gravity | `number` | `900` | 重力强度（px/s²）；0=失重漂浮，越大越快下沉 |
| bounce | `number` | `0.86` | 墙壁/互撞能量保留系数（0–1）；1=完全弹性永不停 |
| sizeRange | `[number, number]` | `[10, 26]` | 小球半径范围 [最小,最大]（px）；另受容器短边约束 |
| followCursor | `boolean` | `true` | 是否跟随光标形成排斥球推开周围小球；关闭后光标无交互 |
| className | `string` | — | 透传到根容器；组件自带 absolute inset-0 z-0 |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 canvas 时的静态兜底（默认一组静态排布的小球占位） |

## 示例
```tsx
// 默认球池：放在 relative 容器内，移动光标推开小球
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <Ballpit />
</div>
```
```tsx
// 失重漂浮 + 完全弹性
<Ballpit gravity={0} bounce={1} count={60} />
```

## 禁忌 / 坑

- **球数 vs 容器面积**：`count` 是上限，组件按「球总面积 ≤ 容器约 42%」自适应缩减；窄卡里硬塞大球（如 count=28 / r∈[24,44]）会触发超填充抖动 —— 让组件自适应，或自己把 count/sizeRange 调小。
- **O(n²) 碰撞**：球数过大（>200）实时碰撞检测会卡顿，背景场景建议小半径多球而非大球。
- **客户端渲染**：依赖 canvas2d 与 `requestAnimationFrame`，SSR 阶段渲染 `fallback` 静态占位；勿在 server component 直接挂载实时逻辑。
- 父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Beams

> 流动体积光柱 WebGL 背景 · perlin 噪声扰动起伏 + 方向光受光梯度 + 倾斜光幕 + 胶片颗粒(ogl·token·reduced-motion 降级静态渐变) · decoration/backdrop · #animated #webgl

## 何时用

需要冷感、有纵深的斜射体积光背景时用（科技产品 Hero、暗色落地页）。要规则点阵/网格底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要油彩旋涡用 [Balatro](https://hulianui.haloritual.com/components/balatro)；Beams 是条带状流动光幕，强调方向感与胶片质感，适合做主视觉满铺背景。

## 导入
```ts
import { Beams } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| beamNumber | `number` | `12` | 光束数量（纵向条带数），建议 4–24，过大低端设备糊成一片 |
| beamWidth | `number` | `2` | 单束光的相对宽度，越大束间缝隙越窄 |
| speed | `number` | `2` | 光束沿轴流动速度；0=静止（仍保留静态纹理） |
| lightColor | `string` | `--color-chart-1` | 光束颜色，CSS 颜色字符串，默认取主题 token 明暗自适应 |
| noiseIntensity | `number` | `1.75` | 颗粒噪声强度，模拟胶片质感；0=纯净无颗粒 |
| scale | `number` | `0.2` | 噪声纹理缩放，越小波纹越舒展，越大越细碎 |
| rotation | `number` | `30` | 整组光束旋转角度（度）；0=垂直，正值顺时针斜射 |
| className | `string` | — | 透传到根容器（根自带 absolute inset-0 z-0） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时降级渲染的静态内容（叠在渐变兜底之上） |

## 示例
```tsx
// 默认光束背景
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <Beams />
</div>
```
```tsx
// 暖橙宽束斜射光幕
<Beams
  lightColor="oklch(0.78 0.18 55)"
  beamNumber={8}
  beamWidth={3}
  rotation={20}
  scale={0.3}
/>
```

## 禁忌 / 坑

- **WebGL 客户端渲染**：依赖 ogl + WebGL，SSR 阶段降级到 `fallback`（静态渐变）；勿在 server component 直接挂载。
- **token 颜色须带 `--color-` 前缀**：`lightColor` 传 CSS 变量须写 `var(--color-chart-1)` 完整名，裸 `var(--chart-1)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- `beamNumber` 过大（>24）在低性能设备会糊成一片，且吃 GPU。
- 父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# BlobCursor

> 果冻光标拖尾组件 · 领头跟手 + 多滴弹性拖尾经 SVG gooey 滤镜融成液态水银(去 gsap·motion useSpring·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要光标本身呈液态水银/果冻形态、移动时多滴弹性拖尾融合（趣味 hero、创意落地页）时用。它做的是「光标形态」；要光标在容器内落下字形拖尾用 [TextCursor](https://hulianui.haloritual.com/components/text-cursor)，要满屏粒子吸附背景用 [Antigravity](https://hulianui.haloritual.com/components/antigravity)，要准星十字线用 [Crosshair](https://hulianui.haloritual.com/components/crosshair)。

## 导入
```ts
import { BlobCursor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| trailCount | `number` | `3` | 拖尾水滴数量（含领头）；越多越黏稠 |
| sizes | `number[]` | `[56, 116, 72]` | 各水滴直径（px），按索引取用、不足循环 |
| innerSizes | `number[]` | `[18, 32, 22]` | 各水滴内部高光点直径（px），同样循环复用 |
| fillColor | `string` | `var(--color-primary)` | 水滴主体填充色，可传任意 CSS 颜色 |
| innerColor | `string` | `var(--color-primary-foreground)` | 内部高光点颜色 |
| square | `boolean` | `false` | 是否方形水滴（false=圆形）；方形配 gooey 得液态方块 |
| gooey | `boolean` | `true` | 是否启用 SVG gooey 融合滤镜；关则各水滴独立 |
| gooeyStrength | `number` | `16` | gooey 高斯模糊标准差，越大融合范围越广、边缘越软 |
| leadStiffness | `number` | `500` | 领头水滴跟手弹簧刚度（越大越跟手） |
| trailStiffness | `number` | `120` | 拖尾水滴弹簧刚度（越小拖尾越长） |
| damping | `number` | `28` | 弹簧阻尼（越大越不回弹、越黏） |
| zIndex | `number` | `50` | 容器层级；水滴层不拦截指针（pointer-events:none） |
| className | `string` | — | 透传到根容器（relative，铺满父级） |
| style | `CSSProperties` | — | 透传到根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在水滴上方的内容（relative z-10） |

## 示例
```tsx
// 默认：移入舞台见果冻跟随
<div className="relative h-64 overflow-hidden rounded-xl">
  <BlobCursor>
    <div className="pointer-events-none flex h-full items-center justify-center">
      移动鼠标 →
    </div>
  </BlobCursor>
</div>

// 长拖尾（5 滴 · 低刚度更拖泥带水）
<BlobCursor trailCount={5} trailStiffness={70} />
```

## 禁忌 / 坑

- 客户端组件：根容器 relative 铺满父级，父级须有明确高度且 `overflow-hidden`。
- `sizes`/`innerSizes` 数组长度建议 ≥ `trailCount`，不足时按索引循环复用，不会报错但配色/尺寸会重复。
- `gooey` 关闭后水滴各自独立、不再融合，方形水滴失去液态块观感。
- 水滴层 `pointer-events:none`，不拦截下层交互；要在其上叠内容用 `children`（自带 z-10）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# BorderBeam

> 边框光束 · motion offsetPath 绕边 + mask 只露边框 · decoration/overlay-fx · #animated

## 何时用

想给卡片/容器边框加一段沿边匀速绕行的彩色光点（强调、加载中、AI 卡片高亮）时用。它是绝对定位的覆盖件，需放进 `relative` 容器内。要的是整条边框持续流光渐变（非一个光点绕圈）用 [ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要连接两个元素的光束用 [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam)；要 hover 斜扫反光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。

## 导入
```ts
import { BorderBeam } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `number` | `50` | 光束方块边长 px（showcase 默认演示用 60） |
| duration | `number` | `6` | 绕行一轮秒数 |
| delay | `number` | `0` | 起始延迟秒 |
| colorFrom | `string` | `var(--color-primary)` | 光束起色 |
| colorTo | `string` | `var(--color-chart-2)` | 光束止色 |
| reverse | `boolean` | `false` | 反向绕行 |
| initialOffset | `number` | `0` | 起始偏移 0–100 |
| borderWidth | `number` | `1` | 边框宽度 px |
| className | `string` | — | 透传 className |
| style | `CSSProperties` | — | 透传内联样式 |

## 示例

```tsx
// 须放进 relative + overflow-hidden 容器
<div className="relative overflow-hidden rounded-xl border bg-surface">
  ...content
  <BorderBeam />
</div>
```

```tsx
<div className="relative overflow-hidden rounded-xl">
  ...content
  <BorderBeam reverse duration={10} size={80} />
</div>
```

## 禁忌 / 坑

- 必须置于 `position:relative` 容器内，且容器一般 `overflow-hidden`，否则光束绕到圆角外溢出。
- 颜色 prop 喂 token 时需带 `--color-` 前缀（默认值已带），裸 `var(--primary)` 不解析——参见 [[hulian-token-color-var-needs-color-prefix]]。
- 基于 motion 动画，reduced-motion 偏好下应预期被弱化/停止。

## 相关
[ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# BorderGlow

> 指针感应发光边框卡片 · 沿光锥点亮彩色网格边框 + 外层霓虹光晕(随边缘贴近度渐变) + 可选挂载自动扫光(零依赖·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要一张内容容器，指针靠近时沿光锥点亮彩色边框 + 外层霓虹光晕的卡片时用，自带可选挂载自动扫光。要给任意现有元素加旋转边框光带用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam) 或 [ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要做悬停眩光高光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。BorderGlow 偏「整卡 + 指针追踪光锥」，是有内容承载的容器型。

## 导入
```ts
import { BorderGlow } from "@hulianui/ui"
```

## Props

继承 `<div>` 属性（已 `Omit` 掉 `color`）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| className | `string` | — | 透传根容器 className（合并进 `.border-glow`） |
| edgeSensitivity | `number` | `30` | 边缘灵敏度 0–100，越小越早触发外层光晕 |
| glowColor | `string` | `var(--color-chart-1)` | 外层光晕色（box-shadow），token 须带 `--color-` 前缀 |
| backgroundColor | `string` | 深色(surface 暗调) | 卡片底色，发光依赖深底对比，浅底下变弱 |
| borderRadius | `number` | `28` | 圆角半径 px |
| glowRadius | `number` | `40` | 外层光晕溢出内边距 px，越大扩散越远 |
| glowIntensity | `number` | `1` | 光晕强度倍率 0–2 |
| coneSpread | `number` | `25` | 光锥角度宽度 0–50，越大高亮弧越宽 |
| animated | `boolean` | `false` | 挂载时自动播一圈扫光；reduced-motion 下跳过 |
| colors | `string[]` | chart-1/3/4 | 彩色网格边框取色，循环映射到 7 个 radial 锚点 |
| fillOpacity | `number` | `0.5` | 边缘彩色填充层透明度 0–1 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 卡片内容，层叠在所有发光层之上 |

## 示例

```tsx
// 默认：移入卡片沿指针点亮边框
<BorderGlow>
  <div className="w-64 p-7">
    <p className="text-base font-semibold">瑚琏组件库</p>
    <p className="mt-1.5 text-sm text-white/55">把指针移到卡片上，边框会沿光锥点亮。</p>
  </div>
</BorderGlow>

// 挂载自动扫光 + 自定义青调发光
<BorderGlow
  animated
  glowColor="var(--color-chart-2)"
  colors={["var(--color-chart-2)", "var(--color-chart-4)", "var(--color-chart-5)"]}
  glowRadius={56}
>
  {children}
</BorderGlow>
```

## 禁忌 / 坑

- 发光边框依赖深色底对比，放在浅色背景上效果显著变弱；用 `backgroundColor` 保持深底。
- `glowColor`/`colors` 喂 token 必须带 `--color-` 前缀（Tailwind v4 真名），裸 `var(--primary)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- 指针追踪与 `animated` 扫光均受 reduced-motion 影响：用户偏好减少动画时自动跳过扫光（DOM 不变）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# CardSpotlight

> 聚光卡片 · 鼠标跟随径向高光(纯 CSS 变量 + radial-gradient) + color-mix 高光色 + surface token(零依赖) · decoration/overlay-fx · #animated

## 何时用

包裹特性卡 / 作品卡 / 定价卡等内容，鼠标悬停时跟随出现一束柔和径向高光，增强可交互的「活」感。聚光锚在卡片自身、随指针移动；要做整页鼠标跟随的边框走光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)，要做悬停时整面眩光扫过用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)，要做局部内容放大用 [Lens](https://hulianui.haloritual.com/components/lens)。

## 导入
```ts
import { CardSpotlight } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`（`className`、`style`、`onClick` 等照常透传）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| radius | `number` | `350` | 聚光灯半径(px)，越大高光扩散越广，越小越聚焦。 |
| color | `string` | chart-1 token | 聚光高光色，接受任意 CSS 颜色串，如 `"#7c3aed"`、`"var(--color-primary)"`。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 卡片内容。 |

## 示例
```tsx
<CardSpotlight color="var(--color-primary)" radius={350} className="w-64">
  <div className="mb-3 text-3xl">⚡</div>
  <h3 className="mb-1.5 text-base font-semibold">主题色高光</h3>
  <p className="text-sm text-muted">color 传 var(--color-primary)，高光随主题联动。</p>
</CardSpotlight>
```

## 禁忌 / 坑

- `color` 若要随主题联动，传 CSS 变量时务必带 `--color-` 前缀（如 `var(--color-primary)`），裸 `var(--primary)` 在 Tailwind v4 `@theme` 下不解析。
- 高光是指针跟随的客户端效果，纯 SSR / 无指针（触屏）环境下不显示高光，属预期降级。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# ClickSpark

> 点击迸发火花的交互背景包裹器 · 点击点放射一圈短线段沿角度缓动飞散 + 数量/半径/长度/时长/缓动全可调（canvas2d+RAF 零依赖·token 取色·reduced-motion 静默·RSC 安全·jsdom 安全） · decoration/overlay-fx · #animated

## 何时用

需要在某区域内任意点击处迸发一圈放射火花（按钮区、卡片、互动 hero）时用——它是包裹器，包住的内容点击即放火花。要光标果冻拖尾用 [BlobCursor](https://hulianui.haloritual.com/components/blob-cursor)，要满屏粒子吸附用 [Antigravity](https://hulianui.haloritual.com/components/antigravity)，要准星十字线用 [Crosshair](https://hulianui.haloritual.com/components/crosshair)。

## 导入
```ts
import { ClickSpark } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| sparkColor | `string` | `var(--color-foreground)` | 火花颜色（自动吃明暗主题），可传任意 CSS 颜色 |
| sparkSize | `number` | `10` | 单条火花线段初始长度（px），越大越粗犷 |
| sparkRadius | `number` | `15` | 火花飞散最大半径（px），决定爆发范围 |
| sparkCount | `number` | `8` | 一次点击放射的火花数量（均分 360°） |
| duration | `number` | `400` | 单次火花动画时长（ms），越大越拖尾 |
| easing | `"linear" \| "ease-in" \| "ease-out" \| "ease-in-out"` | `"ease-out"` | 火花飞出缓动曲线 |
| extraScale | `number` | `1` | 半径额外缩放系数，>1 放大爆发、<1 收敛 |
| className | `string` | — | 透传到根容器（relative DOM 元素） |
| style | `CSSProperties` | — | 透传到根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 包裹内容，点击其内任意位置都在点击点迸发火花 |

## 示例
```tsx
// 默认：前景色火花，点击区域任意处放射
<div className="relative h-56 overflow-hidden rounded-xl">
  <ClickSpark className="absolute inset-0">
    <div className="flex h-full items-center justify-center">点击此处放射火花</div>
  </ClickSpark>
</div>

// 大爆发（多火花 + 长线段 + 大半径 + token 取色）
<ClickSpark sparkColor="var(--color-chart-1)" sparkCount={16} sparkSize={18} sparkRadius={36}>
  <Hint />
</ClickSpark>
```

## 禁忌 / 坑

- `sparkColor` 用 token 必须带 `--color-` 前缀（`var(--color-foreground)`），canvas strokeStyle 喂裸 `var(--foreground)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- 是包裹器：火花只在包住的 `children` 区域内点击触发；根容器须为定位上下文（relative）。
- reduced-motion 下静默不放火花；RSC/jsdom 环境安全（不报错），但实际火花需浏览器运行时。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# ColorBends

> 多色流场 WebGL 背景组件 · 正弦折叠噪声场按软阈值带宽采样叠加生成相互弯折的有机色带 + 指针视差/牵引/自动旋转(ogl·主题感知·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要多彩、相互弯折的有机色带流场背景时用（创意落地页、AI 产品 Hero、品牌彩条）。要单色光幕用 [Beams](https://hulianui.haloritual.com/components/beams)，要油彩旋涡用 [Balatro](https://hulianui.haloritual.com/components/balatro)，要规则点阵用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；ColorBends 主打多色融合与指针牵引交互，色彩最丰富、参数最多。

## 导入
```ts
import { ColorBends } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | chart token ×5 | 色带颜色数组（最多取前 8 个），可传任意 CSS 颜色字符串；不传吃明暗主题 |
| rotation | `number` | `90` | 静态基准旋转角度（度），决定流场整体朝向 |
| autoRotate | `number` | `0` | 自动旋转角速度（度/秒）；非 0 时随时间持续转动 |
| speed | `number` | `0.2` | 流动速度系数；0=冻结为静态纹理 |
| scale | `number` | `1` | 流场缩放；越小色带越密，越大越舒展 |
| frequency | `number` | `1` | 波纹频率；提升后正弦扰动更密集 |
| warpStrength | `number` | `1` | 扭曲强度，控制色带被波场拉扯变形幅度 |
| iterations | `number` | `1` | 折叠迭代次数（1–5）；越大结构越复杂 |
| intensity | `number` | `1.5` | 整体亮度增益，放大最终颜色 |
| bandWidth | `number` | `6` | 色带宽度软参；越大越窄越锐利 |
| noise | `number` | `0.15` | 颗粒噪声强度，打破塑料感；0=纯净 |
| parallax | `number` | `0.5` | 指针视差影响，营造景深 |
| mouseInfluence | `number` | `1` | 指针牵引强度；0=不响应指针 |
| transparent | `boolean` | `true` | 透明背景（仅渲染色带）；false 时填满黑底 |
| className | `string` | — | 透传到根容器（自带 absolute inset-0 z-0） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 降级时渲染在静态渐变兜底层内的内容 |

## 示例
```tsx
// 默认 chart token 多色流场
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <ColorBends />
</div>
```
```tsx
// 自定义暖色带 + 自动旋转壁纸级
<ColorBends
  colors={["oklch(0.72 0.22 30)", "oklch(0.78 0.18 60)", "oklch(0.68 0.2 350)"]}
  autoRotate={8}
  intensity={2.2}
  bandWidth={8}
  speed={0.15}
/>
```

## 禁忌 / 坑

- **WebGL 客户端渲染**：依赖 ogl + WebGL，SSR 阶段降级到 `fallback`；勿在 server component 直接挂载。
- **token 颜色须带 `--color-` 前缀**：`colors` 传 CSS 变量须写 `var(--color-chart-1)` 完整名，裸 `var(--chart-1)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- `colors` 最多取前 8 个，多传无效。
- 父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Crosshair

> 鼠标跟随的容器内准星十字线 · lerp 平滑拖尾 + 进入抖动脉冲 + token 配色(零依赖·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要在某区域内显示跟随鼠标的准星十字线（瞄准/取景/技术风互动区）时用。它是十字准星；要光标果冻拖尾用 [BlobCursor](https://hulianui.haloritual.com/components/blob-cursor)，要点击迸发火花用 [ClickSpark](https://hulianui.haloritual.com/components/click-spark)，要满屏粒子吸附背景用 [Antigravity](https://hulianui.haloritual.com/components/antigravity)。

## 导入
```ts
import { Crosshair } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-primary)` | 准星十字线颜色（自动吃明暗主题），推荐用 token |
| smoothing | `number` | `0.15` | 跟随平滑系数（0–1），越小越黏越拖尾，越大越跟手 |
| thickness | `number` | `1` | 十字线粗细（px） |
| pulseOnEnter | `boolean` | `true` | 进入容器时触发一次抖动脉冲（CSS scale）；reduced-motion 下失效，跟随仍保留 |
| className | `string` | — | 透传到根容器（须为定位上下文，组件内部 absolute inset-0 铺满父级） |
| style | `CSSProperties` | — | 透传到根容器内联样式 |

## 示例
```tsx
// 默认：primary 准星
<div className="relative h-56 overflow-hidden rounded-xl">
  <Crosshair />
</div>

// 高黏滞拖尾 + token 色
<Crosshair smoothing={0.06} color="var(--color-chart-3)" />
```

## 禁忌 / 坑

- 父容器须为定位上下文且有明确高度：组件内部以 `absolute inset-0` 铺满父级，无定位/无高度则准星不可见。
- `color` 用 token 推荐带 `--color-` 前缀（`var(--color-primary)`）以确保解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- reduced-motion 下进入脉冲失效，但鼠标跟随仍保留。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Cubes

> 3D 立方体阵列交互背景 · 指针靠近按距离衰减倾斜 + 空闲自动游走 + 点击环形涟漪高亮（零依赖去 gsap·token 配色·reduced-motion） · decoration/overlay-fx · #animated

## 何时用

需要一块有 3D 立体感、随鼠标倾斜响应的网格背景/装饰板时用，适合 hero 区、控制台空态、活动落地页的视觉点缀。它是规则网格阵列；如果想要更柔和的粒子/光斑类氛围背景，看其他 effects 背景件；要单元素悬停发光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。

## 导入
```ts
import { Cubes } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gridSize | `number` | `8` | 网格边长（行=列），生成 gridSize² 个立方体；DOM 为平方级，建议 ≤ 12 |
| cubeSize | `number` | — | 单个立方体边长（px）；传入时容器固定尺寸，不传则容器自适应（width 100%·1:1） |
| maxAngle | `number` | `45` | 指针处立方体最大倾斜角（度），越近越大越远越接近 0 |
| radius | `number` | `3` | 倾斜影响半径（以「格」为单位），范围内参与倾斜、之外回正 |
| cellGap | `number \| { row?: number \| string; col?: number \| string }` | `"5%"` | 单元间距，数字按 px，对象分别指定行列（百分比字符串随容器缩放） |
| faceColor | `string` | `var(--color-surface)` | 立方体面背景色，须带 `--color-` 前缀 |
| edgeColor | `string` | `var(--color-border)` | 立方体面边框色 |
| rippleColor | `string` | `var(--color-primary)` | 点击时从命中点向外扩散的涟漪高亮色 |
| rippleSpeed | `number` | `2` | 涟漪扩散速度倍率，越大越快 |
| autoAnimate | `boolean` | `true` | 空闲时是否自动游走倾斜（reduced-motion 下自动禁用保持静止） |
| rippleOnClick | `boolean` | `true` | 是否启用点击涟漪 |
| className | `string` | — | 透传根容器额外类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 默认 8×8，由父容器约束尺寸
<div className="h-56 w-56">
  <Cubes />
</div>

// 品牌色涟漪 + 加速（点击试试）
<Cubes
  gridSize={8}
  faceColor="var(--color-surface)"
  edgeColor="var(--color-primary)"
  rippleColor="var(--color-chart-2)"
  rippleSpeed={3}
/>
```

## 禁忌 / 坑

- 不传 `cubeSize` 时容器自适应宽高比 1:1，须由父级约束尺寸（如包一层固定宽高的 div），否则可能塌缩。
- 所有颜色 prop（faceColor/edgeColor/rippleColor）走 token 必须带 `--color-` 前缀。见 [[hulian-token-color-var-needs-color-prefix]]。
- DOM 数量是 `gridSize²`，`gridSize` 别开太大（建议 ≤ 12），否则节点数与重排成本飙升。
- reduced-motion 下 `autoAnimate` 自动失效、立方体静止。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# DarkVeil

> CPPN 神经场暗色流动帷幕 WebGL 背景 · 色相旋转/扫描线/颗粒/空间扭曲(ogl·懒加载·reduced-motion 降级静态渐变) · decoration/backdrop · #animated #webgl

## 何时用

需要深邃、克制的暗色流动帷幕背景时用（暗色落地页、控制台 Hero、沉浸式封面）。要多彩色带用 [ColorBends](https://hulianui.haloritual.com/components/color-bends)，要明亮光幕用 [Beams](https://hulianui.haloritual.com/components/beams)，要油彩旋涡用 [Balatro](https://hulianui.haloritual.com/components/balatro)；DarkVeil 是单一暗调神经场，主打深邃氛围而非鲜艳色彩，并自带扫描线/颗粒等复古显示器质感。

## 导入
```ts
import { DarkVeil } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| hueShift | `number` | `0` | 色相偏移（0–360 度），YIQ 色相旋转调出冷蓝/暖紫/青绿基调 |
| noiseIntensity | `number` | `0` | 颗粒噪声强度，CRT/胶片质感；建议 0–0.1，过大发雪花 |
| scanlineIntensity | `number` | `0` | 扫描线强度，复古显示器观感；建议 0–0.5，需配合频率 |
| speed | `number` | `0.5` | 动画速度因子；0=静止（仍渲染一帧静态画面） |
| scanlineFrequency | `number` | `0` | 扫描线频率（疏密）；需 scanlineIntensity > 0 才可见 |
| warpAmount | `number` | `0` | 空间扭曲量，UV 正余弦扰动产生波动/折射；建议 0–0.2 |
| resolutionScale | `number` | `1` | 渲染分辨率缩放；<1 降采样省电，>1 超采样换清晰度 |
| className | `string` | — | 透传到根容器（或 fallback div），自带 absolute inset-0 z-0 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认暗色径向渐变） |

## 示例
```tsx
// 默认冷调帷幕
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.12 0.02 280)" }}>
  <DarkVeil />
</div>
```
```tsx
// 复古显示器：扫描线 + 颗粒
<DarkVeil
  hueShift={200}
  scanlineIntensity={0.35}
  scanlineFrequency={1.6}
  noiseIntensity={0.04}
  speed={0.4}
/>
```

## 禁忌 / 坑

- **WebGL 客户端渲染 + 懒加载**：依赖 ogl + WebGL，SSR 阶段降级到 `fallback`（暗色径向渐变）；勿在 server component 直接挂载。
- **联动参数**：`scanlineFrequency` 须搭配 `scanlineIntensity > 0` 才可见；`noiseIntensity` 超 0.1 会发雪花。
- **性能旋钮**：低端设备或多实例叠加时调小 `resolutionScale`（如 0.6）降采样省电。
- 父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Dither

> 复古有序抖动波纹 WebGL 背景 · Perlin/fbm 波纹场 + 8×8 Bayer 抖动 + 色阶量化/像素马赛克(ogl 单遍 shader·token·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要 8-bit / 像素艺术复古质感的波纹背景时用（怀旧风落地页、游戏类产品、品牌彩蛋页）。要油彩旋涡用 [Balatro](https://hulianui.haloritual.com/components/balatro)，要光幕用 [Beams](https://hulianui.haloritual.com/components/beams)，要规则点阵用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；Dither 独有有序抖动（ordered dithering）+ 色阶量化的颗粒带状质感，是唯一主打复古像素观感的背景。

## 导入
```ts
import { Dither } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| waveSpeed | `number` | `0.05` | 波纹流动速度；reduced-motion 下冻结为静态画面 |
| waveFrequency | `number` | `3` | 波纹频率（fbm 倍频步长）；越大纹理越细碎 |
| waveAmplitude | `number` | `0.3` | 波纹振幅衰减因子（每 octave 衰减）；越大高频细节越强 |
| waveColor | `string` | `--color-chart-1` | 波纹主色，CSS 颜色字符串，默认取主题 token 明暗自适应 |
| colorNum | `number` | `4` | 量化色阶数，配合 Bayer 矩阵产生有序抖动；越小越 8-bit |
| pixelSize | `number` | `2` | 抖动像素块大小；越大马赛克越粗 |
| disableAnimation | `boolean` | `false` | 是否冻结波形为静帧（与 reduced-motion 等效，可显式控制） |
| className | `string` | — | 透传到 canvas（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认棋盘格+渐变） |

## 示例
```tsx
// 默认抖动波纹
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <Dither />
</div>
```
```tsx
// 粗马赛克像素艺术 + 自定义色 + 冻结静帧
<Dither
  waveColor="oklch(0.72 0.22 40)"
  pixelSize={6}
  colorNum={3}
  disableAnimation
/>
```

## 禁忌 / 坑

- **WebGL 客户端渲染**：依赖 ogl + 单遍 shader，SSR 阶段降级到 `fallback`（棋盘格+渐变）；勿在 server component 直接挂载。
- **token 颜色须带 `--color-` 前缀**：`waveColor` 传 CSS 变量须写 `var(--color-chart-1)` 完整名，裸 `var(--chart-1)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- `colorNum` 越小越「8-bit」颗粒感越强，但太小（如 2）会丢失细节层次。
- 父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# DotField

> 交互式点阵背景 · 光标推挤点阵鼓胀 + 移动泛起径向辉光，可选波浪起伏/星点闪烁（canvas2d 零依赖·token 配色·reduced-motion 静态降级） · decoration/backdrop · #animated #webgl

## 何时用

需要可交互、随光标鼓胀发光的点阵背景时用（科技产品 Hero、控制台底纹、空状态）。要纯静态 CSS 点阵底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)（轻量、不吃 GPU）；要光幕/旋涡用 [Beams](https://hulianui.haloritual.com/components/beams) / [Balatro](https://hulianui.haloritual.com/components/balatro)；DotField 是 canvas2d 实时交互场，强调光标涟漪与隆起，比 DotPattern 重但有交互。

## 导入
```ts
import { DotField } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| dotRadius | `number` | `1.5` | 单个点的绘制半径（px），建议 1–3 |
| dotSpacing | `number` | `14` | 相邻点间距（px），越大越稀疏，建议 8–24 |
| cursorRadius | `number` | `220` | 光标影响半径（px），鼠标周围多大范围内的点被推挤 |
| bulgeStrength | `number` | `56` | 鼓胀强度（px），点被推离原位的最大位移；0=仅随光标发光 |
| color | `string` | `--color-chart-1` | 点阵基色，CSS 颜色字符串；token 须带 `--color-` 前缀 |
| glowColor | `string` | `--color-primary` | 光标处径向辉光颜色 |
| glowRadius | `number` | `160` | 辉光半径（px）；0=关闭辉光 |
| waveAmplitude | `number` | `0` | 波浪振幅（px），全局正弦起伏的「呼吸」感；0=无波浪 |
| sparkle | `boolean` | `false` | 是否开启随机闪烁（少量点偶尔放大成星点） |
| className | `string` | — | 透传到根容器的额外 className |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## 示例
```tsx
// 默认点阵：移动鼠标推挤 + 辉光
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 280)" }}>
  <DotField />
</div>
```
```tsx
// 波浪起伏 + 星点闪烁 + 自定义配色
<DotField
  waveAmplitude={5}
  sparkle
  dotSpacing={16}
  color="oklch(0.75 0.2 50)"
  glowColor="oklch(0.7 0.18 200)"
/>
```

## 禁忌 / 坑

- **token 颜色须带 `--color-` 前缀**：喂给 canvas 的 `color`/`glowColor` 传 CSS 变量必须写完整名（如 `var(--color-chart-1)`），裸 `var(--chart-1)` canvas 不解析 → 点画成黑色/辉光消失。见 [[hulian-token-color-var-needs-color-prefix]]。
- **客户端渲染**：依赖 canvas2d + `requestAnimationFrame`，SSR/reduced-motion 下降级静态点阵；勿在 server component 直接挂载实时逻辑。
- 父容器须 `relative` + `overflow-hidden`（组件自带 absolute 铺满逻辑）。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# DotPattern

> 点阵背景 · 纯 SVG pattern + currentColor token + RSC · decoration/backdrop

## 何时用

给卡片/区块/Hero 加点阵纹理底。要点状纹理用本组件；要线网格用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)，斜条纹用 [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)，径向辉光用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。

## 导入
```ts
import { DotPattern } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number` | `16` | 平铺单元宽 |
| height | `number` | `16` | 平铺单元高 |
| cx | `number` | `1` | 点在单元内的 x 偏移 |
| cy | `number` | `1` | 点在单元内的 y 偏移 |
| cr | `number` | `1` | 点半径 |
| x | `number` | `0` | pattern 整体 x 偏移 |
| y | `number` | `0` | pattern 整体 y 偏移 |

> 继承 `ComponentPropsWithoutRef<"svg">`（`className` 等）。颜色取 `currentColor`，用 `text-*` 工具类控制（如 `text-muted`）。

## 示例
```tsx
<div className="relative h-48 overflow-hidden rounded-xl border">
  <DotPattern />
</div>

<DotPattern width={28} height={28} cr={1.4} className="text-muted" />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，必须放在 `relative`（且通常 `overflow-hidden`）定位容器内，否则无法定位/会溢出。
- 颜色靠 `currentColor`，用 `text-*` 改色而非 `fill`。

## 相关
[GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# ElectricBorder

> 通电跳动的边框装饰 · SVG 湍流位移描边 + 多层模糊光晕模拟放电辉光(零依赖·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

给一块内容（按钮、卡片、CTA）包一圈持续放电跳动的电弧描边，营造科技/赛博氛围。要静态柔光描边用 [ShineBorder](https://hulianui.haloritual.com/components/shine-border)，要单点环绕流光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；本组件是「整条边都在抖动放电」的强动效，最吸睛但也最重。

## 导入
```ts
import { ElectricBorder } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-primary)` | 电流描边颜色，吃明暗主题。任意 CSS 颜色串均可；喂 SVG stroke 的 CSS 变量须带 `--color-` 前缀才解析 |
| speed | `number` | `1` | 电流抖动速度倍率，越大跳动越快（speed=1 ≈ 2s 一轮 `<animate>`） |
| chaos | `number` | `1` | 紊乱程度（湍流位移强度），越大描边被撕扯越剧烈，映射 `feDisplacementMap` 的 scale |
| thickness | `number` | `2` | 边框外发光柔边的厚度（px） |
| borderRadius | `number` | `16` | 圆角半径（px），同时应用到容器与电流描边 |
| className | `string` | — | 透传根容器额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 被电流边框包裹的内容 |

## 示例
```tsx
<ElectricBorder borderRadius={16}>
  <div className="px-8 py-6 text-sm font-medium text-white/85">
    Electric Border
  </div>
</ElectricBorder>
```

暖色圆形按钮（高自定义）：
```tsx
<ElectricBorder color="var(--color-chart-3)" borderRadius={999} thickness={2}>
  <button type="button" className="px-6 py-3 text-sm font-semibold text-white">
    立即体验
  </button>
</ElectricBorder>
```

## 禁忌 / 坑

- 自定义 `color` 用 CSS 变量时务必带 `--color-` 前缀（如 `var(--color-chart-3)`），裸 `var(--primary)` 喂给 SVG stroke 不解析、描边会变黑或消失，见 [[hulian-token-color-var-needs-color-prefix]]。
- 描边电弧需要深色底才显眼，浅色背景上辉光几乎不可见。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# EvilEye

> 火焰邪眼 WebGL 背景 · 极坐标多层程序化噪声画出翻腾火焰瞳孔 + 瞳孔惯性跟随光标 + 外圈弥散辉光（ogl·token 自适应·reduced-motion 静态降级） · decoration/backdrop · #animated #webgl

## 何时用

需要一个有"注视感"、能跟随鼠标的高戏剧化主视觉背景（hero / 404 / 启动页）时用。要纯平铺的几何底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要鼠标聚光跟随但不要"眼睛"具象图形用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；要水波涟漪点缀用 [Ripple](https://hulianui.haloritual.com/components/ripple)。

## 导入
```ts
import { EvilEye } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| eyeColor | `string` | `--color-chart-3` | 主火焰色，任意 CSS 颜色（hex/oklch/rgb/`var(--…)`）。不传吃主题 token，随明暗换色 |
| backgroundColor | `string` | 透明（回退黑） | 背景底色，一般留默认由容器深底衬托 |
| intensity | `number` | `1.5` | 发光强度倍率，越大越亮，建议 0.8–2.5 |
| pupilSize | `number` | `0.6` | 瞳孔大小，越大越饱满、越小越收成缝，建议 0.2–1.0 |
| irisWidth | `number` | `0.25` | 虹膜（内环火焰）宽度，建议 0.1–0.4 |
| glowIntensity | `number` | `0.35` | 外圈辉光浓度，建议 0.1–0.6 |
| scale | `number` | `0.8` | 眼睛缩放，越大占画面越多，建议 0.5–1.2 |
| noiseScale | `number` | `1.0` | 火焰噪声纹理缩放，越大纹路越细碎，建议 0.5–2.0 |
| pupilFollow | `number` | `1.0` | 瞳孔跟随光标幅度，0=不动；带惯性 lerp，松手缓缓回正 |
| flameSpeed | `number` | `1.0` | 火焰流动速度，建议 0.3–2.0 |
| className | `string` | — | 透传根容器，组件默认 `block h-full w-full`，尺寸由容器决定 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 降级时叠在静态兜底层里的内容 |

## 示例
```tsx
// 默认：吃主题 chart-3 暖橙，瞳孔跟随光标
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.01 60)" }}>
  <EvilEye className="absolute inset-0" />
</div>
```
```tsx
// 壁纸级：瞳孔不跟随 + 慢火
<EvilEye className="absolute inset-0" pupilFollow={0} flameSpeed={0.5} noiseScale={1.3} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR 阶段只出静态 fallback 兜底层，首屏视觉以 fallback 为准。
- 根需放进 `relative` + `overflow-hidden` 的定位容器，并自带高度（如 `h-64`），否则铺不满或溢出。
- 深色背景才看得清火焰，浅底上请显式传 `backgroundColor` 或在容器上铺深底。
- `pupilFollow` 跟随依赖指针事件，移动端/无指针环境等同 0。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# FaultyTerminal

> 出故障的 CRT 终端字符雨 WebGL 背景 · fbm 噪声点阵 + 横向撕裂/扫描线/闪烁/桶形畸变/色散 + 鼠标涟漪(ogl·token 着色·reduced-motion 兜底) · decoration/backdrop · #animated #webgl

## 何时用

需要赛博朋克 / 黑客终端 / 复古 CRT 故障风的高动效背景（hero、加载页、404）时用。要静态规整的格纹底用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要复古透视网格地平线用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)；要纯条纹用 [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)。本组件动效最重、最具"信号失真"叙事。

## 导入
```ts
import { FaultyTerminal } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| scale | `number` | `1.5` | 整体 UV 缩放，越大字符网格越密、视野越远 |
| gridMul | `[number, number]` | `[2, 1]` | 字符网格行列倍率 [x, y]，横向更密仿宽屏终端 |
| digitSize | `number` | `1.5` | 单个字符内点阵大小，越大每个"数字"块越胖 |
| timeScale | `number` | `0.3` | 时间流速因子，越大故障/闪烁越快 |
| pause | `boolean` | `false` | 冻结动画定格；reduced-motion 下强制冻结，与本 prop 取或 |
| scanlineIntensity | `number` | `0.3` | 扫描线强度，0=无 |
| glitchAmount | `number` | `1` | 横向撕裂量，>1 更夸张，1=原始位移 |
| flickerAmount | `number` | `1` | 整屏忽明忽暗闪烁量，0=无 |
| noiseAmp | `number` | `0` | 背景有机噪声振幅，增大叠加流动雾噪 |
| chromaticAberration | `number` | `0` | 色散（RGB 分离）像素量，建议 0–6 |
| dither | `number \| boolean` | `0` | 抖动颗粒强度，boolean 时 true=1/false=0 |
| curvature | `number` | `0.2` | 桶形畸变（CRT 球面弯曲），0=平面 |
| tint | `string` | `--color-chart-2` | 字符着色，任意 CSS 颜色，不传吃主题 token |
| mouseReact | `boolean` | `true` | 是否响应鼠标（字符发亮 + 涟漪） |
| mouseStrength | `number` | `0.2` | 鼠标影响强度，仅 mouseReact=true 生效 |
| pageLoadAnimation | `boolean` | `true` | 加载时逐格淡入动画 |
| brightness | `number` | `1` | 整体亮度倍率 |
| className | `string` | — | 透传根容器（或兜底层） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容 |

## 示例
```tsx
// 默认：绿色字符雨
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.12 0.01 255)" }}>
  <FaultyTerminal />
</div>
```
```tsx
// 老 CRT：暖橙 + 强桶形畸变 + 色散
<FaultyTerminal tint="oklch(0.72 0.2 45)" curvature={0.45} scanlineIntensity={0.5} chromaticAberration={3} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR 只出 fallback 静态兜底。
- `pause` 不是唯一冻结开关——reduced-motion 偏好会强制冻结（取或），调试动画时注意系统设置。
- 根需放进 `relative overflow-hidden` 定位容器并自带高度（如 `h-56`）。
- `chromaticAberration` / `glitchAmount` 调高很费 GPU，长驻背景慎用大值。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Ferrofluid

> 液态金属铁磁流体 WebGL 背景组件 · value-noise 峰脊 + smin 软融合 + rim 亮带流动 + 鼠标下凹交互(ogl·主题 chart token·reduced-motion 径向渐变兜底) · decoration/backdrop · #animated #webgl

## 何时用

需要高级感的液态金属 / 流体辉光背景（品牌 hero、产品页）时用。要更偏星河深空用 [Galaxy](https://hulianui.haloritual.com/components/galaxy)；要纯几何底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要鼠标聚光不要流体峰脊用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。本组件主打"金属液面流动 + 鼠标下凹"质感。

## 导入
```ts
import { Ferrofluid } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `--color-chart-1/2/4` | 流体色带，最多 8 色，按高度梯度低→高映射；任意 CSS 颜色 |
| speed | `number` | `0.5` | 动画速度因子，越大流动越快 |
| scale | `number` | `1.6` | 噪声/纹理缩放，越大越细密；< 0.05 钳到下限 |
| turbulence | `number` | `1` | 湍流强度，0=近乎静止平滑液面 |
| fluidity | `number` | `0.1` | 峰脊融合柔度，越大越像液体，下限 0.001 |
| rimWidth | `number` | `0.2` | 高光边缘宽度 |
| sharpness | `number` | `2.5` | 高光锐度 gamma，越大亮带越收束 |
| shimmer | `number` | `1.5` | 微光扰动强度，制造金属闪烁 |
| glow | `number` | `2` | 整体辉光增益，越大越发光 |
| flowDirection | `"up" \| "down" \| "left" \| "right"` | `"down"` | 峰脊整体漂移方向 |
| opacity | `number` | `1` | 整体不透明度，范围 0–1 |
| mouseInteraction | `boolean` | `true` | 指针处液面下凹/抑制亮带；无 WebGL 环境自动无效 |
| mouseStrength | `number` | `1` | 鼠标影响强度，仅 mouseInteraction=true 生效 |
| mouseRadius | `number` | `0.35` | 鼠标影响半径（归一化） |
| mouseDampening | `number` | `0.15` | 鼠标跟随阻尼（秒），0=立即跟随 |
| dpr | `number` | `min(dpr, 2)` | 设备像素比上限，调低省 GPU |
| className | `string` | — | 透传根容器（或兜底 div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认径向渐变 div） |

## 示例
```tsx
// 默认：吃主题 chart token 三色
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 265)" }}>
  <Ferrofluid />
</div>
```
```tsx
// 壁纸级：慢速大尺度，关鼠标交互
<Ferrofluid speed={0.25} scale={2.4} glow={2.4} mouseInteraction={false} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出径向渐变 fallback。
- 根需放进 `relative overflow-hidden` 定位容器并自带高度。
- 深色底才衬得出金属流体，浅底上层次会糊。
- 高分屏可显式传 `dpr={1}` 省 GPU；`turbulence` / `shimmer` 调高会增加片元开销。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# FlickeringGrid

> 闪烁网格 · canvas 像素方格随机明灭 + ResizeObserver 自适应 + 颜色吃主题 token(逐帧现取) · decoration/backdrop · #animated

## 何时用

需要科技感/数据感的像素方格背景，且方格随机明灭闪烁时用。基于 canvas，自带 ResizeObserver 跟随容器尺寸；若要静态规则网格（不闪烁、更轻），用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；若要点阵用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；若要复古透视网格用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)。

## 导入
```ts
import { FlickeringGrid } from "@hulianui/ui"
```

## Props

继承 `HTMLAttributes<HTMLDivElement>`，额外：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| squareSize | number | 4 | 每个方格边长（px），越小越密 |
| gridGap | number | 6 | 方格间距（px） |
| flickerChance | number | 0.3 | 每帧每格闪烁概率（乘 deltaTime）。0=静态网格，1=高频闪烁 |
| maxOpacity | number | 0.3 | 方格最大不透明度（0~1），越高越明显 |
| color | string | `--color-foreground` | 方格颜色，任意 CSS 颜色字符串。不传则从容器 `color`/token 解析 RGB 随主题切换 |
| width | number | — | 固定宽度（px）。不传用 ResizeObserver 跟随容器宽 |
| height | number | — | 固定高度（px）。不传用 ResizeObserver 跟随容器高 |

## 示例
```tsx
// 主题前景色默认网格，铺满定位父容器
<div className="relative h-48 overflow-hidden rounded-xl border">
  <FlickeringGrid className="absolute inset-0" />
</div>
```
```tsx
// 强调色 + 大方格 + 低频闪烁
<FlickeringGrid
  className="absolute inset-0"
  color="var(--color-primary)"
  squareSize={8}
  gridGap={4}
  flickerChance={0.1}
  maxOpacity={0.4}
/>
```

## 禁忌 / 坑

- 基于 canvas，须客户端渲染；父容器需 `relative` + `overflow-hidden`，组件自身用 `absolute inset-0` 铺满。
- 不传 `width`/`height` 时靠 ResizeObserver 跟随容器，故容器必须有确定尺寸（高度别塌成 0）。
- `color` 可传 `var(--color-*)`，组件会逐帧 getComputedStyle 解析（与只吃 rgb 的 Particles 不同），但每帧解析有微小成本。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# FloatingLines

> 漂浮线束 WebGL 背景 · 三组正弦波线束随时间漂浮 + log 半径扭曲旋转 + 渐变色带插值 + 可选指针径向弯曲(ogl 零新依赖·token 吃 chart·reduced-motion 降级静态渐变) · decoration/backdrop · #animated #webgl

## 何时用

需要轻盈、低干扰、能放文字在上面的线条流动背景（hero、登录页、营销区块）时用。要点阵/网格几何底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要液态金属峰脊用 [Ferrofluid](https://hulianui.haloritual.com/components/ferrofluid)；要鼠标聚光用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。本组件线束细、对前景文字可读性友好。

## 导入
```ts
import { FloatingLines } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `--color-chart-1/2/4` | 线条渐变色带，沿线序首→尾插值，最多取前 5 段；任意 CSS 颜色 |
| lineCount | `number` | `6` | 三组波各自的线条数量，越多越密、开销越大，建议 3–12 |
| lineDistance | `number` | `5` | 相邻线条横向相位间距（疏密层叠感） |
| animationSpeed | `number` | `1` | 动画速度倍率，0=静止 |
| interactive | `boolean` | `true` | 指针靠近时线条径向弯曲牵引；reduced-motion / 无 WebGL 自动失效 |
| bendRadius | `number` | `5` | 指针弯曲影响半径系数，越大范围越小越聚焦 |
| bendStrength | `number` | `-0.5` | 指针弯曲强度（带符号，负值反向牵引） |
| className | `string` | — | 透传根容器，根自带 `absolute inset-0 z-0` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 静态兜底层内的内容（如水印文案） |

## 示例
```tsx
// 默认：吃主题 chart token 渐变线束
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <FloatingLines />
  <div className="relative z-10 flex h-full items-center justify-center text-white/80">
    瑚琏组件库
  </div>
</div>
```
```tsx
// 密集慢速壁纸 + 关交互
<FloatingLines lineCount={10} animationSpeed={0.6} lineDistance={4} interactive={false} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出 fallback。
- 根自带 `absolute inset-0 z-0`，需放进 `relative` 容器；前景内容要 `relative z-10` 才压在线束之上。
- `lineCount` 是每组数量（共三组），实际线数约 3 倍，调高注意性能。
- `bendStrength` 默认负值是有意的反向牵引，改正值方向会反。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# FluidGlass

> 跟随指针的流体玻璃折射背景 · 程序化流动渐变底图 + 圆形玻璃透镜实时折射/放大/边缘色散/菲涅尔高光(ogl 单 shader·零 3D 依赖·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要一整块「流体玻璃」背景——程序化流动渐变底图 + 一个跟随指针的圆形玻璃透镜实时折射放大底图时用，适合 hero/区块背景。要做固定尺寸的玻璃面板（药丸/卡片）用 [GlassSurface](https://hulianui.haloritual.com/components/glass-surface)；要做局部静态放大镜用 [Lens](https://hulianui.haloritual.com/components/lens)。FluidGlass 是「会流动的整屏玻璃背景」，靠 ogl WebGL shader 渲染。

## 导入
```ts
import { FluidGlass } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| size | `number` | `0.26` | 透镜半径占容器短边比例 0–1，越大折射区越广，建议 0.15–0.4 |
| refraction | `number` | `0.5` | 折射强度（IOR 映射），越大中心放大/扭曲越强，0=几乎透明，建议 0–1 |
| dispersion | `number` | `0.3` | 色散强度，模拟边缘 RGB 分光彩边，0=关闭，建议 0–1 |
| speed | `number` | `1` | 背景流动速度倍率，0=背景静止（透镜仍跟随指针） |
| colors | `string[]` | chart-1/2/4 | 背景渐变色组，取前 3 个，可传任意 CSS 颜色 |
| followPointer | `boolean` | `true` | 透镜跟随指针；关闭时停在中心缓慢漂移 |
| className | `string` | — | 透传根容器 className（根为 `relative overflow-hidden`，canvas 自带 `absolute inset-0`） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在玻璃背景上方的内容（relative z-10 层叠于画布之上） |

## 示例

```tsx
// 默认：移动指针看透镜跟随
<div className="relative h-64 overflow-hidden rounded-xl">
  <FluidGlass className="absolute inset-0">
    <div className="flex h-full items-center justify-center text-lg font-semibold text-white">
      Fluid Glass
    </div>
  </FluidGlass>
</div>

// 强折射强色散厚玻璃
<FluidGlass size={0.32} refraction={0.85} dispersion={0.7} className="absolute inset-0" />
```

## 禁忌 / 坑

- WebGL 组件（ogl 单 shader），必须客户端渲染，SSR 出空壳；放进固定高度的 `relative overflow-hidden` 容器并给 `className="absolute inset-0"`。
- `colors` 喂 token 须带 `--color-` 前缀；shader 取色经组件解析，裸 `var(--primary)` 不解析。
- WebGL 背景在 headless 截图中常因 shader/context 未就绪而空白，验视觉用真实浏览器或留意 [[webgl-canvas-loseContext-poisons-strictmode-remount]]（cleanup 调 loseContext 会毒化 StrictMode 重挂载的 canvas，本组件如复用 canvas 需警惕）。
- reduced-motion 下停止背景流动动画（透镜折射仍在）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Galaxy

> 程序化生成的多层视差星河 WebGL 背景 · Hash 铺点+十字辉光+HSV 调色+三角波闪烁+自转/鼠标斥力，4 层尺度叠加深空纵深(ogl·懒加载·StrictMode 安全·reduced-motion 降级 chart token 径向渐变) · decoration/backdrop · #animated #webgl

## 何时用

需要深空 / 繁星 / 科技感纵深背景（hero、启动页、数据大屏）时用。要液态金属流体用 [Ferrofluid](https://hulianui.haloritual.com/components/ferrofluid)；要纯点阵底纹（非闪烁星星）用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；要鼠标聚光不要星河用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。本组件主打多层视差 + 星点闪烁 + 鼠标斥力的"宇宙"质感。

## 导入
```ts
import { Galaxy } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| focal | `[number, number]` | `[0.5, 0.5]` | 星空聚焦点（归一化），星河发散中心 |
| rotation | `[number, number]` | `[1, 0]` | 取景旋转（cos/sin 向量），`[0.707,0.707]`≈45° |
| starSpeed | `number` | `0.5` | 星点漂移速度因子 |
| density | `number` | `1` | 星点密度，0.5 稀疏、2 繁星 |
| hueShift | `number` | `140` | 色相偏移（0–360），默认偏青蓝 |
| speed | `number` | `1` | 总动画速度倍率（漂移+闪烁） |
| mouseInteraction | `boolean` | `true` | 鼠标移动时星河偏移 / 斥力 |
| glowIntensity | `number` | `0.3` | 星点辉光强度 |
| saturation | `number` | `0` | 饱和度，0=接近白星；调高配 hueShift 出彩色 |
| mouseRepulsion | `boolean` | `true` | true=星点被推开，false=星河整体平移；仅交互开时生效 |
| repulsionStrength | `number` | `2` | 鼠标斥力强度，仅 mouseRepulsion=true 生效 |
| twinkleIntensity | `number` | `0.3` | 星点闪烁强度，0=不闪 |
| rotationSpeed | `number` | `0.1` | 星河自动旋转速度，0=不自转 |
| autoCenterRepulsion | `number` | `0` | 中心自动斥力，>0 形成空洞中心"星环" |
| transparent | `boolean` | `true` | true=alpha 随亮度过渡可叠底色；false=纯黑底深空 |
| className | `string` | — | 透传根容器（或兜底 div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认径向渐变 div） |

## 示例
```tsx
// 默认：青蓝星河，鼠标斥力交互
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.12 0.02 265)" }}>
  <Galaxy />
</div>
```
```tsx
// 中心星环 + 暖紫调
<Galaxy autoCenterRepulsion={2} density={1.2} hueShift={200} mouseInteraction={false} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染（懒加载、StrictMode 安全）：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出径向渐变 fallback。
- 根需放进 `relative overflow-hidden` 定位容器并自带高度（如 `h-64`）。
- `transparent={true}` 时本身无黑底，需容器铺深色才出深空感；要经典纯黑深空传 `transparent={false}`。
- `mouseRepulsion` / `repulsionStrength` 仅在 `mouseInteraction=true` 时有效。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# GhostCursor

> 跟随指针的幽灵烟雾拖尾 · fbm 噪声烟团 + 环形帧缓冲历史尾迹 + 惯性滑行渐隐（ogl WebGL·去 three.js·reduced-motion 降级） · decoration/overlay-fx · #animated

## 何时用

作为覆盖整块区域的 WebGL 烟雾拖尾层，让指针在 hero/卡片/落地页上拖出发光烟团。要甩出具体图片做拖尾用 [ImageTrail](https://hulianui.haloritual.com/components/image-trail)；本组件是抽象烟雾光效，更适合纯氛围装饰。它是 `absolute inset-0` 覆盖层，父容器须 `relative` + 深色底才出效果。

## 导入
```ts
import { GhostCursor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| trailLength | `number` | `32` | 拖尾保留的历史帧数，越大尾迹越长，片元开销线性增长，建议 16–64 |
| inertia | `number` | `0.5` | 惯性系数 0–1，越接近 1 越「飘」（拖远），越接近 0 越跟手 |
| grainIntensity | `number` | `0.05` | 胶片颗粒强度 0–0.3，叠加噪点；0 = 关闭 |
| brightness | `number` | `1.2` | 整体亮度增益，补偿去掉 Bloom 后的亮度损失，建议 0.8–2.0 |
| color | `string` | `var(--color-chart-1)` | 烟雾主色，吃明暗主题；任意 CSS 颜色串均可 |
| scale | `number` | `1` | 噪声活动半径系数 >0，越大烟团越弥散，越小越聚拢 |
| mixBlendMode | `CSSProperties["mixBlendMode"]` | `"screen"` | canvas 混合模式，深色底用 screen 叠加发光；浅色底可改 multiply/normal |
| className | `string` | — | 透传根容器（absolute inset-0）额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式（如 zIndex） |

## 示例
```tsx
<div
  className="relative h-64 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.14 0.02 285)" }}
>
  <GhostCursor />
</div>
```

暖橙长拖尾（高惯性）：
```tsx
<GhostCursor color="oklch(0.72 0.2 50)" trailLength={48} inertia={0.78} />
```

## 禁忌 / 坑

- WebGL（ogl）组件，React StrictMode 双挂载下若 cleanup 调 `loseContext` 会永久毒化 canvas 复用导致空白崩溃，本组件内部应每次挂载新建 canvas 规避，见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 父容器必须 `relative` + `overflow-hidden` + 深色底（默认 screen 混合模式在浅色底几乎不可见）。
- SSR 下 WebGL 仅客户端可用，组件已带 reduced-motion 降级。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# GlareHover

> 反光悬停 · hover 斜向扫光 + reduced-motion + RSC · decoration/overlay-fx · #animated

## 何时用

想让卡片/按钮/图块在 hover 时被一道斜向玻璃反光扫过（精致感、可交互暗示）时用。它是包裹容器，把要反光的内容作为 `children` 传入，并接受所有原生 `div` 属性。要边框上持续绕行的光点用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；要整条边框流光用 [ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要悬停放大内容用 [Lens](https://hulianui.haloritual.com/components/lens)。

## 导入
```ts
import { GlareHover } from "@hulianui/ui"
```

## Props

继承全部原生 `div` 属性（`ComponentPropsWithoutRef<"div">`），另有：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| glareColor | `string` | 半透明白 | 反光色，默认玻璃光泽（明暗皆宜） |
| duration | `string` | `"650ms"` | 扫光时长（showcase 可选 `"450ms"` / `"650ms"` / `"1000ms"`） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 被反光扫过的内容 |

## 示例

```tsx
<GlareHover className="grid h-40 w-72 place-items-center rounded-xl border bg-surface">
  <span className="text-lg font-semibold">悬停看反光</span>
</GlareHover>
```

```tsx
<GlareHover duration="1000ms" className="rounded-xl p-6">
  <Card>...</Card>
</GlareHover>
```

## 禁忌 / 坑

- reduced-motion 偏好下扫光被弱化/停用，不要把关键信息只放在反光动画里。
- 它是包裹件而非覆盖件——直接给它布局/样式 className，无需额外 `relative` 容器。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# GlassIcons

> 玻璃拟态图标按钮网格 · 背面 3D 旋转彩色发光板 + 前面磨砂玻璃片（backdrop-blur·inset 高光边），hover/focus 彩板抬升旋转、玻璃前推、标签滑出（纯 CSS 零依赖·token 配色·RSC 安全·reduced-motion） · decoration/overlay-fx · #animated

## 何时用

需要一组玻璃拟态、带 3D 抬升发光交互的图标按钮网格（如功能入口/分类导航/快捷操作）时用。要给单个元素加边框光带用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)/[ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要做眩光悬停用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。GlassIcons 是「一组带标签的可点图标」，自带无障碍名。

## 导入
```ts
import { GlassIcons } from "@hulianui/ui"
```

## Props

### GlassIconsProps

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items* | `GlassIconItem[]` | — | 图标项列表，按网格依次渲染为玻璃按钮 |
| columns | `number` | `3` | 网格列数，窄屏自动回落到更少列 |
| className | `string` | — | 透传根网格容器 className（可覆盖列数/间距/对齐） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

### GlassIconItem · Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| label* | `string` | — | hover/focus 滑出的文字，同时作按钮 `aria-label` |
| color | `string` | `"primary"` | 背面发光配色，预设名 `primary｜blue｜purple｜red｜indigo｜orange｜green`，或任意 CSS 颜色/渐变 |
| className | `string` | — | 透传该按钮 className |

### GlassIconItem · Events

| 事件 | 类型 | 说明 |
|------|------|------|
| onClick | `() => void` | 点击该图标按钮时回调 |

### GlassIconItem · Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon* | `ReactNode` | 图标节点（通常 lucide-react），渲染于玻璃前层中央，`aria-hidden` |

## 示例

```tsx
import { Heart, Star, Bell } from "lucide-react";

<GlassIcons
  columns={3}
  items={[
    { icon: <Heart />, label: "收藏", color: "red" },
    { icon: <Star />, label: "星标", color: "orange" },
    { icon: <Bell />, label: "通知", color: "blue" },
  ]}
/>

// 自定义渐变色
<GlassIcons
  columns={2}
  items={[
    { icon: <Cloud />, label: "极光", color: "linear-gradient(135deg, var(--color-chart-1), var(--color-chart-4))" },
  ]}
/>
```

## 禁忌 / 坑

- `label` 既是滑出文字也是 `aria-label`，必填，不要为视觉留空——否则按钮失去无障碍名。
- 玻璃发光在深色背景上才清晰，浅底下效果弱；`color` 喂 token/渐变时务必带 `--color-` 前缀。
- 容器需 `overflow-visible`，否则 3D 抬升与标签滑出会被裁切。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# GlassSurface

> 液态玻璃折射面 · SVG feDisplacementMap 三通道色散 + RGB 色差边缘(零依赖·token 磨砂底/发丝边/焦点环·RSC client·非 SVG 浏览器回落 backdrop-blur·reduced-motion 关过渡) · decoration/overlay-fx · #animated

## 何时用

需要一块真实「液态玻璃」折射面板（药丸/卡片/按钮底），透过它看到背景被位移扭曲并产生 RGB 色散时用。要做跟随指针的整屏流体玻璃背景用 [FluidGlass](https://hulianui.haloritual.com/components/fluid-glass)；要做局部放大镜用 [Lens](https://hulianui.haloritual.com/components/lens)。GlassSurface 是「固定尺寸的折射面板」，靠 SVG 位移图实现，需要丰富背景才看得出效果。

## 导入
```ts
import { GlassSurface } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number ｜ string` | `200` | 宽度，number 视作 px，string 原样透传 |
| height | `number ｜ string` | `80` | 高度，number 视作 px，string 原样透传 |
| borderRadius | `number` | `20` | 圆角半径 px，同时作用于容器与位移图内部矩形 |
| borderWidth | `number` | `0.07` | 边缘高光带宽度系数 0~1（相对短边），越大折射越宽 |
| brightness | `number` | `50` | 位移图内部矩形亮度（HSL 的 L，0~100），控制玻璃厚度质感 |
| opacity | `number` | `0.93` | 位移图内部矩形不透明度 0~1 |
| blur | `number` | `11` | 位移图内部矩形高斯模糊半径 px，柔化折射边界 |
| displace | `number` | `0` | 折射结果二次高斯模糊，消像素锯齿 |
| backgroundOpacity | `number` | `0` | 磨砂底色不透明度，0=全透明 |
| saturation | `number` | `1` | backdrop-filter 饱和度倍率 |
| distortionScale | `number` | `-180` | 位移强度，负值内凹、正值外凸，三通道叠加制造色散 |
| redOffset | `number` | `0` | 红通道相对 distortionScale 的额外位移（色差） |
| greenOffset | `number` | `10` | 绿通道额外位移（色差） |
| blueOffset | `number` | `20` | 蓝通道额外位移（色差） |
| xChannel | `GlassChannel` | `"R"` | X 方向偏移取用通道（`"R"｜"G"｜"B"｜"A"`） |
| yChannel | `GlassChannel` | `"G"` | Y 方向偏移取用通道 |
| mixBlendMode | `CSSProperties["mixBlendMode"]` | `"difference"` | 位移图内红/蓝渐变叠加混合模式（决定折射纹理形态） |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 玻璃面内容（居中于折射层之上） |

## 示例

```tsx
// 默认液态玻璃药丸（外层需有丰富背景才看得出折射）
<GlassSurface width={220} height={90} borderRadius={24}>
  <span className="text-sm font-semibold text-foreground">Glass Surface</span>
</GlassSurface>

// 强色散厚玻璃
<GlassSurface
  width={240}
  height={100}
  borderRadius={28}
  distortionScale={-220}
  greenOffset={25}
  blueOffset={45}
>
  <span className="text-sm font-semibold text-foreground">瑚琏</span>
</GlassSurface>
```

## 禁忌 / 坑

- 折射靠 SVG feDisplacementMap 位移背景像素，纯色/空白背景下几乎看不出效果，必须放在有渐变/纹理/图片的背景上。
- 不支持 SVG 滤镜的浏览器会回落到 backdrop-blur（无色散）；这是组件内置降级，不是 bug。
- 客户端组件（依赖运行时 SVG 滤镜与指针），SSR 下仅出静态壳，交互态须在浏览器验证。
- reduced-motion 下关闭过渡动画（折射本身仍在）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# GradientBlinds

> 渐变百叶窗 WebGL 背景 · 多色站水平渐变 + 竖条百叶明暗调制 + 跟随鼠标聚光灯 + 颗粒噪声(可旋转/镜像/扭曲) · 默认吃 chart token(ogl·reduced-motion 静态百叶降级) · decoration/backdrop · #animated #webgl

## 何时用

需要带竖条百叶质感 + 鼠标聚光灯的彩色渐变背景（hero、营销区块、卡片底）时用。要纯条纹无渐变聚光用 [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)；要纯鼠标聚光不要百叶用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；要液态流体用 [Ferrofluid](https://hulianui.haloritual.com/components/ferrofluid)。本组件融合渐变 + 百叶 + 聚光三者。

## 导入
```ts
import { GradientBlinds } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gradientColors | `string[]` | `--color-chart-1/3` | 渐变色站，水平插值，最多取前 8；任意 CSS 颜色 |
| angle | `number` | `0` | 色带旋转角度（度），仅转渐变与百叶纹理不转容器 |
| noise | `number` | `0.3` | 颗粒噪声强度，0=纯净，建议 0–1 |
| blindCount | `number` | `16` | 百叶竖条数量，与 blindMinWidth 取较小者 |
| blindMinWidth | `number` | `60` | 单条最小宽度(px)，窄容器按此收敛条数；传 0/负值关闭约束 |
| mouseDampening | `number` | `0.15` | 聚光灯跟随阻尼(秒)，0=瞬时无阻尼 |
| mirrorGradient | `boolean` | `false` | 色带中点对折形成对称往返 |
| spotlightRadius | `number` | `0.5` | 聚光灯半径（归一化），最小钳 1e-4 |
| spotlightSoftness | `number` | `1` | 聚光灯衰减指数，越大边缘越锐 |
| spotlightOpacity | `number` | `1` | 聚光灯强度，0=无聚光灯 |
| distortAmount | `number` | `0` | 渐变扭曲幅度，越大色带越波浪 |
| shineDirection | `"left" \| "right"` | `"left"` | 高光扫光方向，"right" 翻转每条百叶明暗倾向 |
| dpr | `number` | `min(dpr, 2)` | 设备像素比上限 |
| className | `string` | — | 透传根容器 div |
| style | `CSSProperties` | — | 根容器内联样式，如 `mixBlendMode` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认静态百叶 div） |

## 示例
```tsx
// 默认：chart token 双色 + 鼠标聚光灯
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <GradientBlinds />
</div>
```
```tsx
// 斜向多色站 + 高条数
<GradientBlinds
  gradientColors={["var(--color-chart-1)", "var(--color-chart-2)", "var(--color-chart-4)"]}
  angle={30}
  blindCount={24}
/>
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出静态百叶 fallback。
- `blindCount` 不是硬条数——窄容器下与 `blindMinWidth` 取较小者收敛；要严格按 count 渲染需把 `blindMinWidth` 设 0。
- 根需放进 `relative overflow-hidden` 定位容器并自带高度。
- 聚光灯跟随依赖指针事件，移动端/无指针下退化为静态色带。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# GradualBlur

> 沿容器某一边叠加多层 backdrop-filter 的渐进式模糊贴边 · 八方向/曲线/指数递增 + 悬停增强 + 进场淡入(零依赖·tokens·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

给滚动容器/图片墙某一边贴一条渐进模糊条，把贴边内容柔化淡出（常做长列表底部/顶部的「渐隐遮罩」）。它靠 `backdrop-filter` 模糊下层真实内容，不绘制自身像素；要纯装饰的边框流光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam) 这类组件。父容器须 `relative` 定位。

## 导入
```ts
import { GradualBlur } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| position | `"top"｜"bottom"｜"left"｜"right"` | `"bottom"` | 模糊条贴靠的边；top/bottom 为横条，left/right 为竖条 |
| strength | `number` | `2` | 模糊强度基数，每层按曲线递增，建议 1–6 |
| height | `string` | `"6rem"` | 横条厚度；竖条模式下若没传 width 则复用此值作竖条宽度 |
| width | `string` | — | 竖条（left/right）宽度，缺省回落到 `height` |
| divCount | `number` | `5` | 叠加模糊层数，越多过渡越细腻、越费性能，建议 3–10 |
| exponential | `boolean` | `false` | 指数级递增模糊量（近边缘急剧变糊），false=线性 |
| curve | `"linear"｜"bezier"｜"ease-in"｜"ease-out"｜"ease-in-out"` | `"linear"` | 每层模糊量沿进度的爬升曲线 |
| opacity | `number` | `1` | 整体不透明度 |
| hoverIntensity | `number` | — | 悬停时模糊放大倍数；传入即启用并接管指针事件（pointer-events:auto），不传则容器穿透不挡交互 |
| revealOnScroll | `boolean` | `false` | 进入视口时淡入（IntersectionObserver 驱动），开启后默认不可见 |
| duration | `string` | `"0.3s"` | 淡入过渡时长，仅 `revealOnScroll` 时生效 |
| zIndex | `number` | `10` | 叠加的 z-index |
| className | `string` | — | 透传根容器额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式（与内部计算样式合并，同名以此为准） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在模糊层之上的内容（如贴边标题/操作条） |

## 示例
```tsx
<div className="relative h-64 overflow-hidden rounded-xl bg-surface">
  {/* ...滚动内容... */}
  <GradualBlur position="bottom" height="7rem" />
</div>
```

顶部强模糊、指数递增：
```tsx
<GradualBlur position="top" height="8rem" strength={4} divCount={8} exponential />
```

## 禁忌 / 坑

- 靠 `backdrop-filter` 工作：若祖先元素自身带了 `filter` / `backdrop-filter` / `transform`，会创建新的包含块，模糊层的 fixed/绝对定位可能错位失效，见 [[backdrop-filter-ancestor-breaks-fixed-overlay-centering]]。
- 不传 `hoverIntensity` 时容器 `pointer-events:none` 不挡下层交互；一旦传入会接管指针事件，注意别遮住可点内容。
- 不传 `width` 时竖条宽度复用 `height` 值，这是有意设计，别误以为是 bug。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Grainient

> 三色域扭曲 + 胶片颗粒的 WebGL 渐变背景 · 噪声驱动旋转 + 实时 grain/对比度后期(ogl·reduced-motion 降级静态渐变) · decoration/backdrop · #animated #webgl

## 何时用

需要柔和流动的三色渐变 + 胶片颗粒质感背景（hero、登录页、空状态、卡片底）时用。要带竖条百叶/聚光灯用 [GradientBlinds](https://hulianui.haloritual.com/components/gradient-blinds)；要液态金属峰脊用 [Ferrofluid](https://hulianui.haloritual.com/components/ferrofluid)；要纯几何底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)。本组件最"安静"、颗粒胶片感最强，适合大面积铺底放文字。

## 导入
```ts
import { Grainient } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| timeSpeed | `number` | `0.25` | 时间流速倍率，0=静止 |
| colorBalance | `number` | `0` | 三色偏置，负偏 color3 一侧、正偏 color1 一侧 |
| warpStrength | `number` | `1` | 域扭曲强度（内部按反比，越大越克制），建议 0.3–3 |
| warpFrequency | `number` | `5` | 域扭曲正弦频率（褶皱密度） |
| warpSpeed | `number` | `2` | 域扭曲随时间漂移速度 |
| warpAmplitude | `number` | `50` | 域扭曲基础振幅，与 warpStrength 共定褶皱幅度 |
| blendAngle | `number` | `0` | 三色混合轴向角度（度） |
| blendSoftness | `number` | `0.05` | 色带过渡柔和度（smoothstep 边缘宽） |
| rotationAmount | `number` | `500` | 噪声驱动整体旋转量（度） |
| noiseScale | `number` | `2` | 旋转噪声采样缩放，越大越细碎 |
| grainAmount | `number` | `0.1` | 颗粒强度，0=纯净渐变 |
| grainScale | `number` | `2` | 颗粒采样缩放（密度） |
| grainAnimated | `boolean` | `false` | 颗粒是否随时间闪动，静态更省性能 |
| contrast | `number` | `1.5` | 对比度，围绕中灰拉伸明暗 |
| gamma | `number` | `1` | Gamma 校正，<1 提亮、>1 压暗 |
| saturation | `number` | `1` | 饱和度，0=灰阶、>1 增艳 |
| centerX | `number` | `0` | 视图中心横向偏移，配合 zoom 取景 |
| centerY | `number` | `0` | 视图中心纵向偏移 |
| zoom | `number` | `0.9` | 缩放，越小看到色场范围越大 |
| color1 | `string` | `--color-chart-1` | 渐变第一色（亮端），任意 CSS 颜色 |
| color2 | `string` | `--color-chart-2` | 渐变第二色（主色/中段） |
| color3 | `string` | `--color-chart-4` | 渐变第三色（暗端） |
| className | `string` | — | 透传根容器，自带 `absolute inset-0 z-0` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 静态渐变兜底层内的内容 |

## 示例
```tsx
// 默认：chart token 三色域扭曲渐变
<div className="relative h-56 overflow-hidden rounded-xl bg-neutral-950">
  <Grainient />
  <div className="relative z-10 flex h-full items-center justify-center text-white/85">
    瑚琏组件库
  </div>
</div>
```
```tsx
// 自定义暖橙三色 + 放大取景
<Grainient color1="oklch(0.82 0.16 70)" color2="oklch(0.62 0.2 30)" color3="oklch(0.32 0.06 300)" zoom={1.3} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出静态渐变 fallback。
- 根自带 `absolute inset-0 z-0`，需放进 `relative` 容器；前景内容要 `relative z-10` 压在上层。
- `grainAnimated` 开启每帧重算颗粒会增加开销，大面积长驻背景建议保持默认静态颗粒。
- `warpStrength` 是"反比"语义——值越大扭曲反而越克制，别按直觉调大求强扭曲。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# GridDistortion

> 鼠标拖拽的液态网格扭曲 WebGL 背景 · 数据纹理位移场 + 鼠标速度涟漪/弛豫回弹(ogl·零外部资源默认程序化网格底纹·token 着色·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要"鼠标划过即液态涟漪扭曲"的强交互网格背景（hero、互动落地页）时用。要静态不动的几何网格用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要复古透视网格地平线用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)；要鼠标聚光不要扭曲用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。本组件交互核心是鼠标速度驱动的位移涟漪 + 弛豫回弹，也可扭曲传入图片。

## 导入
```ts
import { GridDistortion } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| grid | `number` | `15` | 位移网格边长（格子数），JS 每帧迭代 grid²，建议 8–30 |
| mouse | `number` | `0.1` | 鼠标影响半径因子（相对网格比例），影响范围 = grid × mouse |
| strength | `number` | `0.15` | 位移强度，鼠标速度 × 该系数写入位移场，越大涟漪越剧烈 |
| relaxation | `number` | `0.9` | 弛豫系数（每帧衰减，0–1），越近 1 余韵越长 |
| imageSrc | `string` | — | 被扭曲的图像；不传则程序化生成 chart token 网格底纹（推荐）；传入需同源或 CORS |
| color | `string` | `--color-chart-1` | 网格底纹主色（仅 imageSrc 未传时生效），任意 CSS 颜色 |
| className | `string` | — | 透传根容器（或兜底 div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认网格底纹 div） |

## 示例
```tsx
// 默认：程序化网格底纹，鼠标划过扭曲
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <GridDistortion />
</div>
```
```tsx
// 高密度 + 强扭曲
<GridDistortion grid={24} strength={0.3} mouse={0.18} />
```

## 禁忌 / 坑

- WebGL/ogl 客户端渲染：放在 `"use client"` 边界内；SSR / 无 WebGL 仅出静态网格底纹 fallback。
- `grid` 是 JS 侧每帧 O(grid²) 迭代，调到 30 以上会明显吃 CPU，谨慎。
- 传 `imageSrc` 扭曲外部图须同源或目标开启 CORS，否则 WebGL 纹理被污染读取失败。
- 根需放进 `relative overflow-hidden` 定位容器并自带高度（如 `h-64`）；扭曲交互依赖指针事件，移动端退化静态。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# GridMotion

> 倾斜网格视差背景 · 鼠标横移每行奇偶反向弹性追随 + 中心径向光晕(零依赖 motion useSpring·token·reduced-motion) · decoration/backdrop · #animated #webgl

## 何时用

需要把图片/文字/图标铺成倾斜网格、随鼠标横移产生奇偶行反向视差的 hero 背景时用。要纯几何网格底纹（无内容、无视差）用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要带消失点的复古透视网格用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)。

## 导入
```ts
import { GridMotion } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| items | `ReactNode[]` | 占位文字「Item N」 | 网格单元内容。字符串以 `http` 开头视为图片 URL，否则当文字；ReactNode 直接渲染。超过 行×列 截断，不足补占位 |
| rows | `number` | `4` | 网格行数，每行为独立视差平移单元（奇偶行反向） |
| columns | `number` | `7` | 网格列数 |
| gradientColor | `string` | `var(--color-primary)` | 中心径向光晕颜色，从画布中心向外渐隐 |
| maxMoveAmount | `number` | `300` | 鼠标横移时每行最大平移幅度(px)，越大视差越夸张 |
| rotate | `number` | `-15` | 网格整体旋转角度(deg)，营造透视斜切 |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 容器需 relative + overflow-hidden + 定高，组件用 absolute inset-0 铺满
<div className="relative h-72 overflow-hidden rounded-xl">
  <GridMotion className="absolute inset-0" />
</div>
```
```tsx
// 自定义文字 + 暖色光晕
<GridMotion
  className="absolute inset-0"
  gradientColor="var(--color-chart-1)"
  items={Array.from({ length: 28 }, (_, i) => WORDS[i % WORDS.length])}
/>
```

## 禁忌 / 坑

- 父容器必须 `relative + overflow-hidden + 定高`，组件靠 `absolute inset-0` 铺满；缺高度则不可见。
- 视差/光晕走客户端 motion `useSpring`，SSR 首帧无动画，属正常。reduced-motion 下视差降级。
- 自定义 `gradientColor` 传 CSS 变量须用带 `--color-` 前缀的 token（如 `var(--color-chart-1)`），裸 `var(--primary)` 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# GridPattern

> 网格背景 · 纯 SVG 线 + 虚线可配 + currentColor · decoration/backdrop

## 何时用

给区块铺线网格底纹（技术感/蓝图感）。要线网格用本组件；点状纹理用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)，斜条纹用 [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)，带透视滚动的复古网格用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)。

## 导入
```ts
import { GridPattern } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number` | `40` | 单元宽 |
| height | `number` | `40` | 单元高 |
| x | `number` | `0` | pattern x 偏移 |
| y | `number` | `0` | pattern y 偏移 |
| strokeDasharray | `string \| number` | `0` | 线虚线模式；`0` 实线，传如 `"4 2"` 即虚线 |

> 继承 `ComponentPropsWithoutRef<"svg">`。颜色取 `currentColor`，用 `text-*` 工具类控制。

## 示例
```tsx
<div className="relative h-48 overflow-hidden rounded-xl border">
  <GridPattern />
</div>

<GridPattern width={24} height={24} strokeDasharray="3 2" className="text-muted" />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，必须放在 `relative`（且通常 `overflow-hidden`）定位容器内。
- 颜色靠 `currentColor`，用 `text-*` 改色。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# GridScan

> 透视扫描网格 WebGL 背景 · 射线投射无限网格(实线/虚线/点线)+纵深推进的发光扫描脉冲+鼠标视差偏摆(ogl·token·reduced-motion 降级静态网格) · decoration/backdrop · #animated #webgl

## 何时用

需要科技感透视网格 + 纵深推进的发光扫描脉冲做 hero / 仪表盘背景时用。只要静态网格底纹（无扫描、无 WebGL）用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要复古地平线透视网格用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)。

## 导入
```ts
import { GridScan } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| linesColor | `string` | `var(--color-border)` | 网格线颜色，CSS 颜色字符串，默认取 token 明暗自适应 |
| scanColor | `string` | `var(--color-primary)` | 扫描带发光颜色，默认取品牌主色 |
| gridScale | `number` | `0.1` | 网格密度（格子缩放），越小越密，建议 0.05–0.3 |
| lineThickness | `number` | `1` | 网格线粗细（屏幕像素） |
| lineStyle | `"solid" \| "dashed" \| "dotted"` | `"solid"` | 线条样式：实线 / 虚线 / 点线 |
| scanOpacity | `number` | `0.45` | 扫描带发光不透明度(0–1)，0=纯网格无脉冲 |
| scanDirection | `"forward" \| "backward" \| "pingpong"` | `"pingpong"` | 扫描方向：由远及近 / 由近及远 / 往返循环 |
| scanDuration | `number` | `2` | 单趟扫描时长(秒)，越大越慢 |
| scanDelay | `number` | `2` | 两趟扫描间停顿(秒)，pingpong 时仅影响起步延迟 |
| scanSoftness | `number` | `2` | 扫描带柔化程度，越大光带越宽越柔 |
| noiseIntensity | `number` | `0.01` | 颗粒噪声强度，0=干净无噪点 |
| parallax | `boolean` | `true` | 随鼠标轻微透视偏摆；reduced-motion / 无 WebGL 自动失效 |
| className | `string` | — | 透传根容器(或 fallback div) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 叠在网格上方的内容，自动 relative z-10 层叠 |
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容，默认 token 静态网格 |

## 示例
```tsx
// 容器定高 + overflow-hidden，children 自动叠在网格之上
<div className="relative h-64 overflow-hidden rounded-xl">
  <GridScan />
  <div className="relative z-10 flex h-full items-center justify-center">
    GridScan
  </div>
</div>
```
```tsx
// 虚线网格 · 向前扫描
<GridScan lineStyle="dashed" scanDirection="forward" scanOpacity={0.6} />
```

## 禁忌 / 坑

- ogl/WebGL，仅客户端渲染；SSR 出 fallback 静态网格，水合后切真 shader 属正常。reduced-motion / 无 WebGL 下停在 `fallback`。
- 全屏背景层置于 opaque 背景的非层叠上下文父级里可能被父背景盖住而全黑，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- 自定义 `scanColor`/`linesColor` 传 CSS 变量须用 `--color-` 前缀 token，裸 `var(--primary)` 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Hyperspeed

> 超空间跃迁 warp 隧道背景 · 从消失点放射的双色车灯光带向观察者冲来 + 湍流扭曲 + 程序化辉光(ogl 单 shader·零新依赖·token·reduced-motion 静态降级) · decoration/backdrop · #animated #webgl

## 何时用

需要强冲击的 warp 隧道 / 跃迁速度感 hero 背景时用。要纯几何透视网格（无运动隧道）用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)；只要低调网格底纹用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。

## 导入
```ts
import { Hyperspeed } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `number` | `1` | 整体推进速度倍率，越大冲来越快，建议 0.2–4 |
| density | `number` | `40` | 道路两侧光带密度，越大越密集，建议 10–120 |
| distortion | `number` | `1` | 视野扭曲强度（湍流摆动），0=笔直隧道，建议 0–2 |
| fade | `number` | `0.4` | 雾化淡出强度，越大远处越快被黑暗吞没，建议 0–1 |
| leftColor | `string` | `var(--color-chart-4)` | 左侧（驶离）车灯色，任意 CSS 颜色 |
| rightColor | `string` | `var(--color-chart-2)` | 右侧（驶近）车灯色，任意 CSS 颜色 |
| className | `string` | — | 透传根容器（本身 block h-full w-full，由容器控尺寸） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时渲染在静态兜底层内的内容 |

## 示例
```tsx
// warp 隧道需深色底显辉光，容器定高 + overflow-hidden
<div className="relative h-64 overflow-hidden rounded-xl bg-black">
  <Hyperspeed className="absolute inset-0" />
</div>
```
```tsx
// 踩满油门：高速密集
<Hyperspeed speed={3} density={90} className="absolute inset-0" />
```

## 禁忌 / 坑

- 深色底才显辉光，浅色容器上几乎不可见，建议配 `bg-black` 或深色底。
- ogl 单 shader 仅客户端渲染；SSR / 无 WebGL 出 fallback 静态层，reduced-motion 下也降级。
- 全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- `leftColor`/`rightColor` 传 CSS 变量须用 `--color-` 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# ImageTrail

> 光标拖尾图片组件 · 移动光标沿轨迹依次甩出图片淡入跟随、缩小淡出(零依赖 RAF+lerp·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

让光标在区域内移动时沿轨迹依次甩出一串具体图片（作品缩略图、产品图）做拖尾，常用于作品集/落地页 hero。要抽象烟雾光效而非真实图片用 [GhostCursor](https://hulianui.haloritual.com/components/ghost-cursor)。根容器自带 `relative + overflow-hidden` 捕获层，传 `images` 是必填。

## 导入
```ts
import { ImageTrail } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| images* | `string[]` | — | 拖尾依次出现的图片 URL 列表（循环复用）；至少 1 张，建议 6–12 张 |
| threshold | `number` | `80` | 光标累计位移触发下一张图的阈值（px），越小越密集越频繁 |
| imageWidth | `number` | `190` | 单张图片宽度（px），高度按 1.1 宽高比自动派生 |
| followStrength | `number` | `0.5` | 跟随插值系数 0–1，越大跟手越紧，越小越黏滞 |
| fadeDuration | `number` | `0.8` | 单张图从出现到淡出消失的时长（秒） |
| className | `string` | — | 透传根容器（relative+overflow-hidden 捕获层）额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 覆盖在拖尾层之上的内容（如标题文案） |

## 示例
```tsx
<div
  className="relative h-72 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.16 0.02 255)" }}
>
  <ImageTrail images={IMAGES} className="border-0 bg-transparent" />
</div>
```

稀疏大图、慢淡出：
```tsx
<ImageTrail images={IMAGES} threshold={140} imageWidth={240} fadeDuration={1.2} />
```

## 禁忌 / 坑

- `images` 必填且至少 1 张，空数组没有任何拖尾。
- 远程图片受门禁限制（禁外链），库内 showcase 用内联 SVG data URI 占位；接入时请用本地/同源资源。
- 根容器需要明确高度 + `overflow-hidden`，否则甩出的图片会溢出容器。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Iridescence

> 虹彩光泽背景 · WebGL/ogl shader 连续光谱干涉 + 鼠标光流扰动 + chart token + 静态 fallback · decoration/backdrop · #animated #webgl

## 何时用

需要连续光谱/油膜般的虹彩光泽背景，且想要鼠标光流扰动交互时用。基于 WebGL/ogl，有 GPU 开销，自带无 WebGL fallback；与 [Silk](https://hulianui.haloritual.com/components/silk) 同为 WebGL 质感背景，Silk 偏丝绸流动、本组件偏虹彩光谱干涉；不愿引入 WebGL 则用纯 CSS 的 [Aurora](https://hulianui.haloritual.com/components/aurora)。

## 导入
```ts
import { Iridescence } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `[number, number, number] \| string` | `--color-chart-3` | 基础色调。RGB 数组每分量 0..1，或任意 CSS 颜色字符串（hex/oklch/hsl/var）。不传则读主题 token 随明暗切换 |
| speed | number | 1.0 | 动画速度倍率，建议 0.1–5 |
| amplitude | number | 0.1 | 鼠标偏移幅度（扰动强度），建议 0.01–0.5 |
| mouseReact | boolean | true | 是否响应鼠标/触摸（驱动 uMouse）。关闭后固定 (0.5,0.5)，效果保持但不随指针 |
| className | string | — | 透传到 canvas 或 fallback 容器 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | ReactNode | reduced-motion / 无 WebGL 时的静态降级内容 |

## 示例
```tsx
// 默认主题色，自带铺满 canvas，需 relative + overflow-hidden 父容器
<div className="relative h-56 overflow-hidden rounded-xl">
  <Iridescence />
</div>
```
```tsx
// 自定义冷蓝（RGB 数组）+ 高速强扰动
<Iridescence color={[0.3, 0.6, 1.0]} speed={1.5} amplitude={0.2} />
```

## 禁忌 / 坑

- WebGL 组件，须客户端渲染；`color` 既收 0..1 的 `[r,g,b]` 数组也收 CSS 字符串（含 `var(--…)`/oklch），由组件内部解析。
- ogl/WebGL 在 StrictMode 双挂载或 cleanup 时易踩 context 复用毒化坑——改源码时勿 cleanup 调 `loseContext` 后复用同一 canvas（参见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]）；headless 截图无 WebGL 时会走 fallback，视觉验证用真实浏览器。
- 父容器需 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Lanyard

> 可拖拽的挂绳工牌 · 单摆+阻尼弹簧物理回弹(原生 PointerEvents+RAF·零三方依赖) + SVG 二次贝塞尔挂绳随摆角实时弯折 + token 配色(挂绳 primary·工牌 surface/border)·reduced-motion 松手即静止归位 · decoration/overlay-fx · #animated

## 何时用

需要一个有物理感的「挂绳工牌」装饰交互——可拖拽、松手单摆阻尼回弹、挂绳随摆角实时弯折时用，适合个人站/团队页/趣味 hero。要做眩光悬停高光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)；要做静态边框光带用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)。Lanyard 是「会甩动的物理工牌」，工牌正面可放任意 children。

## 导入
```ts
import { Lanyard } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| ropeLength | `number` | `120` | 挂绳长度 px（顶部锚点到工牌钩扣的静止距离），越大摆幅越舒展回弹越慢 |
| ropeColor | `string` | `var(--color-primary)` | 挂绳颜色，喂 SVG stroke 的 token 须带 `--color-` 前缀 |
| stiffness | `number` | `0.045` | 回弹刚度（弹簧常数），越大回正越快越硬，建议 0.02–0.12 |
| damping | `number` | `0.92` | 阻尼（每帧速度衰减），越接近 1 余摆越久，建议 0.85–0.97 |
| title | `string` | `"瑚琏 · HULIAN"` | 占位工牌标题（仅未传 children 时显示） |
| subtitle | `string` | `"拖动摆一摆"` | 占位工牌副标题（仅未传 children 时显示） |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 工牌正面内容；不传则渲染占位工牌 |

## 示例

```tsx
// 默认占位工牌（在固定高度的相对定位舞台内绝对铺满）
<div className="relative h-80 overflow-hidden rounded-xl">
  <Lanyard className="absolute inset-0" />
</div>

// 长绳·绵软余摆
<Lanyard
  className="absolute inset-0"
  ropeLength={160}
  stiffness={0.025}
  damping={0.965}
  title="慢摇工牌"
  subtitle="拖一下放手看余摆"
/>
```

## 禁忌 / 坑

- 工牌靠绝对定位悬挂，根容器需是 `relative overflow-hidden` 且有明确高度，否则工牌会溢出或定位错乱（showcase 一律传 `className="absolute inset-0"` 配固定高舞台）。
- `ropeColor` 喂 SVG stroke，token 必须带 `--color-` 前缀，裸 `var(--primary)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- 客户端组件（PointerEvents + RAF 物理循环），SSR 下不摆动；reduced-motion 下松手立即静止归位，不做余摆。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# LaserFlow

> 自顶向下倾泻的体积激光束 WebGL 背景 · 极坐标光束几何 + fbm 噪声雾 + 行进微流光 + 指针牵引倾斜(ogl 去 three·主题感知·reduced-motion 降级) · decoration/overlay-fx · #animated

## 何时用

作为整屏/整块的 WebGL 体积光背景，自顶向下倾泻激光束 + 雾 + 流光，适合 hero/壁纸级氛围底。要环绕单元素的边框流光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；要鼠标拖尾烟雾用 [GhostCursor](https://hulianui.haloritual.com/components/ghost-cursor)。本组件渲染量重，放在容器底层、内容用 `relative z-10` 叠在其上。

## 导入
```ts
import { LaserFlow } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-chart-1)` | 激光主色，吃明暗主题；任意 CSS 颜色串均可（→ uColor） |
| horizontalBeamOffset | `number` | `0.0` | 横向光束偏移（占视口宽比例），正右负左（→ uBeamXFrac） |
| verticalBeamOffset | `number` | `0.0` | 纵向光束偏移（占视口高比例）（→ uBeamYFrac） |
| flowSpeed | `number` | `0.35` | 光流脉冲速度因子，越大流动越快（→ uFlowSpeed） |
| verticalSizing | `number` | `2.0` | 纵向光束长度因子，越大越长（→ uVLenFactor） |
| horizontalSizing | `number` | `0.5` | 横向耀斑长度因子（→ uHLenFactor） |
| fogIntensity | `number` | `0.45` | 体积雾强度，0=无雾（→ uFogIntensity） |
| fogScale | `number` | `0.3` | 雾噪声缩放，越大雾团越细碎（→ uFogScale） |
| fogFallSpeed | `number` | `0.6` | 雾团下落速度（→ uFogFallSpeed） |
| wispDensity | `number` | `1` | 微流光密度 0–2（→ uWispDensity） |
| wispSpeed | `number` | `15` | 微流光行进速度（→ uWSpeed） |
| wispIntensity | `number` | `5` | 微流光亮度强度（→ uWIntensity） |
| flowStrength | `number` | `0.25` | 光流明暗脉冲强度 0–1（→ uFlowStrength） |
| decay | `number` | `1.1` | 光束衰减相位宽度（→ uDecay） |
| falloffStart | `number` | `1.2` | 光束发光起始衰减（→ uFalloffStart） |
| mouseTiltStrength | `number` | `0.01` | 鼠标牵引雾团倾斜强度；设 0 即关闭鼠标交互（→ uTiltScale） |
| className | `string` | — | 透传根容器（或 reduced-motion fallback div）额外 className |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时渲染的静态替代内容；缺省为吃 chart token 的纵向 linear-gradient 光束 div |

## 示例
```tsx
<div
  className="relative h-72 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.13 0.02 285)" }}
>
  <LaserFlow />
  <div className="relative z-10 flex h-full items-center justify-center text-sm text-white/80">
    LaserFlow
  </div>
</div>
```

暖橙激光 + 高雾：
```tsx
<LaserFlow color="oklch(0.72 0.2 35)" fogIntensity={0.6} fogScale={0.35} />
```

## 禁忌 / 坑

- WebGL（ogl）组件，React StrictMode 双挂载下 cleanup 调 `loseContext` 会毒化 canvas 复用致空白崩溃，内部应每挂载新建 canvas，见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 内容必须用 `relative z-10`（或更高）叠在 LaserFlow 之上，否则被体积光盖住。
- reduced-motion / 无 WebGL 会渲染 `fallback`（默认渐变 div），不要假设一定有动画。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Lens

> 放大镜 · 悬停光标处圆形放大任意 children(零依赖 mask+scale) · decoration/overlay-fx · #animated

## 何时用

想让用户悬停时在光标处用一个圆形镜片局部放大内容（产品图、地图、截图细节）时用。children 可以是任意内容（图片最常见），零依赖、纯 mask+scale 实现。要的是 hover 斜扫反光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)；要边框光效用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam) / [ShineBorder](https://hulianui.haloritual.com/components/shine-border)。

## 导入
```ts
import { Lens } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| zoom | `number` | `1.8` | 放大倍数 |
| size | `number` | — | 镜片直径 px |
| className | `string` | — | 透传 className |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 被放大的内容（常为 `<img>`） |

## 示例

```tsx
<Lens zoom={1.8} className="w-80 rounded-[var(--radius)] border">
  <img src="/photo.jpg" alt="森林" className="block aspect-[4/3] w-full object-cover" />
</Lens>
```

## 禁忌 / 坑

- 需指针 hover 才触发，纯触屏/键盘场景下无放大效果，不要把它当唯一的细节查看方式。
- `children` 必须是有确定尺寸、能被 scale 的可视内容（如 `block` 的 `<img>`），否则镜片放大区为空。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# LetterGlitch

> 终端字符故障雨背景 · canvas 等宽字符矩阵按节拍随机翻字翻色 + 颜色逐帧插值平滑 + 内/外缘暗角(零依赖 canvas2d·token 调色板·reduced-motion) · decoration/backdrop · #animated #webgl

## 何时用

需要黑客终端 / Matrix 风格的字符故障雨背景时用。要纯几何点阵底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；要科技感网格扫描用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。本组件是 canvas2d 字符矩阵，主打"翻字翻色"故障感。

## 导入
```ts
import { LetterGlitch } from "@hulianui/ui"
```

## Props

> 继承 `HTMLAttributes<HTMLDivElement>`（除 `color`），可透传 `id` / 事件等。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| glitchColors | `string[]` | `["var(--color-chart-2)", "var(--color-chart-1)", "var(--color-chart-4)"]` | 字符闪变调色板，任意 CSS 颜色，内部离屏 canvas 解析为 RGB 插值 |
| glitchSpeed | `number` | `50` | 相邻刷新最小间隔(ms)，越小越躁动，建议 20–200 |
| smooth | `boolean` | `true` | 颜色平滑过渡（逐帧插值）；关闭后硬切，更生硬故障感 |
| outerVignette | `boolean` | `true` | 外缘暗角（四周径向渐隐） |
| centerVignette | `boolean` | `false` | 中心暗角（中部压暗→边缘透亮），用于反衬置入内容 |
| characters | `string` | 大写字母+符号+数字 | 参与闪变的字符集，内部按码点拆分，支持任意 Unicode |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 容器定高 + overflow-hidden，组件 absolute inset-0 铺满
<div className="relative h-56 overflow-hidden rounded-xl">
  <LetterGlitch className="absolute inset-0" />
</div>
```
```tsx
// 中心暗角 + 置入内容
<div className="relative h-56 overflow-hidden rounded-xl">
  <LetterGlitch className="absolute inset-0" outerVignette={false} centerVignette />
  <div className="absolute inset-0 flex items-center justify-center">
    <p className="text-lg font-semibold tracking-widest text-white">GLITCH</p>
  </div>
</div>
```

## 禁忌 / 坑

- canvas2d 仅客户端，需在 client 组件树内使用；SSR 首帧空白属正常。reduced-motion 下降级。
- 字符矩阵在深色底上才有终端观感，浅色容器对比度差。
- `glitchColors` 传 CSS 变量须用 `--color-` 前缀 token，裸 `var(--primary)` 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Lightfall

> 隧道光束坠落 WebGL 背景 · 多色光束按高度循环取色 + 中心辉光 + 闪烁/拖尾 + 鼠标牵引(ogl·token·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要深色 hero 上多色光束坠落、带中心辉光与拖尾的氛围背景时用。要放射状光束（自原点向外）用 [LightRays](https://hulianui.haloritual.com/components/light-rays)；要单根体积光柱用 [LightPillar](https://hulianui.haloritual.com/components/light-pillar)；只要静态点阵底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)。

## 导入
```ts
import { Lightfall } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `["var(--color-chart-1)", "var(--color-chart-2)", "var(--color-chart-4)"]` | 光束色板（按高度循环），任意 CSS 颜色，最多取前 8 个 |
| backgroundColor | `string` | `var(--color-primary)` | 背景中心辉光底色 |
| speed | `number` | `0.5` | 坠落速度，0 近似静止（仍渲染） |
| streakCount | `number` | `2` | 同时坠落的光束条数（1–16，四舍五入夹取） |
| streakWidth | `number` | `1` | 单束横向宽度系数，越大越粗 |
| streakLength | `number` | `1` | 单束拖尾长度系数，越大尾迹越长 |
| glow | `number` | `1` | 整体辉光强度 |
| density | `number` | `0.6` | 光束角向疏密（环数），越大越密集 |
| twinkle | `number` | `1` | 闪烁强度，0=常亮，1=明暗呼吸 |
| zoom | `number` | `3` | 视距缩放（隧道纵深感） |
| backgroundGlow | `number` | `0.5` | 背景中心辉光强度，0=关闭 |
| opacity | `number` | `1` | 整体不透明度（写入 shader） |
| mouseInteraction | `boolean` | `true` | 鼠标交互（指针增亮 + 牵引光团） |
| mouseStrength | `number` | `0.5` | 鼠标增亮强度 |
| mouseRadius | `number` | `1` | 鼠标影响半径 |
| className | `string` | — | 透传根容器（组件自带 absolute inset-0 z-0） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态兜底内容 |

## 示例
```tsx
// 组件自带 absolute inset-0，容器只需 relative + 定高 + overflow-hidden
<div className="relative h-64 overflow-hidden rounded-xl">
  <Lightfall />
  <div className="relative z-10 flex h-full items-center justify-center">
    Lightfall
  </div>
</div>
```
```tsx
// 缓慢壁纸级：长拖尾 · 无交互
<Lightfall speed={0.25} streakCount={3} streakLength={1.8} mouseInteraction={false} />
```

## 禁忌 / 坑

- 组件自带 `absolute inset-0 z-0`，叠在它上面的内容须 `relative z-10`，否则被盖住。
- ogl/WebGL 仅客户端；SSR / 无 WebGL 出 fallback，reduced-motion 下降级。
- 全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖成全黑，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- `colors`/`backgroundColor` 传 CSS 变量须用 `--color-` 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Lightning

> fbm 噪声电弧/极光柱 WebGL 背景 · 距离场反比辉光 + hash 随机闪烁(ogl·token 取色·reduced-motion 静态降级) · decoration/backdrop · #animated #webgl

## 何时用

需要纵向电弧 / 极光柱辉光背景、带随机闪烁的科技感 hero 时用。要单根稳定的体积光柱用 [LightPillar](https://hulianui.haloritual.com/components/light-pillar)；要放射状光束用 [LightRays](https://hulianui.haloritual.com/components/light-rays)；要坠落光束用 [Lightfall](https://hulianui.haloritual.com/components/lightfall)。

## 导入
```ts
import { Lightning } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| hue | `number` | `230` | 闪电色相(0–360, HSV 色环)，仅未传 `color` 时生效。例 30 暖橙 / 120 青绿 / 280 品紫 |
| color | `string` | `undefined` | 闪电主色，传入后覆盖 `hue` 路径，shader 直接吃；传 `var(--color-chart-1)` 可吃 token 明暗自适应 |
| xOffset | `number` | `0` | 水平偏移(clip-space)，正值推向右、负值推向左 |
| speed | `number` | `1` | 动画速度因子，越大闪烁/翻涌越快 |
| intensity | `number` | `1` | 辉度强度，越大越亮越粗 |
| size | `number` | `1` | 噪声尺度，越大分叉越细密、越小越宏观 |
| className | `string` | — | 透传根容器(reduced / WebGL 失败时透传 fallback div) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容，默认 token 纵向辉光渐变 |

## 示例
```tsx
// 默认蓝紫色相 230，容器定高 + overflow-hidden
<div className="relative h-64 overflow-hidden rounded-xl bg-black">
  <Lightning />
</div>
```
```tsx
// 吃 chart token，明暗自适应
<Lightning color="var(--color-chart-1)" intensity={1.2} />
```

## 禁忌 / 坑

- `color` 与 `hue` 二选一：传了 `color` 则 `hue` 失效。要 token 自适应优先用 `color="var(--color-chart-1)"`。
- ogl/WebGL 仅客户端；SSR / 无 WebGL 出 fallback（token 渐变），reduced-motion 下也降级。
- `color` 传 CSS 变量须用 `--color-` 前缀 token，裸 `var(--primary)` shader 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。
- 全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# LightPillar

> 体积光柱 WebGL 背景 · 沿 y 轴 raymarch 累积辉光 + 多层波动噪声 + 顶底双色纵向渐变(ogl·token 自适应·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要单根顶底渐变的体积光柱做居中 hero 焦点时用。要随机闪烁的电弧/极光柱用 [Lightning](https://hulianui.haloritual.com/components/lightning)；要放射状多束光用 [LightRays](https://hulianui.haloritual.com/components/light-rays)；要坠落光束用 [Lightfall](https://hulianui.haloritual.com/components/lightfall)。

## 导入
```ts
import { LightPillar } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| topColor | `string` | `var(--color-chart-2)` | 光柱顶部颜色，任意 CSS 颜色，默认 token 明暗自适应 |
| bottomColor | `string` | `var(--color-chart-1)` | 光柱底部颜色，与顶色沿 y 轴渐变混合 |
| intensity | `number` | `1` | 整体亮度系数，越大越亮 |
| rotationSpeed | `number` | `0.3` | 自转速度因子，同时驱动时间推进，0=几乎静止 |
| glowAmount | `number` | `0.005` | 辉光强度（raymarch 累积增益），建议 0.001–0.02 |
| pillarWidth | `number` | `3` | 光柱粗细（世界半径），越小越细如激光 |
| pillarHeight | `number` | `0.4` | 光柱高度系数，越大纵向条纹越密 |
| noiseIntensity | `number` | `0.5` | 颗粒噪声强度，0=纯净无颗粒 |
| pillarRotation | `number` | `0` | 光柱整体倾斜角度(度)，例 30=向一侧斜射 |
| className | `string` | — | 透传 canvas 容器(或 fallback div) |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容，默认 token 渐变光柱 |

## 示例
```tsx
// token 双色，容器定高 + overflow-hidden
<div className="relative h-64 overflow-hidden rounded-xl">
  <LightPillar />
  <div className="relative z-10 flex h-full items-center justify-center">
    LightPillar
  </div>
</div>
```
```tsx
// 细激光：窄柱 · 高亮 · 无颗粒
<LightPillar pillarWidth={1.4} glowAmount={0.009} noiseIntensity={0} intensity={1.2} />
```

## 禁忌 / 坑

- ogl/WebGL 仅客户端；SSR / 无 WebGL 出 fallback（token 渐变），reduced-motion 下降级。
- `glowAmount` 量级很小（默认 0.005），调亮时小步加（如 0.009），数量级跳大会过曝。
- `topColor`/`bottomColor` 传 CSS 变量须用 `--color-` 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。
- 全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# LightRays

> 体积光束放射 WebGL 背景 · 八向原点 + 双层正弦扰动/扩散衰减/脉动/噪点/扭曲 + 鼠标方向跟随(ogl·token 着色·reduced-motion 静态渐变兜底) · decoration/backdrop · #animated #webgl

## 何时用

需要自某个原点（八向可选）放射的体积光束做 hero 背景、且可跟随鼠标偏转时用。要单根体积光柱用 [LightPillar](https://hulianui.haloritual.com/components/light-pillar)；要坠落光束用 [Lightfall](https://hulianui.haloritual.com/components/lightfall)；要随机闪烁电弧用 [Lightning](https://hulianui.haloritual.com/components/lightning)。

## 导入
```ts
import { LightRays } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| raysOrigin | `"top-center" \| "top-left" \| "top-right" \| "left" \| "right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"top-center"` | 光束发射原点，决定锚点与传播方向（四角 / 四边中点） |
| raysColor | `string` | `var(--color-chart-1)` | 光束颜色，任意 CSS 颜色，离屏 canvas 解析为 RGB |
| raysSpeed | `number` | `1` | 闪烁/律动速度倍率，0 近乎静止（仍渲染一帧） |
| lightSpread | `number` | `1` | 光束扩散角度，越大越散、越小越聚拢，建议 0.3–3 |
| rayLength | `number` | `2` | 光束长度（相对视口宽倍数） |
| pulsating | `boolean` | `false` | 整体亮度随时间正弦呼吸 |
| fadeDistance | `number` | `1` | 沿程渐隐距离（相对视口宽倍数），越小越快淡出 |
| saturation | `number` | `1` | 饱和度，<1 去色趋灰，0=纯灰阶 |
| followMouse | `boolean` | `true` | 光束方向跟随鼠标（需 mouseInfluence>0 才有可见偏转） |
| mouseInfluence | `number` | `0.1` | 鼠标对方向的影响权重(0–1)，0=不偏转 |
| noiseAmount | `number` | `0` | 颗粒噪声强度(0–1) |
| distortion | `number` | `0` | 角度扭曲强度，让光束摇曳而非笔直，建议 0–1 |
| className | `string` | — | 透传根容器（自带 pointer-events-none absolute inset-0 z-0） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 叠在光束层之上的内容，WebGL 与降级两路径均渲染 |
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时叠在静态渐变上的兜底内容 |

## 示例
```tsx
// 自带 absolute inset-0，容器 relative + 定高 + overflow-hidden
<div className="relative h-64 overflow-hidden rounded-xl">
  <LightRays raysOrigin="top-center" className="opacity-90" />
  <div className="relative z-10 flex h-full items-center justify-center">
    LightRays
  </div>
</div>
```
```tsx
// 左侧射入 · 暖色 · 聚拢窄束
<LightRays raysOrigin="left" raysColor="oklch(0.78 0.16 70)" lightSpread={0.8} />
```

## 禁忌 / 坑

- 组件自带 `pointer-events-none absolute inset-0 z-0`，叠加内容须 `relative z-10` 才在它之上。
- `followMouse` 默认 true，但需 `mouseInfluence>0`（默认 0.1）才有可见偏转；想完全静止设 `mouseInfluence={0}`。
- ogl/WebGL 仅客户端；SSR / 无 WebGL 出静态渐变兜底，reduced-motion 下降级。`children` 两路径都渲染以保 DOM 一致。
- `raysColor` 传 CSS 变量须用 `--color-` 前缀 token，见 [[hulian-token-color-var-needs-color-prefix]]。
- 全屏背景层在 opaque 背景的非层叠上下文父级里可能被父背景盖住，见 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# LineWaves

> 流动波纹线阵 WebGL 背景 · 双正弦位移场 + 噪声脊线 + 三通道色相循环 + 鼠标局部隆起(ogl·chart token 配色·reduced-motion 静态线纹降级) · decoration/backdrop · #animated #webgl

## 何时用

需要一层「流动线条纹理」的氛围背景（Hero、登录页、空状态铺底）时用它。要点阵/网格几何感选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)，要斜向条纹选 [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)，要鼠标聚光选 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；本组件是有机的波动线场，运动感与色相漂移更强。

## 导入
```ts
import { LineWaves } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `number` | `0.3` | 动画速度因子；越大流动越快，0 = 静止纹理 |
| innerLineCount | `number` | `32` | 中心区线条密度；与 outerLineCount 共同决定疏密渐变 |
| outerLineCount | `number` | `36` | 边缘区线条密度；与 inner 不同时上下边缘到中心产生疏密过渡 |
| warpIntensity | `number` | `1` | 波纹扭曲强度；越大越「波涛汹涌」，0 = 笔直平行线 |
| rotation | `number` | `-45` | 整体纹理旋转角（度）；-45° 使波纹呈对角线走向 |
| edgeFadeWidth | `number` | `0` | 上下边缘渐隐起始宽度；增大可让中心线条区收窄 |
| colorCycleSpeed | `number` | `1` | 颜色循环速度；三通道色相随时间漂移，0 = 颜色恒定 |
| brightness | `number` | `0.2` | 整体亮度系数；因 alpha=颜色长度，同时影响透明度。建议 0.1–0.6 |
| color1 | `string` | `--color-chart-1` | 第一通道颜色，CSS 颜色串；默认取 chart token 明暗自适应 |
| color2 | `string` | `--color-chart-2` | 第二通道颜色 |
| color3 | `string` | `--color-chart-4` | 第三通道颜色；三色都传同一值（如 #ffffff）可还原原版白线 |
| enableMouseInteraction | `boolean` | `true` | 开启指针局部扭曲外推；关闭则纯自动流动 |
| mouseInfluence | `number` | `2` | 指针影响强度；仅 enableMouseInteraction=true 时生效 |
| className | `string` | — | 透传到根容器（或 reduced-motion fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认斜向 chart token 渐变线纹 |

## 示例

```tsx
// 默认：深底上的 chart token 波纹（父容器须 relative，内容叠更高 z）
<div className="relative h-64 overflow-hidden rounded-xl">
  <LineWaves />
  <div className="relative z-10 flex h-full items-center justify-center">
    <p className="text-2xl font-bold text-white/90">LineWaves</p>
  </div>
</div>
```

```tsx
// 还原经典白线：三色同 #ffffff + 关掉色相循环
<LineWaves color1="#ffffff" color2="#ffffff" color3="#ffffff" brightness={0.25} colorCycleSpeed={0} />
```

## 禁忌 / 坑

- 组件自带 `absolute inset-0 z-0`，**父容器必须 `relative` 且页面内容要叠更高 z-index**（如 `relative z-10`），否则线纹要么定位错乱、要么盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件，在 Next App Router 下放进 RSC 树前注意它是 `"use client"`；SSR 阶段不渲染 canvas，只走 fallback。
- `color1/2/3` 传 `var(--color-…)` 时运行时经离屏 canvas 解析颜色，**裸 `var(--primary)` 不带 `--color-` 前缀会解析失败**（黑/透明） [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到空白/静止帧——rAF 驱动的动画在无头环境被饿死，属预期而非 bug，真机或 Playwright 实测可见 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# LiquidChrome

> 液态铬背景 · WebGL/ogl 金属流动反光 + 鼠标涟漪 + chart token 基色 + 静态金属渐变 fallback · decoration/backdrop · #animated #webgl

## 何时用

需要一层铺满区域、缓慢流动的液态金属/铬反光背景（hero、登录页、卡片底）时用。它 `absolute inset-0` 铺满父容器，是背景层而非焦点元素。若要的是聚焦视线、随指针交互的发光能量球用 [Orb](https://hulianui.haloritual.com/components/orb)；只要静态、零成本的几何底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) / [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)。

## 导入
```ts
import { LiquidChrome } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| baseColor | `[number, number, number] \| string` | `var(--color-chart-2)` | 液态铬基础色。`[r,g,b]` 为 0..1 浮点数组（兼容 react-bits 原版），或任意 CSS 颜色串；默认读 chart-2 token 跟随明暗主题 |
| speed | `number` | `0.2` | 流动速度乘子，越大越快 |
| amplitude | `number` | `0.6` | 波形振幅（0 平静 → 1 强烈），控制液面扭曲幅度 |
| frequencyX | `number` | `2.5` | X 方向空间频率 |
| frequencyY | `number` | `1.5` | Y 方向空间频率 |
| interactive | `boolean` | `true` | 是否响应鼠标 / 触摸推动液面涟漪 |
| className | `string` | — | 透传到 canvas（正常）或 fallback div（降级）的 className |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时叠加在金属渐变背景上的静态内容 |

## 示例

```tsx
// 背景层：父容器须 relative，LiquidChrome 自身 absolute inset-0 铺满
<div className="relative h-48 w-full overflow-hidden rounded-xl">
  <LiquidChrome />
</div>
```

```tsx
// 做 hero 背景层，内容叠在上方
<div className="relative h-72 w-full overflow-hidden rounded-xl">
  <LiquidChrome speed={0.18} amplitude={0.55} />
  <div className="relative z-10 flex h-full flex-col items-center justify-center text-center">
    <p className="text-2xl font-bold text-white drop-shadow-md">Liquid Chrome</p>
  </div>
</div>
```

## 禁忌 / 坑

- WebGL 组件，须客户端渲染；SSR / 无 WebGL / reduced-motion 时降级为静态金属渐变 fallback，注意首屏视觉差异。
- cleanup 别调 `loseContext` 毒化 canvas，否则 StrictMode 双挂载复用 canvas 会崩成空白——参见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]，每次挂载新建 canvas。
- 自身 `absolute inset-0`，父容器必须 `position:relative` 且有确定高度，否则不可见；内容叠加层记得加 `relative z-10`。
- 传 `baseColor` 字符串走 CSS 颜色解析，喂裸 `var(--primary)` 可能不解析，token 需带 `--color-` 前缀——参见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# LiquidEther

> 鼠标驱动的液态色域 WebGL 背景 · 域扭曲+metaball 翻涌 + 指针搅动/自动巡游(ogl·token·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要一层「跟手翻涌的液态色团」氛围背景（创意官网、产品 Hero、登录页）时用它，指针交互感最强。要规则点阵/网格选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)，要扫光聚焦选 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；本组件是有机色域流体，色彩重量大，常配 `opacity` 压低做壁纸底。

## 导入
```ts
import { LiquidEther } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `["var(--color-chart-1)","var(--color-chart-2)","var(--color-chart-4)"]` | 调色板，至少 1 色（少于 2 会自动复制两端）；任意 CSS 颜色串，随明暗主题切换 |
| speed | `number` | `0.5` | 流动速度因子；建议 0.2–1.5 |
| scale | `number` | `1` | 液态团块尺度；越小越细碎越多团，越大越融合。建议 0.6–2 |
| mouseForce | `number` | `1` | 指针扰动强度；0=无视指针纯漂流。建议 0–2 |
| autoDemo | `boolean` | `true` | 无人交互时虚拟光标自动巡游搅动；关闭则静止待真实指针 |
| opacity | `number` | `1` | 整体不透明度 0–1；叠内容上常用 0.6–0.85 降视觉重量 |
| className | `string` | — | 透传到根容器（canvas 包裹层或 reduced fallback） |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认多点 chart token radial-gradient 静态液面 |

## 示例

```tsx
// 默认：自动巡游的液态色域（父容器须 relative + overflow-hidden）
<div className="relative h-64 overflow-hidden rounded-xl">
  <LiquidEther />
</div>
```

```tsx
// 壁纸级：慢速 + 半透明叠底，内容叠在更高 z
<div className="relative h-64 overflow-hidden rounded-xl">
  <LiquidEther speed={0.3} scale={1.2} opacity={0.7} />
  <div className="pointer-events-none relative z-10 flex h-full items-center justify-center text-white">
    瑚琏组件库
  </div>
</div>
```

## 禁忌 / 坑

- 父容器须 `relative` + `overflow-hidden`，内容用 `relative z-10` 叠在上层；canvas 会满铺，叠加的文本建议加 `pointer-events-none` 避免吃掉指针搅动 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback，不会有 canvas。
- `colors` 传 `var(--color-…)` 时运行时经离屏 canvas 解析，**必须带 `--color-` 前缀**，裸 `var(--primary)` 解析不出 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到流动 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# MagicRings

> 同心魔法光环装饰背景 · GLSL 循环扩张/淡入淡出双色波纹 + 噪点颗粒 + 鼠标视差/悬停缩放/点击爆发（ogl·token 双色·reduced-motion 静态同心环降级） · decoration/overlay-fx · #animated

## 何时用

作为整块装饰背景，渲染不断向外扩张淡出的同心光环波纹（双色插值），适合登录页/hero/空状态底纹。要倾泻式体积激光用 [LaserFlow](https://hulianui.haloritual.com/components/laser-flow)，要环绕单元素的边框流光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；本组件是「径向扩散涟漪」氛围层。建议 `className="absolute inset-0"` 铺满父容器。

## 导入
```ts
import { MagicRings } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-chart-1)` | 内圈起始色，吃明暗主题；任意 CSS 颜色串均可 |
| colorTwo | `string` | `var(--color-chart-4)` | 外圈终止色，光环色在 color→colorTwo 间按层数线性插值 |
| speed | `number` | `1` | 动画速度倍率，越大波纹扩散越快 |
| ringCount | `number` | `6` | 同时存在的光环层数（1–10，超出截断） |
| attenuation | `number` | `10` | 光晕衰减系数，越大环线越锐利短促，越小越弥散 |
| lineThickness | `number` | `2` | 环线粗细倍率 |
| baseRadius | `number` | `0.35` | 最内圈起始半径（归一化约 0–1） |
| radiusStep | `number` | `0.1` | 相邻两圈起始半径的递增步长 |
| scaleRate | `number` | `0.1` | 单生命周期内环半径的扩张幅度 |
| opacity | `number` | `1` | 整体不透明度，叠加在按亮度派生的 alpha 之上 |
| blur | `number` | `0` | CSS 模糊半径（px），>0 给画布加 filter:blur |
| noiseAmount | `number` | `0.1` | 颗粒噪点强度，0=干净 |
| rotation | `number` | `0` | 整体旋转角度（度） |
| ringGap | `number` | `1.5` | 各环角向裂口幅度，越大缺口越深呈花瓣状 |
| fadeIn | `number` | `0.7` | 单环淡入比例（生命周期前段） |
| fadeOut | `number` | `0.5` | 单环淡出起点比例（生命周期后段） |
| followMouse | `boolean` | `false` | 光环跟随鼠标位移产生视差 |
| mouseInfluence | `number` | `0.2` | followMouse 时鼠标对整体的位移影响系数 |
| hoverScale | `number` | `1.2` | 悬停时整体缩放目标值 |
| parallax | `number` | `0.05` | 各层随鼠标的视差错位系数 |
| clickBurst | `boolean` | `false` | 点击爆发（点击时短暂放大+提亮） |
| className | `string` | — | 透传根容器（或 fallback div）额外 className |

## 示例
```tsx
<div
  className="relative h-64 overflow-hidden rounded-xl"
  style={{ background: "oklch(0.14 0.02 280)" }}
>
  <MagicRings className="absolute inset-0" />
</div>
```

交互式（鼠标视差 + 点击爆发）：
```tsx
<MagicRings className="absolute inset-0" followMouse clickBurst hoverScale={1.25} />
```

## 禁忌 / 坑

- WebGL（ogl）组件，React StrictMode 双挂载下 cleanup 调 `loseContext` 会毒化 canvas 复用致空白，内部应每挂载新建 canvas，见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 父容器须 `relative` + 深色底，光环用 `absolute inset-0` 铺满。
- reduced-motion / 无 WebGL 降级为静态同心环，不要假设一定有扩散动画。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Magnet

> 指针磁吸交互组件 · 内容按「到中心距离/强度」牵引跟随指针、离开平滑归位(零依赖·reduced-motion 钳位) · decoration/overlay-fx · #animated

## 何时用

包裹单个交互元素（按钮、图标、CTA），指针靠近时内容被磁吸牵引跟随、离开平滑归位，做精致的微交互。要给整块区域做指针烟雾/图片拖尾背景用 [GhostCursor](https://hulianui.haloritual.com/components/ghost-cursor) / [ImageTrail](https://hulianui.haloritual.com/components/image-trail)；本组件是「单元素跟手位移」的轻交互。继承 `HTMLAttributes<HTMLDivElement>`（除 children），可透传 div 属性。

## 导入
```ts
import { Magnet } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| padding | `number` | `100` | 感应半径（px），自元素边界向外扩展，越大越远距离感应 |
| disabled | `boolean` | `false` | 禁用磁吸：停止牵引并平滑归位原点，DOM 结构不变 |
| magnetStrength | `number` | `2` | 吸力除数，位移=指针到中心距离/此值，越小吸力越强；建议 1–6 |
| activeTransition | `string` | `"transform 0.3s ease-out"` | 吸附激活态过渡（跟随指针时） |
| inactiveTransition | `string` | `"transform 0.5s ease-in-out"` | 失活态过渡（离开归位时） |
| wrapperClassName | `string` | — | 透传外层包裹 div（定位/尺寸）额外 className |
| innerClassName | `string` | — | 透传内层位移 div（承载 transform）额外 className |
| style | `CSSProperties` | — | 透传外层包裹 div 内联样式 |

> 另继承 `Omit<HTMLAttributes<HTMLDivElement>, "children">` 的所有标准 div 属性。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 被磁吸的内容（按钮、图标、卡片等） |

## 示例
```tsx
<Magnet padding={100} magnetStrength={2}>
  <button className="rounded-full bg-primary px-6 py-3 text-primary-foreground">
    把我拉过来
  </button>
</Magnet>
```

强吸力（几乎贴住指针）：
```tsx
<Magnet padding={140} magnetStrength={1}>
  <Pill label="强磁吸" />
</Magnet>
```

## 禁忌 / 坑

- `magnetStrength` 是除数不是乘数：值越小吸力越强（=1 几乎贴住指针），别理解反了。
- reduced-motion 下位移会被钳位，交互降级，不要依赖磁吸做关键功能。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# MagnetLines

> 指针驱动的磁力线网格 · rows×columns 细线段实时朝向鼠标(acos 反三角求角) + token 线色(零依赖·reduced-motion 静止) · decoration/overlay-fx · #animated

## 何时用

铺一片细线段网格，每根线段实时转向指向鼠标，做磁场/罗盘式的极简交互装饰。它是纯 CSS transform 的轻量方案（无 WebGL），相比 [GhostCursor](https://hulianui.haloritual.com/components/ghost-cursor) / [LaserFlow](https://hulianui.haloritual.com/components/laser-flow) 这类 WebGL 重背景更轻、更适合做小块图形点缀。容器为正方形，默认占 `80vmin`。

## 导入
```ts
import { MagnetLines } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| rows | `number` | `9` | 网格行数，rows×columns 即线段总数 |
| columns | `number` | `9` | 网格列数 |
| containerSize | `string` | `"80vmin"` | 容器尺寸（任意 CSS 长度），正方形，线段在其中等分铺开 |
| lineColor | `string` | `var(--color-foreground)` | 线段颜色，吃明暗主题；任意 CSS 颜色串均可 |
| lineWidth | `string` | `"1vmin"` | 单条线段宽度（任意 CSS 长度） |
| lineHeight | `string` | `"6vmin"` | 单条线段高度（任意 CSS 长度） |
| baseAngle | `number` | `-10` | 初始静止角度（度）；指针未动或 reduced-motion 时保持该角 |
| className | `string` | — | 透传根容器额外 className |
| style | `CSSProperties` | — | 透传根容器内联样式（与内部计算的 grid 样式合并，后写覆盖） |

## 示例
```tsx
<MagnetLines containerSize="16rem" lineColor="var(--color-foreground)" />
```

细密网格 + 品牌色：
```tsx
<MagnetLines
  rows={13}
  columns={13}
  containerSize="16rem"
  lineWidth="0.4rem"
  lineHeight="2rem"
  lineColor="var(--color-chart-1)"
/>
```

## 禁忌 / 坑

- `rows × columns` 即 DOM 线段节点数（默认 81 个），过大网格会拖累渲染，按需控制密度。
- reduced-motion 下所有线段固定在 `baseAngle`，不再跟随鼠标。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# MetaBalls

> 一组黏液球（metaball）公转游走、距离平方反比势场叠加 smoothstep 等值面产生融合/分裂的有机黏连背景 · 主体球与跟随鼠标的光标球交界处混色 + 自动巡游兜底(ogl·token 配色·reduced-motion 静态渐变球团 fallback) · decoration/overlay-fx · #animated

## 何时用

需要一块「有机液态」的发光装饰背景（hero、卡片底、加载页），球体会融合分裂、跟随鼠标。要的是边缘擦亮/折射光感选 [ShapeBlur](https://hulianui.haloritual.com/components/shape-blur)、Lens；要的是规整环绕的图标轨道选 [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)；MetaBalls 是其中最「流体黏连」的一档，放在深色底上发光最佳。

## 导入
```ts
import { MetaBalls } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `"var(--color-chart-1)"` | 主体小球聚合时的填充色。喂 token 必须带 `--color-` 前缀 |
| cursorBallColor | `string` | `"var(--color-chart-4)"` | 光标球颜色，与 color 在交界处混合 |
| speed | `number` | `0.3` | 公转速度倍率，越大游走越快 |
| enableMouseInteraction | `boolean` | `true` | 启用鼠标交互；关闭后光标球自动椭圆巡游 |
| hoverSmoothness | `number` | `0.05` | 光标球插值平滑系数（0–1），越小越拖尾、越大越跟手 |
| animationSize | `number` | `30` | 观察尺度，越大视野越广、小球越小越散 |
| ballCount | `number` | `15` | 主体小球数量（1–50，超出夹取到 50） |
| clumpFactor | `number` | `1` | 聚拢因子，越大轨道越外扩松散，越小越抱团 |
| cursorBallSize | `number` | `3` | 光标球半径（着色器单位） |
| enableTransparency | `boolean` | `true` | 透明背景；false 时填黑底 |
| className | `string` | — | 透传到 canvas / fallback 容器 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的自定义静态备用内容 |

## 示例
```tsx
// 深色底 + 默认参数（容器需 relative + overflow-hidden）
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <MetaBalls className="absolute inset-0" />
</div>
```
```tsx
// 暖色混调 + 自动巡游（关闭鼠标交互，适合纯背景）
<MetaBalls
  className="absolute inset-0"
  color="var(--color-chart-3)"
  cursorBallColor="var(--color-chart-5)"
  enableMouseInteraction={false}
  speed={0.25}
/>
```

## 禁忌 / 坑

- 喂 token 色给 `color` / `cursorBallColor` 必须带 `--color-` 前缀（`var(--color-chart-1)`），裸 `var(--primary)` 在本 Tailwind v4 体系下 shader 解析不到会变黑。见 [[hulian-token-color-var-needs-color-prefix]]。
- WebGL/ogl 组件，仅客户端渲染；放在 RSC 页面里注意它是 `"use client"`。StrictMode 双挂载下 canvas context 复用可能毒化，参考 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 父容器需 `relative` + `overflow-hidden`，组件用 `absolute inset-0` 铺满；底色建议深色才看得清发光黏球。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# MetallicPaint

> 液态金属漆面 WebGL 装饰背景 · fbm 液态扰动 + RGB 折射色散 + 多段金属条纹梯度(ogl·token·reduced-motion 降级) · decoration/overlay-fx · #animated

## 何时用

需要一块流动的「液态金属/水银漆面」背景（hero、品牌页、卡片底），自带折射虹彩与条纹梯度。要的是规整的发光描边选 [BorderBeam](https://hulianui.haloritual.com/components/border-beam) / [ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要的是融合分裂的黏液球选 [MetaBalls](https://hulianui.haloritual.com/components/meta-balls)；MetallicPaint 偏「整面金属质感铺底」，常叠一层居中文案。

## 导入
```ts
import { MetallicPaint } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| lightColor | `string` | `var(--color-chart-1)` | 高光金属色（亮部峰值）。CSS 颜色或带 `--color-` 前缀的 token |
| darkColor | `string` | `var(--color-foreground)` | 暗部金属色（低谷阴影） |
| speed | `number` | `1` | 金属流动速度因子，0≈静止（仍有极慢漂移） |
| scale | `number` | `1` | 纹理缩放，越大纹路越密 |
| refraction | `number` | `1` | 折射强度，越大 RGB 错位色散/虹彩越明显 |
| liquid | `number` | `0.6` | 液态扰动强度，越大越像流动水银，0=平整镜面 |
| blur | `number` | `0.6` | 色带边缘模糊，建议 0.2–1.5；过小条纹生硬、过大金属感消散 |
| angle | `number` | `-45` | 整体旋转角度（度），改变光线入射方向 |
| className | `string` | — | 透传到容器（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代（默认 token 金属渐变 div） |

## 示例
```tsx
// 默认金属漆 + 居中文案（容器需 relative + overflow-hidden）
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.12 0.01 255)" }}>
  <MetallicPaint className="opacity-95" />
  <div className="relative z-10 flex h-full items-center justify-center text-sm text-white/70">
    Metallic Paint
  </div>
</div>
```
```tsx
// 强折射虹彩
<MetallicPaint refraction={1.8} lightColor="var(--color-chart-2)" className="opacity-95" />
```

## 禁忌 / 坑

- token 色喂 `lightColor` / `darkColor` 必须带 `--color-` 前缀，裸 `var(--primary)` shader 解析不到。见 [[hulian-token-color-var-needs-color-prefix]]。
- WebGL/ogl 组件，`"use client"` 仅客户端渲染；StrictMode 双挂载下 canvas context 复用风险见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 父容器需 `overflow-hidden` 裁掉超出的金属纹；叠文案记得给文字层 `relative z-10`。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Meteors

> 流星雨 · 随机斜落拖尾(客户端生成) + currentColor · decoration/backdrop · #animated

## 何时用

需要在 Hero / 卡片 / 空状态等容器内叠一层斜落流星点缀气氛时用。它是轻量的纯 DOM 动画（无 canvas/WebGL），适合做前景小装饰；若要铺满整屏的连续动态背景，选 [Aurora](https://hulianui.haloritual.com/components/aurora) / [WavyBackground](https://hulianui.haloritual.com/components/wavy-background)；若要规则的几何底纹（点阵/网格），选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。

## 导入
```ts
import { Meteors } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| number | number | 20 | 流星数量 |
| minDelay | number | 0.2 | 单颗动画启动最小延迟（秒） |
| maxDelay | number | 1.2 | 单颗动画启动最大延迟（秒） |
| minDuration | number | 2 | 单颗下落最短时长（秒） |
| maxDuration | number | 10 | 单颗下落最长时长（秒） |
| angle | number | 215 | 下落角度（度） |
| className | string | — | 透传到每颗流星 span 的额外类（流星本身用 currentColor，可借此调色） |

## 示例
```tsx
// 父容器须 relative + overflow-hidden 裁剪溢出的流星
<div className="relative overflow-hidden rounded-xl border">
  <Meteors number={20} />
  <div className="grid h-48 place-items-center text-sm text-muted">Meteors</div>
</div>
```

## 禁忌 / 坑

- 流星位置/延迟在客户端随机生成，组件必须在客户端渲染，且首帧前位置未定（SSR 与首屏会有一帧差异），勿用于对首屏像素稳定性敏感处。
- 流星颜色取 `currentColor`，靠父级 `text-*` 或 `className` 着色，不传颜色 prop。
- 父容器需 `position: relative` + `overflow-hidden`，否则流星会溢出到容器外。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# ModelViewer

> 交互式 3D 模型查看舞台 · 拖拽旋转(惯性) + 鼠标视差 + 悬停倾斜 + 自动旋转 + 接触阴影(零依赖 CSS 3D · RAF · reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要把任意 React 节点（产品图/卡片/SVG/emoji）放进一个可拖拽旋转、带惯性/视差/悬停倾斜/接触阴影的 3D 舞台时用——瑚琏化用纯 CSS 3D 替代了 three.js，不加载真实 GLTF/FBX 模型。要做局部放大镜用 [Lens](https://hulianui.haloritual.com/components/lens)；要做眩光悬停用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。ModelViewer 是「给 children 施加 3D 交互的舞台」。

## 导入
```ts
import { ModelViewer } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| width | `number ｜ string` | `"100%"` | 舞台宽度，由外层容器约束 |
| height | `number ｜ string` | `360` | 舞台高度 |
| defaultRotationY | `number` | `-20` | 初始偏航角（绕 Y，°），拖拽时累加 |
| defaultRotationX | `number` | `12` | 初始俯仰角（绕 X，°），拖拽时累加 |
| perspective | `number` | `1000` | 透视景深 px，越小透视越夸张 |
| enableManualRotation | `boolean` | `true` | 允许鼠标拖拽旋转，松手带惯性缓停 |
| enableMouseParallax | `boolean` | `true` | 鼠标视差（指针移动时模型轻微位移） |
| enableHoverRotation | `boolean` | `true` | 悬停倾斜（模型朝指针方向倾斜） |
| autoRotate | `boolean` | `false` | 自动绕 Y 轴匀速旋转，与手动拖拽叠加 |
| autoRotateSpeed | `number` | `24` | 自转角速度（°/s），仅 `autoRotate` 时生效 |
| showResetButton | `boolean` | `true` | 右上角「重置视角」工具按钮 |
| showContactShadow | `boolean` | `true` | 底部柔和接触阴影 |
| className | `string` | — | 透传根容器 className |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 放进 3D 舞台中央的「模型」，由组件统一施加旋转/视差/倾斜 |

## 示例

```tsx
// 默认：拖拽旋转 + 视差 + 悬停倾斜 + 接触阴影
<ModelViewer>
  <YourModel />
</ModelViewer>

// 自动旋转展台
<ModelViewer autoRotate autoRotateSpeed={24} showContactShadow>
  <ProductCard />
</ModelViewer>
```

## 禁忌 / 坑

- 这是 CSS 3D 舞台，不渲染真实 GLTF/FBX/OBJ；`children` 应是平面/伪 3D 内容，深度感来自外层 `preserve-3d` 子层自行用 `translateZ`。
- 客户端组件（拖拽 + RAF 惯性循环），SSR 下静止；reduced-motion 下关惯性/自转等动画。
- 多层立方面等需 `transform-style: preserve-3d` 的内容须自己在 children 里设置，组件只负责整体旋转/视差容器。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Orb

> 指针交互光球 · WebGL/ogl 发光能量球 + hover 增亮/旋转 + hue 色相 + reduced-motion 径向渐变球 · decoration/backdrop · #animated #webgl

## 何时用

需要一个聚焦视线的发光能量球做 hero/卡片/空状态焦点元素，且希望随指针 hover 产生增亮、扭曲、旋转反馈时用。它是「焦点元素」——canvas 填满外层方形容器，尺寸由容器决定。若要的是铺满整面的流动金属背景层用 [LiquidChrome](https://hulianui.haloritual.com/components/liquid-chrome)；只要静态点阵/网格底纹用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。

## 导入
```ts
import { Orb } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| hue | `number` | `0` | 色相旋转（度）。0 = 原始蓝紫；正值顺时针旋转 YIQ 色相 |
| hoverIntensity | `number` | `0.2` | 悬停扭曲强度（0–1），越大变形越明显 |
| rotateOnHover | `boolean` | `true` | 悬停时是否自动旋转光球 |
| forceHoverState | `boolean` | `false` | 强制保持悬停激活态（演示 / 截图场景用） |
| className | `string` | — | 透传到 canvas（正常）或 fallback div（降级）的 className |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态备用内容（置于径向渐变球中央） |

## 示例

```tsx
// Orb 是焦点元素，需放进决定其尺寸的方形容器
<div className="relative overflow-hidden rounded-2xl" style={{ width: 280, height: 280 }}>
  <Orb />
</div>
```

```tsx
// 换色相 + 强制悬停态（适合截图）
<div className="relative" style={{ width: 280, height: 280 }}>
  <Orb hue={120} forceHoverState hoverIntensity={0.4} />
</div>
```

## 禁忌 / 坑

- WebGL 组件，必须在客户端渲染；SSR 环境下首屏走 reduced-motion / 无 WebGL 的径向渐变 fallback，需保证 `fallback` 或默认渐变球在服务端可见。
- cleanup 时不要主动调 `loseContext` 毒化 canvas，否则 React StrictMode 双挂载复用同一 canvas 会直接崩、空白——参见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]，正确做法是每次挂载新建 canvas。
- canvas 填满外层容器，外层必须有确定的宽高（方形最佳），否则光球塌缩不可见。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# OrbitImages

> 沿轨道环绕流转的子项编排组件 · 9 种形状预设(椭圆/圆/方/三角/星/心/无穷/波浪+custom path)+等距铺满/鱼贯出发+可倾斜+中心叠层(纯 CSS offset-path·零依赖·RSC 安全·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要把一组头像/图标/Logo 沿某种形状轨道环绕流转（生态墙、合作伙伴、技术栈展示），且要任意形状（星/心/无穷）和中心叠层。要的是简单同心圆轨道的图标公转选 [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)；OrbitImages 形状更丰富（offset-path 驱动）、可承载任意 ReactNode 子项、零依赖 RSC 安全。

## 导入
```ts
import { OrbitImages } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| shape | `"ellipse"｜"circle"｜"square"｜"rectangle"｜"triangle"｜"star"｜"heart"｜"infinity"｜"wave"｜"custom"` | `"ellipse"` | 轨道形状预设，custom 走 customPath |
| customPath | `string` | — | shape="custom" 时的 SVG path d（坐标基于 baseWidth 方形画布） |
| baseWidth | `number` | `1400` | 设计画布边长（px·方形 viewBox），只影响路径几何比例 |
| radiusX | `number` | `700` | 椭圆/矩形/无穷/波浪 的横向半径（px·基于 baseWidth） |
| radiusY | `number` | `170` | 椭圆/矩形/无穷/波浪 的纵向半径 |
| radius | `number` | `300` | 圆/方/三角/星/心 的半径 |
| starPoints | `number` | `5` | star 形状的角数 |
| starInnerRatio | `number` | `0.5` | star 内外半径比（0–1），越小星芒越尖 |
| rotation | `number` | `-8` | 轨道倾斜角（deg），子项反向自转保持正立 |
| duration | `number` | `40` | 跑完一圈时长（秒），越大越慢 |
| itemSize | `number` | `64` | 单个子项边长（px·CSS 像素） |
| direction | `"normal"｜"reverse"` | `"normal"` | 流转方向 |
| fill | `boolean` | `true` | true 等距铺满轨道，false 从同点鱼贯出发 |
| showPath | `boolean` | `false` | 描出轨道路径（调试/装饰） |
| pathColor | `string` | `"var(--color-border)"` | 轨道描边颜色 |
| pathWidth | `number` | `2` | 轨道描边宽度（px·基于 baseWidth） |
| className | `string` | — | 透传到根容器 |
| style | `CSSProperties` | — | 透传到根容器（默认 1:1 自适应铺满父宽） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| items * | `ReactNode[]` | 沿轨道环绕的子项（img/图标/头像/卡片皆可），必填 |
| centerContent | `ReactNode` | 居中内容（Logo/标题），不随轨道旋转 |

## 示例
```tsx
// 椭圆轨道 · 等距铺满 · 描出路径 · 中心标题
<OrbitImages
  items={chips}
  shape="ellipse"
  duration={24}
  itemSize={48}
  showPath
  centerContent={<span className="text-sm font-semibold">瑚琏</span>}
/>
```
```tsx
// 圆形轨道
<OrbitImages items={chips} shape="circle" radius={260} duration={30} itemSize={44} />
```

## 禁忌 / 坑

- 纯 CSS `offset-path` 驱动，零依赖 RSC 安全；但 `offset-path` 在老浏览器/部分 WebKit 上有兼容差异，关键场景需验真机。
- `radiusX/Y/radius/baseWidth` 都是 baseWidth 坐标系内的设计像素，不是最终屏幕像素——容器靠 CSS 缩放铺满父宽，调几何比例改这些、调实际大小改父容器尺寸。
- `pathColor` 给 token 时用 `var(--color-border)` 这类带 `--color-` 前缀的语义色，避免裸 var 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# OrbitingCircles

> 轨道环绕 · 子元素沿圆周匀速公转 + 自身反旋正立(纯 CSS·RSC) · decoration/overlay-fx · #animated

## 何时用

想让一组图标/头像沿圆形轨道围着中心匀速公转（技术栈环绕、集成生态、品牌 logo 群）时用。子元素按数量均匀分布到圆周、自身反旋保持正立；纯 CSS、可在 RSC 渲染。可叠多个不同 `radius`/`duration` 做多层轨道。要把两个具体节点用流光连起来用 [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam)。

## 导入
```ts
import { OrbitingCircles } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| radius | `number` | — | 轨道半径 px |
| duration | `number` | — | 一圈时长 s |
| reverse | `boolean` | `false` | 反向旋转 |
| iconSize | `number` | — | 子元素方框尺寸 px |
| showPath | `boolean` | — | 是否画出轨道虚线圆环 |
| className | `string` | — | 透传 className |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 环绕的子元素（图标等），按数量均匀分布到圆周 |

## 示例

```tsx
// 双层轨道：内外层反向旋转
<div className="relative flex size-[340px] items-center justify-center">
  <span className="text-sm font-medium text-muted">瑚琏</span>
  <OrbitingCircles radius={140} duration={20}>
    <Icon /><Icon /><Icon /><Icon />
  </OrbitingCircles>
  <OrbitingCircles radius={80} duration={14} reverse iconSize={32}>
    <Icon /><Icon />
  </OrbitingCircles>
</div>
```

## 禁忌 / 坑

- 放在居中的 `relative` 容器内，且容器尺寸需 ≥ 2×radius，否则轨道被裁。
- 纯 CSS 实现，可在 RSC 直接用，无需 `"use client"`。
- reduced-motion 偏好下公转会被弱化/停止，不要把它当唯一的信息载体。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# Particles

> 交互粒子场 · canvas 星尘漂浮 + 鼠标排斥位移 + DPR 自适应 + 颜色吃主题前景 token(明暗跟随) · decoration/backdrop · #animated

## 何时用

需要随鼠标互动的星尘/粒子背景（科技感 Hero、登录页）时用。基于 canvas，有鼠标排斥与漂移交互，比纯 CSS 的 [Aurora](https://hulianui.haloritual.com/components/aurora) 更动态但开销更高；若只要静态彩色渐变背景，用 Aurora 即可；若要规则点阵/网格底纹，用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。

## 导入
```ts
import { Particles } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| quantity | number | 100 | 粒子数量 |
| staticity | number | 50 | 静止系数，越大越不跟鼠标（位移 = mouseOffset / (staticity/magnetism)） |
| ease | number | 50 | 缓动系数，越大越迟钝（translateX += (target-current)/ease） |
| size | number | 0.4 | 粒子基础半径（px），最终在 [size, size+2] 随机 |
| color | string | `--color-foreground` | 粒子颜色。不传则读主题 token 并随 data-theme 切换；传入接受 `#rrggbb`/`#rgb`/`rgb(r,g,b)` |
| vx | number | 0 | X 轴常量漂移速度（px/帧） |
| vy | number | 0 | Y 轴常量漂移速度（px/帧） |
| refresh | boolean \| number \| string | — | 刷新信号——值变化时强制重绘粒子（等价 MagicUI refresh） |
| className | string | — | 透传到容器 div |

## 示例
```tsx
// 主题色粒子，自动跟随明暗
<div className="relative h-48 overflow-hidden rounded-xl border">
  <Particles quantity={120} />
</div>
```
```tsx
// 指定颜色 + 慢速高静止（不太跟鼠标）
<Particles quantity={80} staticity={80} ease={80} color="#6366f1" />
```

## 禁忌 / 坑

- canvas 颜色 prop 只接受 `#rrggbb`/`#rgb`/`rgb()` 解析格式，**不能直接传 `var(--token)` 或 oklch 字符串**——若要主题色，不传 `color` 让它内部读 `--color-foreground`，或自行先解析成 rgb 再传（参见 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]）。
- 基于 canvas，须客户端渲染；父容器需 `relative` + `overflow-hidden`。
- 数量过大（quantity 数百以上）逐帧重绘有性能成本，背景层酌情控制。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# PixelBlast

> 抖动点阵翻涌的 WebGL 背景 · FBM 噪声 + 8×8 Bayer 有序抖动量化成方块/圆/三角/菱形像素 + 四周渐隐（ogl·token·reduced-motion 降级静态点阵） · decoration/backdrop · #animated #webgl

## 何时用

需要一层「复古点阵 / 网点印刷」质感的氛围背景时用它，自带四周渐隐便于叠内容。要静态规则点阵选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)，要 8-bit 复古网格透视选 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)，要扫光聚焦选 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；本组件是噪声驱动的动态点阵，有抖动颗粒感和翻涌运动。

## 导入
```ts
import { PixelBlast, pixelBlastShowcase } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"square" \| "circle" \| "triangle" \| "diamond"` | `"square"` | 像素单元形状：方块（锐利复古）/ 圆点（网点印刷感）/ 三角（织纹）/ 菱形（菱形网点） |
| pixelSize | `number` | `4` | 单个像素方块边长（CSS px）；越小越密越细腻。建议 2–12 |
| color | `string` | `--color-primary` | 像素主色，CSS 颜色串；默认取 primary token 明暗自适应 |
| patternScale | `number` | `2` | 噪声纹理缩放；越大斑块越细碎闪烁越密。建议 0.5–6 |
| patternDensity | `number` | `1` | 像素填充密度；越大亮起像素越多越「满」。建议 0.4–1.6 |
| pixelSizeJitter | `number` | `0` | 每个方块尺寸的随机抖动幅度 0–1；越大越参差颗粒感越强 |
| speed | `number` | `0.5` | 动画速度因子；0=静止画面（仍渲一帧静态点阵） |
| edgeFade | `number` | `0.5` | 四周渐隐宽度 0–1（相对短边）；0=硬边铺满，越大四角越柔和 |
| className | `string` | — | 透传到根容器 div（或 reduced-motion 兜底 div） |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认 primary token radial-gradient 点阵（CSS mask 模拟网点） |

## 示例

```tsx
// 默认：深底上 primary token 方块点阵（父容器须 relative）
<div className="relative h-64 overflow-hidden rounded-xl">
  <PixelBlast />
  <div className="relative z-10 flex h-full items-center justify-center">
    <p className="text-2xl font-bold text-white/90">PixelBlast</p>
  </div>
</div>
```

```tsx
// 圆点网点印刷感 + 加大像素
<PixelBlast variant="circle" pixelSize={6} />
```

## 禁忌 / 坑

- 组件自带 `absolute inset-0 z-0`，**父容器必须 `relative`，叠加内容用 `relative z-10`**，否则盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback。
- `color` 传 `var(--color-…)` 时经离屏 canvas 解析，**须带 `--color-` 前缀**，裸 `var(--primary)` 解析失败 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到翻涌 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# PixelSnow

> 像素化体素雪场 WebGL 背景 · 光线步进逐格哈希生雪 + 景深淡出 · 方块/圆点/六臂雪花三变体（ogl 去 three.js·token 着色·reduced-motion 静态点阵降级） · decoration/backdrop · #animated #webgl

## 何时用

需要一层「飘雪」氛围背景（节日页、冬季活动、登录页）时用它，自带景深纵深感与明暗自适应取色。要规则点阵选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)，要通用复古点阵翻涌选 [PixelBlast](https://hulianui.haloritual.com/components/pixel-blast)；本组件专做体素雪场，有飘落方向、密度和层次纵深。

## 导入
```ts
import { PixelSnow } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variant | `"square" \| "round" \| "snowflake"` | `"square"` | 雪花形状：方块像素 / 圆点 / 六臂雪花 |
| color | `string` | 自适应（`--color-foreground`，撞色时取反） | 雪花主色；默认按身后底色亮度自适应取色，保证深底亮雪、浅底暗雪 |
| flakeSize | `number` | `0.01` | 雪花基准尺寸（屏幕空间比例）；越大越粗 |
| minFlakeSize | `number` | `1.25` | 远处雪花最小投影尺寸，防止亚像素消失 |
| pixelResolution | `number` | `200` | 像素化分辨率（横向切多少「大像素」）；越小马赛克越大越复古 |
| speed | `number` | `1.25` | 飘落速度因子；越大穿越视野越快 |
| depthFade | `number` | `8` | 景深淡出强度；越大远雪衰减越快纵深越强 |
| farPlane | `number` | `20` | 光线步进最远裁剪距离；越大可见层数越多（性能成本越高） |
| brightness | `number` | `1` | 整体亮度倍率 |
| gamma | `number` | `0.4545` | 伽马校正指数（≈1/2.2 sRGB 近似） |
| density | `number` | `0.3` | 雪花密度（每格出雪概率阈值）；越大越密。建议 0.05–0.6 |
| direction | `number` | `125` | 风向角度（度），决定横向漂移方向 |
| className | `string` | — | 透传到根容器（或 reduced-motion fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认白点 + difference 混合静态点阵雪 |

## 示例

```tsx
// 默认：方块像素雪（父容器须 relative + overflow-hidden）
<div className="relative h-56 overflow-hidden rounded-xl">
  <PixelSnow />
</div>
```

```tsx
// 自定义冷蓝色 + 慢速壁纸，内容叠更高 z
<div className="relative h-56 overflow-hidden rounded-xl">
  <PixelSnow color="oklch(0.85 0.08 230)" speed={0.7} density={0.3} />
  <div className="relative z-10 flex h-full items-center justify-center text-white">瑚琏组件库</div>
</div>
```

## 禁忌 / 坑

- 组件满铺画布，**父容器须 `relative`，叠加内容用 `relative z-10`**，否则盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- `color` 缺省会按身后实际底色自适应取色，但若把组件放进与全局主题相反的容器（如亮色主题下塞深色盒子），自适应是按 token 推断的——撞色时显式传 `color` 更稳。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到飘落 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# PixelTrail

> 鼠标划过点亮背后的像素网格、拖尾随时间淡灭的颗粒余晖背景 · 自维护 CPU 拖尾缓冲 + ogl data texture 着色 + 可选 gooey 液态融合(ogl·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要一块「鼠标划过点亮像素格、余晖淡灭」的交互背景（hero、404、空状态铺底），可切硬边像素或 gooey 液态团块。要的是流体溅彩跟随光标选 [SplashCursor](https://hulianui.haloritual.com/components/splash-cursor)；要的是弹性飘带跟随选 [Ribbons](https://hulianui.haloritual.com/components/ribbons)；PixelTrail 是其中「复古像素颗粒感」的一档。

## 导入
```ts
import { PixelTrail } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gridSize | `number` | `40` | 横向像素格子数（纵向按比例自动推算保持方格），建议 16–120 |
| trailSize | `number` | `0.1` | 拖尾影响半径（占容器短边比例 0–1），越大拖尾越粗 |
| maxAge | `number` | `320` | 单格点亮后存活时长（ms），越大余晖越久 |
| color | `string` | `var(--color-chart-1)` | 像素点颜色，token 必须带 `--color-` 前缀 |
| gooey | `boolean` | `false` | 启用黏液滤镜：相邻点融合成液态团块而非硬边方格 |
| gooeyStrength | `number` | `8` | gooey 融合强度（高斯模糊半径 px），仅 gooey=true 生效 |
| className | `string` | — | 透传到根容器（默认 block h-full w-full，由外层控尺寸） |
| style | `CSSProperties` | — | 透传到根容器 |

## 示例
```tsx
// 默认像素拖尾（容器需 relative + overflow-hidden，进区域移动鼠标点亮）
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <PixelTrail className="absolute inset-0" />
</div>
```
```tsx
// gooey 黏液融合 + 自定义色
<PixelTrail gridSize={48} trailSize={0.14} gooey gooeyStrength={9}
  color="var(--color-chart-1)" className="absolute inset-0" />
```

## 禁忌 / 坑

- `color` 喂 token 必须带 `--color-` 前缀，裸 `var(--primary)` shader 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- WebGL/ogl 组件，仅客户端渲染；StrictMode 双挂载 canvas context 复用风险见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 父容器需 `relative` + `overflow-hidden`，组件铺 `absolute inset-0`；深色底上像素余晖最清晰。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# PixelTransition

> 像素马赛克转场卡片：双层内容叠放，悬停/聚焦/点击触发一幕随机散入再散出的像素幕布完成切换 · 自定网格密度/过场时长/只进不退 + token 像素色（去 gsap·motion 减包驱动·reduced-motion 直切） · decoration/overlay-fx · #animated

## 何时用

需要两张内容（图/文案/封面）以「像素马赛克幕布」交互切换的卡片（作品集封面 hover 揭示、CTA 卡）。它是承载真实双层内容的交互件，不是纯背景——要纯背景铺底选 [PixelTrail](https://hulianui.haloritual.com/components/pixel-trail)；要鼠标擦亮高光选 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。

## 导入
```ts
import { PixelTransition } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gridSize | `number` | `7` | 像素网格边长（总块数 gridSize²），越大越细腻越软 |
| pixelColor | `string` | `"var(--color-foreground)"` | 像素块填色，建议 token 变量或 `currentColor` |
| animationStepDuration | `number` | `0.3` | 单次过场时长（秒），散入+散出各占一半，中点切换 |
| once | `boolean` | `false` | 只进不退：激活后停在 secondContent，离开/失焦不返回 |
| aspectRatio | `string` | `"4 / 3"` | 容器宽高比（CSS aspect-ratio 写法，如 `"1 / 1"`、`"16 / 9"`） |
| className | `string` | — | 透传到根元素，cn 合并 |
| style | `CSSProperties` | — | 透传到根元素 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| firstContent * | `ReactNode` | 默认（静止）态内容，通常一张图/一段文案，必填 |
| secondContent * | `ReactNode` | 激活态内容，悬停/聚焦/点击后透过像素幕布显露，必填 |

## 示例
```tsx
// 悬停 / 聚焦触发切换
<PixelTransition
  firstContent={<Face label="瑚琏" />}
  secondContent={<Face label="组件库" />}
/>
```
```tsx
// 只进不退（once）· 正方形
<PixelTransition
  once
  aspectRatio="1 / 1"
  firstContent={<Face label="点我" />}
  secondContent={<Face label="✓" />}
/>
```

## 禁忌 / 坑

- `firstContent` / `secondContent` 为必填双层内容，两层都要能 100% 撑满（用 `h-full w-full`），否则像素幕布揭示后露出空白。
- `pixelColor` 给 token 用带 `--color-` 前缀的变量（`var(--color-foreground)`），裸 var 在 Tailwind v4 下不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- motion 驱动（非 gsap）；reduced-motion 下直接硬切，无散入散出动画。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Plasma

> 等离子流动 WebGL 背景 · 60 步光线步进 shader + 鼠标扰动 + forward/reverse/pingpong 三向(ogl·token 染色·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要一层「等离子能量流动 / 中心发光」氛围背景时用它，单色染色简洁、运动方向可控。要双丝带交织的复杂波带选 [PlasmaWave](https://hulianui.haloritual.com/components/plasma-wave)，要液态色团翻涌选 [LiquidEther](https://hulianui.haloritual.com/components/liquid-ether)，要点阵几何选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；本组件是最克制的单色等离子流，适合做品牌强调色铺底。

## 导入
```ts
import { Plasma } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `--color-chart-1` | 等离子主色，CSS 颜色串；默认取 chart token；传 `null`/解析失败退回 shader 原生彩色（不染色） |
| speed | `number` | `1` | 流动速度因子（内部乘 0.4 喂 shader 与原版对齐）；越大越快 |
| direction | `"forward" \| "reverse" \| "pingpong"` | `"forward"` | 流动方向：向上涌 / 反向下沉 / 正反平滑往复（smoothstep 缓动） |
| scale | `number` | `1` | 视场缩放；越大画面越「拉近」纹理越大，越小越密 |
| opacity | `number` | `1` | 整体不透明度 0–1（叠在 shader alpha 上）；作柔和背景时压暗用 |
| mouseInteractive | `boolean` | `true` | 指针轻微扭曲等离子流场；关闭后纯自动且不挂 mousemove 监听 |
| className | `string` | — | 透传到 root（canvas 容器或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认 chart token 径向渐变（保留中心发光观感） |

## 示例

```tsx
// 默认：主题色等离子流（父容器须 relative + overflow-hidden）
<div className="relative h-56 overflow-hidden rounded-xl">
  <Plasma />
</div>
```

```tsx
// 压暗背景 + 关交互，内容叠更高 z
<div className="relative h-56 overflow-hidden rounded-xl">
  <Plasma opacity={0.5} mouseInteractive={false} scale={1.3} />
  <div className="relative z-10 flex h-full items-center justify-center text-white">瑚琏组件库</div>
</div>
```

## 禁忌 / 坑

- 组件满铺画布，**父容器须 `relative` + `overflow-hidden`，叠加内容用 `relative z-10`**，否则盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback。
- `color` 传 `var(--color-…)` 时经离屏 canvas 解析，**须带 `--color-` 前缀**，裸 `var(--primary)` 解析失败会退回原生彩色而非你想要的主题色 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到流动 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# PlasmaWave

> 等离子波 WebGL 背景 · raymarch 双丝带交织流动 + 双色权重混合(ogl·主题感知 chart token·reduced-motion 静态渐变降级) · decoration/backdrop · #animated #webgl

## 何时用

需要一层「双色丝带交织流动」的高级氛围背景（Hero、品牌页）时用它，双流速 + 弯曲 + 旋转可调出丰富波带构图。要单色克制的等离子流选 [Plasma](https://hulianui.haloritual.com/components/plasma)，要液态色团翻涌选 [LiquidEther](https://hulianui.haloritual.com/components/liquid-ether)，要点阵几何选 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)；本组件是双丝带交织，节奏更复杂、视觉更绵密。

## 导入
```ts
import { PlasmaWave } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `["var(--color-chart-1)","var(--color-chart-2)"]` | 双色，任意 CSS 颜色串；只取前两色（uColor1/uColor2），多传忽略；随明暗主题切换 |
| xOffset | `number` | `0` | 丝带水平偏移（设备像素），让波纹焦点离开正中 |
| yOffset | `number` | `0` | 丝带垂直偏移（设备像素） |
| rotationDeg | `number` | `0` | 整体旋转角度（度），把横向波带斜向铺排更有张力 |
| focalLength | `number` | `0.8` | 焦距（视线收束）；越大越聚拢纵深越强，越小越铺展。建议 0.4–1.6 |
| speed1 | `number` | `0.05` | 第一条丝带流速；越大越快 |
| speed2 | `number` | `0.05` | 第二条丝带流速 |
| dir2 | `number` | `1` | 第二条丝带流向（+1 同向 / -1 反向），与第一条对冲产生交织感 |
| bend1 | `number` | `1` | 第一条丝带弯曲幅度；越大起伏越夸张 |
| bend2 | `number` | `0.5` | 第二条丝带弯曲幅度 |
| className | `string` | — | 透传到 canvas 容器或 fallback div；常用于尺寸/圆角/opacity（如 `absolute inset-0 opacity-80`） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；覆盖在静态渐变之上 |

## 示例

```tsx
// 默认：chart token 双色波带（须自带 absolute inset-0 铺满 relative 父容器）
<div className="relative h-56 overflow-hidden rounded-xl">
  <PlasmaWave className="absolute inset-0" />
  <div className="absolute inset-0 flex items-center justify-center text-white/80">PlasmaWave</div>
</div>
```

```tsx
// 对冲流向 + 暖色：dir2 反向交织
<PlasmaWave
  className="absolute inset-0"
  colors={["var(--color-chart-3)", "oklch(0.72 0.22 30)"]}
  dir2={-1}
  speed1={0.1}
  bend1={1.4}
/>
```

## 禁忌 / 坑

- 与同族组件不同，PlasmaWave **不自带定位 class**，须自己传 `className="absolute inset-0"` 铺满 `relative` 父容器，叠加内容用 `absolute inset-0` / `relative z-10` [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback。
- `colors` 传 `var(--color-…)` 时经离屏 canvas 解析，**须带 `--color-` 前缀**，裸 `var(--primary)` 解析失败 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到流动 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Prism

> 棱镜分光 WebGL 背景 · ray-march 八面体 SDF 折射出彩虹体积光 + rotate/3drotate/hover 三姿态(ogl·主题色相自适应·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

需要一个「3D 棱锥分光辉光」作为视觉焦点的背景（产品 Hero、品牌主视觉）时用它，单个发光棱镜居中、构图聚焦。要从中心放射的多瓣光爆选 [PrismaticBurst](https://hulianui.haloritual.com/components/prismatic-burst)，要满铺流动纹理选 [Plasma](https://hulianui.haloritual.com/components/plasma) / [PlasmaWave](https://hulianui.haloritual.com/components/plasma-wave)；本组件是单体棱镜实体，有体积感和折射彩虹边。

## 导入
```ts
import { Prism } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| height | `number` | `3.5` | 棱锥高度（沿 Y 轴）；越大越高耸光柱越细长 |
| baseWidth | `number` | `5.5` | 棱锥底边宽度；与 height 共定胖瘦比例 |
| animationType | `"rotate" \| "3drotate" \| "hover"` | `"rotate"` | rotate=XZ 正弦呼吸摆动（无整体旋转）/ 3drotate=三轴伪随机旋转 / hover=跟随全局指针倾斜（带惯性） |
| glow | `number` | `1` | 体积光辉强度；0=无辉光（暗轮廓） |
| offset | `{ x?: number; y?: number }` | `{ x: 0, y: 0 }` | 棱锥从画面正中平移（CSS 像素），构图避让内容 |
| noise | `number` | `0.5` | 颗粒噪声强度（电影感胶片颗粒）；0=纯净无颗粒 |
| transparent | `boolean` | `true` | true 时画布 alpha 透出底色，且自动提升饱和度更通透 |
| scale | `number` | `3.6` | 棱镜整体缩放；越大占视口越多 |
| hueShift | `number` | 主题推导（`--color-chart-1`） | 色相旋转（弧度）；显式传值在自动推导基础上叠加偏移 |
| colorFrequency | `number` | `1` | 分光色彩频率；越大彩虹条纹越密，越小色带越宽 |
| hoverStrength | `number` | `2` | hover 模式下跟随强度；越大倾斜幅度越大 |
| inertia | `number` | `0.05` | hover 模式惯性系数 0–1；越小越「黏滞」缓动越久 |
| bloom | `number` | `1` | 泛光叠加；与 glow 相乘放大整体亮度 |
| timeScale | `number` | `0.5` | 时间缩放（动画整体速度）；0=冻结为静态一帧 |
| className | `string` | — | 透传到根容器（或 reduced-motion fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认 chart token 径向辉光渐变 |

## 示例

```tsx
// 默认：rotate 呼吸摆动 + 主题色相（父容器须 relative）
<div className="relative h-64 overflow-hidden rounded-xl">
  <Prism />
  <div className="relative z-10 flex h-full items-center justify-center">
    <p className="text-2xl font-bold text-white/90">Prism</p>
  </div>
</div>
```

```tsx
// hover 跟随指针 + 三维旋转
<Prism animationType="hover" hoverStrength={2.4} inertia={0.06} />
```

## 禁忌 / 坑

- 组件自带 `absolute inset-0 z-0`，**父容器须 `relative`，叠加内容用 `relative z-10`**，否则盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- `animationType="hover"` 跟随的是**全局指针**（不限于容器内），且仅此模式挂指针监听；rotate/3drotate 不响应鼠标。
- WebGL 客户端组件（`"use client"`）；SSR 阶段只渲染 fallback。
- `hueShift` 由 `--color-chart-1` 推导，主题色相经离屏 canvas 解析，**token 须带 `--color-` 前缀** [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到旋转 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# PrismaticBurst

> 棱镜光爆 WebGL 背景 · 从中心放射的体积步进光谱射线(可弯曲扭曲/N 瓣梳理/三维翻滚/hover 跟随) · 默认色带吃 --color-chart-1..5 token(明暗自适应) + 懒加载 ogl 复用 useGlCanvas(StrictMode 安全·reduced-motion 降级静态径向光爆) · decoration/backdrop · #animated #webgl

## 何时用

需要一个「从中心爆发的光谱射线」作为强视觉焦点（产品发布页、活动 Hero）时用它，放射感和色谱跨度最大。要单体棱锥分光选 [Prism](https://hulianui.haloritual.com/components/prism)，要满铺流动纹理选 [Plasma](https://hulianui.haloritual.com/components/plasma) / [PlasmaWave](https://hulianui.haloritual.com/components/plasma-wave)；本组件是中心放射光爆，可调瓣数做六芒星/星爆，叠加底图常配 `mixBlendMode`。

## 导入
```ts
import { PrismaticBurst } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| intensity | `number` | `2` | 整体亮度增益（直接乘最终颜色）；0=全黑 |
| speed | `number` | `1` | 体积步进动画速度因子；越大翻涌越快 |
| animationType | `"rotate" \| "rotate3d" \| "hover"` | `"rotate"` | rotate=单轴平面旋转（最克制）/ rotate3d=三维欧拉旋转 / hover=跟随指针倾斜 |
| colors | `string[]` | `--color-chart-1..5` | 色带（烘焙成一维渐变纹理按 march 进度采样）；任意 CSS 颜色串，默认 chart token 明暗自适应 |
| distort | `number` | `0` | 光线弯曲扭曲量 0–50（shader 内夹紧）；越大射线越像被引力透镜扭弯 |
| noiseAmount | `number` | `0` | 颗粒抖动噪声量 0–1；弱化条带感 |
| rayCount | `number` | `0` | 放射光束瓣数；0=连续光晕，>0 按角度梳理 N 条对称射线（6=六芒星） |
| offset | `{ x?: number; y?: number }` | `{ x: 0, y: 0 }` | 爆发中心相对画面中心的偏移（CSS 像素），x 正向右、y 正向下 |
| mixBlendMode | `string` | `"none"` | 透传到 canvas 的 `mix-blend-mode`；常用 "lighten" / "screen" 叠底更通透 |
| className | `string` | — | 合并到 root 容器（或 reduced 降级 div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容；默认 chart token 径向光爆渐变 |

## 示例

```tsx
// 默认：连续光晕 + token 光谱（父容器须 relative + overflow-hidden）
<div className="relative h-56 overflow-hidden rounded-xl">
  <PrismaticBurst className="opacity-90" />
  <div className="absolute inset-0 flex items-center justify-center text-white/80">PrismaticBurst</div>
</div>
```

```tsx
// 六瓣星爆 + 提亮
<PrismaticBurst rayCount={6} intensity={2.4} className="opacity-95" />
```

## 禁忌 / 坑

- 组件满铺画布，**父容器须 `relative` + `overflow-hidden`，叠加内容用 `absolute inset-0` / `relative z-10`**，否则盖住内容 [[webgl-canvas-rendered-but-invisible-negative-zindex-covered]]。
- WebGL 客户端组件（`"use client"`），ogl 懒加载、复用 useGlCanvas 对 React StrictMode 双挂载安全；SSR 阶段只渲染 fallback。
- `colors` 传 `var(--color-…)` 时经离屏 canvas 解析，**须带 `--color-` 前缀**，裸 `var(--primary)` 解析失败 [[oklch-css-var-color-must-parse-via-offscreen-canvas]]。
- headless 截图常拍到静止/空白帧（rAF 动画被饿死），真机或 Playwright 实测才能看到爆发 [[recharts-headless-screenshot-blank-clippath-animation-starved]]。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# ProgressiveBlur

> 渐进模糊 · 分层 backdrop-blur + mask 渐变(纯 CSS·RSC) · decoration/overlay-fx

## 何时用

需要把内容某一侧（图片墙、长列表、横向滚动条）逐渐模糊淡出做边缘羽化时用，常铺在滚动容器或图片上方做「渐隐遮罩」。它只做单侧渐进模糊叠层；要给边框走光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)/[ShineBorder](https://hulianui.haloritual.com/components/shine-border)，要做鼠标跟随聚光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)，要做局部放大镜用 [Lens](https://hulianui.haloritual.com/components/lens)。

## 导入
```ts
import { ProgressiveBlur } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| side | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | 模糊增强的方向，该侧最糊。 |
| layers | `number` | — | 分层数，越多过渡越平滑。 |
| blur | `number` | — | 基础模糊量(px)，逐层翻倍。 |
| className | `string` | — | 透传到根叠层。 |

## 示例
```tsx
<div className="relative overflow-hidden">
  {/* content */}
  <ProgressiveBlur side="bottom" />
</div>
```

## 禁忌 / 坑

- 父容器必须 `position: relative` 且 `overflow-hidden`，叠层靠绝对定位铺满该侧，否则模糊层会溢出或定位错乱。
- 依赖 `backdrop-filter`，需作用在有实际内容的同层之上才看得见效果（空背景上无可糊之物）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Radar

> 雷达扫描 WebGL 背景 · 同心环波纹 + 径向辐条 + 旋转扫描臂 + 边缘衰减 + 鼠标视差(ogl·主色吃 chart token·reduced-motion 降级静态盘) · decoration/backdrop · #animated #webgl

## 何时用

需要科技 / 监控 / 指挥中心氛围的动态背景，扫描臂旋转隐喻「实时探测」。要规整的几何点阵/线网用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；只要单点同心扩散波用 [Ripple](https://hulianui.haloritual.com/components/ripple)；Radar 是这一族里唯一带旋转扫描臂 + 同心环 + 辐条的「雷达盘」专项。

## 导入
```ts
import { Radar } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `number` | `1` | 整体动画速度因子（环波扩散 + 扫描臂共用基础时间），映射 GLSL uSpeed |
| scale | `number` | `0.5` | 雷达图缩放，越小盘越大（铺满），越大盘越小（留边距） |
| ringCount | `number` | `10` | 同心环数量，越大越密 |
| spokeCount | `number` | `10` | 辐条（径向分隔线）数量，0 = 无辐条 |
| ringThickness | `number` | `0.05` | 同心环线条粗细，越大越宽越柔 |
| spokeThickness | `number` | `0.01` | 辐条线条粗细 |
| sweepSpeed | `number` | `1` | 扫描臂旋转速度 |
| sweepWidth | `number` | `2` | 扫描臂宽度（幂次锐度），越大越窄越锐 |
| sweepLobes | `number` | `1` | 扫描臂瓣数，1=单束 / 2=对称双束 |
| color | `string` | `var(--color-chart-1)` | 雷达主色（环/辐条/扫描臂），任意 CSS 颜色串 |
| backgroundColor | `string` | — | 雷达底色（常驻基色），缺省透明透出宿主背景 |
| falloff | `number` | `2` | 边缘衰减幂次，越大中心越聚焦边缘消散越快 |
| brightness | `number` | `1` | 整体亮度倍率 |
| enableMouseInteraction | `boolean` | `true` | 是否开启鼠标视差（盘随指针平滑偏移） |
| mouseInfluence | `number` | `0.1` | 鼠标视差影响系数 |
| className | `string` | — | 透传到根容器（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认径向渐变装饰 div） |

## 示例
```tsx
// 默认参数，主色吃 chart token，自动明暗适配
<div className="relative h-64 overflow-hidden rounded-xl">
  <Radar />
</div>

// 密集环 + 双瓣快扫
<Radar ringCount={16} spokeCount={16} sweepSpeed={1.8} sweepLobes={2} />
```

## 禁忌 / 坑

- 须客户端渲染（WebGL/ogl），组件自带 `"use client"`；放进 RSC 页时确保挂在 client 子树或动态 import。
- 容器需自带定位 + `overflow-hidden`，组件以 `absolute inset-0` 铺满父级；父级无尺寸时雷达盘不可见。
- reduced-motion / 无 WebGL 环境自动降级为静态 `fallback`，不要依赖扫描臂动画做关键信息表达。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# RetroGrid

> 复古透视网格 · CSS 滚动 + reduced-motion · decoration/backdrop · #animated

## 何时用

营造合成波/赛博朋克风的透视滚动网格地平线。要动态透视网格用本组件；要静态平铺线网格用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)，点状用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)。

## 导入
```ts
import { RetroGrid } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| angle | `number` | `65` | 透视倾斜角度（度） |
| cellSize | `number` | `60` | 网格单元像素 |
| opacity | `number` | `0.5` | 整体不透明度 |
| duration | `number` | `12` | 滚动一轮秒数（越大越慢） |

> 继承 `ComponentPropsWithoutRef<"div">`。颜色取 `currentColor`，用 `text-*` 工具类控制。

## 示例
```tsx
<div className="relative h-56 overflow-hidden rounded-xl border">
  <RetroGrid />
</div>

<RetroGrid cellSize={36} duration={24} className="text-primary" />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，必须放在 `relative`（且通常 `overflow-hidden`）定位容器内。
- 含 CSS 滚动动画，已内置 `prefers-reduced-motion` 降级（系统开启「减少动态效果」时停滚动）。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [Ripple](https://hulianui.haloritual.com/components/ripple) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# Reveal

> 通用「逐级揭示」块级动效原语 · Reveal 包裹元素进入视口时从位移/透明/缩放过渡到正常 + Stagger/StaggerItem 让子项按序错峰入场（非文字动画 · 作用于任意块级内容 · motion 运行时 · 吃 token · reduced-motion 直出终态） · decoration/overlay-fx · #animated

## 何时用

任意块级内容（卡片/段落/列表）想要进入视口或挂载时浮起淡入、多项按序错峰入场时用。这是通用块级动效原语，作用于任意 children；只针对文字逐字符滚动浮现的标题用 ScrollFloat，要边框光带/光泽等装饰特效用 BorderBeam / ShineBorder。

## 导入
```ts
import { Reveal, Stagger, StaggerItem } from "@hulianui/ui"
```

## Props

`Reveal` 与 `Stagger` 共有（继承 `div` props，剔除 motion 冲突的 onDrag*/onAnimationStart）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| trigger | `"in-view" \| "mount"` | `"in-view"`（showcase 演示用 `"mount"`） | 进入视口触发 / 挂载即播(首屏 hero) |
| once | `boolean` | `true` | in-view 时是否只播一次 |

**Reveal**（额外）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| y | `number` | `24` | 起始下移距离 px(自下浮起) |
| blur | `number` | `8` | 起始模糊 px(焦点拉入，GPU 合成) |
| scale | `number` | `1` | 起始缩放(<1 像「放上书架」落位) |
| delay | `number` | — | 延迟秒数(独立块错峰用；Stagger 内由容器编排无需 delay) |

**Stagger**（额外）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| gap | `number` | `0.08` | 子项间错峰秒数 |
| delay | `number` | `0` | 整组起始延迟秒数 |

**StaggerItem**（继承 `div` props，剔除 motion 冲突项）：

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| y | `number` | `18` | 起始下移距离 px |
| blur | `number` | `8` | 起始模糊 px |
| scale | `number` | `1` | 起始缩放(<1 像「放上书架」) |

## 示例
```tsx
// 单块：挂载浮起 + 焦点拉入
<Reveal trigger="mount" y={24} blur={8} scale={1}>
  <div className="card">浮起的内容</div>
</Reveal>

// 逐级编排：子项按 gap 错峰入场，压轴项加重 blur/scale
<Stagger trigger="mount" gap={0.1}>
  <div className="flex flex-col gap-3">
    <StaggerItem><Card>第一行</Card></StaggerItem>
    <StaggerItem><Card>第二行</Card></StaggerItem>
    <StaggerItem y={22} scale={0.94} blur={12}><Card>压轴项</Card></StaggerItem>
  </div>
</Stagger>
```

## 禁忌 / 坑

- 错峰编排走 `Stagger` 容器：放在 Stagger 内的 `StaggerItem` 不要自带 delay（由容器统一编排），独立块错峰才用 `Reveal` 的 delay。
- 这是 motion 运行时的客户端组件（含 `"use client"`）：在 Next.js App Router 里它已是 client 边界，按 server/client 边界正常组合即可，不必再为它把整个父布局升成 client。
- reduced-motion 下直接渲染终态（可见、不糊），别把入场动画当内容可见性的开关。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Ribbons

> 弹簧追随鼠标的飘带 WebGL 效果 · ogl Polyline 多条折线弹性拖尾 + 可选沿带渐隐/正弦波动(ogl·token·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

需要一组「弹性飘带跟随鼠标飞舞」的交互背景（hero、登录页、品牌动效）。同为鼠标跟随特效，要离散溅彩颗粒选 [SplashCursor](https://hulianui.haloritual.com/components/splash-cursor)，要点亮像素格选 [PixelTrail](https://hulianui.haloritual.com/components/pixel-trail)；Ribbons 是连续的丝带拖尾，飘逸感最强。

## 导入
```ts
import { Ribbons } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | `string[]` | `["var(--color-chart-1)","--chart-2","--chart-3"]` | 飘带颜色数组，每色一条飘带；token 须带 `--color-` 前缀 |
| baseSpring | `number` | `0.03` | 弹簧刚度基准，越大追随越紧（每条叠加随机量制造错落） |
| baseFriction | `number` | `0.9` | 阻尼摩擦基准（0–1），越大越黏滞、过冲越少 |
| baseThickness | `number` | `30` | 飘带基础粗细（px） |
| offsetFactor | `number` | `0.05` | 多条飘带横向偏移因子，越大散得越开 |
| maxAge | `number` | `500` | 拖尾衰减寿命（ms），越大尾巴越长；0 或 Infinity 退回固定 0.9 lerp |
| pointCount | `number` | `50` | 每条飘带采样点数（决定折线平滑度） |
| speedMultiplier | `number` | `0.6` | 拖尾追赶速度倍率，配合 maxAge 控尾巴软硬 |
| enableFade | `boolean` | `false` | 沿飘带长度方向渐隐（尾部透明） |
| enableShaderEffect | `boolean` | `false` | shader 波动特效（沿法线正弦抖动） |
| effectAmplitude | `number` | `2` | shader 波动振幅，仅 enableShaderEffect=true 生效 |
| className | `string` | — | 透传到容器（或 reduced-motion fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代（默认 chart token 渐变 div） |

## 示例
```tsx
// 默认三色飘带（容器需 relative + overflow-hidden，移动鼠标追随）
<div className="relative h-56 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 285)" }}>
  <Ribbons />
</div>
```
```tsx
// 尾部渐隐 + 波动特效
<Ribbons enableFade enableShaderEffect effectAmplitude={2} />
```

## 禁忌 / 坑

- `colors` 里的 token 必须带 `--color-` 前缀，裸 `var(--primary)` shader 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- WebGL/ogl 组件，仅客户端渲染；StrictMode 双挂载 canvas context 复用风险见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 飘带追随的是全容器内的鼠标，父级需 `relative` + `overflow-hidden`；本组件不拦截下层交互。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Ripple

> 同心脉冲圆环 · CSS 逐圈延迟 + reduced-motion · decoration/backdrop · #animated

## 何时用

中心向外扩散的同心脉冲（雷达扫描、信号广播、CTA 焦点氛围）。要脉冲圆环用本组件；要静态径向辉光用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)，要规整纹理用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)。

## 导入
```ts
import { Ripple } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| mainCircleSize | `number` | `210` | 最内圈直径 px |
| mainCircleOpacity | `number` | `0.24` | 最内圈不透明度 |
| numCircles | `number` | `8` | 圈数 |

> 继承 `ComponentPropsWithoutRef<"div">`。颜色取 `currentColor`，用 `text-*` 工具类控制。

## 示例
```tsx
<div className="relative grid place-items-center overflow-hidden">
  <Ripple mainCircleSize={160} />
</div>

<Ripple mainCircleSize={140} numCircles={5} className="text-primary" />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，须放在 `relative` 定位容器内，通常配 `grid place-items-center` 让脉冲从内容中心扩散。
- 含逐圈延迟的 CSS 动画，已内置 `prefers-reduced-motion` 降级。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# RippleGrid

> 涟漪网格 WebGL 背景 · 同心 sin 波推挤网格 + 暗角/辉光/彩虹配色 + 指针局部涟漪(ogl·chart token·reduced-motion 降级静态网格) · decoration/backdrop · #animated #webgl

## 何时用

要「网格被波纹推挤起伏」的有机动态底纹（hero / 卡片背景）。要静态规整网格用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要透视退场感网格用 [RetroGrid](https://hulianui.haloritual.com/components/retro-grid)；RippleGrid 是这族里唯一让网格随同心波纹+指针涟漪扭动、并支持彩虹循环配色的一件。

## 导入
```ts
import { RippleGrid } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| enableRainbow | `boolean` | `false` | 彩虹循环配色（随时间在 RGB 间渐变，忽略 color） |
| color | `string` | `var(--color-chart-1)` | 网格主色，任意 CSS 颜色串；enableRainbow=true 时被忽略 |
| rippleIntensity | `number` | `0.05` | 涟漪扰动强度，0 = 静止网格 |
| gridSize | `number` | `10` | 网格密度，越大越密 |
| gridThickness | `number` | `15` | 网格线锐度（粗细反向量），越大越细越锐 |
| fadeDistance | `number` | `1.5` | 中心向四周的距离淡出指数，越大越聚焦中心 |
| vignetteStrength | `number` | `2` | 暗角强度，0 = 无暗角 |
| glowIntensity | `number` | `0.1` | 网格线发光强度，0 = 无辉光 |
| opacity | `number` | `1` | 整体不透明度（0–1） |
| gridRotation | `number` | `0` | 网格旋转角度（度），45 = 菱形网格 |
| mouseInteraction | `boolean` | `true` | 指针处额外激起一圈涟漪 |
| mouseInteractionRadius | `number` | `1` | 鼠标涟漪影响半径 |
| className | `string` | — | 透传到根容器（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认静态网格底纹 div） |

## 示例
```tsx
// 默认：深色底 + chart-1 token，自动明暗适配
<div className="relative h-64 overflow-hidden rounded-xl">
  <RippleGrid />
</div>

// 彩虹循环配色 + 略强涟漪
<RippleGrid enableRainbow rippleIntensity={0.08} gridSize={12} />
```

## 禁忌 / 坑

- 须客户端渲染（WebGL/ogl），组件自带 `"use client"`；RSC 页里挂 client 子树或动态 import。
- 组件自带 `absolute inset-0 z-0`，父容器须有定位 + 尺寸 + `overflow-hidden`，否则不可见。
- `enableRainbow` 会无视 `color`，两者别同时指望；要单一主题色就关掉彩虹。
- reduced-motion / 无 WebGL 时降级为静态网格 `fallback`，关键信息别绑动画。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# ShapeBlur

> 鼠标揭示的模糊形状高光 WebGL 件 · 圆角矩形/圆/圆环/三角四形态 + 阻尼跟随柔光圆擦亮边缘(ogl·token·reduced-motion 降级静态光晕) · decoration/overlay-fx · #animated

## 何时用

需要一块「鼠标靠近才被柔光擦亮的模糊形状高光」装饰背景（hero 留白处、卡片底的隐约几何）。要的是流体黏球选 [MetaBalls](https://hulianui.haloritual.com/components/meta-balls)，要的是图片放大镜选 [Lens](https://hulianui.haloritual.com/components/lens)；ShapeBlur 是其中最克制的一档——平时几乎隐形，鼠标过处才浮现 SDF 几何边缘。

## 导入
```ts
import { ShapeBlur } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| variation | `"round-rect"｜"circle-fill"｜"circle-stroke"｜"triangle"` | `"round-rect"` | 形状预设（圆角矩形描边/实心圆/圆环描边/三角填充） |
| shapeSize | `number` | `1.2` | 形状整体尺寸（GLSL u_shapeSize），越大越大 |
| roundness | `number` | `0.4` | 圆角程度，仅 round-rect 生效，0=直角 |
| borderSize | `number` | `0.05` | 描边宽度，仅描边类（round-rect/circle-stroke）生效 |
| circleSize | `number` | `0.3` | 跟随鼠标的柔光圆半径（擦亮区域大小） |
| circleEdge | `number` | `0.5` | 柔光圆边缘羽化，越大越柔 |
| color | `string` | `var(--color-foreground)` | 形状主色，CSS 颜色或带 `--color-` 前缀的 token |
| damping | `number` | `8` | 鼠标跟随阻尼，越大跟随越快、越小越懒 |
| className | `string` | — | 透传到 root 容器 div |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代（默认 foreground 径向光晕 div） |

## 示例
```tsx
// 默认圆角矩形描边（容器需 relative + overflow-hidden，移动鼠标揭示）
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.13 0.02 270)" }}>
  <ShapeBlur variation="round-rect" />
</div>
```
```tsx
// 圆环描边 + 暖金色 + 更大光圆
<ShapeBlur variation="circle-stroke" color="oklch(0.82 0.16 75)" circleSize={0.35} />
```

## 禁忌 / 坑

- `color` 给 token 必须带 `--color-` 前缀，裸 `var(--primary)` shader 不解析；showcase 里 `color` 留空即用默认 foreground。见 [[hulian-token-color-var-needs-color-prefix]]。
- WebGL/ogl 组件，仅客户端渲染；StrictMode 双挂载 canvas context 复用风险见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]。
- 组件自带 `absolute inset-0 z-0`，父容器需 `relative` + `overflow-hidden`；`roundness`/`borderSize` 只在对应 variation 下生效，换形状别忘对照。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# ShapeGrid

> 无限滚动几何网格背景 · canvas2d 绘制方/圆/三角/六边形四形，沿任意方向匀速平移环绕 + 鼠标悬停缓动填充与渐隐拖尾（零依赖·token 配色·reduced-motion 静止·jsdom 安全） · decoration/backdrop · #animated #webgl

## 何时用

要持续滚动 + 悬停点亮的几何单元背景（看板/落地页底纹）。要静态点阵用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)，静态线网用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；ShapeGrid 是这族里唯一 canvas2d 零依赖、支持四种形状无限平移环绕 + 悬停渐隐拖尾的一件（不走 WebGL，jsdom 测试安全）。

## 导入
```ts
import { ShapeGrid } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| direction | `"right"｜"left"｜"up"｜"down"｜"diagonal"` | `"right"` | 网格滚动方向 |
| speed | `number` | `1` | 滚动速度（像素/帧，内部 clamp 下限 0.1）；reduced-motion 下强制静止 |
| borderColor | `string` | `var(--color-border)` | 单元边线颜色，任意 CSS 颜色串 |
| squareSize | `number` | `40` | 单元边长（px），同时决定网格密度 |
| hoverFillColor | `string` | `var(--color-primary)` | 悬停时单元填充色，淡入/淡出缓动 |
| shape | `"square"｜"circle"｜"triangle"｜"hexagon"` | `"square"` | 单元形状 |
| hoverTrailAmount | `number` | `0` | 悬停拖尾长度（保留多少历史单元渐隐），0 = 无拖尾 |
| className | `string` | — | 透传到根 canvas |
| style | `CSSProperties` | — | 透传到根 canvas 的内联样式 |

## 示例
```tsx
// 默认：方格向右滚动，吃 border token
<div className="relative h-56 overflow-hidden rounded-xl">
  <ShapeGrid className="absolute inset-0 opacity-90" />
</div>

// 圆点阵 · 向上滚 · 悬停拖尾 + chart-2 填充
<ShapeGrid
  shape="circle"
  direction="up"
  hoverTrailAmount={6}
  hoverFillColor="var(--color-chart-2)"
  className="absolute inset-0 opacity-90"
/>
```

## 禁忌 / 坑

- 自身是 canvas，没有 `absolute inset-0`，须自己用 className 定位铺满（示例的 `absolute inset-0`）；父容器要有定位 + 尺寸 + `overflow-hidden`。
- 颜色 token 喂给 canvas 须带 `--color-` 前缀（如 `var(--color-chart-2)`），裸 `var(--primary)` 不解析见 [[hulian-token-color-var-needs-color-prefix]]。
- reduced-motion 下速度按 0 处理（静止），动效别当关键反馈。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# ShineBorder

> 流光边框 · 渐变 mask 只留边框区 + chart token + RSC · decoration/overlay-fx · #animated

## 何时用

想让卡片/容器的整条边框持续流动渐变流光时用（纯 CSS、可在 RSC 服务端渲染）。它是绝对定位覆盖件，放进 `relative` 容器即可。要一个光点绕边而非整边流光用 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)；要 hover 时斜向扫一道反光用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)。

## 导入
```ts
import { ShineBorder } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| borderWidth | `number` | `1` | 边框宽度 px |
| duration | `number` | `14` | 流光一轮秒数 |
| shineColor | `string \| string[]` | 瑚琏 chart token | 流光色，单色或多色数组 |
| className | `string` | — | 透传 className |
| style | `CSSProperties` | — | 透传内联样式 |

## 示例

```tsx
<div className="relative overflow-hidden rounded-xl bg-surface">
  ...content
  <ShineBorder />
</div>
```

```tsx
// 粗边 · 单色
<div className="relative rounded-xl bg-surface">
  ...content
  <ShineBorder borderWidth={2} shineColor="var(--color-primary)" />
</div>
```

## 禁忌 / 坑

- 必须置于 `position:relative` 容器内，否则边框定位错乱。
- `shineColor` 喂 token 需带 `--color-` 前缀，裸 `var(--primary)` 不解析——参见 [[hulian-token-color-var-needs-color-prefix]]。
- 纯 CSS 实现，可在 RSC 直接用，无需 `"use client"`。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles) · [ProgressiveBlur](https://hulianui.haloritual.com/components/progressive-blur)

<!-- ════════════════════════════════════════════════════════ -->
# SideRays

> 从屏幕一角发散的动态侧光束 WebGL 背景 · 双束角度正弦摆动+平方反比衰减+饱和度/混色调节(ogl·token 双色·reduced-motion 静态兜底) · decoration/backdrop · #animated #webgl

## 何时用

要从某个角落射出、缓慢摆动的体积光束氛围（hero / 登录页一侧打光）。要中心聚光跟随鼠标用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)；要满屏点/线纹理用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)；SideRays 是这族里唯一从四角任一起点发散双束、可调张角/混色/饱和度的「侧打光」专项。

## 导入
```ts
import { SideRays } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | `number` | `2.5` | 光束动画速度因子（第二束 0.2× 慢速错相），映射 GLSL iSpeed |
| rayColor1 | `string` | `var(--color-chart-1)` | 主光束颜色，任意 CSS 颜色串 |
| rayColor2 | `string` | `var(--color-chart-2)` | 辅光束颜色，与主色叠加产生混色 |
| intensity | `number` | `2` | 整体亮度强度，过大易过曝 |
| spread | `number` | `2` | 光束张开角度（扇面宽度），越小越聚拢成一道 |
| origin | `"top-left"｜"top-right"｜"bottom-left"｜"bottom-right"` | `"top-right"` | 光束发散的角落起点 |
| tilt | `number` | `0` | 光束整体倾斜角度（度），绕光源点旋转扇面 |
| saturation | `number` | `1.5` | 饱和度，1=原色 / >1 增艳 / 0=去色 |
| blend | `number` | `0.75` | 两束混色比例（0–1），0=仅主色 / 1=仅辅色 |
| falloff | `number` | `1.6` | 亮度随距离衰减指数，越大越集中光源附近 |
| opacity | `number` | `1` | 整体不透明度（0–1），叠内容上常用 0.5–0.8 |
| className | `string` | — | 透传根容器；组件自带 `absolute inset-0 z-0` |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时的静态替代内容（默认角向 radial-gradient div） |

## 示例
```tsx
// 默认右上角发散，吃 chart token 双色
<div className="relative h-56 overflow-hidden rounded-xl">
  <SideRays opacity={0.85} />
</div>

// 左下角起点 · 暖色双束
<SideRays
  origin="bottom-left"
  rayColor1="oklch(0.78 0.18 70)"
  rayColor2="oklch(0.7 0.22 30)"
  intensity={2.4}
  opacity={0.8}
/>
```

## 禁忌 / 坑

- 须客户端渲染（WebGL/ogl），组件自带 `"use client"`；RSC 页里挂 client 子树或动态 import。
- 组件自带 `absolute inset-0 z-0`，父容器须有定位 + 尺寸 + `overflow-hidden`，否则不可见。
- `intensity` 过大光源处易过曝纯白；叠在内容上用 `opacity` 0.5–0.8 降干扰。
- reduced-motion / 无 WebGL 时降级为静态 `fallback`（保留方位感），别把摆动当关键信息。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# Silk

> 丝绸流动背景 · WebGL/ogl 懒加载 shader(复刻 react-bits) + chart token 主色 + reduced-motion 渐变兜底 · decoration/backdrop · #animated #webgl

## 何时用

需要高质感的流动丝绸光泽背景时用，视觉档次高于纯 CSS 背景。基于 WebGL/ogl（懒加载），有 GPU 开销，但自带 reduced-motion / 无 WebGL 时的渐变 fallback；若不愿引入 WebGL，退而求其次用纯 CSS 的 [Aurora](https://hulianui.haloritual.com/components/aurora)；想要虹彩光谱质感用 [Iridescence](https://hulianui.haloritual.com/components/iridescence)，想要丝线网格用 [Threads](https://hulianui.haloritual.com/components/threads)。

## 导入
```ts
import { Silk, silkShowcase } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| speed | number | 5 | 动画速度因子，映射 GLSL uniform uSpeed，越大越快 |
| scale | number | 1 | 噪声/纹理缩放，越大细节越密，越小越宏观 |
| color | string | `--color-chart-1` | 丝绸主色，CSS 颜色字符串（hex/oklch/rgb/var）。默认吃主题 token |
| noiseIntensity | number | 1.5 | 颗粒噪声强度，0=无颗粒（纯色带） |
| rotation | number | 0 | 纹理旋转角度（弧度），如 `Math.PI/4`=45° |
| className | string | — | 透传到 canvas（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | ReactNode | reduced-motion / 无 WebGL 时渲染的静态替代内容（默认 chart token 渐变 div） |

## 示例
```tsx
// 默认深色底 chart-1 token，自带 absolute inset-0 z-0，需 relative 父容器
<div className="relative h-64 overflow-hidden rounded-xl">
  <Silk />
  <div className="relative z-10 flex h-full items-center justify-center">
    <p className="text-2xl font-bold text-white/90">Silk</p>
  </div>
</div>
```
```tsx
// 自定义暖金色 + 慢速细腻
<Silk color="oklch(0.78 0.18 55)" speed={2} scale={1.5} />
```

## 禁忌 / 坑

- WebGL 组件，须客户端渲染；`color` 支持 `var(--…)`/oklch，组件内部负责解析后喂 shader。
- 自带 `absolute inset-0 z-0`，叠加内容须用 `relative z-10`，父容器需 `relative` + `overflow-hidden`。
- ogl shader 在 StrictMode 双挂载或 cleanup 时易踩 context 复用毒化坑——若改源码勿在 cleanup 调 `loseContext` 后复用同一 canvas（参见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]）；headless 截图可能因 WebGL 不可用而走 fallback，验证视觉用真实浏览器。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# SoftAurora

> WebGL 柔和极光背景 · 3D Perlin 噪声 + cosine 渐变双层叠加 · 鼠标视差(ogl·token 着色·reduced-motion 降级) · decoration/backdrop · #animated #webgl

## 何时用

要柔和流动的极光/光晕氛围底（深色 hero、营销页大块留白）。要规整的点/线/网格纹理用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)；要从角落打出的体积光束用 [SideRays](https://hulianui.haloritual.com/components/side-rays)；SoftAurora 是这族里唯一双层 Perlin 噪声 + cosine 色相循环的「极光色带」专项。

## 导入
```ts
import { SoftAurora } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color1 | `string` | `var(--color-chart-1)` | 主极光色带颜色（第 1 层），任意 CSS 颜色串（离屏 canvas 解析） |
| color2 | `string` | `var(--color-chart-4)` | 辅助极光色带颜色（第 2 层），错位叠加产生混色干涉 |
| speed | `number` | `0.6` | 极光流动速度倍率，建议 0.2–2 |
| scale | `number` | `1.5` | 噪声采样缩放，越大纹理越细碎，建议 0.8–3 |
| brightness | `number` | `1` | 整体亮度倍率 |
| noiseFrequency | `number` | `2.5` | 噪声基频，影响褶皱密度 |
| noiseAmplitude | `number` | `1` | 噪声基振幅，影响起伏幅度 |
| bandHeight | `number` | `0.5` | 极光带垂直位置（0–1），越小越靠下 |
| bandSpread | `number` | `1` | 极光带辉光扩散强度 |
| octaveDecay | `number` | `0.1` | 多倍频噪声衰减系数，控制高频细节占比 |
| layerOffset | `number` | `0` | 两层极光的时间相位偏移，非 0 时错峰流动 |
| colorSpeed | `number` | `1` | 色相循环流动速度（cosine 渐变水平滚动快慢） |
| enableMouseInteraction | `boolean` | `true` | 鼠标视差（极光随指针轻微平移） |
| mouseInfluence | `number` | `0.25` | 鼠标视差强度 |
| className | `string` | — | 透传到根容器 |
| style | `CSSProperties` | — | 透传到根容器的内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | `ReactNode` | reduced-motion / 无 WebGL 时降级静态层之上覆盖的内容（如标题） |

## 示例
```tsx
// 默认 chart token 双层极光
<div className="relative h-56 overflow-hidden rounded-xl">
  <SoftAurora className="absolute inset-0" />
</div>

// 壁纸级：低速 · 关交互 · 靠底 · 自带标题 fallback
<SoftAurora
  speed={0.3}
  bandHeight={0.35}
  enableMouseInteraction={false}
  className="absolute inset-0"
  fallback={<h1 className="...">瑚琏组件库</h1>}
/>
```

## 禁忌 / 坑

- 须客户端渲染（WebGL/ogl），组件自带 `"use client"`；RSC 页里挂 client 子树或动态 import。
- 自身无 `inset-0`，须用 className 定位铺满（示例的 `absolute inset-0`）；父容器要有定位 + 尺寸 + `overflow-hidden`。
- `color1/color2` 走离屏 canvas 解析，可直接吃 `var(--color-chart-*)` token；裸 `var(--primary)` 不解析，见 [[hulian-token-color-var-needs-color-prefix]]。
- reduced-motion / 无 WebGL 时降级静态渐变并叠 `fallback`，别把流动当关键信息。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# SplashCursor

> 指针流体溅射光标特效 · 移动溅彩+点击爆斑+拖尾消散 · 彩虹色相轮/固定 chart token 双模(canvas2d 零依赖·reduced-motion·RSC 安全) · decoration/overlay-fx · #animated

## 何时用

想给一块区域（或整页）加「鼠标移动溅彩、点击爆斑」的流体光标特效（hero、玩味落地页）。它是 canvas2d 零依赖 RSC 安全的纯特效层，`pointer-events-none` 不拦交互。要连续丝带拖尾选 [Ribbons](https://hulianui.haloritual.com/components/ribbons)，要像素颗粒余晖选 [PixelTrail](https://hulianui.haloritual.com/components/pixel-trail)；SplashCursor 是离散彩色染料溅射。

## 导入
```ts
import { SplashCursor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| rainbow | `boolean` | `true` | 彩虹模式：每次溅射沿 HSV 色相轮循环。关闭后统一用 color |
| color | `string` | `var(--color-chart-1)` | 非彩虹模式的固定溅射色，token 须带 `--color-` 前缀；rainbow 时忽略 |
| splatRadius | `number` | `56` | 溅射半径基准（px），越大色斑越饱满 |
| splatForce | `number` | `1` | 溅射力度：随指针速度抛洒的位移与拖尾长度，建议 0.5–2 |
| dissipation | `number` | `0.92` | 色斑保留率（每秒衰减，0–1），越接近 1 越持久 |
| opacity | `number` | `1` | 整体不透明度（0–1），叠内容下方时可调暗 |
| className | `string` | — | 透传到根容器（占满父级 absolute inset-0）；父级需 relative |
| style | `CSSProperties` | — | 透传到根容器 |

## 示例
```tsx
// 默认彩虹溅射（父级需 relative + overflow-hidden）
<div className="relative h-64 overflow-hidden rounded-xl"
     style={{ background: "oklch(0.14 0.02 255)" }}>
  <SplashCursor />
</div>
```
```tsx
// 固定主题色 · 猛烈拖尾
<SplashCursor rainbow={false} splatForce={1.8} dissipation={0.97} splatRadius={72} />
```

## 禁忌 / 坑

- 注意 `dissipation` 是「保留率」语义（与原版 DENSITY_DISSIPATION 反向）：越大越持久，不是越大越快消散。
- 非彩虹模式 `color` 给 token 用带 `--color-` 前缀的变量；彩虹开启时此值被忽略。见 [[hulian-token-color-var-needs-color-prefix]]。
- canvas2d 零依赖、RSC 安全、自带 `pointer-events-none` 不拦下层交互；父级必须 `relative` 它才能 `absolute inset-0` 铺满。reduced-motion 下降级不溅射。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Spotlight

> 径向辉光背景 · token 驱动 radial-gradient + 明暗自适应 + RSC · decoration/backdrop

## 何时用

给 Hero/卡片加柔和径向辉光（聚焦视线、营造氛围）。要辉光晕染用本组件；要规整纹理用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern) / [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) / [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern)。

## 导入
```ts
import { Spotlight } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `string` | `var(--color-primary)` | 辉光色；可传任意 CSS 颜色/变量（如 `var(--color-success)`） |
| intensity | `number` | `14` | 辉光强度：辉光中心与底色 color-mix 的百分比，越大越亮 |
| x | `string` | `"50%"` | 辉光中心 X 位置 |
| y | `string` | `"0%"` | 辉光中心 Y 位置（顶部） |
| size | `string` | `"125%"` | 辉光椭圆尺寸（径向渐变范围） |
| fade | `number` | `55` | 渐隐到底色的位置百分比，越小辉光越聚拢 |

> 继承 `ComponentPropsWithoutRef<"div">`。

## 示例
```tsx
<div className="relative grid place-items-center overflow-hidden">
  <Spotlight intensity={18} x="20%" />
  <div className="relative z-10">…内容…</div>
</div>

<Spotlight color="var(--color-success)" y="50%" size="100%" intensity={16} />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，必须放在 `relative`（且通常 `overflow-hidden`）定位容器内；叠加内容须 `relative z-10` 才能盖在辉光之上。
- 自定义 `color` 用 token 变量（`var(--color-*)`，须带 `--color-` 前缀）而非裸 `var(--primary)`，否则 color-mix 不解析。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# StarBorder

> 流星描边按钮 · 上下两道 radial-gradient 光带沿边沿来回扫过(纯 CSS·零依赖·RSC 安全)，光带色走 token、内壳 bg-surface/border-border，多态 as + reduced-motion 自动停。 · decoration/overlay-fx · #animated

## 何时用

需要一个会发光描边、吸引点击的 CTA 按钮/链接时用。相比 [BorderBeam](https://hulianui.haloritual.com/components/border-beam)/[ShineBorder](https://hulianui.haloritual.com/components/shine-border) 这类「给任意卡片容器加边框光效」的包裹件，StarBorder 自带按钮语义（默认渲染 `<button>`、内壳就是按钮皮），直接当按钮用；如果只想给一块已有内容描边发光、不需要按钮，用 ShineBorder/BorderBeam。

## 导入
```ts
import { StarBorder } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| as | `ElementType` | `"button"` | 渲染根标签，可传 `"a"`/`"div"`/任意组件；DOM 属性透传到该元素 |
| color | `string` | `var(--color-primary)` | 流星光带颜色，喂进 radial-gradient；任意 CSS 颜色（hex/oklch/var(--…)）均可 |
| speed | `number` | `6` | 单趟流星扫过时长（秒），越大越慢越克制 |
| thickness | `number` | `1` | 边框光带厚度（px），撑开根容器上下内边距决定描边粗细 |
| className | `string` | — | 透传根容器额外类名（合并，可覆盖圆角/间距） |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 按钮/容器内容 |

## 示例
```tsx
// 主色光带按钮
<StarBorder>立即开始</StarBorder>

// 多态：渲染成链接，自定义色 + 加快
<StarBorder as="a" href="/docs" color="var(--color-chart-2)" speed={3}>
  查看文档 →
</StarBorder>
```

## 禁忌 / 坑

- 自定义 `color` 走 token 时务必带 `--color-` 前缀（如 `var(--color-chart-3)`），裸 `var(--primary)` 在 Tailwind v4 下不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- reduced-motion 下光带自动停（不动但描边仍在），无需额外处理。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# StickerPeel

> 可拖拽贴纸 · hover/按住顶部卷边揭起 + 落地投影 + 鼠标跟随高光（零依赖·PointerEvents 拖拽·reduced-motion） · decoration/overlay-fx · #animated

## 何时用

把一张图片做成可揭起卷边、可在父容器内拖动的「随手贴」装饰时用，适合营销页/作品集里趣味性的徽标、奖章、活动贴纸。它是图片专用的拟物玩法；如果你要的是给任意容器加发光描边或扫光，用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)/[ShineBorder](https://hulianui.haloritual.com/components/shine-border)；要图片局部放大镜则用 [Lens](https://hulianui.haloritual.com/components/lens)。

## 导入
```ts
import { StickerPeel } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| imageSrc * | `string` | — | 贴纸图片地址，渲染两层：正面贴纸 + 翻起的背面卷边 |
| alt | `string` | `""` | 图片可访问性描述（透传 img alt），装饰性贴纸可留空 |
| width | `number` | `200` | 贴纸宽度（px），高度按图片原比例自适应 |
| rotate | `number` | `30` | 内部图案旋转角（deg），制造随手贴的歪斜感 |
| peelBackHoverPct | `number` | `30` | hover 时卷边翻起百分比（顶部揭开高度占比） |
| peelBackActivePct | `number` | `40` | active（按住）时卷边翻起百分比，通常比 hover 大 |
| peelDirection | `number` | `0` | 卷边方向角度（deg），整张贴纸连卷边一起旋转 |
| shadowIntensity | `number` | `0.6` | 落地投影强度 0~1（drop-shadow 透明度） |
| lightingIntensity | `number` | `0.4` | 鼠标跟随高光强度 0~1，0 关闭高光 |
| initialPosition | `"center" \| { x: number; y: number }` | `"center"` | 贴纸初始落点：居中或相对父容器左上角的像素偏移 |
| draggable | `boolean` | `true` | 是否允许在父容器内拖拽（越界自动夹回） |

> 还继承 `HTMLAttributes<HTMLDivElement>`（除 `children`），可透传 `className`/`style`/事件等。

## 示例
```tsx
// 默认：揭起 + 拖拽
<StickerPeel imageSrc="/sticker.svg" width={150} rotate={14} />

// 大幅卷边 + 强高光 + 锁定不可拖
<StickerPeel
  imageSrc="/sticker.svg"
  width={170}
  peelBackHoverPct={42}
  peelBackActivePct={55}
  lightingIntensity={0.7}
  draggable={false}
/>
```

## 禁忌 / 坑

- 父容器需 `position: relative` + `overflow-hidden`，否则拖拽边界算不准、贴纸会跑出框。
- `draggable` 默认开启，会拦截 PointerEvents；若贴纸放在可点击/可滚动区域内需评估手势冲突，按需关掉。
- reduced-motion 下卷边/高光动效降级，但贴纸本体仍可见。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# StripedPattern

> 斜条纹背景 · 纯 CSS 渐变 + currentColor · decoration/backdrop

## 何时用

给区块铺斜条纹底纹（警示带/施工感/质感分隔）。要条纹用本组件；点状用 [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)，线网格用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern)，径向辉光用 [Spotlight](https://hulianui.haloritual.com/components/spotlight)。

## 导入
```ts
import { StripedPattern } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| angle | `number` | `45` | 条纹角度（度） |
| size | `number` | `10` | 条纹+间隔单元宽 px |

> 继承 `ComponentPropsWithoutRef<"div">`。颜色取 `currentColor`，用 `text-*` 工具类控制。

## 示例
```tsx
<div className="relative h-48 overflow-hidden rounded-xl border">
  <StripedPattern />
</div>

<StripedPattern angle={90} size={20} className="text-muted" />
```

## 禁忌 / 坑

- 内部 `absolute inset-0` 铺满父级，必须放在 `relative`（且通常 `overflow-hidden`）定位容器内。
- 颜色靠 `currentColor`，用 `text-*` 改色。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple) · [Meteors](https://hulianui.haloritual.com/components/meteors)

<!-- ════════════════════════════════════════════════════════ -->
# TargetCursor

> 跟随鼠标的准星自定义光标 · 中心圆点 + 四角括号空闲自转、悬停命中元素时展开包裹其包围盒(去 gsap·裸 rAF lerp·token 着色·reduced-motion) · decoration/overlay-fx · #animated

## 何时用

想给页面/某块区域换上准星式自定义光标、悬停到目标元素时四角括号自动框住它，做游戏化或炫技交互时用。它接管光标本身；如果只是想让某个元素在悬停时发光/变形（不改光标），用 [GlareHover](https://hulianui.haloritual.com/components/glare-hover)；要鼠标跟随的局部放大镜则用 [Lens](https://hulianui.haloritual.com/components/lens)。

## 导入
```ts
import { TargetCursor } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| targetSelector | `string` | `".cursor-target"` | 命中目标的 CSS 选择器，悬停匹配元素时四角括号展开包裹它 |
| spinDuration | `number` | `2` | 空闲态四角括号绕中心自转一圈的秒数，越小越快 |
| hideDefaultCursor | `boolean` | `true` | 是否隐藏系统默认光标（容器作用域只隐藏父容器内；fullScreen 接管 body cursor，卸载还原） |
| fullScreen | `boolean` | `false` | 是否升级为整页全屏光标（fixed 铺满 viewport、监听挂 window）；默认容器作用域（absolute 锚父容器、离开即隐藏、多实例并存） |
| color | `string` | `var(--color-foreground)` | 光标主色（dot 背景 + 四角描边），须带 `--color-` 前缀才解析 |
| hoverDuration | `number` | `0.2` | 四角括号包裹目标的缓动跟随时长（秒），越大越「黏」 |
| className | `string` | — | 透传根容器额外类名 |
| style | `CSSProperties` | — | 透传根容器内联样式 |

## 示例
```tsx
// 容器作用域：把准星限制在某块区域内，移入 .cursor-target 即被框住
<div className="relative">
  <div className="cursor-target">瞄准我</div>
  <TargetCursor />
</div>

// 主色 + 快速自转 + 黏性包裹
<TargetCursor color="var(--color-primary)" spinDuration={0.8} hoverDuration={0.6} />
```

## 禁忌 / 坑

- `color` 走 token 必须带 `--color-` 前缀（如 `var(--color-primary)`），裸 `var(--primary)` 不解析。见 [[hulian-token-color-var-needs-color-prefix]]。
- 容器作用域要求父元素是定位上下文；若父元素 `position: static`，组件会就地补 `position: relative` 并在卸载时还原——别依赖父元素自身的 static 定位。
- `fullScreen` 模式接管 `document.body` 的 cursor，全页只该放一个实例；容器作用域才能多实例并存。
- 监听挂 window/容器、隐藏系统光标都是浏览器行为，须客户端运行（组件已标 `"use client"`）。

## 相关
[BorderBeam](https://hulianui.haloritual.com/components/border-beam) · [ShineBorder](https://hulianui.haloritual.com/components/shine-border) · [GlareHover](https://hulianui.haloritual.com/components/glare-hover) · [Lens](https://hulianui.haloritual.com/components/lens) · [AnimatedBeam](https://hulianui.haloritual.com/components/animated-beam) · [OrbitingCircles](https://hulianui.haloritual.com/components/orbiting-circles)

<!-- ════════════════════════════════════════════════════════ -->
# Threads

> 流动丝线背景 · WebGL/ogl Perlin 波动线随鼠标摆动 + 透明底叠加 + chart token + 静态 fallback · decoration/backdrop · #animated #webgl

## 何时用

需要透明底上几条随鼠标摆动的流动丝线（极简科技感页眉/页脚/Hero 点缀）时用。基于 WebGL/ogl，透明底便于叠在任意背景之上；同为 WebGL 背景，[Silk](https://hulianui.haloritual.com/components/silk) 是满铺丝绸面、[Iridescence](https://hulianui.haloritual.com/components/iridescence) 是虹彩光谱面，本组件是稀疏丝线；不愿引入 WebGL 则用纯 CSS 的 [Aurora](https://hulianui.haloritual.com/components/aurora)。

## 导入
```ts
import { Threads } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| color | `[number, number, number] \| string` | `--color-chart-1` | 丝线颜色。RGB 数组每分量 0–1（react-bits 原版格式），或任意 CSS 颜色字符串（hex/oklch/rgb/var）。不传则读主题 token |
| amplitude | number | 1 | 波动幅度，越大摆幅越剧烈，建议 0.3–3 |
| distance | number | 0 | 各丝线纵向间距缩放，正值拉开负值压缩，建议 -1–2 |
| enableMouseInteraction | boolean | true | 鼠标跟随：X 影响时间流速、Y 影响振幅，带 0.05 平滑插值 |
| className | string | — | 透传到 canvas（或 fallback div） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| fallback | ReactNode | reduced-motion / 无 WebGL 时的静态替代（默认几条 CSS 渐变线）。传 `null` 可完全隐藏占位 |

## 示例
```tsx
// 默认深色底 chart-1 色，需 relative + overflow-hidden 父容器
<div className="relative h-56 overflow-hidden rounded-xl">
  <Threads />
</div>
```
```tsx
// 蓝色调（RGB 数组）+ 提高振幅
<Threads color={[0.22, 0.53, 0.96]} amplitude={1.2} />
```

## 禁忌 / 坑

- WebGL 组件，须客户端渲染；`color` 既收 0–1 的 `[r,g,b]` 数组也收 CSS 字符串（含 `var(--color-chart-3)`/oklch/hex）。
- ogl/WebGL 在 StrictMode 双挂载或 cleanup 时易踩 context 复用毒化坑——改源码时勿 cleanup 调 `loseContext` 后复用同一 canvas（参见 [[webgl-canvas-loseContext-poisons-strictmode-remount]]）；headless 无 WebGL 时走 fallback，视觉验证用真实浏览器。
- 透明底，需自行放在有底色的容器内才看得清；父容器须 `relative` + `overflow-hidden`。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)

<!-- ════════════════════════════════════════════════════════ -->
# WavyBackground

> 噪声波浪 · canvas 多彩波浪带叠加 + 内联零依赖 value noise + chart token + reduced-motion 静态 · decoration/backdrop · #animated

## 何时用

需要柔和流动的彩色波浪带背景（Hero / 营销区块）时用。基于 canvas + 内联零依赖噪声，自带 reduced-motion 静帧降级；相比纯 CSS 的 [Aurora](https://hulianui.haloritual.com/components/aurora) 质感更"液态"但有 canvas 开销；若要规则几何底纹用 [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) / [DotPattern](https://hulianui.haloritual.com/components/dot-pattern)。`valueNoise2D` 为内部噪声函数导出，自定义波形时可复用。

## 导入
```ts
import { WavyBackground, valueNoise2D } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| colors | string[] | chart token | 波浪颜色列表，任意 CSS 颜色字符串（含 `var(--…)`）。挂载后 getComputedStyle 解析再绘制 |
| waveWidth | number | 50 | 每条波浪绘制宽度（px），越大波带越粗 |
| backgroundFill | string | `--color-background` / `--color-bg` | 背景填充色，每帧半透明绘制产生拖影 |
| blur | number | 10 | canvas filter blur（px），0=不模糊 |
| speed | `"slow" \| "fast"` | "fast" | 动画速度 |
| waveOpacity | number | 0.5 | 每条波浪整体透明度（0–1） |
| className | string | — | 内容容器类（覆盖在波浪上的 wrapper div） |
| containerClassName | string | — | 外层根容器类 |
| containerProps | `Omit<HTMLAttributes<HTMLDivElement>, "className"> & Record<\`data-${string}\`, …>` | — | 透传至外层根 div（含 data-* 自定义属性） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | ReactNode | 波浪上方内容（absolute 居中覆盖） |

## 示例
```tsx
// 默认 fast + chart token，铺满父容器
<div className="relative h-48 overflow-hidden rounded-xl border">
  <WavyBackground containerClassName="h-full w-full">
    <span className="text-sm font-medium text-foreground">WavyBackground</span>
  </WavyBackground>
</div>
```
```tsx
// 自定义品牌色带 + 慢速 + 轻模糊
<WavyBackground
  colors={["#a855f7", "#6366f1", "#c084fc", "#818cf8"]}
  speed="slow"
  blur={8}
  containerClassName="h-full w-full"
/>
```

## 禁忌 / 坑

- 基于 canvas，须客户端渲染；`prefers-reduced-motion` 下自动降为静帧，验证动画时记得关闭该系统开关。
- 容器尺寸用 `containerClassName`（如 `h-full w-full`）撑开，外层父级需 `relative` + `overflow-hidden`。
- `colors`/`backgroundFill` 支持 `var(--…)`，挂载后解析——SSR 首帧不会有色彩，属正常。

## 相关
[DotPattern](https://hulianui.haloritual.com/components/dot-pattern) · [GridPattern](https://hulianui.haloritual.com/components/grid-pattern) · [StripedPattern](https://hulianui.haloritual.com/components/striped-pattern) · [Spotlight](https://hulianui.haloritual.com/components/spotlight) · [RetroGrid](https://hulianui.haloritual.com/components/retro-grid) · [Ripple](https://hulianui.haloritual.com/components/ripple)


# ━━━━━━━━ 设备外壳 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# Android

> 安卓外壳 · 打孔摄像头机身包裹屏幕 + RSC · mockups/device

## 何时用

把 App 截图 / 移动端页面包进 Android 机身（打孔摄像头）框做展示，覆盖 Pixel / Galaxy 系机型。要 iPhone 灵动岛机身用 [iPhone](https://hulianui.haloritual.com/components/iphone)，要平板用 [Tablet](https://hulianui.haloritual.com/components/tablet)，要浏览器窗口框用 [Safari](https://hulianui.haloritual.com/components/safari)/[Chrome](https://hulianui.haloritual.com/components/chrome)。

## 导入
```ts
import { Android, ANDROID_MODELS } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`。`ANDROID_MODELS` 导出机型→宽度映射常量。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| model | `"pixel-9-pro-xl" \| "pixel-9-pro" \| "pixel-9" \| "galaxy-s24-ultra" \| "galaxy-s24"` | `"pixel-9-pro"`(showcase) | 预设机型，决定默认宽度。 |
| width | `number` | model 预设，无 model 则 `280` | 设备宽度(px)，显式传入时优先于 model。 |
| imageSrc | `string` | — | 屏幕内容图片地址，优先于 children。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 屏幕内容自定义节点。 |

## 示例
```tsx
<Android model="pixel-9-pro">
  <img src="/app.png" />
</Android>
```

## 禁忌 / 坑

- 机身比例由组件内 `aspectRatio` 统一固定，`model`/`width` 只改宽度不改纵横比。
- `imageSrc` 与 `children` 同传时 `imageSrc` 优先。

## 相关
[iPhone](https://hulianui.haloritual.com/components/iphone) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Watch](https://hulianui.haloritual.com/components/watch) · [Safari](https://hulianui.haloritual.com/components/safari) · [Chrome](https://hulianui.haloritual.com/components/chrome) · [Terminal](https://hulianui.haloritual.com/components/terminal)

<!-- ════════════════════════════════════════════════════════ -->
# Chrome

> 浏览器外壳 · 标签页+工具栏(前进/后退/刷新+地址栏)包裹截图 + RSC · mockups/window

## 何时用

把网页截图 / live 内容包进一个 Chrome 风格窗口框，带标签页标题和前进/后退/刷新工具栏，比 Safari 信息更丰富，适合强调「浏览器内运行」的产品截图。只要红绿灯+地址栏的极简框用 [Safari](https://hulianui.haloritual.com/components/safari)，命令行风格用 [Terminal](https://hulianui.haloritual.com/components/terminal)，移动端机身用 [iPhone](https://hulianui.haloritual.com/components/iphone)/[Android](https://hulianui.haloritual.com/components/android)/[Tablet](https://hulianui.haloritual.com/components/tablet)。

## 导入
```ts
import { Chrome } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`（`className`、`style` 等照常透传，常用 `style={{ width }}` 控宽）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| url | `string` | `"hulian.design"` | 地址栏文本。 |
| title | `string` | 取 url | 标签页标题。 |
| imageSrc | `string` | — | 内容区图片地址，优先于 children。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内容区自定义节点（imageSrc 未传时渲染）。 |

## 示例
```tsx
<Chrome url="hulian.design" title="瑚琏 Hulian" style={{ width: 375 }}>
  <img src="/screenshot.png" />
</Chrome>
```

## 禁忌 / 坑

- 纯展示外壳，不带宽度默认值，需自行用 `style={{ width }}` 或 className 控制尺寸，否则塌缩到内容宽。
- `imageSrc` 与 `children` 同传时 `imageSrc` 优先，children 被忽略。

## 相关
[Safari](https://hulianui.haloritual.com/components/safari) · [Terminal](https://hulianui.haloritual.com/components/terminal) · [iPhone](https://hulianui.haloritual.com/components/iphone) · [Android](https://hulianui.haloritual.com/components/android) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Watch](https://hulianui.haloritual.com/components/watch)

<!-- ════════════════════════════════════════════════════════ -->
# iPhone

> 手机外壳 · 灵动岛机身包裹屏幕(token themeable) + RSC · mockups/device

## 何时用

把 App 截图 / 移动端页面包进 iPhone 机身（灵动岛）框做展示，落地页、AppStore 配图常用。要安卓打孔屏机身用 [Android](https://hulianui.haloritual.com/components/android)，要平板用 [Tablet](https://hulianui.haloritual.com/components/tablet)，要浏览器窗口框用 [Safari](https://hulianui.haloritual.com/components/safari)/[Chrome](https://hulianui.haloritual.com/components/chrome)。

## 导入
```ts
import { IPhone, IPHONE_MODELS } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`。`IPHONE_MODELS` 导出机型→宽度映射常量。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| model | `"16-pro-max" \| "16-pro" \| "16-plus" \| "16" \| "15-pro" \| "13-mini"` | `"15-pro"`(showcase) | 预设机型，决定默认宽度。 |
| width | `number` | model 预设，无 model 则 `280` | 设备宽度(px)，显式传入时优先于 model。 |
| imageSrc | `string` | — | 屏幕内容图片地址，优先于 children。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 屏幕内容自定义节点。 |

## 示例
```tsx
<IPhone model="15-pro">
  <img src="/app.png" />
</IPhone>
```

## 禁忌 / 坑

- 机身比例由组件内 `aspectRatio` 统一固定，`model`/`width` 只改宽度不改纵横比；想要别的比例需自行外层裁切。
- `imageSrc` 与 `children` 同传时 `imageSrc` 优先。

## 相关
[Android](https://hulianui.haloritual.com/components/android) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Watch](https://hulianui.haloritual.com/components/watch) · [Safari](https://hulianui.haloritual.com/components/safari) · [Chrome](https://hulianui.haloritual.com/components/chrome) · [Terminal](https://hulianui.haloritual.com/components/terminal)

<!-- ════════════════════════════════════════════════════════ -->
# Safari

> 浏览器外壳 · 顶栏红绿灯+地址栏包裹截图 + RSC · mockups/window

## 何时用

把网页截图 / live 内容包进一个 macOS Safari 风格的窗口框，用于落地页展示、文档配图。它只有红绿灯+地址栏的极简顶栏；要带标签页 + 前进/后退/刷新工具栏用 [Chrome](https://hulianui.haloritual.com/components/chrome)，要命令行风格用 [Terminal](https://hulianui.haloritual.com/components/terminal)，要手机/平板机身用 [iPhone](https://hulianui.haloritual.com/components/iphone)/[Tablet](https://hulianui.haloritual.com/components/tablet)。

## 导入
```ts
import { Safari } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`（`className`、`style` 等照常透传，常用 `style={{ width }}` 控宽）。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| url | `string` | `"hulian.design"` | 地址栏文本。 |
| imageSrc | `string` | — | 内容区图片地址，优先于 children。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 内容区自定义节点（imageSrc 未传时渲染）。 |

## 示例
```tsx
<Safari url="hulian.design" style={{ width: 375 }}>
  <img src="/screenshot.png" />
</Safari>
```

## 禁忌 / 坑

- 纯展示外壳，不带宽度默认值，需自行用 `style={{ width }}` 或 className 控制尺寸，否则塌缩到内容宽。
- `imageSrc` 与 `children` 同传时 `imageSrc` 优先，children 被忽略。

## 相关
[Chrome](https://hulianui.haloritual.com/components/chrome) · [Terminal](https://hulianui.haloritual.com/components/terminal) · [iPhone](https://hulianui.haloritual.com/components/iphone) · [Android](https://hulianui.haloritual.com/components/android) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Watch](https://hulianui.haloritual.com/components/watch)

<!-- ════════════════════════════════════════════════════════ -->
# Tablet

> 平板外壳 · iPad 系机身(model 预设尺寸/比例·token themeable) + RSC · mockups/device

## 何时用

把 App / 网页截图包进 iPad 系平板机身框做展示，覆盖 iPad Pro / Air / mini 系机型（各机型纵横比不同）。要手机机身用 [iPhone](https://hulianui.haloritual.com/components/iphone)/[Android](https://hulianui.haloritual.com/components/android)，要浏览器窗口框用 [Safari](https://hulianui.haloritual.com/components/safari)/[Chrome](https://hulianui.haloritual.com/components/chrome)。

## 导入
```ts
import { Tablet, TABLET_MODELS } from "@hulianui/ui"
```

## Props

继承 `ComponentPropsWithoutRef<"div">`。`TABLET_MODELS` 导出机型→`{ width, aspectRatio }` 映射常量。

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| model | `"ipad-pro-13" \| "ipad-pro-11" \| "ipad-air-11" \| "ipad-10" \| "ipad-mini"` | `"ipad-pro-11"`(showcase) | 预设机型，决定默认宽度与机身比例。 |
| width | `number` | model 预设，无 model 则 `320` | 设备宽度(px)，显式传入时优先覆盖宽度。 |
| imageSrc | `string` | — | 屏幕内容图片地址，优先于 children。 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children | `ReactNode` | 屏幕内容自定义节点。 |

## 示例
```tsx
<Tablet model="ipad-pro-11">
  <img src="/app.png" />
</Tablet>
```

## 禁忌 / 坑

- 与 iPhone/Android 不同：平板机型纵横比各异，`aspectRatio` 由 `model` 决定；`width` 显式传入只覆盖宽度，比例仍随 model。不传 model 时回退默认宽 320 但无机型专属比例。
- `imageSrc` 与 `children` 同传时 `imageSrc` 优先。

## 相关
[iPhone](https://hulianui.haloritual.com/components/iphone) · [Android](https://hulianui.haloritual.com/components/android) · [Watch](https://hulianui.haloritual.com/components/watch) · [Safari](https://hulianui.haloritual.com/components/safari) · [Chrome](https://hulianui.haloritual.com/components/chrome) · [Terminal](https://hulianui.haloritual.com/components/terminal)

<!-- ════════════════════════════════════════════════════════ -->
# Terminal

> 终端框 · mac 窗口外壳 + 命令行逐行揭示(motion + tone) + 语法着色(命令名/flag/URL/数字) · mockups/window · #animated

## 何时用

展示安装命令、CLI 输出、构建日志等终端片段，逐行动画揭示并按 tone 着色（命令/输出/成功），常用于落地页「快速开始」「安装」段落。这是只读的视觉演示框，不是可交互终端（要真终端能力另寻 xterm 类方案）；要包网页截图用 [Safari](https://hulianui.haloritual.com/components/safari)/[Chrome](https://hulianui.haloritual.com/components/chrome)。

## 导入
```ts
import { Terminal } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| lines* | `TerminalLine[]` | — | 要逐行揭示的行数组（见下表）。 |
| lineDelay | `number` | — | 相邻行揭示间隔(s)。 |
| title | `string` | — | 标题栏文字。 |
| highlight | `boolean` | `true` | 命令行/输出行语法着色（命令名/--flag/URL/数字/引号串走 --code-* token）；仅对 text 为字符串的 command/muted 行生效，success 等整行 tone 色不拆。 |
| className | `string` | — | 透传到根容器。 |

`TerminalLine`：
| 字段 | 类型 | 说明 |
|------|------|------|
| text* | `ReactNode` | 行文本。 |
| prompt | `string` | 行首提示符（如 `"$"`、`">"`），缺省无。 |
| tone | `"command" \| "muted" \| "success"` | 该行语气：command(前景) / muted(次要输出) / success。 |

## 示例
```tsx
<Terminal
  lines={[
    { prompt: "$", text: "pnpm add @hulianui/ui", tone: "command" },
    { text: "✓ 安装完成", tone: "success" },
    { prompt: "$", text: "pnpm dev", tone: "command" },
    { text: "▲ Next.js ready on http://localhost:5512", tone: "muted" },
  ]}
/>
```

## 禁忌 / 坑

- 语法着色只对 `text` 为字符串且 tone 为 command/muted 的行拆词；传 ReactNode 或 success 行整行用 tone 色，不再二次着色。
- 逐行揭示是 motion 客户端动画，宿主文件需是 `"use client"`（组件本身已声明）。

## 相关
[Safari](https://hulianui.haloritual.com/components/safari) · [Chrome](https://hulianui.haloritual.com/components/chrome) · [iPhone](https://hulianui.haloritual.com/components/iphone) · [Android](https://hulianui.haloritual.com/components/android) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Watch](https://hulianui.haloritual.com/components/watch)

<!-- ════════════════════════════════════════════════════════ -->
# Watch

> 手表外壳 · Apple Watch 系 squircle 表壳+数码表冠(model 预设尺寸) + RSC · mockups/device

## 何时用

需要把表盘内容（截图或自渲染 UI）放进 Apple Watch 风格的设备外壳里展示时用。配套 [iPhone](https://hulianui.haloritual.com/components/iphone) / [Tablet](https://hulianui.haloritual.com/components/tablet) 等设备框：手机/平板用对应组件，手表场景用本组件。

## 导入
```ts
import { Watch, WATCH_MODELS } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `model` | `"ultra-49" \| "series-45" \| "se-44" \| "series-41"` | `"se-44"`（无 width 且无 model 时按 184px） | 预设机型，决定默认表壳宽度 |
| `width` | `number` | model 预设宽度，否则 184 | 表壳宽度 px；显式传入时优先于 model |
| `imageSrc` | `string` | — | 表盘内容图片地址，优先于 children |

> 继承 `ComponentPropsWithoutRef<"div">`（className、style 等可透传）。`WATCH_MODELS` 导出各机型对应的表壳宽度映射（ultra-49→210、series-45→190、se-44→184、series-41→172）。

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `children` | `ReactNode` | 表盘内容（imageSrc 未传时渲染） |

## 示例
```tsx
<Watch model="series-45">
  <img src="/face.png" />
</Watch>
```

## 禁忌 / 坑
暂无已知坑。设备外壳为纯展示组件（RSC 可用），imageSrc 与 children 同时存在时 imageSrc 胜出。

## 相关
[iPhone](https://hulianui.haloritual.com/components/iphone) · [Android](https://hulianui.haloritual.com/components/android) · [Tablet](https://hulianui.haloritual.com/components/tablet) · [Safari](https://hulianui.haloritual.com/components/safari) · [Chrome](https://hulianui.haloritual.com/components/chrome) · [Terminal](https://hulianui.haloritual.com/components/terminal)


# ━━━━━━━━ 移动端 ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# ActionSheet

> 动作面板 · 建在 Base UI Dialog 底滑(同 Drawer 范式·motion token CSS 镜像) + 动作即 Close + 危险态 + 独立取消块 + 安全区 · mobile/overlay

## 何时用

移动端从底部弹出一组列表式动作（保存/分享/删除等）并带独立「取消」块时用。常驻悬浮的单个主操作用 [Fab](https://hulianui.haloritual.com/components/fab)；从底部选时间/地区等多列滚轮值用 [Picker](https://hulianui.haloritual.com/components/picker)。

## 导入
```ts
import { ActionSheet, ActionSheetTrigger, ActionSheetClose, ActionSheetContent } from "@hulianui/ui"
```

## Props

`ActionSheet`（= Base UI `Dialog.Root` props，受控/非受控 open、onOpenChange 等照常）；`ActionSheetTrigger` / `ActionSheetClose` 透传对应 Base UI Dialog 部件。

**ActionSheetContent — Props**

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `actions` * | `ActionSheetAction[]` | — | 动作列表（见下）；点击任一动作即关闭面板 |
| `container` | `HTMLElement \| null` | `document.body` | portal 挂载容器；传某祖先（如手机框，且其 transform/overflow-hidden）可把遮罩+面板约束在容器内 |
| `className` | `string` | — | — |

**ActionSheetAction**：`key: string` · `label: ReactNode` · `description?: ReactNode`（小字说明）· `danger?: boolean`（红色危险动作）· `disabled?: boolean` · `onClick?: () => void`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onOpenChange` | `(open: boolean) => void` | `ActionSheet`（Dialog.Root）开关状态变化时触发（透传 Base UI Dialog） |

## Slots

`ActionSheetContent` 的内容注入槽：

| 插槽 | 类型 | 说明 |
|------|------|------|
| `title` | `ReactNode` | 顶部标题 |
| `description` | `ReactNode` | 标题下说明 |
| `cancelText` | `ReactNode \| null` | 取消按钮文案（默认「取消」），传 `null` 隐藏取消块 |

## 示例
```tsx
<ActionSheet>
  <ActionSheetTrigger>打开</ActionSheetTrigger>
  <ActionSheetContent
    title="图片操作"
    actions={[
      { key: "save", label: "保存" },
      { key: "delete", label: "删除", danger: true },
    ]}
  />
</ActionSheet>
```

## 禁忌 / 坑
- 点击任一 action 会先触发其 `onClick` 再自动关闭面板（动作即 Close），不需手动 close。
- 默认 portal 到 `document.body`；要「画框内弹层」必须给 `container` 指向那个有 `transform` 或 `overflow-hidden` 的祖先，否则遮罩会铺满整个视口。

## 相关
[TabBar](https://hulianui.haloritual.com/components/tab-bar) · [Fab](https://hulianui.haloritual.com/components/fab) · [Picker](https://hulianui.haloritual.com/components/picker) · [SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)

<!-- ════════════════════════════════════════════════════════ -->
# Fab

> 悬浮操作钮 · fixed 贴边 + speed-dial 子动作错峰展开/主钮旋 45°(零依赖·reduced-motion) · mobile/nav

## 何时用

页面内单一主操作（如新建、回到顶部、分享）需要常驻悬浮入口时用；多个相关动作可挂 speed-dial 展开。全局一级页签切换用 [TabBar](https://hulianui.haloritual.com/components/tab-bar)；点击后弹出一组列表动作并需取消按钮用 [ActionSheet](https://hulianui.haloritual.com/components/action-sheet)。

## 导入
```ts
import { Fab } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `label` | `string` | — | 主按钮文字（extended 胶囊态）；提供后主钮变「图标+文字」自适应胶囊，并默认作 aria-label |
| `actions` | `FabAction[]` | — | speed-dial 子动作；提供则点击主钮展开/收起，否则直接触发 onClick |
| `position` | `"bottom-right" \| "bottom-left" \| "bottom-center"` | `"bottom-right"` | 贴边位置 |
| `size` | `"sm" \| "md"` | `"md"` | md=56px 主钮，sm=48px（紧凑场景） |
| `draggable` | `boolean` | `false` | 按住拖动重定位（位移 >3px 视为拖拽，该次不触发 onClick） |
| `aria-label` | `string` | `"操作"` | 主按钮无障碍标签 |
| `className` | `string` | — | — |

**FabAction**：`key: string` · `icon: ReactNode` · `label?: string`（展开时显示在图标侧并作 aria-label）· `onClick?: () => void`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onClick` | `() => void` | 无 actions 时的主按钮点击 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `icon` | `ReactNode` | 主按钮图标（默认 Plus）；展开 speed-dial 时旋转 45° |

## 示例
```tsx
<Fab
  actions={[
    { key: "search", icon: <Search />, label: "搜索" },
    { key: "share", icon: <Share />, label: "分享" },
  ]}
/>
```

## 禁忌 / 坑
- 默认 `fixed` 贴视口角落，gallery / 容器内演示时用 `className` 覆盖为 `absolute` 收进框内（容器需 `position: relative` + `overflow-hidden`）。
- 给了 `actions` 时点击主钮是展开/收起子动作，`onClick` 不再触发；只有不给 actions 时主钮才直接触发 `onClick`。
- `draggable` 下若拖拽位移超过 3px，本次抬手不会触发点击（避免拖完误触）。

## 相关
[TabBar](https://hulianui.haloritual.com/components/tab-bar) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [Picker](https://hulianui.haloritual.com/components/picker) · [SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)

<!-- ════════════════════════════════════════════════════════ -->
# Picker

> 滚轮选择器 · 多列 CSS scroll-snap 吸附 + 即时高亮居中项 + 停稳防抖 emit + 受控滚定位(零依赖·H5 选时间/地区) · mobile/input

## 何时用

H5 / 移动端从一组有限离散值里选一项或多列联动值（时:分、省/市/区）时用，iOS 风格滚轮交互。弹出层式的列表动作选择用 [ActionSheet](https://hulianui.haloritual.com/components/action-sheet)；通常把 Picker 放进 ActionSheet 或底部抽屉里呈现。

## 导入
```ts
import { Picker } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `columns` * | `PickerColumn[]` | — | 各列配置（见下） |
| `value` | `string[]` | — | 各列选中值数组（受控） |
| `defaultValue` | `string[]` | 各列首项 | 非受控初始值 |
| `visibleCount` | `number` | `5` | 可见行数（建议奇数） |
| `itemHeight` | `number` | `40` | 行高 px |
| `className` | `string` | — | — |

**PickerColumn**：`options: PickerOption[]` · `flex?: number`（列宽 flex 比重，默认 1）。
**PickerOption**：`label: ReactNode` · `value: string`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onChange` | `(value: string[], columnIndex: number) => void` | 某列选定后回调（完整值数组 + 变化的列下标） |

## 示例
```tsx
const [val, setVal] = useState(["9", "30"]);

<Picker columns={[hours, minutes]} value={val} onChange={setVal} />
```

## 禁忌 / 坑
- `value` / `defaultValue` 是**字符串数组**，每项对应一列、值须命中该列 `options` 的某个 `value`；列数与 `columns` 长度一致。
- 受控下 `onChange` 在滚动停稳（防抖）后才 emit，并带变化的列下标；高亮居中是即时的，但回调不是每帧触发。

## 相关
[TabBar](https://hulianui.haloritual.com/components/tab-bar) · [Fab](https://hulianui.haloritual.com/components/fab) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)

<!-- ════════════════════════════════════════════════════════ -->
# PullToRefresh

> 下拉刷新 · 置顶下拉带阻尼 + 过阈进 armed + 松手触发并保持刷新态至 Promise 结束回弹(零依赖·Pointer Events) · mobile/gesture

## 何时用

可滚动列表/页面置顶时下拉触发刷新数据时用。列表行横滑露出操作按钮用 [SwipeAction](https://hulianui.haloritual.com/components/swipe-action)；本组件只管纵向下拉刷新这一手势。

## 导入
```ts
import { PullToRefresh } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `threshold` | `number` | `64` | 触发刷新的下拉阈值 px |
| `resistance` | `number` | `0.5` | 下拉阻尼系数（0-1，越小越「沉」） |
| `className` | `string` | — | — |

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onRefresh` * | `() => Promise<void> \| void` | 触发刷新回调；返回 Promise 期间保持「刷新中」，结束后回弹 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `children` * | `ReactNode` | 可滚动内容 |
| `pullingText` | `ReactNode` | 下拉中文案 |
| `armedText` | `ReactNode` | 越过阈值待释放时的文案 |
| `refreshingText` | `ReactNode` | 刷新中文案 |

## 示例
```tsx
<PullToRefresh onRefresh={async () => { await load(); }}>
  <List />
</PullToRefresh>
```

## 禁忌 / 坑
- `onRefresh` 想让指示器在加载期间持续显示，必须**返回 Promise** 并在数据就绪后 resolve；返回 void 会立即回弹，看不到刷新态。
- 只在内容滚到顶部时下拉才进入手势，中途滚动不会误触发。

## 相关
[SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [TabBar](https://hulianui.haloritual.com/components/tab-bar) · [Fab](https://hulianui.haloritual.com/components/fab) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [Picker](https://hulianui.haloritual.com/components/picker) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)

<!-- ════════════════════════════════════════════════════════ -->
# SafeArea

> 安全区适配 · env(safe-area-inset-*) 作 padding/margin 应用到指定边 + min 兜底 + as 多态(零依赖·RSC·刘海/底部横条) · mobile/layout

## 何时用

页面边缘内容（顶栏避刘海、底栏避 Home 横条）需要避开设备安全区时用，纯布局原语。底部主导航直接用 [TabBar](https://hulianui.haloritual.com/components/tab-bar)（已内置吃安全区）；只有自定义贴边元素才单独包 SafeArea。

## 导入
```ts
import { SafeArea } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `edges` | `SafeAreaEdge[] \| "all" \| "vertical" \| "horizontal"` | `"all"` | 应用哪几条安全区 inset；`SafeAreaEdge = "top"\|"right"\|"bottom"\|"left"` |
| `mode` | `"padding" \| "margin"` | `"padding"` | padding=撑开自身，margin=外推 |
| `min` | `number \| string` | `0` | 每条 inset 的最小值（数字=px 或任意 CSS 长度），env 取不到时兜底 |
| `as` | `ElementType` | `"div"` | 多态根元素 |

> 继承 `HTMLAttributes<HTMLElement>`（className、style、children 等可透传）。

## 示例
```tsx
<SafeArea edges="all" min={0}>
  <Content />
</SafeArea>
```

## 禁忌 / 坑
- 桌面端 `env(safe-area-inset-*)` 恒为 0，要在非刘海设备上看到留白须给 `min`（如 `min={16}`）兜底——这也是真机无安全区时的兜底间距。
- `min` 给数字按 px，也可传任意 CSS 长度字符串（如 `"1rem"`）。

## 相关
[TabBar](https://hulianui.haloritual.com/components/tab-bar) · [Fab](https://hulianui.haloritual.com/components/fab) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [Picker](https://hulianui.haloritual.com/components/picker) · [SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh)

<!-- ════════════════════════════════════════════════════════ -->
# SwipeAction

> 列表项滑动操作 · 内容层 translateX 跟手 + 左/右动作面板 + 过半吸附全开/回弹 + 主轴判定放行纵向滚动(零依赖·Pointer Events) · mobile/gesture

## 何时用

列表行需要横滑露出「删除/置顶/标记已读」等操作按钮时用（微信会话列表式交互）。整列下拉触发刷新用 [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh)；行内常驻按钮直接放内容里即可，不必滑动。

## 导入
```ts
import { SwipeAction } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `left` | `SwipeActionButton[]` | — | 左滑出（内容右移）时显示的动作 |
| `right` | `SwipeActionButton[]` | — | 右滑出（内容左移）时显示的动作 |
| `threshold` | `number` | `0.5` | 松手触发完全展开的阈值（占动作区宽度比例 0-1） |
| `className` | `string` | — | — |

**SwipeActionButton**：`key: string` · `label: ReactNode` · `tone?: "default" \| "primary" \| "danger" \| "success" \| "warning"`（背景色调，默认 default）· `onClick?: () => void`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onOpenChange` | `(side: "left" \| "right" \| null) => void` | 展开/收起回调（null=收起） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| `children` * | `ReactNode` | 行内容（跟手 translateX 的内容层） |

## 示例
```tsx
<SwipeAction
  left={[{ key: "read", label: "已读", tone: "primary" }]}
  right={[{ key: "del", label: "删除", tone: "danger" }]}
>
  <Row />
</SwipeAction>
```

## 禁忌 / 坑
- 用 Pointer Events 做主轴判定：横向位移占优才接管为滑动，纵向占优会放行给外层列表滚动——所以放在可滚动列表里不会卡住纵向滚动。
- `threshold` 是比例（0-1）不是像素：松手时横滑超过动作区宽度的该比例才吸附全开，否则回弹收起。

## 相关
[PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh) · [TabBar](https://hulianui.haloritual.com/components/tab-bar) · [Fab](https://hulianui.haloritual.com/components/fab) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [Picker](https://hulianui.haloritual.com/components/picker) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)

<!-- ════════════════════════════════════════════════════════ -->
# TabBar

> 底部导航栏 · items 驱动受控/非受控 + 激活 text-primary/aria-current + 角标/红点 + 吃底部安全区(零依赖·H5 主导航) · mobile/nav

## 何时用

H5 / 移动端的全局主导航（首页/发现/我的等几个一级页签贴底切换）时用。临时性、单页内的悬浮操作入口用 [Fab](https://hulianui.haloritual.com/components/fab)；一次性列出多个动作并要弹层确认用 [ActionSheet](https://hulianui.haloritual.com/components/action-sheet)。

## 导入
```ts
import { TabBar } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `items` * | `TabBarItem[]` | — | 页签数据（见下） |
| `value` | `string` | — | 受控激活 key |
| `defaultValue` | `string` | 首项 key | 非受控初始 key |
| `safeArea` | `boolean` | `true` | 吃底部安全区 inset |
| `fixed` | `boolean` | `true` | fixed 贴底；false 则随文档流 |
| `className` | `string` | — | — |

**TabBarItem**：`key: string` · `label: ReactNode` · `icon?: ReactNode`（默认态图标）· `activeIcon?: ReactNode`（激活态，缺省复用 icon）· `dot?: boolean`（红点）· `badge?: ReactNode`（角标，优先于 dot）· `disabled?: boolean`。

## Events

| 事件 | 类型 | 说明 |
|------|------|------|
| `onChange` | `(key: string) => void` | 切换页签回调 |

## 示例
```tsx
const [tab, setTab] = useState("home");

<TabBar
  value={tab}
  onChange={setTab}
  items={[
    { key: "home", label: "首页", icon: <Home /> },
    { key: "me", label: "我的", icon: <User />, badge: 5 },
  ]}
/>
```

## 禁忌 / 坑
- 默认 `fixed` 贴视口底 + 吃底部安全区。放进手机框/容器内演示时须 `fixed={false}` 收进文档流，否则会飘到整页底部；容器内不需要安全区时再加 `safeArea={false}`。
- `badge` 与 `dot` 同时给时 `badge` 优先。

## 相关
[Fab](https://hulianui.haloritual.com/components/fab) · [ActionSheet](https://hulianui.haloritual.com/components/action-sheet) · [Picker](https://hulianui.haloritual.com/components/picker) · [SwipeAction](https://hulianui.haloritual.com/components/swipe-action) · [PullToRefresh](https://hulianui.haloritual.com/components/pull-to-refresh) · [SafeArea](https://hulianui.haloritual.com/components/safe-area)


# ━━━━━━━━ uncatalogued ━━━━━━━━

<!-- ════════════════════════════════════════════════════════ -->
# Access

> 声明式权限门禁：有权限渲染 children，否则渲染 fallback（默认隐藏）。 · uncatalogued

## 何时用

按钮 / 菜单项 / 区块按当前用户权限条件渲染时用它包一层，避免散落的 `hasPermission && <X/>` 判断。须先在外层挂 `AccessProvider` 注入权限集合；命令式判定（如 `if`/useEffect 里）用 `useAccess()` hook 而非本组件。

## 导入
```ts
import { Access } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| permission | `string ｜ string[]` | — | 需要的权限；与 accessible 二选一，accessible 优先 |
| mode | `"all" ｜ "any"` | `"all"` | 数组权限匹配模式：all=全部具备 / any=任一具备（单字符串无效） |
| accessible | `boolean ｜ ((access: AccessContextValue) => boolean)` | — | 自定义判定（优先于 permission） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 有权限时渲染的内容 |
| fallback | `ReactNode` | 无权限时渲染的内容（默认 `null`，即隐藏） |

> 须配套 `<AccessProvider permissions={...}>`（`permissions` 接 `string[]` 或 `Set`）在外层注入权限集合；持有 `"*"` 通配符视为超管放行任意检查。

## 示例
```tsx
// 应用最外层注入权限集合（登录后拿到）
<AccessProvider permissions={["user:read", "user:delete"]}>
  <App />
</AccessProvider>

// 业务里条件渲染
<Access permission="user:delete" fallback={<Tooltip>无权限</Tooltip>}>
  <Button tone="danger">删除</Button>
</Access>

// 多权限任一即可
<Access permission={["order:export", "order:admin"]} mode="any">
  <Button>导出</Button>
</Access>
```

## 禁忌 / 坑

- 判定优先级 `accessible > permission > 无约束(恒放行)`：三者都不传时**恒放行**，别误以为无 permission 会拦截。
- 必须在 `AccessProvider` 子树内使用，否则 `useAccess()` 拿不到权限集合。
- 前端门禁只是 UX 兜底，**不是安全边界**——后端接口须独立鉴权，别把隐藏当授权。

## 相关
—

<!-- ════════════════════════════════════════════════════════ -->
# Callout

> 文章 / 文档用提示框（admonition）。 · uncatalogued

## 何时用

长文 / 文档内联强调「Tip / 坑 / 正解 / 警告」，只让标题+图标着 tone 色、正文保持 foreground 可读（左 accent 竖边 + 极浅 tone 底）。要整块染 tone 色的通知横幅用 Alert；Callout 专为正文阅读流里的克制提示。

## 导入
```ts
import { Callout } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| tone | `"tip"｜"info"｜"warning"｜"success"｜"danger"` | `"tip"` | 语气：tip/info 主色、warning 警告、success 正解、danger 坑/危险 |
| className | `string` | — | 透传到根容器 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| icon | `ReactNode` | 图标 slot（emoji 或 SVG；设计系统不绑图标库） |
| title | `ReactNode` | 标题（tone 色强调） |
| children | `ReactNode` | 正文（foreground 可读） |

## 示例
```tsx
<Callout tone="warning" icon="⚠️" title="注意">
  这一步会改写已有数据，操作前先备份。
</Callout>

<Callout tone="danger" title="坑">
  裸 <code>var(--primary)</code> 喂给 SVG fill 不解析，须带 --color- 前缀。
</Callout>
```

## 禁忌 / 坑

- 纯皮肤组件，只消费语义 token（含 success/warning/danger）；改色请改主题 token，别在此打内联 style。
- `title`/`icon` 都不传时只渲染正文区（无标题行），适合纯一段提示。

## 相关
—

<!-- ════════════════════════════════════════════════════════ -->
# Config

> 全局配置根：当前承载 i18n（locale），后续渐进扩展默认尺寸/主题等全局项。 · uncatalogued

## 何时用

应用最外层注入全局 Locale（i18n 文案），裹在与 ThemeProvider 同层。组件级文案覆盖请就近传 prop，不用为单点改 Provider；主题/暗色由 ThemeProvider 负责，Config 当前只管 locale。

## 导入
```ts
import { ConfigProvider } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| locale | `Locale` | `zhCN` | 全局 Locale（用导出的 zhCN/enUS 或 spread 自定义） |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 子树 |

## 示例
```tsx
import { ConfigProvider } from "@hulianui/ui";
// zhCN / enUS 同包导出

// 应用最外层，与 ThemeProvider 同层
<ConfigProvider locale={enUS}>
  <App />
</ConfigProvider>

// 缺省即 zhCN，可不传 locale
<ConfigProvider>
  <App />
</ConfigProvider>
```

## 禁忌 / 坑

- 当前仅承载 locale；不要期望它接管尺寸/主题（按设计后续在同一 Provider 渐进扩展）。
- 自定义 locale 建议 spread 内置 `zhCN`/`enUS` 再覆盖，避免漏键。

## 相关
—

<!-- ════════════════════════════════════════════════════════ -->
# Theme

>  · uncatalogued

## 何时用

在应用根部包一层 `ThemeProvider`，统一管理亮/暗/跟随系统的主题状态，并把解析后的主题写到 `<html data-theme>` 供 CSS token 消费。需要在子组件里读/切主题时配套用 `useTheme()` hook（如主题切换按钮）。本组件只管 React 侧的状态与 `data-theme` 同步，不负责首屏防闪烁——视觉主题的首帧由页面里的 anti-FOUC inline 脚本设的 `data-theme` + CSS 驱动，Provider 在 mount 后做校正。

## 导入
```ts
import { ThemeProvider } from "@hulianui/ui"
```

## Props

| 名称 | 类型 | 默认 | 说明 |
|------|------|------|------|
| defaultSetting | `"light" \| "dark" \| "system"` | `"system"` | 初始主题偏好；mount 时若 localStorage(`hulian-theme`) 有存值则被其覆盖 |
| forcedTheme | `"light" \| "dark"` | — | 强制主题（如按路由定主题）：覆盖用户偏好与系统监听；期间 `setTheme`/`toggle` 仍写入偏好但不改变视觉 |

## Slots

| 插槽 | 类型 | 说明 |
|------|------|------|
| children* | `ReactNode` | 被包裹的子树 |

`useTheme()` 返回的 context 值：`theme`（解析后的实际主题 `"light"|"dark"`）、`setting`（用户选择，含 `"system"`）、`setTheme(s)`、`toggle()`。

## 示例

```tsx
// 应用根
import { ThemeProvider } from "@hulianui/ui";

export function App({ children }: { children: React.ReactNode }) {
  return <ThemeProvider defaultSetting="system">{children}</ThemeProvider>;
}
```

```tsx
// 子组件里切主题（主题切换按钮）
"use client";
import { useTheme } from "@hulianui/ui";

export function ThemeToggle() {
  const { theme, toggle } = useTheme();
  return <button onClick={toggle}>{theme === "dark" ? "切到亮色" : "切到暗色"}</button>;
}
```

## 禁忌 / 坑

- `useTheme()` 必须在 `ThemeProvider` 子树内调用，否则抛 `"useTheme must be used within ThemeProvider"`。
- 该组件是 `"use client"` 客户端组件，须挂在客户端边界内（Next.js App Router 下别直接放进纯 server 组件树）。
- 首渲 `theme` 取确定值（`system` 解析为 `light`），不在 SSR/首帧调 `systemTheme()`，以免主题相关渲染（如 toggler 图标）触发 hydration mismatch（React #418）；真实主题由 mount effect 立即校正。因此别依赖首帧的 `theme` 值做关键渲染分支。
- 传了 `forcedTheme` 后视觉被锁定：`setTheme`/`toggle` 只写偏好不改 `data-theme`，切主题 UI 在强制期看起来"无效"是预期行为。
- 候选坑 skill（MUI/emotion/rehype/theme-factory 系）均针对其它技术栈的主题方案，与本组件的 `data-theme` + CSS 变量机制无关，不适用。

## 相关
—