@linkdesk/plugin-docs 0.1.32 → 0.1.33

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.
@@ -560,10 +560,11 @@ both stylesheets land on the same element.
560
560
  | `ldk-drop-zone-in` | the drop zone's entrance animation |
561
561
  | `ldk-dropdown-card-in` | the dropdown card's entrance animation |
562
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
563
  | `ldk-notif-icon-spin` | the notification icon's spin |
566
564
  | `ldk-notif-progress-scan` | the notification progress scan |
565
+ | `ldk-rn-spin` | the release-notes page's refresh icon spin |
566
+ | `ldk-boot-mark-breath` | the boot brand screen's breathing |
567
+ | `ldk-view-skeleton-breath` | the content loading skeleton's breathing |
567
568
 
568
569
  **The name you reference has to exist somewhere**—rule 2 above says "when you rename, change the reference in
569
570
  the same commit"; this is the other half, and **the machine checks it**: the name you write in
@@ -762,6 +763,64 @@ button { border: none; }
762
763
 
763
764
  ---
764
765
 
766
+ ## 13. Hover Hints → the `data-hint` attributes (or `<HintTip>`)
767
+
768
+ **That little bar that appears when the pointer rests on your button/icon is not drawn by the browser.**
769
+
770
+ The host ships one unified light hint (`HintTip`): light/dark theme, UI scaling, edge flipping, and the
771
+ keycap look for shortcuts are all decided in one place by the shell. **You do not import anything** to use
772
+ it—write attributes:
773
+
774
+ ```tsx
775
+ // ❌ native title: drawn by the browser; theme/scaling/keycaps never follow the shell (red since SDK >= 0.1.49)
776
+ <button title={t("Refresh")}>
777
+
778
+ // ✅ attribute form: swap title= for data-hint= (zero DOM structure change)
779
+ <button data-hint={t("Refresh")} aria-label={t("Refresh")}>
780
+
781
+ // ✅ with a shortcut: give the command id and the shell looks it up (name + keys come from that one table,
782
+ // so the hint bar / context menu / command palette always say the same thing)
783
+ <button data-hint-command="fileTree.refresh" aria-label={t("Refresh")}>
784
+
785
+ // ✅ reveal kind ("see the whole truncated text"): it must appear at once, don't make it wait
786
+ <div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
787
+
788
+ // ✅ composite cases (you want to control the wrapper): the component form
789
+ import { HintTip } from "@linkdesk/ui";
790
+ <HintTip label={t("Refresh")} command="fileTree.refresh"><button …>…</button></HintTip>
791
+ ```
792
+
793
+ Four attributes, all written on your own DOM elements:
794
+
795
+ | Attribute | What it does |
796
+ |---|---|
797
+ | `data-hint` | The hint text (explain and reveal kinds share it—**the text is always yours**; the shell never ships sentences) |
798
+ | `data-hint-command` | Command id—the shell reads name and shortcut from the command table. **Same source** as the context menu / command palette (change it once, everything follows) |
799
+ | `data-hint-delay` | Intent delay in ms. Explain kind: **leave the default** (120 ms—prevents a flash while sweeping past); reveal kind: pass `"0"` |
800
+ | `data-hint-placement` | Preferred side: `top`/`bottom`/`left`/`right` (default `top`; flips automatically when it does not fit) |
801
+
802
+ **⚠️ Three rules**
803
+
804
+ 1. **Explain kind waits, reveal kind does not**—"see the whole truncated text" must be immediate; a command
805
+ explanation for an icon is exactly the case that should pause a moment.
806
+ 2. **No more native `title=`**: the SDK leg `linkdesk/no-native-title` (SDK >= 0.1.49) marks it red—`lint`
807
+ prints a red row and `ci-verify` fails. For the rare form where the hint renderer cannot reach (the
808
+ legitimate exception), write `// eslint-disable-next-line linkdesk/no-native-title -- reason` (a **reason
809
+ is mandatory**).
810
+ 3. **No buttons inside the bar**: a hint is a hint, not a menu (use `<ContextMenu>` for interaction); for a
811
+ **long text / title / footnote** or multi-line explanation use `HintCard`—that component is the one that
812
+ owns "long explanations with a footnote".
813
+
814
+ > 🔧 **Maintainer note (authors may skip)**: renderer = `src/components/shared/hint-tip/HintTipRenderer.tsx`
815
+ > (a single mount in the pool: delegated `pointerover`/`pointerout`/`focusin`/`focusout` plus an intent-delay
816
+ > state machine); the single source of truth for the attribute literals is `hintAttrs.ts` (⛔ never write a
817
+ > `"data-hint"` literal anywhere else); the master switch is the shell config `app.hint.enabled` (default on,
818
+ > visible in settings); the gates are three legs — shell-side `scripts/check-native-title.mjs` (legacy
819
+ > white-list ledger, new sites only) and the SDK leg `checks/no-native-title.ts` (same id, pinned to each
820
+ > other by the three 锚⑪ anchor sentences).
821
+
822
+ ---
823
+
765
824
  ## Quick Reference
