agentcss 0.24.2 → 0.25.0

package/02-primitives/select/select.js

@@ -276,8 +276,26 @@
 
     var options = [].slice.call(list.querySelectorAll('[role="option"]'));
     var isMulti = !!opt.multiple;
-    var selected = opt.value != null ? String(opt.value) : null;
+    /* 🔴 真多值：以前多选也只有一个 `selected` 字符串，而 aria-multiselectable
+       照样写 "true" —— ARIA 在**谎报**能力。现在统一用数组存值，
+       单选只是"长度 0 或 1"的特例，两条路径共用同一份状态。 */
+    var values = [];
     var activeIdx = -1;
+    var destroyed = false;
+
+    function valueOfOpt(o) { return o ? o.getAttribute('data-value') : null; }
+    function hasValue(v) { return v != null && values.indexOf(String(v)) >= 0; }
+    function seed(v) {
+      if (v == null) return;
+      var arr = Object.prototype.toString.call(v) === '[object Array]' ? v : [v];
+      var next = [];
+      for (var i = 0; i < arr.length; i++) {
+        var s = arr[i] == null ? '' : String(arr[i]);
+        if (s && next.indexOf(s) < 0) next.push(s);
+      }
+      values = isMulti ? next : next.slice(0, 1);
+    }
+    seed(opt.value);
 
     list.setAttribute('role', 'listbox');
     if (isMulti) list.setAttribute('aria-multiselectable', 'true');
@@ -317,38 +335,102 @@
 
     function selectedIdx() {
       for (var i = 0; i < options.length; i++) {
-        if (options[i].getAttribute('data-value') === selected) return i;
+        if (hasValue(valueOfOpt(options[i]))) return i;
       }
       return -1;
     }
     function valueText() {
-      var i = selectedIdx();
-      return i < 0 ? (opt.placeholder || '请选择') : optText(options[i]);
+      var texts = [];
+      for (var i = 0; i < options.length; i++) {
+        if (hasValue(valueOfOpt(options[i]))) texts.push(optText(options[i]));
+      }
+      return texts.length ? texts.join('、') : (opt.placeholder || '请选择');
     }
+    /* ⚠️ 空列表也会被调用（初始化 / 清空后重绘）：必须能接住 undefined，
+       老实现直接 o.querySelector 会抛 "Cannot read properties of undefined"。 */
     function optText(o) {
+      if (!o) return '';
       var t = o.querySelector('.select__opt-text');
       return ((t || o).textContent || '').replace(/[✓\s]/g, '').trim();
     }
 
