@gentleduck/upload 0.2.6 → 0.3.0

package/src/react/upload-provider.tsx

@@ -1,70 +1,85 @@
-'use client'
+import { createContext, useContext, useEffect } from 'react'
+import type { Contracts } from '../core'
+import type { Store } from '../core/engine/store'
+import type { Uploader } from './uploader.types'
 
-import { createContext, type ReactNode, useContext } from 'react'
-import { type CursorMap, type IntentMap, isRecord, type UploadResultBase } from '../core'
-import type { UploadStore } from '../core/engine/store'
+const UploadContext = createContext<Store.UploadStore<any, any, any, any> | null>(null)
 
-// React Context can't carry generics, so the runtime value is `unknown`; the
-// hooks below re-narrow with `isUploadStore`.
-const UploadContext = createContext<unknown | null>(null)
-
-/** Provides an upload store to descendants. */
+/**
+ * Context provider that distributes the upload store across the React component hierarchy.
+ *
+ * Wrap this provider around the top of your layout to enable child hooks like `useUploader`
+ * to access upload status.
+ *
+ * @example
+ * ```tsx
+ * const store = createUploadStore({ ... });
+ *
+ * function App() {
+ *   return (
+ *     <UploadProvider store={store}>
+ *       <UploadForm />
+ *     </UploadProvider>
+ *   );
+ * }
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
 export function UploadProvider<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->({ store, children }: { store: UploadStore<M, C, P, R>; children: ReactNode }): React.JSX.Element {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>({ store, children }: Uploader.ProviderProps<M, C, P, R>) {
+  // Safe cleanup: destroy the store runner instance if the provider is unmounted.
+  useEffect(() => {
+    return () => {
+      if ('destroy' in store && typeof store.destroy === 'function') {
+        ;(store as unknown as { destroy: () => void }).destroy()
+      }
+    }
+  }, [store])
+
   return <UploadContext.Provider value={store}>{children}</UploadContext.Provider>
 }
 
 /**
- * Read the upload store from context if provided. Returns `null` outside a
- * provider so higher-level hooks can keep their context read unconditional
- * while still accepting an explicit store argument.
+ * Returns the active upload store instance from context.
+ * Throws a runtime exception if called outside an `<UploadProvider>`.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export function useOptionalUploadStore<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(): UploadStore<M, C, P, R> | null {
-  const store = useContext(UploadContext)
-  if (store === null) {
-    return null
-  }
-
-  if (!isUploadStore<M, C, P, R>(store)) {
-    throw new Error('UploadProvider received an invalid store value')
-  }
-
-  return store
-}
-
-/** Read the upload store from context. Throws when called outside `UploadProvider`. */
 export function useUploadStore<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(): UploadStore<M, C, P, R> {
-  const store = useOptionalUploadStore<M, C, P, R>()
-  if (!store) {
-    throw new Error('useUploadStore must be used within UploadProvider')
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(): Store.UploadStore<M, C, P, R> {
+  const context = useContext(UploadContext)
+  if (!context) {
+    throw new Error('useUploadStore must be used within an <UploadProvider>')
   }
-  return store
+  return context as Store.UploadStore<M, C, P, R>
 }
 
-function isUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  value: unknown,
-): value is UploadStore<M, C, P, R> {
-  if (!isRecord(value)) return false
+/**
+ * Runtime type guard: returns `true` when `value` exposes the upload-store
+ * surface (`getSnapshot`, `subscribe`, `dispatch`, `on`, `off`, `waitFor`).
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function isUploadStore<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(value: unknown): value is Store.UploadStore<M, C, P, R> {
+  if (typeof value !== 'object' || value === null) return false
+  const val = value as Record<string, unknown>
   return (
-    typeof value.getSnapshot === 'function' &&
-    typeof value.subscribe === 'function' &&
-    typeof value.dispatch === 'function' &&
-    typeof value.on === 'function' &&
-    typeof value.off === 'function' &&
-    typeof value.waitFor === 'function'
+    typeof val['getSnapshot'] === 'function' &&
+    typeof val['subscribe'] === 'function' &&
+    typeof val['dispatch'] === 'function' &&
+    typeof val['on'] === 'function' &&
+    typeof val['off'] === 'function' &&
+    typeof val['waitFor'] === 'function'
   )
 }

package/src/react/uploader.types.ts

@@ -1,83 +1,80 @@
+import type React from 'react'
 import type { Contracts, Engine } from '../core'
 import type { Store } from '../core/engine/store'
 
 /**
- * React `useUploader` surface types.
- *
- * Houses the public typings consumed by the React hooks so generated
- * `.d.ts` files do not leak internal generic names.
- *
+ * Public typings and namespaces consumed by React hook components.
  * @author wildduck2 <https://github.com/wildduck2>
  */
 export namespace Uploader {
   /**
-   * Pick the variant of `Engine.Item` matching a phase.
+   * Return state payload returned by the `useUploader` hook.
    *
-   * @template Phase Phase literal to filter on.
-   * @returns The item variant whose `phase` matches `Phase`.
-   * @author wildduck2 <https://github.com/wildduck2>
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
    */
-  export type PickItemsByPhase<Phase extends Engine.Phase> = Extract<
-    Engine.Item<Contracts.IntentMap, Contracts.CursorMap<Contracts.IntentMap>, string, Contracts.IResultBase>,
-    { phase: Phase }
-  >
+  export type State<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = Pick<Store.UploadStore<M, C, P, R>, 'dispatch' | 'on' | 'off'> & {
+    /** List of all registered upload items currently tracked. */
+    items: Array<Engine.Item<M, C, P, R>>
+
+    /** Upload items grouped by phase. */
+    byPhase: Record<Engine.Phase, Array<Engine.Item<M, C, P, R>>>
+
+    /** Subset of items currently active in the transfer phase. */
+    uploading: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items currently paused. */
+    paused: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items that successfully completed uploading and backend finalization. */
+    completed: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items currently in the error state. */
+    failed: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items validated and waiting to begin uploading. */
+    ready: Array<Engine.Item<M, C, P, R>>
+  }
 
   /**
-   * Object returned by `useUploader`.
+   * Bound action callbacks returned by context hooks.
    *
-   * @template M Intent map.
-   * @template C Cursor map.
-   * @template P Purpose union.
-   * @template R Backend result shape.
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Houses both the bound dispatchers and the raw underlying store reference.
+   *
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
    */
-  export interface IUploader<
-    M extends Contracts.IntentMap,
-    C extends Contracts.CursorMap<M>,
+  export type IActions<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
     P extends string,
-    R extends Contracts.IResultBase,
-  > {
-    items: Engine.Item<M, C, P, R>[]
-    /**
-     * Items grouped by phase. `Partial<Record<Engine.Phase, ...>>` so consumers
-     * get autocomplete for the eleven known phases and a missing group reads
-     * as `undefined`.
-     */
-    byPhase: Partial<Record<Engine.Phase, Engine.Item<M, C, P, R>[]>>
-    dispatch: (cmd: Engine.Command<P>) => void
-    on: <K extends keyof Engine.EventMap<M, C, P, R> & string>(
-      type: K,
-      cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void,
-    ) => () => void
-    off: <K extends keyof Engine.EventMap<M, C, P, R> & string>(
-      type: K,
-      cb: (payload: Engine.EventMap<M, C, P, R>[K]) => void,
-    ) => void
-    uploading: Engine.Item<M, C, P, R>[]
-    paused: Engine.Item<M, C, P, R>[]
-    completed: Engine.Item<M, C, P, R>[]
-    failed: Engine.Item<M, C, P, R>[]
-    ready: Engine.Item<M, C, P, R>[]
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = Pick<Store.UploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
+    /** The raw upload store instance. */
+    store: Store.UploadStore<M, C, P, R>
   }
 
   /**
-   * Imperative action surface returned by `useUploaderActions`.
-   *
-   * Declared explicitly so generated `.d.ts` files do not leak internal
-   * generic names.
-   *
-   * @template M Intent map.
-   * @template C Cursor map.
-   * @template P Purpose union.
-   * @template R Backend result shape; defaults to `Contracts.IResultBase`.
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Props for the `<UploadProvider>` component.
    */
-  export type IActions<
-    M extends Contracts.IntentMap,
-    C extends Contracts.CursorMap<M>,
+  export interface ProviderProps<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
     P extends string,
-    R extends Contracts.IResultBase = Contracts.IResultBase,
-  > = Pick<Store.IUploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
-    store: Store.IUploadStore<M, C, P, R>
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > {
+    /** The upload store instance to distribute. */
+    store: Store.UploadStore<M, C, P, R>
+    /** React child elements. */
+    children: React.ReactNode
   }
 }

package/src/react/use-dropzone.tsx

@@ -0,0 +1,226 @@
+import type * as React from 'react'
+import { useCallback, useMemo, useRef, useState } from 'react'
+import type { Contracts } from '../core'
+import type { Store } from '../core/engine/store'
+import { useUploadStore } from './upload-provider'
+
+/**
+ * Test a file against one token from an `accept` string. A token is a MIME type
+ * (`image/png`), a MIME wildcard (`image/*`), or a filename extension (`.pdf`).
+ * @internal exported for tests.
+ */
+export function matchesAcceptToken(file: File, token: string): boolean {
+  const t = token.trim().toLowerCase()
+  if (!t) return false
+
+  if (t.startsWith('.')) {
+    return file.name.toLowerCase().endsWith(t)
+  }
+
+  const type = (file.type || '').toLowerCase()
+  if (t.endsWith('/*')) {
+    return type.startsWith(`${t.slice(0, -1)}`) // "image/" prefix
+  }
+  return type === t
+}
+
+/**
+ * True when `file` satisfies an `accept` list (comma-separated tokens). An empty
+ * or absent list accepts everything.
+ * @internal exported for tests.
+ */
+export function fileMatchesAccept(file: File, accept?: string): boolean {
+  if (!accept) return true
+  const tokens = accept
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  if (tokens.length === 0) return true
+  return tokens.some((tok) => matchesAcceptToken(file, tok))
+}
+
+/**
+ * Filter a dropped/selected file list by `accept` and collapse to a single file
+ * when `multiple` is false.
+ * @internal exported for tests.
+ */
+export function selectFiles(
+  files: File[],
+  opts: { accept?: string | undefined; multiple?: boolean | undefined },
+): File[] {
+  const accepted = files.filter((f) => fileMatchesAccept(f, opts.accept))
+  return opts.multiple === false ? accepted.slice(0, 1) : accepted
+}
+
+/** Options for {@link useDropzone}. */
+export type UseDropzoneOptions<P extends string> = {
+  /** Purpose forwarded to the `addFiles` command. */
+  purpose: P
+  /** Optional caller metadata forwarded to every backend API call. */
+  meta?: Record<string, unknown>
+  /**
+   * Comma-separated `accept` list (`"image/*,.pdf"`). Filters dropped files and
+   * populates the input's `accept` attribute. Absent = accept everything.
+   */
+  accept?: string
+  /** Allow multiple files. Defaults to `true`. */
+  multiple?: boolean
+  /** Disable all interaction (no drop, no click-to-open). Defaults to `false`. */
+  disabled?: boolean
+  /** Do not open the file dialog when the root is clicked. Defaults to `false`. */
+  noClick?: boolean
+  /**
+   * Override the default dispatch. When provided, accepted files are handed here
+   * instead of being dispatched as `addFiles` to the store.
+   */
+  onFiles?: (files: File[]) => void
+  /** Store instance to dispatch to. Falls back to the `<UploadProvider>` store. */
+  store?: Store.UploadStore<Contracts.Intent.Map, Contracts.Cursor.Map<Contracts.Intent.Map>, P, Contracts.Result.Base>
+}
+
+/** Return value of {@link useDropzone}. */
+export type UseDropzoneReturn = {
+  /** True while files are being dragged over the root. */
+  isDragging: boolean
+  /** Programmatically open the native file picker. */
+  open: () => void
+  /** Ref to attach to the hidden `<input type="file">`. */
+  inputRef: React.RefObject<HTMLInputElement | null>
+  /** Spread onto the drop-target element. */
+  getRootProps: (extra?: React.HTMLAttributes<HTMLElement>) => React.HTMLAttributes<HTMLElement>
+  /** Spread onto the hidden `<input type="file">`. */
+  getInputProps: (
+    extra?: React.InputHTMLAttributes<HTMLInputElement>,
+  ) => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.Ref<HTMLInputElement> }
+}
+
+/**
+ * Headless drag-and-drop / file-picker hook.
+ *
+ * Wires drop and file-input events to the upload store's `addFiles` command
+ * (or a custom `onFiles` handler). Returns prop-getters for the drop target and
+ * a hidden file input plus a live `isDragging` flag — styling and markup are
+ * entirely yours.
+ *
+ * @example
+ * ```tsx
+ * function Drop() {
+ *   const { getRootProps, getInputProps, isDragging, open } = useDropzone({
+ *     purpose: 'attachment',
+ *     accept: 'image/*',
+ *   });
+ *   return (
+ *     <div {...getRootProps()} data-active={isDragging}>
+ *       <input {...getInputProps()} />
+ *       <button type="button" onClick={open}>Choose files</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function useDropzone<P extends string>(options: UseDropzoneOptions<P>): UseDropzoneReturn {
+  const { purpose, meta, accept, multiple = true, disabled = false, noClick = false, onFiles } = options
+
+  // Read the context store unconditionally (hooks rule); prefer an explicit one.
+  const contextStore = useUploadStore<
+    Contracts.Intent.Map,
+    Contracts.Cursor.Map<Contracts.Intent.Map>,
+    P,
+    Contracts.Result.Base
+  >()
+  const store = options.store ?? contextStore
+
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const [isDragging, setIsDragging] = useState(false)
+  // Depth counter so nested dragenter/dragleave don't flicker the flag.
+  const dragDepth = useRef(0)
+
+  const handleFiles = useCallback(
+    (list: FileList | null) => {
+      if (!list || list.length === 0) return
+      const chosen = selectFiles(Array.from(list), { accept, multiple })
+      if (chosen.length === 0) return
+      if (onFiles) {
+        onFiles(chosen)
+      } else {
+        store.dispatch({ type: 'addFiles', files: chosen, purpose, meta })
+      }
+    },
+    [accept, multiple, onFiles, store, purpose, meta],
+  )
+
+  const open = useCallback(() => {
+    if (disabled) return
+    inputRef.current?.click()
+  }, [disabled])
+
+  const getRootProps = useCallback<UseDropzoneReturn['getRootProps']>(
+    (extra = {}) => ({
+      ...extra,
+      onDragEnter: (e) => {
+        extra.onDragEnter?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current += 1
+        setIsDragging(true)
+      },
+      onDragOver: (e) => {
+        extra.onDragOver?.(e)
+        if (disabled) return
+        // Required so the browser fires `drop` instead of navigating.
+        e.preventDefault()
+        e.stopPropagation()
+      },
+      onDragLeave: (e) => {
+        extra.onDragLeave?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current = Math.max(0, dragDepth.current - 1)
+        if (dragDepth.current === 0) setIsDragging(false)
+      },
+      onDrop: (e) => {
+        extra.onDrop?.(e)
+        if (disabled) return
+        e.preventDefault()
+        e.stopPropagation()
+        dragDepth.current = 0
+        setIsDragging(false)
+        handleFiles(e.dataTransfer?.files ?? null)
+      },
+      onClick: (e) => {
+        extra.onClick?.(e)
+        if (disabled || noClick) return
+        open()
+      },
+    }),
+    [disabled, noClick, open, handleFiles],
+  )
+
+  const getInputProps = useCallback<UseDropzoneReturn['getInputProps']>(
+    (extra = {}) => ({
+      ...extra,
+      ref: inputRef,
+      type: 'file',
+      multiple,
+      disabled,
+      ...(accept ? { accept } : {}),
+      // Visually hidden; caller styles can extend but not un-hide by accident.
+      style: { display: 'none', ...extra.style },
+      onChange: (e) => {
+        extra.onChange?.(e)
+        handleFiles(e.target.files)
+        // Reset so selecting the same file again re-fires change.
+        e.target.value = ''
+      },
+    }),
+    [multiple, disabled, accept, handleFiles],
+  )
+
+  return useMemo(
+    () => ({ isDragging, open, inputRef, getRootProps, getInputProps }),
+    [isDragging, open, getRootProps, getInputProps],
+  )
+}