agentcss 0.13.1 → 0.14.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/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);
@@ -317,6 +309,12 @@
       menu.hidden = false;
       btn.setAttribute('aria-expanded', 'true');
       active = -1;
+      /* ⭐ 聚焦首项必须放在 open() 里，不能只写在键盘分支。
+         读屏用户在浏览模式下按 Enter，NVDA 会把它变成**一次点击**，
+         走的是 click 分支 ⇒ 键盘分支里的 `focusAt(0)` 根本没机会执行，
+         焦点留在按钮上，菜单项永远进不去（真机用 NVDA + Edge 实测过）。
+         APG 的菜单按钮也是这样：打开即把焦点交给第一项。 */
+      focusAt(0);
       flEmit(root, 'fl-open', null);
       if (opt.onOpen) opt.onOpen();
     }
@@ -391,12 +389,11 @@
     root.addEventListener('keydown', function (e) {
       var k = e.key;
 
-      /* 按钮上：↓ / Enter / Space 打开并聚焦首项 */
+      /* 按钮上：↓ / Enter / Space 打开（聚焦首项已由 open() 负责） */
       if (e.target === btn) {
         if (k === 'ArrowDown' || k === 'Enter' || k === ' ' || k === 'Spacebar') {
           e.preventDefault();
           open();
-          focusAt(0);
         }
         return;
       }

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);

package/03-patterns/overlay/overlay.js

@@ -357,6 +357,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 ==== */
   function dialog(opts) {
     opts = opts || {};
 
@@ -432,26 +499,25 @@
     openStack.push(stackEntry);
     if (!useInert) uninstallIsolation = installIsolation(stackEntry);
 
+    /* ① Esc 走 dismissable 核（0.14.0 收编）。
+       `outside: false` 是模态的定义：点外部**不该关**。核里这个开关专门
+       为它加的（不进栈 ⇒ 不参与"点外部关最内层"的仲裁）。
+       ⚠️ 点遮罩关闭是**另一件事**，不归核管：它带 danger / closeOnBackdrop
+          两个前置条件，是组件自己的语义（见下方 mousedown）。
+       关于"为什么不再手写 stopPropagation"：核在 onDismiss 之后统一
+       preventDefault + stopPropagation，一次 Esc 只关最内层的语义与
+       以前实测一致（两个 backdrop 是兄弟节点，本来也冒泡不到外层）。 */
+    var dm = flDismissable({
+      escOn: [box],
+      outside: false,
+      when: function () { return !closed; },
+      onDismiss: function () { close(); },
+    });
+
     /* ------------------------------------------------------------ 焦点 */
     function focusables() { return focusableIn(box); }
 
     box.addEventListener('keydown', function (e) {
-      if (e.key === 'Escape') {
-        e.preventDefault();
-        /* ⚠️ 防御性 stopPropagation —— 保留，但**当前结构下它不改变任何行为**。
-         * 等价突变体实测：删掉这一行，一次 Esc 仍然只关最内层。
-         * 原因：两个 `.dialog-backdrop` 是 `body` 的**兄弟**节点，外层 box 不是
-         * 内层的祖先，所以内层按钮的 keydown 冒泡路径是
-         *      button → .dialog → .dialog-backdrop → body
-         * —— 根本到不了外层的 `.dialog`（实测 `outer.contains(inner) === false`）。
-         * 原注释写「不拦住会一次关两层」，那是**假设了 DOM 嵌套**，与实现不符。
-         * 保留理由：若将来改成「内层放进外层 box」的真嵌套，这行就必需。
-         * 判据 `pattern-behavior-check.js ⑬` 验证的是**行为**（只关最内层），
-         * 它抓不到删除本行的突变 —— 那是等价突变体，不是判据失效。 */
-        e.stopPropagation();
-        close();
-        return;
-      }
       if (e.key !== 'Tab') return;
 
       /* focus trap：Tab 在弹层内循环，绝不跑到背后的页面去 */
@@ -527,6 +593,9 @@
     function close() {
       if (closed) return;
       closed = true;
+      /* 核的 Esc 监听器要摘（outside:false ⇒ 它本来就没进栈，
+         但 destroy 仍然必须调用：摘监听器与摘栈是同一件事的两半）。 */
+      dm.destroy();
 
       /* 🔴 焦点归还前先看清**焦点现在在谁手里**（必须在移除 backdrop 之前读，
          移除之后 activeElement 会变成 body）。

package/03-patterns/tooltip/tooltip.js

@@ -60,6 +60,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 () {};
 
@@ -79,19 +80,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();
@@ -112,7 +101,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/04-recipes/table/table.css

@@ -72,10 +72,25 @@
   outline-offset: var(--focus-ring-offset);
 }
 
+/* ⭐ 排序指示符改用 mask 画，不再用文字字形。
+   原因：浏览器会把 ::after 的 `content` 文本算进**可访问名**（name-from-contents，
+   `<button>` / `<a>` 这类），读屏于是念出「公司 · ↕ · 按钮」—— 这个符号对用户毫无意义，
+   而且自动检查抓不到（名字非空即过）。换成图像后字形不进无障碍树。
+   ⚠️ 不要改回 `content: "↕"` 的字形写法，那会把符号念出来。
+   ⚠️ 也先别改成 `content: "↕" / ""` 的替代文本语法：三引擎实测**都支持**、也都能清掉 ↕，
+     但它要 Chromium 108 / Firefox 128 / Safari 17.4 起才认，更老的引擎会丢掉整条声明
+     ⇒ 箭头彻底消失（支持矩阵里有 Chromium 97，正好在门槛外）。
+     实测矩阵见 docs/A11Y-MANUAL-PROTOCOL.md。 */
 .table__sort::after {
-  content: "↕";                      /* 未排序：上下双向箭头 */
+  content: "";                       /* 空内容 ⇒ 不进可访问名 */
+  inline-size: .85em;
+  block-size: .85em;
+  flex: none;
+  background-color: currentColor;    /* 跟着文字颜色走，暗色自动适配 */
   opacity: .45;
-  font-size: .9em;
+  -webkit-mask: var(--sort-glyph) center / contain no-repeat;
+  mask: var(--sort-glyph) center / contain no-repeat;
+  --sort-glyph: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.4 5.2 4.6h1.7v2.6h2.2V4.6h1.7z'/%3E%3Cpath d='M8 14.6 10.8 11.4h-1.7V8.8H6.9v2.6H5.2z'/%3E%3C/svg%3E");
 }
 
 /* 🔴🔴 排序指示符：三态必须**同时**用形状 + 颜色表达（WCAG 1.4.1）
@@ -95,13 +110,13 @@
      ⇒ 两条选择器并存，任何一种写法都能把箭头点亮。 */
 .table th[aria-sort="ascending"] .table__sort::after,
 .table__sort[aria-sort="ascending"]::after {
-  content: "↑";
+  --sort-glyph: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.6 4.6 6h2.1v8h2.6V6h2.1z'/%3E%3C/svg%3E");
   opacity: 1;
 }
 
 .table th[aria-sort="descending"] .table__sort::after,
 .table__sort[aria-sort="descending"]::after {
-  content: "↓";
+  --sort-glyph: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 14.4 11.4 10h-2.1V2H6.7v8H4.6z'/%3E%3C/svg%3E");
   opacity: 1;
 }