Merge pull request #888 from yaacov/add-jdoc-to-standardpagewithselec…

…tion

🧼 Add jdoc to StandardPageWithSelection

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<RowProps<T>>} [RowMapper=DefaultRow<T>] - Optional component to map resource data to a table row.
+ * @property {FC<RowProps<T>>} [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<GlobalActionToolbarProps<T>>[]} [GlobalActionToolbarItems=[]] - Optional toolbar items with global actions.
+ *
+ * @template T - The type of the items being displayed in the table.
  */
 export interface StandardPageProps<T> {
   /**
@@ -169,7 +189,37 @@ export interface StandardPageProps<T> {
 }
 
 /**
- * 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<T>} 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<RowProps<T>>} [props.RowMapper=DefaultRow<T>] - Optional component to map resource data to a table row.
+ * @param {FC<RowProps<T>>} [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<GlobalActionToolbarProps<T>>[]} [props.GlobalActionToolbarItems=[]] - Optional toolbar items with global actions.
+ *
+ * @template T - The type of the items being displayed in the table.
+ *
+ * @example
+ * <StandardPage
+ *   namespace="my-namespace"
+ *   dataSource={[myData, false, null]}
+ *   title="My List"
+ *   fieldsMetadata={myFieldsMetadata}
+ *   // ...other props
+ * />
  */
 export function StandardPage<T>({
   namespace,

packages/forklift-console-plugin/src/components/page/StandardPageWithSelection.tsx

@@ -130,13 +130,51 @@ export function withIdBasedSelection<T>({
   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<T>} - 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<T> extends StandardPageProps<T> {
   toId?: (item: T) => string;
   canSelect?: (item: T) => boolean;
   onSelect?: (selectedIds: string[]) => void;
   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<T>} props - Other props that are passed through to the `StandardPage` component.
+ *
+ * @template T - The type of the items being displayed in the table.
+ *
+ * @example
+ * <StandardPageWithSelection
+ *   toId={item => item.id}
+ *   canSelect={item => item.status !== 'archived'}
+ *   onSelect={selectedIds => console.log('Selected IDs:', selectedIds)}
+ *   selectedIds={['1', '2']}
+ *   // ...other props
+ * />
+ */
 export function StandardPageWithSelection<T>(props: StandardPageWithSelectionProps<T>) {
   const { toId, canSelect = () => true, onSelect, selectedIds, ...rest } = props;