agentcss 0.11.14 → 0.12.0

package/02-primitives/metric/README.md

@@ -0,0 +1,93 @@
+# metric · 指标块
+
+报表里**“一个数”的最小完整单元**：一个标签、一个值、一句上下文。
+
+```html
+<link rel="stylesheet" href="02-primitives/metric/metric.css">
+
+<dl class="metric">
+  <dt class="metric__label">营业总收入</dt>
+  <dd class="metric__value">1,294.06<span class="metric__unit">亿元</span></dd>
+  <dd class="metric__foot">
+    <span class="delta delta--up">12.40%</span>
+    <span class="metric__note">同比</span>
+  </dd>
+</dl>
+```
+
+## 类
+
+| 类 | 作用 |
+|---|---|
+| `.metric` | 基础块（推荐 `<dl>`，用 `<div>` 也能渲染） |
+| `.metric__label` | 标签：12px、次要色 |
+| `.metric__value` | 值：等宽字族（`--mono`）+ 默认不换行（装不下才断） |
+| `.metric__unit` | 单位：与数字同基线，小一号 |
+| `.metric__foot` | 脚下那行：通常放 `delta` + 说明词 |
+| `.metric__note` | 说明词（“同比” / “较上季”） |
+| `.metric__spark` | 迷你走势槽位，放不放都行 |
+| `.metric--lg` | 主指标档 |
+| `.metric--sm` | 紧凑档（密集网格） |
+| `.metric--null` | 缺数档：值降为 tertiary、去字重 |
+| `.metric-grid` | KPI 行的自适应网格 |
+
+## 三条硬规矩
+
+1. **缺数写 `—`（U+2014）并说明原因**，不填 0、不留空、不只把字变淡。
+2. **单位放 `metric__unit`**，不要拼进值字符串。
+3. **变化量放 `metric__foot`**，不要混进 `metric__value`。
+
+## 反例
+
+- ❌ **缺数填 0** —— `0.00` 与 `—` 在报表上是两个不同结论。填 0 会让读者把「未披露」读成「现金流为零」，而它其实可能只是没出报表
+- ❌ **把单位拼进值字符串** —— `1,294.06亿元` 让单位跟着 30px 字号走、和数字一样重，读者第一眼会把“亿元”当成数值的一部分；而且没法单选单位调样式
+- ❌ **把 `delta` 塞进 `metric__value`** —— 值里混进变化量之后等宽对齐失效（两段数字位数不同），读屏也会念成一串。变化量属于 `metric__foot`
+- ❌ **用 `opacity` 表达缺数** —— `--text-tertiary` 的 5.33:1 已经是文字色地板，再乘一次透明度就跌破 4.5。缺数靠“不给数字”表达，不靠让它看不清
+- ❌ **把 `metric` 当卡片用** —— 它没有边框、没有内边距、不承载操作区。要“一块带边框的内容”用 `card`；`metric` 只负责一个数
+
+## 为什么推荐 `<dl>`
+
+“标签—值”在 HTML 里有现成语义：术语 + 描述。读屏会念
+「营业总收入 1,294.06 亿元 +12.40% 同比」；用 `<div>` 只会念一串没有关系的词。
+CSS 只认类名，所以 `<div>` 也能渲染（兼容既有页面），但文档一律示范 `<dl>`。
+
+## 网格
+
+```html
+<div class="metric-grid">
+  <dl class="metric"> … </dl>
+  <dl class="metric"> … </dl>
+</div>
+```
+
+内部是 `repeat(auto-fit, minmax(min(100%, 12rem), 1fr))`。
+那层 `min()` 不是冗余：窄容器下 12rem 会比可用宽度还大，没有它就会横向溢出
+（`05-audit/metric-check.js` 判据 ⑧ 在 375px 视口下直接量 `scrollWidth`）。
+
+## 缺数是一等状态
+
+```html
+<dl class="metric metric--null">
+  <dt class="metric__label">经营活动现金流净额</dt>
+  <dd class="metric__value">—</dd>
+  <dd class="metric__foot"><span class="metric__note">本期未披露</span></dd>
+</dl>
+```
+
+`metric--null` 只把值的颜色降到 tertiary、去掉字重，**不隐藏这一块** ——
+版面塌掉比显示“没有”更糟。这是本库从 `04-recipes/detail-page` 的 null 变体
+继承下来的同一条纪律。
+
+## 对本组件不做的事
+
+- **不做数值格式化**。千分位、小数位、单位换算由数据侧决定；CSS 不知道
+  `1,294.06` 与 `1294.06` 哪个对。库保证的是等宽对齐与不换行。
+- **不判断方向**。涨跌颜色交给 `delta`，本组件不含任何方向令牌引用
+  （`metric-check` 判据 ⑦ 静态检查这件事）。
+
+## 预览
+
+```bash
+python -m http.server 8000
+# http://127.0.0.1:8000/02-primitives/metric/demo.html
+```

