Ekklesia/packages/design-tokens/tests/theme.test.ts

import { describe, expect, it, vi } from "vitest";
import {
  createDesignTokenRegistry,
  createEkklesiaThemeController,
  DESIGN_TOKEN_APPEARANCE_ATTRIBUTE,
  DESIGN_TOKEN_MOTION_ATTRIBUTE,
  DesignTokenError,
  EKKLESIA_DARK_SCHEME_QUERY,
  EKKLESIA_REDUCED_MOTION_QUERY,
  type EkklesiaMediaQueryList,
  ekklesiaDesignTokens,
  ekklesiaDesignTokenStylesheet,
  parseEkklesiaAppearance,
  parseEkklesiaMotionPreference,
  resolveEkklesiaColorScheme,
  resolveEkklesiaReducedMotion,
} from "../src/index.js";

/** A media query a test can flip, as a running OS would. */
function mediaQuery(initial = false) {
  const listeners = new Set<() => void>();
  const query: EkklesiaMediaQueryList & { set(matches: boolean): void } = {
    addEventListener: (_type, listener) => listeners.add(listener),
    matches: initial,
    removeEventListener: (_type, listener) => listeners.delete(listener),
    set(matches) {
      (query as { matches: boolean }).matches = matches;
      for (const listener of [...listeners]) {
        listener();
      }
    },
  };
  return { listeners, query };
}

function environment(options: { dark?: boolean; reduced?: boolean } = {}) {
  const dark = mediaQuery(options.dark);
  const reduced = mediaQuery(options.reduced);
  const attributes = new Map<string, string>();
  const target = {
    setAttribute: vi.fn((name: string, value: string) => attributes.set(name, value)),
  };
  const matchMedia = (query: string) => {
    if (query === EKKLESIA_DARK_SCHEME_QUERY) {
      return dark.query;
    }
    if (query === EKKLESIA_REDUCED_MOTION_QUERY) {
      return reduced.query;
    }
    throw new Error(`unexpected query ${query}`);
  };
  return { attributes, dark, matchMedia, reduced, target };
}

