@fecommunity/reactpress-toolkit 4.0.0-beta.0 → 4.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +109 -107
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,89 +1,91 @@
1
1
  # @fecommunity/reactpress-toolkit
2
2
 
3
- ReactPress 的 TypeScript 工具包：从 OpenAPI/Swagger 生成的 API 客户端、站点配置类型、Next.js 主题 SSR 辅助，以及管理后台插件注册。
3
+ TypeScript SDK for the ReactPress publishing platform — OpenAPI clients, Next.js theme SSR, plugin hooks, and headless UI components.
4
4
 
5
- ## 包导出（`package.json` → `exports`）
5
+ Use in **themes**, **plugins**, **Admin extensions**, and **custom frontends** instead of duplicating API or SSR logic.
6
6
 
7
- | 子路径 | 用途 |
7
+ ## Package exports (`package.json` → `exports`)
8
+
9
+ | Subpath | Purpose |
8
10
  |--------|------|
9
- | `.` | 根入口：`api`、`config`、`theme`、`ui`、`plugin` 命名空间及常用 re-export |
10
- | `./api` | 各资源 HTTP 客户端类 |
11
- | `./api/instance` | 默认 `api` 实例与 `createApiInstance` |
12
- | `./types` | Swagger 生成的请求/响应类型 |
13
- | `./utils` | 与业务无关的纯工具（见下方模块表） |
14
- | `./config` | 环境变量、全局默认、`i18n` 文案（`config/locales/*.json`） |
15
- | `./theme` | 访客主题：SSR 拉数、运行时、扩展配置类型，并 re-export `./ui` |
11
+ | `.` | Root entry: `api`, `config`, `theme`, `ui`, `plugin` namespaces and common re-exports |
12
+ | `./api` | HTTP client classes per resource |
13
+ | `./api/instance` | Default `api` instance and `createApiInstance` |
14
+ | `./types` | Swagger-generated request/response types |
15
+ | `./utils` | Framework-agnostic utilities (see module table below) |
16
+ | `./config` | Env vars, global defaults, `i18n` strings (`config/locales/*.json`) |
17
+ | `./theme` | Visitor themes: SSR data fetch, runtime, extension config types; re-exports `./ui` |
16
18
  | `./theme/next-config` | `createReactPressNextConfig()` |
17
- | `./theme/node` | Node 专用（如读取主题管理端 locale 文件） |
18
- | `./ui` | 无样式主题组件与 hooks |
19
- | `./plugin` | 管理端插件聚合入口 |
20
- | `./plugin/admin` | 菜单注册、权限常量 |
21
- | `./plugin/client` | Web/Electron API 客户端工厂（推荐） |
22
- | `./plugin/react` | 与 `./plugin/client` 相同（兼容旧路径） |
23
- | `./plugin/dev` | Vite 开发端口重定向等 |
19
+ | `./theme/node` | Node-only helpers (e.g. read theme admin locale files) |
20
+ | `./ui` | Unstyled theme components and hooks |
21
+ | `./plugin` | Admin plugin aggregate entry |
22
+ | `./plugin/admin` | Menu registration, permission constants |
23
+ | `./plugin/client` | Web/Electron API client factory (recommended) |
24
+ | `./plugin/react` | Same as `./plugin/client` (legacy path) |
25
+ | `./plugin/dev` | Vite dev port redirect, etc. |
24
26
 
25
- **约定：** `src/` 下仅保留与上述导出对应的一级目录；实现细节放在子目录中，根目录用薄 shim 保持对外路径稳定（例如 `theme/node.ts` → `theme/build/node.ts`）。
27
+ **Convention:** Only top-level directories under `src/` match the exports above; implementation details live in subdirectories with thin shims at the root (e.g. `theme/node.ts` → `theme/build/node.ts`).
26
28
 
27
- ## 源码结构
29
+ ## Source layout
28
30
 
