fix: update jsdocs for listbox (#774)

qlik-oss · Mar 2, 2022 · c607e37 · c607e37
1 parent 1ab3a4c
commit c607e37
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 50 deletions.
diff --git a/apis/nucleus/src/components/listbox/listbox-highlight.js b/apis/nucleus/src/components/listbox/listbox-highlight.js
@@ -1,11 +1,11 @@
 /**
- * @typedef {object} Range
+ * @interface Range
  * @property {number} qCharPos The (absolute) index where the highlighted range starts.
  * @property {number} qCharCount The length of the sub-string (starting from qChartPos) that should be highlighted.
  */
 
 /**
- * @typedef {object} Segment
+ * @interface Segment
  * @property {string} segment The sub-string/segment cut out from the original label.
  * @property {boolean} highlighted A flag which tells whether the segment should be highlighted or not.
  */

diff --git a/apis/nucleus/src/components/listbox/listbox-selections.js b/apis/nucleus/src/components/listbox/listbox-selections.js
@@ -70,7 +70,7 @@ export function getElemNumbersFromPages(pages) {
 }
 
 /**
- * @typedef {object} MinMaxResult
+ * @interface MinMaxResult
  * @property {number} min
  * @property {number} max
  */

diff --git a/apis/nucleus/src/index.js b/apis/nucleus/src/index.js
@@ -328,6 +328,18 @@ function nuked(configuration = {}) {
           throw new Error(`Field identifier must be provided`);
         }
 
+        /**
+         * @typedef { 'ltr' | 'rtl' } Direction
+         */
+
+        /**
+         * @typedef { 'vertical' | 'horizontal' } ListLayout
+         */
+
+        /**
+         * @typedef { 'none' | 'value' | 'percent' | 'relative' } FrequencyMode
+         */
+
         /**
          * @typedef {function(function)} ReceiverFunction A callback function which receives another function as input.
          */
@@ -344,9 +356,9 @@ function nuked(configuration = {}) {
            * @param {HTMLElement} element
            * @param {object=} options Settings for the embedded listbox
            * @param {string=} options.title Custom title, defaults to fieldname
-           * @param {string=} [options.direction=ltr] Direction setting ltr|rtl.
-           * @param {string=} [options.listLayout=vertical] Layout direction vertical|horizontal
-           * @param {string=} [options.frequencyMode=none] Show frequency none|value|percent|relative
+           * @param {Direction=} [options.direction=ltr] Direction setting ltr|rtl.
+           * @param {ListLayout=} [options.listLayout=vertical] Layout direction vertical|horizontal
+           * @param {FrequencyMode=} [options.frequencyMode=none] Show frequency none|value|percent|relative
            * @param {boolean=} [options.search=true] Show the search bar
            * @param {boolean=} [options.toolbar=true] Show the toolbar
            * @param {boolean=} [options.checkboxes=false] Show values as checkboxes instead of as fields

diff --git a/apis/stardust/api-spec/spec.json b/apis/stardust/api-spec/spec.json
@@ -732,6 +732,62 @@
         }
       }
     },
+    "Direction": {
+      "kind": "alias",
+      "items": {
+        "kind": "union",
+        "items": [
+          {
+            "kind": "literal",
+            "value": "'ltr'"
+          },
+          {
+            "kind": "literal",
+            "value": "'rtl'"
+          }
+        ]
+      }
+    },
+    "ListLayout": {
+      "kind": "alias",
+      "items": {
+        "kind": "union",
+        "items": [
+          {
+            "kind": "literal",
+            "value": "'vertical'"
+          },
+          {
+            "kind": "literal",
+            "value": "'horizontal'"
+          }
+        ]
+      }
+    },
+    "FrequencyMode": {
+      "kind": "alias",
+      "items": {
+        "kind": "union",
+        "items": [
+          {
+            "kind": "literal",
+            "value": "'none'"
+          },
+          {
+            "kind": "literal",
+            "value": "'value'"
+          },
+          {
+            "kind": "literal",
+            "value": "'percent'"
+          },
+          {
+            "kind": "literal",
+            "value": "'relative'"
+          }
+        ]
+      }
+    },
     "ReceiverFunction": {
       "description": "A callback function which receives another function as input.",
       "kind": "alias",
@@ -781,13 +837,19 @@
                   "description": "Direction setting ltr|rtl.",
                   "optional": true,
                   "defaultValue": "ltr",
-                  "type": "string"
+                  "type": "#/definitions/Direction"
                 },
                 "listLayout": {
                   "description": "Layout direction vertical|horizontal",
                   "optional": true,
                   "defaultValue": "vertical",
-                  "type": "string"
+                  "type": "#/definitions/ListLayout"
+                },
+                "frequencyMode": {
+                  "description": "Show frequency none|value|percent|relative",
+                  "optional": true,
+                  "defaultValue": "none",
+                  "type": "#/definitions/FrequencyMode"
                 },
                 "search": {
                   "description": "Show the search bar",
@@ -1350,34 +1412,28 @@
       }
     },
     "Range": {
-      "kind": "alias",
-      "items": {
-        "kind": "object",
-        "entries": {
-          "qCharPos": {
-            "description": "The (absolute) index where the highlighted range starts.",
-            "type": "number"
-          },
-          "qCharCount": {
-            "description": "The length of the sub-string (starting from qChartPos) that should be highlighted.",
-            "type": "number"
-          }
+      "kind": "interface",
+      "entries": {
+        "qCharPos": {
+          "description": "The (absolute) index where the highlighted range starts.",
+          "type": "number"
+        },
+        "qCharCount": {
+          "description": "The length of the sub-string (starting from qChartPos) that should be highlighted.",
+          "type": "number"
         }
       }
     },
     "Segment": {
-      "kind": "alias",
-      "items": {
-        "kind": "object",
-        "entries": {
-          "segment": {
-            "description": "The sub-string/segment cut out from the original label.",
-            "type": "string"
-          },
-          "highlighted": {
-            "description": "A flag which tells whether the segment should be highlighted or not.",
-            "type": "boolean"
-          }
+      "kind": "interface",
+      "entries": {
+        "segment": {
+          "description": "The sub-string/segment cut out from the original label.",
+          "type": "string"
+        },
+        "highlighted": {
+          "description": "A flag which tells whether the segment should be highlighted or not.",
+          "type": "boolean"
         }
       }
     },
@@ -1411,16 +1467,13 @@
       }
     },
     "MinMaxResult": {
-      "kind": "alias",
-      "items": {
-        "kind": "object",
-        "entries": {
-          "min": {
-            "type": "number"
-          },
-          "max": {
-            "type": "number"
-          }
+      "kind": "interface",
+      "entries": {
+        "min": {
+          "type": "number"
+        },
+        "max": {
+          "type": "number"
         }
       }
     },

diff --git a/apis/stardust/types/index.d.ts b/apis/stardust/types/index.d.ts
@@ -231,6 +231,12 @@ declare namespace stardust {
 
     }
 
+    type Direction = "ltr" | "rtl";
+
+    type ListLayout = "vertical" | "horizontal";
+
+    type FrequencyMode = "none" | "value" | "percent" | "relative";
+
     /**
      * A callback function which receives another function as input.
      */
@@ -246,8 +252,9 @@ declare namespace stardust {
          */
         mount(element: HTMLElement, options?: {
             title?: string;
-            direction?: string;
-            listLayout?: string;
+            direction?: stardust.Direction;
+            listLayout?: stardust.ListLayout;
+            frequencyMode?: stardust.FrequencyMode;
             search?: boolean;
             toolbar?: boolean;
             checkboxes?: boolean;
@@ -424,16 +431,22 @@ declare namespace stardust {
         meta?: object;
     }
 
-    type Range = {
-    };
+    interface Range {
+        qCharPos: number;
+        qCharCount: number;
+    }
 
-    type Segment = {
-    };
+    interface Segment {
+        segment: string;
+        highlighted: boolean;
+    }
 
     type getSegmentsFromRange = (label: string, range: stardust.Range, startIndex?: number)=>stardust.Segment[];
 
-    type MinMaxResult = {
-    };
+    interface MinMaxResult {
+        min: number;
+        max: number;
+    }
 
     /**
      * Returns the min and max indices of elemNumbersOrdered which contains