ag-grid-url-sync 0.5.1 → 0.5.2

package/dist/index.js.map

@@ -1 +1 @@
-{"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,MAAM,sBAAsB,CAAA;AAE1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGlD,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAGzE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE1E,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAEtD,cAAc,iBAAiB,CAAA;AAG/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGlD,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,4 +1,5 @@
+export { useGridUrlSync } from './use-grid-url-sync.js';
 export { useAGGridUrlSync } from './use-ag-grid-url-sync.js';
-export type { UseAGGridUrlSyncOptions, UseAGGridUrlSyncReturn } from './types.js';
+export type { UseGridUrlSyncOptions, UseGridUrlSyncResult, UseAGGridUrlSyncOptions, UseAGGridUrlSyncReturn } from './types.js';
 export type { GridView } from '../core/view-storage.js';
-export type { FilterState, ColumnFilter, FilterOperation, AGGridUrlSyncConfig, GridApi } from '../core/types.js';
+export type { FilterState, ColumnFilter, FilterOperation, AGGridUrlSyncConfig, GridApi, HistoryMode } from '../core/types.js';

package/dist/react/index.js

@@ -1,2 +1,3 @@
+export { useGridUrlSync } from './use-grid-url-sync.js';
 export { useAGGridUrlSync } from './use-ag-grid-url-sync.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA"}

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

@@ -0,0 +1,22 @@
+import type { GridUrlSync, GridUrlSyncSnapshot, URLSyncError } from '../core/types.js';
+import type { GridView } from '../core/view-storage.js';
+export interface SyncHolder {
+    /** Puts a sync in the holder (or none). Does not destroy the old one. */
+    set(sync: GridUrlSync | null): void;
+    /** The current sync, or null */
+    get(): GridUrlSync | null;
+    /**
+     * The stored views to show while there is no sync (#223). The listeners
+     * hear of it only when no sync is in the holder and the views changed.
+     */
+    setIdleViews(views: readonly GridView[]): void;
+    /**
+     * The apply issues of an earlier sync on the same grid. The snapshot of
+     * the current sync shows them before its own issues.
+     */
+    setCarriedIssues(issues: readonly URLSyncError[]): void;
+    subscribe(listener: () => void): () => void;
+    /** The current sync's snapshot, or the idle snapshot */
+    getSnapshot(): GridUrlSyncSnapshot;
+}
+export declare function createSyncHolder(): SyncHolder;

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, URLSyncError } 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 {
     /**
@@ -40,6 +43,24 @@ export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
      * Default: true
      */
     enabledWhenReady?: boolean | undefined;
+    /**
+     * 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
@@ -54,6 +75,8 @@ export interface UseAGGridUrlSyncOptions extends AGGridUrlSyncConfig {
 }
 /**
  * Return type for the useAGGridUrlSync hook
+ *
+ * @deprecated Use `useGridUrlSync` and its types. Removed in 0.6.0.
  */
 export interface UseAGGridUrlSyncReturn {
     /**
@@ -124,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;
     /**
@@ -199,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