@spaced-out/ui-design-system 0.4.13-beta.1 → 0.4.14

package/lib/components/Table/StaticTable.js.flow

@@ -0,0 +1,576 @@
+// @flow strict
+
+import * as React from 'react';
+// $FlowFixMe[untyped-import]
+import {useVirtualizer} from '@tanstack/react-virtual';
+import get from 'lodash/get';
+import xor from 'lodash/xor';
+
+import {useWindowSize} from '../../hooks/useWindowSize';
+import {size48, sizeFluid} from '../../styles/variables/_size';
+import {spaceNone} from '../../styles/variables/_space';
+import {classify} from '../../utils/classify';
+import type {ClassNameComponent} from '../../utils/makeClassNameComponent';
+import {makeClassNameComponent} from '../../utils/makeClassNameComponent';
+import {CircularLoader} from '../CircularLoader';
+
+import type {TableRow} from './DefaultRow';
+import {DefaultRow, EmptyRow} from './DefaultRow';
+import type {GenericHeaderItems} from './DefaultTableHeader';
+import {DefaultTableHeader} from './DefaultTableHeader';
+import type {SortDirection} from './hooks';
+import type {ClassNames, GenericObject, TableProps} from './Table';
+
+import css from './Table.module.css';
+
+
+export const BasicTable: ClassNameComponent<'table'> = makeClassNameComponent(
+  css.defaultTable,
+  'table',
+);
+
+export const BasicTableBody: ClassNameComponent<'tbody'> =
+  makeClassNameComponent(css.defaultTableBody, 'tbody');
+
+function useTableWidth(ref): number | void {
+  const {width} = useWindowSize();
+  const [tableWidth, setTableWidth] = React.useState();
+
+  React.useEffect(() => {
+    if (ref.current) {
+      setTableWidth(ref.current.offsetWidth);
+    }
+  }, [width]);
+
+  return tableWidth;
+}
+
+function useMappedKeys<Data: GenericObject>(
+  entries: Data[],
+  rowKeys: ?(string[]),
+  idName: string,
+): string[] {
+  return React.useMemo(
+    () => rowKeys ?? entries.map((e) => get(e, idName)),
+    [entries, idName, rowKeys],
+  );
+}
+
+function useHeaderCheckboxHandler<Data: GenericObject>(
+  selectedKeys: ?(string[]),
+  entries: Data[],
+  idName: string,
+  onSelect?: (string[]) => mixed,
+) {
+  if (!selectedKeys) {
+    return undefined;
+  }
+
+  return ({checked}: {value: string, checked: boolean}) => {
+    const allIds = entries.map((row) => get(row, idName));
+    const newSelection = checked ? allIds : [];
+    onSelect?.(newSelection);
+  };
+}
+
+type TableWrapperProps<T, U> = {
+  tableRef?: {|current: null | HTMLDivElement|},
+  classNames?: ClassNames,
+  className?: string,
+  borderRadius?: string,
+  tableHeaderClassName?: string,
+  children?: React.Node,
+  wrapperStyle?: {[string]: ?string | number},
+  isLoading?: boolean,
+  emptyText?: React.Node,
+  showHeader?: boolean,
+  stickyHeader?: boolean,
+  sortable?: boolean,
+  disabled?: boolean,
+  entriesLength?: number,
+  selectedKeys?: ?(string[]),
+  headers: GenericHeaderItems<T, U>,
+  sortKey?: string,
+  sortDirection?: SortDirection,
+  handleSortClick?: (sortKey: $Keys<T>) => mixed,
+  handleHeaderCheckboxClick?: ({value: string, checked: boolean}) => mixed,
+};
+
+type RowType<T, U> = {
+  TableRow?: TableRow<T, U>,
+  data: T,
+  headers: GenericHeaderItems<T, U>,
+  extras?: U,
+  sortedKeys?: string[],
+  selected?: boolean,
+  disabled?: boolean,
+  keyId: string,
+  classNames?: ClassNames,
+  onSelect?: ({value: string, checked: boolean}) => mixed,
+};
+
+function RowRenderer<Data: GenericObject, Extras: GenericObject>({
+  TableRow,
+  data,
+  headers,
+  extras,
+  sortedKeys,
+  selected,
+  disabled,
+  classNames,
+  keyId,
+  onSelect,
+}: RowType<Data, Extras>): React.Node {
+  return TableRow ? (
+    <TableRow
+      key={keyId}
+      data={data}
+      headers={headers}
+      // extras and rowKeys are both 'optional'
+      extras={extras}
+      sortedKeys={sortedKeys}
+      selected={selected}
+      disabled={disabled}
+    />
+  ) : (
+    <DefaultRow
+      key={keyId}
+      data={data}
+      extras={extras}
+      headers={headers}
+      selected={selected}
+      onSelect={onSelect}
+      disabled={disabled}
+      classNames={{
+        tableRow: classNames?.tableRow,
+        checkbox: classNames?.checkbox,
+      }}
+    />
+  );
+}
+
+function TableWrapper<Data: GenericObject, Extras: GenericObject>({
+  tableRef,
+  classNames,
+  className,
+  tableHeaderClassName,
+  children,
+  wrapperStyle,
+  isLoading = false,
+  emptyText,
+  showHeader = true,
+  stickyHeader = false,
+  sortable,
+  disabled = false,
+  entriesLength = 0,
+  selectedKeys,
+  headers,
+  sortKey,
+  sortDirection,
+  handleSortClick,
+  handleHeaderCheckboxClick,
+}: TableWrapperProps<Data, Extras>): React.Node {
+  return (
+    <div
+      className={classify(css.tableContainer, classNames?.wrapper)}
+      data-id={'table-wrap'}
+      ref={tableRef}
+      style={wrapperStyle}
+    >
+      <BasicTable
+        data-id="basic-table"
+        className={classify(
+          className,
+          {
+            [css.fullHeightTable]: isLoading || (!entriesLength && !!emptyText),
+          },
+          classNames?.table,
+        )}
+      >
+        {showHeader && (
+          <DefaultTableHeader
+            className={classify(tableHeaderClassName, classNames?.tableHeader)}
+            sortable={sortable}
+            columns={headers}
+            handleSortClick={handleSortClick}
+            sortKey={sortKey}
+            sortDirection={sortDirection}
+            disabled={disabled}
+            handleCheckboxClick={handleHeaderCheckboxClick}
+            stickyHeader={stickyHeader}
+            checked={
+              selectedKeys == null || selectedKeys.length === 0
+                ? 'false'
+                : selectedKeys.length < entriesLength
+                  ? 'mixed'
+                  : 'true'
+            }
+          />
+        )}
+        <BasicTableBody className={classNames?.tableBody}>
+          {children}
+        </BasicTableBody>
+      </BasicTable>
+    </div>
+  );
+}
+
+/**
+ * A Static Default Table.
+ *
+ * Our
+ */
+
+export function StaticTable<Data: GenericObject, Extras: GenericObject>(props: {
+  ...TableProps<Data, Extras>,
+  handleSortClick?: (sortKey: string) => mixed,
+  sortKey?: string,
+  sortDirection?: SortDirection,
+  rowKeys?: string[],
+}): React.Node {
+  const {
+    classNames,
+    className,
+    TableRow,
+    entries,
+    extras,
+    rowKeys,
+    headers,
+    showHeader = true,
+    tableHeaderClassName,
+    sortable,
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    defaultSortKey,
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    defaultSortDirection = 'original',
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    onSort,
+    handleSortClick,
+    sortKey,
+    sortDirection,
+    selectedKeys,
+    disabledKeys = [],
+    onSelect,
+    isLoading,
+    idName = 'id',
+    emptyText,
+    disabled,
+    customLoader,
+    borderRadius,
+    stickyHeader,
+  } = props;
+
+  // this is a fallback and honestly probably doesn't need the
+  // memo'ing
+  const tableRef = React.useRef(null);
+  const mappedKeys = useMappedKeys(entries, rowKeys, idName);
+  const tableWidth = useTableWidth(tableRef);
+
+  /**
+   * this function is also used to decide weather to show checkbox in header or not. so it's value is undefined in case selectedKeys is not there.
+   */
+  const handleHeaderCheckboxClick = useHeaderCheckboxHandler(
+    selectedKeys,
+    entries,
+    idName,
+    onSelect,
+  );
+
+  return (
+    <TableWrapper
+      tableRef={tableRef}
+      wrapperStyle={{
+        '--border-radius': borderRadius,
+        '--table-width': tableWidth ? `${tableWidth}px` : sizeFluid,
+      }}
+      classNames={classNames}
+      className={className}
+      tableHeaderClassName={tableHeaderClassName}
+      borderRadius={borderRadius}
+      isLoading={isLoading}
+      emptyText={emptyText}
+      showHeader={showHeader}
+      stickyHeader={stickyHeader}
+      sortable={sortable}
+      disabled={false}
+      entriesLength={entries.length}
+      selectedKeys={selectedKeys}
+      headers={headers}
+      sortKey={sortKey}
+      sortDirection={sortDirection}
+      handleSortClick={handleSortClick}
+      handleHeaderCheckboxClick={handleHeaderCheckboxClick}
+    >
+      {isLoading || !entries.length ? (
+        <EmptyRow
+          isLoading={isLoading}
+          emptyText={emptyText}
+          headersLength={
+            handleHeaderCheckboxClick ? headers.length + 1 : headers.length
+          }
+          customLoader={customLoader}
+        />
+      ) : (
+        mappedKeys.map((key) => {
+          const data = entries.find((e) => get(e, idName) === key);
+          if (data == null) {
+            return null;
+          }
+          const selected =
+            selectedKeys && Array.isArray(selectedKeys)
+              ? selectedKeys.includes(get(data, idName))
+              : undefined;
+          const isRowDisabled =
+            disabledKeys && Array.isArray(disabledKeys)
+              ? disabledKeys.includes(get(data, idName))
+              : false;
+          return (
+            <RowRenderer
+              TableRow={TableRow}
+              keyId={key}
+              data={data}
+              headers={headers}
+              extras={extras}
+              sortedKeys={rowKeys ?? mappedKeys}
+              selected={selected}
+              disabled={disabled || isRowDisabled}
+              classNames={classNames}
+              onSelect={
+                selectedKeys != null
+                  ? (_v) => onSelect?.(xor(selectedKeys ?? [], [key]))
+                  : undefined
+              }
+            />
+          );
+        })
+      )}
+    </TableWrapper>
+  );
+}
+
+export function StaticTableVirtualized<
+  Data: GenericObject,
+  Extras: GenericObject,
+>(props: {
+  ...TableProps<Data, Extras>,
+  handleSortClick?: (sortKey: string) => mixed,
+  sortKey?: string,
+  sortDirection?: SortDirection,
+  rowKeys?: string[],
+}): React.Node {
+  const {
+    classNames,
+    className,
+    TableRow,
+    entries,
+    extras,
+    rowKeys,
+    headers,
+    showHeader = true,
+    tableHeaderClassName,
+    sortable,
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    defaultSortKey,
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    defaultSortDirection = 'original',
+    // eslint-disable-next-line unused-imports/no-unused-vars
+    onSort,
+    handleSortClick,
+    sortKey,
+    sortDirection,
+    selectedKeys,
+    disabledKeys = [],
+    onSelect,
+    isLoading,
+    idName = 'id',
+    emptyText,
+    disabled,
+    customLoader,
+    borderRadius,
+    stickyHeader,
+    virtualizationOptions,
+  } = props;
+
+  const {
+    rowsCount,
+    rowHeight = size48,
+    onEndReached,
+    isEndLoading = false,
+    isAllDataFetched = false,
+  } = virtualizationOptions ?? {};
+
+  const tableRef = React.useRef(null);
+
+  // this is a fallback and honestly probably doesn't need the
+  // memo'ing
+  const mappedKeys = useMappedKeys(entries, rowKeys, idName);
+  const tableWidth = useTableWidth(tableRef);
+
+  const virtualizer = useVirtualizer({
+    count: entries.length,
+    getScrollElement: () => tableRef.current,
+    estimateSize: () => parseInt(rowHeight),
+    getItemKey: (index) => entries[index][idName],
+    overscan: 1,
+  });
+
+  const currRows = virtualizer.getVirtualItems();
+
+  const hasTriggeredRef = React.useRef(false);
+
+  React.useEffect(() => {
+    if (!tableRef.current || !onEndReached || isAllDataFetched) {
+      return;
+    }
+
+    const scrollElement = tableRef.current;
+
+    const handleScroll = () => {
+      const {scrollTop, scrollHeight, clientHeight} = scrollElement;
+
+      const isAtEnd = scrollTop + clientHeight >= scrollHeight - 100; // buffer
+
+      if (isAtEnd) {
+        if (!hasTriggeredRef.current) {
+          hasTriggeredRef.current = true;
+          onEndReached();
+        }
+      } else {
+        hasTriggeredRef.current = false; // reset when scrolling up
+      }
+    };
+
+    scrollElement.addEventListener('scroll', handleScroll);
+
+    return () => {
+      scrollElement.removeEventListener('scroll', handleScroll);
+    };
+  }, [onEndReached, isAllDataFetched]);
+
+  /**
+   * this function is also used to decide weather to show checkbox in header or not. so it's value is undefined in case selectedKeys is not there.
+   */
+
+  const handleHeaderCheckboxClick = useHeaderCheckboxHandler(
+    selectedKeys,
+    entries,
+    idName,
+    onSelect,
+  );
+
+  const VirtualizedStartRow = () => (
+    <tr
+      style={{
+        height: virtualizer.getVirtualItems()[0]?.start ?? spaceNone,
+        width: sizeFluid,
+      }}
+    >
+      <td
+        colSpan={headers.length + (handleHeaderCheckboxClick ? 1 : 0)}
+        style={{padding: spaceNone, border: 'none', height: '100%'}}
+      />
+    </tr>
+  );
+
+  const VirtualizedEndRow = () => (
+    <tr
+      style={{
+        height:
+          virtualizer.getTotalSize() -
+          (virtualizer.getVirtualItems().at(-1)?.end ?? spaceNone),
+      }}
+      aria-hidden={true}
+    >
+      <td
+        colSpan={headers.length + (handleHeaderCheckboxClick ? 1 : 0)}
+        style={{padding: spaceNone, border: 'none', height: '100%'}}
+      />
+    </tr>
+  );
+
+  return (
+    <TableWrapper
+      tableRef={tableRef}
+      wrapperStyle={{
+        '--border-radius': borderRadius,
+        '--table-width': tableWidth ? `${tableWidth}px` : sizeFluid,
+        height: (rowsCount + 1) * parseInt(rowHeight),
+        overflowY: 'auto',
+      }}
+      classNames={classNames}
+      className={className}
+      tableHeaderClassName={tableHeaderClassName}
+      borderRadius={borderRadius}
+      isLoading={isLoading}
+      emptyText={emptyText}
+      showHeader={showHeader}
+      stickyHeader={stickyHeader}
+      sortable={sortable}
+      disabled={false}
+      entriesLength={entries.length}
+      selectedKeys={selectedKeys}
+      headers={headers}
+      sortKey={sortKey}
+      sortDirection={sortDirection}
+      handleSortClick={handleSortClick}
+      handleHeaderCheckboxClick={handleHeaderCheckboxClick}
+    >
+      <VirtualizedStartRow />
+      {isLoading || !entries.length ? (
+        <EmptyRow
+          isLoading={isLoading}
+          emptyText={emptyText}
+          headersLength={
+            handleHeaderCheckboxClick ? headers.length + 1 : headers.length
+          }
+          customLoader={customLoader}
+        />
+      ) : (
+        currRows.map((virtualRow) => {
+          const key = virtualRow.key;
+          const data = entries[virtualRow.index];
+          if (data == null) {
+            return null;
+          }
+          const selected =
+            selectedKeys && Array.isArray(selectedKeys)
+              ? selectedKeys.includes(get(data, idName))
+              : undefined;
+          const isRowDisabled =
+            disabledKeys && Array.isArray(disabledKeys)
+              ? disabledKeys.includes(get(data, idName))
+              : false;
+
+          return (
+            <RowRenderer
+              TableRow={TableRow}
+              keyId={key}
+              data={data}
+              headers={headers}
+              extras={extras}
+              sortedKeys={rowKeys ?? mappedKeys}
+              selected={selected}
+              disabled={disabled || isRowDisabled}
+              classNames={classNames}
+              onSelect={
+                selectedKeys != null
+                  ? (_v) => onSelect?.(xor(selectedKeys ?? [], [key]))
+                  : undefined
+              }
+            />
+          );
+        })
+      )}
+      <VirtualizedEndRow />
+      {isEndLoading && (
+        <tr>
+          <td colSpan={headers.length + (handleHeaderCheckboxClick ? 1 : 0)}>
+            <div className={css.fetchMoreLoaderContainer}>
+              <CircularLoader />
+            </div>
+          </td>
+        </tr>
+      )}
+    </TableWrapper>
+  );
+}

