@teleporthq/teleport-plugin-next-data-source 0.43.21 → 0.43.22

package/__tests__/search-url-sync.test.ts

@@ -0,0 +1,120 @@
+import * as types from '@babel/types'
+import generator from '@babel/generator'
+import {
+  ChunkType,
+  FileType,
+  ComponentStructure,
+  ChunkDefinition,
+} from '@teleporthq/teleport-types'
+import { createNextArrayMapperPaginationPlugin } from '../src/pagination-plugin'
+
+// A `const TestComponent = (props) => { return <div/> }` shell. The pagination
+// plugin prepends the search/pagination state hooks and splices the URL-sync
+// effects before the return, so a minimal body is enough to observe them — the
+// effects are derived from the UIDL registry, not from the JSX wiring.
+const makeComponentChunk = (): ChunkDefinition => {
+  const body = types.blockStatement([
+    types.returnStatement(
+      types.jsxElement(
+        types.jsxOpeningElement(types.jsxIdentifier('div'), [], true),
+        null,
+        [],
+        true
+      )
+    ),
+  ])
+  const arrow = types.arrowFunctionExpression([types.identifier('props')], body)
+  const declaration = types.variableDeclaration('const', [
+    types.variableDeclarator(types.identifier('TestComponent'), arrow),
+  ])
+  return {
+    name: 'jsx-component',
+    type: ChunkType.AST,
+    fileType: FileType.JS,
+    linkAfter: [],
+    content: declaration,
+    meta: {},
+  }
+}
+
+// A `data-source-list > cms-list-repeater` UIDL: a paginated + search-enabled
+// products list, optionally bound to a URL search-param key.
+// tslint:disable-next-line:no-any
+const makeUidlNode = (searchUrlParamKey?: string): any => ({
+  type: 'data-source-list',
+  content: {
+    renderPropIdentifier: 'items',
+    resourceDefinition: {
+      dataSourceId: 'ds1',
+      tableName: 'products',
+      dataSourceType: 'postgresql',
+    },
+    resource: { params: { queryColumns: { content: ['name'] } } },
+    nodes: {
+      success: {
+        type: 'cms-list-repeater',
+        content: {
+          renderPropIdentifier: 'product',
+          paginated: true,
+          perPage: 20,
+          searchEnabled: true,
+          searchDebounce: 300,
+          ...(searchUrlParamKey ? { searchUrlParamKey } : {}),
+          nodes: { list: { type: 'element', content: { elementType: 'div' } } },
+        },
+      },
+    },
+  },
+})
+
+const runPlugin = async (searchUrlParamKey?: string): Promise<string> => {
+  const chunk = makeComponentChunk()
+  const structure: ComponentStructure = {
+    uidl: { name: 'TestComponent', node: makeUidlNode(searchUrlParamKey) },
+    chunks: [chunk],
+    dependencies: {},
+    options: { dataSources: {}, extractedResources: {} },
+  } as never
+  const plugin = createNextArrayMapperPaginationPlugin()
+  await plugin(structure)
+  return generator(chunk.content as types.Node).code
+}
+
+describe('pagination plugin — search input URL two-way sync (searchUrlParamKey)', () => {
+  it('seeds the query from window.location.search and emits paired read-back/write-back effects', async () => {
+    const code = await runPlugin('searchKeyword')
+
+    // Initial value seeded from the URL on the client (both the immediate input
+    // state AND the debounced value, so a deep link fetches filtered on mount).
+    const seedMatches = code.match(
+      /new URLSearchParams\(window\.location\.search\)\.get\("searchKeyword"\)/g
+    )
+    expect(seedMatches).not.toBeNull()
+    expect((seedMatches || []).length).toBe(2)
+    expect(code).toContain('typeof window !== "undefined"')
+
+    // useRouter is injected for the effects.
+    expect(code).toContain('const router = useRouter()')
+
+    // Write-back (debounced query → URL), keyed on the DEBOUNCED value.
+    expect(code).toContain('__nextQuery.searchKeyword = String(ds_0_state.debouncedQuery)')
+    expect(code).toContain('if (__nextQuery.searchKeyword === router.query.searchKeyword) return')
+    expect(code).toContain('}, [ds_0_state.debouncedQuery, router.isReady])')
+
+    // Read-back (URL → input), functional setState bail-out (loop-free).
+    expect(code).toContain('const __urlValue = router.query.searchKeyword')
+    expect(code).toContain('setDs_0_searchQuery(prev => prev === __nextValue ? prev : __nextValue)')
+    expect(code).toContain('}, [router.query.searchKeyword, router.isReady])')
+  })
+
+  it('does NOT emit any URL sync when the repeater has no searchUrlParamKey (unchanged behaviour)', async () => {
+    const code = await runPlugin(undefined)
+
+    // Search still works locally (state + debounce), but nothing touches the URL.
+    expect(code).toContain('ds_0_searchQuery')
+    expect(code).not.toContain('searchKeyword')
+    expect(code).not.toContain('window.location.search')
+    expect(code).not.toContain('router.replace')
+    expect(code).not.toContain('useRouter')
+  })
+})

