@linkdesk/plugin-docs 0.1.8 → 0.1.10

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.
@@ -668,6 +668,84 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
668
668
  - **What happens if you don't**: exactly the silent failure described in 12.1—the selector just stops matching and those few rules quietly stop applying. **No error.**
669
669
  - **When you must change it**: when you move to **`@linkdesk/ui` 0.3.0**. `^0.2.0` does not resolve `0.3.0` (that's how 0.x ranges work), so nothing breaks until you upgrade deliberately. **Grep your own CSS for the old names** after upgrading: an official plugin (`settings`) had exactly one such spot and it was fixed in the same release batch.
670
670
 
671
+ ### 12.5 The **scope** of custom properties—`--x:` written under `:root` is written for the whole application
672
+
673
+ The three rules above govern **names**; this one governs **territory**. For custom properties (`--xxx`) there is exactly one rule:
674
+
675
+ > **Scope is the namespace.** The name is yours to choose; **which subtree it lives in** is what decides who it belongs to.
676
+
677
+ **① Document-level scope is the host's alone.** Declarations on `:root` / `html` / `body` / `[data-theme="…"]` / `*` are **visible to the entire document**—that is not your territory:
678
+
679
+ ```css
680
+ /* ❌ this declaration is visible to the whole document */
681
+ :root { --my-panel-gap: 8px; }
682
+
683
+ /* ✅ hang it under your own root class: scope = your subtree */
684
+ .my-plugin-root { --my-panel-gap: 8px; }
685
+ ```
686
+
687
+ **② Every other declaration hangs under one of your own classes.** Write `.your-class { --xxx: … }`—and note that **the name needs no prefix there**: a `--gap` under `:root` collides with someone else's, a `--gap` under `.my-plugin-root` cannot (the scope has already divided the territory).
688
+
689
+ **③ Nobody may define a `--ldk-*` custom property** (same rule as class names and keyframes—the whole `ldk-` namespace belongs to the host).
690
+
691
+ **Why this is nastier than a class-name collision**: most of the host's colors / radii / z-index layers are **provided by its stylesheets rather than written by code**. Write one of the host's contract names (say `--bg-card`) under `:root` and **you win**—the whole application's card background follows your value. And **switching themes may switch it back** (a theme overrides some of those names) ⇒ the symptom is "**works sometimes, breaks sometimes**", the hardest kind to diagnose.
692
+
693
+ **One self-check** (glance at it when your CSS is done): **"is my `--x:` written under `:root`?"** If yes ⇒ move it under your own root class.
694
+
695
+ **Migrating**—plugins that already define custom properties under `:root`:
696
+
697
+ | Case | Level | What to do |
698
+ |---|---|---|
699
+ | Name **carries** your own prefix (`--my-plugin-gap`) | 🟡 suggested | Move it under your own root class. The name is yours and nobody competes for it, but there is no reason for it to sit under `:root`—after the move its scope shrinks from the whole document to your own subtree |
700
+ | Name **carries no** prefix (`--gap`, `--bg-card`, …) | 🔴 required | It is live document-wide right now and may already be overriding the host's or another plugin's value ⇒ move it under your own root class (the name may stay as it is; **what changes is the scope**) |
701
+ | Name starts with `ldk-` | 🔴 required | Give it one of your own names—`ldk-` is the host's namespace |
702
+ | Written **under your own root class** | ✅ compliant | Nothing to do. Fine-tuning like `.your-root .ldk-x { --y: … }` is compliant too (one of your own classes appears in the selector) |
703
+
704
+ **How it is enforced mechanically**: run `npm run lint` in the plugin project root (or `npm run verify` in CI) and each occurrence is reported—🔴 turns CI red, 🟡 only prints. When "it works locally but CI is red", read this section first.
705
+
706
+ > 🔧 **Maintainer note (authors may skip)**: the rule text (including how the host registers its contract blocks and the floating-layer host exception) lives under `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/`; the shell side is guarded by `scripts/check-css-namespace.mjs`, the plugin side by the SDK's `check-css-namespace` leg (token scope is the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
707
+
708
+ ### 12.6 The selector itself needs a "landing spot" too—**anchorless selectors are forbidden** (2026-09-16)
709
+
710
+ The five sections above govern **names** (class names / keyframes / custom properties). This one governs the **shape of the selector**—a rule that is even easier to overlook:
711
+
712
+ > **Class names and ids are "name anchors"; element / universal / attribute / pseudo-class / pseudo-element selectors are not.**
713
+ > The latter hit other people's elements **without sharing a single name with anyone.**
714
+
715
+ ```css
716
+ /* ❌ one rule rewrites *every* button in the document—including the host's and other plugins' */
717
+ button { border: none; }
718
+ * { box-sizing: border-box; }
719
+ #some-id { display: none; } /* an id is global and guessable too, and outranks classes */
720
+ :root { outline: none; } /* `:root` is an anchorless selector as well */
721
+
722
+ /* ✅ hang it under your own root class—same intent, landing spot limited to your own subtree */
723
+ .my-plugin-root button { border: none; }
724
+ ```
725
+
726
+ **Two rules** (both are **mechanically red** in `npm run lint` at the plugin project root / `npm run verify` in CI):
727
+
728
+ | Rule | Verdict | Why |
729
+ |---|---|---|
730
+ | **No anchorless selectors** | The selector has **no** `.class` or `#id` subject (element / universal / attribute / pseudo-class / pseudo-element; **top-level *and* qualified, including inside `@media`**) ⇒ 🔴 | It hits "every element of that kind in the document", regardless of who rendered it |
731
+ | **A cross-party hit must carry your own anchor** | The selector mentions an `ldk-*` class (**including a mention inside `:has(…)`**) but does **not** carry a `.<your pluginId>-*` class ⇒ 🔴 | `ldk-` is the host's namespace; **fine-tuning has to happen on your own territory** |
732
+
733
+ ⚠️ **The second rule does not forbid restyling shared components**—that is a **legitimate feature** (scoped tuning). It only requires you to **carry your own prefix as the anchor**:
734
+
735
+ ```css
736
+ /* ❌ targets the host's / shared components' elements with no landing spot of your own ⇒ red */
737
+ .ldk-toggle { transform: scale(1.1); }
738
+
739
+ /* ✅ the same intent, written on your own territory ⇒ compliant */
740
+ .my-plugin-root .ldk-toggle { transform: scale(1.1); }
741
+ ```
742
+
743
+ **Why it is worth remembering**: the host itself has **17** such "anchorless selectors" (`*` resets / `html`·`body` / `[data-theme]` / `*:focus-visible` / the scrollbar family / `input[type="number"]`·`select`)—they are a **deliberate shared baseline** that plugins rely on (and may override). Precisely because they exist, **your anchorless selector will hit them**: write `button { }` and the host's buttons plus every other plugin's buttons change with it.
744
+
745
+ **Migration**: **zero instances today**—a full re-check of the 18 official plugins plus the in-repo fixtures (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
746
+
747
+ > 🔧 **Maintainer note (authors may skip)**: the rule text (R0 scope / R1 host baseline / R2 / R3) plus the decision formulas and negative controls live in `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`; the host side is guarded by criteria ⑩⑪ of `scripts/check-css-namespace.mjs` (plus the runtime mirror on axis ④ of the probe), and the plugin side by the **fourth criterion** of the SDK's `check-css-namespace` leg (`checks/selector-form.ts`, S2/S3).
748
+
671
749
  ---
672
750
 
673
751
  ## Quick Reference
@@ -689,6 +767,7 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
689
767
  | UI discipline gate | `linkdesk-plugin-sdk lint` | all 15 items are WARNs that never fail; a knowing bypass = a standard eslint-disable declaration (see §11.2) |
690
768
  | Text | `t()` | `useTranslation()` from `react-i18next` |
691
769
  | CSS class names / state classes | own prefix + host reserved-name list | see §12 (class names are global—all plugins share the document with the host) |
770
+ | Element / id selectors | must hang under your own root class | see §12.6 (an anchorless selector hits everyone's elements, name or no name) |
692
771
  | Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
693
772
 
694
773
  **Use these facilities when writing plugins; don't hand-roll. Even if you write one, it'll have to be torn out later—better to normalize from day one.**
@@ -652,6 +652,99 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
652
652
  - **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
653
653
  - **什么时候必须改**:升到 **`@linkdesk/ui` 0.3.0** 时。`^0.2.0` 不会解析到 `0.3.0`(0.x 的范围就是这么算的),所以你不主动升级就不会坏。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
654
654
 
655
+ ### 12.5 自定义属性的**作用域**——`--x:` 写在 `:root` 里就等于写给整个软件
656
+
657
+ 类名那三条纪律管的是**名字**,这一节管**地盘**。自定义属性(`--xxx`)的规矩只有一句:
658
+
659
+ > **作用域才是命名空间。** 名字随你起,**它住在哪棵子树里**才是它属于谁。
660
+
661
+ **① 文档级的作用域只有宿主能用。** `:root` / `html` / `body` / `[data-theme="…"]` / `*` 上的定义
662
+ **对整个文档可见**——那不是你的地盘:
663
+
664
+ ```css
665
+ /* ❌ 这条定义全文档可见 */
666
+ :root { --my-panel-gap: 8px; }
667
+
668
+ /* ✅ 挂在你自己的根类之下,作用域 = 你的子树 */
669
+ .my-plugin-root { --my-panel-gap: 8px; }
670
+ ```
671
+
672
+ **② 其余定义一律挂在自己的类之下。** 写 `.你的类 { --xxx: … }` 就好——**这里的名字不需要任何前缀**:
673
+ `:root` 上的 `--gap` 会跟别人撞,`.my-plugin-root` 下的 `--gap` 不会(作用域已经把地盘划开了)。
674
+
675
+ **③ `--ldk-*` 自定义属性谁都不许定义**(和类名、关键帧同一条规矩——整个 `ldk-` 命名空间是宿主的)。
676
+
677
+ **为什么这条比类名还凶**:宿主大部分颜色 / 圆角 / 层级**不是由程序写上去的、而是靠样式表提供的**。
678
+ 你在 `:root` 里写一个宿主的契约名(比如 `--bg-card`),**你会赢**——整个软件的卡片底色跟着变;
679
+ 而且**换个主题可能又变回来**(主题会覆盖其中一部分名字)⇒ 症状是「**时好时坏**」,最难查的一类。
680
+
681
+ **一条自检**(写完 CSS 顺手看一眼):**「我的 `--x:` 是不是写在 `:root` 里?」** 是 ⇒ 搬进你自己的根类。
682
+
683
+ **迁移**——已经在 `:root` 里写过自定义属性的插件:
684
+
685
+ | 情形 | 判级 | 怎么办 |
686
+ |---|---|---|
687
+ | 名字**带**你自己的前缀(`--my-plugin-gap`) | 🟡 建议改 | 搬进自己的根类。名字是你的、没人跟你抢,但「写在 `:root`」本身没有理由——改完作用域从整个文档缩回你自己的子树 |
688
+ | 名字**不带**前缀(`--gap`、`--bg-card`…) | 🔴 必须改 | 它此刻在全文档生效、可能正覆盖着宿主或别的插件的值 ⇒ 把它搬进自己的根类(名字可以照旧保留,**换的是作用域**) |
689
+ | 名字以 `ldk-` 开头 | 🔴 必须改 | 换成你自己的名字——`ldk-` 是宿主命名空间 |
690
+ | 写在**自己的根类**之下 | ✅ 合规 | 不用动。`.你的根类 .ldk-x { --y: … }` 这类**微调**同样合规(选择器里有你自己的类就行) |
691
+
692
+ **它怎么被机械守住**:在插件工程根跑 `npm run lint`(或 CI 里的 `npm run verify`)会逐条报出来
693
+ ——🔴 会让 CI 红,🟡 只提示不拦。「我的插件本地好好的、CI 却红」时先看这一段。
694
+
695
+ > 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
696
+ > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
697
+ > `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
698
+ > (token 作用域是那条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
699
+
700
+ ### 12.6 选择器本身也要有「落点」——**禁写无锚选择器**(2026-09-16)
701
+
702
+ 前五节管的是**名字**(类名 / 关键帧 / 自定义属性)。这一节管**选择器的形态**——一条更容易忽略的规矩:
703
+
704
+ > **类名和 id 是「名字锚」;元素 / 通配 / 属性 / 伪类 / 伪元素不是。**
705
+ > 后者**不需要与任何人同名**就能命中别人的元素。
706
+
707
+ ```css
708
+ /* ❌ 一条规则改掉「这个文档里所有」的按钮——宿主和其他插件的按钮全在内 */
709
+ button { border: none; }
710
+ * { box-sizing: border-box; }
711
+ #some-id { display: none; } /* id 也是全局的、可猜的,优先级还高于类 */
712
+ :root { outline: none; } /* `:root` 同样是无锚选择器 */
713
+
714
+ /* ✅ 挂在自己的根类之下——同一个意图,落点只有你自己的子树 */
715
+ .my-plugin-root button { border: none; }
716
+ ```
717
+
718
+ **两条规则**(都在插件工程根 `npm run lint` / CI `npm run verify` 里**机械判红**):
719
+
720
+ | 规则 | 判定 | 为什么 |
721
+ |---|---|---|
722
+ | **禁无锚选择器** | 选择器**没有**任何 `.类` 或 `#id` 主体(元素 / 通配 / 属性 / 伪类 / 伪元素;**顶层或限定一律禁,`@media` 内也算**)⇒ 🔴 | 它命中「该文档里所有那一类元素」,与谁渲染无关 |
723
+ | **跨方命中必须自带自有锚** | 选择器里出现 `ldk-*` 类(**含 `:has(…)` 内的提及**)却**不带** `.<你的 pluginId>-*` 类 ⇒ 🔴 | `ldk-` 是宿主命名空间;**调优必须发生在自己的地盘里** |
724
+
725
+ ⚠️ **第二条不影响「改共享组件外观」这件事本身**——那是**合法特性**(scoped 调优)。它只要求你**带着自家前缀作锚**:
726
+
727
+ ```css
728
+ /* ❌ 改的是宿主/共享组件的元素,自己却一点落点都没有 ⇒ 判红 */
729
+ .ldk-toggle { transform: scale(1.1); }
730
+
731
+ /* ✅ 同一个意图,写在自己的地盘里 ⇒ 合规 */
732
+ .my-plugin-root .ldk-toggle { transform: scale(1.1); }
733
+ ```
734
+
735
+ **为什么值得专门记住**:宿主自己就有 **17 处**这样的「无锚选择器」(`*` 重置 / `html`·`body` /
736
+ `[data-theme]` / `*:focus-visible` / 滚动条一族 / `input[type="number"]`·`select`)——它们**是有意的
737
+ 共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
738
+ 你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
739
+
740
+ **迁移**:**今天 0 存量**——官方 18 只插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
741
+ 的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
742
+
743
+ > 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
744
+ > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
745
+ > 宿主侧由 `scripts/check-css-namespace.mjs` 的判据⑩⑪(+ 探针轴 ④ 的运行时镜像)守着,
746
+ > 插件侧由 SDK 的 `check-css-namespace` 腿的**第四条判据**守着(`checks/selector-form.ts`,S2/S3)。
747
+
655
748
  ---
656
749
 
657
750
  ## 速查
@@ -673,6 +766,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
673
766
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
674
767
  | 文字 | `t()` | `useTranslation()` from `react-i18next` |
675
768
  | CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
769
+ | 元素 / id 选择器 | 必须挂在自己的根类之下 | 见 §12.6(无锚选择器不需要同名就能命中所有人的元素) |
676
770
  | 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
677
771
 
678
772
  **写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [