@nsnanocat/preference-panes 0.3.0 → 0.4.0

package/README.md

@@ -7,6 +7,7 @@
 | 目录 | 内容 |
 | --- | --- |
 | src/SettingsHandler.mjs | 模块存储桥接 class |
+| src/PreferencesHandler.mjs | 存储桥接与声明式静态资源响应 |
 | src/browser/ | WebView 控件、内存会话和样式 |
 | src/lib/ | 前端 BoxJS 与通用路径解析 |
 | src/proxy/ | 代理宿主打包入口 |
@@ -62,9 +63,47 @@ const panel = mountPreferencePanes({ element: document.querySelector("#preferenc
 
 每次进入主菜单仅并发 HEAD 各配置 Mock。打开、再次进入或刷新模块页，各 GET 一次 BoxJS 与设置子树；404 的设置子树按无覆盖值处理。保存/删除根据 HTTP 200 更新页面缓存并显示通知，不追加 GET。
 
+设置页使用分组行布局：单选为下拉框，开关为即时切换，多选显示摘要并进入可前进/后退的二级选项页。文本输入、下拉选择及勾选变化均立即串行 POST，无逐项保存或删除按钮；失败恢复当前项已保存值，较新的输入不会被较早请求覆盖。多选页返回时保留主列表滚动位置，不重新 GET 配置。单键 DELETE 能力保留在 API/客户端方法中，不作为逐项页面按钮展示。
+
 模块页底部提供查看/刷新 Caches、清空 Caches 和重置模块。查看缓存按需 GET；清空和重置经确认后 DELETE，成功只更新本页状态。重置后控件显示当前 BoxJS 默认值，再次进入页面才重新读取。模块选择、设置值校验和默认值处理都在前端完成。
 
-业务主菜单由调用项目维护，Biliverse 的入口和四个模块按钮归 Enhanced。未提供对应配置 Mock 的插件入口保持禁用。
+主菜单、导航、控件和样式均由本包实现。调用项目只提供品牌与模块 JSON，不需要维护 HTML、页面 JS、CSS 或专用 Rollup 配置。未提供对应配置 Mock 的插件入口保持禁用。
+
+## 零前端代码接入
+
+部署本包的 `dist/settings/` 到 `/settings/assets/`，将其中 index.html 同时用于 `/settings/` 与 `/settings/{module}`。根菜单读取同目录的 `site.boxjs.json`：
+
+~~~json
+{
+  "name": "Example",
+  "icon": "/assets/logo.png",
+  "sectionTitle": "模块",
+  "apps": [{ "module": "Module", "name": "Example Module", "icon": "/assets/module.png" }]
+}
+~~~
+
+`apps[].module` 明确对应 `/settings/{module}`、`/configs/{module}` 和 `/api/{module}/`，不从名称推断。这个菜单 JSON 只声明入口；实际字段仍从配置 Mock 返回的 BoxJS 生成。菜单可选 `desc`、`iconDark` 和 `stylesheets`；`iconDark` 是显式暗色图标扩展，不能把 BoxJS 的透明/彩色 icons 当成亮暗版本。stylesheets 仅加载接入方指定的 HTTP(S) 样式，不加载业务 JS。
+
+根页面每次进入重新 HEAD 探测，菜单 JSON 在当前文档只读取一次；模块页直接打开时无需先读菜单。图片与额外样式由托管站点提供。
+
+代理优先使用原生 Mock 提供配置和页面。需要请求脚本响应静态资源的平台，直接使用本包的 PreferencesHandler，安装参数也可放在 JSON 中：
+
+~~~js
+import { PreferencesHandler } from "@nsnanocat/preference-panes";
+
+const handler = new PreferencesHandler({
+  origin: "https://example.org",
+  storageKey: "Root",
+  module: "Module",
+  resources: [
+    { pattern: "^/configs/Module$", source: "https://example.org/settings/assets/Module.boxjs.json", contentType: "application/json" },
+    { pattern: "^/settings/(?:[a-zA-Z0-9_-]+/?)?$", source: "https://example.org/settings/assets/index.html", contentType: "text/html" }
+  ]
+});
+const response = await handler.handle($request);
+~~~
+
+资源 pattern 匹配 pathname，下载源必须避开拦截路径。只有命中静态资源的 GET/HEAD 才下载文件；API 由 SettingsHandler 直接处理，读写不会下载 BoxJS。接入方保留宿主请求入口和原生 Mock 规则，将响应交给现有 done 适配；无需自行实现路由、fetch、控件或持久化操作。
 
 ## BoxJS 兼容
 
@@ -90,6 +129,6 @@ npm run apifox:check
 npm pack --dry-run
 ~~~
 
-构建生成 dist/preference-panes.mjs 和 dist/preference-panes.request.js；公开 import 路径由 exports 保持稳定。0.3.0 的安装参数替换 0.2.0 的 configURL，HTTP 读写从声明字段变为模块内的任意数据，是一次契约升级。
+构建生成 dist/preference-panes.mjs、dist/preference-panes.request.js，以及可直接部署的 dist/settings/{index.html,app.mjs,panel.css,home.css}。静态文件也通过 `@nsnanocat/preference-panes/dist/settings/*` 导出，托管仓库直接从依赖包复制，不读取业务插件的前端构建目录。0.4.0 增加完整页面与资源处理器，保留 0.3.1 的存储契约和页面交互。
 
 [完整接口说明](apifox/guide.md) · [Apifox JSON](apifox/preference-panes.apifox.json) · [同步方式](apifox/README.md) · [发布工作流](.github/RELEASING.md)

package/dist/preference-panes.mjs

@@ -400,17 +400,19 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 	};
 	const shell = node("div", "pp-panel");
 	const header = node("header", "pp-header");
-	const back = node("button", "pp-back", "返回");
+	const back = node("button", "pp-back", "‹");
+	back.setAttribute("aria-label", "返回");
 	back.type = "button";
 	const heading = node("h1", "pp-title", title);
 	const viewport = node("div", "pp-viewport");
 	const toast = node("div", "pp-toast");
 	toast.setAttribute("role", "status");
 	toast.hidden = true;
-	header.append(back, heading);
+	header.append(back, heading, node("span", "pp-nav-spacer"));
 	shell.append(header, viewport, toast);
 	root.append(shell);
 	let timer,
+		secondaryRoute,
 		routedPath,
 		generation = 0,
 		active = null,
@@ -505,40 +507,68 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 		const view = node("section", "pp-fields");
 		/** @type {Array<() => void>} 挂载后执行的多行高度更新 / Textarea sizing callbacks run after mounting. */
 		const growingInputs = [];
+		const editors = new Map();
+		const summaries = [];
+		const groups = new Map();
+		const scrollPositions = new WeakMap();
+		let activeEditor;
+		let queue = Promise.resolve(),
+			pendingWrites = 0;
 		/**
-		 * 写入期间统一切换控件禁用状态。
-		 * Toggle all control disabled states during mutations.
-		 * @param {boolean} disabled 是否禁用 / Whether controls are disabled.
+		 * 根据 hash 切换多选页，保留上级 DOM 和滚动位置。
+		 * Switch multi-select views by hash while retaining parent DOM and scroll position.
 		 * @returns {void} 无返回值 / No return value.
 		 */
-		const disableControls = disabled => {
-			view.querySelectorAll("button,input,select,textarea").forEach(input => {
-				input.disabled = disabled;
-			});
+		const showEditor = () => {
+			let key;
+			try {
+				key = decodeURIComponent(window.location.hash.slice(1));
+			} catch {
+				key = "";
+			}
+			const editor = editors.get(key);
+			const previous = activeEditor?.node ?? view;
+			const next = editor?.node ?? view;
+			if (previous !== next) {
+				scrollPositions.set(previous, previous.scrollTop);
+				previous.remove();
+				viewport.append(next);
+				next.scrollTop = scrollPositions.get(next) ?? 0;
+				if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) next.animate([{ transform: `translateX(${editor ? 100 : -100}%)` }, { transform: "translateX(0)" }], { duration: 260, easing: "cubic-bezier(.22,.61,.36,1)" });
+			}
+			activeEditor = editor;
+			heading.textContent = editor?.title ?? definition.metadata?.name ?? active;
+			back.disabled = saving || (!editor && window.history.length <= 1);
 		};
+		secondaryRoute = showEditor;
 		/**
-		 * 执行页面操作，期间锁定控件，完成后处理延后的导航。
-		 * Run a page action with controls locked, then process deferred navigation.
+		 * 串行执行页面操作，输入可继续编辑，完成后处理延后导航。
+		 * Serialize page actions while inputs remain editable, then process deferred navigation.
 		 * @param {() => Promise<void>} action 请求或写入 / Request or mutation.
 		 * @param {() => void} success 成功后的局部更新 / Local update after success.
+		 * @param {() => void} [failure] 失败后恢复当前输入 / Restore the current input on failure.
 		 * @returns {Promise<void>} 操作完成 / Operation completion.
 		 */
-		async function perform(action, success) {
-			if (saving) return;
+		function perform(action, success, failure = () => {}) {
+			pendingWrites++;
 			saving = true;
 			back.disabled = true;
-			disableControls(true);
-			try {
-				await action();
-				if (!destroyed) success();
-			} catch {
-				/* 请求层已通知错误 / The request layer has already reported the error. */
-			} finally {
-				saving = false;
-				back.disabled = window.history.length <= 1;
-				disableControls(false);
-				if (!destroyed && pendingRoute) route();
-			}
+			return (queue = queue
+				.then(action)
+				.then(() => {
+					if (!destroyed) success();
+				})
+				.catch(() => {
+					/* 请求层已通知错误 / The request layer has already reported the error. */
+					if (!destroyed) failure();
+				})
+				.finally(() => {
+					pendingWrites--;
+					saving = pendingWrites > 0;
+					if (destroyed && !saving) client.leave(active);
+					back.disabled = saving || (!activeEditor && window.history.length <= 1);
+					if (!saving && !destroyed && pendingRoute) route();
+				}));
 		}
 		const metadata = definition.metadata;
 		if (metadata) {
@@ -575,14 +605,27 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 			view.append(info);
 		}
 		for (const field of definition.fields) {
-			const row = node("fieldset", "pp-field");
-			row.append(node("legend", "", field.name));
-			if (field.description) row.append(node("p", "pp-description", field.description));
+			const match = /^\[([^\]]+)\]\s*(.*)$/.exec(field.name);
+			const group = match?.[1] ?? "通用";
+			if (!groups.has(group)) {
+				const section = node("section", "form-group");
+				const rows = node("div", "form-group__row");
+				section.append(node("h2", "form-group__title", group), rows);
+				groups.set(group, rows);
+				view.append(section);
+			}
+			const row = node("div", "form-row pp-field");
+			const label = node("div", "form-row__text");
+			label.append(node("span", "form-row__title", match?.[2] ?? field.name));
+			if (field.description) label.append(node("span", "form-row__subtitle", field.description));
+			row.append(label);
 			const value = values[field.key];
 			/** @type {() => unknown} 读取尚未保存的输入 / Read the unsaved input. */
 			let read;
 			/** @type {(value: unknown) => void} 更新当前控件 / Update the current control. */
 			let write;
+			let inputContainer = row;
+			let eventName = "change";
 			switch (true) {
 				case Boolean(field.options) && field.type !== "array": {
 					const select = node("select", "pp-input");
@@ -600,12 +643,42 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 					break;
 				}
 				case field.type === "array" && Boolean(field.options): {
+					const page = node("section", "pp-choice-page");
+					if (field.description) page.append(node("p", "pp-description", field.description));
+					const choices = node("div", "form-group__row");
+					page.append(choices);
+					inputContainer = choices;
+					editors.set(field.key, { node: page, title: match?.[2] ?? field.name });
+					const summary = node("span", "form-row__value pp-summary");
+					const link = node("button", "pp-choice-link");
+					link.type = "button";
+					link.setAttribute("aria-label", field.name);
+					link.append(summary, node("span", "pp-chevron", "›"));
+					row.append(link);
+					const refresh = () => {
+						const value = client.snapshot(active).values[field.key];
+						summary.textContent =
+							field.options
+								.filter(option => Array.isArray(value) && value.includes(option.key))
+								.map(option => option.label)
+								.join("、") || "未选择";
+					};
+					summaries.push(refresh);
+					refresh();
+					link.onclick = () => {
+						window.history.pushState({ ...window.history.state, preferencePane: active }, "", `#${encodeURIComponent(field.key)}`);
+						showEditor();
+					};
+					row.addEventListener("click", event => {
+						if (!link.contains(event.target)) link.click();
+					});
 					const inputs = field.options.map(option => {
-						const label = node("label", "pp-choice", option.label);
+						const label = node("label", "form-row pp-choice", option.label);
 						const input = node("input", "");
 						input.type = "checkbox";
-						label.prepend(input);
-						row.append(label);
+						input.setAttribute("aria-label", option.label);
+						label.append(input);
+						choices.append(label);
 						return { input, key: option.key };
 					});
 					read = () => inputs.filter(option => option.input.checked).map(option => option.key);
@@ -617,6 +690,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 				default: {
 					const multiline = field.control === "textarea" || field.type === "array";
 					const input = node(multiline ? "textarea" : "input", "pp-input");
+					if (multiline) row.classList.add("pp-multiline");
 					input.setAttribute("aria-label", field.name);
 					if (field.placeholder) input.placeholder = field.placeholder;
 					if (multiline && field.rows) input.rows = field.rows;
@@ -639,11 +713,14 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 					}
 					if (field.type === "boolean") {
 						input.type = "checkbox";
+						input.classList.add("pp-switch");
+						input.setAttribute("role", "switch");
 						write = value => {
 							input.checked = value === true;
 						};
 						read = () => input.checked;
 					} else {
+						eventName = "input";
 						if (!multiline) input.type = field.type === "number" ? "number" : "text";
 						write = value => {
 							input.value = field.type === "array" ? JSON.stringify(value ?? []) : (value ?? "");
@@ -665,34 +742,31 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 				}
 			}
 			write(value);
-			const actions = node("div", "pp-actions");
-			for (const [operation, label] of [
-				["write", "保存"],
-				["delete", "删除覆盖值"],
-			]) {
-				const button = node("button", "", label);
-				button.type = "button";
-				button.onclick = () =>
-					perform(
-						async () => {
-							if (operation === "delete") await client.remove(active, field.key);
-							else {
-								let value;
-								try {
-									value = read();
-								} catch (error) {
-									notify({ kind: "error", message: error.message });
-									throw error;
-								}
-								await client.set(active, field.key, value);
-							}
-						},
-						() => write(client.snapshot(active).values[field.key]),
-					);
-				actions.append(button);
-			}
-			row.append(actions);
-			view.append(row);
+			let inputVersion = 0;
+			inputContainer.addEventListener(eventName, event => {
+				if (event.isComposing) return;
+				const version = ++inputVersion,
+					module = active;
+				let value;
+				try {
+					value = read();
+				} catch (error) {
+					notify({ kind: "error", message: error.message });
+					return;
+				}
+				const restore = () => {
+					if (version === inputVersion) write(client.snapshot(module).values[field.key]);
+				};
+				perform(
+					() => client.set(module, field.key, value),
+					() => {
+						for (const refresh of summaries) refresh();
+					},
+					restore,
+				);
+			});
+			if (eventName === "input") inputContainer.addEventListener("compositionend", event => event.target.dispatchEvent(new window.Event("input", { bubbles: true })));
+			groups.get(group).append(row);
 		}
 		const maintenance = node("section", "pp-maintenance");
 		maintenance.append(node("h2", "pp-title", "模块数据"));
@@ -705,6 +779,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 		output.setAttribute("aria-label", "Caches 内容");
 		for (const button of [cacheView, cacheClear, reset]) button.type = "button";
 		cacheView.onclick = () => {
+			if (saving) return;
 			let value;
 			return perform(
 				async () => {
@@ -723,6 +798,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 			);
 		};
 		cacheClear.onclick = () => {
+			if (saving) return;
 			if (!window.confirm(`清空 ${active} 的全部 Caches？`)) return;
 			return perform(
 				() => client.clearCaches(active),
@@ -732,6 +808,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 			);
 		};
 		reset.onclick = () => {
+			if (saving) return;
 			if (!window.confirm(`重置 ${active}？这将删除该模块的 Settings、Caches 和其它持久化数据。`)) return;
 			return perform(() => client.reset(active), controls);
 		};
@@ -740,6 +817,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 		view.append(maintenance);
 		viewport.replaceChildren(view);
 		for (const grow of growingInputs) grow();
+		showEditor();
 	}
 	/**
 	 * 按页面 pathname 切换模块，写入尚未完成时延后导航。
@@ -752,6 +830,7 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 			return;
 		}
 		pendingRoute = false;
+		secondaryRoute = undefined;
 		if (active) client.leave(active);
 		routedPath = window.location.pathname;
 		const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(routedPath);
@@ -771,7 +850,9 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 	 */
 	const onPopState = () => {
 		if (window.location.pathname !== routedPath) route();
+		else secondaryRoute?.();
 	};
+	const onHashChange = () => secondaryRoute?.();
 	/**
 	 * 从浏览器往返缓存恢复时重新读取当前模块。
 	 * Reload the current module when restored from the browser back-forward cache.
@@ -782,10 +863,15 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 		if (event.persisted) route();
 	};
 	back.onclick = () => {
-		if (!saving) window.history.back();
+		if (saving) return;
+		if (window.location.hash && window.history.state?.preferencePane !== active) {
+			window.history.replaceState(window.history.state, "", window.location.pathname);
+			secondaryRoute?.();
+		} else window.history.back();
 	};
 	window.addEventListener("popstate", onPopState);
 	window.addEventListener("pageshow", onPageShow);
+	window.addEventListener("hashchange", onHashChange);
 	route();
 	return {
 		/**
@@ -797,8 +883,9 @@ function mountPreferencePanes({ element: root, fetch, title = "Preferences" }) {
 			destroyed = true;
 			window.removeEventListener("popstate", onPopState);
 			window.removeEventListener("pageshow", onPageShow);
+			window.removeEventListener("hashchange", onHashChange);
 			generation++;
-			if (active) client.leave(active);
+			if (active && !saving) client.leave(active);
 			clearTimeout(timer);
 			shell.remove();
 		},