@espresso-lab/mantine-data-table 2.1.14 → 2.2.1

package/README.md

@@ -1,7 +1,8 @@
-# Mantine Data Table 🚀
+# Mantine Data Table
 
-This is a simple wrapper for the [Mantine Datatable](https://icflorescu.github.io/mantine-datatable/) library to work
-with a single configuration object.
+A config-driven wrapper around [mantine-datatable](https://icflorescu.github.io/mantine-datatable/).
+Describe a table once as a list of fields and get sorting, pagination, filtering, CRUD modals,
+row expansion and a responsive mobile card layout — backed by [TanStack Query](https://tanstack.com/query).
 
 [![License](https://img.shields.io/badge/License-MIT-blue)](#license)
 [![NPM Version](https://img.shields.io/npm/v/@espresso-lab/mantine-data-table.svg?style=flat)](https://www.npmjs.com/package/@espresso-lab/mantine-data-table)
@@ -11,4 +12,160 @@ with a single configuration object.
 
 ```bash
 npm i @espresso-lab/mantine-data-table
-```
+```
+
+Peer dependencies you need to install: `@mantine/core`, `@mantine/dates`, `@mantine/form`,
+`@mantine/hooks`, `@tabler/icons-react`, `react` and `react-dom`.
+(`mantine-datatable` and `@tanstack/react-query` come bundled.)
+
+## Setup
+
+Wrap your app in `DataTableProvider`. It provides the base URL, a TanStack Query client and the
+headers sent with every request.
+
+```tsx
+import "@mantine/core/styles.css";
+import "@mantine/dates/styles.css";
+import "mantine-datatable/styles.css";
+
+import { MantineProvider } from "@mantine/core";
+import { QueryClient } from "@tanstack/react-query";
+import { DataTableProvider } from "@espresso-lab/mantine-data-table";
+
+const queryClient = new QueryClient();
+
+export function Root() {
+  return (
+    <MantineProvider>
+      <DataTableProvider
+        baseUrl="https://api.example.com"
+        queryClient={queryClient}
+        getHeaders={async () => ({ Authorization: `Bearer ${await getToken()}` })}
+      >
+        <App />
+      </DataTableProvider>
+    </MantineProvider>
+  );
+}
+```
+
+## Usage
+
+A table is described by a `queryKey`, an `apiPath` and a list of `fields`. The component fetches
+`GET {apiPath}`, renders the rows and wires create/update/delete against the same path.
+
+```tsx
+import { DataTable, Field } from "@espresso-lab/mantine-data-table";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+const fields: Field<User>[] = [
+  {
+    id: "name",
+    list: true, create: true, update: true, delete: true,
+    required: true,
+    column: { accessor: "name", title: "Name", sortable: true },
+  },
+  {
+    id: "email",
+    list: true, create: true, update: true, delete: true,
+    column: { accessor: "email", title: "Email" },
+  },
+  {
+    id: "active",
+    list: true, create: true, update: true, delete: true,
+    type: "boolean",
+    column: { accessor: "active", title: "Active" },
+  },
+];
+
+export function Users() {
+  return (
+    <DataTable<User>
+      title="Users"
+      queryKey={["users"]}
+      apiPath="/users"
+      fields={fields}
+      selection
+      pagination
+      mobileCards
+    />
+  );
+}
+```
+
+### Fields
+
+A field describes both a table column and a form input.
+
+| Key | Description |
+| --- | --- |
+| `id` | Unique key; used as the form field name and column accessor fallback. |
+| `list` / `create` / `update` / `delete` | Whether the field shows in the table, the create form, the edit form, and is editable. |
+| `type` | `text` (default), `number`, `date`, `boolean`, `textarea` or `custom`. |
+| `required` | `boolean` or `(values) => boolean`. |
+| `column` | A [mantine-datatable column](https://icflorescu.github.io/mantine-datatable/) — `accessor`, `title`, `render`, `sortable`, `textAlign`, `filter`, `footer`, `hidden`. |
+| `render` | For `type: "custom"` — render your own input. |
+| `defaultValue`, `placeholder`, `step`, `conditional` | Optional. |
+
+### Common props
+
+| Prop | Description |
+| --- | --- |
+| `selection` | Row checkboxes with bulk actions. |
+| `pagination` | Client-side pagination. |
+| `mobileCards` | Render a card list instead of the table below the `sm` breakpoint. |
+| `tabs` | Switch between datasets, each with its own query params and api path. |
+| `actions` | Custom bulk actions on the selected rows. |
+| `rowExpansion` | Expandable rows (see below). |
+| `defaultSort`, `queryParams`, `onRowClick`, `canUpdate`, `canDelete` | Optional. |
+
+## Row expansion
+
+Set `rowExpansion` to render content under a row. A chevron is added to the first column
+automatically; `expandable` controls which rows can open.
+
+```tsx
+import { SubTable } from "@espresso-lab/mantine-data-table";
+
+<DataTable<Account>
+  title="Accounts"
+  queryKey={["accounts"]}
+  apiPath="/accounts"
+  fields={fields}
+  mobileCards
+  rowExpansion={{
+    expandable: (account) => account.entries.length > 0,
+    content: (account, isMobile) => (
+      <SubTable
+        mobile={isMobile}
+        records={account.entries}
+        idAccessor="id"
+        columns={[
+          { accessor: "date", title: "Date", render: (e) => formatDate(e.date) },
+          {
+            accessor: "amount",
+            title: "Amount",
+            textAlign: "right",
+            render: (e) => formatAmount(e.amount),
+            footer: formatAmount(account.total),
+          },
+        ]}
+      />
+    ),
+  }}
+/>;
+```
+
+`SubTable` uses one set of columns for both layouts: a full mantine-datatable on desktop (sorting,
+column filters, footer totals) and a labelled card list on mobile. Add `hideOnMobile: (record) => boolean`
+to a column to drop low-value cells from the mobile cards.
+
+## License
+
+MIT

package/dist/DataTable/CreateModal.d.ts

@@ -1,5 +1,5 @@
 import { BaseEntity } from '../Hooks/useApi';
-import { Field, StepConfig } from './DataTableInner.tsx';
+import { Field, StepConfig } from './DataTable.tsx';
 export interface CreateModalProps<T> {
     fields: Field<T>[];
     onClose: () => void;

package/dist/DataTable/DataTable.d.ts

@@ -1,3 +1,88 @@
-import { BaseEntity } from '../Hooks/useApi.ts';
-import { DataTableProps } from './DataTableInner.tsx';
-export declare function DataTable<T extends BaseEntity>(props: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
+import { BaseEntity } from '../Hooks/useApi';
+import { default as React } from 'react';
+import { DataTableColumn } from 'mantine-datatable';
+import { Filter } from '../utils/filter';
+export type FieldType = "text" | "number" | "boolean" | "custom" | "date" | "textarea";
+export interface Field<T> {
+    id: string;
+    defaultValue?: T[keyof T];
+    required?: boolean | ((values: Partial<T>) => boolean);
+    step?: number;
+    list: boolean;
+    create: boolean;
+    update: boolean;
+    delete: boolean;
+    type?: FieldType;
+    placeholder?: string;
+    conditional?: (values: Partial<T>) => boolean;
+    render?: (values: T, setValues: (values: Partial<T>) => void, hideButtons: (value: boolean) => void, validationProps?: {
+        error?: string;
+        required?: boolean;
+    }) => React.ReactNode;
+    column: DataTableColumn<T>;
+}
+export interface Action<T extends BaseEntity> {
+    icon?: React.ReactNode;
+    label: string;
+    onClick: (records: T[]) => void;
+    disabled?: (records: T[]) => boolean;
+}
+export interface TabOption {
+    value: string;
+    label: string;
+    icon?: React.ReactNode;
+    queryParams?: Record<string, string | number | boolean | null>;
+    apiPath?: string;
+    mutationApiPath?: string;
+}
+export interface StepConfig {
+    label: string;
+    description?: string;
+}
+export interface DataTableProps<T extends BaseEntity> {
+    title?: string | React.ReactNode;
+    queryKey: (string | number)[];
+    connectedQueryKeys?: (string | number)[][];
+    apiPath: string;
+    mutationApiPath?: string;
+    queryParams?: Record<string, string | number | boolean | null>;
+    filters?: Filter[];
+    buttons?: React.ReactNode[];
+    createButtonText?: string;
+    actions?: Action<T>[];
+    selection?: boolean;
+    pagination?: boolean;
+    steps?: StepConfig[];
+    fields: Field<T>[];
+    defaultSort?: {
+        field: string;
+        direction: "asc" | "desc";
+    };
+    onSortChange?: (field: string, direction: "asc" | "desc") => void;
+    tabs?: TabOption[];
+    defaultTab?: string;
+    activeTab?: string | null;
+    onActiveTabChange?: (tabValue: string | null) => void;
+    canUpdate?: (record: T) => boolean;
+    canDelete?: (record: T) => boolean;
+    showRefresh?: boolean;
+    rowExpansion?: {
+        allowMultiple?: boolean;
+        expandable?: (record: T) => boolean;
+        content: (record: T, isMobile: boolean) => React.ReactNode;
+        expanded?: {
+            recordIds: unknown[];
+            onRecordIdsChange: (recordIds: unknown[]) => void;
+        };
+    };
+    onRowClick?: (params: {
+        record: T;
+        index: number;
+        event: React.MouseEvent;
+    }) => void;
+    mobileCards?: boolean;
+    deleteConfirmMessage?: (records: T[]) => React.ReactNode;
+    editRecordId?: string | null;
+    onEditRecordIdChange?: (id: string | null) => void;
+}
+export declare function DataTable<T extends BaseEntity>({ title, queryKey, connectedQueryKeys, apiPath, mutationApiPath, buttons, fields, selection, pagination, filters, actions, steps, defaultSort, onSortChange, createButtonText, queryParams, tabs, defaultTab, activeTab: controlledActiveTab, onActiveTabChange, canUpdate, canDelete, showRefresh, rowExpansion, onRowClick, mobileCards, deleteConfirmMessage, editRecordId, onEditRecordIdChange, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/DataTable/EntityForm.d.ts

@@ -0,0 +1,13 @@
+import { BaseEntity } from '../Hooks/useApi';
+import { Field, StepConfig } from './DataTable.tsx';
+export interface EntityFormProps<T extends BaseEntity> {
+    fields: Field<T>[];
+    steps?: StepConfig[];
+    record?: T;
+    recordId?: string | number;
+    submitting: boolean;
+    error?: Error | null;
+    onPersist: (values: T) => Promise<void>;
+    onClose: () => void;
+}
+export declare function EntityForm<T extends BaseEntity>({ fields, steps, record, recordId, submitting, error, onPersist, onClose, }: EntityFormProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/DataTable/FieldCard.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export interface FieldRow {
+    label: React.ReactNode;
+    value: React.ReactNode;
+}
+export declare function FieldCardRows({ rows }: {
+    readonly rows: readonly FieldRow[];
+}): import("react/jsx-runtime").JSX.Element;
+export declare function FieldCard({ rows }: {
+    readonly rows: readonly FieldRow[];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/DataTable/MobileCardList.d.ts

@@ -1,5 +1,5 @@
 import { BaseEntity } from '../Hooks/useApi';
-import { Action, Field } from './DataTableInner';
+import { Action, Field } from './DataTable';
 import { default as React } from 'react';
 interface SortConfig {
     field: string;
@@ -27,6 +27,7 @@ interface MobileCardListProps<T extends BaseEntity> {
     };
     sort?: SortConfig;
     rowExpansion?: {
+        expandable?: (record: T) => boolean;
         content: (record: T, isMobile: boolean) => React.ReactNode;
         expanded?: {
             recordIds: unknown[];

package/dist/DataTable/SubTable.d.ts

@@ -0,0 +1,9 @@
+import { DataTableColumn, DataTableProps as MantineDataTableProps } from 'mantine-datatable';
+export type SubTableColumn<T> = DataTableColumn<T> & {
+    hideOnMobile?: (record: T) => boolean;
+};
+export type SubTableProps<T> = Omit<MantineDataTableProps<T>, "columns"> & {
+    mobile: boolean;
+    columns: SubTableColumn<T>[];
+};
+export declare function SubTable<T>({ mobile, columns, ...props }: SubTableProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/DataTable/UpdateModal.d.ts

@@ -1,5 +1,5 @@
 import { BaseEntity } from '../Hooks/useApi';
-import { Field, StepConfig } from './DataTableInner.tsx';
+import { Field, StepConfig } from './DataTable.tsx';
 export interface UpdateModalProps<T> {
     fields: Field<T>[];
     steps?: StepConfig[];

package/dist/Hooks/useApi.d.ts

@@ -1,4 +1,14 @@
 import { GetHeaders } from '../Context/DataTableContext.tsx';
+export interface FieldViolation {
+    field: string;
+    message: string;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly violations?: FieldViolation[];
+    constructor(message: string, status: number, violations?: FieldViolation[]);
+}
+export declare function getFieldViolations(error: unknown): FieldViolation[] | undefined;
 export declare function parseApiError(error: unknown): {
     message: string;
     code?: string;

package/dist/Hooks/usePersistentState.d.ts

@@ -1 +1 @@
-export declare function usePersistentState<T>(initialValue: T, key: string): [T, (value: T) => void];
+export declare function usePersistentState<T>(initialValue: T, key: string): [T, (value: T | ((prev: T) => T)) => void];

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { BaseEntity } from './Hooks/useApi';
 export { parseApiError, api, useGetOne, useDeleteOne, useGetAll, useUpdateOne, deleteOne, createOne, getAll, updateOne, useAddOne, getOne, } from './Hooks/useApi';
-export type { DataTableProps, FieldType, Field, StepConfig, TabOption, Action, } from './DataTable/DataTableInner.tsx';
+export type { DataTableProps, FieldType, Field, StepConfig, TabOption, Action, } from './DataTable/DataTable.tsx';
 export { DataTable } from './DataTable/DataTable.tsx';
 export { CreateModal } from './DataTable/CreateModal.tsx';
 export type { CreateModalProps } from './DataTable/CreateModal.tsx';
@@ -9,6 +9,10 @@ export type { UpdateModalProps } from './DataTable/UpdateModal.tsx';
 export { DeleteModal } from './DataTable/DeleteModal.tsx';
 export type { DeleteModalProps } from './DataTable/DeleteModal.tsx';
 export { MobileCardList } from './DataTable/MobileCardList.tsx';
+export { FieldCard } from './DataTable/FieldCard.tsx';
+export type { FieldRow } from './DataTable/FieldCard.tsx';
+export { SubTable } from './DataTable/SubTable.tsx';
+export type { SubTableColumn, SubTableProps } from './DataTable/SubTable.tsx';
 export { usePersistentState } from './Hooks/usePersistentState.ts';
 export { useDataTable } from './Hooks/useDataTable.ts';
 export { DataTableProvider } from './Context/DataTableContext.tsx';