-    function paint() {
-      var v = valueText();
+    /** 对外值：单选给字符串（无值 null），多选给数组副本 */
+    function value() {
+      return isMulti ? values.slice() : (values.length ? values[0] : null);
+    }
+
+    /* 表单承接：作者写了几个 hidden 就复用几个，不够的自动补同 name 的兄弟节点。
+       多选必须"一个值一个 input"，否则提交出去只有最后一个 —— 那是假多选。 */
+    function syncHidden() {
+      var all = [].slice.call(root.querySelectorAll('input[type="hidden"]'));
+      var mine = [];
+      var author = [];
+      all.forEach(function (i) {
+        if (i.getAttribute('data-select-value') === '1') mine.push(i);
+        else author.push(i);
+      });
+      var name = opt.name || root.getAttribute('data-name') ||
+                 (author[0] && author[0].name) || (mine[0] && mine[0].name) ||
+                 root.id || '';   /* 兜底用根元素 id：没有 name 的话多选压根提交不出去 */
+      var slots = author.concat(mine);
+      var want = values.slice();
+      for (var i = 0; i < want.length; i++) {
+        var inp = slots[i];
+        if (!inp) {
+          inp = document.createElement('input');
+          inp.type = 'hidden';
+          inp.setAttribute('data-select-value', '1');
+          root.appendChild(inp);
+          slots.push(inp);
+        }
+        if (name) inp.name = name;
+        else inp.removeAttribute('name');
+        inp.value = want[i];
+      }
+      for (var j = want.length; j < slots.length; j++) {
+        var extra = slots[j];
+        if (extra.getAttribute('data-select-value') === '1') {
+          if (extra.parentNode) extra.parentNode.removeChild(extra);
+        } else {
+          extra.value = '';        /* 作者自己的 input 留着，只是清空 */
+        }
+      }
+    }
+
+    function paint(silent) {
+      var label = valueText();
+      var empty = selectedIdx() < 0;
       var vEl = btn.querySelector('.select__value');
       if (vEl) {
-        vEl.textContent = v;
-        vEl.classList.toggle('select__value--placeholder', selectedIdx() < 0);
+        vEl.textContent = label;
+        vEl.classList.toggle('select__value--placeholder', empty);
       }
+      /* 多选标签会被 CSS 截断：title 里留全量，鼠标悬停能看全 */
+      if (empty) btn.removeAttribute('title');
+      else btn.setAttribute('title', label);
       options.forEach(function (o) {
-        var on = o.getAttribute('data-value') === selected;
+        var on = hasValue(valueOfOpt(o));
         o.setAttribute('aria-selected', on ? 'true' : 'false');
         var ck = o.querySelector('.select__check');
         if (ck) ck.textContent = on ? '✓' : '';
       });
-      /* hidden input 承接表单值（自建组件最容易漏的）*/
-      var hidden = root.querySelector('input[type="hidden"]');
-      if (hidden) hidden.value = selected == null ? '' : selected;
-      flEmit(root, 'fl-change',
-             { value: selected, text: optText(options[selectedIdx()] || options[0]) });
-      if (opt.onChange) opt.onChange(selected, optText(options[selectedIdx()] || options[0]));
+      syncHidden();
+      if (silent) return;
+      flEmit(root, 'fl-change', { value: value(), values: values.slice(), text: label });
+      if (opt.onChange) opt.onChange(value(), label);
+      /* 🔴 原生 change：宿主表单 / 框架（React 受控、form.reset 监听）认的是这个，
+         只发 fl-change 等于"只有本库自己知道值变了"。 */
+      var ev = null;
+      if (typeof window.Event === 'function') {
+        try { ev = new window.Event('change', { bubbles: true }); } catch (e) { ev = null; }
+      }
+      if (!ev) {
+        try {
+          ev = document.createEvent('Event');
+          ev.initEvent('change', true, false);
+        } catch (e2) { ev = null; }
+      }
+      if (ev) root.dispatchEvent(ev);
     }
 
     /**
@@ -428,112 +510,120 @@
     function commit(i) {
       var o = options[i];
       if (!o || o.getAttribute('aria-disabled') === 'true') return;
+      var v = valueOfOpt(o);
       if (isMulti) {
-        /* 多选：再点一次取消 */
-        selected = o.getAttribute('data-value') === selected ? null : o.getAttribute('data-value');
-      } else {
-        selected = o.getAttribute('data-value');
-        close(true);                              /* 选中并关闭 + 归位 */
+        /* 多选：再点一次取消；不关闭列表（APG 多选 listbox 语义） */
+        var k = values.indexOf(v);
+        if (k >= 0) values.splice(k, 1);
+        else values.push(v);
+        paint();
+        return;
       }
+      values = [v];
       paint();
+      close(true);                                /* 选中并关闭 + 归位 */
     }
 
