@linkdesk/plugin-docs 0.1.59 → 0.1.60

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.
@@ -228,13 +228,15 @@ useEffect(() => {
228
228
  "cad.gridSize": {
229
229
  "type": "number",
230
230
  "default": 10,
231
+ "title": "Grid size",
231
232
  "description": "Grid size (mm)"
232
233
  },
233
234
  "cad.units": {
234
235
  "type": "string",
235
236
  "default": "mm",
236
237
  "enum": ["mm", "cm", "inch"],
237
- "enumDescriptions": ["Millimeters", "Centimeters", "Inches"],
238
+ "enumDescriptions": { "mm": "Millimeters", "cm": "Centimeters", "inch": "Inches" },
239
+ "title": "Units",
238
240
  "description": "Units"
239
241
  },
240
242
  "cad.autoSave": {
@@ -260,7 +262,9 @@ useEffect(() => {
260
262
 
261
263
  **Supported types (the full schema):** `"string"` | `"number"` | `"boolean"` | `"object"` | `"array"`
262
264
 
263
- > **Note:** there is no `"integer"` — use `"number"`. `minimum`/`maximum` are supported at runtime but are not declared in the schema yet (the IDE will flag them) — advanced usage is allowed, and loading does not validate.
265
+ > **Note:** `"integer"` is declared alongside `"number"`, and `minimum`/`maximum` are declared for numeric controls — the IDE completes all of them.
266
+
267
+ > 🟡 `title` and `enumDescriptions` are optional; your repo's verify leg `check-config-titles` warns about the ones missing during the internal-beta period and starts failing from v1 — field semantics and examples in [06-plugin-json-spec](06-plugin-json-spec.md).
264
268
 
265
269
  **Fields:**
266
270
 
@@ -270,7 +274,8 @@ useEffect(() => {
270
274
  | `default` | ✅ | default value |
271
275
  | `description` | ✅ | description — rendered as a hint by the Settings Editor |
272
276
  | `enum` | ❌ | dropdown options (optional for the string type) |
273
- | `enumDescriptions` | ❌ | option descriptions — one-to-one with enum |
277
+ | `title` | ❌ | **the row's short human-readable name** — rendered as the settings row label and shown on the line above the key on the marketplace features tab. Omitted = the row falls back to showing the configuration key, so third-party manifests that declare nothing keep working. Same value convention as `description`: the Chinese source text is the i18n key, the English translation goes in your plugin's `i18n/en.json`. Noun phrase, ≤ 12 characters (drop the plugin-name prefix); a `renderHint: "action"` row reads as a button, so take a verb phrase |
278
+ | `enumDescriptions` | ❌ | dropdown option names — an **object** mapping each `enum` value to the name shown for it (an array is rejected by the schema as the wrong field type); an option with no entry falls back to showing the raw value |
274
279
  | `uiHint` | ❌ | rendering hint — SettingsView picks the control from the hint (known values include `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"`; it is an open string — an unknown hint degrades to the default rendering for the type). `"segmented"` = a segmented single-select (the ghost dual-track scheme, declared together with `enum` + `enumDescriptions`; the short label = the part of the enumDescription before `—`, the tooltip = the whole line) |
275
280
  | `group` | ❌ | **a second-level heading inside the group** — keys sharing the same `group` value are rendered under a subheading on the settings page; keys without a `group` stay flat. Declaring a Chinese section name is enough for it to display; heading text goes through i18n (the plugin's `contributes.i18n` provides the translation). Zero shell changes — the shell mechanism works exactly the same for plugin keys |
276
281
  | `renderHint` | ❌ | rendering hint for special rows (an open string — an unknown value degrades to the default rendering for the `type`). `"action"` renders a **button** (button text = `description`, clicking runs `actionCommand`); `"readonly"` renders a **read-only status line** (the value is the return value of `statusCommand`, re-fetched every 3 seconds; it does not read configuration storage). Both are general capabilities — any plugin gets them by declaring them; usage and examples in [20-adding-a-setting](20-adding-a-setting.md) |
@@ -501,17 +501,21 @@ After installation, the Settings Editor's left-hand tree automatically gains a g
501
501
  "default": 10,
502
502
  "minimum": 1,
503
503
  "maximum": 100,
504
+ "title": "Grid size",
504
505
  "description": "Grid size (mm)"
505
506
  },
506
507
  "cad.units": {
507
508
  "type": "string",
508
509
  "default": "mm",
509
510
  "enum": ["mm", "cm", "inch"],
511
+ "enumDescriptions": { "mm": "Millimeters", "cm": "Centimeters", "inch": "Inches" },
512
+ "title": "Units",
510
513
  "description": "Units"
511
514
  },
512
515
  "cad.darkThemeOverride": {
513
516
  "type": "boolean",
514
517
  "default": false,
518
+ "title": "Force dark view",
515
519
  "description": "Force a dark view"
516
520
  }
517
521
  }
@@ -523,6 +527,13 @@ After installation, the Settings Editor's left-hand tree automatically gains a g
523
527
  **Supported types:** `"string"` | `"number"` | `"boolean"` | `"integer"`
524
528
  **Supported constraints:** `enum` (dropdown list) | `minimum` / `maximum` (numeric range) | `default` (default value)
525
529
 
530
+ **Row names (`title`) and dropdown names (`enumDescriptions`) — both optional.**
531
+
532
+ - `title` = the row's short human-readable name. The Settings Editor renders it as the row label (a plugin that declares none falls back to showing the configuration key), and the marketplace's features tab shows it on the line above the key. Same value convention as `description`: **the Chinese source text is the i18n key** — the English translation goes in your plugin's `i18n/en.json`. Keep it a noun phrase (≤ 12 characters, drop the plugin-name prefix); a row whose `renderHint` is `"action"` reads as a button, so name it as a verb phrase instead.
533
+ - `enumDescriptions` = the name shown for each `enum` value in the dropdown. It is an **object** mapping value → display name (an array is rejected — `npm run build` reports the wrong field type). A value with no entry falls back to showing the raw value, so an enum left unfilled shows `powershell` instead of `PowerShell`.
534
+
535
+ 🟡 **Gate level.** Each plugin repo's verify leg `check-config-titles` runs at **warn** level during the internal-beta period: an item missing `title`, missing its English translation, or declaring an `enum` without `enumDescriptions` is listed as a warning and the run still passes. It flips to **error** (the `--strict` switch) once LinkDesk reaches **v1** — filling these in now avoids a repo-wide sweep later. (LinkDesk's own configuration is already held at the error level.)
536
+
526
537
  **Reading settings from plugin code (through `window.linkdesk.configuration` — an iron rule of plugin communication; `import @src/core/...` is forbidden):**
527
538
  ```typescript
528
539
  function CadView() {
@@ -28,18 +28,21 @@
28
28
  "my-plugin.autoSave": { // ← the key must carry the <pluginId>. prefix
29
29
  "type": "boolean",
30
30
  "default": true, // ← default is required
31
+ "title": "Auto save", // ← the row name (optional; without it the row shows the key)
31
32
  "description": "Save automatically on exit" // ← description is required (rendered as a tooltip)
32
33
  },
33
34
  "my-plugin.refreshInterval": {
34
35
  "type": "number",
35
36
  "default": 1000,
37
+ "title": "Refresh interval",
36
38
  "description": "Refresh interval (ms)"
37
39
  },
38
40
  "my-plugin.units": {
39
41
  "type": "string",
40
42
  "default": "mm",
41
43
  "enum": ["mm", "cm", "inch"],
42
- "enumDescriptions": ["Millimeters", "Centimeters", "Inches"], // ← one-to-one with enum
44
+ "enumDescriptions": { "mm": "Millimeters", "cm": "Centimeters", "inch": "Inches" }, // ← object: enum value → display name
45
+ "title": "Display units",
43
46
  "description": "Display units"
44
47
  }
45
48
  }
@@ -56,6 +59,8 @@ npm run validate # Validate that plugin.json is well-formed
56
59
 
57
60
  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
61
 
62
+ **Two optional names worth filling in.** `title` is the row's human-readable name — the settings page shows it instead of the raw key, and the marketplace's features tab shows it on the line above the key; a row without one falls back to the key. `enumDescriptions` names each dropdown option (an **object**: value → display name); an option with no entry falls back to the raw value. Both follow the same convention as `description`: the Chinese source text is the i18n key, the English translation goes in your plugin's `i18n/en.json`. Your repo's verify leg `check-config-titles` lists the ones still missing as warnings during the internal-beta period (it becomes an error at v1) — see [06-plugin-json-spec](06-plugin-json-spec.md).
63
+
59
64
  ---
60
65
 
61
66
  ## 2. Step 2 (Optional): Make It Look Nicer
@@ -226,13 +226,15 @@ useEffect(() => {
226
226
  "cad.gridSize": {
227
227
  "type": "number",
228
228
  "default": 10,
229
+ "title": "网格大小",
229
230
  "description": "网格大小 (mm)"
230
231
  },
231
232
  "cad.units": {
232
233
  "type": "string",
233
234
  "default": "mm",
234
235
  "enum": ["mm", "cm", "inch"],
235
- "enumDescriptions": ["毫米", "厘米", "英寸"],
236
+ "enumDescriptions": { "mm": "毫米", "cm": "厘米", "inch": "英寸" },
237
+ "title": "单位",
236
238
  "description": "单位"
237
239
  },
238
240
  "cad.autoSave": {
@@ -258,7 +260,9 @@ useEffect(() => {
258
260
 
259
261
  **支持的类型(schema 全量):** `"string"` | `"number"` | `"boolean"` | `"object"` | `"array"`
260
262
 
261
- > **注意:** 没有 `"integer"`——用 `"number"`。`minimum`/`maximum` 运行时类型支持,但 schema 暂未声明(IDE 会提示)——高级用法可写,加载不校验。
263
+ > **注意:** `"integer"` 与 `"number"` 一样已在 schema 里声明;`minimum`/`maximum` 也已声明(用于数值控件)——IDE 都能补全。
264
+
265
+ > 🟡 `title` 与 `enumDescriptions` 都是可选项;你仓的 verify 腿 `check-config-titles` 在内测期对缺项列告警、v1 起判红——字段语义与示例见 [06-plugin.json规范](06-plugin.json规范.md)。
262
266
 
263
267
  **字段:**
264
268
 
@@ -268,7 +272,8 @@ useEffect(() => {
268
272
  | `default` | ✅ | 默认值 |
269
273
  | `description` | ✅ | 说明——Settings Editor 渲染为提示 |
270
274
  | `enum` | ❌ | 下拉选项(string 类型时可选) |
271
- | `enumDescriptions` | ❌ | 选项说明——和 enum 一一对应 |
275
+ | `title` | ❌ | **该行的人话短名**——渲染为设置页行名,市场详情「功能」页把它显示在键的上方一行。不声明 = 行上回退显配置键,第三方存量声明照旧能用。值域约定与 `description` 同:中文原文即 i18n key,英文译名进插件自己的 `i18n/en.json`。名词短语、≤12 字(去掉插件名前缀);`renderHint: "action"` 的行读作按钮,起动词短语 |
276
+ | `enumDescriptions` | ❌ | 下拉选项显示名——**对象**(每个 `enum` 值 → 显示名);写数组会被 schema 判为字段类型不对。没给显示名的选项回退显原文 |
272
277
  | `uiHint` | ❌ | 渲染提示——SettingsView 按 hint 选择控件(已知值 `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"` 等,开放 string——未知 hint 降级回 type 默认渲染)。`"segmented"` = 分段单选(ghost 双轨制,配合 `enum` + `enumDescriptions` 声明,短标签 = enumDescription `—` 前段、tooltip = 全句) |
273
278
  | `group` | ❌ | **组内二级标题**——同 `group` 值的 key 在设置页归到子标题下渲染;无 `group` 的 key 保持平铺。声明中文节名即显示;节名标题走 i18n(插件 `contributes.i18n` 提供翻译)。零壳改动——壳机制对插件键同样生效。 |
274
279
  | `renderHint` | ❌ | 特殊行的渲染提示(开放 string,未知值降级回 `type` 默认渲染)。`"action"` = 渲染成**按钮**(按钮文字 = `description`,点击执行 `actionCommand`);`"readonly"` = 渲染成**只读状态行**(值 = 执行 `statusCommand` 的返回值,每 3 秒重取;不读配置存储)。两个值都是通用能力——任何插件声明即生效,用法与示例见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md) |
@@ -498,17 +498,21 @@ my-plugin/
498
498
  "default": 10,
499
499
  "minimum": 1,
500
500
  "maximum": 100,
501
+ "title": "网格大小",
501
502
  "description": "网格大小 (mm)"
502
503
  },
503
504
  "cad.units": {
504
505
  "type": "string",
505
506
  "default": "mm",
506
507
  "enum": ["mm", "cm", "inch"],
508
+ "enumDescriptions": { "mm": "毫米", "cm": "厘米", "inch": "英寸" },
509
+ "title": "单位",
507
510
  "description": "单位"
508
511
  },
509
512
  "cad.darkThemeOverride": {
510
513
  "type": "boolean",
511
514
  "default": false,
515
+ "title": "强制暗色视图",
512
516
  "description": "强制暗色视图"
513
517
  }
514
518
  }
@@ -520,6 +524,13 @@ my-plugin/
520
524
  **支持的 type:** `"string"` | `"number"` | `"boolean"` | `"integer"`
521
525
  **支持的约束:** `enum`(下拉列表)| `minimum` / `maximum`(数值范围)| `default`(默认值)
522
526
 
527
+ **行名(`title`)与下拉显示名(`enumDescriptions`)——都是可选项。**
528
+
529
+ - `title` = 该行的人话短名。设置页把它渲染为行名(没声明的插件回退显配置键),市场详情「功能」页把它显示在键的上方一行。值域约定与 `description` 同:**中文原文就是 i18n key**——英文译名进你插件自己的 `i18n/en.json`。写成名词短语(≤12 字、去掉插件名前缀);`renderHint` 为 `"action"` 的行读起来是个按钮,改成动词短语起名。
530
+ - `enumDescriptions` = 下拉里每个 `enum` 值显示的名字。形态是**对象**(值 → 显示名)——写数组会被拒(`npm run build` 报字段类型不对)。没给显示名的值回退显原文,于是没补的下拉会显 `powershell` 而不是「PowerShell」。
531
+
532
+ 🟡 **门禁等级。** 每个插件仓的 verify 腿 `check-config-titles` 在内测期是**黄灯**:缺 `title`、缺英译名、或有 `enum` 没 `enumDescriptions` 都只列一行告警,跑完仍然通过;等 LinkDesk 到 **v1** 才切**红灯**(`--strict` 开关)。现在补齐可免将来全仓返工。(LinkDesk 自己的配置面已经是红灯。)
533
+
523
534
  **插件代码里读设置(走 `window.linkdesk.configuration`——插件通信铁律,禁止 `import @src/core/...`):**
524
535
  ```typescript
525
536
  function CadView() {
@@ -28,18 +28,21 @@
28
28
  "my-plugin.autoSave": { // ← key 必须带 <pluginId>. 前缀
29
29
  "type": "boolean",
30
30
  "default": true, // ← default 必填
31
+ "title": "自动保存", // ← 行名(可选;不写则行上显裸键)
31
32
  "description": "退出时自动保存" // ← description 必填(渲染成提示)
32
33
  },
33
34
  "my-plugin.refreshInterval": {
34
35
  "type": "number",
35
36
  "default": 1000,
37
+ "title": "刷新间隔",
36
38
  "description": "刷新间隔(毫秒)"
37
39
  },
38
40
  "my-plugin.units": {
39
41
  "type": "string",
40
42
  "default": "mm",
41
43
  "enum": ["mm", "cm", "inch"],
42
- "enumDescriptions": ["毫米", "厘米", "英寸"], // ← 与 enum 一一对应
44
+ "enumDescriptions": { "mm": "毫米", "cm": "厘米", "inch": "英寸" }, // ← 对象:枚举值 → 显示名
45
+ "title": "显示单位",
43
46
  "description": "显示单位"
44
47
  }
45
48
  }
@@ -56,6 +59,8 @@ npm run validate # 校验 plugin.json 合法
56
59
 
57
60
  装进 LinkDesk 后,设置页左侧出现「我的插件」分组,右侧自动渲染出这三个控件——**布尔变开关、枚举变下拉、数字变输入框**。你没写一行界面代码。
58
61
 
62
+ **两个该补的可选名字。** `title` = 该行的人话短名——设置页显示它而不显示裸键,市场详情「功能」页把它显示在键的上方;不声明则回退显键。`enumDescriptions` = 下拉每个选项的名字(**对象**:值 → 显示名);没给名字的选项回退显原文。两者约定都与 `description` 同——中文原文即 i18n key,英文译名进插件自己的 `i18n/en.json`。你仓的 verify 腿 `check-config-titles` 会在内测期把还没补的列成告警(v1 起判红)——详见 [06-plugin.json规范](06-plugin.json规范.md)。
63
+
59
64
  ---
60
65
 
61
66
  ## 二、第 2 步(可选):让它长得更像样
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.59",
3
+ "version": "0.1.60",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [