@purpurds/table 8.9.0 → 8.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purpurds/table",
-  "version": "8.9.0",
+  "version": "8.10.1",
   "license": "AGPL-3.0-only",
   "main": "./dist/table.cjs.js",
   "types": "./dist/table.d.ts",
@@ -21,22 +21,22 @@
     "@dnd-kit/utilities": "~3.2.2",
     "@tanstack/react-table": "~8.21.2",
     "classnames": "~2.5.1",
-    "@purpurds/badge": "8.9.0",
-    "@purpurds/button": "8.9.0",
-    "@purpurds/cta-link": "8.9.0",
-    "@purpurds/drawer": "8.9.0",
-    "@purpurds/checkbox": "8.9.0",
-    "@purpurds/heading": "8.9.0",
-    "@purpurds/icon": "8.9.0",
-    "@purpurds/link": "8.9.0",
-    "@purpurds/select": "8.9.0",
-    "@purpurds/skeleton": "8.9.0",
-    "@purpurds/paragraph": "8.9.0",
-    "@purpurds/text-field": "8.9.0",
-    "@purpurds/tokens": "8.9.0",
-    "@purpurds/toggle": "8.9.0",
-    "@purpurds/visually-hidden": "8.9.0",
-    "@purpurds/tooltip": "8.9.0"
+    "@purpurds/checkbox": "8.10.1",
+    "@purpurds/cta-link": "8.10.1",
+    "@purpurds/drawer": "8.10.1",
+    "@purpurds/badge": "8.10.1",
+    "@purpurds/button": "8.10.1",
+    "@purpurds/heading": "8.10.1",
+    "@purpurds/link": "8.10.1",
+    "@purpurds/paragraph": "8.10.1",
+    "@purpurds/select": "8.10.1",
+    "@purpurds/skeleton": "8.10.1",
+    "@purpurds/toggle": "8.10.1",
+    "@purpurds/icon": "8.10.1",
+    "@purpurds/text-field": "8.10.1",
+    "@purpurds/tooltip": "8.10.1",
+    "@purpurds/tokens": "8.10.1",
+    "@purpurds/visually-hidden": "8.10.1"
   },
   "devDependencies": {
     "@rushstack/eslint-patch": "~1.10.0",
@@ -60,13 +60,13 @@
     "vitest-axe": "~0.1.0",
     "vitest-canvas-mock": "~0.3.3",
     "vitest": "^4.0.10",
-    "@purpurds/autocomplete": "8.9.0",
-    "@purpurds/grid": "8.9.0",
+    "@purpurds/autocomplete": "8.10.1",
+    "@purpurds/grid": "8.10.1",
     "@purpurds/component-rig": "1.0.0",
-    "@purpurds/illustrative-icon": "8.9.0",
-    "@purpurds/label": "8.9.0",
-    "@purpurds/listbox": "8.9.0",
-    "@purpurds/pagination": "8.9.0"
+    "@purpurds/illustrative-icon": "8.10.1",
+    "@purpurds/label": "8.10.1",
+    "@purpurds/listbox": "8.10.1",
+    "@purpurds/pagination": "8.10.1"
   },
   "scripts": {
     "build:dev": "vite",

package/src/empty-table.tsx

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { useEffect, useState } from "react";
 import { Heading, type HeadingTagType } from "@purpurds/heading";
 import { Paragraph } from "@purpurds/paragraph";
 import c from "classnames/bind";
@@ -17,6 +17,7 @@ type EmptyTableProps = {
   description: string;
   colSpan: number;
   icon: React.ReactNode;
+  tableContainerId: string;
 };
 
 export const EmptyTable = ({
@@ -26,29 +27,56 @@ export const EmptyTable = ({
   description,
   colSpan,
   icon,
-}: EmptyTableProps) => (
-  <TableRow>
-    <TableRowCell
-      colSpan={colSpan}
-      isLastRow={true}
-      isFirstCell={true}
-      isLastCell={true}
-      enableColumnDrag={false}
-    >
-      <div
-        className={cx([
-          `${rootClassName}__empty-section`,
-          `${rootClassName}__empty-section--${variant}`,
-        ])}
+  tableContainerId,
+}: EmptyTableProps) => {
+  const [visibleWidth, setVisibleWidth] = useState<number | undefined>(undefined);
+
+  useEffect(() => {
+    const updateWidth = () => {
+      const container = document.getElementById(tableContainerId);
+      if (container) {
+        setVisibleWidth(container.clientWidth);
+      }
+    };
+
+    updateWidth();
+    window.addEventListener("resize", updateWidth);
+
+    const container = document.getElementById(tableContainerId);
+    container?.addEventListener("scroll", updateWidth);
+
+    return () => {
+      window.removeEventListener("resize", updateWidth);
+      container?.removeEventListener("scroll", updateWidth);
+    };
+  }, [tableContainerId]);
+
+  return (
+    <TableRow>
+      <TableRowCell
+        colSpan={colSpan}
+        isLastRow={true}
+        isFirstCell={true}
+        isLastCell={true}
+        enableColumnDrag={false}
+        isEmptyTable={true}
       >
-        {icon && <div className={cx(`${rootClassName}__empty-section__icon`)}>{icon}</div>}
-        <div className={cx(`${rootClassName}__empty-section__texts`)}>
-          <Heading data-testid="purpur-table-empty-table-title" variant="title-100" tag={tag}>
-            {title}
-          </Heading>
-          <Paragraph data-testid="purpur-table-empty-table-description">{description}</Paragraph>
+        <div
+          className={cx([
+            `${rootClassName}__empty-section`,
+            `${rootClassName}__empty-section--${variant}`,
+          ])}
+          style={visibleWidth ? { width: `${visibleWidth}px` } : undefined}
+        >
+          {icon && <div className={cx(`${rootClassName}__empty-section__icon`)}>{icon}</div>}
+          <div className={cx(`${rootClassName}__empty-section__texts`)}>
+            <Heading data-testid="purpur-table-empty-table-title" variant="title-100" tag={tag}>
+              {title}
+            </Heading>
+            <Paragraph data-testid="purpur-table-empty-table-description">{description}</Paragraph>
+          </div>
         </div>
-      </div>
-    </TableRowCell>
-  </TableRow>
-);
+      </TableRowCell>
+    </TableRow>
+  );
+};

package/src/table-column-header-cell.tsx

@@ -5,6 +5,7 @@ import { Button } from "@purpurds/button";
 import { Checkbox, type CheckedState } from "@purpurds/checkbox";
 import { IconArrowDown } from "@purpurds/icon/arrow-down";
 import { IconArrowUp } from "@purpurds/icon/arrow-up";
+import { IconSearch } from "@purpurds/icon/search";
 import { IconSorter } from "@purpurds/icon/sorter";
 import { Paragraph } from "@purpurds/paragraph";
 import { Select, type SelectProps } from "@purpurds/select";
@@ -204,7 +205,6 @@ export const TableColumnHeaderCell = <TData extends RowData>({
         <div
           className={cx(`${rootClassName}__inner`)}
           style={{
-            maxWidth: widthInRemString,
             minWidth: widthInRemString,
           }}
         >
@@ -406,6 +406,7 @@ const Filter = <TData extends RowData>({ header }: { header: Header<TData, unkno
         }
         placeholder={filterPlaceholder}
         aria-label={filterAriaLabel}
+        startAdornment={<IconSearch key="search-icon" size="xs" />}
       />
     );
   }

package/src/table-content.tsx

@@ -34,6 +34,7 @@ type TableContentProps<TData extends RowData> = {
   emptyTableHeadingTag?: HeadingTagType;
   emptyTableCopy?: { title: string; description: string };
   emptyTableIcon?: React.ReactNode;
+  tableContainerId?: string;
 };
 
 export function TableContent<TData extends RowData>({
@@ -55,6 +56,7 @@ export function TableContent<TData extends RowData>({
   emptyTableHeadingTag,
   emptyTableCopy,
   emptyTableIcon,
+  tableContainerId,
 }: TableContentProps<TData>) {
   return (
     <table
@@ -82,6 +84,7 @@ export function TableContent<TData extends RowData>({
             description={emptyTableCopy.description}
             colSpan={tanstackTable.getVisibleLeafColumns().length}
             icon={emptyTableIcon}
+            tableContainerId={tableContainerId!}
           />
         ) : (
           tableRows.map((row, rowIndex) => (

package/src/table-row-cell.tsx

@@ -45,7 +45,7 @@ type TableRowCellProps<TData extends RowData> = {
   isLastCell: boolean;
   enableColumnDrag: boolean;
   draggingActive?: boolean;
-  enableRowDrag?: boolean;
+  isEmptyTable?: boolean;
 } & (EmptyTableCell | TableRowCell<TData>);
 
 const rootClassName = "purpur-table-row-cell";
@@ -64,7 +64,7 @@ const TableRowCell = <TData extends RowData>({
   isLastCell,
   enableColumnDrag,
   draggingActive,
-  enableRowDrag,
+  isEmptyTable,
 }: TableRowCellProps<TData>) => {
   const elementRef = useRef<HTMLTableCellElement | null>(null);
   const isVisible = useElementVisibility(elementRef, 1);
@@ -98,6 +98,7 @@ const TableRowCell = <TData extends RowData>({
       (cell?.column.getIsLastColumn() || isLastCell) && isVisible && isLastRow,
     [`${rootClassName}__column-drag-enabled`]: enableColumnDrag,
     [`${rootClassName}__dragging`]: draggingActive,
+    [`${rootClassName}__empty-table`]: isEmptyTable,
     [`${rootClassName}--drop-indicator-before`]:
       !isRowSelector && dropIndicatorPosition === "before",
     [`${rootClassName}--drop-indicator-after`]: !isRowSelector && dropIndicatorPosition === "after",

package/src/table-settings-drawer.module.scss

@@ -63,7 +63,7 @@ $border-width: 1px;
 
   div#{$root}__toggle {
     justify-content: space-between;
-    width: 100%;
+    min-width: 100%;
   }
 
   &__draggable-item {

package/src/table.module.scss

@@ -104,6 +104,7 @@ $indicatorWidth: 3px;
     padding: var(--purpur-spacing-100) var(--purpur-spacing-150) var(--purpur-spacing-100)
       var(--purpur-spacing-300);
     align-self: stretch;
+    max-width: fit-content;
   }
 
   &__content {
@@ -316,6 +317,15 @@ $indicatorWidth: 3px;
   white-space: nowrap;
   text-overflow: ellipsis;
 
+  &__empty-table {
+    padding: 0;
+
+    .purpur-table__empty-section {
+      border-bottom-left-radius: var(--table-border-radius);
+      border-bottom-right-radius: var(--table-border-radius);
+    }
+  }
+
   &__date {
     display: flex;
     align-items: center;
@@ -493,6 +503,8 @@ $indicatorWidth: 3px;
   align-items: center;
   gap: var(--purpur-spacing-150);
   align-self: stretch;
+  position: sticky;
+  left: 0;
 
   &__icon {
     width: var(--purpur-spacing-1600);

package/src/table.stories.tsx

@@ -1309,6 +1309,138 @@ This example demonstrates the secondary visual variant of the Table.
   },
 };
 
+/**
+ * Demonstrates controlled table settings with user preferences that differ from defaults.
+ */
+export const ControlledTableSettings: StoryTableData = {
+  args: {
+    variant: "primary",
+    enableFilters: true,
+    enableToolbar: true,
+    settingsDrawerCopy: commonSettingsDrawerCopy,
+    toolbarCopy: commonToolbarCopy,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+This example demonstrates controlled table settings where the user's saved preferences 
+differ from the default values. This is useful for persisting user preferences across sessions.
+
+### How to enable this feature:
+\`\`\`jsx
+const [tableSettings, setTableSettings] = useState({
+  showColumnFilters: false,  // User turned off filters
+  stickyHeaders: false,      // User turned off sticky headers
+  stickyFirstColumn: false,  // User turned off sticky first column
+});
+
+<Table
+  enableFilters={true}
+  
+  // Controlled state (user preferences)
+  controlledShowColumnFilters={tableSettings.showColumnFilters}
+  onShowColumnFiltersChange={(value) => 
+    setTableSettings(prev => ({ ...prev, showColumnFilters: value }))
+  }
+  
+  controlledStickyHeaders={tableSettings.stickyHeaders}
+  onStickyHeadersChange={(value) => 
+    setTableSettings(prev => ({ ...prev, stickyHeaders: value }))
+  }
+  
+  controlledStickyFirstColumn={tableSettings.stickyFirstColumn}
+  onStickyFirstColumnChange={(value) => 
+    setTableSettings(prev => ({ ...prev, stickyFirstColumn: value }))
+  }
+  
+  // Default values (for reset button)
+  defaultShowColumnFilters={true}
+  defaultStickyHeaders={true}
+  defaultStickyFirstColumn={true}
+  ...other props
+/>
+\`\`\`
+
+### Key points:
+- User preferences are stored in state (could be localStorage, API, etc.)
+- Defaults are different from current user preferences
+- Reset button in settings drawer will restore to defaults
+- State changes are captured via onChange callbacks
+- Demonstrates state persistence pattern
+- Uses larger dataset with more columns and rows to properly test sticky functionality
+
+### Try it out:
+1. Open the Settings drawer
+2. Notice filters are hidden, headers aren't sticky, and first column isn't locked
+3. Scroll horizontally and vertically to see the difference
+4. Toggle "Sticky header" to see headers stay fixed while scrolling down
+5. Toggle "Lock first column" to see the first column stay fixed while scrolling horizontally
+6. Click "Reset settings" to restore all to defaults (all enabled)
+        `,
+      },
+    },
+  },
+  render: (args) => {
+    const [tableSettings, setTableSettings] = useState({
+      showColumnFilters: false, // User turned off filters (default is true)
+      stickyHeaders: false, // User turned off sticky headers (default is true)
+      stickyFirstColumn: false, // User turned off sticky first column (default is true)
+    });
+
+    const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+    const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
+
+    // Simulate saving to localStorage when settings change
+    const handleShowColumnFiltersChange = (value: boolean) => {
+      setTableSettings((prev) => ({ ...prev, showColumnFilters: value }));
+      console.log("Saving showColumnFilters to localStorage:", value);
+    };
+
+    const handleStickyHeadersChange = (value: boolean) => {
+      setTableSettings((prev) => ({ ...prev, stickyHeaders: value }));
+      console.log("Saving stickyHeaders to localStorage:", value);
+    };
+
+    const handleStickyFirstColumnChange = (value: boolean) => {
+      setTableSettings((prev) => ({ ...prev, stickyFirstColumn: value }));
+      console.log("Saving stickyFirstColumn to localStorage:", value);
+    };
+
+    return renderTableContainer(
+      args,
+      <Table
+        className={c("table-max-height")}
+        variant={args.variant}
+        columns={columnDef}
+        data={generatedTableData.slice(0, 50)}
+        enableFilters={true}
+        enableToolbar={true}
+        enableSorting={false}
+        enableRowSelection={false}
+        enableActionBar={false}
+        toolbarCopy={commonToolbarCopy}
+        settingsDrawerCopy={commonSettingsDrawerCopy}
+        controlledShowColumnFilters={tableSettings.showColumnFilters}
+        onShowColumnFiltersChange={handleShowColumnFiltersChange}
+        controlledStickyHeaders={tableSettings.stickyHeaders}
+        onStickyHeadersChange={handleStickyHeadersChange}
+        controlledStickyFirstColumn={tableSettings.stickyFirstColumn}
+        onStickyFirstColumnChange={handleStickyFirstColumnChange}
+        defaultShowColumnFilters={true}
+        defaultStickyHeaders={true}
+        defaultStickyFirstColumn={true}
+        state={{ columnFilters, columnVisibility }}
+        onColumnFiltersChange={setColumnFilters}
+        onColumnVisibilityChange={setColumnVisibility}
+        onExportData={(e) => console.log("Export data", e)}
+        exportFormats={"csv"}
+        onToggleExpand={() => console.log("Toggle expand")}
+      />
+    );
+  },
+};
+
 export const WithColumnDragAndDrop = {
   name: "With column drag and drop",
   args: {

package/src/table.tsx

@@ -72,7 +72,22 @@ export type TableProps<TData extends RowData> = {
   data: TData[];
   paginationComponent?: ReactElement<PaginationProps>;
   fullWidth?: boolean;
+  controlledShowColumnFilters?: boolean;
+  onShowColumnFiltersChange?: (value: boolean) => void;
+  controlledStickyHeaders?: boolean;
+  onStickyHeadersChange?: (value: boolean) => void;
+  controlledStickyFirstColumn?: boolean;
+  onStickyFirstColumnChange?: (value: boolean) => void;
+  defaultShowColumnFilters?: boolean;
+  defaultStickyHeaders?: boolean;
+  defaultStickyFirstColumn?: boolean;
+  /**
+   * @deprecated Use defaultStickyHeaders instead
+   */
   stickyHeaders?: boolean;
+  /**
+   * @deprecated Use defaultStickyFirstColumn instead
+   */
   stickyFirstColumn?: boolean;
   onRowsCountChange?: (rowsCount: number) => void;
   drawerZIndex?: number;
@@ -109,8 +124,17 @@ export const Table = <TData extends RowData>({
   skeletonRows,
   sortingAriaLabels,
   state,
-  stickyFirstColumn: stickyFirstColumnProp = true,
-  stickyHeaders: stickyHeadersProp = true,
+  controlledShowColumnFilters,
+  onShowColumnFiltersChange,
+  controlledStickyFirstColumn,
+  onStickyFirstColumnChange,
+  controlledStickyHeaders,
+  onStickyHeadersChange,
+  defaultShowColumnFilters,
+  defaultStickyFirstColumn,
+  defaultStickyHeaders,
+  stickyHeaders: stickyHeadersDeprecated,
+  stickyFirstColumn: stickyFirstColumnDeprecated,
   toolbarCopy,
   toolbarTotalRowCount,
   variant = "primary",
@@ -128,11 +152,80 @@ export const Table = <TData extends RowData>({
 }: TableProps<TData>) => {
   const [isSettingsDrawerOpen, setSettingsDrawerIsOpen] = useState(false);
   const [isExportDrawerOpen, setExportDrawerIsOpen] = useState(false);
-  const [showColumnFiltersEnabled, setShowColumnFiltersEnabled] = useState(
-    Boolean(props.enableFilters)
+
+  // Determine if controlled based on BOTH prop AND handler being provided
+  const isShowColumnFiltersControlled =
+    controlledShowColumnFilters !== undefined && onShowColumnFiltersChange !== undefined;
+  const isStickyFirstColumnControlled =
+    controlledStickyFirstColumn !== undefined && onStickyFirstColumnChange !== undefined;
+  const isStickyHeadersControlled =
+    controlledStickyHeaders !== undefined && onStickyHeadersChange !== undefined;
+
+  // Support deprecated props as fallbacks for defaults (backwards compatibility)
+  const effectiveDefaultStickyHeaders =
+    defaultStickyHeaders !== undefined
+      ? defaultStickyHeaders
+      : stickyHeadersDeprecated !== undefined
+      ? stickyHeadersDeprecated
+      : true;
+  const effectiveDefaultStickyFirstColumn =
+    defaultStickyFirstColumn !== undefined
+      ? defaultStickyFirstColumn
+      : stickyFirstColumnDeprecated !== undefined
+      ? stickyFirstColumnDeprecated
+      : true;
+
+  // Internal state - only used when not controlled
+  const [showColumnFiltersInternal, setShowColumnFiltersInternal] = useState(
+    defaultShowColumnFilters ?? Boolean(props.enableFilters)
+  );
+  const [stickyFirstColumnInternal, setStickyFirstColumnInternal] = useState(
+    effectiveDefaultStickyFirstColumn
   );
-  const [stickyFirstColumn, setStickyFirstColumn] = useState(stickyFirstColumnProp);
-  const [stickyHeaders, setStickyHeaders] = useState(stickyHeadersProp);
+  const [stickyHeadersInternal, setStickyHeadersInternal] = useState(effectiveDefaultStickyHeaders);
+
+  // Use controlled value if fully controlled, otherwise use internal state
+  const showColumnFiltersEnabled = isShowColumnFiltersControlled
+    ? controlledShowColumnFilters!
+    : showColumnFiltersInternal;
+  const stickyFirstColumn = isStickyFirstColumnControlled
+    ? controlledStickyFirstColumn!
+    : stickyFirstColumnInternal;
+  const stickyHeaders = isStickyHeadersControlled
+    ? controlledStickyHeaders!
+    : stickyHeadersInternal;
+
+  // Wrapper functions to handle both controlled and uncontrolled state
+  const setShowColumnFiltersEnabled = (value: boolean | ((prev: boolean) => boolean)) => {
+    const newValue = typeof value === "function" ? value(showColumnFiltersEnabled) : value;
+
+    if (isShowColumnFiltersControlled) {
+      onShowColumnFiltersChange!(newValue);
+    } else {
+      setShowColumnFiltersInternal(newValue);
+    }
+  };
+
+  const setStickyFirstColumn = (value: boolean | ((prev: boolean) => boolean)) => {
+    const newValue = typeof value === "function" ? value(stickyFirstColumn) : value;
+
+    if (isStickyFirstColumnControlled) {
+      onStickyFirstColumnChange!(newValue);
+    } else {
+      setStickyFirstColumnInternal(newValue);
+    }
+  };
+
+  const setStickyHeaders = (value: boolean | ((prev: boolean) => boolean)) => {
+    const newValue = typeof value === "function" ? value(stickyHeaders) : value;
+
+    if (isStickyHeadersControlled) {
+      onStickyHeadersChange!(newValue);
+    } else {
+      setStickyHeadersInternal(newValue);
+    }
+  };
+
   const prevShowOnlySelectedRows = useRef(showOnlySelectedRows);
   const tableContainerRef = useRef<HTMLTableElement>(null);
   const uid = useId();
@@ -298,9 +391,9 @@ export const Table = <TData extends RowData>({
   };
 
   const handleResetSettings = () => {
-    setShowColumnFiltersEnabled(Boolean(props.enableFilters));
-    setStickyFirstColumn(stickyFirstColumnProp);
-    setStickyHeaders(stickyHeadersProp);
+    setShowColumnFiltersEnabled(defaultShowColumnFilters ?? Boolean(props.enableFilters));
+    setStickyFirstColumn(effectiveDefaultStickyFirstColumn);
+    setStickyHeaders(effectiveDefaultStickyHeaders);
     tanstackTable.resetColumnOrder();
     tanstackTable.resetColumnVisibility();
   };
@@ -409,6 +502,7 @@ export const Table = <TData extends RowData>({
       emptyTableHeadingTag={emptyTableHeadingTag}
       emptyTableCopy={emptyTableCopy}
       emptyTableIcon={emptyTableIcon}
+      tableContainerId={`${uid}-table-container`}
     />
   );
 
@@ -434,6 +528,7 @@ export const Table = <TData extends RowData>({
         />
       )}
       <div
+        id={`${uid}-table-container`}
         className={cx(`${rootClassName}__container`, {
           [`${rootClassName}__container--scrolled`]: isScrolled,
         })}