@linkdesk/plugin-docs 0.1.2 → 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.
@@ -526,6 +526,104 @@ When authors build their own settings UI or manage their own saves (without goin
526
526
 
527
527
  ---
528
528
 
529
+ ## 12. CSS Class Names—Prefix Your Own Elements; Don't "Borrow" Reserved Names
530
+
531
+ **One thing to remember first: the plugin view's stylesheet is not yours alone.** The same window loads the
532
+ host's styles, the shared components' (`@linkdesk/ui`) styles, and **every loaded plugin's** styles at once —
533
+ **class names are global identifiers**. Writing a class name claims that name; if someone else uses it too,
534
+ both stylesheets land on the same element.
535
+
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
548
+ styles will hit you):
549
+
550
+ | Source | Reserved names | Notes |
551
+ |---|---|---|
552
+ | Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
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.
567
+
568
+ **Want their look? Use their component**—`import { Button } from "@linkdesk/ui"`, don't hand-write its class
569
+ name (hand-writing bypasses the component, and you fall behind the moment it changes).
570
+
571
+ **Always use state classes in compound form**: `.your-class.active`, `.your-class.on` (never bare
572
+ `.active {}` or `.on {}`—that would also restyle same-named state elements in the host and in other plugins).
573
+
574
+ **A real example from this project**: using a host-reserved name as a "handy style name" on your own element
575
+ painted the background and the text the same color, so the text was swallowed by its own background — the UI
576
+ just looked like "a solid block". **No error**, just wrong, and hard to trace.
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
+
625
+ ---
626
+
529
627
  ## Quick Reference
530
628
 
531
629
  | What you want to do | Core facility | How to bring it in |
@@ -544,6 +642,7 @@ When authors build their own settings UI or manage their own saves (without goin
544
642
  | Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
545
643
  | 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) |
546
644
  | Text | `t()` | `useTranslation()` from `react-i18next` |
645
+ | 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) |
547
646
  | Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
548
647
 
549
648
  **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.**
@@ -526,6 +526,88 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
526
526
 
527
527
  ---
528
528
 
529
+ ## 12. CSS 类名——自己的元素用自有前缀,宿主保留名不要「借用」
530
+
531
+ **先记住一件事:插件视图的样式表不是你自己独占的。** 同一个窗口里同时加载着宿主的样式、共享组件
532
+ (`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
533
+ 就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
534
+
535
+ **三条纪律:**
536
+
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. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
544
+
545
+ | 来源 | 保留名 | 说明 |
546
+ |---|---|---|
547
+ | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
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 里,编辑器会当场提示。
560
+
561
+ **要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
562
+ (手写等于绕过组件,组件升级你就掉队)。
563
+
564
+ **状态类一律复合使用**:`.你的类.active`、`.你的类.on`(不要裸写 `.active {}`、`.on {}`——那会把
565
+ 宿主和其他插件里带同名状态类的元素一起改掉)。
566
+
567
+ **反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
568
+ 同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
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
+
609
+ ---
610
+
529
611
  ## 速查
530
612
 
531
613
  | 你要做的 | 核心设施 | 引入方式 |
@@ -544,6 +626,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
544
626
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
545
627
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
546
628
  | 文字 | `t()` | `useTranslation()` from `react-i18next` |
629
+ | CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
547
630
  | 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
548
631
 
549
632
  **写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
@@ -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.2",
3
+ "version": "0.1.4",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [