@endfield-ui/react 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 球球
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 球球
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,11 +7,11 @@
 | 类别 | 控件 |
 | --- | --- |
 | 基础 | Button / ButtonGroup、IconButton、Toolbar、Tag / TagPair、Badge、Kbd、SectionTitle、BracketTitle、Tabs、Panel |
-| 表单 | Field、Input、Textarea、Select、Combobox、TagInput、DatePicker / DateRangePicker / Calendar、FileUpload / FileItem、Checkbox、Radio / RadioGroup、SegmentedControl、Switch、Stepper、Slider、FilterChip |
+| 表单 | 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、Dialog、Drawer、DropdownMenu、ContextMenu、FlyoutBar |
-| 展示 | Table（行能展开）、Stat、Sparkline、DataRowList / DataRow、List / ListRow、Accordion、MediaCard、PlayButton / PlayMark、Carousel、ItemSlot / ItemGrid、Avatar、Timeline、Schedule、Term、ResourceChip、Countdown、Marquee、ScrollHint |
-| 导航 | SideRail（含二级）、TopBar、NavMenu、NavAction、Breadcrumb、Pagination、Navigator、AvatarSwitcher、DashIndicator、Steps、Toc、BackToTop |
+| 浮层 | 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 |
+| 导航 | 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/)。
@@ -189,6 +189,20 @@ import { Field, FileItem, FileUpload, TagInput } from "@endfield-ui/react";
 - `FileUpload` 只管选和列，不发请求。里面是一个真的 `<input type="file">`：带 `name` 时列表里的文件随表单提交。不合 `accept` / `maxSize` / `maxFiles` 的不收，并在下面说明原因。
 - 选了就要传、要显示进度时，用 `renderFile` 自己返回带状态的那一行：`<FileItem name size status="uploading" progress={40} onRemove={remove} />`。
 
+一格一位的短码用验证码输入：
+
+```tsx
+import { Field, OtpInput } from "@endfield-ui/react";
+
+<Field label="交接口令" help="六位数字，在交接单的右上角。">
+  <OtpInput length={6} groupSize={3} name="code" onComplete={verify} />
+</Field>
+```
+
+- 每一格是一个真的输入框：打一位跳一格，粘贴一整串会分到各格，整组只占一个 Tab 停靠点。值是拼起来的一个字符串，带 `name` 时随表单提交。
+- `type="alphanumeric"` 收字母和数字，`uppercase` 把值统一成大写；`mask` 遮成圆点；`groupSize` 每几格加一道短横。容器窄了格子等比变窄。
+- 不在 `Field` 里时自己传 `aria-label`。
+
 ### 带状态的控件
 
 步进器、分页条、胶囊导航器都有受控与非受控两种用法：传 `value` / `page` / `index` 就由外面决定，只传 `default…` 就由控件自己记。
@@ -267,7 +281,7 @@ import { Loader } from "@endfield-ui/react";
 
 ### 浮层
 
