@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.20

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 (44) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +9 -0
  3. package/README.md +48 -2
  4. package/package.json +141 -4
  5. package/src/action-designer.ts +250 -0
  6. package/src/attachment-url.ts +195 -0
  7. package/src/auth/index.ts +6 -0
  8. package/src/auth/qrcode.ts +519 -0
  9. package/src/auth/types.ts +261 -0
  10. package/src/display-style.ts +250 -0
  11. package/src/editor-frame.ts +623 -0
  12. package/src/editor-session.ts +1214 -0
  13. package/src/editor-testing.ts +838 -0
  14. package/src/editor.ts +1641 -0
  15. package/src/frame-transport.ts +491 -0
  16. package/src/frontend-routes.ts +99 -0
  17. package/src/hooks.ts +48 -0
  18. package/src/host-caps.ts +93 -0
  19. package/src/i18n.ts +238 -0
  20. package/src/im-panel.ts +132 -0
  21. package/src/image-tools.ts +91 -0
  22. package/src/index.ts +118 -0
  23. package/src/interactive-session.ts +94 -0
  24. package/src/nahida-im.ts +391 -0
  25. package/src/nahida-ws.ts +23 -0
  26. package/src/org-directory.ts +78 -0
  27. package/src/oz-realtime.ts +144 -0
  28. package/src/page.ts +404 -0
  29. package/src/print.ts +393 -0
  30. package/src/surface.ts +281 -0
  31. package/src/theme-mocks.ts +140 -0
  32. package/src/theme.ts +125 -0
  33. package/src/ui-fixtures/confirm.ts +16 -0
  34. package/src/ui-fixtures/entity-picker.ts +24 -0
  35. package/src/ui-fixtures/expression-editor.ts +52 -0
  36. package/src/ui-fixtures/image-cropper.ts +23 -0
  37. package/src/ui-fixtures/index.ts +16 -0
  38. package/src/ui-fixtures/org-tri-picker.ts +19 -0
  39. package/src/ui-fixtures/prompt.ts +19 -0
  40. package/src/ui-fixtures/record-picker.ts +17 -0
  41. package/src/ui-fixtures/template-picker.ts +13 -0
  42. package/src/ui-mocks.ts +250 -0
  43. package/src/ui.ts +479 -0
  44. package/src/workflow-designer.ts +475 -0
