nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Inputs/TreeView.d.ts

@@ -0,0 +1,160 @@
+import { type CSSProperties, type ReactNode, type Ref } from "react";
+import { type TreeItem, type TreeValue, type TreeValueMode } from "../../Helpers/TreeStore.ts";
+import type { Size } from "../../Interfaces/TypeInterfaces.ts";
+export type TreeAction = "create" | "update" | "delete";
+export interface TreeCreateRequest<TItem extends TreeItem = TreeItem> {
+    /** The item the new one goes under, or `null` at the top level. */
+    parent: TItem | null;
+    parentValue: TreeValue | null;
+    /** The name typed, trimmed. */
+    label: string;
+    /** What the tree adds when `onCreate` returns nothing: a generated value, the parent's value, and the label. */
+    item: TItem;
+}
+export interface TreeUpdateRequest<TItem extends TreeItem = TreeItem> {
+    item: TItem;
+    value: TreeValue;
+    /** The new name, trimmed. */
+    label: string;
+}
+export interface TreeDeleteRequest<TItem extends TreeItem = TreeItem> {
+    item: TItem;
+    value: TreeValue;
+    /** The item and everything under it, in tree order. */
+    items: TItem[];
+}
+/** What a `ref` on `TreeView` can do. */
+export interface TreeViewHandle<TItem extends TreeItem = TreeItem> {
+    /** Expands every item, or the first `levels` levels. */
+    expandAll: (levels?: number) => void;
+    collapseAll: () => void;
+    /** Expands an item and its parents. */
+    expand: (value: TreeValue) => void;
+    collapse: (value: TreeValue) => void;
+    /** Expands the parents of an item, scrolls to it, and focuses it unless `focus` is false. */
+    reveal: (value: TreeValue, focus?: boolean) => void;
+    getValue: () => TreeValue[];
+    /** Checks exactly these values, locked items included. For a tree without `value`. */
+    setValue: (values: readonly TreeValue[]) => void;
+    /** Checks or unchecks every item that is not locked. */
+    checkAll: (checked: boolean) => void;
+    /** Every item in tree order, with the changes made in the tree. */
+    getItems: () => TItem[];
+    /** Opens the editor for a new item under `parentValue`, or at the top level for `null`. */
+    startCreate: (parentValue: TreeValue | null) => void;
+    startRename: (value: TreeValue) => void;
+    /** Asks (unless `confirmDelete` is off), then deletes an item. Resolves with whether it was deleted. */
+    remove: (value: TreeValue) => Promise<boolean>;
+    /** Focuses the focused row, or the first. */
+    focus: () => void;
+}
+export interface TreeViewProps<TItem extends TreeItem = TreeItem> {
+    /**
+     * The items, flat: each names its parent through `parentKey`, and siblings keep this order. Keep the array stable
+     * (state, a constant, or `useMemo`): a different array, or one with different items, builds the tree again.
+     */
+    items: readonly TItem[];
+    /** The item field that holds its value. Default `id`. */
+    valueKey?: string;
+    /** The item field that holds its parent's value; empty for a top-level item. Default `parentId`. */
+    parentKey?: string;
+    /** The item field shown as its name. Default `label`. */
+    labelKey?: string;
+    /** Muted text after the label. Default `description`. */
+    descriptionKey?: string;
+    /** A Tabler icon name, or an element, before the label. Default `icon`. */
+    iconKey?: string;
+    /**
+     * Items the user has no permission to change: they cannot be checked, unchecked, renamed, or deleted, and everything
+     * under them is locked too. A lock shows at the end of the row, and a try shows `lockedMessage`. Default:
+     * `disabled: true` or `isDisabled: true`.
+     */
+    isItemDisabled?: (item: TItem) => boolean;
+    /** What a locked item says when someone tries to change it. Default "You do not have permission to change this item." */
+    lockedMessage?: string;
+    label?: ReactNode;
+    /** Help text under the tree. */
+    hint?: ReactNode;
+    /** An error from outside, such as a server message. */
+    error?: string | null;
+    /** Default `md`. */
+    size?: Size;
+    /** A checkbox on every row. */
+    checkable?: boolean;
+    /** With `checkable`: checking a parent checks everything under it, and a parent shows the state of its items. Default true. */
+    cascade?: boolean;
+    /** Which checked items the value holds. Default `leaves`, such as the action ids of a permission tree. See `TreeValueMode`. */
+    valueMode?: TreeValueMode;
+    /** The checked values. With `value`, the tree is controlled; pair it with `onValueChange`. */
+    value?: readonly TreeValue[];
+    /** The checked values at the start. Without it, items with `checked: true` or `isChecked: true` start checked. */
+    defaultValue?: readonly TreeValue[];
+    /** After each check or uncheck: the values and their items, in tree order. */
+    onValueChange?: (values: TreeValue[], items: TItem[]) => void;
+    /** A form gets the value as hidden inputs named `name`, one per value. Leave it out for very large values and read them from `onValueChange`. */
+    name?: string;
+    form?: string;
+    /** With `checkable` and `cascade`: a parent shows how many of its items are checked, as "3/5". Default true. */
+    counts?: boolean;
+    /** What is expanded at the start: `"all"`, a number of levels, or the values of items to open. */
+    defaultExpanded?: "all" | number | readonly TreeValue[];
+    /** Items can be added: a + on each row adds under it, and Add in the toolbar adds at the top level. */
+    creatable?: boolean;
+    /** Items can be renamed: a pencil on each row, F2, or the context menu. */
+    editable?: boolean;
+    /** Items can be deleted, with everything under them: a bin on each row, Delete, or the context menu. */
+    deletable?: boolean;
+    /** Narrows the actions per item, e.g. from the user's permissions. `item` is `null` for adding at the top level. */
+    canChange?: (action: TreeAction, item: TItem | null) => boolean;
+    /**
+     * Saves a new item, e.g. through an API. Return the saved item (with the server's id), or nothing to keep
+     * `request.item`. A thrown error keeps the editor open with the name typed and shows the message under the tree.
+     */
+    onCreate?: (request: TreeCreateRequest<TItem>) => TItem | void | Promise<TItem | void>;
+    /** Saves a new name. Return the saved item, or nothing to keep the item with the new label. A thrown error keeps the editor open. */
+    onUpdate?: (request: TreeUpdateRequest<TItem>) => TItem | void | Promise<TItem | void>;
+    /** Deletes an item and everything under it. A thrown error keeps the items and shows the message. */
+    onDelete?: (request: TreeDeleteRequest<TItem>) => void | Promise<void>;
+    /** After an item is added, renamed, or deleted: every item in tree order. Passing this array back as `items` does not rebuild the tree. */
+    onItemsChange?: (items: TItem[]) => void;
+    /** Asks before deleting. Default true; needs `<PopupHost />` on the page. */
+    confirmDelete?: boolean;
+    /** The longest name the editor takes. Default 100. */
+    maxLabelLength?: number;
+    /** A click on a row without a checkbox, or Enter on it. Without it, a click expands or collapses a parent. */
+    onItemClick?: (item: TItem) => void;
+    /** Items are on their way: placeholder rows while the tree is empty, and a spinner in the toolbar. */
+    loading?: boolean;
+    /** Shown when there are no items. Default "No items". */
+    emptyMessage?: ReactNode;
+    /** The bar above the rows: select all, counts, expand all, collapse all, and Add. Default true. */
+    toolbar?: boolean;
+    /** A fixed height for the rows' area, e.g. 480 or "60vh". */
+    height?: number | string;
+    /** The tallest the rows' area grows before it scrolls. Default 420. */
+    maxHeight?: number | string;
+    /** Can be browsed, expanded, and focused, but not changed. A lock follows the label, and a try shows a note. */
+    readOnly?: boolean;
+    /** What a read-only tree says when someone tries to change it. Default "Read-only: this tree cannot be changed." */
+    readOnlyMessage?: string;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Name for screen readers when there is no `label`. */
+    "aria-label"?: string;
+    ref?: Ref<TreeViewHandle<TItem>>;
+}
+/**
+ * A tree of items from a flat list: a permission tree (controller > menu > action) with checkboxes that cascade and
+ * items the user may not change, or a tree of categories to add, rename, and delete. Only the rows in view are
+ * rendered, so collapsed items never reach the page, and 100,000 expanded items scroll like 40. Expanding and
+ * collapsing slide open and closed (at once with reduced motion).
+ *
+ * Keys: arrows move and expand, Home and End jump, letters find a row, Space checks, Enter opens, `*` expands the
+ * siblings, F2 renames, Delete deletes, Insert adds under the focused row, and Shift+F10 opens the actions menu.
+ *
+ * @example
+ * <TreeView label="Permissions" items={permissions} checkable name="actionIds" defaultExpanded={1} isItemDisabled={item => !item.canAssign} />
+ */
+export declare function TreeView<TItem extends TreeItem = TreeItem>(props: TreeViewProps<TItem>): import("react").JSX.Element;