@itwin/presentation-common 3.6.0-dev.8 → 4.0.0-dev.2

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

@@ -8,95 +8,265 @@ import { Field } from "./Fields";
 import { Item } from "./Item";
 import { TypeDescription } from "./TypeDescription";
 import { DisplayValue, DisplayValuesArray, DisplayValuesMap, Value, ValuesArray, ValuesMap } from "./Value";
-/** @alpha */
+/**
+ * A data structure to define a hierarchy of [[Field]] objects.
+ * @public
+ */
 export interface FieldHierarchy {
+    /** Parent field. */
     field: Field;
+    /** Nested fields. */
     childFields: FieldHierarchy[];
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startContent]] call.
+ * @public
+ */
 export interface StartContentProps {
+    /** Descriptor of the visited content. */
     descriptor: Descriptor;
 }
-/** @alpha */
+/**
+ * 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[];
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startItem]] call.
+ * @public
+ */
 export interface StartItemProps {
+    /** The content item that's about to be visited. */
     item: Item;
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startCategory]] call.
+ * @public
+ */
 export interface StartCategoryProps {
+    /** The content category that's about to be visited. */
     category: CategoryDescription;
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startField]] call.
+ * @public
+ */
 export interface StartFieldProps {
+    /** The field that's about to be visited. */
     hierarchy: FieldHierarchy;
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startStruct]] call.
+ * @public
+ */
 export interface StartStructProps {
+    /** Field that describes the struct. */
     hierarchy: FieldHierarchy;
+    /** Type of the struct. */
     valueType: TypeDescription;
-    namePrefix?: string;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Member raw values. */
     rawValues: ValuesMap;
+    /** Member display values. */
     displayValues: DisplayValuesMap;
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.startArray]] call.
+ * @public
+ */
 export interface StartArrayProps {
+    /** Field that describes the array. */
     hierarchy: FieldHierarchy;
+    /** Type of the array. */
     valueType: TypeDescription;
-    namePrefix?: string;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Item raw values. */
     rawValues: ValuesArray;
+    /** Item display values. */
     displayValues: DisplayValuesArray;
 }
-/** @alpha */
+/**
+ * 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;
-    namePrefix?: string;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
 }
-/** @alpha */
+/**
+ * Props for the [[IContentVisitor.processPrimitiveValue]] call.
+ * @public
+ */
 export interface ProcessPrimitiveValueProps {
+    /** Field whose value is being processed. */
     field: Field;
+    /** Type of the value. */
     valueType: TypeDescription;
-    namePrefix?: string;
+    /** Name of the parent field (if there is one). */
+    parentFieldName?: string;
+    /** Raw value. */
     rawValue: Value;
+    /** Display value. */
     displayValue: DisplayValue;
 }
-/** @alpha */
+/**
+ * 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;
 }
-/** @internal */
+/**
+ * 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;
-/** @alpha */
+/**
+ * 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;
-/** @alpha */
+/**
+ * An utility for calling [[traverseContent]] when there's only one content item.
+ * @public
+ */
 export declare function traverseContentItem(visitor: IContentVisitor, descriptor: Descriptor, item: Item): void;
 /**
-  * `ignoreCategories` parameter enables adding all of the `nestedFields` to parent field's `childFields`
-  *  without considering categories.
-  *  @internal
+ * 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[];
-/** @alpha */
+/**
+ * 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 = "$";
-/** @internal */
-export declare function applyOptionalPrefix(str: string, prefix?: string): string;
+/**
+ * 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

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

@@ -1 +1 @@
-{"version":3,"file":"ContentTraverser.d.ts","sourceRoot":"","sources":["../../../../src/presentation-common/content/ContentTraverser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ContentTraverser.d.ts","sourceRoot":"","sources":["../../../../src/presentation-common/content/ContentTraverser.ts"],"names":[],"mappings":"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"}

package/lib/esm/presentation-common/content/ContentTraverser.js

@@ -6,16 +6,24 @@
  * @module Content
  */
 import { assert, using } from "@itwin/core-bentley";
+import { Content } from "./Content";
 import { Field } from "./Fields";
 import { Item } from "./Item";
 import { PropertyValueFormat } from "./TypeDescription";
 import { DisplayValue, Value } from "./Value";
-/** @internal */
+/**
+ * An utility for traversing field hierarchy. Stops traversal as soon as `cb` returns `false`.
+ * @public
+ */
 export function traverseFieldHierarchy(hierarchy, cb) {
     if (cb(hierarchy))
         hierarchy.childFields.forEach((childHierarchy) => traverseFieldHierarchy(childHierarchy, cb));
 }
-/** @alpha */
+/**
+ * An utility to traverse content using provided visitor. Provides means to parse content into different formats,
+ * for different components.
+ * @public
+ */
 export function traverseContent(visitor, content) {
     if (!visitor.startContent({ descriptor: content.descriptor }))
         return;
@@ -30,18 +38,12 @@ export function traverseContent(visitor, content) {
         visitor.finishContent();
     }
 }
-/** @alpha */
+/**
+ * An utility for calling [[traverseContent]] when there's only one content item.
+ * @public
+ */
 export function traverseContentItem(visitor, descriptor, item) {
-    if (!visitor.startContent({ descriptor }))
-        return;
-    try {
-        const fieldHierarchies = createFieldHierarchies(descriptor.fields);
-        visitor.processFieldHierarchies({ hierarchies: fieldHierarchies });
-        traverseContentItemFields(visitor, fieldHierarchies, item);
-    }
-    finally {
-        visitor.finishContent();
-    }
+    traverseContent(visitor, new Content(descriptor, [item]));
 }
 class VisitedCategories {
     constructor(_visitor, category) {
@@ -91,27 +93,27 @@ function traverseContentItemField(visitor, fieldHierarchy, item) {
         return;
     try {
         const rootToThisField = createFieldPath(fieldHierarchy.field);
-        let namePrefix;
+        let parentFieldName;
         const pathUpToField = rootToThisField.slice(undefined, -1);
         for (let i = 0; i < pathUpToField.length; ++i) {
             const parentField = pathUpToField[i];
             const nextField = rootToThisField[i + 1];
             if (item.isFieldMerged(parentField.name)) {
-                visitor.processMergedValue({ requestedField: fieldHierarchy.field, mergedField: parentField, namePrefix });
+                visitor.processMergedValue({ requestedField: fieldHierarchy.field, mergedField: parentField, parentFieldName });
                 return;
             }
             const { emptyNestedItem, convertedItem } = convertNestedContentItemToStructArrayItem(item, parentField, nextField);
             if (emptyNestedItem)
                 return;
             item = convertedItem;
-            namePrefix = applyOptionalPrefix(parentField.name, namePrefix);
+            parentFieldName = combineFieldNames(parentField.name, parentFieldName);
         }
         if (item.isFieldMerged(fieldHierarchy.field.name)) {
-            visitor.processMergedValue({ requestedField: fieldHierarchy.field, mergedField: fieldHierarchy.field, namePrefix });
+            visitor.processMergedValue({ requestedField: fieldHierarchy.field, mergedField: fieldHierarchy.field, parentFieldName });
             return;
         }
         if (fieldHierarchy.field.isNestedContentField()) {
-            fieldHierarchy = convertNestedContentFieldHierarchyToStructArrayHierarchy(fieldHierarchy, namePrefix);
+            fieldHierarchy = convertNestedContentFieldHierarchyToStructArrayHierarchy(fieldHierarchy, parentFieldName);
             const { emptyNestedItem, convertedItem } = convertNestedContentFieldHierarchyItemToStructArrayItem(item, fieldHierarchy);
             if (emptyNestedItem)
                 return;
@@ -129,49 +131,49 @@ function traverseContentItemField(visitor, fieldHierarchy, item) {
                 }),
             };
         }
-        traverseContentItemFieldValue(visitor, fieldHierarchy, item.mergedFieldNames, fieldHierarchy.field.type, namePrefix, item.values[fieldHierarchy.field.name], item.displayValues[fieldHierarchy.field.name]);
+        traverseContentItemFieldValue(visitor, fieldHierarchy, item.mergedFieldNames, fieldHierarchy.field.type, parentFieldName, item.values[fieldHierarchy.field.name], item.displayValues[fieldHierarchy.field.name]);
     }
     finally {
         visitor.finishField();
     }
 }
-function traverseContentItemFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValue, displayValue) {
+function traverseContentItemFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValue, displayValue) {
     if (rawValue !== undefined) {
         if (valueType.valueFormat === PropertyValueFormat.Array) {
             assert(Value.isArray(rawValue));
             assert(DisplayValue.isArray(displayValue));
-            return traverseContentItemArrayFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValue, displayValue);
+            return traverseContentItemArrayFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValue, displayValue);
         }
         if (valueType.valueFormat === PropertyValueFormat.Struct) {
             assert(Value.isMap(rawValue));
             assert(DisplayValue.isMap(displayValue));
-            return traverseContentItemStructFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValue, displayValue);
+            return traverseContentItemStructFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValue, displayValue);
         }
     }
-    traverseContentItemPrimitiveFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValue, displayValue);
+    traverseContentItemPrimitiveFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValue, displayValue);
 }
-function traverseContentItemArrayFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValues, displayValues) {
+function traverseContentItemArrayFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValues, displayValues) {
     assert(rawValues.length === displayValues.length);
     assert(valueType.valueFormat === PropertyValueFormat.Array);
-    if (!visitor.startArray({ hierarchy: fieldHierarchy, valueType, namePrefix, rawValues, displayValues }))
+    if (!visitor.startArray({ hierarchy: fieldHierarchy, valueType, parentFieldName, rawValues, displayValues }))
         return;
     try {
         const itemType = valueType.memberType;
         rawValues.forEach((_, i) => {
-            traverseContentItemFieldValue(visitor, fieldHierarchy, mergedFieldNames, itemType, namePrefix, rawValues[i], displayValues[i]);
+            traverseContentItemFieldValue(visitor, fieldHierarchy, mergedFieldNames, itemType, parentFieldName, rawValues[i], displayValues[i]);
         });
     }
     finally {
         visitor.finishArray();
     }
 }
-function traverseContentItemStructFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValues, displayValues) {
+function traverseContentItemStructFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValues, displayValues) {
     assert(valueType.valueFormat === PropertyValueFormat.Struct);
-    if (!visitor.startStruct({ hierarchy: fieldHierarchy, valueType, namePrefix, rawValues, displayValues }))
+    if (!visitor.startStruct({ hierarchy: fieldHierarchy, valueType, parentFieldName, rawValues, displayValues }))
         return;
     try {
         if (fieldHierarchy.field.isNestedContentField())
-            namePrefix = applyOptionalPrefix(fieldHierarchy.field.name, namePrefix);
+            parentFieldName = combineFieldNames(fieldHierarchy.field.name, parentFieldName);
         valueType.members.forEach((memberDescription) => {
             let memberField = fieldHierarchy.childFields.find((f) => f.field.name === memberDescription.name);
             if (!memberField) {
@@ -182,24 +184,27 @@ function traverseContentItemStructFieldValue(visitor, fieldHierarchy, mergedFiel
                     childFields: [],
                 };
             }
-            traverseContentItemFieldValue(visitor, memberField, mergedFieldNames, memberDescription.type, namePrefix, rawValues[memberDescription.name], displayValues[memberDescription.name]);
+            traverseContentItemFieldValue(visitor, memberField, mergedFieldNames, memberDescription.type, parentFieldName, rawValues[memberDescription.name], displayValues[memberDescription.name]);
         });
     }
     finally {
         visitor.finishStruct();
     }
 }
-function traverseContentItemPrimitiveFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, namePrefix, rawValue, displayValue) {
+function traverseContentItemPrimitiveFieldValue(visitor, fieldHierarchy, mergedFieldNames, valueType, parentFieldName, rawValue, displayValue) {
     if (-1 !== mergedFieldNames.indexOf(fieldHierarchy.field.name)) {
-        visitor.processMergedValue({ mergedField: fieldHierarchy.field, requestedField: fieldHierarchy.field, namePrefix });
+        visitor.processMergedValue({ mergedField: fieldHierarchy.field, requestedField: fieldHierarchy.field, parentFieldName });
         return;
     }
-    visitor.processPrimitiveValue({ field: fieldHierarchy.field, valueType, namePrefix, rawValue, displayValue });
+    visitor.processPrimitiveValue({ field: fieldHierarchy.field, valueType, parentFieldName, rawValue, displayValue });
 }
 /**
-  * `ignoreCategories` parameter enables adding all of the `nestedFields` to parent field's `childFields`
-  *  without considering categories.
-  *  @internal
+ * 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 function createFieldHierarchies(fields, ignoreCategories) {
     const hierarchies = new Array();
@@ -291,7 +296,10 @@ function mergeHierarchies(lhs, rhs) {
     });
     return result;
 }
-/** @alpha */
+/**
+ * Adds a field hierarchy into root field hierarchies list. *
+ * @public
+ */
 export function addFieldHierarchy(rootHierarchies, hierarchy) {
     var _a;
     const match = findRelatedFields(rootHierarchies, hierarchy);
@@ -318,9 +326,19 @@ function createFieldPath(field) {
 }
 /** @internal */
 export const FIELD_NAMES_SEPARATOR = "$";
-/** @internal */
-export function applyOptionalPrefix(str, prefix) {
-    return prefix ? `${prefix}${FIELD_NAMES_SEPARATOR}${str}` : str;
+/**
+ * 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 function combineFieldNames(fieldName, parentFieldName) {
+    return parentFieldName ? `${parentFieldName}${FIELD_NAMES_SEPARATOR}${fieldName}` : fieldName;
+}
+/**
+ * Parses given combined field names string, constructed using [[combineFieldNames]], into a list of individual field names.
+ * @public
+ */
+export function parseCombinedFieldNames(combinedName) {
+    return combinedName ? combinedName.split(FIELD_NAMES_SEPARATOR) : [];
 }
 function convertNestedContentItemToStructArrayItem(item, field, nextField) {
     var _a;
@@ -346,11 +364,11 @@ function convertNestedContentItemToStructArrayItem(item, field, nextField) {
     const convertedItem = new Item(item.primaryKeys, item.label, item.imageId, item.classInfo, { [nextField.name]: nextFieldValues.raw }, { [nextField.name]: nextFieldValues.display }, item.mergedFieldNames, item.extendedData); // eslint-disable-line deprecation/deprecation
     return { emptyNestedItem: false, convertedItem };
 }
-function convertNestedContentFieldHierarchyToStructArrayHierarchy(fieldHierarchy, namePrefix) {
+function convertNestedContentFieldHierarchyToStructArrayHierarchy(fieldHierarchy, parentFieldName) {
     const fieldName = fieldHierarchy.field.name;
     const convertedChildFieldHierarchies = fieldHierarchy.childFields.map((child) => {
         if (child.field.isNestedContentField())
-            return convertNestedContentFieldHierarchyToStructArrayHierarchy(child, applyOptionalPrefix(fieldName, namePrefix));
+            return convertNestedContentFieldHierarchyToStructArrayHierarchy(child, combineFieldNames(fieldName, parentFieldName));
         return child;
     });
     const convertedFieldHierarchy = {