docs: api spec (qlik-oss#90)

Donya-qlik · May 5, 2022 · 554c529 · 554c529
1 parent 384d2bc
commit 554c529
Show file tree

Hide file tree

Showing 8 changed files with 1,513 additions and 30 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -72,6 +72,15 @@ jobs:
           name: Types
           command: yarn run types:check
 
+  spec:
+    <<: *defaults
+    steps:
+      - attach_workspace:
+          at: ~/project
+      - run:
+          name: Build API specification
+          command: yarn run spec
+
 workflows:
   version: 2
   build-all:
@@ -89,3 +98,6 @@ workflows:
       - types:
           requires:
             - install
+      - spec:
+          requires:
+            - install
diff --git a/api-specifications/properties.json b/api-specifications/properties.json
@@ -0,0 +1,130 @@
+{
+  "scriptappy": "1.0.0",
+  "info": {
+    "name": "sn-pivot-table:properties",
+    "description": "Pivot Table generic object definition",
+    "version": "0.0.0",
+    "license": "MIT",
+    "stability": "experimental",
+    "x-qlik-visibility": "private"
+  },
+  "entries": {
+    "properties": {
+      "extends": [
+        {
+          "type": "GenericObjectProperties"
+        }
+      ],
+      "kind": "object",
+      "entries": {
+        "footnote": {
+          "description": "Visualization footnote",
+          "optional": true,
+          "defaultValue": "",
+          "kind": "union",
+          "items": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "StringExpression"
+            }
+          ],
+          "type": "any"
+        },
+        "nullValueRepresentation": {
+          "description": "Null value properties",
+          "optional": true,
+          "kind": "object",
+          "entries": {
+            "text": {
+              "description": "Null value text",
+              "optional": true,
+              "defaultValue": "-",
+              "type": "string"
+            }
+          }
+        },
+        "qHyperCubeDef": {
+          "extends": [
+            {
+              "type": "HyperCubeDef"
+            }
+          ],
+          "kind": "object",
+          "entries": {
+            "qAlwaysFullyExpanded": {
+              "defaultValue": false,
+              "type": "boolean"
+            },
+            "qDimensions": {
+              "kind": "array",
+              "items": {
+                "type": "NxDimension"
+              }
+            },
+            "qMeasures": {
+              "kind": "array",
+              "items": {
+                "type": "NxMeasure"
+              }
+            },
+            "qShowTotalsAbove": {
+              "defaultValue": true,
+              "type": "boolean"
+            },
+            "qSuppressMissing": {
+              "defaultValue": true,
+              "type": "boolean"
+            },
+            "qSuppressZero": {
+              "defaultValue": false,
+              "type": "boolean"
+            }
+          }
+        },
+        "showTitles": {
+          "description": "Show title for the visualization",
+          "optional": true,
+          "defaultValue": true,
+          "type": "boolean"
+        },
+        "subtitle": {
+          "description": "Visualization subtitle",
+          "optional": true,
+          "defaultValue": "",
+          "kind": "union",
+          "items": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "StringExpression"
+            }
+          ],
+          "type": "any"
+        },
+        "title": {
+          "description": "Visualization title",
+          "optional": true,
+          "defaultValue": "",
+          "kind": "union",
+          "items": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "StringExpression"
+            }
+          ],
+          "type": "any"
+        },
+        "version": {
+          "description": "Current version of this generic object definition",
+          "type": "string"
+        }
+      }
+    }
+  },
+  "definitions": {}
+}
diff --git a/nebula.config.js b/nebula.config.js
@@ -1,5 +1,16 @@
+const path = require('path');
+
+const { version } = require(path.resolve(__dirname, './package.json')); // eslint-disable-line
+const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+const sourcemap = mode !== 'production';
+
 module.exports = {
   build: {
+    sourcemap,
+    mode,
     typescript: true,
+    replacementStrings: {
+      'process.env.PACKAGE_VERSION': JSON.stringify(version),
+    },
   },
 };
diff --git a/package.json b/package.json
@@ -12,8 +12,7 @@
   "files": [
     "dist",
     "sn-pivot-table-ext",
-    "sn-pivot-table.js",
-    "sn-pivot-table.qext"
+    "api-specifications"
   ],
   "engines": {
     "node": ">=8"
@@ -26,7 +25,8 @@
     "start": "nebula serve",
     "sense": "nebula sense --sourcemap true --meta src/meta.json",
     "types:check": "tsc --noEmit",
-    "test": "jest"
+    "test": "jest",
+    "spec": "scriptappy-from-jsdoc -c ./scriptappy.config.js"
   },
   "devDependencies": {
     "@babel/core": "7.17.10",
@@ -72,6 +72,7 @@
     "react": "17.0.2",
     "react-dom": "17.0.2",
     "react-window": "1.8.7",
+    "scriptappy-from-jsdoc": "0.7.0",
     "tslib": "2.4.0",
     "typescript": "4.6.4"
   },

