Merge branch '20.0.x' into rivanova/fix-16057-20.0.x

Author: ChronosSF

projects/igniteui-angular/src/lib/grids/common/grid.interface.ts

@@ -295,19 +295,63 @@ export interface RowType {
      */
     unpin?: () => void;
 }
-
+/**
+ * Describes a field that can be used in the Grid and QueryBuilder components.
+ */
 export interface FieldType {
+    /**
+     * Display label for the field.
+     */
     label?: string;
+
+    /**
+     * The internal field name, used in expressions and queries.
+     */
     field: string;
+
+    /**
+     * Optional column header for UI display purposes.
+     */
     header?: string;
+
+    /**
+     * The data type of the field.
+     */
     /* alternateType: GridColumnDataType */
     dataType: DataType;
+
+    /**
+     * Options for the editor associated with this field.
+     */
     editorOptions?: IFieldEditorOptions;
+
+    /**
+     * Optional filtering operands that apply to this field.
+     */
     filters?: IgxFilteringOperand;
+
+    /**
+     * Optional arguments for any pipe applied to the field.
+     */
     pipeArgs?: IFieldPipeArgs;
+
+    /**
+     * Default time format for Date/Time fields.
+     */
     defaultTimeFormat?: string;
+
+    /**
+     * Default date/time format for Date/Time fields.
+     */
     defaultDateTimeFormat?: string;
 
+    /**
+     * Optional formatter function to transform the value before display.
+     *
+     * @param value - The value of the field.
+     * @param rowData - Optional row data that contains this field.
+     * @returns The formatted value.
+     */
     formatter?(value: any, rowData?: any): any;
 }
 
@@ -1492,10 +1536,24 @@ export interface IClipboardOptions {
 }
 
 /**
- * An interface describing entity
+ * Describes an entity in the QueryBuilder.
+ * An entity represents a logical grouping of fields and can have nested child entities.
  */
 export interface EntityType {
+    /**
+     * The name of the entity.
+     * Typically used as an identifier in expressions.
+     */
     name: string;
+
+    /**
+     * The list of fields that belong to this entity.
+     */
     fields: FieldType[];
+
+    /**
+     * Optional child entities.
+     * This allows building hierarchical or nested query structures.
+     */
     childEntities?: EntityType[];
 }

projects/igniteui-angular/src/lib/query-builder/query-builder.component.ts

@@ -51,16 +51,40 @@ export class IgxQueryBuilderComponent implements OnDestroy {
     public showEntityChangeDialog = true;
 
     /**
-     * Returns the entities.
-     * @hidden
+     * Gets the list of entities available for the IgxQueryBuilderComponent.
+     *
+     * Each entity describes a logical group of fields that can be used in queries.
+     * An entity can optionally have child entities, allowing nested sub-queries.
+     *
+     * @returns An array of {@link EntityType} objects.
      */
     public get entities(): EntityType[] {
         return this._entities;
     }
 
     /**
-     * Sets the entities.
-     * @hidden
+     * Sets the list of entities for the IgxQueryBuilderComponent.
+     * If the `expressionTree` is defined, it will be recreated with the new entities.
+     *
+     * Each entity should be an {@link EntityType} object describing the fields and optionally child entities.
+     *
+     * Example:
+     * ```ts
+     * [
+     *   {
+     *     name: 'Orders',
+     *     fields: [{ field: 'OrderID', dataType: 'number' }],
+     *     childEntities: [
+     *       {
+     *         name: 'OrderDetails',
+     *         fields: [{ field: 'ProductID', dataType: 'number' }]
+     *       }
+     *     ]
+     *   }
+     * ]
+     * ```
+     *
+     * @param entities - The array of entities to set.
      */
     @Input()
     public set entities(entities: EntityType[]) {
@@ -73,18 +97,22 @@ export class IgxQueryBuilderComponent implements OnDestroy {
     }
 
     /**
-     * Returns the fields.
+     * Gets the list of fields for the QueryBuilder.
+     *
+     * @deprecated since version 19.1.0. Use the `entities` property instead.
      * @hidden
-     * @deprecated in version 19.1.0. Use the `entities` property instead.
      */
     public get fields(): FieldType[] {
         return this._fields;
     }
 
     /**
-     * Sets the fields.
+     * Sets the list of fields for the QueryBuilder.
+     * Automatically wraps them into a single entity to maintain backward compatibility.
+     *
+     * @param fields - The array of fields to set.
+     * @deprecated since version 19.1.0. Use the `entities` property instead.
      * @hidden
-     * @deprecated in version 19.1.0. Use the `entities` property instead.
      */
     @Input()
     public set fields(fields: FieldType[]) {