ag-grid-url-sync 0.5.0 → 0.5.2

package/README.md

@@ -145,7 +145,7 @@ The library provides two main entry points:
 
 ```typescript
 // Core functionality - works with any framework
-import { createUrlSync } from 'ag-grid-url-sync'
+import { createGridUrlSync } from 'ag-grid-url-sync'
 
 // React hook - for React applications
 import { useAGGridUrlSync } from 'ag-grid-url-sync/react'
@@ -195,16 +195,13 @@ import type {
 
 ```typescript
 import { parseUrlFilters } from 'ag-grid-url-sync/url-parser'
-import { DEFAULT_CONFIG } from 'ag-grid-url-sync/validation'
-import type { FilterState, ParseConfig } from 'ag-grid-url-sync/types'
+import type { FilterState } from 'ag-grid-url-sync/types'
 
 function getFiltersFromUrl(url: string): FilterState {
-  const config: ParseConfig = {
-    ...DEFAULT_CONFIG, // gridApi is not needed for parsing
+  // Options that you leave out get their defaults. No grid is needed.
+  return parseUrlFilters(url, {
     onParseError: error => console.error('Parse error:', error)
-  }
-
-  return parseUrlFilters(url, config)
+  })
 }
 ```
 
@@ -227,22 +224,78 @@ function getFiltersFromUrl(url: string): FilterState {
 
 ```typescript
 import { generateUrl } from 'ag-grid-url-sync/url-generator'
