snap-records 1.1.12 → 1.20.0

package/.nvmrc

@@ -0,0 +1 @@
+26.7.0

package/CONTRIBUTING.md

@@ -8,8 +8,8 @@ First off, thank you for considering contributing to SnapRecords! It's people li
 
 ### Reporting Bugs
 
-- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/your-username/snap-records/issues).
-- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/your-username/snap-records/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
+- Ensure the bug was not already reported by searching on GitHub under [Issues](https://github.com/lbassuncao/SnapRecords/issues).
+- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/lbassuncao/SnapRecords/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
 
 ### Suggesting Enhancements
 
@@ -20,12 +20,12 @@ First off, thank you for considering contributing to SnapRecords! It's people li
 1. Fork the repo and create your branch from `main`.
 2. If you've added code that should be tested, add tests.
 3. If you've changed APIs, update the documentation.
-4. Ensure the test suite passes (`npm test`).
-5. Make sure your code lints (`npm run lint`).
+4. Ensure the test suite passes (`npm test`) and the library builds (`npm run build`).
+5. Make sure your code lints (`npm run lint`) and formatting checks pass (`npm run format:check`).
 6. Issue that pull request!
 
 We will review your pull request as soon as possible.
 
 ## Code of Conduct
 
-This project and everyone participating in it is governed by the [SnapRecords Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+This project and everyone participating in it is governed by the [SnapRecords Code of Conduct](./docs/COC.md). By participating, you are expected to uphold this code.

package/README.md

@@ -13,6 +13,7 @@
 <br>
 
 <p align="center" style="font-size: 1.15rem">
+  <strong><a href="https://github.com/lbassuncao/SnapRecords/blob/main/RELEASES.md">Releases</a></strong> |
   <strong><a href="https://github.com/lbassuncao/SnapRecords/blob/main/docs/CONFIG.md">Configuration</a></strong> |
   <strong><a href="https://github.com/lbassuncao/SnapRecords/blob/main/docs/BUILD.md">Build Guide</a></strong> |
   <strong><a href="https://github.com/lbassuncao/SnapRecords/blob/main/docs/KEYBOARD.md">Keyboard Navigation</a></strong> |
@@ -32,11 +33,11 @@ It supports server-side pagination, sorting, filtering, caching, multiple render
 ## Key Strengths
 
 - **Multiple Rendering Modes**: Supports table (`TABLE`), list (`LIST`), and mobile-friendly card (`MOBILE_CARDS`) views, adapting to various devices and use cases.
-- **Server-Side Data Handling**: Integrates with APIs for pagination, filtering, and sorting, with a 250ms debounce delay and retry mechanism (up to 3 attempts by default).
-- **Caching Support**: Uses IndexedDB via Dexie for caching server responses when `useCache` is enabled, with a default 8-hour expiry and cleanup on destroy if `destroyOnUnload` is enabled.
+- **Server-Side Data Handling**: Integrates with APIs for pagination, filtering, and sorting, with a 250ms debounce delay and retry mechanism (3 retries by default).
+- **Caching Support**: Uses IndexedDB via Dexie for caching server responses when `useCache` is enabled, with a default 8-hour expiry. `destroy()` closes the database connection; it does not delete cached responses.
 - **Interactive Features**: Includes column resizing, drag-and-drop column reordering, and row selection with keyboard navigation (ArrowUp/Down, Enter/Space, PageUp/Down).
-- **Accessibility**: Implements ARIA attributes (`aria-sort`, `aria-selected`, `aria-label`), keyboard navigation, and screen reader announcements for inclusive experiences.
-- **State Persistence**: Persists UI state (column order, widths, filters, page, etc.) in `localStorage` when `persistState` is enabled.
+- **Accessibility**: ARIA sort labels and pagination names in all modes; `aria-selected` only on table rows (`role="row"`). Keyboard navigation and screen reader announcements.
+- **State Persistence**: Persists UI state (column order, widths, `filtering`, page, etc.) in `localStorage` when `persistState` is enabled.
 - **Customizable Styling**: Provides built-in `light` and `dark` themes, plus a `default` theme that inherits styles from the host page via CSS Custom Properties (`--sr-...`). This allows for seamless integration with any design system.
 - **Type Safety**: Written in TypeScript with generic typing for type-safe data and configuration.
 - **Extensibility**: Offers lifecycle hooks (`preDataLoad`, `postDataLoad`, `preRender`, `postRender`, `selectionChanged`) and customizable renderer, event, state, URL, and cache managers.
@@ -48,21 +49,26 @@ It supports server-side pagination, sorting, filtering, caching, multiple render
 To quickly set up SnapRecords:
 
 1. **Install via NPM**:
+
     ```bash
     npm install snap-records
     ```
 
 2. **Include Styles**:
-    If using a bundler (Vite, Webpack, etc.):
+   If using a bundler (Vite, Webpack, etc.):
+
     ```typescript
-    import 'snap-records/dist/snap-records.css';
+    import 'snap-records/style.css';
     ```
+
     Or via HTML:
+
     ```html
     <link rel="stylesheet" href="/node_modules/snap-records/dist/snap-records.css" />
     ```
 
 3. **Create a container**:
+
     ```html
     <div id="table-container"></div>
     ```
@@ -90,63 +96,15 @@ npm install snap-records
 
 ### Prerequisites
 
-- Node.js (version 20 or higher)
-- TypeScript (version 5 or higher)
+- Node.js (version 26.7.0 or higher; see `.nvmrc`)
+- TypeScript (version 6 or higher)
 - A modern browser supporting IndexedDB for caching
 
 ### Dependencies
 
-SnapRecords relies on the following runtime dependencies, which must be installed in your project:
-
-- `dexie` (^4.0.11): For IndexedDB caching of server responses.
-- `immer` (^10.1.1): For immutable state management.
-- `lru-cache` (^11.1.0): For efficient caching of formatted cell values.
-
-Install them with:
-
-```bash
-npm install dexie immer lru-cache
-```
-
-### Steps
-
-1. **Install Dependencies**:
-
-    ```bash
-    npm install dexie immer lru-cache
-    ```
-
-2. **Add SnapRecords**: Copy the source files (`SnapRecords.ts`, `SnapApi.ts`, `SnapRenderer.ts`, `EventManager.ts`, `SnapRecordsDB.ts`, `Translations.ts`, `SnapOptions.ts`, `SnapTypes.ts`, `Configuration.ts`, `StateManager.ts`, `UrlManager.ts`, `CacheManager.ts`, `utils.ts`, and `scss/SnapRecords.scss`) into your project.
+`dexie`, `immer`, and `lru-cache` are runtime dependencies of `snap-records` and are installed automatically with the package.
 
-3. **Add Translation Files**: Place translation JSON files (e.g., `en_US.json`, `pt_PT.json`, `es_ES.json`) in the `/lang` directory within your application's public directory:
-
-    ```
-    public/
-    └── lang/
-        ├── en_US.json
-        ├── pt_PT.json
-        └── es_ES.json
-    ```
-
-4. **Include Styles**: Compile the SCSS file to CSS and include it in your application:
-
-    ````bash
-    sass src/scss/SnapRecords.scss dist/snap-records.css --style=compressed --source-map
-    ```html
-    <link rel="stylesheet" href="/path/to/snap-records.css">
-    ````
-
-5. **Import and Initialize**: Import SnapRecords and initialize it:
-
-    ```typescript
-    import { SnapRecords, RenderType, RowsPerPage } from './SnapRecords';
-
-    const snapRecords = new SnapRecords('table-container', {
-        url: 'https://api.example.com/data',
-        columns: ['id', 'name', 'email'],
-        rowsPerPage: RowsPerPage.DEFAULT,
-    });
-    ```
+Translations ship in `snap-records/lang/*`. Serve them from a public `/lang` path, or set `langPath` to wherever you host the JSON files.
 
 ## Usage Examples
 
@@ -241,24 +199,28 @@ const snapRecords = new SnapRecords('table-container', {
 
 const api = snapRecords.getApi();
 api.search({ status: 'active' }, true);
-api.gotoPage(2);
+api.setCurrentPage(2);
 api.setTheme('light');
-api.setRenderMode(RenderType.MOBILE_CARDS);
+api.setFormat(RenderType.MOBILE_CARDS);
 ```
 
 ## Configuration Options
 
-The `SnapRecordsOptions<T>` interface defines all configuration options. Key options include (see [config.md](https://github.com/lbassuncao/SnapRecords/blob/main/docs/CONFIG.md) for full details):
+The `SnapRecordsOptions<T>` interface defines all configuration options. See [CONFIG.md](https://github.com/lbassuncao/SnapRecords/blob/main/docs/CONFIG.md) for full details.
 
 - `url` (string, required): API URL for data fetching.
 - `columns` (string[], required): Column keys to display.
 - `columnTitles` (string[]): Custom header titles.
 - `columnFormatters` ({ [key: string]: (value, row) => string }): Custom cell formatters, cached with `lru-cache`.
-- `format` (RenderType): Rendering mode (`TABLE`, `LIST`, `MOBILE_CARDS`). Default: `TABLE`.
+- `format` (RenderType): Rendering mode (`TABLE`, `LIST`, `MOBILE_CARDS`). Default: `TABLE`. Change at runtime with `setFormat()`.
 - `rowsPerPage` (RowsPerPage): Rows per page (10, 20, 50, 100, 250, 500, 1000). Default: 10.
+- `filtering` (`Record<string, string>`): Initial filters. Sent to the server as `filtering[key]`. Update later with `search()` or `updateParams()`.
+- `sorting` (`SortCondition[]`): Initial sort. Sent to the server as `sorting[column]`.
 - `useCache` (boolean): Enables IndexedDB caching. Default: `false`.
-- `usePushState` (boolean): Updates browser URL with state. Default: `false`.
+- `usePushState` (boolean): Syncs page/filters/sort to the browser URL via `StateManager`, merging into the existing query string. Default: `false`.
 - `language` (string): UI language. Default: `en_US`.
+- `langPath` (string): Directory for translation JSON files. Default: `/lang`.
+- `debounceDelay` (number): Delay in ms before reloading data. Default: `250`.
 - `headerCellClasses` (string[]): Header CSS classes, with `no-sorting` to disable sorting.
 - `selectable` (boolean): Enables row selection. Default: `false`.
 - `draggableColumns` (boolean): Enables column drag-and-drop. Default: `false`.
@@ -267,35 +229,39 @@ The `SnapRecordsOptions<T>` interface defines all configuration options. Key opt
 - `debug` (boolean): Enables debug logs. Default: `false`.
 - `lazyLoadMedia` (boolean): Enables lazy loading for images. Default: `false`.
 - `formatCacheSize` (number): Sets the maximum size of the LRU format cache. Default: 500.
+- `preloadNextPage` (boolean): Prefetches the next page. Default: `false`.
 - `lifecycleHooks` (LifecycleHooks<T>): Callbacks for lifecycle events.
 - `prevButton`, `nextButton`: Customizes pagination buttons with text, HTML, or templates.
 
+The constructor accepts a container element id (`string`) or an `HTMLElement`.
+
 ## API Methods
 
-The `SnapApi` class provides methods for interacting with the component:
-
-- `search(filters: Record<string, string>, merge?: boolean): void` - Applies filters and reloads data.
-- `updateParams(params: Partial<Pick<SnapRecordsState<T>, 'currentPage' | 'rowsPerPage' | 'filters' | 'sortConditions'>>): void` - Updates multiple parameters.
-- `reset(): void` - Clears filters, sorting, and state.
-- `refresh(): void` - Reloads current data view.
-- `gotoPage(page: number): void` - Navigates to a page.
-- `setTheme(theme: 'light' | 'dark' | 'default'): void` - Sets the theme.
-- `setRenderMode(mode: RenderType): void` - Changes rendering mode.
-- `setRowsPerPage(newRowsPerPage: RowsPerPage): void` - Sets rows per page.
-- `setLanguage(newLanguage: string): Promise<void>` - Sets UI language.
-- `getData(): ReadonlyArray<T>` - Returns current data.
-- `getTotals(): { totalRecords: number }` - Returns total records.
-- `getSelectedRows(): T[]` - Returns selected rows.
-- `clearSelection(): void` - Clears row selections.
-- `destroy(): void` - Destroys the instance, clearing elements and cache.
+Use `snapRecords.getApi()` for the public `ISnapApi` surface. Method names match the implementation:
+
+- `search(filtering: Record<string, string>, merge?: boolean): void` — Applies `filtering` and reloads data.
+- `updateParams(params: Partial<Pick<SnapRecordsState<T>, 'currentPage' | 'rowsPerPage' | 'filtering' | 'sorting'>>): void` — Updates those state fields and reloads.
+- `reset(): void` — Restores constructor `filtering`, sorting, rows per page, and column layout.
+- `refresh(): void` — Reloads the current data view.
+- `setCurrentPage(page: number): void` — Navigates to a page.
+- `setTheme(theme: SnapTheme): void` — Sets `'light' | 'dark' | 'default'`.
+- `setFormat(mode: RenderType): void` — Sets the `format` used for rendering.
+- `setRowsPerPage(newRowsPerPage: RowsPerPage): void` — Sets rows per page.
+- `setLanguage(newLanguage: string): Promise<void>` — Sets UI language.
+- `getData(): ReadonlyArray<T>` — Returns current data.
+- `getTotals(): { totalRecords: number }` — Returns total records.
+- `getSelectedRows(): T[]` — Returns selected rows.
+- `clearSelection(): void` — Clears row selections.
+- `isDestroyed` — `true` after `destroy()`.
+- `destroy(): void` — Removes listeners, clears the container, and closes the cache database connection. Does not wipe cached API responses.
 
 Example:
 
 ```typescript
 const api = snapRecords.getApi();
 api.search({ status: 'active' }, true);
-api.gotoPage(2);
-api.setRenderMode(RenderType.LIST);
+api.setCurrentPage(2);
+api.setFormat(RenderType.LIST);
 api.clearSelection();
 api.destroy();
 ```
@@ -324,15 +290,15 @@ Override styles in your CSS as needed.
 
 SnapRecords prioritizes accessibility:
 
-- **ARIA Attributes**: Supports `aria-sort`, `aria-selected`, `aria-label` for table, list, and card modes.
-- **Keyboard Navigation**: ArrowUp/Down for row navigation, Enter/Space for selection, PageUp/Down for pagination (see [keyboard.md](https://github.com/lbassuncao/SnapRecords/blob/main/docs/KEYBOARD.md)).
+- **ARIA Attributes**: `aria-sort` and `aria-label` in all modes. `aria-selected` only on table rows (`role="row"`).
+- **Keyboard Navigation**: ArrowUp/Down for row navigation, Enter/Space for selection, PageUp/Down for pagination (see [KEYBOARD.md](https://github.com/lbassuncao/SnapRecords/blob/main/docs/KEYBOARD.md)).
 - **Screen Reader Support**: Announces updates (e.g., row selection, mode changes) via ARIA live regions.
 
 ## State Management
 
 The `SnapRecordsState` interface manages state, including:
 
-- Current page, rows per page, filters, sort conditions.
+- Current page, rows per page, `filtering`, `sorting`.
 - Column order, widths, titles.
 - Data, total records, format, language, theme.
 
@@ -340,40 +306,41 @@ State is persisted to `localStorage` when `persistState` is `true`, managed by `
 
 ## Internationalization
 
-Translations are loaded from `/lang` JSON files (e.g., `en_US.json`) via `TranslationManager`. Add new languages by creating JSON files following the `Translation` interface:
+Translations are loaded from `{langPath}/{language}.json` (default `/lang/en_US.json`) by `TranslationManager` in `Translations.ts`. Copy files from `node_modules/snap-records/lang/` into your public directory, or set `langPath`. New files must follow the `Translation` interface, for example:
 
 ```json
 {
-    "errors": {
-        "generic": "An error occurred.",
-        "invalidConfig": "Invalid configuration: {reason}",
-        "containerNotFound": "Container with ID {id} not found.",
-        "dataLoadingFailed": "Failed to load data: {error}",
-        "renderFailed": "Failed to render: {error}"
-    },
     "loading": "Loading...",
     "totalRecords": "Total records: {total}",
-    "filteredRecords": "Filtered records: {total}",
-    "errorTitle": "Error",
-    "errorMessage": "An unexpected error occurred.",
-    "noDataAvailable": "No data available.",
+    "filteredRecords": "Filtered records: {filtered}",
     "previous": "Previous",
     "next": "Next",
-    "retry": "Retry",
-    "pagination": {
-        "showingRecords": "Showing {start} to {end} of {total} records"
-    },
-    "currentPage": "Page {page}",
-    "jumpToPage": "Jump to page",
-    "pageNavigation": "Page navigation",
+    "errorTitle": "Error",
+    "errorMessage": "An error occurred.",
+    "noDataAvailable": "No data available.",
+    "columnResizeHandle": "Resize column",
     "sortAscending": "Sort ascending",
     "sortDescending": "Sort descending",
     "removeSort": "Remove sort",
     "rowSelected": "Row selected",
     "rowDeselected": "Row deselected",
-    "columnResizeHandle": "Resize column",
+    "currentPage": "Current page: {page}",
+    "pageNavigation": "Page navigation",
+    "loadMore": "Load More",
+    "jumpToPage": "Jump to page",
+    "retry": "Retry",
     "dragColumn": "Drag column {col}",
-    "loadMore": "Load more"
+    "rowsPerPageChanged": "Rows per page changed to {count}",
+    "errors": {
+        "containerNotFound": "Container not found.",
+        "invalidConfig": "Invalid configuration.",
+        "dataLoadingFailed": "Failed to load data: {error}",
+        "renderFailed": "Failed to render: {error}",
+        "generic": "An error occurred."
+    },
+    "pagination": {
+        "showingRecords": "Showing {start} to {end} of {total} records"
+    }
 }
 ```
 
@@ -424,7 +391,7 @@ Compile TypeScript and SCSS:
 npm run build
 ```
 
-This runs `npm run build:js` (for `tsc --noEmit` and `vite build`) and `npm run build:css` (for SCSS compilation with source maps).
+This runs `npm run build:js` (`vite build`), `npm run build:css` (Sass), and copies `src/lang/*.json` into `dist/lang/`.
 
 ### Testing
 
@@ -436,20 +403,14 @@ npm test
 
 ### Extending
 
-Add custom translations by creating a JSON file in `/lang`:
-
-```json
-{
-    "loading": "Chargement...",
-    "errors": {
-        "generic": "Une erreur est survenue."
-        // ...
-    }
-}
-```
+Add custom translations by creating a JSON file that matches `src/lang/en_US.json` and serving it from `langPath`.
 
 Customize rendering or event handling by providing custom `renderer`, `eventManager`, `stateManager`, `urlManager`, or `cacheManager` in the options.
 
+### Framework Wrappers
+
+React, Vue, Svelte, and Angular wrapper components live in [`wrappers/`](https://github.com/lbassuncao/SnapRecords/tree/main/wrappers) on GitHub (`SnapRecordsReact.tsx`, `SnapRecordsVue.vue`, `SnapRecords.svelte`, `snap-records.component.ts`). They are **not** published in the `snap-records` npm package and are not importable from it (there is no `snap-records/wrappers/*` export) — each one needs to be compiled by your own app's toolchain (JSX, SFC, Angular CLI, etc.), so copy the file for your framework straight into your project's source tree and adjust the import path to `snap-records`. See [CONFIG.md](https://github.com/lbassuncao/SnapRecords/blob/main/docs/CONFIG.md#public-api-getapi) for what they sync automatically, and [RELEASES.md](https://github.com/lbassuncao/SnapRecords/blob/main/RELEASES.md#framework-wrappers) for their exact behavior.
+
 ## Additional Notes
 
 - **Data Requirement: Unique `id` Field**: The data returned from the server must include a unique `id` field for each row, as required by the `Identifiable` interface in `SnapTypes.ts`. This `id` (string or number) is used by the plugin’s diffing mechanism to efficiently track and reconcile rows during rendering. The diffing process, implemented in `SnapRenderer.ts` (e.g., `#reconcileItems`), relies on this unique identifier to map existing DOM elements to data rows, ensuring accurate updates and preventing duplication or loss of data. For example, a server response should look like:

package/RELEASES.md

@@ -0,0 +1,212 @@
+# Releases
+
+## 1.20.0
+
+Breaking release. State, public API, HTTP query strings, and `usePushState` now share one vocabulary.
+
+Upgrade from `1.1.x` by renaming the symbols below. There are no compatibility aliases.
+
+### Public API methods
+
+| 1.1.x                                       | 1.20.0                                     |
+| ------------------------------------------- | ------------------------------------------ |
+| `api.gotoPage(n)`                           | `api.setCurrentPage(n)`                    |
+| `api.setRenderMode(mode)`                   | `api.setFormat(mode)`                      |
+| `search(filters, merge?)`                   | `search(filtering, merge?)`                |
+| `updateParams({ filters, sortConditions })` | `updateParams({ filtering, sorting })`     |
+| `setTheme('light' \| 'dark')`               | `setTheme('light' \| 'dark' \| 'default')` |
+
+`setTheme('default')` now works in the implementation. In 1.x the type allowed `'default'` but the method rejected it.
+
+`ISnapApi` also exposes `isDestroyed` (`true` after `destroy()`). Invalid `setTheme` / `setFormat` values are ignored.
+
+### State, options, and `localStorage`
+
+`SnapRecordsState`, `SnapRecordsOptions`, `updateParams()`, `preDataLoad`, and persisted state (`persistState`) renamed:
+
+| 1.1.x            | 1.20.0      |
+| ---------------- | ----------- |
+| `filters`        | `filtering` |
+| `sortConditions` | `sorting`   |
+
+`SortCondition` is unchanged: `[column, OrderDirection]`.
+
+Saved `localStorage` payloads from 1.1.x (`filters`, `sortConditions`) are not migrated. Clear old keys or rewrite them before enabling `persistState` on 1.20.0.
+
+### HTTP query and `usePushState`
+
+`filtering[key]` and `sorting[column]` are unchanged. Pagination query keys are not:
+
+| 1.1.x             | 1.20.0                                                             |
+| ----------------- | ------------------------------------------------------------------ |
+| `page`            | `currentPage`                                                      |
+| `perPage`         | `rowsPerPage`                                                      |
+| `offset`          | `offset` (unchanged, derived as `(currentPage - 1) * rowsPerPage`) |
+| `filtering[key]`  | `filtering[key]`                                                   |
+| `sorting[column]` | `sorting[column]`                                                  |
+
+Example:
+
+```
+/api/data?currentPage=2&rowsPerPage=10&offset=10&filtering[status]=active&sorting[name]=ASC
+```
+
+Backends that read `page` or `perPage` must switch to `currentPage` and `rowsPerPage`.
+
+Empty filter values are no longer written to the query string.
+
+The API request URL and the browser URL (`usePushState`) are built from the same helper, so they use the same keys. `usePushState` merges those keys into the existing query string and listens for `popstate`.
+
+### `preDataLoad` / `ServerRequestParams`
+
+| 1.1.x                                       | 1.20.0                                               |
+| ------------------------------------------- | ---------------------------------------------------- |
+| `page: number`                              | `currentPage: number`                                |
+| `perPage: number`                           | `rowsPerPage: number`                                |
+| `filtering?: Record<string, string>`        | `filtering: Record<string, string>` (always present) |
+| `sorting?: Record<string, 'ASC' \| 'DESC'>` | `sorting: SortCondition[]` (always present)          |
+
+```typescript
+lifecycleHooks: {
+    preDataLoad: (params) => {
+        // 1.x: params.page, params.perPage, params.sorting?.name
+        // 1.20.0:
+        console.log(params.currentPage, params.rowsPerPage, params.sorting);
+    },
+}
+```
+
+### Constructor
+
+```typescript
+new SnapRecords(container: string | HTMLElement, options)
+```
+
+A container id still works. Passing an `HTMLElement` is new and required by the framework wrappers.
+
+If the element has no `id`, SnapRecords assigns one (used as the `persistState` storage key).
+
+### Removed from `SnapRecords`
+
+These were public on the instance in 1.x and are now private renderer details:
+
+- `createTableRow`
+- `updateRow`
+- `createListItem`
+- `updateListItem`
+- `createMobileCard`
+- `updateMobileCard`
+
+### Instance properties
+
+| 1.1.x                    | 1.20.0            |
+| ------------------------ | ----------------- |
+| `preloadNextPageEnabled` | `preloadNextPage` |
+
+The option name was already `preloadNextPage`.
+
+Each instance no longer attaches `window` `error` / `unhandledrejection` listeners.
+
+`destroy()` still tears down events, DOM, translations, and the IndexedDB connection. It also clears the in-memory format cache and row selection. It does **not** wipe cached API responses in IndexedDB.
+
+### Pagination CSS config
+
+Current-page number buttons used `classNames.disabled: 'snap-active'` in 1.x. That field is now `active`:
+
+```typescript
+config.pagination.numberButton.classNames.active; // 'snap-active'
+```
+
+`ButtonConfig.classNames.disabled` is optional. Prev/next buttons still use `disabled`.
+
+Custom `renderer` / pagination code that read `classNames.disabled` on number buttons must use `active`.
+
+### Package exports
+
+`snap-records` now exports `ISnapApi`, `SnapTheme`, `SortCondition`, `SnapRecordsState`, and `PersistedState`. Wrappers that imported `ISnapApi` from the package type-check against the public entry.
+
+### Framework wrappers
+
+React, Vue, Svelte, and Angular wrappers pass the container element (not a random id), call `destroy()` on unmount, sync `theme`, `language`, `format`, `filtering`, `sorting`, and `rowsPerPage` through `ISnapApi` (each field watched separately — not the whole `options` object), and skip prop sync when `isDestroyed` is true. The Vue wrapper clears its instance ref after `destroy()` and guards theme/language/format watchers when the instance is not mounted yet. Pagination (`currentPage`) is runtime-only via `ISnapApi`, not reactive `options`.
+
+### Bug fixes (from production use)
+
+- `headerCellClasses` (including `no-sorting`) is read from state. In 1.x the option was stored but never applied to headers.
+- `columnWidths` stays a `Map`. Production calls Immer `enableMapSet()` (tests used to hide the crash by calling it only in the test setup).
+- Constructing a second instance on the same container destroys the previous one (bfcache / `pageshow` re-init).
+- `destroy()` is idempotent, cancels pending loads, and aborts in-flight `fetch`. It closes IndexedDB; it does not wipe the cache.
+- `search()` / `updateParams({ filtering })` drop empty values and reset `currentPage` to 1. Filter object key order does not trigger a reload.
+- `updateParams()` ignores `undefined` fields and does not reload when nothing changed.
+- `setCurrentPage()` / `updateParams({ currentPage })` clamp to the page range. After a load, an out-of-range page redirects.
+- `rowsPerPage` is clamped to 1–1000 in the constructor, setters, URL, and `localStorage`.
+- `reset()` restores constructor `filtering`, `sorting`, `rowsPerPage`, columns, titles, and header classes.
+- Cached responses run `preDataLoad` / `postDataLoad`.
+- A throw in a lifecycle hook is logged and does not abort render or get retried as a network error.
+- HTTP 4xx and invalid JSON are not retried. 5xx and network errors still are.
+- If the API omits `totalRecords`, the received row count is used (the table no longer shows rows with “No data available”).
+- Clicks on buttons, links, and form controls inside a row no longer toggle selection.
+- Row selection highlighting is reapplied after `setFormat()` and other re-renders.
+- Unformatted cell values are escaped as text (`<`, `&`). Formatter HTML is still sanitized. `lazyLoadMedia` does not overwrite an existing `loading` attribute.
+- Prev/next pagination defaults (`«` / `»`) keep `aria-hidden` on the glyph and set `aria-label` from translations. Sort, resize, and drag use `sortAscending` / `sortDescending` / `removeSort`, `columnResizeHandle`, and `dragColumn`.
+- Keyboard handling ignores `input`, `textarea`, `select`, `button`, `a`, and `[contenteditable]:not([contenteditable="false"])`. `Home` / `End` move the current row (they do not call `reset()`). `ArrowUp` is ignored when no row is current. `.snap-current-row` is styled in table, list, and card modes.
+- The table wrapper class is `snap-table-responsive` (the CSS never matched Bootstrap’s `table-responsive`).
+- `loadData()` aborts an in-flight next-page preload so a filter change cannot recache the previous query.
+- Column resize uses the SnapRecords handle only (`resize: horizontal` on `th` was ignored by state/persist).
+- `cursor: pointer` on rows/cards applies only when `selectable` is on (`.snap-selectable`).
+- Sort headers are `<button type="button">` (not `<a href="#">`), so middle-click / Ctrl+click does not navigate away.
+- Translation fetch retries abort immediately on `destroy()` instead of waiting out the retry delay.
+- `aria-selected` is set only on `role="row"` (table). List items and cards keep `.snap-selected` (ARIA does not allow `aria-selected` on `listitem` / `rowgroup`).
+- `retryAttempts` is clamped to 0–10 and `debounceDelay` to 0–10000ms.
+- Resize and drag listeners are no longer duplicated on every render.
+- `showError()` no longer hides the table forever; `render()` / `showLoading()` restore content.
+- Format cache keys are `JSON.stringify([rowIndex, row.id, column])` so duplicate row ids on the same page do not share formatted values.
+- Row reconciliation keys DOM nodes by `` `${id}:${index}` `` so duplicate ids on one page render and update correctly.
+- When the API sends `totalRecords: 0` but returns rows, the footer uses the row count instead of “No data available”.
+- When the dataset becomes empty, `currentPage` resets to 1 instead of leaving pagination on a stale page.
+- On `popstate` to a URL with no snap params, `persistState` reloads filtering/sorting from `localStorage` instead of constructor defaults.
+- `destroy()` during an in-flight load no longer re-renders or rebinds event handlers after IndexedDB caching completes.
+- `setState()` / URL persistence / `localStorage` writes are skipped after `destroy()`.
+- `setupAllHandlers()` is skipped when the instance is destroyed.
+- `showError()` falls back to bundled English when translations are not loaded yet.
+- `buildUrl()` fallback strips existing snap query keys before appending new ones.
+- Language codes are sanitized to `[a-zA-Z0-9_-]` in state and when fetching `{lang}.json` (`../en_US` → `en_US`).
+- `offset` in the URL is derived. A query that only has `offset` is not treated as snap state and does not wipe `persistState` filters.
+- `loadFromURL()` updates `filtering` / `sorting` only when those keys appear in the URL. Pagination-only snap queries no longer reset them to `{}` / `[]`.
+- `loadFromURL()` updates `currentPage` only when `currentPage` appears in the URL. Sorting- or filtering-only snap queries no longer reset the page to 1.
+- On `popstate`, absent `filtering` / `sorting` keys reset those fields to `{}` / `[]` so browser back/forward matches the URL. First load still keeps absent keys from `persistState` or constructor options.
+- `End` with no rows leaves the current row index at `-1` (same as `Home`).
+- Column resize no longer writes `persistState` after `destroy()`.
+- `showLoading()` recovers when `isLoading` is true but the overlay was removed (for example after an aborted fetch or a re-render during load).
+- `hideLoading()` removes stray overlays when `isLoading` was already cleared.
+- `langPath` trailing slashes are stripped (`/lang/` → `/lang/pt_PT.json`). Loaded JSON is merged with bundled `en_US`. Non-string fields in that JSON are ignored.
+- `usePushState` merges snap keys into the existing query. An empty URL on first load does not wipe `persistState`. `popstate` reloads from the URL.
+- Constructor `filtering` / `sorting` are compacted and normalized before `reset()` or an empty `popstate` restore them.
+- `persistState` `currentPage` is truncated to an integer.
+- Pagination totals insert `{start}` / `{end}` / `{total}` as text. Markup in `showingRecords` is not parsed as HTML.
+- `javascript:` / `vbscript:` URLs that use whitespace or control characters are stripped from formatter HTML.
+- Data-load retries wait between attempts (aborted by `destroy()`), matching translation retries.
+- Next-page preload is skipped if the query changed while the cache lookup was in flight.
+- Next-page preload is skipped when `useCache` is `false` (prefetch only writes to IndexedDB).
+- `persistState` writes are flushed on `destroy()` even when the debounce timer has not fired.
+- Duplicate `sorting` entries for the same column collapse to the last direction.
+- `destroy()` removes `tabindex`, theme classes, and the container shell classes from the host element.
+- Invalid persisted `columnWidths` (non-finite or non-positive) are ignored.
+- IndexedDB cache clear on filter change is awaited so a new page cannot be written and then wiped.
+- IndexedDB reads and writes wait for the database connection to open before running.
+- `search()` / `updateParams({ filtering })` treat a non-object as `{}` instead of throwing.
+- The error Retry button is `type="button"` so it does not submit a parent form.
+- `destroy()` restores `position` on the host element when SnapRecords had set it to `relative`.
+- `persistState` restores saved `headerCellClasses` when the array length matches the column count.
+- Corrupted `localStorage` `filtering` arrays are ignored instead of becoming numeric keys.
+- Constructor `filtering` must be a plain object; arrays log a warning and fall back to `{}`.
+- `popstate` re-renders sort/pagination chrome before the debounced fetch completes.
+- Column sort clears the format cache before reload.
+- `reset()` clamps `rowsPerPage` through the same sanitizer as the constructor.
+- `headerCellClasses` length is validated against `columns` in the constructor (`Configuration.validateHeaderCellClasses`). A mismatched, non-empty array now logs a warning and falls back to `[]` instead of silently misaligning header classes across columns after drag-and-drop reorder (`reorderColumns()`) or a `persistState` column-order restore.
+- Removed unused `config.classes` entries (`paginationCell`, `tableOverlay`, `listOverlay`, `cardsOverlay`) that were never applied to the DOM or styled in CSS.
+- `tsconfig.json` / `tsconfig.test.json` use `moduleResolution: "bundler"` instead of `"node"`. TypeScript 6.0.3 (the pinned devDependency) treats `"node"` as a hard error (`TS5107`), so `tsc --noEmit` against either config failed outright even though `vite build` and `ts-jest` masked it by compiling through their own, more lenient paths.
+- **CommonJS `require('snap-records')` returned an empty module.** The UMD build was emitted as `dist/snap-records.umd.js`, but `package.json` has `"type": "module"`, so Node loaded that plain `.js` file as ESM and silently produced a namespace object with none of the UMD bundle's exports (`SnapRecords` was `undefined`). The UMD output is now `dist/snap-records.umd.cjs` (`.cjs` is always loaded as CommonJS regardless of `"type"`), and `package.json`'s `main` and `exports["."].require` were updated to match. Verified both `require()` and `import` resolve `SnapRecords` correctly against the built package.
+
+### Translations
+
+`pt_PT` pagination string is now `A mostrar {start} a {end} de {total} registos`. Custom copies of that file should match `src/lang/en_US.json`.