@linkdesk/plugin-docs 0.1.3 → 0.1.4

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.
@@ -533,19 +533,37 @@ host's styles, the shared components' (`@linkdesk/ui`) styles, and **every loade
533
533
  **class names are global identifiers**. Writing a class name claims that name; if someone else uses it too,
534
534
  both stylesheets land on the same element.
535
535
 
536
- **Two rules:**
537
-
538
- 1. **Give your own elements prefixed class names**—that's what the official plugins do (`settings-*`, `ms-*`,
539
- `mpd-*`). Use your plugin name or an abbreviation as the prefix, not something obviously generic like
540
- `.active-panel`.
541
- 2. **These names are reserved by the host—don't use them for your own elements** (if you do, the host's
536
+ **Three rules:**
537
+
538
+ 1. **Class names you give your own elements must start with your `pluginId` plus a hyphen**—
539
+ `settings-*`, `editor-*`, `file-tree-*` … (`pluginId` is the id you declare in `plugin.json`; every
540
+ official plugin does this). **Don't use abbreviations**: the `ms-` / `mpd-` shorthand style is **retired**—
541
+ an abbreviation guarantees nothing, and two plugins that each abbreviate to `ms-` collide. `pluginId` is
542
+ unique by construction (immutable once published), so deriving the prefix from it is free collision
543
+ protection.
544
+ 2. **`@keyframes` names take the prefix too** (`file-tree-fadeIn`), and **rename the `animation:` reference in
545
+ the same edit**—a keyframe name is a global identifier exactly like a class name: on a collision the later
546
+ definition wins and the earlier animation silently stops.
547
+ 3. **These names are reserved by the host—don't use them for your own elements** (if you do, the host's
542
548
  styles will hit you):
543
549
 
544
550
  | Source | Reserved names | Notes |
545
551
  |---|---|---|
546
552
  | Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
547
- | Host global utility classes | `.titlebar`, `.divider`, `.about`, `.rn`, `.vta` | The host UI's own container names; don't reuse them |
548
- | Shared component public classes | `.badge`, `.button`, `.combobox`, `.mdv`, `.selectbox`, `.sle`, `.slider`, `.toggle` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui` |
553
+ | Shared component classes + host container classes | **the whole `ldk-` namespace**—today: `ldk-badge`, `ldk-button`, `ldk-combobox`, `ldk-mdv`, `ldk-selectbox`, `ldk-sle`, `ldk-slider`, `ldk-toggle` (shared components), plus the host's own container classes such as `ldk-titlebar` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui`. **You don't have to memorize them**—remember one thing: **anything starting with `ldk-` belongs to the host itself (shared components + host UI containers), so don't put it on your own elements** |
554
+
555
+ > 🔧 **Maintainer note (authors can skip this)**—the **Reserved names** column is **machine-read**: the gate
556
+ > in `npm run check` (`scripts/check-reserved-names-doc-sync.mjs`) cross-checks it **both ways** against the
557
+ > registry `packages/plugin-sdk/schemas/reserved-class-names.json`—every registry name must appear here, and
558
+ > every name here must either be registered (bare names) or a real `ldk-` name present in the host source.
559
+ > ⇒ **Editing this column is a public-surface change**: add/remove a name in **three places in one commit**—
560
+ > the registry plus this table in both language trees. This column holds **class names only**; put prose in
561
+ > the third column.
562
+
563
+ **One more namespace rule**: your `pluginId` **must not start with `ldk-`**—the whole `ldk-` namespace belongs
564
+ to the host, so a plugin called `ldk-tools` would derive its prefix (`ldk-tools-*`) **straight into host
565
+ territory**, which also makes rule 1 meaningless. This constraint lives in the `plugin.json` schema, so your
566
+ editor flags it immediately.
549
567
 
550
568
  **Want their look? Use their component**—`import { Button } from "@linkdesk/ui"`, don't hand-write its class
551
569
  name (hand-writing bypasses the component, and you fall behind the moment it changes).
