emdash-header-footer-code 0.1.0

package/src/admin/SnippetList.tsx

@@ -0,0 +1,282 @@
+import { Badge, Button, Dialog, DropdownMenu, Empty, Input, Select, Switch, Table, cn } from "@cloudflare/kumo";
+import * as React from "react";
+import { PLACEMENTS } from "../core/types.js";
+import type { SnippetSummary } from "./api.js";
+import {
+	PLACEMENT_LABEL,
+	type PlacementFilter,
+	filterSnippets,
+	formatTimestamp,
+	relativeTime,
+	userLabel,
+	whereSummary,
+} from "./format.js";
+import { CodeIcon, CopyIcon, DotsIcon, PencilIcon, PlusIcon, SearchIcon, TrashIcon } from "./icons.js";
+
+const FILTER_ITEMS: Record<PlacementFilter, string> = {
+	all: "All placements",
+	...Object.fromEntries(PLACEMENTS.map((p) => [p, PLACEMENT_LABEL[p]])),
+} as Record<PlacementFilter, string>;
+
+/** Clicks on these (or inside them) never open the row's editor. */
+const INTERACTIVE = "button, a, input, label, select, textarea, [role='switch'], [role='menuitem']";
+
+/** Re-render every minute so relative times stay current. */
+function useNow(): number {
+	const [now, setNow] = React.useState(() => Date.now());
+	React.useEffect(() => {
+		const t = setInterval(() => setNow(Date.now()), 60_000);
+		return () => clearInterval(t);
+	}, []);
+	return now;
+}
+
+export function SnippetList(props: {
+	snippets: SnippetSummary[];
+	canManage: boolean;
+	onNew: () => void;
+	onToggle: (id: string, enabled: boolean) => void;
+	onEdit: (id: string) => void;
+	onDuplicate: (id: string) => void;
+	onDelete: (id: string) => Promise<void>;
+}) {
+	const { snippets, canManage } = props;
+	const now = useNow();
+	const [query, setQuery] = React.useState("");
+	const [placement, setPlacement] = React.useState<PlacementFilter>("all");
+	const [confirming, setConfirming] = React.useState<SnippetSummary | null>(null);
+	const [deleting, setDeleting] = React.useState(false);
+
+	const visible = filterSnippets(snippets, { query, placement });
+
+	async function confirmDelete() {
+		if (!confirming) return;
+		setDeleting(true);
+		try {
+			await props.onDelete(confirming.id);
+		} finally {
+			setDeleting(false);
+			setConfirming(null);
+		}
+	}
+
+	if (snippets.length === 0) {
+		return (
+			<Empty
+				icon={<CodeIcon size={40} className="text-kumo-subtle" />}
+				title="No snippets yet"
+				description={
+					canManage
+						? "Add analytics, verification tags, chat widgets or custom CSS and JavaScript to your pages."
+						: "An administrator hasn't added any snippets."
+				}
+				contents={
+					canManage ? (
+						<Button variant="primary" icon={<PlusIcon />} onClick={props.onNew}>
+							New snippet
+						</Button>
+					) : undefined
+				}
+			/>
+		);
+	}
+
+	return (
+		<>
+			<div className="flex flex-col gap-3 border-b border-kumo-line p-4 sm:flex-row sm:items-center">
+				<div className="relative w-full sm:w-72">
+					<span className="pointer-events-none absolute start-3 top-1/2 -translate-y-1/2 text-kumo-subtle">
+						<SearchIcon />
+					</span>
+					<Input
+						type="search"
+						data-testid="hfc-search"
+						aria-label="Search snippets by name"
+						placeholder="Search by name…"
+						className="w-full ps-9"
+						value={query}
+						onChange={(e: React.ChangeEvent<HTMLInputElement>) => setQuery(e.target.value)}
+					/>
+				</div>
+				<div data-testid="hfc-filter-placement" className="w-full sm:w-48">
+					<Select
+						aria-label="Filter by placement"
+						className="w-full"
+						value={placement}
+						onValueChange={(v) => setPlacement((v as PlacementFilter | null) ?? "all")}
+						items={FILTER_ITEMS}
+					/>
+				</div>
+				<p className="whitespace-nowrap text-sm text-kumo-subtle sm:ms-auto">
+					{visible.length === snippets.length
+						? `${snippets.length} ${snippets.length === 1 ? "snippet" : "snippets"}`
+						: `${visible.length} of ${snippets.length}`}
+				</p>
+			</div>
+
+			{visible.length === 0 ? (
+				<Empty
+					size="sm"
+					icon={<SearchIcon size={32} className="text-kumo-subtle" />}
+					title="No matches"
+					description="No snippets match your search or filter."
+					contents={
+						<Button
+							variant="secondary"
+							onClick={() => {
+								setQuery("");
+								setPlacement("all");
+							}}
+						>
+							Clear filters
+						</Button>
+					}
+				/>
+			) : (
+				<div className="overflow-x-auto">
+					<Table>
+						<Table.Header>
+							<Table.Row>
+								<Table.Head>Name</Table.Head>
+								{/* Below lg (e.g. ~820px next to the sidebar) Placement, Priority and Updated give way so
+								    Enabled and the actions fit; the where-summary line still starts with the placement. */}
+								<Table.Head className="hidden lg:table-cell">Placement</Table.Head>
+								<Table.Head className="hidden lg:table-cell">Priority</Table.Head>
+								<Table.Head>Enabled</Table.Head>
+								<Table.Head className="hidden lg:table-cell">Updated</Table.Head>
+								{canManage && (
+									<Table.Head>
+										<span className="sr-only">Actions</span>
+									</Table.Head>
+								)}
+							</Table.Row>
+						</Table.Header>
+						<Table.Body>
+							{visible.map((s) => (
+								<Table.Row
+									key={s.id}
+									data-testid={`hfc-row-${s.id}`}
+									className={cn(canManage && "hfc-row-clickable", !s.enabled && "hfc-row-off")}
+									onClick={
+										canManage
+											? (e: React.MouseEvent<HTMLTableRowElement>) => {
+													const target = e.target as Element;
+													// Portaled menus bubble React events here too; only real in-row clicks count.
+													if (!e.currentTarget.contains(target) || target.closest(INTERACTIVE)) return;
+													props.onEdit(s.id);
+												}
+											: undefined
+									}
+								>
+									<Table.Cell className="hfc-dim">
+										<div className="font-medium text-kumo-default">{s.name}</div>
+										<div className="hfc-where truncate text-sm text-kumo-subtle" title={whereSummary(s)}>
+											{whereSummary(s)}
+										</div>
+									</Table.Cell>
+									<Table.Cell className="hfc-dim hidden lg:table-cell">
+										<Badge variant="secondary">{PLACEMENT_LABEL[s.placement]}</Badge>
+									</Table.Cell>
+									<Table.Cell className="hfc-dim hidden tabular-nums lg:table-cell">{s.priority}</Table.Cell>
+									<Table.Cell className="whitespace-nowrap">
+										{canManage ? (
+											<Switch
+												size="sm"
+												data-testid={`hfc-row-toggle-${s.id}`}
+												checked={s.enabled}
+												onCheckedChange={(v: boolean) => props.onToggle(s.id, v)}
+												label={s.enabled ? "On" : "Off"}
+												aria-label={`${s.enabled ? "On" : "Off"} — ${s.name}`}
+											/>
+										) : (
+											<Badge variant={s.enabled ? "success" : "secondary"}>{s.enabled ? "On" : "Off"}</Badge>
+										)}
+									</Table.Cell>
+									<Table.Cell className="hfc-dim hidden whitespace-nowrap lg:table-cell">
+										<div className="text-sm text-kumo-default" title={formatTimestamp(s.updatedAt)}>
+											{relativeTime(s.updatedAt, now)}
+										</div>
+										<div className="text-sm text-kumo-subtle">{userLabel(s.updatedBy)}</div>
+									</Table.Cell>
+									{canManage && (
+										<Table.Cell>
+											<div className="flex items-center justify-end gap-1">
+												<Button
+													variant="secondary"
+													size="sm"
+													icon={<PencilIcon size={14} />}
+													data-testid={`hfc-row-edit-${s.id}`}
+													onClick={() => props.onEdit(s.id)}
+												>
+													Edit
+												</Button>
+												<DropdownMenu>
+													<DropdownMenu.Trigger
+														render={
+															<Button
+																variant="ghost"
+																size="sm"
+																shape="square"
+																icon={<DotsIcon />}
+																aria-label={`More actions for ${s.name}`}
+																data-testid={`hfc-row-menu-${s.id}`}
+															/>
+														}
+													/>
+													<DropdownMenu.Content align="end">
+														<DropdownMenu.Item
+															icon={<CopyIcon size={14} className="me-2" />}
+															data-testid={`hfc-row-duplicate-${s.id}`}
+															onClick={() => props.onDuplicate(s.id)}
+														>
+															Duplicate
+														</DropdownMenu.Item>
+														<DropdownMenu.Separator />
+														<DropdownMenu.Item
+															variant="danger"
+															icon={<TrashIcon size={14} className="me-2" />}
+															data-testid={`hfc-row-delete-${s.id}`}
+															onClick={() => setConfirming(s)}
+														>
+															Delete
+														</DropdownMenu.Item>
+													</DropdownMenu.Content>
+												</DropdownMenu>
+											</div>
+										</Table.Cell>
+									)}
+								</Table.Row>
+							))}
+						</Table.Body>
+					</Table>
+				</div>
+			)}
+
+			<Dialog.Root
+				role="alertdialog"
+				open={confirming !== null}
+				onOpenChange={(o) => !o && !deleting && setConfirming(null)}
+			>
+				<Dialog className="max-w-md p-6" size="sm">
+					<Dialog.Title className="text-lg font-semibold">Delete snippet?</Dialog.Title>
+					<Dialog.Description className="text-kumo-subtle">
+						“{confirming?.name}” will stop rendering on every page. This cannot be undone.
+					</Dialog.Description>
+					<div className="mt-6 flex justify-end gap-2">
+						<Button variant="secondary" disabled={deleting} onClick={() => setConfirming(null)}>
+							Cancel
+						</Button>
+						<Button
+							variant="destructive"
+							data-testid="hfc-confirm-delete"
+							loading={deleting}
+							onClick={() => void confirmDelete()}
+						>
+							Delete
+						</Button>
+					</div>
+				</Dialog>
+			</Dialog.Root>
+		</>
+	);
+}

package/src/admin/SnippetsPage.tsx

@@ -0,0 +1,285 @@
+import {
+	Badge,
+	Banner,
+	Button,
+	Dialog,
+	LayerCard,
+	Loader,
+	Switch,
+	Tabs,
+	Toasty,
+	useKumoToastManager,
+} from "@cloudflare/kumo";
+import * as React from "react";
+import { emptyDraft } from "../core/fields.js";
+import { api, type ListResponse } from "./api.js";
+import { ChangeLog } from "./ChangeLog.js";
+import { InfoIcon, PlusIcon, WarningIcon } from "./icons.js";
+import { type Draft, SnippetForm } from "./SnippetForm.js";
+import { SnippetList } from "./SnippetList.js";
+import { HfcStyles } from "./styles.js";
+
+type View = { kind: "list" } | { kind: "edit"; draft: Draft };
+type Tab = "snippets" | "changelog";
+type Notify = (title: string, variant?: "success" | "error") => void;
+
+/** True when an ancestor (the EmDash admin shell) already provides Kumo's toast manager. */
+function useHasToastProvider(): boolean {
+	// Deliberate try/catch around a hook: Kumo's useKumoToastManager reads its context and throws
+	// when there is no provider. The hook is called on every render either way, so hook order is
+	// stable; we only use the throw as a "no provider here" signal.
+	try {
+		useKumoToastManager();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function useNotify(): Notify {
+	const toasts = useKumoToastManager();
+	return React.useCallback<Notify>((title, variant = "success") => toasts.add({ title, variant }), [toasts]);
+}
+
+/**
+ * EmDash's admin wraps pages in Kumo's <Toasty>. If this page ever renders where that provider is
+ * a different Kumo instance (or missing), provide one locally instead of crashing.
+ */
+export function SnippetsPage() {
+	const hasProvider = useHasToastProvider();
+	// `hfc-root` scopes our styles and marks the plugin's own UI (e2e accessibility checks run here).
+	const page = (
+		<div className="hfc-root" data-testid="hfc-root">
+			<HfcStyles />
+			<SnippetsScreen />
+		</div>
+	);
+	return hasProvider ? page : <Toasty>{page}</Toasty>;
+}
+
+function SnippetsScreen() {
+	const notify = useNotify();
+	const [tab, setTab] = React.useState<Tab>("snippets");
+	const [view, setView] = React.useState<View>({ kind: "list" });
+	const [data, setData] = React.useState<ListResponse | null>(null);
+	const [error, setError] = React.useState<string | null>(null);
+	const [confirmKill, setConfirmKill] = React.useState(false);
+	const [killPending, setKillPending] = React.useState(false);
+	const [killError, setKillError] = React.useState<string | null>(null);
+
+	const refresh = React.useCallback(() => {
+		return api.list().then(setData, (e: unknown) => setError(e instanceof Error ? e.message : String(e)));
+	}, []);
+	React.useEffect(() => {
+		void refresh();
+	}, [refresh]);
+
+	/** Run a mutation, report failures in the page banner, toast success, then reload the list. */
+	async function run(action: () => Promise<unknown>, success?: string): Promise<boolean> {
+		setError(null);
+		let ok = false;
+		try {
+			await action();
+			ok = true;
+			if (success) notify(success);
+		} catch (e) {
+			setError(e instanceof Error ? e.message : String(e));
+		}
+		await refresh();
+		return ok;
+	}
+
+	async function openEditor(id: string) {
+		setError(null);
+		try {
+			const { snippet } = await api.get(id);
+			setView({ kind: "edit", draft: snippet });
+		} catch (e) {
+			setError(e instanceof Error ? e.message : String(e));
+		}
+	}
+
+	/** Turning output off happens from the confirm Dialog, so its failure is shown there. */
+	async function setOutput(enabled: boolean) {
+		setKillPending(true);
+		setKillError(null);
+		setError(null);
+		try {
+			await api.setKillSwitch(!enabled);
+			notify(enabled ? "Snippet output turned on" : "All snippet output turned off");
+			setConfirmKill(false);
+		} catch (e) {
+			const message = e instanceof Error ? e.message : String(e);
+			if (enabled) setError(message);
+			else setKillError(message);
+		} finally {
+			setKillPending(false);
+			await refresh();
+		}
+	}
+
+	function closeKillDialog() {
+		setConfirmKill(false);
+		setKillError(null);
+	}
+
+	if (view.kind === "edit") {
+		return (
+			<SnippetForm
+				key={view.draft.id ?? "new"}
+				initial={view.draft}
+				onClose={() => setView({ kind: "list" })}
+				onSaved={() => {
+					notify("Snippet saved");
+					setView({ kind: "list" });
+					void refresh();
+				}}
+			/>
+		);
+	}
+
+	const canManage = data?.canManage ?? false;
+	const snippetIds = new Set(data?.snippets.map((s) => s.id) ?? []);
+	const list = data ? (
+		<SnippetList
+			snippets={data.snippets}
+			canManage={canManage}
+			onNew={() => setView({ kind: "edit", draft: emptyDraft() })}
+			onToggle={(id, enabled) => void run(() => api.toggle(id, enabled))}
+			onEdit={(id) => void openEditor(id)}
+			onDuplicate={(id) => void run(() => api.duplicate(id), "Snippet duplicated")}
+			onDelete={async (id) => {
+				await run(() => api.remove(id), "Snippet deleted");
+			}}
+		/>
+	) : (
+		<div className="flex justify-center py-10">
+			<Loader />
+		</div>
+	);
+
+	return (
+		<div className="space-y-6">
+			<header className="flex flex-wrap items-start justify-between gap-4">
+				<div className="min-w-0">
+					<h1 className="text-2xl font-semibold leading-tight">Header &amp; Footer Code</h1>
+					<p className="text-sm text-kumo-subtle">
+						Add analytics, verification tags and other snippets to your pages without editing the theme.
+					</p>
+				</div>
+				{canManage && data && (
+					<div className="flex flex-wrap items-center gap-4">
+						<Switch
+							data-testid="hfc-killswitch"
+							checked={!data.disabled}
+							disabled={killPending}
+							onCheckedChange={(on: boolean) => (on ? void setOutput(true) : setConfirmKill(true))}
+							label="Output enabled"
+						/>
+						<Button
+							variant="primary"
+							icon={<PlusIcon />}
+							data-testid="hfc-new"
+							onClick={() => setView({ kind: "edit", draft: emptyDraft() })}
+						>
+							New snippet
+						</Button>
+					</div>
+				)}
+			</header>
+
+			<div className="space-y-3">
+				<Banner
+					className="hfc-banner-info"
+					data-testid="hfc-theme-note"
+					icon={<InfoIcon size={20} />}
+					title="Your theme must include the EmDash page components"
+					description={
+						<>
+							Snippets only render if the layout includes <code>&lt;EmDashHead /&gt;</code>,{" "}
+							<code>&lt;EmDashBodyStart /&gt;</code> and <code>&lt;EmDashBodyEnd /&gt;</code> for the matching
+							placements. Pages served from an edge HTML cache show changes only after the cache is purged.
+						</>
+					}
+				/>
+				{data?.disabled && (
+					<Banner
+						variant="error"
+						data-testid="hfc-disabled-banner"
+						icon={<WarningIcon size={20} />}
+						title="All snippet output is disabled"
+						description="No snippet renders on any page until output is turned back on."
+					/>
+				)}
+				{error && <Banner variant="error" title="Something went wrong" description={error} />}
+			</div>
+
+			{canManage ? (
+				<div className="space-y-4">
+					<Tabs
+						className="hfc-tabs w-full max-w-full sm:w-fit"
+						listClassName="w-full"
+						indicatorClassName="hfc-tab-indicator"
+						value={tab}
+						onValueChange={(v) => setTab(v === "changelog" ? "changelog" : "snippets")}
+						tabs={[
+							{
+								value: "snippets",
+								className: "hfc-tab",
+								label: (
+									<span data-testid="hfc-tab-snippets" className="flex items-center gap-1.5">
+										Snippets
+										<Badge variant="secondary" className="hfc-tab-count">
+											{data?.snippets.length ?? 0}
+										</Badge>
+									</span>
+								),
+							},
+							{
+								value: "changelog",
+								className: "hfc-tab",
+								label: <span data-testid="hfc-tab-changelog">Change log</span>,
+							},
+						]}
+					/>
+					<LayerCard>
+						{tab === "changelog" ? <ChangeLog snippetIds={snippetIds} onOpen={(id) => void openEditor(id)} /> : list}
+					</LayerCard>
+				</div>
+			) : (
+				<LayerCard>{list}</LayerCard>
+			)}
+
+			<Dialog.Root role="alertdialog" open={confirmKill} onOpenChange={(o) => !o && !killPending && closeKillDialog()}>
+				<Dialog className="max-w-md p-6" size="sm">
+					<Dialog.Title className="text-lg font-semibold">Turn off all snippet output?</Dialog.Title>
+					<Dialog.Description className="text-kumo-subtle">
+						Every snippet stops rendering on every page, whether it is enabled or not, until you turn output back on.
+					</Dialog.Description>
+					{killError && (
+						<Banner
+							variant="error"
+							className="mt-4"
+							data-testid="hfc-killswitch-error"
+							title="Output was not turned off"
+							description={killError}
+						/>
+					)}
+					<div className="mt-6 flex justify-end gap-2">
+						<Button variant="secondary" disabled={killPending} onClick={closeKillDialog}>
+							Cancel
+						</Button>
+						<Button
+							variant="destructive"
+							data-testid="hfc-confirm-killswitch"
+							loading={killPending}
+							onClick={() => void setOutput(false)}
+						>
+							Turn off output
+						</Button>
+					</div>
+				</Dialog>
+			</Dialog.Root>
+		</div>
+	);
+}

package/src/admin/api.ts

@@ -0,0 +1,47 @@
+import { apiFetch } from "emdash/plugin-utils";
+import type { ChangeLogEntry, EditableSnippet, Snippet } from "../core/types.js";
+
+const BASE = "/_emdash/api/plugins/header-footer-code";
+
+export type SnippetSummary = Omit<Snippet, "code"> & { code?: string };
+export interface ListResponse {
+	disabled: boolean;
+	canManage: boolean;
+	snippets: SnippetSummary[];
+}
+
+export class ApiError extends Error {
+	constructor(
+		message: string,
+		public fieldErrors: Record<string, string> = {},
+	) {
+		super(message);
+	}
+}
+
+async function call<T>(route: string, payload?: unknown): Promise<T> {
+	const init: RequestInit =
+		payload === undefined
+			? { method: "GET" }
+			: { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) };
+	const res = await apiFetch(`${BASE}/${route}`, init);
+	const json = (await res.json().catch(() => ({}))) as {
+		data?: T;
+		error?: { message?: string; details?: { errors?: Record<string, string> } };
+	};
+	if (!res.ok) {
+		throw new ApiError(json.error?.message ?? `Request failed (${res.status})`, json.error?.details?.errors ?? {});
+	}
+	return json.data as T;
+}
+
+export const api = {
+	list: () => call<ListResponse>("snippets/list"),
+	get: (id: string) => call<{ snippet: Snippet }>("snippets/get", { id }),
+	save: (draft: EditableSnippet & { id?: string }) => call<{ snippet: Snippet }>("snippets/save", draft),
+	toggle: (id: string, enabled: boolean) => call<{ snippet: Snippet }>("snippets/toggle", { id, enabled }),
+	duplicate: (id: string) => call<{ snippet: Snippet }>("snippets/duplicate", { id }),
+	remove: (id: string) => call<{ deleted: true }>("snippets/delete", { id }),
+	setKillSwitch: (disabled: boolean) => call<{ disabled: boolean }>("killswitch/set", { disabled }),
+	changelog: () => call<{ entries: ChangeLogEntry[] }>("changelog/list"),
+};

package/src/admin/chips.ts

@@ -0,0 +1,51 @@
+import { validatePattern } from "../core/paths.js";
+
+/** Pure add/validate logic behind ChipInput (unit-tested in node). */
+
+export type ChipKind = "path" | "locale";
+
+const WHITESPACE = /\s/;
+const SEPARATORS = /[,\n]/;
+
+/** Returns an error message, or null when `value` (already trimmed) is a valid chip. */
+export function validateChip(value: string, kind: ChipKind): string | null {
+	if (kind === "path") return validatePattern(value);
+	if (value === "") return "Locale must not be empty";
+	if (WHITESPACE.test(value)) return "Locale must not contain spaces";
+	return null;
+}
+
+export interface AddChipsResult {
+	/** The new chip list (unchanged when nothing valid was entered). */
+	chips: string[];
+	/**
+	 * Text to leave in the input: the first invalid value only (so it never contains a separator
+	 * that would re-trigger a commit), or "" when everything was added.
+	 */
+	rest: string;
+	/** Reason the first invalid part was rejected (naming any other rejected parts), or null. */
+	error: string | null;
+}
+
+/**
+ * Add the comma/newline-separated values in `raw` to `chips`. Valid values are trimmed and
+ * added once (no duplicates); the first invalid one stays in the input with its error.
+ */
+export function addChips(chips: readonly string[], raw: string, kind: ChipKind): AddChipsResult {
+	const next = [...chips];
+	const rejected: string[] = [];
+	let error: string | null = null;
+	for (const part of raw.split(SEPARATORS)) {
+		const value = part.trim();
+		if (value === "") continue;
+		const err = validateChip(value, kind);
+		if (err) {
+			rejected.push(value);
+			error ??= err;
+			continue;
+		}
+		if (!next.includes(value)) next.push(value);
+	}
+	if (error && rejected.length > 1) error = `${error} (also rejected: ${rejected.slice(1).join(", ")})`;
+	return { chips: next, rest: rejected[0] ?? "", error };
+}