@nsnanocat/preference-panes 0.7.0 → 0.7.1

package/src/browser/app.mjs

@@ -1,25 +1,31 @@
 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 inputs = context ? JSON.parse(decodeURIComponent(context.content)) : 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;

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,27 @@ 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);
     let timer,
-        secondaryRoute,
+        navigation,
         generation = 0,
         active = null,
         saving = false,
@@ -64,25 +72,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 +83,13 @@ export function mountPanel(root, catalog) {
         active = module;
         back.disabled = window.history.length <= 1;
         heading.textContent = module;
-        replace(node("p", "pp-loading", "读取设置…"), 1);
+        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)));
         }
     }
     /**
@@ -124,37 +110,18 @@ 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;
         };
-        secondaryRoute = showEditor;
         /**
          * 串行执行模块操作，保持输入可编辑。
          * Serialize module actions while keeping inputs editable.
@@ -181,7 +148,7 @@ 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;
                 }));
         }
         const metadata = definition.metadata;
@@ -270,10 +237,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 +384,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 +409,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);
             }
         }