package/02-primitives/metric/demo.html

@@ -0,0 +1,176 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="data:,">
+<title>metric · 指标块</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="../../02-primitives/metric/metric.css">
+<link rel="stylesheet" href="../../02-primitives/delta/delta.css">
+<link rel="stylesheet" href="../../09-assets/sparkline/sparkline.css">
+<style>
+.pad { padding: var(--sp-4) 0; }
+.frame { border: 1px solid var(--border-decor); border-radius: var(--r-md);
+         padding: var(--sp-5); background: var(--surface); }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <h1>metric · 指标块</h1>
+  <p class="lede">
+    报表里<strong>“一个数”的最小完整单元</strong>：一个标签、一个值、一句上下文。
+    KPI 行、详情页顶部、监控面板，都由它排出来。
+  </p>
+
+  <h2 class="rule-top">一个完整的 metric</h2>
+  <div class="frame">
+    <dl class="metric" style="max-width: 18rem">
+      <dt class="metric__label">营业总收入</dt>
+      <dd class="metric__value">1,294.06<span class="metric__unit">亿元</span></dd>
+      <dd class="metric__foot">
+        <span class="delta delta--up">12.40%</span>
+        <span class="metric__note">同比</span>
+      </dd>
+    </dl>
+  </div>
+  <p class="small">
+    四件必须一起做对的事：<strong>数字等宽</strong>（上下两行数位对齐，竖着扫能比大小）、
+    <strong>单位分离成槽位</strong>（拼进字符串就没法单独调样式，也没法让数字右对齐时把单位甩在外面）、
+    <strong>缺数是一等状态</strong>（见下）、<strong>方向交给 delta</strong>（本组件不管颜色）。
+    <br>
+    结构用 <code>&lt;dl&gt;</code> 是因为“标签—值”在 HTML 里有现成语义：
+    读屏会念「营业总收入 1,294.06 亿元 +12.40% 同比」。用 <code>&lt;div&gt;</code>
+    只会念一串没有关系的词（CSS 只认类名，用 div 也能渲染，但不推荐）。
+  </p>
+
+  <h2 class="rule-top">一行四个 KPI</h2>
+  <div class="metric-grid">
+    <dl class="metric">
+      <dt class="metric__label">营业总收入</dt>
+      <dd class="metric__value">1,294.06<span class="metric__unit">亿元</span></dd>
+      <dd class="metric__foot"><span class="delta delta--up">12.40%</span><span class="metric__note">同比</span></dd>
+    </dl>
+    <dl class="metric">
+      <dt class="metric__label">归母净利润</dt>
+      <dd class="metric__value">318.72<span class="metric__unit">亿元</span></dd>
+      <dd class="metric__foot"><span class="delta delta--up">8.60%</span><span class="metric__note">同比</span></dd>
+    </dl>
+    <dl class="metric">
+      <dt class="metric__label">销售毛利率</dt>
+      <dd class="metric__value">41.28<span class="metric__unit">%</span></dd>
+      <dd class="metric__foot"><span class="delta delta--down">1.34%</span><span class="metric__note">同比</span></dd>
+    </dl>
+    <dl class="metric metric--null">
+      <dt class="metric__label">经营活动现金流净额</dt>
+      <dd class="metric__value">—</dd>
+      <dd class="metric__foot"><span class="metric__note">本期未披露</span></dd>
+    </dl>
+  </div>
+  <p class="small">
+    第四块是<strong>缺数</strong>：值写 <code>—</code>（U+2014），并在脚下说明原因。
+    它<strong>不隐藏、不变灰到看不见、也不填 0</strong> —— 版面塌掉比显示“没有”更糟，
+    而填 0 是伪造数据：读者会把“未披露”读成“现金流为零”。
+    <br>
+    网格用 <code>metric-grid</code>，它内部是
+    <code>minmax(min(100%, 12rem), 1fr)</code> —— 那层 <code>min()</code> 不是冗余：
+    窄容器下 12rem 会比可用宽度还大，没有它就会横向溢出。
+  </p>
+
+  <h2 class="rule-top">三档字号</h2>
+  <div class="frame">
+    <div class="metric-grid">
+      <dl class="metric metric--lg">
+        <dt class="metric__label">主指标（lg）</dt>
+        <dd class="metric__value">318.72<span class="metric__unit">亿元</span></dd>
+      </dl>
+      <dl class="metric">
+        <dt class="metric__label">默认</dt>
+        <dd class="metric__value">318.72<span class="metric__unit">亿元</span></dd>
+      </dl>
+      <dl class="metric metric--sm">
+        <dt class="metric__label">紧凑档（sm）</dt>
+        <dd class="metric__value">318.72<span class="metric__unit">亿元</span></dd>
+      </dl>
+    </div>
+  </div>
+  <p class="small">
+    三档够了。出现第四档说明 KPI 行的层级没规划好（与 <code>badge</code> / <code>card</code> 同一判断标准）。
+  </p>
+
+  <h2 class="rule-top">迷你走势槽位</h2>
+  <div class="frame">
+    <div class="metric-grid">
+      <dl class="metric">
+        <dt class="metric__label">近九个交易日收盘</dt>
+        <dd class="metric__value">1,684.00</dd>
+        <dd class="metric__foot"><span class="delta delta--up">5.12%</span><span class="metric__note">五日</span></dd>
+        <dd class="metric__spark">
+          <span class="sparkline" data-spark="1602,1618,1609,1631,1625,1648,1662,1655,1684"></span>
+        </dd>
+      </dl>
+      <dl class="metric">
+        <dt class="metric__label">近九个交易日成交量</dt>
+        <dd class="metric__value">3.42<span class="metric__unit">亿手</span></dd>
+        <dd class="metric__foot"><span class="delta delta--down">2.08%</span><span class="metric__note">五日</span></dd>
+        <dd class="metric__spark">
+          <span class="sparkline" data-spark="3.9,3.7,3.8,3.6,3.5,3.55,3.48,3.5,3.42"></span>
+        </dd>
+      </dl>
+    </div>
+  </div>
+  <p class="small">
+    <code>metric__spark</code> 只是一个<strong>槽位</strong> —— 它不关心里面放什么。
+    上面放的是 <code>sparkline</code>，也可以什么都不放（前三块就没有）。
+    槽位存在但为空时不留空白高度，所以同一个网格里有没有走势图都能对齐。
+  </p>
+
+  <h2 class="rule-top">反例：缺数填 0</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad=".metric__value|glyphs|=4">
+      <h3>错：拿 0 冒充“没有”</h3>
+      <dl class="metric">
+        <dt class="metric__label">经营活动现金流净额</dt>
+        <dd class="metric__value">0.00</dd>
+        <dd class="metric__foot"><span class="metric__note">本期未披露</span></dd>
+      </dl>
+      <p class="small">
+        值有 4 个字形。读者读到的是“现金流为零”—— 一个具体的、错误的结论。
+      </p>
+    </div>
+    <div class="cmp__pane cmp__good" data-good=".metric__value|glyphs|=1">
+      <h3>对：留 <code>—</code> 并说明原因</h3>
+      <dl class="metric metric--null">
+        <dt class="metric__label">经营活动现金流净额</dt>
+        <dd class="metric__value">—</dd>
+        <dd class="metric__foot"><span class="metric__note">本期未披露</span></dd>
+      </dl>
+      <p class="small">
+        值只有 1 个字形（U+2014），且 <code>metric--null</code> 把颜色降到 tertiary。
+      </p>
+    </div>
+  </div>
+  <p class="small">
+    <strong>为什么不能靠“变淡”表达缺数</strong>：颜色淡了但字还在，读者仍会读那个数字。
+    缺数的正确表达是<strong>不给出数字</strong>，再加一句为什么。
+    <br>
+    ⚠️ 也不要用 <code>opacity</code> 压淡 —— <code>--text-tertiary</code> 的 5.33:1
+    已经是地板，再乘一次透明度就跌破 4.5。改令牌才是对的做法。
+  </p>
+
+  <h2 class="rule-top">两条边界</h2>
+  <p class="small">
+    ① <strong>本组件不做格式化</strong>。千分位、小数位、单位换算都由数据侧决定 ——
+    CSS 不知道“1,294.06”和“1294.06”哪个对。库能保证的是
+    <strong>等宽对齐</strong>与<strong>不换行</strong>。
+    <br>
+    ② <strong>不要把 delta 写进 <code>metric__value</code></strong>。值里混进变化量之后，
+    等宽对齐就失效了（数字位数不同），而且读屏会念成一串。
+    变化量放 <code>metric__foot</code>。
+  </p>
+</main>
+<script src="../../09-assets/sparkline/sparkline.js"></script>
+</body>
+</html>

