@nsnanocat/preference-panes 1.0.0 → 1.1.1

package/src/api.mjs

@@ -41,31 +41,21 @@ class API {
         const match = /^\/api\/([a-zA-Z0-9_-]+)(?:\/(get|set|delete))?\/?$/.exec(url.pathname);
         if (!match) return;
         const [, module, action] = match;
-        const configURL = this.#configURL(request, url, module);
+        const configuration = `${url.origin}/configs/${module}`;
         switch (true) {
             case !action && request.method === "HEAD":
-                return this.#probe(request, configURL);
-            case !action && request.method === "GET":
-                return this.#model(request, module, configURL);
+                return this.#probe(request, configuration);
             case Boolean(action) && request.method === "POST":
-                return this.#action(request, module, action, configURL);
+                return this.#action(request, module, action, configuration);
             default:
-                return this.#response(request, 405, { error: "Use GET or HEAD for module reads, POST for module actions" });
+                return this.#response(request, 405, { error: "Use HEAD for module probes and POST for module actions" });
         }
     }
 
-    #configURL(request, url, module) {
-        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        const source = headers["x-preferencepanes-json"] ?? `/configs/${module}`;
-        if (/^https?:\/\//i.test(source)) return source;
-        if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(source)) throw Object.assign(new TypeError("BoxJS resources must use HTTP(S) URLs"), { status: 400 });
-        return `${url.origin}/${source.replace(/^\/+/, "")}`;
-    }
-
-    async #probe(request, configURL) {
+    async #probe(request, configuration) {
         let result;
         try {
-            result = await transport({ url: configURL, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+            result = await transport({ url: configuration, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
         } catch (error) {
             return this.#response(request, 502, { error: error.message });
         }
@@ -73,19 +63,9 @@ class API {
         return this.#response(request, result.statusCode ?? result.status, undefined, version ? { "X-PreferencePanes-Version": version } : {});
     }
 
-    async #model(request, module, configURL) {
-        const loaded = await this.#load(module, configURL);
-        const values = {};
-        for (const entry of loaded.entries) {
-            const value = Storage.getItem(entry.id, MISSING);
-            if (value !== MISSING) values[entry.id.slice(loaded.storageKey.length + 2)] = value;
-        }
-        return this.#response(request, 200, { module, boxjs: loaded.boxjs, values, configURL }, loaded.version ? { "X-PreferencePanes-Version": loaded.version } : {});
-    }
-
-    async #action(request, module, action, configURL) {
+    async #action(request, module, action, configuration) {
         const payload = this.#jsonBody(request);
-        const target = await this.#load(module, configURL);
+        const target = await this.#load(module, configuration);
         switch (action) {
             case "get": {
                 const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
@@ -103,10 +83,10 @@ class API {
         }
     }
 
-    async #load(module, configURL) {
+    async #load(module, configuration) {
         let result;
         try {
-            result = await transport({ url: configURL, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
+            result = await transport({ url: configuration, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
         } catch (error) {
             throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
         }
@@ -137,7 +117,7 @@ class API {
                 }
             }
             if (!entries.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-            return { boxjs, entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
+            return { entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
         } catch (error) {
             throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
         }

package/src/browser/ModuleFrame.mjs

@@ -1,8 +1,6 @@
-import { pageInputs } from "../lib/page-inputs.mjs";
-
 /**
- * 模块文档容器：原始 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.
  */
 export class ModuleFrame extends EventTarget {
     #url;
@@ -24,23 +22,25 @@ export 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 });
     }
 
@@ -61,7 +61,7 @@ export 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();

package/src/browser/ModuleStatus.mjs

@@ -4,7 +4,6 @@
  * @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.
  */
 
@@ -15,14 +14,14 @@
  * @param {ModuleProbeOptions} [options] 请求选项 / Request options.
  * @returns {Promise<Response>} 原始 HTTP 响应，可直接读取 status 和响应头 / Native HTTP response; read status and headers directly.
  */
-export async function probeModule(url, { fetch: request = globalThis.fetch, json, signal, timeout = 3500 } = {}) {
+export 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/src/browser/Navigation.d.mts

@@ -11,9 +11,9 @@ export class ModuleFrame extends EventTarget {
      * 创建容器。
      * Create a container.
      * @param url 模块地址 / Module URL.
-     * @param options 原生请求参数 / Native request options.
+     * @param options 外部取消选项 / External cancellation options.
      */
-    constructor(url: string | URL, options?: RequestInit);
+    constructor(url: string | URL, options?: { signal?: AbortSignal });
     /**
      * 宿主挂载节点。
      * Host-mounted element.
@@ -169,8 +169,6 @@ export interface ModuleProbeOptions {
     fetch?: typeof globalThis.fetch;
     /** 外部取消信号 / External cancellation signal. */
     signal?: AbortSignal;
-    /** 传给模块 API 的 BoxJS JSON 来源 / BoxJS JSON source sent to the module API. */
-    json?: string;
     /** 超时毫秒数，默认 3500 / Timeout in milliseconds, defaults to 3500. */
     timeout?: number;
 }

package/src/browser/client.d.mts

@@ -1,4 +1,4 @@
-import type { ModuleDefinition, ModuleModel, SettingsScalar } from "../index.js";
+import type { ModuleDefinition, SettingsScalar } from "../index.js";
 /**
  * 单键写入或删除的通知事件。
  * Notification for a single-key write or delete.
@@ -16,12 +16,10 @@ export interface Notification {
     message?: string;
 }
 /**
- * 浏览器页面客户端选项；模型由 API 提供。
- * Browser page client options; the model is supplied by the API.
+ * 浏览器页面客户端选项；字段定义来自 BoxJS。
+ * Browser page client options; the field definition comes from BoxJS.
  */
 export interface PreferencesClientOptions {
-    /** API 返回的模块模型 / Module model returned by the API. */
-    model: ModuleModel;
     /** 用于渲染的归一化字段定义 / Normalized field definition for rendering. */
     definition: ModuleDefinition;
     /** 默认使用浏览器 fetch / Defaults to browser fetch. */
@@ -42,10 +40,14 @@ export interface ModuleSnapshot {
     values: Record<string, SettingsScalar | SettingsScalar[] | null>;
 }
 /**
- * 只调用模块 API 的页面客户端。
- * Page client that only calls the module API.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-export interface PreferencesClient {
+export class PreferencesClient {
+    /** 创建页面客户端 / Create the page client. */
+    constructor(options: PreferencesClientOptions);
+    /** 读取设置并建立页面快照 / Read settings and establish the page snapshot. */
+    open(): Promise<ModuleSnapshot>;
     /** 获取页面快照，不发请求 / Get a page snapshot without a request. */
     snapshot(): ModuleSnapshot;
     /** 读取 Settings 子树 / Read the Settings subtree. */
@@ -63,10 +65,3 @@ export interface PreferencesClient {
     /** 删除单个字段覆盖值 / Delete one field override. */
     remove(key: string): Promise<void>;
 }
-/**
- * 创建只调用模块 API 的页面客户端。
- * Create a page client that only calls the module API.
- * @param options API 模型与运行环境 / API model and runtime.
- * @returns 页面客户端 / Page client.
- */
-export function createPreferencesClient(options: PreferencesClientOptions): PreferencesClient;

package/src/browser/client.mjs

@@ -1,14 +1,133 @@
+import { normalizeStoredValue, validValue } from "./boxjs.mjs";
+
 /**
- * 创建单模块页面客户端；只调用模块 API，不读取或解析 BoxJS。
- * Create a single-module 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.
- * @returns {import("./client.mjs").PreferencesClient} 页面客户端 / Page client.
+ * 管理单模块页面的 API 请求、值快照和会话终止。
+ * Manage API requests, value snapshots, and session termination for one module page.
  */
-export function createPreferencesClient({ model, definition, fetch: request = globalThis.fetch.bind(globalThis), notify = () => {}, timeout = 10000 }) {
-    const { module, configURL } = model;
-    const session = new AbortController();
-    const values = structuredClone(model.values);
-    let saving = false;
+export class PreferencesClient {
+    #module;
+    #definition;
+    #request;
+    #notify;
+    #timeout;
+    #session = new AbortController();
+    #values = {};
+    #saving = false;
+
+    /**
+     * 创建从 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({ 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;
+    }
+
+    /**
+     * 读取一次 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();
+    }
+
+    /**
+     * 获取当前字段定义和值的深拷贝，不发起网络请求。
+     * Return a deep copy of the current field definition and values without a network request.
+     * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
+     */
+    snapshot() {
+        return structuredClone({ definition: this.#definition, values: this.#values });
+    }
+
+    /**
+     * 读取 Settings 子树。
+     * Read the Settings subtree.
+     * @returns {Promise<unknown>} Settings 内容或 undefined / Settings content or undefined.
+     */
+    async readSettings() {
+        const response = await this.#send("get", { scope: "settings" });
+        return response.status === 404 ? undefined : response.json();
+    }
+
+    /**
+     * 读取 Caches 子树。
+     * Read the Caches subtree.
+     * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
+     */
+    async readCaches() {
+        const response = await this.#send("get", { scope: "caches" });
+        return response.status === 404 ? undefined : response.json();
+    }
+
+    /**
+     * 删除当前模块的 Caches 子树。
+     * Delete the current module Caches subtree.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    clearCaches() {
+        return this.#change("delete", { scope: "caches" }, "clearCaches");
+    }
+
+    /**
+     * 删除当前模块数据并恢复页面默认值。
+     * Delete current module data and restore page defaults.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    reset() {
+        return this.#change("delete", { scope: "module" }, "reset");
+    }
+
+    /**
+     * 终止当前页面仍在进行的请求。
+     * Abort requests still owned by the current page.
+     * @returns {void} 无返回值 / No return value.
+     */
+    leave() {
+        this.#session.abort();
+    }
+
+    /**
+     * 写入单个字段。
+     * Write one field.
+     * @param {string} key 字段路径 / Field path.
+     * @param {unknown} value 已校验值 / Validated value.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    set(key, value) {
+        return this.#change("set", { key, value }, "write", key);
+    }
+
+    /**
+     * 删除单个字段覆盖值。
+     * Delete one field override.
+     * @param {string} key 字段路径 / Field path.
+     * @returns {Promise<void>} 操作完成 / Operation completion.
+     */
+    remove(key) {
+        return this.#change("delete", { key }, "delete", key);
+    }
 
     /**
      * 向模块 API 发送 JSON 动作。
@@ -17,26 +136,26 @@ export function createPreferencesClient({ model, definition, fetch: request = gl
      * @param {unknown} payload JSON 请求体 / JSON request body.
      * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async function send(action, payload) {
+    async #send(action, payload) {
         const controller = new AbortController();
         const abort = () => controller.abort();
-        if (session.signal.aborted) abort();
-        session.signal.addEventListener("abort", abort, { once: true });
-        const timer = setTimeout(abort, timeout);
+        if (this.#session.signal.aborted) abort();
+        this.#session.signal.addEventListener("abort", abort, { once: true });
+        const timer = setTimeout(abort, this.#timeout);
         try {
-            const response = await request(`/api/${encodeURIComponent(module)}/${action}`, {
+            const response = await this.#request(`/api/${encodeURIComponent(this.#module)}/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/json", "X-PreferencePanes-JSON": configURL },
+                headers: { "Content-Type": "application/json" },
                 body: JSON.stringify(payload),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
         } finally {
             clearTimeout(timer);
-            session.signal.removeEventListener("abort", abort);
+            this.#session.signal.removeEventListener("abort", abort);
         }
     }
 
@@ -44,58 +163,45 @@ export function createPreferencesClient({ model, definition, fetch: request = gl
      * 执行写入动作；成功后只更新当前页面值。
      * Execute a mutation and update only the current page values after success.
      * @param {"set" | "delete"} action API 动作 / API action.
-     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * @param {Record<string, unknown>} payload JSON 请求体 / JSON request body.
      * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
      * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
-    async function change(action, payload, operation, key) {
-        if (saving) throw new Error("A settings write is already in progress");
-        saving = true;
+    async #change(action, payload, operation, key) {
+        if (this.#saving) throw new Error("A settings write is already in progress");
+        this.#saving = true;
         try {
-            await send(action, payload);
+            if (operation === "write") {
+                const field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || !validValue(field, payload.value)) throw new TypeError("Invalid setting value");
+            }
+            await this.#send(action, payload);
             switch (operation) {
                 case "write":
-                    values[key] = structuredClone(payload.value);
+                    this.#values[key] = structuredClone(payload.value);
                     break;
                 case "delete": {
-                    const field = definition.fields.find(candidate => candidate.key === key);
-                    delete values[key];
-                    if (field && Object.hasOwn(field, "defaultValue")) values[key] = structuredClone(field.defaultValue);
+                    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);
                     break;
                 }
                 case "clearCaches":
                     break;
                 case "reset":
-                    for (const field of definition.fields) {
-                        delete values[field.key];
-                        if (Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
+                    for (const field of this.#definition.fields) {
+                        delete this.#values[field.key];
+                        if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);
                     }
                     break;
             }
-            notify({ kind: "success", operation, module, key });
+            this.#notify({ kind: "success", operation, module: this.#module, key });
         } catch (error) {
-            notify({ kind: "error", operation, module, key, message: error.message });
+            this.#notify({ kind: "error", operation, module: this.#module, key, message: error.message });
             throw error;
         } finally {
-            saving = false;
+            this.#saving = false;
         }
     }
-
-    return {
-        snapshot: () => structuredClone({ definition, values }),
-        async readSettings() {
-            const response = await send("get", { scope: "settings" });
-            return response.status === 404 ? undefined : response.json();
-        },
-        async readCaches() {
-            const response = await send("get", { scope: "caches" });
-            return response.status === 404 ? undefined : response.json();
-        },
-        clearCaches: () => change("delete", { scope: "caches" }, "clearCaches"),
-        reset: () => change("delete", { scope: "module" }, "reset"),
-        leave: () => session.abort(),
-        set: (key, value) => change("set", { key, value }, "write", key),
-        remove: key => change("delete", { key }, "delete", key),
-    };
 }

package/src/browser/index.d.ts

@@ -1,4 +1,4 @@
-import type { ModuleModel } from "../index.js";
+import type { BoxJSInput } from "../index.js";
 
 /**
  * 具体模块设置页的生命周期句柄。
@@ -9,10 +9,9 @@ export interface MountedPreferences {
     destroy(): void;
 }
 /**
- * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
- * Mount a settings page from a module API model; CSS only overrides this module.
- * @param model 模块 API 模型 / Module API model.
- * @param css 可选 CSS 正文 / Optional CSS text.
- * @returns 生命周期句柄 / Lifecycle handle.
+ * 使用原始 BoxJS JSON 挂载设置页。
+ * Mount a settings page from raw BoxJS JSON.
+ * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
+ * @returns 模块视图 / Module view.
  */
-export function mount(model: ModuleModel, css?: string): MountedPreferences;
+export function mount(boxjs: BoxJSInput): MountedPreferences;