agentcss 0.25.5 → 0.26.0

package/01-tokens/behavior/labels.js

@@ -0,0 +1,44 @@
+/**
+ * labels.js — 「文案覆盖合并」工具核
+ *
+ * ==========================================================================
+ * 🔴 为什么要有这个核
+ * --------------------------------------------------------------------------
+ *   0.26.0 给组件加 `labels`（读屏 / 可见文案覆盖）时，最初的写法是
+ *   在 9 个组件里各贴一份合并函数：
+ *
+ *       for (k in defaults) { out[k] = src[k] == null ? defaults[k] : src[k]; }
+ *
+ *   九份一模一样的循环，只差 `defaults` 的字面量。这与 I-14 是同一条病：
+ *   **同一份逻辑写 N 份**。后果不是"难看"，是**修正只到一处**：
+ *     · 以后要支持"传 null 表示删掉这条文案"→ 改 1 处、漏 8 处；
+ *     · 要支持嵌套命名空间 → 同上；
+ *     · 某处写成 `src[k] || defaults[k]`，空字符串就再也覆盖不掉 ——
+ *       而这种偏差在 9 份副本里肉眼几乎看不出来。
+ *
+ *   ⇒ 真值源一份（本文件），生成进使用点，`gen-behavior --check` 证明跟随。
+ *      使用点仍然**各自保留自己的 `defaults` 字面量** —— 那是组件的事实，
+ *      不是可以共享的代码。
+ *
+ * ==========================================================================
+ * 语义（三句话，必须与实现逐字对应）
+ * --------------------------------------------------------------------------
+ *   ① `undefined` / `null` ⇒ 用默认值（"没传"和"显式取消"等价）；
+ *   ② 其他任何值（含 `''`、`0`、`false`）⇒ **原样采用** ——
+ *      用 `||` 判断会把空字符串吞掉，那是错误的；
+ *   ③ 只认 `defaults` 里有的键 —— 拼错的键不会悄悄生效（避免"传了却没反应"）。
+ * ==========================================================================
+ */
+/* ==== BEHAVIOR CORE BEGIN: labels ==== */
+var flLabels = function (defaults, src) {
+  src = src || {};
+  var out = {};
+  var k;
+  for (k in defaults) {
+    if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+      out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+    }
+  }
+  return out;
+};
+/* ==== BEHAVIOR CORE END: labels ==== */

package/02-primitives/combobox/combobox.js

@@ -145,6 +145,29 @@
   var uid = 0;
 
   function create(root, opt) {
+    /* 读屏文案默认值（F2 / 0.26.0）。不传 `labels` 时输出逐字不变。 */
+    var DEFAULT_LABELS = {
+      suggest: '建议',
+      input: '输入',
+      noMatch: function (q) { return '没有匹配「' + q + '」的选项'; },
+      empty: '暂无可选'
+    };
+
+    /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+    var flLabels = function (defaults, src) {
+      src = src || {};
+      var out = {};
+      var k;
+      for (k in defaults) {
+        if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+          out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+        }
+      }
+      return out;
+    };
+    /* ==== BEHAVIOR INJECT END: labels ==== */
+  var L = flLabels(DEFAULT_LABELS, opt && opt.labels);
+
     opt = opt || {};
     var input = root.querySelector('[data-combo-input]');
     var list = root.querySelector('[data-combo-list]');
@@ -182,14 +205,14 @@
     var shown = [];                           /* 当前过滤后的选项 */
 
     list.setAttribute('role', 'listbox');
-    list.setAttribute('aria-label', opt.label || '建议');
+    list.setAttribute('aria-label', opt.label || L.suggest);
     input.setAttribute('role', 'combobox');
     input.setAttribute('aria-autocomplete', 'list');
     input.setAttribute('aria-expanded', 'false');
     input.setAttribute('aria-controls', list.id);
     if (!input.id) input.id = 'combo-input-' + seq;
     if (!input.getAttribute('aria-label') && !root.querySelector('label[for="' + input.id + '"]')) {
-      input.setAttribute('aria-label', opt.label || '输入');
+      input.setAttribute('aria-label', opt.label || L.input);
     }
 
     /* ---------- 过滤（含高亮命中片段）---------- */
@@ -226,7 +249,7 @@
       if (!shown.length) {
         /* @html-sink escaped — 插值只有 q，且过了 esc() */
         list.innerHTML = '<li class="combo__empty" role="presentation">' +
-          (q ? '没有匹配「' + esc(q) + '」的选项' : '暂无可选') + '</li>';
+          (q ? L.noMatch(esc(q)) : L.empty) + '</li>';
         return;
       }
       var ql = q.toLowerCase();

package/02-primitives/date-range/date-range.js

@@ -119,6 +119,28 @@
   }
 
   function create(root, opt) {
+    /* 校验文案默认值（F2 / 0.26.0）。不传 `labels` 时输出逐字不变。 */
+    /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+    var flLabels = function (defaults, src) {
+      src = src || {};
+      var out = {};
+      var k;
+      for (k in defaults) {
+        if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+          out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+        }
+      }
+      return out;
+    };
+    /* ==== BEHAVIOR INJECT END: labels ==== */
+    var DEFAULT_LABELS = {
+        requiredEnd: '请填写结束日期。',
+        requiredStart: '请填写开始日期。',
+        order: function (f, t) { return '开始日期不能晚于结束日期（当前：' + f + ' → ' + t + '）。'; },
+        min: function (min) { return '开始日期不能早于 ' + min + '。'; },
+        max: function (max) { return '结束日期不能晚于 ' + max + '。'; }
+    };
+    var L = flLabels(DEFAULT_LABELS, opt && opt.labels);
     opt = opt || {};
     var from = root.querySelector('[data-dr-from]');
     var to = root.querySelector('[data-dr-to]');
@@ -158,14 +180,14 @@
     function validate() {
       var f = from.value, t = to.value;
       if (!f && !t) { setError(''); paintSummary(''); return true; }
-      if (f && !t) { setError('请填写结束日期。'); return false; }
-      if (!f && t) { setError('请填写开始日期。'); return false; }
+      if (f && !t) { setError(L.requiredEnd); return false; }
+      if (!f && t) { setError(L.requiredStart); return false; }
       if (f > t) {
-        setError('开始日期不能晚于结束日期（当前：' + f + ' → ' + t + '）。');
+        setError(L.order(f, t));
         return false;
       }
-      if (opt.min && f < opt.min) { setError('开始日期不能早于 ' + opt.min + '。'); return false; }
-      if (opt.max && t > opt.max) { setError('结束日期不能晚于 ' + opt.max + '。'); return false; }
+      if (opt.min && f < opt.min) { setError(L.min(opt.min)); return false; }
+      if (opt.max && t > opt.max) { setError(L.max(opt.max)); return false; }
       setError('');
       paintSummary(f + ' → ' + t + '（' + days(f, t) + ' 天）');
       return true;

package/02-primitives/popover/popover.js

@@ -181,11 +181,12 @@
        （加了就是模态，语义就错了）。 */
     box.setAttribute('role', 'dialog');
     box.setAttribute('aria-label', opts.label || '');
+    var bodyHtml = sanitizeHtml(opts.html || '', opts.sanitize);
     /* @html-sink raw-html — `opts.html` 是有意的 HTML 入口，调用方负责净化；
-       登记在 SECURITY.md「HTML 入口（sink）」。 */
+       登记在 SECURITY.md「HTML 入口（sink）」。`sanitize` / `setSanitizer` 可挂钩。 */
     box.innerHTML =
       '<span class="popover__arrow" aria-hidden="true"></span>' +
-      '<div class="popover__body">' + (opts.html || '') + '</div>';
+      '<div class="popover__body">' + bodyHtml + '</div>';
 
     /* 箭头要指向触发元素的中心，而不是浮层的中心 */
     positionArrow(box, trigger);
@@ -294,6 +295,24 @@
     return api;
   }
 
