@nsnanocat/preference-panes 0.6.0 → 0.7.0

package/src/build.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { BoxJS } from "./BoxJS.mjs";
+
+/**
+ * 从两个配置输入生成一个模块页及其读写与配置 Mock，不生成项目主页。
+ * Build one module page, its storage script and config Mock without a project landing page.
+ * @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 catalog = new BoxJS(boxjs);
+    const module = catalog.module.module;
+    const [html, app, proxy, mock] = await Promise.all([
+        readFile(new URL("../dist/module/index.html", import.meta.url), "utf8"),
+        readFile(new URL("../dist/module/app.mjs", import.meta.url), "utf8"),
+        readFile(new URL("../dist/preference-panes.proxy.js", import.meta.url), "utf8"),
+        readFile(new URL("../dist/preference-panes.config.js", import.meta.url), "utf8"),
+    ]);
+    const config = JSON.stringify(catalog.select(module));
+    return {
+        [`settings/${module}/index.html`]: html,
+        [`settings/assets/${module}.html`]: html,
+        "settings/assets/app.mjs": app,
+        [`settings/assets/${module}.boxjs.json`]: config,
+        [`settings/assets/${module}.css`]: css,
+        [`settings/assets/${module}.request.js`]: `${proxy}\nPreferencePanes.run(${config},${JSON.stringify(css)});\n`,
+        [`settings/assets/${module}.config.js`]: `${mock}\nPreferencePanes.mock(${config});\n`,
+    };
+}

package/src/index.d.ts

@@ -8,177 +8,271 @@ export type SettingsScalar = string | number | boolean;
  * Stored value and display label of a choice.
  */
 export interface SettingsOption<T extends SettingsScalar = SettingsScalar> {
-	/** 持久化值，保留原始标量类型 / Persisted value with its original scalar type. */
-	key: T;
-	/** 纯文本选项名称 / Plain-text option label. */
-	label: string;
+    /**
+     * 持久化值，保留原始标量类型
+     * Persisted value with its original scalar type.
+     */
+    key: T;
+    /**
+     * 纯文本选项名称
+     * Plain-text option label.
+     */
+    label: string;
 }
 /**
  * 控件共同的路径与展示属性。
  * Shared path and presentation attributes of a control.
  */
 interface FieldBase {
-	/** 不含存储根的点分路径，例如 Module.Settings.key / Dotted path without the storage root, such as Module.Settings.key. */
-	key: string;
-	/** 纯文本标题 / Plain-text title. */
-	name: string;
-	/** 纯文本说明 / Plain-text description. */
-	description?: string;
-	/** 原始 BoxJS 控件类型，与持久化值类型区分 / Original BoxJS control kind, separate from the stored value type. */
-	control?: "boolean" | "checkboxes" | "selects" | "text" | "textarea" | "number";
-	/** 输入占位文字 / Input placeholder. */
-	placeholder?: string;
-	/** 多行控件的基础行数，必须为正整数 / Positive baseline row count for a textarea. */
-	rows?: number;
-	/** 是否随多行内容自动调整高度 / Whether textarea height follows its contents. */
-	autoGrow?: boolean;
+    /**
+     * 不含存储根的点分路径，例如 Module.Settings.key
+     * Dotted path without the storage root, such as Module.Settings.key.
+     */
+    key: string;
+    /**
+     * 纯文本标题
+     * Plain-text title.
+     */
+    name: string;
+    /**
+     * 纯文本说明
+     * Plain-text description.
+     */
+    description?: string;
+    /**
+     * 原始 BoxJS 控件类型，与持久化值类型区分
+     * Original BoxJS control kind, separate from the stored value type.
+     */
+    control?: "boolean" | "checkboxes" | "selects" | "text" | "textarea" | "number";
+    /**
+     * 输入占位文字
+     * Input placeholder.
+     */
+    placeholder?: string;
+    /**
+     * 多行控件的基础行数，必须为正整数
+     * Positive baseline row count for a textarea.
+     */
+    rows?: number;
+    /**
+     * 是否随多行内容自动调整高度
+     * Whether textarea height follows its contents.
+     */
+    autoGrow?: boolean;
 }
 /**
  * 归一化字段；默认值和选项必须符合对应 type，缺失默认值保持缺失。
  * Normalized field; defaults and choices match type, and absent defaults stay absent.
  */
 export type SettingsField = FieldBase &
