@purpurds/table 8.14.0 → 8.16.0

package/src/table.test.tsx

@@ -180,7 +180,7 @@ describe("Data Table", () => {
   });
 
   describe("Expand table", () => {
-    it("should have an expand button", async () => {
+    it("should have an expand button, handle its own state, and default to false", async () => {
       const onToggleExpandMock = vi.fn();
 
       render(
@@ -191,9 +191,11 @@ describe("Data Table", () => {
           toolbarCopy={{
             buttons: {
               expand: "Expand",
+              minimize: "Minimize",
             },
             ariaLabels: {
               expand: "Expand table",
+              minimize: "Minimize table",
             },
           }}
           onToggleExpand={onToggleExpandMock}
@@ -202,8 +204,295 @@ describe("Data Table", () => {
 
       const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
 
+      // First click should expand (pass true)
       await userEvent.click(expandButton);
-      expect(onToggleExpandMock).toHaveBeenCalled();
+      expect(onToggleExpandMock).toHaveBeenCalledWith(true);
+
+      // Second click should minimize (pass false)
+      await userEvent.click(expandButton);
+      expect(onToggleExpandMock).toHaveBeenCalledWith(false);
+    });
+
+    describe("with defaultExpanded prop, without controlledExpanded prop", () => {
+      it("should start in expanded state when defaultExpanded is true", () => {
+        const onToggleExpandMock = vi.fn();
+
+        render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            defaultExpanded={true}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Button should show minimize state
+        expect(expandButton).toHaveTextContent("Minimize");
+        expect(expandButton).toHaveAttribute("aria-expanded", "true");
+        expect(expandButton).toHaveAttribute("aria-label", "Minimize table");
+      });
+
+      it("should start in minimized state when defaultExpanded is false", () => {
+        const onToggleExpandMock = vi.fn();
+
+        render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            defaultExpanded={false}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Button should show expand state
+        expect(expandButton).toHaveTextContent("Expand");
+        expect(expandButton).toHaveAttribute("aria-expanded", "false");
+        expect(expandButton).toHaveAttribute("aria-label", "Expand table");
+      });
+
+      it("should toggle state internally when defaultExpanded is provided", async () => {
+        const onToggleExpandMock = vi.fn();
+
+        render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            defaultExpanded={false}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Initial state - collapsed
+        expect(expandButton).toHaveTextContent("Expand");
+
+        // Click to expand
+        await userEvent.click(expandButton);
+        expect(onToggleExpandMock).toHaveBeenCalledWith(true);
+        expect(expandButton).toHaveTextContent("Minimize");
+
+        // Click to collapse
+        await userEvent.click(expandButton);
+        expect(onToggleExpandMock).toHaveBeenCalledWith(false);
+        expect(expandButton).toHaveTextContent("Expand");
+      });
+    });
+
+    describe("with controlledExpanded prop", () => {
+      it("should use controlledExpanded value when provided", () => {
+        const onToggleExpandMock = vi.fn();
+
+        const { rerender } = render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={false}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Should be collapsed
+        expect(expandButton).toHaveTextContent("Expand");
+        expect(expandButton).toHaveAttribute("aria-expanded", "false");
+
+        // Rerender with expanded state
+        rerender(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={true}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        // Should be expanded
+        expect(expandButton).toHaveTextContent("Minimize");
+        expect(expandButton).toHaveAttribute("aria-expanded", "true");
+      });
+
+      it("should not manage state internally when controlledExpanded is provided", async () => {
+        const onToggleExpandMock = vi.fn();
+
+        render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={false}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Initial state - collapsed
+        expect(expandButton).toHaveTextContent("Expand");
+
+        // Click should trigger callback but not change internal state
+        await userEvent.click(expandButton);
+        expect(onToggleExpandMock).toHaveBeenCalledWith(true);
+
+        // Button should remain in collapsed state since parent didn't update controlledExpanded
+        expect(expandButton).toHaveTextContent("Expand");
+      });
+
+      it("should ignore defaultExpanded when controlledExpanded is provided", () => {
+        const onToggleExpandMock = vi.fn();
+
+        render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={false}
+            defaultExpanded={true}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Should use controlledExpanded (false) instead of defaultExpanded (true)
+        expect(expandButton).toHaveTextContent("Expand");
+        expect(expandButton).toHaveAttribute("aria-expanded", "false");
+      });
+
+      it("should handle toggling between expanded states with controlled prop", () => {
+        const onToggleExpandMock = vi.fn();
+
+        const { rerender } = render(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={true}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        const expandButton = screen.getByTestId(Selectors.TOOLBAR.EXPAND_BUTTON);
+
+        // Initially expanded
+        expect(expandButton).toHaveTextContent("Minimize");
+        expect(expandButton).toHaveAttribute("aria-label", "Minimize table");
+
+        // Update to collapsed
+        rerender(
+          <Table
+            columns={createColumnDefSmall()}
+            data={tableDataSmall}
+            enableToolbar={true}
+            controlledExpanded={false}
+            toolbarCopy={{
+              buttons: {
+                expand: "Expand",
+                minimize: "Minimize",
+              },
+              ariaLabels: {
+                expand: "Expand table",
+                minimize: "Minimize table",
+              },
+            }}
+            onToggleExpand={onToggleExpandMock}
+          />
+        );
+
+        // Should be collapsed
+        expect(expandButton).toHaveTextContent("Expand");
+        expect(expandButton).toHaveAttribute("aria-label", "Expand table");
+      });
     });
   });
 
@@ -217,10 +506,10 @@ describe("Data Table", () => {
           settingsDrawerCopy={copy.settingsDrawer}
           toolbarCopy={{
             buttons: {
-              settings: "Settings",
+              settings: "Table settings",
             },
             ariaLabels: {
-              settings: "Settings",
+              settings: "Table settings",
             },
           }}
         />

package/src/table.tsx

@@ -141,6 +141,8 @@ export const Table = <TData extends RowData>({
   getRowId,
   onExportData,
   onRowsCountChange,
+  controlledExpanded,
+  defaultExpanded,
   onToggleExpand,
   onPrimaryButtonClick,
   onSecondaryButtonClick,
@@ -154,6 +156,8 @@ export const Table = <TData extends RowData>({
   const [isExportDrawerOpen, setExportDrawerIsOpen] = useState(false);
 
   // Determine if controlled based on BOTH prop AND handler being provided
+  const isExpandedControlled =
+    controlledExpanded !== undefined && onToggleExpand !== undefined;
   const isShowColumnFiltersControlled =
     controlledShowColumnFilters !== undefined && onShowColumnFiltersChange !== undefined;
   const isStickyFirstColumnControlled =
@@ -176,6 +180,9 @@ export const Table = <TData extends RowData>({
       : true;
 
   // Internal state - only used when not controlled
+  const [expandedInternal, setExpandedInternal] = useState(
+    defaultExpanded ?? false
+  );
   const [showColumnFiltersInternal, setShowColumnFiltersInternal] = useState(
     defaultShowColumnFilters ?? Boolean(props.enableFilters)
   );
@@ -185,6 +192,9 @@ export const Table = <TData extends RowData>({
   const [stickyHeadersInternal, setStickyHeadersInternal] = useState(effectiveDefaultStickyHeaders);
 
   // Use controlled value if fully controlled, otherwise use internal state
+  const expanded = isExpandedControlled
+    ? controlledExpanded!
+    : expandedInternal;
   const showColumnFiltersEnabled = isShowColumnFiltersControlled
     ? controlledShowColumnFilters!
     : showColumnFiltersInternal;
@@ -196,6 +206,13 @@ export const Table = <TData extends RowData>({
     : stickyHeadersInternal;
 
   // Wrapper functions to handle both controlled and uncontrolled state
+  const onToggleExpandInternal = (value: boolean) => {
+    if (!isExpandedControlled) {
+      setExpandedInternal(value);
+    }
+    onToggleExpand!(value);
+  };
+
   const setShowColumnFiltersEnabled = (value: boolean | ((prev: boolean) => boolean)) => {
     const newValue = typeof value === "function" ? value(showColumnFiltersEnabled) : value;
 
@@ -515,11 +532,12 @@ export const Table = <TData extends RowData>({
           exportDrawerAriaControls={`${uid}-export-drawer`}
           onSetDrawerIsOpen={setSettingsDrawerIsOpen}
           onResetColumnFilters={handleResetColumnFilters}
-          onToggleExpand={onToggleExpand}
+          onToggleExpand={onToggleExpandInternal}
           onExportData={handleExportButton}
           totalRowCount={toolbarTotalRowCount ?? tanstackTable.getRowCount()}
           visibleRowCount={tanstackTable.getRowModel().rows.length}
           toolbarCopy={toolbarCopy}
+          expanded={expanded}
           isSettingsDrawerOpen={isSettingsDrawerOpen}
           hasExportsDrawer={Array.isArray(exportFormats)}
           isExportDrawerOpen={isExportDrawerOpen}

package/src/test-utils/helpers.ts

@@ -219,7 +219,7 @@ export const copy = {
       description: "Change general table settings",
       rearrangeDescription: "Choose how you want to reorder the columns.",
       buttons: {
-        rearrange: "Reorder",
+        rearrange: "Reorder columns",
         done: "Done",
       },
       ariaLabels: {
@@ -248,12 +248,14 @@ export const copy = {
     buttons: {
       clearFilters: "Clear filters",
       expand: "Expand",
+      minimize: "Minimize",
       export: "Export",
-      settings: "Settings",
+      settings: "Table settings",
     },
     ariaLabels: {
-      clearFilters: "Clear all filters",
+      clearFilters: "Clear all table filters",
       expand: "Expand table",
+      minimize: "Minimize table",
       export: "Open export drawer",
       settings: "Open settings drawer",
     },

package/src/types.ts

@@ -315,6 +315,8 @@ export type WithoutToolbarProps = {
   enableToolbar?: false | undefined;
   exportFormats?: never;
   onExportData?: never;
+  controlledExpanded?: never;
+  defaultExpanded?: never;
   onToggleExpand?: never;
   settingsDrawerCopy?: never;
   toolbarCopy?: never;
@@ -342,10 +344,25 @@ type WithFiltersProps = {
  * Props for enabling an expand button in a data table component.
  */
 type WithExpandButtonProps = {
+  /**
+   * Current state of expansion.
+   * Regardless of setting, the consumer must listen to onToggleExpand to change the container size accordingly. The table itself only shows the Expand button differently.
+   * If defined (true or false), this is the state the table will be shown in. Consumer must listen to onToggleExpand, and update this to the new value. defaultExpanded will have no effect.
+   * If undefined, the table will manage its own state, starting with defaultExpanded.
+   */
+  controlledExpanded?: boolean;
+
+  /**
+   * Initial state of expansion.
+   * Defaults to false (collapsed=minimized) if not provided.
+   * No effect if controlledExpanded is provided.
+   */
+  defaultExpanded?: boolean;
+
   /**
    * Callback function triggered when toggling the expansion state of rows.
    */
-  onToggleExpand: () => void;
+  onToggleExpand: (value: boolean) => void;
 
   /**
    * Copy for the toolbar buttons related to expanding rows.
@@ -353,9 +370,11 @@ type WithExpandButtonProps = {
   toolbarCopy: {
     buttons: {
       expand: string;
+      minimize: string;
     };
     ariaLabels: {
       expand: string;
+      minimize: string;
     };
   };
 };
@@ -408,13 +427,17 @@ type WithoutExportProps = {
 };
 
 type WithoutExpandButtonProps = {
+  controlledExpanded?: never;
+  defaultExpanded?: never;
   onToggleExpand?: never;
   toolbarCopy?: {
     buttons?: {
       expand?: never;
+      minimize?: never;
     };
     ariaLabels?: {
       expand?: never;
+      minimize?: never;
     };
   };
 };