Skip to content

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

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

import {describe, expect, it} from 'vitest';
import {
  SIDEBAR_PARENTS,
  applySidebarParents,
  mergeFlatTopics,
  namespaceCategory,
  namespacePage,
  rootNamespacePages,
  sectionAnchors,
  withCliCommands,
} from '../../scripts/docs-pages.mjs';
import {buildOutline} from '../components/docs/docOutline';
import {
  docRedirects,
  docTopics,
  type DocSection,
} from '../generated/docsRegistry';

const section = (title: string, text = `${title} text.`) => ({
  title,
  content: [{type: 'prose', text}],
});

/** The flat topic as the site had it before the split. */
const widgetsBefore = {
  topic: 'widgets',
  title: 'Widgets',
  description: 'Pick and place widgets.',
  category: 'foundations',
  sections: [
    section('Overview'),
    section('Sizes'),
    section('Best Practices'),
    section('Theming'),
  ],
};

type Guide = {route: string; title: string; category: string | null};

/**
 * A docs reader shaped like the CLI docs API after `widgets` became a root
 * namespace of two guides: `docs(route)` reads one guide, and
 * `docs(route, undefined, {depth: 'all', detail: 'full'})` reads the
 * namespace with every guide's compiled sections.
 */
function splitReader(
  guides: Array<Guide & {sections: ReturnType<typeof section>[]}>,
) {
  return async (
    route?: string,
    _section?: string,
    options: {depth?: number | 'all'} = {},
  ) => {
    const guide = guides.find(g => g.route === route);
    if (guide) {
      return {
        type: 'docs.detail',
        data: {
          title: guide.title,
          category: guide.category,
          sections: guide.sections,
        },
      };
    }
    if (route === 'widgets' && options.depth === 'all') {
      return {
        type: 'docs.node',
        data: {
          route: 'widgets',
          kind: 'namespace',
          title: 'Widgets',
          summary: 'Pick and place widgets.',
          content: [],
          slots: [
            {
              name: 'guides',
              title: 'Guides',
              children: guides.map(g => ({
                route: g.route,
                kind: 'generic',
                title: g.title,
                sections: g.sections,
              })),
            },
          ],
        },
      };
    }
    throw new Error(`unexpected read ${route}`);
  };
}

describe('a flat topic split into a docs-tree namespace', () => {
  const guides = [
    {
      route: 'widgets/basics',
      title: 'Basics',
      category: 'foundations',
      sections: widgetsBefore.sections.slice(0, 2),
    },
    {
      route: 'widgets/advanced',
      title: 'Advanced',
      category: 'foundations',
      sections: widgetsBefore.sections.slice(2),
    },
  ];

  it('keeps one page at the old slug, in the same group, with the same sections', async () => {
    const result = await namespacePage(splitReader(guides), 'widgets');
    expect(result?.page).toEqual(widgetsBefore);
  });

  it('sends each guide slug to its section on that page', async () => {
    const result = await namespacePage(splitReader(guides), 'widgets');
    expect(result?.redirects).toEqual({
      'widgets-basics': '/docs/widgets#overview',
      'widgets-advanced': '/docs/widgets#best-practices',
    });
  });

  it('has no page for a level whose children are not placed under it', async () => {
    const read = async () => ({
      type: 'docs.node',
      data: {
        route: 'foundations',
        kind: 'namespace',
        title: 'Foundations',
        content: [],
        slots: [
          {
            name: 'topics',
            children: [{route: 'color', kind: 'generic', sections: []}],
          },
        ],
      },
    });
    expect(await namespacePage(read, 'foundations')).toBeNull();
  });
});

describe('a page for part of a namespace', () => {
  const nested = async (
    route?: string,
    _section?: string,
    options: {depth?: number | 'all'} = {},
  ) => {
    const guideNode = (r: string, title: string) => ({
      route: r,
      kind: 'generic',
      title,
      sections: [section(title)],
    });
    if (route === 'kit/guides' && options.depth === 'all') {
      return {
        type: 'docs.node',
        data: {
          route: 'kit/guides',
          kind: 'namespace',
          title: 'Guides',
          summary: 'Kit guides.',
          content: [],
          slots: [
            {
              name: 'guides',
              children: [
                guideNode('kit/guides/start', 'Start'),
                {
                  route: 'kit/guides/docs',
                  kind: 'namespace',
                  title: 'Docs',
                  content: [],
                  slots: [
                    {
                      name: 'guides',
                      children: [guideNode('kit/guides/docs/write', 'Write')],
                    },
                  ],
                },
              ],
            },
          ],
        },
      };
    }
    return {type: 'docs.detail', data: {category: 'guide', sections: []}};
  };

  it('takes its own slug and title, leaves out what another page holds, and redirects older slugs', async () => {
    const result = await namespacePage(nested, 'kit/guides', {
      slug: 'kit-guide',
      title: 'Kit Guide',
      except: ['kit/guides/docs'],
      aliases: ['kit-overview'],
    });
    expect(result?.page).toMatchObject({
      topic: 'kit-guide',
      title: 'Kit Guide',
      category: 'guide',
    });
    const page = result?.page as {sections: Array<{title: string}>};
    expect(page.sections.map(s => s.title)).toEqual(['Start']);
    expect(result?.redirects).toEqual({
      'kit-guides-start': '/docs/kit-guide#start',
      'kit-guides': '/docs/kit-guide',
      'kit-overview': '/docs/kit-guide',
    });
  });
});