const COLOUR_CATEGORIES = new Set(["background", "text", "accent", "status", "state"]);
const isColour = (value: string) => /^(?:#[0-9a-f]{6}|rgba\()/u.test(value);

describe("light and dark token sets", () => {
  it("gives every colour and shadow a dark value, so no semantic token is missing in either theme", () => {
    const colours = ekklesiaDesignTokens
      .list()
      .filter((token) => isColour(token.value) || token.category === "shadow");
    expect(colours.length).toBeGreaterThan(35);
    for (const token of colours) {
      if (token.name === "shadow.none") {
        continue;
      }
      expect(token.dark, token.name).toBeDefined();
      expect(token.dark, token.name).not.toBe(token.value);
    }
  });

  it("varies only colour, shadow, and border-colour tokens by scheme", () => {
    for (const token of ekklesiaDesignTokens.list()) {
      if (token.dark === undefined) {
        continue;
      }
      expect(
        COLOUR_CATEGORIES.has(token.category) ||
          token.category === "shadow" ||
          (token.category === "border" && isColour(token.value)),
        token.name,
      ).toBe(true);
    }
  });

  it("is a designed dark theme, not an inversion: no pure black or pure white surfaces or text", () => {
    for (const name of [
      "background.page",
      "background.canvas",
      "background.surface",
      "background.raised",
      "text.primary",
    ] as const) {
      expect(ekklesiaDesignTokens.valueFor(name, "dark"), name).not.toMatch(
        /^#(?:000000|ffffff)$/u,
      );
    }
  });

  it("answers a token's value per scheme, falling back to its single value", () => {
    expect(ekklesiaDesignTokens.valueFor("background.page", "light")).toBe("#f3f7f6");
    expect(ekklesiaDesignTokens.valueFor("background.page", "dark")).toBe("#0e1615");
    expect(ekklesiaDesignTokens.valueFor("spacing.md", "dark")).toBe("0.75rem");
    expect(() => ekklesiaDesignTokens.valueFor("nope" as "spacing.md", "dark")).toThrow(
      DesignTokenError,
    );
  });

  it("validates a dark or reduced value exactly like a default value", () => {
    for (const hostile of ["red; color: blue", "url(x)", "#fff !important", "a{b}"]) {
      expect(() =>
        createDesignTokenRegistry([
          { dark: hostile, description: "d", label: "l", name: "text.x", value: "#fff" },
        ]),
      ).toThrow(DesignTokenError);
      expect(() =>
        createDesignTokenRegistry([
          { description: "d", label: "l", name: "motion.x", reduced: hostile, value: "1s" },
        ]),
      ).toThrow(DesignTokenError);
    }
  });
});

describe("the theme stylesheet resolves appearance and motion in CSS", () => {
  const stylesheet = ekklesiaDesignTokenStylesheet();

  it("is deterministic", () => {
    expect(ekklesiaDesignTokenStylesheet()).toBe(stylesheet);
  });

  it("is light by default and says so to the browser", () => {
    expect(stylesheet.startsWith(":root {\n  color-scheme: light;\n")).toBe(true);
    expect(stylesheet).toContain("--ekklesia-background-page: #f3f7f6;");
  });

  it("follows the system into dark unless light was chosen, and goes dark when dark was chosen", () => {
    expect(stylesheet).toContain(
      `@media (prefers-color-scheme: dark) {\n:root:not([${DESIGN_TOKEN_APPEARANCE_ATTRIBUTE}="light"]) {\n  color-scheme: dark;\n`,
    );
    expect(stylesheet).toContain(
      `:root[${DESIGN_TOKEN_APPEARANCE_ATTRIBUTE}="dark"] {\n  color-scheme: dark;\n`,
    );
    const darkRule = stylesheet.slice(
      stylesheet.indexOf(`:root[${DESIGN_TOKEN_APPEARANCE_ATTRIBUTE}="dark"]`),
    );
    expect(darkRule).toContain("--ekklesia-background-page: #0e1615;");
  });

  it("zeroes every motion duration when the system asks, unless motion was allowed, and when reduce was chosen", () => {
    expect(stylesheet).toContain(
      `@media (prefers-reduced-motion: reduce) {\n:root:not([${DESIGN_TOKEN_MOTION_ATTRIBUTE}="allow"]) {\n  --ekklesia-motion-duration-short: 0ms;\n  --ekklesia-motion-duration-ambient: 0s;\n}\n}`,
    );
    expect(stylesheet).toContain(
      `:root[${DESIGN_TOKEN_MOTION_ATTRIBUTE}="reduce"] {\n  --ekklesia-motion-duration-short: 0ms;\n  --ekklesia-motion-duration-ambient: 0s;\n}`,
    );
    for (const token of ekklesiaDesignTokens.listByCategory("motion")) {
      expect(token.reduced, token.name).toMatch(/^0m?s$/u);
    }
  });

  it("uses the same rules on an isolated root's host element", () => {
    const host = ekklesiaDesignTokenStylesheet("host");
    expect(host.startsWith(":host {")).toBe(true);
    expect(host).toContain(`:host(:not([${DESIGN_TOKEN_APPEARANCE_ATTRIBUTE}="light"]))`);
    expect(host).toContain(`:host([${DESIGN_TOKEN_APPEARANCE_ATTRIBUTE}="dark"])`);
    expect(host).toContain(`:host([${DESIGN_TOKEN_MOTION_ATTRIBUTE}="reduce"])`);
  });
});

describe("radius", () => {
  it("scales the small, medium, and large radii from one multiplier, keeping today's values", () => {
    expect(ekklesiaDesignTokens.get("radius.scale")?.value).toBe("1");
    expect(ekklesiaDesignTokens.get("radius.sm")?.value).toBe(
      "calc(0.25rem * var(--ekklesia-radius-scale))",
    );
    expect(ekklesiaDesignTokens.get("radius.md")?.value).toBe(
      "calc(0.625rem * var(--ekklesia-radius-scale))",
    );
    expect(ekklesiaDesignTokens.get("radius.lg")?.value).toBe(
      "calc(0.875rem * var(--ekklesia-radius-scale))",
    );
    expect(ekklesiaDesignTokens.get("radius.pill")?.value).toBe("9999px");
    expect(ekklesiaDesignTokens.get("radius.none")?.value).toBe("0");
  });
});

describe("appearance and motion preferences", () => {
  it("default to system, and read untrusted values safely", () => {
    expect(parseEkklesiaAppearance(undefined)).toBe("system");
    expect(parseEkklesiaAppearance("dark")).toBe("dark");
    expect(parseEkklesiaAppearance("DARK")).toBe("system");
    expect(parseEkklesiaAppearance({})).toBe("system");
    expect(parseEkklesiaMotionPreference("allow")).toBe("allow");
    expect(parseEkklesiaMotionPreference("off")).toBe("system");
  });

  it("resolve to what is on screen", () => {
    expect(resolveEkklesiaColorScheme("system", false)).toBe("light");
    expect(resolveEkklesiaColorScheme("system", true)).toBe("dark");
    expect(resolveEkklesiaColorScheme("light", true)).toBe("light");
    expect(resolveEkklesiaColorScheme("dark", false)).toBe("dark");
    expect(resolveEkklesiaReducedMotion("system", true)).toBe(true);
    expect(resolveEkklesiaReducedMotion("system", false)).toBe(false);
    expect(resolveEkklesiaReducedMotion("reduce", false)).toBe(true);
    expect(resolveEkklesiaReducedMotion("allow", true)).toBe(false);
  });
});

describe("the theme controller", () => {
  it("defaults to System and applies its attributes at once, before anything renders", () => {
    const env = environment();
    const controller = createEkklesiaThemeController({
      matchMedia: env.matchMedia,
      target: env.target,
    });

    expect(controller.appearance()).toBe("system");
    expect(controller.motion()).toBe("system");
    expect(env.attributes.get(DESIGN_TOKEN_APPEARANCE_ATTRIBUTE)).toBe("system");
    expect(env.attributes.get(DESIGN_TOKEN_MOTION_ATTRIBUTE)).toBe("system");
  });

  it("resolves System to Light or Dark from the system, and follows it live", () => {
    const env = environment({ dark: false });
    const controller = createEkklesiaThemeController({
      matchMedia: env.matchMedia,
      target: env.target,
    });
    const listener = vi.fn();
    controller.subscribe(listener);
    expect(controller.colorScheme()).toBe("light");

    env.dark.query.set(true);

    expect(controller.colorScheme()).toBe("dark");
    expect(listener).toHaveBeenCalledTimes(1);
  });

  it("lets an explicit Light or Dark ignore the system", () => {
    for (const appearance of ["light", "dark"] as const) {
      const env = environment({ dark: appearance === "light" });
      const controller = createEkklesiaThemeController({
        appearance,
        matchMedia: env.matchMedia,
        target: env.target,
      });
      expect(controller.colorScheme(), appearance).toBe(appearance);
      env.dark.query.set(appearance !== "light");
      expect(controller.colorScheme(), appearance).toBe(appearance);
      expect(env.attributes.get(DESIGN_TOKEN_APPEARANCE_ATTRIBUTE)).toBe(appearance);
    }
  });

  it("switches mode in place, without a reload, and only notifies on a real change", () => {
    const env = environment({ dark: true });
    const controller = createEkklesiaThemeController({
      matchMedia: env.matchMedia,
      target: env.target,
    });
    const listener = vi.fn();
    controller.subscribe(listener);

    controller.setAppearance("light");
    expect(env.attributes.get(DESIGN_TOKEN_APPEARANCE_ATTRIBUTE)).toBe("light");
    expect(controller.colorScheme()).toBe("light");
    controller.setAppearance("light");
    controller.setAppearance("dark");
    controller.setAppearance("system");
    expect(controller.colorScheme()).toBe("dark");
    expect(listener).toHaveBeenCalledTimes(3);
  });

  it("follows the system's reduced-motion setting, and supports an explicit Reduce or Allow", () => {
    const env = environment({ reduced: false });
    const controller = createEkklesiaThemeController({
      matchMedia: env.matchMedia,
      target: env.target,
    });
    expect(controller.reducedMotion()).toBe(false);
    env.reduced.query.set(true);
    expect(controller.reducedMotion()).toBe(true);

    controller.setMotion("allow");
    expect(env.attributes.get(DESIGN_TOKEN_MOTION_ATTRIBUTE)).toBe("allow");
    expect(controller.reducedMotion()).toBe(false);
    controller.setMotion("reduce");
    env.reduced.query.set(false);
    expect(controller.reducedMotion()).toBe(true);
  });

  it("takes an untrusted stored preference straight in", () => {
    const env = environment();
    const controller = createEkklesiaThemeController({
      appearance: "purple" as "dark",
      matchMedia: env.matchMedia,
      motion: 7 as unknown as "reduce",
      target: env.target,
    });
    expect(controller.appearance()).toBe("system");
    expect(controller.motion()).toBe("system");
  });

  it("listens to the system only while someone is subscribed", () => {
    const env = environment();
    const controller = createEkklesiaThemeController({
      matchMedia: env.matchMedia,
      target: env.target,
    });
    const unsubscribe = controller.subscribe(() => undefined);
    expect(env.dark.listeners.size).toBe(1);
    expect(env.reduced.listeners.size).toBe(1);
    unsubscribe();
    expect(env.dark.listeners.size).toBe(0);
    expect(env.reduced.listeners.size).toBe(0);
  });

  it("works with no media queries at all, as light with full motion", () => {
    const env = environment();
    const controller = createEkklesiaThemeController({ target: env.target });
    expect(controller.colorScheme()).toBe("light");
    expect(controller.reducedMotion()).toBe(false);
  });
});