agentcss 0.11.14 → 0.11.16

package/02-primitives/combobox/combobox.js

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

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

@@ -298,4 +298,4 @@
     iso: iso, addDays: addDays, addMonths: addMonths,
     quarterOf: quarterOf, quarterRange: quarterRange,
   };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/02-primitives/popover/demo.html

@@ -78,7 +78,7 @@ th { font-weight: 600; }
 
 <h2>怎么选？</h2>
 <div class="demo">
-  <table>
+  <table aria-label="tooltip / popover / dialog 三者的选择依据">
     <tr><th>组件</th><th>能放交互内容</th><th>背景是否锁死</th><th>用在哪</th></tr>
     <tr><td><code>tooltip</code></td><td>❌ 只能纯文字</td><td>—</td><td>补充说明、术语解释</td></tr>
     <tr><td><b><code>popover</code></b></td><td>✅</td><td><b>不锁</b></td><td>筛选、快捷设置、补充表单</td></tr>

package/02-primitives/popover/popover.js

@@ -328,4 +328,4 @@
   };
 
   global.Popover = Popover;
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/02-primitives/select/select.js

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

package/03-patterns/accordion/accordion.js

@@ -28,7 +28,7 @@
  *      否则造成 "landmark region proliferation"（地标泛滥）。
  *    ⇒ 加 .accordion--many 即可关闭。
  */