describe('a nested namespace with a page of its own', () => {
  const guideNode = (route: string, title: string) => ({
    route,
    kind: 'generic',
    title,
    sections: [section(title)],
  });
  const extras = {
    route: 'kit/extras',
    kind: 'namespace',
    title: 'Extras',
    summary: 'Extra parts for the kit.',
    content: [{type: 'prose', text: 'Extras fit every kit.'}],
    slots: [
      {
        name: 'guides',
        children: [guideNode('kit/extras/fit', 'Fit an extra')],
      },
    ],
  };
  const reader = async (
    route?: string,
    _section?: string,
    options: {depth?: number | 'all'} = {},
  ) => {
    if (route === 'kit' && options.depth === 'all') {
      return {
        type: 'docs.node',
        data: {
          route: 'kit',
          kind: 'namespace',
          title: 'Kit',
          summary: 'Build the kit.',
          content: [],
          slots: [
            {
              name: 'guides',
              children: [guideNode('kit/start', 'Start'), extras],
            },
          ],
        },
      };
    }
    if (route === 'kit/extras' && options.depth === 'all') {
      return {type: 'docs.node', data: extras};
    }
    return {type: 'docs.detail', data: {category: 'guide', sections: []}};
  };
  const pages = () =>
    rootNamespacePages(reader, 'kit', {nested: ['kit/extras']});

  it('leaves the nested namespace off its root page', async () => {
    const {root} = await pages();
    const page = root?.page as {
      topic: string;
      sections: Array<{title: string}>;
    };
    expect(page.topic).toBe('kit');
    expect(page.sections.map(s => s.title)).toEqual(['Start']);
    expect(root?.redirects).toEqual({'kit-start': '/docs/kit#start'});
  });

  it('gives it a full page at its slug, under its root page', async () => {
    const {nested} = await pages();
    expect(nested).toHaveLength(1);
    const [extrasPage] = nested;
    expect(extrasPage.page).toMatchObject({
      topic: 'kit-extras',
      title: 'Extras',
      description: 'Extra parts for the kit.',
      category: 'guide',
      parent: 'kit',
    });
    const page = extrasPage.page as {sections: Array<{title: string}>};
    expect(page.sections.map(s => s.title)).toEqual([
      'Overview',
      'Fit an extra',
    ]);
    expect(extrasPage.redirects).toEqual({
      'kit-extras-fit': '/docs/kit-extras#fit-an-extra',
    });
  });

  it('keeps a root namespace with no nested page to one page', async () => {
    const {root, nested} = await rootNamespacePages(
      splitReader([
        {
          route: 'widgets/basics',
          title: 'Basics',
          category: 'foundations',
          sections: widgetsBefore.sections,
        },
      ]),
      'widgets',
    );
    expect(root?.page).toEqual(widgetsBefore);
    expect(nested).toEqual([]);
  });
});

describe('sidebar parents', () => {
  const pageAt = (topic: string, parent?: string) => ({
    topic,
    ...(parent ? {parent} : {}),
  });

  it('puts each named page under its parent and leaves the rest alone', () => {
    const pages = applySidebarParents(
      [pageAt('icons'), pageAt('icon-files'), pageAt('kit-extras', 'kit')],
      new Map([['icon-files', 'icons']]),
    );
    expect(pages).toEqual([
      pageAt('icons'),
      pageAt('icon-files', 'icons'),
      pageAt('kit-extras', 'kit'),
    ]);
  });

  it('fails the build on a missing page, a page under itself, or a second level', () => {
    expect(() =>
      applySidebarParents([pageAt('icons')], new Map([['gone', 'icons']])),
    ).toThrow(/gone/);
    expect(() =>
      applySidebarParents([pageAt('icons')], new Map([['icons', 'gone']])),
    ).toThrow(/gone/);
    expect(() =>
      applySidebarParents([pageAt('icons')], new Map([['icons', 'icons']])),
    ).toThrow(/two different pages/);
    expect(() =>
      applySidebarParents(
        [pageAt('a'), pageAt('b', 'a'), pageAt('c')],
        new Map([['c', 'b']]),
      ),
    ).toThrow(/itself under another page/);
  });

  it('places the site pages it names, at unchanged URLs', () => {
    for (const [child, parent] of SIDEBAR_PARENTS) {
      expect(docTopics.find(topic => topic.topic === child)?.parent).toBe(
        parent,
      );
      expect(docTopics.some(topic => topic.topic === parent)).toBe(true);
      expect(docRedirects).not.toHaveProperty(child);
    }
    expect(SIDEBAR_PARENTS.get('cli-experimental-icon-sets')).toBe('icons');
    expect(SIDEBAR_PARENTS.get('cli-experimental-icon-set-files')).toBe(
      'icons',
    );
    expect(SIDEBAR_PARENTS.get('styling')).toBe('styling-overview');
  });
});

