@contember/bindx-react 0.1.0

package/src/jsx/index.ts

@@ -0,0 +1,135 @@
+// Types
+export {
+	BINDX_COMPONENT,
+	FIELD_REF_META,
+	type FieldRefMeta,
+	// Full types
+	type FieldRef,
+	type HasManyRef,
+	type HasOneRef,
+	type HasOneAccessor,
+	type EntityRef,
+	type EntityAccessor,
+	// Base types
+	type FieldRefBase,
+	type HasManyRefBase,
+	type HasOneRefBase,
+	type HasOneAccessorBase,
+	type EntityRefBase,
+	type EntityAccessorBase,
+	// Field mapping types
+	type EntityFields,
+	type SelectedEntityFields,
+	type SelectedEntityFieldsBase,
+	// Component props
+	type FieldProps,
+	type HasManyProps,
+	type HasOneProps,
+	type IfProps,
+	type EntityComponentProps,
+	type SelectionMeta,
+	type SelectionFieldMeta,
+	type HasManyComponentOptions,
+	type SelectionProvider,
+	type AnyBrand,
+} from './types.js'
+
+// Selection metadata
+export {
+	SelectionMetaCollector,
+	mergeSelections,
+	createEmptySelection,
+} from './SelectionMeta.js'
+
+// Proxy creation
+export {
+	createCollectorProxy,
+} from './proxy.js'
+
+// JSX Analyzer
+export {
+	analyzeJsx,
+	collectSelection,
+	convertToQuerySelection,
+	debugSelection,
+} from './analyzer.js'
+
+// Components
+export { Field, FieldWithMeta } from './components/Field.js'
+export { HasMany, HasManyWithMeta } from './components/HasMany.js'
+export { HasOne, HasOneWithMeta } from './components/HasOne.js'
+export { If, IfWithMeta } from './components/If.js'
+export { Show, ShowWithMeta, type ShowProps } from './components/Show.js'
+export { Entity, type EntityProps } from './components/Entity.js'
+export { EntityList, type EntityListProps } from './components/EntityList.js'
+export { HasRole, type HasRoleProps } from './components/HasRole.js'
+
+// Condition DSL for <If> component
+export {
+	cond,
+	isCondition,
+	evaluateCondition,
+	collectConditionFields,
+	CONDITION_META,
+	type Condition,
+	type ConditionMeta,
+} from './conditions.js'
+
+// Component builder (unified API)
+export {
+	isBindxComponent,
+	mergeFragments,
+	COMPONENT_MARKER,
+	COMPONENT_BRAND,
+	COMPONENT_SELECTIONS,
+	createComponentBuilder,
+	ComponentBuilderImpl,
+	getComponentBrand,
+	setBrandValidation,
+	validateBrand,
+} from './createComponent.js'
+
+// Standalone createComponent function
+export { createComponent } from './standaloneCreateComponent.js'
+
+// withCollector — attach staticRender to a component for selection collection
+export { withCollector } from './withCollector.js'
+
+export type {
+	SelectionPropMeta,
+	BindxComponentBase,
+	BindxComponent,
+	ComponentBuilder,
+	ComponentBuilderState,
+	CreateComponentOptions,
+	// Interface types
+	InterfaceEntityPropConfig,
+	ImplicitInterfaceEntityConfig,
+	ExplicitInterfaceEntityConfig,
+	AddInterfaces,
+	InterfaceSelectorsMap,
+	AnyEntityPropConfig,
+	// Entity prop config types
+	EntityPropConfig,
+	ImplicitEntityConfig,
+	ExplicitEntityConfig,
+	// State helpers
+	AddImplicitEntity,
+	AddExplicitEntity,
+	AddImplicitInterfaceEntity,
+	AddExplicitInterfaceEntity,
+	SetScalarProps,
+	// Props building
+	BuildEntityProps,
+	BuildProps,
+	BuildFragmentProps,
+	InitialBuilderState,
+} from './createComponent.js'
+
+// Legacy type exports for backwards compatibility
+export type {
+	EntityPropKeys,
+	EntityFromProp,
+	SelectionFromProp,
+	ImplicitFragmentProperties,
+} from './legacyTypes.js'

package/src/jsx/legacyTypes.ts

@@ -0,0 +1,30 @@
+/**
+ * Legacy type exports for backwards compatibility.
+ * These types were previously exported from createComponent.ts
+ */
+
+import type { EntityRef, FluentFragment } from '@contember/bindx'
+
+/**
+ * Extract keys from props type where value is EntityRef<any, any>
+ */
+export type EntityPropKeys<P> = {
+	[K in keyof P]: P[K] extends EntityRef<infer _T, infer _S> ? K : never
+}[keyof P]
+
+/**
+ * Extract the full entity type from an EntityRef prop
+ */
+export type EntityFromProp<P, K extends keyof P> = P[K] extends EntityRef<infer T, infer _S> ? T : never
+
+/**
+ * Extract the selection type from an EntityRef prop
+ */
+export type SelectionFromProp<P, K extends keyof P> = P[K] extends EntityRef<infer _T, infer S> ? S : never
+
+/**
+ * Fragment properties for implicit mode - $propName for each entity prop
+ */
+export type ImplicitFragmentProperties<P> = {
+	[K in EntityPropKeys<P> as `$${K & string}`]: FluentFragment<EntityFromProp<P, K>, SelectionFromProp<P, K>>
+}

package/src/jsx/proxy.ts

@@ -0,0 +1 @@
+export { createCollectorProxy } from './collectorProxy.js'

package/src/jsx/proxyShared.ts

@@ -0,0 +1,42 @@
+import {
+	type EntityRef,
+	type EntityAccessor,
+	type EntityFields,
+} from './types.js'
+
+/**
+ * Known properties on entity accessor that should NOT be treated as field access.
+ * Properties are accessed with $ prefix for consistency with EntityHandle.
+ * Used by collector proxy.
+ */
+export const ENTITY_ACCESSOR_PROPERTIES = new Set([
+	'id',
+	'$fields', '$data', '$isDirty', '$persistedId', '$isNew',
+	'$errors', '$hasError', '$addError', '$clearErrors', '$clearAllErrors',
+	'$on', '$intercept', '$onPersisted', '$interceptPersisting',
+	'__entityType', '__entityName',
+])
+
+/**
+ * Wraps an EntityRef in a Proxy that supports direct field access.
+ * - `entity.fieldName` is equivalent to `entity.$fields.fieldName`
+ * - Known accessor properties pass through to the target
+ */
+export function wrapEntityRefWithFieldAccessProxy<T>(ref: EntityRef<T>): EntityAccessor<T> {
+	return new Proxy(ref, {
+		get(target, prop) {
+			// Symbols - pass through
+			if (typeof prop !== 'string') {
+				return Reflect.get(target, prop)
+			}
+
+			// Known accessor properties - pass through
+			if (ENTITY_ACCESSOR_PROPERTIES.has(prop)) {
+				return Reflect.get(target, prop)
+			}
+
+			// Otherwise, treat as field access
+			return target.$fields[prop as keyof EntityFields<T>]
+		},
+	}) as EntityAccessor<T>
+}

package/src/jsx/standaloneCreateComponent.ts

@@ -0,0 +1,47 @@
+/**
+ * Standalone createComponent function.
+ *
+ * Unlike the old createBindx()-returned createComponent, this function
+ * does not need a schema-bound closure. The SchemaRegistry is passed as null
+ * and components resolve it from context at render time if needed.
+ */
+
+import type {
+	ComponentBuilder,
+	ComponentBuilderState,
+	CreateComponentOptions,
+} from './componentBuilder.types.js'
+import { createComponentBuilder } from './componentBuilder.js'
+
+/**
+ * Creates a component builder for defining bindx components.
+ *
+ * @example
+ * ```typescript
+ * import { createComponent } from '@contember/bindx-react'
+ * import { schema } from './generated'
+ *
+ * const ArticleCard = createComponent()
+ *   .entity('article', schema.Article, e => e.title().author(a => a.name()))
+ *   .props<{ className?: string }>()
+ *   .render(({ article, className }) => (
+ *     <div className={className}>
+ *       <h2>{article.$data?.title}</h2>
+ *       <span>{article.$data?.author?.name}</span>
+ *     </div>
+ *   ))
+ * ```
+ */
+// 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 ?? []
+	return createComponentBuilder(
+		null,
+		roles,
+	)
+}

package/src/jsx/types.ts

