agentcss 0.13.2 → 0.15.0

package/01-tokens/behavior/dismissable.js

@@ -26,13 +26,14 @@
  *   var d = flDismissable({
  *     escOn:  [box, trigger],                       // 在这些元素上听 Esc
  *     inside: [box, anchor],                        // 点在这些里面 ⇒ 不算"外部"
+ *     outside: false,                               // 模态：点外部**不关**（默认 true）
  *     when:   function () { return opened; },       // 只有开着才响应
  *     onDismiss: function (ev, reason) { close(); } // reason: 'esc' | 'outside'
  *   });
  *   d.destroy();     // 必须成对调用，否则监听器与栈都会泄漏
  *
  * ==========================================================================
- * ⚠️ 三个必须知道的实现细节（都是实测踩出来的，改之前先读）
+ * ⚠️ 五个必须知道的实现细节（都是实测踩出来的，改之前先读）
  * --------------------------------------------------------------------------
  *   ① **Esc 挂在元素上（冒泡阶段），不是挂在 document 上**：
  *      冒泡从最内层往外走 ⇒ 最内层先收到 ⇒ 它 stopPropagation 之后
@@ -52,6 +53,29 @@
  *   （本库既有约定，popover 的 open() 会先关掉别的），
  *   在此前提下"取最后一个活跃的记录"与"取最后打开的那个"等价。
  *
+ *   ④ **模态弹层用 `outside: false`，不进栈**（0.14.0 加）：
+ *      模态的定义就是"点外面不该关"，而外部点击只能挂 document（②）。
+ *      曾经的结论是"那就不收编"（见 ai/behaviors.json 的 0.8.6 记录）——
+ *      于是 drawer / overlay 各留一份手写的 Esc，I-14 的病留在原地。
+ *      开关放进核里之后，收编不必改组件的**语义**，只改它的**接线**。
+ *      不进栈的后果要写清：模态层不再参与"点外部关最内层"的仲裁，
+ *      它压根不该被这条规则选中；Esc 走元素监听器，与栈无关。
+ *      ⚠️ 模态层里的非模态浮层（对话框里的下拉菜单）仍正常进栈 ——
+ *         点菜单外面先关菜单、再点一次才轮到遮罩，层次不会乱。
+ *
+ *   ⑤ **先问 `onDismiss`，再 `preventDefault` / `stopPropagation`**（0.8.8 改）：
+ *      **分级 Esc** 需要核让组件有机会说"这次我没关"。combobox 的 Esc 是三级：
+ *        ① 列表开着 → 关列表
+ *        ② 列表关了、输入有字 → 清空输入
+ *        ③ 都没了 → 什么都不做（此时**不该**阻止默认行为，让 Esc 传给外层）
+ *      原实现是"无条件阻止，再调 onDismiss" ⇒ 组件无法表达"这次我没关"。
+ *      ⚠️ 顺序安全性：stopPropagation 只需在**本次监听器执行期间**被调用即可
+ *         阻止冒泡到外层，放在 onDismiss 之后仍然有效。
+ *
+ * ⚠️ 注入块里只留一行指针，长解释一律写在本文件头（同上，gzip 要算）：
+ *    这段注释以前在块内，8 个使用点各背 429 字节 ⇒ 收编时被 size-budget
+ *    当场红出来（drawer +44%），挪到这里。
+ *
  * ==========================================================================
  * 约束：ES5 · 零依赖 · 可被整块注入 · 不污染除 __flDismiss 外的任何全局
  * ==========================================================================
