@contember/bindx-react 0.1.0

package/src/hooks/usePersist.ts

@@ -0,0 +1,377 @@
+import { useSyncExternalStore, useCallback, useMemo, useRef } from 'react'
+import {
+	FIELD_REF_META,
+	type BatchPersister,
+	type DirtyEntity,
+	type EntityPersistResult,
+	type PersistenceResult,
+	type PersistScope,
+	type BatchPersistOptions,
+	type FieldRef,
+	type HasOneRef,
+	type HasManyRef,
+	type FieldRefMeta,
+} from '@contember/bindx'
+import { useBindxContext } from './BackendAdapterContext.js'
+
+/**
+ * Any ref that has entity metadata (FieldRef, HasOneRef, HasManyRef)
+ */
+export type AnyRefWithMeta = { readonly [FIELD_REF_META]: FieldRefMeta }
+
+/**
+ * Extracts entity metadata from a ref
+ */
+function getRefMeta(ref: AnyRefWithMeta): FieldRefMeta {
+	return ref[FIELD_REF_META]
+}
+
+/**
+ * API returned by usePersist hook
+ */
+export interface PersistApi {
+	/** Persist all dirty entities in a transaction */
+	persistAll(options?: BatchPersistOptions): Promise<PersistenceResult>
+
+	/**
+	 * Persist a single entity.
+	 * Can be called with entityType/entityId or with a ref (FieldRef, HasOneRef, HasManyRef).
+	 *
+	 * @example
+	 * ```tsx
+	 * // With entityType and entityId
+	 * persist('Article', 'abc-123')
+	 *
+	 * // With a FieldRef - persists the entity the field belongs to
+	 * persist(article.fields.title)
+	 * ```
+	 */
+	persist(ref: AnyRefWithMeta, options?: BatchPersistOptions): Promise<EntityPersistResult>
+	persist(entityType: string, entityId: string, options?: BatchPersistOptions): Promise<EntityPersistResult>
+
+	/**
+	 * Persist specific fields of an entity.
+	 *
+	 * @example
+	 * ```tsx
+	 * // With entityType, entityId, and field names
+	 * persistFields('Article', 'abc-123', ['title', 'content'])
+	 *
+	 * // With a FieldRef - persists just that field
+	 * persistFields(article.fields.title)
+	 * ```
+	 */
+	persistFields(ref: AnyRefWithMeta, options?: BatchPersistOptions): Promise<EntityPersistResult>
+	persistFields(
+		entityType: string,
+		entityId: string,
+		fields: readonly string[],
+		options?: BatchPersistOptions,
+	): Promise<EntityPersistResult>
+
+	/** Persist with custom scope */
+	persistScope(scope: PersistScope, options?: BatchPersistOptions): Promise<PersistenceResult>
+
+	/** Check if any entity is currently being persisted */
+	isPersisting: boolean
+
+	/** Get all dirty entities */
+	dirtyEntities: readonly DirtyEntity[]
+
+	/** Check if there are any dirty entities */
+	isDirty: boolean
+}
+
+/**
+ * Hook for accessing the persistence API.
+ * Provides methods to persist all dirty entities, a single entity, or specific fields.
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const { persistAll, isPersisting, isDirty } = usePersist()
+ *
+ *   return (
+ *     <button
+ *       onClick={() => persistAll()}
+ *       disabled={isPersisting || !isDirty}
+ *     >
+ *       {isPersisting ? 'Saving...' : 'Save All'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function usePersist(): PersistApi {
+	const { batchPersister, store } = useBindxContext()
+
+	if (!batchPersister) {
+		throw new Error('usePersist requires BatchPersister to be configured in the context')
+	}
+
+	const changeRegistry = batchPersister.getChangeRegistry()
+
+	// Cache for dirty entities snapshot to avoid infinite loops
+	const dirtyEntitiesCacheRef = useRef<readonly DirtyEntity[]>([])
+
+	// Subscribe to store changes for dirty tracking
+	const dirtyEntities = useSyncExternalStore(
+		useCallback((callback) => store.subscribe(callback), [store]),
+		useCallback(() => {
+			const newDirtyEntities = changeRegistry.getDirtyEntities()
+			// Compare by length and entity keys to avoid unnecessary updates
+			const cached = dirtyEntitiesCacheRef.current
+			if (
+				cached.length === newDirtyEntities.length &&
+				cached.every((e, i) => {
+					const newE = newDirtyEntities[i]
+					return newE && e.entityType === newE.entityType && e.entityId === newE.entityId
+				})
+			) {
+				return cached
+			}
+			dirtyEntitiesCacheRef.current = newDirtyEntities
+			return newDirtyEntities
+		}, [changeRegistry]),
+		useCallback(() => changeRegistry.getDirtyEntities(), [changeRegistry]),
+	)
+
+	// Cache for isPersisting snapshot
+	const isPersistingCacheRef = useRef<boolean>(false)
+
+	// Subscribe to in-flight changes
+	const isPersisting = useSyncExternalStore(
+		useCallback((callback) => changeRegistry.subscribe(callback), [changeRegistry]),
+		useCallback(() => {
+			const newIsPersisting = changeRegistry.hasInFlight()
+			if (isPersistingCacheRef.current === newIsPersisting) {
+				return isPersistingCacheRef.current
+			}
+			isPersistingCacheRef.current = newIsPersisting
+			return newIsPersisting
+		}, [changeRegistry]),
+		useCallback(() => changeRegistry.hasInFlight(), [changeRegistry]),
+	)
+
+	const persistAll = useCallback(
+		(options?: BatchPersistOptions) => batchPersister.persistAll(options),
+		[batchPersister],
+	)
+
+	const persist = useCallback(
+		(
+			refOrEntityType: AnyRefWithMeta | string,
+			entityIdOrOptions?: string | BatchPersistOptions,
+			options?: BatchPersistOptions,
+		) => {
+			if (typeof refOrEntityType === 'string') {
+				// Called with (entityType, entityId, options?)
+				return batchPersister.persist(refOrEntityType, entityIdOrOptions as string, options)
+			}
+			// Called with (ref, options?)
+			const meta = getRefMeta(refOrEntityType)
+			return batchPersister.persist(meta.entityType, meta.entityId, entityIdOrOptions as BatchPersistOptions | undefined)
+		},
+		[batchPersister],
+	)
+
+	const persistFields = useCallback(
+		(
+			refOrEntityType: AnyRefWithMeta | string,
+			entityIdOrOptions?: string | BatchPersistOptions,
+			fieldsOrOptions?: readonly string[] | BatchPersistOptions,
+			options?: BatchPersistOptions,
+		) => {
+			if (typeof refOrEntityType === 'string') {
+				// Called with (entityType, entityId, fields, options?)
+				return batchPersister.persistFields(
+					refOrEntityType,
+					entityIdOrOptions as string,
+					fieldsOrOptions as readonly string[],
+					options,
+				)
+			}
+			// Called with (ref, options?) - persist just this field
+			const meta = getRefMeta(refOrEntityType)
+			return batchPersister.persistFields(
+				meta.entityType,
+				meta.entityId,
+				[meta.fieldName],
+				entityIdOrOptions as BatchPersistOptions | undefined,
+			)
+		},
+		[batchPersister],
+	)
+
+	const persistScope = useCallback(
+		(scope: PersistScope, options?: BatchPersistOptions) =>
+			batchPersister.persistScope(scope, options),
+		[batchPersister],
+	)
+
+	return useMemo(
+		() => ({
+			persistAll,
+			persist,
+			persistFields,
+			persistScope,
+			isPersisting,
+			dirtyEntities,
+			isDirty: dirtyEntities.length > 0,
+		}),
+		[persistAll, persist, persistFields, persistScope, isPersisting, dirtyEntities],
+	)
+}
+
+/**
+ * API returned by usePersistEntity hook
+ */
+export interface EntityPersistApi {
+	/** Persist this entity */
+	persist(options?: BatchPersistOptions): Promise<EntityPersistResult>
+
+	/** Persist specific fields of this entity */
+	persistFields(fields: readonly string[], options?: BatchPersistOptions): Promise<EntityPersistResult>
+
+	/** Check if this entity is currently being persisted */
+	isPersisting: boolean
+
+	/** Check if this entity has any dirty changes */
+	isDirty: boolean
+
+	/** Get dirty fields for this entity */
+	dirtyFields: readonly string[]
+
+	/** Get dirty relations for this entity */
+	dirtyRelations: readonly string[]
+}
+
+/**
+ * Hook for accessing persistence API for a specific entity.
+ * Provides convenience methods scoped to a single entity.
+ *
+ * @example
+ * ```tsx
+ * function ArticleEditor({ id }: { id: string }) {
+ *   const article = useEntity('Article', { id })
+ *   const { persist, persistFields, isPersisting, isDirty } = usePersistEntity('Article', id)
+ *
+ *   return (
+ *     <div>
+ *       <input {...article.fields.title.inputProps} />
+ *       <button onClick={() => persistFields(['title'])} disabled={isPersisting}>
+ *         Save Title
+ *       </button>
+ *       <button onClick={() => persist()} disabled={isPersisting || !isDirty}>
+ *         Save All
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function usePersistEntity(entityType: string, entityId: string): EntityPersistApi {
+	const { batchPersister, store } = useBindxContext()
+
+	if (!batchPersister) {
+		throw new Error('usePersistEntity requires BatchPersister to be configured in the context')
+	}
+
+	const changeRegistry = batchPersister.getChangeRegistry()
+
+	// Caches for snapshot stability
+	const dirtyFieldsCacheRef = useRef<readonly string[]>([])
+	const dirtyRelationsCacheRef = useRef<readonly string[]>([])
+	const isPersistingCacheRef = useRef<boolean>(false)
+
+	const dirtyFields = useSyncExternalStore(
+		useCallback(
+			(callback) => store.subscribeToEntity(entityType, entityId, callback),
+			[store, entityType, entityId],
+		),
+		useCallback(() => {
+			const newDirtyFields = store.getDirtyFields(entityType, entityId)
+			const cached = dirtyFieldsCacheRef.current
+			if (
+				cached.length === newDirtyFields.length &&
+				cached.every((f, i) => f === newDirtyFields[i])
+			) {
+				return cached
+			}
+			dirtyFieldsCacheRef.current = newDirtyFields
+			return newDirtyFields
+		}, [store, entityType, entityId]),
+		useCallback(() => store.getDirtyFields(entityType, entityId), [store, entityType, entityId]),
+	)
+
+	const dirtyRelations = useSyncExternalStore(
+		useCallback(
+			(callback) => store.subscribeToEntity(entityType, entityId, callback),
+			[store, entityType, entityId],
+		),
+		useCallback(() => {
+			const newDirtyRelations = store.getDirtyRelations(entityType, entityId)
+			const cached = dirtyRelationsCacheRef.current
+			if (
+				cached.length === newDirtyRelations.length &&
+				cached.every((r, i) => r === newDirtyRelations[i])
+			) {
+				return cached
+			}
+			dirtyRelationsCacheRef.current = newDirtyRelations
+			return newDirtyRelations
+		}, [store, entityType, entityId]),
+		useCallback(() => store.getDirtyRelations(entityType, entityId), [store, entityType, entityId]),
+	)
+
+	const isPersisting = useSyncExternalStore(
+		useCallback(
+			(callback) => {
+				const unsubStore = store.subscribeToEntity(entityType, entityId, callback)
+				const unsubRegistry = changeRegistry.subscribe(callback)
+				return () => {
+					unsubStore()
+					unsubRegistry()
+				}
+			},
+			[store, changeRegistry, entityType, entityId],
+		),
+		useCallback(() => {
+			const newIsPersisting = changeRegistry.isInFlight(entityType, entityId)
+			if (isPersistingCacheRef.current === newIsPersisting) {
+				return isPersistingCacheRef.current
+			}
+			isPersistingCacheRef.current = newIsPersisting
+			return newIsPersisting
+		}, [changeRegistry, entityType, entityId]),
+		useCallback(
+			() => changeRegistry.isInFlight(entityType, entityId),
+			[changeRegistry, entityType, entityId],
+		),
+	)
+
+	const persist = useCallback(
+		(options?: BatchPersistOptions) => batchPersister.persist(entityType, entityId, options),
+		[batchPersister, entityType, entityId],
+	)
+
+	const persistFields = useCallback(
+		(fields: readonly string[], options?: BatchPersistOptions) =>
+			batchPersister.persistFields(entityType, entityId, fields, options),
+		[batchPersister, entityType, entityId],
+	)
+
+	const isDirty = dirtyFields.length > 0 || dirtyRelations.length > 0
+
+	return useMemo(
+		() => ({
+			persist,
+			persistFields,
+			isPersisting,
+			isDirty,
+			dirtyFields,
+			dirtyRelations,
+		}),
+		[persist, persistFields, isPersisting, isDirty, dirtyFields, dirtyRelations],
+	)
+}

package/src/hooks/useSelectionCollection.ts

@@ -0,0 +1,122 @@
+import { useContext, useMemo, useRef, type ReactNode } from 'react'
+import { createCollectorProxy } from '../jsx/proxy.js'
+import { collectSelection, debugSelection } from '../jsx/analyzer.js'
+import { mergeSelections } from '../jsx/SelectionMeta.js'
+import { buildQueryFromSelection, SelectionScope } from '@contember/bindx'
+import type { SelectionMeta, SchemaRegistry } from '@contember/bindx'
+import type { EntityAccessor } from '../jsx/types.js'
+import { BindxContext } from './BackendAdapterContext.js'
+
+/**
+ * Options for useSelectionCollection hook.
+ */
+export interface UseSelectionCollectionOptions {
+	/** Entity type name (for debugging) */
+	entityType: string
+	/** Stable key for useMemo dependencies (e.g., entityId or JSON-serialized options) */
+	depsKey: string
+	/** Collector function — receives a collector proxy, returns JSX for analysis */
+	collect: (collector: EntityAccessor<unknown>) => ReactNode
+	/** Extra data to include in the query key (e.g., filter/orderBy for lists) */
+	queryKeyExtra?: Record<string, unknown>
+}
+
+/**
+ * Result from useSelectionCollection hook.
+ */
+export interface SelectionCollectionResult {
+	/** Selection metadata for query building */
+	selection: SelectionMeta
+	/** Stable query key for dependency tracking */
+	queryKey: string
+}
+
+/**
+ * Cached selection data
+ */
+interface SelectionCache {
+	selection: SelectionMeta
+	queryKey: string
+}
+
+/**
+ * Hook for collecting field selection from JSX children.
+ * Implements the two-phase rendering approach:
+ * 1. Creates a collector proxy
+ * 2. Calls the collect function with the proxy to gather field accesses
+ * 3. Analyzes returned JSX for component-level selections
+ * 4. Merges both sources of selection
+ *
+ * **Limitation:** Selection is collected once per `depsKey`.
+ * Fields accessed conditionally in the collect function are only captured
+ * if they are accessed during the initial collection phase.
+ *
+ * @internal This hook is for internal use only.
+ */
+export function useSelectionCollection(
+	options: UseSelectionCollectionOptions,
+): SelectionCollectionResult {
+	const { entityType, depsKey, collect, queryKeyExtra } = options
+	const bindxContext = useContext(BindxContext)
+
+	// Stable collect ref - we use a ref to avoid re-running useMemo on every render
+	const collectRef = useRef(collect)
+	collectRef.current = collect
+
+	// Cache for selection to avoid unnecessary refetches
+	const selectionCacheRef = useRef<SelectionCache | null>(null)
+
+	const schemaRegistry = bindxContext?.schema ?? null
+
+	// Collection phase - runs on every render but caches based on content
+	const result = useMemo((): SelectionCollectionResult => {
+		// Create collector proxy using SelectionScope tree
+		const scope = new SelectionScope()
+		const collector = createCollectorProxy<unknown>(scope, entityType, schemaRegistry as SchemaRegistry<Record<string, object>> | null)
+
+		// Call collect function with the proxy to gather field access
+		const jsx = collectRef.current(collector)
+
+		// Analyze the returned JSX for component-level selections
+		let jsxSel: SelectionMeta
+		try {
+			jsxSel = collectSelection(jsx)
+		} catch {
+			// staticRender of nested components may crash during collection
+			jsxSel = { fields: new Map() }
+		}
+
+		// Convert scope to SelectionMeta and merge with JSX selection
+		const selection = scope.toSelectionMeta()
+		mergeSelections(selection, jsxSel)
+
+		// Debug output can be enabled via the debug prop on BindxProvider
+		if (bindxContext?.debug) {
+			console.log('[Selection] Collected selection for', entityType, ':')
+			console.log(debugSelection(selection))
+		}
+
+		// Create a stable key from the selection to detect actual changes
+		const query = buildQueryFromSelection(selection)
+		const newQueryKey = queryKeyExtra
+			? JSON.stringify({ query, ...queryKeyExtra })
+			: JSON.stringify(query)
+
+		// If the selection hasn't actually changed, return cached values
+		const cache = selectionCacheRef.current
+		if (cache && cache.queryKey === newQueryKey) {
+			return cache
+		}
+
+		// Update cache with new values
+		const newCache: SelectionCache = {
+			selection,
+			queryKey: newQueryKey,
+		}
+		selectionCacheRef.current = newCache
+
+		return newCache
+	}, [entityType, depsKey, schemaRegistry]) // Only depend on entity identity, deps key, and schema
+
+	return result
+}

package/src/hooks/useStoreSubscription.ts

@@ -0,0 +1,51 @@
+import { useCallback, useRef, useSyncExternalStore } from 'react'
+
+/**
+ * Options for useStoreSubscription hook.
+ */
+export interface UseStoreSubscriptionOptions<T> {
+	/** Function to subscribe to store changes */
+	subscribe: (callback: () => void) => () => void
+	/** Function to get current snapshot */
+	getSnapshot: () => T
+	/** Optional equality function for cache comparison (defaults to ===) */
+	isEqual?: (a: T, b: T) => boolean
+}
+
+/**
+ * Generic hook for subscribing to store changes with useSyncExternalStore.
+ * Provides snapshot caching for referential stability.
+ *
+ * @internal This hook is for internal use only.
+ */
+export function useStoreSubscription<T>(
+	options: UseStoreSubscriptionOptions<T>,
+): T {
+	const { subscribe, getSnapshot, isEqual = defaultIsEqual } = options
+
+	// Cache for snapshot to ensure referential stability
+	const cacheRef = useRef<{ value: T } | null>(null)
+
+	// Stable getSnapshot callback with caching
+	const getSnapshotCached = useCallback((): T => {
+		const newValue = getSnapshot()
+
+		// Return cached value if equal
+		if (cacheRef.current !== null && isEqual(cacheRef.current.value, newValue)) {
+			return cacheRef.current.value
+		}
+
+		// Update cache and return new value
+		cacheRef.current = { value: newValue }
+		return newValue
+	}, [getSnapshot, isEqual])
+
+	return useSyncExternalStore(subscribe, getSnapshotCached, getSnapshotCached)
+}
+
+/**
+ * Default equality check using strict equality.
+ */
+function defaultIsEqual<T>(a: T, b: T): boolean {
+	return a === b
+}

package/src/hooks/useUndo.ts

@@ -0,0 +1,83 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import type { UndoState } from '@contember/bindx'
+import { useBindxContext } from './BackendAdapterContext.js'
+
+/**
+ * Result type for useUndo hook.
+ */
+export interface UndoHookResult {
+	/** Whether undo is available */
+	canUndo: boolean
+	/** Whether redo is available */
+	canRedo: boolean
+	/** Whether undo/redo is currently blocked (e.g., during persist) */
+	isBlocked: boolean
+	/** Number of entries in undo stack */
+	undoCount: number
+	/** Number of entries in redo stack */
+	redoCount: number
+	/** Undo the last action or group */
+	undo: () => void
+	/** Redo the last undone action or group */
+	redo: () => void
+	/** Begin a manual group - all actions until endGroup are grouped as one undo entry */
+	beginGroup: (label?: string) => string
+	/** End a manual group */
+	endGroup: (groupId: string) => void
+	/** Clear all undo/redo history */
+	clear: () => void
+}
+
+/**
+ * Hook to access undo/redo functionality.
+ * Must be used within a BindxProvider with enableUndo={true}.
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const { canUndo, canRedo, undo, redo } = useUndo()
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useUndo(): UndoHookResult {
+	const { undoManager } = useBindxContext()
+
+	if (!undoManager) {
+		throw new Error(
+			'useUndo: Undo is not enabled. Set enableUndo={true} on BindxProvider.',
+		)
+	}
+
+	// Subscribe to undo manager state changes
+	const state = useSyncExternalStore(
+		useCallback((callback) => undoManager.subscribe(callback), [undoManager]),
+		useCallback(() => undoManager.getState(), [undoManager]),
+		useCallback(() => undoManager.getState(), [undoManager]),
+	)
+
+	const undo = useCallback(() => undoManager.undo(), [undoManager])
+	const redo = useCallback(() => undoManager.redo(), [undoManager])
+	const beginGroup = useCallback((label?: string) => undoManager.beginGroup(label), [undoManager])
+	const endGroup = useCallback((id: string) => undoManager.endGroup(id), [undoManager])
+	const clear = useCallback(() => undoManager.clear(), [undoManager])
+
+	return {
+		canUndo: state.canUndo,
+		canRedo: state.canRedo,
+		isBlocked: state.isBlocked,
+		undoCount: state.undoCount,
+		redoCount: state.redoCount,
+		undo,
+		redo,
+		beginGroup,
+		endGroup,
+		clear,
+	}
+}