@wordrhyme/auto-crud 1.8.2 → 1.9.0

package/README.md

@@ -1651,6 +1651,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 +1719,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

@@ -1012,6 +1012,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) {
@@ -4414,7 +4419,7 @@ 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, 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 }) {
 	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;
@@ -4429,9 +4434,24 @@ 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 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;
 		if (actions) result.push(createActionsColumn(actions));
@@ -4441,7 +4461,8 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 		overrides,
 		enableRowSelection,
 		exclude,
-		actions
+		actions,
+		filterOnly
 	]);
 	const stableInitialState = (0, react.useMemo)(() => ({
 		sorting: initialSorting,
@@ -4465,6 +4486,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), [
@@ -4905,6 +4936,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 +6347,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 +6373,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 +6400,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 +6558,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 +7459,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,
@@ -7764,7 +7815,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 				...resource.tableData.total !== void 0 ? { total: resource.tableData.total } : {},
 				overrides: tableOverrides,
 				classNames: tableConfig?.classNames,
-				exclude: hiddenColumns,
+				exclude: hiddenColumns.filter((key) => !filterOnly.includes(key)),
+				filterOnly,
 				filterMode: tableConfig?.filterModes,
 				search: searchConfig,
 				actions: tableRowActions,
@@ -8597,7 +8649,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 +8661,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),

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { a as positionActions, i as matchesPosition, n as actionPositionSchema, r as compareOrder, t as ActionPosition } from "./position-DoBV7yB6.cjs";
-import * as react_jsx_runtime2 from "react/jsx-runtime";
+import * as react_jsx_runtime4 from "react/jsx-runtime";
 import * as React$1 from "react";
 import * as _tanstack_react_table0 from "@tanstack/react-table";
 import { Column, ColumnDef, ColumnMeta, ColumnSort, Row, RowData, Table, TableOptions, TableState } from "@tanstack/react-table";
@@ -573,6 +573,8 @@ interface UseAutoCrudResourceParams<TSchema extends z.ZodObject<z.ZodRawShape>,
   router: CrudRouter;
   /** Zod schema */
   schema: TSchema;
+  /** Field filter configuration shared with AutoCrudTable. */
+  fields?: Fields;
   /**
    * 查询参数变换函数
    *
@@ -599,6 +601,7 @@ declare function useAutoCrudResource<TSchema extends z.ZodObject<z.ZodRawShape>,
   router,
   schema,
   query: queryTransform,
+  fields,
   options
 }: UseAutoCrudResourceParams<TSchema, TListItem>): UseAutoCrudResourceReturn<TSchema, TListItem>;
 //#endregion
@@ -735,7 +738,7 @@ declare function AutoTableActionBar<TData>({
   extraActions,
   actions,
   deleteConfirmation
-}: AutoTableActionBarProps<TData>): react_jsx_runtime2.JSX.Element;
+}: AutoTableActionBarProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/lib/schema-bridge/types.d.ts
 /**
@@ -856,6 +859,7 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> {
   classNames?: DataTableClassNames;
   enableRowSelection?: boolean;
   exclude?: (keyof z.infer<T>)[];
+  filterOnly?: string[];
   actions?: ActionsColumnConfig<z.infer<T>>;
   /** 自定义固定列配置 */
   pinnedColumns?: {
@@ -908,6 +912,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   classNames,
   enableRowSelection,
   exclude,
+  filterOnly,
   actions,
   pinnedColumns,
   filterMode,
@@ -924,7 +929,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   onSelectedCountChange,
   onSelectedRowsChange,
   getSelectedRows
-}: AutoTableProps<T>): react_jsx_runtime2.JSX.Element;
+}: AutoTableProps<T>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/lib/row-action-dialog.d.ts
 interface RowActionDialogProps {
@@ -1272,6 +1277,8 @@ type RowCustomActionItem<T> = ActionMeta & {
   onClick?: (row: T) => void;
   component?: ActionComponent<AutoCrudRowActionContext<T>>;
   position?: ActionPosition;
+  /** Place a registered custom action before the named builtin, when present. */
+  before?: RowBuiltinActionType;
   separator?: boolean;
   variant?: 'default' | 'destructive';
 };
@@ -1476,7 +1483,7 @@ declare function AutoCrudTable<TSchema extends z.ZodObject<z.ZodRawShape>>({
   toolbarActions,
   locale: localeProp,
   onCreate
-}: AutoCrudTableProps<TSchema>): react_jsx_runtime2.JSX.Element;
+}: AutoCrudTableProps<TSchema>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/auto-form.d.ts
 interface AutoFormProps<T extends z.ZodObject<z.ZodRawShape>> {
@@ -1515,7 +1522,7 @@ declare function AutoFormInner<T extends z.ZodObject<z.ZodRawShape>>({
   labelAlign,
   labelWidth,
   showSubmitButton
-}: AutoFormProps<T>, ref: React.Ref<AutoFormRef>): react_jsx_runtime2.JSX.Element;
+}: AutoFormProps<T>, ref: React.Ref<AutoFormRef>): react_jsx_runtime4.JSX.Element;
 declare const AutoForm: <T extends z.ZodObject<z.ZodRawShape>>(props: AutoFormProps<T> & {
   ref?: React.Ref<AutoFormRef>;
 }) => ReturnType<typeof AutoFormInner>;
