filters

Author: fhlavac

packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md

@@ -11,7 +11,7 @@ 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
 sortValue: 4
-propComponents: ['DataViewToolbar', 'DataViewTableBasic', 'DataViewTableTree']
+propComponents: ['DataViewToolbar', 'DataViewTableBasic', 'DataViewTableTree', 'DataViewTrTree', 'DataViewTrObject']
 sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md
 ---
 import { Button, EmptyState, EmptyStateActions, EmptyStateBody, EmptyStateFooter, EmptyStateHeader, EmptyStateIcon } from '@patternfly/react-core';
@@ -26,7 +26,7 @@ import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynami
 
 The **data view toolbar** component renders a default opinionated data view toolbar above or below the data section. 
 
-Data view toolbar can contain a `pagination`, `bulkSelect`, `actions` or other children content passed. The preffered way of passing children toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component.
+Data view toolbar can contain a `pagination`, `bulkSelect`, `filters`, `actions` or other children content passed. The preffered way of passing children toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component.
 
 ### Basic toolbar example
 

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/FiltersExample.tsx

@@ -0,0 +1,92 @@
+import React, { useMemo } from 'react';
+import { Pagination } from '@patternfly/react-core';
+import { BrowserRouter, useSearchParams } from 'react-router-dom';
+import { useDataViewFilters, useDataViewPagination } from '@patternfly/react-data-view/dist/dynamic/Hooks';
+import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
+import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
+import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
+import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters';
+import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter';
+
+const perPageOptions = [
+  { title: '5', value: 5 },
+  { title: '10', value: 10 }
+];
+
+interface Repository {
+  name: string;
+  branch: string | null;
+  prs: string | null;
+  workspaces: string;
+  lastCommit: string;
+}
+
+interface RepositoryFilters {
+  name: string,
+  branch: string
+}
+
+const repositories: Repository[] = [
+  { name: 'Repository one', branch: 'Branch one', prs: 'Pull request one', workspaces: 'Workspace one', lastCommit: 'Timestamp one' },
+  { name: 'Repository two', branch: 'Branch two', prs: 'Pull request two', workspaces: 'Workspace two', lastCommit: 'Timestamp two' },
+  { name: 'Repository three', branch: 'Branch three', prs: 'Pull request three', workspaces: 'Workspace three', lastCommit: 'Timestamp three' },
+  { name: 'Repository four', branch: 'Branch four', prs: 'Pull request four', workspaces: 'Workspace four', lastCommit: 'Timestamp four' },
+  { name: 'Repository five', branch: 'Branch five', prs: 'Pull request five', workspaces: 'Workspace five', lastCommit: 'Timestamp five' },
+  { name: 'Repository six', branch: 'Branch six', prs: 'Pull request six', workspaces: 'Workspace six', lastCommit: 'Timestamp six' }
+];
+
+const columns = [ 'Name', 'Branch', 'Pull requests', 'Workspaces', 'Last commit' ];
+
+const ouiaId = 'LayoutExample';
+
+const MyTable: React.FunctionComponent = () => { 
+  const [ searchParams, setSearchParams ] = useSearchParams();
+  const pagination = useDataViewPagination({ perPage: 5 });
+  const { page, perPage } = pagination;
+  const { filters, onSetFilters, clearAllFilters } = useDataViewFilters<RepositoryFilters>({ initialFilters: { name: '', branch: '' }, searchParams, setSearchParams });
+
+  const pageRows = useMemo(() => repositories
+    .filter(item => (!filters.name || item.name?.toLocaleLowerCase().includes(filters.name?.toLocaleLowerCase())) && (!filters.branch || item.branch?.toLocaleLowerCase().includes(filters.branch?.toLocaleLowerCase())))
+    .slice((page - 1) * perPage, ((page - 1) * perPage) + perPage)
+    .map(item => Object.values(item)), [ page, perPage, filters ]);
+
+  return (
+    <DataView>
+      <DataViewToolbar
+        ouiaId='LayoutExampleHeader'
+        clearAllFilters = {clearAllFilters}
+        pagination={
+          <Pagination 
+            perPageOptions={perPageOptions} 
+            itemCount={repositories.length} 
+            {...pagination} 
+          />
+        }
+        filters={ 
+          <DataViewFilters onChange={(_e, values) => onSetFilters(values)} values={filters}>
+            <DataViewTextFilter filterId="name" title='Name' placeholder='Filter by name' />
+            <DataViewTextFilter filterId="branch" title='Branch' placeholder='Filter by branch' />
+          </DataViewFilters>
+        }
+      />
+      <DataViewTable aria-label='Repositories table' ouiaId={ouiaId} columns={columns} rows={pageRows} />
+      <DataViewToolbar
+        ouiaId='LayoutExampleFooter'
+        pagination={
+          <Pagination 
+            isCompact  
+            perPageOptions={perPageOptions} 
+            itemCount={repositories.length} 
+            {...pagination} 
+          />
+        } 
+      />
+    </DataView>
+  );
+}
+
+export const BasicExample: React.FunctionComponent = () => (
+  <BrowserRouter>
+    <MyTable/>
+  </BrowserRouter>
+)

packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md

@@ -14,12 +14,14 @@ sortValue: 3
 sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md
 ---
 import { useMemo } from 'react';
-import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks';
+import { BrowserRouter, useSearchParams } from 'react-router-dom';
+import { useDataViewPagination, useDataViewSelection, useDataViewFilters } from '@patternfly/react-data-view/dist/dynamic/Hooks';
 import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView';
 import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect';
 import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
 import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
-import { BrowserRouter, useSearchParams } from 'react-router-dom';
+import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters';
+import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter';
 
 This is a list of functionality you can use to manage data displayed in the **data view**.
 
@@ -84,3 +86,32 @@ The `useDataViewSelection` hook manages the selection state of the data view.
 ```js file="./SelectionExample.tsx"
 
 ```
+
+# Filters
+Enables filtering of data records in the data view and displays the applied filter chips.
+
+### Toolbar usage
+The data view toolbar can include a set of filters by passing a React node to the `filters` property. You can use predefined components `DataViewFilters` and `DataViewTextFilter` to customize and handle filtering directly in the toolbar. The `DataViewFilters` is a wrapper allowing conditional filtering using multiple attributes. If you need just a single filter, you can use `DataViewTextFilter` or a different filter component alone.
+
+### Filters state
+
+The `useDataViewFilters` hook manages the filter state of the data view. It allows you to define default filter values, synchronize filter state with URL parameters, and handle filter changes efficiently.
+
+**Initial values:**
+- `initialFilters` object with default filter values
+- optional `searchParams` object for managing URL-based filter state
+- optional `setSearchParams` function to update the URL when filters are modified
+
+The `useDataViewFilters` hook works well with the React Router library to support URL-based filtering. Alternatively, you can manage filter state in the URL using `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If no URL parameters are provided, the filter state is managed internally.
+
+**Return values:**
+- `filters` object representing the current filter values
+- `onSetFilters` function to update the filter state
+- `clearAllFilters` function to reset all filters to their initial values
+
+### Filtering example
+This example demonstrates the setup and usage of filters within the data view. It includes text filters for different attributes, the ability to clear all filters, and persistence of filter state in the URL.
+
+```js file="./FiltersExample.tsx"
+
+```

packages/module/src/DataView/DataView.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Stack, StackItem } from '@patternfly/react-core';
+import { Stack, StackItem, StackProps } from '@patternfly/react-core';
 import { DataViewSelection, InternalContextProvider } from '../InternalContext';
 
 export const DataViewState = {
@@ -10,7 +10,8 @@ export const DataViewState = {
 
 export type DataViewState = typeof DataViewState[keyof typeof DataViewState];
 
-export interface DataViewProps {
+/** extends StackProps */
+export interface DataViewProps extends StackProps {
   /** Content rendered inside the data view */
   children: React.ReactNode;
   /** Custom OUIA ID */

packages/module/src/DataViewFilters/DataViewFilters.test.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import DataViewFilters from './DataViewFilters';
+import DataViewToolbar from '../DataViewToolbar';
+import DataViewTextFilter from '../DataViewTextFilter';
+
+describe('DataViewFilters component', () => {
+  const mockOnChange = jest.fn();
+
+  it('should render correctly', () => {
+    const { container } = render(<DataViewToolbar
+      filters={
+        <DataViewFilters onChange={mockOnChange} values={{}}>
+          <DataViewTextFilter filterId="one" title="One" />
+          <DataViewTextFilter filterId="two" title="Two" />
+        </DataViewFilters>
+      }
+    />);
+    expect(container).toMatchSnapshot();
+  });
+});

packages/module/src/DataViewFilters/DataViewFilters.tsx

@@ -0,0 +1,119 @@
+import React, { useMemo, useState, useRef, useEffect, ReactElement } from 'react';
+import {
+  Menu, MenuContent, MenuItem, MenuList, MenuToggle, Popper, ToolbarGroup, ToolbarToggleGroup, ToolbarToggleGroupProps,
+} from '@patternfly/react-core';
+import { FilterIcon } from '@patternfly/react-icons';
+
+// helper interface to generate attribute menu
+interface DataViewFilterIdentifiers {
+  filterId: string;
+  title: string;
+}
+
+/** extends ToolbarToggleGroupProps */
+export interface DataViewFiltersProps<T extends object> extends Omit<ToolbarToggleGroupProps, 'toggleIcon' | 'breakpoint' | 'onChange'> {
+  /** Content rendered inside the data view */
+  children: React.ReactNode;
+  /** Optional onChange callback shared across filters */
+  onChange?: (key: string, newValues: Partial<T>) => void;
+  /** Optional values shared across filters */
+  values?: T;
+  /** Icon for the toolbar toggle group */
+  toggleIcon?: ToolbarToggleGroupProps['toggleIcon'];
+  /** Breakpoint for the toolbar toggle group */
+  breakpoint?: ToolbarToggleGroupProps['breakpoint'];
+  /** Custom OUIA ID */
+  ouiaId?: string;
+};
+
+
+export const DataViewFilters = <T extends object>({
+  children,
+  ouiaId = 'DataViewFilters',
+  toggleIcon = <FilterIcon />,
+  breakpoint = 'xl',
+  onChange,
+  values,
+  ...props
+}: DataViewFiltersProps<T>) => {
+  const [ activeAttributeMenu, setActiveAttributeMenu ] = useState<string>('');
+  const [ isAttributeMenuOpen, setIsAttributeMenuOpen ] = useState(false);
+  const attributeToggleRef = useRef<HTMLButtonElement>(null);
+  const attributeMenuRef = useRef<HTMLDivElement>(null);
+  const attributeContainerRef = useRef<HTMLDivElement>(null);
+
+  const filterItems: DataViewFilterIdentifiers[] = useMemo(() => React.Children.toArray(children)
+    .map(child =>
+      React.isValidElement(child) ? { filterId: String(child.props.filterId), title: String(child.props.title) } : undefined
+    ).filter((item): item is DataViewFilterIdentifiers => !!item), []);  // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    filterItems.length > 0 && setActiveAttributeMenu(filterItems[0].title);
+  }, [ filterItems ]);
+
+  const attributeToggle = (
+    <MenuToggle
+      ref={attributeToggleRef}
+      onClick={() => setIsAttributeMenuOpen(!isAttributeMenuOpen)}
+      isExpanded={isAttributeMenuOpen}
+      icon={toggleIcon}
+    >
+      {activeAttributeMenu}
+    </MenuToggle>
+  );
+
+  const attributeMenu = (
+    <Menu
+      ref={attributeMenuRef}
+      onSelect={(_ev, itemId) => {
+        const selectedItem = filterItems.find(item => item.filterId === itemId);
+        selectedItem && setActiveAttributeMenu(selectedItem.title);
+        setIsAttributeMenuOpen(false);
+      }}
+    >
+      <MenuContent>
+        <MenuList>
+          {filterItems.map(item => (
+            <MenuItem key={item.filterId} itemId={item.filterId}>
+              {item.title}
+            </MenuItem>
+          ))}
+        </MenuList>
+      </MenuContent>
+    </Menu>
+  );
+
+  return (
+    <ToolbarToggleGroup data-ouia-component-id={ouiaId} toggleIcon={toggleIcon} breakpoint={breakpoint} {...props}>
+      <ToolbarGroup variant="filter-group">
+        <div ref={attributeContainerRef}>
+          <Popper
+            trigger={attributeToggle}
+            triggerRef={attributeToggleRef}
+            popper={attributeMenu}
+            popperRef={attributeMenuRef}
+            appendTo={attributeContainerRef.current || undefined}
+            isVisible={isAttributeMenuOpen}
+          />
+        </div>
+        {React.Children.map(children, (child) => (
+          React.isValidElement(child) ? (
+            React.cloneElement(child as ReactElement<{
+              showToolbarItem: boolean;
+              onChange: (_e: unknown, values: unknown) => void;
+              value: unknown;
+            }>, {
+              showToolbarItem: activeAttributeMenu === child.props.title,
+              onChange: (event, value) => onChange?.(event, { [child.props.filterId]: value } as Partial<T>),
+              value: values?.[child.props.filterId],
+              ...child.props
+            })
+          ) : child
+        ))}
+
+      </ToolbarGroup>
+    </ToolbarToggleGroup>
+  );
+};
+
+export default DataViewFilters;