@linkdesk/plugin-docs 0.1.79 → 0.1.80

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -874,50 +874,6 @@ Four attributes, all written on your own DOM elements:
874
874
 
875
875
  ---
876
876
 
877
- ## 14. Self-drawn floating surfaces → the `--ldk-pop-*` recipe tokens (glass-correct out of the box)
878
-
879
- **Read this section when** you are about to self-draw any surface that **floats above other
880
- text**—menus, popovers, dropdowns, hover expansion layers. For things that already have a
881
- shared component (context menus / confirm dialogs), swap to it first (§1/§9/§Quick Reference);
882
- for what you truly must self-draw, this section guarantees you **never step on the glass
883
- pitfalls**.
884
-
885
- **Where the pit is (measured 2026-11-21, three-in-one)**: under a glass theme `--bg-card` is
886
- itself translucent—a floating surface using it raw = see-through (you can read the layer
887
- beneath) / double-layer ghosting (the body and the expansion layer visible at once, the lower
888
- layer's colors bleeding through) / destroyed text underneath. Image-backed themes are worse.
889
- Adding blur alone is not enough—blur is translucent, the lower layer's colors still bleed.
890
-
891
- **The recipe (derived by the ThemeEngine—zero configuration for authors)**: write these four
892
- lines and your floating surface is automatically correct under both glass and normal themes:
893
-
894
- ```css
895
- .your-pop {
896
- background: var(--ldk-pop-surface, var(--bg-card)); /* opaque base—auto-deepened to the readability floor under glass */
897
- backdrop-filter: var(--ldk-pop-blur); /* frost (glass: blur+1.15; non-glass: none) */
898
- border: 1px solid var(--ldk-pop-border, var(--border));
899
- box-shadow: var(--ldk-pop-shadow);
900
- }
901
- ```
902
-
903
- **Single-layer presentation (your responsibility)**: when the floating surface shows, the
904
- **duplicate body** beneath it must exit (`visibility: hidden`, or make the floating surface's
905
- base fully opaque and cover it dead)—under glass, without the exit you get two-layer ghosting
906
- and frost cannot save it. Rule: **one piece of content, one visible copy at a time**.
907
-
908
- **Mechanical backstop**: the `check-pop-surface` leg of `npm run check`—floating-surface class
909
- shapes (`menu/modal/dropdown/popover/popup/-over/float-panel`) using `--bg-card/--bg-input`
910
- raw in `background` fail the build; `--path <dir>` scans any css directory (for author repos).
911
-
912
- > 🔧 **Maintainer note (authors may skip)**: the tokens are derived by the shell ThemeEngine
913
- > `synthesizePopSurfaces` (glass: `--bg-card-solid` composed at `clamp(0.75, --glass-surface-alpha, 1)`
914
- > + `--glass-blur`; non-glass: card as-is + blur `none`), pushed to the pool with `theme:changed`—
915
- > zero wiring for plugins; the opacity-floor constant = `POP_SURFACE_MIN_ALPHA` (0.75, measured
916
- > readability floor). Hard-rule upgrade record: the 11-20 "⛔ self-drawn blur outside the float
917
- > layer" became "self-drawn floating surfaces outside the float layer **must consume `--ldk-pop-*`**;
918
- > ⛔ raw self-drawn blur / raw --bg-card floating surfaces" (self-drawing remains fully legal—
919
- > there is now a correct way to do it).
920
-
921
877
  ---
922
878
 
923
879
  ## Quick Reference
