@sehv-oss/basketball-upload 1.0.0

package/dist/basketball-upload.d.ts

@@ -0,0 +1,567 @@
+//#region src/file-types/types.d.ts
+/**
+ * What the body of a file card shows:
+ * - `lines`: the paper with grey text lines of the design.
+ * - `thumbnail`: a preview of the file itself (images), falling back to `lines`.
+ * - a function: any node you build, placed in the `file-artwork` part.
+ */
+type FileArtwork = 'lines' | 'thumbnail' | ((file: File) => Node);
+/**
+ * How files of one type look on the court and in the upload list.
+ */
+interface FileType {
+  /**
+   * Stable id: lowercase letters, digits and dashes, starting with a letter.
+   * Becomes the `data-kind` attribute, the parts `file-<kind>` and
+   * `item-icon-<kind>`, and the token `--basketball-upload-file-<kind>`.
+   */
+  readonly kind: string;
+  /**
+   * `accept` syntax (`.pdf`, `application/pdf`, `image/*`, comma separated), or a predicate.
+   */
+  readonly match: string | ((file: File) => boolean);
+  /**
+   * Badge text. Defaults to the extension in capitals, at most 4 characters.
+   */
+  readonly label?: string | ((file: File) => string) | undefined;
+  /**
+   * Badge color: any CSS color, `light-dark()` included.
+   */
+  readonly color?: string | undefined;
+  /**
+   * Defaults to `lines`.
+   */
+  readonly artwork?: FileArtwork | undefined;
+}
+/**
+ * A file type applied to one file, as `resolveFileType` returns it: every
+ * default filled in.
+ */
+interface ResolvedFileType {
+  /**
+   * `kind` of the matching type, or `file` when none matched.
+   */
+  readonly kind: string;
+  /**
+   * Badge text for this file.
+   */
+  readonly label: string;
+  /**
+   * `null` uses the neutral `--basketball-upload-file-badge` token.
+   */
+  readonly color: string | null;
+  /**
+   * What the body of the card shows.
+   */
+  readonly artwork: FileArtwork;
+}
+//#endregion
+//#region src/upload/types.d.ts
+/**
+ * - `ready`: accepted without an uploader; the file only travels with its form.
+ * - `queued`: waiting for a free upload slot.
+ * - `uploading` / `uploaded` / `error`: the uploader's progress and outcome.
+ */
+type UploadStatus = 'ready' | 'queued' | 'uploading' | 'uploaded' | 'error';
+/**
+ * A file in the basket and its upload. Items are immutable: every change
+ * replaces the item with a new one, under the same `id`.
+ */
+interface UploadItem {
+  /**
+   * Unique within the element, for `retryItem()` and `removeItem()`.
+   */
+  readonly id: string;
+  readonly file: File;
+  readonly status: UploadStatus;
+  /**
+   * From 0 to 1.
+   */
+  readonly progress: number;
+  /**
+   * Whatever the uploader resolved with.
+   */
+  readonly response: unknown;
+  /**
+   * Whatever the uploader rejected with.
+   */
+  readonly error: unknown;
+}
+/**
+ * Second argument of an `Uploader`.
+ */
+interface UploadContext {
+  /**
+   * Aborted when the item is removed or the queue is cleared.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * `total` defaults to the size of the file.
+   */
+  readonly onProgress: (loaded: number, total?: number) => void;
+}
+/**
+ * Sends one file. Resolve when it is stored, reject when it failed.
+ */
+type Uploader = (file: File, context: UploadContext) => Promise<unknown>;
+//#endregion
+//#region src/element/messages.d.ts
+/**
+ * Why a file was turned away:
+ * - `type`: it does not match `accept`.
+ * - `size`: it is larger than `max-size`.
+ * - `count`: it is one file more than `max-files` allows, or than one without
+ *   `multiple`.
+ */
+type RejectReason = 'type' | 'size' | 'count';
+/**
+ * Visible copy and accessible names. The defaults are the copy of the
+ * reference design; override any of them with the `messages` property, or the
+ * first four with slots.
+ */
+interface Messages {
+  /**
+   * Heading of the element. The `title` slot replaces it.
+   */
+  title: string;
+  /**
+   * Line under the heading. The `description` slot replaces it.
+   */
+  description: string;
+  /**
+   * Main text of the dropzone. The `prompt` slot replaces it.
+   */
+  prompt: string;
+  /**
+   * Text under the prompt. The `hint` slot replaces it.
+   */
+  hint: string;
+  /**
+   * Accessible name of the dropzone button.
+   */
+  dropzone: string;
+  /**
+   * Label of the pill that counts the files in the basket.
+   */
+  counter: string;
+  /**
+   * Accessible name of a card waiting on the court.
+   */
+  shoot: (name: string) => string;
+  /**
+   * Status of a file in the basket when there is no uploader.
+   */
+  ready: string;
+  /**
+   * Status of a file waiting for a free upload slot.
+   */
+  queued: string;
+  /**
+   * Status of a file being uploaded.
+   */
+  uploading: string;
+  /**
+   * Status of a file the uploader stored.
+   */
+  uploaded: string;
+  /**
+   * Status of a file whose upload failed.
+   */
+  failed: string;
+  /**
+   * Accessible name and tooltip of the retry button of a row.
+   */
+  retry: (name: string) => string;
+  /**
+   * Accessible name of the progress bar of a row.
+   */
+  progress: (name: string) => string;
+  /**
+   * Validation message when `required` and empty.
+   */
+  required: string;
+  /**
+   * Announced when a file goes through the net.
+   */
+  scored: (name: string) => string;
+  /**
+   * Announced when a shot misses.
+   */
+  missed: (name: string) => string;
+  /**
+   * Announced when a file is turned away.
+   */
+  rejected: (name: string, reason: RejectReason) => string;
+  /**
+   * Announced when an upload succeeds.
+   */
+  complete: (name: string) => string;
+  /**
+   * Announced when an upload fails.
+   */
+  error: (name: string) => string;
+}
+/**
+ * The copy of the reference design, in English.
+ */
+export declare const defaultMessages: Messages;
+//#endregion
+//#region src/element/basketball-upload-element.d.ts
+/**
+ * Color scheme of the element. `system` follows `prefers-color-scheme`.
+ */
+type Theme = 'light' | 'dark' | 'system';
+/**
+ * How a shot ended: through the net (a dunk included), or back on the court.
+ */
+type ShotResult = 'score' | 'miss';
+/**
+ * `CustomEvent`s dispatched by `<basketball-upload>`, keyed by event name. They bubble.
+ */
+interface BasketballUploadEventMap {
+  /**
+   * A file did not pass `accept`, `max-size` or `max-files`, and stays out.
+   */
+  'file-reject': CustomEvent<{
+    file: File;
+    reason: RejectReason;
+  }>;
+  /**
+   * A card went through the net, dunks included, or a shot missed and the
+   * card is back on the court.
+   */
+  shot: CustomEvent<{
+    file: File;
+    result: ShotResult;
+  }>;
+  /**
+   * The uploader was called for an item.
+   */
+  'upload-start': CustomEvent<{
+    item: UploadItem;
+  }>;
+  /**
+   * The uploader reported progress; `item.progress` has the new value.
+   */
+  'upload-progress': CustomEvent<{
+    item: UploadItem;
+  }>;
+  /**
+   * An upload resolved; `item.response` has its value.
+   */
+  'upload-success': CustomEvent<{
+    item: UploadItem;
+  }>;
+  /**
+   * An upload rejected; `item.error` has the reason. Aborted uploads (removed
+   * items, `clear()`) do not fire it.
+   */
+  'upload-error': CustomEvent<{
+    item: UploadItem;
+  }>;
+  /**
+   * Files entered or left the basket, or one changed status. Progress alone
+   * does not fire it: `upload-progress` does.
+   */
+  change: CustomEvent<{
+    items: readonly UploadItem[];
+  }>;
+}
+/**
+ * `HTMLElement` is missing where there is no DOM (SSR). Extending a stand-in
+ * keeps this module importable there; the class is only ever instantiated by
+ * `customElements.define`, which those environments do not have either.
+ */
+declare const BaseElement: typeof HTMLElement;
+/**
+ * `<basketball-upload>`: a file upload where the dropzone is a backboard.
+ * Drop files on it, or drop them on the court and take the shot.
+ */
+export declare class BasketballUploadElement extends BaseElement {
+  #private;
+  static readonly formAssociated = true;
+  static readonly observedAttributes: readonly ['concurrency', 'disabled', 'name', 'required'];
+  constructor();
+  /**
+   * `light`, `dark`, or `system` (the default) to follow `prefers-color-scheme`.
+   */
+  get theme(): Theme;
+  set theme(value: Theme | null | undefined);
+  /**
+   * Accepted files, with the syntax of `<input type="file" accept>`.
+   */
+  get accept(): string;
+  set accept(value: string | null | undefined);
+  /**
+   * Several files at a time. Without it, a new file replaces the previous one.
+   */
+  get multiple(): boolean;
+  set multiple(value: boolean | null | undefined);
+  /**
+   * Largest accepted file, in bytes.
+   */
+  get maxSize(): number | null;
+  set maxSize(value: number | null | undefined);
+  /**
+   * Most files at once, staged and in the basket.
+   */
+  get maxFiles(): number | null;
+  set maxFiles(value: number | null | undefined);
+  /**
+   * Form field the files are submitted under.
+   */
+  get name(): string;
+  set name(value: string | null | undefined);
+  /**
+   * The form is invalid while the basket is empty.
+   */
+  get required(): boolean;
+  set required(value: boolean | null | undefined);
+  /**
+   * Ignores files and shots. A disabled `<fieldset>` does the same, without
+   * changing this property.
+   */
+  get disabled(): boolean;
+  set disabled(value: boolean | null | undefined);
+  /**
+   * No shooting: every file goes straight into the basket.
+   */
+  get instant(): boolean;
+  set instant(value: boolean | null | undefined);
+  /**
+   * Uploads running at the same time.
+   */
+  get concurrency(): number;
+  set concurrency(value: number | null | undefined);
+  /**
+   * Sends each file in the basket. Without one, files only travel with their form.
+   */
+  get uploader(): Uploader | null;
+  set uploader(value: Uploader | null | undefined);
+  /**
+   * Copy and accessible names. Assign a partial object to override some: it is
+   * merged over the defaults, not over the previous value, and keys set to
+   * `undefined` keep their default.
+   */
+  get messages(): Messages;
+  set messages(value: Partial<Messages> | null | undefined);
+  /**
+   * File types for this element only, checked before the registered ones.
+   */
+  get fileTypes(): readonly FileType[];
+  set fileTypes(value: readonly FileType[] | null | undefined);
+  /**
+   * Files in the basket and their uploads.
+   */
+  get items(): readonly UploadItem[];
+  /**
+   * Files in the basket: the value submitted with the form.
+   */
+  get files(): readonly File[];
+  /**
+   * The `<form>` the element belongs to, or `null`.
+   */
+  get form(): HTMLFormElement | null;
+  /**
+   * As on native controls: `valueMissing` while `required` and empty.
+   * `undefined` where `ElementInternals` is missing.
+   */
+  get validity(): ValidityState | undefined;
+  /**
+   * `messages.required` while `required` and empty, otherwise empty.
+   */
+  get validationMessage(): string;
+  /**
+   * Whether the form validates the element, as on native controls: not while
+   * disabled.
+   */
+  get willValidate(): boolean;
+  /**
+   * Whether the element is valid, firing `invalid` when it is not. Always
+   * valid where `ElementInternals` is missing.
+   */
+  checkValidity(): boolean;
+  /**
+   * Like `checkValidity()`, and shows the message on the dropzone when invalid.
+   */
+  reportValidity(): boolean;
+  /**
+   * Opens the file picker. The chosen files land on the court (or in the basket, with `instant`).
+   */
+  openPicker(): void;
+  /**
+   * Puts files on the court, ready to be shot (with `instant`, straight into
+   * the basket). Files that do not pass `accept`, `max-size` or `max-files`
+   * fire `file-reject` instead.
+   */
+  stage(files: Iterable<File>): void;
+  /**
+   * Puts files straight into the basket. Files that do not pass `accept`,
+   * `max-size` or `max-files` fire `file-reject` instead.
+   */
+  dunk(files: Iterable<File>): void;
+  /**
+   * Shoots the card on top of the court with a perfect shot. Returns `false`
+   * when it cannot: no card on the court, disabled, another card held or in
+   * the air, or the element not laid out.
+   */
+  shoot(): boolean;
+  /**
+   * Uploads a failed file again. Returns `false` when `id` is not an item in
+   * error, or there is no `uploader`.
+   */
+  retryItem(id: string): boolean;
+  /**
+   * Takes a file out of the basket, aborting its upload. Returns `false` when
+   * there is no item with this `id`.
+   */
+  removeItem(id: string): boolean;
+  /**
+   * Empties the court and the basket, aborting uploads.
+   */
+  clear(): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, _oldValue: string | null, value: string | null): void;
+  formResetCallback(): void;
+  formDisabledCallback(disabled: boolean): void;
+}
+export interface BasketballUploadElement {
+  /**
+   * Typed for the events of `BasketballUploadEventMap`.
+   */
+  addEventListener<TType extends keyof BasketballUploadEventMap>(type: TType, listener: (this: BasketballUploadElement, event: BasketballUploadEventMap[TType]) => void, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Any other event, as on `HTMLElement`.
+   */
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  /**
+   * Typed for the events of `BasketballUploadEventMap`.
+   */
+  removeEventListener<TType extends keyof BasketballUploadEventMap>(type: TType, listener: (this: BasketballUploadElement, event: BasketballUploadEventMap[TType]) => void, options?: boolean | EventListenerOptions): void;
+  /**
+   * Any other event, as on `HTMLElement`.
+   */
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'basketball-upload': BasketballUploadElement;
+  }
+}
+//#endregion
+//#region src/element/register.d.ts
+/**
+ * Options of `registerBasketballUpload`.
+ */
+interface RegisterBasketballUploadOptions {
+  /**
+   * Custom element name. Defaults to `basketball-upload`.
+   */
+  tagName?: string | undefined;
+}
+/**
+ * Name the element is registered with when no `tagName` is given.
+ */
+export declare const DEFAULT_TAG_NAME = "basketball-upload";
+/**
+ * Defines the custom element. Idempotent, and a no-op where custom elements
+ * do not exist (SSR), so it is safe to call from any module.
+ */
+export declare function registerBasketballUpload(options?: RegisterBasketballUploadOptions): void;
+//#endregion
+//#region src/file-types/defaults.d.ts
+/**
+ * Built-in file types, checked after the ones you register.
+ */
+export declare const defaultFileTypes: readonly FileType[];
+//#endregion
+//#region src/file-types/registry.d.ts
+/**
+ * Adds a file type for every `<basketball-upload>` on the page. It wins over the
+ * built-in types and over the ones registered before it; types set on an
+ * element (`fileTypes`) still win over it. Returns a function that removes it.
+ */
+export declare function registerFileType(type: FileType): () => void;
+/**
+ * The look of a file: the first match among `instanceTypes`, then the
+ * registered types, then the built-in ones, then a neutral `file`.
+ */
+export declare function resolveFileType(file: File, instanceTypes?: readonly FileType[]): ResolvedFileType;
+//#endregion
+//#region src/upload/accept.d.ts
+/**
+ * The parts of a `File` that `matchesAccept` reads.
+ */
+interface FileLike {
+  readonly name: string;
+  readonly type: string;
+}
+/**
+ * Whether a file matches an `accept` string, with the semantics of
+ * `<input type="file" accept>`: comma separated extensions (`.pdf`), MIME
+ * types (`application/pdf`) and wildcards (`image/*`). Empty accepts all.
+ */
+export declare function matchesAccept(file: FileLike, accept: string | null | undefined): boolean;
+//#endregion
+//#region src/upload/format.d.ts
+/**
+ * Human readable size in decimal units, the way file managers show it: `2_400_000` → `2.4 MB`.
+ * `locale` formats the number (`2,4 MB` in `de`); it defaults to the runtime's.
+ */
+export declare function formatBytes(bytes: number, locale?: string): string;
+//#endregion
+//#region src/upload/xhr.d.ts
+/**
+ * Options of `createXhrUploader`.
+ */
+interface XhrUploaderOptions {
+  /**
+   * Endpoint, or a function of the file for one URL per file.
+   */
+  url: string | URL | ((file: File) => string | URL);
+  /**
+   * Defaults to `POST`.
+   */
+  method?: string | undefined;
+  /**
+   * Form field the file is sent under, as `multipart/form-data`. Defaults to
+   * `file`. `null` sends the file itself as the request body.
+   */
+  fieldName?: string | null | undefined;
+  /**
+   * Extra form fields, sent before the file. Ignored when `fieldName` is `null`.
+   */
+  fields?: Record<string, string | Blob> | ((file: File) => Record<string, string | Blob>) | undefined;
+  /**
+   * Request headers, or a function of the file.
+   */
+  headers?: Record<string, string> | ((file: File) => Record<string, string>) | undefined;
+  /**
+   * Sends cookies with cross-origin requests. Defaults to `false`.
+   */
+  withCredentials?: boolean | undefined;
+}
+/**
+ * Rejection reason of `createXhrUploader` for a non-2xx response or a network error.
+ */
+export declare class UploadError extends Error {
+  /**
+   * HTTP status, or 0 when the request did not complete.
+   */
+  readonly status: number;
+  /**
+   * Response text, or an empty string when the request did not complete.
+   */
+  readonly body: string;
+  constructor(status: number, body: string);
+}
+/**
+ * An `Uploader` built on `XMLHttpRequest`, the one browser API that reports
+ * the progress of a request body. Resolves with the parsed JSON response (or
+ * its text), rejects with an `UploadError`, or with the abort reason.
+ */
+export declare function createXhrUploader(options: XhrUploaderOptions): Uploader;
+//#endregion
+export type { BasketballUploadEventMap, FileArtwork, FileType, Messages, RegisterBasketballUploadOptions, RejectReason, ResolvedFileType, ShotResult, Theme, UploadContext, UploadItem, UploadStatus, Uploader, XhrUploaderOptions };
+//# sourceMappingURL=basketball-upload.d.ts.map

package/dist/basketball-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basketball-upload.d.ts","names":[],"sources":["../src/file-types/types.ts","../src/upload/types.ts","../src/element/messages.ts","../src/element/basketball-upload-element.ts","../src/element/register.ts","../src/file-types/defaults.ts","../src/file-types/registry.ts","../src/upload/accept.ts","../src/upload/format.ts","../src/upload/xhr.ts"],"mappings":"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"}