ag-grid-url-sync 0.3.0 → 0.5.0

package/README.md

@@ -196,12 +196,11 @@ import type {
 ```typescript
 import { parseUrlFilters } from 'ag-grid-url-sync/url-parser'
 import { DEFAULT_CONFIG } from 'ag-grid-url-sync/validation'
-import type { FilterState } from 'ag-grid-url-sync/types'
+import type { FilterState, ParseConfig } from 'ag-grid-url-sync/types'
 
 function getFiltersFromUrl(url: string): FilterState {
-  const config = {
-    gridApi: null, // Not needed for parsing
-    ...DEFAULT_CONFIG,
+  const config: ParseConfig = {
+    ...DEFAULT_CONFIG, // gridApi is not needed for parsing
     onParseError: error => console.error('Parse error:', error)
   }
 
@@ -209,18 +208,32 @@ function getFiltersFromUrl(url: string): FilterState {
 }
 ```
 
+`parseUrlFilters` reads the input with these rules, in this order:
+
+| #   | Input                       | Result                   | Example                                   |
+| --- | --------------------------- | ------------------------ | ----------------------------------------- |
+| 1   | A host with no scheme       | Throws `InvalidURLError` | `example.com?…`, `localhost:3000?…`       |
+| 2   | Starts with a scheme        | Absolute URL             | `https://example.com/users?f_name_eq=bob` |
+| 3   | Starts with `/`, `?` or `#` | Relative URL             | `/users?f_name_eq=bob`, `?f_name_eq=bob`  |
+| 4   | Anything else               | Raw query string         | `f_name_eq=bob`                           |
+
+- A relative path must start with `/`. `users?f_name_eq=bob` matches rule 4, so it gives no filters.
+- A bare `localhost?…` with no port cannot be told apart from a raw query, so it matches rule 4.
+- In a raw query string, a `?` or `#` is part of a param name or value.
+
+`InvalidURLError` is thrown for rule 1, and for any input that the `URL` constructor rejects under rules 2 and 3 (for example `http://` or `//[`). A param that is not valid is skipped and sent to `onParseError`.
+
 #### Example: Custom URL Generator
 
 ```typescript
-import { generateUrl, serializeFilters } from 'ag-grid-url-sync/url-generator'
-import type { FilterState } from 'ag-grid-url-sync/types'
+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'
 
 function createShareableUrl(filters: FilterState, baseUrl: string): string {
-  const config = {
-    gridApi: null, // Not needed for generation
-    paramPrefix: 'f_',
-    maxValueLength: 200,
-    onParseError: () => {}
+  const config: ParseConfig = {
+    ...DEFAULT_CONFIG, // gridApi is not needed for generation
+    maxValueLength: 500
   }
 
   return generateUrl(baseUrl, filters, config)
@@ -300,6 +313,10 @@ interface AGGridUrlSyncConfig {
 }
 ```
 
+When the library reads a URL, it reads only the `groupedParam` name and decodes it with the configured `format`. It does not guess the format. This works in both modes, so a grouped link opens in an app in individual mode when the name and format match. If the param is present and not empty, the prefixed params are not read.
+
+> **Note:** A URL written with a different `groupedParam` or `format` does not decode. If you change either option, links that were shared before the change stop working.
+
 ### Format Options
 
 #### QueryString Format (Default)
@@ -420,7 +437,7 @@ import {
 
 ### Error Handling for Grouped Serialization
 
-You can provide a custom error handler to gracefully handle malformed grouped parameters or serialization errors. The library will throw an `InvalidSerializationError` for invalid formats:
+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:
 
 ```typescript
 import { InvalidSerializationError } from 'ag-grid-url-sync/types'
@@ -440,6 +457,18 @@ const urlSync = createUrlSync(gridApi, {
 })
 ```
 
+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:
+
+```typescript
+import { InvalidFilterError } from 'ag-grid-url-sync/types'
+
+const isFilterError = (error: Error) =>
+  error instanceof InvalidFilterError ||
+  error.cause instanceof InvalidFilterError
+```
+
 ### Exports
 
 The package supports granular subpath exports for advanced usage and optimal bundle size:
@@ -450,6 +479,7 @@ The package supports granular subpath exports for advanced usage and optimal bun
 - `ag-grid-url-sync/url-parser` – URL parsing utilities
 - `ag-grid-url-sync/url-generator` – URL generation utilities
 - `ag-grid-url-sync/grid-integration` – AG Grid integration helpers
+- `ag-grid-url-sync/view-storage` – localStorage-backed saved views
 - `ag-grid-url-sync/types` – TypeScript types
 
 Refer to the [package.json](./package.json) for the full export map.
@@ -577,6 +607,9 @@ interface UseAGGridUrlSyncOptions {
   autoApplyOnMount?: boolean // Default: false
   enabledWhenReady?: boolean // Default: true
   onError?: (error: Error, context: string) => void // Advanced error handling
+
+  // Saved views: setting a key enables the feature and namespaces its storage
+  storageKey?: string // Default: undefined (saved views disabled)
 }
 ```
 
@@ -590,22 +623,110 @@ interface UseAGGridUrlSyncOptions {
 | `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 grid has any active text filters        |
+| `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) |
 
+Saved views (inert unless `storageKey` is set):
+
+| Property       | Type                                 | Description                                                             |
+| -------------- | ------------------------------------ | ----------------------------------------------------------------------- |
+| `views`        | `GridView[]`                         | Saved views for this grid, in save order. Empty when views are disabled |
+| `activeViewId` | `string \| null`                     | Id of the view currently applied to the grid, or `null` when none is    |
+| `saveView`     | `(name: string) => GridView \| null` | Save current filters under a name; overwrites an existing name in place |
+| `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.
 
+### Saved Views
+
+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:
+
+```tsx
+const { views, activeViewId, saveView, loadView, deleteView } =
+  useAGGridUrlSync(gridApi, { storageKey: 'employee-grid' })
+
+// One handler each, as a user drives them: save whatever is currently filtered,
+// then apply or remove a view by id in a later interaction.
+const handleSave = () => saveView('Engineering, high salary')
+const handleLoad = (id: string) => loadView(id)
+const handleDelete = (id: string) => deleteView(id)
+const handleReset = () => loadView(null) // back to an unfiltered grid
+```
+
+Render the list from `views` and drive the buttons from it. `views[i].id` is only
+stale immediately after a mutation, not during render. If you do need the new
+view's id in the same handler that saved it, use `saveView`'s return value rather
+than reading it back out of `views`: that array is React state, so it does not
+update until the next render.
+
+Only the filter model is stored, using AG Grid's native format so set filters and
+combined conditions survive a round trip. Column order, row selection and expanded
+groups are not stored.
+
+Behaviour worth knowing:
+
+- **Names are unique.** Saving over an existing name updates that view in place,
+  keeping its id and list position, so "load, adjust, save under the same name" is
+  how you update one. Names are trimmed and must not be empty.
+- **`activeViewId` describes the live grid**, not what is persisted. A stored view
+  is only applied on mount when `autoApplyOnMount` is set, so with it off this
+  stays `null` until you call `loadView` or `saveView`.
+- **Filtering away from a view unloads it.** `activeViewId` returns to `null` as
+  soon as the grid stops showing that view, including through routes that never
+  mention views: `clearFilters`, `applyFilters`, `applyUrlFilters`, or the user
+  editing a filter in the grid's own UI. The stored pointer is cleared with it,
+  so `autoApplyOnMount` will not bring the view back on the next load. The grid
+  is compared against what it reported once the view was applied, so a view AG
+  Grid normalises (one naming a column the grid no longer has, say) stays loaded
+  and keeps its stored pointer. A write AG Grid defers, such as a restore made
+  before column data types are inferred, is recognised when it lands by the
+  event's `source: 'api'`; on AG Grid versions that do not report a source, a
+  deferred view the grid also normalises unloads when it lands. An API change
+  that filters a column the view does not, such as your own `setFilterModel`
+  over a view the grid ignored, is not taken for the view and unloads it. One
+  that filters only the view's columns cannot be told from the view landing.
+  Render the
+  active state from `activeViewId` and it follows the grid on its own. Replacing
+  `gridApi` also clears `activeViewId`, but keeps the stored pointer, so with
+  `autoApplyOnMount` the view is restored against the new grid.
+- **URL filters win on mount.** With `autoApplyOnMount` set, an incoming URL that
+  carries filters takes precedence over the stored view, so a shared link shows the
+  sender's filters rather than the recipient's saved default. It wins once per
+  grid: switching `storageKey` later restores the new namespace's stored view
+  instead of applying the link again.
+- **Deleting is conservative.** `deleteView` clears the grid only if it still shows
+  exactly that view's filters, so hand-edited filters survive.
+- **Failures are reported, not silent.** A save that cannot be persisted (quota
+  exhausted, storage blocked by policy) returns `null` and reports through
+  `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:
+
+```ts
+import { createViewStore } from 'ag-grid-url-sync/view-storage'
+
+const store = createViewStore('employee-grid')
+store.saveView('Engineering', gridApi.getFilterModel())
+```
+
 ### React Features
 
 - **🔄 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
+- **🎯 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
 - **🧹 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
+- **💾 Saved Views**: `storageKey` enables naming and revisiting filter sets
 
 ### React with Grouped Serialization
 
@@ -797,6 +918,15 @@ const url = urlSync.generateUrl('https://app.com/page')
 // https://app.com/page?f_name_contains=john
 ```
 
+##### `getUrlState(baseUrl?: string): { url: string; hasFilters: boolean }`
+
+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.
+
+```typescript
+const { url, hasFilters } = urlSync.getUrlState('https://app.com/page?tab=1')
+// url: https://app.com/page?tab=1 (no filters), hasFilters: false
+```
+
 ##### `getQueryParams(): string`
 
 Gets the current filter state as URL query parameters.

package/dist/core/ag-grid-url-sync.d.ts

@@ -17,6 +17,19 @@ export declare class AGGridUrlSync {
      * @returns URL string with filter parameters
      */
     generateUrl(baseUrl?: string): string;
+    /**
+     * Generates a URL with the current filter state, and tells if the grid has
+     * filters that the library supports.
+     *
+     * Reads the grid filter model one time, so an error in it is reported one
+     * time. `hasFilters` comes from the filter state, not from the URL: the URL
+     * also keeps the page's own params (#215).
+     * @param baseUrl - Optional base URL (defaults to current URL)
+     */
+    getUrlState(baseUrl?: string): {
+        url: string;
+        hasFilters: boolean;
+    };
     /**
      * Gets the current filter state as URL query parameters
      * @returns Query parameter string

package/dist/core/ag-grid-url-sync.js

@@ -3,107 +3,62 @@ import { parseUrlFilters } from './url-parser.js';
 import { generateUrl } from './url-generator.js';
 import { getFilterModel, applyFilterModel } from './grid-integration.js';
 import { serializeGrouped } from './serialization/grouped.js';
-/**
- * AGGridUrlSync class for synchronizing AG Grid text filters with URL parameters
- */
 export class AGGridUrlSync {
     config;
-    /**
-     * Creates a new instance of AGGridUrlSync
-     * @param gridApi - AG Grid API instance
-     * @param config - Optional configuration options
-     */
     constructor(gridApi, config = {}) {
+        const definedConfig = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
         this.config = {
             gridApi,
             ...DEFAULT_CONFIG,
-            ...config
+            ...definedConfig
         };
     }
-    /**
-     * Generates a URL with the current filter state
-     * @param baseUrl - Optional base URL (defaults to current URL)
-     * @returns URL string with filter parameters
-     */
     generateUrl(baseUrl) {
+        return this.getUrlState(baseUrl).url;
+    }
+    getUrlState(baseUrl) {
         const filterState = getFilterModel(this.config);
         const url = baseUrl ?? window.location.href;
-        return generateUrl(url, filterState, this.config);
+        return {
+            url: generateUrl(url, filterState, this.config),
+            hasFilters: Object.keys(filterState).length > 0
+        };
     }
-    /**
-     * Gets the current filter state as URL query parameters
-     * @returns Query parameter string
-     */
     getQueryParams() {
         const url = this.generateUrl();
         const urlObj = new URL(url);
         return urlObj.search;
     }
-    /**
-     * Applies filters from a URL to the grid
-     * @param url - Optional URL to parse (defaults to current URL)
-     */
     applyFromUrl(url) {
         const urlToParse = url ?? window.location.href;
         const filterState = parseUrlFilters(urlToParse, this.config);
         this.applyFilters(filterState);
     }
-    /**
-     * Applies a filter state object to the grid
-     * @param filterState - Filter state to apply
-     */
     applyFilters(filterState) {
         applyFilterModel(filterState, this.config);
     }
-    /**
-     * Clears all text filters from the grid
-     */
     clearFilters() {
         this.applyFilters({});
     }
-    /**
-     * Cleans up any resources or event listeners
-     */
     destroy() {
-        // Currently no cleanup needed, but included for future use
     }
-    /**
-     * Gets the current serialization mode
-     * @returns The current serialization mode
-     */
     getSerializationMode() {
         return this.config.serialization;
     }
-    /**
-     * Gets the current format (for grouped mode)
-     * @returns The current format
-     */
     getCurrentFormat() {
         return this.config.format;
-    } /**
-     * Gets filters in a specific format (useful for sharing/export)
-     * @param format - The format to serialize to
-     * @returns Serialized filter string
-     */
+    }
     getFiltersAsFormat(format) {
         const filterState = getFilterModel(this.config);
-        // Create temporary config for the requested format
         const tempConfig = {
             ...this.config,
             format,
             serialization: 'grouped'
         };
-        // Use the serialization module
         const result = serializeGrouped(filterState, tempConfig);
         return result.value;
     }
 }
-/**
- * Factory function to create a new AGGridUrlSync instance
- * @param gridApi - AG Grid API instance
- * @param config - Optional configuration options
- * @returns AGGridUrlSync instance
- */
 export function createUrlSync(gridApi, config) {
     return new AGGridUrlSync(gridApi, config);
 }

package/dist/core/ag-grid-url-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"ag-grid-url-sync.js","sourceRoot":"","sources":["../../src/core/ag-grid-url-sync.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAE7D;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAgB;IAE9B;;;;OAIG;IACH,YAAY,OAAgB,EAAE,SAA8B,EAAE;QAC5D,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO;YACP,GAAG,cAAc;YACjB,GAAG,MAAM;SACV,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,OAAgB;QAC1B,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/C,MAAM,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC3C,OAAO,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACnD,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,GAAY;QACvB,MAAM,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC9C,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5D,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,WAAwB;QACnC,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAED;;OAEG;IACH,YAAY;QACV,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IACvB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,2DAA2D;IAC7D,CAAC;IAED;;;OAGG;IACH,oBAAoB;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAA;IAClC,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;IAC3B,CAAC,CAAC;;;;OAIC;IACH,kBAAkB,CAAC,MAA2B;QAC5C,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAE/C,mDAAmD;QACnD,MAAM,UAAU,GAAG;YACjB,GAAG,IAAI,CAAC,MAAM;YACd,MAAM;YACN,aAAa,EAAE,SAAkB;SAClC,CAAA;QAED,+BAA+B;QAC/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;QAExD,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"ag-grid-url-sync.js","sourceRoot":"","sources":["../../src/core/ag-grid-url-sync.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAK7D,MAAM,OAAO,aAAa;IAChB,MAAM,CAAgB;IAO9B,YAAY,OAAgB,EAAE,MAAM,GAAwB,EAAE;QAI5D,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAC3C,CAAA;QAExB,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO;YACP,GAAG,cAAc;YACjB,GAAG,aAAa;SACjB,CAAA;IACH,CAAC;IAOD,WAAW,CAAC,OAAgB;QAC1B,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,CAAA;IACtC,CAAC;IAWD,WAAW,CAAC,OAAgB;QAC1B,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC/C,MAAM,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC3C,OAAO;YACL,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;YAC/C,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;SAChD,CAAA;IACH,CAAC;IAMD,cAAc;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;QAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAA;IACtB,CAAC;IAMD,YAAY,CAAC,GAAY;QACvB,MAAM,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAA;QAC9C,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5D,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC;IAMD,YAAY,CAAC,WAAwB;QACnC,gBAAgB,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAKD,YAAY;QACV,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IACvB,CAAC;IAKD,OAAO;IAEP,CAAC;IAMD,oBAAoB;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAA;IAClC,CAAC;IAMD,gBAAgB;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;IAC3B,CAAC;IAKD,kBAAkB,CAAC,MAA2B;QAC5C,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAG/C,MAAM,UAAU,GAAG;YACjB,GAAG,IAAI,CAAC,MAAM;YACd,MAAM;YACN,aAAa,EAAE,SAAkB;SAClC,CAAA;QAGD,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;QAExD,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC;CACF;AAQD,MAAM,UAAU,aAAa,CAC3B,OAAgB,EAChB,MAA4B;IAE5B,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}

package/dist/core/grid-integration.js

@@ -1,6 +1,4 @@
 import { AG_GRID_OPERATION_NAMES, REVERSE_AG_GRID_OPERATION_NAMES, TEXT_FILTER_OPERATIONS, NUMBER_FILTER_OPERATIONS, DATE_FILTER_OPERATIONS } from './types.js';
-// Map AG Grid number operations to our internal number operations
-// Since AG Grid uses generic names, we need to be explicit about number operations
 const AG_GRID_TO_NUMBER_OPERATION_MAP = {
     lessThan: 'lessThan',
     lessThanOrEqual: 'lessThanOrEqual',
@@ -12,74 +10,48 @@ const AG_GRID_TO_NUMBER_OPERATION_MAP = {
     blank: 'blank',
     notBlank: 'notBlank'
 };
-/**
- * Type guard to check if a value is a valid number operation key
- */
 function isValidNumberOperation(operation) {
     return Boolean(operation && operation in AG_GRID_TO_NUMBER_OPERATION_MAP);
 }
-/**
- * Converts a date string to ISO format (YYYY-MM-DD)
- * Handles both date strings and undefined values
- * Returns an empty string if the input is undefined or invalid
- */
 function toIsoDateString(val) {
     if (!val)
         return '';
     const match = val.match(/^(\d{4}-\d{2}-\d{2})/);
     return match?.[1] ? match[1] : val || '';
 }
-/**
- * Type predicate to check if an operation is a valid text filter operation
- */
 function isTextFilterOperation(operation) {
     return TEXT_FILTER_OPERATIONS.includes(operation);
 }
-/**
- * Type predicate to check if an operation is a valid number filter operation
- */
 function isNumberFilterOperation(operation) {
     return NUMBER_FILTER_OPERATIONS.includes(operation);
 }
-/**
- * Type predicate to check if an operation is a valid date filter operation
- */
 function isDateFilterOperation(operation) {
     return DATE_FILTER_OPERATIONS.includes(operation);
 }
-/**
- * Detects the expected filter type for a column based on AG Grid configuration
- */
 export function detectColumnFilterType(gridApi, columnId) {
     try {
         const column = gridApi.getColumn(columnId);
         if (!column)
-            return 'text'; // Default to text for unknown columns
+            return 'text';
         const colDef = column.getColDef();
-        // 1. Explicit filter configuration takes priority
         if (colDef.filter === 'agDateColumnFilter')
             return 'date';
         if (colDef.filter === 'agNumberColumnFilter')
             return 'number';
         if (colDef.filter === 'agTextColumnFilter')
             return 'text';
-        // 2. Cell data type configuration
         if (colDef.cellDataType === 'date')
             return 'date';
         if (colDef.cellDataType === 'number')
             return 'number';
         if (colDef.cellDataType === 'text')
             return 'text';
-        // 3. Default to text for backward compatibility
         return 'text';
     }
     catch {
-        return 'text'; // Safe fallback
+        return 'text';
     }
 }
-/**
- * Gets the current filter model from AG Grid
- */
 export function getFilterModel(config) {
     try {
         const model = config.gridApi.getFilterModel();
@@ -91,28 +63,20 @@ export function getFilterModel(config) {
             if (!filter || typeof filter !== 'object')
                 continue;
             const { filterType, type, filter: value, filterTo, dateFrom, dateTo } = filter;
-            // Handle text filters
             if (filterType === 'text') {
-                // Map AG Grid operations back to our internal operations using centralized mapping
                 const internalOperation = REVERSE_AG_GRID_OPERATION_NAMES[type];
-                // Use type predicate to validate and narrow the type
                 if (internalOperation && isTextFilterOperation(internalOperation)) {
                     filterState[column] = {
                         filterType: 'text',
-                        type: internalOperation, // Now properly typed as TextFilterOperation
+                        type: internalOperation,
                         filter: String(value || '')
                     };
                 }
             }
-            // Handle number filters
             else if (filterType === 'number') {
-                // For number filters, we need to handle the mapping carefully since
-                // AG Grid uses the same operation names for numbers and dates
-                // Use the explicit number mapping instead of the reverse AG Grid mapping
                 const internalOperation = isValidNumberOperation(type)
                     ? AG_GRID_TO_NUMBER_OPERATION_MAP[type]
                     : null;
-                // If the operation type is not recognized, report the error
                 if (!internalOperation) {
                     if (config.onParseError) {
                         config.onParseError(new Error(`Unknown number filter operation '${type}' for column '${column}'. ` +
@@ -120,20 +84,16 @@ export function getFilterModel(config) {
                     }
                     continue;
                 }
-                // Use type predicate to validate and narrow the type
                 if (internalOperation && isNumberFilterOperation(internalOperation)) {
-                    // Validate that the filter value is actually a number
                     const numericValue = typeof value === 'number' ? value : Number(value);
-                    // Skip invalid number filters
                     if (isNaN(numericValue)) {
                         continue;
                     }
                     const numberFilter = {
                         filterType: 'number',
-                        type: internalOperation, // Now properly typed as NumberFilterOperation
+                        type: internalOperation,
                         filter: numericValue
                     };
-                    // Handle range operations
                     if (internalOperation === 'inRange' && typeof filterTo === 'number') {
                         ;
                         numberFilter.filterTo = filterTo;
@@ -141,14 +101,9 @@ export function getFilterModel(config) {
                     filterState[column] = numberFilter;
                 }
             }
-            // Handle date filters
             else if (filterType === 'date') {
-                // Map AG Grid date operations back to our internal operations
                 const internalOperation = REVERSE_AG_GRID_OPERATION_NAMES[type];
-                // For date operations, we need to handle the special case where AG Grid uses
-                // generic operation names but we have date-specific internal names
                 let mappedOperation = internalOperation;
-                // Map AG Grid generic date operations to our date-specific operations
                 const AG_GRID_TO_DATE_OPERATION_MAP = {
                     lessThan: 'dateBefore',
                     lessThanOrEqual: 'dateBeforeOrEqual',
@@ -159,14 +114,12 @@ export function getFilterModel(config) {
                 mappedOperation = type
                     ? AG_GRID_TO_DATE_OPERATION_MAP[type] || internalOperation
                     : internalOperation;
-                // Use type predicate to validate and narrow the type
                 if (mappedOperation && isDateFilterOperation(mappedOperation)) {
                     const dateFilter = {
                         filterType: 'date',
                         type: mappedOperation,
                         filter: toIsoDateString(dateFrom || String(value || ''))
                     };
-                    // Handle date range operations (AG Grid uses dateFrom/dateTo)
                     if (mappedOperation === 'dateRange' && dateTo) {
                         ;
                         dateFilter.filterTo = toIsoDateString(dateTo);
@@ -184,21 +137,16 @@ export function getFilterModel(config) {
         return {};
     }
 }
-/**
- * Converts internal filter to AG Grid filter format
- */
 function convertToAGGridFilter(filter) {
     if (filter.filterType === 'date') {
-        // Handle date range operations
         if (filter.type === 'dateRange') {
             return {
                 filterType: 'date',
-                type: 'inRange', // AG Grid uses 'inRange' for date ranges
+                type: 'inRange',
                 dateFrom: filter.filter,
                 dateTo: filter.filterTo || null
             };
         }
-        // Handle blank operations for dates
         if (filter.type === 'blank' || filter.type === 'notBlank') {
             return {
                 filterType: 'date',
@@ -207,7 +155,6 @@ function convertToAGGridFilter(filter) {
                 dateTo: null
             };
         }
-        // Map date-specific operations to AG Grid generic operations
         const dateOperationMapping = {
             dateBefore: 'lessThan',
             dateBeforeOrEqual: 'lessThanOrEqual',
@@ -231,7 +178,6 @@ function convertToAGGridFilter(filter) {
                 type: agGridOperation,
                 filter: filter.filter
             };
-            // Only include filterTo if it's defined
             return filter.filterTo !== undefined
                 ? { ...baseFilter, filterTo: filter.filterTo }
                 : baseFilter;
@@ -242,7 +188,6 @@ function convertToAGGridFilter(filter) {
             filter: filter.filter
         };
     }
-    // Text filter handling
     const agGridOperation = AG_GRID_OPERATION_NAMES[filter.type];
     return {
         filterType: 'text',
@@ -250,18 +195,13 @@ function convertToAGGridFilter(filter) {
         filter: filter.filter
     };
 }
-/**
- * Applies a filter state to AG Grid
- */
 export function applyFilterModel(filterState, config) {
     try {
         const model = {};
         for (const [column, filter] of Object.entries(filterState)) {
             if (!filter || typeof filter !== 'object')
                 continue;
-            // Detect expected filter type for this column
             const expectedType = detectColumnFilterType(config.gridApi, column);
-            // Validate filter type compatibility
             if (filter.filterType === 'date' && expectedType !== 'date') {
                 console.warn(`Column '${column}' expects a ${expectedType} filter but received a date filter. This may indicate a configuration mismatch in the column definition or filter application.`);
                 continue;
@@ -270,13 +210,11 @@ export function applyFilterModel(filterState, config) {
                 console.warn(`Column '${column}' expects a ${expectedType} filter but received a number filter. This may indicate a configuration mismatch in the column definition or filter application.`);
                 continue;
             }
-            // Convert to AG Grid filter model
             const agGridFilter = convertToAGGridFilter(filter);
             if (agGridFilter) {
                 model[column] = agGridFilter;
             }
         }
-        // Apply the filter model to AG Grid
         config.gridApi.setFilterModel(model);
     }
     catch (error) {