@ifto/mantine-kit 0.4.0 → 0.5.2

package/README.md

@@ -49,7 +49,7 @@ Install the optional ones only if you use the components that need them:
 | `@mantine/form` | the form templates (`FormPage`, `CreateFormPage`, `EditFormPage`) and `DataForm`, which take a `useForm` form |
 | `@mantine/modals` | the confirmations of `Table` (delete), `ListPage` and `DataForm` |
 | `@mantine/dates` and `dayjs` (its peer dependency) | `DateField` |
-| `mantine-datatable` | `Table`, `ViewTable`, `ListPage` |
+| `mantine-datatable` | `Table`, `ViewTable`, `DataTableView` |
 | `echarts` | `EChart` and the chart types |
 | `exceljs` | Excel export |
 | `axios` | `AxiosHttpClient` |
@@ -117,11 +117,13 @@ module.exports = {
 
 ### CRUD list page
 
-`ListPage` shows the records in a sortable, paginated table with view, edit and delete actions. Its `service` is any
-object with `findAll` and `delete`:
+`ListPage` lays out the header with the "Add" button, optional filters and a table. The `Table` shows the records with
+view, edit and delete actions. Its `service` is any object with `delete`, and its `data` comes from a pagination hook:
 
 ```tsx
 import ListPage from '@ifto/mantine-kit/component/template/ListPage/ListPage';
+import Table from '@ifto/mantine-kit/component/organism/Table/Table';
+import { useClientPagination } from '@ifto/mantine-kit/component/organism/Table/useClientPagination';
 import type { ListDataSource } from '@ifto/mantine-kit/data/ListDataSource';
 
 type Region = { id?: number; name: string };
@@ -132,20 +134,88 @@ const regions: ListDataSource<Region> = {
 };
 
 export function RegionsPage() {
+    // The object must be stable (here, a module constant), since a new one fetches again.
+    const data = useClientPagination(regions);
+
     return (
         <ListPage
             title="Regions"
             titlePlural="Regions"
             breadcrumbItems={[{ title: 'Regions', href: '/region' }]}
             addActionRoute="/region/create"
-            service={regions}
-            resourceBasePath="/region"
-            tableColumns={[{ accessor: 'name', title: 'Name', sortable: true }]}
-        />
+        >
+            <Table
+                data={data}
+                service={regions}
+                basePath="/region"
+                columns={[{ accessor: 'name', title: 'Name', sortable: true }]}
+            />
+        </ListPage>
     );
 }
 ```
 
+#### Client-side or server-side pagination
+
+The hook that creates the `data` of the `Table` defines where the records are sorted and paginated:
+
+| | `useClientPagination(source, { pagination })` | `useServerPagination(source, { firstPage })` |
+|---|---|---|
+| **Fetch** | all records at once | one page, with page, size and sort |
+| **Sorted and paginated by** | browser (sorting follows the locale) | backend |
+| **Total of records** | number of fetched records | `totalRecords` of the response |
+
+Both take a `source`, which is either:
+
+- an object with the method that fetches the records: `findAll()` (a `ListDataSource`) or `findPage(request)` (a
+  `PageDataSource`), such as a service. The hook calls the method on the object, so it keeps its `this`;
+- or a function that fetches them, for fetches with a filter (e.g. `useCallback(request => service.findPageByYear(year,
+  request), [year])`).
+
+The source must be stable (e.g. a module constant, or a function created with `useCallback`), since a new one fetches
+again: a `new Service()` inside the component would fetch on every render.
+
+`findPage` (or the function) receives the page, the size and the sort, and returns the records of that page and the total of records. The
+contract knows nothing about your backend, so convert it to the format of your API (here, Spring Data, returning a
+`PagedModel`, which puts the total of records in `page.totalElements`). The page starts at 1, or at the `firstPage`
+option (e.g. 0 for Spring), which only changes the requests: the table always shows the pages starting at 1.
+
+```tsx
+import { useCallback } from 'react';
+import { useServerPagination } from '@ifto/mantine-kit/component/organism/Table/useServerPagination';
+import type { FetchPage } from '@ifto/mantine-kit/data/PageRequest';
+
+export function RegionsTable({ name }: { name: string }) {
+    // A new function means the filter changed, which goes back to page 1.
+    const fetchPage: FetchPage<Region> = useCallback(
+        async ({ page, size, sort }) => {
+            const params = new URLSearchParams({
+                name,
+                page: String(page),
+                size: String(size),
+                sort: `${String(sort.columnAccessor)},${sort.direction}`
+            });
+            const response = await fetch(`/api/region?${params}`).then(result => result.json());
+
+            return { records: response.content, totalRecords: response.page.totalElements };
+        },
+        [name]
+    );
+    const data = useServerPagination(fetchPage, { firstPage: 0 });
+
+    return <Table data={data} service={regions} basePath="/region" columns={columns} />;
+}
+```
+
+With `useServerPagination`:
+
+- `sort.columnAccessor` holds the `sortKey` of the column, if it has one, or else its `accessor`. A calculated column
+  needs a `sortKey` or `sortable: false`.
+- The table goes back to page 1 when the page size, the sort or the filter changes, and to the last existing page when
+  the current one no longer exists (e.g. its last record was deleted).
+- The order of null values and the text collation are defined by the backend, so they can differ from client-side
+  pagination, which follows the locale and always puts null values last.
+
 ### CRUD form page
 
 `FormPage` creates, edits or views a record and saves it with any object that has a `save(id, data)` method:
@@ -395,9 +465,10 @@ Every file is imported by its path inside `src`, without the extension, e.g.
 | `Navbar` | Side menu with links and collapsible groups, highlighting the current page. |
 | `PageHeader` | Page title with the breadcrumb and, in list pages, the "Add" button. |
 | `StatsGrid` | Responsive grid of `StatsCard`s, with placeholders while loading. |
-| `Table` | Table of the records of a data source, with view, edit and delete (with confirmation) actions. |
+| `Table` | Table of records with view, edit and delete (with confirmation) actions, paginated by `useClientPagination` or `useServerPagination`. |
 | `RowActions` | View, edit and delete buttons of a `Table` row. |
-| `ViewTable` | Sortable and paginated table (on top of mantine-datatable), with locale-aware sorting. |
+| `ViewTable` | Table that sorts (locale-aware) and paginates the given records in the browser (on top of mantine-datatable). |
+| `DataTableView` | Table that shows records as received, with the pagination and sort given by the caller. |
 
 The `EChart/chart` folder has chart types that build the ECharts option from generic series: `LineChart`, `BarChart`
 (negative values highlighted), `StackedBarChart` and `DonutChart`, with one panel per unit of measure.
@@ -407,7 +478,7 @@ The `EChart/chart` folder has chart types that build the ECharts option from gen
 | Component | What it does |
 |---|---|
 | `Layout` | App shell: header with the brand, color scheme toggle and user menu, collapsible side menu and content area. |
-| `ListPage` | List page of records: header with the "Add" button, optional filters and the `Table`. |
+| `ListPage` | List page of records: header with the "Add" button, optional filters and the table given as children. |
 | `FormPage` | Create, edit or view form page that saves the record in a `SaveDataSource`. |
 | `CreateFormPage` | Form page to create a record with a given function. |
 | `EditFormPage` | Form page to update a record with a given function. |

package/dist/component/organism/Table/Table.d.ts

@@ -1,5 +1,6 @@
 import { ReactElement } from 'react';
 import { DataTableColumn } from 'mantine-datatable';
+import { TableData } from './TableData';
 import { ListDataSource } from '../../../data/ListDataSource';
 import { Identifiable } from '../../../model/Identifiable';
 /** Which actions the table shows for each record. */
@@ -15,21 +16,19 @@ export type ActionsSettings = {
 };
 /** Props of the {@link Table}. */
 type TableProps<M extends Identifiable, S extends ListDataSource<M>> = {
-    /** Source of the records and of their deletion (e.g. a service that accesses an API). */
-    service: S;
     /**
-     * Fetches the records shown, instead of `service.findAll()`. To show data already available, use
-     * `() => Promise.resolve(data)`.
+     * Records and their pagination and sort, given by `useClientPagination` (sorted and paginated in the browser) or
+     * `useServerPagination` (sorted and paginated by the backend).
      */
-    customFetchMethod?: () => Promise<M[]>;
+    data: TableData<M>;
+    /** Source of the records, which deletes them (e.g. a service that accesses an API). */
+    service: S;
     /** Columns of the table. */
     columns: DataTableColumn<M>[];
     /** Base path of the pages of the records (e.g. `/region`), used to build the view and edit URLs. */
     basePath: string;
     /** Which actions are shown; the ones not given are shown. */
     actionsSettings?: Partial<ActionsSettings>;
-    /** Whether the table is paginated. */
-    pagination?: boolean;
     /**
      * Called by the edit action instead of opening the edit page of the record.
      * @param itemId id of the record to edit
@@ -42,8 +41,9 @@ type TableProps<M extends Identifiable, S extends ListDataSource<M>> = {
     getViewUrl?: (item: M) => string;
 };
 /**
- * A table that shows the records of a data source, with the view, edit and delete actions. Clicking a row opens the
- * record.
+ * A table that shows the records of a data source, with the view, edit and delete actions, or an alert when they cannot
+ * be fetched. Clicking a row opens the record. Its `data` comes from `useClientPagination` or `useServerPagination`,
+ * which define where the records are sorted and paginated.
  * @template M type of the records, shown one per row
  * @template S source of the records (e.g. a service that accesses an API)
  */

package/dist/component/organism/Table/Table.js

@@ -1,17 +1,14 @@
 "use client";
-import ViewTable from "../ViewTable/ViewTable.js";
+import DataTableView from "../ViewTable/DataTableView.js";
 import RowActions from "./RowActions.js";
 import { useKitConfig } from "../../../provider/useKit.js";
 import ErrorAlert from "../../atom/ErrorAlert/ErrorAlert.js";
-import useService from "../../../hook/useService.js";
 import { showErrorNotification, showSuccessNotification } from "../../../util/Notifications.js";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 import { Box } from "@mantine/core";
 // src/component/organism/Table/Table.tsx
 var ROW_HOVER_COLOR = "var(--mantine-primary-color-light)";
-/** Initial records of the table, while they are fetched; a single constant, so it is stable across renders. */
-var NO_RECORDS = [];
 /** Every action shown, used for the settings the caller does not give. */
 var DEFAULT_ACTIONS_SETTINGS = {
 	canShowActions: true,
@@ -30,13 +27,13 @@ function viewUrl(props, item, segments) {
 }
 /**
 * Creates the function that deletes a record and reloads the table.
-* @param setData function that sets the records of the table, obtained from `useState`
+* @param setData function that sets the records of the table
 * @param service source of the records, which deletes them
-* @param fetchMethod fetches the records again after the deletion
+* @param reload fetches the records again after the deletion
 * @param messages texts of the locale
 * @return a function that receives the record to delete and returns a promise resolved when it is deleted
 */
-function getDeleteRecordFn(setData, service, fetchMethod, messages) {
+function getDeleteRecordFn(setData, service, reload, messages) {
 	return async (item) => {
 		const id = item?.id ?? 0;
 		if (!id) {
@@ -46,33 +43,32 @@ function getDeleteRecordFn(setData, service, fetchMethod, messages) {
 		try {
 			await service.delete(id);
 			showSuccessNotification(messages.table.deleteSuccess, messages.common.success);
-			setData(await fetchMethod());
+			await reload();
 		} catch (e) {
 			showErrorNotification(e, void 0, messages.common.error);
 		}
 	};
 }
 /**
-* A table that shows the records of a data source, with the view, edit and delete actions. Clicking a row opens the
-* record.
+* A table that shows the records of a data source, with the view, edit and delete actions, or an alert when they cannot
+* be fetched. Clicking a row opens the record. Its `data` comes from `useClientPagination` or `useServerPagination`,
+* which define where the records are sorted and paginated.
 * @template M type of the records, shown one per row
 * @template S source of the records (e.g. a service that accesses an API)
 */
 var Table = (props) => {
-	const { customFetchMethod, service, columns, basePath, customEditFunction } = props;
-	const fetchMethod = useCallback(() => customFetchMethod ? customFetchMethod() : service.findAll(), [customFetchMethod, service]);
+	const { service, columns, basePath, customEditFunction, data } = props;
+	const { setRecords, reload } = data;
 	const { router, messages, formRouteSegments } = useKitConfig();
 	const navigate = router.useNavigate();
 	const settings = {
 		...DEFAULT_ACTIONS_SETTINGS,
 		...props.actionsSettings
 	};
-	const { data: fetchedData, loading, error } = useService(fetchMethod, NO_RECORDS);
-	const [data, setData] = useState([]);
-	useEffect(() => setData(fetchedData), [fetchedData]);
-	const deleteRecord = useMemo(() => getDeleteRecordFn(setData, service, fetchMethod, messages), [
+	const deleteRecord = useMemo(() => getDeleteRecordFn(setRecords, service, reload, messages), [
+		setRecords,
 		service,
-		fetchMethod,
+		reload,
 		messages
 	]);
 	const actionsColumn = {
@@ -91,15 +87,16 @@ var Table = (props) => {
 		})
 	};
 	const effectiveColumns = settings.canShowActions ? [...columns, actionsColumn] : columns;
-	if (error) return /* @__PURE__ */ jsx(ErrorAlert, {
+	if (data.error) return /* @__PURE__ */ jsx(ErrorAlert, {
 		title: messages.common.loadError,
-		message: String(error)
+		message: String(data.error)
 	});
-	return /* @__PURE__ */ jsx(ViewTable, {
-		data,
+	return /* @__PURE__ */ jsx(DataTableView, {
+		records: data.records,
+		state: data.tableState,
+		paginated: data.paginated,
 		columns: effectiveColumns,
-		loading,
-		pagination: props.pagination,
+		loading: data.loading,
 		highlightOnHover: true,
 		highlightOnHoverColor: ROW_HOVER_COLOR,
 		onRowClick: ({ record }) => navigate(viewUrl(props, record, formRouteSegments))

package/dist/component/organism/Table/Table.js.map

@@ -1 +1 @@
-{"version":3,"file":"Table.js","names":[],"sources":["../../../../src/component/organism/Table/Table.tsx"],"sourcesContent":["'use client';\n\nimport { ReactElement, useCallback, useEffect, useMemo, useState } from 'react';\n\nimport { Box } from '@mantine/core';\nimport { DataTableColumn } from 'mantine-datatable';\n\nimport ViewTable from '../ViewTable/ViewTable';\nimport RowActions from './RowActions';\nimport { ListDataSource } from '../../../data/ListDataSource';\nimport { KitMessages } from '../../../i18n/KitMessages';\nimport { Identifiable } from '../../../model/Identifiable';\nimport { useKitConfig } from '../../../provider/useKit';\nimport { FormRouteSegments } from '../../../router/FormRouteSegments';\nimport ErrorAlert from '../../atom/ErrorAlert/ErrorAlert';\nimport useService from '../../../hook/useService';\nimport { showErrorNotification, showSuccessNotification } from '../../../util/Notifications';\n\n/*\nColor of the row under the mouse. The default color of mantine-datatable (gray-1) is barely distinguishable from the\nzebra stripes (gray-0), so the highlight went unnoticed. The light variant of the primary color adapts to the light and\ndark color schemes.\n*/\nconst ROW_HOVER_COLOR = 'var(--mantine-primary-color-light)';\n\n/** Initial records of the table, while they are fetched; a single constant, so it is stable across renders. */\nconst NO_RECORDS: readonly Identifiable[] = [];\n\n/** Which actions the table shows for each record. */\nexport type ActionsSettings = {\n    /** Whether the actions column is shown. */\n    canShowActions: boolean;\n\n    /** Whether the view action is shown. */\n    canView: boolean;\n\n    /** Whether the edit action is shown. */\n    canEdit: boolean;\n\n    /** Whether the delete action is shown. */\n    canDelete: boolean;\n};\n\n/** Every action shown, used for the settings the caller does not give. */\nconst DEFAULT_ACTIONS_SETTINGS: ActionsSettings = {\n    canShowActions: true,\n    canView: true,\n    canEdit: true,\n    canDelete: true\n};\n\n/** Props of the {@link Table}. */\ntype TableProps<M extends Identifiable, S extends ListDataSource<M>> = {\n    /** Source of the records and of their deletion (e.g. a service that accesses an API). */\n    service: S;\n\n    /**\n     * Fetches the records shown, instead of `service.findAll()`. To show data already available, use\n     * `() => Promise.resolve(data)`.\n     */\n    customFetchMethod?: () => Promise<M[]>;\n\n    /** Columns of the table. */\n    columns: DataTableColumn<M>[];\n\n    /** Base path of the pages of the records (e.g. `/region`), used to build the view and edit URLs. */\n    basePath: string;\n\n    /** Which actions are shown; the ones not given are shown. */\n    actionsSettings?: Partial<ActionsSettings>;\n\n    /** Whether the table is paginated. */\n    pagination?: boolean;\n\n    /**\n     * Called by the edit action instead of opening the edit page of the record.\n     * @param itemId id of the record to edit\n     */\n    customEditFunction?: (itemId: M['id']) => void;\n\n    /**\n     * Builds the URL opened to view a record (click on the row or on the view icon).\n     * If absent, the default route is used: `${basePath}/<view segment>/${item.id}`.\n     */\n    getViewUrl?: (item: M) => string;\n};\n\n/**\n * Returns the view URL of a record: the one of `getViewUrl`, if given; otherwise, the default view route.\n * @param props props of the table\n * @param item record\n * @param segments URL segments of the form pages\n */\nfunction viewUrl<M extends Identifiable, S extends ListDataSource<M>>(\n    props: TableProps<M, S>,\n    item: M,\n    segments: FormRouteSegments\n): string {\n    return props.getViewUrl ? props.getViewUrl(item) : `${props.basePath}/${segments.view}/${item.id}`;\n}\n\n/**\n * Creates the function that deletes a record and reloads the table.\n * @param setData function that sets the records of the table, obtained from `useState`\n * @param service source of the records, which deletes them\n * @param fetchMethod fetches the records again after the deletion\n * @param messages texts of the locale\n * @return a function that receives the record to delete and returns a promise resolved when it is deleted\n */\nfunction getDeleteRecordFn<M extends Identifiable, S extends ListDataSource<M>>(\n    setData: (value: ((prevState: M[]) => M[]) | M[]) => void,\n    service: S,\n    fetchMethod: () => Promise<M[]>,\n    messages: KitMessages\n): (item: M) => Promise<void> {\n    return async (item: M) => {\n        const id = item?.id ?? 0;\n\n        // Without an id, the record was added only to the array and was not sent to the backend: just remove it.\n        if (!id) {\n            setData(prevData => prevData.filter(current => current !== item));\n            return;\n        }\n\n        try {\n            await service.delete(id);\n            showSuccessNotification(messages.table.deleteSuccess, messages.common.success);\n            setData(await fetchMethod());\n        } catch (e) {\n            showErrorNotification(e, undefined, messages.common.error);\n        }\n    };\n}\n\n/**\n * A table that shows the records of a data source, with the view, edit and delete actions. Clicking a row opens the\n * record.\n * @template M type of the records, shown one per row\n * @template S source of the records (e.g. a service that accesses an API)\n */\nconst Table = <M extends Identifiable, S extends ListDataSource<M>>(props: TableProps<M, S>): ReactElement => {\n    const { customFetchMethod, service, columns, basePath, customEditFunction } = props;\n    const fetchMethod = useCallback(\n        () => (customFetchMethod ? customFetchMethod() : service.findAll()),\n        [customFetchMethod, service]\n    );\n    const { router, messages, formRouteSegments } = useKitConfig();\n    const navigate = router.useNavigate();\n    const settings: ActionsSettings = { ...DEFAULT_ACTIONS_SETTINGS, ...props.actionsSettings };\n\n    const { data: fetchedData, loading, error } = useService(fetchMethod, NO_RECORDS as M[]);\n    const [data, setData] = useState<M[]>([]);\n\n    useEffect(() => setData(fetchedData), [fetchedData]);\n\n    const deleteRecord = useMemo(\n        () => getDeleteRecordFn(setData, service, fetchMethod, messages),\n        [service, fetchMethod, messages]\n    );\n\n    const actionsColumn: DataTableColumn<M> = {\n        accessor: 'actions',\n        title: <Box mr={6}>{messages.table.actions}</Box>,\n        textAlign: 'right',\n        render: item => (\n            <RowActions\n                {...settings}\n                viewUrl={viewUrl(props, item, formRouteSegments)}\n                editUrl={item.id ? `${basePath}/${formRouteSegments.edit}/${item.id}` : undefined}\n                onEdit={customEditFunction && item.id ? () => customEditFunction(item.id) : undefined}\n                onDelete={() => deleteRecord(item)}\n            />\n        )\n    };\n    const effectiveColumns = settings.canShowActions ? [...columns, actionsColumn] : columns;\n\n    if (error) {\n        return <ErrorAlert title={messages.common.loadError} message={String(error)} />;\n    }\n\n    return (\n        <ViewTable\n            data={data}\n            columns={effectiveColumns}\n            loading={loading}\n            pagination={props.pagination}\n            // Highlights the row under the mouse, to show that clicking it opens the record, as the view icon does.\n            highlightOnHover\n            highlightOnHoverColor={ROW_HOVER_COLOR}\n            onRowClick={({ record }) => navigate(viewUrl(props, record, formRouteSegments))}\n        />\n    );\n};\n\nexport default Table;\n"],"mappings":";;;;;;;;;;;AAuBA,IAAM,kBAAkB;;AAGxB,IAAM,aAAsC,CAAC;;AAkB7C,IAAM,2BAA4C;CAC9C,gBAAgB;CAChB,SAAS;CACT,SAAS;CACT,WAAW;AACf;;;;;;;AA4CA,SAAS,QACL,OACA,MACA,UACM;CACN,OAAO,MAAM,aAAa,MAAM,WAAW,IAAI,IAAI,GAAG,MAAM,SAAS,GAAG,SAAS,KAAK,GAAG,KAAK;AAClG;;;;;;;;;AAUA,SAAS,kBACL,SACA,SACA,aACA,UAC0B;CAC1B,OAAO,OAAO,SAAY;EACtB,MAAM,KAAK,MAAM,MAAM;EAGvB,IAAI,CAAC,IAAI;GACL,SAAQ,aAAY,SAAS,QAAO,YAAW,YAAY,IAAI,CAAC;GAChE;EACJ;EAEA,IAAI;GACA,MAAM,QAAQ,OAAO,EAAE;GACvB,wBAAwB,SAAS,MAAM,eAAe,SAAS,OAAO,OAAO;GAC7E,QAAQ,MAAM,YAAY,CAAC;EAC/B,SAAS,GAAG;GACR,sBAAsB,GAAG,KAAA,GAAW,SAAS,OAAO,KAAK;EAC7D;CACJ;AACJ;;;;;;;AAQA,IAAM,SAA8D,UAA0C;CAC1G,MAAM,EAAE,mBAAmB,SAAS,SAAS,UAAU,uBAAuB;CAC9E,MAAM,cAAc,kBACT,oBAAoB,kBAAkB,IAAI,QAAQ,QAAQ,GACjE,CAAC,mBAAmB,OAAO,CAC/B;CACA,MAAM,EAAE,QAAQ,UAAU,sBAAsB,aAAa;CAC7D,MAAM,WAAW,OAAO,YAAY;CACpC,MAAM,WAA4B;EAAE,GAAG;EAA0B,GAAG,MAAM;CAAgB;CAE1F,MAAM,EAAE,MAAM,aAAa,SAAS,UAAU,WAAW,aAAa,UAAiB;CACvF,MAAM,CAAC,MAAM,WAAW,SAAc,CAAC,CAAC;CAExC,gBAAgB,QAAQ,WAAW,GAAG,CAAC,WAAW,CAAC;CAEnD,MAAM,eAAe,cACX,kBAAkB,SAAS,SAAS,aAAa,QAAQ,GAC/D;EAAC;EAAS;EAAa;CAAQ,CACnC;CAEA,MAAM,gBAAoC;EACtC,UAAU;EACV,OAAO,oBAAC,KAAD;GAAK,IAAI;GAAI,UAAA,SAAS,MAAM;EAAa,CAAA;EAChD,WAAW;EACX,SAAQ,SACJ,oBAAC,YAAD;GACI,GAAI;GACJ,SAAS,QAAQ,OAAO,MAAM,iBAAiB;GAC/C,SAAS,KAAK,KAAK,GAAG,SAAS,GAAG,kBAAkB,KAAK,GAAG,KAAK,OAAO,KAAA;GACxE,QAAQ,sBAAsB,KAAK,WAAW,mBAAmB,KAAK,EAAE,IAAI,KAAA;GAC5E,gBAAgB,aAAa,IAAI;EACpC,CAAA;CAET;CACA,MAAM,mBAAmB,SAAS,iBAAiB,CAAC,GAAG,SAAS,aAAa,IAAI;CAEjF,IAAI,OACA,OAAO,oBAAC,YAAD;EAAY,OAAO,SAAS,OAAO;EAAW,SAAS,OAAO,KAAK;CAAI,CAAA;CAGlF,OACI,oBAAC,WAAD;EACU;EACN,SAAS;EACA;EACT,YAAY,MAAM;EAElB,kBAAA;EACA,uBAAuB;EACvB,aAAa,EAAE,aAAa,SAAS,QAAQ,OAAO,QAAQ,iBAAiB,CAAC;CACjF,CAAA;AAET"}
+{"version":3,"file":"Table.js","names":[],"sources":["../../../../src/component/organism/Table/Table.tsx"],"sourcesContent":["'use client';\n\nimport { ReactElement, useMemo } from 'react';\n\nimport { Box } from '@mantine/core';\nimport { DataTableColumn } from 'mantine-datatable';\n\nimport DataTableView from '../ViewTable/DataTableView';\nimport { SetRecords, TableData } from './TableData';\nimport RowActions from './RowActions';\nimport { ListDataSource } from '../../../data/ListDataSource';\nimport { KitMessages } from '../../../i18n/KitMessages';\nimport { Identifiable } from '../../../model/Identifiable';\nimport { useKitConfig } from '../../../provider/useKit';\nimport { FormRouteSegments } from '../../../router/FormRouteSegments';\nimport ErrorAlert from '../../atom/ErrorAlert/ErrorAlert';\nimport { showErrorNotification, showSuccessNotification } from '../../../util/Notifications';\n\n/*\nColor of the row under the mouse. The default color of mantine-datatable (gray-1) is barely distinguishable from the\nzebra stripes (gray-0), so the highlight went unnoticed. The light variant of the primary color adapts to the light and\ndark color schemes.\n*/\nconst ROW_HOVER_COLOR = 'var(--mantine-primary-color-light)';\n\n/** Which actions the table shows for each record. */\nexport type ActionsSettings = {\n    /** Whether the actions column is shown. */\n    canShowActions: boolean;\n\n    /** Whether the view action is shown. */\n    canView: boolean;\n\n    /** Whether the edit action is shown. */\n    canEdit: boolean;\n\n    /** Whether the delete action is shown. */\n    canDelete: boolean;\n};\n\n/** Every action shown, used for the settings the caller does not give. */\nconst DEFAULT_ACTIONS_SETTINGS: ActionsSettings = {\n    canShowActions: true,\n    canView: true,\n    canEdit: true,\n    canDelete: true\n};\n\n/** Props of the {@link Table}. */\ntype TableProps<M extends Identifiable, S extends ListDataSource<M>> = {\n    /**\n     * Records and their pagination and sort, given by `useClientPagination` (sorted and paginated in the browser) or\n     * `useServerPagination` (sorted and paginated by the backend).\n     */\n    data: TableData<M>;\n\n    /** Source of the records, which deletes them (e.g. a service that accesses an API). */\n    service: S;\n\n    /** Columns of the table. */\n    columns: DataTableColumn<M>[];\n\n    /** Base path of the pages of the records (e.g. `/region`), used to build the view and edit URLs. */\n    basePath: string;\n\n    /** Which actions are shown; the ones not given are shown. */\n    actionsSettings?: Partial<ActionsSettings>;\n\n    /**\n     * Called by the edit action instead of opening the edit page of the record.\n     * @param itemId id of the record to edit\n     */\n    customEditFunction?: (itemId: M['id']) => void;\n\n    /**\n     * Builds the URL opened to view a record (click on the row or on the view icon).\n     * If absent, the default route is used: `${basePath}/<view segment>/${item.id}`.\n     */\n    getViewUrl?: (item: M) => string;\n};\n\n/**\n * Returns the view URL of a record: the one of `getViewUrl`, if given; otherwise, the default view route.\n * @param props props of the table\n * @param item record\n * @param segments URL segments of the form pages\n */\nfunction viewUrl<M extends Identifiable, S extends ListDataSource<M>>(\n    props: TableProps<M, S>,\n    item: M,\n    segments: FormRouteSegments\n): string {\n    return props.getViewUrl ? props.getViewUrl(item) : `${props.basePath}/${segments.view}/${item.id}`;\n}\n\n/**\n * Creates the function that deletes a record and reloads the table.\n * @param setData function that sets the records of the table\n * @param service source of the records, which deletes them\n * @param reload fetches the records again after the deletion\n * @param messages texts of the locale\n * @return a function that receives the record to delete and returns a promise resolved when it is deleted\n */\nfunction getDeleteRecordFn<M extends Identifiable, S extends ListDataSource<M>>(\n    setData: SetRecords<M>,\n    service: S,\n    reload: () => Promise<void>,\n    messages: KitMessages\n): (item: M) => Promise<void> {\n    return async (item: M) => {\n        const id = item?.id ?? 0;\n\n        // Without an id, the record was added only to the array and was not sent to the backend: just remove it.\n        if (!id) {\n            setData(prevData => prevData.filter(current => current !== item));\n            return;\n        }\n\n        try {\n            await service.delete(id);\n            showSuccessNotification(messages.table.deleteSuccess, messages.common.success);\n            await reload();\n        } catch (e) {\n            showErrorNotification(e, undefined, messages.common.error);\n        }\n    };\n}\n\n/**\n * A table that shows the records of a data source, with the view, edit and delete actions, or an alert when they cannot\n * be fetched. Clicking a row opens the record. Its `data` comes from `useClientPagination` or `useServerPagination`,\n * which define where the records are sorted and paginated.\n * @template M type of the records, shown one per row\n * @template S source of the records (e.g. a service that accesses an API)\n */\nconst Table = <M extends Identifiable, S extends ListDataSource<M>>(props: TableProps<M, S>): ReactElement => {\n    const { service, columns, basePath, customEditFunction, data } = props;\n    const { setRecords, reload } = data;\n    const { router, messages, formRouteSegments } = useKitConfig();\n    const navigate = router.useNavigate();\n    const settings: ActionsSettings = { ...DEFAULT_ACTIONS_SETTINGS, ...props.actionsSettings };\n\n    const deleteRecord = useMemo(\n        () => getDeleteRecordFn(setRecords, service, reload, messages),\n        [setRecords, service, reload, messages]\n    );\n\n    const actionsColumn: DataTableColumn<M> = {\n        accessor: 'actions',\n        title: <Box mr={6}>{messages.table.actions}</Box>,\n        textAlign: 'right',\n        render: item => (\n            <RowActions\n                {...settings}\n                viewUrl={viewUrl(props, item, formRouteSegments)}\n                editUrl={item.id ? `${basePath}/${formRouteSegments.edit}/${item.id}` : undefined}\n                onEdit={customEditFunction && item.id ? () => customEditFunction(item.id) : undefined}\n                onDelete={() => deleteRecord(item)}\n            />\n        )\n    };\n    const effectiveColumns = settings.canShowActions ? [...columns, actionsColumn] : columns;\n\n    if (data.error) {\n        return <ErrorAlert title={messages.common.loadError} message={String(data.error)} />;\n    }\n\n    return (\n        <DataTableView\n            records={data.records}\n            state={data.tableState}\n            paginated={data.paginated}\n            columns={effectiveColumns}\n            loading={data.loading}\n            // Highlights the row under the mouse, to show that clicking it opens the record, as the view icon does.\n            highlightOnHover\n            highlightOnHoverColor={ROW_HOVER_COLOR}\n            onRowClick={({ record }) => navigate(viewUrl(props, record, formRouteSegments))}\n        />\n    );\n};\n\nexport default Table;\n"],"mappings":";;;;;;;;;;AAuBA,IAAM,kBAAkB;;AAkBxB,IAAM,2BAA4C;CAC9C,gBAAgB;CAChB,SAAS;CACT,SAAS;CACT,WAAW;AACf;;;;;;;AAyCA,SAAS,QACL,OACA,MACA,UACM;CACN,OAAO,MAAM,aAAa,MAAM,WAAW,IAAI,IAAI,GAAG,MAAM,SAAS,GAAG,SAAS,KAAK,GAAG,KAAK;AAClG;;;;;;;;;AAUA,SAAS,kBACL,SACA,SACA,QACA,UAC0B;CAC1B,OAAO,OAAO,SAAY;EACtB,MAAM,KAAK,MAAM,MAAM;EAGvB,IAAI,CAAC,IAAI;GACL,SAAQ,aAAY,SAAS,QAAO,YAAW,YAAY,IAAI,CAAC;GAChE;EACJ;EAEA,IAAI;GACA,MAAM,QAAQ,OAAO,EAAE;GACvB,wBAAwB,SAAS,MAAM,eAAe,SAAS,OAAO,OAAO;GAC7E,MAAM,OAAO;EACjB,SAAS,GAAG;GACR,sBAAsB,GAAG,KAAA,GAAW,SAAS,OAAO,KAAK;EAC7D;CACJ;AACJ;;;;;;;;AASA,IAAM,SAA8D,UAA0C;CAC1G,MAAM,EAAE,SAAS,SAAS,UAAU,oBAAoB,SAAS;CACjE,MAAM,EAAE,YAAY,WAAW;CAC/B,MAAM,EAAE,QAAQ,UAAU,sBAAsB,aAAa;CAC7D,MAAM,WAAW,OAAO,YAAY;CACpC,MAAM,WAA4B;EAAE,GAAG;EAA0B,GAAG,MAAM;CAAgB;CAE1F,MAAM,eAAe,cACX,kBAAkB,YAAY,SAAS,QAAQ,QAAQ,GAC7D;EAAC;EAAY;EAAS;EAAQ;CAAQ,CAC1C;CAEA,MAAM,gBAAoC;EACtC,UAAU;EACV,OAAO,oBAAC,KAAD;GAAK,IAAI;GAAI,UAAA,SAAS,MAAM;EAAa,CAAA;EAChD,WAAW;EACX,SAAQ,SACJ,oBAAC,YAAD;GACI,GAAI;GACJ,SAAS,QAAQ,OAAO,MAAM,iBAAiB;GAC/C,SAAS,KAAK,KAAK,GAAG,SAAS,GAAG,kBAAkB,KAAK,GAAG,KAAK,OAAO,KAAA;GACxE,QAAQ,sBAAsB,KAAK,WAAW,mBAAmB,KAAK,EAAE,IAAI,KAAA;GAC5E,gBAAgB,aAAa,IAAI;EACpC,CAAA;CAET;CACA,MAAM,mBAAmB,SAAS,iBAAiB,CAAC,GAAG,SAAS,aAAa,IAAI;CAEjF,IAAI,KAAK,OACL,OAAO,oBAAC,YAAD;EAAY,OAAO,SAAS,OAAO;EAAW,SAAS,OAAO,KAAK,KAAK;CAAI,CAAA;CAGvF,OACI,oBAAC,eAAD;EACI,SAAS,KAAK;EACd,OAAO,KAAK;EACZ,WAAW,KAAK;EAChB,SAAS;EACT,SAAS,KAAK;EAEd,kBAAA;EACA,uBAAuB;EACvB,aAAa,EAAE,aAAa,SAAS,QAAQ,OAAO,QAAQ,iBAAiB,CAAC;CACjF,CAAA;AAET"}

package/dist/component/organism/Table/TableData.d.ts

@@ -0,0 +1,24 @@
+import { TableState } from '../ViewTable/TableState';
+/** Function that sets the records of a table, as the one of `useState`. */
+export type SetRecords<M> = (value: ((prevState: M[]) => M[]) | M[]) => void;
+/**
+ * Records of a {@link Table} and their pagination and sort, given by `useClientPagination` (sorted and paginated in the
+ * browser) or `useServerPagination` (sorted and paginated by the backend).
+ * @template M type of the records
+ */
+export type TableData<M> = {
+    /** Records shown, already sorted and cut to the current page. */
+    records: M[];
+    /** Changes the records of the table without fetching them (e.g. to remove one that was not saved yet). */
+    setRecords: SetRecords<M>;
+    /** Fetches the records again (e.g. after a deletion). */
+    reload: () => Promise<void>;
+    /** Whether the records are being fetched. */
+    loading: boolean;
+    /** Error of the last fetch; `null` if there is none. */
+    error: unknown;
+    /** Pagination and sort of the table. */
+    tableState: TableState<M>;
+    /** Whether the pagination controls are shown. */
+    paginated: boolean;
+};

package/dist/component/organism/Table/TableData.js

@@ -0,0 +1 @@
+"use client";

package/dist/component/organism/Table/useClientPagination.d.ts

@@ -0,0 +1,21 @@
+import { TableData } from './TableData';
+import { ListDataSource } from '../../../data/ListDataSource';
+import { Identifiable } from '../../../model/Identifiable';
+/** Options of {@link useClientPagination}. */
+export type ClientPaginationOptions = {
+    /** Whether the table is paginated; defaults to true. Without it, every record is shown. */
+    pagination?: boolean;
+};
+/** Fetches all records of a table. */
+export type FetchAll<M> = () => Promise<M[]>;
+/**
+ * Fetches all records of a {@link Table} at once (e.g. from an API), which the browser then sorts (following the locale)
+ * and paginates.
+ * @template M type of the records
+ * @param source an object whose `findAll` fetches all records (e.g. a service), or a function that fetches them (e.g.
+ *        with a filter). It must be stable (e.g. a module constant, or a function created with `useCallback`), since a
+ *        new object or function fetches again: a `new Service()` inside the component would fetch on every render
+ * @param options whether the table is paginated
+ * @return the data to give to the `data` prop of the {@link Table}
+ */
+export declare function useClientPagination<M extends Identifiable>(source: Pick<ListDataSource<M>, 'findAll'> | FetchAll<M>, { pagination }?: ClientPaginationOptions): TableData<M>;

package/dist/component/organism/Table/useClientPagination.js

@@ -0,0 +1,43 @@
+"use client";
+import { useClientTableState } from "../ViewTable/useClientTableState.js";
+import useService from "../../../hook/useService.js";
+import { useKitConfig } from "../../../provider/useKit.js";
+import { useCallback, useEffect, useMemo, useState } from "react";
+// src/component/organism/Table/useClientPagination.ts
+/** Initial records of the table, while they are fetched; a single constant, so it is stable across renders. */
+var NO_RECORDS = [];
+/**
+* Fetches all records of a {@link Table} at once (e.g. from an API), which the browser then sorts (following the locale)
+* and paginates.
+* @template M type of the records
+* @param source an object whose `findAll` fetches all records (e.g. a service), or a function that fetches them (e.g.
+*        with a filter). It must be stable (e.g. a module constant, or a function created with `useCallback`), since a
+*        new object or function fetches again: a `new Service()` inside the component would fetch on every render
+* @param options whether the table is paginated
+* @return the data to give to the `data` prop of the {@link Table}
+*/
+function useClientPagination(source, { pagination = true } = {}) {
+	const fetchAll = useMemo(() => typeof source === "function" ? source : () => source.findAll(), [source]);
+	const { locale } = useKitConfig();
+	const { data: fetchedData, loading, error } = useService(fetchAll, NO_RECORDS);
+	const [data, setData] = useState(NO_RECORDS);
+	useEffect(() => setData(fetchedData), [fetchedData]);
+	const reload = useCallback(async () => setData(await fetchAll()), [fetchAll]);
+	const { records, ...tableState } = useClientTableState({
+		data,
+		pagination,
+		locale
+	});
+	return {
+		records,
+		setRecords: setData,
+		reload,
+		loading,
+		error,
+		tableState,
+		paginated: pagination
+	};
+}
+export { useClientPagination };
+
+//# sourceMappingURL=useClientPagination.js.map

package/dist/component/organism/Table/useClientPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useClientPagination.js","names":[],"sources":["../../../../src/component/organism/Table/useClientPagination.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useState } from 'react';\n\nimport { TableData } from './TableData';\nimport { useClientTableState } from '../ViewTable/useClientTableState';\nimport { ListDataSource } from '../../../data/ListDataSource';\nimport useService from '../../../hook/useService';\nimport { Identifiable } from '../../../model/Identifiable';\nimport { useKitConfig } from '../../../provider/useKit';\n\n/** Initial records of the table, while they are fetched; a single constant, so it is stable across renders. */\nconst NO_RECORDS: never[] = [];\n\n/** Options of {@link useClientPagination}. */\nexport type ClientPaginationOptions = {\n    /** Whether the table is paginated; defaults to true. Without it, every record is shown. */\n    pagination?: boolean;\n};\n\n/** Fetches all records of a table. */\nexport type FetchAll<M> = () => Promise<M[]>;\n\n/**\n * Fetches all records of a {@link Table} at once (e.g. from an API), which the browser then sorts (following the locale)\n * and paginates.\n * @template M type of the records\n * @param source an object whose `findAll` fetches all records (e.g. a service), or a function that fetches them (e.g.\n *        with a filter). It must be stable (e.g. a module constant, or a function created with `useCallback`), since a\n *        new object or function fetches again: a `new Service()` inside the component would fetch on every render\n * @param options whether the table is paginated\n * @return the data to give to the `data` prop of the {@link Table}\n */\nexport function useClientPagination<M extends Identifiable>(\n    source: Pick<ListDataSource<M>, 'findAll'> | FetchAll<M>,\n    { pagination = true }: ClientPaginationOptions = {}\n): TableData<M> {\n    // Calls the method on the object, so it keeps its `this`.\n    const fetchAll = useMemo(() => (typeof source === 'function' ? source : () => source.findAll()), [source]);\n    const { locale } = useKitConfig();\n    const { data: fetchedData, loading, error } = useService<M[]>(fetchAll, NO_RECORDS);\n    const [data, setData] = useState<M[]>(NO_RECORDS);\n\n    useEffect(() => setData(fetchedData), [fetchedData]);\n\n    const reload = useCallback(async () => setData(await fetchAll()), [fetchAll]);\n    const { records, ...tableState } = useClientTableState({ data, pagination, locale });\n\n    return { records, setRecords: setData, reload, loading, error, tableState, paginated: pagination };\n}\n"],"mappings":";;;;;;;AAUA,IAAM,aAAsB,CAAC;;;;;;;;;;;AAqB7B,SAAgB,oBACZ,QACA,EAAE,aAAa,SAAkC,CAAC,GACtC;CAEZ,MAAM,WAAW,cAAe,OAAO,WAAW,aAAa,eAAe,OAAO,QAAQ,GAAI,CAAC,MAAM,CAAC;CACzG,MAAM,EAAE,WAAW,aAAa;CAChC,MAAM,EAAE,MAAM,aAAa,SAAS,UAAU,WAAgB,UAAU,UAAU;CAClF,MAAM,CAAC,MAAM,WAAW,SAAc,UAAU;CAEhD,gBAAgB,QAAQ,WAAW,GAAG,CAAC,WAAW,CAAC;CAEnD,MAAM,SAAS,YAAY,YAAY,QAAQ,MAAM,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;CAC5E,MAAM,EAAE,SAAS,GAAG,eAAe,oBAAoB;EAAE;EAAM;EAAY;CAAO,CAAC;CAEnF,OAAO;EAAE;EAAS,YAAY;EAAS;EAAQ;EAAS;EAAO;EAAY,WAAW;CAAW;AACrG"}

package/dist/component/organism/Table/useServerPagination.d.ts

@@ -0,0 +1,24 @@
+import { TableData } from './TableData';
+import { PageDataSource } from '../../../data/PageDataSource';
+import { FetchPage } from '../../../data/PageRequest';
+/** Options of {@link useServerPagination}. */
+export type ServerPaginationOptions = {
+    /**
+     * Number of the first page in the requests to the backend (e.g. 0 for Spring Data); defaults to 1. It only changes
+     * the `page` sent to the backend: the table always shows the pages starting at 1.
+     */
+    firstPage?: number;
+};
+/**
+ * Fetches one page at a time of a {@link Table}, already sorted and paginated by the backend. It goes back to page 1
+ * when the page size, the sort or the filter changes, and to the last existing page when the current one no longer
+ * exists (e.g. its last record was deleted).
+ * @template M type of the records
+ * @param source an object whose `findPage` fetches a page (e.g. a service), or a function that fetches it (e.g. with a
+ *        filter). A new object or function means that the filter changed, so it goes back to page 1 and fetches again.
+ *        Keep it stable otherwise (e.g. a module constant, or a function created with `useCallback`): a
+ *        `new Service()` inside the component would fetch on every render
+ * @param options number of the first page for the backend
+ * @return the data to give to the `data` prop of the {@link Table}
+ */
+export declare function useServerPagination<M>(source: PageDataSource<M> | FetchPage<M>, { firstPage }?: ServerPaginationOptions): TableData<M>;

package/dist/component/organism/Table/useServerPagination.js

@@ -0,0 +1,105 @@
+"use client";
+import { DEFAULT_SORT_STATUS, PAGE_SIZES } from "../ViewTable/TableState.js";
+import useService from "../../../hook/useService.js";
+import { useCallback, useEffect, useMemo, useState } from "react";
+// src/component/organism/Table/useServerPagination.ts
+/** Result before the first response; a single constant, so it is stable across renders. */
+var NO_PAGE = {
+	records: [],
+	totalRecords: 0
+};
+/**
+* Builds what is sent to the backend. The table state keeps the `columnAccessor`, as the header needs it to show the
+* sort indicator, but the backend must receive the `sortKey`, when the column has one.
+* @param request page (starting at {@link FIRST_PAGE}), size and sort chosen in the table
+* @param firstPage number of the first page for the backend
+*/
+function toBackendRequest(request, firstPage) {
+	const { page, sort } = request;
+	return {
+		...request,
+		page: page - 1 + firstPage,
+		sort: {
+			...sort,
+			columnAccessor: sort.sortKey ?? sort.columnAccessor
+		}
+	};
+}
+/**
+* Fetches one page at a time of a {@link Table}, already sorted and paginated by the backend. It goes back to page 1
+* when the page size, the sort or the filter changes, and to the last existing page when the current one no longer
+* exists (e.g. its last record was deleted).
+* @template M type of the records
+* @param source an object whose `findPage` fetches a page (e.g. a service), or a function that fetches it (e.g. with a
+*        filter). A new object or function means that the filter changed, so it goes back to page 1 and fetches again.
+*        Keep it stable otherwise (e.g. a module constant, or a function created with `useCallback`): a
+*        `new Service()` inside the component would fetch on every render
+* @param options number of the first page for the backend
+* @return the data to give to the `data` prop of the {@link Table}
+*/
+function useServerPagination(source, { firstPage = 1 } = {}) {
+	const fetchPage = useMemo(() => typeof source === "function" ? source : (request) => source.findPage(request), [source]);
+	const [request, setRequest] = useState({
+		page: 1,
+		size: PAGE_SIZES[0],
+		sort: DEFAULT_SORT_STATUS
+	});
+	const [previousFetchPage, setPreviousFetchPage] = useState(() => fetchPage);
+	if (fetchPage !== previousFetchPage) {
+		setPreviousFetchPage(() => fetchPage);
+		setRequest((current) => ({
+			...current,
+			page: 1
+		}));
+	}
+	const fetchCurrentPage = useCallback(() => fetchPage(toBackendRequest(request, firstPage)), [
+		fetchPage,
+		request,
+		firstPage
+	]);
+	const { data, loading, error } = useService(fetchCurrentPage, NO_PAGE);
+	const [records, setRecords] = useState([]);
+	useEffect(() => setRecords(data.records), [data]);
+	const lastPage = Math.max(Math.ceil(data.totalRecords / request.size), 1);
+	useEffect(() => {
+		if (!loading && request.page > lastPage) setRequest((current) => ({
+			...current,
+			page: lastPage
+		}));
+	}, [
+		loading,
+		request.page,
+		lastPage
+	]);
+	return {
+		records,
+		setRecords,
+		reload: useCallback(async () => setRequest((current) => ({ ...current })), []),
+		loading,
+		error,
+		tableState: {
+			page: request.page,
+			pageSize: request.size,
+			sortStatus: request.sort,
+			totalRecords: data.totalRecords,
+			onPageChange: (page) => setRequest((current) => ({
+				...current,
+				page
+			})),
+			onPageSizeChange: (size) => setRequest((current) => ({
+				...current,
+				size,
+				page: 1
+			})),
+			onSortStatusChange: (sort) => setRequest((current) => ({
+				...current,
+				sort,
+				page: 1
+			}))
+		},
+		paginated: true
+	};
+}
+export { useServerPagination };
+
+//# sourceMappingURL=useServerPagination.js.map

package/dist/component/organism/Table/useServerPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useServerPagination.js","names":[],"sources":["../../../../src/component/organism/Table/useServerPagination.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useState } from 'react';\n\nimport { TableData } from './TableData';\nimport { DEFAULT_SORT_STATUS, FIRST_PAGE, PAGE_SIZES } from '../ViewTable/TableState';\nimport { PageDataSource } from '../../../data/PageDataSource';\nimport { FetchPage, PageRequest, PageResult } from '../../../data/PageRequest';\nimport useService from '../../../hook/useService';\n\n/** Result before the first response; a single constant, so it is stable across renders. */\nconst NO_PAGE: PageResult<never> = { records: [], totalRecords: 0 };\n\n/** Options of {@link useServerPagination}. */\nexport type ServerPaginationOptions = {\n    /**\n     * Number of the first page in the requests to the backend (e.g. 0 for Spring Data); defaults to 1. It only changes\n     * the `page` sent to the backend: the table always shows the pages starting at 1.\n     */\n    firstPage?: number;\n};\n\n/**\n * Builds what is sent to the backend. The table state keeps the `columnAccessor`, as the header needs it to show the\n * sort indicator, but the backend must receive the `sortKey`, when the column has one.\n * @param request page (starting at {@link FIRST_PAGE}), size and sort chosen in the table\n * @param firstPage number of the first page for the backend\n */\nfunction toBackendRequest<M>(request: PageRequest<M>, firstPage: number): PageRequest<M> {\n    const { page, sort } = request;\n\n    return {\n        ...request,\n        page: page - FIRST_PAGE + firstPage,\n        sort: { ...sort, columnAccessor: sort.sortKey ?? sort.columnAccessor }\n    };\n}\n\n/**\n * Fetches one page at a time of a {@link Table}, already sorted and paginated by the backend. It goes back to page 1\n * when the page size, the sort or the filter changes, and to the last existing page when the current one no longer\n * exists (e.g. its last record was deleted).\n * @template M type of the records\n * @param source an object whose `findPage` fetches a page (e.g. a service), or a function that fetches it (e.g. with a\n *        filter). A new object or function means that the filter changed, so it goes back to page 1 and fetches again.\n *        Keep it stable otherwise (e.g. a module constant, or a function created with `useCallback`): a\n *        `new Service()` inside the component would fetch on every render\n * @param options number of the first page for the backend\n * @return the data to give to the `data` prop of the {@link Table}\n */\nexport function useServerPagination<M>(\n    source: PageDataSource<M> | FetchPage<M>,\n    { firstPage = FIRST_PAGE }: ServerPaginationOptions = {}\n): TableData<M> {\n    // Calls the method on the object, so it keeps its `this`.\n    const fetchPage = useMemo<FetchPage<M>>(\n        () => (typeof source === 'function' ? source : request => source.findPage(request)),\n        [source]\n    );\n    // A single object, so a copy of it fetches the same page again, and a change is always a single fetch.\n    const [request, setRequest] = useState<PageRequest<M>>({\n        page: FIRST_PAGE,\n        size: PAGE_SIZES[0],\n        sort: DEFAULT_SORT_STATUS\n    });\n    const [previousFetchPage, setPreviousFetchPage] = useState(() => fetchPage);\n\n    /* Done while rendering, as an effect would first fetch the new filter with the old page.\n       See https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes */\n    if (fetchPage !== previousFetchPage) {\n        setPreviousFetchPage(() => fetchPage);\n        setRequest(current => ({ ...current, page: FIRST_PAGE }));\n    }\n\n    const fetchCurrentPage = useCallback(\n        () => fetchPage(toBackendRequest(request, firstPage)),\n        [fetchPage, request, firstPage]\n    );\n    const { data, loading, error } = useService<PageResult<M>>(fetchCurrentPage, NO_PAGE);\n    const [records, setRecords] = useState<M[]>([]);\n\n    useEffect(() => setRecords(data.records), [data]);\n\n    const lastPage = Math.max(Math.ceil(data.totalRecords / request.size), FIRST_PAGE);\n\n    // The current page may not exist anymore (e.g. its last record was deleted).\n    useEffect(() => {\n        if (!loading && request.page > lastPage) setRequest(current => ({ ...current, page: lastPage }));\n    }, [loading, request.page, lastPage]);\n\n    const reload = useCallback(async () => setRequest(current => ({ ...current })), []);\n\n    return {\n        records,\n        setRecords,\n        reload,\n        loading,\n        error,\n        tableState: {\n            page: request.page,\n            pageSize: request.size,\n            sortStatus: request.sort,\n            totalRecords: data.totalRecords,\n            onPageChange: page => setRequest(current => ({ ...current, page })),\n            onPageSizeChange: size => setRequest(current => ({ ...current, size, page: FIRST_PAGE })),\n            onSortStatusChange: sort => setRequest(current => ({ ...current, sort, page: FIRST_PAGE }))\n        },\n        paginated: true\n    };\n}\n"],"mappings":";;;;;;AASA,IAAM,UAA6B;CAAE,SAAS,CAAC;CAAG,cAAc;AAAE;;;;;;;AAiBlE,SAAS,iBAAoB,SAAyB,WAAmC;CACrF,MAAM,EAAE,MAAM,SAAS;CAEvB,OAAO;EACH,GAAG;EACH,MAAM,OAAA,IAAoB;EAC1B,MAAM;GAAE,GAAG;GAAM,gBAAgB,KAAK,WAAW,KAAK;EAAe;CACzE;AACJ;;;;;;;;;;;;;AAcA,SAAgB,oBACZ,QACA,EAAE,YAAA,MAAoD,CAAC,GAC3C;CAEZ,MAAM,YAAY,cACP,OAAO,WAAW,aAAa,UAAS,YAAW,OAAO,SAAS,OAAO,GACjF,CAAC,MAAM,CACX;CAEA,MAAM,CAAC,SAAS,cAAc,SAAyB;EACnD,MAAA;EACA,MAAM,WAAW;EACjB,MAAM;CACV,CAAC;CACD,MAAM,CAAC,mBAAmB,wBAAwB,eAAe,SAAS;CAI1E,IAAI,cAAc,mBAAmB;EACjC,2BAA2B,SAAS;EACpC,YAAW,aAAY;GAAE,GAAG;GAAS,MAAA;EAAiB,EAAE;CAC5D;CAEA,MAAM,mBAAmB,kBACf,UAAU,iBAAiB,SAAS,SAAS,CAAC,GACpD;EAAC;EAAW;EAAS;CAAS,CAClC;CACA,MAAM,EAAE,MAAM,SAAS,UAAU,WAA0B,kBAAkB,OAAO;CACpF,MAAM,CAAC,SAAS,cAAc,SAAc,CAAC,CAAC;CAE9C,gBAAgB,WAAW,KAAK,OAAO,GAAG,CAAC,IAAI,CAAC;CAEhD,MAAM,WAAW,KAAK,IAAI,KAAK,KAAK,KAAK,eAAe,QAAQ,IAAI,GAAA,CAAa;CAGjF,gBAAgB;EACZ,IAAI,CAAC,WAAW,QAAQ,OAAO,UAAU,YAAW,aAAY;GAAE,GAAG;GAAS,MAAM;EAAS,EAAE;CACnG,GAAG;EAAC;EAAS,QAAQ;EAAM;CAAQ,CAAC;CAIpC,OAAO;EACH;EACA;EACA,QALW,YAAY,YAAY,YAAW,aAAY,EAAE,GAAG,QAAQ,EAAE,GAAG,CAAC,CAK7E;EACA;EACA;EACA,YAAY;GACR,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,YAAY,QAAQ;GACpB,cAAc,KAAK;GACnB,eAAc,SAAQ,YAAW,aAAY;IAAE,GAAG;IAAS;GAAK,EAAE;GAClE,mBAAkB,SAAQ,YAAW,aAAY;IAAE,GAAG;IAAS;IAAM,MAAA;GAAiB,EAAE;GACxF,qBAAoB,SAAQ,YAAW,aAAY;IAAE,GAAG;IAAS;IAAM,MAAA;GAAiB,EAAE;EAC9F;EACA,WAAW;CACf;AACJ"}

package/dist/component/organism/ViewTable/DataTableView.d.ts

@@ -0,0 +1,39 @@
+import { DataTableColumn, DataTablePaginationProps, DataTableProps } from 'mantine-datatable';
+import { Identifiable } from '../../../model/Identifiable';
+import { TableState } from './TableState';
+/** Function that defines extra attributes (e.g. aria-label) for each pagination control button. */
+type PaginationControlPropsGetter = Extract<DataTablePaginationProps, {
+    page: number;
+}>['getPaginationControlProps'];
+/**
+ * Props of the {@link DataTable} passed straight through.
+ * Only the props actually used by the callers are accepted: using `Partial<DataTableProps<M>>` makes TypeScript combine
+ * the variants of the `DataTableProps` union with the ones of `paginationProps`, which exhausts the memory of `tsc`.
+ */
+type DataTablePassThroughProps<M extends Identifiable> = Pick<DataTableProps<M>, 'onRowClick' | 'rowStyle' | 'noRecordsText' | 'highlightOnHover' | 'highlightOnHoverColor' | 'className' | 'minHeight' | 'withColumnBorders' | 'verticalSpacing' | 'horizontalSpacing'>;
+/** Props of the {@link DataTableView} that do not depend on where the table is sorted and paginated. */
+export type DataTableViewBaseProps<M extends Identifiable> = {
+    columns: DataTableColumn<M>[];
+    /** Whether the records are being loaded. */
+    loading?: boolean;
+    /** Shows the ID column, automatically added to the given columns. */
+    showIdColumn?: boolean;
+    /** Extra attributes for the pagination control buttons, when the table is paginated. */
+    getPaginationControlProps?: PaginationControlPropsGetter;
+} & DataTablePassThroughProps<M>;
+/** Props of the {@link DataTableView}. */
+type DataTableViewProps<M extends Identifiable> = DataTableViewBaseProps<M> & {
+    /** Records shown, already sorted and cut to the current page. */
+    records: M[];
+    /** Pagination and sort of the table. */
+    state: TableState<M>;
+    /** Whether the pagination controls are shown. */
+    paginated: boolean;
+};
+/**
+ * Shows records as received, with the given pagination and sort (e.g. kept by a backend that paginates). It is the
+ * visual part of the tables, on top of the mantine-datatable `DataTable`, with the texts of the locale.
+ * @template M type of the records, shown one per row
+ */
+declare const DataTableView: <M extends Identifiable>({ records, state, paginated, columns, loading, showIdColumn, getPaginationControlProps, ...rest }: DataTableViewProps<M>) => import("react/jsx-runtime").JSX.Element;
+export default DataTableView;