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(); 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); }); });