@cubejs-client/react 1.7.12 → 1.7.14

package/dist/cubejs-client-react.cjs.js

@@ -363,13 +363,59 @@ function _unsupportedIterableToArray(r, a) {
   }
 }
 
+/**
+ * In case when you need direct access to `cubeApi` you can use `CubeContext` anywhere in your app
+ *
+ * ```js
+ * import React from 'react';
+ * import { CubeContext } from '@cubejs-client/react';
+ *
+ * export default function DisplayComponent() {
+ *   const { cubeApi } = React.useContext(CubeContext);
+ *   const [rawResults, setRawResults] = React.useState([]);
+ *   const query = {
+ *     ...
+ *   };
+ *
+ *   React.useEffect(() => {
+ *     cubeApi.load(query).then((resultSet) => {
+ *       setRawResults(resultSet.rawData());
+ *     });
+ *   }, [query]);
+ *
+ *   return (
+ *     <>
+ *       {rawResults.map(row => (
+ *         ...
+ *       ))}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+// The context has no default value: `cubeApi` is only available under a
+// `CubeProvider`, and consumers guard against a missing context.
 var CubeContext = /*#__PURE__*/React.createContext(null);
 
+/**
+ * `<QueryRenderer />` a react component that accepts a query, fetches the given query, and uses the render prop to render the resulting data
+ * @stickyTypes QueryRendererProps, QueryRendererRenderProps
+ * @noInheritDoc
+ */
 var QueryRenderer = /*#__PURE__*/function (_React$Component) {
   function QueryRenderer(props) {
     var _this;
     _classCallCheck(this, QueryRenderer);
     _this = _callSuper(this, QueryRenderer, [props]);
+    // These sit after the lifecycle methods because `react/sort-comp` sorts
+    // TypeScript field declarations into `everything-else`, which the configured
+    // order puts after `lifecycle`. Runtime is unaffected: field initializers run
+    // right after `super()`, so the constructor's assignments still win.
+    //
+    // `this.context` is not re-declared: React types it as `any`, and a field
+    // declaration would be emitted at runtime and shadow the context React
+    // assigns.
+    _defineProperty(_this, "mutexObj", void 0);
     _this.state = {};
     _this.mutexObj = {};
     return _this;
@@ -566,6 +612,8 @@ var QueryRenderer = /*#__PURE__*/function (_React$Component) {
         sqlQuery: sqlQuery
       };
       if (render) {
+        // The prop is declared as returning `void` for backwards compatibility,
+        // while what it returns is what gets rendered
         return render(loadState);
       }
       return null;
@@ -597,6 +645,7 @@ var QueryRendererWithTotals = function QueryRendererWithTotals(_ref) {
     restProps = _objectWithoutProperties(_ref, _excluded$1);
   return /*#__PURE__*/React__default["default"].createElement(QueryRenderer, _extends({
     queries: {
+      // `granularity: null` is sent to the API on purpose to get totals
       totals: _objectSpread2(_objectSpread2({}, query), {}, {
         dimensions: [],
         timeDimensions: query.timeDimensions ? query.timeDimensions.map(function (td) {
@@ -657,13 +706,89 @@ var granularities = [{
   name: 'year',
   title: 'Year'
 }];
+
+/**
+ * `<QueryBuilder />` is used to build interactive analytics query builders. It abstracts state management and API calls to Cube.js Backend. It uses render prop technique and doesn’t render anything itself, but calls the render function instead.
+ *
+ * **Example**
+ *
+ * [Open in CodeSandbox](https://codesandbox.io/s/z6r7qj8wm)
+ * ```js
+ * import React from 'react';
+ * import ReactDOM from 'react-dom';
+ * import { Layout, Divider, Empty, Select } from 'antd';
+ * import { QueryBuilder } from '@cubejs-client/react';
+ * import cube from '@cubejs-client/core';
+ * import 'antd/dist/antd.css';
+ *
+ * import ChartRenderer from './ChartRenderer';
+ *
+ * const cubeApi = cube('YOUR-CUBE-API-TOKEN', {
+ *   apiUrl: 'http://localhost:4000/cubejs-api/v1',
+ * });
+ *
+ * const App = () => (
+ *   <QueryBuilder
+ *     query={{
+ *       timeDimensions: [
+ *         {
+ *           dimension: 'LineItems.createdAt',
+ *           granularity: 'month',
+ *         },
+ *       ],
+ *     }}
+ *     cubeApi={cubeApi}
+ *     render={({ resultSet, measures, availableMeasures, updateMeasures }) => (
+ *       <Layout.Content style={{ padding: '20px' }}>
+ *         <Select
+ *           mode="multiple"
+ *           style={{ width: '100%' }}
+ *           placeholder="Please select"
+ *           onSelect={(measure) => updateMeasures.add(measure)}
+ *           onDeselect={(measure) => updateMeasures.remove(measure)}
+ *         >
+ *           {availableMeasures.map((measure) => (
+ *             <Select.Option key={measure.name} value={measure}>
+ *               {measure.title}
+ *             </Select.Option>
+ *           ))}
+ *         </Select>
+ *         <Divider />
+ *         {measures.length > 0 ? (
+ *           <ChartRenderer resultSet={resultSet} />
+ *         ) : (
+ *           <Empty description="Select measure or dimension to get started" />
+ *         )}
+ *       </Layout.Content>
+ *     )}
+ *   />
+ * );
+ *
+ * const rootElement = document.getElementById("root");
+ * ReactDOM.render(<App />, rootElement);
+ * ```
+ * @stickyTypes QueryBuilderProps, QueryBuilderRenderProps, QueryBuilderState
+ * @noInheritDoc
+ * @order 2
+ */
 var QueryBuilder = /*#__PURE__*/function (_React$Component) {
   function QueryBuilder(props) {
     var _this;
     _classCallCheck(this, QueryBuilder);
     _this = _callSuper(this, QueryBuilder, [props]);
+    // These sit after the lifecycle methods because `react/sort-comp` sorts
+    // TypeScript field declarations into `everything-else`, which the configured
+    // order puts after `lifecycle`. Runtime is unaffected: field initializers run
+    // right after `super()`, so the constructor's assignments still win.
+    //
+    // `this.context` is not re-declared: React types it as `any`, and a field
+    // declaration would be emitted at runtime and shadow the context React
+    // assigns.
+    _defineProperty(_this, "mutexObj", void 0);
+    _defineProperty(_this, "orderMembersOrderKeys", void 0);
+    _defineProperty(_this, "prevContext", void 0);
     _defineProperty(_this, "fetchMeta", /*#__PURE__*/_asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
-      var meta, metaError, richMetaError, metaErrorStack, _error$response, _error$response2, _t;
+      var meta, metaError, richMetaError, metaErrorStack, _requestError$respons, _requestError$respons2, requestError, _t;
       return _regenerator().w(function (_context) {
         while (1) switch (_context.p = _context.n) {
           case 0:
@@ -689,9 +814,10 @@ var QueryBuilder = /*#__PURE__*/function (_React$Component) {
           case 4:
             _context.p = 4;
             _t = _context.v;
-            metaError = ((_error$response = _t.response) === null || _error$response === void 0 ? void 0 : _error$response.plainError) || _t;
-            richMetaError = _t;
-            metaErrorStack = ((_error$response2 = _t.response) === null || _error$response2 === void 0 || (_error$response2 = _error$response2.stack) === null || _error$response2 === void 0 ? void 0 : _error$response2.replace(_t.message || '', '')) || '';
+            requestError = _t;
+            metaError = ((_requestError$respons = requestError.response) === null || _requestError$respons === void 0 ? void 0 : _requestError$respons.plainError) || requestError;
+            richMetaError = requestError;
+            metaErrorStack = ((_requestError$respons2 = requestError.response) === null || _requestError$respons2 === void 0 || (_requestError$respons2 = _requestError$respons2.stack) === null || _requestError$respons2 === void 0 ? void 0 : _requestError$respons2.replace(requestError.message || '', '')) || '';
           case 5:
             _this.setState({
               meta: meta,
@@ -942,6 +1068,9 @@ var QueryBuilder = /*#__PURE__*/function (_React$Component) {
         var indexedMeasures = ramda.indexBy(ramda.prop('cubeName'), availableMembers.measures);
         var indexedDimensions = ramda.indexBy(ramda.prop('cubeName'), availableMembers.dimensions);
         var cubeNames = ramda.uniq([].concat(_toConsumableArray(Object.keys(indexedMeasures)), _toConsumableArray(Object.keys(indexedDimensions)))).sort();
+
+        // Measures and dimensions of a cube are merged into one member list, which
+        // the declared type describes as either one or the other
         availableFilterMembers = cubeNames.map(function (name) {
           var _indexedMeasures$name, _indexedDimensions$na;
           var cube = indexedMeasures[name] || indexedDimensions[name];
@@ -994,6 +1123,8 @@ var QueryBuilder = /*#__PURE__*/function (_React$Component) {
         chartType: chartType,
         measures: measures,
         dimensions: dimensions,
+        // The declared granularity options require a `name`, which the
+        // "w/o grouping" option leaves out
         timeDimensions: timeDimensions,
         segments: segments,
         filters: filters,
@@ -1098,7 +1229,7 @@ var QueryBuilder = /*#__PURE__*/function (_React$Component) {
     value: function () {
       var _updateVizState = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(state) {
         var _this4 = this;
-        var _this$props2, setQuery, setVizState, _this$state2, stateQuery, statePivotConfig, chartType, meta, finalState, vizStateSent, handleVizStateChange, runSetters, shouldFetchDryRun, response, _error$response3, _t3;
+        var _this$props2, setQuery, setVizState, _this$state2, stateQuery, statePivotConfig, chartType, meta, finalState, vizStateSent, handleVizStateChange, runSetters, shouldFetchDryRun, response, _requestError$respons3, requestError, _t3;
         return _regenerator().w(function (_context5) {
           while (1) switch (_context5.p = _context5.n) {
             case 0:
@@ -1176,9 +1307,10 @@ var QueryBuilder = /*#__PURE__*/function (_React$Component) {
             case 3:
               _context5.p = 3;
               _t3 = _context5.v;
+              requestError = _t3;
               this.setState({
-                queryError: new Error(((_error$response3 = _t3.response) === null || _error$response3 === void 0 ? void 0 : _error$response3.plainError) || _t3.message),
-                richQueryError: new Error(_t3.message || _t3.toString())
+                queryError: new Error(((_requestError$respons3 = requestError.response) === null || _requestError$respons3 === void 0 ? void 0 : _requestError$respons3.plainError) || requestError.message),
+                richQueryError: new Error(requestError.message || requestError.toString())
               });
             case 4:
               this.setState(finalState, function () {
@@ -1321,7 +1453,33 @@ _defineProperty(QueryBuilder, "defaultProps", {
   setVizState: null
 });
 
-function CubeProvider(_ref) {
+/**
+ * Cube.js context provider
+ * ```js
+ * import React from 'react';
+ * import cube from '@cubejs-client/core';
+ * import { CubeProvider } from '@cubejs-client/react';
+ *
+ * const API_URL = 'https://harsh-eel.aws-us-east-2.cubecloudapp.dev';
+ * const CUBE_TOKEN =
+ *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.* eyJpYXQiOjE1OTE3MDcxNDgsImV4cCI6MTU5NDI5OTE0OH0.* n5jGLQJ14igg6_Hri_Autx9qOIzVqp4oYxmX27V-4T4';
+ *
+ * const cubeApi = cube(CUBE_TOKEN, {
+ *   apiUrl: `${API_URL}/cubejs-api/v1`,
+ * });
+ *
+ * export default function App() {
+ *   return (
+ *     <CubeProvider cubeApi={cubeApi}>
+ *       //...
+ *     </CubeProvider>
+ *   )
+ * }
+ * ```
+ * @stickyTypes
+ * @order 10
+ */
+var CubeProvider = function CubeProvider(_ref) {
   var cubeApi = _ref.cubeApi,
     children = _ref.children,
     _ref$options = _ref.options,
@@ -1332,7 +1490,7 @@ function CubeProvider(_ref) {
       options: options
     }
   }, children);
-}
+};
 
 function useDeepCompareMemoize(value) {
   var ref = React.useRef([]);
@@ -1342,6 +1500,10 @@ function useDeepCompareMemoize(value) {
   return ref.current;
 }
 
+/**
+ * @hidden
+ */
+
 function useCubeFetch(method) {
   var _options$query;
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -1369,10 +1531,12 @@ function useCubeFetch(method) {
         ignoreSkip,
         cubeApi,
         query,
+        onlyViews,
         queryCondition,
         coreOptions,
         args,
-        _response,
+        fetchMethod,
+        fetchResponse,
         _args = arguments,
         _t;
       return _regenerator().w(function (_context) {
@@ -1382,6 +1546,7 @@ function useCubeFetch(method) {
             ignoreSkip = _args.length > 1 && _args[1] !== undefined ? _args[1] : false;
             cubeApi = options.cubeApi || (context === null || context === void 0 ? void 0 : context.cubeApi);
             query = loadOptions.query || options.query;
+            onlyViews = 'onlyViews' in loadOptions ? loadOptions.onlyViews : options.onlyViews;
             queryCondition = method === 'meta' ? true : query && core.isQueryPresent(query);
             if (!(cubeApi && (ignoreSkip || !skip) && queryCondition)) {
               _context.n = 4;
@@ -1392,20 +1557,24 @@ function useCubeFetch(method) {
               isLoading: true,
               response: null
             });
-            coreOptions = _objectSpread2({
+            coreOptions = _objectSpread2(_objectSpread2({
               mutexObj: mutexRef.current,
               mutexKey: method
             }, options.baseRequestId ? {
               baseRequestId: options.baseRequestId
+            } : {}), method === 'meta' && onlyViews ? {
+              onlyViews: true
             } : {});
-            args = method === 'meta' ? [coreOptions] : [query, coreOptions];
+            args = method === 'meta' ? [coreOptions] : [query, coreOptions]; // `method` picks between overloaded `CubeApi` methods, so the call is
+            // dispatched dynamically while keeping `cubeApi` as the receiver
+            fetchMethod = cubeApi[method];
             _context.p = 1;
             _context.n = 2;
-            return cubeApi[method].apply(cubeApi, args);
+            return fetchMethod.apply(cubeApi, args);
           case 2:
-            _response = _context.v;
+            fetchResponse = _context.v;
             setResponse({
-              response: _response,
+              response: fetchResponse,
               isLoading: false
             });
             _context.n = 4;
@@ -1427,15 +1596,24 @@ function useCubeFetch(method) {
   }
   React.useEffect(function () {
     load();
+    // `order` is read off a single query; an array of queries does not carry it
   }, useDeepCompareMemoize([Object.keys(((_options$query = options.query) === null || _options$query === void 0 ? void 0 : _options$query.order) || {}), options, context]));
   return _objectSpread2(_objectSpread2({}, response), {}, {
     error: error,
-    refetch: function refetch(options) {
-      return load(options, true);
+    refetch: function refetch(refetchOptions) {
+      return load(refetchOptions, true);
     }
   });
 }
 
+/**
+ * The hook resolves with a `SqlQuery`, while its `response` stays declared as a
+ * dry-run response for backwards compatibility — `UseCubeSqlResult` spells the
+ * real shape. `refetch` is declared, as it is on `useDryRun` and `useCubeMeta`,
+ * because all three return the same object.
+ *
+ * @hidden
+ */
 function useCubeSql(query) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   return useCubeFetch('sql', _objectSpread2(_objectSpread2({}, options), {}, {
@@ -1443,6 +1621,9 @@ function useCubeSql(query) {
   }));
 }
 
+/**
+ * @hidden
+ */
 function useDryRun(query) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   return useCubeFetch('dryRun', _objectSpread2(_objectSpread2({}, options), {}, {
@@ -1451,6 +1632,9 @@ function useDryRun(query) {
 }
 
 var _excluded = ["refetch"];
+/**
+ * @hidden
+ */
 function useLazyDryRun(query) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var _useCubeFetch = useCubeFetch('dryRun', _objectSpread2(_objectSpread2({}, options), {}, {
@@ -1462,6 +1646,42 @@ function useLazyDryRun(query) {
   return [refetch, result];
 }
 
+/**
+ * A React hook for executing Cube.js queries
+ * ```js
+ * import React from 'react';
+ * import { Table } from 'antd';
+ * import { useCubeQuery }  from '@cubejs-client/react';
+ *
+ * export default function App() {
+ *   const { resultSet, isLoading, error, progress } = useCubeQuery({
+ *     measures: ['Orders.count'],
+ *     dimensions: ['Orders.createdAt.month'],
+ *   });
+ *
+ *   if (isLoading) {
+ *     return <div>{progress?.stage || 'Loading...'}</div>;
+ *   }
+ *
+ *   if (error) {
+ *     return <div>{error.toString()}</div>;
+ *   }
+ *
+ *   if (!resultSet) {
+ *     return null;
+ *   }
+ *
+ *   const dataSource = resultSet.tablePivot();
+ *   const columns = resultSet.tableColumns();
+ *
+ *   return <Table columns={columns} dataSource={dataSource} />;
+ * }
+ *
+ * ```
+ * @order 1
+ * @stickyTypes
+ */
+
 function useCubeQuery(query) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var mutexRef = React.useRef({});
@@ -1487,9 +1707,10 @@ function useCubeQuery(query) {
     setError = _useState0[1];
   var context = React.useContext(CubeContext);
   var subscribeRequest = null;
-  var progressCallback = function progressCallback(_ref) {
-    var progressResponse = _ref.progressResponse;
-    return setProgress(progressResponse);
+
+  // `progressResponse` is not part of the public `ProgressResult` API
+  var progressCallback = function progressCallback(progressResult) {
+    return setProgress(progressResult.progressResponse);
   };
   function fetch() {
     return _fetch.apply(this, arguments);
@@ -1557,7 +1778,7 @@ function useCubeQuery(query) {
     }
     function _loadQuery() {
       _loadQuery = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
-        var _t;
+        var previousQuery, _t;
         return _regenerator().w(function (_context) {
           while (1) switch (_context.p = _context.n) {
             case 0:
@@ -1565,7 +1786,10 @@ function useCubeQuery(query) {
                 _context.n = 7;
                 break;
               }
-              if (!core.areQueriesEqual(currentQuery, query)) {
+              // `areQueriesEqual` is declared for a single query, and reads no more
+              // than `order` off one when given an array of queries
+              previousQuery = currentQuery;
+              if (!core.areQueriesEqual(previousQuery, query)) {
                 if (resetResultSetOnChange == null || resetResultSetOnChange) {
                   setResultSet(null);
                 }
@@ -1631,7 +1855,8 @@ function useCubeQuery(query) {
         subscribeRequest = null;
       }
     };
-  }, useDeepCompareMemoize([query, Object.keys(query && query.order || {}), options, context]));
+    // `order` is read off a single query; an array of queries does not carry it
+  }, useDeepCompareMemoize([query, Object.keys((query === null || query === void 0 ? void 0 : query.order) || {}), options, context]));
   return {
     isLoading: isLoading,
     resultSet: resultSet,