@nsnanocat/preference-panes 1.1.0 → 1.1.2

package/dist/module/navigation.mjs

@@ -147,26 +147,8 @@ class ActionMenu {
 }
 
 /**
- * 统一解析模块页的资源地址：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.
- */
-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") ?? "";
-    if (!json.trim()) throw new TypeError("JSON resource URL is required");
-    return { url: url.href, module, json, css };
-}
-
-/**
- * 模块文档容器：原始 HTML 不改写，请求上下文随 iframe 元素传递。
- * Module document container: preserve HTML verbatim and carry request context on the iframe element.
+ * 模块文档容器：原始 HTML 不改写，只向 iframe 标记模块身份。
+ * Module document container: preserve HTML verbatim and mark only the module identity on the iframe.
  */
 class ModuleFrame extends EventTarget {
     #url;
@@ -188,23 +170,25 @@ class ModuleFrame extends EventTarget {
     };
 
     /**
-     * 建立 iframe 与请求输入；调用方挂载 element 后调用 load。
-     * Create the iframe and request inputs; callers mount element and then call load.
+     * 建立 iframe；调用方挂载 element 后调用 load。
+     * Create the iframe; callers mount element and then call load.
      * @param {string | URL} url 模块请求地址 / Module request URL.
-     * @param {RequestInit} [options] 原生请求头和取消信号 / Native headers and cancellation signal.
+     * @param {{signal?: AbortSignal}} [options] 外部取消信号 / External cancellation signal.
      */
     constructor(url, options = {}) {
         super();
         this.#url = new URL(url, document.baseURI);
-        this.#options = { ...options, headers: new Headers(options.headers) };
-        const inputs = pageInputs(this.#url, Object.fromEntries(this.#options.headers));
+        const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#url.pathname);
+        if (!match) throw new TypeError("Open a concrete module URL");
+        this.#options = options;
         this.element = document.createElement("iframe");
-        this.element.title = `${inputs.module} 设置`;
-        this.element.dataset.preferencePanes = JSON.stringify(inputs);
+        this.element.title = `${match[1]} 设置`;
+        this.element.dataset.preferencePanes = "true";
+        this.element.dataset.preferencePanesModule = match[1];
         this.element.addEventListener("preferencepanes:change", this.#change);
         this.element.addEventListener("preferencepanes:confirm", this.#confirmation);
         this.element.addEventListener("preferencepanes:notice", this.#notice);
-        this.#state = { title: inputs.module, module: inputs.module, busy: false, canGoBack: true, actions: [] };
+        this.#state = { title: match[1], module: match[1], busy: false, canGoBack: true, actions: [] };
         options.signal?.addEventListener("abort", this.#abort, { once: true });
     }
 
@@ -225,7 +209,7 @@ class ModuleFrame extends EventTarget {
         if (this.#options.signal?.aborted) this.destroy();
         const timer = setTimeout(() => this.#controller.abort(), 10000);
         try {
-            const response = await fetch(this.#url, { cache: "no-store", credentials: "omit", ...this.#options, signal: this.#controller.signal });
+            const response = await fetch(this.#url, { cache: "no-store", credentials: "omit", signal: this.#controller.signal });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
             const html = await response.text();
             this.#controller.signal.throwIfAborted();
@@ -275,7 +259,6 @@ class ModuleFrame extends EventTarget {
  * @typedef {object} ModuleProbeOptions
  * @property {typeof globalThis.fetch} [fetch] 可注入的 fetch / Injectable fetch.
  * @property {AbortSignal} [signal] 外部取消信号 / External cancellation signal.
- * @property {string} [json] BoxJS JSON 来源，将随探测请求头传递 / BoxJS JSON source sent in the probe header.
  * @property {number} [timeout] 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500.
  */
 
@@ -286,14 +269,14 @@ class ModuleFrame extends EventTarget {
  * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
  * @returns {Promise<Response>} 原始 HTTP 响应，可直接读取 status 和响应头 / Native HTTP response; read status and headers directly.
  */
-async function probeModule(url, { fetch: request = globalThis.fetch, json, signal, timeout = 3500 } = {}) {
+async function probeModule(url, { fetch: request = globalThis.fetch, signal, timeout = 3500 } = {}) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     if (signal?.aborted) abort();
     signal?.addEventListener("abort", abort, { once: true });
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal, headers: json ? { "X-PreferencePanes-JSON": json } : undefined });
+        return await request(url, { method: "HEAD", cache: "no-store", credentials: "omit", signal: controller.signal });
     } finally {
         clearTimeout(timer);
         signal?.removeEventListener("abort", abort);

package/dist/preference-panes.mjs

@@ -45,8 +45,8 @@ function normalizeBoxJs(config, module) {
             target.owners.add(app);
         }
     }
-    if (module === undefined && modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
-    const target = module === undefined ? modules.values().next().value : modules.get(module);
+    if (modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
+    const target = modules.values().next().value ;
     if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
     const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
@@ -428,28 +428,50 @@ class ActionMenu {
  */
 class PreferencesClient {
     #module;
-    #configURL;
     #definition;
     #request;
     #notify;
     #timeout;
     #session = new AbortController();
-    #values;
+    #values = {};
     #saving = false;
 
     /**
-     * 创建只调用模块 API、不读取或解析 BoxJS 的页面客户端。
-     * Create a page client that only calls the module API and never reads or parses BoxJS.
-     * @param {import("./client.mjs").PreferencesClientOptions} options API 模型、请求与通知 / API model, requests, and notifications.
+     * 创建从 BoxJS 定义读取和持久化设置的页面客户端。
+     * Create a page client that reads and persists settings from a BoxJS definition.
+     * @param {import("./client.mjs").PreferencesClientOptions} options 字段定义、请求与通知 / Field definition, requests, and notifications.
      */
-    constructor({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-        this.#module = model.module;
-        this.#configURL = model.configURL;
+    constructor({ definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
+        this.#module = definition.module;
         this.#definition = definition;
         this.#request = request;
         this.#notify = notify;
         this.#timeout = timeout;
-        this.#values = structuredClone(model.values);
+    }
+
+    /**
+     * 读取一次 Settings 子树并建立页面值快照。
+     * Read the Settings subtree once and establish the page value snapshot.
+     * @returns {Promise<import("./client.mjs").ModuleSnapshot>} 页面快照 / Page snapshot.
+     */
+    async open() {
+        let subtree = await this.readSettings();
+        if (subtree === undefined) subtree = {};
+        if (typeof subtree === "string") subtree = JSON.parse(subtree);
+        if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
+        const values = {};
+        for (const field of this.#definition.fields) {
+            const stored = field.key
+                .split(".")
+                .slice(this.#definition.settingsPath.length)
+                .reduce((parent, part) => Object(parent)[part], subtree);
+            const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
+            if (value === undefined) continue;
+            if (!validValue(field, value)) throw new TypeError(`Invalid stored value: ${field.key}`);
+            values[field.key] = value;
+        }
+        this.#values = values;
+        return this.snapshot();
     }
 
     /**
@@ -467,7 +489,7 @@ class PreferencesClient {
      * @returns {Promise<unknown>} Settings 内容或 undefined / Settings content or undefined.
      */
     async readSettings() {
-        const response = await this.#send("get", { scope: "settings" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#definition.settingsPath.join(".")}`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -477,7 +499,7 @@ class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", { scope: "caches" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -487,7 +509,7 @@ class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", { scope: "caches" }, "clearCaches");
+        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
     }
 
     /**
@@ -496,7 +518,7 @@ class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
-        return this.#change("delete", { scope: "module" }, "reset");
+        return this.#change("delete", this.#module, undefined, "reset");
     }
 
     /**
@@ -516,7 +538,7 @@ class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     set(key, value) {
-        return this.#change("set", { key, value }, "write", key);
+        return this.#change("set", key, value, "write");
     }
 
     /**
@@ -526,30 +548,31 @@ class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     remove(key) {
-        return this.#change("delete", { key }, "delete", key);
+        return this.#change("delete", key, undefined, "delete");
     }
 
     /**
-     * 向模块 API 发送 JSON 动作。
-     * Send a JSON action to the module API.
-     * @param {"get" | "set" | "delete"} action 模块动作 / Module action.
-     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * 向固定存储 API 发送完整路径的 form 动作。
+     * Send a complete-path form action to the fixed storage API.
+     * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+     * @param {string} path 完整 @root.path / Complete @root.path.
+     * @param {unknown} [value] set 写入值 / Value written by set.
      * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async #send(action, payload) {
+    async #send(action, path, value) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         if (this.#session.signal.aborted) abort();
         this.#session.signal.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, this.#timeout);
         try {
-            const response = await this.#request(`/api/${encodeURIComponent(this.#module)}/${action}`, {
+            const response = await this.#request(`/api/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": this.#configURL },
-                body: JSON.stringify(payload),
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(value) : ""]]).toString(),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
@@ -563,24 +586,28 @@ class PreferencesClient {
      * 执行写入动作；成功后只更新当前页面值。
      * Execute a mutation and update only the current page values after success.
      * @param {"set" | "delete"} action API 动作 / API action.
-     * @param {Record<string, unknown>} payload JSON 请求体 / JSON request body.
+     * @param {string} key 不含存储根的路径 / Path without the storage root.
+     * @param {unknown} value set 写入值 / Value written by set.
      * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
-     * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
-    async #change(action, payload, operation, key) {
+    async #change(action, key, value, operation) {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            await this.#send(action, payload);
+            let field;
+            if (operation === "write" || operation === "delete") {
+                field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
+            }
+            await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
             switch (operation) {
                 case "write":
-                    this.#values[key] = structuredClone(payload.value);
+                    this.#values[key] = structuredClone(value);
                     break;
                 case "delete": {
-                    const field = this.#definition.fields.find(candidate => candidate.key === key);
                     delete this.#values[key];
-                    if (field && Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
                     break;
                 }
                 case "clearCaches":
@@ -769,24 +796,23 @@ class PreferencesPanel {
     #release;
 
     /**
-     * 挂载 API 返回的模块模型表单。
-     * Mount the module form returned by the API.
+     * 挂载 BoxJS 定义对应的模块表单。
+     * Mount the module form described by a BoxJS definition.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      */
-    constructor(root, model) {
-        this.#release = this.#mount(root, model);
+    constructor(root, definition) {
+        this.#release = this.#mount(root, definition);
     }
 
     /**
      * 建立面板 DOM、交互和会话，并返回其释放操作。
      * Build panel DOM, interactions, and session, then return its release operation.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      * @returns {() => void} 释放操作 / Release operation.
      */
-    #mount(root, model) {
-        const { definition } = model;
+    #mount(root, definition) {
         const title = definition.metadata?.name ?? definition.module;
         const document = root.ownerDocument;
         const window = document.defaultView;
@@ -878,7 +904,7 @@ class PreferencesPanel {
                 toast.hidden = true;
             }, 2400);
         };
-        const client = new PreferencesClient({ model, definition, notify });
+        const client = new PreferencesClient({ definition, notify });
         /**
          * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
          * Share async error handling between both menus, including host-dialog errors.
@@ -906,6 +932,7 @@ class PreferencesPanel {
             publishNavigation();
             viewport.replaceChildren(statusView("读取设置…"));
             try {
+                await client.open();
                 if (version === generation) controls();
             } catch (error) {
                 if (version !== generation) return;
@@ -1294,15 +1321,14 @@ function installDefaultStyles(document) {
 }
 
 /**
- * 管理模块设置视图的模型规范化、样式、主题同步和面板生命周期。
- * Manage model normalization, styles, theme synchronization, and panel lifecycle for a module settings view.
+ * 管理 BoxJS 规范化、主题同步和面板生命周期。
+ * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
  */
 class PreferencesView {
     #existing;
     #root;
     #base;
     #ownsBase;
-    #custom;
     #previousTitle;
     #previousTheme;
     #systemTheme;
@@ -1312,22 +1338,12 @@ class PreferencesView {
     #panel;
 
     /**
-     * 使用模块 API 返回的模型挂载设置页。
-     * Mount a settings page from the model returned by the module API.
-     * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
-     * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
+     * 使用原始 BoxJS JSON 挂载设置页。
+     * Mount a settings page from raw BoxJS JSON.
+     * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
      */
-    constructor(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}`);
-        }
-        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 };
+    constructor(boxjs) {
+        const definition = normalizeBoxJs(boxjs);
         const metadata = definition.metadata ?? {};
         const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
         if (image) resourceURL(image);
@@ -1342,9 +1358,6 @@ class PreferencesView {
         const styles = installDefaultStyles(document);
         this.#base = styles.element;
         this.#ownsBase = styles.owned;
-        this.#custom = element("style", "");
-        this.#custom.textContent = css;
-        document.head.append(this.#custom);
         this.#previousTitle = document.title;
         this.#previousTheme = document.documentElement.dataset.theme;
         this.#systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
@@ -1359,7 +1372,7 @@ class PreferencesView {
         document.title = metadata.name ?? definition.module;
         try {
             this.#root.replaceChildren();
-            this.#panel = new PreferencesPanel(this.#root, rendered);
+            this.#panel = new PreferencesPanel(this.#root, definition);
         } catch (error) {
             this.destroy();
             throw error;
@@ -1387,7 +1400,6 @@ class PreferencesView {
         this.#systemTheme.removeEventListener("change", this.#syncAppearance);
         this.#panel?.destroy();
         if (this.#ownsBase) this.#base.remove();
-        this.#custom.remove();
         if (this.#existing) this.#root.replaceChildren();
         else this.#root.remove();
         document.title = this.#previousTitle;
@@ -1398,14 +1410,13 @@ class PreferencesView {
 }
 
 /**
- * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
- * Mount a settings page from a module API model; CSS only overrides this module.
- * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
- * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
- * @returns {PreferencesView} 模块视图 / Module view.
+ * 使用原始 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.
  */
-function mount(model, css = "") {
-    return new PreferencesView(model, css);
+function mount(boxjs) {
+    return new PreferencesView(boxjs);
 }
 
-export { PreferencesView, mount };
+export { mount };