@nsnanocat/preference-panes 0.9.15 → 1.0.0

package/src/browser/panel.mjs

@@ -1,21 +1,23 @@
 import { ActionMenu } from "./ActionMenu.mjs";
+import { validValue } from "./boxjs.mjs";
 import { createPreferencesClient } from "./client.mjs";
 import { fieldControl, element as node, requestConfirmation, resourceURL, settingRow, statusView } from "./components.mjs";
 import { Navigation } from "./Navigation.mjs";
 
 /**
- * 挂载已导入 BoxJS 对应的模块表单和短暂通知。
- * Mount the imported BoxJS module form and transient notifications.
+ * 挂载 API 返回的模块模型表单和短暂通知。
+ * Mount the module model returned by the API and transient notifications.
  * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
- * @param {import("../BoxJS.mjs").BoxJS} catalog 包内 BoxJS 目录 / Internal BoxJS catalog.
+ * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
  * @returns {import("./index.js").MountedPreferences} 面板生命周期句柄 / Panel lifecycle handle.
  */
-export function mountPanel(root, catalog) {
-    const title = catalog.module.metadata.name ?? catalog.module.module;
+export function mountPanel(root, model) {
+    const { definition } = model;
+    const title = definition.metadata?.name ?? definition.module;
     const document = root.ownerDocument;
     const window = document.defaultView;
     const shell = node("div", "pp-panel");
-    shell.dataset.module = catalog.module.module;
+    shell.dataset.module = definition.module;
     const header = node("header", "pp-header");
     const back = node("button", "pp-back", "‹");
     back.setAttribute("aria-label", "返回");
@@ -45,7 +47,7 @@ export function mountPanel(root, catalog) {
         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, actions },
+                detail: { title: heading.textContent, module: definition.module, busy: saving, canGoBack: !back.disabled, actions },
             }),
         );
     };
@@ -102,7 +104,7 @@ export function mountPanel(root, catalog) {
             toast.hidden = true;
         }, 2400);
     };