diff --git a/scriptappy.config.js b/scriptappy.config.js
@@ -0,0 +1,41 @@
+const path = require('path');
+
+const pkgPath = path.resolve(__dirname, './package.json');
+const pkg = require(pkgPath); // eslint-disable-line
+
+module.exports = {
+  glob: ['./src/qae/initial-properties.js'],
+  package: pkgPath,
+  api: {
+    stability: 'experimental',
+    properties: {
+      'x-qlik-visibility': 'private',
+    },
+    visibility: 'private',
+    name: `${pkg.name}:properties`,
+    version: pkg.version,
+    description: 'Pivot Table generic object definition',
+  },
+  output: {
+    file: path.resolve(__dirname, './api-specifications/properties.json'),
+  },
+  parse: {
+    types: {
+      GenericObjectProperties: {
+        url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FGenericObjectProperties',
+      },
+      NxDimension: {
+        url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxDimension',
+      },
+      NxMeasure: {
+        url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FNxMeasure',
+      },
+      HyperCubeDef: {
+        url: 'https://qlik.dev/apis/json-rpc/qix/schemas#%23%2Fdefinitions%2Fschemas%2Fentries%2FHyperCubeDef',
+      },
+      StringExpression: {
+        url: 'https://qlik.dev/apis/json-rpc/qix/schemas/#%23%2Fdefinitions%2Fschemas%2Fentries%2FStringExpression',
+      },
+    },
+  },
+};
diff --git a/src/qae/initial-properties.d.ts b/src/qae/initial-properties.d.ts
@@ -0,0 +1,32 @@
+declare module 'initial-properties';
+
+declare const properties: {
+  version: number,
+  qHyperCubeDef: {
+    qAlwaysFullyExpanded: boolean,
+    qDimensions: [],
+    qMeasures: [],
+    qMode: 'P',
+    qSuppressMissing: boolean,
+    qSuppressZero: boolean,
+    qShowTotalsAbove: boolean,
+    qInitialDataFetch: [
+      {
+        qTop: 0,
+        qLeft: 0,
+        qWidth: 50,
+        qHeight: 50,
+      },
+    ],
+    qIndentMode: boolean,
+  },
+  showTitles: boolean,
+  title: '',
+  subtitle: '',
+  footnote: '',
+  nullValueRepresentation: {
+    text: '-'
+  },
+};
+
+export default properties;
diff --git a/src/qae/initial-properties.ts → src/qae/initial-properties.js b/src/qae/initial-properties.ts → src/qae/initial-properties.js
@@ -1,19 +1,23 @@
-import { DEFAULT_PAGE_SIZE } from '../constants';
-
 /**
- * @extends {qae.GenericObjectProperties}
+ * @extends {GenericObjectProperties}
  * @entry
  */
 const properties = {
   /**
-   * @extends {qae.HyperCubeDef}
+   * Current version of this generic object definition
+   * @type {string}
+   * @default
+   */
+   version: process.env.PACKAGE_VERSION,
+  /**
+   * @extends {HyperCubeDef}
    */
   qHyperCubeDef: {
     /** @type {boolean} */
     qAlwaysFullyExpanded: false,
-    /** @type {DimensionProperties[]} */
+    /** @type {NxDimension[]} */
     qDimensions: [],
-    /** @type {MeasureProperties[]} */
+    /** @type {NxMeasure[]} */
     qMeasures: [],
     qMode: 'P',
     /** @type {boolean} */
@@ -26,8 +30,8 @@ const properties = {
       {
         qTop: 0,
         qLeft: 0,
-        qWidth: DEFAULT_PAGE_SIZE,
-        qHeight: DEFAULT_PAGE_SIZE,
+        qWidth: 50,
+        qHeight: 50,
       },
     ],
     qIndentMode: false,
@@ -39,19 +43,30 @@ const properties = {
   showTitles: true,
   /**
    * Visualization title
-   * @type {string=}
+   * @type {(string|StringExpression)=}
    */
   title: '',
   /**
    * Visualization subtitle
-   * @type {string=}
+   * @type {(string|StringExpression)=}
    */
   subtitle: '',
   /**
-   * Holds general styling
-   * @type {Styling[]}
+   * Visualization footnote
+   * @type {(string|StringExpression)=}
    */
   footnote: '',
+  /**
+   * Null value properties
+   * @type {object=}
+   */
+  nullValueRepresentation: {
+    /**
+     * Null value text
+     * @type {string=}
+     */
+    text: '-'
+  },
 };
 
 export default properties;