@teleporthq/teleport-plugin-common 0.43.21 → 0.43.27

package/dist/esm/utils/url-search-param-sync.js

@@ -0,0 +1,177 @@
+import * as types from '@babel/types';
+// Shared builders for two-way `<state> ⇄ ?key=` URL search-param syncing.
+//
+// Used by BOTH:
+//   • `createNextUrlSearchParamsPlugin` (teleport-project-generator-next) for
+//     page/component state defs that declare `urlSearchParamBinding` — e.g.
+//     the products-list `selectedCategory` / `sortBy` dropdowns.
+//   • `createNextArrayMapperPaginationPlugin` (teleport-plugin-next-data-source)
+//     for the products-list search input, whose query lives in a
+//     pagination-managed state (`ds_N_searchQuery` / `ds_N_state.debouncedQuery`)
+//     rather than a UIDL state def, so it cannot ride the plugin above.
+//
+// Both emit the SAME loop-free read-back / write-back effect shapes, so the
+// builders live here to keep the two call sites byte-identical and the
+// loop-prevention reasoning in one place.
+// Strict JS identifier (Latin only is fine: UIDL URL keys are limited to the
+// subset Next.js supports as a query param key, which the GUI guarantees to
+// be at minimum URL-safe; but the *generated* code must be valid JS, and
+// `__nextQuery.foo-bar` parses as a subtraction). Anything off-pattern goes
+// through bracket notation: `__nextQuery['foo-bar']`.
+var VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+// `object.<paramKey>` for identifier-safe keys, `object['param-key']` otherwise,
+// so the emitted code is always valid JS regardless of the URL key shape.
+var accessKeyOf = function (object, paramKey) {
+    if (VALID_JS_IDENTIFIER.test(paramKey)) {
+        return types.memberExpression(object, types.identifier(paramKey));
+    }
+    return types.memberExpression(object, types.stringLiteral(paramKey), true);
+};
+var routerQueryAccess = function (paramKey) {
+    return accessKeyOf(types.memberExpression(types.identifier('router'), types.identifier('query')), paramKey);
+};
+// Clones an expression so it can be slotted into multiple positions of the
+// emitted AST — Babel does not support sharing the same node reference across
+// the tree, and callers pass arbitrary value/dependency expressions.
+var clone = function (expr) {
+    return types.cloneNode(expr, /* deep */ true);
+};
+// Builds the state→URL write-back useEffect. Emitted shape (for a value of
+// `selectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (typeof window === 'undefined') return
+//     if (!router.isReady) return
+//     const __nextQuery = { ...router.query }
+//     if (selectedCategory === '' || selectedCategory == null) {
+//       delete __nextQuery.categoryFilter
+//     } else {
+//       __nextQuery.categoryFilter = String(selectedCategory)
+//     }
+//     if (__nextQuery.categoryFilter === router.query.categoryFilter) return
+//     router.replace(
+//       { pathname: router.pathname, query: __nextQuery },
+//       undefined,
+//       { shallow: true }
+//     )
+//   }, [selectedCategory, router.isReady])
+//
+// `valueExpr` is the expression read each render and pushed to the URL (a bare
+// state identifier for dropdowns, `ds_N_state.debouncedQuery` for the search
+// input). `depExpr` is the effect dependency that re-triggers the write-back
+// when that value changes — usually the same expression as `valueExpr`.
+//
+// Notes:
+// 1. `router.isReady` gate: on the very first SSG render `router.query` is
+//    empty, so without this gate any value initialized from
+//    `window.location.search` would immediately `router.replace` itself with
+//    the same value, racing with Next's own hydration. `router.isReady` is
+//    also in the deps array — once it flips to true, the effect re-runs with
+//    the now-hydrated `router.query` and decides correctly whether to replace.
+// 2. The equality check after building `__nextQuery` short-circuits replaces
+//    that would not change the URL — important when the user re-enters the
+//    same value, when the value mounts equal to the URL, and when the
+//    read-back effect fires its setter with the value just pushed.
+// 3. `shallow: true` keeps `getStaticProps` from re-running just because the
+//    URL bar changed; the data-source `useMemo` reacts to the state, not the
+//    URL.
+// 4. Empty / null value deletes the key entirely so the URL never keeps a
+//    sticky `?key=` empty param.
+export var buildUrlWriteBackEffect = function (paramKey, valueExpr, depExpr) {
+    var effectBody = types.blockStatement([
+        // if (typeof window === 'undefined') return
+        types.ifStatement(types.binaryExpression('===', types.unaryExpression('typeof', types.identifier('window')), types.stringLiteral('undefined')), types.returnStatement(null)),
+        // if (!router.isReady) return
+        types.ifStatement(types.unaryExpression('!', types.memberExpression(types.identifier('router'), types.identifier('isReady'))), types.returnStatement(null)),
+        // const __nextQuery = { ...router.query }
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__nextQuery'), types.objectExpression([
+                types.spreadElement(types.memberExpression(types.identifier('router'), types.identifier('query'))),
+            ])),
+        ]),
+        // if (value === '' || value == null) { delete __nextQuery.key }
+        // else { __nextQuery.key = String(value) }
+        types.ifStatement(types.logicalExpression('||', types.binaryExpression('===', clone(valueExpr), types.stringLiteral('')), types.binaryExpression('==', clone(valueExpr), types.nullLiteral())), types.blockStatement([
+            types.expressionStatement(types.unaryExpression('delete', accessKeyOf(types.identifier('__nextQuery'), paramKey))),
+        ]), types.blockStatement([
+            types.expressionStatement(types.assignmentExpression('=', accessKeyOf(types.identifier('__nextQuery'), paramKey), types.callExpression(types.identifier('String'), [clone(valueExpr)]))),
+        ])),
+        // if (__nextQuery.key === router.query.key) return
+        types.ifStatement(types.binaryExpression('===', accessKeyOf(types.identifier('__nextQuery'), paramKey), routerQueryAccess(paramKey)), types.returnStatement(null)),
+        // router.replace({ pathname: router.pathname, query: __nextQuery }, undefined, { shallow: true })
+        types.expressionStatement(types.callExpression(types.memberExpression(types.identifier('router'), types.identifier('replace')), [
+            types.objectExpression([
+                types.objectProperty(types.identifier('pathname'), types.memberExpression(types.identifier('router'), types.identifier('pathname'))),
+                types.objectProperty(types.identifier('query'), types.identifier('__nextQuery')),
+            ]),
+            types.identifier('undefined'),
+            types.objectExpression([
+                types.objectProperty(types.identifier('shallow'), types.booleanLiteral(true)),
+            ]),
+        ])),
+    ]);
+    return types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
+        types.arrowFunctionExpression([], effectBody),
+        types.arrayExpression([
+            clone(depExpr),
+            types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+        ]),
+    ]));
+};
+// Builds the URL→state read-back useEffect. Emitted shape (for setter
+// `setSelectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (!router.isReady) return
+//     const __urlValue = router.query.categoryFilter
+//     const __nextValue =
+//       typeof __urlValue === 'string' ? __urlValue : Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+//     setSelectedCategory((prev) => (prev === __nextValue ? prev : __nextValue))
+//   }, [router.query.categoryFilter, router.isReady])
+//
+// Why pair this with the write-back effect:
+// - On `<Link>` / `router.push` shallow navigations that land on the same path
+//   with a different query (or browser back/forward, which can change the query
+//   without remounting the page), `router.query` updates but the state hook does
+//   not. Without this effect, the control would be stuck on whatever the user
+//   last picked even though the URL has moved on.
+// - The functional `setState((prev) => prev === next ? prev : next)` form
+//   guarantees React bails out when the URL value matches state, which prevents
+//   an infinite write-back ↔ read-back loop: when the user picks a new value,
+//   state→URL fires once, URL→state observes the matching value and returns
+//   `prev`, so React does not re-render or fire any deps.
+// - `router.query[key]` can be either `string` (single value) or `string[]`
+//   (duplicate keys) per Next.js's typings; the helper normalizes both to a
+//   string before comparing, defaulting to `''` for the missing-key case so the
+//   comparison aligns with the write-back's `value === ''` empty-check.
+export var buildUrlReadBackEffect = function (paramKey, setterName) {
+    var normalizeArg = types.conditionalExpression(
+    // typeof __urlValue === 'string' ? __urlValue
+    types.binaryExpression('===', types.unaryExpression('typeof', types.identifier('__urlValue')), types.stringLiteral('string')), types.identifier('__urlValue'), types.conditionalExpression(
+    // Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+    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('')));
+    var effectBody = types.blockStatement([
+        // if (!router.isReady) return
+        types.ifStatement(types.unaryExpression('!', types.memberExpression(types.identifier('router'), types.identifier('isReady'))), types.returnStatement(null)),
+        // const __urlValue = router.query.<paramKey>
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(paramKey)),
+        ]),
+        // const __nextValue = (normalized)
+        types.variableDeclaration('const', [
+            types.variableDeclarator(types.identifier('__nextValue'), normalizeArg),
+        ]),
+        // setState((prev) => prev === __nextValue ? prev : __nextValue)
+        types.expressionStatement(types.callExpression(types.identifier(setterName), [
+            types.arrowFunctionExpression([types.identifier('prev')], types.conditionalExpression(types.binaryExpression('===', types.identifier('prev'), types.identifier('__nextValue')), types.identifier('prev'), types.identifier('__nextValue'))),
+        ])),
+    ]);
+    return types.expressionStatement(types.callExpression(types.identifier('useEffect'), [
+        types.arrowFunctionExpression([], effectBody),
+        types.arrayExpression([
+            routerQueryAccess(paramKey),
+            types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+        ]),
+    ]));
+};
+//# sourceMappingURL=url-search-param-sync.js.map

package/dist/esm/utils/url-search-param-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-search-param-sync.js","sourceRoot":"","sources":["../../../src/utils/url-search-param-sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teleporthq/teleport-plugin-common",
-  "version": "0.43.21",
+  "version": "0.43.27",
   "description": "Common building and modelating functions for ASTs and HASTs",
   "author": "teleportHQ",
   "license": "MIT",
@@ -27,10 +27,10 @@
     "@babel/core": "^7.5.5",
     "@babel/preset-react": "^7.22.5",
     "@babel/types": "^7.5.5",
-    "@teleporthq/teleport-shared": "^0.43.14",
-    "@teleporthq/teleport-types": "^0.43.14",
+    "@teleporthq/teleport-shared": "^0.43.22",
+    "@teleporthq/teleport-types": "^0.43.22",
     "jss": "^10.0.0",
     "jss-preset-default": "^10.0.0"
   },
-  "gitHead": "41c68c00e06f6f811056979b4f0473c277a219cb"
+  "gitHead": "96a6f138f6e447af1c07b1746b67719c16c9dc7b"
 }

package/src/index.ts

@@ -5,6 +5,7 @@ import * as HASTBuilders from './builders/hast-builders'
 import * as ASTUtils from './utils/ast-utils'
 import * as StyleUtils from './utils/style-utils'
 import * as HASTUtils from './utils/hast-utils'
+import * as URLSearchParamSync from './utils/url-search-param-sync'
 import ParsedASTNode from './utils/parsed-ast'
 
 import { createBinaryExpression } from './node-handlers/node-to-jsx/utils'
@@ -16,6 +17,7 @@ export {
   ASTUtils,
   StyleUtils,
   HASTUtils,
+  URLSearchParamSync,
   ParsedASTNode,
   createBinaryExpression,
 }

package/src/node-handlers/node-to-jsx/index.ts

@@ -705,7 +705,35 @@ const generateElementNode: NodeToJSX<UIDLElementNode, types.JSXElement> = (
     )
   }
 
-  if (!selfClosing && children) {
+  // A markdown-node can carry its rich-text content as a dynamic/expr child
+  // (e.g. CMS-bound rich text) rather than as a `raw` attribute. The raw-attribute
+  // path is handled in addAttributesToJSXTag; here we handle the children path so
+  // the content is injected as HTML (dangerouslySetInnerHTML) instead of being
+  // printed as an escaped raw value by the generic expression handler.
+  const isMarkdownNode =
+    node.content.semanticType === 'markdown-node' || originalElementName === 'markdown-node'
+  const hasRawAttr = attrs
+    ? Object.keys(attrs).some((attrKey) => attrs[attrKey]?.type === 'raw')
+    : false
+
+  let markdownChildrenHandled = false
+  if (isMarkdownNode && !selfClosing && !hasRawAttr && children && children.length > 0) {
+    const markdownChild = children.find(
+      (child) => child.type === 'expr' || child.type === 'dynamic'
+    )
+    let markdownExpr: types.Expression | undefined
+    if (markdownChild?.type === 'expr') {
+      markdownExpr = ASTUtils.getExpressionFromUIDLExpressionNode(markdownChild)
+    } else if (markdownChild?.type === 'dynamic') {
+      markdownExpr = resolveDynamicReferenceExpression(markdownChild, childParams, options)
+    }
+    if (markdownExpr) {
+      injectMarkdownExpression(elementTag, markdownExpr, '', childParams)
+      markdownChildrenHandled = true
+    }
+  }
+
+  if (!markdownChildrenHandled && !selfClosing && children) {
     // Reorder children to ensure search nodes appear before DataProvider nodes
     const reorderedChildren = reorderChildrenForSearch(children)
 
@@ -2005,25 +2033,7 @@ const applyStaticMarkdownInjection = (
   rawValue: UIDLRawValue,
   params: JSXGenerationParams
 ) => {
-  const content = rawValue.content || ''
-
-  ;(elementTag.openingElement.name as types.JSXIdentifier).name = 'div'
-  elementTag.openingElement.selfClosing = true
-  elementTag.closingElement = null
-  elementTag.children = []
-
-  elementTag.openingElement.attributes.push(
-    types.jsxAttribute(
-      types.jsxIdentifier('dangerouslySetInnerHTML'),
-      types.jsxExpressionContainer(
-        types.objectExpression([
-          types.objectProperty(types.identifier('__html'), types.stringLiteral(content)),
-        ])
-      )
-    )
-  )
-
-  cleanupMarkdownMappingDependencies(params)
+  injectMarkdownExpression(elementTag, types.stringLiteral(rawValue.content || ''), '', params)
 }
 
 const applyDynamicMarkdownInjection = (
@@ -2034,40 +2044,53 @@ const applyDynamicMarkdownInjection = (
 ) => {
   const dynamicExpr = resolveDynamicReferenceExpression(rawValue.dynamic, params, options)
   const fallbackContent = rawValue.fallback || rawValue.content
+  injectMarkdownExpression(elementTag, dynamicExpr, fallbackContent, params)
+}
 
-  const reactMarkdownTag = createJSXTag('ReactMarkdown')
-  addChildJSXTag(reactMarkdownTag, types.jsxExpressionContainer(types.cloneNode(dynamicExpr)))
-
-  const fallbackTag = ASTBuilders.createDOMInjectionNode(fallbackContent)
-
-  const conditionalExpr = types.conditionalExpression(dynamicExpr, reactMarkdownTag, fallbackTag)
+/**
+ * Renders a markdown-node's rich-text content through the `markdown-to-jsx` <Markdown>
+ * component (the React generator's mapping for markdown-node).
+ *
+ * markdown-to-jsx parses BOTH markdown syntax AND embedded HTML, so it renders correctly
+ * whether the CMS field returns markdown (`# Heading`) or HTML markup (`<p>…</p>`). A raw
+ * HTML approach (dangerouslySetInnerHTML) would ignore markdown, and a markdown-only
+ * renderer (react-markdown) escapes HTML — markdown-to-jsx covers both at once.
+ *
+ * Shared by every way a markdown-node can carry its content:
+ * - a static `raw` attribute (see applyStaticMarkdownInjection)
+ * - a `raw` attribute holding a dynamic reference (see applyDynamicMarkdownInjection)
+ * - a dynamic/expr child, e.g. CMS-bound rich text (see generateElementNode)
+ *
+ * Produces: <Markdown>{expr || fallback}</Markdown>
+ */
+const injectMarkdownExpression = (
+  elementTag: types.JSXElement,
+  expression: types.Expression,
+  fallbackContent: string,
+  params: JSXGenerationParams
+) => {
+  // markdown-to-jsx requires a string child; guard dynamic expressions with a fallback so
+  // a nullish CMS value renders as empty rather than throwing. Static literals need no guard.
+  const childExpr = types.isStringLiteral(expression)
+    ? expression
+    : types.logicalExpression('||', expression, types.stringLiteral(fallbackContent || ''))
 
-  ;(elementTag.openingElement.name as types.JSXIdentifier).name = 'div'
+  ;(elementTag.openingElement.name as types.JSXIdentifier).name = 'Markdown'
   elementTag.openingElement.selfClosing = false
   if (!elementTag.closingElement) {
-    elementTag.closingElement = types.jsxClosingElement(types.jsxIdentifier('div'))
+    elementTag.closingElement = types.jsxClosingElement(types.jsxIdentifier('Markdown'))
   } else {
-    ;(elementTag.closingElement.name as types.JSXIdentifier).name = 'div'
+    ;(elementTag.closingElement.name as types.JSXIdentifier).name = 'Markdown'
   }
-  elementTag.children = [types.jsxExpressionContainer(conditionalExpr)]
-
-  cleanupMarkdownMappingDependencies(params)
+  elementTag.children = [types.jsxExpressionContainer(childExpr)]
 
-  params.dependencies.ReactMarkdown = {
+  params.dependencies.Markdown = {
     type: 'package',
-    path: 'react-markdown',
-    version: '^8.0.7',
+    path: 'markdown-to-jsx',
+    version: '7.7.12',
   }
 }
 
-const cleanupMarkdownMappingDependencies = (params: JSXGenerationParams) => {
-  Object.keys(params.dependencies).forEach((key) => {
-    if (params.dependencies[key]?.path?.includes('markdown-to-jsx')) {
-      delete params.dependencies[key]
-    }
-  })
-}
-
 /**
  * Handles raw attributes on a rich-text-editor-node element.
  *

package/src/utils/url-search-param-sync.ts

@@ -0,0 +1,286 @@
+import * as types from '@babel/types'
+
+// Shared builders for two-way `<state> ⇄ ?key=` URL search-param syncing.
+//
+// Used by BOTH:
+//   • `createNextUrlSearchParamsPlugin` (teleport-project-generator-next) for
+//     page/component state defs that declare `urlSearchParamBinding` — e.g.
+//     the products-list `selectedCategory` / `sortBy` dropdowns.
+//   • `createNextArrayMapperPaginationPlugin` (teleport-plugin-next-data-source)
+//     for the products-list search input, whose query lives in a
+//     pagination-managed state (`ds_N_searchQuery` / `ds_N_state.debouncedQuery`)
+//     rather than a UIDL state def, so it cannot ride the plugin above.
+//
+// Both emit the SAME loop-free read-back / write-back effect shapes, so the
+// builders live here to keep the two call sites byte-identical and the
+// loop-prevention reasoning in one place.
+
+// Strict JS identifier (Latin only is fine: UIDL URL keys are limited to the
+// subset Next.js supports as a query param key, which the GUI guarantees to
+// be at minimum URL-safe; but the *generated* code must be valid JS, and
+// `__nextQuery.foo-bar` parses as a subtraction). Anything off-pattern goes
+// through bracket notation: `__nextQuery['foo-bar']`.
+const VALID_JS_IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+
+// `object.<paramKey>` for identifier-safe keys, `object['param-key']` otherwise,
+// so the emitted code is always valid JS regardless of the URL key shape.
+const accessKeyOf = (object: types.Expression, paramKey: string): types.MemberExpression => {
+  if (VALID_JS_IDENTIFIER.test(paramKey)) {
+    return types.memberExpression(object, types.identifier(paramKey))
+  }
+  return types.memberExpression(object, types.stringLiteral(paramKey), true)
+}
+
+const routerQueryAccess = (paramKey: string): types.MemberExpression =>
+  accessKeyOf(
+    types.memberExpression(types.identifier('router'), types.identifier('query')),
+    paramKey
+  )
+
+// Clones an expression so it can be slotted into multiple positions of the
+// emitted AST — Babel does not support sharing the same node reference across
+// the tree, and callers pass arbitrary value/dependency expressions.
+const clone = (expr: types.Expression): types.Expression =>
+  types.cloneNode(expr, /* deep */ true) as types.Expression
+
+// Builds the state→URL write-back useEffect. Emitted shape (for a value of
+// `selectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (typeof window === 'undefined') return
+//     if (!router.isReady) return
+//     const __nextQuery = { ...router.query }
+//     if (selectedCategory === '' || selectedCategory == null) {
+//       delete __nextQuery.categoryFilter
+//     } else {
+//       __nextQuery.categoryFilter = String(selectedCategory)
+//     }
+//     if (__nextQuery.categoryFilter === router.query.categoryFilter) return
+//     router.replace(
+//       { pathname: router.pathname, query: __nextQuery },
+//       undefined,
+//       { shallow: true }
+//     )
+//   }, [selectedCategory, router.isReady])
+//
+// `valueExpr` is the expression read each render and pushed to the URL (a bare
+// state identifier for dropdowns, `ds_N_state.debouncedQuery` for the search
+// input). `depExpr` is the effect dependency that re-triggers the write-back
+// when that value changes — usually the same expression as `valueExpr`.
+//
+// Notes:
+// 1. `router.isReady` gate: on the very first SSG render `router.query` is
+//    empty, so without this gate any value initialized from
+//    `window.location.search` would immediately `router.replace` itself with
+//    the same value, racing with Next's own hydration. `router.isReady` is
+//    also in the deps array — once it flips to true, the effect re-runs with
+//    the now-hydrated `router.query` and decides correctly whether to replace.
+// 2. The equality check after building `__nextQuery` short-circuits replaces
+//    that would not change the URL — important when the user re-enters the
+//    same value, when the value mounts equal to the URL, and when the
+//    read-back effect fires its setter with the value just pushed.
+// 3. `shallow: true` keeps `getStaticProps` from re-running just because the
+//    URL bar changed; the data-source `useMemo` reacts to the state, not the
+//    URL.
+// 4. Empty / null value deletes the key entirely so the URL never keeps a
+//    sticky `?key=` empty param.
+export const buildUrlWriteBackEffect = (
+  paramKey: string,
+  valueExpr: types.Expression,
+  depExpr: types.Expression
+): types.ExpressionStatement => {
+  const effectBody = types.blockStatement([
+    // if (typeof window === 'undefined') return
+    types.ifStatement(
+      types.binaryExpression(
+        '===',
+        types.unaryExpression('typeof', types.identifier('window')),
+        types.stringLiteral('undefined')
+      ),
+      types.returnStatement(null)
+    ),
+    // if (!router.isReady) return
+    types.ifStatement(
+      types.unaryExpression(
+        '!',
+        types.memberExpression(types.identifier('router'), types.identifier('isReady'))
+      ),
+      types.returnStatement(null)
+    ),
+    // const __nextQuery = { ...router.query }
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier('__nextQuery'),
+        types.objectExpression([
+          types.spreadElement(
+            types.memberExpression(types.identifier('router'), types.identifier('query'))
+          ),
+        ])
+      ),
+    ]),
+    // if (value === '' || value == null) { delete __nextQuery.key }
+    // else { __nextQuery.key = String(value) }
+    types.ifStatement(
+      types.logicalExpression(
+        '||',
+        types.binaryExpression('===', clone(valueExpr), types.stringLiteral('')),
+        types.binaryExpression('==', clone(valueExpr), types.nullLiteral())
+      ),
+      types.blockStatement([
+        types.expressionStatement(
+          types.unaryExpression(
+            'delete',
+            accessKeyOf(types.identifier('__nextQuery'), paramKey)
+          ) as unknown as types.Expression
+        ),
+      ]),
+      types.blockStatement([
+        types.expressionStatement(
+          types.assignmentExpression(
+            '=',
+            accessKeyOf(types.identifier('__nextQuery'), paramKey),
+            types.callExpression(types.identifier('String'), [clone(valueExpr)])
+          )
+        ),
+      ])
+    ),
+    // if (__nextQuery.key === router.query.key) return
+    types.ifStatement(
+      types.binaryExpression(
+        '===',
+        accessKeyOf(types.identifier('__nextQuery'), paramKey),
+        routerQueryAccess(paramKey)
+      ),
+      types.returnStatement(null)
+    ),
+    // router.replace({ pathname: router.pathname, query: __nextQuery }, undefined, { shallow: true })
+    types.expressionStatement(
+      types.callExpression(
+        types.memberExpression(types.identifier('router'), types.identifier('replace')),
+        [
+          types.objectExpression([
+            types.objectProperty(
+              types.identifier('pathname'),
+              types.memberExpression(types.identifier('router'), types.identifier('pathname'))
+            ),
+            types.objectProperty(types.identifier('query'), types.identifier('__nextQuery')),
+          ]),
+          types.identifier('undefined'),
+          types.objectExpression([
+            types.objectProperty(types.identifier('shallow'), types.booleanLiteral(true)),
+          ]),
+        ]
+      )
+    ),
+  ])
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], effectBody),
+      types.arrayExpression([
+        clone(depExpr),
+        types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+      ]),
+    ])
+  )
+}
+
+// Builds the URL→state read-back useEffect. Emitted shape (for setter
+// `setSelectedCategory` bound to URL key `categoryFilter`):
+//
+//   useEffect(() => {
+//     if (!router.isReady) return
+//     const __urlValue = router.query.categoryFilter
+//     const __nextValue =
+//       typeof __urlValue === 'string' ? __urlValue : Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+//     setSelectedCategory((prev) => (prev === __nextValue ? prev : __nextValue))
+//   }, [router.query.categoryFilter, router.isReady])
+//
+// Why pair this with the write-back effect:
+// - On `<Link>` / `router.push` shallow navigations that land on the same path
+//   with a different query (or browser back/forward, which can change the query
+//   without remounting the page), `router.query` updates but the state hook does
+//   not. Without this effect, the control would be stuck on whatever the user
+//   last picked even though the URL has moved on.
+// - The functional `setState((prev) => prev === next ? prev : next)` form
+//   guarantees React bails out when the URL value matches state, which prevents
+//   an infinite write-back ↔ read-back loop: when the user picks a new value,
+//   state→URL fires once, URL→state observes the matching value and returns
+//   `prev`, so React does not re-render or fire any deps.
+// - `router.query[key]` can be either `string` (single value) or `string[]`
+//   (duplicate keys) per Next.js's typings; the helper normalizes both to a
+//   string before comparing, defaulting to `''` for the missing-key case so the
+//   comparison aligns with the write-back's `value === ''` empty-check.
+export const buildUrlReadBackEffect = (
+  paramKey: string,
+  setterName: string
+): types.ExpressionStatement => {
+  const normalizeArg = types.conditionalExpression(
+    // typeof __urlValue === 'string' ? __urlValue
+    types.binaryExpression(
+      '===',
+      types.unaryExpression('typeof', types.identifier('__urlValue')),
+      types.stringLiteral('string')
+    ),
+    types.identifier('__urlValue'),
+    types.conditionalExpression(
+      // Array.isArray(__urlValue) ? (__urlValue[0] || '') : ''
+      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('')
+    )
+  )
+
+  const effectBody = types.blockStatement([
+    // if (!router.isReady) return
+    types.ifStatement(
+      types.unaryExpression(
+        '!',
+        types.memberExpression(types.identifier('router'), types.identifier('isReady'))
+      ),
+      types.returnStatement(null)
+    ),
+    // const __urlValue = router.query.<paramKey>
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__urlValue'), routerQueryAccess(paramKey)),
+    ]),
+    // const __nextValue = (normalized)
+    types.variableDeclaration('const', [
+      types.variableDeclarator(types.identifier('__nextValue'), normalizeArg),
+    ]),
+    // setState((prev) => prev === __nextValue ? prev : __nextValue)
+    types.expressionStatement(
+      types.callExpression(types.identifier(setterName), [
+        types.arrowFunctionExpression(
+          [types.identifier('prev')],
+          types.conditionalExpression(
+            types.binaryExpression(
+              '===',
+              types.identifier('prev'),
+              types.identifier('__nextValue')
+            ),
+            types.identifier('prev'),
+            types.identifier('__nextValue')
+          )
+        ),
+      ])
+    ),
+  ])
+
+  return types.expressionStatement(
+    types.callExpression(types.identifier('useEffect'), [
+      types.arrowFunctionExpression([], effectBody),
+      types.arrayExpression([
+        routerQueryAccess(paramKey),
+        types.memberExpression(types.identifier('router'), types.identifier('isReady')),
+      ]),
+    ])
+  )
+}