@teleporthq/teleport-plugin-next-data-source 0.43.59 → 0.43.60

package/dist/esm/page-url-sync.d.ts

@@ -0,0 +1,42 @@
+import * as types from '@babel/types';
+/** `const <refVar> = useRef(null)` — the last `?page=` value this effect saw. */
+export declare const buildPageUrlRefDeclaration: (refVar: string) => types.VariableDeclaration;
+export interface PageUrlSyncOptions {
+    paramKey: string;
+    /** Ref holding the previously seen URL page. */
+    refVar: string;
+    /** How this usage reads its current page. */
+    currentPageExpr: () => types.Expression;
+    /** How this usage writes a page back. */
+    buildSetPageStatement: (pageExpr: types.Expression) => types.Expression;
+}
+/**
+ * Emitted shape (for `?page=`, a combined `{ page, debouncedQuery }` state):
+ *
+ *   useEffect(() => {
+ *     if (!router.isReady) return
+ *     const __urlValue = router.query.page
+ *     const __raw = typeof __urlValue === 'string' ? __urlValue
+ *       : Array.isArray(__urlValue) ? __urlValue[0] || '' : ''
+ *     const __urlPage = Math.max(1, parseInt(__raw, 10) || 1)
+ *     const __statePage = ds_0_state.page
+ *     const __seenUrlPage = ds_0_pageUrlRef.current
+ *     if (__tqQuerySyncRef.current.inFlight === 0 &&
+ *         __seenUrlPage !== __urlPage && __urlPage !== __statePage) {
+ *       ds_0_pageUrlRef.current = __urlPage
+ *       setDs_0_state(state => state.page === __urlPage ? state : { ...state, page: __urlPage })
+ *       return
+ *     }
+ *     ds_0_pageUrlRef.current = __urlPage
+ *     if (__urlPage === __statePage) return
+ *     __tqWriteQueryParam('page', __statePage <= 1 ? undefined : __statePage)
+ *   }, [router.query.page, router.isReady, ds_0_state.page])
+ *
+ * The write goes through `URLQueryWriter` rather than spreading `router.query`
+ * here. This effect and a filter's write-back fire in the SAME flush on every
+ * filter change (the reset moves the page), and two effects each merging into
+ * their own stale snapshot of `router.query` erase each other's keys — see
+ * `url-query-writer.ts` for why that then never settles.
+ */
+export declare const buildPageUrlSyncEffect: (options: PageUrlSyncOptions) => types.ExpressionStatement;
+//# sourceMappingURL=page-url-sync.d.ts.map

package/dist/esm/page-url-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-url-sync.d.ts","sourceRoot":"","sources":["../../src/page-url-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AA4DrC,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,WAAY,MAAM,KAAG,MAAM,mBAM9D,CAAA;AAEJ,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,eAAe,EAAE,MAAM,KAAK,CAAC,UAAU,CAAA;IACvC,yCAAyC;IACzC,qBAAqB,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAA;CACxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,sBAAsB,YAAa,kBAAkB,KAAG,MAAM,mBAqI1E,CAAA"}

package/dist/esm/page-url-sync.js

@@ -0,0 +1,152 @@
+import * as types from '@babel/types';
+import { URLQueryWriter } from '@teleporthq/teleport-plugin-common';
+/**
+ * Keeping the current page and the `?page=` query in step.
+ *
+ * ## Why one effect and not the read-back / write-back PAIR
+ *
+ * Every other URL-bound control (the category dropdown, the sort select, the
+ * search box) uses two independent effects from `URLSearchParamSync`, each
+ * bailing when the value it would write is already there. That works because
+ * both sides start out agreeing: the state is SEEDED from
+ * `window.location.search` in its `useState` initializer, so by the time the
+ * effects run there is nothing to reconcile.
+ *
+ * The page cannot be seeded that way, for a reason that only shows up in a
+ * browser: a statically generated page is rendered on the server with page 1,
+ * and React does NOT repair mismatched ATTRIBUTES when it hydrates — it keeps
+ * the server's DOM and warns. A client that seeded page 3 renders "Previous" as
+ * enabled, the server rendered it disabled, and the disabled one is what stays
+ * on screen. Worse, it stays for good: React's later re-renders diff against the
+ * client's own first render, which already said enabled, so nothing ever
+ * repaints it. The rows would be page 3's with no way back to page 2.
+ *
+ * Adopting the URL in an effect instead makes the page change from 1 to 3 a
+ * real state transition, which React renders normally. But a naive PAIR of
+ * effects then races: on the render where the router becomes ready, the
+ * write-back sees page 1, deletes `?page=3` from the URL, and the read-back it
+ * was supposed to cooperate with reads back the page it just erased.
+ *
+ * So one effect owns both directions and decides which side moved:
+ *
+ *   • the URL moved (a deep link, a `<Link>`, browser back/forward) ⇒ adopt it
+ *   • the page moved (a click, or the filter reset) ⇒ write it
+ *
+ * The previously seen URL value is what separates the two, so neither direction
+ * has to guess. Page 1 is written as the ABSENCE of the key, so an unpaginated
+ * visit keeps a clean URL and a filter reset takes `?page=` back off it.
+ *
+ * ⚠️ A deep-linked page 2+ therefore costs one extra fetch: the provider mounts
+ * on page 1 and refetches when this effect adopts the URL. Correctness over the
+ * round trip — the alternative leaves a control the visitor cannot use.
+ */
+// Strict JS identifier check, mirroring `URLSearchParamSync`: a key like
+// `foo-bar` has to go through bracket notation or the emitted code is a
+// subtraction.
+var VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+var accessKeyOf = function (object, paramKey) {
+    return VALID_JS_IDENTIFIER.test(paramKey)
+        ? types.memberExpression(object, types.identifier(paramKey))
+        : types.memberExpression(object, types.stringLiteral(paramKey), true);
+};
+var routerQueryAccess = function (paramKey) {
+    return accessKeyOf(types.memberExpression(types.identifier('router'), types.identifier('query')), paramKey);
+};
+/** `const <refVar> = useRef(null)` — the last `?page=` value this effect saw. */
+export var buildPageUrlRefDeclaration = function (refVar) {
+    return types.variableDeclaration('const', [
+        types.variableDeclarator(types.identifier(refVar), types.callExpression(types.identifier('useRef'), [types.nullLiteral()])),
+    ]);
+};
+/**
+ * Emitted shape (for `?page=`, a combined `{ page, debouncedQuery }` state):
+ *
+ *   useEffect(() => {
+ *     if (!router.isReady) return
+ *     const __urlValue = router.query.page
+ *     const __raw = typeof __urlValue === 'string' ? __urlValue
+ *       : Array.isArray(__urlValue) ? __urlValue[0] || '' : ''
+ *     const __urlPage = Math.max(1, parseInt(__raw, 10) || 1)
+ *     const __statePage = ds_0_state.page
+ *     const __seenUrlPage = ds_0_pageUrlRef.current
+ *     if (__tqQuerySyncRef.current.inFlight === 0 &&
+ *         __seenUrlPage !== __urlPage && __urlPage !== __statePage) {
+ *       ds_0_pageUrlRef.current = __urlPage
+ *       setDs_0_state(state => state.page === __urlPage ? state : { ...state, page: __urlPage })
+ *       return
+ *     }
+ *     ds_0_pageUrlRef.current = __urlPage
+ *     if (__urlPage === __statePage) return
+ *     __tqWriteQueryParam('page', __statePage <= 1 ? undefined : __statePage)
+ *   }, [router.query.page, router.isReady, ds_0_state.page])
+ *
+ * The write goes through `URLQueryWriter` rather than spreading `router.query`
+ * here. This effect and a filter's write-back fire in the SAME flush on every
+ * filter change (the reset moves the page), and two effects each merging into
+ * their own stale snapshot of `router.query` erase each other's keys — see
+ * `url-query-writer.ts` for why that then never settles.
+ */
+export var buildPageUrlSyncEffect = function (options) {
+    var refCurrent = function () {
+        return types.memberExpression(types.identifier(options.refVar), types.identifier('current'));
+    };
+    var rememberUrlPage = function () {
+        return types.expressionStatement(types.assignmentExpression('=', refCurrent(), types.identifier('__urlPage')));
+    };
+    var effectBody = types.blockStatement([
+        types.ifStatement(types.unaryExpression('!', types.memberExpression(types.identifier('router'), types.identifier('isReady'))), types.returnStatement(null)),
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(options.paramKey)),
+        ]),
+        // `router.query[key]` is `string | string[] | undefined` in Next's typings.
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__raw'), types.conditionalExpression(types.binaryExpression('===', types.unaryExpression('typeof', types.identifier('__urlValue')), types.stringLiteral('string')), types.identifier('__urlValue'), types.conditionalExpression(types.callExpression(types.memberExpression(types.identifier('Array'), types.identifier('isArray')), [types.identifier('__urlValue')]), types.logicalExpression('||', types.memberExpression(types.identifier('__urlValue'), types.numericLiteral(0), true), types.stringLiteral('')), types.stringLiteral('')))),
+        ]),
+        // A missing, unparseable or out-of-range param all mean page 1 — which is
+        // also the value written as no key at all, so the two sides agree.
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__urlPage'), types.callExpression(types.memberExpression(types.identifier('Math'), types.identifier('max')), [
+                types.numericLiteral(1),
+                types.logicalExpression('||', types.callExpression(types.identifier('parseInt'), [
+                    types.identifier('__raw'),
+                    types.numericLiteral(10),
+                ]), types.numericLiteral(1)),
+            ])),
+        ]),
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__statePage'), options.currentPageExpr()),
+        ]),
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__seenUrlPage'), refCurrent()),
+        ]),
+        // The URL is the side that moved: a deep link (nothing seen yet), a
+        // same-path navigation, or browser back/forward.
+        types.ifStatement(types.logicalExpression('&&', 
+        // ⛔ Only when nothing this component asked for is still landing.
+        // Mid-flight, `router.query` holds a page the visitor is on their way
+        // OUT of (the filter reset writes page 1 while `?page=5` is still in the
+        // bar), and adopting it would put them straight back on it.
+        URLQueryWriter.buildQuerySettledExpr(), types.logicalExpression('&&', types.binaryExpression('!==', types.identifier('__seenUrlPage'), types.identifier('__urlPage')), types.binaryExpression('!==', types.identifier('__urlPage'), types.identifier('__statePage')))), types.blockStatement([
+            rememberUrlPage(),
+            types.expressionStatement(options.buildSetPageStatement(types.identifier('__urlPage'))),
+            types.returnStatement(null),
+        ])),
+        rememberUrlPage(),
+        types.ifStatement(types.binaryExpression('===', types.identifier('__urlPage'), types.identifier('__statePage')), types.returnStatement(null)),
+        // The page is the side that moved: a control click, or the filter reset.
+        // The write goes through the shared query writer so it merges into the last
+        // query this component asked for — the filter's own write-back may still be
+        // in flight in this very flush. Page 1 is written as the ABSENCE of the key,
+        // which the writer expresses as `undefined`.
+        URLQueryWriter.buildQueryWriteCall(options.paramKey, types.conditionalExpression(types.binaryExpression('<=', types.identifier('__statePage'), types.numericLiteral(1)), types.identifier('undefined'), types.identifier('__statePage'))),
+    ]);
+    return types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
+        types.arrowFunctionExpression([], effectBody),
+        types.arrayExpression([
+            routerQueryAccess(options.paramKey),
+            types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+            options.currentPageExpr(),
+        ]),
+    ]));
+};
+//# sourceMappingURL=page-url-sync.js.map