@@ -1534,7 +1541,7 @@ declare function AutoTableSimpleFilters<TData>({
   filters: externalFilters,
   onFiltersChange,
   leading
-}: AutoTableSimpleFiltersProps<TData>): react_jsx_runtime2.JSX.Element | null;
+}: AutoTableSimpleFiltersProps<TData>): react_jsx_runtime4.JSX.Element | null;
 //#endregion
 //#region src/components/auto-crud/form-modal.d.ts
 type ModalVariant = 'dialog' | 'sheet';
@@ -1578,7 +1585,7 @@ declare function CrudFormModal<T extends z.ZodObject<z.ZodRawShape>>({
   labelAlign,
   labelWidth,
   className
-}: CrudFormModalProps<T>): react_jsx_runtime2.JSX.Element;
+}: CrudFormModalProps<T>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/import-dialog.d.ts
 interface ImportDialogProps {
@@ -1600,7 +1607,7 @@ declare function ImportDialog({
   columns,
   title,
   locale
-}: ImportDialogProps): react_jsx_runtime2.JSX.Element;
+}: ImportDialogProps): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/export-dialog.d.ts
 type ExportMode = 'selected' | 'filtered';
@@ -1620,7 +1627,7 @@ declare function ExportDialog({
   selectedCount,
   onExport,
   canExportFiltered
-}: ExportDialogProps): react_jsx_runtime2.JSX.Element;
+}: ExportDialogProps): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table.d.ts
 interface DataTableProps<TData> extends React$1.ComponentProps<'div'> {
@@ -1637,7 +1644,7 @@ declare function DataTable<TData>({
   className,
   classNames,
   ...props
-}: DataTableProps<TData>): react_jsx_runtime2.JSX.Element;
+}: DataTableProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-advanced-toolbar.d.ts
 interface DataTableAdvancedToolbarProps<TData> extends React$1.ComponentProps<'div'> {
@@ -1648,7 +1655,7 @@ declare function DataTableAdvancedToolbar<TData>({
   children,
   className,
   ...props
-}: DataTableAdvancedToolbarProps<TData>): react_jsx_runtime2.JSX.Element;
+}: DataTableAdvancedToolbarProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-column-header.d.ts
 interface DataTableColumnHeaderProps<TData, TValue> extends React.ComponentProps<typeof DropdownMenuTrigger> {
@@ -1660,7 +1667,7 @@ declare function DataTableColumnHeader<TData, TValue>({
   label,
   className,
   ...props
-}: DataTableColumnHeaderProps<TData, TValue>): react_jsx_runtime2.JSX.Element;
+}: DataTableColumnHeaderProps<TData, TValue>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-faceted-filter.d.ts
 interface DataTableFacetedFilterProps<TData, TValue> {
@@ -1674,7 +1681,7 @@ declare function DataTableFacetedFilter<TData, TValue>({
   title,
   options,
   multiple
-}: DataTableFacetedFilterProps<TData, TValue>): react_jsx_runtime2.JSX.Element;
+}: DataTableFacetedFilterProps<TData, TValue>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-pagination.d.ts
 interface DataTablePaginationProps<TData> extends React.ComponentProps<'div'>, TablePaginationOptions {
@@ -1690,7 +1697,7 @@ declare function DataTablePagination<TData>({
   pageJumpLabel,
   className,
   ...props
-}: DataTablePaginationProps<TData>): react_jsx_runtime2.JSX.Element;
+}: DataTablePaginationProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-toolbar.d.ts
 interface DataTableToolbarProps<TData> extends React$1.ComponentProps<'div'> {
@@ -1701,7 +1708,7 @@ declare function DataTableToolbar<TData>({
   children,
   className,
   ...props
-}: DataTableToolbarProps<TData>): react_jsx_runtime2.JSX.Element;
+}: DataTableToolbarProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-view-options.d.ts
 interface DataTableViewOptionsProps<TData> extends React$1.ComponentProps<typeof PopoverContent> {
@@ -1712,7 +1719,7 @@ declare function DataTableViewOptions<TData>({
   table,
   disabled,
   ...props
-}: DataTableViewOptionsProps<TData>): react_jsx_runtime2.JSX.Element;
+}: DataTableViewOptionsProps<TData>): react_jsx_runtime4.JSX.Element;
 //#endregion
 //#region src/lib/crud-actions.d.ts
 type CrudActionZone = 'toolbar' | 'row' | 'batch';
@@ -1722,6 +1729,8 @@ type CrudActionBase = {
   order?: number;
   hidden?: boolean;
   position?: ActionPosition;
+  /** Insert a custom action before a builtin action type, if present. */
+  before?: string;
 };
 type CrudActionEntry<TAction extends CrudActionBase = CrudActionBase> = {
   targetId: string;

package/dist/index.d.ts

@@ -573,6 +573,8 @@ interface UseAutoCrudResourceParams<TSchema extends z.ZodObject<z.ZodRawShape>,
   router: CrudRouter;
   /** Zod schema */
   schema: TSchema;
+  /** Field filter configuration shared with AutoCrudTable. */
+  fields?: Fields;
   /**
    * 查询参数变换函数
    *
@@ -599,6 +601,7 @@ declare function useAutoCrudResource<TSchema extends z.ZodObject<z.ZodRawShape>,
   router,
   schema,
   query: queryTransform,
+  fields,
   options
 }: UseAutoCrudResourceParams<TSchema, TListItem>): UseAutoCrudResourceReturn<TSchema, TListItem>;
 //#endregion
@@ -856,6 +859,7 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> {
   classNames?: DataTableClassNames;
   enableRowSelection?: boolean;
   exclude?: (keyof z.infer<T>)[];
+  filterOnly?: string[];
   actions?: ActionsColumnConfig<z.infer<T>>;
   /** 自定义固定列配置 */
   pinnedColumns?: {
@@ -908,6 +912,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   classNames,
   enableRowSelection,
   exclude,
+  filterOnly,
   actions,
   pinnedColumns,
   filterMode,
@@ -1272,6 +1277,8 @@ type RowCustomActionItem<T> = ActionMeta & {
   onClick?: (row: T) => void;
   component?: ActionComponent<AutoCrudRowActionContext<T>>;
   position?: ActionPosition;
+  /** Place a registered custom action before the named builtin, when present. */
+  before?: RowBuiltinActionType;
   separator?: boolean;
   variant?: 'default' | 'destructive';
 };
@@ -1722,6 +1729,8 @@ type CrudActionBase = {
   order?: number;
   hidden?: boolean;
   position?: ActionPosition;
+  /** Insert a custom action before a builtin action type, if present. */
+  before?: string;
 };
 type CrudActionEntry<TAction extends CrudActionBase = CrudActionBase> = {
   targetId: string;

package/dist/index.js

@@ -997,6 +997,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) {
@@ -4399,7 +4404,7 @@ 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, 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 }) {
 	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;
@@ -4414,9 +4419,24 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 	const searchConfig = search && typeof search === "object" ? search : {};
 	const enableAdvancedFilter = true;
 	const columns = 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;
 		if (actions) result.push(createActionsColumn(actions));
@@ -4426,7 +4446,8 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 		overrides,
 		enableRowSelection,
 		exclude,
-		actions
+		actions,
+		filterOnly
 	]);
 	const stableInitialState = useMemo(() => ({
 		sorting: initialSorting,
@@ -4450,6 +4471,16 @@ function AutoTable({ schema, data, pageCount = 1, pagination, total, overrides,
 		shallow: false,
 		clearOnDefault: true
 	});
+	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 = useMemo(() => table.getFilteredSelectedRowModel().rows.map((row) => row.original), [
@@ -4890,6 +4921,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) => ({
@@ -6277,7 +6332,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 positionActions(baseActions).map(withoutRegistryMeta);
 	const nextActions = [...baseActions];
 	const extraActions = [];
 	const groups = /* @__PURE__ */ new Map();
@@ -6304,7 +6358,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] : [];
 		});
@@ -6325,6 +6385,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 positionActions(nextActions, extraActions).map(withoutRegistryMeta);
 }
 const crudActions = {
@@ -6474,30 +6543,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]) => {
@@ -7399,6 +7444,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,
@@ -7749,7 +7800,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 				...resource.tableData.total !== void 0 ? { total: resource.tableData.total } : {},
 				overrides: tableOverrides,
 				classNames: tableConfig?.classNames,
-				exclude: hiddenColumns,
+				exclude: hiddenColumns.filter((key) => !filterOnly.includes(key)),
+				filterOnly,
 				filterMode: tableConfig?.filterModes,
 				search: searchConfig,
 				actions: tableRowActions,
@@ -8582,7 +8634,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$1 = useMemo(() => toastAdapter === false ? noopToastAdapter : toastAdapter ?? defaultToastAdapter, [toastAdapter]);
 	const hooksRef = useRef(hooks);
@@ -8594,7 +8646,14 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	const defaultSorting = useMemo(() => defaultSortOption === false ? [] : defaultSortOption ?? getDefaultSortingForSchema(resolvedSchema), [defaultSortOption, resolvedSchema]);
 	const metadataFields = useMemo(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
 	const capabilities = metadata?.capabilities;
-	const columns = useMemo(() => createTableSchema(resolvedSchema), [resolvedSchema]);
+	const columns = 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),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud",
   "type": "module",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Schema-first CRUD components with auto-generated tables and forms",
   "author": "wordrhyme",
   "license": "MIT",
@@ -71,8 +71,8 @@
     "tailwind-merge": "^3.5.0",
     "vaul": "^1.1.2",
     "@wordrhyme/shadcn": "2.0.1",
-    "@wordrhyme/formily-shadcn": "2.1.1",
-    "@wordrhyme/shadcn-ui": "2.1.1"
+    "@wordrhyme/shadcn-ui": "2.1.1",
+    "@wordrhyme/formily-shadcn": "2.1.1"
   },
   "devDependencies": {
     "@storybook/react": "^8.6.18",
@@ -93,11 +93,11 @@
     "tsdown": "^0.15.12",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@internal/tsconfig": "0.1.0",
     "@internal/prettier-config": "0.0.1",
-    "@internal/eslint-config": "0.3.0",
     "@internal/tsdown-config": "0.1.0",
-    "@internal/vitest-config": "0.1.0"
+    "@internal/tsconfig": "0.1.0",
+    "@internal/vitest-config": "0.1.0",
+    "@internal/eslint-config": "0.3.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {