agentcss 0.0.0-stage → 0.11.3

package/03-patterns/drawer/drawer.css

@@ -0,0 +1,129 @@
+/* ============================================================================
+   drawer.css — 抽屉（D2 /
+   ============================================================================
+   依据：APG Dialog 模式（Drawer 是从侧边滑入的 Dialog）
+
+   ⭐ 与 dialog 的差别只有"从哪进来"，**三条硬要求完全一样**：
+     ① **焦点陷阱**：Tab 不能跑到抽屉外
+     ② **Esc 关闭**
+     ③ ⭐ **关闭后焦点归位**（回到触发它的按钮）
+        —— 这条最容易漏，且**影响最大**：
+           键盘用户被"扔"回页面顶部，得重新 Tab 一遍。
+
+   ⚠️ 抽屉是**模态**（modal）：背景必须 `inert` 或 `aria-hidden`，
+      否则读屏会同时读到抽屉与背景（"双重朗读"）。
+   ============================================================================ */
+
+.drawer-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-modal);
+  /*🔴 改：原来是写死的 rgba(0,0,0,.42)——
+     暗色模式下遮罩明显偏黑（暗色下 --scrim 是 0.62 的黑，
+     而写死的 .42 在深底上几乎看不出来）。
+     overlay.css 与 nav.css 都用 var(--scrim)，只有这里漏了 ⇒
+     同一套库里三个遮罩表现不一致。
+     统一走令牌后，暗色跟随自动生效。 */
+  background: var(--scrim);
+  display: flex;
+  /* 抽屉从右侧滑入（可改成 left / top / bottom）*/
+  justify-content: flex-end;
+}
+
+.drawer-backdrop[hidden] { display: none; }
+
+.drawer {
+  width: min(420px, 92vw);
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  background: var(--surface);
+  border-inline-start: 1px solid var(--border-decor);
+  box-shadow: var(--shadow-2);
+  /* 焦点在抽屉里时，浏览器不会自动滚进视野 ⇒ 手动处理 */
+  overflow: hidden;
+}
+
+.drawer--left  { border-inline-start: 0; border-inline-end: 1px solid var(--border-decor); }
+.drawer--top   { width: 100%; height: min(60vh, 420px); border-inline-start: 0;
+                border-bottom: 1px solid var(--border-decor); }
+.drawer--bottom { width: 100%; height: min(60vh, 420px); border-inline-start: 0;
+                border-top: 1px solid var(--border-decor); }
+
+/* ---------- 头 ---------- */
+.drawer__head {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-3);
+  padding: var(--sp-4);
+  border-bottom: 1px solid var(--border-decor);
+  flex: 0 0 auto;
+}
+
+.drawer__title {
+  flex: 1 1 auto;
+  margin: 0;
+  font-size: var(--fs-lg);
+  font-weight: 600;
+}
+
+.drawer__close {
+  flex: 0 0 auto;
+  width: 44px;                 /* 🔴 命中区（关闭按钮是独立目标，用 44）*/
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: 0;
+  border-radius: var(--r-sm);
+  color: var(--text-secondary);
+  font-size: 20px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.drawer__close:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .drawer__close:hover { background: var(--surface-sunken); }
+}
+
+/* ---------- 体 / 脚 ---------- */
+.drawer__body {
+  flex: 1 1 auto;
+  padding: var(--sp-4);
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.drawer__foot {
+  flex: 0 0 auto;
+  display: flex;
+  gap: var(--sp-2);
+  justify-content: flex-end;
+  padding: var(--sp-4);
+  border-top: 1px solid var(--border-decor);
+}
+
+/* ---------- 进出场动画 ----------
+   ⚠️ 用 transform 而不是 left/right（合成层动画，不触发重排）。
+   ⚠️ 动画只做"位移 + 少量透明度"，**不做大幅缩放** —— 那看起来廉价。 */
+@media (prefers-reduced-motion: no-preference) {
+  /* --ease-drawer：滑入面板专用曲线（不是通用的 --ease-out） */
+  .drawer--right  { animation: drawer-in-right  220ms var(--ease-drawer, ease); }
+  .drawer--left   { animation: drawer-in-left   220ms var(--ease-drawer, ease); }
+  .drawer--top    { animation: drawer-in-top    220ms var(--ease-drawer, ease); }
+  .drawer--bottom { animation: drawer-in-bottom 220ms var(--ease-drawer, ease); }
+
+  @keyframes drawer-in-right  { from { transform: translateX(16px); opacity: .6; } }
+  @keyframes drawer-in-left   { from { transform: translateX(-16px); opacity: .6; } }
+  @keyframes drawer-in-top    { from { transform: translateY(-16px); opacity: .6; } }
+  @keyframes drawer-in-bottom { from { transform: translateY(16px); opacity: .6; } }
+}
+
+/* 退场（JS 设这个属性，等动画结束再移除节点）*/
+.drawer[data-state="leaving"] { opacity: 0; transition: opacity 160ms var(--ease-out, ease); }

package/03-patterns/drawer/drawer.js

@@ -0,0 +1,258 @@
+/**
+ * drawer.js — 抽屉（D2 /
+ *
+ * 依据：APG Dialog 模式
+ *   ① **焦点陷阱**：Tab 在抽屉内循环
+ *   ② **Esc 关闭**
+ *   ③ ⭐ **关闭后焦点归位**（回到触发它的元素）
+ *   ④ 背景 inert（避免读屏"双重朗读"）
+ *   ⑤ 锁滚动（背景不该跟着滚）
+ *
+ * ⚠️ 与 dialog 的差别只是"从哪进来"，契约完全一样。
+ *
+ * 无依赖 · ES5
+ */
+(function (global) {
+  '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: focus-return ==== */
+  var flFocusReturn = function (opts) {
+    var opt = opts || {};
+    var saved = null;
+
+    return {
+      save: function () {
+        var a = document.activeElement;
+        saved = (a && a !== document.body && a.focus) ? a : null;
+        return saved;
+      },
+
+      restore: function () {
+        var target = saved;
+        /* ⚠️ 见文档 ②：不判 contains 的话，元素被移除后 focus() 不报错
+           但焦点不动 ⇒ 用户以为还回去了，其实掉在 body 上。 */
+        if (!target || !document.contains(target)) target = opt.fallback || null;
+        if (!target) { saved = null; return false; }
+        try {
+          target.focus();
+        } catch (e) {
+          saved = null;
+          return false;
+        }
+        var ok = document.activeElement === target;
+        saved = null;   /* 见文档 ③ */
+        return ok;
+      },
+
+      target: function () { return saved; },
+      clear: function () { saved = null; },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: focus-return ==== */
+
+  var FOCUSABLE = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+  ].join(',');
+
+  var lockCount = 0, savedScroll = 0, inerts = [];
+
+  function lockScroll() {
+    if (lockCount === 0) {
+      savedScroll = window.pageYOffset || 0;
+      document.body.style.overflow = 'hidden';
+    }
+    lockCount++;
+  }
+  function unlockScroll() {
+    lockCount = Math.max(0, lockCount - 1);
+    if (lockCount === 0) {
+      document.body.style.overflow = '';
+      window.scrollTo(0, savedScroll);
+    }
+  }
+
+  function setBackgroundInert(on) {
+    if (on) {
+      if (inerts.length) return;
+      /* ⚠️ 只把 body 的**直接子元素**（除抽屉容器）设 inert。
+         抽屉本身也在 body 下 ⇒ 必须排除，否则刚打开就 inert 了。 */
+      Array.prototype.forEach.call(document.body.children, function (n) {
+        if (n.hasAttribute && n.hasAttribute('data-drawer-host')) return;
+        if (n.tagName === 'SCRIPT' || n.tagName === 'STYLE') return;
+        n.inert = true;
+        n.setAttribute('aria-hidden', 'true');
+        inerts.push(n);
+      });
+    } else {
+      inerts.forEach(function (n) {
+        n.inert = false;
+        n.removeAttribute('aria-hidden');
+      });
+      inerts = [];
+    }
+  }
+
+  function open(opt) {
+    opt = opt || {};
+    var place = opt.place || 'right';
+
+    /* ⭐ 记住"打开那一刻的焦点"—— 关闭时要还回去。
+       （必须在插入 DOM **之前**记录，否则会记到新节点上。）
+       走 focus-return 核（01-tokens/behavior/focus-return.js）：
+       抽屉没有 fallback —— 打开它的元素若被删了，就维持现状不动，
+       不假装"还回去了"。 */
+    var fr = flFocusReturn({});
+    fr.save();
+
+    var host = document.createElement('div');
+    host.className = 'drawer-backdrop';
+    host.setAttribute('data-drawer-host', '');
+    if (opt.label) host.setAttribute('aria-label', opt.label);
+
+    var d = document.createElement('aside');
+    d.className = 'drawer drawer--' + place;
+    d.setAttribute('role', 'dialog');
+    d.setAttribute('aria-modal', 'true');
+    if (!d.id) d.id = 'drawer-' + (new Date()).getTime();
+    if (opt.title) d.setAttribute('aria-labelledby', d.id + '-title');
+    else d.setAttribute('aria-label', opt.label || '抽屉');
+    d.tabIndex = -1;              /* 焦点陷阱的兜底落点 */
+
+    var head = document.createElement('div');
+    head.className = 'drawer__head';
+    var h = document.createElement('h2');
+    h.className = 'drawer__title';
+    h.id = d.id + '-title';
+    h.textContent = opt.title || '';
+    var closeBtn = document.createElement('button');   /* 🔴 不能叫 close：
+     下方有 `function close()`，函数声明会**提升并覆盖**同名变量，
+     导致上面所有 close.addEventListener 绑在函数上（静默失败）。 */
+    closeBtn.className = 'drawer__close';
+    closeBtn.type = 'button';
+    closeBtn.setAttribute('aria-label', '关闭');
+    closeBtn.textContent = '\u00D7';
+    head.appendChild(h);
+    head.appendChild(closeBtn);
+
+    var body = document.createElement('div');
+    body.className = 'drawer__body';
+    if (typeof opt.content === 'string') body.innerHTML = opt.content;
+    else if (opt.content) body.appendChild(opt.content);
+
+    d.appendChild(head);
+    d.appendChild(body);
+
+    if (opt.actions && opt.actions.length) {
+      var foot = document.createElement('div');
+      foot.className = 'drawer__foot';
+      opt.actions.forEach(function (a) {
+        var b = document.createElement('button');
+        b.type = 'button';
+        b.className = 'btn' + (a.variant ? ' btn--' + a.variant : '');
+        b.textContent = a.label;
+        b.addEventListener('click', function () {
+          if (a.onClick) a.onClick(close);
+          if (a.keepOpen !== true) close();
+        });
+        foot.appendChild(b);
+      });
+      d.appendChild(foot);
+    }
+
+    host.appendChild(d);
+    document.body.appendChild(host);
+
+    setBackgroundInert(true);
+    lockScroll();
+
+    /* 初始焦点：优先指定项，其次第一个可聚焦元素，最后容器本身 */
+    var f = d.querySelectorAll(FOCUSABLE);
+    if (opt.initialFocus) {
+      var t = d.querySelector(opt.initialFocus);
+      if (t) t.focus();
+      else (f[0] || d).focus();
+    } else {
+      (f[0] || d).focus();
+    }
+
+    function onKey(e) {
+      var k = e.key;
+      /* ② Esc 关闭 */
+      if (k === 'Escape' || k === 'Esc') { e.preventDefault(); close(); return; }
+      if (k !== 'Tab') return;
+      /* ① 焦点陷阱：Tab / Shift+Tab 在抽屉内循环 */
+      var list = [].slice.call(d.querySelectorAll(FOCUSABLE))
+        .filter(function (x) { return x.offsetParent !== null; });
+      if (!list.length) { e.preventDefault(); d.focus(); return; }
+      var first = list[0], last = list[list.length - 1];
+      if (e.shiftKey && (document.activeElement === first || document.activeElement === d)) {
+        e.preventDefault(); last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault(); first.focus();
+      }
+    }
+    function onBackdropClick(e) { if (e.target === host) close(); }
+
+    d.addEventListener('keydown', onKey);
+    host.addEventListener('click', onBackdropClick);
+    closeBtn.addEventListener('click', function () { close(); });
+
+    var closed = false;
+    function close() {
+      if (closed) return;
+      closed = true;
+      d.setAttribute('data-state', 'leaving');
+      d.removeEventListener('keydown', onKey);
+      host.removeEventListener('click', onBackdropClick);
+      setBackgroundInert(false);
+      unlockScroll();
+      /* 动画结束再移除；reduced-motion 下没有 transition ⇒ 兜底定时器 */
+      var done = false;
+      function remove() {
+        if (done) return; done = true;
+        if (host.parentNode) host.parentNode.removeChild(host);
+      }
+      d.addEventListener('transitionend', remove, { once: true });
+      setTimeout(remove, 320);
+      /* ⭐ ③ 焦点归位：回到打开抽屉的那个元素（核里已处理
+         "元素被移除 / 不可聚焦"两种降级，都不抛错）。 */
+      fr.restore();
+      /* 抽屉用完即毁 ⇒ 必须在 host 被移出 DOM **之前**派发，否则没人收得到 */
+      flEmit(d, 'fl-close', null);
+      if (opt.onClose) opt.onClose();
+    }
+
+    return { el: d, close: close };
+  }
+
+  global.Drawer = { open: open };
+})(window);

package/03-patterns/dropdown/README.md

@@ -0,0 +1,78 @@
+# dropdown · 下拉菜单
+
+依据 **APG（ARIA Authoring Practices）Menu Button** 模式。
+
+## 🔴 APG 的四条键盘契约（缺一条就不算合规）
+
+| 键 | 行为 |
+|---|---|
+| `↑` `↓` | 在**项**之间移动 |
+| `Esc` | 关闭，并把焦点**还给按钮** |
+| `Tab` | 关闭菜单（焦点移到下一个元素）|
+| `Enter` / `Space` | 激活当前项 |
+
+## ⚠️ 另有两条容易漏的
+
+- **关闭后焦点必须归位** —— 不归位，键盘用户在页面里迷路
+- **菜单项命中区 ≥ 44px** —— 密集列表也必须够大（WCAG 2.5.5AAA）
+
+## 结构
+
+⚠️ **类名前缀是 `dd__`，不是 `dropdown__`**；标记是 `data-dd-*`。
+
+```html
+<div class="dd">
+  <button class="dd__btn" data-dd-btn aria-haspopup="menu" aria-expanded="false">
+    <span>操作</span><span class="dd__caret" aria-hidden="true"></span>
+  </button>
+  <div class="dd__menu" data-dd-menu role="menu">
+    <button class="dd__item" role="menuitem" data-value="edit">编辑</button>
+    <hr class="dd__sep" data-dd-sep role="separator">
+    <button class="dd__item" role="menuitem" data-value="del">删除</button>
+  </div>
+</div>
+```
+
+| 部件 | 说明 |
+|---|---|
+| `.dd` | 根 |
+| `.dd__btn` / `[data-dd-btn]` | 触发按钮 |
+| `.dd__menu` / `[data-dd-menu]` | 菜单本体，**必需** |
+| `.dd__item` | 菜单项，带 `data-value` |
+| `.dd__sep` / `[data-dd-sep]` | 分隔线 |
+| `.dd__check` | 多选勾选位 |
+| `.dd--end` | 菜单右对齐 |
+
+## 启用
+
+```js
+const dd = Dropdown.create(元素);
+```
+
+- `[data-dd-btn]` 找不到时**退回第一个 `<button>`**（省事的写法也能跑）
+- `[data-dd-menu]` 找不到 → **直接抛错**
+
+## 🔴 `role="menu"` 要么全设要么全不设
+
+```js
+// APG：菜单要么全 aria-hidden，要么全不设 —— 不能半吊子
+menu.setAttribute('role', 'menu');
+```
+
+`aria-hidden` 打了一半在个别项上，读屏会读到一半就断掉。
+
+## 状态写在 DOM 属性上
+
+`data-state` / `data-value`，**不用 class 切换** —— 这是全库 INVARIANT I-8
+（状态必须活在 DOM 属性上），也是门禁会查的东西。
+
+## 成熟度：beta（两条行为债，如实列出）
+
+| 债 | 现在的后果 |
+|---|---|
+| `focus-return:manual` | 关闭后归位是手写的，不是统一机制 |
+| `typeahead:gap` | **没有类型搜索** —— APG 的 Menu Button 不硬性要求，但列表长时体验缺失 |
+
+## 门禁
+
+`05-audit/dropdown-check.js`

package/03-patterns/dropdown/demo.html

@@ -0,0 +1,101 @@
+<!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>dropdown · 下拉菜单 · 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="dropdown.css">
+<style>
+.pad { padding: var(--sp-4) 0 var(--sp-9); }
+.log {
+    margin-top: var(--sp-4); padding: var(--sp-3);
+    background: var(--surface-sunken); border-radius: var(--r-sm);
+    font-family: var(--font-mono, monospace); font-size: var(--fs-xs);
+    color: var(--text-secondary); min-height: 2.6em;
+  }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+<h1>dropdown · 下拉菜单</h1>
+<p class="note">
+  依据 <strong>APG Menu Button</strong>：<code>↑↓</code> 移动 ·
+  <code>Esc</code> 关闭并<strong>把焦点还给按钮</strong> ·
+  <code>Tab</code> 关闭 · <code>Enter</code>/<code>Space</code> 激活 ·
+  <code>Home</code>/<code>End</code> 跳首末。
+  <br>⚠️ 菜单项 <code>tabindex="-1"</code>：<strong>不参与 Tab 序列</strong>，
+  因为 Tab 的语义是「关闭菜单」。
+</p>
+
+<h2>1 · 基本用法（试试键盘）</h2>
+<div class="pad">
+  <div class="dd" id="d1">
+    <button class="dd__btn" data-dd-btn>操作 <span class="dd__caret"></span></button>
+    <ul class="dd__menu" data-dd-menu hidden>
+      <li data-value="edit">编辑</li>
+      <li data-value="copy">复制</li>
+      <li data-value="paste">粘贴</li>
+      <li data-dd-sep></li>
+      <li data-value="del" aria-disabled="true">删除（不可用）</li>
+    </ul>
+  </div>
+  <div class="log" id="log">（选中项会显示在这里）</div>
+</div>
+
+<h2>2 · 带勾选（选中性不只靠颜色）</h2>
+<div class="pad">
+  <div class="dd" id="d2">
+    <button class="dd__btn" data-dd-btn>排序方式 <span class="dd__caret"></span></button>
+    <ul class="dd__menu" data-dd-menu hidden>
+      <li data-value="date"><span class="dd__check" data-check>✓</span>按日期</li>
+      <li data-value="name"><span class="dd__check" data-check></span>按名称</li>
+      <li data-value="size"><span class="dd__check" data-check></span>按大小</li>
+    </ul>
+  </div>
+</div>
+
+<h2>3 · 靠右对齐（窄屏不出屏）</h2>
+<div class="pad">
+  <div class="dd dd--end" id="d3">
+    <button class="dd__btn" data-dd-btn>账号 <span class="dd__caret"></span></button>
+    <ul class="dd__menu" data-dd-menu hidden>
+      <li data-value="profile">个人资料</li>
+      <li data-value="billing">账单</li>
+      <li data-value="signout">退出登录</li>
+    </ul>
+  </div>
+</div>
+
+</main>
+
+<script src="dropdown.js"></script>
+<script>
+(function () {
+  var log = document.getElementById('log');
+  function onSelect(v) { log.textContent = '选中：' + v; }
+
+  Dropdown.create(document.getElementById('d1'), { onSelect: onSelect, label: '操作' });
+  Dropdown.create(document.getElementById('d2'), { onSelect: onSelect, label: '排序方式' });
+  Dropdown.create(document.getElementById('d3'), { onSelect: onSelect, label: '账号' });
+
+  /* 选中性：点中某项后把 ✓ 挪过去（不是只改颜色）*/
+  document.getElementById('d2').__dd = true;
+  var d2 = document.getElementById('d2');
+  d2.addEventListener('click', function (e) {
+    var li = e.target.closest('li[data-value]');
+    if (!li) return;
+    d2.querySelectorAll('[data-check]').forEach(function (s) { s.textContent = ''; });
+    var c = li.querySelector('[data-check]');
+    if (c) c.textContent = '✓';
+  });
+})();
+</script>
+</body>
+</html>