@nsnanocat/preference-panes 0.5.0 → 0.7.0

package/src/lib/boxjs.mjs

@@ -1,3 +1,4 @@
+import { BoxJS } from "../BoxJS.mjs";
 import { validatePathParts } from "./settings-path.mjs";
 
 /**
@@ -9,74 +10,51 @@ import { validatePathParts } from "./settings-path.mjs";
  * @throws {TypeError} 配置结构、字段路径、默认值或展示属性无效 / Invalid configuration, field path, default or presentation attribute.
  */
 export function normalizeBoxJs(config, module) {
-	validatePathParts([module]);
-	const apps = Array.isArray(config) ? [] : (config?.apps ?? [config]);
-	if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-	for (const candidate of apps) {
-		if (!candidate || typeof candidate !== "object") throw new TypeError("Expected BoxJS app object");
-		if (candidate.settings !== undefined && !Array.isArray(candidate.settings)) throw new TypeError("Expected BoxJS settings array");
-	}
-	const owners = apps.filter(candidate => candidate.settings?.some(entry => typeof entry.id === "string" && entry.id.startsWith("@") && entry.id.slice(1).split(".")[1] === module));
-	const entries = Array.isArray(config) ? config : owners.flatMap(candidate => candidate.settings);
-	const app = owners.length === 1 ? owners[0] : undefined;
-	let storageKey;
-	const fields = [];
-	for (const entry of entries) {
-		if (typeof entry.id !== "string" || !entry.id.startsWith("@")) throw new TypeError("BoxJS settings require @root.path IDs");
-		const [root, ...parts] = entry.id.slice(1).split(".");
-		if (parts[0] !== module) continue;
-		if (parts.length < 2) throw new TypeError("A BoxJS setting must be below the module root");
-		validatePathParts(parts);
-		if (!root || (storageKey && root !== storageKey)) throw new TypeError("A module must use one storage root");
-		storageKey = root;
-		const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[entry.type];
-		if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
-		const field = {
-			key: parts.join("."),
-			type: type === "select" ? typeof entry.val : type,
+    validatePathParts([module]);
+    const target = new BoxJS(config).modules.get(module);
+    if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
+    const { entries, storageKey, metadata } = target;
+    const fields = [];
+    for (const entry of entries) {
+        const parts = entry.id.slice(1).split(".").slice(1);
+        const type = { boolean: "boolean", checkboxes: "array", selects: "select", text: "string", textarea: "string", number: "number" }[entry.type];
+        if (!type) throw new TypeError(`Unsupported BoxJS control: ${entry.type}`);
+        const field = {
+            key: parts.join("."),
+            type: type === "select" ? typeof entry.val : type,
 
-			name: entry.name,
-			description: entry.desc ?? "",
-			control: entry.type,
-			...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
-			...(entry.rows === undefined ? {} : { rows: entry.rows }),
-			...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
-		};
-		if (type === "select" && !["string", "number", "boolean"].includes(field.type)) throw new TypeError(`Select requires a scalar val: ${entry.id}`);
-		if (entry.items) field.options = entry.items.map(item => ({ key: item.key, label: item.label }));
-		if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
-		if (
-			typeof field.name !== "string" ||
-			(field.placeholder !== undefined && typeof field.placeholder !== "string") ||
-			(field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
-			(field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
-			fields.some(other => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
-		)
-			throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
-		if (field.options && (new Set(field.options.map(item => item.key)).size !== field.options.length || field.options.some(item => !scalar(item.key) || typeof item.label !== "string"))) throw new TypeError(`Invalid options: ${entry.id}`);
-		if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
-		fields.push(field);
-	}
-	if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-	const common = fields[0].key.split(".").slice(0, -1);
-	for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
-	const metadata = {};
-	if (app) {
-		for (const key of ["id", "name", "author", "repo", "script", "icon", "description", "desc", "icons", "descs"]) {
-			if (app[key] === undefined) continue;
-			const multiple = key === "icons" || key === "descs";
-			const values = multiple ? app[key] : [app[key]];
-			if (!Array.isArray(values) || values.some(item => typeof item !== "string")) throw new TypeError(`Invalid BoxJS app ${key}`);
-			metadata[key] = multiple ? [...values] : app[key];
-		}
-	}
-	return {
-		module,
-		storageKey,
-		fields,
-		settingsPath: common,
-		...(Object.keys(metadata).length ? { metadata } : {}),
-	};
+            name: entry.name,
+            description: entry.desc ?? "",
+            control: entry.type,
+            ...(entry.placeholder === undefined ? {} : { placeholder: entry.placeholder }),
+            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+            ...(entry.autoGrow === undefined ? {} : { autoGrow: entry.autoGrow }),
+        };
+        if (type === "select" && !["string", "number", "boolean"].includes(field.type)) throw new TypeError(`Select requires a scalar val: ${entry.id}`);
+        if (entry.items) field.options = entry.items.map(item => ({ key: item.key, label: item.label }));
+        if (Object.hasOwn(entry, "val")) field.defaultValue = normalizeStoredValue(field, entry.val);
+        if (
+            typeof field.name !== "string" ||
+            (field.placeholder !== undefined && typeof field.placeholder !== "string") ||
+            (field.rows !== undefined && (!Number.isInteger(field.rows) || field.rows < 1)) ||
+            (field.autoGrow !== undefined && typeof field.autoGrow !== "boolean") ||
+            fields.some(other => other.key === field.key || other.key.startsWith(`${field.key}.`) || field.key.startsWith(`${other.key}.`))
+        )
+            throw new TypeError(`Invalid or overlapping BoxJS field: ${entry.id}`);
+        if (field.options && (new Set(field.options.map(item => item.key)).size !== field.options.length || field.options.some(item => !scalar(item.key) || typeof item.label !== "string"))) throw new TypeError(`Invalid options: ${entry.id}`);
+        if (Object.hasOwn(field, "defaultValue") && !validValue(field, field.defaultValue)) throw new TypeError(`Invalid BoxJS val: ${entry.id}`);
+        fields.push(field);
+    }
+    if (!fields.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
+    const common = fields[0].key.split(".").slice(0, -1);
+    for (const field of fields) while (!field.key.startsWith(`${common.join(".")}.`)) common.pop();
+    return {
+        module,
+        storageKey,
+        fields,
+        settingsPath: common,
+        ...(Object.keys(metadata).length ? { metadata } : {}),
+    };
 }
 
 /**
@@ -87,24 +65,24 @@ export function normalizeBoxJs(config, module) {
  * @returns {unknown} 转换后的控件值；是否允许写入由 validValue 单独校验 / Converted control value; write eligibility is checked separately by validValue.
  */
 export function normalizeStoredValue(field, value) {
-	switch (field.type) {
-		case "boolean":
-			if (value === "true" || value === "false") return value === "true";
-			break;
-		case "number":
-			if (typeof value === "string" && value.trim() !== "") return Number(value);
-			break;
-		case "array":
-			if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
-			break;
-		default:
-			break;
-	}
-	if (field.options) {
-		const match = item => field.options.find(option => String(option.key) === String(item))?.key ?? item;
-		return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
-	}
-	return value;
+    switch (field.type) {
+        case "boolean":
+            if (value === "true" || value === "false") return value === "true";
+            break;
+        case "number":
+            if (typeof value === "string" && value.trim() !== "") return Number(value);
+            break;
+        case "array":
+            if (typeof value === "string") value = value === "" || value === "[]" ? [] : value.split(",");
+            break;
+        default:
+            break;
+    }
+    if (field.options) {
+        const match = item => field.options.find(option => String(option.key) === String(item))?.key ?? item;
+        return field.type === "array" && Array.isArray(value) ? value.map(match) : match(value);
+    }
+    return value;
 }
 
 /**
@@ -114,16 +92,16 @@ export function normalizeStoredValue(field, value) {
  * @returns {boolean} 是否为有效标量 / Whether the scalar is valid.
  */
 function scalar(value) {
-	switch (typeof value) {
-		case "boolean":
-			return true;
-		case "string":
-			return value.length <= 2048;
-		case "number":
-			return Number.isFinite(value);
-		default:
-			return false;
-	}
+    switch (typeof value) {
+        case "boolean":
+            return true;
+        case "string":
+            return value.length <= 2048;
+        case "number":
+            return Number.isFinite(value);
+        default:
+            return false;
+    }
 }
 
 /**
@@ -134,8 +112,8 @@ function scalar(value) {
  * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
  */
 export function validValue(field, value) {
-	if (field.type === "array") {
-		if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
-	} else if (typeof value !== field.type || !scalar(value)) return false;
-	return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
+    if (field.type === "array") {
+        if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
+    } else if (typeof value !== field.type || !scalar(value)) return false;
+    return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
 }

package/src/lib/response.mjs

@@ -0,0 +1,16 @@
+/**
+ * 统一生成不可缓存的响应，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/lib/settings-path.mjs

@@ -1,16 +1,3 @@
-import { URL } from "@nsnanocat/url";
-
-/**
- * 将 /api/ 后的 URL 路径转换为 util 的路径片段；非 API 路径不处理。
- * Convert URL segments after /api/ to util path segments; ignore non-API paths.
- * @param {string} url 请求完整 URL / Absolute request URL.
- * @returns {string[] | undefined} 键路径片段 / Key path segments.
- * @throws {TypeError} API 路径无效或包含危险片段 / Invalid or unsafe API path.
- */
-export function parseSettingsPath(url) {
-	return parseSettingsPathname(new URL(url).pathname);
-}
-
 /**
  * 解析已经取得的 pathname，避免重复构造 URL。
  * Parse an existing pathname without constructing another URL.
@@ -19,14 +6,14 @@ export function parseSettingsPath(url) {
  * @throws {TypeError} 转义编码或路径片段非法 / Invalid percent encoding or path segments.
  */
 export function parseSettingsPathname(pathname) {
-	if (!pathname.startsWith("/api/")) return;
-	let parts;
-	try {
-		parts = pathname.slice(5).replace(/\/$/, "").split("/").map(decodeURIComponent);
-	} catch {
-		throw new TypeError("Invalid encoded key path");
-	}
-	return validatePathParts(parts);
+    if (!pathname.startsWith("/api/")) return;
+    let parts;
+    try {
+        parts = pathname.slice(5).replace(/\/$/, "").split("/").map(decodeURIComponent);
+    } catch {
+        throw new TypeError("Invalid encoded key path");
+    }
+    return validatePathParts(parts);
 }
 
 /**
@@ -37,6 +24,6 @@ export function parseSettingsPathname(pathname) {
  * @throws {TypeError} 空片段、非法字符或原型属性名 / Empty segments, invalid characters or prototype property names.
  */
 export function validatePathParts(parts) {
-	if (!parts.every(part => typeof part === "string" && /^[a-zA-Z0-9_-]+$/.test(part) && !["__proto__", "prototype", "constructor"].includes(part))) throw new TypeError("Invalid key path");
-	return parts;
+    if (!parts.every(part => typeof part === "string" && /^[a-zA-Z0-9_-]+$/.test(part) && !["__proto__", "prototype", "constructor"].includes(part))) throw new TypeError("Invalid key path");
+    return parts;
 }

package/src/proxy/config.mjs

@@ -0,0 +1,14 @@
+import { response } from "../lib/response.mjs";
+import { complete } from "./response.mjs";
+
+/**
+ * 为没有原生远程 Mock 的代理返回 BoxJS JSON，不提供存储或页面处理。
+ * Return BoxJS JSON on proxies without native remote Mock, without storage or page handling.
+ * @param {unknown} config 构建时嵌入的 BoxJS JSON / BoxJS JSON embedded at build time.
+ * @returns {void} 将响应交给宿主 / Deliver the response to the host.
+ */
+export function mock(config) {
+    const method = globalThis.$request.method;
+    const allowed = method === "GET" || method === "HEAD";
+    complete(response(globalThis.$request, allowed ? 200 : 405, allowed ? config : { error: "Method not allowed" }));
+}

package/src/proxy/handler.mjs

@@ -1,31 +1,44 @@
-import { $app } from "@nsnanocat/util/lib/app.mjs";
-import { done } from "@nsnanocat/util/lib/done.mjs";
-import { qs } from "@nsnanocat/util/polyfill/qs.mjs";
-import { PreferencesHandler } from "../PreferencesHandler.mjs";
+import { URL } from "@nsnanocat/url";
+import assets from "#assets";
+import { BoxJS } from "../BoxJS.mjs";
+import { response } from "../lib/response.mjs";
+import { Store } from "../Store.mjs";
+import { complete } from "./response.mjs";
 
 /**
- * 执行独立代理脚本；安装映射由托管站点生成，或由宿主参数提供。
- * Run a standalone proxy script with a site-generated installation mapping or host arguments.
- * @param {import("../index.js").PreferencesHandlerOptions} [options] 安装映射 / Installation mapping.
- * @returns {Promise<void>} 已交给宿主的响应 / Response delivered to the proxy host.
+ * 仅为导入的模块提供页面与存储服务，项目主页由调用方自行托管。
+ * Serve only the imported module's page and persistence; callers host their own project landing pages.
+ * @param {unknown} boxjs BoxJS JSON / BoxJS JSON.
+ * @param {string} [css] 自定义 CSS 正文 / Custom CSS text.
+ * @returns {Promise<void>} 已提交宿主响应 / Delivered host response.
  */
-export async function runPreferences(options) {
-	let response;
-	try {
-		const config = options ?? qs.parse(globalThis.$argument);
-		const handler = new PreferencesHandler({ ...config, resources: config.resources ?? [] });
-		response = await handler.handle(globalThis.$request);
-	} catch (error) {
-		console.error(`PreferencePanes: ${error.message}`);
-		response = {
-			status: 500,
-			headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
-			body: globalThis.$request.method === "HEAD" ? "" : JSON.stringify({ error: "Settings execution failed" }),
-		};
-	}
-	if (!response) {
-		done({});
-		return;
-	}
-	done($app === "Quantumult X" ? response : { response });
+export async function run(boxjs, css = "") {
+    const request = globalThis.$request;
+    let result;
+    try {
+        if (typeof css !== "string") throw new TypeError("CSS must be a string");
+        const catalog = new BoxJS(boxjs);
+        const module = catalog.module.module;
+        const url = new URL(request.url);
+        switch (true) {
+            case url.pathname.startsWith("/api/"):
+                result = await new Store(catalog).handle(request, url);
+                break;
+            case url.pathname.startsWith("/configs/"):
+                break;
+            case url.pathname === `/settings/assets/${module}.css`:
+                result = response(request, 200, css, "text/css");
+                break;
+            default: {
+                const path = url.pathname === `/settings/${module}` || url.pathname === `/settings/${module}/` ? "page" : url.pathname;
+                const asset = assets[path];
+                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: "Settings execution failed" });
+    }
+    complete(result);
 }

package/src/proxy/response.mjs

@@ -0,0 +1,16 @@
+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 });
+}