@hoardodile/ui 0.0.0

package/src/components/image-cropper.test.tsx

@@ -0,0 +1,144 @@
+import { fireEvent, render, waitFor } from "@testing-library/react"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { type CroppedImage, ImageCropper } from "./image-cropper"
+
+beforeEach(() => {
+	const context = {
+		drawImage: vi.fn(),
+		imageSmoothingQuality: "",
+	}
+	HTMLCanvasElement.prototype.getContext = vi.fn(() => context) as never
+	HTMLCanvasElement.prototype.toDataURL = vi.fn(
+		() => "data:image/png;base64,",
+	) as never
+	HTMLCanvasElement.prototype.toBlob = vi.fn((callback) => {
+		callback?.(new Blob([""], { type: "image/png" }))
+	}) as never
+})
+
+const TALL_IMAGE_SRC =
+	"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1000' height='2000'%3E%3Crect width='100%25' height='100%25' fill='red'/%3E%3C/svg%3E"
+const SQUARE_IMAGE_SRC =
+	"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='804' height='804'%3E%3Crect width='100%25' height='100%25' fill='red'/%3E%3C/svg%3E"
+
+describe("ImageCropper", () => {
+	it("fills a tall image with a square aspect crop", async () => {
+		let renderCrop: (() => Promise<CroppedImage>) | undefined
+
+		render(
+			<ImageCropper
+				src={TALL_IMAGE_SRC}
+				aspect={1}
+				onCropReady={(render) => {
+					renderCrop = render
+				}}
+			/>,
+		)
+
+		const img = await waitFor(() => {
+			const el = document.querySelector("img")
+			expect(el).toBeInTheDocument()
+			return el as HTMLImageElement
+		})
+
+		// Natural size is 1000x2000, but the image is displayed at 200x400.
+		// The output must still be a 1000x1000 square based on natural pixels.
+		setImageSize(img, {
+			naturalWidth: 1000,
+			naturalHeight: 2000,
+			width: 200,
+			height: 400,
+		})
+		fireEvent.load(img)
+
+		await waitFor(() => expect(renderCrop).toBeDefined())
+		const cropped = await renderCrop!()
+
+		expect(cropped.width).toBe(1000)
+		expect(cropped.height).toBe(1000)
+	})
+
+	it("keeps a square image square with a 1:1 aspect crop", async () => {
+		let renderCrop: (() => Promise<CroppedImage>) | undefined
+
+		render(
+			<ImageCropper
+				src={SQUARE_IMAGE_SRC}
+				aspect={1}
+				onCropReady={(render) => {
+					renderCrop = render
+				}}
+			/>,
+		)
+
+		const img = await waitFor(() => {
+			const el = document.querySelector("img")
+			expect(el).toBeInTheDocument()
+			return el as HTMLImageElement
+		})
+
+		// Natural size is 804x804, displayed much smaller (e.g. 200x200).
+		// The output must remain exactly 804x804.
+		setImageSize(img, {
+			naturalWidth: 804,
+			naturalHeight: 804,
+			width: 200,
+			height: 200,
+		})
+		fireEvent.load(img)
+
+		await waitFor(() => expect(renderCrop).toBeDefined())
+		const cropped = await renderCrop!()
+
+		expect(cropped.width).toBe(804)
+		expect(cropped.height).toBe(804)
+	})
+
+	it("uses the full image when no aspect is provided", async () => {
+		let renderCrop: (() => Promise<CroppedImage>) | undefined
+
+		render(
+			<ImageCropper
+				src={TALL_IMAGE_SRC}
+				onCropReady={(render) => {
+					renderCrop = render
+				}}
+			/>,
+		)
+
+		const img = await waitFor(() => {
+			const el = document.querySelector("img")
+			expect(el).toBeInTheDocument()
+			return el as HTMLImageElement
+		})
+
+		setImageSize(img, {
+			naturalWidth: 1000,
+			naturalHeight: 2000,
+			width: 200,
+			height: 400,
+		})
+		fireEvent.load(img)
+
+		await waitFor(() => expect(renderCrop).toBeDefined())
+		const cropped = await renderCrop!()
+
+		expect(cropped.width).toBe(1000)
+		expect(cropped.height).toBe(2000)
+	})
+})
+
+function setImageSize(
+	img: HTMLImageElement,
+	size: {
+		naturalWidth: number
+		naturalHeight: number
+		width: number
+		height: number
+	},
+): void {
+	Object.defineProperty(img, "naturalWidth", { value: size.naturalWidth })
+	Object.defineProperty(img, "naturalHeight", { value: size.naturalHeight })
+	Object.defineProperty(img, "width", { value: size.width })
+	Object.defineProperty(img, "height", { value: size.height })
+}

package/src/components/image-cropper.tsx

@@ -0,0 +1,265 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import ReactCrop, { type Crop } from "react-image-crop"
+import "react-image-crop/dist/ReactCrop.css"
+
+/**
+ * Output of {@link ImageCropper} once the user releases the selection
+ * box. Contains the cropped pixel data ready to upload (PNG by default)
+ * plus its dimensions.
+ */
+export type CroppedImage = {
+	readonly blob: Blob
+	readonly width: number
+	readonly height: number
+	readonly mimeType: string
+}
+
+export type ImageCropperProps = {
+	/** The source image as a data URL or object URL. */
+	readonly src: string
+	/**
+	 * Optional fixed aspect ratio (width / height). When omitted, the
+	 * user can crop freely.
+	 */
+	readonly aspect?: number
+	/**
+	 * Output mime type. Defaults to `image/png`. PNG preserves quality;
+	 * JPEG produces smaller files for photographic content.
+	 */
+	readonly mimeType?: "image/png" | "image/jpeg" | "image/webp"
+	/** JPEG/WebP quality (0..1). Ignored for PNG. */
+	readonly quality?: number
+	/**
+	 * Called whenever the cropped pixel rectangle changes and is non-empty.
+	 * The callback receives a function that, when invoked, produces the
+	 * final {@link CroppedImage}. The render is deferred to avoid running
+	 * the canvas pipeline on every drag tick.
+	 */
+	readonly onCropReady: (render: () => Promise<CroppedImage>) => void
+	/**
+	 * Called synchronously with a PNG `data:` URL whenever the crop
+	 * selection changes. PNG preserves alpha for the live preview (JPEG
+	 * would flatten transparency to black). Unlike blob URLs, `data:`
+	 * URLs never appear in the browser network tab and setting them as
+	 * image `src` cannot cause an infinite re-render loop.
+	 */
+	readonly onPreviewChange?: (dataUrl: string) => void
+	/**
+	 * Max CSS width for the source image in the crop stage. When omitted the
+	 * image relies on `max-w-full` to fill the parent width.
+	 */
+	readonly displayMaxWidth?: number | string
+	/**
+	 * Max CSS height for the source image in the crop stage (e.g. `80vh` for
+	 * large canvas captures). Defaults to `70vh`.
+	 */
+	readonly displayMaxHeight?: number | string
+}
+
+/**
+ * Free-aspect (or fixed-aspect when {@link ImageCropperProps.aspect} is
+ * provided) image cropper. Wraps `react-image-crop` and exposes a
+ * deferred `render()` callback so callers can rasterise the selection on
+ * demand (typically when the user clicks "save").
+ */
+export function ImageCropper(props: ImageCropperProps) {
+	const {
+		src,
+		aspect,
+		mimeType = "image/png",
+		quality = 0.92,
+		displayMaxWidth,
+		displayMaxHeight = "70vh",
+	} = props
+
+	const imgRef = useRef<HTMLImageElement | null>(null)
+	const [crop, setCrop] = useState<Crop | undefined>(undefined)
+	const [completed, setCompleted] = useState<Crop | undefined>(undefined)
+
+	const handleImageLoad = useCallback(
+		(e: React.SyntheticEvent<HTMLImageElement>) => {
+			const { naturalWidth, naturalHeight } = e.currentTarget
+			const initial = buildInitialCrop(naturalWidth, naturalHeight, aspect)
+			setCrop(initial)
+			setCompleted(initial)
+		},
+		[aspect],
+	)
+
+	const onCropReady = props.onCropReady
+	const onPreviewChange = props.onPreviewChange
+
+	useEffect(() => {
+		const img = imgRef.current
+		if (img === null || completed === undefined || completed.width === 0) {
+			return
+		}
+		onCropReady(() => renderCroppedImage(img, completed, mimeType, quality))
+		if (onPreviewChange !== undefined) {
+			onPreviewChange(renderPreviewDataUrl(img, completed))
+		}
+	}, [completed, mimeType, quality, onCropReady, onPreviewChange])
+
+	return (
+		<div className="react-crop-theme flex min-h-0 w-full max-w-full flex-col items-center gap-2 overflow-hidden">
+			<ReactCrop
+				className="max-w-full"
+				crop={crop}
+				onChange={(_, percentCrop) => setCrop(percentCrop)}
+				onComplete={(_, percentCrop) => setCompleted(percentCrop)}
+				aspect={aspect}
+				keepSelection
+				ruleOfThirds
+			>
+				{/* biome-ignore lint/a11y/useAltText: cropper preview lacks user-supplied alt */}
+				<img
+					ref={imgRef}
+					src={src}
+					onLoad={handleImageLoad}
+					className="h-auto max-w-full"
+					style={{
+						maxWidth: displayMaxWidth,
+						maxHeight: displayMaxHeight,
+					}}
+				/>
+			</ReactCrop>
+		</div>
+	)
+}
+
+function buildInitialCrop(
+	imgWidth: number,
+	imgHeight: number,
+	aspect: number | undefined,
+): Crop {
+	if (aspect === undefined) {
+		return { unit: "%" as const, x: 0, y: 0, width: 100, height: 100 }
+	}
+
+	const imgAspect = imgWidth / imgHeight
+	let widthPct: number
+	let heightPct: number
+
+	if (imgAspect >= aspect) {
+		// Image is wider (or equal) than the target aspect: fit to height,
+		// crop the sides.
+		heightPct = 100
+		widthPct = (100 * aspect) / imgAspect
+	} else {
+		// Image is taller than the target aspect: fit to width, crop top/bottom.
+		widthPct = 100
+		heightPct = (100 * imgAspect) / aspect
+	}
+
+	return {
+		unit: "%" as const,
+		x: (100 - widthPct) / 2,
+		y: (100 - heightPct) / 2,
+		width: widthPct,
+		height: heightPct,
+	}
+}
+
+class CroppedImageRenderError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "CroppedImageRenderError"
+	}
+}
+
+/**
+ * @throws CroppedImageRenderError when the canvas context is unavailable
+ *   or the browser refuses to encode the selected blob.
+ */
+async function renderCroppedImage(
+	image: HTMLImageElement,
+	crop: Crop,
+	mimeType: string,
+	quality: number,
+): Promise<CroppedImage> {
+	const sourceRect = cropToNaturalRect(image, crop)
+
+	const canvas = document.createElement("canvas")
+	canvas.width = sourceRect.sw
+	canvas.height = sourceRect.sh
+	const ctx = canvas.getContext("2d")
+	if (ctx === null) {
+		throw new CroppedImageRenderError("2d context is unavailable")
+	}
+	ctx.imageSmoothingQuality = "high"
+	ctx.drawImage(
+		image,
+		sourceRect.sx,
+		sourceRect.sy,
+		sourceRect.sw,
+		sourceRect.sh,
+		0,
+		0,
+		sourceRect.sw,
+		sourceRect.sh,
+	)
+
+	const blob = await new Promise<Blob | null>((resolve) => {
+		canvas.toBlob(resolve, mimeType, quality)
+	})
+	if (blob === null) {
+		throw new CroppedImageRenderError("toBlob returned null")
+	}
+	return { blob, width: sourceRect.sw, height: sourceRect.sh, mimeType }
+}
+
+/**
+ * Render the current crop to a PNG `data:` URL synchronously.
+ *
+ * Unlike {@link renderCroppedImage}, this function does NOT create a
+ * `blob:` URL and therefore does not appear in the browser network tab.
+ * Preview uses PNG (not JPEG) so transparent regions stay transparent.
+ */
+function renderPreviewDataUrl(image: HTMLImageElement, crop: Crop): string {
+	const sourceRect = cropToNaturalRect(image, crop)
+
+	const canvas = document.createElement("canvas")
+	canvas.width = sourceRect.sw
+	canvas.height = sourceRect.sh
+	const ctx = canvas.getContext("2d", { alpha: true })
+	if (ctx === null) return ""
+	ctx.imageSmoothingQuality = "high"
+	ctx.drawImage(
+		image,
+		sourceRect.sx,
+		sourceRect.sy,
+		sourceRect.sw,
+		sourceRect.sh,
+		0,
+		0,
+		sourceRect.sw,
+		sourceRect.sh,
+	)
+	return canvas.toDataURL("image/png")
+}
+
+function cropToNaturalRect(
+	image: HTMLImageElement,
+	crop: Crop,
+): { sx: number; sy: number; sw: number; sh: number } {
+	const naturalWidth = image.naturalWidth
+	const naturalHeight = image.naturalHeight
+
+	if (crop.unit === "px") {
+		return {
+			sx: crop.x,
+			sy: crop.y,
+			sw: Math.max(1, Math.round(crop.width)),
+			sh: Math.max(1, Math.round(crop.height)),
+		}
+	}
+
+	const sx = (crop.x / 100) * naturalWidth
+	const sy = (crop.y / 100) * naturalHeight
+	const swRaw = (crop.width / 100) * naturalWidth
+	const shRaw = (crop.height / 100) * naturalHeight
+	const sw = Math.max(1, Math.round(swRaw))
+	const sh = Math.max(1, Math.round(shRaw))
+
+	return { sx, sy, sw, sh }
+}

package/src/components/input-group.tsx

@@ -0,0 +1,156 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+import { Button } from "@hoardodile/ui/components/button"
+import { Input } from "@hoardodile/ui/components/input"
+import { Textarea } from "@hoardodile/ui/components/textarea"
+
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group relative flex h-9 w-full min-w-0 items-center rounded-md border border-input shadow-xs transition-[color,box-shadow] outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto dark:bg-input/30 dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-2 has-[>button]:-ml-1 has-[>kbd]:ml-[-0.15rem]",
+        "inline-end":
+          "order-last pr-2 has-[>button]:-mr-1 has-[>kbd]:mr-[-0.15rem]",
+        "block-start":
+          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
+        "block-end":
+          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  }
+)
+
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+const inputGroupButtonVariants = cva(
+  "flex items-center gap-2 text-sm shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-[calc(var(--radius)-5px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "",
+        "icon-xs":
+          "size-6 rounded-[calc(var(--radius)-5px)] p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  }
+)
+
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size" | "type"> &
+  VariantProps<typeof inputGroupButtonVariants> & {
+    type?: "button" | "submit" | "reset"
+  }) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupInput({
+  className,
+  ...props
+}: Omit<React.ComponentProps<"input">, "size">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none bg-transparent aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 resize-none rounded-none bg-transparent py-2 aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+}

package/src/components/input.tsx

@@ -0,0 +1,45 @@
+import { Input as InputPrimitive } from "@base-ui/react/input"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+/**
+ * Muted-fill control (the ControlStub / forms anatomy): fill background,
+ * `rounded-lg`, no border — the same anatomy as the search field. Three
+ * height tiers ride the control tokens: `sm` h-chip, `md` h-control,
+ * `lg` h-10.
+ */
+const inputVariants = cva(
+  "w-full min-w-0 rounded-lg bg-muted text-ui text-foreground outline-none placeholder:text-muted-foreground disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:ring-[3px] aria-invalid:ring-destructive/20",
+  {
+    variants: {
+      size: {
+        sm: "h-chip px-2.5 text-xs",
+        md: "h-control px-3",
+        lg: "h-10 px-3.5",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+)
+
+function Input({
+  className,
+  size,
+  type,
+  ...props
+}: Omit<React.ComponentProps<"input">, "size"> &
+  VariantProps<typeof inputVariants>) {
+  return (
+    <InputPrimitive
+      type={type}
+      data-slot="input"
+      className={cn(inputVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Input, inputVariants }

package/src/components/label.tsx

@@ -0,0 +1,20 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+function Label({ className, ...props }: React.ComponentProps<"label">) {
+  return (
+    <label
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Label }

package/src/components/list-empty-row.tsx

@@ -0,0 +1,27 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+export type ListEmptyRowProps = {
+	readonly testId?: string
+	readonly className?: string
+	readonly children: ReactNode
+}
+
+/**
+ * Dashed empty-list row — a quiet centered slot that reads as an empty
+ * list item rather than a gap. Shared by comment, character, resource
+ * and tag-rule lists.
+ */
+export function ListEmptyRow(props: ListEmptyRowProps) {
+	return (
+		<div
+			className={cn(
+				"flex min-h-9 items-center justify-center rounded-lg border border-dashed border-border-strong px-3 py-2 text-xs text-muted-foreground",
+				props.className,
+			)}
+			data-testid={props.testId}
+		>
+			{props.children}
+		</div>
+	)
+}

package/src/components/management-empty.tsx

@@ -0,0 +1,25 @@
+import { cn } from "@hoardodile/ui/lib/utils"
+import type { ReactNode } from "react"
+
+export type ManagementEmptyProps = {
+	readonly testId?: string
+	readonly className?: string
+	readonly children: ReactNode
+}
+
+/**
+ * Dashed empty-state placeholder shared by entity-management panels.
+ */
+export function ManagementEmpty(props: ManagementEmptyProps) {
+	return (
+		<div
+			className={cn(
+				"w-full rounded-lg border border-dashed bg-muted/20 px-4 py-3 text-sm text-muted-foreground",
+				props.className,
+			)}
+			data-testid={props.testId}
+		>
+			{props.children}
+		</div>
+	)
+}