@nsnanocat/preference-panes 1.1.1 → 1.1.2

package/dist/module/index.mjs

@@ -1,94 +1,3 @@
-/**
- * 创建元素，所有展示文本通过 textContent 写入。
- * Create elements and assign display text through textContent only.
- * @template {keyof HTMLElementTagNameMap} T
- * @param {T} tag 元素标签 / Element tag.
- * @param {string} className 样式类名 / CSS class.
- * @param {string} [text] 纯文本 / Plain text.
- * @returns {HTMLElementTagNameMap[T]} 创建的元素 / Created element.
- */
-function element(tag, className, text) {
-    const node = document.createElement(tag);
-    node.className = className;
-    if (text !== undefined) node.textContent = text;
-    return node;
-}
-
-/**
- * 创建通用设置行；外部 CSS 可通过 pp 类名覆盖视觉样式。
- * Create a generic settings row whose appearance can be overridden through pp classes.
- * @template {"div" | "label"} T
- * @param {T} tag 行元素 / Row element.
- * @returns {HTMLElementTagNameMap[T]} 设置行 / Settings row.
- */
-function settingRow(tag) {
-    return element(tag, "pp-row");
-}
-
-/**
- * 为标准 HTML 输入控件添加通用面板类名。
- * Add the generic panel class to a standard HTML input control.
- * @param {HTMLElement} control 已创建的原生控件 / Existing native control.
- * @returns {HTMLElement} 输入控件 / Input control.
- */
-function fieldControl(control) {
-    control.classList.add("pp-editor");
-    return control;
-}
-
-/**
- * 元数据地址只允许 HTTP(S) 和相对地址。
- * Allow only HTTP(S) and relative metadata addresses.
- * @param {string} value 元数据地址 / Metadata address.
- * @returns {string} 完整地址 / Absolute address.
- */
-function resourceURL(value) {
-    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;
-}
-
-/**
- * 创建覆盖可用内容区的通用读取状态，失败时可附加重试动作。
- * Create a shared status view that fills the available content area and may include retry.
- * @param {string} message 状态文本 / Status message.
- * @param {(() => unknown) | undefined} [retry] 重试动作 / Retry action.
- * @returns {HTMLElement} 居中状态视图 / Centered status view.
- */
-function statusView(message, retry) {
-    const view = element("section", "pp-status");
-    view.setAttribute("role", "status");
-    view.setAttribute("aria-live", "polite");
-    const spinner = element("span", "pp-status-spinner");
-    spinner.setAttribute("aria-hidden", "true");
-    view.append(spinner, element("p", "pp-status-message", message));
-    if (retry) {
-        const button = element("button", "pp-status-action", "重新读取");
-        button.type = "button";
-        button.onclick = retry;
-        view.append(button);
-    }
-    return view;
-}
-
-/**
- * 请求宿主确认；独立网页使用浏览器对话框。
- * Request confirmation from the host, using the browser dialog for standalone pages.
- * @param {Window} host 模块窗口 / Module window.
- * @param {string} message 确认内容 / Confirmation message.
- * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
- */
-function requestConfirmation(host, message) {
-    return new Promise((resolve, reject) => {
-        const frame = host.frameElement;
-        if (frame) {
-            const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:confirm", { cancelable: true, detail: { message, resolve, reject } });
-            if (!frame.dispatchEvent(event)) return;
-        }
-        resolve(host.confirm(message));
-    });
-}
-
 /**
  * 校验原始路径片段，不进行 URL 编码转换。
  * Validate raw path segments without URL encoding conversion.
@@ -136,8 +45,8 @@ function normalizeBoxJs(config, module) {
             target.owners.add(app);
         }
     }
-    if (modules.size !== 1) throw new TypeError("Import BoxJS JSON for exactly one module");
-    const target = modules.values().next().value ;
+    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 (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
     const metadata = normalizeMetadata(target.owners.size === 1 ? presentation([...target.owners][0]) : {});
     const fields = [];
@@ -274,6 +183,97 @@ function validValue(field, value) {
     return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
 }
 
+/**
+ * 创建元素，所有展示文本通过 textContent 写入。
+ * Create elements and assign display text through textContent only.
+ * @template {keyof HTMLElementTagNameMap} T
+ * @param {T} tag 元素标签 / Element tag.
+ * @param {string} className 样式类名 / CSS class.
+ * @param {string} [text] 纯文本 / Plain text.
+ * @returns {HTMLElementTagNameMap[T]} 创建的元素 / Created element.
+ */
+function element(tag, className, text) {
+    const node = document.createElement(tag);
+    node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+}
+
+/**
+ * 创建通用设置行；外部 CSS 可通过 pp 类名覆盖视觉样式。
+ * Create a generic settings row whose appearance can be overridden through pp classes.
+ * @template {"div" | "label"} T
+ * @param {T} tag 行元素 / Row element.
+ * @returns {HTMLElementTagNameMap[T]} 设置行 / Settings row.
+ */
+function settingRow(tag) {
+    return element(tag, "pp-row");
+}
+
+/**
+ * 为标准 HTML 输入控件添加通用面板类名。
+ * Add the generic panel class to a standard HTML input control.
+ * @param {HTMLElement} control 已创建的原生控件 / Existing native control.
+ * @returns {HTMLElement} 输入控件 / Input control.
+ */
+function fieldControl(control) {
+    control.classList.add("pp-editor");
+    return control;
+}
+
+/**
+ * 元数据地址只允许 HTTP(S) 和相对地址。
+ * Allow only HTTP(S) and relative metadata addresses.
+ * @param {string} value 元数据地址 / Metadata address.
+ * @returns {string} 完整地址 / Absolute address.
+ */
+function resourceURL(value) {
+    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;
+}
+
+/**
+ * 创建覆盖可用内容区的通用读取状态，失败时可附加重试动作。
+ * Create a shared status view that fills the available content area and may include retry.
+ * @param {string} message 状态文本 / Status message.
+ * @param {(() => unknown) | undefined} [retry] 重试动作 / Retry action.
+ * @returns {HTMLElement} 居中状态视图 / Centered status view.
+ */
+function statusView(message, retry) {
+    const view = element("section", "pp-status");
+    view.setAttribute("role", "status");
+    view.setAttribute("aria-live", "polite");
+    const spinner = element("span", "pp-status-spinner");
+    spinner.setAttribute("aria-hidden", "true");
+    view.append(spinner, element("p", "pp-status-message", message));
+    if (retry) {
+        const button = element("button", "pp-status-action", "重新读取");
+        button.type = "button";
+        button.onclick = retry;
+        view.append(button);
+    }
+    return view;
+}
+
+/**
+ * 请求宿主确认；独立网页使用浏览器对话框。
+ * Request confirmation from the host, using the browser dialog for standalone pages.
+ * @param {Window} host 模块窗口 / Module window.
+ * @param {string} message 确认内容 / Confirmation message.
+ * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
+ */
+function requestConfirmation(host, message) {
+    return new Promise((resolve, reject) => {
+        const frame = host.frameElement;
+        if (frame) {
+            const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:confirm", { cancelable: true, detail: { message, resolve, reject } });
+            if (!frame.dispatchEvent(event)) return;
+        }
+        resolve(host.confirm(message));
+    });
+}
+
 /**
  * 共用三点按钮和底部操作菜单；弹层挂载到文档根部，不受标题栏显示状态影响。
  * Shared overflow trigger and bottom action sheet; the layer is mounted at document level and remains independent of header visibility.
@@ -489,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();
     }
 
@@ -499,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();
     }
 
@@ -509,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");
     }
 
     /**
@@ -518,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");
     }
 
     /**
@@ -538,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");
     }
 
     /**
@@ -548,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" },
-                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;
@@ -585,28 +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 {
-            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");
+            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, payload);
+            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":
@@ -1440,8 +1441,8 @@ class ModulePage {
     }
 
     /**
-     * 从规范模块路径读取 BoxJS JSON 并挂载通用前端。
-     * Read BoxJS JSON from the conventional module path and mount the generic frontend.
+     * 通过模块 API 读取 BoxJS JSON 并挂载通用前端。
+     * Read BoxJS JSON through the module API and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -1453,9 +1454,11 @@ class ModulePage {
             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" } });
+            const response = await fetch(`/api/${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());
+            const boxjs = await response.json();
+            normalizeBoxJs(boxjs, module);
+            this.#view = mount(boxjs);
         } catch (error) {
             this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
         }

package/dist/preference-panes.mjs

@@ -489,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();
     }
 
@@ -499,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();
     }
 
@@ -509,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");
     }
 
     /**
@@ -518,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");
     }
 
     /**
@@ -538,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");
     }
 
     /**
@@ -548,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" },
-                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;
@@ -585,28 +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 {
-            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");
+            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, payload);
+            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":