agentcss 0.11.13 → 0.11.16

package/03-patterns/tabs/demo.html

@@ -17,7 +17,6 @@
 </head>
 <body class="page page">
 <main class="wrap">
-  <!-- demo-claim:skip 两块都可量（button 的个数、tabindex="0" 的个数），但这一页仍是单栏结构，升级成 cmp 要重排整页 —— 本轮没做，已知欠账 -->
   <h1>tabs · 标签页</h1>
   <p class="lede">
     标签页用于在同一位置切换<strong>同层级的几块内容</strong>。
@@ -103,37 +102,82 @@
     </p>
   </div>
 
-  <h2 class="rule-top">反例</h2>
-  <div class="box bad">
-    <h3>反例：用 div 当 tab</h3>
-    <div class="tabs">
-      <div class="tabs__list" role="tablist">
-        <div class="tabs__tab" role="tab" aria-selected="true">基本信息</div>
-        <div class="tabs__tab" role="tab" aria-selected="false">高级设置</div>
+  <h2 class="rule-top">对照：两处最容易写错的地方</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="[role=tab]|focus|=0">
+      <h3>❌ 用 div 当 tab</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="错例：div 当 tab">
+          <div class="tabs__tab" role="tab" aria-selected="true">基本信息</div>
+          <div class="tabs__tab" role="tab" aria-selected="false">高级设置</div>
+        </div>
       </div>
+      <p class="cmp__why">
+        这两个 tab <strong>看起来完全正常</strong>，但
+        <code>&lt;div role="tab"&gt;</code> 根本 Tab 不到（除非手写
+        <code>tabindex</code>），也不响应 Enter/Space。
+        APG 要求 tab 是 <code>&lt;button role="tab"&gt;</code>。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="[role=tab]|focus|=2">
+      <h3>✅ button role="tab"</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="正例：button 当 tab">
+          <button class="tabs__tab" role="tab" aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" aria-selected="false">高级设置</button>
+        </div>
+      </div>
+      <p class="cmp__why">
+        同一个外观，键盘行为免费且必然正确。
+        （这里只演示"能不能聚焦"，roving 见下面那块。）
+      </p>
     </div>
-    <p class="small">
-      上面这两个 tab <strong>看起来完全正常</strong>，但
-      <code>&lt;div role="tab"&gt;</code> 键盘上根本<strong>Tab 不到</strong>
-      （除非手写 <code>tabindex</code>），也不会响应 Enter/Space。
-      APG 明确要求 tab 是 <code>&lt;button role="tab"&gt;</code> ——
-      用原生 button，键盘行为免费且必然正确。
-    </p>
   </div>
-  <div class="box bad">
-    <h3>反例：每个 tab 都写 tabindex="0"</h3>
-    <div class="tabs">
-      <div class="tabs__list" role="tablist">
-        <button class="tabs__tab" role="tab" tabindex="0" aria-selected="true">基本信息</button>
-        <button class="tabs__tab" role="tab" tabindex="0">高级设置</button>
-        <button class="tabs__tab" role="tab" tabindex="0">日志</button>
+
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="[role=tab]|focus|=3">
+      <h3>❌ 每个 tab 都写 tabindex="0"</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="错例：三个 tab 全是 0">
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="false">高级设置</button>
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="false">日志</button>
+        </div>
       </div>
+      <p class="cmp__why">
+        看起来"都能 Tab 到"，但一排 3 个 tab 就要按 <strong>3 次 Tab</strong>
+        才能进内容区。Tab 键应该是<strong>进出</strong>控件的，
+        组内移动是方向键的活。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="[role=tab]|focus|=1">
+      <h3>✅ roving tabindex：整组只有一个 0</h3>
+      <div class="tabs" data-tabs>
+        <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="正例：roving">
+          <button class="tabs__tab" role="tab" id="rt1" aria-controls="rp1"
+                  aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" id="rt2" aria-controls="rp2"
+                  aria-selected="false">高级设置</button>
+          <button class="tabs__tab" role="tab" id="rt3" aria-controls="rp3"
+                  aria-selected="false">日志</button>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp1" aria-labelledby="rt1">
+          <p>一次 Tab 就进来，方向键在组内移动。</p>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp2" aria-labelledby="rt2" hidden>
+          <p>方向键到这里。</p>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp3" aria-labelledby="rt3" hidden>
+          <p>方向键到这里。</p>
+        </div>
+      </div>
+      <p class="cmp__why">
+        那个 <code>0</code> 跟着选中项走 —— 由 <code>roving.js</code> 在切换时搬，
+        不是初始化时设一次。只设一次是最常见的 bug。
+      </p>
     </div>
-    <p class="small">
-      看起来"都能 Tab 到"，但一排 3 个 tab 就要按 <strong>3 次 Tab</strong>
-      才能进内容区（真到 5 个 tab 的页面上只会更糟）。Tab 键应该是<strong>进出</strong>控件的，
-      组内移动是方向键的活。
-    </p>
   </div>
 </main>
 <script src="tabs.js"></script>

package/03-patterns/tabs/tabs.js

@@ -26,7 +26,7 @@
  *      只在初始化时设一次是最常见的 bug：用户激活第 3 个 tab 后，
  *      Tab 键还是会回到第 1 个。
  */
-(function () {
+(function (global) {
   'use strict';
 
   /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
@@ -165,6 +165,9 @@
   }
 
   function Tabs(root, opts) {
+    /* 🔴 同一 root 只允许一个实例 —— 理由同 accordion.js。
+       重复构造会让 keydown 监听叠两份：方向键按一次跳两格。 */
+    if (root && root.tabsInstance) return root.tabsInstance;
     this.root = root;
     this.opts = opts || {};
     this.list = root.querySelector('[role="tablist"]');
@@ -281,7 +284,7 @@
   };
 
   // 暴露
-  window.Tabs = Tabs;
+  global.Tabs = Tabs;
 
   // 自动初始化：<div class="tabs" data-tabs>
   //
@@ -294,14 +297,20 @@
   function init() {
     var nodes = document.querySelectorAll('[data-tabs]');
     for (var i = 0; i < nodes.length; i++) {
+      /* 🔴 幂等：同 accordion.js 里的理由。重复 new 会让 keydown / click
+         监听叠在同一个 root 上 ⇒ 方向键按一次跳两格。 */
+      if (nodes[i].tabsInstance) continue;
       nodes[i].tabsInstance = new Tabs(nodes[i], {});
     }
   }
 
   // @autoinit: [data-tabs] —— 扫属性自动建实例（详见 API.md「自动初始化」）
+  // ⚠️ 无 DOM 环境（SSR / 构建期 / Node 里 import）不自动初始化。
+  //    之前这里直接摸 document ⇒ Next.js 等 SSR 里 import 即 ReferenceError。
+  if (typeof document === 'undefined') return;
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', init);
   } else {
     init();
   }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/tooltip/tooltip.js

@@ -285,4 +285,4 @@ var flDismissable = function (opts) {
   }
 
   global.Tooltip = { attach: attach };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/tree/tree.js

@@ -461,4 +461,4 @@
   }
 
   global.Tree = { create: create };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/04-recipes/report/demo.html

@@ -181,7 +181,7 @@
            写死数字的话，插入一张新图后面全会错位。
            同一句标记放在 financial 版里不会出编号 —— 那是 profile 决定的，不是标记决定的。 -->
       <figure class="rep__fig">
-        <div class="table"><table>
+        <div class="table"><table aria-label="关键读数：包覆方案与保持率">
           <thead><tr>
             <th scope="col">方案</th>
             <th scope="col">保持率</th>
@@ -248,7 +248,7 @@
         <h3>关键假设</h3>
         <!-- 同一句标记放在 finance 版：没有编号，因为 financial profile 不开 counter -->
         <figure class="rep__fig">
-          <div class="table"><table>
+          <div class="table"><table aria-label="关键假设：三种情形下的良率与毛利率">
             <thead><tr>
               <th scope="col">情形</th>
               <th scope="col">良率</th>

package/09-assets/echarts-adapter/demo.html

@@ -35,7 +35,6 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
 </head>
 <body class="page page">
 <div class="wrap">
-  <!-- demo-claim:skip 反例是一张「不要做」清单表；3D、双 Y 轴这些错法都要真的渲染一张图才立得住，本页没有图表实例可摆 -->
   <h1>图表规范</h1>
   <p class="lede">
     <strong>下次画图照这里做就行</strong>，不用再反复微调。
@@ -45,7 +44,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   </p>
 
   <h2 class="rule-top">0 · 边界：什么该用本库，什么该用 ECharts</h2>
-  <table>
+  <table aria-label="能力边界：什么场景用本库、什么用 ECharts">
     <tr><th>场景</th><th>用什么</th><th>谁维护</th></tr>
     <tr><td>列表右侧的<strong>迷你趋势</strong>（看走势）</td>
         <td class="ok">本库 <code>sparkline</code>（1.5KB，零依赖）</td><td>我们</td></tr>
@@ -95,7 +94,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   <div class="flex">
     <div class="box">
       <h3 style="margin-top:0">✅ 规范：柱状图（分类轴从 0）</h3>
-      <table>
+      <table aria-label="示例数据：柱状图的分季度营收">
         <tr><th>季度</th><th class="num">营收(亿)</th><th class="num">同比</th></tr>
         <tr><td>Q1</td><td class="num">128.4</td><td class="num up">+12.4%</td></tr>
         <tr><td>Q2</td><td class="num">136.1</td><td class="num up">+8.1%</td></tr>
@@ -110,7 +109,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
 
     <div class="box">
       <h3 style="margin-top:0">✅ 规范：多系列（≤ 5 条）</h3>
-      <table>
+      <table aria-label="示例数据：A / B / C 三支股票的逐年对比">
         <tr><th>年份</th>
             <th class="num"><span class="swatch" style="background:var(--accent)"></span>A 股</th>
             <th class="num"><span class="swatch" style="background:var(--danger)"></span>B 股</th>
@@ -134,7 +133,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   </div>
 
   <h2 class="rule-top">3 · 数字格式（已经在用）</h2>
-  <table>
+  <table aria-label="数字格式规则与例子">
     <tr><th>类型</th><th>规则</th><th>例子</th></tr>
     <tr><td>千分位</td><td>每三位加逗号</td><td class="num">1,234,567</td></tr>
     <tr><td>百分比</td><td>固定 1–2 位小数</td><td class="num">42.6%</td></tr>
@@ -148,8 +147,8 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   </p>
 
   <h2 class="rule-top">4 · 明确禁止（这些是"看起来专业但会骗人"的）</h2>
-  <div class="box bad">
-    <table>
+  <div class="box bad" data-claim-skip="这一块是「不要做」清单本身（一张表），不是某个组件的错写法 —— 要给它配正例栏，得先真的渲染一张 3D 图与一张 2D 图做对照，而本页没有图表实例可摆；表格尺寸量出来的是排版，不是观点">
+    <table aria-label="明确禁止的做法与原因">
       <tr><th>不要做</th><th>为什么</th></tr>
       <tr><td class="no">3D 图表</td><td>透视扭曲会<b>误导读数</b>（Tufte 的核心结论）</td></tr>
       <tr><td class="no">双 Y 轴</td><td>两轴的交叉点可以被随意搬动 ⇒ <b>视觉在说谎</b></td></tr>

package/09-assets/model-viewer/demo.html

@@ -59,7 +59,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
        data-mv-orbit="vendor/OrbitControls.js"></div>
 
   <h2 class="rule-top">为什么是这样设计的</h2>
-  <table>
+  <table aria-label="3D 模型页的设计要求与做法">
     <tr><th>要求</th><th>做法</th></tr>
     <tr><td>首屏要快</td>
         <td>3D 引擎<strong>点击后</strong>才 <code>&lt;script&gt;</code> 注入，
@@ -85,7 +85,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   </ul>
 
   <h2 class="rule-top">体积现状</h2>
-  <table>
+  <table aria-label="各文件的体积与加载时机">
     <tr><th>文件</th><th class="num">体积</th><th>何时加载</th></tr>
     <tr><td><code>model-viewer.js</code>（本库）</td><td class="num">~9 KB</td><td><span class="ok">首屏</span></td></tr>
     <tr><td><code>models/fox.glb</code></td><td class="num">159 KB</td><td>点击后（可 XHR 显示进度）</td></tr>

package/09-assets/sparkline/demo.html

@@ -34,7 +34,6 @@
 </head>
 <body class="page page">
 <main class="wrap">
-  <!-- demo-claim:skip 两块反例（读屏念什么、reduced-motion 动画）都是运行时或读屏输出，没有可量的元素属性 -->
   <h1>sparkline · 迷你趋势图</h1>
   <p class="lede">
     在一行里显示"最近走势"。它是<strong>辅助</strong>不是图表 ——
@@ -124,7 +123,7 @@
   </div>
 
   <h2 class="rule-top">反例</h2>
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="两栏画的是同一条走势线，差别只在旁边有没有一个数字 —— 而「该不该配数字」本页上文明写取决于数值重不重要（纯装饰小图可以不配），没有一条能划的界线；断言只能去数一个我自己编出来的选择器，那证明的是我编的标记，不是这件事">
     <h3>反例：只放 sparkline，没有数字</h3>
     <p class="small">
       视觉上"很有信息"，但读屏用户<strong>什么都不知道</strong> ——

package/API.md

@@ -24,6 +24,30 @@
 各有各的调用方式。下表由`05-audit/global-api-probe.js`在真实浏览器里
 探测生成，门禁 `api-doc` 会核对本文与实现是否一致。
 
+### 模块化引入（ESM）
+
+除了 `<script src>`，16 个交互组件的脚本还有一个 ESM 入口：
+
+```js
+// 只要一个
+import { Accordion } from 'agentcss/esm/accordion.mjs';
+
+// 或者一次拿全（体积更大，Vite/Rollup 会按需摇树）
+import { Accordion, Tabs, Select } from 'agentcss/esm';
+```
+
+三条容易踩的：
+
+1. **入口是包装，不是第二份实现**。`esm/*.mjs` 只做
+   「导入副作用 + 把全局上那个对象 re-export」，所以
+   `Accordion === window.Accordion` 恒成立（门禁 `behavior-api` 断言这一点）。
+   它由 `05-audit/gen-esm.py` 生成，改源码后要重新生成，`esm-gen` 门禁会拦住漂移。
+2. **无 DOM 环境可以直接 import**（SSR 安全）。但自动初始化会被跳过 ——
+   服务端没有 DOM 可扫，到浏览器里再调 `init()`/构造函数。16 个脚本
+   在 Node 里 `require` 全部成功（门禁的判据 A）。
+3. **重复初始化是安全的**。`init()` 与构造函数都做了幂等处理：
+   同一 root 只会有一个实例，不会出现「点一次切换两次」。
+
 ### 四种接入形态
 
 | 形态 | 调用方式 | 适合 |
@@ -327,6 +351,16 @@ python3 05-audit/prefix-build.py --prefix fl
 
 ## 破坏性变更怎么走
 
-- 只在**大版本**移除或重命名公开类名、`data-*`、方法
-- 弃用项先加警告并保留一个完整版本周期
-- 变更记录写在 `CHANGELOG.md`
+公开**名字**（令牌名 / 类名 / 全局与类型成员 / 事件名）的移除走**登记制**：
+
+- 先在 `ai/deprecations.json` 里登记，写清 `deprecatedIn`、`removeIn`、`reason`
+- 迁移窗口**至少跨一个次版本**：`0.7.x` 里标弃用 ⇒ 最早 `0.8.0` 才允许消失
+- 到期才删。**提前删**和**到期不删**都会被门禁拦下（`05-audit/deprecation-gate.py`）
+- 对外说明在 `docs/DEPRECATIONS.md`，那份文档与登记册由门禁**双向**比对，
+  漏告知（登记了没写进文档）与假承诺（文档写了、登记册没有）都会红
+
+> 🔴 本节此前写的是「只在**大版本**移除」「弃用项先加警告并保留一个完整版本周期」——
+> 两句都是错的：本库在 `0.7.x → 0.8.0` 就删过名字（`state--delayed`），
+> 而且组件脚本从不打印运行时警告（移动端 WebView 里那是纯噪音）。
+> `0.x` 期间按 semver 本就允许破坏性变更，把话说满比说清更伤人。
+> 现在这两句被上面四条取代，覆盖范围与抓不到哪些名字见 `docs/DEPRECATIONS.md`。