Allow adding query params to the @webframe.navigate action (#4569)

.changeset/webframe-navigate-query.md

@@ -0,0 +1,6 @@
+---
+"gitbook": patch
+"@gitbook/react-contentkit": patch
+---
+
+Support query params in the `@webframe.navigate` action.

packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx

@@ -12,6 +12,9 @@ import { type GitBookLinker, createLinker } from '@/lib/links';
 
 type ContentKitProps<RenderContext> = React.ComponentProps<typeof ContentKit<RenderContext>>;
 
+// Query params a webframe may set when navigating: the search/ask widget params (see `useSearch`).
+const ALLOWED_NAVIGATE_QUERY_PARAMS = ['q', 'ask', 'scope', 'section'];
+
 /** Serializable inputs to rebuild the tested linker on the client (functions can't cross the RSC boundary). */
 export type WebframeLinkerData = Pick<
     Parameters<typeof createLinker>[0],
@@ -62,11 +65,17 @@ export function ContentKitWithClientContext<RenderContext>(
                 ? () => ({ visitor: visitorClaims?.visitor ?? null })
                 : undefined,
             getPageContext: page ? () => ({ page }) : undefined,
-            navigate: ({ path, anchor }) => {
+            navigate: ({ path, anchor, query }) => {
                 // Resolve the requested path relative to the site root so a webframe can navigate
                 // to any section or space within the site (and nowhere outside it).
-                const suffix = anchor ? `#${anchor}` : '';
+                const params = new URLSearchParams(
-                navigateTo(linker.toPathInSite(path) + suffix);
+                    Object.entries(query ?? {}).filter(([key]) =>
+                        ALLOWED_NAVIGATE_QUERY_PARAMS.includes(key)
+                    )
+                ).toString();
+                const search = params ? `?${params}` : '';
+                const hash = anchor ? `#${anchor}` : '';
+                navigateTo(linker.toPathInSite(path) + search + hash);
             },
         }),
         [canAccessVisitorClaims, visitorClaims, page, linker, navigateTo]

packages/react-contentkit/src/ElementWebframe.tsx

@@ -138,6 +138,7 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
                                     typeof message.action.anchor === 'string'
                                         ? message.action.anchor
                                         : undefined,
+                                query: message.action.query,
                             });
                         }
                         break;

packages/react-contentkit/src/context.ts

@@ -53,7 +53,7 @@ export type ContentKitClientContextData = {
      * action. The destination is addressed by `path` (resolved against the site base path); the
      * host restricts navigation to destinations within the current site.
      */
-    navigate?: (target: { path: string; anchor?: string }) => void;
+    navigate?: (target: { path: string; anchor?: string; query?: Record<string, string> }) => void;
 };
 
 export interface ContentKitClientContextType {