Merge branch 'main' into taran/generic-alternates

Author: taranvohra

packages/gitbook/e2e/internal.spec.ts

@@ -338,6 +338,37 @@ const testCases: TestsCase[] = [
                     ).toBeVisible();
                 },
             },
+            {
+                name: 'Switch variant with alternate link in metadata',
+                url: 'rfcs',
+                run: async (page) => {
+                    const spaceDropdown = page
+                        .locator('[data-testid="space-dropdown-button"]')
+                        .locator('visible=true');
+                    await spaceDropdown.click();
+
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
+
+                    // Click the variant space called 'Multi-Variants' for which
+                    // there is an alternate link in the current (RFC variant) page metadata
+                    await variantSelectionDropdown
+                        .getByRole('menuitem', {
+                            name: 'Multi-Variants',
+                        })
+                        .click();
+
+                    // It should navigate to the alternate link defined in the metadata (a completely different page)
+                    await page.waitForURL((url) =>
+                        url.pathname.includes('multi-variants/reference/api-reference/pets')
+                    );
+                    // Verify we are on the correct page by checking the h1
+                    await expect(
+                        page.getByRole('heading', { level: 1, name: 'Pets' })
+                    ).toBeVisible();
+                },
+            },
         ],
     },
     {

packages/gitbook/src/components/Header/SpacesDropdown.tsx

@@ -45,11 +45,12 @@ export function SpacesDropdown(props: {
             }
         >
             <SpacesDropdownMenuItems
-                slimSpaces={siteSpaces.map((space) => ({
-                    id: space.id,
-                    title: space.title,
-                    url: getSiteSpaceURL(context, space),
-                    isActive: space.id === siteSpace.id,
+                slimSpaces={siteSpaces.map((siteSp) => ({
+                    id: siteSp.id,
+                    title: siteSp.title,
+                    url: getSiteSpaceURL(context, siteSp),
+                    isActive: siteSp.id === siteSpace.id,
+                    spaceId: siteSp.space.id,
                 }))}
                 curPath={siteSpace.path}
             />

packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx

@@ -1,26 +1,39 @@
 'use client';
 
-import type { Space } from '@gitbook/api';
-
 import { joinPath } from '@/lib/paths';
-import { useCurrentPagePath } from '../hooks';
+import { useCurrentPageMetadata, useCurrentPagePath } from '../hooks';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 
 interface VariantSpace {
-    id: Space['id'];
-    title: Space['title'];
+    id: string;
+    title: string;
     url: string;
     isActive: boolean;
+    spaceId: string;
 }
 
-// When switching to a different variant space, we reconstruct the URL by swapping the space path.
-function useVariantSpaceHref(variantSpaceUrl: string, currentSpacePath: string, active = false) {
+/**
+ * Return the href for a variant space, taking into account the current page path and metadata.
+ */
+function useVariantSpaceHref(variantSpace: VariantSpace, currentSpacePath: string, active = false) {
     const currentPathname = useCurrentPagePath();
+    const { metaLinks } = useCurrentPageMetadata();
+
+    // We first check if there is an alternate link for the variant space in the current page metadata.
+    const pageHasAlternateForVariant = metaLinks?.alternates.find(
+        (alt) => alt.space?.id === variantSpace.spaceId
+    );
+    if (pageHasAlternateForVariant) {
+        return pageHasAlternateForVariant.href;
+    }
+
+    // If there is no alternate link, we reconstruct the URL by swapping the space path.
 
     // We need to ensure that the variant space URL is not the same as the current space path.
     // If it is, we return only the variant space URL to redirect to the root of the variant space.
     // This is necessary in case the currentPathname is the same as the variantSpaceUrl,
     // otherwise we would redirect to the same space if the variant space that we are switching to is the default one.
+    const variantSpaceUrl = variantSpace.url;
     if (!active && currentPathname.startsWith(`${currentSpacePath}/`)) {
         return variantSpaceUrl;
     }
@@ -44,7 +57,7 @@ export function SpacesDropdownMenuItem(props: {
     currentSpacePath: string;
 }) {
     const { variantSpace, active, currentSpacePath } = props;
-    const variantHref = useVariantSpaceHref(variantSpace.url, currentSpacePath, active);
+    const variantHref = useVariantSpaceHref(variantSpace, currentSpacePath, active);
 
     return (
         <DropdownMenuItem key={variantSpace.id} href={variantHref} active={active}>

packages/gitbook/src/components/SitePage/PageClientLayout.tsx

@@ -3,16 +3,26 @@
 import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React from 'react';
 
-import { useScrollPage } from '@/components/hooks';
+import { currentPageMetadataStore, useScrollPage } from '@/components/hooks';
+import type { PageMetaLinks } from './SitePage';
 
 /**
  * Client component to initialize interactivity for a page.
  */
-export function PageClientLayout() {
+export function PageClientLayout({
+    pageMetaLinks,
+}: {
+    pageMetaLinks: PageMetaLinks | null;
+}) {
     // We use this hook in the page layout to ensure the elements for the blocks
     // are rendered before we scroll to a hash or to the top of the page
     useScrollPage();
 
+    // The page metadata such as meta links are generated on the server side,
+    // but need to be registered on the client side in other parts of the layout
+    // such as the SpaceDropdown.
+    useRegisterPageMetadata({ pageMetaLinks });
+
     useStripFallbackQueryParam();
     return null;
 }
@@ -38,3 +48,15 @@ function useStripFallbackQueryParam() {
         }
     }, [router, pathname, searchParams]);
 }
+
+/**
+ * Register the generated page metadata such as meta links for the current page.
+ */
+function useRegisterPageMetadata(metadata: {
+    pageMetaLinks: PageMetaLinks | null;
+}) {
+    const { pageMetaLinks } = metadata;
+    React.useEffect(() => {
+        currentPageMetadataStore.setState({ metaLinks: pageMetaLinks });
+    }, [pageMetaLinks]);
+}

packages/gitbook/src/components/SitePage/SitePage.tsx

@@ -26,6 +26,28 @@ export type SitePageProps = {
     pageParams: PagePathParams;
 };
 
+type AlternateLinkSpace = {
+    id: string;
+    language: TranslationLanguage | undefined;
+};
+
+export type PageMetaLinks = {
+    /**
+     * The canonical URL for the page, if any.
+     */
+    canonical: string | null;
+    /**
+     * The alternate URLs for the page, if any.
+     */
+    alternates: Array<{
+        href: string;
+        /**
+         * Space the alternate link points to, if any.
+         */
+        space: AlternateLinkSpace | null;
+    }>;
+};
+
 /**
  * Fetch and render a page.
  */
@@ -39,6 +61,7 @@ export async function SitePage(props: SitePageProps) {
         withPageFeedback,
         withSections,
         withTopHeader,
+        pageMetaLinks,
     } = await getSitePageData(props);
     const headerOffset = { sectionsHeader: withSections, topHeader: withTopHeader };
 
@@ -76,7 +99,7 @@ export async function SitePage(props: SitePageProps) {
                         insightsDisplayContext={SiteInsightsDisplayContext.Site}
                     />
                 </div>
-                <PageClientLayout />
+                <PageClientLayout pageMetaLinks={pageMetaLinks} />
             </div>
         </PageContextProvider>
     );
@@ -155,8 +178,8 @@ export async function generateSitePageMetadata(props: SitePageProps): Promise<Me
         }>;
     }>(
         (acc, alt) => {
-            if (alt.language) {
-                acc.languages[alt.language] = URL.canParse(alt.href)
+            if (alt.space?.language) {
+                acc.languages[alt.space.language] = URL.canParse(alt.href)
                     ? alt.href
                     : linker.toAbsoluteURL(alt.href);
             } else {
@@ -211,7 +234,7 @@ export async function generateSitePageMetadata(props: SitePageProps): Promise<Me
  * Fetches all the data required to render the site page.
  */
 export async function getSitePageData(props: SitePageProps) {
-    const { context, pageTarget } = await getPageDataWithFallback({
+    const { context, pageTarget, pageMetaLinks } = await getPageDataWithFallback({
         context: props.context,
         pagePathParams: props.pageParams,
     });
@@ -263,6 +286,7 @@ export async function getSitePageData(props: SitePageProps) {
         withPageFeedback,
         withFullPageCover,
         withTopHeader,
+        pageMetaLinks,
     };
 }
 
@@ -295,13 +319,7 @@ async function getPageDataWithFallback(args: {
 async function resolvePageMetaLinks(
     context: GitBookSiteContext,
     pageId: string
-): Promise<{
-    canonical: string | null;
-    alternates: Array<{
-        href: string;
-        language: TranslationLanguage | null;
-    }>;
-}> {
+): Promise<PageMetaLinks> {
     const pageMetaLinks = await getDataOrNull(
         context.dataFetcher.listRevisionPageMetaLinks({
             spaceId: context.space.id,
@@ -318,7 +336,9 @@ async function resolvePageMetaLinks(
         const alternatesResolutions = (pageMetaLinks.alternates || []).map((link) =>
             resolveContentRef(link, context).then((resolved) => ({
                 href: resolved?.href ?? null,
-                language: resolved?.space?.language ?? null,
+                space: resolved?.space
+                    ? { id: resolved.space.id, language: resolved.space.language }
+                    : null,
             }))
         );
 
@@ -330,7 +350,7 @@ async function resolvePageMetaLinks(
         return {
             canonical: resolvedCanonical ?? null,
             alternates: resolvedAlternates.filter(
-                (alt): alt is { href: string; language: TranslationLanguage | null } => !!alt.href
+                (alt): alt is { href: string; space: AlternateLinkSpace | null } => !!alt.href
             ),
         };
     }
@@ -344,8 +364,15 @@ async function resolvePageMetaLinks(
 /**
  * Determine whether to resolve meta links for a site based on a percentage rollout.
  */
-export function shouldResolveMetaLinks(siteId: string): boolean {
-    const META_LINKS_PERCENTAGE_ROLLOUT = 10;
+function shouldResolveMetaLinks(siteId: string): boolean {
+    const META_LINKS_PERCENTAGE_ROLLOUT = 25;
+    const ALLOWED_SITES: Record<string, boolean> = {
+        site_CZrtk: true,
+    };
+
+    if (ALLOWED_SITES[siteId] || process.env.NODE_ENV === 'development') {
+        return true;
+    }
 
     // compute a simple hash of the siteId
     let hash = 0;

packages/gitbook/src/components/hooks/index.ts

@@ -8,3 +8,4 @@ export * from './useCurrentContent';
 export * from './useCurrentPage';
 export * from './useNow';
 export * from './useListOverflow';
+export * from './useCurrentPageMetadata';

packages/gitbook/src/components/hooks/useCurrentPageMetadata.tsx

@@ -0,0 +1,26 @@
+'use client';
+import type { PageMetaLinks } from '../SitePage';
+
+import * as zustand from 'zustand';
+
+/**
+ * A store for the current page metadata.
+ *
+ * We use a global store because the metadata is generated and set by the Page component
+ * but needs to be accessed by other components (ex - Layout) that are not its descendants.
+ */
+export const currentPageMetadataStore = zustand.create<{
+    metaLinks: PageMetaLinks | null;
+}>(() => ({
+    metaLinks: null,
+}));
+
+/**
+ * Return the metadata for the current page.
+ */
+export function useCurrentPageMetadata() {
+    const metaLinks = zustand.useStore(currentPageMetadataStore, (state) => state.metaLinks);
+    return {
+        metaLinks,
+    };
+}