@contember/bindx-uploader 0.1.0

package/src/components/MultiUploader.tsx

@@ -0,0 +1,210 @@
+import { useCallback, useMemo, useRef, type ReactNode } from 'react'
+import type { EntityRef, HasManyRef, SelectionFieldMeta, SelectionMeta } from '@contember/bindx'
+import { FIELD_REF_META } from '@contember/bindx'
+import { BINDX_COMPONENT, type SelectionProvider, createEmptySelection } from '@contember/bindx-react'
+import type { FileType, UploaderEvents } from '../types.js'
+import {
+	MultiUploaderEntityToFileStateMapContext,
+	UploaderOptionsContext,
+	UploaderStateContext,
+	UploaderUploadFilesContext,
+} from '../contexts.js'
+import { useUploadState } from '../internal/hooks/useUploadState.js'
+import { useUploaderDoUpload } from '../internal/hooks/useUploaderDoUpload.js'
+import { resolveAcceptingSingleType } from '../internal/utils/resolveAccept.js'
+import { executeExtractors } from '../internal/utils/executeExtractors.js'
+import { uploaderErrorHandler } from '../internal/utils/uploaderErrorHandler.js'
+
+export interface MultiUploaderProps<TEntity = Record<string, unknown>> {
+	/**
+	 * The has-many relation to add uploaded files to.
+	 */
+	field: HasManyRef<TEntity>
+	/**
+	 * File type configuration defining accepted files and extractors.
+	 * Must be created with the same entity type as the field prop.
+	 */
+	fileType: FileType<TEntity>
+	/**
+	 * Children to render within the uploader context.
+	 */
+	children?: ReactNode
+}
+
+/**
+ * Multi-file upload component for bindx.
+ * Creates new items in a has-many relation for each uploaded file.
+ *
+ * @example
+ * ```tsx
+ * <MultiUploader field={article.images} fileType={imageFileType}>
+ *   <DropZone multiple />
+ *   <UploaderEachFile>
+ *     <UploaderFileStateSwitch
+ *       uploading={<ProgressBar />}
+ *       success={<SuccessMessage />}
+ *       error={<ErrorMessage />}
+ *     />
+ *   </UploaderEachFile>
+ * </MultiUploader>
+ * ```
+ */
+export function MultiUploader<TEntity extends Record<string, unknown>>({
+	field,
+	fileType,
+	children,
+}: MultiUploaderProps<TEntity>): ReactNode {
+	// Map file ID -> entity ID
+	const fileToEntityMapRef = useRef(new Map<string, string>())
+	// Map entity ID -> file ID (for reverse lookup)
+	const entityToFileMapRef = useRef(new Map<string, string>())
+
+	const getEntityForFile = useCallback(
+		(fileId: string): EntityRef<unknown> | undefined => {
+			const entityId = fileToEntityMapRef.current.get(fileId)
+			if (!entityId) return undefined
+			return field.items.find((item: { id: string }) => item.id === entityId) as EntityRef<unknown> | undefined
+		},
+		[field.items],
+	)
+
+	// Create entity for file and track mapping
+	const useCreateRepeaterEntityEvents = useCallback(
+		(events: UploaderEvents): UploaderEvents => ({
+			...events,
+			onBeforeUpload: async event => {
+				if (!(await resolveAcceptingSingleType(event.file, fileType as FileType))) {
+					return undefined
+				}
+
+				// Create new entity in the has-many relation
+				const entityId = field.add()
+				fileToEntityMapRef.current.set(event.file.id, entityId)
+				entityToFileMapRef.current.set(entityId, event.file.id)
+
+				return (await events.onBeforeUpload?.(event)) ?? (fileType as FileType)
+			},
+			onAfterUpload: async event => {
+				await Promise.all([
+					(async () => {
+						const entity = getEntityForFile(event.file.id)
+						if (!entity) return
+
+						const extractionResult = await executeExtractors({
+							fileType: fileType as FileType,
+							result: event.result,
+							file: event.file,
+						})
+						extractionResult?.({ entity })
+					})(),
+					events.onAfterUpload?.(event),
+				])
+			},
+			onError: event => {
+				// Remove entity on error
+				const entityId = fileToEntityMapRef.current.get(event.file.id)
+				if (entityId) {
+					field.remove(entityId)
+					fileToEntityMapRef.current.delete(event.file.id)
+					entityToFileMapRef.current.delete(entityId)
+				}
+				events.onError?.(event)
+			},
+		}),
+		[field, fileType, getEntityForFile],
+	)
+
+	const baseEvents: UploaderEvents = useMemo(
+		() => ({
+			onError: uploaderErrorHandler,
+			onStartUpload: () => {},
+			onBeforeUpload: async () => undefined,
+			onProgress: () => {},
+			onAfterUpload: async () => {},
+			onSuccess: () => {},
+		}),
+		[],
+	)
+
+	const fillEntityEvents = useCreateRepeaterEntityEvents(baseEvents)
+	const { files, ...stateEvents } = useUploadState(fillEntityEvents)
+	const onDrop = useUploaderDoUpload(stateEvents)
+
+	const options = useMemo(
+		() => ({
+			accept: fileType.accept,
+			multiple: true,
+		}),
+		[fileType.accept],
+	)
+
+	return (
+		<MultiUploaderEntityToFileStateMapContext.Provider value={entityToFileMapRef.current}>
+			<UploaderStateContext.Provider value={files}>
+				<UploaderUploadFilesContext.Provider value={onDrop}>
+					<UploaderOptionsContext.Provider value={options}>
+						{children}
+					</UploaderOptionsContext.Provider>
+				</UploaderUploadFilesContext.Provider>
+			</UploaderStateContext.Provider>
+		</MultiUploaderEntityToFileStateMapContext.Provider>
+	)
+}
+
+/**
+ * Collects field names from all extractors in a file type.
+ */
+function collectExtractorFieldNames(fileType: FileType): string[] {
+	const fieldNames: string[] = []
+	for (const extractor of fileType.extractors ?? []) {
+		fieldNames.push(...extractor.getFieldNames())
+	}
+	return fieldNames
+}
+
+/**
+ * Builds nested selection meta from field names.
+ */
+function buildNestedSelection(fieldNames: string[]): SelectionMeta {
+	const selection = createEmptySelection()
+	for (const fieldName of fieldNames) {
+		selection.fields.set(fieldName, {
+			fieldName,
+			alias: fieldName,
+			path: [],
+			isArray: false,
+			isRelation: false,
+		})
+	}
+	return selection
+}
+
+// Static method for selection extraction
+const multiUploaderWithSelection = MultiUploader as typeof MultiUploader & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+multiUploaderWithSelection.getSelection = (
+	props: MultiUploaderProps,
+	_collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta | null => {
+	const fieldNames = collectExtractorFieldNames(props.fileType)
+
+	if (fieldNames.length === 0) {
+		return null
+	}
+
+	const meta = props.field[FIELD_REF_META]
+
+	// MultiUploader always works with a has-many relation
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: true,
+		isRelation: true,
+		nested: buildNestedSelection(fieldNames),
+	}
+}
+
+multiUploaderWithSelection[BINDX_COMPONENT] = true
+
+export { multiUploaderWithSelection as MultiUploaderWithMeta }

package/src/components/Uploader.tsx

@@ -0,0 +1,174 @@
+import { useMemo, type ReactNode } from 'react'
+import type { EntityRef, HasOneRef, SelectionFieldMeta, SelectionMeta } from '@contember/bindx'
+import { FIELD_REF_META } from '@contember/bindx'
+import { BINDX_COMPONENT, type SelectionProvider, createEmptySelection } from '@contember/bindx-react'
+import type { FileType } from '../types.js'
+import {
+	UploaderOptionsContext,
+	UploaderStateContext,
+	UploaderUploadFilesContext,
+} from '../contexts.js'
+import { useUploadState } from '../internal/hooks/useUploadState.js'
+import { useUploaderDoUpload } from '../internal/hooks/useUploaderDoUpload.js'
+import { useFillEntity } from '../internal/hooks/useFillEntity.js'
+import { uploaderErrorHandler } from '../internal/utils/uploaderErrorHandler.js'
+
+export interface UploaderProps<TEntity = Record<string, unknown>> {
+	/**
+	 * The entity to fill with uploaded file data.
+	 * Can be an EntityRef or HasOneRef.
+	 */
+	entity: EntityRef<TEntity> | HasOneRef<TEntity>
+	/**
+	 * File type configuration defining accepted files and extractors.
+	 * Must be created with the same entity type as the entity prop.
+	 */
+	fileType: FileType<TEntity>
+	/**
+	 * Children to render within the uploader context.
+	 */
+	children?: ReactNode
+}
+
+const noop = (): Promise<undefined> => Promise.resolve(undefined)
+
+/**
+ * Single file upload component for bindx.
+ * Provides upload state and upload function to children via context.
+ *
+ * @example
+ * ```tsx
+ * interface Image {
+ *   id: string
+ *   url: string
+ *   width: number
+ *   height: number
+ * }
+ *
+ * const imageFileType = createImageFileType<Image>({
+ *   urlField: 'url',
+ *   widthField: 'width',
+ *   heightField: 'height',
+ * })
+ *
+ * // article.image is HasOneRef<Image>
+ * <Uploader entity={article.image} fileType={imageFileType}>
+ *   <DropZone />
+ *   <UploaderEachFile>
+ *     <UploaderFileStateSwitch
+ *       uploading={<ProgressBar />}
+ *       success={<SuccessMessage />}
+ *       error={<ErrorMessage />}
+ *     />
+ *   </UploaderEachFile>
+ * </Uploader>
+ * ```
+ */
+export function Uploader<TEntity extends Record<string, unknown>>({
+	entity,
+	fileType,
+	children,
+}: UploaderProps<TEntity>): ReactNode {
+	const fillEntityEvents = useFillEntity({
+		entity,
+		fileType,
+		onError: uploaderErrorHandler,
+		onStartUpload: noop,
+		onBeforeUpload: noop,
+		onProgress: noop,
+		onAfterUpload: noop,
+		onSuccess: noop,
+	})
+
+	const { files, ...stateEvents } = useUploadState(fillEntityEvents)
+	const onDrop = useUploaderDoUpload(stateEvents)
+
+	const options = useMemo(
+		() => ({
+			accept: fileType.accept,
+			multiple: false,
+		}),
+		[fileType.accept],
+	)
+
+	return (
+		<UploaderStateContext.Provider value={files}>
+			<UploaderUploadFilesContext.Provider value={onDrop}>
+				<UploaderOptionsContext.Provider value={options}>
+					{children}
+				</UploaderOptionsContext.Provider>
+			</UploaderUploadFilesContext.Provider>
+		</UploaderStateContext.Provider>
+	)
+}
+
+/**
+ * Type guard to check if an entity has FIELD_REF_META (is a relation handle).
+ */
+function hasFieldRefMeta(entity: unknown): entity is { [FIELD_REF_META]: { fieldName: string; path: string[]; isRelation: boolean } } {
+	return entity !== null && typeof entity === 'object' && FIELD_REF_META in entity
+}
+
+/**
+ * Collects field names from all extractors in a file type.
+ */
+function collectExtractorFieldNames(fileType: FileType): string[] {
+	const fieldNames: string[] = []
+	for (const extractor of fileType.extractors ?? []) {
+		fieldNames.push(...extractor.getFieldNames())
+	}
+	return fieldNames
+}
+
+/**
+ * Builds nested selection meta from field names.
+ */
+function buildNestedSelection(fieldNames: string[]): SelectionMeta {
+	const selection = createEmptySelection()
+	for (const fieldName of fieldNames) {
+		selection.fields.set(fieldName, {
+			fieldName,
+			alias: fieldName,
+			path: [],
+			isArray: false,
+			isRelation: false,
+		})
+	}
+	return selection
+}
+
+// Static method for selection extraction
+const uploaderWithSelection = Uploader as typeof Uploader & SelectionProvider & { [BINDX_COMPONENT]: true }
+
+uploaderWithSelection.getSelection = (
+	props: UploaderProps,
+	_collectNested: (children: ReactNode) => SelectionMeta,
+): SelectionFieldMeta | null => {
+	const fieldNames = collectExtractorFieldNames(props.fileType)
+
+	if (fieldNames.length === 0) {
+		return null
+	}
+
+	// Only HasOneRef has FIELD_REF_META - EntityRef doesn't have it
+	// If passed an EntityRef directly, we can't build selection (return null)
+	if (!hasFieldRefMeta(props.entity)) {
+		return null
+	}
+
+	const meta = props.entity[FIELD_REF_META]
+
+	// Return nested selection under the relation
+	return {
+		fieldName: meta.fieldName,
+		alias: meta.fieldName,
+		path: meta.path,
+		isArray: false,
+		isRelation: true,
+		nested: buildNestedSelection(fieldNames),
+	}
+}
+
+uploaderWithSelection[BINDX_COMPONENT] = true
+
+export { uploaderWithSelection as UploaderWithMeta }

package/src/components/UploaderDropzoneArea.tsx

@@ -0,0 +1,29 @@
+import { type ReactNode, useMemo } from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { useUploaderDropzoneState, useUploaderState } from '../contexts.js'
+
+const dataAttribute = (value: unknown): '' | undefined => value ? '' : undefined
+
+export interface UploaderDropzoneAreaProps {
+	children: ReactNode
+}
+
+export const UploaderDropzoneArea = ({ children }: UploaderDropzoneAreaProps): ReactNode => {
+	const { getRootProps, isDragActive, isDragAccept, isDragReject, isFocused, isFileDialogActive } = useUploaderDropzoneState()
+	const files = useUploaderState()
+	const isUploading = useMemo(() => files.some(it => it.state === 'uploading' || it.state === 'initial'), [files])
+
+	return (
+		<Slot
+			{...getRootProps()}
+			data-dropzone-active={dataAttribute(isDragActive)}
+			data-dropzone-accept={dataAttribute(isDragAccept)}
+			data-dropzone-reject={dataAttribute(isDragReject)}
+			data-dropzone-focused={dataAttribute(isFocused)}
+			data-dropzone-file-dialog-active={dataAttribute(isFileDialogActive)}
+			data-dropzone-uploading={dataAttribute(isUploading)}
+		>
+			{children}
+		</Slot>
+	)
+}

