@nsnanocat/preference-panes 0.6.0 → 0.7.1

package/package.json

@@ -1,69 +1,68 @@
 {
-	"name": "@nsnanocat/preference-panes",
-	"version": "0.6.0",
-	"description": "Shared settings API runtime for JavaScript proxy modules",
-	"author": "VirgilClyne <Virgil@nanocat.me>",
-	"homepage": "https://NSNanoCat.github.io/preference-panes",
-	"keywords": [
-		"loon",
-		"quantumult",
-		"surge",
-		"shadowrocket",
-		"stash",
-		"egern",
-		"settings"
-	],
-	"license": "Apache-2.0",
-	"bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
-	"type": "module",
-	"main": "src/index.mjs",
-	"exports": {
-		".": {
-			"types": "./src/index.d.ts",
-			"import": "./src/index.mjs"
-		},
-		"./browser": {
-			"types": "./src/browser/index.d.ts",
-			"import": "./src/browser/index.mjs"
-		},
-		"./browser/panel.css": "./src/browser/panel.css",
-		"./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
-		"./dist/preference-panes.request.js": "./dist/preference-panes.request.js",
-		"./dist/preference-panes.proxy.js": "./dist/preference-panes.proxy.js",
-		"./dist/preference-panes.config.js": "./dist/preference-panes.config.js",
-		"./dist/settings/*": "./dist/settings/*"
-	},
-	"types": "src/index.d.ts",
-	"scripts": {
-		"test": "node --test test/*.test.mjs",
-		"check": "npm run lint && npm run typecheck && npm test",
-		"lint": "biome check .",
-		"format": "biome check --write .",
-		"typecheck": "tsc --noEmit",
-		"build": "rollup -c",
-		"prepack": "npm run build",
-		"apifox:generate": "node apifox/generate.mjs",
-		"apifox:check": "node apifox/generate.mjs --check"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
-	},
-	"files": [
-		"src",
-		"dist"
-	],
-	"dependencies": {
-		"@nsnanocat/url": "^1.2.6",
-		"@nsnanocat/util": "^2.7.4"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.4.6",
-		"@rollup/plugin-node-resolve": "^16.0.3",
-		"rollup": "^4.63.1",
-		"typescript": "^5.9.3"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
+    "name": "@nsnanocat/preference-panes",
+    "version": "0.7.1",
+    "description": "Shared settings API runtime for JavaScript proxy modules",
+    "author": "VirgilClyne <Virgil@nanocat.me>",
+    "homepage": "https://NSNanoCat.github.io/preference-panes",
+    "keywords": [
+        "loon",
+        "quantumult",
+        "surge",
+        "shadowrocket",
+        "stash",
+        "egern",
+        "settings"
+    ],
+    "license": "Apache-2.0",
+    "bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
+    "type": "module",
+    "main": "src/index.mjs",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "import": "./src/index.mjs"
+        },
+        "./browser": {
+            "types": "./src/browser/index.d.ts",
+            "import": "./dist/preference-panes.mjs"
+        },
+        "./navigation": {
+            "types": "./src/browser/Navigation.d.mts",
+            "import": "./dist/module/navigation.mjs"
+        }
+    },
+    "types": "src/index.d.ts",
+    "scripts": {
+        "test": "node --test test/*.test.mjs",
+        "pretest": "npm run build",
+        "check": "npm run lint && npm run typecheck && npm test",
+        "lint": "biome check .",
+        "format": "biome check --write .",
+        "typecheck": "tsc --noEmit",
+        "build": "rollup -c",
+        "prebuild": "node --input-type=module -e \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+        "prepack": "npm run build",
+        "preview": "npm run build && node examples/preview.mjs",
+        "apifox:generate": "node apifox/generate.mjs",
+        "apifox:check": "node apifox/generate.mjs --check"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
+    },
+    "files": [
+        "src",
+        "dist"
+    ],
+    "devDependencies": {
+        "@biomejs/biome": "2.1.4",
+        "@nsnanocat/url": "^1.2.6",
+        "@nsnanocat/util": "^2.7.4",
+        "@rollup/plugin-node-resolve": "^16.0.3",
+        "rollup": "^4.63.1",
+        "typescript": "^5.9.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/BoxJS.mjs

@@ -0,0 +1,86 @@
+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");
+        this.document = JSON.parse(JSON.stringify(input));
+        const apps = Array.isArray(this.document) ? [{ settings: this.document }] : (this.document.apps ?? [this.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(this.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(this.document) ? {} : this.document);
+        for (const target of this.modules.values()) target.metadata = target.owners.size === 1 ? metadata([...target.owners][0]) : {};
+    }
+
+    /**
+     * 提取一个模块的原生 BoxJS，保留所属 app 的元数据。
+     * Select a module's native BoxJS while retaining owning-app metadata.
+     * @param {string} module 模块标识 / Module identifier.
+     * @returns {unknown} 可直接用作配置 Mock 的 JSON / JSON suitable for a configuration Mock.
+     */
+    select(module) {
+        const target = this.modules.get(module);
+        if (!target) throw new TypeError(`No BoxJS settings for module: ${module}`);
+        if (Array.isArray(this.document)) return target.entries;
+        const apps = [...target.owners].map(app => ({ ...app, settings: app.settings.filter(entry => target.entries.includes(entry)) }));
+        return this.document.apps ? { ...this.document, apps } : apps[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

@@ -0,0 +1,127 @@
+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 { parseSettingsPathname } from "./lib/settings-path.mjs";
+
+/**
+ * 根据 BoxJS 目录桥接持久化存储，不下载配置或解析控件。
+ * Bridge persistence using the BoxJS catalog without downloading configuration or interpreting controls.
+ */
+export class Store {
+    #catalog;
+
+    /**
+     * 复用包内已解析的目录，构造时不访问网络或存储。
+     * Reuse the parsed internal catalog without network or persistence access during construction.
+     * @param {import("./BoxJS.mjs").BoxJS} catalog BoxJS 路径目录 / BoxJS path catalog.
+     */
+    constructor(catalog) {
+        this.#catalog = catalog;
+    }
+
+    /**
+     * GET 返回指定值，POST 替换指定值，DELETE 删除指定键或整个模块。
+     * GET returns a value, POST replaces it, and DELETE removes a key or the entire module.
+     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+     * @param {URL} [url] 包内复用的已解析地址 / Parsed URL reused within the package.
+     * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 响应或非接管请求 / Response, or undefined for an unhandled request.
+     */
+    async handle(request, url = new URL(request.url)) {
+        if (!url.pathname.startsWith("/api/")) return;
+        const reply = (status, data) => response(request, status, data);
+        let parts;
+        try {
+            parts = parseSettingsPathname(url.pathname);
+        } catch (error) {
+            return reply(400, { error: error.message });
+        }
+        const binding = this.#catalog.modules.get(parts[0]);
+        if (!binding) return reply(404, { error: "Module is not declared in BoxJS" });
+        const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+        if (requestHeaders["x-settings-client"] !== "1" || (requestHeaders.origin && requestHeaders.origin !== url.origin)) return reply(403, { error: "Forbidden settings client" });
+        let value;
+        switch (request.method) {
+            case "HEAD":
+                return reply(200, undefined);
+            case "GET":
+            case "DELETE":
+                break;
+            case "POST":
+                if (requestHeaders["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") return reply(415, { error: "Expected application/json" });
+                if (typeof request.body !== "string") return reply(400, { error: "Expected a JSON string body" });
+                if (request.body.length > 65536) return reply(413, { error: "Body exceeds 65536 UTF-16 code units" });
+                try {
+                    value = JSON.parse(request.body);
+                } catch {
+                    return reply(400, { error: "Invalid JSON" });
+                }
+                break;
+            default:
+                return { ...reply(405, { error: "Method not allowed" }), headers: { ...reply(405).headers, Allow: "HEAD, GET, POST, DELETE" } };
+        }
+        try {
+            const root = Storage.getItem(binding.storageKey, {});
+            if (!isRecord(root)) throw new TypeError("stored root must be an object");
+            const parent = storageParent(root, parts, request.method === "POST");
+            const key = parts.at(-1);
+            switch (request.method) {
+                case "GET": {
+                    const result = parent ? _.get(parent, [key]) : undefined;
+                    return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+                }
+                case "POST":
+                    _.set(parent, [key], value);
+                    break;
+                case "DELETE":
+                    if (parent) _.unset(parent, [key]);
+                    break;
+            }
+            if (!Storage.setItem(binding.storageKey, root)) throw new Error("Storage write failed");
+            return reply(200, request.method === "POST" ? { 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/browser/Navigation.d.mts

@@ -0,0 +1,43 @@
+/**
+ * 同一文档的根页/子页导航，不定义页面布局或模块业务。
+ * Home/detail navigation within a document, without layout or module business rules.
+ */
+export class Navigation extends EventTarget {
+    /**
+     * 挂载根页并按 URL 创建子页；容器负责页面定位与背景样式。
+     * Mount home and resolve details from the URL; the container owns positioning and backgrounds.
+     * @param container 页面容器 / View container.
+     * @param home 根页节点 / Home node.
+     * @param create 子页工厂，signal 在离开时取消 / Detail factory; signal aborts on departure.
+     */
+    constructor(container: HTMLElement, home: HTMLElement, create: (key: string, signal: AbortSignal) => HTMLElement | undefined);
+    /**
+     * 当前键；空字符串表示根页。
+     * Current key; empty means home.
+     */
+    readonly current: string;
+    /**
+     * 是否可以后退。
+     * Whether back navigation is available.
+     */
+    readonly canGoBack: boolean;
+    /**
+     * 前进到子页。
+     * Navigate to a detail.
+     * @param key 子页键 / Detail key.
+     * @returns 无返回值 / No return value.
+     */
+    open(key: string): void;
+    /**
+     * 沿联合历史后退。
+     * Go back through joint history.
+     * @returns 无返回值 / No return value.
+     */
+    back(): void;
+    /**
+     * 释放加载、监听器与视图。
+     * Release loads, listeners and views.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
+}

package/src/browser/Navigation.mjs

@@ -0,0 +1,158 @@
+/**
+ * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
+ * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
+ */
+export class Navigation extends EventTarget {
+    #container;
+    #home;
+    #create;
+    #window;
+    #key = null;
+    #view;
+    #retiring;
+    #controller;
+    #animation;
+    #scroll = new WeakMap();
+    #onHistory = () => this.#route();
+    #onPageShow = event => {
+        if (event.persisted) this.#route(true);
+    };
+
+    /**
+     * 根视图始终保留；工厂按需提供子页，可用 signal 取消离开后的异步加载。
+     * Retain the home view and create details on demand; signal cancels async work after departure.
+     * @param {HTMLElement} container 由调用方布局的页面容器 / Caller-styled view container.
+     * @param {HTMLElement} home 已创建的主页节点 / Existing home view.
+     * @param {(key: string, signal: AbortSignal) => HTMLElement | undefined} create 子页工厂；未知路径返回 undefined / Detail factory; undefined for unknown routes.
+     */
+    constructor(container, home, create) {
+        super();
+        this.#container = container;
+        this.#home = home;
+        this.#create = create;
+        this.#window = container.ownerDocument.defaultView;
+        container.replaceChildren(home);
+        this.#window.addEventListener("popstate", this.#onHistory);
+        this.#window.addEventListener("hashchange", this.#onHistory);
+        this.#window.addEventListener("pageshow", this.#onPageShow);
+        this.#route();
+    }
+
+    /**
+     * 当前子页键；空字符串表示主页。
+     * Current detail key; empty means home.
+     */
+    get current() {
+        return this.#key;
+    }
+
+    /**
+     * 是否可以返回上一级或先前文档。
+     * Whether a parent view or previous document is available.
+     */
+    get canGoBack() {
+        return Boolean(this.#key) || this.#window.history.length > 1;
+    }
+
+    /**
+     * 加入子页历史；使用文档自身 URL，避免 srcdoc 按宿主 base URL 跳转。
+     * Push a detail using the document URL, avoiding srcdoc navigation against the host base URL.
+     * @param {string} key 子页键 / Detail key.
+     * @returns {void} 无返回值 / No return value.
+     */
+    open(key) {
+        if (key === this.#key) return;
+        const url = new URL(this.#window.location.href);
+        url.hash = encodeURIComponent(key);
+        this.#window.history.pushState({ ...this.#window.history.state, preferencePanesRoute: key }, "", url.href);
+        this.#route();
+    }
+
+    /**
+     * 沿浏览器联合历史返回，根页可退回宿主或上个文档。
+     * Go back through joint history, including a host or previous document from home.
+     * @returns {void} 无返回值 / No return value.
+     */
+    back() {
+        if (this.canGoBack) this.#window.history.back();
+    }
+
+    /**
+     * 解析 URL 并统一处理页面切换、加载取消与动画结束后的释放。
+     * Resolve the URL and coordinate transitions, cancellation and release after animation.
+     * @param {boolean} [reload] 从页面缓存恢复时重新创建子页 / Recreate a detail after bfcache restoration.
+     * @returns {void} 无返回值 / No return value.
+     */
+    #route(reload = false) {
+        const url = new URL(this.#window.location.href);
+        let key;
+        try {
+            key = decodeURIComponent(url.hash.slice(1));
+        } catch (error) {
+            if (!(error instanceof URIError)) throw error;
+            key = "";
+        }
+        if (!reload && key === this.#key) return;
+        this.#controller?.abort();
+        this.#controller = new AbortController();
+        const next = key ? this.#create(key, this.#controller.signal) : undefined;
+        if (!next) key = "";
+        const history = this.#window.history;
+        // 直接打开子页时建立一次主页历史；刷新不重复堆叠。
+        // Seed home history once for direct details, without stacking entries on reload.
+        if (url.hash && history.state?.preferencePanesRoute !== key) {
+            url.hash = "";
+            history.replaceState({ ...history.state, preferencePanesRoute: "" }, "", url.href);
+            if (key) {
+                url.hash = encodeURIComponent(key);
+                history.pushState({ ...history.state, preferencePanesRoute: key }, "", url.href);
+            }
+        }
+        const previous = this.#view;
+        const position = previous ? this.#window.getComputedStyle(previous).transform : "none";
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#retiring = previous;
+        if (previous) {
+            this.#scroll.set(previous, previous.scrollTop);
+            previous.inert = true;
+        }
+        this.#key = key;
+        this.#view = next;
+        this.#home.inert = Boolean(next);
+        if (next) {
+            next.inert = false;
+            this.#container.append(next);
+            next.scrollTop = this.#scroll.get(next) ?? 0;
+        }
+        const moving = next ?? previous;
+        if (moving) {
+            const animation = moving.animate([{ transform: next ? "translateX(100%)" : position }, { transform: next ? "translateX(0)" : "translateX(100%)" }], { duration: this.#window.matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : 280, easing: "cubic-bezier(.22,.61,.36,1)", fill: "forwards" });
+            this.#animation = animation;
+            animation.onfinish = () => {
+                if (this.#animation !== animation) return;
+                this.#retiring?.remove();
+                this.#retiring = undefined;
+                animation.cancel();
+                this.#animation = undefined;
+            };
+        }
+        this.dispatchEvent(new Event("change"));
+    }
+
+    /**
+     * 释放监听器、加载、动画和节点；调用方可重新创建导航。
+     * Release listeners, loads, animations and nodes so callers can recreate navigation.
+     * @returns {void} 无返回值 / No return value.
+     */
+    destroy() {
+        this.#window.removeEventListener("popstate", this.#onHistory);
+        this.#window.removeEventListener("hashchange", this.#onHistory);
+        this.#window.removeEventListener("pageshow", this.#onPageShow);
+        this.#controller?.abort();
+        this.#animation?.cancel();
+        this.#retiring?.remove();
+        this.#view?.remove();
+        this.#home.remove();
+    }
+}