@decocms/apps-website 7.2.0

package/src/components/OneDollarStats.tsx

@@ -0,0 +1,283 @@
+/**
+ * OneDollarStats — deco's lightweight in-house analytics.
+ *
+ * Posts pageviews (initial load + SPA navigations) and forwards DECO
+ * events to the lilstts collector. Mount once in `__root.tsx` as a child
+ * of `DecoRootLayout`:
+ *
+ * ```tsx
+ * <DecoRootLayout … >
+ *   <OneDollarStats />
+ * </DecoRootLayout>
+ * ```
+ *
+ * The component is env-gated and self-mounting — no CMS wiring needed.
+ *
+ * ## Why this design
+ *
+ * 1. **We own pageviews.** The lilstts SDK has its own auto-pageview path
+ *    (driven by `history.pushState` wrapping). We disable it via
+ *    `data-autocollect="false"` and call `window.stonks.view(flags)`
+ *    ourselves. This is the only way to attach `deco_segment` cookie
+ *    flags to pageviews — the SDK's auto-path doesn't know about them.
+ *
+ * 2. **`useEffect` for client logic.** All side-effects (initial pageview,
+ *    pushState wrap, DECO event subscribe) run inside a `useEffect`,
+ *    which fires after hydration. By then `<ScriptOnce>` in
+ *    `DecoRootLayout` has bootstrapped `window.DECO.events`, and the SDK
+ *    `<script>` (rendered as a sibling) has loaded and set
+ *    `window.stonks`. No inline `dangerouslySetInnerHTML` snippet, no
+ *    fragile script-execution-order dependency.
+ *
+ * 3. **Module-level guards.** `window.DECO.events.subscribe()` returns no
+ *    unsubscribe handle, so we cannot clean up on unmount. We use a
+ *    module-level `initialized` flag to ensure init runs exactly once
+ *    per page lifetime, surviving HMR and React StrictMode double-mount.
+ *
+ * 4. **Bounded readiness polling.** `window.stonks` and `window.DECO`
+ *    might not be ready the instant our effect fires (race with script
+ *    load). We poll every 50 ms for up to 10 s. Production: resolves
+ *    within one tick.
+ *
+ * ## Behavioural parity vs Fresh `deco-cx/apps`
+ *
+ * Mirrors the Path B snippet (`analytics/loaders/OneDollarScript.ts`):
+ * unconditional first pageview with flag enrichment, SPA nav tracking,
+ * and DECO event forwarding. Diverges from the Fresh component variant
+ * (which depended on a synthesised `{ name: "deco" }` event from
+ * `Events.tsx`'s subscribe-replay — no equivalent in TanStack).
+ *
+ * `pageId` enrichment is intentionally dropped — no admin dashboard
+ * consumes it. Add later if a flag-segmented dashboard needs it.
+ */
+
+import { useEffect } from "react";
+
+declare global {
+	interface Window {
+		stonks?: {
+			view?: (params?: Record<string, string | boolean | number>) => void;
+			event?: (name: string, params?: Record<string, string | boolean | number>) => void;
+		};
+	}
+}
+
+export interface Props {
+	/** lilstts collector URL. Defaults to {@link DEFAULT_COLLECTOR_ADDRESS}. */
+	collectorAddress?: string;
+	/** lilstts static script URL. Defaults to {@link DEFAULT_ANALYTICS_SCRIPT_URL}. */
+	staticScriptUrl?: string;
+}
+
+export const DEFAULT_COLLECTOR_ADDRESS = "https://d.lilstts.com/events";
+export const DEFAULT_ANALYTICS_SCRIPT_URL = "https://s.lilstts.com/deco.js";
+
+/**
+ * Set `ONEDOLLAR_ENABLED=false` on the Worker to disable. Default: enabled.
+ * Matches the Fresh-side Deno env contract.
+ */
+const ONEDOLLAR_ENABLED = process.env.ONEDOLLAR_ENABLED !== "false";
+const ONEDOLLAR_COLLECTOR = process.env.ONEDOLLAR_COLLECTOR;
+const ONEDOLLAR_STATIC_SCRIPT = process.env.ONEDOLLAR_STATIC_SCRIPT;
+
+function OneDollarStats({ collectorAddress, staticScriptUrl }: Props) {
+	if (!ONEDOLLAR_ENABLED) return null;
+
+	const collector = collectorAddress ?? ONEDOLLAR_COLLECTOR ?? DEFAULT_COLLECTOR_ADDRESS;
+	const staticScript = staticScriptUrl ?? ONEDOLLAR_STATIC_SCRIPT ?? DEFAULT_ANALYTICS_SCRIPT_URL;
+
+	return (
+		<>
+			<link rel="dns-prefetch" href={collector} />
+			<link rel="preconnect" href={collector} crossOrigin="anonymous" />
+			<script
+				id="onedollarstats-tracker"
+				data-autocollect="false"
+				data-hash-routing="true"
+				data-url={collector}
+				src={staticScript}
+				defer
+			/>
+			<OneDollarStatsClient />
+		</>
+	);
+}
+
+/**
+ * Client-only side-effects. Mounted as a child of {@link OneDollarStats};
+ * does not render any DOM.
+ */
+function OneDollarStatsClient() {
+	useEffect(() => {
+		initOneDollarStats();
+	}, []);
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Module-level state — survives StrictMode double-mount and HMR remounts.
+// ---------------------------------------------------------------------------
+
+let initialized = false;
+let cachedFlags: Record<string, boolean> | null = null;
+
+interface DecoSegmentCookie {
+	active?: string[];
+	inactiveDrawn?: string[];
+}
+
+/**
+ * Read A/B test flags from the `deco_segment` cookie. Cached after first
+ * read for the lifetime of the page — flags are baked at request time
+ * server-side and don't change mid-session.
+ *
+ * Exported for testing.
+ */
+export function readFlagsFromCookie(
+	cookieString: string = typeof document !== "undefined" ? document.cookie : "",
+): Record<string, boolean> {
+	if (cachedFlags && cookieString === (typeof document !== "undefined" ? document.cookie : "")) {
+		return cachedFlags;
+	}
+	const flags: Record<string, boolean> = {};
+	try {
+		const cookies = parseCookies(cookieString);
+		const raw = cookies.deco_segment;
+		if (raw) {
+			const seg = JSON.parse(decodeURIComponent(atob(raw))) as DecoSegmentCookie;
+			for (const name of seg.active ?? []) flags[name] = true;
+			for (const name of seg.inactiveDrawn ?? []) flags[name] = false;
+		}
+	} catch {
+		// Malformed cookie — proceed with empty flags rather than crashing analytics.
+	}
+	cachedFlags = flags;
+	return flags;
+}
+
+function parseCookies(cookieString: string): Record<string, string> {
+	return cookieString.split(";").reduce<Record<string, string>>((acc, c) => {
+		const idx = c.indexOf("=");
+		if (idx > 0) acc[c.slice(0, idx).trim()] = c.slice(idx + 1).trim();
+		return acc;
+	}, {});
+}
+
+/**
+ * Truncate any value to the lilstts payload limit (~1 KB per field).
+ * Exported for testing.
+ */
+export function truncate(v: unknown): string {
+	const s = typeof v === "string" ? v : typeof v === "object" ? JSON.stringify(v) : String(v);
+	return s.slice(0, 990);
+}
+
+/**
+ * Poll for a global to become available, then invoke `cb` exactly once.
+ * Bounded by `maxAttempts * intervalMs` (default ~10 s). On timeout, no-op.
+ */
+function whenReady<T>(
+	check: () => T | undefined,
+	cb: (value: T) => void,
+	{ intervalMs = 50, maxAttempts = 200 }: { intervalMs?: number; maxAttempts?: number } = {},
+): void {
+	const initial = check();
+	if (initial !== undefined) {
+		cb(initial);
+		return;
+	}
+	let attempts = 0;
+	const iv = setInterval(() => {
+		attempts++;
+		const v = check();
+		if (v !== undefined) {
+			clearInterval(iv);
+			cb(v);
+		} else if (attempts >= maxAttempts) {
+			clearInterval(iv);
+		}
+	}, intervalMs);
+}
+
+/**
+ * Wire up the analytics integration. Idempotent — only the first call has
+ * any effect.
+ *
+ * @internal exported for tests; do not call from app code.
+ */
+export function initOneDollarStats(): void {
+	if (initialized) return;
+	initialized = true;
+
+	const flags = readFlagsFromCookie();
+
+	// 1) Initial pageview + SPA nav tracking, with flag enrichment.
+	whenReady(
+		() =>
+			typeof window.stonks?.view === "function"
+				? window.stonks.view.bind(window.stonks)
+				: undefined,
+		(view) => {
+			view(flags);
+			wrapHistoryPushState(() => view(flags));
+			addEventListener("popstate", () => view(flags));
+		},
+	);
+
+	// 2) Forward DECO events to stonks.event with flag enrichment.
+	whenReady(
+		() =>
+			typeof window.DECO?.events?.subscribe === "function"
+				? window.DECO.events.subscribe.bind(window.DECO.events)
+				: undefined,
+		(subscribe) => {
+			subscribe((event: { name?: string; params?: Record<string, unknown> } | null | undefined) => {
+				if (!event || !event.name || event.name === "deco") return;
+				if (typeof window.stonks?.event !== "function") return;
+				const values: Record<string, string | boolean | number> = { ...flags };
+				for (const [k, v] of Object.entries(event.params ?? {})) {
+					if (v == null) continue;
+					values[k] = truncate(v);
+				}
+				window.stonks.event(event.name, values);
+			});
+		},
+	);
+}
+
+/**
+ * Wrap `history.pushState` to invoke `onPush` after each call. Idempotent
+ * via a marker property on the wrapper. The lilstts SDK installs its own
+ * wrapper too — with `data-autocollect="false"` its handler is a no-op,
+ * so we don't double-fire.
+ */
+function wrapHistoryPushState(onPush: () => void): void {
+	const ANY_HISTORY = history as History & { __onedollarstats_wrapped?: true };
+	if (ANY_HISTORY.__onedollarstats_wrapped) return;
+	const original = history.pushState;
+	const wrapped = function (this: History, ...args: Parameters<History["pushState"]>): void {
+		original.apply(this, args);
+		try {
+			onPush();
+		} catch (err) {
+			console.error("[OneDollarStats] pushState handler", err);
+		}
+	} as History["pushState"];
+	(wrapped as unknown as { __onedollarstats_wrapped: true }).__onedollarstats_wrapped = true;
+	history.pushState = wrapped;
+	ANY_HISTORY.__onedollarstats_wrapped = true;
+}
+
+/**
+ * @internal — reset module state for tests. NEVER call from app code.
+ */
+export function __resetForTests(): void {
+	initialized = false;
+	cachedFlags = null;
+	if (typeof history !== "undefined") {
+		const h = history as History & { __onedollarstats_wrapped?: true };
+		delete h.__onedollarstats_wrapped;
+	}
+}
+
+export default OneDollarStats;

package/src/components/Seo.tsx

@@ -0,0 +1,139 @@
+import type { ImageWidget, OGType } from "../types";
+import { stripHTML } from "../utils/html";
+
+export const renderTemplateString = (template: string, value: string) =>
+	template.replace("%s", value);
+
+export type SEOSection = React.JSX.Element;
+
+export interface Props {
+	title?: string;
+	/**
+	 * @title Title template
+	 * @description add a %s whenever you want it to be replaced with the product name, category name or search term
+	 * @default %s
+	 */
+	titleTemplate?: string;
+	description?: string;
+	/**
+	 * @title Description template
+	 * @description add a %s whenever you want it to be replaced with the product name, category name or search term
+	 * @default %s
+	 */
+	descriptionTemplate?: string;
+	/** @default website */
+	type?: OGType;
+	/** @description Recommended: 1200 x 630 px (up to 5MB) */
+	image?: ImageWidget;
+	/** @description Recommended: 16 x 16 px */
+	favicon?: ImageWidget;
+	/** @description Suggested color that browsers should use to customize the display of the page or of the surrounding user interface */
+	themeColor?: string;
+	/** @title Canonical URL */
+	canonical?: string;
+	/**
+	 * @title Disable indexing
+	 * @description In testing, you can use this to prevent search engines from indexing your site
+	 */
+	noIndexing?: boolean;
+
+	/** @title Open Graph Config */
+	openGraphConfig?: {
+		title?: string;
+		description?: string;
+		image?: ImageWidget;
+		url?: string;
+	};
+
+	/** @title Twitter Config */
+	twitterConfig?: {
+		title?: string;
+		description?: string;
+		image?: ImageWidget;
+	};
+
+	jsonLDs?: unknown[];
+}
+
+/**
+ * SEO component — renders meta tags that React 19 / TanStack Start
+ * automatically hoists into <head>.
+ */
+function Seo({
+	title: t = "",
+	titleTemplate = "%s",
+	description: desc,
+	descriptionTemplate = "%s",
+	type,
+	image,
+	favicon,
+	themeColor,
+	canonical,
+	noIndexing,
+	openGraphConfig,
+	twitterConfig,
+	jsonLDs = [],
+}: Props) {
+	const twitterCard = type === "website" ? "summary" : "summary_large_image";
+
+	const title = stripHTML(t);
+	const description = stripHTML(desc || "");
+
+	const twitterImage = twitterConfig?.image ?? image;
+	const twitterTitle = twitterConfig?.title ? stripHTML(twitterConfig.title) : title;
+	const twitterDescription = twitterConfig?.description
+		? stripHTML(twitterConfig.description)
+		: description;
+
+	const openGraphImage = openGraphConfig?.image ?? image;
+	const openGraphTitle = openGraphConfig?.title ? stripHTML(openGraphConfig.title) : title;
+	const openGraphDescription = openGraphConfig?.description
+		? stripHTML(openGraphConfig.description)
+		: description;
+
+	return (
+		<>
+			<title>{renderTemplateString(titleTemplate, title)}</title>
+			<meta name="description" content={renderTemplateString(descriptionTemplate, description)} />
+			<meta name="theme-color" content={themeColor} />
+			<link rel="icon" href={favicon} />
+
+			{/* Twitter tags */}
+			<meta property="twitter:title" content={twitterTitle} />
+			<meta property="twitter:description" content={twitterDescription} />
+			<meta property="twitter:image" content={twitterImage} />
+			<meta property="twitter:card" content={twitterCard} />
+
+			{/* OpenGraph tags */}
+			<meta property="og:title" content={openGraphTitle} />
+			<meta property="og:description" content={openGraphDescription} />
+			<meta property="og:type" content={type} />
+			<meta property="og:image" content={openGraphImage} />
+			{Boolean(openGraphConfig?.url || canonical) && (
+				<meta property="og:url" content={openGraphConfig?.url ?? canonical} />
+			)}
+
+			{/* Link tags */}
+			{canonical && <link rel="canonical" href={canonical} />}
+
+			{/* No index, no follow */}
+			{noIndexing && <meta name="robots" content="noindex, nofollow" />}
+			{!noIndexing && <meta name="robots" content="index, follow" />}
+
+			{jsonLDs.map((json, idx) => (
+				<script
+					key={idx}
+					type="application/ld+json"
+					dangerouslySetInnerHTML={{
+						__html: JSON.stringify({
+							"@context": "https://schema.org",
+							...(json as Record<string, unknown>),
+						}),
+					}}
+				/>
+			))}
+		</>
+	);
+}
+
+export default Seo;

package/src/components/Theme.tsx

@@ -0,0 +1,47 @@
+import { useId } from "react";
+import type { Font, Variable } from "../types";
+
+export interface Props {
+	variables?: Variable[];
+	fonts?: Font[];
+	colorScheme?: "light" | "dark";
+}
+
+const withPrefersColorScheme = (scheme: "light" | "dark", css: string) =>
+	`@media (prefers-color-scheme: ${scheme}) { ${css} }`;
+
+/**
+ * Theme component — injects CSS custom properties and font stylesheets.
+ * React 19 / TanStack Start automatically hoists <style> into <head>.
+ */
+function Theme({ fonts = [], variables = [], colorScheme }: Props) {
+	const id = useId();
+
+	const family = fonts.reduce((acc, { family }) => (acc ? `${acc}, ${family}` : family), "");
+
+	const vars = [{ name: "--font-family", value: family }, ...variables]
+		.map(({ name, value }) => `${name}: ${value}`)
+		.join(";");
+
+	const css = `* {${vars}}`;
+	const html = colorScheme ? withPrefersColorScheme(colorScheme, css) : css;
+
+	return (
+		<>
+			{fonts?.map(({ styleSheet }, idx) =>
+				styleSheet ? (
+					<style key={idx} type="text/css" dangerouslySetInnerHTML={{ __html: styleSheet }} />
+				) : null,
+			)}
+			{html && (
+				<style
+					type="text/css"
+					id={`__DESIGN_SYSTEM_VARS-${id}`}
+					dangerouslySetInnerHTML={{ __html: html }}
+				/>
+			)}
+		</>
+	);
+}
+
+export default Theme;

package/src/components/Video.tsx

@@ -0,0 +1,44 @@
+/**
+ * TODO: Implement video preload with link[rel="preload"] tags once
+ * browsers support it. More info at: https://stackoverflow.com/a/68368601
+ */
+import { forwardRef } from "react";
+
+import { getOptimizedMediaUrl } from "@decocms/blocks/hooks";
+
+export interface Props {
+	src: string;
+	/** @description Improves Web Vitals (CLS|LCP) */
+	width: number;
+	/** @description Improves Web Vitals (CLS|LCP) */
+	height: number;
+	/** @description Force video through the optimization engine */
+	forceOptimizedSrc?: boolean;
+	className?: string;
+	style?: React.CSSProperties;
+	autoPlay?: boolean;
+	loop?: boolean;
+	muted?: boolean;
+	playsInline?: boolean;
+	controls?: boolean;
+	poster?: string;
+}
+
+const Video = forwardRef<HTMLVideoElement, Props>((props, ref) => {
+	const { forceOptimizedSrc, src: originalSrc, width, height, ...rest } = props;
+
+	const src = forceOptimizedSrc
+		? getOptimizedMediaUrl({
+				originalSrc,
+				width,
+				height,
+				fit: "cover",
+			})
+		: originalSrc;
+
+	return <video {...rest} preload={undefined} src={src} width={width} height={height} ref={ref} />;
+});
+
+Video.displayName = "Video";
+
+export default Video;

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Public API for the website app.
+ */
+
+export { configureWebsite, getWebsiteConfig } from "./client";
+// App
+export { configure } from "./mod";
+
+// Types
+export type {
+	FlagObj,
+	Font,
+	ImageWidget,
+	MatchContext,
+	Matcher,
+	MultivariateFlag,
+	OGType,
+	SeoConfig,
+	Variable,
+	Variant,
+	WebsiteConfig,
+} from "./types";

package/src/loaders/environment.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import EnvironmentLoader from "./environment";
+
+describe("EnvironmentLoader", () => {
+	it("reads from process.env when name is set", () => {
+		process.env.MY_ENV_VAR = "hello";
+		const result = EnvironmentLoader({ value: "fallback", name: "MY_ENV_VAR" });
+		expect(result.get()).toBe("hello");
+		delete process.env.MY_ENV_VAR;
+	});
+
+	it("returns value when env var is not set", () => {
+		const result = EnvironmentLoader({ value: "fallback", name: "NONEXISTENT_VAR" });
+		expect(result.get()).toBe("fallback");
+	});
+
+	it("returns null when value is empty", () => {
+		const result = EnvironmentLoader({ value: "" });
+		expect(result.get()).toBeNull();
+	});
+});

package/src/loaders/environment.ts

@@ -0,0 +1,45 @@
+/**
+ * @title Environment
+ * @hideOption true
+ */
+export interface Environment {
+	/** @ignore */
+	get: () => string | null;
+}
+
+export interface Props {
+	/**
+	 * @title Environment Value
+	 */
+	value: string;
+	/**
+	 * @title Environment Name
+	 * @description Used in dev mode as a environment variable (should not contain spaces or special characters)
+	 * @pattern ^[a-zA-Z_][a-zA-Z0-9_]*$
+	 */
+	name?: string;
+}
+
+const getEnvironment = (props: Props): string | null => {
+	const name = props?.name;
+	if (name && process.env[name] !== undefined) {
+		return process.env[name]!;
+	}
+	const value = props?.value;
+	if (!value) {
+		return null;
+	}
+	return value;
+};
+
+/**
+ * @title Environment
+ */
+export default function EnvironmentLoader(props: Props): Environment {
+	const environmentValue = getEnvironment(props);
+	return {
+		get: (): string | null => {
+			return environmentValue;
+		},
+	};
+}

package/src/loaders/fonts/googleFonts.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import googleFonts from "./googleFonts";
+
+describe("googleFonts", () => {
+	let fetchSpy: ReturnType<typeof vi.fn>;
+
+	beforeEach(() => {
+		fetchSpy = vi.fn();
+		vi.stubGlobal("fetch", fetchSpy);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("returns empty font for no fonts", async () => {
+		const result = await googleFonts({ fonts: [] });
+		expect(result.family).toBe("");
+		expect(result.styleSheet).toBe("");
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it("fetches Google Fonts CSS with two User-Agents", async () => {
+		fetchSpy.mockResolvedValue({ text: () => Promise.resolve("/* css */") });
+
+		const result = await googleFonts({
+			fonts: [{ family: "Inter", variations: [{ weight: "400" }] }],
+		});
+
+		expect(fetchSpy).toHaveBeenCalledTimes(2);
+		expect(result.family).toBe("Inter");
+		expect(result.styleSheet).toContain("/* css */");
+	});
+
+	it("handles fetch errors gracefully", async () => {
+		fetchSpy.mockRejectedValue(new Error("Network error"));
+
+		const result = await googleFonts({
+			fonts: [{ family: "Roboto", variations: [{ weight: "400" }] }],
+		});
+
+		expect(result.family).toBe("Roboto");
+		expect(result.styleSheet).toBe("\n");
+	});
+
+	it("merges duplicate font families", async () => {
+		fetchSpy.mockResolvedValue({ text: () => Promise.resolve("") });
+
+		await googleFonts({
+			fonts: [
+				{ family: "Inter", variations: [{ weight: "400" }] },
+				{ family: "Inter", variations: [{ weight: "700" }] },
+			],
+		});
+
+		// Should only have one "family" param for "Inter" with merged variations
+		const calledUrl = fetchSpy.mock.calls[0][0] as URL;
+		const families = calledUrl.searchParams.getAll("family");
+		expect(families).toHaveLength(1);
+		expect(families[0]).toContain("Inter");
+	});
+});