@wordrhyme/auto-crud 1.7.0 → 1.8.0

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.
package/dist/index.d.ts CHANGED
@@ -10,323 +10,6 @@ import { z } from "zod";
10
10
  import { JsonSchemaFormScope } from "@wordrhyme/formily-shadcn";
11
11
  import { ISchema } from "@formily/json-schema";
12
12
 
13
- //#region src/lib/default-sorting.d.ts
14
- type AutoCrudSorting = Array<{
15
- id: string;
16
- desc: boolean;
17
- }>;
18
- //#endregion
19
- //#region src/hooks/use-auto-crud-resource.d.ts
20
- /**
21
- * Toast 适配器接口
22
- * 用户可以注入自己的 toast 实现
23
- */
24
- interface ToastAdapter {
25
- success: (message: string) => void;
26
- error: (message: string) => void;
27
- info?: (message: string) => void;
28
- warning?: (message: string) => void;
29
- }
30
- /** 空 toast 适配器(禁用通知) */
31
- declare const noopToastAdapter: ToastAdapter;
32
- interface AutoCrudQueryCapabilities {
33
- search?: {
34
- enabled: boolean;
35
- fields: string[];
36
- };
37
- filters?: {
38
- enabled: boolean;
39
- fields: string[] | null;
40
- };
41
- sort?: {
42
- enabled: boolean;
43
- fields: string[] | null;
44
- };
45
- }
46
- /**
47
- * Modal 状态类型
48
- */
49
- type ModalVariant$1 = 'dialog' | 'sheet';
50
- interface ModalState<T> {
51
- createOpen: boolean;
52
- editOpen: boolean;
53
- deleteOpen: boolean;
54
- viewOpen: boolean;
55
- selected: T | null;
56
- /** 复制源数据(用于复制行功能) */
57
- copySource: T | null;
58
- variant: ModalVariant$1;
59
- }
60
- /**
61
- * Hook 返回值类型(用于判断是数据转换还是完全自定义)
62
- * - 返回对象 = 数据转换,继续执行默认 mutation
63
- * - 返回 true/false = 完全自定义,跳过默认 mutation
64
- */
65
- type HookResult<T> = T | boolean;
66
- /**
67
- * 统一的 hooks 配置
68
- */
69
- interface CrudHooks<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
70
- /**
71
- * 创建前钩子
72
- * - 返回对象: 作为转换后的数据,继续执行默认创建
73
- * - 返回 true: 表示已自定义处理成功,跳过默认创建
74
- * - 返回 false: 表示自定义处理失败,跳过默认创建
75
- */
76
- beforeCreate?: (values: z.infer<TSchema>) => HookResult<z.infer<TSchema>> | Promise<HookResult<z.infer<TSchema>>>;
77
- /**
78
- * 更新前钩子
79
- * - 返回对象: 作为转换后的数据,继续执行默认更新
80
- * - 返回 true/false: 完全自定义处理
81
- */
82
- beforeUpdate?: (values: z.infer<TSchema>, original: TListItem) => HookResult<z.infer<TSchema>> | Promise<HookResult<z.infer<TSchema>>>;
83
- /**
84
- * 删除前钩子
85
- * - 返回 true: 表示已自定义处理成功(如软删除)
86
- * - 返回 false: 表示自定义处理失败
87
- * - 返回 undefined/void: 继续执行默认删除
88
- */
89
- beforeDelete?: (item: TListItem) => boolean | void | Promise<boolean | void>;
90
- /** 操作成功回调 */
91
- onSuccess?: (op: 'create' | 'update' | 'delete', payload: unknown) => void;
92
- /** 操作失败回调 */
93
- onError?: (op: 'create' | 'update' | 'delete', error: Error) => void;
94
- }
95
- /**
96
- * Hook 配置选项
97
- */
98
- interface UseAutoCrudResourceOptions<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
99
- /** 主键字段名(默认: "id") */
100
- idKey?: keyof TListItem & string;
101
- /** 默认弹窗模式 */
102
- defaultVariant?: ModalVariant$1;
103
- /** 统一钩子配置 */
104
- hooks?: CrudHooks<TSchema, TListItem>;
105
- /**
106
- * Toast 配置
107
- * - undefined: 使用内置 sonner(默认)
108
- * - false: 禁用所有通知
109
- * - ToastAdapter: 注入自定义 toast 实现
110
- */
111
- toast?: ToastAdapter | false;
112
- /**
113
- * 自定义导出数据获取函数(escape hatch)
114
- *
115
- * 通常不需要传此参数:
116
- * - 导出选中行:纯客户端,零配置
117
- * - 导出筛选结果:router 有 export procedure 时自动可用
118
- *
119
- * 仅当需要完全自定义导出逻辑时才使用(如队列导出、自定义接口等)
120
- * 传入后优先级高于 router.export
121
- */
122
- exportFetcher?: (params: any) => Promise<{
123
- data: Record<string, unknown>[];
124
- total: number;
125
- hasMore: boolean;
126
- }>;
127
- /**
128
- * 默认排序。
129
- * - undefined: schema 有 createdAt 时默认 createdAt desc
130
- * - false: 不应用默认排序
131
- */
132
- defaultSort?: AutoCrudSorting | false;
133
- }
134
- /**
135
- * 导入结果类型(与服务端保持一致)
136
- */
137
- interface ImportResult {
138
- success: number;
139
- updated: number;
140
- skipped: number;
141
- failed: Array<{
142
- row: number;
143
- errors: string[];
144
- }>;
145
- }
146
- /**
147
- * Hook 返回值类型
148
- */
149
- interface UseAutoCrudResourceReturn<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
150
- /** 主键字段名(默认: "id") */
151
- idKey?: keyof TListItem & string;
152
- tableData: {
153
- data: TListItem[];
154
- pageCount: number;
155
- /** Total rows matching the current search and filters. */
156
- total?: number;
157
- isLoading: boolean;
158
- /** 是否正在获取数据(用于显示微妙的加载指示器) */
159
- isFetching: boolean;
160
- };
161
- /** Optional schema override from host metadata. */
162
- schema?: z.ZodObject<z.ZodRawShape>;
163
- /** Optional field config override from host metadata. */
164
- fields?: Fields;
165
- /** Query capabilities reported by auto-crud-server metadata. */
166
- capabilities?: AutoCrudQueryCapabilities;
167
- /** Default sorting used by this resource's list query. */
168
- defaultSort?: AutoCrudSorting;
169
- modal: ModalState<TListItem>;
170
- mutations: {
171
- isCreating: boolean;
172
- isUpdating: boolean;
173
- isDeleting: boolean;
174
- isImporting: boolean;
175
- };
176
- handlers: {
177
- openCreate: () => void;
178
- openEdit: (row: TListItem) => void;
179
- openDelete: (row: TListItem) => void;
180
- openView: (row: TListItem) => void;
181
- copyRow: (row: TListItem) => void;
182
- closeModals: () => void;
183
- submitCreate: (values: z.infer<TSchema>) => void;
184
- submitUpdate: (values: z.infer<TSchema>) => void;
185
- confirmDelete: () => void;
186
- deleteMany: (rows: TListItem[]) => void;
187
- updateMany: (rows: TListItem[], data: Record<string, unknown>) => void;
188
- setVariant: (variant: ModalVariant$1) => void;
189
- /** 刷新当前列表数据 */
190
- refresh?: () => Promise<unknown>;
191
- /** 导入数据(router 有 import 路由时自动可用) */
192
- import: ((rows: Record<string, unknown>[]) => Promise<ImportResult>) | null;
193
- /** 导出筛选结果(router 有 export procedure 或传入 exportFetcher 时自动可用)。导出选中行由 AutoCrudTable 内部处理 */
194
- export: (() => Promise<Record<string, unknown>[]>) | null;
195
- };
196
- }
197
- /**
198
- * tRPC Router 接口定义(宽松类型以兼容实际 tRPC router)
199
- * import 为可选 — 传入 router 时自动检测是否存在
200
- */
201
- interface CrudRouter {
202
- list: {
203
- useQuery: (input?: any, opts?: any) => any;
204
- };
205
- create: {
206
- useMutation: (opts?: any) => any;
207
- };
208
- update: {
209
- useMutation: (opts?: any) => any;
210
- };
211
- delete: {
212
- useMutation: (opts?: any) => any;
213
- };
214
- deleteMany?: {
215
- useMutation: (opts?: any) => any;
216
- };
217
- updateMany?: {
218
- useMutation: (opts?: any) => any;
219
- };
220
- /** 导入路由(mutation,由 createCrudRouter 自动生成) */
221
- import?: {
222
- useMutation: (opts?: any) => any;
223
- };
224
- /** 导出路由(query,由 createCrudRouter 自动生成) */
225
- export?: {
226
- useQuery: (input?: any, opts?: any) => any;
227
- };
228
- /** 元数据路由(query,由 createCrudRouter 自动生成) */
229
- meta?: {
230
- useQuery: (input?: any, opts?: any) => any;
231
- };
232
- }
233
- /**
234
- * 自动生成的查询参数(由内部 URL 状态管理生成)
235
- */
236
- interface AutoQueryParams {
237
- page: number;
238
- perPage: number;
239
- sort: Array<{
240
- id: string;
241
- desc: boolean;
242
- }>;
243
- search?: string;
244
- filters: any[];
245
- joinOperator: 'and' | 'or';
246
- }
247
- /**
248
- * Hook 配置参数
249
- */
250
- interface UseAutoCrudResourceParams<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
251
- /** tRPC router (如 trpc.tasks) */
252
- router: CrudRouter;
253
- /** Zod schema */
254
- schema: TSchema;
255
- /**
256
- * 查询参数变换函数
257
- *
258
- * 默认零配置:hook 内部自动管理 URL 状态(分页、排序、筛选),
259
- * 传入此函数可注入额外参数或修改自动生成的参数。
260
- *
261
- * @example
262
- * ```tsx
263
- * // 注入租户 ID
264
- * query: (params) => ({ ...params, tenantId: currentTenant.id })
265
- *
266
- * // 覆盖默认分页
267
- * query: (params) => ({ ...params, perPage: 20 })
268
- * ```
269
- */
270
- query?: (params: AutoQueryParams) => Record<string, unknown>;
271
- /** 其他配置选项 */
272
- options?: UseAutoCrudResourceOptions<TSchema, TListItem>;
273
- }
274
- /**
275
- * Hook 主函数
276
- */
277
- declare function useAutoCrudResource<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem = z.output<TSchema>>({
278
- router,
279
- schema,
280
- query: queryTransform,
281
- options
282
- }: UseAutoCrudResourceParams<TSchema, TListItem>): UseAutoCrudResourceReturn<TSchema, TListItem>;
283
- //#endregion
284
- //#region src/types/permissions.d.ts
285
- /**
286
- * CRUD 操作权限
287
- * 控制工具栏按钮、行操作按钮、批量操作按钮的显示
288
- */
289
- interface CrudOperationPermissions {
290
- /** 是否允许创建(新建按钮、复制行操作) */
291
- create?: boolean;
292
- /** 是否允许更新(编辑按钮、批量更新) */
293
- update?: boolean;
294
- /** 是否允许删除(删除按钮、批量删除) */
295
- delete?: boolean;
296
- /** 是否允许导出 */
297
- export?: boolean;
298
- /** 是否允许导入 */
299
- import?: boolean;
300
- }
301
- /**
302
- * AutoCrudTable 权限配置
303
- *
304
- * @example
305
- * ```tsx
306
- * const permissions = useMemo(() => ({
307
- * can: {
308
- * create: user.role === 'admin',
309
- * update: user.role === 'admin' || user.role === 'editor',
310
- * delete: user.role === 'admin',
311
- * export: true,
312
- * },
313
- * deny: user.role === 'user' ? ['salary', 'ssn'] : [],
314
- * }), [user.role]);
315
- *
316
- * <AutoCrudTable
317
- * schema={employeeSchema}
318
- * resource={resource}
319
- * permissions={permissions}
320
- * />
321
- * ```
322
- */
323
- interface CrudPermissions {
324
- /** 操作权限(默认全部为 true) */
325
- can?: CrudOperationPermissions;
326
- /** 禁止访问的字段列表(表格列和表单字段都会隐藏) */
327
- deny?: string[];
328
- }
329
- //#endregion
330
13
  //#region src/hooks/use-url-state.d.ts
331
14
  /**
332
15
  * URL 状态管理 Hook - 替代 nuqs
@@ -559,80 +242,409 @@ declare const filterItemSchema: z.ZodObject<{
559
242
  inArray: "inArray";
560
243
  notInArray: "notInArray";
561
244
  }>;
562
- filterId: z.ZodString;
563
- }, z.core.$strip>;
564
- type FilterItemSchema = z.infer<typeof filterItemSchema>;
565
- //#endregion
566
- //#region src/types/data-table.d.ts
567
- interface DataTableClassNames {
568
- table?: string;
569
- thead?: string;
570
- tbody?: string;
571
- /** 应用于表头行、正文行和空状态行 */
572
- tr?: string;
573
- th?: string;
574
- td?: string;
245
+ filterId: z.ZodString;
246
+ }, z.core.$strip>;
247
+ type FilterItemSchema = z.infer<typeof filterItemSchema>;
248
+ //#endregion
249
+ //#region src/types/data-table.d.ts
250
+ interface DataTableClassNames {
251
+ table?: string;
252
+ thead?: string;
253
+ tbody?: string;
254
+ /** 应用于表头行、正文行和空状态行 */
255
+ tr?: string;
256
+ th?: string;
257
+ td?: string;
258
+ }
259
+ /** Optional pagination controls. Omitted options preserve the existing layout. */
260
+ interface TablePaginationOptions {
261
+ /** Show first/last page buttons at every viewport width; default remains lg-only. */
262
+ alwaysShowFirstLast?: boolean;
263
+ /** Hide optional controls when their measured content does not fit the container. */
264
+ responsive?: boolean;
265
+ /** Show an input to jump to a known page; defaults to false. */
266
+ showPageJump?: boolean;
267
+ pageJumpLabel?: string;
268
+ }
269
+ declare module '@tanstack/react-table' {
270
+ interface TableMeta<TData extends RowData> {
271
+ queryKeys?: QueryKeys;
272
+ queryStateOptions?: UrlStateOptions;
273
+ }
274
+ interface ColumnMeta<TData extends RowData, TValue> {
275
+ label?: string;
276
+ index?: number;
277
+ /** 按元素分组的列类名,优先于全局单元格类名 */
278
+ classNames?: Pick<DataTableClassNames, 'th' | 'td'>;
279
+ placeholder?: string;
280
+ variant?: FilterVariant$1;
281
+ options?: Option[];
282
+ range?: [number, number];
283
+ /** Latest selectable calendar day (YYYY-MM-DD), or today in the Host time zone. */
284
+ maxDate?: string;
285
+ unit?: string;
286
+ icon?: React.FC<React.SVGProps<SVGSVGElement>>;
287
+ /** 控制在哪些筛选模式下显示(未设置则在所有模式显示) */
288
+ modes?: Array<'simple' | 'advanced' | 'command'>;
289
+ /** 内部:远程筛选选项搜索值 */
290
+ autoCrudFilterSearchValue?: string;
291
+ /** 内部:远程筛选选项搜索回调 */
292
+ autoCrudFilterOnSearch?: (value: string) => void;
293
+ /** 内部:是否启用本地选项过滤 */
294
+ autoCrudFilterShouldFilter?: boolean;
295
+ /** 内部:远程筛选当前弹窗选项,和稳定标签缓存分离 */
296
+ autoCrudFilterOptions?: Option[];
297
+ /** 内部:远程筛选是否还有更多选项 */
298
+ autoCrudFilterHasMore?: boolean;
299
+ /** 内部:远程筛选是否正在加载 */
300
+ autoCrudFilterLoading?: boolean;
301
+ /** 内部:远程筛选弹窗滚动回调 */
302
+ autoCrudFilterOnPopupScroll?: React.UIEventHandler<HTMLElement>;
303
+ }
304
+ }
305
+ interface QueryKeys {
306
+ page: string;
307
+ perPage: string;
308
+ sort: string;
309
+ filters: string;
310
+ joinOperator: string;
311
+ }
312
+ interface Option {
313
+ label: string;
314
+ value: string;
315
+ searchText?: string;
316
+ count?: number;
317
+ icon?: React.FC<React.SVGProps<SVGSVGElement>>;
318
+ }
319
+ type FilterOperator = DataTableConfig['operators'][number];
320
+ type FilterVariant$1 = DataTableConfig['filterVariants'][number];
321
+ type JoinOperator = DataTableConfig['joinOperators'][number];
322
+ interface ExtendedColumnSort<TData> extends Omit<ColumnSort, 'id'> {
323
+ id: Extract<keyof TData, string>;
324
+ }
325
+ interface ExtendedColumnFilter<TData> extends FilterItemSchema {
326
+ id: Extract<keyof TData, string>;
327
+ }
328
+ interface DataTableRowAction<TData> {
329
+ row: Row<TData>;
330
+ variant: 'update' | 'delete';
331
+ }
332
+ //#endregion
333
+ //#region src/lib/default-sorting.d.ts
334
+ type AutoCrudSorting = Array<{
335
+ id: string;
336
+ desc: boolean;
337
+ }>;
338
+ //#endregion
339
+ //#region src/hooks/use-auto-crud-resource.d.ts
340
+ /**
341
+ * Toast 适配器接口
342
+ * 用户可以注入自己的 toast 实现
343
+ */
344
+ interface ToastAdapter {
345
+ success: (message: string) => void;
346
+ error: (message: string) => void;
347
+ info?: (message: string) => void;
348
+ warning?: (message: string) => void;
349
+ }
350
+ /** 空 toast 适配器(禁用通知) */
351
+ declare const noopToastAdapter: ToastAdapter;
352
+ interface AutoCrudQueryCapabilities {
353
+ search?: {
354
+ enabled: boolean;
355
+ fields: string[];
356
+ };
357
+ filters?: {
358
+ enabled: boolean;
359
+ fields: string[] | null;
360
+ };
361
+ sort?: {
362
+ enabled: boolean;
363
+ fields: string[] | null;
364
+ };
365
+ }
366
+ /**
367
+ * Modal 状态类型
368
+ */
369
+ type ModalVariant$1 = 'dialog' | 'sheet';
370
+ interface ModalState<T> {
371
+ createOpen: boolean;
372
+ editOpen: boolean;
373
+ deleteOpen: boolean;
374
+ viewOpen: boolean;
375
+ selected: T | null;
376
+ /** 复制源数据(用于复制行功能) */
377
+ copySource: T | null;
378
+ variant: ModalVariant$1;
379
+ }
380
+ /**
381
+ * Hook 返回值类型(用于判断是数据转换还是完全自定义)
382
+ * - 返回对象 = 数据转换,继续执行默认 mutation
383
+ * - 返回 true/false = 完全自定义,跳过默认 mutation
384
+ */
385
+ type HookResult<T> = T | boolean;
386
+ /**
387
+ * 统一的 hooks 配置
388
+ */
389
+ interface CrudHooks<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
390
+ /**
391
+ * 创建前钩子
392
+ * - 返回对象: 作为转换后的数据,继续执行默认创建
393
+ * - 返回 true: 表示已自定义处理成功,跳过默认创建
394
+ * - 返回 false: 表示自定义处理失败,跳过默认创建
395
+ */
396
+ beforeCreate?: (values: z.infer<TSchema>) => HookResult<z.infer<TSchema>> | Promise<HookResult<z.infer<TSchema>>>;
397
+ /**
398
+ * 更新前钩子
399
+ * - 返回对象: 作为转换后的数据,继续执行默认更新
400
+ * - 返回 true/false: 完全自定义处理
401
+ */
402
+ beforeUpdate?: (values: z.infer<TSchema>, original: TListItem) => HookResult<z.infer<TSchema>> | Promise<HookResult<z.infer<TSchema>>>;
403
+ /**
404
+ * 删除前钩子
405
+ * - 返回 true: 表示已自定义处理成功(如软删除)
406
+ * - 返回 false: 表示自定义处理失败
407
+ * - 返回 undefined/void: 继续执行默认删除
408
+ */
409
+ beforeDelete?: (item: TListItem) => boolean | void | Promise<boolean | void>;
410
+ /** 操作成功回调 */
411
+ onSuccess?: (op: 'create' | 'update' | 'delete', payload: unknown) => void;
412
+ /** 操作失败回调 */
413
+ onError?: (op: 'create' | 'update' | 'delete', error: Error) => void;
414
+ }
415
+ /**
416
+ * Hook 配置选项
417
+ */
418
+ interface UseAutoCrudResourceOptions<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
419
+ /** 主键字段名(默认: "id") */
420
+ idKey?: keyof TListItem & string;
421
+ /** 默认弹窗模式 */
422
+ defaultVariant?: ModalVariant$1;
423
+ /** 统一钩子配置 */
424
+ hooks?: CrudHooks<TSchema, TListItem>;
425
+ /**
426
+ * Toast 配置
427
+ * - undefined: 使用内置 sonner(默认)
428
+ * - false: 禁用所有通知
429
+ * - ToastAdapter: 注入自定义 toast 实现
430
+ */
431
+ toast?: ToastAdapter | false;
432
+ /**
433
+ * 自定义导出数据获取函数(escape hatch)
434
+ *
435
+ * 通常不需要传此参数:
436
+ * - 导出选中行:纯客户端,零配置
437
+ * - 导出筛选结果:router 有 export procedure 时自动可用
438
+ *
439
+ * 仅当需要完全自定义导出逻辑时才使用(如队列导出、自定义接口等)
440
+ * 传入后优先级高于 router.export
441
+ */
442
+ exportFetcher?: (params: any) => Promise<{
443
+ data: Record<string, unknown>[];
444
+ total: number;
445
+ hasMore: boolean;
446
+ }>;
447
+ /**
448
+ * 默认排序。
449
+ * - undefined: schema 有 createdAt 时默认 createdAt desc
450
+ * - false: 不应用默认排序
451
+ */
452
+ defaultSort?: AutoCrudSorting | false;
453
+ }
454
+ /**
455
+ * 导入结果类型(与服务端保持一致)
456
+ */
457
+ interface ImportResult {
458
+ success: number;
459
+ updated: number;
460
+ skipped: number;
461
+ failed: Array<{
462
+ row: number;
463
+ errors: string[];
464
+ }>;
575
465
  }
