Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
5.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Guards the docsite's query-driven PPR boundaries and global footer.
 * @input Reads the relevant docsite source files
 * @output Invariants for narrow Suspense boundaries, shaped visible fallbacks,
 *   invisible URL synchronizers, and CSS-driven footer responsiveness
 * @position Cross-cutting meta-test; no runtime behavior of its own
 *
 * The docsite runs with `cacheComponents: true` (Partial Prerendering).
 * Request state such as `searchParams` is valid, but everything up to its
 * nearest Suspense boundary becomes a PPR hole. The component detail page,
 * templates gallery, and theme explorer deliberately keep their deep-link
 * behavior; these tests keep visible content outside the query-dependent hole
 * or reserve a shaped fallback. An invisible URL synchronizer may render no
 * fallback because it owns no layout. The global footer must be CSS-responsive
 * because a JavaScript media query cannot know the viewport during prerendering.
 */

import {describe, it, expect} from 'vitest';
import {readFileSync} from 'node:fs';
import {join} from 'node:path';

const SRC_DIR = join(__dirname, '..');

function source(path: string): string {
  return readFileSync(join(SRC_DIR, path), 'utf8');
}

describe('docsite static shell', () => {
  it('keeps the component heading outside the query-dependent boundary', () => {
    const detail = source(
      'components/component-detail/ComponentDetailClient.tsx',
    );

    expect(detail).toContain('const searchParams = useSearchParams()');
    expect(detail).toContain(
      'fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}',
    );
    expect(detail).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
    expect(detail.indexOf('<Text type="display-1">')).toBeLessThan(
      detail.indexOf('<Suspense'),
    );
  });

  it('keeps the templates gallery outside its URL sync boundary', () => {
    const templates = source('app/(site)/templates/page.tsx');
    const galleryStart = templates.indexOf('function TemplatesGallery()');
    const heading = templates.indexOf('<Heading level={1}', galleryStart);
    const grid = templates.indexOf('<Grid', heading);
    const boundary = templates.indexOf(
      '<Suspense fallback={null}>',
      galleryStart,
    );
    const boundaryEnd = templates.indexOf('</Suspense>', boundary);
    const boundarySource = templates.slice(boundary, boundaryEnd);

    expect(templates).toContain('function TemplatePreviewURLSync');
    expect(templates).toContain('const searchParams = useSearchParams()');
    expect(templates).toContain('return <TemplatesGallery />;');
    expect(heading).toBeGreaterThan(galleryStart);
    expect(grid).toBeGreaterThan(heading);
    expect(boundary).toBeGreaterThan(grid);
    expect(boundarySource).toContain('<TemplatePreviewURLSync');
    expect(boundarySource).not.toContain('<TemplatesGallery');
  });

  it('reuses the same theme heading in fallback and resolved layouts', () => {
    const themes = source('app/(site)/themes/page.tsx');
    const themePage = source('components/ThemePackagePage.tsx');
    const heading = source('components/ThemeHeading.tsx');
    const layout = source('components/ThemeExplorerLayout.tsx');

    expect(themes).toContain('const params = await searchParams');
    expect(themes).toContain('fallback={<ThemeExplorerFallback />}');
    expect(themes).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
    expect(themePage).toContain("import {ThemeHeading} from './ThemeHeading'");
    expect(themes).toContain(
      "import {ThemeHeading} from '../../../components/ThemeHeading'",
    );
    for (const component of [
      'ThemeExplorerLayout',
      'ThemeExplorerSidebar',
      'ThemeExplorerSidebarSurface',
      'ThemeExplorerSidebarContent',
      'ThemeExplorerActions',
      'ThemeExplorerRightColumn',
      'ThemeExplorerMobileContext',
      'ThemeExplorerMobileCarousel',
      'ThemeExplorerMobileCarouselItem',
      'ThemeExplorerPreview',
    ]) {
      expect(themePage).toContain(`<${component}`);
      expect(themes).toContain(`<${component}`);
    }
    expect(themePage.match(/<ThemeHeading/g)).toHaveLength(2);
    expect(themes.match(/<ThemeHeading/g)).toHaveLength(2);
    expect(themePage).toContain('<ThemeExplorerLayout>');
    expect(themes).toContain(
      '<ThemeExplorerLayout statusLabel="Loading theme explorer">',
    );
    expect(layout).toContain('inert={statusLabel ? true : undefined}');
    expect(layout).toContain('<VisuallyHidden as="div" role="status">');
    expect(themePage).not.toContain('useMediaQuery');
    expect(themePage).toContain('isMobile\n            mode={mode}');
    expect(heading).toContain('<Skeleton width={36} height={36}');
    expect(heading).toContain('tabIndex={isLoading ? -1 : undefined}');
    expect(heading).toContain('Astryx comes with a default theme built in');
    expect(heading).toContain('Learn how theming works');
  });

  it('the site footer does not branch on a media query', () => {
    // SiteFooter renders on every route, docs and marketing alike, so it is
    // part of the static shell at every width. Its responsive layout has to be
    // CSS (see the MOBILE media query in SiteFooter.tsx), because a JS branch
    // can only ever prerender one of the two arms.
    const footer = source('components/SiteFooter.tsx');
    expect(footer).not.toMatch(
      /import[^;]*(?:useAppShellMobile|useMediaQuery)[^;]*from/,
    );
  });
});