@endfield-ui/react 0.2.0 → 1.0.0

package/NOTICE.md

@@ -5,7 +5,7 @@
 ## 归属
 
 - 《明日方舟：终末地》（Arknights: Endfield）的名称、标志、角色、美术、界面、字体及其他一切官方素材，版权与商标权归鹰角网络及其权利人所有。
-- 本仓库以 [MIT License](LICENSE) 发布的范围**仅限仓库内的原创内容**：文档文字、原创 SVG 图解、设计令牌与（后续的）组件代码。
+- 本仓库以 [MIT License](LICENSE) 发布的范围**仅限仓库内的原创内容**：文档文字、原创 SVG 图解、设计令牌、组件代码与原创图标。
 
 ## 本仓库不包含
 
@@ -17,7 +17,7 @@
 
 ## 使用本项目时请注意
 
-- 本项目提供的是"受终末地视觉语言启发"的设计规范，不是官方设计规范，也不代表官方立场。
+- 本项目提供的是"受终末地视觉语言启发"的设计规范和按它实现的组件库，不是官方设计规范，也不代表官方立场。
 - 请不要用它制作可能被误认为官方产品、官方公告或官方周边的内容。
 - 公开发布或商业使用衍生作品前，请自行确认符合鹰角网络的同人创作与素材使用政策；截至本文档撰写时，我们没有检索到针对《终末地》的官方同人创作规范原文，以官方最新公告为准。
 - 权利人如认为本仓库内容不妥，请通过 Issue 联系，我们会及时处理。

package/README.md

@@ -10,11 +10,11 @@
 | 表单 | Field、Input、OtpInput、Textarea、Select、Combobox、TagInput、DatePicker / DateRangePicker / Calendar、FileUpload / FileItem、Checkbox、Radio / RadioGroup、SegmentedControl、Switch、Stepper、Slider、FilterChip |
 | 反馈 | Alert、Toast、Progress / ProgressRing、Spinner、Skeleton、EmptyState、Loader、CompletionBanner、RecIndicator |
 | 浮层 | Tooltip、Popover、HoverCard、Dialog、Drawer、DropdownMenu、ContextMenu、FlyoutBar |
-| 展示 | Table（行能展开）、Stat、Sparkline、DataRowList / DataRow、List / ListRow、Accordion、ScrollArea、MediaCard、PlayButton / PlayMark、Carousel、ImageViewer、ItemSlot / ItemGrid、Avatar、Timeline、Schedule、Term、ResourceChip、Countdown、Marquee、ScrollHint |
+| 展示 | Table（行能展开）、Stat、RollingNumber、Sparkline、DataRowList / DataRow、List / ListRow、Accordion、ScrollArea、MediaCard、PlayButton / PlayMark、Carousel、ImageViewer、ItemSlot / ItemGrid、Avatar、Timeline、Schedule、Term、ResourceChip、Countdown、Marquee、ScrollHint |
 | 导航 | SideRail（含二级）、TopBar、NavMenu、NavAction、PageHeader、Breadcrumb、Pagination、Navigator、AvatarSwitcher、DashIndicator、Steps、Toc、BackToTop |
 | 母题 | CornerBrackets、Viewfinder、GhostText、Hatch、Texture、RegistrationStrip、TickRing、HazardStripe |
 