@@ -557,6 +575,53 @@ name (hand-writing bypasses the component, and you fall behind the moment it cha
557
575
  painted the background and the text the same color, so the text was swallowed by its own background — the UI
558
576
  just looked like "a solid block". **No error**, just wrong, and hard to trace.
559
577
 
578
+ ### 12.1 Upgrading from an older `@linkdesk/ui`—the one thing you have to change yourself
579
+
580
+ Shared component class names now carry an `ldk-` prefix (as of `@linkdesk/ui` **0.2.0**). This affects exactly
581
+ one kind of code: rules in **your own plugin's CSS** that use a descendant selector to fine-tune a shared
582
+ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix.**
583
+
584
+ - **When it hits you**: after `@linkdesk/ui` moves to **0.2.0**—**not before**. In older versions these
585
+ components' class names were bare (`.badge`), and the CSS shipped inside the package is consistent with the
586
+ components, so **if you don't upgrade, nothing breaks**. (A `^0.1.x` range will not cross over to `0.2.0` by
587
+ itself, so this only comes up on the upgrade you perform deliberately.)
588
+ - **What is affected**: descendant selectors in **your own plugin CSS** such as
589
+ `.control-bar .combobox { … }`, `.settings-slider-control .slider { … }`, `.changelog .mdv { … }`.
590
+ **The components' own styles are unaffected, and your own class names don't change.**
591
+ - **How to fix it**: add the `ldk-` prefix to **the part of the selector that points at the shared component**—
592
+ `.combobox` → `.ldk-combobox`, `.slider` → `.ldk-slider`, `.mdv` → `.ldk-mdv`, `.badge` → `.ldk-badge`,
593
+ `.selectbox-trigger` → `.ldk-selectbox-trigger`, `.combobox-field` → `.ldk-combobox-field`. **Family names
594
+ (suffixes like `-trigger` / `-field` / `-input`) take the prefix too.** Your own prefixes (`.control-bar`,
595
+ `.settings-*`) stay as they are. **After upgrading, grep your CSS for the eight old base names
596
+ `.badge`, `.button`, `.combobox`, `.mdv`, `.selectbox`, `.sle`, `.slider`, `.toggle`**: add the prefix where
597
+ the rule tunes a shared component, leave the rest alone.
598
+ - **Why it isn't automatically compatible**: this kind of mismatch **raises no error**—a selector that no
599
+ longer matches simply stops applying, so the UI looks "roughly right, just a bit off". Because it is silent,
600
+ we moved the names under the `ldk-` prefix and wrote this section.
601
+
602
+ ### 12.2 The prefix rules (§12 rules 1 and 2) are live—what about existing code?
603
+
604
+ **In one line: it keeps working unchanged, but the next time you touch that file is when you fix it.**
605
+
606
+ - **The official plugins have already been cleaned up under the new rules**—four plugins were renamed:
607
+ `file-tree` (v1.0.9), `settings` (v1.0.11), `serial-monitor` (v1.0.12) and `marketplace` (v1.0.33); their
608
+ bare class names and keyframe names now carry the `<pluginId>-` prefix. The remaining official plugin repos
609
+ had no bare definitions to begin with (their class names either already carry a prefix or they define none).
610
+ Measured against the official catalog, the audit reads **18/18 compliant**.
611
+ - **Third-party authors have no repository to change**: this rule governs only **the class and keyframe names
612
+ you write yourself**—it doesn't touch repo layout, your `pluginId`, or anyone else's code. You do **not**
613
+ need to cut a release for it.
614
+ - **Old unprefixed class names raise no error and don't stop working**—they work fine today. The cost is that
615
+ **the collision risk is still there**: if another plugin defines the same class name, both stylesheets land
616
+ on the same element (no error, just wrong-looking, and hard to trace).
617
+ - **Compliance is judged by the check that ships with your project**: a scaffolded project carries a strict
618
+ check leg (`npm run verify`) that scans your CSS for class names **bare-defined on your own elements** and
619
+ for `@keyframes` names, and fails them when they don't start with `<pluginId>-`. So the real action is
620
+ **rename them the next time you open that file**: `.panel {}` → `.myplugin-panel {}`, changing the CSS and
621
+ the JSX that uses it together (identifiers only—don't touch style values).
622
+
623
+ > Want to see whether your project has bare names right now? Run `npm run verify` in the project root.
624
+
560
625
  ---
561
626
 
562
627
  ## Quick Reference
@@ -532,17 +532,31 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
532
532
  (`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
533
533
  就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
534
534
 
535
- **两条纪律:**
535
+ **三条纪律:**
536
536
 
537
- 1. **给自己的元素起带前缀的类名**——官方插件就是这么做的(`settings-*`、`ms-*`、`mpd-*`)。
538
- 前缀用你自己的插件名或简写,别用 `.active-panel` 这种一看就通用的名字。
539
- 2. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
537
+ 1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
538
+ `pluginId` 就是你 `plugin.json` 里声明的那个 id(官方插件统统这么做)。**别用缩写**:`ms-`、
539
+ `mpd-` 这类简写写法**已经废弃**——缩写不保证唯一,两个插件各自缩写成 `ms-` 就撞在一起了;
540
+ 而 `pluginId` 的唯一性由发布流程保证(发布后不可变),拿它当前缀是免费的防撞。
541
+ 2. **`@keyframes` 的名字一样要带前缀**(`file-tree-fadeIn`),并且**改名字时同笔改 `animation:` 的引用**——
542
+ 关键帧名与类名一样是全局标识符,重名时后加载的那份会把前一份的动画顶掉。
543
+ 3. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
540
544
 
541
545
  | 来源 | 保留名 | 说明 |
542
546
  |---|---|---|
543
547
  | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
544
- | 宿主全局工具类 | `.titlebar`、`.divider`、`.about`、`.rn`、`.vta` | 宿主界面自己的容器名,不要复用 |
545
- | 共享组件公共类名 | `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle` | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名 |
548
+ | 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用** |
549
+
550
+ > 🔧 **维护者注(作者可跳过)**:「**保留名**」这一列是**机器读的**——`npm run check` 里的门禁
551
+ > (`scripts/check-reserved-names-doc-sync.mjs`)把它与登记表
552
+ > `packages/plugin-sdk/schemas/reserved-class-names.json` **双向核对**:登记表里的名字必须在这里出现,
553
+ > 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名)。
554
+ > ⇒ **改这一列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这张表。
555
+ > 这一列**只放类名**,解释写第三列。
556
+
557
+ **还有一条跟命名空间有关的**:你的 `pluginId` **不得以 `ldk-` 开头**——整个 `ldk-` 命名空间是宿主的,
558
+ 一个叫 `ldk-tools` 的插件用纪律 1 派生出来的前缀(`ldk-tools-*`)会**由构造落进宿主空间**,纪律 1
559
+ 也就跟着失效了。这条约束写在 `plugin.json` 的 schema 里,编辑器会当场提示。
546
560
 
547
561
  **要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
548
562
  (手写等于绕过组件,组件升级你就掉队)。
@@ -553,6 +567,45 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
553
567
  **反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
554
568
  同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
555
569
 
570
+ ### 12.1 从旧版 `@linkdesk/ui` 升上来——一件要你自己改的事
571
+
572
+ 共享组件的类名带上了 `ldk-` 前缀(`@linkdesk/ui` **0.2.0** 起)。这件事**只影响一种写法**:
573
+ 你写在**插件自己 CSS 里**、用后代选择器去微调共享组件外观的那些规则。**升级前不用动,升级时改一处前缀即可。**
574
+
575
+ - **什么时候受影响**:把 `@linkdesk/ui` 升到 **0.2.0 之后**——**不是立刻**。旧版本里这些组件的类名是
576
+ `.badge` 这样的裸名,包里带的 CSS 与组件自洽,**你不升级就不会坏**。(依赖写 `^0.1.x` 时不会自动
577
+ 跨到 `0.2.0`,所以只有你主动升级的那一下才需要动。)
578
+ - **什么会受影响**:你**插件自己 CSS** 里的这类后代选择器——
579
+ `.control-bar .combobox { … }`、`.settings-slider-control .slider { … }`、`.changelog .mdv { … }`
580
+ 等等。**组件自己的样式不受影响,你自己的类名也不用改。**
581
+ - **怎么改**:把选择器里**指向共享组件的那一段**加上 `ldk-` 前缀——`.combobox` → `.ldk-combobox`、
582
+ `.slider` → `.ldk-slider`、`.mdv` → `.ldk-mdv`、`.badge` → `.ldk-badge`、`.selectbox-trigger` →
583
+ `.ldk-selectbox-trigger`、`.combobox-field` → `.ldk-combobox-field`——**族里的名字(`-trigger` / `-field` /
584
+ `-input` 这类后缀)一样带前缀**。你自己的前缀(`.control-bar`、`.settings-*`)照旧。
585
+ **升级后拿这八个旧基名 `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle`
586
+ grep 一遍自己的 CSS**:在调共享组件的就加上前缀,其余别动。
587
+ - **为什么不自动兼容**:这类失配**不报错**——选择器匹配不上,只是那几条规则悄悄不再生效,界面看着
588
+ 「大致还对、就是不太对」。正因为它是静默的,我们才把名字收进 `ldk-` 前缀,并把这段写进文档。
589
+
590
+ ### 12.2 前缀规则(§12 纪律 1/2)上线——既有代码要不要动
591
+
592
+ **一句话:不改也照常跑,但下次动那个文件就是该改的时候。**
593
+
594
+ - **官方插件已经按新规则清过账**——本次改名涉及四只:`file-tree`(v1.0.9)、`settings`(v1.0.11)、
595
+ `serial-monitor`(v1.0.12)、`marketplace`(v1.0.33),裸类名与关键帧名都补上了 `<pluginId>-` 前缀;
596
+ 其余官方插件仓本来就没有裸定义(它们的类名不是自带前缀,就是根本没定义类名)。以官方插件清单为口径
597
+ 的审计读数是 **18/18 合规**。
598
+ - **第三方作者没有仓要改**:这条规则只管**你自己写的类名与关键帧名**——不动仓库结构、不动 `pluginId`、
599
+ 也不影响别人的代码。你既有插件**不用为它单独发版**。
600
+ - **旧的无前缀类名不会报错、也不会失效**——今天照常工作。代价是**撞名的风险仍然在**:另一个插件写了
601
+ 同名类名,两边样式就会落到同一个元素上(不报错,只是长得不对,很难查)。
602
+ - **合规由工程自带的检查判**:脚手架建出来的工程带着一条严格检查腿(`npm run verify`),它扫你自己 CSS
603
+ 里**给自有元素裸定义**的类名和 `@keyframes` 名,不带 `<pluginId>-` 前缀就判红。所以真正的动作是
604
+ **下一次动那个文件时顺手把名字改掉**:`.panel {}` → `.myplugin-panel {}`,CSS 与用到它的 JSX 两侧一起改
605
+ (只改标识符,不动样式值)。
606
+
607
+ > 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
608
+
556
609
  ---
557
610
 
558
611
  ## 速查
@@ -13,8 +13,8 @@
13
13
  },
14
14
  "pluginId": {
15
15
  "type": "string",
16
- "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
17
- "description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit."
16
+ "pattern": "^(?!ldk-)[A-Za-z0-9][A-Za-z0-9._-]*$",
17
+ "description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit. It must not start with `ldk-`: that whole namespace belongs to the host and its shared components, and since your CSS class prefix is derived from this id (`<pluginId>-your-class`), an `ldk-` id would land in host territory by construction and void the plugin-prefix rule (SDK check-css-namespace leg)."
18
18
  },
19
19
  "type": {
20
20
  "type": "string",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [