@itwin/presentation-common 4.0.0-dev.10 → 4.0.0-dev.101

package/lib/esm/presentation-common/content/ContentTraverser.d.ts

@@ -1,272 +1,272 @@
-/** @packageDocumentation
- * @module Content
- */
-import { CategoryDescription } from "./Category";
-import { Content } from "./Content";
-import { Descriptor } from "./Descriptor";
-import { Field } from "./Fields";
-import { Item } from "./Item";
-import { TypeDescription } from "./TypeDescription";
-import { DisplayValue, DisplayValuesArray, DisplayValuesMap, Value, ValuesArray, ValuesMap } from "./Value";
-/**
- * A data structure to define a hierarchy of [[Field]] objects.
- * @public
- */
-export interface FieldHierarchy {
-    /** Parent field. */
-    field: Field;
-    /** Nested fields. */
-    childFields: FieldHierarchy[];
-}
-/**
- * Props for the [[IContentVisitor.startContent]] call.
- * @public
- */
-export interface StartContentProps {
-    /** Descriptor of the visited content. */
-    descriptor: Descriptor;
-}
-/**
- * Props for the [[IContentVisitor.processFieldHierarchies]] call.
- * @public
- */
-export interface ProcessFieldHierarchiesProps {
-    /**
-     * The root list of fields, which may be mutated by the visitor to change order or the fields,
-     * add new fields, etc.
-     */
-    hierarchies: FieldHierarchy[];
-}
-/**
- * Props for the [[IContentVisitor.startItem]] call.
- * @public
- */
-export interface StartItemProps {
-    /** The content item that's about to be visited. */
-    item: Item;
-}
-/**
- * Props for the [[IContentVisitor.startCategory]] call.
- * @public
- */
-export interface StartCategoryProps {
-    /** The content category that's about to be visited. */
-    category: CategoryDescription;
-}
-/**
- * Props for the [[IContentVisitor.startField]] call.
- * @public
- */
-export interface StartFieldProps {
-    /** The field that's about to be visited. */
-    hierarchy: FieldHierarchy;
-}
-/**
- * Props for the [[IContentVisitor.startStruct]] call.
- * @public
- */
-export interface StartStructProps {
-    /** Field that describes the struct. */
-    hierarchy: FieldHierarchy;
-    /** Type of the struct. */
-    valueType: TypeDescription;
-    /** Name of the parent field (if there is one). */
-    parentFieldName?: string;
-    /** Member raw values. */
-    rawValues: ValuesMap;
-    /** Member display values. */
-    displayValues: DisplayValuesMap;
-}
-/**
- * Props for the [[IContentVisitor.startArray]] call.
- * @public
- */
-export interface StartArrayProps {
-    /** Field that describes the array. */
-    hierarchy: FieldHierarchy;
-    /** Type of the array. */
-    valueType: TypeDescription;
-    /** Name of the parent field (if there is one). */
-    parentFieldName?: string;
-    /** Item raw values. */
-    rawValues: ValuesArray;
-    /** Item display values. */
-    displayValues: DisplayValuesArray;
-}
-/**
- * Props for the [[IContentVisitor.processMergedValue]] call.
- * @public
- */
-export interface ProcessMergedValueProps {
-    /** The field whose values are merged. */
-    mergedField: Field;
-    /**
-     * Generally this matches the [[mergedField]], but there are situations when a nested field is propagated
-     * up to display it as if it wasn't nested its parent fields. In those cases, if one of the parent fields
-     * is merged, the merged parent is going to be represented by [[mergedField]] and the field we wanted to
-     * process is going to be represented by [[requestedField]].
-     */
-    requestedField: Field;
-    /** Name of the parent field (if there is one). */
-    parentFieldName?: string;
-}
-/**
- * Props for the [[IContentVisitor.processPrimitiveValue]] call.
- * @public
- */
-export interface ProcessPrimitiveValueProps {
-    /** Field whose value is being processed. */
-    field: Field;
-    /** Type of the value. */
-    valueType: TypeDescription;
-    /** Name of the parent field (if there is one). */
-    parentFieldName?: string;
-    /** Raw value. */
-    rawValue: Value;
-    /** Display value. */
-    displayValue: DisplayValue;
-}
-/**
- * An interface for a visitor that can be passed to the [[traverseContent]] function
- * to be called on each piece of content.
- *
- * The order of calls when using the visitor with [[traverseContent]] or [[traverseContentItem]]:
- *
- * ```
- * startContent
- *   processFieldHierarchies
- *   for each content item:
- *     startItem
- *     for each field in root level:
- *       for each category in field's category stack from root to field's category:
- *         startCategory
- *       startField
- *         valueProcessing:
- *           if item's value for this field is merged:
- *             processMergedValue
- *           else if the field is struct:
- *             startStruct
- *             for each struct member:
- *               recurse into the valueProcessing step
- *             finishStruct
- *           else if the field is array:
- *             startArray
- *             for each array item:
- *               recurse into the valueProcessing step
- *             finishArray
- *           else if the field is primitive:
- *             processPrimitiveValue
- *       finishField
- *     finishItem
- * finishContent
- * ```
- * @public
- */
-export interface IContentVisitor {
-    /**
-     * Called before starting [[Content]] processing. This is a good place to initialize various caches and prepare
-     * for parsing content.
-     *
-     * Processing is skipped if the function returns `false` and [[finishContent]] is not called in that case.
-     */
-    startContent(props: StartContentProps): boolean;
-    /** Called after processing of [[Content]] is complete. */
-    finishContent(): void;
-    /** Called to post-process field hierarchies after they're extracted from [[Descriptor]] in processed [[Content]]. */
-    processFieldHierarchies(props: ProcessFieldHierarchiesProps): void;
-    /**
-     * Called before starting each [[Item]] processing. This is a good place to initialize for a new content item, e.g.
-     * set up a new row in table.
-     *
-     * Processing is skipped if the function returns `false` and [[finishItem]] is not called in that case.
-     */
-    startItem(props: StartItemProps): boolean;
-    /**
-     * Called after processing of [[Item]] is complete. May be used to do any kind of post-processing after all
-     * values for one content item have been processed.
-     */
-    finishItem(): void;
-    /**
-     * Called before processing a content item field ([[startField]] call) for each category in the field's
-     * category stack, starting from the root and finishing with the field's category.
-     *
-     * Processing is skipped if the function returns `false` and [[finishCategory]] is not called in that case.
-     */
-    startCategory(props: StartCategoryProps): boolean;
-    /** Called after processing of field is complete for every category in the field's category stack. */
-    finishCategory(): void;
-    /**
-     * Called before starting [[Field]] processing for each individual [[Item]]. This is a good callback
-     * to skip a field if it doesn't need to be handled.
-     *
-     * Processing is skipped if the function returns `false` and [[finishField]] is not called in that case.
-     */
-    startField(props: StartFieldProps): boolean;
-    /** Called after processing of [[Field]] for individual [[Item]] is complete. */
-    finishField(): void;
-    /**
-     * Called before processing a struct value. This is a good callback to skip handling the value or set up
-     * for struct member values handling.
-     *
-     * Processing is skipped if the function returns `false` and [[finishStruct]] is not called in that case.
-     */
-    startStruct(props: StartStructProps): boolean;
-    /** Called after processing of struct value is complete. */
-    finishStruct(): void;
-    /**
-     * Called before processing an array value. This is a good callback to skip handling the value or set up
-     * for array items handling.
-     *
-     * Processing is skipped if the function returns `false` and [[finishArray]] is not called in that case.
-     */
-    startArray(props: StartArrayProps): boolean;
-    /** Called after processing of array value is complete. */
-    finishArray(): void;
-    /** Called to process a [merged value]($docs/presentation/content/Terminology.md#value-merging). */
-    processMergedValue(props: ProcessMergedValueProps): void;
-    /** Called to process a primitive value. */
-    processPrimitiveValue(props: ProcessPrimitiveValueProps): void;
-}
-/**
- * An utility for traversing field hierarchy. Stops traversal as soon as `cb` returns `false`.
- * @public
- */
-export declare function traverseFieldHierarchy(hierarchy: FieldHierarchy, cb: (h: FieldHierarchy) => boolean): void;
-/**
- * An utility to traverse content using provided visitor. Provides means to parse content into different formats,
- * for different components.
- * @public
- */
-export declare function traverseContent(visitor: IContentVisitor, content: Content): void;
-/**
- * An utility for calling [[traverseContent]] when there's only one content item.
- * @public
- */
-export declare function traverseContentItem(visitor: IContentVisitor, descriptor: Descriptor, item: Item): void;
-/**
- * Parses a list of [[Field]] objects into a list of [[FieldHierarchy]].
- *
- * @param ignoreCategories Enables adding all of the `nestedFields` to parent field's `childFields`
- * without considering categories.
- *
- * @public
- */
-export declare function createFieldHierarchies(fields: Field[], ignoreCategories?: Boolean): FieldHierarchy[];
-/**
- * Adds a field hierarchy into root field hierarchies list. *
- * @public
- */
-export declare function addFieldHierarchy(rootHierarchies: FieldHierarchy[], hierarchy: FieldHierarchy): void;
-/** @internal */
-export declare const FIELD_NAMES_SEPARATOR = "$";
-/**
- * Combines given field names in a way that allows them to be parsed back into a list of individual names using the [[parseCombinedFieldNames]] function.
- * @public
- */
-export declare function combineFieldNames(fieldName: string, parentFieldName?: string): string;
-/**
- * Parses given combined field names string, constructed using [[combineFieldNames]], into a list of individual field names.
- * @public
- */
-export declare function parseCombinedFieldNames(combinedName: string): string[];
+/** @packageDocumentation
+ * @module Content
+ */
+import { CategoryDescription } from "./Category";
+import { Content } from "./Content";
+import { Descriptor } from "./Descriptor";
+import { Field } from "./Fields";
+import { Item } from "./Item";
+import { TypeDescription } from "./TypeDescription";
+import { DisplayValue, DisplayValuesArray, DisplayValuesMap, Value, ValuesArray, ValuesMap } from "./Value";
+/**
+ * A data structure to define a hierarchy of [[Field]] objects.
+ * @public
+ */
+export interface FieldHierarchy {
+    /** Parent field. */
+    field: Field;
+    /** Nested fields. */
+    childFields: FieldHierarchy[];
+}
+/**
+ * Props for the [[IContentVisitor.startContent]] call.
+ * @public
+ */
+export interface StartContentProps {
+    /** Descriptor of the visited content. */
+    descriptor: Descriptor;
+}
+/**
+ * Props for the [[IContentVisitor.processFieldHierarchies]] call.
+ * @public
+ */
+export interface ProcessFieldHierarchiesProps {
+    /**
+     * The root list of fields, which may be mutated by the visitor to change order or the fields,
+     * add new fields, etc.
+     */
+    hierarchies: FieldHierarchy[];
+}
+/**
+ * Props for the [[IContentVisitor.startItem]] call.
+ * @public
+ */
+export interface StartItemProps {
+    /** The content item that's about to be visited. */
+    item: Item;
+}
+/**
+ * Props for the [[IContentVisitor.startCategory]] call.
+ * @public
+ */
+export interface StartCategoryProps {
+    /** The content category that's about to be visited. */
+    category: CategoryDescription;
+}
+/**
+ * Props for the [[IContentVisitor.startField]] call.
+ * @public
+ */
+export interface StartFieldProps {
+    /** The field that's about to be visited. */
+    hierarchy: FieldHierarchy;
+}
+/**
+ * Props for the [[IContentVisitor.startStruct]] call.
+ * @public
+ */
+export interface StartStructProps {
+    /** Field that describes the struct. */
+    hierarchy: FieldHierarchy;
+    /** Type of the struct. */
+    valueType: TypeDescription;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Member raw values. */
+    rawValues: ValuesMap;
+    /** Member display values. */
+    displayValues: DisplayValuesMap;
+}
+/**
+ * Props for the [[IContentVisitor.startArray]] call.
+ * @public
+ */
+export interface StartArrayProps {
+    /** Field that describes the array. */
+    hierarchy: FieldHierarchy;
+    /** Type of the array. */
+    valueType: TypeDescription;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Item raw values. */
+    rawValues: ValuesArray;
+    /** Item display values. */
+    displayValues: DisplayValuesArray;
+}
+/**
+ * Props for the [[IContentVisitor.processMergedValue]] call.
+ * @public
+ */
+export interface ProcessMergedValueProps {
+    /** The field whose values are merged. */
+    mergedField: Field;
+    /**
+     * Generally this matches the [[mergedField]], but there are situations when a nested field is propagated
+     * up to display it as if it wasn't nested its parent fields. In those cases, if one of the parent fields
+     * is merged, the merged parent is going to be represented by [[mergedField]] and the field we wanted to
+     * process is going to be represented by [[requestedField]].
+     */
+    requestedField: Field;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+}
+/**
+ * Props for the [[IContentVisitor.processPrimitiveValue]] call.
+ * @public
+ */
+export interface ProcessPrimitiveValueProps {
+    /** Field whose value is being processed. */
+    field: Field;
+    /** Type of the value. */
+    valueType: TypeDescription;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Raw value. */
+    rawValue: Value;
+    /** Display value. */
+    displayValue: DisplayValue;
+}
+/**
+ * An interface for a visitor that can be passed to the [[traverseContent]] function
+ * to be called on each piece of content.
+ *
+ * The order of calls when using the visitor with [[traverseContent]] or [[traverseContentItem]]:
+ *
+ * ```
+ * startContent
+ *   processFieldHierarchies
+ *   for each content item:
+ *     startItem
+ *     for each field in root level:
+ *       for each category in field's category stack from root to field's category:
+ *         startCategory
+ *       startField
+ *         valueProcessing:
+ *           if item's value for this field is merged:
+ *             processMergedValue
+ *           else if the field is struct:
+ *             startStruct
+ *             for each struct member:
+ *               recurse into the valueProcessing step
+ *             finishStruct
+ *           else if the field is array:
+ *             startArray
+ *             for each array item:
+ *               recurse into the valueProcessing step
+ *             finishArray
+ *           else if the field is primitive:
+ *             processPrimitiveValue
+ *       finishField
+ *     finishItem
+ * finishContent
+ * ```
+ * @public
+ */
+export interface IContentVisitor {
+    /**
+     * Called before starting [[Content]] processing. This is a good place to initialize various caches and prepare
+     * for parsing content.
+     *
+     * Processing is skipped if the function returns `false` and [[finishContent]] is not called in that case.
+     */
+    startContent(props: StartContentProps): boolean;
+    /** Called after processing of [[Content]] is complete. */
+    finishContent(): void;
+    /** Called to post-process field hierarchies after they're extracted from [[Descriptor]] in processed [[Content]]. */
+    processFieldHierarchies(props: ProcessFieldHierarchiesProps): void;
+    /**
+     * Called before starting each [[Item]] processing. This is a good place to initialize for a new content item, e.g.
+     * set up a new row in table.
+     *
+     * Processing is skipped if the function returns `false` and [[finishItem]] is not called in that case.
+     */
+    startItem(props: StartItemProps): boolean;
+    /**
+     * Called after processing of [[Item]] is complete. May be used to do any kind of post-processing after all
+     * values for one content item have been processed.
+     */
+    finishItem(): void;
+    /**
+     * Called before processing a content item field ([[startField]] call) for each category in the field's
+     * category stack, starting from the root and finishing with the field's category.
+     *
+     * Processing is skipped if the function returns `false` and [[finishCategory]] is not called in that case.
+     */
+    startCategory(props: StartCategoryProps): boolean;
+    /** Called after processing of field is complete for every category in the field's category stack. */
+    finishCategory(): void;
+    /**
+     * Called before starting [[Field]] processing for each individual [[Item]]. This is a good callback
+     * to skip a field if it doesn't need to be handled.
+     *
+     * Processing is skipped if the function returns `false` and [[finishField]] is not called in that case.
+     */
+    startField(props: StartFieldProps): boolean;
+    /** Called after processing of [[Field]] for individual [[Item]] is complete. */
+    finishField(): void;
+    /**
+     * Called before processing a struct value. This is a good callback to skip handling the value or set up
+     * for struct member values handling.
+     *
+     * Processing is skipped if the function returns `false` and [[finishStruct]] is not called in that case.
+     */
+    startStruct(props: StartStructProps): boolean;
+    /** Called after processing of struct value is complete. */
+    finishStruct(): void;
+    /**
+     * Called before processing an array value. This is a good callback to skip handling the value or set up
+     * for array items handling.
+     *
+     * Processing is skipped if the function returns `false` and [[finishArray]] is not called in that case.
+     */
+    startArray(props: StartArrayProps): boolean;
+    /** Called after processing of array value is complete. */
+    finishArray(): void;
+    /** Called to process a [merged value]($docs/presentation/content/Terminology.md#value-merging). */
+    processMergedValue(props: ProcessMergedValueProps): void;
+    /** Called to process a primitive value. */
+    processPrimitiveValue(props: ProcessPrimitiveValueProps): void;
+}
+/**
+ * An utility for traversing field hierarchy. Stops traversal as soon as `cb` returns `false`.
+ * @public
+ */
+export declare function traverseFieldHierarchy(hierarchy: FieldHierarchy, cb: (h: FieldHierarchy) => boolean): void;
+/**
+ * An utility to traverse content using provided visitor. Provides means to parse content into different formats,
+ * for different components.
+ * @public
+ */
+export declare function traverseContent(visitor: IContentVisitor, content: Content): void;
+/**
+ * An utility for calling [[traverseContent]] when there's only one content item.
+ * @public
+ */
+export declare function traverseContentItem(visitor: IContentVisitor, descriptor: Descriptor, item: Item): void;
+/**
+ * Parses a list of [[Field]] objects into a list of [[FieldHierarchy]].
+ *
+ * @param ignoreCategories Enables adding all of the `nestedFields` to parent field's `childFields`
+ * without considering categories.
+ *
+ * @public
+ */
+export declare function createFieldHierarchies(fields: Field[], ignoreCategories?: Boolean): FieldHierarchy[];
+/**
+ * Adds a field hierarchy into root field hierarchies list. *
+ * @public
+ */
+export declare function addFieldHierarchy(rootHierarchies: FieldHierarchy[], hierarchy: FieldHierarchy): void;
+/** @internal */
+export declare const FIELD_NAMES_SEPARATOR = "$";
+/**
+ * Combines given field names in a way that allows them to be parsed back into a list of individual names using the [[parseCombinedFieldNames]] function.
+ * @public
+ */
+export declare function combineFieldNames(fieldName: string, parentFieldName?: string): string;
+/**
+ * Parses given combined field names string, constructed using [[combineFieldNames]], into a list of individual field names.
+ * @public
+ */
+export declare function parseCombinedFieldNames(combinedName: string): string[];
 //# sourceMappingURL=ContentTraverser.d.ts.map