agentcss 0.0.0-stage → 0.11.3

package/03-patterns/tabs/tabs.js

@@ -0,0 +1,307 @@
+/*
+ * tabs.js — Tabs 的行为层（APG: Tabs Pattern）
+ *
+ * 语法刻意用 ES5（无箭头函数 / const / let / 模板字符串）——
+ * 精简档（某项目 上的 WebView）版本不确定。
+ *
+ * 🔴 键盘契约（照抄 Radix / APG，不是我的设计）
+ * ------------------------------------------------
+ *     Tab        进入组时落在**当前选中**的 tab；再按 Tab 走到面板
+ *     ArrowRight 下一个 tab（并激活）
+ *     ArrowLeft  上一个 tab（并激活）
+ *     ArrowDown  下一个（纵向）
+ *     ArrowUp    上一个（纵向）
+ *     Home       第一个 tab（并激活）
+ *     End        最后一个 tab（并激活）
+ *
+ * 🔴 roving tabindex（本文件最容易写错的地方）
+ * ------------------------------------------------
+ * 一组 tab 里**只有一个** tabindex="0"，其余全是 -1。
+ * 为什么要这样：否则 Tab 键会**逐个穿过所有 tab** ——
+ * 一排 5 个 tab 要按 5 次 Tab 才能进内容。
+ * roving 让整组只占**一个** Tab 停靠点，组内用方向键移动。
+ *
+ *   ⚠️ 而且这个唯一的 "0" 必须**跟着选中项走** ——
+ *      激活某个 tab 时要把它的 tabindex 设为 0、把上一个设为 -1。
+ *      只在初始化时设一次是最常见的 bug：用户激活第 3 个 tab 后，
+ *      Tab 键还是会回到第 1 个。
+ */
+(function () {
+  'use strict';
+
+  /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
+  var flEmit = function (el, name, detail) {
+    if (!el || !el.dispatchEvent) return null;
+    var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+    var ev = null;
+    /* 老 WebView 没有 CustomEvent 构造函数 ⇒ 兜底走 createEvent（理由见文件头）*/
+    if (typeof window.CustomEvent === 'function') {
+      try {
+        ev = new window.CustomEvent(type, {
+          detail: detail || null, bubbles: true, cancelable: false
+        });
+      } catch (e) { ev = null; }
+    }
+    if (!ev) {
+      try {
+        ev = document.createEvent('CustomEvent');
+        ev.initCustomEvent(type, true, false, detail || null);
+      } catch (e2) { return null; }
+    }
+    el.dispatchEvent(ev);
+    return ev;
+  };
+  /* ==== BEHAVIOR INJECT END: emit ==== */
+
+  /* ==== BEHAVIOR INJECT BEGIN: roving ==== */
+  var flRoving = function (opts) {
+    var opt = opts || {};
+    var container = opt.container;
+    var all = opt.items || function () { return []; };
+    var movable = opt.movable || all;
+    var nodeOf = opt.nodeOf || function (x) { return x; };
+    var axis = opt.axis || 'x';
+    var loop = opt.loop !== false;
+    var homeEnd = opt.homeEnd !== false;
+    /* ④ tabindex: false ⇒ 只要步进，不要 roving tabindex（理由见文件头）*/
+    var roveTab = opt.tabindex !== false;
+    var onMove = opt.onMove || function () {};
+
+    /* ① tabindex 落在**全集**上：禁用项也必须是 -1，否则 Tab 会停上去 */
+    function rove(target) {
+      if (!roveTab) return target;
+      var l = all() || [];
+      for (var i = 0; i < l.length; i++) {
+        var n = nodeOf(l[i]);
+        if (!n || !n.setAttribute) continue;
+        n.setAttribute('tabindex', n === target ? '0' : '-1');
+      }
+      return target;
+    }
+
+    /* ② 取模循环：对负数、对 |d| > n 都对 */
+    function step(i, d) {
+      var n = (movable() || []).length;
+      if (!n) return -1;
+      if (loop) return ((i + d) % n + n) % n;
+      var t = i + d;
+      return (t < 0 || t >= n) ? -1 : t;
+    }
+
+    function indexOfNode(node) {
+      var l = movable() || [];
+      for (var i = 0; i < l.length; i++) {
+        if (nodeOf(l[i]) === node) return i;
+      }
+      return -1;
+    }
+
+    function onKey(e) {
+      var l = movable() || [];
+      if (!l.length) return;
+      var i = indexOfNode(e.target);
+      if (i < 0) return;
+      var k = e.key;
+      var next = -1;
+      var reason = 'step';
+
+      if (axis === 'y') {
+        if (k === 'ArrowDown') next = step(i, 1);
+        else if (k === 'ArrowUp') next = step(i, -1);
+      } else {
+        if (k === 'ArrowRight') next = step(i, 1);
+        else if (k === 'ArrowLeft') next = step(i, -1);
+      }
+      if (homeEnd && k === 'Home') { next = 0; reason = 'home'; }
+      else if (homeEnd && k === 'End') { next = l.length - 1; reason = 'end'; }
+
+      if (next < 0 || next >= l.length) return;
+      /* ③ 只拦事件，不替组件决定移动后做什么 */
+      if (e.preventDefault) e.preventDefault();
+      if (e.stopPropagation) e.stopPropagation();
+      onMove(next, l[next], reason);
+    }
+
+    if (container) container.addEventListener('keydown', onKey);
+
+    /* ⚠️ 只暴露有人用的东西（理由见文件头）*/
+    return {
+      rove: rove,
+      step: step,
+      indexOf: indexOfNode,
+      destroy: function () {
+        if (container) container.removeEventListener('keydown', onKey);
+      },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: roving ==== */
+
+  function toArray(x) { return Array.prototype.slice.call(x); }
+
+  /* 🔴 刻意不用 Element.closest / Array.filter ——
+     它们是 ES5 之后才有的（closest 还要 ES6 风格的 DOM 扩展），
+     而本库要跑在**精简档（某项目 上的 WebView）**上，版本不确定。
+     同目录的 list.js / overlay.js 也都避开这两个 ——
+     一致比方便重要。 */
+  function closest(el, sel) {
+    while (el && el.nodeType === 1) {
+      if (matches(el, sel)) return el;
+      el = el.parentNode;
+    }
+    return null;
+  }
+
+  function matches(el, sel) {
+    var fn = el.matches || el.msMatchesSelector || el.webkitMatchesSelector;
+    return fn ? fn.call(el, sel) : false;
+  }
+
+  function filter(list, fn, self) {
+    var out = [];
+    for (var i = 0; i < list.length; i++) {
+      if (fn.call(self, list[i], i, list)) out.push(list[i]);
+    }
+    return out;
+  }
+
+  function Tabs(root, opts) {
+    this.root = root;
+    this.opts = opts || {};
+    this.list = root.querySelector('[role="tablist"]');
+    if (!this.list) return;
+    this.tabs = toArray(this.list.querySelectorAll('[role="tab"]'));
+    this.panels = toArray(root.querySelectorAll('[role="tabpanel"]'));
+    this.vertical = this.list.getAttribute('aria-orientation') === 'vertical';
+    // automatic（默认）：方向键移动即激活；manual：只移动焦点
+    this.manual = root.classList.contains('tabs--manual');
+
+    /* 方向键游走走 roving 核（01-tokens/behavior/roving.js）。
+       ⭐ 两个列表必须分开：
+         items   = 全部 tab（含禁用）⇒ tabindex 也要给禁用项设成 -1，
+                   否则 Tab 会停在禁用项上
+         movable = 可用 tab ⇒ 方向键只在这里面移动，跳过禁用项 */
+    var self = this;
+    this.roving = flRoving({
+      container: this.list,
+      items: function () { return self.tabs; },
+      movable: function () { return self.focusables(); },
+      axis: this.vertical ? 'y' : 'x',
+      onMove: function (i, tab) {
+        if (self.manual) { self.rove(tab); tab.focus(); }   // manual：只移焦点
+        else self.select(tab, true);                        // automatic：移动即激活
+      },
+    });
+    this.bind();
+  }
+
+  Tabs.prototype.enabled = function (tab) {
+    return tab.getAttribute('aria-disabled') !== 'true';
+  };
+
+  Tabs.prototype.focusables = function () {
+    return filter(this.tabs, this.enabled, this);
+  };
+
+  /* 🔴 roving 的核心：把 tabindex="0" 给 active，其余 -1
+     —— 实现已移到 roving 核，这里只做转发（规则只有一份）。 */
+  Tabs.prototype.rove = function (target) {
+    if (!this.roving) return;
+    this.roving.rove(target);
+  };
+  Tabs.prototype.select = function (tab, focusIt) {
+    if (!this.enabled(tab)) return;
+    for (var i = 0; i < this.tabs.length; i++) {
+      var on = this.tabs[i] === tab;
+      this.tabs[i].setAttribute('aria-selected', on ? 'true' : 'false');
+      // APG：tab 的 id 与 panel 的 aria-labelledby / aria-controls 互指
+      var pid = this.tabs[i].getAttribute('aria-controls');
+      var panel = pid ? document.getElementById(pid) : null;
+      if (!panel) {
+        // 没有 aria-controls 时按顺序对应
+        panel = this.panels[i] || null;
+      }
+      if (panel) {
+        if (on) {
+          panel.removeAttribute('hidden');
+          panel.classList.add('tabs__panel--enter');
+        } else {
+          panel.setAttribute('hidden', '');
+          panel.classList.remove('tabs__panel--enter');
+        }
+      }
+    }
+    this.active = tab;
+    this.rove(tab);
+    if (focusIt) tab.focus();
+    flEmit(this.root, 'fl-change',
+           { value: tab.getAttribute('data-value') || tab.id, tab: tab });
+    if (typeof this.opts.onChange === 'function') {
+      this.opts.onChange(tab.getAttribute('data-value') || tab.id, tab);
+    }
+  };
+
+  Tabs.prototype.bind = function () {
+    var self = this;
+
+    // 初始化：激活 aria-selected="true" 的那个；没有就选第一个
+    var initial = null;
+    for (var i = 0; i < this.tabs.length; i++) {
+      if (this.tabs[i].getAttribute('aria-selected') === 'true') {
+        initial = this.tabs[i];
+        break;
+      }
+    }
+    this.select(initial || this.tabs[0], false);
+
+    // 点击
+    this.list.addEventListener('click', function (e) {
+      var tab = closest(e.target, '[role="tab"]');
+      if (!tab || !self.list.contains(tab)) return;
+      if (!self.enabled(tab)) return;
+      self.select(tab, false);
+    });
+
+    // 键盘
+    this.list.addEventListener('keydown', function (e) {
+      var tab = closest(e.target, '[role="tab"]');
+      if (!tab) return;
+      var k = e.key;
+
+      /* ↑↓←→ 与 Home / End 已由 roving 核接管（见构造函数里的 flRoving），
+         这里只剩 Enter / Space。
+         ⚠️ automatic 模式下**不要** preventDefault —— 交给 button 的默认行为
+         （它会触发 click ⇒ select）。只有 manual 模式才需要显式激活：
+         那种模式下方向键只移了焦点，面板还没切。 */
+      if (k !== 'Enter' && k !== ' ' && k !== 'Spacebar') return;
+      if (self.manual) {
+        e.preventDefault();
+        self.select(tab, false);
+      }
+    });
+  };
+
+  // 暴露
+  window.Tabs = Tabs;
+
+  // 自动初始化：<div class="tabs" data-tabs>
+  //
+  // ⚠️ 这里**曾经**写过 `onChange: el.getAttribute('data-on-change')` ——
+  //    它把一个**字符串**塞进了要求函数的位置，`select()` 里
+  //    `typeof this.opts.onChange === 'function'` 永远不成立
+  //    ⇒ 这个属性从第一天起就**从来没有生效过**，而且没有任何报错。
+  //    现已删除：自动初始化不接回调，要收通知请用 `fl-change` 事件
+  //    （见 API.md「事件」一节）。
+  function init() {
+    var nodes = document.querySelectorAll('[data-tabs]');
+    for (var i = 0; i < nodes.length; i++) {
+      nodes[i].tabsInstance = new Tabs(nodes[i], {});
+    }
+  }
+
+  // @autoinit: [data-tabs] —— 扫属性自动建实例（详见 API.md「自动初始化」）
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/03-patterns/tooltip/README.md

@@ -0,0 +1,96 @@
+# tooltip · 文字提示
+
+补充说明，**不是**主要信息的载体。
+
+## 🔴 一条铁律：tooltip 不承载必要信息
+
+触屏设备**没有 hover** ⇒ tooltip 在手机上等于不存在。
+凡是"用户必须知道"的内容，绝不能只放在 tooltip 里。
+
+**怎么自己查**：tooltip 里的文字必须与触发元素的可见文字或 `aria-label`
+**不重复**。重复了，就说明它本该直接可见。
+
+> 这是本库唯一一条"用法约束"级别的规则，也是最常被违反的一条。
+
+## 结构（JS 生成，不要手写）
+
+```js
+Tooltip.attach(按钮, '说明文字', 'top');
+```
+
+生成的结构：
+
+```html
+<button data-tooltip="说明文字" aria-describedby="tt1">…</button>
+<div id="tt1" class="tooltip tooltip--top" role="tooltip">说明文字</div>
+```
+
+| 参数 | 取值 | 说明 |
+|---|---|---|
+| `el` | Element | 触发元素 |
+| `text` | string | 纯文本（用 `textContent` 写入，**天然免疫注入**）|
+| `place` | `top`（默认）/ `bottom` / `inset-inline-start` / `inset-inline-end` | 方位 |
+
+公开 API 只有 `Tooltip.attach()`，**没有** `show` / `hide` ——
+显隐由 hover / focus / click 自动驱动。
+
+## 🔴 用 `aria-describedby`，不是 `aria-label`
+
+tooltip 与触发元素的关系是**描述**，不是**命名**。
+`aria-label` 会**覆盖**元素本来的可访问名——按钮上的文字会被抹掉。
+
+```js
+el.setAttribute('aria-describedby', cur ? (cur + ' ' + id) : id);
+```
+
+⚠️ 已有 `aria-describedby` 时是**追加空格**，不是覆盖 —— 可能同时有多个描述。
+
+`role="tooltip"` + `aria-live="polite"`：内容变化时读屏会念出来。
+
+## 键盘与触屏
+
+| 输入 | 行为 |
+|---|---|
+| 键盘 `focus` | 出（**键盘必须可达**，只做 hover 等于对键盘用户不存在）|
+| `Esc` | 关（WCAG 1.4.13 Content on Hover or Focus）|
+| 触屏 `click` | 切换开/关 |
+
+## 🔴 定位前必须先入 DOM
+
+游离元素的 `getBoundingClientRect()` **全是 0**。
+
+实测踩过：`top` 方位的气泡与锚点完全重叠 —— 原因就是先量尺寸、
+后插进 DOM。正确顺序是**先挂上去、藏起来量，量完再显示**。
+
+## 显隐靠 `data-state`，别写 `display`
+
+```css
+.tooltip[data-state="open"] { … }
+```
+
+JS 只切`data-state`，显隐与动画全交给 CSS。
+写 `style.display` 会把过渡动画彻底干掉。
+
+## 降级
+
+| 场景 | 处理 |
+|---|---|
+| `prefers-color-scheme: dark` | 已适配 |
+| `prefers-reduced-motion: reduce` | 已关闭动效 |
+| 无 `(hover: hover) and (pointer: fine)` | 只保留点击触发 |
+
+## 成熟度：beta（两条行为债，如实列出）
+
+契约里标的是 `beta`，两条债都记在这儿，**别当stable 用**：
+
+| 债 | 含义 | 现在能做什么 |
+|---|---|---|
+| `dismissable:manual` | 关闭逻辑是手写的，不是统一机制 | 点击/`Esc` 能关，但**点击外部空白不关** |
+| `focus-return:manual` | 焦点归位是手写的 | 关闭后焦点**不一定**回到触发元素 |
+
+要接统一行为层，得先清这两条债。
+
+## 门禁
+
+`05-audit/tooltip-check.js`（契约 `gates` 里登记的唯一一道）——
+覆盖 `aria-describedby` 关联、`Esc` 关闭、触屏点击三条。

package/03-patterns/tooltip/demo.html

@@ -0,0 +1,78 @@
+<!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>tooltip · 文字提示 · frontend-lib</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/focus-ring.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="../../02-primitives/button/button.css">
+<link rel="stylesheet" href="tooltip.css">
+<style>
+.row { display: flex; gap: var(--sp-4); flex-wrap: wrap; align-items: center; }
+.pad { padding: var(--sp-9) 0; }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+<h1>tooltip · 文字提示</h1>
+<p class="note">
+  ⛔ <strong>tooltip 不承载必要信息</strong> —— 触屏没有 hover，
+  只放在 tooltip 里的内容等于不存在。
+  <br>✅ 键盘 focus 也会出 · <code>Esc</code> 能关 · 用
+  <code>aria-describedby</code> 关联（不是 aria-label：那个是「名字」）。
+</p>
+
+<h2>1 · 键盘可达（Tab 聚焦即出）</h2>
+<div class="row pad">
+  <button class="btn" id="b1">悬停/聚焦我</button>
+  <span class="btn btn--ghost" id="b2" tabindex="0">可聚焦的说明文字</span>
+</div>
+
+<h2>2 · 四个方位</h2>
+<div class="row pad">
+  <button class="btn" id="p-top">上方</button>
+  <button class="btn" id="p-bottom">下方</button>
+  <button class="btn" id="p-left">左侧</button>
+  <button class="btn" id="p-right">右侧</button>
+</div>
+
+<h2>3 · 🔴 错误示范：把必要信息只放在 tooltip 里</h2>
+<p class="note">
+  下面这个按钮的 tooltip 文字是「删除」，与按钮可见文字完全相同
+  ⇒ 说明它<strong>没有提供额外信息</strong>，只是重复 ⇒ 应该删掉 tooltip，
+  或改成真正的补充说明。
+  <br>契约里有一条判据专门抓这个（<code>tooltip 不承载必要信息</code>）。
+</p>
+<div class="row pad">
+  <button class="btn" id="bad" data-bad-example="1">删除</button>
+</div>
+
+<h2>4 · 正确示范：补充说明</h2>
+<div class="row pad">
+  <button class="btn" id="good">导出 CSV</button>
+</div>
+
+</main>
+
+<script src="tooltip.js"></script>
+<script>
+(function () {
+  Tooltip.attach(document.getElementById('b1'), '这是补充说明：点击后会进入批量模式');
+  Tooltip.attach(document.getElementById('b2'), '聚焦也会出现，不必依赖鼠标');
+  Tooltip.attach(document.getElementById('p-top'), '出现在上方', 'top');
+  Tooltip.attach(document.getElementById('p-bottom'), '出现在下方', 'bottom');
+  Tooltip.attach(document.getElementById('p-left'), '出现在左侧', 'left');
+  Tooltip.attach(document.getElementById('p-right'), '出现在右侧', 'right');
+  /* 🔴 反例：tooltip 文字 = 按钮可见文字 ⇒ 没有额外信息 */
+  Tooltip.attach(document.getElementById('bad'), '删除');
+  /* ✅ 正例：提供了额外信息 */
+  Tooltip.attach(document.getElementById('good'), '导出当前筛选结果，含表头；UTF-8 编码');
+})();
+</script>
+</body>
+</html>

package/03-patterns/tooltip/tooltip.css

@@ -0,0 +1,89 @@
+/* ============================================================================
+   tooltip.css — 文字提示（B3 /
+   ============================================================================
+   ⭐ 一条铁律：**tooltip 不承载必要信息**。
+
+     触屏设备**没有 hover** ⇒ tooltip 在手机上等于不存在。
+     ⇒ 凡是"用户必须知道"的内容，绝不能只放在 tooltip 里。
+     ⇒ 判据：tooltip 里的文字必须与触发元素的可见文字/aria-label **不重复**，
+        否则说明它承载了本该可见的信息。
+
+   另外：
+     · **键盘必须可达**（focus 时也要能出）
+     · `Esc` 必须能关（WCAG 1.4.13 Content on Hover or Focus）
+   ============================================================================ */
+
+.tooltip {
+  position: absolute;
+  z-index: var(--z-raised);
+  max-width: 260px;
+  padding: var(--sp-2) var(--sp-3);
+  background: var(--tooltip-bg);          /* 深色气泡（浅色作用域下） */
+  color: var(--tooltip-fg);
+  font-size: var(--fs-xs);
+  line-height: 1.5;
+  border-radius: var(--r-sm);
+  /* 描边用 inset 环而不用 border：同色时零像素，暗色下正好贴在原边线上。
+     `--shadow-2` 是公开令牌，不写兜底字面量（兜底 = 第二份真值，见 I-7）。 */
+  box-shadow: inset 0 0 0 1px var(--tooltip-border), var(--shadow-2);
+  /* 文字不被选中（否则会误选） */
+  user-select: none;
+  /* 淡入用透明度，不用 display（display 会让读屏读不到）*/
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 120ms var(--ease-out, ease);
+  pointer-events: none;                  /* 不挡住下面的元素 */
+}
+
+.tooltip[data-state="open"] {
+  opacity: 1;
+  visibility: visible;
+}
+
+/* ---------- 箭头（小三角，用 CSS 画，不引图片）---------- */
+.tooltip::after {
+  content: "";
+  position: absolute;
+  border: 5px solid transparent;
+}
+
+/* 上下是**块轴**（RTL 不翻转，写物理没问题）；
+   左右是**内联轴**（RTL 会翻转 ⇒ 必须写逻辑属性）。
+   🔴 0.4.2 修：原本写物理 border-left/right-color。小三角是
+   "给哪条边上色、尖角就指向反方向" —— RTL 下左边变成内联终点 ⇒ 尖角指反，
+   指向气泡外侧而不是锚点（I-12 同一类：不报错，只是看着不对）。 */
+.tooltip--top::after {
+  top: 100%; inset-inline-start: 50%;
+  margin-inline-start: -5px;
+  border-top-color: var(--tooltip-bg);
+}
+.tooltip--bottom::after {
+  bottom: 100%; inset-inline-start: 50%;
+  margin-inline-start: -5px;
+  border-bottom-color: var(--tooltip-bg);
+}
+.tooltip--inset-inline-start::after {
+  inset-inline-start: 100%; top: 50%;
+  margin-top: -5px;
+  border-inline-start-color: var(--tooltip-bg);
+}
+.tooltip--inset-inline-end::after {
+  inset-inline-end: 100%; top: 50%;
+  margin-top: -5px;
+  border-inline-end-color: var(--tooltip-bg);
+}
+
+/* 原有一段 `@media (prefers-color-scheme: dark)`，已改为令牌驱动：
+   主题能挂在容器上之后，media 只反映系统偏好（RFC-THEME-SCOPE D5）。 */
+
+/* ---------- 减弱动效：不要淡入动画 ---------- */
+@media (prefers-reduced-motion: reduce) {
+  .tooltip { transition: none; }
+}
+
+/* ---------- 悬停显示：只对真能悬停的设备 ----------
+   🔴 触屏上 hover 会"粘住" ⇒ 触屏靠 JS 的 click/focus 触发。 */
+@media (hover: hover) and (pointer: fine) {
+  [data-tooltip]:hover + .tooltip,
+  [data-tooltip]:focus-visible + .tooltip { opacity: 1; visibility: visible; }
+}