@contember/bindx-react 0.1.23 → 0.1.25

package/src/hooks/useHasMany.ts

@@ -1,14 +1,10 @@
-import { useSyncExternalStore } from 'react'
-import { type HasManyRef, type HasManyAccessor, FIELD_REF_META } from '@contember/bindx'
-import { useSnapshotStore } from './BackendAdapterContext.js'
-import type { AnyBrand } from '@contember/bindx'
+import { type HasManyRef, type HasManyAccessor, type AnyBrand } from '@contember/bindx'
+import { useAccessor } from './useAccessor.js'
 
 /**
  * Subscribes to a has-many ref and returns a HasManyAccessor with live collection access.
  *
- * At runtime, HasManyRef proxies already have .items/.length/.map —
- * this hook adds a store subscription so the component re-renders on changes,
- * and widens the type to HasManyAccessor.
+ * Thin wrapper over useAccessor for ergonomics.
  */
 export function useHasMany<
 	TEntity,
@@ -17,14 +13,5 @@ export function useHasMany<
 	TEntityName extends string = string,
 	TSchema extends Record<string, object> = Record<string, object>,
 >(ref: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>): HasManyAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema> {
-	const store = useSnapshotStore()
-	const meta = ref[FIELD_REF_META]
-
-	useSyncExternalStore(
-		(callback) => store.subscribeToEntity(meta.entityType, meta.entityId, callback),
-		() => store.getVersion(),
-		() => store.getVersion(),
-	)
-
-	return ref as unknown as HasManyAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	return useAccessor(ref)
 }

package/src/hooks/useHasOne.ts

@@ -1,14 +1,10 @@
-import { useSyncExternalStore } from 'react'
-import { type HasOneRef, type HasOneAccessor, FIELD_REF_META } from '@contember/bindx'
-import { useSnapshotStore } from './BackendAdapterContext.js'
-import type { AnyBrand } from '@contember/bindx'
+import { type HasOneRef, type HasOneAccessor, type AnyBrand } from '@contember/bindx'
+import { useAccessor } from './useAccessor.js'
 
 /**
  * Subscribes to a has-one ref and returns a HasOneAccessor with live state access.
  *
- * At runtime, HasOneRef proxies already have .$state/.$data/.$entity/.$fields —
- * this hook adds a store subscription so the component re-renders on changes,
- * and widens the type to HasOneAccessor.
+ * Thin wrapper over useAccessor for ergonomics.
  */
 export function useHasOne<
 	TEntity,
@@ -17,14 +13,5 @@ export function useHasOne<
 	TEntityName extends string = string,
 	TSchema extends Record<string, object> = Record<string, object>,
 >(ref: HasOneRef<TEntity, TSelected, TBrand, TEntityName, TSchema>): HasOneAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema> {
-	const store = useSnapshotStore()
-	const meta = ref[FIELD_REF_META]
-
-	useSyncExternalStore(
-		(callback) => store.subscribeToEntity(meta.entityType, meta.entityId, callback),
-		() => store.getVersion(),
-		() => store.getVersion(),
-	)
-
-	return ref as unknown as HasOneAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	return useAccessor(ref)
 }

package/src/index.ts

