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

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