From d450d4e6c3776947d887f30594ac81759c7631cc Mon Sep 17 00:00:00 2001 From: Yaacov Zamir Date: Wed, 7 Feb 2024 11:34:47 +0200 Subject: [PATCH] Add jdoc to StandardPageWithSelection Signed-off-by: Yaacov Zamir --- .../src/components/page/StandardPage.tsx | 54 ++++++++++++++++++- .../page/StandardPageWithSelection.tsx | 38 +++++++++++++ 2 files changed, 90 insertions(+), 2 deletions(-) diff --git a/packages/forklift-console-plugin/src/components/page/StandardPage.tsx b/packages/forklift-console-plugin/src/components/page/StandardPage.tsx index 381c178f1..012ee6c04 100644 --- a/packages/forklift-console-plugin/src/components/page/StandardPage.tsx +++ b/packages/forklift-console-plugin/src/components/page/StandardPage.tsx @@ -73,7 +73,27 @@ const reduceValueFilters = ( }; /** - * @param T type to be displayed in the list + * Properties for the `StandardPage` component. + * These properties define the configuration and behavior of the standard list page. + * + * @typedef {Object} StandardPageProps + * @property {string} namespace - The namespace in which the data resides. + * @property {[T[], boolean, unknown]} dataSource - The data source tuple consisting of an array of items, a loading flag, and an error object. + * @property {FC>} [RowMapper=DefaultRow] - Optional component to map resource data to a table row. + * @property {FC>} [CellMapper] - Optional component to map resource data to individual cells within a row. + * @property {string} title - The title displayed at the top of the page. + * @property {JSX.Element} [addButton] - Optional element to display as an "add" or "create" button. + * @property {ResourceField[]} fieldsMetadata - Metadata for the fields to be displayed. + * @property {{ [type: string]: FilterRenderer }} [extraSupportedFilters] - Optional additional filter types. + * @property {JSX.Element} [customNoResultsFound] - Optional custom message to display when no results are found. + * @property {JSX.Element} [customNoResultsMatchFilter] - Optional custom message to display when no results match the filter. + * @property {number | 'on' | 'off'} [pagination=DEFAULT_PER_PAGE] - Controls the display of pagination controls. + * @property {string} [filterPrefix=''] - Prefix for filters stored in the query params part of the URL. + * @property {UserSettings} [userSettings] - User settings store to initialize the page according to user preferences. + * @property {ReactNode} [alerts] - Optional alerts section below the page title. + * @property {FC>[]} [GlobalActionToolbarItems=[]] - Optional toolbar items with global actions. + * + * @template T - The type of the items being displayed in the table. */ export interface StandardPageProps { /** @@ -169,7 +189,37 @@ export interface StandardPageProps { } /** - * Standard list page. + * Standard list page component. + * This component renders a list view with filtering, sorting, and pagination capabilities. + * It supports custom renderers for rows and headers, as well as global actions. + * + * @param {StandardPageProps} props - The properties passed to the component. + * @param {string} props.namespace - The namespace in which the data resides. + * @param {T[]} props.dataSource - The data source tuple consisting of an array of items, a loading flag, and an error object. + * @param {FC>} [props.RowMapper=DefaultRow] - Optional component to map resource data to a table row. + * @param {FC>} [props.CellMapper] - Optional component to map resource data to individual cells within a row. + * @param {string} props.title - The title displayed at the top of the page. + * @param {JSX.Element} [props.addButton] - Optional element to display as an "add" or "create" button. + * @param {ResourceField[]} props.fieldsMetadata - Metadata for the fields to be displayed. + * @param {{ [type: string]: FilterRenderer }} [props.extraSupportedFilters] - Optional additional filter types. + * @param {JSX.Element} [props.customNoResultsFound] - Optional custom message to display when no results are found. + * @param {JSX.Element} [props.customNoResultsMatchFilter] - Optional custom message to display when no results match the filter. + * @param {number | 'on' | 'off'} [props.pagination=DEFAULT_PER_PAGE] - Controls the display of pagination controls. + * @param {string} [props.filterPrefix=''] - Prefix for filters stored in the query params part of the URL. + * @param {UserSettings} [props.userSettings] - User settings store to initialize the page according to user preferences. + * @param {ReactNode} [props.alerts] - Optional alerts section below the page title. + * @param {FC>[]} [props.GlobalActionToolbarItems=[]] - Optional toolbar items with global actions. + * + * @template T - The type of the items being displayed in the table. + * + * @example + * */ export function StandardPage({ namespace, diff --git a/packages/forklift-console-plugin/src/components/page/StandardPageWithSelection.tsx b/packages/forklift-console-plugin/src/components/page/StandardPageWithSelection.tsx index 3f3c47340..ff7e70f47 100644 --- a/packages/forklift-console-plugin/src/components/page/StandardPageWithSelection.tsx +++ b/packages/forklift-console-plugin/src/components/page/StandardPageWithSelection.tsx @@ -130,6 +130,19 @@ export function withIdBasedSelection({ return Enhanced; } +/** + * Properties for the `StandardPageWithSelection` component. + * These properties extend the base `StandardPageProps` and add additional ones related to selection. + * + * @typedef {Object} StandardPageWithSelectionProps + * @property {Function} toId - A function that returns a unique identifier for each item. + * @property {Function} canSelect - A function that determines whether an item can be selected. + * @property {Function} onSelect - A callback function that is triggered when the selection changes. + * @property {string[]} selectedIds - An array of identifiers for the currently selected items. + * @property {...StandardPageProps} - Other props that are passed through to the `StandardPage` component. + * + * @template T - The type of the items being displayed in the table. + */ export interface StandardPageWithSelectionProps extends StandardPageProps { toId?: (item: T) => string; canSelect?: (item: T) => boolean; @@ -137,6 +150,31 @@ export interface StandardPageWithSelectionProps extends StandardPageProps selectedIds?: string[]; } +/** + * Renders a standard page with selection capabilities. + * This component wraps the `StandardPage` component and adds support for row selection. + * It uses the provided `toId`, `canSelect`, `onSelect`, and `selectedIds` props to manage the selection state. + * + * NOTE: if `onSelect` is missing, the component will return `StandardPage` without selections. + * + * @param {Object} props - The properties passed to the component. + * @param {Function} props.toId - A function that returns a unique identifier for each item. + * @param {Function} props.canSelect - A function that determines whether an item can be selected. + * @param {Function} props.onSelect - A callback function that is triggered when the selection changes. + * @param {string[]} props.selectedIds - An array of identifiers for the currently selected items. + * @param {...StandardPageProps} props - Other props that are passed through to the `StandardPage` component. + * + * @template T - The type of the items being displayed in the table. + * + * @example + * item.id} + * canSelect={item => item.status !== 'archived'} + * onSelect={selectedIds => console.log('Selected IDs:', selectedIds)} + * selectedIds={['1', '2']} + * // ...other props + * /> + */ export function StandardPageWithSelection(props: StandardPageWithSelectionProps) { const { toId, canSelect = () => true, onSelect, selectedIds, ...rest } = props;