upload-motion 0.0.0-stage → 0.1.0

package/dist/index-BZJA26zI.d.ts

@@ -0,0 +1,471 @@
+
+//#region src/core/errors.d.ts
+type UploadErrorCode = 'network' | 'timeout' | 'http' | 'aborted' | 'invalid-response' | 'handler';
+declare const BRAND: unique symbol;
+interface UploadErrorInit {
+  status?: number;
+  retryable?: boolean;
+  response?: unknown;
+  cause?: unknown;
+}
+/** Error type produced by built-in transports and by the store when wrapping handler failures. */
+declare class UploadError extends Error {
+  readonly code: UploadErrorCode;
+  readonly status: number | undefined;
+  readonly retryable: boolean;
+  readonly response: unknown;
+  readonly [BRAND] = true;
+  constructor(code: UploadErrorCode, message: string, init?: UploadErrorInit);
+}
+/** Works across bundle copies (no `instanceof` pitfalls). */
+declare function isUploadError(value: unknown): value is UploadError;
+declare function httpErrorMessage(status: number): string;
+declare function toUploadError(error: unknown): UploadError;
+//#endregion
+//#region src/core/types.d.ts
+type FileKind = 'image' | 'video' | 'audio' | 'pdf' | 'document' | 'spreadsheet' | 'presentation' | 'archive' | 'code' | 'data' | 'text' | 'unknown';
+/**
+ * Lifecycle of a single file in the queue.
+ *
+ * - `pending`   selected locally, waiting for `start()` (manual mode or no handler)
+ * - `queued`    waiting for a free concurrency slot
+ * - `uploading` request in flight
+ * - `paused`    request aborted by `pause()`; `resume()` re-queues it
+ * - `success`   handler resolved
+ * - `error`     handler rejected (see `item.error`)
+ * - `canceled`  aborted by `cancel()`; can be retried
+ */
+type UploadStatus = 'pending' | 'queued' | 'uploading' | 'paused' | 'success' | 'error' | 'canceled';
+interface UploadItem<TResponse = unknown> {
+  readonly id: string;
+  readonly file: File;
+  readonly name: string;
+  readonly size: number;
+  readonly type: string;
+  /** Lower-case extension without the dot, e.g. `"pdf"`. Empty string when absent. */
+  readonly extension: string;
+  readonly kind: FileKind;
+  readonly status: UploadStatus;
+  /** 0..1 fraction of bytes reported as sent by the upload handler. */
+  readonly progress: number;
+  readonly loaded: number;
+  /** Smoothed transfer speed in bytes per second (0 when idle). */
+  readonly speed: number;
+  /** Estimated seconds remaining, or `null` when unknown. */
+  readonly eta: number | null;
+  /** Number of times an upload has been attempted. */
+  readonly attempts: number;
+  readonly error: UploadError | null;
+  readonly response: TResponse | undefined;
+  readonly addedAt: number;
+  readonly startedAt: number | null;
+  readonly completedAt: number | null;
+  /** Timestamp of the next automatic retry, when one is scheduled. */
+  readonly retryAt: number | null;
+}
+type RejectionCode = 'file-invalid-type' | 'file-too-large' | 'file-too-small' | 'too-many-files' | 'custom';
+interface RejectionReason {
+  code: RejectionCode;
+  message: string;
+}
+interface FileRejection {
+  readonly id: string;
+  readonly file: File;
+  readonly errors: readonly RejectionReason[];
+  readonly at: number;
+}
+interface UploadContext<TResponse = unknown> {
+  file: File;
+  item: UploadItem<TResponse>;
+  /** Aborted when the upload is canceled, paused, removed or the store is disposed. */
+  signal: AbortSignal;
+  /** 1-based attempt number. */
+  attempt: number;
+  /** Report bytes sent. `total` defaults to `file.size`. */
+  onProgress: (loaded: number, total?: number) => void;
+}
+/**
+ * Sends one file somewhere and resolves with the server response.
+ * Reject (or throw) to mark the upload as failed. Must honour `ctx.signal`.
+ */
+type UploadHandler<TResponse = unknown> = ((ctx: UploadContext<TResponse>) => Promise<TResponse>) & {
+  /** Set by `createSimulatedUploader` so UIs can label fake progress honestly. */
+  readonly simulated?: boolean;
+};
+type CustomValidator = (file: File, context: {
+  items: readonly UploadItem[];
+}) => string | null | undefined | false;
+interface RetryOptions {
+  /** Automatic retries for retryable errors (network, timeout, 5xx). Default 0. */
+  attempts?: number;
+  /** Base delay in ms, doubled each attempt. Default 800. */
+  delay?: number;
+}
+interface UploaderOptions<TResponse = unknown> {
+  /** Transport. Without one, files stay `pending` – nothing is ever claimed as uploaded. */
+  upload?: UploadHandler<TResponse>;
+  /** Same syntax as the `accept` attribute: `"image/*,.pdf"` or `['image/*', '.pdf']`. */
+  accept?: string | readonly string[];
+  /** Max bytes per file. */
+  maxSize?: number;
+  /** Min bytes per file. */
+  minSize?: number;
+  /** Max files held in the queue at once (canceled/failed files count until removed). */
+  maxFiles?: number;
+  /** Allow selecting several files. `false` replaces the current file. Default true. */
+  multiple?: boolean;
+  validate?: CustomValidator;
+  /** Start uploading as soon as files are added. Default true. */
+  autoUpload?: boolean;
+  /** Parallel uploads. Default 3. */
+  concurrency?: number;
+  retry?: number | RetryOptions;
+  onFilesAdded?: (items: UploadItem<TResponse>[]) => void;
+  onFilesRejected?: (rejections: FileRejection[]) => void;
+  onUploadStart?: (item: UploadItem<TResponse>) => void;
+  onUploadProgress?: (item: UploadItem<TResponse>) => void;
+  onUploadSuccess?: (item: UploadItem<TResponse>, response: TResponse) => void;
+  onUploadError?: (item: UploadItem<TResponse>, error: UploadError) => void;
+  onUploadCancel?: (item: UploadItem<TResponse>) => void;
+  onFileRemoved?: (item: UploadItem<TResponse>) => void;
+  /** Fires once every started upload has settled (success, error or canceled). */
+  onQueueComplete?: (items: UploadItem<TResponse>[]) => void;
+  onChange?: (items: UploadItem<TResponse>[]) => void;
+}
+interface UploadTotals {
+  count: number;
+  /** 0..1 across files that are in flight or done (excludes pending, failed, canceled). */
+  progress: number;
+  loaded: number;
+  size: number;
+  speed: number;
+  eta: number | null;
+  pending: number;
+  queued: number;
+  uploading: number;
+  paused: number;
+  success: number;
+  error: number;
+  canceled: number;
+  /** queued + uploading */
+  active: number;
+  isUploading: boolean;
+  /** At least one success and nothing pending, queued, uploading or paused. */
+  isComplete: boolean;
+}
+interface UploadSnapshot<TResponse = unknown> {
+  readonly items: readonly UploadItem<TResponse>[];
+  readonly rejections: readonly FileRejection[];
+  readonly totals: UploadTotals;
+  /** `'simulated'` when the handler fakes progress, `'none'` without a handler. */
+  readonly transport: 'network' | 'simulated' | 'none';
+}
+interface UploadEventMap<TResponse = unknown> {
+  added: UploadItem<TResponse>[];
+  rejected: FileRejection[];
+  start: UploadItem<TResponse>;
+  success: UploadItem<TResponse>;
+  error: UploadItem<TResponse>;
+  cancel: UploadItem<TResponse>;
+  removed: UploadItem<TResponse>;
+  complete: UploadItem<TResponse>[];
+}
+type ClearFilter = 'all' | 'completed' | 'failed' | 'canceled';
+//#endregion
+//#region src/core/store.d.ts
+type Ids = string | readonly string[] | undefined;
+interface AddFilesResult<TResponse = unknown> {
+  accepted: UploadItem<TResponse>[];
+  rejected: FileRejection[];
+}
+interface UploadStore<TResponse = unknown> {
+  /** Immutable snapshot; identity changes only when something changed. */
+  getSnapshot(): UploadSnapshot<TResponse>;
+  /** `useSyncExternalStore`-compatible subscription. Progress is batched per animation frame. */
+  subscribe(listener: () => void): () => void;
+  on<K extends keyof UploadEventMap<TResponse>>(event: K, handler: (payload: UploadEventMap<TResponse>[K]) => void): () => void;
+  setOptions(options: UploaderOptions<TResponse>): void;
+  getOptions(): UploaderOptions<TResponse>;
+  /** The options passed to `createUploadStore` (UI layers merge their props over these). */
+  getInitialOptions(): UploaderOptions<TResponse>;
+  /** Validates and enqueues files. Returns what was accepted and rejected. */
+  addFiles(files: Iterable<File> | ArrayLike<File>): AddFilesResult<TResponse>;
+  /** Starts `pending` files (manual mode). No ids = all pending. */
+  start(ids?: Ids): void;
+  /** Aborts in-flight or waiting uploads; they become `canceled`. No ids = all. */
+  cancel(ids?: Ids): void;
+  /** Re-queues `error`/`canceled` files. No ids = all of them. */
+  retry(ids?: Ids): void;
+  /** Aborts and parks uploads as `paused`. No ids = all active. */
+  pause(ids?: Ids): void;
+  /** Re-queues `paused` files. Transfers restart unless your handler supports resumption. */
+  resume(ids?: Ids): void;
+  /** Aborts (if needed) and removes files from the queue. */
+  remove(ids: string | readonly string[]): void;
+  clear(filter?: ClearFilter): void;
+  dismissRejection(id?: string): void;
+  getItem(id: string): UploadItem<TResponse> | undefined;
+  /** Aborts everything and clears timers. The store stays usable afterwards. */
+  dispose(): void;
+}
+declare function computeTotals(items: readonly UploadItem[]): UploadTotals;
+declare function createUploadStore<TResponse = unknown>(initialOptions?: UploaderOptions<TResponse>): UploadStore<TResponse>;
+//#endregion
+//#region src/core/transports.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type PerItem<T> = T | ((item: UploadItem) => MaybePromise<T>);
+interface XhrUploaderOptions<TResponse = unknown> {
+  /** Endpoint, or a function returning one (e.g. a presigned URL). */
+  url: PerItem<string>;
+  /** Default `POST`. Use `PUT` with `body: 'raw'` for S3/GCS presigned URLs. */
+  method?: 'POST' | 'PUT' | 'PATCH';
+  headers?: PerItem<Record<string, string>>;
+  /** `form-data` (default) sends multipart; `raw` sends the file bytes as the body. */
+  body?: 'form-data' | 'raw';
+  /** Multipart field name for the file. Default `"file"`. */
+  fieldName?: string;
+  /** Extra multipart fields. */
+  formData?: PerItem<Record<string, string | Blob>>;
+  withCredentials?: boolean;
+  /** Request timeout in ms. 0 / undefined disables it. */
+  timeout?: number;
+  /** Turn the finished XHR into your response type. Defaults to JSON when possible, else text. */
+  parseResponse?: (xhr: XMLHttpRequest) => TResponse;
+  /** Which statuses count as success. Default 2xx. */
+  isSuccess?: (status: number) => boolean;
+}
+/**
+ * Real network transport built on `XMLHttpRequest`, the only browser API that
+ * reports upload progress for request bodies on HTTP/1.1.
+ */
+declare function createXhrUploader<TResponse = unknown>(options: XhrUploaderOptions<TResponse>): UploadHandler<TResponse>;
+interface SimulatedUploaderOptions {
+  /** Simulated throughput in bytes per second. A `[min, max]` range picks a random speed per file. Default `[1.5 MB, 6 MB]`. */
+  speed?: number | readonly [number, number];
+  /** Minimum duration in ms so tiny files still show motion. Default 1400. */
+  minDuration?: number;
+  /** 0..1 probability that an attempt fails midway. Default 0. */
+  failureRate?: number;
+  /** Delay before the first byte, in ms. Default 250. */
+  latency?: number;
+}
+/**
+ * Demo transport: no bytes leave the browser. The returned handler is flagged
+ * `simulated: true` so built-in components display a "Simulated" badge.
+ */
+declare function createSimulatedUploader(options?: SimulatedUploaderOptions): UploadHandler<{
+  simulated: true;
+  name: string;
+  size: number;
+}>;
+//#endregion
+//#region src/core/validation.d.ts
+/** Normalises `accept` to lower-case tokens: `['image/*', '.pdf', 'application/json']`. */
+declare function parseAccept(accept: string | readonly string[] | undefined): string[];
+/** Mirrors the browser's `accept` matching rules. An empty list accepts everything. */
+declare function isFileAccepted(file: {
+  name: string;
+  type?: string;
+}, accept: readonly string[]): boolean;
+/** Human description of an accept list: `"Images, PDF"`. */
+declare function describeAccept(accept: readonly string[]): string;
+interface ValidationRules {
+  accept: readonly string[];
+  maxSize?: number;
+  minSize?: number;
+  validate?: CustomValidator;
+}
+declare function validateFile(file: File, rules: ValidationRules, items: readonly UploadItem[]): RejectionReason[];
+//#endregion
+//#region src/core/file-kind.d.ts
+declare function getExtension(name: string): string;
+/** Classifies a file by extension first (more specific), then MIME type. */
+declare function getFileKind(file: {
+  name: string;
+  type?: string;
+}): FileKind;
+/** Short badge label such as `PDF`, `DOCX`, `MP4`. Falls back to the kind. */
+declare function getFileLabel(file: {
+  name: string;
+  type?: string;
+}): string;
+/** Kinds that browsers can render as an `<img>` without extra libraries. */
+declare function isPreviewableImage(file: {
+  name: string;
+  type?: string;
+}): boolean;
+//#endregion
+//#region src/core/format.d.ts
+/**
+ * `25 * 1024 * 1024` → `"25 MB"`. Uses 1024-based units so limits written the
+ * usual way (`n * 1024 * 1024`) read back exactly as configured.
+ */
+declare function formatBytes(bytes: number, fractionDigits?: number): string;
+declare function formatSpeed(bytesPerSecond: number): string;
+/** `5` → `"5 seconds"`, `90` → `"2 minutes"`, `3900` → `"1 hour"` */
+declare function formatDuration(seconds: number): string;
+declare function formatPercent(fraction: number): string;
+declare function clamp01(value: number): number;
+//#endregion
+//#region src/core/preset-catalog.d.ts
+/**
+ * Plain-data descriptions of the built-in presets. No React here, so this is
+ * importable from servers (docs pages, sitemaps, CMS schemas) via
+ * `upload-motion/core`. The React entry attaches a Component to each entry.
+ */
+type PresetId = 'card-fan' | 'wave-bar' | 'hoop-shot' | 'essential' | 'magnetic' | 'portal' | 'liquid' | 'segment-ring' | 'stack' | 'orbit' | 'bloom' | 'page-reveal' | 'filmstrip' | 'waveform' | 'pixel' | 'beam' | 'adaptive';
+type PresetCategory = 'reference' | 'professional' | 'expressive' | 'media';
+interface PresetInfo {
+  id: PresetId;
+  name: string;
+  description: string;
+  category: PresetCategory;
+  /** Short list of use cases, shown in docs and galleries. */
+  bestFor: readonly string[];
+  /** Options the preset defaults to (user props still win). */
+  defaults?: {
+    autoUpload?: boolean;
+    progressVariant?: 'bar' | 'ring' | 'wave' | 'beam';
+    layout?: 'list' | 'grid';
+  };
+}
+declare const PRESET_INFO: {
+  'card-fan': {
+    id: "card-fan";
+    name: string;
+    description: string;
+    category: "reference";
+    bestFor: string[];
+    defaults: {
+      autoUpload: false;
+    };
+  };
+  'wave-bar': {
+    id: "wave-bar";
+    name: string;
+    description: string;
+    category: "reference";
+    bestFor: string[];
+    defaults: {
+      progressVariant: "wave";
+    };
+  };
+  'hoop-shot': {
+    id: "hoop-shot";
+    name: string;
+    description: string;
+    category: "reference";
+    bestFor: string[];
+    defaults: {
+      autoUpload: false;
+    };
+  };
+  essential: {
+    id: "essential";
+    name: string;
+    description: string;
+    category: "professional";
+    bestFor: string[];
+  };
+  'segment-ring': {
+    id: "segment-ring";
+    name: string;
+    description: string;
+    category: "professional";
+    bestFor: string[];
+    defaults: {
+      progressVariant: "ring";
+    };
+  };
+  beam: {
+    id: "beam";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+    defaults: {
+      progressVariant: "beam";
+    };
+  };
+  magnetic: {
+    id: "magnetic";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+  };
+  portal: {
+    id: "portal";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+  };
+  liquid: {
+    id: "liquid";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+  };
+  stack: {
+    id: "stack";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+  };
+  orbit: {
+    id: "orbit";
+    name: string;
+    description: string;
+    category: "expressive";
+    bestFor: string[];
+  };
+  bloom: {
+    id: "bloom";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+  'page-reveal': {
+    id: "page-reveal";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+  filmstrip: {
+    id: "filmstrip";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+  waveform: {
+    id: "waveform";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+  pixel: {
+    id: "pixel";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+  adaptive: {
+    id: "adaptive";
+    name: string;
+    description: string;
+    category: "media";
+    bestFor: string[];
+  };
+};
+/** Built-in presets in gallery order. */
+declare const presetCatalog: readonly PresetInfo[];
+//#endregion
+export { FileRejection as A, UploadTotals as B, AddFilesResult as C, ClearFilter as D, createUploadStore as E, UploadEventMap as F, isUploadError as G, UploadError as H, UploadHandler as I, toUploadError as K, UploadItem as L, RejectionReason as M, RetryOptions as N, CustomValidator as O, UploadContext as P, UploadSnapshot as R, createXhrUploader as S, computeTotals as T, UploadErrorCode as U, UploaderOptions as V, httpErrorMessage as W, parseAccept as _, presetCatalog as a, XhrUploaderOptions as b, formatDuration as c, getExtension as d, getFileKind as f, isFileAccepted as g, describeAccept as h, PresetInfo as i, RejectionCode as j, FileKind as k, formatPercent as l, isPreviewableImage as m, PresetCategory as n, clamp01 as o, getFileLabel as p, PresetId as r, formatBytes as s, PRESET_INFO as t, formatSpeed as u, validateFile as v, UploadStore as w, createSimulatedUploader as x, SimulatedUploaderOptions as y, UploadStatus as z };