@contember/bindx-react 0.1.0

package/src/index.ts

@@ -0,0 +1,357 @@
+/**
+ * React Bindx - Type-safe React data binding framework
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Re-export core types and functions from @contember/bindx
+// ============================================================================
+
+export type {
+	// Schema types
+	RelationType,
+	ScalarFieldDef,
+	HasOneRelationDef,
+	HasManyRelationDef,
+	FieldDef,
+	EntitySchemaDef,
+	SchemaDefinition,
+	InferModel,
+	InferEntityNames,
+	EntityDef,
+	InferEntityDef,
+	// Role types
+	UnionToIntersection,
+	RoleNames,
+	CommonEntity,
+	EntityForRoles,
+	ResolveEntity,
+	SingleRoleMap,
+	DefaultRole,
+	// Selection types
+	SelectionBuilder,
+	SelectionMeta,
+	SelectionFieldMeta,
+	FluentFragment,
+	FluentDefiner,
+	HasManyOptions,
+	InferSelection,
+	QuerySpec,
+	QueryFieldSpec,
+	// Query types (typed filter/orderBy)
+	EntityWhere,
+	EntityOrderBy,
+	ScalarCondition,
+	OrderDirection,
+	TypedHasManyOptions,
+	AliasOptions,
+	// Handle types
+	HasOneRelationState,
+	InputProps,
+	EntityFields,
+	SelectedEntityFields,
+	ScalarKeys,
+	HasManyKeys,
+	HasOneKeys,
+	FieldRefMeta,
+	FieldRef,
+	HasManyRef,
+	HasOneRef,
+	EntityRef,
+	// Type extraction helpers
+	ExtractHasOneEntityName,
+	ExtractHasManyEntityName,
+	ExtractRoleMap,
+	// Adapter types
+	BackendAdapter,
+	QueryOptions,
+	Query,
+	GetQuery,
+	ListQuery,
+	QueryResult,
+	GetQueryResult,
+	ListQueryResult,
+	MockDataStore,
+	MockAdapterOptions,
+	ContemberAdapterOptions,
+	// Core types
+	EntityLoadResult,
+	EntityListLoadResult,
+	LoadEntityOptions,
+	LoadEntityListOptions,
+	SelectionInput,
+	CoreFluentDefiner,
+	// Store types
+	EntitySnapshot,
+	FieldSnapshot,
+	HasOneRelationSnapshot,
+	HasManySnapshot,
+	EntityState,
+	LoadStatus,
+	// Undo types
+	UndoManagerConfig,
+	UndoState,
+	UndoEntry,
+	// Event types
+	BindxEvent,
+	FieldScopedEvent,
+	FieldChangingEvent,
+	FieldChangedEvent,
+	RelationConnectingEvent,
+	RelationConnectedEvent,
+	RelationDisconnectingEvent,
+	RelationDisconnectedEvent,
+	RelationDeletingEvent,
+	RelationDeletedEvent,
+	HasManyConnectingEvent,
+	HasManyConnectedEvent,
+	HasManyDisconnectingEvent,
+	HasManyDisconnectedEvent,
+	EntityPersistingEvent,
+	EntityPersistedEvent,
+	EntityPersistFailedEvent,
+	EntityResettingEvent,
+	EntityResetEvent,
+	EntityDeletingEvent,
+	EntityDeletedEvent,
+	ErrorAddedEvent,
+	ErrorsClearedEvent,
+	LoadStateChangedEvent,
+	BeforeEvent,
+	AfterEvent,
+	AnyBindxEvent,
+	EventTypeMap,
+	InterceptorResult,
+	Interceptor,
+	EventListener,
+	Unsubscribe,
+	BeforeEventTypes,
+	AfterEventTypes,
+} from '@contember/bindx'
+
+export {
+	// Schema utilities
+	scalar,
+	hasOne,
+	hasMany,
+	defineSchema,
+	entityDef,
+	roleEntityDef,
+	DEFAULT_ROLE,
+	SchemaRegistry,
+	// Selection utilities
+	createFragment,
+	buildQueryFromSelection,
+	// Handles
+	EntityHandle,
+	HasOneHandle,
+	HasManyListHandle,
+	FieldHandle,
+	// Handle symbols
+	FIELD_REF_META,
+	// Adapter
+	MockAdapter,
+	ContemberAdapter,
+	// Core
+	createEntityLoader,
+	resolveSelectionMeta,
+	buildQuery,
+	// Store
+	SnapshotStore,
+	ActionDispatcher,
+	// ID type detection
+	isTempId,
+	isPlaceholderId,
+	isPersistedId,
+	generatePlaceholderId,
+	// Persistence
+	BatchPersister,
+	ChangeRegistry,
+	// Undo
+	UndoManager,
+	// Events
+	EventEmitter,
+	// Internal
+	__internal,
+} from '@contember/bindx'
+
+// ============================================================================
+// React-specific types
+// ============================================================================
+
+// Hook types
+export type {
+	BindxProviderProps,
+	BindxContextValue,
+	UseEntityOptions,
+	UseEntityListOptions,
+	LoadingEntityAccessor,
+	ErrorEntityAccessor,
+	NotFoundEntityAccessor,
+	ReadyEntityAccessor,
+	EntityAccessorResult,
+	LoadingEntityListAccessor,
+	ErrorEntityListAccessor,
+	ReadyEntityListAccessor,
+	EntityListAccessorResult,
+	// Persistence hook types
+	PersistApi,
+	EntityPersistApi,
+	AnyRefWithMeta,
+} from './hooks/index.js'
+
+// Persistence types from @contember/bindx
+export type {
+	DirtyEntity,
+	PersistScope,
+	AllScope,
+	EntityScope as EntityPersistScope,
+	FieldsScope,
+	RelationScope,
+	CustomScope,
+	EntityPersistResult,
+	PersistenceResult,
+	BatchPersistOptions,
+} from '@contember/bindx'
+
+// JSX types
+export type {
+	EntityAccessor,
+	FieldRefBase,
+	FieldProps,
+	HasManyProps,
+	HasOneProps,
+	IfProps,
+	EntityComponentProps,
+	HasManyComponentOptions,
+	ShowProps,
+	SelectionPropMeta,
+	SelectionProvider,
+	EntityPropKeys,
+	EntityFromProp,
+	SelectionFromProp,
+	ImplicitFragmentProperties,
+	// Component builder types
+	BindxComponentBase,
+	BindxComponent,
+	ComponentBuilder,
+	ComponentBuilderState,
+	CreateComponentOptions,
+	// Interface types
+	InterfaceEntityPropConfig,
+	ImplicitInterfaceEntityConfig,
+	ExplicitInterfaceEntityConfig,
+	AddInterfaces,
+	InterfaceSelectorsMap,
+	AnyEntityPropConfig,
+	// Entity prop config types
+	EntityPropConfig,
+	ImplicitEntityConfig,
+	ExplicitEntityConfig,
+	// State helpers
+	AddImplicitEntity,
+	AddExplicitEntity,
+	AddImplicitInterfaceEntity,
+	AddExplicitInterfaceEntity,
+	SetScalarProps,
+	// Props building
+	BuildEntityProps,
+	BuildProps,
+	BuildFragmentProps,
+	InitialBuilderState,
+} from './jsx/index.js'
+
+// ============================================================================
+// React-specific functions & components
+// ============================================================================
+
+// Hooks
+export {
+	BindxProvider,
+	useBackendAdapter,
+	useSnapshotStore,
+	useDispatcher,
+	useBatchPersister,
+	useBindxContext,
+	useSchemaRegistry,
+	// Standalone hooks
+	useEntity,
+	useEntityList,
+	// Persistence
+	usePersist,
+	usePersistEntity,
+	// Undo
+	useUndo,
+	// Events
+	useOnEvent,
+	useOnEntityEvent,
+	useOnFieldEvent,
+	useIntercept,
+	useInterceptEntity,
+	useInterceptField,
+	// Contember
+	ContemberBindxProvider,
+	schemaNamesToDef,
+} from './hooks/index.js'
+
+// Role context
+export { RoleProvider, useHasRole, type RoleProviderProps } from './roles/index.js'
+
+// Undo hook types
+export type { UndoHookResult } from './hooks/useUndo.js'
+
+
+// JSX Components
+export {
+	Field,
+	HasMany,
+	HasOne,
+	If,
+	Show,
+	Entity,
+	type EntityProps,
+	EntityList,
+	type EntityListProps,
+	HasRole,
+	type HasRoleProps,
+	BINDX_COMPONENT,
+	// Condition DSL for <If> component
+	cond,
+	type Condition,
+	// Component (unified API)
+	createComponent,
+	withCollector,
+	isBindxComponent,
+	mergeFragments,
+	COMPONENT_MARKER,
+	COMPONENT_BRAND,
+	COMPONENT_SELECTIONS,
+	createComponentBuilder,
+	getComponentBrand,
+	setBrandValidation,
+	validateBrand,
+} from './jsx/index.js'
+
+// Entity Scope
+export {
+	EntityScope,
+	useEntityScope,
+	useOptionalEntityScope,
+	type EntityScopeProps,
+} from './components/EntityScope.js'
+
+// ============================================================================
+// Internal React API
+// ============================================================================
+
+export {
+	SelectionMetaCollector,
+	mergeSelections,
+	createEmptySelection,
+	createCollectorProxy,
+	analyzeJsx,
+	collectSelection,
+	convertToQuerySelection,
+	debugSelection,
+} from './jsx/index.js'

package/src/jsx/SelectionMeta.ts

@@ -0,0 +1,2 @@
+// Re-export from @contember/bindx
+export { SelectionMetaCollector, mergeSelections, createEmptySelection } from '@contember/bindx'

package/src/jsx/analyzer.ts

@@ -0,0 +1,261 @@
+import type { ReactNode, ReactElement } from 'react'
+import { isValidElement } from 'react'
+import type { SelectionMeta, SelectionFieldMeta, SelectionProvider } from './types.js'
+import { FIELD_REF_META, SCOPE_REF } from './types.js'
+import { SelectionMetaCollector, mergeSelections } from './SelectionMeta.js'
+import { SelectionScope } from '@contember/bindx'
+import { isBindxComponent, COMPONENT_SELECTIONS } from './createComponent.js'
+
+/**
+ * Analyzes JSX tree to extract field selection metadata.
+ * This is called during the collection phase to determine which fields need to be fetched.
+ */
+export function analyzeJsx(node: ReactNode, selection: SelectionMetaCollector): void {
+	// Handle null/undefined
+	if (node === null || node === undefined) {
+		return
+	}
+
+	// Handle primitives (string, number, boolean)
+	if (typeof node !== 'object') {
+		return
+	}
+
+	// Handle arrays
+	if (Array.isArray(node)) {
+		for (const child of node) {
+			analyzeJsx(child, selection)
+		}
+		return
+	}
+
+	// Must be a React element at this point
+	if (!isValidElement(node)) {
+		return
+	}
+
+	const element = node as ReactElement<{ children?: ReactNode }>
+
+	// Handle React Fragment and host elements (div, span, etc.) - just analyze children
+	if (typeof element.type === 'symbol' || typeof element.type === 'string') {
+		if (element.props.children) {
+			analyzeJsx(element.props.children, selection)
+		}
+		return
+	}
+
+	// Handle function components
+	const component = element.type as unknown
+
+	// Check if it's a bindx component with pre-computed selection - needs special handling
+	if (isBindxComponent(component)) {
+		// First, trigger implicit collection if the component has getSelection
+		// This ensures lazy implicit selections are collected before we access COMPONENT_SELECTIONS
+		const componentObj = component as Record<string, unknown>
+		if ('getSelection' in componentObj && typeof componentObj['getSelection'] === 'function') {
+			;(component as SelectionProvider).getSelection(element.props as Record<string, unknown>, () => new SelectionMetaCollector())
+		}
+
+		handleBindxComponent(
+			component as { [COMPONENT_SELECTIONS]: Map<string, { selection: SelectionMeta }> },
+			element.props as Record<string, unknown>,
+			selection,
+		)
+		return
+	}
+
+	// Check if it's a component with getSelection (memo() wrapped or plain function components)
+	if (
+		component !== null &&
+		(typeof component === 'object' || typeof component === 'function') &&
+		'getSelection' in component &&
+		typeof (component as SelectionProvider).getSelection === 'function'
+	) {
+		const provider = component as SelectionProvider
+
+		// Collector function for nested selection analysis
+		const collectNested = (children: ReactNode): SelectionMeta => {
+			const nestedSelection = new SelectionMetaCollector()
+			analyzeJsx(children, nestedSelection)
+			return nestedSelection
+		}
+
+		// Get selection info from the component
+		const fieldSelection = provider.getSelection(element.props, collectNested)
+
+		// Add to selection
+		if (fieldSelection) {
+			if (Array.isArray(fieldSelection)) {
+				for (const field of fieldSelection) {
+					selection.addField(field)
+				}
+			} else {
+				selection.addField(fieldSelection)
+			}
+		}
+
+		return
+	}
+
+	// Check if component has staticRender — like Contember OSS's Component(render, staticRender) pattern.
+	// staticRender receives the same props (with collector proxies during analysis) and returns JSX to analyze.
+	if (
+		component !== null &&
+		(typeof component === 'object' || typeof component === 'function') &&
+		'staticRender' in component &&
+		typeof (component as { staticRender: unknown }).staticRender === 'function'
+	) {
+		const staticJsx = (component as { staticRender: (props: Record<string, unknown>) => ReactNode }).staticRender(
+			element.props as Record<string, unknown>,
+		)
+		if (staticJsx) {
+			analyzeJsx(staticJsx, selection)
+		}
+		return
+	}
+
+	// For non-bindx components, try to analyze children
+	// This handles wrapper components that pass children through
+	const children = element.props.children
+	if (children) {
+		analyzeJsx(children, selection)
+	}
+}
+
+/**
+ * Collects all field selections from a JSX tree.
+ * Entry point for the collection phase.
+ */
+export function collectSelection(jsx: ReactNode): SelectionMetaCollector {
+	const selection = new SelectionMetaCollector()
+	analyzeJsx(jsx, selection)
+	return selection
+}
+
+/**
+ * Converts JSX selection metadata to the format used by query builder
+ */
+export function convertToQuerySelection(jsxSelection: SelectionMeta): Record<string, unknown> {
+	const result: Record<string, unknown> = {}
+
+	for (const [_, field] of jsxSelection.fields) {
+		if (field.path.length !== 1) {
+			// Skip nested paths - they're handled by parent relations
+			continue
+		}
+
+		if (field.isRelation && field.nested) {
+			// Relation with nested selection
+			const nestedQuery = convertToQuerySelection(field.nested)
+
+			if (field.isArray && field.hasManyParams) {
+				// HasMany with params
+				result[field.fieldName] = {
+					...nestedQuery,
+					__params: field.hasManyParams,
+				}
+			} else {
+				result[field.fieldName] = nestedQuery
+			}
+		} else {
+			// Scalar field
+			result[field.fieldName] = true
+		}
+	}
+
+	return result
+}
+
+/**
+ * Handles bindx component in JSX analysis.
+ * Merges the component's pre-computed selection into the parent selection,
+ * adjusted to the correct path context based on the entity prop.
+ */
+function handleBindxComponent(
+	component: { [COMPONENT_SELECTIONS]: Map<string, { selection: SelectionMeta }> },
+	props: Record<string, unknown>,
+	parentSelection: SelectionMetaCollector,
+): void {
+	const entityPropsMap = component[COMPONENT_SELECTIONS]
+	// For each entity prop in the fragment component
+	for (const [propName, meta] of entityPropsMap) {
+		const propValue = props[propName]
+
+		if (!propValue || typeof propValue !== 'object') {
+			continue
+		}
+
+		// Case 1: Prop has SCOPE_REF - direct reference to SelectionScope
+		// This is the case when passing relation.entity to a nested component
+		if (SCOPE_REF in propValue) {
+			const targetScope = (propValue as { [SCOPE_REF]: SelectionScope })[SCOPE_REF]
+			// Merge the nested component's selection directly into the relation's scope
+			targetScope.mergeFromSelectionMeta(meta.selection)
+		}
+		// Case 2: Prop is a FieldRef from a relation (e.g., article.fields.author)
+		// This has FIELD_REF_META with a path to adjust
+		else if (FIELD_REF_META in propValue) {
+			const refMeta = (propValue as { [FIELD_REF_META]: { path: string[]; fieldName: string } })[FIELD_REF_META]
+
+			// Add fields with adjusted paths to parent selection
+			for (const [_key, field] of meta.selection.fields) {
+				// Only process root-level fields from the fragment
+				if (field.path.length === 1) {
+					// Create a new field meta with the path adjusted to the parent context
+					const adjustedField: SelectionFieldMeta = {
+						...field,
+						path: [...refMeta.path, ...field.path],
+					}
+
+					// If the field has nested selection, we need to preserve it
+					if (field.nested) {
+						adjustedField.nested = field.nested
+					}
+
+					parentSelection.addField(adjustedField)
+				}
+			}
+		}
+		// Case 3: Prop is an EntityRef from Entity children callback (root level)
+		// This doesn't have FIELD_REF_META, just merge the fields directly
+		else if ('id' in propValue && 'fields' in propValue) {
+			// This is an EntityRef - merge fragment's selection directly
+			for (const [_key, field] of meta.selection.fields) {
+				if (field.path.length === 1) {
+					parentSelection.addField({ ...field })
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Debug helper - prints selection tree
+ */
+export function debugSelection(selection: SelectionMeta, indent = 0): string {
+	const lines: string[] = []
+	const prefix = '  '.repeat(indent)
+
+	for (const [key, field] of selection.fields) {
+		let line = `${prefix}${field.fieldName}`
+
+		if (field.isArray) {
+			line += '[]'
+		}
+		if (field.isRelation) {
+			line += ' (relation)'
+		}
+		if (field.hasManyParams) {
+			const params = JSON.stringify(field.hasManyParams)
+			line += ` ${params}`
+		}
+
+		lines.push(line)
+
+		if (field.nested) {
+			lines.push(debugSelection(field.nested, indent + 1))
+		}
+	}
+
+	return lines.join('\n')
+}