@codeleap/web 6.2.3 → 6.8.0

package/src/components/Dropzone/index.tsx

@@ -1,227 +1,82 @@
-import { DropzoneFilePreviewProps, DropzoneInnerFilePreviewProps, DropzoneProps, DropzoneRef } from './types'
-import { PropsOf, TypeGuards } from '@codeleap/types'
-import { onUpdate, useCallback } from '@codeleap/hooks'
-import { FileRejection, useDropzone } from 'react-dropzone'
+import { DropzoneProps, DropzonePropsAugmentation, DropzoneRef } from './types'
+import { useImperativeHandle, useRef } from 'react'
 import { View, ViewProps } from '../View'
 import { Text } from '../Text'
 import { Icon } from '../Icon'
-import { forwardRef, useImperativeHandle, useState, HTMLProps } from 'react'
-import { ActionIcon } from '../ActionIcon'
 import { useStylesFor } from '../../lib/hooks/useStylesFor'
 import { WebStyleRegistry } from '../../lib/WebStyleRegistry'
-import { AnyRecord, AppIcon, IJSX, StyledComponentProps, StyledComponentWithProps, useNestedStylesByKey } from '@codeleap/styles'
+import { AnyRecord, AppIcon, IJSX, StyledComponentProps } from '@codeleap/styles'
+import { DropzoneProvider } from './context'
+import { DropzoneWrapper, DropzoneOverlay, DropzoneFullscreenOverlay } from './elements'
+import { useDropzone } from './useDropzone'
+import { useDropzoneContext } from './context'
 
 export * from './styles'
 export * from './types'