766
825
 
767
826
  | What you want to do | Core facility | How to bring it in |
@@ -775,6 +834,7 @@ button { border: none; }
775
834
  | Rich-content confirm | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | the in-pool DialogHost renders the shell, **the content = a plugin-drawn view** (see §9) |
776
835
  | Shortcuts (non-text keys) | `plugin.json contributes.keybindings` | — (putting text keys here = swallowing the whole pool, see §4.1) |
777
836
  | Shortcuts (text keys / focus-bound keys) | container `onKeyDown` + `tabIndex` | pool-side self-handling, see §4.2 (document/window keydown is forbidden) |
837
+ | Hover hints | `data-hint` / `data-hint-command` / `data-hint-delay` attributes (or `<HintTip>`) | just write them on your own DOM elements — **no import needed** (see §13; a native `title=` is red) |
778
838
  | Colors | CSS variables | `var(--xxx)`, list in `src/index.css` |
779
839
  | Font sizes | CSS variables | `var(--font-size-*)` + `--ui-scale`, bare px forbidden (gate, see §10) |
780
840
  | Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
@@ -99,10 +99,10 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
99
99
  |:--|:--|:--|
100
100
  | Host command prefix | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | Your command id lands in the host's own segment — in the command palette and the keybindings page it looks like a host feature |
101
101
  | Host protocol id | `bracket` | Same name as the host's bracket-matching protocol handler ⇒ one of the two never runs, with no error |
