@linkdesk/plugin-docs 0.1.0
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/README.md +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
- 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 +164 -0
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
- package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
- package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
- package/docs/zh/plugin.schema.json +687 -0
- package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
- package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
- package/package.json +20 -0
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# 18 — Cross-Region Wiring: Sidebar selection → Main Area switches → Status Bar updates
|
|
2
|
+
|
|
3
|
+
> **This page answers one question:** your plugin spans several regions (Icon Bar / Sidebar / Main Area / Bottom Panel / Status Bar) — **how do they line up with each other**?
|
|
4
|
+
> Example: "Select a session in the sidebar → the Main Area switches to that session's tab → the Status Bar shows the current session name."
|
|
5
|
+
|
|
6
|
+
| | |
|
|
7
|
+
|---|---|
|
|
8
|
+
| Audience | Authors who already know where the regions are (→ [17-Region Map](17-region-map.md)) and now want them to **work together** |
|
|
9
|
+
| Form | **A recipe collection** — a skeleton you can copy, one per scenario |
|
|
10
|
+
| Not | A dictionary of communication mechanisms (→ [07-Plugin-to-Plugin Communication](07-plugin-to-plugin-communication.md) covers "what mechanisms exist") · data pipeline command naming (→ [14-Data Pipeline Command Conventions](14-data-pipeline-command-conventions.md)) |
|
|
11
|
+
|
|
12
|
+
> **Division of labor in one sentence: `07` answers "how do plugins pass data to each other"; this page answers "how do the several regions of one plugin line up".** The former is mechanism, the latter is **wiring** — pick your tool on this page first, then read `07` for the mechanism details.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. Five Wiring Tools (pick the tool, then write the code)
|
|
17
|
+
|
|
18
|
+
| What you want to achieve | What to use | Direction | Coupling |
|
|
19
|
+
|:--|:--|:--|:--|
|
|
20
|
+
| **Click something → another region does something** | `window.linkdesk.commands.executeCommand("id", args)` | Directed (one-to-one) | Tight — the caller knows the command name |
|
|
21
|
+
| **One region changes → whoever cares refreshes itself** | `window.linkdesk.events.emit(channel, payload)` + `events.on` | Broadcast (one-to-many) | Loose — the publisher doesn't know who's listening |
|
|
22
|
+
| **Some state decides whether a button/menu/view shows** | `window.linkdesk.contextKey.set(key, value)` + `when` in the declaration | Declarative (zero-code wiring) | Loosest — the shell reads the key, you never touch the other side |
|
|
23
|
+
| **Cross-region "navigation"** (open/focus somewhere else) | `tabs.create` / `tabs.openOrFocus` / `tabs.focus` / `panel.reveal(viewId)` / `panel.revealFloating(viewId)` | Directed | Tight — you're naming the destination |
|
|
24
|
+
| **The user changes a value on the settings page → regions follow** | `window.linkdesk.configuration.onChange(key, cb)` | Broadcast (the shell publishes for you) | Loosest — zero extra declarations (→ [20-Adding a Setting](20-adding-a-setting.md)) |
|
|
25
|
+
|
|
26
|
+
**And one more, zero-code:** **appearance** — colors, fonts, radii, glass — follows the theme automatically. Just use `var(--xxx)` and switching themes updates every region, with no subscription at all.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. Four Typical Recipes
|
|
31
|
+
|
|
32
|
+
### Recipe A — Selection in the sidebar → open/focus the matching tab in the Main Area
|
|
33
|
+
|
|
34
|
+
Pick an item in the sidebar view and make the Main Area show/focus the matching content. This is the **"command + open"** combination:
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
// Sidebar view (src/views/SessionListView.tsx)
|
|
38
|
+
function onPick(id: string) {
|
|
39
|
+
// ① Have the Main Area surface the matching content (idempotent: focus if it exists, create if not)
|
|
40
|
+
void window.linkdesk.tabs.openOrFocus("my-plugin", { sourceId: id, label: `Session ${id}` });
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
// Main Area entry component (src/index.tsx) — sourceId tells it which one to show
|
|
46
|
+
export default function MyView({ isActive, sourceId }: { isActive: boolean; sourceId?: string }) {
|
|
47
|
+
// sourceId changed → this is "same plugin, different tab"; each is independent
|
|
48
|
+
return <SessionDetail id={sourceId} />;
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
> **`openOrFocus` is used more often than `create`** — double-clicking shouldn't produce two identical tabs.
|
|
53
|
+
> Multiple tabs of the same plugin are told apart by **`sourceId`** (not by each one's own React state) — see [17 §5 Props Contract](17-region-map.md).
|
|
54
|
+
|
|
55
|
+
### Recipe B — Selected or not → Status Bar entries / Title Bar buttons show and hide by themselves
|
|
56
|
+
|
|
57
|
+
**To make a "only appears when something is selected" button appear, don't thread a prop down through React — use a context key and let the shell decide:**
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
// Sidebar view: write the state into a context key (prefix the key with your plugin id so it can't collide)
|
|
61
|
+
useEffect(() => {
|
|
62
|
+
void window.linkdesk.contextKey.set("my-plugin.hasSelection", !!selectedId);
|
|
63
|
+
}, [selectedId]);
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```jsonc
|
|
67
|
+
// plugin.json — consume that key declaratively; each region writes its own when
|
|
68
|
+
{
|
|
69
|
+
"contributes": {
|
|
70
|
+
"titleBar": { "right": [
|
|
71
|
+
{ "command": "my-plugin.rename", "icon": "codicon-edit", "when": "my-plugin.hasSelection" }
|
|
72
|
+
] },
|
|
73
|
+
"menus": { "editor/context": [ { "command": "my-plugin.rename", "when": "my-plugin.hasSelection" } ] }
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
> **This is "zero-code wiring"**: Title Bar buttons, context menu items, keybindings, and sidebar views can all use the same `when` condition — you `set` it in one place and the shell reads it in N places. The `when` syntax (`&&` / `||` / `==` / `in` / `!` / `()`) and the shell's built-in key table → [03-Contributes Spec §4](03-contributes-spec.md).
|
|
79
|
+
|
|
80
|
+
### Recipe C — One region changes, UI scattered across several places refreshes together
|
|
81
|
+
|
|
82
|
+
Say "the serial port disconnected" has to affect the sidebar's connection row, a button in the Main Area, and the Status Bar's counter at the same time. **Publish one event and let each place subscribe on its own:**
|
|
83
|
+
|
|
84
|
+
```tsx
|
|
85
|
+
// Publisher (e.g. the sidebar view detects that the port dropped)
|
|
86
|
+
window.linkdesk.events.emit("my-plugin:connectionChanged", { portName, open: false });
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
// Subscriber 1 — Main Area component
|
|
91
|
+
useEffect(() => window.linkdesk.events.on<{ open: boolean }>("my-plugin:connectionChanged", (p) => setOpen(p.open)), []);
|
|
92
|
+
|
|
93
|
+
// Subscriber 2 — Status Bar component (a different file, a different region; neither knows the other exists)
|
|
94
|
+
useEffect(() => window.linkdesk.events.on<{ open: boolean }>("my-plugin:connectionChanged", (p) => setText(p.open ? "Connected" : "Disconnected")), []);
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
> 🔴 **Channel names must carry a plugin prefix** (`<pluginId>:<dataName>`). All plugins share one renderer process, and channels are **visible pool-wide** — naming one `changed` will collide.
|
|
98
|
+
|
|
99
|
+
### Recipe D — The user changes a setting → every region follows immediately
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
useEffect(() => {
|
|
103
|
+
return window.linkdesk.configuration.onChange<number>("my-plugin.refreshInterval", (ms) => {
|
|
104
|
+
restartTimer(ms); // Sidebar, Main Area, and Status Bar each subscribe to the keys they care about
|
|
105
|
+
});
|
|
106
|
+
}, []);
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
How to declare a setting and make it appear on the settings page → [20-Adding a Setting](20-adding-a-setting.md).
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 3. One Complete Small Example (three regions strung together)
|
|
114
|
+
|
|
115
|
+
Goal: select in the sidebar list → the Main Area switches over → the Status Bar shows the current item → the Title Bar button hides when nothing is selected.
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
// ① src/views/SessionListView.tsx — Sidebar: the single place where "user intent" originates
|
|
119
|
+
export default function SessionListView() {
|
|
120
|
+
const [sel, setSel] = useState<string | null>(null);
|
|
121
|
+
|
|
122
|
+
const pick = (id: string) => {
|
|
123
|
+
setSel(id);
|
|
124
|
+
void window.linkdesk.contextKey.set("my-plugin.hasSelection", true); // → Recipe B
|
|
125
|
+
void window.linkdesk.tabs.openOrFocus("my-plugin", { sourceId: id }); // → Recipe A
|
|
126
|
+
window.linkdesk.events.emit("my-plugin:selectionChanged", { id }); // → Recipe C
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
return <ul>{items.map((it) => <li key={it.id} onClick={() => pick(it.id)}>{it.name}</li>)}</ul>;
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
```tsx
|
|
134
|
+
// ② src/index.tsx — Main Area entry: only cares about sourceId, manages its own state
|
|
135
|
+
export default function MyView({ sourceId }: { sourceId?: string }) {
|
|
136
|
+
return sourceId ? <Detail id={sourceId} /> : <Empty />;
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
// ③ src/components/statusBar.tsx — Status Bar: subscribes to the event instead of asking "who selected it"
|
|
142
|
+
export default function StatusBar() {
|
|
143
|
+
const [label, setLabel] = useState("");
|
|
144
|
+
useEffect(
|
|
145
|
+
() => window.linkdesk.events.on<{ id: string }>("my-plugin:selectionChanged", (p) => setLabel(`Current: ${p.id}`)),
|
|
146
|
+
[],
|
|
147
|
+
);
|
|
148
|
+
return <span>{label}</span>;
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
```jsonc
|
|
153
|
+
// ④ plugin.json — the declarative side: each region in its place, the button carries a when
|
|
154
|
+
{
|
|
155
|
+
"pluginId": "my-plugin",
|
|
156
|
+
"appearsIn": { "iconBar": "top", "tabBar": true },
|
|
157
|
+
"entry": "src/index.tsx",
|
|
158
|
+
"contributes": {
|
|
159
|
+
"viewsContainers": { "my-plugin": { "title": "Sessions", "location": "sidebar" } },
|
|
160
|
+
"views": { "my-plugin": [ { "id": "sessions", "title": "", "render": "src/views/SessionListView.tsx", "order": 0 } ] },
|
|
161
|
+
"titleBar": { "right": [ { "command": "my-plugin.rename", "icon": "codicon-edit", "when": "my-plugin.hasSelection" } ] }
|
|
162
|
+
},
|
|
163
|
+
"statusBar": [ { "id": "current", "label": "", "align": "left" } ]
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## 4. Iron Rules and Anti-Patterns
|
|
170
|
+
|
|
171
|
+
| Don't do this | Why | Do this instead |
|
|
172
|
+
|:--|:--|:--|
|
|
173
|
+
| Register `events.on` / IPC listeners **at module top level** | Module level = runs on import = never cleaned up, becomes a zombie callback after unmount (hard constraint 19, mechanically caught by ESLint) | Put it in `useEffect` and return the unsubscribe function |
|
|
174
|
+
| Store "state passed across regions" in a `useRef` | Ref updates don't re-render → the UI drifts from the real state and only "jumps" when the next unrelated event fires (hard constraint 17) | Anything render-related goes in `useState` |
|
|
175
|
+
| Use `localStorage` / a global variable as the bus | Bypasses the shell's single channel; behavior across multiple windows / after unmount is unpredictable | `configuration` (when it must persist) or `events` (when it's just a notification) |
|
|
176
|
+
| Channel names without a plugin prefix | All plugins share one renderer process, and channels are globally visible | `<pluginId>:<dataName>` |
|
|
177
|
+
| `import` another plugin directly | Plugins don't know each other exists (the round-hall model) | Go through commands / events / context keys |
|
|
178
|
+
| Blank whole content blocks with `isActive` | Under keep-alive every tab stays mounted; conditional rendering loses state | `isActive` only gates side effects |
|
|
179
|
+
| Hand-roll a context menu to "string regions together" | Hard constraint: context menus are declarative (`contributes.menus` + `<ContextMenu>`) | See [05-UI Conventions](05-ui-conventions.md) |
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 5. Related Reading
|
|
184
|
+
|
|
185
|
+
| What you want to do | Read this |
|
|
186
|
+
|:--|:--|
|
|
187
|
+
| Which regions exist and how to get into them | [17-Region Map](17-region-map.md) |
|
|
188
|
+
| The full table of communication mechanisms (events / commands / data pipeline) | [07-Plugin-to-Plugin Communication](07-plugin-to-plugin-communication.md) |
|
|
189
|
+
| Naming and registration conventions for data pipeline commands | [14-Data Pipeline Command Conventions](14-data-pipeline-command-conventions.md) |
|
|
190
|
+
| `when` syntax and the shell's built-in context keys | [03-Contributes Spec §4](03-contributes-spec.md) |
|
|
191
|
+
| Adding a setting to your plugin | [20-Adding a Setting](20-adding-a-setting.md) |
|
|
192
|
+
| Every `window.linkdesk.*` method signature | [01-Plugin API Contract](01-plugin-api-contract.md) |
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# 19 — Component Cheatsheet: What UI Parts Does the Shell Provide?
|
|
2
|
+
|
|
3
|
+
> **This page answers one question:** the buttons, dropdowns, toggles, context menus on screen… **which of them does the shell already give you**? When should you use which?
|
|
4
|
+
>
|
|
5
|
+
> 🔴 **This page is a "list + selection criteria", not an API manual.** The **single source of truth** for component props, signatures, and defaults is in the package:
|
|
6
|
+
> the README and `dist/index.d.ts` under `node_modules/@linkdesk/ui/` (`import` it in your editor and you get completion).
|
|
7
|
+
> **This page does not copy the props tables** — copies drift, and that's exactly the second source of truth we want to avoid.
|
|
8
|
+
|
|
9
|
+
| | |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Audience | Authors who want to write UI without building their own wheels |
|
|
12
|
+
| Form | A cheatsheet (look up one row per "what widget do I want") |
|
|
13
|
+
| Not | Props documentation for the components (→ the README / d.ts inside the `@linkdesk/ui` package) · UI conventions (→ [05-UI Conventions](05-ui-conventions.md)) |
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 1. When Shared Parts Are **Mandatory** (not a suggestion)
|
|
18
|
+
|
|
19
|
+
| What you're doing | You must go through | Why |
|
|
20
|
+
|:--|:--|:--|
|
|
21
|
+
| Context menu | A `contributes.menus` declaration + `<ContextMenu>` (or `window.linkdesk.menu.registerItems`) | Hand-rolling a context menu = violating a hard constraint; and it won't follow the theme / glass |
|
|
22
|
+
| Dialog / overlay | `createPortal` to `document.body` (the shared `OverlayPortal` already encapsulates the positioning conventions) | Layering, focus trapping, and window-drag-region conflicts are all handled in there |
|
|
23
|
+
| Persisting "remember what the user picked last" | `window.linkdesk.configuration.get/set` | `localStorage.setItem()` is forbidden |
|
|
24
|
+
| Letting the user pick a file/directory | `window.linkdesk.dialog.openFile` + `FilePathInput` | Path resolution and asset-path conventions live shell-side |
|
|
25
|
+
|
|
26
|
+
**In one sentence:** the glass / theme / focus / layering behavior of these controls is **managed centrally by the shell**. Write your own and it won't follow a theme switch — users flipping back and forth between two appearances will notice immediately.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. Installing and Importing
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm i @linkdesk/ui # Optional — install it when you want your UI to match the built-ins
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
38
|
+
```
|
|
39
|
+
|
|
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) — no need to worry about size.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 3. Component List
|
|
45
|
+
|
|
46
|
+
| Component | What it does | When to use it |
|
|
47
|
+
|:--|:--|:--|
|
|
48
|
+
| `Button` | Button | Any "click and it happens" action; variants/sizes follow the theme |
|
|
49
|
+
| `Toggle` | Toggle switch | Two-state settings (on/off) |
|
|
50
|
+
| `Slider` | Slider | Adjusting a numeric range (pair with `inferSliderStep` for the step) |
|
|
51
|
+
| `NumberInput` | Numeric input box | Numbers that need precise entry (often sits next to a slider) |
|
|
52
|
+
| `SelectBox` | Dropdown (fixed options) | Enumerated values, e.g. units mm/cm/inch |
|
|
53
|
+
| `DynamicSelect` | Dropdown (dynamic options) | Options that come from runtime data (serial port list, theme list…) |
|
|
54
|
+
| `Combobox` | Type-ahead dropdown | Many options, and users may type their own (custom paths, etc.) |
|
|
55
|
+
| `SegmentedRadio` | Segmented radio | 2–4 mutually exclusive short options, clearer than a dropdown (e.g. Left/Center/Right) |
|
|
56
|
+
| `FormRow` | One form row (label + control) | When you want the settings-page layout: label on the left, control on the right |
|
|
57
|
+
| `StringListEditor` | String list editor (one per row, add/remove) | Path lists / extension lists / marketplace source lists |
|
|
58
|
+
| `FilePathInput` | File or directory path input | Picking a path, with a browse button and validation |
|
|
59
|
+
| `FontFamilySelect` | Font family picker | Let users choose UI/editor fonts |
|
|
60
|
+
| `ColorPicker` | Color picker | Let users pick a color (remember to store it as a config value, don't hardcode it into the component) |
|
|
61
|
+
| `ThemePicker` | Theme picker | When you want to list/preview the available themes (usually you can just use the shell's settings page) |
|
|
62
|
+
| `MarkdownView` | Markdown rendering (with sanitization) | Showing a README / description / changelog — **the one sanctioned component**; don't pull in your own markdown library |
|
|
63
|
+
| `Badge` | Small badge / count | Corner badges like unread counts or installed counts |
|
|
64
|
+
| `PluginIcon` | Renders a plugin icon | Showing some plugin's icon (handles codicon / custom svg / colored identity art automatically) |
|
|
65
|
+
| `ContextMenu` | Context menu component | Works with `contributes.menus` — see [05-UI Conventions](05-ui-conventions.md) |
|
|
66
|
+
| `InlineInput` | Inline input (imperative handle) | Renaming in place in a tree/list (grab the `ref` and call `InlineInputHandle`) |
|
|
67
|
+
| `OverlayPortal` | Overlay portal host | Use it when a custom-drawn dialog needs to portal to body; don't scatter bare `createPortal` calls everywhere |
|
|
68
|
+
|
|
69
|
+
> 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
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 4. Hooks and Utility Functions
|
|
74
|
+
|
|
75
|
+
| Name | What it does | When to use it |
|
|
76
|
+
|:--|:--|:--|
|
|
77
|
+
| `useDebouncedInput` | Input debouncing | Computing/searching as the user types (avoid firing heavy work on every character) |
|
|
78
|
+
| `useClipboardKeys` | Clipboard shortcuts (three tracks) | When you want copy/paste inside your own widget (text keys go through the container's `onKeyDown` — see doc 05) |
|
|
79
|
+
| `useClickPreview` | Single-click/double-click preview distinction | Interactions like "single-click previews, double-click opens" on list items |
|
|
80
|
+
| `inferSliderStep` | Infers a slider step from a range | Pair with `Slider` (float ranges automatically get something like a 0.01 step) |
|
|
81
|
+
| `urlSourceKey` | Dedup key for URL sources (owner/repo, branch-independent) | When you build your own "add a source" list, the key must match the shell's |
|
|
82
|
+
| `FileIconResolver` | File icon resolver | When you want to show file icons (mapped by extension/filename, the same resolver as the shell) |
|
|
83
|
+
| `pickIdentityArt` / `DEFAULT_PLUGIN_IDENTITY_URI` | Plugin identity-art arbitration and fallback | Use the same arbitration chain when drawing your own plugin identity art |
|
|
84
|
+
| `IconDescriptor` / `ContextMenuProps` / `ManifestIconShape` / `ResolvedIcon` / `InlineInputHandle` | Types | `import type` when you need to annotate types explicitly |
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 5. Common Mistakes
|
|
89
|
+
|
|
90
|
+
| Symptom | Root cause | Do this instead |
|
|
91
|
+
|:--|:--|:--|
|
|
92
|
+
| After a theme switch my dropdowns/menus still look old | You wrote your own widget set | Switch to the shared parts from `@linkdesk/ui` |
|
|
93
|
+
| The context menu won't open / lands in the wrong place | Hand-wiring the `contextmenu` event | `contributes.menus` + `<ContextMenu>` |
|
|
94
|
+
| 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
|
+
| User settings don't stick | You used `localStorage` | `window.linkdesk.configuration.set` |
|
|
96
|
+
| 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 |
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 6. Related Reading
|
|
101
|
+
|
|
102
|
+
| What you want to do | Read this |
|
|
103
|
+
|:--|:--|
|
|
104
|
+
| UI conventions (context menus / overlays / persistence / the two shortcut tracks / the three clipboard channels) | [05-UI Conventions](05-ui-conventions.md) |
|
|
105
|
+
| Which region a component goes in, and how to declare it | [17-Region Map](17-region-map.md) |
|
|
106
|
+
| How components wire together | [18-Cross-Region Wiring](18-cross-region-wiring.md) |
|
|
107
|
+
| Component props and signatures (source of truth) | the README / `dist/index.d.ts` inside the `@linkdesk/ui` package |
|
|
108
|
+
| Every `window.linkdesk.*` method signature | [01-Plugin API Contract](01-plugin-api-contract.md) |
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# 20 — Adding a Setting to Your Plugin
|
|
2
|
+
|
|
3
|
+
> **This page answers one question:** your plugin needs a "user-adjustable toggle/number/dropdown" — **what is the minimum you have to write**?
|
|
4
|
+
>
|
|
5
|
+
> **Three steps: declare one entry → it appears on the settings page by itself → read it in code.** No settings UI to write at all.
|
|
6
|
+
|
|
7
|
+
| | |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Audience | Authors who already have a plugin running and now want to add a configurable entry |
|
|
10
|
+
| Form | **The minimal path** (copy it and you're done) |
|
|
11
|
+
| Not | "Building a settings plugin" (that means **replacing the whole settings UI**, a different job → [10-Building a Settings Plugin](10-building-a-settings-plugin.md)) · the full field table (→ [03-Contributes Spec](03-contributes-spec.md)) |
|
|
12
|
+
|
|
13
|
+
> **Don't conflate two things** (this is the most common misunderstanding):
|
|
14
|
+
> - **This page**: add one setting **to your plugin** — it shows up in the **existing** settings page, as one group, with zero UI code.
|
|
15
|
+
> - [10-Building a Settings Plugin](10-building-a-settings-plugin.md): **build a whole settings UI yourself** to replace the shell's settings page (`factoryRole: "settings"`). The vast majority of plugins **never need** this.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 1. Step 1: Declare it in `plugin.json`
|
|
20
|
+
|
|
21
|
+
```jsonc
|
|
22
|
+
{
|
|
23
|
+
"pluginId": "my-plugin",
|
|
24
|
+
"contributes": {
|
|
25
|
+
"configuration": {
|
|
26
|
+
"title": "My Plugin", // ← the group name in the settings page's left nav
|
|
27
|
+
"properties": {
|
|
28
|
+
"my-plugin.autoSave": { // ← the key must carry the <pluginId>. prefix
|
|
29
|
+
"type": "boolean",
|
|
30
|
+
"default": true, // ← default is required
|
|
31
|
+
"description": "Save automatically on exit" // ← description is required (rendered as a tooltip)
|
|
32
|
+
},
|
|
33
|
+
"my-plugin.refreshInterval": {
|
|
34
|
+
"type": "number",
|
|
35
|
+
"default": 1000,
|
|
36
|
+
"description": "Refresh interval (ms)"
|
|
37
|
+
},
|
|
38
|
+
"my-plugin.units": {
|
|
39
|
+
"type": "string",
|
|
40
|
+
"default": "mm",
|
|
41
|
+
"enum": ["mm", "cm", "inch"],
|
|
42
|
+
"enumDescriptions": ["Millimeters", "Centimeters", "Inches"], // ← one-to-one with enum
|
|
43
|
+
"description": "Display units"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**The sign you got it right:**
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm run validate # Validate that plugin.json is well-formed
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Once installed into LinkDesk, a "My Plugin" group appears on the left of the settings page and the three controls render automatically on the right — **boolean becomes a toggle, enum becomes a dropdown, number becomes an input box**. You didn't write a single line of UI code.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 2. Step 2 (Optional): Make It Look Nicer
|
|
62
|
+
|
|
63
|
+
| What you want | What to add |
|
|
64
|
+
|:--|:--|
|
|
65
|
+
| **A more fitting widget** (color picker / slider / file picker…) | `uiHint` — see the table below |
|
|
66
|
+
| Subheadings inside the same group | `group` — entries sharing a `group` value collect under one second-level heading |
|
|
67
|
+
| Dropdown options that **show a short label**, with the full sentence on hover | `enum` + `enumDescriptions`, together with `uiHint: "segmented"` |
|
|
68
|
+
|
|
69
|
+
**Known `uiHint` values** (an unknown value falls back to the default rendering for its `type`, without error):
|
|
70
|
+
|
|
71
|
+
| `uiHint` | Renders as |
|
|
72
|
+
|:--|:--|
|
|
73
|
+
| `"color"` | Color picker |
|
|
74
|
+
| `"slider"` | Slider (pair with `minimum` / `maximum` / `step`; inferred from the range if omitted) |
|
|
75
|
+
| `"segmented"` | Segmented radio (pair with `enum` + `enumDescriptions`) |
|
|
76
|
+
| `"fontFamily"` | Font family picker (`monoOnly: true` lists monospace families only) |
|
|
77
|
+
| `"fontSize"` / `"file"` / `"directory"` / `"image"` | The matching specialized widget |
|
|
78
|
+
|
|
79
|
+
```jsonc
|
|
80
|
+
"my-plugin.accent": {
|
|
81
|
+
"type": "string", "default": "#3B82F6",
|
|
82
|
+
"uiHint": "color", "description": "Accent color"
|
|
83
|
+
},
|
|
84
|
+
"my-plugin.level": {
|
|
85
|
+
"type": "number", "default": 50,
|
|
86
|
+
"uiHint": "slider", "minimum": 0, "maximum": 100, "step": 5,
|
|
87
|
+
"description": "Sensitivity"
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
> ⚠️ **There is no `"integer"`** — integers use `"number"` too (with `step: 1`).
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 3. Step 3: Read It in Code
|
|
96
|
+
|
|
97
|
+
**Always read and write through `window.linkdesk.configuration`** (`localStorage` is forbidden):
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
// Read it once
|
|
101
|
+
const autoSave = await window.linkdesk.configuration.get<boolean>("my-plugin.autoSave");
|
|
102
|
+
|
|
103
|
+
// Subscribe to changes (the moment the user edits it on the settings page, you hear about it)
|
|
104
|
+
useEffect(() => {
|
|
105
|
+
return window.linkdesk.configuration.onChange<number>("my-plugin.refreshInterval", (ms) => {
|
|
106
|
+
restartTimer(ms);
|
|
107
|
+
});
|
|
108
|
+
}, []);
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**Don't forget to unsubscribe**: the return value of `onChange` is the unsubscribe function — `return` it from your `useEffect` (subscriptions always hang off an effect, never off module top level).
|
|
112
|
+
|
|
113
|
+
> For "the user changes a setting → several places in the UI update at once", see [18-Cross-Region Wiring §Recipe D](18-cross-region-wiring.md).
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 4. Advanced: Suggesting Values for **Someone Else's** Setting
|
|
118
|
+
|
|
119
|
+
If you want a key to "have a better default" but **the key isn't yours** (suggesting a font size for the built-in editor, say), use `configurationDefaults`:
|
|
120
|
+
|
|
121
|
+
```jsonc
|
|
122
|
+
{
|
|
123
|
+
"contributes": {
|
|
124
|
+
"configurationDefaults": {
|
|
125
|
+
"editor.fontSize": 14
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
| Comparison | `configuration` | `configurationDefaults` |
|
|
132
|
+
|:--|:--|:--|
|
|
133
|
+
| Defining **your own** settings | ✅ | ❌ |
|
|
134
|
+
| Suggesting a default for **someone else's** key | ❌ | ✅ |
|
|
135
|
+
| After the user has set it manually | the user's value wins | the user's value wins (the weak default only applies when the user has never set it) |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 5. Common Mistakes
|
|
140
|
+
|
|
141
|
+
| Symptom | Root cause | Do this instead |
|
|
142
|
+
|:--|:--|:--|
|
|
143
|
+
| The setting never appears on the settings page | The `key` lacks the `<pluginId>.` prefix, or `default` is missing | Always `my-plugin.xxx`; you need all three of `type`/`default`/`description` |
|
|
144
|
+
| I have to restart for a settings change to take effect | You only `get` once and never subscribed | `configuration.onChange` |
|
|
145
|
+
| `npm run validate` errors out | `configuration` was written as an array / `properties` is missing | Copy the shape from §1 of this page |
|
|
146
|
+
| The value is lost on restart | You used `localStorage` or component state | `configuration.set` |
|
|
147
|
+
| I want a full-page settings UI, but I'm only changing a font size | Wrong door | The three steps on this page are enough; a full replacement is the job of [10](10-building-a-settings-plugin.md) |
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## 6. Related Reading
|
|
152
|
+
|
|
153
|
+
| What you want to do | Read this |
|
|
154
|
+
|:--|:--|
|
|
155
|
+
| The complete field table / more examples | [03-Contributes Spec](03-contributes-spec.md) |
|
|
156
|
+
| Building a whole settings UI (replacing the shell's settings page) | [10-Building a Settings Plugin](10-building-a-settings-plugin.md) |
|
|
157
|
+
| How to make several regions follow a config change | [18-Cross-Region Wiring](18-cross-region-wiring.md) |
|
|
158
|
+
| What the settings page looks like and which widgets it has | [19-Component Cheatsheet](19-component-cheatsheet.md) |
|
|
159
|
+
| Field type definitions | `plugin.schema.json` |
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Build a Theme Plugin — From Scratch to Installed
|
|
2
|
+
|
|
3
|
+
> **In one sentence: authoring a theme requires no code.** A theme plugin = **one JSON recipe** + **one declaration**. Changing the color scheme means editing that JSON.
|
|
4
|
+
>
|
|
5
|
+
> **This page is the walkthrough** (I want to build a theme, so let's go from the top); the **deep reference for recipe fields** is in [11-Authoring Themes](https://github.com/Encaron/linkdesk/blob/electron/docs/11-authoring-themes.md) (directory conventions / fully-specified example / pitfalls table), and the **index of fields and variables** is in [02-Theme Field Index](02-theme-field-index.md).
|
|
6
|
+
|
|
7
|
+
| | |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Audience | Anyone who wants to build a theme (a colorway pack / a glass style) — human, or a human's AI |
|
|
10
|
+
| Form | A tutorial walkthrough (just follow it in order; no components to write at any point) |
|
|
11
|
+
| Not | A field dictionary (→ [02-Theme Field Index](02-theme-field-index.md)) · the theme system's internal design (that's shell history; authors don't need it) |
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. Build Three Mental Models First
|
|
16
|
+
|
|
17
|
+
| Concept | In one sentence |
|
|
18
|
+
|:--|:--|
|
|
19
|
+
| **Theme = plugin** | A theme takes exactly the same path as any other plugin: `plugin.json` declaration → bundle → install → marketplace. **It just has no components** (a pure data plugin) |
|
|
20
|
+
| **Recipe** | One theme file = one complete appearance recipe. It has two orthogonal axes: **style** (`appearance`) and **colorways** (`colorways[]`) |
|
|
21
|
+
| **Sparse override** | **Write only what you want to change; everything else inherits the shell default.** The less you write, the more stable it is — when the shell later adjusts a default, your theme benefits automatically |
|
|
22
|
+
|
|
23
|
+
**Style and colorway are separated** (the single most important rule of the whole design): to get "1 style base + N colorways", put `colorways[]` in **one recipe** — switching colorways only touches the array items, and the style (radius/glass/font/background) is never re-copied.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2. The Walkthrough from Scratch (five steps)
|
|
28
|
+
|
|
29
|
+
### Step 1: Scaffold the Project
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm create linkdesk-plugin theme-myglass # kebab-case name
|
|
33
|
+
cd theme-myglass
|
|
34
|
+
npm install
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The scaffold already contains `plugin.json` and `src/index.tsx`. **A theme plugin has no use for that component file** — leaving it in does no harm (it's an empty minimal view).
|
|
38
|
+
|
|
39
|
+
### Step 2: Lay Out the Directory (don't flatten it into the root)
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
theme-myglass/
|
|
43
|
+
├── plugin.json # Declaration (contributes.themes)
|
|
44
|
+
├── themes/ # ← the one and only home for recipe json
|
|
45
|
+
│ └── myglass.json
|
|
46
|
+
├── assets/ # Optional: fonts (woff2/ttf) + background images (png/jpeg/webp)
|
|
47
|
+
└── resources/ # Metadata assets such as the plugin icon
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
> 🔴 **Recipe json always goes in `themes/`**, never flattened into the plugin root. The reason is practical: themes grow deeper over time (per-surface fine-tuning, i18n, README…), so set up the three slots now and you won't have to move anything later.
|
|
51
|
+
> **A minimal theme needs only the `themes/` directory** — a pure colorway theme doesn't even need `assets/`.
|
|
52
|
+
|
|
53
|
+
### Step 3: Declare It (`plugin.json`)
|
|
54
|
+
|
|
55
|
+
```jsonc
|
|
56
|
+
{
|
|
57
|
+
"pluginId": "theme-myglass",
|
|
58
|
+
"name": "My Glass Theme",
|
|
59
|
+
"version": "0.1.0",
|
|
60
|
+
"contributes": {
|
|
61
|
+
"themes": [
|
|
62
|
+
{ "id": "myglass", "label": "My Glass", "uiTheme": "dark", "path": "themes/myglass.json" }
|
|
63
|
+
]
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| Field | Meaning |
|
|
69
|
+
|:--|:--|
|
|
70
|
+
| `id` | Theme id (the `id` in the recipe file must **match it**) |
|
|
71
|
+
| `label` | The name shown in the theme picker |
|
|
72
|
+
| `uiTheme` | `"dark"` or `"light"` — decides which baseline set (dark or light backing) is used |
|
|
73
|
+
| `path` | Path of the recipe json relative to the plugin root |
|
|
74
|
+
|
|
75
|
+
> One plugin **can ship multiple recipes** (write several entries in `contributes.themes`, each pointing at a json). But **one style with multiple colorways** is better merged into a single recipe (`colorways[]`) — that way the theme picker shows **one card with several colorways**, which is tidier than a row of cards.
|
|
76
|
+
|
|
77
|
+
### Step 4: Write the Recipe (minimal working version)
|
|
78
|
+
|
|
79
|
+
```jsonc
|
|
80
|
+
// themes/myglass.json
|
|
81
|
+
{
|
|
82
|
+
"id": "myglass",
|
|
83
|
+
"name": "My Glass",
|
|
84
|
+
"type": "dark",
|
|
85
|
+
"appearance": {
|
|
86
|
+
"radius": { "md": 10, "lg": 16 },
|
|
87
|
+
"glass": { "blur": 16, "saturate": 1.3, "tint": "rgba(255,255,255,0.06)", "opacity": 0.9 }
|
|
88
|
+
},
|
|
89
|
+
"colorways": [
|
|
90
|
+
{ "id": "violet", "name": "Violet", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
|
|
91
|
+
{ "id": "emerald", "name": "Emerald", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } }
|
|
92
|
+
]
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**Three points you must remember:**
|
|
97
|
+
|
|
98
|
+
1. **Keys in `colors` = CSS variable names with the `--` prefix stripped** (`--bg-window` → `"bg-window"`) — what you write *is* the variable; there's no second set of names to memorize.
|
|
99
|
+
2. **`colorways` is always an array** — even a single colorway goes in as a 1-item array (**there is no other spelling**).
|
|
100
|
+
3. Do **not** also write a top-level `colors` — that's the old format; the engine reads only `colorways[]`.
|
|
101
|
+
|
|
102
|
+
> To get editor completion and validation errors, add a `$schema` line at the top of the recipe pointing at the schema inside the SDK package:
|
|
103
|
+
> `"$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/theme.schema.json"` (relative to **your own project root**; this is the only accepted form).
|
|
104
|
+
|
|
105
|
+
### Step 5: See It
|
|
106
|
+
|
|
107
|
+
Themes are pure data plugins and have **no "browser preview host page"** — the only way to see the effect is in the real shell:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
npm run dev:real # Real-device loop: installs into your installed LinkDesk, refreshes as you edit
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Once installed into LinkDesk: **Settings → Appearance/Themes** shows your theme card; select it and the whole interface changes color/radius/glass together.
|
|
114
|
+
|
|
115
|
+
Publishing it to others (package → publish, two steps) follows **exactly the same** flow as any other plugin — see steps 8 and 9 of [13-Development Guide](https://github.com/Encaron/linkdesk/blob/electron/docs/13-development-guide.md).
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 3. Common Pitfalls
|
|
120
|
+
|
|
121
|
+
| Pitfall | Explanation |
|
|
122
|
+
|:--|:--|
|
|
123
|
+
| Recipe json flattened into the plugin root | Always put it in `themes/` (Step 2) |
|
|
124
|
+
| Writing a top-level `colors` (with no `colorways`) | The old format is deprecated — the engine reads only `colorways[]` |
|
|
125
|
+
| Absolute paths for assets | They all break under `file://` once packaged — **always relative paths** (`assets/...`); the shell resolves them uniformly |
|
|
126
|
+
| Copying in every key that can be changed | Sparse overrides are easier to maintain — write only the keys you differ on; anything unwritten inherits the default |
|
|
127
|
+
| The theme changes, but only takes effect inside my own plugin | Themes are **global** (shell-level CSS variables); for local overrides use your plugin's own CSS, not the theme domain |
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## 4. What Else You Get (extra powers for theme authors)
|
|
132
|
+
|
|
133
|
+
- **Mix-and-match shows up for free**: based on the domains you contribute, your theme automatically appears among the settings page's "mix sources" — **zero extra work for the author**.
|
|
134
|
+
- **Data and events**: `window.linkdesk.theme.listRecipes()` returns the recipe list (with preview colors); the `theme:changed` event gives you live wiring.
|
|
135
|
+
- **Applying a theme**: `setRecipe` / `setColorway`, or write the `app.theme` config directly.
|
|
136
|
+
|
|
137
|
+
Method signatures and payloads → [01-Plugin API Contract](https://github.com/Encaron/linkdesk/blob/electron/docs/01-plugin-api-contract.md).
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## 5. Related Reading
|
|
142
|
+
|
|
143
|
+
| What you want to do | Read this |
|
|
144
|
+
|:--|:--|
|
|
145
|
+
| **The index of recipe fields and variables** (the second doc in this folder) | [02-Theme Field Index](02-theme-field-index.md) |
|
|
146
|
+
| Recipe syntax deep reference (directory conventions / fully-specified example / full pitfalls table) | [11-Authoring Themes](https://github.com/Encaron/linkdesk/blob/electron/docs/11-authoring-themes.md) |
|
|
147
|
+
| The complete path from scratch to publishing | [13-Development Guide](https://github.com/Encaron/linkdesk/blob/electron/docs/13-development-guide.md) |
|
|
148
|
+
| I want to draw my own plugin icon / identity art | [06-plugin.json Spec](https://github.com/Encaron/linkdesk/blob/electron/docs/06-plugin-json-spec.md) |
|
|
149
|
+
| Field-level authoritative definitions | `theme.schema.json` (`schemas/theme.schema.json` inside the SDK package) |
|
|
150
|
+
| The full documentation index | [00-README](https://github.com/Encaron/linkdesk/blob/electron/docs/00-readme.md) |
|