dsh-plugin-update 0.2.0 → 0.3.0

package/dist/panel-batch.d.ts

@@ -0,0 +1,151 @@
+import { type UpdatePanelTheme } from './panel.js';
+/** 一行要画的东西（宿主回包里的形状）。 */
+export interface BatchRowView {
+    key: string;
+    title: string;
+    /** 会话相位：pending/checking/ready/installing/current/done/failed/skipped（认不出按 pending）。 */
+    phase: string;
+    targetVersion: string | null;
+    restartRequired: boolean;
+    error: string | null;
+    /** 该行的单插件快照（展开详情与「安装这家」按钮的门控都用它）。 */
+    snapshot: unknown;
+    manual?: string | null;
+    queue?: unknown;
+    profileName?: string | null;
+    /** 该行的插件标识（跳过存储与诊断文本用；缺省用 key）。宿主侧后补字段，缺了照样跑。 */
+    pluginId?: string | null;
+    /** 该行的诊断详情（宿主给就带上；没有就不带）。 */
+    diag?: unknown;
+    /** 宿主种类（进诊断文本；缺省说人话）。 */
+    hostKind?: string | null;
+    /** 该家单插件三电话的名字（取消排队要用它自己的安装电话；老宿主不给就不给取消入口）。 */
+    phoneNames?: unknown;
+}
+/** 摆放形态：默认内嵌，切弹窗走同一参数（与单插件面板同一套写法）。 */
+export type BatchPanelMode = 'embedded' | 'dialog';
+/** 批量面板的挂载参数。 */
+export interface BatchPanelOptions {
+    /** 批量电话前缀（与宿主一致）。 */
+    prefix: string;
+    /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
+    call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    /** 主题：与单插件面板同一套（缺省 default）。 */
+    theme?: UpdatePanelTheme;
+    /** 摆放形态：内嵌或弹窗（缺省 embedded）。 */
+    mode?: BatchPanelMode;
+    /** 轮询间隔（毫秒，缺省 1500，下限 250）。 */
+    pollMs?: number;
+    /** 可选：键 -> 中文名覆盖。 */
+    titles?: Record<string, string>;
+    /**
+     * 「重启宿主」的落地（与单插件面板同一口径）：不传就只提示手动重启，不假装能重启。
+     */
+    onRestartRequested?: () => void | Promise<void>;
+    /** 复制文本的出口（与单插件面板同一口径）：不传即试浏览器剪贴板，都没有也不抛错。 */
+    copyText?: (text: string) => void | Promise<void>;
+}
+/** 面板可点的动作（HTML 上 data-act 一一对应；测试走同一条路）。 */
+export type BatchPanelActionKind = 'check' | 'install' | 'resume' | 'cancel' | 'row-install' | 'row-skip' | 'row-resume-skip' | 'row-cancel-queue' | 'row-copy-manual' | 'row-copy-diag' | 'toggle-details' | 'restart' | 'close';
+/** 挂载点：只要有 innerHTML 的容器即可（浏览器元素或测试替身都行）。 */
+export interface BatchPanelContainer {
+    innerHTML: string;
+    addEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+}
+/** 批量面板控制器（与契约桩同名同义；act 多收一个可选 key，供行内动作指认某一家）。 */
+export interface BatchPanelController {
+    refresh(): Promise<void>;
+    act(action: BatchPanelActionKind, key?: string): Promise<void>;
+    setTheme(theme: UpdatePanelTheme): void;
+    setMode(mode: BatchPanelMode): void;
+    unmount(): void;
+}
+/** 批量五个电话名（与宿主侧 MultiHostUpdate.phoneNames 同一形状）。 */
+export interface BatchPhoneNames {
+    status: string;
+    check: string;
+    install: string;
+    resume: string;
+    cancel: string;
+}
+/** 批量面板轮询口径（默认 1.5 秒、下限 250 毫秒，与单插件面板同一套下限）。 */
+export declare const BATCH_PANEL_POLL: {
+    readonly defaultMs: 1500;
+    readonly minMs: 250;
+};
+/** 批量电话名拼法：前缀 + 五个固定动作名（前缀形状校验与单插件面板同一套）。 */
+export declare function buildBatchPhoneNames(prefix: string): BatchPhoneNames;
+export interface BatchLedgerCounts {
+    /** phase=ready：有新版、还没安装。 */
+    updatable: number;
+    /** phase=installing：正在安装。 */
+    installing: number;
+    /** phase=pending/checking：还没轮到/正在查。 */
+    pending: number;
+    /** 安装好了但要重启宿主才生效（终态之外的一档，单独数）。 */
+    restart: number;
+    /** phase=failed。 */
+    failed: number;
+    /** phase=skipped。 */
+    skipped: number;
+    /** phase=current/done 且不用重启：真的没事了。 */
+    settled: number;
+}
+/**
+ * 从行上数分类账（每行恰好进一档，七档之和 === 行数）：
+ * 失败优先（失败行永远算失败，不算待重启）；其余按相位落档；不用重启的终态才算「已最新」。
+ * 例外一处：「忙失败占位」（phase=failed 但 error=update-busy）其实是**排队**不是失败——
+ * 宿主忙时先写占位再回 update-busy，面板把它翻回「可更新」，免得总账把它报成失败。
+ */
+export declare function batchLedgerCounts(rows: readonly BatchRowView[]): BatchLedgerCounts;
+/** 分类计数 → 一句话总账（只出现非零档，顺序固定：可更新 · 安装中 · 待查 · 待重启 · 失败 · 已跳过 · 已最新）。 */
+export declare function batchLedgerText(counts: BatchLedgerCounts): string;
+/**
+ * 排队中的状态词：只回答「还要等多久」。位置从该行的队列视图来。
+ * queue.ts 的 position 是 waiting 顺位（队首为 1、0 = 自己正在装），而正在装的那一家也压在这一家前面，
+ * 所以「前方 N 个」= position N（队首那家前方正好 1 个：正在装的拥有者）。
+ * 位置取不到（宿主只记了忙、没给占位读数）就说「等前面安装完」，不猜数字。
+ */
+export declare function batchQueuedStatus(position: number | null): string;
+/**
+ * 一行的状态词：只回答一个问题——这家的**下一步**是什么。
+ * 中文可执行，不写相位英文（相位只留在 data-phase 属性上，给人看的这句永远是动作）。
+ */
+export declare function batchRowStatus(row: BatchRowView, skippedVersion?: string | null): string;
+export interface BatchPanelRenderInput {
+    rows?: readonly BatchRowView[];
+    theme?: UpdatePanelTheme;
+    mode?: BatchPanelMode;
+    /** 当前展开的那一家（键）；null 即全部收起。 */
+    expandedKey?: string | null;
+    /** 批量电话本身失败的稳定码（ok:false 或抛错）。 */
+    lastError?: string | null;
+    /** 本地提示（重启入口、取消结果之类）。 */
+    notice?: string | null;
+    /** 面板正有一次电话在飞（本地忙守卫的一半）。 */
+    inFlight?: boolean;
+    /** 是否已经拿到过第一次回包（决定总账那句是不是「正在读取…」）。 */
+    loaded?: boolean;
+    titles?: Record<string, string>;
+    /** 键 -> 该家被跳过的版本（挂载侧从跳过存储读出；纯渲染函数不读存储）。 */
+    skippedVersions?: Record<string, string | null>;
+    /** notice 归哪一家：等于某行键时那条回执画在该家详情里（否则画在面板底部）。 */
+    noticeKey?: string | null;
+}
+/** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */
+export declare function renderBatchPanelHTML(input: BatchPanelRenderInput): string;
+export declare const UPDATE_BATCH_PANEL_CSS: string;
+/**
+ * 批量面板的 D5 皮肤（#20 同一套口径：只换颜色/字体/间距，不改顺序、不藏东西）。
+ * 卷宗抬头右侧给大印章留 120px（与单插件面板档案头同一处理）。
+ */
+export declare const UPDATE_BATCH_PANEL_D5_CSS: string;
+/**
+ * 挂批量面板（调用方一行即跑）：
+ * ```js
+ * const panel = mountUpdateBatchPanel(document.getElementById('upd'), { prefix: 'life', call: host.call })
+ * // …离开时 panel.unmount()（只停轮询，批量更新在宿主侧继续跑）
+ * ```
+ */
+export declare function mountUpdateBatchPanel(container: BatchPanelContainer, options: BatchPanelOptions): BatchPanelController;