@contember/bindx-dataview 0.1.0

package/src/sortingComponents.tsx

@@ -0,0 +1,104 @@
+/**
+ * Composable sorting UI components using Radix Slot pattern.
+ *
+ * Usage:
+ * ```tsx
+ * <DataViewSortingTrigger field={it.title}>
+ *   <button>Sort by Title</button>
+ * </DataViewSortingTrigger>
+ *
+ * <DataViewSortingSwitch field={it.title}
+ *   asc={<span>↑</span>}
+ *   desc={<span>↓</span>}
+ *   none={<span>↕</span>}
+ * />
+ * ```
+ */
+
+import React, { forwardRef, type ReactElement, useCallback } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { composeEventHandlers } from '@radix-ui/primitive'
+import { useDataViewContext } from './DataViewContext.js'
+import { dataAttribute } from './dataAttribute.js'
+import type { SortingDirectionAction, OrderDirection, FieldRefBase } from '@contember/bindx'
+
+// ============================================================================
+// DataViewSortingTrigger
+// ============================================================================
+
+export interface DataViewSortingTriggerProps<T> {
+	/** Field to sort by */
+	field: FieldRefBase<T>
+	/** Sorting action. Default: 'next' (cycles asc → desc → none) */
+	action?: SortingDirectionAction
+	/** Button element to render */
+	children: ReactElement
+}
+
+const actionToState: Record<Exclude<SortingDirectionAction, OrderDirection>, OrderDirection | null> = {
+	next: null,
+	toggleAsc: 'asc',
+	toggleDesc: 'desc',
+	clear: null,
+}
+
+export const DataViewSortingTrigger = forwardRef<HTMLButtonElement, DataViewSortingTriggerProps<unknown>>(
+	({ action = 'next', field, ...props }, ref) => {
+		const { sorting } = useDataViewContext()
+		const orderDirection = sorting.directionOf(field)
+
+		const changeOrder = useCallback(
+			(e: React.MouseEvent): void => {
+				sorting.setOrderBy(field, action, e.ctrlKey || e.metaKey)
+			},
+			[field, action, sorting],
+		)
+
+		const active = !!action
+			&& action !== 'next'
+			&& action !== 'clear'
+			&& orderDirection === (action === 'toggleAsc' ? 'asc' : action === 'toggleDesc' ? 'desc' : action)
+
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, changeOrder)}
+				data-active={dataAttribute(active)}
+				data-current={orderDirection ?? 'none'}
+				{...otherProps}
+			/>
+		)
+	},
+) as <T>(props: DataViewSortingTriggerProps<T> & React.RefAttributes<HTMLButtonElement>) => ReactElement | null
+;(DataViewSortingTrigger as React.FC).displayName = 'DataViewSortingTrigger'
+
+// ============================================================================
+// DataViewSortingSwitch
+// ============================================================================
+
+export interface DataViewSortingSwitchProps<T> {
+	/** Field to check sorting direction for */
+	field: FieldRefBase<T>
+	/** Render when sorted ascending */
+	asc?: React.ReactNode
+	/** Render when sorted descending */
+	desc?: React.ReactNode
+	/** Render when not sorted */
+	none?: React.ReactNode
+}
+
+export function DataViewSortingSwitch<T>({
+	field,
+	asc,
+	desc,
+	none,
+}: DataViewSortingSwitchProps<T>): ReactElement {
+	const { sorting } = useDataViewContext()
+	const direction = sorting.directionOf(field)
+
+	if (direction === 'asc') return <>{asc ?? null}</>
+	if (direction === 'desc') return <>{desc ?? null}</>
+	return <>{none ?? null}</>
+}

package/src/stateStorage.ts

@@ -0,0 +1,188 @@
+/**
+ * State storage abstraction for DataView state persistence.
+ *
+ * Supports URL params, sessionStorage, localStorage, or custom backends.
+ *
+ * Usage:
+ * ```tsx
+ * const [value, setValue] = useStoredState('url', ['myGrid', 'sorting'], initialValue)
+ * ```
+ */
+
+import { useState, useCallback, useMemo } from 'react'
+
+// ============================================================================
+// Storage Interface
+// ============================================================================
+
+export interface StateStorage {
+	get<T>(key: string): T | undefined
+	set<T>(key: string, value: T): void
+	remove(key: string): void
+}
+
+export type StateStorageOrName = 'url' | 'session' | 'local' | 'null' | StateStorage
+
+// ============================================================================
+// Built-in Storage Backends
+// ============================================================================
+
+const nullStorage: StateStorage = {
+	get: () => undefined,
+	set: () => {},
+	remove: () => {},
+}
+
+function createWebStorage(storage: Storage): StateStorage {
+	return {
+		get<T>(key: string): T | undefined {
+			try {
+				const raw = storage.getItem(key)
+				return raw ? JSON.parse(raw) : undefined
+			} catch {
+				return undefined
+			}
+		},
+		set<T>(key: string, value: T): void {
+			try {
+				storage.setItem(key, JSON.stringify(value))
+			} catch {
+				// Storage full or unavailable
+			}
+		},
+		remove(key: string): void {
+			try {
+				storage.removeItem(key)
+			} catch {
+				// Ignore
+			}
+		},
+	}
+}
+
+function createUrlStorage(): StateStorage {
+	return {
+		get<T>(key: string): T | undefined {
+			if (typeof window === 'undefined') return undefined
+			try {
+				const params = new URLSearchParams(window.location.search)
+				const raw = params.get(key)
+				return raw ? JSON.parse(raw) : undefined
+			} catch {
+				return undefined
+			}
+		},
+		set<T>(key: string, value: T): void {
+			if (typeof window === 'undefined') return
+			try {
+				const params = new URLSearchParams(window.location.search)
+				const serialized = JSON.stringify(value)
+				params.set(key, serialized)
+				const url = `${window.location.pathname}?${params.toString()}`
+				window.history.replaceState(null, '', url)
+			} catch {
+				// Ignore
+			}
+		},
+		remove(key: string): void {
+			if (typeof window === 'undefined') return
+			try {
+				const params = new URLSearchParams(window.location.search)
+				params.delete(key)
+				const search = params.toString()
+				const url = search ? `${window.location.pathname}?${search}` : window.location.pathname
+				window.history.replaceState(null, '', url)
+			} catch {
+				// Ignore
+			}
+		},
+	}
+}
+
+function resolveStorage(storageOrName: StateStorageOrName): StateStorage {
+	if (typeof storageOrName === 'object') return storageOrName
+
+	switch (storageOrName) {
+		case 'null':
+			return nullStorage
+		case 'url':
+			return createUrlStorage()
+		case 'session':
+			if (typeof sessionStorage !== 'undefined') {
+				return createWebStorage(sessionStorage)
+			}
+			return nullStorage
+		case 'local':
+			if (typeof localStorage !== 'undefined') {
+				return createWebStorage(localStorage)
+			}
+			return nullStorage
+	}
+}
+
+function createFallbackStorage(storages: StateStorage[]): StateStorage {
+	return {
+		get<T>(key: string): T | undefined {
+			for (const storage of storages) {
+				const value = storage.get<T>(key)
+				if (value !== undefined) return value
+			}
+			return undefined
+		},
+		set<T>(key: string, value: T): void {
+			for (const storage of storages) {
+				storage.set(key, value)
+			}
+		},
+		remove(key: string): void {
+			for (const storage of storages) {
+				storage.remove(key)
+			}
+		},
+	}
+}
+
+function resolveStorageOrFallback(storageOrName: StateStorageOrName | StateStorageOrName[]): StateStorage {
+	if (Array.isArray(storageOrName)) {
+		return createFallbackStorage(storageOrName.map(resolveStorage))
+	}
+	return resolveStorage(storageOrName)
+}
+
+// ============================================================================
+// useStoredState Hook
+// ============================================================================
+
+export type SetStoredState<T> = (value: T | ((current: T) => T)) => void
+
+export function useStoredState<T>(
+	storageOrName: StateStorageOrName | StateStorageOrName[],
+	key: readonly string[],
+	initializer: (storedValue: T | undefined) => T,
+): [T, SetStoredState<T>] {
+	const storage = useMemo(() => resolveStorageOrFallback(storageOrName), [storageOrName])
+	const storageKey = key.join(':')
+
+	const [value, setValueInternal] = useState<T>(() => {
+		const stored = storage.get<T>(storageKey)
+		return initializer(stored)
+	})
+
+	const setValue = useCallback((update: T | ((current: T) => T)): void => {
+		setValueInternal(current => {
+			const newValue = typeof update === 'function' ? (update as (current: T) => T)(current) : update
+			storage.set(storageKey, newValue)
+			return newValue
+		})
+	}, [storage, storageKey])
+
+	return [value, setValue]
+}
+
+// ============================================================================
+// DataView Key
+// ============================================================================
+
+export function buildDataViewKey(parts: readonly string[]): string {
+	return parts.join(':')
+}

package/src/useDataGridSetup.ts

@@ -0,0 +1,230 @@
+/**
+ * Shared setup logic for DataGrid and HasManyDataGrid.
+ * Handles collection phase (JSX analysis), state management, and filter building.
+ */
+
+import React, { type ReactNode, useMemo } from 'react'
+import type {
+	EntityAccessor,
+	OrderDirection,
+	FilterHandler,
+	FilterArtifact,
+	SortingDirections,
+	DataViewLayout,
+	SelectionMeta,
+	SelectionValues,
+	SchemaRegistry,
+} from '@contember/bindx'
+import { createFullTextFilterHandler, SelectionScope, buildQueryFromSelection } from '@contember/bindx'
+import {
+	createCollectorProxy,
+	mergeSelections,
+	collectSelection,
+} from '@contember/bindx-react'
+import { ColumnLeaf, type ColumnLeafProps, analyzeChildren } 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'
+import type { StateStorageOrName } from './stateStorage.js'
+import type { DataViewContextValue, DataViewElementData } from './DataViewContext.js'
+import { DataViewElement, type DataViewElementProps } from './selectionComponents.js'
+
+export const QUERY_FILTER_NAME = '__query'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const MARKER_TYPES: ReadonlySet<React.ComponentType<any>> = new Set([
+	ColumnLeaf,
+	DataGridToolbarContent,
+	DataGridLayout,
+])
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ELEMENT_MARKER_TYPES: ReadonlySet<React.ComponentType<any>> = new Set([
+	DataViewElement,
+])
+
+export interface DataGridCommonProps<TEntity extends object> {
+	children: (it: EntityAccessor<TEntity>) => ReactNode
+	initialSorting?: Partial<Record<string, OrderDirection>>
+	itemsPerPage?: number | null
+	filter?: Record<string, unknown>
+	layouts?: readonly DataViewLayout[]
+	initialSelection?: SelectionValues
+	stateStorage?: StateStorageOrName
+	currentPageStateStorage?: StateStorageOrName
+	pagingSettingsStorage?: StateStorageOrName
+	storageKey?: string
+}
+
+export interface DataGridSetupResult {
+	childrenJsx: ReactNode
+	columns: ColumnLeafProps[]
+	selection: SelectionMeta
+	queryKey: string
+	toolbarContent: ReactNode | undefined
+	layoutRenders: Map<string, (item: DataViewContextValue['items'][number]) => ReactNode>
+	layoutElements: Map<string, readonly DataViewElementData[]>
+	effectiveLayouts: readonly DataViewLayout[]
+	filtering: ReturnType<typeof useFilteringState>
+	sorting: ReturnType<typeof useSortingState>
+	paging: ReturnType<typeof usePagingState>
+	selectionState: ReturnType<typeof useSelectionState>
+	combinedFilter: Record<string, unknown> | undefined
+}
+
+export function useDataGridSetup<TEntity extends object>({
+	entityType,
+	schemaRegistry,
+	children,
+	initialSorting,
+	itemsPerPage = 50,
+	staticFilter,
+	layouts,
+	initialSelection,
+	stateStorage,
+	currentPageStateStorage,
+	pagingSettingsStorage,
+	storageKey,
+}: {
+	entityType: string
+	schemaRegistry: SchemaRegistry | null
+	children: (it: EntityAccessor<TEntity>) => ReactNode
+	initialSorting?: Partial<Record<string, OrderDirection>>
+	itemsPerPage?: number | null
+	staticFilter?: Record<string, unknown>
+	layouts?: readonly DataViewLayout[]
+	initialSelection?: SelectionValues
+	stateStorage?: StateStorageOrName
+	currentPageStateStorage?: StateStorageOrName
+	pagingSettingsStorage?: StateStorageOrName
+	storageKey?: string
+}): DataGridSetupResult {
+	// ---- Phase 1: Collection ----
+	const { childrenJsx, columns, selection, queryKey, toolbarContent, layoutRenders, layoutElements, effectiveLayouts } = useMemo(() => {
+		const scope = new SelectionScope()
+		const collector = createCollectorProxy<TEntity>(scope, entityType, schemaRegistry ?? undefined) as unknown as EntityAccessor<TEntity>
+
+		const jsx = children(collector)
+		const analysis = analyzeChildren(jsx, MARKER_TYPES)
+
+		const cols = analysis.getAll(ColumnLeaf) as unknown as ColumnLeafProps[]
+		const toolbarMarker = analysis.getFirst(DataGridToolbarContent) as DataGridToolbarContentProps | undefined
+		const layoutMarkers = analysis.getAll(DataGridLayout) as unknown as DataGridLayoutProps[]
+
+		for (const col of cols) {
+			col.collectSelection?.(collector)
+		}
+
+		const renders = new Map<string, (item: DataViewContextValue['items'][number]) => ReactNode>()
+		const elements = new Map<string, readonly DataViewElementData[]>()
+		for (const marker of layoutMarkers) {
+			const layoutCallback = marker.children as (item: EntityAccessor<object>) => ReactNode
+			const layoutJsx = layoutCallback(collector as unknown as EntityAccessor<object>)
+			const layoutSel = collectSelection(layoutJsx)
+			mergeSelections(scope.toSelectionMeta(), layoutSel)
+			renders.set(marker.name, layoutCallback)
+
+			const elementAnalysis = analyzeChildren(layoutJsx, ELEMENT_MARKER_TYPES)
+			const elementProps = elementAnalysis.getAll(DataViewElement) as unknown as DataViewElementProps[]
+			if (elementProps.length > 0) {
+				elements.set(marker.name, elementProps.map(it => ({ name: it.name, label: it.label, fallback: it.fallback })))
+			}
+		}
+
+		const jsxSel = collectSelection(jsx)
+		const sel = scope.toSelectionMeta()
+		mergeSelections(sel, jsxSel)
+
+		const query = buildQueryFromSelection(sel)
+		const key = JSON.stringify({ entityType, query })
+
+		const autoLayouts = layouts ?? [
+			{ name: 'table', label: 'Table' },
+			...layoutMarkers.map(m => ({ name: m.name, label: m.label })),
+		]
+
+		return {
+			childrenJsx: jsx,
+			columns: cols,
+			selection: sel,
+			queryKey: key,
+			toolbarContent: toolbarMarker?.children,
+			layoutRenders: renders,
+			layoutElements: elements,
+			effectiveLayouts: autoLayouts,
+		}
+	}, [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 textFieldPaths: string[] = []
+		for (const col of columns) {
+			if (col.filterName && col.filterHandler) {
+				map.set(col.filterName, { handler: col.filterHandler })
+			}
+			if (col.isTextSearchable && col.fieldName) {
+				textFieldPaths.push(col.fieldName)
+			}
+		}
+		if (textFieldPaths.length > 0) {
+			map.set(QUERY_FILTER_NAME, { handler: createFullTextFilterHandler(textFieldPaths) })
+		}
+		return map
+	}, [columns])
+
+	const sortableFields = useMemo((): ReadonlySet<string> => {
+		const set = new Set<string>()
+		for (const col of columns) {
+			if (col.sortingField) {
+				set.add(col.sortingField)
+			}
+		}
+		return set
+	}, [columns])
+
+	const initialSortingDirs = useMemo((): SortingDirections | undefined => {
+		if (!initialSorting) return undefined
+		const dirs: Record<string, OrderDirection> = {}
+		for (const [field, dir] of Object.entries(initialSorting)) {
+			if (dir) dirs[field] = dir
+		}
+		return Object.keys(dirs).length > 0 ? dirs : undefined
+	}, [initialSorting])
+
+	const filtering = useFilteringState({ filters: filterDefs, stateStorage, storageKey })
+	const sorting = useSortingState({ sortableFields, initialSorting: initialSortingDirs, stateStorage, storageKey })
+	const paging = usePagingState({
+		initialItemsPerPage: itemsPerPage,
+		currentPageStateStorage: currentPageStateStorage ?? stateStorage,
+		pagingSettingsStorage,
+		storageKey,
+	})
+	const selectionState = useSelectionState({ layouts: effectiveLayouts, initialSelection, stateStorage, storageKey })
+
+	// ---- Phase 3: Build combined filter ----
+	const combinedFilter = useMemo((): Record<string, unknown> | undefined => {
+		const parts: Record<string, unknown>[] = []
+		if (staticFilter) parts.push(staticFilter as Record<string, unknown>)
+		if (filtering.resolvedWhere) parts.push(filtering.resolvedWhere)
+		if (parts.length === 0) return undefined
+		if (parts.length === 1) return parts[0]
+		return { and: parts }
+	}, [staticFilter, filtering.resolvedWhere])
+
+	return {
+		childrenJsx,
+		columns,
+		selection,
+		queryKey,
+		toolbarContent,
+		layoutRenders,
+		layoutElements,
+		effectiveLayouts,
+		filtering,
+		sorting,
+		paging,
+		selectionState,
+		combinedFilter,
+	}
+}

package/src/useDataView.ts

@@ -0,0 +1,148 @@
+/**
+ * useDataView — low-level hook for building custom data views.
+ *
+ * Manages filtering, sorting, paging, and selection state, and loads data
+ * from the backend adapter. This is the hook API that DataGrid
+ * uses internally, exposed for building custom grid/list UIs.
+ */
+
+import { useMemo } from 'react'
+import type {
+	EntityDef,
+	EntityAccessor,
+	FilterHandler,
+	FilterArtifact,
+	SelectionMeta,
+	FieldError,
+	SortingDirections,
+	DataViewLayout,
+	SelectionValues,
+} from '@contember/bindx'
+import { useEntityList } from '@contember/bindx-react'
+import {
+	useFilteringState,
+	useSortingState,
+	usePagingState,
+	useSelectionState,
+	type FilteringState,
+	type SortingStateResult,
+	type PagingStateResult,
+	type SelectionStateResult,
+} from './useDataViewState.js'
+import type { StateStorageOrName } from './stateStorage.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseDataViewOptions {
+	/** Filter definitions: name → { handler, initialArtifact? } */
+	filters?: ReadonlyMap<string, { handler: FilterHandler<FilterArtifact>; initialArtifact?: FilterArtifact }>
+	/** Fields that can be sorted */
+	sortableFields?: ReadonlySet<string>
+	/** Initial sorting directions (supports multi-column) */
+	initialSorting?: SortingDirections
+	/** Items per page. null = show all. Default: 50 */
+	itemsPerPage?: number | null
+	/** Static filter (always applied) */
+	filter?: Record<string, unknown>
+	/** Selection metadata for building the query */
+	selection: SelectionMeta
+	/** Available layouts */
+	layouts?: readonly DataViewLayout[]
+	/** Initial selection (layout + visibility) */
+	initialSelection?: SelectionValues
+	/** State storage for filter/sorting/selection state */
+	stateStorage?: StateStorageOrName
+	/** State storage for current page (typically 'url') */
+	currentPageStateStorage?: StateStorageOrName
+	/** State storage for page size preference (typically 'session' or 'local') */
+	pagingSettingsStorage?: StateStorageOrName
+	/** Storage key prefix for isolation */
+	storageKey?: string
+}
+
+export interface DataViewResult {
+	/** Current load status */
+	readonly status: 'loading' | 'error' | 'ready'
+	/** Error if status is 'error' */
+	readonly error?: FieldError
+	/** Loaded items as entity accessors */
+	readonly items: readonly EntityAccessor<object>[]
+	/** Filtering state and controls */
+	readonly filtering: FilteringState
+	/** Sorting state and controls */
+	readonly sorting: SortingStateResult
+	/** Paging state and controls */
+	readonly paging: PagingStateResult
+	/** Selection state (visibility + layout) */
+	readonly selection: SelectionStateResult
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+const EMPTY_FILTERS = new Map<string, { handler: FilterHandler<FilterArtifact> }>()
+const EMPTY_SORTABLE = new Set<string>()
+
+export function useDataView(
+	entity: EntityDef,
+	options: UseDataViewOptions,
+): DataViewResult {
+	const {
+		filters: filterDefs = EMPTY_FILTERS,
+		sortableFields = EMPTY_SORTABLE,
+		initialSorting,
+		itemsPerPage = 50,
+		filter: staticFilter,
+		selection,
+		layouts,
+		initialSelection,
+		stateStorage,
+		currentPageStateStorage,
+		pagingSettingsStorage,
+		storageKey,
+	} = options
+
+	const filtering = useFilteringState({ filters: filterDefs, stateStorage, storageKey })
+	const sorting = useSortingState({ sortableFields, initialSorting, stateStorage, storageKey })
+	const paging = usePagingState({
+		initialItemsPerPage: itemsPerPage,
+		currentPageStateStorage: currentPageStateStorage ?? stateStorage,
+		pagingSettingsStorage,
+		storageKey,
+	})
+	const selectionState = useSelectionState({ layouts, initialSelection, stateStorage, storageKey })
+
+	// Combine static + dynamic filters
+	const combinedFilter = useMemo((): Record<string, unknown> | undefined => {
+		const parts: Record<string, unknown>[] = []
+		if (staticFilter) parts.push(staticFilter)
+		if (filtering.resolvedWhere) parts.push(filtering.resolvedWhere)
+		if (parts.length === 0) return undefined
+		if (parts.length === 1) return parts[0]
+		return { and: parts }
+	}, [staticFilter, filtering.resolvedWhere])
+
+	// Load data
+	const result = useEntityList(entity, {
+		filter: combinedFilter,
+		orderBy: sorting.resolvedOrderBy,
+		limit: paging.queryLimit,
+		offset: paging.queryOffset,
+		selection,
+	})
+
+	const items = result.status === 'ready' ? result.items : []
+
+	return {
+		status: result.status,
+		error: result.status === 'error' ? result.error : undefined,
+		items,
+		filtering,
+		sorting,
+		paging,
+		selection: selectionState,
+	}
+}