@linkdesk/plugin-docs 0.1.6 → 0.1.8
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.
|
@@ -549,21 +549,21 @@ both stylesheets land on the same element.
|
|
|
549
549
|
|
|
550
550
|
| Source | Reserved names | Notes |
|
|
551
551
|
|---|---|---|
|
|
552
|
-
|
|
|
553
|
-
| 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` (shared components), plus the host's own container classes such as `ldk-titlebar` | 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** |
|
|
552
|
+
| 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") |
|
|
553
|
+
| 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` (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**) |
|
|
554
554
|
|
|
555
555
|
**`@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.
|
|
556
556
|
|
|
557
557
|
| Reserved keyframe names | Notes |
|
|
558
558
|
|---|---|
|
|
559
|
-
| `selectbox-in` | the shared select dropdown's entrance animation |
|
|
560
|
-
| `drop-zone-in` | the drop zone's entrance animation |
|
|
561
|
-
| `dropdown-card-in` | the dropdown card's entrance animation |
|
|
562
|
-
| `floating-panel-in` | the floating panel's entrance animation |
|
|
563
|
-
| `group-tab-enter` | the group tab's entrance animation |
|
|
564
|
-
| `group-tab-exit` | the group tab's exit animation |
|
|
565
|
-
| `notif-icon-spin` | the notification icon's spin |
|
|
566
|
-
| `notif-progress-scan` | the notification progress scan |
|
|
559
|
+
| `ldk-selectbox-in` | the shared select dropdown's entrance animation |
|
|
560
|
+
| `ldk-drop-zone-in` | the drop zone's entrance animation |
|
|
561
|
+
| `ldk-dropdown-card-in` | the dropdown card's entrance animation |
|
|
562
|
+
| `ldk-floating-panel-in` | the floating panel's entrance animation |
|
|
563
|
+
| `ldk-group-tab-enter` | the group tab's entrance animation |
|
|
564
|
+
| `ldk-group-tab-exit` | the group tab's exit animation |
|
|
565
|
+
| `ldk-notif-icon-spin` | the notification icon's spin |
|
|
566
|
+
| `ldk-notif-progress-scan` | the notification progress scan |
|
|
567
567
|
|
|
568
568
|
> 🔧 **Maintainer note (authors can skip this)**—the **Reserved names** and **Reserved keyframe names** columns in the two tables above are **machine-read**: the gate
|
|
569
569
|
> in `npm run check` (`scripts/check-reserved-names-doc-sync.mjs`) cross-checks them **both ways** against the
|
|
@@ -636,6 +636,38 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
|
|
|
636
636
|
|
|
637
637
|
> Want to see whether your project has bare names right now? Run `npm run verify` in the project root.
|
|
638
638
|
|
|
639
|
+
### 12.3 The host's input-box utility was renamed: `.input` → `.ldk-input` (2026-09-16)
|
|
640
|
+
|
|
641
|
+
**In one line: if your plugin wrote `className="input"`, change it to `className="ldk-input"`—the styling is identical, only the name changed.**
|
|
642
|
+
|
|
643
|
+
- **What changed**: the host used to call its input-box utility **`.input`** (no prefix—the only host public name without `ldk-`). That conflicted with rule 1 above ("every cross-party name carries a namespace") ⇒ it is now **`.ldk-input`**. The host's **setting-group card**, `.setting-group`, was renamed to **`.ldk-setting-group`** at the same time.
|
|
644
|
+
- **Who is affected**: **any plugin that wrote `className="input"` in its own JSX/TSX**—among the official plugins, `settings` and `serial-monitor` used it and were updated in the same release batch. **The fix is one place**: `className="input"` → `className="ldk-input"`; the same for concatenated forms (`"input my-input"` → `"ldk-input my-input"`). **Zero styling change**—same rule, same CSS variables, only the name.
|
|
645
|
+
- **What happens if you don't**: the input doesn't error; it simply **loses the host-provided appearance** (background / border / radius / padding) and looks like a browser-native input.
|
|
646
|
+
- **When you must change it**: as soon as you run on the **new shell**. The new shell version is **`0.2.0`**, and both official plugins now declare `minAppVersion: "0.2.0"` in `plugin.json`—declare the same value in your plugin and users on an older shell get a clear "requires app version ≥0.2.0" message instead of an unstyled input (see [04-distribution-format §minAppVersion](04-distribution-format.md) for the semantics).
|
|
647
|
+
|
|
648
|
+
### 12.4 The rest of the shared components' class names took the `ldk-` prefix too (2026-09-16)
|
|
649
|
+
|
|
650
|
+
**In one line: same story as 12.1, just for the components that 12.1 didn't cover—if your own CSS tunes those components with descendant selectors, add the `ldk-` prefix when you upgrade.**
|
|
651
|
+
|
|
652
|
+
- **What changed**: §12.1 covered the eight base names of `@linkdesk/ui` (`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`) at **0.2.0**. The remaining components' class names—plus one `@keyframes` name—now carry the prefix too, at **`@linkdesk/ui` 0.3.0**:
|
|
653
|
+
|
|
654
|
+
| Old family | New family |
|
|
655
|
+
|---|---|
|
|
656
|
+
| `.colorpicker-*` | `.ldk-colorpicker-*` |
|
|
657
|
+
| `.ctx-*` | `.ldk-ctx-*` |
|
|
658
|
+
| `.form-row` | `.ldk-form-row` |
|
|
659
|
+
| `.inline-input`, `.inline-input--compact/--normal` | `.ldk-inline-input`, `.ldk-inline-input--compact/--normal` |
|
|
660
|
+
| `.number-input*` | `.ldk-number-input*` |
|
|
661
|
+
| `.segmented-radio`, `.segmented-radio__option/__label` | `.ldk-segmented-radio`, `.ldk-segmented-radio__option/__label` |
|
|
662
|
+
| `.sidebar-section*`, `.sidebar-pane-view`, `.sidebar-pane-sash` | `.ldk-sidebar-section*`, `.ldk-sidebar-section-pane-view`, `.ldk-sidebar-section-pane-sash` |
|
|
663
|
+
| `.theme-picker*`, `.theme-card`, `.theme-preview` | `.ldk-theme-picker*`, `.ldk-theme-picker-card`, `.ldk-theme-picker-preview` |
|
|
664
|
+
| `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot` (theme-card internals) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
|
|
665
|
+
| `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
|
|
666
|
+
|
|
667
|
+
- **Who is affected**: again **only your own CSS**'s descendant selectors that point at those components (e.g. `.settings-row:has(.theme-picker)`). **The components' own styling does not change, and your own class names stay as they are.** The whole point is that the shared components' names now all live in the `ldk-` namespace, whose rule you already know: **anything starting with `ldk-` belongs to the host—don't put it on your own elements** (the one exception is `.ldk-input`, the utility that is **for you**).
|
|
668
|
+
- **What happens if you don't**: exactly the silent failure described in 12.1—the selector just stops matching and those few rules quietly stop applying. **No error.**
|
|
669
|
+
- **When you must change it**: when you move to **`@linkdesk/ui` 0.3.0**. `^0.2.0` does not resolve `0.3.0` (that's how 0.x ranges work), so nothing breaks until you upgrade deliberately. **Grep your own CSS for the old names** after upgrading: an official plugin (`settings`) had exactly one such spot and it was fixed in the same release batch.
|
|
670
|
+
|
|
639
671
|
---
|
|
640
672
|
|
|
641
673
|
## Quick Reference
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -544,21 +544,21 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
544
544
|
|
|
545
545
|
| 来源 | 保留名 | 说明 |
|
|
546
546
|
|---|---|---|
|
|
547
|
-
|
|
|
548
|
-
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 +
|
|
547
|
+
| 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
|
|
548
|
+
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
|
|
549
549
|
|
|
550
550
|
**`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
|
|
551
551
|
|
|
552
552
|
| 保留的关键帧名 | 说明 |
|
|
553
553
|
|---|---|
|
|
554
|
-
| `selectbox-in` | 共享组件下拉框的入场动画 |
|
|
555
|
-
| `drop-zone-in` |
|
|
556
|
-
| `dropdown-card-in` | 下拉卡片的入场动画 |
|
|
557
|
-
| `floating-panel-in` | 浮动面板的入场动画 |
|
|
558
|
-
| `group-tab-enter` | 分组标签的入场动画 |
|
|
559
|
-
| `group-tab-exit` | 分组标签的退场动画 |
|
|
560
|
-
| `notif-icon-spin` | 通知图标的旋转 |
|
|
561
|
-
| `notif-progress-scan` | 通知的进度扫描 |
|
|
554
|
+
| `ldk-selectbox-in` | 共享组件下拉框的入场动画 |
|
|
555
|
+
| `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
|
|
556
|
+
| `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
|
|
557
|
+
| `ldk-floating-panel-in` | 浮动面板的入场动画 |
|
|
558
|
+
| `ldk-group-tab-enter` | 分组标签的入场动画 |
|
|
559
|
+
| `ldk-group-tab-exit` | 分组标签的退场动画 |
|
|
560
|
+
| `ldk-notif-icon-spin` | 通知图标的旋转 |
|
|
561
|
+
| `ldk-notif-progress-scan` | 通知的进度扫描 |
|
|
562
562
|
|
|
563
563
|
> 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
|
|
564
564
|
> (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
|
|
@@ -620,6 +620,38 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
620
620
|
|
|
621
621
|
> 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
|
|
622
622
|
|
|
623
|
+
### 12.3 宿主的输入框工具类改名了:`.input` → `.ldk-input`(2026-09-16)
|
|
624
|
+
|
|
625
|
+
**一句话:如果你的插件写过 `className="input"`,改成 `className="ldk-input"` 就行——样式一模一样,只是名字换了。**
|
|
626
|
+
|
|
627
|
+
- **改了什么**:宿主原来把一个输入框工具类叫 **`.input`**(不带前缀,是唯一一个不带 `ldk-` 的宿主公共名)。它和本条纪律 1「跨方的名字都带命名空间」冲突 ⇒ 现在统一叫 **`.ldk-input`**。同时宿主的**设置分组卡片** `.setting-group` 也改名为 **`.ldk-setting-group`**。
|
|
628
|
+
- **谁受影响**:**在你自己插件的 JSX/TSX 里写过 `className="input"` 的插件**——官方插件里 `settings` 与 `serial-monitor` 两家用过,已在同一批发版改好。**改法就一处**:`className="input"` → `className="ldk-input"`;拼接写法同理(`"input my-input"` → `"ldk-input my-input"`)。**样式零变化**——同一条规则、同一批 CSS 变量,只换了名字。
|
|
629
|
+
- **不改会怎样**:输入框**不报错**,只是**失去宿主给的外观**(底色 / 边框 / 圆角 / 内边距),看起来像浏览器原生输入框。
|
|
630
|
+
- **什么时候必须改**:在**新壳**上跑就要改。新壳的版本号是 **`0.2.0`**,官方两只插件都已在 `plugin.json` 里声明 `minAppVersion: "0.2.0"`——你也给自己的插件声明同一个值,旧壳上的用户就会收到一句清楚的「需要应用版本 ≥0.2.0」提示,而不是看到一个没样式的输入框(`minAppVersion` 的语义见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
|
|
631
|
+
|
|
632
|
+
### 12.4 共享组件剩下的类名也带 `ldk-` 了(2026-09-16)
|
|
633
|
+
|
|
634
|
+
**一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
|
|
635
|
+
|
|
636
|
+
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀,**`@linkdesk/ui` 0.3.0 起**:
|
|
637
|
+
|
|
638
|
+
| 旧族 | 新族 |
|
|
639
|
+
|---|---|
|
|
640
|
+
| `.colorpicker-*` | `.ldk-colorpicker-*` |
|
|
641
|
+
| `.ctx-*` | `.ldk-ctx-*` |
|
|
642
|
+
| `.form-row` | `.ldk-form-row` |
|
|
643
|
+
| `.inline-input`、`.inline-input--compact/--normal` | `.ldk-inline-input`、`.ldk-inline-input--compact/--normal` |
|
|
644
|
+
| `.number-input*` | `.ldk-number-input*` |
|
|
645
|
+
| `.segmented-radio`、`.segmented-radio__option/__label` | `.ldk-segmented-radio`、`.ldk-segmented-radio__option/__label` |
|
|
646
|
+
| `.sidebar-section*`、`.sidebar-pane-view`、`.sidebar-pane-sash` | `.ldk-sidebar-section*`、`.ldk-sidebar-section-pane-view`、`.ldk-sidebar-section-pane-sash` |
|
|
647
|
+
| `.theme-picker*`、`.theme-card`、`.theme-preview` | `.ldk-theme-picker*`、`.ldk-theme-picker-card`、`.ldk-theme-picker-preview` |
|
|
648
|
+
| `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot`(主题卡片内部) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
|
|
649
|
+
| `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
|
|
650
|
+
|
|
651
|
+
- **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
|
|
652
|
+
- **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
|
|
653
|
+
- **什么时候必须改**:升到 **`@linkdesk/ui` 0.3.0** 时。`^0.2.0` 不会解析到 `0.3.0`(0.x 的范围就是这么算的),所以你不主动升级就不会坏。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
654
|
+
|
|
623
655
|
---
|
|
624
656
|
|
|
625
657
|
## 速查
|