@linkdesk/plugin-docs 0.1.18 → 0.1.24
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.
- package/docs/00-readme.md +1 -1
- package/docs/01-plugin-api-contract.md +1 -1
- package/docs/05-ui-conventions.md +6 -3
- package/docs/10-building-a-settings-plugin.md +1 -1
- package/docs/13-development-guide.md +1 -1
- package/docs/16-naming-conventions.md +48 -0
- package/docs/19-component-cheatsheet.md +22 -1
- package/docs/zh/00-README.md +1 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +1 -1
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +6 -3
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +1 -1
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +1 -1
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +37 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +23 -1
- package/package.json +1 -1
package/docs/00-readme.md
CHANGED
|
@@ -97,7 +97,7 @@ System-level capabilities (serial ports, filesystem, configuration, dialogs) are
|
|
|
97
97
|
| `create-linkdesk-plugin` | Generates a plugin project skeleton in one line (the yo code equivalent) — **and it creates the git repo for you** | `npm create` when starting a new plugin; one-off, not part of the project |
|
|
98
98
|
| `@linkdesk/plugin-sdk` | The four author-toolchain commands: `dev` (dev host + HMR) / `build` (→ `.linkdesk-plugin`) / `validate` / `lint`; ships `plugin.schema.json` + `theme.schema.json` + the dev host page | devDependencies of every plugin project |
|
|
99
99
|
| `@linkdesk/contracts` | Full TS types for `window.linkdesk.*` (generated contract artifacts — the single source of truth) | **No need to install it yourself** — the SDK depends on it and forwards everything |
|
|
100
|
-
| `@linkdesk/ui` | Shared UI parts (buttons/selects/toggles/color picker/context menu…) | **Optional** — install it when you want your UI to look built-in (automatic theme/glass following) → [19-component-cheatsheet](19-component-cheatsheet.md) |
|
|
100
|
+
| `@linkdesk/ui` | Shared UI parts (buttons/selects/toggles/color picker/context menu…) — **the shell pool serves one instance at runtime**; installing it is for types and local dev | **Optional** — install it when you want your UI to look built-in (automatic theme/glass following); **its version matches the shell's** (one line → [19-component-cheatsheet §2.1](19-component-cheatsheet.md)) |
|
|
101
101
|
|
|
102
102
|
**In one sentence:** `create` generates the project → the project installs `sdk` → `sdk` brings `contracts` (types come along) → `ui` is standalone, installed on demand.
|
|
103
103
|
> Version numbers are not pinned on this page — **just install without a version to get the latest**.
|
|
@@ -137,7 +137,7 @@ The old §3.x per-namespace method list has been deleted (= a hand-written secon
|
|
|
137
137
|
|
|
138
138
|
**Allowed imports (shared controls come from the `@linkdesk/ui` npm package; the full `@src/core` exception allowlist lives in `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
|
|
139
139
|
- `@linkdesk/contracts` **types** (`import type`, zero runtime coupling) — the real registry package (see §3.1)
|
|
140
|
-
- `@linkdesk/ui` **shared controls / shared hooks** (ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker, etc., consolidated) — **declare it explicitly in your own project's `dependencies
|
|
140
|
+
- `@linkdesk/ui` **shared controls / shared hooks** (ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker, etc., consolidated) — **declare it explicitly in your own project's `dependencies`**, with the same version number as the shell you support (shell `0.2.13` ⇒ `"@linkdesk/ui": "^0.2.13"`; see [19-Component Cheatsheet §2.1](19-component-cheatsheet.md) for the version line) and build against the published package. ⛔ **Do not import its css** (styles are supplied by the shell pool; an SDK lint leg fails it — see [05-UI Conventions §12.4](05-ui-conventions.md)). 🔴 After that, **official plugins and third-party plugins share one project shape** (the six official ones already have the explicit declaration added); the only exception is those two **dev fixtures** inside the shell repo (still hoisted via the root workspaces). **Never import from `@src/components/shared/*`** (the second entry point for shared controls has been deleted)
|
|
141
141
|
- **Pure-utility allowlist (`@src/core` exceptions)**: `@src/core/pipeline/*` (DataConverter / DataDispatch / RingBuffer / ProtocolParser) + `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry` (the MenuId type/enum only) and so on — treat `eslint-local-rules.js` as the only authority for the full table; don't copy a second one here
|
|
142
142
|
- 🔴 **Review conclusion**: this allowlist **is in practice used only by shell-repo fixtures** — after the official plugins moved out of the shell repo, their source has zero `@src` hits (at runtime everything goes through `window.linkdesk.*`; measured). The allowlist **stays** (the fixtures are still inside `plugins/` and still guarded by that same eslint rule), but **third-party authors should pretend it doesn't exist**: the only three things you can use are `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*`
|
|
143
143
|
- **Exception registry**: imports outside the allowlist must be registered before they are permitted (an audit item of the plugin-independence iron rule)
|
|
@@ -550,7 +550,7 @@ both stylesheets land on the same element.
|
|
|
550
550
|
| Source | Reserved names | Notes |
|
|
551
551
|
|---|---|---|
|
|
552
552
|
| The input-box utility the host **gives you** | `.ldk-input` | Input-box utility—**just use it** (it exists for your inputs). ⚠️ It is the **one** name in the whole `ldk-` family you're encouraged to **consume** (every other `ldk-` name means "hands off"; this one means "take it") |
|
|
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`, `ldk-input`, `ldk-setting-group` | 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** (the one exception is `.ldk-input` on the row above: that one is **for you**) |
|
|
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`, `ldk-hint-card` (2026-09-19, hover hint card) (shared components), plus the host's own container classes such as `ldk-titlebar`, `ldk-input`, `ldk-setting-group` | 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** (the one exception is `.ldk-input` on the row above: that one is **for you**) |
|
|
554
554
|
|
|
555
555
|
**`@keyframes` names work the same way**—the host already uses the animation names below, so avoid them when naming your own animations. A collision has the same consequence as a class name (the later definition wins, the earlier one is dropped), and it is equally **silent**: one of the two animations simply stops playing, with nothing in the console.
|
|
556
556
|
|
|
@@ -660,7 +660,7 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
|
|
|
660
660
|
|
|
661
661
|
**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.**
|
|
662
662
|
|
|
663
|
-
- **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
|
|
663
|
+
- **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 (**since the 2026-09-16 round**; for how to read the version line see [19-Component Cheatsheet §2.1](19-component-cheatsheet.md)):
|
|
664
664
|
|
|
665
665
|
| Old family | New family |
|
|
666
666
|
|---|---|
|
|
@@ -677,7 +677,10 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
|
|
|
677
677
|
|
|
678
678
|
- **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**).
|
|
679
679
|
- **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.**
|
|
680
|
-
- **When
|
|
680
|
+
- 🔴 **When the host renames a shared name or restyles a component, there is no code and no CSS for you to change** — components and styles are supplied by the shell pool (L9 centralized supply, see [19-Component Cheatsheet §2](19-component-cheatsheet.md)): the same implementation follows the shell upgrade, so your UI stays consistent. The one thing to maintain is that your `@linkdesk/ui` dependency **stays on the current version line** (it decides what your local dev and types resolve to).
|
|
681
|
+
- ⛔ **Component styles never come from your source either**: a line like `import "@linkdesk/ui/index.css"` (or its dist / `@import` form) is failed by the SDK lint leg `linkdesk/no-ui-css-import`, with **no exemption exit** — baking the styles into your plugin means "the shell restyles once, the whole ecosystem follows" stops being true for you.
|
|
682
|
+
- **When you must change it**: when the shell you support moves to a version that contains this rename (how to read the version line: [19-Component Cheatsheet §2.1](19-component-cheatsheet.md) — ui version = shell version, one line). After upgrading, **grep your own CSS for the old families** in the table above: an official plugin (`settings`) had exactly one such spot and it was fixed in the same release batch.
|
|
683
|
+
- **You get the same ruler** (`@linkdesk/plugin-sdk` 0.1.40 onward): your repo's lint ships with a dangling-name check—when the host renames a shared name and you didn't follow, **your own CI calls it out** (usage and fixes in [16-naming-conventions §7.6](16-naming-conventions.md)).
|
|
681
684
|
|
|
682
685
|
### 12.5 The **scope** of custom properties—`--x:` written under `:root` is written for the whole application
|
|
683
686
|
|
|
@@ -71,7 +71,7 @@ The filename is simply `settings.json`, with no shell-side map — copy it as-is
|
|
|
71
71
|
|
|
72
72
|
## Shared controls — `@linkdesk/ui`
|
|
73
73
|
|
|
74
|
-
A settings UI's shared controls live in the **`@linkdesk/ui`** package (consolidated there — third parties `npm i @linkdesk/ui` and import directly; **`import @src/core/...` is forbidden, and so is `@src/components/...`**):
|
|
74
|
+
A settings UI's shared controls live in the **`@linkdesk/ui`** package (consolidated there — third parties `npm i @linkdesk/ui` and import directly; **`import @src/core/...` is forbidden, and so is `@src/components/...`**); install the version line that **matches the shell** (see [19-component-cheatsheet §2.1](19-component-cheatsheet.md): ui version = shell version) — components and styles are supplied by the shell pool at runtime, so ⛔ **do not import its css from your source**:
|
|
75
75
|
|
|
76
76
|
`ContextMenu` · `InlineInput` · `SelectBox` · `Toggle` · `ColorPicker` · `FontFamilySelect` · `FilePathInput` · `NumberInput` · `Slider` · `Combobox` · `FormRow` · `SegmentedRadio` · `ThemePicker` · `PluginIcon` · shared hooks (`useDebouncedInput` / `useClipboardKeys`, etc.)
|
|
77
77
|
|
|
@@ -145,7 +145,7 @@ No errors in the output means it passes. Declared a command → press `Ctrl+Shif
|
|
|
145
145
|
npm i @linkdesk/ui
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
-
Controls like context menus, selects, and toggles come from the shared package — **glass/theme follow automatically**, no styling of your own.
|
|
148
|
+
Controls like context menus, selects, and toggles come from the shared package — **glass/theme follow automatically**, no styling of your own; components and styles are supplied by the shell pool at runtime (install the line that **matches the shell**, see [19-component-cheatsheet §2.1](19-component-cheatsheet.md)), and ⛔ you must not import its css.
|
|
149
149
|
|
|
150
150
|
**How to know you did it right**
|
|
151
151
|
Switch themes and your context menu's appearance follows (hand-made implementations usually don't). Repo hard constraint 3 is explicit: a hand-written context menu is a violation.
|
|
@@ -146,6 +146,54 @@ Renames on the host side **all come with migrations**, so users don't reconfigur
|
|
|
146
146
|
|
|
147
147
|
Your only takeaway as a plugin author: **don't invent compatibility aliases for old host names** — old-name mapping is the shell's job. Just declare names in the **new shape**.
|
|
148
148
|
|
|
149
|
+
### 7.5 Host names do get retired—you are never forced to upgrade
|
|
150
|
+
|
|
151
|
+
The host also **retires its own names**: a **rename** (the name changed), a **changed meaning** (same name, different
|
|
152
|
+
meaning) and a **changed value domain** (same name and meaning, different accepted values) all count as retirement-level
|
|
153
|
+
actions. Only three things matter to you:
|
|
154
|
+
|
|
155
|
+
1. **You are never auto-uninstalled, and never refused**: retirement is the host's own business—the shell does not
|
|
156
|
+
uninstall or refuse to load you because you reference a retired name, and it is never used to gate `minAppVersion`.
|
|
157
|
+
Your plugin keeps running, on the semantics of the **new** name.
|
|
158
|
+
2. **If you reference a retired name, you get a hint in your own repo** (`@linkdesk/plugin-sdk` **0.1.40** onward,
|
|
159
|
+
usage in 7.6): `linkdesk-plugin-sdk lint` and your repo's CI scan your sources and `plugin.json` for references
|
|
160
|
+
to retired names and report each one with since-when and what replaced it (`file:line`). 🔴 It is **only a
|
|
161
|
+
hint**—it never enters any failing leg and will never block your build or release (retired ≠ deleted; the host
|
|
162
|
+
does not refuse to load you over it).
|
|
163
|
+
3. **Two steps to fix**: ① bump your `@linkdesk/plugin-sdk` dependency; ② ship a new release (`npm run publish`).
|
|
164
|
+
⛔ Don't shim the old name yourself—retired names **do not free up their slot**: taking one over only overwrites the
|
|
165
|
+
host's **historical data** (see the config-key rows in 7.1).
|
|
166
|
+
|
|
167
|
+
Retired names are **on the record**: the host ledger (`retired[]` in `scripts/host-reserved.json`) plus the
|
|
168
|
+
**byte-identical** copy inside the SDK package, each entry stating since when, why, what replaced it and where a live
|
|
169
|
+
reference still remains. That ledger is **co-read** by host maintainers and authors, and 🔴 **it is not a blacklist**—it
|
|
170
|
+
only states facts, and no gate will ever use it to block you.
|
|
171
|
+
|
|
172
|
+
> 🔧 **Maintainer note (authors can skip)**: the ledger's source of truth and shape live in
|
|
173
|
+
> `scripts/lib/retired-ledger.mjs` (7 fields + the kind vocabulary + `approvedBy` which must be a date signed by the
|
|
174
|
+
> **user**); its internal consistency is guarded by `scripts/check-retired-ledger.mjs` (wired into `npm run check`), and
|
|
175
|
+
> the single outlet for "surface taken away but registered ⇒ pass" is `scripts/check-api-surface-additive.mjs`.
|
|
176
|
+
|
|
177
|
+
### 7.6 Run the "dangling name" self-check in your own repo (`@linkdesk/plugin-sdk` 0.1.40 onward)
|
|
178
|
+
|
|
179
|
+
Your repo's CI (the strict lint leg of `ci-verify`) and `linkdesk-plugin-sdk lint` ship with a **dangling name**
|
|
180
|
+
check: it takes every `ldk-*` name your sources shout plus every keyframe name your CSS references via `animation:`,
|
|
181
|
+
and matches them against **two definition sets**—① the definitions in your own CSS; ② the host definition set
|
|
182
|
+
shipped with the package (`schemas/host-css-names.json` inside the SDK). A name in neither set is reported as
|
|
183
|
+
dangling (name + `file:line`), because that style **silently disappears after publishing** (zero errors—this is the
|
|
184
|
+
mechanical reminder for "the host renamed it and you didn't follow"; the thing §12.4 describes now has someone
|
|
185
|
+
watching it for you).
|
|
186
|
+
|
|
187
|
+
- **How to fix a red (two steps)**: ① switch to a name that really exists in the host, or define it in your repo
|
|
188
|
+
(your own class names start with `<pluginId>-`; `ldk-*` belongs to the host); ② re-pack and ship.
|
|
189
|
+
- **No false alarms**: dynamically composed names (`` className={`x-${v}`} ``) are **skipped and counted**, never
|
|
190
|
+
judged; third-party built-ins (Monaco / codicon—the name and its rules live in their own bundled styles) and DOM
|
|
191
|
+
hook names are **not judged**; test and mock files are not scanned.
|
|
192
|
+
- **Informed bypass**: `// eslint-disable-next-line linkdesk/no-reserved-class-name -- reason` (same id as the
|
|
193
|
+
namespace leg).
|
|
194
|
+
- **Host definition set unreadable** ⇒ the leg reports "**unverified**" instead of "0 issues"—that means a broken
|
|
195
|
+
install; reinstall `@linkdesk/plugin-sdk`.
|
|
196
|
+
|
|
149
197
|
---
|
|
150
198
|
|
|
151
199
|
> **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
|
|
@@ -35,9 +35,28 @@ npm i @linkdesk/ui # Optional — install it when you want your UI to match
|
|
|
35
35
|
|
|
36
36
|
```tsx
|
|
37
37
|
import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
38
|
+
// ⛔ Do not import "@linkdesk/ui/index.css" — the shell pool supplies the styles; that line has no business in your source
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
> The package is the build artifact of a **single-source, anti-drift** setup: the shell changes a component → the package changes with it, so "same as the built-ins" is literally the same implementation. It also **does not go into** your `.linkdesk-plugin` bundle (externalized at build time) —
|
|
41
|
+
> The package is the build artifact of a **single-source, anti-drift** setup: the shell changes a component → the package changes with it, so "same as the built-ins" is literally the same implementation. It also **does not go into** your `.linkdesk-plugin` bundle (externalized at build time), and at **runtime the shell pool supplies that one instance** — nothing to worry about in terms of size or duplicate copies.
|
|
42
|
+
|
|
43
|
+
### 2.1 One version line (no lookup table)
|
|
44
|
+
|
|
45
|
+
The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you installed**. Shell 0.2.13 → package 0.2.13.
|
|
46
|
+
|
|
47
|
+
- **Which one to install**: look at the **oldest shell** you intend to support and install the matching ui version; `npm i @linkdesk/ui@latest` gets you the newest line. This page keeps no lookup table — the shell maintains that line, and it isn't something you have to track.
|
|
48
|
+
- **No need to chase upgrades**: a range like `^0.2.13` picks up later patches on the same line by itself; a shell upgrade won't suddenly break your plugin.
|
|
49
|
+
- **When you do have to move**: only when a **new component you want** appears in a higher version — that's a deliberate upgrade on your side, not something you're forced into.
|
|
50
|
+
|
|
51
|
+
### 2.2 Three promises the shell makes to authors (each backed by a mechanical gate)
|
|
52
|
+
|
|
53
|
+
| Promise | What it means | Backstop |
|
|
54
|
+
|:--|:--|:--|
|
|
55
|
+
| **Add-only** | Published component/export names are lifelong commitments: new ones get added, existing ones are never renamed or removed | The shell repo's export-surface snapshot gate (removing one fails the gate) |
|
|
56
|
+
| **Behavior changes arrive as new names** | To change behavior, a new prop or a new component name is added; the old name keeps its meaning | Same gate — changing the meaning of an old name counts as a removal |
|
|
57
|
+
| **Styles follow the shell** | What a component looks like is the shell's call; upgrades bring the styling along | Styles are supplied by the shell pool (above); your bundle carries no copy that can drift |
|
|
58
|
+
|
|
59
|
+
> Conversely: **to change appearance, switch components or variant props — don't override `ldk-` class names** (those belong to the host; see [05-UI Conventions](05-ui-conventions.md) §12).
|
|
41
60
|
|
|
42
61
|
---
|
|
43
62
|
|
|
@@ -65,6 +84,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
65
84
|
| `ContextMenu` | Context menu component | Works with `contributes.menus` — see [05-UI Conventions](05-ui-conventions.md) |
|
|
66
85
|
| `InlineInput` | Inline input (imperative handle) | Renaming in place in a tree/list (grab the `ref` and call `InlineInputHandle`) |
|
|
67
86
|
| `OverlayPortal` | Overlay portal host | Use it when a custom-drawn dialog needs to portal to body; don't scatter bare `createPortal` calls everywhere |
|
|
87
|
+
| `HintCard` | Anchored hover hint card (non-interactive) | For "hover a small badge, see a short explanation card": give `lines` (1–3 sentences) and the anchor element; triggering/positioning/glass are all handled by the shell; ⛔ no links or buttons inside the card |
|
|
68
88
|
|
|
69
89
|
> The list follows the package's actual export surface (`packages/linkdesk-ui/src/index.ts` is the single source of truth) — if this page disagrees with the package, **the package wins**.
|
|
70
90
|
|
|
@@ -94,6 +114,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
94
114
|
| The Title Bar eats half the clicks on my dialog | The overlay sits at `top: 0` and collides with the window drag region | Use the shared overlay component (it already avoids the drag region) |
|
|
95
115
|
| User settings don't stick | You used `localStorage` | `window.linkdesk.configuration.set` |
|
|
96
116
|
| Two UI libraries installed, styles bleed into each other | You pulled in a third-party component library | Use the shared parts where you can; if you truly need a third party, watch out for style isolation |
|
|
117
|
+
| The shell restyled a component but my plugin didn't follow | Your source `import`s `@linkdesk/ui`'s css (baking the styles into your own package) | Delete that line — the shell pool supplies the styles (the SDK's lint leg fails it; see §2) |
|
|
97
118
|
|
|
98
119
|
---
|
|
99
120
|
|
package/docs/zh/00-README.md
CHANGED
|
@@ -97,7 +97,7 @@
|
|
|
97
97
|
| `create-linkdesk-plugin` | 一行生成插件工程骨架(对标 yo code)——**还会替你建好 git 仓** | 建新插件时 `npm create`,一次性、不进项目 |
|
|
98
98
|
| `@linkdesk/plugin-sdk` | 作者工具链四命令:`dev`(dev 宿主+HMR)/ `build`(→ `.linkdesk-plugin`)/ `validate` / `lint`;随包 `plugin.schema.json` + `theme.schema.json` + dev 宿主页 | 每个插件工程 devDependencies |
|
|
99
99
|
| `@linkdesk/contracts` | `window.linkdesk.*` 全量 TS 类型(契约生成产物——单一真相源) | **不用主动装**——SDK 依赖它并全量转发 |
|
|
100
|
-
| `@linkdesk/ui` | 共享 UI
|
|
100
|
+
| `@linkdesk/ui` | 共享 UI 零件(按钮/下拉/开关/取色器/右键菜单…)——**运行时由壳池供给同一份实例**,装它是为了类型与本地 dev | **可选**——想让界面跟内置同款(自动跟随主题/玻璃)时装;**版本与壳同号**(一条线 → [19-组件速查 §2.1](19-组件速查.md)) |
|
|
101
101
|
|
|
102
102
|
**关系一句话**:`create` 生成工程 → 工程装 `sdk` → `sdk` 带 `contracts`(类型随来)→ `ui` 独立、按需装。
|
|
103
103
|
> 版本号不写死在本页——**装的时候不带版本号即可拿到最新**。
|
|
@@ -137,7 +137,7 @@ async function list(): Promise<FileEntry[]> {
|
|
|
137
137
|
|
|
138
138
|
**允许的 import(共享控件走 `@linkdesk/ui` npm 包;`@src/core` 例外白名单全表见 `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
|
|
139
139
|
- `@linkdesk/contracts` **类型**(`import type`,零运行时耦合)——registry 真包(见 §三 3.1)
|
|
140
|
-
- `@linkdesk/ui` **共享控件 / 共享 hooks**(ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker 等,收归)——**在你自己工程的 `dependencies`
|
|
140
|
+
- `@linkdesk/ui` **共享控件 / 共享 hooks**(ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker 等,收归)——**在你自己工程的 `dependencies` 里显式声明**,版本与你要支持的壳同号(壳 `0.2.13` ⇒ `"@linkdesk/ui": "^0.2.13"`;版本线见 [19-组件速查 §2.1](19-组件速查.md)),构建走货架。⛔ **不要 import 它的 css**(样式由壳池统一供给,SDK 的 lint 腿判红——见 [05-插件UI写法规约 §12.4](05-插件UI写法规约.md))。🔴后**官方插件与第三方是同一款工程形态**(官方 6 只在已补上显式声明);唯一例外是壳仓内那两只**开发夹具**(仍靠根 workspaces 提升)。**一律不从 `@src/components/shared/*` import**(后共享控件第二入口已删)
|
|
141
141
|
- **纯工具白名单(`@src/core` 例外)**:`@src/core/pipeline/*`(DataConverter / DataDispatch / RingBuffer / ProtocolParser)+ `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry`(仅 MenuId 类型/枚举)等——全表只以 eslint-local-rules.js 为准,不在此抄第二份
|
|
142
142
|
- 🔴 **复核结论**:这条白名单**实际只剩壳仓夹具在用**——官方插件搬出壳仓后,它们的源码里 `@src` 早已零命中(运行时全走 `window.linkdesk.*`,已实测)。白名单**保留**(夹具仍在 `plugins/` 内、仍由同一条 eslint 规则守着),但**第三方作者请当作它不存在**:你能用的只有 `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*` 三样
|
|
143
143
|
- **例外登记**:白名单外的 import 必须登记在案再放行(插件独立铁律审计项)
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -545,7 +545,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
545
545
|
| 来源 | 保留名 | 说明 |
|
|
546
546
|
|---|---|---|
|
|
547
547
|
| 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
|
|
548
|
-
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle
|
|
548
|
+
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle`、`ldk-hint-card`(2026-09-19 起,悬停说明卡)等(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
|
|
549
549
|
|
|
550
550
|
**`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
|
|
551
551
|
|
|
@@ -641,7 +641,7 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
|
|
|
641
641
|
|
|
642
642
|
**一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
|
|
643
643
|
|
|
644
|
-
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes`
|
|
644
|
+
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀(**2026-09-16 那轮起**;版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)):
|
|
645
645
|
|
|
646
646
|
| 旧族 | 新族 |
|
|
647
647
|
|---|---|
|
|
@@ -658,7 +658,10 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
|
|
|
658
658
|
|
|
659
659
|
- **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
|
|
660
660
|
- **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
|
|
661
|
-
-
|
|
661
|
+
- 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(L9 集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
|
|
662
|
+
- ⛔ **组件样式同样不从你的源码里来**:源码里出现 `import "@linkdesk/ui/index.css"`(或其 dist / `@import` 形态)会被 SDK 的 lint 腿 `linkdesk/no-ui-css-import` 判红——**没有豁免出口**。把样式烤进插件,等于「壳改样式、全生态跟随」对你失效。
|
|
663
|
+
- **什么时候必须改**:当你要支持的壳升到含这次改名的版本时(版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)——ui 版本 = 壳版本,一条线)。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
664
|
+
- **这把尺子你也有**(`@linkdesk/plugin-sdk` 0.1.40 起):你仓里的 lint 自带「悬空名」判据——宿主改了共享名、你没跟上时,**你自己的 CI 会替你喊**(用法与修法见 [16-命名规范 §7.6](16-命名规范.md))。
|
|
662
665
|
|
|
663
666
|
### 12.5 自定义属性的**作用域**——`--x:` 写在 `:root` 里就等于写给整个软件
|
|
664
667
|
|
|
@@ -71,7 +71,7 @@ const filePath = dir ? window.linkdesk.path.join(dir, "settings.json") : "";
|
|
|
71
71
|
|
|
72
72
|
## 共享控件——`@linkdesk/ui`
|
|
73
73
|
|
|
74
|
-
设置 UI 的共享控件在 **`@linkdesk/ui`** 包(收归——第三方 `npm i @linkdesk/ui` 后直接 import,**禁 `import @src/core/...` 也禁 `@src/components
|
|
74
|
+
设置 UI 的共享控件在 **`@linkdesk/ui`** 包(收归——第三方 `npm i @linkdesk/ui` 后直接 import,**禁 `import @src/core/...` 也禁 `@src/components/...`**);装**与壳同号**的那条线(见 [19-组件速查 §2.1](19-组件速查.md):ui 版本 = 壳版本),组件与样式运行时由壳池供给,⛔ **源码里不要 import 它的 css**:
|
|
75
75
|
|
|
76
76
|
`ContextMenu` · `InlineInput` · `SelectBox` · `Toggle` · `ColorPicker` · `FontFamilySelect` · `FilePathInput` · `NumberInput` · `Slider`· `Combobox` · `FormRow` · `SegmentedRadio` · `ThemePicker` · `PluginIcon` · 共享 hooks(`useDebouncedInput` / `useClipboardKeys` 等)
|
|
77
77
|
|
package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md
CHANGED
|
@@ -145,7 +145,7 @@ npm run validate # 校验 plugin.json:$schema / 字段合法性 / i18n 文
|
|
|
145
145
|
npm i @linkdesk/ui
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
-
|
|
148
|
+
右键菜单、下拉、开关这类控件走共享包——**玻璃/主题自动跟随**,不用自己调样式;组件与样式由壳池运行时供给(装与壳**同号**的那条线,见 [19-组件速查 §2.1](19-组件速查.md)),⛔ 不要 import 它的 css。
|
|
149
149
|
|
|
150
150
|
**怎么知道做对了**
|
|
151
151
|
切换主题时你的右键菜单外观跟着变(自造的实现通常不会)。仓库硬约束 3 明确:手写右键菜单是违规的。
|
|
@@ -155,6 +155,43 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
155
155
|
|
|
156
156
|
对你(插件作者)的影响只有一条:**别自己发明宿主的旧名做兼容**——旧名映射是壳的事,你声明**新形状**的名字即可。
|
|
157
157
|
|
|
158
|
+
### 7.5 宿主的名字会退役,你不会被强制升级
|
|
159
|
+
|
|
160
|
+
宿主也会**退役自己的名字**——**改名**(名字变了)、**改含义**(同名但意思变了)、**改取值域**(同名同义但
|
|
161
|
+
接受的值变了)三种都算退役级动作。对你的影响只有三条:
|
|
162
|
+
|
|
163
|
+
1. **你不会被自动卸载,也不会被拒绝**:退役是宿主**自己**的事——壳不会因为你引用了某个退役名字就卸载你、
|
|
164
|
+
拒载你,也不会拿它去卡 `minAppVersion`。你的插件照旧跑,跑的是**新名字**那套语义。
|
|
165
|
+
2. **引用了已退役的名字,你能在自己仓里跑出提示**(`@linkdesk/plugin-sdk` **0.1.40** 起,用法见 7.6):
|
|
166
|
+
`linkdesk-plugin-sdk lint` + 插件仓 CI 会在你的源码与 `plugin.json` 里找已退役名字的引用,逐条提示
|
|
167
|
+
「哪天退的休、替身是谁」(`文件:行`)。🔴 它**只是提示**——不进任何判红腿、永远不会拦你的构建与发布
|
|
168
|
+
(退役 ≠ 删除,宿主不因它拒载你)。
|
|
169
|
+
3. **改法两步**:① 升依赖(`@linkdesk/plugin-sdk` 升到最新);② 重发一版(`npm run publish`)。
|
|
170
|
+
⛔ 别自己给旧名做兼容——退役名**不腾位**,你占它只会顶掉宿主的**历史数据**(见 7.1 表里配置键那几行)。
|
|
171
|
+
|
|
172
|
+
退役名是**登记在册**的:宿主侧的账(`scripts/host-reserved.json` 的 `retired[]`)+ SDK 包里那份**逐字节相同**的
|
|
173
|
+
副本,每条写明「从哪天起、为什么、替身是谁、还剩哪个活口」。这份账是宿主维护者与作者**共读**的,
|
|
174
|
+
🔴 **它不是黑名单**——它只陈述事实,**不会**被任何门禁拿去拦你。
|
|
175
|
+
|
|
176
|
+
> 🔧 **维护者注(作者可跳过)**:账的真源与形状见 `scripts/lib/retired-ledger.mjs`(7 字段 + kind 词表 +
|
|
177
|
+
> `approvedBy` 必须是**用户本人**签的日期);它的自洽由 `scripts/check-retired-ledger.mjs` 守(跑在 `npm run check` 里),
|
|
178
|
+
> 「面被拿走但有登记 ⇒ 放行」的唯一出口在 `scripts/check-api-surface-additive.mjs`。
|
|
179
|
+
|
|
180
|
+
### 7.6 在自己仓里跑「悬空名」自检(`@linkdesk/plugin-sdk` 0.1.40 起)
|
|
181
|
+
|
|
182
|
+
你仓里的 CI(`ci-verify` 的 lint 严格腿)和 `linkdesk-plugin-sdk lint` 自带一条**悬空名**判据:它把你源码里
|
|
183
|
+
喊的 `ldk-*` 名 + CSS `animation:` 引用的关键帧名,跟**两个定义集**对——① 你自己 CSS 里的定义;
|
|
184
|
+
② 随包下发的宿主定义集(SDK 包内 `schemas/host-css-names.json`)。两边都没有 ⇒ 报悬空(名字 + `文件:行`),
|
|
185
|
+
因为那条样式**发布后会静默消失**(零报错——这正是「宿主改了名、你没跟上」的机械提醒,§12.4 说的那件事
|
|
186
|
+
从此有人替你盯着)。
|
|
187
|
+
|
|
188
|
+
- **报红了怎么修(两步)**:① 换成宿主真实存在的名字,或在你仓里补定义(自有类名以 `<pluginId>-` 开头;
|
|
189
|
+
`ldk-*` 只许宿主定义);② 重新打包发版。
|
|
190
|
+
- **不用怕假红**:动态拼出来的名字(`` className={`x-${v}`} ``)**跳过并计数**、不判;第三方自带的
|
|
191
|
+
(Monaco / codicon 那一类,名字+规则都在它随包样式里)与 DOM 钩子名**不计悬空**;测试与 mock 文件不扫。
|
|
192
|
+
- **知情绕行**:`// eslint-disable-next-line linkdesk/no-reserved-class-name -- 理由`(与命名空间腿同一 id)。
|
|
193
|
+
- **宿主定义集读不到** ⇒ 判据报「**未核验**」而不是「0 处通过」——那是包不完整,重装 `@linkdesk/plugin-sdk`。
|
|
194
|
+
|
|
158
195
|
---
|
|
159
196
|
|
|
160
197
|
> **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
|
|
@@ -35,9 +35,29 @@ npm i @linkdesk/ui # 可选——想让界面跟内置同款时装
|
|
|
35
35
|
|
|
36
36
|
```tsx
|
|
37
37
|
import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
38
|
+
// ⛔ 不要 import "@linkdesk/ui/index.css"——样式由壳池统一供给,源码里不该有这行
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
> 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"
|
|
41
|
+
> 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"是字面意义上的同一份实现。
|
|
42
|
+
> 它也**不进**你的 `.linkdesk-plugin` bundle(构建时 external),**运行时由壳池供给同一份实例**——不必担心体积,也不必担心装了两份。
|
|
43
|
+
|
|
44
|
+
### 2.1 版本一条线(没有对照表)
|
|
45
|
+
|
|
46
|
+
`@linkdesk/ui` 的版本号 **= 你装的那个 LinkDesk 壳的版本号**。壳 0.2.13,包就是 0.2.13。
|
|
47
|
+
|
|
48
|
+
- **该装哪个**:看你**最低要支持**的那个壳版本,装同号的 ui;`npm i @linkdesk/ui@latest` 拿到的就是最新那条线。本页不设对照表——这条线由壳自己维护,不是你要记的东西。
|
|
49
|
+
- **不用追着升**:`^0.2.13` 这样的范围会自动吃到同一线上的后续修订版;壳升级不会让你的插件突然坏掉。
|
|
50
|
+
- **什么时候必须动**:只有当你**要用的新组件**出现在更高版本时——那是你主动升,不是被迫跟。
|
|
51
|
+
|
|
52
|
+
### 2.2 壳对作者的三条承诺(都有机械兜底)
|
|
53
|
+
|
|
54
|
+
| 承诺 | 意思 | 兜底 |
|
|
55
|
+
|:--|:--|:--|
|
|
56
|
+
| **只加不删** | 已发布的组件名 / 导出名是终身承诺——只会新增,不会改名或删除 | 壳仓的导出面快照门禁(删一个就判红) |
|
|
57
|
+
| **行为改走新名字** | 要改行为就**新加 prop / 新加组件名**,不动老名字的语义 | 同上——老名字的语义变更按"删"处理 |
|
|
58
|
+
| **样式跟着壳走** | 组件长什么样由壳决定,升级后样式自然同步 | 样式由壳池供给(见上),你的包里没有会漂移的副本 |
|
|
59
|
+
|
|
60
|
+
> 反过来说:**要换外观就换组件 / 换变体 prop,别覆写 `ldk-` 类名**——那是宿主的(见 [05-插件UI写法规约](05-插件UI写法规约.md) §12)。
|
|
41
61
|
|
|
42
62
|
---
|
|
43
63
|
|
|
@@ -65,6 +85,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
65
85
|
| `ContextMenu` | 右键菜单组件 | 配合 `contributes.menus` —— 见 [05-插件UI写法规约](05-插件UI写法规约.md) |
|
|
66
86
|
| `InlineInput` | 行内输入(命令式句柄) | 树/列表里就地改名(拿 `ref` 调 `InlineInputHandle`) |
|
|
67
87
|
| `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
|
|
88
|
+
| `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
|
|
68
89
|
|
|
69
90
|
> 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
|
|
70
91
|
|
|
@@ -94,6 +115,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
94
115
|
| 弹窗被标题栏吃掉一半点击 | 弹层放到 `top: 0`,撞上窗口拖拽区 | 用共享弹层组件(它已避开拖拽区) |
|
|
95
116
|
| 用户设置没保存住 | 用了 `localStorage` | `window.linkdesk.configuration.set` |
|
|
96
117
|
| 装了两个 UI 库,样式互相污染 | 自己引了第三方组件库 | 能用共享件就用;确需第三方时注意样式隔离 |
|
|
118
|
+
| 壳改过组件样式,我的插件没跟着变 | 源码里 `import` 了 `@linkdesk/ui` 的 css(样式被烤进自己的包) | 删掉那行——样式由壳池供给(SDK 的 lint 腿判红,见 §二) |
|
|
97
119
|
|
|
98
120
|
---
|
|
99
121
|
|