@patternfly/react-data-view 5.4.1 → 5.5.0

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

@@ -11,15 +11,18 @@ 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: 3
+propComponents: ['DataViewFilters', 'DataViewTextFilter']
 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 +87,34 @@ 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. Props of these filter components are listed at the bottom of this page. 
+
+You can decide between passing `value` and `onChange` event to every filter separately or pass `values` and `onChange` to the `DataViewFilters` wrapper which make them available to its children. Props directly passed to child filters have a higher priority than the "inherited" ones. 
+
+### 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"
+
+```

package/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();
+  });
+});

package/src/DataViewFilters/DataViewFilters.tsx

@@ -0,0 +1,125 @@
+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 childrenHash = useMemo(() => JSON.stringify(
+    React.Children.map(children, (child) =>
+      React.isValidElement(child) ? { type: child.type, key: child.key, props: child.props } : child
+    )
+  ), [ children ]);
+
+  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), [ childrenHash ]);  // 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;

package/src/DataViewFilters/__snapshots__/DataViewFilters.test.tsx.snap

@@ -0,0 +1,182 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`DataViewFilters component should render correctly 1`] = `
+<div>
+  <div
+    class="pf-v5-c-toolbar"
+    data-ouia-component-id="DataViewToolbar"
+    data-ouia-component-type="PF5/Toolbar"
+    data-ouia-safe="true"
+    id="pf-random-id-0"
+  >
+    <div
+      class="pf-v5-c-toolbar__content"
+    >
+      <div
+        class="pf-v5-c-toolbar__content-section"
+      >
+        <div
+          class="pf-v5-c-toolbar__item pf-m-search-filter"
+        >
+          <div
+            class="pf-v5-c-toolbar__group pf-m-toggle-group pf-m-show-on-xl"
+            data-ouia-component-id="DataViewFilters"
+          >
+            <div
+              class="pf-v5-c-toolbar__toggle"
+            >
+              <button
+                aria-disabled="false"
+                aria-haspopup="false"
+                aria-label="Show Filters"
+                class="pf-v5-c-button pf-m-plain"
+                data-ouia-component-id="OUIA-Generated-Button-plain-1"
+                data-ouia-component-type="PF5/Button"
+                data-ouia-safe="true"
+                type="button"
+              >
+                <svg
+                  aria-hidden="true"
+                  class="pf-v5-svg"
+                  fill="currentColor"
+                  height="1em"
+                  role="img"
+                  viewBox="0 0 512 512"
+                  width="1em"
+                >
+                  <path
+                    d="M487.976 0H24.028C2.71 0-8.047 25.866 7.058 40.971L192 225.941V432c0 7.831 3.821 15.17 10.237 19.662l80 55.98C298.02 518.69 320 507.493 320 487.98V225.941l184.947-184.97C520.021 25.896 509.338 0 487.976 0z"
+                  />
+                </svg>
+              </button>
+            </div>
+            <div
+              class="pf-v5-c-toolbar__group pf-m-filter-group"
+            >
+              <div>
+                <button
+                  aria-expanded="false"
+                  class="pf-v5-c-menu-toggle"
+                  data-ouia-component-id="OUIA-Generated-MenuToggle-1"
+                  data-ouia-component-type="PF5/MenuToggle"
+                  data-ouia-safe="true"
+                  type="button"
+                >
+                  <span
+                    class="pf-v5-c-menu-toggle__icon"
+                  >
+                    <svg
+                      aria-hidden="true"
+                      class="pf-v5-svg"
+                      fill="currentColor"
+                      height="1em"
+                      role="img"
+                      viewBox="0 0 512 512"
+                      width="1em"
+                    >
+                      <path
+                        d="M487.976 0H24.028C2.71 0-8.047 25.866 7.058 40.971L192 225.941V432c0 7.831 3.821 15.17 10.237 19.662l80 55.98C298.02 518.69 320 507.493 320 487.98V225.941l184.947-184.97C520.021 25.896 509.338 0 487.976 0z"
+                      />
+                    </svg>
+                  </span>
+                  <span
+                    class="pf-v5-c-menu-toggle__text"
+                  >
+                    One
+                  </span>
+                  <span
+                    class="pf-v5-c-menu-toggle__controls"
+                  >
+                    <span
+                      class="pf-v5-c-menu-toggle__toggle-icon"
+                    >
+                      <svg
+                        aria-hidden="true"
+                        class="pf-v5-svg"
+                        fill="currentColor"
+                        height="1em"
+                        role="img"
+                        viewBox="0 0 320 512"
+                        width="1em"
+                      >
+                        <path
+                          d="M31.3 192h257.3c17.8 0 26.7 21.5 14.1 34.1L174.1 354.8c-7.8 7.8-20.5 7.8-28.3 0L17.2 226.1C4.6 213.5 13.5 192 31.3 192z"
+                        />
+                      </svg>
+                    </span>
+                  </span>
+                </button>
+              </div>
+              <div
+                class="pf-v5-c-toolbar__item"
+                data-ouia-component-id="DataViewTextFilter"
+              >
+                <div
+                  class="pf-v5-c-text-input-group"
+                  data-ouia-component-id="DataViewTextFilter-input"
+                >
+                  <div
+                    class="pf-v5-c-text-input-group__main pf-m-icon"
+                  >
+                    <span
+                      class="pf-v5-c-text-input-group__text"
+                    >
+                      <span
+                        class="pf-v5-c-text-input-group__icon"
+                      >
+                        <svg
+                          aria-hidden="true"
+                          class="pf-v5-svg"
+                          fill="currentColor"
+                          height="1em"
+                          role="img"
+                          viewBox="0 0 512 512"
+                          width="1em"
+                        >
+                          <path
+                            d="M505 442.7L405.3 343c-4.5-4.5-10.6-7-17-7H372c27.6-35.3 44-79.7 44-128C416 93.1 322.9 0 208 0S0 93.1 0 208s93.1 208 208 208c48.3 0 92.7-16.4 128-44v16.3c0 6.4 2.5 12.5 7 17l99.7 99.7c9.4 9.4 24.6 9.4 33.9 0l28.3-28.3c9.4-9.4 9.4-24.6.1-34zM208 336c-70.7 0-128-57.2-128-128 0-70.7 57.2-128 128-128 70.7 0 128 57.2 128 128 0 70.7-57.2 128-128 128z"
+                          />
+                        </svg>
+                      </span>
+                      <input
+                        aria-label="One filter"
+                        class="pf-v5-c-text-input-group__text-input"
+                        id="one"
+                        placeholder="Filter by One"
+                        type="text"
+                        value=""
+                      />
+                    </span>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div
+      class="pf-v5-c-toolbar__content pf-m-hidden"
+      hidden=""
+    >
+      <div
+        class="pf-v5-c-toolbar__group"
+      />
+      <div
+        class="pf-v5-c-toolbar__item"
+      >
+        <button
+          aria-disabled="false"
+          class="pf-v5-c-button pf-m-link pf-m-inline"
+          data-ouia-component-id="DataViewToolbar-clear-all-filters"
+          data-ouia-component-type="PF5/Button"
+          data-ouia-safe="true"
+          type="button"
+        >
+          Clear filters
+        </button>
+      </div>
+    </div>
+  </div>
+</div>
+`;

package/src/DataViewFilters/index.tsx

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

package/src/DataViewTable/DataViewTable.tsx

@@ -8,18 +8,38 @@ import { DataViewTableTree, DataViewTableTreeProps } from '../DataViewTableTree'
 import { DataViewTableBasic, DataViewTableBasicProps } from '../DataViewTableBasic';
 
 // Table head typings
-export type DataViewTh = ReactNode | { cell: ReactNode; props?: ThProps };
+export type DataViewTh = ReactNode | {
+  /** Table head cell node */
+  cell: ReactNode;
+  /** Props passed to Th */
+  props?: ThProps
+};
 export const isDataViewThObject = (value: DataViewTh): value is { cell: ReactNode; props?: ThProps } => value != null && typeof value === 'object' && 'cell' in value;
 
 // Basic table typings
-export interface DataViewTrObject { row: DataViewTd[], id?: string, props?: TrProps }
-export type DataViewTd = ReactNode | { cell: ReactNode; props?: TdProps };
+export interface DataViewTrObject {
+  /** Array of rows */
+  row: DataViewTd[],
+  /** Unique identifier of a row */
+  id?: string,
+  /** Props passed to Tr */
+  props?: TrProps
+}
+
+export type DataViewTd = ReactNode | {
+  /** Table body cell node */
+  cell: ReactNode;
+  /** Props passed to Td */
+  props?: TdProps
+};
+
 export type DataViewTr = DataViewTd[] | DataViewTrObject;
 
 export const isDataViewTdObject = (value: DataViewTd): value is { cell: ReactNode; props?: TdProps } => value != null && typeof value === 'object' && 'cell' in value;
 export const isDataViewTrObject = (value: DataViewTr): value is { row: DataViewTd[], id?: string } => value != null && typeof value === 'object' && 'row' in value;
 
 // Tree table typings
+/** extends DataViewTrObject */
 export interface DataViewTrTree extends DataViewTrObject { id: string, children?: DataViewTrTree[] }
 
 export type DataViewTableProps =

package/src/DataViewTableBasic/DataViewTableBasic.tsx

@@ -11,6 +11,7 @@ import { DataViewTableHead } from '../DataViewTableHead';
 import { DataViewTh, DataViewTr, isDataViewTdObject, isDataViewTrObject } from '../DataViewTable';
 import { DataViewState } from '../DataView/DataView';
 
+/** extends TableProps */
 export interface DataViewTableBasicProps extends Omit<TableProps, 'onSelect' | 'rows'> {
   /** Columns definition */
   columns: DataViewTh[];

package/src/DataViewTableHead/DataViewTableHead.tsx

@@ -8,6 +8,7 @@ import {
 import { useInternalContext } from '../InternalContext';
 import { DataViewTh, isDataViewThObject } from '../DataViewTable';
 
+/** extends TheadProps */
 export interface DataViewTableHeadProps extends TheadProps {
   /** Indicates whether table is a tree */
   isTreeTable?: boolean;

package/src/DataViewTableTree/DataViewTableTree.tsx

@@ -30,6 +30,7 @@ const isNodeChecked = (node: DataViewTrTree, isSelected: (node: DataViewTrTree)
   return allSelected;
 };
 
+/** extends TableProps */
 export interface DataViewTableTreeProps extends Omit<TableProps, 'onSelect' | 'rows'> {
   /** Columns definition */
   columns: DataViewTh[];

package/src/DataViewTextFilter/DataViewTextFilter.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import DataViewTextFilter, { DataViewTextFilterProps } from './DataViewTextFilter';
+import DataViewToolbar from '../DataViewToolbar';
+
+describe('DataViewTextFilter component', () => {
+  const mockOnChange = jest.fn();
+
+  const defaultProps: DataViewTextFilterProps = {
+    filterId: 'test-filter',
+    title: 'Test Filter',
+    value: 'initial value',
+    onChange: mockOnChange,
+  };
+
+  it('should render correctly', () => {
+    const { container } = render(<DataViewToolbar
+      filters={ 
+        <DataViewTextFilter {...defaultProps} />
+      }
+    />);
+    expect(container).toMatchSnapshot();
+  });
+});

package/src/DataViewTextFilter/DataViewTextFilter.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { SearchInput, SearchInputProps, ToolbarFilter, ToolbarFilterProps } from '@patternfly/react-core';
+
+/** extends SearchInputProps */
+export interface DataViewTextFilterProps extends SearchInputProps {
+  /** Unique key for the filter attribute */
+  filterId: string;
+  /** Current filter value */
+  value?: string;
+  /** Filter title displayed in the toolbar */
+  title: string;
+  /** Callback for when the input value changes */
+  onChange?: (event: React.FormEvent<HTMLInputElement> | undefined, value: string) => void;
+  /** Controls visibility of the filter in the toolbar */
+  showToolbarItem?: ToolbarFilterProps['showToolbarItem'];
+  /** Trims input value on change */
+  trimValue?: boolean;
+  /** Custom OUIA ID */
+  ouiaId?: string;
+}
+
+export const DataViewTextFilter: React.FC<DataViewTextFilterProps> = ({
+  filterId,
+  title,
+  value = '',
+  onChange,
+  onClear = () => onChange?.(undefined, ''),
+  showToolbarItem,
+  trimValue = true,
+  ouiaId = 'DataViewTextFilter',
+  ...props
+}: DataViewTextFilterProps) => (
+  <ToolbarFilter
+    data-ouia-component-id={ouiaId}
+    chips={value.length > 0 ? [ { key: title, node: value } ] : []}
+    deleteChip={() => onChange?.(undefined, '')}
+    categoryName={title}
+    showToolbarItem={showToolbarItem}
+  >
+    <SearchInput
+      searchInputId={filterId}
+      value={value}
+      onChange={(e, inputValue) => onChange?.(e, trimValue ? inputValue.trim() : inputValue)}
+      onClear={onClear}
+      placeholder={`Filter by ${title}`}
+      aria-label={`${title ?? filterId} filter`}
+      data-ouia-component-id={`${ouiaId}-input`}
+      {...props}
+    />
+  </ToolbarFilter>
+);
+
+export default DataViewTextFilter;