@nsnanocat/preference-panes 1.0.0 → 1.1.1

package/src/browser/index.mjs

@@ -1,90 +1,70 @@
-import { normalizeBoxJs, normalizeStoredValue, validValue } from "./boxjs.mjs";
-import { element, resourceURL } from "./components.mjs";
-import { mountPanel } from "./panel.mjs";
+import { statusView } from "./components.mjs";
+import { mount } from "./mount.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
- * 挂载模块设置页；默认样式由包提供，可选 CSS 仅作用于当前模块。
- * Mount a module page with package defaults and optional module-scoped CSS.
- * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
- * @param {string} [css] 可选 CSS 正文 / Optional CSS text.
- * @returns {import("./index.js").MountedPreferences} 模块生命周期句柄 / Module lifecycle handle.
+ * 管理模块文档的配置请求、重载和错误状态。
+ * Manage configuration requests, reloads, and error states for a module document.
  */
-export function mount(model, css = "") {
-    if (typeof css !== "string") throw new TypeError("CSS must be a string");
-    const definition = normalizeBoxJs(model.boxjs, model.module);
-    const values = { ...model.values };
-    for (const field of definition.fields) {
-        if (values[field.key] === undefined) continue;
-        values[field.key] = normalizeStoredValue(field, values[field.key]);
-        if (!validValue(field, values[field.key])) throw new TypeError(`Invalid stored value: ${field.key}`);
+class ModulePage {
+    #window;
+    #root;
+    #view;
+
+    /**
+     * 创建模块页面控制器并安装基础样式。
+     * Create the module page controller and install base styles.
+     * @param {Document} document 模块文档 / Module document.
+     */
+    constructor(document) {
+        this.#window = document.defaultView;
+        this.#root = document.querySelector("#preferences");
+        installDefaultStyles(document);
+        this.#window.addEventListener("pageshow", this.#show);
     }
-    for (const field of definition.fields) if (values[field.key] === undefined && Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
-    const rendered = { ...model, definition, values };
-    const metadata = definition.metadata ?? {};
-    const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
-    if (image) resourceURL(image);
-    if (metadata.repo) resourceURL(metadata.repo);
-    const existing = document.querySelector("#preferences");
-    const root = existing ?? element("main", "");
-    if (!existing) {
-        root.id = "preferences";
-        document.body.append(root);
+
+    /**
+     * 从规范模块路径读取 BoxJS JSON 并挂载通用前端。
+     * Read BoxJS JSON from the conventional module path and mount the generic frontend.
+     * @returns {Promise<void>} 启动完成 / Startup completion.
+     */
+    async start() {
+        try {
+            this.#view?.destroy();
+            this.#view = undefined;
+            this.#root.replaceChildren(statusView("读取设置…"));
+            const embedded = this.#window.frameElement?.dataset.preferencePanesModule;
+            const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#window.location.pathname);
+            const module = embedded ?? match?.[1];
+            if (!module) throw new TypeError("Open a concrete module URL");
+            const response = await fetch(`/configs/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            this.#view = mount(await response.json());
+        } catch (error) {
+            this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
+        }
     }
-    const { element: base, owned: ownsBase } = installDefaultStyles(document);
-    const custom = element("style", "");
-    custom.textContent = css;
-    document.head.append(custom);
-    const previousTitle = document.title;
-    const previousTheme = document.documentElement.dataset.theme;
-    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.
+     * 释放页面视图和页面级监听器。
+     * Release the page view and page-level listener.
+     * @returns {void} 无返回值 / No return value.
      */
-    const syncAppearance = () => {
-        const theme = host?.dataset.theme ?? previousTheme ?? (systemTheme.matches ? "dark" : "light");
-        document.documentElement.dataset.theme = theme;
-        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"] });
+    destroy() {
+        this.#window.removeEventListener("pageshow", this.#show);
+        this.#view?.destroy();
+        this.#view = undefined;
     }
-    document.title = metadata.name ?? definition.module;
-    let panel;
-    const view = {
-        /**
-         * 释放模块视图、样式与会话，不操作项目入口页。
-         * Release the module view, styles and session without operating a project landing page.
-         * @returns {void} 无返回值 / No return value.
-         */
-        destroy() {
-            observer?.disconnect();
-            systemTheme.removeEventListener("change", syncAppearance);
-            panel?.destroy();
-            if (ownsBase) base.remove();
-            custom.remove();
-            if (existing) root.replaceChildren();
-            else root.remove();
-            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);
-        },
+
+    /**
+     * 从前进后退缓存恢复时重新加载模块。
+     * Reload the module when restored from the back-forward cache.
+     * @param {PageTransitionEvent} event 页面显示事件 / Page show event.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #show = event => {
+        if (event.persisted) this.start();
     };
-    try {
-        root.replaceChildren();
-        panel = mountPanel(root, rendered);
-        return view;
-    } catch (error) {
-        view.destroy();
-        throw error;
-    }
 }
+
+new ModulePage(document).start();

package/src/browser/module.html

@@ -9,6 +9,6 @@
     </head>
     <body>
         <main id="preferences"></main>
-        <script type="module" src="/settings/assets/app.mjs?v=__VERSION__"></script>
+        <script type="module" src="/settings/assets/index.mjs?v=__VERSION__"></script>
     </body>
 </html>

package/src/browser/mount.mjs

@@ -0,0 +1,103 @@
+import { normalizeBoxJs } from "./boxjs.mjs";
+import { element, resourceURL } from "./components.mjs";
+import { PreferencesPanel } from "./panel.mjs";
+import { installDefaultStyles } from "./styles.mjs";
+
+/**
+ * 管理 BoxJS 规范化、主题同步和面板生命周期。
+ * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
+ */
+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;
+        }
+    }
+
+    /**
+     * 跟随嵌入宿主的通用环境状态，不识别业务 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"));
+    };
+
+    /**
+     * 释放模块视图、样式与会话，不操作项目入口页。
+     * Release the module view, styles, and session without operating a project landing page.
+     * @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);
+    }
+}
+
+/**
+ * 使用原始 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);
+}