agentcss 0.0.0-stage → 0.11.3

package/ai/components.meta.json

@@ -0,0 +1,168 @@
+{
+  "$comment": [
+    "这是『人工持有』的那一半组件契约。",
+    "机器持有的那一半（元素名/变体/状态/文件）由 05-audit/gen-ai-contract.py 从源码抽出，",
+    "两者合并生成 ai/components.json；--check 模式下不一致即红。",
+    "",
+    "⚠️ 这里只放『无法从源码机械推出』的东西：根类、用途、成熟度理由。",
+    "能机械推出的东西放这里 = 第二份真值来源 = 必然漂移（见 INVARIANT I-7）。"
+  ],
+  "maturityCriteria": {
+    "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",
+    "beta": "有 demo + 专属门禁，但**下面至少有一条没过**：① 状态仍用 .is-* class 表达（违反 INVARIANT I-8）；② 该收编到微行为核的行为还是**手写副本**（manual）或**根本没做**（gap） ⇒ 改一处不会全库跟着变（I-14 的病）",
+    "stable": "以上四条全过：有 demo + 专属门禁 + 状态全在 data-* 属性上 + 行为零欠账",
+    "$note": "成熟度是【计算出来的】，不是拍的。手写把某个组件改成 stable 而它还有 manual / gap ⇒ 门禁会红。",
+    "$whyFourth": "🔴 为什么 M8 要加第四条（0.7.6）：只用前三条时 27 个组件**全是 stable** ⇒ ladder 没有任何鉴别力（对标 Primer 六档阶梯，每档都有硬判据）。补上行为欠账这一条后：stable 20 / beta 7。",
+    "$strictImpact": "⚠️ strict 档位只放行 stable ⇒ 这 7 个组件在 strict 下不可用（accordion / combobox / drawer / dropdown / overlay / select / tooltip）。这是**有意的**：它们的行为还有手写副本或缺一个该有的行为。要用就切 standard 档。"
+  },
+  "components": {
+    "accordion": {
+      "rootClass": "accordion",
+      "purpose": "可折叠分组"
+    },
+    "analysis-report": {
+      "rootClass": "report",
+      "tier": "recipe",
+      "purpose": "组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏"
+    },
+    "badge": {
+      "rootClass": "badge",
+      "purpose": "状态标签：计数、分类、结果标记"
+    },
+    "bar": {
+      "rootClass": "bar",
+      "tier": "asset",
+      "purpose": "柱状图（charter 13 图表规范）：堆叠/分组两种语义、超量程裁剪、图例"
+    },
+    "button": {
+      "rootClass": "btn",
+      "purpose": "动作触发：主/次/危险/纯文字四档"
+    },
+    "card": {
+      "rootClass": "card",
+      "purpose": "内容容器：媒体+正文+操作区三段"
+    },
+    "choice": {
+      "rootClass": "choice",
+      "purpose": "单选/多选/原生 select 外观的统一控件"
+    },
+    "combobox": {
+      "rootClass": "combo",
+      "purpose": "可搜索 + 可多选标签的输入控件"
+    },
+    "content": {
+      "rootClass": "prose",
+      "purpose": "长文排版容器（标题/段落/列表/引用/代码）"
+    },
+    "date-range": {
+      "rootClass": "drange",
+      "purpose": "日期区间选择，含预设快捷范围"
+    },
+    "drawer": {
+      "rootClass": "drawer",
+      "purpose": "侧边抽屉，含遮罩"
+    },
+    "dropdown": {
+      "rootClass": "dd",
+      "purpose": "下拉菜单"
+    },
+    "form-validation": {
+      "rootClass": "form",
+      "purpose": "表单校验反馈与错误汇总"
+    },
+    "input": {
+      "rootClass": "field",
+      "purpose": "文本输入及其标签/帮助/错误三件套"
+    },
+    "list": {
+      "rootClass": "list",
+      "purpose": "键值列表/条目列表"
+    },
+    "model-viewer": {
+      "rootClass": "mv",
+      "tier": "asset",
+      "purpose": "3D 模型查看器：令牌驱动样式，不含渲染库本体"
+    },
+    "nav": {
+      "rootClass": "nav",
+      "purpose": "顶部导航与目录"
+    },
+    "overlay": {
+      "rootClass": "toast",
+      "purpose": "吐司提示与模态遮罩"
+    },
+    "pagination": {
+      "rootClass": "pagination",
+      "purpose": "分页控件"
+    },
+    "popover": {
+      "rootClass": "popover",
+      "purpose": "锚定到触发元素的浮层"
+    },
+    "progress": {
+      "rootClass": "progress",
+      "purpose": "进度条与进度环"
+    },
+    "report": {
+      "rootClass": "rep",
+      "tier": "recipe",
+      "purpose": "报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一个 rep--* 类即可切换取舍"
+    },
+    "scientific-plot": {
+      "rootClass": "splot",
+      "tier": "asset",
+      "purpose": "二维科学绘图：折线/区间带/对数轴，纯令牌驱动、零依赖"
+    },
+    "select": {
+      "rootClass": "select",
+      "purpose": "自定义下拉选择（非原生）"
+    },
+    "separator": {
+      "rootClass": "separator",
+      "purpose": "分隔线，可带中间文字"
+    },
+    "skeleton": {
+      "rootClass": "skeleton",
+      "purpose": "加载占位骨架"
+    },
+    "sparkline": {
+      "rootClass": "sparkline",
+      "tier": "asset",
+      "purpose": "迷你趋势图：无坐标轴、纯形状，适合表格内嵌的一行走势"
+    },
+    "states": {
+      "rootClass": "state",
+      "purpose": "空/加载/错误/成功四种整块状态"
+    },
+    "switch": {
+      "rootClass": "switch",
+      "purpose": "开关切换"
+    },
+    "table": {
+      "rootClass": "table",
+      "tier": "recipe",
+      "purpose": "数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计）"
+    },
+    "tabs": {
+      "rootClass": "tabs",
+      "purpose": "选项卡切换"
+    },
+    "reveal": {
+      "rootClass": "reveal",
+      "purpose": "入场动效：一个 data-reveal 属性六个方向，无 JS 时内容全可见"
+    },
+    "tooltip": {
+      "rootClass": "tooltip",
+      "purpose": "悬停/聚焦提示"
+    },
+    "tree": {
+      "rootClass": "tree",
+      "purpose": "可展开树形结构"
+    },
+    "detail-page": {
+      "rootClass": "detail-page",
+      "tier": "recipe",
+      "purpose": "实体详情页骨架：字段齐全 / 部分缺失 / 无数据三种状态同构，无数据是一等状态"
+    }
+  }
+}