@@ -297,6 +297,7 @@ export {
 	useInterceptEntity,
 	useInterceptField,
 	// Ref → Accessor hooks
+	useAccessor,
 	useField,
 	useHasMany,
 	useHasOne,
@@ -314,6 +315,8 @@ export type { UndoHookResult } from './hooks/useUndo.js'
 
 // JSX Components
 export {
+	Attribute,
+	type AttributeProps,
 	Field,
 	HasMany,
 	HasOne,

package/src/jsx/analyzer.ts

@@ -1,10 +1,7 @@
 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.
@@ -47,24 +44,7 @@ export function analyzeJsx(node: ReactNode, selection: SelectionMetaCollector):
 	// 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)
+	// Check if it's a component with getSelection (createComponent, Field, HasOne, HasMany, If, Show, etc.)
 	if (
 		component !== null &&
 		(typeof component === 'object' || typeof component === 'function') &&
@@ -166,69 +146,6 @@ export function convertToQuerySelection(jsxSelection: SelectionMeta): Record<str
 	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
  */

package/src/jsx/componentBuilder.types.ts

@@ -222,20 +222,32 @@ export type SetScalarProps<
 // ============================================================================
 
 /**
- * Build EntityAccessor props from entity config.
- *
- * For explicit selection (selector provided): Returns EntityAccessor with full access
- * - Allows direct field access: `entity.fieldName.value`
- * - Allows relation access: `entity.relation.length`, `entity.relation.$entity`
- *
- * For implicit selection (no selector): Returns EntityRef with restricted access
- * - Blocks direct field access to enforce declarative patterns
- * - Users must use components: `<Field field={entity.fieldName} />`
- * - Users must use condition DSL: `<If condition={cond.hasItems(entity.relation)} />`
+ * Build public entity props — always EntityRef (stable pointer, no live data).
+ * Used for the component's external React props.
  */
 export type BuildEntityProps<
 	TEntityProps extends Record<string, AnyEntityPropConfig>,
 	TRoles extends readonly string[],
+> = {
+	readonly [K in keyof TEntityProps]: TEntityProps[K] extends EntityPropConfig<
+		infer TEntity,
+		infer TSelected,
+		infer _TIsImplicit
+	>
+		? EntityRef<TEntity, TSelected, AnyBrand, string>
+		: TEntityProps[K] extends InterfaceEntityPropConfig<infer TInterface, infer _TIsImplicit>
+			? EntityRef<TInterface, TInterface, AnyBrand, string>
+			: never
+}
+
+/**
+ * Build render entity props — explicit selection → EntityAccessor (live data),
+ * implicit selection → EntityRef (pointer only, use <Field> components).
+ * Used for the render function's props type.
+ */
+export type BuildRenderEntityProps<
+	TEntityProps extends Record<string, AnyEntityPropConfig>,
+	TRoles extends readonly string[],
 > = {
 	readonly [K in keyof TEntityProps]: TEntityProps[K] extends EntityPropConfig<
 		infer TEntity,
@@ -243,26 +255,29 @@ export type BuildEntityProps<
 		infer TIsImplicit
 	>
 		? TIsImplicit extends true
-			// Implicit selection -> restricted EntityRef (no .value, .length access)
 			? EntityRef<TEntity, TSelected, AnyBrand, string>
-			// Explicit selection -> full EntityAccessor (full access)
 			: EntityAccessor<TEntity, TSelected, AnyBrand, string>
 		: TEntityProps[K] extends InterfaceEntityPropConfig<infer TInterface, infer TIsImplicit>
 			? TIsImplicit extends true
-				// Implicit interface -> restricted
 				? EntityRef<TInterface, TInterface, AnyBrand, string>
-				// Explicit interface -> full access
 				: EntityAccessor<TInterface, TInterface, AnyBrand, string>
 			: never
 }
 
 /**
- * Build complete props type from builder state.
+ * Build complete public props type from builder state.
  */
 export type BuildProps<TState extends ComponentBuilderState> =
 	TState['__scalarProps'] &
 		BuildEntityProps<TState['__entityProps'], TState['__roles']>
 
+/**
+ * Build complete render props type from builder state.
+ */
+export type BuildRenderProps<TState extends ComponentBuilderState> =
+	TState['__scalarProps'] &
+		BuildRenderEntityProps<TState['__entityProps'], TState['__roles']>
+
 /**
  * Build fragment properties ($propName) from entity config.
  */
@@ -437,7 +452,7 @@ export interface ComponentBuilder<
 	 * @param renderFn - React render function receiving typed props
 	 * @returns Bindx component with fragment properties
 	 */
-	render(renderFn: (props: BuildProps<TState>) => ReactNode): BindxComponent<TState>
+	render(renderFn: (props: BuildRenderProps<TState>) => ReactNode): BindxComponent<TState>
 }
 
 // ============================================================================

package/src/jsx/componentFactory.ts

@@ -15,6 +15,7 @@ import type {
 	SelectionMeta,
 	SelectionBuilder,
 	AnyBrand,
+	EntityRef,
 	SchemaDefinition,
 } from '@contember/bindx'
 import {
@@ -28,10 +29,11 @@ import type {
 	SelectionPropMeta,
 } from './componentBuilder.types.js'
 import type { SelectionProvider, SelectionFieldMeta } from './types.js'
-import { FIELD_REF_META, BINDX_COMPONENT } from './types.js'
+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'
 
 // ============================================================================
 // Symbols
@@ -63,6 +65,24 @@ export interface EntityConfig {
 	readonly schema?: SchemaDefinition<Record<string, object>>
 }
 
+// ============================================================================
+// Render Props Transformation
+// ============================================================================
+
+/**
+ * Converts explicit entity ref props to accessors via useAccessor.
+ * Called with a fixed list of prop names — hook count is stable across renders.
+ */
+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
+}
+
 // ============================================================================
 // Component Building
 // ============================================================================
@@ -100,6 +120,11 @@ 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)
+
 	// 2. Implicit entities - collect lazily to avoid TDZ errors
 	const implicitConfigs = [...entityConfigs.entries()].filter(([_, c]) => !c.selector)
 	let implicitCollected = false
@@ -118,14 +143,20 @@ export function buildComponent<TProps extends object>(
 	// 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
+
 		// Evaluate condition at runtime
 		if (conditionFn) {
-			const condition = conditionFn(props)
+			const condition = conditionFn(renderProps)
 			if (!evaluateCondition(condition)) {
 				return null
 			}
 		}
-		return renderFn(props)
+		return renderFn(renderProps)
 	}
 
 	const MemoizedComponent = memo(ComponentImpl)
@@ -372,8 +403,19 @@ function createGetSelection(
 		for (const [propName, meta] of selectionsMap) {
 			const propValue = props[propName]
 
+			if (!propValue || typeof propValue !== 'object') {
+				continue
+			}
+
+			// Case 0: Collection phase — prop has SCOPE_REF, merge directly into scope
+			if (SCOPE_REF in propValue) {
+				const targetScope = (propValue as { [SCOPE_REF]: SelectionScope })[SCOPE_REF]
+				targetScope.mergeFromSelectionMeta(meta.selection)
+				continue
+			}
+
 			// Case 1: Prop is a field reference (from relation)
-			if (propValue && typeof propValue === 'object' && FIELD_REF_META in propValue) {
+			if (FIELD_REF_META in propValue) {
 				const refMeta = (propValue as { [FIELD_REF_META]: { path: string[]; fieldName: string } })[FIELD_REF_META]
 
 				for (const [_key, field] of meta.selection.fields) {
@@ -386,7 +428,7 @@ function createGetSelection(
 				}
 			}
 			// Case 2: Prop is an EntityRef from root level
-			else if (propValue && typeof propValue === 'object' && 'id' in propValue && 'fields' in propValue) {
+			else if ('id' in propValue && 'fields' in propValue) {
 				for (const [_key, field] of meta.selection.fields) {
 					if (field.path.length === 1) {
 						fields.push({ ...field })

package/src/jsx/components/Attribute.tsx

@@ -0,0 +1,90 @@
+import { cloneElement, isValidElement, memo, type ReactElement, type ReactNode } from 'react'
+import type { FieldAccessor, FieldRef, SelectionFieldMeta, SelectionMeta, AnyBrand } from '../types.js'
+import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
+import type { SelectionProvider } from '../types.js'
+import { useField } from '../../hooks/useField.js'
+import { isDevAnnotationsEnabled } from '../devAnnotations.js'
+
+/**
+ * Props for Attribute component.
+ */
+export interface AttributeProps<T> {
+	/** The field to subscribe to */
+	field: FieldRef<T>
+	/** Maps the field accessor to props that get spread onto the child element */
+	format: (accessor: FieldAccessor<T>) => Record<string, unknown>
+	/** Single child element — receives the formatted props via cloneElement */
+	children: ReactElement
+}
+
+/**
+ * Attribute component — applies field-derived props to a child element.
+ *
+ * Like `<Field>` but for attributes (style, className, data-*) instead of text content.
+ * Subscribes to the field, calls `format` to produce props, and clones the child with merged props.
+ * During selection collection, both the field and children's fields are tracked.
+ *
+ * @example
+ * ```tsx
+ * <Attribute field={tag.color} format={color => ({ style: { backgroundColor: color.value ?? '#666' } })}>
+ *   <span>
+ *     <Field field={tag.name} />
+ *   </span>
+ * </Attribute>
+ * ```
+ */
+function AttributeImpl<T>({ field, format, children }: AttributeProps<T>): ReactElement | null {
+	if (field === undefined || field === null) {
+		return children
+	}
+
+	const accessor = useField(field)
+	const extraProps = {
+		...format(accessor),
+		...(isDevAnnotationsEnabled() ? { 'data-field': field[FIELD_REF_META]?.fieldName } : {}),
+	}
+
+	if (!isValidElement(children)) {
+		return children
+	}
+
+	return cloneElement(children, extraProps)
+}
+
+export const Attribute = memo(AttributeImpl) as typeof AttributeImpl
+
+// Static method for selection extraction
+const attributeWithSelection = Attribute as typeof Attribute & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+attributeWithSelection.getSelection = (
+	props: AttributeProps<unknown>,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta | null => {
+	if (props.field === undefined || props.field === null) {
+		return null
+	}
+
+	const meta = props.field[FIELD_REF_META]
+	if (!meta) {
+		return null
+	}
+
+	// During collection phase, skip — field access is already tracked by the collector proxy
+	if (meta.entityId === '') {
+		// But still analyze children for nested field selections
+		collectNested(props.children)
+		return null
+	}
+
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: false,
+		isRelation: false,
+	}
+}
+
+attributeWithSelection[BINDX_COMPONENT] = true
+
+export { attributeWithSelection as AttributeWithMeta }

package/src/jsx/components/Entity.tsx

@@ -1,8 +1,9 @@
 import React, { memo, useCallback, useEffect, useMemo, useRef, useSyncExternalStore, type ReactElement } from 'react'
 import { useBindxContext, useSchemaRegistry } from '../../hooks/BackendAdapterContext.js'
+import { annotateElement } from '../devAnnotations.js'
 import { useEntity } from '../../hooks/useEntity.js'
 import { useSelectionCollection } from '../../hooks/useSelectionCollection.js'
-import type { EntityAccessor, SelectionMeta } from '../types.js'
+import type { EntityAccessor, EntityRef, SelectionMeta } from '../types.js'
 import { type EntityDef, type EntityUniqueWhere, type AnyBrand, type FieldError, EntityHandle, type SnapshotStore, type ActionDispatcher, type SchemaRegistry, type CommonEntity } from '@contember/bindx'
 
 // ==================== Props Types ====================
@@ -15,7 +16,7 @@ interface EntityBaseProps<TRoleMap extends Record<string, object>> {
 	/** Entity definition reference */
 	entity: EntityDef<TRoleMap>
 	/** Render function receiving typed entity accessor with direct field access */
-	children: (entity: EntityAccessor<CommonEntity<TRoleMap>>) => React.ReactNode
+	children: (entity: EntityRef<CommonEntity<TRoleMap>>) => React.ReactNode
 	/** Error fallback */
 	error?: (error: FieldError) => React.ReactNode
 }
@@ -284,7 +285,8 @@ function EntityHandleRenderer({
 
 	useEffect(() => () => { rawHandle.dispose() }, [rawHandle])
 
-	return <>{children(handle as EntityAccessor<unknown>)}</>
+	const result = children(handle as EntityAccessor<unknown>)
+	return <>{annotateElement(result, { 'data-entity': entityType, 'data-entity-id': entityId })}</>
 }
 
 // ==================== Main Entity Component ====================

package/src/jsx/components/EntityList.tsx

@@ -3,6 +3,7 @@ import { type EntityDef, type EntityWhere, type EntityOrderBy, type FieldError,
 import { useEntityList } from '../../hooks/useEntityList.js'
 import { useSelectionCollection } from '../../hooks/useSelectionCollection.js'
 import type { EntityAccessor } from '../types.js'
+import { annotateElement } from '../devAnnotations.js'
 
 /**
  * Props for EntityList component
@@ -104,9 +105,10 @@ function EntityListComponent<TRoleMap extends Record<string, object>>({
 
 	// Phase 3: Runtime render — items are already EntityAccessors from the hook
 	const items = result.items.map((item: (typeof result.items)[number], index: number) => {
+		const result = children(item as unknown as EntityAccessor<CommonEntity<TRoleMap>>, index)
 		return (
 			<React.Fragment key={item.id}>
-				{children(item as unknown as EntityAccessor<CommonEntity<TRoleMap>>, index)}
+				{annotateElement(result, { 'data-entity': entityType, 'data-entity-id': item.id })}
 			</React.Fragment>
 		)
 	})

package/src/jsx/components/Field.tsx

@@ -2,6 +2,7 @@ import { memo, type ReactElement } from 'react'
 import type { FieldProps, SelectionFieldMeta, SelectionProvider } from '../types.js'
 import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
 import { useField } from '../../hooks/useField.js'
+import { annotateElement, isDevAnnotationsEnabled } from '../devAnnotations.js'
 
 /**
  * Field component - renders a scalar field value
@@ -28,13 +29,18 @@ function FieldImpl<T>({ field, children, format }: FieldProps<T>): ReactElement
 
 	// useField() subscribes to store and returns FieldAccessor with .value access
 	const accessor = useField(field)
+	const fieldName = field[FIELD_REF_META]?.fieldName
 
 	if (children) {
-		return <>{children(accessor)}</>
+		const result = children(accessor)
+		return <>{annotateElement(result, { 'data-field': fieldName })}</>
 	}
 
 	if (format) {
-		return <>{format(accessor.value)}</>
+		const content = format(accessor.value)
+		return isDevAnnotationsEnabled() && fieldName
+			? <span data-field={fieldName}>{content}</span>
+			: <>{content}</>
 	}
 
 	// Default: render value as string
@@ -42,7 +48,9 @@ function FieldImpl<T>({ field, children, format }: FieldProps<T>): ReactElement
 		return null
 	}
 
-	return <>{String(accessor.value)}</>
+	return isDevAnnotationsEnabled() && fieldName
+		? <span data-field={fieldName}>{String(accessor.value)}</span>
+		: <>{String(accessor.value)}</>
 }
 
 export const Field = memo(FieldImpl) as typeof FieldImpl

package/src/jsx/components/HasMany.tsx

@@ -4,6 +4,7 @@ import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from '../types.js'
 import { mergeSelections } from '../SelectionMeta.js'
 import { SelectionScope, generateHasManyAlias, type HasManyAccessor } from '@contember/bindx'
 import { useHasMany } from '../../hooks/useHasMany.js'
+import { annotateElement } from '../devAnnotations.js'
 
 /**
  * HasMany component - renders a has-many relation
@@ -38,8 +39,16 @@ function HasManyImpl<
 >({ field, children }: HasManyProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement {
 	// useHasMany() subscribes to store and returns HasManyAccessor with .map()/.items/.length
 	const accessor = useHasMany(field)
+	const targetType = field[FIELD_REF_META]?.targetType
+
 	const items = accessor.map((item, index) => {
-		return <React.Fragment key={item.id}>{children(item, index)}</React.Fragment>
+		const result = children(item, index)
+		return <React.Fragment key={item.id}>{
+			annotateElement(result, {
+				'data-entity': targetType ?? '',
+				'data-entity-id': item.id,
+			})
+		}</React.Fragment>
 	})
 
 	return <>{items}</>

package/src/jsx/components/HasOne.tsx

@@ -4,6 +4,7 @@ import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from '../types.js'
 import { mergeSelections } from '../SelectionMeta.js'
 import { SelectionScope, type HasOneAccessor } from '@contember/bindx'
 import { useHasOne } from '../../hooks/useHasOne.js'
+import { annotateElement } from '../devAnnotations.js'
 
 /**
  * HasOne component - renders a has-one relation
@@ -29,8 +30,11 @@ function HasOneImpl<
 >({ field, children }: HasOneProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement {
 	// useHasOne() subscribes to store and returns HasOneAccessor with .$entity
 	const accessor = useHasOne(field)
+	const relationName = field[FIELD_REF_META]?.fieldName
+
 	// Get the related entity reference (always available, may be placeholder with id=null)
-	return <>{children(accessor.$entity)}</>
+	const result = children(accessor.$entity)
+	return <>{annotateElement(result, { 'data-relation': relationName ?? '' })}</>
 }
 
 export const HasOne = memo(HasOneImpl) as typeof HasOneImpl

package/src/jsx/components/index.ts

@@ -1,3 +1,6 @@
+// Attribute component
+export { Attribute, AttributeWithMeta, type AttributeProps } from './Attribute.js'
+
 // Field component
 export { Field, FieldWithMeta } from './Field.js'
 

package/src/jsx/devAnnotations.ts

@@ -0,0 +1,33 @@
+import { cloneElement, isValidElement, type ReactNode } from 'react'
+
+/**
+ * Whether dev-mode data attributes are enabled.
+ *
+ * Controlled via `BINDX_DEV_ANNOTATIONS` env variable.
+ * Bundlers (Vite, webpack) replace `import.meta.env` at build time,
+ * so this entire module tree-shakes away in production builds.
+ */
+// @ts-ignore -- import.meta.env is provided by bundler
+const DEV_ANNOTATIONS: boolean = typeof import.meta !== 'undefined' && import.meta.env?.VITE_BINDX_DEV_ANNOTATIONS === 'true'
+
+/**
+ * In dev mode, injects data attributes onto an existing React element via cloneElement.
+ * If annotations are disabled or the node is not a valid element, returns as-is.
+ */
+export function annotateElement(
+	element: ReactNode,
+	attrs: Record<string, string>,
+): ReactNode {
+	if (!DEV_ANNOTATIONS || !isValidElement(element)) {
+		return element
+	}
+	return cloneElement(element, attrs)
+}
+
+/**
+ * Returns true if dev annotations are enabled.
+ * Use for conditional wrapping (e.g., Field text render in span).
+ */
+export function isDevAnnotationsEnabled(): boolean {
+	return DEV_ANNOTATIONS
+}

package/src/jsx/index.ts

@@ -52,6 +52,7 @@ export {
 } from './analyzer.js'
 
 // Components
+export { Attribute, AttributeWithMeta, type AttributeProps } from './components/Attribute.js'
 export { Field, FieldWithMeta } from './components/Field.js'
 export { HasMany, HasManyWithMeta } from './components/HasMany.js'
 export { HasOne, HasOneWithMeta } from './components/HasOne.js'