@hoardodile/ui 0.0.0

package/src/components/popover.tsx

@@ -0,0 +1,133 @@
+import * as React from "react"
+import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+import { useMobileBackToClose } from "@hoardodile/ui/hooks/useMobileBackToClose"
+
+function Popover({
+  open,
+  defaultOpen,
+  onOpenChange,
+  ...props
+}: Omit<PopoverPrimitive.Root.Props, "onOpenChange"> & {
+  /**
+   * `eventDetails` is absent for closes triggered by the mobile back
+   * gesture (a synthetic close with no underlying Base UI event).
+   */
+  onOpenChange?: (
+    open: boolean,
+    eventDetails?: PopoverPrimitive.Root.ChangeEventDetails,
+  ) => void
+}) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(
+    defaultOpen ?? false,
+  )
+  const isControlled = open !== undefined
+  const currentOpen = isControlled ? open : uncontrolledOpen
+  function handleOpenChange(
+    next: boolean,
+    eventDetails?: PopoverPrimitive.Root.ChangeEventDetails,
+  ) {
+    if (!isControlled) setUncontrolledOpen(next)
+    onOpenChange?.(next, eventDetails)
+  }
+  useMobileBackToClose(currentOpen, handleOpenChange)
+  return (
+    <PopoverPrimitive.Root
+      data-slot="popover"
+      open={currentOpen}
+      onOpenChange={handleOpenChange}
+      {...props}
+    />
+  )
+}
+
+function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
+}
+
+function PopoverContent({
+  className,
+  align = "center",
+  alignOffset = 0,
+  side = "bottom",
+  sideOffset = 4,
+  container,
+  ...props
+}: PopoverPrimitive.Popup.Props &
+  Pick<
+    PopoverPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  > & {
+    /**
+     * Override the portal target. Used by the video player so popovers
+     * stay attached to the fullscreen container; otherwise they'd be
+     * portalled to `document.body` and rendered behind the fullscreen
+     * surface, where every tap registers as outside-click and dismisses
+     * the popover immediately.
+     */
+    container?: PopoverPrimitive.Portal.Props["container"]
+  }) {
+  return (
+    <PopoverPrimitive.Portal container={container}>
+      <PopoverPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <PopoverPrimitive.Popup
+          data-slot="popover-content"
+          className={cn(
+            "z-50 flex w-72 origin-(--transform-origin) flex-col gap-4 rounded-md bg-popover p-4 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        />
+      </PopoverPrimitive.Positioner>
+    </PopoverPrimitive.Portal>
+  )
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="popover-header"
+      className={cn("flex flex-col gap-1 text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props) {
+  return (
+    <PopoverPrimitive.Title
+      data-slot="popover-title"
+      className={cn("font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function PopoverDescription({
+  className,
+  ...props
+}: PopoverPrimitive.Description.Props) {
+  return (
+    <PopoverPrimitive.Description
+      data-slot="popover-description"
+      className={cn("text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+}

package/src/components/progress.tsx

@@ -0,0 +1,88 @@
+"use client"
+
+import { Progress as ProgressPrimitive } from "@base-ui/react/progress"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+function Progress({
+  className,
+  children,
+  value,
+  ...props
+}: ProgressPrimitive.Root.Props) {
+  return (
+    // `relative` makes the root the containing block for loose children
+    // (e.g. `sr-only` labels for screen readers): without it they anchor
+    // to the nearest positioned ancestor instead — typically the app
+    // shell, outside the page's scroll clip — and stack a second,
+    // viewport-level scrollbar on long pages (Settings → App).
+    <ProgressPrimitive.Root
+      value={value}
+      data-slot="progress"
+      className={cn("relative flex flex-wrap gap-3", className)}
+      {...props}
+    >
+      {children}
+      <ProgressTrack>
+        <ProgressIndicator />
+      </ProgressTrack>
+    </ProgressPrimitive.Root>
+  )
+}
+
+function ProgressTrack({ className, ...props }: ProgressPrimitive.Track.Props) {
+  return (
+    <ProgressPrimitive.Track
+      className={cn(
+        "relative flex h-1.5 w-full items-center overflow-x-hidden rounded-full bg-muted",
+        className
+      )}
+      data-slot="progress-track"
+      {...props}
+    />
+  )
+}
+
+function ProgressIndicator({
+  className,
+  ...props
+}: ProgressPrimitive.Indicator.Props) {
+  return (
+    <ProgressPrimitive.Indicator
+      data-slot="progress-indicator"
+      className={cn("h-full bg-primary transition-all", className)}
+      {...props}
+    />
+  )
+}
+
+function ProgressLabel({ className, ...props }: ProgressPrimitive.Label.Props) {
+  return (
+    <ProgressPrimitive.Label
+      className={cn("text-sm font-medium", className)}
+      data-slot="progress-label"
+      {...props}
+    />
+  )
+}
+
+function ProgressValue({ className, ...props }: ProgressPrimitive.Value.Props) {
+  return (
+    <ProgressPrimitive.Value
+      className={cn(
+        "ml-auto text-sm text-muted-foreground tabular-nums",
+        className
+      )}
+      data-slot="progress-value"
+      {...props}
+    />
+  )
+}
+
+export {
+  Progress,
+  ProgressTrack,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressValue,
+}

package/src/components/query-state-view.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from "react"
+
+/**
+ * Slot-based renderer for the loading/empty/error/data quartet that
+ * wraps almost every list query in the app. Reduces:
+ *
+ * ```tsx
+ * {q.isLoading ? <Skeleton/> : null}
+ * {!q.isLoading && q.isError ? <Error/> : null}
+ * {!q.isLoading && !q.isError && data.length === 0 ? <Empty/> : null}
+ * {!q.isLoading && !q.isError && data.length > 0 ? <List data={data}/> : null}
+ * ```
+ *
+ * to a single declarative element. Pass a `result` describing the
+ * query's status, a derived `data`, and the slot renderers.
+ *
+ * Decoupled from TanStack Query so it can be used with any data source
+ * (URL state, suspense, manual fetches) and stays cheap to test.
+ */
+export type QueryStateResult<T> = {
+	readonly isLoading: boolean
+	readonly isError: boolean
+	readonly error?: Error | null
+	readonly data: T | undefined
+}
+
+export type QueryStateViewProps<T> = {
+	readonly result: QueryStateResult<T>
+	readonly isEmpty?: (data: T) => boolean
+	readonly loading: ReactNode
+	readonly empty?: ReactNode
+	readonly error?: (error: Error) => ReactNode
+	readonly children: (data: T) => ReactNode
+}
+
+export function QueryStateView<T>(props: QueryStateViewProps<T>): ReactNode {
+	const { result, isEmpty, loading, empty, error, children } = props
+	if (result.isLoading) return loading
+	if (result.isError) {
+		const renderError = error
+		const err = result.error ?? new Error("Unknown error")
+		return renderError !== undefined ? renderError(err) : null
+	}
+	if (result.data === undefined) return null
+	if (isEmpty?.(result.data) === true) return empty ?? null
+	return children(result.data)
+}

package/src/components/radio-group.tsx

@@ -0,0 +1,36 @@
+import { Radio as RadioPrimitive } from "@base-ui/react/radio"
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
+  return (
+    <RadioGroupPrimitive
+      data-slot="radio-group"
+      className={cn("grid w-full gap-3", className)}
+      {...props}
+    />
+  )
+}
+
+function RadioGroupItem({ className, ...props }: RadioPrimitive.Root.Props) {
+  return (
+    <RadioPrimitive.Root
+      data-slot="radio-group-item"
+      className={cn(
+        "group/radio-group-item peer relative flex aspect-square size-4 shrink-0 rounded-full border border-input outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary",
+        className
+      )}
+      {...props}
+    >
+      <RadioPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="flex size-4 items-center justify-center"
+      >
+        <span className="absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary-foreground" />
+      </RadioPrimitive.Indicator>
+    </RadioPrimitive.Root>
+  )
+}
+
+export { RadioGroup, RadioGroupItem }

package/src/components/scroll-area.tsx

@@ -0,0 +1,52 @@
+import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: ScrollAreaPrimitive.Root.Props) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  )
+}
+
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: ScrollAreaPrimitive.Scrollbar.Props) {
+  return (
+    <ScrollAreaPrimitive.Scrollbar
+      data-slot="scroll-area-scrollbar"
+      data-orientation={orientation}
+      orientation={orientation}
+      className={cn(
+        "flex touch-none p-px transition-colors select-none data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
+        className
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Thumb
+        data-slot="scroll-area-thumb"
+        className="relative flex-1 rounded-full bg-border"
+      />
+    </ScrollAreaPrimitive.Scrollbar>
+  )
+}
+
+export { ScrollArea, ScrollBar }

package/src/components/search-field.test.tsx

@@ -0,0 +1,86 @@
+import { render, screen, waitFor } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, test, vi } from "vitest"
+import { SearchField } from "./search-field"
+
+describe("SearchField", () => {
+	test("debounces keystrokes before committing", async () => {
+		const user = userEvent.setup()
+		const onCommit = vi.fn()
+		render(
+			<SearchField value="" onCommit={onCommit} testId="search" delayMs={50} />,
+		)
+		await user.type(screen.getByTestId("search"), "hello")
+		expect(onCommit).not.toHaveBeenCalledWith("hello")
+		await waitFor(() => {
+			expect(onCommit).toHaveBeenCalledWith("hello")
+		})
+	})
+
+	test("re-syncs with external resets", () => {
+		const { rerender } = render(
+			<SearchField value="foo" onCommit={() => {}} testId="search" />,
+		)
+		const input = screen.getByTestId("search") as HTMLInputElement
+		expect(input.value).toBe("foo")
+		rerender(<SearchField value="" onCommit={() => {}} testId="search" />)
+		expect(input.value).toBe("")
+	})
+
+	test("commits only on Enter in commitOnEnterOnly mode", async () => {
+		const user = userEvent.setup()
+		const onCommit = vi.fn()
+		const onSubmit = vi.fn()
+		render(
+			<SearchField
+				value=""
+				onCommit={onCommit}
+				onSubmit={onSubmit}
+				commitOnEnterOnly
+				testId="search"
+				delayMs={10}
+			/>,
+		)
+		await user.type(screen.getByTestId("search"), "harbor")
+		// Typing never commits on its own in this mode.
+		await waitFor(() => {
+			expect(onCommit).not.toHaveBeenCalled()
+		})
+		await user.keyboard("{Enter}")
+		expect(onSubmit).toHaveBeenCalledWith("harbor")
+		expect(onCommit).not.toHaveBeenCalled()
+	})
+
+	test("commits immediately and submits on Enter in debounced mode", async () => {
+		const user = userEvent.setup()
+		const onCommit = vi.fn()
+		const onSubmit = vi.fn()
+		render(
+			<SearchField
+				value=""
+				onCommit={onCommit}
+				onSubmit={onSubmit}
+				testId="search"
+				delayMs={10}
+			/>,
+		)
+		await user.type(screen.getByTestId("search"), "harbor")
+		await user.keyboard("{Enter}")
+		expect(onCommit).toHaveBeenCalledWith("harbor")
+		expect(onSubmit).toHaveBeenCalledWith("harbor")
+	})
+
+	test("submits the draft through the form", async () => {
+		const user = userEvent.setup()
+		const onSubmit = vi.fn()
+		render(<SearchField value="" onSubmit={onSubmit} testId="search" />)
+		await user.type(screen.getByTestId("search"), "harbor")
+		await user.keyboard("{Enter}")
+		expect(onSubmit).toHaveBeenCalledWith("harbor")
+	})
+
+	test("renders the global-search-input testid by default", () => {
+		render(<SearchField value="" />)
+		expect(screen.getByTestId("global-search-input")).not.toBeNull()
+	})
+})

package/src/components/search-field.tsx

@@ -0,0 +1,119 @@
+import { Icon } from "@hoardodile/ui/components/icon"
+import { Magnifier } from "@hoardodile/ui/icons/registry"
+import { cn } from "@hoardodile/ui/lib/utils"
+import {
+	type KeyboardEvent,
+	type ReactNode,
+	type Ref,
+	useEffect,
+	useState,
+} from "react"
+import { useDebounce } from "react-use"
+
+export type SearchFieldProps = {
+	/** The committed value; the input re-syncs to it on external changes. */
+	readonly value: string
+	readonly placeholder?: string
+	/**
+	 * Layout overrides — the hero form passes `h-11 px-4` (the sidebar
+	 * h-nav and the hero h-11 share one anatomy).
+	 */
+	readonly className?: string
+	/** Optional actions rendered at the trailing edge of the field. */
+	readonly actions?: ReactNode
+	/** Input length cap (e.g. the app's max search-query length). */
+	readonly maxLength?: number
+	/**
+	 * Debounced commit of the draft (unless {@link commitOnEnterOnly}).
+	 * Filter bars pass their live patch here.
+	 */
+	readonly onCommit?: (value: string) => void
+	/** Enter / form submit — navigation and apply-on-demand surfaces. */
+	readonly onSubmit?: (value: string) => void
+	/**
+	 * When true, keystrokes never debounce-commit; the value is delivered
+	 * only through {@link onSubmit} (Enter). Used by apply-on-demand
+	 * surfaces where typing stages and Enter applies.
+	 */
+	readonly commitOnEnterOnly?: boolean
+	readonly delayMs?: number
+	/** Optional ref to the inner input (sidebar "/" and Ctrl/Cmd+K). */
+	readonly inputRef?: Ref<HTMLInputElement>
+	readonly testId?: string
+}
+
+/**
+ * The one search field: muted fill, rounded-lg, leading magnifier,
+ * muted placeholder — sidebar (h-nav) and hero (h-11) share this
+ * anatomy, as do the index-page filter bars. Commit semantics are the
+ * caller's: debounced {@link onCommit} for live filtering, Enter through
+ * {@link onSubmit} for navigation and apply-on-demand surfaces.
+ *
+ * The root is a div, not a form: the field nests inside page forms (the
+ * new character/resource editors, which wrap their whole body in one), so
+ * a nested form would be invalid HTML. Enter is captured on keydown and
+ * preventDefaulted, so it never submits an enclosing form either.
+ */
+export function SearchField(props: SearchFieldProps) {
+	const {
+		value,
+		placeholder,
+		className,
+		actions,
+		maxLength,
+		onCommit,
+		onSubmit,
+		commitOnEnterOnly,
+		delayMs,
+		inputRef,
+		testId,
+	} = props
+	const [draft, setDraft] = useState(value)
+
+	useEffect(() => {
+		setDraft(value)
+	}, [value])
+
+	useDebounce(
+		() => {
+			if (commitOnEnterOnly) return
+			if (draft !== value) onCommit?.(draft)
+		},
+		delayMs ?? 300,
+		[draft],
+	)
+
+	function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {
+		if (event.key !== "Enter") return
+		event.preventDefault()
+		if (commitOnEnterOnly) {
+			onSubmit?.(draft)
+			return
+		}
+		if (draft !== value) onCommit?.(draft)
+		onSubmit?.(draft)
+	}
+
+	return (
+		<div
+			onKeyDown={handleKeyDown}
+			className={cn(
+				"flex h-nav items-center gap-2 rounded-lg bg-muted px-3",
+				className,
+			)}
+		>
+			<Icon icon={Magnifier} className="shrink-0 text-muted-foreground" />
+			<input
+				ref={inputRef}
+				type="text"
+				value={draft}
+				onChange={(ev) => setDraft(ev.target.value)}
+				placeholder={placeholder}
+				maxLength={maxLength}
+				className="min-w-0 flex-1 bg-transparent text-ui text-foreground outline-none placeholder:text-muted-foreground"
+				data-testid={testId ?? "global-search-input"}
+			/>
+			{actions}
+		</div>
+	)
+}

package/src/components/secondary-stat.tsx

@@ -0,0 +1,24 @@
+import { SectionLabel } from "./section-label"
+
+/**
+ * Secondary stat — the quiet supporting readout beside a KPI: uppercase
+ * tracking-label label over a bold tabular numeral.
+ */
+export function SecondaryStat({
+	label,
+	value,
+	className,
+}: {
+	readonly label: string
+	readonly value: string
+	readonly className?: string
+}) {
+	return (
+		<div className={className}>
+			<SectionLabel>{label}</SectionLabel>
+			<div className="mt-1 text-xl font-bold tabular-nums text-foreground">
+				{value}
+			</div>
+		</div>
+	)
+}

package/src/components/section-header.tsx

@@ -0,0 +1,54 @@
+import { Icon, type IconType } from "@hoardodile/ui/components/icon"
+import type { ReactNode } from "react"
+
+/**
+ * Section header: icon 16 + 16px semibold title, muted count on the
+ * baseline; the right slot holds trailing controls ("View all" links,
+ * toggles, marquee chevrons).
+ */
+export function SectionHeader({
+	icon,
+	title,
+	count,
+	viewAll,
+	onViewAll,
+	right,
+	className,
+}: {
+	readonly icon?: IconType
+	readonly title: string
+	/** Muted count rendered right after the title, e.g. "(2)". */
+	readonly count?: string
+	/** Label for the right-aligned "View all" text link. */
+	readonly viewAll?: string
+	readonly onViewAll?: () => void
+	/** Right-aligned trailing slot (the ml-auto position). */
+	readonly right?: ReactNode
+	readonly className?: string
+}) {
+	return (
+		<div className={`flex items-center gap-2 ${className ?? ""}`}>
+			{icon !== undefined ? (
+				<Icon icon={icon} className="text-secondary-foreground" />
+			) : null}
+			<span className="text-base font-semibold text-foreground">{title}</span>
+			{count !== undefined ? (
+				<span className="text-xs text-muted-foreground">{count}</span>
+			) : null}
+			{viewAll !== undefined || right !== undefined ? (
+				<span className="ml-auto flex items-center gap-4">
+					{viewAll !== undefined ? (
+						<button
+							type="button"
+							onClick={onViewAll}
+							className="cursor-pointer text-xs text-muted-foreground hover:text-secondary-foreground"
+						>
+							{viewAll}
+						</button>
+					) : null}
+					{right}
+				</span>
+			) : null}
+		</div>
+	)
+}

package/src/components/section-label.tsx

@@ -0,0 +1,40 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+/**
+ * Section label — the 12px uppercase tracking-label voice (DESIGN.md —
+ * Typography), one component instead of a class string repeated across
+ * panels, rails, dialogs and settings. Ink tones: `muted` (default, the
+ * quiet section voice), `foreground` (structural headings), `danger`
+ * (the dialog eyebrow of a destructive ritual). Callers with a
+ * right-aligned count arrange it inside `children` (flex via
+ * `className`) — the voice is the unit.
+ */
+export function SectionLabel({
+	tone = "muted",
+	size = "xs",
+	className,
+	children,
+}: {
+	tone?: "muted" | "foreground" | "danger"
+	size?: "xs" | "tiny"
+	className?: string
+	children: ReactNode
+}) {
+	return (
+		<div
+			className={cn(
+				size === "tiny" ? "text-tiny leading-none" : "text-xs",
+				"font-semibold tracking-label uppercase",
+				tone === "foreground"
+					? "text-foreground"
+					: tone === "danger"
+						? "text-destructive"
+						: "text-muted-foreground",
+				className,
+			)}
+		>
+			{children}
+		</div>
+	)
+}