create-linkdesk-plugin 0.1.11 → 0.1.13

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.
Files changed (6) hide show
  1. package/package.json +1 -1
  2. package/template/README.md +4 -2
  3. package/template/plugin.json +21 -1
  4. package/template/resources/cover.svg +11 -0
  5. package/template/resources/icon-bar.svg +9 -0
  6. package/template/resources/icon.svg +4 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-linkdesk-plugin",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "LinkDesk 插件脚手架——`npm create linkdesk-plugin@latest my-cool-plugin` 一行生成你的第一个插件项目（对标 yo code）。",
5
5
  "type": "module",
6
6
  "bin": {
package/template/README.md CHANGED
@@ -18,7 +18,7 @@ You do not need to pre-create empty folders (git does not track them). **Create
18
18
  | `plugin.json` | The plugin manifest | **Always** |
19
19
  | `README.md` | Description — the data source for the marketplace **Details** tab | Strongly recommended |
20
20
  | `CHANGELOG.md` | Release notes — the data source for the marketplace **Changelog** tab | Strongly recommended |
21
- | `resources/` | Assets: `icon.svg` / `cover.svg` / images referenced from the README | Once you have images |
21
+ | `resources/` | Assets — **three preset placeholders, each with a job comment inside**: `icon.svg` (small in-app icon) / `icon-bar.svg` (Icon Bar single-colour glyph) / `cover.svg` (README cover), plus any images referenced from the README | Always (replace the placeholders) |
22
22
  | `i18n/` | `en.json` (key = the source string; **do not create `zh.json`**) | Once you have UI text |
23
23
  | `themes/` · `languages/` · `snippets/` | Payloads for data-only plugins | Data-only plugins |
24
24
  | `src/index.tsx` | Entry (the `entry` in `plugin.json`) | Always for view plugins |
@@ -26,7 +26,7 @@ You do not need to pre-create empty folders (git does not track them). **Create
26
26
  | `src/components/` | Components reused inside this plugin | When needed |
27
27
  | `src/services/` | Domain logic / IPC wrappers / data layer | When needed |
28
28
  | `src/styles/` | **Multiple** CSS files — keep them together here (a single file next to the entry is fine too) | When needed |
29
- | `src/__tests__/` | Unit tests (run `npm i -D vitest` yourself if you want them — the scaffold does not preinstall test tooling) | When needed |
29
+ | `src/__tests__/` | Unit tests — **test tooling is preinstalled** (`vitest` / `jsdom` / `@testing-library/react` are already in `devDependencies`); write tests and run `npm run test` | When needed |
30
30
 
31
31
  > 🔴 **Shared things do not belong here** — components/hooks reused across plugins come from `@linkdesk/ui` (the public package the shell provides; it is already declared in `package.json` as `"latest"`, which resolves to the shell's current version line when you install — pin it to a specific shell version if you need a floor). The shell supplies that one instance at runtime, so **do not import its css** and **do not write a second copy inside your plugin**. Only logic that belongs to this plugin stays local.
32
32
  > 🔴 **Assets always live in `resources/` — no loose images in the plugin root.** What gets into the install package is what is **referenced by the README** or **declared by `icon` / `marketIcon`**; the directory name itself has no magic.
@@ -37,6 +37,8 @@ You do not need to pre-create empty folders (git does not track them). **Create
37
37
  2. **UI text goes through `t()`** — `t("source string")`, with English in `i18n/en.json` and **no `zh.json`** (the source string is the key and is its own fallback). **Only add keys you actually read with `t()`** — an unread key is a dead key. Code identifiers (`src/index.tsx` and friends) are not copy — do not wrap them in `t()`.
38
38
  3. **Plugin identity comes only from declared fields in `plugin.json`** — declare whatever capability you need (`contributes` / `tabBehavior` / `icon` …). **Never make other people guess what your plugin is from a directory name or file location.**
39
39
 
40
+ **Dev preview note:** the dev host (`npm run dev`) gives your view a **fixed-height root container** (`#ld-root`) — write `height: 100%` on your root element with confidence and it fills the preview. You never need ResizeObserver self-healing or a "just in case" fallback layer; if your panel still renders collapsed or transparent in the preview, report it — don't code around it.
41
+
40
42
  ## Publishing
41
43
 
42
44
  ```bash
package/template/plugin.json CHANGED
@@ -16,9 +16,19 @@
16
16
  "pluginId": "{{pluginName}}",
17
17
  "name": "{{displayName}}", // 显示名——标签页 / 插件详情等 UI 出现处
18
18
  "version": "0.1.0", // 语义化版本 x.y.z——市场更新比较靠它；+1 时务必同笔补 CHANGELOG.md 的新段
19
+ // ── 最低壳版本──
20
+ // 模板消费 @linkdesk/ui（组件由壳池 vendor 单实例供给）⇒ 必须声明 ≥ 重锚号 0.2.13：低于它的旧壳
21
+ // 没有组件可解析，装上即视图全崩。SDK lint 腿（check-ui-min-app-version）机械把关，漏声明判红。
22
+ "minAppVersion": "0.2.13",
19
23
  "description": "{{displayName}}——我的第一个 LinkDesk 插件", // 一句话描述（插件详情页展示）
20
24
  "author": "{{author}}", // 作者名
21
- "icon": "resources/icon.svg", // 图标——图标栏 / 标签页 / 市场里显示的就是它（resources/icon.svg 是占位图，换成你的）
25
+ // ── 图标——三图模型（完整规则见作者面 06 号《plugin.json 规范》§marketIcon）──
26
+ // icon = 界面小图标：标签页 [＋] 菜单 / 欢迎页等处（要进 42px 图标栏需再声明 appearsIn.iconBar；
27
+ // ⚠️ 图标栏会对图强制单色染色——进图标栏的图要画单色线稿剪影，resources/icon-bar.svg 是预置占位）。
28
+ // marketIcon = 市场彩色身份图：市场列表行与详情页头部用（可选；缺省回落 icon）。
29
+ // cover = README 场景封面：只住 README 说明区，不是 manifest 字段（resources/cover.svg 已预置）。
30
+ "icon": "resources/icon.svg", // 占位图，换成你的
31
+ // "marketIcon": "resources/icon.svg", // 市场彩色身份图（可选；缺省回落 icon）——市场要彩色展示时取消注释
22
32
 
23
33
  // ── 入口（视图插件 = 此文件 default 导出一个 React 组件）──
24
34
  "entry": "src/index.tsx",
@@ -29,6 +39,16 @@
29
39
 
30
40
  // ── 贡献点（contributes：全部可选，按需增删）──
31
41
  "contributes": {
42
+ // ── 贡献点速查（每键一行，只指路不展开——完整语法与示例见作者面 03 号《contributes 规范》，落位见 17 号《区域地图》）──
43
+ // commands —— 注册命令：命令面板 / 右键菜单 / 快捷键 / 标题栏按钮的公共落脚点（id 用 "<pluginId>." 前缀防撞）
44
+ // keybindings —— 给命令绑快捷键：keys ＋ command ＋ when（上下文旗子，条件满足才触发）
45
+ // menus —— 菜单位声明（右键菜单走声明式，禁止手写右键菜单）
46
+ // configuration —— 声明设置项：设置页自动渲染一个分组（另见 20 号《我的插件加一条配置项》）
47
+ // titleBar —— 标题栏按钮：right[] / left[]，icon ＋ command（＋ when）
48
+ // viewsContainers / views —— 侧栏 / 底部面板的容器与视图（下面注释里有现成示例；容器 API 详见 08 号）
49
+ // themes / languages —— 主题包 / 语言包（数据型插件的载荷）
50
+ // floatingPanel —— 把你已有的某个视图声明成「可在悬浮面板打开」
51
+ // ⚠️ statusBar 不是 contributes 的键——它是 plugin.json **顶层**的 statusBar[] 数组（写进 contributes 无效，见 17 号 ⑦ 状态栏）
32
52
  // 自带翻译：key=语言码, value=相对插件根的 JSON 文件。UI 文案用 t() 读这里；无需 zh.json——中文 key 原文自带兜底。
33
53
  "i18n": { "en": "i18n/en.json" },
34
54
  // ── 需要「侧栏 / 底部面板 / 辅助侧栏」分区视图时：取消注释，在 src/views/ 放对应组件，
package/template/resources/cover.svg ADDED
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" viewBox="0 0 640 320">
2
+ <!-- README 场景封面占位——替换成你插件的真实截图/场景图（同名覆盖即可），
3
+ 在 README.md 顶部引用（模板 README 里已有注释好的引用行，取消注释即用）：
4
+ ![<插件名> cover](resources/cover.svg)
5
+ ⚠️ 这张图只住 README（市场详情页「详情」页签的说明区）——它不是市场列表/详情头的身份图，
6
+ 那个位置是 marketIcon（见 plugin.json 注释 / 作者面 06 号 §marketIcon）；
7
+ README 放图的完整规则见作者面 12 号《README 说明区媒体契约》。 -->
8
+ <rect x="0" y="0" width="640" height="320" rx="12" fill="#1E293B"/>
9
+ <rect x="170" y="110" width="300" height="100" rx="8" fill="none" stroke="#475569" stroke-width="2" stroke-dasharray="7 5"/>
10
+ <text x="320" y="166" fill="#64748B" font-family="sans-serif" font-size="17" text-anchor="middle">cover.svg — your scene here</text>
11
+ </svg>
package/template/resources/icon-bar.svg ADDED
@@ -0,0 +1,9 @@
1
+ <svg fill="none" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
2
+ <!-- 图标栏 Type-1 单色线稿剪影占位——替换成你自己插件的剪影（同名覆盖即可）。
3
+ 用法：plugin.json 里 "appearsIn": { "iconBar": "top" } ＋ "icon": "resources/icon-bar.svg"。
4
+ ⚠️ 图标栏会对图强制单色染色——别放彩色图（彩色进来会糊成一团）；
5
+ 这是独立 SVG 文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。
6
+ 市场里要彩色身份图不归这张管——那是 marketIcon 的职责（见 plugin.json 注释 / 作者面 06 号 §marketIcon）。 -->
7
+ <rect x="4.5" y="4.5" width="15" height="15" rx="3.5" stroke="#9CA3AF" stroke-width="1.8" stroke-dasharray="3.5 2.5" stroke-linecap="round"/>
8
+ <path d="M12 9v6M9 12h6" stroke="#9CA3AF" stroke-width="1.8" stroke-linecap="round"/>
9
+ </svg>
package/template/resources/icon.svg CHANGED
@@ -1,7 +1,10 @@
1
1
  <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48">
2
2
  <!-- ⚠️ 占位图——请替换成你自己插件的图标（同名同位置覆盖即可，plugin.json 的 icon 已指向本文件）。
3
3
  写法与官方插件一致：界面里以 <img src="linkdesk://<id>/resources/icon.svg"> 显示，
4
- 是独立文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。 -->
4
+ 是独立文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。
5
+ 三图模型——本文件 = 界面小图标（要进图标栏需 appearsIn.iconBar，图标栏会强制单色染色，
6
+ 进图标栏请换 resources/icon-bar.svg 那样的单色剪影）；市场彩色身份图 = marketIcon；
7
+ README 场景封面 = resources/cover.svg。各管各的，详见作者面 06 号《plugin.json 规范》§marketIcon。 -->
5
8
  <defs>
6
9
  <linearGradient id="phi_bg" x1="0" y1="0" x2="1" y2="1">
7
10
  <stop offset="0" stop-color="#64748B"/>