ag-grid-url-sync 0.2.4 → 0.4.1

package/dist/core/view-storage.js

@@ -0,0 +1,112 @@
+const SCHEMA_VERSION = 'v1';
+const keyFor = (storageKey) => `ag-grid-url-sync:views:${SCHEMA_VERSION}:${storageKey}`;
+const empty = () => ({ views: [], activeId: null });
+function isGridView(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.id === 'string' &&
+        typeof candidate.name === 'string' &&
+        typeof candidate.updatedAt === 'number' &&
+        typeof candidate.filterModel === 'object' &&
+        candidate.filterModel !== null);
+}
+function createId() {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    return `view-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+}
+export function createViewStore(storageKey) {
+    const key = keyFor(storageKey);
+    const read = () => {
+        if (typeof window === 'undefined')
+            return empty();
+        let raw = null;
+        try {
+            raw = window.localStorage.getItem(key);
+        }
+        catch {
+            return empty();
+        }
+        if (!raw)
+            return empty();
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null)
+                return empty();
+            const { views, activeId } = parsed;
+            const validViews = Array.isArray(views) ? views.filter(isGridView) : [];
+            return {
+                views: validViews,
+                activeId: typeof activeId === 'string' &&
+                    validViews.some(view => view.id === activeId)
+                    ? activeId
+                    : null
+            };
+        }
+        catch {
+            return empty();
+        }
+    };
+    const write = (next) => {
+        if (typeof window === 'undefined') {
+            throw new Error('Browser storage is unavailable.');
+        }
+        try {
+            window.localStorage.setItem(key, JSON.stringify(next));
+        }
+        catch (error) {
+            const isQuota = typeof DOMException !== 'undefined' &&
+                error instanceof DOMException &&
+                (error.name === 'QuotaExceededError' ||
+                    error.name === 'NS_ERROR_DOM_QUOTA_REACHED');
+            throw new Error(isQuota
+                ? 'Browser storage is full. Delete a saved view and try again.'
+                : 'Error writing to storage.', { cause: error });
+        }
+    };
+    return {
+        listViews: () => read().views,
+        getActiveViewId: () => read().activeId,
+        persistActiveViewId: (id) => {
+            const current = read();
+            if (current.activeId === id)
+                return;
+            write({ ...current, activeId: id });
+        },
+        saveView: (name, filterModel) => {
+            const trimmedName = name.trim();
+            if (!trimmedName) {
+                throw new Error('A view name is required.');
+            }
+            const current = read();
+            const existing = current.views.find(view => view.name === trimmedName);
+            const view = {
+                id: existing?.id ?? createId(),
+                name: trimmedName,
+                updatedAt: Date.now(),
+                filterModel: structuredClone(filterModel ?? {})
+            };
+            write({
+                views: existing
+                    ? current.views.map(candidate => candidate.id === existing.id ? view : candidate)
+                    : [...current.views, view],
+                activeId: view.id
+            });
+            return view;
+        },
+        deleteView: (id) => {
+            const current = read();
+            const views = current.views.filter(view => view.id !== id);
+            if (views.length === current.views.length && current.activeId !== id) {
+                return;
+            }
+            write({
+                views,
+                activeId: current.activeId === id ? null : current.activeId
+            });
+        }
+    };
+}
+//# sourceMappingURL=view-storage.js.map

package/dist/core/view-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-storage.js","sourceRoot":"","sources":["../../src/core/view-storage.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,3 +4,6 @@ export { validateFilterValue, DEFAULT_CONFIG } from './core/validation.js';
 export { parseUrlFilters, parseFilterParam } from './core/url-parser.js';
 export { serializeFilters, generateUrl } from './core/url-generator.js';
 export { getFilterModel, applyFilterModel } from './core/grid-integration.js';
+export type { GridView, ViewStore } from './core/view-storage.js';
+export { serializeGrouped, deserializeGrouped, detectGroupedSerialization, getAvailableFormats, getFormatSerializer } from './core/serialization/grouped.js';
+export { QueryStringSerializer, JsonSerializer, Base64Serializer } from './core/serialization/formats.js';

package/dist/index.js

@@ -1,12 +1,9 @@
-// Export core functionality (vanilla JS)
 export { AGGridUrlSync, createUrlSync } from './core/ag-grid-url-sync.js';
 export * from './core/types.js';
-// Validation utilities
 export { validateFilterValue, DEFAULT_CONFIG } from './core/validation.js';
-// URL parsing utilities
 export { parseUrlFilters, parseFilterParam } from './core/url-parser.js';
-// URL generation utilities
 export { serializeFilters, generateUrl } from './core/url-generator.js';
-// AG Grid integration utilities
 export { getFilterModel, applyFilterModel } from './core/grid-integration.js';
+export { serializeGrouped, deserializeGrouped, detectGroupedSerialization, getAvailableFormats, getFormatSerializer } from './core/serialization/grouped.js';
+export { QueryStringSerializer, JsonSerializer, Base64Serializer } from './core/serialization/formats.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAEzE,cAAc,iBAAiB,CAAA;AAE/B,uBAAuB;AACvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1E,wBAAwB;AACxB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAExE,2BAA2B;AAC3B,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAEvE,gCAAgC;AAChC,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAEzE,cAAc,iBAAiB,CAAA;AAG/B,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAG1E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAGxE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAGvE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAS7E,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EACjB,MAAM,iCAAiC,CAAA"}

package/dist/react/index.d.ts

@@ -1,3 +1,4 @@
 export { useAGGridUrlSync } from './use-ag-grid-url-sync.js';
 export type { UseAGGridUrlSyncOptions, UseAGGridUrlSyncReturn } from './types.js';
+export type { GridView } from '../core/view-storage.js';
 export type { FilterState, ColumnFilter, FilterOperation, AGGridUrlSyncConfig, GridApi } from '../core/types.js';

package/dist/react/types.d.ts

@@ -1,15 +1,41 @@
-import type { AGGridUrlSyncConfig, FilterState } from '../core/types.js';
+import type { AGGridUrlSyncConfig, FilterState, SerializationFormat, SerializationMode } from '../core/types.js';
+import type { GridView } from '../core/view-storage.js';
 /**
  * Configuration options for the React hook
  */
 export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
+    /**
+     * Enables saved views, persisted to localStorage under this key.
+     *
+     * The key both switches the feature on and namespaces the storage, so two
+     * grids on the same origin must use different keys. Omit it and the view
+     * members of the hook's return value are inert.
+     *
+     * @example 'employee-grid'
+     */
+    storageKey?: string;
     /**
      * Automatically apply URL filters when the component mounts and grid API becomes ready
+     *
+     * Also restores the active saved view when `storageKey` is set. URL filters
+     * take precedence: a shared link should show the sender's filters rather than
+     * the recipient's stored view.
+     *
+     * Attempted once per grid. A failed attempt is reported through `onError` and
+     * `onParseError` and is not retried on later renders; pass a new `gridApi`, or
+     * call `applyUrlFilters`, to try again.
+     *
      * Default: false
      */
     autoApplyOnMount?: boolean;
     /**
      * Whether the hook should be enabled when the grid API is ready
+     *
+     * Set to false and every operation goes inert, saved views included: no URL is
+     * generated, no filters are applied, and no view is saved, loaded or deleted.
+     * `views` still reflects what is in storage, since reading it has no effect on
+     * the grid.
+     *
      * Default: true
      */
     enabledWhenReady?: boolean;
@@ -66,4 +92,85 @@ export interface UseAGGridUrlSyncReturn {
      * @param filters - Filter state to apply
      */
     applyFilters: (filters: FilterState) => void;
+    /**
+     * Get filters in a specific format (useful for sharing/export)
+     * @param format - The format to serialize to
+     * @returns Serialized filter string
+     */
+    getFiltersAsFormat: (format: SerializationFormat) => string;
+    /**
+     * Get the current serialization format
+     * @returns The current format
+     */
+    getCurrentFormat: () => SerializationMode;
+    /**
+     * Saved views for this grid, in save order.
+     * Always an empty array when `storageKey` is not set.
+     */
+    views: GridView[];
+    /**
+     * Id of the view currently applied to the grid, or null when none is.
+     *
+     * This 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 `loadView` or `saveView` is called, even though a previous
+     * session's view is still listed in `views`.
+     *
+     * It goes back to null as soon as the grid stops showing that view, which
+     * includes routes that never mention views: `clearFilters`, `applyFilters`,
+     * `applyUrlFilters`, and the user editing a filter in the grid's own UI. That
+     * also clears the stored pointer, so `autoApplyOnMount` will not restore the
+     * view on the next load either - filtering away from a view is treated as
+     * leaving it, not as a detour back to it.
+     *
+     * "Showing" means the model the grid reported once the view was applied, not
+     * the stored one. A view AG Grid normalises on the way in, such as one naming
+     * a column the grid no longer has, stays loaded and keeps its stored pointer.
+     * A write AG Grid defers is recognised when it lands by the event's
+     * `source: 'api'`. On versions that report no source, a deferred view the
+     * grid also normalises unloads when it lands.
+     *
+     * Replacing `gridApi` clears this too, since nothing has been applied to the
+     * new grid yet, but leaves the stored pointer alone: with `autoApplyOnMount`
+     * the view is restored against the new grid and this becomes non-null again.
+     */
+    activeViewId: string | null;
+    /**
+     * Saves the grid's current filters under a name and makes it active.
+     *
+     * The name is trimmed, and must not be empty. Names are unique: saving over an
+     * existing name updates that view in place, keeping its id and list position,
+     * so "load a view, adjust the filters, save under the same name" is how you
+     * update one.
+     *
+     * @param name - Display name for the view
+     * @returns The saved view, or null if it could not be saved. An empty name, a
+     *   failed write, and being called before the grid is ready are all reported
+     *   through `onError`. Silent when `storageKey` is not set or the hook is
+     *   disabled, since the feature was switched off by configuration rather than
+     *   having failed.
+     */
+    saveView: (name: string) => GridView | null;
+    /**
+     * Applies a saved view's filters to the grid, or clears filters when passed
+     * null. Use `clearFilters` to reset filters independently of saved views.
+     *
+     * Silent when `storageKey` is not set or the hook is disabled; reports through
+     * `onError` when called before the grid is ready, or when the id is not found.
+     *
+     * @param id - Id of the view to load, or null to reset to unfiltered
+     */
+    loadView: (id: string | null) => void;
+    /**
+     * Deletes a saved view. Clears the grid's filters only if the grid still shows
+     * exactly that view's filters, so hand-edited filters survive.
+     *
+     * Unlike `saveView` and `loadView`, this does not need the grid: it works
+     * before the grid API resolves, since deleting only touches storage, so it
+     * never reports a not-ready error. Silent when `storageKey` is not set or the
+     * hook is disabled.
+     *
+     * @param id - Id of the view to delete
+     */
+    deleteView: (id: string) => void;
 }