package/ai/components.schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/components.schema.json",
+  "title": "frontend-lib 组件契约",
+  "$comment": [
+    "描述 ai/components.json 的形状。那份文件由 05-audit/gen-ai-contract.py 生成。",
+    "",
+    "🔴 slots 为什么是 BEM 元素名：",
+    "   在本库里 `card__media` / `card__body` 就是『可以往里放东西的位置』，",
+    "   元素名与插槽名是同一个东西。这与 Web Awesome 的 slots 是同一概念，",
+    "   只是它用 <slot name>，我们用 class —— 因为我们不用 Shadow DOM。"
+  ],
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "components"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string"
+    },
+    "generatedBy": {
+      "type": "string"
+    },
+    "libraryVersion": {
+      "type": "string"
+    },
+    "maturityCriteria": {
+      "type": "object"
+    },
+    "summary": {
+      "type": "object"
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/component"
+      }
+    }
+  },
+  "definitions": {
+    "component": {
+      "type": "object",
+      "required": [
+        "id",
+        "tier",
+        "rootClass",
+        "maturity",
+        "slots",
+        "states"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "tier": {
+          "type": "string",
+          "enum": [
+            "primitive",
+            "pattern",
+            "recipe",
+            "asset"
+          ]
+        },
+        "purpose": {
+          "type": "string"
+        },
+        "rootClass": {
+          "type": "string"
+        },
+        "maturity": {
+          "type": "string",
+          "enum": [
+            "alpha",
+            "beta",
+            "stable"
+          ]
+        },
+        "maturityReasons": {
+          "type": "object",
+          "properties": {
+            "hasDemo": {
+              "type": "boolean"
+            },
+            "hasDedicatedGate": {
+              "type": "boolean"
+            },
+            "statesOnDomAttributes": {
+              "type": "boolean"
+            }
+          },
+          "$comment": "成熟度是算出来的，不是拍的。改了这些信号，成熟度必须跟着变。"
+        },
+        "gates": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "files": {
+          "type": "object",
+          "properties": {
+            "css": {
+              "type": "string"
+            },
+            "js": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "jsAlso": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "$comment": "同目录下的**其他** .js（主文件在 js 里）。没有这个字段时，第二个文件在契约里彻底消失 —— 而 AI 消费者读的就是这份契约。"
+            },
+            "demo": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
+        "slots": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "$comment": "BEM 元素名，即具名插入点。"
+        },
+        "variants": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "states": {
+          "type": "object",
+          "properties": {
+            "enum": {
+              "type": "object",
+              "$comment": "data-* 属性名 → 全部可能取值。状态是枚举字符串，不是布尔（I-9）。"
+            },
+            "boolean": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "legacyClass": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "$comment": [
+                "仍未收敛到 data 属性的 .is-* 状态类。",
+                "非空 ⇒ 该组件违反 I-8（状态不在 DOM 上）⇒ 成熟度上限为 beta。"
+              ]
+            }
+          }
+        },
+        "aria": {
+          "type": "object",
+          "properties": {
+            "roles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "attrs": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "usesOtherNamespaces": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "global": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "globalAlso": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "global",
+              "js"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "global": {
+                "type": "string"
+              },
+              "js": {
+                "type": "string"
+              }
+            }
+          },
+          "$comment": "同目录下**主文件之外**导出的全局（0.11.2：nav/ 里 nav.js 导 Nav、toc.js 导 Toc）。只记主文件那个 ⇒ 第二个全局在量具眼里不存在 ⇒ 文档写了它反而被报成\"库里没有\"。"
+        },
+        "behaviorRef": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/ai/contract.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/contract.schema.json",
+  "title": "frontend-lib 编辑契约 · 文档信封",
+  "$comment": [
+    "这是【版本化契约】层：约定接口长什么样。会随版本变，但向后兼容。",
+    "它不规定 AI 该怎么做（那是 docs/GUIDANCE.md），",
+    "也不陈述客观事实（那是 docs/INVARIANT.md）。",
+    "",
+    "🔴 分层理由：把三者混在一起，约束就会变成天花板 ——",
+    "   模型变强时，你要放宽的是 Guidance，而不是把 Contract 和 Invariant 一起推翻。",
+    "",
+    "🔴 extensions 是前向兼容位：",
+    "   旧版校验器遇到不认识的键必须【忽略】，不能判文档非法。"
+  ],
+  "invariants": [
+    "I-1",
+    "I-2",
+    "I-3",
+    "I-4",
+    "I-5",
+    "I-6",
+    "I-7",
+    "I-8",
+    "I-9",
+    "I-10",
+    "I-11",
+    "I-12",
+    "I-13",
+    "I-14",
+    "I-15",
+    "I-16"
+  ],
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "profile",
+    "nodes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "$comment": "契约版本，不是库版本。语义化：主版本=不兼容，次版本=新增可选能力。"
+    },
+    "profile": {
+      "type": "string",
+      "enum": [
+        "creative",
+        "standard",
+        "strict"
+      ],
+      "$comment": "详见 ai/profiles.json。三档决定『允许多不成熟的东西进入文档』。"
+    },
+    "capabilities": {
+      "$ref": "#/definitions/capabilities",
+      "$comment": [
+        "能力协商：编辑方【声明自己有什么能力】，而不是我们【按模型名猜】。",
+        "按模型名分支会立刻过期，且无法容纳同一模型的不同接入方式。"
+      ]
+    },
+    "root": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "$comment": "顶层节点的 id 顺序。数组顺序即渲染顺序。"
+    },
+    "nodes": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/node"
+      },
+      "$comment": [
+        "id → 节点。**编辑的作用对象是 id，不是 HTML 路径。**",
+        "理由：HTML 路径（第 3 个 div 的第 2 个子节点）在每次结构变动后都会失效，",
+        "而语义 id 不会 —— 这正是『改 A 坏 B』的技术根因。"
+      ]
+    },
+    "extensions": {
+      "type": "object",
+      "$comment": "前向兼容位。旧版校验器必须忽略未知键，不得判文档非法。"
+    }
+  },
+  "definitions": {
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "structuredOutput": {
+          "type": "boolean",
+          "$comment": "能否稳定输出符合本契约的 JSON"
+        },
+        "toolCalling": {
+          "type": "boolean",
+          "$comment": "能否调用外部工具（跑校验器、读文件）"
+        },
+        "visualInspection": {
+          "type": "boolean",
+          "$comment": "能否看到渲染结果（截图/浏览器）"
+        },
+        "patchEditing": {
+          "type": "boolean",
+          "$comment": "能否按语义 id 增量修改，而不是整篇重写"
+        }
+      }
+    },
+    "node": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "$comment": "语义 id。小写字母开头，稳定不变 —— 变 id 等于换了一个节点。"
+        },
+        "kind": {
+          "type": "string",
+          "$comment": [
+            "组件 id（见 ai/components.json），或内置种类：",
+            "  text    纯文本",
+            "  slot    具名插入点（对应组件的 BEM 元素名）"
+          ]
+        },
+        "text": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object",
+          "$comment": "组件属性：变体名、状态取值等。取值受 ai/components.json 约束。"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "$comment": "子节点 id。移动子节点 = move 操作，不动内容。"
+        },
+        "extensions": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}

