@teleporthq/teleport-plugin-next-data-source 0.43.75 → 0.44.1

package/src/pagination-plugin.ts

@@ -3,15 +3,28 @@ import {
   ComponentPluginFactory,
   ChunkType,
   FileType,
+  UIDLStateDefinition,
 } from '@teleporthq/teleport-types'
 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 {
+  ASTUtils,
+  RouteUtils,
+  URLQueryWriter,
+  URLSearchParamSync,
+} from '@teleporthq/teleport-plugin-common'
 import { collectFilterLeafConditions, generateSafeFileName, pruneFilterTree } from './utils'
 import { generateDataSourceFetcherWithCore } from './data-source-fetchers'
 import { buildProductTransformOptions, type EntityTransformOptions } from './transformations'
-import { appendSortsParam, DynamicSortAST, extractDynamicSort, readFixedSort } from './sort-utils'
+import {
+  appendSortsParam,
+  buildSortAtStartGuard,
+  buildStartingSortsValue,
+  DynamicSortAST,
+  readRepeaterSort,
+  type SortStateDefault,
+} from './sort-utils'
 import {
   appendFiltersParam,
   buildStaticFiltersStringifyCall,
@@ -32,15 +45,21 @@ import {
   buildCacheStoreThen,
   buildCachedFetchBody,
   buildCachedParamsDeclarations,
+  paramsVarFor,
   registerCacheClientImports,
 } from './cache/ast'
 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,
@@ -53,10 +72,15 @@ import {
   type NumberedPaginationVars,
 } from './numbered-pagination'
 import {
+  buildAccumulatingRequestMark,
   buildAccumulatingResponseHandler,
+  buildAppendingRequestCheck,
+  buildFirstPageDeclaration,
+  buildFirstPageSeedEffect,
   buildInfiniteScrollDeclarations,
   buildSentinelElement,
   buildSentinelObserverEffect,
+  buildServerRowsExpression,
   getInfiniteScrollVars,
 } from './infinite-scroll'
 import {
@@ -154,6 +178,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
@@ -187,6 +215,12 @@ 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
+  // With `dynamicSort`: the states it reads, at the values a visitor starts
+  // with (`readSortStateDefaults`). The build fetches the first page by that
+  // sort, and the list takes those rows while the sort is still there. Absent
+  // when the build cannot know the starting sort: the list then fetches its
+  // first page in the browser.
+  startingSort?: SortStateDefault[]
   // 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
@@ -446,7 +480,10 @@ function buildFilterDestinationExpression(destination: unknown): types.Expressio
 }
 
 // Scan UIDL to find all data source usages and build a registry
-function buildStateRegistry(uidlNode: any): StateRegistry {
+function buildStateRegistry(
+  uidlNode: any,
+  stateDefinitions?: Record<string, UIDLStateDefinition>
+): StateRegistry {
   const usages: DataSourceUsage[] = []
   const byDataSourceId = new Map<string, DataSourceUsage[]>()
   const byArrayMapperRenderProp = new Map<string, DataSourceUsage>()
@@ -515,15 +552,20 @@ function buildStateRegistry(uidlNode: any): StateRegistry {
         // 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) {
-          const fixedSort = readFixedSort(content.sort, content.sortDirection)
-          if (fixedSort) {
-            sorts = [fixedSort]
-          } else {
-            dynamicSort = extractDynamicSort(content.sort, content.sortDirection)
-          }
+        //
+        // A sort the visitor picks still starts somewhere — the store's sort
+        // dropdown at "Name A-Z". Known at build time, it orders the
+        // server-side first page, which the list then shows while the visitor
+        // leaves the sort alone. Read as a plain list's page fetch reads it.
+        const repeaterSort =
+          !sorts || sorts.length === 0
+            ? readRepeaterSort(content.sort, content.sortDirection, stateDefinitions)
+            : {}
+        if (repeaterSort.fixed) {
+          sorts = [repeaterSort.fixed]
         }
+        const dynamicSort = repeaterSort.dynamic
+        const startingSort = repeaterSort.starting
 
         // Extract filters from parent's resource params, keeping the group tree
         // the inspector authored (see `readFilterTree`).
@@ -603,6 +645,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 || '',
@@ -617,6 +660,7 @@ function buildStateRegistry(uidlNode: any): StateRegistry {
           queryColumns,
           sorts,
           dynamicSort,
+          startingSort,
           filters,
           filterStateIds,
           filterPropIds,
@@ -704,6 +748,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
@@ -722,6 +769,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`,
@@ -829,7 +878,8 @@ function pushSearchUrlSyncEffects(
   )
   // 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 the page — `?searchKeyword=x&page=3` lands on page 3.
+  // debounce and keeps a page the address carries — `?searchKeyword=x&page=3`
+  // lands on page 3.
   effectStatements.push(
     URLSearchParamSync.buildUrlReadBackEffect(
       usage.searchUrlParamKey,
@@ -842,19 +892,26 @@ function pushSearchUrlSyncEffects(
 
 // `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; the combined paginated state keeps its
-// page, which a typed change resets to 1 in the debounce effect.
+// 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, debouncedQuery: next }
+        //   return next === state.debouncedQuery ? state : { ...state, page: 1, debouncedQuery: next }
         // })
         types.callExpression(types.identifier(vars.setCombinedStateVar), [
           types.arrowFunctionExpression(
@@ -884,6 +941,7 @@ function buildUrlSearchAdopter(
                   types.identifier('state'),
                   types.objectExpression([
                     types.spreadElement(types.identifier('state')),
+                    ...pageReset,
                     types.objectProperty(
                       types.identifier('debouncedQuery'),
                       types.identifier('next')
@@ -1186,8 +1244,16 @@ 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)
+    const registry = buildStateRegistry(uidl.node, uidl.stateDefinitions)
 
     if (registry.usages.length === 0) {
       return structure
@@ -1500,12 +1566,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,
@@ -1572,8 +1642,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,
@@ -1610,12 +1682,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,
@@ -1804,6 +1880,9 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
     // widgets can be matched to their owner rather than counted off in order.
     const usageByProviderNode = new Map<any, DataSourceUsage>()
     const cacheDeclarations: types.Statement[] = []
+    // Only a page has rows of its own to start an appending list from: its
+    // `getStaticProps` fetched page 1 (`updateGetStaticProps`).
+    const firstPageDeclarations: types.Statement[] | undefined = isPage ? [] : undefined
 
     dataProvidersWithRepeaters.forEach((dp) => {
       const nameAttr = dp.openingElement.attributes.find(
@@ -1842,10 +1921,19 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
           vars,
           fileName,
           cacheDeclarations,
-          localized
+          localized,
+          firstPageDeclarations
         )
       } else if (usage.category === 'paginated-only') {
-        updateDataProviderForPaginationOnly(dp, usage, vars, fileName, cacheDeclarations, localized)
+        updateDataProviderForPaginationOnly(
+          dp,
+          usage,
+          vars,
+          fileName,
+          cacheDeclarations,
+          localized,
+          firstPageDeclarations
+        )
       } else if (usage.category === 'search-only') {
         updateDataProviderForSearchOnly(dp, usage, vars, fileName, cacheDeclarations, localized)
       } else if (usage.category === 'plain') {
@@ -1856,9 +1944,17 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       // change refetches, instead of leaving the previous rows on screen with
       // no feedback. Runs last so it sees the `fetchData` and
       // `persistDataDuringLoading` attributes the updaters above just wrote.
+      // An appending list keeps its rows on screen while its next page loads;
+      // only a list loading afresh falls through to the loading slot.
       const loadingVars = getLoadingStateVars(usage.index)
-      if (applyLoadingStateToDataProvider(dp, loadingVars)) {
-        loadingStateDeclarations.push(...buildLoadingStateDeclarations(loadingVars))
+      const appendingRequest =
+        usage.infiniteScroll && usage.paginated
+          ? buildAppendingRequestCheck(getInfiniteScrollVars(usage.index))
+          : undefined
+      if (applyLoadingStateToDataProvider(dp, loadingVars, appendingRequest)) {
+        loadingStateDeclarations.push(
+          ...buildLoadingStateDeclarations(loadingVars, !!appendingRequest)
+        )
         // Recorded because the loading state is only declared for a provider
         // that HAS a loading slot; a Load More button wired later may only
         // reference `ds_N_isFetching` if it actually exists.
@@ -1868,10 +1964,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)
         )
       }
 
@@ -1928,6 +2022,12 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       registerCacheClientImports(dependencies, uidl.outputOptions?.folderPath)
     }
 
+    // After the cache declarations: a cached list's first page reads the
+    // `ds_N_params` they hoisted.
+    if (firstPageDeclarations?.length) {
+      ASTStatementOrder.insertStatementsAfterDependencies(blockStatement, firstPageDeclarations)
+    }
+
     // STEP 3.5: Handle DataProviders WITHOUT repeaters (data-source-item type)
     // These access single items like data[0].name and should not re-render on state changes
     // We wrap their params in useMemo to prevent reference changes from triggering re-renders
@@ -1940,25 +2040,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) => {
@@ -1997,14 +2089,36 @@ export const createNextArrayMapperPaginationPlugin: ComponentPluginFactory<{}> =
       }
     )
 
-    // STEP 6: Update getStaticProps if this is a page
+    // 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. Its rows are what the
+    // page renders, so they are read as a visitor is served them — unless only
+    // the store's trusted readers can open the page (`pageDataReadArguments`).
     if (isPage) {
       updateGetStaticProps(
         chunks,
         registry,
         dependencies,
         uidl.outputOptions?.folderPath,
-        localized
+        localized,
+        () => RouteUtils.pageDataReadArguments(uidl, options.auth)
       )
     }
 
@@ -2023,6 +2137,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
@@ -2031,35 +2147,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
@@ -2067,23 +2201,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
 }
 
@@ -2199,68 +2333,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.
  *
@@ -2343,10 +2415,12 @@ function findPaginationNodesWithOwners(
  *
  * An uncached mapper keeps the inline `params={useMemo(...)}` it has always had,
  * byte for byte. A cached one hoists that memo into a component const so the
- * peek can depend on the same object identity instead of rebuilding it.
+ * peek can depend on the same object identity instead of rebuilding it; so does
+ * an appending list that starts from its page's rows (`hoistInto`), whose first
+ * page is filed in the accumulator under those params.
  *
- * Returns the identifier holding the peeked rows, or `undefined` when this
- * mapper does not cache.
+ * Returns the identifier holding the params when they were hoisted, and the one
+ * holding the peeked rows when this mapper caches.
  */
 function pushParamsAttribute(
   // tslint:disable-next-line:no-any
@@ -2354,24 +2428,40 @@ function pushParamsAttribute(
   usage: DataSourceUsage,
   paramsProps: types.ObjectProperty[],
   memoDeps: types.Expression[],
-  cacheDeclarations: types.Statement[]
-): string | undefined {
+  cacheDeclarations: types.Statement[],
+  hoistInto?: types.Statement[]
+): { paramsIdentifier?: string; cachedIdentifier?: string } {
   const paramsMemo = types.callExpression(types.identifier('useMemo'), [
     types.arrowFunctionExpression([], types.objectExpression(paramsProps)),
     types.arrayExpression(memoDeps),
   ])
 
-  // A state-bound sort deliberately suppresses `initialData` (see the comment at
-  // the call site): the prefetch ran without sort params, so reusing anything on
-  // mount would mask the current sort. The cache peek is `initialData` by
-  // another name, so it has to be suppressed for exactly the same reason.
+  // A state-bound sort gets no cache peek. The peek is `initialData` by another
+  // name, and such a list takes the server's rows only while its sort is still
+  // where the visitor starts (`buildStartingSortGuard`); the peek was never
+  // extended to it.
   const cache = usage.cache?.client && !usage.dynamicSort ? usage.cache : undefined
 
   if (!cache) {
+    if (!hoistInto) {
+      dp.openingElement.attributes.push(
+        types.jsxAttribute(types.jsxIdentifier('params'), types.jsxExpressionContainer(paramsMemo))
+      )
+      return {}
+    }
+    const paramsIdentifier = paramsVarFor(usage.index)
+    hoistInto.push(
+      types.variableDeclaration('const', [
+        types.variableDeclarator(types.identifier(paramsIdentifier), paramsMemo),
+      ])
+    )
     dp.openingElement.attributes.push(
-      types.jsxAttribute(types.jsxIdentifier('params'), types.jsxExpressionContainer(paramsMemo))
+      types.jsxAttribute(
+        types.jsxIdentifier('params'),
+        types.jsxExpressionContainer(types.identifier(paramsIdentifier))
+      )
     )
-    return undefined
+    return { paramsIdentifier }
   }
 
   const hoisted = buildCachedParamsDeclarations({ index: usage.index, paramsMemo, cache })
@@ -2384,7 +2474,97 @@ function pushParamsAttribute(
     )
   )
 
-  return hoisted.cachedIdentifier
+  return { paramsIdentifier: hoisted.paramsIdentifier, cachedIdentifier: hoisted.cachedIdentifier }
+}
+
+// Whether the rows `getStaticProps` fetched can be this list's first page at
+// all. A sort bound to state can only be served them when the build knows the
+// sort the visitor starts with (`startingSort`) and fetched by it; otherwise
+// the fetch has no sort, and its rows are not the list's first page.
+function prefetchFollowsSort(usage: DataSourceUsage): boolean {
+  return !usage.dynamicSort || !!usage.startingSort
+}
+
+// `sortBy === "name-asc"`: the visitor has not moved the sort from where it
+// starts, so the build-time rows are still its first page. `null` for a list
+// whose sort the visitor cannot pick, or one that reads no state.
+function buildStartingSortGuard(usage: DataSourceUsage): types.Expression | null {
+  return usage.dynamicSort && usage.startingSort ? buildSortAtStartGuard(usage.startingSort) : null
+}
+
+// `<condition> && <starting-sort guard>`, or the condition alone.
+function withStartingSortGuard(
+  condition: types.Expression,
+  usage: DataSourceUsage
+): types.Expression {
+  const sortGuard = buildStartingSortGuard(usage)
+  return sortGuard ? types.logicalExpression('&&', condition, sortGuard) : condition
+}
+
+// An appending list on a page starts from the rows its `getStaticProps`
+// fetched, when they can be its first page (`prefetchFollowsSort`).
+function startsFromServerRows(usage: DataSourceUsage): boolean {
+  return usage.infiniteScroll && usage.paginated && prefetchFollowsSort(usage)
+}
+
+/**
+ * `initialData={ds_N_firstPage}` on an appending list, beside the frozen first
+ * page and the effect that files it as page 1 of the accumulator (see
+ * `infinite-scroll.ts`).
+ *
+ * The rows stand in for page 1 only while they answer the list's query: no
+ * search (`queryGuard`), the sort where the visitor starts, no filter set (the
+ * guards the paged lists use), and at least one row — an empty build-time
+ * answer, which a failed fetch also gives, leaves the browser to fetch page 1
+ * as before.
+ */
+function pushInfiniteScrollFirstPage(
+  // tslint:disable-next-line:no-any
+  dp: any,
+  usage: DataSourceUsage,
+  vars: ReturnType<typeof getStateVarsForUsage>,
+  paramsIdentifier: string,
+  declarations: types.Statement[],
+  queryGuard: types.Expression | null,
+  instanceDeps: types.Expression[]
+): void {
+  const infiniteVars = getInfiniteScrollVars(usage.index)
+  const serverPayload = (): types.Expression =>
+    types.optionalMemberExpression(
+      types.identifier('props'),
+      types.identifier(vars.propsPrefix),
+      false,
+      true
+    )
+  const hasServerRows = types.binaryExpression(
+    '>',
+    types.optionalMemberExpression(
+      buildServerRowsExpression(serverPayload(), usage.itemsPath),
+      types.identifier('length'),
+      false,
+      true
+    ),
+    types.numericLiteral(0)
+  )
+  const startsFromServer = [
+    queryGuard,
+    buildStartingSortGuard(usage),
+    buildNoUrlFilterGuard(usage),
+    hasServerRows,
+  ]
+    .filter((guard): guard is types.Expression => guard !== null)
+    .reduce((all, guard) => types.logicalExpression('&&', all, guard))
+
+  declarations.push(
+    buildFirstPageDeclaration(infiniteVars, startsFromServer, serverPayload(), instanceDeps),
+    buildFirstPageSeedEffect(infiniteVars, paramsIdentifier, usage.perPage, usage.itemsPath)
+  )
+  dp.openingElement.attributes.push(
+    types.jsxAttribute(
+      types.jsxIdentifier('initialData'),
+      types.jsxExpressionContainer(types.identifier(infiniteVars.firstPageVar))
+    )
+  )
 }
 
 function updateDataProviderForPaginatedSearch(
@@ -2393,7 +2573,8 @@ function updateDataProviderForPaginatedSearch(
   vars: ReturnType<typeof getStateVarsForUsage>,
   fileName: string,
   cacheDeclarations: types.Statement[],
-  localized: boolean
+  localized: boolean,
+  firstPageDeclarations?: types.Statement[]
 ): void {
   const attrs = dp.openingElement.attributes
 
@@ -2452,36 +2633,67 @@ function updateDataProviderForPaginatedSearch(
     appendClientLocaleParam(paramsProps, memoDeps)
   }
 
-  const cachedInitialData = pushParamsAttribute(dp, usage, paramsProps, memoDeps, cacheDeclarations)
+  const seedInto = startsFromServerRows(usage) ? firstPageDeclarations : undefined
+  const { paramsIdentifier, cachedIdentifier: cachedInitialData } = pushParamsAttribute(
+    dp,
+    usage,
+    paramsProps,
+    memoDeps,
+    cacheDeclarations,
+    seedInto
+  )
 
-  // Add initialData. Skip the server-prefetched data entirely when a dynamic
-  // state-bound sort is active — the prefetch ran without sort parameters, so
-  // reusing it would mask the current sort state AND cause DataProvider to skip
-  // the first client fetch (its internal guard only skips when initialData is
-  // defined on mount). Without that skip, toggling sort correctly triggers a
-  // refetch via the useMemo params dependency chain.
+  // Add initialData: the server-prefetched page 1 while it is the page on show
+  // — page 1, no search, no filter set, and a sort the visitor picks still where
+  // they start (the prefetch ran by that sort). A list whose starting sort the
+  // build cannot know never takes it: that prefetch ran without a sort, so
+  // reusing it would mask the current sort AND make DataProvider skip its first
+  // client fetch (its internal guard only skips when initialData is defined on
+  // mount). Any other sort is fetched fresh, through the useMemo params.
   //
-  // An appending list skips it for a second reason: `initialData` makes
-  // DataProvider skip its first fetch, so page 1 would render from the prefetch
-  // and never enter the accumulator — appending page 2 would then REPLACE the
-  // visible rows with page 2 alone.
-  if (!usage.dynamicSort && !usage.infiniteScroll) {
+  // An appending list takes its own: `initialData` makes DataProvider skip its
+  // first fetch, so the prefetched page 1 has to be filed in the accumulator
+  // too, or appending page 2 would REPLACE the visible rows with page 2 alone.
+  // The provider remounts per query (its `key`), so the first page is frozen
+  // per query.
+  if (seedInto && paramsIdentifier) {
+    const appliedQuery = (): types.MemberExpression =>
+      types.memberExpression(
+        types.identifier(vars.combinedStateVar),
+        types.identifier('debouncedQuery')
+      )
+    pushInfiniteScrollFirstPage(
+      dp,
+      usage,
+      vars,
+      paramsIdentifier,
+      seedInto,
+      types.unaryExpression('!', appliedQuery(), true),
+      [appliedQuery()]
+    )
+  } else if (prefetchFollowsSort(usage) && !usage.infiniteScroll) {
     const initialDataCondition = wrapInitialDataWithUrlFilterGuard(
-      types.logicalExpression(
-        '&&',
-        types.binaryExpression(
-          '===',
-          types.memberExpression(types.identifier(vars.combinedStateVar), types.identifier('page')),
-          types.numericLiteral(1)
-        ),
-        types.unaryExpression(
-          '!',
-          types.memberExpression(
-            types.identifier(vars.combinedStateVar),
-            types.identifier('debouncedQuery')
+      withStartingSortGuard(
+        types.logicalExpression(
+          '&&',
+          types.binaryExpression(
+            '===',
+            types.memberExpression(
+              types.identifier(vars.combinedStateVar),
+              types.identifier('page')
+            ),
+            types.numericLiteral(1)
           ),
-          true
-        )
+          types.unaryExpression(
+            '!',
+            types.memberExpression(
+              types.identifier(vars.combinedStateVar),
+              types.identifier('debouncedQuery')
+            ),
+            true
+          )
+        ),
+        usage
       ),
       usage
     )
@@ -2575,7 +2787,8 @@ function updateDataProviderForPaginationOnly(
   vars: ReturnType<typeof getStateVarsForUsage>,
   fileName: string,
   cacheDeclarations: types.Statement[],
-  localized: boolean
+  localized: boolean,
+  firstPageDeclarations?: types.Statement[]
 ): void {
   const attrs = dp.openingElement.attributes
 
@@ -2613,22 +2826,36 @@ function updateDataProviderForPaginationOnly(
   }
 
   // Add params
-  const cachedInitialData = pushParamsAttribute(dp, usage, paramsProps, memoDeps, cacheDeclarations)
+  const seedInto = startsFromServerRows(usage) ? firstPageDeclarations : undefined
+  const { paramsIdentifier, cachedIdentifier: cachedInitialData } = pushParamsAttribute(
+    dp,
+    usage,
+    paramsProps,
+    memoDeps,
+    cacheDeclarations,
+    seedInto
+  )
 
-  // Add initialData. See paginated+search updater for why we skip prefetch
-  // reuse when a dynamic state-bound sort is active, and why an appending list
-  // skips it too.
-  if (!usage.dynamicSort && !usage.infiniteScroll) {
+  // Add initialData. See paginated+search updater for when a sort the visitor
+  // picks may reuse the prefetch, and how an appending list takes its own. This
+  // provider never remounts (no `key`), so its first page is frozen for the
+  // page's lifetime.
+  if (seedInto && paramsIdentifier) {
+    pushInfiniteScrollFirstPage(dp, usage, vars, paramsIdentifier, seedInto, null, [])
+  } else if (prefetchFollowsSort(usage) && !usage.infiniteScroll) {
     dp.openingElement.attributes.push(
       types.jsxAttribute(
         types.jsxIdentifier('initialData'),
         types.jsxExpressionContainer(
           types.conditionalExpression(
             wrapInitialDataWithUrlFilterGuard(
-              types.binaryExpression(
-                '===',
-                types.identifier(vars.pageStateVar),
-                types.numericLiteral(1)
+              withStartingSortGuard(
+                types.binaryExpression(
+                  '===',
+                  types.identifier(vars.pageStateVar),
+                  types.numericLiteral(1)
+                ),
+                usage
               ),
               usage
             ),
@@ -2733,18 +2960,27 @@ function updateDataProviderForSearchOnly(
     appendClientLocaleParam(paramsProps, memoDeps)
   }
 
-  const cachedInitialData = pushParamsAttribute(dp, usage, paramsProps, memoDeps, cacheDeclarations)
+  const { cachedIdentifier: cachedInitialData } = pushParamsAttribute(
+    dp,
+    usage,
+    paramsProps,
+    memoDeps,
+    cacheDeclarations
+  )
 
-  // Add initialData. See paginated+search updater for why we skip prefetch
-  // reuse when a dynamic state-bound sort is active.
-  if (!usage.dynamicSort) {
+  // Add initialData. See paginated+search updater for when a sort the visitor
+  // picks may reuse the prefetch.
+  if (prefetchFollowsSort(usage)) {
     dp.openingElement.attributes.push(
       types.jsxAttribute(
         types.jsxIdentifier('initialData'),
         types.jsxExpressionContainer(
           types.conditionalExpression(
             wrapInitialDataWithUrlFilterGuard(
-              types.unaryExpression('!', types.identifier(vars.debouncedSearchQueryVar), true),
+              withStartingSortGuard(
+                types.unaryExpression('!', types.identifier(vars.debouncedSearchQueryVar), true),
+                usage
+              ),
               usage
             ),
             types.optionalMemberExpression(
@@ -2789,20 +3025,58 @@ function updateDataProviderForSearchOnly(
   )
 }
 
+/**
+ * A plain list on a page is seeded with the rows its `getStaticProps` fetched
+ * (`extractDataSourceIntoGetStaticProps`), and a seeded provider skips its first
+ * fetch. With a sort the visitor picks, those rows are the list's only while the
+ * sort is where a visitor starts — the build fetched them by it:
+ *
+ *   initialData={sortBy === "name-asc" ? props.items_products : undefined}
+ *
+ * — and any other sort is fetched fresh, through the params it changes. When the
+ * build cannot know where the sort starts (`prefetchFollowsSort`), it fetched
+ * the rows unsorted, and the list is never seeded with them. A plain list has no
+ * search, and is only seeded without a filter a visitor sets.
+ */
+function seedPlainListWhileSortStarts(dp: any, usage: DataSourceUsage): void {
+  if (!usage.dynamicSort) {
+    return
+  }
+  const attrs = dp.openingElement.attributes
+  const index = attrs.findIndex(
+    (attr: any) => attr.type === 'JSXAttribute' && attr.name?.name === 'initialData'
+  )
+  if (index === -1) {
+    return
+  }
+  if (!prefetchFollowsSort(usage)) {
+    attrs.splice(index, 1)
+    return
+  }
+  const sortGuard = buildStartingSortGuard(usage)
+  const seeded = (attrs[index] as types.JSXAttribute).value
+  if (!sortGuard || seeded?.type !== 'JSXExpressionContainer') {
+    return
+  }
+  attrs[index] = types.jsxAttribute(
+    types.jsxIdentifier('initialData'),
+    types.jsxExpressionContainer(
+      types.conditionalExpression(
+        sortGuard,
+        seeded.expression as types.Expression,
+        types.identifier('undefined')
+      )
+    )
+  )
+}
+
 function updateDataProviderForPlain(
   dp: any,
   fileName: string,
   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')
-    )
-  }
+  seedPlainListWhileSortStarts(dp, usage)
 
   const attrs = dp.openingElement.attributes
 
@@ -3057,11 +3331,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(
@@ -3072,39 +3356,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.
  *
@@ -3120,6 +3371,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.
  *
@@ -3185,6 +3471,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.
@@ -3599,12 +3891,24 @@ export default dataSourceModule.getCount
   }
 }
 
+// `fetchCount(<params>, <read arguments>)`: the params may be left out only
+// when nothing follows them.
+const countReadArguments = (
+  countParams: types.ObjectProperty[],
+  readArguments: types.Expression[]
+): types.Expression[] =>
+  countParams.length > 0 || readArguments.length > 0
+    ? [types.objectExpression(countParams), ...readArguments]
+    : []
+
 function updateGetStaticProps(
   chunks: any[],
   registry: StateRegistry,
   dependencies: Record<string, any>,
   folderPath: string[] | undefined,
-  localized: boolean
+  localized: boolean,
+  // The arguments every read hands the module after its params (fresh nodes per call).
+  readArguments: () => types.Expression[]
 ): void {
   const getStaticPropsChunk = chunks.find((c) => c.name === 'getStaticProps')
   if (!getStaticPropsChunk || getStaticPropsChunk.type !== ChunkType.AST) {
@@ -3736,6 +4040,16 @@ function updateGetStaticProps(
             )
           )
         )
+      } else if (usage.dynamicSort && usage.startingSort) {
+        // A sort the visitor picks: page 1 by the sort they start with, sent
+        // as the very string the browser sends for it, so page 2 continues
+        // this page exactly (see `buildStartingSortsValue`).
+        fetchParams.push(
+          types.objectProperty(
+            types.identifier('sorts'),
+            buildStartingSortsValue(usage.dynamicSort, usage.startingSort)
+          )
+        )
       }
 
       // Add filters if present
@@ -3773,7 +4087,7 @@ function updateGetStaticProps(
                   types.identifier(fetcherImportName),
                   types.identifier('fetchData')
                 ),
-                [types.objectExpression(fetchParams)]
+                [types.objectExpression(fetchParams), ...readArguments()]
               ),
               types.identifier('catch')
             ),
@@ -3962,7 +4276,7 @@ function updateGetStaticProps(
                   types.identifier(fetcherImportName),
                   types.identifier('fetchCount')
                 ),
-                countParams.length > 0 ? [types.objectExpression(countParams)] : []
+                countReadArguments(countParams, readArguments())
               ),
               types.identifier('catch')
             ),