[IndexTable] Add sort toggle labels and fix z-index icon issue (#7360)

### WHY are these changes introduced?

Fixes Shopify/web#74406
Fixes Shopify/web#74393

This PR fixes a couple of bugs in the IndexTable when the table is
sortable and adds the ability to have Tooltips showing the sort
direction label.

- Fixes a visual bug where if a table is sticky and sortable, the sticky
headings have a different color to the unsticky ones
- Fixes a visual bug where the sort icon would display above the sticky
heading cells
- Adds functionality to display the label of the sort direction in a
Tooltip when hovering over the index table heading.



https://user-images.githubusercontent.com/2562596/194280147-f553b94e-6f91-411c-9914-87bb96c35103.mov



### 🎩 checklist

- [x] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [x] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [x] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [x] Updated the component's `README.md` with documentation changes
- [x] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Author: mrcthms

.changeset/cyan-adults-refuse.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Update `IndexTable` in sortable mode to fix visual bugs and include label Tooltips

polaris-react/src/components/IndexTable/IndexTable.scss

@@ -213,11 +213,12 @@ $loading-panel-height: 53px;
 }
 
 .TableHeadingSortButton {
+  position: static;
   background: none;
   padding: 0;
   border: 0;
   cursor: pointer;
-  display: flex;
+  display: inline-flex;
   align-items: center;
   justify-content: center;
   font-weight: var(--p-font-weight-medium);
@@ -235,13 +236,23 @@ $loading-panel-height: 53px;
 .TableHeadingSortIcon {
   order: 1;
   opacity: 0;
-  transition: var(--p-ease) var(--p-duration-150) opacity;
+  height: var(--p-space-5);
+  width: var(--p-space-5);
+  transition: opacity var(--p-duration-200) var(--p-ease-in)
+    var(--p-duration-100);
 }
 
 .TableHeadingSortIcon-visible {
   opacity: 1;
 }
 
+.TableHeadingSortSvg {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  max-height: 100%;
+}
+
 .ColumnHeaderCheckboxWrapper {
   display: flex;
 }
@@ -390,6 +401,12 @@ $loading-panel-height: 53px;
   }
 }
 
+.Table-sortable {
+  .TableHeading {
+    background-color: var(--p-surface-subdued);
+  }
+}
+
 .StickyTable {
   position: relative;
   top: 0;

polaris-react/src/components/IndexTable/IndexTable.stories.tsx

@@ -1351,38 +1351,65 @@ export function WithSortableHeadings() {
   const [sortIndex, setSortIndex] = useState(0);
   const [sortDirection, setSortDirection] = useState('descending');
 
+  const sortToggleLabels = {
+    0: {ascending: 'A-Z', descending: 'Z-A'},
+    1: {ascending: 'Ascending', descending: 'Descending'},
+    2: {ascending: 'Newest', descending: 'Oldest'},
+    3: {ascending: 'Ascending', descending: 'Ascending'},
+    4: {ascending: 'A-Z', descending: 'Z-A'},
+    5: {ascending: 'A-Z', descending: 'Z-A'},
+    6: {ascending: 'A-Z', descending: 'Z-A'},
+    7: {ascending: 'A-Z', descending: 'Z-A'},
+  };
+
   const initialRows = [
     {
       id: '3411',
       url: 'customers/341',
       name: 'Mae Jemison',
+      date: '2022-02-04',
       location: 'Decatur, USA',
       orders: 20,
       amountSpent: '$2,400',
+      fulfillmentStatus: 'Fulfilled',
+      paymentStatus: 'Paid',
+      notes: '',
     },
     {
       id: '2561',
       url: 'customers/256',
+      date: '2022-01-19',
       name: 'Ellen Ochoa',
       location: 'Los Angeles, USA',
       orders: 30,
       amountSpent: '$140',
+      fulfillmentStatus: 'Fulfilled',
+      paymentStatus: 'Not paid',
+      notes: 'This customer lives on the 3rd floor',
     },
     {
       id: '1245',
       url: 'customers/123',
+      date: '2021-12-12',
       name: 'Anne-Marie Johnson',
       location: 'Portland, USA',
       orders: 10,
       amountSpent: '$250',
+      fulfillmentStatus: 'Fulfilled',
+      paymentStatus: 'Not paid',
+      notes: '',
     },
     {
       id: '8741',
       url: 'customers/543',
+      date: '2022-05-11',
       name: 'Bradley Stevens',
       location: 'Hialeah, USA',
       orders: 5,
       amountSpent: '$26',
+      fulfillmentStatus: 'Unfulfilled',
+      paymentStatus: 'Not paid',
+      notes: 'This customer has requested fragile delivery',
     },
   ];
   const [sortedRows, setSortedRows] = useState(
@@ -1420,7 +1447,20 @@ export function WithSortableHeadings() {
   }
 
   const rowMarkup = rows.map(
-    ({id, name, location, orders, amountSpent}, index) => (
+    (
+      {
+        id,
+        name,
+        date,
+        location,
+        orders,
+        amountSpent,
+        fulfillmentStatus,
+        paymentStatus,
+        notes,
+      },
+      index,
+    ) => (
       <IndexTable.Row
         id={id}
         key={id}
@@ -1430,9 +1470,13 @@ export function WithSortableHeadings() {
         <IndexTable.Cell>
           <TextStyle variation="strong">{name}</TextStyle>
         </IndexTable.Cell>
+        <IndexTable.Cell>{date}</IndexTable.Cell>
         <IndexTable.Cell>{orders}</IndexTable.Cell>
         <IndexTable.Cell>{amountSpent}</IndexTable.Cell>
         <IndexTable.Cell>{location}</IndexTable.Cell>
+        <IndexTable.Cell>{fulfillmentStatus}</IndexTable.Cell>
+        <IndexTable.Cell>{paymentStatus}</IndexTable.Cell>
+        <IndexTable.Cell>{notes}</IndexTable.Cell>
       </IndexTable.Row>
     ),
   );
@@ -1448,14 +1492,20 @@ export function WithSortableHeadings() {
         onSelectionChange={handleSelectionChange}
         headings={[
           {title: 'Name'},
+          {title: 'Date'},
           {title: 'Order count'},
           {title: 'Amount spent'},
           {title: 'Location'},
+          {title: 'Fulfillment status'},
+          {title: 'Payment status'},
+          {title: 'Notes'},
         ]}
-        sortable={[true, false, false, true]}
+        sortable={[true, true, false, true, true, false, false]}
         sortDirection={sortDirection}
         sortColumnIndex={sortIndex}
         onSort={handleClickSortHeading}
+        sortToggleLabels={sortToggleLabels}
+        lastColumnSticky
       >
         {rowMarkup}
       </IndexTable>

polaris-react/src/components/IndexTable/IndexTable.tsx

@@ -15,12 +15,12 @@ import {Checkbox as PolarisCheckbox} from '../Checkbox';
 import {EmptySearchResult} from '../EmptySearchResult';
 // eslint-disable-next-line import/no-deprecated
 import {EventListener} from '../EventListener';
-import {Icon} from '../Icon';
 import {Stack} from '../Stack';
 import {Sticky} from '../Sticky';
 import {Spinner} from '../Spinner';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {Button} from '../Button';
+import {Tooltip} from '../Tooltip';
 import {UnstyledButton} from '../UnstyledButton';
 import {BulkActions, BulkActionsProps} from '../BulkActions';
 import {classNames} from '../../utilities/css';
@@ -60,6 +60,14 @@ export type IndexTableHeading =
 
 export type IndexTableSortDirection = 'ascending' | 'descending';
 
+type IndexTableSortToggleLabel = {
+  [key in IndexTableSortDirection]: string;
+};
+
+interface IndexTableSortToggleLabels {
+  [key: number]: IndexTableSortToggleLabel;
+}
+
 export interface IndexTableBaseProps {
   headings: NonEmptyArray<IndexTableHeading>;
   promotedBulkActions?: BulkActionsProps['promotedActions'];
@@ -85,6 +93,9 @@ export interface IndexTableBaseProps {
   sortColumnIndex?: number;
   /** Callback fired on click or keypress of a sortable column heading. */
   onSort?(headingIndex: number, direction: IndexTableSortDirection): void;
+  /** Optional dictionary of sort toggle labels for each sortable column, with ascending and descending label,
+   * with the key as the index of the column */
+  sortToggleLabels?: IndexTableSortToggleLabels;
 }
 
 export interface TableHeadingRect {
@@ -109,6 +120,7 @@ function IndexTableBase({
   defaultSortDirection = 'descending',
   sortColumnIndex,
   onSort,
+  sortToggleLabels,
   ...restProps
 }: IndexTableBaseProps) {
   const {
@@ -655,13 +667,16 @@ function IndexTableBase({
       </AfterInitialMount>
     ) : null;
 
+  const isSortable = sortable?.some((value) => value);
+
   const tableClassNames = classNames(
     styles.Table,
     hasMoreLeftColumns && styles['Table-scrolling'],
     selectMode && styles.disableTextSelection,
     selectMode && shouldShowBulkActions && styles.selectMode,
     !selectable && styles['Table-unselectable'],
     canFitStickyColumn && styles['Table-sticky'],
+    isSortable && styles['Table-sortable'],
     canFitStickyColumn && lastColumnSticky && styles['Table-sticky-last'],
     canFitStickyColumn &&
       lastColumnSticky &&
@@ -830,35 +845,34 @@ function IndexTableBase({
       const isCurrentlySorted = index === sortColumnIndex;
       const isAscending = sortDirection === 'ascending';
       let newDirection: IndexTableSortDirection = defaultSortDirection;
-      let source =
+      let SourceComponent =
         defaultSortDirection === 'ascending'
           ? SortAscendingMajor
           : SortDescendingMajor;
       if (isCurrentlySorted) {
         newDirection = isAscending ? 'descending' : 'ascending';
-        source =
+        SourceComponent =
           sortDirection === 'ascending'
             ? SortAscendingMajor
             : SortDescendingMajor;
       }
 
-      const sortAccessibilityLabel = i18n.translate(
-        'Polaris.IndexTable.sortAccessibilityLabel',
-        {direction: newDirection},
-      );
-
       const iconMarkup = (
         <span
           className={classNames(
             styles.TableHeadingSortIcon,
             isCurrentlySorted && styles['TableHeadingSortIcon-visible'],
           )}
         >
-          <Icon source={source} accessibilityLabel={sortAccessibilityLabel} />
+          <SourceComponent
+            focusable="false"
+            aria-hidden="true"
+            className={styles.TableHeadingSortSvg}
+          />
         </span>
       );
 
-      return (
+      const sortMarkup = (
         <UnstyledButton
           onClick={() => handleSortHeadingClick(index, newDirection)}
           className={styles.TableHeadingSortButton}
@@ -868,6 +882,18 @@ function IndexTableBase({
           {headingContent}
         </UnstyledButton>
       );
+
+      if (!sortToggleLabels) {
+        return sortMarkup;
+      }
+
+      const tooltipDirection = isCurrentlySorted
+        ? sortDirection!
+        : defaultSortDirection;
+
+      const tooltipContent = sortToggleLabels[index][tooltipDirection];
+
+      return <Tooltip content={tooltipContent}>{sortMarkup}</Tooltip>;
     }
     return headingContent;
   }