-import { DEFAULT_CONFIG } from 'ag-grid-url-sync/validation'
-import type { FilterState, ParseConfig } from 'ag-grid-url-sync/types'
+import type { FilterState } from 'ag-grid-url-sync/types'
 
 function createShareableUrl(filters: FilterState, baseUrl: string): string {
-  const config: ParseConfig = {
-    ...DEFAULT_CONFIG, // gridApi is not needed for generation
-    maxValueLength: 500
-  }
-
-  return generateUrl(baseUrl, filters, config)
+  return generateUrl(baseUrl, filters, { maxValueLength: 500 })
 }
 ```
 
+#### Example: Read and Write the Grid Filters
+
+```typescript
+import {
+  getFilterModel,
+  applyFilterModel
+} from 'ag-grid-url-sync/grid-integration'
+
+const filters = getFilterModel(gridApi, { onParseError: console.warn })
+applyFilterModel(filters, otherGridApi)
+```
+
+The config form (`getFilterModel({ ...DEFAULT_CONFIG, gridApi })`) still works, but it is deprecated.
+
 **💡 Pro Tip**: Use granular imports in libraries and applications where bundle size matters. All existing import patterns remain fully supported for backward compatibility.
 
-### Basic Example
+### Vanilla JS: `createGridUrlSync`
+
+One call gives full sync. `createGridUrlSync` applies the address bar's filters to the grid, follows the grid's filter changes, can write them to the address bar, and removes its listeners when the grid is destroyed.
+
+```typescript
+import { createGridUrlSync, individual, grouped } from 'ag-grid-url-sync'
+
+const sync = createGridUrlSync({
+  api: gridApi,
+  codec: individual({ prefix: 'f_' }), // or grouped({ param: 'gf', format: 'json' })
+  history: 'replace', // 'none' (default) | 'replace' | 'push' | (url) => router.replace(url)
+  onIssue: ({ issue, source }) => {
+    if (issue.severity === 'warning') showToast(issue.message)
+  }
+})
+
+// The current state: { status, url, hasFilters, issues, views, activeViewId }
+const { url, hasFilters } = sync.getSnapshot()
+
+// Called after each change of the snapshot. Returns an unsubscribe function.
+const unsubscribe = sync.subscribe(() => render(sync.getSnapshot()))
+
+sync.applyUrl('https://app.com/data?f_name_contains=jo') // { issues }
+sync.getUrl('https://app.com/share') // a share link for the grid's filters
+sync.applyFilters({
+  name: { filterType: 'text', type: 'contains', filter: 'jo' }
+}) // { issues }
+sync.destroy()
+```
+
+`applyFilters` writes filters to the grid as the app's own write. When they land, the sync writes the URL in the `history` mode, as it does for a user edit. `applyUrl` writes no history, because the URL already holds those filters.
+
+| Option             | Default                   | Meaning                                                                                                                                                                                                   |
+| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`              | (required)                | The AG Grid API                                                                                                                                                                                           |
+| `codec`            | `individual()`            | How the filters are written in the URL. `individual({ prefix })` writes one param for each filter; `grouped({ param, format })` writes all filters in one param                                           |
+| `maxValueLength`   | `200`                     | The longest text value that is kept                                                                                                                                                                       |
+| `history`          | `'none'`                  | How a filter change goes to the address bar. `'replace'` and `'push'` use `window.history`; a function gets the URL, for a router. The page's other params, the `#hash` and `history.state` stay          |
+| `popstate`         | `true` only with `'push'` | Apply the URL when the back or forward button changes it                                                                                                                                                  |
+| `applyUrlOnCreate` | `true`                    | Apply the address bar's filters on create. A URL with no filter params keeps the grid's filters (for example from `initialState`), and with `history` they are written to the URL with replace            |
+| `views`            | none                      | The saved views. Give `createViewStore(key)` from `ag-grid-url-sync/view-storage`. See [Saved Views](#saved-views)                                                                                        |
+| `throwOnError`     | `false`                   | Throw an issue instead of reporting it, in the methods that the app calls (`applyUrl`, `getUrl`, `applyFilters`, `saveView`, `loadView`, `deleteView`). `createGridUrlSync` and its listeners never throw |
+| `onIssue`          | none                      | Gets each issue one time, as `{ issue, source }`. `source` is `'url'` (the sync read the address bar), `'grid'` (it read the grid) or `'api'` (a method that the app called)                              |
+
+The snapshot `status` is `'active'` from create, and `'destroyed'` after `destroy()` or after the grid is destroyed. After that, `applyUrl`, `applyFilters`, `saveView` and `loadView` report `NOT_READY` to `onIssue`. `deleteView` needs only storage, so it still works. `IDLE_SNAPSHOT` (`status: 'idle'`) is the snapshot for a time when there is no sync yet. `getSnapshot()` returns the same object until something changes, so it works with React's `useSyncExternalStore`. The sync writes no history for an `applyUrl` apply, because the URL holds those filters already. `applyFilters` and `loadView` write the URL as a user edit does. Nothing reads `window` when the module loads, and a sync made with no `window` does nothing to the address bar.
+
+### Basic Example (deprecated `createUrlSync`)
+
+`createUrlSync` and `AGGridUrlSync` will be removed in 0.6.0. Use `createGridUrlSync`.
 
 ```typescript
 import { createUrlSync } from 'ag-grid-url-sync'
@@ -435,38 +488,83 @@ import {
 
 ---
 
-### Error Handling for Grouped Serialization
+### Error Handling
+
+The library never writes to the console. Each problem goes to one callback, and each error that the library makes has a `code` that you can switch on:
+
+| Code                                                          | Meaning                                                        | Callback                                                                                                 |
+| ------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `INVALID_PARAM`                                               | A param name that is not valid, or an unknown operation        | `onParseError`                                                                                           |
+| `INVALID_NUMBER`                                              | A value that is not a number, or that would be rounded         | `onParseError`                                                                                           |
+| `INVALID_DATE`                                                | A date that does not exist, or a date range in the wrong order | `onParseError`                                                                                           |
+| `VALUE_TOO_LONG`                                              | A text value over `maxValueLength`                             | `onParseError`                                                                                           |
+| `INVALID_GROUPED`                                             | A grouped value that does not decode (bad JSON or base64)      | `onParseError`                                                                                           |
+| `TYPE_MISMATCH`                                               | A number or date filter on a column of another type            | `onParseError`                                                                                           |
+| `INVALID_URL`                                                 | A URL that the parser cannot read                              | Thrown by `parseUrlFilters` and `applyFromUrl`. The React hook catches it and sends it to `onParseError` |
+| `GRID_ERROR`                                                  | The AG Grid API threw                                          | `onParseError` in the core, `onError` in the React hook                                                  |
+| `NOT_READY`                                                   | A hook operation called before the grid is ready               | `onError` (React)                                                                                        |
+| `VIEW_NOT_FOUND`, `VIEW_NAME_REQUIRED`                        | A saved view operation that cannot run                         | `onError` (React)                                                                                        |
+| `STORAGE_UNAVAILABLE`, `STORAGE_FULL`, `STORAGE_WRITE_FAILED` | Browser storage for saved views failed                         | `onError` (React)                                                                                        |
+| `HISTORY_WRITE_FAILED`                                        | The sync could not write the address bar                       | `onIssue` in the core, `onError` in the React hook                                                       |
 
-You can provide a custom error handler to gracefully handle malformed grouped parameters or serialization errors. In grouped mode, `onParseError` receives an `InvalidSerializationError` for invalid formats:
+Each error has a `severity`: `'warning'` for the first seven rows, `'error'` for the others. `createGridUrlSync` sends every issue to `onIssue`; the callbacks in the table are for the deprecated API and the React hook.
+
+The codes in the first seven rows are data issues: a filter that is dropped or is not valid. The library skips that filter and keeps the others. When the library knows the column, it is in `error.column`. `onParseError` is typed with `Error`, so check `instanceof URLSyncError` before you read `code` or `column`.
+
+Every error is a `URLSyncError`. The classes from earlier versions (`InvalidFilterError`, `InvalidDateError`, `InvalidURLError`, `InvalidSerializationError`) are subclasses of it, so an `instanceof` check still works.
 
 ```typescript
-import { InvalidSerializationError } from 'ag-grid-url-sync/types'
+import { createUrlSync, URLSyncError } from 'ag-grid-url-sync'
 
 const urlSync = createUrlSync(gridApi, {
-  serialization: 'grouped',
-  format: 'json',
   onParseError: error => {
-    if (error instanceof InvalidSerializationError) {
-      // Handle grouped serialization error
-      alert('Invalid filter data in URL!')
-    } else {
-      // Handle other errors
-      console.error(error)
+    if (error instanceof URLSyncError && error.code === 'VALUE_TOO_LONG') {
+      showToast(`The link leaves out the filter on ${error.column}`)
     }
   }
 })
 ```
 
+In grouped mode, an error that comes from the grouped URL value is an `InvalidSerializationError`, and the original error is in `error.cause`. When the original error is an issue with one filter (for example a value over `maxValueLength`), the wrapper has the same `code` and `column`. So a check on `error.code` works the same in both modes. `INVALID_GROUPED` means that the grouped value itself does not decode.
+
 In every grouped format (`querystring`, `json`, `base64`), a text value over `maxValueLength` (default 200) is dropped and reported through `onParseError`, both when the URL is generated and when it is parsed.
 
-In grouped mode, an error that comes from the grouped URL value is an `InvalidSerializationError`. This includes an error for one bad parameter inside a grouped querystring value, such as a value over `maxValueLength`. The original error is in `error.cause`. In individual mode, the same failure arrives as the original error, with no wrapper. To handle a specific error in both modes, check the error and its cause:
+#### Dropped Filters in the Result
+
+A caller does not need a callback to see dropped filters. `getUrlState()` and the apply methods return the issues of each call. They are the same objects that `onParseError` gets.
 
 ```typescript
-import { InvalidFilterError } from 'ag-grid-url-sync/types'
+const { url, hasFilters, issues } = urlSync.getUrlState()
 
-const isFilterError = (error: Error) =>
-  error instanceof InvalidFilterError ||
-  error.cause instanceof InvalidFilterError
+if (issues.length > 0) {
+  // The link leaves out these filters, so the recipient sees other rows
+  showToast(`The link leaves out ${issues.length} filter(s)`)
+}
+
+const { issues: urlIssues } = urlSync.applyFromUrl()
+```
+
+In React, the hook returns `issues`: the issues of the latest URL apply (`applyUrlFilters`, `applyFilters`, auto-apply), followed by the issues of the latest URL write. The apply issues stay until the next apply, `clearFilters` or `loadView`. Operation failures (`onError`) are not in the list:
+
+```tsx
+const { shareUrl, issues } = useAGGridUrlSync(gridApi)
+
+return issues.length > 0 ? (
+  <Warning>The link leaves out a filter</Warning>
+) : null
+```
+
+#### `throwOnError`
+
+Like TanStack Query, the library can throw an issue instead of reporting it. Set `throwOnError: true` to throw every issue, or give a function that picks issues. In the core, a thrown issue does not go to `onParseError`, and the first one stops the call. In React, the hook keeps reporting each issue to `onParseError` one time, and then throws the picked issue during render, so an error boundary catches it. The default is `false`.
+
+Only `createGridUrlSync` or the hook with `history` changes the address bar. Before an error boundary resets, remove the bad param from the URL (or the filter from the grid), or the same issue is thrown again.
+
+```tsx
+useAGGridUrlSync(gridApi, {
+  // Throw only when a link would leave out a filter
+  throwOnError: issue => issue.code === 'VALUE_TOO_LONG'
+})
 ```
 
 ### Exports
@@ -486,7 +584,7 @@ Refer to the [package.json](./package.json) for the full export map.
 
 ## React Integration
 
-For React applications, use the dedicated `useAGGridUrlSync` hook that provides a complete solution with React-specific features and state management.
+For React applications, use the `useGridUrlSync` hook. It is a thin adapter on [`createGridUrlSync`](#vanilla-js-creategridurlsync): it takes the same options, and the grid behaves as with the vanilla sync. The older `useAGGridUrlSync` hook is deprecated and will be removed in 0.6.0 (see [Migrating from `useAGGridUrlSync`](#migrating-from-useaggridurlsync)).
 
 ### Installation for React
 
@@ -494,7 +592,90 @@ For React applications, use the dedicated `useAGGridUrlSync` hook that provides
 npm install ag-grid-url-sync
 ```
 
-### Basic React Usage
+The hook works with React 16.8 and later. It uses the `use-sync-external-store` package, which npm installs with the library. On React 18 and later, that package uses React's own `useSyncExternalStore`.
+
+### `useGridUrlSync({ api, ...options })`
+
+```tsx
+import { useState } from 'react'
+import { AgGridReact } from 'ag-grid-react'
+import type { GridApi } from 'ag-grid-community'
+import { useGridUrlSync } from 'ag-grid-url-sync/react'
+import { individual } from 'ag-grid-url-sync'
+
+function GridComponent() {
+  const [api, setApi] = useState<GridApi | null>(null)
+
+  const { status, hasFilters, issues, getUrl, applyFilters } = useGridUrlSync({
+    api,
+    codec: individual({ prefix: 'filter_' }),
+    history: 'push', // each filter change adds a history entry; back and forward apply the URL
+    onIssue: ({ issue, source }) => console.warn(source, issue.code)
+  })
+
+  return (
+    <div>
+      <button
+        disabled={status !== 'active'}
+        onClick={() => navigator.clipboard.writeText(getUrl())}
+      >
+        Share filters
+      </button>
+      <button disabled={!hasFilters} onClick={() => applyFilters({})}>
+        Clear filters
+      </button>
+      {issues.length > 0 && (
+        <p>The link leaves out {issues.length} filter(s)</p>
+      )}
+      <AgGridReact onGridReady={params => setApi(params.api)} {...gridProps} />
+    </div>
+  )
+}
+```
+
+The options are the [`createGridUrlSync` options](#vanilla-js-creategridurlsync) (`codec`, `maxValueLength`, `history`, `popstate`, `applyUrlOnCreate`, `throwOnError`, `onIssue`), with these changes:
+
+| Option         | Default | Description                                                                                                                                                                                                     |
+| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`          | none    | The AG Grid API, or `null` while the grid starts                                                                                                                                                                |
+| `storageKey`   | none    | Enables saved views, kept in `localStorage` under this key (in place of the core's `views` store). With no key, the view methods do nothing                                                                     |
+| `enabled`      | `true`  | With `false`, the hook makes no sync: `status` is `'idle'`, and a method reports `NOT_READY`. `views` still shows what is in storage. Back to `true` starts again, as a new sync does: the URL is applied again |
+| `throwOnError` | `false` | As in TanStack Query: the hook throws a picked issue during render, so an error boundary catches it. The methods do not throw                                                                                   |
+
+The hook returns the snapshot and the methods of the sync:
+
+| Property                             | Description                                                                      |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| `status`                             | `'idle'` (no grid, no sync yet, or a server render), `'active'` or `'destroyed'` |
+| `url`, `hasFilters`, `issues`        | The URL with the grid's filters, whether there are filters, the latest issues    |
+| `views`, `activeViewId`              | The saved views and the active one                                               |
+| `applyUrl(url?)`, `applyFilters(f)`  | Apply a URL or filters. They return `{ issues }`                                 |
+| `getUrl(baseUrl?)`                   | The URL with the grid's filters, for example to share                            |
+| `saveView`, `loadView`, `deleteView` | The saved view methods of the sync                                               |
+
+- **The core's rules hold.** On mount, a URL with filters wins over the stored view, a URL with no filters keeps the grid's filters, and a URL apply writes no history.
+- **Options can change after mount.** A new codec, `maxValueLength`, history mode, `popstate` or `storageKey` makes a new sync on the same grid. It does not apply the URL again, and it keeps the active view. A new `storageKey` restores that store's view. A new codec object with the same settings, a new `onIssue` or a new `history` function makes no new sync.
+- **The result is stable.** It is the same object until a snapshot value changes, and the methods never change.
+- **A method with no sync** (no grid yet, `enabled: false`): `applyUrl` and `applyFilters` report `NOT_READY` to `onIssue`, and so do `saveView` and `loadView` with a `storageKey`. `getUrl` returns the base URL. `deleteView` still works with storage only.
+- **Issues stay across a new sync.** After an option change or a `StrictMode` remount, `issues` still shows the latest apply's issues until the next apply. `onIssue` gets each issue one time.
+- `StrictMode`, React's `<Activity>` and server rendering are supported.
+
+### Migrating from `useAGGridUrlSync`
+
+| `useAGGridUrlSync`                                              | `useGridUrlSync`                                                                      |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `useAGGridUrlSync(gridApi, options)`                            | `useGridUrlSync({ api: gridApi, ...options })`                                        |
+| `paramPrefix`, `serialization`, `groupedParam`, `format`        | `codec: individual({ prefix })` or `grouped({ param, format })`                       |
+| `autoApplyOnMount` (default `false`)                            | `applyUrlOnCreate` (default `true`). A URL with no filters keeps the grid's filters   |
+| `enabledWhenReady`                                              | `enabled`                                                                             |
+| `onParseError`, `onError(error, context)`                       | `onIssue({ issue, source })`                                                          |
+| `isReady`                                                       | `status === 'active'`                                                                 |
+| `currentUrl`, `shareUrl(baseUrl?)`                              | `url`, `getUrl(baseUrl?)`                                                             |
+| `applyUrlFilters(url?)`, `clearFilters()`                       | `applyUrl(url?)`, `applyFilters({})`                                                  |
+| `getQueryParams()`                                              | `new URL(getUrl()).search`, while `status` is `'active'`                              |
+| `parseUrlFilters`, `getFiltersAsFormat`, `getSerializationMode` | The module functions `parseUrlFilters` and `serializeGrouped` from `ag-grid-url-sync` |
+
+### Basic React Usage (deprecated `useAGGridUrlSync`)
 
 ```tsx
 import React, { useState } from 'react'
@@ -572,7 +753,7 @@ function GridComponent() {
 }
 ```
 
-### React Hook API
+### React Hook API (deprecated `useAGGridUrlSync`)
 
 #### `useAGGridUrlSync(gridApi, options?)`
 
@@ -587,13 +768,39 @@ const {
   isReady,
   currentUrl,
   hasFilters,
+  issues,
   parseUrlFilters,
   applyFilters,
   getFiltersAsFormat,
-  getCurrentFormat
+  getSerializationMode
 } = useAGGridUrlSync(gridApi, options)
 ```
 
+The hook runs on [`createGridUrlSync`](#vanilla-js-creategridurlsync) and reads its state with `useSyncExternalStore`:
+
+- **Options can change after mount.** A change to `paramPrefix`, `maxValueLength`, `serialization`, `groupedParam`, `format`, `history` (the mode) or `popstate` makes a new sync. The grid keeps its filters, and `currentUrl` uses the new format. The URL is not applied again. A new options object with the same values, or a new callback, makes no new sync.
+- **The returned object is stable.** It is the same object across renders until a value in it changes.
+- **A grid-read issue goes to `onParseError` one time** while it stays. It is reported again only after it goes away and comes back.
+- **After AG Grid destroys the grid**, `isReady` is `false` and `currentUrl` is `''`, as with no grid. `applyUrlFilters`, `clearFilters`, `applyFilters`, `saveView` and `loadView` then report `NOT_READY` to `onError`. `shareUrl`, `getQueryParams` and `getFiltersAsFormat` return their fallback values.
+- **The hook writes to the address bar only with `history`.** With the default `'none'`, use `currentUrl` or `shareUrl()` to update it.
+
+#### Address bar (`history` and `popstate`)
+
+The hook takes the `history` and `popstate` options of [`createGridUrlSync`](#vanilla-js-creategridurlsync), so a React app gets the same address-bar sync with one option:
+
+```tsx
+// Each filter change adds a history entry, and back and forward apply the URL
+useAGGridUrlSync(gridApi, { autoApplyOnMount: true, history: 'push' })
+
+// Or give the URL to a router. A new function on each render is fine.
+useAGGridUrlSync(gridApi, { history: url => router.replace(url) })
+```
+
+- A user edit, `applyFilters`, `clearFilters` and `loadView` write the URL. `'push'` adds one entry for each of them.
+- A URL apply writes nothing, because the URL holds those filters already: auto-apply on mount, `applyUrlFilters` and the back button.
+- The restore of a stored view on mount replaces the entry. A new sync for an option change, or a `StrictMode` remount, adds no entry.
+- `popstate` is `true` by default with `'push'`. On back or forward, the hook applies the new URL. The view is then no longer active, and the issues of that apply are in `issues`. A grid error goes to `onError` with the context `'popstate'`. A failed address-bar write is `HISTORY_WRITE_FAILED`, to `onError` with the context `'filter-change'`.
+
 #### Hook Options
 
 ```tsx
@@ -602,11 +809,16 @@ interface UseAGGridUrlSyncOptions {
   paramPrefix?: string // Default: 'f_'
   maxValueLength?: number // Default: 200
   onParseError?: (error: Error) => void
+  throwOnError?: boolean | ((issue: URLSyncError) => boolean) // Default: false
+
+  // Address bar (see Address bar above)
+  history?: 'none' | 'replace' | 'push' | ((url: string) => void) // Default: 'none'
+  popstate?: boolean // Default: true with 'push', else false
 
   // React-specific options
   autoApplyOnMount?: boolean // Default: false
   enabledWhenReady?: boolean // Default: true
-  onError?: (error: Error, context: string) => void // Advanced error handling
+  onError?: (error: Error, context: string) => void // Operation failures (see Error Handling)
 
   // Saved views: setting a key enables the feature and namespaces its storage
   storageKey?: string // Default: undefined (saved views disabled)
@@ -615,19 +827,21 @@ interface UseAGGridUrlSyncOptions {
 
 #### Hook Return Values
 
-| Property             | Type                             | Description                                     |
-| -------------------- | -------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
-| `shareUrl`           | `(baseUrl?: string) => string`   | Generate shareable URL with current filters     |
-| `getQueryParams`     | `() => string`                   | Get filter state as query parameters            |
-| `applyUrlFilters`    | `(url?: string) => void`         | Apply filters from URL to grid                  |
-| `clearFilters`       | `() => void`                     | Clear all text filters                          |
-| `isReady`            | `boolean`                        | Whether grid API is available and hook is ready |
-| `currentUrl`         | `string`                         | Current URL with filters applied                |
-| `hasFilters`         | `boolean`                        | Whether the grid has supported filters          |
-| `parseUrlFilters`    | `(url: string) => FilterState`   | Parse filters from URL without applying         |
-| `applyFilters`       | `(filters: FilterState) => void` | Apply filter state object to grid               |
-| `getFiltersAsFormat` | `(format: 'querystring'          | 'json'                                          | 'base64') => string`                                       | Serialize filters to any supported format (for sharing/export) |
-| `getCurrentFormat`   | `() => 'individual'              | 'grouped'`                                      | Get the current serialization mode (individual or grouped) |
+| Property               | Type                                                      | Description                                                                                       |
+| ---------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `shareUrl`             | `(baseUrl?: string) => string`                            | Generate shareable URL with current filters                                                       |
+| `getQueryParams`       | `() => string`                                            | Get filter state as query parameters                                                              |
+| `applyUrlFilters`      | `(url?: string) => void`                                  | Apply filters from URL to grid                                                                    |
+| `clearFilters`         | `() => void`                                              | Clear all text filters                                                                            |
+| `isReady`              | `boolean`                                                 | Whether the grid API is available and the hook is ready. `false` after AG Grid destroys the grid. |
+| `currentUrl`           | `string`                                                  | Current URL with filters applied                                                                  |
+| `hasFilters`           | `boolean`                                                 | Whether the grid has supported filters                                                            |
+| `issues`               | `readonly URLSyncError[]`                                 | Filters that the latest URL apply or URL write dropped (see Error Handling)                       |
+| `parseUrlFilters`      | `(url: string) => FilterState`                            | Parse filters from URL without applying                                                           |
+| `applyFilters`         | `(filters: FilterState) => void`                          | Apply filter state object to grid                                                                 |
+| `getFiltersAsFormat`   | `(format: 'querystring' \| 'json' \| 'base64') => string` | Serialize filters to any supported format (for sharing/export)                                    |
+| `getSerializationMode` | `() => 'individual' \| 'grouped'`                         | Get the current serialization mode (individual or grouped)                                        |
+| `getCurrentFormat`     | `() => 'individual' \| 'grouped'`                         | **Deprecated** (removed in 0.6.0): use `getSerializationMode`                                     |
 
 Saved views (inert unless `storageKey` is set):
 
@@ -639,10 +853,58 @@ Saved views (inert unless `storageKey` is set):
 | `loadView`     | `(id: string \| null) => void`       | Apply a saved view, or pass `null` to reset to unfiltered               |
 | `deleteView`   | `(id: string) => void`               | Delete a saved view                                                     |
 
-> **Note:** `getFiltersAsFormat` and `getCurrentFormat` are especially useful for grouped serialization, format conversion, and advanced sharing scenarios.
+> **Note:** `getFiltersAsFormat` and `getSerializationMode` are especially useful for grouped serialization, format conversion, and advanced sharing scenarios.
 
 ### Saved Views
 
+The views are part of `createGridUrlSync`. The React hook uses the same code, so a vanilla app and a React app get the same rules.
+
+#### Saved views in vanilla JS
+
+Give the `views` option a view store. `createViewStore` is in its own entry, so an app with no saved views does not get the storage code.
+
+```ts
+import { createGridUrlSync } from 'ag-grid-url-sync'
+import { createViewStore } from 'ag-grid-url-sync/view-storage'
+
+const sync = createGridUrlSync({
+  api: gridApi,
+  history: 'push',
+  views: createViewStore('orders')
+})
+
+const { views, activeViewId } = sync.getSnapshot()
+
+const view = sync.saveView('Open orders') // GridView, or null if the save failed
+sync.loadView(view.id)
+sync.loadView(null) // clear the filters
+sync.deleteView(view.id)
+```
+
+You can also give your own `ViewStore`, for example one that talks to a server. With no `views` option, `views` is `[]`, `activeViewId` is `null`, and the three methods do nothing.
+
+Rules for the vanilla API:
+
+- **`activeViewId` is tracked.** `saveView`, `loadView` and the restore of the stored view set it. A load sets it before the grid write, so a snapshot never shows `null` while the write is still pending.
+- **Any other filter model clears it.** A user edit, `applyUrl`, `applyFilters` and a back-button apply all set `activeViewId` to `null` and clear the stored pointer. A view that AG Grid changes when it applies it stays active.
+- **A hand edit does not make a view active.** If the user types the filters of a view, `activeViewId` stays `null`. When two views have the same model, the active one is the one the user loaded.
+- **A view load writes the URL as a user edit does.** With `history: 'push'`, the back button goes back to the URL from before the load. If the URL does not change, the sync writes no entry. Set and multi filters are kept in a view, but the URL cannot hold them. A view that differs only in those filters adds no entry.
+- **A URL apply writes no history.** This holds for `applyUrl`, the apply on create and the back button.
+- **A failed grid write restores `activeViewId`.** The failure goes to `onIssue` as `GRID_ERROR`.
+- **Deleting is conservative.** If the deleted view is active and the grid still shows it, the grid is cleared. If the user edited the filters, they stay.
+- **Failures go to `onIssue`**, not to `snapshot.issues`. They are `NOT_READY`, `GRID_ERROR`, `VIEW_NOT_FOUND`, `VIEW_NAME_REQUIRED`, `STORAGE_FULL`, `STORAGE_UNAVAILABLE` and `STORAGE_WRITE_FAILED`. `loadView` with an unknown id reads the store again, then reports `VIEW_NOT_FOUND`. After `destroy`, `saveView` and `loadView` report `NOT_READY`, and `deleteView` still deletes from the store.
+
+On create (when `applyUrlOnCreate` is not `false`), the sync picks the starting filters in this order:
+
+1. The URL holds the filters of the stored view (compared in URL form). The sync restores the view with its full model, and keeps `activeViewId` and the pointer. This is how a reload keeps a view that was loaded with `history` on.
+2. The URL has at least one filter. The URL wins. `activeViewId` is `null` and the pointer is cleared. A URL with only bad params does not win.
+3. A stored view exists. The sync restores it. With `history` on, the URL is written with replace, so page load adds no back-button step.
+4. Else, the grid keeps its filters.
+
+A stored pointer that names a missing view is ignored.
+
+#### Saved views in React
+
 Pass a `storageKey` to let users name and revisit filter sets. The key both enables
 the feature and namespaces its storage, so two grids on the same origin must use
 different keys:
@@ -707,7 +969,7 @@ Behaviour worth knowing:
   `onError` with context `'save-view'`. Reads degrade to an empty list instead of
   throwing, so server rendering is safe.
 
-For non-React consumers the same store is available directly:
+The store is also available directly:
 
 ```ts
 import { createViewStore } from 'ag-grid-url-sync/view-storage'
@@ -721,8 +983,9 @@ store.saveView('Engineering', gridApi.getFilterModel())
 - **🔄 Automatic State Management**: Tracks grid state and filter changes automatically
 - **⚡ Ready State**: `isReady` indicates when the grid API is available
 - **🎯 Auto-Apply**: `autoApplyOnMount` applies URL filters when component mounts.
-  It is attempted once per grid: a failure is reported through `onError` and
-  `onParseError` and is not retried on later renders
+  It is attempted once per grid: a failure is reported one time (a bad filter
+  through `onParseError`, any other failure through `onError`) and is not
+  retried on later renders
 - **🧹 Cleanup**: Automatically cleans up resources when component unmounts
 - **🛡️ Error Boundaries**: Graceful error handling with configurable callbacks
 - **📊 Filter Status**: `hasFilters` tracks whether any filters are active
@@ -885,9 +1148,13 @@ Parameter structure:
 
 ## API Reference
 
-### `createUrlSync(gridApi, config?)`
+### `createGridUrlSync(options)`
+
+See [Vanilla JS: `createGridUrlSync`](#vanilla-js-creategridurlsync) for the options. It returns `{ getSnapshot, subscribe, applyUrl, applyFilters, getUrl, saveView, loadView, deleteView, destroy }`. The snapshot is `{ status, url, hasFilters, issues, views, activeViewId }`. See [Saved Views](#saved-views) for the view methods.
 
-Factory function to create a new AGGridUrlSync instance.
+### `createUrlSync(gridApi, config?)` (deprecated)
+
+Factory function to create a new AGGridUrlSync instance. Deprecated: use `createGridUrlSync`. It will be removed in 0.6.0.
 
 ```typescript
 import { createUrlSync } from 'ag-grid-url-sync'
@@ -899,7 +1166,9 @@ const urlSync = createUrlSync(gridApi, {
 })
 ```
 
-### `AGGridUrlSync` Class
+### `AGGridUrlSync` Class (deprecated)
+
+Deprecated: use `createGridUrlSync`. It will be removed in 0.6.0.
 
 #### Constructor
 
@@ -918,7 +1187,7 @@ const url = urlSync.generateUrl('https://app.com/page')
 // https://app.com/page?f_name_contains=john
 ```
 
-##### `getUrlState(baseUrl?: string): { url: string; hasFilters: boolean }`
+##### `getUrlState(baseUrl?: string): { url: string; hasFilters: boolean; issues: readonly URLSyncError[] }`
 
 Generates the same URL as `generateUrl`, and tells if the grid has filters that the library supports. It reads the grid one time for both values. `hasFilters` comes from the filter state, not from the URL, because the URL also keeps the page's own params.
 
@@ -927,6 +1196,8 @@ const { url, hasFilters } = urlSync.getUrlState('https://app.com/page?tab=1')
 // url: https://app.com/page?tab=1 (no filters), hasFilters: false
 ```
 
+`issues` holds the filters that this call dropped, for example a text value over `maxValueLength`.
+
 ##### `getQueryParams(): string`
 
 Gets the current filter state as URL query parameters.
@@ -936,17 +1207,17 @@ const params = urlSync.getQueryParams()
 // ?f_name_contains=john
 ```
 
-##### `applyFromUrl(url?: string): void`
+##### `applyFromUrl(url?: string): { issues: readonly URLSyncError[] }`
 
-Applies filters from a URL to the grid.
+Applies filters from a URL to the grid, and returns the filters in the URL that were dropped.
 
 ```typescript
 urlSync.applyFromUrl('https://app.com/page?f_name_contains=john')
 ```
 
-##### `applyFilters(filterState: FilterState): void`
+##### `applyFilters(filterState: FilterState): { issues: readonly URLSyncError[] }`
 
-Applies a filter state object to the grid.
+Applies a filter state object to the grid, and returns the filters that were dropped (for example a number filter on a text column).
 
 ```typescript
 urlSync.applyFilters({
@@ -958,7 +1229,7 @@ urlSync.applyFilters({
 })
 ```
 
-##### `clearFilters(): void`
+##### `clearFilters(): { issues: readonly URLSyncError[] }`
 
 Clears all text filters from the grid.
 
@@ -992,8 +1263,10 @@ interface AGGridUrlSyncConfig {
   // Parameter name for grouped mode (default: 'grid_filters')
   groupedParam?: string
 
-  // Prefix for URL parameters (default: 'f_')
-  // In grouped mode, this affects individual parameter names within the group
+  // Prefix for URL parameters in individual mode (default: 'f_')
+  // A prefix without a trailing '_' gets one ('filter' -> 'filter_name_contains').
+  // An empty prefix means the default. Grouped mode always uses 'f_' inside the
+  // grouped value, so grouped URLs do not change with this option.
   paramPrefix?: string
 
   // Maximum length for filter values (default: 200)