@isrd-isi-edu/ermrestjs 2.0.1 → 2.1.1

package/README.md

@@ -1,6 +1,6 @@
 # ERMrestJS [![Build Status](https://github.com/informatics-isi-edu/ermrestjs/actions/workflows/unit-test.yml/badge.svg?branch=master)](https://github.com/informatics-isi-edu/ermrestjs/actions?query=workflow%3A%22ERmrestJS+tests%22+branch%3Amaster)
 
-ERMrestJS is a javascript client library for interacting with the [ERMrest](http://github.com/informatics-isi-edu/ermrest) service. It provides higher-level, simplified application programming interfaces (APIs) for working with the Entity-Relationship concepts native to ERMrest. 
+ERMrestJS is a javascript client library for interacting with the [ERMrest](http://github.com/informatics-isi-edu/ermrest) service. It provides higher-level, simplified application programming interfaces (APIs) for working with the Entity-Relationship concepts native to ERMrest.
 
 The library has been extended to also support [Hatrac](https://github.com/informatics-isi-edu/hatrac) (an object store service), and [deriva-web export](https://github.com/informatics-isi-edu/deriva-web). ERMrestJS is a part of [Deriva Platform](http://isrd.isi.edu/deriva).
 
@@ -29,7 +29,7 @@ Documents are categorized based on their audience.
 
 When developing new code for ERMrestJS, please make sure you're following these steps:
 
-1. create a new branch and make your updates to the code in the branch (avoid changing the `master` branch directly);
+1. create a new branch and make your updates to the code in the branch (follow DO NOT change `master` branch directly and ensure your commit messages follow [the convetions described here](docs/dev-docs/dev-guide.md#commit-message-conventions));
 2. do your own quality assurance;
 3. update all relevant documentation (Please refer to [this page](docs/dev-docs/update-docs.md) for more information);
 4. update the unit tests (if applicable);

package/js/core.js

@@ -481,7 +481,7 @@ import {
             // load the catalog (or use the one that is cached)
             this._get().then((response) => {
                 this.snaptime = response.snaptime;
-                
+
                 let versionCorrected = false;
                 if (isStringAndNotEmpty(this.version) && this.version !== this.snaptime) {
                     this.version = this.snaptime;
@@ -4351,7 +4351,7 @@ import {
             var definitions = this._table.sourceDefinitions, wm = _warningMessages;
             var logErr = function (bool, message, i) {
                 if (bool) {
-                    $log.info("inbound foreignkeys list for table: " + self._table.name + ", context: " + context + ", fk index:" + i);
+                    $log.info(`vis-fk for table '${self._table.name}' in context '${context}' at index '${i}':`);
                     $log.info(message);
                 }
                 return bool;

package/js/parser.js

@@ -858,11 +858,12 @@ import HistoryService from '@isrd-isi-edu/ermrestjs/src/services/history';
 
         /**
          * The datetime iso string representation of the catalog version
-         * @returns {String} the iso string or null if version is not specified
+         * @returns {String|null} the iso string or null if version is not specified
          */
         get versionAsISOString() {
             if (this._versionAsISOString === undefined) {
-                this._versionAsISOString = HistoryService.snapshotToDatetimeISO(this._version, false);
+                this._versionAsISOString = HistoryService.snapshotToDatetimeISO(this._version, true);
+                if (this._versionAsISOString === '') this._versionAsISOString = null;
             }
             return this._versionAsISOString;
         },
@@ -972,7 +973,7 @@ import HistoryService from '@isrd-isi-edu/ermrestjs/src/services/history';
 
         /**
          * filter is converted to the last join table (if uri has join)
-         * @returns {ParsedFilter} undefined if there is no filter
+         * @returns {ParsedFilter|undefined} undefined if there is no filter
          */
         get filter() {
             return this.lastPathPart ? this.lastPathPart.filter : undefined;
@@ -1059,7 +1060,7 @@ import HistoryService from '@isrd-isi-edu/ermrestjs/src/services/history';
 
         /**
          * facets object of the last path part
-         * @type {ParsedFacets} facets object
+         * @type {ParsedFacets|undefined} facets object
          */
         get facets() {
             return this.lastPathPart ? this.lastPathPart.facets : undefined;
@@ -1084,7 +1085,7 @@ import HistoryService from '@isrd-isi-edu/ermrestjs/src/services/history';
 
         /**
          * the custom facet of the last path part
-         * @type {CustomFacets}
+         * @type {CustomFacets|undefined}
          */
         get customFacets() {
             return this.lastPathPart ? this.lastPathPart.customFacets : undefined;

package/js/utils/helpers.js

@@ -642,6 +642,10 @@ import AuthnService from '@isrd-isi-edu/ermrestjs/src/services/authn';
 
     /**
      * Given the source object and default comment props, will return the comment that should be used.
+     * @param {any} sourceObject the object that might have comment props
+     * @param {string=} defaultComment the default comment that should be used if sourceObject doesn't have comment
+     * @param {boolean=} defaultCommentRenderMd the default comment_render_markdown that should be used if sourceObject doesn't have comment_render_markdown
+     * @param {string=} defaultDisplayMode the default comment_display that should be used if sourceObject doesn't have comment_display
      * @returns {CommentType}
      * @private
      */

package/js/utils/pseudocolumn_helpers.js

@@ -894,24 +894,61 @@ import { parse, _convertSearchTermToFilter } from '@isrd-isi-edu/ermrestjs/js/pa
         },
 
         /**
-         * Given a source object wrapper,  do we support the facet for it or not
-         * @ignore
+         * Given a source definition object, it will return a SourceObjectWrapper that can be used as a facet object.
+         * It will return null if the source definition is not supported as a facet.
+         *
+         * NOTE:
+         * - this function will remove any filter defined in the source definition if hasFilterOrFacet is true.
+         * - might throw an error if the source definition is invalid.
+         *
+         *
+         * @param {any} obj the source definition object
+         * @param {Table} table the table that this source definition is based on
+         * @param {boolean} hasFilterOrFacet whether the url has any filter or facet defined. If this is true, we will remove any filter defined in the source definition.
+         *
+         * @throws {Error} if the source definition is invalid for facet
+         *
+         * @returns {SourceObjectWrapper} the source object wrapper that can be used as a facet object.
          */
-        checkFacetObjectWrapper: function (facetObjectWrapper) {
-            var col = facetObjectWrapper.column;
+        sourceDefToFacetObjectWrapper: function (obj, table, hasFilterOrFacet) {
+            let wrapper;
+            // if both source and sourcekey are defined, ignore the source and use sourcekey
+            if (obj.sourcekey) {
+                const sd = table.sourceDefinitions.getSource(obj.sourcekey);
+                if (!sd) {
+                    throw new Error(_facetingErrors.invalidSourcekey);
+                }
+
+                wrapper = sd.clone(obj, table, true);
+            } else {
+                wrapper = new SourceObjectWrapper(obj, table, true);
+            }
+
+            const col = wrapper.column;
 
             // aggregate is not supported
-            if (facetObjectWrapper.hasAggregate) {
-                return false;
+            if (wrapper.hasAggregate) {
+                throw new Error(_facetingErrors.aggregateFnNowtAllowed);
             }
 
             // column type array is not supported
             if (col.type.isArray) {
-                return false;
+                throw new Error(_facetingErrors.arrayColumnTypeNotSupported);
             }
 
             // check the column type
-            return _facetUnsupportedTypes.indexOf(col.type.name) === -1;
+            if (_facetUnsupportedTypes.indexOf(col.type.name) !== -1) {
+                throw new Error(`Facet of column type '${col.type.name}' is not supported.`);
+            }
+
+            // if we have filters in the url, we will get the filters only from url
+            if (hasFilterOrFacet) {
+                delete wrapper.sourceObject.not_null;
+                delete wrapper.sourceObject.choices;
+                delete wrapper.sourceObject.search;
+                delete wrapper.sourceObject.ranges;
+            }
+            return wrapper;
         },
 
         /**
@@ -1003,7 +1040,10 @@ import { parse, _convertSearchTermToFilter } from '@isrd-isi-edu/ermrestjs/js/pa
          * NOTE: facetColumns MUST be only used in COMPACT_SELECT context
          * It doesn't feel right that I am doing contextualization in here,
          * it's something that should be in client.
-         * @ignore
+         * @param {SourceObjectWrapper} facetObjectWrapper the facet object
+         * @param {boolean} usedAnnotation the annotation that was used to create this facet (if any)
+         * @param {Table} table the current table that we want to make sure the facetObject is valid for.
+         * @returns {boolean} whether the facetObjectWrapper is valid for this table.
          */
         checkForAlternative: function (facetObjectWrapper, usedAnnotation, table) {
             var currTable = facetObjectWrapper.column.table;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@isrd-isi-edu/ermrestjs",
   "description": "ERMrest client library in JavaScript",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "license": "Apache-2.0",
   "engines": {
     "node": ">= 20.0.0",
@@ -19,12 +19,14 @@
   ],
   "scripts": {
     "build": "tsc && vite build",
+    "watch": "tsc --watch && vite build --watch",
     "pretest": "make deps-test && make dist-w-deps",
     "deploy": "make deploy",
     "test": "make test",
     "lint": "eslint src js --quiet",
     "lint-w-warn": "eslint src js",
-    "format": "prettier --write src"
+    "format": "prettier --write src",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
@@ -43,7 +45,7 @@
   "dependencies": {
     "@types/markdown-it": "^14.1.2",
     "@types/q": "^1.5.8",
-    "axios": "1.12.2",
+    "axios": "1.13.2",
     "handlebars": "4.7.8",
     "lz-string": "^1.5.0",
     "markdown-it": "12.3.2",
@@ -52,25 +54,28 @@
     "mustache": "x",
     "q": "1.5.1",
     "spark-md5": "^3.0.0",
-    "terser": "^5.43.1",
-    "typescript": "~5.8.3",
+    "terser": "^5.44.1",
+    "typescript": "~5.9.3",
     "vite": "^6.4.1",
     "vite-plugin-compression2": "^2.2.1"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
     "@eslint/js": "^9.36.0",
     "@isrd-isi-edu/ermrest-data-utils": "0.0.5",
+    "@semantic-release/git": "^10.0.1",
     "@types/node": "^24.6.1",
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
-    "file-api": "^0.10.4",
     "globals": "^16.4.0",
+    "husky": "^9.1.7",
     "jasmine": "2.5.3",
     "jasmine-expect": "3.7.1",
     "jasmine-spec-reporter": "2.5.0",
     "nock": "13.5.4",
-    "prettier": "^3.6.2",
+    "prettier": "^3.7.4",
     "require-reload": "^0.2.2",
     "rollup-plugin-visualizer": "^6.0.3",
     "typescript-eslint": "^8.45.0",

package/src/models/reference/reference.ts

@@ -18,6 +18,7 @@ import {
   KeyPseudoColumn,
   AssetPseudoColumn,
   InboundForeignKeyPseudoColumn,
+  type FacetGroup,
   type PseudoColumn,
   type ColumnAggregateFn,
 } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
@@ -124,8 +125,6 @@ export const resolve = async (uri: string, contextHeaderParams?: any): Promise<R
   // It should have been taken care by outer try but did not work
   const loc = parse(uri);
 
-  console.log(loc.catalog);
-
   const server = ermrestFactory.getServer(loc.service, contextHeaderParams);
 
   const catalog = await server.catalogs.get(loc.catalog);
@@ -239,6 +238,7 @@ export class Reference {
   private _referenceColumns?: Array<VisibleColumn>;
   private _related?: Array<RelatedReference>;
   private _facetColumns?: Array<FacetColumn>;
+  private _facetColumnsStructure?: Array<number | FacetGroup>;
   private _activeList?: any;
   private _citation?: Citation | null;
   private _googleDatasetMetadata?: GoogleDatasetMetadata | null;
@@ -614,19 +614,37 @@ export class Reference {
   }
 
   /**
-   * NOTE this will not map the entity choice pickers, use "generateFacetColumns" instead.
-   * so directly using this is not recommended.
+   * Returns the list of facets.
+   *
+   * NOTE this will not map the entity choice pickers, make sure to call "generateFacetColumns" first.
    */
   get facetColumns(): FacetColumn[] {
     if (this._facetColumns === undefined) {
       const res = generateFacetColumns(this, true);
       if (!(res instanceof Promise)) {
         this._facetColumns = res.facetColumns;
+        this._facetColumnsStructure = res.facetColumnsStructure;
       }
     }
     return this._facetColumns!;
   }
 
+  /**
+   * An array of numbers and FacetGroup objects that represent the structure of facet columns.
+   * Each number indicates the number of facet columns in that group, while a FacetGroup object
+   * represents a nested group of facets.
+   */
+  get facetColumnsStructure(): Array<number | FacetGroup> {
+    if (this._facetColumnsStructure === undefined) {
+      const res = generateFacetColumns(this, true);
+      if (!(res instanceof Promise)) {
+        this._facetColumns = res.facetColumns;
+        this._facetColumnsStructure = res.facetColumnsStructure;
+      }
+    }
+    return this._facetColumnsStructure!;
+  }
+
   /**
    * Returns the facets that should be represented to the user.
    * It will return a promise resolved with the following object:
@@ -663,14 +681,25 @@ export class Reference {
    * });
    * ```
    */
-  generateFacetColumns(): Promise<{ facetColumns: FacetColumn[]; issues: UnsupportedFilters | null }> {
+  generateFacetColumns(): Promise<{
+    facetColumns: FacetColumn[];
+    facetColumnsStructure: Array<number | FacetGroup>;
+    issues: UnsupportedFilters | null;
+  }> {
     return new Promise((resolve, reject) => {
-      const p = generateFacetColumns(this, false) as Promise<{ facetColumns: FacetColumn[]; issues: UnsupportedFilters | null }>;
+      const p = generateFacetColumns(this, false) as Promise<{
+        facetColumns: FacetColumn[];
+        issues: UnsupportedFilters | null;
+        facetColumnsStructure: Array<number | FacetGroup>;
+      }>;
+
       p.then((res) => {
         this._facetColumns = res.facetColumns;
+        this._facetColumnsStructure = res.facetColumnsStructure;
         resolve(res);
       }).catch((err) => {
         this._facetColumns = [];
+        this._facetColumnsStructure = [];
         reject(err);
       });
     });
@@ -680,8 +709,9 @@ export class Reference {
    * This is only added so _applyFilters in facet-column can use it.
    * SHOULD NOT be used outside of this library.
    */
-  manuallySetFacetColumns(facetCols: FacetColumn[]) {
+  manuallySetFacetColumns(facetCols: FacetColumn[], facetColsStructure: Array<number | FacetGroup>) {
     this._facetColumns = facetCols;
+    this._facetColumnsStructure = facetColsStructure;
   }
 
   /**
@@ -1195,11 +1225,11 @@ export class Reference {
 
   /**
    * Remove all the filters, facets, and custom-facets from the reference
-   * @param {boolean} sameFilter By default we're removing filters, if this is true filters won't be changed.
-   * @param {boolean} sameCustomFacet By default we're removing custom-facets, if this is true custom-facets won't be changed.
-   * @param {boolean} sameFacet By default we're removing facets, if this is true facets won't be changed.
+   * @param sameFilter By default we're removing filters, if this is true filters won't be changed.
+   * @param sameCustomFacet By default we're removing custom-facets, if this is true custom-facets won't be changed.
+   * @param sameFacet By default we're removing facets, if this is true facets won't be changed.
    *
-   * @return {reference} A reference without facet filters
+   * @return A reference without facet filters
    */
   removeAllFacetFilters(sameFilter?: boolean, sameCustomFacet?: boolean, sameFacet?: boolean) {
     verify(!(sameFilter && sameCustomFacet && sameFacet), 'at least one of the options must be false.');
@@ -1214,10 +1244,16 @@ export class Reference {
     //    compute that logic again, those facets will disappear.
     newReference._facetColumns = [];
     this.facetColumns.forEach((fc) => {
-      newReference._facetColumns!.push(new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, sameFacet ? fc.filters.slice() : []));
+      newReference._facetColumns!.push(
+        new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.groupIndex, sameFacet ? fc.filters.slice() : []),
+      );
+    });
+    newReference._facetColumnsStructure = [];
+    this.facetColumnsStructure.forEach((structure) => {
+      newReference._facetColumnsStructure!.push(typeof structure === 'number' ? structure : structure.copy(newReference));
     });
 
-    // update the location objectcd
+    // update the location object
     newReference._location = this._location._clone(newReference);
     newReference._location.beforeObject = null;
     newReference._location.afterObject = null;
@@ -1802,7 +1838,7 @@ export class Reference {
    * b) A single term with space using ""
    * c) use space for conjunction of terms
    */
-  search(term: string) {
+  search(term?: string | null) {
     if (term) {
       if (typeof term === 'string') term = term.trim();
       else throw new InvalidInputError('Invalid input. Seach expects a string.');
@@ -1822,7 +1858,13 @@ export class Reference {
     if (this._facetColumns !== undefined) {
       newReference._facetColumns = [];
       this.facetColumns.forEach((fc) => {
-        newReference._facetColumns!.push(new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.filters.slice()));
+        newReference._facetColumns!.push(new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.groupIndex, fc.filters.slice()));
+      });
+    }
+    if (this._facetColumnsStructure !== undefined) {
+      newReference._facetColumnsStructure = [];
+      this.facetColumnsStructure.forEach((structure) => {
+        newReference._facetColumnsStructure!.push(typeof structure === 'number' ? structure : structure.copy(newReference));
       });
     }
 
@@ -1859,7 +1901,13 @@ export class Reference {
     if (this._facetColumns !== undefined) {
       newReference._facetColumns = [];
       this.facetColumns.forEach((fc) => {
-        newReference._facetColumns!.push(new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.filters.slice()));
+        newReference._facetColumns!.push(new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.groupIndex, fc.filters.slice()));
+      });
+    }
+    if (this._facetColumnsStructure !== undefined) {
+      newReference._facetColumnsStructure = [];
+      this.facetColumnsStructure.forEach((structure) => {
+        newReference._facetColumnsStructure!.push(typeof structure === 'number' ? structure : structure.copy(newReference));
       });
     }
 

package/src/models/reference-column/facet-column.ts

@@ -1,7 +1,7 @@
 // models
 import SourceObjectWrapper from '@isrd-isi-edu/ermrestjs/src/models/source-object-wrapper';
 import type SourceObjectNode from '@isrd-isi-edu/ermrestjs/src/models/source-object-node';
-import { ReferenceColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
+import { FacetGroup, ReferenceColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
 import type { CommentType } from '@isrd-isi-edu/ermrestjs/src/models/comment';
 import type { DisplayName } from '@isrd-isi-edu/ermrestjs/src/models/display-name';
 import { type Tuple, Reference } from '@isrd-isi-edu/ermrestjs/src/models/reference';
@@ -163,7 +163,8 @@ class NotNullFacetFilter {
 
 /**
  * @param {Reference} reference the reference that this FacetColumn blongs to.
- * @param {int} index The index of this FacetColumn in the list of facetColumns
+ * @param {number} index The index of this FacetColumn in the list of facetColumns
+ * @param {number} structureIndex The index of this FacetColumn in the structure array
  * @param {SourceObjectWrapper} facetObjectWrapper The filter object that this FacetColumn will be created based on
  * @param {?FacetFilter[]} filters Array of filters
  */
@@ -180,10 +181,14 @@ export class FacetColumn {
 
   /**
    * The index of facetColumn in the list of facetColumns
-   * NOTE: Might not be needed
    */
   public index: number;
 
+  /**
+   * if part of the group, the index of that group in the facetColumnsStructure array
+   */
+  public groupIndex?: number;
+
   /**
    * A valid data-source path
    * NOTE: we're not validating this data-source, we assume that this is valid.
@@ -245,10 +250,17 @@ export class FacetColumn {
   private _choiceFilters?: ChoiceFacetFilter[];
   private _rangeFilters?: RangeFacetFilter[];
 
-  constructor(reference: Reference, index: number, facetObjectWrapper: SourceObjectWrapper, filters?: Array<FacetFilter | NotNullFacetFilter>) {
+  constructor(
+    reference: Reference,
+    index: number,
+    facetObjectWrapper: SourceObjectWrapper,
+    groupIndex?: number,
+    filters?: Array<FacetFilter | NotNullFacetFilter>,
+  ) {
     this._column = facetObjectWrapper.column!;
     this.reference = reference;
     this.index = index;
+    this.groupIndex = groupIndex;
     this.dataSource = facetObjectWrapper.sourceObject.source;
     this.compressedDataSource = _compressSource(this.dataSource);
 
@@ -1326,6 +1338,7 @@ export class FacetColumn {
     const loc = this.reference.location;
     const newReference = this.reference.copy();
     const facets: FacetColumn[] = [];
+    const facetColsStructure: Array<FacetGroup | number> = [];
 
     // create a new FacetColumn so it doesn't reference to the current FacetColum
     // TODO can be refactored
@@ -1337,9 +1350,9 @@ export class FacetColumn {
     let newFc: FacetColumn;
     this.reference.facetColumns.forEach((fc: FacetColumn) => {
       if (fc.index !== this.index) {
-        newFc = new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.filters.slice() as FacetFilter[]);
+        newFc = new FacetColumn(newReference, fc.index, fc.sourceObjectWrapper, fc.groupIndex, fc.filters.slice() as FacetFilter[]);
       } else {
-        newFc = new FacetColumn(newReference, this.index, this.sourceObjectWrapper, filters as FacetFilter[]);
+        newFc = new FacetColumn(newReference, this.index, this.sourceObjectWrapper, this.groupIndex, filters as FacetFilter[]);
       }
 
       facets.push(newFc);
@@ -1349,7 +1362,12 @@ export class FacetColumn {
       }
     });
 
-    newReference.manuallySetFacetColumns(facets);
+    // recreate the facetColumnsStructure so we don't have to recompute the whole thing.
+    this.reference.facetColumnsStructure.forEach((structure) => {
+      facetColsStructure.push(typeof structure === 'number' ? structure : structure.copy(newReference));
+    });
+
+    newReference.manuallySetFacetColumns(facets, facetColsStructure);
     newReference.setLocation(this.reference.location._clone(newReference));
     newReference.location.beforeObject = null;
     newReference.location.afterObject = null;

package/src/models/reference-column/facet-group.ts

@@ -0,0 +1,76 @@
+import type { DisplayName } from '@isrd-isi-edu/ermrestjs/src/models/display-name';
+import type { CommentType } from '@isrd-isi-edu/ermrestjs/src/models/comment';
+import type { FacetObjectGroupWrapper } from '@isrd-isi-edu/ermrestjs/src/models/source-object-wrapper';
+import type { Reference } from '@isrd-isi-edu/ermrestjs/src/models/reference';
+
+import { _processSourceObjectComment } from '@isrd-isi-edu/ermrestjs/js/utils/helpers';
+
+export class FacetGroup {
+  /**
+   * The reference that this facet blongs to
+   */
+  public reference: Reference;
+  /**
+   * the index of this group in the reference.facetColumnsStructure array
+   */
+  public structureIndex: number;
+  /**
+   * the facet object group wrapper from the source object
+   */
+  public facetObjectGroupWrapper: FacetObjectGroupWrapper;
+  /**
+   * the indices of the children facet columns in the facetColumns array
+   */
+  public children: Array<number>;
+
+  public displayname: DisplayName;
+  public comment: CommentType;
+
+  private _isOpen?: boolean;
+
+  constructor(reference: Reference, index: number, facetObjectGroupWrapper: FacetObjectGroupWrapper, children: Array<number>) {
+    this.reference = reference;
+    this.structureIndex = index;
+    this.facetObjectGroupWrapper = facetObjectGroupWrapper;
+    this.children = children;
+    this.displayname = facetObjectGroupWrapper.displayname;
+    this.comment = _processSourceObjectComment(facetObjectGroupWrapper.sourceObject);
+  }
+
+  /**
+   * whether the group should be opened by default or not
+   */
+  get isOpen(): boolean {
+    if (this._isOpen === undefined) {
+      // by default all groups are opened
+      let isOpen = true;
+
+      // if the source object has open property, use it
+      const sourceOpen = this.facetObjectGroupWrapper.sourceObject.open;
+      if (typeof sourceOpen === 'boolean') {
+        isOpen = sourceOpen;
+      }
+
+      // if any of the childrens have filters, the group should be opened
+      for (const child of this.facetObjectGroupWrapper.children) {
+        const facet = this.reference.facetColumns.find((fc) => fc.sourceObjectWrapper.name === child.name);
+        if (facet && facet.filters.length > 0) {
+          isOpen = true;
+          break;
+        }
+      }
+
+      this._isOpen = isOpen;
+    }
+    return this._isOpen;
+  }
+
+  /**
+   * creates a copy of this facet group for the new reference
+   * @param newReference the reference that the cloned facet group will belong to
+   * @returns a cloned facet group
+   */
+  copy(newReference?: Reference): FacetGroup {
+    return new FacetGroup(newReference ? newReference : this.reference, this.structureIndex, this.facetObjectGroupWrapper, this.children.slice());
+  }
+}

package/src/models/reference-column/index.ts

@@ -4,6 +4,7 @@
  * other files must import from here and not directly from each individual class
  */
 export * from '@isrd-isi-edu/ermrestjs/src/models/reference-column/reference-column';
+export * from '@isrd-isi-edu/ermrestjs/src/models/reference-column/facet-group';
 export * from '@isrd-isi-edu/ermrestjs/src/models/reference-column/facet-column';
 export * from '@isrd-isi-edu/ermrestjs/src/models/reference-column/pseudo-column';
 export * from '@isrd-isi-edu/ermrestjs/src/models/reference-column/foreign-key-pseudo-column';

package/src/models/source-object-wrapper.ts

@@ -1,22 +1,29 @@
 /* eslint-disable prettier/prettier */
 
 // models
-import SourceObjectNode from '@isrd-isi-edu/ermrestjs/src/models/source-object-node';
-import { ReferenceColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
-import { Tuple, Reference } from '@isrd-isi-edu/ermrestjs/src/models/reference';
+import type SourceObjectNode from '@isrd-isi-edu/ermrestjs/src/models/source-object-node';
+import type { ReferenceColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
+import type { Tuple, Reference } from '@isrd-isi-edu/ermrestjs/src/models/reference';
+import type { DisplayName } from '@isrd-isi-edu/ermrestjs/src/models/display-name';
 
 // services
-// import $log from '@isrd-isi-edu/ermrestjs/src/services/logger';
+import $log from '@isrd-isi-edu/ermrestjs/src/services/logger';
 
 // utils
 import { isObjectAndNotNull, isStringAndNotEmpty } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
-import { _contexts, _facetFilterTypes, _pseudoColAggregateFns, _sourceDefinitionAttributes, _warningMessages } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
+import {
+  _contexts,
+  _facetFilterTypes,
+  _pseudoColAggregateFns,
+  _sourceDefinitionAttributes,
+  _warningMessages,
+} from '@isrd-isi-edu/ermrestjs/src/utils/constants';
 import { renderMarkdown } from '@isrd-isi-edu/ermrestjs/src/utils/markdown-utils';
 import { createPseudoColumn } from '@isrd-isi-edu/ermrestjs/src/utils/column-utils';
 
 // legacy imports that need to be accessed
-import { _sourceColumnHelpers } from '@isrd-isi-edu/ermrestjs/js/utils/pseudocolumn_helpers';
-import { Column, Table } from '@isrd-isi-edu/ermrestjs/js/core';
+import { _facetColumnHelpers, _sourceColumnHelpers } from '@isrd-isi-edu/ermrestjs/js/utils/pseudocolumn_helpers';
+import type { Column, Table } from '@isrd-isi-edu/ermrestjs/js/core';
 
 export type FilterPropsType = {
   /**
@@ -68,7 +75,7 @@ export type InputIframePropsType = {
 /**
  * Represents a column-directive
  */
-class SourceObjectWrapper {
+export default class SourceObjectWrapper {
   /**
    * the source object
    */
@@ -107,7 +114,7 @@ class SourceObjectWrapper {
     isFilterProcessed: true,
     hasRootFilter: false,
     hasFilterInBetween: false,
-    leafFilterString: ''
+    leafFilterString: '',
   };
 
   /**
@@ -138,7 +145,6 @@ class SourceObjectWrapper {
   public isInputIframe = false;
   public inputIframeProps?: InputIframePropsType;
 
-
   /**
    * used for facets
    * TODO is there a better way to manage this?
@@ -152,6 +158,8 @@ class SourceObjectWrapper {
    * @param sources already generated source (only useful for source-def generation)
    * @param mainTuple the main tuple that is used for filters
    * @param skipProcessingFilters whether we should skip processing filters or not
+   *
+   * @throws Will throw an error if the source object is invalid.
    */
   constructor(
     sourceObject: Record<string, unknown>,
@@ -226,7 +234,7 @@ class SourceObjectWrapper {
     isFacet?: boolean,
     sources?: any,
     mainTuple?: Tuple,
-    skipProcessingFilters?: boolean
+    skipProcessingFilters?: boolean,
   ): true | { error: boolean; message: string } {
     const sourceObject = this.sourceObject;
     const wm = _warningMessages;
@@ -270,7 +278,7 @@ class SourceObjectWrapper {
         table.schema.catalog.id,
         sources,
         mainTuple,
-        skipProcessingFilters
+        skipProcessingFilters,
       ) as any;
 
       if (res.error) {
@@ -346,21 +354,13 @@ class SourceObjectWrapper {
 
     // generate name:
     // TODO maybe we shouldn't even allow aggregate in faceting (for now we're ignoring it)
-    if (
-      sourceObject.self_link === true ||
-      this.isFiltered ||
-      this.hasPath ||
-      this.isEntityMode ||
-      (isFacet !== true && this.hasAggregate)
-    ) {
+    if (sourceObject.self_link === true || this.isFiltered || this.hasPath || this.isEntityMode || (isFacet !== true && this.hasAggregate)) {
       this.name = _sourceColumnHelpers.generateSourceObjectHashName(sourceObject, !!isFacet, sourceObjectNodes) as string;
 
       this.isHash = true;
 
       if (table.columns.has(this.name)) {
-        return returnError(
-          'Generated Hash `' + this.name + '` for pseudo-column exists in table `' + table.name + '`.'
-        );
+        return returnError('Generated Hash `' + this.name + '` for pseudo-column exists in table `' + table.name + '`.');
       }
     } else {
       this.name = col.name;
@@ -403,19 +403,12 @@ class SourceObjectWrapper {
         if (reverse) {
           return sn.toString(reverse, isLeft, outAlias, isReverseRightJoin);
         } else {
-          return sn.toString(
-            reverse,
-            isLeft,
-            this.foreignKeyPathLength === sn.nodeObject.foreignKeyPathLength ? outAlias : null,
-            isReverseRightJoin
-          );
+          return sn.toString(reverse, isLeft, this.foreignKeyPathLength === sn.nodeObject.foreignKeyPathLength ? outAlias : null, isReverseRightJoin);
         }
       }
 
       const fkStr = sn.toString(reverse, isLeft);
-      const addAlias =
-        outAlias &&
-        ((reverse && sn === this.firstForeignKeyNode) || (!reverse && sn === this.lastForeignKeyNode));
+      const addAlias = outAlias && ((reverse && sn === this.firstForeignKeyNode) || (!reverse && sn === this.lastForeignKeyNode));
 
       // NOTE alias on each node is ignored!
       // currently we've added alias only for the association and
@@ -465,12 +458,7 @@ class SourceObjectWrapper {
       const sn = this.sourceObjectNodes[i];
       if (sn.isPathPrefix) {
         // if this is the last element, we have to add the alias to this
-        path.push(
-          ...sn.nodeObject.getRawSourcePath(
-            reverse,
-            this.foreignKeyPathLength == sn.nodeObject.foreignKeyPathLength ? outAlias : null
-          )
-        );
+        path.push(...sn.nodeObject.getRawSourcePath(reverse, this.foreignKeyPathLength == sn.nodeObject.foreignKeyPathLength ? outAlias : null));
       } else if (sn.isFilter) {
         path.push(sn.nodeObject);
       } else {
@@ -549,7 +537,11 @@ class SourceObjectWrapper {
    * @param usedIframeInputMappings an object capturing columns used in other mappings. used to avoid overlapping
    * @param tuple the tuple object
    */
-  processInputIframe(reference: Reference, usedIframeInputMappings: any, tuple?: Tuple): {
+  processInputIframe(
+    reference: Reference,
+    usedIframeInputMappings: any,
+    tuple?: Tuple,
+  ): {
     success?: boolean;
     error?: boolean;
     message?: string;
@@ -595,20 +587,14 @@ class SourceObjectWrapper {
         const isSerial = c.type.name.indexOf('serial') === 0;
 
         // we cannot use getInputDisabled since we just want to do this based on ACLs
-        if (
-          context === _contexts.CREATE &&
-          (c.isSystemColumn || c.isGeneratedPerACLs || isSerial)
-        ) {
+        if (context === _contexts.CREATE && (c.isSystemColumn || c.isGeneratedPerACLs || isSerial)) {
           if (colName in optionalFieldNames) continue;
           return {
             error: true,
             message: 'column `' + colName + '` cannot be modified by this user.',
           };
         }
-        if (
-          (context === _contexts.EDIT || context === _contexts.ENTRY) &&
-          (c.isSystemColumn || c.isImmutablePerACLs || isSerial)
-        ) {
+        if ((context === _contexts.EDIT || context === _contexts.ENTRY) && (c.isSystemColumn || c.isImmutablePerACLs || isSerial)) {
           if (colName in optionalFieldNames) continue;
           return {
             error: true,
@@ -660,7 +646,10 @@ class SourceObjectWrapper {
    * @param mainTuple
    * @param dontThrowError if set to true, will not throw an error if the filters are not valid
    */
-  processFilterNodes(mainTuple?: Tuple, dontThrowError?: boolean): {
+  processFilterNodes(
+    mainTuple?: Tuple,
+    dontThrowError?: boolean,
+  ): {
     success: boolean;
     error?: boolean;
     message?: string;
@@ -691,4 +680,65 @@ class SourceObjectWrapper {
   }
 }
 
-export default SourceObjectWrapper;
+/**
+ * Represents a facet object group
+ */
+export class FacetObjectGroupWrapper {
+  sourceObject: Record<string, unknown>;
+  children: SourceObjectWrapper[];
+  displayname: DisplayName;
+
+  /**
+   * Creates a new instance of FacetObjectGroupWrapper.
+   * Will throw an error if there was any issues in processing the source object.
+   *
+   * @param sourceObject The source object representing the facet group.
+   * @param table The table to which the facet group belongs.
+   * @param hasFilterOrFacet Indicates if the group has any filters or facets.
+   *
+   * @throws Will throw an error if the source object is invalid or has no valid children.
+   */
+  constructor(sourceObject: Record<string, unknown>, table: Table, hasFilterOrFacet: boolean) {
+    if (!Array.isArray(sourceObject.and) || sourceObject.and.length === 0) {
+      throw new Error('valid array of children is required');
+    }
+
+    this.sourceObject = sourceObject;
+
+    let displayname: DisplayName | null = null;
+    const rendered = renderMarkdown(
+      sourceObject.markdown_name && typeof sourceObject.markdown_name === 'string' ? sourceObject.markdown_name : '',
+      true,
+    );
+    if (rendered) {
+      displayname = {
+        value: rendered,
+        unformatted: sourceObject.markdown_name as string,
+        isHTML: true,
+      };
+    }
+
+    if (!displayname) {
+      throw new Error('valid markdown_name is required');
+    }
+
+    this.displayname = displayname;
+
+    const children: SourceObjectWrapper[] = [];
+    for (const child of sourceObject.and) {
+      try {
+        const wrapper = _facetColumnHelpers.sourceDefToFacetObjectWrapper(child, table, hasFilterOrFacet);
+        children.push(wrapper);
+      } catch (exp: unknown) {
+        $log.info(`child of facet group "${sourceObject.markdown_name}", index: ${children.length} is invalid:`);
+        $log.info((exp as Error).message);
+      }
+    }
+
+    if (children.length === 0) {
+      throw new Error('the group must have at least one valid child');
+    }
+
+    this.children = children;
+  }
+}

package/src/models/table-source-definitions.ts

@@ -81,8 +81,10 @@ class TableSourceDefinitions {
 
   /**
    * Get a source definition by its key.
+   * This will also make sure the filter nodes are processed and valid.
    * @param sourcekey The key of the source definition.
-   * @returns The source definition or undefined if not found.
+   * @param mainTuple The main tuple to use for processing the filter nodes.
+   * @returns The source object wrapper or undefined if not found.
    */
   getSource(sourcekey: string, mainTuple?: Tuple): SourceObjectWrapper | undefined {
     const sd = this.sources[sourcekey];

package/src/utils/constants.ts

@@ -353,6 +353,8 @@ export const _facetingErrors = Object.freeze({
   onlyOneNullFilter: 'Only one null filter is allowed in the facets',
   duplicateFacets: 'Cannot define two different sets of facets',
   invalidSourcekey: 'Given sourcekey string is not valid',
+  aggregateFnNowtAllowed: 'Aggregate functions are not allowed in facet source definition.',
+  arrayColumnTypeNotSupported: 'Facet of array column types are not supported.',
 });
 
 export const _HTTPErrorCodes = Object.freeze({
@@ -370,6 +372,7 @@ export const _HTTPErrorCodes = Object.freeze({
 
 export const _warningMessages = Object.freeze({
   NO_PSEUDO_IN_ENTRY: 'pseudo-columns are not allowed in entry contexts.',
+  INVALID_FACET_ENTRY: 'given value must be an object with either `source` or `sourcekey` defined.',
   INVALID_SOURCE: 'given object is invalid. `source` is required and it must be valid',
   INVALID_SOURCEKEY: 'given object is invalid. The defined `sourcekey` is invalid.',
   INVALID_VIRTUAL_NO_NAME: '`markdown_name` is required when `source` and `sourcekey` are undefiend.',

package/src/utils/reference-utils.ts

@@ -1,9 +1,10 @@
 // models
 import { InvalidPageCriteria, InvalidSortCriteria, UnsupportedFilters } from '@isrd-isi-edu/ermrestjs/src/models/errors';
-import SourceObjectWrapper from '@isrd-isi-edu/ermrestjs/src/models/source-object-wrapper';
+import SourceObjectWrapper, { FacetObjectGroupWrapper } from '@isrd-isi-edu/ermrestjs/src/models/source-object-wrapper';
 import {
   AssetPseudoColumn,
   FacetColumn,
+  FacetGroup,
   ForeignKeyPseudoColumn,
   InboundForeignKeyPseudoColumn,
   KeyPseudoColumn,
@@ -61,7 +62,7 @@ export interface ReadPathResult {
 }
 
 export type ValidatedFacetFilters = {
-  facetObjectWrappers: Array<SourceObjectWrapper>;
+  facetObjectWrappers: Array<SourceObjectWrapper | FacetObjectGroupWrapper>;
   newFilters: Array<any>;
   issues: UnsupportedFilters | null;
 };
@@ -522,6 +523,21 @@ export function generateColumnsList(reference: Reference | RelatedReference, tup
   const isCompact = typeof context === 'string' && context.startsWith(_contexts.COMPACT);
   const isCompactEntry = typeof context === 'string' && context.startsWith(_contexts.COMPACT_ENTRY);
 
+  // create a map of tableColumns to make it easier to find one
+  reference.table.columns.all().forEach((c: any) => {
+    tableColumns[c.name] = true;
+  });
+
+  // get columns from the input (used when we just want to process the given list of columns)
+  let columns: unknown = -1;
+  if (Array.isArray(columnsList)) {
+    columns = columnsList;
+  }
+  // get column orders from annotation
+  else if (reference.table.annotations.contains(_annotations.VISIBLE_COLUMNS)) {
+    columns = _getRecursiveAnnotationValue(reference.context, reference.table.annotations.get(_annotations.VISIBLE_COLUMNS).content);
+  }
+
   // check if we should hide some columns or not.
   // NOTE: if the reference is actually an inbound related reference, we should hide the foreign key that created reference link.
   const hasOrigFKRToHide = typeof context === 'string' && context.startsWith(_contexts.COMPACT_BRIEF) && isObjectAndNotNull(hiddenFKR);
@@ -596,29 +612,15 @@ export function generateColumnsList(reference: Reference | RelatedReference, tup
   };
 
   const wm = _warningMessages;
-  const logCol = (bool: boolean, message: string, index?: number) => {
+  const logCol = (bool: boolean, message: string, index: number) => {
     if (bool && !skipLog) {
-      $log.info(`columns list for table: ${reference.table.name}, context: ${context}, column index:${index}`);
+      $log.info(`vis-col for table '${reference.table.name}' in context '${context}' at index '${index}':`);
       $log.info(message);
+      // we could log the object too, but it might be too verbose
     }
     return bool;
   };
 
-  // create a map of tableColumns to make it easier to find one
-  reference.table.columns.all().forEach((c: any) => {
-    tableColumns[c.name] = true;
-  });
-
-  // get columns from the input (used when we just want to process the given list of columns)
-  let columns: unknown = -1;
-  if (Array.isArray(columnsList)) {
-    columns = columnsList;
-  }
-  // get column orders from annotation
-  else if (reference.table.annotations.contains(_annotations.VISIBLE_COLUMNS)) {
-    columns = _getRecursiveAnnotationValue(reference.context, reference.table.annotations.get(_annotations.VISIBLE_COLUMNS).content);
-  }
-
   // annotation
   if (columns !== -1 && Array.isArray(columns)) {
     for (let i = 0; i < columns.length; i++) {
@@ -724,7 +726,7 @@ export function generateColumnsList(reference: Reference | RelatedReference, tup
             wrapper = new SourceObjectWrapper(col, reference.table, false, undefined, tuple);
           }
         } catch (exp: unknown) {
-          logCol(true, wm.INVALID_SOURCE + ': ' + (exp as Error).message, i);
+          logCol(true, (exp as Error).message, i);
           continue;
         }
 
@@ -754,7 +756,7 @@ export function generateColumnsList(reference: Reference | RelatedReference, tup
             i,
           ) ||
           logCol(wrapper.hasAggregate && isEntry, wm.NO_AGG_IN_ENTRY, i) ||
-          logCol(wrapper.isUniqueFiltered, wm.FILTER_NO_PATH_NOT_ALLOWED) ||
+          logCol(wrapper.isUniqueFiltered, wm.FILTER_NO_PATH_NOT_ALLOWED, i) ||
           logCol(
             isEntry && wrapper.hasPath && (wrapper.hasInbound || wrapper.isFiltered || wrapper.foreignKeyPathLength > 1),
             wm.NO_PATH_IN_ENTRY,
@@ -1043,13 +1045,16 @@ export function generateColumnsList(reference: Reference | RelatedReference, tup
 export function generateFacetColumns(
   reference: Reference,
   skipMappingEntityChoices: boolean,
-): Promise<{ facetColumns: FacetColumn[]; issues: UnsupportedFilters | null }> | { facetColumns: FacetColumn[]; issues: UnsupportedFilters | null } {
+):
+  | Promise<{ facetColumns: FacetColumn[]; issues: UnsupportedFilters | null; facetColumnsStructure: Array<number | FacetGroup> }>
+  | { facetColumns: FacetColumn[]; issues: UnsupportedFilters | null; facetColumnsStructure: Array<number | FacetGroup> } {
   const andOperator = _FacetsLogicalOperators.AND;
+  const addedGroups: Record<string, boolean> = {};
   let searchTerm = reference.location.searchTerm;
   const helpers = _facetColumnHelpers;
 
   // if location has facet or filter, we should honor it and we should not add preselected facets in annotation
-  const hasFilterOrFacet = reference.location.facets || reference.location.filter || reference.location.customFacets;
+  const hasFilterOrFacet = !!reference.location.facets || !!reference.location.filter || !!reference.location.customFacets;
 
   const andFilters = reference.location.facets ? reference.location.facets.andFilters : [];
   // change filters to facet NOTE can be optimized to actually merge instead of just appending to list
@@ -1060,7 +1065,7 @@ export function generateFacetColumns(
 
   let annotationCols: any = -1;
   let usedAnnotation = false;
-  const facetObjectWrappers: any[] = [];
+  const facetObjectWrappers: Array<SourceObjectWrapper | FacetObjectGroupWrapper> = [];
 
   // get column orders from annotation
   if (reference.table.annotations.contains(_annotations.VISIBLE_COLUMNS)) {
@@ -1072,10 +1077,21 @@ export function generateFacetColumns(
     }
   }
 
+  const wm = _warningMessages;
+  const logError = (message: string, index: number) => {
+    $log.info(`vis-col for table '${reference.table.name}' in context 'filter' at index '${index}':`);
+    $log.info(message);
+  };
+
   if (annotationCols !== -1) {
     usedAnnotation = true;
     // NOTE We're allowing duplicates in annotation.
     annotationCols.forEach((obj: any, objIndex: number) => {
+      if (!isObjectAndNotNull(obj)) {
+        logError(wm.INVALID_FACET_ENTRY, objIndex);
+        return;
+      }
+
       // if we have filters in the url, we will get the filters only from url
       if (obj.sourcekey === _specialSourceDefinitions.SEARCH_BOX && andFilters.length === 0) {
         if (!searchTerm) {
@@ -1087,36 +1103,23 @@ export function generateFacetColumns(
       // make sure it's not referring to the annotation object.
       obj = simpleDeepCopy(obj);
 
-      let sd: any, wrapper: any;
       try {
-        // if both source and sourcekey are defined, ignore the source and use sourcekey
-        if (obj.sourcekey) {
-          sd = reference.table.sourceDefinitions.getSource(obj.sourcekey);
-          if (!sd || !sd.processFilterNodes(undefined).success) return;
-
-          wrapper = sd.clone(obj, reference.table, true);
+        if ('and' in obj) {
+          const fow = new FacetObjectGroupWrapper(obj, reference.table, hasFilterOrFacet);
+          // avoid duplicate groups
+          if (fow.displayname.unformatted! in addedGroups) {
+            throw new Error(`Duplicate facet group name: ${fow.displayname.unformatted}`);
+          }
+          addedGroups[fow.displayname.unformatted!] = true;
+          facetObjectWrappers.push(fow);
         } else {
-          wrapper = new SourceObjectWrapper(obj, reference.table, true);
+          const wrapper = helpers.sourceDefToFacetObjectWrapper(obj, reference.table, hasFilterOrFacet);
+          facetObjectWrappers.push(wrapper);
         }
       } catch (exp) {
-        $log.info(`facet definition index=${objIndex}: ` + exp);
-        // invalid definition or not unsupported
-        // TODO could show the error message
+        logError((exp as Error).message, objIndex);
         return;
       }
-
-      const supported = helpers.checkFacetObjectWrapper(wrapper);
-      if (!supported) return;
-
-      // if we have filters in the url, we will get the filters only from url
-      if (hasFilterOrFacet) {
-        delete wrapper.sourceObject.not_null;
-        delete wrapper.sourceObject.choices;
-        delete wrapper.sourceObject.search;
-        delete wrapper.sourceObject.ranges;
-      }
-
-      facetObjectWrappers.push(wrapper);
     });
   }
   // annotation didn't exist, so we are going to use the
@@ -1164,20 +1167,39 @@ export function generateFacetColumns(
   }
 
   // if we have filters in the url, we should just get the structure from annotation
-  const finalize = (res: any) => {
-    const facetColumns: any[] = [];
+  const finalize = (res: ValidatedFacetFilters) => {
+    const facetColumns: FacetColumn[] = [];
+    const facetColumnsStructure: Array<number | FacetGroup> = [];
 
     // turn facetObjectWrappers into facetColumn
-    res.facetObjectWrappers.forEach((fo: any, index: number) => {
-      // if the function returns false, it couldn't handle that case,
-      // and therefore we are ignoring it.
-      // it might change the fo
-      if (!helpers.checkForAlternative(fo, usedAnnotation, reference.table)) return;
-      facetColumns.push(new FacetColumn(reference, index, fo));
+    res.facetObjectWrappers.forEach((fo) => {
+      // if it's a group, we should create object for all children and add their index to the group
+      if ('children' in fo) {
+        // TODO should this be a proper check for FacetObjectGroupWrapper?
+        const structureIndex = facetColumnsStructure.length;
+        const childIndexes: number[] = [];
+        fo.children.forEach((child) => {
+          // if the function returns false, it couldn't handle that case, and therefore we are ignoring it.
+          if (!helpers.checkForAlternative(child, usedAnnotation, reference.table)) return;
+          const usedIndex = facetColumns.length;
+          facetColumns.push(new FacetColumn(reference, usedIndex, child, structureIndex));
+          childIndexes.push(usedIndex);
+        });
+        if (childIndexes.length === 0) return; // if there wasn't any valid child, ignore the group
+        facetColumnsStructure.push(new FacetGroup(reference, structureIndex, fo, childIndexes));
+      }
+      // individual facet column
+      else {
+        // if the function returns false, it couldn't handle that case, and therefore we are ignoring it.
+        if (!helpers.checkForAlternative(fo, usedAnnotation, reference.table)) return;
+        const usedIndex = facetColumns.length;
+        facetColumns.push(new FacetColumn(reference, usedIndex, fo));
+        facetColumnsStructure.push(usedIndex);
+      }
     });
 
     // get the existing facets on the columns (coming from annotation)
-    facetColumns.forEach((fc: any) => {
+    facetColumns.forEach((fc) => {
       if (fc.filters.length !== 0) {
         res.newFilters.push(fc.toJSON());
       }
@@ -1190,24 +1212,26 @@ export function generateFacetColumns(
       reference.location.facets = null;
     }
 
-    return facetColumns;
+    return { facetColumns, facetColumnsStructure };
   };
 
   // if we don't want to map entity choices, then function will work in sync mode
   if (skipMappingEntityChoices) {
     const res = validateFacetsFilters(reference, andFilters, facetObjectWrappers, searchTerm, skipMappingEntityChoices) as ValidatedFacetFilters;
-    const facetColumns = finalize(res);
+    const finalizedRes = finalize(res);
     return {
-      facetColumns,
+      facetColumns: finalizedRes.facetColumns,
+      facetColumnsStructure: finalizedRes.facetColumnsStructure,
       issues: res.issues,
     };
   } else {
     return new Promise((resolve, reject) => {
       (validateFacetsFilters(reference, andFilters, facetObjectWrappers, searchTerm, skipMappingEntityChoices) as Promise<ValidatedFacetFilters>)
         .then((res) => {
-          const facetColumns = finalize(res);
+          const finalizedRes = finalize(res);
           resolve({
-            facetColumns,
+            facetColumns: finalizedRes.facetColumns,
+            facetColumnsStructure: finalizedRes.facetColumnsStructure,
             issues: res.issues,
           });
         })
@@ -1234,14 +1258,14 @@ export function generateFacetColumns(
 export function validateFacetsFilters(
   reference: Reference,
   facetAndFilters: any,
-  facetObjectWrappers: Array<SourceObjectWrapper>,
+  facetObjectWrappers: Array<SourceObjectWrapper | FacetObjectGroupWrapper>,
   searchTerm?: string,
   skipMappingEntityChoices?: boolean,
   changeLocation?: boolean,
 ): ValidatedFacetFilters | Promise<ValidatedFacetFilters> {
   const helpers = _facetColumnHelpers;
   const promises: any[] = [];
-  const checkedObjects: { [key: number]: boolean } = {};
+  const checkedObjects: { [key: string]: boolean } = {};
   let j: number;
   const facetLen = facetObjectWrappers.length;
   let andFilterObject: SourceObjectWrapper;
@@ -1422,21 +1446,42 @@ export function validateFacetsFilters(
         // find the facet corresponding to the filter
         let found = false;
         for (j = 0; j < facetLen; j++) {
-          // it can be merged only once, since in a facet the filter is
-          // `or` and outside it's `and`.
-          if (checkedObjects[j]) continue;
-
-          // we want to make sure these two sources are exactly the same
-          // so we can compare their hashnames
-          if (res.facetObjectWrappers[j].name === resp.andFilterObject.name) {
-            checkedObjects[j] = true;
-            found = true;
-            // merge facet objects
-            helpers.mergeFacetObjects(res.facetObjectWrappers[j].sourceObject, resp.andFilterObject.sourceObject);
-
-            // make sure the page object is stored
-            if (resp.andFilterObject.entityChoiceFilterTuples) {
-              res.facetObjectWrappers[j].entityChoiceFilterTuples = resp.andFilterObject.entityChoiceFilterTuples;
+          const curr = res.facetObjectWrappers[j];
+
+          if (curr instanceof FacetObjectGroupWrapper) {
+            curr.children.forEach((child, childIndex) => {
+              if (checkedObjects[`${j}_${childIndex}`]) return;
+              if (child.name === resp.andFilterObject.name) {
+                checkedObjects[`${j}_${childIndex}`] = true;
+                found = true;
+                // merge facet objects
+                helpers.mergeFacetObjects(child.sourceObject, resp.andFilterObject.sourceObject);
+
+                // make sure the page object is stored
+                if (resp.andFilterObject.entityChoiceFilterTuples) {
+                  child.entityChoiceFilterTuples = resp.andFilterObject.entityChoiceFilterTuples;
+                }
+              }
+            });
+          } else {
+            // it can be merged only once, since in a facet the filter is
+            // `or` and outside it's `and`.
+            if (checkedObjects[j]) continue;
+
+            const facetObjectWrapper = curr as SourceObjectWrapper;
+
+            // we want to make sure these two sources are exactly the same
+            // so we can compare their hashnames
+            if (facetObjectWrapper.name === resp.andFilterObject.name) {
+              checkedObjects[j] = true;
+              found = true;
+              // merge facet objects
+              helpers.mergeFacetObjects(facetObjectWrapper.sourceObject, resp.andFilterObject.sourceObject);
+
+              // make sure the page object is stored
+              if (resp.andFilterObject.entityChoiceFilterTuples) {
+                facetObjectWrapper.entityChoiceFilterTuples = resp.andFilterObject.entityChoiceFilterTuples;
+              }
             }
           }
         }

package/vite.config.mts

@@ -51,7 +51,7 @@ export default defineConfig(async (): Promise<UserConfig> => {
       'process.env.NODE_ENV': JSON.stringify(mode),
     },
     build: {
-      minify: 'terser',
+      minify: isDev ? false : 'terser',
       reportCompressedSize: false,
       sourcemap: isDev,
       lib: {