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

package/src/page-reset.ts

@@ -0,0 +1,162 @@
+import * as types from '@babel/types'
+
+/**
+ * Resetting a paginated list back to page 1 when its FILTER or SORT changes.
+ *
+ * Without this a visitor on page 5 who picks a category with twelve results
+ * fetches page 5 of twelve rows and is shown an empty grid, with only
+ * "Previous" to get out of it. The search input never had this bug: its
+ * debounce effect REPLACES the whole `{ page, debouncedQuery }` state, and so
+ * has always dropped the page back to 1 as a side effect.
+ *
+ * ⛔ Why the guard is a signature and not the usual `useRef(true)` skip-first:
+ * URL-driven dependencies (`router.query.categoryFilter`) are `undefined` on
+ * the first render and only take their real value once the router hydrates.
+ * A skip-first guard would treat that hydration as a change and reset the page
+ * of a deep link like `?page=3&categoryFilter=Rings` back to 1 — the very
+ * sharing case the page-in-URL feature exists to support. Comparing a
+ * serialised signature instead means the first OBSERVED value is recorded
+ * rather than acted on, whatever render it arrives in, and any later genuine
+ * change resets exactly once.
+ */
+
+export interface PageResetDeps {
+  /** Bare identifiers: state-bound filter destinations and dynamic-sort deps. */
+  stateIds: string[]
+  /** Emitted as `props.<id>` — props are never destructured into scope. */
+  propIds: string[]
+  /** Emitted as `router.query.<key>`. */
+  urlSearchParamKeys: string[]
+}
+
+/** True when there is nothing that could ever change the filtering of this list. */
+export const hasNoPageResetDeps = (deps: PageResetDeps): boolean =>
+  deps.stateIds.length === 0 && deps.propIds.length === 0 && deps.urlSearchParamKeys.length === 0
+
+const routerQueryAccess = (key: string): types.MemberExpression =>
+  types.memberExpression(
+    types.memberExpression(types.identifier('router'), types.identifier('query')),
+    types.identifier(key)
+  )
+
+/**
+ * The expressions the effect both depends on and hashes into its signature.
+ *
+ * Kept in one place so the two can never drift: a value in the signature but
+ * not the deps would be read stale, and one in the deps but not the signature
+ * would re-run the effect without being able to explain why it changed.
+ */
+const buildTrackedExpressions = (deps: PageResetDeps): types.Expression[] => {
+  const tracked: types.Expression[] = []
+  const seen = new Set<string>()
+  for (const id of deps.stateIds) {
+    if (seen.has(id)) {
+      continue
+    }
+    seen.add(id)
+    tracked.push(types.identifier(id))
+  }
+  for (const id of deps.propIds) {
+    const key = `props.${id}`
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    tracked.push(types.memberExpression(types.identifier('props'), types.identifier(id)))
+  }
+  for (const key of deps.urlSearchParamKeys) {
+    tracked.push(routerQueryAccess(key))
+  }
+  return tracked
+}
+
+/**
+ * Builds the reset effect.
+ *
+ * @param refVar          name of the `useRef` holding the last seen signature
+ * @param buildResetStatement  how this usage writes page 1 — the combined
+ *                        `{ page, debouncedQuery }` state and the standalone
+ *                        page state need different setters
+ */
+export const buildFilterSortPageResetEffect = (
+  refVar: string,
+  deps: PageResetDeps,
+  buildResetStatement: () => types.Statement
+): types.ExpressionStatement => {
+  const body: types.Statement[] = []
+  const hasRouterDeps = deps.urlSearchParamKeys.length > 0
+
+  // Reading `router.query` before the router is ready would hash `undefined`
+  // for every URL-driven filter and record a signature that is about to change
+  // on its own.
+  if (hasRouterDeps) {
+    body.push(
+      types.ifStatement(
+        types.unaryExpression(
+          '!',
+          types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+          true
+        ),
+        types.returnStatement()
+      )
+    )
+  }
+
+  const refCurrent = types.memberExpression(types.identifier(refVar), types.identifier('current'))
+
+  // `?? null` so a missing URL param serialises as `null` rather than dropping
+  // out of the array and shifting every later entry.
+  const signatureEntries = buildTrackedExpressions(deps).map((expr) =>
+    expr.type === 'MemberExpression' && expr.object.type === 'MemberExpression'
+      ? types.logicalExpression('??', expr, types.nullLiteral())
+      : expr
+  )
+
+  body.push(
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__sig'),
+        types.callExpression(
+          types.memberExpression(types.identifier('JSON'), types.identifier('stringify')),
+          [types.arrayExpression(signatureEntries)]
+        )
+      ),
+    ]),
+    types.ifStatement(
+      types.binaryExpression('===', types.cloneNode(refCurrent, true), types.identifier('__sig')),
+      types.returnStatement()
+    ),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__first'),
+        types.binaryExpression('===', types.cloneNode(refCurrent, true), types.nullLiteral())
+      ),
+    ]),
+    types.expressionStatement(
+      types.assignmentExpression('=', types.cloneNode(refCurrent, true), types.identifier('__sig'))
+    ),
+    types.ifStatement(types.identifier('__first'), types.returnStatement()),
+    buildResetStatement()
+  )
+
+  const effectDeps = buildTrackedExpressions(deps)
+  if (hasRouterDeps) {
+    effectDeps.push(types.memberExpression(types.identifier('router'), types.identifier('isReady')))
+  }
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], types.blockStatement(body)),
+      types.arrayExpression(effectDeps),
+    ])
+  )
+}
+
+/** `const <refVar> = useRef(null)` — the signature store for the effect above. */
+export const buildPageResetRefDeclaration = (refVar: string): types.VariableDeclaration =>
+  types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.identifier(refVar),
+      types.callExpression(types.identifier('useRef'), [types.nullLiteral()])
+    ),
+  ])