-    /* ---------- 键盘（APG Select）---------- */
-    btn.addEventListener('keydown', function (e) {
+    /* ---------- 键盘（APG Select）----------
+       🔴 只允许**一个** keydown 处理器。
+       以前这里挂了两个：一个是 ↑↓/Enter，一个是 onListKey（↑↓/Home/End/Enter/字符）。
+       同一事件两个监听器都跑 ⇒ 按一次 ↓ 走两格、多选 Enter 选上又取消、
+       关闭态 Enter 打开后立刻被第二个处理器提交关闭。
+       ⚠️ 而旧契约只断言"序列变了"，所以这个 bug 从门禁底下过去了。 */
+    function onBtnKey(e) {
+      if (destroyed) return;
       var k = e.key;
-      if (k === 'ArrowDown' || k === 'ArrowUp' || k === 'Enter' || k === ' ' ||
-          k === 'Spacebar' || (k === 'Alt' && false)) {
-        if (k === 'ArrowDown' || k === 'ArrowUp') {
-          e.preventDefault();
-          if (list.hidden) { open(); return; }
-          var dir = k === 'ArrowDown' ? 1 : -1;
-          setActive(activeIndex() + dir, dir);
+      var opened = !list.hidden;
+
+      if (k === 'ArrowDown' || k === 'ArrowUp' || k === 'Enter' || k === ' ' || k === 'Spacebar') {
+        e.preventDefault();
+        if (!opened) {
+          open();
+          /* APG：↑ 打开时游标落**末项**，↓ 打开落选中项 */
+          if (k === 'ArrowUp' && options.length) setActive(options.length - 1, -1);
           return;
         }
-        e.preventDefault();
-        if (list.hidden) open();
-        else if (activeIdx >= 0) commit(activeIdx);
-        return;
-      }
-      /* Alt+↓ 直接打开（不改值）*/
-      if (k === 'ArrowDown' && e.altKey) { e.preventDefault(); open(); return; }
-      /* Home/End */
-      if (list.hidden && (k === 'Home' || k === 'End')) {
-        e.preventDefault(); open();
-        if (k === 'Home') setActive(0);
-        else setActive(options.length - 1);
+        if (k === 'ArrowDown') { setActive(activeIndex() + 1, 1); return; }
+        if (k === 'ArrowUp') { setActive(activeIndex() - 1, -1); return; }
+        if (activeIdx >= 0) commit(activeIdx);     /* 多选：切一次、不关闭 */
         return;
       }
-    });
-
-    /* 🔴 焦点常驻按钮 ⇒ 键盘事件主要落在 btn 上。
-       这里把 btn 的 handler 也挂一份完整逻辑（Esc/类型搜索/Home/End），
-       否则它们永远收不到事件。 */
-    function onListKey(e) {
-      var k = e.key;
-      if (k === 'ArrowDown') { e.preventDefault(); setActive(activeIndex() + 1, 1); return; }
-      if (k === 'ArrowUp')   { e.preventDefault(); setActive(activeIndex() - 1, -1); return; }
-      if (k === 'Home')      { e.preventDefault(); setActive(0, 1); return; }
-      if (k === 'End')       { e.preventDefault(); setActive(options.length - 1, -1); return; }
-      /* ③ Esc 关闭 + 焦点还按钮
-         🔴 加 stopPropagation（**组合契约**抓到的真问题）：
-         本组件常被放进 drawer / dialog 里。
-         原来只 preventDefault ⇒ 事件**继续冒泡**到外层弹层
-         ⇒ **按一次 Esc 把内外两层一起关掉**。
-         ⚠️ 单组件契约**测不到这个**（它没有外层）——
-            所以必须有"组合契约"这种真嵌套的测试。
-         ⇒ 正解：内层弹层"吃掉"这个键时必须 stopPropagation。
-         层级弹层的 Esc 语义本来就是"只关最上面那层"。 */
-      /* Esc 已由 dismissable 核接管（见上面的 flDismissable）：
-         核把它挂在 btn 上冒泡、并 stopPropagation ⇒ 只关最内层，
-         组件里不再各写一份（原先手写 10 处、分布 7 个文件）。 */
-      if (k === 'Tab') { close(false); return; }
-      if (k === 'Enter' || k === ' ' || k === 'Spacebar') {
+      if (k === 'Home' || k === 'End') {
         e.preventDefault();
-        if (activeIdx >= 0) commit(activeIdx);
+        if (!opened) open();
+        if (options.length) setActive(k === 'Home' ? 0 : options.length - 1, k === 'Home' ? 1 : -1);
         return;
       }
-      /* ④ 类型搜索 —— 已移到 typeahead 核（见上面的 flTypeahead）。
-         ⚠️ 核不监听键盘：Enter / Space / Tab 在本组件各有语义，
-            只有"单个可打印字符"才算打字。 */
-      if (k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+      if (k === 'Tab') { if (opened) close(false); return; }
+
+      /* 单个可打印字符 = 类型搜索（Enter/Space/Tab 各有语义，不能算打字） */
+      if (k && k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        if (!opened) open();                       /* 关闭态打字：先开再定位 */
         e.preventDefault();
         typeahead.type(k);
       }
+      /* Esc 由 dismissable 核接管（挂在 btn 上、且 stopPropagation）：
+         只关最内层，组件里不再写第二份。 */
     }
-    /* 挂在按钮上（焦点常驻处）*/
-    btn.addEventListener('keydown', function (e) {
-      /* 列表没开时，btn 自己的 handler 已经处理了开合；开了之后交给 onListKey */
-      if (list.hidden) return;
-      var k = e.key;
-      /* 这些键在"已打开"状态下由 onListKey 统一处理 */
-      if (k === 'Escape' || k === 'Esc' || k === 'ArrowDown' || k === 'ArrowUp' ||
-          k === 'Home' || k === 'End' || k === 'Enter' || k === ' ' ||
-          k === 'Spacebar' || k === 'Tab') {
-        /* Enter/Space 在关闭态要"打开"，交给 btn 原 handler */
-        if (list.hidden) return;
-        onListKey(e);
-        return;
-      }
-      if (k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) onListKey(e);
-    });
+    btn.addEventListener('keydown', onBtnKey);
 
     /* ---------- 点击 ---------- */
-    btn.addEventListener('click', function () {
+    function onBtnClick() {
+      if (destroyed) return;
       if (list.hidden) open(); else close();
-    });
-    list.addEventListener('click', function (e) {
+    }
+    function onListClick(e) {
+      if (destroyed) return;
       var o = e.target.closest ? closest(e.target, '[role="option"]') : null;
       if (!o) return;
       commit(options.indexOf(o));
-    });
+    }
+    btn.addEventListener('click', onBtnClick);
+    list.addEventListener('click', onListClick);
+
+    /* 🔴 表单 reset：hidden input 会被浏览器清空，而组件内部状态不会跟着变
+       ⇒ 重置后 UI 还显示旧值，提交却是空的。监听 form 的 reset，
+       等浏览器把 DOM 重置完（下一个宏任务）再把状态改回初始值。 */
+    var initialValues = values.slice();
+    var form = closest(root, 'form');   /* 用模块内兜底，别直接调 Element.closest（老 WebView 没有） */
+    function onFormReset() {
+      setTimeout(function () {
+        if (destroyed) return;
+        values = initialValues.slice();
+        paint();
+      }, 0);
+    }
+    if (form) form.addEventListener('reset', onFormReset);
     /* 点外部关闭已由 dismissable 核接管（document 捕获阶段判定）。 */
 
-    paint();
+    /* 初始化重绘不派发 change：原生 select 也不会在挂载时发一次 */
+    paint(true);
+
     return {
       open: open, close: close,
-      get value() { return selected; },
-      set value(v) { selected = v == null ? null : String(v); paint(); },
+      get value() { return value(); },
+      set value(v) { seed(v); paint(); },
+      get values() { return values.slice(); },
+      set values(v) { seed(v); paint(); },
+      /* 🔴 对外必须能销毁：动态移除组件时，document 上的 dismissable 监听、
+         typeahead 缓冲、btn 上的 keydown 都要摘掉，否则越挂越多。 */
+      destroy: function () {
+        if (destroyed) return;
+        destroyed = true;
+        btn.removeEventListener('keydown', onBtnKey);
+        btn.removeEventListener('click', onBtnClick);
+        list.removeEventListener('click', onListClick);
+        if (form) form.removeEventListener('reset', onFormReset);
+        dismiss.destroy();
+        typeahead.destroy();
+        fr.clear();
+        list.hidden = true;
+        btn.setAttribute('aria-expanded', 'false');
+        btn.removeAttribute('aria-activedescendant');
+        /* 只删我们自己补出来的 hidden（作者写的那几个不动） */
+        [].slice.call(root.querySelectorAll('input[type="hidden"][data-select-value="1"]'))
+          .forEach(function (i) { if (i.parentNode) i.parentNode.removeChild(i); });
+      },
     };
   }
 

package/02-primitives/timeline/demo.html

@@ -118,8 +118,8 @@
   </div>
   <p class="cmp__why">
     两栏的字形数差 1 —— 那 1 个就是圆点。这不是洁癖：
-    <strong>伪元素里的字符会参与可访问名计算</strong>（本库 `internal/ERRORS.md` E189 记过，
-    侧栏当时被念成“圆点 总览”）。要画形状就用盒子，不要用字。
+    <strong>伪元素里的字符会参与可访问名计算</strong>（实测：侧栏被读屏念成
+    “圆点 总览”）。要画形状就用盒子，不要用字。
   </p>
 
   <h2 class="rule-top">什么时候不该用它</h2>

package/02-primitives/timeline/timeline.css

@@ -37,7 +37,7 @@
    ----------------------------------------------------------------------------
    同一个道理：颜色在强制色里会消失。这里用**圆点更大 + 标题更重**，
    两条都是非颜色线索，且都不依赖 `::before` 里的字符
-   （`content: "●"` 会被算进可访问名，读屏念「圆点 …」，见 internal/ERRORS.md E189）。
+   （`content: "●"` 会被算进可访问名，读屏念「圆点 …」—— 实测过）。
    ========================================================================= */
 
 .timeline {

package/03-patterns/accordion/README.md

@@ -38,6 +38,21 @@
 | `.accordion__heading` | heading 包装（真实 `<h2>`–`<h6>`）|
 | `.accordion__trigger` | 原生 `<button>` |
 | `.accordion__panel` | 内容区 |
+| `.accordion__hint` | 标题下方的补充说明（`--fs-xs` + `--text-secondary`，`display:block`）。放"展开后有什么"这类预期，能显著减少无谓展开 |
+| `.accordion--flush` | 去掉外框与背景，融进已有卡片 / 侧栏里（`border:0; background:transparent`） |
+| `.accordion__panel-inner.cols-auto` | 面板内容按内容宽度自动分列（`auto-fit` + `minmax(200px,1fr)`），窄了自动塌成一列 |
+| `.accordion__panel-inner.cols-2` / `.cols-3` | 固定两列 / 三列；**≥720px 才分列**，窄屏塌成一列 |
+| `.acc-table` | 面板里的表格：`width:100%` + `border-collapse`，**窄屏横向滚动而不挤压换行**（表格一旦换行，列头和数据就对不上） |
+
+`cols-*` 加在 `.accordion__panel-inner` 上，不是加在 `.accordion__panel` 上：
+
+```html
+<div class="accordion__panel">
+  <div class="accordion__panel-inner cols-2">
+    <p>左栏</p><p>右栏</p>
+  </div>
+</div>
+```
 
 ## 两种模式
 

package/03-patterns/content/README.md

@@ -25,6 +25,17 @@
 .prose > table { ... }
 ```
 
+**唯一的例外是 `.task-list-item`。** 它不是我们发明的：GFM 的任务列表会把
+`<li>` 渲染成 `<li class="task-list-item"><input type="checkbox" disabled>`，
+类名由渲染器给出，我们只能去接。所以 `content.css` 里只有它是类选择器：
+
+| 类 | 谁来加 | 我们做什么 |
+|---|---|---|
+| `.task-list-item` | markdown 渲染器（GFM 任务列表） | 去掉原生项目符号（`list-style:none`）、把复选框从缩进里拉回来（`margin-inline-start:-1.5em`）；`disabled` 的复选框用 `accent-color` 表达状态，**不用 opacity**（灰到看不清等于没表达） |
+
+⚠️ 只有 `.prose .task-list-item` 生效——任务列表必须出现在文章正文里，
+裸的 `<ul>` 不接管。
+
 结果：**从任何 CommonMark 兼容渲染器拿到的 HTML，不需要任何后处理就能正确显示。**
 
 唯一的自定义类名是 `.prose`——它不改变语义，只是"这块是正文"的标记。

package/03-patterns/drawer/README.md

@@ -40,7 +40,7 @@
 
 | 部件 | 说明 |
 |---|---|
-| `--right`（默认）/ `--left` / `--top` / `--bottom` | 四个进入方向 |
+| `.drawer--right`（默认）/ `.drawer--left` / `.drawer--top` / `.drawer--bottom` | 四个进入方向。左右是侧栏（宽度由 `--drawer-w` 定），上下是**抽屉式面板**（`min(60vh, 420px)` 高、整宽），适合移动端底部操作区 |
 | `.drawer__head` / `__title` / `__close` | 头部与关闭按钮 |
 | `.drawer__body` | 内容 |
 | `.drawer__foot` | 底部操作区 |

package/03-patterns/dropdown/demo.html

@@ -26,7 +26,7 @@
   border: 1px solid var(--border-decor);
   border-radius: var(--r-sm);
 }
-/* 反例专用：24px 一行（本库把它量出来过，见 dropdown.css 的复盘） */
+/* 反例专用：24px 一行（本库把它量出来过，见 dropdown.css 的实测记录） */
 .dd-bug {
   display: flex; align-items: center;
   height: 24px; padding: 0 var(--sp-3);

package/03-patterns/form-validation/README.md

@@ -117,6 +117,24 @@ e.textContent = v === '' ? '金额不能为空' : '最多两位小数，例如 1
 4. 字段加 `aria-invalid="true"`
 5. **异步校验时不要禁用输入框** —— 用户会以为不能打字了。保持可输入，旁边给小提示
 
+### 异步校验的 pending 态两个类
+
+| 类 | 加在哪 | 作用 |
+|---|---|---|
+| `.field--checking` | `.field` 上 | 标记"这一格正在校验"。目前只作状态标记（并占住 `::after`，防止有人改用 padding 挤位置） |
+| `.field__checking-hint` | `.field` 里、输入框后 | 显示一个小转圈 + 文字（"正在检查用户名…"）。转圈用 `::before` 画，配色走 `--accent` / `--border-control` |
+
+```html
+<div class="field field--checking">
+  <label class="field__label" for="u">用户名</label>
+  <input class="field__input" id="u" aria-describedby="u-check">
+  <span class="field__checking-hint" id="u-check">正在检查是否可用…</span>
+</div>
+```
+
+⚠️ 校验结束要把 `.field--checking` 摘掉、把 hint 换成错误或成功提示 ——
+**留着不摘，用户会以为一直在转圈**，这比不显示更糟。
+
 ---
 
 ## 反例

package/03-patterns/form-validation/form-validation.css

@@ -142,7 +142,18 @@
       "脏"是**正交标记**（一个字段可以同时是 dirty 且 state=invalid）。
       塞进同一个属性 ⇒ 两个维度互斥，表达不了组合。
    ------------------------------------------------------------------------ */
-.field__error { display: none; }
+/* 🔴 这里必须是 `.field .field__error`（两段），不能只写 `.field__error`。
+   原因：`02-primitives/input/input.css` 给 `.field__error` 定了**外观**
+   （`display:flex` + 图标 + 危险色），本文件给它定**可见性**（默认藏起来）。
+   两条同特异性（0,1,0）⇒ 谁后加载谁赢。实测：
+
+     input.css 先、本文件后 → display:none  ✅ 校验前不报红
+     本文件先、input.css 后 → display:flex  🔴 首屏把全部错误都挂出来
+
+   也就是说"错误提示该不该显示"取决于打包器的 CSS 顺序 —— 用户永远不会想到
+   去查这个。加一层 `.field` 把特异性抬到 (0,2,0)，顺序就不再是变量。
+   代价：错误元素必须在 `.field` 内（本库的结构契约就是这么定的）。 */
+.field .field__error { display: none; }
 .field[data-dirty] .field__error { display: flex; }
 
 /* 错误汇总展开时，全部错误强制显示，不管字段脏不脏 —— 那是用户主动要看清单。

package/03-patterns/list/README.md

@@ -120,6 +120,17 @@ CSS 里另外关掉 hover 等微交互过渡——那是**不同层次**，别
 
 触屏**没有 hover**，操作会彻底消失。
 
+### `.list__note`：列表末尾的一行小字
+
+`--fs-xs` + `--text-tertiary`，左右内边距与行对齐（`--sp-2 --sp-4`）。
+放"共 128 条，按更新时间排序"这类**关于这个列表本身**的说明 ——
+不要拿它当空状态用（空状态用 `states` 的 `.state--empty`）。
+
+```html
+<ul class="list">…</ul>
+<p class="list__note">共 128 条，按更新时间排序</p>
+```
+
 ---
 
 ## 反模式

package/03-patterns/overlay/README.md

@@ -15,13 +15,18 @@
 
 | 类 | 作用 |
 |---|---|
-| `.overlay` | 遮罩层（`role="dialog"` 的宿主） |
+| `.dialog-backdrop` | 遮罩层（`position: fixed` 铺满视口，`role="dialog"` 的宿主） |
 | `.dialog` | 弹窗面板 |
-| `.dialog__title` / `__body` / `__actions` | 弹窗内部结构 |
-| `.toast-region` | 通知容器（`role="status" aria-live="polite"`）|
+| `.dialog__title` / `__desc` / `__actions` | 弹窗内部结构 |
+| `.toast-region` | 通知容器（`role="status"` `aria-live="polite"`）|
 | `.toast` | 单条通知 |
-| `.toast__icon` / `__body` | 通知内部结构 |
-| `.toast--success` / `--error` / `--warning` | 三种变体（**靠底色 + 图标双编码**，不只靠颜色）|
+| `.toast__title` / `__desc` / `__body` | 通知内部结构 |
+| `.toast--success` / `.toast--error` / `.toast--warning` | 三种变体（**靠底色 + 图标双编码**，不只靠颜色）|
+
+⚠️ **这张表曾经有三行是假的**（2026-11-02 修）：`.overlay` 这个类全库
+没有任何 CSS 定义（真实的遮罩叫 `.dialog-backdrop`）、`.toast__icon` 与
+`.dialog__body` 同样不存在。它们是从早期版本抄下来的名字 ——
+照着写的人会得到"样式没生效，但也不报错"。
 
 ⚠️ **三种 toast 变体在本 demo 里没有演示** ——
 它们是给复用者的钩子，样式已备好，需要你自己触发。
@@ -57,9 +62,24 @@ Tab 在弹层内循环，**绝不跑到背后的页面去**。
 **并加一层保险**：支持 `inert` 的浏览器上，把背景节点整体 `inert = true`——
 比 focus trap 更彻底（鼠标点击也失效）。不支持就靠 focus trap 兜。
 
+#### 背景隔离的三条硬要求（外部审计后补的）
+
+| 要求 | 为什么 |
+|---|---|
+| **记原值再还原** | 页面可能本来就把某块设为 `inert`（另一个弹层、宿主锁屏）。关闭时固定写 `false` 会把它**误解锁** |
+| **嵌套时隔离下层弹层** | 以前把所有 `.dialog-backdrop` 一律跳过，导致开 A 再开 B 时，**两个 dialog 同时暴露给读屏**。只该跳过自己这一层 |
+| **打开期间新增的节点也要隔离** | 快照只拍一次是不够的：toast、埋点 iframe、框架 portal 在弹层开着时插进 `body`，不在快照里就漏网 ⇒ 用 `MutationObserver` 盯 `body` 的直接子节点 |
+
+⚠️ 观察器必须**能自愈**：如果这一层的 backdrop 被外部直接摘掉（框架卸载、
+测试清理），`close()` 永远不会跑 ⇒ 幽灵观察器会把之后插入的每个节点都设成
+`inert` 且无人释放。症状是"之后任何 dialog 都抢不回焦点"。所以回调里先检查
+自己是否还在文档里，不在就地回收。
+
 ### 2. 焦点归还
 
-**关闭后焦点必须回到触发它的那个元素。**
+**关闭后焦点必须回到触发它的那个元素 —— 但只在"焦点还是我的"时候。**
+先算 `focusIsMine`（焦点在弹层内 / 在 backdrop 上 / 已经掉到 body），
+不是我的就**不要抢**：先关外层时，内层正拿着焦点。
 不还的话焦点掉到 `<body>`，键盘用户要重新 Tab 一遍才能回到原处。
 
 触发元素可能已被移除（用户点了别处），所以要有 fallback。

package/03-patterns/overlay/overlay.css

@@ -54,7 +54,7 @@
   box-shadow: var(--shadow-2);
 
   /* 🔴 去掉 `border-left: 3px solid`。
-     评审意见左侧竖条"很蠢"——它是纯装饰：3px 竖条在浅底上形成一条硬边，
+     左侧竖条是纯装饰：3px 竖条在浅底上形成一条硬边，
      视觉噪声大于信息量。已从全库去掉，**这里漏了**（典型的"只改一半"）。
 
      WCAG 1.4.1（不能只靠颜色）**不依赖竖条**：图标 + 文字本身就够了
@@ -194,8 +194,7 @@
 
 /* 动作区：按钮**右对齐且相邻**。
    🔴 去掉 space-between + margin-right:auto。
-      原来让破坏性按钮靠左、取消靠右，中间空一大片 ——
-      评审意见「删除和取消放到中间来」，看着别扭。
+      原来让破坏性按钮靠左、取消靠右，中间空一大片 —— 看着别扭。
       常规做法（Linear / Vercel / GitHub 都这样）：两个按钮挨着，一起靠右。
       次要的在左（取消），主要的在右（删除）。 */
 .dialog__actions {
@@ -283,6 +282,26 @@ body[data-scroll-locked] { overflow: hidden; }
   .toast__timer { animation: none; width: 100%; }   /* 进度条停住，不假装还在倒计时 */
 }
 
+/* ============================================================================
+   @media print —— 模态在纸上
+   =========================================================================
+   🔴 遮罩**不隐藏**，拉回正常流：`.dialog` 是 `.dialog-backdrop` 的子节点，
+      隐藏遮罩会把弹窗里的字一起吞掉（静默截断）。实测：屏幕开着 dialog 时
+      打印，遮罩是 `position: fixed; inset: 0; rgba(21,24,28,.4)`，整页 40% 黑。
+   ⚠️ 必须写在这个文件里：写进 tokens.css 会被这里同特异性的 `position: fixed`
+      盖掉 —— 规则写了、不生效、不报错（E254；由 print-policy-gate L3 抓到）。
+   ========================================================================= */
+@media print {
+  .dialog-backdrop {
+    position: static;
+    inset: auto;
+    display: block;
+    padding: 0;
+    background: none;
+  }
+  .dialog { max-height: none; overflow: visible; }
+}
+
 /* ============================================================================
    反模式
    =========================================================================