Skip to content

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

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

/**
 * Unit tests for the font-loading warning helpers behind `astryx theme build`
 * (#5015). `collectUnloadedFonts()` reads a RESOLVED theme — `--font-family-*`
 * tokens plus component-override `fontFamily` values (typography configs are
 * already collapsed into tokens by the time the build sees the theme) — and
 * returns the families the theme names but nothing loads. CSS generics,
 * CSS-wide keywords, `var()` references, and known preinstalled system
 * families are treated as loaded; anything unrecognized is assumed to be a
 * webfont, because a missed warning is worse than a spurious one.
 * `formatFontLoadingHelp()` renders the human snippet (<link> pair +
 * @font-face) printed after the install instructions.
 */

import {describe, it, expect} from 'vitest';
import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';
import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';

describe('collectUnloadedFonts', () => {
  it('returns webfont families from font-family tokens, skipping known fallbacks', () => {
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-body': '"Fraunces", Georgia, serif'},
      }),
    ).toEqual(['Fraunces']);
  });

  it('returns nothing for the default system stacks', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body':
            '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
          '--font-family-code': '"SF Mono", Monaco, Consolas, monospace',
        },
      }),
    ).toEqual([]);
  });

  it('treats bare system keywords like ui-monospace as loaded', () => {
    expect(
      collectUnloadedFonts({tokens: {'--font-family-code': 'ui-monospace'}}),
    ).toEqual([]);
  });

  it('handles single-quoted and unquoted multi-word family names', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body': "'JetBrains Mono', monospace",
          '--font-family-heading': 'Space Grotesk, sans-serif',
        },
      }),
    ).toEqual(['JetBrains Mono', 'Space Grotesk']);
  });

  it('dedupes case-insensitively across roles, keeping the first casing', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body': '"Space Grotesk", sans-serif',
          '--font-family-heading': '"space grotesk", serif',
        },
      }),
    ).toEqual(['Space Grotesk']);
  });

  it('skips var() references and CSS-wide keywords', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-heading': 'var(--font-family-body)',
          '--font-family-code': 'inherit',
        },
      }),
    ).toEqual([]);
  });

  it("strips whole var() calls — fallback arguments are not this theme's declarations", () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body': 'var(--x, "Web Font")',
          '--font-family-heading': 'var(--x, "Web Font", serif)',
        },
      }),
    ).toEqual([]);
    // Families outside the var() call still count.
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-code': 'var(--x), Bungee'},
      }),
    ).toEqual(['Bungee']);
  });

  it('keeps a comma inside a quoted name whole, even mid-list', () => {
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-body': 'Georgia, "Foo, Bar", serif'},
      }),
    ).toEqual(['Foo, Bar']);
  });

  it('ignores an empty font-family token', () => {
    expect(collectUnloadedFonts({tokens: {'--font-family-body': ''}})).toEqual(
      [],
    );
  });

  it('collects component-override fontFamily values, any style key', () => {
    expect(
      collectUnloadedFonts({
        components: {
          Button: {base: {fontFamily: '"Orbitron", sans-serif'}},
          Card: {'variant:hero': {fontFamily: 'Bungee'}},
        },
      }),
    ).toEqual(['Orbitron', 'Bungee']);
  });

  it('collects families from serialized adaptation typography', () => {
    expect(
      collectUnloadedFonts({
        typography: {
          body: {family: 'Revision Webfont', fallbacks: 'sans-serif'},
          heading: {family: 'Display Face', fallbacks: 'Georgia, serif'},
        },
      }),
    ).toEqual(['Revision Webfont', 'Display Face']);
  });

  it('ignores serialized fallbacks that have no family', () => {
    expect(
      collectUnloadedFonts({
        typography: {
          body: {fallbacks: 'Phantom Serif'},
          heading: {family: 'Display Face', fallbacks: 'Georgia, serif'},
        },
      }),
    ).toEqual(['Display Face']);
  });

  it('matches known system families case-insensitively', () => {
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-body': 'arial, sans-serif'},
      }),
    ).toEqual([]);
  });

  it('returns nothing for a theme with no tokens or components', () => {
    expect(collectUnloadedFonts({})).toEqual([]);
  });

  it('returns nothing for a null or undefined resolved theme', () => {
    // Older build.mjs consumers guard with `resolvedTheme || themeDef` — if
    // a path ever hands the collector nothing, it must shrug, not throw.
    expect(collectUnloadedFonts(null)).toEqual([]);
    expect(collectUnloadedFonts(undefined)).toEqual([]);
  });

  it('ignores non-string values without throwing: numeric or object-valued', () => {
    // The generator only allows object values under ':pseudo' keys, so an
    // object-valued fontFamily is not a family declaration — skip, not crash.
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-body': 42},
        components: {
          button: {base: {fontFamily: 700}},
          card: {base: {fontFamily: {default: '"Sneaky"'}}},
        },
      }),
    ).toEqual([]);
  });

  it('collects fontFamily nested under a pseudo-class block', () => {
    // generateThemeRules accepts {':hover': {fontFamily}} inside a style
    // key — a family named only there must still warn.
    expect(
      collectUnloadedFonts({
        components: {
          button: {base: {':hover': {fontFamily: '"Rubik Doodle", cursive'}}},
        },
      }),
    ).toEqual(['Rubik Doodle']);
  });

  it('strips a var() whose fallback list contains another var()', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body': 'var(--brand, var(--fallback), "Web Font")',
        },
      }),
    ).toEqual([]);
    // …and still keeps a family declared outside the nested call.
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-code': 'var(--a, var(--b, serif)), Bungee'},
      }),
    ).toEqual(['Bungee']);
  });

  it('matches generic keywords case-insensitively', () => {
    expect(
      collectUnloadedFonts({
        tokens: {
          '--font-family-body': 'Sans-Serif',
          '--font-family-heading': 'SERIF',
          '--font-family-code': 'Ui-Monospace',
        },
      }),
    ).toEqual([]);
  });

  it('collapses newlines and whitespace runs inside a family name', () => {
    // Template-literal theme sources wrap long stacks across lines.
    expect(
      collectUnloadedFonts({
        tokens: {'--font-family-body': '"Space\n      Grotesk",\n  serif'},
      }),
    ).toEqual(['Space Grotesk']);
  });
});

