Clean up the docs

[fhlavac]

closes #22
RHCLOUD-36308

Before:

Now:

[patternfly-build]

Preview: https://react-data-view-pr-data-view-152.surge.sh

A11y report: https://react-data-view-pr-data-view-152-a11y.surge.sh

[edonehoo]

I only made it through a small portion of the docs, but just wanted to comment these suggestions so that they don't get lost. Will continue reviewing tomorrow!

[edonehoo]

Suggested change

	id: Data view
	id: Overview
	title: Data view overview

What if we change the nav label to just be "Overview" and then expand in the page title to be "Data view overview"? We made similar changes to our ChatBot extension docs, and this would align well with those if you think it sounds okay

[edonehoo]

Could we move this note to line 21 to be the first text on the page?

[edonehoo]

Suggested change

## Data view table

What if we let the page title serve this purpose instead?

[edonehoo]

Suggested change

	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.
	The **data view** extension enables you to present data in an organized layout, with a toolbar that supports interactions like selection and pagination.

What if we move the second sentence to the layout section? I'll add it as a suggestion

[edonehoo]

Suggested change

	### 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).
	### 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).
	The data view toolbars and sub-components that display the data (like a card view or table) are always passed as `children` to the `<DataView>` component.

[edonehoo]

Suggested change

	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.
	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 `<DataViewToolbar>` 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, 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 `<DataView>` child. In the near future, we are also planning to introduce a predefined card view component.

[edonehoo]

Suggested change

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.

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.

Maybe it's just my lack of familiarity with the extension, but I'm struggling to understand this section or the value that this info adds. Is this just explaining how the DataView props are created? Do any of the examples demonstrate this? For me, this is a confusing section, but I'm also not a dev, so I know I'm not the target audience 😄

[fhlavac]

True, these are unnecessary details. Thank you

[edonehoo]

Suggested change

	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`.
	The `<DataViewEventsContext>` 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 `<DataViewEventsProvider>`.

I'm assuming "your components" means other components outside of the data view, but let me know if I'm wrong

[fhlavac]

Yes, components outside of the data view

[fhlavac]

@edonehoo thank you for the great comments! I've just pushed the updated version

[edonehoo]

Left a bunch of comments/suggestions. GitHub was giving me trouble, so I apologize in advance if this is hard to parse through. Feel free to shoot me a message with any questions!

Also, you can ignore any suggestions that violate any requirements for the docs framework. I'm not sure what's optional vs required

[edonehoo]

Suggested change

	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.

[edonehoo]

Suggested change

	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).

since we repeat this in the following sentence

[edonehoo]

Suggested change

	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.

[edonehoo]

Suggested change

	## 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.
	### Events context
	## Events context

since we removed the other section, could we bump up the events context up a level maybe?

[edonehoo]

Suggested change

	The `<DataViewEventsContext>` 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 `<DataViewEventsProvider>`.
	The `<DataViewEventsContext>` 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 `<DataViewEventsProvider>`. This is demonstrated in the following example.

[edonehoo]

Suggested change

	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.

[edonehoo]

Suggested change

### Toolbar usage

[edonehoo]

again, I can't make GH native suggestions for lines 94-113:

The data view toolbar can display a bulk selection component using bulkSelect. You can make use of a predefined component group extension bulk select component.

Selection state

The useDataViewSelection hook manages the selection state of the data viwe.

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.
    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

[edonehoo]

Suggested change

	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.

[edonehoo]

For the next section:

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 <DataViewFilters>, <DataViewTextFilter>, and <DataViewCheckboxFilter> to customize and handle filtering directly in the toolbar. The <DataViewFilters> component is a wrapper that allows 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.

You can either pass a value and onChange event to every filter separately, or you can pass values and onChange to the <DataViewFilters> wrapper, which make them available to its children. Props directly passed to child filters have a higher priority than the "inherited" ones.

Filters state

The useDataViewFilters hook manages the filter state of the data view. It allows you to define default filter values, synchronize filter state with URL parameters, and handle filter changes efficiently.

Initial values:

• initialFilters object with default filter values (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 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

[fhlavac]

@edonehoo I tried to add the requested changes. Please let me know if something needs to be further improved. Thank you for all your comments!

[edonehoo]

just a few small formatting suggestions, but overall I think this content is in a good place/ready to go live! Nothing big to hold up the release

[edonehoo]

Suggested change

	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.

[edonehoo]

Suggested change

	*When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array.*
	- When no `matchOption` is passed, the `Array.prototype.includes()` operation is performed on the `selected` array.

I would indent this under the matchOption line if you can

[edonehoo]

Suggested change

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 `<DataViewFilters>`, `<DataViewTextFilter>`, and `<DataViewCheckboxFilter>` to customize and handle filtering directly in the toolbar. The `<DataViewFilters>` component is a wrapper that allows 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 `<DataViewFilters>`, `<DataViewTextFilter>`, and `<DataViewCheckboxFilter>` to customize and handle filtering directly in the toolbar. The `<DataViewFilters>` component is a wrapper that allows 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 in the [props section of this page](#props).

we just typically avoid words like below/above for accessibility purposes. so however you'd like to adjust that!

[edonehoo]

Suggested change

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.

[edonehoo]

Suggested change

	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.

[edonehoo]

Suggested change

	- 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.

[edonehoo]

Suggested change

	- Optional `initialSelected` array of record's identifiers selected by default
	- `matchOption` function to check if given record is selected
	- Optional `initialSelected` array of record's identifiers selected by default.
	- `matchOption` function to check if given record is selected.

[edonehoo]

Suggested change

	- `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.

[edonehoo]

Suggested change

	- `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.

[edonehoo]

Suggested change

	- `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.

[github-actions]

🎉 This PR is included in version 5.8.0 🎉

The release is available on:

• GitHub release
• npm package (@prerelease-v5 dist-tag)

Your semantic-release bot 📦🚀