29
31
  ```
30
32
  src/
31
- ├── api/ # OpenAPI 生成（勿手改业务逻辑）
32
- ├── config/ # env、global、i18n + locales/
33
- ├── types/ # Swagger 生成类型
34
- ├── utils/ # 纯函数工具（theme/plugin 共用）
33
+ ├── api/ # OpenAPI generated (do not hand-edit business logic)
34
+ ├── config/ # env, global, i18n + locales/
35
+ ├── types/ # Swagger generated types
36
+ ├── utils/ # Pure utilities (shared by theme/plugin)
35
37
  │ ├── api-envelope.ts # unpackList / unpackOne / unpackPaginated
36
38
  │ ├── cookie.ts # readRequestCookie
37
- │ ├── date.ts # formatDate、formatPublishDate*
38
- │ ├── email.ts # 评论邮箱校验
39
- │ ├── error.ts # ApiError、isApiError
39
+ │ ├── date.ts # formatDate, formatPublishDate*
40
+ │ ├── email.ts # Comment email validation
41
+ │ ├── error.ts # ApiError, isApiError
40
42
  │ ├── json.ts # safeJsonParse
41
- │ ├── jsonp.ts # 浏览器 JSONP
42
- │ ├── object.ts # deepMerge、getByPath、deepClone
43
+ │ ├── jsonp.ts # Browser JSONP
44
+ │ ├── object.ts # deepMerge, getByPath, deepClone
43
45
  │ ├── setting.ts # pickSiteSettings
44
- │ └── string.ts # stripHtml、truncateWords
46
+ │ └── string.ts # stripHtml, truncateWords
45
47
  ├── plugin/
46
- │ ├── admin/ # AdminModule、菜单注册、权限
47
- │ ├── client/ # createClient、resolveApiBaseUrl
48
- │ ├── dev/ # devPortRedirectPlugin 等
49
- │ └── react/ # 仅 re-export client（兼容）
48
+ │ ├── admin/ # AdminModule, menu registration, permissions
49
+ │ ├── client/ # createClient, resolveApiBaseUrl
50
+ │ ├── dev/ # devPortRedirectPlugin, etc.
51
+ │ └── react/ # Re-export client only (compat)
50
52
  ├── theme/
51
- │ ├── api/ # themeApi、axios 封装（JSON/解包 re-export utils）
52
- │ ├── ssr/ # fetch、static props、站点 meta
53
- │ ├── visitor/ # 语言、会话、配色、运行时 mods
54
- │ ├── content/ # SEO、导航路径、摘要、静态资源 URL
55
- │ ├── preview/ # 预览 token / mods / config 查询参数
56
- │ ├── createCatalogApp.js # 完整主题 _app 工厂（无 UI 框架依赖）
57
- │ ├── createApp.js # Next `_app` 工厂（allowJs，随 tsc 输出到 dist）
58
- │ ├── extension/ # theme.json schema、站点配置、与服务端共享的类型
53
+ │ ├── api/ # themeApi, axios wrapper
54
+ │ ├── ssr/ # fetch, static props, site meta
55
+ │ ├── visitor/ # Language, session, colors, runtime mods
56
+ │ ├── content/ # SEO, nav paths, excerpts, static asset URLs
57
+ │ ├── preview/ # Preview token / mods / config query params
58
+ │ ├── createCatalogApp.js # Full theme _app factory (no UI framework)
59
+ │ ├── createApp.js # Next `_app` factory (allowJs, emitted to dist)
60
+ │ ├── extension/ # theme.json schema, site config, shared server types
59
61
  │ ├── node.ts # → build/node
60
62
  │ ├── next-config.ts
61
- │ └── index.ts # 对外 barrel
63
+ │ └── index.ts # Public barrel
62
64
  └── ui/
63
- ├── components/ # 无样式 React 组件
64
- ├── context/ # ReactPressProvider、locale、runtime
65
- └── hooks/ # 通用 React hooks（与具体页面无关）
65
+ ├── components/ # Unstyled React components
66
+ ├── context/ # ReactPressProvider, locale, runtime
67
+ └── hooks/ # Generic React hooks
66
68
  ```
67
69
 
68
- ## 安装
70
+ ## Install
69
71
 
70
72
  ```bash
71
73
  pnpm add @fecommunity/reactpress-toolkit
72
74
  ```
73
75
 
74
- ## 快速开始
76
+ ## Quick start
75
77
 
76
- ### API 客户端
78
+ ### API client
77
79
 
78
80
  ```typescript
79
81
  import { api } from '@fecommunity/reactpress-toolkit';
80
- // 或
82
+ // or
81
83
  import { api, createApiInstance } from '@fecommunity/reactpress-toolkit/api/instance';
82
84
 
83
85
  const articles = await api.article.findAll();
84
86
  ```
85
87
 
86
- 自定义 baseURL：
88
+ Custom baseURL:
87
89
 
