@nsnanocat/preference-panes 1.2.5 → 1.3.1

package/src/browser/home.d.mts

@@ -0,0 +1,66 @@
+import type { ActionMenu, MenuAction, Notice } from "./Navigation.mjs";
+
+/** 宿主导航状态 / Bridge navigation state. */
+export interface HomeState {
+    /** 当前标题 / Current title. */
+    title: string;
+    /** 首页导航图片 / Homepage navigation image. */
+    logo?: string;
+    /** 首页导航文字 / Homepage navigation text. */
+    logoText?: string;
+    /** 网页导航品牌链接 / Web navigation brand link. */
+    logoHref?: string;
+    /** 可用菜单操作 / Available menu actions. */
+    actions: MenuAction[];
+    /** 操作是否正在执行 / Whether an operation is in progress. */
+    busy: boolean;
+    /** 联合历史是否可返回 / Whether joint history can go back. */
+    canGoBack: boolean;
+}
+/** 宿主初始化输入 / Bridge initialization inputs. */
+export interface BridgeOptions {
+    /** 共用操作菜单 / Shared action menu. */
+    menu: ActionMenu;
+    /** 沿当前页面历史返回 / Go back through the current page history. */
+    back(): void;
+}
+/** 可选 Bridge 模块提供的宿主能力 / Host capabilities supplied by the optional Bridge module. */
+export interface Bridge {
+    /** 同步当前导航状态 / Synchronize current navigation state. */
+    update(state: HomeState): void | Promise<void>;
+    /** 返回确认或取消选择 / Return the confirmation or cancellation choice. */
+    confirm(message: string): boolean | Promise<boolean>;
+    /** 显示操作结果 / Display an operation result. */
+    notice(detail: Notice): void;
+    /** 打开完整地址；_blank 保留当前页面，_self 替换当前页面 / Open an absolute URL; _blank retains the current page and _self replaces it. */
+    openURL(url: string, target?: "_self" | "_blank"): void | Promise<void>;
+    /** 释放界面与监听器 / Release UI and listeners. */
+    destroy(): void;
+}
+/** 宿主工厂；默认导出 / Bridge factory; the override's default export. */
+export type BridgeFactory = (options: BridgeOptions) => Bridge | Promise<Bridge>;
+/**
+ * 初始化固定路径的 JSON 首页及可选 Bridge。
+ * Initialize the JSON homepage and optional Bridge at fixed paths.
+ * @returns 退出清理动作；失败显示错误并拒绝 / Cleanup action; failures display an error and reject.
+ */
+export function startHome(): Promise<() => void>;
+/** 首页入口图标 / Homepage entry icon. */
+export type HomeIcon = { src: string; text?: never } | { text: string; src?: never };
+/** 外链打开方式：带导航的内部框架、当前页面或新页面 / Link opening mode: an internal frame with navigation, the current page or a new page. */
+export type HomeLinkTarget = "internal" | "_self" | "_blank";
+/** 首页模块或链接入口 / Homepage module or link entry. */
+export type HomeItem = { name: string; icon: HomeIcon; description?: string } & ({ module: string; href?: never; target?: never } | { href: string; target?: HomeLinkTarget; module?: never });
+/** 运行时导入的首页配置 / Runtime-imported homepage configuration. */
+export interface HomeConfig {
+    /** 文档和原生导航标题；未提供品牌时也是网页导航文字 / Document and native navigation title; also the web navigation text when no brand is supplied. */
+    title: string;
+    /** 网页导航图片，相对于 JSON 地址 / Web navigation image, relative to the JSON URL. */
+    logo?: string;
+    /** 网页导航文字，沿用 Rspress 命名 / Web navigation text, following Rspress naming. */
+    logoText?: string;
+    /** 网页导航品牌链接，相对于 JSON 地址；默认网站首页 / Web navigation brand link, relative to the JSON URL; defaults to the site homepage. */
+    logoHref?: string;
+    sections: { title: string; layout?: "grid" | "list"; items: HomeItem[] }[];
+    footer?: string[];
+}

package/src/browser/home.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN" class="pp-page">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+    <title>设置</title>
+  </head>
+  <body>
+    <div data-preference-panes-pages>
+      <main class="pp-home" data-preference-panes-home></main>
+    </div>
+    <script type="module">__PREFERENCE_PANES_HOME_SCRIPT__
+await startHome();</script>
+  </body>
+</html>

package/src/browser/home.mjs

