feat: optional tooltip helper for table column headers

packages/open-ui-kit/src/components/table/components/table.tsx

@@ -32,6 +32,7 @@ import { TableProps } from "../types";
 import { tableComfortStyles, tableCompactStyles } from "../styles";
 import { Box, PaginationItem, SvgIconProps, useTheme } from "@mui/material";
 import { EmptyState, Link, OverflowTooltip, TooltipSize } from "@/components";
+import { withHeaderHelpTooltips } from "../utils/helpers";
 
 /**
  * `Table` Component
@@ -109,7 +110,7 @@ export const CreateTableInstance = <TData extends MRT_RowData>({
     enableFilters: !!data.length,
     enableFullScreenToggle: !!data.length,
     enableHiding: !!data.length,
-    columns,
+    columns: withHeaderHelpTooltips(columns),
     data,
     enableColumnActions: false,
     enableTopToolbar,

packages/open-ui-kit/src/components/table/stories/table.stories.tsx

@@ -118,18 +118,21 @@ const data = {
       accessorKey: "id",
       header: "ID",
       size: 350,
+      meta: { headerTooltip: "The unique identifier of the record" },
     },
     {
       header: "Name",
       accessorKey: "name",
       enableColumnOrdering: false,
       size: 200,
+      meta: { headerTooltip: "Full name of the person" },
     },
     {
       header: "Phone",
       accessorKey: "phone",
       enableSorting: false,
       enableColumnOrdering: false,
+      meta: { headerTooltip: "Primary phone number" },
     },
     {
       header: "firstName",

packages/open-ui-kit/src/components/table/types/index.ts

@@ -68,11 +68,16 @@ interface TableRow {
   subRows?: ReactNode;
 }
 
+interface HeaderTooltipMeta {
+  headerTooltip?: ReactNode;
+}
+
 export {
   AtomicTypes,
   ExportProps,
   TableProps,
   TableRow,
   TopToolbarProps,
   TableTitle,
+  HeaderTooltipMeta,
 };

packages/open-ui-kit/src/components/table/utils/helpers.tsx

@@ -6,9 +6,14 @@
 
 import {
   MRT_Column,
+  MRT_ColumnDef,
   MRT_RowData,
   MRT_TableInstance,
 } from "material-react-table";
+import { Box, IconButton, Stack } from "@mui/material";
+import { Tooltip, TooltipSize } from "@/components";
+import { InfoCircleOutline } from "@/custom-icons";
+import { HeaderTooltipMeta } from "../types";
 
 //  Check rightmost left-pinned column / leftmost right-pinned column
 export const isOuterPinnedColumn = <TData extends MRT_RowData>(
@@ -38,3 +43,49 @@ export const parseFromValuesOrFunc = <T, U>(
   fn: ((arg: U) => T) | T | undefined,
   arg: U,
 ): T | undefined => (fn instanceof Function ? fn(arg) : fn);
+
+// Enhance column headers to optionally show an info tooltip icon.
+// Usage: column.meta?.headerTooltip?: React.ReactNode
+export const withHeaderHelpTooltips = <
+  TData extends MRT_RowData,
+  TValue = unknown,
+>(
+  columns: MRT_ColumnDef<TData, TValue>[],
+): MRT_ColumnDef<TData, TValue>[] => {
+  return columns.map((col) => {
+    const meta = col.meta as HeaderTooltipMeta;
+    const hasHeaderTooltip =
+      meta?.headerTooltip !== undefined && meta?.headerTooltip !== null;
+
+    const updated: MRT_ColumnDef<TData, TValue> = {
+      ...col,
+    };
+
+    if (hasHeaderTooltip) {
+      updated.Header = (
+        <Stack direction="row" alignItems="flex-start" gap="2px">
+          <Box component="span">{col.header}</Box>
+          <Tooltip
+            size={TooltipSize.Medium}
+            title={meta?.headerTooltip}
+            placement="top"
+          >
+            <IconButton
+              sx={{
+                color: (theme) => theme.palette.vars.controlIconDefault,
+                "&:hover": {
+                  color: (theme) => theme.palette.vars.controlIconHover,
+                },
+              }}
+              aria-label="Column info"
+            >
+              <InfoCircleOutline sx={{ width: "16px", height: "16px" }} />
+            </IconButton>
+          </Tooltip>
+        </Stack>
+      );
+    }
+
+    return updated;
+  });
+};