gbs-add-block 1.2.11 → 1.2.13

package/source/beta-components/fileuploader/core/store.ts

@@ -0,0 +1,432 @@
+import { abortError, isRetryable, UploadHttpError } from "./transport";
+import type {
+  FileRejection,
+  Transport,
+  UploaderSnapshot,
+  UploadItem,
+  UploadStatus,
+} from "./types";
+import { partitionFiles, type ValidationRules } from "./validate";
+
+/** 5 MiB: small enough to retry cheaply, large enough to keep request overhead low. */
+export const DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
+export const DEFAULT_CONCURRENCY = 3;
+export const DEFAULT_RETRIES = 3;
+export const DEFAULT_RETRY_DELAY = 1000;
+
+export interface UploaderConfig extends ValidationRules {
+  /** Sends the chunks. Without one, files can be selected but not uploaded. */
+  transport?: Transport;
+  /** Bytes per request. Default 5 MiB. */
+  chunkSize?: number;
+  /** Files uploading at the same time. Chunks of one file go one after another. Default 3. */
+  concurrency?: number;
+  /** Extra attempts per chunk after a retryable failure. Default 3. */
+  retries?: number;
+  /** First retry delay in ms; doubles on each attempt. Default 1000. */
+  retryDelay?: number;
+  /** Start uploading as soon as files are added. */
+  autoUpload?: boolean;
+  /** The selected files changed (added, removed, cleared). */
+  onChange?(files: File[]): void;
+  onRejected?(rejections: FileRejection[]): void;
+  onFileSuccess?(item: UploadItem): void;
+  onFileError?(item: UploadItem, error: unknown): void;
+  /** Every file started by one `upload()` call has finished, failed, paused or been canceled. */
+  onComplete?(items: UploadItem[]): void;
+}
+
+export interface AddResult {
+  accepted: UploadItem[];
+  rejected: FileRejection[];
+}
+
+export interface UploaderStore {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): UploaderSnapshot;
+  getServerSnapshot(): UploaderSnapshot;
+  addFiles(files: Iterable<File> | ArrayLike<File>): AddResult;
+  remove(id: string): void;
+  clear(): void;
+  /**
+   * Starts (or resumes, or retries) the given files, or every file that isn't
+   * uploaded yet. Resolves once they have all stopped.
+   */
+  upload(ids?: readonly string[]): Promise<UploadItem[]>;
+  /** Stops after aborting the chunk in flight; `upload()` continues from that chunk. */
+  pause(id?: string): void;
+  /** Stops and forgets progress; `upload()` starts again from the beginning. */
+  cancel(id?: string): void;
+  dismissRejection(id?: string): void;
+  configure(config: UploaderConfig): void;
+}
+
+type StopReason = "pause" | "cancel" | "remove";
+
+interface Running {
+  controller: AbortController;
+  reason?: StopReason;
+}
+
+const EMPTY: UploaderSnapshot = { items: [], rejections: [] };
+const IN_FLIGHT: ReadonlySet<UploadStatus> = new Set(["queued", "uploading"]);
+const STARTABLE: ReadonlySet<UploadStatus> = new Set(["idle", "paused", "error", "canceled"]);
+const NO_TRANSPORT = "Set an endpoint or a transport to upload files.";
+
+let sequence = 0;
+
+/** `crypto.randomUUID` exists only on HTTPS and localhost, so plain-HTTP intranet pages fall back. */
+export function createUploadId(): string {
+  return (
+    globalThis.crypto?.randomUUID?.() ??
+    `${Date.now().toString(36)}-${(sequence++).toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  );
+}
+
+export const chunkCount = (size: number, chunkSize: number) =>
+  Math.max(1, Math.ceil(size / chunkSize));
+
+function sleep(ms: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortError());
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError());
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof UploadHttpError) return error.message;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/** Totals across all items, for an overall progress bar. */
+export function summarize(items: readonly UploadItem[]) {
+  let totalBytes = 0;
+  let uploadedBytes = 0;
+  const counts: Record<UploadStatus, number> = {
+    idle: 0,
+    queued: 0,
+    uploading: 0,
+    paused: 0,
+    success: 0,
+    error: 0,
+    canceled: 0,
+  };
+  for (const item of items) {
+    totalBytes += item.file.size;
+    uploadedBytes += item.uploadedBytes;
+    counts[item.status]++;
+  }
+  return {
+    totalBytes,
+    uploadedBytes,
+    progress: totalBytes > 0 ? uploadedBytes / totalBytes : counts.success > 0 ? 1 : 0,
+    counts,
+    /** Something is queued or uploading. */
+    busy: counts.queued + counts.uploading > 0,
+    /** Files `upload()` would start. */
+    startable: counts.idle + counts.paused + counts.error + counts.canceled,
+  };
+}
+
+/**
+ * Selection, validation and chunked uploading, with no React. Snapshots are
+ * immutable, so the store plugs straight into `useSyncExternalStore`. Progress
+ * is published at most once per whole percent per file, so a fast connection
+ * doesn't flood the UI with renders.
+ */
+export function createUploaderStore(initial: UploaderConfig = {}): UploaderStore {
+  let config: UploaderConfig = { ...initial };
+  let snapshot: UploaderSnapshot = EMPTY;
+  let running = 0;
+  const listeners = new Set<() => void>();
+  const controllers = new Map<string, Running>();
+  const waiters: { ids: ReadonlySet<string>; resolve(items: UploadItem[]): void }[] = [];
+
+  const find = (id: string) => snapshot.items.find((item) => item.id === id);
+  const selectedFiles = () => snapshot.items.map((item) => item.file);
+
+  function commit(next: UploaderSnapshot) {
+    snapshot = next;
+    for (let i = waiters.length - 1; i >= 0; i--) {
+      const { ids, resolve } = waiters[i];
+      const items = snapshot.items.filter((item) => ids.has(item.id));
+      if (items.some((item) => IN_FLIGHT.has(item.status))) continue;
+      waiters.splice(i, 1);
+      resolve(items);
+    }
+    for (const listener of listeners) listener();
+  }
+
+  function patch(id: string, changes: Partial<UploadItem>) {
+    if (!find(id)) return;
+    commit({
+      ...snapshot,
+      items: snapshot.items.map((item) => (item.id === id ? { ...item, ...changes } : item)),
+    });
+  }
+
+  /** Aborts the request in flight. Returns false when nothing was running. */
+  function stop(id: string, reason: StopReason): boolean {
+    const entry = controllers.get(id);
+    if (!entry) return false;
+    entry.reason = reason;
+    entry.controller.abort();
+    return true;
+  }
+
+  async function withRetries<T>(send: () => Promise<T>, signal: AbortSignal): Promise<T> {
+    const retries = Math.max(0, config.retries ?? DEFAULT_RETRIES);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await send();
+      } catch (error) {
+        if (signal.aborted || attempt >= retries || !isRetryable(error)) throw error;
+        await sleep((config.retryDelay ?? DEFAULT_RETRY_DELAY) * 2 ** attempt, signal);
+      }
+    }
+  }
+
+  async function run(id: string) {
+    const item = find(id);
+    if (!item || item.status !== "queued") return;
+    const transport = config.transport;
+    if (!transport) {
+      patch(id, { status: "error", error: NO_TRANSPORT });
+      return;
+    }
+
+    const entry: Running = { controller: new AbortController() };
+    controllers.set(id, entry);
+    const { signal } = entry.controller;
+
+    // A resumed upload keeps its original chunk size, so indexes still line up on the server.
+    const fresh = item.chunksDone === 0;
+    const chunkSize = fresh ? Math.max(1, config.chunkSize ?? DEFAULT_CHUNK_SIZE) : item.chunkSize;
+    const total = fresh ? chunkCount(item.file.size, chunkSize) : item.totalChunks;
+    const { file, uploadId } = item;
+    const ratio = (bytes: number) => (file.size > 0 ? bytes / file.size : 1);
+    patch(id, { status: "uploading", chunkSize, totalChunks: total });
+
+    let percent = Math.floor(item.progress * 100);
+    const report = (bytes: number) => {
+      const next = Math.floor(ratio(bytes) * 100);
+      if (signal.aborted || next === percent) return;
+      percent = next;
+      patch(id, { uploadedBytes: bytes, progress: ratio(bytes) });
+    };
+
+    try {
+      for (let index = item.chunksDone; index < total; index++) {
+        const offset = index * chunkSize;
+        const end = Math.min(file.size, offset + chunkSize);
+        const chunk = file.slice(offset, end);
+        const response = await withRetries(
+          () =>
+            transport({
+              file,
+              chunk,
+              index,
+              total,
+              offset,
+              uploadId,
+              signal,
+              onProgress: (loaded) => report(offset + Math.min(loaded, chunk.size)),
+            }),
+          signal,
+        );
+        percent = Math.floor(ratio(end) * 100);
+        patch(id, { chunksDone: index + 1, uploadedBytes: end, progress: ratio(end), response });
+      }
+      patch(id, { status: "success", uploadedBytes: file.size, progress: 1 });
+      const done = find(id);
+      if (done) config.onFileSuccess?.(done);
+    } catch (error) {
+      const current = find(id);
+      if (!current || entry.reason === "remove") return;
+      const confirmed = Math.min(file.size, current.chunksDone * chunkSize);
+
+      if (entry.reason === "pause") {
+        patch(id, { status: "paused", uploadedBytes: confirmed, progress: ratio(confirmed) });
+      } else if (entry.reason === "cancel") {
+        patch(id, { status: "canceled", uploadedBytes: 0, progress: 0, chunksDone: 0 });
+      } else {
+        patch(id, {
+          status: "error",
+          error: describeError(error),
+          uploadedBytes: confirmed,
+          progress: ratio(confirmed),
+        });
+        const failed = find(id);
+        if (failed) config.onFileError?.(failed, error);
+      }
+    } finally {
+      if (controllers.get(id) === entry) controllers.delete(id);
+    }
+  }
+
+  function pump() {
+    const limit = Math.max(1, config.concurrency ?? DEFAULT_CONCURRENCY);
+    while (running < limit) {
+      const next = snapshot.items.find((item) => item.status === "queued");
+      if (!next) return;
+      running++;
+      // `run` marks the item as uploading before its first await, so the loop moves on.
+      void run(next.id).finally(() => {
+        running--;
+        pump();
+      });
+    }
+  }
+
+  function upload(ids?: readonly string[]): Promise<UploadItem[]> {
+    const wanted = ids ? new Set(ids) : undefined;
+    const tracked = snapshot.items.filter(
+      (item) =>
+        (!wanted || wanted.has(item.id)) &&
+        (STARTABLE.has(item.status) || IN_FLIGHT.has(item.status)),
+    );
+    const starting = new Set(
+      tracked.filter((item) => STARTABLE.has(item.status)).map((item) => item.id),
+    );
+    if (tracked.length === 0) return Promise.resolve([]);
+
+    const done = new Promise<UploadItem[]>((resolve) =>
+      waiters.push({ ids: new Set(tracked.map((item) => item.id)), resolve }),
+    );
+
+    const hasTransport = config.transport !== undefined;
+    commit({
+      ...snapshot,
+      items: snapshot.items.map((item): UploadItem => {
+        if (!starting.has(item.id)) return item;
+        if (!hasTransport) return { ...item, status: "error", error: NO_TRANSPORT };
+        return item.status === "canceled"
+          ? {
+              ...item,
+              status: "queued",
+              error: undefined,
+              uploadId: createUploadId(),
+              uploadedBytes: 0,
+              progress: 0,
+              chunksDone: 0,
+            }
+          : { ...item, status: "queued", error: undefined };
+      }),
+    });
+    pump();
+
+    if (starting.size > 0) void done.then((items) => config.onComplete?.(items));
+    return done;
+  }
+
+  function addFiles(input: Iterable<File> | ArrayLike<File>): AddResult {
+    const current = snapshot.items;
+    const { accepted, rejected } = partitionFiles(
+      Array.from(input),
+      current.map((item) => item.file),
+      config,
+    );
+    const chunkSize = Math.max(1, config.chunkSize ?? DEFAULT_CHUNK_SIZE);
+    const added: UploadItem[] = accepted.map((file) => ({
+      id: createUploadId(),
+      uploadId: createUploadId(),
+      file,
+      status: "idle",
+      uploadedBytes: 0,
+      progress: 0,
+      chunkSize,
+      chunksDone: 0,
+      totalChunks: chunkCount(file.size, chunkSize),
+    }));
+    const rejections: FileRejection[] = rejected.map((entry) => ({
+      ...entry,
+      id: createUploadId(),
+    }));
+    if (added.length === 0 && rejections.length === 0) return { accepted: [], rejected: [] };
+
+    const replace = !(config.multiple ?? false) && added.length > 0;
+    if (replace) for (const item of current) stop(item.id, "remove");
+
+    commit({ items: replace ? added : [...current, ...added], rejections });
+    if (added.length > 0) config.onChange?.(selectedFiles());
+    if (rejections.length > 0) config.onRejected?.(rejections);
+    if (added.length > 0 && config.autoUpload && config.transport) {
+      void upload(added.map((item) => item.id));
+    }
+    return { accepted: added, rejected: rejections };
+  }
+
+  function remove(id: string) {
+    if (!find(id)) return;
+    stop(id, "remove");
+    commit({ ...snapshot, items: snapshot.items.filter((item) => item.id !== id) });
+    config.onChange?.(selectedFiles());
+  }
+
+  function clear() {
+    if (snapshot.items.length === 0 && snapshot.rejections.length === 0) return;
+    const hadItems = snapshot.items.length > 0;
+    for (const item of snapshot.items) stop(item.id, "remove");
+    commit(EMPTY);
+    if (hadItems) config.onChange?.([]);
+  }
+
+  function pause(id?: string) {
+    for (const item of snapshot.items) {
+      if ((id !== undefined && item.id !== id) || !IN_FLIGHT.has(item.status)) continue;
+      if (!stop(item.id, "pause")) patch(item.id, { status: "paused" });
+    }
+  }
+
+  function cancel(id?: string) {
+    for (const item of snapshot.items) {
+      if (id !== undefined && item.id !== id) continue;
+      if (item.status === "idle" || item.status === "success" || item.status === "canceled") {
+        continue;
+      }
+      if (!stop(item.id, "cancel")) {
+        patch(item.id, { status: "canceled", uploadedBytes: 0, progress: 0, chunksDone: 0 });
+      }
+    }
+  }
+
+  function dismissRejection(id?: string) {
+    const rejections =
+      id === undefined ? [] : snapshot.rejections.filter((rejection) => rejection.id !== id);
+    if (rejections.length !== snapshot.rejections.length) commit({ ...snapshot, rejections });
+  }
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => snapshot,
+    getServerSnapshot: () => EMPTY,
+    addFiles,
+    remove,
+    clear,
+    upload,
+    pause,
+    cancel,
+    dismissRejection,
+    configure(next) {
+      config = { ...config, ...next };
+      pump();
+    },
+  };
+}

package/source/beta-components/fileuploader/core/transport.ts

@@ -0,0 +1,145 @@
+import type { ChunkRequest, Transport } from "./types";
+
+/** Form field names for each chunk request. The defaults match the Go chunk-uploader. */
+export interface ChunkFieldNames {
+  chunk: string;
+  fileName: string;
+  chunkIndex: string;
+  totalChunks: string;
+  fileSize: string;
+  uploadId: string;
+  additionalParams: string;
+}
+
+export const DEFAULT_FIELD_NAMES: ChunkFieldNames = {
+  chunk: "chunk",
+  fileName: "fileName",
+  chunkIndex: "chunkIndex",
+  totalChunks: "totalChunks",
+  fileSize: "fileSize",
+  uploadId: "uploadId",
+  additionalParams: "additionalParams",
+};
+
+export type UploadParams = Record<string, unknown>;
+
+export interface HttpTransportOptions {
+  endpoint: string | ((request: ChunkRequest) => string);
+  method?: "POST" | "PUT" | "PATCH";
+  /** Static headers, or a function (async allowed) for tokens that expire. */
+  headers?:
+    | Record<string, string>
+    | ((request: ChunkRequest) => Record<string, string> | Promise<Record<string, string>>);
+  /** Send cookies on cross-origin requests. */
+  withCredentials?: boolean;
+  fieldNames?: Partial<ChunkFieldNames>;
+  /** Extra data sent as JSON in the `additionalParams` field. */
+  params?: UploadParams | ((file: File) => UploadParams);
+  /** Turns the response text into the value stored on the item. Default: JSON, else text. */
+  parseResponse?(body: string, xhr: XMLHttpRequest): unknown;
+}
+
+/** A non-2xx response. `body` is the parsed response. */
+export class UploadHttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, body: unknown) {
+    super(`Upload failed with status ${status}`);
+    this.name = "UploadHttpError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export const abortError = () => new DOMException("Upload aborted", "AbortError");
+
+/** Network failures, timeouts, rate limits and server errors are worth another try; 4xx is not. */
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof DOMException && error.name === "AbortError") return false;
+  if (error instanceof UploadHttpError) {
+    return error.status >= 500 || error.status === 408 || error.status === 429;
+  }
+  return true;
+}
+
+/** The multipart body for one chunk. Metadata comes first so streaming parsers see it before the bytes. */
+export function buildChunkForm(
+  request: ChunkRequest,
+  options: Pick<HttpTransportOptions, "fieldNames" | "params"> = {},
+): FormData {
+  const names = { ...DEFAULT_FIELD_NAMES, ...options.fieldNames };
+  const form = new FormData();
+  form.append(names.uploadId, request.uploadId);
+  form.append(names.fileName, request.file.name);
+  form.append(names.chunkIndex, String(request.index));
+  form.append(names.totalChunks, String(request.total));
+  form.append(names.fileSize, String(request.file.size));
+
+  const params =
+    typeof options.params === "function" ? options.params(request.file) : options.params;
+  if (params && Object.keys(params).length > 0) {
+    form.append(names.additionalParams, JSON.stringify(params));
+  }
+
+  form.append(names.chunk, request.chunk, request.file.name);
+  return form;
+}
+
+function parseBody(text: string): unknown {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Sends each chunk as `multipart/form-data`. Uses XMLHttpRequest rather than
+ * fetch because fetch still can't report upload progress in every browser.
+ */
+export function createHttpTransport(options: HttpTransportOptions): Transport {
+  return async (request) => {
+    const url =
+      typeof options.endpoint === "function" ? options.endpoint(request) : options.endpoint;
+    const headers =
+      typeof options.headers === "function" ? await options.headers(request) : options.headers;
+    const body = buildChunkForm(request, options);
+
+    return new Promise((resolve, reject) => {
+      const { signal } = request;
+      if (signal.aborted) {
+        reject(abortError());
+        return;
+      }
+
+      const xhr = new XMLHttpRequest();
+      const onAbort = () => xhr.abort();
+
+      xhr.open(options.method ?? "POST", url);
+      xhr.withCredentials = options.withCredentials ?? false;
+      for (const [name, value] of Object.entries(headers ?? {})) {
+        xhr.setRequestHeader(name, value);
+      }
+
+      // `loaded` includes the multipart framing, so cap it at the chunk's size.
+      xhr.upload.onprogress = (event) =>
+        request.onProgress(Math.min(event.loaded, request.chunk.size));
+      xhr.onload = () => {
+        const parsed = options.parseResponse
+          ? options.parseResponse(xhr.responseText, xhr)
+          : parseBody(xhr.responseText);
+        if (xhr.status >= 200 && xhr.status < 300) resolve(parsed);
+        else reject(new UploadHttpError(xhr.status, parsed));
+      };
+      xhr.onerror = () => reject(new Error("Network error"));
+      xhr.ontimeout = () => reject(new Error("Request timed out"));
+      xhr.onabort = () => reject(abortError());
+      xhr.onloadend = () => signal.removeEventListener("abort", onAbort);
+
+      signal.addEventListener("abort", onAbort, { once: true });
+      xhr.send(body);
+    });
+  };
+}

package/source/beta-components/fileuploader/core/types.ts

@@ -0,0 +1,126 @@
+export type UploadStatus =
+  /** Selected, not sent yet. */
+  | "idle"
+  /** Waiting for a free upload slot. */
+  | "queued"
+  | "uploading"
+  | "paused"
+  | "success"
+  | "error"
+  | "canceled";
+
+export interface UploadItem {
+  /** Stable key for the row. */
+  id: string;
+  /**
+   * Sent with every chunk so the server can group them. Resuming after a pause
+   * or an error keeps it; starting again after a cancel gets a new one.
+   */
+  uploadId: string;
+  file: File;
+  status: UploadStatus;
+  /** Bytes confirmed by the server plus the bytes of the chunk in flight. */
+  uploadedBytes: number;
+  /** 0 to 1. */
+  progress: number;
+  chunkSize: number;
+  chunksDone: number;
+  totalChunks: number;
+  error?: string;
+  /** The server's answer to the most recent chunk; for the last chunk, the finished file. */
+  response?: unknown;
+}
+
+export type RejectionCode =
+  | "file-type"
+  | "file-too-large"
+  | "file-too-small"
+  | "too-many-files"
+  | "duplicate"
+  | "custom";
+
+export interface FileRejection {
+  id: string;
+  file: File;
+  code: RejectionCode;
+  /** Set for `custom`: the text returned by `validate`. */
+  message?: string;
+}
+
+export interface UploaderSnapshot {
+  items: readonly UploadItem[];
+  /** From the most recent selection; replaced by the next one. */
+  rejections: readonly FileRejection[];
+}
+
+/** One chunk, as handed to a transport. */
+export interface ChunkRequest {
+  file: File;
+  chunk: Blob;
+  /** 0-based. */
+  index: number;
+  total: number;
+  /** Byte position of this chunk in the file. */
+  offset: number;
+  uploadId: string;
+  signal: AbortSignal;
+  /** Report bytes of this chunk sent so far. */
+  onProgress(loaded: number): void;
+}
+
+/** Sends one chunk and resolves with the server's answer. Throw to fail it. */
+export type Transport = (request: ChunkRequest) => Promise<unknown>;
+
+/** A file already on the server, e.g. when editing a saved record. */
+export interface ExistingFile {
+  id: string;
+  name: string;
+  size?: number;
+  type?: string;
+  /** Download link; also the preview for images. */
+  url?: string;
+}
+
+export type FileKind =
+  | "image"
+  | "video"
+  | "audio"
+  | "pdf"
+  | "spreadsheet"
+  | "document"
+  | "archive"
+  | "other";
+
+export type UploaderSize = "sm" | "md" | "lg";
+
+export interface UploaderLocaleText {
+  dropzone: string;
+  browse: string;
+  dropHere: string;
+  hintTypes(types: string): string;
+  hintMaxSize(size: string): string;
+  hintMaxFiles(count: string): string;
+  upload(count: string): string;
+  cancelAll: string;
+  clear: string;
+  dismiss: string;
+  remove(name: string): string;
+  cancel(name: string): string;
+  pause(name: string): string;
+  resume(name: string): string;
+  retry(name: string): string;
+  download(name: string): string;
+  queued: string;
+  paused: string;
+  uploaded: string;
+  canceled: string;
+  failed: string;
+  progress(sent: string, total: string, percent: string): string;
+  rejectFileType(name: string): string;
+  rejectTooLarge(name: string, max: string): string;
+  rejectTooSmall(name: string, min: string): string;
+  rejectTooMany(max: string): string;
+  rejectDuplicate(name: string): string;
+  announceDone(name: string): string;
+  announceFailed(name: string): string;
+}