@@ -61,6 +85,7 @@ var flDismissable = function (opts) {
   var opt = opts || {};
   var escOn = opt.escOn || [];
   var inside = opt.inside || [];
+  var outside = opt.outside !== false;
   var when = opt.when || function () { return true; };
   var onDismiss = opt.onDismiss || function () {};
 
@@ -80,19 +105,7 @@ var flDismissable = function (opts) {
     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 之后仍然有效。
-    */
+    /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
     var closed = onDismiss(e, 'esc');
     if (closed === false) return;
     if (e.preventDefault) e.preventDefault();
@@ -113,7 +126,10 @@ var flDismissable = function (opts) {
   for (var j = 0; j < escOn.length; j++) {
     if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
   }
-  shared.stack.push(rec);
+  /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+     模态层不该被这条规则选中（见文件头 ④）。
+     ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+  if (outside) shared.stack.push(rec);
   if (!shared.bound) {
     shared.bound = true;
     document.addEventListener('click', onDocClick, true);

package/02-primitives/combobox/combobox.js

@@ -24,6 +24,7 @@
     var opt = opts || {};
     var escOn = opt.escOn || [];
     var inside = opt.inside || [];
+    var outside = opt.outside !== false;
     var when = opt.when || function () { return true; };
     var onDismiss = opt.onDismiss || function () {};
 
@@ -43,19 +44,7 @@
       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 之后仍然有效。
-      */
+      /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
       var closed = onDismiss(e, 'esc');
       if (closed === false) return;
       if (e.preventDefault) e.preventDefault();
@@ -76,7 +65,10 @@
     for (var j = 0; j < escOn.length; j++) {
       if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
     }
-    shared.stack.push(rec);
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) shared.stack.push(rec);
     if (!shared.bound) {
       shared.bound = true;
       document.addEventListener('click', onDocClick, true);

package/02-primitives/popover/popover.js

@@ -18,6 +18,7 @@
     var opt = opts || {};
     var escOn = opt.escOn || [];
     var inside = opt.inside || [];
+    var outside = opt.outside !== false;
     var when = opt.when || function () { return true; };
     var onDismiss = opt.onDismiss || function () {};
 
@@ -37,19 +38,7 @@
       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 之后仍然有效。
-      */
+      /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
       var closed = onDismiss(e, 'esc');
       if (closed === false) return;
       if (e.preventDefault) e.preventDefault();
@@ -70,7 +59,10 @@
     for (var j = 0; j < escOn.length; j++) {
       if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
     }
-    shared.stack.push(rec);
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) shared.stack.push(rec);
     if (!shared.bound) {
       shared.bound = true;
       document.addEventListener('click', onDocClick, true);

package/02-primitives/select/README.md

@@ -68,6 +68,11 @@ const sel = Select.create(元素, { multiple: false, value: 'b', label: '选项'
 **① 为什么强调"落在选中项"**：这是 APG 明确要求的，也是最常做错的一条。
 打开后焦点在第一项，用户按一次`↓` 就跳到第二项 —— 原来选的那项被跳过了。
 
+⚠️ 这里的"焦点"是**活动项**：用 `aria-activedescendant` 指到选中项，DOM 焦点仍留在
+按钮上。这是 APG「select-only combobox」的合法形态 —— 拿 `document.activeElement`
+去要求它落进 `<ul>` 会判成缺陷，实际不是。本库的判据也是按前一种断的
+（`opener-path-check` 里这条组件的 `focus` 声明为 `activedesc`）。
+
 ## 类型搜索（typeahead）
 
 连续打字跳到匹配项。**原生 `<select>` 有这个能力，所以自建的必须有**。

package/02-primitives/select/select.js

@@ -26,6 +26,7 @@
     var opt = opts || {};
     var escOn = opt.escOn || [];
     var inside = opt.inside || [];
+    var outside = opt.outside !== false;
     var when = opt.when || function () { return true; };
     var onDismiss = opt.onDismiss || function () {};
 
@@ -45,19 +46,7 @@
       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 之后仍然有效。
-      */
+      /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
       var closed = onDismiss(e, 'esc');
       if (closed === false) return;
       if (e.preventDefault) e.preventDefault();
@@ -78,7 +67,10 @@
     for (var j = 0; j < escOn.length; j++) {
       if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
     }
-    shared.stack.push(rec);
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) shared.stack.push(rec);
     if (!shared.bound) {
       shared.bound = true;
       document.addEventListener('click', onDocClick, true);

package/03-patterns/drawer/drawer.js

@@ -74,6 +74,73 @@
   };
   /* ==== BEHAVIOR INJECT END: focus-return ==== */
 
+  /* ==== BEHAVIOR INJECT BEGIN: dismissable ==== */
+  var flDismissable = function (opts) {
+    var opt = opts || {};
+    var escOn = opt.escOn || [];
+    var inside = opt.inside || [];
+    var outside = opt.outside !== false;
+    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，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
+      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);
+    }
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) 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 INJECT END: dismissable ==== */
+
   var FOCUSABLE = [
     'a[href]',
     'button:not([disabled])',
@@ -204,12 +271,23 @@
       (f[0] || d).focus();
     }
 
+    /* ① Esc 与「点抽屉之外关闭」走 dismissable 核（0.14.0 收编）。
+       0.8.6 曾**拒绝收编**，理由写得很实在：核当时只有"点外部一律关"，
+       而 drawer 是模态。现在核有了 `outside` 开关（模态层不进栈），
+       收编不再需要改组件的语义 —— 只改接线。
+       ⚠️ inside 只放抽屉本体，**不能**把 host（遮罩）也放进去：
+          放进去等于声明"点遮罩算内部"，"点遮罩关闭"立刻变成谎话
+          （nav 那一格踩过这个坑，见 ai/behaviors.json）。 */
+    var dm = flDismissable({
+      escOn: [d],
+      inside: [d],
+      when: function () { return !closed; },
+      onDismiss: function () { close(); },
+    });
+
     function onKey(e) {
-      var k = e.key;
-      /* ② Esc 关闭 */
-      if (k === 'Escape' || k === 'Esc') { e.preventDefault(); close(); return; }
-      if (k !== 'Tab') return;
-      /* ① 焦点陷阱：Tab / Shift+Tab 在抽屉内循环 */
+      if (e.key !== 'Tab') return;
+      /* ② 焦点陷阱：Tab / Shift+Tab 在抽屉内循环（Esc 已交给核） */
       var list = [].slice.call(d.querySelectorAll(FOCUSABLE))
         .filter(function (x) { return x.offsetParent !== null; });
       if (!list.length) { e.preventDefault(); d.focus(); return; }
@@ -220,10 +298,8 @@
         e.preventDefault(); first.focus();
       }
     }
-    function onBackdropClick(e) { if (e.target === host) close(); }
 
     d.addEventListener('keydown', onKey);
-    host.addEventListener('click', onBackdropClick);
     closeBtn.addEventListener('click', function () { close(); });
 
     var closed = false;
@@ -232,7 +308,9 @@
       closed = true;
       d.setAttribute('data-state', 'leaving');
       d.removeEventListener('keydown', onKey);
-      host.removeEventListener('click', onBackdropClick);
+      /* 核的监听器与栈记录必须一起摘：只摘 Esc 不摘栈的话，
+         点外部仍会关到一个已经没了的抽屉（dismissable 门禁 ⑥ 守这条）。 */
+      dm.destroy();
       setBackgroundInert(false);
       unlockScroll();
       /* 动画结束再移除；reduced-motion 下没有 transition ⇒ 兜底定时器 */

package/03-patterns/dropdown/README.md

@@ -10,6 +10,7 @@
 | `Esc` | 关闭，并把焦点**还给按钮** |
 | `Tab` | 关闭菜单（焦点移到下一个元素）|
 | `Enter` / `Space` | 激活当前项 |
+| 字母 / 数字（**可选**） | 跳到名字以该前缀开头的项（APG 标为 `(Optional)`；见下） |
 
 ## ⚠️ 另有两条容易漏的
 
@@ -66,12 +67,27 @@ menu.setAttribute('role', 'menu');
 `data-state` / `data-value`，**不用 class 切换** —— 这是全库 INVARIANT I-8
 （状态必须活在 DOM 属性上），也是门禁会查的东西。
 
-## 成熟度：beta（两条行为债，如实列出）
+## 成熟度：stable（行为零欠账）
 
-| 债 | 现在的后果 |
+两条历史债都收编了，记账在 `ai/behaviors.json`：
+
+| 曾经 | 现在 |
 |---|---|
-| `focus-return:manual` | 关闭后归位是手写的，不是统一机制 |
-| `typeahead:gap` | **没有类型搜索** —— APG 的 Menu Button 不硬性要求，但列表长时体验缺失 |
+| `focus-return:manual` | 0.8.6 收编：`open()` 里 `save()`、`close()` 里 `restore()`，替掉手写的 `btn.focus()` |
+| `typeahead:gap` | 0.15.0 收编：打字跳项走 typeahead 核（见下） |
+
+### 打字跳项（APG 的 `(Optional)` 项）
+
+打一个字母 ⇒ 跳到**下一个**以它开头的项；快速连打 ⇒ 前缀累积；连打同一个字母 ⇒
+在匹配项之间循环；不匹配 ⇒ **什么都不做**（APG 不要求"没找到"有反馈）。
+
+⚠️ **它天然只对拉丁字母标签有效**：中文标签靠输入法，而 IME 组字时 `keydown`
+给的是 `Process` / `Unidentified`，拿不到字符。所以判据用一张英文夹具测
+（`dropdown-check` ⑦），demo 的中文菜单不受影响、也不会因此变慢。
+
+⚠️ 匹配前会**剥掉开头的装饰符号**：带勾选的项文本是「✓ 按日期」，
+不剥的话打「按」永远匹配不到。这和 table 列头把 `↕` 念出来是同一类问题 ——
+装饰符号不该混进"名字"里。
 
 ## 反例
 

package/03-patterns/dropdown/dropdown.js

@@ -161,6 +161,7 @@
     var opt = opts || {};
     var escOn = opt.escOn || [];
     var inside = opt.inside || [];
+    var outside = opt.outside !== false;
     var when = opt.when || function () { return true; };
     var onDismiss = opt.onDismiss || function () {};
 
@@ -180,19 +181,7 @@
       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 之后仍然有效。
-      */
+      /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
       var closed = onDismiss(e, 'esc');
       if (closed === false) return;
       if (e.preventDefault) e.preventDefault();
@@ -213,7 +202,10 @@
     for (var j = 0; j < escOn.length; j++) {
       if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
     }
-    shared.stack.push(rec);
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) shared.stack.push(rec);
     if (!shared.bound) {
       shared.bound = true;
       document.addEventListener('click', onDocClick, true);
@@ -231,6 +223,72 @@
   };
   /* ==== BEHAVIOR INJECT END: dismissable ==== */
 
+  /* ==== BEHAVIOR INJECT BEGIN: typeahead ==== */
+  var flTypeahead = function (opts) {
+    var opt = opts || {};
+    var items = opt.items || function () { return []; };
+    var textOf = opt.textOf || function (x) { return String((x && x.textContent) || ''); };
+    var usable = opt.usable || function () { return true; };
+    var timeout = opt.timeout || 500;
+    var onHit = opt.onHit || function () {};
+    var buf = '';
+    var timer = null;
+    var last = -1;
+
+    function stop() {
+      if (timer) { clearTimeout(timer); timer = null; }
+    }
+
+    /* 连打同一字符 ⇒ 只按首字符匹配（理由见文件头 ③④）*/
+    function repeated(s) {
+      if (s.length < 2) return false;
+      for (var i = 1; i < s.length; i++) {
+        if (s.charAt(i) !== s.charAt(0)) return false;
+      }
+      return true;
+    }
+
+    function find(needle) {
+      var l = items() || [];
+      var n = l.length;
+      if (!n) return -1;
+      for (var k = 0; k < n; k++) {
+        var i = (last + 1 + k) % n;      /* ① 从当前项之后开始 ⇒ 会绕回 */
+        if (!usable(l[i])) continue;     /* ⑤ */
+        if (textOf(l[i]).toLowerCase().indexOf(needle) === 0) return i;
+      }
+      return -1;                          /* ⑥ */
+    }
+
+    function type(ch) {
+      if (!ch) return -1;
+      buf += String(ch).toLowerCase();    /* ② */
+      stop();
+      timer = setTimeout(clear, timeout); /* ④ */
+      var needle = repeated(buf) ? buf.charAt(0) : buf;   /* ③ */
+      var i = find(needle);
+      if (i >= 0) {
+        last = i;
+        onHit(i, (items() || [])[i], buf);
+      }
+      return i;
+    }
+
+    /* 只清缓冲，不清 last（理由见文件头）*/
+    function clear() {
+      buf = '';
+      stop();
+    }
+
+    return {
+      type: type,
+      clear: clear,
+      buffer: function () { return buf; },
+      destroy: function () { stop(); },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: typeahead ==== */
+
   /* ---- 旧环境兼容：Element.closest 在老 WebView 上不存在 ----
      直接调用会在真机上抛 `is not a function`（本地完全正常，
      只在老环境炸 —— 属静默失效）。这里做模块内兜底，
@@ -323,6 +381,8 @@
          焦点留在按钮上，菜单项永远进不去（真机用 NVDA + Edge 实测过）。
          APG 的菜单按钮也是这样：打开即把焦点交给第一项。 */
       focusAt(0);
+      /* 每次打开都从空缓冲开始：上次关菜单前打了一半的前缀不该留到这次 */
+      typeahead.clear();
       flEmit(root, 'fl-open', null);
       if (opt.onOpen) opt.onOpen();
     }
@@ -332,6 +392,7 @@
       menu.hidden = true;
       btn.setAttribute('aria-expanded', 'false');
       active = -1;
+      typeahead.clear();
       if (restoreFocus !== false) fr.restore();
       flEmit(root, 'fl-close', null);
       if (opt.onClose) opt.onClose();
@@ -367,6 +428,22 @@
       onMove: function (i) { focusAt(i); },
     });
 