@@ -0,0 +1,192 @@
+import type { ReactNode } from 'react'
+import type {
+	SelectionMeta,
+	SelectionFieldMeta,
+	EntityFields,
+	FieldRefMeta,
+	ScalarKeys,
+	HasManyKeys,
+	HasOneKeys,
+	SelectedEntityFields,
+	SelectedEntityFieldsBase,
+	// Full types
+	FieldRef,
+	HasManyRef,
+	HasOneRef,
+	HasOneAccessor,
+	EntityRef,
+	EntityAccessor,
+	// Base types (for component props - accept both)
+	FieldRefBase,
+	HasManyRefBase,
+	HasOneRefBase,
+	HasOneAccessorBase,
+	EntityRefBase,
+	EntityAccessorBase,
+	AnyBrand,
+} from '@contember/bindx'
+import { Condition } from './conditions.js'
+
+// Re-export unified types for backwards compatibility
+export type { SelectionMeta, SelectionFieldMeta }
+
+// Re-export from @contember/bindx
+export { FIELD_REF_META } from '@contember/bindx'
+export type {
+	EntityFields,
+	FieldRefMeta,
+	ScalarKeys,
+	HasManyKeys,
+	HasOneKeys,
+	SelectedEntityFields,
+	SelectedEntityFieldsBase,
+	// Full types
+	FieldRef,
+	HasManyRef,
+	HasOneRef,
+	HasOneAccessor,
+	EntityRef,
+	EntityAccessor,
+	// Base types
+	FieldRefBase,
+	HasManyRefBase,
+	HasOneRefBase,
+	HasOneAccessorBase,
+	EntityRefBase,
+	EntityAccessorBase,
+	AnyBrand,
+}
+
+/**
+ * Marker symbol for identifying bindx components
+ */
+export const BINDX_COMPONENT = Symbol('BINDX_COMPONENT')
+
+/**
+ * Symbol for direct scope access on collector proxies.
+ * Replaces NESTED_SELECTION_REF - carries the SelectionScope directly.
+ * Used when passing relation entities to nested createComponent components.
+ */
+export const SCOPE_REF = Symbol('SCOPE_REF')
+
+
+/**
+ * Props for Field component.
+ * Accepts FieldRefBase, so both FieldRef (explicit) and FieldRefBase (implicit) work.
+ */
+export interface FieldProps<T> {
+	field: FieldRefBase<T>
+	children?: (accessor: FieldRef<T>) => ReactNode
+	format?: (value: T | null) => ReactNode
+}
+
+/**
+ * Options for HasMany relation
+ */
+export interface HasManyComponentOptions {
+	filter?: unknown
+	orderBy?: unknown
+	limit?: number
+	offset?: number
+}
+
+/**
+ * Props for HasMany component.
+ * Selection-aware: children callback receives EntityAccessor with direct field access.
+ * Accepts HasManyRefBase, so both HasManyRef (explicit) and HasManyRefBase (implicit) work.
+ *
+ * @typeParam TEntity - The full entity type
+ * @typeParam TSelected - The selected subset of fields (defaults to TEntity for backwards compatibility)
+ * @typeParam TBrand - Component brand type for validation (defaults to AnyBrand)
+ * @typeParam TEntityName - Entity name as string literal for type narrowing
+ * @typeParam TSchema - Schema for entity name lookup in nested relations
+ */
+export interface HasManyProps<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> {
+	field: HasManyRefBase<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	children: (item: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>, index: number) => ReactNode
+	filter?: unknown
+	orderBy?: unknown
+	limit?: number
+	offset?: number
+}
+
+/**
+ * Props for HasOne component.
+ * Selection-aware: children callback receives EntityAccessor with direct field access.
+ * Accepts HasOneRefBase, so both HasOneRef (explicit) and HasOneRefBase (implicit) work.
+ *
+ * @typeParam TEntity - The full entity type
+ * @typeParam TSelected - The selected subset of fields (defaults to TEntity for backwards compatibility)
+ * @typeParam TBrand - Component brand type for validation (defaults to AnyBrand)
+ * @typeParam TEntityName - Entity name as string literal for type narrowing
+ * @typeParam TSchema - Schema for entity name lookup in nested relations
+ */
+export interface HasOneProps<
+	TEntity,
+	TSelected = TEntity,
+	TBrand extends AnyBrand = AnyBrand,
+	TEntityName extends string = string,
+	TSchema extends Record<string, object> = Record<string, object>,
+> {
+	field: HasOneRefBase<TEntity, TSelected, TBrand, TEntityName, TSchema>
+	children: (entity: EntityAccessor<TEntity, TSelected, TBrand, TEntityName, TSchema>) => ReactNode
+}
+
+/**
+ * Props for Entity component.
+ * Entity name is preserved for proper HasRole type narrowing.
+ * Children receive EntityAccessor with direct field access.
+ */
+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
+}
+
+/**
+ * Props for If conditional component.
+ *
+ * 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
+ *
+ * Using the Condition DSL is recommended for implicit selection mode as it ensures
+ * all referenced fields are collected for the GraphQL query.
+ */
+export interface IfProps {
+	/**
+	 * Condition to evaluate. Can be:
+	 * - A boolean literal
+	 * - A FieldRef<boolean>
+	 * - A Condition object from the condition builders (hasItems, isEmpty, eq, and, or, not, etc.)
+	 */
+	condition: boolean | FieldRef<boolean> | Condition
+	then: ReactNode
+	else?: ReactNode
+}
+
+/**
+ * Interface for components that can provide selection info
+ */
+export interface SelectionProvider {
+	getSelection(
+		props: unknown,
+		collectNested: (children: ReactNode) => SelectionMeta,
+	): SelectionFieldMeta | SelectionFieldMeta[] | null
+}
+
+// Re-export component types
+export type {
+	EntityPropKeys,
+	EntityFromProp,
+	SelectionFromProp,
+	ImplicitFragmentProperties,
+} from './legacyTypes.js'
+export { COMPONENT_MARKER, COMPONENT_SELECTIONS } from './componentBuilder.js'