88
90
  ```typescript
89
91
  import { createApiInstance } from '@fecommunity/reactpress-toolkit/api/instance';
@@ -91,9 +93,9 @@ import { createApiInstance } from '@fecommunity/reactpress-toolkit/api/instance'
91
93
  const customApi = createApiInstance({ baseURL: 'https://api.example.com/api' });
92
94
  ```
93
95
 
94
- ### 通用工具（`./utils`）
96
+ ### Utilities (`./utils`)
95
97
 
96
- 与 Next/主题无关的逻辑应放在 `utils`，`theme` 仅 re-export 以保持 `@fecommunity/reactpress-toolkit/theme` 路径兼容：
98
+ Framework-agnostic logic belongs in `utils`; `theme` re-exports for `@fecommunity/reactpress-toolkit/theme` compatibility:
97
99
 
98
100
  ```typescript
99
101
  import {
@@ -107,49 +109,49 @@ import {
107
109
  } from '@fecommunity/reactpress-toolkit/utils';
108
110
  ```
109
111
 
110
- | 模块 | 典型用途 |
112
+ | Module | Typical use |
111
113
  |------|----------|
112
- | `json` | 解析 setting 里的 JSON 字符串 |
113
- | `api-envelope` | 解包 Nest `TransformInterceptor` 的 `{ data }` |
114
- | `date` | 文章发布日期展示 |
115
- | `string` | 归档摘要 HTML 剥离、截断 |
116
- | `object` | theme.json 配置合并、点路径读写 |
117
- | `setting` | 把 settings 行映射为 props |
118
- | `cookie` | SSR 读取 `Cookie` 头 |
119
- | `email` | 访客评论邮箱格式 |
114
+ | `json` | Parse JSON strings in settings |
115
+ | `api-envelope` | Unwrap Nest `TransformInterceptor` `{ data }` |
116
+ | `date` | Article publish date display |
117
+ | `string` | Strip HTML for archive excerpts, truncate |
118
+ | `object` | Merge theme.json config, dot-path read/write |
119
+ | `setting` | Map settings rows to props |
120
+ | `cookie` | Read `Cookie` header in SSR |
121
+ | `email` | Visitor comment email format |
120
122
 
121
- ### 管理后台插件
123
+ ### Admin plugins
122
124
 
123
125
  ```typescript
124
126
  import type { AdminModule } from '@fecommunity/reactpress-toolkit/plugin/admin';
125
127
  import { permissionsForRole } from '@fecommunity/reactpress-toolkit/plugin/admin';
126
128
  ```
127
129
 
128
- ### Web / Electron 客户端
130
+ ### Web / Electron client
129
131
 
130
132
  ```typescript
131
133
  import { createClient, resolveApiBaseUrl } from '@fecommunity/reactpress-toolkit/plugin/client';
132
134
  ```
133
135
 
134
- ## App 工厂（`./app`）
136
+ ## App factories (`./app`)
135
137
 
136
- 主题 `_app.tsx` 的入口工厂，与 UI 框架无关：
138
+ Entry factories for theme `_app.tsx`, UI-framework agnostic:
137
139
 
138
- | 工厂 | 用途 |
140
+ | Factory | Purpose |
139
141
  |------|------|
140
- | `createThemeApp` | 极简主题（hello-world）：`ReactPressProvider` + `ThemeCssVars` |
141
- | `createReactPressApp` | 完整主题：SSR catalog、i18n、统计、PV；通过 `wrapContent` 注入 Ant Design 等 |
142
+ | `createThemeApp` | Minimal theme (hello-world): `ReactPressProvider` + `ThemeCssVars` |
143
+ | `createReactPressApp` | Full theme: SSR catalog, i18n, analytics, PV; inject Ant Design etc. via `wrapContent` |
142
144
 
143
145
  ```typescript
144
146
  import { createThemeApp } from '@fecommunity/reactpress-toolkit/app';
145
147
  import { createReactPressApp } from '@fecommunity/reactpress-toolkit/app';
146
148
  ```
147
149
 
148
- 也可从 `./theme` re-export 导入（兼容旧路径）。
150
+ Also re-exported from `./theme` (legacy paths).
149
151
 
150
- ## 主题开发（`./theme`）
152
+ ## Theme development (`./theme`)
151
153
 
152
- Next.js 访客主题应使用 toolkit 提供的 API 与 SSR 辅助，避免在每个主题里复制 `lib/api.ts`。
154
+ Next.js visitor themes should use toolkit API and SSR helpers instead of copying `lib/api.ts` per theme.
153
155
 
154
156
  ```typescript
155
157
  import {
@@ -175,7 +177,7 @@ import themeManifest from '../theme.json';
175
177
  export default createThemeApp(themeManifest);
176
178
  ```
177
179
 
178
- **完整功能主题** — 使用 `createReactPressApp`（UI 框架无关），Ant Design 等重型依赖留在主题内：
180
+ **Full-featured themes** — use `createReactPressApp` (UI-framework agnostic); keep Ant Design and heavy deps in the theme:
179
181
 
180
182
  ```typescript
181
183
  import { createReactPressApp } from '@fecommunity/reactpress-toolkit/app';
@@ -193,9 +195,9 @@ export default createReactPressApp(themeManifest, {
193
195
  });
194
196
  ```
195
197
 
196
- `createReactPressApp` 内置：SSR 站点数据、预览 mods、SiteCatalogProvider、路由进度条、统计脚本、PV 上报。**不含** Ant Design / cssinjs。
198
+ `createReactPressApp` includes: SSR site data, preview mods, SiteCatalogProvider, route progress, analytics scripts, PV reporting. **Does not** include Ant Design / cssinjs.
197
199
 
198
- **REST Provider** — 无需在每个主题复制 14 个 Provider 文件：
200
+ **REST providers** — avoid copying 14 provider files per theme:
199
201
 
200
202
  ```typescript
201
203
  import { createThemeAxiosClient, createThemeProviders } from '@fecommunity/reactpress-toolkit/theme';
@@ -204,68 +206,68 @@ export const httpProvider = createThemeAxiosClient({ onError, onUnauthorized });
204
206
  export const { ArticleProvider, CategoryProvider, TagProvider } = createThemeProviders(httpProvider);
205
207
  ```
206
208
 
207
- 环境变量：`REACTPRESS_API_URL`（SSR）、`NEXT_PUBLIC_REACTPRESS_API_URL`（浏览器），由 `reactpress theme dev` 注入。
209
+ Env: `REACTPRESS_API_URL` (SSR), `NEXT_PUBLIC_REACTPRESS_API_URL` (browser), injected by `reactpress theme dev`.
208
210
 
209
- ### 无样式 UI（`./ui`）
211
+ ### Headless UI (`./ui`)
210
212
 
211
- 也可从 `./theme` 一并导入：
213
+ Also importable from `./theme`:
212
214
 
213
215
  ```typescript
214
216
  import { NavMenu, ArticleList, ReactPressProvider, useLocale } from '@fecommunity/reactpress-toolkit/ui';
215
217
  ```
216
218
 
217
- | 符号 | 说明 |
219
+ | Symbol | Description |
218
220
  |------|------|
219
- | `ReactPressProvider` | 在 `_app` 注入站点上下文 |
220
- | `useLocale` / `useThemeRuntime` / `useThemeMod` | 语言与主题 mods |
221
- | `useToggle` / `useAsyncLoading` | 布尔切换、防抖 loading（评论/搜索等） |
222
- | `usePagination` | `[items, total]` 分页列表 |
223
- | `useReportArticleView` / `useReportPageView` | 文章阅读数、全站 PV 上报 |
224
- | `useRouteParam` / `useNavActive` | 动态路由参数、导航高亮 |
225
- | `useWarningOnExit` | 离开页面前确认（Next Router） |
226
- | `NavMenu` | 配置驱动导航，通过 `renderLink` 接 Next `Link` |
227
- | `ArticleList` | 列表渲染，通过 `renderArticle` 自定义卡片 |
228
- | `SiteCatalogProvider` / `useSiteSetting` / `useSiteUser` | 全站 catalog + 用户会话 |
229
- | `SiteSeo` / `RouteProgress` / `SiteAnalytics` | SEO meta、路由进度条、GA/百度统计 |
230
- | `ArticleReader` / `HtmlContent` / `ArticleToc` | 文章阅读、HTML 渲染、目录 |
231
- | `ImageViewer` / `LocaleTime` | 图片预览、本地化时间 |
232
- | `createReactPressApp` | 完整主题 `_app` 工厂（`@fecommunity/reactpress-toolkit/app`） |
233
- | `fetchAppBootstrap` | `_app.getInitialProps` SSR 数据（setting / taxonomy / preview） |
234
-
235
- ### 扩展配置类型
236
-
237
- `theme/extension` 中的类型与校验逻辑与 **server**、**web 外观设置** 共用，例如 `ThemeConfigurationSchema`、`resolveSiteConfig`、`PUBLIC_SETTING_KEYS`。服务端可：
221
+ | `ReactPressProvider` | Inject site context in `_app` |
222
+ | `useLocale` / `useThemeRuntime` / `useThemeMod` | Language and theme mods |
223
+ | `useToggle` / `useAsyncLoading` | Boolean toggle, debounced loading |
224
+ | `usePagination` | `[items, total]` paginated lists |
225
+ | `useReportArticleView` / `useReportPageView` | Article views, site PV |
226
+ | `useRouteParam` / `useNavActive` | Dynamic route params, nav highlight |
227
+ | `useWarningOnExit` | Confirm before leaving page (Next Router) |
228
+ | `NavMenu` | Config-driven nav via `renderLink` + Next `Link` |
229
+ | `ArticleList` | List renderer via `renderArticle` |
230
+ | `SiteCatalogProvider` / `useSiteSetting` / `useSiteUser` | Site catalog + user session |
231
+ | `SiteSeo` / `RouteProgress` / `SiteAnalytics` | SEO meta, progress bar, GA/Baidu |
232
+ | `ArticleReader` / `HtmlContent` / `ArticleToc` | Article reading, HTML, TOC |
233
+ | `ImageViewer` / `LocaleTime` | Image preview, localized time |
234
+ | `createReactPressApp` | Full theme `_app` factory |
235
+ | `fetchAppBootstrap` | `_app.getInitialProps` SSR data |
236
+
237
+ ### Extension config types
238
+
239
+ Types and validation in `theme/extension` are shared with **server** and **web appearance settings**, e.g. `ThemeConfigurationSchema`, `resolveSiteConfig`, `PUBLIC_SETTING_KEYS`. Server example:
238
240
 
