@contember/bindx-dataview 0.1.0

package/src/loaderComponents.tsx

@@ -0,0 +1,239 @@
+/**
+ * Loader state, reload trigger, and conditional rendering components using Radix Slot.
+ *
+ * Usage:
+ * ```tsx
+ * <DataViewReloadTrigger>
+ *   <button>Refresh</button>
+ * </DataViewReloadTrigger>
+ *
+ * <DataViewLoaderState loaded={<Table />} refreshing={<Table />} initial={<Loading />} failed={<Error />} />
+ *
+ * <DataViewEmpty>No results found</DataViewEmpty>
+ * <DataViewNonEmpty><Table /></DataViewNonEmpty>
+ *
+ * <DataViewKeyboardEventHandler>
+ *   <div tabIndex={0}>...</div>
+ * </DataViewKeyboardEventHandler>
+ * ```
+ */
+
+import React, { forwardRef, type ReactElement, useCallback } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { composeEventHandlers } from '@radix-ui/primitive'
+import { useDataViewContext, type DataViewItem } from './DataViewContext.js'
+import type { DataViewLoaderState as DataViewLoaderStateType } from './DataViewContext.js'
+
+// ============================================================================
+// Reload Trigger
+// ============================================================================
+
+export interface DataViewReloadTriggerProps {
+	children: ReactElement
+}
+
+export const DataViewReloadTrigger = forwardRef<HTMLButtonElement, DataViewReloadTriggerProps>(
+	(props, ref) => {
+		const { reload, loaderState } = useDataViewContext()
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement> & { children: ReactElement }
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, reload)}
+				data-state={loaderState}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewReloadTrigger.displayName = 'DataViewReloadTrigger'
+
+// ============================================================================
+// Loader State Switch (Contember: DataViewLoaderState)
+// ============================================================================
+
+// ---- DataViewLoaderState (Contember-matching API) ----
+// Boolean-prop conditional wrapper: renders children when state matches any true flag
+
+export interface DataViewLoaderStateProps {
+	children: React.ReactNode
+	/** Render children when data is loaded */
+	loaded?: boolean
+	/** Render children when refreshing (after initial load) */
+	refreshing?: boolean
+	/** Render children during initial load */
+	initial?: boolean
+	/** Render children on failure */
+	failed?: boolean
+}
+
+export function DataViewLoaderState({
+	children,
+	...props
+}: DataViewLoaderStateProps): ReactElement | null {
+	const { loaderState } = useDataViewContext()
+	return (props as Record<string, boolean | undefined>)[loaderState] ? <>{children}</> : null
+}
+
+// ---- DataViewLoaderStateSwitch (bindx convenience API) ----
+// Switch pattern: separate ReactNode per state
+
+export interface DataViewLoaderStateSwitchProps {
+	/** Render when data is loaded */
+	loaded?: React.ReactNode
+	/** Render when refreshing (after initial load) */
+	refreshing?: React.ReactNode
+	/** Render during initial load */
+	initial?: React.ReactNode
+	/** Render on failure */
+	failed?: React.ReactNode
+}
+
+export function DataViewLoaderStateSwitch({
+	loaded,
+	refreshing,
+	initial,
+	failed,
+}: DataViewLoaderStateSwitchProps): ReactElement {
+	const { loaderState } = useDataViewContext()
+
+	switch (loaderState) {
+		case 'loaded':
+			return <>{loaded ?? null}</>
+		case 'refreshing':
+			return <>{refreshing ?? loaded ?? null}</>
+		case 'initial':
+			return <>{initial ?? null}</>
+		case 'failed':
+			return <>{failed ?? null}</>
+	}
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+export function useDataViewLoaderState(): DataViewLoaderStateType {
+	return useDataViewContext().loaderState
+}
+
+export function useDataViewReload(): () => void {
+	return useDataViewContext().reload
+}
+
+export function useDataViewHighlightIndex(): number | null {
+	return useDataViewContext().highlightIndex
+}
+
+// ============================================================================
+// Empty / Non-Empty
+// ============================================================================
+
+export interface DataViewEmptyProps {
+	children: React.ReactNode
+}
+
+export function DataViewEmpty({ children }: DataViewEmptyProps): ReactElement {
+	const { loaderState, itemCount } = useDataViewContext()
+	if (loaderState !== 'loaded' || itemCount > 0) return <>{null}</>
+	return <>{children}</>
+}
+
+export interface DataViewNonEmptyProps {
+	children: React.ReactNode
+}
+
+export function DataViewNonEmpty({ children }: DataViewNonEmptyProps): ReactElement {
+	const { loaderState, itemCount } = useDataViewContext()
+	if (loaderState !== 'loaded' || itemCount === 0) return <>{null}</>
+	return <>{children}</>
+}
+
+// ============================================================================
+// Each Row
+// ============================================================================
+
+export interface DataViewEachRowProps {
+	children: (item: DataViewItem, index: number) => React.ReactNode
+}
+
+export function DataViewEachRow({ children }: DataViewEachRowProps): ReactElement {
+	const { items } = useDataViewContext()
+	return <>{items.map((item, index) => children(item, index))}</>
+}
+
+// ============================================================================
+// Highlight Row — Slot-based
+// ============================================================================
+
+export interface DataViewHighlightRowProps {
+	index: number
+	children: ReactElement
+}
+
+export const DataViewHighlightRow = forwardRef<HTMLElement, DataViewHighlightRowProps>(
+	({ index, ...props }, ref) => {
+		const { highlightIndex, setHighlightIndex } = useDataViewContext()
+		const isHighlighted = highlightIndex === index
+
+		const handleClick = useCallback((): void => {
+			setHighlightIndex(index)
+		}, [setHighlightIndex, index])
+
+		const { onClick, ...otherProps } = props as React.HTMLAttributes<HTMLElement> & { children: ReactElement }
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				data-highlighted={isHighlighted ? '' : undefined}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewHighlightRow.displayName = 'DataViewHighlightRow'
+
+// ============================================================================
+// Keyboard Event Handler — Slot-based
+// ============================================================================
+
+export interface DataViewKeyboardEventHandlerProps {
+	children: ReactElement
+	onSelectHighlighted?: (item: DataViewItem) => void
+}
+
+export const DataViewKeyboardEventHandler = forwardRef<HTMLElement, DataViewKeyboardEventHandlerProps>(
+	({ onSelectHighlighted, ...props }, ref) => {
+		const { items, highlightIndex, setHighlightIndex } = useDataViewContext()
+
+		const handleKeyDown = useCallback((e: React.KeyboardEvent): void => {
+			if (items.length === 0) return
+
+			if (e.key === 'ArrowDown') {
+				e.preventDefault()
+				setHighlightIndex(Math.min((highlightIndex ?? -1) + 1, items.length - 1))
+			} else if (e.key === 'ArrowUp') {
+				e.preventDefault()
+				setHighlightIndex(Math.max((highlightIndex ?? 1) - 1, 0))
+			} else if (e.key === 'Escape') {
+				setHighlightIndex(null)
+			} else if (e.key === 'Enter' && highlightIndex !== null && onSelectHighlighted) {
+				const item = items[highlightIndex]
+				if (item) onSelectHighlighted(item)
+			}
+		}, [items, highlightIndex, setHighlightIndex, onSelectHighlighted])
+
+		const { onKeyDown, ...otherProps } = props as React.HTMLAttributes<HTMLElement> & { children: ReactElement }
+
+		return (
+			<Slot
+				ref={ref}
+				onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewKeyboardEventHandler.displayName = 'DataViewKeyboardEventHandler'

package/src/markers.ts

@@ -0,0 +1,54 @@
+/**
+ * Marker components for DataGrid children analysis.
+ *
+ * These are metadata components — they return null at runtime.
+ * Their props are extracted by `analyzeChildren()` during the DataGrid's
+ * collection phase and stored in DataViewContext for layout components to consume.
+ */
+
+import type React from 'react'
+import type { ReactNode } from 'react'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { EntityAccessor } from '@contember/bindx'
+
+// ============================================================================
+// Toolbar Content Marker
+// ============================================================================
+
+export interface DataGridToolbarContentProps {
+	readonly children: React.ReactNode
+}
+
+/**
+ * Marker for toolbar content inside a DataGrid children render function.
+ * At analysis time, the children ReactNode is extracted and stored in context.
+ * At runtime, returns null (content is rendered by toolbar layout components).
+ */
+export function DataGridToolbarContent(_props: DataGridToolbarContentProps): null {
+	return null
+}
+
+// ============================================================================
+// Layout Marker (replaces DataGridTileLayout)
+// ============================================================================
+
+export interface DataGridLayoutProps<T = never> {
+	/** Unique name for this layout (e.g. "grid", "rows", "cards") */
+	readonly name: string
+	/** Label shown in the layout switcher UI (supports ReactNode for icons) */
+	readonly label?: ReactNode
+	/** Pass the DataGrid's `it` parameter for type inference on the children callback. */
+	readonly item?: T
+	readonly children: (item: T) => ReactNode
+}
+
+/**
+ * Marker for a named layout inside a DataGrid children render function.
+ * Multiple DataGridLayout markers can coexist with different names.
+ * At analysis time, the callback is extracted and called with the collector proxy
+ * to discover field selections. At runtime, returns null (callback is stored in
+ * context and invoked per-item by layout rendering components).
+ */
+export function DataGridLayout<T>(_props: DataGridLayoutProps<T>): null {
+	return null
+}

package/src/pagingComponents.tsx

@@ -0,0 +1,149 @@
+/**
+ * Composable paging UI components using Radix Slot pattern.
+ *
+ * Usage:
+ * ```tsx
+ * <DataViewChangePageTrigger page="previous">
+ *   <button>Previous</button>
+ * </DataViewChangePageTrigger>
+ *
+ * <DataViewChangePageTrigger page="next">
+ *   <button>Next</button>
+ * </DataViewChangePageTrigger>
+ *
+ * <DataViewSetItemsPerPageTrigger value={25}>
+ *   <button>25 per page</button>
+ * </DataViewSetItemsPerPageTrigger>
+ *
+ * <DataViewPagingStateView>
+ *   {({ pageIndex, totalPages }) => <span>Page {pageIndex + 1} of {totalPages}</span>}
+ * </DataViewPagingStateView>
+ * ```
+ */
+
+import React, { forwardRef, type ReactElement, type ReactNode, 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'
+
+// ============================================================================
+// DataViewChangePageTrigger
+// ============================================================================
+
+export interface DataViewChangePageTriggerProps {
+	/** Target page: named shortcut or zero-based page index */
+	page: 'first' | 'last' | 'next' | 'previous' | number
+	/** Button element */
+	children: ReactElement
+}
+
+export const DataViewChangePageTrigger = forwardRef<HTMLButtonElement, DataViewChangePageTriggerProps>(
+	({ page, ...props }, ref) => {
+		const { paging } = useDataViewContext()
+
+		const isDisabled = resolveIsDisabled(page, paging.hasPrevious, paging.hasNext, paging.state.pageIndex, paging.info.totalPages)
+		const isActive = typeof page === 'number' && page === paging.state.pageIndex
+
+		const handleClick = useCallback((): 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)
+		}, [paging, page])
+
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				disabled={isDisabled}
+				data-active={dataAttribute(isActive)}
+				data-current={String(paging.state.pageIndex)}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewChangePageTrigger.displayName = 'DataViewChangePageTrigger'
+
+function resolveIsDisabled(
+	page: DataViewChangePageTriggerProps['page'],
+	hasPrevious: boolean,
+	hasNext: boolean,
+	currentPageIndex: number,
+	totalPages: number | null,
+): boolean {
+	if (page === 'first' || page === 'previous') return !hasPrevious
+	if (page === 'next') return !hasNext
+	if (page === 'last') return totalPages === null || currentPageIndex >= totalPages - 1
+	return page === currentPageIndex
+}
+
+// ============================================================================
+// DataViewSetItemsPerPageTrigger
+// ============================================================================
+
+export interface DataViewSetItemsPerPageTriggerProps {
+	/** Items per page to set. null = show all. */
+	value: number | null
+	/** Button element */
+	children: ReactElement
+}
+
+export const DataViewSetItemsPerPageTrigger = forwardRef<HTMLButtonElement, DataViewSetItemsPerPageTriggerProps>(
+	({ value, ...props }, ref) => {
+		const { paging } = useDataViewContext()
+		const currentItemsPerPage = paging.state.itemsPerPage === 0 ? null : paging.state.itemsPerPage
+		const isActive = currentItemsPerPage === value
+
+		const handleClick = useCallback((): void => {
+			paging.setItemsPerPage(value)
+		}, [paging, value])
+
+		const { onClick, ...otherProps } = props as React.ButtonHTMLAttributes<HTMLButtonElement>
+
+		return (
+			<Slot
+				ref={ref}
+				onClick={composeEventHandlers(onClick, handleClick)}
+				data-active={dataAttribute(isActive)}
+				{...otherProps}
+			/>
+		)
+	},
+)
+DataViewSetItemsPerPageTrigger.displayName = 'DataViewSetItemsPerPageTrigger'
+
+// ============================================================================
+// DataViewPagingStateView (Contember name) / DataViewPagingInfo (alias)
+// ============================================================================
+
+export interface DataViewPagingInfoProps {
+	children: (info: {
+		pageIndex: number
+		totalPages: number | null
+		totalCount: number | null
+		itemsPerPage: number
+	}) => ReactNode
+}
+
+export function DataViewPagingStateView({
+	children,
+}: DataViewPagingInfoProps): ReactElement {
+	const { paging } = useDataViewContext()
+
+	return <>{children({
+		pageIndex: paging.state.pageIndex,
+		totalPages: paging.info.totalPages,
+		totalCount: paging.info.totalCount,
+		itemsPerPage: paging.state.itemsPerPage,
+	})}</>
+}
+
+/** Alias for DataViewPagingStateView */
+export const DataViewPagingInfo = DataViewPagingStateView
+
+export type DataViewPagingStateViewProps = DataViewPagingInfoProps

package/src/select/MultiSelect.tsx

@@ -0,0 +1,88 @@
+/**
+ * MultiSelect — headless multi-select component for has-many relations.
+ *
+ * Manages selection state for a has-many relation field and provides
+ * context for descendant components (SelectDataView, SelectOption, etc.).
+ *
+ * Usage:
+ * ```tsx
+ * <MultiSelect relation={article.tags} options={schema.Tag}>
+ *   <SelectDataView queryField={['name']}>
+ *     {it => <SelectOption><SelectItemTrigger><Field field={it.name} /></SelectItemTrigger></SelectOption>}
+ *   </SelectDataView>
+ * </MultiSelect>
+ * ```
+ */
+
+import { type ReactNode, useCallback, useMemo } from 'react'
+import type { EntityAccessor, EntityDef, HasManyRef } from '@contember/bindx'
+import {
+	SelectCurrentEntitiesContext,
+	SelectHandleSelectContext,
+	SelectIsSelectedContext,
+	SelectOptionsContext,
+	type SelectAction,
+	type SelectEvents,
+	type SelectHandler,
+} from './selectContext.js'
+
+export interface MultiSelectProps extends SelectEvents {
+	/** Has-many relation ref from parent entity */
+	relation: HasManyRef<object>
+	/** Entity definition for the options list */
+	options: EntityDef
+	children: ReactNode
+}
+
+export function MultiSelect({
+	relation,
+	options,
+	children,
+	onSelect,
+	onUnselect,
+}: MultiSelectProps): ReactNode {
+	const items = relation.items
+	const selectedIds = useMemo(
+		() => new Set(items.map(it => it.id)),
+		[items],
+	)
+
+	const entitiesArr = useMemo(
+		(): readonly EntityAccessor<object>[] => items as EntityAccessor<object>[],
+		[items],
+	)
+
+	const handleSelect = useCallback<SelectHandler>(
+		(entity: EntityAccessor<object>, action: SelectAction = 'toggle') => {
+			const isCurrentlySelected = selectedIds.has(entity.id)
+			if (action === 'toggle') {
+				action = isCurrentlySelected ? 'unselect' : 'select'
+			}
+			if (action === 'unselect' && isCurrentlySelected) {
+				relation.disconnect(entity.id)
+				onUnselect?.(entity)
+			} else if (action === 'select' && !isCurrentlySelected) {
+				relation.connect(entity.id)
+				onSelect?.(entity)
+			}
+		},
+		[relation, selectedIds, onSelect, onUnselect],
+	)
+
+	const isSelected = useCallback(
+		(entity: EntityAccessor<object>): boolean => selectedIds.has(entity.id),
+		[selectedIds],
+	)
+
+	return (
+		<SelectCurrentEntitiesContext.Provider value={entitiesArr}>
+			<SelectIsSelectedContext.Provider value={isSelected}>
+				<SelectHandleSelectContext.Provider value={handleSelect}>
+					<SelectOptionsContext.Provider value={options}>
+						{children}
+					</SelectOptionsContext.Provider>
+				</SelectHandleSelectContext.Provider>
+			</SelectIsSelectedContext.Provider>
+		</SelectCurrentEntitiesContext.Provider>
+	)
+}

package/src/select/Select.tsx

@@ -0,0 +1,88 @@
+/**
+ * Select — headless single-select component for has-one relations.
+ *
+ * Manages selection state for a has-one relation field and provides
+ * context for descendant components (SelectDataView, SelectOption, etc.).
+ *
+ * Usage:
+ * ```tsx
+ * <Select relation={article.category} options={schema.Category}>
+ *   <SelectDataView queryField={['name']}>
+ *     ...options rendering...
+ *   </SelectDataView>
+ * </Select>
+ * ```
+ */
+
+import { type ReactNode, useCallback, useMemo } from 'react'
+import type { EntityAccessor, EntityDef, HasOneRef } from '@contember/bindx'
+import { isPlaceholderId } from '@contember/bindx'
+import {
+	SelectCurrentEntitiesContext,
+	SelectHandleSelectContext,
+	SelectIsSelectedContext,
+	SelectOptionsContext,
+	type SelectAction,
+	type SelectEvents,
+	type SelectHandler,
+} from './selectContext.js'
+
+export interface SelectProps extends SelectEvents {
+	/** Has-one relation ref from parent entity */
+	relation: HasOneRef<object>
+	/** Entity definition for the options list */
+	options: EntityDef
+	children: ReactNode
+}
+
+export function Select({
+	relation,
+	options,
+	children,
+	onSelect,
+	onUnselect,
+}: SelectProps): ReactNode {
+	const entity = relation.$entity
+	const entityId = entity.id
+	const isConnected = !isPlaceholderId(entityId)
+	const currentId = isConnected ? entityId : null
+
+	const entitiesArr = useMemo(
+		(): readonly EntityAccessor<object>[] =>
+			isConnected ? [entity as EntityAccessor<object>] : [],
+		[isConnected, entity],
+	)
+
+	const handleSelect = useCallback<SelectHandler>(
+		(selected: EntityAccessor<object>, action: SelectAction = 'toggle') => {
+			if (action === 'toggle') {
+				action = selected.id === currentId ? 'unselect' : 'select'
+			}
+			if (action === 'unselect') {
+				relation.$disconnect()
+				onUnselect?.(selected)
+			} else if (action === 'select') {
+				relation.$connect(selected.id)
+				onSelect?.(selected)
+			}
+		},
+		[relation, currentId, onSelect, onUnselect],
+	)
+
+	const isSelected = useCallback(
+		(entity: EntityAccessor<object>): boolean => entity.id === currentId,
+		[currentId],
+	)
+
+	return (
+		<SelectCurrentEntitiesContext.Provider value={entitiesArr}>
+			<SelectIsSelectedContext.Provider value={isSelected}>
+				<SelectHandleSelectContext.Provider value={handleSelect}>
+					<SelectOptionsContext.Provider value={options}>
+						{children}
+					</SelectOptionsContext.Provider>
+				</SelectHandleSelectContext.Provider>
+			</SelectIsSelectedContext.Provider>
+		</SelectCurrentEntitiesContext.Provider>
+	)
+}