@linkdesk/plugin-docs 0.1.29 → 0.1.31
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.
|
@@ -254,6 +254,25 @@ Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two
|
|
|
254
254
|
|
|
255
255
|
---
|
|
256
256
|
|
|
257
|
+
## Tests in a plugin repo
|
|
258
|
+
|
|
259
|
+
Nothing to set up — but "should I test this?" deserves a straight answer.
|
|
260
|
+
|
|
261
|
+
- **The toolchain is preinstalled.** `vitest` / `jsdom` / `@testing-library/react` are already in `devDependencies` — write `src/__tests__/<same-name>.test.ts` and run `npm run test`.
|
|
262
|
+
- **The shared test ground comes from the SDK.** The minimal `window.linkdesk` mock lives in `@linkdesk/plugin-sdk/vitest-setup`, and your `vitest.setup.ts` is a **one-line pointer** to it. ⛔ **Do not paste a second copy into your repo** — a copied mock silently drifts from the shared one.
|
|
263
|
+
- **Pure logic is what pays off.** A unit under `src/**/*.ts` that touches neither React nor `window.linkdesk` should get a test. Views and interactions are worth testing **when it pays off** — nothing measures that today.
|
|
264
|
+
- **Plugin-specific stubs stay in your own test files.** Does your code call something the shared mock does not cover (say `window.linkdesk.serial`)? Stub it with `vi.fn()` in the test that needs it — do not expect the shared mock to grow a branch for your plugin.
|
|
265
|
+
- **Declarative plugins** (pure JSON / themes / language packs) have **no testable units** — their gate is `npm run verify` (structure + declarations). **"It has no tests" is not a defect there.**
|
|
266
|
+
- **Older projects can migrate whenever they like.** Replacing the full mock body with the one-line pointer plus one `npm install` is the whole move (upside: mock upgrades then ride along with the SDK).
|
|
267
|
+
|
|
268
|
+
**How to know you did it right**
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
npm run test # vitest run — an empty suite passes on purpose (passWithNoTests)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
257
276
|
## Pitfalls Beginners Hit Most
|
|
258
277
|
|
|
259
278
|
| Symptom | Root cause | Where to look |
|
|
@@ -281,4 +300,5 @@ Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two
|
|
|
281
300
|
| A whole **replacement settings UI** | [10-building-a-settings-plugin](10-building-a-settings-plugin.md) |
|
|
282
301
|
| Build **themes/icons** | [11-authoring-themes](11-authoring-themes.md) |
|
|
283
302
|
| **Where files should go**; authoritative README/CHANGELOG criteria | [09-plugin-directory-layout](09-plugin-directory-layout.md) |
|
|
303
|
+
| Decide **whether / how to test my plugin** | [§ Tests in a plugin repo](#tests-in-a-plugin-repo) |
|
|
284
304
|
| The full documentation index | [00-readme §Documentation Index](00-readme.md#documentation-index) |
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -169,6 +169,8 @@ useEffect(() => {
|
|
|
169
169
|
|
|
170
170
|
**❌ 反模式(红字):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **全局劫持**——绕过分区前提,插件有活动会话时劫持全池同键(串口 F2 曾劫持文件树 F2)。**`tabIndex` + 容器 `onKeyDown` 才是焦点分区正解**;非焦点元素不触发,可加 `tabIndex={0}` 承接。
|
|
171
171
|
|
|
172
|
+
🔴 **这条反模式有腿了(2026-09-20,SDK 0.1.46 起)**:`linkdesk-plugin-sdk lint` 的 `linkdesk/no-global-key-listener` 腿机械拦截 window/document 的 keydown/keyup **字面量**监听,报错文案直接给正解与豁免写法。确需全局抓键的正当形态(如快捷键录制器要 capture 抓原始键)走标准 disable 注释+理由——判据本身无白名单。
|
|
173
|
+
|
|
172
174
|
**注意:** 轨道二键**不进快捷键设置面板**——面板只显示 KeybindingRegistry 绑定(轨道一)。这是设计取舍(注册即吞池,见 4.1),不是 bug。
|
|
173
175
|
|
|
174
176
|
### 4.3 剪贴板三选一通道表
|
|
@@ -532,6 +534,8 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
532
534
|
(`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
|
|
533
535
|
就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
|
|
534
536
|
|
|
537
|
+
🔴 **引用侧也有腿了(2026-09-20,SDK 0.1.46 起)**:TSX `className` **字面量**里引用的本插件前缀类名,必须能在本仓 CSS(含 scoped 规则)里找到定义——`linkdesk/no-reserved-class-name` 家族新判据机械把关。头号根因 = CSS 块注释里写 `--text-*/` 这类文本:`*/` 把注释**提前闭合**,残渣黏住下一条规则把它整条吞掉(生态首例,样式静默丢失零报错);文案列三种常见根因(拼错/漏 import/注释吞规则)。动态拼接(模板插值 / clsx / 变量)跳过并计数。
|
|
538
|
+
|
|
535
539
|
**三条纪律:**
|
|
536
540
|
|
|
537
541
|
1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
|
package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md
CHANGED
|
@@ -254,6 +254,25 @@ env:
|
|
|
254
254
|
|
|
255
255
|
---
|
|
256
256
|
|
|
257
|
+
## 插件仓里的测试怎么写
|
|
258
|
+
|
|
259
|
+
不用配任何东西——但「这段该不该测」值得一个直给的回答。
|
|
260
|
+
|
|
261
|
+
- **工具链已预装**:`vitest` / `jsdom` / `@testing-library/react` 都在 `devDependencies` 里,写 `src/__tests__/<同名>.test.ts`,然后 `npm run test`。
|
|
262
|
+
- **共享测试地基由 SDK 提供**:`window.linkdesk` 的最小 mock 住在 `@linkdesk/plugin-sdk/vitest-setup`,你仓里的 `vitest.setup.ts` 是指向它的**一行指针**。⛔ **不要在自己仓里再抄一份**——抄来的那份会与共享版**无声漂移**。
|
|
263
|
+
- **纯逻辑最值得测**:`src/**/*.ts` 里既不碰 React、也不碰 `window.linkdesk` 的单元,应该配上测试。视图与交互**划得来时再测**——今天没有任何东西在量它。
|
|
264
|
+
- **插件专属桩住本仓**:你的代码调了共享 mock 没覆盖的东西(比如 `window.linkdesk.serial`)?在需要它的那个测试文件里用 `vi.fn()` 补上——别指望共享 mock 为你的插件长一条分支。
|
|
265
|
+
- **声明式插件**(纯 JSON/主题/语言包)**没有可测单元**——它的门禁是 `npm run verify`(结构与声明)。**「没有测试」在那里不是缺陷。**
|
|
266
|
+
- **老仓什么时候迁都行**:把整份 mock 换成一枚一行指针 + 一次 `npm install`,就是全部动作(好处:mock 升级从此跟着 SDK 走)。
|
|
267
|
+
|
|
268
|
+
**怎么知道做对了**
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
npm run test # vitest run——空测试集**故意**判过(passWithNoTests)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
257
276
|
## 新手最常踩的坑
|
|
258
277
|
|
|
259
278
|
| 症状 | 病根 | 去哪看 |
|
|
@@ -281,4 +300,5 @@ env:
|
|
|
281
300
|
| 整套**替代设置 UI** | [10-如何造一个设置插件](10-如何造一个设置插件.md) |
|
|
282
301
|
| 做**主题/图标** | [11-主题制作](11-主题制作.md) |
|
|
283
302
|
| 文件**该放哪**、README/CHANGELOG 权威判据 | [09-插件目录规范](09-插件目录规范.md) |
|
|
303
|
+
| 决定**要不要/怎么写测试** | [§ 插件仓里的测试怎么写](#插件仓里的测试怎么写) |
|
|
284
304
|
| 全部文档索引 | [00-README §文档索引](00-README.md#文档索引) |
|