@stratakit/structures/dist/TreeItem.d.ts

Medium-sized component structures for the Strata design system

import * as React from "react";
import type { BaseProps } from "@stratakit/foundations/secret-internals";
interface TreeItemProps extends Omit<BaseProps, "content" | "children"> {
    /** Specifies the nesting level of the tree item. Nesting levels start at 1. */
    "aria-level": number;
    /** Defines tree item position in the current level of tree items. Integer greater than or equal to 1. */
    "aria-posinset": number;
    /** Defines tree item set size of the current level. */
    "aria-setsize": number;
    /**
     * Specifies if the tree item is selected.
     *
     * If `undefined`, the tree item is not selectable.
     *
     * @default undefined
     */
    selected?: boolean;
    /**
     * Callback fired when the tree item is selected.
     *
     * Should be used with the `selected` prop.
     */
    onSelectedChange?: (selected: boolean) => void;
    /**
     * Specifies if the tree item is expanded.
     *
     * Used to determine if a tree item is a parent node. If `undefined`, it is a leaf node (i.e. not expandable).
     *
     * @default undefined
     */
    expanded?: boolean;
    /**
     * Callback fired when the tree item is expanded.
     *
     * Should be used with the `expanded` prop.
     */
    onExpandedChange?: (expanded: boolean) => void;
    /**
     * Icon to be displayed inside the tree item.
     *
     * Can be a URL of an SVG from the `@stratakit/icons` package, or a JSX element.
     *
     * For multiple icons/decorations, use the `unstable_decorations` prop.
     */
    icon?: string | React.JSX.Element;
    /**
     * Decoration(s) to be displayed inside the tree item.
     *
     * This is an alternative to the `icon` prop, and can be used to
     * display multiple icons or other decorations before the label.
     *
     * Note: This should _not_ be used together with the `icon` prop.
     *
     * @experimental
     */
    unstable_decorations?: React.ReactNode;
    /**
     * The primary label that identifies the tree item and is displayed inside it.
     */
    label?: React.ReactNode;
    /** Secondary line of text to display additional information about the tree item. */
    description?: React.ReactNode;
    /**
     * The secondary actions available for the tree item displayed as icon buttons in a toolbar. Must be a list of `Tree.ItemAction` components.
     *
     * Example:
     * ```tsx
     * inlineActions={
     *   error
     *     ? [
     *         <Tree.ItemAction key={…} icon={…} label={…} />
     *       ]
     *     : [
     *         <Tree.ItemAction key={…} icon={…} label={…} />,
     *         <Tree.ItemAction key={…} icon={…} label={…} />,
     *       ]
     * }
     * ```
     *
     * Inline actions should only be used for frequently used and quickly accessible actions.
     * At most two inline actions are displayed. A single action should be specified when tree item has an error.
     *
     * The inline actions are normally hidden until the treeitem is hovered or focused.
     * When the `error` prop is set, the actions will be made visible by default. The first
     * action slot should usually be used to display an error-related action.
     *
     * @experimental
     */
    inlineActions?: React.ReactNode[];
    /**
     * The secondary actions available for the tree item displayed in a dropdown menu. Must be a list of `Tree.ItemAction` components.
     *
     * ```tsx
     * actions={[
     *   <Tree.ItemAction key={…} icon={…} label={…} />,
     *   <Tree.ItemAction key={…} icon={…} label={…} />,
     * ]}
     * ```
     *
     * @experimental
     */
    actions?: React.ReactNode[];
    /**
     * Specifies if the tree item is in an error state.
     * The id for an associated error message (e.g. `<ErrorRegion.Item>`) can be passed as a string.
     *
     * Can be combined with the `actions` prop to display an error-related action (e.g. "Retry").
     * The first action will be made visible by default.
     *
     * @default false
     */
    error?: boolean | string;
}
/**
 * A treeitem is a node in a tree structure that may be expanded or collapsed to reveal or hide its descendants.
 *
 * `Tree.Item`s can be rendered inside a `Tree.Root`. Additional properties are specified to the `Tree.Item`s to create a hierarchical tree structure.
 *
 * Example:
 * ```tsx
 * <Tree.Root>
 *   <Tree.Item label="Parent" aria-level={1} aria-posinset={1} aria-setsize={1} />
 *   <Tree.Item label="Child 1" aria-level={2} aria-posinset={1} aria-setsize={2} />
 *   <Tree.Item label="Child 2" aria-level={2} aria-posinset={2} aria-setsize={2}  />
 * </Tree.Root>
 * ```
 *
 * The `label` and `icon` props can be used to specify the treeitem's own content.
 *
 * The `aria-level` prop is used to specify the nesting level of the treeitem. Nesting levels start at 1.
 *
 * The `aria-posinset` and `aria-setsize` props are used to define the treeitem's position in the current level of tree items.
 *
 * The `expanded` and `onExpandedChange` props can be used to control the expansion state of a treeitem.
 *
 * The `selected` and `onSelectedChange` props can be used to control the selection state of a treeitem.
 *
 * Secondary actions can be passed into the `actions` prop.
 */
declare const TreeItem: React.NamedExoticComponent<TreeItemProps & React.RefAttributes<HTMLDivElement | HTMLElement>>;
interface TreeItemActionProps extends Omit<BaseProps<"button">, "children"> {
    /**
     * Label for the action.
     *
     * Will be displayed as a tooltip when the action is an icon-button,
     * otherwise will be displayed as a label inside the menu-item.
     */
    label: string;
    /**
     * Icon for the action.
     *
     * Can be a URL of an SVG from the `@stratakit/icons` package, or a JSX element.
     *
     * Required when the action is displayed as an icon-button (i.e. not overflowing).
     */
    icon?: string | React.JSX.Element;
    /**
     * Controls the visibility of the action (only when the action is displayed as icon-button).
     *
     * If `true`, the action is always visible.
     * If `false`, the action is hidden and becomes inaccessible, but still occupies space.
     *
     * By default, the action is shown only when the treeitem receives hover/focus. When the
     * treeitem has an `error`, the action will become always visible (i.e. it will default
     * to `true` when `error` is set).
     */
    visible?: boolean;
    /**
     * A small dot displayed in the corner of the action.
     *
     * The value of this prop gets used as the button's "accessible description".
     *
     * Example:
     * ```tsx
     * <Tree.ItemAction
     *   label="Filter"
     *   dot="Some filters applied"
     *   icon={…}
     * />
     * ```
     */
    dot?: string;
}
/**
 * A secondary action for `<Tree.Item>`, to be passed into the `actions` prop. The action is typically
 * displayed as an icon-button or a menu-item (e.g. when overflowing).
 *
 * By default, the action appears only when the treeitem has hover/focus or an error. This behavior can
 * be overridden using the `visible` prop.
 */
declare const TreeItemAction: React.NamedExoticComponent<TreeItemActionProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
export { TreeItem as Root, TreeItemAction as Action };