@contember/bindx-dataview 0.1.51 → 0.1.53

package/src/HasManyDataGrid.tsx

@@ -42,6 +42,7 @@ import { useDataViewKey } from './DataViewKeyProvider.js'
 import { DataViewProvider, type DataViewContextValue, type DataViewFetchAllData, type DataViewLoaderState } from './DataViewContext.js'
 import { useDataGridSetup } from './useDataGridSetup.js'
 import { buildHasManyRelationQuery, extractHasManyRelationRows } from './hasManyRelationQuery.js'
+import { usePagingTotalCount } from './usePagingTotalCount.js'
 
 // ============================================================================
 // Props
@@ -80,10 +81,18 @@ interface ListState {
 	status: 'loading' | 'error' | 'ready'
 	items: Array<{ id: string; data: object }>
 	totalCount?: number
+	/** The query options the items were loaded for. */
+	optionsKey?: string
 }
 
 const INITIAL_LIST_STATE: ListState = { status: 'loading', items: [] }
 
+function getRowId(entityType: string, row: Record<string, unknown>): string {
+	const id = row['id']
+	if (typeof id !== 'string') throw new Error(`${entityType} relation row has no string id`)
+	return id
+}
+
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -179,19 +188,19 @@ function HasManyDataGridImpl<TEntity extends object>({
 
 				const relation = extractHasManyRelationRows(result.data, { alias, fieldName })
 				if (!relation) {
-					setListState({ status: 'ready', items: [] })
+					setListState({ status: 'ready', items: [], optionsKey })
 					return
 				}
 
-				const items = relation.rows.map((data: Record<string, unknown>) => {
-					const id = data['id'] as string
-					dispatcher.dispatch(
-						setEntityData(targetEntityType, id, data, true),
-					)
-					return { id, data: data as object }
+				store.indexServerResponse(targetEntityType, relation.rows, setup.selection, schemaRegistry)
+				const items = relation.rows.map(data => ({ id: getRowId(targetEntityType, data), data: store.resolveServerOccurrence(data) }))
+				store.batchNotifications(() => {
+					for (const item of items) {
+						dispatcher.dispatch(setEntityData(targetEntityType, item.id, item.data, true))
+					}
 				})
 
-				setListState({ status: 'ready', items, totalCount: relation.totalCount })
+				setListState({ status: 'ready', items, totalCount: relation.totalCount, optionsKey })
 			} catch (error) {
 				if (abortController.signal.aborted) return
 				setListState({ status: 'error', items: [] })
@@ -203,7 +212,7 @@ function HasManyDataGridImpl<TEntity extends object>({
 		return () => {
 			abortController.abort()
 		}
-	}, [parentEntityType, parentEntityId, fieldName, targetEntityType, optionsKey, setup.selection, batcher, dispatcher, store])
+	}, [parentEntityType, parentEntityId, fieldName, targetEntityType, optionsKey, setup.selection, batcher, dispatcher, store, schemaRegistry])
 
 	// ---- Build items from state ----
 	const items = useMemo((): EntityAccessor<TEntity>[] => {
@@ -233,14 +242,16 @@ function HasManyDataGridImpl<TEntity extends object>({
 		}
 	}, [listState.status])
 
-	// Update total count from paginateRelation
-	useEffect(() => {
-		if (listState.totalCount !== undefined) {
-			setup.paging.setTotalCount(listState.totalCount)
-		} else if (listState.status === 'ready' && setup.paging.queryLimit !== undefined && setup.paging.queryOffset !== undefined && itemCount < setup.paging.queryLimit) {
-			setup.paging.setTotalCount(setup.paging.queryOffset + itemCount)
-		}
-	}, [listState.status, listState.totalCount, itemCount, setup.paging.queryLimit, setup.paging.queryOffset, setup.paging.setTotalCount])
+	const countKey = useMemo(
+		() => JSON.stringify([parentEntityType, parentEntityId, fieldName, setup.combinedFilter ?? {}]),
+		[parentEntityType, parentEntityId, fieldName, setup.combinedFilter],
+	)
+	usePagingTotalCount(setup.paging, {
+		countedTotal: listState.totalCount ?? null,
+		countKey,
+		isPageCurrent: listState.status === 'ready' && listState.optionsKey === optionsKey,
+		pageItemCount: itemCount,
+	})
 
 	// ---- Reload ----
 	const [, setReloadCounter] = useState(0)

package/src/columnLeaf.ts

@@ -23,13 +23,30 @@ export type ColumnType = 'text' | 'number' | 'date' | 'dateTime' | 'boolean' | '
 
 export interface ColumnLeafProps {
 	// ── Core ──
-	readonly name: string
+	/**
+	 * Identity of the column: the key its visibility is stored under and the key
+	 * its header and cells are rendered by. Optional here because most call sites
+	 * let it be derived — see {@link resolveColumnNames}. Pass it explicitly when
+	 * two columns bind the same field, which would otherwise derive one name.
+	 */
+	readonly name?: string
 	readonly fieldName: string | null
 	readonly fieldRef: FieldRef<unknown> | null
 	readonly sortingField: string | null
 	readonly filterName: string | null
 	readonly filterHandler: FilterHandler<FilterArtifact> | undefined
+	/**
+	 * Where the filter starts when nothing is stored for it. Defaults to the
+	 * handler's (inactive) default artifact.
+	 */
+	readonly filterInitialArtifact?: FilterArtifact
 	readonly isTextSearchable: boolean
+	/**
+	 * The leaf exists only to register its field — for full-text search, or to
+	 * pull the field into the query. It is not a column: neither the table nor
+	 * the visibility list shows it.
+	 */
+	readonly virtual?: boolean
 	readonly columnType?: ColumnType
 	readonly collectSelection?: (collectorProxy: unknown) => void
 
@@ -64,6 +81,44 @@ export function ColumnLeaf(_props: ColumnLeafProps): null {
 	return null
 }
 
+// ============================================================================
+// Column Identity
+// ============================================================================
+
+/** A column leaf once its identity is settled — what the view exposes. */
+export interface DataViewColumn extends ColumnLeafProps {
+	readonly name: string
+}
+
+/**
+ * Settle each leaf's identity: the declared name, else the bound field, else the
+ * position.
+ *
+ * Position is the last resort rather than the first, because it is only stable
+ * while the column order is — and the name is a persisted visibility key, so a
+ * reordered grid would read a stale one. That is also why duplicates are
+ * reported instead of being suffixed away.
+ */
+export function resolveColumnNames(leaves: readonly ColumnLeafProps[]): DataViewColumn[] {
+	const columns = leaves.map((leaf, index): DataViewColumn => ({
+		...leaf,
+		name: leaf.name ?? leaf.fieldName ?? `col-${index}`,
+	}))
+
+	const duplicates = columns
+		.map(it => it.name)
+		.filter((name, index, names) => names.indexOf(name) !== index)
+	if (duplicates.length > 0) {
+		console.warn(
+			`[bindx] DataGrid columns share the name ${[...new Set(duplicates)].map(it => `"${it}"`).join(', ')}. ` +
+			`A name keys a column's cells and stores its visibility, so the columns act as one. ` +
+			`Give each of them a \`name\` prop.`,
+		)
+	}
+
+	return columns
+}
+
 // ============================================================================
 // Generalized Children Analyzer
 // ============================================================================

package/src/columns.tsx

@@ -99,9 +99,15 @@ interface EnumExtraProps<T extends string> {
 	options: readonly T[] | Record<T, ReactNode>
 }
 
-export interface DataGridEnumColumnProps<T extends string> extends DataGridScalarColumnPropsBase<T>, EnumExtraProps<NoInfer<T>> {}
+export interface DataGridEnumColumnProps<T extends string> extends DataGridScalarColumnPropsBase<T>, EnumExtraProps<NoInfer<T>> {
+	/** Where the column's filter starts when nothing is stored for it. Defaults to no value picked. */
+	filterInitialArtifact?: EnumFilterArtifact<NoInfer<T>>
+}
 
-export interface DataGridEnumListColumnProps<T extends string> extends DataGridScalarColumnPropsBase<T>, EnumExtraProps<NoInfer<T>> {}
+export interface DataGridEnumListColumnProps<T extends string> extends DataGridScalarColumnPropsBase<T>, EnumExtraProps<NoInfer<T>> {
+	/** Where the column's filter starts when nothing is stored for it. Defaults to no value picked. */
+	filterInitialArtifact?: EnumListFilterArtifact<NoInfer<T>>
+}
 
 // ============================================================================
 // Scalar Columns via createColumn()
@@ -186,6 +192,8 @@ export const DataGridHasManyColumn: {
 
 export interface DataGridActionColumnProps {
 	children: React.ReactNode | ((entity: EntityAccessor<object>) => React.ReactNode)
+	/** Column identity. An action column binds no field, so without this it is named by its position. */
+	name?: string
 	header?: React.ReactNode
 }
 
@@ -203,7 +211,7 @@ export const DataGridActionColumn = Object.assign(
 
 			const leafProps: ColumnLeafProps = {
 				columnType: 'action',
-				name: `action-${Math.random().toString(36).slice(2, 8)}`,
+				name: props['name'] as string | undefined,
 				fieldName: null,
 				fieldRef: null,
 				sortingField: null,
@@ -225,10 +233,16 @@ export const DataGridActionColumn = Object.assign(
 
 export interface DataGridColumnProps<T> {
 	field?: FieldRef<T>
+	/** Column identity. Defaults to the bound field name — pass it when two columns bind one field, or when there is no field. */
+	name?: string
 	header?: React.ReactNode
 	sortable?: boolean
 	filter?: boolean
 	filterHandler?: FilterHandler<FilterArtifact>
+	/** Where the column's filter starts when nothing is stored for it. Defaults to the handler's inactive artifact. */
+	filterInitialArtifact?: FilterArtifact
+	/** Register the field without showing a column (e.g. to make it full-text searchable). */
+	virtual?: boolean
 	children?: (value: T | null, accessor: EntityAccessor<object>) => React.ReactNode
 }
 
@@ -247,7 +261,8 @@ export const DataGridColumn = Object.assign(
 			const children = props['children'] as ((value: unknown, accessor: EntityAccessor<object>) => React.ReactNode) | undefined
 
 			const leafProps: ColumnLeafProps = {
-				name: fieldName ?? `col-${Math.random().toString(36).slice(2, 8)}`,
+				name: props['name'] as string | undefined,
+				virtual: props['virtual'] as boolean | undefined,
 				fieldName,
 				fieldRef: fieldRef ?? null,
 				sortingField: sortable && fieldName ? fieldName : null,
@@ -255,6 +270,7 @@ export const DataGridColumn = Object.assign(
 				filterHandler: filterEnabled && fieldName
 					? (customHandler ?? textColumnDef.createFilterHandler(fieldName) as FilterHandler<FilterArtifact>)
 					: undefined,
+				filterInitialArtifact: props['filterInitialArtifact'] as FilterArtifact | undefined,
 				isTextSearchable: false,
 				header,
 				renderCell: (accessor: EntityAccessor<object>) => {

package/src/contextHooks.ts

@@ -154,13 +154,22 @@ export function useDataViewElements(): readonly DataViewElementData[] {
 			if (elements) return elements
 		}
 
-		// Fallback: derive elements from columns (table layout or no layout markers)
-		return columns
-			.filter(c => c.fieldName !== null)
-			.map(c => ({
-				name: c.name,
-				label: c.header,
+		// Fallback: derive elements from columns (table layout or no layout markers).
+		// Every column is offered — `name` is what the table hides by, so a column
+		// with no field of its own is reachable just the same. An empty header is
+		// left unset so the label falls back to the formatted name.
+		//
+		// Columns sharing a name share one visibility flag, so they are listed once
+		// rather than as rows that look independent and are not.
+		const byName = new Map<string, DataViewElementData>()
+		for (const column of columns) {
+			if (column.virtual || byName.has(column.name)) continue
+			byName.set(column.name, {
+				name: column.name,
+				label: column.header === '' ? undefined : column.header,
 				fallback: true,
-			}))
+			})
+		}
+		return [...byName.values()]
 	}, [columns, currentLayout, layoutElements])
 }

package/src/createColumn.ts

@@ -43,11 +43,17 @@ export interface CreateColumnConfig<TValue, TFilterArtifact extends FilterArtifa
 // Column Component Props
 // ============================================================================
 
-export interface ColumnComponentProps<TValue = unknown> {
+export interface ColumnComponentProps<TValue = unknown, TFilterArtifact extends FilterArtifact = FilterArtifact> {
 	field: FieldRef<TValue>
+	/** Column identity. Defaults to the bound field name — pass it when two columns bind one field. */
+	name?: string
 	header?: React.ReactNode
 	sortable?: boolean
 	filter?: boolean
+	/** Where the column's filter starts when nothing is stored for it. Defaults to the handler's inactive artifact. */
+	filterInitialArtifact?: TFilterArtifact
+	/** Register the field without showing a column (e.g. to make it full-text searchable). */
+	virtual?: boolean
 	children?: (value: TValue | null, accessor: EntityAccessor<object>) => React.ReactNode
 }
 
@@ -55,8 +61,12 @@ export interface ColumnComponentProps<TValue = unknown> {
 // Factory
 // ============================================================================
 
-export interface ColumnComponent<TExtraProps = object> {
-	<T>(props: ColumnComponentProps<T> & TExtraProps): null
+/**
+ * `TFilterArtifact` defaults to `never`: a column whose artifact type is not known takes no
+ * `filterInitialArtifact`, and every column `createColumn` builds is assignable to it.
+ */
+export interface ColumnComponent<TExtraProps = object, TFilterArtifact extends FilterArtifact = never> {
+	<T>(props: ColumnComponentProps<T, TFilterArtifact> & TExtraProps): null
 	staticRender: (props: Record<string, unknown>) => React.ReactNode
 }
 
@@ -106,7 +116,8 @@ export function createColumnStaticRender<TValue, TFilterArtifact extends FilterA
 			}
 
 		const leafProps = {
-			name: fieldName ?? `col-${Math.random().toString(36).slice(2, 8)}`,
+			name: props['name'] as string | undefined,
+			virtual: props['virtual'] as boolean | undefined,
 			fieldName,
 			fieldRef: fieldRef ?? null,
 			sortingField: sortable && fieldName ? fieldName : null,
@@ -114,6 +125,7 @@ export function createColumnStaticRender<TValue, TFilterArtifact extends FilterA
 			filterHandler: filterEnabled && fieldName
 				? columnType.createFilterHandler(fieldName) as FilterHandler<FilterArtifact>
 				: undefined,
+			filterInitialArtifact: props['filterInitialArtifact'] as FilterArtifact | undefined,
 			isTextSearchable: columnType.isTextSearchable,
 			columnType: columnType.name as ColumnLeafProps['columnType'],
 			enumName,
@@ -135,10 +147,10 @@ export function createColumnStaticRender<TValue, TFilterArtifact extends FilterA
 export function createColumn<TValue, TFilterArtifact extends FilterArtifact, TExtraProps = object>(
 	columnType: ColumnTypeDef<TValue, TFilterArtifact>,
 	config: CreateColumnConfig<TValue, TFilterArtifact>,
-): ColumnComponent<TExtraProps> {
-	function Column(_props: ColumnComponentProps<unknown> & TExtraProps): null {
+): ColumnComponent<TExtraProps, TFilterArtifact> {
+	function Column(_props: ColumnComponentProps<unknown, TFilterArtifact> & TExtraProps): null {
 		return null
 	}
 	Column.staticRender = createColumnStaticRender(columnType, config)
-	return Column as ColumnComponent<TExtraProps>
+	return Column as ColumnComponent<TExtraProps, TFilterArtifact>
 }

package/src/createRelationColumn.tsx

@@ -11,7 +11,7 @@
  */
 
 import React from 'react'
-import type { FieldRef, FilterArtifact, FilterHandler, EntityAccessor, SelectionMeta } from '@contember/bindx'
+import type { FieldRef, FilterArtifact, FilterHandler, EntityAccessor, RelationFilterArtifact, SelectionMeta } from '@contember/bindx'
 import { SelectionScope } from '@contember/bindx'
 import { createCollectorProxy, collectSelection as collectJsxSelection, SCOPE_REF } from '@contember/bindx-react'
 import type { ColumnTypeDef } from './columnTypes.js'
@@ -60,8 +60,14 @@ export interface RelationCellWrapperContext {
 
 export interface RelationColumnProps<TEntity, TSelected> {
 	field: object
+	/** Column identity. Defaults to the bound field name — pass it when two columns bind one relation. */
+	name?: string
 	header?: React.ReactNode
 	filter?: boolean
+	/** Where the column's filter starts when nothing is stored for it. Defaults to no related row picked. */
+	filterInitialArtifact?: RelationFilterArtifact
+	/** Register the relation without showing a column. */
+	virtual?: boolean
 	renderCellWrapper?: (content: React.ReactNode, item: EntityAccessor<object>) => React.ReactNode
 	children: (entity: EntityAccessor<TEntity, TSelected>) => React.ReactNode
 }
@@ -149,7 +155,8 @@ export function createRelationColumn<TFilterArtifact extends FilterArtifact>(
 				: undefined)
 
 		return {
-			name: fieldName ?? `col-${Math.random().toString(36).slice(2, 8)}`,
+			name: props['name'] as string | undefined,
+			virtual: props['virtual'] as boolean | undefined,
 			fieldName,
 			fieldRef: fieldRef ?? null,
 			sortingField: null,
@@ -157,6 +164,7 @@ export function createRelationColumn<TFilterArtifact extends FilterArtifact>(
 			filterHandler: filterName
 				? columnType.createFilterHandler(fieldName!) as FilterHandler<FilterArtifact>
 				: undefined,
+			filterInitialArtifact: props['filterInitialArtifact'] as FilterArtifact | undefined,
 			isTextSearchable: false,
 			columnType: columnType.name as ColumnLeafProps['columnType'],
 			relatedEntityName,

package/src/export.tsx

@@ -123,7 +123,7 @@ export const DataViewExportTrigger = forwardRef<HTMLButtonElement, DataViewExpor
 
 			try {
 				const visibleColumns = onlyVisible
-					? columns.filter((c, i) => selection.isVisible(c.fieldName ?? `col-${i}`))
+					? columns.filter(c => selection.isVisible(c.name))
 					: columns
 
 				const data = await fetchAllData()
@@ -133,7 +133,7 @@ export const DataViewExportTrigger = forwardRef<HTMLButtonElement, DataViewExpor
 				}
 
 				const exportColumns = visibleColumns
-					.filter(c => c.fieldName !== null)
+					.filter(c => !c.virtual && c.fieldName !== null)
 					.map(c => ({ name: String(c.header ?? c.fieldName ?? ''), fieldName: c.fieldName }))
 
 				const { blob, extension } = exportFactory.create({

package/src/index.ts

@@ -24,6 +24,8 @@ export {
 export {
 	ColumnLeaf,
 	type ColumnLeafProps,
+	type DataViewColumn,
+	resolveColumnNames,
 	extractColumnLeaves,
 	analyzeChildren,
 	type ChildrenAnalysisResult,

package/src/select/SelectDataView.tsx

@@ -46,6 +46,7 @@ import { useSelectOptions } from './selectContext.js'
 import { DataViewProvider, type DataViewContextValue, type DataViewLoaderState } from '../DataViewContext.js'
 import { useFilteringState, useSortingState, usePagingState, useSelectionState } from '../useDataViewState.js'
 import { useListFetchAllData } from '../useListFetchAllData.js'
+import { usePagingTotalCount } from '../usePagingTotalCount.js'
 
 export interface SelectDataViewProps {
 	/** Children rendered inside the DataView context */
@@ -185,15 +186,13 @@ function SelectDataViewImpl({
 		}
 	}, [result.$status])
 
-	// Update total count from the count query, falling back to the partial-page
-	// heuristic until the count resolves.
-	useEffect(() => {
-		if (totalCount !== null) {
-			paging.setTotalCount(totalCount)
-		} else if (result.$status === 'ready' && paging.queryLimit !== undefined && paging.queryOffset !== undefined && itemCount < paging.queryLimit) {
-			paging.setTotalCount(paging.queryOffset + itemCount)
-		}
-	}, [totalCount, result.$status, itemCount, paging.queryLimit, paging.queryOffset, paging.setTotalCount])
+	const countKey = useMemo(() => JSON.stringify(combinedFilter ?? {}), [combinedFilter])
+	usePagingTotalCount(paging, {
+		countedTotal: totalCount,
+		countKey,
+		isPageCurrent: result.$status === 'ready' && !result.$isRefetching,
+		pageItemCount: itemCount,
+	})
 
 	// ---- Reload ----
 	const [, setReloadCounter] = useState(0)

package/src/useDataGridSetup.ts

@@ -21,7 +21,7 @@ import {
 	mergeSelections,
 	collectSelection,
 } from '@contember/bindx-react'
-import { ColumnLeaf, type ColumnLeafProps, analyzeChildren } from './columnLeaf.js'
+import { ColumnLeaf, type ColumnLeafProps, type DataViewColumn, analyzeChildren, resolveColumnNames } from './columnLeaf.js'
 import { DataGridToolbarContent, type DataGridToolbarContentProps } from './markers.js'
 import { DataGridLayout, type DataGridLayoutProps } from './markers.js'
 import { useFilteringState, useSortingState, usePagingState, useSelectionState } from './useDataViewState.js'
@@ -63,7 +63,7 @@ export interface DataGridCommonProps<TEntity extends object> {
 
 export interface DataGridSetupResult {
 	childrenJsx: ReactNode
-	columns: ColumnLeafProps[]
+	columns: DataViewColumn[]
 	selection: SelectionMeta
 	queryKey: string
 	toolbarContent: ReactNode | undefined
@@ -141,7 +141,7 @@ export function useDataGridSetup<TEntity extends object>({
 			return runtimeColumns
 		}
 
-		const runtimeBoundColumns = cols.map((column, index): ColumnLeafProps => ({
+		const runtimeBoundColumns = resolveColumnNames(cols).map((column, index): DataViewColumn => ({
 			...column,
 			renderCell: accessor => {
 				const runtimeColumn = getRuntimeColumns(accessor)[index]
@@ -199,12 +199,12 @@ export function useDataGridSetup<TEntity extends object>({
 	}, [entityType, schemaRegistry, children, layouts])
 
 	// ---- Phase 2: State management ----
-	const filterDefs = useMemo((): ReadonlyMap<string, { handler: FilterHandler<FilterArtifact> }> => {
-		const map = new Map<string, { handler: FilterHandler<FilterArtifact> }>()
+	const filterDefs = useMemo((): ReadonlyMap<string, { handler: FilterHandler<FilterArtifact>; initialArtifact?: FilterArtifact }> => {
+		const map = new Map<string, { handler: FilterHandler<FilterArtifact>; initialArtifact?: FilterArtifact }>()
 		const textFieldPaths: string[] = []
 		for (const col of columns) {
 			if (col.filterName && col.filterHandler) {
-				map.set(col.filterName, { handler: col.filterHandler })
+				map.set(col.filterName, { handler: col.filterHandler, initialArtifact: col.filterInitialArtifact })
 			}
 			if (col.isTextSearchable && col.fieldName) {
 				textFieldPaths.push(col.fieldName)

package/src/useDataViewState.ts

@@ -5,7 +5,7 @@
  * for persisting state across navigations.
  */
 
-import { useState, useCallback, useMemo } from 'react'
+import { useState, useCallback, useEffect, useMemo } from 'react'
 import type {
 	FilterHandler,
 	FilterArtifact,
@@ -40,12 +40,18 @@ export type FilterArtifactUpdate =
 
 export interface FilteringState {
 	readonly filters: ReadonlyMap<string, RegisteredFilter>
+	/** The filter's current artifact: the stored one, else its initial artifact. `undefined` only for an unregistered filter. */
 	getArtifact(name: string): FilterArtifact | undefined
 	/** An updater sees the live artifact, not a render snapshot; returning `undefined` resets the filter to its default. */
 	setArtifact(name: string, artifact: FilterArtifactUpdate): void
-	/** Replaces the whole artifact record at once — for restoring a saved filter preset. */
+	/**
+	 * Replaces the whole artifact record at once — for restoring a saved filter preset.
+	 * A registered filter the record does not name reads as its initial artifact.
+	 */
 	setAllArtifacts(artifacts: Record<string, FilterArtifact>): void
+	/** Clears one filter: sets it to its handler's default (inactive) artifact. */
 	resetFilter(name: string): void
+	/** Puts every filter back where it starts: its initial artifact, else the handler default. */
 	resetAll(): void
 	readonly hasActiveFilters: boolean
 	readonly resolvedWhere: Record<string, unknown> | undefined
@@ -62,7 +68,7 @@ export interface UseFilteringOptions {
 export function useFilteringState(options: UseFilteringOptions): FilteringState {
 	const { filters: filterDefs, stateStorage = 'null', storageKey = 'dataview' } = options
 
-	const defaultArtifacts = useMemo((): Record<string, FilterArtifact> => {
+	const initialArtifacts = useMemo((): Record<string, FilterArtifact> => {
 		const result: Record<string, FilterArtifact> = {}
 		for (const [name, def] of filterDefs) {
 			result[name] = def.initialArtifact ?? def.handler.defaultArtifact()
@@ -70,10 +76,18 @@ export function useFilteringState(options: UseFilteringOptions): FilteringState
 		return result
 	}, [filterDefs])
 
-	const [artifacts, setArtifacts] = useStoredState<Record<string, FilterArtifact>>(
+	const [storedArtifacts, setArtifacts] = useStoredState<Record<string, FilterArtifact>>(
 		stateStorage,
 		[storageKey, 'filters'],
-		(stored) => stored ?? defaultArtifacts,
+		(stored) => stored ?? initialArtifacts,
+	)
+
+	// A registered filter the record does not name (a record stored before the filter
+	// existed, or a restored preset that omits it) is where it would start with nothing
+	// stored. Every view below reads this one record, so the UI and the query agree.
+	const artifacts = useMemo(
+		(): Record<string, FilterArtifact> => ({ ...initialArtifacts, ...storedArtifacts }),
+		[initialArtifacts, storedArtifacts],
 	)
 
 	const getArtifact = useCallback(
@@ -85,12 +99,12 @@ export function useFilteringState(options: UseFilteringOptions): FilteringState
 	const setArtifact = useCallback(
 		(name: string, artifact: FilterArtifactUpdate): void => {
 			setArtifacts(current => {
-				const next = typeof artifact === 'function' ? artifact(current[name]) : artifact
+				const next = typeof artifact === 'function' ? artifact(current[name] ?? initialArtifacts[name]) : artifact
 				const resolved = next ?? filterDefs.get(name)?.handler.defaultArtifact()
 				return resolved === undefined ? current : { ...current, [name]: resolved }
 			})
 		},
-		[filterDefs, setArtifacts],
+		[filterDefs, initialArtifacts, setArtifacts],
 	)
 
 	const resetFilter = useCallback(
@@ -103,8 +117,8 @@ export function useFilteringState(options: UseFilteringOptions): FilteringState
 	)
 
 	const resetAll = useCallback((): void => {
-		setArtifacts(defaultArtifacts)
-	}, [defaultArtifacts, setArtifacts])
+		setArtifacts(initialArtifacts)
+	}, [initialArtifacts, setArtifacts])
 
 	const hasActiveFilters = useMemo((): boolean => {
 		for (const [name, def] of filterDefs) {
@@ -135,6 +149,7 @@ export function useFilteringState(options: UseFilteringOptions): FilteringState
 			map.set(name, {
 				name,
 				handler: def.handler,
+				// Stored JSON is not validated, so a `null` entry falls back to the handler default.
 				artifact: artifacts[name] ?? def.handler.defaultArtifact(),
 			})
 		}
@@ -304,7 +319,7 @@ export function usePagingState(options: UsePagingOptions = {}): PagingStateResul
 		storageKey = 'dataview',
 	} = options
 
-	const [pageIndex, setPageIndex] = useStoredState<number>(
+	const [requestedPageIndex, setPageIndex] = useStoredState<number>(
 		currentPageStateStorage,
 		[storageKey, 'pageIndex'],
 		(stored) => stored ?? 0,
@@ -316,11 +331,6 @@ export function usePagingState(options: UsePagingOptions = {}): PagingStateResul
 		(stored) => stored ?? initialItemsPerPage,
 	)
 
-	const state = useMemo((): PagingState => ({
-		pageIndex,
-		itemsPerPage: itemsPerPage ?? 0,
-	}), [pageIndex, itemsPerPage])
-
 	const [totalCount, setTotalCount] = useState<number | null>(null)
 	const [refreshCounter, setRefreshCounter] = useState(0)
 
@@ -329,6 +339,19 @@ export function usePagingState(options: UsePagingOptions = {}): PagingStateResul
 		return Math.max(1, Math.ceil(totalCount / itemsPerPage))
 	}, [totalCount, itemsPerPage])
 
+	// A requested page past the end (the total shrank, or a stored index outlived its result set)
+	// reads as the last page, so the query offset never points past the rows.
+	const pageIndex = totalPages === null ? requestedPageIndex : Math.min(requestedPageIndex, totalPages - 1)
+
+	useEffect(() => {
+		if (pageIndex !== requestedPageIndex) setPageIndex(pageIndex)
+	}, [pageIndex, requestedPageIndex, setPageIndex])
+
+	const state = useMemo((): PagingState => ({
+		pageIndex,
+		itemsPerPage: itemsPerPage ?? 0,
+	}), [pageIndex, itemsPerPage])
+
 	const info: PagingInfo = useMemo(() => ({
 		totalCount,
 		totalPages,