@linkdesk/plugin-docs 0.1.70 → 0.1.72

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.
@@ -569,7 +569,9 @@ both stylesheets land on the same element.
569
569
  | Source | Reserved names | Notes |
570
570
  |---|---|---|
571
571
  | 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") |
572
- | 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**) |
572
+ | 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), `ldk-famgr` (2026-10-06, the class family of the file-associations manager assembly view), `ldk-plugin-card-toolbar` (`PluginCard`'s toolbar slot) (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**) |
573
+
574
+ **Slots are the host's surface too.** A slot a shared component gives you—`PluginCard`'s `toolbar`, for instance—is **its own row** in the host's layout (`.ldk-plugin-card-toolbar`). What you put in it is *content*, therefore: ⛔ don't nest the slot's content inside one of the host's own buttons or drag it into the card head with negative margins (the card head is itself the expand/collapse button, so nesting means your toolbar and the collapse fight over the same click area); ⛔ don't borrow a host family segment for the elements you put in the slot (use your own `pluginId` prefix); ⛔ don't move the slot (the host decides where that row sits—you **fill** it, you don't lay it out).
573
575
 
574
576
  **`@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.
575
577
 
@@ -97,6 +97,8 @@ import { InlineInput, SelectBox, FormRow } from "@linkdesk/ui";
97
97
 
98
98
  > The official settings implementation (`src/views/SettingsView.tsx`, in the settings plugin's own repo) imports from `@linkdesk/ui` — copy the import line as-is, no extra project configuration needed.
99
99
 
100
+ **Exclusive capability groups are not private to a renderer either — they are shared parts too.** A whole manager section like the "default Open With" manager (the host group declaring `uiHint: "fileAssociationsManager"`) reaches a renderer as the shared **assembly view** `ManagerView` plus the shared `buildManagerModel` / `orderRows` / `filterRows`: recognise that hint and the whole group goes to `ManagerView`; a renderer that does not recognise the hint uses `isSettingsHiddenHint` to decide which rows not to draw. So a second settings UI's author can build it fully **without reading the official set's source** — their job is only the *assembly* (dispatch, grouping, search, wiring), and ⛔ row states / group merging / row order and filtering are never written a second time inside a renderer.
101
+
100
102
  ## The composition layer is free-form — same data, laid out however you like
101
103
 
102
104
  The data API only determines "what data exists"; **the layout is your free play**. Current references:
@@ -194,6 +194,11 @@ watching it for you).
194
194
  hook names are **not judged**; test and mock files are not scanned.
195
195
  - **Informed bypass**: `// eslint-disable-next-line linkdesk/no-reserved-class-name -- reason` (same id as the
196
196
  namespace leg).
197
+ - **Where the family ledger lives**: the `ldk-` **family segments** owned by the host and the shared components
198
+ (including `ldk-famgr` from 2026-10-06—the class family of the file-associations manager assembly view) are not
199
+ registered in the table above; their registry is the two reserved-name tables in
200
+ [05-UI Conventions §12](05-ui-conventions.md) (guarded both ways by `check-reserved-names-doc-sync`). You may
201
+ **consume** them only, ⛔ never borrow a family segment to name your own elements.
197
202
  - **Host definition set unreadable** ⇒ the leg reports "**unverified**" instead of "0 issues"—that means a broken
198
203
  install; reinstall `@linkdesk/plugin-sdk`.
199
204
 
@@ -59,6 +59,7 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
59
59
  | **0.2.22** | `ReadOnlyText`, `SectionSubtitle` | — | — |
60
60
  | **0.2.40** | `BackgroundImagePicker`, `EffectiveBadge`, `SegmentPreviewSwatch`, `SegmentPreviewText`, `SourceBadge` | `useStatusPolling`, `CONFIG_NONE_SENTINEL`, `MIX_FOLLOW_THEME_SENTINEL`, `SETTINGS_RENDER_HINTS`, `SETTINGS_UI_HINTS`, `formatEffectiveValue`, `isSettingsUiHint`, `splitStringList` | `BackgroundImagePickerProps`, `EffectiveBadgeProps`, `RunStatusCommand`, `SourceBadgeKind`, `SourceBadgeProps`, `SourceBadgeSource` |
61
61
  | **0.2.48** | `OpenWithPicker`, `PluginCard` | — | `OpenWithHandler`, `OpenWithPickerProps`, `OpenWithRequest` |
62
+ | **0.2.52** | `CardRow`, `ContestedRow`, `ManagerView` | `EXT_LABEL_MAX`, `SETTINGS_HIDDEN_HINTS`, `buildManagerModel`, `extLabelHead`, `extractDeclaredExtensions`, `filterRows`, `hitKindOf`, `isSettingsHiddenHint`, `normalizeExt`, `normalizeExtList`, `orderRows`, `overrideKeyOf`, `readOverride` | `BuildInput`, `CardModel`, `CardRowProps`, `ContestedRowModel`, `ContestedRowProps`, `DeclaredExtension`, `DeclaredPlugin`, `ExtRowModel`, `HandlerSnapshot`, `ManagerModel`, `ManagerViewProps`, `RowOption`, `RowSortMode`, `RowState` |
62
63
  <!-- ui-since:end -->
63
64
 
64
65
  **How to use it**: look up every export you **import statically** and take the largest `since` — that is your `minAppVersion` floor (below it, the whole plugin **fails to load** on that older shell, it is not "one component missing"). You do not have to compute it yourself: `npm run lint` tells you the number to put in (see [04-distribution-format §minAppVersion](04-distribution-format.md)).
@@ -104,6 +105,8 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
104
105
  | `ReadOnlyText` | Read-only text (single-line or multi-line, not editable) | Showing a **read-only value**: paths, addresses, live status lines (this is what the settings page's read-only status rows use — declare `renderHint: "readonly"` + `statusCommand`, see [20-adding-a-setting](20-adding-a-setting.md)) |
105
106
  | `SectionSubtitle` | Section subtitle (one small line under a heading) | A one-line note under a group/section — the settings page renders `subtitle` / `groupDescriptions` with it, and you can use it directly when assembling your own explanatory block |
106
107
  | `OpenWithPicker` | The "Open with…" picker panel (rows = handlers, each labelled with the plugin's name and its icon) | Letting the user choose **which plugin opens a file / a type**. 🔴 **Call the host command, don't build your own panel**: `openWith({ uri })` / `openWith({ ext })` from `@linkdesk/plugin-sdk` rises the centered panel; the shell assembles the handler list (names, icons, current default) and sends the action back. The component is exported so the panel is one implementation, ⛔ not so every plugin draws its own |
108
+ | `PluginCard` | Plugin card shell (identity art + expandable head + gear + disabled state) with a `toolbar` slot | When you draw "one plugin's card" in a settings page or list. **To give a card a toolbar** (filter box, sort dropdown, action buttons), hand it to the `toolbar` slot: it renders as its **own row** between the card head and the card body (`.ldk-plugin-card-toolbar`). ⚠️ The card head is itself the expand/collapse button, so ⛔ never nest interactive controls inside it |
109
+ | `ManagerView` | **A whole manager assembly view** (the "types with multiple handlers" section + the "browse by plugin" card list + empty states / group collapsing) | The host group that declares `uiHint: "fileAssociationsManager"` (the default Open With manager). Feed it the result of `buildManagerModel({ plugins, handlersByExt, overrideTable, search })` and an `onPick(exts, pluginId, label)` writer (`pluginId: null` = restore automatic); pass `contestedGearItems` / `cardGearItems` / `cardRowGearItems` to add gear menus, command ids stay yours. 🔴 **Row states, group merging and row order/filtering live in exactly one implementation — the shared parts**; if you assemble it yourself, still use `CardRow` / `ContestedRow` + `orderRows` / `filterRows` (and `hitKindOf` for the matched reason), ⛔ never a second implementation in your plugin |
107
110
 
108
111
  > 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**.
109
112
 
@@ -562,7 +562,9 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
562
562
  | 来源 | 保留名 | 说明 |
563
563
  |---|---|---|
564
564
  | 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
565
- | 共享组件类名 + 宿主容器类名 | **整个 `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`:那个是**给你用的**) |
565
+ | 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle`、`ldk-hint-card`(2026-09-19 起,悬停说明卡)、`ldk-famgr`(2026-10-06 起,文件关联管理器组装视图的类族)、`ldk-plugin-card-toolbar`(`PluginCard` 的工具条槽)等(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
566
+
567
+ **槽位(slot)也是宿主的面。** 共享件给的槽——例如 `PluginCard` 的 `toolbar`——是宿主布局里**独立的一行**(`.ldk-plugin-card-toolbar`)。往里放的是**内容**,所以:⛔ 不要把槽的内容塞进宿主自己的按钮或用负外边距「并进」卡头(卡头本身就是展开/折叠按钮,塞进去=工具条与折叠抢同一个点击面);⛔ 不要给槽里的元素借用宿主族段(用你自己的 `pluginId` 前缀);⛔ 不要给槽换布局位置(槽的位置是宿主定的,你是往里**填**,不是重排这一行)。
566
568
 
567
569
  **`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
568
570
 
@@ -97,6 +97,8 @@ import { InlineInput, SelectBox, FormRow } from "@linkdesk/ui";
97
97
 
98
98
  > 官方 settings 实样(`src/views/SettingsView.tsx`,在 settings 插件自己的仓里)就是从 `@linkdesk/ui` import——照抄 import 行即可,不用额外工程配置。
99
99
 
100
+ **独占能力组也不在渲染器里私有——它们同样是共享件。** 像「默认打开方式管理器」这种一整段管理器(宿主贡献点声明 `uiHint: "fileAssociationsManager"`),渲染套拿到的是共享**组装视图** `ManagerView` + 共享的 `buildManagerModel`/`orderRows`/`filterRows`:识别到该 hint ⇒ 整组交给 `ManagerView`;不认识的渲染套按 `isSettingsHiddenHint` 决定不画哪一行。所以第二套设置 UI 的作者**不读官方套源码也能做全**——他要写的只有「组装」(分发、分组、搜索、接线),⛔ 行状态/分组合并/行序过滤不在渲染器里各写一份。
101
+
100
102
  ## 编排层自由组合——数据一样,想怎么排就怎么排
101
103
 
102
104
  数据 API 只决定"有什么数据";**布局是你的自由发挥**。现役参考:
@@ -193,6 +193,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
193
193
  - **不用怕假红**:动态拼出来的名字(`` className={`x-${v}`} ``)**跳过并计数**、不判;第三方自带的
194
194
  (Monaco / codicon 那一类,名字+规则都在它随包样式里)与 DOM 钩子名**不计悬空**;测试与 mock 文件不扫。
195
195
  - **知情绕行**:`// eslint-disable-next-line linkdesk/no-reserved-class-name -- 理由`(与命名空间腿同一 id)。
196
+ - **族段的账在哪**:宿主与共享件自有的 `ldk-` **族段**(含 2026-10-06 起的 `ldk-famgr`——文件关联管理器组装视图的类族)不在本文的总表里登记;登记处是 [05-插件UI写法规约 §12](05-插件UI写法规约.md) 的两张保留名表(`check-reserved-names-doc-sync` 双向守)。你**只能消费**,⛔ 不能借族段给自己的元素命名。
196
197
  - **宿主定义集读不到** ⇒ 判据报「**未核验**」而不是「0 处通过」——那是包不完整,重装 `@linkdesk/plugin-sdk`。
197
198
 
198
199
  ### 7.7 菜单槽位的名字是**值**,不是成员名(`@linkdesk/plugin-sdk` 0.1.56 起)
@@ -60,6 +60,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
60
60
  | **0.2.22** | `ReadOnlyText`、`SectionSubtitle` | — | — |
61
61
  | **0.2.40** | `BackgroundImagePicker`、`EffectiveBadge`、`SegmentPreviewSwatch`、`SegmentPreviewText`、`SourceBadge` | `useStatusPolling`、`CONFIG_NONE_SENTINEL`、`MIX_FOLLOW_THEME_SENTINEL`、`SETTINGS_RENDER_HINTS`、`SETTINGS_UI_HINTS`、`formatEffectiveValue`、`isSettingsUiHint`、`splitStringList` | `BackgroundImagePickerProps`、`EffectiveBadgeProps`、`RunStatusCommand`、`SourceBadgeKind`、`SourceBadgeProps`、`SourceBadgeSource` |
62
62
  | **0.2.48** | `OpenWithPicker`、`PluginCard` | — | `OpenWithHandler`、`OpenWithPickerProps`、`OpenWithRequest` |
63
+ | **0.2.52** | `CardRow`、`ContestedRow`、`ManagerView` | `EXT_LABEL_MAX`、`SETTINGS_HIDDEN_HINTS`、`buildManagerModel`、`extLabelHead`、`extractDeclaredExtensions`、`filterRows`、`hitKindOf`、`isSettingsHiddenHint`、`normalizeExt`、`normalizeExtList`、`orderRows`、`overrideKeyOf`、`readOverride` | `BuildInput`、`CardModel`、`CardRowProps`、`ContestedRowModel`、`ContestedRowProps`、`DeclaredExtension`、`DeclaredPlugin`、`ExtRowModel`、`HandlerSnapshot`、`ManagerModel`、`ManagerViewProps`、`RowOption`、`RowSortMode`、`RowState` |
63
64
  <!-- ui-since:end -->
64
65
 
65
66
  **怎么用**:把你**静态导入**的每个导出查一遍,取最大的那个 `since` ⇒ 就是你的 `minAppVersion` 下限(低了,旧壳上**整只插件加载失败**——不是「那个组件不显示」)。不用自己算:`npm run lint` 会直接告诉你该填多少(见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
@@ -105,6 +106,8 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
105
106
  | `ReadOnlyText` | 只读文字(单行/多行,不可编辑) | 显示**只读值**:路径、地址、实时状态行(设置页的只读状态行使的就是它——声明 `renderHint: "readonly"` + `statusCommand` 即可,见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md)) |
106
107
  | `SectionSubtitle` | 分节副标题(标题下的一行小字) | 分组/分节下面的一行说明——设置页用它渲染 `subtitle` / `groupDescriptions`,自己拼说明区时也可以直接用它 |
107
108
  | `OpenWithPicker` | 「打开方式…」选择器面板(每行一个处理器:插件名 + 图标) | 让用户挑**某文件/某类型用哪个插件打开**时。🔴 **调宿主命令即可,⛔ 别自己实现面板**:`@linkdesk/plugin-sdk` 的 `openWith({ uri })` / `openWith({ ext })` 升起居中选择面板,处理器表(名字、图标、当前默认)由宿主装配、动作由宿主回收。本组件导出是为了「面板只有一份实现」,⛔ 不是让每只插件各画一套 |
109
+ | `PluginCard` | 插件卡外壳(身份图 + 可展开卡头 + 齿轮 + 禁用态),另有一个 `toolbar` 槽 | 你要在设置页/列表里画「一张插件的卡」时。**要给卡加工具条**(过滤框、排序下拉、动作按钮)就把它交给 `toolbar` 槽:它渲染在卡头之下、卡体之上的**独立一行**(`.ldk-plugin-card-toolbar`)。⚠️ 卡头本身就是展开/折叠按钮,⛔ 别把交互控件塞进卡头里 |
110
+ | `ManagerView` | **整段管理器组装视图**(「多候选类型」小节 +「按插件浏览」卡片列表 + 空态/局部折叠) | 宿主贡献点声明 `uiHint: "fileAssociationsManager"` 的那一组(默认打开方式管理器)。数据喂 `buildManagerModel({ plugins, handlersByExt, overrideTable, search })` 的产物,动作给一个 `onPick(exts, pluginId, label)` 写入器(`pluginId: null` = 恢复自动);要齿轮就传 `contestedGearItems` / `cardGearItems` / `cardRowGearItems`,命令 id 归你。🔴 **行状态/分组合并/行序与过滤只有共享件这一份实现**——自画也只用 `CardRow`/`ContestedRow` + `orderRows`/`filterRows`(含命中原因 `hitKindOf`),⛔ 别在插件里再写一份 |
108
111
 
109
112
  > 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
110
113
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.70",
3
+ "version": "0.1.72",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [