From 66edbaba460e3b4fa61d2185135f3e7377323365 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Wed, 27 Nov 2024 15:59:27 +0100 Subject: [PATCH 01/12] fix(toolbar): move actions after filters --- .../module/src/DataViewToolbar/DataViewToolbar.tsx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/module/src/DataViewToolbar/DataViewToolbar.tsx b/packages/module/src/DataViewToolbar/DataViewToolbar.tsx index 1258528f..9e6b3eec 100644 --- a/packages/module/src/DataViewToolbar/DataViewToolbar.tsx +++ b/packages/module/src/DataViewToolbar/DataViewToolbar.tsx @@ -35,16 +35,16 @@ export const DataViewToolbar: React.FC = ({ className, oui {bulkSelect} )} - {actions && ( - - {actions} - - )} {filters && ( {filters} )} + {actions && ( + + {actions} + + )} {pagination && ( {pagination} From b4aed6b58925ce11e0ae61dd3c050fecd2bde98f Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Tue, 3 Dec 2024 16:55:00 +0100 Subject: [PATCH 02/12] chore: clean up the docs --- .../extensions/data-view/about-data-view.md | 14 -- .../examples/Components/Components.md | 108 -------------- .../AbstractLayoutExample.tsx | 0 .../data-view/examples/DataView/DataView.md | 72 +++++++++ .../EventsExample.tsx | 0 .../PredefinedLayoutExample.tsx | 0 .../examples/EventsContext/EventsContext.md | 33 ----- .../data-view/examples/Layout/Layout.md | 40 ----- .../DataViewTableEmptyExample.tsx | 0 .../DataViewTableErrorExample.tsx | 0 .../DataViewTableExample.tsx | 0 .../DataViewTableLoadingExample.tsx | 0 .../DataViewTableTreeExample.tsx | 0 .../SortingExample.tsx | 0 .../data-view/examples/Table/Table.md | 137 ++++++++++++++++++ .../DataViewToolbarActionsExample.tsx | 0 .../DataViewToolbarExample.tsx | 0 .../FiltersExample.tsx | 0 .../PaginationExample.tsx | 0 .../SelectionExample.tsx | 0 .../Functionality.md => Toolbar/Toolbar.md} | 83 +++++------ 21 files changed, 248 insertions(+), 239 deletions(-) delete mode 100644 packages/module/patternfly-docs/content/extensions/data-view/about-data-view.md delete mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Layout => DataView}/AbstractLayoutExample.tsx (100%) create mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md rename packages/module/patternfly-docs/content/extensions/data-view/examples/{EventsContext => DataView}/EventsExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Layout => DataView}/PredefinedLayoutExample.tsx (100%) delete mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsContext.md delete mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/Layout.md rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Table}/DataViewTableEmptyExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Table}/DataViewTableErrorExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Table}/DataViewTableExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Table}/DataViewTableLoadingExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Table}/DataViewTableTreeExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Functionality => Table}/SortingExample.tsx (100%) create mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Toolbar}/DataViewToolbarActionsExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Components => Toolbar}/DataViewToolbarExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Functionality => Toolbar}/FiltersExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Functionality => Toolbar}/PaginationExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Functionality => Toolbar}/SelectionExample.tsx (100%) rename packages/module/patternfly-docs/content/extensions/data-view/examples/{Functionality/Functionality.md => Toolbar/Toolbar.md} (68%) diff --git a/packages/module/patternfly-docs/content/extensions/data-view/about-data-view.md b/packages/module/patternfly-docs/content/extensions/data-view/about-data-view.md deleted file mode 100644 index 0fd1b95e..00000000 --- a/packages/module/patternfly-docs/content/extensions/data-view/about-data-view.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -section: extensions -subsection: Data view -id: About data view -sortValue: 1 ---- - -Data view lives in its own package [`@patternfly/react-data-view`](https://www.npmjs.com/package/@patternfly/react-data-view) - -# Data view - -The data view extension contains implementation of the data view component allowing to display record data in a configured layout. - -If you notice a bug or have a suggestion for the data view, feel free to file an issue in our [GitHub repository](https://github.com/patternfly/react-data-view/issues)! Please make sure to check if there is already a pre-existing issue before creating a new issue. diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md deleted file mode 100644 index 628ecd3f..00000000 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/Components.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -# Sidenav top-level section -# should be the same for all markdown files -section: extensions -subsection: Data view -# Sidenav secondary level section -# should be the same for all markdown files -id: Components -# 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 -sortValue: 4 -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 } from '@patternfly/react-core'; -import { CubesIcon, FolderIcon, FolderOpenIcon, LeafIcon, ExclamationCircleIcon } from '@patternfly/react-icons'; -import { BulkSelect, ErrorState, ResponsiveAction, ResponsiveActions, SkeletonTableHead, SkeletonTableBody } from '@patternfly/react-component-groups'; -import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; -import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; -import { useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; -import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynamic/DataView'; - -## Data view toolbar - -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`, `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 - -```js file="./DataViewToolbarExample.tsx" - -``` - -# Toolbar actions -Data view toolbar can display actions using the `actions` property accepting a React node. You can make use of a predefined [responsive actions](/extensions/component-groups/responsive-actions) component from the [component groups](/extensions/component-groups/about-component-groups) extension. - -### Actions configuration - -### Actions example - -```js file="./DataViewToolbarActionsExample.tsx" - -``` - -## Data view table - -The **data view table** component renders your columns and rows definition into a [table](/components/table) component. - -### Rows and columns customization - -This example shows possible formats of `rows` and `columns` passed to the `DataViewTable` which allow you various customizations of the table head and body. - -```js file="./DataViewTableExample.tsx" - -``` - -The `DataViewTable` component accepts the following props: - -- `columns` defining the column heads of the table. Each item in the array can be a `ReactNode` (for simple heads) or an object with the following properties: - - `cell` (`ReactNode`) content to display in the column head. - - optional `props` (`ThProps`) to pass to the `` component, such as `width`, `sort`, and other table head cell properties. - -- `rows` defining the rows to be displayed in the table. Each item in the array can be either an array of `DataViewTd` (for simple rows) or an object with the following properties: - - `row` (`DataViewTd[]`) defining the content for each cell in the row. - - optional `id` (`string`) for the row (can be used to match items in selection). - - optional `props` (`TrProps`) to pass to the `` component, such as `isHoverable`, `isRowSelected`, and other table row properties. - -- optional `ouiaId` - -- optional `props` (`TableProps`) that are passed down to the `` component, except for `onSelect`, which is managed internally. - -It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. - -### Tree table example -This example shows the tree table variant with expandable rows, custom icons for leaf and parent nodes. Tree table is turned on by passing `isTreeTable` flag to the `DataViewTable` component. You can pass `collapsedIcon`, `expandedIcon` or `leafIcon` to be displayen rows with given status. The tree table rows have to be defined in a format of object with following keys: - - `row` (`DataViewTd[]`) defining the content for each cell in the row. - - `id` (`string`) for the row (used to match items in selection end expand the rows). - - optional `children` (`DataViewTrTree[]`) defining the children rows. - -It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. - -```js file="./DataViewTableTreeExample.tsx" - -``` - -### Empty state example -The data view table supports displaying a custom empty state. You can pass it using the the `headStates` and `bodyStates` properties and their `empty` key. It will be automatically displayed in case there are no rows to be rendered. - -```js file="./DataViewTableEmptyExample.tsx" - -``` - -### Error state example -The data view table also supports displaying an error state. You can pass it using the the `headStates` and `bodyStates` properties and their `error` key. It will be displayed in case the data view recieves its `state` property set to `error`. - -```js file="./DataViewTableErrorExample.tsx" - -``` - -### Loading state example -The data view table also supports displaying a custom loading state. You can pass it using the `headStates` and `bodyStates` properties and their `loading` key. Your state will be displayed in case the data view recieves its `state` property set to `loading`. - -```js file="./DataViewTableLoadingExample.tsx" - -``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/AbstractLayoutExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/AbstractLayoutExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/AbstractLayoutExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/AbstractLayoutExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md new file mode 100644 index 00000000..5eadc6cc --- /dev/null +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -0,0 +1,72 @@ +--- +section: extensions +subsection: Data view +id: Data view +propComponents: ['DataView'] +sortValue: 1 +sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md +--- +import { useState, useEffect, useRef, useMemo } from 'react'; +import { Drawer, DrawerContent, DrawerContentBody } from '@patternfly/react-core'; +import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; +import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; +import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView'; +import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; +import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; +import { useDataViewEventsContext, DataViewEventsContext, DataViewEventsProvider, EventTypes } from '@patternfly/react-data-view/dist/dynamic/DataViewEventsContext'; + +## Core concepts + +The **data view** extension helps you display datasets in organized layouts containing data representation and toolbars allowing interactions like selection or pagination. + +Sub-components for displaying the data (card view, table) and toolbars (top and bottom) are always passed as `children` to the `DataView` component. + +--- + +**Note:** Data view lives in its own package [`@patternfly/react-data-view`](https://www.npmjs.com/package/@patternfly/react-data-view) + +If you notice a bug, or if you have a suggestion for improving the data view extension or its documentation, please file an issue in [the react-data-view repository](https://github.com/patternfly/react-data-view/issues). Before doing so, please make sure there is not already a pre-existing issue. + +--- + +### Layout + +Data view is expected to consist of header, data representation part and footer stacked below each other. The layout is implemented using PatternFly [stack](/layouts/stack). + +```js file="./AbstractLayoutExample.tsx" + +``` + +### Modularity + +The extension's modular architecture lets you efficiently create consistent data views by using predefined sub-components and hooks or defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. + +For the toolbar, you can make use of the predefined `DataViewToolbar` component, which extends the PatternFly [toolbar](/components/toolbar) with the most common use cases. For more details, please refer to the [Toolbar](/extensions/data-view/toolbar) section. In case it does not fit your needs, you can also use your custom toolbar component. + +Data can be presented using the predefined `DataViewTable` component, which is an abstraction above the PatternFly [table](/components/table). For more details, please refer to the [Table](/extensions/data-view/table) docs section. In the near future, we are also planning to introduce a predefined Card view component. If you have more specific needs to display data, you can pass your custom implementation as a `DataView` child. + +```js file="./PredefinedLayoutExample.tsx" + +``` + +## Advanced concepts + +This section contains advanced features related to the `DataView` wrapping component and information to better understand how the data view works under the hood. + +### Data view context + +The **data view internal context** provides shared state to all sub-components. It lives inside the `DataView` component to store callbacks for the data selection (`onSelect`, `isSelected`, `isSelectDisabled`), internally computed `isSelectable` flag based on selection callbacks passed, and `activeState` of the data view (loading, error, etc.). Its values are set up through props of the `DataView` component. + +### Events context + +The **data view events context** provides a way of listening to the data view events from the outside of the component through the `DataViewEventsContext`. + +In order to give your components an access to the shared context, wrap them and your data view with the `DataViewEventsProvider`. + +### Row click subscription example +This example illustrates how to set up a layout that listens for row click events and displays detailed information about the selected row in a [drawer component](/components/drawer). + + +```js file="./EventsExample.tsx" + +``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/EventsExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/EventsExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/PredefinedLayoutExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/PredefinedLayoutExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsContext.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsContext.md deleted file mode 100644 index 293a1a0c..00000000 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsContext.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -# Sidenav top-level section -# should be the same for all markdown files -section: extensions -subsection: Data view -# Sidenav secondary level section -# should be the same for all markdown files -id: Events context -# 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 -sortValue: 3 -sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/EventsContext/EventsContext.md ---- -import { useState, useEffect, useRef, useMemo } from 'react'; -import { Table, Tbody, Th, Thead, Tr, Td } from '@patternfly/react-table'; -import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView'; -import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; -import { useDataViewEventsContext, DataViewEventsContext, DataViewEventsProvider, EventTypes } from '@patternfly/react-data-view/dist/dynamic/DataViewEventsContext'; -import { useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; -import { Drawer, DrawerContent, DrawerContentBody } from '@patternfly/react-core'; - -The **data view events context** provides a way of listening to the data view events from the outside of the component. - -### Row click subscription example -The following example demonstrates how to use the `DataViewEventsContext` to manage shared state and handle events. The `DataViewEventsProvider` is used to wrap components that need access to the shared context. This example illustrates how to set up a layout that listens for data view row click events and displays detailed information about the selected row in a [drawer component](/components/drawer). - - -```js file="./EventsExample.tsx" - -``` - diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/Layout.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/Layout.md deleted file mode 100644 index 13c892d3..00000000 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/Layout.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -# Sidenav top-level section -# should be the same for all markdown files -section: extensions -subsection: Data view -# Sidenav secondary level section -# should be the same for all markdown files -id: Layout -# 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 -sortValue: 2 -propComponents: ['DataView', 'DataViewState'] -sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Layout/Layout.md ---- -import { useMemo } from 'react'; -import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; -import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; -import DataView from '@patternfly/react-data-view/dist/dynamic/DataView'; -import DataViewToolbar from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; -import DataViewTable from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; - -The **data view** component renders record data in a configured layout. - -### Layout example - -Data view is expected to consist of header, data part and footer stacked below each other and passed as `children`. - -```js file="./AbstractLayoutExample.tsx" - -``` - -### Predefined layout components - -You can make use of the predefined layout components to display a default header and footer. See [data view toolbar](/extensions/data-view/components#dataviewtoolbar) for more information - -```js file="./PredefinedLayoutExample.tsx" - -``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableEmptyExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableEmptyExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableEmptyExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableEmptyExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableErrorExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableErrorExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableErrorExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableErrorExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableLoadingExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableLoadingExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableLoadingExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableLoadingExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableTreeExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableTreeExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewTableTreeExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/DataViewTableTreeExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/SortingExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/SortingExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/SortingExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Table/SortingExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md new file mode 100644 index 00000000..a1f48218 --- /dev/null +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md @@ -0,0 +1,137 @@ +--- +# Sidenav top-level section +# should be the same for all markdown files +section: extensions +subsection: Data view +# Sidenav secondary level section +# should be the same for all markdown files +id: Table +# 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 +sortValue: 3 +propComponents: ['DataViewTableBasic', 'DataViewTableTree', 'DataViewTrTree', 'DataViewTrObject'] +sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md +--- +import { useMemo } from 'react'; +import { BrowserRouter, useSearchParams } from 'react-router-dom'; +import { Button, EmptyState, EmptyStateActions, EmptyStateBody, EmptyStateFooter, EmptyStateHeader, EmptyStateIcon } from '@patternfly/react-core'; +import { CubesIcon, FolderIcon, FolderOpenIcon, LeafIcon, ExclamationCircleIcon } from '@patternfly/react-icons'; +import { ErrorState, ResponsiveAction, ResponsiveActions, SkeletonTableHead, SkeletonTableBody } from '@patternfly/react-component-groups'; +import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; +import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; +import { useDataViewSelection, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; +import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynamic/DataView'; + +## Data view table + +The **data view table** component is an abstraction that renders your columns and rows in the PatternFly [table](/components/table) component. + +Below, you can see an example of displaying `rows` and `columns` in the `DataViewTable`, which simplifies the table declaration, but at the same time keeps the customization possibilities of the core component. + +### Customized table example +```js file="./DataViewTableExample.tsx" + +``` + +The `DataViewTable` component accepts the following props: + +- `columns` defining the column heads of the table. Each item in the array can be a `ReactNode` (for simple heads) or an object with the following properties: + - `cell` (`ReactNode`) content to display in the column head. + - optional `props` (`ThProps`) to pass to the `` component, such as `isHoverable`, `isRowSelected`, and other table row properties. + +- optional `ouiaId` + +- optional `props` (`TableProps`) that are passed down to the `
` component, such as `width`, `sort`, and other table head cell properties. + +- `rows` defining the rows to be displayed in the table. Each item in the array can be either an array of `DataViewTd` (for simple rows) or an object with the following properties: + - `row` (`DataViewTd[]`) defining the content for each cell in the row. + - optional `id` (`string`) for the row (can be used to match items in selection). + - optional `props` (`TrProps`) to pass to the `
` component, except for `onSelect`, which is managed internally. + +It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. + +## Tree table + +Instead of a basic table, your data view can use a tree table variant, with expandable rows and custom icons for leaf and parent nodes. + +To enable a tree table, pass the `isTreeTable` flag to the `` component. + +Pass `collapsedIcon`, `expandedIcon`, and `leafIcon` to ``, to align a row's icon to its state. + +Tree table rows have to be defined in a format of object with following keys: + - `row` (`DataViewTd[]`) defining the content for each cell in the row. + - `id` (`string`) for the row (used to match items in selection end expand the rows). + - optional `children` (`DataViewTrTree[]`) defining the children rows. + +It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. + +### Tree table example +```js file="./DataViewTableTreeExample.tsx" + +``` + +## Sorting + +The `useDataViewSort` hook manages the sorting state of a data view. It provides an easy way to handle sorting logic, including synchronization with URL parameters and defining default sorting behavior. + +**Initial values:** +- `initialSort` object to set default `sortBy` and `direction` values: + - `sortBy`: key of the initial column to sort. + - `direction`: default sorting direction (`asc` or `desc`). +- Optional `searchParams` object to manage URL-based synchronization of sort state. +- Optional `setSearchParams` function to update the URL parameters when sorting changes. +- `defaultDirection` to set the default direction when no direction is specified. +- Customizable parameter names for the URL: + - `sortByParam`: name of the URL parameter for the column key. + - `directionParam`: name of the URL parameter for the sorting direction. + +The `useDataViewSort` hook integrates seamlessly with React Router to manage sort state via URL parameters. Alternatively, you can use `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If URL synchronization is not configured, the sort state is managed internally within the component. + +**Return values:** +- `sortBy`: key of the column currently being sorted. +- `direction`: current sorting direction (`asc` or `desc`). +- `onSort`: function to handle sorting changes programmatically or via user interaction. + +### Sorting example + +The following example demonstrates how to set up and use sorting functionality within a data view. The implementation includes dynamic sorting by column with persistence of sort state in the URL using React Router. +```js file="./SortingExample.tsx" + +``` + +## States + +The data view table allows you to react to the `activeState` property passed to the data view (`loading`, `error`, `empty`, etc.). You can use `headStates` and `bodyStates` props to define table head and body applicable to given state. Below, you can see examples of the most common use cases. + +### Empty +When there is no data to render in the data view, you can instead display an empty state. + +You can create your error state by using the PatternFly [empty state](/components/empty-state) component. To render the empty state, pass the component under `empty` key to `headStates` or `bodyStates`. + +```js file="./DataViewTableEmptyExample.tsx" + +``` + +### Error +When there is a data connection or retrieval error, you can display an error state. + +You can create your error state by using the [error state](/component-groups/error-state) component from the [component groups](/extensions/component-groups/about-component-groups) extension or PatternFly [empty state](/components/empty-state) component. To render the error state, pass the component under `error` key to `headStates` or `bodyStates`. + +The error state will be displayed when the data view `activeState` value is `error`. + +```js file="./DataViewTableErrorExample.tsx" + +``` + +### Loading +To indicate that data is loading, you can display a loading state. + +You can create your loading state by using the [skeleton table](/component-groups/skeleton-table) from the [component groups](/extensions/component-groups/about-component-groups)extension or customized PatternFly [empty state](/components/empty-state) component. To render the loading state, pass the component under `loading` key to `headStates` or `bodyStates`. + +The loading state will be displayed when the data view `activeState` value is `loading`. + +```js file="./DataViewTableLoadingExample.tsx" + +``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewToolbarActionsExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarActionsExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewToolbarActionsExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarActionsExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewToolbarExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Components/DataViewToolbarExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/FiltersExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/FiltersExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/FiltersExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/FiltersExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/PaginationExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/PaginationExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/PaginationExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/PaginationExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/SelectionExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/SelectionExample.tsx similarity index 100% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/SelectionExample.tsx rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/SelectionExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md similarity index 68% rename from packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md rename to packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index 3e263c56..c1b5cd34 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -5,30 +5,56 @@ section: extensions subsection: Data view # Sidenav secondary level section # should be the same for all markdown files -id: Functionality +id: Toolbar # 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 -sortValue: 3 -propComponents: ['DataViewFilters', 'DataViewTextFilter', 'DataViewCheckboxFilter'] -sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Functionality/Functionality.md +sortValue: 2 +propComponents: ['DataViewToolbar', 'DataViewFilters', 'DataViewTextFilter', 'DataViewCheckboxFilter'] +sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md --- import { useMemo } from 'react'; import { BrowserRouter, useSearchParams } from 'react-router-dom'; -import { useDataViewPagination, useDataViewSelection, useDataViewFilters, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; +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 { BulkSelect, BulkSelectValue, ErrorState, ResponsiveAction, ResponsiveActions, SkeletonTableHead, SkeletonTableBody } from '@patternfly/react-component-groups'; import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters'; import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewCheckboxFilter'; -This is a list of functionality you can use to manage data displayed in the **data view**. +## Data view toolbar -# Pagination -Allows to display data records on multiple pages and display the pagination state. +The **data view toolbar** component renders a default opinionated data view toolbar above or below the data section. + +Data view toolbar can contain pagination, bulk select, filters, actions or other child content passed. The preffered way of passing child toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component or predefined `DataViewToolbar` props for specific use cases. + +You can further customize toolbar interactions by referring to the additional documentation: +- [Actions](#toolbar-actions) +- [Pagination](#pagination) +- [Selection](#selection) +- [Filters](#filters) + +### Basic toolbar example + +```js file="./DataViewToolbarExample.tsx" + +``` + +## Toolbar actions +To support additional user needs, you can pass relevant actions to the toolbar via `actions`. Add standard PatternFly actions (like buttons) or choose predefined [responsive actions](/component-groups/responsive-actions) which ensure the responsive behavior of multiple actions in one toolbar. + +### Actions example + +```js file="./DataViewToolbarActionsExample.tsx" + +``` + +## Pagination + +Helps users navigate data records that span multiple pages. ### Toolbar usage Data view toolbar can display a pagination using the `pagination` property accepting a React node. You can also pass a custom `ouiaId` for testing purposes. @@ -43,7 +69,7 @@ The `useDataViewPagination` hook manages the pagination state of the data view. - optional `searchParams` object - optional `setSearchParams` function -While the hook works seamlessly with React Router library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage. +While the hook works seamlessly with the React Router library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage. You can also pass custom `pageParam` or `perPageParam` names, renaming the pagination parameters in the URL. @@ -60,7 +86,7 @@ The retrieved values are named to match the PatternFly [pagination](/components/ ``` -# Selection +## Selection Allows to select data records inside the data view and show the selection state. ### Toolbar usage @@ -87,8 +113,8 @@ The `useDataViewSelection` hook manages the selection state of the data view. ``` -# Filters -Enables filtering of data records in the data view and displays the applied filter labels. +## 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`, `DataViewTextFilter` and `DataViewCheckboxFilter` 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`, `DataViewCheckboxFilter` or a different filter component alone. Props of these filter components are listed at the bottom of this page. @@ -117,34 +143,3 @@ This example demonstrates the setup and usage of filters within the data view. I ```js file="./FiltersExample.tsx" ``` - -### Sort state - -The `useDataViewSort` hook manages the sorting state of a data view. It provides an easy way to handle sorting logic, including synchronization with URL parameters and defining default sorting behavior. - -**Initial values:** -- `initialSort` object to set default `sortBy` and `direction` values: - - `sortBy`: key of the initial column to sort. - - `direction`: default sorting direction (`asc` or `desc`). -- Optional `searchParams` object to manage URL-based synchronization of sort state. -- Optional `setSearchParams` function to update the URL parameters when sorting changes. -- `defaultDirection` to set the default direction when no direction is specified. -- Customizable parameter names for the URL: - - `sortByParam`: name of the URL parameter for the column key. - - `directionParam`: name of the URL parameter for the sorting direction. - -The `useDataViewSort` hook integrates seamlessly with React Router to manage sort state via URL parameters. Alternatively, you can use `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If URL synchronization is not configured, the sort state is managed internally within the component. - -**Return values:** -- `sortBy`: key of the column currently being sorted. -- `direction`: current sorting direction (`asc` or `desc`). -- `onSort`: function to handle sorting changes programmatically or via user interaction. - -### Sorting example - -This example demonstrates how to set up and use sorting functionality within a data view. The implementation includes dynamic sorting by column with persistence of sort state in the URL using React Router. - - -```js file="./SortingExample.tsx" - -``` From 622590ccad55e6b8164ad5246ef65b98cf592186 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Tue, 3 Dec 2024 16:54:38 +0100 Subject: [PATCH 03/12] chore: update PF versions --- package-lock.json | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/package-lock.json b/package-lock.json index 7de73eef..467c2bae 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4281,6 +4281,15 @@ "react-dom": "^17 || ^18" } }, + "node_modules/@patternfly/react-core/node_modules/focus-trap": { + "version": "7.6.0", + "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.0.tgz", + "integrity": "sha512-1td0l3pMkWJLFipobUcGaf+5DTY4PLDDrcqoSaKP8ediO/CoWCCYk/fT/Y2A4e6TNB+Sh6clRJCjOPPnKoNHnQ==", + "license": "MIT", + "dependencies": { + "tabbable": "^6.2.0" + } + }, "node_modules/@patternfly/react-data-view": { "resolved": "packages/module", "link": true From d9673880cabb1880ccc14d0a2b75572540142258 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Wed, 4 Dec 2024 14:07:12 +0100 Subject: [PATCH 04/12] feat: enhance toolbar and data view examples to cover all features --- .../data-view/examples/DataView/DataView.md | 10 +- .../DataView/PredefinedLayoutExample.tsx | 89 ------ .../DataView/PredefinedLayoutFullExample.tsx | 276 ++++++++++++++++++ .../Toolbar/DataViewToolbarExample.tsx | 26 +- .../data-view/examples/Toolbar/Toolbar.md | 2 +- 5 files changed, 305 insertions(+), 98 deletions(-) delete mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx create mode 100644 packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md index 5eadc6cc..9962305b 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -8,12 +8,16 @@ sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/mod --- import { useState, useEffect, useRef, useMemo } from 'react'; import { Drawer, DrawerContent, DrawerContentBody } from '@patternfly/react-core'; -import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; -import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; +import { CubesIcon } from '@patternfly/react-icons'; +import { useDataViewPagination, useDataViewSelection, useDataViewFilters, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; +import { BulkSelect, BulkSelectValue, ErrorState, ResponsiveAction, ResponsiveActions, SkeletonTableHead, SkeletonTableBody } from '@patternfly/react-component-groups'; import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView'; import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; import { useDataViewEventsContext, DataViewEventsContext, DataViewEventsProvider, EventTypes } from '@patternfly/react-data-view/dist/dynamic/DataViewEventsContext'; +import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters'; +import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; +import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewCheckboxFilter'; ## Core concepts @@ -45,7 +49,7 @@ For the toolbar, you can make use of the predefined `DataViewToolbar` component, Data can be presented using the predefined `DataViewTable` component, which is an abstraction above the PatternFly [table](/components/table). For more details, please refer to the [Table](/extensions/data-view/table) docs section. In the near future, we are also planning to introduce a predefined Card view component. If you have more specific needs to display data, you can pass your custom implementation as a `DataView` child. -```js file="./PredefinedLayoutExample.tsx" +```js file="./PredefinedLayoutFullExample.tsx" ``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx deleted file mode 100644 index 7381f544..00000000 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutExample.tsx +++ /dev/null @@ -1,89 +0,0 @@ -import React, { useMemo } from 'react'; -import { Pagination } from '@patternfly/react-core'; -import { useDataViewPagination, useDataViewSelection } from '@patternfly/react-data-view/dist/dynamic/Hooks'; -import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; -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'; - -const perPageOptions = [ - { title: '5', value: 5 }, - { title: '10', value: 10 } -]; - -interface Repository { - name: string; - branches: string | null; - prs: string | null; - workspaces: string; - lastCommit: string; -} - -const repositories: Repository[] = [ - { name: 'Repository one', branches: 'Branch one', prs: 'Pull request one', workspaces: 'Workspace one', lastCommit: 'Timestamp one' }, - { name: 'Repository two', branches: 'Branch two', prs: 'Pull request two', workspaces: 'Workspace two', lastCommit: 'Timestamp two' }, - { name: 'Repository three', branches: 'Branch three', prs: 'Pull request three', workspaces: 'Workspace three', lastCommit: 'Timestamp three' }, - { name: 'Repository four', branches: 'Branch four', prs: 'Pull request four', workspaces: 'Workspace four', lastCommit: 'Timestamp four' }, - { name: 'Repository five', branches: 'Branch five', prs: 'Pull request five', workspaces: 'Workspace five', lastCommit: 'Timestamp five' }, - { name: 'Repository six', branches: 'Branch six', prs: 'Pull request six', workspaces: 'Workspace six', lastCommit: 'Timestamp six' } -]; - -const rows = repositories.map(item => Object.values(item)); - -const columns = [ 'Repositories', 'Branches', 'Pull requests', 'Workspaces', 'Last commit' ]; - -const ouiaId = 'LayoutExample'; - -export const BasicExample: React.FunctionComponent = () => { - const pagination = useDataViewPagination({ perPage: 5 }); - const { page, perPage } = pagination; - const selection = useDataViewSelection({ matchOption: (a, b) => a[0] === b[0] }); - const { selected, onSelect, isSelected } = selection; - - const pageRows = useMemo(() => rows.slice((page - 1) * perPage, ((page - 1) * perPage) + perPage), [ page, perPage ]); - - const handleBulkSelect = (value: BulkSelectValue) => { - value === BulkSelectValue.none && onSelect(false); - value === BulkSelectValue.all && onSelect(true, rows); - value === BulkSelectValue.nonePage && onSelect(false, pageRows); - value === BulkSelectValue.page && onSelect(true, pageRows); - }; - - return ( - - isSelected(item))} - pagePartiallySelected={pageRows.some(item => isSelected(item)) && !pageRows.every(item => isSelected(item))} - onSelect={handleBulkSelect} - /> - } - pagination={ - - } - /> - - - } - /> - - ); -} \ No newline at end of file diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx new file mode 100644 index 00000000..b9bf759d --- /dev/null +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx @@ -0,0 +1,276 @@ +/* eslint-disable no-nested-ternary */ +import React, { useEffect, useState, useRef, useMemo } from 'react'; +import { Drawer, DrawerActions, DrawerCloseButton, DrawerContent, DrawerContentBody, DrawerHead, DrawerPanelContent, Title, Text, EmptyState, EmptyStateHeader, EmptyStateBody, EmptyStateFooter, EmptyStateActions, Button, EmptyStateIcon } from '@patternfly/react-core'; +import { ActionsColumn, Tbody, Td, ThProps, Tr } from '@patternfly/react-table'; +import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; +import { Pagination } from '@patternfly/react-core'; +import { DataView } from '@patternfly/react-data-view/dist/dynamic/DataView'; +import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; +import { DataViewTable, DataViewTh } from '@patternfly/react-data-view/dist/dynamic/DataViewTable'; +import { DataViewEventsProvider, EventTypes, useDataViewEventsContext } from '@patternfly/react-data-view/dist/dynamic/DataViewEventsContext'; +import { useDataViewPagination, useDataViewSelection, useDataViewFilters, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; +import { ResponsiveAction, ResponsiveActions } from '@patternfly/react-component-groups'; +import { DataViewFilterOption, DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters'; +import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; +import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewCheckboxFilter'; +import { CubesIcon } from '@patternfly/react-icons'; + +const perPageOptions = [ + { title: '5', value: 5 }, + { title: '10', value: 10 } +]; + +interface Repository { + name: string; + branch: string | null; + prs: string | null; + workspace: string; + lastCommit: string; +}; + +interface RepositoryFilters { + name: string, + branch: string, + workspace: string[] +}; + +const repositories: Repository[] = [ + { name: 'Repository one', branch: 'Branch one', prs: 'Pull request one', workspace: 'Workspace one', lastCommit: 'Timestamp one' }, + { name: 'Repository two', branch: 'Branch two', prs: 'Pull request two', workspace: 'Workspace two', lastCommit: 'Timestamp two' }, + { name: 'Repository three', branch: 'Branch three', prs: 'Pull request three', workspace: 'Workspace three', lastCommit: 'Timestamp three' }, + { name: 'Repository four', branch: 'Branch four', prs: 'Pull request four', workspace: 'Workspace four', lastCommit: 'Timestamp four' }, + { name: 'Repository five', branch: 'Branch five', prs: 'Pull request five', workspace: 'Workspace five', lastCommit: 'Timestamp five' }, + { name: 'Repository six', branch: 'Branch six', prs: 'Pull request six', workspace: 'Workspace six', lastCommit: 'Timestamp six' } +]; + +const filterOptions: DataViewFilterOption[] = [ + { label: 'Workspace one', value: 'workspace-one' }, + { label: 'Workspace two', value: 'workspace-two' }, + { label: 'Workspace three', value: 'workspace-three' } +]; + +const COLUMNS = [ + { label: 'Repository', key: 'name', index: 0 }, + { label: 'Branch', key: 'branches', index: 1 }, + { label: 'Pull request', key: 'prs', index: 2 }, + { label: 'Workspace', key: 'workspaces', index: 3 }, + { label: 'Last commit', key: 'lastCommit', index: 4 } +]; + +const ouiaId = 'LayoutExample'; + +const sortData = (data: Repository[], sortBy: string | undefined, direction: 'asc' | 'desc' | undefined) => + sortBy && direction + ? [ ...data ].sort((a, b) => + direction === 'asc' + ? a[sortBy] < b[sortBy] ? -1 : a[sortBy] > b[sortBy] ? 1 : 0 + : a[sortBy] > b[sortBy] ? -1 : a[sortBy] < b[sortBy] ? 1 : 0 + ) + : data; + +const empty = ( + + + + + +); + +interface RepositoryDetailProps { + selectedRepo?: Repository; + setSelectedRepo: React.Dispatch>; +} + +const RepositoryDetail: React.FunctionComponent = ({ selectedRepo, setSelectedRepo }) => { + const context = useDataViewEventsContext(); + + useEffect(() => { + const unsubscribe = context.subscribe(EventTypes.rowClick, (repo: Repository) => { + setSelectedRepo(repo); + }); + + return () => unsubscribe(); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, []); + + return ( + + + + Detail of {selectedRepo?.name} + + Branch: {selectedRepo?.branch} + Pull requests: {selectedRepo?.prs} + Workspace: {selectedRepo?.workspace} + Last commit: {selectedRepo?.lastCommit} + + setSelectedRepo(undefined)} data-ouia-component-id="detail-drawer-close-btn"/> + + + + ); +}; + +interface RepositoriesTableProps { + selectedRepo?: Repository; +} + +const rowActions = [ + { + title: 'Some action', + onClick: () => console.log('clicked on Some action') // eslint-disable-line no-console + }, + { + title:
Another action
, + onClick: () => console.log('clicked on Another action') // eslint-disable-line no-console + }, + { + isSeparator: true + }, + { + title: 'Third action', + onClick: () => console.log('clicked on Third action') // eslint-disable-line no-console + } +]; + +const RepositoriesTable: React.FunctionComponent = ({ selectedRepo = undefined }) => { + const { filters, onSetFilters, clearAllFilters } = useDataViewFilters({ initialFilters: { name: '', branch: '', workspace: [] } }); + + const pagination = useDataViewPagination({ perPage: 5 }); + const { page, perPage } = pagination; + + const selection = useDataViewSelection({ matchOption: (a, b) => a[0] === b[0] }); + const { selected, onSelect, isSelected } = selection; + + const { trigger } = useDataViewEventsContext(); + + const { sortBy, direction, onSort } = useDataViewSort(); + const sortByIndex = useMemo(() => COLUMNS.findIndex(item => item.key === sortBy), [ sortBy ]); + const getSortParams = (columnIndex: number): ThProps['sort'] => ({ + sortBy: { + index: sortByIndex, + direction, + defaultDirection: 'asc' + }, + onSort: (_event, index, direction) => onSort(_event, COLUMNS[index].key, direction), + columnIndex + }); + + const columns: DataViewTh[] = COLUMNS.map((column, index) => ({ + cell: column.label, + props: { sort: getSortParams(index) } + })); + + const finalData = useMemo(() => sortData(repositories, sortBy, direction).filter(item => + (!filters.name || item.name?.toLocaleLowerCase().includes(filters.name?.toLocaleLowerCase())) && + (!filters.branch || item.branch?.toLocaleLowerCase().includes(filters.branch?.toLocaleLowerCase())) && + (!filters.workspace || filters.workspace.length === 0 || filters.workspace.includes(String(filterOptions.find(option => option.label === item.workspace)?.value))) + ), [ filters, sortBy, direction ]); + + const pageRows = useMemo(() => { + const handleRowClick = (event, repo: Repository | undefined) => { + // prevents drawer toggle on actions or checkbox click + (event.target.matches('td') || event.target.matches('tr')) && trigger(EventTypes.rowClick, repo); + }; + + return finalData.map(repo => ({ + row: [ ...Object.values(repo), { cell: , props: { isActionCell: true } } ], + props: { + isClickable: true, + onRowClick: (event) => handleRowClick(event, selectedRepo?.name === repo.name ? undefined : repo), + isRowSelected: selectedRepo?.name === repo.name + } + })).slice((page - 1) * perPage, ((page - 1) * perPage) + perPage); + }, [ selectedRepo?.name, trigger, page, perPage, finalData ]); + + const handleBulkSelect = (value: BulkSelectValue) => { + value === BulkSelectValue.none && onSelect(false); + value === BulkSelectValue.nonePage && onSelect(false, pageRows); + value === BulkSelectValue.page && onSelect(true, pageRows); + }; + + return ( + 0 ? undefined : 'empty'}> + isSelected(item))} + pagePartiallySelected={pageRows.some(item => isSelected(item)) && !pageRows.every(item => isSelected(item))} + onSelect={handleBulkSelect} + /> + } + filters={ + onSetFilters(values)} values={filters}> + + + + + } + actions={ + + Add repository + Delete repository + + } + pagination={ + + } + /> + + + } + /> + + ); +}; + +export const BasicExample: React.FunctionComponent = () => { + const [ selectedRepo, setSelectedRepo ] = useState(); + const drawerRef = useRef(null); + + return ( + + drawerRef.current?.focus()} data-ouia-component-id="detail-drawer" > + } + > + + + + + + + ); +}; diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx index 2827aab8..0b65a34e 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/DataViewToolbarExample.tsx @@ -1,20 +1,36 @@ +/* eslint-disable no-console */ import React from 'react'; import { Pagination } from '@patternfly/react-core'; import { BulkSelect } from '@patternfly/react-component-groups'; -import DataViewToolbar from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; - +import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; +import { ResponsiveAction, ResponsiveActions } from '@patternfly/react-component-groups'; +import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataViewFilters'; +import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; export const BasicExample: React.FunctionComponent = () => ( console.log('clearAllFilters called')} bulkSelect={ null} + onSelect={() => console.log('onSelect called')} /> } - pagination={ - + filters={ + console.log('onSetFilters calles')} values={{}}> + + + } + actions={ + + Add repository + Delete repository + + } + pagination={ + + } /> ) diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index c1b5cd34..ede16b3e 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -37,7 +37,7 @@ You can further customize toolbar interactions by referring to the additional do - [Selection](#selection) - [Filters](#filters) -### Basic toolbar example +### Toolbar example ```js file="./DataViewToolbarExample.tsx" From de7c8fecc07ccbe5753f545fe36ca5b6c6869739 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Thu, 5 Dec 2024 12:22:50 +0100 Subject: [PATCH 05/12] chore: improve docs per review comments --- cypress/e2e/DataView.spec.cy.ts | 30 +++++++--------- .../data-view/examples/DataView/DataView.md | 35 ++++++++----------- .../data-view/examples/Table/Table.md | 3 +- .../data-view/examples/Toolbar/Toolbar.md | 3 +- 4 files changed, 29 insertions(+), 42 deletions(-) diff --git a/cypress/e2e/DataView.spec.cy.ts b/cypress/e2e/DataView.spec.cy.ts index 99db58b3..e53ff8c9 100644 --- a/cypress/e2e/DataView.spec.cy.ts +++ b/cypress/e2e/DataView.spec.cy.ts @@ -1,17 +1,19 @@ describe('Test the Data view docs page', () => { - + it('displays a layout with a table and paginates', () => { const ouiaId = 'LayoutExample'; + cy.viewport(1400, 2800) cy.visit('http://localhost:8006/extensions/data-view/layout'); + cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).scrollIntoView().contains('Repository'); cy.get(`[data-ouia-component-id="${ouiaId}Header-pagination"]`).should('exist'); cy.get(`[data-ouia-component-id="${ouiaId}Header-bulk-select"]`).should('exist'); cy.get(`[data-ouia-component-id="${ouiaId}Footer-pagination"]`).should('exist'); cy.get(`[data-ouia-component-id="${ouiaId}Footer-bulk-select"]`).should('not.exist'); - cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).contains('Repositories'); + cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).contains('Repository'); cy.get(`[data-ouia-component-id="${ouiaId}-th-4"]`).contains('Last commit'); cy.get(`[data-ouia-component-id="${ouiaId}-td-0-0"]`).contains('Repository one'); @@ -34,26 +36,20 @@ describe('Test the Data view docs page', () => { cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('be.checked')}); cy.contains('5 selected').should('exist'); - // select none - cy.get(`[data-ouia-component-id="BulkSelect-toggle"`).first().click({ force: true }); - cy.get(`[data-ouia-component-id="BulkSelect-select-none"`).first().click(); - cy.contains('5 selected').should('not.exist'); - - // select all - cy.get(`[data-ouia-component-id="BulkSelect-toggle"`).first().click({ force: true }); - cy.get(`[data-ouia-component-id="BulkSelect-select-all"`).first().click(); - cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('be.checked')}); - cy.contains('6 selected').should('exist'); - // page checkbox deselect cy.get(`[data-ouia-component-id="BulkSelect-checkbox"`).first().click(); - cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('not.be.checked')}); - cy.contains('1 selected').should('exist'); + cy.get('[data-ouia-component-id="LayoutExample"] input[type="checkbox"]') + .each(($checkbox) => { + cy.wrap($checkbox).should('not.be.checked'); + }); // select page cy.get(`[data-ouia-component-id="BulkSelect-toggle"`).first().click({ force: true }); cy.get(`[data-ouia-component-id="BulkSelect-select-page"`).first().click(); - cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('be.checked')}); - cy.contains('6 selected').should('exist'); + cy.get('[data-ouia-component-id="LayoutExample"] input[type="checkbox"]') + .each(($checkbox) => { + cy.wrap($checkbox).should('be.checked'); + }); + cy.contains('5 selected').should('exist'); }) }); \ No newline at end of file diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md index 9962305b..12431ec1 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -1,7 +1,8 @@ --- section: extensions subsection: Data view -id: Data view +id: Overview +title: Data view overview propComponents: ['DataView'] sortValue: 1 sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -19,23 +20,19 @@ import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataVi import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewCheckboxFilter'; -## Core concepts - -The **data view** extension helps you display datasets in organized layouts containing data representation and toolbars allowing interactions like selection or pagination. - -Sub-components for displaying the data (card view, table) and toolbars (top and bottom) are always passed as `children` to the `DataView` component. - ---- - **Note:** Data view lives in its own package [`@patternfly/react-data-view`](https://www.npmjs.com/package/@patternfly/react-data-view) -If you notice a bug, or if you have a suggestion for improving the data view extension or its documentation, please file an issue in [the react-data-view repository](https://github.com/patternfly/react-data-view/issues). Before doing so, please make sure there is not already a pre-existing issue. +If you notice a bug, or if you have a suggestion for improving the data view extension or its documentation, please file an issue in the [react-data-view](https://github.com/patternfly/react-data-view/issues) repository. Before doing so, please make sure there is not already a pre-existing issue. --- +The **data view** extension helps you display datasets in organized layouts containing data representation and toolbars allowing interactions like selection or pagination. + ### Layout -Data view is expected to consist of header, data representation part and footer stacked below each other. The layout is implemented using PatternFly [stack](/layouts/stack). +A data view should contain a header, the data representation (like a card view or table), and a footer. These parts are organized in a [stack layout](/layouts/stack). + +The data view toolbars and sub-components that display the data (like a card view or table) are always passed as `children` to the `` component. ```js file="./AbstractLayoutExample.tsx" @@ -43,11 +40,11 @@ Data view is expected to consist of header, data representation part and footer ### Modularity -The extension's modular architecture lets you efficiently create consistent data views by using predefined sub-components and hooks or defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. +The extension's modular architecture lets you efficiently create consistent data views, by either using predefined sub-components and hooks, or by defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. -For the toolbar, you can make use of the predefined `DataViewToolbar` component, which extends the PatternFly [toolbar](/components/toolbar) with the most common use cases. For more details, please refer to the [Toolbar](/extensions/data-view/toolbar) section. In case it does not fit your needs, you can also use your custom toolbar component. +The `` component extends the [PatternFly toolbar](/components/toolbar) to support the most common needs. For more details, refer to the [data view toolbar](/extensions/data-view/toolbar) examples. You can also use a custom toolbar component if needed for your use case. -Data can be presented using the predefined `DataViewTable` component, which is an abstraction above the PatternFly [table](/components/table). For more details, please refer to the [Table](/extensions/data-view/table) docs section. In the near future, we are also planning to introduce a predefined Card view component. If you have more specific needs to display data, you can pass your custom implementation as a `DataView` child. +Data can be presented using the predefined `` component, which is an abstraction above the [PatternFly table](/components/table). For more details, refer to the [data view table](/extensions/data-view/table) examples. If you have more specific data display needs, you can pass a custom implementation as a `` child. In the near future, we are also planning to introduce a predefined card view component. ```js file="./PredefinedLayoutFullExample.tsx" @@ -55,17 +52,13 @@ Data can be presented using the predefined `DataViewTable` component, which is a ## Advanced concepts -This section contains advanced features related to the `DataView` wrapping component and information to better understand how the data view works under the hood. - -### Data view context - -The **data view internal context** provides shared state to all sub-components. It lives inside the `DataView` component to store callbacks for the data selection (`onSelect`, `isSelected`, `isSelectDisabled`), internally computed `isSelectable` flag based on selection callbacks passed, and `activeState` of the data view (loading, error, etc.). Its values are set up through props of the `DataView` component. +This section contains advanced features related to the `` wrapping component and information to better understand how the data view works under the hood. ### Events context -The **data view events context** provides a way of listening to the data view events from the outside of the component through the `DataViewEventsContext`. +The `` provides a method of listening to the data view events from the outside of the component. -In order to give your components an access to the shared context, wrap them and your data view with the `DataViewEventsProvider`. +In order to give your other UI components access to the shared context, wrap them and your data view with the ``. ### Row click subscription example This example illustrates how to set up a layout that listens for row click events and displays detailed information about the selected row in a [drawer component](/components/drawer). diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md index a1f48218..d6dd2ef3 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md @@ -6,6 +6,7 @@ subsection: Data view # Sidenav secondary level section # should be the same for all markdown files id: Table +title: Data view table # 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 @@ -24,8 +25,6 @@ import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataView import { useDataViewSelection, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynamic/DataView'; -## Data view table - The **data view table** component is an abstraction that renders your columns and rows in the PatternFly [table](/components/table) component. Below, you can see an example of displaying `rows` and `columns` in the `DataViewTable`, which simplifies the table declaration, but at the same time keeps the customization possibilities of the core component. diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index ede16b3e..bed524f1 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -6,6 +6,7 @@ subsection: Data view # Sidenav secondary level section # should be the same for all markdown files id: Toolbar +title: Data view toolbar # 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 @@ -25,8 +26,6 @@ import { DataViewFilters } from '@patternfly/react-data-view/dist/dynamic/DataVi import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter'; import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewCheckboxFilter'; -## Data view toolbar - The **data view toolbar** component renders a default opinionated data view toolbar above or below the data section. Data view toolbar can contain pagination, bulk select, filters, actions or other child content passed. The preffered way of passing child toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component or predefined `DataViewToolbar` props for specific use cases. From e8e6bb0c0792ab5b3947c29b5b87a28d1c248f76 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Fri, 6 Dec 2024 14:41:49 +0100 Subject: [PATCH 06/12] fix: fix URL in e2e tests --- cypress/e2e/DataView.spec.cy.ts | 2 +- cypress/e2e/DataViewEvents.spec.cy.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cypress/e2e/DataView.spec.cy.ts b/cypress/e2e/DataView.spec.cy.ts index e53ff8c9..80ef0a8a 100644 --- a/cypress/e2e/DataView.spec.cy.ts +++ b/cypress/e2e/DataView.spec.cy.ts @@ -4,7 +4,7 @@ describe('Test the Data view docs page', () => { const ouiaId = 'LayoutExample'; cy.viewport(1400, 2800) - cy.visit('http://localhost:8006/extensions/data-view/layout'); + cy.visit('http://localhost:8006/extensions/data-view/overview'); cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).scrollIntoView().contains('Repository'); cy.get(`[data-ouia-component-id="${ouiaId}Header-pagination"]`).should('exist'); diff --git a/cypress/e2e/DataViewEvents.spec.cy.ts b/cypress/e2e/DataViewEvents.spec.cy.ts index b3035e08..b8104f84 100644 --- a/cypress/e2e/DataViewEvents.spec.cy.ts +++ b/cypress/e2e/DataViewEvents.spec.cy.ts @@ -3,7 +3,7 @@ describe('Test the Data view docs page', () => { it('displays a table and opens detail', () => { const ouiaId = 'ContextExample'; - cy.visit('http://localhost:8006/extensions/data-view/events-context'); + cy.visit('http://localhost:8006/extensions/data-view/overview'); cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).contains('Repositories'); cy.get(`[data-ouia-component-id="${ouiaId}-th-4"]`).contains('Last commit'); From ad81a7973b7c02ec0acfc63c334b49830fec7754 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Mon, 9 Dec 2024 14:49:22 +0100 Subject: [PATCH 07/12] fix: add more wording changes --- .../data-view/examples/DataView/DataView.md | 20 ++-- .../data-view/examples/Table/Table.md | 102 +++++++++--------- .../data-view/examples/Toolbar/Toolbar.md | 41 ++++--- 3 files changed, 75 insertions(+), 88 deletions(-) diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md index 12431ec1..0cc3e971 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -26,11 +26,11 @@ If you notice a bug, or if you have a suggestion for improving the data view ext --- -The **data view** extension helps you display datasets in organized layouts containing data representation and toolbars allowing interactions like selection or pagination. +The **data view** extension enables you to display datasets in organized layouts, with data representations and interactive toolbars for actions like selection and pagination. ### Layout -A data view should contain a header, the data representation (like a card view or table), and a footer. These parts are organized in a [stack layout](/layouts/stack). +A data view should contain a header, the data representation, and a footer. These parts are organized in a [stack layout](/layouts/stack). The data view toolbars and sub-components that display the data (like a card view or table) are always passed as `children` to the `` component. @@ -40,7 +40,7 @@ The data view toolbars and sub-components that display the data (like a card vie ### Modularity -The extension's modular architecture lets you efficiently create consistent data views, by either using predefined sub-components and hooks, or by defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. +The extension's modular architecture lets you efficiently create consistent data views, either by using predefined sub-components and hooks or by defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. The `` component extends the [PatternFly toolbar](/components/toolbar) to support the most common needs. For more details, refer to the [data view toolbar](/extensions/data-view/toolbar) examples. You can also use a custom toolbar component if needed for your use case. @@ -50,18 +50,12 @@ Data can be presented using the predefined `` component, which is ``` -## Advanced concepts +## Events context -This section contains advanced features related to the `` wrapping component and information to better understand how the data view works under the hood. +The `` component is an advanced feature that enables external listening of data view events. In order to share data view context with your other UI components, both your components and your data view should be wrapped with the ``. This is demonstrated in the following example. -### Events context - -The `` provides a method of listening to the data view events from the outside of the component. - -In order to give your other UI components access to the shared context, wrap them and your data view with the ``. - -### Row click subscription example -This example illustrates how to set up a layout that listens for row click events and displays detailed information about the selected row in a [drawer component](/components/drawer). +### Row click subscription +This example uses the `` to display details about a selected row in a [drawer component](/components/drawer). ```js file="./EventsExample.tsx" diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md index d6dd2ef3..0e63e62d 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md @@ -25,101 +25,94 @@ import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataView import { useDataViewSelection, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynamic/DataView'; -The **data view table** component is an abstraction that renders your columns and rows in the PatternFly [table](/components/table) component. +The **data view table** component renders your data into columns and rows within a [PatternFly table](/components/table) component. You can easily customize and configure the table by adjusting the properties listed at the bottom of this page. -Below, you can see an example of displaying `rows` and `columns` in the `DataViewTable`, which simplifies the table declaration, but at the same time keeps the customization possibilities of the core component. +## Configuring rows and columns +Below is a detailed description of properties used to define rows and columns for your table: +- `columns`: Defines the column heads of the table. Each item in the array can be a `ReactNode` for simple heads, or an object with the following properties: + - `cell`: Content to display in the column head. + - `props` (optional): (`ThProps`) to pass to the `` component, such as `isHoverable`, `isRowSelected`, and other table row properties. -### Customized table example +It is also possible to disable row selection using the `isSelectDisabled` function, which can be passed to the wrapping `DataView` component through the `selection`. + +### Table example ```js file="./DataViewTableExample.tsx" ``` -The `DataViewTable` component accepts the following props: - -- `columns` defining the column heads of the table. Each item in the array can be a `ReactNode` (for simple heads) or an object with the following properties: - - `cell` (`ReactNode`) content to display in the column head. - - optional `props` (`ThProps`) to pass to the `` component, such as `isHoverable`, `isRowSelected`, and other table row properties. - -- optional `ouiaId` - -- optional `props` (`TableProps`) that are passed down to the `
+ + } /> + There are no matching data to be displayed. + + + + + + + + + + +
` component, such as `width`, `sort`, and other table head cell properties. +- `rows`: Defines the rows to be displayed in the table. Each item in the array can be either an array of `DataViewTd` for simple rows, or an object with the following properties: + - `row`: Content to display in each cell in the row. + - `id` (optional): Unique identifier for the row that's used for matching selected items. + - `props` (optional): (`TrProps`) to pass to the `
` component, such as `width`, `sort`, and other table head cell properties. - -- `rows` defining the rows to be displayed in the table. Each item in the array can be either an array of `DataViewTd` (for simple rows) or an object with the following properties: - - `row` (`DataViewTd[]`) defining the content for each cell in the row. - - optional `id` (`string`) for the row (can be used to match items in selection). - - optional `props` (`TrProps`) to pass to the `
` component, except for `onSelect`, which is managed internally. - -It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. - ## Tree table -Instead of a basic table, your data view can use a tree table variant, with expandable rows and custom icons for leaf and parent nodes. +A tree table includes expandable rows and custom icons for leaf and parent nodes. +To enable a tree table, pass the `isTreeTable` flag to the `` component. -To enable a tree table, pass the `isTreeTable` flag to the `` component. -Pass `collapsedIcon`, `expandedIcon`, and `leafIcon` to ``, to align a row's icon to its state. +Tree table rows have to be defined with following keys: + - `row`: Defines the content for each cell in the row. + - `id`: Unique identifier for the row that's used for matching selected items. + - `children` (optional): Defines the children rows. -Tree table rows have to be defined in a format of object with following keys: - - `row` (`DataViewTd[]`) defining the content for each cell in the row. - - `id` (`string`) for the row (used to match items in selection end expand the rows). - - optional `children` (`DataViewTrTree[]`) defining the children rows. +To update a row's icon to reflect its expansion state, pass `collapsedIcon`, `expandedIcon`, and `leafIcon` to ``. -It is also possible to disable row selection using the `isSelectDisabled` function passed to the wrapping data view component through `selection`. +To disable row selection, pass the `isSelectDisabled` function to `selection` prop of the wrapping `` component . ### Tree table example + ```js file="./DataViewTableTreeExample.tsx" ``` ## Sorting +The following example demonstrates how to enable sorting functionality within a data view. This implementation support dynamic sorting by column and persists the sort state in the page's URL via [React Router](https://reactrouter.com/). + +### Sorting example +```js file="./SortingExample.tsx" + +``` +### useDataViewSort hook The `useDataViewSort` hook manages the sorting state of a data view. It provides an easy way to handle sorting logic, including synchronization with URL parameters and defining default sorting behavior. **Initial values:** - `initialSort` object to set default `sortBy` and `direction` values: - - `sortBy`: key of the initial column to sort. - - `direction`: default sorting direction (`asc` or `desc`). -- Optional `searchParams` object to manage URL-based synchronization of sort state. -- Optional `setSearchParams` function to update the URL parameters when sorting changes. -- `defaultDirection` to set the default direction when no direction is specified. + - `sortBy`: Key of the initial column to sort. + - `direction`: Default sorting direction (`asc` or `desc`). +- `searchParams` (optional): Object to manage URL-based synchronization of sort state. +- `setSearchParams` (optional): Function to update the URL parameters when sorting changes. +- `defaultDirection`: Used to set the default direction when no direction is specified. - Customizable parameter names for the URL: - - `sortByParam`: name of the URL parameter for the column key. - - `directionParam`: name of the URL parameter for the sorting direction. - -The `useDataViewSort` hook integrates seamlessly with React Router to manage sort state via URL parameters. Alternatively, you can use `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If URL synchronization is not configured, the sort state is managed internally within the component. + - `sortByParam`: Name of the URL parameter for the column key. + - `directionParam`: Name of the URL parameter for the sorting direction. +The `useDataViewSort` hook integrates seamlessly with [React Router](https://reactrouter.com/) to manage the sort state via URL parameters. Alternatively, you can use `URLSearchParams` and `window.history.pushState` APIs, or other routing libraries. If URL synchronization is not configured, the sort state is managed internally within the component. **Return values:** -- `sortBy`: key of the column currently being sorted. -- `direction`: current sorting direction (`asc` or `desc`). -- `onSort`: function to handle sorting changes programmatically or via user interaction. - -### Sorting example - -The following example demonstrates how to set up and use sorting functionality within a data view. The implementation includes dynamic sorting by column with persistence of sort state in the URL using React Router. -```js file="./SortingExample.tsx" - -``` +- `sortBy`: Key of the column currently being sorted. +- `direction`: Current sorting direction (`asc` or `desc`). +- `onSort`: Function to handle sorting changes programmatically or via user interaction. ## States -The data view table allows you to react to the `activeState` property passed to the data view (`loading`, `error`, `empty`, etc.). You can use `headStates` and `bodyStates` props to define table head and body applicable to given state. Below, you can see examples of the most common use cases. +The data view table allows you to react to the `activeState` property passed to the data view (such as `empty`, `error`, `loading`). You can use the `headStates` and `bodyStates` props to define the table head and body for a given state. ### Empty When there is no data to render in the data view, you can instead display an empty state. -You can create your error state by using the PatternFly [empty state](/components/empty-state) component. To render the empty state, pass the component under `empty` key to `headStates` or `bodyStates`. +You can create your error state by using a [PatternFly empty state](/components/empty-state). To render the empty state, pass the component under `empty` key to `headStates` or `bodyStates`. ```js file="./DataViewTableEmptyExample.tsx" ``` ### Error -When there is a data connection or retrieval error, you can display an error state. - -You can create your error state by using the [error state](/component-groups/error-state) component from the [component groups](/extensions/component-groups/about-component-groups) extension or PatternFly [empty state](/components/empty-state) component. To render the error state, pass the component under `error` key to `headStates` or `bodyStates`. +When there is a data connection or retrieval error, you can display an error state. The error state will be displayed when the data view `activeState` value is `error`. +You can create your error state by either using the [component groups extension's error state](/component-groups/error-state) or a [PatternFly empty state](/components/empty-state) component. To render the error state, pass the component under `error` key to `headStates` or `bodyStates`. + ```js file="./DataViewTableErrorExample.tsx" ``` @@ -127,10 +120,11 @@ The error state will be displayed when the data view `activeState` value is `err ### Loading To indicate that data is loading, you can display a loading state. -You can create your loading state by using the [skeleton table](/component-groups/skeleton-table) from the [component groups](/extensions/component-groups/about-component-groups)extension or customized PatternFly [empty state](/components/empty-state) component. To render the loading state, pass the component under `loading` key to `headStates` or `bodyStates`. - The loading state will be displayed when the data view `activeState` value is `loading`. +You can create your loading state by either using the [component groups extension's skeleton table](/component-groups/skeleton-table) or a customized [PatternFly empty state](/components/empty-state). To render the loading state, pass the component under the `loading` key to `headStates` or `bodyStates`. + + ```js file="./DataViewTableLoadingExample.tsx" ``` diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index bed524f1..8f7c194e 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -28,7 +28,7 @@ import { DataViewCheckboxFilter } from '@patternfly/react-data-view/dist/dynamic The **data view toolbar** component renders a default opinionated data view toolbar above or below the data section. -Data view toolbar can contain pagination, bulk select, filters, actions or other child content passed. The preffered way of passing child toolbar items is using the [toolbar item](/components/toolbar#toolbar-items) component or predefined `DataViewToolbar` props for specific use cases. +Data view toolbar can contain pagination, bulk select, filters, actions, or other custom child content. To pass child items to the toolbar, use the [toolbar item](/components/toolbar#toolbar-items) component or predefined `` props for specific use cases. You can further customize toolbar interactions by referring to the additional documentation: - [Actions](#toolbar-actions) @@ -53,10 +53,9 @@ To support additional user needs, you can pass relevant actions to the toolbar v ## Pagination -Helps users navigate data records that span multiple pages. +To help users navigate data records that span multiple pages, add pagination support to your toolbar. -### Toolbar usage -Data view toolbar can display a pagination using the `pagination` property accepting a React node. You can also pass a custom `ouiaId` for testing purposes. +The data view toolbar can display a pagination using the `pagination` prop. You can also pass a custom `ouiaId` for testing purposes to the toolbar. You can also persist pagination values in the URL, to make it easier to share or bookmark specific pages of your data. ### Pagination state @@ -64,39 +63,40 @@ The `useDataViewPagination` hook manages the pagination state of the data view. **Initial values:** - `perPage` initial value -- optional `page` initial value -- optional `searchParams` object -- optional `setSearchParams` function +- Optional `page` initial value +- Optional `searchParams` object +- Optional `setSearchParams` function While the hook works seamlessly with the React Router library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage. You can also pass custom `pageParam` or `perPageParam` names, renaming the pagination parameters in the URL. -The retrieved values are named to match the PatternFly [pagination](/components/pagination) component props, so you can easily spread them to the component. +The retrieved values are named to match the PatternFly pagination component props. **Return values:** -- current `page` number +- Current `page` number - `onSetPage` to modify current page -- items `perPage` value +- Items `perPage` value - `onPerPageSelect` to modify per page value ### Pagination example +This example uses the URL to persist the pagination state. + ```js file="./PaginationExample.tsx" ``` ## Selection -Allows to select data records inside the data view and show the selection state. +To allow users to select data records inside the data view, add selection support that displays a row's selection state. -### Toolbar usage -Data view toolbar can display a bulk selection component using the `bulkSelect` property accepting a React node. You can make use of a predefined [bulk select](/extensions/component-groups/bulk-select) component from the [component groups](/extensions/component-groups/about-component-groups) extension. +The data view toolbar can display a bulk selection component using bulkSelect. You can make use of a predefined [component group extension bulk select](/extensions/component-groups/bulk-select) component. ### Selection state The `useDataViewSelection` hook manages the selection state of the data view. **Initial values:** -- optional `initialSelected` array of record's identifiers selected by default +- Optional `initialSelected` array of record's identifiers selected by default - `matchOption` function to check if given record is selected *When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array.* @@ -113,12 +113,11 @@ The `useDataViewSelection` hook manages the selection state of the data view. ``` ## Filters -Enables filtering of data records in the data view and displays the applied filter chips. +To allow users to filter data records in the data view, add filtering support that 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`, `DataViewTextFilter` and `DataViewCheckboxFilter` 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`, `DataViewCheckboxFilter` or a different filter component alone. Props of these filter components are listed at the bottom of this page. +The data view toolbar can include a set of filters by passing a React node to the `filters` property. You can use the predefined components ``, ``, and `` to customize and handle filtering directly in the toolbar. The `` component is a wrapper that allows conditional filtering using multiple attributes. If you need just a single filter, you can use ``, ``, 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. +You can either pass a `value` and `onChange` event to every filter separately, or you can pass `values` and `onChange` to the `` wrapper, which makes them available to its children. Props directly passed to child filters have a higher priority than the "inherited" ones. ### Filters state @@ -126,10 +125,10 @@ The `useDataViewFilters` hook manages the filter state of the data view. It allo **Initial values:** - `initialFilters` object with default filter values (if the filter param allows multiple values, pass an array) -- optional `searchParams` object for managing URL-based filter state -- optional `setSearchParams` function to update the URL when filters are modified +- 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. +The `useDataViewFilters` hook works well with the React Router library to support URL-based filtering. Alternatively, you can manage the 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 From 7885c74415c7a5e728f83d953d32446f61243b61 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Tue, 10 Dec 2024 15:03:36 +0100 Subject: [PATCH 08/12] chore: clean Toolbar.md --- .../data-view/examples/Toolbar/Toolbar.md | 49 +++++++++---------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index 8f7c194e..e81f5ff0 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -62,22 +62,22 @@ The data view toolbar can display a pagination using the `pagination` prop. You The `useDataViewPagination` hook manages the pagination state of the data view. **Initial values:** -- `perPage` initial value -- Optional `page` initial value -- Optional `searchParams` object -- Optional `setSearchParams` function +- `perPage` initial value. +- Optional `page` initial value. +- Optional `searchParams` object. +- Optional `setSearchParams` function. -While the hook works seamlessly with the React Router library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage. +While the hook works seamlessly with the [React Router](https://reactrouter.com/) library, you do not need to use it to take advantage of URL persistence. The `searchParams` and `setSearchParams` props can be managed using native browser APIs (`URLSearchParams` and `window.history.pushState`) or any other routing library of your choice. If you don't pass these two props, the pagination state will be stored internally without the URL usage. You can also pass custom `pageParam` or `perPageParam` names, renaming the pagination parameters in the URL. The retrieved values are named to match the PatternFly pagination component props. **Return values:** -- Current `page` number -- `onSetPage` to modify current page -- Items `perPage` value -- `onPerPageSelect` to modify per page value +- Current `page` number. +- `onSetPage` to modify current page. +- Items `perPage` value. +- `onPerPageSelect` to modify per page value. ### Pagination example This example uses the URL to persist the pagination state. @@ -89,22 +89,21 @@ This example uses the URL to persist the pagination state. ## Selection To allow users to select data records inside the data view, add selection support that displays a row's selection state. -The data view toolbar can display a bulk selection component using bulkSelect. You can make use of a predefined [component group extension bulk select](/extensions/component-groups/bulk-select) component. +The data view toolbar can display a bulk selection component by using the predefined [component group extension bulk select](/extensions/component-groups/bulk-select) component. ### Selection state The `useDataViewSelection` hook manages the selection state of the data view. **Initial values:** -- Optional `initialSelected` array of record's identifiers selected by default -- `matchOption` function to check if given record is selected - -*When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array.* +- Optional `initialSelected` array of record's identifiers selected by default. +- `matchOption` function to check if given record is selected. + - When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array. **Return values:** -- `selected` array of currently selected records -- `isSelected` function returning the selection state for given record -- `onSelect` callback to modify the selection state and accepting `isSelecting` flag indicating if records are changing to selected or deselected and `items` containing affected records +- `selected` array of currently selected records. +- `isSelected` function returning the selection state for given record. +- `onSelect` callback to modify the selection state and accepting `isSelecting` flag indicating if records are changing to selected or deselected and `items` containing affected records. ### Selection example @@ -115,7 +114,7 @@ The `useDataViewSelection` hook manages the selection state of the data view. ## Filters To allow users to filter data records in the data view, add filtering support that displays the applied filter chips. -The data view toolbar can include a set of filters by passing a React node to the `filters` property. You can use the predefined components ``, ``, and `` to customize and handle filtering directly in the toolbar. The `` component is a wrapper that allows conditional filtering using multiple attributes. If you need just a single filter, you can use ``, ``, or a different filter component alone. Props of these filter components are listed at the bottom of this page. +The data view toolbar can include a set of filters by passing a React node to the `filters` property. You can use the predefined components ``, ``, and `` to customize and handle filtering directly in the toolbar. The `` component is a wrapper that allows conditional filtering using multiple attributes. If you need just a single filter, you can use ``, ``, or a different filter component alone. Props of these filter components are listed in the [props section of this page](#props). You can either pass a `value` and `onChange` event to every filter separately, or you can pass `values` and `onChange` to the `` wrapper, which makes them available to its children. Props directly passed to child filters have a higher priority than the "inherited" ones. @@ -124,16 +123,16 @@ You can either pass a `value` and `onChange` event to every filter separately, o 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 (if the filter param allows multiple values, pass an array) -- Optional `searchParams` object for managing URL-based filter state -- Optional `setSearchParams` function to update the URL when filters are modified +- `initialFilters` object with default filter values (if the filter param allows multiple values, pass an array). +- 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 the 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. +The `useDataViewFilters` hook works well with the [React Router](https://reactrouter.com/) library to support URL-based filtering. Alternatively, you can manage the 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 +- `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. From 36dc8f33d9c31996c55ac0475a92b11c57d91fa2 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Tue, 10 Dec 2024 16:24:07 +0100 Subject: [PATCH 09/12] chore: update lock file --- package-lock.json | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/package-lock.json b/package-lock.json index 467c2bae..ce4a0eb9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4281,15 +4281,6 @@ "react-dom": "^17 || ^18" } }, - "node_modules/@patternfly/react-core/node_modules/focus-trap": { - "version": "7.6.0", - "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.0.tgz", - "integrity": "sha512-1td0l3pMkWJLFipobUcGaf+5DTY4PLDDrcqoSaKP8ediO/CoWCCYk/fT/Y2A4e6TNB+Sh6clRJCjOPPnKoNHnQ==", - "license": "MIT", - "dependencies": { - "tabbable": "^6.2.0" - } - }, "node_modules/@patternfly/react-data-view": { "resolved": "packages/module", "link": true @@ -12590,14 +12581,6 @@ "readable-stream": "^2.3.6" } }, - "node_modules/focus-trap": { - "version": "7.6.2", - "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.2.tgz", - "integrity": "sha512-9FhUxK1hVju2+AiQIDJ5Dd//9R2n2RAfJ0qfhF4IHGHgcoEUTMpbTeG/zbEuwaiYXfuAH6XE0/aCyxDdRM+W5w==", - "dependencies": { - "tabbable": "^6.2.0" - } - }, "node_modules/follow-redirects": { "version": "1.5.10", "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.5.10.tgz", @@ -36699,14 +36682,6 @@ "readable-stream": "^2.3.6" } }, - "focus-trap": { - "version": "7.6.2", - "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.2.tgz", - "integrity": "sha512-9FhUxK1hVju2+AiQIDJ5Dd//9R2n2RAfJ0qfhF4IHGHgcoEUTMpbTeG/zbEuwaiYXfuAH6XE0/aCyxDdRM+W5w==", - "requires": { - "tabbable": "^6.2.0" - } - }, "follow-redirects": { "version": "1.5.10", "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.5.10.tgz", @@ -45309,8 +45284,7 @@ } }, "tabbable": { - "version": "6.2.0", - "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", + "version": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", "integrity": "sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==" }, "tapable": { From c2202a73a3746f9c10bbf1822620bdca41729853 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Wed, 11 Dec 2024 10:00:30 +0100 Subject: [PATCH 10/12] chore: add final docs cleanup changes --- .../data-view/examples/DataView/DataView.md | 4 ++-- .../data-view/examples/Table/Table.md | 20 +++++++++---------- .../data-view/examples/Toolbar/Toolbar.md | 10 +++++----- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md index 0cc3e971..1642e572 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/DataView.md @@ -40,7 +40,7 @@ The data view toolbars and sub-components that display the data (like a card vie ### Modularity -The extension's modular architecture lets you efficiently create consistent data views, either by using predefined sub-components and hooks or by defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. +The extension's modular architecture lets you efficiently create consistent data views, either by using predefined sub-components and hooks, or by defining your own. You can choose the tools that suit your needs and easily replace any part with a custom implementation. The `` component extends the [PatternFly toolbar](/components/toolbar) to support the most common needs. For more details, refer to the [data view toolbar](/extensions/data-view/toolbar) examples. You can also use a custom toolbar component if needed for your use case. @@ -54,7 +54,7 @@ Data can be presented using the predefined `` component, which is The `` component is an advanced feature that enables external listening of data view events. In order to share data view context with your other UI components, both your components and your data view should be wrapped with the ``. This is demonstrated in the following example. -### Row click subscription +### Row click subscription example This example uses the `` to display details about a selected row in a [drawer component](/components/drawer). diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md index 0e63e62d..bc813e54 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md @@ -25,10 +25,10 @@ import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataView import { useDataViewSelection, useDataViewSort } from '@patternfly/react-data-view/dist/dynamic/Hooks'; import { DataView, DataViewState } from '@patternfly/react-data-view/dist/dynamic/DataView'; -The **data view table** component renders your data into columns and rows within a [PatternFly table](/components/table) component. You can easily customize and configure the table by adjusting the properties listed at the bottom of this page. +The **data view table** component renders your data into columns and rows within a [PatternFly table](/components/table) component. You can easily customize and configure the table with these additional [data view components and props](/extensions/data-view/table#props). ## Configuring rows and columns -Below is a detailed description of properties used to define rows and columns for your table: +To define rows and columns for your table, use these props: - `columns`: Defines the column heads of the table. Each item in the array can be a `ReactNode` for simple heads, or an object with the following properties: - `cell`: Content to display in the column head. - `props` (optional): (`ThProps`) to pass to the `` component, such as `isHoverable`, `isRowSelected`, and other table row properties. -It is also possible to disable row selection using the `isSelectDisabled` function, which can be passed to the wrapping `DataView` component through the `selection`. +It is also possible to disable row selection using the `isSelectDisabled` function, which can be passed to the wrapping `DataView` component through the `selection` prop. ### Table example ```js file="./DataViewTableExample.tsx" @@ -66,15 +66,15 @@ To disable row selection, pass the `isSelectDisabled` function to `selection` pr ``` ## Sorting -The following example demonstrates how to enable sorting functionality within a data view. This implementation support dynamic sorting by column and persists the sort state in the page's URL via [React Router](https://reactrouter.com/). +The following example demonstrates how to enable sorting functionality within a data view. This implementation supports dynamic sorting by column and persists the sort state in the page's URL via [React Router](https://reactrouter.com/). ### Sorting example ```js file="./SortingExample.tsx" ``` -### useDataViewSort hook +### Sorting state -The `useDataViewSort` hook manages the sorting state of a data view. It provides an easy way to handle sorting logic, including synchronization with URL parameters and defining default sorting behavior. +The `useDataViewSort` hook manages the sorting state of a data view and provides an easy way to handle sorting logic, such as synchronization with URL parameters and the definition of default sorting behavior. **Initial values:** - `initialSort` object to set default `sortBy` and `direction` values: @@ -95,12 +95,12 @@ The `useDataViewSort` hook integrates seamlessly with [React Router](https://rea ## States -The data view table allows you to react to the `activeState` property passed to the data view (such as `empty`, `error`, `loading`). You can use the `headStates` and `bodyStates` props to define the table head and body for a given state. +The data view table allows you to react to the `activeState` of the data view (such as `empty`, `error`, `loading`). You can use the `headStates` and `bodyStates` props to define the table head and body for a given state. ### Empty When there is no data to render in the data view, you can instead display an empty state. -You can create your error state by using a [PatternFly empty state](/components/empty-state). To render the empty state, pass the component under `empty` key to `headStates` or `bodyStates`. +You can create your empty state by passing a [PatternFly empty state](/components/empty-state) to the `empty` key of `headStates` or `bodyStates`. ```js file="./DataViewTableEmptyExample.tsx" @@ -111,7 +111,7 @@ When there is a data connection or retrieval error, you can display an error sta The error state will be displayed when the data view `activeState` value is `error`. -You can create your error state by either using the [component groups extension's error state](/component-groups/error-state) or a [PatternFly empty state](/components/empty-state) component. To render the error state, pass the component under `error` key to `headStates` or `bodyStates`. +You can create your error state by passing either the [component groups extension's error state](/component-groups/error-state) or a [PatternFly empty state](/components/empty-state) to the `error` key of `headStates` or `bodyStates`. ```js file="./DataViewTableErrorExample.tsx" @@ -122,7 +122,7 @@ To indicate that data is loading, you can display a loading state. The loading state will be displayed when the data view `activeState` value is `loading`. -You can create your loading state by either using the [component groups extension's skeleton table](/component-groups/skeleton-table) or a customized [PatternFly empty state](/components/empty-state). To render the loading state, pass the component under the `loading` key to `headStates` or `bodyStates`. +You can create your loading state by passing either the [component groups extension's skeleton table](/component-groups/skeleton-table) or a customized [PatternFly empty state](/components/empty-state) to the `loading` key of `headStates` or `bodyStates`. ```js file="./DataViewTableLoadingExample.tsx" diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md index e81f5ff0..1901f424 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Toolbar/Toolbar.md @@ -43,7 +43,7 @@ You can further customize toolbar interactions by referring to the additional do ``` ## Toolbar actions -To support additional user needs, you can pass relevant actions to the toolbar via `actions`. Add standard PatternFly actions (like buttons) or choose predefined [responsive actions](/component-groups/responsive-actions) which ensure the responsive behavior of multiple actions in one toolbar. +To support additional user needs, you can pass relevant actions to the toolbar via `actions`. Add standard PatternFly actions (like buttons) or choose predefined [responsive actions](/component-groups/responsive-actions) which ensure the responsive behavior of multiple actions in 1 toolbar. ### Actions example @@ -55,7 +55,7 @@ To support additional user needs, you can pass relevant actions to the toolbar v To help users navigate data records that span multiple pages, add pagination support to your toolbar. -The data view toolbar can display a pagination using the `pagination` prop. You can also pass a custom `ouiaId` for testing purposes to the toolbar. You can also persist pagination values in the URL, to make it easier to share or bookmark specific pages of your data. +The data view toolbar can display a pagination using the `pagination` prop. You can also pass a custom `ouiaId` to the toolbar for testing purposes. You can also persist pagination values in the URL to make it easier to share or bookmark specific pages of your data. ### Pagination state @@ -97,13 +97,13 @@ The `useDataViewSelection` hook manages the selection state of the data view. **Initial values:** - Optional `initialSelected` array of record's identifiers selected by default. -- `matchOption` function to check if given record is selected. +- `matchOption` function to check if the record is selected. - When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array. **Return values:** - `selected` array of currently selected records. -- `isSelected` function returning the selection state for given record. -- `onSelect` callback to modify the selection state and accepting `isSelecting` flag indicating if records are changing to selected or deselected and `items` containing affected records. +- `isSelected` function returning the selection state for the record. +- `onSelect` callback to modify the selection state. This accepts the `isSelecting` flag (indicates if records are being selected or deselected) and `items` (affected records). ### Selection example From 9b089559531ef3ea84b72aedaf0cf4902e2664c1 Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Wed, 11 Dec 2024 15:29:02 +0100 Subject: [PATCH 11/12] chore: update new features to v6 --- .../{Components.spec.cy.ts => TreeTable.spec.cy.ts} | 2 +- .../DataView/PredefinedLayoutFullExample.tsx | 13 ++++++------- .../extensions/data-view/examples/Table/Table.md | 2 +- .../module/src/DataViewToolbar/DataViewToolbar.tsx | 2 +- 4 files changed, 9 insertions(+), 10 deletions(-) rename cypress/e2e/{Components.spec.cy.ts => TreeTable.spec.cy.ts} (97%) diff --git a/cypress/e2e/Components.spec.cy.ts b/cypress/e2e/TreeTable.spec.cy.ts similarity index 97% rename from cypress/e2e/Components.spec.cy.ts rename to cypress/e2e/TreeTable.spec.cy.ts index 765da5f6..e03ffafc 100644 --- a/cypress/e2e/Components.spec.cy.ts +++ b/cypress/e2e/TreeTable.spec.cy.ts @@ -3,7 +3,7 @@ describe('Test the Data view docs with tree table', () => { it('displays a a components page with tree table', () => { const ouiaId = 'TreeTableExample'; - cy.visit('http://localhost:8006/extensions/data-view/components'); + cy.visit('http://localhost:8006/extensions/data-view/table'); cy.get(`[data-ouia-component-id="${ouiaId}-th-0"]`).scrollIntoView().contains('Repositories'); cy.get(`[data-ouia-component-id="${ouiaId}-th-1"]`).contains('Branches'); diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx index b9bf759d..b4873e9d 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/DataView/PredefinedLayoutFullExample.tsx @@ -1,6 +1,6 @@ /* eslint-disable no-nested-ternary */ import React, { useEffect, useState, useRef, useMemo } from 'react'; -import { Drawer, DrawerActions, DrawerCloseButton, DrawerContent, DrawerContentBody, DrawerHead, DrawerPanelContent, Title, Text, EmptyState, EmptyStateHeader, EmptyStateBody, EmptyStateFooter, EmptyStateActions, Button, EmptyStateIcon } from '@patternfly/react-core'; +import { Drawer, DrawerActions, DrawerCloseButton, DrawerContent, DrawerContentBody, DrawerHead, DrawerPanelContent, Title, Content, EmptyState, EmptyStateBody, EmptyStateFooter, EmptyStateActions, Button, } from '@patternfly/react-core'; import { ActionsColumn, Tbody, Td, ThProps, Tr } from '@patternfly/react-table'; import { BulkSelect, BulkSelectValue } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; import { Pagination } from '@patternfly/react-core'; @@ -72,8 +72,7 @@ const empty = (
` component, such as `width`, `sort`, and other table head cell properties. @@ -37,7 +37,7 @@ Below is a detailed description of properties used to define rows and columns fo - `id` (optional): Unique identifier for the row that's used for matching selected items. - `props` (optional): (`TrProps`) to pass to the `
- - } /> + There are no matching data to be displayed. @@ -113,10 +112,10 @@ const RepositoryDetail: React.FunctionComponent = ({ sele Detail of {selectedRepo?.name} - Branch: {selectedRepo?.branch} - Pull requests: {selectedRepo?.prs} - Workspace: {selectedRepo?.workspace} - Last commit: {selectedRepo?.lastCommit} + Branch: {selectedRepo?.branch} + Pull requests: {selectedRepo?.prs} + Workspace: {selectedRepo?.workspace} + Last commit: {selectedRepo?.lastCommit} setSelectedRepo(undefined)} data-ouia-component-id="detail-drawer-close-btn"/> diff --git a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md index bc813e54..19254f94 100644 --- a/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md +++ b/packages/module/patternfly-docs/content/extensions/data-view/examples/Table/Table.md @@ -17,7 +17,7 @@ sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/mod --- import { useMemo } from 'react'; import { BrowserRouter, useSearchParams } from 'react-router-dom'; -import { Button, EmptyState, EmptyStateActions, EmptyStateBody, EmptyStateFooter, EmptyStateHeader, EmptyStateIcon } from '@patternfly/react-core'; +import { Button, EmptyState, EmptyStateActions, EmptyStateBody, EmptyStateFooter } from '@patternfly/react-core'; import { CubesIcon, FolderIcon, FolderOpenIcon, LeafIcon, ExclamationCircleIcon } from '@patternfly/react-icons'; import { ErrorState, ResponsiveAction, ResponsiveActions, SkeletonTableHead, SkeletonTableBody } from '@patternfly/react-component-groups'; import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar'; diff --git a/packages/module/src/DataViewToolbar/DataViewToolbar.tsx b/packages/module/src/DataViewToolbar/DataViewToolbar.tsx index 9e6b3eec..5410e706 100644 --- a/packages/module/src/DataViewToolbar/DataViewToolbar.tsx +++ b/packages/module/src/DataViewToolbar/DataViewToolbar.tsx @@ -41,7 +41,7 @@ export const DataViewToolbar: React.FC = ({ className, oui )} {actions && ( - + {actions} )} From d511ebfd2c3b835c2e9119aa92035a6cf9c4691a Mon Sep 17 00:00:00 2001 From: Filip Hlavac Date: Mon, 6 Jan 2025 13:21:13 +0100 Subject: [PATCH 12/12] fix: fix E2E tests --- cypress/e2e/DataView.spec.cy.ts | 4 ++-- package-lock.json | 20 +++++++++++++++++++- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/cypress/e2e/DataView.spec.cy.ts b/cypress/e2e/DataView.spec.cy.ts index 80ef0a8a..2504ab7b 100644 --- a/cypress/e2e/DataView.spec.cy.ts +++ b/cypress/e2e/DataView.spec.cy.ts @@ -29,11 +29,11 @@ describe('Test the Data view docs page', () => { cy.get(`[data-ouia-component-id="${ouiaId}-td-0-4"]`).contains('Timestamp one'); // test bulk select - cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('not.be.checked')}); + cy.get(`[data-ouia-component-id="LayoutExample"] input[type="checkbox"]`).each(($checkbox) => {cy.wrap($checkbox).should('not.be.checked')}); // page checkbox select cy.get(`[data-ouia-component-id="BulkSelect-checkbox"`).first().click(); - cy.get(`input[type="checkbox"`).each(($checkbox) => {cy.wrap($checkbox).should('be.checked')}); + cy.get(`[data-ouia-component-id="LayoutExample"] input[type="checkbox"]`).each(($checkbox) => {cy.wrap($checkbox).should('be.checked')}); cy.contains('5 selected').should('exist'); // page checkbox deselect diff --git a/package-lock.json b/package-lock.json index ce4a0eb9..9e89670e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12581,6 +12581,15 @@ "readable-stream": "^2.3.6" } }, + "node_modules/focus-trap": { + "version": "7.6.2", + "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.2.tgz", + "integrity": "sha512-9FhUxK1hVju2+AiQIDJ5Dd//9R2n2RAfJ0qfhF4IHGHgcoEUTMpbTeG/zbEuwaiYXfuAH6XE0/aCyxDdRM+W5w==", + "license": "MIT", + "dependencies": { + "tabbable": "^6.2.0" + } + }, "node_modules/follow-redirects": { "version": "1.5.10", "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.5.10.tgz", @@ -36682,6 +36691,14 @@ "readable-stream": "^2.3.6" } }, + "focus-trap": { + "version": "7.6.2", + "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.2.tgz", + "integrity": "sha512-9FhUxK1hVju2+AiQIDJ5Dd//9R2n2RAfJ0qfhF4IHGHgcoEUTMpbTeG/zbEuwaiYXfuAH6XE0/aCyxDdRM+W5w==", + "requires": { + "tabbable": "^6.2.0" + } + }, "follow-redirects": { "version": "1.5.10", "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.5.10.tgz", @@ -45284,7 +45301,8 @@ } }, "tabbable": { - "version": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", "integrity": "sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==" }, "tapable": {