@@ -0,0 +1,261 @@
1
+ // 登录页插件(page 类,slot auth.login)前端契约(定稿)。
2
+ // 覆盖:LoginPageProps / LoginMethod、AuthLoginHostBridge、各 kind 的 UI 义务与错误码词表;
3
+ // 使用说明见 SDK 第三方指南 docs/third-party/auth-and-hooks.md。
4
+ //
5
+ // 四者分工(务必牢记,决定本文件的类型边界):
6
+ // 登录页插件 ←(本文件 AuthLoginHostBridge,前端契约)→ 宿主 ←(auth.proto,后端契约)→ auth 插件
7
+ // 登录页插件与 auth 插件互不相识,唯一共享的知识是 6 个 kind 的交互形态词表(AuthKind)。
8
+ //
9
+ // 红线(写进类型注释供插件作者随手可见):
10
+ // 不持凭证 / 不知协议(providerCode 只能挑图标文案,禁止 if (providerCode==='dingtalk') 特殊协议逻辑)/
11
+ // 不调第三方 / 不建会话 / 不接触敏感配置(只拿得到 publicConfig 的 x-public 子集)。
12
+
13
+ import type { HostI18n } from '../i18n';
14
+ import type { SurfaceCreateInput, SurfaceMountResult } from '../surface';
15
+ import { definePluginSurface } from '../surface';
16
+
17
+ /** 登录交互形态词表(六 kind)。宿主按 methods[].kind 分组渲染,插件按 kind 画对应 UI。 */
18
+ export type AuthKind = 'password' | 'redirect' | 'qr' | 'otp' | 'challenge' | 'passkey';
19
+
20
+ /**
21
+ * 登录方式目录条目。
22
+ * 宿主已完成「插件声明的 supported_auth_kinds ∩ 实例启用的认证源」交集与敏感字段过滤,
23
+ * 插件拿到的即是可直接渲染的公开子集。
24
+ */
25
+ export interface LoginMethod {
26
+ /** 认证源实例 ID —— bridge 各方法的 methodId/qrSessionId 之外的入参就是它。 */
27
+ id: string;
28
+ kind: AuthKind;
29
+ /** 'google' | 'oidc' | 'dingtalk' | ... 仅用于选内置图标/默认文案,禁止据此写协议分支逻辑。 */
30
+ providerCode?: string;
31
+ /** 已按当前 locale 解析好的展示名。 */
32
+ displayName: string;
33
+ logo?: string;
34
+ description?: string;
35
+ /** config 的 x-public 字段子集,只用于样式/品牌展示,不含 client_id/secret 等敏感字段。 */
36
+ publicConfig?: Record<string, unknown>;
37
+ }
38
+
39
+ /** 登录页顶层数据输入,由宿主经 SurfaceCreateInput.props 注入。 */
40
+ export interface LoginPageProps {
41
+ /** 登录方式目录;为空数组时插件需展示"暂无可用登录方式,请联系管理员",不得白屏。 */
42
+ methods: LoginMethod[];
43
+ /** 初始是否需要验证码;运行中还会由 AUTH_NEED_CAPTCHA 错误码动态触发。 */
44
+ captcha: { required: boolean };
45
+ /** 改密续步表单的即时强度提示(三期后有);仅 UX 提示,权威校验永远在宿主。 */
46
+ passwordRuleHint?: {
47
+ minLength?: number;
48
+ requireClasses?: number;
49
+ };
50
+ /** 品牌公开配置(来自认证源/实例配置的 x-public 子集);缺省插件应有默认视觉,不得硬编码品牌资产。 */
51
+ brand?: {
52
+ logo?: string;
53
+ background?: string;
54
+ slogan?: string;
55
+ };
56
+ /**
57
+ * 当前登录页插件自身配置中标记为公开的字段(login-bootstrap 的 login_page.public_config 原样透传),
58
+ * 含义由登录页插件自己解释(如样式、标语);宿主不认识其中的枚举值。缺省或空对象时插件按默认外观渲染。
59
+ */
60
+ pageConfig?: Record<string, unknown>;
61
+ /**
62
+ * 宿主记住的登录名(安全设置「登录行为策略」的记住用户名开关开、且本浏览器记住过时才下发)。
63
+ * 插件只用它预填用户名输入框(用户已输入时不覆盖),不得自行写本地存储:登录名在 login()
64
+ * 凭证校验通过后由宿主保存,开关关闭时由宿主清除。缺省表示不预填。
65
+ */
66
+ rememberedUsername?: string;
67
+ }
68
+
69
+ /**
70
+ * login()/verifyOtp()/answerChallenge() 的统一返回结构。
71
+ * ok:true → 宿主已建会话,插件调 redirectFromLogin() 进系统。
72
+ * ok:false → errorCode 按 AUTH_ERROR_CODES 词表映射 UI 行为。
73
+ * challenge 存在时 → 既不算失败也不算成功,切换到对应续步 UI。
74
+ */
75
+ export interface LoginOutcome {
76
+ ok: boolean;
77
+ errorCode?: AuthErrorCode | (string & {});
78
+ challenge?: {
79
+ type: string;
80
+ challengeToken: string;
81
+ };
82
+ }
83
+
84
+ /**
85
+ * 登录页能收到的宿主错误码词表(login() / verifyOtp() / answerChallenge() 等的 errorCode,与宿主登录接口
86
+ * 对外返回的码一致;v1.1.0-tp.19 按宿主实际对外码核定)。
87
+ * 用 const + 联合类型(而非纯 enum)落地:既给插件作者类型安全的枚举提示,
88
+ * 又保留 `(string & {})` 兜底位——宿主未来新增错误码时插件不会因联合类型收窄而编译失败,
89
+ * 只是失去该新 code 的类型提示,运行时仍走"未知 code → 通用失败文案 + log('warn', ...)"分支。
90
+ *
91
+ * 注意:认证插件后端(Authenticate 等)返回给宿主的是 proto 冻结的标准码闭集(如 AUTH_ACCOUNT_DISABLED、
92
+ * AUTH_USER_NOT_FOUND),宿主会翻译后再交给登录页(停用 → AUTH_USER_DISABLED,用户不存在 → 并入
93
+ * AUTH_INVALID_CREDENTIALS),所以那几个插件侧码不在本词表里。
94
+ */
95
+ export const AUTH_ERROR_CODES = [
96
+ /** 凭证错误(密码错 / 验证码错或过期);宿主已合并"用户不存在"防枚举,UI 不做区分。 */
97
+ 'AUTH_INVALID_CREDENTIALS',
98
+ /** 账户被停用(本地停用,或认证插件报告上游停用)。 */
99
+ 'AUTH_USER_DISABLED',
100
+ /** kimpo 登录行为策略锁定(失败次数过多,临时锁定)。 */
101
+ 'AUTH_ACCOUNT_LOCKED',
102
+ /** 账户在企业目录等上游被锁定,需与 AUTH_ACCOUNT_LOCKED 可区分展示。 */
103
+ 'AUTH_ACCOUNT_LOCKED_UPSTREAM',
104
+ /** 密码已在上游过期:引导去认证源改密。 */
105
+ 'AUTH_PASSWORD_EXPIRED',
106
+ /** 上游要求先改密、宿主无法代改:引导去认证源改密(可改密的场景走 challenge 续步)。 */
107
+ 'AUTH_MUST_CHANGE_PASSWORD',
108
+ /** 需要验证码:显示 captcha 区并自动 refreshCaptcha()。 */
109
+ 'AUTH_NEED_CAPTCHA',
110
+ /** 验证码错误:提示 + 自动刷新验证码。 */
111
+ 'AUTH_CAPTCHA_INVALID',
112
+ /** 续步令牌(challengeToken)无效或已过期:回到第一步重新登录。 */
113
+ 'AUTH_CHALLENGE_INVALID',
114
+ /** 改密续步:新密码不满足复杂度要求。 */
115
+ 'AUTH_PASSWORD_COMPLEXITY',
116
+ /** 改密续步:新密码与当前或近期密码相同。 */
117
+ 'AUTH_PASSWORD_HISTORY',
118
+ /** 改密续步:该账户密码由外部系统管理,宿主不能改。 */
119
+ 'AUTH_PASSWORD_CHANGE_UNSUPPORTED',
120
+ /** 上游不可达(LDAP 连不上 / IdP 超时 / 网络错)。 */
121
+ 'AUTH_UPSTREAM_UNAVAILABLE',
122
+ /** 外部身份无预建账户且首次登录建号关闭。 */
123
+ 'AUTH_NO_ACCOUNT_JIT_DISABLED',
124
+ /** state 校验失败:提示登录会话已失效,重新发起。 */
125
+ 'AUTH_STATE_MISMATCH',
126
+ /** 登录方式不存在或未启用(methodId 失效):刷新登录方式目录。 */
127
+ 'AUTH_METHOD_NOT_FOUND',
128
+ /** 该登录方式不支持所请求的交互形态(如对 redirect 方式调 login())。 */
129
+ 'AUTH_METHOD_KIND_UNSUPPORTED',
130
+ /** 二维码会话不存在或已过期:qr 状态机进 expired,重新取码。 */
131
+ 'AUTH_QR_SESSION_NOT_FOUND',
132
+ /** 验证码登录未启用。 */
133
+ 'AUTH_OTP_NOT_ENABLED',
134
+ /** 验证码短信发送失败:稍后重试。 */
135
+ 'AUTH_OTP_SMS_FAILED',
136
+ /** 限频:提示操作过于频繁(发码限频也归到这个码,见 sendOtp 的 retryAfter)。 */
137
+ 'AUTH_RATE_LIMITED',
138
+ /** 登录前钩子(auth.before_login)拒绝本次登录:只给通用文案,插件原因不回前端。 */
139
+ 'AUTH_LOGIN_HOOK_REJECTED',
140
+ /** 本机授权尚未激活。 */
141
+ 'AUTH_LICENSE_NOT_ACTIVATED',
142
+ /** 授权进入最终宽限期,仅系统管理员可登录。 */
143
+ 'AUTH_LICENSE_FINAL_GRACE_ADMIN_ONLY',
144
+ /** 授权状态异常,禁止登录。 */
145
+ 'AUTH_LICENSE_LOGIN_BLOCKED',
146
+ /** 在线用户数已达授权上限。 */
147
+ 'AUTH_LICENSE_SEAT_FULL',
148
+ /** 授权校验服务暂不可达:稍后重试。 */
149
+ 'AUTH_LICENSE_ARBITER_UNAVAILABLE'
150
+ ] as const;
151
+
152
+ /** AUTH_ERROR_CODES 的类型投影,供 LoginOutcome.errorCode 等字段做类型安全消费。 */
153
+ export type AuthErrorCode = (typeof AUTH_ERROR_CODES)[number];
154
+
155
+ /**
156
+ * AuthLoginHostBridge —— 宿主注入给登录页插件的能力面(冻结契约)。
157
+ * 由宿主实现并经 SurfaceCreateInput.hostBridge 注入;所有方法保证真实可执行,
158
+ * 不存在"想象中的端点"。插件不得自行拼接 URL 绕过 bridge 直接发请求( 红线③)。
159
+ */
160
+ export interface AuthLoginHostBridge {
161
+ // —— password kind ——
162
+ /** 提交账密登录;密码只在此调用瞬间经桥传给宿主,不落任何本地存储( 红线①)。 */
163
+ login(input: {
164
+ loginName: string;
165
+ password: string;
166
+ captchaId?: string;
167
+ captchaCode?: string;
168
+ /**
169
+ * 所选登录方式目录条目 id(宿主本地为 `local`)。只有一种 password 方式时可省略;
170
+ * 多种时由用户选择后传入,宿主按它定向认证并校验其可用。
171
+ */
172
+ methodId?: string;
173
+ }): Promise<LoginOutcome>;
174
+
175
+ // —— redirect kind ——
176
+ /**
177
+ * 发起 SSO 跳转;宿主拉取 login_url 后整页跳转。
178
+ * 正常情况下本 Promise 不会 resolve(页面已离开);失败(上游不可用等)时 reject,errorCode 见 AUTH_ERROR_CODES。
179
+ */
180
+ startRedirect(methodId: string): Promise<void>;
181
+
182
+ // —— qr kind ——
183
+ /** 创建二维码会话;返回 embedUrl 则渲染 iframe,返回 qrContent 则用 SDK QrCodeRenderer 自绘(二选一)。 */
184
+ createQr(methodId: string): Promise<{
185
+ qrSessionId: string;
186
+ /** 与 embedUrl 二选一:自渲染内容,交给 QrCodeRenderer。 */
187
+ qrContent?: string;
188
+ /** 二选一:第三方官方 iframe 地址。 */
189
+ embedUrl?: string;
190
+ /** 二维码有效期,单位秒。 */
191
+ expiresIn: number;
192
+ }>;
193
+ /** 轮询二维码状态;loggedIn:true 表示宿主已在本响应种下会话 cookie。 */
194
+ pollQr(qrSessionId: string): Promise<{
195
+ status: 'pending' | 'scanned' | 'confirmed' | 'expired';
196
+ loggedIn: boolean;
197
+ }>;
198
+
199
+ // —— otp kind(契约已定,实现推后至五期)——
200
+ sendOtp(methodId: string, identifier: string): Promise<{ retryAfter: number }>;
201
+ verifyOtp(methodId: string, identifier: string, code: string): Promise<LoginOutcome>;
202
+
203
+ // —— challenge 续步——
204
+ answerChallenge(input: {
205
+ challengeToken: string;
206
+ /** 首个 challenge 类型;MFA 等类型五期扩展,未识别类型插件应提示"当前登录页版本不支持"。 */
207
+ type: 'password_change';
208
+ newPassword?: string;
209
+ oldPassword?: string;
210
+ }): Promise<LoginOutcome>;
211
+
212
+ // —— 辅助 ——
213
+ refreshCaptcha(): Promise<{ captchaId: string; imageBase64: string }>;
214
+ /** 登录完成后由插件调用(或宿主在 loggedIn 后自动调,实施后校准)进入系统。 */
215
+ redirectFromLogin(): void;
216
+ message: {
217
+ success(m: string): void;
218
+ error(m: string): void;
219
+ info(m: string): void;
220
+ };
221
+ /** 复用现有宿主 i18n 能力,不自建语言探测。 */
222
+ i18n: HostI18n;
223
+ /**
224
+ * 日志上报进宿主日志中心;宿主 bridge 层做脱敏兜底,但插件自身必须先保证:
225
+ * 日志参数里永不出现密码、captcha 答案、challengeToken 原文。
226
+ */
227
+ log(level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
228
+ }
229
+
230
+ /**
231
+ * 登录页 surface 的强类型 createSurface 输入。
232
+ * 与通用 SurfaceCreateInput(surface.ts)结构一致,仅将 props/hostBridge 收窄为
233
+ * LoginPageProps/AuthLoginHostBridge 具体类型,供 definePluginLoginSurface 做类型推导。
234
+ * 登录页 surface 在 manifest 里声明为 `{ type: "page-slot", slot: "auth.login" }`,
235
+ * 故 surfaceType 固定为 'page-slot'(SurfaceType 中的 'login-form' 是未启用的历史取值,登录页插件不使用该类型)。
236
+ */
237
+ export interface LoginSurfaceCreateInput extends Omit<SurfaceCreateInput, 'props' | 'hostBridge' | 'surfaceType'> {
238
+ surfaceType: 'page-slot';
239
+ props: LoginPageProps;
240
+ hostBridge: AuthLoginHostBridge;
241
+ }
242
+
243
+ /**
244
+ * definePluginLoginSurface —— 登录页版的 definePluginSurface:给插件作者收敛 createSurface 到登录页类型
245
+ * (props/hostBridge 强类型化),返回值签名与宿主实际调用的 `(input: SurfaceCreateInput) => SurfaceMountResult`
246
+ * 保持一致。同源档里只做类型收窄;在宿主沙箱框架里(第三方插件恒为沙箱档)经 definePluginSurface 登记工厂并
247
+ * 启动框架运行时——否则 bundle 不会响应宿主握手,登录页约 15 秒后被判加载失败。
248
+ * 沙箱档下 hostBridge 的方法一律返回 Promise(`redirectFromLogin()`、`message.success()` 等也一样),请 await。
249
+ *
250
+ * @example
251
+ * ```ts
252
+ * export const createSurface = definePluginLoginSurface((input) => {
253
+ * return { component: LoginPage, props: input.props };
254
+ * });
255
+ * ```
256
+ */
257
+ export function definePluginLoginSurface(
258
+ factory: (input: LoginSurfaceCreateInput) => SurfaceMountResult
259
+ ): (input: SurfaceCreateInput) => SurfaceMountResult {
260
+ return definePluginSurface((input: SurfaceCreateInput): SurfaceMountResult => factory(input as unknown as LoginSurfaceCreateInput));
261
+ }
@@ -0,0 +1,250 @@
1
+ // 字段展示样式格式化:把字段值按设计态配置的展示样式码(display_style,权威目录在宿主后端)
2
+ // 转成展示文本。
3
+ //
4
+ // 定位:纯函数、零依赖、不读宿主状态、不做时区换算。供「不持有表格编辑器格式化引擎」的消费方复用——
5
+ // 例如模板历史记录列表的两侧实现(历史记录页插件与宿主内置回退视图),避免两份各写各的。
6
+ //
7
+ // 口径:逐档对齐表格编辑器的填报态单元格格式化。表格编辑器保留自有引擎(Excel 格式码全量实现),
8
+ // 两侧一致性由对拍测试钉住:任一侧改口径,对拍测试必须失败;新增样式码须两侧同步并补对拍矩阵。
9
+ //
10
+ // 与表格编辑器的刻意差异(均只扩展、不改变表格编辑器能处理的输入的结果):
11
+ // - 日期直接取字符串里的年月日时分秒分量,不经 Date 对象——浏览器所在时区若有夏令时空档,
12
+ // 经 Date 会把墙钟时刻平移一小时;业务日期字段是墙钟语义。
13
+ // - 额外接受带毫秒与时区后缀(Z / ±hh:mm)的 ISO 串,按字面墙钟分量取数、不做换算
14
+ // (与候选值格式化同一口径)。
15
+ // - 不接受 Excel 序列数与纯时间串(表格编辑器单元格存储形态,记录接口不会下发),返回 null 交调用方回退。
16
+
17
+ /** 日期时间大类(目录大类「4」)叶子码。 */
18
+ const DATE_TIME_DISPLAY_STYLES = new Set<string>([
19
+ '401', '402', '403', '421', '404', '422', '405', '423', '412',
20
+ '406', '424', '407', '425', '408', '426', '413', '427', '414', '428', '415', '429',
21
+ '409', '430', '410', '431', '411', '432',
22
+ '416', '417', '418', '419',
23
+ ]);
24
+
25
+ /** 数值样式渲染参数:小数位 / 千分位 / 前缀(货币符号)/ 是否百分比(值 ×100 加 %)。 */
26
+ interface NumericDisplayStyleSpec {
27
+ decimals: number;
28
+ thousand: boolean;
29
+ prefix: string;
30
+ percent: boolean;
31
+ }
32
+
33
+ /**
34
+ * 数值大类(目录大类「3」)叶子码 → 渲染参数。与表格编辑器数值样式映射的
35
+ * 单元格格式码逐档对应:301 `0` / 302 `0.00` / 304 `0.00%` / 308 `#,##0.00` / 306 `¥#,##0.00` / 307 `$#,##0.00`。
36
+ */
37
+ const NUMERIC_DISPLAY_STYLE_SPECS: Record<string, NumericDisplayStyleSpec> = {
38
+ '301': { decimals: 0, thousand: false, prefix: '', percent: false },
39
+ '302': { decimals: 2, thousand: false, prefix: '', percent: false },
40
+ '304': { decimals: 2, thousand: false, prefix: '', percent: true },
41
+ '308': { decimals: 2, thousand: true, prefix: '', percent: false },
42
+ '306': { decimals: 2, thousand: true, prefix: '¥', percent: false },
43
+ '307': { decimals: 2, thousand: true, prefix: '$', percent: false },
44
+ };
45
+
46
+ /** 展示样式码是否属于日期时间大类。 */
47
+ export function isDateTimeDisplayStyle(displayStyle: string | null | undefined): boolean {
48
+ return !!displayStyle && DATE_TIME_DISPLAY_STYLES.has(displayStyle);
49
+ }
50
+
51
+ /** 展示样式码是否属于数值大类。 */
52
+ export function isNumericDisplayStyle(displayStyle: string | null | undefined): boolean {
53
+ return !!displayStyle && Object.prototype.hasOwnProperty.call(NUMERIC_DISPLAY_STYLE_SPECS, displayStyle);
54
+ }
55
+
56
+ /**
57
+ * 按展示样式码把字段值格式化为展示文本。
58
+ *
59
+ * 返回 null 表示「该样式没有格式化规则」(文本/图片/附件大类、未知码、空码)或「值解析不了」,
60
+ * 调用方应回退到自己原有的显示方式,不要把 null 当空文本呈现。
61
+ */
62
+ export function formatDisplayStyleValue(value: unknown, displayStyle: string | null | undefined): string | null {
63
+ if (value === null || value === undefined || value === '') return null;
64
+ if (!displayStyle) return null;
65
+ if (DATE_TIME_DISPLAY_STYLES.has(displayStyle)) {
66
+ const parts = parseWallClockParts(value);
67
+ return parts ? formatDateTimeParts(displayStyle, parts) : null;
68
+ }
69
+ const spec = NUMERIC_DISPLAY_STYLE_SPECS[displayStyle];
70
+ if (spec) {
71
+ const numeric = coerceNumber(value);
72
+ return numeric === null ? null : formatNumber(numeric, spec);
73
+ }
74
+ return null;
75
+ }
76
+
77
+ // ── 数值 ────────────────────────────────────────────────────────────────────
78
+
79
+ /** 数值识别:有限数,或纯数字串(与表格编辑器的数值识别同一正则;千分位串 `1,234` 不认)。 */
80
+ function coerceNumber(value: unknown): number | null {
81
+ if (typeof value === 'number') return Number.isFinite(value) ? value : null;
82
+ if (typeof value !== 'string') return null;
83
+ const trimmed = value.trim();
84
+ if (!/^-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(trimmed)) return null;
85
+ const n = Number(trimmed);
86
+ return Number.isFinite(n) ? n : null;
87
+ }
88
+
89
+ /** 负号置于货币符号之前(`-¥1,234.50`),与表格编辑器一致;舍入沿用 toFixed(与表格编辑器同源)。 */
90
+ function formatNumber(value: number, spec: NumericDisplayStyleSpec): string {
91
+ const scaled = spec.percent ? value * 100 : value;
92
+ const body = renderFixedNumber(Math.abs(scaled), spec.decimals, spec.thousand);
93
+ const sign = value < 0 ? '-' : '';
94
+ return `${sign}${spec.prefix}${body}${spec.percent ? '%' : ''}`;
95
+ }
96
+
97
+ function renderFixedNumber(value: number, decimals: number, thousand: boolean): string {
98
+ if (!Number.isFinite(value)) return String(value);
99
+ const fixed = value.toFixed(decimals);
100
+ if (!thousand) return fixed;
101
+ const [intPart, decPart] = fixed.split('.');
102
+ const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
103
+ return decPart ? `${grouped}.${decPart}` : grouped;
104
+ }
105
+
106
+ // ── 日期时间 ────────────────────────────────────────────────────────────────
107
+
108
+ interface WallClockParts {
109
+ year: number;
110
+ month: number;
111
+ day: number;
112
+ hour: number;
113
+ minute: number;
114
+ second: number;
115
+ }
116
+
117
+ /**
118
+ * 解析 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm`、`YYYY-MM-DD HH:mm:ss`(分隔符可为空格或 T),
119
+ * 可带毫秒与时区后缀(后缀只丢弃、不换算)。分量越界返回 null。
120
+ */
121
+ function parseWallClockParts(value: unknown): WallClockParts | null {
122
+ if (typeof value !== 'string') return null;
123
+ const match = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/.exec(value.trim());
124
+ if (!match) return null;
125
+ const parts: WallClockParts = {
126
+ year: Number(match[1]),
127
+ month: Number(match[2]),
128
+ day: Number(match[3]),
129
+ hour: Number(match[4] ?? 0),
130
+ minute: Number(match[5] ?? 0),
131
+ second: Number(match[6] ?? 0),
132
+ };
133
+ if (parts.month < 1 || parts.month > 12 || parts.day < 1 || parts.day > 31) return null;
134
+ if (parts.hour > 23 || parts.minute > 59 || parts.second > 59) return null;
135
+ return parts;
136
+ }
137
+
138
+ function pad2(value: number): string {
139
+ return String(value).padStart(2, '0');
140
+ }
141
+
142
+ /**
143
+ * 叶子码 → 文本,逐档对齐表格编辑器的主表字段样式预览:小时不补零、分秒补零。
144
+ * 中文纪年档(402/405/408/411… 等)是目录固定的数据格式,四语言一致,故直接写字面量。
145
+ */
146
+ function formatDateTimeParts(displayStyle: string, parts: WallClockParts): string | null {
147
+ const { year, month, day, hour } = parts;
148
+ const minute = pad2(parts.minute);
149
+ const second = pad2(parts.second);
150
+ const mm = pad2(month);
151
+ const dd = pad2(day);
152
+ switch (displayStyle) {
153
+ case '401': return `${year}`;
154
+ case '402': return `${year}年`;
155
+ case '403': return `${year}-${month}`;
156
+ case '421': return `${year}-${mm}`;
157
+ case '404': return `${year}/${month}`;
158
+ case '422': return `${year}/${mm}`;
159
+ case '405': return `${year}年${month}月`;
160
+ case '423': return `${year}年${mm}月`;
161
+ case '412': return `${month}月`;
162
+ case '406': return `${year}-${month}-${day}`;
163
+ case '424': return `${year}-${mm}-${dd}`;
164
+ case '407': return `${year}/${month}/${day}`;
165
+ case '425': return `${year}/${mm}/${dd}`;
166
+ case '408': return `${year}年${month}月${day}日`;
167
+ case '426': return `${year}年${mm}月${dd}日`;
168
+ case '413': return `${month}-${day}`;
169
+ case '427': return `${mm}-${dd}`;
170
+ case '414': return `${month}/${day}`;
171
+ case '428': return `${mm}/${dd}`;
172
+ case '415': return `${month}月${day}日`;
173
+ case '429': return `${mm}月${dd}日`;
174
+ case '409': return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
175
+ case '430': return `${year}-${mm}-${dd} ${hour}:${minute}:${second}`;
176
+ case '410': return `${year}/${month}/${day} ${hour}:${minute}:${second}`;
177
+ case '431': return `${year}/${mm}/${dd} ${hour}:${minute}:${second}`;
178
+ case '411': return `${year}年${month}月${day}日 ${hour}时${minute}分${second}秒`;
179
+ case '432': return `${year}年${mm}月${dd}日 ${hour}时${minute}分${second}秒`;
180
+ case '416': return `${hour}:${minute}`;
181
+ case '417': return `${hour}时${minute}分`;
182
+ case '418': return `${hour}:${minute}:${second}`;
183
+ case '419': return `${hour}时${minute}分${second}秒`;
184
+ default: return null;
185
+ }
186
+ }
187
+
188
+ // ── 分组桶标签 ─────────────────────────────────────────────────────────────
189
+
190
+ /** 分组桶:日期桶(按年/月/日截断)或数值区间桶(含起不含止)。 */
191
+ export type DisplayStyleBucket =
192
+ | { kind: 'date'; granularity: 'year' | 'month' | 'day'; start: string }
193
+ | { kind: 'range'; start: number; end: number };
194
+
195
+ /**
196
+ * 把分组桶按字段展示样式格式化为分类树标签。
197
+ * - 日期桶:start 取 `YYYY-MM-DD...`(或 RFC3339)的字面年月日,不经 Date、不换算时区;
198
+ * 按样式码的日期写法(中文年月日 / 斜杠 / 短横线)截到所选粒度,如 `2026年10月`、`2026/10`、`2026-10`。
199
+ * 样式码不是日期类、或该写法无法截到所选粒度的写法推断 → 返回 null,调用方回退到自己的显示方式。
200
+ * - 数值区间桶:两端各按数值样式格式化,用 ` ~ ` 连接;非数值样式两端原样数字连接。
201
+ */
202
+ export function formatDisplayStyleBucketLabel(
203
+ bucket: DisplayStyleBucket,
204
+ displayStyle: string | null | undefined,
205
+ ): string | null {
206
+ if (bucket.kind === 'range') {
207
+ if (!Number.isFinite(bucket.start) || !Number.isFinite(bucket.end)) return null;
208
+ const fmt = (n: number): string =>
209
+ (isNumericDisplayStyle(displayStyle) ? formatDisplayStyleValue(n, displayStyle) : null) ?? String(n);
210
+ return `${fmt(bucket.start)} ~ ${fmt(bucket.end)}`;
211
+ }
212
+ if (!displayStyle || !DATE_TIME_DISPLAY_STYLES.has(displayStyle)) return null;
213
+ const parts = parseWallClockParts(bucket.start);
214
+ if (!parts) return null;
215
+ const sep = dateSeparatorOf(displayStyle);
216
+ if (!sep) return null;
217
+ // 补零口径跟随样式本身:421~432 族补零,401~411 族不补零(对齐 formatDateTimeParts)
218
+ const padded = PADDED_DATE_STYLES.has(displayStyle);
219
+ const mm = padded ? pad2(parts.month) : String(parts.month);
220
+ const dd = padded ? pad2(parts.day) : String(parts.day);
221
+ if (sep === 'cn') {
222
+ if (bucket.granularity === 'year') return `${parts.year}年`;
223
+ if (bucket.granularity === 'month') return `${parts.year}年${mm}月`;
224
+ return `${parts.year}年${mm}月${dd}日`;
225
+ }
226
+ if (bucket.granularity === 'year') return `${parts.year}`;
227
+ if (bucket.granularity === 'month') return `${parts.year}${sep}${mm}`;
228
+ return `${parts.year}${sep}${mm}${sep}${dd}`;
229
+ }
230
+
231
+ /** 月/日补零的日期样式码(421~432 族);其余日期码(401~411)不补零。 */
232
+ const PADDED_DATE_STYLES = new Set<string>(['421', '422', '423', '424', '425', '426', '430', '431', '432']);
233
+
234
+ /**
235
+ * 日期样式码 → 日期写法:'cn'=中文年月日、'/'=斜杠、'-'=短横线;时分秒类与纯月日类(缺年份)返回 null。
236
+ * 码表对应 formatDateTimeParts:401~403/406/409/421/424/430 为短横线(401 仅年份按短横线处理),
237
+ * 402/405/408/411/423/426/432 为中文,404/407/410/422/425/431 为斜杠。
238
+ */
239
+ function dateSeparatorOf(displayStyle: string): '-' | '/' | 'cn' | null {
240
+ switch (displayStyle) {
241
+ case '401': case '403': case '421': case '406': case '424': case '409': case '430':
242
+ return '-';
243
+ case '404': case '422': case '407': case '425': case '410': case '431':
244
+ return '/';
245
+ case '402': case '405': case '423': case '408': case '426': case '411': case '432':
246
+ return 'cn';
247
+ default:
248
+ return null;
249
+ }
250
+ }