agentcss 0.25.6 → 0.27.0

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;

package/03-patterns/pagination/pagination.js

@@ -137,12 +137,39 @@
 
   /* ---------------------------------------------------------------------- */
 
-  function Pagination(node) {
+  /* 读屏文案默认值（F2 / 0.26.0）。值是字符串或函数；
+     不传 `labels` 时输出与之前逐字相同。 */
+  var DEFAULT_LABELS = {
+    nav: '分页',
+    prev: '上一页',
+    next: '下一页',
+    page: function (p, isCurrent) {
+      return '第 ' + p + ' 页' + (isCurrent ? '（当前页）' : '');
+    },
+    status: function (page, pages) { return '第 ' + page + ' 页 / 共 ' + pages + ' 页'; },
+    live: function (page, pages) { return '第 ' + page + ' 页，共 ' + pages + ' 页'; }
+  };
+
+  /* ==== 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 Pagination(node, opts) {
     this.node = node;
+    this.labels = flLabels(DEFAULT_LABELS, opts && opts.labels);
     this.total = Math.max(1, parseInt(node.getAttribute('data-total') || '1', 10));
     this.size = Math.max(1, parseInt(node.getAttribute('data-page-size') || '20', 10));
     this.page = Math.max(1, parseInt(node.getAttribute('data-page') || '1', 10));
-    this.label = node.getAttribute('aria-label') || '分页';
+    this.label = node.getAttribute('aria-label') || this.labels.nav;
     this.pages = Math.max(1, Math.ceil(this.total / this.size));
     this.onChange = null;
 
@@ -301,7 +328,7 @@
   /** ⭐ 播报（依据第 2 条：改 textContent，不换元素） */
   Pagination.prototype.announce = function () {
     if (!this.liveNode) return;
-    this.liveNode.textContent = '第 ' + this.page + ' 页，共 ' + this.pages + ' 页';
+    this.liveNode.textContent = this.labels.live(this.page, this.pages);
   };
 
   Pagination.prototype.render = function () {
@@ -309,6 +336,7 @@
     var L = this.listNode;
     while (L.firstChild) L.removeChild(L.firstChild);
     var self = this;
+    var T = this.labels;
 
     function addBtn(text, ariaLabel, goto, disabled) {
       var li = el('li', 'pagination__item');
@@ -325,7 +353,7 @@
     }
 
     /* --- 上一页 / 首页 --- */
-    addBtn('‹', '上一页', 'prev', self.page <= 1);
+    addBtn('‹', T.prev, 'prev', self.page <= 1);
     /* --- 页码 --- */
     var win = pageWindow(self.page, self.pages, SLOTS);
     for (var i = 0; i < win.length; i++) {
@@ -347,7 +375,7 @@
       var b2 = el('button', 'pagination__link', String(p));
       b2.type = 'button';
       b2.setAttribute('data-goto', String(p));
-      b2.setAttribute('aria-label', '第 ' + p + ' 页' + (isCur ? '（当前页）' : ''));
+      b2.setAttribute('aria-label', T.page(p, isCur));
       if (isCur) {
         b2.setAttribute('aria-current', 'page');
         b2.setAttribute('aria-disabled', 'true');
@@ -356,22 +384,21 @@
       L.appendChild(li2);
     }
     /* --- 下一页 / 末页 --- */
-    addBtn('›', '下一页', 'next', self.page >= self.pages);
+    addBtn('›', T.next, 'next', self.page >= self.pages);
 
     /* --- 可见状态（"第 2 页 / 共 12 页"） --- */
     if (this.statusNode) {
-      this.statusNode.textContent =
-        '第 ' + self.page + ' 页 / 共 ' + self.pages + ' 页';
+      this.statusNode.textContent = T.status(self.page, self.pages);
     }
   };
 
   /* ---------------------------------------------------------------------- */
   var API = {
     /** 创建一个分页实例（返回实例以便绑定 onChange） */
-    create: function (node) {
+    create: function (node, opts) {
       if (!node) return null;
       if (node.__pg) return node.__pg;
-      node.__pg = new Pagination(node);
+      node.__pg = new Pagination(node, opts);
       return node.__pg;
     },
     /** 页面内所有 [data-pagination] */

package/03-patterns/states/states.css

@@ -137,7 +137,7 @@
        ⇒ 减少动态效果的用户照样看到闪烁的微光；
      · 与 `02-primitives/skeleton/skeleton.css` 同特异性 ⇒ 谁后加载谁定生死。
 
-   即"要不要尊重减少动态效果"取决于 CSS 顺序。与 E254 同类。
+   即"要不要尊重减少动态效果"取决于 CSS 顺序。与同类。
    ⚠️ 这里与 skeleton.css 是**两份实现**（已登记在 css-ownership.json），
       修的时候两边都要看。 */
 @media (prefers-reduced-motion: no-preference) {

package/03-patterns/tooltip/tooltip.js

@@ -125,6 +125,21 @@ var flDismissable = function (opts) {
 
   var uid = 0;
 
+  /* 读屏文案默认值（F2 / 0.26.0）。
+     本组件是 `attach(el, text)` 形式、没有逐实例 opts，
+     所以文案用**模块级**设置：`Tooltip.setLabels({ region: 'Tooltip' })`。 */
+  var LABELS = { region: '组件提示' };
+
+  function setLabels(patch) {
+    if (!patch) return;
+    for (var k in LABELS) {
+      if (Object.prototype.hasOwnProperty.call(LABELS, k)
+        && patch[k] !== undefined && patch[k] !== null) {
+        LABELS[k] = patch[k];
+      }
+    }
+  }
+
   function ensureStyle() {
     if (document.getElementById('tooltip-css')) return;
     /* 说明：样式由页面通过 <link> 引入；这里只做"有没有"的提示，
@@ -149,7 +164,7 @@ var flDismissable = function (opts) {
        而在读屏用户"到达"它之前它通常是空的
        ⇒ 光靠内容拿不到名字 ⇒ 必须显式给 aria-label。
        label 用通用措辞，具体内容由 aria-live 负责播报。 */
-    r.setAttribute('aria-label', '组件提示');
+    r.setAttribute('aria-label', LABELS.region);
     r.style.cssText =
       'position:absolute;width:1px;height:1px;padding:0;margin:-1px;' +
       'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0';
@@ -280,5 +295,5 @@ var flDismissable = function (opts) {
     el.setAttribute('data-tooltip', text);
   }
 
-  global.Tooltip = { attach: attach };
+  global.Tooltip = { attach: attach, setLabels: setLabels };
 })(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/tree/tree.js

@@ -231,11 +231,31 @@
   var uid = 0;
 
   function create(root, opt) {
+    /* 读屏文案默认值（F2 / 0.26.0）。不传 `labels` 时输出逐字不变。 */
+    var DEFAULT_LABELS = {
+      tree: '树形视图'
+    };
+
+    /* ==== 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 || {};
     root.classList.add('tree');
     if (!root.getAttribute('role')) root.setAttribute('role', 'tree');
     if (!root.getAttribute('aria-label') && !root.getAttribute('aria-labelledby')) {
-      root.setAttribute('aria-label', opt.label || '树形视图');
+      root.setAttribute('aria-label', opt.label || L.tree);
     }
 
     /* ---------- 初始化结构 ---------- */

package/04-recipes/analysis-report/demo.html

@@ -98,7 +98,7 @@
           每组成 2 个平行样，取算术平均。
         </p>
 
-        <pre class="report__code">电解液     1 M LiPF6 in EC:EMC:DMC = 3:5:2 (v/v) + 2 wt% VC
+        <pre class="report__code" tabindex="0">电解液     1 M LiPF6 in EC:EMC:DMC = 3:5:2 (v/v) + 2 wt% VC
 截止电压   3.0 – 4.4 V (vs. Li/Li+)
 倍率       0.5C 充电 / 1.0C 放电
 温度       25 ± 1 °C

package/04-recipes/app-shell/README.md

@@ -243,7 +243,7 @@ rail 下硬塞一个 `.shell__side-label` 会被 CSS 藏掉（兜底，防止它
 
 - **❌ 侧栏 `position: fixed` + 主区 `margin-inline-start`** —— 看起来能用，但侧栏被摘出
   grid 流，主区宽度靠**手抄的数字**维持（改侧栏宽就要改两处）；`inset-inline-start`
-  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。**
+  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。
 
   正确的做法见上面「侧栏为什么是 `sticky` 而不是 `fixed`」。
 

package/04-recipes/app-shell/demo.html

@@ -48,7 +48,7 @@
 
 <h1>应用外壳 · app-shell</h1>
 <p class="lede">工具型页面的骨架：左边一列常驻导航、上面一条工具栏、右边是主区。
-它存在的理由不是"少写几个 div"，而是**两个每个人都会踩的坑** —— 见下面两节。</p>
+它存在的理由不是"少写几个 div"，而是<strong>两个每个人都会踩的坑</strong> —— 见下面两节。</p>
 
 <h2>1 · 标准三段式</h2>
 <div class="demo">

package/04-recipes/data-showcase/demo.html

@@ -112,7 +112,7 @@
   多级表头用 <code>scope</code> 标明层级。
 </p>
 
-<div class="table table--academic">
+<div class="table table--academic" tabindex="0" role="region" aria-label="三种干燥工艺的成品性能对比（可横向滚动）">
   <table>
     <caption class="table__cap">表 1 · 三种干燥工艺的成品性能对比（示例数据）</caption>
     <thead>
@@ -157,7 +157,7 @@
   不能用同一个数字格式化函数打发。<strong>本表不推断显著性，也不计算统计量。</strong>
 </p>
 
-<div class="table table--stats">
+<div class="table table--stats" tabindex="0" role="region" aria-label="干燥工艺对含水率的影响（可横向滚动）">
   <table>
     <caption class="table__cap">表 2 · 干燥工艺对含水率的影响（OLS 估计，示例数据，n = 60）</caption>
     <thead>