package/src/components/UploaderDropzoneRoot.tsx

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react'
+import { useDropzone } from 'react-dropzone'
+import { UploaderDropzoneStateContext } from '../contexts.js'
+import { useUploaderOptions, useUploaderUploadFiles } from '../contexts.js'
+
+export interface UploaderDropzoneRootProps {
+	children: ReactNode
+	noInput?: boolean
+	disabled?: boolean
+}
+
+export const UploaderDropzoneRoot = ({ children, noInput, disabled }: UploaderDropzoneRootProps): ReactNode => {
+	const onDrop = useUploaderUploadFiles()
+	const { multiple, accept } = useUploaderOptions()
+
+	const dropzoneState = useDropzone({
+		onDrop,
+		disabled,
+		accept,
+		multiple,
+		noKeyboard: true, // Keyboard navigation handled by button inside
+	})
+
+	return (
+		<UploaderDropzoneStateContext.Provider value={dropzoneState}>
+			{noInput ? null : (
+				<input {...dropzoneState.getInputProps()} />
+			)}
+			{children}
+		</UploaderDropzoneStateContext.Provider>
+	)
+}

package/src/components/UploaderEachFile.tsx

@@ -0,0 +1,46 @@
+import { Fragment, type ReactNode } from 'react'
+import type { UploaderFileState } from '../types.js'
+import { UploaderFileStateContext, useUploaderState } from '../contexts.js'
+import type { StateFilter } from '../hooks/useUploaderStateFiles.js'
+
+export interface UploaderEachFileProps {
+	children: ReactNode
+	/** Filter by specific state(s) */
+	state?: StateFilter
+	/** Fallback when no files match */
+	fallback?: ReactNode
+}
+
+/**
+ * Iterates over files in the upload state, providing file state context to children.
+ */
+export function UploaderEachFile({
+	children,
+	state: stateFilter,
+	fallback,
+}: UploaderEachFileProps): ReactNode {
+	const files = useUploaderState()
+
+	const filteredFiles = stateFilter
+		? files.filter(file => {
+				const filterArray = Array.isArray(stateFilter) ? stateFilter : [stateFilter]
+				return filterArray.includes(file.state)
+			})
+		: files
+
+	if (filteredFiles.length === 0 && fallback !== undefined) {
+		return fallback
+	}
+
+	return (
+		<>
+			{filteredFiles.map(file => (
+				<Fragment key={file.file.id}>
+					<UploaderFileStateContext.Provider value={file}>
+						{children}
+					</UploaderFileStateContext.Provider>
+				</Fragment>
+			))}
+		</>
+	)
+}