+  /* HTML 净化钩子（F6 / 0.26.0）。
+     🔴 默认**不改变任何行为**：没传 `sanitize` 也没有 `setSanitizer()` 时，
+        `opts.html` 仍然按"调用方已净化"处理（与 0.25.x 一致）。
+     ⇒ 想接入 DOMPurify 这类库：
+          Popover.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+        或逐次传 `opts.sanitize` 覆盖（逐次优先于模块级）。
+     ⚠️ 钩子只处理**字符串入口**；传 Node 的入口本来就绕过了 HTML 解析。 */
+  var SANITIZER = null;
+
+  function setSanitizer(fn) {
+    SANITIZER = (typeof fn === 'function') ? fn : null;
+  }
+
+  function sanitizeHtml(html, perCall) {
+    var fn = (typeof perCall === 'function') ? perCall : SANITIZER;
+    return fn ? String(fn(String(html))) : String(html);
+  }
+
   /* 箭头对准触发元素中心（浮层可能比触发元素宽） */
   function positionArrow(box, trigger) {
     var arrow = box.querySelector('.popover__arrow');
@@ -321,5 +340,6 @@
     get current() { return current; },
   };
 
+  Popover.setSanitizer = setSanitizer;
   global.Popover = Popover;
 })(typeof window !== 'undefined' ? window : globalThis);

package/02-primitives/select/select.js

@@ -246,6 +246,27 @@
   var uid = 0;
 
   function create(root, opt) {
+    /* 读屏文案默认值（F2 / 0.26.0）。不传 `labels` 时输出逐字不变。 */
+    var DEFAULT_LABELS = {
+      option: '选项',
+      placeholder: '请选择'
+    };
+
+    /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+    var flLabels = function (defaults, src) {
+      src = src || {};
+      var out = {};
+      var k;
+      for (k in defaults) {
+        if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+          out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+        }
+      }
+      return out;
+    };
+    /* ==== BEHAVIOR INJECT END: labels ==== */
+  var L = flLabels(DEFAULT_LABELS, opt && opt.labels);
+
     opt = opt || {};
     var btn = root.querySelector('[data-select-btn]');
     var list = root.querySelector('[data-select-list]');
@@ -299,7 +320,7 @@
 
     list.setAttribute('role', 'listbox');
     if (isMulti) list.setAttribute('aria-multiselectable', 'true');
-    list.setAttribute('aria-label', opt.label || '选项');
+    list.setAttribute('aria-label', opt.label || L.option);
     btn.setAttribute('aria-haspopup', 'listbox');
     btn.setAttribute('aria-expanded', 'false');
     btn.setAttribute('aria-controls', list.id);
@@ -344,7 +365,7 @@
       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 || '请选择');
+      return texts.length ? texts.join('、') : (opt.placeholder || L.placeholder);
     }
     /* ⚠️ 空列表也会被调用（初始化 / 清空后重绘）：必须能接住 undefined，
        老实现直接 o.querySelector 会抛 "Cannot read properties of undefined"。 */

package/02-primitives/upload/upload.js

@@ -80,8 +80,42 @@
     remove: 'M4.2 4.2l7.6 7.6M11.8 4.2l-7.6 7.6'
   };
 
-  var STATE_TEXT = { pending: '待上传', done: '已完成', error: '失败' };
+  /* 读屏 / 状态文案默认值（F2 / 0.26.0）。
+     值可以是字符串或函数；不传 `labels` 时输出与之前逐字相同。 */
+  var DEFAULT_LABELS = {
+    pending: '待上传',
+    done: '已完成',
+    error: '失败',
+    remove: function (name) { return '移除 ' + name; },
+    uploading: function (pct) { return '上传中 ' + Math.round(pct) + '%'; },
+    countMax: function (n) { return '最多 ' + n + ' 个文件'; },
+    sizeMax: function (limit) { return '超过 ' + limit; },
+    type: '类型不支持',
+    folder: '请拖入文件，不支持文件夹',
+    none: function (reason) { return reason ? '未添加任何文件：' + reason : '未添加任何文件'; },
+    noDrop: '当前浏览器不支持拖放，请点「选择文件」',
+    noDropShort: '当前浏览器不支持拖放，请点选择文件',
+    summary: function (added, total, rejected) {
+      var s = '已添加 ' + added + ' 个文件，共 ' + total + ' 个';
+      if (rejected) s += '；' + rejected + ' 个未通过校验';
+      return s;
+    },
+    removed: function (name, rest) { return '已移除 ' + name + '，还剩 ' + rest + ' 个'; }
+  };
 
+  /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+  var flLabels = function (defaults, src) {
+    src = src || {};
+    var out = {};
+    var k;
+    for (k in defaults) {
+      if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+        out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+      }
+    }
+    return out;
+  };
+  /* ==== BEHAVIOR INJECT END: labels ==== */
   /* ---------------------------------------------------------------- 工具 */
 
   /**
@@ -183,6 +217,7 @@
     var opt = opts || {};
 
     this.root = root;
+    this.labels = flLabels(DEFAULT_LABELS, opt && opt.labels);
     this.input = root.querySelector('.upload__input');
     this.list = root.querySelector('.upload__list');
     this.status = root.querySelector('.upload__status');
@@ -299,15 +334,15 @@
       for (var i = 0; i < incoming.length; i++) {
         var f = incoming[i];
         if (maxFiles && keep.length >= maxFiles) {
-          rejected.push({ file: f, reason: 'count', text: '最多 ' + maxFiles + ' 个文件' });
+          rejected.push({ file: f, reason: 'count', text: this.labels.countMax(maxFiles) });
           continue;
         }
         if (this.maxSize && f.size > this.maxSize) {
-          rejected.push({ file: f, reason: 'size', text: '超过 ' + humanSize(this.maxSize) });
+          rejected.push({ file: f, reason: 'size', text: this.labels.sizeMax(humanSize(this.maxSize)) });
           continue;
         }
         if (!matchesAccept(f, accept)) {
-          rejected.push({ file: f, reason: 'type', text: '类型不支持' });
+          rejected.push({ file: f, reason: 'type', text: this.labels.type });
           continue;
         }
         keep.push(f);
@@ -336,7 +371,7 @@
       if (dirCount) {
         r.rejected.push({
           file: { name: dirCount + ' 个文件夹', size: 0 },
-          reason: 'dir', text: '请拖入文件，不支持文件夹'
+          reason: 'dir', text: this.labels.folder
         });
       }
 
@@ -344,7 +379,7 @@
         /* 一个都没收：仍要把拒收项画出来，否则用户"拖了没反应" */
         this.rejected = r.rejected;
         this.render();
-        this.announce(r.rejected.length ? '未添加任何文件：' + r.rejected[0].text : '未添加任何文件');
+        this.announce(this.labels.none(r.rejected.length ? r.rejected[0].text : ''));
         flEmit(this.root, 'fl-upload', {
           files: currentFiles(this.input), added: 0, rejected: r.rejected
         });
@@ -354,9 +389,9 @@
       if (!writeFiles(this.input, r.keep)) {
         /* 见文件头：宁可明说不可用，也不能装作收下了 */
         this.rejected = [{ file: r.keep[0], reason: 'unsupported',
-          text: '当前浏览器不支持拖放，请点「选择文件」' }];
+          text: this.labels.noDrop }];
         this.render();
-        this.announce('当前浏览器不支持拖放，请点选择文件');
+        this.announce(this.labels.noDropShort);
         return false;
       }
 
@@ -441,7 +476,7 @@
       /* 状态词给读屏（图标是 aria-hidden）—— 也是色盲用户的第二条线索 */
       var sr = document.createElement('span');
       sr.className = 'upload__status';
-      sr.textContent = STATE_TEXT[state] || '';
+      sr.textContent = this.labels[state] || '';
       mark.appendChild(sr);
 
       var name = document.createElement('span');
@@ -477,12 +512,12 @@
         var rm = document.createElement('button');
         rm.className = 'upload__remove';
         rm.type = 'button';
-        rm.setAttribute('aria-label', '移除 ' + (file.name || ''));
+        rm.setAttribute('aria-label', this.labels.remove(file.name || ''));
         rm.appendChild(iconEl('remove'));
         rm.addEventListener('click', function () { self.removeAt(index); });
         li.appendChild(rm);
 
-        if (pct != null && pct >= 0) meta.textContent = '上传中 ' + Math.round(pct) + '%';
+        if (pct != null && pct >= 0) meta.textContent = self.labels.uploading(pct);
       }
 
       return li;
@@ -536,7 +571,7 @@
           mark.appendChild(iconEl('done'));
           var sr = document.createElement('span');
           sr.className = 'upload__status';
-          sr.textContent = STATE_TEXT.done;
+          sr.textContent = this.labels.done;
           mark.appendChild(sr);
         }
         if (meta && f) meta.textContent = humanSize(f.size);
@@ -557,7 +592,7 @@
       }
       this.paintProgress(bar, pct);
       /* 进度也写成文本：**信息不能只在图形里**，否则强制色/色盲下丢失 */
-      if (meta) meta.textContent = '上传中 ' + Math.round(pct) + '%';
+      if (meta) meta.textContent = this.labels.uploading(pct);
     },
 
     /* ================================================================ 移除 */
@@ -579,7 +614,7 @@
 
       this.rebind();      /* 索引整体前移，旧闭包里的 i 已过期 */
       this.syncCount();
-      this.announce('已移除 ' + (removed.name || '文件') + '，还剩 ' + rest.length + ' 个');
+      this.announce(this.labels.removed(removed.name || '文件', rest.length));
       flEmit(this.root, 'fl-upload', {
         files: rest, added: 0, removed: removed, rejected: []
       });
@@ -620,9 +655,7 @@
 
     summary: function (added, rejected) {
       var total = currentFiles(this.input).length;
-      var s = '已添加 ' + added + ' 个文件，共 ' + total + ' 个';
-      if (rejected) s += '；' + rejected + ' 个未通过校验';
-      return s;
+      return this.labels.summary(added, total, rejected);
     },
 
     /* ================================================================ 销毁 */

package/03-patterns/content/content.css

@@ -180,7 +180,19 @@
   height: 0;                /* 🔴 hr 默认有 inset 边框，必须清掉 */
 }
 
-.prose > img {
+/* 🔴 必须是**后代**选择器，不是 `> img` —— 和下面 `.prose a` 同一条教训。
+ *
+ *   Markdown / CommonMark 渲染图片出来是 `<p><img></p>`，图片的父节点是 `<p>`，
+ *   不是 `.prose` 的直接子代 ⇒ `> img` **一条都匹配不上**，
+ *   于是 `max-width:100%` 从未生效。
+ *   实测（外部审计 F1）：`04-recipes/longform/content.html` 里
+ *   `<p><img width="600">`，375px 溢出 246px、320px 溢出 301px。
+ *   对"给用户和 AI 照抄的配方页"来说，这个缺陷会被原样复制出去。
+ *
+ *   `> a` → `a` 早在 0.9 就踩过一次（段落里的链接落到浏览器默认蓝，
+ *   暗色对比度 1.91:1）。同一个坑换了标签又踩一次，所以这次把范围写宽：
+ *   正文里任何位置的图片都受同一条约束。 */
+.prose img {
   max-width: 100%;
   height: auto;
   display: block;

package/03-patterns/content/demo.html

@@ -79,7 +79,7 @@
   </dl>
 
   <h2>4 · 代码与链接</h2>
-  <pre><code>const f = (x) =&gt; x * 2;   // 纯 ES5 时代写法</code></pre>
+  <pre tabindex="0"><code>const f = (x) =&gt; x * 2;   // 纯 ES5 时代写法</code></pre>
   <p>详细口径见 <a href="#main">内部数据字典</a>。</p>
 
   <h2>5 · 待办清单</h2>

package/03-patterns/drawer/drawer.js

@@ -201,8 +201,44 @@
     bottom: 'drawer--bottom'
   };
 
+
+  /* HTML 净化钩子（F6 / 0.26.0）。
+     🔴 默认**不改变任何行为**：没传 `sanitize` 也没有 `setSanitizer()` 时，
+        `opt.content` 仍然按"调用方已净化"处理（与 0.25.x 一致）。
+     ⇒ 想接入 DOMPurify 这类库：
+          Drawer.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+        或逐次传 `opt.sanitize` 覆盖（逐次优先于模块级）。
+     ⚠️ 钩子只处理**字符串入口**；传 Node 的入口本来就绕过了 HTML 解析。 */
+  var SANITIZER = null;
+
+  function setSanitizer(fn) {
+    SANITIZER = (typeof fn === 'function') ? fn : null;
+  }
+
+  function sanitizeHtml(html, perCall) {
+    var fn = (typeof perCall === 'function') ? perCall : SANITIZER;
+    return fn ? String(fn(String(html))) : String(html);
+  }
+
+  /* 读屏文案默认值（F2 / 0.26.0）。不传 `labels` 时行为逐字不变。 */
+  var DEFAULT_LABELS = { dialog: '抽屉', close: '关闭' };
+
+  /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+  var flLabels = function (defaults, src) {
+    src = src || {};
+    var out = {};
+    var k;
+    for (k in defaults) {
+      if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+        out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+      }
+    }
+    return out;
+  };
+  /* ==== BEHAVIOR INJECT END: labels ==== */
   function open(opt) {
     opt = opt || {};
+    var L = flLabels(DEFAULT_LABELS, opt && opt.labels);
     var place = opt.place || 'right';
     var placeCls = PLACE_CLASS[place];
     if (!placeCls) placeCls = PLACE_CLASS.right;
@@ -226,7 +262,7 @@
     d.setAttribute('aria-modal', 'true');
     if (!d.id) d.id = 'drawer-' + (new Date()).getTime();
     if (opt.title) d.setAttribute('aria-labelledby', d.id + '-title');
-    else d.setAttribute('aria-label', opt.label || '抽屉');
+    else d.setAttribute('aria-label', opt.label || L.dialog);
     d.tabIndex = -1;              /* 焦点陷阱的兜底落点 */
 
     var head = document.createElement('div');
@@ -240,16 +276,18 @@
      导致上面所有 close.addEventListener 绑在函数上（静默失败）。 */
     closeBtn.className = 'drawer__close';
     closeBtn.type = 'button';
-    closeBtn.setAttribute('aria-label', '关闭');
+    closeBtn.setAttribute('aria-label', L.close);
     closeBtn.textContent = '\u00D7';
     head.appendChild(h);
     head.appendChild(closeBtn);
 
     var body = document.createElement('div');
     body.className = 'drawer__body';
-    /* @html-sink raw-html — `opt.content` 是有意的 HTML 入口，调用方负责净化；
-       登记在 SECURITY.md「HTML 入口（sink）」。 */
-    if (typeof opt.content === 'string') body.innerHTML = opt.content;
+    if (typeof opt.content === 'string') {
+      /* @html-sink raw-html — `opt.content` 是有意的 HTML 入口，调用方负责净化；
+         登记在 SECURITY.md「HTML 入口（sink）」。`sanitize` / `setSanitizer` 可挂钩。 */
+      body.innerHTML = sanitizeHtml(opt.content, opt.sanitize);
+    }
     else if (opt.content) body.appendChild(opt.content);
 
     d.appendChild(head);
@@ -374,5 +412,5 @@
     return { el: d, close: close };
   }
 
-  global.Drawer = { open: open };
+  global.Drawer = { open: open, setSanitizer: setSanitizer };
 })(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/dropdown/dropdown.js

@@ -330,6 +330,26 @@
   }
 
   function create(root, opt) {
+    /* 读屏文案默认值（F2 / 0.26.0）。不传 `labels` 时输出逐字不变。 */
+    var DEFAULT_LABELS = {
+      menu: '菜单'
+    };
+
+    /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+    var flLabels = function (defaults, src) {
+      src = src || {};
+      var out = {};
+      var k;
+      for (k in defaults) {
+        if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+          out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+        }
+      }
+      return out;
+    };
+    /* ==== BEHAVIOR INJECT END: labels ==== */
+  var L = flLabels(DEFAULT_LABELS, opt && opt.labels);
+
     opt = opt || {};
     var btn = root.querySelector('[data-dd-btn]') || root.querySelector('button');
     var menu = root.querySelector('[data-dd-menu]');
