@linkdesk/plugin-docs 0.1.2 → 0.1.3

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,39 @@ 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
+ **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
542
+ styles will hit you):
543
+
544
+ | Source | Reserved names | Notes |
545
+ |---|---|---|
546
+ | 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` |
549
+
550
+ **Want their look? Use their component**—`import { Button } from "@linkdesk/ui"`, don't hand-write its class
551
+ name (hand-writing bypasses the component, and you fall behind the moment it changes).
552
+
553
+ **Always use state classes in compound form**: `.your-class.active`, `.your-class.on` (never bare
554
+ `.active {}` or `.on {}`—that would also restyle same-named state elements in the host and in other plugins).
555
+
556
+ **A real example from this project**: using a host-reserved name as a "handy style name" on your own element
557
+ painted the background and the text the same color, so the text was swallowed by its own background — the UI
558
+ just looked like "a solid block". **No error**, just wrong, and hard to trace.
559
+
560
+ ---
561
+
529
562
  ## Quick Reference
530
563
 
531
564
  | What you want to do | Core facility | How to bring it in |
@@ -544,6 +577,7 @@ When authors build their own settings UI or manage their own saves (without goin
544
577
  | 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
578
  | 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
579
  | Text | `t()` | `useTranslation()` from `react-i18next` |
580
+ | 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
581
  | Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
548
582
 
549
583
  **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,35 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
526
526
 
527
527
  ---
528
528
 
529
+ ## 12. CSS 类名——自己的元素用自有前缀,宿主保留名不要「借用」
530
+
531
+ **先记住一件事:插件视图的样式表不是你自己独占的。** 同一个窗口里同时加载着宿主的样式、共享组件
532
+ (`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
533
+ 就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
534
+
535
+ **两条纪律:**
536
+
537
+ 1. **给自己的元素起带前缀的类名**——官方插件就是这么做的(`settings-*`、`ms-*`、`mpd-*`)。
538
+ 前缀用你自己的插件名或简写,别用 `.active-panel` 这种一看就通用的名字。
539
+ 2. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
540
+
541
+ | 来源 | 保留名 | 说明 |
542
+ |---|---|---|
543
+ | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
544
+ | 宿主全局工具类 | `.titlebar`、`.divider`、`.about`、`.rn`、`.vta` | 宿主界面自己的容器名,不要复用 |
545
+ | 共享组件公共类名 | `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle` | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名 |
546
+
547
+ **要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
548
+ (手写等于绕过组件,组件升级你就掉队)。
549
+
550
+ **状态类一律复合使用**:`.你的类.active`、`.你的类.on`(不要裸写 `.active {}`、`.on {}`——那会把
551
+ 宿主和其他插件里带同名状态类的元素一起改掉)。
552
+
553
+ **反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
554
+ 同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
555
+
556
+ ---
557
+
529
558
  ## 速查
530
559
 
531
560
  | 你要做的 | 核心设施 | 引入方式 |
@@ -544,6 +573,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
544
573
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
545
574
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
546
575
  | 文字 | `t()` | `useTranslation()` from `react-i18next` |
576
+ | CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
547
577
  | 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
548
578
 
549
579
  **写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
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.3",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [