@contember/bindx-dataview 0.1.0

package/src/select/SelectDataView.tsx

@@ -0,0 +1,231 @@
+/**
+ * SelectDataView — provides a DataView context for select option lists.
+ *
+ * Analyzes the children render function for field selection, loads data
+ * from the options entity, and provides a DataView context for rendering.
+ * Children are rendered directly inside the DataView — use DataViewEachRow
+ * or DataViewLoaderState to iterate items and show loading states.
+ *
+ * Usage:
+ * ```tsx
+ * <Select relation={article.category} options={schema.Category}>
+ *   <SelectDataView queryField={['name']}>
+ *     <DataViewEachRow>
+ *       {(item) => (
+ *         <SelectOption entity={item}>
+ *           <SelectItemTrigger entity={item}>
+ *             <button>{item.name.value}</button>
+ *           </SelectItemTrigger>
+ *         </SelectOption>
+ *       )}
+ *     </DataViewEachRow>
+ *   </SelectDataView>
+ * </Select>
+ * ```
+ */
+
+import { memo, type ReactElement, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type {
+	EntityAccessor,
+	FilterArtifact,
+	FilterHandler,
+	OrderDirection,
+	SortingDirections,
+} from '@contember/bindx'
+import { SelectionScope, buildQueryFromSelection, createFullTextFilterHandler, FIELD_REF_META } from '@contember/bindx'
+import type { FieldRefBase } from '@contember/bindx'
+import {
+	useBindxContext,
+	useEntityList,
+	createCollectorProxy,
+	mergeSelections,
+	collectSelection,
+} from '@contember/bindx-react'
+import { useSelectOptions } from './selectContext.js'
+import { DataViewProvider, type DataViewContextValue, type DataViewLoaderState } from '../DataViewContext.js'
+import { useFilteringState, useSortingState, usePagingState, useSelectionState } from '../useDataViewState.js'
+
+export interface SelectDataViewProps {
+	/** Children rendered inside the DataView context */
+	children: ReactNode
+	/** Selection definer — called with collector proxy to discover fields */
+	selection?: (it: EntityAccessor<object>) => ReactNode
+	/** Field(s) to search across */
+	queryField?: FieldRefBase<unknown> | FieldRefBase<unknown>[] | string[]
+	/** Initial sort order */
+	initialSorting?: Partial<Record<string, OrderDirection>>
+	/** Static filter for the options list */
+	filter?: Record<string, unknown>
+	/** Items per page (null = all). Default: 50 */
+	itemsPerPage?: number | null
+}
+
+const QUERY_FILTER_NAME = '__query'
+
+function SelectDataViewImpl({
+	children,
+	selection: selectionDefiner,
+	queryField,
+	initialSorting,
+	filter: staticFilter,
+	itemsPerPage = 50,
+}: SelectDataViewProps): ReactElement | null {
+	const options = useSelectOptions()
+	const { schema: schemaRegistry } = useBindxContext()
+	const entityType = options.$name
+
+	// ---- Loader state tracking ----
+	const hasLoadedOnce = useRef(false)
+	const [loaderState, setLoaderState] = useState<DataViewLoaderState>('initial')
+
+	// ---- Build selection from definer ----
+	// Use ref for selectionDefiner to avoid re-running on every render
+	// (inline arrow functions create new refs each render)
+	const selectionDefinerRef = useRef(selectionDefiner)
+	selectionDefinerRef.current = selectionDefiner
+
+	const { selection, queryKey } = useMemo(() => {
+		const scope = new SelectionScope()
+		const collector = createCollectorProxy<object>(scope, entityType, schemaRegistry ?? undefined) as unknown as EntityAccessor<object>
+
+		if (selectionDefinerRef.current) {
+			const jsx = selectionDefinerRef.current(collector)
+			const jsxSel = collectSelection(jsx)
+			const sel = scope.toSelectionMeta()
+			mergeSelections(sel, jsxSel)
+		}
+
+		const sel = scope.toSelectionMeta()
+		const query = buildQueryFromSelection(sel)
+		const key = JSON.stringify({ entityType, query })
+
+		return { selection: sel, queryKey: key }
+	}, [entityType, schemaRegistry])
+
+	// ---- Filter setup ----
+	const filterDefs = useMemo((): ReadonlyMap<string, { handler: FilterHandler<FilterArtifact> }> => {
+		const map = new Map<string, { handler: FilterHandler<FilterArtifact> }>()
+
+		// Resolve query fields: explicit prop → auto-derive from selection scalars
+		let resolvedPaths: string[] | undefined
+		if (queryField) {
+			const fields = Array.isArray(queryField) ? queryField : [queryField]
+			resolvedPaths = fields.map(f => typeof f === 'string' ? f : f[FIELD_REF_META].fieldName)
+		} else if (selection.fields.size > 0) {
+			// Auto-derive: use all scalar fields from selection as searchable fields
+			resolvedPaths = []
+			for (const [name, field] of selection.fields) {
+				if (!field.nested) resolvedPaths.push(name)
+			}
+		}
+
+		if (resolvedPaths && resolvedPaths.length > 0) {
+			map.set(QUERY_FILTER_NAME, { handler: createFullTextFilterHandler(resolvedPaths) })
+		}
+		return map
+	}, [queryField, selection])
+
+	const sortableFields = useMemo((): ReadonlySet<string> => new Set(), [])
+
+	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])
+
+	// ---- State (no persistence for select dropdowns) ----
+	const filtering = useFilteringState({ filters: filterDefs })
+	const sorting = useSortingState({ sortableFields, initialSorting: initialSortingDirs })
+	const paging = usePagingState({ initialItemsPerPage: itemsPerPage })
+	const selectionState = useSelectionState({})
+
+	// ---- Build combined filter ----
+	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(options, {
+		filter: combinedFilter,
+		orderBy: sorting.resolvedOrderBy,
+		limit: paging.queryLimit,
+		offset: paging.queryOffset,
+		selection,
+		queryKey,
+	})
+
+	const items = result.status === 'ready' ? result.items : []
+	const itemCount = items.length
+
+	// Update loader state
+	useEffect(() => {
+		if (result.status === 'ready') {
+			hasLoadedOnce.current = true
+			setLoaderState('loaded')
+		} else if (result.status === 'error') {
+			setLoaderState('failed')
+		} else if (result.status === 'loading') {
+			setLoaderState(hasLoadedOnce.current ? 'refreshing' : 'initial')
+		}
+	}, [result.status])
+
+	// Update total count for paging
+	useEffect(() => {
+		if (result.status === 'ready' && paging.queryLimit !== undefined && paging.queryOffset !== undefined && itemCount < paging.queryLimit) {
+			paging.setTotalCount(paging.queryOffset + itemCount)
+		}
+	}, [result.status, itemCount, paging.queryLimit, paging.queryOffset, paging.setTotalCount])
+
+	// ---- Reload ----
+	const [, setReloadCounter] = useState(0)
+	const reload = useCallback((): void => {
+		setReloadCounter(c => c + 1)
+	}, [])
+
+	// ---- Row highlighting ----
+	const [highlightIndex, setHighlightIndex] = useState<number | null>(null)
+
+	// Reset highlight when filter/sort changes (not on every items reference change)
+	const filterKey = filtering.resolvedWhere ? JSON.stringify(filtering.resolvedWhere) : ''
+	const sortKey = sorting.resolvedOrderBy ? JSON.stringify(sorting.resolvedOrderBy) : ''
+	useEffect(() => {
+		setHighlightIndex(null)
+	}, [filterKey, sortKey])
+
+	const emptyMap = useMemo(() => new Map(), [])
+
+	const contextValue = useMemo((): DataViewContextValue => ({
+		filtering,
+		sorting,
+		paging,
+		selection: selectionState,
+		columns: [],
+		entityType,
+		items,
+		itemCount,
+		loaderState,
+		reload,
+		highlightIndex,
+		setHighlightIndex,
+		selectionMeta: selection,
+		toolbarContent: undefined,
+		layoutRenders: emptyMap,
+		layoutElements: emptyMap,
+	}), [filtering, sorting, paging, selectionState, entityType, items, itemCount, loaderState, reload, highlightIndex, selection, emptyMap])
+
+	return (
+		<DataViewProvider value={contextValue}>
+			{children}
+		</DataViewProvider>
+	)
+}
+
+export const SelectDataView = memo(SelectDataViewImpl) as unknown as typeof SelectDataViewImpl

package/src/select/SelectEachValue.tsx

@@ -0,0 +1,34 @@
+/**
+ * SelectEachValue — iterates over currently selected entities.
+ *
+ * Renders its children once for each selected entity,
+ * providing the entity accessor and index.
+ *
+ * Usage:
+ * ```tsx
+ * <SelectEachValue>
+ *   {(entity) => <span>{entity.name.value}</span>}
+ * </SelectEachValue>
+ * ```
+ */
+
+import React, { type ReactNode } from 'react'
+import type { EntityAccessor } from '@contember/bindx'
+import { useSelectCurrentEntities } from './selectContext.js'
+
+export interface SelectEachValueProps {
+	children: (entity: EntityAccessor<object>, index: number) => ReactNode
+}
+
+export function SelectEachValue({ children }: SelectEachValueProps): ReactNode {
+	const entities = useSelectCurrentEntities()
+	return (
+		<>
+			{entities.map((entity, index) => (
+				<React.Fragment key={entity.id}>
+					{children(entity, index)}
+				</React.Fragment>
+			))}
+		</>
+	)
+}

package/src/select/SelectItemTrigger.tsx

@@ -0,0 +1,51 @@
+/**
+ * SelectItemTrigger — clickable handler for option items.
+ *
+ * Slot-based: wraps its single child element, adding an onClick handler
+ * that calls the select handler with the specified action.
+ *
+ * Usage:
+ * ```tsx
+ * <SelectItemTrigger action="toggle">
+ *   <button><Field field={it.name} /></button>
+ * </SelectItemTrigger>
+ * ```
+ */
+
+import React, { forwardRef, type ReactElement, useCallback } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { composeEventHandlers } from '@radix-ui/primitive'
+import { useSelectHandleSelect, type SelectAction } from './selectContext.js'
+import type { EntityAccessor } from '@contember/bindx'
+
+export interface SelectItemTriggerProps {
+	/** Entity accessor for this option */
+	entity: EntityAccessor<object>
+	/** Action to perform on click. Default: 'toggle' */
+	action?: SelectAction
+	children: ReactElement
+}
+
+export const SelectItemTrigger = forwardRef<HTMLElement, SelectItemTriggerProps>(
+	({ entity, action = 'toggle', ...props }, ref) => {
+		const handleSelect = useSelectHandleSelect()
+
+		const handleClick = useCallback(
+			(): void => {
+				handleSelect(entity, action)
+			},
+			[entity, action, handleSelect],
+		)
+
+		const { onClick, ...otherProps } = props as React.HTMLAttributes<HTMLElement> & { children: ReactElement }
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				{...otherProps}
+			/>
+		)
+	},
+)
+SelectItemTrigger.displayName = 'SelectItemTrigger'

package/src/select/SelectOption.tsx

@@ -0,0 +1,40 @@
+/**
+ * SelectOption — marks an option item with data-selected attribute.
+ *
+ * Slot-based: wraps its single child element, adding `data-selected`
+ * when the current entity is selected.
+ *
+ * Usage:
+ * ```tsx
+ * <SelectOption>
+ *   <button>Option label</button>
+ * </SelectOption>
+ * ```
+ */
+
+import { forwardRef, type ReactElement } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { useSelectIsSelected } from './selectContext.js'
+import { dataAttribute } from '../dataAttribute.js'
+
+export interface SelectOptionProps {
+	/** Entity accessor for this option (passed automatically by DataViewEachRow) */
+	entity: { id: string }
+	children: ReactElement
+}
+
+export const SelectOption = forwardRef<HTMLElement, SelectOptionProps>(
+	({ entity, children, ...rest }, ref) => {
+		const isSelected = useSelectIsSelected()
+		return (
+			<Slot
+				ref={ref}
+				data-selected={dataAttribute(isSelected({ id: entity.id } as Parameters<typeof isSelected>[0]))}
+				{...rest}
+			>
+				{children}
+			</Slot>
+		)
+	},
+)
+SelectOption.displayName = 'SelectOption'

package/src/select/SelectPlaceholder.tsx

@@ -0,0 +1,22 @@
+/**
+ * SelectPlaceholder — renders children only when no entities are selected.
+ *
+ * Usage:
+ * ```tsx
+ * <SelectPlaceholder>
+ *   <span>Select an option...</span>
+ * </SelectPlaceholder>
+ * ```
+ */
+
+import type { ReactNode } from 'react'
+import { useSelectCurrentEntities } from './selectContext.js'
+
+export interface SelectPlaceholderProps {
+	children: ReactNode
+}
+
+export function SelectPlaceholder({ children }: SelectPlaceholderProps): ReactNode {
+	const entities = useSelectCurrentEntities()
+	return entities.length > 0 ? null : <>{children}</>
+}

package/src/select/index.ts

@@ -0,0 +1,17 @@
+export { Select, type SelectProps } from './Select.js'
+export { MultiSelect, type MultiSelectProps } from './MultiSelect.js'
+export { SelectDataView, type SelectDataViewProps } from './SelectDataView.js'
+export { SelectOption, type SelectOptionProps } from './SelectOption.js'
+export { SelectItemTrigger, type SelectItemTriggerProps } from './SelectItemTrigger.js'
+export { SelectEachValue, type SelectEachValueProps } from './SelectEachValue.js'
+export { SelectPlaceholder, type SelectPlaceholderProps } from './SelectPlaceholder.js'
+export {
+	useSelectCurrentEntities,
+	useSelectIsSelected,
+	useSelectHandleSelect,
+	useSelectOptions,
+	SelectOptionsContext,
+	type SelectHandler,
+	type SelectAction,
+	type SelectEvents,
+} from './selectContext.js'

package/src/select/selectContext.ts

@@ -0,0 +1,82 @@
+/**
+ * Select context — provides selection state and handlers to descendant components.
+ */
+
+import { createContext, useContext } from 'react'
+import type { EntityAccessor, EntityDef } from '@contember/bindx'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SelectAction = 'select' | 'unselect' | 'toggle'
+
+export type SelectHandler = (entity: EntityAccessor<object>, action?: SelectAction) => void
+
+export interface SelectEvents {
+	onSelect?: (entity: EntityAccessor<object>) => void
+	onUnselect?: (entity: EntityAccessor<object>) => void
+}
+
+// ============================================================================
+// Contexts
+// ============================================================================
+
+const SelectCurrentEntitiesContext = createContext<readonly EntityAccessor<object>[] | null>(null)
+SelectCurrentEntitiesContext.displayName = 'SelectCurrentEntitiesContext'
+
+const SelectIsSelectedContext = createContext<((entity: EntityAccessor<object>) => boolean) | null>(null)
+SelectIsSelectedContext.displayName = 'SelectIsSelectedContext'
+
+const SelectHandleSelectContext = createContext<SelectHandler | null>(null)
+SelectHandleSelectContext.displayName = 'SelectHandleSelectContext'
+
+const SelectOptionsContext = createContext<EntityDef | null>(null)
+SelectOptionsContext.displayName = 'SelectOptionsContext'
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export function useSelectCurrentEntities(): readonly EntityAccessor<object>[] {
+	const ctx = useContext(SelectCurrentEntitiesContext)
+	if (ctx === null) {
+		throw new Error('useSelectCurrentEntities must be used within a Select or MultiSelect')
+	}
+	return ctx
+}
+
+export function useSelectIsSelected(): (entity: EntityAccessor<object>) => boolean {
+	const ctx = useContext(SelectIsSelectedContext)
+	if (ctx === null) {
+		throw new Error('useSelectIsSelected must be used within a Select or MultiSelect')
+	}
+	return ctx
+}
+
+export function useSelectHandleSelect(): SelectHandler {
+	const ctx = useContext(SelectHandleSelectContext)
+	if (ctx === null) {
+		throw new Error('useSelectHandleSelect must be used within a Select or MultiSelect')
+	}
+	return ctx
+}
+
+export function useSelectOptions(): EntityDef {
+	const ctx = useContext(SelectOptionsContext)
+	if (ctx === null) {
+		throw new Error('useSelectOptions must be used within a Select or MultiSelect')
+	}
+	return ctx
+}
+
+// ============================================================================
+// Providers (exported for internal use by Select/MultiSelect)
+// ============================================================================
+
+export {
+	SelectCurrentEntitiesContext,
+	SelectIsSelectedContext,
+	SelectHandleSelectContext,
+	SelectOptionsContext,
+}

package/src/selectionComponents.tsx

@@ -0,0 +1,160 @@
+/**
+ * Selection components — column visibility + layout switching using Radix Slot.
+ *
+ * Usage:
+ * ```tsx
+ * <DataViewVisibilityTrigger name="description">
+ *   <button>Toggle Description</button>
+ * </DataViewVisibilityTrigger>
+ *
+ * <DataViewElement name="description">
+ *   <DescriptionColumn />
+ * </DataViewElement>
+ *
+ * <DataViewLayout name="table">
+ *   <TableView />
+ * </DataViewLayout>
+ *
+ * <DataViewLayoutTrigger name="table">
+ *   <button>Table View</button>
+ * </DataViewLayoutTrigger>
+ * ```
+ */
+
+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'
+
+// ============================================================================
+// Column Visibility
+// ============================================================================
+
+export interface DataViewVisibilityTriggerProps {
+	/** Element name to toggle */
+	name: string
+	/** Value to set. Can be boolean or function. Default: toggle */
+	value?: boolean | ((current: boolean) => boolean)
+	/** Fallback visibility when not explicitly set. Default: true */
+	fallbackValue?: boolean
+	/** Button element */
+	children: ReactElement
+}
+
+export const DataViewVisibilityTrigger = forwardRef<HTMLButtonElement, DataViewVisibilityTriggerProps>(
+	({ name, value, fallbackValue = true, ...props }, ref) => {
+		const { selection } = useDataViewContext()
+		const isVisible = selection.isVisible(name, fallbackValue)
+
+		const handleClick = useCallback((): void => {
+			if (value === undefined) {
+				selection.setVisibility(name, !isVisible)
+			} else if (typeof value === 'function') {
+				selection.setVisibility(name, value(isVisible))
+			} else {
+				selection.setVisibility(name, value)
+			}
+		}, [selection, name, value, isVisible])
+
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				data-active={dataAttribute(isVisible)}
+				data-current={String(isVisible)}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewVisibilityTrigger.displayName = 'DataViewVisibilityTrigger'
+
+// ============================================================================
+// Conditional Element (visibility-aware)
+// ============================================================================
+
+export interface DataViewElementProps {
+	/** Element name (used for visibility toggle) */
+	name: string
+	/** Label for the element (for UI display) */
+	label?: React.ReactNode
+	/** Default visibility when not explicitly set. Default: true */
+	fallback?: boolean
+	children: React.ReactNode
+}
+
+export function DataViewElement({
+	name,
+	fallback = true,
+	children,
+}: DataViewElementProps): ReactElement | null {
+	const { selection } = useDataViewContext()
+	const isVisible = selection.isVisible(name, fallback)
+
+	if (!isVisible) return null
+	return <>{children}</>
+}
+
+/** @deprecated Use DataViewElement instead */
+export const DataViewIsVisible = DataViewElement
+
+// ============================================================================
+// Layout Switching
+// ============================================================================
+
+export interface DataViewLayoutProps {
+	/** Layout name */
+	name: string
+	/** Label for the layout */
+	label?: React.ReactNode
+	children: React.ReactNode
+}
+
+export function DataViewLayout({
+	name,
+	children,
+}: DataViewLayoutProps): ReactElement | null {
+	const { selection } = useDataViewContext()
+	const currentLayout = selection.currentLayout
+	const layouts = selection.state.layouts
+	const isActive = currentLayout === name || (currentLayout === undefined && layouts[0]?.name === name)
+
+	if (!isActive) return null
+	return <>{children}</>
+}
+
+export interface DataViewLayoutTriggerProps {
+	/** Layout name to switch to */
+	name: string
+	/** Button element */
+	children: ReactElement
+}
+
+export const DataViewLayoutTrigger = forwardRef<HTMLButtonElement, DataViewLayoutTriggerProps>(
+	({ name, ...props }, ref) => {
+		const { selection } = useDataViewContext()
+		const currentLayout = selection.currentLayout
+		const layouts = selection.state.layouts
+		const isActive = currentLayout === name || (currentLayout === undefined && layouts[0]?.name === name)
+
+		const handleClick = useCallback((): void => {
+			selection.setLayout(name)
+		}, [selection, name])
+
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				data-active={dataAttribute(isActive)}
+				data-current={currentLayout ?? layouts[0]?.name ?? 'none'}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewLayoutTrigger.displayName = 'DataViewLayoutTrigger'