package/dist/esm/page-url-sync.js.map

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

package/dist/esm/pagination-controls.d.ts

@@ -0,0 +1,55 @@
+import * as types from '@babel/types';
+/**
+ * How the generator recognises the pagination controls the builder authored.
+ *
+ * The marker is a STATIC UIDL attribute, which survives the resolver, the JSX
+ * printer and the browser verbatim — unlike `elementType`, which the resolver
+ * replaces with the node's `semanticType`, and unlike the class name, which is
+ * a side effect of the styling pipeline (`ThqPreviousElm` →
+ * `products-list-thq-previous-elm`) and so silently renames whenever a node is
+ * renamed. The same attribute is readable from the DOM, which is how the
+ * pagination-scroll runtime already identifies its own nodes.
+ */
+export declare const PAGINATION_CONTROL_ATTR = "data-tq-pagination-control";
+/**
+ * `'pages'` is the container the page-number buttons are repeated into and
+ * `'page'` the single template button inside it. `'ellipsis'` and `'sentinel'`
+ * are reserved for an authored gap marker / scroll sentinel; until a builder
+ * emits them both runtimes fall back to generating their own.
+ */
+export type PaginationControlKind = 'first' | 'previous' | 'pages' | 'page' | 'ellipsis' | 'next' | 'last' | 'load-more' | 'sentinel';
+export declare function readJSXAttributeString(node: any, attrName: string): string;
+/**
+ * Depth-first search for one authored pagination control.
+ *
+ * `legacyClassName` keeps every project generated before the marker existed
+ * working: its Previous/Next buttons carry no attribute, so the search falls
+ * back to the class-name substring the generator has always matched on. New
+ * control kinds have no legacy spelling and are marker-only.
+ */
+export declare function findPaginationControl(root: any, kind: PaginationControlKind, legacyClassName?: string): any;
+/** Every authored control of one kind, in document order (page-number templates aside, callers want one). */
+export declare function findAllPaginationControls(root: any, kind: PaginationControlKind): any[];
+/**
+ * Turns an authored control into a real `<button type="button">`.
+ *
+ * The builders author these as styled containers (a `div` after the resolver),
+ * so without this a keyboard user could never reach them and a click would not
+ * register as a form-safe activation. An author-supplied `type` is respected.
+ */
+export declare function convertControlToButton(node: any): void;
+/** Replaces (never duplicates) one JSX attribute, appending it last. */
+export declare function setJSXExpressionAttribute(node: any, attrName: string, expression: types.Expression): void;
+/** Drops one JSX attribute if present. */
+export declare function removeJSXAttribute(node: any, attrName: string): void;
+/**
+ * Removes the controls that belong to a pagination mode this mapper is not in —
+ * a numbered strip left in a Previous/Next list would render unwired buttons
+ * that look clickable and do nothing.
+ *
+ * Children carrying NO marker are always kept: they are the author's own
+ * additions (a page counter, a spacer) and the generator has no business
+ * deciding whether they belong.
+ */
+export declare function dropInactivePaginationControls(paginationNode: any, activeKinds: PaginationControlKind[]): void;
+//# sourceMappingURL=pagination-controls.d.ts.map

package/dist/esm/pagination-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination-controls.d.ts","sourceRoot":"","sources":["../../src/pagination-controls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,+BAA+B,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,UAAU,GACV,OAAO,GACP,MAAM,GACN,UAAU,GACV,MAAM,GACN,MAAM,GACN,WAAW,GACX,UAAU,CAAA;AAOd,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,qBAAqB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,GAAG,CA2BL;AAED,6GAA6G;AAC7G,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,qBAAqB,GAAG,GAAG,EAAE,CAkBvF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAWtD;AAED,wEAAwE;AACxE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,GAAG,EACT,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,KAAK,CAAC,UAAU,GAC3B,IAAI,CAON;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,GAAG,EACnB,WAAW,EAAE,qBAAqB,EAAE,GACnC,IAAI,CAgBN"}

package/dist/esm/pagination-controls.js

@@ -0,0 +1,126 @@
+import * as types from '@babel/types';
+/**
+ * How the generator recognises the pagination controls the builder authored.
+ *
+ * The marker is a STATIC UIDL attribute, which survives the resolver, the JSX
+ * printer and the browser verbatim — unlike `elementType`, which the resolver
+ * replaces with the node's `semanticType`, and unlike the class name, which is
+ * a side effect of the styling pipeline (`ThqPreviousElm` →
+ * `products-list-thq-previous-elm`) and so silently renames whenever a node is
+ * renamed. The same attribute is readable from the DOM, which is how the
+ * pagination-scroll runtime already identifies its own nodes.
+ */
+export var PAGINATION_CONTROL_ATTR = 'data-tq-pagination-control';
+// tslint:disable:no-any
+// Reads a JSX attribute's literal string value, covering both the plain
+// `attr="value"` form and the `attr={'value'}` container the UIDL printer emits
+// for some static attributes.
+export function readJSXAttributeString(node, attrName) {
+    var _a, _b, _c, _d, _e;
+    var attr = (_b = (_a = node === null || node === void 0 ? void 0 : node.openingElement) === null || _a === void 0 ? void 0 : _a.attributes) === null || _b === void 0 ? void 0 : _b.find(function (candidate) { var _a; return candidate.type === 'JSXAttribute' && ((_a = candidate.name) === null || _a === void 0 ? void 0 : _a.name) === attrName; });
+    return ((_c = attr === null || attr === void 0 ? void 0 : attr.value) === null || _c === void 0 ? void 0 : _c.value) || ((_e = (_d = attr === null || attr === void 0 ? void 0 : attr.value) === null || _d === void 0 ? void 0 : _d.expression) === null || _e === void 0 ? void 0 : _e.value) || '';
+}
+/**
+ * Depth-first search for one authored pagination control.
+ *
+ * `legacyClassName` keeps every project generated before the marker existed
+ * working: its Previous/Next buttons carry no attribute, so the search falls
+ * back to the class-name substring the generator has always matched on. New
+ * control kinds have no legacy spelling and are marker-only.
+ */
+export function findPaginationControl(root, kind, legacyClassName) {
+    var search = function (node, matches) {
+        if (!node) {
+            return null;
+        }
+        if (node.type === 'JSXElement' && matches(node)) {
+            return node;
+        }
+        if (Array.isArray(node.children)) {
+            for (var _i = 0, _a = node.children; _i < _a.length; _i++) {
+                var child = _a[_i];
+                var found = search(child, matches);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    };
+    var byMarker = search(root, function (node) { return readJSXAttributeString(node, PAGINATION_CONTROL_ATTR) === kind; });
+    if (byMarker || !legacyClassName) {
+        return byMarker;
+    }
+    return search(root, function (node) { return readJSXAttributeString(node, 'className').includes(legacyClassName); });
+}
+/** Every authored control of one kind, in document order (page-number templates aside, callers want one). */
+export function findAllPaginationControls(root, kind) {
+    var found = [];
+    var traverse = function (node) {
+        if (!node) {
+            return;
+        }
+        if (node.type === 'JSXElement' &&
+            readJSXAttributeString(node, PAGINATION_CONTROL_ATTR) === kind) {
+            found.push(node);
+        }
+        if (Array.isArray(node.children)) {
+            node.children.forEach(traverse);
+        }
+    };
+    traverse(root);
+    return found;
+}
+/**
+ * Turns an authored control into a real `<button type="button">`.
+ *
+ * The builders author these as styled containers (a `div` after the resolver),
+ * so without this a keyboard user could never reach them and a click would not
+ * register as a form-safe activation. An author-supplied `type` is respected.
+ */
+export function convertControlToButton(node) {
+    node.openingElement.name.name = 'button';
+    if (node.closingElement) {
+        node.closingElement.name.name = 'button';
+    }
+    var hasType = node.openingElement.attributes.some(function (attr) { var _a; return ((_a = attr.name) === null || _a === void 0 ? void 0 : _a.name) === 'type'; });
+    if (!hasType) {
+        node.openingElement.attributes.push(types.jsxAttribute(types.jsxIdentifier('type'), types.stringLiteral('button')));
+    }
+}
+/** Replaces (never duplicates) one JSX attribute, appending it last. */
+export function setJSXExpressionAttribute(node, attrName, expression) {
+    node.openingElement.attributes = node.openingElement.attributes.filter(function (attr) { var _a; return ((_a = attr.name) === null || _a === void 0 ? void 0 : _a.name) !== attrName; });
+    node.openingElement.attributes.push(types.jsxAttribute(types.jsxIdentifier(attrName), types.jsxExpressionContainer(expression)));
+}
+/** Drops one JSX attribute if present. */
+export function removeJSXAttribute(node, attrName) {
+    node.openingElement.attributes = node.openingElement.attributes.filter(function (attr) { var _a; return ((_a = attr.name) === null || _a === void 0 ? void 0 : _a.name) !== attrName; });
+}
+/**
+ * Removes the controls that belong to a pagination mode this mapper is not in —
+ * a numbered strip left in a Previous/Next list would render unwired buttons
+ * that look clickable and do nothing.
+ *
+ * Children carrying NO marker are always kept: they are the author's own
+ * additions (a page counter, a spacer) and the generator has no business
+ * deciding whether they belong.
+ */
+export function dropInactivePaginationControls(paginationNode, activeKinds) {
+    var active = new Set(activeKinds);
+    var prune = function (node) {
+        if (!node || !Array.isArray(node.children)) {
+            return;
+        }
+        node.children = node.children.filter(function (child) {
+            if ((child === null || child === void 0 ? void 0 : child.type) !== 'JSXElement') {
+                return true;
+            }
+            var marker = readJSXAttributeString(child, PAGINATION_CONTROL_ATTR);
+            return marker === '' || active.has(marker);
+        });
+        node.children.forEach(prune);
+    };
+    prune(paginationNode);
+}
+//# sourceMappingURL=pagination-controls.js.map

package/dist/esm/pagination-controls.js.map

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

package/dist/esm/pagination-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination-plugin.d.ts","sourceRoot":"","sources":["../../src/pagination-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EAGvB,MAAM,4BAA4B,CAAA;AAivBnC,eAAO,MAAM,qCAAqC,EAAE,sBAAsB,CAAC,EAAE,CAi6B5E,CAAA"}
+{"version":3,"file":"pagination-plugin.d.ts","sourceRoot":"","sources":["../../src/pagination-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EAGvB,MAAM,4BAA4B,CAAA;AA+iCnC,eAAO,MAAM,qCAAqC,EAAE,sBAAsB,CAAC,EAAE,CA40B5E,CAAA"}