@contember/bindx 0.1.0

package/src/dataview/filterHandlers.ts

@@ -0,0 +1,443 @@
+/**
+ * Built-in filter handler implementations.
+ *
+ * Each handler converts a typed filter artifact into a Contember-style
+ * EntityWhere clause for use with the backend adapter.
+ */
+
+import type {
+	FilterHandler,
+	TextFilterArtifact,
+	NumberFilterArtifact,
+	NumberRangeFilterArtifact,
+	DateFilterArtifact,
+	BooleanFilterArtifact,
+	EnumFilterArtifact,
+	EnumListFilterArtifact,
+	RelationFilterArtifact,
+	IsDefinedFilterArtifact,
+} from './types.js'
+
+// ============================================================================
+// Text Filter
+// ============================================================================
+
+export function createTextFilterHandler(fieldPath: string): FilterHandler<TextFilterArtifact> {
+	return {
+		defaultArtifact(): TextFilterArtifact {
+			return { mode: 'contains', query: '' }
+		},
+
+		isActive(artifact: TextFilterArtifact): boolean {
+			return artifact.query.length > 0 || artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: TextFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.query.length > 0) {
+				const fieldCondition = buildTextCondition(artifact.mode, artifact.query)
+				conditions.push(buildNestedWhere(fieldPath, fieldCondition))
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+function buildTextCondition(mode: TextFilterArtifact['mode'], query: string): Record<string, unknown> {
+	switch (mode) {
+		case 'contains':
+			return { containsCI: query }
+		case 'startsWith':
+			return { startsWithCI: query }
+		case 'endsWith':
+			return { endsWithCI: query }
+		case 'equals':
+			return { eq: query }
+		case 'notContains':
+			return { not: { containsCI: query } }
+	}
+}
+
+// ============================================================================
+// Full Text Filter (across multiple fields)
+// ============================================================================
+
+export function createFullTextFilterHandler(fieldPaths: readonly string[]): FilterHandler<TextFilterArtifact> {
+	return {
+		defaultArtifact(): TextFilterArtifact {
+			return { mode: 'contains', query: '' }
+		},
+
+		isActive(artifact: TextFilterArtifact): boolean {
+			return artifact.query.length > 0
+		},
+
+		toWhere(artifact: TextFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions = fieldPaths.map(fieldPath => {
+				const fieldCondition = buildTextCondition(artifact.mode, artifact.query)
+				return buildNestedWhere(fieldPath, fieldCondition)
+			})
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { or: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Number Filter
+// ============================================================================
+
+export function createNumberFilterHandler(fieldPath: string): FilterHandler<NumberFilterArtifact> {
+	return {
+		defaultArtifact(): NumberFilterArtifact {
+			return { mode: 'eq', value: null }
+		},
+
+		isActive(artifact: NumberFilterArtifact): boolean {
+			return artifact.value !== null || artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: NumberFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.value !== null) {
+				conditions.push(buildNestedWhere(fieldPath, { [artifact.mode]: artifact.value }))
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Number Range Filter
+// ============================================================================
+
+export function createNumberRangeFilterHandler(fieldPath: string): FilterHandler<NumberRangeFilterArtifact> {
+	return {
+		defaultArtifact(): NumberRangeFilterArtifact {
+			return { min: null, max: null }
+		},
+
+		isActive(artifact: NumberRangeFilterArtifact): boolean {
+			return artifact.min !== null || artifact.max !== null || artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: NumberRangeFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.min !== null) {
+				conditions.push(buildNestedWhere(fieldPath, { gte: artifact.min }))
+			}
+
+			if (artifact.max !== null) {
+				conditions.push(buildNestedWhere(fieldPath, { lte: artifact.max }))
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Date Filter
+// ============================================================================
+
+export function createDateFilterHandler(fieldPath: string): FilterHandler<DateFilterArtifact> {
+	return {
+		defaultArtifact(): DateFilterArtifact {
+			return { start: null, end: null }
+		},
+
+		isActive(artifact: DateFilterArtifact): boolean {
+			return artifact.start !== null || artifact.end !== null || artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: DateFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.start !== null) {
+				const normalized = new Date(artifact.start + 'T00:00:00')
+				if (!isNaN(normalized.getTime())) {
+					conditions.push(buildNestedWhere(fieldPath, { gte: toLocalIsoString(normalized) }))
+				}
+			}
+
+			if (artifact.end !== null) {
+				const normalized = new Date(artifact.end + 'T00:00:00')
+				if (!isNaN(normalized.getTime())) {
+					// End date is inclusive — advance to start of next day
+					normalized.setDate(normalized.getDate() + 1)
+					conditions.push(buildNestedWhere(fieldPath, { lt: toLocalIsoString(normalized) }))
+				}
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Boolean Filter
+// ============================================================================
+
+export function createBooleanFilterHandler(fieldPath: string): FilterHandler<BooleanFilterArtifact> {
+	return {
+		defaultArtifact(): BooleanFilterArtifact {
+			return {}
+		},
+
+		isActive(artifact: BooleanFilterArtifact): boolean {
+			return artifact.includeTrue === true || artifact.includeFalse === true || artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: BooleanFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.includeTrue && artifact.includeFalse) {
+				// Both selected — matches all, no field condition needed
+			} else if (artifact.includeTrue) {
+				conditions.push(buildNestedWhere(fieldPath, { eq: true }))
+			} else if (artifact.includeFalse) {
+				conditions.push(buildNestedWhere(fieldPath, { eq: false }))
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Enum Filter
+// ============================================================================
+
+export function createEnumFilterHandler(fieldPath: string): FilterHandler<EnumFilterArtifact> {
+	return {
+		defaultArtifact(): EnumFilterArtifact {
+			return {}
+		},
+
+		isActive(artifact: EnumFilterArtifact): boolean {
+			return (artifact.values !== undefined && artifact.values.length > 0)
+				|| (artifact.notValues !== undefined && artifact.notValues.length > 0)
+				|| artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: EnumFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.values !== undefined && artifact.values.length > 0) {
+				conditions.push(buildNestedWhere(fieldPath, { in: artifact.values }))
+			}
+
+			if (artifact.notValues !== undefined && artifact.notValues.length > 0) {
+				conditions.push(buildNestedWhere(fieldPath, { notIn: artifact.notValues }))
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Enum List Filter (for array enum fields)
+// ============================================================================
+
+export function createEnumListFilterHandler(fieldPath: string): FilterHandler<EnumListFilterArtifact> {
+	return {
+		defaultArtifact(): EnumListFilterArtifact {
+			return {}
+		},
+
+		isActive(artifact: EnumListFilterArtifact): boolean {
+			return (artifact.values !== undefined && artifact.values.length > 0)
+				|| (artifact.notValues !== undefined && artifact.notValues.length > 0)
+				|| artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: EnumListFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.values !== undefined && artifact.values.length > 0) {
+				const valueConds = artifact.values.map(v =>
+					buildNestedWhere(fieldPath, { includes: v }),
+				)
+				conditions.push(valueConds.length === 1 ? valueConds[0]! : { or: valueConds })
+			}
+
+			if (artifact.notValues !== undefined && artifact.notValues.length > 0) {
+				const valueConds = artifact.notValues.map(v =>
+					buildNestedWhere(fieldPath, { includes: v }),
+				)
+				const inner = valueConds.length === 1 ? valueConds[0]! : { or: valueConds }
+				conditions.push({ not: inner })
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { isNull: artifact.nullCondition }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// Relation Filter (HasOne / HasMany)
+// ============================================================================
+
+export function createRelationFilterHandler(fieldPath: string): FilterHandler<RelationFilterArtifact> {
+	return {
+		defaultArtifact(): RelationFilterArtifact {
+			return {}
+		},
+
+		isActive(artifact: RelationFilterArtifact): boolean {
+			return (artifact.id !== undefined && artifact.id.length > 0)
+				|| (artifact.notId !== undefined && artifact.notId.length > 0)
+				|| artifact.nullCondition !== undefined
+		},
+
+		toWhere(artifact: RelationFilterArtifact): Record<string, unknown> | undefined {
+			if (!this.isActive(artifact)) return undefined
+
+			const conditions: Record<string, unknown>[] = []
+
+			if (artifact.id !== undefined && artifact.id.length > 0) {
+				const idCondition = artifact.id.length === 1
+					? { eq: artifact.id[0] }
+					: { in: artifact.id }
+				conditions.push(buildNestedWhere(fieldPath, { id: idCondition }))
+			}
+
+			if (artifact.notId !== undefined && artifact.notId.length > 0) {
+				const idCondition = artifact.notId.length === 1
+					? { eq: artifact.notId[0] }
+					: { in: artifact.notId }
+				conditions.push({ not: buildNestedWhere(fieldPath, { id: idCondition }) })
+			}
+
+			if (artifact.nullCondition !== undefined) {
+				conditions.push(buildNestedWhere(fieldPath, { id: { isNull: artifact.nullCondition } }))
+			}
+
+			if (conditions.length === 0) return undefined
+			if (conditions.length === 1) return conditions[0]
+			return { and: conditions }
+		},
+	}
+}
+
+// ============================================================================
+// IsDefined Filter
+// ============================================================================
+
+export function createIsDefinedFilterHandler(fieldPath: string): FilterHandler<IsDefinedFilterArtifact> {
+	return {
+		defaultArtifact(): IsDefinedFilterArtifact {
+			return { defined: null }
+		},
+
+		isActive(artifact: IsDefinedFilterArtifact): boolean {
+			return artifact.defined !== null
+		},
+
+		toWhere(artifact: IsDefinedFilterArtifact): Record<string, unknown> | undefined {
+			if (artifact.defined === null) return undefined
+			return buildNestedWhere(fieldPath, { isNull: !artifact.defined })
+		},
+	}
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Format a Date as ISO string with local timezone offset.
+ * e.g. 2024-01-15T00:00:00+01:00
+ */
+function toLocalIsoString(date: Date): string {
+	const tzo = -date.getTimezoneOffset()
+	const sign = tzo >= 0 ? '+' : '-'
+	const pad = (n: number, len = 2): string => String(n).padStart(len, '0')
+
+	return (
+		pad(date.getFullYear(), 4) + '-' + pad(date.getMonth() + 1) + '-' + pad(date.getDate()) +
+		'T' + pad(date.getHours()) + ':' + pad(date.getMinutes()) + ':' + pad(date.getSeconds()) +
+		sign + pad(Math.floor(Math.abs(tzo) / 60)) + ':' + pad(Math.abs(tzo) % 60)
+	)
+}
+
+/**
+ * Builds a nested where clause from a dot-separated field path.
+ * e.g., "author.name" → { author: { name: condition } }
+ */
+function buildNestedWhere(fieldPath: string, condition: Record<string, unknown>): Record<string, unknown> {
+	const parts = fieldPath.split('.')
+	let result = condition
+
+	for (let i = parts.length - 1; i >= 0; i--) {
+		result = { [parts[i]!]: result }
+	}
+
+	return result
+}

package/src/dataview/index.ts

@@ -0,0 +1,36 @@
+export type {
+	TextFilterArtifact,
+	NumberFilterArtifact,
+	NumberRangeFilterArtifact,
+	DateFilterArtifact,
+	BooleanFilterArtifact,
+	EnumFilterArtifact,
+	EnumListFilterArtifact,
+	RelationFilterArtifact,
+	IsDefinedFilterArtifact,
+	FilterArtifact,
+	FilterHandler,
+	ColumnType,
+	ColumnDefinition,
+	SortingDirections,
+	SortingDirectionAction,
+	SortingState,
+	PagingState,
+	PagingInfo,
+	DataViewLayout,
+	SelectionValues,
+	SelectionState,
+} from './types.js'
+
+export {
+	createTextFilterHandler,
+	createFullTextFilterHandler,
+	createNumberFilterHandler,
+	createNumberRangeFilterHandler,
+	createDateFilterHandler,
+	createBooleanFilterHandler,
+	createEnumFilterHandler,
+	createEnumListFilterHandler,
+	createRelationFilterHandler,
+	createIsDefinedFilterHandler,
+} from './filterHandlers.js'

package/src/dataview/types.ts

@@ -0,0 +1,220 @@
+/**
+ * Core types for the DataView/DataGrid system.
+ *
+ * These types are framework-agnostic and define the filter artifact system,
+ * filter handlers, sorting state, and paging state.
+ */
+
+import type { ReactNode } from 'react'
+import type { EntityWhere, EntityOrderBy, OrderDirection } from '../selection/queryTypes.js'
+
+// ============================================================================
+// Filter Artifact Types
+// ============================================================================
+
+/**
+ * Text filter artifact - stored as user's filter state
+ */
+export interface TextFilterArtifact {
+	readonly mode: 'contains' | 'startsWith' | 'endsWith' | 'equals' | 'notContains'
+	readonly query: string
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Number filter artifact
+ */
+export interface NumberFilterArtifact {
+	readonly mode: 'eq' | 'gt' | 'gte' | 'lt' | 'lte'
+	readonly value: number | null
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Number range filter artifact
+ */
+export interface NumberRangeFilterArtifact {
+	readonly min: number | null
+	readonly max: number | null
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Date filter artifact
+ */
+export interface DateFilterArtifact {
+	readonly start: string | null
+	readonly end: string | null
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Boolean filter artifact
+ */
+export interface BooleanFilterArtifact {
+	readonly includeTrue?: boolean
+	readonly includeFalse?: boolean
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Enum filter artifact
+ */
+export interface EnumFilterArtifact {
+	readonly values?: readonly string[]
+	readonly notValues?: readonly string[]
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Relation filter artifact (hasOne/hasMany)
+ */
+export interface RelationFilterArtifact {
+	readonly id?: readonly string[]
+	readonly notId?: readonly string[]
+	readonly nullCondition?: boolean
+}
+
+/**
+ * Enum list filter artifact - for array enum fields (uses 'includes' condition)
+ */
+export interface EnumListFilterArtifact {
+	readonly values?: readonly string[]
+	readonly notValues?: readonly string[]
+	readonly nullCondition?: boolean
+}
+
+/**
+ * IsDefined filter artifact
+ */
+export interface IsDefinedFilterArtifact {
+	readonly defined: boolean | null
+}
+
+/**
+ * Union of all filter artifact types
+ */
+export type FilterArtifact =
+	| TextFilterArtifact
+	| NumberFilterArtifact
+	| NumberRangeFilterArtifact
+	| DateFilterArtifact
+	| BooleanFilterArtifact
+	| EnumFilterArtifact
+	| EnumListFilterArtifact
+	| RelationFilterArtifact
+	| IsDefinedFilterArtifact
+
+// ============================================================================
+// Filter Handler
+// ============================================================================
+
+/**
+ * Filter handler converts a filter artifact into an EntityWhere clause.
+ * Returns undefined when the filter is not active (artifact is empty/default).
+ */
+export interface FilterHandler<TArtifact = FilterArtifact> {
+	/** Convert artifact to where clause */
+	toWhere(artifact: TArtifact): Record<string, unknown> | undefined
+
+	/** Check if artifact represents an active filter */
+	isActive(artifact: TArtifact): boolean
+
+	/** Create default (empty/inactive) artifact */
+	defaultArtifact(): TArtifact
+}
+
+// ============================================================================
+// Column Definition Types
+// ============================================================================
+
+/**
+ * Column type discriminator
+ */
+export type ColumnType = 'text' | 'number' | 'date' | 'dateTime' | 'boolean' | 'enum' | 'enumList' | 'uuid' | 'isDefined' | 'hasOne' | 'hasMany' | 'action' | 'custom'
+
+/**
+ * Base column definition - framework-agnostic metadata
+ */
+export interface ColumnDefinition {
+	/** Column type */
+	readonly type: ColumnType
+	/** Field name on the entity (null for action columns) */
+	readonly field: string | null
+	/** Whether this column supports sorting */
+	readonly sortable: boolean
+	/** Filter handler for this column (null if no filtering) */
+	readonly filterHandler: FilterHandler | null
+	/** Initial filter artifact (null if no filtering) */
+	readonly filterArtifact: FilterArtifact | null
+}
+
+// ============================================================================
+// Sorting State
+// ============================================================================
+
+/**
+ * Sorting directions - map of field → direction.
+ * Supports multi-column sorting (order of keys = sort priority).
+ */
+export type SortingDirections = Readonly<Record<string, OrderDirection>>
+
+/**
+ * Sorting direction action for triggers
+ */
+export type SortingDirectionAction = OrderDirection | 'next' | 'toggleAsc' | 'toggleDesc' | 'clear'
+
+/**
+ * Sorting state - supports multiple sorted columns
+ */
+export interface SortingState {
+	readonly directions: SortingDirections
+}
+
+// ============================================================================
+// Selection State (Column Visibility + Layout)
+// ============================================================================
+
+/**
+ * Layout definition for DataView
+ */
+export interface DataViewLayout {
+	readonly name: string
+	readonly label?: ReactNode
+}
+
+/**
+ * Selection values - current layout + column visibility
+ */
+export interface SelectionValues {
+	readonly layout?: string
+	readonly visibility: Readonly<Record<string, boolean>>
+}
+
+/**
+ * Selection state - includes values + available layouts
+ */
+export interface SelectionState {
+	readonly values: SelectionValues
+	readonly layouts: readonly DataViewLayout[]
+}
+
+// ============================================================================
+// Paging State
+// ============================================================================
+
+/**
+ * Paging state
+ */
+export interface PagingState {
+	readonly pageIndex: number
+	readonly itemsPerPage: number
+}
+
+/**
+ * Paging info (computed from state + data)
+ */
+export interface PagingInfo {
+	readonly totalCount: number | null
+	readonly totalPages: number | null
+}