@@ -925,7 +881,6 @@ raw in `background` fail the build; `--path <dir>` scans any css directory (for
925
881
  | What you want to do | Core facility | How to bring it in |
926
882
  |---|---|---|
927
883
  | Context menu | `<ContextMenu>` (open-string menuId) | `@linkdesk/ui` (ContextMenu) + a `plugin.json contributes.menus` declaration (or `window.linkdesk.menu.registerItems`, see §1) |
928
- | Self-drawn floating surfaces (menus/popovers/expansion layers) | `--ldk-pop-surface / -blur` | consume the CSS variables directly (see §14; glass-correct out of the box; raw --bg-card fails the build) |
929
884
  | Overlay/dialog | `createPortal` | `react-dom` (render into `document.body`, see §2) |
930
885
  | Persistence | `window.linkdesk.configuration.get/set/onChange` | plugin communication iron rule—only `window.linkdesk.*` (see §3) |
931
886
  | System picker | `window.linkdesk.quickPick.show` | uniform rendering by the in-pool QuickPickHost (see §9) |
@@ -868,40 +868,6 @@ import { HintTip } from "@linkdesk/ui";
868
868
 
869
869
  ---
870
870
 
871
- ## 14. 自绘浮起面 → `--ldk-pop-*` 配方 token(玻璃正确开箱即得)
872
-
873
- **什么时候读这节**:你要自绘任何「浮在别的字上面」的面——菜单、弹层、下拉、hover 展开层。
874
- 右键菜单/确认框这类**有现成共享件**的先换装(§1/§9/橱窗判据);确需自绘的,本节保证你
875
- **不用踩玻璃的坑**。
876
-
877
- **坑在哪(2026-11-21 实测三连)**:玻璃主题下 `--bg-card` 本身半透——浮起面裸用它=
878
- 「透底(能看穿到下层)/双层叠影(本体+展开层同时可见,下层颜色糊透)/下层文字全毁」。
879
- 带图片的主题尤其糟。光加磨砂也不够——磨砂半透,下层颜色照样糊透。
880
-
881
- **配方(ThemeEngine 派生,作者零配置)**:你的浮起面只要写这四行,玻璃/普通主题都自动正确:
882
-
883
- ```css
884
- .your-pop {
885
- background: var(--ldk-pop-surface, var(--bg-card)); /* 不透明基底——玻璃态自动加深到可读下限 */
886
- backdrop-filter: var(--ldk-pop-blur); /* 磨砂(玻璃态 blur+1.15;非玻璃态 none) */
887
- }
888
- ```
889
-
890
- **单层呈现(必须自己负责)**:浮起面显示时,被它盖住的**重复本体**要退场
891
- (`visibility: hidden` 或让浮起面基底完全不透明盖死)——玻璃下不退场=两层叠影,
892
- 磨砂救不了。规则:**同一内容同一时刻只呈现一份**。
893
-
894
- **机械兜底**:`npm run check` 的 `check-pop-surface` 腿——浮起面类名形态
895
- (`menu/modal/dropdown/popover/popup/-over/float-panel`)里 `background` 裸用
896
- `--bg-card/--bg-input` 直接判红;`--path <目录>` 可扫任意 css 目录(作者仓自查用)。
897
-
898
- > 🔧 **维护者注(作者可跳过)**:token 由壳 ThemeEngine `synthesizePopSurfaces` 派生
899
- > (玻璃态 = `--bg-card-solid` 按 `clamp(0.75, --glass-surface-alpha, 1)` 合成+`--glass-blur`;
900
- > 非玻璃态 = card 原样+blur none),随 `theme:changed` 推到池——插件零接线;
901
- > 不透明度下限常量 = `POP_SURFACE_MIN_ALPHA`(0.75,实测可读下限)。硬规定升级记录:
902
- > 11-20「⛔ 浮层外自绘 blur」→「浮层外自绘浮起面必须消费 `--ldk-pop-*`,⛔ 裸自绘 blur/裸
903
- > --bg-card 浮面」(自绘依然合法,只是有正确姿势)。
904
-
905
871
  ---
906
872
 
907
873
  ## 速查
@@ -918,7 +884,6 @@ import { HintTip } from "@linkdesk/ui";
918
884
  | 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
919
885
  | 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
920
886
  | 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
921
- | 自绘浮起面(菜单/弹层/展开层) | `--ldk-pop-surface / -blur` | CSS 变量直接消费(见 §14;玻璃正确开箱即得,⛔ 裸 --bg-card 判红) |
922
887
  | 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
923
888
  | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
924
889
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.79",
3
+ "version": "0.1.80",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [