@databiosphere/findable-ui 21.2.0 → 21.3.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "21.2.0"
+  ".": "21.3.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [21.3.0](https://github.com/DataBiosphere/findable-ui/compare/v21.2.0...v21.3.0) (2025-02-14)
+
+
+### Features
+
+* add data dictionary tooltip support [#4131](https://github.com/DataBiosphere/findable-ui/issues/4131) ([#320](https://github.com/DataBiosphere/findable-ui/issues/320)) ([849e5cf](https://github.com/DataBiosphere/findable-ui/commit/849e5cf5898f71be210436863c9b10baf85a8427))
+
 ## [21.2.0](https://github.com/DataBiosphere/findable-ui/compare/v21.1.1...v21.2.0) (2025-02-12)
 
 

package/lib/common/entities.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Model of a value of a metadata class.
+ */
+export interface Attribute {
+    description: string;
+    key: string;
+    label: string;
+}
 /**
  * Filterable metadata keys.
  */
@@ -10,10 +18,34 @@ export interface CategoryTag {
     onRemove: () => void;
     superseded: boolean;
 }
+/**
+ * Model of a metadata class, to be specified manually or built from LinkML schema.
+ */
+export interface Class {
+    attributes: Attribute[];
+    description: string;
+    key: string;
+    label: string;
+    name: string;
+}
 /**
  * Category values to be used as keys. For example, "Homo sapiens" or "10X 3' v2 sequencing".
  */
 export type CategoryValueKey = unknown;
+/**
+ * Model of a metadata dictionary containing a set of classes and their definitions.
+ */
+export interface DataDictionary {
+    classes: Class[];
+}
+/**
+ * Label and description values from a data dictionary that are added to a site
+ * config value.
+ */
+export interface DataDictionaryAnnotation {
+    description: string;
+    label: string;
+}
 /**
  * Set of selected category values.
  */
@@ -63,6 +95,7 @@ export interface SelectCategoryValueView {
  * View model of category, for multiselect categories.
  */
 export interface SelectCategoryView {
+    annotation?: DataDictionaryAnnotation;
     isDisabled?: boolean;
     key: CategoryKey;
     label: string;

package/lib/components/DataDictionary/common/utils.d.ts

@@ -0,0 +1,38 @@
+import { DataDictionaryAnnotation } from "../../../common/entities";
+import { 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 declare function annotateColumnConfig(siteConfig: SiteConfig, annotationsByKey: Record<string, DataDictionaryAnnotation>): void;
+/**
+ * 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 declare function annotateSiteConfig(siteConfig: SiteConfig): void;
+/**
+ * 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 declare function annotateEntityConfig(siteConfig: SiteConfig, annotationsByKey: Record<string, DataDictionaryAnnotation>): void;
+/**
+ * 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 declare function annotateDefaultCategoryConfig(siteConfig: SiteConfig, annotationsByKey: Record<string, DataDictionaryAnnotation>): void;
+/**
+ * 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 declare function annotateEntityCategoryConfig(siteConfig: SiteConfig, annotationsByKey: Record<string, DataDictionaryAnnotation>): void;

package/lib/components/DataDictionary/common/utils.js

@@ -0,0 +1,122 @@
+/**
+ * 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, annotationsByKey) {
+    // 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) {
+    // 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, annotationsByKey) {
+    // 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, annotationsByKey) {
+    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, annotationsByKey) {
+    // 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, annotationsByKey) {
+    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) {
+    return dataDictionary.classes.reduce((acc, cls) => {
+        // Add class to map.
+        acc[cls.key] = {
+            description: cls.description,
+            label: cls.label,
+        };
+        // Add each class attribute to the map.
+        cls.attributes.forEach((attribute) => {
+            acc[attribute.key] = {
+                description: attribute.description,
+                label: attribute.label,
+            };
+        });
+        return acc;
+    }, {});
+}

package/lib/components/Filter/components/Filter/filter.js

@@ -48,7 +48,7 @@ export const Filter = ({ categorySection, categoryView, closeAncestor, isFilterD
         trackFilterOpened?.({ category: categoryView.key });
     };
     return (React.createElement(React.Fragment, null,
-        React.createElement(FilterLabel, { count: categoryView.values.length, disabled: categoryView.isDisabled, isOpen: isOpen, label: categoryView.label, onClick: onOpenFilter }),
+        React.createElement(FilterLabel, { annotation: categoryView.annotation, count: categoryView.values.length, disabled: categoryView.isDisabled, isOpen: isOpen, label: categoryView.label, onClick: onOpenFilter }),
         React.createElement(FilterPopover, { anchorPosition: anchorPosition, anchorReference: "anchorPosition", marginThreshold: 0, onClose: onCloseFilters, open: isOpen, slotProps: slotProps, TransitionComponent: TransitionComponent, transitionDuration: TransitionDuration },
             isOpen && isFilterDrawer && (React.createElement(IconButton, { Icon: CloseRounded, onClick: onCloseFilters, size: "medium" })),
             React.createElement(FilterMenu, { categorySection: categorySection, categoryKey: categoryView.key, categoryLabel: categoryView.label, isFilterDrawer: isFilterDrawer, onFilter: onFilter, onCloseFilter: onCloseFilter, values: categoryView.values })),

package/lib/components/Filter/components/FilterLabel/filterLabel.d.ts

@@ -1,9 +1,11 @@
 import { MouseEvent } from "react";
+import { DataDictionaryAnnotation } from "../../../../common/entities";
 export interface FilterLabelProps {
+    annotation?: DataDictionaryAnnotation;
     count?: number;
     disabled?: boolean;
     isOpen: boolean;
     label: string;
     onClick: (event: MouseEvent<HTMLButtonElement>) => void;
 }
-export declare const FilterLabel: ({ count, disabled, isOpen, label, onClick, }: FilterLabelProps) => JSX.Element;
+export declare const FilterLabel: ({ annotation, count, disabled, isOpen, label, onClick, }: FilterLabelProps) => JSX.Element;

package/lib/components/Filter/components/FilterLabel/filterLabel.js

@@ -1,7 +1,9 @@
 import ArrowDropDownRoundedIcon from "@mui/icons-material/ArrowDropDownRounded";
 import React from "react";
+import { Tooltip } from "../../../DataDictionary/components/Tooltip/tooltip";
 import { FilterLabel as Label } from "./filterLabel.styles";
-export const FilterLabel = ({ count, disabled = false, isOpen, label, onClick, }) => {
+export const FilterLabel = ({ annotation, count, disabled = false, isOpen, label, onClick, }) => {
     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 (React.createElement(Label, { color: "inherit", disabled: disabled, endIcon: React.createElement(ArrowDropDownRoundedIcon, { fontSize: "small" }), fullWidth: true, isOpen: isOpen, onClick: onClick }, filterLabel));
+    return (React.createElement(Tooltip, { description: annotation?.description, title: annotation?.label },
+        React.createElement(Label, { color: "inherit", disabled: disabled, endIcon: React.createElement(ArrowDropDownRoundedIcon, { fontSize: "small" }), fullWidth: true, isOpen: isOpen, onClick: onClick }, filterLabel)));
 };

package/lib/components/Index/components/Tabs/common/utils.js

@@ -4,9 +4,10 @@
  * @returns tabs list.
  */
 export function getEntityListTabs(entities) {
-    return entities.reduce((acc, { label, listView: { enableTab = true } = {}, route, tabIcon: icon, tabIconPosition: iconPosition, }) => {
+    return entities.reduce((acc, { annotation, label, listView: { enableTab = true } = {}, route, tabIcon: icon, tabIconPosition: iconPosition, }) => {
         if (enableTab) {
             acc.push({
+                annotation,
                 icon,
                 iconPosition,
                 label,

package/lib/components/Table/components/TableHead/tableHead.js

@@ -2,6 +2,7 @@ import SouthRoundedIcon from "@mui/icons-material/SouthRounded";
 import { TableHead as MTableHead, TableRow as MTableRow, TableCell, TableSortLabel, } from "@mui/material";
 import { flexRender } from "@tanstack/react-table";
 import React, { Fragment } from "react";
+import { Tooltip } from "../../../DataDictionary/components/Tooltip/tooltip";
 import { ROW_DIRECTION } from "../../common/entities";
 import { getTableCellAlign, getTableCellPadding, } from "../TableCell/common/utils";
 import { handleToggleSorting } from "../TableFeatures/RowSorting/utils";
@@ -11,6 +12,8 @@ export const TableHead = ({ rowDirection, tableInstance, }) => {
         tableInstance.getHeaderGroups().map((headerGroup) => (React.createElement(MTableHead, { key: headerGroup.id },
             React.createElement(MTableRow, null, headerGroup.headers.map(({ column, getContext, id }) => {
                 const { columnDef, getIsGrouped, getIsSorted } = column;
-                return getIsGrouped() ? null : (React.createElement(TableCell, { key: id, align: getTableCellAlign(column), padding: getTableCellPadding(id) }, shouldSortColumn(tableInstance, column) ? (React.createElement(TableSortLabel, { IconComponent: SouthRoundedIcon, active: Boolean(getIsSorted()), direction: getIsSorted() || undefined, disabled: isSortDisabled(tableInstance), onClick: (mouseEvent) => handleToggleSorting(mouseEvent, tableInstance, column) }, flexRender(columnDef.header, getContext()))) : (flexRender(columnDef.header, getContext()))));
+                const annotation = columnDef.meta?.annotation;
+                return getIsGrouped() ? null : (React.createElement(TableCell, { key: id, align: getTableCellAlign(column), padding: getTableCellPadding(id) },
+                    React.createElement(Tooltip, { description: annotation?.description, title: annotation?.label }, shouldSortColumn(tableInstance, column) ? (React.createElement(TableSortLabel, { IconComponent: SouthRoundedIcon, active: Boolean(getIsSorted()), direction: getIsSorted() || undefined, disabled: isSortDisabled(tableInstance), onClick: (mouseEvent) => handleToggleSorting(mouseEvent, tableInstance, column) }, flexRender(columnDef.header, getContext()))) : (flexRender(columnDef.header, getContext())))));
             })))))));
 };

package/lib/components/common/Tabs/tabs.d.ts

@@ -1,9 +1,11 @@
 import { TabProps as MTabProps, TabsProps as MTabsProps } from "@mui/material";
 import { ReactNode } from "react";
+import { DataDictionaryAnnotation } from "../../../common/entities";
 export type TabsValue = MTabsProps["value"];
 export type TabValue = MTabProps["value"];
 export type OnTabChangeFn = (tabValue: TabValue) => void;
 export interface Tab {
+    annotation?: DataDictionaryAnnotation;
     count?: string;
     icon?: MTabProps["icon"];
     iconPosition?: MTabProps["iconPosition"];

package/lib/components/common/Tabs/tabs.js

@@ -1,6 +1,19 @@
 import { Tabs as MTabs, } from "@mui/material";
 import React from "react";
+import { Tooltip } from "../../DataDictionary/components/Tooltip/tooltip";
 import { Tab, TabScrollFuzz } from "./tabs.styles";
 export const Tabs = ({ className, onTabChange, tabs, value, }) => {
-    return (React.createElement(MTabs, { allowScrollButtonsMobile: true, className: className, onChange: (_, tabValue) => onTabChange(tabValue), ScrollButtonComponent: TabScrollFuzz, value: value }, tabs.map(({ count, icon, iconPosition = "start", label, value: tabValue }, t) => (React.createElement(Tab, { icon: icon, iconPosition: icon ? iconPosition : undefined, key: `${label}${t}`, label: count ? `${label} (${count})` : label, value: tabValue })))));
+    return (React.createElement(MTabs, { allowScrollButtonsMobile: true, className: className, onChange: (_, tabValue) => onTabChange(tabValue), ScrollButtonComponent: TabScrollFuzz, value: value }, tabs.map(({ annotation, count, icon, iconPosition = "start", label, value: tabValue, }, t) => (React.createElement(Tab, { icon: icon, iconPosition: icon ? iconPosition : undefined, key: `${label}${t}`, label: buildTabLabel(label, count, annotation), value: tabValue })))));
 };
+/**
+ * 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, count, annotation) {
+    return (React.createElement(Tooltip, { description: annotation?.description, title: annotation?.label },
+        React.createElement("span", null, count ? `${label} (${count})` : label)));
+}

package/lib/config/entities.d.ts

@@ -1,7 +1,7 @@
 import { TabProps as MTabProps, Theme, ThemeOptions } from "@mui/material";
 import { CellContext, ColumnDef, ColumnMeta, ColumnSort, GroupingState, RowData, Table, 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";
@@ -70,6 +70,7 @@ export interface CategoryGroup {
  * Model of category configured in site config.
  */
 export interface CategoryConfig {
+    annotation?: DataDictionaryAnnotation;
     key: string;
     label: string;
     mapSelectCategoryValue?: (selectCategoryValue: SelectCategoryValueView) => SelectCategoryValueView;
@@ -127,6 +128,7 @@ export type EntityPath = string;
  * the detail and the list page configuration.
  */
 export interface EntityConfig<T = any, I = any> extends TabConfig {
+    annotation?: DataDictionaryAnnotation;
     apiPath?: EntityPath;
     categoryGroupConfig?: CategoryGroupConfig;
     detail: BackPageConfig;
@@ -137,6 +139,7 @@ export interface EntityConfig<T = any, I = any> extends TabConfig {
     getId?: GetIdFunction<T>;
     getTitle?: GetTitleFunction<T>;
     hideTabs?: boolean;
+    key?: string;
     list: ListConfig<T>;
     listView?: ListViewConfig;
     options?: Options;
@@ -295,6 +298,7 @@ export interface SiteConfig {
     categoryGroupConfig?: CategoryGroupConfig;
     contentDir?: string;
     contentThemeOptionsFn?: ThemeOptionsFn;
+    dataDictionary?: DataDictionary;
     dataSource: DataSourceConfig;
     entities: EntityConfig[];
     explorerTitle: HeroTitle;

package/lib/hooks/useCategoryFilter.js

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

package/lib/providers/config.js

@@ -1,4 +1,5 @@
-import React, { createContext } from "react";
+import React, { createContext, useState } from "react";
+import { annotateSiteConfig } from "../components/DataDictionary/common/utils";
 import { getDefaultConfig, getDefaultEntityConfig, getEntityConfig, } from "../config/utils";
 export const ConfigContext = createContext({
     config: getDefaultConfig(),
@@ -7,7 +8,13 @@ export const ConfigContext = createContext({
     entityListType: "",
 });
 export function ConfigProvider({ children, config, entityListType = "", }) {
-    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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databiosphere/findable-ui",
-  "version": "21.2.0",
+  "version": "21.3.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",

package/src/common/entities.ts

@@ -1,3 +1,12 @@
+/**
+ * Model of a value of a metadata class.
+ */
+export interface Attribute {
+  description: string;
+  key: string;
+  label: string;
+}
+
 /**
  * Filterable metadata keys.
  */
@@ -12,11 +21,38 @@ export interface CategoryTag {
   superseded: boolean;
 }
 
+/**
+ * Model of a metadata class, to be specified manually or built from LinkML schema.
+ */
+export interface Class {
+  attributes: Attribute[];
+  description: string;
+  key: string;
+  label: string;
+  name: string;
+}
+
 /**
  * Category values to be used as keys. For example, "Homo sapiens" or "10X 3' v2 sequencing".
  */
 export type CategoryValueKey = unknown;
 
+/**
+ * Model of a metadata dictionary containing a set of classes and their definitions.
+ */
+export interface DataDictionary {
+  classes: Class[];
+}
+
+/**
+ * Label and description values from a data dictionary that are added to a site
+ * config value.
+ */
+export interface DataDictionaryAnnotation {
+  description: string;
+  label: string;
+}
+
 /**
  * Set of selected category values.
  */
@@ -72,6 +108,7 @@ export interface SelectCategoryValueView {
  * View model of category, for multiselect categories.
  */
 export interface SelectCategoryView {
+  annotation?: DataDictionaryAnnotation;
   isDisabled?: boolean;
   key: CategoryKey;
   label: string;

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/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);

package/tests/dataDictionary_utils.test.ts

@@ -0,0 +1,153 @@
+import {
+  annotateColumnConfig,
+  annotateDefaultCategoryConfig,
+  annotateEntityCategoryConfig,
+  annotateEntityConfig,
+} from "../src/components/DataDictionary/common/utils";
+import { SiteConfig } from "../src/config/entities";
+
+describe("Data Dictionary", () => {
+  it("annotates entity", () => {
+    const key = "entity";
+
+    // Create annotation for column and add to dummy annotation map.
+    const annotation = {
+      description: "description for entity",
+      label: "entity",
+    };
+    const annotationsByKey = {
+      [key]: annotation,
+    };
+
+    // Create dummy site config.
+    const siteConfig = {
+      entities: [
+        {
+          key,
+          list: {
+            columns: [{ id: "col150" }, { id: "col1" }],
+          },
+        },
+      ],
+    } as unknown as SiteConfig;
+
+    // Annotate
+    annotateEntityConfig(siteConfig, annotationsByKey);
+
+    // Confirm entity is annotated.
+    const entity = siteConfig.entities[0];
+    expect(entity.annotation).toEqual(annotation);
+  });
+
+  it("annotates entity category config", () => {
+    const key = "filter0";
+
+    // Create annotation for column and add to dummy annotation map.
+    const annotation = {
+      description: "description for filter 0",
+      label: "filter 0",
+    };
+    const annotationsByKey = {
+      [key]: annotation,
+    };
+
+    // Create dummy site config.
+    const siteConfig = {
+      entities: [
+        {
+          categoryGroupConfig: {
+            categoryGroups: [
+              {
+                categoryConfigs: [
+                  {
+                    key,
+                    label: "filter 0",
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    } as unknown as SiteConfig;
+
+    // Annotate
+    annotateEntityCategoryConfig(siteConfig, annotationsByKey);
+
+    // Confirm filter is annotated.
+    const categoryConfig =
+      siteConfig.entities[0].categoryGroupConfig?.categoryGroups[0]
+        .categoryConfigs[0];
+    expect(categoryConfig?.annotation).toEqual(annotation);
+  });
+
+  it("annotates default category config", () => {
+    const key = "filter0";
+
+    // Create annotation for column and add to dummy annotation map.
+    const annotation = {
+      description: "description for filter 0",
+      label: "filter 0",
+    };
+    const annotationsByKey = {
+      [key]: annotation,
+    };
+
+    // Create dummy site config.
+    const siteConfig = {
+      categoryGroupConfig: {
+        categoryGroups: [
+          {
+            categoryConfigs: [
+              {
+                key,
+                label: "filter 0",
+              },
+            ],
+          },
+        ],
+      },
+    } as unknown as SiteConfig;
+
+    // Annotate
+    annotateDefaultCategoryConfig(siteConfig, annotationsByKey);
+
+    // Confirm filter is annotated.
+    const categoryConfig =
+      siteConfig.categoryGroupConfig?.categoryGroups[0].categoryConfigs[0];
+    expect(categoryConfig?.annotation).toEqual(annotation);
+  });
+
+  it("annotates column", () => {
+    const key = "col0";
+
+    // Create annotation for column and add to dummy annotation map.
+    const annotation = {
+      description: "description for column 0",
+      label: "column 0",
+    };
+    const annotationsByKey = {
+      [key]: annotation,
+    };
+
+    // Create dummy site config.
+    const siteConfig = {
+      entities: [
+        {
+          list: {
+            columns: [{ id: key }, { id: "col1" }],
+          },
+          name: "entity",
+        },
+      ],
+    } as unknown as SiteConfig;
+
+    // Annotate
+    annotateColumnConfig(siteConfig, annotationsByKey);
+
+    // Confirm column 0 is annotated and column 1 is not.
+    const columns = siteConfig.entities[0].list.columns ?? [];
+    expect((columns[0]?.meta as any)?.annotation).toEqual(annotation);
+    expect((columns[1]?.meta as any)?.annotation).toBeUndefined();
+  });
+});

package/types/data-explorer-ui.d.ts

@@ -18,6 +18,7 @@ import type {} from "@mui/material/Typography";
 import type {} from "@tanstack/react-table";
 import { RowData } from "@tanstack/react-table";
 import { DataLayer } from "../src/common/analytics/entities";
+import { DataDictionaryAnnotation } from "../src/common/entities";
 import {
   CustomFeatureInitialTableState,
   CustomFeatureInstance,
@@ -268,6 +269,7 @@ declare module "@tanstack/react-table" {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars -- TData and TValue are unused variables.
   interface ColumnMeta<TData extends RowData, TValue> {
     align?: TableCellProps["align"];
+    annotation?: DataDictionaryAnnotation;
     columnPinned?: boolean;
     header?: string;
     width?: GridTrackSize;