@linkdesk/plugin-docs 0.1.7 → 0.1.9

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.
@@ -556,14 +556,14 @@ both stylesheets land on the same element.
556
556
 
557
557
  | Reserved keyframe names | Notes |
558
558
  |---|---|
559
- | `selectbox-in` | the shared select dropdown's entrance animation |
560
- | `drop-zone-in` | the drop zone's entrance animation |
561
- | `dropdown-card-in` | the dropdown card's entrance animation |
562
- | `floating-panel-in` | the floating panel's entrance animation |
563
- | `group-tab-enter` | the group tab's entrance animation |
564
- | `group-tab-exit` | the group tab's exit animation |
565
- | `notif-icon-spin` | the notification icon's spin |
566
- | `notif-progress-scan` | the notification progress scan |
559
+ | `ldk-selectbox-in` | the shared select dropdown's entrance animation |
560
+ | `ldk-drop-zone-in` | the drop zone's entrance animation |
561
+ | `ldk-dropdown-card-in` | the dropdown card's entrance animation |
562
+ | `ldk-floating-panel-in` | the floating panel's entrance animation |
563
+ | `ldk-group-tab-enter` | the group tab's entrance animation |
564
+ | `ldk-group-tab-exit` | the group tab's exit animation |
565
+ | `ldk-notif-icon-spin` | the notification icon's spin |
566
+ | `ldk-notif-progress-scan` | the notification progress scan |
567
567
 
568
568
  > 🔧 **Maintainer note (authors can skip this)**—the **Reserved names** and **Reserved keyframe names** columns in the two tables above are **machine-read**: the gate
569
569
  > in `npm run check` (`scripts/check-reserved-names-doc-sync.mjs`) cross-checks them **both ways** against the
@@ -645,6 +645,66 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
645
645
  - **What happens if you don't**: the input doesn't error; it simply **loses the host-provided appearance** (background / border / radius / padding) and looks like a browser-native input.
646
646
  - **When you must change it**: as soon as you run on the **new shell**. The new shell version is **`0.2.0`**, and both official plugins now declare `minAppVersion: "0.2.0"` in `plugin.json`—declare the same value in your plugin and users on an older shell get a clear "requires app version ≥0.2.0" message instead of an unstyled input (see [04-distribution-format §minAppVersion](04-distribution-format.md) for the semantics).
647
647
 
