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

package/__tests__/ecommerce-product-model.test.ts

@@ -0,0 +1,179 @@
+import { generateEcommerceProductTransformationCode } from '../src/transformations/ecommerce-product'
+import { generateSharedTransformationCode } from '../src/transformations/shared-utils'
+
+// A product's optional 3D model. The transform must hand the storefront
+// resolved URLs, STRING gates ('true' / 'false' — the builders compare with
+// `=`/`!=`, so an absent field reads as the IMAGE branch), and the gallery as
+// media entries in display order. MUST stay in sync with the renderer mirror
+// (packages/renderer/src/utils/ecommerce-products.ts) and the GUI's
+// `PRODUCT_PROP_DEFAULT` — see the GUI-side specs.
+
+type Product = Record<string, unknown> & {
+  galleryMedia: Array<{ kind: string; src: string; poster: string; thumbnail: string; alt: string }>
+  galleryThumbnails: Array<{ kind: string; src: string }>
+}
+
+const evalBuildProduct = (): ((record: unknown, options?: unknown) => Product) => {
+  const code =
+    generateSharedTransformationCode() + '\n' + generateEcommerceProductTransformationCode()
+  const fn = new Function(code + '\nreturn buildEcommerceProduct;')
+  return fn() as (record: unknown, options?: unknown) => Product
+}
+
+const ASSET_MAP = {
+  TQ_model: { remoteSrc: 'https://storage.example.com/p/model.glb' },
+  TQ_poster: { remoteSrc: 'https://cdn.example.com/poster.png' },
+  TQ_img1: { remoteSrc: 'https://cdn.example.com/img1.jpg' },
+  TQ_img2: { remoteSrc: 'https://cdn.example.com/img2.jpg' },
+}
+
+const baseRecord = {
+  id: 'p1',
+  name: 'Chair',
+  slug: 'chair',
+  price: '10',
+  currency: 'USD',
+  image_url: 'TQ_img1',
+  gallery_images: JSON.stringify(['TQ_img2']),
+}
+
+describe('ecommerce product transform — 3D model', () => {
+  const buildEcommerceProduct = evalBuildProduct()
+  const build = (record: Record<string, unknown>) =>
+    buildEcommerceProduct(record, { assetMap: ASSET_MAP })
+
+  it('emits the image branch for a product without a model', () => {
+    const product = build(baseRecord)
+    expect(product.modelUrl).toBeNull()
+    expect(product.modelPoster).toBeNull()
+    expect(product.hasModel).toBe('false')
+    expect(product.showModel).toBe('false')
+    expect(product.galleryMedia.map((m) => m.kind)).toEqual(['image', 'image'])
+    expect(product.galleryThumbnails.map((m) => m.src)).toEqual([ASSET_MAP.TQ_img2.remoteSrc])
+  })
+
+  it('resolves the model and poster asset ids to URLs and shows the model by default', () => {
+    const product = build({ ...baseRecord, model_url: 'TQ_model', model_poster_url: 'TQ_poster' })
+    expect(product.modelUrl).toBe(ASSET_MAP.TQ_model.remoteSrc)
+    expect(product.modelPoster).toBe(ASSET_MAP.TQ_poster.remoteSrc)
+    expect(product.hasModel).toBe('true')
+    // NULL / absent flag = ON
+    expect(product.showModel).toBe('true')
+    // hero first, then the images
+    expect(product.galleryMedia.map((m) => m.kind)).toEqual(['model', 'image', 'image'])
+    expect(product.galleryMedia[0]).toEqual({
+      kind: 'model',
+      src: ASSET_MAP.TQ_model.remoteSrc,
+      poster: ASSET_MAP.TQ_poster.remoteSrc,
+      thumbnail: ASSET_MAP.TQ_poster.remoteSrc,
+      alt: 'Chair',
+    })
+    // the main image moves into the strip when the model is the hero
+    expect(product.galleryThumbnails.map((m) => m.src)).toEqual([
+      ASSET_MAP.TQ_img1.remoteSrc,
+      ASSET_MAP.TQ_img2.remoteSrc,
+    ])
+  })
+
+  it('keeps the image hero when the merchant switched the model off, with the model last', () => {
+    const product = build({
+      ...baseRecord,
+      model_url: 'TQ_model',
+      model_poster_url: 'TQ_poster',
+      show_model_by_default: false,
+    })
+    expect(product.hasModel).toBe('true')
+    expect(product.showModel).toBe('false')
+    expect(product.galleryMedia.map((m) => m.kind)).toEqual(['image', 'image', 'model'])
+    expect(product.galleryThumbnails.map((m) => m.kind)).toEqual(['image', 'model'])
+    expect(product.galleryThumbnails[1].src).toBe(ASSET_MAP.TQ_model.remoteSrc)
+  })
+
+  it.each([
+    [true, 'true'],
+    [false, 'false'],
+    [1, 'true'],
+    [0, 'false'],
+    ['true', 'true'],
+    ['false', 'false'],
+    ['t', 'true'],
+    ['f', 'false'],
+    ['1', 'true'],
+    ['0', 'false'],
+    [null, 'true'],
+    [undefined, 'true'],
+    ['', 'true'],
+  ])('normalizes show_model_by_default = %p to showModel %s', (raw, expected) => {
+    const product = build({ ...baseRecord, model_url: 'TQ_model', show_model_by_default: raw })
+    expect(product.showModel).toBe(expected)
+  })
+
+  it('always shows the model when it is the only media, whatever the flag says', () => {
+    const product = build({
+      id: 'p2',
+      name: 'Lamp',
+      slug: 'lamp',
+      price: '5',
+      currency: 'USD',
+      model_url: 'TQ_model',
+      show_model_by_default: false,
+    })
+    expect(product.showModel).toBe('true')
+    expect(product.galleryMedia).toHaveLength(1)
+    expect(product.galleryThumbnails).toEqual([])
+    // nothing to poster with — the viewer paints its transparent poster
+    expect(product.modelPoster).toBeNull()
+  })
+
+  it('falls back to the main image as poster and thumbnail when the model has none', () => {
+    const product = build({ ...baseRecord, model_url: 'TQ_model', show_model_by_default: false })
+    expect(product.modelPoster).toBe(ASSET_MAP.TQ_img1.remoteSrc)
+    const modelEntry = product.galleryMedia.find((m) => m.kind === 'model')
+    expect(modelEntry?.poster).toBe(ASSET_MAP.TQ_img1.remoteSrc)
+    expect(modelEntry?.thumbnail).toBe(ASSET_MAP.TQ_img1.remoteSrc)
+  })
+
+  it('treats an asset id the asset map cannot resolve as no model at all', () => {
+    // resolveAssetUrl returns unknown ids verbatim; a bare 'TQ_…' must never
+    // reach <model-viewer src>.
+    const product = build({ ...baseRecord, model_url: 'TQ_deleted', model_poster_url: 'TQ_gone' })
+    expect(product.modelUrl).toBeNull()
+    expect(product.hasModel).toBe('false')
+    expect(product.showModel).toBe('false')
+    expect(product.galleryMedia.map((m) => m.kind)).toEqual(['image', 'image'])
+  })
+
+  it('drops a stale poster id but keeps the model', () => {
+    const product = build({ ...baseRecord, model_url: 'TQ_model', model_poster_url: 'TQ_gone' })
+    expect(product.modelUrl).toBe(ASSET_MAP.TQ_model.remoteSrc)
+    expect(product.modelPoster).toBe(ASSET_MAP.TQ_img1.remoteSrc)
+  })
+
+  it('accepts raw URLs in the model columns', () => {
+    const product = build({
+      ...baseRecord,
+      model_url: 'https://cdn.example.com/raw.glb',
+      model_poster_url: '/local/poster.png',
+    })
+    expect(product.modelUrl).toBe('https://cdn.example.com/raw.glb')
+    expect(product.modelPoster).toBe('/local/poster.png')
+  })
+
+  it('carries the model fields into related products', () => {
+    const related = { ...baseRecord, id: 'p9', slug: 'chair-9', model_url: 'TQ_model' }
+    const product = buildEcommerceProduct(
+      { ...baseRecord, related_product_ids: JSON.stringify(['p9']) },
+      { assetMap: ASSET_MAP, relatedProductsById: { p9: related } }
+    )
+    const relatedProducts = product.relatedProducts as Product[]
+    expect(relatedProducts).toHaveLength(1)
+    expect(relatedProducts[0].showModel).toBe('true')
+    expect(relatedProducts[0].modelUrl).toBe(ASSET_MAP.TQ_model.remoteSrc)
+  })
+
+  it('uses the image alt for pictures and the product name for the model', () => {
+    const product = build({ ...baseRecord, image_alt: 'A chair', model_url: 'TQ_model' })
+    expect(product.galleryMedia[0].alt).toBe('Chair')
+    expect(product.galleryMedia[1].alt).toBe('A chair')
+  })
+})

