@linkdesk/plugin-docs 0.1.9 → 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.
|
@@ -703,7 +703,48 @@ The three rules above govern **names**; this one governs **territory**. For cust
|
|
|
703
703
|
|
|
704
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
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 (the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
|
|
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).
|
|
707
748
|
|
|
708
749
|
---
|
|
709
750
|
|
|
@@ -726,6 +767,7 @@ The three rules above govern **names**; this one governs **territory**. For cust
|
|
|
726
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) |
|
|
727
768
|
| Text | `t()` | `useTranslation()` from `react-i18next` |
|
|
728
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) |
|
|
729
771
|
| Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
|
|
730
772
|
|
|
731
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.**
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -695,7 +695,55 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
695
695
|
> 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
|
|
696
696
|
> `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
|
|
697
697
|
> `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
|
|
698
|
-
>
|
|
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)。
|
|
699
747
|
|
|
700
748
|
---
|
|
701
749
|
|
|
@@ -718,6 +766,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
718
766
|
| UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
|
|
719
767
|
| 文字 | `t()` | `useTranslation()` from `react-i18next` |
|
|
720
768
|
| CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
|
|
769
|
+
| 元素 / id 选择器 | 必须挂在自己的根类之下 | 见 §12.6(无锚选择器不需要同名就能命中所有人的元素) |
|
|
721
770
|
| 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
|
|
722
771
|
|
|
723
772
|
**写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
|