@openwarelabs/ui 0.15.0 → 0.16.1

package/dist/components/TransferList/TransferList.d.ts

@@ -0,0 +1,7 @@
+import type { TransferListProps } from "./TransferList.types.js";
+export type { TransferListOption, TransferListProps } from "./TransferList.types.js";
+/**
+ * Two lists side by side, the available items and the chosen ones, with buttons between them that move the selected
+ * items across: permissions, the columns a table shows, a team's members. Double-click or Enter moves an item too.
+ */
+export declare const TransferList: import("react").ForwardRefExoticComponent<TransferListProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/TransferList/TransferList.types.d.cts

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+export interface TransferListOption {
+    /** What goes in the value when it's chosen. Unique among the options. */
+    value: string;
+    /** The text in the list, matched by the search and read out when it moves. */
+    label: string;
+    /** A muted line under the label; matched by the search when it's a string. */
+    description?: ReactNode;
+    /** Stays on its side: it can't be selected or moved. */
+    disabled?: boolean;
+    /** A heading to show it under. Options with the same group are listed together, groups in the order they first appear. */
+    group?: string;
+}
+/** One side of the transfer list. Internal. */
+export type TransferListSide = "source" | "target";
+export interface TransferListProps {
+    /** Everything that can be chosen. The available side lists them in this order. */
+    options: TransferListOption[];
+    /** The chosen values, in order, when you control them. */
+    value?: string[];
+    /** The chosen values at first, when it controls them itself.
+     * @default [] */
+    defaultValue?: string[];
+    /** Called with the chosen values when they move or are reordered. Moved values join the end. */
+    onChange?(value: string[]): void;
+    /** The heading over the available list, which also names it.
+     * @default "Available" */
+    sourceLabel?: string;
+    /** The heading over the chosen list, which also names it.
+     * @default "Selected" */
+    targetLabel?: string;
+    /** A search box over each list that filters it by label and description.
+     * @default false */
+    searchable?: boolean;
+    /** Adds buttons that move every item (that the search shows) from one side to the other.
+     * @default false */
+    showMoveAll?: boolean;
+    /** Adds Move up and Move down buttons under the chosen list (and Alt+Up/Down in it), for an order that matters.
+     * The chosen list is then shown without group headings, in the value's order.
+     * @default false */
+    orderable?: boolean;
+    /** Submits each chosen value under this name, in a hidden input, so a Form or a plain form sends them as a list. */
+    name?: string;
+    /** Fades both lists and the buttons, and takes them out of the tab order.
+     * @default false */
+    disabled?: boolean;
+    /** The lists' height, e.g. 320 or "40vh"; they scroll past it.
+     * @default 280 */
+    height?: number | string;
+    id?: string;
+    /** The words it uses, for other languages. `to` is the side's label. */
+    labels?: {
+        /** The count under each heading. @default (selected, total) => `${selected} of ${total} selected` */
+        count?(selected: number, total: number): string;
+        /** The button that moves the selected items. @default (count, to) => `Move 2 selected to ${to}`, or `Move selected to ${to}` with none */
+        moveSelected?(count: number, to: string): string;
+        /** The button that moves them all, with `showMoveAll`. @default (to) => `Move all to ${to}` */
+        moveAll?(to: string): string;
+        /** Read out after a move. @default (names, to) => `Moved Ada and Grace to ${to}`, or `Moved 7 items to ${to}` past five */
+        moved?(names: string[], to: string): string;
+        /** With `orderable`. @default "Move up" */
+        moveUp?: string;
+        /** With `orderable`. @default "Move down" */
+        moveDown?: string;
+        /** Read out after reordering. @default (names, direction) => `Moved Ada up` */
+        reordered?(names: string[], direction: "up" | "down"): string;
+        /** Names a side's search box. @default (side) => `Search ${side}` */
+        search?(side: string): string;
+        /** Shown in an empty list. @default "No items" */
+        empty?: ReactNode;
+        /** Shown when the search matches nothing. @default "No matches" */
+        noMatches?: ReactNode;
+    };
+    className?: string;
+}

package/dist/components/TransferList/TransferList.types.d.ts

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+export interface TransferListOption {
+    /** What goes in the value when it's chosen. Unique among the options. */
+    value: string;
+    /** The text in the list, matched by the search and read out when it moves. */
+    label: string;
+    /** A muted line under the label; matched by the search when it's a string. */
+    description?: ReactNode;
+    /** Stays on its side: it can't be selected or moved. */
+    disabled?: boolean;
+    /** A heading to show it under. Options with the same group are listed together, groups in the order they first appear. */
+    group?: string;
+}
+/** One side of the transfer list. Internal. */
+export type TransferListSide = "source" | "target";
+export interface TransferListProps {
+    /** Everything that can be chosen. The available side lists them in this order. */
+    options: TransferListOption[];
+    /** The chosen values, in order, when you control them. */
+    value?: string[];
+    /** The chosen values at first, when it controls them itself.
+     * @default [] */
+    defaultValue?: string[];
+    /** Called with the chosen values when they move or are reordered. Moved values join the end. */
+    onChange?(value: string[]): void;
+    /** The heading over the available list, which also names it.
+     * @default "Available" */
+    sourceLabel?: string;
+    /** The heading over the chosen list, which also names it.
+     * @default "Selected" */
+    targetLabel?: string;
+    /** A search box over each list that filters it by label and description.
+     * @default false */
+    searchable?: boolean;
+    /** Adds buttons that move every item (that the search shows) from one side to the other.
+     * @default false */
+    showMoveAll?: boolean;
+    /** Adds Move up and Move down buttons under the chosen list (and Alt+Up/Down in it), for an order that matters.
+     * The chosen list is then shown without group headings, in the value's order.
+     * @default false */
+    orderable?: boolean;
+    /** Submits each chosen value under this name, in a hidden input, so a Form or a plain form sends them as a list. */
+    name?: string;
+    /** Fades both lists and the buttons, and takes them out of the tab order.
+     * @default false */
+    disabled?: boolean;
+    /** The lists' height, e.g. 320 or "40vh"; they scroll past it.
+     * @default 280 */
+    height?: number | string;
+    id?: string;
+    /** The words it uses, for other languages. `to` is the side's label. */
+    labels?: {
+        /** The count under each heading. @default (selected, total) => `${selected} of ${total} selected` */
+        count?(selected: number, total: number): string;
+        /** The button that moves the selected items. @default (count, to) => `Move 2 selected to ${to}`, or `Move selected to ${to}` with none */
+        moveSelected?(count: number, to: string): string;
+        /** The button that moves them all, with `showMoveAll`. @default (to) => `Move all to ${to}` */
+        moveAll?(to: string): string;
+        /** Read out after a move. @default (names, to) => `Moved Ada and Grace to ${to}`, or `Moved 7 items to ${to}` past five */
+        moved?(names: string[], to: string): string;
+        /** With `orderable`. @default "Move up" */
+        moveUp?: string;
+        /** With `orderable`. @default "Move down" */
+        moveDown?: string;
+        /** Read out after reordering. @default (names, direction) => `Moved Ada up` */
+        reordered?(names: string[], direction: "up" | "down"): string;
+        /** Names a side's search box. @default (side) => `Search ${side}` */
+        search?(side: string): string;
+        /** Shown in an empty list. @default "No items" */
+        empty?: ReactNode;
+        /** Shown when the search matches nothing. @default "No matches" */
+        noMatches?: ReactNode;
+    };
+    className?: string;
+}

package/dist/components/UploadList/UploadList.d.cts

@@ -0,0 +1,9 @@
+import type { UploadListProps } from "./UploadList.types.cjs";
+export type { UploadContext, Uploader, UploadListItem, UploadListLabels, UploadListProps, UploadQueue, UploadStatus, UseUploadQueueOptions, } from "./UploadList.types.cjs";
+export { useUploadQueue } from "./useUploadQueue.cjs";
+/**
+ * The files being uploaded, under a FileDropZone: each with its size, a progress bar while it uploads, and its
+ * status. Retry, Cancel and Remove buttons call back with the file's id. Finished and failed files are announced
+ * politely. `useUploadQueue` does the uploading and keeps the `items` for you.
+ */
+export declare function UploadList({ items, onRetry, onCancel, onRemove, layout, density, showTimeRemaining, locale, labels: labelsProp, className, }: UploadListProps): import("react").JSX.Element;

package/dist/components/UploadList/UploadList.d.ts

@@ -0,0 +1,9 @@
+import type { UploadListProps } from "./UploadList.types.js";
+export type { UploadContext, Uploader, UploadListItem, UploadListLabels, UploadListProps, UploadQueue, UploadStatus, UseUploadQueueOptions, } from "./UploadList.types.js";
+export { useUploadQueue } from "./useUploadQueue.js";
+/**
+ * The files being uploaded, under a FileDropZone: each with its size, a progress bar while it uploads, and its
+ * status. Retry, Cancel and Remove buttons call back with the file's id. Finished and failed files are announced
+ * politely. `useUploadQueue` does the uploading and keeps the `items` for you.
+ */
+export declare function UploadList({ items, onRetry, onCancel, onRemove, layout, density, showTimeRemaining, locale, labels: labelsProp, className, }: UploadListProps): import("react").JSX.Element;

package/dist/components/UploadList/UploadList.types.d.cts

@@ -0,0 +1,113 @@
+/** Where a file's upload has got to. */
+export type UploadStatus = "queued" | "uploading" | "done" | "error" | "canceled";
+/** One file in an UploadList. */
+export interface UploadListItem {
+    /** Tells the rows apart; stays the same while the file uploads. */
+    id: string;
+    /** The file's name, shown and used to name its buttons: "report.pdf". */
+    name: string;
+    /** The file's size in bytes. */
+    size: number;
+    /** The file's MIME type, such as "image/png". */
+    type?: string;
+    /** How far it's got, from 0 to 100. Leave it out while uploading for a bar of unknown length. */
+    progress?: number;
+    /** Where it's got to: `queued` waits its turn, `uploading` shows a bar, `done`, `error` and `canceled` say so. */
+    status: UploadStatus;
+    /** Why it failed, shown in place of the size when the status is "error". */
+    error?: string;
+    /** An image to show as its thumbnail, such as an object URL of the file. */
+    previewUrl?: string;
+    /** Where the uploaded file is: once it's done, the name links there. */
+    href?: string;
+}
+export interface UploadListLabels {
+    /** Names the list for screen readers.
+     * @default "Uploads" */
+    list?: string;
+    /** @default "Waiting" */
+    queued?: string;
+    /** Shown while uploading when the progress isn't known.
+     * @default "Uploading" */
+    uploading?: string;
+    /** @default "Upload failed" */
+    failed?: string;
+    /** @default "Canceled" */
+    canceled?: string;
+    /** How much has gone up, from sizes already formatted.
+     * @default (loaded, total) => `${loaded} of ${total}` */
+    progress?(loaded: string, total: string): string;
+    /** The time left, in seconds.
+     * @default (seconds) => "About 12 sec left" */
+    remaining?(seconds: number): string;
+    /** Formats a size in bytes.
+     * @default 2.1 MB, 340 kB, with Intl.NumberFormat */
+    size?(bytes: number): string;
+    /** @default (name) => `Retry upload of ${name}` */
+    retry?(name: string): string;
+    /** @default (name) => `Cancel upload of ${name}` */
+    cancel?(name: string): string;
+    /** @default (name) => `Remove ${name}` */
+    remove?(name: string): string;
+    /** Announced when a file finishes.
+     * @default (name) => `${name} uploaded` */
+    done?(name: string): string;
+    /** Announced when a file fails.
+     * @default (name, error) => `${name} failed to upload: ${error}` */
+    error?(name: string, error?: string): string;
+}
+export interface UploadListProps {
+    /** The files, in the order to show them. `useUploadQueue` keeps a list like this for you. */
+    items: UploadListItem[];
+    /** Called when Retry is pressed on a file that failed or was canceled. Without it there's no Retry button. */
+    onRetry?(id: string): void;
+    /** Called when Cancel is pressed on a file that's waiting or uploading. Without it there's no Cancel button. */
+    onCancel?(id: string): void;
+    /** Called when Remove is pressed. Without it there's no Remove button. */
+    onRemove?(id: string): void;
+    /** `list` is a row per file; `grid` is a tile per file, with a large thumbnail, for images.
+     * @default "list" */
+    layout?: "list" | "grid";
+    /** `compact` fits each file on one short line, for a sidebar or a long list.
+     * @default "comfortable" */
+    density?: "comfortable" | "compact";
+    /** Shows an estimate of the time left on files that are uploading.
+     * @default false */
+    showTimeRemaining?: boolean;
+    /** The locale sizes and times are formatted in.
+     * @default "en" */
+    locale?: string;
+    /** The words it uses, for other languages. */
+    labels?: UploadListLabels;
+    className?: string;
+}
+/** What an uploader is given along with the file. */
+export interface UploadContext {
+    /** Report how far it's got, from 0 to 100, or undefined when it can't tell. */
+    onProgress(progress: number | undefined): void;
+    /** Aborted when the upload is canceled or removed: pass it to fetch, or listen for "abort". */
+    signal: AbortSignal;
+}
+/**
+ * Uploads one file. Resolve when it's done, with the uploaded file's URL if you have one (the name then links to it);
+ * throw or reject to fail it, and the error's message is shown.
+ */
+export type Uploader = (file: File, context: UploadContext) => Promise<string | void>;
+export interface UseUploadQueueOptions {
+    /** How many files upload at once.
+     * @default 3 */
+    concurrency?: number;
+}
+/** What `useUploadQueue` returns: the items for UploadList and the actions for its buttons. */
+export interface UploadQueue {
+    /** The files and how they're going, for `UploadList`'s `items`. */
+    items: UploadListItem[];
+    /** Adds files to the queue, such as those from `FileDropZone`'s `onFiles`. */
+    add(files: File[]): void;
+    /** Puts a failed or canceled file back in the queue. */
+    retry(id: string): void;
+    /** Stops a file that's waiting or uploading, aborting its signal. */
+    cancel(id: string): void;
+    /** Stops a file if it's going, and takes it off the list. */
+    remove(id: string): void;
+}

package/dist/components/UploadList/UploadList.types.d.ts

@@ -0,0 +1,113 @@
+/** Where a file's upload has got to. */
+export type UploadStatus = "queued" | "uploading" | "done" | "error" | "canceled";
+/** One file in an UploadList. */
+export interface UploadListItem {
+    /** Tells the rows apart; stays the same while the file uploads. */
+    id: string;
+    /** The file's name, shown and used to name its buttons: "report.pdf". */
+    name: string;
+    /** The file's size in bytes. */
+    size: number;
+    /** The file's MIME type, such as "image/png". */
+    type?: string;
+    /** How far it's got, from 0 to 100. Leave it out while uploading for a bar of unknown length. */
+    progress?: number;
+    /** Where it's got to: `queued` waits its turn, `uploading` shows a bar, `done`, `error` and `canceled` say so. */
+    status: UploadStatus;
+    /** Why it failed, shown in place of the size when the status is "error". */
+    error?: string;
+    /** An image to show as its thumbnail, such as an object URL of the file. */
+    previewUrl?: string;
+    /** Where the uploaded file is: once it's done, the name links there. */
+    href?: string;
+}
+export interface UploadListLabels {
+    /** Names the list for screen readers.
+     * @default "Uploads" */
+    list?: string;
+    /** @default "Waiting" */
+    queued?: string;
+    /** Shown while uploading when the progress isn't known.
+     * @default "Uploading" */
+    uploading?: string;
+    /** @default "Upload failed" */
+    failed?: string;
+    /** @default "Canceled" */
+    canceled?: string;
+    /** How much has gone up, from sizes already formatted.
+     * @default (loaded, total) => `${loaded} of ${total}` */
+    progress?(loaded: string, total: string): string;
+    /** The time left, in seconds.
+     * @default (seconds) => "About 12 sec left" */
+    remaining?(seconds: number): string;
+    /** Formats a size in bytes.
+     * @default 2.1 MB, 340 kB, with Intl.NumberFormat */
+    size?(bytes: number): string;
+    /** @default (name) => `Retry upload of ${name}` */
+    retry?(name: string): string;
+    /** @default (name) => `Cancel upload of ${name}` */
+    cancel?(name: string): string;
+    /** @default (name) => `Remove ${name}` */
+    remove?(name: string): string;
+    /** Announced when a file finishes.
+     * @default (name) => `${name} uploaded` */
+    done?(name: string): string;
+    /** Announced when a file fails.
+     * @default (name, error) => `${name} failed to upload: ${error}` */
+    error?(name: string, error?: string): string;
+}
+export interface UploadListProps {
+    /** The files, in the order to show them. `useUploadQueue` keeps a list like this for you. */
+    items: UploadListItem[];
+    /** Called when Retry is pressed on a file that failed or was canceled. Without it there's no Retry button. */
+    onRetry?(id: string): void;
+    /** Called when Cancel is pressed on a file that's waiting or uploading. Without it there's no Cancel button. */
+    onCancel?(id: string): void;
+    /** Called when Remove is pressed. Without it there's no Remove button. */
+    onRemove?(id: string): void;
+    /** `list` is a row per file; `grid` is a tile per file, with a large thumbnail, for images.
+     * @default "list" */
+    layout?: "list" | "grid";
+    /** `compact` fits each file on one short line, for a sidebar or a long list.
+     * @default "comfortable" */
+    density?: "comfortable" | "compact";
+    /** Shows an estimate of the time left on files that are uploading.
+     * @default false */
+    showTimeRemaining?: boolean;
+    /** The locale sizes and times are formatted in.
+     * @default "en" */
+    locale?: string;
+    /** The words it uses, for other languages. */
+    labels?: UploadListLabels;
+    className?: string;
+}
+/** What an uploader is given along with the file. */
+export interface UploadContext {
+    /** Report how far it's got, from 0 to 100, or undefined when it can't tell. */
+    onProgress(progress: number | undefined): void;
+    /** Aborted when the upload is canceled or removed: pass it to fetch, or listen for "abort". */
+    signal: AbortSignal;
+}
+/**
+ * Uploads one file. Resolve when it's done, with the uploaded file's URL if you have one (the name then links to it);
+ * throw or reject to fail it, and the error's message is shown.
+ */
+export type Uploader = (file: File, context: UploadContext) => Promise<string | void>;
+export interface UseUploadQueueOptions {
+    /** How many files upload at once.
+     * @default 3 */
+    concurrency?: number;
+}
+/** What `useUploadQueue` returns: the items for UploadList and the actions for its buttons. */
+export interface UploadQueue {
+    /** The files and how they're going, for `UploadList`'s `items`. */
+    items: UploadListItem[];
+    /** Adds files to the queue, such as those from `FileDropZone`'s `onFiles`. */
+    add(files: File[]): void;
+    /** Puts a failed or canceled file back in the queue. */
+    retry(id: string): void;
+    /** Stops a file that's waiting or uploading, aborting its signal. */
+    cancel(id: string): void;
+    /** Stops a file if it's going, and takes it off the list. */
+    remove(id: string): void;
+}