102
- | Host pseudo plugin id | `app`、`appearance`、`update` | The host registers as a "plugin" too (shell core / appearance / updater) ⇒ these ids read as the host itself |
102
+ | Host pseudo plugin id | `app`、`appearance` | The host registers as a "plugin" too (shell core / appearance; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself |
103
103
  | Host config key | `app.schemaVersion` | The config **internal version marker** (invisible in the settings UI, never registered) — taking it derails migration bookkeeping and the user's data looks lost |
104
104
  | Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
105
- | Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` | Light/dark mode, accent colour, menu style |
105
+ | Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | Light/dark mode, accent colour, menu style, hover hints |
106
106
  | Host config key | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | Background and per-zone backgrounds |
107
107
  | Host config key | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | The four glass parameters |
108
108
  | Host config key | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | Corner radii |
@@ -84,6 +84,7 @@ The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you ins
84
84
  | `ContextMenu` | Context menu component | Works with `contributes.menus` — see [05-UI Conventions](05-ui-conventions.md) |
85
85
  | `InlineInput` | Inline input (imperative handle) | Renaming in place in a tree/list (grab the `ref` and call `InlineInputHandle`) |
86
86
  | `OverlayPortal` | Overlay portal host | Use it when a custom-drawn dialog needs to portal to body; don't scatter bare `createPortal` calls everywhere |
87
+ | `HintTip` | Lightweight hover hint (component form) | For "give it a child element and one sentence" — **most cases just write the `data-hint` attribute, no import needed**; use this component when you want to control the wrapper yourself (see [05-UI Conventions](05-ui-conventions.md) §13; a native `title=` is red) |
87
88
  | `HintCard` | Anchored hover hint card (non-interactive) | For "hover a small badge, see a short explanation card": give `lines` (1–3 sentences) and the anchor element; triggering/positioning/glass are all handled by the shell; ⛔ no links or buttons inside the card |
88
89
 
89
90
  > 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**.
@@ -559,10 +559,11 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
559
559
  | `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
560
560
  | `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
561
561
  | `ldk-floating-panel-in` | 浮动面板的入场动画 |
562
- | `ldk-group-tab-enter` | 分组标签的入场动画 |
563
- | `ldk-group-tab-exit` | 分组标签的退场动画 |
564
562
  | `ldk-notif-icon-spin` | 通知图标的旋转 |
565
563
  | `ldk-notif-progress-scan` | 通知的进度扫描 |
564
+ | `ldk-rn-spin` | 发行说明页刷新图标的旋转 |
565
+ | `ldk-boot-mark-breath` | 池首帧品牌过场的呼吸 |
566
+ | `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
566
567
 
567
568
  **引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
568
569
  你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
@@ -769,6 +770,57 @@ button { border: none; }
769
770
 
770
771
  ---
771
772
 
773
+ ## 13. 悬停提示 → `data-hint` 属性(或 `<HintTip>`)
774
+
775
+ **鼠标停在你的按钮/图标上时,那个小条不是浏览器画的。**
776
+
777
+ 宿主有一套统一的轻提示(`HintTip`):深浅主题、字号缩放、贴边翻面、快捷键键帽都由壳一处决定。
778
+ **你不需要 import 任何东西**就能用——写属性即可:
779
+
780
+ ```tsx
781
+ // ❌ 原生 title:浏览器画,主题/缩放/键帽都不跟壳走(SDK ≥ 0.1.49 起这条腿判红)
782
+ <button title={t("刷新")}>
783
+
784
+ // ✅ 属性式:把 title= 换成 data-hint=(DOM 结构零变化)
785
+ <button data-hint={t("刷新")} aria-label={t("刷新")}>
786
+
787
+ // ✅ 带快捷键:给命令 id,壳去查命令表(文案与快捷键都来自那一份 ⇒ 提示条/右键菜单/命令面板永远一个说法)
788
+ <button data-hint-command="fileTree.refresh" aria-label={t("刷新")}>
789
+
790
+ // ✅ 揭示类("看全被截断的字"):该立刻出现,别让它等
791
+ <div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
792
+
793
+ // ✅ 复合场景(要自己控制包裹):组件式
794
+ import { HintTip } from "@linkdesk/ui";
795
+ <HintTip label={t("刷新")} command="fileTree.refresh"><button …>…</button></HintTip>
796
+ ```
797
+
798
+ 四个属性,都写在你自己的 DOM 元素上:
799
+
800
+ | 属性 | 作用 |
801
+ |---|---|
802
+ | `data-hint` | 提示主文案(说明类与揭示类通用——**文案永远由你给**,壳不下发任何句子) |
803
+ | `data-hint-command` | 命令 id——壳查命令表取名字与快捷键。与右键菜单/命令面板**同源**(改一处全跟走) |
804
+ | `data-hint-delay` | 意图延时(毫秒)。说明类**留默认**(120ms——防划过闪一下);揭示类传 `"0"` |
805
+ | `data-hint-placement` | 首选方位 `top`/`bottom`/`left`/`right`(缺省 `top`,贴不下自动翻面) |
806
+
807
+ **⚠️ 三条纪律**
808
+
809
+ 1. **说明类慢、揭示类近 0**——「看全被截断的字」要立刻;反过来给图标加命令说明才该等那一等。
810
+ 2. **别再用原生 `title=`**:SDK 腿 `linkdesk/no-native-title`(SDK ≥ 0.1.49)判红——`lint` 输出红行、
811
+ `ci-verify` 判红。确需原生 title 的形态(提示渲染器够不到的)走
812
+ `// eslint-disable-next-line linkdesk/no-native-title -- 理由`(**理由必填**)。
813
+ 3. **条内不放按钮**:提示是提示不是菜单(要交互用 `<ContextMenu>`);要**长文案/标题/注脚**或多行说明,
814
+ 用 `HintCard`——那一件本来就是管"有注脚的长说明"的。
815
+
816
+ > 🔧 **维护者注(作者可跳过)**:渲染器 = `src/components/shared/hint-tip/HintTipRenderer.tsx`(池内单例挂载:
817
+ > 委托 `pointerover`/`pointerout`/`focusin`/`focusout` + 意图延时状态机);属性字面量的单一真相源 =
818
+ > `hintAttrs.ts`(⛔ 别处不许再写 `"data-hint"` 字面量);总开关 = 壳配置 `app.hint.enabled`(缺省开,设置页可见);
819
+ > 门禁三腿 = 壳侧 `scripts/check-native-title.mjs`(存量白名单账、只判新增)+ SDK 腿
820
+ > `checks/no-native-title.ts`(同 id、锚⑪ 3 句锚词互钉)。
821
+
822
+ ---
823
+
772
824
  ## 速查
773
825
 
774
826
  | 你要做的 | 核心设施 | 引入方式 |
@@ -782,6 +834,8 @@ button { border: none; }
782
834
  | 富内容确认框 | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | 池内 DialogHost 渲染壳,**内容 = 插件自绘视图**(见 §9) |
783
835
  | 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
784
836
  | 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
837
+ | 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
838
+ | 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
785
839
  | 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
786
840
  | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
787
841
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
@@ -101,10 +101,10 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
101
101
  |:--|:--|:--|
102
102
  | 宿主命令前缀 | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | 你的命令 id 落进宿主自己的段——命令面板、快捷键设置页里它看起来像宿主的功能 |
103
103
  | 宿主协议 id | `bracket` | 与宿主的括号匹配协议处理器同名 ⇒ 有一方不生效(不报错) |
104
- | 宿主伪 pluginId | `app`、`appearance`、`update` | 宿主自己也以「插件」身份注册(壳通用 / 外观 / 更新)⇒ 用这些 id 会被当成宿主自己 |
104
+ | 宿主伪 pluginId | `app`、`appearance` | 宿主自己也以「插件」身份注册(壳通用 / 外观;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己 |
105
105
  | 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
106
106
  | 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
107
- | 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` | 亮暗模式、强调色、菜单样式 |
107
+ | 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | 亮暗模式、强调色、菜单样式、悬停提示 |
108
108
  | 宿主配置键 | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | 背景与区域背景 |
109
109
  | 宿主配置键 | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | 玻璃材质四参 |
110
110
  | 宿主配置键 | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | 圆角 |
@@ -85,6 +85,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
85
85
  | `ContextMenu` | 右键菜单组件 | 配合 `contributes.menus` —— 见 [05-插件UI写法规约](05-插件UI写法规约.md) |
86
86
  | `InlineInput` | 行内输入(命令式句柄) | 树/列表里就地改名(拿 `ref` 调 `InlineInputHandle`) |
87
87
  | `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
88
+ | `HintTip` | 轻量悬停提示(组件式) | 「给它一个子元素、一句话」——**多数场景直接写 `data-hint` 属性即可,不必 import**;要自己控制包裹时用这个组件(见 [05-插件UI写法规约](05-插件UI写法规约.md) §13;原生 `title=` 判红) |
88
89
  | `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
89
90
 
90
91
  > 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.32",
3
+ "version": "0.1.33",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [