@teleporthq/teleport-plugin-next-data-source 0.43.74 → 0.44.0

package/src/pagination-plugin.ts

@@ -8,11 +8,16 @@ import * as types from '@babel/types'
 import { parseExpression } from '@babel/parser'
 import { ASTStatementOrder, GenericUtils, StringUtils } from '@teleporthq/teleport-shared'
 import { ASTUtils, URLQueryWriter, URLSearchParamSync } from '@teleporthq/teleport-plugin-common'
-import { generateSafeFileName } from './utils'
+import { collectFilterLeafConditions, generateSafeFileName, pruneFilterTree } from './utils'
 import { generateDataSourceFetcherWithCore } from './data-source-fetchers'
 import { buildProductTransformOptions, type EntityTransformOptions } from './transformations'
-import { appendSortsParam, DynamicSortAST, extractDynamicSort } from './sort-utils'
-import { appendFiltersParam, pushStateIdsAsDeps, pushPropIdsAsDeps } from './filter-utils'
+import { appendSortsParam, DynamicSortAST, extractDynamicSort, readFixedSort } from './sort-utils'
+import {
+  appendFiltersParam,
+  buildStaticFiltersStringifyCall,
+  pushStateIdsAsDeps,
+  pushPropIdsAsDeps,
+} from './filter-utils'
 import { appendItemsPathParam, extractItemsPath } from './items-path'
 import { resolveRepeaterPerPage } from './repeater-page-size'
 import {
@@ -32,10 +37,15 @@ import {
 import {
   convertControlToButton,
   dropInactivePaginationControls,
+  findAllPaginationControls,
   findPaginationControl,
+  PAGINATION_FOR_ATTR,
+  readJSXAttributeString,
   setJSXExpressionAttribute,
   type PaginationControlKind,
 } from './pagination-controls'
+import { findRangeControls, wireRangeControl } from './range-control'
+import { findAllSearchInputsInJSX, pairSearchInputs, wireSearchInput } from './search-input'
 import { buildCountFetchEffect, buildCountSeqDeclaration } from './count-effect'
 import {
   findAllSearchClearButtonsInJSX,
@@ -48,6 +58,7 @@ import {
   type NumberedPaginationVars,
 } from './numbered-pagination'
 import {
+  buildAccumulatingRequestMark,
   buildAccumulatingResponseHandler,
   buildInfiniteScrollDeclarations,
   buildSentinelElement,
@@ -121,51 +132,20 @@ function searchDefaultValueInitAST(value: SearchDefaultValue | undefined): types
   return types.cloneNode(value.ast, /* deep */ true) as types.Expression
 }
 
-// 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.
+// Builds the `useState(...)` initializer for the search query: the
+// `searchDefaultValue` seed (empty string by default), never the address. A
+// statically generated page is rendered on the server without the visitor's
+// `?searchKeyword=`, and the browser's first render must match it — a query
+// seeded from `window.location.search` rendered a filled input and skipped the
+// prefetched rows there, and React warned of a hydration mismatch. A URL-bound
+// search adopts the address after mount instead (`pushSearchUrlSyncEffects`),
+// as the page number does (`page-url-sync.ts`).
 //
 // 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: DataSourceUsage): types.Expression {
-  const 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
-  )
+  return searchDefaultValueInitAST(usage.searchDefaultValue)
 }
 
 // ==================== UIDL-FIRST STATE MANAGEMENT ====================
@@ -180,6 +160,10 @@ interface DataSourceUsage {
   dataSourceIdentifier: string
   // The cms-list-repeater renderPropIdentifier (e.g., "context_1i871")
   arrayMapperRenderProp: string
+  // The array mapper's editor node id (`nodeId` on the cms-list-repeater), which
+  // a `range` control placed outside the pagination container names in its
+  // `data-tq-pagination-for` attribute. Absent from UIDL exported before it.
+  nodeId?: string
   // Resource definition from UIDL
   resourceDefinition: {
     dataSourceId: string
@@ -213,10 +197,11 @@ interface DataSourceUsage {
   // Dynamic single-column sort bound to component state (set when legacy sorts empty
   // and cms-list-repeater declares sort/sortDirection fields)
   dynamicSort?: DynamicSortAST
-  // Filters from resource params (FLAT condition array — any `{ type: 'group',
-  // children: [...] }` wrappers from the UIDL inspector have already been
-  // unwrapped via `flattenFilterGroups`). Downstream emit sites rely on
-  // entries having `.source` / `.destination` / `.operand` directly.
+  // Filters from resource params, as the TREE the inspector authored: condition
+  // leaves and `{ type: 'group', operator, children }` entries (see
+  // `readFilterTree`). Anything that needs the leaves walks the tree with
+  // `collectFilterLeafConditions`; the emit sites write the tree out whole, so
+  // an `or` group reaches the data source as an `or`.
   // tslint:disable-next-line:no-any
   filters: any[]
   // State IDs from dynamic filter destinations (for useMemo dependencies).
@@ -272,53 +257,26 @@ interface StateRegistry {
   byArrayMapperRenderProp: Map<string, DataSourceUsage>
 }
 
-// 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
-// source API endpoint (`processFilters` in the generated data-source module)
-// only knows how to consume a FLAT array of `{ source, destination, operand }`
-// conditions, so we walk groups recursively here and collect their leaf
-// conditions in order. Anything that isn't a group AND isn't a condition is
-// dropped — defensive against partially-built filter entries that would
-// otherwise emit `{ source: '', destination: '', operand: '' }` rows the
-// API ignores anyway.
-//
-// `or`-grouped conditions are flattened just like `and`-grouped ones — the
-// downstream SQL builder always joins flat filters with `AND`, so emitting
-// the conditions side-by-side approximates AND semantics. A future API
-// upgrade that respects group operators would key off the original tree
-// directly; until then, AND-flattening is the closest correct behaviour and
-// matches what the inspector preview shows for the common single-group case
-// the GUI emits today.
-function flattenFilterGroups(filters: any[]): any[] {
+// The UIDL's `filters.content` array is the tree the inspector authored:
+// `{ type: 'group', operator: 'and' | 'or', children: [...] }` entries around
+// `{ source, destination, operand }` conditions, nested as deep as the user
+// grouped them. The tree is kept as it is — the generated fetchers read it with
+// `normalizeFilterTree`, so an `or` group stays an `or`. Only junk is dropped:
+// an entry that is neither a group nor a condition (a half-built inspector
+// row) would otherwise reach the API as `{ source: '', destination: '' }`.
+// Entries without an explicit `type` are the legacy flat form and are
+// conditions.
+function readFilterTree(filters: any[]): any[] {
   if (!Array.isArray(filters)) {
     return []
   }
-  const out: any[] = []
-  const walk = (entry: any): void => {
-    if (!entry || typeof entry !== 'object') {
-      return
-    }
-    if (entry.type === 'group' && Array.isArray(entry.children)) {
-      for (const child of entry.children) {
-        walk(child)
-      }
-      return
-    }
-    // Backwards-compatible: entries without an explicit `type` (legacy flat
-    // form) and entries explicitly tagged `condition` are both treated as
-    // condition leaves.
-    if (entry.type === undefined || entry.type === 'condition') {
-      out.push(entry)
-    }
-  }
-  for (const entry of filters) {
-    walk(entry)
-  }
-  return out
+  return pruneFilterTree(
+    filters,
+    (entry: any) => entry.type === undefined || entry.type === 'condition'
+  )
 }
 
-// Walks a flat filter list to extract every `urlSearchParams` reference key
+// Walks the filter tree to extract every `urlSearchParams` reference key
 // (e.g. `'categoryFilter'`). Used to (a) inject `const router = useRouter()`
 // once at the top of the component, (b) wire `router.query.<key>` into the
 // `useMemo` dependency array so the client-side fetch reruns whenever the
@@ -327,7 +285,7 @@ function flattenFilterGroups(filters: any[]): any[] {
 function collectFilterUrlSearchParamKeys(filters: any[]): string[] {
   const seen = new Set<string>()
   const out: string[] = []
-  for (const f of filters) {
+  for (const f of collectFilterLeafConditions(filters) as any[]) {
     const dest = f?.destination
     if (!ASTUtils.isUIDLDynamicReference(dest)) {
       continue
@@ -345,6 +303,16 @@ function collectFilterUrlSearchParamKeys(filters: any[]): string[] {
   return out
 }
 
+// The filter tree with every dynamic destination pruned — what `getStaticProps`
+// can resolve at build time. Groups keep their operator; a group left empty by
+// the pruning disappears with it (`pruneFilterTree`).
+function staticFiltersOf(usage: DataSourceUsage): any[] {
+  return pruneFilterTree(
+    usage.filters || [],
+    (f: any) => !ASTUtils.isUIDLDynamicReference(f.destination)
+  )
+}
+
 // Returns true when any filter destination is a `urlSearchParams` dynamic
 // reference — used by the plugin to know it needs to import `useRouter` and
 // emit `const router = useRouter()` at the top of the component. Cheaper to
@@ -550,23 +518,28 @@ function buildStateRegistry(uidlNode: any): StateRegistry {
           sorts = parentDataSource.resourceParams.sorts.content
         }
 
-        // If legacy sorts aren't set, fall back to the new dynamic single-column
-        // sort fields on the cms-list-repeater (used by admin-panel listing pages).
+        // If legacy sorts aren't set, fall back to the single-column sort fields
+        // on the cms-list-repeater. A FIXED one (a column chosen in the editor,
+        // e.g. a blog listing's newest first) is a static sort: read as dynamic,
+        // it made the list drop the server-side first page (`initialData` below
+        // is skipped for a dynamic sort) — the pre-rendered HTML carried no
+        // posts, and the browser fetched page 1 a second time. Only a sort
+        // bound to state (the admin panel's sortable columns) is dynamic.
         let dynamicSort: DynamicSortAST | undefined
         if ((!sorts || sorts.length === 0) && content.sort) {
-          dynamicSort = extractDynamicSort(content.sort, content.sortDirection)
+          const fixedSort = readFixedSort(content.sort, content.sortDirection)
+          if (fixedSort) {
+            sorts = [fixedSort]
+          } else {
+            dynamicSort = extractDynamicSort(content.sort, content.sortDirection)
+          }
         }
 
-        // Extract filters from parent's resource params. The inspector wraps
-        // every condition in a `{ type: 'group' }` envelope (single-group or
-        // nested), so flatten to leaf conditions before the downstream emit
-        // sites consume `.source` / `.destination` / `.operand` directly —
-        // they expect a flat condition array. See `flattenFilterGroups`'s
-        // header comment for why AND-flattening is the correct fallback for
-        // the API endpoint's flat-condition contract.
+        // Extract filters from parent's resource params, keeping the group tree
+        // the inspector authored (see `readFilterTree`).
         let filters: any[] = []
         if (parentDataSource.resourceParams?.filters?.content) {
-          filters = flattenFilterGroups(parentDataSource.resourceParams.filters.content)
+          filters = readFilterTree(parentDataSource.resourceParams.filters.content)
         }
 
         // Split dynamic destination keys by reference type. `state`/`prop`
@@ -575,7 +548,7 @@ function buildStateRegistry(uidlNode: any): StateRegistry {
         // `useRouter()` declaration injected separately.
         const filterStateIds: string[] = []
         const filterPropIds: string[] = []
-        for (const f of filters) {
+        for (const f of collectFilterLeafConditions(filters) as any[]) {
           if (!ASTUtils.isUIDLDynamicReference(f.destination)) {
             continue
           }
@@ -640,6 +613,7 @@ function buildStateRegistry(uidlNode: any): StateRegistry {
           index: index++,
           dataSourceIdentifier: parentDataSource.identifier,
           arrayMapperRenderProp,
+          nodeId: typeof content.nodeId === 'string' ? content.nodeId : undefined,
           resourceDefinition: {
             dataSourceId: parentDataSource.resourceDef.dataSourceId || '',
             tableName: parentDataSource.resourceDef.tableName || '',
@@ -741,6 +715,9 @@ function getStateVarsForUsage(usage: DataSourceUsage): {
   setPageStateVar: string
   maxPagesStateVar: string
   setMaxPagesStateVar: string
+  /** The counted row total behind a `range` control; `null` until counted. */
+  totalStateVar: string
+  setTotalStateVar: string
   searchQueryVar: string
   setSearchQueryVar: string
   debouncedSearchQueryVar: string
@@ -759,6 +736,8 @@ function getStateVarsForUsage(usage: DataSourceUsage): {
     setPageStateVar: `setDs_${idx}_page`,
     maxPagesStateVar: `ds_${idx}_maxPages`,
     setMaxPagesStateVar: `setDs_${idx}_maxPages`,
+    totalStateVar: `ds_${idx}_total`,
+    setTotalStateVar: `setDs_${idx}_total`,
     searchQueryVar: `ds_${idx}_searchQuery`,
     setSearchQueryVar: `setDs_${idx}_searchQuery`,
     debouncedSearchQueryVar: `ds_${idx}_debouncedQuery`,
@@ -838,21 +817,127 @@ function pushSearchUrlSyncEffects(
         )
       : types.identifier(vars.debouncedSearchQueryVar)
 
+  // The query starts at its default (see `buildSearchQueryInitAST`), so the
+  // pair must agree on who goes first: the read-back adopts the address, THEN
+  // the write-back may write — before that, its first run would delete the very
+  // `?<key>=` the read-back is about to adopt.
+  const adoptedRefVar = `ds_${usage.index}_searchUrlAdopted`
+  const adopterVar = `ds_${usage.index}_adoptUrlSearch`
+  effectStatements.push(
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier(adoptedRefVar),
+        types.callExpression(types.identifier('useRef'), [types.booleanLiteral(false)])
+      ),
+    ]),
+    buildUrlSearchAdopter(adopterVar, usage, vars)
+  )
+
   // write-back: debounced query → `?<searchUrlParamKey>=`
   effectStatements.push(
     URLSearchParamSync.buildUrlWriteBackEffect(
       usage.searchUrlParamKey,
       buildDebouncedValueExpr(),
-      buildDebouncedValueExpr()
+      buildDebouncedValueExpr(),
+      undefined,
+      adoptedRefVar
     )
   )
-  // read-back: `?<searchUrlParamKey>=` → input (`setDs_N_searchQuery`). The
-  // debounce effect propagates the change into the debounced value + fetch.
+  // read-back: `?<searchUrlParamKey>=` → the input AND the applied query at once
+  // (`ds_N_adoptUrlSearch`), so an address is not a typed change: it skips the
+  // debounce and keeps a page the address carries — `?searchKeyword=x&page=3`
+  // lands on page 3.
   effectStatements.push(
-    URLSearchParamSync.buildUrlReadBackEffect(usage.searchUrlParamKey, vars.setSearchQueryVar)
+    URLSearchParamSync.buildUrlReadBackEffect(
+      usage.searchUrlParamKey,
+      adopterVar,
+      undefined,
+      adoptedRefVar
+    )
   )
 }
 
+// `const ds_N_adoptUrlSearch = (update) => { … }`: the setter the search's URL
+// read-back calls with its `(prev) => next` updater. It moves the input and the
+// applied (debounced) query together. A list whose page is in the address
+// keeps its page — the page sync sets it from the same address. Any other
+// list starts the new query on page 1, as a typed change does in the debounce
+// effect: an appending list has usually advanced past page 1 by the time the
+// router is ready, and the query's first answer would otherwise be its page 2
+// — empty for a query only a few rows match.
+function buildUrlSearchAdopter(
+  adopterVar: string,
+  usage: DataSourceUsage,
+  vars: ReturnType<typeof getStateVarsForUsage>
+): types.VariableDeclaration {
+  const update = types.identifier('update')
+  const pageReset = usageHasPageUrlSync(usage)
+    ? []
+    : [types.objectProperty(types.identifier('page'), types.numericLiteral(1))]
+  const applyToDebounced =
+    usage.category === 'paginated+search'
+      ? // setDs_N_state((state) => {
+        //   const next = update(state.debouncedQuery)
+        //   return next === state.debouncedQuery ? state : { ...state, page: 1, debouncedQuery: next }
+        // })
+        types.callExpression(types.identifier(vars.setCombinedStateVar), [
+          types.arrowFunctionExpression(
+            [types.identifier('state')],
+            types.blockStatement([
+              types.variableDeclaration('const', [
+                types.variableDeclarator(
+                  types.identifier('next'),
+                  types.callExpression(types.identifier('update'), [
+                    types.memberExpression(
+                      types.identifier('state'),
+                      types.identifier('debouncedQuery')
+                    ),
+                  ])
+                ),
+              ]),
+              types.returnStatement(
+                types.conditionalExpression(
+                  types.binaryExpression(
+                    '===',
+                    types.identifier('next'),
+                    types.memberExpression(
+                      types.identifier('state'),
+                      types.identifier('debouncedQuery')
+                    )
+                  ),
+                  types.identifier('state'),
+                  types.objectExpression([
+                    types.spreadElement(types.identifier('state')),
+                    ...pageReset,
+                    types.objectProperty(
+                      types.identifier('debouncedQuery'),
+                      types.identifier('next')
+                    ),
+                  ])
+                )
+              ),
+            ])
+          ),
+        ])
+      : types.callExpression(types.identifier(vars.setDebouncedSearchQueryVar), [update])
+  return types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.identifier(adopterVar),
+      types.arrowFunctionExpression(
+        [types.identifier('update')],
+        types.blockStatement([
+          types.expressionStatement(
+            types.callExpression(types.identifier(vars.setSearchQueryVar), [
+              types.identifier('update'),
+            ])
+          ),
+          types.expressionStatement(applyToDebounced),
+        ])
+      )
+    ),
+  ])
+}
+
 // How one usage reads and writes its current page.
 //
 // A paginated+search list keeps the page inside a combined
@@ -1126,6 +1211,14 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
     }
     const blockStatement = arrowFunction.body as types.BlockStatement
 
+    // The "Showing 1–8 of 12" texts. Known up front because a component that
+    // draws one needs the counted TOTAL in state — `ds_N_maxPages` alone cannot
+    // say how many rows there are — and that state, with the live count that
+    // fills it, is declared per usage below. A component without one emits
+    // exactly what it always did.
+    const rangeControls = findRangeControls(blockStatement)
+    const hasRangeControl = rangeControls.length > 0
+
     // STEP 1: Build state registry from UIDL
     const registry = buildStateRegistry(uidl.node)
 
@@ -1258,13 +1351,12 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
           ])
         )
 
-        // 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.
+        // Immediate search query state — seeded with `searchDefaultValue`, like
+        // the debounced value above. A deep-linked `?searchKeyword=` is adopted
+        // after mount by the URL read-back, which sets both at once; the
+        // paginated+search `initialData` is gated on `!ds_N_state.debouncedQuery`,
+        // so the adopted query makes the DataProvider fetch filtered rows
+        // instead of reusing the unfiltered SSG prefetch the first render shows.
         stateDeclarations.push(
           types.variableDeclaration('const', [
             types.variableDeclarator(
@@ -1441,12 +1533,16 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
         pushPropIdsAsDeps(countEffectDeps, countEffectSeen, usage.filterPropIds)
         // Same goes for URL-driven filters (already documented above).
         pushUrlSearchParamMemoDeps(countEffectDeps, usage)
+        if (hasRangeControl) {
+          stateDeclarations.push(buildTotalDeclaration(vars))
+        }
         stateDeclarations.push(buildCountSeqDeclaration(vars.countSeqRefVar))
         effectStatements.push(
           buildCountFetchEffect({
             fileName,
             perPage: usage.perPage,
             setMaxPagesVar: vars.setMaxPagesStateVar,
+            setTotalVar: hasRangeControl ? vars.setTotalStateVar : undefined,
             urlParams,
             deps: countEffectDeps,
             countSeqRefVar: vars.countSeqRefVar,
@@ -1513,8 +1609,10 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
         // "Next" button, but not to label a numbered strip or to know when an
         // infinite list has reached its end, so those two modes fetch a live
         // count as well.
+        // A range text needs the live count too: the build-time count only
+        // ever became a page count, never the total it shows.
         const needsLiveCount =
-          !isPage || usage.paginationMode === 'numbered' || usage.infiniteScroll
+          !isPage || usage.paginationMode === 'numbered' || usage.infiniteScroll || hasRangeControl
         if (needsLiveCount) {
           const fileName = generateSafeFileName(
             usage.resourceDefinition.dataSourceType,
@@ -1551,12 +1649,16 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
           pushPropIdsAsDeps(countDeps, countDepsSeen, usage.filterPropIds)
           pushUrlSearchParamMemoDeps(countDeps, usage)
 
+          if (hasRangeControl) {
+            stateDeclarations.push(buildTotalDeclaration(vars))
+          }
           stateDeclarations.push(buildCountSeqDeclaration(vars.countSeqRefVar))
           effectStatements.push(
             buildCountFetchEffect({
               fileName,
               perPage: usage.perPage,
               setMaxPagesVar: vars.setMaxPagesStateVar,
+              setTotalVar: hasRangeControl ? vars.setTotalStateVar : undefined,
               urlParams: countUrlParams,
               deps: countDeps,
               countSeqRefVar: vars.countSeqRefVar,
@@ -1809,10 +1911,8 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       // An auto-loading list needs something at the end of the rows for its
       // IntersectionObserver to watch.
       if (usage.infiniteScroll && usage.paginated && !usage.infiniteScrollLoadMore) {
-        insertSentinelAfterProvider(
-          blockStatement,
-          dp,
-          buildSentinelElement(getInfiniteScrollVars(usage.index))
+        insertSentinelAfterProvider(blockStatement, dp, (parentTag) =>
+          buildSentinelElement(getInfiniteScrollVars(usage.index), parentTag)
         )
       }
 
@@ -1881,25 +1981,17 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       stabilizeDataProviderWithoutRepeater(dp)
     })
 
-    // STEP 4: Wire search inputs
-    // Match search inputs to usages by order (within each dataSourceIdentifier that has search enabled)
+    // STEP 4: Wire search inputs — a platform input by its place among the
+    // search-enabled mappers, a page's own marked input by the mapper it names
+    // (`search-input.ts`).
     const searchInputs = findAllSearchInputsInJSX(blockStatement)
-
-    // Get all search-enabled usages in order
-    const searchEnabledUsages = registry.usages.filter((u) => u.searchEnabled)
-
-    // Match by order - search input 0 -> searchEnabledUsages[0], etc.
-    const usageBySearchInput = new Map<any, DataSourceUsage>()
-    searchInputs.forEach((input, idx) => {
-      if (idx >= searchEnabledUsages.length) {
-        return
+    const usageBySearchInput = pairSearchInputs(searchInputs, registry.usages)
+    for (const input of searchInputs) {
+      const usage = usageBySearchInput.get(input.node)
+      if (usage) {
+        wireSearchInput(input, getStateVarsForUsage(usage))
       }
-
-      const usage = searchEnabledUsages[idx]
-      const vars = getStateVarsForUsage(usage)
-      wireSearchInput(input.node, vars)
-      usageBySearchInput.set(input.node, usage)
-    })
+    }
 
     // STEP 4.5: Wire the clear buttons, each to the input it shares a parent with.
     findAllSearchClearButtonsInJSX(blockStatement).forEach((button) => {
@@ -1938,6 +2030,25 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       }
     )
 
+    // STEP 5b: Wire the range texts that name their mapper.
+    //
+    // A `range` control carrying `data-tq-pagination-for` belongs to the mapper
+    // whose editor node id it names, wherever it sits — a template's footer or
+    // toolbar is laid out by the author, not inside a pagination container, so
+    // the container-ownership rule above cannot reach it. One without the
+    // attribute was wired by its container in STEP 5; one naming a mapper this
+    // component does not render stays as drawn.
+    rangeControls.forEach((control) => {
+      const ownerNodeId = readJSXAttributeString(control, PAGINATION_FOR_ATTR)
+      if (!ownerNodeId) {
+        return
+      }
+      const owner = registry.usages.find((usage) => usage.nodeId === ownerNodeId)
+      if (owner) {
+        wireRangeControlFor(control, owner, getStateVarsForUsage(owner))
+      }
+    })
+
     // STEP 6: Update getStaticProps if this is a page
     if (isPage) {
       updateGetStaticProps(
@@ -1964,6 +2075,8 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
  * It has to be a sibling: the provider's own child is a render-prop function,
  * and anything placed inside it would be re-created on every fetch — the
  * observer would then be watching an element that is no longer in the document.
+ * The sentinel is built for the element it lands in (`buildSentinelElement`):
+ * a fragment is transparent, a component's children may go anywhere.
  *
  * Returns false when the provider has no element parent to splice into (a
  * provider returned directly from the component), leaving the list on its
@@ -1972,35 +2085,53 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
 function insertSentinelAfterProvider(
   blockStatement: types.BlockStatement,
   provider: any,
-  sentinel: types.JSXElement
+  buildSentinel: (parentTag: string | null) => types.JSXElement
 ): boolean {
   let inserted = false
 
-  const traverse = (node: any): void => {
+  const elementTagOf = (node: any, enclosing: string | null): string | null => {
+    if (node?.type === 'JSXFragment') {
+      return enclosing
+    }
+    if (node?.type !== 'JSXElement') {
+      return enclosing
+    }
+    const name = node.openingElement?.name
+    if (name?.type !== 'JSXIdentifier') {
+      return null
+    }
+    if (name.name === 'Fragment') {
+      return enclosing
+    }
+    return /^[a-z]/.test(name.name) ? name.name : null
+  }
+
+  const traverse = (node: any, enclosing: string | null): void => {
     if (!node || inserted) {
       return
     }
+    const tag = elementTagOf(node, enclosing)
     if (Array.isArray(node.children)) {
       const at = node.children.indexOf(provider)
       if (at !== -1) {
-        node.children.splice(at + 1, 0, sentinel)
+        node.children.splice(at + 1, 0, buildSentinel(tag))
         inserted = true
         return
       }
-      node.children.forEach(traverse)
+      node.children.forEach((child: any) => traverse(child, tag))
     }
     if (node.body) {
       if (Array.isArray(node.body)) {
-        node.body.forEach(traverse)
+        node.body.forEach((child: any) => traverse(child, tag))
       } else {
-        traverse(node.body)
+        traverse(node.body, tag)
       }
     }
     if (node.consequent) {
-      traverse(node.consequent)
+      traverse(node.consequent, tag)
     }
     if (node.alternate) {
-      traverse(node.alternate)
+      traverse(node.alternate, tag)
     }
     // `{activeTabIndex === 0 && (<div>…<DataProvider/>…</div>)}` — a tab
     // panel, a gated section: the provider sits on the RIGHT of a logical
@@ -2008,23 +2139,23 @@ function insertSentinelAfterProvider(
     // an argument. Left unvisited, the products list under the first tab of
     // a shop was never paginated or seeded, and rendered nothing.
     if (node.left) {
-      traverse(node.left)
+      traverse(node.left, tag)
     }
     if (node.right) {
-      traverse(node.right)
+      traverse(node.right, tag)
     }
     if (node.test) {
-      traverse(node.test)
+      traverse(node.test, tag)
     }
     if (node.expression) {
-      traverse(node.expression)
+      traverse(node.expression, tag)
     }
     if (node.argument) {
-      traverse(node.argument)
+      traverse(node.argument, tag)
     }
   }
 
-  traverse(blockStatement)
+  traverse(blockStatement, null)
   return inserted
 }
 
@@ -2140,68 +2271,6 @@ function findArrayMapperRenderPropInDataProvider(dataProvider: any): string | un
   return renderItemAttr.value.expression.params[0].name
 }
 
-function findAllSearchInputsInJSX(
-  blockStatement: types.BlockStatement
-): Array<{ node: any; className: string }> {
-  const results: Array<{ node: any; className: string }> = []
-
-  const traverse = (node: any): void => {
-    if (!node) {
-      return
-    }
-
-    if (node.type === 'JSXElement' && node.openingElement?.name?.name === 'input') {
-      const classAttr = node.openingElement.attributes?.find(
-        (attr: any) => attr.type === 'JSXAttribute' && attr.name.name === 'className'
-      )
-      const className = classAttr?.value?.value || classAttr?.value?.expression?.value || ''
-      if (className.includes('search-input')) {
-        results.push({ node, className })
-      }
-    }
-
-    if (node.children && Array.isArray(node.children)) {
-      node.children.forEach((c: any) => traverse(c))
-    }
-    if (node.body) {
-      if (Array.isArray(node.body)) {
-        node.body.forEach((s: any) => traverse(s))
-      } else {
-        traverse(node.body)
-      }
-    }
-    if (node.consequent) {
-      traverse(node.consequent)
-    }
-    if (node.alternate) {
-      traverse(node.alternate)
-    }
-    // `{activeTabIndex === 0 && (<div>…<DataProvider/>…</div>)}` — a tab
-    // panel, a gated section: the provider sits on the RIGHT of a logical
-    // expression (or in a ternary's `test`), which is not a child, a body or
-    // an argument. Left unvisited, the products list under the first tab of
-    // a shop was never paginated or seeded, and rendered nothing.
-    if (node.left) {
-      traverse(node.left)
-    }
-    if (node.right) {
-      traverse(node.right)
-    }
-    if (node.test) {
-      traverse(node.test)
-    }
-    if (node.expression) {
-      traverse(node.expression)
-    }
-    if (node.argument) {
-      traverse(node.argument)
-    }
-  }
-
-  traverse(blockStatement)
-  return results
-}
-
 /**
  * Every pagination widget in the JSX, paired with the mapper it belongs to.
  *
@@ -2736,6 +2805,15 @@ function updateDataProviderForPlain(
   usage: DataSourceUsage,
   localized: boolean
 ): void {
+  // A sort bound to state is the visitor's, which the server cannot know: rows
+  // pre-rendered in the table's order would stand in for it, since a seeded
+  // provider skips its first fetch — the paginated lists drop them the same way.
+  if (usage.dynamicSort) {
+    dp.openingElement.attributes = dp.openingElement.attributes.filter(
+      (attr: any) => !(attr.type === 'JSXAttribute' && attr.name?.name === 'initialData')
+    )
+  }
+
   const attrs = dp.openingElement.attributes
 
   const clientCache = usage.cache?.client ? usage.cache : undefined
@@ -2774,13 +2852,15 @@ function updateDataProviderForPlain(
 
   // Find the params attribute. A plain list may have none at all — but the
   // fetch it was just given sends `params` regardless, and in a localized
-  // project those have to carry the locale, so the attribute is created.
+  // project those have to carry the locale, and a sorted list its sort, so the
+  // attribute is created.
   let paramsAttrIndex = attrs.findIndex(
     (attr: any) => attr.type === 'JSXAttribute' && attr.name.name === 'params'
   )
+  const isSorted = usage.sorts.length > 0 || !!usage.dynamicSort
 
   if (paramsAttrIndex === -1) {
-    if (!localized) {
+    if (!localized && !isSorted) {
       return
     }
     attrs.push(
@@ -2814,10 +2894,22 @@ function updateDataProviderForPlain(
     return
   }
 
-  // Build useMemo dependencies including filter state IDs
+  // The repeater's sort, which the paginated and searchable lists add to the
+  // params they rebuild: kept as they come, a plain list's params never
+  // carried it, and the rows arrived in the table's own order.
+  if (paramsExpression.type === 'ObjectExpression' && !hasObjectKey(paramsExpression, 'sorts')) {
+    appendSortsParam(
+      paramsExpression.properties as types.ObjectProperty[],
+      usage.sorts,
+      usage.dynamicSort
+    )
+  }
+
+  // Build useMemo dependencies including filter state IDs and a dynamic sort's state
   const memoDeps: types.Expression[] = []
   const memoSeen = new Set<string>()
   pushStateIdsAsDeps(memoDeps, memoSeen, usage.filterStateIds)
+  pushStateIdsAsDeps(memoDeps, memoSeen, usage.dynamicSort?.depStateIds ?? [])
   pushPropIdsAsDeps(memoDeps, memoSeen, usage.filterPropIds)
   pushUrlSearchParamMemoDeps(memoDeps, usage)
   if (localized && paramsExpression.type === 'ObjectExpression') {
@@ -2837,6 +2929,14 @@ function updateDataProviderForPlain(
   )
 }
 
+const hasObjectKey = (object: types.ObjectExpression, key: string): boolean =>
+  object.properties.some(
+    (property) =>
+      property.type === 'ObjectProperty' &&
+      ((property.key.type === 'Identifier' && property.key.name === key) ||
+        (property.key.type === 'StringLiteral' && property.key.value === key))
+  )
+
 function stabilizeDataProviderWithoutRepeater(dp: any): void {
   const attrs = dp.openingElement.attributes
 
@@ -2967,11 +3067,21 @@ function createFetchDataAttribute(
     [responseTail]
   )
 
+  // An appending list records the request it now stands on before making it
+  // (see `buildAccumulatingRequestMark`).
   const arrow = cache
     ? types.arrowFunctionExpression(
         [types.identifier('params')],
         buildCachedFetchBody(networkChain, cache)
       )
+    : accumulate
+    ? types.arrowFunctionExpression(
+        [types.identifier('params')],
+        types.blockStatement([
+          buildAccumulatingRequestMark(getInfiniteScrollVars(accumulate.usage.index)),
+          types.returnStatement(networkChain),
+        ])
+      )
     : types.arrowFunctionExpression([types.identifier('params')], networkChain)
 
   return types.jsxAttribute(
@@ -2982,39 +3092,6 @@ function createFetchDataAttribute(
   )
 }
 
-function wireSearchInput(inputNode: any, vars: ReturnType<typeof getStateVarsForUsage>): void {
-  // Remove existing onChange and value
-  inputNode.openingElement.attributes = inputNode.openingElement.attributes.filter(
-    (attr: any) => !['onChange', 'value'].includes(attr.name?.name)
-  )
-
-  // Add onChange
-  inputNode.openingElement.attributes.push(
-    types.jsxAttribute(
-      types.jsxIdentifier('onChange'),
-      types.jsxExpressionContainer(
-        types.arrowFunctionExpression(
-          [types.identifier('e')],
-          types.callExpression(types.identifier(vars.setSearchQueryVar), [
-            types.memberExpression(
-              types.memberExpression(types.identifier('e'), types.identifier('target')),
-              types.identifier('value')
-            ),
-          ])
-        )
-      )
-    )
-  )
-
-  // Add value
-  inputNode.openingElement.attributes.push(
-    types.jsxAttribute(
-      types.jsxIdentifier('value'),
-      types.jsxExpressionContainer(types.identifier(vars.searchQueryVar))
-    )
-  )
-}
-
 /**
  * The `fetchData` attribute for one paginated usage.
  *
@@ -3030,6 +3107,41 @@ function buildFetchDataForUsage(fileName: string, usage: DataSourceUsage): types
   return createFetchDataAttribute(fileName, usage.cache?.client ? usage.cache : undefined)
 }
 
+/** `const [ds_N_total, setDs_N_total] = useState(null)` — declared only beside a range control. */
+function buildTotalDeclaration(vars: ReturnType<typeof getStateVarsForUsage>): types.Statement {
+  return types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.arrayPattern([
+        types.identifier(vars.totalStateVar),
+        types.identifier(vars.setTotalStateVar),
+      ]),
+      types.callExpression(types.identifier('useState'), [types.nullLiteral()])
+    ),
+  ])
+}
+
+/**
+ * Fills one `range` text with the live row range of `usage` (see
+ * `range-control.ts`). A mapper that does not page has no count to show, so
+ * its range text is left as drawn.
+ */
+function wireRangeControlFor(
+  control: any,
+  usage: DataSourceUsage,
+  vars: ReturnType<typeof getStateVarsForUsage>
+): void {
+  if (!usage.paginated) {
+    return
+  }
+  const { currentPageExpr } = getPageAccessors(usage, vars)
+  wireRangeControl(control, {
+    totalVar: vars.totalStateVar,
+    currentPageExpr: currentPageExpr(),
+    perPage: usage.perPage,
+    infiniteScroll: usage.infiniteScroll,
+  })
+}
+
 /**
  * Wires the authored Load More button of an appending list.
  *
@@ -3095,6 +3207,12 @@ function wirePaginationWidget(
   vars: ReturnType<typeof getStateVarsForUsage>,
   hasLoadingState: boolean
 ): void {
+  // A range text inside the container takes the container's owner, like the
+  // buttons beside it; one naming its own mapper is wired in STEP 5b instead.
+  findAllPaginationControls(paginationNode, 'range')
+    .filter((control) => !readJSXAttributeString(control, PAGINATION_FOR_ATTR))
+    .forEach((control) => wireRangeControlFor(control, usage, vars))
+
   if (usage.infiniteScroll) {
     // Only the Load More button survives; page controls make no sense for a
     // list the visitor never leaves.
@@ -3650,38 +3768,12 @@ function updateGetStaticProps(
 
       // Add filters if present
       // Filter out dynamic destinations for getStaticProps (they can't be resolved at build time)
-      const staticFilters = (usage.filters || []).filter(
-        (f: any) => !ASTUtils.isUIDLDynamicReference(f.destination)
-      )
+      const staticFilters = staticFiltersOf(usage)
       if (staticFilters.length > 0) {
         fetchParams.push(
           types.objectProperty(
             types.identifier('filters'),
-            types.callExpression(
-              types.memberExpression(types.identifier('JSON'), types.identifier('stringify')),
-              [
-                types.arrayExpression(
-                  staticFilters.map((filter: any) =>
-                    types.objectExpression([
-                      types.objectProperty(
-                        types.identifier('source'),
-                        types.stringLiteral(filter.source || '')
-                      ),
-                      types.objectProperty(
-                        types.identifier('destination'),
-                        types.stringLiteral(
-                          typeof filter.destination === 'string' ? filter.destination : ''
-                        )
-                      ),
-                      types.objectProperty(
-                        types.identifier('operand'),
-                        types.stringLiteral(filter.operand || '')
-                      ),
-                    ])
-                  )
-                ),
-              ]
-            )
+            buildStaticFiltersStringifyCall(staticFilters)
           )
         )
       }
@@ -3766,9 +3858,7 @@ function updateGetStaticProps(
         const maxPagesPropName = `${vars.propsPrefix}_maxPages`
         // Use filter-specific count variable if usage has static filters
         // (dynamic filters can't be resolved at build time)
-        const staticFiltersForCount = (usage.filters || []).filter(
-          (f: any) => !ASTUtils.isUIDLDynamicReference(f.destination)
-        )
+        const staticFiltersForCount = staticFiltersOf(usage)
         // A count scoped to an inner array is a different number from the
         // whole-payload one, so it gets its own variable just like a filtered one.
         const hasScopedCount = staticFiltersForCount.length > 0 || !!usage.itemsPath
@@ -3854,9 +3944,7 @@ function updateGetStaticProps(
     usagesByFilters.forEach((usages, filtersKey) => {
       const firstUsage = usages[0]
       // Filter out dynamic destinations for getStaticProps (they can't be resolved at build time)
-      const staticFiltersForCount = (firstUsage.filters || []).filter(
-        (f: any) => !ASTUtils.isUIDLDynamicReference(f.destination)
-      )
+      const staticFiltersForCount = staticFiltersOf(firstUsage)
       const hasStaticFilters = staticFiltersForCount.length > 0
 
       // Create unique count variable name based on filters (and inner-array
@@ -3887,31 +3975,7 @@ function updateGetStaticProps(
           countParams.push(
             types.objectProperty(
               types.identifier('filters'),
-              types.callExpression(
-                types.memberExpression(types.identifier('JSON'), types.identifier('stringify')),
-                [
-                  types.arrayExpression(
-                    staticFiltersForCount.map((f: any) =>
-                      types.objectExpression([
-                        types.objectProperty(
-                          types.identifier('source'),
-                          types.stringLiteral(f.source || '')
-                        ),
-                        types.objectProperty(
-                          types.identifier('destination'),
-                          types.stringLiteral(
-                            typeof f.destination === 'string' ? f.destination : ''
-                          )
-                        ),
-                        types.objectProperty(
-                          types.identifier('operand'),
-                          types.stringLiteral(f.operand || '')
-                        ),
-                      ])
-                    )
-                  ),
-                ]
-              )
+              buildStaticFiltersStringifyCall(staticFiltersForCount)
             )
           )
         }