package/lib/components/Table/Table.docs.js

@@ -16,7 +16,7 @@ const TABLE_DOCS = exports.TABLE_DOCS = {
       },
       table: {
         type: {
-          summary: '{label: React.ReactNode, key: $Keys<T>, className?: string, filterIcon?: React.ReactNode, filtered?: boolean, subtext?: string, sortable?: boolean, headerIconClassName?: string, sticky?: boolean, render?: React.ComponentType<{data: T, extras?: U, className?: string, selected?: boolean,}>, }'
+          summary: '{label: React.Node, key: $Keys<T>, className?: string, filterIcon?: React.Node, filtered?: boolean, subtext?: string, sortable?: boolean, headerIconClassName?: string, sticky?: boolean, render?: React.ComponentType<{data: T, extras?: U, className?: string, selected?: boolean,}>, }'
         }
       }
     },
@@ -221,6 +221,77 @@ const TABLE_DOCS = exports.TABLE_DOCS = {
           summary: true
         }
       }
+    },
+    rowsCount: {
+      name: 'virtualizationOptions.rowsCount',
+      description: 'Total number of virtual rows.',
+      control: {
+        type: 'number'
+      },
+      table: {
+        type: {
+          summary: 'number'
+        },
+        defaultValue: {
+          summary: 20
+        }
+      }
+    },
+    rowHeight: {
+      name: 'virtualizationOptions.rowHeight',
+      description: 'Row height in CSS units (e.g., "48px"). Should be provided correctly, otherwise it will not work as expected.',
+      control: {
+        type: 'text'
+      },
+      table: {
+        type: {
+          summary: 'string'
+        },
+        defaultValue: {
+          summary: '48px'
+        }
+      }
+    },
+    isEndLoading: {
+      name: 'virtualizationOptions.isEndLoading',
+      description: 'Whether to show loading spinner at the bottom.',
+      control: {
+        type: 'boolean'
+      },
+      table: {
+        type: {
+          summary: 'boolean'
+        },
+        defaultValue: {
+          summary: false
+        }
+      }
+    },
+    isAllDataFetched: {
+      name: 'virtualizationOptions.isAllDataFetched',
+      description: 'Whether all rows are fetched (disables infinite loading).',
+      control: {
+        type: 'boolean'
+      },
+      table: {
+        type: {
+          summary: 'boolean'
+        },
+        defaultValue: {
+          summary: false
+        }
+      }
+    },
+    // Note: onEndReached can't be controlled, but you can mock it
+    onEndReached: {
+      name: 'virtualizationOptions.onEndReached',
+      description: 'Callback triggered when end of list is reached.',
+      action: 'onEndReached',
+      table: {
+        type: {
+          summary: '() => void'
+        }
+      }
     }
   },
   parameters: {
@@ -285,6 +356,15 @@ just CSS Wrappers for Button and SimpleButtonDropdown components
 * Use ButtonCta component to add a button CTA in the \`TableActionBar\`
 * Use DropdownCta component to add a dropdown CTA button in the \`TableActionBar\` for screen width less than size1280(1280px)
 
+### Handling Sticky Headers with Virtualization
+* When using **virtualization**, always assign a fixed \`min-width\` and \`max-width\` to sticky table headers with **same value**. 
+This ensures a strict, fixed width for header cells. Directly using \`width\` (non strict for table headers) alone is not sufficient, as 
+it can be overridden by content width due to table layout behavior, causing headers to shift.
+* If the cell content may exceed the defined width, or if you're unsure of its maximum width, also use \`white-space: normal;\` and \`word-break: break-word;\` 
+to ensure the content wraps within the cell instead of overflowing or causing layout shifts.
+
+This helps maintain consistent column alignment and improves readability across varying data lengths.
+
 \`\`\`jsx
 <Table
   headers={TABLE_HEADERS}
@@ -329,7 +409,7 @@ const TABLE_DATA = [
   },
 ];
 
-export const _TableExample = (): React.ReactNode => {
+export const _TableExample = (): React.Node => {
   return (
     <div className={css.container}>
       {/* Top Bar with Filters */}
@@ -530,7 +610,7 @@ export const _TableExample = (): React.ReactNode => {
       }
     },
     storySource: {
-      componentPath: '/src/components/Table/Table.jsx'
+      componentPath: '/src/components/Table/Table.js'
     }
   }
 };