@itwin/presentation-hierarchies
Version:
A package for creating hierarchies based on data in iTwin.js iModels.
187 lines • 8.75 kB
TypeScript
import { HierarchyNode, NonGroupingHierarchyNode } from "./HierarchyNode.js";
import { HierarchyNodeIdentifier, HierarchyNodeIdentifiersPath } from "./HierarchyNodeIdentifier.js";
import { GenericNodeKey, GroupingNodeKey, InstancesNodeKey } from "./HierarchyNodeKey.js";
/**
* @public
* @deprecated in 1.7. Use `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
export interface FilterTargetGroupingNodeInfo {
/**
* Key of the grouping node.
* @deprecated in 1.6. Use `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
key: GroupingNodeKey;
/**
* Depth up to which nodes in the hierarchy should be expanded.
* @deprecated in 1.6. Use `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
depth: number;
}
/**
* @public
* @deprecated in 1.7. Use `FilteringPathAutoExpandDepthInPath` or `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
export interface FilteringPathAutoExpandOption {
/**
* Depth up to which nodes in the hierarchy should be expanded.
*
* If `includeGroupingNodes` is set to true, then depth should take into account the number of grouping nodes in hierarchy.
* @deprecated in 1.7. Use `FilteringPathAutoExpandDepthInPath` or `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
depth: number;
/**
* Whether or not `depth` includes grouping nodes.
*
* Use when you want to autoExpand only some of the grouping nodes.
*
* **Use case example:**
*
* You want to `autoExpand` only `Node1` and `GroupingNode1` in the following hierarchy:
* - Node1
* - GroupingNode1
* - GroupingNode2
* - Element1
* - Element2
* Then you provide `autoExpand: { depth: 2, includeGroupingNodes: true }`
*
* To get the correct depth use `HierarchyNode.parentKeys.length`.
* @deprecated in 1.7. Use `FilteringPathAutoExpandDepthInHierarchy` instead.
*/
includeGroupingNodes?: boolean;
}
/** @public */
export interface FilteringPathAutoExpandDepthInPath {
/**
* Depth that tells which nodes in the filtering path should be expanded.
*
* Use when you want to expand up to specific instance node and don't care about grouping nodes.
*
* **NOTE**: All nodes that are up to `depthInPath` will be expanded. Node at the `depthInPath` position won't be expanded.
*/
depthInPath: number;
}
/** @public */
export interface FilteringPathAutoExpandDepthInHierarchy {
/**
* Depth that tells which nodes in the hierarchy should be expanded.
*
* This should take into account the number of grouping nodes in hierarchy.
*
* * **Use case example:**
*
* You want to `autoExpand` only `Node1` and `GroupingNode1` in the following hierarchy:
* - Node1
* - GroupingNode1
* - GroupingNode2
* - Element1
* - Element2
* Then you provide `autoExpand: { depthInHierarchy: 2 }`
*
* To get the correct depth use `HierarchyNode.parentKeys.length`.
*
* **NOTE**: All nodes that are up to and including `depthInHierarchy` will be expanded.
*/
depthInHierarchy: 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.
* - If it's an instance of `FilteringPathAutoExpandOption`, then all nodes up to and including `depth` will have `autoExpand` flag.
* - If it's an instance of `FilteringPathAutoExpandDepthInPath`, then all nodes up to `depthInPath` will have `autoExpand` flag.
* - If it's an instance of `FilteringPathAutoExpandDepthInHierarchy`, then all nodes up to and including `depthInHierarchy` will have `autoExpand` flag.
*/
autoExpand?: boolean | FilterTargetGroupingNodeInfo | FilteringPathAutoExpandOption | FilteringPathAutoExpandDepthInHierarchy | FilteringPathAutoExpandDepthInPath;
}
/**
* 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 only one of the inputs is an object, return it,
* - else if both inputs are falsy, return `false` or `undefined`,
* - else:
* - if only one of the inputs has `includeGroupingNodes` set to `true` or `key` defined or `depthInHierarchy` set, return the other one,
* - else return the one with greater `depth`, `depthInPath` or `depthInHierarchy`.
*
* @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" | "parentKeys"> | 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, "autoExpand" | "filtering"> | undefined;
/**
* Similar to `createChildNodeProps`, but takes an async `pathMatcher` prop.
*/
createChildNodePropsAsync: (props: {
pathMatcher: (identifier: HierarchyNodeIdentifier) => boolean | Promise<boolean>;
}) => Promise<Pick<HierarchyNode, "autoExpand" | "filtering"> | undefined> | Pick<HierarchyNode, "autoExpand" | "filtering"> | undefined;
};
//# sourceMappingURL=HierarchyFiltering.d.ts.map