package/src/components/UploaderFileStateSwitch.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode, ComponentType } from 'react'
+import type {
+	UploaderFileState,
+	UploaderFileStateInitial,
+	UploaderFileStateUploading,
+	UploaderFileStateFinalizing,
+	UploaderFileStateSuccess,
+	UploaderFileStateError,
+} from '../types.js'
+import { useUploaderFileState } from '../contexts.js'
+
+type StateRenderer<TState> = ReactNode | ComponentType<{ state: TState }>
+
+export interface UploaderFileStateSwitchProps {
+	/** Render for initial state (file selected, pre-upload) */
+	initial?: StateRenderer<UploaderFileStateInitial>
+	/** Render for uploading state */
+	uploading?: StateRenderer<UploaderFileStateUploading>
+	/** Render for finalizing state (upload complete, processing) */
+	finalizing?: StateRenderer<UploaderFileStateFinalizing>
+	/** Render for success state */
+	success?: StateRenderer<UploaderFileStateSuccess>
+	/** Render for error state */
+	error?: StateRenderer<UploaderFileStateError>
+}
+
+function renderState<TState>(
+	renderer: StateRenderer<TState> | undefined,
+	state: TState,
+): ReactNode {
+	if (renderer === undefined) {
+		return null
+	}
+	if (typeof renderer === 'function') {
+		const Component = renderer as ComponentType<{ state: TState }>
+		return <Component state={state} />
+	}
+	return renderer
+}
+
+/**
+ * Renders different content based on the current file upload state.
+ * Must be used within UploaderEachFile or another component that provides UploaderFileStateContext.
+ */
+export function UploaderFileStateSwitch({
+	initial,
+	uploading,
+	finalizing,
+	success,
+	error,
+}: UploaderFileStateSwitchProps): ReactNode {
+	const state = useUploaderFileState()
+
+	switch (state.state) {
+		case 'initial':
+			return renderState(initial, state)
+		case 'uploading':
+			return renderState(uploading, state)
+		case 'finalizing':
+			return renderState(finalizing, state)
+		case 'success':
+			return renderState(success, state)
+		case 'error':
+			return renderState(error, state)
+	}
+}

package/src/components/UploaderHasFile.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react'
+import { useUploaderState } from '../contexts.js'
+import type { StateFilter } from '../hooks/useUploaderStateFiles.js'
+
+export interface UploaderHasFileProps {
+	children: ReactNode
+	/** Fallback when no files match */
+	fallback?: ReactNode
+	/** Filter by specific state(s) */
+	state?: StateFilter
+}
+
+/**
+ * Conditionally renders children if there are files in the upload state.
+ */
+export function UploaderHasFile({
+	children,
+	fallback,
+	state: stateFilter,
+}: UploaderHasFileProps): ReactNode {
+	const files = useUploaderState()
+
+	const hasFiles = stateFilter
+		? files.some(file => {
+				const filterArray = Array.isArray(stateFilter) ? stateFilter : [stateFilter]
+				return filterArray.includes(file.state)
+			})
+		: files.length > 0
+
+	if (!hasFiles) {
+		return fallback ?? null
+	}
+
+	return children
+}

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export { Uploader, UploaderWithMeta, type UploaderProps } from './Uploader.js'
+export { MultiUploader, MultiUploaderWithMeta, type MultiUploaderProps } from './MultiUploader.js'
+export { UploaderEachFile, type UploaderEachFileProps } from './UploaderEachFile.js'
+export { UploaderHasFile, type UploaderHasFileProps } from './UploaderHasFile.js'
+export { UploaderFileStateSwitch, type UploaderFileStateSwitchProps } from './UploaderFileStateSwitch.js'
+export { UploaderDropzoneRoot, type UploaderDropzoneRootProps } from './UploaderDropzoneRoot.js'
+export { UploaderDropzoneArea, type UploaderDropzoneAreaProps } from './UploaderDropzoneArea.js'

package/src/contexts.ts

@@ -0,0 +1,76 @@
+import { createContext, useContext } from 'react'
+import type { DropzoneState } from 'react-dropzone'
+import type { UploaderFileState, UploaderOptions, UploaderState, UploadClient } from './types.js'
+
+// ============================================================================
+// Context Creation Helpers
+// ============================================================================
+
+function createRequiredContext<T>(name: string): [React.Context<T | null>, () => T] {
+	const Context = createContext<T | null>(null)
+	Context.displayName = name
+
+	const useContextHook = (): T => {
+		const value = useContext(Context)
+		if (value === null) {
+			throw new Error(`${name} must be used within its Provider`)
+		}
+		return value
+	}
+
+	return [Context, useContextHook]
+}
+
+// ============================================================================
+// Public Contexts
+// ============================================================================
+
+/**
+ * Context for the upload function
+ */
+export const [UploaderUploadFilesContext, useUploaderUploadFiles] =
+	createRequiredContext<(files: File[]) => void>('UploaderUploadFiles')
+
+/**
+ * Context for current upload state
+ */
+export const [UploaderStateContext, useUploaderState] =
+	createRequiredContext<UploaderState>('UploaderState')
+
+/**
+ * Context for uploader options (accept, multiple)
+ */
+export const [UploaderOptionsContext, useUploaderOptions] =
+	createRequiredContext<UploaderOptions>('UploaderOptions')
+
+/**
+ * Context for current file state (within UploaderEachFile)
+ */
+export const [UploaderFileStateContext, useUploaderFileState] =
+	createRequiredContext<UploaderFileState>('UploaderFileState')
+
+/**
+ * Context for the default upload client
+ */
+export const UploaderClientContext = createContext<UploadClient<unknown> | null>(null)
+UploaderClientContext.displayName = 'UploaderClient'
+
+export const useUploaderClient = (): UploadClient<unknown> | null => {
+	return useContext(UploaderClientContext)
+}
+
+// ============================================================================
+// Internal Contexts
+// ============================================================================
+
+/**
+ * Context for multi-uploader entity to file state mapping
+ */
+export const MultiUploaderEntityToFileStateMapContext = createContext<Map<string, string> | null>(null)
+MultiUploaderEntityToFileStateMapContext.displayName = 'MultiUploaderEntityToFileStateMap'
+
+/**
+ * Context for dropzone state from react-dropzone
+ */
+export const [UploaderDropzoneStateContext, useUploaderDropzoneState] =
+	createRequiredContext<DropzoneState>('UploaderDropzoneState')