@linkdesk/plugin-docs 0.1.72 → 0.1.74

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.
@@ -230,6 +230,20 @@ const { t } = useTranslation();
230
230
  <button>{t("发送")}</button> // the i18n key = the plugin UI's source text (a Chinese plugin uses Chinese, an English/French plugin uses its own language)
231
231
  ```
232
232
 
233
+ **🔴 Don't mix up the two sources — same `t()`, opposite verdicts:**
234
+
235
+ | The string in your hand | What to do |
236
+ |:--|:--|
237
+ | A text field the host **has already resolved** (`bellTitle` / `panelTitle` / group labels returned by `pool.getLayout()` / `notifications.list()`, …) | **Display as-is** — do ⛔ not pass it through `t()` a second time (source: [01-plugin-api-contract](01-plugin-api-contract.md), read-surface rules ③) |
238
+ | Text **you declared yourself** (plugin display name from the manifest, a file type's `displayName`, an option `label`, …) arriving back to you **as a variable** | **Must go through `t(thatVariable)` before rendering** — ⛔ never render the raw variable |
239
+
240
+ ```tsx
241
+ {row.handlers.map((h) => <option key={h.pluginId} value={h.pluginId}>{t(h.label)}</option>)}
242
+ // ^^^^^^^^ declared source text arrives as a variable ⇒ wrap it in t()
243
+ ```
244
+
245
+ **Why this needs its own rule:** both literal gates (`audit-i18n` / the dictionary gate) only collect **Chinese literals inside `t()`**; a **variable form** like `{name}` is invisible to them by construction — write it wrong and nothing turns red, you only see it when **the English UI actually shows Chinese**. Same goes when a shared component hands display names back to you as data (e.g. `RowOption.label` from `@linkdesk/ui`).
246
+
233
247
  ---
234
248
 
235
249
  ## 7. Sidebar List Item Selection → `onMouseDown` (not `onClick`)
@@ -59,7 +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
+ | **0.2.52** | `CardRow`, `ColorField`, `ContestedRow`, `ManagerView`, `ObjectEditor` | `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
63
  <!-- ui-since:end -->
64
64
 
65
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)).
@@ -226,6 +226,20 @@ const { t } = useTranslation();
226
226
  <button>{t("发送")}</button> // i18n key = 插件 UI 原文(中文插件用中文,英文/法文插件用自己的语言)
227
227
  ```
228
228
 
229
+ **🔴 两种来源别混——同一枚 `t()`,判据相反:**
230
+
231
+ | 你手里的字符串 | 怎么办 |
232
+ |:--|:--|
233
+ | 宿主**已经解析好**的文案字段(`pool.getLayout()` / `notifications.list()` 回的 `bellTitle` / `panelTitle` / 分组 label 等) | **原样显示**,⛔ 不要再 `t()` 一次(出处 [01-插件API契约](01-插件API契约.md) 三条读取面规矩 ③) |
234
+ | **你自己声明的文本**(清单/声明里的插件显示名、文件类型 `displayName`、选项 `label`…)——**以变量形态**回到你手上时 | **渲染前必须过 `t(那个变量)`**,⛔ 不许直接渲染它 |
235
+
236
+ ```tsx
237
+ {row.handlers.map((h) => <option key={h.pluginId} value={h.pluginId}>{t(h.label)}</option>)}
238
+ // ^^^^^^^^ 声明原文是变量 ⇒ 过 t()
239
+ ```
240
+
241
+ **为什么这条要单列**:两道字面量门(`audit-i18n` / 词典门)只收 `t()` 里的**中文字面量**,`{name}` 这种**变量形态**它们原理上照不到——写歪了不会报红,只有**英文界面真的露出中文**才看得见。共享件把显示名当数据交回来时(如 `@linkdesk/ui` 的 `RowOption.label`)同理。
242
+
229
243
  ---
230
244
 
231
245
  ## 7. 侧栏列表选中条目 → `onMouseDown`(不是 `onClick`)
@@ -60,7 +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
+ | **0.2.52** | `CardRow`、`ColorField`、`ContestedRow`、`ManagerView`、`ObjectEditor` | `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` |
64
64
  <!-- ui-since:end -->
65
65
 
66
66
  **怎么用**:把你**静态导入**的每个导出查一遍,取最大的那个 `since` ⇒ 就是你的 `minAppVersion` 下限(低了,旧壳上**整只插件加载失败**——不是「那个组件不显示」)。不用自己算:`npm run lint` 会直接告诉你该填多少(见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.72",
3
+ "version": "0.1.74",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [