@contember/bindx-react 0.1.24 → 0.1.26

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'

package/src/jsx/types.ts

@@ -97,7 +97,7 @@ export interface HasManyProps<
 	TSchema extends Record<string, object> = Record<string, object>,
 > {
 	field: HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
-	children: (item: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>, index: number) => ReactNode
+	children: (item: EntityRef<TEntity, TSelected, TBrand, TEntityName, TSchema>, index: number) => ReactNode
 	filter?: unknown
 	orderBy?: unknown
 	limit?: number
@@ -123,7 +123,7 @@ export interface HasOneProps<
 	TSchema extends Record<string, object> = Record<string, object>,
 > {
 	field: HasOneRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
-	children: (entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>) => ReactNode
+	children: (entity: EntityRef<TEntity, TSelected, TBrand, TEntityName, TSchema>) => ReactNode
 }
 
 /**
@@ -134,7 +134,7 @@ export interface HasOneProps<
 export interface EntityComponentProps<TSchema extends Record<string, object>, K extends keyof TSchema & string> {
 	name: K
 	id: string
-	children: (entity: EntityAccessor<TSchema[K], TSchema[K], import('@contember/bindx').AnyBrand, K, TSchema>) => ReactNode
+	children: (entity: EntityRef<TSchema[K], TSchema[K], import('@contember/bindx').AnyBrand, K, TSchema>) => ReactNode
 }
 
 /**