@nsnanocat/preference-panes 0.7.0 → 0.7.2

package/src/browser/Navigation.mjs

@@ -0,0 +1,160 @@
+export { ModuleFrame } from "./ModuleFrame.mjs";
+
+/**
+ * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
+ * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
+ */
+export class Navigation extends EventTarget {
+    #container;
+    #home;
+    #create;
+    #window;
+    #key = null;
+    #view;
+    #retiring;
+    #controller;
+    #animation;
+    #scroll = new WeakMap();
+    #onHistory = () => this.#route();
+    #onPageShow = event => {
+        if (event.persisted) this.#route(true);
+    };
+
+    /**
+     * 根视图始终保留；工厂按需提供子页，可用 signal 取消离开后的异步加载。
+     * Retain the home view and create details on demand; signal cancels async work after departure.
+     * @param {HTMLElement} container 由调用方布局的页面容器 / Caller-styled view container.
+     * @param {HTMLElement} home 已创建的主页节点 / Existing home view.
+     * @param {(key: string, signal: AbortSignal) => HTMLElement | undefined} create 子页工厂；未知路径返回 undefined / Detail factory; undefined for unknown routes.
+     */
+    constructor(container, home, create) {
+        super();
+        this.#container = container;
+        this.#home = home;
+        this.#create = create;
+        this.#window = container.ownerDocument.defaultView;
+        container.replaceChildren(home);
+        this.#window.addEventListener("popstate", this.#onHistory);
+        this.#window.addEventListener("hashchange", this.#onHistory);
+        this.#window.addEventListener("pageshow", this.#onPageShow);
+        this.#route();
+    }
+
+    /**
+     * 当前子页键；空字符串表示主页。
+     * Current detail key; empty means home.
+     */
+    get current() {
+        return this.#key;
+    }
+
+    /**
+     * 是否可以返回上一级或先前文档。
+     * Whether a parent view or previous document is available.
+     */
+    get canGoBack() {
+        return Boolean(this.#key) || this.#window.history.length > 1;
+    }
+
+    /**
+     * 加入子页历史；使用文档自身 URL，避免 srcdoc 按宿主 base URL 跳转。
+     * Push a detail using the document URL, avoiding srcdoc navigation against the host base URL.
+     * @param {string} key 子页键 / Detail key.
+     * @returns {void} 无返回值 / No return value.
+     */
+    open(key) {
+        if (key === this.#key) return;
+        const url = new URL(this.#window.location.href);
+        url.hash = encodeURIComponent(key);
+        this.#window.history.pushState({ ...this.#window.history.state, preferencePanesRoute: key }, "", url.href);
+        this.#route();
+    }
+
+    /**
+     * 沿浏览器联合历史返回，根页可退回宿主或上个文档。
+     * Go back through joint history, including a host or previous document from home.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (this.canGoBack) this.#window.history.back();
+    }
+
+    /**
+     * 解析 URL 并统一处理页面切换、加载取消与动画结束后的释放。
+     * Resolve the URL and coordinate transitions, cancellation and release after animation.
+     * @param {boolean} [reload] 从页面缓存恢复时重新创建子页 / Recreate a detail after bfcache restoration.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #route(reload = false) {
+        const url = new URL(this.#window.location.href);
+        let key;
+        try {
+            key = decodeURIComponent(url.hash.slice(1));
+        } catch (error) {
+            if (!(error instanceof URIError)) throw error;
+            key = "";
+        }
+        if (!reload && key === this.#key) return;
+        this.#controller?.abort();
+        this.#controller = new AbortController();
+        const next = key ? this.#create(key, this.#controller.signal) : undefined;
+        if (!next) key = "";
+        const history = this.#window.history;
+        // 直接打开子页时建立一次主页历史；刷新不重复堆叠。
+        // Seed home history once for direct details, without stacking entries on reload.
+        if (url.hash && history.state?.preferencePanesRoute !== key) {
+            url.hash = "";
+            history.replaceState({ ...history.state, preferencePanesRoute: "" }, "", url.href);
+            if (key) {
+                url.hash = encodeURIComponent(key);
+                history.pushState({ ...history.state, preferencePanesRoute: key }, "", url.href);
+            }
+        }
+        const previous = this.#view;
+        const position = previous ? this.#window.getComputedStyle(previous).transform : "none";
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#retiring = previous;
+        if (previous) {
+            this.#scroll.set(previous, previous.scrollTop);
+            previous.inert = true;
+        }
+        this.#key = key;
+        this.#view = next;
+        this.#home.inert = Boolean(next);
+        if (next) {
+            next.inert = false;
+            this.#container.append(next);
+            next.scrollTop = this.#scroll.get(next) ?? 0;
+        }
+        const moving = next ?? previous;
+        if (moving) {
+            const animation = moving.animate([{ transform: next ? "translateX(100%)" : position }, { transform: next ? "translateX(0)" : "translateX(100%)" }], { duration: this.#window.matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : 280, easing: "cubic-bezier(.22,.61,.36,1)", fill: "forwards" });
+            this.#animation = animation;
+            animation.onfinish = () => {
+                if (this.#animation !== animation) return;
+                this.#retiring?.remove();
+                this.#retiring = undefined;
+                animation.cancel();
+                this.#animation = undefined;
+            };
+        }
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放监听器、加载、动画和节点；调用方可重新创建导航。
+     * Release listeners, loads, animations and nodes so callers can recreate navigation.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#window.removeEventListener("popstate", this.#onHistory);
+        this.#window.removeEventListener("hashchange", this.#onHistory);
+        this.#window.removeEventListener("pageshow", this.#onPageShow);
+        this.#controller?.abort();
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#view?.remove();
+        this.#home.remove();
+    }
+}

package/src/browser/app.mjs

@@ -1,25 +1,43 @@
 import { BoxJS } from "../BoxJS.mjs";
+import { pageInputs } from "../lib/page-inputs.mjs";
 import { errorView } from "./components.mjs";
 import { mount } from "./index.mjs";
 
 let view;
 /**
- * 在具体模块地址导入 JSON 与 CSS，再交给模块渲染器。
- * Import JSON and CSS at a concrete module URL and pass them to the module renderer.
+ * 从 URL 或代理传递的 Header 导入 JSON/CSS，支持独立文档与 srcdoc。
+ * Import JSON/CSS from the URL or proxy-carried headers in standalone and srcdoc documents.
  * @returns {Promise<void>} 启动完成 / Startup completion.
  */
 async function start() {
     try {
         view?.destroy();
         view = undefined;
-        const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(location.pathname);
-        if (!match) throw new Error("Open a concrete module URL");
-        const module = match[1];
-        const [data, style] = await Promise.all([fetch(`/configs/${module}`, { cache: "no-store" }), fetch(`/settings/assets/${module}.css`, { cache: "no-store" })]);
-        if (data.status !== 200 || style.status !== 200) throw new Error(`HTTP ${data.status !== 200 ? data.status : style.status}`);
+        const context = document.querySelector('meta[name="preference-panes-inputs"]');
+        const embedded = window.frameElement?.dataset.preferencePanes;
+        let inputs;
+        switch (true) {
+            case embedded !== undefined:
+                inputs = JSON.parse(embedded);
+                document.documentElement.dataset.preferencePanesEmbedded = "";
+                break;
+            case context !== null:
+                inputs = JSON.parse(decodeURIComponent(context.content));
+                break;
+            default:
+                inputs = pageInputs(new URL(location.href));
+        }
+        const resources = [inputs.json, inputs.css].map(source => {
+            if (!source) return null;
+            const url = new URL(source, inputs.url);
+            if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
+            return url.href;
+        });
+        const [data, style] = await Promise.all(resources.map(url => (url ? fetch(url, { cache: "no-store", credentials: "omit" }) : null)));
+        if (data.status !== 200 || (style && style.status !== 200)) throw new Error(`HTTP ${data.status !== 200 ? data.status : style.status}`);
         const boxjs = await data.json();
-        if (new BoxJS(boxjs).module.module !== module) throw new Error("Imported JSON does not match the module URL");
-        view = mount(boxjs, await style.text());
+        if (new BoxJS(boxjs).module.module !== inputs.module) throw new Error("Imported JSON does not match the module URL");
+        view = mount(boxjs, style ? await style.text() : "");
     } catch (error) {
         document.querySelector("#preferences").replaceChildren(errorView(error, start));
     }

package/src/browser/components.mjs

@@ -21,7 +21,7 @@ export function element(tag, className, text) {
  * @returns {string} 完整地址 / Absolute address.
  */
 export function resourceURL(value) {
-    const url = new URL(value, location.href);
+    const url = new URL(value, document.baseURI);
     if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Metadata URLs must use HTTP(S)");
     return url.href;
 }

package/src/browser/panel.css

@@ -28,7 +28,9 @@
     align-items: center;
     background: var(--pp-surface);
     border-bottom: 1px solid var(--pp-border);
-    position: relative;
+    position: sticky;
+    top: 0;
+    z-index: 1;
 }
 .pp-title {
     font-size: 17px;
@@ -37,10 +39,30 @@
     min-width: 0;
     overflow-wrap: anywhere;
 }
-.pp-header .pp-title {
+.pp-brand {
     flex: 1;
+    min-width: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
     text-align: center;
 }
+.pp-brand-icon {
+    display: none;
+    flex: none;
+    width: 28px;
+    height: 28px;
+}
+.pp-brand-icon:not(:empty) {
+    display: block;
+}
+.pp-brand-icon img {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
 .pp-nav-spacer {
     width: 44px;
     flex: none;
@@ -69,10 +91,19 @@
     height: calc(100vh - 52px - env(safe-area-inset-top));
     overflow: hidden;
 }
+:root[data-preference-panes-embedded] .pp-header {
+    display: none;
+}
+:root[data-preference-panes-embedded] .pp-viewport {
+    height: 100vh;
+}
 @supports (height: 100dvh) {
     .pp-viewport {
         height: calc(100dvh - 52px - env(safe-area-inset-top));
     }
+    :root[data-preference-panes-embedded] .pp-viewport {
+        height: 100dvh;
+    }
 }
 .pp-fields,
 .pp-choice-page {

package/src/browser/panel.mjs

@@ -1,5 +1,6 @@
 import { createPreferencesClient } from "./client.mjs";
 import { errorView, icon, element as node, resourceURL } from "./components.mjs";
+import { Navigation } from "./Navigation.mjs";
 
 /**
  * 挂载已导入 BoxJS 对应的模块表单和短暂通知。
@@ -13,20 +14,38 @@ export function mountPanel(root, catalog) {
     const document = root.ownerDocument;
     const window = document.defaultView;
     const shell = node("div", "pp-panel");
+    shell.dataset.module = catalog.module.module;
     const header = node("header", "pp-header");
     const back = node("button", "pp-back", "‹");
     back.setAttribute("aria-label", "返回");
     back.type = "button";
     const heading = node("h1", "pp-title", title);
+    const brand = node("div", "pp-brand");
+    const logo = node("span", "pp-brand-icon");
+    logo.setAttribute("aria-hidden", "true");
+    const image = icon(catalog.module.metadata, "");
+    if (image) logo.append(image);
+    brand.append(logo, heading);
     const viewport = node("div", "pp-viewport");
     const toast = node("div", "pp-toast");
     toast.setAttribute("role", "status");
     toast.hidden = true;
-    header.append(back, heading, node("span", "pp-nav-spacer"));
+    header.append(back, brand, node("span", "pp-nav-spacer"));
     shell.append(header, viewport, toast);
     root.append(shell);
+    // 嵌入模式向宿主发布导航状态，宿主不读取或修改模块内部 DOM。
+    // Embedded mode publishes navigation state without host reads or mutations of the module DOM.
+    const publishNavigation = () => {
+        const frame = window.frameElement;
+        if (!frame?.dataset.preferencePanes) return;
+        frame.dispatchEvent(
+            new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:change", {
+                detail: { title: heading.textContent, module: catalog.module.module, busy: saving, canGoBack: !back.disabled },
+            }),
+        );
+    };
     let timer,
-        secondaryRoute,
+        navigation,
         generation = 0,
         active = null,
         saving = false,
@@ -64,25 +83,6 @@ export function mountPanel(root, catalog) {
         }, 2400);
     };
     const client = createPreferencesClient({ catalog, notify });
-    /**
-     * 切换加载或错误视图，按用户的动态效果偏好播放过渡。
-     * Replace a loading or error view, respecting reduced-motion preferences.
-     * @param {HTMLElement} view 新视图 / New view.
-     * @param {number} direction 过渡方向，正数从右侧进入 / Transition direction; positive enters from the right.
-     * @returns {void} 无返回值 / No return value.
-     */
-    function replace(view, direction) {
-        const old = viewport.firstElementChild;
-        viewport.replaceChildren(view);
-        if (old && !window.matchMedia("(prefers-reduced-motion: reduce)").matches)
-            view.animate(
-                [
-                    { opacity: 0.4, transform: `translateX(${direction * 24}px)` },
-                    { opacity: 1, transform: "translateX(0)" },
-                ],
-                { duration: 180, easing: "ease-out" },
-            );
-    }
     /**
      * 打开模块并忽略已过期的异步结果。
      * Open a module and ignore stale asynchronous results.
@@ -94,16 +94,15 @@ export function mountPanel(root, catalog) {
         active = module;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
-        replace(node("p", "pp-loading", "读取设置…"), 1);
+        publishNavigation();
+        viewport.replaceChildren(node("p", "pp-loading", "读取设置…"));
         try {
             await client.open(module);
             if (version === generation) controls();
         } catch (error) {
             if (version !== generation) return;
-            replace(
-                errorView(error, () => open(module)),
-                1,
-            );
+            viewport.replaceChildren(errorView(error, () => open(module)));
+            publishNavigation();
         }
     }
     /**
@@ -124,37 +123,19 @@ export function mountPanel(root, catalog) {
         const editors = new Map();
         const summaries = [];
         const groups = new Map();
-        const scrollPositions = new WeakMap();
-        let activeEditor;
         let queue = Promise.resolve(),
             pendingWrites = 0;
         /**
-         * 根据 hash 切换多选页，保留上级 DOM 和滚动位置。
-         * Switch multi-select views by hash while retaining parent DOM and scroll position.
+         * 导航组件处理页面切换，表单只更新当前标题与返回按钮。
+         * Let navigation own transitions; the form only updates the title and back button.
          * @returns {void} 无返回值 / No return value.
          */
-        const showEditor = () => {
-            let key;
-            try {
-                key = decodeURIComponent(window.location.hash.slice(1));
-            } catch {
-                key = "";
-            }
-            const editor = editors.get(key);
-            const previous = activeEditor?.node ?? view;
-            const next = editor?.node ?? view;
-            if (previous !== next) {
-                scrollPositions.set(previous, previous.scrollTop);
-                previous.remove();
-                viewport.append(next);
-                next.scrollTop = scrollPositions.get(next) ?? 0;
-                if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) next.animate([{ transform: `translateX(${editor ? 100 : -100}%)` }, { transform: "translateX(0)" }], { duration: 260, easing: "cubic-bezier(.22,.61,.36,1)" });
-            }
-            activeEditor = editor;
+        const updateNavigation = () => {
+            const editor = editors.get(navigation.current);
             heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
-            back.disabled = saving || (!editor && window.history.length <= 1);
+            back.disabled = saving || !navigation.canGoBack;
+            publishNavigation();
         };
-        secondaryRoute = showEditor;
         /**
          * 串行执行模块操作，保持输入可编辑。
          * Serialize module actions while keeping inputs editable.
@@ -167,6 +148,7 @@ export function mountPanel(root, catalog) {
             pendingWrites++;
             saving = true;
             back.disabled = true;
+            publishNavigation();
             return (queue = queue
                 .then(action)
                 .then(() => {
@@ -181,7 +163,8 @@ export function mountPanel(root, catalog) {
                     pendingWrites--;
                     saving = pendingWrites > 0;
                     if (destroyed && !saving) client.leave(active);
-                    back.disabled = saving || (!activeEditor && window.history.length <= 1);
+                    back.disabled = saving || !navigation.canGoBack;
+                    publishNavigation();
                 }));
         }
         const metadata = definition.metadata;
@@ -270,10 +253,7 @@ export function mountPanel(root, catalog) {
                     };
                     summaries.push(refresh);
                     refresh();
-                    link.onclick = () => {
-                        window.history.pushState({ ...window.history.state, preferencePane: active }, "", `#${encodeURIComponent(field.key)}`);
-                        showEditor();
-                    };
+                    link.onclick = () => navigation.open(field.key);
                     row.addEventListener("click", event => {
                         if (!link.contains(event.target)) link.click();
                     });
@@ -420,26 +400,22 @@ export function mountPanel(root, catalog) {
         actions.append(cacheView, cacheClear, reset);
         maintenance.append(actions, output);
         view.append(maintenance);
-        viewport.replaceChildren(view);
+        navigation?.destroy();
+        navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
+        navigation.addEventListener("change", updateNavigation);
         for (const grow of growingInputs) grow();
-        showEditor();
+        updateNavigation();
     }
     /**
-     * 历史导航只切换当前模块的二级页，不接管项目主页或跨模块路由。
-     * History navigation switches only this module's subpages, never project or cross-module routes.
+     * 已加载的表单交由导航组件返回；加载阶段可以返回先前文档。
+     * Loaded forms delegate back to navigation; loading views can return to the previous document.
      * @returns {void} 无返回值 / No return value.
      */
-    const onPopState = () => secondaryRoute?.();
-    const onHashChange = () => secondaryRoute?.();
     back.onclick = () => {
         if (saving) return;
-        if (window.location.hash && window.history.state?.preferencePane !== active) {
-            window.history.replaceState(window.history.state, "", window.location.pathname);
-            secondaryRoute?.();
-        } else window.history.back();
+        if (navigation) navigation.back();
+        else window.history.back();
     };
-    window.addEventListener("popstate", onPopState);
-    window.addEventListener("hashchange", onHashChange);
     open(catalog.module.module);
     return {
         /**
@@ -449,8 +425,7 @@ export function mountPanel(root, catalog) {
          */
         destroy() {
             destroyed = true;
-            window.removeEventListener("popstate", onPopState);
-            window.removeEventListener("hashchange", onHashChange);
+            navigation?.destroy();
             generation++;
             if (active && !saving) client.leave(active);
             clearTimeout(timer);

package/src/build.mjs

@@ -12,9 +12,10 @@ export async function build(boxjs, css = "") {
     if (typeof css !== "string") throw new TypeError("CSS must be a string");
     const catalog = new BoxJS(boxjs);
     const module = catalog.module.module;
-    const [html, app, proxy, mock] = await Promise.all([
+    const [html, app, navigation, proxy, mock] = await Promise.all([
         readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"),
         readFile(new URL("../dist/module/app.mjs", import.meta.url), "utf8"),
+        readFile(new URL("../dist/module/navigation.mjs", import.meta.url), "utf8"),
         readFile(new URL("../dist/preference-panes.proxy.js", import.meta.url), "utf8"),
         readFile(new URL("../dist/preference-panes.config.js", import.meta.url), "utf8"),
     ]);
@@ -23,6 +24,7 @@ export async function build(boxjs, css = "") {
         [`settings/${module}/index.html`]: html,
         [`settings/assets/${module}.html`]: html,
         "settings/assets/app.mjs": app,
+        "settings/assets/navigation.mjs": navigation,
         [`settings/assets/${module}.boxjs.json`]: config,
         [`settings/assets/${module}.css`]: css,
         [`settings/assets/${module}.request.js`]: `${proxy}\nPreferencePanes.run(${config},${JSON.stringify(css)});\n`,

package/src/lib/page-inputs.mjs

@@ -0,0 +1,17 @@
+/**
+ * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
+ * Resolve module resource locations: headers override query parameters and module conventions.
+ * @param {URL} url 已解析的页面请求地址 / Parsed page request URL.
+ * @param {Record<string, string | undefined>} [headers] 请求头，名称不区分大小写 / Case-insensitive request headers.
+ * @returns {{url: string, module: string, json: string, css: string}} 页面上下文与两个资源输入 / Page context and two resource inputs.
+ */
+export function pageInputs(url, headers = {}) {
+    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname);
+    if (!match) throw new TypeError("Open a concrete module URL");
+    const module = match[1];
+    const values = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+    const json = values["x-preferencepanes-json"] ?? url.searchParams.get("json") ?? `/configs/${module}`;
+    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? `/settings/assets/${module}.css`;
+    if (!json.trim()) throw new TypeError("JSON resource URL is required");
+    return { url: url.href, module, json, css };
+}

package/src/proxy/handler.mjs

@@ -1,6 +1,7 @@
 import { URL } from "@nsnanocat/url";
 import assets from "#assets";
 import { BoxJS } from "../BoxJS.mjs";
+import { pageInputs } from "../lib/page-inputs.mjs";
 import { response } from "../lib/response.mjs";
 import { Store } from "../Store.mjs";
 import { complete } from "./response.mjs";
@@ -26,12 +27,19 @@ export async function run(boxjs, css = "") {
                 break;
             case url.pathname.startsWith("/configs/"):
                 break;
+            case url.pathname === `/settings/${module}` || url.pathname === `/settings/${module}/`: {
+                // Header 由代理传入文档，浏览器再下载 JSON/CSS；代理不获取外部资源。
+                // Carry headers into the document; only the browser downloads external JSON/CSS.
+                const inputs = encodeURIComponent(JSON.stringify(pageInputs(url, request.headers)));
+                const html = assets.page.body.replace("</head>", `<meta name="preference-panes-inputs" content="${inputs}"></head>`);
+                result = response(request, 200, html, "text/html");
+                break;
+            }
             case url.pathname === `/settings/assets/${module}.css`:
                 result = response(request, 200, css, "text/css");
                 break;
             default: {
-                const path = url.pathname === `/settings/${module}` || url.pathname === `/settings/${module}/` ? "page" : url.pathname;
-                const asset = assets[path];
+                const asset = assets[url.pathname];
                 if (asset) result = response(request, 200, asset.body, asset.type);
             }
         }