package/ai/deprecations.json

@@ -0,0 +1,55 @@
+{
+  "$comment": [
+    "这是『人工持有』的废弃登记册：库里**曾经有 / 现在有但将来要删**的公开名字。",
+    "",
+    "⚠️ 为什么它必须存在（M9 · 0.7.7）",
+    "   移除一个公开名字（令牌 / 类名）是**对下游的破坏性变更**，",
+    "   而此前它是**不受任何门禁约束**的：0.7.4 移除了 `--measure`，",
+    "   更新日志里记了一笔，但没有一处机器可读的地方说清楚：",
+    "     · 它什么时候开始算废弃的",
+    "     · 什么时候**允许**真的删",
+    "     · 删了之后该用什么替代",
+    "   ⇒ 下游只能靠读更新日志的人肉记忆来迁移。这是不可接受的。",
+    "",
+    "   对标 Primer 的 Deprecated / Removed 两档：废弃要有告警、有替代方案、",
+    "   提前公告、并用 codemod 或 lint 阻断继续使用。我们没有 codemod，",
+    "   所以『迁移窗口』只能用**版本号的距离**来表达 —— 这就是 policy.minLead。",
+    "",
+    "🔴 两个桶的区别（不要混用）",
+    "   planned     走流程的：先登记，到 removeIn 才允许删。判据双向看住它。",
+    "   retroactive 事后补登：**已经删了**才来登记的。它是历史欠账，不是流程。",
+    "     ⇒ 数量写死在 budget.retroactive 里当棘轮：想再加一条，必须改预算，",
+    "       而改预算是一次**看得见的、需要说明理由**的改动。"
+  ],
+  "schemaVersion": "1.0.0",
+  "policy": {
+    "minLead": "至少跨一个次版本：0.7.x 废弃 ⇒ 最早 0.8.0 才允许移除",
+    "$whyMinLead": "本库一天可能发好几个修订号，用『修订号个数』当窗口等于没有窗口。只有次版本/主版本的推进才是下游会专门安排迁移的节奏。",
+    "$whatWeCannotDo": "诚实边界：我们**没有** codemod、也没有运行时告警（组件 JS 不打印 console.warn，那是移动端 WebView 的噪音）。所以这个窗口只是『版本号承诺』，不是技术阻断。"
+  },
+  "planned": [
+    {
+      "id": "state--delayed",
+      "kind": "class",
+      "name": "state--delayed",
+      "deprecatedIn": "0.7.7",
+      "removeIn": "0.8.0",
+      "reason": "这个类承诺了一个『延迟显现』的机制，但全库**没有任何 JS** 会去设置它所依赖的 data-state=\"shown\" ⇒ 使用者必须自己接，而文档没写。它读起来像本库已经实现了 —— 这类名字最危险，因为误会发生在读者脑子里，代码不会报错。",
+      "replacement": null,
+      "replacementNote": "没有替代品：想要延迟显现，自己给元素加 data-state=\"shown\" 即可（states.css 里那两行就是全部实现）。",
+      "$evidence": "05-audit/dead-class-gate.py 把它列在『真死类候选』里，并注明『全库没有任何 JS 加过它』。"
+    }
+  ],
+  "retroactive": [
+    {
+      "kind": "token",
+      "name": "--measure",
+      "removedIn": "0.7.4",
+      "replacement": ["--measure-page", "--measure-prose"],
+      "$why": "0.7.4 移除它的时候，这套流程还不存在。补登是为了让它**不从历史里消失**，不是为了让那次移除看起来走过流程 —— 那次就是没走。"
+    }
+  ],
+  "budget": {
+    "retroactive": 1
+  }
+}

