@databiosphere/findable-ui 33.0.0 → 34.1.0

package/src/components/Table/components/TableFeatures/ColumnFilter/types.ts

@@ -0,0 +1,10 @@
+import { Button, MenuProps } from "@mui/material";
+import { Column, RowData } from "@tanstack/react-table";
+import { BaseComponentProps } from "../../../../types";
+
+export interface ColumnFilterProps<T extends RowData>
+  extends BaseComponentProps,
+    Omit<MenuProps, "anchorEl" | "onClose" | "open"> {
+  Button?: typeof Button;
+  column: Column<T>;
+}

package/src/components/Table/components/TableFeatures/ColumnFilter/utils.ts

@@ -0,0 +1,27 @@
+/**
+ * Returns an updater function for column filter.
+ * @param value - Value.
+ * @returns An updater function that returns the new filter value.
+ */
+export function updater(
+  value: unknown
+): (old: unknown[] | undefined) => unknown[] | undefined {
+  return (old: unknown[] | undefined) => {
+    // If no old value, return new value.
+    if (!old) return [value];
+
+    // If value already exists, remove it.
+    if (old.includes(value)) {
+      // Filter out the value.
+      const next = old.filter((v) => v !== value);
+
+      // If no values remain, return undefined.
+      if (next.length === 0) return undefined;
+
+      return next;
+    }
+
+    // Otherwise, add the value.
+    return [...old, value];
+  };
+}

package/src/components/Table/featureOptions/facetedColumn/utils.ts

@@ -0,0 +1,14 @@
+import { COLLATOR_CASE_INSENSITIVE } from "../../../../common/constants";
+
+/**
+ * Sorts Map entries by key.
+ * @param facetedValues - Map of faceted values.
+ * @returns Sorted array of [key, value] entries.
+ */
+export function getSortedFacetedValues(
+  facetedValues: Map<unknown, number>
+): [unknown, number][] {
+  return [...facetedValues].sort((a, b) =>
+    COLLATOR_CASE_INSENSITIVE.compare(String(a), String(b))
+  );
+}

package/src/components/common/ButtonGroup/constants.ts

@@ -0,0 +1,13 @@
+import { ButtonGroupProps } from "@mui/material";
+import { BUTTON_GROUP_PROPS as MUI_BUTTON_GROUP_PROPS } from "../../../styles/common/mui/buttonGroup";
+
+export const BUTTON_GROUP_PROPS: Record<string, Partial<ButtonGroupProps>> = {
+  PRIMARY_CONTAINED: {
+    color: MUI_BUTTON_GROUP_PROPS.COLOR.PRIMARY,
+    variant: MUI_BUTTON_GROUP_PROPS.VARIANT.CONTAINED,
+  },
+  SECONDARY_OUTLINED: {
+    color: MUI_BUTTON_GROUP_PROPS.COLOR.SECONDARY,
+    variant: MUI_BUTTON_GROUP_PROPS.VARIANT.OUTLINED,
+  },
+};

package/src/mocks/@storybook/addon-actions.ts

@@ -0,0 +1,10 @@
+import { jest } from "@jest/globals";
+
+/**
+ * Mock for Storybook's @storybook/addon-actions function.
+ * The mock keeps the same function signature as the real Storybook action,
+ * does not trigger any Storybook logic, and simply returns a Jest mock function
+ * for use in tests.
+ * @returns A Jest mock function.
+ */
+export const action = (): jest.Mock => jest.fn();

package/src/providers/exploreState/entities.ts

@@ -18,7 +18,7 @@ import {
   EntityPath,
   SavedFilter,
 } from "../../config/entities";
-import { META_COMMAND } from "./hooks/UseMetaCommands/types";
+import { META_COMMAND } from "../exploreStateSync/hooks/UseMetaCommands/types";
 
 export interface EntityPageState {
   categoryGroupConfigKey: CategoryGroupConfigKey;

package/src/providers/exploreState.tsx

@@ -35,8 +35,6 @@ import {
   Meta,
 } from "./exploreState/entities";
 import { useBeforePopState } from "./exploreState/hooks/UseBeforePopState/useBeforePopState";
-import { META_COMMAND } from "./exploreState/hooks/UseMetaCommands/types";
-import { useMetaCommands } from "./exploreState/hooks/UseMetaCommands/useMetaCommands";
 import {
   DEFAULT_PAGINATION_STATE,
   INITIAL_STATE,
@@ -70,6 +68,7 @@ import {
   updateEntityStateByCategoryGroupConfigKey,
   updateSelectColumnVisibility,
 } from "./exploreState/utils";
+import { META_COMMAND } from "./exploreStateSync/hooks/UseMetaCommands/types";
 
 export type CatalogState = string | undefined;
 
@@ -215,9 +214,6 @@ export function ExploreStateProvider({
     });
   }, [exploreDispatch, token]);
 
-  // Meta-command related side effects.
-  useMetaCommands({ exploreDispatch, exploreState });
-
   // Before pop state related side effects (forward / backward navigation by browser buttons).
   useBeforePopState({ exploreDispatch, exploreState });
 
@@ -445,7 +441,7 @@ function exploreReducer(
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -471,7 +467,7 @@ function exploreReducer(
         ),
         filterCount,
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };
@@ -578,8 +574,11 @@ function exploreReducer(
      **/
     case ExploreActionKind.SelectEntityType: {
       if (payload === state.tabValue) {
-        // Update meta to match command "REPLACE_TO_FILTERS" - facilitates navigation to filters on return back to entity from elsewhere.
-        return { ...state, meta: { command: META_COMMAND.REPLACE_TO_FILTERS } };
+        // Update meta to match command "STATE_TO_URL_REPLACE" - facilitates navigation to filters on return back to entity from elsewhere.
+        return {
+          ...state,
+          meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
+        };
       }
       const entityState = getEntityState(
         state,
@@ -594,7 +593,7 @@ function exploreReducer(
         filterState: entityState.filterState,
         listItems: [],
         loading: true,
-        meta: { command: META_COMMAND.REPLACE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_REPLACE },
         paginationState: { ...resetPage(state.paginationState), rows: 0 },
         rowPreview,
         tabValue: payload,
@@ -699,7 +698,7 @@ function exploreReducer(
         ),
         filterCount: getFilterCount(filterState),
         filterState,
-        meta: { command: META_COMMAND.NAVIGATE_TO_FILTERS },
+        meta: { command: META_COMMAND.STATE_TO_URL_PUSH },
         paginationState: resetPage(state.paginationState),
         rowPreview,
       };

package/src/providers/exploreStateSync/hooks/UseMetaCommands/handlers.ts

@@ -0,0 +1,25 @@
+import Router, { NextRouter } from "next/router";
+import { ExploreQueryState } from "./types";
+import { buildQuery, stringifyQuery } from "./utils";
+
+/**
+ * Updates the URL query parameters based on state.
+ * Pushes or replaces the query to the router.
+ * @param state - State -- partial explore state.
+ * @param currentQuery - Query -- current.
+ * @param method - "push" or "replace".
+ */
+export function updateUrlFromState(
+  state: ExploreQueryState,
+  currentQuery: NextRouter["query"],
+  method: "push" | "replace" = "push"
+): void {
+  // Build the next query.
+  const query = buildQuery(state);
+
+  // Do nothing if the next query is the same as the current query.
+  if (stringifyQuery(query) === stringifyQuery(currentQuery)) return;
+
+  // Push or replace the query to the router.
+  Router[method]({ query }, undefined, { shallow: true });
+}

package/src/providers/exploreStateSync/hooks/UseMetaCommands/hook.ts

@@ -0,0 +1,38 @@
+import { useRouter } from "next/router";
+import { useEffect, useMemo } from "react";
+import { useExploreState } from "../../../../hooks/useExploreState";
+import { clearMeta } from "../../../exploreState/actions/clearMeta/dispatch";
+import { updateUrlFromState } from "./handlers";
+import { META_COMMAND } from "./types";
+import { getQueryState } from "./utils";
+
+export const useMetaCommands = (): void => {
+  const { exploreDispatch, exploreState } = useExploreState();
+
+  // Router must be ready before executing any meta-command side effects.
+  const { isReady, query } = useRouter();
+
+  // Command.
+  const command = exploreState.meta?.command;
+
+  // Extract relevant state to update URL.
+  const state = useMemo(() => getQueryState(exploreState), [exploreState]);
+
+  useEffect(() => {
+    // Do nothing if the router is not ready.
+    if (!isReady) return;
+
+    switch (command) {
+      case META_COMMAND.STATE_TO_URL_PUSH:
+        updateUrlFromState(state, query);
+        exploreDispatch(clearMeta());
+        break;
+      case META_COMMAND.STATE_TO_URL_REPLACE:
+        updateUrlFromState(state, query, "replace");
+        exploreDispatch(clearMeta());
+        break;
+      default:
+        break;
+    }
+  }, [command, exploreDispatch, isReady, query, state]);
+};

package/src/providers/exploreStateSync/hooks/UseMetaCommands/types.ts

@@ -0,0 +1,13 @@
+import { ExploreState } from "../../../exploreState";
+
+export interface ExploreQueryState {
+  catalog: ExploreState["catalogState"];
+  entityListType: ExploreState["tabValue"];
+  ff: ExploreState["featureFlagState"];
+  filter: ExploreState["filterState"];
+}
+
+export enum META_COMMAND {
+  STATE_TO_URL_PUSH = "STATE_TO_URL_PUSH",
+  STATE_TO_URL_REPLACE = "STATE_TO_URL_REPLACE",
+}

package/src/providers/exploreStateSync/hooks/UseMetaCommands/utils.ts

@@ -0,0 +1,69 @@
+import { NextRouter } from "next/router";
+import { ExploreState } from "../../../exploreState";
+import { ExploreQueryState } from "./types";
+
+/**
+ * Builds a query object from state.
+ * State values are expected to be undefined, string, or an array.
+ * Undefined values and empty arrays are not included in the query.
+ * @param state - State -- partial explore state.
+ * @returns A query object.
+ */
+export function buildQuery(state: ExploreQueryState): NextRouter["query"] {
+  const query: NextRouter["query"] = {};
+
+  for (const [key, value] of Object.entries(state)) {
+    // Handle the undefined case.
+    if (value === undefined) continue;
+
+    // Handle the string case.
+    if (typeof value === "string") {
+      query[key] = value;
+      continue;
+    }
+
+    // Handle the array case.
+    if (value.length === 0) continue;
+    query[key] = JSON.stringify(value);
+  }
+
+  return query;
+}
+
+/**
+ * Extracts URL-relevant values from the ExploreState for query parameter synchronization.
+ *
+ * This function maps specific properties from the full ExploreState to the
+ * ExploreQueryState interface, which contains only the subset of state that
+ * should be synchronized with the URL.
+ *
+ * The extracted properties are:
+ * - catalog: Current catalog selection (string | undefined)
+ * - entityListType: Current active tab value (string)
+ * - ff: Feature flag state (string | undefined)
+ * - filter: Applied filters (SelectedFilter[])
+ *
+ * @param exploreState - Explore state.
+ * @returns Subset of state used for URL query parameters.
+ */
+export function getQueryState(exploreState: ExploreState): ExploreQueryState {
+  return {
+    catalog: exploreState.catalogState,
+    entityListType: exploreState.tabValue,
+    ff: exploreState.featureFlagState,
+    filter: exploreState.filterState,
+  };
+}
+
+/**
+ * Returns a sorted string representation of a query object.
+ * @param query - Query object.
+ * @returns Sorted string representation of the query object.
+ */
+export function stringifyQuery(query: NextRouter["query"]): string {
+  return JSON.stringify(
+    Object.keys(query)
+      .sort()
+      .reduce((acc, key) => ({ ...acc, [key]: query[key] }), {})
+  );
+}

package/src/providers/exploreStateSync/provider.tsx

@@ -0,0 +1,29 @@
+import React, { ReactNode } from "react";
+import { useMetaCommands } from "./hooks/UseMetaCommands/hook";
+
+/**
+ * Synchronizes the ExploreView component's state with the Next.js URL.
+ *
+ * Listens for reducer meta-commands (`STATE_TO_URL_PUSH`/`STATE_TO_URL_REPLACE`)
+ * and updates the URL accordingly using router methods.
+ *
+ * Usage:
+ * ```tsx
+ * <ExploreStateProvider>
+ *   <ExploreStateSyncProvider>
+ *     <ExploreView />
+ *   </ExploreStateSyncProvider>
+ * </ExploreStateProvider>
+ * ```
+ */
+
+export function ExploreStateSyncProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  // Meta-command related side effects.
+  useMetaCommands();
+
+  return <>{children}</>;
+}

package/src/styles/common/mui/buttonGroup.ts

@@ -0,0 +1,46 @@
+import { buttonGroupClasses, ButtonGroupProps } from "@mui/material";
+
+type ButtonGroupPropsOptions = {
+  CLASSES: typeof CLASSES;
+  COLOR: typeof COLOR;
+  SIZE: typeof SIZE;
+  VARIANT: typeof VARIANT;
+};
+
+const CLASSES: Record<string, ButtonGroupProps["classes"]> = {
+  COLOR_PRIMARY: buttonGroupClasses.colorPrimary,
+  COLOR_SECONDARY: buttonGroupClasses.colorSecondary,
+  CONTAINED: buttonGroupClasses.contained,
+  GROUPED: buttonGroupClasses.grouped,
+  OUTLINED: buttonGroupClasses.outlined,
+  ROOT: buttonGroupClasses.root,
+};
+
+const COLOR: Record<string, ButtonGroupProps["color"]> = {
+  ERROR: "error",
+  INFO: "info",
+  INHERIT: "inherit",
+  PRIMARY: "primary",
+  SECONDARY: "secondary",
+  SUCCESS: "success",
+  WARNING: "warning",
+};
+
+const SIZE: Record<string, ButtonGroupProps["size"]> = {
+  LARGE: "large",
+  MEDIUM: "medium",
+  SMALL: "small",
+};
+
+const VARIANT: Record<string, ButtonGroupProps["variant"]> = {
+  CONTAINED: "contained",
+  OUTLINED: "outlined",
+  TEXT: "text",
+};
+
+export const BUTTON_GROUP_PROPS: ButtonGroupPropsOptions = {
+  CLASSES,
+  COLOR,
+  SIZE,
+  VARIANT,
+};

package/src/styles/common/mui/typography.ts

@@ -10,12 +10,14 @@ const COLOR: Record<string, TypographyOwnProps["color"]> = {
   INHERIT: "inherit",
   INK_LIGHT: "ink.light",
   INK_MAIN: "ink.main",
+  PRIMARY: "primary",
 };
 
 const VARIANT: Record<string, TypographyOwnProps["variant"]> = {
   INHERIT: "inherit",
   TEXT_BODY_400: "text-body-400",
   TEXT_BODY_400_2_LINES: "text-body-400-2lines",
+  TEXT_BODY_500: "text-body-500",
   TEXT_BODY_SMALL_400: "text-body-small-400",
   TEXT_HEADING_LARGE: "text-heading-large",
   TEXT_HEADING_SMALL: "text-heading-small",

package/src/tests/mui/constants.ts

@@ -1,5 +1,6 @@
 export const MUI_CLASSES = {
   ACTIVE: "Mui-active",
   COMPLETED: "Mui-completed",
+  DISABLED: "Mui-disabled",
   SELECTED: "Mui-selected",
 };

package/src/tests/utils.ts

@@ -32,6 +32,15 @@ export function getStartsWithRegex(text: string): RegExp {
   return new RegExp(`^${escapeRegExp(text)}`);
 }
 
+/**
+ * Retrieves an element by its role.
+ * @param role - The role of the element.
+ * @returns The element.
+ */
+export function getRole<T extends HTMLElement = HTMLElement>(role: string): T {
+  return screen.getByRole(role);
+}
+
 /**
  * Retrieves an element by its text content.
  * @param text - The text content of the element.

package/src/theme/common/components.ts

@@ -3,6 +3,7 @@ import { DropDownIcon } from "../../components/common/Form/components/Select/com
 import { COLOR_MIXES } from "../../styles/common/constants/colorMixes";
 import { PALETTE } from "../../styles/common/constants/palette";
 import { SHADOWS } from "../../styles/common/constants/shadows";
+import { BUTTON_PROPS } from "../../styles/common/mui/button";
 import { CHIP_PROPS } from "../../styles/common/mui/chip";
 import { desktopUp, mobileUp, tabletUp } from "./breakpoints";
 import {
@@ -200,6 +201,22 @@ export const MuiButton = (theme: Theme): Components["MuiButton"] => {
       },
       endIcon: {
         margin: 0,
+        variants: [
+          {
+            props: { size: BUTTON_PROPS.SIZE.MEDIUM },
+            style: {
+              marginLeft: -6,
+              marginRight: -6,
+            },
+          },
+          {
+            props: { size: BUTTON_PROPS.SIZE.SMALL },
+            style: {
+              marginLeft: -6,
+              marginRight: -6,
+            },
+          },
+        ],
       },
       outlinedSecondary: {
         backgroundColor: "transparent",
@@ -317,38 +334,6 @@ export const MuiButtonBase = (theme: Theme): Components["MuiButtonBase"] => {
   };
 };
 
-/**
- * MuiButtonGroup Component
- * @param theme - Theme.
- * @returns MuiButtonGroup component theme styles.
- */
-export const MuiButtonGroup = (theme: Theme): Components["MuiButtonGroup"] => {
-  return {
-    defaultProps: {
-      disableElevation: true,
-      disableRipple: true,
-    },
-    styleOverrides: {
-      grouped: {
-        minWidth: 0,
-        padding: "6px 8px",
-      },
-      groupedContainedPrimary: {
-        borderColor: theme.palette.primary.dark,
-        boxShadow: `0 1px 0 0 ${theme.palette.primary.dark}`,
-        // eslint-disable-next-line sort-keys -- disabling key order for readability
-        "&:hover": {
-          boxShadow: `0 1px 0 0 ${theme.palette.primary.dark}`,
-        },
-        // eslint-disable-next-line sort-keys -- disabling key order for readability
-        "&:active": {
-          boxShadow: "none",
-        },
-      },
-    },
-  };
-};
-
 /**
  * MuiCard Component
  */

package/src/theme/components/index.ts

@@ -1,3 +1,4 @@
 export { MuiAlert } from "./muiAlert";
 export { MuiAlertTitle } from "./muiAlertTitle";
+export { MuiButtonGroup } from "./muiButtonGroup";
 export { MuiTableCell } from "./muiTableCell";

package/src/theme/components/muiButtonGroup.ts

@@ -0,0 +1,79 @@
+import { Components } from "@mui/material";
+import { COLOR_MIXES } from "../../styles/common/constants/colorMixes";
+import { PALETTE } from "../../styles/common/constants/palette";
+import { BUTTON_GROUP_PROPS } from "../../styles/common/mui/buttonGroup";
+
+const SELECTORS = {
+  GROUPED: `.${BUTTON_GROUP_PROPS.CLASSES.GROUPED}`,
+};
+
+export const MuiButtonGroup: Components["MuiButtonGroup"] = {
+  defaultProps: {
+    disableElevation: true,
+    disableRipple: true,
+  },
+  styleOverrides: {
+    root: {
+      variants: [
+        /* PRIMARY CONTAINED */
+        {
+          props: {
+            color: BUTTON_GROUP_PROPS.COLOR.PRIMARY,
+            variant: BUTTON_GROUP_PROPS.VARIANT.CONTAINED,
+          },
+          style: {
+            [SELECTORS.GROUPED]: {
+              borderColor: PALETTE.PRIMARY_DARK,
+              boxShadow: `0 1px 0 0 ${PALETTE.PRIMARY_DARK}`,
+              minWidth: 0,
+              // eslint-disable-next-line sort-keys -- disabling key order for readability
+              "&:hover": {
+                boxShadow: `0 1px 0 0 ${PALETTE.PRIMARY_DARK}`,
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for readability
+              "&:active": {
+                boxShadow: "none",
+              },
+            },
+          },
+        },
+        /* SECONDARY OUTLINED */
+        {
+          props: {
+            color: BUTTON_GROUP_PROPS.COLOR.SECONDARY,
+            variant: BUTTON_GROUP_PROPS.VARIANT.OUTLINED,
+          },
+          style: {
+            [SELECTORS.GROUPED]: {
+              backgroundColor: PALETTE.COMMON_WHITE,
+              boxShadow: `inset 0 0 0 1px ${PALETTE.SMOKE_DARK}, 0 1px 0 0 ${COLOR_MIXES.COMMON_BLACK_08}`,
+              color: PALETTE.INK_MAIN,
+              minWidth: 0,
+              // eslint-disable-next-line sort-keys -- disabling key order for readability
+              "&:hover": {
+                backgroundColor: PALETTE.SMOKE_LIGHTEST,
+                boxShadow: `inset 0 0 0 1px ${PALETTE.SMOKE_DARK}, 0 1px 0 0 ${COLOR_MIXES.COMMON_BLACK_08}`,
+              },
+              // eslint-disable-next-line sort-keys -- disabling key order for readability
+              "&:active": {
+                backgroundColor: PALETTE.SMOKE_LIGHTEST,
+                boxShadow: `inset 0 0 0 1px ${PALETTE.SMOKE_DARK}`,
+              },
+            },
+          },
+        },
+        /* SMALL */
+        {
+          props: {
+            size: BUTTON_GROUP_PROPS.SIZE.SMALL,
+          },
+          style: {
+            [SELECTORS.GROUPED]: {
+              padding: "6px 8px",
+            },
+          },
+        },
+      ],
+    },
+  },
+};

package/src/theme/theme.ts

@@ -80,7 +80,7 @@ export function createAppTheme(customOptions: ThemeOptions = {}): Theme {
     MuiBreadcrumbs: C.MuiBreadcrumbs(theme),
     MuiButton: C.MuiButton(theme),
     MuiButtonBase: C.MuiButtonBase(theme),
-    MuiButtonGroup: C.MuiButtonGroup(theme),
+    MuiButtonGroup: M.MuiButtonGroup,
     MuiCard: C.MuiCard,
     MuiCheckbox: C.MuiCheckbox(theme),
     MuiChip: C.MuiChip(theme),

package/src/views/ExploreView/exploreView.tsx

@@ -35,6 +35,7 @@ import { useExploreState } from "../../hooks/useExploreState";
 import { useSummary } from "../../hooks/useSummary";
 import { ExploreActionKind } from "../../providers/exploreState";
 import { SELECT_CATEGORY_KEY } from "../../providers/exploreState/constants";
+import { ExploreStateSyncProvider } from "../../providers/exploreStateSync/provider";
 import { TEST_IDS } from "../../tests/testIds";
 import { DESKTOP_SM } from "../../theme/common/breakpoints";
 
@@ -141,7 +142,7 @@ export const ExploreView = (props: ExploreViewProps): JSX.Element => {
   }, [entityListType, exploreDispatch]);
 
   return (
-    <>
+    <ExploreStateSyncProvider>
       {categoryViews && !!categoryViews.length && (
         <Sidebar drawerOpen={isDrawerOpen} onDrawerClose={onCloseDrawer}>
           <SidebarTools data-testid={TEST_IDS.FILTER_CONTROLS}>
@@ -182,7 +183,7 @@ export const ExploreView = (props: ExploreViewProps): JSX.Element => {
         Tabs={<Tabs />}
         title={entityConfig.explorerTitle || explorerTitle}
       />
-    </>
+    </ExploreStateSyncProvider>
   );
 };