@nsnanocat/preference-panes 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "description": "Shared settings API runtime for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",
@@ -18,6 +18,7 @@
     "type": "module",
     "main": "src/index.mjs",
     "exports": {
+        "./styles/*": "./src/browser/vendor/*",
         ".": {
             "types": "./src/index.d.ts",
             "import": "./src/index.mjs"

package/src/browser/ActionMenu.mjs

@@ -0,0 +1,115 @@
+/**
+ * 标题栏共用三点菜单；Shadow DOM 隔离项目样式，保留继承的主题色。
+ * Shared title-bar overflow menu; Shadow DOM isolates layout while inheriting theme colors.
+ */
+export class ActionMenu {
+    #button;
+    #popup;
+    #backdrop;
+    #select;
+    #document;
+    #key = event => {
+        if (event.key === "Escape" && !this.#popup.hidden) {
+            event.preventDefault();
+            this.close();
+            this.#button.focus();
+        }
+    };
+
+    /**
+     * 创建菜单，操作逻辑由调用方提供。
+     * Create a menu whose actions are handled by the caller.
+     * @param {(id: string) => void} select 菜单选择回调 / Selection callback.
+     */
+    constructor(select) {
+        this.#document = document;
+        this.#select = select;
+        this.element = document.createElement("span");
+        const root = this.element.attachShadow({ mode: "open" });
+        root.innerHTML = `<style>
+          :host{display:inline-flex;position:relative;width:44px;height:44px;color:inherit}
+          :host([hidden]),[hidden]{display:none!important}
+          button{font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button:disabled{opacity:.4;cursor:default}
+          button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
+          #trigger{width:44px;height:44px;padding:10px;position:relative;z-index:3}
+          svg{display:block;width:24px;height:24px;fill:currentColor}
+          #backdrop{position:fixed;inset:0;z-index:1}
+          #items{position:absolute;right:0;top:46px;z-index:2;min-width:160px;padding:6px;background:var(--pp-surface,Canvas);color:var(--pp-text,CanvasText);border:1px solid var(--pp-border,#8884);border-radius:12px;box-shadow:0 8px 28px #0003}
+          #items button{display:block;text-align:left;white-space:nowrap;width:100%;padding:11px 14px;border-radius:8px;font:14px/1.4 system-ui,sans-serif}
+          #items button:hover{background:#8882}
+          #items button[data-danger]{color:#e45656}
+        </style><button id="trigger" type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false" aria-controls="items"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="4" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="20" cy="12" r="2"/></svg></button><button id="backdrop" type="button" tabindex="-1" aria-label="关闭菜单" hidden></button><div id="items" role="menu" hidden></div>`;
+        this.#button = root.querySelector("#trigger");
+        this.#popup = root.querySelector("#items");
+        this.#backdrop = root.querySelector("#backdrop");
+        this.#button.onclick = () => {
+            const open = this.#popup.hidden;
+            this.#popup.hidden = this.#backdrop.hidden = !open;
+            this.#button.setAttribute("aria-expanded", String(open));
+            if (open) this.#popup.firstElementChild.focus();
+        };
+        this.#backdrop.onclick = () => this.close();
+        this.#popup.onkeydown = event => {
+            if (event.key === "Tab") {
+                this.close();
+                return;
+            }
+            const items = [...this.#popup.children];
+            const index = items.indexOf(root.activeElement);
+            const offsets = { ArrowDown: 1, ArrowUp: -1 };
+            if (event.key in offsets) {
+                event.preventDefault();
+                items[(index + offsets[event.key] + items.length) % items.length].focus();
+            }
+        };
+        document.addEventListener("keydown", this.#key);
+        this.update([]);
+    }
+
+    /**
+     * 同步可用操作和忙碌状态，不重建菜单触发按钮。
+     * Update actions and busy state without replacing the trigger button.
+     * @param {Array<{id: string, label: string, destructive?: boolean}>} items 操作列表 / Actions.
+     * @param {boolean} [disabled] 是否忙碌 / Whether operations are busy.
+     * @returns {void} 无返回值 / No return value.
+     */
+    update(items, disabled = false) {
+        this.close();
+        this.#button.disabled = disabled || items.length === 0;
+        this.#popup.replaceChildren(
+            ...items.map(item => {
+                const button = this.#document.createElement("button");
+                button.type = "button";
+                button.setAttribute("role", "menuitem");
+                button.textContent = item.label;
+                button.toggleAttribute("data-danger", Boolean(item.destructive));
+                button.onclick = () => {
+                    this.close();
+                    this.#select(item.id);
+                };
+                return button;
+            }),
+        );
+    }
+
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns {void} 无返回值 / No return value.
+     */
+    close() {
+        this.#popup.hidden = this.#backdrop.hidden = true;
+        this.#button.setAttribute("aria-expanded", "false");
+    }
+
+    /**
+     * 移除监听器与节点。
+     * Remove listeners and elements.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#document.removeEventListener("keydown", this.#key);
+        this.element.remove();
+    }
+}

package/src/browser/ModuleFrame.mjs

@@ -11,9 +11,13 @@ export class ModuleFrame extends EventTarget {
     #abort = () => this.destroy();
     #state;
     #change = event => {
-        this.#state = event.detail;
+        this.#state = { ...event.detail, actions: event.detail.actions ?? [] };
         this.dispatchEvent(new Event("change"));
     };
+    #confirmation = event => {
+        const request = new CustomEvent("confirm", { cancelable: true, detail: event.detail });
+        if (!this.dispatchEvent(request)) event.preventDefault();
+    };
 
     /**
      * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
@@ -30,7 +34,8 @@ export class ModuleFrame extends EventTarget {
         this.element.title = `${inputs.module} 设置`;
         this.element.dataset.preferencePanes = JSON.stringify(inputs);
         this.element.addEventListener("preferencepanes:change", this.#change);
-        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true };
+        this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
+        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
         options.signal?.addEventListener("abort", this.#abort, { once: true });
     }
 
@@ -70,6 +75,17 @@ export class ModuleFrame extends EventTarget {
         if (!this.#state.busy && this.#state.canGoBack) this.element.contentWindow.history.back();
     }
 
+    /**
+     * 向模块发送菜单操作，不让宿主访问内部 DOM 或存储客户端。
+     * Dispatch a menu action without host access to internal DOM or the storage client.
+     * @param {string} id 当前可用操作 / Available action identifier.
+     * @returns {void} 无返回值 / No return value.
+     */
+    perform(id) {
+        if (this.#state.busy || !this.#state.actions.some(action => action.id === id)) throw new Error("Action is not available");
+        this.element.dispatchEvent(new CustomEvent("preferencepanes:action", { detail: id }));
+    }
+
     /**
      * 取消加载与事件订阅；节点保留到 Navigation 的退出动画结束。
      * Cancel loading and subscriptions; Navigation retains the node until its exit animation ends.
@@ -79,5 +95,6 @@ export class ModuleFrame extends EventTarget {
         this.#controller.abort();
         this.#options.signal?.removeEventListener("abort", this.#abort);
         this.element.removeEventListener("preferencepanes:change", this.#change);
+        this.element.removeEventListener("preferencepanes:confirm", this.#confirmation);
     }
 }

package/src/browser/ModuleStatus.mjs

@@ -0,0 +1,86 @@
+/**
+ * 模块入口的固定状态行，只通过 HEAD 探测安装状态和业务版本。
+ * Fixed module status row, probing installation and business version with HEAD only.
+ */
+export class ModuleStatus extends EventTarget {
+    #element;
+    #controller;
+    #state = { status: "checking", version: null };
+
+    /**
+     * 绑定调用方提供的状态行。
+     * Bind a caller-owned status row.
+     * @param {HTMLElement} element 状态文字容器 / Status text container.
+     */
+    constructor(element) {
+        super();
+        this.#element = element;
+        this.#render("checking");
+    }
+
+    /**
+     * 当前安装状态与业务版本。
+     * Current installation state and business version.
+     */
+    get state() {
+        return { ...this.#state };
+    }
+
+    /**
+     * 每次进入重新探测，取消旧请求并忽略其迟到结果。
+     * Reprobe on entry, cancelling old requests and ignoring late results.
+     * @param {string | URL} url 配置 Mock 地址 / Configuration Mock URL.
+     * @returns {Promise<void>} 探测完成 / Probe completion.
+     */
+    async check(url) {
+        this.#controller?.abort();
+        const controller = (this.#controller = new AbortController());
+        this.#render("checking");
+        const timer = setTimeout(() => controller.abort(), 3500);
+        try {
+            const response = await fetch(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
+            if (controller !== this.#controller) return;
+            const version = response.headers.get("X-PreferencePanes-Version")?.trim() || null;
+            this.#render(response.status === 200 ? "installed" : "missing", version);
+        } catch {
+            if (controller === this.#controller) this.#render("missing");
+        } finally {
+            clearTimeout(timer);
+        }
+    }
+
+    /**
+     * 更新状态标签，缺少版本时不伪造版本号。
+     * Render the label without inventing a missing version.
+     * @param {"checking" | "installed" | "missing"} status 状态 / State.
+     * @param {string | null} [version] 业务版本 / Business version.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #render(status, version = null) {
+        this.#state = { status, version: status === "installed" ? version : null };
+        switch (status) {
+            case "checking":
+                this.#element.textContent = "检测中";
+                break;
+            case "installed":
+                this.#element.textContent = version ?? "版本未知";
+                break;
+            case "missing":
+                this.#element.textContent = "未安装";
+                break;
+        }
+        this.#element.dataset.state = status;
+        this.#element.title = this.#element.textContent;
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放尚未完成的探测。
+     * Release pending probes.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#controller?.abort();
+        this.#controller = undefined;
+    }
+}

package/src/browser/Navigation.d.mts

@@ -1,6 +1,8 @@
 /**
  * 原始 HTML 的模块 iframe 容器；通过元素传递请求上下文。
  * Iframe container preserving module HTML and carrying context on the element.
+ * confirm 事件可 preventDefault 后通过 detail.resolve/reject 完成宿主确认。
+ * Prevent default on confirm events and settle host dialogs through detail.resolve/reject.
  */
 export class ModuleFrame extends EventTarget {
     /**
@@ -19,7 +21,7 @@ export class ModuleFrame extends EventTarget {
      * change 事件对应的导航状态。
      * Navigation state exposed with change events.
      */
-    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean };
+    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean; actions: MenuAction[] };
     /**
      * 获取原始 HTML。
      * Fetch unmodified HTML.
@@ -32,6 +34,13 @@ export class ModuleFrame extends EventTarget {
      * @returns 无返回值 / No return value.
      */
     back(): void;
+    /**
+     * 执行模块提供的菜单操作。
+     * Perform a module-provided menu action.
+     * @param id 操作标识 / Action identifier.
+     * @returns 无返回值 / No return value.
+     */
+    perform(id: string): void;
     /**
      * 取消请求与事件订阅。
      * Cancel requests and subscriptions.
@@ -40,6 +49,123 @@ export class ModuleFrame extends EventTarget {
     destroy(): void;
 }
 
+/**
+ * 宿主确认事件的数据。
+ * Host confirmation event detail.
+ */
+export interface ConfirmationRequest {
+    /**
+     * 确认内容。
+     * Confirmation message.
+     */
+    message: string;
+    /**
+     * 返回选择。
+     * Return the user's choice.
+     * @param confirmed 是否确认 / Whether confirmed.
+     * @returns 无返回值 / No return value.
+     */
+    resolve(confirmed: boolean): void;
+    /**
+     * 返回失败。
+     * Return a failure.
+     * @param error 错误 / Error.
+     * @returns 无返回值 / No return value.
+     */
+    reject(error: Error): void;
+}
+
+/**
+ * 菜单操作描述。
+ * Menu action descriptor.
+ */
+export interface MenuAction {
+    /**
+     * 操作标识。
+     * Action identifier.
+     */
+    id: string;
+    /**
+     * 显示文字。
+     * Display text.
+     */
+    label: string;
+    /**
+     * 危险操作样式。
+     * Destructive action style.
+     */
+    destructive?: boolean;
+}
+
+/**
+ * 共用三点菜单。
+ * Shared overflow menu.
+ */
+export class ActionMenu {
+    /**
+     * 创建菜单。
+     * Create a menu.
+     * @param select 选择回调 / Selection callback.
+     */
+    constructor(select: (id: string) => void);
+    /**
+     * 菜单节点。
+     * Menu element.
+     */
+    readonly element: HTMLElement;
+    /**
+     * 更新操作列表。
+     * Update available actions.
+     * @param items 操作列表 / Actions.
+     * @param disabled 是否忙碌 / Busy state.
+     * @returns 无返回值 / No return value.
+     */
+    update(items: MenuAction[], disabled?: boolean): void;
+    /**
+     * 关闭菜单。
+     * Close the menu.
+     * @returns 无返回值 / No return value.
+     */
+    close(): void;
+    /**
+     * 释放组件。
+     * Release the component.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
+/**
+ * HEAD 探测的固定模块状态行。
+ * Fixed module status row backed by HEAD probes.
+ */
+export class ModuleStatus extends EventTarget {
+    /**
+     * 绑定状态行。
+     * Bind a status row.
+     * @param element 状态行节点 / Status row node.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * 当前状态及模块版本。
+     * Current state and module version.
+     */
+    readonly state: { status: "checking" | "installed" | "missing"; version: string | null };
+    /**
+     * 探测配置 Mock。
+     * Probe a configuration Mock.
+     * @param url 配置地址 / Configuration URL.
+     * @returns 探测完成 / Probe completion.
+     */
+    check(url: string | URL): Promise<void>;
+    /**
+     * 取消探测。
+     * Cancel probes.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}
+
 /**
  * 同一文档的根页/子页导航，不定义页面布局或模块业务。
  * Home/detail navigation within a document, without layout or module business rules.

package/src/browser/Navigation.mjs

@@ -1,4 +1,6 @@
+export { ActionMenu } from "./ActionMenu.mjs";
 export { ModuleFrame } from "./ModuleFrame.mjs";
+export { ModuleStatus } from "./ModuleStatus.mjs";
 
 /**
  * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。

package/src/browser/components.mjs

@@ -10,10 +10,30 @@
 export function element(tag, className, text) {
     const node = document.createElement(tag);
     node.className = className;
+    // 官方 AppSettings 1.1.2 的作用域标记与原版 CSS 一起固定版本。
+    // Pin official AppSettings 1.1.2 scope attributes together with its unmodified CSS.
+    if (/\bform-row(?:\b|__)/.test(className)) node.setAttribute("data-v-b69aa1ea", "");
+    if (/\bform-group(?:\b|__)/.test(className)) node.setAttribute("data-v-e590be47", "");
     if (text !== undefined) node.textContent = text;
     return node;
 }
 
+/**
+ * 搜索、选择和文本控件共用官方 VField 的 DOM 结构。
+ * Share the official VField DOM structure across search, select and text controls.
+ * @param {HTMLElement} control 已创建的原生控件 / Existing native control.
+ * @param {boolean} [multiline] 是否为多行输入 / Whether the control is multiline.
+ * @returns {HTMLDivElement} 字段容器 / Field container.
+ */
+export function fieldControl(control, multiline = false) {
+    const field = element("div", `v-field pp-editor${multiline ? " v-field--textarea" : ""}`);
+    const body = element("div", "v-field__body");
+    control.classList.add("v-field__control");
+    body.append(control);
+    field.append(body);
+    return field;
+}
+
 /**
  * 元数据地址只允许 HTTP(S) 和相对地址。
  * Allow only HTTP(S) and relative metadata addresses.
@@ -57,3 +77,21 @@ export function errorView(error, retry) {
     view.append(element("p", "", `加载失败：${error.message}`), button);
     return view;
 }
+
+/**
+ * 请求宿主确认；独立网页使用浏览器对话框。
+ * Request confirmation from the host, using the browser dialog for standalone pages.
+ * @param {Window} host 模块窗口 / Module window.
+ * @param {string} message 确认内容 / Confirmation message.
+ * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
+ */
+export function requestConfirmation(host, message) {
+    return new Promise((resolve, reject) => {
+        const frame = host.frameElement;
+        if (frame) {
+            const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:confirm", { cancelable: true, detail: { message, resolve, reject } });
+            if (!frame.dispatchEvent(event)) return;
+        }
+        resolve(host.confirm(message));
+    });
+}

package/src/browser/index.mjs

@@ -30,8 +30,28 @@ export function mount(boxjs, css = "") {
     document.head.append(base, custom);
     const previousTitle = document.title;
     const previousTheme = document.documentElement.dataset.theme;
-    const theme = navigator.userAgent.match(/themeId\/(\d+)/)?.[1];
-    if (theme) document.documentElement.dataset.theme = theme === "2" ? "dark" : "light";
+    const previousDark = document.documentElement.classList.contains("bili_dark");
+    const systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
+    const previousKeyboard = document.documentElement.style.getPropertyValue("--pp-keyboard-height");
+    const host = window.frameElement?.ownerDocument.documentElement;
+    /**
+     * 跟随嵌入宿主的通用环境状态，不识别业务 App 或解析其 UA。
+     * Follow generic host appearance without detecting a business app or parsing its user agent.
+     * @returns {void} 已同步主题与键盘避让 / Theme and keyboard clearance synchronized.
+     */
+    const syncAppearance = () => {
+        const theme = host?.dataset.theme ?? previousTheme ?? (systemTheme.matches ? "dark" : "light");
+        document.documentElement.dataset.theme = theme;
+        document.documentElement.classList.toggle("bili_dark", theme === "dark");
+        if (host) document.documentElement.style.setProperty("--pp-keyboard-height", host.style.getPropertyValue("--pp-keyboard-height"));
+    };
+    let observer;
+    syncAppearance();
+    systemTheme.addEventListener("change", syncAppearance);
+    if (host) {
+        observer = new MutationObserver(syncAppearance);
+        observer.observe(host, { attributes: true, attributeFilter: ["data-theme", "style"] });
+    }
     document.title = metadata.name ?? catalog.module.module;
     let panel;
     const view = {
@@ -41,6 +61,9 @@ export function mount(boxjs, css = "") {
          * @returns {void} 无返回值 / No return value.
          */
         destroy() {
+            observer?.disconnect();
+            systemTheme.removeEventListener("change", syncAppearance);
+            document.documentElement.classList.toggle("bili_dark", previousDark);
             panel?.destroy();
             base.remove();
             custom.remove();
@@ -49,6 +72,7 @@ export function mount(boxjs, css = "") {
             document.title = previousTitle;
             if (previousTheme === undefined) delete document.documentElement.dataset.theme;
             else document.documentElement.dataset.theme = previousTheme;
+            document.documentElement.style.setProperty("--pp-keyboard-height", previousKeyboard);
         },
     };
     try {