package/src/jsx/withCollector.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Attaches a static render function to a component for selection collection.
+ *
+ * During the collection phase, the analyzer calls `staticRender(props)` instead of
+ * analyzing runtime children. Props contain collector proxies, so field accesses
+ * are tracked automatically. The returned JSX is analyzed for nested components.
+ *
+ * @example
+ * ```tsx
+ * // Simple: children is a render prop receiving has-one entity
+ * export const SelectField = withCollector(
+ *   function SelectField({ field, children, ... }) { ... },
+ *   (props) => props.children(props.field.$entity)
+ * )
+ *
+ * // Composing with HasMany for iteration
+ * export const DefaultRepeater = withCollector(
+ *   function DefaultRepeater({ field, children, ... }) { ... },
+ *   (props) => (
+ *     <HasMany field={props.field}>
+ *       {item => props.children(item, collectionItemInfo)}
+ *     </HasMany>
+ *   )
+ * )
+ *
+ * // Programmatic field access (no JSX needed)
+ * export const Uploader = withCollector(
+ *   function Uploader({ field, fileType }) { ... },
+ *   (props) => {
+ *     const entity = props.field.$entity
+ *     for (const ext of props.fileType.extractors) entity[ext.fieldName]
+ *     return null
+ *   }
+ * )
+ * ```
+ */
+export function withCollector<TComponent extends (...args: never[]) => ReactNode>(
+	component: TComponent,
+	staticRender: (props: Parameters<TComponent>[0]) => ReactNode,
+): TComponent {
+	(component as TComponent & { staticRender: typeof staticRender }).staticRender = staticRender
+	return component
+}

package/src/roles/RoleContext.tsx

@@ -0,0 +1,57 @@
+/**
+ * Role provider context for runtime role checking.
+ *
+ * HasRole uses this to determine if the current user has the required roles.
+ * Without a RoleProvider, HasRole always renders (no gating).
+ */
+
+import React, { createContext, useContext, type ReactNode, type ReactElement } from 'react'
+
+// ============================================================================
+// Context
+// ============================================================================
+
+type HasRoleFn = (role: string) => boolean
+
+const RoleContext = createContext<HasRoleFn | null>(null)
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface RoleProviderProps {
+	children: ReactNode
+	/** Function that checks if the current user has a given role */
+	hasRole: HasRoleFn
+}
+
+/**
+ * Provides runtime role checking for HasRole components.
+ *
+ * @example
+ * ```tsx
+ * <RoleProvider hasRole={role => currentUser.roles.includes(role)}>
+ *   <App />
+ * </RoleProvider>
+ * ```
+ */
+export function RoleProvider({ children, hasRole }: RoleProviderProps): ReactElement {
+	return <RoleContext.Provider value={hasRole}>{children}</RoleContext.Provider>
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Returns a function to check if the current user has a given role.
+ * If no RoleProvider is present, returns a function that always returns true.
+ */
+export function useHasRole(): HasRoleFn {
+	const hasRole = useContext(RoleContext)
+	return hasRole ?? alwaysTrue
+}
+
+function alwaysTrue(): boolean {
+	return true
+}

package/src/roles/index.ts

@@ -0,0 +1 @@
+export { RoleProvider, useHasRole, type RoleProviderProps } from './RoleContext.js'