-(function () {
+(function (global) {
   'use strict';
   // 🔴 手风琴实例序号（保证 id 全局唯一，见 init 里的说明）
   var uid = 0;
@@ -60,8 +60,13 @@
 
   function toArray(x) { return Array.prototype.slice.call(x); }
 
-  /* requestAnimationFrame 的 ES5 安全版 */
-  var raf = (typeof window.requestAnimationFrame === 'function')
+  /* requestAnimationFrame 的 ES5 安全版
+     ⚠️ 必须先判 `window` 存在再摸 `.requestAnimationFrame`：
+        `typeof window.requestAnimationFrame` 会**先解引用 window**，
+        在 Node / SSR 里直接 ReferenceError（不是返回 'undefined'）。
+        这条曾经让本文件在 Next.js 里 import 即崩。 */
+  var raf = (typeof window !== 'undefined' &&
+             typeof window.requestAnimationFrame === 'function')
     ? window.requestAnimationFrame.bind(window)
     : function (fn) { return setTimeout(fn, 16); };
 
@@ -85,6 +90,12 @@
   }
 
   function Accordion(root, opts) {
+    /* 🔴 同一 root 只允许一个实例。
+       不加这条时 `new Accordion(root)` 两次会留下**两份** click 监听
+       （旧实例不会被回收：它的监听器闭包referencing this，还挂在 root 上）
+       ⇒ 一次点击 toggle 两次，肉眼看到的是"点了没反应"。
+       构造器返回对象是 JS 合法行为，会覆盖 `this`，调用方拿到的就是旧实例。 */
+    if (root && root.accordionInstance) return root.accordionInstance;
     this.root = root;
     this.opts = opts || {};
     this.items = toArray(root.querySelectorAll('.accordion__item'));
@@ -351,19 +362,28 @@
     //    这是「用原生控件」的又一处收益：**无障碍行为免费且必然正确**。
   };
 
-  window.Accordion = Accordion;
+  global.Accordion = Accordion;
 
   function init() {
     var nodes = document.querySelectorAll('[data-accordion]');
     for (var i = 0; i < nodes.length; i++) {
+      /* 🔴 幂等：已经初始化过就跳过。
+         不加守卫的后果是**静默的**：第二次 new 会把 accordionInstance 覆盖成新实例，
+         而**旧实例挂在 root 上的 click 监听还在** ⇒ 一次点击 toggle 两次
+         （展开又收起，看上去"点了没反应"）。
+         SPA 路由切换、HMR、重复引入同一份脚本都会触发这条路。 */
+      if (nodes[i].accordionInstance) continue;
       nodes[i].accordionInstance = new Accordion(nodes[i]);
     }
   }
 
   // @autoinit: [data-accordion] —— 自动初始化；与 API.md「自动初始化」表由 autoinit-gate 双向校验
+  // ⚠️ 无 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/drawer/drawer.js

@@ -255,4 +255,4 @@
   }
 
   global.Drawer = { open: open };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/dropdown/dropdown.js

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

package/03-patterns/list/flip.js

@@ -198,4 +198,4 @@
 
   global.FLIP = { flip: flip, remove: removeWithAnimation };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/nav/nav.js

@@ -59,7 +59,7 @@
  *   手动：new Nav(rootEl, { labels: { open: '打开菜单', close: '关闭菜单' } })
  *   事件：fl-nav-open / fl-nav-close（detail = { root: <nav> }）
  */
-(function () {
+(function (global) {
   'use strict';
 
   /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
@@ -413,7 +413,7 @@
     return root.navInstance;
   };
 
-  window.Nav = Nav;
+  global.Nav = Nav;
 
   function init() {
     each(document.querySelectorAll('[data-nav]'), function (el) {
@@ -422,9 +422,12 @@
   }
 
   // @autoinit: [data-nav] —— 扫属性自动建实例（详见 README「自动初始化」）
+  // ⚠️ 无 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/nav/toc.js

@@ -108,4 +108,4 @@
 
   global.Toc = { init: init };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/overlay/overlay.js

@@ -560,4 +560,4 @@
 
   global.Overlay = { toast: toast, dialog: dialog };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/pagination/demo.html

@@ -69,7 +69,7 @@ th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
   </div>
 
   <h2 class="rule-top">2 · 结构：六条硬要求</h2>
-  <table>
+  <table aria-label="分页容器的六条结构要求与理由">
     <tr><th>要求</th><th>为什么</th></tr>
     <tr><td>包在 <code>&lt;nav aria-label&gt;</code> 里</td>
         <td>页面常有多个 nav（主导航/面包屑/分页），

package/03-patterns/pagination/pagination.js

@@ -35,7 +35,7 @@
  *     });
  *   </script>
  */
-(function () {
+(function (global) {
   'use strict';
 
   /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
@@ -385,11 +385,17 @@
     },
   };
 
-  if (typeof window !== 'undefined') window.Pagination = API;
+  /* global 已在 IIFE 收尾处解析成 window 或 globalThis（无 DOM 环境），
+     所以这里**无条件挂**——再套一层 `typeof window !== 'undefined'` 会让
+     SSR 里 require 得到 undefined（`esm/` 包装就取不到 API）。 */
+  global.Pagination = API;
   // @autoinit: [data-pagination] —— 扫属性自动 update()（详见 API.md「自动初始化」）
+  // ⚠️ 无 DOM 环境（SSR / 构建期 / Node 里 import）不自动初始化。
+  //    之前这里直接摸 document ⇒ Next.js 等 SSR 里 import 即 ReferenceError。
+  if (typeof document === 'undefined') return;
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', function () { API.update(); });
   } else {
     API.update();
   }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);

package/03-patterns/reveal/reveal.js

@@ -164,9 +164,12 @@
   }
 
   // @autoinit: conditional[data-reveal-auto] —— 只有 <html data-reveal-auto> 才 enable()；不写则完全不动
+  // ⚠️ 无 DOM 环境（SSR / 构建期 / Node 里 import）不自动初始化。
+  //    之前这里直接摸 document ⇒ Next.js 等 SSR 里 import 即 ReferenceError。
+  if (typeof document === 'undefined') return;
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', auto, false);
   } else {
     auto();
   }
-}(this));
+})(typeof window !== 'undefined' ? window : globalThis);

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

@@ -44,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>
@@ -94,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>
@@ -109,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>
@@ -133,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,7 +148,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
 
   <h2 class="rule-top">4 · 明确禁止（这些是"看起来专业但会骗人"的）</h2>
   <div class="box bad" data-claim-skip="这一块是「不要做」清单本身（一张表），不是某个组件的错写法 —— 要给它配正例栏，得先真的渲染一张 3D 图与一张 2D 图做对照，而本页没有图表实例可摆；表格尺寸量出来的是排版，不是观点">
-    <table>
+    <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/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`。