chore: import editorial review (#592)

* chore: import editorial review

* chore: make spec compliant

apis/conversion/src/export-format.js

@@ -1,6 +1,6 @@
 /**
  * Used for exporting and importing properties between backend models. An object that exports to
- * ExportFormat should put dimensions and measures inside one data group. If an object has two hypercubes
+ * ExportFormat should put dimensions and measures inside one data group. If an object has two hypercubes,
  * each of the cubes should export dimensions and measures in two separate data groups.
  * An object that imports from this structure is responsible for putting the existing properties where they should be
  * in the new model.

apis/conversion/src/index.js

@@ -87,7 +87,7 @@ export const convertTo = async ({ halo, model, cellRef, newType }) => {
  * @alias Conversion
  * @experimental
  * @since 1.1.0
- * @description Provides conversion functionality to extensions
+ * @description Provides conversion functionality to extensions.
  * @example
  * import { conversion } from '@nebula.js/stardust';
  *
@@ -108,7 +108,7 @@ const conversion = {
    * @type {hyperCubeConversion}
    * @experimental
    * @since 1.1.0
-   * @description Provides conversion functionality for extensions with hyperCubes
+   * @description Provides conversion functionality to extensions with hyperCubes.
    */
   hypercube,
 };

apis/locale/src/translator.js