package/dist/cjs/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;AAulBnC,eAAO,MAAM,qCAAqC,EAAE,sBAAsB,CAAC,EAAE,CAi3B5E,CAAA"}
+{"version":3,"file":"pagination-plugin.d.ts","sourceRoot":"","sources":["../../src/pagination-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,sBAAsB,EAGvB,MAAM,4BAA4B,CAAA;AA4tBnC,eAAO,MAAM,qCAAqC,EAAE,sBAAsB,CAAC,EAAE,CA63B5E,CAAA"}

package/dist/cjs/pagination-plugin.js

@@ -105,6 +105,31 @@ function searchDefaultValueInitAST(value) {
     // independent AST node — Babel does not support shared references.
     return types.cloneNode(value.ast, /* deep */ true);
 }
+// Builds the `useState(...)` initializer for the search query. When the
+// cms-list-repeater is bound to a URL param (`searchUrlParamKey`), the query is
+// seeded from `window.location.search` on the client so a deep link such as
+// `/products-list?searchKeyword=yoga` arrives pre-filtered on the very first
+// paint; the server render (where `window` is undefined) and any missing param
+// fall back to the `searchDefaultValue` seed (empty string by default). This
+// mirrors the `selectedCategory` / `sortBy` initializer emitted by
+// `createStateHookAST` for state-level `urlSearchParamBinding`, keeping the
+// three products-list controls consistent.
+//
+// Returns a fresh AST on every call (no shared node references) so the same
+// initializer can seed both the immediate `ds_N_searchQuery` state and the
+// debounced `ds_N_state.debouncedQuery` value.
+function buildSearchQueryInitAST(usage) {
+    var fallback = searchDefaultValueInitAST(usage.searchDefaultValue);
+    if (!usage.searchUrlParamKey) {
+        return fallback;
+    }
+    // (typeof window !== 'undefined'
+    //   ? new URLSearchParams(window.location.search).get('<key>')
+    //   : null) ?? <fallback>
+    return types.logicalExpression('??', types.conditionalExpression(types.binaryExpression('!==', types.unaryExpression('typeof', types.identifier('window')), types.stringLiteral('undefined')), types.callExpression(types.memberExpression(types.newExpression(types.identifier('URLSearchParams'), [
+        types.memberExpression(types.memberExpression(types.identifier('window'), types.identifier('location')), types.identifier('search')),
+    ]), types.identifier('get')), [types.stringLiteral(usage.searchUrlParamKey)]), types.nullLiteral()), fallback);
+}
 // The UIDL's `filters.content` array can wrap one or more conditions inside
 // a `{ type: 'group', operator: 'and' | 'or', children: [...] }` entry — the
 // GUI builds this shape when the inspector adds a logical group. The data
@@ -390,6 +415,13 @@ function buildStateRegistry(uidlNode) {
                 // For plain mappers, use limit from data-source-list resource params
                 var effectivePerPage = content.paginated ? content.perPage : limit || content.perPage;
                 var searchDefaultValue = parseSearchDefaultValue(content.searchDefaultValue);
+                // URL two-way binding key for the search input. Only honoured when it
+                // is a non-empty string; blank / non-string values fall back to the
+                // plain (non-URL-synced) search behaviour.
+                var searchUrlParamKey = typeof content.searchUrlParamKey === 'string' &&
+                    content.searchUrlParamKey.trim().length > 0
+                    ? content.searchUrlParamKey.trim()
+                    : undefined;
                 var usage = {
                     index: index++,
                     dataSourceIdentifier: parentDataSource.identifier,
@@ -404,6 +436,7 @@ function buildStateRegistry(uidlNode) {
                     searchEnabled: !!content.searchEnabled,
                     searchDebounce: content.searchDebounce || 300,
                     searchDefaultValue: searchDefaultValue,
+                    searchUrlParamKey: searchUrlParamKey,
                     queryColumns: queryColumns,
                     sorts: sorts,
                     dynamicSort: dynamicSort,
@@ -493,6 +526,55 @@ function getStateVarsForUsage(usage) {
         propsPrefix: "".concat(usage.dataSourceIdentifier, "_ds_").concat(idx),
     };
 }
+// True when a usage actually emits the search ⇄ URL sync effects: it must carry
+// a non-empty `searchUrlParamKey` AND own a search query state (only the
+// `paginated+search` and `search-only` categories declare `ds_N_searchQuery`).
+// Single source of truth for both the effect emission and the `useRouter`
+// injection, so a `searchUrlParamKey` mistakenly set on a non-search mapper
+// never injects an unused `const router = useRouter()`.
+function usageHasSearchUrlSync(usage) {
+    return (!!usage.searchUrlParamKey &&
+        (usage.category === 'paginated+search' || usage.category === 'search-only'));
+}
+// Emits the two URL-sync effects for a search input bound to a URL param
+// (`searchUrlParamKey`), reusing the shared `URLSearchParamSync` builders so the
+// search input behaves exactly like the `selectedCategory` / `sortBy` dropdowns:
+//
+//   • read-back  (URL → input): browser back/forward, shallow `router.push`,
+//     and deep links flow into the immediate `ds_N_searchQuery` input state;
+//     the existing debounce effect then carries the change into the debounced
+//     value and the data fetch.
+//   • write-back (debounced → URL): the DEBOUNCED query is pushed onto the URL
+//     so it survives reloads and is shareable. Keying on the debounced value
+//     (not the raw input) means the URL updates only after the user stops
+//     typing — never on every keystroke — honouring the "search runs after a
+//     debounce" contract and avoiding a flood of `router.replace` history
+//     churn.
+//
+// Loop-free: the write-back skips when the URL already equals the value, and the
+// read-back uses functional `setState(prev => prev === next ? prev : next)`, so
+// a user edit fires write-back once and the echoed read-back bails without a
+// re-render. No-op unless the usage actually has a search query state
+// (paginated+search or search-only) AND a non-empty `searchUrlParamKey`.
+function pushSearchUrlSyncEffects(effectStatements, usage, vars) {
+    if (!usageHasSearchUrlSync(usage)) {
+        return;
+    }
+    // The canonical (debounced) query the URL should reflect. For
+    // paginated+search it lives on the combined state object as
+    // `ds_N_state.debouncedQuery`; for search-only it is the standalone
+    // `ds_N_debouncedQuery` state.
+    var buildDebouncedValueExpr = function () {
+        return usage.category === 'paginated+search'
+            ? types.memberExpression(types.identifier(vars.combinedStateVar), types.identifier('debouncedQuery'))
+            : types.identifier(vars.debouncedSearchQueryVar);
+    };
+    // write-back: debounced query → `?<searchUrlParamKey>=`
+    effectStatements.push(teleport_plugin_common_1.URLSearchParamSync.buildUrlWriteBackEffect(usage.searchUrlParamKey, buildDebouncedValueExpr(), buildDebouncedValueExpr()));
+    // read-back: `?<searchUrlParamKey>=` → input (`setDs_N_searchQuery`). The
+    // debounce effect propagates the change into the debounced value + fetch.
+    effectStatements.push(teleport_plugin_common_1.URLSearchParamSync.buildUrlReadBackEffect(usage.searchUrlParamKey, vars.setSearchQueryVar));
+}
 // ==================== MAIN PLUGIN ====================
 var createNextArrayMapperPaginationPlugin = function () {
     var paginationPlugin = function (structure) { return __awaiter(void 0, void 0, void 0, function () {
@@ -608,19 +690,22 @@ var createNextArrayMapperPaginationPlugin = function () {
                         ]), types.callExpression(types.identifier('useState'), [
                             types.objectExpression([
                                 types.objectProperty(types.identifier('page'), types.numericLiteral(1)),
-                                types.objectProperty(types.identifier('debouncedQuery'), searchDefaultValueInitAST(usage.searchDefaultValue)),
+                                types.objectProperty(types.identifier('debouncedQuery'), buildSearchQueryInitAST(usage)),
                             ]),
                         ])),
                     ]));
-                    // Immediate search query state — seeded with `searchDefaultValue`
-                    // when provided so the input is pre-filled on mount.
+                    // Immediate search query state — seeded with `searchDefaultValue` (or
+                    // the `searchUrlParamKey` URL value when bound) so the input is
+                    // pre-filled on mount. The debounced value above is seeded identically
+                    // so a deep-linked `?searchKeyword=` fetches filtered results on the
+                    // first paint: the paginated+search `initialData` is gated on
+                    // `!ds_N_state.debouncedQuery`, so a non-empty seed forces the
+                    // DataProvider to fetch instead of reusing the unfiltered SSG prefetch.
                     stateDeclarations.push(types.variableDeclaration('const', [
                         types.variableDeclarator(types.arrayPattern([
                             types.identifier(vars.searchQueryVar),
                             types.identifier(vars.setSearchQueryVar),
-                        ]), types.callExpression(types.identifier('useState'), [
-                            searchDefaultValueInitAST(usage.searchDefaultValue),
-                        ])),
+                        ]), types.callExpression(types.identifier('useState'), [buildSearchQueryInitAST(usage)])),
                     ]));
                     // Debounce effect
                     effectStatements.push(types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
@@ -722,6 +807,8 @@ var createNextArrayMapperPaginationPlugin = function () {
                         types.arrowFunctionExpression([], types.blockStatement(countFetchEffectBody)),
                         types.arrayExpression(countEffectDeps),
                     ])));
