@nsnanocat/preference-panes 1.2.1 → 1.2.3

package/src/browser/Navigation.d.mts

@@ -5,6 +5,8 @@
  * 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 {
     /**
@@ -94,6 +96,18 @@ export interface Notice {
     message: string;
 }
 
+/**
+ * 宿主 URL 导航请求。
+ * Host URL navigation request.
+ */
+export interface OpenURLRequest {
+    /**
+     * 完整目标地址。
+     * Absolute target URL.
+     */
+    url: string;
+}
+
 /**
  * 菜单操作描述。
  * Menu action descriptor.

package/src/browser/boxjs.mjs

@@ -164,16 +164,60 @@ function scalar(value) {
 }
 
 /**
- * 检查值类型、数组唯一性及声明的选项，不进行转换。
- * Check value type, array uniqueness and declared choices without coercion.
+ * 检查值类型与数组结构，不检查选项是否仍在当前配置中。
+ * Check value type and array structure without requiring current option membership.
  * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
- * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
- * @returns {boolean} 是否符合字段约束 / Whether the value satisfies field constraints.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否可由控件表示 / Whether the control can represent the value.
  */
-export function validValue(field, value) {
+function validValueShape(field, value) {
     if (field.type === "array") {
         if (!Array.isArray(value) || value.some(item => !scalar(item)) || new Set(value).size !== value.length) return false;
     } else if (typeof value !== field.type || !scalar(value)) return false;
     if (field.control === "url" && (!/^[a-z][a-z\d+.-]*:/i.test(value) || /^(?:javascript|data|vbscript):/i.test(value))) return false;
-    return !field.options || (field.type === "array" ? value : [value]).every(item => field.options.some(option => option.key === item));
+    return true;
+}
+
+/**
+ * 返回当前配置未声明的选项值。
+ * Return option values absent from the current definition.
+ * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
+ * @param {unknown} value 已确认结构有效的值 / Value with a valid shape.
+ * @returns {unknown[]} 未定义值 / Undefined values.
+ */
+function undefinedOptions(field, value) {
+    if (!field.options) return [];
+    return (field.type === "array" ? value : [value]).filter(item => !field.options.some(option => option.key === item));
+}
+
+/**
+ * 将外部存储值解析为可渲染值，并把兼容性问题作为字段级警告返回。
+ * Resolve external storage into a renderable value and return compatibility issues as field warnings.
+ * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
+ * @param {unknown} stored 外部存储值 / External stored value.
+ * @returns {{value?: unknown, warning?: {kind: "invalid-value" | "undefined-options", values: unknown[]}}} 解析结果 / Resolution result.
+ */
+export function resolveStoredValue(field, stored) {
+    if (field.control === "url") return { value: field.defaultValue };
+    const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
+    if (value === undefined) return {};
+    if (!validValueShape(field, value)) {
+        return {
+            ...(Object.hasOwn(field, "defaultValue") ? { value: field.defaultValue } : {}),
+            warning: { kind: "invalid-value", values: [stored] },
+        };
+    }
+    const undefinedValues = undefinedOptions(field, value);
+    return { value, ...(undefinedValues.length ? { warning: { kind: "undefined-options", values: undefinedValues } } : {}) };
+}
+
+/**
+ * 严格检查写入值的类型、数组唯一性及声明选项。
+ * Strictly check a write value's type, array uniqueness, and declared options.
+ * @param {import("../index.js").SettingsField} field 前端归一化字段 / Normalized frontend field.
+ * @param {unknown} value 待写入的 JSON 值 / JSON value to write.
+ * @returns {boolean} 是否允许写入 / Whether the value may be written.
+ */
+export function validValue(field, value) {
+    return validValueShape(field, value) && undefinedOptions(field, value).length === 0;
 }

package/src/browser/client.d.mts

@@ -29,6 +29,16 @@ export interface PreferencesClientOptions {
     /** 请求超时毫秒数 / Request timeout in milliseconds. */
     timeout?: number;
 }
+/**
+ * 外部存储值与当前字段定义不完全兼容时的非阻断诊断。
+ * Non-blocking diagnostic for external storage that no longer fully matches a field definition.
+ */
+export interface StoredValueWarning {
+    /** 警告类别 / Warning kind. */
+    kind: "invalid-value" | "undefined-options";
+    /** 触发警告的原始值或未定义选项 / Raw value or undefined options that triggered the warning. */
+    values: unknown[];
+}
 /**
  * 会话的深拷贝快照。
  * Deep-cloned session snapshot.
@@ -38,6 +48,8 @@ export interface ModuleSnapshot {
     definition: ModuleDefinition;
     /** 当前页面值 / Current page values. */
     values: Record<string, SettingsScalar | SettingsScalar[] | null>;
+    /** 按字段路径索引的非阻断存储警告 / Non-blocking storage warnings keyed by field path. */
+    warnings: Record<string, StoredValueWarning>;
 }
 /**
  * 管理单模块页面的 API 请求、值快照和会话终止。

package/src/browser/client.mjs

@@ -1,4 +1,4 @@
-import { normalizeStoredValue, validValue } from "./boxjs.mjs";
+import { resolveStoredValue, validValue } from "./boxjs.mjs";
 
 /**
  * 管理单模块页面的 API 请求、值快照和会话终止。
@@ -12,6 +12,7 @@ export class PreferencesClient {
     #timeout;
     #session = new AbortController();
     #values = {};
+    #warnings = {};
     #saving = false;
 
     /**
@@ -38,17 +39,18 @@ export class PreferencesClient {
         if (typeof subtree === "string") subtree = JSON.parse(subtree);
         if (!subtree || typeof subtree !== "object" || Array.isArray(subtree)) throw new TypeError("Expected a settings subtree object");
         const values = {};
+        const warnings = {};
         for (const field of this.#definition.fields) {
             const stored = field.key
                 .split(".")
                 .slice(this.#definition.settingsPath.length)
                 .reduce((parent, part) => Object(parent)[part], subtree);
-            const value = normalizeStoredValue(field, stored === undefined ? field.defaultValue : stored);
-            if (value === undefined) continue;
-            if (!validValue(field, value)) throw new TypeError(`Invalid stored value: ${field.key}`);
-            values[field.key] = value;
+            const resolved = resolveStoredValue(field, stored);
+            if (Object.hasOwn(resolved, "value")) values[field.key] = resolved.value;
+            if (resolved.warning) warnings[field.key] = resolved.warning;
         }
         this.#values = values;
+        this.#warnings = warnings;
         return this.snapshot();
     }
 
@@ -58,7 +60,7 @@ export class PreferencesClient {
      * @returns {import("./client.mjs").ModuleSnapshot} 会话快照 / Session snapshot.
      */
     snapshot() {
-        return structuredClone({ definition: this.#definition, values: this.#values });
+        return structuredClone({ definition: this.#definition, values: this.#values, warnings: this.#warnings });
     }
 
     /**
@@ -182,15 +184,18 @@ export class PreferencesClient {
             switch (operation) {
                 case "write":
                     this.#values[key] = structuredClone(value);
+                    delete this.#warnings[key];
                     break;
                 case "delete": {
                     delete this.#values[key];
+                    delete this.#warnings[key];
                     if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
                     break;
                 }
                 case "clearCaches":
                     break;
                 case "reset":
+                    this.#warnings = {};
                     for (const field of this.#definition.fields) {
                         delete this.#values[field.key];
                         if (Object.hasOwn(field, "defaultValue")) this.#values[field.key] = structuredClone(field.defaultValue);

package/src/browser/components.mjs

@@ -88,3 +88,17 @@ export function requestConfirmation(host, message) {
         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/panel.css

@@ -8,6 +8,7 @@
     --pp-border: #e3e5e7;
     --pp-muted: #797f87;
     --pp-accent: #1677ff;
+    --pp-warning: #9a6700;
     font:
         15px / 1.5 -apple-system,
         BlinkMacSystemFont,
@@ -32,6 +33,7 @@
     --pp-field: #2f3238;
     --pp-border: #2f3238;
     --pp-muted: #9499a0;
+    --pp-warning: #f0b849;
 }
 .pp-panel * {
     box-sizing: border-box;
@@ -175,6 +177,12 @@
     color: var(--pp-muted);
     font-size: 12px;
 }
+.pp-field-warning {
+    margin-top: 4px;
+    color: var(--pp-warning);
+    font-size: 12px;
+    overflow-wrap: anywhere;
+}
 .pp-group {
     margin-top: 16px;
 }

package/src/browser/panel.mjs

@@ -1,9 +1,25 @@
 import { ActionMenu } from "./ActionMenu.mjs";
 import { validValue } from "./boxjs.mjs";
 import { PreferencesClient } from "./client.mjs";
-import { fieldControl, element as node, requestConfirmation, resourceURL, settingRow, statusView } from "./components.mjs";
+import { fieldControl, element as node, requestConfirmation, requestURLNavigation, resourceURL, settingRow, statusView } from "./components.mjs";
 import { Navigation } from "./Navigation.mjs";
 
+/**
+ * 将字段级存储诊断转换为简短提示。
+ * Convert a field-level storage diagnostic into concise display text.
+ * @param {import("./client.mjs").StoredValueWarning} warning 存储警告 / Storage warning.
+ * @returns {string} 用户可见提示 / User-visible warning.
+ */
+function warningMessage(warning) {
+    const values = warning.values
+        .map(value => {
+            if (typeof value === "string") return value;
+            return JSON.stringify(value) ?? String(value);
+        })
+        .join("、");
+    return warning.kind === "undefined-options" ? `当前配置未定义值：${values}` : `当前存储值格式不受支持：${values}`;
+}
+
 /**
  * 管理模块表单、导航、操作队列和短暂通知。
  * Manage the module form, navigation, operation queue, and transient notifications.
@@ -182,6 +198,7 @@ export class PreferencesPanel {
             const growingInputs = [];
             const editors = new Map();
             const summaries = [];
+            const warningRefreshers = [];
             const groups = new Map();
             let queue = Promise.resolve(),
                 pendingWrites = 0;
@@ -258,6 +275,15 @@ export class PreferencesPanel {
                 const label = node("div", "pp-label");
                 label.append(node("span", "pp-field-name", match?.[2] ?? field.name));
                 if (field.description) label.append(node("span", "pp-field-description", field.description));
+                const warning = node("span", "pp-field-warning");
+                const refreshWarning = () => {
+                    const issue = client.snapshot().warnings[field.key];
+                    warning.hidden = !issue;
+                    warning.textContent = issue ? warningMessage(issue) : "";
+                };
+                warningRefreshers.push(refreshWarning);
+                refreshWarning();
+                label.append(warning);
                 row.append(label);
                 const value = values[field.key];
                 /**
@@ -282,6 +308,9 @@ export class PreferencesPanel {
                         write = value => {
                             link.href = value;
                         };
+                        link.addEventListener("click", event => {
+                            if (requestURLNavigation(window, link.href)) event.preventDefault();
+                        });
                         row.append(link);
                         row.addEventListener("click", event => {
                             if (!link.contains(event.target)) link.click();
@@ -431,6 +460,7 @@ export class PreferencesPanel {
                         },
                         () => {
                             for (const refresh of summaries) refresh();
+                            for (const refresh of warningRefreshers) refresh();
                         },
                         restore,
                     );