-    const client = createPreferencesClient({ catalog, notify });
+    const client = createPreferencesClient({ model, definition, notify });
     /**
      * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
      * Share async error handling between both menus, including host-dialog errors.
@@ -130,7 +132,6 @@ export function mountPanel(root, catalog) {
         publishNavigation();
         viewport.replaceChildren(statusView("读取设置…"));
         try {
-            await client.open(module);
             if (version === generation) controls();
         } catch (error) {
             if (version !== generation) return;
@@ -144,7 +145,7 @@ export function mountPanel(root, catalog) {
      * @returns {void} 无返回值 / No return value.
      */
     function controls() {
-        const { definition, values } = client.snapshot(active);
+        const { definition, values } = client.snapshot();
         heading.textContent = definition.metadata?.name || active;
         const view = node("section", "pp-fields");
         /**
@@ -182,7 +183,7 @@ export function mountPanel(root, catalog) {
             saving = true;
             back.disabled = true;
             publishNavigation();
-            return (queue = queue
+            queue = queue
                 .then(action)
                 .then(() => {
                     if (!destroyed) success();
@@ -195,10 +196,11 @@ export function mountPanel(root, catalog) {
                 .finally(() => {
                     pendingWrites--;
                     saving = pendingWrites > 0;
-                    if (destroyed && !saving) client.leave(active);
+                    if (destroyed && !saving) client.leave();
                     back.disabled = saving || !navigation.canGoBack;
                     publishNavigation();
-                }));
+                });
+            return queue;
         }
         const metadata = definition.metadata;
         if (metadata) {
@@ -276,7 +278,7 @@ export function mountPanel(root, catalog) {
                     link.append(summary, node("span", "pp-chevron", "›"));
                     row.append(link);
                     const refresh = () => {
-                        const value = client.snapshot(active).values[field.key];
+                        const value = client.snapshot().values[field.key];
                         summary.textContent =
                             field.options
                                 .filter(option => Array.isArray(value) && value.includes(option.key))
@@ -377,10 +379,17 @@ export function mountPanel(root, catalog) {
                     return;
                 }
                 const restore = () => {
-                    if (version === inputVersion) write(client.snapshot(module).values[field.key]);
+                    if (version === inputVersion) write(client.snapshot().values[field.key]);
                 };
                 perform(
-                    () => client.set(module, field.key, value),
+                    () => {
+                        if (!validValue(field, value)) {
+                            const error = new TypeError("Invalid setting value");
+                            notify({ kind: "error", operation: "write", module, key: field.key, message: error.message });
+                            throw error;
+                        }
+                        return client.set(field.key, value);
+                    },
                     () => {
                         for (const refresh of summaries) refresh();
                     },
@@ -401,7 +410,7 @@ export function mountPanel(root, catalog) {
             return perform(
                 async () => {
                     try {
-                        value = await client.readSettings(active);
+                        value = await client.readSettings();
                     } catch (error) {
                         notify({ kind: "error", message: error.message });
                         throw error;
@@ -425,7 +434,7 @@ export function mountPanel(root, catalog) {
             return perform(
                 async () => {
                     try {
-                        value = await client.readCaches(active);
+                        value = await client.readCaches();
                     } catch (error) {
                         notify({ kind: "error", message: error.message });
                         throw error;
@@ -441,7 +450,7 @@ export function mountPanel(root, catalog) {
             if (saving) return;
             if (!(await requestConfirmation(window, `清空 ${active} 的全部 Caches？`)) || destroyed || saving) return;
             return perform(
-                () => client.clearCaches(active),
+                () => client.clearCaches(),
                 () => {
                     output.textContent = "暂无缓存";
                 },
@@ -450,7 +459,7 @@ export function mountPanel(root, catalog) {
         handlers.set("reset", async () => {
             if (saving) return;
             if (!(await requestConfirmation(window, `重置 ${active} 的设置？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) || destroyed || saving) return;
-            return perform(() => client.reset(active), controls);
+            return perform(() => client.reset(), controls);
         });
         navigation?.destroy();
         navigation = new Navigation(viewport, view, key => editors.get(key)?.node);
@@ -468,7 +477,7 @@ export function mountPanel(root, catalog) {
         if (navigation) navigation.back();
         else window.history.back();
     };
-    open(catalog.module.module);
+    open(definition.module);
     return {
         /**
          * 移除监听器、定时器、会话和挂载内容。
@@ -481,7 +490,7 @@ export function mountPanel(root, catalog) {
             window.frameElement?.removeEventListener("preferencepanes:action", onAction);
             navigation?.destroy();
             generation++;
-            if (active && !saving) client.leave(active);
+            if (active && !saving) client.leave();
             clearTimeout(timer);
             shell.remove();
         },

package/src/build.mjs

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { BoxJS } from "./BoxJS.mjs";
+import { normalizeBoxJs } from "./browser/boxjs.mjs";
 
 /**
  * 仅生成模块前端文件，不复制配置或生成绑定业务的读写脚本。
@@ -10,8 +10,7 @@ import { BoxJS } from "./BoxJS.mjs";
  */
 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 module = normalizeBoxJs(boxjs).module;
     const [html, app] = 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")]);
     return {
         [`settings/${module}/index.html`]: html,

package/src/index.d.ts

@@ -92,8 +92,8 @@ export interface SettingsRequest {
      */
     headers?: Record<string, string | undefined>;
     /**
-     * POST 的正文为一个 form 字段，字段名是完整 @root.path
-     * POST contains one form field whose name is the complete @root.path.
+     * 模块动作的 JSON 正文
+     * JSON body for a module action.
      */
     body?: string;
 }
@@ -268,6 +268,20 @@ export interface BoxJSSubscription extends BoxJSMetadata {
  * The sole data configuration input.
  */
 export type BoxJSInput = BoxJSSetting[] | BoxJSApp | BoxJSSubscription;
+/**
+ * 模块 API 返回的原始 BoxJS 与当前值模型。
+ * Raw BoxJS and current-value model returned by the module API.
+ */
+export interface ModuleModel {
+    /** 模块路径段 / Module path segment. */
+    module: string;
+    /** API 获取的原始 BoxJS JSON / Raw BoxJS JSON fetched by the API. */
+    boxjs: BoxJSInput;
+    /** API 读取到的原始已保存字段值 / Raw persisted field values read by the API. */
+    values: Record<string, JsonValue>;
+    /** 后续 API 动作使用的 BoxJS JSON 地址 / BoxJS JSON URL used by later API actions. */
+    configURL: string;
+}
 /**
  * 生成模块前端文件，不复制配置、不生成绑定模块的代理脚本。
  * Build module frontend files without copying configuration or producing bound proxy scripts.

package/src/web.mjs

@@ -0,0 +1,52 @@
+import { URL } from "@nsnanocat/url";
+import { $app } from "@nsnanocat/util/lib/app.mjs";
+import { done } from "@nsnanocat/util/lib/done.mjs";
+import assets from "#assets";
+import { pageInputs } from "./lib/page-inputs.mjs";
+
+/**
+ * 返回模块页面及其公共浏览器资源，不处理 API、网络或持久化。
+ * Serve module pages and common browser assets without handling APIs, network access or persistence.
+ * @returns {void} 响应已交给代理宿主 / Response delivered to the proxy host.
+ */
+function run() {
+    const request = globalThis.$request;
+    let result;
+    try {
+        const url = new URL(request.url);
+        if (/^\/settings\/[a-zA-Z0-9_-]+\/?$/.test(url.pathname)) {
+            if (!["GET", "HEAD"].includes(request.method)) result = response(request, 405, { error: "Method not allowed" });
+            else {
+                const inputs = encodeURIComponent(JSON.stringify(pageInputs(url, request.headers)));
+                result = response(request, 200, assets.page.body.replace("</head>", `<meta name="preference-panes-inputs" content="${inputs}"></head>`), "text/html");
+            }
+        } else {
+            const asset = assets[url.pathname];
+            if (asset) result = ["GET", "HEAD"].includes(request.method) ? response(request, 200, asset.body, asset.type) : response(request, 405, { error: "Method not allowed" });
+        }
+    } catch (error) {
+        console.error(`PreferencePanes Web: ${error.message}`);
+        result = response(request, 500, { error: error.message });
+    }
+    if (!result) done({});
+    else done($app === "Quantumult X" ? result : { response: result });
+}
+
+/**
+ * 构造静态资源响应，HEAD 请求不返回正文。
+ * Build a static resource response without a body for HEAD requests.
+ * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+ * @param {number} status HTTP 状态 / HTTP status.
+ * @param {unknown} body 响应正文 / Response body.
+ * @param {string} [type] 媒体类型 / Media type.
+ * @returns {import("./index.js").SettingsResponse} 静态资源响应 / Static resource response.
+ */
+function response(request, status, body, type = "application/json") {
+    return {
+        status,
+        headers: { "Content-Type": `${type}; charset=utf-8`, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
+        body: request.method === "HEAD" ? "" : type === "application/json" ? JSON.stringify(body) : body,
+    };
+}
+
+run();

package/src/BoxJS.mjs

@@ -1,72 +0,0 @@
-import { validatePathParts } from "./lib/settings-path.mjs";
-
-/**
- * BoxJS 的共同目录：模块、存储根和展示元数据都来自同一份 JSON。
- * Shared BoxJS catalog deriving modules, storage roots and metadata from one JSON document.
- */
-export class BoxJS {
-    /**
-     * 建立路径索引，不解析控件类型，也不读写持久化存储。
-     * Index field paths without interpreting controls or accessing persistence.
-     * @param {unknown} input 字段数组、单个 app 或 apps 订阅 / Field array, app or apps subscription.
-     */
-    constructor(input) {
-        if (!input || typeof input !== "object") throw new TypeError("Expected BoxJS JSON");
-        const document = JSON.parse(JSON.stringify(input));
-        const apps = Array.isArray(document) ? [{ settings: document }] : (document.apps ?? [document]);
-        if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-        this.modules = new Map();
-        for (const app of apps) {
-            if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
-            for (const entry of app.settings) {
-                if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
-                if (!entry.id.startsWith("@")) {
-                    if (Array.isArray(document)) throw new TypeError("BoxJS settings require @root.path IDs");
-                    continue;
-                }
-                const [storageKey, ...parts] = entry.id.slice(1).split(".");
-                if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                validatePathParts(parts);
-                const module = parts[0];
-                let target = this.modules.get(module);
-                if (!target) {
-                    target = { module, storageKey, entries: [], owners: new Set() };
-                    this.modules.set(module, target);
-                }
-                if (target.storageKey !== storageKey) throw new TypeError(`A module must use one storage root: ${module}`);
-                target.entries.push(entry);
-                target.owners.add(app);
-            }
-        }
-        this.metadata = metadata(Array.isArray(document) ? {} : document);
-        for (const target of this.modules.values()) target.metadata = target.owners.size === 1 ? metadata([...target.owners][0]) : {};
-    }
-
-    /**
-     * 取得本次导入的唯一模块，避免把模块数据变成项目目录。
-     * Get the single imported module without turning module data into a project directory.
-     * @returns {object} 唯一模块的目录项 / The single module entry.
-     */
-    get module() {
-        if (this.modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
-        return this.modules.values().next().value;
-    }
-}
-
-/**
- * 保留标准 BoxJS 展示信息；script 仅为元数据，不执行。
- * Retain standard BoxJS presentation data; script is metadata only and never executed.
- * @param {object} source BoxJS app 或订阅 / BoxJS app or subscription.
- * @returns {object} 经过类型检查的展示信息 / Type-checked presentation metadata.
- */
-function metadata(source) {
-    const result = {};
-    for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
-        if (source[key] === undefined) continue;
-        const multiple = key === "icons" || key === "descs";
-        const values = multiple ? source[key] : [source[key]];
-        if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
-        result[key] = multiple ? [...values] : source[key];
-    }
-    return result;
-}

package/src/Store.mjs

@@ -1,114 +0,0 @@
-import { URL } from "@nsnanocat/url";
-import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
-import { Storage } from "@nsnanocat/util/polyfill/Storage";
-import { response } from "./lib/response.mjs";
-import { validatePathParts } from "./lib/settings-path.mjs";
-
-/**
- * 无配置绑定的本地存储桥接；form 字段名就是完整 @root.path。
- * Unbound local storage bridge; the form field name is the complete @root.path.
- */
-export class Store {
-    /**
-     * POST /api/get、set、delete；不下载配置、不解析控件、不鉴权。
-     * POST /api/get, set or delete without config downloads, control parsing or authentication.
-     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
-     * @param {URL} [url] 已解析地址 / Parsed URL.
-     * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 操作结果 / Operation result.
-     */
-    async handle(request, url = new URL(request.url)) {
-        if (!url.pathname.startsWith("/api/")) return;
-        const reply = (status, data) => response(request, status, data);
-        const action = url.pathname.slice(5);
-        if (!["get", "set", "delete"].includes(action)) return reply(404, { error: "Unknown action" });
-        if (request.method !== "POST") return reply(405, { error: "Use POST with a form body" });
-        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return reply(415, { error: "Expected application/x-www-form-urlencoded" });
-        if (typeof request.body !== "string" || request.body.length > 65536) return reply(400, { error: "Expected a form body up to 65536 characters" });
-        let parts, value;
-        try {
-            const fields = request.body.split("&");
-            if (fields.length !== 1) throw new TypeError("Send exactly one storage key");
-            const separator = fields[0].indexOf("=");
-            if (separator < 0) throw new TypeError("Expected @root.path=value");
-            const key = decodeURIComponent(fields[0].slice(0, separator).replace(/\+/g, " "));
-            value = decodeURIComponent(fields[0].slice(separator + 1).replace(/\+/g, " "));
-            if (!key.startsWith("@")) throw new TypeError("Storage keys must start with @");
-            parts = validatePathParts(key.slice(1).split("."));
-            if (parts.length < 2) throw new TypeError("Specify a storage root and child path");
-        } catch (error) {
-            return reply(400, { error: error.message });
-        }
-        if (action === "set") {
-            try {
-                value = JSON.parse(value);
-            } catch (error) {
-                if (!(error instanceof SyntaxError)) throw error;
-            }
-        }
-        const [storageKey, ...path] = parts;
-        try {
-            const root = Storage.getItem(storageKey, {});
-            if (!isRecord(root)) throw new TypeError("Stored root must be an object");
-            const parent = storageParent(root, path, action === "set");
-            const key = path.at(-1);
-            switch (action) {
-                case "get": {
-                    const result = parent ? _.get(parent, [key]) : undefined;
-                    return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
-                }
-                case "set":
-                    _.set(parent, [key], value);
-                    break;
-                case "delete":
-                    if (parent) _.unset(parent, [key]);
-                    break;
-            }
-            if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
-            return reply(200, action === "set" ? { saved: true } : { deleted: true });
-        } catch (error) {
-            return reply(500, { error: error.message });
-        }
-    }
-}
-
-/**
- * 判断根节点是否为普通对象。
- * Determine whether a root node is a plain object.
- * @param {unknown} value 待检查值 / Value to inspect.
- * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
- */
-function isRecord(value) {
-    return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
-}
-
-/**
- * 遍历父路径，兼容旧存储中 JSON 字符串形式的中间节点。
- * Traverse parents, supporting legacy intermediate nodes serialized as JSON strings.
- * @param {Record<string, unknown>} root 存储根 / Storage root.
- * @param {string[]} parts 完整路径 / Complete path.
- * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
- * @returns {object | undefined} 父节点，缺失且不创建时为 undefined / Parent, or undefined when absent and not creating.
- * @throws {TypeError} 无法继续遍历标量节点 / A scalar node cannot be traversed.
- */
-function storageParent(root, parts, create) {
-    let parent = root;
-    for (const part of parts.slice(0, -1)) {
-        let next = _.get(parent, [part]);
-        switch (typeof next) {
-            case "undefined":
-                if (!create) return;
-                next = {};
-                break;
-            case "string":
-                next = JSON.parse(next);
-                break;
-            default:
-                break;
-        }
-        if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
-        _.set(parent, [part], next);
-        parent = next;
-    }
-    return parent;
-}

package/src/lib/response.mjs

@@ -1,16 +0,0 @@
-/**
- * 统一生成不可缓存的响应，HEAD 始终省略正文。
- * Create an uncached response, always omitting the body for HEAD.
- * @param {import("../index.js").SettingsRequest} request 宿主请求 / Host request.
- * @param {number} status HTTP 状态 / HTTP status.
- * @param {unknown} body JSON 数据或资源正文 / JSON data or resource body.
- * @param {string} [type] 媒体类型 / Media type.
- * @returns {import("../index.js").SettingsResponse} 通用响应 / Common response.
- */
-export function response(request, status, body, type = "application/json") {
-    return {
-        status,
-        headers: { "Content-Type": `${type}; charset=utf-8`, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
-        body: request.method === "HEAD" ? "" : type === "application/json" ? JSON.stringify(body) : body,
-    };
-}

package/src/proxy/handler.mjs

@@ -1,39 +0,0 @@
-import { URL } from "@nsnanocat/url";
-import assets from "#assets";
-import { pageInputs } from "../lib/page-inputs.mjs";
-import { response } from "../lib/response.mjs";
-import { Store } from "../Store.mjs";
-import { complete } from "./response.mjs";
-
-/**
- * 通用代理入口：提供无鉴权 form 存储 API 及模块页面，不含业务配置。
- * Generic proxy entry serving unauthenticated form storage and module pages without business configuration.
- * @returns {Promise<void>} 已交给代理宿主的响应 / Response delivered to the proxy host.
- */
-async function run() {
-    const request = globalThis.$request;
-    let result;
-    try {
-        const url = new URL(request.url);
-        switch (true) {
-            case url.pathname.startsWith("/api/"):
-                result = await new Store().handle(request, url);
-                break;
-            case /^\/settings\/[a-zA-Z0-9_-]+\/?$/.test(url.pathname): {
-                const inputs = encodeURIComponent(JSON.stringify(pageInputs(url, request.headers)));
-                result = response(request, 200, assets.page.body.replace("</head>", `<meta name="preference-panes-inputs" content="${inputs}"></head>`), "text/html");
-                break;
-            }
-            default: {
-                const asset = assets[url.pathname];
-                if (asset) result = response(request, 200, asset.body, asset.type);
-            }
-        }
-        if (result && !url.pathname.startsWith("/api/") && !["GET", "HEAD"].includes(request.method)) result = response(request, 405, { error: "Method not allowed" });
-    } catch (error) {
-        console.error(`PreferencePanes: ${error.message}`);
-        result = response(request, 500, { error: error.message });
-    }
-    complete(result);
-}
-run();

package/src/proxy/response.mjs

@@ -1,16 +0,0 @@
-import { $app } from "@nsnanocat/util/lib/app.mjs";
-import { done } from "@nsnanocat/util/lib/done.mjs";
-
-/**
- * 统一适配代理的完成格式；未接管的请求原样继续。
- * Adapt the host completion format and pass through unhandled requests.
- * @param {import("../index.js").SettingsResponse | undefined} result 通用响应 / Common response.
- * @returns {void} 响应已交给宿主 / Response delivered to the host.
- */
-export function complete(result) {
-    if (!result) {
-        done({});
-        return;
-    }
-    done($app === "Quantumult X" ? result : { response: result });
-}