+                    // Two-way URL sync for the search input when bound to a URL param.
+                    pushSearchUrlSyncEffects(effectStatements, usage, vars);
                 }
                 else if (usage.category === 'paginated-only') {
                     // Simple page state
@@ -786,17 +873,13 @@ var createNextArrayMapperPaginationPlugin = function () {
                         types.variableDeclarator(types.arrayPattern([
                             types.identifier(vars.debouncedSearchQueryVar),
                             types.identifier(vars.setDebouncedSearchQueryVar),
-                        ]), types.callExpression(types.identifier('useState'), [
-                            searchDefaultValueInitAST(usage.searchDefaultValue),
-                        ])),
+                        ]), types.callExpression(types.identifier('useState'), [buildSearchQueryInitAST(usage)])),
                     ]));
                     stateDeclarations.push(types.variableDeclaration('const', [
                         types.variableDeclarator(types.arrayPattern([
                             types.identifier(vars.searchQueryVar),
                             types.identifier(vars.setSearchQueryVar),
-                        ]), types.callExpression(types.identifier('useState'), [
-                            searchDefaultValueInitAST(usage.searchDefaultValue),
-                        ])),
+                        ]), types.callExpression(types.identifier('useState'), [buildSearchQueryInitAST(usage)])),
                     ]));
                     // Debounce effect
                     effectStatements.push(types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
@@ -819,11 +902,13 @@ var createNextArrayMapperPaginationPlugin = function () {
                         ])),
                         types.arrayExpression([types.identifier(vars.searchQueryVar)]),
                     ])));
+                    // Two-way URL sync for the search input when bound to a URL param.
+                    pushSearchUrlSyncEffects(effectStatements, usage, vars);
                 }
             });
             // Insert state declarations at the beginning
             stateDeclarations.reverse().forEach(function (s) { return blockStatement.body.unshift(s); });
-            needsUseRouter = registry.usages.some(function (u) { return hasUrlSearchParamFilters(u); });
+            needsUseRouter = registry.usages.some(function (u) { return hasUrlSearchParamFilters(u) || usageHasSearchUrlSync(u); });
             if (needsUseRouter) {
                 if (!dependencies.useRouter) {
                     // Match the shape the sibling Next.js plugins use (i18n locale mapper,