agentcss 0.0.0-stage → 0.11.2

package/02-primitives/progress/progress.css

@@ -0,0 +1,172 @@
+/* ============================================================================
+   progress — 进度条
+   ============================================================================
+   为什么需要它（通行系统的必备件）
+   ---------------------------------------------------------------------------
+   「已知进度」和 skeleton 的「未知进度」是两件事：
+     · 进度**已知**（上传 3MB 到了 60%）⇒ 用 progress 给出**可预期**的反馈
+     · 进度**未知**（不知道要多久）  ⇒ 用 skeleton（本库已有）
+   ⭐ 两者混用是常见错误：不知道进度却给一个假的百分比，比不给更糟。
+
+   参照：Carbon ProgressBar / Ant Design Progress / MUI LinearProgress
+
+   设计要点
+   ---------------------------------------------------------------------------
+   ① **纯 CSS，无 JS**（用 `--progress` 自定义属性驱动）
+   ② 四种形态：线形 / 环形 / 不确定（indeterminate）/ 步骤分段
+   ③ 动画尊重 prefers-reduced-motion（WCAG 2.3.3，本库铁律）
+   ④ 暗色用令牌，不硬编码
+   ⑤ **零硬编码色**（准入清单第 ④ 条）
+   ============================================================================ */
+
+/* ============================================================================
+   1 · 线形进度条（最常用）
+   ============================================================================ */
+.progress {
+  display: block;
+  width: 100%;
+  height: var(--progress-h);
+  background: var(--surface-sunken);
+  border-radius: var(--r-full);   /* 胶囊形 */
+  overflow: hidden;
+  /* ⚠️ 不用 <progress> 原生标签的原因：它在部分浏览器里无法设成胶囊形，
+     且 ::-webkit-progress-value 的圆角行为不一致。 */
+}
+
+.progress__bar {
+  display: block;
+  height: 100%;
+  width: var(--progress, 0%);
+  background: var(--accent);
+  border-radius: inherit;
+  /* ⭐ 用 ease-out 而不是 linear —— 进度条是"向前"的 feel，
+     匀速反而像卡住了。缓出更符合心理预期。 */
+  transition: width var(--progress-dur) var(--ease-out);
+}
+
+/* 语义色变体（上传失败 / 即将超时 / 已完成） */
+.progress--success .progress__bar { background: var(--success); }
+.progress--warning .progress__bar { background: var(--warning); }
+.progress--danger  .progress__bar { background: var(--danger); }
+
+/* 尺寸变体 */
+.progress--lg { --progress-h: 10px; }
+.progress--sm { --progress-h: 4px; }
+
+/* ============================================================================
+   2 · 环形进度（需要"占比"感时，比线形更直观）
+   ============================================================================ */
+.progress-ring {
+  display: inline-grid;
+  place-items: center;
+  position: relative;
+  width: var(--ring-size);
+  height: var(--ring-size);
+  border-radius: 50%;
+  /* ⭐ 用 conic-gradient 而非 SVG：零依赖、纯 CSS、可被令牌驱动 */
+  /* 🔴 修 bug：环形之前用 `calc(var(--progress) * 1%)`，
+     但 JS 把 --progress 设成 "72%"（**带百分号**）⇒ 72% * 1% 非法
+     ⇒ 整条 background 无效（实测 background-image: none，环完全没画出来）。
+     ⇒ 正解：环形用**无单位**的 --progress-num（JS 同时写两个变量）。 */
+  background: conic-gradient(
+    var(--accent) calc(var(--progress-num, 0) * 1%),
+    var(--surface-sunken) 0
+  );
+}
+
+.progress-ring__label {
+  /* 内圈挖空：用 surface 色的圆盘盖住中间 */
+  display: grid;
+  place-items: center;
+  width: calc(100% - var(--ring-thickness) * 2);
+  height: calc(100% - var(--ring-thickness) * 2);
+  border-radius: 50%;
+  background: var(--surface);
+  font-size: var(--fs-sm);
+  color: var(--text-primary);
+  font-variant-numeric: tabular-nums;   /* 数字等宽，不跳动 */
+}
+
+.progress-ring--success { background: conic-gradient(var(--success) calc(var(--progress-num, 0) * 1%), var(--surface-sunken) 0); }
+.progress-ring--danger  { background: conic-gradient(var(--danger)  calc(var(--progress-num, 0) * 1%), var(--surface-sunken) 0); }
+
+/* ============================================================================
+   3 · 不确定进度（不知道要多久）
+   ============================================================================
+   ⚠️ 关键：不确定时**绝不能**显示百分比数字（那是撒谎）。
+   ============================================================================ */
+.progress--indeterminate .progress__bar {
+  width: 35%;
+  animation: progress-slide 1.1s var(--ease-out) infinite;
+}
+
+@keyframes progress-slide {
+  0%   { transform: translateX(-100%); }
+  100% { transform: translateX(340%); }
+}
+
+/* ============================================================================
+   4 · 步骤分段（"第 3 步 / 共 5 步"这类已知流程）
+   ============================================================================ */
+.progress-steps {
+  display: flex;
+  gap: var(--sp-1);
+}
+.progress-steps__seg {
+  flex: 1;
+  height: var(--progress-h, 4px);
+  background: var(--surface-sunken);
+  border-radius: var(--r-full);
+}
+.progress-steps__seg--done { background: var(--accent); }
+.progress-steps__seg--current { background: var(--accent); opacity: 0.55; }
+
+/* ============================================================================
+   5 · 无障碍
+   ============================================================================
+   进度条必须：
+     · role="progressbar" + aria-valuenow/min/max（或不确定时不设 valuenow）
+     · 内部文字对读屏隐藏（避免念出无意义的百分比）
+   ============================================================================ */
+.progress[aria-busy='true'] { cursor: progress; }
+
+/* ============================================================================
+   减少动态效果（prefers-reduced-motion: reduce）
+   ============================================================================
+   ⚠️⚠️ 这里改过一次。**第一版是错的**（看截图后指出）：
+
+   第一版做法：动画停掉，留一个 33% 宽的条子，但仍保留 `::after` 的扫光渐变
+   ⇒ 结果是**一条明显的两色硬边界**（左边浅、右边深，边界很锐）
+   ⇒ 看起来像"卡在某个位置"，反而比分段线形更糟。
+
+   ⭐ 通行做法（某设计系统 Horizon 设计系统）：
+     "This option displays a **static progress bar, set at 25% completion**"
+     —— 固定 25% 的**单色**条，**没有任何两色边界**。
+
+   为什么单色更好：
+     · 不"卡住了"的错觉（两色边界看起来像"已经走了 33%"）
+     · 边界不锐利，不刺激（前庭功能敏感者对强边界尤其敏感）
+     · 语义仍然清楚：有一条短条 = 正在处理
+   ============================================================================ */
+@media (prefers-reduced-motion: reduce) {
+  .progress__bar { transition: none; }
+
+  .progress--indeterminate .progress__bar {
+    animation: none;
+    transform: none;
+    /* 固定 25%（对齐 Horizon）—— 表示"在处理，但不知道到哪" */
+    width: 25%;
+    /* ⭐ 关键：扫光层**整个去掉**，不留两色边界 */
+    background: var(--accent);
+  }
+  .progress--indeterminate .progress__bar::after {
+    /* 不用 display:none（那会留下 ::after 参与合成的空盒），
+       改成 transparent —— 盒子还在，但完全不可见，边界消失 */
+    content: none;
+  }
+
+  /* 语义色变体在 reduce 下也要保持单色 */
+  .progress--indeterminate.progress--success .progress__bar { background: var(--success); }
+  .progress--indeterminate.progress--warning .progress__bar { background: var(--warning); }
+  .progress--indeterminate.progress--danger  .progress__bar { background: var(--danger); }
+}

