@hoardodile/ui 0.0.0

package/src/components/caption-bar.test.tsx

@@ -0,0 +1,151 @@
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import {
+	CaptionBar,
+	type CaptionHistoryControls,
+	type CaptionWindowControls,
+} from "./caption-bar"
+
+function fakeControls(
+	overrides: Partial<CaptionWindowControls> = {},
+): CaptionWindowControls {
+	return {
+		minimize: vi.fn(),
+		toggleMaximize: vi.fn(),
+		close: vi.fn(),
+		isMaximized: async () => false,
+		onMaximizedChange: () => () => undefined,
+		...overrides,
+	}
+}
+
+function fakeHistory(
+	overrides: Partial<CaptionHistoryControls> = {},
+): CaptionHistoryControls {
+	return {
+		canGoBack: true,
+		canGoForward: true,
+		back: vi.fn(),
+		forward: vi.fn(),
+		reload: vi.fn(),
+		...overrides,
+	}
+}
+
+describe("CaptionBar", () => {
+	it("invokes window controls from the caption buttons", async () => {
+		const user = userEvent.setup()
+		const controls = fakeControls()
+		render(<CaptionBar controls={controls} history={fakeHistory()} />)
+
+		await user.click(screen.getByTestId("desktop-caption-minimize"))
+		await user.click(screen.getByTestId("desktop-caption-maximize"))
+		await user.click(screen.getByTestId("desktop-caption-close"))
+
+		expect(controls.minimize).toHaveBeenCalledTimes(1)
+		expect(controls.toggleMaximize).toHaveBeenCalledTimes(1)
+		expect(controls.close).toHaveBeenCalledTimes(1)
+		expect(screen.queryByText("hoardodile")).toBeNull()
+	})
+
+	it("hides the DevTools button when the control is absent", () => {
+		render(<CaptionBar controls={fakeControls()} history={fakeHistory()} />)
+		expect(screen.queryByTestId("desktop-caption-devtools")).toBeNull()
+	})
+
+	it("toggles DevTools from the caption button", async () => {
+		const user = userEvent.setup()
+		const toggleDevtools = vi.fn()
+		render(
+			<CaptionBar
+				controls={fakeControls({ toggleDevtools })}
+				history={fakeHistory()}
+			/>,
+		)
+		await user.click(screen.getByTestId("desktop-caption-devtools"))
+		expect(toggleDevtools).toHaveBeenCalledTimes(1)
+	})
+
+	it("does not double-toggle on double-click of the drag region (native handles it)", async () => {
+		const user = userEvent.setup()
+		const controls = fakeControls()
+		render(<CaptionBar controls={controls} history={fakeHistory()} />)
+
+		await user.dblClick(screen.getByTestId("desktop-caption-drag"))
+		expect(controls.toggleMaximize).not.toHaveBeenCalled()
+	})
+
+	it("keeps reload a plain browser reload (never routed through the desktop bridge)", async () => {
+		const user = userEvent.setup()
+		const retryLoad = vi.fn()
+		Reflect.set(window, "hoardodileDesktop", { retryLoad })
+		try {
+			render(<CaptionBar controls={fakeControls()} />)
+			await user.click(screen.getByTestId("desktop-caption-reload"))
+			expect(retryLoad).not.toHaveBeenCalled()
+		} finally {
+			Reflect.deleteProperty(window, "hoardodileDesktop")
+		}
+	})
+
+	it("blurs a caption button focused during load so no stray ring persists", async () => {
+		const { unmount } = render(
+			<CaptionBar controls={fakeControls()} history={fakeHistory()} />,
+		)
+		const back = screen.getByTestId("desktop-caption-back")
+		back.focus()
+		expect(document.activeElement).toBe(back)
+		window.dispatchEvent(new Event("load"))
+		expect(document.activeElement).not.toBe(back)
+		unmount()
+	})
+
+	it("invokes history controls from the navigation buttons", async () => {
+		const user = userEvent.setup()
+		const history = fakeHistory()
+		render(<CaptionBar controls={fakeControls()} history={history} />)
+
+		await user.click(screen.getByTestId("desktop-caption-back"))
+		await user.click(screen.getByTestId("desktop-caption-forward"))
+		await user.click(screen.getByTestId("desktop-caption-reload"))
+
+		expect(history.back).toHaveBeenCalledTimes(1)
+		expect(history.forward).toHaveBeenCalledTimes(1)
+		expect(history.reload).toHaveBeenCalledTimes(1)
+	})
+
+	it("disables back and forward when the stack cannot move", () => {
+		render(
+			<CaptionBar
+				controls={fakeControls()}
+				history={fakeHistory({ canGoBack: false, canGoForward: false })}
+			/>,
+		)
+
+		expect(screen.getByTestId("desktop-caption-back")).toBeDisabled()
+		expect(screen.getByTestId("desktop-caption-forward")).toBeDisabled()
+		expect(screen.getByTestId("desktop-caption-reload")).toBeEnabled()
+	})
+
+	it("renders the leading slot leftmost, before the history buttons", () => {
+		render(
+			<CaptionBar
+				controls={fakeControls()}
+				history={fakeHistory()}
+				leading={
+					<button type="button" data-testid="desktop-caption-leading">
+						menu
+					</button>
+				}
+			/>,
+		)
+
+		const leading = screen.getByTestId("desktop-caption-leading")
+		const back = screen.getByTestId("desktop-caption-back")
+		expect(screen.getByTestId("desktop-caption-bar")).toContainElement(leading)
+		expect(
+			leading.compareDocumentPosition(back) & Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy()
+	})
+})

package/src/components/caption-bar.tsx

@@ -0,0 +1,392 @@
+"use client"
+
+import { Icon } from "@hoardodile/ui/components/icon"
+import { Refresh } from "@hoardodile/ui/icons/registry"
+import { cn } from "@hoardodile/ui/lib/utils"
+import { type ReactNode, useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+export type CaptionWindowControls = {
+	minimize: () => void
+	toggleMaximize: () => void
+	close: () => void
+	/**
+	 * Toggle the DevTools dock. Present only on dev (unpackaged) runs —
+	 * the desktop bridge carries it only there, so packaged builds never
+	 * render the button.
+	 */
+	toggleDevtools?: () => void
+	isMaximized: () => Promise<boolean>
+	onMaximizedChange: (listener: (maximized: boolean) => void) => () => void
+}
+
+const captionChromeButtonClassName =
+	"flex h-nav w-[46px] items-center justify-center text-secondary-foreground enabled:hover:bg-muted enabled:hover:text-foreground disabled:text-muted-foreground focus:outline-none focus-visible:outline-none focus-visible:ring-0"
+
+export type CaptionHistoryControls = {
+	readonly canGoBack: boolean
+	readonly canGoForward: boolean
+	back: () => void
+	forward: () => void
+	reload: () => void
+}
+
+export type CaptionBarProps = {
+	readonly controls: CaptionWindowControls
+	/** Test seam; production uses the window history stack. */
+	readonly history?: CaptionHistoryControls
+	/**
+	 * Leftmost slot in the strip's no-drag group, before back / forward /
+	 * reload. Used by the SPA to host the global sidebar toggle below the
+	 * sidebar breakpoint; the wizard leaves it empty.
+	 */
+	readonly leading?: ReactNode
+	readonly className?: string
+}
+
+/**
+ * Frameless-window caption strip (DESIGN.md: 38px `h-nav`). An optional
+ * `leading` control, then back / forward / reload on the left; drag region
+ * in the middle; Windows caption buttons on the right. Shared by the
+ * first-run wizard and the SPA so the two pages cannot drift.
+ */
+function CaptionBar({
+	controls,
+	history,
+	leading,
+	className,
+}: CaptionBarProps) {
+	const { t } = useTranslation("ui", { useSuspense: false })
+	const windowHistory = useWindowHistoryControls()
+	const nav = history ?? windowHistory
+	const [maximized, setMaximized] = useState(false)
+
+	useEffect(() => {
+		let cancelled = false
+		void controls.isMaximized().then((value) => {
+			if (!cancelled) setMaximized(value)
+		})
+		const unsubscribe = controls.onMaximizedChange(setMaximized)
+		return () => {
+			cancelled = true
+			unsubscribe()
+		}
+	}, [controls])
+
+	// Chromium may restore focus to the last-focused caption button when
+	// the window or session comes back, leaving a stray focus ring on the
+	// chrome. Clear focus only when it sits on a caption button — never
+	// blur an input the user is typing into. Runs at mount (restored focus
+	// may already be present) and again on load (restored afterwards).
+	useEffect(() => {
+		function clearChromeFocus() {
+			const el = document.activeElement
+			if (
+				el instanceof HTMLElement &&
+				el.closest('[data-testid="desktop-caption-bar"]') !== null
+			) {
+				el.blur()
+			}
+		}
+		clearChromeFocus()
+		window.addEventListener("load", clearChromeFocus)
+		return () => {
+			window.removeEventListener("load", clearChromeFocus)
+		}
+	}, [])
+
+	return (
+		<div
+			data-testid="desktop-caption-bar"
+			className={cn(
+				"flex h-nav shrink-0 select-none items-stretch bg-background text-foreground",
+				className
+			)}
+		>
+			<div className="flex shrink-0 [-webkit-app-region:no-drag]">
+				{leading}
+				<button
+					type="button"
+					title={t("caption.back")}
+					aria-label={t("caption.back")}
+					data-testid="desktop-caption-back"
+					disabled={!nav.canGoBack}
+					className={captionChromeButtonClassName}
+					onClick={() => {
+						nav.back()
+					}}
+				>
+					<ChevronLeftGlyph />
+				</button>
+				<button
+					type="button"
+					title={t("caption.forward")}
+					aria-label={t("caption.forward")}
+					data-testid="desktop-caption-forward"
+					disabled={!nav.canGoForward}
+					className={captionChromeButtonClassName}
+					onClick={() => {
+						nav.forward()
+					}}
+				>
+					<ChevronRightGlyph />
+				</button>
+				<button
+					type="button"
+					title={t("caption.reload")}
+					aria-label={t("caption.reload")}
+					data-testid="desktop-caption-reload"
+					className={captionChromeButtonClassName}
+					onClick={() => {
+						nav.reload()
+					}}
+				>
+					<Icon icon={Refresh} />
+				</button>
+			</div>
+			<div
+				data-testid="desktop-caption-drag"
+				className="min-w-0 flex-1 [-webkit-app-region:drag]"
+			/>
+			{/* Double-click toggles maximize natively on Windows drag regions;
+			    a JS handler here would double-toggle (native + JS). */}
+			<div className="flex shrink-0 [-webkit-app-region:no-drag]">
+				{controls.toggleDevtools !== undefined ? (
+					<button
+						type="button"
+						title={t("caption.devtools")}
+						aria-label={t("caption.devtools")}
+						data-testid="desktop-caption-devtools"
+						className={captionChromeButtonClassName}
+						onClick={() => {
+							controls.toggleDevtools?.()
+						}}
+					>
+						<DevToolsGlyph />
+					</button>
+				) : null}
+				<button
+					type="button"
+					aria-label={t("caption.minimize")}
+					data-testid="desktop-caption-minimize"
+					className={captionChromeButtonClassName}
+					onClick={() => {
+						controls.minimize()
+					}}
+				>
+					<MinimizeGlyph />
+				</button>
+				<button
+					type="button"
+					aria-label={maximized ? t("caption.restore") : t("caption.maximize")}
+					data-testid="desktop-caption-maximize"
+					className={captionChromeButtonClassName}
+					onClick={() => {
+						controls.toggleMaximize()
+					}}
+				>
+					{maximized ? <RestoreGlyph /> : <MaximizeGlyph />}
+				</button>
+				<button
+					type="button"
+					aria-label={t("caption.close")}
+					data-testid="desktop-caption-close"
+					className="flex h-nav w-[46px] items-center justify-center text-secondary-foreground hover:bg-[#c42b1c] hover:text-white"
+					onClick={() => {
+						controls.close()
+					}}
+				>
+					<CloseGlyph />
+				</button>
+			</div>
+		</div>
+	)
+}
+
+type WindowNavigationSource = {
+	readonly canGoBack: boolean
+	readonly canGoForward: boolean
+	addEventListener: (type: string, listener: () => void) => void
+	removeEventListener: (type: string, listener: () => void) => void
+}
+
+function isWindowNavigationSource(
+	value: unknown,
+): value is WindowNavigationSource {
+	if (typeof value !== "object" || value === null) return false
+	if (!("canGoBack" in value) || typeof value.canGoBack !== "boolean") {
+		return false
+	}
+	if (!("canGoForward" in value) || typeof value.canGoForward !== "boolean") {
+		return false
+	}
+	if (
+		!("addEventListener" in value) ||
+		typeof value.addEventListener !== "function"
+	) {
+		return false
+	}
+	if (
+		!("removeEventListener" in value) ||
+		typeof value.removeEventListener !== "function"
+	) {
+		return false
+	}
+	return true
+}
+
+function readWindowNavigation(): WindowNavigationSource | undefined {
+	if (typeof window === "undefined") return undefined
+	const value = Reflect.get(window, "navigation")
+	return isWindowNavigationSource(value) ? value : undefined
+}
+
+function useWindowHistoryControls(): CaptionHistoryControls {
+	const [canGoBack, setCanGoBack] = useState(false)
+	const [canGoForward, setCanGoForward] = useState(false)
+
+	useEffect(() => {
+		function sync() {
+			const source = readWindowNavigation()
+			if (source !== undefined) {
+				setCanGoBack(source.canGoBack)
+				setCanGoForward(source.canGoForward)
+				return
+			}
+			setCanGoBack(window.history.length > 1)
+			setCanGoForward(false)
+		}
+
+		sync()
+		const source = readWindowNavigation()
+		if (source !== undefined) {
+			source.addEventListener("currententrychange", sync)
+			return () => {
+				source.removeEventListener("currententrychange", sync)
+			}
+		}
+		window.addEventListener("popstate", sync)
+		return () => {
+			window.removeEventListener("popstate", sync)
+		}
+	}, [])
+
+	// Plain browser reload. The app's own first frame (index.html splash)
+	// covers the pre-paint gap, so routing this through the desktop shell
+	// would only add unnecessary hops.
+	function reload() {
+		window.location.reload()
+	}
+
+	return {
+		canGoBack,
+		canGoForward,
+		back() {
+			window.history.back()
+		},
+		forward() {
+			window.history.forward()
+		},
+		reload,
+	}
+}
+
+function ChevronLeftGlyph() {
+	return (
+		<svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
+			<path
+				d="M10 3.5L5 8l5 4.5"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1.5"
+			/>
+		</svg>
+	)
+}
+
+function ChevronRightGlyph() {
+	return (
+		<svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true">
+			<path
+				d="M6 3.5L11 8l-5 4.5"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1.5"
+			/>
+		</svg>
+	)
+}
+
+function MinimizeGlyph() {
+	return (
+		<svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+			<path d="M0 5h10" fill="none" stroke="currentColor" strokeWidth="1" />
+		</svg>
+	)
+}
+
+function DevToolsGlyph() {
+	return (
+		<svg width="14" height="14" viewBox="0 0 14 14" aria-hidden="true">
+			<path
+				d="M4.5 4.5L2 7l2.5 2.5M9.5 4.5L12 7l-2.5 2.5"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1"
+			/>
+		</svg>
+	)
+}
+
+function MaximizeGlyph() {
+	return (
+		<svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+			<rect
+				x="0.5"
+				y="0.5"
+				width="9"
+				height="9"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1"
+			/>
+		</svg>
+	)
+}
+
+function RestoreGlyph() {
+	return (
+		<svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+			<rect
+				x="2.5"
+				y="0.5"
+				width="7"
+				height="7"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1"
+			/>
+			<path
+				d="M0.5 2.5h7v7h-7z"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1"
+			/>
+		</svg>
+	)
+}
+
+function CloseGlyph() {
+	return (
+		<svg width="10" height="10" viewBox="0 0 10 10" aria-hidden="true">
+			<path
+				d="M1 1l8 8M9 1L1 9"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1"
+			/>
+		</svg>
+	)
+}
+
+export { CaptionBar }

package/src/components/chart-card.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react"
+
+/**
+ * Chart card — the stats page's standard chart surface: a floating card
+ * with the chart's name and a muted trailing note, the chart below.
+ */
+export function ChartCard({
+	title,
+	subtitle,
+	children,
+	className,
+}: {
+	readonly title: string
+	readonly subtitle: string
+	readonly children: ReactNode
+	readonly className?: string
+}) {
+	return (
+		<div
+			className={`rounded-xl border border-border bg-card p-5 shadow-card ${className ?? ""}`}
+		>
+			<div className="flex items-baseline justify-between gap-3">
+				<span className="text-ui font-semibold text-foreground">{title}</span>
+				<span className="shrink-0 text-tiny text-muted-foreground">
+					{subtitle}
+				</span>
+			</div>
+			<div className="mt-4">{children}</div>
+		</div>
+	)
+}

package/src/components/checkbox.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+import { Check } from "@hoardodile/ui/icons/marks"
+
+function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        "peer relative flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-sm bg-muted outline-none group-has-disabled/field:opacity-50 focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:bg-destructive/20 aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-checked:bg-primary data-checked:text-primary-foreground",
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current [&>svg]:size-3"
+      >
+        <Check />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  )
+}
+
+export { Checkbox }

package/src/components/chip-button.tsx

@@ -0,0 +1,69 @@
+import type { IconType } from "@hoardodile/ui/components/icon"
+import { Icon } from "@hoardodile/ui/components/icon"
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+export type ChipButtonProps = {
+	readonly icon?: IconType
+	/** Latched-toggle state — accent fill, no hover shift. */
+	readonly active?: boolean
+	/** The dashed outline (the Unused triage filter) instead of the quiet
+	    text idle state. */
+	readonly dashed?: boolean
+	readonly disabled?: boolean
+	readonly children: ReactNode
+	readonly className?: string
+	readonly onClick?: () => void
+	readonly testId?: string
+}
+
+/**
+ * Chip button: the toolbar's compact toggle, h-chip height. Two kinds:
+ * the quiet toggle (Reorder) wears medium weight in both states so its
+ * width never moves; the dashed filter (Unused) is an indicator, not a
+ * toggle, so it stays regular weight with a dashed outline. `active`
+ * latches the accent fill on both; the dashed outline keeps a transparent
+ * border when active so the width never shifts.
+ */
+export function ChipButton(props: ChipButtonProps) {
+	const {
+		icon,
+		active,
+		dashed,
+		disabled,
+		children,
+		className,
+		onClick,
+		testId,
+	} = props
+	return (
+		<button
+			type="button"
+			onClick={disabled ? undefined : onClick}
+			data-testid={testId}
+			disabled={disabled}
+			className={cn(
+				"inline-flex h-chip shrink-0 items-center gap-1.5 rounded-md px-2.5 text-xs whitespace-nowrap",
+				!dashed && "font-medium",
+				disabled ? "cursor-default" : "cursor-pointer",
+				active && "bg-accent text-foreground",
+				// The dashed outline keeps a 1px transparent border when
+				// active so the width never moves with the state.
+				active && dashed && "border border-transparent",
+				!active && disabled && "text-muted-foreground",
+				!active &&
+					!disabled &&
+					dashed &&
+					"border border-dashed border-border-strong bg-card text-muted-foreground hover:text-secondary-foreground",
+				!active &&
+					!disabled &&
+					!dashed &&
+					"text-secondary-foreground hover:text-foreground",
+				className,
+			)}
+		>
+			{icon !== undefined ? <Icon icon={icon} /> : null}
+			{children}
+		</button>
+	)
+}