@cubejs-client/react 1.7.13 → 1.7.14

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

@@ -2,8 +2,45 @@ import React, { createContext, useRef, useContext, useState, useEffect } from 'r
 import { equals, toPairs, fromPairs, uniqBy, prop, indexBy, uniq, pick, clone } from 'ramda';
 import { isQueryPresent, getQueryMembers, flattenFilters, moveItemInArray, movePivotItem, removeEmptyQueryFields, defaultOrder, ResultSet, validateQuery, defaultHeuristics, areQueriesEqual } from '@cubejs-client/core';
 
+/**
+ * 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__*/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
+ */
 class QueryRenderer extends React.Component {
   static contextType = CubeContext;
   static defaultProps = {
@@ -64,6 +101,16 @@ class QueryRenderer extends React.Component {
       this.loadQueries(queries);
     }
   }
+
+  // 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.
+
   cubeApi() {
     // eslint-disable-next-line react/destructuring-assignment
     return this.props.cubeApi || this.context && this.context.cubeApi;
@@ -191,6 +238,8 @@ class QueryRenderer extends React.Component {
       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;
@@ -212,6 +261,7 @@ const QueryRendererWithTotals = ({
   ...restProps
 }) => /*#__PURE__*/React.createElement(QueryRenderer, _extends({
   queries: {
+    // `granularity: null` is sent to the API on purpose to get totals
     totals: {
       ...query,
       dimensions: [],
@@ -264,6 +314,71 @@ const 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
+ */
 class QueryBuilder extends React.Component {
   static contextType = CubeContext;
   static defaultProps = {
@@ -371,7 +486,7 @@ class QueryBuilder extends React.Component {
         const newMeta = await this.cubeApi().meta();
         if (!equals(newMeta, meta) && typeof onSchemaChange === 'function') {
           onSchemaChange({
-            schemaVersion,
+            schemaVersion: schemaVersion,
             refresh: async () => {
               await this.fetchMeta();
             }
@@ -385,6 +500,16 @@ class QueryBuilder extends React.Component {
       }
     }
   }
+
+  // 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.
+
   fetchMeta = async () => {
     if (!this.cubeApi()) {
       return;
@@ -399,9 +524,10 @@ class QueryBuilder extends React.Component {
       });
       meta = await this.cubeApi().meta();
     } catch (error) {
-      metaError = error.response?.plainError || error;
-      richMetaError = error;
-      metaErrorStack = error.response?.stack?.replace(error.message || '', '') || '';
+      const requestError = error;
+      metaError = requestError.response?.plainError || requestError;
+      richMetaError = requestError;
+      metaErrorStack = requestError.response?.stack?.replace(requestError.message || '', '') || '';
     }
     this.setState({
       meta,
@@ -537,6 +663,9 @@ class QueryBuilder extends React.Component {
       const indexedMeasures = indexBy(prop('cubeName'), availableMembers.measures);
       const indexedDimensions = indexBy(prop('cubeName'), availableMembers.dimensions);
       const cubeNames = uniq([...Object.keys(indexedMeasures), ...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(name => {
         const cube = indexedMeasures[name] || indexedDimensions[name];
         return {
@@ -577,12 +706,14 @@ class QueryBuilder extends React.Component {
       query,
       error: queryError,
       // Match same name as QueryRenderer prop
-      validatedQuery,
+      validatedQuery: validatedQuery,
       isQueryPresent: this.isQueryPresent(),
       chartType,
       measures,
       dimensions,
-      timeDimensions,
+      // The declared granularity options require a `name`, which the
+      // "w/o grouping" option leaves out
+      timeDimensions: timeDimensions,
       segments,
       filters,
       orderMembers,
@@ -667,7 +798,7 @@ class QueryBuilder extends React.Component {
       missingMembers,
       refresh: this.fetchMeta,
       isFetchingMeta,
-      dryRunResponse,
+      dryRunResponse: dryRunResponse,
       ...queryRendererProps
     };
   }
@@ -767,9 +898,10 @@ class QueryBuilder extends React.Component {
           });
         }
       } catch (error) {
+        const requestError = error;
         this.setState({
-          queryError: new Error(error.response?.plainError || error.message),
-          richQueryError: new Error(error.message || error.toString())
+          queryError: new Error(requestError.response?.plainError || requestError.message),
+          richQueryError: new Error(requestError.message || requestError.toString())
         });
       }
     }
@@ -788,7 +920,7 @@ class QueryBuilder extends React.Component {
       meta
     } = this.state;
     return defaultHeuristics(newState, query, {
-      meta,
+      meta: meta,
       sessionGranularity: sessionGranularity || 'day'
     });
   }
@@ -832,18 +964,42 @@ class QueryBuilder extends React.Component {
   }
 }
 
-function CubeProvider({
+/**
+ * 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
+ */
+const CubeProvider = ({
   cubeApi,
   children,
   options = {}
-}) {
-  return /*#__PURE__*/React.createElement(CubeContext.Provider, {
-    value: {
-      cubeApi,
-      options
-    }
-  }, children);
-}
+}) => /*#__PURE__*/React.createElement(CubeContext.Provider, {
+  value: {
+    cubeApi,
+    options
+  }
+}, children);
 
 function useDeepCompareMemoize(value) {
   const ref = useRef([]);
@@ -853,6 +1009,10 @@ function useDeepCompareMemoize(value) {
   return ref.current;
 }
 
+/**
+ * @hidden
+ */
+
 function useCubeFetch(method, options = {}) {
   const context = useContext(CubeContext);
   const mutexRef = useRef({});
@@ -867,6 +1027,7 @@ function useCubeFetch(method, options = {}) {
   async function load(loadOptions = {}, ignoreSkip = false) {
     const cubeApi = options.cubeApi || context?.cubeApi;
     const query = loadOptions.query || options.query;
+    const onlyViews = 'onlyViews' in loadOptions ? loadOptions.onlyViews : options.onlyViews;
     const queryCondition = method === 'meta' ? true : query && isQueryPresent(query);
     if (cubeApi && (ignoreSkip || !skip) && queryCondition) {
       setError(null);
@@ -879,17 +1040,23 @@ function useCubeFetch(method, options = {}) {
         mutexKey: method,
         ...(options.baseRequestId ? {
           baseRequestId: options.baseRequestId
+        } : {}),
+        ...(method === 'meta' && onlyViews ? {
+          onlyViews: true
         } : {})
       };
       const args = method === 'meta' ? [coreOptions] : [query, coreOptions];
+      // `method` picks between overloaded `CubeApi` methods, so the call is
+      // dispatched dynamically while keeping `cubeApi` as the receiver
+      const fetchMethod = cubeApi[method];
       try {
-        const response = await cubeApi[method](...args);
+        const fetchResponse = await fetchMethod.apply(cubeApi, args);
         setResponse({
-          response,
+          response: fetchResponse,
           isLoading: false
         });
-      } catch (error) {
-        setError(error);
+      } catch (fetchError) {
+        setError(fetchError);
         setResponse({
           isLoading: false,
           response: null
@@ -899,14 +1066,23 @@ function useCubeFetch(method, options = {}) {
   }
   useEffect(() => {
     load();
+    // `order` is read off a single query; an array of queries does not carry it
   }, useDeepCompareMemoize([Object.keys(options.query?.order || {}), options, context]));
   return {
     ...response,
     error,
-    refetch: options => load(options, true)
+    refetch: refetchOptions => 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, options = {}) {
   return useCubeFetch('sql', {
     ...options,
@@ -914,6 +1090,9 @@ function useCubeSql(query, options = {}) {
   });
 }
 
+/**
+ * @hidden
+ */
 function useDryRun(query, options = {}) {
   return useCubeFetch('dryRun', {
     ...options,
@@ -921,6 +1100,9 @@ function useDryRun(query, options = {}) {
   });
 }
 
+/**
+ * @hidden
+ */
 function useLazyDryRun(query, options = {}) {
   const {
     refetch,
@@ -933,6 +1115,42 @@ function useLazyDryRun(query, options = {}) {
   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, options = {}) {
   const mutexRef = useRef({});
   const [currentQuery, setCurrentQuery] = useState(null);
@@ -942,9 +1160,9 @@ function useCubeQuery(query, options = {}) {
   const [error, setError] = useState(null);
   const context = useContext(CubeContext);
   let subscribeRequest = null;
-  const progressCallback = ({
-    progressResponse
-  }) => setProgress(progressResponse);
+
+  // `progressResponse` is not part of the public `ProgressResult` API
+  const progressCallback = progressResult => setProgress(progressResult.progressResponse);
   async function fetch() {
     const {
       resetResultSetOnChange
@@ -970,8 +1188,8 @@ function useCubeQuery(query, options = {}) {
       });
       setResultSet(response);
       setProgress(null);
-    } catch (error) {
-      setError(error);
+    } catch (loadError) {
+      setError(loadError);
       setResultSet(null);
       setProgress(null);
     }
@@ -988,7 +1206,10 @@ function useCubeQuery(query, options = {}) {
     }
     async function loadQuery() {
       if (!skip && isQueryPresent(query)) {
-        if (!areQueriesEqual(currentQuery, query)) {
+        // `areQueriesEqual` is declared for a single query, and reads no more
+        // than `order` off one when given an array of queries
+        const previousQuery = currentQuery;
+        if (!areQueriesEqual(previousQuery, query)) {
           if (resetResultSetOnChange == null || resetResultSetOnChange) {
             setResultSet(null);
           }
@@ -1036,7 +1257,8 @@ function useCubeQuery(query, options = {}) {
         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?.order || {}), options, context]));
   return {
     isLoading,
     resultSet,