agentcss 0.0.0-stage → 0.11.3

package/index.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="color-scheme" content="light dark">
+<title>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/page.css">
+<style>
+ul { list-style:none; padding:0; margin:0; }
+li { padding: var(--sp-2) 0; border-bottom: 1px solid var(--border-decor); }
+a { color: var(--accent); text-decoration: none; display: block; }
+a:active { background: var(--surface-sunken); }
+.first { background: var(--surface-sunken); border: 1px solid var(--border-control);
+           border-radius: var(--r-md); padding: var(--sp-4); margin: 0 0 var(--sp-5); }
+.first a { font-weight: 600; }
+</style>
+<link rel="stylesheet" href="03-patterns/nav/nav.css">
+</head>
+<body class="page page">
+<!-- 🔴 补（a11y-scan 报 landmark-one-main / region 两违规）：
+     入口页必须有 <main> 地标，并提供"跳到主内容"的 skip link
+     （WCAG 2.4.1 Bypass Blocks）—— 键盘用户按一次 Tab 就能跳过导航。
+     ⚠️ 这段必须写在**生成器**里，否则每次重新生成 index.html 都会被覆盖。 -->
+<a href="#main" class="skip">跳到主内容</a>
+<main id="main" class="wrap">
+  <h1>frontend-lib · 演示</h1>
+  <p class="lede">
+    零依赖前端组件库。全部页面可点开，<strong>在手机上直接看也可以</strong>。
+  </p>
+
+  <div class="first">
+    <p style="margin:0 0 var(--sp-2)"><strong>建议先看这个</strong></p>
+    <a href="10-review/ios/index.html">iOS 验证页（十项，Safari 专用）</a>
+    <p class="note" style="margin:var(--sp-2) 0 0">
+      按钮 / 输入框 / 开关 / 单选 / 标签页 / 折叠 / 弹窗 / 趋势图 / 徽章 / 暗色
+      —— 每节都写了「该看到什么」。
+    </p>
+  
+  <h2 class="rule-top">全部页面</h2>
+  <ul>
+    <li><a href="02-primitives/badge/demo.html"><code>02-primitives/badge/demo.html</code></a></li>
+    <li><a href="02-primitives/button/demo.html"><code>02-primitives/button/demo.html</code></a></li>
+    <li><a href="02-primitives/card/demo.html"><code>02-primitives/card/demo.html</code></a></li>
+    <li><a href="02-primitives/choice/demo.html"><code>02-primitives/choice/demo.html</code></a></li>
+    <li><a href="02-primitives/combobox/demo.html"><code>02-primitives/combobox/demo.html</code></a></li>
+    <li><a href="02-primitives/date-range/demo.html"><code>02-primitives/date-range/demo.html</code></a></li>
+    <li><a href="02-primitives/input/demo.html"><code>02-primitives/input/demo.html</code></a></li>
+    <li><a href="02-primitives/popover/demo.html"><code>02-primitives/popover/demo.html</code></a></li>
+    <li><a href="02-primitives/progress/demo.html"><code>02-primitives/progress/demo.html</code></a></li>
+    <li><a href="02-primitives/select/demo.html"><code>02-primitives/select/demo.html</code></a></li>
+    <li><a href="02-primitives/separator/demo.html"><code>02-primitives/separator/demo.html</code></a></li>
+    <li><a href="02-primitives/skeleton/demo.html"><code>02-primitives/skeleton/demo.html</code></a></li>
+    <li><a href="02-primitives/switch/demo.html"><code>02-primitives/switch/demo.html</code></a></li>
+    <li><a href="03-patterns/accordion/demo.html"><code>03-patterns/accordion/demo.html</code></a></li>
+    <li><a href="03-patterns/content/demo.html"><code>03-patterns/content/demo.html</code></a></li>
+    <li><a href="03-patterns/drawer/demo.html"><code>03-patterns/drawer/demo.html</code></a></li>
+    <li><a href="03-patterns/dropdown/demo.html"><code>03-patterns/dropdown/demo.html</code></a></li>
+    <li><a href="03-patterns/form-validation/demo.html"><code>03-patterns/form-validation/demo.html</code></a></li>
+    <li><a href="03-patterns/list/demo.html"><code>03-patterns/list/demo.html</code></a></li>
+    <li><a href="03-patterns/nav/demo.html"><code>03-patterns/nav/demo.html</code></a></li>
+    <li><a href="03-patterns/overlay/demo.html"><code>03-patterns/overlay/demo.html</code></a></li>
+    <li><a href="03-patterns/pagination/demo.html"><code>03-patterns/pagination/demo.html</code></a></li>
+    <li><a href="03-patterns/states/demo.html"><code>03-patterns/states/demo.html</code></a></li>
+    <li><a href="03-patterns/tabs/demo.html"><code>03-patterns/tabs/demo.html</code></a></li>
+    <li><a href="03-patterns/tooltip/demo.html"><code>03-patterns/tooltip/demo.html</code></a></li>
+    <li><a href="03-patterns/tree/demo.html"><code>03-patterns/tree/demo.html</code></a></li>
+    <li><a href="04-recipes/table/demo.html"><code>04-recipes/table/demo.html</code></a></li>
+    <li><a href="09-assets/bar/demo.html"><code>09-assets/bar/demo.html</code></a></li>
+    <li><a href="09-assets/echarts-adapter/demo.html"><code>09-assets/echarts-adapter/demo.html</code></a></li>
+    <li><a href="09-assets/model-viewer/demo.html"><code>09-assets/model-viewer/demo.html</code></a></li>
+    <li><a href="09-assets/sparkline/demo.html"><code>09-assets/sparkline/demo.html</code></a></li>
+    <li><a href="10-review/composition/demo.html"><code>10-review/composition/demo.html</code></a></li>
+    <li><a href="10-review/ios/index.html"><code>10-review/ios/index.html</code></a></li>
+    <li><a href="examples/react-vite/index.html"><code>examples/react-vite/index.html</code></a></li>
+  </ul>
+</div>
+</main>
+</body>
+</html>

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "agentcss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.11.3",
+  "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
+  "keywords": [
+    "css",
+    "components",
+    "mobile-web",
+    "webview",
+    "accessibility",
+    "dark-mode",
+    "rtl"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "agentcss": "./ai/cli.js"
+  },
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.html"
+    },
+    "./tokens.css": "./dist/01-tokens/tokens.css",
+    "./typography.css": "./dist/01-tokens/typography.css",
+    "./page.css": "./dist/01-tokens/page.css",
+    "./primitives/*": "./dist/02-primitives/*",
+    "./patterns/*": "./dist/03-patterns/*",
+    "./recipes/*": "./dist/04-recipes/*",
+    "./assets/*": "./dist/09-assets/*",
+    "./dist/*": "./dist/*",
+    "./src/*": "./*",
+    "./types": "./types/index.d.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "ai/",
+    "!ai/surface.baseline.json",
+    "adapters/",
+    "!adapters/presentation/fixtures",
+    "types/",
+    "dist/",
+    "!dist/manifest.json",
+    "01-tokens/",
+    "02-primitives/",
+    "03-patterns/",
+    "04-recipes/",
+    "09-assets/",
+    "!09-assets/model-viewer/vendor",
+    "!09-assets/model-viewer/models",
+    "docs/",
+    "README.md",
+    "START-HERE.md",
+    "API.md",
+    "ERRORS.md",
+    "SUPPORT.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "index.html"
+  ],
+  "sideEffects": [
+    "*.css",
+    "*.js"
+  ],
+  "scripts": {
+    "test": "node --test 05-audit/unit.test.mjs 05-audit/behavior-cores.test.mjs",
+    "gate": "bash 05-audit/check-all.sh",
+    "gate:fast": "bash 05-audit/check-all.sh --fast",
+    "gate:timing": "bash 05-audit/check-all.sh --timing",
+    "size:record": "python3 05-audit/size-baseline.py --record",
+    "dist": "python3 05-audit/build-dist.py",
+    "dist:check": "python3 05-audit/build-dist.py --check && node 05-audit/dist-parity-check.js && python3 05-audit/dist-cost-gate.py",
+    "cost:update": "python3 05-audit/dist-cost-gate.py --update",
+    "prefix": "python3 05-audit/prefix-build.py",
+    "ai": "node ai/cli.js",
+    "benchmark": "node benchmark/run.js",
+    "test:types": "python3 05-audit/tsc-gate.py",
+    "publish:check": "bash 05-audit/check-all.sh --fast && bash 05-audit/pack-smoke.sh",
+    "prepublishOnly": "npm run publish:check"
+  },
+  "devDependencies": {
+    "axe-core": "^4.10.0",
+    "pixelmatch": "^5.3.0",
+    "playwright": "^1.49.1",
+    "pngjs": "^7.0.0",
+    "puppeteer-core": "^23.11.1",
+    "typescript": "^5.9.3",
+    "yaml": "^2.9.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owain323/frontend-lib.git"
+  },
+  "keywords_note": "零依赖是本库的核心约束：安装它不会给使用者的 node_modules 增加任何一个包",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/owain323/frontend-lib",
+  "bugs": {
+    "url": "https://github.com/owain323/frontend-lib/issues"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * frontend-lib — TypeScript 类型定义
+ *
+ * ============================================================================
+ * 为什么需要它
+ * ---------------------------------------------------------------------------
+ *   本库是**纯 JS + 零依赖**，但使用者接入时没有任何类型提示：
+ *   参数名写错、要传几个字段、返回值是什么 —— 全靠读源码。
+ *   ⇒ 接入成本高，且类型错误只会在**运行时**暴露。
+ *
+ *   ⭐ 解法：给有 JS API 的组件补 `.d.ts`。
+ *   ⚠️ **不引入 TypeScript 作为运行时依赖** —— 这些声明文件是纯文本，
+ *      TS 项目会自动读取，JS 项目完全无感。
+ *
+ * ============================================================================
+ * ⭐ 本文件的每一行都由门禁核对过（2026-10-06 起）
+ * ---------------------------------------------------------------------------
+ *   曾经的教训：类型里写满了 runtime 根本没有的 API，而门禁抓不到——
+ *   因为旧门禁只比对「方法名是否出现」，不比对「是方法还是属性」。
+ *
+ *   实际发生过的错误（全部已修，并由 `api-contract` 门禁防复发）：
+ *     ① Select.value 声明成 string[]，实际是标量
+ *     ② ComponentInstance.destroy() —— select/combobox/date-range 都没有
+ *     ③ Combobox.tags 声明成方法()，实际是 getter
+ *     ④ DateRange 实例声明了 iso/quarterOf 等**静态**函数
+ *     ⑤ PresetName 列的 'today'/'week' 全部不存在
+ *     ⑥ DateRange.onChange 签名是两个字符串，实际是 (对象, 布尔)
+ *
+ *   ⇒ 改本文件前先跑：
+ *       python3 05-audit/api-contract.py         # 看 runtime 真实形状
+ *       npx tsc --noEmit -p type-tests/          # 看类型自洽
+ *
+ * ============================================================================
+ * 怎么用
+ * ---------------------------------------------------------------------------
+ *   // tsconfig.json
+ *   { "compilerOptions": { "paths": { "agentcss": ["./types/index.d.ts"] } } }
+ *
+ *   import { Select } from 'agentcss';
+ *   const s = Select.create(el, { label: '口径', onChange: (v, text) => … });
+ *                                                       ^^^^^^^^^^^^^^ 参数名/个数写错会立刻报错
+ */
+
+/* ============================================================================
+ * 基础形状
+ * ========================================================================== */
+
+/**
+ * ⭐ **不再有一个统一的 ComponentInstance**。
+ *
+ *   之前所有组件都 `extends ComponentInstance`，而那个接口带 `destroy()`。
+ *   实测：只有 dropdown / tree / bar / sparkline 提供 destroy()，
+ *   select / combobox / date-range / popover / tooltip **都没有**。
+ *   ⇒ 一个共用接口必然对一部分组件说谎。
+ *
+ *   ⇒ 改为：每个组件单独声明它**真实拥有**的成员。
+ *      需要销毁能力的组件自己带 `destroy()`（下面 accordion/dropdown 等）。
+ */
+export interface Destroyable {
+  /** 销毁：移除监听、清空生成的 DOM */
+  destroy(): void;
+}
+
+/* ============================================================================
+ * select —— 单选下拉
+ * ========================================================================== */
+export interface SelectOption {
+  value: string;
+  label: string;
+  /** 语义色（success / warning / danger / info /neutral） */
+  tone?: 'success' | 'warning' | 'danger' | 'info' | 'neutral';
+  disabled?: boolean;
+}
+
+export interface SelectOptions {
+  /** 无障碍名（读屏会读它） */
+  label: string;
+  options: SelectOption[];
+  /** 初始选中值 */
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /**
+   * ⭐ 变更回调。**两个参数**，不是数组。
+   *   runtime：`opt.onChange(selected, 显示文本)`
+   *
+   * ⚠️ 本组件**只支持单选** —— 内部状态是标量。
+   *   早期类型里写过 `string[]` 与 `max`/`min`，实现从未支持，
+   *   属于「声明了却没有」⇒ 已移除。需要多选请用 combobox。
+   */
+  onChange?(value: string | null, text: string): void;
+  /**
+   * 打开/关闭。
+   * ⚠️ runtime 是 `opt.onOpen()`，**不传参数**。
+   *   想知道是开是关，请自己在 onChange 里判断，或观察 DOM。
+   */
+  onOpen?(): void;
+}
+
+/**
+ * ⭐ 与 `select.js` 的实际返回逐项对齐。
+ *   runtime 返回：`{ open, close, get value(), set value(v) }`
+ *   ⇒ 用 `value` 属性（getter/setter），**不是** getValue/setValue。
+ *   ⇒ 没有 destroy()：卸载请直接移除节点（组件无全局监听）。
+ */
+export interface Select {
+  /** 展开下拉 */
+  open(): void;
+  /** 收起下拉 */
+  close(): void;
+  /** 当前值（可读写；写入会触发 onChange） */
+  value: string | null;
+}
+
+/* ============================================================================
+ * combobox —— 多选组合框
+ * ========================================================================== */
+export interface ComboboxOptions {
+  label: string;
+  options: SelectOption[];
+  /**
+   * 最多可选几个 —— **硬上限**，不是"选满了就收起下拉"。
+   *
+   * ⭐ 三条入口都受它约束：点选项 / Enter 提交 / 公开 `add()`。
+   *   （以前只在 `commitActive()` 里"加完发现满了才关列表"，
+   *     公开 `add()` 和点击路径都能绕过 —— 2026-10-10 修。）
+   *   满了以后 `add()` 返回 `false`，标签数量不再变化。
+   */
+  max?: number;
+  placeholder?: string;
+  disabled?: boolean;
+  /** 变更回调（传已选的 value 数组） */
+  onChange?(values: string[]): void;
+  /**
+   * 自定义过滤（不传则用 label/value 的 includes 匹配）。
+   * ⚠️ **必须同步返回布尔值** —— 会被逐项调用，不能在里面做异步过滤。
+   */
+  filter?(input: string, opt: SelectOption): boolean;
+}
+
+/**
+ * ⭐ 与 `combobox.js` 实际返回对齐。
+ *   runtime 返回：`{ get tags(), add, remove, setOptions, destroy }`
+ *
+ * ⚠️ `tags` 是**属性（getter）**，不是方法 —— 用 `c.tags`，不是 `c.tags()`。
+ *   早期类型写成方法，于是文档与实际用法对不上。
+ *
+ * 🔴 关于 `destroy()`（2026-10-10 修）：
+ *   以前这里写"它**没有** destroy()" —— 那句话曾经是真的，
+ *   但组件注册了一个 **document 级** click 监听却没人摘，
+ *   ⇒ 实例销毁后监听还活着（每个死掉的实例都握着一份 DOM 引用）。
+ *   现在有 `destroy()` 了，**卸载时必须调用**（或至少在移除节点前调用）。
+ */
+export interface Combobox {
+  /** 已选中的 value 数组（只读快照，每次访问返回新数组） */
+  readonly tags: string[];
+  /**
+   * 追加一项。
+   * 返回 `false` 表示没加进去：空值 / 已存在 / **禁用项** / **已达 max**。
+   */
+  add(value: string): boolean;
+  /** 移除一项 */
+  remove(value: string): void;
+  /** 替换候选项 */
+  setOptions(options: SelectOption[]): void;
+  /**
+   * 解绑全部监听（含 document 级）并收起列表。**幂等**。
+   * ⚠️ 移除 DOM 之前请先调用它，否则监听会泄漏。
+   */
+  destroy(): void;
+}
+
+/* ============================================================================
+ * date-range —— 日期区间
+ * ========================================================================== */
+
+/**
+ * ⭐ 内置预设区间名。
+ *
+ *   ⚠️ 这五个是**实现里真实存在的全部值**，取自 `date-range.js` 的 PRESETS：
+ *       thisQ（本季度） / lastQ（上季度） / lastM（上月）
+ *       thisY（今年）   / yoy（去年同期）
+ *
+ *   之前类型里写的是'today' / 'week' / 'month' / 'lastMonth' /
+ *   'thisYear' / 'lastYear' —— 这些 preset **一个都不存在**，
+ *   而类型却放它们过关 ⇒ TS 放行、runtime 静默无反应。
+ */
+export type PresetName = 'thisQ' | 'lastQ' | 'lastM' | 'thisY' | 'yoy';
+
+export interface DateRangeOptions {
+  label: string;
+  /**
+   * 要显示哪些快捷区间（取值为预设名）。
+   * ⚠️ 传了但 DOM 里没有对应 `data-dr-preset` 按钮的，会被静默忽略。
+   */
+  presets?: PresetName[];
+  /** 是否允许手动输入 */
+  editable?: boolean;
+  disabled?: boolean;
+  /**
+   * ⭐ 变更回调。**第一个参数是对象，第二个是布尔**。
+   *   runtime：`opt.onChange({ from, to, valid }, valid)`
+   *
+   *   之前类型写成 `(from: string, to: string)` ——
+   *   调用方按类型写 `onChange: (from, to) => ...`，to 会拿到 undefined。
+   */
+  onChange?(value: { from: string; to: string; valid: boolean },
+            valid: boolean): void;
+}
+
+/**
+ * ⭐ 与 `date-range.js` 实际返回对齐：
+ *   `{ get from(), get to(), get valid(), set, setPreset, clear }`
+ *
+ * ⚠️ **它没有** iso / quarterOf / quarterRange / addDays / addMonths ——
+ *   那些是 `DateRange` 命名空间上的**静态**函数，见 DateRangeStatics。
+ *   之前把它们声明成实例方法，于是 `dr.addDays(...)` 类型通过、
+ *   运行时 `dr.addDays is not a function`。
+ */
+export interface DateRange {
+  /** 起始日（YYYY-MM-DD，只读） */
+  readonly from: string;
+  /** 结束日（YYYY-MM-DD，只读） */
+  readonly to: string;
+  /** 区间是否有效（from <= to） */
+  readonly valid: boolean;
+  /** 设置区间 */
+  set(from: string, to: string): void;
+  /**
+   * 套用预设。
+   * ⚠️ 参数是**预设名**（`thisQ` / `lastM` / …），不是日期区间。
+   *   之前类型写成 `setPreset(from, to)` ⇒ 完全错误的用法被类型放行。
+   *   传入未渲染的 preset 名会**静默无反应**（找不到对应按钮）。
+   */
+  setPreset(preset: PresetName): void;
+  /** 清空 */
+  clear(): void;
+}
+
+/* ============================================================================
+ * DateRange 命名空间上的静态函数（可脱离组件单独用）
+ * ========================================================================== */
+export interface DateRangeStatics {
+  /** Date → 'YYYY-MM-DD'（**本地时区**，不用 toISOString，避免时区偏移） */
+  iso(d: Date): string;
+  /** 加天数（跨月/跨年/闰年都正确） */
+  addDays(isoStr: string, n: number): string;
+  /** 加月份，**月末夹取**（1/31 + 1 月 = 2/28 或 2/29） */
+  addMonths(isoStr: string, n: number): string;
+  /** 日期 → 季度。⚠️ 返回对象，`q` 是 **0-based**（0=Q1） */
+  quarterOf(date: Date): { y: number; q: number };
+  /** 季度 → 起止日。🔴 `q` **必须 0-3**，否则抛错 */
+  quarterRange(y: number, q: number): { from: string; to: string };
+  /** 挂载一个日期区间组件 */
+  create(root: HTMLElement, opt: DateRangeOptions): DateRange;
+}
+
+/* ============================================================================
+ * dropdown —— 下拉菜单（唯一带 destroy 的常用组件之一）
+ * ========================================================================== */
+export interface Dropdown {
+  open(): void;
+  close(): void;
+  destroy(): void;
+}
+
+/* ============================================================================
+ * tree —— 树形导航
+ * ========================================================================== */
+export interface TreeOptions {
+  /** 无障碍名（读屏会读它） */
+  label?: string;
+}
+
+/* ============================================================================
+ * tree —— 树形导航
+ * ========================================================================== */
+export interface Tree {
+  /** 让第 n 项（按可见顺序）获得焦点 */
+  focusAt(n: number): void;
+  /**
+   * 当前选中项。
+   * ⚠️ 返回的是**列表项 DOM 元素**，不是 value 字符串
+   *   （runtime：`list[cur]`，list 是可见项数组）。没有选中项时为 null。
+   */
+  readonly selected: HTMLElement | null;
+  destroy(): void;
+}
+
+/* ============================================================================
+ * 全局命名空间（组件脚本是 IIFE，挂到 window）
+ * ========================================================================== */
+export interface FrontendLibGlobal {
+  DateRange: DateRangeStatics;
+  Select: { create(root: HTMLElement, opt: SelectOptions): Select };
+  Combobox: { create(root: HTMLElement, opt: ComboboxOptions): Combobox };
+  Dropdown: { create(root: HTMLElement, opt?: object): Dropdown };
+  Tree: { create(root: HTMLElement, opt?: TreeOptions): Tree };
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface Window extends FrontendLibGlobal {}
+}
+
+export declare const Select: FrontendLibGlobal['Select'];
+export declare const Combobox: FrontendLibGlobal['Combobox'];
+export declare const DateRange: DateRangeStatics;
+export declare const Dropdown: FrontendLibGlobal['Dropdown'];
+export declare const Tree: FrontendLibGlobal['Tree'];