@openwarelabs/ui 0.14.1 → 0.15.0

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/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;
+}

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;