576
- declare module '@tanstack/react-table' {
577
- interface TableMeta<TData extends RowData> {
578
- queryKeys?: QueryKeys;
579
- queryStateOptions?: UrlStateOptions;
580
- }
581
- interface ColumnMeta<TData extends RowData, TValue> {
582
- label?: string;
583
- index?: number;
584
- /** 按元素分组的列类名,优先于全局单元格类名 */
585
- classNames?: Pick<DataTableClassNames, 'th' | 'td'>;
586
- placeholder?: string;
587
- variant?: FilterVariant$1;
588
- options?: Option[];
589
- range?: [number, number];
590
- unit?: string;
591
- icon?: React.FC<React.SVGProps<SVGSVGElement>>;
592
- /** 控制在哪些筛选模式下显示(未设置则在所有模式显示) */
593
- modes?: Array<'simple' | 'advanced' | 'command'>;
594
- /** 内部:远程筛选选项搜索值 */
595
- autoCrudFilterSearchValue?: string;
596
- /** 内部:远程筛选选项搜索回调 */
597
- autoCrudFilterOnSearch?: (value: string) => void;
598
- /** 内部:是否启用本地选项过滤 */
599
- autoCrudFilterShouldFilter?: boolean;
600
- /** 内部:远程筛选当前弹窗选项,和稳定标签缓存分离 */
601
- autoCrudFilterOptions?: Option[];
602
- /** 内部:远程筛选是否还有更多选项 */
603
- autoCrudFilterHasMore?: boolean;
604
- /** 内部:远程筛选是否正在加载 */
605
- autoCrudFilterLoading?: boolean;
606
- /** 内部:远程筛选弹窗滚动回调 */
607
- autoCrudFilterOnPopupScroll?: React.UIEventHandler<HTMLElement>;
608
- }
466
+ /**
467
+ * Hook 返回值类型
468
+ */
469
+ interface UseAutoCrudResourceReturn<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
470
+ /** 主键字段名(默认: "id") */
471
+ idKey?: keyof TListItem & string;
472
+ tableData: {
473
+ data: TListItem[];
474
+ pageCount: number;
475
+ /** Total rows matching the current search and filters. */
476
+ total?: number;
477
+ isLoading: boolean;
478
+ /** 是否正在获取数据(用于显示微妙的加载指示器) */
479
+ isFetching: boolean;
480
+ };
481
+ /** Optional schema override from host metadata. */
482
+ schema?: z.ZodObject<z.ZodRawShape>;
483
+ /** Optional field config override from host metadata. */
484
+ fields?: Fields;
485
+ /** Query capabilities reported by auto-crud-server metadata. */
486
+ capabilities?: AutoCrudQueryCapabilities;
487
+ /** Default sorting used by this resource's list query. */
488
+ defaultSort?: AutoCrudSorting;
489
+ modal: ModalState<TListItem>;
490
+ mutations: {
491
+ isCreating: boolean;
492
+ isUpdating: boolean;
493
+ isDeleting: boolean;
494
+ isImporting: boolean;
495
+ };
496
+ handlers: {
497
+ openCreate: () => void;
498
+ openEdit: (row: TListItem) => void;
499
+ openDelete: (row: TListItem) => void;
500
+ openView: (row: TListItem) => void;
501
+ copyRow: (row: TListItem) => void;
502
+ closeModals: () => void;
503
+ submitCreate: (values: z.infer<TSchema>) => void;
504
+ submitUpdate: (values: z.infer<TSchema>) => void;
505
+ confirmDelete: () => void;
506
+ deleteMany: (rows: TListItem[]) => void;
507
+ updateMany: (rows: TListItem[], data: Record<string, unknown>) => void;
508
+ setVariant: (variant: ModalVariant$1) => void;
509
+ /** 刷新当前列表数据 */
510
+ refresh?: () => Promise<unknown>;
511
+ /** 导入数据(router 有 import 路由时自动可用) */
512
+ import: ((rows: Record<string, unknown>[]) => Promise<ImportResult>) | null;
513
+ /** 导出筛选结果(router 有 export procedure 或传入 exportFetcher 时自动可用)。导出选中行由 AutoCrudTable 内部处理 */
514
+ export: (() => Promise<Record<string, unknown>[]>) | null;
515
+ };
609
516
  }
