@hoardodile/ui 0.0.0

package/src/components/management-skeleton.tsx

@@ -0,0 +1,23 @@
+import { Skeleton } from "@hoardodile/ui/components/skeleton"
+import { Surface } from "@hoardodile/ui/components/surface"
+
+export type ManagementSkeletonProps = {
+	readonly chipCount?: number
+}
+
+/**
+ * Loading placeholder for a chip-based management panel.
+ */
+export function ManagementSkeleton(props: ManagementSkeletonProps) {
+	const chipCount = props.chipCount ?? 2
+	return (
+		<Surface as="section" size="compact" className="space-y-3">
+			<Skeleton className="h-4 w-28" />
+			<div className="flex flex-wrap gap-1.5">
+				{Array.from({ length: chipCount }).map((_, i) => (
+					<Skeleton key={i} className="h-8 w-24 rounded-md" />
+				))}
+			</div>
+		</Surface>
+	)
+}

package/src/components/meta-chip.tsx

@@ -0,0 +1,40 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+export type MetaChipProps = {
+	/** muted: quiet gray chip (default); inverse: foreground on background;
+	    bordered: outline-only state marker. */
+	readonly tone?: "muted" | "inverse" | "bordered"
+	readonly className?: string
+	readonly children: ReactNode
+}
+
+/**
+ * Meta chip — the tiny rounded-sm text-tiny state marker worn next to
+ * names, versions, deltas and list rows across the app.
+ */
+export function MetaChip(props: MetaChipProps) {
+	return (
+		<span
+			className={cn(
+				"shrink-0 rounded-sm px-1.5 py-0.5 text-tiny leading-none",
+				chipToneClassName(props.tone),
+				props.className,
+			)}
+		>
+			{props.children}
+		</span>
+	)
+}
+
+function chipToneClassName(tone: MetaChipProps["tone"]) {
+	if (tone === "inverse") {
+		return "bg-foreground text-background"
+	}
+
+	if (tone === "bordered") {
+		return "border border-border-strong text-muted-foreground"
+	}
+
+	return "bg-muted text-secondary-foreground"
+}

package/src/components/mobile-drawer.test.tsx

@@ -0,0 +1,52 @@
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { MobileDrawer } from "./mobile-drawer"
+
+function renderDrawer(open: boolean) {
+	return render(
+		<MobileDrawer open={open} onOpenChange={() => {}} title="Drawer">
+			<div data-testid="drawer-content">content</div>
+		</MobileDrawer>,
+	)
+}
+
+describe("MobileDrawer children gating", () => {
+	it("does not render children while closed before the first open", () => {
+		renderDrawer(false)
+		expect(screen.queryByTestId("drawer-content")).not.toBeInTheDocument()
+	})
+
+	it("renders children once open", () => {
+		renderDrawer(true)
+		expect(screen.getByTestId("drawer-content")).toBeInTheDocument()
+	})
+
+	it("keeps children mounted after closing again", () => {
+		const { rerender } = render(
+			<MobileDrawer open={false} onOpenChange={() => {}}>
+				<div data-testid="drawer-content">content</div>
+			</MobileDrawer>,
+		)
+		expect(screen.queryByTestId("drawer-content")).not.toBeInTheDocument()
+		rerender(
+			<MobileDrawer open={true} onOpenChange={() => {}}>
+				<div data-testid="drawer-content">content</div>
+			</MobileDrawer>,
+		)
+		expect(screen.getByTestId("drawer-content")).toBeInTheDocument()
+		rerender(
+			<MobileDrawer open={false} onOpenChange={() => {}}>
+				<div data-testid="drawer-content">content</div>
+			</MobileDrawer>,
+		)
+		expect(screen.getByTestId("drawer-content")).toBeInTheDocument()
+	})
+
+	it("sizes the body as a constrained flex column", () => {
+		const { container } = renderDrawer(true)
+		const body = container.querySelector("aside > div:last-child")
+		for (const token of ["flex", "min-h-0", "flex-1", "flex-col"]) {
+			expect(body?.classList.contains(token)).toBe(true)
+		}
+	})
+})

package/src/components/mobile-drawer.tsx

@@ -0,0 +1,98 @@
+import { useMobileBackToClose } from "@hoardodile/ui/hooks/useMobileBackToClose"
+import { Cross } from "@hoardodile/ui/icons/marks"
+import { cn } from "@hoardodile/ui/lib/utils"
+import { type ReactNode, useEffect, useState } from "react"
+
+export type MobileDrawerProps = {
+	readonly open: boolean
+	readonly onOpenChange: (open: boolean) => void
+	readonly side?: "left" | "right"
+	readonly width?: string
+	/**
+	 * Viewport variant at and above which the drawer is hidden. Must be a
+	 * literal class at the call site (e.g. "min-[1440px]:hidden") so
+	 * Tailwind can scan it. Defaults to "md:hidden".
+	 */
+	readonly hideAbove?: string
+	readonly title?: ReactNode
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+/**
+ * Mobile-only slide-in drawer with backdrop, close header and
+ * {@link useMobileBackToClose} integration.
+ *
+ * Renders nothing at and above the {@link MobileDrawerProps.hideAbove}
+ * breakpoint ("md" by default) — the caller is expected to provide its
+ * own desktop layout independently.
+ */
+export function MobileDrawer(props: MobileDrawerProps) {
+	const {
+		open,
+		onOpenChange,
+		side = "left",
+		width = "w-72",
+		hideAbove = "md:hidden",
+		title,
+	} = props
+	const isLeft = side === "left"
+	// Mount children only once the drawer has been opened, so closed drawers
+	// (which stay in the tree for the slide transition) do not pay for
+	// rendering their content. Once mounted they stay mounted so the close
+	// animation and any inner state survive.
+	const [hasOpened, setHasOpened] = useState(open)
+
+	useEffect(() => {
+		if (open) setHasOpened(true)
+	}, [open])
+
+	useMobileBackToClose(open, onOpenChange)
+
+	return (
+		<>
+			{open && (
+				<button
+					type="button"
+					className={cn(
+						"fixed inset-0 z-30 bg-background/60 backdrop-blur-sm",
+						hideAbove,
+					)}
+					onClick={() => onOpenChange(false)}
+				/>
+			)}
+			<aside
+				className={cn(
+					"fixed top-0 z-40 flex h-svh flex-col bg-card transition-transform duration-200",
+					hideAbove,
+					isLeft ? "left-0 border-r" : "right-0 border-l",
+					width,
+					isLeft
+						? open
+							? "translate-x-0 shadow-xl"
+							: "-translate-x-full"
+						: open
+							? "translate-x-0 shadow-xl"
+							: "translate-x-full",
+					props.className,
+				)}
+			>
+				{title !== undefined && (
+					<div className="flex items-center justify-between border-b px-3 py-3">
+						<span className="text-sm font-medium">{title}</span>
+						<button
+							type="button"
+							className="flex size-7 items-center justify-center rounded-md text-muted-foreground hover:bg-accent"
+							onClick={() => onOpenChange(false)}
+						>
+							<Cross className="size-4" />
+						</button>
+					</div>
+				)}
+				<div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+					{hasOpened ? props.children : null}
+				</div>
+			</aside>
+		</>
+	)
+}

package/src/components/page-header.tsx

@@ -0,0 +1,47 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+type PageHeaderProps = {
+	readonly title?: ReactNode
+	/** Muted total on the title baseline (e.g. the item count). */
+	readonly count?: string
+	readonly description?: ReactNode
+	readonly actions?: ReactNode
+	readonly className?: string
+}
+
+/**
+ * Page header — 28px bold title with the total count muted on its baseline,
+ * optional muted description below, page actions on the right. The literary
+ * serif (font-doc) is scoped to the documents section; chrome and index
+ * pages speak in the app sans.
+ */
+export function PageHeader(props: PageHeaderProps) {
+	const { title, count, description, actions, className } = props
+	return (
+		<header className={cn("mb-6", className)}>
+			<div className="flex flex-wrap items-end justify-between gap-x-6 gap-y-3">
+				<div className="flex min-w-0 items-baseline gap-3">
+					{title !== undefined ? (
+						<h1 className="text-doc-heading font-bold text-foreground">
+							{title}
+						</h1>
+					) : null}
+					{count !== undefined ? (
+						<span className="text-ui text-muted-foreground">{count}</span>
+					) : null}
+				</div>
+				{actions !== undefined ? (
+					// `ml-auto` keeps a wrapped actions line right-aligned on
+					// narrow viewports, matching the same-line justify-between.
+					<div className="ml-auto flex shrink-0 flex-wrap items-center gap-4 pb-1">
+						{actions}
+					</div>
+				) : null}
+			</div>
+			{description !== undefined ? (
+				<p className="mt-2 text-ui text-muted-foreground">{description}</p>
+			) : null}
+		</header>
+	)
+}

package/src/components/page-scaffold.test.tsx

@@ -0,0 +1,24 @@
+import { render } from "@testing-library/react"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { RoutePendingFallback } from "./page-scaffold"
+
+describe("RoutePendingFallback", () => {
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	it("renders the header skeletons without invalid DOM nesting", () => {
+		// React's dev-time validator logs "cannot be a descendant of <p>" /
+		// "cannot contain a nested <div>" for a block element inside the
+		// header's h1/p wrappers — a hydration hazard.
+		const errorSpy = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => undefined)
+		render(<RoutePendingFallback />)
+		for (const call of errorSpy.mock.calls) {
+			const message = String(call[0])
+			expect(message).not.toContain("cannot be a descendant")
+			expect(message).not.toContain("cannot contain a nested")
+		}
+	})
+})

