@contember/bindx-dataview 0.1.0

package/src/contextHooks.ts

@@ -0,0 +1,157 @@
+/**
+ * Fine-grained context hooks matching Contember's react-dataview API.
+ *
+ * These hooks provide convenient access to specific parts of the DataView context,
+ * matching Contember's pattern of separate state/methods hooks per concern.
+ */
+
+import { useMemo } from 'react'
+import { useDataViewContext } from './DataViewContext.js'
+import type { DataViewElementData } from './DataViewContext.js'
+import type { FilteringState, SortingStateResult, PagingStateResult, SelectionStateResult } from './useDataViewState.js'
+import type {
+	SortingState,
+	SortingDirectionAction,
+	PagingState,
+	PagingInfo,
+	OrderDirection,
+	FilterHandler,
+	FilterArtifact,
+	DataViewLayout,
+	FieldRefBase,
+} from '@contember/bindx'
+
+// ============================================================================
+// Sorting
+// ============================================================================
+
+export interface DataViewSortingMethods {
+	setOrderBy<T>(field: FieldRefBase<T>, action: SortingDirectionAction, append?: boolean): void
+}
+
+export function useDataViewSortingState(): SortingState {
+	return useDataViewContext().sorting.state
+}
+
+export function useDataViewSortingMethods(): DataViewSortingMethods {
+	const { sorting } = useDataViewContext()
+	return useMemo(() => ({ setOrderBy: sorting.setOrderBy }), [sorting.setOrderBy])
+}
+
+export function useDataViewSortingDirection<T>(field: FieldRefBase<T>): OrderDirection | null {
+	return useDataViewContext().sorting.directionOf(field)
+}
+
+// ============================================================================
+// Paging
+// ============================================================================
+
+export interface DataViewPagingMethods {
+	goToPage(page: number | 'first' | 'next' | 'previous' | 'last'): void
+	setItemsPerPage(count: number | null): void
+	refreshTotalCount(): void
+}
+
+export function useDataViewPagingState(): PagingState {
+	return useDataViewContext().paging.state
+}
+
+export function useDataViewPagingInfo(): PagingInfo {
+	return useDataViewContext().paging.info
+}
+
+export function useDataViewPagingMethods(): DataViewPagingMethods {
+	const { paging } = useDataViewContext()
+	return useMemo((): DataViewPagingMethods => ({
+		goToPage: (page: number | 'first' | 'next' | 'previous' | 'last'): void => {
+			if (page === 'first') paging.first()
+			else if (page === 'last') paging.last()
+			else if (page === 'next') paging.next()
+			else if (page === 'previous') paging.previous()
+			else paging.goTo(page)
+		},
+		setItemsPerPage: paging.setItemsPerPage,
+		refreshTotalCount: paging.refreshTotalCount,
+	}), [paging])
+}
+
+// ============================================================================
+// Filtering
+// ============================================================================
+
+export interface DataViewFilteringMethods {
+	setFilter(name: string, artifact: FilterArtifact): void
+}
+
+export function useDataViewFilteringState(): FilteringState {
+	return useDataViewContext().filtering
+}
+
+export function useDataViewFilteringMethods(): DataViewFilteringMethods {
+	const { filtering } = useDataViewContext()
+	return useMemo(() => ({ setFilter: filtering.setArtifact }), [filtering.setArtifact])
+}
+
+export function useDataViewFilterHandlerRegistry(): ReadonlyMap<string, { handler: FilterHandler<FilterArtifact> }> {
+	return useDataViewContext().filtering.filters
+}
+
+// ============================================================================
+// Selection
+// ============================================================================
+
+export interface DataViewSelectionState {
+	readonly layout: string | undefined
+	readonly visibility: Record<string, boolean | undefined>
+	readonly layouts: readonly DataViewLayout[]
+}
+
+export interface DataViewSelectionMethods {
+	setLayout(layout: string | undefined): void
+	setVisibility(name: string, visible: boolean): void
+}
+
+export function useDataViewSelectionState(): DataViewSelectionState {
+	const { selection } = useDataViewContext()
+	return useMemo((): DataViewSelectionState => ({
+		layout: selection.currentLayout,
+		visibility: selection.state.values.visibility ?? {},
+		layouts: selection.state.layouts,
+	}), [selection.currentLayout, selection.state.values.visibility, selection.state.layouts])
+}
+
+export function useDataViewSelectionMethods(): DataViewSelectionMethods {
+	const { selection } = useDataViewContext()
+	return useMemo(() => ({
+		setLayout: selection.setLayout,
+		setVisibility: selection.setVisibility,
+	}), [selection.setLayout, selection.setVisibility])
+}
+
+// ============================================================================
+// Elements (visibility-togglable items)
+// ============================================================================
+
+export type { DataViewElementData } from './DataViewContext.js'
+
+export function useDataViewElements(): readonly DataViewElementData[] {
+	const { columns, selection, layoutElements } = useDataViewContext()
+	const currentLayout = selection.currentLayout
+
+	return useMemo((): readonly DataViewElementData[] => {
+		// If the active layout has explicitly declared elements, use those
+		if (currentLayout) {
+			const elements = layoutElements.get(currentLayout)
+			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: true,
+			}))
+	}, [columns, currentLayout, layoutElements])
+}

package/src/createColumn.ts

@@ -0,0 +1,128 @@
+/**
+ * `createColumn()` — factory for building column components from a column type definition.
+ *
+ * Layer 2 in the column architecture: wraps a headless `ColumnTypeDef` with
+ * rendering configuration (cell renderer, optional filter renderer) to produce
+ * a React component usable inside a DataGrid children render function.
+ */
+
+import React from 'react'
+import type { FieldRefBase, FilterArtifact, FilterHandler, EntityAccessor } from '@contember/bindx'
+import type { ColumnTypeDef } from './columnTypes.js'
+import { ColumnLeaf, type ColumnLeafProps } from './columnLeaf.js'
+import { extractFieldName, extractEnumName } from './columns.js'
+
+// ============================================================================
+// Render Props
+// ============================================================================
+
+export interface ColumnRenderProps<TValue> {
+	readonly value: TValue
+	readonly accessor: EntityAccessor<object>
+	readonly fieldRef: FieldRefBase<unknown> | null
+	readonly fieldName: string | null
+}
+
+export interface FilterRenderProps<TFilterArtifact> {
+	readonly artifact: TFilterArtifact
+	readonly setArtifact: (artifact: TFilterArtifact) => void
+}
+
+// ============================================================================
+// Config
+// ============================================================================
+
+export interface CreateColumnConfig<TValue, TFilterArtifact extends FilterArtifact> {
+	readonly renderCell: (props: ColumnRenderProps<TValue>) => React.ReactNode
+	readonly renderFilter?: (props: FilterRenderProps<TFilterArtifact>) => React.ReactNode
+}
+
+// ============================================================================
+// Column Component Props
+// ============================================================================
+
+export interface ColumnComponentProps<TValue = unknown> {
+	field: FieldRefBase<TValue>
+	header?: React.ReactNode
+	sortable?: boolean
+	filter?: boolean
+	children?: (value: TValue | null, accessor: EntityAccessor<object>) => React.ReactNode
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+export interface ColumnComponent<TExtraProps = object> {
+	<T>(props: ColumnComponentProps<T> & TExtraProps): null
+	staticRender: (props: Record<string, unknown>) => React.ReactNode
+}
+
+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 {
+		return null
+	}
+
+	Column.staticRender = (props: Record<string, unknown>): React.ReactNode => {
+		const fieldRef = props['field'] as FieldRefBase<unknown> | undefined
+		const fieldName = fieldRef ? extractFieldName(fieldRef) : null
+		const header = props['header'] as React.ReactNode | undefined
+		const sortable = (props['sortable'] as boolean | undefined) ?? columnType.defaultSortable
+		const filterEnabled = (props['filter'] as boolean | undefined) ?? false
+		const children = props['children'] as ((value: TValue | null, accessor: EntityAccessor<object>) => React.ReactNode) | undefined
+		const rawOptions = props['options'] as readonly string[] | Readonly<Record<string, React.ReactNode>> | undefined
+		const enumOptions = Array.isArray(rawOptions)
+			? Object.fromEntries(rawOptions.map(v => [v, v])) as Readonly<Record<string, React.ReactNode>>
+			: rawOptions
+		const enumName = extractEnumName(fieldRef)
+
+		const renderCell = children
+			? (accessor: EntityAccessor<object>): React.ReactNode => {
+				const value = fieldName
+					? columnType.extractValue(accessor, fieldName)
+					: null as TValue
+				return children(value, accessor)
+			}
+			: (accessor: EntityAccessor<object>): React.ReactNode => {
+				const value = fieldName
+					? columnType.extractValue(accessor, fieldName)
+					: null as TValue
+				return config.renderCell({
+					value,
+					accessor,
+					fieldRef: fieldRef ?? null,
+					fieldName,
+				})
+			}
+
+		const leafProps = {
+			name: fieldName ?? `col-${Math.random().toString(36).slice(2, 8)}`,
+			fieldName,
+			fieldRef: fieldRef ?? null,
+			sortingField: sortable && fieldName ? fieldName : null,
+			filterName: filterEnabled && fieldName ? fieldName : null,
+			filterHandler: filterEnabled && fieldName
+				? columnType.createFilterHandler(fieldName) as FilterHandler<FilterArtifact>
+				: undefined,
+			isTextSearchable: columnType.isTextSearchable,
+			columnType: columnType.name as ColumnLeafProps['columnType'],
+			enumName,
+			enumOptions,
+			header,
+			renderCell,
+			renderFilter: config.renderFilter
+				? ({ artifact, setArtifact }: { artifact: unknown; setArtifact: (artifact: FilterArtifact) => void }) => config.renderFilter!({
+					artifact: artifact as TFilterArtifact,
+					setArtifact: setArtifact as (artifact: TFilterArtifact) => void,
+				})
+				: undefined,
+		}
+
+		return React.createElement(ColumnLeaf, leafProps as ColumnLeafProps)
+	}
+
+	return Column as ColumnComponent<TExtraProps>
+}

package/src/createRelationColumn.tsx

@@ -0,0 +1,203 @@
+/**
+ * `createRelationColumn()` — factory for building relation column components (hasOne, hasMany).
+ *
+ * Parallel to `createColumn()` for scalar types. Handles:
+ * - Related entity metadata extraction (entityName, selection)
+ * - Collection phase (collectSelection)
+ * - Filter item rendering (renderFilterItem)
+ * - Cell rendering with children render function
+ *
+ * UI layers provide renderFilter and renderCellWrapper via config.
+ */
+
+import React from 'react'
+import type { FieldRefBase, FilterArtifact, FilterHandler, EntityAccessor, SelectionMeta } from '@contember/bindx'
+import { SelectionScope } from '@contember/bindx'
+import { createCollectorProxy } from '@contember/bindx-react'
+import type { ColumnTypeDef } from './columnTypes.js'
+import { accessField } from './columnTypes.js'
+
+/** If a render result is a FieldRef-like object with `.value`, extract the string value. */
+function unwrapRenderResult(result: React.ReactNode): React.ReactNode {
+	if (result && typeof result === 'object' && 'value' in result) {
+		const val = (result as { value: unknown }).value
+		return val != null ? String(val) : ''
+	}
+	return result
+}
+import { ColumnLeaf, type ColumnLeafProps } from './columnLeaf.js'
+import { extractFieldName, extractRelatedEntityName, getRelatedAccessor } from './columns.js'
+
+// ============================================================================
+// Config
+// ============================================================================
+
+export interface RelationColumnConfig {
+	/** Renders the filter UI in column header popover. Receives relation context. */
+	readonly renderFilter?: (ctx: RelationFilterContext) => React.ReactNode
+	/** Wraps cell content (e.g. tooltip with filter actions). */
+	readonly renderCellWrapper?: (ctx: RelationCellWrapperContext) => React.ReactNode
+}
+
+export interface RelationFilterContext {
+	readonly filterName: string
+	readonly entityName: string
+	readonly selection: SelectionMeta
+	readonly renderItem: (accessor: EntityAccessor<object>) => React.ReactNode
+}
+
+export interface RelationCellWrapperContext {
+	readonly content: React.ReactNode
+	readonly item: EntityAccessor<object>
+	readonly fieldName: string
+	readonly filterName: string
+	readonly fieldRef: FieldRefBase<unknown>
+}
+
+// ============================================================================
+// Props
+// ============================================================================
+
+export interface RelationColumnProps<TEntity, TSelected> {
+	field: object
+	header?: React.ReactNode
+	filter?: boolean
+	renderCellWrapper?: (content: React.ReactNode, item: EntityAccessor<object>) => React.ReactNode
+	children: (entity: EntityAccessor<TEntity, TSelected>) => React.ReactNode
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+interface RelationCellConfig {
+	/** How to collect selection for the relation (differs between hasOne and hasMany) */
+	collectSelection: (renderer: (ref: unknown) => React.ReactNode, fieldRef: FieldRefBase<unknown>) => void
+	/** How to render the cell content (differs between hasOne and hasMany) */
+	renderCell: (accessor: EntityAccessor<object>, fieldName: string, renderer: (ref: unknown) => React.ReactNode) => React.ReactNode
+}
+
+export function createRelationColumn<TFilterArtifact extends FilterArtifact>(
+	columnType: ColumnTypeDef<unknown, TFilterArtifact>,
+	cellConfig: RelationCellConfig,
+	uiConfig: RelationColumnConfig = {},
+) {
+	function buildLeaf(props: Record<string, unknown>): ColumnLeafProps {
+		const fieldRef = props['field'] as FieldRefBase<unknown> | undefined
+		const fieldName = fieldRef ? extractFieldName(fieldRef) : null
+		const renderer = props['children'] as ((ref: unknown) => React.ReactNode) | undefined
+		const header = props['header'] as React.ReactNode | undefined
+		const filterEnabled = (props['filter'] as boolean | undefined) ?? true
+		const customCellWrapper = props['renderCellWrapper'] as ((content: React.ReactNode, item: EntityAccessor<object>) => React.ReactNode) | undefined
+
+		const relatedEntityName = extractRelatedEntityName(fieldRef) ?? ''
+
+		// Collect selection metadata for the related entity (for filter fetching)
+		let relatedSelection: SelectionMeta = { fields: new Map() }
+		if (relatedEntityName && renderer) {
+			const scope = new SelectionScope()
+			const proxy = createCollectorProxy(scope, relatedEntityName)
+			renderer(proxy)
+			relatedSelection = scope.toSelectionMeta()
+		}
+
+		const renderFilterItem = renderer
+			? (accessor: EntityAccessor<object>): React.ReactNode => unwrapRenderResult(renderer(accessor))
+			: (() => null)
+
+		const filterName = filterEnabled && fieldName ? fieldName : null
+
+		// Resolve renderFilter — use UI config, or leave undefined (headless)
+		// Note: relation filter UI ignores artifact/setArtifact (uses hooks internally)
+		const renderFilter = filterName && relatedEntityName && uiConfig.renderFilter
+			? (_filterProps: { artifact: FilterArtifact; setArtifact: (artifact: FilterArtifact) => void }) =>
+				uiConfig.renderFilter!({ filterName, entityName: relatedEntityName, selection: relatedSelection, renderItem: renderFilterItem })
+			: undefined
+
+		// Resolve renderCellWrapper — user prop overrides UI config default
+		const resolvedCellWrapper = customCellWrapper
+			?? (filterName && fieldName && fieldRef && uiConfig.renderCellWrapper
+				? (content: React.ReactNode, item: EntityAccessor<object>) =>
+					uiConfig.renderCellWrapper!({ content, item, fieldName, filterName, fieldRef })
+				: undefined)
+
+		return {
+			name: fieldName ?? `col-${Math.random().toString(36).slice(2, 8)}`,
+			fieldName,
+			fieldRef: fieldRef ?? null,
+			sortingField: null,
+			filterName,
+			filterHandler: filterName
+				? columnType.createFilterHandler(fieldName!) as FilterHandler<FilterArtifact>
+				: undefined,
+			isTextSearchable: false,
+			columnType: columnType.name as ColumnLeafProps['columnType'],
+			relatedEntityName,
+			relatedSelection,
+			renderFilterItem,
+			renderFilter,
+			renderCellWrapper: resolvedCellWrapper,
+			header,
+			collectSelection: () => {
+				if (renderer && fieldRef) {
+					cellConfig.collectSelection(renderer, fieldRef)
+				}
+			},
+			renderCell: (accessor: EntityAccessor<object>) => {
+				if (!fieldName || !renderer) return null
+				return cellConfig.renderCell(accessor, fieldName, renderer)
+			},
+		}
+	}
+
+	const Component = Object.assign(
+		function RelationColumn<TEntity, TSelected>(_props: RelationColumnProps<TEntity, TSelected>): null {
+			return null
+		},
+		{
+			staticRender: (props: Record<string, unknown>): React.ReactNode => {
+				return React.createElement(ColumnLeaf, buildLeaf(props) as ColumnLeafProps)
+			},
+			buildLeaf,
+		},
+	)
+
+	return Component as RelationColumnComponent
+}
+
+export interface RelationColumnComponent {
+	<TEntity, TSelected>(props: RelationColumnProps<TEntity, TSelected>): null
+	staticRender: (props: Record<string, unknown>) => React.ReactNode
+	buildLeaf: (props: Record<string, unknown>) => ColumnLeafProps
+}
+
+// ============================================================================
+// Cell configs for hasOne and hasMany
+// ============================================================================
+
+export const hasOneCellConfig: RelationCellConfig = {
+	collectSelection: (renderer, fieldRef) => {
+		renderer(fieldRef)
+	},
+	renderCell: (accessor, fieldName, renderer) => {
+		const related = getRelatedAccessor(accessor, fieldName)
+		if (!related) return null
+		return unwrapRenderResult(renderer(related))
+	},
+}
+
+export const hasManyCellConfig: RelationCellConfig = {
+	collectSelection: (renderer, fieldRef) => {
+		const ref = fieldRef as { map?: (fn: (item: unknown, index: number) => unknown) => unknown[] }
+		ref.map?.((item) => { renderer(item); return null })
+	},
+	renderCell: (accessor, fieldName, renderer) => {
+		const ref = accessField(accessor, fieldName) as { items?: EntityAccessor<object>[] } | null
+		const items = ref?.items
+		if (!Array.isArray(items) || items.length === 0) return ''
+
+		return items.map((item, i) => (
+			<React.Fragment key={i}>{i > 0 ? ', ' : ''}{unwrapRenderResult(renderer(item))}</React.Fragment>
+		))
+	},
+}

package/src/dataAttribute.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts a boolean to a data attribute value.
+ * Returns '' (present) for true, undefined (absent) for false.
+ */
+export function dataAttribute(value: boolean): '' | undefined {
+	return value ? '' : undefined
+}