@contember/bindx-react 0.1.5 → 0.1.11

package/src/hooks/useEntityList.ts

@@ -34,106 +34,66 @@ export interface UseEntityListOptions {
 // Result types
 // ============================================================================
 
-/**
- * Loading state for entity list accessor
- */
-export interface LoadingEntityListAccessor {
-	readonly status: 'loading'
-	readonly isLoading: true
-	readonly isError: false
-	readonly isDirty: false
-	readonly items: never
-	readonly length: 0
-	add(data?: unknown): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
+interface EntityListResultBase {
+	$add(data?: unknown): string
+	$remove(key: string): void
+	$move(fromIndex: number, toIndex: number): void
 }
 
-/**
- * Error state for entity list accessor
- */
-export interface ErrorEntityListAccessor {
-	readonly status: 'error'
-	readonly isLoading: false
-	readonly isError: true
-	readonly error: FieldError
-	readonly isDirty: false
-	readonly items: never
-	readonly length: 0
-	add(data?: unknown): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
+export type LoadingEntityListResult = EntityListResultBase & {
+	readonly $status: 'loading'
+	readonly $isLoading: true
+	readonly $isError: false
+	readonly $error: null
 }
 
-/**
- * Ready state for entity list accessor
- */
-export interface ReadyEntityListAccessor<T extends object> {
-	readonly status: 'ready'
-	readonly isLoading: false
-	readonly isError: false
-	readonly isDirty: boolean
+export type ErrorEntityListResult = EntityListResultBase & {
+	readonly $status: 'error'
+	readonly $isLoading: false
+	readonly $isError: true
+	readonly $error: FieldError
+}
+
+export type ReadyEntityListResult<T extends object> = EntityListResultBase & {
+	readonly $status: 'ready'
+	readonly $isLoading: false
+	readonly $isError: false
+	readonly $error: null
+	readonly $isDirty: boolean
 	readonly items: Array<EntityAccessor<T>>
 	readonly length: number
-	add(data?: Partial<T>): string
-	remove(key: string): void
-	move(fromIndex: number, toIndex: number): void
 }
 
-/**
- * Union of all entity list accessor states
- */
-export type EntityListAccessorResult<T extends object> =
-	| LoadingEntityListAccessor
-	| ErrorEntityListAccessor
-	| ReadyEntityListAccessor<T>
+export type UseEntityListResult<T extends object> =
+	| LoadingEntityListResult
+	| ErrorEntityListResult
+	| ReadyEntityListResult<T>
 
 // ============================================================================
 // Internal helpers
 // ============================================================================
 
-function createLoadingListAccessor(): LoadingEntityListAccessor {
+function createLoadingListResult(): LoadingEntityListResult {
 	return {
-		status: 'loading',
-		isLoading: true,
-		isError: false,
-		isDirty: false,
-		get items(): never {
-			throw new Error('Cannot access items while loading')
-		},
-		length: 0,
-		add() {
-			throw new Error('Cannot add items while loading')
-		},
-		remove() {
-			throw new Error('Cannot remove items while loading')
-		},
-		move() {
-			throw new Error('Cannot move items while loading')
-		},
+		$status: 'loading',
+		$isLoading: true,
+		$isError: false,
+		$error: null,
+		$add() { throw new Error('Cannot add items while loading') },
+		$remove() { throw new Error('Cannot remove items while loading') },
+		$move() { throw new Error('Cannot move items while loading') },
 	}
 }
 
-function createErrorListAccessor(error: FieldError): ErrorEntityListAccessor {
+function createErrorListResult(error: FieldError): ErrorEntityListResult {
 	return {
-		status: 'error',
-		isLoading: false,
-		isError: true,
-		error,
-		isDirty: false,
-		get items(): never {
-			throw new Error('Cannot access items after error')
-		},
-		length: 0,
-		add() {
-			throw new Error('Cannot add items after error')
-		},
-		remove() {
-			throw new Error('Cannot remove items after error')
-		},
-		move() {
-			throw new Error('Cannot move items after error')
-		},
+		$status: 'error',
+		$isLoading: false,
+		$isError: true,
+		$error: error,
+		$add() { throw new Error('Cannot add items after error') },
+		$remove() { throw new Error('Cannot remove items after error') },
+		$move() { throw new Error('Cannot move items after error') },
 	}
 }
 
@@ -157,7 +117,7 @@ export function useEntityList<
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityListOptions & { roles: readonly TRoles[] },
 	definer: SelectionInput<EntityForRoles<TRoleMap, TRoles>, TResult>,
-): EntityListAccessorResult<TResult>
+): UseEntityListResult<TResult>
 
 /**
  * Hook to fetch and manage a list of entities with full type inference.
@@ -174,7 +134,7 @@ export function useEntityList<TRoleMap extends Record<string, object>, TResult e
 	entity: EntityDef<TRoleMap>,
 	options: UseEntityListOptions,
 	definer: SelectionInput<CommonEntity<TRoleMap>, TResult>,
-): EntityListAccessorResult<TResult>
+): UseEntityListResult<TResult>
 
 /**
  * Hook to fetch and manage a list of entities with pre-resolved selection.
@@ -185,7 +145,7 @@ export function useEntityList<TRoleMap extends Record<string, object>, TResult e
 export function useEntityList(
 	entity: EntityDef,
 	options: UseEntityListOptions & { selection: SelectionMeta },
-): EntityListAccessorResult<object>
+): UseEntityListResult<object>
 
 // ============================================================================
 // Implementation
@@ -197,7 +157,7 @@ export function useEntityList(
 	options: UseEntityListOptions,
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	definer?: SelectionInput<any, any>,
-): EntityListAccessorResult<any> {
+): UseEntityListResult<any> {
 	const schemaRegistry = useSchemaRegistry()
 	const entityType = entity.$name
 	const { store, dispatcher, batcher } = useBindxContext()
@@ -250,7 +210,7 @@ export function useEntityList(
 		version: number
 		storeVersion: number
 		status: string
-		result: EntityListAccessorResult<object>
+		result: UseEntityListResult<any>
 	} | null>(null)
 
 	// --- Store subscription ---
@@ -310,7 +270,7 @@ export function useEntityList(
 	)
 
 	// --- Snapshot ---
-	const getSnapshot = useCallback((): EntityListAccessorResult<object> => {
+	const getSnapshot = useCallback((): UseEntityListResult<any> => {
 		const state = listStateRef.current
 		const version = versionRef.current
 		const storeVersion = store.getVersion()
@@ -320,12 +280,12 @@ export function useEntityList(
 			return cache.result
 		}
 
-		let result: EntityListAccessorResult<object>
+		let result: UseEntityListResult<any>
 
 		if (state.status === 'loading') {
-			result = createLoadingListAccessor()
+			result = createLoadingListResult()
 		} else if (state.status === 'error') {
-			result = createErrorListAccessor(state.error!)
+			result = createErrorListResult(state.error!)
 		} else {
 			const items = state.items.map((item) => {
 				return EntityHandle.create<object>(
@@ -334,19 +294,20 @@ export function useEntityList(
 					store,
 					dispatcher,
 					schemaRegistry as SchemaRegistry<Record<string, object>>,
-				) as unknown as EntityAccessor<object>
+				) as unknown as EntityAccessor<any>
 			})
 
 			result = {
-				status: 'ready',
-				isLoading: false,
-				isError: false,
-				isDirty: false,
+				$status: 'ready',
+				$isLoading: false,
+				$isError: false,
+				$error: null,
+				$isDirty: false,
 				items,
 				length: items.length,
-				add: addItem,
-				remove: removeItem,
-				move: moveItem,
+				$add: addItem,
+				$remove: removeItem,
+				$move: moveItem,
 			}
 		}
 
@@ -361,7 +322,7 @@ export function useEntityList(
 	}, [entityType, store, dispatcher, schemaRegistry, addItem, removeItem, moveItem])
 
 	const isEqual = useCallback(
-		(a: EntityListAccessorResult<object>, b: EntityListAccessorResult<object>): boolean => {
+		(a: UseEntityListResult<any>, b: UseEntityListResult<any>): boolean => {
 			return a === b
 		},
 		[],

package/src/index.ts

@@ -184,17 +184,18 @@ export {
 export type {
 	BindxProviderProps,
 	BindxContextValue,
+	BindxGraphQlClient,
 	UseEntityOptions,
 	UseEntityListOptions,
-	LoadingEntityAccessor,
-	ErrorEntityAccessor,
-	NotFoundEntityAccessor,
-	ReadyEntityAccessor,
-	EntityAccessorResult,
-	LoadingEntityListAccessor,
-	ErrorEntityListAccessor,
-	ReadyEntityListAccessor,
-	EntityListAccessorResult,
+	LoadingEntityResult,
+	ErrorEntityResult,
+	NotFoundEntityResult,
+	ReadyEntityResult,
+	UseEntityResult,
+	LoadingEntityListResult,
+	ErrorEntityListResult,
+	ReadyEntityListResult,
+	UseEntityListResult,
 	// Persistence hook types
 	PersistApi,
 	EntityPersistApi,
@@ -316,6 +317,7 @@ export {
 	HasRole,
 	type HasRoleProps,
 	BINDX_COMPONENT,
+	SCOPE_REF,
 	// Condition DSL for <If> component
 	cond,
 	type Condition,

package/src/jsx/collectorProxy.ts

@@ -47,6 +47,7 @@ export function createCollectorProxy<T>(
 		$fields: fieldsProxy,
 		$data: null,
 		$isDirty: false,
+		$isPersisting: false,
 		$persistedId: null,
 		$isNew: true,
 		__entityType: undefined as unknown as T,
@@ -189,7 +190,7 @@ function createCollectorFieldRef(
 		items: [],
 		map: mapFn,
 		add: () => '',
-		getById: () => ({} as any),
+		getById: () => createCollectorProxy<unknown>(getChildScope(), targetEntityName, schemaRegistry),
 		remove: () => {},
 		move: () => {},
 		connect: () => {},
@@ -226,6 +227,7 @@ function createCollectorFieldRef(
 		// EntityRef-compatible properties (for HasOneAccessor = EntityAccessor compatibility)
 		id: placeholderId,
 		$data: null,
+		$isPersisting: false,
 		$isNew: false,
 		$persistedId: null,
 		__entityName: targetEntityName ?? '',
@@ -248,20 +250,27 @@ function createCollectorFieldRef(
 	// This works for all field types:
 	// - Scalar fields: Accessing ref.value works (exists on target, passes through)
 	// - Has-many fields: Accessing ref.items/length works (exists on target, passes through)
-	// - Has-one with schema: Direct field access proxies to $fields
+	// - Has-one with schema: Direct field access proxies to $fields (isHasOneRelation=true)
 	// - Has-one without schema: Same - direct field access proxies to $fields
 	// The hasOneFieldsProxy creates nested collector refs which properly track selection.
-	return wrapCollectorRefWithFieldAccessProxy(refObject, hasOneFieldsProxy)
+	return wrapCollectorRefWithFieldAccessProxy(refObject, hasOneFieldsProxy, isHasOneRelation)
 }
 
 /**
  * Wraps a collector ref in a Proxy that supports direct field access for hasOne relations.
  * - `ref.fieldName` is equivalent to `ref.$fields.fieldName`
  * - Known ref properties pass through to the target
+ *
+ * When `isHasOneRelation` is true, matches runtime EntityHandle proxy behavior:
+ * only `id`, `$`-prefixed, and `__`-prefixed properties pass through;
+ * everything else is delegated to `fieldsProxy` as field access on the related entity.
+ * This prevents built-in ref properties (like `items`, `value`, `map`) from
+ * shadowing entity field names on the has-one target.
  */
 function wrapCollectorRefWithFieldAccessProxy(
 	ref: CollectorRef,
 	fieldsProxy: EntityFields<unknown>,
+	isHasOneRelation: boolean,
 ): CollectorRef {
 	return new Proxy(ref, {
 		get(target, prop) {
@@ -270,7 +279,17 @@ function wrapCollectorRefWithFieldAccessProxy(
 				return Reflect.get(target, prop)
 			}
 
-			// Check if property exists on target - if so, pass through
+			if (isHasOneRelation) {
+				// For has-one relations, match runtime EntityHandle proxy behavior:
+				// Only pass through id, $-prefixed, and __-prefixed properties.
+				// Everything else is field access on the related entity.
+				if (prop === 'id' || prop.startsWith('$') || prop.startsWith('__')) {
+					return Reflect.get(target, prop)
+				}
+				return fieldsProxy[prop as keyof EntityFields<unknown>]
+			}
+
+			// For has-many/scalar/unknown: existing behavior
 			if (prop in target) {
 				return Reflect.get(target, prop)
 			}

package/src/jsx/components/Entity.tsx

@@ -106,18 +106,19 @@ function EntityByMode({
 	})
 
 	// Render based on status
-	if (result.status === 'loading') {
+	if (result.$status === 'loading') {
 		return <>{loading ?? <DefaultLoading />}</>
 	}
 
-	if (result.status === 'error') {
+	if (result.$status === 'error') {
+		const error: FieldError = result.$error ?? { source: 'load', message: 'Unknown error', category: 'unknown', retryable: false }
 		if (errorFallback) {
-			return <>{errorFallback(result.error)}</>
+			return <>{errorFallback(error)}</>
 		}
-		return <DefaultError error={result.error} />
+		return <DefaultError error={error} />
 	}
 
-	if (result.status === 'not_found') {
+	if (result.$status === 'not_found') {
 		return <>{notFound ?? <DefaultNotFound entityType={entityType} by={by} />}</>
 	}
 
@@ -271,14 +272,19 @@ function EntityHandleRenderer({
 
 	const version = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
-	const handle = useMemo(
-		() => EntityHandle.create(entityId, entityType, store, dispatcher, schemaRegistry, undefined, selection),
+	const rawHandle = useMemo(
+		() => EntityHandle.createRaw(entityId, entityType, store, dispatcher, schemaRegistry, undefined, selection),
 		[entityId, entityType, store, dispatcher, schemaRegistry, selection, version],
 	)
 
-	useEffect(() => () => { handle.dispose() }, [handle])
+	const handle = useMemo(
+		() => EntityHandle.wrapProxy(rawHandle),
+		[rawHandle],
+	)
+
+	useEffect(() => () => { rawHandle.dispose() }, [rawHandle])
 
-	return <>{children(handle as unknown as EntityAccessor<unknown>)}</>
+	return <>{children(handle as EntityAccessor<unknown>)}</>
 }
 
 // ==================== Main Entity Component ====================

package/src/jsx/components/EntityList.tsx

@@ -86,15 +86,15 @@ function EntityListComponent<TRoleMap extends Record<string, object>>({
 	})
 
 	// Render based on status
-	if (result.status === 'loading') {
+	if (result.$status === 'loading') {
 		return <>{loading ?? <DefaultLoading />}</>
 	}
 
-	if (result.status === 'error') {
+	if (result.$status === 'error') {
 		if (errorFallback) {
-			return <>{errorFallback(result.error)}</>
+			return <>{errorFallback(result.$error)}</>
 		}
-		return <DefaultError error={result.error} />
+		return <DefaultError error={result.$error} />
 	}
 
 	// Empty state
@@ -103,7 +103,7 @@ function EntityListComponent<TRoleMap extends Record<string, object>>({
 	}
 
 	// Phase 3: Runtime render — items are already EntityAccessors from the hook
-	const items = result.items.map((item, index) => {
+	const items = result.items.map((item: (typeof result.items)[number], index: number) => {
 		return (
 			<React.Fragment key={item.id}>
 				{children(item as unknown as EntityAccessor<CommonEntity<TRoleMap>>, index)}

package/src/jsx/index.ts

@@ -2,6 +2,7 @@
 export {
 	BINDX_COMPONENT,
 	FIELD_REF_META,
+	SCOPE_REF,
 	type FieldRefMeta,
 	// Full types
 	type FieldRef,