From 2da866b34525bb49fa79a21176dc95c9525e68d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9?= <583546+oandregal@users.noreply.github.com> Date: Tue, 5 Nov 2024 09:16:15 +0100 Subject: [PATCH] Document `filterSortAndPaginate` & `isItemValid` utilities (#66738) --- packages/dataviews/README.md | 31 ++++++++++++++++++++++++++++ packages/dataviews/src/validation.ts | 9 ++++++++ 2 files changed, 40 insertions(+) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index 066a32fc40f47..79875542378b3 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -407,6 +407,37 @@ Same as `fields` property of `DataViews`. - `type`: either `regular` or `panel`. - `fields`: a list of fields ids that should be rendered. +## Utilities + +### `filterSortAndPaginate` + +Utility to apply the view config (filters, search, sorting, and pagination) to a dataset client-side. + +Parameters: + +- `data`: the dataset, as described in the "data" property of DataViews. +- `view`: the view config, as described in the "view" property of DataViews. +- `fields`: the fields config, as described in the "fields" property of DataViews. + +Returns an object containing: + +- `data`: the new dataset, with the view config applied. +- `paginationInfo`: object containing the following properties: + - `totalItems`: total number of items for the current view config. + - `totalPages`: total number of pages for the current view config. + +### `isItemValid` + +Utility to determine whether or not the given item's value is valid according to the current fields and form config. + +Parameters: + +- `item`: the item, as described in the "data" property of DataForm. +- `fields`: the fields config, as described in the "fields" property of DataForm. +- `form`: the form config, as described in the "form" property of DataForm. + +Returns a boolean indicating if the item is valid (true) or not (false). + ## Contributing to this package This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. diff --git a/packages/dataviews/src/validation.ts b/packages/dataviews/src/validation.ts index 41969a7960af6..0a6542da4e8d4 100644 --- a/packages/dataviews/src/validation.ts +++ b/packages/dataviews/src/validation.ts @@ -4,6 +4,15 @@ import { normalizeFields } from './normalize-fields'; import type { Field, Form } from './types'; +/** + * Whether or not the given item's value is valid according to the fields and form config. + * + * @param item The item to validate. + * @param fields Fields config. + * @param form Form config. + * + * @return A boolean indicating if the item is valid (true) or not (false). + */ export function isItemValid< Item >( item: Item, fields: Field< Item >[],