+    /* ⑥ 打字跳项 —— APG Menu 的 `(Optional)` 项，走 typeahead 核。
+       匹配**可见文本**，但先剥掉开头的装饰符号：带勾选的项文本是
+       "✓ 按日期"，不剥的话打"按"永远匹配不到（同 table 列头 ↕ 那一类问题）。
+       ⚠️ 中文标签实际上打不出来：IME 走 keydown 时 key 是 Process / Unidentified。
+          这条是给拉丁字母标签的菜单用的 —— APG 的 typeahead 本来就是这个前提，
+          所以判据用一张英文夹具页测（见 dropdown-check ⑥）。 */
+    var typeahead = flTypeahead({
+      items: function () { return itemsOf(menu); },
+      textOf: function (el) {
+        var s = String((el && el.textContent) || '').replace(/\s+/g, ' ').trim();
+        return s.replace(/^[^0-9A-Za-z\u4e00-\u9fa5]+/, '');
+      },
+      usable: function (el) { return el.getAttribute('aria-disabled') !== 'true'; },
+      onHit: function (i) { focusAt(i); },
+    });
+
     /* ---------- 按钮 ---------- */
     /* 🔴 修：原来先 `setAttribute('aria-controls', menu.id || '')`
        **再**给 menu.id ⇒ aria-controls 永远拿到空串。
@@ -424,6 +501,17 @@
          留在原地会**关两次**（同一元素上的两个监听器，stopPropagation 挡不住
          同级的另一个监听器，那是 stopImmediatePropagation 的活）⇒ onClose 被调两遍。 */
 