648
+ ### 12.4 The rest of the shared components' class names took the `ldk-` prefix too (2026-09-16)
649
+
650
+ **In one line: same story as 12.1, just for the components that 12.1 didn't cover—if your own CSS tunes those components with descendant selectors, add the `ldk-` prefix when you upgrade.**
651
+
652
+ - **What changed**: §12.1 covered the eight base names of `@linkdesk/ui` (`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`) at **0.2.0**. The remaining components' class names—plus one `@keyframes` name—now carry the prefix too, at **`@linkdesk/ui` 0.3.0**:
653
+
654
+ | Old family | New family |
655
+ |---|---|
656
+ | `.colorpicker-*` | `.ldk-colorpicker-*` |
657
+ | `.ctx-*` | `.ldk-ctx-*` |
658
+ | `.form-row` | `.ldk-form-row` |
659
+ | `.inline-input`, `.inline-input--compact/--normal` | `.ldk-inline-input`, `.ldk-inline-input--compact/--normal` |
660
+ | `.number-input*` | `.ldk-number-input*` |
661
+ | `.segmented-radio`, `.segmented-radio__option/__label` | `.ldk-segmented-radio`, `.ldk-segmented-radio__option/__label` |
662
+ | `.sidebar-section*`, `.sidebar-pane-view`, `.sidebar-pane-sash` | `.ldk-sidebar-section*`, `.ldk-sidebar-section-pane-view`, `.ldk-sidebar-section-pane-sash` |
663
+ | `.theme-picker*`, `.theme-card`, `.theme-preview` | `.ldk-theme-picker*`, `.ldk-theme-picker-card`, `.ldk-theme-picker-preview` |
664
+ | `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot` (theme-card internals) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
665
+ | `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
666
+
667
+ - **Who is affected**: again **only your own CSS**'s descendant selectors that point at those components (e.g. `.settings-row:has(.theme-picker)`). **The components' own styling does not change, and your own class names stay as they are.** The whole point is that the shared components' names now all live in the `ldk-` namespace, whose rule you already know: **anything starting with `ldk-` belongs to the host—don't put it on your own elements** (the one exception is `.ldk-input`, the utility that is **for you**).
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
+ - **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
+
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 (the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
707
+
648
708
  ---
649
709
 
650
710
  ## Quick Reference
@@ -551,14 +551,14 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
551
551
 
552
552
  | 保留的关键帧名 | 说明 |
553
553
  |---|---|
554
- | `selectbox-in` | 共享组件下拉框的入场动画 |
555
- | `drop-zone-in` | 拖放区的入场动画 |
556
- | `dropdown-card-in` | 下拉卡片的入场动画 |
557
- | `floating-panel-in` | 浮动面板的入场动画 |
558
- | `group-tab-enter` | 分组标签的入场动画 |
559
- | `group-tab-exit` | 分组标签的退场动画 |
560
- | `notif-icon-spin` | 通知图标的旋转 |
561
- | `notif-progress-scan` | 通知的进度扫描 |
554
+ | `ldk-selectbox-in` | 共享组件下拉框的入场动画 |
555
+ | `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
556
+ | `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
557
+ | `ldk-floating-panel-in` | 浮动面板的入场动画 |
558
+ | `ldk-group-tab-enter` | 分组标签的入场动画 |
559
+ | `ldk-group-tab-exit` | 分组标签的退场动画 |
560
+ | `ldk-notif-icon-spin` | 通知图标的旋转 |
561
+ | `ldk-notif-progress-scan` | 通知的进度扫描 |
562
562
 
563
563
  > 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
564
564
  > (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
@@ -629,6 +629,74 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
629
629
  - **不改会怎样**:输入框**不报错**,只是**失去宿主给的外观**(底色 / 边框 / 圆角 / 内边距),看起来像浏览器原生输入框。
630
630
  - **什么时候必须改**:在**新壳**上跑就要改。新壳的版本号是 **`0.2.0`**,官方两只插件都已在 `plugin.json` 里声明 `minAppVersion: "0.2.0"`——你也给自己的插件声明同一个值,旧壳上的用户就会收到一句清楚的「需要应用版本 ≥0.2.0」提示,而不是看到一个没样式的输入框(`minAppVersion` 的语义见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
631
631
 
632
+ ### 12.4 共享组件剩下的类名也带 `ldk-` 了(2026-09-16)
633
+
634
+ **一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
635
+
636
+ - **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀,**`@linkdesk/ui` 0.3.0 起**:
637
+
638
+ | 旧族 | 新族 |
639
+ |---|---|
640
+ | `.colorpicker-*` | `.ldk-colorpicker-*` |
641
+ | `.ctx-*` | `.ldk-ctx-*` |
642
+ | `.form-row` | `.ldk-form-row` |
643
+ | `.inline-input`、`.inline-input--compact/--normal` | `.ldk-inline-input`、`.ldk-inline-input--compact/--normal` |
644
+ | `.number-input*` | `.ldk-number-input*` |
645
+ | `.segmented-radio`、`.segmented-radio__option/__label` | `.ldk-segmented-radio`、`.ldk-segmented-radio__option/__label` |
646
+ | `.sidebar-section*`、`.sidebar-pane-view`、`.sidebar-pane-sash` | `.ldk-sidebar-section*`、`.ldk-sidebar-section-pane-view`、`.ldk-sidebar-section-pane-sash` |
647
+ | `.theme-picker*`、`.theme-card`、`.theme-preview` | `.ldk-theme-picker*`、`.ldk-theme-picker-card`、`.ldk-theme-picker-preview` |
648
+ | `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot`(主题卡片内部) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
649
+ | `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
650
+
651
+ - **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
652
+ - **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
653
+ - **什么时候必须改**:升到 **`@linkdesk/ui` 0.3.0** 时。`^0.2.0` 不会解析到 `0.3.0`(0.x 的范围就是这么算的),所以你不主动升级就不会坏。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
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
+ > (同一条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
699
+
632
700
  ---
633
701
 
634
702
  ## 速查
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [