@nsnanocat/preference-panes 1.3.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsnanocat/preference-panes",
-    "version": "1.3.0",
+    "version": "1.3.1",
     "description": "Generic BoxJS settings frontend and persistence API for JavaScript proxy modules",
     "author": "VirgilClyne <Virgil@nanocat.me>",
     "homepage": "https://NSNanoCat.github.io/preference-panes",
@@ -28,7 +28,7 @@
         },
         "./navigation": {
             "types": "./src/browser/Navigation.d.mts",
-            "import": "./dist/module/navigation.mjs"
+            "import": "./dist/navigation.mjs"
         }
     },
     "types": "src/index.d.ts",

package/src/browser/ActionMenu.mjs

@@ -1,6 +1,6 @@
 /**
- * 独立页面的三点按钮和底部操作菜单；嵌入页面由宿主提供对应界面。
- * Overflow trigger and bottom action sheet for standalone pages; embedded pages use host-provided chrome.
+ * 共用菜单按钮和底部操作菜单；原生宿主可通过 MORE 调用。
+ * Shared menu trigger and bottom action sheet; native hosts may invoke it through MORE.
  */
 export class ActionMenu {
     #button;
@@ -28,13 +28,14 @@ export class ActionMenu {
         this.element = document.createElement("span");
         const triggerRoot = this.element.attachShadow({ mode: "open" });
         triggerRoot.innerHTML = `<style>
-          :host{display:inline-flex;width:44px;height:44px;color:inherit}
+          :host{display:inline-flex;flex:none;width:37px;height:37px;color:inherit}
           :host([hidden]){display:none!important}
-          button{width:44px;height:44px;padding:10px;font:inherit;cursor:pointer;border:0;color:inherit;background:none}
+          button{box-sizing:border-box;width:37px;height:37px;padding:8px;border-radius:4px;font:inherit;cursor:pointer;border:0;color:inherit;background:none;transition:background-color .3s}
+          button:hover{background:var(--pp-field,#8882)}
           button:disabled{opacity:.4;cursor:default}
           button:focus-visible{outline:2px solid currentColor;outline-offset:-3px}
-          svg{display:block;width:24px;height:24px;fill:currentColor}
-        </style><button type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="4" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="20" cy="12" r="2"/></svg></button>`;
+          svg{display:block;width:21px;height:21px;fill:none}
+        </style><button type="button" aria-label="更多操作" aria-haspopup="menu" aria-expanded="false"><svg viewBox="0 0 21 21" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.667" d="M3.645 5.225h13.333M3.645 10.225h13.333M3.645 15.225h13.333"/></svg></button>`;
         this.#button = triggerRoot.querySelector("button");
         this.#layer = document.createElement("span");
         const layerRoot = this.#layer.attachShadow({ mode: "open" });

package/src/browser/Navigation.d.mts

@@ -1,84 +1,3 @@
-/**
- * 静态 HTML 的模块 iframe 容器；页面资源输入写入 iframe 数据属性。
- * Static HTML module iframe whose resource inputs are written to iframe data attributes.
- * confirm 事件可 preventDefault 后通过 detail.resolve/reject 完成宿主确认。
- * Prevent default on confirm events and settle host dialogs through detail.resolve/reject.
- * notice 事件可 preventDefault 后交由宿主显示，模块不再创建网页 Toast。
- * Prevent default on notice events to display them in the host without a module web Toast.
- * open-url 事件可 preventDefault 后交由宿主打开 URL，模块不再执行链接默认导航。
- * Prevent default on open-url events to open the URL in the host instead of navigating the module.
- */
-export class ModuleFrame extends EventTarget {
-    /**
-     * 创建容器。
-     * Create a container.
-     * @param url 模块地址 / Module URL.
-     * @param options 静态页面请求与资源输入 / Static page request and resource inputs.
-     */
-    constructor(url: string | URL, options?: { signal?: AbortSignal; headers?: HeadersInit });
-    /**
-     * 宿主挂载节点。
-     * Host-mounted element.
-     */
-    readonly element: HTMLIFrameElement;
-    /**
-     * change 事件对应的导航状态。
-     * Navigation state exposed with change events.
-     */
-    readonly state: { title: string; module: string; busy: boolean; canGoBack: boolean; actions: MenuAction[] };
-    /**
-     * 获取原始 HTML。
-     * Fetch unmodified HTML.
-     * @returns 加载完成 / Load completion.
-     */
-    load(): Promise<void>;
-    /**
-     * 沿模块历史返回。
-     * Go back through module history.
-     * @returns 无返回值 / No return value.
-     */
-    back(): void;
-    /**
-     * 执行模块提供的菜单操作。
-     * Perform a module-provided menu action.
-     * @param id 操作标识 / Action identifier.
-     * @returns 无返回值 / No return value.
-     */
-    perform(id: string): void;
-    /**
-     * 取消请求与事件订阅。
-     * Cancel requests and subscriptions.
-     * @returns 无返回值 / No return value.
-     */
-    destroy(): void;
-}
-
-/**
- * 宿主确认事件的数据。
- * Host confirmation event detail.
- */
-export interface ConfirmationRequest {
-    /**
-     * 确认内容。
-     * Confirmation message.
-     */
-    message: string;
-    /**
-     * 返回选择。
-     * Return the user's choice.
-     * @param confirmed 是否确认 / Whether confirmed.
-     * @returns 无返回值 / No return value.
-     */
-    resolve(confirmed: boolean): void;
-    /**
-     * 返回失败。
-     * Return a failure.
-     * @param error 错误 / Error.
-     * @returns 无返回值 / No return value.
-     */
-    reject(error: Error): void;
-}
-
 /**
  * 操作结果通知。
  * Operation result notice.
@@ -96,18 +15,6 @@ export interface Notice {
     message: string;
 }
 
-/**
- * 宿主 URL 导航请求。
- * Host URL navigation request.
- */
-export interface OpenURLRequest {
-    /**
-     * 完整目标地址。
-     * Absolute target URL.
-     */
-    url: string;
-}
-
 /**
  * 菜单操作描述。
  * Menu action descriptor.
@@ -131,8 +38,8 @@ export interface MenuAction {
 }
 
 /**
- * 共用三点菜单。
- * Shared overflow menu.
+ * 共用操作菜单。
+ * Shared action menu.
  */
 export class ActionMenu {
     /**
@@ -258,6 +165,8 @@ export class Navigation extends EventTarget {
      * @returns 无返回值 / No return value.
      */
     open(key: string): void;
+    /** 更新当前挂载视图，不增加历史 / Refresh the mounted view without adding history. */
+    refresh(): void;
     /**
      * 沿联合历史后退。
      * Go back through joint history.

package/src/browser/Navigation.mjs

@@ -1,10 +1,9 @@
 export { ActionMenu } from "./ActionMenu.mjs";
-export { ModuleFrame } from "./ModuleFrame.mjs";
 export { ModuleStatus, probeModule } from "./ModuleStatus.mjs";
 
 /**
- * 同一文档内的主页/子页导航；iframe 各自的实例通过浏览器联合历史协作。
- * Navigate home/detail views within a document; iframe instances cooperate through joint browser history.
+ * 同一文档内的首页、模块及字段子页导航。
+ * Navigate homepage, module and field views within one document.
  */
 export class Navigation extends EventTarget {
     #container;
@@ -16,7 +15,7 @@ export class Navigation extends EventTarget {
     #retiring;
     #controller;
     #animation;
-    #scroll = new WeakMap();
+    #scroll = new Map();
     #onHistory = () => this.#route();
     #onPageShow = event => {
         if (event.persisted) this.#route(true);
@@ -59,28 +58,37 @@ export class Navigation extends EventTarget {
     }
 
     /**
-     * 加入子页历史；使用文档自身 URL，避免 srcdoc 按宿主 base URL 跳转。
-     * Push a detail using the document URL, avoiding srcdoc navigation against the host base URL.
+     * 加入模块或字段子页历史，保留路由中的层级分隔符。
+     * Push a module or field view while retaining route hierarchy separators.
      * @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);
+        url.hash = key.split("/").map(encodeURIComponent).join("/");
         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.
+     * 沿文档历史返回，根页可退回上个文档。
+     * Go back through document history, including the previous document from home.
      * @returns {void} 无返回值 / No return value.
      */
     back() {
         if (this.canGoBack) this.#window.history.back();
     }
 
+    /**
+     * 更新当前页的挂载视图，保留路由和滚动位置。
+     * Refresh the mounted view while retaining route and scroll position.
+     * @returns {void} 无返回值 / No return value.
+     */
+    refresh() {
+        this.#route(true);
+    }
+
     /**
      * 解析 URL 并统一处理页面切换、加载取消与动画结束后的释放。
      * Resolve the URL and coordinate transitions, cancellation and release after animation.
@@ -97,28 +105,42 @@ export class Navigation extends EventTarget {
             key = "";
         }
         if (!reload && key === this.#key) return;
+        if (key !== this.#key) this.#scroll.set(this.#key, (this.#view ?? this.#home).scrollTop);
         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.
+        // 直接打开字段页时补齐首页和模块历史；刷新不重复堆叠。
+        // Seed homepage and module history for direct field links without stacking on reload.
         if (url.hash && history.state?.preferencePanesRoute !== key) {
             url.hash = "";
             history.replaceState({ ...history.state, preferencePanesRoute: "" }, "", url.href);
             if (key) {
-                url.hash = encodeURIComponent(key);
+                const module = key.split("/")[0];
+                if (key.includes("/") && module !== "$link") {
+                    url.hash = encodeURIComponent(module);
+                    history.pushState({ ...history.state, preferencePanesRoute: module }, "", url.href);
+                }
+                url.hash = key.split("/").map(encodeURIComponent).join("/");
                 history.pushState({ ...history.state, preferencePanesRoute: key }, "", url.href);
             }
         }
         const previous = this.#view;
+        if (previous === next && this.#key === key) {
+            if (previous && this.#scroll.has(key)) {
+                previous.scrollTop = this.#scroll.get(key);
+                this.#scroll.delete(key);
+            }
+            this.dispatchEvent(new Event("change"));
+            return;
+        }
+        const scroll = this.#scroll.get(key) ?? (key === this.#key ? (previous?.scrollTop ?? 0) : 0);
         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;
@@ -127,7 +149,14 @@ export class Navigation extends EventTarget {
         if (next) {
             next.inert = false;
             this.#container.append(next);
-            next.scrollTop = this.#scroll.get(next) ?? 0;
+            next.scrollTop = scroll;
+            // 加载占位页可能无法滚到原位置；配置与控件就绪后的 refresh 再恢复一次。
+            // A loading placeholder may clamp scrolling; restore once more when config and controls refresh.
+            if (next.scrollTop === scroll) this.#scroll.delete(key);
+        }
+        if (!next) {
+            this.#home.scrollTop = this.#scroll.get("") ?? 0;
+            this.#scroll.delete("");
         }
         const moving = next ?? previous;
         if (moving) {

package/src/browser/client.d.mts

@@ -70,7 +70,7 @@ export class PreferencesClient {
     clearCaches(): Promise<void>;
     /** 删除声明的设置路径，默认整个模块数据，并恢复默认值 / Delete declared setting paths, defaulting to module data, and restore defaults. */
     reset(): Promise<void>;
-    /** 取消请求 / Cancel requests. */
+    /** 取消读取，已开始的写入继续完成 / Cancel reads while allowing started writes to finish. */
     leave(): void;
     /** 写入单个字段 / Write one field. */
     set(key: string, value: SettingsScalar | SettingsScalar[]): Promise<void>;

package/src/browser/client.mjs

@@ -113,8 +113,8 @@ export class PreferencesClient {
     }
 
     /**
-     * 终止当前页面仍在进行的请求。
-     * Abort requests still owned by the current page.
+     * 终止当前页面的读取；已开始的持久化写入继续完成。
+     * Abort reads owned by the current page while allowing started persistence writes to finish.
      * @returns {void} 无返回值 / No return value.
      */
     leave() {
@@ -153,8 +153,10 @@ export class PreferencesClient {
     async #send(action, path, value) {
         const controller = new AbortController();
         const abort = () => controller.abort();
-        if (this.#session.signal.aborted) abort();
-        this.#session.signal.addEventListener("abort", abort, { once: true });
+        if (action === "get") {
+            if (this.#session.signal.aborted) abort();
+            this.#session.signal.addEventListener("abort", abort, { once: true });
+        }
         const timer = setTimeout(abort, this.#timeout);
         try {
             const response = await this.#request(`/api/${action}`, {

package/src/browser/components.mjs

@@ -36,18 +36,6 @@ export function fieldControl(control) {
     return control;
 }
 
-/**
- * 元数据地址只允许 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, document.baseURI);
-    if (!["http:", "https:"].includes(url.protocol)) throw new TypeError("Metadata URLs must use HTTP(S)");
-    return url.href;
-}
-
 /**
  * 创建覆盖可用内容区的通用读取状态，失败时可附加重试动作。
  * Create a shared status view that fills the available content area and may include retry.
@@ -70,35 +58,3 @@ export function statusView(message, retry) {
     }
     return view;
 }
-
-/**
- * 请求宿主确认；独立网页使用浏览器对话框。
- * Request confirmation from the host, using the browser dialog for standalone pages.
- * @param {Window} host 模块窗口 / Module window.
- * @param {string} message 确认内容 / Confirmation message.
- * @returns {Promise<boolean>} 用户是否确认 / Whether the user confirmed.
- */
-export function requestConfirmation(host, message) {
-    return new Promise((resolve, reject) => {
-        const frame = host.frameElement;
-        if (frame) {
-            const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:confirm", { cancelable: true, detail: { message, resolve, reject } });
-            if (!frame.dispatchEvent(event)) return;
-        }
-        resolve(host.confirm(message));
-    });
-}
-
-/**
- * 请求宿主打开 URL；未被接管时保留链接默认导航。
- * Request host URL navigation while preserving the link default when unhandled.
- * @param {Window} host 模块窗口 / Module window.
- * @param {string} url 完整目标地址 / Absolute target URL.
- * @returns {boolean} 宿主是否接管导航 / Whether the host accepted navigation ownership.
- */
-export function requestURLNavigation(host, url) {
-    const frame = host.frameElement;
-    if (!frame) return false;
-    const event = new frame.ownerDocument.defaultView.CustomEvent("preferencepanes:open-url", { cancelable: true, detail: { url } });
-    return !frame.dispatchEvent(event);
-}

package/src/browser/home.d.mts

@@ -4,6 +4,12 @@ import type { ActionMenu, MenuAction, Notice } from "./Navigation.mjs";
 export interface HomeState {
     /** 当前标题 / Current title. */
     title: string;
+    /** 首页导航图片 / Homepage navigation image. */
+    logo?: string;
+    /** 首页导航文字 / Homepage navigation text. */
+    logoText?: string;
+    /** 网页导航品牌链接 / Web navigation brand link. */
+    logoHref?: string;
     /** 可用菜单操作 / Available menu actions. */
     actions: MenuAction[];
     /** 操作是否正在执行 / Whether an operation is in progress. */
@@ -44,11 +50,17 @@ export type HomeIcon = { src: string; text?: never } | { text: string; src?: nev
 /** 外链打开方式：带导航的内部框架、当前页面或新页面 / Link opening mode: an internal frame with navigation, the current page or a new page. */
 export type HomeLinkTarget = "internal" | "_self" | "_blank";
 /** 首页模块或链接入口 / Homepage module or link entry. */
-export type HomeItem = { name: string; icon: HomeIcon; description?: string } & ({ module: string; pageModule?: string; href?: never; target?: never } | { href: string; target?: HomeLinkTarget; module?: never; pageModule?: never });
+export type HomeItem = { name: string; icon: HomeIcon; description?: string } & ({ module: string; href?: never; target?: never } | { href: string; target?: HomeLinkTarget; module?: never });
 /** 运行时导入的首页配置 / Runtime-imported homepage configuration. */
 export interface HomeConfig {
+    /** 文档和原生导航标题；未提供品牌时也是网页导航文字 / Document and native navigation title; also the web navigation text when no brand is supplied. */
     title: string;
+    /** 网页导航图片，相对于 JSON 地址 / Web navigation image, relative to the JSON URL. */
     logo?: string;
+    /** 网页导航文字，沿用 Rspress 命名 / Web navigation text, following Rspress naming. */
+    logoText?: string;
+    /** 网页导航品牌链接，相对于 JSON 地址；默认网站首页 / Web navigation brand link, relative to the JSON URL; defaults to the site homepage. */
+    logoHref?: string;
     sections: { title: string; layout?: "grid" | "list"; items: HomeItem[] }[];
     footer?: string[];
 }

package/src/browser/home.html

@@ -9,7 +9,6 @@
     <div data-preference-panes-pages>
       <main class="pp-home" data-preference-panes-home></main>
     </div>
-    <template data-preference-panes-module><section data-preference-panes-module-page><p data-module-message>正在打开设置…</p></section></template>
     <script type="module">__PREFERENCE_PANES_HOME_SCRIPT__
 await startHome();</script>
   </body>