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,
+  /**
+   * Pre-fill search input field with wildcard characters.
+   * @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: {
+      /**
+       * Automatically fit as many columns as possible.
+       * 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: {
+      /**
+       * Automatically fits as many rows as possible.
+       * 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/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/listbox-spec.conf.js

@@ -0,0 +1,24 @@
+module.exports = {
+  fromJsdoc: {
+    glob: ['../nucleus/src/components/listbox/default-properties.js'],
+    api: {
+      stability: 'experimental',
+      name: '@nebula.js/stardust:listbox',
+      description: 'nebula listbox properties definition',
+    },
+    output: {
+      sort: {
+        alpha: true,
+      },
+      file: './api-spec/listbox-spec.json',
+    },
+    parse: {
+      types: {
+        undefined: {},
+        'EngineAPI.IListObjectDef': {
+          url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FListObjectDef',
+        },
+      },
+    },
+  },
+};