ag-grid-url-sync 0.5.0 → 0.5.2

package/dist/react/sync-holder.js

@@ -0,0 +1,68 @@
+import { IDLE_SNAPSHOT } from '../core/grid-url-sync.js';
+function sameViews(a, b) {
+    return a.length === b.length && JSON.stringify(a) === JSON.stringify(b);
+}
+export function createSyncHolder() {
+    const listeners = new Set();
+    let current = null;
+    let stopForwarding = null;
+    let idle = IDLE_SNAPSHOT;
+    let carried = [];
+    let merged = null;
+    const withCarried = (from) => {
+        if (merged?.from === from && merged.carried === carried) {
+            return merged.snapshot;
+        }
+        const issues = merged?.from.issues === from.issues && merged.carried === carried
+            ? merged.snapshot.issues
+            : Object.freeze([...carried, ...from.issues]);
+        merged = { from, carried, snapshot: Object.freeze({ ...from, issues }) };
+        return merged.snapshot;
+    };
+    const notify = () => {
+        for (const listener of Array.from(listeners))
+            listener();
+    };
+    return {
+        set(sync) {
+            if (sync === current)
+                return;
+            stopForwarding?.();
+            stopForwarding = null;
+            current = sync;
+            if (sync)
+                stopForwarding = sync.subscribe(notify);
+            notify();
+        },
+        get: () => current,
+        setIdleViews(views) {
+            if (sameViews(idle.views, views))
+                return;
+            idle = views.length
+                ? Object.freeze({ ...IDLE_SNAPSHOT, views: Object.freeze([...views]) })
+                : IDLE_SNAPSHOT;
+            if (!current)
+                notify();
+        },
+        setCarriedIssues(issues) {
+            if (issues === carried)
+                return;
+            carried = issues;
+            if (current)
+                notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot() {
+            if (!current)
+                return idle;
+            const snapshot = current.getSnapshot();
+            return carried.length ? withCarried(snapshot) : snapshot;
+        }
+    };
+}
+//# sourceMappingURL=sync-holder.js.map

package/dist/react/sync-holder.js.map

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

package/dist/react/sync-options.d.ts

@@ -0,0 +1,17 @@
+import type { GridApi } from 'ag-grid-community';
+import type { AGGridUrlSyncConfig, GridUrlSyncOptions, HistoryMode, IssueEvent } from '../core/types.js';
+import type { ViewStore } from '../core/view-storage.js';
+/** The address-bar options of the hook's sync (#270) */
+export interface AddressBarOptions {
+    history: HistoryMode;
+    popstate: boolean | undefined;
+}
+/** The default: the sync never writes history and never follows popstate */
+export declare const NO_ADDRESS_BAR: AddressBarOptions;
+/**
+ * The createGridUrlSync options for the hook. The hook's sync never throws.
+ * It writes history and follows popstate only with the hook's options
+ * (#270). It applies the URL on create only when the hook asks for it
+ * (auto-apply with saved views, #223).
+ */
+export declare function gridUrlSyncOptions(api: GridApi, options: AGGridUrlSyncConfig, onIssue: (event: IssueEvent) => void, views?: ViewStore, applyUrlOnCreate?: boolean, addressBar?: AddressBarOptions): GridUrlSyncOptions;

package/dist/react/sync-options.js

@@ -0,0 +1,22 @@
+import { codecFromOptions } from '../core/codecs.js';
+import { resolveOptions } from '../core/options.js';
+export const NO_ADDRESS_BAR = {
+    history: 'none',
+    popstate: false
+};
+export function gridUrlSyncOptions(api, options, onIssue, views, applyUrlOnCreate = false, addressBar = NO_ADDRESS_BAR) {
+    const resolved = resolveOptions(options);
+    const codec = codecFromOptions(resolved);
+    return {
+        api,
+        codec,
+        maxValueLength: resolved.maxValueLength,
+        history: addressBar.history,
+        popstate: addressBar.popstate,
+        applyUrlOnCreate,
+        throwOnError: false,
+        onIssue,
+        views
+    };
+}
+//# sourceMappingURL=sync-options.js.map

package/dist/react/sync-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-options.js","sourceRoot":"","sources":["../../src/react/sync-options.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAYnD,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,KAAK;CAChB,CAAA;AAQD,MAAM,UAAU,kBAAkB,CAChC,GAAY,EACZ,OAA4B,EAC5B,OAAoC,EACpC,KAAiB,EACjB,gBAAgB,GAAG,KAAK,EACxB,UAAU,GAAsB,cAAc;IAE9C,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAIxC,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAExC,OAAO;QACL,GAAG;QACH,KAAK;QACL,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,gBAAgB;QAChB,YAAY,EAAE,KAAK;QACnB,OAAO;QACP,KAAK;KACN,CAAA;AACH,CAAC"}

package/dist/react/types.d.ts

@@ -1,7 +1,10 @@
-import type { AGGridUrlSyncConfig, FilterState, SerializationFormat, SerializationMode } from '../core/types.js';
+import type { GridApi } from 'ag-grid-community';
+import type { AGGridUrlSyncConfig, ApplyResult, FilterState, GridUrlSyncOptions, GridUrlSyncSnapshot, HistoryMode, SerializationFormat, SerializationMode, URLSyncError } from '../core/types.js';
 import type { GridView } from '../core/view-storage.js';
 /**
  * Configuration options for the React hook
+ *
+ * @deprecated Use `useGridUrlSync` and its types. Removed in 0.6.0.
  */
 export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
     /**
@@ -13,7 +16,7 @@ export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
      *
      * @example 'employee-grid'
      */
-    storageKey?: string;
+    storageKey?: string | undefined;
     /**
      * Automatically apply URL filters when the component mounts and grid API becomes ready
      *
@@ -21,13 +24,14 @@ export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
      * 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.
+     * Attempted once per grid. A failed attempt is reported one time (a bad
+     * filter through `onParseError`, any other failure through `onError`) and is
+     * not retried on later renders; pass a new `gridApi`, or call
+     * `applyUrlFilters`, to try again.
      *
      * Default: false
      */
-    autoApplyOnMount?: boolean;
+    autoApplyOnMount?: boolean | undefined;
     /**
      * Whether the hook should be enabled when the grid API is ready
      *
@@ -38,15 +42,41 @@ export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
      *
      * Default: true
      */
-    enabledWhenReady?: boolean;
+    enabledWhenReady?: boolean | undefined;
     /**
-     * Optional error handler for hook-level errors (initialization, URL operations, etc.)
-     * This supplements the core onParseError callback for comprehensive error handling
+     * How a filter change goes to the address bar, as in `createGridUrlSync`
+     * (#270). A user edit, a view load, `applyFilters` and `clearFilters`
+     * write the URL. A URL apply (auto-apply, `applyUrlFilters`, the back
+     * button) writes nothing, because the URL holds those filters already.
+     * `'replace'` and `'push'` use `window.history`. A function gets the URL,
+     * for a router: a new function on a later render is used, and makes no
+     * new sync.
+     *
+     * Default: 'none'
+     */
+    history?: HistoryMode | undefined;
+    /**
+     * Apply the URL when the browser's back or forward button changes it.
+     *
+     * Default: true when `history` is `'push'`, else false
+     */
+    popstate?: boolean | undefined;
+    /**
+     * Optional handler for operation failures: an operation called before the
+     * grid is ready (`NOT_READY`), a grid API error (`GRID_ERROR`), a saved view
+     * that is not found or cannot be stored (`VIEW_*`, `STORAGE_*`). `context`
+     * names the operation, for example `'apply-url-filters'`.
+     *
+     * Each failure reaches one callback only (#220). A filter that is dropped or
+     * not valid goes to `onParseError`, not here. The hook never writes to the
+     * console, so a failure with no handler is silent.
      */
-    onError?: (error: Error, context: string) => void;
+    onError?: ((error: Error, context: string) => void) | undefined;
 }
 /**
  * Return type for the useAGGridUrlSync hook
+ *
+ * @deprecated Use `useGridUrlSync` and its types. Removed in 0.6.0.
  */
 export interface UseAGGridUrlSyncReturn {
     /**
@@ -83,10 +113,22 @@ export interface UseAGGridUrlSyncReturn {
      * Comes from the grid's filter state, not from the URL, because the URL also
      * keeps the page's own params. A filter that the URL cannot carry (for
      * example a text value over `maxValueLength`) still counts, so a "clear
-     * filters" button stays enabled. The URL leaves that filter out and reports
-     * it through `onParseError`.
+     * filters" button stays enabled. The URL leaves that filter out, reports it
+     * through `onParseError`, and puts it in `issues`.
      */
     hasFilters: boolean;
+    /**
+     * The filters that were dropped (#229): the data issues of the latest URL
+     * apply (`applyUrlFilters`, `applyFilters`, auto-apply), and of the latest
+     * URL write (each filter change). Each one is a `URLSyncError` with a
+     * `code` and, when it is known, a `column`. The apply issues stay until the
+     * next apply, `clearFilters` or `loadView`.
+     *
+     * The array keeps its identity while its content does not change. Operation
+     * failures (`NOT_READY`, `GRID_ERROR`, storage) go to `onError` and are not
+     * here. With `throwOnError`, the hook throws a picked issue during render.
+     */
+    issues: readonly URLSyncError[];
     /**
      * Parse filters from a URL without applying them
      * @param url - URL to parse
@@ -105,8 +147,13 @@ export interface UseAGGridUrlSyncReturn {
      */
     getFiltersAsFormat: (format: SerializationFormat) => string;
     /**
-     * Get the current serialization format
-     * @returns The current format
+     * The serialization mode of the URL: `'individual'` or `'grouped'`
+     */
+    getSerializationMode: () => SerializationMode;
+    /**
+     * The serialization mode of the URL. The name is wrong: it returns the
+     * mode, not the format.
+     * @deprecated Use `getSerializationMode`. Removed in 0.6.0.
      */
     getCurrentFormat: () => SerializationMode;
     /**
@@ -180,3 +227,43 @@ export interface UseAGGridUrlSyncReturn {
      */
     deleteView: (id: string) => void;
 }
+/**
+ * The options of `useGridUrlSync`: the options of `createGridUrlSync`, with
+ * the grid's `api` that can be null while the grid starts, and the React
+ * options. An option can change after mount.
+ */
+export interface UseGridUrlSyncOptions extends Omit<GridUrlSyncOptions, 'api' | 'views'> {
+    /** The AG Grid API, or null while the grid starts */
+    api: GridApi | null | undefined;
+    /**
+     * Enables saved views, kept in localStorage under this key. Two grids on
+     * the same origin need two keys. With no key, `views` is empty and the
+     * view methods do nothing.
+     */
+    storageKey?: string | undefined;
+    /**
+     * With `false`, the hook makes no sync: the state is idle, and a method
+     * reports `NOT_READY`. `views` still shows what is in storage.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+}
+/**
+ * The result of `useGridUrlSync`: the sync's snapshot and its methods. The
+ * object stays the same until a snapshot value changes, and the methods
+ * never change.
+ */
+export interface UseGridUrlSyncResult extends GridUrlSyncSnapshot {
+    /** Applies the filters of a URL (default: the address bar) to the grid */
+    applyUrl: (url?: string) => ApplyResult;
+    /** Applies filters to the grid, as the app's own write */
+    applyFilters: (filters: FilterState) => ApplyResult;
+    /** The URL with the grid's filters (default base: the address bar) */
+    getUrl: (baseUrl?: string) => string;
+    /** Saves the grid's filters as a view, and makes it active */
+    saveView: (name: string) => GridView | null;
+    /** Loads a saved view. `null` clears the filters. */
+    loadView: (id: string | null) => void;
+    /** Deletes a saved view */
+    deleteView: (id: string) => void;
+}

package/dist/react/use-ag-grid-url-sync.d.ts

@@ -3,6 +3,9 @@ import type { UseAGGridUrlSyncOptions, UseAGGridUrlSyncReturn } from './types.js
 /**
  * React hook for AG Grid URL synchronization
  *
+ * @deprecated Use `useGridUrlSync({ api, ...options })` (#271). This hook
+ * will be removed in 0.6.0.
+ *
  * @param gridApi - AG Grid API instance (can be null during initialization)
  * @param options - Configuration options for the hook
  * @returns Hook API for URL synchronization