@contember/bindx-react 0.1.0

package/src/jsx/components/HasMany.tsx

@@ -0,0 +1,109 @@
+import React, { memo, type ReactElement, type ReactNode } from 'react'
+import type { HasManyProps, SelectionFieldMeta, SelectionMeta, SelectionProvider, EntityRef, AnyBrand, HasManyRef } from '../types.js'
+import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from '../types.js'
+import { mergeSelections } from '../SelectionMeta.js'
+import { SelectionScope, generateHasManyAlias } from '@contember/bindx'
+
+/**
+ * HasMany component - renders a has-many relation
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <HasMany field={author.fields.articles}>
+ *   {article => (
+ *     <div>
+ *       <Field field={article.fields.title} />
+ *     </div>
+ *   )}
+ * </HasMany>
+ *
+ * // With query parameters
+ * <HasMany field={author.fields.articles} limit={5} orderBy={{ publishedAt: 'desc' }}>
+ *   {(article, index) => (
+ *     <div key={article.id}>
+ *       {index + 1}. <Field field={article.fields.title} />
+ *     </div>
+ *   )}
+ * </HasMany>
+ * ```
+ */
+function HasManyImpl<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+>({ field, children }: HasManyProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement {
+	// At runtime, field is always a full HasManyRef (proxy provides all properties)
+	// Props accept HasManyRefBase for type compatibility with both implicit and explicit modes
+	const fullField = field as HasManyRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	const items = fullField.map((item, index) => {
+		return <React.Fragment key={item.id}>{children(item, index)}</React.Fragment>
+	})
+
+	return <>{items}</>
+}
+
+export const HasMany = memo(HasManyImpl) as typeof HasManyImpl
+
+// Static method for selection extraction
+const hasManyWithSelection = HasMany as typeof HasMany & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+hasManyWithSelection.getSelection = (
+	props: HasManyProps<unknown>,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta => {
+	const meta = props.field[FIELD_REF_META]
+	// At runtime, field is always a full HasManyRef (proxy provides all properties)
+	const fullField = props.field as HasManyRef<unknown>
+
+	// Use field's map function to get a properly configured collector with schema info
+	// The map() creates a collector that knows about entity types and relations
+	const result: { syntheticChildren: ReactNode; childScope: SelectionScope | null } = {
+		syntheticChildren: null,
+		childScope: null,
+	}
+
+	fullField.map((item, index) => {
+		// Get the scope from the collector entity (it has SCOPE_REF)
+		const scopeRef = (item as unknown as Record<symbol, unknown>)[SCOPE_REF]
+		if (scopeRef instanceof SelectionScope) {
+			result.childScope = scopeRef
+		}
+		result.syntheticChildren = props.children(item, index)
+		return null
+	})
+
+	// Also analyze the JSX structure
+	const jsxSelection = result.syntheticChildren ? collectNested(result.syntheticChildren) : { fields: new Map() }
+
+	// Convert scope to SelectionMeta and merge with JSX selection
+	const nestedSelection = result.childScope ? result.childScope.toSelectionMeta() : { fields: new Map() }
+	mergeSelections(nestedSelection, jsxSelection)
+
+	// Build hasManyParams object
+	const hasManyParams = {
+		filter: props.filter,
+		orderBy: props.orderBy,
+		limit: props.limit,
+		offset: props.offset,
+	}
+
+	// Generate alias based on params if any are provided
+	const alias = generateHasManyAlias(meta.fieldName, hasManyParams)
+
+	return {
+		fieldName: meta.fieldName,
+		alias,
+		path: meta.path,
+		isArray: true,
+		isRelation: true,
+		nested: nestedSelection,
+		hasManyParams,
+	}
+}
+
+hasManyWithSelection[BINDX_COMPONENT] = true
+
+export { hasManyWithSelection as HasManyWithMeta }

package/src/jsx/components/HasOne.tsx

@@ -0,0 +1,78 @@
+import React, { memo, type ReactElement, type ReactNode } from 'react'
+import type { HasOneProps, SelectionFieldMeta, SelectionMeta, SelectionProvider, AnyBrand, HasOneRef } from '../types.js'
+import { FIELD_REF_META, BINDX_COMPONENT, SCOPE_REF } from '../types.js'
+import { mergeSelections } from '../SelectionMeta.js'
+import { SelectionScope } from '@contember/bindx'
+
+/**
+ * HasOne component - renders a has-one relation
+ *
+ * @example
+ * ```tsx
+ * <HasOne field={article.fields.author}>
+ *   {author => (
+ *     <div>
+ *       <Field field={author.fields.name} />
+ *       <Field field={author.fields.email} />
+ *     </div>
+ *   )}
+ * </HasOne>
+ * ```
+ */
+function HasOneImpl<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+>({ field, children }: HasOneProps<TEntity, TSelected, TBrand, TEntityName, TSchema>): ReactElement {
+	// At runtime, field is always a full HasOneRef (proxy provides all properties)
+	// Props accept HasOneRefBase for type compatibility with both implicit and explicit modes
+	const fullField = field as HasOneRef<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	// Get the related entity reference (always available, may be placeholder with id=null)
+	return <>{children(fullField.$entity)}</>
+}
+
+export const HasOne = memo(HasOneImpl) as typeof HasOneImpl
+
+// Static method for selection extraction
+const hasOneWithSelection = HasOne as typeof HasOne & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+hasOneWithSelection.getSelection = (
+	props: HasOneProps<unknown>,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta => {
+	const meta = props.field[FIELD_REF_META]
+	// At runtime, field is always a full HasOneRef (proxy provides all properties)
+	const fullField = props.field as HasOneRef<unknown>
+
+	// Use field's $entity which has a properly configured scope with schema info
+	const nestedCollector = fullField.$entity
+
+	// Get the scope from the collector entity (it has SCOPE_REF)
+	const scopeRef = (nestedCollector as unknown as Record<symbol, unknown>)[SCOPE_REF]
+	const childScope = scopeRef instanceof SelectionScope ? scopeRef : null
+
+	// Call children once to gather nested field access
+	const syntheticChildren = props.children(nestedCollector)
+
+	// Also analyze the JSX structure
+	const jsxSelection = collectNested(syntheticChildren)
+
+	// Convert scope to SelectionMeta and merge with JSX selection
+	const nestedSelection = childScope ? childScope.toSelectionMeta() : { fields: new Map() }
+	mergeSelections(nestedSelection, jsxSelection)
+
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: false,
+		isRelation: true,
+		nested: nestedSelection,
+	}
+}
+
+hasOneWithSelection[BINDX_COMPONENT] = true
+
+export { hasOneWithSelection as HasOneWithMeta }

package/src/jsx/components/HasRole.tsx

@@ -0,0 +1,95 @@
+/**
+ * HasRole component — runtime role gating with optional entity type narrowing.
+ *
+ * Mode 1 (context gate): Renders children only if user has at least one specified role.
+ * Mode 2 (entity re-typing): Narrows entity accessor type to the role-specific entity type.
+ */
+
+import React, { type ReactNode, type ReactElement } from 'react'
+import type {
+	EntityAccessor,
+	EntityForRoles,
+	RoleNames,
+	ExtractRoleMap,
+} from '@contember/bindx'
+import { useHasRole } from '../../roles/RoleContext.js'
+
+// ============================================================================
+// Props
+// ============================================================================
+
+/**
+ * Props for HasRole in context-gate mode (no entity).
+ */
+interface HasRoleGateProps<TRoles extends string> {
+	/** Roles to check — renders if user has at least one */
+	roles: readonly TRoles[]
+	/** Children to render if role check passes */
+	children: ReactNode
+	entity?: never
+}
+
+/**
+ * Props for HasRole in entity-narrowing mode.
+ * TRoleMap is inferred from the entity accessor's __roleMap phantom type.
+ */
+interface HasRoleEntityProps<
+	TRoleMap extends Record<string, object>,
+	TRoles extends RoleNames<TRoleMap>,
+> {
+	/** Roles to expand to */
+	roles: readonly TRoles[]
+	/** Entity accessor to narrow */
+	entity: EntityAccessor<any, any, any, any, any, TRoleMap>
+	/** Render function receiving the role-expanded entity */
+	children: (entity: EntityAccessor<EntityForRoles<TRoleMap, TRoles>>) => ReactNode
+}
+
+export type HasRoleProps<
+	TRoleMap extends Record<string, object> = Record<string, object>,
+	TRoles extends RoleNames<TRoleMap> = RoleNames<TRoleMap>,
+> = HasRoleGateProps<TRoles> | HasRoleEntityProps<TRoleMap, TRoles>
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * HasRole component — conditionally renders based on user roles.
+ *
+ * @example Context gate mode
+ * ```tsx
+ * <HasRole roles={['admin']}>
+ *   <AdminPanel />
+ * </HasRole>
+ * ```
+ *
+ * @example Entity narrowing mode
+ * ```tsx
+ * <HasRole roles={['admin']} entity={article}>
+ *   {adminArticle => <span>{adminArticle.internalNotes.value}</span>}
+ * </HasRole>
+ * ```
+ */
+export function HasRole<
+	TRoleMap extends Record<string, object>,
+	TRoles extends RoleNames<TRoleMap>,
+>(props: HasRoleProps<TRoleMap, TRoles>): ReactElement | null {
+	const hasRole = useHasRole()
+
+	// Check if user has at least one of the specified roles
+	const hasAccess = props.roles.some(role => hasRole(role))
+	if (!hasAccess) {
+		return null
+	}
+
+	// Entity narrowing mode
+	if ('entity' in props && props.entity !== undefined) {
+		const { entity, children } = props as HasRoleEntityProps<TRoleMap, TRoles>
+		// At runtime, the entity handle is the same object — we just widen the TS type
+		return <>{children(entity as unknown as EntityAccessor<EntityForRoles<TRoleMap, TRoles>>)}</>
+	}
+
+	// Context gate mode
+	return <>{props.children}</>
+}

package/src/jsx/components/If.tsx

@@ -0,0 +1,127 @@
+import React, { memo, type ReactElement, type ReactNode } from 'react'
+import type { IfProps, SelectionFieldMeta, SelectionMeta, SelectionProvider, FieldRef } from '../types.js'
+import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
+import { mergeSelections, createEmptySelection } from '../SelectionMeta.js'
+import {
+	type Condition,
+	isCondition,
+	evaluateCondition,
+	collectConditionFields,
+	CONDITION_META,
+} from '../conditions.js'
+
+/**
+ * If component - conditional rendering that ensures both branches are analyzed
+ *
+ * During collection phase, BOTH branches are analyzed to capture all required fields.
+ * During runtime, only the matching branch is rendered.
+ *
+ * Supports three types of conditions:
+ * 1. Boolean literals: `condition={true}` or `condition={someBoolean}`
+ * 2. FieldRef<boolean>: `condition={task.isActive}` - field value is used
+ * 3. Condition objects: `condition={cond.hasItems(task.developers)}` - composable DSL
+ *
+ * @example
+ * ```tsx
+ * // With boolean condition
+ * <If condition={showBio} then={
+ *   <Field field={author.bio} />
+ * } />
+ *
+ * // With field condition
+ * <If
+ *   condition={author.isPublished}
+ *   then={<Field field={author.publishedAt} />}
+ *   else={<span>Draft</span>}
+ * />
+ *
+ * // With condition DSL
+ * <If
+ *   condition={cond.hasItems(task.developers)}
+ *   then={<HasMany field={task.developers}>{dev => ...}</HasMany>}
+ * />
+ *
+ * // Complex conditions
+ * <If
+ *   condition={cond.and(
+ *     cond.hasItems(task.developers),
+ *     cond.eq(task.status, 'active')
+ *   )}
+ *   then={<span>Ready to work</span>}
+ * />
+ * ```
+ */
+function IfImpl({ condition, then: thenBranch, else: elseBranch }: IfProps): ReactElement | null {
+	let conditionValue: boolean
+
+	if (typeof condition === 'boolean') {
+		// Boolean literal
+		conditionValue = condition
+	} else if (isCondition(condition)) {
+		// Condition DSL object
+		conditionValue = evaluateCondition(condition)
+	} else {
+		// FieldRef<boolean>
+		conditionValue = (condition as FieldRef<boolean>).value ?? false
+	}
+
+	return conditionValue ? <>{thenBranch}</> : <>{elseBranch ?? null}</>
+}
+
+export const If = memo(IfImpl)
+
+// Static method for selection extraction - analyzes BOTH branches
+const ifWithSelection = If as typeof If & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+ifWithSelection.getSelection = (
+	props: IfProps,
+	collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta[] | null => {
+	const thenSelection = collectNested(props.then)
+	const elseSelection = props.else ? collectNested(props.else) : createEmptySelection()
+
+	// Merge both selections - we need fields from both branches
+	mergeSelections(thenSelection, elseSelection)
+
+	// Return all fields from merged selection
+	const result: SelectionFieldMeta[] = []
+	for (const field of thenSelection.fields.values()) {
+		result.push(field)
+	}
+
+	// Collect fields from condition
+	if (typeof props.condition !== 'boolean') {
+		if (isCondition(props.condition)) {
+			// Condition DSL object - collect all referenced fields
+			const conditionFields = collectConditionFields(props.condition)
+			for (const field of conditionFields) {
+				if (field && typeof field === 'object' && FIELD_REF_META in field) {
+					const meta = (field as { [FIELD_REF_META]: { fieldName: string; path: string[]; isArray?: boolean; isRelation?: boolean } })[FIELD_REF_META]
+					result.push({
+						fieldName: meta.fieldName,
+						alias: meta.fieldName,
+						path: meta.path,
+						isArray: meta.isArray ?? false,
+						isRelation: meta.isRelation ?? false,
+					})
+				}
+			}
+		} else {
+			// FieldRef<boolean> - add that field
+			const meta = (props.condition as { [FIELD_REF_META]: { fieldName: string; path: string[]; isArray?: boolean; isRelation?: boolean } })[FIELD_REF_META]
+			result.push({
+				fieldName: meta.fieldName,
+				alias: meta.fieldName,
+				path: meta.path,
+				isArray: false,
+				isRelation: false,
+			})
+		}
+	}
+
+	return result.length > 0 ? result : null
+}
+
+ifWithSelection[BINDX_COMPONENT] = true
+
+export { ifWithSelection as IfWithMeta }

package/src/jsx/components/Show.tsx

@@ -0,0 +1,56 @@
+import React, { memo, type ReactElement, type ReactNode } from 'react'
+import type { FieldRef, SelectionFieldMeta, SelectionMeta, SelectionProvider } from '../types.js'
+import { FIELD_REF_META, BINDX_COMPONENT } from '../types.js'
+
+/**
+ * Props for Show component
+ */
+export interface ShowProps<T> {
+	field: FieldRef<T>
+	children: (value: NonNullable<T>) => ReactNode
+	fallback?: ReactNode
+}
+
+/**
+ * Show component - renders content only if field has a value
+ * Useful for nullable fields.
+ *
+ * @example
+ * ```tsx
+ * <Show field={article.fields.publishedAt}>
+ *   {value => <time>{value.toISOString()}</time>}
+ * </Show>
+ *
+ * <Show field={author.fields.bio} fallback={<span>No bio</span>}>
+ *   {bio => <p>{bio}</p>}
+ * </Show>
+ * ```
+ */
+function ShowImpl<T>({ field, children, fallback }: ShowProps<T>): ReactElement | null {
+	if (field.value === null || field.value === undefined) {
+		return fallback ? <>{fallback}</> : null
+	}
+
+	return <>{children(field.value as NonNullable<T>)}</>
+}
+
+export const Show = memo(ShowImpl) as typeof ShowImpl
+
+// Static method for selection extraction
+const showWithSelection = Show as typeof Show & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+showWithSelection.getSelection = (props: ShowProps<unknown>): SelectionFieldMeta | null => {
+	const meta = props.field[FIELD_REF_META]
+
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: false,
+		isRelation: false,
+	}
+}
+
+showWithSelection[BINDX_COMPONENT] = true
+
+export { showWithSelection as ShowWithMeta }

package/src/jsx/components/index.ts

@@ -0,0 +1,20 @@
+// Field component
+export { Field, FieldWithMeta } from './Field.js'
+
+// HasMany component
+export { HasMany, HasManyWithMeta } from './HasMany.js'
+
+// HasOne component
+export { HasOne, HasOneWithMeta } from './HasOne.js'
+
+// If component
+export { If, IfWithMeta } from './If.js'
+
+// Show component
+export { Show, ShowWithMeta, type ShowProps } from './Show.js'
+
+// Entity component
+export { Entity, type EntityProps } from './Entity.js'
+
+// EntityList component
+export { EntityList, type EntityListProps } from './EntityList.js'