@contember/bindx-react 0.1.0

package/dist/jsx/withCollector.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+/**
+ * Attaches a static render function to a component for selection collection.
+ *
+ * During the collection phase, the analyzer calls `staticRender(props)` instead of
+ * analyzing runtime children. Props contain collector proxies, so field accesses
+ * are tracked automatically. The returned JSX is analyzed for nested components.
+ *
+ * @example
+ * ```tsx
+ * // Simple: children is a render prop receiving has-one entity
+ * export const SelectField = withCollector(
+ *   function SelectField({ field, children, ... }) { ... },
+ *   (props) => props.children(props.field.$entity)
+ * )
+ *
+ * // Composing with HasMany for iteration
+ * export const DefaultRepeater = withCollector(
+ *   function DefaultRepeater({ field, children, ... }) { ... },
+ *   (props) => (
+ *     <HasMany field={props.field}>
+ *       {item => props.children(item, collectionItemInfo)}
+ *     </HasMany>
+ *   )
+ * )
+ *
+ * // Programmatic field access (no JSX needed)
+ * export const Uploader = withCollector(
+ *   function Uploader({ field, fileType }) { ... },
+ *   (props) => {
+ *     const entity = props.field.$entity
+ *     for (const ext of props.fileType.extractors) entity[ext.fieldName]
+ *     return null
+ *   }
+ * )
+ * ```
+ */
+export declare function withCollector<TComponent extends (...args: never[]) => ReactNode>(component: TComponent, staticRender: (props: Parameters<TComponent>[0]) => ReactNode): TComponent;
+//# sourceMappingURL=withCollector.d.ts.map

package/dist/jsx/withCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withCollector.d.ts","sourceRoot":"","sources":["../../src/jsx/withCollector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,CAAC,UAAU,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,SAAS,EAC/E,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,GAC3D,UAAU,CAGZ"}

package/dist/roles/RoleContext.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Role provider context for runtime role checking.
+ *
+ * HasRole uses this to determine if the current user has the required roles.
+ * Without a RoleProvider, HasRole always renders (no gating).
+ */
+import { type ReactNode, type ReactElement } from 'react';
+type HasRoleFn = (role: string) => boolean;
+export interface RoleProviderProps {
+    children: ReactNode;
+    /** Function that checks if the current user has a given role */
+    hasRole: HasRoleFn;
+}
+/**
+ * Provides runtime role checking for HasRole components.
+ *
+ * @example
+ * ```tsx
+ * <RoleProvider hasRole={role => currentUser.roles.includes(role)}>
+ *   <App />
+ * </RoleProvider>
+ * ```
+ */
+export declare function RoleProvider({ children, hasRole }: RoleProviderProps): ReactElement;
+/**
+ * Returns a function to check if the current user has a given role.
+ * If no RoleProvider is present, returns a function that always returns true.
+ */
+export declare function useHasRole(): HasRoleFn;
+export {};
+//# sourceMappingURL=RoleContext.d.ts.map

package/dist/roles/RoleContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleContext.d.ts","sourceRoot":"","sources":["../../src/roles/RoleContext.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAA6B,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAM3F,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;AAQ1C,MAAM,WAAW,iBAAiB;IACjC,QAAQ,EAAE,SAAS,CAAA;IACnB,gEAAgE;IAChE,OAAO,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,YAAY,CAEnF;AAMD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAGtC"}

package/dist/roles/index.d.ts

@@ -0,0 +1,2 @@
+export { RoleProvider, useHasRole, type RoleProviderProps } from './RoleContext.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/roles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/roles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAA"}

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@contember/bindx-react",
+	"version": "0.1.0",
+	"description": "Type-safe React data binding framework",
+	"type": "module",
+	"main": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"build": "tsc --build",
+		"typecheck": "tsc --build"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	},
+	"dependencies": {
+		"@contember/bindx": "0.1.0",
+		"@contember/client-content": "^2.1.0-alpha.30",
+		"@contember/graphql-client": "^2.1.0-alpha.30",
+		"@radix-ui/primitive": "^1.1.3",
+		"@radix-ui/react-slot": "^1.2.4"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/contember/bindx.git",
+		"directory": "packages/bindx-react"
+	}
+}

package/src/batching/QueryBatcher.ts

@@ -0,0 +1,114 @@
+import type { BackendAdapter, Query, QueryResult, QueryOptions } from '@contember/bindx'
+
+/**
+ * Pending query with its resolution callbacks
+ */
+interface PendingQuery {
+	readonly query: Query
+	readonly resolve: (result: QueryResult) => void
+	readonly reject: (error: Error) => void
+	readonly signal?: AbortSignal
+}
+
+/**
+ * Batches queries from multiple components into single adapter calls.
+ *
+ * Uses queueMicrotask to collect all queries during a React render cycle
+ * and execute them together in a single batch.
+ */
+export class QueryBatcher {
+	private pendingQueries: PendingQuery[] = []
+	private flushScheduled = false
+
+	constructor(private readonly adapter: BackendAdapter) {}
+
+	/**
+	 * Queue a query for batched execution.
+	 * Returns a promise that resolves when the query completes.
+	 */
+	enqueue(query: Query, options?: QueryOptions): Promise<QueryResult> {
+		return new Promise((resolve, reject) => {
+			// If provided signal is already aborted, reject immediately
+			if (options?.signal?.aborted) {
+				reject(new DOMException('Aborted', 'AbortError'))
+				return
+			}
+
+			const pending: PendingQuery = { query, resolve, reject, signal: options?.signal }
+
+			// Handle abort for this specific query
+			if (options?.signal) {
+				const abortHandler = (): void => {
+					const index = this.pendingQueries.indexOf(pending)
+					if (index >= 0) {
+						this.pendingQueries.splice(index, 1)
+						reject(new DOMException('Aborted', 'AbortError'))
+					}
+				}
+				options.signal.addEventListener('abort', abortHandler, { once: true })
+			}
+
+			this.pendingQueries.push(pending)
+			this.scheduleFlush()
+		})
+	}
+
+	/**
+	 * Schedule flush using microtask to batch within render cycle
+	 */
+	private scheduleFlush(): void {
+		if (this.flushScheduled) return
+		this.flushScheduled = true
+
+		queueMicrotask(() => {
+			this.flush()
+		})
+	}
+
+	/**
+	 * Execute all pending queries in a batch
+	 */
+	private async flush(): Promise<void> {
+		this.flushScheduled = false
+
+		if (this.pendingQueries.length === 0) return
+
+		// Take all pending queries
+		const batch = this.pendingQueries.splice(0)
+
+		// Find queries that aren't aborted
+		const activeBatch = batch.filter(p => !p.signal?.aborted)
+
+		if (activeBatch.length === 0) return
+
+		try {
+			const queries = activeBatch.map(p => p.query)
+			const results = await this.adapter.query(queries)
+
+			// Resolve each query with its result
+			for (let i = 0; i < activeBatch.length; i++) {
+				const pending = activeBatch[i]
+				const result = results[i]
+				if (pending && result) {
+					pending.resolve(result)
+				}
+			}
+		} catch (error) {
+			// Reject all queries in batch
+			for (const pending of activeBatch) {
+				pending.reject(error instanceof Error ? error : new Error(String(error)))
+			}
+		}
+	}
+
+	/**
+	 * Cancel all pending queries
+	 */
+	cancelAll(): void {
+		const error = new DOMException('Cancelled', 'AbortError')
+		for (const pending of this.pendingQueries) {
+			pending.reject(error)
+		}
+		this.pendingQueries = []
+	}
+}

package/src/batching/index.ts

@@ -0,0 +1 @@
+export { QueryBatcher } from './QueryBatcher.js'

package/src/components/EntityScope.tsx

@@ -0,0 +1,43 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import type { EntityHandle } from '@contember/bindx'
+
+const EntityScopeContext = createContext<EntityHandle | null>(null)
+
+export interface EntityScopeProps {
+	entity: EntityHandle
+	children: ReactNode
+}
+
+/**
+ * Provides an EntityHandle into React context for nested components.
+ * Useful for scoping entity access in editors, repeaters, selects, etc.
+ *
+ * @example
+ * ```tsx
+ * <EntityScope entity={handle}>
+ *   <MyComponent /> // can use useEntityScope() inside
+ * </EntityScope>
+ * ```
+ */
+export function EntityScope({ entity, children }: EntityScopeProps): ReactNode {
+	return <EntityScopeContext.Provider value={entity}>{children}</EntityScopeContext.Provider>
+}
+
+/**
+ * Reads the closest EntityHandle from EntityScope context.
+ * Throws if used outside of an EntityScope.
+ */
+export function useEntityScope(): EntityHandle {
+	const entity = useContext(EntityScopeContext)
+	if (!entity) {
+		throw new Error('useEntityScope must be used within an EntityScope')
+	}
+	return entity
+}
+
+/**
+ * Reads the closest EntityHandle from EntityScope context, or null if not in scope.
+ */
+export function useOptionalEntityScope(): EntityHandle | null {
+	return useContext(EntityScopeContext)
+}

package/src/hooks/BackendAdapterContext.tsx

@@ -0,0 +1,214 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import type { BackendAdapter, MutationDataCollector, SchemaDefinition, UndoManagerConfig, UpdateMode } from '@contember/bindx'
+import { SnapshotStore } from '@contember/bindx'
+import { ActionDispatcher } from '@contember/bindx'
+import { BatchPersister } from '@contember/bindx'
+import { MutationCollector } from '@contember/bindx'
+import { SchemaRegistry } from '@contember/bindx'
+import { UndoManager } from '@contember/bindx'
+import { QueryBatcher } from '../batching/QueryBatcher.js'
+
+/**
+ * Context value containing all bindx services
+ */
+export interface BindxContextValue {
+	/** Backend adapter for data fetching/persistence */
+	adapter: BackendAdapter
+	/** Query batcher for combining multiple queries into single requests */
+	batcher: QueryBatcher
+	/** Immutable snapshot store */
+	store: SnapshotStore
+	/** Action dispatcher for mutations */
+	dispatcher: ActionDispatcher
+	/** Batch persister for multi-entity persistence */
+	batchPersister: BatchPersister
+	/** Schema registry for entity metadata */
+	schema: SchemaRegistry
+	/** Undo manager (if enabled) */
+	undoManager: UndoManager | null
+	/** Whether debug logging is enabled */
+	debug: boolean
+}
+
+export const BindxContext = createContext<BindxContextValue | null>(null)
+
+/**
+ * Props for BindxProvider
+ */
+export interface BindxProviderProps {
+	/** The backend adapter to use for data fetching/persistence */
+	adapter: BackendAdapter
+	/** Optional custom snapshot store (useful for testing) */
+	store?: SnapshotStore
+	/** Schema definition for entity metadata and mutation collection */
+	schema: SchemaDefinition<Record<string, object>>
+	/** Optional custom mutation collector (overrides default behavior) */
+	mutationCollector?: MutationDataCollector
+	/** Enable undo/redo functionality */
+	enableUndo?: boolean
+	/** Configuration for undo manager */
+	undoConfig?: UndoManagerConfig
+	/**
+	 * Default update mode for persistence operations.
+	 * - 'optimistic': Update UI immediately, revert on failure (default)
+	 * - 'pessimistic': Wait for server confirmation before updating UI
+	 */
+	defaultUpdateMode?: UpdateMode
+	/** Enable debug logging (e.g., selection collection output) */
+	debug?: boolean
+	children: ReactNode
+}
+
+/**
+ * Provider component that supplies the bindx services
+ * to all child components using bindx hooks.
+ *
+ * @example
+ * ```tsx
+ * const adapter = new MockAdapter(initialData)
+ *
+ * function App() {
+ *   return (
+ *     <BindxProvider adapter={adapter} schema={testSchema}>
+ *       <ArticleEditor id="123" />
+ *     </BindxProvider>
+ *   )
+ * }
+ * ```
+ */
+export function BindxProvider({
+	adapter,
+	store: customStore,
+	schema: schemaDefinition,
+	mutationCollector: customMutationCollector,
+	enableUndo = false,
+	undoConfig,
+	defaultUpdateMode,
+	debug = false,
+	children,
+}: BindxProviderProps) {
+	// Create services - memoized to maintain stable references
+	const services = useMemo(() => {
+		const store = customStore ?? new SnapshotStore()
+		const dispatcher = new ActionDispatcher(store)
+		const batcher = new QueryBatcher(adapter)
+
+		// Create undo manager if enabled
+		const undoManager = enableUndo ? new UndoManager(store, undoConfig) : null
+		if (undoManager) {
+			dispatcher.addMiddleware(undoManager.createMiddleware())
+		}
+
+		// Create schema registry from definition
+		const schemaRegistry = new SchemaRegistry(schemaDefinition)
+
+		// Create mutation collector - use custom, or auto-create from schema
+		// SchemaRegistry implements MutationSchemaProvider interface
+		const mutationCollector =
+			customMutationCollector ?? new MutationCollector(store, schemaRegistry)
+
+		const batchPersister = new BatchPersister(adapter, store, dispatcher, {
+			mutationCollector,
+			undoManager: undoManager ?? undefined,
+			schema: schemaRegistry,
+			defaultUpdateMode,
+		})
+
+		return {
+			adapter,
+			batcher,
+			store,
+			dispatcher,
+			batchPersister,
+			schema: schemaRegistry,
+			undoManager,
+			debug,
+		}
+	}, [adapter, customStore, schemaDefinition, customMutationCollector, enableUndo, undoConfig, defaultUpdateMode, debug])
+
+	return <BindxContext.Provider value={services}>{children}</BindxContext.Provider>
+}
+
+/**
+ * Hook to access the schema registry.
+ * Must be used within a BindxProvider or ContemberBindxProvider.
+ */
+export function useSchemaRegistry(): SchemaRegistry {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useSchemaRegistry must be used within a BindxProvider')
+	}
+	return context.schema
+}
+
+/**
+ * Hook to access the backend adapter.
+ * Must be used within a BindxProvider.
+ */
+export function useBackendAdapter(): BackendAdapter {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useBackendAdapter must be used within a BindxProvider')
+	}
+	return context.adapter
+}
+
+/**
+ * Hook to access the snapshot store.
+ * Must be used within a BindxProvider.
+ */
+export function useSnapshotStore(): SnapshotStore {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useSnapshotStore must be used within a BindxProvider')
+	}
+	return context.store
+}
+
+/**
+ * Hook to access the action dispatcher.
+ * Must be used within a BindxProvider.
+ */
+export function useDispatcher(): ActionDispatcher {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useDispatcher must be used within a BindxProvider')
+	}
+	return context.dispatcher
+}
+
+/**
+ * Hook to access the batch persister.
+ * Must be used within a BindxProvider.
+ */
+export function useBatchPersister(): BatchPersister {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useBatchPersister must be used within a BindxProvider')
+	}
+	return context.batchPersister
+}
+
+/**
+ * Hook to access all bindx services.
+ * Must be used within a BindxProvider.
+ */
+export function useBindxContext(): BindxContextValue {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useBindxContext must be used within a BindxProvider')
+	}
+	return context
+}
+
+/**
+ * Hook to access the query batcher.
+ * Must be used within a BindxProvider.
+ */
+export function useQueryBatcher(): QueryBatcher {
+	const context = useContext(BindxContext)
+	if (!context) {
+		throw new Error('useQueryBatcher must be used within a BindxProvider')
+	}
+	return context.batcher
+}

package/src/hooks/ContemberBindxProvider.tsx

@@ -0,0 +1,158 @@
+import { memo, useMemo, type ReactNode } from 'react'
+import { GraphQlClient } from '@contember/graphql-client'
+import { ContentClient, ContentQueryBuilder, type SchemaNames } from '@contember/client-content'
+import { ContemberAdapter, SnapshotStore, ActionDispatcher, BatchPersister, MutationCollector, ContemberSchemaMutationAdapter, UndoManager, SchemaRegistry, type SchemaDefinition, type FieldDef, type UndoManagerConfig, type UpdateMode } from '@contember/bindx'
+import { BindxContext, type BindxContextValue } from './BackendAdapterContext.js'
+import { QueryBatcher } from '../batching/QueryBatcher.js'
+
+/**
+ * Converts SchemaNames (Contember format) to SchemaDefinition (bindx format)
+ * so that a SchemaRegistry can be created for standalone hooks.
+ */
+export function schemaNamesToDef(schemaNames: SchemaNames): SchemaDefinition<Record<string, object>> {
+	const enumsMap = (schemaNames as { enums?: Record<string, readonly string[]> }).enums ?? {}
+	const entities: Record<string, { fields: Record<string, FieldDef> }> = {}
+	for (const [entityName, entity] of Object.entries(schemaNames.entities)) {
+		const fields: Record<string, FieldDef> = {}
+		for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
+			if (fieldDef.type === 'column') {
+				const enumName = (fieldDef as { enumName?: string }).enumName
+				const columnType = (fieldDef as { columnType?: string }).columnType
+				const enumValues = enumName ? enumsMap[enumName] : undefined
+				if (enumName && enumValues) {
+					fields[fieldName] = { type: 'enum', enumName, values: enumValues }
+				} else {
+					fields[fieldName] = { type: 'scalar', columnType }
+				}
+			} else if (fieldDef.type === 'one') {
+				fields[fieldName] = { type: 'hasOne', target: fieldDef.entity }
+			} else if (fieldDef.type === 'many') {
+				fields[fieldName] = { type: 'hasMany', target: fieldDef.entity }
+			}
+		}
+		entities[entityName] = { fields }
+	}
+	return { entities }
+}
+
+/**
+ * Props for ContemberBindxProvider
+ */
+export interface ContemberBindxProviderProps {
+	/** Contember schema names for query building */
+	schema: SchemaNames
+	/** Optional custom snapshot store (useful for testing) */
+	store?: SnapshotStore
+	/** Children */
+	children: ReactNode
+
+	client: GraphQlClient
+
+	/** Enable undo/redo functionality. Pass true to auto-create an UndoManager, or pass an UndoManager instance. */
+	undoManager?: UndoManager | boolean
+	/** Configuration for auto-created undo manager (only used when undoManager={true}) */
+	undoConfig?: UndoManagerConfig
+	/**
+	 * Default update mode for persistence operations.
+	 * - 'optimistic': Update UI immediately, revert on failure (default)
+	 * - 'pessimistic': Wait for server confirmation before updating UI
+	 */
+	defaultUpdateMode?: UpdateMode
+	/** Enable debug logging (e.g., selection collection output) */
+	debug?: boolean
+}
+
+/**
+ * Provider component that combines Contember authentication with bindx data binding.
+ *
+ * @example
+ * ```tsx
+ * import { ContemberBindxProvider, useUndo } from '@contember/bindx-react'
+ * import { schema } from './generated/schema'
+ *
+ * function App() {
+ *   return (
+ *     <ContemberBindxProvider
+ *       client={graphQlClient}
+ *       schema={schema}
+ *       undoManager={true}
+ *     >
+ *       <ArticleEditor id="123" />
+ *     </ContemberBindxProvider>
+ *   )
+ * }
+ *
+ * // Access undo/redo in child components
+ * function UndoControls() {
+ *   const { canUndo, canRedo, undo, redo } = useUndo()
+ *   return (
+ *     <div>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export const ContemberBindxProvider = memo(function ContemberBindxProvider({
+	schema,
+	store: customStore,
+	children,
+	client: graphQlClient,
+	undoManager: undoManagerProp,
+	undoConfig,
+	defaultUpdateMode,
+	debug = false,
+}: ContemberBindxProviderProps) {
+
+	// Create GraphQL client and adapter
+	const bindxValue = useMemo((): BindxContextValue => {
+
+		const adapter = new ContemberAdapter(new ContentClient(graphQlClient), new ContentQueryBuilder(schema))
+		const batcher = new QueryBatcher(adapter)
+
+		const store = customStore ?? new SnapshotStore()
+		const dispatcher = new ActionDispatcher(store)
+
+		// Create undo manager if enabled
+		const undoManager = undoManagerProp === true
+			? new UndoManager(store, undoConfig)
+			: undoManagerProp instanceof UndoManager
+				? undoManagerProp
+				: null
+		if (undoManager) {
+			dispatcher.addMiddleware(undoManager.createMiddleware())
+		}
+
+		// Create schema registry from SchemaNames for standalone hooks
+		const schemaRegistry = new SchemaRegistry(schemaNamesToDef(schema))
+
+		// Create mutation collector for proper nested operations
+		// Use ContemberSchemaMutationAdapter to wrap SchemaNames
+		const schemaAdapter = new ContemberSchemaMutationAdapter(schema)
+		const mutationCollector = new MutationCollector(store, schemaAdapter)
+
+		const batchPersister = new BatchPersister(adapter, store, dispatcher, {
+			mutationCollector,
+			undoManager: undoManager ?? undefined,
+			defaultUpdateMode,
+		})
+
+		return {
+			adapter,
+			batcher,
+			store,
+			dispatcher,
+			batchPersister,
+			schema: schemaRegistry,
+			undoManager,
+			debug,
+		}
+	}, [schema, customStore, undoManagerProp, undoConfig, defaultUpdateMode, debug])
+
+	return (
+		<BindxContext.Provider value={bindxValue}>
+			{children}
+		</BindxContext.Provider>
+	)
+})