@wisdomgarden/torque-knowledge 1.0.7 → 1.0.9

package/README.md

@@ -13,7 +13,7 @@
 | 文件 | 给谁 | 是什么 |
 | --- | --- | --- |
 | `dist/torque-components.md` | **diting**（`lms-web` 的 CI code review） | 选型决策树 + 可用组件清单 + 硬约束 + 禁止事项。**只有清单和策略，没有组件细节** —— 细节查 `components.db`。带 diting 认的 frontmatter（单行 `keywords` / `globs`），解包进它的 `rule_dirs` 就能被召回 |
-| `dist/components.db` | **`lms-web` 的本地 MCP** + **diting** | SQLite 组件目录，MCP `search_component()` 和 diting `query_ui_components` 共同的数据源。44 个组件的导出名（含 `Combobox.InfiniteDropdown` 这类点号子组件名）、英文描述、keywords 和完整 props |
+| `dist/components.db` | **`lms-web` 的本地 MCP** + **diting** | SQLite 组件目录，MCP `search_component()` 和 diting `query_ui_components` 共同的数据源。46 个组件的导出名（含 `Combobox.InfiniteDropdown` 这类点号子组件名）、英文描述、keywords 和完整 props |
 | `dist/.meta.json` | CI / 下游漂移检测 | `{ knowledge, torque, generatedAt }` —— 这份知识是哪个版本、描述的又是哪个 torque 版本 |
 
 ## 版本与 `@wisdomgarden/torque` 相互独立
