@linkdesk/ui 0.2.35 → 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.33",
-  "commit": "d0a8c66cf",
-  "cutAt": "2026-10-01"
+  "shellVersion": "0.2.38",
+  "commit": "56311cead",
+  "cutAt": "2026-10-03"
 }

package/dist/slider/Slider.d.ts

@@ -6,17 +6,36 @@
  * 无障碍（原生 range = role="slider" + aria-valuemin/max/now），不手写 pointer 拖拽状态机（B 类 bug 高发区）。
  * 填充 = inline `--slider-pct` CSS 变量 → linear-gradient（mockup fill 语义，见 Slider.css）。
  * prefers-reduced-motion：原生 range 无动画，天然满足（无 transition 可禁）。
+ *
+ * 能力扩展（2026-10-03，docs/04-软件更新/待抉择池/滑杆件-Slider能力扩展）——
+ * 「值标签」与「细调步进」自设置仓包裹层下沉进组件（D3：组件自带能力，声明即显、不声明即无）：
+ * - unit / unitPosition：值标签（当前值＋单位一体，D1）。⚠️ 空串 ≠ 未声明——未声明 = 不渲染标签
+ *   （裸滑杆）；"" = 有标签无单位（如设置页不透明度的 0.5）。方位 D5：before/after 贴「按钮对」外侧，
+ *   above/below 脱离行内流居中压轨道中线（配置键一律用缺省 after——上下方位撑破固定行高）。
+ * - stepper：轨道两侧常驻 −/＋（D2，单击单发、长按连发不做）；按 step 步进、min/max 夹取、
+ *   触边置灰、disabled 联动；步进按 step 小数位收敛浮点误差（E7）。按钮可聚焦（E5——
+ *   ⛔ 不做「不可聚焦」的偷懒解法），键盘全链 = Tab − → 轨道 → ＋。
+ * 结构（E13）：声明了任一能力时根节点 = .ldk-slider-root 网格盒；两者都不声明 = 返回裸 input
+ * （与历史 DOM 逐字节一致，第三方零感知）。.ldk-slider 类名仍留在 input 上（后代选择器兼容）；
+ * style prop 仍落在 input 上（不改既有 API 语义）。
  */
+type UnitPosition = "before" | "after" | "above" | "below";
 interface SliderProps {
     value: number;
     onChange: (v: number) => void;
     min?: number;
     max?: number;
     step?: number;
-    /** 无障碍标签（设置行 label 由 SettingRow 显示，此处供读屏） */
+    /** 单位文案（px / ms / × / 毫米…由声明者自定）——声明了才有值标签；空串 = 有标签无单位 */
+    unit?: string;
+    /** 值标签方位（缺省 after）；above/below 只留插件自绘场景（撑破固定行高） */
+    unitPosition?: UnitPosition;
+    /** 轨道两侧 −/＋ 细调按钮（常驻，单击单发）；不声明 = 一个 DOM 都不多 */
+    stepper?: boolean;
+    /** 无障碍标签（设置行 label 由 SettingRow 显示，此处供读屏；stepper 按钮连带「减少/增加」＋此标签） */
     ariaLabel?: string;
     disabled?: boolean;
     style?: React.CSSProperties;
 }
-declare function Slider({ value, onChange, min, max, step, ariaLabel, disabled, style }: SliderProps): import("react").JSX.Element;
+declare function Slider({ value, onChange, min, max, step, unit, unitPosition, stepper, ariaLabel, disabled, style, }: SliderProps): import("react").JSX.Element;
 export default Slider;

package/dist/slider/sliderValueLabel.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 滑杆值标签格式化——E5.8#77 数值显示。
+ * 纯函数零依赖：unit "×" → 倍数前缀 + 1 位小数（mockup ×1.0）；"px" → 数值 + 后缀；
+ * 空 → 裸数值（0-1 不透明度 0.45）。
+ * 滑杆件能力扩展（2026-10-03）：自设置仓迁入组件本体（能力搬家，非复制）——
+ * 设置仓那份已删除，组件值标签统一走这里（⛔ 不造第二套格式化器）。
+ */
+/**
+ * 把滑杆当前值格式化为带单位标签。
+ * - 非有限值（val 解析失败）→ 空串（防御）。
+ * - "×"：前置 + toFixed(1)（×1.0 / ×1.5，mockup 倍数语义）。
+ * - 其余单位：数值规整（去尾零）+ 单位后缀（16px / 0.5px）。
+ * - 空单位：裸数值（0.45 / 1——不透明度直接显示）。
+ */
+export declare function formatSliderValue(v: number, unit?: string): string;

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.35",
+  "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",