-
-function isImage(file) {
-  return file?.type?.startsWith('image/')
-}
-
-const DefaultFilePreview = (props: DropzoneInnerFilePreviewProps) => {
-  const {
-    file,
-    styles,
-    errors = [],
-    onRemove,
-    fileLeftIcon,
-    fileRightIcon,
-    fileRightIconStyles,
-    hasErrors,
-    revokeImageUrl,
-    imageUrl,
-    isPreview,
-  } = props
-
-  const handleRemove = (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
-    e?.stopPropagation?.()
-    onRemove?.()
+export * from './context'
+export * from './elements'
+export * from './useDropzone'
+
+/**
+ * Drag-and-drop file upload zone. Stateless — use the `onDrop` callback to
+ * receive dropped files and manage your own file state.
+ *
+ * Assign `Dropzone.Default` to replace the built-in empty-state UI.
+ * Augment `DropzonePropsAugmentation` to add app-specific props that flow
+ * through to `Dropzone.Default` via context.
+ *
+ * For custom layouts compose the primitives directly:
+ * `Dropzone.Provider` + `Dropzone.Wrapper` + `Dropzone.Overlay` + `Dropzone.FullscreenOverlay`.
+ */
+export const Dropzone = (props: DropzoneProps) => {
+  const merged = {
+    ...Dropzone.defaultProps,
+    ...props,
   }
 
-  return (
-    <View style={[styles.fileWrapper, hasErrors && styles['fileWrapper:error']]}>
-      {isPreview ? (
-        <img
-          onLoad={revokeImageUrl}
-          src={imageUrl}
-          css={styles.fileImage}
-        />
-      ) : (
-        <Icon
-          debugName='DropzoneFilePreview:LeftIcon'
-          name={fileLeftIcon}
-          style={styles.fileLeftIcon}
-        />)
-      }
-
-      <View style={styles.fileNameWrapper}>
-        <Text text={file.name} style={styles.fileName} />
-        {hasErrors && errors?.map(error => <Text text={error.message} style={styles.fileError} />)}
-      </View>
-
-      <ActionIcon
-        onPress={handleRemove}
-        propagate={false}
-        debugName='DropzoneFilePreview:RightIcon'
-        name={fileRightIcon}
-        style={fileRightIconStyles}
-      />
-    </View>
-  )
-}
-
-const FilePreview = (props: DropzoneFilePreviewProps) => {
-  const {
-    file,
-    withImagePreview,
-    errors = [],
-    FilePreviewComponent,
-    ...rest
-  } = props
-
-  const hasErrors = errors?.length > 0
-  const isPreview = withImagePreview && isImage(file)
-
-  const [imageUrl, setImageUrl] = useState<string>()
-
-  const revokeImageUrl = () => {
-    URL.revokeObjectURL(imageUrl)
-  }
-
-  onUpdate(() => {
-    if (isImage(file)) {
-      setImageUrl(URL.createObjectURL(file))
-    }
-  }, [file])
-
-  const _FilePreview = !TypeGuards.isNil(FilePreviewComponent) ? FilePreviewComponent : DefaultFilePreview
-
-  return (
-    <_FilePreview
-      file={file}
-      hasErrors={hasErrors}
-      isPreview={isPreview}
-      imageUrl={imageUrl}
-      revokeImageUrl={revokeImageUrl}
-      errors={errors}
-      {...rest}
-    />
-  )
-}
-
-export const Dropzone = (props: DropzoneProps) => {
   const {
     icon,
-    placeholder,
-    multiple,
-    acceptedFiles,
-    setAcceptedFiles,
-    rejectedFiles: rejectedFilesProps,
-    setRejectedFiles: setRejectedFilesProps,
-    fileLeftIcon,
-    fileRightIcon,
-    withImagePreview,
-    onDrop,
-    onRemove,
+  
     children,
-    FilePreviewComponent,
     style,
     ref,
-    ...rest
-  } = {
-    ...Dropzone.defaultProps,
-    ...props,
-  }
+    ...dropzoneOptions
+  } = merged
 
+  const handle = useDropzone(dropzoneOptions)
   const styles = useStylesFor(Dropzone.styleRegistryName, style)
 
-  const [rejectedFilesState, setRejectedFilesState] = useState<DropzoneProps['rejectedFiles']>([])
-  const [rejectedFiles, setRejectedFiles] = [rejectedFilesProps || rejectedFilesState, setRejectedFilesProps || setRejectedFilesState]
-
-  const fileRightIconStyles = useNestedStylesByKey('fileRightIcon', styles)
-
-  const handleDrop = useCallback((newAcceptedFiles: File[], newRejectedFiles: FileRejection[], event) => {
-    setRejectedFiles(newRejectedFiles)
-    setAcceptedFiles?.(state => multiple ? [...state, ...newAcceptedFiles] : newAcceptedFiles)
-    onDrop?.(newAcceptedFiles, newRejectedFiles, event)
-  }, [onDrop, setAcceptedFiles])
-
-  const handleRemoveFile = useCallback((file: File, isRejected = false) => {
-    if (!isRejected) {
-      setAcceptedFiles?.(state => state.filter(f => f.name !== file.name))
-    } else {
-      setRejectedFiles(state => state.filter(f => f.file.name !== file.name))
-    }
-  }, [setAcceptedFiles])
-
-  const { getRootProps, getInputProps, open } = useDropzone({
-    ...rest,
-    multiple,
-    onDrop: handleDrop,
-  })
-
-  const clear = useCallback(() => {
-    setAcceptedFiles?.([])
-    setRejectedFiles([])
-  }, [setAcceptedFiles])
+  const handleRef = useRef(handle)
+  handleRef.current = handle
 
   useImperativeHandle(ref, () => ({
-    clear,
-    open,
+    open: () => handleRef.current.dropzone.open(),
   }))
 
-  const hasFiles = acceptedFiles?.length > 0 || rejectedFiles?.length > 0
-
-  const fileProps = {
-    fileLeftIcon,
-    fileRightIcon,
-    styles,
-    withImagePreview,
-    fileRightIconStyles,
-  }
+  const extensionProps: DropzonePropsAugmentation = merged
 
   return (
     <View style={styles.wrapper}>
-      <View {...getRootProps() as PropsOf<ViewProps>} style={styles.dropzone}>
-
-        {icon && !hasFiles ? (
-          <View style={styles.iconWrapper}>
-            <Icon debugName='Dropzone:Icon' name={icon} style={styles.icon} />
-          </View>
-        ) : null}
-
-        {hasFiles ? (
-          <View style={styles.filesWrapper}>
-            {acceptedFiles?.map?.((file, index) => (
-              <FilePreview
-                {...fileProps}
-                index={index}
-                file={file}
-                key={file.name}
-                onRemove={() => handleRemoveFile(file)}
-                FilePreviewComponent={FilePreviewComponent}
-              />))}
-
-            {rejectedFiles?.map?.(({ file, errors }, index) => (
-              <FilePreview
-                {...fileProps}
-                index={index}
-                key={file.name}
-                file={file}
-                errors={errors}
-                onRemove={() => handleRemoveFile(file, true)}
-                FilePreviewComponent={FilePreviewComponent}
-              />))}
-          </View>
-        ) : null}
-
-        {children}
-
-        {!!placeholder ? <Text text={placeholder} style={styles.placeholder} /> : null}
-
-        <input {...getInputProps() as HTMLProps<HTMLInputElement>} />
-      </View>
-    </View>)
+      <DropzoneProvider handle={handle} style={style} extensionProps={extensionProps}>
+        <DropzoneWrapper>
+          {Dropzone.Default ? (
+            <Dropzone.Default />
+          ) : (
+            <>
+              {icon ? (
+                <View style={styles.iconWrapper}>
+                  <Icon debugName='Dropzone:Icon' icon={icon} style={styles.icon} />
+                </View>
+              ) : null}
+             
+            </>
+          )}
+
+          {children}
+        </DropzoneWrapper>
+      </DropzoneProvider>
+    </View>
+  )
 }
 
 Dropzone.styleRegistryName = 'Dropzone'