package/dist/components/UploadList/useUploadQueue.d.cts

@@ -0,0 +1,8 @@
+import type { UploadQueue, Uploader, UseUploadQueueOptions } from "./UploadList.types.cjs";
+/**
+ * Keeps a queue of files for `UploadList`: uploads them with your `uploader`, a few at a time, and tracks each one's
+ * progress and status. Cancel and remove abort the upload's signal; retry puts a file back in the queue.
+ *
+ * `const queue = useUploadQueue((file, { onProgress, signal }) => upload(file, onProgress, signal));`
+ */
+export declare function useUploadQueue(uploader: Uploader, { concurrency }?: UseUploadQueueOptions): UploadQueue;

package/dist/components/UploadList/useUploadQueue.d.ts

@@ -0,0 +1,8 @@
+import type { UploadQueue, Uploader, UseUploadQueueOptions } from "./UploadList.types.js";
+/**
+ * Keeps a queue of files for `UploadList`: uploads them with your `uploader`, a few at a time, and tracks each one's
+ * progress and status. Cancel and remove abort the upload's signal; retry puts a file back in the queue.
+ *
+ * `const queue = useUploadQueue((file, { onProgress, signal }) => upload(file, onProgress, signal));`
+ */
+export declare function useUploadQueue(uploader: Uploader, { concurrency }?: UseUploadQueueOptions): UploadQueue;