@nsnanocat/preference-panes 0.6.0 → 0.7.1

package/src/browser/app.mjs

@@ -1,154 +1,36 @@
-import { validatePathParts } from "../lib/settings-path.mjs";
-import { createPreferencesClient } from "./client.mjs";
-import { mountPreferencePanes } from "./panel.mjs";
+import { BoxJS } from "../BoxJS.mjs";
+import { pageInputs } from "../lib/page-inputs.mjs";
+import { errorView } from "./components.mjs";
+import { mount } from "./index.mjs";
 
+let view;
 /**
- * 自包含页面入口，业务名称、图标和入口全部从站点 BoxJS JSON 读取。
- * Self-contained page entry reading all branding, icons and navigation from site BoxJS JSON.
- * @module @nsnanocat/preference-panes/site
+ * 从 URL 或代理传递的 Header 导入 JSON/CSS，支持独立文档与 srcdoc。
+ * Import JSON/CSS from the URL or proxy-carried headers in standalone and srcdoc documents.
+ * @returns {Promise<void>} 启动完成 / Startup completion.
  */
-const root = document.querySelector("#preferences");
-const client = createPreferencesClient({ timeout: 3500 });
-const theme = navigator.userAgent.match(/themeId\/(\d+)/)?.[1];
-if (theme) document.documentElement.dataset.theme = theme === "2" ? "dark" : "light";
-let panel,
-	menu,
-	revision = 0,
-	routedPath;
-
-/**
- * 创建只含纯文本的元素。
- * Create an element containing plain text only.
- * @param {string} tag 标签 / Tag.
- * @param {string} className 样式 / CSS class.
- * @param {string} [text] 文本 / Text.
- * @returns {HTMLElement} 元素 / Element.
- */
-function node(tag, className, text) {
-	const element = document.createElement(tag);
-	element.className = className;
-	if (text !== undefined) element.textContent = text;
-	return element;
+async function start() {
+    try {
+        view?.destroy();
+        view = undefined;
+        const context = document.querySelector('meta[name="preference-panes-inputs"]');
+        const inputs = context ? JSON.parse(decodeURIComponent(context.content)) : pageInputs(new URL(location.href));
+        const resources = [inputs.json, inputs.css].map(source => {
+            if (!source) return null;
+            const url = new URL(source, inputs.url);
+            if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
+            return url.href;
+        });
+        const [data, style] = await Promise.all(resources.map(url => (url ? fetch(url, { cache: "no-store", credentials: "omit" }) : null)));
+        if (data.status !== 200 || (style && style.status !== 200)) throw new Error(`HTTP ${data.status !== 200 ? data.status : style.status}`);
+        const boxjs = await data.json();
+        if (new BoxJS(boxjs).module.module !== inputs.module) throw new Error("Imported JSON does not match the module URL");
+        view = mount(boxjs, style ? await style.text() : "");
+    } catch (error) {
+        document.querySelector("#preferences").replaceChildren(errorView(error, start));
+    }
 }
-
-/**
- * 按站点 JSON 显示图标；iconDark 是明确的暗色扩展，不改变 BoxJS icons 语义。
- * Display configured icons; iconDark is an explicit dark variant without changing BoxJS icons semantics.
- * @param {{icon?:string,iconDark?:string,icons?:string[]}} metadata 图标数据 / Icon data.
- * @param {string} className 样式 / CSS class.
- * @returns {HTMLPictureElement} 图片元素 / Picture element.
- */
-function icon(metadata, className) {
-	const picture = node("picture", className),
-		image = node("img", "");
-	if (metadata.iconDark) {
-		const source = node("source", "");
-		source.media = theme ? (theme === "2" ? "all" : "not all") : "(prefers-color-scheme: dark)";
-		source.srcset = resourceURL(metadata.iconDark);
-		picture.append(source);
-	}
-	const selected = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
-	if (selected) image.src = resourceURL(selected);
-	image.alt = "";
-	picture.append(image);
-	return picture;
-}
-
-/**
- * 校验配置中的资源 URL。
- * Validate resource URLs in site configuration.
- * @param {string} value 地址 / Address.
- * @returns {string} 完整 URL / Absolute URL.
- */
-function resourceURL(value) {
-	const url = new URL(value, location.href);
-	if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S)");
-	return url.href;
-}
-
-/**
- * 挂载通用设置或站点菜单，每次进入菜单都重新 HEAD 探测。
- * Mount settings or the site menu, repeating HEAD probes on every menu entry.
- * @returns {Promise<void>} 挂载完成 / Mount completion.
- */
-async function render() {
-	routedPath = location.pathname;
-	const version = ++revision;
-	panel?.destroy();
-	panel = undefined;
-	root.replaceChildren();
-	if (routedPath !== "/settings/") {
-		document.title = routedPath.split("/")[2] || "Preferences";
-		panel = mountPreferencePanes({ element: root });
-		return;
-	}
-	try {
-		if (!menu) {
-			const response = await fetch("/settings/assets/site.boxjs.json", { cache: "no-store", credentials: "omit" });
-			if (response.status !== 200) throw new Error(`Site config HTTP ${response.status}`);
-			const data = await response.json();
-			if (typeof data.name !== "string" || !Array.isArray(data.apps)) throw new TypeError("Invalid site BoxJS JSON");
-			for (const app of data.apps) validatePathParts([app.module]);
-			const localStyles = document.head.querySelector('link[rel="stylesheet"]');
-			for (const href of data.stylesheets ?? []) {
-				const link = document.createElement("link");
-				link.rel = "stylesheet";
-				link.href = resourceURL(href);
-				document.head.insertBefore(link, localStyles);
-			}
-			menu = data;
-		}
-		if (version !== revision) return;
-		document.title = menu.name;
-		const home = node("section", "pp-home");
-		home.append(icon(menu, "brand-logo"), node("h1", "", menu.name));
-		const section = node("section", "self-panel is-zh");
-		section.append(node("h2", "header", menu.sectionTitle ?? "模块"));
-		const container = node("div", "container"),
-			scrollView = node("div", "scroll-view"),
-			rows = node("div", "scroll");
-		scrollView.append(rows);
-		container.append(scrollView);
-		section.append(container);
-		home.append(section);
-		if (menu.desc) home.append(node("p", "settings-note", menu.desc));
-		root.append(home);
-		for (const app of menu.apps) {
-			const button = node("button", "self-item is-zh"),
-				status = node("span", "module-status", "检测中");
-			button.type = "button";
-			button.disabled = true;
-			button.dataset.module = app.module;
-			button.append(icon(app, "logo"), node("span", "name", app.name ?? app.module), status);
-			rows.append(button);
-			button.onclick = () => {
-				history.pushState(null, "", `/settings/${app.module}`);
-				render();
-				if (!matchMedia("(prefers-reduced-motion: reduce)").matches) root.animate([{ transform: "translateX(100%)" }, { transform: "translateX(0)" }], { duration: 260, easing: "ease-out" });
-			};
-			client.probe(app.module).then(available => {
-				if (revision !== version) return;
-				button.disabled = !available;
-				status.textContent = available ? "" : "未响应";
-			});
-		}
-	} catch (error) {
-		if (version === revision) {
-			const retry = node("button", "", "重新读取");
-			retry.type = "button";
-			retry.onclick = render;
-			root.replaceChildren(node("p", "pp-site-error", `加载失败：${error.message}`), retry);
-		}
-	}
-}
-
-window.addEventListener("popstate", () => {
-	if (routedPath !== location.pathname) {
-		render();
-		if (location.pathname === "/settings/" && !matchMedia("(prefers-reduced-motion: reduce)").matches) root.animate([{ transform: "translateX(-100%)" }, { transform: "translateX(0)" }], { duration: 260, easing: "ease-out" });
-	}
-});
+start();
 window.addEventListener("pageshow", event => {
-	if (event.persisted && location.pathname === "/settings/") render();
+    if (event.persisted) start();
 });
-render();

package/src/browser/client.d.mts

@@ -0,0 +1,150 @@
+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 {
+    /**
+     * 包内从 BoxJS 推导的目录。
+     * Internal catalog derived from BoxJS.
+     */
+    catalog: { modules: ReadonlyMap<string, { storageKey: string }>; select(module: string): unknown };
+    /**
+     * 默认使用浏览器 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;
+}
+/**
+ * 会话的深拷贝快照，调用方修改不会影响缓存。
+ * Deep-cloned session snapshot; caller changes cannot alter the cache.
+ */
+export interface ModuleSnapshot {
+    /**
+     * 当前配置生成的模块定义
+     * Module definition generated from current config.
+     */
+    definition: ModuleDefinition;
+    /**
+     * 点分键到显示值的映射，已包含适用的默认值；持久化 null 原样保留。
+     * Dotted keys mapped to display values including applicable defaults; persisted null is preserved.
+     */
+    values: Record<string, SettingsScalar | SettingsScalar[] | null>;
+}
+/**
+ * 只在页面存活期间维护模块缓存的通用客户端。
+ * Generic client maintaining module caches only during the page lifetime.
+ */
+export interface PreferencesClient {
+    /**
+     * 使用已导入的 JSON 替换会话，只读取一次设置值。
+     * Replace the session from imported JSON and read stored settings once.
+     * @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>;
+}
+/**
+ * 创建包内客户端，接管请求和会话。
+ * Create an internal client for requests and sessions.
+ * @param options 包内目录与运行环境 / Internal catalog and runtime environment.
+ * @returns 会话客户端 / Session client.
+ */
+export function createPreferencesClient(options: PreferencesClientOptions): PreferencesClient;