@itwin/presentation-hierarchies-react/lib/cjs/presentation-hierarchies-react/UseTree.d.ts

React components based on `@itwin/presentation-hierarchies`

import { GenericInstanceFilter, HierarchyFilteringPath, HierarchyNode, HierarchyProvider } from "@itwin/presentation-hierarchies";
import { InstanceKey, IPrimitiveValueFormatter } from "@itwin/presentation-shared";
import { UseUnifiedTreeSelectionProps } from "./internal/UseUnifiedSelection.js";
import { PresentationHierarchyNode, PresentationTreeNode } from "./TreeNode.js";
import { SelectionChangeType } from "./UseSelectionHandler.js";
/**
 * A data structure that contains information about a single hierarchy level.
 * @public
 */
export interface HierarchyLevelDetails {
    /** The parent node whose hierarchy level's information is contained in this data structure */
    hierarchyNode: HierarchyNode | undefined;
    /** A function to get instance keys of the hierarchy level. */
    getInstanceKeysIterator: (props?: {
        instanceFilter?: GenericInstanceFilter;
        hierarchyLevelSizeLimit?: number | "unbounded";
    }) => AsyncIterableIterator<InstanceKey>;
    /** Get the limit of how many nodes can be loaded in this hierarchy level. */
    sizeLimit?: number | "unbounded";
    /** Set the limit of how many nodes can be loaded in this hierarchy level. */
    setSizeLimit: (value: undefined | number | "unbounded") => void;
    /** Get the active instance filter applied to this hierarchy level. */
    instanceFilter?: GenericInstanceFilter;
    /** Set the instance filter to apply to this hierarchy level */
    setInstanceFilter: (filter: GenericInstanceFilter | undefined) => void;
}
/**
 * A React hook that creates state for a tree component.
 *
 * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
 * component-agnostic result which may be used to render the hierarchy using any UI framework.
 *
 * See `README.md` for an example
 *
 * @see `useUnifiedSelectionTree`
 * @see `useIModelTree`
 * @public
 */
export declare function useTree(props: UseTreeProps): UseTreeResult;
/**
 * A React hook that creates state for a tree component, that is integrated with unified selection
 * through the given selection storage (previously the storage was provided through the, now
 * deprecated, `UnifiedSelectionProvider`).
 *
 * The hook uses `@itwin/presentation-hierarchies` package to load the hierarchy data and returns a
 * component-agnostic result which may be used to render the hierarchy using any UI framework.
 *
 * See `README.md` for an example
 *
 * @see `useTree`
 * @see `useIModelUnifiedSelectionTree`
 * @see `UnifiedSelectionProvider`
 * @public
 */
export declare function useUnifiedSelectionTree({ sourceName, selectionStorage, ...props }: UseTreeProps & UseUnifiedTreeSelectionProps): UseTreeResult;
/** @public */
export interface UseTreeProps {
    /** Provides the hierarchy provider for the tree. */
    getHierarchyProvider: () => HierarchyProvider;
    /** Provides paths to filtered nodes. */
    getFilteredPaths?: ({ abortSignal }: {
        abortSignal: AbortSignal;
    }) => Promise<HierarchyFilteringPath[] | undefined>;
    /**
     * Callback that is called just after a certain action is finished.
     * Can be used for performance tracking.
     */
    onPerformanceMeasured?: (action: "initial-load" | "hierarchy-level-load" | "reload", duration: number) => void;
    /** Action to perform when hierarchy level contains more items that the specified limit. */
    onHierarchyLimitExceeded?: (props: {
        parentId?: string;
        filter?: GenericInstanceFilter;
        limit?: number | "unbounded";
    }) => void;
    /** Action to perform when an error occurs while loading hierarchy. */
    onHierarchyLoadError?: (props: {
        parentId?: string;
        type: "timeout" | "unknown";
        error: unknown;
    }) => void;
}
/**
 * Options for doing either full or a sub tree reload.
 * @public
 */
interface ReloadTreeOptions {
    /** Specifies parent node under which sub tree should be reloaded. */
    parentNodeId: string | undefined;
    /**
     * Specifies how current tree state should be handled:
     * - `keep` - try to keep current tree state (expanded/collapsed nodes, instance filters, etc.).
     * - `discard` - do not try to keep current tree state. Tree model will be update after nodes are reloaded.
     * - `reset` - remove subtree from the model before reloading and reload nodes ignoring cache.
     *
     * Defaults to `"keep"`.
     */
    state?: "keep" | "discard" | "reset";
}
/** @public */
export interface UseTreeResult {
    /**
     * Array containing root tree nodes. It is `undefined` on initial render until any nodes are loaded.
     */
    rootNodes: PresentationTreeNode[] | undefined;
    /**
     * Specifies whether tree is loading or not. It is set to `true` when initial tree load is in progress
     * or tree is reloading.
     */
    isLoading: boolean;
    /**
     * A function that should be called to reload the tree.
     */
    reloadTree: (options?: ReloadTreeOptions) => void;
    /**
     * A function that should be called to either expand or collapse the given node.
     */
    expandNode: (nodeId: string, isExpanded: boolean) => void;
    /**
     * A function that should be called to select nodes in the tree.
     * @param nodeIds Ids of the nodes that are selected.
     * @param changeType Type of change that occurred for the selection.
     */
    selectNodes: (nodeIds: Array<string>, changeType: SelectionChangeType) => void;
    /** Determines whether a given node is selected. */
    isNodeSelected: (nodeId: string) => boolean;
    /** Get a tree node by id */
    getNode: (nodeId: string) => PresentationHierarchyNode | undefined;
    /** Returns hierarchy level details for a given node ID. */
    getHierarchyLevelDetails: (nodeId: string | undefined) => HierarchyLevelDetails | undefined;
    /** Sets a formatter for the primitive values that are displayed in the hierarchy. */
    setFormatter: (formatter: IPrimitiveValueFormatter | undefined) => void;
}
export {};
//# sourceMappingURL=UseTree.d.ts.map