@wordrhyme/auto-crud 1.8.2 → 1.10.0

package/README.md

@@ -264,6 +264,8 @@ interface AutoCrudTableProps<TSchema> {
   table?: {
     hidden?: string[]; // 隐藏的列
     overrides?: Record<string, any>; // 列覆盖配置
+    getRowId?: (record: z.output<TSchema>) => string; // 稳定行标识；展开时必填
+    expandedRow?: (record: z.output<TSchema>) => React.ReactNode; // 展开行内容
     filterModes?: FilterMode | FilterMode[]; // 过滤模式
     batchFields?: (string | BatchUpdateField)[]; // 批量更新字段
     /** @deprecated 新代码请使用 actions.batch */
@@ -294,6 +296,30 @@ interface AutoCrudTableProps<TSchema> {
 }
 ```
 
+#### 展开行详情
+
+配置 `table.expandedRow` 后，表格自动添加展开箭头。默认全部收起，允许同时展开多行。
+必须提供 TanStack Table 的 `getRowId`，使用稳定且唯一的业务主键，避免分页、排序后展开错位。
+
+```tsx
+<AutoCrudTable
+  schema={orderSchema}
+  resource={resource}
+  table={{
+    getRowId: (order) => order.id,
+    expandedRow: (order) => <OrderDetails orderId={order.id} />,
+  }}
+/>
+```
+
+回调接收当前行的原始记录，并同步返回 React 内容。详情组件只在展开时挂载，收起时卸载；
+可由详情组件按订单 ID 查询数据并处理加载、错误和重试，也可直接使用记录中已有的明细。
+明细数据及其字段权限由业务组件和现有服务负责。
+
+详情区域跨全部可见列，不计入分页条数，也不参与主表选择或导出。
+数据更新时，展开状态遵循 TanStack Table 默认重置行为。
+`AutoTable` 同样支持 `getRowId` 和 `expandedRow`；直接使用 `DataTable` 时，需自行配置 TanStack 展开能力及触发按钮。
+
 ### `useAutoCrudResource()`
 
 连接数据源到组件的 Hook。
@@ -1651,6 +1677,14 @@ MIT © [wordrhyme](https://github.com/denvey/wordrhyme-components)
 - [Notion](https://notion.so) - 高级筛选器设计
 - [Linear](https://linear.app) - 命令面板设计
 
+### Status badge colors
+
+For `table.display: "badge"`, a scalar field's `table.options` entries may set `badgeTone` to `neutral`, `success`, `warning`, or `info`. This renders a tinted, outlined rounded label with a decorative dot. Labels remain readable without color; omitted tones retain the default badge. `display: "text"` is unaffected. Domain-specific state-to-tone mappings belong in the consuming plugin metadata.
+
+Registered custom actions may set `before: "delete"` (or another builtin action type) to appear immediately before that action. If the builtin is absent, the existing `position` fallback applies. This only controls ordering and does not add or grant the target action.
+
+Custom row components receive `MenuItem` in their action context. Use this supplied primitive instead of importing a menu item from another UI bundle: the menu root and item must share the same Radix runtime context. Prevent the select event's default dismissal when the component owns an open dialog, so the menu does not unmount the workflow.
+
 ### Detail presentation
 
 Details automatically share field labels, `enum`/`dataSource` mappings and
@@ -1711,6 +1745,31 @@ is pinned to the already-published alpha.19 for reproducible ESM tests and type
 checks until alpha.20 is published; it is not the supported CommonJS runtime.
 The CommonJS export/identity regression belongs to the UI provider repository.
 
+### Filter-only fields
+
+Use `table: false` with an explicit `filter` to keep a field in the standard
+filter bar without rendering a data column. Shared `hidden`, permission `deny`,
+and explicit table exclusions still hide the filter. Pass the same filter
+configuration to the resource so URL values use the same variants/operators:
+
+```tsx
+const fields = {
+  customerId: {
+    label: 'Customer',
+    table: false as const,
+    form: false as const,
+    filter: { variant: 'select' as const, dataSource: 'customers', index: 20 },
+  },
+};
+const resource = useAutoCrudResource({ router, schema, fields });
+return <AutoCrudTable schema={schema} resource={resource} fields={fields} />;
+```
+
+The field must exist in the schema or resource metadata, and the server must
+resolve its filter. A data source loads options; it does not translate query
+conditions. Standard filters share URL state, Reset, and pagination. Dynamically
+registered schema fields hydrate existing URL values without resetting the page.
+
 ### 按 ID 隐藏或替换自定义操作
 
 拥有方为 custom 操作声明稳定 `id` 后，扩展可以在相同 CRUD target 和操作区域

package/dist/index.cjs

@@ -566,7 +566,7 @@ function formatDate(date, opts = {}, preset) {
 
 //#endregion
 //#region src/components/data-table/data-table.tsx
-function DataTable({ table, actionBar, pagination, children, className, classNames,...props }) {
+function DataTable({ table, actionBar, pagination, expandedRow, children, className, classNames,...props }) {
 	useDateFormatterVersion();
 	const columns = [
 		...table.getLeftVisibleLeafColumns(),
@@ -606,7 +606,7 @@ function DataTable({ table, actionBar, pagination, children, className, classNam
 						}),
 						/* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableBody, {
 							className: classNames?.tbody,
-							children: table.getRowModel().rows?.length ? table.getRowModel().rows.map((row) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableRow, {
+							children: table.getRowModel().rows?.length ? table.getRowModel().rows.map((row) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableRow, {
 								className: classNames?.tr,
 								"data-state": row.getIsSelected() && "selected",
 								children: row.getVisibleCells().map((cell) => {
@@ -617,7 +617,14 @@ function DataTable({ table, actionBar, pagination, children, className, classNam
 										children: (0, __tanstack_react_table.flexRender)(cell.column.columnDef.cell, cell.getContext())
 									}, cell.id);
 								})
-							}, row.id)) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableRow, {
+							}), expandedRow && row.getCanExpand() && row.getIsExpanded() && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableRow, {
+								className: classNames?.tr,
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableCell, {
+									colSpan: row.getVisibleCells().length,
+									className: classNames?.td,
+									children: expandedRow(row.original)
+								})
+							})] }, row.id)) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableRow, {
 								className: classNames?.tr,
 								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.TableCell, {
 									colSpan: table.getAllColumns().length,
@@ -1012,6 +1019,11 @@ function useReadableFilters(columns, options = {}) {
 		filtersRef.current = initial;
 		return initial;
 	});
+	react.useEffect(() => {
+		const next = parseReadableFilters(getUrlParams(), columnSnapshot);
+		filtersRef.current = next;
+		setFilters((previous) => JSON.stringify(previous) === JSON.stringify(next) ? previous : next);
+	}, [columnSnapshot]);
 	react.useEffect(() => {
 		const handleUrlChange = () => {
 			if (lastWrittenUrlRef.current !== null && window.location.search === lastWrittenUrlRef.current) {
@@ -3901,9 +3913,12 @@ function coerceRowValues(rows, schema) {
 
 //#endregion
 //#region src/lib/export.ts
+function getExportColumnIds(table) {
+	return table.getAllLeafColumns().filter((column) => column.accessorFn).map((column) => column.id);
+}
 function exportTableToCSV(table, opts = {}) {
 	const { filename = "table", excludeColumns = [], onlySelected = false } = opts;
-	const headers = table.getAllLeafColumns().map((column) => column.id).filter((id) => !excludeColumns.includes(id));
+	const headers = getExportColumnIds(table).filter((id) => !excludeColumns.includes(id));
 	downloadCSV([headers.join(","), ...(onlySelected ? table.getFilteredSelectedRowModel().rows : table.getRowModel().rows).map((row) => headers.map((header) => {
 		const cellValue = row.getValue(header);
 		return typeof cellValue === "string" ? `"${cellValue.replace(/"/g, "\"\"")}"` : cellValue;
@@ -4414,7 +4429,9 @@ const filterModeConfig = {
 		tooltip: "Linear-style command filters"
 	}
 };
-function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, actions, pinnedColumns, filterMode, search = false, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows }) {
+function AutoTable({ schema, data, getRowId, expandedRow, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, filterOnly, actions, pinnedColumns, filterMode, search = false, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows }) {
+	if (expandedRow && !getRowId) throw new Error("AutoTable requires getRowId when expandedRow is provided.");
+	const enableExpansion = !!expandedRow;
 	const modes = filterMode ? Array.isArray(filterMode) ? filterMode : [filterMode] : DEFAULT_MODES;
 	const [currentMode, setCurrentMode] = useQueryState("filterMode", parseAsStringEnum(modes).withDefault(modes[0] ?? "simple"));
 	const showToggle = modes.length > 1;
@@ -4428,36 +4445,85 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 	});
 	const searchConfig = search && typeof search === "object" ? search : {};
 	const enableAdvancedFilter = true;
-	const columns = (0, react.useMemo)(() => {
+	const { columns, expandColumnId } = (0, react.useMemo)(() => {
+		const columnOverrides = Object.assign({}, overrides);
+		for (const key of filterOnly ?? []) {
+			const field = key;
+			Object.assign(columnOverrides, { [field]: {
+				...columnOverrides[field],
+				hidden: false
+			} });
+		}
 		const dataColumns = createTableSchema(schema, {
-			overrides,
+			overrides: columnOverrides,
 			exclude
+		}).map((column) => {
+			const key = column.id ?? ("accessorKey" in column ? String(column.accessorKey) : "");
+			return filterOnly?.includes(key) ? {
+				...column,
+				enableHiding: false,
+				enableSorting: false
+			} : column;
 		});
 		const result = enableRowSelection ? [createSelectColumn(), ...dataColumns] : dataColumns;
+		let expandColumnId$1 = "expand";
+		if (enableExpansion) {
+			while (expandColumnId$1 in schema.shape || result.some((column) => column.id === expandColumnId$1)) expandColumnId$1 = `_${expandColumnId$1}`;
+			result.unshift({
+				id: expandColumnId$1,
+				header: () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "sr-only",
+					children: "Row details"
+				}),
+				cell: ({ row }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.Button, {
+					type: "button",
+					variant: "ghost",
+					size: "icon-sm",
+					"aria-label": row.getIsExpanded() ? "Collapse row" : "Expand row",
+					"aria-expanded": row.getIsExpanded(),
+					onClick: row.getToggleExpandedHandler(),
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.ChevronRightIcon, { className: row.getIsExpanded() ? "size-4 rotate-90" : "size-4" })
+				}),
+				enableHiding: false,
+				enableSorting: false,
+				size: 40
+			});
+		}
 		if (actions) result.push(createActionsColumn(actions));
-		return result;
+		return {
+			columns: result,
+			expandColumnId: expandColumnId$1
+		};
 	}, [
 		schema,
 		overrides,
 		enableRowSelection,
+		enableExpansion,
 		exclude,
-		actions
+		actions,
+		filterOnly
 	]);
 	const stableInitialState = (0, react.useMemo)(() => ({
 		sorting: initialSorting,
 		columnPinning: pinnedColumns ?? {
-			left: enableRowSelection ? ["select"] : [],
+			left: [...enableExpansion ? [expandColumnId] : [], ...enableRowSelection ? ["select"] : []],
 			right: actions ? ["actions"] : []
 		}
 	}), [
 		initialSorting,
 		pinnedColumns,
 		enableRowSelection,
+		enableExpansion,
+		expandColumnId,
 		actions
 	]);
+	const expandedRowModel = (0, react.useMemo)(() => (0, __tanstack_react_table.getExpandedRowModel)(), []);
 	const { table, shallow, debounceMs, throttleMs } = useDataTable({
 		data,
 		columns,
+		getRowId,
+		getRowCanExpand: () => enableExpansion,
+		getExpandedRowModel: enableExpansion ? expandedRowModel : void 0,
 		pageCount,
 		...total !== void 0 ? { rowCount: total } : {},
 		enableAdvancedFilter,
@@ -4465,6 +4531,16 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 		shallow: false,
 		clearOnDefault: true
 	});
+	(0, react.useEffect)(() => {
+		if (!filterOnly?.length) return;
+		table.setColumnVisibility((previous) => {
+			if (filterOnly.every((key) => previous[key] === false)) return previous;
+			return {
+				...previous,
+				...Object.fromEntries(filterOnly.map((key) => [key, false]))
+			};
+		});
+	}, [table, filterOnly]);
 	const rowSelection = table.getState().rowSelection;
 	const columnFilters = table.getState().columnFilters;
 	const selectedRows = (0, react.useMemo)(() => table.getFilteredSelectedRowModel().rows.map((row) => row.original), [
@@ -4579,7 +4655,8 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTable, {
 				pagination,
 				table,
-				classNames
+				classNames,
+				expandedRow
 			}),
 			enableRowSelection && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AutoTableActionBar, {
 				table,
@@ -4905,6 +4982,30 @@ function normalizeHasMore(result) {
 
 //#endregion
 //#region src/lib/field-config.ts
+function mergeFieldPart(base, override) {
+	if (override === void 0) return base;
+	if (override === false || base === false || typeof base !== "object" || typeof override !== "object" || base === null || override === null || Array.isArray(base) || Array.isArray(override)) return override;
+	return {
+		...base,
+		...override
+	};
+}
+function mergeFieldConfig(base, override) {
+	return {
+		...base,
+		...override,
+		enum: override?.enum ?? base?.enum,
+		dataSource: override?.dataSource ?? base?.dataSource,
+		table: mergeFieldPart(base?.table, override?.table),
+		filter: mergeFieldPart(base?.filter, override?.filter),
+		form: mergeFieldPart(base?.form, override?.form)
+	};
+}
+function mergeFields(base, override) {
+	if (!base && !override) return void 0;
+	const keys = new Set([...Object.keys(base ?? {}), ...Object.keys(override ?? {})]);
+	return Object.fromEntries(Array.from(keys).map((key) => [key, mergeFieldConfig(base?.[key], override?.[key])]));
+}
 function normalizeFieldOptions$1(options) {
 	if (!options || options.length === 0) return void 0;
 	return options.map((option) => ({
@@ -6292,7 +6393,6 @@ function resolveActions$1(targetId, zone, ownerActions) {
 	const ownerCustomIds = new Set(ownerActions.flatMap((action$1) => isCustomAction$1(action$1) && action$1.id ? [action$1.id] : []));
 	const baseActions = ownerActions.filter((action$1) => !action$1.hidden && !isMaskedCustom(action$1)).map((action$1) => ({ ...isCustomAction$1(action$1) && action$1.id ? customOverrides.get(action$1.id)?.action ?? action$1 : action$1 }));
 	const isReplacedCustom = ({ action: action$1, seq: seq$1 }) => isCustomAction$1(action$1) && Boolean(action$1.id && (ownerCustomIds.has(action$1.id) || customOverrides.get(action$1.id)?.seq !== seq$1));
-	if (registered.length === 0) return require_position.positionActions(baseActions).map(withoutRegistryMeta);
 	const nextActions = [...baseActions];
 	const extraActions = [];
 	const groups = /* @__PURE__ */ new Map();
@@ -6319,7 +6419,13 @@ function resolveActions$1(targetId, zone, ownerActions) {
 		const items = group.sort((left, right) => left.seq - right.seq).flatMap((entry) => {
 			const { action: action$1 } = entry;
 			if (action$1.hidden || isReplacedCustom(entry)) return [];
-			if (isCustomAction$1(action$1)) return [{ ...action$1 }];
+			if (isCustomAction$1(action$1)) {
+				if (action$1.before) {
+					extraActions.push({ ...action$1 });
+					return [];
+				}
+				return [{ ...action$1 }];
+			}
 			const builtin = nextActions.find((item) => item.type === action$1.type);
 			return builtin ? [builtin] : [];
 		});
@@ -6340,6 +6446,15 @@ function resolveActions$1(targetId, zone, ownerActions) {
 			}
 		} else extraActions.push(...items);
 	}
+	for (const action$1 of [...nextActions, ...extraActions]) {
+		if (!isCustomAction$1(action$1) || !action$1.before) continue;
+		const anchor = nextActions.find((item) => !isCustomAction$1(item) && item.type === action$1.before);
+		if (anchor) action$1.position = {
+			anchor: anchor.id ?? anchor.type,
+			side: "before"
+		};
+		else if (typeof action$1.position === "object") action$1.position = "end";
+	}
 	return require_position.positionActions(nextActions, extraActions).map(withoutRegistryMeta);
 }
 const crudActions = {
@@ -6489,30 +6604,6 @@ function resolveToolbarActionsWithResolver(targetId, ownerActions, context) {
 	const resolver = autoCrudToolbarResolver;
 	return targetId !== void 0 && targetId.length > 0 && resolver !== null ? resolver(targetId, ownerActions, context) : ownerActions;
 }
-function mergeFieldPart(base, override) {
-	if (override === void 0) return base;
-	if (override === false || base === false || typeof base !== "object" || typeof override !== "object" || base === null || override === null || Array.isArray(base) || Array.isArray(override)) return override;
-	return {
-		...base,
-		...override
-	};
-}
-function mergeFieldConfig(base, override) {
-	return {
-		...base,
-		...override,
-		enum: override?.enum ?? base?.enum,
-		dataSource: override?.dataSource ?? base?.dataSource,
-		table: mergeFieldPart(base?.table, override?.table),
-		filter: mergeFieldPart(base?.filter, override?.filter),
-		form: mergeFieldPart(base?.form, override?.form)
-	};
-}
-function mergeFields(base, override) {
-	if (!base && !override) return void 0;
-	const keys = new Set([...Object.keys(base ?? {}), ...Object.keys(override ?? {})]);
-	return Object.fromEntries(Array.from(keys).map((key) => [key, mergeFieldConfig(base?.[key], override?.[key])]));
-}
 function applyResourceTablePresentation(fields, resourceFields) {
 	if (!fields || !resourceFields) return fields;
 	return Object.fromEntries(Object.entries(fields).map(([key, config]) => {
@@ -7414,6 +7505,12 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 	const [exporting, setExporting] = react.useState(false);
 	const getSelectedRowsRef = react.useRef(null);
 	const dynamicFilterOptions = useDynamicFilterOptions(resolvedFields);
+	const filterOnly = react.useMemo(() => Object.entries(resolvedFields).filter(([key, config]) => config.table === false && config.filter && config.hidden !== true && !denyFields?.includes(key) && !tableConfig?.hidden?.includes(key) && tableConfig?.overrides?.[key]?.hidden !== true).map(([key]) => key), [
+		resolvedFields,
+		denyFields,
+		tableConfig?.hidden,
+		tableConfig?.overrides
+	]);
 	const hiddenColumns = react.useMemo(() => buildHiddenColumns(resolvedFields, tableConfig?.hidden, denyFields, tableConfig?.overrides), [
 		resolvedFields,
 		tableConfig?.hidden,
@@ -7502,7 +7599,7 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 			return {
 				...action$1,
 				onClick: (_rows, { table }) => {
-					const headers = table.getAllLeafColumns().map((column) => column.id).filter((key) => key !== "select" && key !== "actions" && !denyFields?.includes(key));
+					const headers = getExportColumnIds(table).filter((key) => key !== "select" && key !== "actions" && !denyFields?.includes(key));
 					exportAllToCSV(table.getFilteredSelectedRowModel().rows.map((row) => formatExportRow(row.original, resolvedFields, Object.fromEntries(headers.map((key) => [key, row.getValue(key)])))), {
 						filename: "table",
 						headers
@@ -7762,9 +7859,12 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 					...pagination
 				} : void 0,
 				...resource.tableData.total !== void 0 ? { total: resource.tableData.total } : {},
+				getRowId: tableConfig?.getRowId,
+				expandedRow: tableConfig?.expandedRow,
 				overrides: tableOverrides,
 				classNames: tableConfig?.classNames,
-				exclude: hiddenColumns,
+				exclude: hiddenColumns.filter((key) => !filterOnly.includes(key)),
+				filterOnly,
 				filterMode: tableConfig?.filterModes,
 				search: searchConfig,
 				actions: tableRowActions,
@@ -8597,7 +8697,7 @@ function modalReducer(state, action$1) {
 /**
 * Hook 主函数
 */
-function useAutoCrudResource({ router, schema, query: queryTransform, options = {} }) {
+function useAutoCrudResource({ router, schema, query: queryTransform, fields, options = {} }) {
 	const { idKey = "id", defaultVariant = "dialog", hooks, toast: toastAdapter, exportFetcher, defaultSort: defaultSortOption } = options;
 	const toast = (0, react.useMemo)(() => toastAdapter === false ? noopToastAdapter : toastAdapter ?? defaultToastAdapter, [toastAdapter]);
 	const hooksRef = (0, react.useRef)(hooks);
@@ -8609,7 +8709,14 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	const defaultSorting = (0, react.useMemo)(() => defaultSortOption === false ? [] : defaultSortOption ?? getDefaultSortingForSchema(resolvedSchema), [defaultSortOption, resolvedSchema]);
 	const metadataFields = (0, react.useMemo)(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
 	const capabilities = metadata?.capabilities;
-	const columns = (0, react.useMemo)(() => createTableSchema(resolvedSchema), [resolvedSchema]);
+	const columns = (0, react.useMemo)(() => createTableSchema(resolvedSchema, { overrides: Object.fromEntries(Object.entries(mergeFields(metadataFields, fields) ?? {}).flatMap(([key, field]) => {
+		const filter = field.filter;
+		return filter && typeof filter === "object" && filter.variant ? [[key, { meta: { variant: filter.variant } }]] : [];
+	})) }), [
+		resolvedSchema,
+		fields,
+		metadataFields
+	]);
 	const [urlParams] = useQueryStates({
 		page: parseAsInteger.withDefault(1),
 		perPage: parseAsInteger.withDefault(10),