@purpurds/table 0.0.1

package/src/types.ts

@@ -0,0 +1,496 @@
+import { HeadingTagType } from "@purpurds/heading";
+import type { SelectProps } from "@purpurds/select";
+import type { Cell, FilterFn, Row, RowData, SortingFn } from "@tanstack/react-table";
+
+import { TableActionBarCopyProps } from "./table-action-bar";
+import type { FilterVariants, SortingAriaLabels } from "./table-column-header-cell";
+import { TableExportDrawerCopyProps } from "./table-export-drawer";
+import { TableSettingsDrawerCopyProps } from "./table-settings-drawer";
+
+export type CellType =
+  | "badge"
+  | "bodyText"
+  | "button"
+  | "buttonGroup"
+  | "ctaLink"
+  | "date"
+  | "empty"
+  | "errorAlertMessage"
+  | "iconText"
+  | "leadText"
+  | "link"
+  | "number"
+  | "rowSelection"
+  | "rowToggle"
+  | "toggle"
+  | "warningAlertMessage";
+
+declare module "@tanstack/react-table" {
+  // Allows us to define custom properties for our columns
+  // All declarations of ColumnMeta must have identical type parameters.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    /**
+     * Represents the variant of the filter applied to a column.
+     * - "string": A text-based filter.
+     * - "select": A dropdown-based filter.
+     */
+    filterVariant?: FilterVariants;
+
+    /**
+     * Placeholder text for the filter input.
+     */
+    filterPlaceholder?: string;
+
+    /**
+     * ARIA label for the filter input, used for accessibility.
+     */
+    filterAriaLabel?: string;
+
+    /**
+     * A key used to filter the column data when the data is an object.
+     * This is useful for custom filtering logic on a specific key within the object.
+     * Required when using the `filterOnFilterKey` filterFn.
+     */
+    filterKey?: string;
+
+    /**
+     * Represents the type of cell in a table row.
+     * This determines the behavior and rendering of the cell.
+     * - "badge": Displays status, category, or label with visual emphasis, allowing users to differentiate data at a glance without cluttering the table.
+     * - "bodyText": Displays all types of textual information.
+     * - "button": A single button for performing row-specific actions directly within a table cell, such as edit, delete, or download. Button can be any variant.
+     * - "buttonGroup": Similar to the standalone button, but used when multiple actions are needed for a row, grouped together for better organization. Typically placed in the last column. Buttons can be any variants.
+     * - "ctaLink": Allowing users to navigate to external or internal resources.
+     * - "date": Displays date and time in a consistent format, with the option to toggle the time visibility on or off. Visibility is controlled through the 'showTime' attribute in the meta. Please provide the date in ISO format.
+     * - "empty": Used when a cell has no data or when the data is not applicable.
+     * - "errorAlertMessage": Displays validation or data-related errors, typically with a brief description to help users identify the issue.
+     * - "iconText": A visual symbol that represents contextual information, enhancing readability by conveying meaning at a glance without the need for text. The ext is optional but recommended to use for further clarity.
+     * - "leadText": Highlights key information, like a primary identifier, to ensure it stands out in the table. Typically used in the first column.
+     * - "link": Enables users to navigate to external or internal resources. It has lower importance and is less intrusive than a CTA link.
+     * - "number": Numeric data that isn't related to size should be left-aligned, such as phone numbers or order numbers. Numeric data related to size should be right-aligned for easier scanning, helping users quickly differentiate between values such as prices. Alignment is controlled through the 'numberCellAlignment' attribute in the meta.
+     * - "rowSelection":
+     * - "toggle": Lets users enable or disable a setting or option directly within a table cell.
+     * - "warningAlertMessage": Highlights a potential issue with the data, often accompanied by a brief description to guide users on the necessary action.
+     *
+     * If you want a custom cell type then leave this undefined and create a custom cell component using the cell attribute in the columnDef.
+     */
+    cellType?: CellType;
+
+    /**
+     * Alignment for number cells. Defaults to "left" if not specified.
+     */
+    numberCellAlignment?: "left" | "right";
+
+    /**
+     * Properties for the select dropdown used in the filter.
+     * Required when filterVariant is "select".
+     */
+    selectProps?: SelectProps;
+
+    /**
+     * Callback function triggered when a button cell is clicked.
+     * Only applicable when cellType is "button".
+     */
+    onClick?: (cell: Cell<TData, unknown> & { buttonId?: string }) => void;
+
+    /**
+     * Determines whether to show the time in a date cell.
+     * Enabled by default when cellType is "date".
+     */
+    showTime?: boolean;
+
+    /**
+     * Aria labels for row selection checkboxes.
+     * Used for accessibility purposes.
+     */
+    rowSelectionAriaLabels?: {
+      header: string;
+      row: string;
+    };
+  }
+
+  interface FilterFns {
+    /**
+     * A custom filter function that filters data based on a specified key.
+     * Useful for advanced filtering scenarios.
+     * Requires the `filterKey` property in the column's meta.
+     */
+    filterOnFilterKey: FilterFn<unknown>;
+  }
+
+  interface SortingFns {
+    /**
+     * A custom sorting function that sorts badge column based on the badge variant.
+     */
+    sortOnBadgeVariant: SortingFn<unknown>;
+
+    /**
+     * A custom sorting function that sorts badge column based on the badge value.
+     */
+    sortOnBadgeValue: SortingFn<unknown>;
+  }
+}
+
+/**
+ * Props for enabling and configuring the action bar in a data table component.
+ */
+export type WithActionBarProps = {
+  /**
+   * Configuration for the action bar copy, such as labels and messages.
+   */
+  actionbarCopy: TableActionBarCopyProps;
+
+  /**
+   * Flag to enable the action bar functionality.
+   */
+  enableActionBar: true;
+
+  /**
+   * The total number of rows in the data table, displayed in the action bar.
+   */
+  actionBarTotalRowCount: number;
+
+  /**
+   * Callback function triggered when the primary button in the action bar is clicked.
+   */
+  onPrimaryButtonClick: () => void;
+
+  /**
+   * Optional callback function triggered when the secondary button in the action bar is clicked.
+   */
+  onSecondaryButtonClick?: () => void;
+};
+
+export type WithoutActionBarProps = {
+  actionbarCopy?: never;
+  enableActionBar?: false | undefined;
+  actionBarTotalRowCount?: never;
+  onPrimaryButtonClick?: never;
+  onSecondaryButtonClick?: never;
+};
+
+/**
+ * Props for displaying an empty table state in a data table component.
+ */
+export type WithEmptyTableProps = {
+  /**
+   * Copy for the empty table state, such as title and description.
+   */
+  emptyTableCopy: {
+    title: string;
+    description: string;
+  };
+
+  /**
+   * The heading tag to use for the empty table title.
+   */
+  emptyTableHeadingTag: HeadingTagType;
+
+  /**
+   * Icon to display in the empty table state.
+   */
+  emptyTableIcon: React.ReactNode;
+};
+
+export type WithoutEmptyTableProps = {
+  emptyTableCopy?: never;
+  emptyTableHeadingTag?: never;
+  emptyTableIcon?: never;
+};
+
+/**
+ * Props for enabling a loading state in a data table component.
+ */
+export type WithLoadingProps = {
+  /**
+   * Flag to enable the loading state.
+   */
+  loading: boolean;
+
+  /**
+   * The number of skeleton rows to display while loading.
+   */
+  skeletonRows: number;
+};
+
+export type WithoutLoadingProps = {
+  loading?: never;
+  skeletonRows?: never;
+};
+
+/**
+ * Props for enabling row selection functionality in a data table component.
+ */
+export type WithRowSelectionProps<TData> = {
+  /**
+   * Flag to enable row selection functionality.
+   */
+  enableRowSelection: true | ((row: Row<TData>) => boolean);
+
+  /**
+   * ARIA labels for row selection checkboxes, used for accessibility.
+   */
+  rowSelectionAriaLabels: {
+    header: string;
+    row: string;
+  };
+
+  /**
+   * showOnlySelectedRows - Flag to filter the table to show only selected rows.
+   */
+  showOnlySelectedRows: boolean;
+
+  /**
+   * setShowOnlySelectedRows - Function to update the showOnlySelectedRows state.
+   */
+  setShowOnlySelectedRows: React.Dispatch<React.SetStateAction<boolean>>;
+};
+
+export type WithoutRowSelectionProps = {
+  enableRowSelection?: false | undefined;
+  rowSelectionAriaLabels?: never;
+  showOnlySelectedRows?: never;
+  setShowOnlySelectedRows?: never;
+};
+
+/**
+ * Props for enabling sorting functionality in a data table component.
+ */
+export type WithSortingProps = {
+  /**
+   * Flag to enable sorting functionality.
+   */
+  enableSorting: true;
+
+  /**
+   * ARIA labels for sorting controls, used for accessibility.
+   */
+  sortingAriaLabels: SortingAriaLabels;
+};
+
+export type WithoutSortingProps = {
+  enableSorting?: false | undefined;
+  sortingAriaLabels?: never;
+};
+
+/**
+ * Represents the properties for a data table component with a toolbar.
+ * This type is used when the toolbar is enabled and provides additional
+ * functionality such as exporting data, toggling table expansion, and displaying
+ * settings.
+ */
+export type WithToolbarProps = {
+  /**
+   * Indicates whether the toolbar is enabled.
+   */
+  enableToolbar: true;
+
+  // /**
+  //  * Optional properties for customizing the toolbar copy.
+  //  */
+  toolbarCopy?: {
+    rowCount?: {
+      showing: string;
+      of: string;
+      rows: string;
+    };
+  };
+
+  /**
+   * The total number of rows to display in the toolbar.
+   * This is used when handling data on the server side.
+   */
+  toolbarTotalRowCount?: number;
+} & (WithFiltersProps | WithoutFiltersProps) &
+  (WithSettingsDrawerProps | WithoutSettingsDrawerProps) &
+  ((WithExportDrawerProps | WithSingleExportFormatProps) | WithoutExportProps) &
+  (WithExpandButtonProps | WithoutExpandButtonProps);
+
+export type WithoutToolbarProps = {
+  /**
+   * Indicates whether the toolbar is enabled.
+   */
+  enableToolbar?: false | undefined;
+  exportFormats?: never;
+  onExportData?: never;
+  onToggleExpand?: never;
+  settingsDrawerCopy?: never;
+  toolbarCopy?: never;
+  toolbarTotalRowCount?: never;
+  exportDrawerCopy?: never;
+};
+
+type WithFiltersProps = {
+  enableFilters: true;
+  /**
+   * Optional properties for customizing the filter copy.
+   */
+  toolbarCopy: {
+    buttons: {
+      clearFilters: string;
+    };
+    ariaLabels: {
+      clearFilters: string;
+    };
+  };
+};
+
+/**
+ * Props for enabling an expand button in a data table component.
+ */
+type WithExpandButtonProps = {
+  /**
+   * Callback function triggered when toggling the expansion state of rows.
+   */
+  onToggleExpand: () => void;
+
+  /**
+   * Copy for the toolbar buttons related to expanding rows.
+   */
+  toolbarCopy: {
+    buttons: {
+      expand: string;
+    };
+    ariaLabels: {
+      expand: string;
+    };
+  };
+};
+
+/**
+ * Props for enabling an export drawer in a data table component.
+ */
+type WithExportDrawerProps = {
+  /**
+   * The formats in which the data can be exported.
+   */
+  exportFormats: string[];
+
+  /**
+   * Copy for the export drawer, such as labels and messages.
+   */
+  exportDrawerCopy: TableExportDrawerCopyProps;
+
+  /**
+   * Callback function triggered when exporting data.
+   * @param format - The format in which the data should be exported.
+   */
+  onExportData: (format: string) => void;
+
+  /**
+   * Copy for the toolbar buttons and ARIA labels related to exporting.
+   */
+  toolbarCopy: {
+    buttons: {
+      export: string;
+    };
+    ariaLabels: {
+      export: string;
+    };
+  };
+};
+
+type WithoutExportProps = {
+  exportFormats?: never;
+  exportDrawerCopy?: never;
+  onExportData?: never;
+  toolbarCopy?: {
+    buttons: {
+      export?: never;
+    };
+    ariaLabels?: {
+      export?: never;
+    };
+  };
+};
+
+type WithoutExpandButtonProps = {
+  onToggleExpand?: never;
+  toolbarCopy?: {
+    buttons?: {
+      expand?: never;
+    };
+    ariaLabels?: {
+      expand?: never;
+    };
+  };
+};
+
+type WithoutFiltersProps = {
+  enableFilters?: false | undefined;
+  /**
+   * Optional properties for customizing the filter copy.
+   */
+  toolbarCopy?: {
+    buttons?: {
+      clearFilters?: never;
+    };
+    ariaLabels?: {
+      clearFilters?: never;
+    };
+  };
+};
+
+/**
+ * Props for enabling a settings drawer in a data table component.
+ */
+type WithSettingsDrawerProps = {
+  /**
+   * Optional properties for customizing the settings drawer copy.
+   */
+  settingsDrawerCopy: TableSettingsDrawerCopyProps;
+  toolbarCopy: {
+    buttons: {
+      settings: string;
+    };
+    ariaLabels: {
+      settings: string;
+    };
+  };
+};
+
+/**
+ * Props for enabling a single export format in a data table component.
+ */
+type WithSingleExportFormatProps = {
+  /**
+   * The format in which the data should be exported.
+   */
+  exportFormats: string;
+
+  /**
+   * Callback function triggered when exporting data.
+   * @param format - The format in which the data should be exported.
+   */
+  onExportData: (format: string) => void;
+
+  /**
+   * Copy for the toolbar buttons and ARIA labels related to exporting.
+   */
+  toolbarCopy: {
+    buttons: {
+      export: string;
+    };
+    ariaLabels: {
+      export: string;
+    };
+  };
+
+  exportDrawerCopy?: never;
+};
+
+type WithoutSettingsDrawerProps = {
+  /**
+   * Optional properties for customizing the settings drawer copy.
+   */
+  settingsDrawerCopy?: undefined;
+  toolbarCopy?: {
+    buttons?: {
+      settings?: undefined;
+    };
+    ariaLabels?: {
+      settings?: undefined;
+    };
+  };
+};

package/src/use-screen-size.hook.ts

@@ -0,0 +1,23 @@
+import { useLayoutEffect, useState } from "react";
+import { purpurBreakpointRelativeLg } from "@purpurds/tokens";
+
+export const SCREEN_MEDIA_QUERY = {
+  MAX_LG: `(max-width: ${purpurBreakpointRelativeLg})`,
+} as const;
+
+export const useScreenSize = () => {
+  const [isLgOrSmaller, setIsLgOrSmaller] = useState(false);
+
+  useLayoutEffect(() => {
+    const maxMediumScreen = window.matchMedia(SCREEN_MEDIA_QUERY.MAX_LG);
+    function updateSize() {
+      setIsLgOrSmaller(maxMediumScreen.matches);
+    }
+
+    window.addEventListener("resize", updateSize);
+    updateSize();
+    return () => window.removeEventListener("resize", updateSize);
+  }, []);
+
+  return { isLgOrSmaller };
+};

package/src/use-truncated-hook.tsx

@@ -0,0 +1,74 @@
+import { useEffect, useRef, useState } from "react";
+import { Cell, RowData } from "@tanstack/react-table";
+
+const useTruncatedTooltip = <TData extends RowData>(cell: Cell<TData, unknown> | undefined) => {
+  const divRef = useRef<HTMLParagraphElement>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+  const timeoutIdRef = useRef<NodeJS.Timeout | undefined>(undefined);
+  const [showPopover, setShowPopover] = useState(false);
+
+  const debounce = (func: (...args: unknown[]) => void, delay: number) => {
+    let timeoutId: NodeJS.Timeout;
+    const debouncedFunction = (...args: unknown[]) => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => func.apply(this, args), delay);
+    };
+    return {
+      debouncedFunction,
+      get timeoutId() {
+        return timeoutId;
+      },
+    };
+  };
+
+  useEffect(() => {
+    if (!cell) {
+      return;
+    }
+
+    const { debouncedFunction: checkTruncation, timeoutId } = debounce(() => {
+      if (divRef.current && cell) {
+        const pEl = divRef.current.querySelector("p");
+        if (pEl) {
+          setIsTruncated(pEl.scrollWidth > cell.column.getSize());
+        }
+      }
+    }, 100); // Adjust debounce delay as needed
+
+    checkTruncation();
+    timeoutIdRef.current = timeoutId;
+
+    return () => {
+      clearTimeout(timeoutIdRef.current);
+    };
+  }, [cell]);
+
+  useEffect(() => {
+    if (divRef.current && cell) {
+      if (divRef.current.textContent) {
+        const pEl = divRef.current.querySelector("p");
+        if (pEl) {
+          setIsTruncated(pEl.scrollWidth > cell.column.getSize());
+        }
+        const aEl = divRef.current.querySelector("a");
+        if (aEl) {
+          setIsTruncated(aEl.scrollWidth > cell.column.getSize());
+        }
+      }
+    }
+  }, [divRef, cell, isTruncated]);
+
+  const onMouseEnter = () => {
+    if (isTruncated) {
+      setShowPopover(true);
+    }
+  };
+
+  const onMouseLeave = () => {
+    setShowPopover(false);
+  };
+
+  return { divRef, onMouseEnter, onMouseLeave, showPopover };
+};
+
+export default useTruncatedTooltip;