239
241
  ```typescript
240
242
  import { PUBLIC_SETTING_KEYS, systemGlobalSettingDefaults } from '@fecommunity/reactpress-toolkit/theme';
241
243
  import { readThemeAdminLocaleFile } from '@fecommunity/reactpress-toolkit/theme/node';
242
244
  ```
243
245
 
244
- ## 从 Swagger 重新生成 API
246
+ ## Regenerate API from Swagger
245
247
 
246
- 在 monorepo 根目录确保 server 可构建后：
248
+ From monorepo root, ensure server builds:
247
249
 
248
250
  ```bash
249
251
  cd toolkit && pnpm run generate
250
252
  ```
251
253
 
252
- 将更新 `src/api/*` 与 `src/types/*`。
254
+ Updates `src/api/*` and `src/types/*`.
253
255
 
254
- ## 构建
256
+ ## Build
255
257
 
256
258
  ```bash
257
259
  cd toolkit && pnpm run build
258
260
  ```
259
261
 
260
- 输出到 `dist/`；`createApp.js` 随 `tsc`（`allowJs`）写入 `dist/theme/createApp.js`。
262
+ Output in `dist/`; `createApp.js` is emitted via `tsc` (`allowJs`) to `dist/theme/createApp.js`.
261
263
 
262
- ## 开发脚本
264
+ ## Scripts
263
265
 
264
- | 命令 | 说明 |
266
+ | Command | Description |
265
267
  |------|------|
266
- | `pnpm run generate` | 从 server Swagger 生成 API |
267
- | `pnpm run build` | `tsc` + 复制 locales |
268
- | `pnpm run typecheck` | 仅类型检查 |
268
+ | `pnpm run generate` | Generate API from server Swagger |
269
+ | `pnpm run build` | `tsc` + copy locales |
270
+ | `pnpm run typecheck` | Type check only |
269
271
 
270
272
  ## License
271
273
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fecommunity/reactpress-toolkit",
3
- "version": "4.0.0-beta.0",
3
+ "version": "4.0.0-beta.10",
4
4
  "main": "dist/index.js",
5
5
  "types": "dist/index.d.ts",
6
6
  "exports": {
@@ -150,7 +150,7 @@
150
150
  "access": "public",
151
151
  "registry": "https://registry.npmjs.org/"
152
152
  },
153
- "description": "ReactPress TypeScript toolkit: OpenAPI clients, theme SSR helpers, headless UI, and admin plugin registry.",
153
+ "description": "ReactPress TypeScript SDK — API clients, theme SSR, plugin hooks, headless UI",
154
154
  "dependencies": {
155
155
  "ajv": "^8.17.1",
156
156
  "axios": "^1.12.2",