@nsnanocat/preference-panes 0.6.0 → 0.7.0

package/src/browser/components.mjs

@@ -0,0 +1,59 @@
+/**
+ * 创建元素，所有展示文本通过 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.
+ */
+export function element(tag, className, text) {
+    const node = document.createElement(tag);
+    node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+}
+
+/**
+ * 元数据地址只允许 HTTP(S) 和相对地址。
+ * Allow only HTTP(S) and relative metadata addresses.
+ * @param {string} value 元数据地址 / Metadata address.
+ * @returns {string} 完整地址 / Absolute address.
+ */
+export function resourceURL(value) {
+    const url = new URL(value, location.href);
+    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Metadata URLs must use HTTP(S)");
+    return url.href;
+}
+
+/**
+ * 展示标准 BoxJS 图标；icons 保持透明/彩色语义，不解释为亮暗版本。
+ * Display standard BoxJS icons, preserving transparent/color rather than light/dark semantics.
+ * @param {import("../index.js").BoxJSMetadata} metadata 展示信息 / Presentation metadata.
+ * @param {string} className 样式 / CSS class.
+ * @returns {HTMLImageElement | null} 图标或无图标 / Icon or no icon.
+ */
+export function icon(metadata, className) {
+    const source = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
+    if (!source) return null;
+    const image = element("img", className);
+    image.src = resourceURL(source);
+    image.alt = "";
+    return image;
+}
+
+/**
+ * 共享加载失败视图，不创建配置表单或数据读取。
+ * Share a load-error view without creating controls or reading settings.
+ * @param {Error} error 失败原因 / Failure reason.
+ * @param {() => unknown} retry 重试动作 / Retry action.
+ * @returns {HTMLElement} 错误视图 / Error view.
+ */
+export function errorView(error, retry) {
+    const view = element("section", "pp-error");
+    const button = element("button", "", "重新读取");
+    button.type = "button";
+    button.onclick = retry;
+    view.append(element("p", "", `加载失败：${error.message}`), button);
+    return view;
+}

package/src/browser/index.d.ts

@@ -1,155 +1,22 @@
-import type { ModuleDefinition, SettingsScalar } from "../index.js";
-/**
- * 单键写入或删除的通知事件，携带对应模块与点分键路径。
- * Notification for a single-key write or delete, including module and dotted key path.
- */
-export interface Notification {
-	/** 结果类别 / Result kind. */
-	kind: "success" | "error";
-	/** 操作类别 / Operation kind. */
-	operation: "write" | "delete" | "clearCaches" | "reset";
-	/** 模块标识 / Module identifier. */
-	module: string;
-	/** 含模块名、不含存储根的点分路径 / Dotted path including the module but excluding the storage root. */
-	key: string;
-	/** 失败原因，仅错误事件提供 / Failure reason, provided for errors only. */
-	message?: string;
-}
-/**
- * 浏览器会话客户端选项。
- * Options for the browser session client.
- */
-export interface PreferencesClientOptions {
-	/** 默认使用浏览器 fetch，可注入同签名传输 / Defaults to browser fetch; an equivalent transport may be supplied. */
-	fetch?: typeof globalThis.fetch;
-	/** 成功写入或失败时调用，不用于读取事件 / Called for successful mutations or failures, not reads. */
-	notify?: (notification: Notification) => void;
-	/** 单次请求超时，单位毫秒，默认 10000 / Per-request timeout in milliseconds; defaults to 10000. */
-	timeout?: number;
+import type { BoxJSInput } from "../index.js";
+
+/**
+ * 具体模块设置页的生命周期句柄。
+ * Lifecycle handle for a concrete module settings page.
+ */
+export interface MountedPreferences {
+    /**
+     * 移除页面、样式、监听器和临时会话。
+     * Remove the page, styles, listeners and transient sessions.
+     * @returns 无返回值 / No return value.
+     */
+    destroy(): void;
 }
 /**
- * 会话的深拷贝快照，调用方修改不会影响缓存。
- * Deep-cloned session snapshot; caller changes cannot alter the cache.
- */
-export interface ModuleSnapshot {
-	/** 当前配置生成的模块定义 / Module definition generated from current config. */
-	definition: ModuleDefinition;
-	/** 点分键到显示值的映射，已包含适用的默认值 / Dotted keys mapped to display values including applicable defaults. */
-	values: Record<string, SettingsScalar | SettingsScalar[]>;
-}
-/**
- * 只在页面存活期间维护模块缓存的通用客户端。
- * Generic client maintaining module caches only during the page lifetime.
- */
-export interface PreferencesClient {
-	/**
-	 * HEAD 探测配置 Mock，不读取持久化数据。
-	 * Probe the config Mock with HEAD without reading persistence.
-	 * @param module 模块标识 / Module identifier.
-	 * @returns 仅 HTTP 200 为 true；无效模块或请求失败为 false / True only for HTTP 200; false for invalid modules or failed requests.
-	 */
-	probe(module: string): Promise<boolean>;
-	/**
-	 * 替换会话，各读取一次配置与设置子树。
-	 * Replace the session and fetch config and settings subtree once each.
-	 * @param module 模块标识 / Module identifier.
-	 * @returns 新会话的独立快照 / Independent snapshot of the new session.
-	 * @throws {Error} 写入进行中、请求或配置无效、会话被替换 / Active write, invalid request or config, or replaced session.
-	 */
-	open(module: string): Promise<ModuleSnapshot>;
-	/**
-	 * 获取已打开模块的快照，不发请求。
-	 * Get a snapshot of an open module without network requests.
-	 * @param module 模块标识 / Module identifier.
-	 * @returns 深拷贝快照 / Deep-cloned snapshot.
-	 * @throws {Error} 模块尚未打开 / Module has not been opened.
-	 */
-	snapshot(module: string): ModuleSnapshot;
-	/**
-	 * 取消未完成的读取并移除缓存，不撤销已发送的写入。
-	 * Abort pending reads and discard the cache without undoing dispatched writes.
-	 * @param module 模块标识 / Module identifier.
-	 * @returns 无返回值 / No return value.
-	 */
-	leave(module: string): void;
-	/**
-	 * POST 单个字段，HTTP 200 后更新缓存，不追加 GET。
-	 * POST one field and update its cache only on HTTP 200, without a follow-up GET.
-	 * @param module 已打开的模块 / Open module.
-	 * @param key 完整点分字段路径 / Complete dotted field path.
-	 * @param value 符合字段类型和选项的值 / Value matching the field type and choices.
-	 * @returns 操作完成 / Completion of the operation.
-	 * @throws {Error} 会话、值、并发写入或网络错误 / Session, value, concurrent-write or network error.
-	 */
-	set(module: string, key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;
-	/**
-	 * DELETE 单个覆盖值，HTTP 200 后显示默认值，不追加 GET。
-	 * DELETE an override and display its default after HTTP 200, without a follow-up GET.
-	 * @param module 已打开的模块 / Open module.
-	 * @param key 完整点分字段路径 / Complete dotted field path.
-	 * @returns 操作完成 / Completion of the operation.
-	 * @throws {Error} 会话、路径、并发写入或网络错误 / Session, path, concurrent-write or network error.
-	 */
-	remove(module: string, key: string): Promise<void>;
-	/**
-	 * 按需读取整个模块 Caches，不刷新设置。
-	 * Read all module Caches on demand without refreshing settings.
-	 * @param module 已打开模块 / Open module.
-	 * @returns 缓存 JSON 值，缺失时为 undefined / Cache JSON value, or undefined when absent.
-	 */
-	readCaches(module: string): Promise<unknown>;
-	/**
-	 * 删除模块 Caches 并更新相关页面状态，不追加 GET。
-	 * Delete module Caches and update related page state without a follow-up GET.
-	 * @param module 已打开模块 / Open module.
-	 * @returns 清理完成 / Cleanup completion.
-	 */
-	clearCaches(module: string): Promise<void>;
-	/**
-	 * 删除整个模块持久化数据，页面使用当前 BoxJS 默认值。
-	 * Delete all module persistence and use current BoxJS defaults on the page.
-	 * @param module 已打开模块 / Open module.
-	 * @returns 重置完成 / Reset completion.
-	 */
-	reset(module: string): Promise<void>;
-}
-/**
- * WebView 面板的挂载选项，模块标识从页面路径读取。
- * Mount options for the WebView panel; the module is read from the page path.
- */
-export interface PreferencesPanelOptions {
-	/** 具有浏览器 window 的挂载元素 / Mount element owned by a document with a browser window. */
-	element: HTMLElement;
-	/** 无有效模块时的标题，默认 Preferences / Title without a valid module; defaults to Preferences. */
-	title?: string;
-	/** 可选浏览器请求传输 / Optional browser request transport. */
-	fetch?: typeof globalThis.fetch;
-}
-/**
- * 面板生命周期控制句柄。
- * Handle controlling the panel lifecycle.
- */
-export interface PreferencesPanel {
-	/**
-	 * 移除事件、面板与定时器，并取消当前读取。
-	 * Remove listeners, panel and timers, and abort the current read.
-	 * @returns 无返回值 / No return value.
-	 */
-	destroy(): void;
-}
-/**
- * 创建模块会话客户端，不立即发出请求。
- * Create a module session client without immediately making requests.
- * @param options 请求、通知和超时选项 / Request, notification and timeout options.
- * @returns 通用客户端 / Generic client.
- */
-export function createPreferencesClient(options?: PreferencesClientOptions): PreferencesClient;
-/**
- * 按 /settings/{module} 挂载动态面板，监听导航和页面恢复事件。
- * Mount a dynamic panel at /settings/{module} and observe navigation and page restoration.
- * 控件变化即时串行写入；多选用二级页，返回不重新读取设置。
- * Control changes save immediately in sequence; multi-select uses a secondary page without refetching on return.
- * @param options 挂载选项 / Mount options.
- * @returns 面板生命周期句柄 / Panel lifecycle handle.
+ * 仅以 BoxJS 和可选 CSS 挂载一个模块页，不生成项目主页。
+ * Mount one module page using BoxJS and optional CSS, without a project landing page.
+ * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
+ * @param css 可选 CSS 正文；默认样式始终内置 / Optional CSS text; default styles are built in.
+ * @returns 生命周期句柄 / Lifecycle handle.
  */
-export function mountPreferencePanes(options: PreferencesPanelOptions): PreferencesPanel;
+export function mount(boxjs: BoxJSInput, css?: string): MountedPreferences;

package/src/browser/index.mjs

@@ -1,7 +1,62 @@
+import defaults from "#styles";
+import { BoxJS } from "../BoxJS.mjs";
+import { element, resourceURL } from "./components.mjs";
+import { mountPanel } from "./panel.mjs";
+
 /**
- * WebView 面板与页面会话客户端的公开入口。
- * Public entry for the WebView panel and page session client.
- * @module @nsnanocat/preference-panes/browser
+ * 只挂载导入 JSON 对应的模块设置页，默认样式内置，CSS 仅用于该页。
+ * Mount only the imported module's settings page with built-in defaults and optional page CSS.
+ * @param {import("../index.js").BoxJSInput} boxjs 单个模块的 BoxJS JSON / BoxJS JSON for one module.
+ * @param {string} [css] 可选 CSS 正文 / Optional CSS text.
+ * @returns {import("./index.js").MountedPreferences} 模块生命周期句柄 / Module lifecycle handle.
  */
-export { createPreferencesClient } from "./client.mjs";
-export { mountPreferencePanes } from "./panel.mjs";
+export function mount(boxjs, css = "") {
+    if (typeof css !== "string") throw new TypeError("CSS must be a string");
+    const catalog = new BoxJS(boxjs);
+    const metadata = catalog.module.metadata;
+    const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
+    if (image) resourceURL(image);
+    if (metadata.repo) resourceURL(metadata.repo);
+    const existing = document.querySelector("#preferences");
+    const root = existing ?? element("main", "");
+    if (!existing) {
+        root.id = "preferences";
+        document.body.append(root);
+    }
+    const base = element("style", ""),
+        custom = element("style", "");
+    base.textContent = defaults;
+    custom.textContent = css;
+    document.head.append(base, custom);
+    const previousTitle = document.title;
+    const previousTheme = document.documentElement.dataset.theme;
+    const theme = navigator.userAgent.match(/themeId\/(\d+)/)?.[1];
+    if (theme) document.documentElement.dataset.theme = theme === "2" ? "dark" : "light";
+    document.title = metadata.name ?? catalog.module.module;
+    let panel;
+    const view = {
+        /**
+         * 释放模块视图、样式与会话，不操作项目入口页。
+         * Release the module view, styles and session without operating a project landing page.
+         * @returns {void} 无返回值 / No return value.
+         */
+        destroy() {
+            panel?.destroy();
+            base.remove();
+            custom.remove();
+            if (existing) root.replaceChildren();
+            else root.remove();
+            document.title = previousTitle;
+            if (previousTheme === undefined) delete document.documentElement.dataset.theme;
+            else document.documentElement.dataset.theme = previousTheme;
+        },
+    };
+    try {
+        root.replaceChildren();
+        panel = mountPanel(root, catalog);
+        return view;
+    } catch (error) {
+        view.destroy();
+        throw error;
+    }
+}

package/src/browser/module.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+        <meta name="color-scheme" content="light dark">
+        <title>Module Preferences</title>
+        <style>body { margin: 0; }</style>
+    </head>
+    <body>
+        <main id="preferences"></main>
+        <script type="module" src="/settings/assets/app.mjs?v=__VERSION__"></script>
+    </body>
+</html>