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

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 {
@@ -121,51 +126,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 ====================
@@ -213,10 +187,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 +247,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 +275,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 +293,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 +508,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 +538,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
           }
@@ -838,21 +801,118 @@ 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 the page — `?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; the combined paginated state keeps its
+// page, which a typed change resets to 1 in the debounce effect.
+function buildUrlSearchAdopter(
+  adopterVar: string,
+  usage: DataSourceUsage,
+  vars: ReturnType<typeof getStateVarsForUsage>
+): types.VariableDeclaration {
+  const update = types.identifier('update')
+  const applyToDebounced =
+    usage.category === 'paginated+search'
+      ? // setDs_N_state((state) => {
+        //   const next = update(state.debouncedQuery)
+        //   return next === state.debouncedQuery ? state : { ...state, 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')),
+                    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
@@ -1258,13 +1318,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(
@@ -2736,6 +2795,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 +2842,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 +2884,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 +2919,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
 
@@ -3650,38 +3740,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 +3830,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 +3916,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 +3947,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)
             )
           )
         }

package/src/product-price-sort.ts

@@ -191,14 +191,3 @@ export const generateSortFallbackFieldHelper = (tableName: string): string => {
 
   return ['function sortFallbackField(field) {', branches + '  return field', '}'].join('\n')
 }
-
-/**
- * A deterministic tiebreaker appended to every products ORDER BY.
- *
- * Without one, a paginated sort with ties — and "sort by discount" ties every
- * undiscounted product at zero — has no defined order between equal rows, so
- * the same product can appear on two pages or on none. `id` is on the products
- * table from its first migration.
- */
-export const generateSortTiebreakSql = (tableName: string): string =>
-  supportsProductPriceSort(tableName) ? ', "id" ASC' : ''

package/src/row-order.ts

@@ -0,0 +1,54 @@
+import { supportsProductPriceSort } from './product-price-sort'
+
+interface ColumnLike {
+  name?: unknown
+  isPrimaryKey?: unknown
+}
+
+/**
+ * The column that tells a table's rows apart, read from the table the project
+ * saved: its primary key, else a column named `id`. The products table has `id`
+ * from its first migration. Null when neither is known — then nothing is added,
+ * rather than a column that may not exist.
+ */
+export const rowIdentityColumn = (
+  config: Record<string, unknown>,
+  tableName: string
+): string | null => {
+  const selectedTables = (config as { selectedTables?: Record<string, { columns?: unknown }> })
+    .selectedTables
+  const saved = selectedTables?.[tableName]?.columns
+  const columns = (Array.isArray(saved) ? (saved as ColumnLike[]) : []).filter(
+    (column) => typeof column?.name === 'string'
+  )
+  const key =
+    columns.find((column) => column.isPrimaryKey === true)?.name ??
+    columns.find((column) => column.name === 'id')?.name
+  if (typeof key === 'string') {
+    return key
+  }
+  return supportsProductPriceSort(tableName) ? 'id' : null
+}
+
+/**
+ * The `rowOrderTiebreak(fields, direction)` helper a SQL fetcher embeds: what
+ * ends an ORDER BY so that it orders every row.
+ *
+ * Rows that share every requested key have no order of their own, and the
+ * database deals them out differently for each page — "sort by discount" ties
+ * every undiscounted product at zero, and an import dates hundreds of articles
+ * alike — so a paginated list repeated some rows and never showed others.
+ * The tie follows the last key's direction, as the editor's canvas does.
+ */
+export const generateRowOrderTiebreakHelper = (identityColumn: string | null): string => {
+  if (!identityColumn) {
+    return "const rowOrderTiebreak = () => ''"
+  }
+  const quoted = `"${identityColumn.replace(/"/g, '""')}"`
+  return [
+    'const rowOrderTiebreak = (fields, direction) =>',
+    `  fields.includes(${JSON.stringify(identityColumn)}) ? '' : ${JSON.stringify(
+      `, ${quoted} `
+    )} + direction`,
+  ].join('\n')
+}

package/src/sort-utils.ts

@@ -63,6 +63,31 @@ const toExpressionAndDeps = (
   return { expr: parsed, deps: Array.from(deps) }
 }
 
+/**
+ * The `{ field, order }` of a sort the UIDL FIXES — a static column and a
+ * static direction (or none: ascending) — or undefined for one bound to state.
+ * A fixed sort is a static sort: it rides on the server-side first-page fetch
+ * and the client keeps that page, which a dynamic sort cannot let it do.
+ */
+export const readFixedSort = (
+  sort: UIDLStaticValue | UIDLExpressionValue | undefined,
+  sortDirection: UIDLStaticValue | UIDLExpressionValue | undefined
+): { field: string; order: 'asc' | 'desc' } | undefined => {
+  if (sort?.type !== 'static' || typeof sort.content !== 'string' || !sort.content.trim()) {
+    return undefined
+  }
+  if (
+    sortDirection &&
+    (sortDirection.type !== 'static' || typeof sortDirection.content !== 'string')
+  ) {
+    return undefined
+  }
+  const direction = String(sortDirection?.content ?? '')
+    .trim()
+    .toLowerCase()
+  return { field: sort.content.trim(), order: direction.startsWith('desc') ? 'desc' : 'asc' }
+}
+
 export const extractDynamicSort = (
   sort: UIDLStaticValue | UIDLExpressionValue | undefined,
   sortDirection: UIDLStaticValue | UIDLExpressionValue | undefined