@@ -344,7 +364,7 @@
     /* APG：菜单要么全 aria-hidden，要么全不设 —— 不能半吊子 */
     menu.setAttribute('role', 'menu');
     if (!menu.getAttribute('aria-label') && !menu.getAttribute('aria-labelledby')) {
-      menu.setAttribute('aria-label', opt.label || '菜单');
+      menu.setAttribute('aria-label', opt.label || L.menu);
     }
     Array.prototype.forEach.call(menu.querySelectorAll('li'), function (li) {
       /* 🔴 修一个**静默失效**（实测发现）：

package/03-patterns/overlay/overlay.js

@@ -10,8 +10,9 @@
       demo 可以用现代语法（跑在用户浏览器上），库代码不行。
 
    API：
-     Overlay.toast({ title, desc, variant, duration })
+     Overlay.toast({ title, desc, variant, duration, maxVisible, labels })
      Overlay.dialog({ title, desc, actions, danger, initialFocus })
+     labels: 读屏文案覆盖（默认中文，不传时行为不变）
        → 返回 { el, close }
    ========================================================================= */
 (function (global) {
@@ -265,8 +266,36 @@
     warning: 'toast--warning'
   };
 
+  /* 读屏文案的**默认值**与合并规则（F2 / 0.26.0）。
+     🔴 只覆盖"会被读屏念出来或用户看得见"的文案；`throw new Error(...)`
+        这类是给调用方看的开发期信息，不在这里 —— 它们不经过 UI。
+     值可以是字符串，也可以是函数（动态文案，如 `第 N 页`）。
+     不传 `labels` 时行为与之前**逐字相同**（默认中文）。 */
+  var DEFAULT_LABELS = {
+    closeToast: '关闭提示'
+  };
+
+  /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+  var flLabels = function (defaults, src) {
+    src = src || {};
+    var out = {};
+    var k;
+    for (k in defaults) {
+      if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+        out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+      }
+    }
+    return out;
+  };
+  /* ==== BEHAVIOR INJECT END: labels ==== */
+  /* 同屏最多几条 toast。超了就把**最旧的**直接摘掉 ——
+     否则 20 条并发提示会把屏幕铺满，且最后一条永远读不到。
+     0 / 负数表示不限制（调用方自己负责）。 */
+  var TOAST_LIMIT = 4;
+
   function toast(opts) {
     opts = opts || {};
+    var L = flLabels(DEFAULT_LABELS, opts && opts.labels);
 
     var region = document.querySelector('.toast-region');
     if (!region) {
@@ -314,7 +343,7 @@
     var closeBtn = document.createElement('button');
     closeBtn.className = 'toast__close';
     closeBtn.type = 'button';
-    closeBtn.setAttribute('aria-label', '关闭提示');
+    closeBtn.setAttribute('aria-label', L.closeToast);
     closeBtn.textContent = '×';
     el.appendChild(closeBtn);
 
@@ -331,6 +360,14 @@
     }
 
     closeBtn.addEventListener('click', close);
+    /* 同屏上限：先摘最旧的，再挂新的。
+       🔴 摘的时候**不走 close()** —— 它带 220ms 退场动画，
+          动画期间节点仍在 DOM 里，children.length 不减 ⇒ 这里会空转。
+          被摘掉的那条已经在屏幕外了，动画没有意义。 */
+    var max = (opts.maxVisible === undefined) ? TOAST_LIMIT : opts.maxVisible;
+    while (max > 0 && region.children.length >= max) {
+      region.removeChild(region.firstChild);
+    }
     region.appendChild(el);
 
     var timerId = auto > 0 ? setTimeout(close, auto) : null;