@linkdesk/ui 0.2.36 → 0.2.37

package/dist/readonly-text/ReadOnlyText.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 只读文本展示件（M4 `AI#38.12` · P-2 拍板 A）——**通用原语**，与 Toggle/SelectBox 同层级
+ * （`@linkdesk/ui` 单实例供给，任何插件可 import）。
+ *
+ * 用途一（原有）：设置页 `renderHint: "readonly"` 的状态行 · 多行只读明细（如 AI 接入的开放范围）。
+ * 用途二（本案 3.2 升级）：**状态行值活起来**——声明 `statusCommand` 即进入轮询模式，
+ * 值来自运行时命令而不是静态 prop（原设置插件本地件 `ReadOnlyStatus` 整件退场，行为上移到这里）。
+ *
+ * 🔴 就是文字——不做可点、不做悬停花活（用户拍板「控件形态尽量基础」）。升级只加"值从哪来"，
+ * 不加任何交互面。
+ *
+ * 值来源优先级：`statusCommand` 存在 ⇒ **轮询值优先**（`value` 被取代；未读到之前不渲染，
+ * 不拿静态值冒充实时读数）；否则用 `value`。（执行句柄 `runCommand` 由使用方注入——
+ * 共享件不引宿主内核。）
+ */
+import { type RunStatusCommand } from "./useStatusPolling";
+interface ReadOnlyTextProps {
+    /** 展示文本（多行用 \n 分隔）；声明 `statusCommand` 时被轮询值取代 */
+    value?: string;
+    /** true = 多行块（明细清单；pre-wrap 保留换行）；缺省 = 单行（状态值，等宽字体） */
+    multiline?: boolean;
+    /** 轮询的命令 id——存在即进入轮询模式（值来自命令，不来自配置存储/静态 prop） */
+    statusCommand?: string;
+    /** 命令执行句柄（使用方注入，如 `window.linkdesk.commands.executeCommand`） */
+    runCommand?: RunStatusCommand;
+    /** 轮询间隔（毫秒），缺省 3000；仅 `statusCommand` 存在时生效 */
+    intervalMs?: number;
+}
+declare function ReadOnlyText({ value, multiline, statusCommand, runCommand, intervalMs }: ReadOnlyTextProps): import("react").JSX.Element | null;
+export default ReadOnlyText;

package/dist/readonly-text/useStatusPolling.d.ts

@@ -0,0 +1,10 @@
+/** 命令执行句柄——返回状态字符串；`null` / 非字符串一律按「没读到」处理（保持现值）。 */
+export type RunStatusCommand = (commandId: string) => Promise<string | null>;
+/**
+ * 轮询 `statusCommand` 指向的壳命令，返回最近一次读数。
+ *
+ * @param statusCommand 命令 id；缺省/空 ⇒ 不轮询（返回 null，一条定时器都不建）
+ * @param runCommand    命令执行句柄（使用方注入）
+ * @param intervalMs    轮询间隔，缺省 3000（仅 `statusCommand` 存在时生效）
+ */
+export declare function useStatusPolling(statusCommand: string | undefined, runCommand: RunStatusCommand | undefined, intervalMs?: number): string | null;

package/dist/section-subtitle/SectionSubtitle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 分节副标题件（M4 `AI#38.12` · P-3 拍板 A）——**通用原语**（`@linkdesk/ui`，任何插件可 import）。
+ *
+ * 用途：分区大标题 / 分节小标题（`group`）下面的一行说明小字——设置页从
+ * configuration contribution 的 `subtitle` / `groupDescriptions` 读到即渲染（零侵入：
+ * 未声明 = 不渲染）。🔴 就是文字（不做可点，用户拍板「控件形态尽量基础」）。
+ */
+import type { ReactNode } from "react";
+interface SectionSubtitleProps {
+    children: ReactNode;
+}
+declare function SectionSubtitle({ children }: SectionSubtitleProps): import("react").JSX.Element | null;
+export default SectionSubtitle;

