@openwarelabs/ui 0.14.1 → 0.16.0

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/TreeView/TreeView.d.cts

@@ -0,0 +1,8 @@
+import type { TreeViewProps } from "./TreeView.types.cjs";
+export type { TreeItem, TreeViewLabels, TreeViewProps, TreeViewSelectionMode } from "./TreeView.types.cjs";
+/**
+ * A tree of rows that open and close, for categories, org charts, permissions, nested settings or navigation. Rows can
+ * be selected (one or many), checked with tri-state parents, activated, and their children fetched when they first open.
+ * It's one tab stop: the arrow keys move and open, Home/End jump, typing finds a row, Space selects and Enter activates.
+ */
+export declare function TreeView({ items, label, "aria-labelledby": ariaLabelledBy, expanded, defaultExpanded, onExpandedChange, selectionMode, selected, defaultSelected, onSelectedChange, checkboxes, loadChildren, onAction, renderLabel, labels: labelsProp, className, }: TreeViewProps): import("react").JSX.Element;

package/dist/components/TreeView/TreeView.d.ts

@@ -0,0 +1,8 @@
+import type { TreeViewProps } from "./TreeView.types.js";
+export type { TreeItem, TreeViewLabels, TreeViewProps, TreeViewSelectionMode } from "./TreeView.types.js";
+/**
+ * A tree of rows that open and close, for categories, org charts, permissions, nested settings or navigation. Rows can
+ * be selected (one or many), checked with tri-state parents, activated, and their children fetched when they first open.
+ * It's one tab stop: the arrow keys move and open, Home/End jump, typing finds a row, Space selects and Enter activates.
+ */
+export declare function TreeView({ items, label, "aria-labelledby": ariaLabelledBy, expanded, defaultExpanded, onExpandedChange, selectionMode, selected, defaultSelected, onSelectedChange, checkboxes, loadChildren, onAction, renderLabel, labels: labelsProp, className, }: TreeViewProps): import("react").JSX.Element;

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

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react";
+/** One row of the tree, and the rows under it. */
+export interface TreeItem {
+    /** Unique in the whole tree: it's what `expanded` and `selected` hold. */
+    id: string;
+    /** The row's text. It names the row for screen readers and is what type-ahead matches. */
+    label: string;
+    /** A 16px icon before the label. */
+    icon?: ReactNode;
+    /** A muted line under the label. */
+    description?: ReactNode;
+    /** Muted content at the end of the row: a count, a badge, a status. Keep it non-interactive. */
+    end?: ReactNode;
+    /** It can be focused and opened, but not selected, checked or activated. */
+    disabled?: boolean;
+    /** The rows under this one. */
+    children?: TreeItem[];
+    /** It has children that `loadChildren` fetches the first time it opens. */
+    hasChildren?: boolean;
+}
+export type TreeViewSelectionMode = "none" | "single" | "multiple";
+export interface TreeViewLabels {
+    /** The row shown while children load.
+     * @default "Loading…" */
+    loading?: string;
+    /** The row shown when they couldn't load, before the retry text.
+     * @default "Couldn't load." */
+    error?: string;
+    /** The retry text in that row; activating the row tries again.
+     * @default "Retry" */
+    retry?: string;
+}
+export interface TreeViewProps {
+    /** The top-level rows. */
+    items: TreeItem[];
+    /** Names the tree for screen readers: "Categories", "Permissions". */
+    label?: string;
+    /** Names the tree by another element's id instead, such as a heading's. */
+    "aria-labelledby"?: string;
+    /** The ids of the open rows, when you control them. */
+    expanded?: string[];
+    /** The ids open at first when uncontrolled.
+     * @default [] */
+    defaultExpanded?: string[];
+    /** Called with the open ids when a row opens or closes. */
+    onExpandedChange?(expanded: string[]): void;
+    /** `single` selects one row; `multiple` any number (Shift extends a range); `none` makes rows only activate.
+     * @default "single" */
+    selectionMode?: TreeViewSelectionMode;
+    /** The selected (or checked) ids, when you control them. */
+    selected?: string[];
+    /** The ids selected at first when uncontrolled.
+     * @default [] */
+    defaultSelected?: string[];
+    /** Called with the selected (or checked) ids, in the tree's order. */
+    onSelectedChange?(selected: string[]): void;
+    /** Shows a checkbox on each row for picking several. Checking a row checks the loaded rows under it, and a row whose
+     * rows are partly checked shows a dash. `selected` then holds every fully checked id. Implies multiple selection.
+     * @default false */
+    checkboxes?: boolean;
+    /** Fetches a row's children the first time it opens, for rows with `hasChildren`. A loading row shows meanwhile,
+     * and if it rejects, a row to retry. */
+    loadChildren?(item: TreeItem): Promise<TreeItem[]>;
+    /** Called when a row is activated: Enter, a double-click, or a click when `selectionMode` is `none`. */
+    onAction?(item: TreeItem): void;
+    /** Draws each row's label instead of the plain text, e.g. to highlight a search match. */
+    renderLabel?(item: TreeItem): ReactNode;
+    /** The words it shows, for other languages. */
+    labels?: TreeViewLabels;
+    className?: string;
+}
+/** A row's checkbox: checked, not, or partly (some of the rows under it). Internal. */
+export type TreeViewChecked = boolean | "mixed";
+/** A visible row: an item, or the loading or error row under an item whose children are being fetched. Internal. */
+export interface TreeViewRow {
+    id: string;
+    item?: TreeItem;
+    status?: "loading" | "error";
+    parent?: TreeViewRow;
+    /** Its place in the visible rows. */
+    index: number;
+    level: number;
+    pos: number;
+    size: number;
+    expandable: boolean;
+    open: boolean;
+    kids: TreeViewRow[];
+}

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

@@ -0,0 +1,88 @@
+import type { ReactNode } from "react";
+/** One row of the tree, and the rows under it. */
+export interface TreeItem {
+    /** Unique in the whole tree: it's what `expanded` and `selected` hold. */
+    id: string;
+    /** The row's text. It names the row for screen readers and is what type-ahead matches. */
+    label: string;
+    /** A 16px icon before the label. */
+    icon?: ReactNode;
+    /** A muted line under the label. */
+    description?: ReactNode;
+    /** Muted content at the end of the row: a count, a badge, a status. Keep it non-interactive. */
+    end?: ReactNode;
+    /** It can be focused and opened, but not selected, checked or activated. */
+    disabled?: boolean;
+    /** The rows under this one. */
+    children?: TreeItem[];
+    /** It has children that `loadChildren` fetches the first time it opens. */
+    hasChildren?: boolean;
+}
+export type TreeViewSelectionMode = "none" | "single" | "multiple";
+export interface TreeViewLabels {
+    /** The row shown while children load.
+     * @default "Loading…" */
+    loading?: string;
+    /** The row shown when they couldn't load, before the retry text.
+     * @default "Couldn't load." */
+    error?: string;
+    /** The retry text in that row; activating the row tries again.
+     * @default "Retry" */
+    retry?: string;
+}
+export interface TreeViewProps {
+    /** The top-level rows. */
+    items: TreeItem[];
+    /** Names the tree for screen readers: "Categories", "Permissions". */
+    label?: string;
+    /** Names the tree by another element's id instead, such as a heading's. */
+    "aria-labelledby"?: string;
+    /** The ids of the open rows, when you control them. */
+    expanded?: string[];
+    /** The ids open at first when uncontrolled.
+     * @default [] */
+    defaultExpanded?: string[];
+    /** Called with the open ids when a row opens or closes. */
+    onExpandedChange?(expanded: string[]): void;
+    /** `single` selects one row; `multiple` any number (Shift extends a range); `none` makes rows only activate.
+     * @default "single" */
+    selectionMode?: TreeViewSelectionMode;
+    /** The selected (or checked) ids, when you control them. */
+    selected?: string[];
+    /** The ids selected at first when uncontrolled.
+     * @default [] */
+    defaultSelected?: string[];
+    /** Called with the selected (or checked) ids, in the tree's order. */
+    onSelectedChange?(selected: string[]): void;
+    /** Shows a checkbox on each row for picking several. Checking a row checks the loaded rows under it, and a row whose
+     * rows are partly checked shows a dash. `selected` then holds every fully checked id. Implies multiple selection.
+     * @default false */
+    checkboxes?: boolean;
+    /** Fetches a row's children the first time it opens, for rows with `hasChildren`. A loading row shows meanwhile,
+     * and if it rejects, a row to retry. */
+    loadChildren?(item: TreeItem): Promise<TreeItem[]>;
+    /** Called when a row is activated: Enter, a double-click, or a click when `selectionMode` is `none`. */
+    onAction?(item: TreeItem): void;
+    /** Draws each row's label instead of the plain text, e.g. to highlight a search match. */
+    renderLabel?(item: TreeItem): ReactNode;
+    /** The words it shows, for other languages. */
+    labels?: TreeViewLabels;
+    className?: string;
+}
+/** A row's checkbox: checked, not, or partly (some of the rows under it). Internal. */
+export type TreeViewChecked = boolean | "mixed";
+/** A visible row: an item, or the loading or error row under an item whose children are being fetched. Internal. */
+export interface TreeViewRow {
+    id: string;
+    item?: TreeItem;
+    status?: "loading" | "error";
+    parent?: TreeViewRow;
+    /** Its place in the visible rows. */
+    index: number;
+    level: number;
+    pos: number;
+    size: number;
+    expandable: boolean;
+    open: boolean;
+    kids: TreeViewRow[];
+}

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;

package/dist/components/VirtualList/VirtualList.d.cts

@@ -0,0 +1,9 @@
+import { type ReactElement, type RefAttributes } from "react";
+import type { VirtualListHandle, VirtualListProps } from "./VirtualList.types.cjs";
+export type { VirtualListHandle, VirtualListLabels, VirtualListProps } from "./VirtualList.types.cjs";
+/**
+ * A scrolling list that renders only the rows in view, for long logs, chat histories and big datasets: 10,000 rows
+ * cost what 20 do. Rows have a fixed `itemSize`, or are measured as they render. `onEndReached` loads more as the
+ * reader nears the end, `followOutput` keeps a log's newest line in view, and a ref scrolls to any row.
+ */
+export declare const VirtualList: <T = unknown>(props: VirtualListProps<T> & RefAttributes<VirtualListHandle>) => ReactElement | null;

package/dist/components/VirtualList/VirtualList.d.ts

@@ -0,0 +1,9 @@
+import { type ReactElement, type RefAttributes } from "react";
+import type { VirtualListHandle, VirtualListProps } from "./VirtualList.types.js";
+export type { VirtualListHandle, VirtualListLabels, VirtualListProps } from "./VirtualList.types.js";
+/**
+ * A scrolling list that renders only the rows in view, for long logs, chat histories and big datasets: 10,000 rows
+ * cost what 20 do. Rows have a fixed `itemSize`, or are measured as they render. `onEndReached` loads more as the
+ * reader nears the end, `followOutput` keeps a log's newest line in view, and a ref scrolls to any row.
+ */
+export declare const VirtualList: <T = unknown>(props: VirtualListProps<T> & RefAttributes<VirtualListHandle>) => ReactElement | null;

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

@@ -0,0 +1,80 @@
+import type { CSSProperties, Key, ReactNode } from "react";
+import type { ScrollToIndexOptions } from "./useVirtualizer.cjs";
+export interface VirtualListLabels {
+    /** Announced to screen readers while more rows load.
+     * @default "Loading more" */
+    loading?: string;
+}
+export interface VirtualListProps<T = unknown> {
+    /** The rows' data. Leave it out and pass `count` to render rows from their index alone. */
+    items?: readonly T[];
+    /** How many rows there are.
+     * @default items.length */
+    count?: number;
+    /** Renders one row. With `count` alone, `item` is undefined: use the index. */
+    renderItem(item: T, index: number): ReactNode;
+    /** A stable key for each row, such as its id. Give one when rows can be added at the top (older messages), so
+     * the view stays where it was, and so measured heights follow their row.
+     * @default (item, index) => index */
+    getKey?(item: T, index: number): Key;
+    /** Every row's height in pixels, when they're all the same. The fastest: nothing is measured. */
+    itemSize?: number;
+    /** A guess at a row's height in pixels when they vary. Each row is measured once it renders, and replaces the
+     * guess without the view jumping; the closer the guess, the steadier the scrollbar.
+     * @default 48 */
+    estimateSize?: number | ((index: number) => number);
+    /** How many rows to render beyond each edge of the view, so fast scrolling doesn't show blank space.
+     * @default 4 */
+    overscan?: number;
+    /** Space between rows, in pixels.
+     * @default 0 */
+    gap?: number;
+    /** The list's height. Without `height` or `maxHeight`, it fills its parent, which needs a height. */
+    height?: number | string;
+    /** Lets the list grow with its rows up to this height, then scroll. */
+    maxHeight?: number | string;
+    /** Called when the reader scrolls near the end, to load more rows. Called once per number of rows, and not
+     * while `loading` or once `hasMore` is false. */
+    onEndReached?(): void;
+    /** Called when the reader scrolls near the start, to load older rows (a chat's history). Rows added at the top
+     * keep the view where it was, as long as `getKey` gives real keys. */
+    onStartReached?(): void;
+    /** How close to either end, in pixels, calls `onEndReached` or `onStartReached`.
+     * @default 200 */
+    endReachedThreshold?: number;
+    /** Shows a spinner after the last row and tells screen readers more is loading.
+     * @default false */
+    loading?: boolean;
+    /** Whether there are more rows to load at the end; false stops `onEndReached`.
+     * @default true */
+    hasMore?: boolean;
+    /** Opens at the end and keeps the newest row in view as rows are added or grow, while the reader is at the end:
+     * for logs and chats. Scrolling up to read stops it; scrolling back down starts it again.
+     * @default false */
+    followOutput?: boolean;
+    /** `list` for a list of rows. `feed` for an endless stream of articles people read one by one (posts, news):
+     * each row is a focusable article, and Page Down and Page Up move between them.
+     * @default "list" */
+    role?: "list" | "feed";
+    /** Names the list for screen readers. */
+    label?: string;
+    /** The id of a visible heading that names the list, in place of `label`. */
+    "aria-labelledby"?: string;
+    /** Shown in place of the rows when there are none and nothing is loading. */
+    empty?: ReactNode;
+    /** The words it uses, for other languages. */
+    labels?: VirtualListLabels;
+    /** A class for each row's wrapper. */
+    itemClassName?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+export interface VirtualListHandle {
+    /** Scrolls a row into view, rendering it first. `behavior: "smooth"` animates, except under reduced motion. */
+    scrollToIndex(index: number, options?: ScrollToIndexOptions): void;
+    /** Scrolls to the last row, and follows new rows again with `followOutput`. */
+    scrollToEnd(options?: Pick<ScrollToIndexOptions, "behavior">): void;
+    /** The element that scrolls. */
+    readonly element: HTMLDivElement | null;
+}