@fecommunity/reactpress-toolkit 4.0.0-beta.8 → 4.0.0

package/README.md

@@ -1,8 +1,22 @@
 # @fecommunity/reactpress-toolkit
 
-TypeScript SDK for the ReactPress publishing platform — OpenAPI clients, Next.js theme SSR, plugin hooks, and headless UI components.
+> **Official TypeScript SDK for the ReactPress publishing platform.**
 
-Use in **themes**, **plugins**, **Admin extensions**, and **custom frontends** instead of duplicating API or SSR logic.
+[![npm version](https://img.shields.io/npm/v/@fecommunity/reactpress-toolkit/beta.svg?label=beta)](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit/v/beta)
+[![npm latest](https://img.shields.io/npm/v/@fecommunity/reactpress-toolkit.svg?label=latest)](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit)
+[![npm downloads](https://img.shields.io/npm/dm/@fecommunity/reactpress-toolkit.svg)](https://www.npmjs.com/package/@fecommunity/reactpress-toolkit)
+[![License: MIT](https://img.shields.io/npm/l/@fecommunity/reactpress-toolkit.svg)](https://github.com/fecommunity/reactpress/blob/master/LICENSE)
+
+The shared foundation for **ReactPress themes, plugins, Admin extensions, and custom frontends**. Auto-generated OpenAPI clients, Next.js theme SSR helpers, plugin admin hooks, and headless React UI — so you extend the platform instead of duplicating API or rendering logic.
+
+| Use case | Start here |
+| :------- | :--------- |
+| **Next.js themes** | `./theme`, `./theme/next-config`, `./app` |
+| **Plugins** | `./plugin`, `./plugin/admin`, `./plugin/client` |
+| **API integration** | `./api`, `./api/instance`, `./types` |
+| **Headless UI** | `./ui` — unstyled components and hooks |
+
+[Documentation](https://docs.gaoredu.com/) · [ReactPress CLI](../cli/) · [GitHub](https://github.com/fecommunity/reactpress)
 
 ## Package exports (`package.json` → `exports`)
 
@@ -271,4 +285,6 @@ Output in `dist/`; `createApp.js` is emitted via `tsc` (`allowJs`) to `dist/them
 
 ## License
 
-ISC
+MIT © [FECommunity](https://github.com/fecommunity)
+
+<p align="center"><sub>Part of <a href="https://github.com/fecommunity/reactpress">ReactPress</a> — the official SDK for themes, plugins, and custom frontends.</sub></p>

package/dist/config/locales/en.json

@@ -121,5 +121,5 @@
   "navCategoryMenu": "Navigation categories",
   "carouselPrev": "Previous slide, {current} of {total}",
   "carouselNext": "Next slide, {current} of {total}",
-  "aboutUsFallback": "ReactPress — Modern blog publishing platform"
+  "aboutUsFallback": "ReactPress — Publish with React. Ship like WordPress."
 }

package/dist/config/locales/zh.json

@@ -121,5 +121,5 @@
   "navCategoryMenu": "导航分类",
   "carouselPrev": "上一张，第 {current} 张，共 {total} 张",
   "carouselNext": "下一张，第 {current} 张，共 {total} 张",
-  "aboutUsFallback": "ReactPress — 现代化博客发布平台"
+  "aboutUsFallback": "ReactPress — 用 React 发布，像 WordPress 一样交付。"
 }

package/dist/plugin/extension/plugin-admin-locale.d.ts

@@ -1,7 +1,10 @@
 import { getNestedLocaleString, getNestedLocaleValue } from '../../utils/object';
-/** Admin copy shipped with the plugin (`locales/{locale}.json`). */
+/** Admin copy shipped with the plugin (`src/locales/{locale}.json`). */
 export type PluginAdminLocaleMessages = Record<string, unknown>;
-export declare const PLUGIN_LOCALE_DIR = "locales";
+/** Primary locale directory inside a plugin package. */
+export declare const PLUGIN_LOCALE_DIR = "src/locales";
+/** Legacy root-level locale dir (pre–4.x layout); kept for older bundled plugins. */
+export declare const PLUGIN_LOCALE_DIR_LEGACY = "locales";
 export { getNestedLocaleString, getNestedLocaleValue };
 type PluginSchemaProperty = {
     type?: string;

package/dist/plugin/extension/plugin-admin-locale.io.js

@@ -37,18 +37,20 @@ exports.readPluginAdminLocaleFile = readPluginAdminLocaleFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const plugin_admin_locale_1 = require("./plugin-admin-locale");
+const PLUGIN_LOCALE_SEARCH_DIRS = [plugin_admin_locale_1.PLUGIN_LOCALE_DIR, plugin_admin_locale_1.PLUGIN_LOCALE_DIR_LEGACY];
 function readPluginAdminLocaleFile(pluginDir, locale) {
     const safeLocale = /^[a-z]{2}(?:-[a-z]{2})?$/i.test(locale) ? locale : 'en';
-    const filePath = path.join(pluginDir, plugin_admin_locale_1.PLUGIN_LOCALE_DIR, `${safeLocale}.json`);
-    if (!fs.existsSync(filePath))
-        return null;
-    try {
-        const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        return raw && typeof raw === 'object' && !Array.isArray(raw)
-            ? raw
-            : null;
-    }
-    catch {
-        return null;
+    for (const localeDir of PLUGIN_LOCALE_SEARCH_DIRS) {
+        const filePath = path.join(pluginDir, localeDir, `${safeLocale}.json`);
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+        }
+        catch {
+            return null;
+        }
     }
+    return null;
 }

package/dist/plugin/extension/plugin-admin-locale.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNestedLocaleValue = exports.getNestedLocaleString = exports.PLUGIN_LOCALE_DIR = void 0;
+exports.getNestedLocaleValue = exports.getNestedLocaleString = exports.PLUGIN_LOCALE_DIR_LEGACY = exports.PLUGIN_LOCALE_DIR = void 0;
 exports.resolvePluginAdminLocaleText = resolvePluginAdminLocaleText;
 exports.localizePluginSettingsSchemaWithLocale = localizePluginSettingsSchemaWithLocale;
 const object_1 = require("../../utils/object");
 Object.defineProperty(exports, "getNestedLocaleString", { enumerable: true, get: function () { return object_1.getNestedLocaleString; } });
 Object.defineProperty(exports, "getNestedLocaleValue", { enumerable: true, get: function () { return object_1.getNestedLocaleValue; } });
-exports.PLUGIN_LOCALE_DIR = 'locales';
+/** Primary locale directory inside a plugin package. */
+exports.PLUGIN_LOCALE_DIR = 'src/locales';
+/** Legacy root-level locale dir (pre–4.x layout); kept for older bundled plugins. */
+exports.PLUGIN_LOCALE_DIR_LEGACY = 'locales';
 /** Resolve admin copy from plugin locale bundle; falls back to manifest text. */
 function resolvePluginAdminLocaleText(messages, dotPath, fallback) {
     const fromLocale = messages ? (0, object_1.getNestedLocaleString)(messages, dotPath) : undefined;

package/dist/plugin/extension/plugin.d.ts

@@ -20,7 +20,7 @@ export interface PluginAdminSlotsManifest {
     subscribe?: AdminSlotId[];
 }
 export interface PluginAdminManifest {
-    /** @deprecated Use convention `admin/index.ts`; declared slots drive loading. */
+    /** @deprecated Use convention `src/admin/index.ts`; declared slots drive loading. */
     entry?: string;
     slots?: PluginAdminSlotsManifest;
     menu?: PluginAdminMenuManifest;

package/dist/plugin/extension/plugin.js

@@ -39,15 +39,12 @@ function parsePluginManifest(raw) {
                 hooks: serverRaw.hooks &&
                     typeof serverRaw.hooks === 'object'
                     ? {
-                        subscribe: Array.isArray(serverRaw.hooks
-                            .subscribe)
+                        subscribe: Array.isArray(serverRaw.hooks.subscribe)
                             ? serverRaw.hooks
                                 .subscribe.filter((h) => typeof h === 'string')
                             : undefined,
-                        provide: Array.isArray(serverRaw.hooks
-                            .provide)
-                            ? serverRaw.hooks
-                                .provide.filter((h) => typeof h === 'string')
+                        provide: Array.isArray(serverRaw.hooks.provide)
+                            ? serverRaw.hooks.provide.filter((h) => typeof h === 'string')
                             : undefined,
                     }
                     : undefined,
@@ -59,17 +56,13 @@ function parsePluginManifest(raw) {
         ? (() => {
             const raw = adminRaw;
             const slotsRaw = raw.slots;
-            const subscribe = slotsRaw &&
-                typeof slotsRaw === 'object' &&
-                Array.isArray(slotsRaw.subscribe)
+            const subscribe = slotsRaw && typeof slotsRaw === 'object' && Array.isArray(slotsRaw.subscribe)
                 ? slotsRaw.subscribe.filter((slot) => typeof slot === 'string' && (0, slots_1.isAdminSlotId)(slot))
                 : undefined;
             return {
                 entry: typeof raw.entry === 'string' ? raw.entry : undefined,
                 slots: subscribe?.length ? { subscribe } : undefined,
-                menu: raw.menu && typeof raw.menu === 'object'
-                    ? raw.menu
-                    : undefined,
+                menu: raw.menu && typeof raw.menu === 'object' ? raw.menu : undefined,
             };
         })()
         : undefined;
@@ -83,9 +76,7 @@ function parsePluginManifest(raw) {
         }
         : undefined;
     const capsRaw = o.capabilities;
-    const capabilities = capsRaw && typeof capsRaw === 'object'
-        ? capsRaw
-        : undefined;
+    const capabilities = capsRaw && typeof capsRaw === 'object' ? capsRaw : undefined;
     return {
         id: o.id,
         name: o.name,

package/dist/theme/build/next-config.js

@@ -41,9 +41,12 @@ function applyThemeWebpackResolve(config, appDir) {
  * Pass overrides to extend (your `webpack` runs after the supports-color alias).
  */
 function createReactPressNextConfig(overrides = {}) {
-    const { webpack: userWebpack, eslint, transpilePackages, ...rest } = overrides;
+    const { webpack: userWebpack, eslint, transpilePackages, compress, ...rest } = overrides;
     return {
         reactStrictMode: true,
+        // Themes rewrite `/api` to Nest. Next's compress middleware decompresses upstream
+        // bodies but can still emit `Content-Encoding: br`, breaking admin fetch (ERR_CONTENT_DECODING_FAILED).
+        compress: compress ?? false,
         transpilePackages: ['@fecommunity/reactpress-toolkit', ...(transpilePackages ?? [])],
         eslint: {
             ignoreDuringBuilds: true,

package/dist/ui/components/SiteCustomHtml.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface SiteCustomHtmlProps {
+    children?: React.ReactNode;
+    /**
+     * When true (default), wrap nodes in `next/head` for Pages Router SSR.
+     * App Router themes should pass `html` into layout `<head>` via `renderCustomHeadHtml` instead.
+     */
+    useNextHead?: boolean;
+    /** Optional HTML override (skips reading site setting). */
+    html?: string;
+}
+export { renderCustomHeadHtml, resolveCustomHeadHtml } from './custom-head-html';
+/**
+ * SSR-friendly custom head HTML from Admin → Settings → SEO (`customHeadHtml`).
+ * Pages Router: renders through `next/head`. App Router: prefer `renderCustomHeadHtml` in root layout.
+ */
+export declare function SiteCustomHtml({ children, useNextHead, html, }: SiteCustomHtmlProps): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null;

package/dist/ui/components/SiteCustomHtml.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCustomHeadHtml = exports.renderCustomHeadHtml = void 0;
+exports.SiteCustomHtml = SiteCustomHtml;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const head_1 = __importDefault(require("next/head"));
+const SiteCatalogContext_1 = require("../context/SiteCatalogContext");
+const custom_head_html_1 = require("./custom-head-html");
+var custom_head_html_2 = require("./custom-head-html");
+Object.defineProperty(exports, "renderCustomHeadHtml", { enumerable: true, get: function () { return custom_head_html_2.renderCustomHeadHtml; } });
+Object.defineProperty(exports, "resolveCustomHeadHtml", { enumerable: true, get: function () { return custom_head_html_2.resolveCustomHeadHtml; } });
+/**
+ * SSR-friendly custom head HTML from Admin → Settings → SEO (`customHeadHtml`).
+ * Pages Router: renders through `next/head`. App Router: prefer `renderCustomHeadHtml` in root layout.
+ */
+function SiteCustomHtml({ children = null, useNextHead = true, html, }) {
+    const setting = (0, SiteCatalogContext_1.useSiteSetting)();
+    const source = html ?? (0, custom_head_html_1.resolveCustomHeadHtml)(setting);
+    const nodes = (0, custom_head_html_1.renderCustomHeadHtml)(source);
+    if (nodes.length === 0)
+        return children;
+    if (useNextHead) {
+        return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(head_1.default, { children: nodes }), children] }));
+    }
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [nodes, children] }));
+}

package/dist/ui/components/custom-head-html.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+/**
+ * Parse admin custom head HTML into React nodes for SSR (App Router `<head>` or `next/head`).
+ * Supports common head tags: script / meta / link / style / noscript.
+ */
+export declare function renderCustomHeadHtml(html: string): React.ReactNode[];
+/** Resolve custom head HTML from a setting row (flat field or `globalSetting` JSON). */
+export declare function resolveCustomHeadHtml(setting: Record<string, unknown> | null | undefined): string;

package/dist/ui/components/custom-head-html.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCustomHeadHtml = renderCustomHeadHtml;
+exports.resolveCustomHeadHtml = resolveCustomHeadHtml;
+const react_1 = __importDefault(require("react"));
+const VOID_TAGS = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+]);
+const BOOL_ATTRS = new Set([
+    'async',
+    'defer',
+    'nomodule',
+    'checked',
+    'disabled',
+    'readonly',
+    'required',
+    'selected',
+    'multiple',
+    'muted',
+    'playsinline',
+    'autofocus',
+    'autoplay',
+    'controls',
+    'loop',
+    'open',
+]);
+const ATTR_NAME_MAP = {
+    class: 'className',
+    charset: 'charSet',
+    charSet: 'charSet',
+    crossorigin: 'crossOrigin',
+    crossOrigin: 'crossOrigin',
+    httpequiv: 'httpEquiv',
+    'http-equiv': 'httpEquiv',
+    httpEquiv: 'httpEquiv',
+    for: 'htmlFor',
+    tabindex: 'tabIndex',
+    readonly: 'readOnly',
+    maxlength: 'maxLength',
+    minlength: 'minLength',
+    allowfullscreen: 'allowFullScreen',
+    nomodule: 'noModule',
+    playsinline: 'playsInline',
+};
+function toReactAttrName(name) {
+    if (ATTR_NAME_MAP[name])
+        return ATTR_NAME_MAP[name];
+    if (ATTR_NAME_MAP[name.toLowerCase()])
+        return ATTR_NAME_MAP[name.toLowerCase()];
+    if (name.startsWith('data-') || name.startsWith('aria-'))
+        return name;
+    return name;
+}
+function parseAttributes(attrSource) {
+    const attrs = {};
+    const re = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+    let match;
+    while ((match = re.exec(attrSource))) {
+        const rawName = match[1];
+        if (!rawName || rawName === '/')
+            continue;
+        const reactName = toReactAttrName(rawName);
+        const rawValue = match[2] ?? match[3] ?? match[4];
+        if (rawValue === undefined) {
+            attrs[reactName] = true;
+            continue;
+        }
+        if (BOOL_ATTRS.has(rawName.toLowerCase()) || BOOL_ATTRS.has(reactName.toLowerCase())) {
+            attrs[reactName] = rawValue === '' || rawValue.toLowerCase() === reactName.toLowerCase() || rawValue === 'true';
+            continue;
+        }
+        attrs[reactName] = rawValue;
+    }
+    return attrs;
+}
+function findClosingTag(html, tagName, fromIndex) {
+    const openRe = new RegExp(`<${tagName}\\b`, 'gi');
+    const closeRe = new RegExp(`</${tagName}\\s*>`, 'gi');
+    let depth = 1;
+    let i = fromIndex;
+    while (i < html.length && depth > 0) {
+        openRe.lastIndex = i;
+        closeRe.lastIndex = i;
+        const openMatch = openRe.exec(html);
+        const closeMatch = closeRe.exec(html);
+        if (!closeMatch)
+            return -1;
+        if (openMatch && openMatch.index < closeMatch.index) {
+            depth += 1;
+            i = openMatch.index + openMatch[0].length;
+            continue;
+        }
+        depth -= 1;
+        if (depth === 0)
+            return closeMatch.index;
+        i = closeMatch.index + closeMatch[0].length;
+    }
+    return -1;
+}
+/**
+ * Parse admin custom head HTML into React nodes for SSR (App Router `<head>` or `next/head`).
+ * Supports common head tags: script / meta / link / style / noscript.
+ */
+function renderCustomHeadHtml(html) {
+    const source = String(html || '').trim();
+    if (!source)
+        return [];
+    const nodes = [];
+    let i = 0;
+    let key = 0;
+    while (i < source.length) {
+        const nextTag = source.indexOf('<', i);
+        if (nextTag === -1)
+            break;
+        if (nextTag > i && source.slice(i, nextTag).trim()) {
+            // Ignore loose text nodes in <head>
+            i = nextTag;
+        }
+        if (source.startsWith('<!--', nextTag)) {
+            const end = source.indexOf('-->', nextTag + 4);
+            i = end === -1 ? source.length : end + 3;
+            continue;
+        }
+        const tagMatch = source
+            .slice(nextTag)
+            .match(/^<\/?([a-zA-Z][\w:-]*)((?:\s[^>]*)?)(\/?)>/);
+        if (!tagMatch) {
+            i = nextTag + 1;
+            continue;
+        }
+        const full = tagMatch[0];
+        const tagName = tagMatch[1].toLowerCase();
+        const attrSource = tagMatch[2] || '';
+        const selfClosing = Boolean(tagMatch[3]) || VOID_TAGS.has(tagName);
+        const openEnd = nextTag + full.length;
+        if (full.startsWith('</')) {
+            i = openEnd;
+            continue;
+        }
+        const attrs = parseAttributes(attrSource);
+        attrs['data-reactpress-custom-html'] = 'head';
+        if (selfClosing || VOID_TAGS.has(tagName)) {
+            nodes.push(react_1.default.createElement(tagName, { ...attrs, key: `rp-custom-head-${key++}` }));
+            i = openEnd;
+            continue;
+        }
+        const closeIndex = findClosingTag(source, tagName, openEnd);
+        if (closeIndex === -1) {
+            nodes.push(react_1.default.createElement(tagName, { ...attrs, key: `rp-custom-head-${key++}` }));
+            i = openEnd;
+            continue;
+        }
+        const inner = source.slice(openEnd, closeIndex);
+        const closeMatch = source.slice(closeIndex).match(new RegExp(`^</${tagName}\\s*>`, 'i'));
+        i = closeIndex + (closeMatch ? closeMatch[0].length : 0);
+        if (tagName === 'script' || tagName === 'style') {
+            nodes.push(react_1.default.createElement(tagName, {
+                ...attrs,
+                key: `rp-custom-head-${key++}`,
+                dangerouslySetInnerHTML: { __html: inner },
+            }));
+            continue;
+        }
+        nodes.push(react_1.default.createElement(tagName, { ...attrs, key: `rp-custom-head-${key++}` }, inner || null));
+    }
+    return nodes;
+}
+/** Resolve custom head HTML from a setting row (flat field or `globalSetting` JSON). */
+function resolveCustomHeadHtml(setting) {
+    if (!setting)
+        return '';
+    const direct = setting.customHeadHtml;
+    if (typeof direct === 'string' && direct.trim())
+        return direct;
+    const raw = setting.globalSetting;
+    let gs = null;
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        gs = raw;
+    }
+    else if (typeof raw === 'string' && raw.trim()) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                gs = parsed;
+            }
+        }
+        catch {
+            gs = null;
+        }
+    }
+    const nested = gs?.customHeadHtml;
+    return typeof nested === 'string' ? nested : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fecommunity/reactpress-toolkit",
-  "version": "4.0.0-beta.8",
+  "version": "4.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -44,6 +44,10 @@
       "types": "./dist/theme/node.d.ts",
       "default": "./dist/theme/node.js"
     },
+    "./theme/extension": {
+      "types": "./dist/theme/extension/index.d.ts",
+      "default": "./dist/theme/extension/index.js"
+    },
     "./theme/providers": {
       "types": "./dist/theme/providers/index.d.ts",
       "default": "./dist/theme/providers/index.js"
@@ -130,17 +134,35 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "reactpress",
+    "typescript",
+    "sdk",
+    "headless-cms",
     "cms",
-    "toolkit",
+    "blog",
+    "nextjs",
+    "openapi",
+    "api-client",
+    "ssr",
     "theme",
-    "headless"
+    "plugin",
+    "react",
+    "publishing-platform"
   ],
   "author": "fecommunity",
-  "license": "ISC",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://docs.gaoredu.com/",
+  "bugs": {
+    "url": "https://github.com/fecommunity/reactpress/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fecommunity/reactpress.git",
@@ -150,7 +172,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "description": "ReactPress TypeScript SDK — API clients, theme SSR, plugin hooks, headless UI",
+  "description": "Official ReactPress TypeScript SDK — OpenAPI REST clients, Next.js theme SSR, plugin hooks, and headless UI for the publishing platform",
   "dependencies": {
     "ajv": "^8.17.1",
     "axios": "^1.12.2",