+      /* ③b 可打印字符 ⇒ 跳到名字以它开头的项（APG 的 (Optional) 项）
+         · 空格排除：它的语义是"激活当前项"（下面 ④）
+         · 带 Ctrl / Meta / Alt 排除：那是浏览器快捷键
+         · isComposing 时排除：中文输入法正在组字，不能抢 */
+      if (k.length === 1 && k !== ' ' &&
+          !e.ctrlKey && !e.metaKey && !e.altKey && !e.isComposing) {
+        e.preventDefault();
+        typeahead.type(k);
+        return;
+      }
+
       /* ③ Tab 关闭（不拦截，让焦点自然走到下一个）*/
       if (k === 'Tab') { close(false); return; }
 
@@ -448,7 +536,10 @@
     return {
       open: open,
       close: close,
-      destroy: function () { roving.destroy(); dismiss.destroy(); menu.hidden = true; },
+      destroy: function () {
+        roving.destroy(); dismiss.destroy(); typeahead.destroy();
+        menu.hidden = true;
+      },
     };
   }
 

package/03-patterns/nav/nav.js

@@ -126,6 +126,7 @@
     var opt = opts || {};
     var escOn = opt.escOn || [];
     var inside = opt.inside || [];
+    var outside = opt.outside !== false;
     var when = opt.when || function () { return true; };
     var onDismiss = opt.onDismiss || function () {};
 
@@ -145,19 +146,7 @@
       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 之后仍然有效。
-      */
+      /* 先问 onDismiss，它返回 false 就不干预（分级 Esc，见文件头 ⑤） */
       var closed = onDismiss(e, 'esc');
       if (closed === false) return;
       if (e.preventDefault) e.preventDefault();
@@ -178,7 +167,10 @@
     for (var j = 0; j < escOn.length; j++) {
       if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
     }
-    shared.stack.push(rec);
+    /* 只有"点外部要关"的层才进栈：栈是给 onDocClick 挑最内层用的，
+       模态层不该被这条规则选中（见文件头 ④）。
+       ⚠️ Esc 不依赖栈（它挂在元素上），所以不进栈不影响 Esc。 */
+    if (outside) shared.stack.push(rec);
     if (!shared.bound) {
       shared.bound = true;
       document.addEventListener('click', onDocClick, true);