package/02-primitives/select/README.md

@@ -0,0 +1,95 @@
+# select · 自建下拉选择
+
+依据 **APG（ARIA Authoring Practices）Select-Only Combobox** 模式。
+
+## ⭐ 什么场景用、什么场景别用
+
+| 场景 | 用什么 |
+|---|---|
+| 表单提交、移动端体验 | **原生 `<select>`** |
+| 需要自定义外观（圆角/字体/阴影、选项带说明） | 本组件 |
+
+**为什么需要自建**：原生 `<select>` 在 Windows 上**无法定制样式**（下拉列表由
+系统绘制），圆角/字体/阴影全部无效 ⇒ 跨平台观感不一致。
+
+⛔ 但**表单提交**仍由本组件通过 `hidden input` 承接，`create()` 时会自己建。
+
+## 结构
+
+```html
+<div class="select">
+  <button class="select__btn" data-select-btn aria-haspopup="listbox"
+          aria-expanded="false" aria-controls="select-list-1">
+    <span class="select__value">…</span>
+    <span class="select__caret" aria-hidden="true"></span>
+  </button>
+  <ul class="select__list" data-select-list id="select-list-1" role="listbox">
+    <li class="select__opt" role="option" aria-selected="false">
+      <span class="select__opt-text">…</span>
+    </li>
+  </ul>
+</div>
+```
+
+| 部件 | 说明 |
+|---|---|
+| `.select` | 根（**必须**），`position: relative` 靠它定位列表 |
+| `[data-select-btn]` / `[data-select-list]` | **两个都必需**，缺一个 `create()` 直接抛错 |
+| `.select__value` | 按钮里显示当前值 |
+| `.select__check` | 多选时的勾选位 |
+| `.select--block` | 整块宽度（省掉 `min-width: 12rem`）|
+| `.select--end` | 列表右对齐 |
+
+⚠️ `id` 可以不写，`create()` 会自动补`select-list-N`。
+
+## 启用
+
+```js
+const sel = Select.create(元素, { multiple: false, value: 'b', label: '选项' });
+```
+
+| 参数 | 说明 |
+|---|---|
+| `multiple` | 多选（会写 `aria-multiselectable`）|
+| `value` | 初始选中项的 value |
+| `label` | 列表的 `aria-label` |
+
+## 🔴 APG 的键盘契约（三条最容易漏）
+
+| 键 | 行为 |
+|---|---|
+| 打开后焦点 | **落在选中项**（不是第一项，也不是按钮）|
+| `↑` `↓` | 循环上下移动 |
+| `Home` / `End` | 跳首/ 末 |
+| `Enter` / `Space` | 选中并关闭 |
+| `Esc` | 关闭，并**把焦点还给按钮** |
+| `Alt` + `↓` | 直接打开 |
+
+**① 为什么强调"落在选中项"**：这是 APG 明确要求的，也是最常做错的一条。
+打开后焦点在第一项，用户按一次`↓` 就跳到第二项 —— 原来选的那项被跳过了。
+
+## 类型搜索（typeahead）
+
+连续打字跳到匹配项。**原生 `<select>` 有这个能力，所以自建的必须有**。
+
+它不是在这里实现的，而是**接线**到共享微行为核
+`01-tokens/behavior/typeahead.js`（`BEHAVIOR INJECT: typeahead` 段）——
+`tabs` / `tree` 等也接同一份，所以各组件只有一半接线代码，不是各抄一遍规则。
+
+⚠️ 已知盲点（实测结论，记在 `select-check.js` 里）：
+把 `typeahead.type(k)` 那行接线删掉，门禁**会红**；
+但把 `close()` 里的 `typeahead.clear()` 删掉，**守不住**。
+⇒ 这类"接线"类缺陷目前只能靠人读，别把门禁绿当成"接线全对"。
+
+## 成熟度：beta（两条行为债，如实列出）
+
+| 债 | 现在的后果 |
+|---|---|
+| `dismissable:manual` | 点外部空白能关，但**不是统一机制** |
+| `focus-return:manual` | `Esc` 关闭后焦点能回按钮，但**不是统一机制** |
+
+接统一行为层前，别当`stable` 用。
+
+## 门禁
+
+`05-audit/select-check.js` —— 覆盖键盘契约与 ARIA 属性同步。

