@openwarelabs/ui 0.14.1 → 0.16.0

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

@@ -0,0 +1,80 @@
+import type { CSSProperties, Key, ReactNode } from "react";
+import type { ScrollToIndexOptions } from "./useVirtualizer.js";
+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;
+}

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

@@ -0,0 +1,60 @@
+import { type Key } from "react";
+/** One row that's rendered: where it goes and how tall it is. */
+export interface VirtualItem {
+    index: number;
+    /** The row's key, from `getKey`: use it as the React key. */
+    key: Key;
+    /** Its top, in pixels from the top of the scrolling content. */
+    start: number;
+    /** Its height in pixels: `itemSize`, or measured, or the estimate until it's measured. */
+    size: number;
+}
+export interface ScrollToIndexOptions {
+    /** Where the row ends up: at the `start` (top) of the view, the `center`, the `end`, or `auto`, scrolling only as
+     * far as needed to show it.
+     * @default "auto" */
+    align?: "start" | "center" | "end" | "auto";
+    /** `smooth` animates the scroll, except for people who prefer reduced motion.
+     * @default "auto" */
+    behavior?: ScrollBehavior;
+}
+export interface UseVirtualizerOptions {
+    /** How many rows there are. */
+    count: number;
+    /** Returns the element that scrolls. It must be there once the component has mounted. */
+    getScrollElement(): HTMLElement | null;
+    /** Every row's height in pixels, when they're all the same: the fastest, as nothing is measured. */
+    itemSize?: number;
+    /** A guess at a row's height in pixels, before it's measured. Rows are measured as they render, and the view
+     * doesn't jump when a row above it turns out taller or shorter than the guess.
+     * @default 48 */
+    estimateSize?: number | ((index: number) => number);
+    /** How many rows to render beyond each edge of the view, so fast scrolling doesn't show gaps.
+     * @default 4 */
+    overscan?: number;
+    /** Space between rows, in pixels.
+     * @default 0 */
+    gap?: number;
+    /** A stable key for each row. With real keys (not the index), measured heights follow their row, and rows
+     * added at the top keep the view where it was.
+     * @default (index) => index */
+    getKey?(index: number): Key;
+    /** A row to keep rendered even out of view, such as the one that has focus, so it isn't lost. */
+    keepMounted?: number | null;
+}
+export interface Virtualizer {
+    /** The rows to render: those in view and the overscan around them. */
+    items: VirtualItem[];
+    /** The height of all the rows together: give the content inside the scrolling element this height. */
+    totalSize: number;
+    /** Pass as the `ref` of each rendered row, with `data-index` on it, so its height is measured. */
+    measureElement(element: HTMLElement | null): void;
+    /** Scrolls a row into view. */
+    scrollToIndex(index: number, options?: ScrollToIndexOptions): void;
+}
+/**
+ * Windowing for long lists: works out which rows of `count` are in view of a scrolling element, where each one goes,
+ * and how tall the whole list is, so you render only those rows. Rows have a fixed `itemSize`, or are measured with
+ * ResizeObserver as they render. VirtualList is built on it; use it for your own virtualized table or list box.
+ */
+export declare function useVirtualizer({ count, getScrollElement, itemSize, estimateSize, overscan, gap, getKey, keepMounted, }: UseVirtualizerOptions): Virtualizer;

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

@@ -0,0 +1,60 @@
+import { type Key } from "react";
+/** One row that's rendered: where it goes and how tall it is. */
+export interface VirtualItem {
+    index: number;
+    /** The row's key, from `getKey`: use it as the React key. */
+    key: Key;
+    /** Its top, in pixels from the top of the scrolling content. */
+    start: number;
+    /** Its height in pixels: `itemSize`, or measured, or the estimate until it's measured. */
+    size: number;
+}
+export interface ScrollToIndexOptions {
+    /** Where the row ends up: at the `start` (top) of the view, the `center`, the `end`, or `auto`, scrolling only as
+     * far as needed to show it.
+     * @default "auto" */
+    align?: "start" | "center" | "end" | "auto";
+    /** `smooth` animates the scroll, except for people who prefer reduced motion.
+     * @default "auto" */
+    behavior?: ScrollBehavior;
+}
+export interface UseVirtualizerOptions {
+    /** How many rows there are. */
+    count: number;
+    /** Returns the element that scrolls. It must be there once the component has mounted. */
+    getScrollElement(): HTMLElement | null;
+    /** Every row's height in pixels, when they're all the same: the fastest, as nothing is measured. */
+    itemSize?: number;
+    /** A guess at a row's height in pixels, before it's measured. Rows are measured as they render, and the view
+     * doesn't jump when a row above it turns out taller or shorter than the guess.
+     * @default 48 */
+    estimateSize?: number | ((index: number) => number);
+    /** How many rows to render beyond each edge of the view, so fast scrolling doesn't show gaps.
+     * @default 4 */
+    overscan?: number;
+    /** Space between rows, in pixels.
+     * @default 0 */
+    gap?: number;
+    /** A stable key for each row. With real keys (not the index), measured heights follow their row, and rows
+     * added at the top keep the view where it was.
+     * @default (index) => index */
+    getKey?(index: number): Key;
+    /** A row to keep rendered even out of view, such as the one that has focus, so it isn't lost. */
+    keepMounted?: number | null;
+}
+export interface Virtualizer {
+    /** The rows to render: those in view and the overscan around them. */
+    items: VirtualItem[];
+    /** The height of all the rows together: give the content inside the scrolling element this height. */
+    totalSize: number;
+    /** Pass as the `ref` of each rendered row, with `data-index` on it, so its height is measured. */
+    measureElement(element: HTMLElement | null): void;
+    /** Scrolls a row into view. */
+    scrollToIndex(index: number, options?: ScrollToIndexOptions): void;
+}
+/**
+ * Windowing for long lists: works out which rows of `count` are in view of a scrolling element, where each one goes,
+ * and how tall the whole list is, so you render only those rows. Rows have a fixed `itemSize`, or are measured with
+ * ResizeObserver as they render. VirtualList is built on it; use it for your own virtualized table or list box.
+ */
+export declare function useVirtualizer({ count, getScrollElement, itemSize, estimateSize, overscan, gap, getKey, keepMounted, }: UseVirtualizerOptions): Virtualizer;