-文字提示、气泡卡片、弹窗、抽屉、下拉菜单、展开条、下拉选择、轻提示。焦点的进出与锁定、键盘、定位与翻转都交给 Base UI，这里只管长相；用的时候不用自己拼部件。触发元素作为一个 React 元素传进去：
+文字提示、气泡卡片、悬浮卡、弹窗、抽屉、下拉菜单、展开条、下拉选择、轻提示。焦点的进出与锁定、键盘、定位与翻转都交给 Base UI，这里只管长相；用的时候不用自己拼部件。触发元素作为一个 React 元素传进去：
 
 ```tsx
 import {
@@ -324,6 +338,7 @@ import {
 - `ContextMenu` 是右键菜单：`<ContextMenu menu={…}>` 包住被右键的那个元素，`menu` 里放的就是上面这些 `DropdownMenuItem`。它只是捷径——里面的操作在页面上要另有入口。
 - `FlyoutBar` 是从一个图标按钮旁边拉开的一条横排操作（分享的几个去处），键盘上是一个横向的菜单。里面放 `FlyoutBarItem`：子元素是图标，只有图标时必须给 `aria-label`。触发按钮用 `<IconButton variant="inverse">`，它的 `aria-label` 同时是这一条的名称。
 - `Popover` 是点击触发、里面可以操作的一小块面板（`trigger`、`title`、`description` + 子元素），不打断页面。一句说明用 `Tooltip`，必须做完才能继续的用 `Dialog`。
+- `HoverCard` 是指针停在一个**链接**上时出来的预览，写法比照 `Popover`（`trigger` 是那个链接），面板也是同一块。触屏上不出现、读屏也不读，所以里面只放点进去也看得到的东西。竖排的一列链接让它出在侧面（`side="right"`），出在下面会盖住下一行的链接。
 - 触发元素要是一个按钮，并且把收到的属性和 `ref` 交给原生元素。本库的 `Button`、`IconButton` 都可以直接用。
 
 下拉选择的触发器和输入框长得一样，放进 `Field` 自动关联标签与错误说明：
@@ -536,11 +551,14 @@ import {
   BackToTop,
   Carousel,
   CarouselSlide,
+  ImageViewer,
+  ImageViewerItem,
   MediaCard,
   PlayButton,
   Schedule,
   ScheduleItem,
   ScheduleTrack,
+  ScrollArea,
 } from "@endfield-ui/react";
 
 <Accordion defaultValue={["route"]}>
@@ -566,6 +584,16 @@ import {
   </CarouselSlide>
 </Carousel>
 
+<ImageViewer aria-label="现场照片">
+  <ImageViewerItem title="三号管廊入口" description="北段复测当天拍的。">
+    <img src={photo} alt="" />
+  </ImageViewerItem>
+</ImageViewer>
+
+<ScrollArea aria-label="值守日志" className="max-h-64">
+  {log}
+</ScrollArea>
+
 <Schedule label="十月排期" start="2026-10-01" end="2026-10-31" today={today}>
   <ScheduleTrack label="测绘" icon={<RouteIcon />}>
     <ScheduleItem start="2026-10-03" end="2026-10-12" title="管廊北段" type="限时" />
@@ -580,10 +608,29 @@ import {
 - `AvatarSwitcher` 是一列头像里选一个，语义是单选组（方向键换人）；放不下时给它一个高度上限。
 - `MediaCard` 的 `video` 在封面左下角加一个播放记号（黄色小方块，`PlayMark`）。记号不能点，整卡仍然只有一个链接；封面要"点了就在原地播放"时用 `PlayButton`，它是真的按钮。
 - `Carousel` 不自动播放。轨道是原生的横向滚动，触屏上直接滑；不在眼前的幻灯片 `Tab` 走不进去。
+- `ImageViewer` 原地是一组缩略图，点一张放大到整屏看：方向键、触屏左右滑翻页，`Esc` 或点图以外的空处关，焦点回到当前那一张的缩略图。大图那一层在两个主题下都是深色。图用 `<img>`，按原比例整张显示；`thumbnail` 可以另给一张小图。
+- `ScrollArea` 是一块限高、自己滚的区域，滚动条是画出来的；高度（或上限）用 `className` 给。只有真的溢出才有滚动条，也才是一个能聚焦的区域，所以 `aria-label` 必填。整页的滚动留给浏览器，不要包。`viewportRef` 交出真正在滚的元素，给 `Toc`、`BackToTop` 的 `target`。
 - `Schedule` 的条目只写起止日期，位置和错行都是算出来的；放不下时在自己的容器里横向滚动。
 - `BackToTop` 滚过 400px 才出现，默认钉在视口右下角；点了回到顶部，焦点也交还给页面的头上。要看某个滚动容器时传 `target`，并用 `className` 改位置。祖先上有 `transform` 或容器查询（`@container`）时 `fixed` 不再相对视口：把它放在那一栏的最后，加 `className="sticky bottom-4 self-end"`。
 - 本库不带任何图片：头像、轮播和排期里的图都由使用方给。
 
+每一页顶上放一个页头：
+
+```tsx
+import { Button, PageHeader, PageHeaderBack } from "@endfield-ui/react";
+
+<PageHeader
+  back={<PageHeaderBack href="/archive" aria-label="返回档案" />}
+  meta="// TR-2041　2026.10.08"
+  title="十月第二批"
+  description="北区仓储站发出，三号管廊转运。"
+  actions={<Button variant="action">签收</Button>}
+/>
+```
+
+- 各格都是可选的：`breadcrumb`（放一个 `Breadcrumb`）、`back`、`meta`、`description`、`actions`，以及标题下面的子元素（页签、几个统计块）。标题默认是 `<h1>`，用 `level` 改。
+- 按自身的宽度响应：`actions` 放不下就整块折到标题下面。`sticky` 吸顶并带实底，上面还有顶栏时用 `className` 改 `top`。
+
 长页面旁边放一列页内目录：
 
 ```tsx
@@ -745,11 +792,14 @@ packages/ui/
 | `pnpm test` | 跑单元测试 |
 | `pnpm test:browser` | 在真的浏览器里测键盘、焦点与布局（先 `pnpm build:docs`），见 [apps/docs](https://github.com/icaruszezen/endfield-ui/blob/main/apps/docs/README.md#浏览器实测) |
 | `pnpm typecheck` | 类型检查全部工作区包 |
+| `pnpm lint` | 用 oxlint 查写错的地方：漏掉的 `await`、钩子的用法、已弃用的接口等 |
 | `pnpm build` | 生成 `dist/index.js`、`dist/index.d.ts`、`dist/styles.css` |
 | `pnpm format` | 用 Prettier 格式化全仓库；`pnpm format:check` 只检查不改，CI 跑的是它 |
 
 格式用 Prettier 的默认配置，提交前跑一次 `pnpm format`。Markdown 不在它的范围里（它会把表格逐列补空格对齐）；Tailwind 的类名顺序也不归它管。
 
+代码检查用 oxlint（配置在根目录的 `.oxlintrc.json`），没用 ESLint：typescript-eslint 还不支持 TypeScript 7，要用就得另装一份 6.x 专门给它；oxlint 里要类型信息的规则和 `tsc` 是同一套编译器。只开"八成是写错了"的那一类规则，风格类的不开。有意为之的写法用 `// oxlint-disable-next-line 规则名 -- 原因` 就地豁免。输出里的提醒（warning）不拦 CI，报错（error）才拦。
+
 TypeScript 用的是 7.0。tsdown 在这个版本下生成类型声明时会提示"API 尚不稳定"，目前产物正常；如果以后出问题，退路是 `tsc --emitDeclarationOnly`。
 
 ### 发布

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 
-import { ComponentProps, HTMLAttributes, MouseEvent, MouseEventHandler, ReactElement, ReactNode, Ref, RefObject } from "react";
+import { CSSProperties, ComponentProps, HTMLAttributes, MouseEvent, MouseEventHandler, ReactElement, ReactNode, Ref, RefObject } from "react";
 import { ClassValue } from "clsx";
 import { Dialog as Dialog$1 } from "@base-ui/react/dialog";
 import { Drawer as Drawer$1 } from "@base-ui/react/drawer";
@@ -1274,6 +1274,39 @@ type HazardStripeProps = Omit<ComponentProps<"div">, "children"> & {
  */
 export declare function HazardStripe({ size, className, ...props }: HazardStripeProps): import("react").JSX.Element;
 //#endregion
+//#region src/components/hover-card/HoverCard.d.ts
+type HoverCardSide = "top" | "bottom" | "left" | "right";
+type HoverCardAlign = "start" | "center" | "end";
+type HoverCardProps = Omit<ComponentProps<"div">, "title" | "children" | "className" | "style"> & {
+  /** 触发元素：一个链接（`<a>`、带 `href` 的按钮、路由库的链接组件） */
+  trigger: ReactElement<Record<string, unknown>>;
+  /** 卡片里的标题 */
+  title?: ReactNode;
+  /** 标题下的一行说明 */
+  description?: ReactNode;
+  /** 卡片出现在链接的哪一侧，放不下时自动翻到对面。默认 `bottom` */
+  side?: HoverCardSide;
+  /** 和链接的哪一边对齐。默认 `start` */
+  align?: HoverCardAlign;
+  /** 指针停住多久后出现，毫秒，默认 600。键盘聚焦时同样要等 */
+  delay?: number;
+  /** 指针离开多久后消失，毫秒，默认 300：够把指针移进卡片里 */
+  closeDelay?: number;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 给卡片 */
+  className?: string;
+  children?: ReactNode;
+};
+/**
+ * 悬浮卡：指针停在一个链接上时，在旁边预览它的去处。面板和气泡卡片是同一块。
+ *
+ * 触屏上不出现，读屏也不会读到它：里面只放"点进去也看得到"的内容，
+ * 不放只有这里才有的信息和操作。要操作的用 `Popover`，一句说明用 `Tooltip`。
+ */
+export declare function HoverCard({ trigger, title, description, side, align, delay, closeDelay, open, defaultOpen, onOpenChange, className, children, ...props }: HoverCardProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/icon-button/IconButton.d.ts
 type IconButtonVariant = "plain" | "floating" | "accent" | "inverse";
 type IconButtonSize = "sm" | "md" | "lg";
@@ -1293,6 +1326,52 @@ type IconButtonProps = Omit<ComponentProps<"button">, "aria-label"> & {
 };
 export declare function IconButton({ variant, size, pressed, disabled, type, className, children, ...props }: IconButtonProps): import("react").JSX.Element;
 //#endregion
+//#region src/components/image-viewer/ImageViewer.d.ts
+type ImageViewerRatio = "16/9" | "4/3" | "1/1" | "3/4";
+type ImageViewerProps = Omit<ComponentProps<"ul">, "aria-label"> & {
+  /** 这组图是什么，比如"现场照片"。缩略图的列表和大图层都用它命名 */
+  "aria-label": string;
+  /** 大图层开没开 */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 大图层现在是第几张，从 0 起 */
+  index?: number;
+  defaultIndex?: number;
+  onIndexChange?: (index: number) => void;
+  /** 到头之后绕回另一头。默认到头时翻页钮禁用 */
+  loop?: boolean;
+  /** 缩略图的宽高比，默认 `4/3`。大图不裁切，按原比例整张显示 */
+  ratio?: ImageViewerRatio;
+  /** 缩略图按钮名称的开头，默认"查看大图" */
+  viewLabel?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+  closeLabel?: string;
+  /** 直接放 `ImageViewerItem` */
+  children: ReactNode;
+};
+/**
+ * 图片查看：一组缩略图，点一张放大到整屏看，前后翻。
+ * 大图那一层在亮暗两个主题下都是深色；翻页用的是媒体轮播的那条轨道，触屏可以左右滑。
+ *
+ * `className` 和其余属性给缩略图的列表。
+ */
+export declare function ImageViewer({ "aria-label": label, open: openProp, onOpenChange, index: indexProp, defaultIndex, onIndexChange, loop, ratio, viewLabel, previousLabel, nextLabel, closeLabel, className, children, ...props }: ImageViewerProps): import("react").JSX.Element;
+type ImageViewerItemProps = Omit<ComponentProps<"li">, "title" | "aria-label"> & {
+  /** 这一张的标题，显示在大图下面；也用来给缩略图按钮起名 */
+  title?: ReactNode;
+  /** 标题下面的一段说明 */
+  description?: ReactNode;
+  /** 另给的小图，放在缩略图里。不传就用同一张图 */
+  thumbnail?: ReactNode;
+  /** 缩略图按钮的可访问名称。默认是"查看大图：标题"，没有文字标题时报第几张 */
+  "aria-label"?: string;
+  /** 图：一个 `<img>`（或 `<video>`）。大图层里按原比例整张显示 */
+  children: ReactNode;
+};
+/** 图片查看里的一张。直接放在 `ImageViewer` 里。 */
+export declare function ImageViewerItem({ title, description: _description, thumbnail, "aria-label": ariaLabel, className, children, ...props }: ImageViewerItemProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/input/Input.d.ts
 type InputSize = ControlSize;
 type InputVariant = ControlVariant;
@@ -1615,6 +1694,105 @@ type NavigatorProps = Omit<ComponentProps<"div">, "children" | "onChange"> & {
  */
 export declare function Navigator({ items, index, defaultIndex, onIndexChange, loop, size, prevLabel, nextLabel, positionLabel, className, ...props }: NavigatorProps): import("react").JSX.Element;
 //#endregion
+//#region src/components/otp-input/OtpInput.d.ts
+type OtpInputType = "numeric" | "alphanumeric";
+type OtpInputSize = ControlSize;
+type OtpInputVariant = ControlVariant;
+type OtpInputProps = Omit<ComponentProps<"div">, "onChange" | "defaultValue" | "children"> & {
+  /** 一共几位，默认 6 */
+  length?: number;
+  /** 拼起来的那一串 */
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 每一位都填上了。粘贴一整串也算 */
+  onComplete?: (value: string) => void;
+  /** 收哪些字符：`numeric` 只收数字，默认；`alphanumeric` 收字母和数字 */
+  type?: OtpInputType;
+  /** 字母统一成大写：值也是大写，不只是看起来 */
+  uppercase?: boolean;
+  /** 把填进去的字遮成圆点 */
+  mask?: boolean;
+  /** 每几格之间加一道短横，如 6 位的码写 `3` 分成两组。只是画的 */
+  groupSize?: number;
+  /** 32 / 40 / 56px 见方 */
+  size?: OtpInputSize;
+  /** 同输入框：`sunken` 凹陷的底 + 底边线，默认；`outline` 四边描边 */
+  variant?: OtpInputVariant;
+  /** 错误态：每一格的边线变红。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** 传了就有一个隐藏字段随表单提交，值是拼起来的那一串 */
+  name?: string;
+  form?: string;
+  /** 填满就提交所在的表单 */
+  autoSubmit?: boolean;
+  /** 挂载后焦点落在第一格 */
+  autoFocus?: boolean;
+  /** 第二格起每一格的可访问名称，默认"第 2 位，共 6 位"。第一格的名称是字段的标签 */
+  slotLabel?: (position: number, length: number) => string;
+};
+/**
+ * 验证码输入：一格一位的短码。每一格是一个真的输入框——打一位跳一格，
+ * 粘贴一整串会分到各格，整组在 Tab 顺序里只停一次。
+ *
+ * 每个都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ * `className` 与 `ref` 给外面那一排。
+ */
+export declare function OtpInput({ length, value, defaultValue, onValueChange, onComplete, type, uppercase, mask, groupSize, size, variant, invalid: invalidProp, id: idProp, disabled: disabledProp, required: requiredProp, readOnly, name, form, autoSubmit, autoFocus, slotLabel, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": describedByProp, className, ...props }: OtpInputProps): import("react").JSX.Element;
+//#endregion
+//#region src/components/page-header/PageHeader.d.ts
+type PageHeaderProps = Omit<ComponentProps<"header">, "title"> & {
+  /** 页面的标题 */
+  title: ReactNode;
+  /** 标题的层级，默认 1（`<h1>`）。页头用在抽屉、分栏里时改小 */
+  level?: 1 | 2 | 3;
+  /** 标题上面的微文字行，如 `// ARCHIVE　共 128 条` */
+  meta?: ReactNode;
+  /** 标题下面的一段说明 */
+  description?: ReactNode;
+  /** 最上面的层级路径：放一个 `Breadcrumb` */
+  breadcrumb?: ReactNode;
+  /** 标题左边的返回：放一个 `PageHeaderBack` */
+  back?: ReactNode;
+  /** 右边的行动区：几个按钮。放不下时折到标题下面 */
+  actions?: ReactNode;
+  /** 底下加一条分隔线 */
+  divider?: boolean;
+  /**
+   * 吸在滚动容器的顶上，带实底和底下那条线。
+   * 上面还有吸顶的顶栏时用 `className` 改 `top`
+   */
+  sticky?: boolean;
+  /** 标题下面的一行：页签、几个统计块 */
+  children?: ReactNode;
+};
+/**
+ * 页头：这是哪一页、怎么回去、在这一页能做什么。一页一个。
+ * 按自身的宽度响应：行动区放不下时折到标题下面。
+ */
+export declare function PageHeader({ title, level, meta, description, breadcrumb, back, actions, divider, sticky, className, children, ...props }: PageHeaderProps): import("react").JSX.Element;
+type BackOwnProps = {
+  /** 默认"返回"。建议写成"返回某某" */
+  "aria-label"?: string;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  disabled?: boolean;
+};
+type PageHeaderBackProps = BackOwnProps & Omit<ComponentProps<"button">, keyof BackOwnProps | "type" | "children">;
+/**
+ * 页头里的返回：40px 的深灰斜纹方块加一个左箭头，`back` 按钮收成的图标形态。
+ * 放进 `PageHeader` 的 `back`。
+ */
+export declare function PageHeaderBack({ "aria-label": label, href, target, rel, render, onClick, disabled, className, ...props }: PageHeaderBackProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/pagination/Pagination.d.ts
 type PaginationSize = "md" | "lg";
 type PaginationProps = Omit<ComponentProps<"nav">, "children" | "onChange"> & {
@@ -1907,6 +2085,30 @@ type ScheduleItemProps = ItemOwnProps$1 & Omit<ComponentProps<"li">, keyof ItemO
 /** 排期里的一个条目。直接放在 `ScheduleTrack` 里。 */
 export declare function ScheduleItem({ start, end, title, type, variant, media, href, target, rel, render, onClick, className, style, ...props }: ScheduleItemProps): import("react").JSX.Element | null;
 //#endregion
+//#region src/components/scroll-area/ScrollArea.d.ts
+type ScrollAreaOrientation = "vertical" | "horizontal" | "both";
+type ScrollAreaProps = Omit<ComponentProps<"div">, "aria-label" | "className" | "style" | "ref"> & {
+  /** 这一块是什么。能滚的时候它是一个能聚焦的区域，读屏听到的就是这个名称 */
+  "aria-label": string;
+  /** 哪个方向能滚，默认 `vertical`。只管一个方向时，另一个方向滚不了 */
+  orientation?: ScrollAreaOrientation;
+  /** 真正在滚的那个元素：给页内目录、回到顶部的 `target` */
+  viewportRef?: Ref<HTMLDivElement>;
+  /** 给外框：高度或者高度上限写在这里 */
+  className?: string;
+  style?: CSSProperties;
+  /** 给外框 */
+  ref?: Ref<HTMLDivElement>;
+};
+/**
+ * 滚动区：一块自己能滚的区域，滚动条是画出来的。高度（或高度上限）由 `className` 给。
+ * 只有真的溢出时才有滚动条，也才是一个能聚焦的区域。
+ *
+ * 整页的滚动留给浏览器，不要把页面主体包进来。
+ * `className` 与 `ref` 给外框，其余属性（`onScroll` 等）给真正在滚的可视区。
+ */
+export declare function ScrollArea({ "aria-label": label, orientation, viewportRef, className, style, ref, children, ...props }: ScrollAreaProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/scroll-hint/ScrollHint.d.ts
 type ScrollHintVariant = "line" | "chevron";
 type ScrollHintProps = Omit<ComponentProps<"div">, "children"> & {
@@ -3240,4 +3442,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, IconButtonProps, IconButtonSize, IconButtonVariant, IconProps, InputProps, InputSize, InputVariant, ItemGridProps, ItemSlotProps, ItemSlotRarity, ItemSlotRatio, KbdProps, KbdSize, ListProps, ListRowProps, ListRowSize, ListVariant, LoaderProps, MarqueeProps, MediaCardProps, MediaCardRatio, NavActionLayout, NavActionProps, NavMenuItemProps, NavMenuProps, NavigatorProps, NavigatorSize, 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, 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, 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 };