@linkdesk/ui 0.2.47 → 0.2.48

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.
@@ -30,6 +30,19 @@ export interface InlineInputProps {
30
30
  /** 数字类型的 min/max */
31
31
  min?: number;
32
32
  max?: number;
33
+ /**
34
+ * 无障碍名(E13)——过滤框这类**没有可见 label** 的输入必须有 `aria-label`;缺省不挂该属性。
35
+ */
36
+ ariaLabel?: string;
37
+ /**
38
+ * 受控回灌:`value` 变化即重新播种本地值。缺省 `false` = **一次性种子**(rename 语义——编辑中
39
+ * 父组件的 `value` 是「已保存的名字」,不该覆盖用户正在打的字)。
40
+ *
41
+ * 🔴 搜索/过滤类用法置 `true`:`Esc` → `onCancel` 把父侧值清空后,输入框必须**真清空**
42
+ * (缺省语义下本地值不跟随 `value` ⇒ 界面残留已过滤的词、行却已回全量)。
43
+ * 置 true 的前提是父组件把 `onChange` 的值**回灌**到 `value`(照设置页搜索栏写法)。
44
+ */
45
+ syncValue?: boolean;
33
46
  }
34
47
  /** 暴露给父组件的 imperative handle——外部按钮读当前值 */
35
48
  export interface InlineInputHandle {
@@ -19,8 +19,18 @@ interface PluginCardProps {
19
19
  gearItems?: MenuItemDescriptor[];
20
20
  /** 插件停用:卡体降不透明度+「已停用」徽标。行与动作的惰性由管理器组装的 children 承担(03 §1)。 */
21
21
  disabled?: boolean;
22
+ /**
23
+ * 卡头与卡体之间的一行**通用工具条槽**(C5)——`PluginCard` 对它**零业务语义**:不认识过滤、
24
+ * 不认识排序,也不认识阈值(阈值/口径/行序全属组装方策略)。
25
+ *
26
+ * 🔴 槽是卡头那个**铺满整头的真按钮的兄弟**(卡头 `div` 的第二个孩子之后、卡体之前)——
27
+ * ⛔ 槽内控件(`<input>`/真件 SelectBox 的 `<button>` 触发)绝不许成为卡头按钮的子孙:
28
+ * HTML 不合法,且点击/打字会被卡头开合吞掉(嵌套按钮禁令,见本文件头注)。
29
+ * ⛔ 折叠态不渲染(不占位、不参与布局);不传槽的既有调用方**逐像素不变**(加性 API)。
30
+ */
31
+ toolbar?: ReactNode;
22
32
  /** 展开体(行清单)——管理器自组。 */
23
33
  children: ReactNode;
24
34
  }
25
- declare function PluginCard({ pluginId, manifest, title, version, summary, expanded, onToggle, gearItems, disabled, children, }: PluginCardProps): import("react").JSX.Element;
35
+ declare function PluginCard({ pluginId, manifest, title, version, summary, expanded, onToggle, gearItems, disabled, toolbar, children, }: PluginCardProps): import("react").JSX.Element;
26
36
  export default PluginCard;
@@ -10,7 +10,7 @@
10
10
  * · **类型**半边住 `@linkdesk/contracts`(`SettingsUiHint` / `SettingsRenderHint`)——那是
11
11
  * 生成产物、纯类型、零运行时,写不出 `export const`;壳仓定义点在
12
12
  * `src/core/api/linkdesk-api/types.ts`,随生成器进契约。
13
- * · **运行时值**半边 = 本件(哨兵两枚 + 名单两枚 + 类型守卫一枚)——`contracts` 给不了值。
13
+ * · **运行时值**半边 = 本件(哨兵两枚 + 名单三枚 + 类型守卫两枚)——`contracts` 给不了值。
14
14
  *
15
15
  * ── 🔴 本件纪律:纯 TS,零 React、零 DOM、零 @src/ 依赖 ──
16
16
  * 壳 core 会**反向 import** 本件(`services/ui/ThemeEngine/constants.ts` re-export 哨兵,
@@ -29,14 +29,39 @@ export declare const MIX_FOLLOW_THEME_SENTINEL = "followTheme";
29
29
  * 「设置控件-词表正典与共享化」01 §0.2)。
30
30
  * ⚠️ 加值/改值必须**同笔**动三处:`SettingsUiHint`(contracts)· 本数组 · 作者面 schema description
31
31
  * (轻门禁守同步);漏一处 = 门禁红。
32
- * ⚠️ `fileAssociationsManager`(第 4 波追加,13→14)**不是行内控件**:它声明在「默认打开方式」组的键上,
33
- * 表示该**整组**由设置插件渲染成「文件关联管理器」自定义视图(组内行无配置键)——渲染方是设置插件。
32
+ * ⚠️ `fileAssociationsManager`(第 4 波追加,13→14)**不是行内控件**:它声明在「默认打开方式」组的
33
+ * 挂载键上,表示该**整组**由设置插件渲染成「文件关联管理器」自定义视图(组内行无配置键)
34
+ * ——渲染方是设置插件;不认识它的渲染器**不画这一行**(隐藏位语义,见 `SETTINGS_HIDDEN_HINTS`)。
34
35
  */
35
36
  export declare const SETTINGS_UI_HINTS: readonly SettingsUiHint[];
36
37
  /** 渲染提示词表——3 枚(`renderHint` 的已知值)。
37
38
  * ⚠️ `"color"` 是阶段 1.1 全量对账补上的第 3 值(壳 `app.accentColor` / `app.glassTint` 已用),
38
39
  * 漏了它 = 壳侧收窄类型当场红。 */
39
40
  export declare const SETTINGS_RENDER_HINTS: readonly SettingsRenderHint[];
41
+ /**
42
+ * 「隐藏位」hint 名单——**挂在挂载键上**的那几枚,它们的语义不是「画一只控件」,而是
43
+ * 「**这个键自己没有行**:认识它的渲染器把该键所在的**整组**画成自定义视图;不认识的渲染器
44
+ * **整行不渲染**」(⛔ 不出「只读当前值」的垃圾行)。
45
+ *
46
+ * ── 为什么要这一条名单(C2b 定案,2026-10-06 用户拍板)──
47
+ * 挂载键的值常常是「没有用户语义的容器」(先例 `workbench.fileAssociations` 的 `{}`)。
48
+ * 未知 hint 的既有降级契约是**只读展示当前值 + title 说明**(防裸字符串写穿值域)——那条
49
+ * 对「有值的键」是对的,对**挂载键**只产出一行 `{}` 垃圾:没有信息量、还诱导用户以为它坏了。
50
+ * 故给这条契约开一个**具名例外**:正典认识的隐藏位 hint ⇒ 隐藏;**其余未知 hint 降级一字不动**。
51
+ *
52
+ * ── 消费方怎么用(两问,顺序别反)──
53
+ * ① `isSettingsHiddenHint(prop.uiHint)` 为真 ⇒ 该键**不渲染任何行**(自定义视图由实现该 hint
54
+ * 的渲染器挂,⛔ 不是这里的事);
55
+ * ② 否则走既有分流:`isSettingsUiHint` 假 ⇒ 未知 hint ⇒ 只读降级(老契约)。
56
+ * ⚠️ 隐藏位 hint 在 `SETTINGS_UI_HINTS` 里**仍然为真**(值是正典认识的)——故①必须先问。
57
+ *
58
+ * ── 维护纪律 ──
59
+ * · 名单是 `SETTINGS_UI_HINTS` 的**子集**(轻门禁 `check-settings-hint-canon` ③ 守);
60
+ * · 加一枚 = 正典表 + 本条 + 作者面 schema description(三处同笔,别只动一处);
61
+ * · 正典住共享层 ⇒ 第三方渲染器与官方设置插件读到**同一份**(判据 A:消费宿主声明的件。
62
+ * ⛔ 别在渲染方各写一遍名单)。
63
+ */
64
+ export declare const SETTINGS_HIDDEN_HINTS: readonly SettingsUiHint[];
40
65
  /**
41
66
  * 词表守卫——「声明的 uiHint 是不是正典认识的形态」。
42
67
  *
@@ -47,3 +72,12 @@ export declare const SETTINGS_RENDER_HINTS: readonly SettingsRenderHint[];
47
72
  * 正常路径(按 `type` 渲染,一字不动,见 02 E2)。本守卫只管「值在不在正典里」。
48
73
  */
49
74
  export declare function isSettingsUiHint(v: unknown): v is SettingsUiHint;
75
+ /**
76
+ * 隐藏位守卫——「这枚 uiHint 是不是**挂载位**」:为真 ⇒ 该配置键**一行都不画**(说明与消费顺序
77
+ * 见 `SETTINGS_HIDDEN_HINTS` 的文件内注释)。
78
+ *
79
+ * ⚠️ 与 `isSettingsUiHint` 的关系是**先问顺序**、不是互斥:隐藏位 hint 在正典里也为真
80
+ * (`isSettingsUiHint("fileAssociationsManager") === true`)。渲染器顺序:先本守卫(真 ⇒ 不画),
81
+ * 再 `isSettingsUiHint`(假 ⇒ 未知 hint 只读降级),最后按 `type` 渲染——⛔ 三支不许合并。
82
+ */
83
+ export declare function isSettingsHiddenHint(v: unknown): v is SettingsUiHint;
@@ -1,5 +1,5 @@
1
1
  {
2
- "shellVersion": "0.2.49",
3
- "commit": "802abc3e5",
4
- "cutAt": "2026-10-05"
2
+ "shellVersion": "0.2.52",
3
+ "commit": "1291ed570",
4
+ "cutAt": "2026-10-06"
5
5
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/ui",
3
- "version": "0.2.47",
3
+ "version": "0.2.48",
4
4
  "description": "@linkdesk/ui——LinkDesk 共享 UI 组件的类型契约 + dev 解析体。L9 集中供给:组件代码与样式在运行时由壳池 vendor 单实例供给(壳改一处全生态跟随);npm i 装的是类型与本地解析体,插件源码不 import 本包 css(lint 腿 check-ui-css-import 判红)。版本号自走(E6#166 对货不对号:2026-10-01 起与壳脱钩,壳发版只查作者面货不落后)。",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",