-	(
-		| { type: "boolean"; defaultValue?: boolean; options?: SettingsOption<boolean>[] }
-		| { type: "number"; defaultValue?: number; options?: SettingsOption<number>[] }
-		| { type: "string"; defaultValue?: string; options?: SettingsOption<string>[] }
-		| { type: "array"; defaultValue?: SettingsScalar[]; options?: SettingsOption[] }
-	);
+    (
+        | { type: "boolean"; defaultValue?: boolean; options?: SettingsOption<boolean>[] }
+        | { type: "number"; defaultValue?: number; options?: SettingsOption<number>[] }
+        | { type: "string"; defaultValue?: string; options?: SettingsOption<string>[] }
+        | { type: "array"; defaultValue?: SettingsScalar[]; options?: SettingsOption[] }
+    );
 /**
  * 代理宿主提供的请求；保留字符串方法以便拒绝不支持的方法。
  * Request provided by the proxy host; string methods allow unsupported methods to be rejected.
  */
 export interface SettingsRequest {
-	/** 请求的完整 URL / Absolute request URL. */
-	url: string;
-	/** 区分大小写的 HTTP 方法 / Case-sensitive HTTP method. */
-	method: string;
-	/** 头名称在处理器中统一转为小写 / Header names are normalized to lowercase by the handler. */
-	headers?: Record<string, string | undefined>;
-	/** POST 的正文为 JSON 值本身；DELETE 无正文 / POST contains the JSON value itself; DELETE has no body. */
-	body?: string;
+    /**
+     * 请求的完整 URL
+     * Absolute request URL.
+     */
+    url: string;
+    /**
+     * 区分大小写的 HTTP 方法
+     * Case-sensitive HTTP method.
+     */
+    method: string;
+    /**
+     * 头名称在处理器中统一转为小写
+     * Header names are normalized to lowercase by the handler.
+     */
+    headers?: Record<string, string | undefined>;
+    /**
+     * POST 的正文为 JSON 值本身；DELETE 无正文
+     * POST contains the JSON value itself; DELETE has no body.
+     */
+    body?: string;
 }
 /**
  * 通用 HTTP 响应，调用方负责转换为代理宿主的 done 格式。
  * Generic HTTP response; the caller adapts it to the host's done format.
  */
 export interface SettingsResponse {
-	/** 数字状态码 / Numeric status code. */
-	status: number;
-	/** 响应头 / Response headers. */
-	headers: Record<string, string>;
-	/** JSON 文本；HEAD 始终为空字符串 / JSON text; always an empty string for HEAD. */
-	body: string;
+    /**
+     * 数字状态码
+     * Numeric status code.
+     */
+    status: number;
+    /**
+     * 响应头
+     * Response headers.
+     */
+    headers: Record<string, string>;
+    /**
+     * JSON 文本；HEAD 始终为空字符串
+     * JSON text; always an empty string for HEAD.
+     */
+    body: string;
 }
 /**
- * 由插件安装配置提供的固定存储映射，不接受浏览器指定存储根。
- * Fixed storage mapping provided by plugin installation, never a browser-selected root.
+ * 属于单个模块的字段、存储根及可选展示元数据。
+ * Fields, storage root and optional display metadata belonging to one module.
  */