package/dist/segment-preview/SegmentPreview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 分段控件段内预览两原子——文字极性（Aa 样本）＋强调色来源（色块）。
+ * E6#87d 自设置仓 `toneControls.tsx` 的 FontTonePreview 抽出（判据 A：只搬预览原子，
+ * 两个 handler 留设置仓变薄绑定）。纯展示、零宿主耦合、零语义——「哪个 hint 值显示哪种
+ * 极性/色块」的映射住消费方。
+ *
+ * 几何＝单一 swatch（52×30 ＋ var(--radius-sm)），两原子共用（设置页原归一化结论 #3）。
+ * 颜色全走 CSS 变量（硬约束 1）：极性取样壳 `--tone-*` 实色标尺；自定义强调色读 `--accent`
+ * （applyAccentColor 恒写 effective accent——三态全对，声明式读，零 IPC 零 DOM 读）。
+ */
+/** `Aa` 分半/单半样本——halves 为极性名单（"deep" | "light"），消费方按 hint 值给 */
+export declare function SegmentPreviewText({ halves }: {
+    halves: readonly string[];
+}): import("react").JSX.Element;
+/** 色块样本——split = 中性分半（「主题决定强调色」示意）；accent = 实时生效强调色 */
+export declare function SegmentPreviewSwatch({ variant }: {
+    variant: "split" | "accent";
+}): import("react").JSX.Element;

package/dist/settings-hints/settingsHints.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 设置控件词表**正典**（运行时值半边）——「设置控件-词表正典与共享化」判据 B 的落地物。
+ *
+ * ── 为什么住这一层 ──
+ * `uiHint` / `renderHint` 是**宿主声明 ↔ 渲染层**之间的词表。声明的消费方（壳共享控件、
+ * 设置插件、第三方设置插件）都要读到**同一份**名单 ⇒ 正典住 `@linkdesk/ui`
+ * （判据 A：消费宿主声明的件，必须住在任何声明者与渲染者都取得到的层）。
+ *
+ * ── 与 contracts 的分工（一案两半，⛔ 别复制第三份）──
+ * · **类型**半边住 `@linkdesk/contracts`（`SettingsUiHint` / `SettingsRenderHint`）——那是
+ *   生成产物、纯类型、零运行时，写不出 `export const`；壳仓定义点在
+ *   `src/core/api/linkdesk-api/types.ts`，随生成器进契约。
+ * · **运行时值**半边 = 本件（哨兵两枚 ＋ 名单两枚 ＋ 类型守卫一枚）——`contracts` 给不了值。
+ *
+ * ── 🔴 本件纪律：纯 TS，零 React、零 DOM、零 @src/ 依赖 ──
+ * 壳 core 会**反向 import** 本件（`services/ui/ThemeEngine/constants.ts` re-export 哨兵，
+ * 保住插件与老调用方的既有 import 路径；见 02 E4b）。带进任何组件/DOM/宿主耦合，
+ * 都会把核心的依赖图污染——共享层唯一的「core ← shared」边只许是这一条，且只许是纯值。
+ */
+import type { SettingsRenderHint, SettingsUiHint } from "@linkdesk/contracts";
+/** 显式「无」哨兵——配置值字面量契约：`__none__` = **绝对无**（背景图无图 / 字体族落系统栈），
+ *  与「空串 = 跟随主题」区分两语义（E5.8#87/#158）。跨边界契约：壳 core、共享控件、任何设置插件同读这一份。 */
+export declare const CONFIG_NONE_SENTINEL = "__none__";
+/** 混搭来源「跟随主题」哨兵——外观域 mix 来源键的缺省/播种值，也是来源徽标判定里
+ *  「域来源未生效」的那一支（`deriveSourceBadge`）。同族跨边界字符串契约，与
+ *  `CONFIG_NONE_SENTINEL` 一处一个正典（⛔ 不新开第二个「哨兵件」）。 */
+export declare const MIX_FOLLOW_THEME_SENTINEL = "followTheme";
+/** 声明式控件词表——13 枚，与 `SettingsUiHint` 联合类型一一对应（正典表本体见
+ *  「设置控件-词表正典与共享化」01 §0.2）。
+ *  ⚠️ 加值/改值必须**同笔**动三处：`SettingsUiHint`（contracts）· 本数组 · 作者面 schema description
+ *  （轻门禁守同步）；漏一处 = 门禁红。 */
+export declare const SETTINGS_UI_HINTS: readonly SettingsUiHint[];
+/** 渲染提示词表——3 枚（`renderHint` 的已知值）。
+ *  ⚠️ `"color"` 是阶段 1.1 全量对账补上的第 3 值（壳 `app.accentColor` / `app.glassTint` 已用），
+ *  漏了它 = 壳侧收窄类型当场红。 */
+export declare const SETTINGS_RENDER_HINTS: readonly SettingsRenderHint[];
+/**
+ * 词表守卫——「声明的 uiHint 是不是正典认识的形态」。
+ *
+ * 渲染层降级契约据此分流：**不认识 ⇒ 只读展示当前值 ＋ title 说明**（⛔ 不再落进可编辑文本框，
+ * 防裸字符串写穿值域——`app.backgroundImage` 露 `__none__` 那类）。
+ *
+ * ⚠️ **「没声明」≠「未知」**：`undefined` / `""` 也要先由调用方判成「未声明」，那是大多数键的
+ * 正常路径（按 `type` 渲染，一字不动，见 02 E2）。本守卫只管「值在不在正典里」。
+ */
+export declare function isSettingsUiHint(v: unknown): v is SettingsUiHint;

package/dist/shell-provenance.json

@@ -1,5 +1,5 @@
 {
-  "shellVersion": "0.2.36",
-  "commit": "4beb9c281",
+  "shellVersion": "0.2.38",
+  "commit": "56311cead",
   "cutAt": "2026-10-03"
 }

package/dist/source-badge/SourceBadge.d.ts

@@ -0,0 +1,12 @@
+/** 来源域——宿主的读数语义（含默认态 `theme`）；⛔ 与 `EffectiveBadge` 的「生效值」不是一回事 */
+export type SourceBadgeSource = "theme" | "user" | "mix";
+/** 可显徽标的来源（降噪：`theme` 不显） */
+export type SourceBadgeKind = Exclude<SourceBadgeSource, "theme">;
+export interface SourceBadgeProps {
+    /** 来源种类（可显示的两种；`theme` 由调用方自行不渲染） */
+    source: SourceBadgeKind;
+    /** 徽标文案（调用方 `t()` 已译，如「来源：用户覆盖」）——同时用作悬停提示 */
+    label: string;
+}
+declare function SourceBadge({ source, label }: SourceBadgeProps): import("react").JSX.Element;
+export default SourceBadge;

package/dist/string-list-editor/splitStringList.d.ts

@@ -0,0 +1,21 @@
+/**
+ * stringList 控件的前置计算——「锁定行 / 可编辑行」切分（纯函数，零 React 零宿主耦合）。
+ * E6#87d 自设置仓 `renderControl/stringList.ts` 平移（判据 A：消费宿主 `uiHint:"stringList"`
+ * 声明的计算住共享层，任何声明者与渲染者都取得到）。
+ *
+ * E6#30c：default 数组 = locked 固定行（官方源「内置」徽标 + 锁——不可删、不入 onChange 值、
+ * 永不落盘，读时由消费方恒前置去重）；effective 值（含 default）减 locked 后 = 作者源（可删）。
+ * 身份规则（E6#30c）：相减与行内判重用同一把钥匙 urlSourceKey——github 源归 owner/repo、分支
+ * 无关；官方源的「其他形态」（仓库主页/HEAD 直链）在此一并滤除。urlSourceKey 非 github 输入
+ * 返 null → 回精确比较。本函数对任何 uiHint:"stringList" 配置通用，零插件域依赖。
+ *
+ * 入参只读 `prop.default` 一个字段 ⇒ 形参收窄为结构类型 `{ default?: unknown }`，
+ * 消费方 ConfigProperty 直接传得进（LSP 兼容），共享层不引插件类型。
+ */
+/** 锁定行（default 声明）+ 可编辑行（effective 值滤掉锁定身份后的剩余） */
+export declare function splitStringList(prop: {
+    default?: unknown;
+}, value: unknown): {
+    locked: string[];
+    editable: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkdesk/ui",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "@linkdesk/ui——LinkDesk 共享 UI 组件的类型契约 + dev 解析体。L9 集中供给：组件代码与样式在运行时由壳池 vendor 单实例供给（壳改一处全生态跟随）；npm i 装的是类型与本地解析体，插件源码不 import 本包 css（lint 腿 check-ui-css-import 判红）。版本号自走（E6#166 对货不对号：2026-10-01 起与壳脱钩，壳发版只查作者面货不落后）。",
   "type": "module",
   "main": "./dist/index.js",