package/__tests__/infinite-scroll.test.ts

@@ -0,0 +1,143 @@
+import * as types from '@babel/types'
+import generator from '@babel/generator'
+import { ComponentStructure } from '@teleporthq/teleport-types'
+import { createNextArrayMapperPaginationPlugin } from '../src/pagination-plugin'
+import {
+  makeMultiMapperUidl,
+  makeUidlNode,
+  makeWidgetComponentChunk,
+  type RepeaterOptions,
+} from './_helpers/pagination-widget-fixture'
+
+const runPlugin = async (
+  repeater: RepeaterOptions,
+  controls: string[] = ['previous', 'next']
+): Promise<string> => {
+  const chunk = makeWidgetComponentChunk({ controls })
+  const structure: ComponentStructure = {
+    uidl: { name: 'TestComponent', node: makeUidlNode(repeater) },
+    chunks: [chunk],
+    dependencies: {},
+    options: { dataSources: {}, extractedResources: {} },
+  } as never
+  await createNextArrayMapperPaginationPlugin()(structure)
+  return generator(chunk.content as types.Node).code
+}
+
+const collapse = (code: string): string => code.replace(/\s+/g, ' ')
+
+describe('pagination plugin — infinite scroll', () => {
+  it('accumulates pages inside fetchData and reports the end of the data', async () => {
+    const code = await runPlugin({ infiniteScroll: true })
+    const flat = collapse(code)
+
+    expect(flat).toContain('const ds_0_accumRef = useRef({ sig: "", pages: {} })')
+    expect(flat).toContain('const [ds_0_hasMoreFlag, setDs_0_hasMoreFlag] = useState(true)')
+    // Two independent end-of-data signals: a short page, and the counted total.
+    expect(flat).toContain(
+      'const ds_0_hasMore = ds_0_hasMoreFlag && (ds_0_maxPages === 0 || ds_0_page < ds_0_maxPages)'
+    )
+
+    // Everything but the page identifies the QUERY: a filter, sort or search
+    // change must start a fresh list rather than interleave two result sets.
+    expect(flat).toContain('const sig = JSON.stringify({ ...params, page: 0 })')
+    expect(flat).toContain('if (ds_0_accumRef.current.sig !== sig)')
+    expect(flat).toContain('ds_0_accumRef.current = { sig, pages: {} }')
+    expect(flat).toContain('ds_0_accumRef.current.pages[page] = rows')
+    // A short page is the only end signal a source that cannot count gives.
+    expect(flat).toContain('setDs_0_hasMoreFlag(rows.length >= 20)')
+    // Numeric sort, so page 10 does not land between 1 and 2.
+    expect(flat).toContain('.map(Number).sort((a, b) => a - b).reduce(')
+  })
+
+  it('keeps the page out of the provider key and suppresses initialData', async () => {
+    const code = await runPlugin({ infiniteScroll: true })
+
+    // Remounting per appended page would throw away the accumulated rows...
+    expect(code).not.toContain('ds_0_page}`')
+    // ...and initialData would make DataProvider skip the fetch that fills the
+    // accumulator with page 1.
+    expect(code).not.toContain('initialData')
+  })
+
+  it('observes a sentinel after the list when there is no Load More button', async () => {
+    const code = await runPlugin({ infiniteScroll: true })
+    const flat = collapse(code)
+
+    expect(flat).toContain('const ds_0_sentinelRef = useRef(null)')
+    expect(flat).toContain(
+      '<div ref={ds_0_sentinelRef} aria-hidden="true" style={{ height: "1px" }} />'
+    )
+    expect(flat).toContain('new IntersectionObserver(')
+    expect(flat).toContain('typeof IntersectionObserver === "undefined"')
+    expect(flat).toContain('rootMargin: "200px"')
+    expect(flat).toContain('return () => observer.disconnect()')
+    expect(flat).toContain('}, [ds_0_hasMore, ds_0_maxPages])')
+    // ⛔ The next page comes from the updater's OWN argument. The effect is
+    // re-armed on hasMore/maxPages, neither of which changes on an append while
+    // the total is unknown — a captured page would still read 1 on the second
+    // intersection and the list would stop growing after one page.
+    expect(flat).toContain(
+      'setDs_0_page(page => ds_0_maxPages > 0 && page >= ds_0_maxPages ? page : page + 1)'
+    )
+  })
+
+  it('wires the authored Load More button instead, with no observer', async () => {
+    const code = await runPlugin({ infiniteScroll: true, infiniteScrollLoadMore: true }, [
+      'load-more',
+    ])
+    const flat = collapse(code)
+
+    expect(flat).toContain('className="thq-load-more-elm"')
+    expect(flat).toContain('type="button"')
+    expect(flat).toContain('disabled={!ds_0_hasMore}')
+    expect(flat).not.toContain('IntersectionObserver')
+    expect(flat).not.toContain('sentinelRef')
+  })
+
+  it('drops page controls left in the widget when the list appends', async () => {
+    const code = await runPlugin({ infiniteScroll: true, infiniteScrollLoadMore: true }, [
+      'previous',
+      'load-more',
+      'next',
+    ])
+
+    // A visitor of an appending list never leaves page 1, so Previous/Next
+    // would be dead controls.
+    expect(code).not.toContain('thq-previous-elm')
+    expect(code).not.toContain('thq-next-elm')
+    expect(code).toContain('thq-load-more-elm')
+  })
+
+  it('strips a widget left behind on an auto-loading list', async () => {
+    // An older project (or an externally placed widget) can still carry
+    // Previous/Next after the author switches to infinite scroll. They would be
+    // dead controls, so the mode's own pruning removes them even though this
+    // mapper renders no widget of its own.
+    const code = await runPlugin({ infiniteScroll: true }, ['previous', 'next'])
+
+    expect(code).not.toContain('thq-previous-elm')
+    expect(code).not.toContain('thq-next-elm')
+  })
+
+  it('does not desynchronise the widget zip when mappers use different modes', async () => {
+    // ⛔ The infinite mapper draws no container. Counting one for it would wire
+    // THIS mapper's buttons to the other mapper's state.
+    const chunk = makeWidgetComponentChunk({ controls: ['previous', 'next'], mappers: 1 })
+    const structure: ComponentStructure = {
+      uidl: {
+        name: 'TestComponent',
+        node: makeMultiMapperUidl([{ infiniteScroll: true }, {}]),
+      },
+      chunks: [chunk],
+      dependencies: {},
+      options: { dataSources: {}, extractedResources: {} },
+    } as never
+    await createNextArrayMapperPaginationPlugin()(structure)
+    const code = generator(chunk.content as types.Node).code
+
+    // The single authored widget belongs to the SECOND (paginated) mapper.
+    expect(code).toContain('setDs_1_page')
+    expect(code).not.toContain('setDs_0_page(page => Math.max(1, page - 1))')
+  })
+})

package/__tests__/numbered-pagination.test.ts

@@ -0,0 +1,113 @@
+import * as types from '@babel/types'
+import generator from '@babel/generator'
+import { ComponentStructure } from '@teleporthq/teleport-types'
+import { createNextArrayMapperPaginationPlugin } from '../src/pagination-plugin'
+import {
+  makeUidlNode,
+  makeWidgetComponentChunk,
+  type RepeaterOptions,
+} from './_helpers/pagination-widget-fixture'
+
+const runPlugin = async (
+  repeater: RepeaterOptions,
+  controls: string[],
+  legacyOnly = false
+): Promise<string> => {
+  const chunk = makeWidgetComponentChunk({ controls, legacyOnly })
+  const structure: ComponentStructure = {
+    uidl: { name: 'TestComponent', node: makeUidlNode(repeater) },
+    chunks: [chunk],
+    dependencies: {},
+    options: { dataSources: {}, extractedResources: {} },
+  } as never
+  await createNextArrayMapperPaginationPlugin()(structure)
+  return generator(chunk.content as types.Node).code
+}
+
+const collapse = (code: string): string => code.replace(/\s+/g, ' ')
+
+const NUMBERED_CONTROLS = ['first', 'previous', 'pages', 'next', 'last']
+
+describe('pagination plugin — numbered mode', () => {
+  it('computes a windowed token list with an ellipsis on each side', async () => {
+    const code = await runPlugin({ paginationMode: 'numbered' }, NUMBERED_CONTROLS)
+    const flat = collapse(code)
+
+    expect(flat).toContain('const ds_0_pageTokens = useMemo(')
+    // No results at all and a single page are answered without a window.
+    expect(flat).toContain('if (total <= 0) return []')
+    expect(flat).toContain('if (total === 1) return [1]')
+    // First and last are always shown, with one neighbour either side.
+    expect(flat).toContain('const start = Math.max(2, current - 1)')
+    expect(flat).toContain('const end = Math.min(total - 1, current + 1)')
+    expect(flat).toContain('if (start > 2) tokens.push("start-ellipsis")')
+    expect(flat).toContain('if (end < total - 1) tokens.push("end-ellipsis")')
+    expect(flat).toContain('}, [ds_0_maxPages, ds_0_page])')
+  })
+
+  it('repeats the authored template button per page, preserving its class', async () => {
+    const code = await runPlugin({ paginationMode: 'numbered' }, NUMBERED_CONTROLS)
+    const flat = collapse(code)
+
+    expect(flat).toContain('ds_0_pageTokens.map(token =>')
+    expect(flat).toContain('typeof token === "number"')
+    // The author's own node is cloned, so their styling survives.
+    expect(flat).toContain('className="thq-page-elm"')
+    // The current page is MARKED, not disabled — it stays reachable and
+    // `[aria-current='page']` is styleable.
+    expect(flat).toContain('aria-current={ds_0_page === token ? "page" : undefined}')
+    // The `${token}` here is the GENERATED source being asserted on, not an
+    // interpolation this file wants performed.
+    // tslint:disable-next-line:no-invalid-template-strings
+    expect(flat).toContain('key={`page-${token}`}')
+    expect(flat).toContain('onClick={() => setDs_0_page(page => page === token ? page : token)}')
+    // Whatever label the template carried is replaced by the real number.
+    expect(flat).toContain('>{token}<')
+    // No authored ellipsis template ⇒ a plain span fills the gap.
+    expect(flat).toContain('<span key={token}>…</span>')
+  })
+
+  it('wires First and Last against the live page count', async () => {
+    const code = await runPlugin({ paginationMode: 'numbered' }, NUMBERED_CONTROLS)
+    const flat = collapse(code)
+
+    expect(flat).toContain('onClick={() => setDs_0_page(page => page === 1 ? page : 1)}')
+    expect(flat).toContain('disabled={ds_0_page <= 1}')
+    expect(flat).toContain(
+      'onClick={() => setDs_0_page(page => page === ds_0_maxPages ? page : ds_0_maxPages)}'
+    )
+    // maxPages 0 is "no results", where the last page would be page 0.
+    expect(flat).toContain('disabled={ds_0_maxPages === 0 || ds_0_page >= ds_0_maxPages}')
+  })
+
+  it('fetches a live count on a PAGE, which otherwise only has the build-time one', async () => {
+    const code = await runPlugin({ paginationMode: 'numbered' }, NUMBERED_CONTROLS)
+
+    // A numbered strip labels every page, so a stale build-time count would
+    // print numbers that do not exist.
+    expect(code).toContain('-count?')
+    expect(code).toContain('setDs_0_maxPages(data.count === 0 ? 0 : Math.ceil(data.count / 20))')
+  })
+
+  it('removes a numbered strip left over from a mode switch', async () => {
+    // The builder never deletes controls on a mode switch (that would discard
+    // the author's styling), so a Previous/Next list can still carry them.
+    const code = await runPlugin({}, NUMBERED_CONTROLS)
+
+    expect(code).not.toContain('ds_0_pageTokens')
+    expect(code).not.toContain('thq-first-elm')
+    expect(code).not.toContain('thq-last-elm')
+    expect(code).not.toContain('thq-pages-elm')
+    // Previous/Next are still wired exactly as before.
+    expect(code).toContain('thq-previous-elm')
+    expect(code).toContain('disabled={ds_0_page <= 1}')
+  })
+
+  it('still finds Previous/Next by class name in projects predating the marker', async () => {
+    const code = await runPlugin({}, ['previous', 'next'], /* legacyOnly */ true)
+
+    expect(code).toContain('products-list-thq-previous-elm')
+    expect(code).toContain('disabled={ds_0_page <= 1}')
+    expect(code).toContain('disabled={ds_0_page >= ds_0_maxPages}')
+  })
+})

package/__tests__/page-reset-on-filter-sort.test.ts

@@ -0,0 +1,182 @@
+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'
+
+// Same minimal `const TestComponent = (props) => { return <div/> }` shell the
+// search-url-sync suite uses: the reset effect is derived from the UIDL
+// registry, not from the JSX, so an empty body is enough to observe it.
+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: {},
+  }
+}
+
+interface ListOptions {
+  searchEnabled?: boolean
+  // A filter destination bound to component state (the category dropdown).
+  stateFilter?: string
+  // A filter destination read straight from the URL (`?categoryFilter=`).
+  urlFilter?: string
+  // A dynamic sort expression reading component state (the sort dropdown).
+  sortExpression?: string
+}
+
+// tslint:disable-next-line:no-any
+const makeUidlNode = (options: ListOptions): any => {
+  // tslint:disable-next-line:no-any
+  const filters: any[] = []
+  if (options.stateFilter) {
+    filters.push({
+      source: 'category_filter_ids',
+      operand: 'array_overlap',
+      destination: {
+        type: 'dynamic',
+        content: { referenceType: 'state', id: options.stateFilter },
+      },
+    })
+  }
+  if (options.urlFilter) {
+    filters.push({
+      source: 'category_filter_ids',
+      operand: 'array_overlap',
+      destination: {
+        type: 'dynamic',
+        content: { referenceType: 'urlSearchParams', id: options.urlFilter },
+      },
+    })
+  }
+
+  return {
+    type: 'data-source-list',
+    content: {
+      renderPropIdentifier: 'items',
+      resourceDefinition: {
+        dataSourceId: 'ds1',
+        tableName: 'products',
+        dataSourceType: 'postgresql',
+      },
+      resource: {
+        params: {
+          queryColumns: { content: ['name'] },
+          ...(filters.length > 0 ? { filters: { content: filters } } : {}),
+        },
+      },
+      nodes: {
+        success: {
+          type: 'cms-list-repeater',
+          content: {
+            renderPropIdentifier: 'product',
+            paginated: true,
+            perPage: 20,
+            searchEnabled: options.searchEnabled !== false,
+            searchDebounce: 300,
+            ...(options.sortExpression
+              ? {
+                  sort: { type: 'expr', content: options.sortExpression },
+                  sortDirection: { type: 'static', content: 'asc' },
+                }
+              : {}),
+            nodes: { list: { type: 'element', content: { elementType: 'div' } } },
+          },
+        },
+      },
+    },
+  }
+}
+
+// Babel prints object literals across several lines; assertions about a whole
+// statement read better against a whitespace-collapsed copy.
+const collapse = (code: string): string => code.replace(/\s+/g, ' ')
+
+const runPlugin = async (options: ListOptions): Promise<string> => {
+  const chunk = makeComponentChunk()
+  const structure: ComponentStructure = {
+    uidl: { name: 'TestComponent', node: makeUidlNode(options) },
+    chunks: [chunk],
+    dependencies: {},
+    options: { dataSources: {}, extractedResources: {} },
+  } as never
+  await createNextArrayMapperPaginationPlugin()(structure)
+  return generator(chunk.content as types.Node).code
+}
+
+describe('pagination plugin — page resets to 1 when a filter or sort changes', () => {
+  it('resets the combined state page for a state-bound filter', async () => {
+    const code = await runPlugin({ stateFilter: 'selectedCategory' })
+
+    expect(code).toContain('const ds_0_filterResetRef = useRef(null)')
+    expect(code).toContain('const __sig = JSON.stringify([selectedCategory])')
+    expect(code).toContain('if (ds_0_filterResetRef.current === __sig) return')
+    // First OBSERVED value is recorded, never acted on.
+    expect(code).toContain('const __first = ds_0_filterResetRef.current === null')
+    expect(code).toContain('if (__first) return')
+    // Functional update that bails when already on page 1, so a visitor who
+    // never paginated does not get an extra render (and refetch).
+    expect(collapse(code)).toContain(
+      'setDs_0_state(state => state.page === 1 ? state : { ...state, page: 1 })'
+    )
+    expect(code).toContain('}, [selectedCategory])')
+  })
+
+  it('tracks the sort state alongside the filter', async () => {
+    const code = await runPlugin({
+      stateFilter: 'selectedCategory',
+      sortExpression: 'sortBy.split("-")[0]',
+    })
+
+    expect(code).toContain('const __sig = JSON.stringify([selectedCategory, sortBy])')
+    expect(code).toContain('}, [selectedCategory, sortBy])')
+  })
+
+  it('guards on router.isReady and null-coalesces URL params so deep links survive', async () => {
+    const code = await runPlugin({ urlFilter: 'categoryFilter' })
+
+    // ⛔ The reason this effect hashes a signature instead of skipping the first
+    // run: router.query is empty until the router hydrates, and treating that
+    // hydration as a change would reset a `?page=3&categoryFilter=X` deep link.
+    expect(code).toContain('if (!router.isReady) return')
+    expect(code).toContain('const __sig = JSON.stringify([router.query.categoryFilter ?? null])')
+    expect(code).toContain('}, [router.query.categoryFilter, router.isReady])')
+  })
+
+  it('uses the standalone page setter for a paginated-only list', async () => {
+    const code = await runPlugin({ searchEnabled: false, stateFilter: 'selectedCategory' })
+
+    expect(code).toContain('setDs_0_page(page => page === 1 ? page : 1)')
+    expect(code).not.toContain('setDs_0_state(')
+  })
+
+  it('emits nothing for a list that has no filter and no dynamic sort', async () => {
+    const code = await runPlugin({})
+
+    // Regression guard: an unfiltered mapper must generate exactly what it did
+    // before this feature existed.
+    expect(code).not.toContain('filterResetRef')
+    expect(code).not.toContain('__sig')
+  })
+})