@teleporthq/teleport-plugin-next-data-source 0.43.66 → 0.43.68

package/src/transformations/heading-anchors.ts

@@ -0,0 +1,85 @@
+/**
+ * The class of the `#` link added to a post's content headings.
+ *
+ * ⛔ PAIRED with `BLOG_HEADING_ANCHOR_CLASS` in teleport-gui
+ * `features/blog/constants/blog-heading-anchors.ts`, whose stylesheet (shipped
+ * on the post page) is what keeps the link out of sight until the heading is
+ * hovered or focused.
+ */
+export const BLOG_HEADING_ANCHOR_CLASS = 'tq-heading-anchor'
+
+/**
+ * Generates `addHeadingAnchors(html)`: every `<h2>`–`<h6>` of a post's content
+ * gets an `id` (kept when it already has one, otherwise a slug of its text,
+ * unique within the post) and a trailing `#` link to itself, so a section can
+ * be linked to (`/blog/post#setup`) and the link works on the very first load —
+ * the ids are in the server-rendered HTML.
+ *
+ * The link repeats the heading a screen reader already announces, so it is
+ * hidden from assistive technology and left out of the tab order; the heading
+ * stays the landmark.
+ *
+ * Idempotent: a heading that already carries the link is left alone. `h1` is
+ * the post title's level and is never touched.
+ */
+export const generateHeadingAnchorsCode = (): string => `
+var BLOG_HEADING_ANCHOR_CLASS = '${BLOG_HEADING_ANCHOR_CLASS}'
+var BLOG_HEADING_ID_PATTERN = /\\sid\\s*=\\s*("([^"]*)"|'([^']*)')/i
+
+function escapeHeadingAttribute(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function blogHeadingSlug(text, used) {
+  var base = String(text || '')
+    .normalize('NFKD')
+    .replace(/[\\u0300-\\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^\\p{L}\\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+  if (!base) base = 'section'
+  var slug = base
+  var suffix = 2
+  while (used[slug]) {
+    slug = base + '-' + suffix
+    suffix++
+  }
+  used[slug] = true
+  return slug
+}
+
+function addHeadingAnchors(html) {
+  if (typeof html !== 'string' || !/<h[2-6][\\s>]/i.test(html)) return html
+  // Every id the content already uses is taken, so a generated one never
+  // duplicates it.
+  var used = {}
+  var existingIds = new RegExp(BLOG_HEADING_ID_PATTERN.source, 'gi')
+  var existing
+  while ((existing = existingIds.exec(html)) !== null) {
+    used[decodeHtmlEntities(existing[2] || existing[3] || '')] = true
+  }
+
+  return html.replace(/<h([2-6])(\\s[^>]*)?>([\\s\\S]*?)<\\/h\\1>/gi, function(match, level, rawAttrs, inner) {
+    if (inner.indexOf(BLOG_HEADING_ANCHOR_CLASS) !== -1) return match
+    var text = stripHtmlTags(inner)
+    if (!text) return match
+    var attrs = rawAttrs || ''
+    var idMatch = attrs.match(BLOG_HEADING_ID_PATTERN)
+    var id = idMatch ? decodeHtmlEntities(idMatch[2] || idMatch[3] || '') : ''
+    if (!id) {
+      id = blogHeadingSlug(text, used)
+      attrs = ' id="' + escapeHeadingAttribute(id) + '"' + attrs
+    }
+    return (
+      '<h' + level + attrs + '>' + inner +
+      '<a class="' + BLOG_HEADING_ANCHOR_CLASS + '" href="#' + escapeHeadingAttribute(id) +
+      '" aria-hidden="true" tabindex="-1">#</a>' +
+      '</h' + level + '>'
+    )
+  })
+}
+`

package/src/transformations/index.ts

@@ -1,5 +1,9 @@
-import type { GeneratorOptions, UIDLEcommerceCategory } from '@teleporthq/teleport-types'
-import { StorefrontTax } from '@teleporthq/teleport-shared'
+import type {
+  GeneratorOptions,
+  UIDLAuthentication,
+  UIDLEcommerceCategory,
+} from '@teleporthq/teleport-types'
+import { StorefrontTax, TableAccess } from '@teleporthq/teleport-shared'
 import { generateSharedTransformationCode } from './shared-utils'
 import { generateBlogPostTransformationCode } from './blog-post'
 import { generateCustomPageTransformationCode } from './custom-page'
@@ -7,6 +11,12 @@ import {
   generateEcommerceProductTransformationCode,
   type EcommerceProductTransformOptions,
 } from './ecommerce-product'
+import { REQUEST_LOCALE_PARAM } from '../request-locale'
+import {
+  resolveContentLocalization,
+  type ContentLocalization,
+  type LocalizedProjectOptions,
+} from '../content-localization'
 
 export type { EcommerceProductTransformOptions }
 
@@ -19,6 +29,27 @@ export type { EcommerceProductTransformOptions }
 export interface EntityTransformOptions extends EcommerceProductTransformOptions {
   /** Blog post-category taxonomy — see `blogSettings.categories`. */
   blogCategories?: UIDLEcommerceCategory[]
+  /** Post content headings get ids and `#` links — see `blogSettings.headingAnchors`. */
+  blogHeadingAnchors?: boolean
+  /**
+   * A post details fetch carries the post's approved comments — see
+   * `blogSettings.comments`. Off, the comments table is never queried: a blog
+   * without comments has no such table.
+   */
+  blogComments?: boolean
+  /**
+   * The languages the rows are stored in — absent for a single-language
+   * project. The transform resolves every translatable field against the
+   * request's locale (`?locale=es` → `es_name`, falling back to `name`), and
+   * the fetcher matches and sorts translatable columns the same way.
+   */
+  localization?: ContentLocalization
+  /**
+   * Who may read a money table (gift cards, vouchers, their ledgers) from a
+   * browser: the roles the generated admin panel admits. See
+   * `TableAccess.resolveTrustedReaderRoles`.
+   */
+  trustedReaderRoles?: string[]
 }
 
 /**
@@ -47,12 +78,32 @@ const resolveAllowBackorders = (
  * "stock never blocks a purchase" flag — see `resolveAllowBackorders`.
  */
 export const buildProductTransformOptions = (
-  options: Pick<GeneratorOptions, 'ecommerceSettings' | 'invoiceSettings' | 'blogSettings'>
+  options: Pick<
+    GeneratorOptions,
+    'ecommerceSettings' | 'invoiceSettings' | 'blogSettings' | 'auth'
+  > &
+    LocalizedProjectOptions & {
+      /**
+       * The SAME project authentication under the name a `ProjectUIDL` gives
+       * it — the project plugins call this with the UIDL itself, where the
+       * field is `authentication`, while a component plugin calls it with
+       * `GeneratorOptions`, where it is `auth`. Reading only one of the two
+       * left every fetcher emitted by the project plugins with an empty
+       * trusted-reader list, i.e. a generated admin panel refused its own
+       * money tables.
+       */
+      authentication?: UIDLAuthentication
+    }
 ): EntityTransformOptions => ({
   categories: options.ecommerceSettings?.categories,
   blogCategories: options.blogSettings?.categories,
+  blogHeadingAnchors: options.blogSettings?.headingAnchors === true,
+  blogComments: options.blogSettings?.comments === true,
   storefrontTaxRate: StorefrontTax.resolveStorefrontTaxRate(options.invoiceSettings),
   allowBackorders: resolveAllowBackorders(options.ecommerceSettings),
+  productPages: options.ecommerceSettings?.productPages,
+  localization: resolveContentLocalization(options),
+  trustedReaderRoles: TableAccess.resolveTrustedReaderRoles(options.auth || options.authentication),
 })
 
 export type TransformationType = 'blog-post' | 'ecommerce-product' | 'custom-page' | null
@@ -117,7 +168,13 @@ export const getTransformationCode = (
 
   switch (type) {
     case 'blog-post':
-      return shared + generateBlogPostTransformationCode({ categories: options.blogCategories })
+      return (
+        shared +
+        generateBlogPostTransformationCode({
+          categories: options.blogCategories,
+          headingAnchors: options.blogHeadingAnchors,
+        })
+      )
     case 'ecommerce-product':
       return shared + generateEcommerceProductTransformationCode(options)
     case 'custom-page':
@@ -127,30 +184,99 @@ export const getTransformationCode = (
   }
 }
 
+/**
+ * The request parameter that asks a transformed table for its rows AS STORED.
+ *
+ * The product, blog-post and custom-page transforms build a storefront view
+ * model: camelCased keys, flags as `"true"`/`"false"` strings, derived fields,
+ * and several columns left out altogether (a product's `discounts`,
+ * `category_ids`, `download_limit`, …). A caller that WRITES the row back —
+ * the generated admin's edit forms — needs the columns themselves: fed the view
+ * model, its form showed a digital product as not digital, a gift card switch
+ * ticked on a product that is not one, no discounts, and every save wrote the
+ * missing columns back blank.
+ *
+ * ⛔ PAIRED with `ADMIN_RAW_ROWS_PARAM` in the GUI's
+ * `mappers/domain-to-uidl/feature-detail-page-options.ts`, which bakes it into
+ * the admin update pages' detail resource.
+ */
+export const RAW_ROWS_PARAM = 'rawRows'
+
 /**
  * Returns the JavaScript expression that transforms the data array.
  * This expression assumes the data array variable is called `safeData`,
  * that `getClient` is available for asset resolution, and that `req` is in scope.
- * Returns null if no transformation is needed.
+ * Returns null if no transformation is needed. A request carrying
+ * `RAW_ROWS_PARAM` gets the stored rows instead (see `rawRecords`).
  */
 export const getTransformExpression = (tableName: string): string | null => {
-  const type = detectTransformationType(tableName)
-  if (!type) {
+  if (!detectTransformationType(tableName)) {
     return null
   }
+  return '(__tqWantsRawRows(req.query) ? await rawRecords(safeData, getClient) : await transformRecords(safeData, getClient, req.query))'
+}
 
-  switch (type) {
-    case 'blog-post':
-      return 'await transformRecords(safeData, getClient, req.query)'
-    case 'ecommerce-product':
-      return 'await transformRecords(safeData, getClient, req.query)'
-    case 'custom-page':
-      return 'await transformRecords(safeData, getClient, req.query)'
-    default:
-      return null
+/**
+ * The raw-rows mode every transformed table's fetcher carries: the rows as
+ * stored, with one exception — a value that is an uploaded asset's ID, alone or
+ * inside a JSON list column, becomes the URL the transform would have shown, so
+ * an edit form's image previews keep working. Nothing else is renamed, derived
+ * or dropped. The response cache keys on the query, so the two modes never
+ * share an entry.
+ */
+const RAW_ROWS_CODE = `
+function __tqWantsRawRows(query) {
+  var flag = query ? query.${RAW_ROWS_PARAM} : undefined
+  return flag === true || flag === 'true'
+}
+
+async function rawRecords(records, getClientFn) {
+  if (!Array.isArray(records)) return []
+  var assetMap = {}
+  try {
+    assetMap = await getAssetMap(getClientFn)
+  } catch (e) {
+    // Asset resolution is best-effort; the stored values pass through as they are.
+  }
+  return records.map(function(record) { return __tqResolveRowAssets(record, assetMap || {}) })
+}
+
+function __tqResolveRowAssets(record, assetMap) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return record
+  var out = {}
+  for (var key in record) {
+    if (!Object.prototype.hasOwnProperty.call(record, key)) continue
+    out[key] = __tqResolveAssetValue(record[key], assetMap)
   }
+  return out
+}
+
+function __tqIsAssetId(value, assetMap) {
+  return typeof value === 'string' && value !== '' && Object.prototype.hasOwnProperty.call(assetMap, value)
 }
 
+function __tqResolveAssetValue(value, assetMap) {
+  if (typeof value !== 'string' || !value) return value
+  if (__tqIsAssetId(value, assetMap)) return resolveAssetUrl(value, assetMap)
+  var trimmed = value.trim()
+  if (trimmed.charAt(0) !== '[') return value
+  var list
+  try {
+    list = JSON.parse(trimmed)
+  } catch (e) {
+    return value
+  }
+  if (!Array.isArray(list)) return value
+  var changed = false
+  var resolved = list.map(function(item) {
+    if (!__tqIsAssetId(item, assetMap)) return item
+    changed = true
+    return resolveAssetUrl(item, assetMap)
+  })
+  return changed ? JSON.stringify(resolved) : value
+}
+`
+
 /**
  * How many reviews a product page carries into its structured data.
  *
@@ -165,13 +291,24 @@ export const REVIEWS_PER_PRODUCT = 5
  * Returns the transform wrapper function code that handles asset map loading
  * and calls the appropriate transformer.
  * Returns empty string if no transformation is needed.
+ *
+ * The request's `locale` (see `REQUEST_LOCALE_PARAM`) is what every
+ * translatable field resolves against; the MAIN locale it falls back to is a
+ * project constant and is baked in from `options.localization` rather than
+ * asked of every caller. Without a localization every row reads as before —
+ * the base columns.
  */
-export const getTransformWrapperCode = (tableName: string): string => {
+export const getTransformWrapperCode = (
+  tableName: string,
+  options: Pick<EntityTransformOptions, 'localization' | 'blogComments'> = {}
+): string => {
   const type = detectTransformationType(tableName)
   if (!type) {
     return ''
   }
 
+  const mainLanguageLiteral = JSON.stringify(options.localization?.mainLocale ?? null)
+
   const transformFn =
     type === 'blog-post'
       ? 'transformBlogPosts'
@@ -247,9 +384,11 @@ export const getTransformWrapperCode = (tableName: string): string => {
   }`
       : ''
 
+  // `includeOptionDetail` uses the same single-record heuristic as the related
+  // items: only the details page carries a product's full option tree.
   const variantOption =
     type === 'ecommerce-product'
-      ? ', variantsByProductId: variantsByProductId, ratingsByProductId: ratingsByProductId, reviewsByProductId: reviewsByProductId'
+      ? ', variantsByProductId: variantsByProductId, ratingsByProductId: ratingsByProductId, reviewsByProductId: reviewsByProductId, includeOptionDetail: Array.isArray(records) && records.length === 1'
       : ''
 
   // Related items are resolved for a SINGLE-record fetch only — which is the
@@ -281,17 +420,46 @@ export const getTransformWrapperCode = (tableName: string): string => {
     : ''
   const relatedOption = hasRelatedItems ? `, ${relatedMapVar}: ${relatedMapVar}` : ''
 
-  return `
+  // A post page's neighbours and comments, on the same single-record heuristic
+  // as the related rail. The comments are only asked for when the blog takes
+  // them — see `EntityTransformOptions.blogComments`.
+  const blogPageEnrichment =
+    type === 'blog-post'
+      ? `
+  var adjacentPostsById = null
+  var commentsByPostId = null
+  if (Array.isArray(records) && records.length === 1) {
+    try {
+      adjacentPostsById = await getAdjacentPostsMap(getClientFn, records)
+    } catch (e) {
+      // Best-effort; the post navigation stays hidden.
+    }${
+      options.blogComments
+        ? `
+    try {
+      commentsByPostId = await getBlogCommentsMap(getClientFn, records)
+    } catch (e) {
+      // Best-effort; the post renders without comments.
+    }`
+        : ''
+    }
+  }`
+      : ''
+  const blogPageOption =
+    type === 'blog-post'
+      ? ', adjacentPostsById: adjacentPostsById, commentsByPostId: commentsByPostId'
+      : ''
+
+  return `${RAW_ROWS_CODE}
 async function transformRecords(records, getClientFn, reqQuery) {
   var assetMap = {}
   try {
     assetMap = await getAssetMap(getClientFn)
   } catch (e) {
     // Asset resolution is best-effort; continue without it
-  }${relatedEnrichment}${variantEnrichment}
-  var currentLanguage = (reqQuery && reqQuery.lang) || null
-  var mainLanguage = (reqQuery && reqQuery.mainLang) || null
-  var options = { assetMap: assetMap, currentLanguage: currentLanguage, mainLanguage: mainLanguage${variantOption}${relatedOption} }
+  }${relatedEnrichment}${blogPageEnrichment}${variantEnrichment}
+  var currentLanguage = reqQuery && typeof reqQuery.${REQUEST_LOCALE_PARAM} === 'string' && reqQuery.${REQUEST_LOCALE_PARAM} ? reqQuery.${REQUEST_LOCALE_PARAM} : null
+  var options = { assetMap: assetMap, currentLanguage: currentLanguage, mainLanguage: ${mainLanguageLiteral}${variantOption}${relatedOption}${blogPageOption} }
   return ${transformFn}(records, options)
 }
 `

package/src/transformations/shared-utils.ts

@@ -74,6 +74,12 @@ function getCurrencySymbol(currencyCode) {
 
 function normalizeTimestamp(value) {
   if (value == null) return Date.now()
+  // A row read straight off the driver (the related / adjacent lookups) carries
+  // its timestamps as Date objects.
+  if (value instanceof Date) {
+    var time = value.getTime()
+    return isNaN(time) ? Date.now() : time
+  }
   if (typeof value === 'number') {
     if (isNaN(value)) return Date.now()
     return value < 100000000000 ? value * 1000 : value

package/src/utils.ts

@@ -14,6 +14,7 @@ import { GenericUtils, StringUtils } from '@teleporthq/teleport-shared'
 import { generateDataSourceFetcherWithCore } from './data-source-fetchers'
 import type { EntityTransformOptions } from './transformations'
 import { DATA_SOURCE_ISR_REVALIDATE_SECONDS } from './isr'
+import { buildServerLocaleParam, hasLocaleParam, buildClientLocaleParam } from './request-locale'
 
 const VALID_DATA_SOURCE_TYPES: DataSourceType[] = [
   'rest-api',
@@ -187,18 +188,28 @@ export const generateSafeFileName = (
   return StringUtils.camelCaseToDashCase(baseName)
 }
 
+/**
+ * Wires a `DataProvider` to a client-side fetch of its API route.
+ *
+ * In a localized project (`transformOptions.localization`) the fetch carries
+ * the visitor's locale: it is added to the provider's `params` — created when
+ * the node declares none — so it reaches the route AND keys the client cache.
+ * The caller puts `router` in scope when this answers `true`.
+ *
+ * @returns `true` when a provider was wired to a client fetch.
+ */
 export const extractDataSourceIntoNextAPIFolder = (
   node: UIDLDataSourceItemNode | UIDLDataSourceListNode,
   dataSources: Record<string, UIDLDataSource>,
   componentChunk: ChunkDefinition,
   extractedResources: GeneratorOptions['extractedResources'],
   transformOptions: EntityTransformOptions = {}
-) => {
+): boolean => {
   try {
     // Validate node content structure
     const contentValidation = validateNodeContent(node.content)
     if (!contentValidation.isValid) {
-      return
+      return false
     }
 
     const { resourceDefinition } = node.content
@@ -206,31 +217,31 @@ export const extractDataSourceIntoNextAPIFolder = (
     // Validate resource definition
     const resourceValidation = validateResourceDefinition(resourceDefinition)
     if (!resourceValidation.isValid) {
-      return
+      return false
     }
 
     const { dataSourceId, tableName, dataSourceType } = resourceDefinition
 
     // Check if dataSources object exists
     if (!dataSources || typeof dataSources !== 'object') {
-      return
+      return false
     }
 
     // Check if data source exists
     const dataSource = dataSources[dataSourceId]
     if (!dataSource) {
-      return
+      return false
     }
 
     // Validate data source configuration
     const configValidation = validateDataSourceConfig(dataSource)
     if (!configValidation.isValid) {
-      return
+      return false
     }
 
     // Check if component chunk has meta and nodesLookup
     if (!componentChunk.meta || !componentChunk.meta.nodesLookup) {
-      return
+      return false
     }
 
     // Generate safe file name
@@ -238,7 +249,7 @@ export const extractDataSourceIntoNextAPIFolder = (
 
     // Check if file name is valid
     if (!fileName || fileName === 'unknown') {
-      return
+      return false
     }
 
     // Find JSX node by searching through nodesLookup
@@ -322,12 +333,12 @@ export const extractDataSourceIntoNextAPIFolder = (
     }
 
     if (!jsxNode || jsxNode.type !== 'JSXElement') {
-      return
+      return false
     }
 
     // Ensure opening element and attributes exist
     if (!jsxNode.openingElement || !Array.isArray(jsxNode.openingElement.attributes)) {
-      return
+      return false
     }
 
     // Check if this node has already been processed (has fetchData attribute)
@@ -336,12 +347,16 @@ export const extractDataSourceIntoNextAPIFolder = (
     )
 
     if (existingFetchData) {
-      return
+      return false
     }
 
     // Check if there are resource params
     const resourceParams = node.content.resource?.params || {}
-    const hasParams = Object.keys(resourceParams).length > 0
+    const localized = transformOptions.localization !== undefined
+    if (localized) {
+      addClientLocaleToParams(jsxNode)
+    }
+    const hasParams = localized || Object.keys(resourceParams).length > 0
 
     // Build resource path - use template literal if params exist
     let resourcePath: types.StringLiteral | types.TemplateLiteral
@@ -423,7 +438,7 @@ export const extractDataSourceIntoNextAPIFolder = (
 
     // Ensure extracted resources object exists
     if (!extractedResources || typeof extractedResources !== 'object') {
-      return
+      return true
     }
 
     // Check if a utils file already exists for this data source (from getStaticProps)
@@ -440,7 +455,7 @@ export default dataSourceModule.handler
         path: ['pages', 'api'],
         content: apiRouteCode,
       }
-      return
+      return true
     }
 
     // Generate fetcher code for API route (exports just the handler)
@@ -453,7 +468,7 @@ export default dataSourceModule.handler
         transformOptions
       )
     } catch (error) {
-      return
+      return true
     }
 
     extractedResources[`api/${fileName}`] = {
@@ -462,11 +477,43 @@ export default dataSourceModule.handler
       path: ['pages', 'api'],
       content: fetcherCode,
     }
+    return true
   } catch (error) {
     // Catch any unexpected errors to prevent plugin from crashing
+    return false
   }
 }
 
+/**
+ * Puts `locale: router?.locale` into a provider's `params` object literal,
+ * creating the attribute when the node declared no params at all.
+ */
+const addClientLocaleToParams = (jsxNode: types.JSXElement): void => {
+  const attrs = jsxNode.openingElement.attributes
+  let paramsAttr = attrs.find(
+    (attr): attr is types.JSXAttribute =>
+      attr.type === 'JSXAttribute' &&
+      attr.name.type === 'JSXIdentifier' &&
+      attr.name.name === 'params'
+  )
+  if (!paramsAttr) {
+    paramsAttr = types.jsxAttribute(
+      types.jsxIdentifier('params'),
+      types.jsxExpressionContainer(types.objectExpression([]))
+    )
+    attrs.push(paramsAttr)
+  }
+  const value = paramsAttr.value
+  if (
+    value?.type !== 'JSXExpressionContainer' ||
+    value.expression.type !== 'ObjectExpression' ||
+    hasLocaleParam(value.expression.properties)
+  ) {
+    return
+  }
+  value.expression.properties.push(buildClientLocaleParam())
+}
+
 export const isEmbeddedDataSource = (dataSourceType: string): boolean => {
   return ['javascript', 'csv-file'].includes(dataSourceType)
 }
@@ -581,8 +628,8 @@ export const generateSafeJSONParseCode = (): string => {
  * collapsing to an empty result the caller cannot explain.
  */
 export const generateCollectionPathHelperCode = (): string => {
-  return `const resolveCollectionPath = (payload, rawPath) => {
-  if (!rawPath) return payload
+  return `const parsePayloadPath = (rawPath) => {
+  if (!rawPath) return null
   let path = rawPath
   if (typeof path === 'string') {
     try {
@@ -591,17 +638,39 @@ export const generateCollectionPathHelperCode = (): string => {
       path = path.split('.').filter(Boolean)
     }
   }
-  if (!Array.isArray(path) || path.length === 0) return payload
+  return Array.isArray(path) && path.length > 0 ? path : null
+}
 
+const readPayloadPath = (payload, path) => {
   let current = payload
   for (const segment of path) {
     if (!current || typeof current !== 'object' || Array.isArray(current) || !(segment in current)) {
-      return payload
+      return undefined
     }
     current = current[segment]
   }
+  return current
+}
 
+const resolveCollectionPath = (payload, rawPath) => {
+  const path = parsePayloadPath(rawPath)
+  if (!path) return payload
+  const current = readPayloadPath(payload, path)
   return Array.isArray(current) ? current : payload
+}
+
+// A list bound to an array INSIDE the payload (\`data?.results\`) still has to be
+// searched, filtered, sorted and paged, but the page reads it back through the
+// same path, so the wrapper must survive. Returns the inner array plus a way to
+// put the processed array back, or null when the path does not lead to one.
+const openItemsEnvelope = (payload, rawPath) => {
+  const path = parsePayloadPath(rawPath)
+  if (!path) return null
+  const items = readPayloadPath(payload, path)
+  if (!Array.isArray(items)) return null
+  const rebuild = (node, depth, next) =>
+    depth === path.length ? next : { ...node, [path[depth]]: rebuild(node[path[depth]], depth + 1, next) }
+  return { items, close: (next) => rebuild(payload, 0, next) }
 }`
 }
 
@@ -766,6 +835,22 @@ const buildFilterTreeClause = (node, buildCondition) => {
   return buildCondition(node)
 }
 
+// The generic multi-value operand. The editor sends the destination either as
+// an array or as one comma-joined string (a URL-bound state such as
+// "acme,globex"); both become an array, and "in" becomes "=" so every
+// fetcher's existing array branch answers with IN (...). An empty set means
+// "no filter", never "match nothing".
+const normalizeInOperand = (operand, value) => {
+  if (operand !== 'in') return { operand, value }
+  const entries = Array.isArray(value) ? value : [value]
+  const values = entries
+    .flatMap((entry) => (typeof entry === 'string' ? entry.split(',') : [entry]))
+    .map((entry) => (typeof entry === 'string' ? entry.trim() : entry))
+    .filter((entry) => entry !== '' && entry !== null && entry !== undefined)
+  if (values.length === 0) return null
+  return { operand: '=', value: values }
+}
+
 const flattenFilterConditions = (node) => {
   if (!node) return []
   if (node.type === 'group') {
@@ -1588,6 +1673,11 @@ export const extractDataSourceIntoGetStaticProps = (
       }
     })
 
+    // getStaticProps runs once per language: the prefetch is for that language.
+    if (transformOptions.localization !== undefined) {
+      paramsProperties.push(buildServerLocaleParam())
+    }
+
     const fetchCallExpression = types.callExpression(
       types.memberExpression(types.identifier(fetcherImportName), types.identifier('fetchData')),
       [types.objectExpression(paramsProperties)]