@chelone/core 0.10.0 → 0.11.0

package/dist/block-editor/block-document.d.ts

@@ -45,7 +45,7 @@ export declare function getBlockDefaultAttrs<A extends Attrs>(schema: BlockSchem
     [K in keyof A]: A[K] | null;
 };
 /** One descriptor per attr, for an adapter to build the block's config form from. */
-export declare function describeBlockAttrs(schema: BlockSchema<Attrs>): FieldDescriptor[];
+export declare function describeBlockAttrs(schema: BlockSchema<Attrs>): FieldDescriptor<string>[];
 export declare function matchBlocks<B extends BlockSpec>(blocks: readonly B[], query: string): B[];
 /**
  * Wraps each node of an unknown type in an `unknownBlock`, so the editor keeps

package/dist/controller/calendar-events.d.ts

@@ -1,4 +1,6 @@
-import type { SourcePath } from "../resource/source-path.js";
+import type { FilterPayload } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
+import type { FilterSourceKey, SourcePath } from "../resource/source-path.js";
 import { type CalendarRange } from "./calendar-dates.js";
 export interface CalendarEvent<R> {
     record: R;
@@ -45,11 +47,11 @@ export declare function moveCalendarEvent<R>(event: CalendarEvent<R>, fromDay: D
  * began earlier and runs into the range is fetched; a record with an empty end
  * is then left out. Without one, only the start is bounded, on both sides.
  */
-export declare function calendarRangeFilter(startSource: string, range: CalendarRange, endSource?: string): Record<string, string>;
+export declare function calendarRangeFilter<R = LooseRecord>(startSource: SourcePath<R>, range: CalendarRange, endSource?: SourcePath<R>): FilterPayload<R>;
 /**
  * Keys an earlier default filter wrote that the current one no longer does: a
  * list URL or store can still hold the start's lower bound, which would hide
  * the event that starts before the range.
  */
-export declare function staleCalendarRangeKeys(startSource: string, endSource?: string): string[];
-export declare function omitCalendarRangeFilter(filter: Record<string, unknown>, startSource: string, endSource?: string): Record<string, unknown>;
+export declare function staleCalendarRangeKeys<R = LooseRecord>(startSource: SourcePath<R>, endSource?: SourcePath<R>): FilterSourceKey<R>[];
+export declare function omitCalendarRangeFilter<R = LooseRecord>(filter: FilterPayload<R>, startSource: SourcePath<R>, endSource?: SourcePath<R>): FilterPayload<R>;

package/dist/controller/calendar-events.js

@@ -84,11 +84,10 @@ function moveCalendarEvent(event, fromDay, toDay) {
 * is then left out. Without one, only the start is bounded, on both sides.
 */
 function calendarRangeFilter(startSource, range, endSource) {
-	if (endSource) return {
+	return endSource ? {
 		[`${startSource}_lte`]: range.end.toISOString(),
 		[`${endSource}_gte`]: range.start.toISOString()
-	};
-	return {
+	} : {
 		[`${startSource}_gte`]: range.start.toISOString(),
 		[`${startSource}_lte`]: range.end.toISOString()
 	};

package/dist/controller/client-list-controller.d.ts

@@ -11,9 +11,9 @@ export interface ClientListControllerOptions<TRecord> {
     /** The in-memory records. `undefined` = not-yet-loaded (data/total stay undefined). */
     data?: TRecord[];
     /** Initial user filter. */
-    filter?: FilterPayload;
+    filter?: FilterPayload<TRecord>;
     /** Initial sort. Single payload or an array (multi-sort is normalized to an array). */
-    sort?: SortPayload | SortPayload[];
+    sort?: SortPayload<TRecord> | SortPayload<TRecord>[];
     /** Initial page (1-based). Default 1. */
     page?: number;
     /** Page size. Default 1000 (ra-core `useList` default — "show everything"). */
@@ -45,7 +45,7 @@ export interface ClientListController<TRecord> extends ListController<TRecord> {
     /** Replace the source records (external `data` prop change) and recompute. */
     setData(data: TRecord[] | undefined): void;
     /** Replace the user filter from the `filter` prop (external change) and recompute. */
-    setSourceFilter(filter: FilterPayload): void;
+    setSourceFilter(filter: FilterPayload<TRecord>): void;
     /**
      * Push external loading-flag changes (async source feeding a client list).
      * An `isPending` transition re-runs the derived-slice recompute so data

package/dist/controller/client-list-controller.js

@@ -2,14 +2,10 @@ import { isFilterBranch } from "../data/filter-branch.js";
 import { removeEmpty } from "../data/remove-empty.js";
 import { getAtPath } from "../resource/get-at-path.js";
 import { createMicroStore } from "../store/micro-store.js";
-import { listParamsFromPatch, removeFilterPath } from "./list-controller.js";
+import { listParamsFromPatch, nextSortOf, normalizeSort, removeDisplayedFilter, removeFilterPath } from "./list-controller.js";
 // src/controller/client-list-controller.ts
 var DEFAULT_PER_PAGE = 1e3;
 var DEFAULT_SORT = [];
-function normalizeSort(sort) {
-	if (!sort) return DEFAULT_SORT.map((entry) => ({ ...entry }));
-	return (Array.isArray(sort) ? sort : [sort]).map((entry) => ({ ...entry }));
-}
 /**
 * Flatten a nested filter object into dotted keys (`{nested:{level:5}}` →
 * `{'nested.level':5}`), matching ra-core's `flattenObject`. Arrays and
@@ -75,7 +71,7 @@ function createClientListController(options) {
 	const store = createMicroStore({
 		page: options.page ?? 1,
 		perPage: options.perPage ?? DEFAULT_PER_PAGE,
-		sort: normalizeSort(options.sort),
+		sort: normalizeSort(options.sort, DEFAULT_SORT),
 		filter: removeEmpty(options.filter ?? {}),
 		displayedFilters: {},
 		selectedIds: [],
@@ -134,20 +130,8 @@ function createClientListController(options) {
 	};
 	const setSort = (input) => {
 		if (destroyed) return;
-		const current = store.getSnapshot().sort;
-		const single = current.length === 1 ? current[0] : void 0;
-		let next;
-		if (Array.isArray(input)) next = input.map((entry) => ({ ...entry }));
-		else if (single && single.field === input.field) next = [{
-			field: input.field,
-			order: single.order === "ASC" ? "DESC" : "ASC"
-		}];
-		else next = [{
-			field: input.field,
-			order: input.order ?? "ASC"
-		}];
 		store.setState({
-			sort: next,
+			sort: nextSortOf(store.getSnapshot().sort, input),
 			page: 1
 		});
 		recompute();
@@ -187,7 +171,7 @@ function createClientListController(options) {
 		if (destroyed) return;
 		const s = store.getSnapshot();
 		const filter = removeFilterPath(s.filter, name);
-		const { [name]: _shown, ...displayedFilters } = s.displayedFilters;
+		const displayedFilters = removeDisplayedFilter(s.displayedFilters, name);
 		store.setState({
 			filter,
 			displayedFilters,

package/dist/controller/filter-toggle.d.ts

@@ -5,13 +5,13 @@
  * Chelone divergence: arrays compare for deep equality, not lodash's
  * contains-all rule.
  */
-type Filters = Record<string, unknown>;
+import type { FilterPayload } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
 /** True when every defined key of `value` is held by `filters`. */
-export declare function isFilterSelected(value: Filters, filters: Filters): boolean;
+export declare function isFilterSelected<TRecord = LooseRecord>(value: FilterPayload<TRecord>, filters: FilterPayload<TRecord>): boolean;
 /**
  * Selecting a value merges it into the filters; toggling a selected one drops
  * the keys it holds, down to nested sub-keys, and keeps the rest. Neither
  * argument is mutated.
  */
-export declare function toggleFilterValue(value: Filters, filters: Filters): Filters;
-export {};
+export declare function toggleFilterValue<TRecord = LooseRecord>(value: FilterPayload<TRecord>, filters: FilterPayload<TRecord>): FilterPayload<TRecord>;

package/dist/controller/filter-toggle.js

@@ -1,13 +1,6 @@
 import { isPlainObject } from "../guards.js";
 import { deepEqual } from "./deep-equal.js";
 // src/controller/filter-toggle.ts
-/**
-* The select and toggle rules behind a one-click list filter (ra-core's
-* `FilterListItem` and `ToggleFilterButton`), pure so both adapters share them.
-*
-* Chelone divergence: arrays compare for deep equality, not lodash's
-* contains-all rule.
-*/
 function matches(expected, actual) {
 	if (isPlainObject(expected)) return isPlainObject(actual) && Object.keys(expected).every((key) => expected[key] === void 0 || matches(expected[key], actual[key]));
 	return deepEqual(expected, actual);

package/dist/controller/in-place-editor.d.ts

@@ -40,4 +40,4 @@ export interface InPlaceSave<R extends ResourceRecord> {
  * then typed back is dropped. Returns `null` when nothing changed, so a save
  * with no change makes no call.
  */
-export declare function planInPlaceSave<R extends ResourceRecord>(record: R, dirty: Record<string, unknown>): InPlaceSave<R> | null;
+export declare function planInPlaceSave<R extends ResourceRecord>(record: R, dirty: Partial<NoInfer<R>>): InPlaceSave<R> | null;

package/dist/controller/infinite-list-controller.d.ts

@@ -28,4 +28,4 @@ export interface InfiniteListController<TRecord> extends MicroStore<InfiniteList
  * out-of-range page reset of the list controller does not apply: the inner
  * controller reads a private empty cache, so no result can trigger it.
  */
-export declare function createInfiniteListController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, resource: TName, options?: ListControllerOptions): InfiniteListController<RecordOf<TResources, TName>>;
+export declare function createInfiniteListController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, resource: TName, options?: ListControllerOptions<RecordOf<TResources, TName>>): InfiniteListController<RecordOf<TResources, TName>>;

package/dist/controller/kanban-board.d.ts

@@ -8,7 +8,7 @@
  * beside {@link moveCalendarEvent}.
  */
 import type { Identifier } from "../resource/identifier.js";
-import type { ResourceRecord } from "../resource/record.js";
+import type { LooseRecord, ResourceRecord } from "../resource/record.js";
 import type { SourceKey } from "../resource/source-path.js";
 export interface KanbanColumnDef {
     /** Value written to `groupSource` by a drop into this column. */
@@ -25,9 +25,11 @@ export interface KanbanBucket<R> {
  * and `previousData` the record as it was, so an adapter can undo the drop
  * without a second read.
  */
-export interface KanbanMove<R> {
+export interface KanbanMove<R = LooseRecord> {
     id: Identifier;
-    data: Record<string, string>;
+    data: {
+        [K in SourceKey<R>]?: string;
+    };
     previousData: R;
 }
 /**

package/dist/controller/list-controller.d.ts

@@ -1,18 +1,19 @@
 import { type DataContext } from "../data/query-options.js";
-import type { FilterPayload, PageInfo, SortPayload } from "../data/types.js";
+import type { DisplayedFilters, FilterPayload, LooseDisplayedFilters, LooseFilterPayload, LooseSortPayload, PageInfo, SortPayload } from "../data/types.js";
 import type { NotificationStore } from "../notification/notification-store.js";
 import type { Identifier } from "../resource/identifier.js";
-import type { ResourceRecord } from "../resource/record.js";
+import type { LooseRecord, ResourceRecord } from "../resource/record.js";
 import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { RecordFilterKey } from "../resource/source-path.js";
 import { type MicroStore } from "../store/micro-store.js";
 import type { CheloneStore } from "../store/store.js";
-export interface ListControllerState<TRecord> {
+export interface ListControllerState<TRecord = LooseRecord> {
     page: number;
     perPage: number;
     /** Always an array in controller state — multi-sort is first-class. */
-    sort: SortPayload[];
-    filter: FilterPayload;
-    displayedFilters: Record<string, boolean>;
+    sort: SortPayload<TRecord>[];
+    filter: FilterPayload<TRecord>;
+    displayedFilters: DisplayedFilters<TRecord>;
     selectedIds: Identifier[];
     data: TRecord[] | undefined;
     total: number | undefined;
@@ -28,28 +29,87 @@ export interface ListControllerState<TRecord> {
  * write and one query reconfiguration. Every key is optional; an omitted key
  * stays as it is.
  */
-export interface ListParamsPatch {
+export interface ListParamsPatch<TRecord = LooseRecord> {
     /** Replaces the user filter; empty values are stripped. */
-    filter?: FilterPayload;
-    displayedFilters?: Record<string, boolean>;
+    filter?: FilterPayload<TRecord>;
+    displayedFilters?: DisplayedFilters<TRecord>;
     /** Replaces wholesale; a single payload never toggles the order. */
-    sort?: SortPayload | SortPayload[];
+    sort?: SortPayload<TRecord> | SortPayload<TRecord>[];
     perPage?: number;
     /** Defaults to 1 when the patch holds `filter`, `sort` or `perPage`. */
     page?: number;
 }
+/**
+ * A {@link ListParamsPatch} with the record type erased: the filter and the
+ * displayed filters are open key maps and the sort an open field name. Each
+ * adapter's list context carries this, because a context cannot be generic and
+ * a controller typed to any record must mount in one.
+ *
+ * Written as `Omit` plus fresh `filter`, `displayedFilters` and `sort`, not as
+ * `ListParamsPatch` itself:
+ * TypeScript compares two instantiations of one generic interface by the
+ * variance of their type argument, so a `ListParamsPatch<Post>` never reaches
+ * `ListParamsPatch<LooseRecord>` however the fields read. As a separate type
+ * the two line up field by field.
+ */
+export type LooseListParamsPatch = Omit<ListParamsPatch, "filter" | "sort" | "displayedFilters"> & {
+    filter?: LooseFilterPayload;
+    displayedFilters?: LooseDisplayedFilters;
+    sort?: LooseSortPayload | LooseSortPayload[];
+};
+/**
+ * A list controller's state and actions, without the micro-store plumbing each
+ * adapter re-binds through its own reactive seam (`useSyncExternalStore` in
+ * React, `useMicroStore` in Vue).
+ */
+export type ListControllerSurface<TRecord> = ListControllerState<TRecord> & Omit<ListController<TRecord>, keyof MicroStore<ListControllerState<TRecord>>>;
+/**
+ * The list surface an adapter's list context publishes: the rows typed to
+ * `TRecord`, the filter and the displayed filters open key maps.
+ *
+ * The sort is as open as the filter, for the same reason: a column header or a
+ * URL names a field with no record to check it, so `sort` and `setSort` take
+ * the structural {@link LooseSortPayload}: a `SortPayload<Post>` never reaches
+ * `SortPayload<LooseRecord>` by variance, as with {@link LooseListParamsPatch}.
+ * A record's own sort fields are the job of
+ * {@link ListController.setSort} and the options of each controller.
+ *
+ * The filter is open on purpose. What writes a context filter names no record:
+ * a filter form's field names, a calendar's range keys, a URL query. A record's
+ * own filter keys are the job of {@link ListController.setFilters} and the
+ * hooks, which are generic over the record. Erasing the filter is what lets a
+ * controller typed to any record be mounted in one context.
+ *
+ * The displayed filters and the two actions that move them are open for the
+ * same reason, and they must be erased together with it: a filter input names
+ * its filter by a plain `source` (`FilterElementProps` in React's filter form),
+ * so a context keyed by the record would stop every filter input compiling in a
+ * registered app.
+ */
+export type ListContextSurface<TRecord = ResourceRecord> = Omit<ListControllerSurface<TRecord>, "filter" | "setFilters" | "setParams" | "sort" | "setSort" | "displayedFilters" | "showFilter" | "hideFilter"> & {
+    sort: LooseSortPayload[];
+    setSort(sort: LooseSortPayload | LooseSortPayload[]): void;
+    filter: LooseFilterPayload;
+    displayedFilters: LooseDisplayedFilters;
+    setFilters(filter: LooseFilterPayload, displayedFilters?: LooseDisplayedFilters, debounced?: boolean): void;
+    setParams(patch: LooseListParamsPatch): void;
+    showFilter(name: string, defaultValue?: unknown): void;
+    hideFilter(name: string): void;
+};
 export interface ListController<TRecord> extends MicroStore<ListControllerState<TRecord>> {
     /** The `perPage` the list starts at when nothing is persisted or in the URL. Optional so other list controllers and fakes need not set it. */
     readonly defaultPerPage?: number;
     setPage(page: number): void;
     setPerPage(perPage: number): void;
     /** Single payload on the SAME single-sorted field toggles order; anything else replaces. */
-    setSort(sort: SortPayload | SortPayload[]): void;
-    setFilters(filter: FilterPayload, displayedFilters?: Record<string, boolean>, debounced?: boolean): void;
+    setSort(sort: SortPayload<TRecord> | SortPayload<TRecord>[]): void;
+    setFilters(filter: FilterPayload<TRecord>, displayedFilters?: DisplayedFilters<TRecord>, debounced?: boolean): void;
     /** Applies a {@link ListParamsPatch} as one change (one persisted write, one query update; a fetch only if the query changes). An empty patch does nothing. Never debounced. */
-    setParams(patch: ListParamsPatch): void;
-    showFilter(name: string, defaultValue?: unknown): void;
-    hideFilter(name: string): void;
+    setParams(patch: ListParamsPatch<TRecord>): void;
+    /** Shows the filter input `name`, and writes `{ [name]: defaultValue }` into the filter when a default is given. */
+    showFilter(name: RecordFilterKey<TRecord>, defaultValue?: unknown): void;
+    /** Hides the filter input `name` and removes that path from the filter. */
+    hideFilter(name: RecordFilterKey<TRecord>): void;
     select(ids: Identifier[]): void;
     toggleItem(id: Identifier): void;
     unselectAll(): void;
@@ -63,13 +123,13 @@ export interface ListControllerContext<TResources extends ResourceMap = Resource
     notifications?: NotificationStore;
     translate?: (key: string) => string;
 }
-export interface ListControllerOptions {
+export interface ListControllerOptions<TRecord = LooseRecord> {
     perPage?: number;
-    sort?: SortPayload | SortPayload[];
+    sort?: SortPayload<TRecord> | SortPayload<TRecord>[];
     /** Permanent filter — merged OVER the user filter for every fetch. */
-    filter?: FilterPayload;
+    filter?: FilterPayload<TRecord>;
     /** Seed for the user filter when nothing is persisted. */
-    filterDefaultValues?: FilterPayload;
+    filterDefaultValues?: FilterPayload<TRecord>;
     /** Debounce delay for `setFilters(..., debounced=true)`. Default 500ms. */
     debounceMs?: number;
     /** KV namespace for params/selection persistence. Default: the resource name. `false` disables persistence. */
@@ -81,17 +141,34 @@ export declare const DEFAULT_PER_PAGE = 10;
 /** Debounce delay for `setFilters(..., debounced=true)` when no `debounceMs` option is given. Shared with the reference-many and choices controllers. */
 export declare const DEFAULT_DEBOUNCE_MS = 500;
 export declare const DEFAULT_SELECT_ALL_LIMIT = 250;
+/**
+ * A sort prop as controller state: always an array, always a fresh copy, so a
+ * caller's payload is never the object the controller holds. `fallback` is what
+ * an absent sort becomes. Shared with the client controller.
+ */
+export declare function normalizeSort<TRecord>(sort: SortPayload<TRecord> | SortPayload<TRecord>[] | undefined, fallback: SortPayload<TRecord>[]): SortPayload<TRecord>[];
+/**
+ * The sort a `setSort` input produces: a single payload on the SAME
+ * single-sorted field toggles its order (ra-core column-header semantics);
+ * anything else replaces. Shared with the client controller.
+ */
+export declare function nextSortOf<TRecord>(current: SortPayload<TRecord>[], input: SortPayload<TRecord> | SortPayload<TRecord>[]): SortPayload<TRecord>[];
 /**
  * Returns `filter` without the value at `path`: the flat key of that name and,
  * for a dotted path, the nested value, pruning parents it leaves empty. Never
  * mutates `filter`. Shared with the client controller.
  */
-export declare function removeFilterPath(filter: FilterPayload, path: string): FilterPayload;
+export declare function removeFilterPath<TRecord = LooseRecord>(filter: FilterPayload<TRecord>, path: string): FilterPayload<TRecord>;
+/**
+ * The displayed filters without the entry named `name`: always a fresh copy,
+ * never the map it was given. Shared with the client controller.
+ */
+export declare function removeDisplayedFilter<TRecord = LooseRecord>(displayedFilters: DisplayedFilters<TRecord>, name: RecordFilterKey<TRecord>): DisplayedFilters<TRecord>;
 /**
  * Turns a {@link ListParamsPatch} into the state slice it changes. Shared with
  * the client controller so the page-reset rule lives in one place.
  */
-export declare function listParamsFromPatch<TRecord>(patch: ListParamsPatch): Partial<Pick<ListControllerState<TRecord>, "page" | "perPage" | "sort" | "filter" | "displayedFilters">>;
+export declare function listParamsFromPatch<TRecord>(patch: ListParamsPatch<TRecord>): Partial<Pick<ListControllerState<TRecord>, "page" | "perPage" | "sort" | "filter" | "displayedFilters">>;
 /** The notification key for a failed fetch: the error's own message, else `chelone.notification.http_error`. */
 export declare function errorMessageKey(error: unknown): string;
 /** Notifies a failed fetch under its message, falling back to the generic http error. */
@@ -145,14 +222,14 @@ export declare function resetPageTarget(s: Pick<ListControllerState<ResourceReco
  * The actions of a list controller, for an adapter to spread next to its own
  * reactive state. They are the same functions across state changes.
  */
-export declare function listControllerActions(controller: Omit<ListController<ResourceRecord>, keyof MicroStore<ListControllerState<ResourceRecord>> | "defaultPerPage">): {
+export declare function listControllerActions<TRecord>(controller: Omit<ListController<TRecord>, keyof MicroStore<ListControllerState<TRecord>> | "defaultPerPage">): {
     setPage: (page: number) => void;
     setPerPage: (perPage: number) => void;
-    setSort: (sort: SortPayload | SortPayload[]) => void;
-    setFilters: (filter: FilterPayload, displayedFilters?: Record<string, boolean>, debounced?: boolean) => void;
-    setParams: (patch: ListParamsPatch) => void;
-    showFilter: (name: string, defaultValue?: unknown) => void;
-    hideFilter: (name: string) => void;
+    setSort: (sort: SortPayload<TRecord> | SortPayload<TRecord>[]) => void;
+    setFilters: (filter: FilterPayload<TRecord>, displayedFilters?: DisplayedFilters<TRecord> | undefined, debounced?: boolean) => void;
+    setParams: (patch: ListParamsPatch<TRecord>) => void;
+    showFilter: (name: RecordFilterKey<TRecord>, defaultValue?: unknown) => void;
+    hideFilter: (name: RecordFilterKey<TRecord>) => void;
     select: (ids: Identifier[]) => void;
     toggleItem: (id: Identifier) => void;
     unselectAll: () => void;
@@ -161,4 +238,4 @@ export declare function listControllerActions(controller: Omit<ListController<Re
     }) => Promise<void>;
     refetch: () => void;
 };
-export declare function createListController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, resource: TName, options?: ListControllerOptions): ListController<RecordOf<TResources, TName>>;
+export declare function createListController<TResources extends ResourceMap, TName extends keyof TResources & string>(ctx: ListControllerContext<TResources>, resource: TName, options?: ListControllerOptions<RecordOf<TResources, TName>>): ListController<RecordOf<TResources, TName>>;

package/dist/controller/list-controller.js

@@ -8,44 +8,98 @@ import { QueryObserver } from "@tanstack/query-core";
 var DEFAULT_PER_PAGE = 10;
 /** Debounce delay for `setFilters(..., debounced=true)` when no `debounceMs` option is given. Shared with the reference-many and choices controllers. */
 var DEFAULT_DEBOUNCE_MS = 500;
-var DEFAULT_SORT = [{
-	field: "id",
-	order: "ASC"
-}];
+/**
+* The sort a list starts on: `id` ascending, as it always was. This is the one
+* cast this change adds. A schema is not required to declare `id`, so a record
+* this generic cannot prove carries the path; a resource without one still sends
+* `id` to its provider, exactly as before the sort was keyed by the record.
+*/
+function defaultSort() {
+	return [{
+		field: "id",
+		order: "ASC"
+	}];
+}
+/**
+* A sort prop as controller state: always an array, always a fresh copy, so a
+* caller's payload is never the object the controller holds. `fallback` is what
+* an absent sort becomes. Shared with the client controller.
+*/
 function normalizeSort(sort, fallback) {
 	if (!sort) return fallback.map((entry) => ({ ...entry }));
 	return (Array.isArray(sort) ? sort : [sort]).map((entry) => ({ ...entry }));
 }
 /**
+* The sort a `setSort` input produces: a single payload on the SAME
+* single-sorted field toggles its order (ra-core column-header semantics);
+* anything else replaces. Shared with the client controller.
+*/
+function nextSortOf(current, input) {
+	if (Array.isArray(input)) return input.map((entry) => ({ ...entry }));
+	const single = current.length === 1 ? current[0] : void 0;
+	if (single && single.field === input.field) return [{
+		field: input.field,
+		order: single.order === "ASC" ? "DESC" : "ASC"
+	}];
+	return [{
+		field: input.field,
+		order: input.order ?? "ASC"
+	}];
+}
+/**
+* `branch` with the dotted `keys` removed from `depth` on: every branch it
+* rebuilds is a copy, and it returns `branch` itself when nothing under it
+* changed, so the caller can tell "untouched" from "pruned".
+*/
+function pruneFilterBranch(branch, keys, depth) {
+	const key = keys[depth];
+	if (key === void 0) return branch;
+	const child = branch[key];
+	if (depth === keys.length - 1) {
+		const { [key]: _removed, ...others } = branch;
+		return others;
+	}
+	if (!isRecord(child)) return branch;
+	const pruned = pruneFilterBranch(child, keys, depth + 1);
+	if (pruned === child) return branch;
+	if (Object.keys(pruned).length === 0) {
+		const { [key]: _emptied, ...others } = branch;
+		return others;
+	}
+	return {
+		...branch,
+		[key]: pruned
+	};
+}
+/**
 * Returns `filter` without the value at `path`: the flat key of that name and,
 * for a dotted path, the nested value, pruning parents it leaves empty. Never
 * mutates `filter`. Shared with the client controller.
 */
 function removeFilterPath(filter, path) {
-	const { [path]: _flat, ...rest } = filter;
+	const result = { ...filter };
+	const pruned = result;
+	delete pruned[path];
 	const keys = path.split(".");
-	if (keys.length === 1) return rest;
-	const prune = (node, depth) => {
-		const key = keys[depth];
-		if (key === void 0) return node;
-		const child = node[key];
-		if (depth === keys.length - 1) {
-			const { [key]: _removed, ...others } = node;
-			return others;
-		}
-		if (!isRecord(child)) return node;
-		const pruned = prune(child, depth + 1);
-		if (pruned === child) return node;
-		if (Object.keys(pruned).length === 0) {
-			const { [key]: _emptied, ...others } = node;
-			return others;
-		}
-		return {
-			...node,
-			[key]: pruned
-		};
-	};
-	return prune(rest, 0);
+	const [head] = keys;
+	if (head === void 0 || keys.length === 1) return result;
+	const branch = pruned[head];
+	if (!isRecord(branch)) return result;
+	const kept = pruneFilterBranch(branch, keys, 1);
+	if (kept === branch) return result;
+	if (Object.keys(kept).length === 0) delete pruned[head];
+	else pruned[head] = kept;
+	return result;
+}
+/**
+* The displayed filters without the entry named `name`: always a fresh copy,
+* never the map it was given. Shared with the client controller.
+*/
+function removeDisplayedFilter(displayedFilters, name) {
+	const kept = { ...displayedFilters };
+	const open = kept;
+	delete open[name];
+	return kept;
 }
 /**
 * Turns a {@link ListParamsPatch} into the state slice it changes. Shared with
@@ -192,7 +246,7 @@ function createListController(ctx, resource, options = {}) {
 	const defaults = {
 		page: 1,
 		perPage: options.perPage ?? 10,
-		sort: normalizeSort(options.sort, DEFAULT_SORT),
+		sort: normalizeSort(options.sort, defaultSort()),
 		filter: { ...options.filterDefaultValues ?? {} },
 		displayedFilters: {}
 	};
@@ -277,20 +331,8 @@ function createListController(ctx, resource, options = {}) {
 	};
 	const setSort = (input) => {
 		if (destroyed) return;
-		const current = store.getSnapshot().sort;
-		const single = current.length === 1 ? current[0] : void 0;
-		let next;
-		if (Array.isArray(input)) next = input.map((entry) => ({ ...entry }));
-		else if (single && single.field === input.field) next = [{
-			field: input.field,
-			order: single.order === "ASC" ? "DESC" : "ASC"
-		}];
-		else next = [{
-			field: input.field,
-			order: input.order ?? "ASC"
-		}];
 		applyParams({
-			sort: next,
+			sort: nextSortOf(store.getSnapshot().sort, input),
 			page: 1
 		});
 	};
@@ -356,7 +398,7 @@ function createListController(ctx, resource, options = {}) {
 		const pending = pendingFilters;
 		clearDebounce();
 		const filter = removeFilterPath(pending ? removeEmpty(pending.filter) : s.filter, name);
-		const { [name]: _shown, ...displayedFilters } = pending?.displayedFilters ?? s.displayedFilters;
+		const displayedFilters = removeDisplayedFilter(pending?.displayedFilters ?? s.displayedFilters, name);
 		applyParams({
 			filter,
 			displayedFilters,
@@ -469,4 +511,4 @@ function createListController(ctx, resource, options = {}) {
 		refetch
 	};
 }
-export { DEFAULT_DEBOUNCE_MS, DEFAULT_PER_PAGE, createErrorAnnouncer, createListController, errorMessageKey, listControllerActions, listParamsFromPatch, notifyFetchError, notifySelectAllLimit, pageFlags, removeFilterPath, resetPageTarget, runSelectAll };
+export { DEFAULT_DEBOUNCE_MS, DEFAULT_PER_PAGE, createErrorAnnouncer, createListController, errorMessageKey, listControllerActions, listParamsFromPatch, nextSortOf, normalizeSort, notifyFetchError, notifySelectAllLimit, pageFlags, removeDisplayedFilter, removeFilterPath, resetPageTarget, runSelectAll };

package/dist/controller/list-params.d.ts

@@ -15,17 +15,20 @@
  * {@link serializeListState} and {@link listPatchFromSearch} map between the
  * two (primary key) for the adapters' location sync.
  */
-import type { FilterPayload, SortPayload } from "../data/types.js";
+import type { DisplayedFilters, FilterPayload, SortPayload } from "../data/types.js";
+import type { LooseRecord } from "../resource/record.js";
 import type { ListParamsPatch } from "./list-controller.js";
 type SortOrder = "ASC" | "DESC";
 /**
  * The URL-shaped list params. A flat mirror of the query string: `sort` is the
  * field name and `order` its direction (not a `SortPayload`), so this maps 1:1
  * onto the wire format. Every field is optional — absent means "not in the URL".
+ * `TRecord` keys `filter` and `displayedFilters`: a parse hands back what the
+ * URL names, and a list hands it to its own controller.
  */
-export interface ListParamsQuery {
-    filter?: FilterPayload;
-    displayedFilters?: Record<string, boolean>;
+export interface ListParamsQuery<TRecord = LooseRecord> {
+    filter?: FilterPayload<TRecord>;
+    displayedFilters?: DisplayedFilters<TRecord>;
     sort?: string;
     order?: SortOrder;
     page?: number;
@@ -36,7 +39,7 @@ export interface ListParamsQuery {
  * or `''` when no field is set). Only defined fields are emitted; `filter` and
  * `displayedFilters` are JSON-encoded (an empty object serializes as `{}`).
  */
-export declare function serializeListParams(params: ListParamsQuery): string;
+export declare function serializeListParams<TRecord = LooseRecord>(params: ListParamsQuery<TRecord>): string;
 /**
  * Parse a query string (with or without a leading `?`) into URL-shaped list
  * params. Malformed values are ignored, never trusted or thrown: bad JSON, or
@@ -44,7 +47,7 @@ export declare function serializeListParams(params: ListParamsQuery): string;
  * `page`/`perPage`, or one below 1; and an `order` outside `ASC`/`DESC` are
  * simply omitted. `order` is upper-cased first.
  */
-export declare function parseListParams(search: string): ListParamsQuery;
+export declare function parseListParams<TRecord = LooseRecord>(search: string): ListParamsQuery<TRecord>;
 /**
  * Whether the user has set any non-default list param — a filter with keys, an
  * explicit sort/order, a page other than 1, or a perPage. Used by adapters to
@@ -52,21 +55,21 @@ export declare function parseListParams(search: string): ListParamsQuery;
  * defaults. Mirrors react-admin's `hasCustomParams` semantics (an empty filter
  * and `page === 1` are not "custom"), without its filter-must-be-present guard.
  */
-export declare function hasCustomParams(params: ListParamsQuery): boolean;
+export declare function hasCustomParams<TRecord = LooseRecord>(params: ListParamsQuery<TRecord>): boolean;
 /** The list-controller state a URL carries. */
-export interface ListUrlState {
+export interface ListUrlState<TRecord = LooseRecord> {
     page: number;
     perPage: number;
-    sort: SortPayload[];
-    filter: FilterPayload;
-    displayedFilters: Record<string, boolean>;
+    sort: SortPayload<TRecord>[];
+    filter: FilterPayload<TRecord>;
+    displayedFilters: DisplayedFilters<TRecord>;
 }
 /** The query string for a list's state; the primary sort becomes `sort`/`order`. */
-export declare function serializeListState(state: ListUrlState): string;
+export declare function serializeListState<TRecord = LooseRecord>(state: ListUrlState<TRecord>): string;
 /**
  * The params a URL query string sets, as one `setParams` patch, or `null` when
  * it sets none of {@link hasCustomParams}, so a clean URL keeps the option and
  * store defaults. Shown filter inputs without a filter clear the filter.
  */
-export declare function listPatchFromSearch(search: string): ListParamsPatch | null;
+export declare function listPatchFromSearch<TRecord = LooseRecord>(search: string): ListParamsPatch<TRecord> | null;
 export {};