agentcss 0.0.0-stage → 0.11.3

package/01-tokens/README.md

@@ -0,0 +1,236 @@
+# tokens —— 设计令牌
+
+| 字段 | 内容 |
+|---|---|
+| **来源** | 原创。流体公式与 WCAG 判据来自公开资料，见下 |
+| **实测** | `05-audit/contrast.py` 22/22 |
+| **适用** | 精简档 / B / C |
+| **规范** | 见本文件「流体与断点」一节|
+
+---
+
+## 三组令牌，三条不同的规则
+
+| 组 | 规则 | 为什么 |
+|---|---|---|
+| **色** | **全部必须过对比度门禁** | 无对比度的颜色等于没有 |
+| **字号** | 标题/正文流体，**UI 文本固定** | UI 字号参与控件尺寸，流体化会抖动 |
+| **间距** | 大值流体，小值固定 | 同上 |
+
+🔴 每档的取值与理由都写在下面，**改之前先读这一节**。
+
+---
+
+## 明暗与**局部换肤**
+
+整页明暗有三条路，都不需要 JS：
+
+| 做法 | 效果 |
+|---|---|
+| 什么都不做 | 跟随系统（`prefers-color-scheme`） |
+| `<html data-theme="dark">` | 强制暗（系统是浅色也暗） |
+| `<html data-theme="light">` | 强制亮（系统是暗色也亮） |
+
+**任何容器**也可以单独指定，用来做"深色 hero + 浅色正文"、文档站里的反色示例：
+
+```html
+<div data-theme="dark">          <!-- 这块区域整体切到暗色 -->
+  <button class="btn btn--primary">暗色按钮</button>
+
+  <div data-theme="light">       <!-- 嵌回去也成立 -->
+    <button class="btn btn--primary">浅色按钮</button>
+  </div>
+</div>
+```
+
+⚠️ 三条边界，都是有意的：
+
+1. **容器必须显式写 `data-theme`**。不做"没写就跟随系统"——那需要把令牌写到
+   **每一个元素**上（`*:not([data-theme])`），后果是使用者写在 `body` 上的覆盖
+   失效，且长页面上每个元素各存 30 个自定义属性。
+2. **容器自己不会涂底色**。`[data-theme]` 只切换令牌；要不要给这块区域加背景，
+   由你决定（通常 `background: var(--paper)`）。
+3. **`color-scheme` 目前只由 `date-range` 局部设置**，根上没有。所以暗色下
+   原生滚动条/日期弹层不会跟着变 —— 这是已知未决项，见
+   `docs/RFC-THEME-SCOPE.md` 第六节（它会让既有 40 页视觉基线全变，需要单独一轮）。
+
+组件的明暗差异**全部由令牌表达**，组件 CSS 里不许出现
+`@media (prefers-color-scheme: dark)` —— 主题能从容器来之后，那种写法只反映系统偏好，
+局部暗区里的组件会拿到另一套配色。这条由 `theme-scope-gate` 静态守着。
+
+---
+
+## 色（全部实测达标）
+
+| 令牌 | 值 | 对比度 |
+|---|---|---|
+| `--paper` | `#f6f7f8` | 底色 |
+| `--text-primary` | `#15181c` | **17.37 AAA** |
+| `--text-secondary` | `#4f555e` | **7.33 AAA** |
+| `--text-tertiary` | `#6b7280` | **4.72 AA** |
+| `--accent` | `#1b4d8f` | **8.18 AAA** |
+| `--danger` | `#c0392b` | **6.26 AA** |
+| `--border-control` | `#868b94` | **3.56**（UI 边界需 ≥3.0）|
+
+🔴 **暖褐色已被移除**。理由见 `05-品味规范.md`：
+暖纸感是我第一轮凭感觉定的，没有依据。**颜色应该服务于内容，不该自己表演。**
+
+---
+
+## 字号：流体与固定的分工
+
+```css
+--fs-xs:   0.75rem;                    /* 12px 固定：辅助文字 */
+--fs-sm:   0.875rem;                   /* 14px 固定：UI 文本 */
+--fs-base: clamp(1rem, 0.95rem + 0.3vw, 1.125rem);      /* 16 → 18px */
+--fs-md:   clamp(1.125rem, 1.05rem + 0.5vw, 1.3125rem); /* 18 → 21px */
+--fs-lg:   clamp(1.3125rem, 1.2rem + 0.7vw, 1.5rem);    /* 21 → 24px */
+--fs-xl:   clamp(1.5rem, 1.3rem + 1.2vw, 1.875rem);     /* 24 → 30px */
+--fs-2xl:  clamp(1.75rem, 1.45rem + 1.8vw, 2.5rem);     /* 28 → 40px */
+```
+
+### 两条硬规则
+
+**1. `clamp()` 的上下限必须用 rem，绝不用 px。**
+px 上下限不尊重"用户把浏览器字号调大"的设置——下限会锁死，放到 200% 也涨不上去。
+
+**2. UI 文本（`--fs-xs` / `--fs-sm`）不流体。**
+它们是**控件尺寸的一部分**。流体会让按钮和输入框在不同屏幕下大小不一、布局抖动。
+
+### 验收判据（WCAG 1.4.4）
+
+> 只要 **MAX ≤ 2.5 × MIN**，就一定通过 resize-text 检查。
+
+本库最大比值 = 2.5 ÷ 1.75 = **1.43**，安全。
+
+### 🔴 硬下限：表单字号 ≥ 16px
+
+`input` 的字号**不能**低于 16px。iOS Safari 在小于 16px 时会自动放大整个页面
+**且不缩回**。这是硬约束，不是审美。
+
+---
+
+## 间距：大值流体
+
+```css
+--sp-1: 4px;  --sp-2: 8px;  --sp-3: 12px;         /* 固定 */
+--sp-4: clamp(1rem, 0.95rem + 0.3vw, 1.25rem);      /* 16 → 20px */
+--sp-5: clamp(1.25rem, 1.15rem + 0.7vw, 1.75rem);   /* 20 → 28px */
+--sp-6: clamp(1.5rem, 1.3rem + 1.2vw, 2.25rem);     /* 24 → 36px */
+--sp-7: clamp(2rem, 1.7rem + 1.8vw, 3.5rem);        /* 32 → 56px */
+--sp-8: clamp(2.5rem, 2.1rem + 2.4vw, 4.5rem);     /* 40 → 72px */
+```
+
+**判据**：
+> 这个值变了会不会导致"控件大小跟着变"？会 → **不要**流体。
+
+---
+
+## 断点令牌
+
+| 令牌 | 值 | 用途 |
+|---|---|---|
+| `--bp-sm` | 30rem (480px) | 大手机 / 小平板 |
+| `--bp-md` | 48rem (768px) | 平板 |
+| `--bp-lg` | 64rem (1024px) | 小笔记本 |
+| `--bp-xl` | 80rem (1280px) | 桌面 |
+
+🔴 **断点用 rem 不用 px** —— 用户调大字号时断点跟着变，这才是对的。
+
+🔴 **CSS 变量不能用在 media query 条件里**，所以写的时候仍要字面值
+（`@media (min-width: 48rem)`，不是 `var(--bp-md)`）。
+令牌的作用是：给流体计算提供锚点、给脚本查询、让"我们有几个断点"有唯一答案。
+
+---
+
+## 两份机器可读导出（给不同胃口的工具）
+
+| 文件 | 形状 | 喂给谁 |
+|---|---|---|
+| `ai/tokens.json` | DTCG 草案：键名带 `--`，字段带 `$`（`$value` / `$type`） | 想**读**令牌的人 / 认 DTCG 的工具 |
+| `ai/tokens.tree.json` | 分层：键名不带 `--`，字段不带 `$`（`value` / `type`） | **Style Dictionary / Figma Tokens（Tokens Studio）** |
+
+为什么要两份：**`$value` 和 `value` 是不兼容的两套约定**，
+同一个文件喂不进两类工具。`tokens.tree.json` 的 `index` 段把两种键名互相对应
+（`--paper` ↔ `color/paper`）。
+
+命令行可直接查：
+
+```bash
+node ai/cli.js tokens [--set=light|dark]        # 第一种
+node ai/cli.js tree   [--set=light|dark] [--cat=color]   # 第二种
+```
+
+⚠️ 第二份是**生成物**，它的正确性不是靠"再生成一遍"保证的 ——
+`token-tree-gate.py` 判据 ⑤ 会把每一个名字、每一个值拿到**真浏览器**里，
+用 Chrome 自己的 CSS 解析器（CSSOM）重新读一遍再比。
+
+---
+
+## 库里没引用、但承诺给你用的令牌
+
+下面这些令牌**本库的组件一个都没用**（`token-audience-gate.py` 会一直盯着这个数：
+现在 5 个，只能降不能升）。它们不是死代码 —— 是**阶梯的档位**和**给脚本读的常量**，
+你写自己的页面时可以直接引用。
+
+| 令牌 | 值 | 为什么库里没人用 |
+|---|---|---|
+| `--tracking-normal` | `0` | 字距阶梯的"常规"档：它是**默认值**，写了等于没写 |
+| `--bp-sm` / `--bp-lg` / `--bp-xl` | 见上表 | 断点**物理上不可能**被 `var()` 引用（进不了 media query 条件） |
+
+> 2026-10-10（第二次）：新增的 `04-recipes/report` 在本层内把边注重定义为 14em，
+> 因此不再引用本层的"边注"档 ⇒ 那个档位回到这张表里。
+> 棘轮数仍为 5（同一轮里既有回收也有放出，净额不变）。
+> ⚠️ 这不是"放水"：门禁把它挑出来的依据是它**真的**没人引用了。
+>
+> 2026-10-10：行高阶梯的"松"档与字号阶梯的 XL 档原先在这张表里。
+> 新增的 `04-recipes/analysis-report`（代码块行高）与
+> `04-recipes/data-showcase`（KPI 数值字号）开始引用它们 ⇒ 它们**不再**是孤儿。
+> 按双向校验规则从名单移除，棘轮数 7 → 5（棘轮只能降，本次是降）。
+>
+> ⚠️ 这一节里的**任何** `--` 开头字符串都会被 `token-audience-gate.py` 当作名单项，
+> 所以上面这句只能用中文描述、不能直接写令牌名。
+
+⚠️ 这张表是**双向校验**的：表里的令牌必须真的存在、真的没人引用；
+反过来，一个没人引用的公开令牌如果不在表里，门禁都会拦。
+（0.7.3 就据此挖出两个真缺陷：一个历史遗留的版心令牌被移除，
+一个"为抽屉造的缓动曲线"其实从没接到抽屉上。）
+
+---
+
+## 页面骨架 `page.css`（选配）
+
+`tokens.css` 管**值**，`typography.css` 管**辅助文字**，`page.css` 管**页面框**：
+页面底色/字色/安全区内边距、内容列宽、标题阶梯、行内代码、说明块、演示块。
+
+**只在写了 `class="page"` 的页面上生效**（不写就不生效，对宿主零副作用）。
+
+要改全局观感，改这几个令牌就够了 —— 不要在页面里再写一遍：
+
+| 令牌 | 值 | 管什么 |
+|---|---|---|
+| `--measure-page` | `52rem` | 内容列宽（所有 `.wrap` 一起变） |
+| `--tracking-title` | `-0.02em` | 标题字距 |
+| `--fs-2xl` | 见字号表 | 一级标题字号 |
+| `--sp-6` / `--sp-4` | 见间距表 | 页面框的上下 / 左右内边距 |
+| `--measure-prose` | 见下 | `.wrap--prose`（长文窄列） |
+
+`--measure-page` 的来历：收编之前 33 个页面写了 16 种列宽
+（680 / 720 / 760 / 800 / 820 / 860 / 900 px，以及 42 / 44 / 46 / 52 rem 和 72ch），
+彼此**没有语义差别**，纯粹是每次手敲随手写的。取众数 820px，落成干净的 `52rem`。
+
+⚠️ 页面里重写 `body` / `h1` / `h2` / `.wrap` / `code` 等
+**不会报错但也不会生效**（被 `.page` 前缀的定义以更高特异性静默盖掉，
+成为死声明）⇒ `05-audit/shell-gate.py` 会拦住它。
+
+## 精简档 的使用方式
+
+复制 **`04-recipes/tierA-tokens.css`** 进 `<style>`（**5.1 KB**，含浅色 102 + 暗色 33 个令牌，零外链零构建）。
+
+那一份是由 `tokens.css` **自动抽取**的（`python 05-audit/make-tiersnippet.py`），
+所以不会与本文件漂移；改了这个文件请重新生成。
+
+> 🔴 更正：这一行原先写的是「复制 `tokens.css` 里 `[核心]` 段，约 2 KB」，
+> **但 `[核心]` 这个区块从来不存在** —— 是个指向空处的假承诺。
+
+`responsive-demo.html` 可以拖窄窗口直接看出哪些在流体、哪些没有。

package/01-tokens/behavior/dismissable.js

@@ -0,0 +1,132 @@
+/**
+ * dismissable.js — 「关得掉」微行为核
+ *
+ * ==========================================================================
+ * 🔴 为什么要抽成核（数字是实测的，复算命令见本项目更新日志）
+ * --------------------------------------------------------------------------
+ *   抽之前，14 个组件 JS 里：
+ *     · Esc 关闭      手写了 10 处，分布在 7 个文件
+ *     · 点击外部关闭   手写了 7 处，分布在 7 个文件
+ *
+ *   同一件事写 7 份 ⇒ 改一处要改 7 处 ⇒ 必然漏（见 I-14）。
+ *   更难看的是**漏了没人知道**：popover 曾因为 `contains` 没把触发元素算进去，
+ *   导致"点触发器刚打开就被关掉" —— 这种 bug 会在每个手写副本里各犯一遍。
+ *
+ * ==========================================================================
+ * 边界：只管"关得掉"，不管别的
+ * --------------------------------------------------------------------------
+ *   ① Esc 关闭
+ *   ② 点击浮层之外关闭
+ *   不管：焦点归位（focus-return 核）、滚动锁、动画。
+ *   一个核只做一件事 —— 否则它就变成另一个"什么都管"的大文件。
+ *
+ * ==========================================================================
+ * 用法
+ * --------------------------------------------------------------------------
+ *   var d = flDismissable({
+ *     escOn:  [box, trigger],                       // 在这些元素上听 Esc
+ *     inside: [box, anchor],                        // 点在这些里面 ⇒ 不算"外部"
+ *     when:   function () { return opened; },       // 只有开着才响应
+ *     onDismiss: function (ev, reason) { close(); } // reason: 'esc' | 'outside'
+ *   });
+ *   d.destroy();     // 必须成对调用，否则监听器与栈都会泄漏
+ *
+ * ==========================================================================
+ * ⚠️ 三个必须知道的实现细节（都是实测踩出来的，改之前先读）
+ * --------------------------------------------------------------------------
+ *   ① **Esc 挂在元素上（冒泡阶段），不是挂在 document 上**：
+ *      冒泡从最内层往外走 ⇒ 最内层先收到 ⇒ 它 stopPropagation 之后
+ *      外层的 dialog 就收不到 ⇒ 一次 Esc 只关最内层。
+ *      （挂在 document 捕获阶段会**先**触发 ⇒ 分不清内外层 ⇒ 两层一起关）
+ *
+ *   ② **外部点击必须挂在 document 捕获阶段**：
+ *      组件自己的 click 先跑、再轮到"是不是外部"的判定，
+ *      否则点触发器会被判成外部点击 ⇒ 刚打开就关掉（popover 踩过）。
+ *
+ *   ③ **栈必须挂在 window 上，不能写在闭包里**：
+ *      本核会被 05-audit/gen-behavior.py 整块注入进多个组件文件，
+ *      每个组件拿到的是**各自的副本**（各自闭包）。
+ *      栈若写在闭包里 ⇒ 两个组件各维护一个栈 ⇒ 嵌套时 ① 的语义失效。
+ *
+ *   栈的取舍（如实写明）：同一时刻**只允许一个非模态浮层打开**
+ *   （本库既有约定，popover 的 open() 会先关掉别的），
+ *   在此前提下"取最后一个活跃的记录"与"取最后打开的那个"等价。
+ *
+ * ==========================================================================
+ * 约束：ES5 · 零依赖 · 可被整块注入 · 不污染除 __flDismiss 外的任何全局
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: dismissable ==== */
+var flDismissable = function (opts) {
+  var opt = opts || {};
+  var escOn = opt.escOn || [];
+  var inside = opt.inside || [];
+  var when = opt.when || function () { return true; };
+  var onDismiss = opt.onDismiss || function () {};
+
+  var shared = window.__flDismiss || (window.__flDismiss = { stack: [], bound: false });
+
+  function isInside(node) {
+    if (!node) return false;
+    for (var i = 0; i < inside.length; i++) {
+      var el = inside[i];
+      if (!el || !el.contains) continue;
+      if (el === node || el.contains(node)) return true;
+    }
+    return false;
+  }
+
+  function onKey(e) {
+    if (!when()) return;
+    var k = e.key;
+    if (k !== 'Escape' && k !== 'Esc' && e.keyCode !== 27) return;
+    /* 🔴 为什么 onDismiss 在前、preventDefault/stopPropagation 在后
+       （0.8.8 改）：**分级 Esc** 需要核让组件有机会说"这次我没关"。
+       combobox 的 Esc 是三级的：
+         ① 列表开着 → 关列表
+         ② 列表关了、输入有字 → 清空输入
+         ③ 都没了 → 什么都不做（此时**不该**阻止默认行为，
+            让 Esc 能继续传给外层浮层）
+       而原实现是「无条件 preventDefault + stopPropagation，再调 onDismiss」
+       ⇒ 组件根本无法表达"这次我没关"。
+       ⇒ 改成：先问onDismiss，它返回 false 就**不干预**默认行为。
+       ⚠️ 顺序安全性：stopPropagation 只需在**本次监听器执行期间**被调用即可
+          阻止冒泡到外层，放在 onDismiss 之后仍然有效。
+    */
+    var closed = onDismiss(e, 'esc');
+    if (closed === false) return;
+    if (e.preventDefault) e.preventDefault();
+    if (e.stopPropagation) e.stopPropagation();
+  }
+
+  function onDocClick(e) {
+    var top = null;
+    for (var i = shared.stack.length - 1; i >= 0; i--) {
+      if (shared.stack[i].when()) { top = shared.stack[i]; break; }
+    }
+    if (!top || top.isInside(e.target)) return;
+    top.onDismiss(e, 'outside');
+  }
+
+  var rec = { when: when, isInside: isInside, onDismiss: onDismiss };
+
+  for (var j = 0; j < escOn.length; j++) {
+    if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
+  }
+  shared.stack.push(rec);
+  if (!shared.bound) {
+    shared.bound = true;
+    document.addEventListener('click', onDocClick, true);
+  }
+
+  return {
+    destroy: function () {
+      for (var j = 0; j < escOn.length; j++) {
+        if (escOn[j]) escOn[j].removeEventListener('keydown', onKey);
+      }
+      var k = shared.stack.indexOf(rec);
+      if (k >= 0) shared.stack.splice(k, 1);
+    },
+  };
+};
+/* ==== BEHAVIOR CORE END: dismissable ==== */

package/01-tokens/behavior/emit.js

@@ -0,0 +1,76 @@
+/**
+ * emit.js — 「统一事件发射」工具核
+ *
+ * ==========================================================================
+ * 🔴 为什么要抽成核（不是因为懒，是因为这里有一处**必须只有一份**的兜底）
+ * --------------------------------------------------------------------------
+ *   老 WebView（以及部分精简档内核）**没有 `CustomEvent` 构造函数**，
+ *   只有 `document.createEvent('CustomEvent')` + `initCustomEvent()`。
+ *
+ *   ⚠️ 这个坑的恶劣之处：
+ *     · `new CustomEvent(...)` 在老环境里**抛异常**，而且是在**用户交互的路径上**抛
+ *       （点一下按钮才炸），本地 Chrome 永远测不出来；
+ *     · 若每个组件各写一次兜底，8 个组件里迟早有一个只写了新写法
+ *       ⇒ 那个组件在真机上"点了没反应"，而且控制台不一定有线索。
+ *
+ *   ⇒ 兜底逻辑只能有一份，由门禁保证每个使用点逐行一致。
+ *
+ * ==========================================================================
+ * 事件模型（统一约定，不是各组件各起各的）
+ * --------------------------------------------------------------------------
+ *   ① 事件名一律 `fl-` 前缀。
+ *      为什么：组件内部有原生 `<input>` / `<button>`，它们的 `change` / `click`
+ *      会**冒泡上来**；不加前缀 ⇒ 调用方 `el.addEventListener('change', ...)`
+ *      会收到自己没订阅过的东西。
+ *   ② 一律 `bubbles: true`：调用方可以在**祖先**上做事件委托。
+ *   ③ 一律 `cancelable: false`：本库的事件是**通知**，不是"可撤销的动作"。
+ *      （真要拦就用回调里 return false，别把两件事混在事件上。）
+ *   ④ 一律在**组件根元素**上派发，不在内部子元素上。
+ *   ⑤ `detail` 统一带 `value`（有值的组件），组件自己的字段另加。
+ *   ⑥ 委托时**必须认 `e.target`**：事件会冒泡，嵌套组件（如 tabs 里放
+ *      select）会在同一个祖先上收到两个 `fl-change`；靠 `e.target` 认
+ *      组件根，事件名不能代替身份。
+ *   ⑦ 顺序：**先派发事件，再调回调**。回调是调用方写的，可能抛异常；
+ *      事件先落地 ⇒ 回调炸了也不会连累挂在祖先上的其它订阅者。
+
+ * ==========================================================================
+ * 用法
+ * --------------------------------------------------------------------------
+ *   flEmit(root, 'fl-change', { value: v });
+ *   // 名字里已带 fl- 就不重复加；不带就自动补 —— 防止漏写前缀
+ *
+ * ⚠️ 它**不是"行为核"**（不像 Esc 关闭那样是用户能感知的行为），
+ *   所以不进 `ai/behaviors.json` 的行为矩阵；它是**工具核**。
+ *
+ * ==========================================================================
+ * ⚠️ 注入块里的注释会**被复制进每个使用点**（gzip 也要算）
+ * --------------------------------------------------------------------------
+ *   ⇒ 长解释一律写在**本文件头**（BEGIN 标记之外），注入块内只留一行提示。
+ *
+ * ==========================================================================
+ * 约束：ES5 · 零依赖 · 可被整块注入 · 不新增任何全局
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: emit ==== */
+var flEmit = function (el, name, detail) {
+  if (!el || !el.dispatchEvent) return null;
+  var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+  var ev = null;
+  /* 老 WebView 没有 CustomEvent 构造函数 ⇒ 兜底走 createEvent（理由见文件头）*/
+  if (typeof window.CustomEvent === 'function') {
+    try {
+      ev = new window.CustomEvent(type, {
+        detail: detail || null, bubbles: true, cancelable: false
+      });
+    } catch (e) { ev = null; }
+  }
+  if (!ev) {
+    try {
+      ev = document.createEvent('CustomEvent');
+      ev.initCustomEvent(type, true, false, detail || null);
+    } catch (e2) { return null; }
+  }
+  el.dispatchEvent(ev);
+  return ev;
+};
+/* ==== BEHAVIOR CORE END: emit ==== */

package/01-tokens/behavior/focus-return.js

@@ -0,0 +1,81 @@
+/**
+ * focus-return.js — 「焦点归位」微行为核
+ *
+ * ==========================================================================
+ * 🔴 为什么要抽成核（14 个组件 JS 实测）
+ * --------------------------------------------------------------------------
+ *   "记住当前焦点，关闭时还回去"被手写了 **6 处**，分布在 5 个文件
+ *   （drawer / overlay / popover / dropdown / pagination）。
+ *
+ *   它看起来只有两行（存 activeElement、再 focus 回去），
+ *   但每一处手写副本都要各自回答三个问题，而实测**每处答得都不一样**：
+ *
+ *     ① 要记的元素已经**不在文档里**了怎么办？（列表项被删了）
+ *     ② 焦点本来就在 body 上，要不要记？
+ *     ③ 还原失败（元素不可聚焦）要不要抛错？
+ *
+ *   ⇒ 于是 5 个组件有 5 种降级行为，其中至少一种是**静默把焦点丢在 body 上**
+ *     （键盘用户要从页面开头重新 Tab，而开发者完全看不出来）。
+ *
+ * ==========================================================================
+ * 边界
+ * --------------------------------------------------------------------------
+ *   只管"记住 / 归还"这一件事。
+ *   不管：焦点陷阱（那是 dialog 的事）、初始焦点该落在哪、滚动锁。
+ *
+ * ==========================================================================
+ * 用法
+ * --------------------------------------------------------------------------
+ *   var fr = flFocusReturn({ fallback: trigger });  // 原元素没了时的退路
+ *   fr.save();        // 打开浮层**之前**调
+ *   ...
+ *   fr.restore();     // 关闭时调；还回去了返回 true
+ *
+ * ==========================================================================
+ * ⚠️ 三个必须知道的实现细节（都是实测定下来的）
+ * --------------------------------------------------------------------------
+ *   ① **body 不当作目标**。焦点默认就在 body 上，记它等于没记，
+ *      还原时也不会比"不动"更好。⇒ save() 记 null，restore() 退到 fallback。
+ *   ② **还原前必须 document.contains 判一次**。元素被移除后 focus() 不报错，
+ *      但**焦点不会动** ⇒ 用户以为还回去了，其实焦点掉在 body 上（静默失效）。
+ *   ③ **restore() 之后清空**。否则第二次 restore 会把焦点又拽回同一个元素，
+ *      打断用户**已经主动移走**的焦点。
+ *
+ * ==========================================================================
+ * 约束：ES5 · 零依赖 · 可被整块注入 · 不新增任何全局
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: focus-return ==== */
+var flFocusReturn = function (opts) {
+  var opt = opts || {};
+  var saved = null;
+
+  return {
+    save: function () {
+      var a = document.activeElement;
+      saved = (a && a !== document.body && a.focus) ? a : null;
+      return saved;
+    },
+
+    restore: function () {
+      var target = saved;
+      /* ⚠️ 见文档 ②：不判 contains 的话，元素被移除后 focus() 不报错
+         但焦点不动 ⇒ 用户以为还回去了，其实掉在 body 上。 */
+      if (!target || !document.contains(target)) target = opt.fallback || null;
+      if (!target) { saved = null; return false; }
+      try {
+        target.focus();
+      } catch (e) {
+        saved = null;
+        return false;
+      }
+      var ok = document.activeElement === target;
+      saved = null;   /* 见文档 ③ */
+      return ok;
+    },
+
+    target: function () { return saved; },
+    clear: function () { saved = null; },
+  };
+};
+/* ==== BEHAVIOR CORE END: focus-return ==== */

package/01-tokens/behavior/roving.js

@@ -0,0 +1,152 @@
+/**
+ * roving.js — 「方向键游走」微行为核（roving tabindex）
+ *
+ * ==========================================================================
+ * 🔴 为什么要抽成核（14 个组件 JS 实测）
+ * --------------------------------------------------------------------------
+ *   `tabindex` 被手写了 **33 处**，分布在 9 个文件，是数量最多的一项。
+ *
+ *   其中真正危险的不是"写了很多次"，而是**每一处自己决定边界行为**：
+ *
+ *     · 走到最后一个再按一次 ⇒ 有的绕回第一个，有的**停住**（同一库两种手感）
+ *     · 禁用项 ⇒ 有的跳过，有的**停在上面不动**（用户以为卡了）
+ *     · Home / End ⇒ 有的实现，有的**没实现**
+ *     · 纵向 / 横向 ⇒ 有的只认 ↑↓，有的只认 ←→，有的两种都认
+ *
+ *   ⇒ 同一个"按 ↓"在不同组件里有不同结果。这种不一致**没有门禁会报**，
+ *     只有键盘用户会遇到。
+ *
+ * ==========================================================================
+ * 边界
+ * --------------------------------------------------------------------------
+ *   只管"一组项里焦点怎么走"。
+ *   不管：展开/收起（那是 tree 自己的语义）、选中与激活的差别
+ *   （APG 里 automatic 与 manual 的差别由组件决定 —— 本核只告诉它"移到第几项"）。
+ *
+ * ==========================================================================
+ * 用法
+ * --------------------------------------------------------------------------
+ *   var roving = flRoving({
+ *     container: listEl,              // 在哪里听 keydown
+ *     items:   function () { return allTabs; },      // tabindex 全集（含禁用项）
+ *     movable: function () { return enabledTabs; },  // 可移动子集（省略则用 items）
+ *     nodeOf:  function (x) { return x.node; },      // 项 → DOM 节点（省略则项就是节点）
+ *     axis:    'y',                   // 'x' ←→（默认） / 'y' ↑↓
+ *     loop:    true,                  // 默认绕回
+ *     homeEnd: true,                  // 默认支持 Home / End
+ *     tabindex: true,                 // 默认接管 tabindex；false = 只接管步进
+ *     onMove:  function (i, item, reason) { ... }    // reason: step / home / end
+ *   });
+ *   roving.rove(targetNode);          // 把 tabindex="0" 给目标，其余 -1
+ *   roving.destroy();                 // 摘掉 keydown
+ *
+ * ==========================================================================
+ * ⚠️ 四个必须知道的实现细节
+ * --------------------------------------------------------------------------
+ *   ① **items 与 movable 必须分开**。tabindex 要落在**全集**上（禁用项也得是 -1，
+ *      否则 Tab 会停到禁用项上），但移动只在**可用子集**里进行。
+ *      早期写法只用一个列表 ⇒ 禁用项要么能被方向键走到、要么 Tab 能停上去。
+ *   ② **循环用取模，不要用 if 夹逼**。`((i + d) % n + n) % n` 对负数也对，
+ *      而 `if (i < 0) i = n - 1` 在 d 的绝对值大于 n 时会错。
+ *   ③ **核只负责 preventDefault + stopPropagation**，不替组件决定"移动后做什么"
+ *      （激活还是只移焦点）—— 那是 APG 里 automatic / manual 的分工。
+ *   ④ **"步进"与"roving tabindex"是两件事**，用 `tabindex: false` 分开。
+ *      APG 菜单的菜单项按规范**全部 tabindex=-1**（焦点由程序移动，
+ *      菜单项永远不占 Tab 位）⇒ 它要的是同一套步进/绕回/Home·End，
+ *      但**不能**让核把某一项改成 0（会破坏"Tab 用来关闭菜单"这条契约）。
+ *
+ * ==========================================================================
+ * ⚠️ 注入块里的注释会**被复制进每个使用点**（真金白银，gzip 也要算）
+ * --------------------------------------------------------------------------
+ *   ⇒ 长解释一律写在**本文件头**（BEGIN 标记之外），注入块内只留一行提示。
+ *   ⇒ 同理：只暴露**有人用**的 API。初版多暴露了一个 `wrap()`
+ *     （"越界就夹回边界"），实测零个使用点调用 ⇒ 它是被注入进 3 个组件的
+ *     死代码，每个组件白背几百字节 ⇒ 删掉。真需要时从版本历史里找回来，
+ *     别让使用点为"可能会用到"买单。
+ *
+ * ==========================================================================
+ * 约束：ES5 · 零依赖 · 可被整块注入 · 不新增任何全局
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: roving ==== */
+var flRoving = function (opts) {
+  var opt = opts || {};
+  var container = opt.container;
+  var all = opt.items || function () { return []; };
+  var movable = opt.movable || all;
+  var nodeOf = opt.nodeOf || function (x) { return x; };
+  var axis = opt.axis || 'x';
+  var loop = opt.loop !== false;
+  var homeEnd = opt.homeEnd !== false;
+  /* ④ tabindex: false ⇒ 只要步进，不要 roving tabindex（理由见文件头）*/
+  var roveTab = opt.tabindex !== false;
+  var onMove = opt.onMove || function () {};
+
+  /* ① tabindex 落在**全集**上：禁用项也必须是 -1，否则 Tab 会停上去 */
+  function rove(target) {
+    if (!roveTab) return target;
+    var l = all() || [];
+    for (var i = 0; i < l.length; i++) {
+      var n = nodeOf(l[i]);
+      if (!n || !n.setAttribute) continue;
+      n.setAttribute('tabindex', n === target ? '0' : '-1');
+    }
+    return target;
+  }
+
+  /* ② 取模循环：对负数、对 |d| > n 都对 */
+  function step(i, d) {
+    var n = (movable() || []).length;
+    if (!n) return -1;
+    if (loop) return ((i + d) % n + n) % n;
+    var t = i + d;
+    return (t < 0 || t >= n) ? -1 : t;
+  }
+
+  function indexOfNode(node) {
+    var l = movable() || [];
+    for (var i = 0; i < l.length; i++) {
+      if (nodeOf(l[i]) === node) return i;
+    }
+    return -1;
+  }
+
+  function onKey(e) {
+    var l = movable() || [];
+    if (!l.length) return;
+    var i = indexOfNode(e.target);
+    if (i < 0) return;
+    var k = e.key;
+    var next = -1;
+    var reason = 'step';
+
+    if (axis === 'y') {
+      if (k === 'ArrowDown') next = step(i, 1);
+      else if (k === 'ArrowUp') next = step(i, -1);
+    } else {
+      if (k === 'ArrowRight') next = step(i, 1);
+      else if (k === 'ArrowLeft') next = step(i, -1);
+    }
+    if (homeEnd && k === 'Home') { next = 0; reason = 'home'; }
+    else if (homeEnd && k === 'End') { next = l.length - 1; reason = 'end'; }
+
+    if (next < 0 || next >= l.length) return;
+    /* ③ 只拦事件，不替组件决定移动后做什么 */
+    if (e.preventDefault) e.preventDefault();
+    if (e.stopPropagation) e.stopPropagation();
+    onMove(next, l[next], reason);
+  }
+
+  if (container) container.addEventListener('keydown', onKey);
+
+  /* ⚠️ 只暴露有人用的东西（理由见文件头）*/
+  return {
+    rove: rove,
+    step: step,
+    indexOf: indexOfNode,
+    destroy: function () {
+      if (container) container.removeEventListener('keydown', onKey);
+    },
+  };
+};
+/* ==== BEHAVIOR CORE END: roving ==== */