@endfield-ui/react 1.2.0 → 1.2.1

package/src/components/README.md

@@ -1,191 +0,0 @@
-# components
-
-主入口（`@endfield-ui/react`）的控件。照游戏内界面复刻的那一组在 [`../game`](../game/README.md)，独立入口，约定不同；这个目录里的东西不许引它。
-
-| 目录 | 导出 | 规范 |
-| --- | --- | --- |
-| `button/` | `Button`、`ButtonGroup` | [按钮](../../../../docs/design/components/button.md) |
-| `icon-button/` | `IconButton` | [按钮](../../../../docs/design/components/button.md) |
-| `toolbar/` | `Toolbar`、`ToolbarButton`、`ToolbarToggle`、`ToolbarToggleGroup`、`ToolbarGroup`、`ToolbarSeparator`（工具栏：整条一个 Tab 停靠点） | [按钮](../../../../docs/design/components/button.md) |
-| `tag/` | `Tag`、`TagPair` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `badge/` | `Badge` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `chip/` | `FilterChip`、`ResourceChip` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `countdown/` | `Countdown` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `stat/` | `Stat` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `rolling-number/` | `RollingNumber`（从 0 滚到终值的数字，放进 `Stat` 的 `value`） | [数据展示](../../../../docs/design/components/data-display.md#滚动数字) |
-| `sparkline/` | `Sparkline` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `data-row/` | `DataRowList`、`DataRow` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `avatar/` | `Avatar`、`AvatarSwitcher`、`AvatarSwitcherItem`（头像切换：一列头像里选一个） | [数据展示](../../../../docs/design/components/data-display.md)、[导航](../../../../docs/design/components/navigation.md) |
-| `section-title/` | `SectionTitle` | [分节标题](../../../../docs/design/elements/section-title.md) |
-| `bracket-title/` | `BracketTitle` | [括号与标记](../../../../docs/design/elements/brackets-and-markers.md) |
-| `term/` | `Term` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `kbd/` | `Kbd` | [测绘叠层](../../../../docs/design/elements/hud-overlays.md) |
-| `tabs/` | `Tabs`、`TabList`、`Tab`、`TabPanel`（格子、胶囊、楔形三种） | [导航](../../../../docs/design/components/navigation.md) |
-| `side-rail/` | `SideRail`、`SideRailItem`、`SideRailGroup`、`SideRailSub`、`SideRailSubItem`（二级） | [导航](../../../../docs/design/components/navigation.md) |
-| `top-bar/` | `TopBar` | [导航](../../../../docs/design/components/navigation.md) |
-| `nav-menu/` | `NavMenu`、`NavMenuItem`（全屏菜单） | [导航](../../../../docs/design/components/navigation.md) |
-| `nav-action/` | `NavAction`（主行动块） | [导航](../../../../docs/design/components/navigation.md) |
-| `breadcrumb/` | `Breadcrumb`、`BreadcrumbItem` | [导航](../../../../docs/design/components/navigation.md) |
-| `page-header/` | `PageHeader`、`PageHeaderBack`（页头：标题、返回、右边的行动区） | [导航](../../../../docs/design/components/navigation.md) |
-| `pagination/` | `Pagination` | [导航](../../../../docs/design/components/navigation.md) |
-| `navigator/` | `Navigator` | [导航](../../../../docs/design/components/navigation.md) |
-| `dash-indicator/` | `DashIndicator` | [导航](../../../../docs/design/components/navigation.md) |
-| `steps/` | `Steps`、`Step`（步骤条；`Stepper` 是数字步进器，不是它） | [导航](../../../../docs/design/components/navigation.md) |
-| `toc/` | `Toc`、`TocItem`（页内目录：滚到哪一节哪一项亮） | [导航](../../../../docs/design/components/navigation.md) |
-| `back-to-top/` | `BackToTop`（回到顶部：滚过一段才出现的悬浮钮） | [导航](../../../../docs/design/components/navigation.md) |
-| `panel/` | `Panel`、`PanelHeader`、`PanelBody`、`PanelRows`、`PanelRow` | [卡片](../../../../docs/design/components/card.md) |
-| `accordion/` | `Accordion`、`AccordionItem`（折叠面板） | [卡片](../../../../docs/design/components/card.md) |
-| `scroll-area/` | `ScrollArea`（滚动区：限高、自己滚，滚动条是画出来的） | [卡片](../../../../docs/design/components/card.md) |
-| `list/` | `List`、`ListRow` | [卡片](../../../../docs/design/components/card.md) |
-| `media-card/` | `MediaCard` | [卡片](../../../../docs/design/components/card.md) |
-| `play-button/` | `PlayButton`、`PlayMark`（播放钮与不能点的播放记号） | [卡片](../../../../docs/design/components/card.md) |
-| `carousel/` | `Carousel`、`CarouselSlide`（媒体轮播） | [卡片](../../../../docs/design/components/card.md) |
-| `image-viewer/` | `ImageViewer`、`ImageViewerItem`（图片查看：缩略图点开看大图） | [卡片](../../../../docs/design/components/card.md) |
-| `item-slot/` | `ItemSlot`、`ItemGrid`（方向键导航的矩阵） | [卡片](../../../../docs/design/components/card.md) |
-| `table/` | `Table`、`TableHead`、`TableBody`、`TableRow`、`TableHeaderCell`、`TableCell`、`TableExpander`（行展开的钮） | [数据展示](../../../../docs/design/components/data-display.md) |
-| `timeline/` | `Timeline`、`TimelineItem` | [数据展示](../../../../docs/design/components/data-display.md) |
-| `schedule/` | `Schedule`、`ScheduleTrack`、`ScheduleItem`（排期：横向的时间轨图） | [数据展示](../../../../docs/design/components/data-display.md) |
-| `field/` | `Field`、`useFieldControl`、`useFieldContext` | [表单](../../../../docs/design/components/form.md) |
-| `input/` | `Input` | [表单](../../../../docs/design/components/form.md) |
-| `otp-input/` | `OtpInput`（验证码输入：一格一位） | [表单](../../../../docs/design/components/form.md) |
-| `textarea/` | `Textarea` | [表单](../../../../docs/design/components/form.md) |
-| `checkbox/` | `Checkbox`（可整体换成菱形符号） | [表单](../../../../docs/design/components/form.md) |
-| `radio/` | `RadioGroup`、`Radio`（同上） | [表单](../../../../docs/design/components/form.md) |
-| `segmented-control/` | `SegmentedControl`、`Segment`（分段选择：并排的单选） | [表单](../../../../docs/design/components/form.md) |
-| `switch/` | `Switch`（含双标签开关） | [表单](../../../../docs/design/components/form.md) |
-| `stepper/` | `Stepper` | [表单](../../../../docs/design/components/form.md) |
-| `slider/` | `Slider`（传两个值是范围滑块） | [表单](../../../../docs/design/components/form.md) |
-| `calendar/` | `Calendar`（月历；加 `range` 是选一段） | [表单](../../../../docs/design/components/form.md) |
-| `date-picker/` | `DatePicker`、`DateRangePicker`（日期选择与日期范围：外框 + 一块带月历的面板；两个共用内部的 `DateField`） | [表单](../../../../docs/design/components/form.md) |
-| `alert/` | `Alert` | [反馈](../../../../docs/design/components/feedback.md) |
-| `progress/` | `Progress`、`ProgressRing` | [反馈](../../../../docs/design/components/feedback.md) |
-| `skeleton/` | `Skeleton` | [反馈](../../../../docs/design/components/feedback.md) |
-| `empty-state/` | `EmptyState` | [反馈](../../../../docs/design/components/feedback.md) |
-| `loader/` | `Loader` | [反馈](../../../../docs/design/components/feedback.md) |
-| `splash-screen/` | `SplashScreen`（开屏页：照官网首次载入的那一页排的，标志和底图是插槽） | [反馈](../../../../docs/design/components/feedback.md#开屏页) |
-| `spinner/` | `Spinner` | [反馈](../../../../docs/design/components/feedback.md) |
-| `completion-banner/` | `CompletionBanner` | [反馈](../../../../docs/design/components/feedback.md) |
-| `tooltip/` | `Tooltip`、`TooltipProvider` | [浮层](../../../../docs/design/components/overlay.md) |
-| `dialog/` | `Dialog`、`DialogClose` | [浮层](../../../../docs/design/components/overlay.md) |
-| `drawer/` | `Drawer` | [浮层](../../../../docs/design/components/overlay.md) |
-| `dropdown-menu/` | `DropdownMenu`、`DropdownMenuItem`、`DropdownMenuCheckboxItem`、`DropdownMenuGroup`、`DropdownMenuSeparator`、`DropdownMenuRadioGroup`、`DropdownMenuRadioItem`、`DropdownMenuSub` | [浮层](../../../../docs/design/components/overlay.md) |
-| `context-menu/` | `ContextMenu`（右键菜单；选项用 `DropdownMenuItem` 那一组） | [浮层](../../../../docs/design/components/overlay.md) |
-| `flyout-bar/` | `FlyoutBar`、`FlyoutBarItem` | [浮层](../../../../docs/design/components/overlay.md) |
-| `popover/` | `Popover`、`PopoverClose` | [浮层](../../../../docs/design/components/overlay.md) |
-| `hover-card/` | `HoverCard`（悬浮卡：链接悬停时预览它的去处） | [浮层](../../../../docs/design/components/overlay.md) |
-| `select/` | `Select`、`SelectItem`、`SelectGroup`、`SelectSeparator` | [表单](../../../../docs/design/components/form.md) |
-| `combobox/` | `Combobox`（可搜索的下拉，含多选、分组与远程检索） | [表单](../../../../docs/design/components/form.md) |
-| `tag-input/` | `TagInput`（标签输入：自己打出来的一串短词） | [表单](../../../../docs/design/components/form.md) |
-| `file-upload/` | `FileUpload`、`FileItem`（文件上传：只管选和列，不管传） | [表单](../../../../docs/design/components/form.md) |
-| `toast/` | `ToastProvider`、`useToast` | [反馈](../../../../docs/design/components/feedback.md) |
-| `rec-indicator/` | `RecIndicator` | [测绘叠层](../../../../docs/design/elements/hud-overlays.md) |
-| `marquee/` | `Marquee` | [动效](../../../../docs/design/foundations/motion.md) |
-| `scroll-hint/` | `ScrollHint` | [测绘叠层](../../../../docs/design/elements/hud-overlays.md) |
-| `corner-brackets/` | `CornerBrackets` | [括号与标记](../../../../docs/design/elements/brackets-and-markers.md) |
-| `viewfinder/` | `Viewfinder` | [测绘叠层](../../../../docs/design/elements/hud-overlays.md) |
-| `tick-ring/` | `TickRing` | [测绘叠层](../../../../docs/design/elements/hud-overlays.md) |
-| `ghost-text/` | `GhostText` | [镂空字与微文字](../../../../docs/design/elements/ghost-and-micro-text.md) |
-| `hatch/` | `Hatch` | [斜纹与色条](../../../../docs/design/elements/stripes-and-strips.md) |
-| `hazard-stripe/` | `HazardStripe` | [斜纹与色条](../../../../docs/design/elements/stripes-and-strips.md) |
-| `registration-strip/` | `RegistrationStrip` | [斜纹与色条](../../../../docs/design/elements/stripes-and-strips.md) |
-| `texture/` | `Texture`（点阵、工程网格、等高线） | [网格、等高线、点阵](../../../../docs/design/elements/grid-contour-dots.md) |
-
-几个目录里有不对外导出的样式文件，供外观相同的控件共用，免得两边走样：
-
-| 文件 | 谁在用 |
-| --- | --- |
-| `chip/capsule-style.ts` | `FilterChip`、`Tabs` 的 `capsule` 变体 |
-| `input/control-box.ts` | `Input`、`Textarea` 的外框（凹陷与描边两种），`Select`、`DatePicker` 的触发器和 `Combobox`、`TagInput` 的外框也用它 |
-| `input/value-chip.ts` | 框里排着的直角小块（已经定下来的值）：`Combobox` 的多选、`TagInput` |
-| `checkbox/choice-style.ts` | `Checkbox`、`Radio`、`Switch` 的行与方格（含菱形方案的写法） |
-| `dialog/overlay-style.ts` | `Dialog`、`Drawer` 的遮罩、深色标题带、关闭按钮；`ImageViewer` 的大图层用它的标题带和关闭按钮 |
-| `popover/panel-style.ts` | `Popover`、`HoverCard` 的面板，和里面的标题、说明 |
-| `carousel/snap-track.ts` | 横向滚动加吸附的轨道，下标和滚动位置互相跟：`Carousel`、`ImageViewer` |
-| `dialog/initial-focus.ts` | `Dialog`、`Drawer` 打开时焦点落在哪 |
-| `dropdown-menu/menu-style.ts` | `DropdownMenu`、`ContextMenu`、`Select`、`Combobox`、`Popover` 的面板，前四者的选项（跟随主题与固定深色两种） |
-| `dropdown-menu/MenuCheck.tsx` | 菜单复选项和多选选项（`Select`、`Combobox`）行首的小方格（复选框的画法缩到 16px） |
-| `list/band-style.ts` | 深色行带的画布、行与缝：`List` 的 `band` 变体和 `DataRow` |
-| `link-element/LinkElement.tsx` | 各控件"链接形态"里的那个 `<a>`：传了 `render` 就把属性合并到使用方给的元素上（路由库的链接组件） |
-| [`lib/decor.ts`](../lib/decor.ts) | 所有装饰层：不挡点击、不可选中，高对比模式与打印时去掉 |
-
-## 约定
-
-一组件一目录，目录名用 kebab-case，组件名用 PascalCase：
-
-```
-components/
-└── button/
-    ├── Button.tsx        组件实现
-    ├── Button.test.tsx   行为与无障碍测试
-    └── index.ts          具名导出
-```
-
-预览用的 stories 不放在这里，放在 [apps/docs/stories](../../../../apps/docs/README.md)，保持依赖方向 `apps/docs → packages/ui`。
-
-- 只用 [theme.css](../styles/theme.css) 里的令牌生成的工具类；组件内不写十六进制色值。
-- 随主题翻转的颜色一律用语义令牌（`surface`、`ink`、`action`…）。只有"有意不随主题变"的填充才直接用 `neutral-*`，并在旁边写一句注释说明原因。
-- 压在反转块（`surface-inverse`）上的强调记号用 `accent-ink-inverse`，压在页面表面上的用 `accent-ink`，都不直接用 `action`：它在浅色底上看不见。
-- 悬停底用 `hover:bg-ink/5`，不用 `surface-sunken`——后者在暗色主题下是纯黑。
-- **只靠底色或阴影说"选中 / 当前"的地方，要另写一份高对比模式（`forced-colors:`）下的画法。** 系统会把作者写的底色都换成页面色、阴影不画：填充反转的块改成 `forced-colors:bg-[Highlight]` 加 `forced-colors:text-[HighlightText]`，底色画的记号改成 `forced-colors:bg-[Highlight]`。系统色关键字只写在 `forced-colors:` 变体里，是"只用令牌"的例外。字压在 `Highlight` 上的那个元素还要加 `forced-colors:forced-color-adjust-none`（不然浏览器会在字后面垫一块页面色），并把它的边线、焦点环一起写成系统色。对应关系和理由见 [色彩](../../../../docs/design/foundations/color.md#高对比模式)。
-- **全靠底色成形的部件，高对比模式下同样要另写**——不只是"选中"。整个是底色画的（滑块、进度条、加载指示、骨架）会直接不见；靠底色围出来的一块（框里的值块、步进器的格子、排期的条目）只剩里面的字。轨道和填上的那一段写成"空心对实心"（轨道 `forced-colors:outline forced-colors:-outline-offset-1`，填充 `forced-colors:bg-[Highlight]`），不靠两种系统色分；围出来的一块补一圈线（`forced-colors:border`）。控件自己的部件用 `ButtonText`，页面上的用 `CanvasText`。还有几件容易漏的：**禁用的字色**写在 `<label>`、`<span>`、`<output>` 上时系统会当普通字换掉，要写明 `GrayText`——禁用的 `<input>` 也要在它自己身上写（`forced-colors:disabled:text-[GrayText]`，[`controlElement`](input/control-box.ts) 里有），浏览器只认写了 `type` 的；**SVG 里写的颜色**（`fill-*`、`stroke-*`）系统不换，要自己写成系统色，直接写在图标 `<svg>` 上的 `text-*` 也一样（图标跟着走的只是继承来的字色）；**占位用的透明边线**（只读的输入框）会被系统显形，写成 `forced-colors:border-[Canvas]`；**说着事的线别用 [`decor`](../lib/decor.ts)**，它在高对比模式下整个去掉（排期里"今天"的竖线）。
-- **按钮这一类在高对比模式下的写法**（按钮、图标按钮、工具栏、分页条是照这几条改的）：
-  - 外形是一圈线，不做成实心块——实心留给"选中"。线只在 `forced-colors:` 下补，平时的尺寸不动：自己要聚焦的元素用 `forced-colors:border`（`outline` 让焦点环占着），不聚焦的容器（带子、条）用 `forced-colors:outline forced-colors:-outline-offset-1` 画在内边距里。用了 `border` 的，伪元素往外补的点击区要跟着多补 1px（它是从线的里沿起算的）。
-  - 平时就是透明、靠外面一层围着的（工具栏里的钮），补外面那一层，不逐个补。
-  - **带状态的类盖得住单写的 `forced-colors:`**：`hover:`、`group-hover:`、`data-disabled:` 都多一层选择器，优先级更高或一样高。颜色会随状态换的地方，高对比模式下那几档各写一份（`forced-colors:group-hover:bg-[ButtonText]`、`forced-colors:data-disabled:text-[GrayText]`）；能在组件里按属性分支的（`disabled ? … : …`），就只放其中一份，不靠优先级。
-  - **不是真的 `disabled` 的禁用**（去掉了地址的链接、工具栏里还走得到的钮）系统不会替它把字换灰，`GrayText` 要自己写。
-  - 放在控件里的 [`Spinner`](spinner/Spinner.tsx) 自己写的是页面的字色：要它和控件上的字一个颜色，用 `className` 换成 `forced-colors:bg-[ButtonText]`。
-- 组件 API 用语义命名（`variant="action"`、`tone="danger"`），不把颜色名写进属性（不要 `yellow`）。
-- **能当链接用的控件，`href` 之外同时收 `render`**（路由库的链接组件）。链接形态里的那个 `<a>` 换成 [`LinkElement`](link-element/LinkElement.tsx)，判断写成 `href !== undefined || render !== undefined`；转给 Base UI 部件的（菜单项）用 [`defined()`](../lib/defined.ts) 去掉没有值的属性，免得把那个元素自己的地址盖掉。
-- 变体写成 `Record<Variant, string>`，用 [`cn()`](../lib/cn.ts) 合并，使用方传入的 `className` 排在最后、可以覆盖内置类。
-- 形状是语义的一部分：切角、胶囊、圆形分别对应什么含义见 [形状规范](../../../../docs/design/foundations/shape.md)，不要给所有组件套同一个外形。
-- 每个交互组件都要有 `:focus-visible` 样式，用 [`focusRing`](../lib/focus-ring.ts)；会被滚动容器裁切的地方用 `focusRingInset`；外框自己不能聚焦、里面的控件能（输入框）时用 `focusRingWithin`。焦点环不能被 `clip-path` 裁掉（做法见 [切角与斜楔](../../../../docs/design/elements/corner-and-wedge.md)）。
-- 悬停用 Tailwind 的 `hover:`，它只在有指针的设备上生效。
-- 组件内部的响应式看**自身宽度**，用容器查询（`@container` + `@md:` 这类变体），不用视口断点（`md:`）：组件不知道自己会被放进多窄的栏里。视口断点只留给"必须和页面布局同步切换"的地方，目前只有 `SectionTitle` 的 `side` 形态。
-- 会出现英文长单词的大号文字加 `wrap-anywhere` 兜底，并确保它所在的弹性子项能收缩（`min-w-0` 或 `max-w-full`）。有意不换行的控件（按钮、标签、页签）除外。中间带空格的短读数（轮播的 `1 / 5`）不折行也不收缩（`shrink-0 whitespace-nowrap`）：同一行里让别的东西去收，不然它被挤成一竖条。
-- 装饰元素（竖条、箭头、分隔线）加 `aria-hidden`。
-- 动效遵守 `prefers-reduced-motion`：降级后内容必须停在终态。循环动画停下来的样子不能被看成一个具体的值：不确定进度的色块停在正中，进度环换成一圈虚线。
-- 用 `group` / `peer` 时给 `group` 起名字（`group/card` + `group-hover/card:`）：不起名的 `group-hover:` 会被外层任何一个 `group` 的悬停带着走，控件一旦被放进别的可悬停容器就会出错。
-- `z-index` 不在组件里写数值，用 [theme.css](../styles/theme.css) 里的层叠变量（`z-(--z-nav)`、`z-(--z-overlay)`、`z-(--z-toast)`、`z-(--z-loader)`）。只在自己内部排先后的（表格冻结的那一列）先用 `isolate` 围起来，再写小的数值。
-- **会粘住不动的格子必须是不透明的**（表格冻结的首列）：滚过去的内容会从半透明的底下面透出来。它的悬停底不能用 `bg-ink/5`，用 `color-mix()` 把同样的比例混进它所在的底色里，得到一个看上去一样的实色。
-- **压在反转块上的焦点环用 `accent-ink-inverse`**（表格的标题带、月历的选中格）；压在行动色上的用 `on-action`（全屏菜单的当前项、楔形页签的选中项、深色面板里的当前项）。普通的焦点色在亮色下是墨色、暗色下是黄色，正好和这两种底撞色。只有环画在块**里面**时才撞：画在外面的（分段选择、工具栏按下的开关钮）隔着 2px 压在页面上，不用换。换了颜色还要看它贴着的那条边外面是什么：`on-action` 是墨色，贴边的话在暗色页面、深色面板上和周围分不开，所以压在行动色上的环都再往里收 2px（`focus-visible:-outline-offset-4`），让环的两边都是黄。
-
-### 母题与装饰
-
-- **切角和斜楔画在伪元素的底上，不直接裁可聚焦的元素。** `clip-path` 会把焦点环一起裁掉，所以写成 `relative isolate before:absolute before:inset-0 before:-z-10 before:wedge-r before:bg-action`（楔形页签就是这样）。不可聚焦的小东西（角标）可以直接写 `cut-br`。
-- **角括号画在宿主之外 4px。** 宿主自己要定位，并且不能被贴身的祖先裁切：需要裁切内容时把裁切放到内层（物品格的卡面），括号留在外层。选中又被聚焦时，焦点环外移到括号之外（`focus-visible:outline-offset-[6px]`）。
-- **纯装饰的元素加 `aria-hidden` 并用 [`decor`](../lib/decor.ts)。** 用背景画出来的状态（角括号）在高对比模式下不显示，要另给一个描边之类的替代。
-- **装饰不压字。** 描边词、巨字放在空白处，或者排在两段文字之间，或者朝文字的方向淡出；不要从标题、说明、数值后面穿过去——再淡的线也会切碎字的轮廓。
-- **叠在画面上的控件颜色跟画面走。** 取景角、刻度圆环、录制指示用的都是 `ink`，压在深色图像上时由使用方给它加 `data-theme="dark"`，组件自己不猜。
-- **全库只能选一套的外观做成全局开关，不做成属性。** 菱形表单符号是 `<html data-choice="diamond">`，写法是自定义变体 `choice-diamond:`——做成属性的话，两套符号迟早会被混着用。
-
-### 浮层
-
-- 行为交给 [Base UI](https://base-ui.com)（`@base-ui/react`，按子路径引入）：焦点的进出与锁定、键盘、定位与翻转、关闭的时机。本库只写长相，并把它的部件装成一个组件——使用方不用自己拼 `Root` / `Portal` / `Positioner`。
-- 触发元素作为一个 React 元素传入（`trigger={<Button>…</Button>}`，文字提示是 `children`），内部交给基元的 `render`。它得把收到的属性和 `ref` 交给原生元素。
-- **所有浮层用同一个 `z-(--z-overlay)`**，靠打开的先后叠：弹窗里的下拉才能盖住弹窗。不要给某个浮层单独加高。
-- **浮层挂在 `<body>` 下，拿不到局部主题。** 用 [`usePortalScope`](../hooks/usePortalScope.ts)：`anchorRef` 给触发元素，`portalRef` 给基元的 `Portal`，它把最近的 `data-theme` / `data-choice` 抄过去。
-- **一块固定深色的区域里还要放别的控件时，把它做成局部主题**（`data-theme="dark"`），里面照常用语义令牌；不要逐个写 `neutral-*`。弹窗的标题带、行带都是这样。
-- **一块跟着主题翻、但总和页面相反的区域（反转块）里要放别的控件时，用 `data-theme="inverse"`**，里面照常用 `bg-surface text-ink`——取到的就是原来的 `surface-inverse` / `ink-inverse`，颜色不变。面板的标题带、表格的表头带、完成横幅都是这样。反转块里不要再嵌反转块。
-- 进出场用基元给的 `data-starting-style` / `data-ending-style` 写 CSS 过渡（`data-starting-style:opacity-0`），不写关键帧。基元等过渡结束才卸载浮层。
-- 没有边线、全靠底色和页面分开的浮层（文字提示）加一圈透明的边线：高对比模式下底色被系统覆盖，边线会自己显形。反过来，只为占位留着的透明边线不想让它显形，就写成 `Canvas`（见上面"全靠底色成形的部件"那一条）。
-- **要画焦点环的元素不要写 `outline-none`。** Tailwind v4 里它把轮廓的线型定成 `none`，后面的 `focus-visible:outline-2` 也跟着画不出来（菜单的选项踩过）。`outline-none` 只留给"焦点环画在别处"的元素：输入框里的 `<input>`、下拉的触发按钮（环在外框上）、弹窗的面。
-- 局部主题里的焦点环如果会画到局部主题之外（外扩 2px），颜色就压在了页面的底色上。轻提示是深色的一块，环是黄的，画到亮色页面上看不见——所以它用画在里面的 `focusRingInset`。
-- 测试里查浮层用角色（`findByRole("dialog")`）。文字提示的内容同时存在于隐藏的描述里，按文字查时要排除 `[hidden]`。
-
-### 带状态的控件
-
-- 受控与非受控两种用法都要支持，用 [`useControllableState`](../hooks/useControllableState.ts)：`value` / `defaultValue` / `onValueChange`（分页是 `page`，导航器是 `index`）。
-- 页码从 1 起，其余的位置（`index`）从 0 起。
-- 越界的值夹回范围内，不抛错。
-- 会变的位置信息用 `aria-live="polite"` 播报一句完整的话（"第 2 页，共 12 页"），看得见的 `02 / 12` 对读屏隐藏。
-- 输入到一半的内容单独存一份草稿，失焦或回车时才落定——边输入边校正会让人打不出想要的数（步进器、分页的跳页）。
-
-### 表单控件
-
-- 建立在原生 `<input>` / `<textarea>` 上：`className` 给外层（外框或整行），其余属性与 `ref` 给原生元素。
-- 状态用原生伪类写样式（`checked:`、`disabled:`、`indeterminate:`），不另外维护一份 React 状态。
-- 同一个元素上几个状态类互相覆盖时，谁赢取决于它们在生成的 CSS 里的先后，而不是写在 `className` 里的先后。目前依赖的顺序是 `group-hover` < `checked` / `indeterminate` < `hover` < `disabled`；`hover` 排在 `focus-within` 之后，所以输入框的悬停写成 `hover:not-focus-within:`。
-- `:indeterminate` 也会命中"一组里都没选"的单选框，半选的样式只能写在复选框上。
-- 需要标签、帮助文字、错误说明时放进 [`Field`](field/Field.tsx)；自定义控件用 `useFieldControl` 接入。
-
-各组件的设计规范与各期的清单见 [docs/design/components](../../../../docs/design/components/README.md)。

package/src/hooks/README.md

@@ -1,20 +0,0 @@
-# hooks
-
-只放不依赖具体组件的逻辑。只服务于单个组件的 hook 放在该组件目录内。
-
-| hook | 作用 |
-| --- | --- |
-| `useTheme` | 读写 `<html data-theme>`；支持 `light` / `dark` / `system`，选择记在 `localStorage`。亮暗变了的时候放在视图过渡里换，整页交叉淡化一次（200ms，时长在 [theme.css](../styles/theme.css) 的 `data-theme-switching` 下）；浏览器不支持、系统开了"减少动态效果"时直接切 |
-| `useControllableState` | 受控 / 非受控状态合并；值没变时不触发 `onChange` |
-| `useInView` | 元素第一次进入视口后返回 `true`，之后不再变回去——入场动画只播一次 |
-| `useReducedMotion` | 系统开了"减少动态效果"时返回 `true`，设置变了跟着变。只给脚本驱动的动效用（滚动数字）：CSS 的动画和过渡不用它 |
-| `usePresence` | 退场后再卸载：`open` 变成假之后元素先留着，等它身上正在跑的过渡和动画走完才卸载；没有动效可等就当场卸载。另外告诉你这个元素是不是"后来才出现的"——一开始就在的不播进场。加载页的滑出在用。不对外导出 |
-| `useAddedKeys` | 一串 key 里哪几个是后来加进来的：一开始就在的不算，删了又加回来的算。"新项淡入"只给这几个加入场的类（标签输入、文件上传）。不对外导出 |
-| `useIndicator` | 选中指示的位置：量出容器里当前项相对容器的位置和尺寸，写成容器上的 CSS 变量，并标上有没有当前项（`data-indicator`）。换了一项才滑；第一次到位、同一项挪了地方或变了大小都直接到；量不到就不标，各项照旧自己画选中态。给分段选择、页内目录、胶囊页签的滑动用。不对外导出 |
-| `useLingering` | 列表里被拿掉的项先留着：给它现在的那几个 key，返回"现在的 + 正在走的"（走的带 `leaving`，排在原来的位置上），等走的那一项身上的动效走完才拿掉——等法和 `usePresence` 是同一个（`afterMotion`），没有动效可等就当场拿掉。同时有加进来的不留。给标签输入、文件上传的列表用。不对外导出 |
-| `useFlip` | 补位：一排里有一项走了（带着 `data-leaving`），其余的直接子元素从旧位置滑到新位置——每次渲染后记位置，少了一项的那一次把挪了地方的先用 `translate` 摆回旧位置、再撤掉，滑回来靠 CSS 的过渡。走的那一项被钉在原处；容器因此变矮了，高度也量着收过去。只有少了一项才补位；超过 50 项、量不到就不做。给标签输入用。不对外导出 |
-| `useOverflowing` | 容器里的内容是不是比容器宽、比容器高。给"只有真的能滚动时才是一个能聚焦的区域"用（表格、排期）。不对外导出 |
-| `useScrollPosition` | 盯着一个滚动容器（不传就是整个页面），由滚动位置算出一个值：滚动、窗口尺寸变了、内容晚到都会重新算，值没变不重新渲染。滚动提示和回到顶部共用。不对外导出 |
-| `usePortalScope` | 浮层挂到 `<body>` 下之后拿不到局部容器上的 `data-theme` / `data-choice`：返回 `anchorRef`（给触发元素）和 `portalRef`（给浮层的容器），容器挂载时把最近的开关抄过去。`invertTheme` 抄相反的主题（文字提示）。最近的是反转块（`data-theme="inverse"`）时，抄的是它实际算出来的亮或暗 |
-
-动效几乎都是 CSS 的动画与过渡，由 [theme.css](../styles/theme.css) 末尾的全局规则统一降级，不用在组件里判断。那条规则管不到脚本：一帧一帧自己算的动效（现在只有滚动数字）要用 `useReducedMotion` 自己看；脚本里要的平滑滚动、视图过渡（页内目录、回到顶部、`useTheme`）也是各自当场看一眼系统的设置。

package/src/icons/README.md

@@ -1,31 +0,0 @@
-# icons
-
-原创图标组件。目前只有控件自己用到的二十个：
-
-| 图标 | 用在哪 |
-| --- | --- |
-| `ArrowCorner`（斜箭头 ↘）、`ArrowLeft`、`ArrowRight` | 分节标题、文字按钮 |
-| `ChevronLeft`、`ChevronRight`、`ChevronDown` | 返回按钮、翻页、滚动提示 |
-| `TriangleRight`（实心三角 ▶） | 页签的箭头块 |
-| `Close`、`Plus`、`Minus`、`Check` | 关闭、增减、已选与半选 |
-| `StatusInfo`、`StatusSuccess`、`StatusWarning`、`StatusDanger` | 提示条的四种色调、输入框的错误图标 |
-| `Lock`、`Crosshair`（四个取景角加准星） | 物品格的"锁定"与"未获得" |
-| `Menu`（三条横线） | 顶栏的菜单钮 |
-| `CalendarIcon` | 日期选择右侧的记号（`Calendar` 这个名字给了月历控件） |
-| `Upload`（托盘加一支朝上的箭头） | 文件上传的投放区 |
-
-四个状态图标的外形各不相同——方框、圆、三角、菱形——状态因此不只靠颜色区分。
-
-## 规则
-
-- **只收录原创图标。** 不收录、不描摹官方图标与 Logo，包括游戏内图标、官网导航图标和阵营徽记。
-- 绘制规范见 [图标规范](../../../../docs/design/foundations/iconography.md)：24 网格、2px 描边、平头端点、尖角拐角、几何母题（菱形、三角、斜杠）。
-- 每个图标一个文件，用 [`createIcon`](createIcon.tsx) 生成：接受 `size` 与 `className`，颜色用 `currentColor`，默认 `aria-hidden`。
-
-```tsx
-import { createIcon } from "./createIcon";
-
-export const Plus = createIcon("Plus", <path d="M12 4v16M4 12h16" />);
-```
-
-- 通用图标（关闭、箭头、搜索等）优先画一套自己的；需要大量通用图标时，可以在文档站里搭配成熟的开源图标库，但不要打包进本库。

package/src/lib/README.md

@@ -1,19 +0,0 @@
-# lib
-
-纯函数与常量。这里不放 React 组件和 hooks。
-
-| 文件 | 内容 |
-| --- | --- |
-| `cn.ts` | `cn()`：合并类名（`clsx` + `tailwind-merge`）。里面登记了 [theme.css](../styles/theme.css) 的自定义令牌名，否则 `text-micro` 会被当成颜色、与 `text-ink` 互相覆盖 |
-| `focus-ring.ts` | `focusRing`、`focusRingInset`、`focusRingWithin`：全库统一的焦点环类名 |
-| `merge-refs.ts` | `mergeRefs()`：组件自己要用节点、同时还得把它交给使用方时，把几个 ref 合成一个 |
-| `inline-style.ts` | `dropEmptyStyle()`：往元素上临时写过内联样式、又都撤掉之后，把空下来的 `style` 属性拿掉。浏览器是懒着同步这个属性的，直接删会落空、回头又冒出一个空的 |
-| `defined.ts` | `defined()`：去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上（`render`）之前用，免得把那个元素自己写的盖掉 |
-| `decor.ts` | `decor`：装饰层共用的类 |
-| `motion.ts` | 几处共用的动效类名。`enterFromSide`：浮层面板进场的方向位移——按基元给的 `data-side`，起点往触发元素那一侧偏 `--motion-shift`；`collapse` / `collapseEnter` / `collapseInner`：按高度收放；`fadeInFast`：小件的淡入；`indicator` / `indicatorBox`：画在容器 `::after` 上的选中指示，位置来自 `useIndicator`；`flipBox` / `flipLeaving`：补位（`useFlip`）的那一排，和里面走的那一项。见 [动效](../../../../docs/design/foundations/motion.md#补的几条约定) |
-| `date.ts` | 日期的纯函数：加减日和月、比较、把两天排成先后、夹到范围内、月历的六行七列。日期一律是 `YYYY-MM-DD` 的字符串，全部按 UTC 算，不碰本地时区。`Calendar`、`DatePicker`、`Schedule` 共用，不对外导出 |
-| `file.ts` | 文件的纯函数：按 `accept` 认类型（扩展名、MIME、`image/*` 通配）、把字节数写成 `1.2 MB`、取扩展名、判断是不是同一个文件。`FileUpload` 用，不对外导出 |
-
-没有单独的"变体工具"：各组件直接写 `Record<Variant, string>` 再用 `cn()` 合并，够用且类型清楚。
-
-以后可能放进来的：与 DOM 无关的格式化函数，例如把数字格式化成等宽的 `01 / 04`。

package/src/styles/README.md

@@ -1,77 +0,0 @@
-# styles
-
-| 文件 | 内容 |
-| --- | --- |
-| [theme.css](theme.css) | 设计令牌：语义变量（亮 / 暗）+ Tailwind v4 `@theme` 映射 |
-| [utilities.css](utilities.css) | `@utility`：母题工具类（斜纹、切角、斜楔、角括号、镂空字、警示条纹、竖条变箭头），以及菱形表单符号的开关 |
-| [index.css](index.css) | 入口：`tailwindcss` → `theme.css` → `utilities.css` → 基础样式 → `@source` |
-
-对外的入口（见包的 `exports`）：
-
-| 引入路径 | 对应 | 给谁用 |
-| --- | --- | --- |
-| `@endfield-ui/react/tailwind.css` | `index.css` | 用 Tailwind v4 的项目，代替 `@import "tailwindcss"` |
-| `@endfield-ui/react/styles.css` | `dist/styles.css` | 不用 Tailwind 的项目，预编译产物 |
-| `@endfield-ui/react/theme.css` | `theme.css` | 只要令牌、不要组件 |
-| `@endfield-ui/react/utilities.css` | `utilities.css` | 只要母题工具类 |
-| `@endfield-ui/react/game.css` | `dist/game/styles.css` | 用了 [Game 实机风格](../game/README.md)那一类控件的项目；纯 CSS，和上面的主样式一起引 |
-
-Game 实机风格的样式不在这个目录里，也不在主样式里：源码是 [`../game/styles.css`](../game/styles.css) 汇总的每个控件一份纯 CSS，`index.css` 用 `@source not` 把那个目录排除在扫描之外。
-
-## theme.css 的结构
-
-1. **语义变量**：亮色定义在 `:root` 与 `[data-theme="light"]`（对齐官网的纸白基底），`[data-theme="dark"]` 覆盖为暗色（对齐游戏 HUD 与官网深色版块）。两种取值都可以加在局部容器上。
-   - `[data-theme="inverse"]` 是"和所在主题相反"，给反转块（标题带、表头带）用：底和字取所在主题的 `surface-inverse` / `ink-inverse`，其余取相反主题的值。亮、暗两块里的 `--ef-x-*` 就是给它准备的那份"相反主题的取值"，**改亮、暗任何一个值时要把另一块里对应的 `--ef-x-*` 一起改**——[theme.test.ts](theme.test.ts) 会核对。
-2. **`@theme`**：不随主题变化的原始令牌——色板、字体、字阶、圆角、阴影、缓动、动画、切角尺寸（`--cut-sm` / `md` / `lg`），以及层叠值（`--z-float` 100、`--z-nav` 200、`--z-overlay` 300、`--z-toast` 400、`--z-loader` 1000，用法是 `z-(--z-overlay)`）。
-3. **`@theme inline`**：把第 1 步的语义变量映射成 Tailwind 颜色，生成 `bg-surface`、`text-ink`、`border-line` 这类工具类。
-
-## 只用令牌
-
-```css
-@import "tailwindcss";
-@import "@endfield-ui/react/theme.css";
-```
-
-```html
-<html data-theme="dark">
-  <button class="bg-action text-on-action font-sans text-lg">前往游戏</button>
-</html>
-```
-
-## 修改令牌
-
-令牌值的依据写在 [docs/design/foundations](../../../../docs/design/foundations/color.md)。改动任何一个值时，同步改对应文档里的表格；文档里每个值都标了来源等级（实测 / 观察 / 社区 / 推断），替换"社区"和"推断"级别的值时请在文档里写明新的依据。
-
-新增或改名自定义的字阶、阴影、缓动、动画、字距令牌时，还要同步 [lib/cn.ts](../lib/cn.ts) 里登记给 `tailwind-merge` 的清单，否则 `cn()` 会把它们归错类。
-
-## 母题工具类
-
-| 工具类 | 作用 | 可调的变量 |
-| --- | --- | --- |
-| `hatch`，加 `hatch-mid` / `hatch-fine` | 45° 斜纹的粗、中、细三档 | `--hatch-color`、`--hatch-width` |
-| `hazard` | 黄黑警示条纹 | `--hazard-size` |
-| `cut-tr`、`cut-br`、`cut-diagonal`，加 `cut-sm` / `cut-md` / `cut-lg` | 切角与切口大小 | `--cut` |
-| `wedge`、`wedge-l`、`wedge-r` | 两侧 / 单侧斜切 | `--wedge` |
-| `corner-brackets` | 四角的 L 形短线，画在 `::after` 上 | `--bracket-color`、`--bracket-arm`、`--bracket-width`、`--bracket-offset` |
-| `ghost-hatch`、`ghost-outline` | 镂空字的斜纹与描边两种画法 | `--ghost-ink` |
-| `dot-grid` | 点阵底纹 | `--dot-color`、`--dot-size`、`--dot-gap` |
-| `blueprint-grid` | 工程网格底纹 | `--grid-color`、`--grid-gap` |
-| `contour` | 等高线底纹，贴在右下角、朝左上淡出 | `--contour-color`、`--contour-size`、`--contour-position`、`--contour-image` |
-| `marker-bar`、`marker-arrow` | 按钮里竖条变箭头的两个形状 | `--marker-bar` |
-
-- 跟着主题走的颜色（斜纹、角括号、镂空字、三种底纹）默认取 `--ef-ink`；警示条纹和斜纹的"中"档有意不随主题变。
-- `cut-*` 与 `wedge*` 用的是 `clip-path`，会把焦点环一起裁掉。可聚焦的元素把它们写在伪元素上：`before:cut-tr before:bg-action`。
-- `corner-brackets` 不替宿主设 `position`，宿主自己要是 `relative` 或 `absolute`。
-- `contour` 是遮罩（`mask-image`），会把元素自己的内容一起遮掉：只能写在空的装饰层上。`dot-grid` 和 `blueprint-grid` 是背景，没有这个限制，但同样建议画在独立的装饰层上。
-- 镂空字不叫 `text-hatch`：`text-*` 是字号和文字颜色的名字空间，`cn()` 合并类名时会把它当成颜色。
-
-这些类只画形状。什么东西可以切角、哪里能放斜纹，见 [docs/design/elements](../../../../docs/design/elements/corner-and-wedge.md) 各篇的"什么时候用"。预编译的 `styles.css` 里只有组件自己用到的那几个；不用 Tailwind 的项目用对应的装饰组件。
-
-文件末尾还有两个自定义变体：
-
-- `choice-diamond:`，在祖先带 `data-choice="diamond"` 时生效，复选与单选靠它整体换成菱形符号。
-- `cq-portrait:`，在最近的尺寸容器（`container-type: size`）高大于宽时生效。开屏页靠它换成竖排——看的是它所在的那一块，不是视口。
-
-## 注意
-
-`index.css` 里的 `@source "../"` 扫的是整个 `src`，不能缩成只扫 `components`：焦点环这类共用的类名写在 `lib` 里，扫不到就不会生成。