package/02-primitives/metric/metric.css

@@ -0,0 +1,157 @@
+/* ============================================================================
+   Metric — 指标块（一个标签 + 一个值 + 一句上下文）
+   ============================================================================
+   一句话：**报表里“一个数”的最小完整单元**。
+   财务页、监控页、详情页顶部的 KPI 行，都是由它排出来的。
+
+   🔴 为什么它是组件，而不是几个工具类
+   ----------------------------------------------------------------------------
+   因为“一个数”有四件事必须一起做对，少一件就会在真实报表里出错：
+
+     ① 数字要**等宽**（用等宽字族，不靠比例字体的默认）—— 否则上下两行的数位对不齐，
+        竖着扫一眼比大小这件事就废了；这是「财务表格」与「装饰表格」的分界
+     ② 单位要**分离**成槽位 —— 拼进字符串后（"1,294.06亿元"）既不能单独调样式，
+        也没法让数字右对齐时把单位甩在外面
+     ③ **缺数是一等状态** —— 不能渲染成 0、不能留空、不能只把字变淡；
+        必须给出“为什么没有”（本库的既有纪律，见 04-recipes/detail-page 的 null 变体）
+     ④ 变化的**方向**要能表达 —— 所以它给 delta 留了位置，但它自己不管颜色
+
+   这四件事里任意一件交给调用方“记得做”，就会漏。本库在同一条路上栽过：
+   `table__unit` 的括号是组件加的，不是要求每个调用方记得加。
+
+   🔴 为什么推荐 `<dl>`
+   ----------------------------------------------------------------------------
+   “标签—值”在 HTML 里有现成语义：术语 + 描述。用 `<dl>` 读屏会念
+   「营业总收入 1,294.06 亿元 +12.4% 同比」，用 `<div>` 只会念一串没有关系的词。
+
+   本文件的 CSS **只认类名，不认标签** —— 用 `<div>` 也能正常渲染
+   （兼容既有页面），但 demo 与文档一律示范 `<dl>`。
+
+   🔴 缺数怎么写
+   ----------------------------------------------------------------------------
+     <dl class="metric metric--null">
+       <dt class="metric__label">经营现金流</dt>
+       <dd class="metric__value">—</dd>            <!-- U+2014，不是 0、不是空 -->
+       <dd class="metric__foot"><span class="metric__note">本期未披露</span></dd>
+     </dl>
+
+   `metric--null` 只做一件事：把值的颜色降到 tertiary、去掉字重。
+   它**不隐藏**这块 —— 版面塌掉比显示“没有”更糟。
+   ========================================================================= */
+
+.metric {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-1);
+  margin: 0;                       /* dl 自带外边距，会破坏网格对齐 */
+  min-width: 0;                    /* flex/grid 子项默认不缩，长标签会撑破列 */
+}
+
+/* dl 的 dd 默认有 40px 起始缩进 —— 只在结构与类名同时出现时清掉 */
+.metric > dd {
+  margin-inline-start: 0;
+}
+
+.metric__label {
+  margin: 0;
+  font-size: var(--fs-xs);
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--text-secondary);
+  letter-spacing: var(--tracking-normal);   /* 小字号中文给一点字距更清；令牌在暗色段有另一档 */
+}
+
+/* 值：这一块的全部意义所在 */
+.metric__value {
+  margin: 0;
+  font-family: var(--mono);   /* 等宽字族 ⇒ 数字天然对齐，不需要 tabular-nums */
+  font-size: var(--fs-xl);
+  font-weight: 600;
+  line-height: var(--lh-tight);
+  color: var(--text-primary);
+  /* 🔴 数字**默认不换行**，但极端情况下必须能断，否则顶破视口。
+     第一版写的是 `white-space: nowrap`，RTL 下阿语膨胀 1.3× 后
+     整个值变成一串装不下的长词，横向溢出 212px（实测）。
+     `overflow-wrap: anywhere` 的语义正好是「只有当一个词装不下整行时才断」——
+     正常列宽下 `1,294.06` 绝不会被拆开，只有真的放不下才断。 */
+  white-space: normal;
+  overflow-wrap: anywhere;
+  /* 值 + 单位按 flex 排，**允许整体换行**（单位可以整块掉到下一行）。 */
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+}
+
+/* 单位：与数字同基线、小一号、次要色
+   ⚠️ 用 margin-inline-start 而不是空格字符：
+      空格在等宽字族里也占一格，而 4 位数 × 十几行就会看出错位。 */
+.metric__unit {
+  margin-inline-start: 0.3em;
+  font-size: var(--fs-sm);
+  font-weight: 400;
+  color: var(--text-secondary);
+  /* 🔴 单位**允许换行**。第一版给了 `nowrap`，结果 RTL 下阿语膨胀 1.3×
+     直接顶破列宽（实测溢出 379px）：`nowrap` 会把单位变成列的**最小内容宽度**，
+     网格再想收也收不了。
+     `overflow-wrap: anywhere` 是给「一个词长过整列」的兜底 ——
+     阿/希的单位词本来就比中文长，不加它还是会溢出。 */
+  white-space: normal;
+  overflow-wrap: anywhere;
+  min-width: 0;               /* flex 子项默认不缩 —— 不写这句上面的换行等于没写 */
+}
+
+/* 脚下那行：通常放一个 delta + 一个说明词（"同比" / "较上季"）*/
+.metric__foot {
+  margin: 0;
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: var(--sp-2);
+  font-size: var(--fs-xs);
+  line-height: 1.5;
+  color: var(--text-tertiary);
+}
+
+.metric__note {
+  color: var(--text-tertiary);
+}
+
+/* 迷你图槽位：放 sparkline 之类。给它一点上间距，避免贴着数字 */
+.metric__spark {
+  margin-block-start: var(--sp-1);
+  color: var(--text-tertiary);
+}
+
+/* 缺数：值降到 tertiary、去字重，但**仍然占位**
+   ⚠️ 不要用 opacity —— 它会让对比度跌破 4.5（--text-tertiary 已经是 5.33 的地板，
+      再乘一次透明度就没了）。改令牌才是对的做法。 */
+.metric--null .metric__value {
+  color: var(--text-tertiary);
+  font-weight: 400;
+}
+
+/* ---------------------------------------------------------------- 字号三档
+   三档够了。出现第四档说明 KPI 行的层级没规划好
+   （与 badge / card 的判断标准一致）。 */
+.metric--lg .metric__value {
+  font-size: var(--fs-2xl);
+}
+
+.metric--sm .metric__value {
+  font-size: var(--fs-md);
+  font-weight: 500;
+}
+
+/* ---------------------------------------------------------------- 网格容器
+   KPI 行几乎总是成排出现，把重复的栅格收进来一次。
+   ⚠️ `minmax(min(100%, 12rem), 1fr)` 里的 `min(100%, …)` 不是冗余：
+      窄容器（手机单列、侧栏）下 12rem 会比可用宽度还大，
+      没有这层 min() 就会横向溢出 —— 这是 auto-fit 最常见的翻车方式。 */
+.metric-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 12rem), 1fr));
+  gap: var(--sp-5) var(--sp-5);
+  margin: 0;
+  padding: 0;
+  list-style: none;     /* 用 <ul> 包 metric 时不想看到圆点 */
+}

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);