-每个控件的变体与状态见[在线预览](https://icaruszezen.github.io/endfield-ui/)。
+每个控件的变体与状态见[在线预览](https://icaruszezen.github.io/endfield-ui/)；各版本改了什么见[更新记录](https://github.com/icaruszezen/endfield-ui/blob/main/CHANGELOG.md)。
 
 ## 安装
 
@@ -22,7 +22,10 @@
 pnpm add @endfield-ui/react
 ```
 
-需要 React 19。走 `tailwind.css` 入口的项目还要有 Tailwind CSS v4，用预编译的 `styles.css` 则不需要。包只出 ESM。
+需要 React 19。走 `tailwind.css` 入口的项目还要有 Tailwind CSS v4，用预编译的 `styles.css` 则不需要。包只出 ESM，带类型声明。
+
+- 浏览器的底线和 Tailwind CSS v4 相同（Chrome 111、Safari 16.4、Firefox 128 起）。更新的特性只用在过渡上：不支持视图过渡、`@starting-style` 的浏览器少的是那一下过渡，功能照常。
+- 1.0.0 起版本号按语义化版本走。
 
 ## 技术栈
 
@@ -31,7 +34,7 @@ pnpm add @endfield-ui/react
 | 框架 | React 19 + TypeScript |
 | 样式 | Tailwind CSS v4（CSS-first，`@theme` 令牌，不使用 `tailwind.config.js`） |
 | 变体 | 手写的 `Record<Variant, string>` + `cn()`（`clsx` + `tailwind-merge`） |
-| 无障碍基元 | [Base UI](https://base-ui.com)（`@base-ui/react`），用在浮层和几个行为复杂的控件上：文字提示、气泡卡片、弹窗、抽屉、全屏菜单、轻提示、下拉选择、组合框、下拉菜单、右键菜单、展开条、折叠面板、滑块、头像。其余控件建立在原生元素上（月历是手写的：Base UI 还没有公开的日历基元） |
+| 无障碍基元 | [Base UI](https://base-ui.com)（`@base-ui/react`），用在浮层和几个行为复杂的控件上：文字提示、气泡卡片、悬浮卡、弹窗、抽屉、全屏菜单、图片查看的大图层、轻提示、下拉选择、组合框、日期选择的面板、下拉菜单、右键菜单、展开条、折叠面板、侧轨的二级、工具栏、滑块、验证码输入、滚动区、头像。其余控件建立在原生元素上（月历是手写的：Base UI 还没有公开的日历基元） |
 | 构建 | tsdown（ESM + 类型声明）+ `@tailwindcss/cli`（预编译 CSS） |
 | 测试 | Vitest + Testing Library（jsdom） |
 
@@ -267,6 +270,43 @@ import {
 - 只有图标的钮必须有 `aria-label`。`ToolbarButton` 可以交给 `DropdownMenu` / `Popover` 的 `trigger`，也可以用 `Tooltip` 包住。
 - 不在工具栏里放输入框：左右方向键在输入框里是移光标。
 
+### 反馈
+
+```tsx
+import {
+  Alert,
+  Button,
+  EmptyState,
+  Progress,
+  ProgressRing,
+  Skeleton,
+} from "@endfield-ui/react";
+
+<Alert tone="danger" title="有两项没有填对" open={invalid} onClose={() => setInvalid(false)}>
+  改正标红的字段之后再保存。
+</Alert>
+
+<Progress value={62} showValue aria-label="同步进度" />
+<Progress segments={6} value={3} showValue aria-label="建站步骤" />
+<ProgressRing value={75} showValue aria-label="载重" />
+
+<Button loading loadingText="保存中">保存</Button>
+
+<Skeleton variant="text" lines={3} />
+
+<EmptyState
+  title="暂无记录"
+  description="完成一次任务后，这里会出现记录。"
+  action={<Button>新建任务</Button>}
+/>
+```
+
+- `Alert` 是常驻在页面里的提示条，色调只点在左缘的色条和图标上。传了 `onClose` 才有关闭图标；显示与否由你决定——把 `open` 置为 `false`，它先收起、淡出再卸载（之后触发 `onExited`），直接不渲染它就是立刻消失。
+- `Progress`、`ProgressRing` 不传 `value` 就是"不确定进度"。步骤数明确时用 `segments` 把轨道切成小段。
+- 等的时间短、位置小的用 `Spinner`；按钮的 `loading` 里就是它，按钮的尺寸不变、不响应点击。
+- `Skeleton` 自己对读屏隐藏，"正在加载"由外层区域的 `aria-busy="true"` 说。
+- 一闪而过、不需要处理的消息用轻提示（见下面的[浮层](#浮层)）；盖住整页的等待用加载页。
+
 ### 加载页
 
 `Loader` 默认铺满视口，并在加载期间锁住页面滚动和焦点。内容就绪后把 `open` 置为 `false`，遮罩滑出、随后自己卸载：
@@ -292,6 +332,7 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
   IconButton,
+  Lock,
   Tooltip,
 } from "@endfield-ui/react";
 
@@ -642,10 +683,22 @@ import { Toc, TocItem } from "@endfield-ui/react";
 </Toc>
 ```
 
-- 滚到哪一节哪一项亮（`aria-current="location"`）；滚到底是最后一项。点一项就是点一个锚点链接，滚不滚、平不平滑由浏览器和页面的 CSS 决定。
+- 滚到哪一节哪一项亮（`aria-current="location"`）；滚到底是最后一项。点一项仍然是点一个锚点链接（地址、后退都是原生的），只是这一次跳转滚得平滑；系统开了"减少动态效果"时直接跳。
 - 页面有吸顶的页头时 `offset` 传它的高度，并给各节的标题加同样大小的 `scroll-mt-*`。内容在某个滚动容器里时传 `target`。
 - 位置自己给（`sticky`）；窄屏放不下时由页面收起来。
 
+要被一眼看到的数字用统计块：
+
+```tsx
+import { RollingNumber, Stat } from "@endfield-ui/react";
+
+<Stat label="在线站点" value={<RollingNumber value={1280} />} unit="座" delta="+6%" />
+<Stat label="待处理批次" value="07" delta="−2" trend="down" />
+```
+
+- `label` 前面的 `//` 由组件加；`delta` 连同正负号一起传，`trend="down"` 时是危险色。
+- `RollingNumber` 进入视口时从 0 滚到终值，一次；值后来变了直接换。读屏读到的、打印和服务端渲染出来的都是终值。默认带千分位，换写法用 `format`。
+
 ### 游戏风格的控件
 
 物品格的宽度跟着所在的网格走。格子里只有图标，`name` 是给读屏的名称；选中是四角的角括号，画在格子之外 4px。一组格子放进 `ItemGrid`：它自带留好空隙的网格，并且整个矩阵只占一个 Tab 停靠点，进去之后用方向键在格子之间走。
@@ -763,12 +816,54 @@ function ThemeToggle() {
 }
 ```
 
-`useTheme` 读写 `<html data-theme>`，支持 `"light"`、`"dark"`、`"system"`，选择记在 `localStorage` 的 `ef-theme` 里。要避免首屏闪一下亮色，在 `<head>` 里用一小段内联脚本提前把 `data-theme` 写好。
+`useTheme` 读写 `<html data-theme>`，支持 `"light"`、`"dark"`、`"system"`，选择记在 `localStorage` 的 `ef-theme` 里。亮暗变了的时候整页交叉淡化一次（200ms；浏览器要支持视图过渡，系统开了"减少动态效果"时直接切）——这时候 `<html>` 上的属性和钩子返回的值是晚一帧才变的。要避免首屏闪一下亮色，在 `<head>` 里用一小段内联脚本提前把 `data-theme` 写好。
 
 把强调色换成自己的主题色，见 [色彩](https://github.com/icaruszezen/endfield-ui/blob/main/docs/design/foundations/color.md) 的"主题色接管"。
 
 还有第三个取值 `data-theme="inverse"`：和所在的主题相反。面板的标题带、表格的表头带、完成横幅用的就是它，所以放进去的按钮、复选框、焦点环不用另外处理。自己做一块"和页面相反"、里面还要放控件的区域时，写 `data-theme="inverse"` 加 `bg-surface text-ink`——取到的就是 `surface-inverse` / `ink-inverse`。反转块里不要再嵌反转块。
 
+### 动效
+
+动效是控件自带的，不用配置：状态变了有过渡（勾和圆点淡入、选中的墨块滑过去、明细按高度展开、删掉的一项淡出、其余的补位），浮层从触发它的那一侧来。都在 0.2 – 0.3 秒里做完，没有回弹，悬停不放大。
+
+- **只播一次的入场**带一个 `animate` 属性，默认开，传 `animate={false}` 关掉：`SectionTitle`、`BracketTitle`、`PageHeader`、`CompletionBanner`、`EmptyState`、`Sparkline`、`RollingNumber`。反过来默认关着的有两个：`Progress`（入场时充填一次）和 `Viewfinder`（取景角落位）。
+- **系统开了"减少动态效果"时全部停在终态。** CSS 的动画和过渡由样式入口末尾的一条全局规则统一降级；脚本驱动的几处（滚动数字、平滑滚动、主题的交叉淡化）各自看系统设置。你自己写脚本驱动的动效时用 `useReducedMotion()`。
+- 时长、缓动、位移量都是令牌（`--duration-fast`、`--ease-exit`、`--motion-shift`…），各自的用途见 [动效规范](https://github.com/icaruszezen/endfield-ui/blob/main/docs/design/foundations/motion.md)。
+
+### 无障碍
+
+- **键盘。** 每个能点的控件都能用键盘操作，有 `:focus-visible` 的焦点环。成组的控件（页签、分段选择、头像切换、工具栏、物品格矩阵、验证码输入）整组只占一个 Tab 停靠点，进去之后用方向键走。弹窗、抽屉、菜单这类浮层打开时焦点移入，关上时还给触发元素。
+- **读屏。** 能用原生元素的都用原生元素；纯图标的控件必须给 `aria-label`（`IconButton` 在类型上就是必填的）；装饰（竖条、括号、纹理、巨字）对读屏隐藏。状态不只靠颜色说：错误同时有图标和文字，四种提示的图标外形各不相同。
+- **高对比模式**（Windows 的对比度主题，CSS 的 `forced-colors`）。系统会把底色统一换成页面色，所以凡是靠底色成形的地方——"选中"的墨块、进度条、滑块、按钮的外形——都另写了一份用系统色的画法。是在 Chromium 的模拟下逐个核对的，对应关系见 [色彩](https://github.com/icaruszezen/endfield-ui/blob/main/docs/design/foundations/color.md#高对比模式)。
+- **触屏。** 悬停的样式只在有指针的设备上生效；靠悬停才出现的东西（表格的行内操作）在触屏上常显。
+- 对比度按各主题里最不利的常用表面验算过，见 [色彩](https://github.com/icaruszezen/endfield-ui/blob/main/docs/design/foundations/color.md#对比度)。
+
+### 图标与工具
+
+控件自己用到的二十个图标一并导出（`Close`、`Check`、`Plus`、`Minus`、`ChevronDown`、`ArrowRight`、`Lock`、`Menu`、`CalendarIcon`、`Upload`…），全是原创的；清单见 [icons/README.md](src/icons/README.md)。它们接受 `size` 与 `className`，颜色跟着文字走，默认对读屏隐藏。业务上要的图标用 `createIcon` 照同一套画法做（24 网格、2px 描边、平头端点、尖角拐角）：
+
+```tsx
+import { createIcon, IconButton } from "@endfield-ui/react";
+
+const Route = createIcon("Route", <path d="M5 19V9l7-4 7 4v10" />);
+
+<IconButton aria-label="路线">
+  <Route size={20} />
+</IconButton>
+```
+
+另外导出的几样：
+
+| 导出 | 作用 |
+| --- | --- |
+| `cn()` | 合并类名（`clsx` + `tailwind-merge`），认得本库自定义的令牌名。给控件传 `className` 覆盖内置类时，库里用的就是它 |
+| `useTheme()` | 读写主题，见上面的[主题](#主题) |
+| `useReducedMotion()` | 系统开了"减少动态效果"时返回 `true` |
+| `useInView()` | 返回 `[ref, inView]`：元素第一次进入视口后是 `true`，之后不再变回去——自己做"只播一次"的入场时用 |
+| `useControllableState()` | 受控 / 非受控合并，自己写带状态的控件时用 |
+| `usePortalScope()` | 自己用 Base UI 拼浮层时，把触发处的局部主题带到挂在 `<body>` 下的浮层上 |
+| `useFieldControl()`、`useFieldContext()` | 把自定义控件接进 `Field`：拿到该落在控件上的 `id`、`disabled`、`required`、`invalid` 和 `aria-describedby` |
+
 ## 目录
 
 ```
@@ -804,8 +899,8 @@ TypeScript 用的是 7.0。tsdown 在这个版本下生成类型声明时会提
 
 ### 发布
 
-1. 改本目录 `package.json` 里的 `version`，提交并推到 `main`，等 CI 跑完。
-2. 打一个和版本号对应的标签推上去：`git tag v0.2.0`，`git push origin v0.2.0`。
+1. 改本目录 `package.json` 里的 `version`，在根目录的 [CHANGELOG.md](https://github.com/icaruszezen/endfield-ui/blob/main/CHANGELOG.md) 里写上这一版改了什么，提交并推到 `main`，等 CI 跑完。
+2. 打一个和版本号对应的标签推上去：`git tag v1.0.0`，`git push origin v1.0.0`。
 3. [publish.yml](https://github.com/icaruszezen/endfield-ui/blob/main/.github/workflows/publish.yml) 核对标签与版本号，跑类型检查、测试与构建（`prepublishOnly`），然后发布到 npm。
 
 认证用的是 npm 的 Trusted Publishing，仓库里不存 token：npm 上这个包的设置里登记了本仓库和 `publish.yml` 这个文件名，两边任何一个改名都要同步。

package/dist/index.d.ts

@@ -55,15 +55,22 @@ type AlertProps = Omit<ComponentProps<"div">, "title"> & {
   title?: ReactNode;
   /** 右侧的一个操作，通常是 `text` 按钮 */
   action?: ReactNode;
-  /** 传了就出现关闭图标。提示条自己不隐藏，由使用方决定 */
+  /**
+   * 传了就出现关闭图标。它只负责通知：显示与否由使用方决定——
+   * 要收起的过程，把 `open` 交给提示条；直接不渲染它就是立刻消失
+   */
   onClose?: () => void;
+  /** 置为 `false` 时先收起、淡出，再卸载。默认 `true` */
+  open?: boolean;
+  /** 收完、已经卸载之后触发 */
+  onExited?: () => void;
   /** 关闭图标的可访问名称 */
   closeLabel?: string;
   /** 替换默认图标；传 `null` 去掉 */
   icon?: ReactNode;
 };
 /** 页面内的一条常驻消息。需要用户处理的重要信息用它，不用会消失的轻提示。 */
-export declare function Alert({ tone, title, action, onClose, closeLabel, icon, className, children, ...props }: AlertProps): import("react").JSX.Element;
+export declare function Alert({ tone, title, action, onClose, open, onExited, closeLabel, icon, className, ref, children, ...props }: AlertProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/components/avatar/Avatar.d.ts
 type AvatarSize = "sm" | "md" | "lg" | "xl";
@@ -170,6 +177,8 @@ export declare function Badge({ count, max, showZero, dot, label, className, chi
 type BracketTitleProps = Omit<ComponentProps<"h3">, "children"> & {
   /** 标题层级，默认 3（`<h3>`） */
   level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** 进入视口时播放一次入场：括号先到，名称随后。默认开启 */
+  animate?: boolean;
   /** 名称 */
   children: ReactNode;
 };
@@ -177,7 +186,7 @@ type BracketTitleProps = Omit<ComponentProps<"h3">, "children"> & {
  * 方括号标题 `[ 名称 ]`：人物、地点、物品的名称——"一个被归档的条目"。
  * 普通的分节标题用 `SectionTitle`。字号用 `className` 改，默认是名称用的 `text-4xl`。
  */
-export declare function BracketTitle({ level, className, children, ...props }: BracketTitleProps): import("react").JSX.Element;
+export declare function BracketTitle({ level, animate, className, children, ref, ...props }: BracketTitleProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/link-element/LinkElement.d.ts
 /** 用来代替 `<a>` 的元素，通常是路由库的链接组件：`<Link to="/archive" />` */
@@ -528,6 +537,8 @@ type CompletionBannerProps = Omit<ComponentProps<"div">, "title"> & {
   action?: ReactNode;
   /** 标题层级，默认 3（`<h3>`） */
   level?: 2 | 3 | 4 | 5 | 6;
+  /** 进入视口时播放一次入场：色带从左擦入，随后出字。默认开启 */
+  animate?: boolean;
 };
 /**
  * 完成横幅：一个阶段全部完成时，头部区域做一次明暗反转。
@@ -536,7 +547,7 @@ type CompletionBannerProps = Omit<ComponentProps<"div">, "title"> & {
  * 底是反转块：亮色主题下是深底黄字，暗色主题下是浅底深字。
  * 整块是一个 `data-theme="inverse"` 的局部主题，`action` 里的按钮按这块底色取值。
  */
-export declare function CompletionBanner({ title, word, description, action, level, className, children, ...props }: CompletionBannerProps): import("react").JSX.Element;
+export declare function CompletionBanner({ title, word, description, action, level, animate, className, children, ref, ...props }: CompletionBannerProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/context-menu/ContextMenu.d.ts
 type ContextMenuVariant = MenuVariant;
@@ -578,6 +589,7 @@ type CornerBracketsProps = ComponentProps<"div"> & {
  * 用于矩阵里的单选（物品格、名册卡、图鉴）；列表行用左缘色条，页签用底色，都不用它。
  *
  * 括号画在盒子之外 4px：它所在的容器不能贴着盒子裁切。
+ * 出现时八段短线从角的顶点伸到满长（200ms），消失是直接消失。
  * 括号只是给眼睛看的，选中态另外要有 `aria-selected` / `aria-pressed`。
  */
 export declare function CornerBrackets({ visible, size, className, ...props }: CornerBracketsProps): import("react").JSX.Element;
@@ -999,9 +1011,11 @@ type EmptyStateProps = Omit<ComponentProps<"div">, "title"> & {
   bordered?: boolean;
   /** 标题层级，默认 3（`<h3>`） */
   level?: 2 | 3 | 4 | 5 | 6;
+  /** 挂上时淡入一次，不"啪"地一下出现。默认开启 */
+  animate?: boolean;
 };
 /** 没有内容时的占位。说清楚为什么为空、接下来能做什么；不要用大幅插画填满。 */
-export declare function EmptyState({ title, description, action, icon, bordered, level, className, children, ...props }: EmptyStateProps): import("react").JSX.Element;
+export declare function EmptyState({ title, description, action, icon, bordered, level, animate, className, children, ...props }: EmptyStateProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/field/Field.d.ts
 type FieldContextValue = {
@@ -1531,7 +1545,7 @@ type LoaderProps = Omit<ComponentProps<"div">, "children"> & {
  * 加载页：近黑底、大号等宽百分比、一行标语、黄色进度条。只用于整页的首次加载。
  * 不伪造进度；内容就绪后立刻把 `open` 置为 `false`，不要为了播完动画而等待。
  */
-export declare function Loader({ value, tagline, open, fullscreen, label, onExited, onKeyDown, onTransitionEnd, className, ...props }: LoaderProps): import("react").JSX.Element | null;
+export declare function Loader({ value, tagline, open, fullscreen, label, onExited, onKeyDown, className, ref, ...props }: LoaderProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/components/marquee/Marquee.d.ts
 type MarqueeProps = ComponentProps<"div"> & {
@@ -1667,7 +1681,7 @@ type ItemOwnProps$2 = {
 };
 type NavMenuItemProps = ItemOwnProps$2 & Omit<ComponentProps<"li">, keyof ItemOwnProps$2>;
 /** 全屏菜单里的一个栏目。 */
-export declare function NavMenuItem({ icon, current, disabled, closeOnClick, href, target, rel, render, onClick, children, ...props }: NavMenuItemProps): import("react").JSX.Element;
+export declare function NavMenuItem({ icon, current, disabled, closeOnClick, href, target, rel, render, onClick, className, children, ...props }: NavMenuItemProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/navigator/Navigator.d.ts
 type NavigatorSize = "sm" | "md";
@@ -1766,6 +1780,8 @@ type PageHeaderProps = Omit<ComponentProps<"header">, "title"> & {
    * 上面还有吸顶的顶栏时用 `className` 改 `top`
    */
   sticky?: boolean;
+  /** 挂上时播放一次入场：微文字行 → 标题 → 说明。默认开启；`sticky` 时不播 */
+  animate?: boolean;
   /** 标题下面的一行：页签、几个统计块 */
   children?: ReactNode;
 };
@@ -1773,7 +1789,7 @@ type PageHeaderProps = Omit<ComponentProps<"header">, "title"> & {
  * 页头：这是哪一页、怎么回去、在这一页能做什么。一页一个。
  * 按自身的宽度响应：行动区放不下时折到标题下面。
  */
-export declare function PageHeader({ title, level, meta, description, breadcrumb, back, actions, divider, sticky, className, children, ...props }: PageHeaderProps): import("react").JSX.Element;
+export declare function PageHeader({ title, level, meta, description, breadcrumb, back, actions, divider, sticky, animate, className, children, ...props }: PageHeaderProps): import("react").JSX.Element;
 type BackOwnProps = {
   /** 默认"返回"。建议写成"返回某某" */
   "aria-label"?: string;
@@ -2011,6 +2027,29 @@ type RegistrationStripProps = Omit<ComponentProps<"div">, "children"> & {
  */
 export declare function RegistrationStrip({ orientation, rule, className, ...props }: RegistrationStripProps): import("react").JSX.Element;
 //#endregion
+//#region src/components/rolling-number/RollingNumber.d.ts
+type RollingNumberProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 终值 */
+  value: number;
+  /**
+   * 把数值写成字。默认带千分位（`1,280`），小数位数跟着 `value`。
+   * 滚的过程中每一帧都会调它
+   */
+  format?: (value: number) => string;
+  /** 进入视口时从 0 滚到终值，一次。默认开启 */
+  animate?: boolean;
+};
+/**
+ * 滚动数字：进入视口时从 0 滚到终值，只滚一次。放进 `Stat` 的 `value` 里，
+ * 或者任何"一个需要被一眼看到的数字"的地方。等宽数字由所在处给（`tabular-nums`）。
+ *
+ * - 读屏只读终值：终值一直在，滚的时候只是看不见；滚动的那一份对读屏隐藏。
+ * - 宽度由终值占着，滚的时候旁边的东西不动。
+ * - 服务端渲染出来的、打印出来的、"减少动态效果"下的，都直接是终值。
+ * - 值后来变了直接换，不再滚。
+ */
+export declare function RollingNumber({ value, format, animate, className, ref, ...props }: RollingNumberProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/schedule/Schedule.d.ts
 type ScheduleProps = Omit<ComponentProps<"div">, "aria-label"> & {
   /** 这张排期的名称。横向能滚动时，滚动的那一块用它 */
@@ -2192,7 +2231,7 @@ type SegmentedControlProps = Omit<ComponentProps<"div">, "onChange" | "defaultVa
  *
  * 切换的是下面显示哪一块内容时用 `Tabs`，不是它。
  */
-export declare function SegmentedControl({ value, defaultValue, onValueChange, name, size, variant, disabled: disabledProp, required: requiredProp, invalid: invalidProp, className, ...props }: SegmentedControlProps): import("react").JSX.Element;
+export declare function SegmentedControl({ value, defaultValue, onValueChange, name, size, variant, disabled: disabledProp, required: requiredProp, invalid: invalidProp, className, ref, ...props }: SegmentedControlProps): import("react").JSX.Element;
 type SegmentOwnProps = {
   value: string;
   /** 文字左边的图标。只有图标时要给 `aria-label` */
@@ -2498,12 +2537,14 @@ type SparklineProps = Omit<ComponentProps<"svg">, "children"> & {
   max?: number;
   /** 传了它就是一张有名称的图；不传是纯装饰，对读屏隐藏 */
   label?: string;
+  /** 进入视口时从左画出一次。默认开启 */
+  animate?: boolean;
 };
 /**
  * 行内的小型图表：没有坐标轴、网格和图例，只有一块面积或一条折线。
  * 撑满给它的盒子（默认高 32px、通宽）。它旁边应该有数字——图只是帮着看趋势。
  */
-export declare function Sparkline({ data, variant, tone, min, max, label, className, ...props }: SparklineProps): import("react").JSX.Element;
+export declare function Sparkline({ data, variant, tone, min, max, label, animate, className, ref, ...props }: SparklineProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/spinner/Spinner.d.ts
 type SpinnerSize = "sm" | "md";
@@ -2761,7 +2802,7 @@ type TabsOwnProps = {
 type TabsProps = Omit<ComponentProps<"div">, keyof TabsOwnProps> & TabsOwnProps;
 export declare function Tabs({ value, defaultValue, onValueChange, variant, size, ...props }: TabsProps): import("react").JSX.Element;
 type TabListProps = ComponentProps<"div">;
-export declare function TabList({ className, onKeyDown, ...props }: TabListProps): import("react").JSX.Element;
+export declare function TabList({ className, onKeyDown, ref, ...props }: TabListProps): import("react").JSX.Element;
 type TabProps = Omit<ComponentProps<"button">, "value"> & {
   value: string;
 };
@@ -2769,7 +2810,10 @@ export declare function Tab({ value, disabled, className, children, onClick, ...
 type TabPanelProps = ComponentProps<"div"> & {
   value: string;
 };
-/** 未选中的面板保留一个隐藏的空容器，让页签的 `aria-controls` 始终有所指。 */
+/**
+ * 未选中的面板保留一个隐藏的空容器，让页签的 `aria-controls` 始终有所指。
+ * 切过来的面板淡入；一开始就选中的那一块不动。
+ */
 export declare function TabPanel({ value, className, children, ...props }: TabPanelProps): import("react").JSX.Element;
 //#endregion
 //#region src/components/tag/Tag.d.ts
@@ -3022,8 +3066,9 @@ type TocProps = TocOwnProps & Omit<ComponentProps<"nav">, keyof TocOwnProps>;
 /**
  * 页内目录：这一页有哪几节、现在看到了哪一节。里面放 `TocItem`。
  *
- * 位置由使用方给，通常是 `className="sticky top-6"`。点一项就是点一个锚点链接：
- * 滚不滚、平不平滑是浏览器和页面 CSS 的事，它不接管滚动。
+ * 位置由使用方给，通常是 `className="sticky top-6"`。点一项仍然是点一个锚点链接——
+ * 地址、后退、`scroll-mt` 都是浏览器原生的那一套；它只让这一次跳转滚得平滑
+ * （系统开了"减少动态效果"时照旧直接跳）。
  */
 export declare function Toc({ title, offset, target, onActiveChange, "aria-label": ariaLabel, className, ref, children, ...props }: TocProps): import("react").JSX.Element;
 type TocItemOwnProps = {
@@ -3212,6 +3257,12 @@ type ViewfinderProps = ComponentProps<"div"> & {
   size?: ViewfinderSize;
   /** 正中放一个小准星，标出焦点 */
   crosshair?: boolean;
+  /**
+   * 挂上的时候取景角落位：八段短线各自从角上伸出来，播一次。
+   * 默认不动——取景角平时是静态的装饰。要它晚一点再动（等外面那一层先淡入完），
+   * 在外层设 `--bracket-delay`
+   */
+  animate?: boolean;
   /**
    * 四个角上的读数：坐标、比例、版本、时间码。
    * 必须是真实的数据；没有就不放。
@@ -3224,7 +3275,7 @@ type ViewfinderProps = ComponentProps<"div"> & {
  *
  * 只用在展示性的画面上，一屏一处。取景角与准星是装饰，读数是真实信息、读屏读得到。
  */
-export declare function Viewfinder({ size, crosshair, readouts, className, children, ...props }: ViewfinderProps): import("react").JSX.Element;
+export declare function Viewfinder({ size, crosshair, animate, readouts, className, children, ...props }: ViewfinderProps): import("react").JSX.Element;
 //#endregion
 //#region src/hooks/useControllableState.d.ts
 type Options$1<T> = {
@@ -3248,6 +3299,15 @@ type Options = {
  */
 export declare function useInView<T extends Element = Element>({ disabled, rootMargin, threshold }?: Options): [RefObject<T | null>, boolean];
 //#endregion
+//#region src/hooks/useReducedMotion.d.ts
+/**
+ * 系统开了"减少动态效果"时返回 true，设置变了会跟着变。
+ *
+ * CSS 的动画和过渡不用它：`theme.css` 末尾的全局规则已经统一降级了。
+ * 只有脚本驱动的动效（一帧一帧自己算的）才要看它——那条规则管不到脚本。
+ */
+export declare function useReducedMotion(): boolean;
+//#endregion
 //#region src/hooks/useTheme.d.ts
 type Theme = "light" | "dark";
 type ThemePreference = Theme | "system";
@@ -3260,7 +3320,8 @@ type Snapshot = {
  *
  * - `theme`：用户的选择，可以是 `"system"`；
  * - `resolvedTheme`：实际生效的 `"light"` 或 `"dark"`；
- * - `setTheme`：切换并记到 `localStorage`。
+ * - `setTheme`：切换并记到 `localStorage`。亮暗变了的时候整页交叉淡化一次
+ *   （浏览器支持视图过渡、系统没开"减少动态效果"时；否则直接切）。
  */
 export declare function useTheme(): Snapshot & {
   setTheme: (theme: ThemePreference) => void;
@@ -3442,4 +3503,4 @@ export declare const Upload: {
 //#region src/lib/cn.d.ts
 export declare function cn(...inputs: ClassValue[]): string;
 //#endregion
-export type { AccordionItemProps, AccordionLevel, AccordionProps, AccordionSize, AlertProps, AlertTone, AvatarProps, AvatarSize, AvatarSwitcherItemProps, AvatarSwitcherOrientation, AvatarSwitcherProps, BackToTopProps, BackToTopSize, BadgeProps, BracketTitleProps, BreadcrumbItemProps, BreadcrumbProps, ButtonGroupAlign, ButtonGroupGap, ButtonGroupOrientation, ButtonGroupProps, ButtonProps, ButtonSize, ButtonVariant, CalendarProps, CalendarRangeProps, CalendarSingleProps, CarouselProps, CarouselRatio, CarouselSlideProps, CheckboxProps, ComboboxMultipleProps, ComboboxOption, ComboboxOptionGroup, ComboboxProps, ComboboxSingleProps, ComboboxSize, ComboboxVariant, CompletionBannerProps, ContextMenuProps, ContextMenuVariant, CornerBracketsProps, CornerBracketsSize, CountdownProps, CountdownSize, CountdownState, DashIndicatorProps, DataRowColumns, DataRowListProps, DataRowProps, DataRowTone, DatePickerProps, DatePickerSize, DatePickerVariant, DateRange, DateRangePickerProps, DialogCloseProps, DialogProps, DialogSize, DrawerProps, DrawerSide, DrawerSize, DropdownMenuAlign, DropdownMenuCheckboxItemProps, DropdownMenuGroupProps, DropdownMenuItemProps, DropdownMenuItemTone, DropdownMenuProps, DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps, DropdownMenuSeparatorProps, DropdownMenuSide, DropdownMenuSubProps, DropdownMenuVariant, EmptyStateProps, FieldProps, FileItemProps, FileItemStatus, FileRejectReason, FileRejection, FileUploadLabels, FileUploadProps, FileUploadSize, FilterChipProps, FlyoutBarItemProps, FlyoutBarProps, FlyoutBarSide, GhostTextProps, GhostTextVariant, HatchDensity, HatchProps, HazardStripeProps, HazardStripeSize, HoverCardAlign, HoverCardProps, HoverCardSide, IconButtonProps, IconButtonSize, IconButtonVariant, IconProps, ImageViewerItemProps, ImageViewerProps, ImageViewerRatio, InputProps, InputSize, InputVariant, ItemGridProps, ItemSlotProps, ItemSlotRarity, ItemSlotRatio, KbdProps, KbdSize, ListProps, ListRowProps, ListRowSize, ListVariant, LoaderProps, MarqueeProps, MediaCardProps, MediaCardRatio, NavActionLayout, NavActionProps, NavMenuItemProps, NavMenuProps, NavigatorProps, NavigatorSize, OtpInputProps, OtpInputSize, OtpInputType, OtpInputVariant, PageHeaderBackProps, PageHeaderProps, PaginationProps, PaginationSize, PanelBodyProps, PanelHeaderProps, PanelHeaderVariant, PanelProps, PanelRowProps, PanelRowsProps, PlayButtonProps, PlayMarkProps, PlayMarkSize, PopoverAlign, PopoverCloseProps, PopoverProps, PopoverSide, ProgressProps, ProgressRingProps, ProgressSize, RadioGroupOrientation, RadioGroupProps, RadioProps, RecIndicatorProps, RegistrationStripOrientation, RegistrationStripProps, ResourceChipProps, ResourceChipSize, ScheduleItemProps, ScheduleItemVariant, ScheduleProps, ScheduleTrackProps, ScrollAreaOrientation, ScrollAreaProps, ScrollHintProps, ScrollHintVariant, SectionTitleProps, SectionTitleVariant, SegmentProps, SegmentedControlProps, SegmentedControlSize, SegmentedControlVariant, SelectGroupProps, SelectItemProps, SelectMultipleProps, SelectOption, SelectProps, SelectSeparatorProps, SelectSingleProps, SelectSize, SelectVariant, SideRailGroupProps, SideRailItemProps, SideRailProps, SideRailSubItemProps, SideRailSubProps, SkeletonProps, SkeletonVariant, SliderMark, SliderProps, SliderRangeProps, SliderSingleProps, SliderSize, SparklineProps, SparklineTone, SparklineVariant, SpinnerProps, SpinnerSize, StatProps, StatSize, StatTrend, StepProps, StepStatus, StepStatusLabels, StepperProps, StepperSize, StepsOrientation, StepsProps, StepsSize, SwitchProps, TabListProps, TabPanelProps, TabProps, TableAlign, TableBodyProps, TableCellProps, TableExpanderProps, TableHeadProps, TableHeaderCellProps, TableHeaderVariant, TableProps, TableRowProps, TableSize, TableSortDirection, TabsProps, TabsSize, TabsVariant, TagInputLabels, TagInputProps, TagInputRejectReason, TagInputSize, TagInputVariant, TagPairProps, TagProps, TagSize, TagVariant, TermProps, TermTone, TextareaProps, TextureProps, TextureVariant, Theme, ThemePreference, TickRingProps, TimelineItemProps, TimelineProps, TimelineStatus, ToastAction, ToastApi, ToastOptions, ToastPlacement, ToastProviderProps, ToastTone, TocItemProps, TocLevel, TocProps, ToolbarButtonProps, ToolbarGroupProps, ToolbarOrientation, ToolbarProps, ToolbarSeparatorProps, ToolbarSize, ToolbarToggleGroupProps, ToolbarToggleProps, ToolbarVariant, TooltipAlign, TooltipProps, TooltipProviderProps, TooltipSide, TopBarProps, ViewfinderProps, ViewfinderReadouts, ViewfinderSize };
+export type { AccordionItemProps, AccordionLevel, AccordionProps, AccordionSize, AlertProps, AlertTone, AvatarProps, AvatarSize, AvatarSwitcherItemProps, AvatarSwitcherOrientation, AvatarSwitcherProps, BackToTopProps, BackToTopSize, BadgeProps, BracketTitleProps, BreadcrumbItemProps, BreadcrumbProps, ButtonGroupAlign, ButtonGroupGap, ButtonGroupOrientation, ButtonGroupProps, ButtonProps, ButtonSize, ButtonVariant, CalendarProps, CalendarRangeProps, CalendarSingleProps, CarouselProps, CarouselRatio, CarouselSlideProps, CheckboxProps, ComboboxMultipleProps, ComboboxOption, ComboboxOptionGroup, ComboboxProps, ComboboxSingleProps, ComboboxSize, ComboboxVariant, CompletionBannerProps, ContextMenuProps, ContextMenuVariant, CornerBracketsProps, CornerBracketsSize, CountdownProps, CountdownSize, CountdownState, DashIndicatorProps, DataRowColumns, DataRowListProps, DataRowProps, DataRowTone, DatePickerProps, DatePickerSize, DatePickerVariant, DateRange, DateRangePickerProps, DialogCloseProps, DialogProps, DialogSize, DrawerProps, DrawerSide, DrawerSize, DropdownMenuAlign, DropdownMenuCheckboxItemProps, DropdownMenuGroupProps, DropdownMenuItemProps, DropdownMenuItemTone, DropdownMenuProps, DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps, DropdownMenuSeparatorProps, DropdownMenuSide, DropdownMenuSubProps, DropdownMenuVariant, EmptyStateProps, FieldProps, FileItemProps, FileItemStatus, FileRejectReason, FileRejection, FileUploadLabels, FileUploadProps, FileUploadSize, FilterChipProps, FlyoutBarItemProps, FlyoutBarProps, FlyoutBarSide, GhostTextProps, GhostTextVariant, HatchDensity, HatchProps, HazardStripeProps, HazardStripeSize, HoverCardAlign, HoverCardProps, HoverCardSide, IconButtonProps, IconButtonSize, IconButtonVariant, IconProps, ImageViewerItemProps, ImageViewerProps, ImageViewerRatio, InputProps, InputSize, InputVariant, ItemGridProps, ItemSlotProps, ItemSlotRarity, ItemSlotRatio, KbdProps, KbdSize, ListProps, ListRowProps, ListRowSize, ListVariant, LoaderProps, MarqueeProps, MediaCardProps, MediaCardRatio, NavActionLayout, NavActionProps, NavMenuItemProps, NavMenuProps, NavigatorProps, NavigatorSize, OtpInputProps, OtpInputSize, OtpInputType, OtpInputVariant, PageHeaderBackProps, PageHeaderProps, PaginationProps, PaginationSize, PanelBodyProps, PanelHeaderProps, PanelHeaderVariant, PanelProps, PanelRowProps, PanelRowsProps, PlayButtonProps, PlayMarkProps, PlayMarkSize, PopoverAlign, PopoverCloseProps, PopoverProps, PopoverSide, ProgressProps, ProgressRingProps, ProgressSize, RadioGroupOrientation, RadioGroupProps, RadioProps, RecIndicatorProps, RegistrationStripOrientation, RegistrationStripProps, ResourceChipProps, ResourceChipSize, RollingNumberProps, ScheduleItemProps, ScheduleItemVariant, ScheduleProps, ScheduleTrackProps, ScrollAreaOrientation, ScrollAreaProps, ScrollHintProps, ScrollHintVariant, SectionTitleProps, SectionTitleVariant, SegmentProps, SegmentedControlProps, SegmentedControlSize, SegmentedControlVariant, SelectGroupProps, SelectItemProps, SelectMultipleProps, SelectOption, SelectProps, SelectSeparatorProps, SelectSingleProps, SelectSize, SelectVariant, SideRailGroupProps, SideRailItemProps, SideRailProps, SideRailSubItemProps, SideRailSubProps, SkeletonProps, SkeletonVariant, SliderMark, SliderProps, SliderRangeProps, SliderSingleProps, SliderSize, SparklineProps, SparklineTone, SparklineVariant, SpinnerProps, SpinnerSize, StatProps, StatSize, StatTrend, StepProps, StepStatus, StepStatusLabels, StepperProps, StepperSize, StepsOrientation, StepsProps, StepsSize, SwitchProps, TabListProps, TabPanelProps, TabProps, TableAlign, TableBodyProps, TableCellProps, TableExpanderProps, TableHeadProps, TableHeaderCellProps, TableHeaderVariant, TableProps, TableRowProps, TableSize, TableSortDirection, TabsProps, TabsSize, TabsVariant, TagInputLabels, TagInputProps, TagInputRejectReason, TagInputSize, TagInputVariant, TagPairProps, TagProps, TagSize, TagVariant, TermProps, TermTone, TextareaProps, TextureProps, TextureVariant, Theme, ThemePreference, TickRingProps, TimelineItemProps, TimelineProps, TimelineStatus, ToastAction, ToastApi, ToastOptions, ToastPlacement, ToastProviderProps, ToastTone, TocItemProps, TocLevel, TocProps, ToolbarButtonProps, ToolbarGroupProps, ToolbarOrientation, ToolbarProps, ToolbarSeparatorProps, ToolbarSize, ToolbarToggleGroupProps, ToolbarToggleProps, ToolbarVariant, TooltipAlign, TooltipProps, TooltipProviderProps, TooltipSide, TopBarProps, ViewfinderProps, ViewfinderReadouts, ViewfinderSize };