-export interface SettingsHandlerOptions {
-	/** 接管 /api/ 路径的 HTTPS 来源 / HTTPS origin serving /api/ paths. */
-	origin: string;
-	/** 顶层持久化键，不能使用 @ 路径语法 / Literal top-level storage key, without @ path syntax. */
-	storageKey: string;
-	/** /api/ 后允许访问的模块；独立通用模块可声明多个 / Allowed module segments following /api/; a standalone installation can declare several. */
-	module: string | string[];
-	/** 默认 X-Settings-Client，值必须为 1；不是认证凭据 / Defaults to X-Settings-Client with value 1; not an authentication credential. */
-	requestHeader?: string;
+export interface ModuleDefinition {
+    /**
+     * 字段 ID 的模块段，不能由 app 名称推断
+     * Module segment from field IDs, never inferred from app names.
+     */
+    module: string;
+    /**
+     * 由 @root.module.path 中的 root 提取
+     * Root extracted from @root.module.path.
+     */
+    storageKey: string;
+    /**
+     * 保留配置文件中的字段顺序
+     * Fields in configuration order.
+     */
+    fields: SettingsField[];
+    /**
+     * 含模块名的公共父路径片段
+     * Common parent path segments including the module name.
+     */
+    settingsPath: string[];
+    /**
+     * 只有字段来自唯一 app 时提供
+     * Present only when all fields belong to one app.
+     */
+    metadata?: {
+        /**
+         * 应用标识，仅用于展示或溯源
+         * App identifier for display or provenance only.
+         */
+        id?: string;
+        /**
+         * 显示名称
+         * Display name.
+         */
+        name?: string;
+        /**
+         * 作者纯文本
+         * Plain-text author.
+         */
+        author?: string;
+        /**
+         * 项目地址；页面仅接受 HTTP(S) 或相对链接
+         * Project address; the page accepts only HTTP(S) or relative URLs.
+         */
+        repo?: string;
+        /**
+         * 仅保留来源信息，不执行脚本
+         * Source metadata only; never executed.
+         */
+        script?: string;
+        /**
+         * 优先使用的显式图标地址
+         * Explicit preferred icon URL.
+         */
+        icon?: string;
+        /**
+         * 原版透明/彩色顺序，不是亮暗顺序
+         * Original transparent/color order, not light/dark order.
+         */
+        icons?: string[];
+        /**
+         * 多段纯文本说明
+         * Multiple plain-text paragraphs.
+         */
+        descs?: string[];
+        /**
+         * desc 未提供时的说明
+         * Description used when desc is absent.
+         */
+        description?: string;
+        /**
+         * 优先使用的纯文本说明
+         * Preferred plain-text description.
+         */
+        desc?: string;
+    };
 }
 /**
- * 原生 Mock 的等价资源映射，支持不具备该语法的代理。
- * Equivalent resource mapping for proxies lacking native Mock syntax.
+ * 可序列化的 JSON 值。
+ * Serializable JSON value.
  */
-export interface PreferencesHandlerOptions extends SettingsHandlerOptions {
-	/** 按 pathname 匹配，不匹配下载源自身 / Match pathnames without intercepting the download source itself. */
-	resources: Array<{
-		/** 锚定的 pathname 正则 / Anchored pathname regular expression. */
-		pattern: string;
-		/** HTTPS 下载源 / HTTPS resource source. */
-		source: string;
-		/** 响应媒体类型 / Response media type. */
-		contentType: string;
-	}>;
-}
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 /**
- * 通用安装入口；API 保持无网络读写，静态请求才下载资源。
- * Generic installation entry; APIs remain network-free and only static requests download resources.
+ * 标准 BoxJS 展示元数据。
+ * Standard BoxJS presentation metadata.
  */
-export class PreferencesHandler extends SettingsHandler {
-	/** @param options 安装 JSON 配置 / Installation JSON configuration. */
-	constructor(options: PreferencesHandlerOptions);
-}
+export type BoxJSMetadata = NonNullable<ModuleDefinition["metadata"]>;
 /**
- * 属于单个模块的字段、存储根及可选展示元数据。
- * Fields, storage root and optional display metadata belonging to one module.
+ * 标准 BoxJS 设置项，由浏览器解析控件语义。
+ * Standard BoxJS setting interpreted by the browser.
  */
-export interface ModuleDefinition {
-	/** 字段 ID 的模块段，不能由 app 名称推断 / Module segment from field IDs, never inferred from app names. */
-	module: string;
-	/** 由 @root.module.path 中的 root 提取 / Root extracted from @root.module.path. */
-	storageKey: string;
-	/** 保留配置文件中的字段顺序 / Fields in configuration order. */
-	fields: SettingsField[];
-	/** 含模块名的公共父路径片段 / Common parent path segments including the module name. */
-	settingsPath: string[];
-	/** 只有字段来自唯一 app 时提供 / Present only when all fields belong to one app. */
-	metadata?: {
-		/** 应用标识，仅用于展示或溯源 / App identifier for display or provenance only. */
-		id?: string;
-		/** 显示名称 / Display name. */
-		name?: string;
-		/** 作者纯文本 / Plain-text author. */
-		author?: string;
-		/** 项目地址；页面仅接受 HTTP(S) 或相对链接 / Project address; the page accepts only HTTP(S) or relative URLs. */
-		repo?: string;
-		/** 仅保留来源信息，不执行脚本 / Source metadata only; never executed. */
-		script?: string;
-		/** 优先使用的显式图标地址 / Explicit preferred icon URL. */
-		icon?: string;
-		/** 原版透明/彩色顺序，不是亮暗顺序 / Original transparent/color order, not light/dark order. */
-		icons?: string[];
-		/** 多段纯文本说明 / Multiple plain-text paragraphs. */
-		descs?: string[];
-		/** desc 未提供时的说明 / Description used when desc is absent. */
-		description?: string;
-		/** 优先使用的纯文本说明 / Preferred plain-text description. */
-		desc?: string;
-	};
+export interface BoxJSSetting {
+    /**
+     * 字段存储 ID
+     * Field storage ID.
+     */
+    id: string;
+    /**
+     * 显示名称
+     * Display name.
+     */
+    name: string;
+    /**
+     * BoxJS 控件类型
+     * BoxJS control type.
+     */
+    type: string;
+    /**
+     * 默认 JSON 值
+     * Default JSON value.
+     */
+    val?: JsonValue;
+    /**
+     * 标准扩展属性
+     * Standard extension properties.
+     */
+    [key: string]: unknown;
 }
 /**
- * 将 BoxJS 字段数组、app 或订阅解析为模块定义，不执行脚本或 HTML。
- * Parse a BoxJS field array, app or subscription into a module definition without executing scripts or HTML.
- * @param config 外部 JSON 数据，在运行时校验 / External JSON validated at runtime.
- * @param module 请求路径中的模块标识 / Module identifier from the request path.
- * @returns 字段、公共路径与元数据 / Fields, common path and metadata.
- * @throws {TypeError} 配置格式、类型、路径或选项无效 / Invalid configuration shape, types, paths or options.
+ * 单个 BoxJS 应用。
+ * A BoxJS application.
  */
-export function normalizeBoxJs(config: unknown, module: string): ModuleDefinition;
+export interface BoxJSApp extends BoxJSMetadata {
+    /**
+     * 应用设置
+     * Application settings.
+     */
+    settings: BoxJSSetting[];
+}
 /**
- * 使用 util 桥接指定模块的持久化存储，不下载或校验 BoxJS。
- * Bridge module persistence through util without downloading or validating BoxJS.
+ * BoxJS 订阅。
+ * A BoxJS subscription.
  */
-export class SettingsHandler {
-	/**
-	 * 创建实例，不发送请求或读取存储。
-	 * Construct an instance without network requests or storage reads.
-	 * @param options 来源、存储根与模块 / Origin, storage root and module.
-	 * @throws {TypeError} 来源、存储根、模块或头名称无效 / Invalid origin, storage root, module or header name.
-	 */
-	constructor(options: SettingsHandlerOptions);
-	/**
-	 * HEAD 不读存储；GET 返回任意指定值，POST/DELETE 对键或子树读改写一次。
-	 * HEAD avoids storage; GET returns any requested value, and POST/DELETE mutate a key or subtree in one read-modify-write.
-	 * @param request 代理请求 / Proxy request.
-	 * @returns HTTP 响应；非目标来源或非 API 路径返回 undefined / HTTP response, or undefined outside the configured API origin and path.
-	 * @throws {Error} 请求 URL 无效；存储失败以 HTTP 500 返回 / Invalid request URL; storage failures return HTTP 500.
-	 */
-	handle(request: SettingsRequest): Promise<SettingsResponse | undefined>;
+export interface BoxJSSubscription extends BoxJSMetadata {
+    /**
+     * 应用列表
+     * Application list.
+     */
+    apps: BoxJSApp[];
 }
 /**
- * 从完整 URL 解析 /api/ 后的 database 路径。
- * Parse database path segments following /api/ from an absolute URL.
- * @param url 完整请求地址 / Absolute request URL.
- * @returns 已解码的路径片段；非 API 路径返回 undefined / Decoded segments, or undefined for non-API paths.
- * @throws {TypeError} URL、编码或路径片段非法 / Invalid URL, encoding or path segment.
+ * 唯一的数据配置输入。
+ * The sole data configuration input.
+ */
+export type BoxJSInput = BoxJSSetting[] | BoxJSApp | BoxJSSubscription;
+/**
+ * 生成具体模块的页面、代理和配置 Mock，不生成项目入口页。
+ * Build a concrete module's page, proxy and config Mock without a project landing page.
+ * @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 parseSettingsPath(url: string): string[] | undefined;
+export function build(boxjs: BoxJSInput, css?: string): Promise<Record<string, string>>;

package/src/index.mjs

@@ -1,9 +1,6 @@
-export { normalizeBoxJs } from "./lib/boxjs.mjs";
-export { parseSettingsPath } from "./lib/settings-path.mjs";
-export { PreferencesHandler } from "./PreferencesHandler.mjs";
 /**
- * 通用代理处理器与配置解析的公开入口。
- * Public entry for the proxy handler and configuration parsing.
+ * 仅接收 BoxJS JSON 与可选 CSS 的构建入口。
+ * Build entry accepting only BoxJS JSON and optional CSS.
  * @module @nsnanocat/preference-panes
  */
-export { SettingsHandler } from "./SettingsHandler.mjs";
+export { build } from "./build.mjs";