@nsnanocat/preference-panes 1.1.0 → 1.1.2

package/src/browser/index.d.ts

@@ -1,4 +1,4 @@
-import type { ModuleModel } from "../index.js";
+import type { BoxJSInput } from "../index.js";
 
 /**
  * 具体模块设置页的生命周期句柄。
@@ -9,25 +9,9 @@ export interface MountedPreferences {
     destroy(): void;
 }
 /**
- * 管理模块设置视图的模型、样式、主题和面板生命周期。
- * Manage model, styles, theme, and panel lifecycle for a module settings view.
- */
-export class PreferencesView implements MountedPreferences {
-    /**
-     * 使用模块 API 返回的模型挂载设置页。
-     * Mount a settings page from the model returned by the module API.
-     * @param model 模块 API 模型 / Module API model.
-     * @param css 可选 CSS 正文 / Optional CSS text.
-     */
-    constructor(model: ModuleModel, css?: string);
-    /** 移除页面、样式和监听器 / Remove page, styles and listeners. */
-    destroy(): void;
-}
-/**
- * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
- * Mount a settings page from a module API model; CSS only overrides this module.
- * @param model 模块 API 模型 / Module API model.
- * @param css 可选 CSS 正文 / Optional CSS text.
+ * 使用原始 BoxJS JSON 挂载设置页。
+ * Mount a settings page from raw BoxJS JSON.
+ * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
  * @returns 模块视图 / Module view.
  */
-export function mount(model: ModuleModel, css?: string): PreferencesView;
+export function mount(boxjs: BoxJSInput): MountedPreferences;

package/src/browser/index.mjs

@@ -1,14 +1,13 @@
-import { pageInputs } from "../lib/page-inputs.mjs";
+import { normalizeBoxJs } from "./boxjs.mjs";
 import { statusView } from "./components.mjs";
-import { PreferencesView } from "./mount.mjs";
+import { mount } from "./mount.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
- * 管理模块文档的页面输入、初始请求、重载和错误状态。
- * Manage page inputs, initial requests, reloads, and error states for a module document.
+ * 管理模块文档的配置请求、重载和错误状态。
+ * Manage configuration requests, reloads, and error states for a module document.
  */
-export class ModulePage {
-    #document;
+class ModulePage {
     #window;
     #root;
     #view;
@@ -19,7 +18,6 @@ export class ModulePage {
      * @param {Document} document 模块文档 / Module document.
      */
     constructor(document) {
-        this.#document = document;
         this.#window = document.defaultView;
         this.#root = document.querySelector("#preferences");
         installDefaultStyles(document);
@@ -27,8 +25,8 @@ export class ModulePage {
     }
 
     /**
-     * 从 URL 或代理传递的 Header 导入 JSON/CSS，支持独立文档与 srcdoc。
-     * Import JSON/CSS from the URL or proxy-carried headers in standalone and srcdoc documents.
+     * 通过模块 API 读取 BoxJS JSON 并挂载通用前端。
+     * Read BoxJS JSON through the module API and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -36,12 +34,15 @@ export class ModulePage {
             this.#view?.destroy();
             this.#view = undefined;
             this.#root.replaceChildren(statusView("读取设置…"));
-            const inputs = this.#readInputs();
-            const apiURL = new URL(`/api/${encodeURIComponent(inputs.module)}`, inputs.url).href;
-            const styleURL = this.#resourceURL(inputs.css, inputs.url);
-            const [style, modelResponse] = await Promise.all([styleURL ? fetch(styleURL, { cache: "no-store", credentials: "omit" }) : null, fetch(apiURL, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json", "X-PreferencePanes-JSON": inputs.json } })]);
-            if ((style && style.status !== 200) || modelResponse.status !== 200) throw new Error(`HTTP ${modelResponse.status !== 200 ? modelResponse.status : style.status}`);
-            this.#view = new PreferencesView(await modelResponse.json(), style ? await style.text() : "");
+            const embedded = this.#window.frameElement?.dataset.preferencePanesModule;
+            const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#window.location.pathname);
+            const module = embedded ?? match?.[1];
+            if (!module) throw new TypeError("Open a concrete module URL");
+            const response = await fetch(`/api/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
+            const boxjs = await response.json();
+            normalizeBoxJs(boxjs, module);
+            this.#view = mount(boxjs);
         } catch (error) {
             this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
         }
@@ -58,39 +59,6 @@ export class ModulePage {
         this.#view = undefined;
     }
 
-    /**
-     * 读取嵌入参数、文档元数据或当前 URL 输入。
-     * Read embedded parameters, document metadata, or current URL inputs.
-     * @returns {ReturnType<typeof pageInputs>} 页面输入 / Page inputs.
-     */
-    #readInputs() {
-        const context = this.#document.querySelector('meta[name="preference-panes-inputs"]');
-        const embedded = this.#window.frameElement?.dataset.preferencePanes;
-        switch (true) {
-            case embedded !== undefined:
-                this.#document.documentElement.dataset.preferencePanesEmbedded = "";
-                return JSON.parse(embedded);
-            case context !== null:
-                return JSON.parse(decodeURIComponent(context.content));
-            default:
-                return pageInputs(new URL(this.#window.location.href));
-        }
-    }
-
-    /**
-     * 将可选页面资源限制为 HTTP(S) 地址。
-     * Restrict an optional page resource to an HTTP(S) URL.
-     * @param {string | undefined} source 资源地址 / Resource location.
-     * @param {string} baseURL 页面基准地址 / Page base URL.
-     * @returns {string | null} 绝对资源地址 / Absolute resource URL.
-     */
-    #resourceURL(source, baseURL) {
-        if (!source) return null;
-        const url = new URL(source, baseURL);
-        if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Resources must use HTTP(S) URLs");
-        return url.href;
-    }
-
     /**
      * 从前进后退缓存恢复时重新加载模块。
      * Reload the module when restored from the back-forward cache.

package/src/browser/mount.mjs

@@ -1,18 +1,17 @@
-import { normalizeBoxJs, normalizeStoredValue, validValue } from "./boxjs.mjs";
+import { normalizeBoxJs } from "./boxjs.mjs";
 import { element, resourceURL } from "./components.mjs";
 import { PreferencesPanel } from "./panel.mjs";
 import { installDefaultStyles } from "./styles.mjs";
 
 /**
- * 管理模块设置视图的模型规范化、样式、主题同步和面板生命周期。
- * Manage model normalization, styles, theme synchronization, and panel lifecycle for a module settings view.
+ * 管理 BoxJS 规范化、主题同步和面板生命周期。
+ * Manage BoxJS normalization, theme synchronization, and panel lifecycle.
  */
-export class PreferencesView {
+class PreferencesView {
     #existing;
     #root;
     #base;
     #ownsBase;
-    #custom;
     #previousTitle;
     #previousTheme;
     #systemTheme;
@@ -22,22 +21,12 @@ export class PreferencesView {
     #panel;
 
     /**
-     * 使用模块 API 返回的模型挂载设置页。
-     * Mount a settings page from the model returned by the module API.
-     * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
-     * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
+     * 使用原始 BoxJS JSON 挂载设置页。
+     * Mount a settings page from raw BoxJS JSON.
+     * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
      */
-    constructor(model, css = "") {
-        if (typeof css !== "string") throw new TypeError("CSS must be a string");
-        const definition = normalizeBoxJs(model.boxjs, model.module);
-        const values = { ...model.values };
-        for (const field of definition.fields) {
-            if (values[field.key] === undefined) continue;
-            values[field.key] = normalizeStoredValue(field, values[field.key]);
-            if (!validValue(field, values[field.key])) throw new TypeError(`Invalid stored value: ${field.key}`);
-        }
-        for (const field of definition.fields) if (values[field.key] === undefined && Object.hasOwn(field, "defaultValue")) values[field.key] = structuredClone(field.defaultValue);
-        const rendered = { ...model, definition, values };
+    constructor(boxjs) {
+        const definition = normalizeBoxJs(boxjs);
         const metadata = definition.metadata ?? {};
         const image = metadata.icon || metadata.icons?.[1] || metadata.icons?.[0];
         if (image) resourceURL(image);
@@ -52,9 +41,6 @@ export class PreferencesView {
         const styles = installDefaultStyles(document);
         this.#base = styles.element;
         this.#ownsBase = styles.owned;
-        this.#custom = element("style", "");
-        this.#custom.textContent = css;
-        document.head.append(this.#custom);
         this.#previousTitle = document.title;
         this.#previousTheme = document.documentElement.dataset.theme;
         this.#systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
@@ -69,7 +55,7 @@ export class PreferencesView {
         document.title = metadata.name ?? definition.module;
         try {
             this.#root.replaceChildren();
-            this.#panel = new PreferencesPanel(this.#root, rendered);
+            this.#panel = new PreferencesPanel(this.#root, definition);
         } catch (error) {
             this.destroy();
             throw error;
@@ -97,7 +83,6 @@ export class PreferencesView {
         this.#systemTheme.removeEventListener("change", this.#syncAppearance);
         this.#panel?.destroy();
         if (this.#ownsBase) this.#base.remove();
-        this.#custom.remove();
         if (this.#existing) this.#root.replaceChildren();
         else this.#root.remove();
         document.title = this.#previousTitle;
@@ -108,12 +93,11 @@ export class PreferencesView {
 }
 
 /**
- * 使用模块 API 返回的模型挂载设置页；CSS 仅覆盖当前模块。
- * Mount a settings page from a module API model; CSS only overrides this module.
- * @param {import("../index.js").ModuleModel} model API 返回的模块模型 / Module model returned by the API.
- * @param {string} [css] 可选 CSS 正文 / Optional module-scoped CSS text.
- * @returns {PreferencesView} 模块视图 / Module view.
+ * 使用原始 BoxJS JSON 挂载设置页。
+ * Mount a settings page from raw BoxJS JSON.
+ * @param {import("../index.js").BoxJSInput} boxjs 单模块 BoxJS JSON / Single-module BoxJS JSON.
+ * @returns {import("./index.js").MountedPreferences} 模块视图 / Module view.
  */
-export function mount(model, css = "") {
-    return new PreferencesView(model, css);
+export function mount(boxjs) {
+    return new PreferencesView(boxjs);
 }

package/src/browser/panel.mjs

@@ -12,24 +12,23 @@ export class PreferencesPanel {
     #release;
 
     /**
-     * 挂载 API 返回的模块模型表单。
-     * Mount the module form returned by the API.
+     * 挂载 BoxJS 定义对应的模块表单。
+     * Mount the module form described by a BoxJS definition.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      */
-    constructor(root, model) {
-        this.#release = this.#mount(root, model);
+    constructor(root, definition) {
+        this.#release = this.#mount(root, definition);
     }
 
     /**
      * 建立面板 DOM、交互和会话，并返回其释放操作。
      * Build panel DOM, interactions, and session, then return its release operation.
      * @param {HTMLElement} root 包内挂载元素 / Internal mount element.
-     * @param {import("../index.js").ModuleModel & {definition: import("../index.js").ModuleDefinition}} model 已规范化模块模型 / Normalized module model.
+     * @param {import("../index.js").ModuleDefinition} definition 已规范化字段定义 / Normalized field definition.
      * @returns {() => void} 释放操作 / Release operation.
      */
-    #mount(root, model) {
-        const { definition } = model;
+    #mount(root, definition) {
         const title = definition.metadata?.name ?? definition.module;
         const document = root.ownerDocument;
         const window = document.defaultView;
@@ -121,7 +120,7 @@ export class PreferencesPanel {
                 toast.hidden = true;
             }, 2400);
         };
-        const client = new PreferencesClient({ model, definition, notify });
+        const client = new PreferencesClient({ definition, notify });
         /**
          * 两种菜单入口共用异步错误处理，包含宿主确认框错误。
          * Share async error handling between both menus, including host-dialog errors.
@@ -149,6 +148,7 @@ export class PreferencesPanel {
             publishNavigation();
             viewport.replaceChildren(statusView("读取设置…"));
             try {
+                await client.open();
                 if (version === generation) controls();
             } catch (error) {
                 if (version !== generation) return;

package/src/index.d.ts

@@ -92,8 +92,8 @@ export interface SettingsRequest {
      */
     headers?: Record<string, string | undefined>;
     /**
-     * 模块动作的 JSON 正文
-     * JSON body for a module action.
+     * 存储动作的 form 正文
+     * Form body for a storage action.
      */
     body?: string;
 }
@@ -268,25 +268,3 @@ export interface BoxJSSubscription extends BoxJSMetadata {
  * The sole data configuration input.
  */
 export type BoxJSInput = BoxJSSetting[] | BoxJSApp | BoxJSSubscription;
-/**
- * 模块 API 返回的原始 BoxJS 与当前值模型。
- * Raw BoxJS and current-value model returned by the module API.
- */
-export interface ModuleModel {
-    /** 模块路径段 / Module path segment. */
-    module: string;
-    /** API 获取的原始 BoxJS JSON / Raw BoxJS JSON fetched by the API. */
-    boxjs: BoxJSInput;
-    /** API 读取到的原始已保存字段值 / Raw persisted field values read by the API. */
-    values: Record<string, JsonValue>;
-    /** 后续 API 动作使用的 BoxJS JSON 地址 / BoxJS JSON URL used by later API actions. */
-    configURL: string;
-}
-/**
- * 生成模块前端文件，不复制配置、不生成绑定模块的代理脚本。
- * Build module frontend files without copying configuration or producing bound proxy scripts.
- * @param boxjs 恰好包含一个模块的 BoxJS JSON / BoxJS JSON describing exactly one module.
- * @param css 可选 CSS 正文 / Optional CSS text.
- * @returns 相对路径到文件内容的映射 / Relative paths mapped to file contents.
- */
-export function build(boxjs: BoxJSInput, css?: string): Promise<Record<string, string>>;

package/src/index.mjs

@@ -1,6 +1,6 @@
 /**
- * 仅接收 BoxJS JSON 与可选 CSS 的构建入口。
- * Build entry accepting only BoxJS JSON and optional CSS.
+ * PreferencePanes 公共类型根入口；浏览器运行时由子路径导出。
+ * PreferencePanes public type root; browser runtimes are exported from subpaths.
  * @module @nsnanocat/preference-panes
  */
-export { build } from "./build.mjs";
+export {};

package/src/web.mjs

@@ -2,7 +2,6 @@ import { URL } from "@nsnanocat/url";
 import { $app } from "@nsnanocat/util/lib/app.mjs";
 import { done } from "@nsnanocat/util/lib/done.mjs";
 import assets from "#assets";
-import { pageInputs } from "./lib/page-inputs.mjs";
 
 /**
  * 返回模块页面及其公共浏览器资源，不处理 API、网络或持久化。
@@ -16,10 +15,7 @@ function run() {
         const url = new URL(request.url);
         if (/^\/settings\/[a-zA-Z0-9_-]+\/?$/.test(url.pathname)) {
             if (!["GET", "HEAD"].includes(request.method)) result = response(request, 405, { error: "Method not allowed" });
-            else {
-                const inputs = encodeURIComponent(JSON.stringify(pageInputs(url, request.headers)));
-                result = response(request, 200, assets.page.body.replace("</head>", `<meta name="preference-panes-inputs" content="${inputs}"></head>`), "text/html");
-            }
+            else result = response(request, 200, assets.page.body, "text/html");
         } else {
             const asset = assets[url.pathname];
             if (asset) result = ["GET", "HEAD"].includes(request.method) ? response(request, 200, asset.body, asset.type) : response(request, 405, { error: "Method not allowed" });

package/src/build.mjs

@@ -1,20 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { normalizeBoxJs } from "./browser/boxjs.mjs";
-
-/**
- * 仅生成模块前端文件，不复制配置或生成绑定业务的读写脚本。
- * Build module frontend files without copying configuration or generating bound storage scripts.
- * @param {unknown} boxjs 仅包含一个模块的 BoxJS JSON / BoxJS JSON containing exactly one module.
- * @param {string} [css] 可选自定义 CSS 正文 / Optional custom CSS text.
- * @returns {Promise<Record<string, string>>} 相对路径到文件正文的映射 / Relative file paths mapped to file contents.
- */
-export async function build(boxjs, css = "") {
-    if (typeof css !== "string") throw new TypeError("CSS must be a string");
-    const module = normalizeBoxJs(boxjs).module;
-    const [html, index] = await Promise.all([readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"), readFile(new URL("../dist/module/index.mjs", import.meta.url), "utf8")]);
-    return {
-        [`settings/${module}/index.html`]: html,
-        "settings/assets/index.mjs": index,
-        [`settings/assets/${module}.css`]: css,
-    };
-}

package/src/lib/page-inputs.mjs

@@ -1,17 +0,0 @@
-/**
- * 统一解析模块页的资源地址：Header 优先于查询参数，再使用模块约定。
- * Resolve module resource locations: headers override query parameters and module conventions.
- * @param {URL} url 已解析的页面请求地址 / Parsed page request URL.
- * @param {Record<string, string | undefined>} [headers] 请求头，名称不区分大小写 / Case-insensitive request headers.
- * @returns {{url: string, module: string, json: string, css: string}} 页面上下文与两个资源输入 / Page context and two resource inputs.
- */
-export function pageInputs(url, headers = {}) {
-    const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(url.pathname);
-    if (!match) throw new TypeError("Open a concrete module URL");
-    const module = match[1];
-    const values = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
-    const json = values["x-preferencepanes-json"] ?? url.searchParams.get("json") ?? `/configs/${module}`;
-    const css = values["x-preferencepanes-css"] ?? url.searchParams.get("css") ?? "";
-    if (!json.trim()) throw new TypeError("JSON resource URL is required");
-    return { url: url.href, module, json, css };
-}