@itwin/presentation-hierarchies/lib/esm/hierarchies/HierarchyFiltering.d.ts

A package for creating hierarchies based on data in iTwin.js iModels.

import { HierarchyNode, NonGroupingHierarchyNode } from "./HierarchyNode.js";
import { HierarchyNodeIdentifier, HierarchyNodeIdentifiersPath } from "./HierarchyNodeIdentifier.js";
import { GenericNodeKey, GroupingNodeKey, InstancesNodeKey } from "./HierarchyNodeKey.js";
/** @public */
export interface FilterTargetGroupingNodeInfo {
    /** Key of the grouping node. */
    key: GroupingNodeKey;
    /**
     * Depth of the grouping node in the hierarchy.
     * Generally, it can be retrieved from `parentKeys.length`.
     */
    depth: number;
}
/** @public */
export interface HierarchyFilteringPathOptions {
    /**
     * This option specifies the way `autoExpand` flag should be assigned to nodes in the filtered hierarchy.
     * - If it's `false` or `undefined`, nodes have no 'autoExpand' flag.
     * - If it's `true`, then all nodes up to the filter target will have `autoExpand` flag.
     * - If it's an instance of `FilterTargetGroupingNodeInfo`, then all nodes up to the grouping node that matches this property,
     * will have `autoExpand` flag.
     */
    autoExpand?: boolean | FilterTargetGroupingNodeInfo;
}
/**
 * A path of hierarchy node identifiers for filtering the hierarchy with additional options.
 * @public
 */
export type HierarchyFilteringPath = HierarchyNodeIdentifiersPath | {
    path: HierarchyNodeIdentifiersPath;
    options?: HierarchyFilteringPathOptions;
};
/** @public */
export declare namespace HierarchyFilteringPath {
    /**
     * Normalizes the hierarchy filtering path to the object form.
     * @public
     */
    function normalize(source: HierarchyFilteringPath): Exclude<HierarchyFilteringPath, HierarchyNodeIdentifiersPath>;
    /**
     * Merges two given `HierarchyFilteringPathOptions` objects.
     * - if both inputs are `undefined`, `undefined` is returned,
     * - else if one of the inputs is `undefined`, the other one is returned.
     * - else, merge each option individually.
     *
     * For the `autoExpand` attribute, the merge chooses to auto-expand as deep as the deepest input:
     * - if any one of the inputs is `true`, return `true`,
     * - else if both inputs are objects, return the one with the greater `depth` attribute.
     * - else if one input is an object, return it.
     * - else, return `false` or `undefined`.
     *
     * @public
     */
    function mergeOptions(lhs: HierarchyFilteringPathOptions | undefined, rhs: HierarchyFilteringPathOptions | undefined): HierarchyFilteringPathOptions | undefined;
}
/**
 * An utility that extracts filtering properties from given root level filtering props or
 * the parent node. Returns `undefined` if filtering props are not present.
 * @public
 * @deprecated in 1.3. Use `createHierarchyFilteringHelper` instead.
 */
export declare function extractFilteringProps(rootLevelFilteringProps: HierarchyFilteringPath[], parentNode: Pick<NonGroupingHierarchyNode, "filtering"> | undefined): {
    filteredNodePaths: HierarchyFilteringPath[];
    hasFilterTargetAncestor: boolean;
} | undefined;
/**
 * Creates a set of utilities for making it easier to filter the given hierarchy
 * level.
 *
 * @public
 */
export declare function createHierarchyFilteringHelper(rootLevelFilteringProps: HierarchyFilteringPath[] | undefined, parentNode: Pick<NonGroupingHierarchyNode, "filtering"> | undefined): {
    /**
     * Returns a flag indicating if the hierarchy level is filtered.
     */
    hasFilter: boolean;
    /**
     * Returns a flag indicating whether this hierarchy level has an ancestor node
     * that is a filter target. That generally means that this and all downstream hierarchy
     * levels should be displayed without filter being applied to them, even if filter paths
     * say otherwise.
     */
    hasFilterTargetAncestor: boolean;
    /**
     * Returns a list of hierarchy node identifiers that apply specifically for this
     * hierarchy level. Returns `undefined` if filtering is not applied to this level.
     */
    getChildNodeFilteringIdentifiers: () => HierarchyNodeIdentifier[] | undefined;
    /**
     * When a hierarchy node is created for a filtered hierarchy level, it needs some attributes (e.g. `filtering`
     * and `autoExpand`) to be set based on the filter paths and filtering options. This function calculates
     * these props for a child node based on its key or path matcher.
     *
     * When using `pathMatcher` prop, callers have more flexibility to decide whether the given `HierarchyNodeIdentifier` applies
     * to their node. For example, only some parts of the identifier can be checked for improved performance. Otherwise, the
     * `nodeKey` prop can be used to check the whole identifier.
     */
    createChildNodeProps: (props: {
        nodeKey: InstancesNodeKey | GenericNodeKey;
    } | {
        pathMatcher: (identifier: HierarchyNodeIdentifier) => boolean;
    }) => Pick<HierarchyNode, "filtering" | "autoExpand"> | undefined;
    /**
     * Similar to `createChildNodeProps`, but takes an async `pathMatcher` prop.
     */
    createChildNodePropsAsync: (props: {
        pathMatcher: (identifier: HierarchyNodeIdentifier) => boolean | Promise<boolean>;
    }) => Promise<Pick<HierarchyNode, "filtering" | "autoExpand"> | undefined> | Pick<HierarchyNode, "filtering" | "autoExpand"> | undefined;
};
//# sourceMappingURL=HierarchyFiltering.d.ts.map