610
- interface QueryKeys {
611
- page: string;
612
- perPage: string;
613
- sort: string;
614
- filters: string;
615
- joinOperator: string;
517
+ /**
518
+ * tRPC Router 接口定义(宽松类型以兼容实际 tRPC router)
519
+ * import 为可选 — 传入 router 时自动检测是否存在
520
+ */
521
+ interface CrudRouter {
522
+ list: {
523
+ useQuery: (input?: any, opts?: any) => any;
524
+ };
525
+ create: {
526
+ useMutation: (opts?: any) => any;
527
+ };
528
+ update: {
529
+ useMutation: (opts?: any) => any;
530
+ };
531
+ delete: {
532
+ useMutation: (opts?: any) => any;
533
+ };
534
+ deleteMany?: {
535
+ useMutation: (opts?: any) => any;
536
+ };
537
+ updateMany?: {
538
+ useMutation: (opts?: any) => any;
539
+ };
540
+ /** 导入路由(mutation,由 createCrudRouter 自动生成) */
541
+ import?: {
542
+ useMutation: (opts?: any) => any;
543
+ };
544
+ /** 导出路由(query,由 createCrudRouter 自动生成) */
545
+ export?: {
546
+ useQuery: (input?: any, opts?: any) => any;
547
+ };
548
+ /** 元数据路由(query,由 createCrudRouter 自动生成) */
549
+ meta?: {
550
+ useQuery: (input?: any, opts?: any) => any;
551
+ };
616
552
  }
617
- interface Option {
618
- label: string;
619
- value: string;
620
- searchText?: string;
621
- count?: number;
622
- icon?: React.FC<React.SVGProps<SVGSVGElement>>;
553
+ /**
554
+ * 自动生成的查询参数(由内部 URL 状态管理生成)
555
+ */
556
+ interface AutoQueryParams {
557
+ page: number;
558
+ perPage: number;
559
+ sort: Array<{
560
+ id: string;
561
+ desc: boolean;
562
+ }>;
563
+ search?: string;
564
+ filters: any[];
565
+ joinOperator: 'and' | 'or';
623
566
  }
624
- type FilterOperator = DataTableConfig['operators'][number];
625
- type FilterVariant$1 = DataTableConfig['filterVariants'][number];
626
- type JoinOperator = DataTableConfig['joinOperators'][number];
627
- interface ExtendedColumnSort<TData> extends Omit<ColumnSort, 'id'> {
628
- id: Extract<keyof TData, string>;
567
+ /**
568
+ * Hook 配置参数
569
+ */
570
+ interface UseAutoCrudResourceParams<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem> {
571
+ /** tRPC router (如 trpc.tasks) */
572
+ router: CrudRouter;
573
+ /** Zod schema */
574
+ schema: TSchema;
575
+ /**
576
+ * 查询参数变换函数
577
+ *
578
+ * 默认零配置:hook 内部自动管理 URL 状态(分页、排序、筛选),
579
+ * 传入此函数可注入额外参数或修改自动生成的参数。
580
+ *
581
+ * @example
582
+ * ```tsx
583
+ * // 注入租户 ID
584
+ * query: (params) => ({ ...params, tenantId: currentTenant.id })
585
+ *
586
+ * // 覆盖默认分页
587
+ * query: (params) => ({ ...params, perPage: 20 })
588
+ * ```
589
+ */
590
+ query?: (params: AutoQueryParams) => Record<string, unknown>;
591
+ /** 其他配置选项 */
592
+ options?: UseAutoCrudResourceOptions<TSchema, TListItem>;
629
593
  }
630
- interface ExtendedColumnFilter<TData> extends FilterItemSchema {
631
- id: Extract<keyof TData, string>;
594
+ /**
595
+ * Hook 主函数
596
+ */
597
+ declare function useAutoCrudResource<TSchema extends z.ZodObject<z.ZodRawShape>, TListItem = z.output<TSchema>>({
598
+ router,
599
+ schema,
600
+ query: queryTransform,
601
+ options
602
+ }: UseAutoCrudResourceParams<TSchema, TListItem>): UseAutoCrudResourceReturn<TSchema, TListItem>;
603
+ //#endregion
604
+ //#region src/types/permissions.d.ts
605
+ /**
606
+ * CRUD 操作权限
607
+ * 控制工具栏按钮、行操作按钮、批量操作按钮的显示
608
+ */
609
+ interface CrudOperationPermissions {
610
+ /** 是否允许创建(新建按钮、复制行操作) */
611
+ create?: boolean;
612
+ /** 是否允许更新(编辑按钮、批量更新) */
613
+ update?: boolean;
614
+ /** 是否允许删除(删除按钮、批量删除) */
615
+ delete?: boolean;
616
+ /** 是否允许导出 */
617
+ export?: boolean;
618
+ /** 是否允许导入 */
619
+ import?: boolean;
632
620
  }
633
- interface DataTableRowAction<TData> {
634
- row: Row<TData>;
635
- variant: 'update' | 'delete';
621
+ /**
622
+ * AutoCrudTable 权限配置
623
+ *
624
+ * @example
625
+ * ```tsx
626
+ * const permissions = useMemo(() => ({
627
+ * can: {
628
+ * create: user.role === 'admin',
629
+ * update: user.role === 'admin' || user.role === 'editor',
630
+ * delete: user.role === 'admin',
631
+ * export: true,
632
+ * },
633
+ * deny: user.role === 'user' ? ['salary', 'ssn'] : [],
634
+ * }), [user.role]);
635
+ *
636
+ * <AutoCrudTable
637
+ * schema={employeeSchema}
638
+ * resource={resource}
639
+ * permissions={permissions}
640
+ * />
641
+ * ```
642
+ */
643
+ interface CrudPermissions {
644
+ /** 操作权限(默认全部为 true) */
645
+ can?: CrudOperationPermissions;
646
+ /** 禁止访问的字段列表(表格列和表单字段都会隐藏) */
647
+ deny?: string[];
636
648
  }
637
649
  //#endregion
638
650
  //#region src/components/auto-crud/auto-table-action-bar.d.ts
@@ -835,6 +847,7 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> {
835
847
  schema: T;
836
848
  data: z.infer<T>[];
837
849
  pageCount?: number;
850
+ pagination?: TablePaginationOptions;
838
851
  /** Total rows matching the current search and filters. */
839
852
  total?: number;
840
853
  overrides?: ColumnOverrides<z.infer<T>>;
@@ -888,6 +901,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
888
901
  schema,
889
902
  data,
890
903
  pageCount,
904
+ pagination,
891
905
  total,
892
906
  overrides,
893
907
  classNames,
@@ -930,6 +944,9 @@ interface RowActionDialogProps {
930
944
  * <AutoCrudTable locale={{ toolbar: { create: "Add" } }} ... />
931
945
  */
932
946
  interface AutoCrudLocale {
947
+ pagination?: {
948
+ pageJump?: string;
949
+ };
933
950
  toolbar: {
934
951
  refresh: string;
935
952
  create: string;
@@ -1071,6 +1088,13 @@ type AutoCrudDataSourceEntry = {
1071
1088
  load: AutoCrudDataSourceLoader;
1072
1089
  };
1073
1090
  type RegistryListener$1 = () => void;
1091
+ declare const tablePagination: {
1092
+ register(name: string, value: TablePaginationOptions): void;
1093
+ unregister(name: string): void;
1094
+ get(name: string): TablePaginationOptions | undefined;
1095
+ all(): Record<string, TablePaginationOptions>;
1096
+ subscribe(listener: RegistryListener$1): () => void;
1097
+ };
1074
1098
  declare const formComponents: {
1075
1099
  register(name: string, value: AutoCrudFormComponentConfig): void;
1076
1100
  unregister(name: string): void;
@@ -1113,6 +1137,8 @@ interface FilterConfig {
1113
1137
  dataSource?: AutoCrudDataSourceConfig;
1114
1138
  /** range 的最小/最大值 */
1115
1139
  range?: [number, number];
1140
+ /** Latest selectable calendar day (YYYY-MM-DD), or today in the Host time zone. */
1141
+ maxDate?: string;
1116
1142
  /** number 的单位 */
1117
1143
  unit?: string;
1118
1144
  /** 过滤器占位符 */
@@ -1142,6 +1168,11 @@ type FieldTableDisplay = 'auto' | 'text' | 'badge' | 'date' | 'datetime';
1142
1168
  interface Field {
1143
1169
  /** 字段标签(表格和表单共用) */
1144
1170
  label?: string;
1171
+ /** Format default table/detail text and CSV values; undefined keeps the default. */
1172
+ format?: (value: unknown, context: {
1173
+ row: Record<string, unknown>;
1174
+ target: 'display' | 'export';
1175
+ }) => string | undefined;
1145
1176
  /** 字段级静态选项(表单、筛选、展示共用) */
1146
1177
  enum?: FieldOption[];
1147
1178
  /** 字段级动态选项源(表单、筛选、展示共用) */
@@ -1329,6 +1360,8 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
1329
1360
  };
1330
1361
  /** 表格配置 */
1331
1362
  table?: {
1363
+ /** Optional controls; overrides the application registration for this CRUD id. */
1364
+ pagination?: TablePaginationOptions;
1332
1365
  /** 按元素分组的全局表格类名;列级 th/td 类名优先 */
1333
1366
  classNames?: DataTableClassNames;
1334
1367
  /** 隐藏的列 */
@@ -1591,12 +1624,14 @@ declare function ExportDialog({
1591
1624
  //#region src/components/data-table/data-table.d.ts
1592
1625
  interface DataTableProps<TData> extends React$1.ComponentProps<'div'> {
1593
1626
  table: Table<TData>;
1627
+ pagination?: TablePaginationOptions;
1594
1628
  classNames?: DataTableClassNames;
1595
1629
  actionBar?: React$1.ReactNode;
1596
1630
  }
1597
1631
  declare function DataTable<TData>({
1598
1632
  table,
1599
1633
  actionBar,
1634
+ pagination,
1600
1635
  children,
1601
1636
  className,
1602
1637
  classNames,
@@ -1641,13 +1676,17 @@ declare function DataTableFacetedFilter<TData, TValue>({
1641
1676
  }: DataTableFacetedFilterProps<TData, TValue>): react_jsx_runtime2.JSX.Element;
1642
1677
  //#endregion
1643
1678
  //#region src/components/data-table/data-table-pagination.d.ts
1644
- interface DataTablePaginationProps<TData> extends React.ComponentProps<'div'> {
1679
+ interface DataTablePaginationProps<TData> extends React.ComponentProps<'div'>, TablePaginationOptions {
1645
1680
  table: Table<TData>;
1646
1681
  pageSizeOptions?: number[];
1647
1682
  }
1648
1683
  declare function DataTablePagination<TData>({
1649
1684
  table,
1650
1685
  pageSizeOptions,
1686
+ alwaysShowFirstLast,
1687
+ responsive,
1688
+ showPageJump,
1689
+ pageJumpLabel,
1651
1690
  className,
1652
1691
  ...props
1653
1692
  }: DataTablePaginationProps<TData>): react_jsx_runtime2.JSX.Element;
@@ -2064,4 +2103,4 @@ declare function exportAllToCSV<T extends Record<string, unknown>>(data: T[], op
2064
2103
  */
2065
2104
  declare function downloadCSVTemplate(headers: string[], filename?: string): void;
2066
2105
  //#endregion
2067
- export { type ActionConfig, type ActionItem, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, cn, coerceRowValues, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };
2106
+ export { type ActionConfig, type ActionItem, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type TablePaginationOptions, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, cn, coerceRowValues, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };