From 99030998cba981215a56ce260c588385f78b398a Mon Sep 17 00:00:00 2001
From: cassie spain <58054751+dreamwasp@users.noreply.github.com>
Date: Wed, 29 Jan 2025 11:44:47 -0500
Subject: [PATCH] fix: DataGrid reformatted to `table` and aria-sort added

Refactors the DataTable + DataList components to properly be semantic HTML tables and adds `aria-sort` to the appropriate controls
---
 .../__snapshots__/gamut.test.ts.snap          |  2 +-
 .../src/DataList/Controls/FilterControl.tsx   |  1 -
 .../src/DataList/Controls/SortControl.tsx     |  7 ++
 packages/gamut/src/DataList/DataGrid.tsx      |  5 +-
 packages/gamut/src/DataList/EmptyRows.tsx     | 43 +++++-----
 .../Rows/TableHeaderRow.tsx}                  | 28 +++----
 .../Row.tsx => Tables/Rows/TableRow.tsx}      | 82 ++++++++++++-------
 packages/gamut/src/List/List.tsx              | 76 ++++++++++-------
 packages/gamut/src/List/ListCol.tsx           | 18 ++--
 packages/gamut/src/List/ListHeader.tsx        | 25 ------
 packages/gamut/src/List/ListProvider.tsx      |  6 +-
 packages/gamut/src/List/ListRow.tsx           | 52 +++++++++---
 packages/gamut/src/List/TableHeader.tsx       | 28 +++++++
 packages/gamut/src/List/elements.tsx          | 49 +++++++----
 packages/gamut/src/List/index.tsx             |  2 +-
 packages/gamut/src/List/types.ts              |  4 +-
 packages/gamut/src/List/utils.tsx             | 10 +++
 .../DataList/DataList.stories.tsx             | 18 ++--
 .../DataTable/DataTable.stories.tsx           | 21 +++--
 19 files changed, 295 insertions(+), 182 deletions(-)
 rename packages/gamut/src/DataList/{Rows/HeaderRow.tsx => Tables/Rows/TableHeaderRow.tsx} (80%)
 rename packages/gamut/src/DataList/{Rows/Row.tsx => Tables/Rows/TableRow.tsx} (57%)
 delete mode 100644 packages/gamut/src/List/ListHeader.tsx
 create mode 100644 packages/gamut/src/List/TableHeader.tsx
 create mode 100644 packages/gamut/src/List/utils.tsx

diff --git a/packages/gamut/__tests__/__snapshots__/gamut.test.ts.snap b/packages/gamut/__tests__/__snapshots__/gamut.test.ts.snap
index 21c0132482..7e999fd87d 100644
--- a/packages/gamut/__tests__/__snapshots__/gamut.test.ts.snap
+++ b/packages/gamut/__tests__/__snapshots__/gamut.test.ts.snap
@@ -63,7 +63,6 @@ exports[`Gamut Exported Keys 1`] = `
   "LayoutGrid",
   "List",
   "ListCol",
-  "ListHeader",
   "ListRow",
   "Logo",
   "LogoDefault",
@@ -99,6 +98,7 @@ exports[`Gamut Exported Keys 1`] = `
   "submitSuccessStatus",
   "Tab",
   "TabButton",
+  "TableHeader",
   "TabList",
   "TabNav",
   "TabNavLink",
diff --git a/packages/gamut/src/DataList/Controls/FilterControl.tsx b/packages/gamut/src/DataList/Controls/FilterControl.tsx
index 85ae96d564..a30fbc5f5b 100644
--- a/packages/gamut/src/DataList/Controls/FilterControl.tsx
+++ b/packages/gamut/src/DataList/Controls/FilterControl.tsx
@@ -64,7 +64,6 @@ export const FilterControl: React.FC<FilterProps> = ({
       {menuOpen && (
         <PopoverContainer
           isOpen
-          inline
           targetRef={target as any}
           offset={0}
           alignment={justify === 'left' ? 'bottom-right' : 'bottom-left'}
diff --git a/packages/gamut/src/DataList/Controls/SortControl.tsx b/packages/gamut/src/DataList/Controls/SortControl.tsx
index b1cdc09db2..36ff3ba479 100644
--- a/packages/gamut/src/DataList/Controls/SortControl.tsx
+++ b/packages/gamut/src/DataList/Controls/SortControl.tsx
@@ -61,6 +61,13 @@ export const SortControl: React.FC<SortControlProps> = ({
 
   return (
     <SortAnchor
+      aria-sort={
+        direction === 'none'
+          ? 'none'
+          : direction === 'asc'
+          ? 'ascending'
+          : 'descending'
+      }
       variant="interface"
       onClick={() =>
         onSort?.({
diff --git a/packages/gamut/src/DataList/DataGrid.tsx b/packages/gamut/src/DataList/DataGrid.tsx
index 305678143a..0904768fbf 100644
--- a/packages/gamut/src/DataList/DataGrid.tsx
+++ b/packages/gamut/src/DataList/DataGrid.tsx
@@ -4,8 +4,8 @@ import { List } from '../List';
 import { EmptyRows } from './EmptyRows';
 import { ListControlContext, useListControls } from './hooks/useListControls';
 import { ListStateContext } from './hooks/useListState';
-import { HeaderRow } from './Rows/HeaderRow';
-import { DataRow, MarshaledColProps } from './Rows/Row';
+import { HeaderRow } from './Tables/Rows/TableHeaderRow';
+import { DataRow, MarshaledColProps } from './Tables/Rows/TableRow';
 import { ColumnConfig, DataListControls, IdentifiableKeys } from './types';
 
 export interface DataGridProps<
@@ -97,6 +97,7 @@ export function DataGrid<
       <ListControlContext.Provider value={listControls}>
         <List
           {...rest}
+          as="table"
           emptyMessage={emptyMessage ?? <EmptyRows />}
           header={
             header ? (
diff --git a/packages/gamut/src/DataList/EmptyRows.tsx b/packages/gamut/src/DataList/EmptyRows.tsx
index c93f6da2da..3684664b57 100644
--- a/packages/gamut/src/DataList/EmptyRows.tsx
+++ b/packages/gamut/src/DataList/EmptyRows.tsx
@@ -1,5 +1,3 @@
-import { DotLoose } from '@codecademy/gamut-patterns';
-
 import { FlexBox } from '../Box';
 import { FillButton } from '../Button';
 import { Text } from '../Typography';
@@ -9,26 +7,27 @@ export const EmptyRows = () => {
   const { onResetQuery } = useControlContext();
 
   return (
-    <>
-      <FlexBox
-        bg="background-current"
-        center
-        column
-        gap={16}
-        left="calc(50% - 160px)"
-        p={32}
-        position="sticky"
-        top="calc(50% - 92px)"
-        width="320px"
-        zIndex={1}
-      >
-        <Text variant="title-sm">No Results Found</Text>
-        <Text variant="p-base">Remove filters to view</Text>
-        <FillButton onClick={onResetQuery}>Reset Filters</FillButton>
-      </FlexBox>
-      <FlexBox height={409} center width={1}>
-        <DotLoose position="absolute" inset={0} top={-2} />
+    <FlexBox
+      as="tbody"
+      bg="background-current"
+      left="calc(50% - 160px)"
+      p={32}
+      position="sticky"
+      top="calc(50% - 66px)"
+      width="320px"
+      zIndex={1}
+    >
+      <FlexBox as="tr" center column gap={16} width="100%">
+        <th>
+          <Text variant="title-sm">No Results Found</Text>
+        </th>
+        <th>
+          <Text variant="p-base">Remove filters to view</Text>
+        </th>
+        <th>
+          <FillButton onClick={onResetQuery}>Reset Filters</FillButton>
+        </th>
       </FlexBox>
-    </>
+    </FlexBox>
   );
 };
diff --git a/packages/gamut/src/DataList/Rows/HeaderRow.tsx b/packages/gamut/src/DataList/Tables/Rows/TableHeaderRow.tsx
similarity index 80%
rename from packages/gamut/src/DataList/Rows/HeaderRow.tsx
rename to packages/gamut/src/DataList/Tables/Rows/TableHeaderRow.tsx
index cd72074e67..34e6ebf9a6 100644
--- a/packages/gamut/src/DataList/Rows/HeaderRow.tsx
+++ b/packages/gamut/src/DataList/Tables/Rows/TableHeaderRow.tsx
@@ -1,15 +1,15 @@
 import { memo, ReactElement } from 'react';
 
-import { FlexBox } from '../..';
-import { ListCol, ListHeader } from '../../List';
+import { FlexBox } from '../../..';
+import { ListCol, TableHeader } from '../../../List';
 import {
   ExpandControl,
   FilterControl,
   SelectControl,
   SortControl,
-} from '../Controls';
-import { useControlContext } from '../hooks/useListControls';
-import { ColumnConfig, Query } from '../types';
+} from '../../Controls';
+import { useControlContext } from '../../hooks/useListControls';
+import { ColumnConfig, Query } from '../../types';
 
 interface HeaderComponent {
   <Row>(props: {
@@ -21,23 +21,17 @@ interface HeaderComponent {
   }): ReactElement<any, any>;
 }
 
-export const Header: HeaderComponent = ({
+export const TableHeaderRow: HeaderComponent = ({
   columns,
   selected = false,
   empty = false,
   hideSelectAll,
 }) => {
-  const {
-    expandable,
-    selectable,
-    onSelect,
-    onFilter,
-    onSort,
-    prefixId,
-  } = useControlContext();
+  const { expandable, selectable, onSelect, onFilter, onSort, prefixId } =
+    useControlContext();
 
   return (
-    <ListHeader>
+    <TableHeader>
       <>
         {selectable && (
           <ListCol size="content">
@@ -86,8 +80,8 @@ export const Header: HeaderComponent = ({
           </ListCol>
         )}
       </>
-    </ListHeader>
+    </TableHeader>
   );
 };
 
-export const HeaderRow = memo(Header) as HeaderComponent;
+export const HeaderRow = memo(TableHeaderRow) as HeaderComponent;
diff --git a/packages/gamut/src/DataList/Rows/Row.tsx b/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx
similarity index 57%
rename from packages/gamut/src/DataList/Rows/Row.tsx
rename to packages/gamut/src/DataList/Tables/Rows/TableRow.tsx
index 856f69b83b..38784942c4 100644
--- a/packages/gamut/src/DataList/Rows/Row.tsx
+++ b/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx
@@ -1,12 +1,18 @@
-import { memo, ReactElement, ReactNode, useCallback } from 'react';
+import {
+  isValidElement,
+  memo,
+  ReactElement,
+  useCallback,
+  useMemo,
+} from 'react';
 
-import { Text } from '../..';
-import { ListCol, ListRow } from '../../List';
-import { ColProps } from '../../List/elements';
-import { Shimmer } from '../../Loading/Shimmer';
-import { ExpandControl, SelectControl } from '../Controls';
-import { useControlContext } from '../hooks/useListControls';
-import { ColumnConfig, IdentifiableKeys } from '../types';
+import { Text } from '../../..';
+import { ListCol, ListRow } from '../../../List';
+import { ColProps } from '../../../List/elements';
+import { Shimmer } from '../../../Loading/Shimmer';
+import { ExpandControl, SelectControl } from '../../Controls';
+import { useControlContext } from '../../hooks/useListControls';
+import { ColumnConfig, IdentifiableKeys } from '../../types';
 
 export type MarshaledColProps = Partial<Pick<ColProps, 'showOverflow'>>;
 
@@ -23,7 +29,7 @@ interface DataRow {
   ): ReactElement<any, any>;
 }
 
-export const Row: DataRow = ({
+export const TableRow: DataRow = ({
   id,
   columns,
   row,
@@ -50,8 +56,24 @@ export const Row: DataRow = ({
     });
   }, [onExpand, expandedContent, id, row]);
 
+  const numberOfColumns = useMemo(() => {
+    return columns.length;
+  }, [columns]);
+
+  const listRowProps = expandable
+    ? {
+        expanded,
+        renderExpanded: renderExpandedContent,
+      }
+    : {};
+
   return (
-    <ListRow expanded={expanded} renderExpanded={renderExpandedContent}>
+    <ListRow
+      as="tr"
+      numOfColumns={numberOfColumns}
+      selectable={selectable}
+      {...listRowProps}
+    >
       {selectable && (
         <ListCol
           {...listColProps}
@@ -70,18 +92,18 @@ export const Row: DataRow = ({
         </ListCol>
       )}
       {columns.map(({ key, render, size, justify, fill, type }) => {
+        const newKey = prefixId(`${id}-col-${String(key)}`);
         const colProps = {
           ...listColProps,
           size,
           justify,
           fill,
           type,
-          key: prefixId(`${id}-col-${String(key)}`),
         };
 
         if (loading) {
           return (
-            <ListCol {...colProps}>
+            <ListCol {...colProps} key={newKey}>
               <Shimmer
                 minHeight={24}
                 height="calc(100% - 1rem)"
@@ -92,22 +114,24 @@ export const Row: DataRow = ({
         }
 
         return (
-          <ListCol {...colProps}>
-            <>
-              {render ? (
-                render(row)
-              ) : typeof row[key] === 'string' ? (
-                <Text
-                  truncate="ellipsis"
-                  truncateLines={1}
-                  textAlign={justify ?? 'left'}
-                >
-                  {row[key] as ReactNode}
-                </Text>
-              ) : (
-                row[key]
-              )}
-            </>
+          <ListCol {...colProps} key={newKey}>
+            {render ? (
+              render(row)
+            ) : typeof row[key] === 'string' || typeof row[key] === 'number' ? (
+              <Text
+                truncate="ellipsis"
+                truncateLines={1}
+                textAlign={justify ?? 'left'}
+              >
+                {row[key] as string}
+              </Text>
+            ) : isValidElement(row[key]) ? (
+              (row[key] as ReactElement)
+            ) : !row[key] ? (
+              ''
+            ) : (
+              'Invalid data type'
+            )}
           </ListCol>
         );
       })}
@@ -125,4 +149,4 @@ export const Row: DataRow = ({
   );
 };
 
-export const DataRow = memo(Row) as DataRow;
+export const DataRow = memo(TableRow) as DataRow;
diff --git a/packages/gamut/src/List/List.tsx b/packages/gamut/src/List/List.tsx
index 42353ef9cd..ec822f12d4 100644
--- a/packages/gamut/src/List/List.tsx
+++ b/packages/gamut/src/List/List.tsx
@@ -1,15 +1,16 @@
+import { DotLoose } from '@codecademy/gamut-patterns';
 import isArray from 'lodash/isArray';
 import { ComponentProps, forwardRef, useEffect, useRef, useState } from 'react';
 import * as React from 'react';
 
-import { Box, BoxProps } from '../Box';
-import { ListEl } from './elements';
+import { Box, BoxProps, FlexBox } from '../Box';
+import { ListEl, ListWrapper } from './elements';
 import { ListProvider, useList } from './ListProvider';
 import { AllListProps } from './types';
 
 export interface ListProps extends AllListProps<ComponentProps<typeof ListEl>> {
-  /** Whether List should be an ol or ul element */
-  as?: 'ol' | 'ul';
+  /** Whether List should be an ol, ul element, or table */
+  as?: 'ol' | 'ul' | 'table';
   /** Whether a placeholder width should be set when loading */
   loading?: boolean;
   /** Should only be used internally to Gamut */
@@ -58,45 +59,61 @@ export const List = forwardRef<HTMLUListElement, ListProps>(
     const [isEnd, setIsEnd] = useState(false);
     const showShadow = shadow && scrollable && !isEnd;
     const value = useList({
-      isOl: as === 'ol',
+      listType: as,
       rowBreakpoint,
       scrollable,
       spacing,
       variant,
     });
 
-    const topOfTable = useRef<HTMLDivElement>(null);
+    const wrapperRef = useRef<HTMLDivElement>(null);
+    const tableRef = useRef<HTMLDivElement>(null);
 
     useEffect(() => {
-      if (scrollToTopOnUpdate && topOfTable.current !== null) {
-        topOfTable.current.scrollTo({ top: 0 });
+      const wrapperWidth =
+        wrapperRef?.current?.getBoundingClientRect()?.width ?? 0;
+      const tableWidth = tableRef?.current?.getBoundingClientRect().width ?? 0;
+
+      setIsEnd(tableWidth < wrapperWidth);
+    }, []);
+
+    const isTable = as === 'table';
+    useEffect(() => {
+      if (scrollToTopOnUpdate && tableRef.current !== null) {
+        tableRef.current.scrollTo({ top: 0 });
       }
     });
 
     const listContent = (
-      <ListEl as={as} ref={ref} variant={value.variant}>
+      <ListEl as={isTable ? 'tbody' : as} ref={ref} variant={value.variant}>
         {children}
       </ListEl>
     );
 
     const scrollHandler = (event: React.UIEvent<HTMLDivElement>) => {
       const { offsetWidth, scrollLeft, scrollWidth } = event.currentTarget;
-      setIsEnd(offsetWidth + scrollLeft >= scrollWidth);
+      setIsEnd(offsetWidth + Math.ceil(scrollLeft) >= scrollWidth);
     };
 
     const listContents = (
       <>
-        {header} {isEmpty ? emptyMessage : listContent}
+        {header}
+        {isEmpty ? emptyMessage : listContent}
       </>
     );
 
     const content =
       isEmpty || loading ? (
         <Box
+          as="table"
+          maxHeight="inherit"
+          height="inherit"
+          minHeight="inherit"
           minWidth="min-content"
-          width="100%"
           position="relative"
-          ref={topOfTable}
+          overflow="inherit"
+          ref={tableRef}
+          width="100%"
         >
           {listContents}
         </Box>
@@ -106,35 +123,36 @@ export const List = forwardRef<HTMLUListElement, ListProps>(
 
     return (
       <ListProvider value={value}>
-        <Box
-          position="relative"
+        <ListWrapper
+          id={id}
+          onScroll={scrollable ? scrollHandler : undefined}
           overflow={overflowHidden ? 'hidden' : overflow}
+          position="relative"
+          ref={wrapperRef}
+          scrollable={!isEmpty && showShadow}
           width={1}
-          id={id}
+          maxHeight={height}
         >
           <Box
+            as={isTable && !isEmpty && !loading ? 'table' : 'div'}
             data-testid={`scrollable-${id}`}
-            maxHeight={height}
+            height={isEmpty ? height : 'fit-content'}
             maxWidth={1}
             minHeight={minHeight}
-            onScroll={scrollable ? scrollHandler : undefined}
             overflow="inherit"
             position="relative"
-            ref={!isEmpty ? topOfTable : undefined}
+            ref={!isEmpty ? tableRef : undefined}
+            width="inherit"
           >
             {content}
           </Box>
-          {showShadow && (
-            <Box
-              position="absolute"
-              right={-10}
-              top={0}
-              bottom={0}
-              width={10}
-              boxShadow="0 0 48px black, 0 0 24px black"
-            />
+
+          {isEmpty && (
+            <FlexBox center width={1}>
+              <DotLoose position="absolute" inset={0} top={-2} />
+            </FlexBox>
           )}
-        </Box>
+        </ListWrapper>
       </ListProvider>
     );
   }
diff --git a/packages/gamut/src/List/ListCol.tsx b/packages/gamut/src/List/ListCol.tsx
index fbf42d3bbe..7c7164454d 100644
--- a/packages/gamut/src/List/ListCol.tsx
+++ b/packages/gamut/src/List/ListCol.tsx
@@ -1,6 +1,6 @@
 import { ComponentProps, forwardRef } from 'react';
 
-import { ColEl, StickyColumnWrapper } from './elements';
+import { ColEl, StickyHeaderColWrapper } from './elements';
 import { useListContext } from './ListProvider';
 import { PublicListProps } from './types';
 
@@ -9,9 +9,14 @@ export interface ListColProps
 
 export const ListCol = forwardRef<HTMLDivElement, ListColProps>(
   ({ type, ...rest }, ref) => {
-    const { isOl, scrollable, ...activeVariants } = useListContext();
-    const sticky = type === 'header' && scrollable;
-    const isOrderedHeader = isOl && type === 'header';
+    const { listType, scrollable, ...activeVariants } = useListContext();
+    const isOl = listType === 'ol';
+    const isTable = listType === 'table';
+    const isHeader = type === 'header';
+    const sticky = isHeader && scrollable;
+    const isOrderedHeader = isOl && isHeader;
+    const colEl =
+      isTable && !sticky && isHeader ? 'th' : !isTable || sticky ? 'div' : 'td';
 
     const col = (
       <ColEl
@@ -21,13 +26,14 @@ export const ListCol = forwardRef<HTMLDivElement, ListColProps>(
         type={isOrderedHeader ? 'orderedHeader' : type}
         sticky={sticky}
         ref={ref}
+        as={colEl}
       />
     );
     if (sticky) {
       return (
-        <StickyColumnWrapper data-testid="header-container">
+        <StickyHeaderColWrapper data-testid="header-container">
           {col}
-        </StickyColumnWrapper>
+        </StickyHeaderColWrapper>
       );
     }
     return <>{col}</>;
diff --git a/packages/gamut/src/List/ListHeader.tsx b/packages/gamut/src/List/ListHeader.tsx
deleted file mode 100644
index c40572f18e..0000000000
--- a/packages/gamut/src/List/ListHeader.tsx
+++ /dev/null
@@ -1,25 +0,0 @@
-import { ComponentProps, forwardRef } from 'react';
-
-import { HeaderEl } from './elements';
-import { useListContext } from './ListProvider';
-import { PublicListProps } from './types';
-
-export interface ListHeaderProps
-  extends Partial<PublicListProps<ComponentProps<typeof HeaderEl>>> {}
-
-export const ListHeader = forwardRef<HTMLDivElement, ListHeaderProps>(
-  ({ children, ...rest }, ref) => {
-    const { spacing, scrollable, variant } = useListContext();
-    return (
-      <HeaderEl
-        {...rest}
-        spacing={spacing}
-        variant={variant}
-        scrollable={scrollable}
-        ref={ref}
-      >
-        {children}
-      </HeaderEl>
-    );
-  }
-);
diff --git a/packages/gamut/src/List/ListProvider.tsx b/packages/gamut/src/List/ListProvider.tsx
index bc56e6b8ce..0d7c2d8fdd 100644
--- a/packages/gamut/src/List/ListProvider.tsx
+++ b/packages/gamut/src/List/ListProvider.tsx
@@ -20,7 +20,7 @@ export function useListContext() {
 }
 
 export function useList({
-  isOl,
+  listType,
   rowBreakpoint,
   scrollable,
   spacing,
@@ -37,13 +37,13 @@ export function useList({
   return useMemo(
     () => ({
       depth: depth + 1,
-      isOl,
+      listType,
       root: depth === 0,
       rowBreakpoint,
       scrollable,
       spacing: activeSpacing,
       variant: activeVariant,
     }),
-    [isOl, scrollable, activeVariant, activeSpacing, depth, rowBreakpoint]
+    [listType, scrollable, activeVariant, activeSpacing, depth, rowBreakpoint]
   );
 }
diff --git a/packages/gamut/src/List/ListRow.tsx b/packages/gamut/src/List/ListRow.tsx
index 9d78ef93ca..45a86463b8 100644
--- a/packages/gamut/src/List/ListRow.tsx
+++ b/packages/gamut/src/List/ListRow.tsx
@@ -1,3 +1,5 @@
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
 import { AnimatePresence, motion } from 'framer-motion';
 import { ComponentProps, forwardRef, MouseEvent } from 'react';
 import * as React from 'react';
@@ -7,10 +9,15 @@ import { WithChildrenProp } from '../utils';
 import { RowEl } from './elements';
 import { useListContext } from './ListProvider';
 import { PublicListProps } from './types';
+import { getGridTemplateColumns } from './utils';
 
 export interface RowProps
   extends Partial<PublicListProps<ComponentProps<typeof RowEl>>> {
   header?: boolean;
+  /** This is an internal prop that is largely only used for the DataTable component */
+  numOfColumns?: number;
+  /**  This is an internal prop that is largely only used for the DataTable component */
+  selectable?: boolean;
 }
 
 export interface ExpandableRowProps extends RowProps {
@@ -29,13 +36,24 @@ export interface SimpleRowProps extends RowProps {
 
 export type ListRowProps = ExpandableRowProps | SimpleRowProps;
 
-const ExpandInCollapseOut: React.FC<WithChildrenProp> = ({ children }) => {
+const expandStyles = css({
+  overflow: 'hidden',
+  gridColumn: { _: 'span 2', xs: 'span 12' },
+});
+
+const DivExpand = styled(motion.div)(expandStyles);
+const TDExpand = styled(motion.td)(expandStyles);
+
+const ExpandInCollapseOut: React.FC<
+  WithChildrenProp & { as: 'td' | 'div' }
+> = ({ as, children }) => {
+  const ResponsiveExpand = as === 'td' ? TDExpand : DivExpand;
+
   return (
-    <motion.div
+    <ResponsiveExpand
       initial="collapsed"
       exit="collapsed"
       animate="expanded"
-      style={{ overflow: 'hidden' }}
       variants={{
         expanded: { height: 'auto' },
         collapsed: { height: 0 },
@@ -43,7 +61,7 @@ const ExpandInCollapseOut: React.FC<WithChildrenProp> = ({ children }) => {
       transition={{ duration: 0.2, ease: 'easeInOut' }}
     >
       {children}
-    </motion.div>
+    </ResponsiveExpand>
   );
 };
 
@@ -55,21 +73,30 @@ export const ListRow = forwardRef<HTMLLIElement, ListRowProps>(
       expandedRowAriaLabel,
       renderExpanded,
       keepSpacingWhileExpanded,
+      numOfColumns,
+      selectable,
       ...rest
     },
     ref
   ) => {
-    const { isOl, rowBreakpoint, scrollable, variant, ...rowConfig } =
+    const { listType, rowBreakpoint, scrollable, variant, ...rowConfig } =
       useListContext();
+    const isOl = listType === 'ol';
+    const isTable = listType === 'table';
     const { onClick, role, tabIndex, ...rowProps } = rest;
     const wrapperProps =
-      !renderExpanded && !onClick
+      (!renderExpanded && !onClick) || isTable
         ? { ...rowConfig, ...rowProps }
         : { spacing: keepSpacingWhileExpanded ? rowConfig.spacing : undefined };
     let content = children;
     const renderNumbering = isOl && renderExpanded === undefined && !onClick;
 
-    if (renderExpanded || Boolean(onClick)) {
+    const gridTemplateColumns =
+      isTable && renderExpanded
+        ? getGridTemplateColumns({ numOfColumns, selectable })
+        : 'minmax(0, 1fr) max-content';
+
+    if ((renderExpanded || Boolean(onClick)) && !isTable) {
       content = (
         <RowEl
           as="div"
@@ -97,19 +124,24 @@ export const ListRow = forwardRef<HTMLLIElement, ListRowProps>(
       <RowEl
         aria-live={renderExpanded ? 'polite' : undefined}
         variant={variant}
-        expanded={!!renderExpanded}
+        expanded={isTable ? undefined : !!renderExpanded}
         scrollable={scrollable}
-        rowBreakpoint={rowBreakpoint}
+        rowBreakpoint={isTable && renderExpanded ? 'grid' : rowBreakpoint}
         isOl={renderNumbering}
         role={role}
         tabIndex={tabIndex}
+        gridAutoRows={{ _: undefined, xs: 'minmax(1.5rem, max-content) 6fr' }}
+        gridTemplateColumns={{
+          _: 'minmax(0, 1fr) max-content',
+          xs: gridTemplateColumns,
+        }}
         {...wrapperProps}
       >
         <>
           {content}
           <AnimatePresence>
             {expanded && (
-              <ExpandInCollapseOut>
+              <ExpandInCollapseOut as={isTable ? 'td' : 'div'}>
                 <Box role="region" aria-label={expandedRowAriaLabel}>
                   {renderExpanded?.()}
                 </Box>
diff --git a/packages/gamut/src/List/TableHeader.tsx b/packages/gamut/src/List/TableHeader.tsx
new file mode 100644
index 0000000000..be5bf72ae3
--- /dev/null
+++ b/packages/gamut/src/List/TableHeader.tsx
@@ -0,0 +1,28 @@
+import { ComponentProps, forwardRef } from 'react';
+
+import { Box } from '../Box';
+import { HeaderRowEl } from './elements';
+import { useListContext } from './ListProvider';
+import { PublicListProps } from './types';
+
+export interface TableHeaderProps
+  extends Partial<PublicListProps<ComponentProps<typeof HeaderRowEl>>> {}
+
+export const TableHeader = forwardRef<HTMLTableRowElement, TableHeaderProps>(
+  ({ children, ...rest }, ref) => {
+    const { spacing, scrollable, variant } = useListContext();
+    return (
+      <Box as="thead" display="block" position="sticky" top={0} zIndex={2}>
+        <HeaderRowEl
+          {...rest}
+          spacing={spacing}
+          variant={variant}
+          scrollable={scrollable}
+          ref={ref}
+        >
+          {children}
+        </HeaderRowEl>
+      </Box>
+    );
+  }
+);
diff --git a/packages/gamut/src/List/elements.tsx b/packages/gamut/src/List/elements.tsx
index 1bcb1ec90a..3960893655 100644
--- a/packages/gamut/src/List/elements.tsx
+++ b/packages/gamut/src/List/elements.tsx
@@ -6,9 +6,11 @@ import {
   theme,
   variant,
 } from '@codecademy/gamut-styles';
-import { StyleProps } from '@codecademy/variance';
+import { StyleProps, variance } from '@codecademy/variance';
 import styled from '@emotion/styled';
 
+import { Box } from '../Box';
+
 const olStyles = {
   alignItems: 'center',
   content: 'counters(section, ".") "."',
@@ -131,10 +133,6 @@ const rowVariants = variant({
 
 const rowBreakpointVariants = variant({
   prop: 'rowBreakpoint',
-  base: {
-    gridAutoRows: 'minmax(1.5rem, max-content)',
-    gridTemplateColumns: 'minmax(0, 1fr) max-content',
-  },
   defaultVariant: 'xs',
   variants: {
     xs: {
@@ -149,6 +147,7 @@ const rowBreakpointVariants = variant({
       display: { _: 'grid', md: 'flex' },
       flexDirection: { _: 'column', md: 'row' },
     },
+    grid: { display: 'grid' },
   },
 });
 
@@ -156,13 +155,15 @@ export interface RowProps
   extends StyleProps<typeof rowVariants>,
     StyleProps<typeof rowBreakpointVariants>,
     StyleProps<typeof spacingVariants>,
-    StyleProps<typeof rowStates> {}
+    StyleProps<typeof rowStates>,
+    StyleProps<typeof system.grid> {}
 
 export const RowEl = styled('li', styledOptions<'li'>())<RowProps>(
   css({
     py: { _: 8, xs: 0 },
     bg: 'inherit',
   }),
+  variance.compose(system.grid),
   rowBreakpointVariants,
   rowVariants,
   spacingVariants,
@@ -187,9 +188,9 @@ export interface HeaderProps
     StyleProps<typeof rowStates>,
     StyleProps<typeof listVariants> {}
 
-export const HeaderEl = styled('div', styledOptions)<HeaderProps>(
+export const HeaderRowEl = styled('tr', styledOptions)<HeaderProps>(
   css({
-    display: { _: 'none', xs: 'flex' },
+    display: 'flex',
     position: { _: 'initial', xs: 'sticky' },
     flexDirection: ['column', 'row'],
     top: 0,
@@ -202,16 +203,13 @@ export const HeaderEl = styled('div', styledOptions)<HeaderProps>(
   headerVariants
 );
 
-const headerStyles = { gridColumn: 1 } as const;
 const columnType = variant({
   prop: 'type',
   defaultVariant: 'content',
   variants: {
-    header: {
-      ...headerStyles,
-    },
+    // Keeping this within variants for typing purposes, we use this behaviorally despite it not needing specific styling
+    header: {},
     orderedHeader: {
-      ...headerStyles,
       '&::before': {
         ...olStyles,
         display: { _: 'flex', xs: 'none' },
@@ -228,7 +226,12 @@ const columnType = variant({
         _: 'flex-start',
         xs: 'center',
       },
-      gridColumn: 2,
+      justifyItems: {
+        _: 'end',
+        xs: undefined,
+      },
+
+      gridColumn: { _: 2, xs: 1 },
       gridRow: 1,
     },
     expand: {
@@ -295,7 +298,7 @@ const columnStates = states({
       bg: 'background-current',
       right: -4,
       top: 0,
-      bottom: -2,
+      bottom: -3,
       width: 4,
       position: 'absolute',
     },
@@ -351,7 +354,7 @@ export interface ColProps
     StyleProps<typeof columnType>,
     StyleProps<typeof columnStates>,
     StyleProps<typeof columnJustify>,
-    StyleProps<typeof system['layout']> {}
+    StyleProps<(typeof system)['layout']> {}
 
 export const ColEl = styled(
   'div',
@@ -367,6 +370,7 @@ export const ColEl = styled(
   ])
 )<ColProps>(
   css({
+    fontWeight: 400,
     display: 'inline-flex',
     alignItems: 'center',
     whiteSpace: 'nowrap',
@@ -381,7 +385,7 @@ export const ColEl = styled(
   system.layout
 );
 
-export const StickyColumnWrapper = styled.div(
+export const StickyHeaderColWrapper = styled.th(
   css({
     '&:before': {
       content: '""',
@@ -396,7 +400,7 @@ export const StickyColumnWrapper = styled.div(
     '&:after': {
       content: '""',
       position: 'absolute',
-      bg: 'inherit',
+      bg: 'background-current',
       width: '100%',
       height: '100%',
       top: 0,
@@ -407,6 +411,7 @@ export const StickyColumnWrapper = styled.div(
     left: 0,
     zIndex: 1,
     bg: 'inherit',
+
     '&:not(:first-of-type)': {
       left: { xs: 16 },
       overflow: 'visible',
@@ -422,3 +427,11 @@ export const StickyColumnWrapper = styled.div(
     },
   })
 );
+
+export const ListWrapper = styled(Box)(
+  states({
+    scrollable: {
+      boxShadow: { _: undefined, xs: 'inset -24px 0 24px -24px black' },
+    },
+  })
+);
diff --git a/packages/gamut/src/List/index.tsx b/packages/gamut/src/List/index.tsx
index 24d4d4bfe0..85e0c33c10 100644
--- a/packages/gamut/src/List/index.tsx
+++ b/packages/gamut/src/List/index.tsx
@@ -1,5 +1,5 @@
 export * from './List';
 export * from './ListRow';
 export * from './ListCol';
-export * from './ListHeader';
+export * from './TableHeader';
 export * from './types';
diff --git a/packages/gamut/src/List/types.ts b/packages/gamut/src/List/types.ts
index c3776287f2..90a9ca3856 100644
--- a/packages/gamut/src/List/types.ts
+++ b/packages/gamut/src/List/types.ts
@@ -1,5 +1,7 @@
+import { ListProps } from './List';
+
 export interface PrivateListProps {
-  isOl?: boolean;
+  listType?: ListProps['as'];
   rowBreakpoint?: 'xs' | 'sm' | 'md';
   scrollable?: boolean;
   spacing?: 'normal' | 'condensed' | 'compact';
diff --git a/packages/gamut/src/List/utils.tsx b/packages/gamut/src/List/utils.tsx
new file mode 100644
index 0000000000..a48edc30b4
--- /dev/null
+++ b/packages/gamut/src/List/utils.tsx
@@ -0,0 +1,10 @@
+export const getGridTemplateColumns = ({
+  numOfColumns,
+  selectable,
+}: {
+  numOfColumns?: number;
+  selectable?: boolean;
+}) => {
+  const selectableText = selectable ? 'min-content ' : '';
+  return `${selectableText}repeat(${numOfColumns}, minmax(0, min-content) max-content) min-content`;
+};
diff --git a/packages/styleguide/src/lib/Organisms/Lists & Tables/DataList/DataList.stories.tsx b/packages/styleguide/src/lib/Organisms/Lists & Tables/DataList/DataList.stories.tsx
index f4544f56d3..77d29496ee 100644
--- a/packages/styleguide/src/lib/Organisms/Lists & Tables/DataList/DataList.stories.tsx	
+++ b/packages/styleguide/src/lib/Organisms/Lists & Tables/DataList/DataList.stories.tsx	
@@ -4,7 +4,7 @@
 import { DataList, DataTable, FlexBox } from '@codecademy/gamut';
 import type { Meta, StoryObj } from '@storybook/react';
 
-import { DataListTemplate } from '../examples'
+import { DataListTemplate } from '../examples';
 
 const meta: Meta<typeof DataList> = {
   component: DataList,
@@ -63,7 +63,7 @@ const meta: Meta<typeof DataList> = {
         />
       </FlexBox>
     ),
-  }
+  },
 };
 
 export default meta;
@@ -71,7 +71,7 @@ type Story = StoryObj<typeof DataList>;
 
 export const FullDataList: Story = {
   render: () => <DataListTemplate />,
-}
+};
 
 export const Default: Story = {
   args: {},
@@ -79,12 +79,12 @@ export const Default: Story = {
 
 export const Expanded: Story = {
   args: {
-    expanded: ['Data']
-  }
-}
+    expanded: ['Data'],
+  },
+};
 
 export const Selected: Story = {
   args: {
-    selected: ['Data']
-  }
-}
+    selected: ['Data'],
+  },
+};
diff --git a/packages/styleguide/src/lib/Organisms/Lists & Tables/DataTable/DataTable.stories.tsx b/packages/styleguide/src/lib/Organisms/Lists & Tables/DataTable/DataTable.stories.tsx
index 75958eb773..32d53adfff 100644
--- a/packages/styleguide/src/lib/Organisms/Lists & Tables/DataTable/DataTable.stories.tsx	
+++ b/packages/styleguide/src/lib/Organisms/Lists & Tables/DataTable/DataTable.stories.tsx	
@@ -56,8 +56,6 @@ const meta: Meta<typeof DataTable> = {
       { label: 'Ship', key: 'ship', size: 'lg', sortable: true, fill: true },
     ],
     spacing: 'condensed',
-    onRowExpand: undefined,
-    onRowSelect: undefined,
   },
 };
 
@@ -69,16 +67,23 @@ export const FullDataTable: Story = {
 };
 
 export const EmptyState: Story = {
-  args: { rows: [], shadow: true, scrollable: true }
-}
+  args: {
+    rows: [],
+    shadow: true,
+    scrollable: true,
+    height: '45vh',
+    minHeight: '300px',
+  },
+  render: (args) => <DataTable {...args} />,
+};
 
 export const LoadingRows: Story = {
-  args: { loading: true, shadow: true }
-}
+  args: { loading: true, shadow: true },
+};
 
 export const Scrollable: Story = {
-  args: { shadow: true }
-}
+  args: { shadow: true },
+};
 
 export const Default: Story = {
   args: {},