@fecommunity/reactpress-toolkit 3.0.4 → 3.7.0

package/dist/extension/branding-mods.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THEME_BRANDING_DIRECT_MODS = exports.THEME_BRANDING_MOD_TO_SETTING = void 0;
+exports.seedThemeModsFromLegacySetting = seedThemeModsFromLegacySetting;
+exports.applyThemeModsToSiteSetting = applyThemeModsToSiteSetting;
+exports.brandingModValue = brandingModValue;
+/** Customizer mod id → legacy Setting column (runtime overlay for themes). */
+exports.THEME_BRANDING_MOD_TO_SETTING = {
+    displayTitle: 'systemTitle',
+    displayTagline: 'systemSubTitle',
+    siteLogo: 'systemLogo',
+    backgroundImage: 'systemBg',
+    siteFavicon: 'systemFavicon',
+    siteNotice: 'systemNoticeInfo',
+    seoKeyword: 'seoKeyword',
+    seoDesc: 'seoDesc',
+    baiduAnalyticsId: 'baiduAnalyticsId',
+    googleAnalyticsId: 'googleAnalyticsId',
+};
+/** Mod ids stored under the same key in mods and Setting overlay. */
+exports.THEME_BRANDING_DIRECT_MODS = [
+    'systemFooterInfo',
+    'aboutUsGithubUrl',
+    'aboutUsCommentQr',
+    'aboutUsWechatQr',
+];
+function modValue(mods, modId) {
+    const v = mods[modId];
+    if (v == null || String(v).trim() === '')
+        return undefined;
+    return String(v);
+}
+/** Build customizer form seed from legacy Setting columns (one-time / fallback). */
+function seedThemeModsFromLegacySetting(setting, mods = {}) {
+    const merged = { ...mods };
+    for (const [modId, settingKey] of Object.entries(exports.THEME_BRANDING_MOD_TO_SETTING)) {
+        if (!modValue(merged, modId) && setting?.[settingKey] != null) {
+            merged[modId] = String(setting[settingKey]);
+        }
+    }
+    for (const key of exports.THEME_BRANDING_DIRECT_MODS) {
+        if (!modValue(merged, key) && setting?.[key] != null) {
+            merged[key] = String(setting[key]);
+        }
+    }
+    return merged;
+}
+/** Overlay theme mods onto a Setting-shaped object for theme runtime & mail templates. */
+function applyThemeModsToSiteSetting(setting, mods) {
+    const next = { ...setting };
+    for (const [modId, settingKey] of Object.entries(exports.THEME_BRANDING_MOD_TO_SETTING)) {
+        const v = modValue(mods, modId);
+        if (v)
+            next[settingKey] = v;
+    }
+    for (const key of exports.THEME_BRANDING_DIRECT_MODS) {
+        const v = modValue(mods, key);
+        if (v)
+            next[key] = v;
+    }
+    return next;
+}
+function brandingModValue(mods, modId) {
+    return modValue(mods, modId);
+}

package/dist/extension/configuration/defaults.d.ts

@@ -0,0 +1,3 @@
+import type { ThemeConfigurationSchema } from './types';
+/** Collect `default` values from a JSON Schema object tree. */
+export declare function defaultsFromSchema(schema: ThemeConfigurationSchema | null | undefined): Record<string, unknown>;

package/dist/extension/configuration/defaults.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultsFromSchema = defaultsFromSchema;
+/** Collect `default` values from a JSON Schema object tree. */
+function defaultsFromSchema(schema) {
+    if (!schema?.properties)
+        return {};
+    const out = {};
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        const value = defaultFromProperty(prop);
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function defaultFromProperty(prop) {
+    if (!prop)
+        return undefined;
+    if (prop.default !== undefined)
+        return prop.default;
+    if (prop.type === 'object' && prop.properties) {
+        const nested = {};
+        for (const [k, p] of Object.entries(prop.properties)) {
+            const v = defaultFromProperty(p);
+            if (v !== undefined)
+                nested[k] = v;
+        }
+        return Object.keys(nested).length ? nested : undefined;
+    }
+    return undefined;
+}

package/dist/extension/configuration/formily.d.ts

@@ -0,0 +1,10 @@
+import type { ThemeConfigurationSchema } from './types';
+/** Formily `ISchema` node (JSON Schema + Formily x-* extensions). */
+export type FormilySchemaNode = Record<string, unknown>;
+export declare function registerFormilyWidget(widgetId: string, componentName: string): void;
+/**
+ * Convert theme `reactpress.configuration` JSON Schema to Formily render schema.
+ * Adds `x-decorator` / `x-component` from types and `x-ui.widget`.
+ */
+export declare function toFormilyJsonSchema(schema: ThemeConfigurationSchema | null | undefined): FormilySchemaNode | null;
+export declare function getFormilyVoidComponents(): string[];

package/dist/extension/configuration/formily.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFormilyWidget = registerFormilyWidget;
+exports.toFormilyJsonSchema = toFormilyJsonSchema;
+exports.getFormilyVoidComponents = getFormilyVoidComponents;
+const VOID_COMPONENTS = [
+    'FormLayout',
+    'FormGrid',
+    'FormGrid.GridColumn',
+    'SectionCard',
+    'FormCollapse',
+    'FormCollapse.CollapsePanel',
+    'CollapsePanel',
+    'FormTab',
+    'FormTab.TabPane',
+];
+/** Map `x-ui.widget` → Formily `x-component` (extend via registerFormilyWidget). */
+const WIDGET_COMPONENT_MAP = {
+    navLinkList: 'NavLinkListField',
+    urlConfigEditor: 'JsonConfigEditor',
+    navSearchEditor: 'JsonConfigEditor',
+};
+const registeredWidgets = { ...WIDGET_COMPONENT_MAP };
+function registerFormilyWidget(widgetId, componentName) {
+    registeredWidgets[widgetId] = componentName;
+}
+/**
+ * Convert theme `reactpress.configuration` JSON Schema to Formily render schema.
+ * Adds `x-decorator` / `x-component` from types and `x-ui.widget`.
+ */
+function toFormilyJsonSchema(schema) {
+    if (!schema || schema.type !== 'object')
+        return null;
+    const root = convertProperty({ ...schema, type: 'object' }, 0, true);
+    const sectionProps = (root.properties ?? {});
+    return {
+        type: 'object',
+        'x-component': 'FormLayout',
+        'x-component-props': { layout: 'vertical', style: { width: '100%' } },
+        properties: wrapRootSections(sectionProps),
+    };
+}
+/** Full-width section cards; field paths stay `header.*` / `nav.*`. */
+function wrapRootSections(properties) {
+    return Object.fromEntries(Object.entries(properties).map(([key, child]) => {
+        const title = typeof child.title === 'string' ? child.title : key;
+        const inner = withObjectLayout(child);
+        return [
+            key,
+            {
+                ...inner,
+                'x-decorator': 'SectionCard',
+                'x-decorator-props': {
+                    title,
+                    sectionId: `theme-section-${key}`,
+                    feedbackLayout: 'none',
+                    layout: 'vertical',
+                    fullness: true,
+                },
+            },
+        ];
+    }));
+}
+/** Ensure nested object fields render their properties in Formily. */
+function withObjectLayout(node, title) {
+    if (node.type !== 'object' || !node.properties)
+        return node;
+    const props = node.properties;
+    const keys = Object.keys(props);
+    return {
+        ...node,
+        ...(keys.length > 1 ? { title } : {}),
+        'x-component': 'FormLayout',
+        'x-component-props': { layout: 'vertical' },
+    };
+}
+function convertProperty(node, depth, isRoot = false) {
+    const ui = node['x-ui'];
+    if (ui?.hidden) {
+        return { ...node, 'x-display': 'hidden' };
+    }
+    const type = typeof node.type === 'string' ? node.type : undefined;
+    if (type === 'object') {
+        const widget = ui?.widget ? registeredWidgets[ui.widget] : undefined;
+        if (widget === 'JsonConfigEditor') {
+            return {
+                ...stripMeta(node),
+                type: 'object',
+                'x-decorator': 'FormItem',
+                'x-decorator-props': {
+                    feedbackLayout: 'none',
+                    layout: 'vertical',
+                    fullness: true,
+                    wrapperCol: 24,
+                },
+                'x-component': 'JsonConfigEditor',
+                'x-component-props': { height: 360 },
+            };
+        }
+        if (node.properties) {
+            const properties = Object.fromEntries(Object.entries(node.properties).map(([key, child]) => [
+                key,
+                convertProperty(child, depth + 1),
+            ]));
+            return {
+                ...stripMeta(node),
+                type: 'object',
+                properties,
+            };
+        }
+    }
+    if (type === 'array') {
+        const widget = ui?.widget ? registeredWidgets[ui.widget] : undefined;
+        const out = {
+            ...stripMeta(node),
+            type: 'array',
+            'x-decorator': 'FormItem',
+            'x-decorator-props': {
+                feedbackLayout: 'none',
+                layout: 'vertical',
+                colon: false,
+                fullness: true,
+                wrapperCol: 24,
+            },
+            'x-component': widget ?? 'ArrayCards',
+            'x-component-props': widget === 'NavLinkListField'
+                ? {}
+                : widget === 'ArrayCards'
+                    ? { title: node.title ?? 'Item' }
+                    : {},
+        };
+        if (widget !== 'NavLinkListField' && node.items && typeof node.items === 'object' && !Array.isArray(node.items)) {
+            out.items = convertProperty(node.items, depth + 1);
+        }
+        return out;
+    }
+    if (type === 'boolean') {
+        return {
+            ...stripMeta(node),
+            type: 'boolean',
+            'x-decorator': 'FormItem',
+            'x-component': 'Switch',
+        };
+    }
+    if (type === 'number' || type === 'integer') {
+        return {
+            ...stripMeta(node),
+            type: 'number',
+            'x-decorator': 'FormItem',
+            'x-component': 'NumberPicker',
+        };
+    }
+    if (type === 'string') {
+        const component = node.enum ? 'Select' : 'Input';
+        return {
+            ...stripMeta(node),
+            type: 'string',
+            'x-decorator': 'FormItem',
+            'x-component': component,
+        };
+    }
+    return { ...stripMeta(node) };
+}
+function stripMeta(node) {
+    const { ['x-ui']: _ui, ...rest } = node;
+    return { ...rest };
+}
+function getFormilyVoidComponents() {
+    return [...VOID_COMPONENTS];
+}

package/dist/extension/configuration/index.d.ts

@@ -0,0 +1,7 @@
+export * from './defaults';
+export * from './formily';
+export * from './paths';
+export { getThemeConfigurationSchema, getThemeConfigurationSeed, TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA, twentytwentyfiveConfigSeed, } from './presets/twentytwentyfive';
+export * from './resolve';
+export * from './types';
+export * from './validate';

package/dist/extension/configuration/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.twentytwentyfiveConfigSeed = exports.TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA = exports.getThemeConfigurationSeed = exports.getThemeConfigurationSchema = void 0;
+__exportStar(require("./defaults"), exports);
+__exportStar(require("./formily"), exports);
+__exportStar(require("./paths"), exports);
+var twentytwentyfive_1 = require("./presets/twentytwentyfive");
+Object.defineProperty(exports, "getThemeConfigurationSchema", { enumerable: true, get: function () { return twentytwentyfive_1.getThemeConfigurationSchema; } });
+Object.defineProperty(exports, "getThemeConfigurationSeed", { enumerable: true, get: function () { return twentytwentyfive_1.getThemeConfigurationSeed; } });
+Object.defineProperty(exports, "TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA", { enumerable: true, get: function () { return twentytwentyfive_1.TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA; } });
+Object.defineProperty(exports, "twentytwentyfiveConfigSeed", { enumerable: true, get: function () { return twentytwentyfive_1.twentytwentyfiveConfigSeed; } });
+__exportStar(require("./resolve"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./validate"), exports);

package/dist/extension/configuration/paths.d.ts

@@ -0,0 +1,4 @@
+/** Deep get/set for nested configuration objects. */
+export declare function getByPath(obj: unknown, path: string): unknown;
+export declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;

package/dist/extension/configuration/paths.js

@@ -0,0 +1,50 @@
+"use strict";
+/** Deep get/set for nested configuration objects. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getByPath = getByPath;
+exports.setByPath = setByPath;
+exports.deepMerge = deepMerge;
+function getByPath(obj, path) {
+    if (!path)
+        return obj;
+    const parts = path.split('.');
+    let cur = obj;
+    for (const part of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function setByPath(obj, path, value) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        const next = cur[key];
+        if (next == null || typeof next !== 'object' || Array.isArray(next)) {
+            cur[key] = {};
+        }
+        cur = cur[key];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function deepMerge(target, source) {
+    const out = { ...target };
+    for (const key of Object.keys(source)) {
+        const sv = source[key];
+        const tv = out[key];
+        if (sv &&
+            typeof sv === 'object' &&
+            !Array.isArray(sv) &&
+            tv &&
+            typeof tv === 'object' &&
+            !Array.isArray(tv)) {
+            out[key] = deepMerge(tv, sv);
+        }
+        else if (sv !== undefined) {
+            out[key] = sv;
+        }
+    }
+    return out;
+}

package/dist/extension/configuration/presets/twentytwentyfive.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeConfigurationSchema } from '../types';
+/** Declarative schema shipped with the default blog theme (also embedded in `theme.json`). */
+export declare const TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA: ThemeConfigurationSchema;
+/** Seed nav blocks from toolkit `globalSetting` locale bundles (too large for inline schema defaults). */
+export declare function twentytwentyfiveConfigSeed(locale?: string): Record<string, unknown>;
+export declare function getThemeConfigurationSchema(themeId: string): ThemeConfigurationSchema | null;
+export declare function getThemeConfigurationSeed(themeId: string, locale?: string): Record<string, unknown> | null;

package/dist/extension/configuration/presets/twentytwentyfive.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA = void 0;
+exports.twentytwentyfiveConfigSeed = twentytwentyfiveConfigSeed;
+exports.getThemeConfigurationSchema = getThemeConfigurationSchema;
+exports.getThemeConfigurationSeed = getThemeConfigurationSeed;
+const global_1 = require("../../../config/global");
+const defaults_1 = require("../defaults");
+const paths_1 = require("../paths");
+/** Declarative schema shipped with the default blog theme (also embedded in `theme.json`). */
+exports.TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Twenty Twenty-Five',
+    description: '顶栏导航与 /nav 网址导航、聚合搜索',
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        header: {
+            type: 'object',
+            title: '顶栏',
+            properties: {
+                navLinks: {
+                    type: 'array',
+                    title: '固定导航链接',
+                    description: '显示在「页面」模块发布的自定义页面之前',
+                    default: [
+                        { path: '/', locale: 'home', icon: 'HomeOutlined', visible: true },
+                        { path: '/nav', locale: 'nav', icon: 'GlobalOutlined', visible: true },
+                        { path: '/knowledge', locale: 'knowledge', icon: 'BookOutlined', visible: false },
+                        { path: '/archives', locale: 'archives', icon: 'HistoryOutlined', visible: true },
+                    ],
+                    items: {
+                        type: 'object',
+                        required: ['path'],
+                        properties: {
+                            path: { type: 'string', title: '路径' },
+                            locale: { type: 'string', title: 'i18n 键' },
+                            label: { type: 'string', title: '覆盖文案' },
+                            icon: { type: 'string', title: 'Ant Design 图标名' },
+                            visible: { type: 'boolean', title: '显示', default: true },
+                        },
+                    },
+                    'x-ui': { widget: 'navLinkList', section: 'header', order: 10 },
+                },
+            },
+        },
+        nav: {
+            type: 'object',
+            title: '网址导航',
+            properties: {
+                urlConfig: {
+                    type: 'array',
+                    title: '导航卡片分组',
+                    'x-ui': { widget: 'urlConfigEditor', section: 'nav', order: 20 },
+                    items: { type: 'object' },
+                },
+                searchCategories: {
+                    type: 'object',
+                    title: '聚合搜索分类',
+                    'x-ui': { widget: 'navSearchEditor', section: 'nav', order: 30 },
+                    properties: {
+                        categories: { type: 'array', items: { type: 'object' } },
+                        subCategories: { type: 'object' },
+                    },
+                },
+            },
+        },
+    },
+};
+/** Seed nav blocks from toolkit `globalSetting` locale bundles (too large for inline schema defaults). */
+function twentytwentyfiveConfigSeed(locale = 'zh') {
+    const gs = global_1.globalSetting;
+    const bundle = locale === 'en' ? gs.en : gs.zh;
+    const gc = bundle?.globalConfig ?? {};
+    return {
+        nav: {
+            urlConfig: gc.urlConfig ?? [],
+            searchCategories: gc.navConfig ?? { categories: [], subCategories: {} },
+        },
+    };
+}
+function getThemeConfigurationSchema(themeId) {
+    if (themeId === 'twentytwentyfive')
+        return exports.TWENTYTWENTYFIVE_CONFIGURATION_SCHEMA;
+    return null;
+}
+function getThemeConfigurationSeed(themeId, locale = 'zh') {
+    const schema = getThemeConfigurationSchema(themeId);
+    if (!schema)
+        return null;
+    const schemaDefaults = (0, defaults_1.defaultsFromSchema)(schema);
+    const navSeed = themeId === 'twentytwentyfive' ? twentytwentyfiveConfigSeed(locale) : {};
+    return (0, paths_1.deepMerge)(schemaDefaults, navSeed);
+}

package/dist/extension/configuration/resolve.d.ts

@@ -0,0 +1,24 @@
+import type { GlobalSettingWithConfig, ResolvedSiteConfig, ThemeConfigurationSchema } from './types';
+export declare function parseGlobalSettingRaw(raw: unknown): GlobalSettingWithConfig;
+type ManifestWithOptions = {
+    options?: ThemeConfigurationSchema;
+};
+export declare function getConfigurationSchemaFromManifest(manifest: ManifestWithOptions | null | undefined, themeId: string): ThemeConfigurationSchema | null;
+export declare function getMergedThemeConfiguration(globalRaw: unknown, themeId: string, options?: {
+    locale?: string;
+    manifest?: ManifestWithOptions;
+}): Record<string, unknown>;
+export declare function getConfig<T = unknown>(configuration: Record<string, unknown>, path: string): T | undefined;
+export declare function patchConfiguration(current: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+export declare function mergeConfigIntoGlobalSetting(globalRaw: unknown, themeId: string, themeConfig: Record<string, unknown>): GlobalSettingWithConfig;
+export declare function resolveSiteConfig(globalRaw: unknown, themeId: string, locale?: string, manifest?: ManifestWithOptions, 
+/** Draft theme config from appearance preview query (not persisted). */
+configOverride?: Record<string, unknown>): ResolvedSiteConfig;
+export declare function validateAndMergeThemeConfiguration(themeId: string, globalRaw: unknown, patch: Record<string, unknown>, manifest?: ManifestWithOptions): {
+    ok: true;
+    config: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+};
+export {};

package/dist/extension/configuration/resolve.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGlobalSettingRaw = parseGlobalSettingRaw;
+exports.getConfigurationSchemaFromManifest = getConfigurationSchemaFromManifest;
+exports.getMergedThemeConfiguration = getMergedThemeConfiguration;
+exports.getConfig = getConfig;
+exports.patchConfiguration = patchConfiguration;
+exports.mergeConfigIntoGlobalSetting = mergeConfigIntoGlobalSetting;
+exports.resolveSiteConfig = resolveSiteConfig;
+exports.validateAndMergeThemeConfiguration = validateAndMergeThemeConfiguration;
+const defaults_1 = require("./defaults");
+const paths_1 = require("./paths");
+const twentytwentyfive_1 = require("./presets/twentytwentyfive");
+const validate_1 = require("./validate");
+const FALLBACK_HEADER_NAV = [
+    { path: '/', locale: 'home', icon: 'HomeOutlined', visible: true },
+    { path: '/nav', locale: 'nav', icon: 'GlobalOutlined', visible: true },
+    { path: '/archives', locale: 'archives', icon: 'HistoryOutlined', visible: true },
+];
+function parseGlobalSettingRaw(raw) {
+    if (!raw)
+        return {};
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    if (typeof raw === 'object')
+        return raw;
+    return {};
+}
+function getConfigurationSchemaFromManifest(manifest, themeId) {
+    const fromManifest = manifest?.options;
+    if (fromManifest && fromManifest.type === 'object')
+        return fromManifest;
+    return (0, twentytwentyfive_1.getThemeConfigurationSchema)(themeId);
+}
+function getMergedThemeConfiguration(globalRaw, themeId, options) {
+    const gs = parseGlobalSettingRaw(globalRaw);
+    const schema = getConfigurationSchemaFromManifest(options?.manifest ?? null, themeId) ??
+        (0, twentytwentyfive_1.getThemeConfigurationSchema)(themeId);
+    const seed = (0, twentytwentyfive_1.getThemeConfigurationSeed)(themeId, options?.locale ?? 'zh') ??
+        (schema ? (0, defaults_1.defaultsFromSchema)(schema) : {});
+    const store = gs.config && typeof gs.config === 'object' ? gs.config : {};
+    const stored = store[themeId];
+    const storedObj = stored && typeof stored === 'object' && !Array.isArray(stored)
+        ? stored
+        : {};
+    return (0, paths_1.deepMerge)((0, paths_1.deepMerge)({}, seed), storedObj);
+}
+function getConfig(configuration, path) {
+    return (0, paths_1.getByPath)(configuration, path);
+}
+function patchConfiguration(current, patch) {
+    return (0, paths_1.deepMerge)({ ...current }, patch);
+}
+function mergeConfigIntoGlobalSetting(globalRaw, themeId, themeConfig) {
+    const gs = parseGlobalSettingRaw(globalRaw);
+    const config = gs.config && typeof gs.config === 'object' ? { ...gs.config } : {};
+    config[themeId] = themeConfig;
+    return { ...gs, config };
+}
+function resolveSiteConfig(globalRaw, themeId, locale = 'zh', manifest, 
+/** Draft theme config from appearance preview query (not persisted). */
+configOverride) {
+    const merged = getMergedThemeConfiguration(globalRaw, themeId, { locale, manifest });
+    const effective = configOverride && Object.keys(configOverride).length > 0
+        ? patchConfiguration(merged, configOverride)
+        : merged;
+    const gs = parseGlobalSettingRaw(globalRaw);
+    const legacyBundle = (gs[locale] ?? gs.zh);
+    const legacy = legacyBundle?.globalConfig;
+    const headerNav = getConfig(effective, 'header.navLinks');
+    const urlConfig = getConfig(effective, 'nav.urlConfig');
+    const searchCategories = getConfig(effective, 'nav.searchCategories');
+    const navLinks = (headerNav ?? FALLBACK_HEADER_NAV).filter((item) => item.visible !== false);
+    return {
+        header: { navLinks },
+        nav: {
+            urlConfig: urlConfig ?? legacy?.urlConfig ?? [],
+            searchCategories: searchCategories ??
+                legacy?.navConfig ?? { categories: [], subCategories: {} },
+        },
+    };
+}
+function validateAndMergeThemeConfiguration(themeId, globalRaw, patch, manifest) {
+    const schema = getConfigurationSchemaFromManifest(manifest ?? null, themeId);
+    const current = getMergedThemeConfiguration(globalRaw, themeId, { manifest });
+    const next = patchConfiguration(current, patch);
+    const result = (0, validate_1.validateThemeConfiguration)(schema, next);
+    if (!result.valid) {
+        return { ok: false, message: result.message ?? 'Invalid configuration' };
+    }
+    return { ok: true, config: next };
+}

package/dist/extension/configuration/types.d.ts

@@ -0,0 +1,68 @@
+/** JSON Schema–driven theme/site configuration (VS Code `contributes.configuration` style). */
+/** UI hints for admin settings editor (P2); stored in schema only. */
+export interface ConfigurationUiMeta {
+    widget?: string;
+    section?: string;
+    order?: number;
+    scope?: 'site' | 'locale';
+    hidden?: boolean;
+}
+/** JSON Schema 7 object schema for theme `reactpress.configuration`. */
+export interface ThemeConfigurationSchema {
+    $schema?: string;
+    title?: string;
+    description?: string;
+    type: 'object';
+    properties?: Record<string, ThemeConfigurationPropertySchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+export type ThemeConfigurationPropertySchema = {
+    type?: string | string[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    items?: ThemeConfigurationPropertySchema;
+    properties?: Record<string, ThemeConfigurationPropertySchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    /** Extension: admin widget id */
+    'x-ui'?: ConfigurationUiMeta;
+    [key: string]: unknown;
+};
+export interface HeaderNavLinkConfig {
+    path: string;
+    locale?: string;
+    label?: string;
+    icon?: string;
+    visible?: boolean;
+}
+export interface ThemeConfigStore {
+    [themeId: string]: Record<string, unknown>;
+}
+export interface GlobalSettingWithConfig {
+    zh?: {
+        globalConfig?: unknown;
+        [key: string]: unknown;
+    };
+    en?: {
+        globalConfig?: unknown;
+        [key: string]: unknown;
+    };
+    theme?: unknown;
+    config?: ThemeConfigStore;
+    [key: string]: unknown;
+}
+export interface ResolvedSiteConfig {
+    header: {
+        navLinks: HeaderNavLinkConfig[];
+    };
+    nav: {
+        urlConfig: unknown[];
+        searchCategories: {
+            categories?: unknown[];
+            subCategories?: Record<string, unknown[]>;
+        };
+    };
+}