@nsnanocat/preference-panes 1.3.0 → 1.3.1

package/src/browser/home.mjs

@@ -1,4 +1,5 @@
-import { ActionMenu, ModuleFrame, ModuleStatus, Navigation } from "./Navigation.mjs";
+import { ActionMenu, ModuleStatus } from "./Navigation.mjs";
+import { browserHost, PageController } from "./page.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
@@ -10,6 +11,11 @@ import { installDefaultStyles } from "./styles.mjs";
 function validateHome(config) {
     if (!config || typeof config.title !== "string" || !Array.isArray(config.sections)) throw new Error("首页 JSON 缺少 title 或 sections");
     if (config.logo !== undefined && typeof config.logo !== "string") throw new Error("首页 logo 必须是图片地址");
+    if (config.logoText !== undefined && typeof config.logoText !== "string") throw new Error("首页 logoText 必须是文字");
+    if (config.logoHref !== undefined) {
+        if (typeof config.logoHref !== "string") throw new Error("首页 logoHref 必须是链接地址");
+        if (["javascript:", "data:", "vbscript:"].includes(new URL(config.logoHref, "https://preference-panes.invalid/").protocol)) throw new Error("首页 logoHref 的链接无效");
+    }
     if (config.footer !== undefined && (!Array.isArray(config.footer) || config.footer.some(text => typeof text !== "string"))) throw new Error("首页 footer 必须是文字数组");
     const modules = new Set();
     for (const section of config.sections) {
@@ -21,11 +27,11 @@ function validateHome(config) {
             if (item.target !== undefined && (item.module !== undefined || !["internal", "_self", "_blank"].includes(item.target))) throw new Error(`入口 ${item.name} 的 target 只允许链接使用 internal、_self 或 _blank`);
             if ((typeof item.module === "string") === (typeof item.href === "string") || (item.module !== undefined && typeof item.module !== "string") || (item.href !== undefined && typeof item.href !== "string")) throw new Error(`入口 ${item.name} 必须选择 module 或 href`);
             if (item.module !== undefined) {
-                if (!/^[A-Za-z0-9_-]+$/.test(item.module) || (item.pageModule !== undefined && (typeof item.pageModule !== "string" || !/^[A-Za-z0-9_-]+$/.test(item.pageModule))) || modules.has(item.module)) throw new Error(`入口 ${item.name} 的模块名称无效或重复`);
+                if (!/^[A-Za-z0-9_-]+$/.test(item.module) || modules.has(item.module)) throw new Error(`入口 ${item.name} 的模块名称无效或重复`);
                 modules.add(item.module);
             } else {
                 const protocol = new URL(item.href, "https://preference-panes.invalid/").protocol;
-                if (item.pageModule !== undefined || ["javascript:", "data:", "vbscript:"].includes(protocol) || (item.target === "internal" && !["http:", "https:"].includes(protocol))) throw new Error(`入口 ${item.name} 的链接无效`);
+                if (["javascript:", "data:", "vbscript:"].includes(protocol) || (item.target === "internal" && !["http:", "https:"].includes(protocol))) throw new Error(`入口 ${item.name} 的链接无效`);
             }
         }
     }
@@ -42,13 +48,6 @@ function validateHome(config) {
 function renderHome(config, url, home) {
     const document = home.ownerDocument;
     home.replaceChildren();
-    if (config.logo) {
-        const logo = document.createElement("img");
-        logo.className = "pp-home-logo";
-        logo.src = new URL(config.logo, url).href;
-        logo.alt = config.title;
-        home.append(logo);
-    }
     for (const section of config.sections) {
         const group = document.createElement("section");
         group.className = "pp-group";
@@ -65,7 +64,6 @@ function renderHome(config, url, home) {
                 entry.type = "button";
                 entry.disabled = true;
                 entry.dataset.module = item.module;
-                if (item.pageModule) entry.dataset.preferencePanesModule = item.pageModule;
             } else {
                 entry.href = new URL(item.href, url).href;
                 if (item.target !== undefined) {
@@ -132,90 +130,6 @@ function renderHome(config, url, home) {
     home.append(footer);
 }
 
-/**
- * 浏览器宿主提供网页导航、通知、主题和可视区域避让。
- * The browser host provides web navigation, notices, theme and viewport clearance.
- * @param {import("./home.mjs").BridgeOptions} options 菜单和返回动作 / Menu and back action.
- * @returns {import("./home.mjs").Bridge} 浏览器宿主 / Browser host.
- */
-function browserHost({ menu, back }) {
-    const root = document.documentElement;
-    const header = document.createElement("header");
-    header.className = "pp-host-header";
-    const button = document.createElement("button");
-    button.className = "pp-host-back";
-    button.type = "button";
-    button.textContent = "‹";
-    button.setAttribute("aria-label", "返回");
-    button.onclick = back;
-    const title = document.createElement("span");
-    title.className = "pp-host-title";
-    header.append(button, title, menu.element);
-    document.body.prepend(header);
-    const toast = document.createElement("div");
-    toast.className = "pp-host-toast";
-    toast.setAttribute("role", "status");
-    toast.hidden = true;
-    document.body.append(toast);
-    let timer;
-    const theme = window.matchMedia("(prefers-color-scheme: dark)");
-    const applyTheme = () => {
-        root.dataset.theme = theme.matches ? "dark" : "light";
-    };
-    const viewport = window.visualViewport;
-    const resize = () => {
-        root.style.setProperty("--pp-host-height", `${header.getBoundingClientRect().height}px`);
-        const clearance = viewport && viewport.scale === 1 ? Math.max(0, window.innerHeight - viewport.height - viewport.offsetTop) : 0;
-        root.style.setProperty("--pp-keyboard-height", `${clearance}px`);
-    };
-    theme.addEventListener("change", applyTheme);
-    window.addEventListener("resize", resize);
-    window.addEventListener("pageshow", resize);
-    viewport?.addEventListener("resize", resize);
-    viewport?.addEventListener("scroll", resize);
-    applyTheme();
-    resize();
-    return {
-        update(state) {
-            title.textContent = state.title;
-            button.hidden = !state.canGoBack;
-            menu.element.hidden = !state.actions.length;
-        },
-        confirm: message => window.confirm(message),
-        notice(detail) {
-            clearTimeout(timer);
-            toast.textContent = detail.message;
-            toast.hidden = false;
-            timer = setTimeout(() => {
-                toast.hidden = true;
-            }, 2400);
-        },
-        openURL(url, target) {
-            switch (target) {
-                case "_blank":
-                    window.open(url, "_blank", "noopener,noreferrer");
-                    break;
-                default:
-                    window.location.assign(url);
-                    break;
-            }
-        },
-        destroy() {
-            clearTimeout(timer);
-            theme.removeEventListener("change", applyTheme);
-            window.removeEventListener("resize", resize);
-            window.removeEventListener("pageshow", resize);
-            viewport?.removeEventListener("resize", resize);
-            viewport?.removeEventListener("scroll", resize);
-            root.style.removeProperty("--pp-host-height");
-            root.style.removeProperty("--pp-keyboard-height");
-            delete root.dataset.theme;
-            header.remove();
-            toast.remove();
-        },
-    };
-}
-
 /**
  * 读取固定相对路径的首页 JSON 与可选 CSS、Bridge，初始化后共用模块探测与导航。
  * Load homepage JSON and optional CSS and Bridge at fixed relative paths, then share module probes and navigation.
@@ -225,8 +139,7 @@ export async function startHome() {
     let host;
     let menu;
     let navigation;
-    let frame;
-    let linkTitle;
+    let page;
     let statuses = [];
     let destroyed = false;
     let defaults;
@@ -237,9 +150,11 @@ export async function startHome() {
         destroyed = true;
         controller.abort();
         for (const { status } of statuses) status.destroy();
-        navigation?.destroy();
-        host?.destroy();
-        menu?.destroy();
+        if (page) page.destroy();
+        else {
+            host?.destroy();
+            menu?.destroy();
+        }
         stylesheet?.remove();
         if (defaults?.owned) defaults.element.remove();
         window.removeEventListener("pagehide", pagehide);
@@ -301,8 +216,8 @@ export async function startHome() {
         }
         if (destroyed) return destroy;
         document.title = config.title;
-        menu = new ActionMenu(id => frame.perform(id));
-        host = await factory({ menu, back: () => (navigation.current && frame ? frame.back() : navigation.back()) });
+        menu = new ActionMenu(id => page.perform(id));
+        host = await factory({ menu, back: () => navigation.back() });
         if (destroyed) {
             host.destroy();
             menu.destroy();
@@ -310,82 +225,20 @@ export async function startHome() {
         }
         const container = document.querySelector("[data-preference-panes-pages]");
         const home = document.querySelector("[data-preference-panes-home]");
-        const template = document.querySelector("template[data-preference-panes-module]");
         renderHome(config, jsonURL, home);
         const buttons = [...home.querySelectorAll("[data-module]")];
         const links = [...home.querySelectorAll("a[href]")];
-        const stylesheetURL = stylesheet?.href;
-        const update = () => {
-            if (destroyed) return;
-            const state = navigation.current && frame ? frame.state : { title: navigation.current ? linkTitle : document.title, actions: [], busy: false, canGoBack: navigation.canGoBack };
-            menu.update(state.actions, state.busy);
-            Promise.resolve(host.update(state)).catch(error => {
-                if (!destroyed) host.notice({ kind: "error", message: error.message });
-            });
-        };
-        navigation = new Navigation(container, home, (module, signal) => {
-            frame = undefined;
-            const link = links.find((link, index) => link.dataset.target === "internal" && module === `link:${index}`);
-            if (link) {
-                const page = document.createElement("section");
-                page.dataset.preferencePanesLinkPage = "";
-                const iframe = document.createElement("iframe");
-                linkTitle = link.querySelector(".pp-home-name").textContent;
-                iframe.title = linkTitle;
-                iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox");
-                iframe.src = link.href;
-                page.append(iframe);
-                signal.addEventListener("abort", () => iframe.remove(), { once: true });
-                return page;
-            }
-            const button = buttons.find(button => button.dataset.module === module);
-            if (!button) return;
-            const page = template.content.firstElementChild.cloneNode(true);
-            page.dataset.preferencePanesModulePage = "";
-            const message = page.querySelector("[data-module-message]");
-            const moduleName = encodeURIComponent(button.dataset.preferencePanesModule ?? module);
-            const current = new ModuleFrame(`/settings/${moduleName}`, {
-                signal,
-                headers: { "X-PreferencePanes-JSON": `/api/${encodeURIComponent(module)}`, ...(stylesheetURL ? { "X-PreferencePanes-CSS": stylesheetURL } : {}) },
-            });
-            frame = current;
-            current.addEventListener("confirm", event => {
-                event.preventDefault();
-                Promise.resolve()
-                    .then(() => host.confirm(event.detail.message))
-                    .then(
-                        value => {
-                            if (!signal.aborted) event.detail.resolve(value);
-                        },
-                        error => {
-                            if (!signal.aborted) event.detail.reject(error);
-                        },
-                    );
-            });
-            current.addEventListener("notice", event => {
-                event.preventDefault();
-                host.notice(event.detail);
-            });
-            current.addEventListener("open-url", event => {
-                event.preventDefault();
-                Promise.resolve()
-                    .then(() => host.openURL(event.detail.url))
-                    .catch(error => {
-                        if (!signal.aborted) host.notice({ kind: "error", message: error.message });
-                    });
-            });
-            current.addEventListener("change", () => {
-                if (!signal.aborted) update();
-            });
-            current.element.onload = () => {
-                if (!signal.aborted) message.hidden = true;
-            };
-            page.append(current.element);
-            current.load().catch(error => {
-                if (!signal.aborted) message.textContent = error.message;
-            });
-            return page;
+        page = new PageController(container, home, {
+            host,
+            menu,
+            title: config.title,
+            logo: config.logo ? new URL(config.logo, jsonURL).href : undefined,
+            logoText: config.logoText,
+            logoHref: new URL(config.logoHref || "/", jsonURL).href,
+            modules: new Map(config.sections.flatMap(section => section.items.filter(item => item.module).map(item => [item.module, item]))),
+            links,
         });
+        navigation = page.navigation;
         for (const [index, link] of links.entries()) {
             link.addEventListener(
                 "click",
@@ -394,16 +247,10 @@ export async function startHome() {
                     event.preventDefault();
                     switch (link.dataset.target) {
                         case "internal":
-                            navigation.open(`link:${index}`);
+                            navigation.open(`$link/${index}`);
                             break;
                         default:
-                            try {
-                                Promise.resolve(host.openURL(link.href, link.dataset.target)).catch(error => {
-                                    if (!destroyed) host.notice({ kind: "error", message: error.message });
-                                });
-                            } catch (error) {
-                                if (!destroyed) host.notice({ kind: "error", message: error.message });
-                            }
+                            page.openURL(link.href, link.dataset.target);
                             break;
                     }
                 },
@@ -419,7 +266,6 @@ export async function startHome() {
             return { button, status };
         });
         const probe = () => {
-            update();
             if (navigation.current) return;
             for (const { button, status } of statuses) status.check(`/api/${encodeURIComponent(button.dataset.module)}`);
         };

package/src/browser/mount.mjs

@@ -1,103 +1,62 @@
+import { ActionMenu } from "./ActionMenu.mjs";
 import { normalizeBoxJs } from "./boxjs.mjs";
-import { element, resourceURL } from "./components.mjs";
-import { PreferencesPanel } from "./panel.mjs";
+import { element } from "./components.mjs";
+import { browserHost, PageController } from "./page.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
- * 管理 BoxJS 规范化、主题同步和面板生命周期。
- * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
+ * 使用原始 BoxJS JSON 挂载设置页，共用内部页面控制器。
+ * Mount a settings page from raw BoxJS JSON through the shared internal page controller.
+ * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
+ * @returns {import("./index.js").MountedPreferences} 模块视图 / Module view.
  */
-class PreferencesView {
-    #existing;
-    #root;
-    #base;
-    #ownsBase;
-    #previousTitle;
-    #previousTheme;
-    #systemTheme;
-    #previousKeyboard;
-    #host;
-    #observer;
-    #panel;
-
-    /**
-     * 使用原始 BoxJS JSON 挂载设置页。
-     * Mount a settings page from raw BoxJS JSON.
-     * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
-     */
-    constructor(boxjs) {
-        const definition = normalizeBoxJs(boxjs);
-        const metadata = definition.metadata ?? {};
-        const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
-        if (image) resourceURL(image);
-        if (metadata.repo) resourceURL(metadata.repo);
-
-        this.#existing = document.querySelector("#preferences");
-        this.#root = this.#existing ?? element("main", "");
-        if (!this.#existing) {
-            this.#root.id = "preferences";
-            document.body.append(this.#root);
-        }
-        const styles = installDefaultStyles(document);
-        this.#base = styles.element;
-        this.#ownsBase = styles.owned;
-        this.#previousTitle = document.title;
-        this.#previousTheme = document.documentElement.dataset.theme;
-        this.#systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
-        this.#previousKeyboard = document.documentElement.style.getPropertyValue("--pp-keyboard-height");
-        this.#host = window.frameElement?.ownerDocument.documentElement;
-        this.#syncAppearance();
-        this.#systemTheme.addEventListener("change", this.#syncAppearance);
-        if (this.#host) {
-            this.#observer = new MutationObserver(this.#syncAppearance);
-            this.#observer.observe(this.#host, { attributes: true, attributeFilter: ["data-theme", "style"] });
-        }
-        document.title = metadata.name ?? definition.module;
-        try {
-            this.#root.replaceChildren();
-            this.#panel = new PreferencesPanel(this.#root, definition);
-        } catch (error) {
-            this.destroy();
-            throw error;
-        }
+export function mount(boxjs) {
+    const definition = normalizeBoxJs(boxjs);
+    const title = definition.metadata?.name ?? definition.module;
+    const existing = document.querySelector("#preferences");
+    const root = existing ?? element("main", "");
+    const previousTitle = document.title;
+    const previousKeyboard = document.documentElement.style.getPropertyValue("--pp-keyboard-height");
+    const previousHeight = document.documentElement.style.getPropertyValue("--pp-host-height");
+    const previousTheme = document.documentElement.dataset.theme;
+    const previousClass = document.documentElement.classList.contains("pp-page");
+    document.documentElement.classList.add("pp-page");
+    root.dataset.preferencePanesPages = "";
+    if (!existing) {
+        root.id = "preferences";
+        document.body.append(root);
     }
-
-    /**
-     * 跟随嵌入宿主的通用环境状态，不识别业务 App 或解析其 UA。
-     * Follow generic host appearance without detecting a business App or parsing its UA.
-     * @returns {void} 已同步主题与键盘避让 / Theme and keyboard clearance synchronized.
-     */
-    #syncAppearance = () => {
-        const theme = this.#host?.dataset.theme ?? this.#previousTheme ?? (this.#systemTheme.matches ? "dark" : "light");
-        document.documentElement.dataset.theme = theme;
-        if (this.#host) document.documentElement.style.setProperty("--pp-keyboard-height", this.#host.style.getPropertyValue("--pp-keyboard-height"));
+    const defaults = installDefaultStyles(document);
+    const menu = new ActionMenu(id => page.perform(id));
+    const host = browserHost({ menu, back: () => page.navigation.back() });
+    const page = new PageController(root, element("main", "pp-home"), { host, menu, title, modules: new Map([[definition.module, { name: title, boxjs }]]) });
+    if (!page.navigation.current) page.navigation.open(definition.module);
+    let destroyed = false;
+    const pagehide = event => {
+        if (!event.persisted) destroy();
     };
-
+    window.addEventListener("pagehide", pagehide);
     /**
-     * 释放模块视图、样式与会话，不操作项目入口页。
-     * Release the module view, styles, and session without operating a project landing page.
+     * 释放模块、样式与监听器，并恢复调用方的文档状态。
+     * Release the module, styles and listeners and restore the caller's document state.
      * @returns {void} 无返回值 / No return value.
      */
-    destroy() {
-        this.#observer?.disconnect();
-        this.#systemTheme.removeEventListener("change", this.#syncAppearance);
-        this.#panel?.destroy();
-        if (this.#ownsBase) this.#base.remove();
-        if (this.#existing) this.#root.replaceChildren();
-        else this.#root.remove();
-        document.title = this.#previousTitle;
-        if (this.#previousTheme === undefined) delete document.documentElement.dataset.theme;
-        else document.documentElement.dataset.theme = this.#previousTheme;
-        document.documentElement.style.setProperty("--pp-keyboard-height", this.#previousKeyboard);
+    function destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        page.destroy();
+        window.removeEventListener("pagehide", pagehide);
+        if (defaults.owned) defaults.element.remove();
+        if (existing) {
+            root.replaceChildren();
+            delete root.dataset.preferencePanesPages;
+        } else root.remove();
+        if (!previousClass) document.documentElement.classList.remove("pp-page");
+        document.title = previousTitle;
+        document.documentElement.style.setProperty("--pp-keyboard-height", previousKeyboard);
+        document.documentElement.style.setProperty("--pp-host-height", previousHeight);
+        if (previousTheme === undefined) delete document.documentElement.dataset.theme;
+        else document.documentElement.dataset.theme = previousTheme;
     }
-}
-
-/**
- * 使用原始 BoxJS JSON 挂载设置页。
- * Mount a settings page from raw BoxJS JSON.
- * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
- * @returns {import("./index.js").MountedPreferences} 模块视图 / Module view.
- */
-export function mount(boxjs) {
-    return new PreferencesView(boxjs);
+    return { destroy };
 }