@contember/bindx-react 0.1.46 → 0.1.48

package/src/jsx/componentFactory.ts

@@ -15,7 +15,6 @@ import type {
 	SelectionMeta,
 	SelectionBuilder,
 	AnyBrand,
-	EntityRef,
 	SchemaDefinition,
 } from '@contember/bindx'
 import {
@@ -33,7 +32,7 @@ import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from './types.js'
 import { createCollectorProxy } from './proxy.js'
 import { collectSelection } from './analyzer.js'
 import { type Condition, evaluateCondition } from './conditions.js'
-import { useAccessor } from '../hooks/useAccessor.js'
+import { useRefSubscription } from '../hooks/useFields.js'
 
 // ============================================================================
 // Symbols
@@ -70,17 +69,19 @@ export interface EntityConfig {
 // ============================================================================
 
 /**
- * Converts explicit entity ref props to accessors via useAccessor.
- * Called with a fixed list of prop names — hook count is stable across renders.
+ * Converts entity ref props to accessors while subscribing with one fixed hook.
  */
-function useRenderProps<TProps extends object>(props: TProps, explicitPropNames: string[]): TProps {
-	const record = props as Record<string, unknown>
-	const accessors: Record<string, unknown> = {}
-	for (const name of explicitPropNames) {
-		// eslint-disable-next-line react-hooks/rules-of-hooks -- stable iteration count (explicitPropNames is fixed at build time)
-		accessors[name] = useAccessor(record[name] as EntityRef<object>)
-	}
-	return { ...props, ...accessors } as TProps
+function readProperty(target: object, name: string): unknown {
+	return Reflect.get(target, name)
+}
+
+function useRenderProps<TProps extends object>(props: TProps, entityPropNames: string[]): TProps {
+	const refs = entityPropNames.map(name => readProperty(props, name))
+	const accessors = useRefSubscription(refs)
+	const accessorProps = Object.fromEntries(
+		entityPropNames.map((name, index) => [name, accessors[index]]),
+	)
+	return Object.assign({}, props, accessorProps)
 }
 
 // ============================================================================
@@ -101,8 +102,10 @@ export function buildComponent<TProps extends object>(
 	schemaRegistry: SchemaRegistry<Record<string, object>> | null,
 	conditionFn: ((props: TProps) => Condition) | null,
 	slotNames: readonly string[],
+	useFns: readonly ((props: TProps) => object)[],
 ): unknown {
 	const selectionsMap = new Map<string, SelectionPropMeta>()
+	const componentDisplayName = `BindxComponent(${[...entityConfigs.keys()].join(', ')})`
 
 	// Generate unique brand for this component
 	const componentBrand = new ComponentBrand(`component_${Math.random().toString(36).slice(2)}`)
@@ -121,34 +124,58 @@ export function buildComponent<TProps extends object>(
 		}
 	}
 
-	// Collect explicit entity prop names (stable list for hooks)
-	const explicitEntityPropNames = [...entityConfigs.entries()]
-		.filter(([_, c]) => c.selector)
-		.map(([name]) => name)
+	// Every entity prop is subscribed, selector or not: accessor identity is stable, so a
+	// memo()-wrapped component only learns about its entity through its own subscription.
+	// Interface props are appended during lazy collection, before the first runtime render.
+	const entityPropNames = [...entityConfigs.keys()]
 
 	// 2. Implicit entities - collect lazily to avoid TDZ errors
 	const implicitConfigs = [...entityConfigs.entries()].filter(([_, c]) => !c.selector)
-	let implicitCollected = false
+	// Tri-state: 'collecting' terminates self-recursive components
+	let collectionState: 'idle' | 'collecting' | 'done' = 'idle'
 
+	// Runs only from the static-analysis surface (getSelection, $propName fragment
+	// getters) — never from render. Render bodies stay pure runtime code.
 	function ensureImplicitCollected(): void {
 		// In interfaces mode, we also need to collect even if no explicit implicit configs exist
 		// (because interface props may be discovered dynamically)
 		// Also collect if there's a conditionFn (it may access entity fields)
-		if (implicitCollected || (implicitConfigs.length === 0 && !hasInterfacesMode && !conditionFn)) {
+		if (collectionState !== 'idle' || (implicitConfigs.length === 0 && !hasInterfacesMode && !conditionFn)) {
 			return
 		}
-		implicitCollected = true
-		collectImplicitSelections(implicitConfigs, renderFn, selectionsMap, componentBrand, roles, hasInterfacesMode, schemaRegistry, conditionFn)
+		collectionState = 'collecting'
+		try {
+			collectImplicitSelections(implicitConfigs, renderFn, selectionsMap, componentBrand, roles, hasInterfacesMode, schemaRegistry, conditionFn)
+		} catch (error) {
+			// Analysis is deterministic, so retrying is pointless — degrade loudly
+			// to the fields captured before the throw (scopes record eagerly).
+			console.error(
+				`[bindx] Implicit selection analysis of <${componentDisplayName}> failed — `
+				+ 'only fields accessed before the error were collected; fields used after it may be missing from queries.',
+				error,
+			)
+		} finally {
+			collectionState = 'done'
+			// Subscribe the props collection discovered too, incl. a degraded partial pass.
+			for (const propName of selectionsMap.keys()) {
+				if (!entityPropNames.includes(propName)) entityPropNames.push(propName)
+			}
+		}
 	}
 
 	// 3. Create React component
 	function ComponentImpl(props: TProps): ReactNode {
 		ensureImplicitCollected()
 
-		// Convert explicit entity refs to accessors (stable hook count — explicitEntityPropNames is fixed)
-		const renderProps = explicitEntityPropNames.length > 0
-			? useRenderProps(props, explicitEntityPropNames)
-			: props
+		// Subscribe every entity ref prop; an empty fixed list is a no-op.
+		let renderProps: TProps = useRenderProps(props, entityPropNames)
+
+		// Runtime-only values from .use() — hooks are allowed here; static analysis
+		// never executes these (their outputs are mocked in the collection pass).
+		for (const useFn of useFns) {
+			// eslint-disable-next-line react-hooks/rules-of-hooks -- stable iteration count (useFns is fixed at build time)
+			renderProps = { ...renderProps, ...useFn(renderProps) }
+		}
 
 		// Evaluate condition at runtime
 		if (conditionFn) {
@@ -161,6 +188,8 @@ export function buildComponent<TProps extends object>(
 	}
 
 	const MemoizedComponent = memo(ComponentImpl)
+	// Names for selection-analysis error attribution; users can override
+	MemoizedComponent.displayName = componentDisplayName
 
 	// 4. Attach metadata
 	const comp = MemoizedComponent as unknown as Record<symbol | string, unknown>
@@ -262,6 +291,34 @@ function createExplicitPropMock(): unknown {
 	})
 }
 
+/**
+ * Creates a tolerant stand-in for scalar (non-entity) props during collection.
+ * Render bodies may call it (`t('key')`), read nested properties
+ * (`labels.heading`) or coerce it to a primitive — all are no-ops so the
+ * collection pass keeps capturing entity field accesses (see issue #57).
+ */
+function createScalarPropMock(): unknown {
+	const mock: unknown = new Proxy(function () {}, {
+		get(_target, prop): unknown {
+			if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+				return (): string => ''
+			}
+			if (prop === Symbol.iterator) {
+				return function* (): Generator<never> {}
+			}
+			// undefined keeps JSON.stringify from recursing via a callable toJSON
+			if (prop === 'toJSON') {
+				return undefined
+			}
+			return mock
+		},
+		apply(): unknown {
+			return mock
+		},
+	})
+	return mock
+}
+
 /**
  * Collects selections from JSX for implicit entity props.
  *
@@ -327,18 +384,38 @@ function collectImplicitSelections<TProps extends object>(
 				return createCollectorProxy(scope, null, schemaRegistry)
 			}
 
-			// Scalar prop - return undefined
-			return undefined
+			// Scalar prop — tolerant stand-in so render bodies using it survive
+			return createScalarPropMock()
 		},
 	})
 
-	// Execute conditionFn to capture field accesses from the condition
-	if (conditionFn) {
-		conditionFn(propsProxy)
+	// Create fragments for captured entities
+	const finalizeScopes = (): void => {
+		for (const [propName, scope] of propScopes) {
+			if (scope.hasFields()) {
+				const selection = scope.toSelectionMeta()
+
+				selectionsMap.set(propName, {
+					selection,
+					fragment: createFragment(selection, componentBrand, roles),
+				})
+			}
+		}
 	}
 
-	// Execute render to capture field accesses
-	const jsx = renderFn(propsProxy)
+	let jsx: ReactNode
+	try {
+		// Execute conditionFn + render to capture field accesses
+		if (conditionFn) {
+			conditionFn(propsProxy)
+		}
+		jsx = renderFn(propsProxy)
+	} catch (error) {
+		// Scopes capture accesses eagerly, so a throw mid-render still leaves a
+		// usable partial selection — keep it, then let the caller report the error.
+		finalizeScopes()
+		throw error
+	}
 
 	// Analyze JSX tree for component-level selections (handles nested createComponent)
 	try {
@@ -349,17 +426,7 @@ function collectImplicitSelections<TProps extends object>(
 		// Field accesses are still captured in the scope tree via proxy.
 	}
 
-	// Create fragments for captured entities
-	for (const [propName, scope] of propScopes) {
-		if (scope.hasFields()) {
-			const selection = scope.toSelectionMeta()
-
-			selectionsMap.set(propName, {
-				selection,
-				fragment: createFragment(selection, componentBrand, roles),
-			})
-		}
-	}
+	finalizeScopes()
 }
 
 // ============================================================================

package/src/jsx/components/Attribute.tsx

@@ -34,11 +34,11 @@ export interface AttributeProps<T> {
  * ```
  */
 function AttributeImpl<T>({ field, format, children }: AttributeProps<T>): ReactElement | null {
-	if (field === undefined || field === null) {
+	const accessor = useField(field ?? null)
+	if (accessor === null) {
 		return children
 	}
 
-	const accessor = useField(field)
 	const extraProps = {
 		...format(accessor),
 		...(isDevAnnotationsEnabled() ? { 'data-field': field[FIELD_REF_META]?.fieldName } : {}),

package/src/jsx/components/Entity.tsx

@@ -319,9 +319,13 @@ interface EntityHandleRendererProps {
  * Shared component that creates an EntityHandle and renders children with it.
  * Used by both EntityByMode and EntityCreateMode.
  *
- * Subscribes to entity snapshot changes so that the handle reference changes
- * when entity data changes. This is necessary because children may be wrapped
- * in React.memo and need a new handle reference to trigger re-renders.
+ * Subscribes to the entity snapshot so this host re-renders on data changes,
+ * which keeps inline reads in `children` fresh. The EntityHandle itself has a
+ * stable identity — it is intentionally NOT recreated on data changes — because
+ * it is a stateless live view over the store (see BaseHandle). Memoized leaf
+ * components (<Field>, <HasOne>, <HasMany>) re-render through their own store
+ * subscription (useField/useAccessor), not through a changing handle reference,
+ * so a data change re-renders only the leaves that read the changed data.
  */
 function EntityHandleRenderer({
 	entityId,
@@ -342,11 +346,14 @@ function EntityHandleRenderer({
 		[store, entityType, entityId],
 	)
 
-	const version = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+	// Subscribe so this host re-renders on data changes (keeps inline reads in `children` fresh).
+	// The version is deliberately NOT fed into the handle memo below: the handle is a stable live
+	// view and must keep a stable identity across data changes.
+	useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
 	const rawHandle = useMemo(
 		() => EntityHandle.createRaw(entityId, entityType, store, dispatcher, schemaRegistry, undefined, selection),
-		[entityId, entityType, store, dispatcher, schemaRegistry, selection, version],
+		[entityId, entityType, store, dispatcher, schemaRegistry, selection],
 	)
 
 	const handle = useMemo(
@@ -354,13 +361,6 @@ function EntityHandleRenderer({
 		[rawHandle],
 	)
 
-	// `version` is a useMemo dep, so `rawHandle` is recreated on every entity data change (to give
-	// memoized children a fresh reference). Superseded handles need no cleanup: EntityHandle and its
-	// child Field/HasMany handles are stateless live views that own no resources (see BaseHandle),
-	// so they are reclaimed by GC once unreferenced — and a consumer that still holds an accessor
-	// from an earlier render (e.g. the Slate block editor dispatching `setValue` from an async
-	// onChange after the version bumped) can keep using it.
-
 	const result = children(handle as EntityAccessor<unknown>)
 	return <>{annotateElement(result, { 'data-entity': entityType, 'data-entity-id': entityId })}</>
 }

package/src/jsx/components/Field.tsx

@@ -22,13 +22,11 @@ import { annotateElement, isDevAnnotationsEnabled } from '../devAnnotations.js'
  * ```
  */
 function FieldImpl<T>({ field, children, format }: FieldProps<T>): ReactElement | null {
-	// Handle undefined field (e.g., when accessing field on disconnected has-one relation)
-	if (field === undefined || field === null) {
+	const accessor = useField(field ?? null)
+	if (accessor === null) {
 		return null
 	}
 
-	// useField() subscribes to store and returns FieldAccessor with .value access
-	const accessor = useField(field)
 	const fieldName = field[FIELD_REF_META]?.fieldName
 
 	if (children) {

package/src/jsx/components/If.tsx

@@ -3,6 +3,7 @@ import type { IfProps, SelectionFieldMeta, SelectionMeta, SelectionProvider, Fie
 import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
 import { mergeSelections, createEmptySelection } from '../SelectionMeta.js'
 import { useField } from '../../hooks/useField.js'
+import { useRefSubscription } from '../../hooks/useFields.js'
 import {
 	type Condition,
 	isCondition,
@@ -11,6 +12,8 @@ import {
 	CONDITION_META,
 } from '../conditions.js'
 
+const NO_CONDITION_FIELDS: readonly unknown[] = []
+
 /**
  * If component - conditional rendering that ensures both branches are analyzed
  *
@@ -55,6 +58,9 @@ import {
 function IfImpl({ condition, then: thenBranch, else: elseBranch }: IfProps): ReactElement | null {
 	const fieldRef = typeof condition !== 'boolean' && !isCondition(condition) ? condition : null
 	const fieldAccessor = useField(fieldRef)
+	// A Condition is evaluated against live data, so it needs a subscription of its own —
+	// a memoized <If> is not re-rendered by its parent.
+	useRefSubscription(isCondition(condition) ? collectConditionFields(condition) : NO_CONDITION_FIELDS)
 
 	let conditionValue: boolean
 

package/src/jsx/components/Switch.tsx

@@ -13,7 +13,7 @@ import type {
 	SelectionProvider,
 } from '../types.js'
 import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
-import { useField } from '../../hooks/useField.js'
+import { useFields, useRefSubscription } from '../../hooks/useFields.js'
 import {
 	type Condition,
 	isCondition,
@@ -132,6 +132,20 @@ function resolveTriggerField(props: CaseProps<unknown>): FieldRef<unknown> | nul
 	return null
 }
 
+/**
+ * Fields read by `if={cond...}` cases. They are evaluated against live data, so they need
+ * a subscription of their own — a memoized <Switch> is not re-rendered by its parent.
+ */
+function collectConditionRefs(cases: readonly CaseEntry[]): unknown[] {
+	const refs: unknown[] = []
+	for (const { props } of cases) {
+		if ('if' in props && props.if !== undefined && isCondition(props.if)) {
+			refs.push(...collectConditionFields(props.if))
+		}
+	}
+	return refs
+}
+
 // =============================================================================
 // Runtime
 // =============================================================================
@@ -139,17 +153,14 @@ function resolveTriggerField(props: CaseProps<unknown>): FieldRef<unknown> | nul
 function SwitchImpl({ children }: SwitchProps): ReactElement | null {
 	const entries = extractEntries(children)
 
-	// Subscribe to one field per case (stable count, stable order).
-	const accessors: Array<{ value: unknown } | null> = []
-	for (const entry of entries.cases) {
-		const ref = resolveTriggerField(entry.props)
-		// eslint-disable-next-line react-hooks/rules-of-hooks
-		accessors.push(useField(ref))
-	}
+	// Two fixed hooks cover every case, so the hook count never depends on how many
+	// <Case> children are rendered (a conditional <Case> used to crash React).
+	const accessors = useFields(entries.cases.map(entry => resolveTriggerField(entry.props)))
+	useRefSubscription(collectConditionRefs(entries.cases))
 
 	for (let i = 0; i < entries.cases.length; i++) {
 		const { props } = entries.cases[i]!
-		const accessor = accessors[i]!
+		const accessor = accessors[i]
 
 		if ('show' in props && props.show !== undefined) {
 			const value = accessor?.value

package/src/jsx/standaloneCreateComponent.ts

@@ -32,11 +32,9 @@ import { createComponentBuilder } from './componentBuilder.js'
  *   ))
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/ban-types
 export function createComponent(): ComponentBuilder<ComponentBuilderState<{}, object, readonly string[]>>
 export function createComponent<const TRoles extends readonly string[]>(
 	options: CreateComponentOptions<TRoles>,
-// eslint-disable-next-line @typescript-eslint/ban-types
 ): ComponentBuilder<ComponentBuilderState<{}, object, TRoles>>
 export function createComponent(options?: CreateComponentOptions<readonly string[]>): ComponentBuilder<ComponentBuilderState> {
 	const roles = options?.roles ?? []