describe('formatFontLoadingHelp', () => {
  const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);

  it('names the theme and every family in the headline', () => {
    expect(help).toContain('[note] Theme "ocean"');
    expect(help).toContain('"Fraunces"');
    expect(help).toContain('"JetBrains Mono"');
  });

  it('is plain ASCII', () => {
    expect(help).not.toMatch(/[\u0080-\uffff]/);
  });

  it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
    expect(help).toContain(
      '<link rel="preconnect" href="https://fonts.googleapis.com"',
    );
    expect(help).toContain('https://fonts.gstatic.com');
    // The whole href, so a malformed URL cannot hide behind fragment checks.
    expect(help).toContain(
      'href="https://fonts.googleapis.com/css2?family=Fraunces&family=JetBrains+Mono&display=swap"',
    );
  });

  it('includes a self-hosted @font-face alternative with font-display: swap', () => {
    expect(help).toContain('@font-face');
    expect(help).toContain('font-family: "Fraunces"');
    expect(help).toContain('woff2');
    expect(help).toContain('font-display: swap');
  });

  it('points at the docs recipe', () => {
    expect(help).toContain(formatCliCommand('docs typography'));
  });

  it('percent-encodes family names in the css2 URL', () => {
    const spiced = formatFontLoadingHelp('spice', ['P&Co Sans', 'Sömething']);
    expect(spiced).toContain(
      'href="https://fonts.googleapis.com/css2?family=P%26Co+Sans&family=S%C3%B6mething&display=swap"',
    );
  });
});