@lovrozagar/flare 0.1.0

package/src/styles/sx-types.ts

@@ -0,0 +1,11 @@
+import type { Properties } from "csstype";
+
+/** Style object accepted by the `sx` prop. Supports flat CSS, `&` selectors, at-rules, and variants. */
+export type Sx = Properties<string | number> & {
+	[selector: `&${string}`]: Sx;
+	[atRule: `@${string}`]: Sx;
+	variants?: Record<string, Record<string, Sx>>;
+};
+
+/** Accepts strings, falsy values, and nested arrays — mirrors clsx input. */
+export type ClassValue = string | false | null | undefined | ClassValue[];

package/src/testing/index.ts

@@ -0,0 +1,251 @@
+import { EMPTY_ARR } from "../internal/index.ts";
+
+const HYDRATION_PATTERNS = [/hydration/i, /mismatch/i, /unable to find dom nodes/i];
+
+export function isHydrationError(message: string): boolean {
+	return HYDRATION_PATTERNS.some((p) => p.test(message));
+}
+
+export function filterByPatterns(messages: string[], patterns: readonly RegExp[]): string[] {
+	if (patterns.length === 0) return messages;
+	return messages.filter((msg) => !patterns.some((p) => p.test(msg)));
+}
+
+export function assertFlareStateShape(state: unknown): void {
+	if (state === null || state === undefined || typeof state !== "object") {
+		throw new Error("FlareState is null or not an object");
+	}
+
+	const obj = state as Record<string, unknown>;
+
+	if (typeof obj.p !== "string") {
+		throw new Error("FlareState.p (pathname) must be a string");
+	}
+
+	if (typeof obj.r !== "object" || obj.r === null) {
+		throw new Error("FlareState.r (params) must be an object");
+	}
+
+	if (typeof obj.c !== "object" || obj.c === null) {
+		throw new Error("FlareState.c (context) must be an object");
+	}
+}
+
+/* ── FlarePage ───────────────────────────────────────────────────────── */
+
+export interface ConsoleMessage {
+	text: string;
+	type: "error" | "log" | "warning";
+}
+
+export interface PageError {
+	message: string;
+	stack?: string;
+}
+
+/**
+ * Minimal page interface matching Playwright's Page.
+ * Avoids hard dependency on @playwright/test.
+ */
+export interface FlarePageInterface {
+	evaluate: (fn: unknown) => Promise<unknown>;
+	getByText: (text: string) => { click: () => Promise<void> };
+	goto: (url: string, options?: { waitUntil?: string }) => Promise<unknown>;
+	locator: (selector: string) => unknown;
+	on: (event: string, handler: (...args: unknown[]) => void) => void;
+	url: () => string;
+	waitForFunction: (
+		fn: string | ((arg: unknown) => boolean),
+		arg?: unknown,
+		options?: { timeout?: number },
+	) => Promise<void>;
+	waitForLoadState: (state?: string) => Promise<void>;
+	waitForSelector: (selector: string, options?: { timeout?: number }) => Promise<void>;
+}
+
+export class FlarePage {
+	readonly page: FlarePageInterface;
+	private captures: {
+		consoleErrors: string[];
+		consoleLogs: string[];
+		consoleWarnings: string[];
+		pageErrors: PageError[];
+	} = {
+		consoleErrors: [],
+		consoleLogs: [],
+		consoleWarnings: [],
+		pageErrors: [],
+	};
+	private capturing = false;
+	private lastResponse: unknown = null;
+
+	constructor(page: FlarePageInterface) {
+		this.page = page;
+	}
+
+	/* ── Lifecycle ──────────────────────────────────────────────────── */
+
+	startCapturing(): void {
+		if (this.capturing) return;
+		this.capturing = true;
+
+		this.page.on("console", (...args: unknown[]) => {
+			const msg = args[0] as { text: () => string; type: () => string };
+			const text = msg.text();
+			const type = msg.type();
+			if (type === "error") this.captures.consoleErrors.push(text);
+			else if (type === "warning") this.captures.consoleWarnings.push(text);
+			else this.captures.consoleLogs.push(text);
+		});
+
+		this.page.on("pageerror", (...args: unknown[]) => {
+			const error = args[0] as { message: string; stack?: string };
+			this.captures.pageErrors.push({
+				message: error.message,
+				stack: error.stack,
+			});
+		});
+	}
+
+	clearCaptures(): void {
+		this.captures.consoleErrors = [];
+		this.captures.consoleLogs = [];
+		this.captures.consoleWarnings = [];
+		this.captures.pageErrors = [];
+	}
+
+	/* ── Navigation ─────────────────────────────────────────────────── */
+
+	async goto(path = "/"): Promise<unknown> {
+		this.lastResponse = await this.page.goto(path, { waitUntil: "domcontentloaded" });
+		await this.page.waitForSelector("body", { timeout: 15_000 });
+		return this.lastResponse;
+	}
+
+	async load(path: string): Promise<unknown> {
+		const response = await this.goto(path);
+		await this.waitForHydration();
+		await this.page.waitForLoadState("networkidle");
+		return response;
+	}
+
+	async waitForNavigation(path: string): Promise<void> {
+		await this.page.waitForFunction((expected: unknown) => window.location.pathname === expected, path, {
+			timeout: 15_000,
+		});
+	}
+
+	async clickLink(text: string): Promise<void> {
+		await this.page.getByText(text).click();
+	}
+
+	async navigateNdjson(linkText: string): Promise<void> {
+		await this.setNavigationMarker();
+		await this.clickLink(linkText);
+		await this.page.waitForLoadState("networkidle");
+	}
+
+	/* ── Hydration ──────────────────────────────────────────────────── */
+
+	async waitForHydration(timeout = 15_000): Promise<void> {
+		await this.page.waitForFunction("document.documentElement.hasAttribute('data-hydrated')", undefined, {
+			timeout,
+		});
+	}
+
+	/* ── State ──────────────────────────────────────────────────────── */
+
+	async getFlareState(): Promise<unknown> {
+		return await this.page.evaluate(() => (self as unknown as { flare?: unknown }).flare ?? null);
+	}
+
+	async assertFlareStateValid(): Promise<void> {
+		const state = await this.getFlareState();
+		assertFlareStateShape(state);
+	}
+
+	/* ── CSR detection ──────────────────────────────────────────────── */
+
+	async setNavigationMarker(): Promise<void> {
+		await this.page.evaluate("window.__FLARE_NAV_MARKER__ = true");
+	}
+
+	async wasClientNavigation(): Promise<boolean> {
+		const result = await this.page.evaluate("Boolean(window.__FLARE_NAV_MARKER__)");
+		return result as boolean;
+	}
+
+	/* ── Response ───────────────────────────────────────────────────── */
+
+	getLastResponse(): unknown {
+		return this.lastResponse;
+	}
+
+	/* ── Captures ───────────────────────────────────────────────────── */
+
+	getConsoleLogs(): string[] {
+		return [...this.captures.consoleLogs];
+	}
+
+	getConsoleErrors(): string[] {
+		return [...this.captures.consoleErrors];
+	}
+
+	getConsoleWarnings(): string[] {
+		return [...this.captures.consoleWarnings];
+	}
+
+	getPageErrors(): PageError[] {
+		return [...this.captures.pageErrors];
+	}
+
+	getHydrationErrors(): string[] {
+		const all = [...this.captures.consoleErrors, ...this.captures.pageErrors.map((e) => e.message)];
+		return all.filter((msg) => isHydrationError(msg));
+	}
+
+	hasHydrationErrors(): boolean {
+		return this.getHydrationErrors().length > 0;
+	}
+
+	/* ── Assertions ─────────────────────────────────────────────────── */
+
+	assertNoConsoleErrors(ignorePatterns: readonly RegExp[] = EMPTY_ARR): void {
+		const errors = filterByPatterns(this.captures.consoleErrors, ignorePatterns);
+		if (errors.length > 0) {
+			throw new Error(`Test failed: ${errors.length} console error(s): ${errors.join(", ")}`);
+		}
+	}
+
+	assertNoConsoleWarnings(ignorePatterns: readonly RegExp[] = EMPTY_ARR): void {
+		const warnings = filterByPatterns(this.captures.consoleWarnings, ignorePatterns);
+		if (warnings.length > 0) {
+			throw new Error(`Test failed: ${warnings.length} console warning(s): ${warnings.join(", ")}`);
+		}
+	}
+
+	assertNoPageErrors(): void {
+		if (this.captures.pageErrors.length > 0) {
+			const msgs = this.captures.pageErrors.map((e) => e.message);
+			throw new Error(`Test failed: ${msgs.length} page error(s): ${msgs.join(", ")}`);
+		}
+	}
+
+	assertNoHydrationErrors(): void {
+		const hydrationErrors = this.getHydrationErrors();
+		if (hydrationErrors.length > 0) {
+			throw new Error(`Test failed: ${hydrationErrors.length} hydration error(s): ${hydrationErrors.join(", ")}`);
+		}
+	}
+
+	assertHealthy(): void {
+		this.assertNoHydrationErrors();
+		this.assertNoPageErrors();
+		this.assertNoConsoleErrors();
+	}
+
+	assertFullyHealthy(): void {
+		this.assertHealthy();
+		this.assertNoConsoleWarnings();
+	}
+}

package/src/testing.ts

@@ -0,0 +1,2 @@
+export type { ConsoleMessage, FlarePageInterface, PageError } from "./testing/index.ts";
+export { assertFlareStateShape, FlarePage, filterByPatterns, isHydrationError } from "./testing/index.ts";

package/src/theme/index.tsx

@@ -0,0 +1,232 @@
+import {
+	createContext,
+	createEffect,
+	createSignal,
+	type JSX,
+	on,
+	onCleanup,
+	onMount,
+	sharedConfig,
+	useContext,
+} from "solid-js";
+
+export type Theme = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+export interface ThemeConfig {
+	attribute?: string;
+	defaultTheme?: Theme;
+	disableTransitionOnChange?: boolean;
+	storageKey?: string;
+	themes?: readonly Theme[];
+}
+
+const DEFAULT_CONFIG: Required<ThemeConfig> = {
+	attribute: "data-theme",
+	defaultTheme: "system",
+	disableTransitionOnChange: true,
+	storageKey: "flare.theme",
+	themes: ["light", "dark", "system"],
+};
+
+/* Escape for safe interpolation into JS double-quoted strings inside <script> */
+export function escapeJsString(s: string): string {
+	return s
+		.replace(/\\/g, "\\\\")
+		.replace(/"/g, '\\"')
+		.replace(/<\//g, "<\\/")
+		.replace(/\n/g, "\\n")
+		.replace(/\r/g, "\\r")
+		.replace(/\u2028/g, "\\u2028")
+		.replace(/\u2029/g, "\\u2029");
+}
+
+export function getThemeScript(opts?: ThemeConfig): string {
+	const attr = escapeJsString(opts?.attribute ?? DEFAULT_CONFIG.attribute);
+	const defaultTheme = escapeJsString(opts?.defaultTheme ?? DEFAULT_CONFIG.defaultTheme);
+	const storageKey = escapeJsString(opts?.storageKey ?? DEFAULT_CONFIG.storageKey);
+	return `((k,d,a)=>{const e=document.documentElement;let t;try{t=localStorage.getItem(k)||d}catch{t=d}if(t==="system")t=matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light";e.setAttribute(a,t);try{e.style.colorScheme=t}catch{}})("${storageKey}","${defaultTheme}","${attr}")`;
+}
+
+/* ── Context ──────────────────────────────────────────────────────── */
+
+export interface ThemeContextValue {
+	resolvedTheme: () => ResolvedTheme;
+	setTheme: (theme: Theme) => void;
+	theme: () => Theme;
+	toggleTheme: () => void;
+}
+
+const ThemeCtx = createContext<ThemeContextValue>();
+
+export function ThemeProvider(props: { children: JSX.Element; config?: ThemeConfig }): JSX.Element {
+	const cfg: Required<ThemeConfig> = {
+		attribute: props.config?.attribute ?? DEFAULT_CONFIG.attribute,
+		defaultTheme: props.config?.defaultTheme ?? DEFAULT_CONFIG.defaultTheme,
+		disableTransitionOnChange: props.config?.disableTransitionOnChange ?? DEFAULT_CONFIG.disableTransitionOnChange,
+		storageKey: props.config?.storageKey ?? DEFAULT_CONFIG.storageKey,
+		themes: props.config?.themes ?? DEFAULT_CONFIG.themes,
+	};
+
+	const hydrating = !!sharedConfig.context;
+
+	/* During SSR + hydration, always start from defaultTheme so the tree matches.
+	   ThemeScript already applied localStorage to <html> before first paint.
+	   Reading storage here on the client would hydrate with a different signal
+	   than the server and freeze the SSR "system" text until refresh. */
+	let initial: Theme = cfg.defaultTheme;
+	if (typeof localStorage !== "undefined" && !hydrating) {
+		try {
+			const stored = localStorage.getItem(cfg.storageKey);
+			if (stored && cfg.themes.includes(stored as Theme)) {
+				initial = stored as Theme;
+			}
+		} catch {
+			/* noop */
+		}
+	}
+
+	const [theme, setThemeSignal] = createSignal<Theme>(initial);
+
+	/* Initialize system theme synchronously to avoid extra effect cycle */
+	let initialSystem: ResolvedTheme = "light";
+	if (typeof matchMedia !== "undefined" && matchMedia("(prefers-color-scheme: dark)").matches) {
+		initialSystem = "dark";
+	}
+	const [systemTheme, setSystemTheme] = createSignal<ResolvedTheme>(initialSystem);
+
+	const resolvedTheme = (): ResolvedTheme => {
+		const t = theme();
+		return t === "system" ? systemTheme() : t;
+	};
+
+	const applyToDocument = (resolved: ResolvedTheme): void => {
+		if (typeof document === "undefined") return;
+		const el = document.documentElement;
+		el.setAttribute(cfg.attribute, resolved);
+		try {
+			el.style.colorScheme = resolved;
+		} catch {
+			/* CSP style-src may block CSSOM writes; attribute + nonce'd CSS still apply */
+		}
+	};
+
+	/* Client remount / CSR: apply immediately. During hydration, ThemeScript owns
+	   first paint — applying here would overwrite a stored theme with "system". */
+	if (!hydrating) {
+		applyToDocument(resolvedTheme());
+	}
+
+	/* After hydrate, sync from localStorage so useTheme() matches ThemeScript. */
+	onMount(() => {
+		if (typeof localStorage === "undefined") return;
+		try {
+			const stored = localStorage.getItem(cfg.storageKey);
+			if (stored && cfg.themes.includes(stored as Theme) && stored !== theme()) {
+				setThemeSignal(stored as Theme);
+			}
+		} catch {
+			/* noop */
+		}
+		applyToDocument(resolvedTheme());
+	});
+
+	/* Listen for OS preference changes */
+	onMount(() => {
+		if (typeof matchMedia === "undefined") return;
+		const mq = matchMedia("(prefers-color-scheme: dark)");
+		const handler = (e: MediaQueryListEvent) => {
+			setSystemTheme(e.matches ? "dark" : "light");
+		};
+		mq.addEventListener("change", handler);
+		onCleanup(() => mq.removeEventListener("change", handler));
+	});
+
+	/* Cross-tab sync: StorageEvent fires in OTHER tabs only */
+	onMount(() => {
+		const handler = (e: StorageEvent) => {
+			if (e.key !== cfg.storageKey || e.storageArea !== localStorage) return;
+			const v = e.newValue;
+			if (v && cfg.themes.includes(v as Theme)) {
+				setThemeSignal(v as Theme);
+			}
+		};
+		window.addEventListener("storage", handler);
+		onCleanup(() => window.removeEventListener("storage", handler));
+	});
+
+	/* Sync resolved theme to DOM (skip transition-disable on first run) */
+	let skipFirst = true;
+	createEffect(() => {
+		const resolved = resolvedTheme();
+		if (typeof document === "undefined") return;
+
+		if (skipFirst) {
+			skipFirst = false;
+			/* After Solid hydrates <html> it drops ThemeScript's data-theme.
+			   Re-apply the visual value (storage or system) without waiting for onMount. */
+			let visual: ResolvedTheme = resolved;
+			if (typeof localStorage !== "undefined") {
+				try {
+					const stored = localStorage.getItem(cfg.storageKey);
+					if (stored === "light" || stored === "dark") visual = stored;
+				} catch {
+					/* noop */
+				}
+			}
+			applyToDocument(visual);
+			return;
+		}
+
+		if (cfg.disableTransitionOnChange) {
+			const style = document.createElement("style");
+			style.textContent = "* { transition: none !important }";
+			document.head.appendChild(style);
+			applyToDocument(resolved);
+			if (document.body) void getComputedStyle(document.body).opacity;
+			requestAnimationFrame(() => style.remove());
+		} else {
+			applyToDocument(resolved);
+		}
+	});
+
+	/* Persist to localStorage on changes (not initial — it was read from there) */
+	createEffect(
+		on(
+			theme,
+			(t) => {
+				try {
+					localStorage.setItem(cfg.storageKey, t);
+				} catch {
+					/* noop */
+				}
+			},
+			{ defer: true },
+		),
+	);
+
+	const setTheme = (t: Theme): void => {
+		if (!cfg.themes.includes(t)) return;
+		setThemeSignal(t);
+	};
+
+	const toggleTheme = (): void => {
+		const current = resolvedTheme();
+		setTheme(current === "light" ? "dark" : "light");
+	};
+
+	const value: ThemeContextValue = {
+		resolvedTheme,
+		setTheme,
+		theme,
+		toggleTheme,
+	};
+
+	return <ThemeCtx.Provider value={value}>{props.children}</ThemeCtx.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+	const ctx = useContext(ThemeCtx);
+	if (!ctx) throw new Error("useTheme() called outside ThemeProvider. Wrap your app with <ThemeProvider>.");
+	return ctx;
+}

package/src/theme.ts

@@ -0,0 +1,3 @@
+export { ThemeScript } from "./components/theme-script.tsx";
+export type { ResolvedTheme, Theme, ThemeConfig, ThemeContextValue } from "./theme/index.tsx";
+export { escapeJsString, getThemeScript, ThemeProvider, useTheme } from "./theme/index.tsx";

package/src/tracing/index.ts

@@ -0,0 +1,4 @@
+export { noopTracer } from "./noop.ts";
+export { createOtelTracer, type OtelSpanLike, type OtelTracerLike } from "./otel.ts";
+export { buildServerTimingHeader, createTimingTracer, type TimingEntry, type TimingTracer } from "./timing.ts";
+export type { FlareSpan, FlareTracer } from "./types.ts";

package/src/tracing/noop.ts

@@ -0,0 +1,13 @@
+import type { FlareSpan, FlareTracer } from "./types.ts";
+
+const noopSpan: FlareSpan = {
+	end() {},
+	setAttribute() {},
+	setStatus() {},
+};
+
+export const noopTracer: FlareTracer = {
+	startSpan() {
+		return noopSpan;
+	},
+};

package/src/tracing/otel.ts

@@ -0,0 +1,37 @@
+import type { FlareSpan, FlareTracer } from "./types.ts";
+
+/**
+ * Minimal subset of the OpenTelemetry Tracer API that Flare consumes.
+ * Users pass their real OTel tracer — this avoids a hard dependency on @opentelemetry/*.
+ */
+export interface OtelTracerLike {
+	startSpan(name: string): OtelSpanLike;
+}
+
+export interface OtelSpanLike {
+	end(): void;
+	setAttribute(key: string, value: boolean | number | string): void;
+	setStatus(status: { code: number; message?: string }): void;
+}
+
+/** OTel StatusCode.ERROR = 2, StatusCode.OK = 1 */
+const STATUS_MAP: Record<"error" | "ok", number> = { error: 2, ok: 1 };
+
+export function createOtelTracer(provider: OtelTracerLike): FlareTracer {
+	return {
+		startSpan(name: string): FlareSpan {
+			const span = provider.startSpan(name);
+			return {
+				end() {
+					span.end();
+				},
+				setAttribute(key: string, value: boolean | number | string) {
+					span.setAttribute(key, value);
+				},
+				setStatus(status: "error" | "ok") {
+					span.setStatus({ code: STATUS_MAP[status] });
+				},
+			};
+		},
+	};
+}

package/src/tracing/timing.ts

@@ -0,0 +1,34 @@
+import type { FlareSpan, FlareTracer } from "./types.ts";
+
+export interface TimingEntry {
+	dur: number;
+	name: string;
+}
+
+export interface TimingTracer extends FlareTracer {
+	getEntries(): TimingEntry[];
+}
+
+export function createTimingTracer(): TimingTracer {
+	const entries: TimingEntry[] = [];
+
+	return {
+		getEntries() {
+			return entries;
+		},
+		startSpan(name: string): FlareSpan {
+			const start = performance.now();
+			return {
+				end() {
+					entries.push({ dur: performance.now() - start, name });
+				},
+				setAttribute() {},
+				setStatus() {},
+			};
+		},
+	};
+}
+
+export function buildServerTimingHeader(entries: TimingEntry[]): string {
+	return entries.map((e) => `${e.name};dur=${e.dur.toFixed(1)}`).join(", ");
+}

package/src/tracing/types.ts

@@ -0,0 +1,9 @@
+export interface FlareSpan {
+	end(): void;
+	setAttribute(key: string, value: boolean | number | string): void;
+	setStatus(status: "error" | "ok"): void;
+}
+
+export interface FlareTracer {
+	startSpan(name: string): FlareSpan;
+}