package/src/page-url-sync.ts

@@ -0,0 +1,241 @@
+import * as types from '@babel/types'
+import { URLQueryWriter } from '@teleporthq/teleport-plugin-common'
+
+/**
+ * Keeping the current page and the `?page=` query in step.
+ *
+ * ## Why one effect and not the read-back / write-back PAIR
+ *
+ * Every other URL-bound control (the category dropdown, the sort select, the
+ * search box) uses two independent effects from `URLSearchParamSync`, each
+ * bailing when the value it would write is already there. That works because
+ * both sides start out agreeing: the state is SEEDED from
+ * `window.location.search` in its `useState` initializer, so by the time the
+ * effects run there is nothing to reconcile.
+ *
+ * The page cannot be seeded that way, for a reason that only shows up in a
+ * browser: a statically generated page is rendered on the server with page 1,
+ * and React does NOT repair mismatched ATTRIBUTES when it hydrates — it keeps
+ * the server's DOM and warns. A client that seeded page 3 renders "Previous" as
+ * enabled, the server rendered it disabled, and the disabled one is what stays
+ * on screen. Worse, it stays for good: React's later re-renders diff against the
+ * client's own first render, which already said enabled, so nothing ever
+ * repaints it. The rows would be page 3's with no way back to page 2.
+ *
+ * Adopting the URL in an effect instead makes the page change from 1 to 3 a
+ * real state transition, which React renders normally. But a naive PAIR of
+ * effects then races: on the render where the router becomes ready, the
+ * write-back sees page 1, deletes `?page=3` from the URL, and the read-back it
+ * was supposed to cooperate with reads back the page it just erased.
+ *
+ * So one effect owns both directions and decides which side moved:
+ *
+ *   • the URL moved (a deep link, a `<Link>`, browser back/forward) ⇒ adopt it
+ *   • the page moved (a click, or the filter reset) ⇒ write it
+ *
+ * The previously seen URL value is what separates the two, so neither direction
+ * has to guess. Page 1 is written as the ABSENCE of the key, so an unpaginated
+ * visit keeps a clean URL and a filter reset takes `?page=` back off it.
+ *
+ * ⚠️ A deep-linked page 2+ therefore costs one extra fetch: the provider mounts
+ * on page 1 and refetches when this effect adopts the URL. Correctness over the
+ * round trip — the alternative leaves a control the visitor cannot use.
+ */
+
+// Strict JS identifier check, mirroring `URLSearchParamSync`: a key like
+// `foo-bar` has to go through bracket notation or the emitted code is a
+// subtraction.
+const VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+
+const accessKeyOf = (object: types.Expression, paramKey: string): types.MemberExpression =>
+  VALID_JS_IDENTIFIER.test(paramKey)
+    ? types.memberExpression(object, types.identifier(paramKey))
+    : types.memberExpression(object, types.stringLiteral(paramKey), true)
+
+const routerQueryAccess = (paramKey: string): types.MemberExpression =>
+  accessKeyOf(
+    types.memberExpression(types.identifier('router'), types.identifier('query')),
+    paramKey
+  )
+
+/** `const <refVar> = useRef(null)` — the last `?page=` value this effect saw. */
+export const buildPageUrlRefDeclaration = (refVar: string): types.VariableDeclaration =>
+  types.variableDeclaration('const', [
+    types.variableDeclarator(
+      types.identifier(refVar),
+      types.callExpression(types.identifier('useRef'), [types.nullLiteral()])
+    ),
+  ])
+
+export interface PageUrlSyncOptions {
+  paramKey: string
+  /** Ref holding the previously seen URL page. */
+  refVar: string
+  /** How this usage reads its current page. */
+  currentPageExpr: () => types.Expression
+  /** How this usage writes a page back. */
+  buildSetPageStatement: (pageExpr: types.Expression) => types.Expression
+}
+
+/**
+ * Emitted shape (for `?page=`, a combined `{ page, debouncedQuery }` state):
+ *
+ *   useEffect(() => {
+ *     if (!router.isReady) return
+ *     const __urlValue = router.query.page
+ *     const __raw = typeof __urlValue === 'string' ? __urlValue
+ *       : Array.isArray(__urlValue) ? __urlValue[0] || '' : ''
+ *     const __urlPage = Math.max(1, parseInt(__raw, 10) || 1)
+ *     const __statePage = ds_0_state.page
+ *     const __seenUrlPage = ds_0_pageUrlRef.current
+ *     if (__tqQuerySyncRef.current.inFlight === 0 &&
+ *         __seenUrlPage !== __urlPage && __urlPage !== __statePage) {
+ *       ds_0_pageUrlRef.current = __urlPage
+ *       setDs_0_state(state => state.page === __urlPage ? state : { ...state, page: __urlPage })
+ *       return
+ *     }
+ *     ds_0_pageUrlRef.current = __urlPage
+ *     if (__urlPage === __statePage) return
+ *     __tqWriteQueryParam('page', __statePage <= 1 ? undefined : __statePage)
+ *   }, [router.query.page, router.isReady, ds_0_state.page])
+ *
+ * The write goes through `URLQueryWriter` rather than spreading `router.query`
+ * here. This effect and a filter's write-back fire in the SAME flush on every
+ * filter change (the reset moves the page), and two effects each merging into
+ * their own stale snapshot of `router.query` erase each other's keys — see
+ * `url-query-writer.ts` for why that then never settles.
+ */
+export const buildPageUrlSyncEffect = (options: PageUrlSyncOptions): types.ExpressionStatement => {
+  const refCurrent = (): types.MemberExpression =>
+    types.memberExpression(types.identifier(options.refVar), types.identifier('current'))
+
+  const rememberUrlPage = (): types.Statement =>
+    types.expressionStatement(
+      types.assignmentExpression('=', refCurrent(), types.identifier('__urlPage'))
+    )
+
+  const effectBody = types.blockStatement([
+    types.ifStatement(
+      types.unaryExpression(
+        '!',
+        types.memberExpression(types.identifier('router'), types.identifier('isReady'))
+      ),
+      types.returnStatement(null)
+    ),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(options.paramKey)),
+    ]),
+    // `router.query[key]` is `string | string[] | undefined` in Next's typings.
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__raw'),
+        types.conditionalExpression(
+          types.binaryExpression(
+            '===',
+            types.unaryExpression('typeof', types.identifier('__urlValue')),
+            types.stringLiteral('string')
+          ),
+          types.identifier('__urlValue'),
+          types.conditionalExpression(
+            types.callExpression(
+              types.memberExpression(types.identifier('Array'), types.identifier('isArray')),
+              [types.identifier('__urlValue')]
+            ),
+            types.logicalExpression(
+              '||',
+              types.memberExpression(types.identifier('__urlValue'), types.numericLiteral(0), true),
+              types.stringLiteral('')
+            ),
+            types.stringLiteral('')
+          )
+        )
+      ),
+    ]),
+    // A missing, unparseable or out-of-range param all mean page 1 — which is
+    // also the value written as no key at all, so the two sides agree.
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__urlPage'),
+        types.callExpression(
+          types.memberExpression(types.identifier('Math'), types.identifier('max')),
+          [
+            types.numericLiteral(1),
+            types.logicalExpression(
+              '||',
+              types.callExpression(types.identifier('parseInt'), [
+                types.identifier('__raw'),
+                types.numericLiteral(10),
+              ]),
+              types.numericLiteral(1)
+            ),
+          ]
+        )
+      ),
+    ]),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__statePage'), options.currentPageExpr()),
+    ]),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__seenUrlPage'), refCurrent()),
+    ]),
+    // The URL is the side that moved: a deep link (nothing seen yet), a
+    // same-path navigation, or browser back/forward.
+    types.ifStatement(
+      types.logicalExpression(
+        '&&',
+        // ⛔ Only when nothing this component asked for is still landing.
+        // Mid-flight, `router.query` holds a page the visitor is on their way
+        // OUT of (the filter reset writes page 1 while `?page=5` is still in the
+        // bar), and adopting it would put them straight back on it.
+        URLQueryWriter.buildQuerySettledExpr(),
+        types.logicalExpression(
+          '&&',
+          types.binaryExpression(
+            '!==',
+            types.identifier('__seenUrlPage'),
+            types.identifier('__urlPage')
+          ),
+          types.binaryExpression(
+            '!==',
+            types.identifier('__urlPage'),
+            types.identifier('__statePage')
+          )
+        )
+      ),
+      types.blockStatement([
+        rememberUrlPage(),
+        types.expressionStatement(options.buildSetPageStatement(types.identifier('__urlPage'))),
+        types.returnStatement(null),
+      ])
+    ),
+    rememberUrlPage(),
+    types.ifStatement(
+      types.binaryExpression('===', types.identifier('__urlPage'), types.identifier('__statePage')),
+      types.returnStatement(null)
+    ),
+    // The page is the side that moved: a control click, or the filter reset.
+    // The write goes through the shared query writer so it merges into the last
+    // query this component asked for — the filter's own write-back may still be
+    // in flight in this very flush. Page 1 is written as the ABSENCE of the key,
+    // which the writer expresses as `undefined`.
+    URLQueryWriter.buildQueryWriteCall(
+      options.paramKey,
+      types.conditionalExpression(
+        types.binaryExpression('<=', types.identifier('__statePage'), types.numericLiteral(1)),
+        types.identifier('undefined'),
+        types.identifier('__statePage')
+      )
+    ),
+  ])
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], effectBody),
+      types.arrayExpression([
+        routerQueryAccess(options.paramKey),
+        types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+        options.currentPageExpr(),
+      ]),
+    ])
+  )
+}

package/src/pagination-controls.ts

@@ -0,0 +1,176 @@
+import * as types from '@babel/types'
+
+/**
+ * How the generator recognises the pagination controls the builder authored.
+ *
+ * The marker is a STATIC UIDL attribute, which survives the resolver, the JSX
+ * printer and the browser verbatim — unlike `elementType`, which the resolver
+ * replaces with the node's `semanticType`, and unlike the class name, which is
+ * a side effect of the styling pipeline (`ThqPreviousElm` →
+ * `products-list-thq-previous-elm`) and so silently renames whenever a node is
+ * renamed. The same attribute is readable from the DOM, which is how the
+ * pagination-scroll runtime already identifies its own nodes.
+ */
+export const PAGINATION_CONTROL_ATTR = 'data-tq-pagination-control'
+
+/**
+ * `'pages'` is the container the page-number buttons are repeated into and
+ * `'page'` the single template button inside it. `'ellipsis'` and `'sentinel'`
+ * are reserved for an authored gap marker / scroll sentinel; until a builder
+ * emits them both runtimes fall back to generating their own.
+ */
+export type PaginationControlKind =
+  | 'first'
+  | 'previous'
+  | 'pages'
+  | 'page'
+  | 'ellipsis'
+  | 'next'
+  | 'last'
+  | 'load-more'
+  | 'sentinel'
+
+// tslint:disable:no-any
+
+// Reads a JSX attribute's literal string value, covering both the plain
+// `attr="value"` form and the `attr={'value'}` container the UIDL printer emits
+// for some static attributes.
+export function readJSXAttributeString(node: any, attrName: string): string {
+  const attr = node?.openingElement?.attributes?.find(
+    (candidate: any) => candidate.type === 'JSXAttribute' && candidate.name?.name === attrName
+  )
+  return attr?.value?.value || attr?.value?.expression?.value || ''
+}
+
+/**
+ * Depth-first search for one authored pagination control.
+ *
+ * `legacyClassName` keeps every project generated before the marker existed
+ * working: its Previous/Next buttons carry no attribute, so the search falls
+ * back to the class-name substring the generator has always matched on. New
+ * control kinds have no legacy spelling and are marker-only.
+ */
+export function findPaginationControl(
+  root: any,
+  kind: PaginationControlKind,
+  legacyClassName?: string
+): any {
+  const search = (node: any, matches: (candidate: any) => boolean): any => {
+    if (!node) {
+      return null
+    }
+    if (node.type === 'JSXElement' && matches(node)) {
+      return node
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) {
+        const found = search(child, matches)
+        if (found) {
+          return found
+        }
+      }
+    }
+    return null
+  }
+
+  const byMarker = search(
+    root,
+    (node) => readJSXAttributeString(node, PAGINATION_CONTROL_ATTR) === kind
+  )
+  if (byMarker || !legacyClassName) {
+    return byMarker
+  }
+  return search(root, (node) => readJSXAttributeString(node, 'className').includes(legacyClassName))
+}
+
+/** Every authored control of one kind, in document order (page-number templates aside, callers want one). */
+export function findAllPaginationControls(root: any, kind: PaginationControlKind): any[] {
+  const found: any[] = []
+  const traverse = (node: any): void => {
+    if (!node) {
+      return
+    }
+    if (
+      node.type === 'JSXElement' &&
+      readJSXAttributeString(node, PAGINATION_CONTROL_ATTR) === kind
+    ) {
+      found.push(node)
+    }
+    if (Array.isArray(node.children)) {
+      node.children.forEach(traverse)
+    }
+  }
+  traverse(root)
+  return found
+}
+
+/**
+ * Turns an authored control into a real `<button type="button">`.
+ *
+ * The builders author these as styled containers (a `div` after the resolver),
+ * so without this a keyboard user could never reach them and a click would not
+ * register as a form-safe activation. An author-supplied `type` is respected.
+ */
+export function convertControlToButton(node: any): void {
+  node.openingElement.name.name = 'button'
+  if (node.closingElement) {
+    node.closingElement.name.name = 'button'
+  }
+  const hasType = node.openingElement.attributes.some((attr: any) => attr.name?.name === 'type')
+  if (!hasType) {
+    node.openingElement.attributes.push(
+      types.jsxAttribute(types.jsxIdentifier('type'), types.stringLiteral('button'))
+    )
+  }
+}
+
+/** Replaces (never duplicates) one JSX attribute, appending it last. */
+export function setJSXExpressionAttribute(
+  node: any,
+  attrName: string,
+  expression: types.Expression
+): void {
+  node.openingElement.attributes = node.openingElement.attributes.filter(
+    (attr: any) => attr.name?.name !== attrName
+  )
+  node.openingElement.attributes.push(
+    types.jsxAttribute(types.jsxIdentifier(attrName), types.jsxExpressionContainer(expression))
+  )
+}
+
+/** Drops one JSX attribute if present. */
+export function removeJSXAttribute(node: any, attrName: string): void {
+  node.openingElement.attributes = node.openingElement.attributes.filter(
+    (attr: any) => attr.name?.name !== attrName
+  )
+}
+
+/**
+ * Removes the controls that belong to a pagination mode this mapper is not in —
+ * a numbered strip left in a Previous/Next list would render unwired buttons
+ * that look clickable and do nothing.
+ *
+ * Children carrying NO marker are always kept: they are the author's own
+ * additions (a page counter, a spacer) and the generator has no business
+ * deciding whether they belong.
+ */
+export function dropInactivePaginationControls(
+  paginationNode: any,
+  activeKinds: PaginationControlKind[]
+): void {
+  const active = new Set<string>(activeKinds)
+  const prune = (node: any): void => {
+    if (!node || !Array.isArray(node.children)) {
+      return
+    }
+    node.children = node.children.filter((child: any) => {
+      if (child?.type !== 'JSXElement') {
+        return true
+      }
+      const marker = readJSXAttributeString(child, PAGINATION_CONTROL_ATTR)
+      return marker === '' || active.has(marker)
+    })
+    node.children.forEach(prune)
+  }
+  prune(paginationNode)
+}