@cubejs-client/react 1.7.13 → 1.7.14

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

@@ -339,13 +339,59 @@
     }
   }
 
+  /**
+   * 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;
@@ -542,6 +588,8 @@
           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;
@@ -573,6 +621,7 @@
       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) {
@@ -633,13 +682,89 @@
     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:
@@ -665,9 +790,10 @@
             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,
@@ -918,6 +1044,9 @@
           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];
@@ -970,6 +1099,8 @@
           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,
@@ -1074,7 +1205,7 @@
       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:
@@ -1152,9 +1283,10 @@
               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 () {
@@ -1297,7 +1429,33 @@
     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,
@@ -1308,7 +1466,7 @@
         options: options
       }
     }, children);
-  }
+  };
 
   function useDeepCompareMemoize(value) {
     var ref = React.useRef([]);
@@ -1318,6 +1476,10 @@
     return ref.current;
   }
 
+  /**
+   * @hidden
+   */
+
   function useCubeFetch(method) {
     var _options$query;
     var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -1345,10 +1507,12 @@
           ignoreSkip,
           cubeApi,
           query,
+          onlyViews,
           queryCondition,
           coreOptions,
           args,
-          _response,
+          fetchMethod,
+          fetchResponse,
           _args = arguments,
           _t;
         return _regenerator().w(function (_context) {
@@ -1358,6 +1522,7 @@
               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;
@@ -1368,20 +1533,24 @@
                 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;
@@ -1403,15 +1572,24 @@
     }
     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), {}, {
@@ -1419,6 +1597,9 @@
     }));
   }
 
+  /**
+   * @hidden
+   */
   function useDryRun(query) {
     var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     return useCubeFetch('dryRun', _objectSpread2(_objectSpread2({}, options), {}, {
@@ -1427,6 +1608,9 @@
   }
 
   var _excluded = ["refetch"];
+  /**
+   * @hidden
+   */
   function useLazyDryRun(query) {
     var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
     var _useCubeFetch = useCubeFetch('dryRun', _objectSpread2(_objectSpread2({}, options), {}, {
@@ -1438,6 +1622,42 @@
     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({});
@@ -1463,9 +1683,10 @@
       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);
@@ -1533,7 +1754,7 @@
       }
       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:
@@ -1541,7 +1762,10 @@
                   _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);
                   }
@@ -1607,7 +1831,8 @@
           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,