feat: listbox properties spec

apis/nucleus/src/components/listbox/default-properties.js

@@ -1,7 +1,32 @@
+/**
+ * see: https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FValueExpression
+ * @name ValueExpression
+ * @type object
+ * @property {string} qValueExpression.qExpr
+ */
+
+/**
+ * Extends `ListObjectDef`, see Engine API: `ListObjectDef`.
+ * @interface ListObjectDef
+ * @extends EngineAPI.IListObjectDef
+ * @property {boolean} [frequencyEnabled=false] Show frequency count. also requires qListObjectDef.qFrequencyMode to be set
+ */
+
+/**
+ * @name ListboxProperties
+ * @type object
+ */
+
+/**
+ * @lends ListboxProperties
+ */
 const listdef = {
   qInfo: {
     qType: 'njsListbox',
   },
+  /**
+   * @type {ListObjectDef}
+   */
   qListObjectDef: {
     qStateName: '',
     qShowAlternatives: true,
@@ -26,15 +51,125 @@ const listdef = {
       ],
     },
   },
+  /**
+   * Show histogram bar.
+   * also requires (qListObjectDef.qFrequencyMode 'V' and frequencyMax) or qListObjectDef.qFrequencyMode 'P'
+   * @type {boolean=}
+   * @default
+   */
   histogram: false,
+  /**
+   * frequencyMax calculation
+   * needed for histogram when not using qListObjectDef.qFrequencyMode: 'P'
+   * use an expression in the form `Max(AGGR(Count([field]), [field]))` (when needed)
+   * or 'fetch' that triggers an extra engine call but needed for library dimension that could change field when using the object
+   * @type {('fetch' | ValueExpression)=}
+   */
+  frequencyMax: undefined,
+  /**
+   * Show values as checkboxes instead of as fields.
+   * @type {boolean=}
+   * @default
+   */
   checkboxes: false,
+  /**
+   * enables search.
+   * @type {boolean=}
+   * @default
+   */
+  searchEnabled: true,
+  /**
+   * show title.
+   * @type {boolean=}
+   * @default
+   */
+  showTitle: true,
+  /**
+   * start search with wildcard search.
+   * @type {boolean=}
+   * @default
+   */
+  wildCardSearch: false,
+  /**
+   * layout settings.
+   * @type {object=}
+   */
   layoutOptions: {
+    /**
+     * dense mode.
+     * @type {boolean=}
+     * @default
+     */
     dense: false,
+    /**
+     * layout mode.
+     * @type {('singleColumn' | 'grid')=}
+     * @default
+     */
     dataLayout: 'singleColumn',
+    /**
+     * layout order.
+     * Only used when dataLayout is 'grid'
+     * @type {('row' | 'column')=}
+     * @default
+     */
     layoutOrder: 'row',
-    maxVisibleColumns: { auto: true },
-    maxVisibleRows: { auto: true },
+    /**
+     * max visible columns.
+     * Only used when dataLayout is 'grid'
+     * and layoutOrder is 'row'
+     * @type {object=}
+     */
+    maxVisibleColumns: {
+      /**
+       * auto max visible columns. (as many as it can fit)
+       * Only used when dataLayout is 'grid'
+       * and layoutOrder is 'row'
+       * @type {boolean=}
+       * @default
+       */
+      auto: true,
+      /**
+       * fixed number of max visible columns.
+       * Only used when dataLayout is 'grid'
+       * layoutOrder is 'row'
+       * and auto is false
+       * @type {number=}
+       * @default
+       */
+      maxColumns: 3,
+    },
+    /**
+     * max visible rows.
+     * Only used when dataLayout is 'grid'
+     * and layoutOrder is 'column'
+     * @type {object=}
+     */
+    maxVisibleRows: {
+      /**
+       * auto max visible rows. (as many as it can fit)
+       * Only used when dataLayout is 'grid'
+       * and layoutOrder is 'column'
+       * @type {boolean=}
+       * @default
+       */
+      auto: true,
+      /**
+       * fixed number of max visible rows.
+       * Only used when dataLayout is 'grid'
+       * layoutOrder is 'column'
+       * and auto is false
+       * @type {number=}
+       * @default
+       */
+      maxRows: 3,
+    },
   },
+  /**
+   * listbox title
+   * @type {string=}
+   * @default
+   */
   title: '',
 };
 export default listdef;

apis/nucleus/src/components/listbox/hooks/__tests__/useOnTheFlyModel.test.jsx