package/src/components/page-scaffold.tsx

@@ -0,0 +1,131 @@
+import { Skeleton } from "@hoardodile/ui/components/skeleton"
+import { Surface } from "@hoardodile/ui/components/surface"
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+import { PageHeader } from "./page-header"
+
+/** Content widths (DESIGN.md — Layout): the three fixed measures
+    index/detail pages are held to, centered beyond them. The measure is
+    the content width — padding never counts toward it (DESIGN.md),
+    so it lives on the outer wrapper, not on the measure element. Desktop
+    padding is `px-10 pt-10 pb-16`; mobile
+    and tablet keep their own tighter gutters. */
+export type PageScaffoldWidth = "reading" | "medium" | "content"
+
+const widthClasses: Record<PageScaffoldWidth, string> = {
+	reading: "max-w-reading",
+	medium: "max-w-medium",
+	content: "max-w-content",
+}
+
+type PageScaffoldProps = {
+	readonly children: ReactNode
+	/** Center the page at one of the three content measures; omitted when
+	    the page's own component owns the measure. */
+	readonly width?: PageScaffoldWidth
+	/** Drop the desktop bottom padding — pages ending in a sticky ActionBar. */
+	readonly bottomPad?: boolean
+	readonly className?: string
+}
+
+function frameClassName(props: PageScaffoldProps) {
+	return cn(
+		"pb-4 pt-2 px-3 md:px-4 md:pt-4.5 lg:px-10",
+		props.bottomPad !== false && "lg:pb-16",
+		props.className,
+	)
+}
+
+export function PageScaffold(props: PageScaffoldProps) {
+	if (props.width === undefined) {
+		return (
+			<div className={cn("flex w-full flex-col", frameClassName(props))}>
+				{props.children}
+			</div>
+		)
+	}
+
+	return (
+		<div className={frameClassName(props)}>
+			<div
+				className={cn(
+					"mx-auto flex w-full flex-col",
+					widthClasses[props.width],
+				)}
+			>
+				{props.children}
+			</div>
+		</div>
+	)
+}
+
+type SurfaceProps = {
+	readonly children: ReactNode
+	readonly className?: string
+}
+
+export function FlatSurface(props: SurfaceProps) {
+	return (
+		<Surface as="section" size="compact" className={props.className}>
+			{props.children}
+		</Surface>
+	)
+}
+
+type PillProps = {
+	readonly children: ReactNode
+	readonly tone?: "primary" | "secondary" | "accent" | "muted"
+	readonly className?: string
+}
+
+export function InfoPill(props: PillProps) {
+	return (
+		<span
+			className={cn(
+				"inline-flex items-center rounded-md px-2 py-1 text-xs font-medium",
+				pillToneClassName(props.tone),
+				props.className,
+			)}
+		>
+			{props.children}
+		</span>
+	)
+}
+
+export function RoutePendingFallback() {
+	return (
+		<PageScaffold>
+			<PageHeader
+				title={
+					// Span elements: the header wraps title in h1 and description
+					// in p, and a block div inside either is invalid HTML.
+					<Skeleton element="span" className="block h-8 w-64 max-w-full" />
+				}
+				description={
+					<Skeleton element="span" className="block h-4 w-full max-w-lg" />
+				}
+			/>
+			<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+				<Skeleton className="h-32 rounded-lg" />
+				<Skeleton className="h-32 rounded-lg" />
+				<Skeleton className="h-32 rounded-lg md:col-span-2 xl:col-span-1" />
+			</div>
+		</PageScaffold>
+	)
+}
+
+function pillToneClassName(tone: PillProps["tone"]) {
+	if (tone === "primary") {
+		return "bg-primary/10 text-primary"
+	}
+
+	if (tone === "secondary") {
+		return "bg-secondary text-secondary-foreground"
+	}
+
+	if (tone === "accent") {
+		return "bg-accent text-accent-foreground"
+	}
+
+	return "bg-muted text-muted-foreground"
+}

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

@@ -0,0 +1,87 @@
+import { fireEvent, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { renderWithI18n } from "../test/i18n"
+import { PaginationBar } from "./pagination-bar"
+
+let mobileMock = false
+
+vi.mock("@hoardodile/ui/hooks/use-mobile", () => ({
+	useBelowMd: () => mobileMock,
+}))
+
+describe("PaginationBar", () => {
+	beforeEach(() => {
+		mobileMock = false
+	})
+
+	it("renders the asymmetric window with first, last and the total label", () => {
+		const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+		renderWithI18n(
+			<PaginationBar
+				page={6}
+				pageCount={68}
+				totalLabel="68 items"
+				onChangePage={() => {}}
+			/>,
+		)
+		for (const page of ["1", "5", "6", "7", "8", "68"]) {
+			expect(screen.getByRole("button", { name: page })).toBeInTheDocument()
+		}
+		expect(screen.getByTestId("pagination-current")).toHaveTextContent("6")
+		expect(screen.getAllByText("…")).toHaveLength(2)
+		expect(screen.getByText("68 items")).toBeInTheDocument()
+		expect(errorSpy).not.toHaveBeenCalled()
+		errorSpy.mockRestore()
+	})
+
+	it("collapses to a page/total chip below the md breakpoint", () => {
+		mobileMock = true
+		renderWithI18n(
+			<PaginationBar
+				page={6}
+				pageCount={68}
+				totalLabel="68 items"
+				onChangePage={() => {}}
+			/>,
+		)
+		expect(screen.getByTestId("pagination-current")).toHaveTextContent("6/68")
+		expect(screen.queryByRole("button", { name: "5" })).not.toBeInTheDocument()
+		expect(screen.queryByText("…")).not.toBeInTheDocument()
+	})
+
+	it("disables the prev chevron on the first page without hover", async () => {
+		const onChangePage = vi.fn()
+		const user = userEvent.setup()
+		renderWithI18n(
+			<PaginationBar
+				page={1}
+				pageCount={3}
+				totalLabel="3 items"
+				onChangePage={onChangePage}
+			/>,
+		)
+		const prev = screen.getByRole("button", { name: "Prev" })
+		expect(prev).toBeDisabled()
+		await user.click(prev)
+		expect(onChangePage).not.toHaveBeenCalled()
+	})
+
+	it("jumps to a clamped page via the go-to field", async () => {
+		const onChangePage = vi.fn()
+		const user = userEvent.setup()
+		renderWithI18n(
+			<PaginationBar
+				page={3}
+				pageCount={10}
+				totalLabel="10 items"
+				onChangePage={onChangePage}
+			/>,
+		)
+		const input = screen.getByRole("spinbutton")
+		await user.click(input)
+		fireEvent.change(input, { target: { value: "12" } })
+		fireEvent.submit(input.closest("form")!)
+		expect(onChangePage).toHaveBeenCalledWith(10)
+	})
+})

package/src/components/pagination-bar.tsx

@@ -0,0 +1,139 @@
+import { Icon } from "@hoardodile/ui/components/icon"
+import { Input } from "@hoardodile/ui/components/input"
+import {
+	Pagination,
+	PaginationContent,
+	PaginationItem,
+} from "@hoardodile/ui/components/pagination"
+import { useBelowMd } from "@hoardodile/ui/hooks/use-mobile"
+import { AltArrowLeft, AltArrowRight } from "@hoardodile/ui/icons/registry"
+import { paginationWindow } from "@hoardodile/ui/lib/pagination"
+import { cn } from "@hoardodile/ui/lib/utils"
+import { useState } from "react"
+import { useTranslation } from "react-i18next"
+
+export type PaginationBarProps = {
+	readonly page: number
+	readonly pageCount: number
+	readonly onChangePage: (page: number) => void
+	/** Result-count label rendered in the left slot (e.g. "56 messages"). */
+	readonly totalLabel: string
+}
+
+const pageButton =
+	"flex h-control min-w-8 cursor-pointer items-center justify-center rounded-lg px-2 text-xs"
+
+/**
+ * The paginator: the result count on the left, balanced by the page-jump
+ * field on the right, and the centered row of h-control page chips —
+ * chevrons, first and last page always visible with an asymmetric window
+ * around the active page (one leading, two trailing) and ellipses for the
+ * gap (see {@link paginationWindow}). Below the md breakpoint the window
+ * collapses to a compact `page/total` chip, so narrow screens still see
+ * how many pages exist. Shared by every paged list (resources,
+ * characters, comments, stats, footprints).
+ */
+export function PaginationBar(props: PaginationBarProps) {
+	const { page, pageCount, onChangePage, totalLabel } = props
+	const { t } = useTranslation("ui", { useSuspense: false })
+	const [draft, setDraft] = useState("")
+	const isMobile = useBelowMd()
+
+	function jump(): void {
+		const parsed = Number.parseInt(draft, 10)
+		if (Number.isNaN(parsed)) return
+		const clamped = Math.min(Math.max(1, parsed), pageCount)
+		setDraft("")
+		if (clamped !== page) onChangePage(clamped)
+	}
+
+	const pages = isMobile ? [page] : paginationWindow(page, pageCount)
+	const chip = (active: boolean) =>
+		cn(
+			pageButton,
+			active
+				? "bg-muted font-medium text-foreground"
+				: "text-muted-foreground enabled:hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50",
+		)
+
+	return (
+		<Pagination data-testid="pagination-bar">
+			<div className="flex w-full items-center gap-2">
+				<span className="w-28 shrink-0 truncate text-xs text-muted-foreground">
+					{totalLabel}
+				</span>
+				<PaginationContent className="flex-1 justify-center">
+					<PaginationItem>
+						<button
+							type="button"
+							className={chip(false)}
+							disabled={page <= 1}
+							aria-label={t("pagination.prev")}
+							onClick={() => onChangePage(page - 1)}
+						>
+							<Icon icon={AltArrowLeft} />
+						</button>
+					</PaginationItem>
+					{pages.map((entry, index) =>
+						entry === "…" ? (
+							<PaginationItem key={`ellipsis-${index}`}>
+								<span className="px-1 text-xs text-muted-foreground">
+									{entry}
+								</span>
+							</PaginationItem>
+						) : (
+							<PaginationItem key={entry}>
+								<button
+									type="button"
+									className={chip(entry === page)}
+									data-testid={
+										entry === page ? "pagination-current" : undefined
+									}
+									onClick={() => onChangePage(entry)}
+								>
+									{isMobile ? `${page}/${pageCount}` : entry}
+								</button>
+							</PaginationItem>
+						),
+					)}
+					<PaginationItem>
+						<button
+							type="button"
+							className={chip(false)}
+							disabled={page >= pageCount}
+							aria-label={t("pagination.next")}
+							onClick={() => onChangePage(page + 1)}
+						>
+							<Icon icon={AltArrowRight} />
+						</button>
+					</PaginationItem>
+				</PaginationContent>
+				<form
+					className="flex w-28 items-center justify-end gap-1.5 text-xs text-muted-foreground"
+					onSubmit={(event) => {
+						event.preventDefault()
+						jump()
+					}}
+				>
+					<span className="shrink-0 whitespace-nowrap">{t("pagination.goTo")}</span>
+					<Input
+						type="number"
+						min={1}
+						max={pageCount}
+						value={draft}
+						onChange={(event) => setDraft(event.target.value)}
+						placeholder={t("pagination.jumpToPage")}
+						aria-label={t("pagination.goTo")}
+						size="sm"
+						// Content-elastic width in `ch` units (the native `size`
+						// attribute's modern equivalent — `field-sizing` is not
+						// supported everywhere yet): one character per digit,
+						// with room for the "Page" placeholder and padding.
+						style={{ width: `${Math.max(4, draft.length + 2) + 4}ch` }}
+						className="min-w-0 text-center [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
+					/>
+				</form>
+			</div>
+		</Pagination>
+	)
+}