@eztrak/shared 0.4.1 → 0.4.6

package/README.md

@@ -40,6 +40,18 @@ handleApiError(error, { fallbackMessage: "Save failed" });
 handleApiError(error, { showAlert: true });
 ```
 
+Confirmation dialog (SweetAlert2):
+
+```js
+import { confirmationAlert } from "@eztrak/shared/utils";
+
+confirmationAlert(() => resetLayout(), {
+  title: "Reset column layout to default",
+  text: "Reset column order, widths, and visibility to defaults?",
+  icon: "warning",
+});
+```
+
 ### Hooks
 
 ```js
@@ -48,6 +60,87 @@ import { usePaginationUrlSync, useGridHeight } from "@eztrak/shared/hooks";
 const gridHeight = useGridHeight({ offset: 390 });
 ```
 
+Pair `usePaginationUrlSync` with `CustomPagination` so URL query params stay in sync with your data fetch:
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+import { usePaginationUrlSync } from "@eztrak/shared/hooks";
+
+const [searchParams, setSearchParams] = useSearchParams();
+const [page, setPage] = useState(1);
+const [perPage, setPerPage] = useState(20);
+
+usePaginationUrlSync(
+  searchParams,
+  setSearchParams,
+  page,
+  setPage,
+  perPage,
+  setPerPage
+);
+```
+
+### Components — CustomPagination
+
+URL-driven pagination bar with page controls, results summary, items-per-page select, and an optional reset-columns button. Requires a React Router context (`useSearchParams`).
+
+```tsx
+import { CustomPagination } from "@eztrak/shared/components";
+
+<CustomPagination
+  paginationData={{
+    currentPage: 1,
+    pageCount: 10,
+    perPage: 20,
+    totalCount: 193,
+  }}
+  className="bg-white"
+  pageSizeOptions={[10, 20, 30, 50, 100]}
+  onResetLayout={handleResetLayout}
+  layoutStatus={{
+    isLayoutLoading,
+    isLayoutSaving,
+    isLayoutResetting,
+  }}
+/>
+```
+
+#### With loading state
+
+```tsx
+<CustomPagination
+  paginationData={data ?? null}
+  isLoading={isFetching}
+/>
+```
+
+#### Custom URL param names
+
+```tsx
+<CustomPagination
+  paginationData={paginationData}
+  paramNames={{ page: "p", perPage: "size" }}
+/>
+```
+
+#### Standalone reset button
+
+```tsx
+import {
+  ResetColumnsButton,
+  TableLayoutToolbarControls,
+} from "@eztrak/shared/components";
+
+<ResetColumnsButton onReset={handleResetLayout} isLoading={isResetting} />
+
+<TableLayoutToolbarControls
+  onResetLayout={handleResetLayout}
+  layoutStatus={{ isLayoutSaving: true }}
+/>
+```
+
+`ResetColumnsButton` shows a SweetAlert2 confirmation before calling `onReset`.
+
 ### Components — EztrakTabs
 
 Import styles once in your app entry or layout:
@@ -162,17 +255,34 @@ Pass classes per slot — they merge with the default `eztrak-tabs-*` styles via
 ### Root import
 
 ```js
-import { cn, useGridHeight, EztrakTabs } from "@eztrak/shared";
+import {
+  cn,
+  useGridHeight,
+  EztrakTabs,
+  CustomPagination,
+} from "@eztrak/shared";
+```
+
+## Storybook
+
+Run the component playground locally (dev-only, not published to npm):
+
+```bash
+npm run storybook
+# or from the monorepo root:
+npm run storybook -w @eztrak/shared
 ```
 
+Opens on [http://localhost:6006](http://localhost:6006) with stories for `EztrakTabs`, `CustomPagination`, and `ResetColumnsButton`.
+
 ## Exports
 
 | Subpath | Description |
 | --- | --- |
 | `@eztrak/shared` | Main entry — re-exports utils, hooks, and components |
-| `@eztrak/shared/utils` | `cn`, `handleApiError`, date/format helpers, API error helpers, form field helpers |
+| `@eztrak/shared/utils` | `cn`, `handleApiError`, `confirmationAlert`, date/format helpers, API error helpers, form field helpers |
 | `@eztrak/shared/hooks` | `usePaginationUrlSync`, `useGridHeight` |
-| `@eztrak/shared/components` | `EztrakTabs` and related types |
+| `@eztrak/shared/components` | `EztrakTabs`, `CustomPagination`, `ResetColumnsButton`, `TableLayoutToolbarControls`, and related types |
 | `@eztrak/shared/components/tabs.css` | Default tab styles (CSS variables) |
 
 ### EztrakTabs props
@@ -190,10 +300,31 @@ import { cn, useGridHeight, EztrakTabs } from "@eztrak/shared";
 
 Keyboard: Arrow keys move between tabs; Home/End jump to first/last enabled tab.
 
+### CustomPagination props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `paginationData` | `PaginationData \| null` | required | Server pagination metadata (`currentPage`, `pageCount`, `perPage`, `totalCount`) |
+| `pageSizeOptions` | `number[]` | `[10, 20, 30, 50, 100]` | Options shown in the per-page select |
+| `paginationPageSize` | `number[]` | — | Deprecated alias for `pageSizeOptions` |
+| `isLoading` | `boolean` | `false` | Show loading state when data is not ready |
+| `paramNames` | `{ page?: string; perPage?: string }` | `{ page: "page", perPage: "perPage" }` | URL query param keys |
+| `onPageChange` | `(page: number) => void` | — | Called after page URL param is updated (1-based page) |
+| `onPageSizeChange` | `(perPage: number) => void` | — | Called after per-page URL param is updated |
+| `onResetLayout` | `() => void` | — | When set, shows a reset-columns button |
+| `renderResetControl` | `(onReset: () => void) => ReactNode` | — | Custom reset control instead of the default button |
+| `layoutStatus` | `LayoutStatus` | — | Disables reset button while layout is loading/saving/resetting |
+| `classNames` | `CustomPaginationClassNames` | — | Per-slot class overrides (`root`, `info`, `nav`, `pageButton`, `activePageButton`, `select`) |
+| `className` | `string` | — | Root wrapper class |
+
+`CustomPagination` writes `page` and `perPage` to the URL via `react-router-dom`. Your page should read those params, fetch data, and pass the result back as `paginationData`.
+
 ## Requirements
 
 - Node.js 18+
 - React 18+ (for hooks and components)
+- `react-router-dom` (required for `CustomPagination` and `usePaginationUrlSync`)
+- `sweetalert2` (required for `ResetColumnsButton` and `confirmationAlert`)
 - Works with any bundler that supports the [Node.js `exports` field](https://nodejs.org/api/packages.html#exports)
 
 ## License