@@ -10,7 +10,6 @@ export default function translator({ initial = 'en-US', fallback = 'en-US' } = {
 
   /**
    * @class Translator
-   * @hideconstructor
    */
   const api = /** @lends Translator# */ {
     language: (lang) => {
@@ -45,10 +44,10 @@ export default function translator({ initial = 'en-US', fallback = 'en-US' } = {
       });
     },
     /**
-     * Translates a string for current locale
+     * Translates a string for current locale.
-     * @param {string} str - Id of the registered string
+     * @param {string} str - ID of the registered string.
-     * @param {Array<string>=} args - Values passed down for string interpolation
+     * @param {Array<string>=} args - Values passed down for string interpolation.
-     * @returns {string} The translated string
+     * @returns {string} The translated string.
      */
     get(str, args) {
       let v;

apis/nucleus/src/hooks/useAppSelections.js

@@ -59,7 +59,6 @@ function createAppSelections({ app, currentSelectionsLayout, navState }) {
 
   /**
    * @class
-   * @hideconstructor
    * @alias AppSelections
    */
   const appSelections = {

apis/nucleus/src/hooks/useObjectSelections.js

@@ -23,7 +23,6 @@ function createObjectSelections({ appSelections, appModal, model }) {
   /**
    * @class
    * @alias ObjectSelections
-   * @hideconstructor
    */
   const api = /** @lends ObjectSelections# */ {
     // model,

apis/nucleus/src/index.js

@@ -193,7 +193,6 @@ function nuked(configuration = {}) {
     /**
      * @class
      * @alias Embed
-     * @hideconstructor
      */
     const api = /** @lends Embed# */ {
       /**
@@ -329,7 +328,6 @@ function nuked(configuration = {}) {
 
         /**
          * @class
-         * @hideconstructor
          * @alias FieldInstance
          * @experimental
          * @since 1.1.0
@@ -430,7 +428,7 @@ function nuked(configuration = {}) {
 /**
  * @interface ThemeInfo
  * @property {string} id Theme identifier
- * @property {function(): Promise<ThemeJSON>} load A function that should return a Promise that resolve to a raw JSON theme
+ * @property {function(): Promise<ThemeJSON>} load A function that should return a Promise that resolves to a raw JSON theme.
  */
 
 export default nuked(DEFAULT_CONFIG);

apis/nucleus/src/viz.js

@@ -37,7 +37,6 @@ export default function viz({ model, halo, initialError, onDestroy = async () =>
   /**
    * @class
    * @alias Viz
-   * @hideconstructor
    * @classdesc A controller to further modify a visualization after it has been rendered.
    * @example
    * const viz = await embed(app).render({
@@ -53,7 +52,7 @@ export default function viz({ model, halo, initialError, onDestroy = async () =>
      */
     id: model.id,
     /**
-     * Destroys the visualization and removes if from the the DOM.
+     * Destroys the visualization and removes it from the the DOM.
      * @example
      * const viz = await embed(app).render({
      *   element,
@@ -67,12 +66,12 @@ export default function viz({ model, halo, initialError, onDestroy = async () =>
       unmountCell = noopi;
     },
     /**
-     * Converts the visualization to a different registred type
+     * Converts the visualization to a different registered type
      * @experimental
      * @since 1.1.0
-     * @param {string} newType - Which registered type to convert to
+     * @param {string} newType - Which registered type to convert to.
      * @param {boolean=} forceUpdate - Whether to run setProperties or not, defaults to true.
-     * @returns {Promise<object>} Promise object that resolves to the full property tree of the converted visualizatiom
+     * @returns {Promise<object>} Promise object that resolves to the full property tree of the converted visualization.
      * @example
      * const viz = await embed(app).render({
      *   element,

apis/stardust/api-spec/spec.json

@@ -95,7 +95,7 @@
       ]
     },
     "useEffect": {
-      "description": "Triggers a callback function when a dependant value changes.",
+      "description": "Triggers a callback function when a dependent value changes.",
       "kind": "function",
       "params": [
         {
@@ -105,7 +105,7 @@
         },
         {
           "name": "deps",
-          "description": "The dependencies which should trigger the callback.",
+          "description": "The dependencies that should trigger the callback.",
           "optional": true,
           "kind": "array",
           "items": {
@@ -118,7 +118,7 @@
       ]
     },
     "useMemo": {
-      "description": "Creates a stateful value when a dependant changes.",
+      "description": "Creates a stateful value when a dependent changes.",
       "templates": [
         {
           "name": "T"
@@ -153,7 +153,7 @@
       ]
     },
     "usePromise": {
-      "description": "Runs a callback function when a dependant changes.",
+      "description": "Runs a callback function when a dependent changes.",
       "templates": [
         {
           "name": "P"
@@ -353,6 +353,18 @@
         "import { useTranslator } from '@nebula.js/stardust';\n// ...\nconst translator = useTranslator();\nconsole.log(translator.get('SomeString'));"
       ]
     },
+    "useDeviceType": {
+      "description": "Gets the device type. ('touch' or 'desktop')",
+      "kind": "function",
+      "params": [],
+      "returns": {
+        "description": "device type.",
+        "type": "string"
+      },
+      "examples": [
+        "import { useDeviceType } from '@nebula.js/stardust';\n// ...\nconst deviceType = useDeviceType();\nif (deviceType === 'touch') { ... };"
+      ]
+    },
     "useAction": {
       "description": "Registers a custom action.",
       "templates": [
@@ -450,10 +462,6 @@
           "optional": true,
           "kind": "object",
           "entries": {
-            "select": {
-              "optional": true,
-              "type": "boolean"
-            },
             "active": {
               "optional": true,
               "type": "boolean"
@@ -461,6 +469,10 @@
             "passive": {
               "optional": true,
               "type": "boolean"
+            },
+            "select": {
+              "optional": true,
+              "type": "boolean"
             }
           }
         },
@@ -473,6 +485,11 @@
           "optional": true,
           "defaultValue": "en-US",
           "type": "string"
+        },
+        "deviceType": {
+          "optional": true,
+          "defaultValue": "auto",
+          "type": "string"
         }
       }
     },
@@ -512,6 +529,9 @@
         "flags": {
           "type": "#/definitions/Flags"
         },
+        "deviceType": {
+          "type": "string"
+        },
         "anything": {
           "type": "object"
         }
@@ -519,6 +539,10 @@
     },
     "Embed": {
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "render": {
           "description": "Renders a visualization into an HTMLElement.",
@@ -631,6 +655,10 @@
         "since": "1.1.0"
       },
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {},
       "staticEntries": {
         "mount": {
@@ -705,7 +733,7 @@
           "type": "string"
         },
         "load": {
-          "description": "A function that should return a Promise that resolve to a raw JSON theme",
+          "description": "A function that should return a Promise that resolves to a raw JSON theme.",
           "kind": "function",
           "params": [],
           "returns": {
@@ -722,19 +750,23 @@
     "Viz": {
       "description": "A controller to further modify a visualization after it has been rendered.",
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "id": {
           "description": "The id of this visualization's generic object.",
           "type": "string"
         },
         "destroy": {
-          "description": "Destroys the visualization and removes if from the the DOM.",
+          "description": "Destroys the visualization and removes it from the the DOM.",
           "kind": "function",
           "params": [],
           "examples": ["const viz = await embed(app).render({\n  element,\n  id: 'abc'\n});\nviz.destroy();"]
         },
         "convertTo": {
-          "description": "Converts the visualization to a different registred type",
+          "description": "Converts the visualization to a different registered type",
           "stability": "experimental",
           "availability": {
             "since": "1.1.0"
@@ -743,7 +775,7 @@
           "params": [
             {
               "name": "newType",
-              "description": "Which registered type to convert to",
+              "description": "Which registered type to convert to.",
               "type": "string"
             },
             {
@@ -754,7 +786,7 @@
             }
           ],
           "returns": {
-            "description": "Promise object that resolves to the full property tree of the converted visualizatiom",
+            "description": "Promise object that resolves to the full property tree of the converted visualization.",
             "type": "Promise",
             "generics": [
               {
@@ -791,6 +823,10 @@
     },
     "AppSelections": {
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "mount": {
           "description": "Mounts the app selection UI into the provided HTMLElement.",
@@ -813,6 +849,10 @@
     },
     "ObjectSelections": {
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "begin": {
           "kind": "function",
@@ -1501,6 +1541,10 @@
     },
     "Translator": {
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "add": {
           "description": "Registers a string in multiple locales",
@@ -1532,17 +1576,17 @@
           ]
         },
         "get": {
-          "description": "Translates a string for current locale",
+          "description": "Translates a string for current locale.",
           "kind": "function",
           "params": [
             {
               "name": "str",
-              "description": "Id of the registered string",
+              "description": "ID of the registered string.",
               "type": "string"
             },
             {
               "name": "args",
-              "description": "Values passed down for string interpolation",
+              "description": "Values passed down for string interpolation.",
               "optional": true,
               "kind": "array",
               "items": {
@@ -1551,7 +1595,7 @@
             }
           ],
           "returns": {
-            "description": "The translated string",
+            "description": "The translated string.",
             "type": "string"
           }
         }
@@ -1559,6 +1603,10 @@
     },
     "Theme": {
       "kind": "class",
+      "constructor": {
+        "kind": "function",
+        "params": []
+      },
       "entries": {
         "getDataColorScales": {
           "kind": "function",
@@ -1639,22 +1687,22 @@
           "examples": ["theme.getContrastingColorTo('#400');"]
         },
         "getStyle": {
-          "description": "Get the value of a style attribute in the theme by searching in the theme's json structure.\nThe search starts at the specified base path and continue upwards until the value is found.\nIf possible it will get the attribute's value using the given path.",
+          "description": "Get the value of a style attribute in the theme by searching in the theme's JSON structure.\nThe search starts at the specified base path and continues upwards until the value is found.\nIf possible it will get the attribute's value using the given path.",
           "kind": "function",
           "params": [
             {
               "name": "basePath",
-              "description": "Base path in the theme's json structure to start the search in (specified as a name path separated by dots)",
+              "description": "Base path in the theme's JSON structure to start the search in (specified as a name path separated by dots).",
               "type": "string"
             },
             {
               "name": "path",
-              "description": "Expected path for the attribute (specified as a name path separated by dots)",
+              "description": "Expected path for the attribute (specified as a name path separated by dots).",
               "type": "string"
             },
             {
               "name": "attribute",
-              "description": "Name of the style attribute",
+              "description": "Name of the style attribute.",
               "type": "string"
             }
           ],
@@ -1779,7 +1827,7 @@
       }
     },
     "ExportFormat": {
-      "description": "Used for exporting and importing properties between backend models. An object that exports to\nExportFormat should put dimensions and measures inside one data group. If an object has two hypercubes\neach of the cubes should export dimensions and measures in two separate data groups.\nAn object that imports from this structure is responsible for putting the existing properties where they should be\nin the new model.",
+      "description": "Used for exporting and importing properties between backend models. An object that exports to\nExportFormat should put dimensions and measures inside one data group. If an object has two hypercubes,\neach of the cubes should export dimensions and measures in two separate data groups.\nAn object that imports from this structure is responsible for putting the existing properties where they should be\nin the new model.",
       "stability": "experimental",
       "availability": {
         "since": "1.1.0"
@@ -1859,7 +1907,7 @@
       }
     },
     "Conversion": {
-      "description": "Provides conversion functionality to extensions",
+      "description": "Provides conversion functionality to extensions.",
       "stability": "experimental",
       "availability": {
         "since": "1.1.0"
@@ -1867,7 +1915,7 @@
       "kind": "interface",
       "entries": {
         "hypercube": {
-          "description": "Provides conversion functionality for extensions with hyperCubes",
+          "description": "Provides conversion functionality to extensions with hyperCubes.",
           "stability": "experimental",
           "availability": {
             "since": "1.1.0"

apis/supernova/src/hooks.js

@@ -292,10 +292,10 @@ export function useState(initial) {
  */
 
 /**
- * Triggers a callback function when a dependant value changes.
+ * Triggers a callback function when a dependent value changes.
  * @entry
  * @param {EffectCallback} effect - The callback.
- * @param {Array<any>=} deps - The dependencies which should trigger the callback.
+ * @param {Array<any>=} deps - The dependencies that should trigger the callback.
  * @example
  * import { useEffect } from '@nebula.js/stardust';
  * // ...
@@ -336,7 +336,7 @@ function useLayoutEffect(cb, deps) {
 }
 
 /**
- * Creates a stateful value when a dependant changes.
+ * Creates a stateful value when a dependent changes.
  * @entry
  * @template T
  * @param {function():T} factory - The factory function.
@@ -363,7 +363,7 @@ export function useMemo(fn, deps) {
 }
 
 /**
- * Runs a callback function when a dependant changes.
+ * Runs a callback function when a dependent changes.
  * @entry
  * @template P
  * @param {function():Promise<P>} factory - The factory function that calls the promise.

apis/theme/src/index.js

@@ -17,7 +17,6 @@ export default function theme() {
   /**
    * @class
    * @alias Theme
-   * @hideconstructor
    */
   const externalAPI = /** @lends Theme# */ {
     /**
@@ -74,13 +73,13 @@ export default function theme() {
     },
 
     /**
-     * Get the value of a style attribute in the theme by searching in the theme's json structure.
+     * Get the value of a style attribute in the theme by searching in the theme's JSON structure.
-     * The search starts at the specified base path and continue upwards until the value is found.
+     * The search starts at the specified base path and continues upwards until the value is found.
      * If possible it will get the attribute's value using the given path.
      *
-     * @param {string} basePath - Base path in the theme's json structure to start the search in (specified as a name path separated by dots)
+     * @param {string} basePath - Base path in the theme's JSON structure to start the search in (specified as a name path separated by dots).
-     * @param {string} path - Expected path for the attribute (specified as a name path separated by dots)
+     * @param {string} path - Expected path for the attribute (specified as a name path separated by dots).
-     * @param {string} attribute - Name of the style attribute
+     * @param {string} attribute - Name of the style attribute.
      * @returns {string} The style value
      *
      * @example

docs/api-reference.md

@@ -167,7 +167,7 @@ const [value, setValue] = useState(() => heavy());
 - `effect` <[EffectCallback]> The callback.
 - `deps` <[Array]<`any`>> The dependencies which should trigger the callback.
 
-Triggers a callback function when a dependant value changes.
+Triggers a callback function when a dependent value changes.
 
 ```js
 import { useEffect } from '@nebula.js/stardust';
@@ -186,7 +186,7 @@ useEffect(() => {
 - `deps` <[Array]<`any`>> The dependencies.
 - `returns:` <`T`> The value returned from the factory function.
 
-Creates a stateful value when a dependant changes.
+Creates a stateful value when a dependent changes.
 
 ```js
 import { useMemo } from '@nebula.js/stardust';
@@ -202,7 +202,7 @@ const v = useMemo(() => {
 - `deps` <[Array]<`any`>> The dependencies.
 - `returns:` <[Array]> The resolved value.
 
-Runs a callback function when a dependant changes.
+Runs a callback function when a dependent changes.
 
 ```js
 import { usePromise } from '@nebula.js/stardust';