@datawheel/data-explorer 0.2.6 → 0.2.8

package/dist/main.js

@@ -1,8 +1,8 @@
-import { keyframes, createStyles, Select, rem, Flex, Title, Text, Group, Button, Input, Box, Stack, SimpleGrid, ScrollArea, LoadingOverlay, Table, MultiSelect, Center, NumberInput, Menu, ActionIcon, Alert, Loader, Modal, MantineProvider, Paper, useComponentDefaultProps, Anchor, Tabs, Switch, ThemeIcon, Tooltip, useMantineTheme, CloseButton, Drawer, Divider, Checkbox, UnstyledButton, Accordion, Popover } from '@mantine/core';
+import { keyframes, createStyles, Select, rem, Flex, Title, Text, Group, Button, Input, Box, Stack, SimpleGrid, ScrollArea, LoadingOverlay, Table, MultiSelect, Center, NumberInput, Menu, ActionIcon, UnstyledButton, Alert, Loader, Container, Modal, useMantineTheme, MantineProvider, Paper, useComponentDefaultProps, Anchor, Tabs, Switch, ThemeIcon, Tooltip, CloseButton, Drawer, Divider, Checkbox, packSx, Affix, Accordion, Popover } from '@mantine/core';
 import { useClipboard, useClickOutside, useFullscreen, useDebouncedState, useMediaQuery, useDisclosure } from '@mantine/hooks';
-import { IconWorld, IconExternalLink, IconClipboard, IconSettings, IconMathGreater, IconMathLower, IconArrowsLeftRight, IconAlertCircle, IconAlertTriangle, IconCopy, IconDownload, IconDotsVertical, IconArrowsMinimize, IconArrowsMaximize, IconTrash, IconInfoCircleFilled, IconSearch, IconPhotoDown, IconVectorTriangle, IconArrowsSort, IconSortDescendingNumbers, IconSortDescendingLetters, IconSortAscendingNumbers, IconSortAscendingLetters, IconPlus, IconStack3, IconFilterOff, IconFilter, IconBox, IconClock, IconLanguage } from '@tabler/icons-react';
+import { IconWorld, IconExternalLink, IconClipboard, IconSettings, IconMathGreater, IconMathLower, IconArrowsLeftRight, IconAlertCircle, IconAlertTriangle, IconCopy, IconDownload, IconDotsVertical, IconArrowRight, IconArrowLeft, IconArrowsMinimize, IconArrowsMaximize, IconTrash, IconInfoCircleFilled, IconSearch, IconPhotoDown, IconVectorTriangle, IconArrowsSort, IconSortDescendingNumbers, IconSortDescendingLetters, IconSortAscendingNumbers, IconSortAscendingLetters, IconPlus, IconStack3, IconFilterOff, IconFilter, IconBox, IconClock, IconHelpCircle, IconLanguage } from '@tabler/icons-react';
 import * as React13 from 'react';
-import React13__default, { createContext, forwardRef, useMemo, useCallback, useContext, useState, useEffect, useRef, Suspense, useLayoutEffect } from 'react';
+import React13__default, { createContext, forwardRef, useMemo, useCallback, useContext, useRef, useEffect, useState, Suspense, useLayoutEffect } from 'react';
 import { translationFactory } from '@datawheel/use-translation';
 import { translationDict, generateCharts, createChartConfig } from '@datawheel/vizbuilder';
 import { createSlice, createSelector, combineReducers, bindActionCreators, configureStore } from '@reduxjs/toolkit';
@@ -12,7 +12,7 @@ import { QueryClient, QueryClientProvider, useQuery, useQueryClient } from '@tan
 import debounce from 'lodash.debounce';
 import { MRT_ProgressBar, flexRender, MRT_TableBodyCell, MRT_ToolbarAlertBanner, useMantineReactTable, MantineReactTable, MRT_TablePagination } from 'mantine-react-table';
 import { formatAbbreviate, format } from 'd3plus-format';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { TourProvider, useTour } from '@reactour/tour';
 import yn from 'yn';
 import { matchSorter } from 'match-sorter';
 import { BarChart, Donut, Geomap, LinePlot, Pie, StackedArea, Treemap } from 'd3plus-react';
@@ -66,7 +66,7 @@ var require_FileSaver = __commonJS({
       }
       var doc = view.document, get_URL = function() {
         return view.URL || view.webkitURL || view;
-      }, save_link = doc.createElementNS("http://www.w3.org/1999/xhtml", "a"), can_use_save_link = "download" in save_link, click = function(node) {
+      }, save_link = doc.createElementNS("http://www.w3.org/1999/xhtml", "a"), can_use_save_link = "download" in save_link, click2 = function(node) {
         var event = new MouseEvent("click");
         node.dispatchEvent(event);
       }, is_safari = /constructor/i.test(view.HTMLElement) || view.safari, is_chrome_ios = /CriOS\/[\d]+/.test(navigator.userAgent), throw_outside = function(ex) {
@@ -142,7 +142,7 @@ var require_FileSaver = __commonJS({
           setTimeout(function() {
             save_link.href = object_url;
             save_link.download = name4;
-            click(save_link);
+            click2(save_link);
             dispatch_all();
             revoke(object_url);
             filesaver.readyState = filesaver.DONE;
@@ -223,7 +223,9 @@ var defaultTranslation = {
   formats: {
     csv: "CSV",
     json: "JSON",
-    jsonarrays: "JSON Arrays",
+    tsv: "TSV",
+    parquet: "Parquet",
+    // jsonarrays: "JSON Arrays",
     jsonrecords: "JSON Records",
     xlsx: "XLSX"
   },
@@ -366,6 +368,67 @@ var defaultTranslation = {
     sort_asc: "Sort Asc",
     sort_desc: "Sort Desc"
   },
+  tour: {
+    controls: {
+      prev: "Previous",
+      next: "Next",
+      help: "Help"
+    },
+    steps: {
+      welcome: {
+        title: "Welcome to the Data Explorer",
+        text1: "This tutorial will guide you through the steps on how to use the Data Explorer",
+        text2: "By following this tutorial, you will be able to find data of interest and generate your own data tables and visualizations."
+      },
+      locale: {
+        title: "Multilingual",
+        text1: "The Data Explorer makes data available multiple languages.",
+        text2: "Use the dropdown menu to change the output language of the data."
+      },
+      dataset: {
+        title: "Selecting a Dataset",
+        text1: "Begin by selecting a topic of interest.",
+        text2: "Then, select a specific data table within that topic grouping."
+      },
+      search: {
+        title: "Searching for a Dataset",
+        text1: "You can also explore the list of topics and datasets.",
+        text2: "Start typing to filter the list of datasets with your search"
+      },
+      table: {
+        title: "Data Table",
+        text1: "Results are initially displayed as a data table.",
+        text2: "Each column header allows live sorting and filtering options."
+      },
+      columns: {
+        title: "Columns",
+        text1: "Select the columns that you are interested in viewing.",
+        text2: "When you toggle any column checkbox, the data table will automatically update to reflect your selection."
+      },
+      filters: {
+        title: "Filters",
+        text1: "You can filter the elements of each column that you want to display in the data table and visualization.",
+        text2: "If you want all available elements to be displayed, you don't need to apply filters."
+      },
+      download: {
+        title: "Downloading the Data",
+        text1: "You are able to download the information in CSV and JSON formats."
+      },
+      api: {
+        title: "API",
+        text1: "You can access the raw data programmatically using the Data Explorer JSON REST API."
+      },
+      vizbuilderTab: {
+        title: "Vizbuilder",
+        text1: "You can see the results of your query in different types of visualizations."
+      },
+      last: {
+        title: "Let's get started!",
+        text: "You are ready to start exploring the Data Explorer database and generate your own tables and visualizations.",
+        button: "Begin"
+      }
+    }
+  },
   transfer_input: {
     count_hidden: "{{n}} item hidden",
     count_hidden_plural: "{{n}} items hidden",
@@ -508,7 +571,6 @@ var Comparison = /* @__PURE__ */ ((Comparison2) => {
 })(Comparison || {});
 var Format = /* @__PURE__ */ ((Format2) => {
   Format2["csv"] = "csv";
-  Format2["jsonarrays"] = "jsonarrays";
   Format2["jsonrecords"] = "jsonrecords";
   Format2["parquet"] = "parquet";
   Format2["tsv"] = "tsv";
@@ -1369,7 +1431,7 @@ var ComplexityModuleClient = class {
 init_esm_shims();
 var TesseractModuleClient = class {
   constructor(baseURL, config) {
-    this.baseURL = baseURL || "";
+    this.baseURL = baseURL ? baseURL.replace(/\/?$/, "/") : "";
     this.requestConfig = config || { headers: new Headers() };
   }
   fetchStatus(params) {
@@ -1578,6 +1640,10 @@ function useKey(params = {}) {
 }
 
 // src/hooks/settings.tsx
+var defaultToolbarConfig = {
+  buttons: [],
+  showLabels: true
+};
 var SettingsContext = createContext(void 0);
 var { Consumer: ContextConsumer, Provider: ContextProvider } = SettingsContext;
 function SettingsProvider(props) {
@@ -1592,10 +1658,11 @@ function SettingsProvider(props) {
         panels: props.panels,
         previewLimit: props.previewLimit || 50,
         paginationConfig: (_a = props.pagination) != null ? _a : { rowsLimits: [100, 300, 500, 1e3], defaultLimit: 100 },
-        measuresActive: props.measuresActive
+        measuresActive: props.measuresActive,
+        toolbarConfig: { ...defaultToolbarConfig, ...props.toolbarConfig }
       };
     },
-    [props.formatters, props.previewLimit]
+    [props.formatters, props.previewLimit, props.toolbarConfig]
   );
   return /* @__PURE__ */ React13__default.createElement(ContextProvider, { value }, props.children);
 }
@@ -1667,7 +1734,7 @@ function willDownloadQuery(format2) {
     }
     const queryParams = { ...params, pagiLimit: 0, pagiOffset: 0 };
     return tesseract.fetchData({ request: queryParamsToRequest(queryParams), format: format2 }).then((response) => response.blob()).then((result) => ({
-      content: result[0],
+      content: result,
       extension: format2.replace(/json\w+/, "json"),
       name: `${params.cube}_${(/* @__PURE__ */ new Date()).toISOString()}`
     }));
@@ -1905,7 +1972,7 @@ function willReloadCube({ locale }) {
 }
 function willSetupClient(baseURL, defaultLocale, requestConfig) {
   return (dispatch, getState, { tesseract }) => {
-    tesseract.baseURL = baseURL;
+    tesseract.baseURL = baseURL.replace(/\/?$/, "/");
     getState();
     const search = new URLSearchParams(location.search);
     const locale = search.get("locale");
@@ -2489,10 +2556,10 @@ var ApiAndCsvButtons = (props) => {
   return /* @__PURE__ */ React13__default.createElement(Box, { id: "query-results-debug-view" }, /* @__PURE__ */ React13__default.createElement(Group, { spacing: "xs" }, url && /* @__PURE__ */ React13__default.createElement(
     Button,
     {
-      variant: "filled",
-      color: "dark",
+      id: "dex-api-btn",
+      variant: "subtle",
       leftIcon: /* @__PURE__ */ React13__default.createElement(IconCopy, { size: 20 }),
-      sx: { height: 30, backgroundColor: "#5A5A5A" },
+      sx: { height: 30 },
       onClick: copyHandler
     },
     copied ? t("action_copy_done") : t("action_copy"),
@@ -2508,10 +2575,9 @@ var DownloadQuery = ({ data }) => {
     /* @__PURE__ */ React13__default.createElement(
       ButtonDownload,
       {
-        variant: "filled",
-        color: "dark",
+        variant: "light",
         leftIcon: /* @__PURE__ */ React13__default.createElement(IconDownload, { size: 20 }),
-        sx: { height: 30, backgroundColor: "#5A5A5A" },
+        sx: { height: 30 },
         key: "download_csv",
         provider: () => actions2.willDownloadQuery("csv")
       },
@@ -2521,7 +2587,7 @@ var DownloadQuery = ({ data }) => {
   if (components.length === 0 || data.length === 0) {
     return null;
   }
-  return /* @__PURE__ */ React13__default.createElement(Box, { id: "button-group-download-results" }, /* @__PURE__ */ React13__default.createElement(Group, { spacing: "xs" }, components, /* @__PURE__ */ React13__default.createElement(MenuOpts, { formats: formats.filter((f) => f !== "csv") })));
+  return /* @__PURE__ */ React13__default.createElement(Box, { id: "dex-btn-group-download" }, /* @__PURE__ */ React13__default.createElement(Group, { spacing: "xs" }, components, /* @__PURE__ */ React13__default.createElement(MenuOpts, { formats: formats.filter((f) => f !== "csv") })));
 };
 var mimeTypes = {
   csv: "text/csv",
@@ -2695,7 +2761,7 @@ function BarsSVG() {
   );
 }
 function FullScreenSVG() {
-  return /* @__PURE__ */ React13__default.createElement("svg", { width: "20", height: "20", viewBox: "0 0 20 20", fill: "none", xmlns: "http://www.w3.org/2000/svg" }, /* @__PURE__ */ React13__default.createElement("g", { clipPath: "url(#clip0_905_15763)" }, /* @__PURE__ */ React13__default.createElement(
+  return /* @__PURE__ */ React13__default.createElement("svg", { width: "20", height: "20", viewBox: "0 0 20 20", fill: "none", xmlns: "http://www.w3.org/2000/svg", strokeWidth: 1.5 }, /* @__PURE__ */ React13__default.createElement("g", { clipPath: "url(#clip0_905_15763)" }, /* @__PURE__ */ React13__default.createElement(
     "path",
     {
       d: "M3.33325 6.66668V5.00001C3.33325 4.55798 3.50885 4.13406 3.82141 3.8215C4.13397 3.50894 4.55789 3.33334 4.99992 3.33334H6.66659",
@@ -3155,10 +3221,17 @@ function TableView({
 }) {
   const isData = Boolean(table.getRowModel().rows.length);
   const loadingState = useSelector$1(selectLoadingState);
+  const viewport = useRef(null);
+  useEffect(() => {
+    var _a;
+    (_a = viewport.current) == null ? void 0 : _a.scrollTo({ top: 0, behavior: "smooth" });
+  }, [pagination == null ? void 0 : pagination.pageIndex, pagination == null ? void 0 : pagination.pageSize]);
   return /* @__PURE__ */ React13__default.createElement(Box, { sx: { height: "100%" } }, /* @__PURE__ */ React13__default.createElement(Flex, { direction: "column", justify: "space-between", sx: { height: "100%", flex: "1 1 auto" } }, /* @__PURE__ */ React13__default.createElement(MRT_ProgressBar, { isTopToolbar: false, table }), /* @__PURE__ */ React13__default.createElement(
     ScrollArea,
     {
+      id: "dex-table",
       h: isData ? "100%" : "auto",
+      viewportRef: viewport,
       sx: {
         flex: "1 1 auto",
         position: "relative",
@@ -3220,11 +3293,22 @@ function TableView({
               key: header.id,
               sx: (theme) => isRowIndex ? index(theme) : base(theme)
             },
-            header.isPlaceholder ? null : flexRender(
-              (_a = header.column.columnDef.Header) != null ? _a : header.column.columnDef.header,
-              header.getContext()
-            ),
-            !isRowIndex && /* @__PURE__ */ React13__default.createElement(ColumnFilterCell, { isNumeric, header, table })
+            /* @__PURE__ */ React13__default.createElement(
+              Box,
+              {
+                sx: {
+                  display: "flex",
+                  flexFlow: "column",
+                  height: "100%",
+                  justifyContent: "space-between"
+                }
+              },
+              header.isPlaceholder ? null : flexRender(
+                (_a = header.column.columnDef.Header) != null ? _a : header.column.columnDef.header,
+                header.getContext()
+              ),
+              !isRowIndex && /* @__PURE__ */ React13__default.createElement(ColumnFilterCell, { isNumeric, header, table })
+            )
           );
         })))
       ),
@@ -3331,9 +3415,13 @@ function AddColumnsDrawer() {
   return /* @__PURE__ */ React13__default.createElement(React13__default.Fragment, null, /* @__PURE__ */ React13__default.createElement(
     Drawer,
     {
+      id: "dex-column-drawer",
       opened,
       position: "right",
       onClose: close2,
+      closeButtonProps: {
+        id: "dex-column-drawer-close"
+      },
       title: /* @__PURE__ */ React13__default.createElement(Group, null, /* @__PURE__ */ React13__default.createElement(IconPlus, { size: "1.2rem" }), /* @__PURE__ */ React13__default.createElement(Text, { fw: 700 }, t("params.add_columns"))),
       styles,
       overlayProps: {
@@ -3342,7 +3430,7 @@ function AddColumnsDrawer() {
     },
     /* @__PURE__ */ React13__default.createElement(MeasuresOptions, null),
     /* @__PURE__ */ React13__default.createElement(DrillDownOptions, null)
-  ), /* @__PURE__ */ React13__default.createElement(Group, { position: "center", sx: { flexWrap: "nowrap" } }, smallerThanMd ? /* @__PURE__ */ React13__default.createElement(ActionIcon, { onClick: open, size: "md", variant: "filled", color: theme.primaryColor }, /* @__PURE__ */ React13__default.createElement(IconStack3, { size: "0.75rem" })) : /* @__PURE__ */ React13__default.createElement(Button, { leftIcon: /* @__PURE__ */ React13__default.createElement(IconPlus, { size: "1.2rem" }), onClick: open, m: "md", size: "sm" }, t("params.add_columns"))));
+  ), /* @__PURE__ */ React13__default.createElement(Group, { position: "center", sx: { flexWrap: "nowrap" } }, smallerThanMd ? /* @__PURE__ */ React13__default.createElement(ActionIcon, { onClick: open, size: "md", variant: "filled", color: theme.primaryColor }, /* @__PURE__ */ React13__default.createElement(IconStack3, { size: "0.75rem" })) : /* @__PURE__ */ React13__default.createElement(Button, { id: "dex-column-btn", leftIcon: /* @__PURE__ */ React13__default.createElement(IconPlus, { size: "1.2rem" }), onClick: open, m: "md", size: "sm" }, t("params.add_columns"))));
 }
 function DrillDownOptions() {
   const locale = useSelector$1(selectLocale);
@@ -3380,7 +3468,7 @@ function DimensionItem({
       activeItems
     }
   ));
-  return /* @__PURE__ */ React13__default.createElement("div", { key: dimension.name }, /* @__PURE__ */ React13__default.createElement(
+  return /* @__PURE__ */ React13__default.createElement("div", { key: dimension.name, className: "dex-dimension-control", id: `dex-dimension-${dimension.name}` }, /* @__PURE__ */ React13__default.createElement(
     Divider,
     {
       my: "md",
@@ -3496,7 +3584,7 @@ function LevelItem({
   const isDisabled = isOtherHierarchySelected && !checked;
   if (!currentDrilldown) return;
   const paddingLeft = `${5 * depth + 5}px`;
-  return currentDrilldown && /* @__PURE__ */ React13__default.createElement(React13__default.Fragment, null, /* @__PURE__ */ React13__default.createElement(Group, { mt: "sm", position: "apart", key: level.name, noWrap: true }, /* @__PURE__ */ React13__default.createElement(
+  return currentDrilldown && /* @__PURE__ */ React13__default.createElement(React13__default.Fragment, null, /* @__PURE__ */ React13__default.createElement(Group, { className: "dex-level-control", mt: "sm", position: "apart", key: level.name, noWrap: true }, /* @__PURE__ */ React13__default.createElement(
     Checkbox,
     {
       sx: { cursor: "pointer", paddingLeft },
@@ -3518,6 +3606,7 @@ function LevelItem({
   ), /* @__PURE__ */ React13__default.createElement(Group, { sx: { flexWrap: "nowrap" } }, /* @__PURE__ */ React13__default.createElement(
     ActionIcon,
     {
+      className: "dex-level-filter",
       size: "sm",
       onClick: () => setActiveFilter((value) => !value),
       disabled: isDisabled
@@ -3843,6 +3932,7 @@ var toolbarSx = (t) => ({
   height: "fit-content"
 });
 function ToolbarButton({ icon, label, onClick = () => void 0 }) {
+  const { toolbarConfig } = useSettings();
   return /* @__PURE__ */ React13__default.createElement(
     UnstyledButton,
     {
@@ -3850,7 +3940,23 @@ function ToolbarButton({ icon, label, onClick = () => void 0 }) {
       py: { base: "0.2rem", md: 0 },
       sx: (t) => ({ "& svg path": { stroke: t.colorScheme === "dark" ? "white" : "black" } })
     },
-    /* @__PURE__ */ React13__default.createElement(Group, { spacing: "xs", noWrap: true }, icon, /* @__PURE__ */ React13__default.createElement(Text, { size: "sm" }, label))
+    /* @__PURE__ */ React13__default.createElement(Group, { spacing: "xs", noWrap: true }, icon, (toolbarConfig == null ? void 0 : toolbarConfig.showLabels) && label && /* @__PURE__ */ React13__default.createElement(Text, { size: "sm" }, label))
+  );
+}
+function TourButton() {
+  const { setIsOpen, setCurrentStep } = useTour();
+  const { translate: t } = useTranslation();
+  const startTour = () => {
+    setCurrentStep(0);
+    setIsOpen(true);
+  };
+  return /* @__PURE__ */ React13__default.createElement(
+    ToolbarButton,
+    {
+      icon: /* @__PURE__ */ React13__default.createElement(IconHelpCircle, { strokeWidth: 1.5 }),
+      label: t("tour.controls.help"),
+      onClick: startTour
+    }
   );
 }
 function Toolbar({
@@ -3859,11 +3965,12 @@ function Toolbar({
 }) {
   const { translate: t } = useTranslation();
   const theme = useMantineTheme();
-  const smallerThanMd = useMediaQuery(`(max-width: ${theme.breakpoints.md})`);
+  const smallerThanLg = useMediaQuery(`(max-width: ${theme.breakpoints.lg})`);
+  const { toolbarConfig } = useSettings();
   const settings = /* @__PURE__ */ React13__default.createElement(
     Flex,
     {
-      direction: { base: "column", md: "row" },
+      direction: { base: "column", lg: "row" },
       justify: "flex-start",
       sx: toolbarSx,
       p: "0.325rem",
@@ -3871,6 +3978,8 @@ function Toolbar({
       wrap: "nowrap",
       gap: "xs"
     },
+    toolbarConfig == null ? void 0 : toolbarConfig.buttons.map((b) => /* @__PURE__ */ React13__default.createElement(ToolbarButton, { key: b.label, ...b })),
+    /* @__PURE__ */ React13__default.createElement(TourButton, null),
     /* @__PURE__ */ React13__default.createElement(
       ToolbarButton,
       {
@@ -3880,8 +3989,10 @@ function Toolbar({
       }
     )
   );
-  return smallerThanMd ? /* @__PURE__ */ React13__default.createElement(Menu, null, /* @__PURE__ */ React13__default.createElement(Menu.Target, null, /* @__PURE__ */ React13__default.createElement(ActionIcon, null, /* @__PURE__ */ React13__default.createElement(IconSettings, null))), /* @__PURE__ */ React13__default.createElement(Menu.Dropdown, null, settings)) : settings;
+  return smallerThanLg ? /* @__PURE__ */ React13__default.createElement(Menu, null, /* @__PURE__ */ React13__default.createElement(Menu.Target, null, /* @__PURE__ */ React13__default.createElement(ActionIcon, null, /* @__PURE__ */ React13__default.createElement(IconSettings, null))), /* @__PURE__ */ React13__default.createElement(Menu.Dropdown, null, settings)) : settings;
 }
+
+// src/components/ExplorerResults.tsx
 var useStyles2 = createStyles(() => ({
   container: {
     minHeight: "40vh",
@@ -4011,7 +4122,7 @@ function SuccessResult(props) {
       pagination,
       setPagination
     }
-  )))))), /* @__PURE__ */ React13__default.createElement(ReactQueryDevtools, { initialIsOpen: true }));
+  )))))));
 }
 
 // src/components/ParamsExplorer.tsx
@@ -4229,7 +4340,7 @@ function LocaleSelector() {
   if (localeOptions.length < 2) {
     return null;
   }
-  return /* @__PURE__ */ React13__default.createElement(Box, { id: "select-locale" }, /* @__PURE__ */ React13__default.createElement(Tooltip, { label: t("params.label_locale") }, /* @__PURE__ */ React13__default.createElement(
+  return /* @__PURE__ */ React13__default.createElement(Box, { id: "dex-select-locale" }, /* @__PURE__ */ React13__default.createElement(Tooltip, { label: t("params.label_locale") }, /* @__PURE__ */ React13__default.createElement(
     SelectObject,
     {
       getLabel: "value",
@@ -4323,10 +4434,42 @@ function SideBarProvider(props) {
     }
   );
 }
+function SideBarControlBtn({ actionIconProps = {} }) {
+  const { expanded, setExpanded } = useSideBar();
+  const sx = (t) => ({
+    alignSelf: "center",
+    color: t.colorScheme === "dark" ? t.white : t.colors.gray[7]
+  });
+  if (expanded) return null;
+  return /* @__PURE__ */ React13__default.createElement(
+    ActionIcon,
+    {
+      onClick: () => setExpanded(!expanded),
+      variant: "subtle",
+      ...actionIconProps,
+      sx: [sx, ...packSx(actionIconProps.sx)]
+    },
+    /* @__PURE__ */ React13__default.createElement(DataSetSVG, null)
+  );
+}
+function SideBarControlBtnFixed() {
+  const actionIconProps = {
+    sx: (t) => ({
+      backgroundColor: `${t.colorScheme === "dark" ? t.colors.dark[8] : t.colors.gray[1]} !important`,
+      padding: `calc(${t.spacing.xs} / 2)`,
+      borderRadius: t.radius.xl,
+      width: 50,
+      height: 50
+    })
+  };
+  return /* @__PURE__ */ React13__default.createElement(Affix, { position: { left: "1rem", bottom: 150 } }, /* @__PURE__ */ React13__default.createElement(SideBarControlBtn, { actionIconProps }));
+}
 function SideBar(props) {
   const { expanded, setExpanded } = useSideBar();
   const { translate: t } = useTranslation();
-  return /* @__PURE__ */ React13__default.createElement(
+  const theme = useMantineTheme();
+  const smallerThanMd = useMediaQuery(`(max-width: ${theme.breakpoints.md})`);
+  return /* @__PURE__ */ React13__default.createElement(React13__default.Fragment, null, smallerThanMd && /* @__PURE__ */ React13__default.createElement(SideBarControlBtnFixed, null), /* @__PURE__ */ React13__default.createElement(
     Box,
     {
       id: "dex-sidebar",
@@ -4341,8 +4484,8 @@ function SideBar(props) {
         boxSizing: "border-box",
         [t2.fn.smallerThan("md")]: {
           position: "absolute",
-          width: expanded ? 300 : 54,
-          height: expanded ? "calc(100vh - 75px)" : 54,
+          width: expanded ? 300 : 0,
+          height: expanded ? "calc(100vh - 50px)" : 0,
           bottom: expanded ? "unset" : t2.spacing.md,
           left: expanded ? "unset" : t2.spacing.md,
           overflow: "hidden",
@@ -4352,18 +4495,7 @@ function SideBar(props) {
         }
       })
     },
-    /* @__PURE__ */ React13__default.createElement(Flex, { h: "100%", direction: "column", justify: "flex-start" }, /* @__PURE__ */ React13__default.createElement(Box, { px: "sm", my: "sm" }, /* @__PURE__ */ React13__default.createElement(Flex, { direction: "column", sx: { flex: 1 } }, /* @__PURE__ */ React13__default.createElement(Flex, { align: "center", justify: "apart" }, /* @__PURE__ */ React13__default.createElement(
-      ActionIcon,
-      {
-        onClick: () => setExpanded(!expanded),
-        variant: "subtle",
-        sx: (t2) => ({
-          alignSelf: "center",
-          color: t2.colorScheme === "dark" ? t2.white : t2.colors.gray[7]
-        })
-      },
-      /* @__PURE__ */ React13__default.createElement(DataSetSVG, null)
-    ), /* @__PURE__ */ React13__default.createElement(
+    /* @__PURE__ */ React13__default.createElement(Flex, { h: "100%", direction: "column", justify: "flex-start" }, /* @__PURE__ */ React13__default.createElement(Box, { px: "sm", my: "sm" }, /* @__PURE__ */ React13__default.createElement(Flex, { direction: "column", sx: { flex: 1 } }, /* @__PURE__ */ React13__default.createElement(Flex, { align: "center", justify: "apart" }, /* @__PURE__ */ React13__default.createElement(SideBarControlBtn, null), /* @__PURE__ */ React13__default.createElement(
       Group,
       {
         position: "apart",
@@ -4392,8 +4524,9 @@ function SideBar(props) {
     ), /* @__PURE__ */ React13__default.createElement(Box, { sx: { flexGrow: 1 } }))), /* @__PURE__ */ React13__default.createElement(
       ScrollArea,
       {
-        sx: (theme) => ({
-          borderTopColor: theme.colorScheme === "dark" ? theme.colors.dark[6] : theme.colors.gray[3],
+        id: "dex-select-cube-area",
+        sx: (theme2) => ({
+          borderTopColor: theme2.colorScheme === "dark" ? theme2.colors.dark[6] : theme2.colors.gray[3],
           borderTopWidth: "1px",
           borderTopStyle: expanded ? "solid" : "none"
         })
@@ -4420,7 +4553,7 @@ function SideBar(props) {
         expanded ? /* @__PURE__ */ React13__default.createElement(IconChevronLeft, null) : /* @__PURE__ */ React13__default.createElement(IconChevronRight, null)
       )
     ))
-  );
+  ));
 }
 var SideBar_default = SideBar;
 function SideBarItem({ children }) {
@@ -4445,6 +4578,7 @@ function Auto() {
     Input,
     {
       icon: /* @__PURE__ */ React13__default.createElement(IconSearch, null),
+      id: "dex-search",
       radius: "xl",
       size: "md",
       placeholder: t("params.label_search"),
@@ -4524,7 +4658,7 @@ var useStyles3 = createStyles((theme) => ({
   },
   linkActive: {
     backgroundColor: theme.colorScheme === "dark" ? theme.fn.rgba(theme.colors[theme.primaryColor][9], 0.45) : theme.colors[theme.primaryColor][4],
-    color: theme.colorScheme === "dark" ? theme.colors[theme.primaryColor][1] : theme.white,
+    color: theme.white,
     fontWeight: 500
   }
 }));
@@ -4597,7 +4731,7 @@ function SelectCubeInternal(props) {
       }
     }
   }, [selectedItem, cube, measuresActive]);
-  return /* @__PURE__ */ React13__default.createElement(Stack, { id: "select-cube", spacing: "xs", w: "100%" }, /* @__PURE__ */ React13__default.createElement(CubeTree, { items, locale, selectedItem }));
+  return /* @__PURE__ */ React13__default.createElement(Stack, { id: "dex-select-cube", spacing: "xs", w: "100%" }, /* @__PURE__ */ React13__default.createElement(CubeTree, { items, locale, selectedItem }));
 }
 function AccordionControl(props) {
   return /* @__PURE__ */ React13__default.createElement(Box, { sx: { display: "flex", alignItems: "center" } }, /* @__PURE__ */ React13__default.createElement(Accordion.Control, { ...props }));
@@ -4764,7 +4898,7 @@ function CubeButton({
       }),
       onClick: () => onSelectCube(item, subtopic)
     },
-    table
+    table != null ? table : item
   );
 }
 function SubtopicAccordion({
@@ -5534,7 +5668,303 @@ function stringifyMatrix(matrix, formatter2, format2) {
   ].join("\n");
 }
 
+// src/components/tour/ExplorerTour.tsx
+init_esm_shims();
+
+// src/components/tour/useTourSteps.tsx
+init_esm_shims();
+
+// src/components/tour/FirstStep.tsx
+init_esm_shims();
+function FirstStep({ introImage }) {
+  const { translate: t } = useTranslation();
+  return /* @__PURE__ */ React13__default.createElement(Container, { className: "tour-item tour-welcome", px: 0 }, introImage && /* @__PURE__ */ React13__default.createElement("div", { className: "tour-img" }, introImage), /* @__PURE__ */ React13__default.createElement(Box, { className: "tour-text", px: "md" }, /* @__PURE__ */ React13__default.createElement("h3", null, t("tour.steps.welcome.title")), /* @__PURE__ */ React13__default.createElement("p", null, t("tour.steps.welcome.text1")), /* @__PURE__ */ React13__default.createElement("p", null, t("tour.steps.welcome.text2"))));
+}
+
+// src/components/tour/TourStep.tsx
+init_esm_shims();
+function TourStep(props) {
+  const { title, texts } = props;
+  const paragraphs = Array.isArray(texts) ? texts : [texts];
+  return /* @__PURE__ */ React13__default.createElement(Container, { className: "tour-item tour-step", pt: "md" }, /* @__PURE__ */ React13__default.createElement("div", { className: "tour-text" }, /* @__PURE__ */ React13__default.createElement(Title, { order: 3 }, title), paragraphs.map((p, i) => /* @__PURE__ */ React13__default.createElement(Text, { component: "p", key: `p-${i + 1}` }, p))));
+}
+
+// src/components/tour/LastStep.tsx
+init_esm_shims();
+function LastStep({ t }) {
+  return /* @__PURE__ */ React13__default.createElement(Container, { className: "tour-item tour-last", pt: "md" }, /* @__PURE__ */ React13__default.createElement("div", { className: "tour-text" }, /* @__PURE__ */ React13__default.createElement(Title, { order: 3 }, t("tour.steps.last.title")), /* @__PURE__ */ React13__default.createElement(Text, { component: "p" }, t("tour.steps.last.text"))));
+}
+
+// src/components/tour/useTourSteps.tsx
+var click = (selector) => () => {
+  const element = document.querySelector(selector);
+  element == null ? void 0 : element.click();
+};
+var useTourSteps = (tourConfig) => {
+  const { translate: t } = useTranslation();
+  const steps = useMemo(() => [
+    {
+      selector: "document",
+      content: /* @__PURE__ */ React13__default.createElement(FirstStep, { introImage: tourConfig.introImage }),
+      position: "center"
+    },
+    {
+      selector: "#dex-select-locale",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.locale.title"),
+          texts: [
+            t("tour.steps.locale.text1"),
+            t("tour.steps.locale.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: "#dex-select-cube-area",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.dataset.title"),
+          texts: [
+            t("tour.steps.dataset.text1"),
+            t("tour.steps.dataset.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: "#dex-search",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.search.title"),
+          texts: [
+            t("tour.steps.search.text1"),
+            t("tour.steps.search.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: "#dex-table",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.table.title"),
+          texts: [
+            t("tour.steps.table.text1"),
+            t("tour.steps.table.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: "#dex-column-drawer-body",
+      actionBefore: click("#dex-column-btn"),
+      stepInteraction: true,
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.columns.title"),
+          texts: [
+            t("tour.steps.columns.text1"),
+            t("tour.steps.columns.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: ".dex-dimension-control",
+      actionBefore: click(".dex-level-filter"),
+      actionAfter: click("#dex-column-drawer-close"),
+      stepInteraction: true,
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.filters.title"),
+          texts: [
+            t("tour.steps.filters.text1"),
+            t("tour.steps.filters.text2")
+          ]
+        }
+      )
+    },
+    {
+      selector: "#dex-btn-group-download",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.download.title"),
+          texts: [t("tour.steps.download.text1")]
+        }
+      )
+    },
+    {
+      selector: "#dex-api-btn",
+      content: /* @__PURE__ */ React13__default.createElement(
+        TourStep,
+        {
+          title: t("tour.steps.api.title"),
+          texts: [t("tour.steps.api.text1")]
+        }
+      )
+    },
+    ...tourConfig.extraSteps || [],
+    {
+      selector: "viewport",
+      content: /* @__PURE__ */ React13__default.createElement(LastStep, { t }),
+      position: "center"
+    }
+    // ...
+  ], [tourConfig.extraSteps]);
+  return steps;
+};
+
+// src/components/tour/ExplorerTour.tsx
+function PrevButton(props) {
+  const { translate: t } = useTranslation();
+  const theme = useMantineTheme();
+  const isRtl = theme.dir === "rtl";
+  const handleClick = () => props.setCurrentStep(
+    (s) => s === 0 ? props.steps.length - 1 : s - 1
+  );
+  return /* @__PURE__ */ React13__default.createElement(
+    Button,
+    {
+      leftIcon: isRtl ? /* @__PURE__ */ React13__default.createElement(IconArrowRight, { size: "0.8rem" }) : /* @__PURE__ */ React13__default.createElement(IconArrowLeft, { size: "0.8rem" }),
+      onClick: handleClick,
+      radius: 0,
+      size: "lg",
+      sx: { flex: "0 0 50%" },
+      variant: "light",
+      disabled: props.currentStep === 0,
+      w: "50%"
+    },
+    t("tour.controls.prev")
+  );
+}
+function NextButton(props) {
+  const { translate: t } = useTranslation();
+  const theme = useMantineTheme();
+  const isRtl = theme.dir === "rtl";
+  const handleClick = () => {
+    if (props.currentStep === props.steps.length - 1) {
+      props.setIsOpen(false);
+      props.setCurrentStep(0);
+    } else {
+      const nextStep = props.steps[props.currentStep + 1];
+      if (nextStep.hasOwnProperty("actionBefore")) {
+        nextStep.actionBefore();
+        setTimeout(() => props.setCurrentStep((s) => s + 1), 250);
+      } else {
+        props.setCurrentStep((s) => s + 1);
+      }
+    }
+  };
+  return /* @__PURE__ */ React13__default.createElement(
+    Button,
+    {
+      variant: "filled",
+      w: "50%",
+      size: "lg",
+      sx: { flex: "0 0 50%" },
+      onClick: handleClick,
+      rightIcon: isRtl ? /* @__PURE__ */ React13__default.createElement(IconArrowLeft, { size: "0.8rem" }) : /* @__PURE__ */ React13__default.createElement(IconArrowRight, { size: "0.8rem" }),
+      radius: 0
+    },
+    t("tour.controls.next")
+  );
+}
+var withBase = (styles2) => (base) => ({ ...base, ...styles2 });
+var keyboardHandler = (rtl) => (e, clickProps) => {
+  e.stopPropagation();
+  if (!clickProps) return;
+  function next() {
+    if (clickProps.currentStep === clickProps.steps.length - 1) {
+      clickProps.setIsOpen(false);
+      clickProps.setCurrentStep(0);
+    } else {
+      const nextStep = clickProps.steps[clickProps.currentStep + 1];
+      if (nextStep.hasOwnProperty("actionBefore")) {
+        nextStep.actionBefore();
+        setTimeout(() => clickProps.setCurrentStep((s) => s + 1), 250);
+      } else {
+        clickProps.setCurrentStep((s) => s + 1);
+      }
+    }
+  }
+  function prev() {
+    clickProps.setCurrentStep(
+      (s) => s === 0 ? clickProps.steps.length - 1 : s - 1
+    );
+  }
+  if (e.keyCode === 27) {
+    e.preventDefault();
+    clickProps.setIsOpen(false);
+  }
+  if (e.keyCode === 39) {
+    e.preventDefault();
+    if (rtl) {
+      prev();
+    } else {
+      next();
+    }
+  }
+  if (e.keyCode === 37) {
+    e.preventDefault();
+    if (rtl) {
+      next();
+    } else {
+      prev();
+    }
+  }
+};
+function ExplorerTour({ children, tourConfig }) {
+  const theme = useMantineTheme();
+  const steps = useTourSteps(tourConfig);
+  const styles2 = {
+    popover: withBase({ padding: 0, borderRadius: theme.radius.md, overflow: "hidden" }),
+    controls: withBase({ flexWrap: "wrap" }),
+    navigation: withBase({
+      justifyContent: "center",
+      order: -1,
+      width: "100%",
+      margin: `0 auto ${theme.spacing.xs}`
+    }),
+    dot: (base, { current }) => ({
+      ...base,
+      background: current ? theme.fn.primaryColor() : "transparent",
+      color: theme.fn.primaryColor(),
+      borderColor: theme.colors.gray[5]
+    })
+  };
+  const rtl = theme.dir === "rtl";
+  return /* @__PURE__ */ React13__default.createElement(
+    TourProvider,
+    {
+      steps,
+      position: "right",
+      prevButton: PrevButton,
+      nextButton: NextButton,
+      showBadge: false,
+      styles: styles2,
+      rtl: theme.dir === "rtl",
+      keyboardHandler: keyboardHandler(rtl),
+      disableInteraction: true,
+      ...tourConfig == null ? void 0 : tourConfig.tourProps
+    },
+    children
+  );
+}
+
 // src/components/Explorer.tsx
+var defaultTourConfig = {
+  extraSteps: [],
+  introImage: null,
+  tourProps: {}
+};
 function ExplorerComponent(props) {
   const {
     locale = "en",
@@ -5544,6 +5974,7 @@ function ExplorerComponent(props) {
     withinReduxProvider = false,
     withMultiQuery = false,
     pagination,
+    tourConfig,
     measuresActive
   } = props;
   const panels = useMemo(
@@ -5568,9 +5999,10 @@ function ExplorerComponent(props) {
       withPermalink: props.withPermalink,
       panels,
       pagination,
-      measuresActive
+      measuresActive,
+      toolbarConfig: props.toolbarConfig
     },
-    /* @__PURE__ */ React13__default.createElement(TranslationProvider, { defaultLocale: locale, translations: props.translations }, /* @__PURE__ */ React13__default.createElement(
+    /* @__PURE__ */ React13__default.createElement(TranslationProvider, { defaultLocale: locale, translations: props.translations }, /* @__PURE__ */ React13__default.createElement(ExplorerTour, { tourConfig: { ...defaultTourConfig, ...tourConfig } }, /* @__PURE__ */ React13__default.createElement(
       ExplorerContent,
       {
         defaultCube: props.defaultCube,
@@ -5584,7 +6016,7 @@ function ExplorerComponent(props) {
         splash: props.splash,
         withMultiQuery
       }
-    ))
+    )))
   );
   if (withinMantineProvider) {
     content = /* @__PURE__ */ React13__default.createElement(
@@ -6794,4 +7226,4 @@ file-saver/FileSaver.js:
   (*! @source http://purl.eligrey.com/github/FileSaver.js/blob/master/FileSaver.js *)
 */
 
-export { DebugView, ExplorerComponent as Explorer, PivotView, SettingsConsumer, TableView, TranslationConsumer, createVizbuilderView, reducer as explorerReducer, thunkExtraArg as explorerThunkExtraArg, defaultTranslation as translationDict, useSettings, useTranslation };
+export { DebugView, ExplorerComponent as Explorer, PivotView, SettingsConsumer, TableView, ToolbarButton, TourStep, TranslationConsumer, createVizbuilderView, reducer as explorerReducer, thunkExtraArg as explorerThunkExtraArg, defaultTranslation as translationDict, useSettings, useTranslation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datawheel/data-explorer",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "exports": {
     ".": {
       "import": "./dist/main.js"
@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "@datawheel/use-translation": "^0.2.0",
+    "@reactour/tour": "^3.7.0",
     "@reduxjs/toolkit": "^1.9.3",
     "@tabler/icons-react": "^2.7.0",
     "@tanstack/react-query": "^5.51.23",