@@ -42,9 +42,9 @@ pnpm --filter @wisdomgarden/torque-knowledge build
 
 ```
 packages/torque/src/index.ts              ← 组件清单的唯一来源（不是 readdir）
-packages/torque/src/components/*/readme.md ← 39 篇，props 和中文描述
-packages/torque/src/provider/readme.md     ← 第 40 篇
-src/fallback.json                          ← 全部 44 个组件的英文描述（手工维护）
+packages/torque/src/components/*/readme.md ← 42 篇，props 和中文描述
+packages/torque/src/provider/readme.md     ← 第 43 篇
+src/fallback.json                          ← 全部 46 个组件的英文描述（手工维护）
 src/handwritten/*.md                       ← 人工提炼的正文片段
         │
         └──> scripts/gen.mjs ──> dist/

package/dist/.meta.json

@@ -1,5 +1,5 @@
 {
-  "knowledge": "1.0.7",
-  "torque": "0.2.2",
-  "generatedAt": "2026-09-22T06:38:12.733Z"
+  "knowledge": "1.0.9",
+  "torque": "0.3.0",
+  "generatedAt": "2026-09-30T09:36:45.145Z"
 }

package/dist/torque-components.md

@@ -1,12 +1,12 @@
 ---
 description: Torque UI component library — selection priority, available components, and hard constraints.
 globs: src/**/*.{tsx,ts}
-keywords: torque, component, ui, mantine, layout, button, icon-button, link-button, link-icon-button, tooltip, popover, drawer, bottom-drawer, modal, menu, message, notifications, alert, sticky-box, tag, tab, table, table-pagination, tree, tree-select, virtualized-tree-select, date-picker, filter, data-filter, base-input, form-wrapper, text-input, text-area, number-input, password-input, checkbox, radio, switch, select, multi-select, combobox, box, text, flex, group, stack, paper, unstyled-button, provider, iconbutton, linkbutton, linkiconbutton, bottomdrawer, messages, stickybox, tabs, tablepagination, treeselect, virtualizedtreeselect, datepicker, datafilter, baseinput, formitemwrapper, textinput, textarea, numberinput, passwordinput, multiselect, unstyledbutton, uiprovider
+keywords: torque, component, ui, mantine, layout, button, icon-button, link-button, link-icon-button, tooltip, popover, drawer, bottom-drawer, modal, modal-deprecated, overlay-layer, menu, message, notifications, alert, sticky-box, tag, tab, table, table-pagination, tree, tree-select, virtualized-tree-select, date-picker, filter, data-filter, base-input, form-wrapper, text-input, text-area, number-input, password-input, checkbox, radio, switch, select, multi-select, combobox, box, text, flex, group, stack, paper, unstyled-button, provider, iconbutton, linkbutton, linkiconbutton, bottomdrawer, modaldeprecated, useoverlaylayer, messages, stickybox, tabs, tablepagination, treeselect, virtualizedtreeselect, datepicker, datafilter, baseinput, formitemwrapper, textinput, textarea, numberinput, passwordinput, multiselect, unstyledbutton, uiprovider
 ---
 
 # Torque UI 组件库
 
-> 由 `@wisdomgarden/torque-knowledge@1.0.7` 生成，对应 `@wisdomgarden/torque@0.2.2`。
+> 由 `@wisdomgarden/torque-knowledge@1.0.9` 生成，对应 `@wisdomgarden/torque@0.3.0`。
 > 不要手改 —— 它是 npm 包解包出来的，下次装依赖就被覆盖。
 
 ## 导入方式
@@ -40,13 +40,11 @@ Server Component 序列化不了。
 | 自定义点击区（整卡可点、图片热区） | `UnstyledButton` |
 | 有明确按钮样式变体 | `Button`；纯图标 `IconButton`；跳转 `LinkButton` / `LinkIconButton` |
 
-`Box` 替代 `<div>`；`Text` 替代 `<span>` / `<p>`，用 `component` 选语义标签
-（`h1`–`h6` / `p` / `span`）；`UnstyledButton` 替代 `<button>`。
-`Paper` 不参与布局 —— 内部要排版就在里面嵌 `Flex` / `Group` / `Stack`。
+`Box` / `Text` / `UnstyledButton` 分别替代裸 `<div>`、文本标签、`<button>`；
+`Text.component` 选语义标签。`Paper` 只管表面，内部排版用布局组件。
 
-`Group` / `Stack` 是 `Flex` 的预设，只是默认值不同：`Group` = `align: center` +
-`wrap` + `gap: md`；`Stack` = `align: stretch` + `nowrap` + `gap: md`；
-`Flex` = `align: stretch` + `nowrap` + 无 gap。**默认值合适就别用 `Flex`。**
+`Group` / `Stack` 是 `Flex` 的预设：默认分别为 `center` + `wrap` + `gap: md`
+和 `stretch` + `nowrap` + `gap: md`；`Flex` 默认无 gap。**优先用预设。**
 
 **下拉与选择** —— 标准表单字段用 `Select`（单选）/ `MultiSelect`（多选，值是
 `string[]`）；要自定义触发器外观或富选项内容（头像、标签）才用 `Combobox`；
@@ -59,6 +57,8 @@ Server Component 序列化不了。
 侧边抽屉优先指令式 `drawers.open()`，需要复杂局部状态联动才用声明式 `<Drawer>`；
 移动端底部抽屉用 `BottomDrawer`（**只在移动端**）；悬停提示 `Tooltip`；
 需要交互内容的浮层 `Popover`；操作菜单 `Menu`。
+对话框：事件中打开用 `modals.open()` / `openConfirmModal()`；局部受控用 `<Modal>`；
+自定义结构或全屏用 `Modal.Root`。新代码不用 `ModalDeprecated`。
 
 **多态（`component` prop）** —— 自建布局组件**只接受 HTML 标签字符串**，Server 和
 Client Component 都安全。Mantine 的 `component={ReactComponent}` 只能在 Client
@@ -80,10 +80,12 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 | popover | `Popover`, `PopoverTarget`, `PopoverDropdown` |
 | drawer | `Drawer`, `DrawerManager`, `drawers` |
 | bottom-drawer | `BottomDrawer` |
-| modal | `Modal` |
+| modal | `Modal`, `ModalRoot`, `ModalBody`, `ModalTitle` |
+| modal-deprecated | `ModalDeprecated` |
+| overlay-layer | `useOverlayLayer`, `OVERLAY_BASE`, `OVERLAY_TOP_MIN`, `OverlayTierScope` |
 | menu | `Menu` |
 | message | `messages` |
-| notifications | `notifications`, `Notification` |
+| notifications | `notifications`, `Notification`, `NotificationsContainer` |
 | alert | `Alert`, `AlertSkeleton` |
 | sticky-box | `StickyBox` |
 | tag | `Tag` |
@@ -119,8 +121,7 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 
 ## 硬约束
 
-每一条都会**直接导致 bug 或规范违规**，不是风格偏好。来源是各组件 readme 的
-「AI 编码最佳实践 & 注意事项」。
+每一条都会**直接导致 bug 或规范违规**，不是风格偏好。
 
 ### 表单
 
@@ -129,8 +130,8 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
   `NumberInput` / `DatePicker` 系列 / `TreeSelect`）
 - **表单控件已内置 `FormItemWrapper`**，外面不要再包 `Field` / `Form.Item`，
   `DataFilter` 里的 `Select` 也一样 —— 会出现重复 label。
-- **`TextInput` / `TextArea` 的字数统计要求受控或绑表单。** 非受控且没传 `form` 时
-  组件读不到当前长度，`maxLength` 计数不更新。
+- **`TextInput` / `TextArea` 的字数统计要求受控或绑表单**（非受控且没传 `form` 时
+  计数不更新）。
 - **`CheckboxGroup` 内的 `Checkbox` 不要手动绑 `checked` / `onChange`**，会被 Context
   覆盖，只传 `value`。
 - **`Switch` 的 `onChange` 参数是原生 `ChangeEvent`**，取值要 `e.currentTarget.checked`。
@@ -147,9 +148,11 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 
 ### 浮层与移动端
 
+- **命令式 `modals` 须在根部挂一次 `ModalManager`**；`open()` 返回 id，
+  `close(id)` 定向关闭，`closeAll()` 全关；确认 / 取消先关弹窗再调用回调。
 - **`DataFilter` 里的下拉控件（`Select` / `MultiSelect` / `TreeSelect` / `DatePicker`）
   保持 `withinPortal` 默认的 `true`，不要设 `false`** —— 设了下拉层会被 DataFilter 的
-  滚动容器裁剪。嵌套浮层的外部点击、焦点范围、层级和逐层 Escape 由基础 `Popover` 统一处理。
+  滚动容器裁剪。嵌套浮层的层级与关闭规则由 `overlay-layer` 统一处理。
 - **移动端标题靠 `placeholder` / `title`**（`Select` / `MultiSelect` 用前者，
   `Menu` / `Combobox.Dropdown` / `Filter` 用后者）。桌面端可能不显示，但在移动端
   它是底部弹层的标题，不传就是没标题。
@@ -162,10 +165,9 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
   再放交互元素会触发 a11y 的 `nested-interactive` 违规。
 - **不要给 `Filter` / `IconFilter` 的 `buttonProps` / `iconButtonProps` 传 `onClick`**，
   会覆盖内置的弹层开关，导致弹不出来。
-- **`Popover` 的三个静默陷阱**：受控（传了 `opened`）漏传 `onOpenChange`，所有内部触发连同两个
-  hover 延迟一起失效（`trigger="none"` 除外，开发环境有 warn）；开关按钮在浮层外时要
-  `closeOnClickOutside={false}`，否则 `mousedown` 捕获阶段的关闭早于按钮自己的 `click`；子元素上
-  与 `trigger` 同名的 handler 会被 `Popover.Target` 覆盖丢弃，要保留就传给 `<Popover.Target>` 自身。
+- **`Popover` 三个陷阱**：受控时须传 `onOpenChange`（`trigger="none"` 除外）；
+  外部开关按钮须设 `closeOnClickOutside={false}`，避免 mousedown 先关、click 又打开；
+  子元素上与 `trigger` 同名的 handler 须传给 `<Popover.Target>`，否则会被覆盖。
 
 ### 文本与截断
 
@@ -200,7 +202,7 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 
 - ❌ **从 `@mantine/core` 导入 `Box` / `Text` / `Flex` / `Group` / `Stack` / `Paper` /
   `UnstyledButton`。** 这些在 `@wisdomgarden/torque` 里都有同名替代品，行为和默认值
-  是本设计系统的，不是 Mantine 的。其他 Mantine 交互组件同理 —— 库里有的一律用库里的。
+  是本设计系统的。其他 Mantine 交互组件同理 —— 库里有的一律用库里的。
 - ❌ **Mantine style props**：`p` / `m` / `bg` / `c` / `fz` / `fw` / `sx` / `styles`。
   一律用 `className` + Tailwind。（`Flex` / `Group` / `Stack` 的 `gap` / `align` /
   `justify` 是本库自己的 props，接受设计 token，不在此列。）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wisdomgarden/torque-knowledge",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Machine-readable knowledge artifact for @wisdomgarden/torque — component catalog (SQLite) and AI coding rules (Markdown). Consumed by CI code review and local AI tooling, not by application runtime.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",