agentcss 0.24.2 → 0.25.0

package/01-tokens/README.md

@@ -255,7 +255,7 @@ node ai/cli.js tree   [--set=light|dark] [--cat=color]   # 第二种
 1. **必须排在 `tokens.css` 之后** —— 同权重靠顺序定胜负。
 2. **不许写进 `tokens.css`** —— 那会让六个靠词法读 CSS 的工具静默读错
    （`contrast` / `gen-ai-contract` / `gen-tokens-tree` / `token-audience` /
-   `theme-sync`）。真实事故见 `internal/ERRORS.md` 的 E137。
+   `theme-sync`）。真实事故：一条 `@layer` 让六个工具同时读错，且都没有报错。
 3. 选择器是 `:root[data-market="intl"]` (0,2,0)，**不是** `:where(...)` (0) ——
    `:where()` 抢不过 `:root` 的 (0,1,0)，写了等于没写（E135）。
 

package/01-tokens/tokens.css

@@ -651,7 +651,9 @@
    用 @media 是目前兼容性最好的做法。
    ---------------------------------------------------------------- */
 
-@media (prefers-color-scheme: dark) {
+/* `screen and` 承重：暗色是屏幕概念，纸没有深色模式。
+   缺了它，暗色令牌在 print 里照样生效 ⇒ 浅字配被丢弃的深底。 */
+@media screen and (prefers-color-scheme: dark) {
   /* ========================================================================
      第二次修正（上一版被 真机实测否决）
      ------------------------------------------------------------------------
@@ -839,6 +841,7 @@
 /* === END: light-via-attr === */
 
 /* === BEGIN: dark-via-attr（由 05-audit/theme-sync.py 生成，勿手改）=== */
+@media screen {
 :root[data-theme="dark"],
 [data-theme="dark"] {
   --raw-accent: #7AA9DE;
@@ -913,6 +916,7 @@
   --warning: var(--raw-warning);
   --warning-bg: var(--raw-warning-bg);
 }
+}
 /* === END: dark-via-attr === */
 
 /* 🔴 涨跌口径切换（`[data-market="intl"]`）**不在本文件里**，在 `01-tokens/market.css`。
@@ -1065,3 +1069,65 @@ input[type="submit"],
      为什么是 44px：**WCAG 2.5.5 Target Size (Level AAA)** 要求 44×44 CSS px。
      ⚠️ 注意区分：
        · WCAG 2.5.8（AA 级）只要 24×24 */
+
+/* ============================================================================
+   打印（print）—— 纸没有主题：暗色已被上面的 `@media screen and` 关在屏幕里。
+   剩下的只有一处：实心控件的字。打印丢弃背景色，而它们的
+   `--text-on-accent` 是 #ffffff ⇒ 白纸白字（实测产物 2.30:1）。
+   改这两个令牌一处，好过改 8 个组件。
+   ========================================================================== */
+/* ==========================================================================
+   X · 打印（工具类 + 全局策略）
+   放这里而不是新建 print.css：新 .css 会连带 dist / docs / README 一串连锁。
+   完整说明（收窄层级的理由、为什么没写 thead、代价）见 docs/PRINT.md。
+   ========================================================================== */
+
+/* 屏幕上隐藏、纸上显示（块级元素用）。 */
+.print-only { display: none; }
+
+@media print {
+  :root {
+    color-scheme: light;          /* 表单控件/滚动条别跟着系统去暗色 */
+    --text-on-accent: #15181c;
+    --text-on-solid:  #15181c;
+  }
+
+  /* 使用者控制器：加 .no-print 的元素不上纸。全库唯一的 !important ——
+     不加就永远可能被使用者自己写的 display 覆盖，等于没提供这个能力。 */
+  .no-print { display: none !important; }
+  .print-only { display: block; }
+
+  /* 打印前展开折叠内容 —— 不展开 = 静默截断（页数正常、内容少一半）。
+     ⚠️ 必须带组件根前缀：tokens.css 在 head 里最先加载，同特异性的规则会被
+     组件 CSS 覆盖（实测：不加前缀时 PDF 与改动前逐字节相同）。
+     accordion 三条缺一不可。逐条理由见 docs/PRINT.md。 */
+  .tabs .tabs__panel[hidden] { display: block; }
+  .accordion .accordion__panel[hidden] {
+    display: grid !important;      /* ① 它有 display:none !important */
+    grid-template-rows: 1fr;       /* ② 收起态是 0fr */
+    visibility: visible;           /* ③ 它还有 visibility:hidden（缺这条就一个字不印） */
+  }
+
+  /* 浮层与纯导航。不用裸 button（accordion 标题在 button 里），
+     不动 .btn / .upload（文档页会空、表单控件有状态）。见 docs/PRINT.md。 */
+  .toast, .tooltip, .popover, .skeleton,
+  .tabs__list, .nav__list, .nav__toggle, .pagination,
+  .accordion__marker { display: none !important; }
+
+  /* ⚠️ 模态的遮罩规则**不在这里**，在 03-patterns/overlay/overlay.css。
+     原因不是洁癖：`.dialog-backdrop { position: static }` 写在这里会被
+     overlay.css 里同特异性的 `position: fixed` 盖掉 —— 规则写了、不生效、
+     不报错（E254 的同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
+
+  /* 不跨页切断。代价：高于半页的卡片会被整体推到下一页 ⇒ 页数可能变多。 */
+  tr, img, figure, svg,
+  .card, .metric, .sparkline, .splot { break-inside: avoid; }
+
+  /* 退出开关：高块想省纸就加这个类（标定表见 docs/PRINT.md）。
+     必须写在上一条之后 —— 同特异性靠顺序取胜，不靠 !important。 */
+  .print-allow-break { break-inside: auto; }
+
+  /* ⚠️ 这里**没有** `p, li, blockquote { orphans/widows }` ——
+     裸标签选择器会改掉宿主页面所有段落（`bleed-gate` 的硬红线）。
+     孤行寡行只在库里自己的文档容器内生效，见 `04-recipes/report/report.css`。 */
+}

package/01-tokens/typography.css

@@ -48,7 +48,7 @@ body {
      20 页当灰底说明块手写同一个值，只有 1 页用 warning ⇒ 取众数。 */
 .note {
   /* 🔴 去掉 `border-left: 3px solid`。
-     评审意见"很蠢的左边侧边阴影" —— 说得对：
+     左边那条侧边阴影是多余的：
        ① 它是**纯装饰**，不传达信息（颜色已经表达了）
        ② 3px 竖条在浅底上形成一条硬边，视觉噪声比信息量大
        ③ 满库 13 处同款，一眼就能看出"模板感" —— 这正是 AI 味的来源。

package/02-primitives/button/demo.html

@@ -22,6 +22,14 @@
                 transition: all 200ms; }
 .btn--naive:hover { filter: brightness(1.08); transform: scale(1.05); }
 .btn--naive:disabled { opacity: 0.5; }
+/* 🔴 打印：反例按钮的底色会被丢弃，白字就成了白纸白字。
+   实测（0.24.2，Chromium，printBackground:false）：产物里 6 段文字是
+   #ABABAB，对白纸 2.30:1。这里换成描边 + 正文墨色 —— 反例照样看得出
+   "它长得像按钮"，但纸上读得出来。 */
+@media print {
+  .btn--naive { background: transparent; color: var(--text-primary);
+                  outline: 1px dashed currentColor; }
+}
 </style>
 </head>
 <body class="page">

package/02-primitives/card/README.md

@@ -56,6 +56,21 @@
 | `.card--row` | 横向排列（图左文右） |
 | `.card--selected` | 选中态 |
 
+| 部件 | 用途 |
+|---|---|
+| `.card__body` | 内容区（内边距都在这里，**不是可选的**） |
+| `.card__footer` | 底部条：上边框分隔 + 两端对齐（左说明 / 右操作），字号取 `--fs-xs` |
+
+```html
+<div class="card">
+  <div class="card__body"><p>本月营收 1,280,000</p></div>
+  <div class="card__footer">
+    <span>数据截至 10 月 31 日</span>
+    <a href="/reports">查看明细</a>
+  </div>
+</div>
+```
+
 依赖：`01-tokens/tokens.css` + `01-tokens/typography.css`（正文）+
 `01-tokens/page.css`（`.wrap` / `.small` 等页面骨架）。
 

package/02-primitives/choice/README.md

@@ -47,6 +47,22 @@ input 被 `opacity:0` 覆盖后，它自己的 `outline` 你根本看不见。
 
 `:indeterminate` **只能由 JS 设置**（`el.indeterminate = true`），CSS 不影响它。
 
+### `.choice__hint`：选项的补充说明
+
+勾选框右侧、标签下方的一行小字（`--fs-xs` + `--text-tertiary`）。用于"选了这个会怎样"
+这类**必须先看再选**的说明——比如"同意后我们会给你发月度报告"。
+
+```html
+<label class="choice choice--checkbox">
+  <input class="choice__input" type="checkbox">
+  <span class="choice__label">订阅月度报告</span>
+  <span class="choice__hint">每月 1 日发一封，可随时退订</span>
+</label>
+```
+
+⚠️ 别把这段说明塞进 `aria-describedby` 之外的地方：它是**解释**，不是标签的一部分，
+读屏应该念"订阅月度报告，复选框"，再念说明。
+
 ---
 
 ## radio 组：必须 `fieldset + legend`
@@ -88,6 +104,20 @@ input 被 `opacity:0` 覆盖后，它自己的 `outline` 你根本看不见。
 
 select 用 `:focus` 不用 `:focus-visible`——和 input 一样，用户必须随时知道当前选的是哪个。
 
+结构（注意：这里的 `.select` 是**原生 select 的外壳**，与
+`02-primitives/select/select.css` 里那个自定义下拉的 `.select` **同名不同义**，
+同页面同时用两个组件会互相覆盖，详见 `05-audit/css-ownership.json`）：
+
+| 类 | 作用 |
+|---|---|
+| `.select` | 外壳（`position:relative` + `inline-flex`，给箭头定位用） |
+| `.select__control` | **原生 `<select>` 本体**，高度 44px、字号 16px 硬下限（iOS 防缩放） |
+| `.select__arrow` | 自绘箭头（必须 `pointer-events:none`，否则吃掉点击） |
+| `.select__control--auto` | 高度改 `auto`（`min-height:44px`），用于**选项文字会换行**的场合，例如多选列表式的长选项 |
+
+`.select__control--auto` 的存在理由：固定 44px 高度遇到换行文字会把第二行裁掉。
+它把 `height` 放开、`padding-block` 加到 `--sp-2`，行数变多时整块自然长高。
+
 ---
 
 ## disabled

package/02-primitives/choice/choice.css

@@ -198,7 +198,7 @@
    🔴 不做这个态，"全选"复选框就没法正确表达中间状态。 */
 .choice--checkbox .choice__input:indeterminate ~ .choice__label .choice__mark {
   /* 🔴 由「深蓝满色块」改为「白底 + accent 描边 + accent 横线」。
-     评审意见满色块"感觉比较差" —— 确实，半选塞一整块深色视觉太重。
+     满色块的问题：半选塞一整块深色，视觉太重。
      描边式同样能表达"部分选中"，且更轻。 */
   background: var(--surface);
   border-color: var(--accent);

package/02-primitives/input/README.md

@@ -122,6 +122,7 @@ python 05-audit/states.py 02-primitives/input/input.css
 | 类 | 作用 | 什么时候用 |
 |---|---|---|
 | `.field__input--sm` | 小尺寸（表格 / 紧凑栏） | 表格行内、侧栏等密度高的场景 |
+| `.field__input--textarea` | 多行：`height:auto` + `min-height:88px` + `padding:--sp-3` + `resize:vertical` | 备注、说明、地址等会换行的输入；直接拿 `.field__input` 配 `<textarea>` 会被 44px 固定高度裁掉 |
 
 > ⚠️ **demo 里没有演示这一档** —— 它是留给复用者的钩子，
 > 不是"看起来有其实没有"。要用就自己加类。

package/02-primitives/select/README.md

@@ -61,9 +61,10 @@ const sel = Select.create(元素, { multiple: false, value: 'b', label: '选项'
 | 打开后焦点 | **落在选中项**（不是第一项，也不是按钮）|
 | `↑` `↓` | 循环上下移动 |
 | `Home` / `End` | 跳首/ 末 |
-| `Enter` / `Space` | 选中并关闭 |
+| `Enter` / `Space` | 单选：选中并关闭；**多选：切换该项、列表不关** |
 | `Esc` | 关闭，并**把焦点还给按钮** |
 | `Alt` + `↓` | 直接打开 |
+| 关闭态打字 | 打开并跳到首个匹配项（同原生 `<select>`） |
 
 **① 为什么强调"落在选中项"**：这是 APG 明确要求的，也是最常做错的一条。
 打开后焦点在第一项，用户按一次`↓` 就跳到第二项 —— 原来选的那项被跳过了。
@@ -73,6 +74,41 @@ const sel = Select.create(元素, { multiple: false, value: 'b', label: '选项'
 去要求它落进 `<ul>` 会判成缺陷，实际不是。本库的判据也是按前一种断的
 （`opener-path-check` 里这条组件的 `focus` 声明为 `activedesc`）。
 
+## 多选与表单提交
+
+`multiple: true` 时：
+
+- 内部状态是**数组**，`aria-multiselectable="true"` 与 `aria-selected` 都按它写
+  —— 不是"写着多选、其实只有一个值"。
+- 按钮文本按勾选顺序拼成 `A、B、C`，过长由 CSS 截断，`title` 里保留全量。
+- **提交值一个选项一个 `input[type=hidden]`，同名多条**：
+
+  ```html
+  <input type="hidden" name="sector" value="a">
+  <input type="hidden" name="sector" value="c">
+  ```
+
+  name 依次取 `create({name})` → 根上的 `data-name` → 作者自己写的 hidden 的 name → 根元素 `id`。
+  一个都不给的话多选提交不出去，所以最后一档兜底到 `id`。
+
+- 每次值变化都会在**根元素上派发原生 `change`**（冒泡），
+  React 受控组件 / `form.reset` 监听器认的是这个；`fl-change` 仍然发，给本库自己的使用者。
+
+## API
+
+```js
+const sel = Select.create(el, { multiple: true, value: ['a', 'c'], name: 'sector' });
+
+sel.value          // 单选：字符串或 null；多选：数组
+sel.values         // 数组副本（多选常用）
+sel.value = 'b'    // 赋值后立即重绘 + 派发 change
+sel.open() / sel.close()
+sel.destroy()      // 摘掉 keydown/click/dismissable/typeahead，删掉自己补的 hidden
+```
+
+`destroy()` 之前没暴露过：动态移除组件时 `document` 上的 dismissable 监听、
+typeahead 缓冲、按钮上的 keydown 会一直留着。现在必须调，重复调是安全的。
+
 ## 类型搜索（typeahead）
 
 连续打字跳到匹配项。**原生 `<select>` 有这个能力，所以自建的必须有**。
@@ -109,4 +145,8 @@ const sel = Select.create(元素, { multiple: false, value: 'b', label: '选项'
 
 ## 门禁
 
-`05-audit/select-check.js` —— 覆盖键盘契约与 ARIA 属性同步。
+`05-audit/select-check.js` —— 覆盖键盘契约、ARIA 同步、多值与表单提交。
+
+外部审计（2026-11）指出"↑↓ 一次走两格、多选 Enter 选上又取消、空列表抛错、
+没有 destroy"之后，这四条变成了**精确断言**（一次按键只准走一格、Enter 只准切一次、
+空列表不准抛、destroy 后不准再响应）。旧断言只判"序列有变化"，所以双处理器能混过去。

package/02-primitives/select/demo.html

@@ -81,7 +81,7 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 
 <h2>2 · 多选</h2>
 <div class="pad">
-  <div class="select select--block" id="s2">
+  <div class="select select--block" id="s2" data-name="sector">
     <button class="select__btn" data-select-btn type="button">
       <span class="select__value">请选择板块</span>
       <span class="select__caret"></span>
@@ -146,16 +146,21 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 <script>
 (function () {
   var log = document.getElementById('log');
+  function show(v, text) {
+    var hidden = document.querySelector('#s1 input[type=hidden]');
+    log.textContent = 'value=' + v + '  文字=「' + text + '」  hidden=' +
+                      (hidden ? hidden.value : '(无)') + '  [aria-current 项带 ✓]';
+  }
   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 项带 ✓]';
-    },
+    onChange: show,
   });
+  /* 🔴 初始化**不派发** change（和原生 <select> 一致：挂载不是用户操作），
+     所以这里手动补一次回显 —— 否则页面一开始只有一句占位话，
+     看不出组件已经带着默认值、hidden input 也已经填好了。 */
+  show(s1.value, document.querySelector('#s1 .select__value').textContent.trim());
 
   Select.create(document.getElementById('s2'), {
     label: '板块', multiple: true, placeholder: '请选择板块',