package/02-primitives/select/demo.html

@@ -0,0 +1,121 @@
+<!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>select · 下拉选择 · 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="select.css">
+<style>
+.pad { padding: var(--sp-3) 0 var(--sp-8); }
+.log {
+    margin-top: var(--sp-3); padding: var(--sp-3);
+    background: var(--surface-sunken); border-radius: var(--r-sm);
+    font-family: var(--mono); font-size: var(--fs-xs);
+    color: var(--text-secondary); min-height: 3em;
+  }
+label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+
+<h1>select · 下拉选择</h1>
+<p class="note">
+  依据 <strong>APG Select-Only Combobox</strong>。四条最容易漏的：
+  <br>① 打开后焦点落在<strong>选中项</strong>（不是第一项）
+  <br>② <code>↑↓</code> 循环 · <code>Home</code>/<code>End</code> 首末 ·
+  <code>Enter</code> 选中并关闭
+  <br>③ <code>Esc</code> 关闭且焦点<strong>还给按钮</strong>
+  <br>④ <strong>类型搜索</strong>：连续打字跳到匹配项
+  <br>⚠️ <code>hidden input</code> 承接表单值（自建组件最容易漏的）
+</p>
+
+<h2>1 · 基本（默认选中第二项）</h2>
+<div class="pad">
+  <label class="f" for="b1">投资主体</label>
+  <div class="select" id="s1">
+    <button class="select__btn" data-select-btn type="button" id="b1">
+      <span class="select__value">请选择</span>
+      <span class="select__caret"></span>
+    </button>
+    <ul class="select__list" data-select-list hidden>
+      <li class="select__opt" data-value="hk" role="option">
+        <span class="select__check"></span><span class="select__opt-text">港股通</span></li>
+      <li class="select__opt" data-value="a" role="option">
+        <span class="select__check"></span><span class="select__opt-text">A 股主板</span></li>
+      <li class="select__opt" data-value="star" role="option">
+        <span class="select__check"></span><span class="select__opt-text">科创板</span></li>
+      <li class="select__opt" data-value="gem" role="option">
+        <span class="select__check"></span><span class="select__opt-text">创业板</span></li>
+      <li class="select__opt" data-value="bond" role="option" aria-disabled="true">
+        <span class="select__check"></span><span class="select__opt-text">债券（暂不支持）</span></li>
+      <li class="select__opt" data-value="fund" role="option">
+        <span class="select__check"></span><span class="select__opt-text">Fund 基金</span></li>
+    </ul>
+    <input type="hidden" name="market">
+  </div>
+  <div class="log" id="log">（选中的值会显示在这里，也会写进 hidden input）</div>
+</div>
+
+<h2>2 · 多选</h2>
+<div class="pad">
+  <div class="select select--block" id="s2">
+    <button class="select__btn" data-select-btn type="button">
+      <span class="select__value">请选择板块</span>
+      <span class="select__caret"></span>
+    </button>
+    <ul class="select__list" data-select-list hidden>
+      <li class="select__opt" data-value="a" role="option">
+        <span class="select__check"></span><span class="select__opt-text">消费</span></li>
+      <li class="select__opt" data-value="b" role="option">
+        <span class="select__check"></span><span class="select__opt-text">半导体</span></li>
+      <li class="select__opt" data-value="c" role="option">
+        <span class="select__check"></span><span class="select__opt-text">医药</span></li>
+    </ul>
+  </div>
+</div>
+
+<h2>3 · 禁用 + 靠右对齐</h2>
+<div class="pad">
+  <div class="select select--end" id="s3">
+    <button class="select__btn" data-select-btn type="button" disabled>
+      <span class="select__value">暂不可用</span>
+      <span class="select__caret"></span>
+    </button>
+    <ul class="select__list" data-select-list hidden>
+      <li class="select__opt" data-value="x" role="option">
+        <span class="select__check"></span><span class="select__opt-text">选项 X</span></li>
+    </ul>
+  </div>
+</div>
+
+</main>
+
+<script src="select.js"></script>
+<script>
+(function () {
+  var log = document.getElementById('log');
+  var s1 = Select.create(document.getElementById('s1'), {
+    label: '投资市场',
+    value: 'a',                       /* 默认选中 A 股主板 */
+    placeholder: '请选择市场',
+    onChange: function (v, text) {
+      var hidden = document.querySelector('#s1 input[type=hidden]');
+      log.textContent = 'value=' + v + '  文字=「' + text + '」  hidden=' +
+                        (hidden ? hidden.value : '(无)') + '  [aria-current 项带 ✓]';
+    },
+  });
+
+  Select.create(document.getElementById('s2'), {
+    label: '板块', multiple: true, placeholder: '请选择板块',
+  });
+  Select.create(document.getElementById('s3'), { label: '不可用' });
+})();
+</script>
+</body>
+</html>

package/02-primitives/select/select.css

@@ -0,0 +1,151 @@
+/* ============================================================================
+   select.css — 自建下拉选择（E1 /
+   ============================================================================
+   依据：APG（ARIA Authoring Practices）Select-Only Combobox 模式
+
+   ⭐ 为什么必须自建，而不是直接用原生 <select>：
+     原生 `<select>` 在 Windows 上**无法定制样式**（下拉列表由系统绘制），
+     圆角/字体/阴影全部无效 ⇒ 跨平台观感不一致。
+     ⛔ 但**表单提交、移动端体验**仍应优先用原生 ——
+        本组件专用于「需要自定义外观的场景」，并保留 hidden input 承接表单值。
+
+   ── APG Select 的键盘契约（三条最容易漏）──
+     ① 打开后焦点**落在选中项**（不是第一项，也不是按钮）
+     ② ↑↓ 循环 · Home/End 跳首末 · **Enter/Space 选中并关闭**
+     ③ **Esc 关闭并把焦点还给按钮** · Alt+↓ 直接打开
+
+   ⚠️ 还有一条**类型搜索**：连续打字跳到匹配项（原生 select 有，必须做）。
+   ============================================================================ */
+
+.select {
+  position: relative;
+  display: inline-block;
+  min-width: 12rem;
+}
+
+.select--block { display: block; min-width: 0; }
+.select--block .select__btn { width: 100%; }
+
+/* ---------- 按钮（视觉上就是 select）---------- */
+.select__btn {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  width: 100%;
+  min-height: 44px;                  /* 🔴 命中区（AAA）*/
+  padding: 0 var(--sp-3);
+  background: var(--surface);
+  color: var(--text-primary);
+  border: 1px solid var(--border-control);
+  border-radius: var(--r-sm);
+  font: inherit;
+  font-size: var(--fs-sm);
+  text-align: start;
+  cursor: pointer;
+}
+
+.select__btn:focus-visible {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+  outline-offset: var(--focus-ring-offset);
+}
+
+.select__btn[aria-expanded="true"] { border-color: var(--accent); }
+
+/* 禁用态 */
+.select__btn[disabled] {
+  background: var(--surface-sunken);
+  color: var(--text-tertiary);
+  cursor: not-allowed;
+}
+
+.select__value {
+  flex: 1 1 auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 占位态：还没选值时颜色更淡，且**文字要说清要选什么** */
+.select__value--placeholder { color: var(--text-tertiary); }
+
+.select__caret {
+  flex: 0 0 auto;
+  width: 0;
+  height: 0;
+  border: 4px solid transparent;
+  border-top-color: currentColor;
+  margin-top: 3px;
+  transition: transform 140ms var(--ease-out, ease);
+}
+
+.select__btn[aria-expanded="true"] .select__caret {
+  transform: rotate(180deg);
+  margin-top: -3px;
+}
+
+/* ---------- 列表 ---------- */
+.select__list {
+  position: absolute;
+  top: calc(100% + var(--sp-1));
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  z-index: var(--z-raised);
+  max-height: 15rem;
+  overflow-y: auto;
+  margin: 0;
+  padding: var(--sp-1);
+  list-style: none;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-sm);
+  box-shadow: var(--shadow-2);
+}
+
+.select__list[hidden] { display: none; }
+
+.select__opt {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-2);
+  min-height: 44px;                  /* 🔴 命中区（AAA，与 dropdown 同）*/
+  padding: 0 var(--sp-3);
+  border-radius: var(--r-xs);
+  color: var(--text-primary);
+  font-size: var(--fs-sm);
+  cursor: pointer;
+}
+
+/* ⭐ 焦点与"当前选中"是两件事，用**两个**视觉区分：
+   · [data-state="active"]  = 键盘游标在该项（高亮，由 JS 同步）
+   · [aria-selected=true] = 已被选中的值（勾 + 粗体） */
+.select__opt[data-state="active"] { background: var(--accent-soft); }
+.select__opt[aria-selected="true"] { font-weight: 600; }
+
+@media (hover: hover) and (pointer: fine) {
+  .select__opt:hover { background: var(--surface-sunken); }
+}
+
+.select__opt[aria-disabled="true"] {
+  color: var(--text-tertiary);
+  background: var(--surface-sunken);
+  cursor: not-allowed;
+}
+
+/* 勾：选中的标志（**形状线索**，不只靠颜色）*/
+.select__check {
+  flex: 0 0 auto;
+  width: 1em;
+  font-weight: 700;
+  color: var(--accent);
+}
+
+.select__opt-text { flex: 1 1 auto; }
+
+/* 窄屏：贴右对齐，避免出屏 */
+@media (max-width: 30rem) {
+  .select--end .select__list { inset-inline-start: auto; inset-inline-end: 0; min-width: 12rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .select__caret { transition: none; }
+}