@@ -0,0 +1,287 @@
+import { ActionMenu, ModuleStatus } from "./Navigation.mjs";
+import { browserHost, PageController } from "./page.mjs";
+import { installDefaultStyles } from "./styles.mjs";
+
+/**
+ * 校验外部 JSON 中的章节、入口和导航目标，避免生成不可访问的设置入口。
+ * Validate sections, entries and navigation targets in external JSON before rendering inaccessible entries.
+ * @param {unknown} config 外部首页配置 / External homepage configuration.
+ * @returns {void} 非法输入抛出错误 / Invalid input throws.
+ */
+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) {
+        if (!section || typeof section.title !== "string" || !Array.isArray(section.items) || (section.layout !== undefined && !["grid", "list"].includes(section.layout))) throw new Error("首页章节需要 title、items 和有效的 layout");
+        for (const item of section.items) {
+            if (!item || typeof item.name !== "string" || !item.icon || (typeof item.icon.src === "string") === (typeof item.icon.text === "string") || (item.icon.src !== undefined && typeof item.icon.src !== "string") || (item.icon.text !== undefined && typeof item.icon.text !== "string"))
+                throw new Error("首页入口需要 name 和唯一的图片或文字 icon");
+            if (item.description !== undefined && typeof item.description !== "string") throw new Error(`入口 ${item.name} 的 description 必须是文字`);
+            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) || 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 (["javascript:", "data:", "vbscript:"].includes(protocol) || (item.target === "internal" && !["http:", "https:"].includes(protocol))) throw new Error(`入口 ${item.name} 的链接无效`);
+            }
+        }
+    }
+}
+
+/**
+ * 共用网格和列表章节；资源地址相对于 JSON，所有项目文字通过 textContent 绘制。
+ * Share grid and list sections, resolve resources against JSON and render project text through textContent.
+ * @param {import("./home.mjs").HomeConfig} config 已校验的首页配置 / Validated homepage configuration.
+ * @param {URL} url JSON 地址 / JSON URL.
+ * @param {HTMLElement} home 首页容器 / Homepage container.
+ * @returns {void} 无返回值 / No return value.
+ */
+function renderHome(config, url, home) {
+    const document = home.ownerDocument;
+    home.replaceChildren();
+    for (const section of config.sections) {
+        const group = document.createElement("section");
+        group.className = "pp-group";
+        const title = document.createElement("h2");
+        title.className = "pp-group-title";
+        title.textContent = section.title;
+        const entries = document.createElement("div");
+        entries.className = "pp-home-entries";
+        entries.dataset.layout = section.layout ?? "grid";
+        for (const item of section.items) {
+            const entry = document.createElement(item.module ? "button" : "a");
+            entry.className = "pp-home-item";
+            if (item.module) {
+                entry.type = "button";
+                entry.disabled = true;
+                entry.dataset.module = item.module;
+            } else {
+                entry.href = new URL(item.href, url).href;
+                if (item.target !== undefined) {
+                    entry.dataset.target = item.target;
+                    switch (item.target) {
+                        case "_blank":
+                            entry.target = item.target;
+                            entry.rel = "noopener noreferrer";
+                            break;
+                        case "_self":
+                            entry.target = item.target;
+                            break;
+                    }
+                }
+            }
+            const icon = document.createElement("span");
+            icon.className = "pp-home-icon";
+            icon.setAttribute("aria-hidden", "true");
+            if (item.icon.src !== undefined) {
+                const image = document.createElement("img");
+                image.src = new URL(item.icon.src, url).href;
+                image.alt = "";
+                icon.append(image);
+            } else icon.textContent = item.icon.text;
+            const content = document.createElement("span");
+            content.className = "pp-home-content";
+            const name = document.createElement("span");
+            name.className = "pp-home-name";
+            name.textContent = item.name;
+            content.append(name);
+            if (item.description !== undefined) {
+                const description = document.createElement("span");
+                description.className = "pp-description";
+                description.textContent = item.description;
+                content.append(description);
+            }
+            if (item.module) {
+                const status = document.createElement("span");
+                status.className = "pp-description";
+                status.dataset.moduleStatus = "";
+                status.textContent = "检测中";
+                content.append(status);
+            }
+            entry.append(icon, content);
+            if (entries.dataset.layout === "list") {
+                const arrow = document.createElement("span");
+                arrow.className = "pp-home-arrow";
+                arrow.textContent = "›";
+                arrow.setAttribute("aria-hidden", "true");
+                entry.append(arrow);
+            }
+            entries.append(entry);
+        }
+        group.append(title, entries);
+        home.append(group);
+    }
+    const footer = document.createElement("footer");
+    footer.className = "pp-home-footer pp-description";
+    for (const text of config.footer ?? []) {
+        const paragraph = document.createElement("p");
+        paragraph.textContent = text;
+        footer.append(paragraph);
+    }
+    home.append(footer);
+}
+
+/**
+ * 读取固定相对路径的首页 JSON 与可选 CSS、Bridge，初始化后共用模块探测与导航。
+ * Load homepage JSON and optional CSS and Bridge at fixed relative paths, then share module probes and navigation.
+ * @returns {Promise<() => void>} 退出清理动作；加载失败会显示错误并拒绝 / Cleanup action; load failures display an error and reject.
+ */
+export async function startHome() {
+    let host;
+    let menu;
+    let navigation;
+    let page;
+    let statuses = [];
+    let destroyed = false;
+    let defaults;
+    let stylesheet;
+    const controller = new AbortController();
+    const destroy = () => {
+        if (destroyed) return;
+        destroyed = true;
+        controller.abort();
+        for (const { status } of statuses) status.destroy();
+        if (page) page.destroy();
+        else {
+            host?.destroy();
+            menu?.destroy();
+        }
+        stylesheet?.remove();
+        if (defaults?.owned) defaults.element.remove();
+        window.removeEventListener("pagehide", pagehide);
+    };
+    const pagehide = event => {
+        if (!event.persisted) destroy();
+    };
+    window.addEventListener("pagehide", pagehide);
+    try {
+        defaults = installDefaultStyles(document);
+        const jsonURL = new URL("./home.json", document.baseURI);
+        const response = await fetch(jsonURL, { signal: controller.signal });
+        if (!response.ok) throw new Error(`首页 JSON 加载失败：HTTP ${response.status}`);
+        const config = await response.json();
+        validateHome(config);
+        if (destroyed) return destroy;
+        const cssURL = new URL("./theme.css", document.baseURI);
+        const cssResponse = await fetch(cssURL, { method: "HEAD", cache: "no-store", signal: controller.signal });
+        if (destroyed) return destroy;
+        switch (cssResponse.status) {
+            case 200:
+                stylesheet = document.createElement("link");
+                stylesheet.rel = "stylesheet";
+                stylesheet.dataset.preferencePanesStylesheet = "";
+                stylesheet.href = cssURL.href;
+                await new Promise((resolve, reject) => {
+                    const abort = () => reject(new DOMException("页面已退出", "AbortError"));
+                    controller.signal.addEventListener("abort", abort, { once: true });
+                    stylesheet.onload = () => {
+                        controller.signal.removeEventListener("abort", abort);
+                        resolve();
+                    };
+                    stylesheet.onerror = () => {
+                        controller.signal.removeEventListener("abort", abort);
+                        reject(new Error("项目 CSS 加载失败"));
+                    };
+                    document.head.append(stylesheet);
+                });
+                break;
+            case 404:
+                break;
+            default:
+                throw new Error(`项目 CSS 探测失败：HTTP ${cssResponse.status}`);
+        }
+        if (destroyed) return destroy;
+        const bridgeURL = new URL("./bridge.mjs", document.baseURI);
+        const bridgeResponse = await fetch(bridgeURL, { method: "HEAD", cache: "no-store", signal: controller.signal });
+        if (destroyed) return destroy;
+        let factory;
+        switch (bridgeResponse.status) {
+            case 200:
+                factory = (await import(bridgeURL.href)).default;
+                break;
+            case 404:
+                factory = browserHost;
+                break;
+            default:
+                throw new Error(`Bridge 探测失败：HTTP ${bridgeResponse.status}`);
+        }
+        if (destroyed) return destroy;
+        document.title = config.title;
+        menu = new ActionMenu(id => page.perform(id));
+        host = await factory({ menu, back: () => navigation.back() });
+        if (destroyed) {
+            host.destroy();
+            menu.destroy();
+            return destroy;
+        }
+        const container = document.querySelector("[data-preference-panes-pages]");
+        const home = document.querySelector("[data-preference-panes-home]");
+        renderHome(config, jsonURL, home);
+        const buttons = [...home.querySelectorAll("[data-module]")];
+        const links = [...home.querySelectorAll("a[href]")];
+        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",
+                event => {
+                    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+                    event.preventDefault();
+                    switch (link.dataset.target) {
+                        case "internal":
+                            navigation.open(`$link/${index}`);
+                            break;
+                        default:
+                            page.openURL(link.href, link.dataset.target);
+                            break;
+                    }
+                },
+                { signal: controller.signal },
+            );
+        }
+        statuses = buttons.map(button => {
+            const status = new ModuleStatus(button.querySelector("[data-module-status]"));
+            status.addEventListener("change", () => {
+                button.disabled = status.state.status !== "installed";
+            });
+            button.addEventListener("click", () => navigation.open(button.dataset.module), { signal: controller.signal });
+            return { button, status };
+        });
+        const probe = () => {
+            if (navigation.current) return;
+            for (const { button, status } of statuses) status.check(`/api/${encodeURIComponent(button.dataset.module)}`);
+        };
+        navigation.addEventListener("change", probe);
+        probe();
+        return destroy;
+    } catch (error) {
+        const display = !destroyed;
+        destroy();
+        if (display) {
+            const message = document.createElement("p");
+            message.className = "pp-host-error";
+            message.setAttribute("role", "alert");
+            message.textContent = `无法打开设置：${error.message}`;
+            document.body.prepend(message);
+        }
+        throw error;
+    }
+}

package/src/browser/index.d.ts

@@ -15,3 +15,5 @@ export interface MountedPreferences {
  * @returns 模块视图 / Module view.
  */
 export function mount(boxjs: BoxJSInput): MountedPreferences;
+
+export type { HomeConfig, HomeIcon, HomeItem, HomeLinkTarget, HomeState, Bridge, BridgeOptions, BridgeFactory } from "./home.mjs";

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 };
 }