feat: refactor Column into ColumnManagement and add patternfly-docs/examples

Author: apinkert

packages/module/patternfly-docs/content/extensions/component-groups/examples/ColumnManagement/ColumnManagement.md

@@ -0,0 +1,28 @@
+---
+# Sidenav top-level section
+# should be the same for all markdown files
+section: Component groups
+subsection: Helpers
+# Sidenav secondary level section
+# should be the same for all markdown files
+id: Column management
+# Tab (react | react-demos | html | html-demos | design-guidelines | accessibility)
+source: react
+# If you use typescript, the name of the interface to display props for
+# These are found through the sourceProps function provided in patternfly-docs.source.js
+propComponents: ['ColumnManagement']
+sourceLink: https://github.com/patternfly/react-component-groups/blob/main/packages/module/patternfly-docs/content/extensions/component-groups/examples/ColumnManagement/ColumnManagement.md
+---
+
+import ColumnManagement from '@patternfly/react-component-groups/dist/dynamic/ColumnManagement';
+import { FunctionComponent, useState } from 'react';
+
+The **column management** component can be used to implement customizable table columns. Columns can be configured to be enabled or disabled by default or be unhidable. 
+
+## Examples
+
+### Basic column list
+
+The order of the columns can be changed by dragging and dropping the columns themselves. This list can be used within a page or within a modal. Always make sure to set `isShownByDefault` and `isShown` to the same boolean value in the initial state.
+
+```js file="./ColumnManagementExample.tsx"

packages/module/patternfly-docs/content/extensions/component-groups/examples/ColumnManagement/ColumnManagementExample.tsx

@@ -0,0 +1,57 @@
+import { FunctionComponent, useState } from 'react';
+import { Column, ColumnManagement } from '@patternfly/react-component-groups';
+
+const DEFAULT_COLUMNS: Column[] = [
+  {
+    title: 'ID',
+    key: 'id',
+    isShownByDefault: true,
+    isShown: true,
+    isUntoggleable: true
+  },
+  {
+    title: 'Publish date',
+    key: 'publishDate',
+    isShownByDefault: true,
+    isShown: true
+  },
+  {
+    title: 'Impact',
+    key: 'impact',
+    isShownByDefault: true,
+    isShown: true
+  },
+  {
+    title: 'Score',
+    key: 'score',
+    isShownByDefault: false,
+    isShown: false
+  }
+];
+
+export const ColumnExample: FunctionComponent = () => {
+  const [ columns, setColumns ] = useState(DEFAULT_COLUMNS);
+
+  return (
+    <ColumnManagement
+      title="Manage columns"
+      description="Select the columns to display in the table."
+      columns={columns}
+      onOrderChange={setColumns}
+      onSelect={(col) => {
+          const newColumns = [...columns];
+          const changedColumn = newColumns.find(c => c.key === col.key);
+          if (changedColumn) {
+              changedColumn.isShown = col.isShown;
+          }
+          setColumns(newColumns);
+      }}
+      onSelectAll={(newColumns) => setColumns(newColumns)}
+      onSave={(newColumns) => {
+          setColumns(newColumns);
+          alert('Changes saved!');
+      }}
+      onCancel={() => alert('Changes cancelled!')}
+    />
+  );
+};

packages/module/src/Column/Column.test.tsx

@@ -0,0 +1,77 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import ColumnManagement from './ColumnManagement';
+
+const mockColumns = [
+  { key: 'name', title: 'Name', isShown: true, isShownByDefault: true },
+  { key: 'status', title: 'Status', isShown: true, isShownByDefault: true },
+  { key: 'version', title: 'Version', isShown: false, isShownByDefault: false },
+];
+
+describe('Column', () => {
+  it('renders with initial columns', () => {
+    render(<ColumnManagement columns={mockColumns} />);
+    expect(screen.getByTestId('column-check-name')).toBeChecked();
+    expect(screen.getByTestId('column-check-status')).toBeChecked();
+    expect(screen.getByTestId('column-check-version')).not.toBeChecked();
+  });
+
+  it('renders title and description', () => {
+    render(<ColumnManagement columns={mockColumns} title="Test Title" description="Test Description" />);
+    expect(screen.getByText('Test Title')).toBeInTheDocument();
+    expect(screen.getByText('Test Description')).toBeInTheDocument();
+  });
+
+  it('renders a cancel button', async () => {
+    const onCancel = jest.fn();
+    render(<ColumnManagement columns={mockColumns} onCancel={onCancel} />);
+    const cancelButton = screen.getByText('Cancel');
+    expect(cancelButton).toBeInTheDocument();
+    await userEvent.click(cancelButton);
+    expect(onCancel).toHaveBeenCalled();
+  });
+
+  it('toggles a column', async () => {
+    const onSelect = jest.fn();
+    render(<ColumnManagement columns={mockColumns} onSelect={onSelect} />);
+    const nameCheckbox = screen.getByTestId('column-check-name');
+    await userEvent.click(nameCheckbox);
+    expect(nameCheckbox).not.toBeChecked();
+    expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ key: 'name', isShown: false }));
+  });
+
+  it('selects all columns', async () => {
+    render(<ColumnManagement columns={mockColumns} />);
+    const menuToggle = screen.getByLabelText('Select all').closest('button');
+    if (menuToggle) {
+      await userEvent.click(menuToggle);
+    }
+    const selectAllButton = screen.getByText('Select all');
+    await userEvent.click(selectAllButton);
+    expect(screen.getByTestId('column-check-name')).toBeChecked();
+    expect(screen.getByTestId('column-check-status')).toBeChecked();
+    expect(screen.getByTestId('column-check-version')).toBeChecked();
+  });
+
+  it('selects no columns', async () => {
+    render(<ColumnManagement columns={mockColumns} />);
+    const menuToggle = screen.getByLabelText('Select all').closest('button');
+    if (menuToggle) {
+      await userEvent.click(menuToggle);
+    }
+    const selectNoneButton = screen.getByText('Select none');
+    await userEvent.click(selectNoneButton);
+    expect(screen.getByTestId('column-check-name')).not.toBeChecked();
+    expect(screen.getByTestId('column-check-status')).not.toBeChecked();
+    expect(screen.getByTestId('column-check-version')).not.toBeChecked();
+  });
+
+  it('saves changes', async () => {
+    const onSave = jest.fn();
+    render(<ColumnManagement columns={mockColumns} onSave={onSave} />);
+    const saveButton = screen.getByText('Save');
+    await userEvent.click(saveButton);
+    expect(onSave).toHaveBeenCalledWith(expect.any(Array));
+  });
+});

packages/module/src/Column/index.ts

@@ -23,7 +23,7 @@ import {
   Draggable
 } from '@patternfly/react-core/deprecated';
 
-export interface ColumnColumn {
+export interface Column {
   /** Internal identifier of a column by which table displayed columns are filtered. */
   key: string;
   /** The actual display name of the column possibly with a tooltip or icon. */
@@ -38,29 +38,32 @@ export interface ColumnColumn {
 
 export interface ColumnProps {
   /** Current column state */
-  columns: ColumnColumn[];
+  columns: Column[];
   /* Column description text */
   description?: string;
   /* Column title text */
   title?: string;
   /** Custom OUIA ID */
   ouiaId?: string | number;
   /** Callback when a column is selected or deselected */
-  onSelect?: (column: ColumnColumn) => void;
+  onSelect?: (column: Column) => void;
+  /** Callback when all columns are selected or deselected */
+  onSelectAll?: (columns: Column[]) => void;
   /** Callback when the column order changes */
-  onOrderChange?: (columns: ColumnColumn[]) => void;
+  onOrderChange?: (columns: Column[]) => void;
   /** Callback to save the column state */
-  onSave?: (columns: ColumnColumn[]) => void;
+  onSave?: (columns: Column[]) => void;
   /** Callback to close the modal */
   onCancel?: () => void;
 }
 
-const Column: FunctionComponent<ColumnProps> = (
+const ColumnManagement: FunctionComponent<ColumnProps> = (
   { columns,
     description,
     title,
     ouiaId = 'Column',
     onSelect,
+    onSelectAll,
     onOrderChange,
     onSave,
     onCancel }: ColumnProps) => {
@@ -99,24 +102,23 @@ const Column: FunctionComponent<ColumnProps> = (
 
   const handleSave = () => {
     onSave?.(currentColumns);
-    onCancel?.();
   }
 
-  const onSelectAll = (select = true) => {
+  const handleSelectAll = (select = true) => {
     const newColumns = currentColumns.map(c => ({ ...c, isShown: c.isUntoggleable ? c.isShown : select }));
     setCurrentColumns(newColumns);
-    onOrderChange?.(newColumns);
+    onSelectAll?.(newColumns);
   }
 
   const isAllSelected = () => currentColumns.every(c => c.isShown || c.isUntoggleable);
   const isSomeSelected = () => currentColumns.some(c => c.isShown);
 
   const dropdownItems = [
-    <DropdownItem key="select-all" onClick={() => onSelectAll(true)}>Select all</DropdownItem>,
-    <DropdownItem key="deselect-all" onClick={() => onSelectAll(false)}>Select none</DropdownItem>
+    <DropdownItem key="select-all" onClick={() => handleSelectAll(true)}>Select all</DropdownItem>,
+    <DropdownItem key="deselect-all" onClick={() => handleSelectAll(false)}>Select none</DropdownItem>
   ];
 
-  const content = (
+  return (
     <>
       <Title headingLevel="h3">{title}</Title>
       {description && <div style={{ paddingBottom: '1rem' }}><p>{description}</p></div>}
@@ -146,7 +148,7 @@ const Column: FunctionComponent<ColumnProps> = (
           <DataList aria-label="Selected columns" isCompact data-ouia-component-id={`${ouiaId}-column-list`}>
             {currentColumns.map((column, index) =>
               <Draggable key={column.key} id={column.key}>
-                <DataListItem key={column.key}>
+                <DataListItem key={column.key} data-testid={`column-item-${column.key}`}>
                   <DataListItemRow>
                     <DataListControl>
                       <DataListDragButton
@@ -155,6 +157,7 @@ const Column: FunctionComponent<ColumnProps> = (
                       />
                     </DataListControl>
                     <DataListCheck
+                      data-testid={`column-check-${column.key}`}
                       isChecked={column.isShown}
                       onChange={() => handleChange(index)}
                       isDisabled={column.isUntoggleable}
@@ -188,8 +191,6 @@ const Column: FunctionComponent<ColumnProps> = (
       </div>
     </>
   );
-
-  return content;
 }
 
-export default Column;
+export default ColumnManagement;

packages/module/src/ColumnManagement/ColumnManagement.test.tsx

@@ -0,0 +1,2 @@
+export { default } from './ColumnManagement';
+export * from './ColumnManagement';

packages/module/src/Column/Column.tsx renamed to packages/module/src/ColumnManagement/ColumnManagement.tsx

@@ -72,8 +72,8 @@ export * from './ErrorBoundary';
 export { default as ColumnManagementModal } from './ColumnManagementModal';
 export * from './ColumnManagementModal';
 
-export { default as Column } from './Column';
-export * from './Column';
+export { default as ColumnManagement } from './ColumnManagement';
+export * from './ColumnManagement';
 
 export { default as CloseButton } from './CloseButton';
 export * from './CloseButton';