@@ -229,18 +84,14 @@ Dropzone.styleRegistryName = 'Dropzone'
 Dropzone.elements = [
   'wrapper',
   'dropzone',
+  'overlay',
+  'overlayInner',
+  'fullscreenOverlay',
+  'fullscreenOverlayInner',
   'icon',
-  'placeholder',
-  'filesWrapper',
-  'fileWrapper',
-  'fileLeftIcon',
-  'fileName',
-  'fileError',
-  'fileErrors',
-  'fileNameWrapper',
-  'fileImage',
   'iconWrapper',
-  `fileRightIcon`,
+  'title',
+  'placeholder',
 ]
 
 Dropzone.rootElement = 'wrapper'
@@ -252,10 +103,13 @@ Dropzone.withVariantTypes = <S extends AnyRecord>(styles: S) => {
 Dropzone.defaultProps = {
   icon: 'file-plus' as AppIcon,
   multiple: false,
-  acceptedFiles: [],
-  fileLeftIcon: 'file' as AppIcon,
-  fileRightIcon: 'x' as AppIcon,
-  withImagePreview: true,
 } as Partial<DropzoneProps>
 
+Dropzone.Provider = DropzoneProvider
+Dropzone.Wrapper = DropzoneWrapper
+Dropzone.Overlay = DropzoneOverlay
+Dropzone.FullscreenOverlay = DropzoneFullscreenOverlay
+Dropzone.useContext = useDropzoneContext
+Dropzone.Default = null as React.ComponentType | null
+
 WebStyleRegistry.registerComponent(Dropzone)

package/src/components/Dropzone/styles.ts

@@ -1,17 +1,12 @@
-import { ActionIconComposition } from '../ActionIcon'
-
+/** Style element keys for the Dropzone component. */
 export type DropzoneComposition =
   | 'wrapper'
   | 'dropzone'
+  | 'overlay'
+  | 'overlayInner'
+  | 'fullscreenOverlay'
+  | 'fullscreenOverlayInner'
   | 'icon'
-  | 'placeholder'
-  | 'filesWrapper'
-  | 'fileWrapper'
-  | 'fileLeftIcon'
-  | 'fileName'
-  | 'fileError'
-  | 'fileErrors'
-  | 'fileNameWrapper'
-  | 'fileImage'
   | 'iconWrapper'
-  | `fileRightIcon${Capitalize<ActionIconComposition>}`
+  | 'title'
+ 

package/src/components/Dropzone/types.ts

@@ -1,53 +1,106 @@
 import { StylesOf } from '@codeleap/types'
 import { DropzoneComposition } from './styles'
-import { DropzoneOptions, FileRejection, DropzoneRef as ReactDropzoneRef } from 'react-dropzone'
-import { ActionIconComposition } from '../ActionIcon'
-import { AppIcon, StyledProp } from '@codeleap/styles'
-import { RefObject } from 'react'
+import {
+  DropzoneOptions as ReactDropzoneOptions,
+  DropzoneState,
+  FileRejection,
+} from 'react-dropzone'
+import { AppIcon, StyleProp, StyledProp } from '@codeleap/styles'
+import React, { RefObject } from 'react'
+
+export interface DropzoneStyleDef {}
+
+/** Augment this interface to add custom props to the `Dropzone` component and context. */
+export interface DropzonePropsAugmentation {}
 
 export type DropzoneFile = File
 
 export type DropzoneFileRejection = FileRejection
 
+// ─── Handle ───────────────────────────────────────────────────────────────────
+
+/** Options accepted by `useDropzone`. Passes all react-dropzone options through unchanged. */
+export type UseDropzoneOptions = ReactDropzoneOptions
+
+/**
+ * Service object returned by `useDropzone`. Contains the full react-dropzone
+ * state pass-through (`getRootProps`, `getInputProps`, `open`, `isDragActive`,
+ * `isDragAccept`, `isDragReject`, `isDragGlobal`, etc.).
+ */
+export type DropzoneHandle = {
+  /** Full react-dropzone state, including getRootProps, getInputProps, open, isDragActive, isDragGlobal, etc. */
+  dropzone: DropzoneState
+}
+
+// ─── Provider ─────────────────────────────────────────────────────────────────
+
+/**
+ * Props for `Dropzone.Provider`. Accepts either a pre-built `handle` (full
+ * external control) or raw `UseDropzoneOptions` to have the Provider create a
+ * handle internally. All react-dropzone options are forwarded when no handle
+ * is supplied.
+ */
+export type DropzoneProviderProps = UseDropzoneOptions & {
+  /** Pre-built handle from `useDropzone`. When provided, all dropzone option props are ignored. */
+  handle?: DropzoneHandle
+  style?: StyleProp<DropzoneComposition, keyof DropzoneStyleDef>
+  children?: React.ReactNode
+  /** Augmented extension props forwarded to context for consumption by `Dropzone.Default`. */
+  extensionProps?: DropzonePropsAugmentation
+}
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+/**
+ * Value stored in `DropzoneContext`. Exposes the handle, resolved styles, and
+ * any augmented extension props to all sub-components.
+ */
+export type DropzoneContextValue = {
+  handle: DropzoneHandle
+  styles: Record<DropzoneComposition, any>
+  extensionProps: DropzonePropsAugmentation
+}
+
+// ─── Element props ────────────────────────────────────────────────────────────
+
+/** Props for `Dropzone.Wrapper` — the droppable zone element. */
+export type DropzoneWrapperProps = {
+  children?: React.ReactNode
+}
+
+/** Props for `Dropzone.Overlay` — shown while a file is dragged over this zone. */
+export type DropzoneOverlayProps = {
+  children?: React.ReactNode
+  style?: StyleProp<DropzoneComposition, keyof DropzoneStyleDef>
+}
+
+/** Props for `Dropzone.FullscreenOverlay` — shown while a file is dragged anywhere on the document. */
+export type DropzoneFullscreenOverlayProps = {
+  children?: React.ReactNode
+  style?: StyleProp<DropzoneComposition, keyof DropzoneStyleDef>
+}
+
+// ─── Convenience wrapper ──────────────────────────────────────────────────────
+
+/**
+ * Props for the `Dropzone` convenience wrapper. Use the `onDrop` callback to
+ * receive dropped files and manage your own file state. Augment
+ * `DropzonePropsAugmentation` to add app-specific props that flow through to
+ * `Dropzone.Default` via context.
+ */
 export type DropzoneProps =
-  Omit<DropzoneOptions, 'style'> &
+  Omit<ReactDropzoneOptions, 'style'> &
+  DropzonePropsAugmentation &
   {
-    style?: StyledProp<DropzoneComposition>
+    style?: StyleProp<DropzoneComposition, keyof DropzoneStyleDef>
     icon?: AppIcon
-    placeholder?: string
-    acceptedFiles: File[]
-    rejectedFiles?: DropzoneFileRejection[]
-    setAcceptedFiles: React.Dispatch<React.SetStateAction<DropzoneFile[]>>
-    setRejectedFiles?: React.Dispatch<React.SetStateAction<DropzoneFileRejection[]>>
-    onRemove?: (file: DropzoneFile) => void
-    children?: React.ReactNode
-    fileRightIcon?: AppIcon
-    fileLeftIcon?: AppIcon
-    withImagePreview?: boolean
-    FilePreviewComponent?: (props: DropzoneInnerFilePreviewProps) => React.ReactElement
+ 
     ref?: RefObject<DropzoneRef | null>
+    children?: React.ReactNode
   }
 
-export type DropzoneFilePreviewProps =
-  Pick<DropzoneProps, 'fileRightIcon' | 'fileLeftIcon' | 'withImagePreview' | 'FilePreviewComponent'> &
-  {
-    file: DropzoneFile
-    errors?: DropzoneFileRejection['errors']
-    styles: StylesOf<DropzoneComposition>
-    onRemove?: () => void
-    fileRightIconStyles?: StylesOf<ActionIconComposition>
-    index?: number
-  }
-
-export type DropzoneInnerFilePreviewProps =
-  DropzoneFilePreviewProps &
-  {
-    hasErrors: boolean
-    revokeImageUrl: () => void
-    imageUrl: string
-    isPreview: boolean
-  }
-
-export type DropzoneRef = ReactDropzoneRef & {
-  clear: () => void
+/** Imperative handle exposed via `ref` on the `Dropzone` convenience wrapper. */
+export type DropzoneRef = {
+  /** Programmatically opens the file picker. */
+  open: () => void
 }

package/src/components/Dropzone/useDropzone.ts

@@ -0,0 +1,18 @@
+import { useDropzone as useReactDropzone } from 'react-dropzone'
+import { DropzoneHandle, UseDropzoneOptions } from './types'
+
+/**
+ * Creates a `DropzoneHandle` — the service object that owns drag-and-drop
+ * mechanics. The returned `dropzone` field is the full react-dropzone state
+ * pass-through (`getRootProps`, `getInputProps`, `open`, `isDragActive`,
+ * `isDragAccept`, `isDragReject`, `isDragGlobal`, etc.).
+ *
+ * Pass the handle to `Dropzone.Provider` to wire it into the component tree,
+ * or use it directly when you need access to the drag state outside JSX.
+ * File management is the caller's responsibility — use the `onDrop` callback
+ * to receive accepted and rejected files.
+ */
+export function useDropzone(options: UseDropzoneOptions = {}): DropzoneHandle {
+  const dropzone = useReactDropzone(options)
+  return { dropzone }
+}

package/src/components/EmptyPlaceholder/index.tsx

@@ -12,6 +12,11 @@ import { AnyRecord, AppIcon, IJSX, StyledComponentProps, useNestedStylesByKey }
 export * from './styles'
 export * from './types'
 
+/**
+ * Communicates an empty or loading state for a content region with an optional icon/image, title, and description.
+ * When `loading` is `true`, replaces all content with an `ActivityIndicator`; when `renderEmpty` is provided, it takes over the entire content layout.
+ * Uses: `Icon`, `Text`, `ActivityIndicator`
+ */
 export const EmptyPlaceholder = (props: EmptyPlaceholderProps) => {
   const {
     itemName,
@@ -55,7 +60,7 @@ export const EmptyPlaceholder = (props: EmptyPlaceholderProps) => {
     if (TypeGuards.isNil(IconEmpty)) return null
 
     if (TypeGuards.isString(IconEmpty)) {
-      return <Icon debugName={debugName} name={IconEmpty as AppIcon} forceStyle={styles.icon} />
+      return <Icon debugName={debugName} icon={IconEmpty as AppIcon} forceStyle={styles.icon} />
     } else if (React.isValidElement(IconEmpty)) {
       return <IconEmpty {...props} />
     }

package/src/components/EmptyPlaceholder/types.ts

@@ -4,7 +4,9 @@ import { ActivityIndicatorComposition, ActivityIndicatorProps } from '../Activit
 import { EmptyPlaceholderComposition } from './styles'
 import { StylesOf } from '@codeleap/types'
 import { ComponentCommonProps } from '../../types'
-import { AppIcon, StyledProp } from '@codeleap/styles'
+import { AppIcon, StyleProp, StyledProp } from '@codeleap/styles'
+
+export interface EmptyPlaceholderStyleDef {}
 
 type RenderEmptyProps = {
   emptyText: string | React.ReactElement
@@ -14,6 +16,13 @@ type RenderEmptyProps = {
   }
 }
 
+/**
+ * @field itemName - Auto-generates a `"No {itemName} found."` title when `title` is not provided.
+ * @field loading - When `true`, hides content and renders an `ActivityIndicator` instead.
+ * @field icon - Theme-registered icon name or a render-function component; ignored when `image` is set.
+ * @field renderEmpty - Fully replaces the default content layout; receives resolved text, icon name, and styles.
+ * @field ImageComponent - Defaults to `"img"`; swap for a framework image component (e.g. Next.js `Image`).
+ */
 export type EmptyPlaceholderProps =
   ComponentCommonProps &
   {
@@ -24,7 +33,7 @@ export type EmptyPlaceholderProps =
     image?: string
     imageProps?: ImgHTMLAttributes<HTMLImageElement>
     loading?: boolean
-    style?: StyledProp<EmptyPlaceholderComposition>
+    style?: StyleProp<EmptyPlaceholderComposition, keyof EmptyPlaceholderStyleDef>
     renderEmpty?: (props: RenderEmptyProps) => React.ReactElement
     wrapperProps?: ViewProps
     imageWrapperProps?: ViewProps

package/src/components/Field/context.tsx

@@ -0,0 +1,66 @@
+import { createContext, useContext, useId } from 'react'
+import { FieldProps } from './types'
+import { useStylesFor } from '../../lib'
+import { FieldStateContext } from './styles'
+
+/** Derives stable ARIA `label` and `helper` element IDs from a base field ID. */
+export const getFieldIds = (baseId: string) => ({
+  label: baseId + '-label',
+  helper: baseId + '-helper',
+})
+
+const useFieldContextProvider = (props: FieldProps) => {
+  const generatedId = useId()
+  const baseId = props.id ?? generatedId
+  const { label: labelId, helper: helperId } = getFieldIds(baseId)
+
+  const stateContext:FieldStateContext = {
+    disabled: props.context?.disabled,
+    error: props.context?.error,
+    focused: props.context?.focused,
+    hasValue: props.context?.hasValue,
+  }
+
+  const styles = useStylesFor('Field', props?.style, stateContext)
+
+  const getClassName = (...suffixes: string[]) => {
+    const getClasses = (basename) => suffixes.map(s => `${basename}__${s}`).join(' ')
+
+    let classes = getClasses('field')
+
+    if (props?.componentName) {
+      classes += ` ${getClasses(props.componentName)}`
+    }
+
+    return classes
+  }
+  return {
+    props,
+    styles,
+    stateContext,
+    getClassName,
+    labelId,
+    helperId,
+  }
+}
+type TFieldContext = ReturnType<typeof useFieldContextProvider>
+
+const FieldContext = createContext({} as TFieldContext)
+
+/**
+ * Context provider for `Field`; computes styles and state data from `FieldProps`
+ * and makes them available to all `Field.*` sub-elements.
+ * Must wrap any composition that uses `useFieldContext`.
+ */
+export const FieldProvider = ({ children, ...props }:React.PropsWithChildren<FieldProps>) => {
+  const value = useFieldContextProvider(props)
+  return <FieldContext.Provider value={value}>
+    {children}
+  </FieldContext.Provider>
+}
+
+/**
+ * Reads the nearest `FieldProvider` context.
+ * Must be called inside a component rendered within `FieldProvider`.
+ */
+export const useFieldContext = () => useContext(FieldContext)