@wisdomgarden/torque-knowledge 1.0.6 → 1.0.8

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.6",
-  "torque": "0.2.1",
-  "generatedAt": "2026-09-22T04:01:33.778Z"
+  "knowledge": "1.0.8",
+  "torque": "0.2.3",
+  "generatedAt": "2026-09-28T09:01:40.077Z"
 }

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.6` 生成，对应 `@wisdomgarden/torque@0.2.1`。
+> 由 `@wisdomgarden/torque-knowledge@1.0.8` 生成，对应 `@wisdomgarden/torque@0.2.3`。
 > 不要手改 —— 它是 npm 包解包出来的，下次装依赖就被覆盖。
 
 ## 导入方式
@@ -81,9 +81,11 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 | drawer | `Drawer`, `DrawerManager`, `drawers` |
 | bottom-drawer | `BottomDrawer` |
 | modal | `Modal` |
+| 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`。
@@ -149,7 +150,7 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
 
 - **`DataFilter` 里的下拉控件（`Select` / `MultiSelect` / `TreeSelect` / `DatePicker`）
   保持 `withinPortal` 默认的 `true`，不要设 `false`** —— 设了下拉层会被 DataFilter 的
-  滚动容器裁剪。嵌套浮层的外部点击、焦点范围、层级和逐层 Escape 由基础 `Popover` 统一处理。
+  滚动容器裁剪。嵌套浮层的层级与关闭规则由 `overlay-layer` 统一处理。
 - **移动端标题靠 `placeholder` / `title`**（`Select` / `MultiSelect` 用前者，
   `Menu` / `Combobox.Dropdown` / `Filter` 用后者）。桌面端可能不显示，但在移动端
   它是底部弹层的标题，不传就是没标题。
@@ -162,9 +163,10 @@ Component 里用（函数跨 Server/Client 边界无法序列化）。
   再放交互元素会触发 a11y 的 `nested-interactive` 违规。
 - **不要给 `Filter` / `IconFilter` 的 `buttonProps` / `iconButtonProps` 传 `onClick`**，
   会覆盖内置的弹层开关，导致弹不出来。
-- **`Popover` 的 `closeDelay`（仅 `trigger="hover"` 生效）浮层内有可交互内容时不要设为
-  `0`** —— 默认 `100`ms 是留给鼠标从触发元素滑进浮层的缓冲，设成 0 会导致内容还没点到
-  就先关闭了。
+- **`Popover` 的三个静默陷阱**：受控（传了 `opened`）漏传 `onOpenChange`，所有内部触发连同两个
+  hover 延迟一起失效（`trigger="none"` 除外，开发环境有 warn）；开关按钮在浮层外时要
+  `closeOnClickOutside={false}`，否则 `mousedown` 捕获阶段的关闭早于按钮自己的 `click`；子元素上
+  与 `trigger` 同名的 handler 会被 `Popover.Target` 覆盖丢弃，要保留就传给 `<Popover.Target>` 自身。
 
 ### 文本与截断
 
@@ -199,7 +201,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.6",
+  "version": "1.0.8",
   "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",