@databiosphere/findable-ui 21.1.1 → 21.3.0

package/src/components/DataDictionary/common/utils.ts

@@ -0,0 +1,160 @@
+import {
+  Attribute,
+  Class,
+  DataDictionary,
+  DataDictionaryAnnotation,
+} from "../../../common/entities";
+import { CategoryGroupConfig, SiteConfig } from "../../../config/entities";
+
+/**
+ * Annotate each entity column configuration with data dictionary values. Specifically,
+ * look up label and description for each column key.
+ * @param siteConfig - Site configuration to annotate.
+ * @param annotationsByKey - Data dictionary annotations keyed by key.
+ */
+export function annotateColumnConfig(
+  siteConfig: SiteConfig,
+  annotationsByKey: Record<string, DataDictionaryAnnotation>
+): void {
+  // Annotate every column in every entity.
+  siteConfig.entities.forEach((entity) => {
+    entity.list.columns.forEach((columnConfig) => {
+      // Find the annotation for the column key.
+      const annotation = annotationsByKey[columnConfig.id];
+      if (!annotation) {
+        return;
+      }
+
+      if (!columnConfig.meta) {
+        columnConfig.meta = {};
+      }
+      columnConfig.meta.annotation = annotation;
+    });
+  });
+}
+
+/**
+ * Annotate filter and colummn configuration with data dictionary values. Note this
+ * functionality mutates the site config. A possible future improvement would be to
+ * create either a specific "raw"  or "annotated" type to indicate clearly the point
+ * at which the config has been annotated.
+ * @param siteConfig - The site configuration to annotate.
+ */
+export function annotateSiteConfig(siteConfig: SiteConfig): void {
+  // Build and map data dictionary annotations by key.
+  const { dataDictionary } = siteConfig;
+  if (!dataDictionary) {
+    return;
+  }
+  const annotationsByKey = keyAnnotationsByKey(dataDictionary);
+
+  // Annotate elements of site config.
+  annotateEntityConfig(siteConfig, annotationsByKey);
+  annotateDefaultCategoryConfig(siteConfig, annotationsByKey);
+  annotateEntityCategoryConfig(siteConfig, annotationsByKey);
+  annotateColumnConfig(siteConfig, annotationsByKey);
+}
+
+/**
+ * Annotate entity configuration with data dictionary values. Specifically, look
+ * up label and description for each entity key.
+ * @param siteConfig - The site configuration to annotate.
+ * @param annotationsByKey - Data dictionary annotations keyed by key.
+ */
+export function annotateEntityConfig(
+  siteConfig: SiteConfig,
+  annotationsByKey: Record<string, DataDictionaryAnnotation>
+): void {
+  // Annotate every entity.
+  siteConfig.entities.forEach((entityConfig) => {
+    // Check entity for a data dictionary key.
+    const { key } = entityConfig;
+    if (!key) {
+      return;
+    }
+
+    // Find corresponding annotation for the key and set on entity config.
+    entityConfig.annotation = annotationsByKey[key];
+  });
+}
+
+/**
+ * Annotate top-level (app-wide) category config with data dictionary values.
+ * Specifically, look up label and description for each filter key.
+ * @param siteConfig - Site configuration to annotate.
+ * @param annotationsByKey - Data dictionary annotations keyed by key.
+ */
+export function annotateDefaultCategoryConfig(
+  siteConfig: SiteConfig,
+  annotationsByKey: Record<string, DataDictionaryAnnotation>
+): void {
+  const { categoryGroupConfig } = siteConfig;
+  if (categoryGroupConfig) {
+    annotateCategoryGroupConfig(categoryGroupConfig, annotationsByKey);
+  }
+}
+
+/**
+ * Annotate entity-specific category config with data dictionary values. Specifically,
+ * look up label and description for each category key.
+ * @param siteConfig - Site configuration to annotate.
+ * @param annotationsByKey - Data dictionary annotations keyed by key.
+ */
+export function annotateEntityCategoryConfig(
+  siteConfig: SiteConfig,
+  annotationsByKey: Record<string, DataDictionaryAnnotation>
+): void {
+  // Annotate every category in every entity.
+  siteConfig.entities.forEach((entityConfig) => {
+    const { categoryGroupConfig } = entityConfig;
+    if (categoryGroupConfig) {
+      annotateCategoryGroupConfig(categoryGroupConfig, annotationsByKey);
+    }
+  });
+}
+
+/**
+ * Annonate category group configuration with data dictionary values.
+ * @param categoryGroupConfig - Category group to annotate.
+ * @param annotationsByKey - Data dictionary annotations keyed by key.
+ */
+function annotateCategoryGroupConfig(
+  categoryGroupConfig: CategoryGroupConfig,
+  annotationsByKey: Record<string, DataDictionaryAnnotation>
+): void {
+  categoryGroupConfig.categoryGroups.forEach((categoryGroup) => {
+    categoryGroup.categoryConfigs.forEach((categorConfig) => {
+      categorConfig.annotation = annotationsByKey[categorConfig.key];
+    });
+  });
+}
+
+/**
+ * Transform a data dictionary into a key-annotation map. Build annotations for both
+ * classes and attributes and add to map.
+ * @param dataDictionary - Data dictionary to transform into a key-annotation map.
+ * @returns Key-annotation map.
+ */
+function keyAnnotationsByKey(
+  dataDictionary: DataDictionary
+): Record<string, DataDictionaryAnnotation> {
+  return dataDictionary.classes.reduce(
+    (acc: Record<string, DataDictionaryAnnotation>, cls: Class) => {
+      // Add class to map.
+      acc[cls.key] = {
+        description: cls.description,
+        label: cls.label,
+      };
+
+      // Add each class attribute to the map.
+      cls.attributes.forEach((attribute: Attribute) => {
+        acc[attribute.key] = {
+          description: attribute.description,
+          label: attribute.label,
+        };
+      });
+      return acc;
+    },
+    {} as Record<string, DataDictionaryAnnotation>
+  );
+}

package/src/components/DataDictionary/components/Tooltip/components/Title/constants.ts

@@ -0,0 +1,11 @@
+import { StackProps, TypographyProps } from "@mui/material";
+
+export const STACK_PROPS: StackProps = {
+  spacing: 2,
+  useFlexGap: true,
+};
+
+export const TYPOGRAPHY_PROPS: TypographyProps = {
+  color: "ink.light",
+  component: "div",
+};

package/src/components/DataDictionary/components/Tooltip/components/Title/title.tsx

@@ -0,0 +1,19 @@
+import { Stack, Typography } from "@mui/material";
+import React from "react";
+import { TEXT_BODY_LARGE_500 } from "../../../../../../theme/common/typography";
+import { BaseComponentProps } from "../../../../../types";
+import { STACK_PROPS, TYPOGRAPHY_PROPS } from "./constants";
+import { TitleProps } from "./types";
+
+export const Title = ({
+  className,
+  description,
+  title,
+}: BaseComponentProps & Required<TitleProps>): JSX.Element => {
+  return (
+    <Stack {...STACK_PROPS} className={className}>
+      <Typography variant={TEXT_BODY_LARGE_500}>{title}</Typography>
+      <Typography {...TYPOGRAPHY_PROPS}>{description}</Typography>
+    </Stack>
+  );
+};

package/src/components/DataDictionary/components/Tooltip/components/Title/types.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from "react";
+
+export interface TitleProps {
+  description?: ReactNode;
+  title: ReactNode;
+}

package/src/components/DataDictionary/components/Tooltip/constants.ts

@@ -0,0 +1,26 @@
+import { TooltipProps } from "@mui/material";
+import { TEXT_BODY_SMALL_400_2_LINES } from "../../../../theme/common/typography";
+
+export const TOOLTIP_PROPS: Omit<TooltipProps, "children" | "title"> = {
+  arrow: true,
+  disableInteractive: true,
+  enterNextDelay: 250,
+  slotProps: {
+    arrow: { sx: (theme) => ({ color: theme.palette.common.white }) },
+    popper: {
+      modifiers: [
+        { name: "offset", options: { offset: [0, 2] } },
+        { name: "preventOverflow", options: { padding: 8 } },
+      ],
+    },
+    tooltip: {
+      sx: (theme) => ({
+        ...theme.typography[TEXT_BODY_SMALL_400_2_LINES],
+        backgroundColor: theme.palette.common.white,
+        borderRadius: 2,
+        color: theme.palette.ink.main,
+        padding: 4,
+      }),
+    },
+  },
+};

package/src/components/DataDictionary/components/Tooltip/tooltip.tsx

@@ -0,0 +1,26 @@
+import { Tooltip as MTooltip } from "@mui/material";
+import React from "react";
+import { BaseComponentProps } from "../../../types";
+import { Title } from "./components/Title/title";
+import { TitleProps } from "./components/Title/types";
+import { TOOLTIP_PROPS } from "./constants";
+import { TooltipProps } from "./types";
+
+export const Tooltip = ({
+  children,
+  className,
+  description,
+  title,
+  ...props
+}: BaseComponentProps & TitleProps & TooltipProps): JSX.Element => {
+  return (
+    <MTooltip
+      {...TOOLTIP_PROPS}
+      className={className}
+      title={description && <Title description={description} title={title} />}
+      {...props}
+    >
+      <span>{children}</span>
+    </MTooltip>
+  );
+};

package/src/components/DataDictionary/components/Tooltip/types.ts

@@ -0,0 +1,10 @@
+import { TooltipProps as MTooltipProps } from "@mui/material";
+import { ReactNode } from "react";
+
+// `children` is defined as a `ReactNode` instead of an `Element`
+// because the Data Dictionary `Tooltip` component wraps its child in a `span` element.
+// This ensures that `children` can hold a ref properly (see https://mui.com/material-ui/api/tooltip/#props).
+
+export type TooltipProps = Omit<MTooltipProps, "children"> & {
+  children: ReactNode;
+};

package/src/components/Filter/components/Filter/filter.tsx

@@ -77,6 +77,7 @@ export const Filter = ({
   return (
     <>
       <FilterLabel
+        annotation={categoryView.annotation}
         count={categoryView.values.length}
         disabled={categoryView.isDisabled}
         isOpen={isOpen}

package/src/components/Filter/components/FilterLabel/filterLabel.tsx

@@ -1,8 +1,11 @@
 import ArrowDropDownRoundedIcon from "@mui/icons-material/ArrowDropDownRounded";
 import React, { MouseEvent } from "react";
+import { DataDictionaryAnnotation } from "../../../../common/entities";
+import { Tooltip } from "../../../DataDictionary/components/Tooltip/tooltip";
 import { FilterLabel as Label } from "./filterLabel.styles";
 
 export interface FilterLabelProps {
+  annotation?: DataDictionaryAnnotation;
   count?: number;
   disabled?: boolean;
   isOpen: boolean;
@@ -11,6 +14,7 @@ export interface FilterLabelProps {
 }
 
 export const FilterLabel = ({
+  annotation,
   count,
   disabled = false,
   isOpen,
@@ -19,15 +23,17 @@ export const FilterLabel = ({
 }: FilterLabelProps): JSX.Element => {
   const filterLabel = count ? `${label}\xa0(${count})` : label; // When the count is present, a non-breaking space is used to prevent it from being on its own line
   return (
-    <Label
-      color="inherit"
-      disabled={disabled}
-      endIcon={<ArrowDropDownRoundedIcon fontSize="small" />}
-      fullWidth
-      isOpen={isOpen}
-      onClick={onClick}
-    >
-      {filterLabel}
-    </Label>
+    <Tooltip description={annotation?.description} title={annotation?.label}>
+      <Label
+        color="inherit"
+        disabled={disabled}
+        endIcon={<ArrowDropDownRoundedIcon fontSize="small" />}
+        fullWidth
+        isOpen={isOpen}
+        onClick={onClick}
+      >
+        {filterLabel}
+      </Label>
+    </Tooltip>
   );
 };

package/src/components/Index/components/Tabs/common/utils.ts

@@ -11,6 +11,7 @@ export function getEntityListTabs(entities: EntityConfig[]): Tab[] {
     (
       acc: Tab[],
       {
+        annotation,
         label,
         listView: { enableTab = true } = {},
         route,
@@ -20,6 +21,7 @@ export function getEntityListTabs(entities: EntityConfig[]): Tab[] {
     ) => {
       if (enableTab) {
         acc.push({
+          annotation,
           icon,
           iconPosition,
           label,

package/src/components/Table/components/TableHead/tableHead.tsx

@@ -7,6 +7,7 @@ import {
 } from "@mui/material";
 import { flexRender, RowData } from "@tanstack/react-table";
 import React, { Fragment } from "react";
+import { Tooltip } from "../../../DataDictionary/components/Tooltip/tooltip";
 import { ROW_DIRECTION } from "../../common/entities";
 import {
   getTableCellAlign,
@@ -28,27 +29,37 @@ export const TableHead = <T extends RowData>({
             <MTableRow>
               {headerGroup.headers.map(({ column, getContext, id }) => {
                 const { columnDef, getIsGrouped, getIsSorted } = column;
+                const annotation = columnDef.meta?.annotation;
                 return getIsGrouped() ? null : (
                   <TableCell
                     key={id}
                     align={getTableCellAlign(column)}
                     padding={getTableCellPadding(id)}
                   >
-                    {shouldSortColumn(tableInstance, column) ? (
-                      <TableSortLabel
-                        IconComponent={SouthRoundedIcon}
-                        active={Boolean(getIsSorted())}
-                        direction={getIsSorted() || undefined}
-                        disabled={isSortDisabled(tableInstance)}
-                        onClick={(mouseEvent) =>
-                          handleToggleSorting(mouseEvent, tableInstance, column)
-                        }
-                      >
-                        {flexRender(columnDef.header, getContext())}
-                      </TableSortLabel>
-                    ) : (
-                      flexRender(columnDef.header, getContext())
-                    )}
+                    <Tooltip
+                      description={annotation?.description}
+                      title={annotation?.label}
+                    >
+                      {shouldSortColumn(tableInstance, column) ? (
+                        <TableSortLabel
+                          IconComponent={SouthRoundedIcon}
+                          active={Boolean(getIsSorted())}
+                          direction={getIsSorted() || undefined}
+                          disabled={isSortDisabled(tableInstance)}
+                          onClick={(mouseEvent) =>
+                            handleToggleSorting(
+                              mouseEvent,
+                              tableInstance,
+                              column
+                            )
+                          }
+                        >
+                          {flexRender(columnDef.header, getContext())}
+                        </TableSortLabel>
+                      ) : (
+                        flexRender(columnDef.header, getContext())
+                      )}
+                    </Tooltip>
                   </TableCell>
                 );
               })}

package/src/components/common/Tabs/tabs.tsx

@@ -3,7 +3,9 @@ import {
   Tabs as MTabs,
   TabsProps as MTabsProps,
 } from "@mui/material";
-import React, { ReactNode } from "react";
+import React, { ReactElement, ReactNode } from "react";
+import { DataDictionaryAnnotation } from "../../../common/entities";
+import { Tooltip } from "../../DataDictionary/components/Tooltip/tooltip";
 import { Tab, TabScrollFuzz } from "./tabs.styles";
 
 export type TabsValue = MTabsProps["value"]; // any
@@ -11,6 +13,7 @@ export type TabValue = MTabProps["value"]; // any
 export type OnTabChangeFn = (tabValue: TabValue) => void; // Function invoked when selected tab value changes.
 
 export interface Tab {
+  annotation?: DataDictionaryAnnotation;
   count?: string;
   icon?: MTabProps["icon"]; // element or string
   iconPosition?: MTabProps["iconPosition"]; // "bottom" or "end" or "start" or "top
@@ -41,14 +44,21 @@ export const Tabs = ({
     >
       {tabs.map(
         (
-          { count, icon, iconPosition = "start", label, value: tabValue },
+          {
+            annotation,
+            count,
+            icon,
+            iconPosition = "start",
+            label,
+            value: tabValue,
+          },
           t
         ) => (
           <Tab
             icon={icon}
             iconPosition={icon ? iconPosition : undefined}
             key={`${label}${t}`}
-            label={count ? `${label} (${count})` : label}
+            label={buildTabLabel(label, count, annotation)}
             value={tabValue}
           />
         )
@@ -56,3 +66,23 @@ export const Tabs = ({
     </MTabs>
   );
 };
+
+/**
+ * Build a tab value from a tab config. Specifically, display the tab label
+ * with a tooltip annotation if necessary.
+ * @param label - Tab display value.
+ * @param count - Optional count to display next to the tab label.
+ * @param annotation - Data dictionary annotation.
+ * @returns Tab label with optional count and tooltip.
+ */
+function buildTabLabel(
+  label: ReactNode,
+  count?: string,
+  annotation?: DataDictionaryAnnotation
+): ReactElement {
+  return (
+    <Tooltip description={annotation?.description} title={annotation?.label}>
+      <span>{count ? `${label} (${count})` : label}</span>
+    </Tooltip>
+  );
+}

package/src/config/entities.ts

@@ -10,7 +10,12 @@ import {
   TableOptions,
 } from "@tanstack/react-table";
 import { JSXElementConstructor, ReactNode } from "react";
-import { SelectCategoryValueView, SelectedFilter } from "../common/entities";
+import {
+  DataDictionary,
+  DataDictionaryAnnotation,
+  SelectCategoryValueView,
+  SelectedFilter,
+} from "../common/entities";
 import { HeroTitle } from "../components/common/Title/title";
 import { FooterProps } from "../components/Layout/components/Footer/footer";
 import { HeaderProps } from "../components/Layout/components/Header/header";
@@ -87,6 +92,7 @@ export interface CategoryGroup {
  * Model of category configured in site config.
  */
 export interface CategoryConfig {
+  annotation?: DataDictionaryAnnotation;
   key: string;
   label: string;
   mapSelectCategoryValue?: (
@@ -170,6 +176,7 @@ export type EntityPath = string;
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This config model is part of a generic array
 export interface EntityConfig<T = any, I = any> extends TabConfig {
+  annotation?: DataDictionaryAnnotation;
   apiPath?: EntityPath;
   categoryGroupConfig?: CategoryGroupConfig;
   detail: BackPageConfig;
@@ -180,6 +187,7 @@ export interface EntityConfig<T = any, I = any> extends TabConfig {
   getId?: GetIdFunction<T>;
   getTitle?: GetTitleFunction<T>;
   hideTabs?: boolean;
+  key?: string; // Optional data dictionary key
   list: ListConfig<T>;
   listView?: ListViewConfig;
   options?: Options;
@@ -366,6 +374,7 @@ export interface SiteConfig {
   categoryGroupConfig?: CategoryGroupConfig;
   contentDir?: string;
   contentThemeOptionsFn?: ThemeOptionsFn;
+  dataDictionary?: DataDictionary;
   dataSource: DataSourceConfig;
   entities: EntityConfig[];
   explorerTitle: HeroTitle;

package/src/hooks/useCategoryFilter.ts

@@ -77,6 +77,7 @@ function buildCategoryView(
   const mapSelectCategoryValue =
     categoryConfig?.mapSelectCategoryValue || getSelectCategoryValue;
   return {
+    annotation: categoryConfig?.annotation,
     isDisabled: false,
     key: category.key,
     label: getCategoryLabel(category.key, categoryConfig),

package/src/providers/config.tsx

@@ -1,4 +1,5 @@
-import React, { createContext, ReactNode } from "react";
+import React, { createContext, ReactNode, useState } from "react";
+import { annotateSiteConfig } from "../components/DataDictionary/common/utils";
 import { EntityConfig, SiteConfig } from "../config/entities";
 import {
   getDefaultConfig,
@@ -31,7 +32,14 @@ export function ConfigProvider({
   config,
   entityListType = "",
 }: ConfigProps): JSX.Element {
-  const { entities } = config;
+  // Annote config on init. Note config is mutated but using state here to
+  // ensure annotated config is calculated once and is used rather than the raw config.
+  const [annotatedConfig] = useState(() => {
+    annotateSiteConfig(config);
+    return config;
+  });
+
+  const { entities } = annotatedConfig;
   const defaultEntityListType = config.redirectRootToPath.slice(1);
   const entityName = entityListType || defaultEntityListType;
   const entityConfig = getEntityConfig(entities, entityName);