@@ -109,9 +109,11 @@ describe('useExistingModel', () => {
         layoutOrder: 'row',
         maxVisibleColumns: {
           auto: true,
+          maxColumns: 3,
         },
         maxVisibleRows: {
           auto: true,
+          maxRows: 3,
         },
       });
 
@@ -121,7 +123,7 @@ describe('useExistingModel', () => {
         dense: false,
         dataLayout: 'grid',
         layoutOrder: 'column',
-        maxVisibleColumns: { auto: true },
+        maxVisibleColumns: { auto: true, maxColumns: 3 },
         maxVisibleRows: { auto: false, maxRows: 1 },
       });
     });
@@ -136,9 +138,11 @@ describe('useExistingModel', () => {
         layoutOrder: 'row',
         maxVisibleColumns: {
           auto: true,
+          maxColumns: 3,
         },
         maxVisibleRows: {
           auto: true,
+          maxRows: 3,
         },
       });
     });

apis/nucleus/src/index.js

@@ -480,7 +480,7 @@ function nuked(configuration = {}) {
            * @param {boolean=} [options.checkboxes=false] Show values as checkboxes instead of as fields (not applicable for existing objects)
            * @param {boolean=} [options.dense=false] Reduces padding and text size (not applicable for existing objects)
            * @param {string=} [options.stateName="$"] Sets the state to make selections in (not applicable for existing objects)
-           * @param {object=} [options.properties={}] Properties object to extend default properties with
+           * @param {ListboxProperties=} [options.properties={}] Properties object to extend default properties with
            * @returns {Promise<void>} A promise that resolves when the data is fetched.
            *
            * @since 1.1.0

apis/nucleus/src/object/__tests__/filterpane-handler.test.js

@@ -39,6 +39,9 @@ describe('filterpane-handler', () => {
               qType: expect.any(String),
             },
             title: 'A',
+            searchEnabled: true,
+            showTitle: true,
+            wildCardSearch: false,
             checkboxes: false,
             histogram: false,
             layoutOptions: {
@@ -47,9 +50,11 @@ describe('filterpane-handler', () => {
               layoutOrder: 'row',
               maxVisibleColumns: {
                 auto: true,
+                maxColumns: 3,
               },
               maxVisibleRows: {
                 auto: true,
+                maxRows: 3,
               },
             },
             qListObjectDef: {
@@ -95,6 +100,9 @@ describe('filterpane-handler', () => {
               qType: expect.any(String),
             },
             title: 'lib dim title',
+            searchEnabled: true,
+            showTitle: true,
+            wildCardSearch: false,
             checkboxes: false,
             histogram: false,
             layoutOptions: {
@@ -103,9 +111,11 @@ describe('filterpane-handler', () => {
               layoutOrder: 'row',
               maxVisibleColumns: {
                 auto: true,
+                maxColumns: 3,
               },
               maxVisibleRows: {
                 auto: true,
+                maxRows: 3,
               },
             },
             qListObjectDef: {
@@ -156,6 +166,9 @@ describe('filterpane-handler', () => {
               qType: expect.any(String),
             },
             title: 'C',
+            searchEnabled: true,
+            showTitle: true,
+            wildCardSearch: false,
             checkboxes: true,
             histogram: false,
             layoutOptions: {
@@ -164,9 +177,11 @@ describe('filterpane-handler', () => {
               layoutOrder: 'row',
               maxVisibleColumns: {
                 auto: true,
+                maxColumns: 3,
               },
               maxVisibleRows: {
                 auto: true,
+                maxRows: 3,
               },
             },
             qListObjectDef: {
@@ -218,6 +233,9 @@ describe('filterpane-handler', () => {
               qType: expect.any(String),
             },
             title: 'My custom title',
+            searchEnabled: true,
+            showTitle: true,
+            wildCardSearch: false,
             checkboxes: true,
             histogram: false,
             layoutOptions: {
@@ -226,9 +244,11 @@ describe('filterpane-handler', () => {
               layoutOrder: 'row',
               maxVisibleColumns: {
                 auto: true,
+                maxColumns: 3,
               },
               maxVisibleRows: {
                 auto: true,
+                maxRows: 3,
               },
             },
             qListObjectDef: {

apis/stardust/api-spec/spec.conf.js

@@ -40,6 +40,9 @@ module.exports = {
         'EngineAPI.INxMeasure': {
           url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxMeasure',
         },
+        'EngineAPI.IListObjectDef': {
+          url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FListObjectDef',
+        },
         Emitter: {
           url: 'https://nodejs.org/api/events.html#class-eventemitter',
         },