package/ai/deprecations.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/deprecations.schema.json",
+  "title": "frontend-lib 废弃登记册",
+  "$comment": [
+    "描述 ai/deprecations.json 的形状：**库里曾经有 / 现在有但将来要删的公开名字**。",
+    "",
+    "🔴 为什么这份登记要存在：移除一个公开名字是**对下游的破坏性变更**，",
+    "   而此前它不受任何门禁约束 —— 0.7.4 移除了 `--measure`，只在更新日志里",
+    "   记了一笔 ⇒ 没有机器可读的地方说清『什么时候开始算废弃 / 什么时候允许删 /",
+    "   删了之后用什么替代』。下游只能靠人肉记忆迁移。",
+    "",
+    "🔴 两个桶：",
+    "   planned     走流程的：先登记，到 removeIn 才允许删（判据双向看住）",
+    "   retroactive 事后补登：已经删了才来登记 ⇒ 历史欠账，数量由 budget 当棘轮",
+    "",
+    "⚠️ 本文件是**手写**的，不是生成的（生成的契约只跟再生成一遍比，没有新信息，",
+    "   docs/INVARIANT.md I-10 实证 9）。",
+    "⚠️ 本 schema 只用了 ai/validate.js 白名单里的关键字。"
+  ],
+  "type": "object",
+  "required": ["schemaVersion", "planned", "retroactive", "budget"],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "$comment": {},
+    "policy": {
+      "type": "object",
+      "required": ["minLead"],
+      "properties": {
+        "minLead": { "type": "string", "minLength": 1 },
+        "$whyMinLead": { "type": "string" },
+        "$whatWeCannotDo": { "type": "string" }
+      }
+    },
+    "planned": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "name", "deprecatedIn", "removeIn", "reason"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["token", "class"] },
+          "name": { "type": "string", "minLength": 1 },
+          "deprecatedIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+          "removeIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+          "reason": { "type": "string", "minLength": 1 },
+          "replacement": {
+            "oneOf": [
+              { "type": "null" },
+              { "type": "string", "minLength": 1 },
+              { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            ]
+          },
+          "replacementNote": { "type": "string" }
+        }
+      }
+    },
+    "retroactive": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "name", "removedIn"],
+        "properties": {
+          "kind": { "enum": ["token", "class"] },
+          "name": { "type": "string", "minLength": 1 },
+          "removedIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+          "replacement": {
+            "oneOf": [
+              { "type": "null" },
+              { "type": "string", "minLength": 1 },
+              { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            ]
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "required": ["retroactive"],
+      "properties": {
+        "retroactive": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}