package/src/utils/custom-functions.ts

@@ -0,0 +1,52 @@
+import { BadgeVariant } from "@purpurds/badge";
+import { Row } from "@tanstack/react-table";
+
+export const filterOnFilterKey = <TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: {
+    filterKey: string;
+    value: string;
+  }
+): boolean => {
+  const { filterKey, value } = filterValue;
+  const cellValue = row.getValue<Record<string, unknown>>(columnId);
+  return value === "" || cellValue[filterKey] === value;
+};
+
+export const sortOnBadgeVariant = <TData>(
+  row1: Row<TData>,
+  row0: Row<TData>,
+  columnId: string
+): number => {
+  const row0Value = row0.getValue(columnId) as {
+    variant: BadgeVariant;
+    children: React.ReactNode;
+  };
+  const row1Value = row1.getValue(columnId) as {
+    variant: BadgeVariant;
+    children: React.ReactNode;
+  };
+
+  return row1Value.variant.localeCompare(row0Value.variant);
+};
+
+export const sortOnBadgeValue = <TData>(
+  row1: Row<TData>,
+  row0: Row<TData>,
+  columnId: string
+): number => {
+  const row0Value = row0.getValue(columnId) as {
+    variant: BadgeVariant;
+    children: React.ReactNode;
+  };
+  const row1Value = row1.getValue(columnId) as {
+    variant: BadgeVariant;
+    children: React.ReactNode;
+  };
+
+  const row0String = row0Value.children as string;
+  const row1String = row1Value.children as string;
+
+  return row1String.localeCompare(row0String);
+};