describe('namespaceCategory', () => {
  it('prefers the namespace, then foundations only when every guide is', () => {
    expect(namespaceCategory('guide', ['foundations'])).toBe('guide');
    expect(namespaceCategory(null, ['foundations', 'foundations'])).toBe(
      'foundations',
    );
    expect(namespaceCategory(null, ['foundations', 'guide'])).toBe('guide');
    expect(namespaceCategory(null, [null])).toBe('guide');
  });
});

describe('mergeFlatTopics', () => {
  const flat = (topic: string, titles: string[]) => ({
    topic,
    title: topic,
    description: '',
    category: 'guide',
    sections: titles.map(t => section(t)),
  });

  it('shows the theme split on one theme page', () => {
    const {topics, redirects} = mergeFlatTopics([
      flat('theme', ['Wrap your app in a theme']),
      flat('use-a-theme', ['Wrap your app in a theme', 'Dark mode']),
      flat('author-a-theme', ['Custom themes']),
      flat('color', ['Overview']),
    ]);
    expect(topics.map(t => t.topic)).toEqual(['theme', 'color']);
    expect(topics[0].sections.map((s: {title: string}) => s.title)).toEqual([
      'Wrap your app in a theme',
      'Dark mode',
      'Custom themes',
    ]);
    expect(redirects).toEqual({
      'use-a-theme': '/docs/theme#wrap-your-app-in-a-theme',
      'author-a-theme': '/docs/theme#custom-themes',
    });
  });

  it('leaves the topics alone before the split', () => {
    const before = [flat('theme', ['Dark mode']), flat('tokens', ['Color'])];
    expect(mergeFlatTopics(before)).toEqual({topics: before, redirects: {}});
  });

  it('keeps token data off the site', () => {
    const {topics, redirects} = mergeFlatTopics([flat('token-tables', ['A'])]);
    expect(topics).toEqual([]);
    expect(redirects).toEqual({'token-tables': '/docs/tokens'});
  });
});

describe('sectionAnchors', () => {
  it('matches the page outline, repeats and heading blocks included', () => {
    const sections = [
      {
        title: 'Overview',
        content: [{type: 'heading', text: 'Overview'}],
      },
      section('Overview'),
      section('Best Practices'),
      section('Best practices'),
    ];
    expect(sectionAnchors(sections)).toEqual(
      buildOutline(sections as DocSection[]).sectionIds,
    );
  });
});

describe('CLI commands on docsite pages', () => {
  it('prefixes commands in prose, lists, tables and shell code only', () => {
    const show = (text: string, lang: string | null = null) =>
      lang === 'tsx' ? text : text.replaceAll('`astryx', '`npx astryx');
    const [shown] = withCliCommands(
      [
        {
          title: 'Run it',
          content: [
            {type: 'prose', text: 'Run `astryx docs`.'},
            {type: 'list', items: ['`astryx doctor`']},
            {type: 'table', rows: [['Neutral', 'astryx theme add neutral']]},
            {type: 'code', lang: 'tsx', code: '`astryx docs`'},
          ],
        },
      ],
      show,
      'npx astryx',
    );
    expect(shown.content).toEqual([
      {type: 'prose', text: 'Run `npx astryx docs`.'},
      {type: 'list', items: ['`npx astryx doctor`']},
      {type: 'table', rows: [['Neutral', 'npx astryx theme add neutral']]},
      {type: 'code', lang: 'tsx', code: '`astryx docs`'},
    ]);
  });

  it('shows the Authoring page a command that runs before any install', () => {
    const page = docTopics.find(topic => topic.topic === 'authoring');
    const section = page?.sections.find(
      each => each.title === 'Verify the packed import',
    );
    expect(section?.content).toContainEqual(
      expect.objectContaining({
        type: 'code',
        code: 'npx @astryxdesign/cli integration verify',
      }),
    );
  });
});