@hoardodile/ui 0.0.0

package/src/components/icon.tsx

@@ -0,0 +1,66 @@
+import type { ComponentType } from "react"
+import { cn } from "../lib/utils.ts"
+import type { IconMode } from "../icons/icon-style.ts"
+
+/** Anything renderable through `Icon`: a Solar icon (imported from the
+    central registry on the web side) or a local utility mark (marks.tsx) —
+    both take `className`; registry icons take `mode` (marks ignore it). */
+export type IconType = ComponentType<{ className?: string; mode?: IconMode }>
+
+/** The three sanctioned icon sizes: `sm` 12 inside pills and meta lines,
+    `md` 16 by default, `lg` 20 for primary toolbar actions. */
+export type IconSize = "sm" | "md" | "lg"
+
+const sizeClasses = {
+	sm: "size-3",
+	md: "size-4",
+	lg: "size-5",
+} as const satisfies Record<IconSize, string>
+
+/**
+ * Solar icons with the design system's defaults baked in: callers pass
+ * the registry icon — by default it renders the boldDuotone weight,
+ * whose second tone takes the palette's `--icon-tone` hue (theme.css
+ * recolors the duotone accent via `--solar-secondary-color` under the
+ * `hd-icon` hook), so colored palettes feel alive while mono stays
+ * neutral.
+ *
+ * Mode is one channel: `mode` picks the weight directly; `selected` maps
+ * to `"bold"` (the filled, single-color weight — the only sanctioned use
+ * of Bold); otherwise the active icon style preference decides.
+ *
+ * Sizing is class-based, three tiers only — `sm`/`md`/`lg` map to
+ * `size-3/4/5` (12/16/20). Escape the tiers with
+ * `className="size-[18px]"` — twMerge lets the later class win.
+ *
+ * ✓/×/+ semantics never use Solar's Circle/Square composites — the
+ * container is full-bleed while the informative mark is barely a third
+ * of the box, so it goes muddy at small sizes. The plain marks (Check,
+ * Cross, Plus from marks.tsx) cover these at every size; `sm` otherwise
+ * belongs to simple single-stroke glyphs (arrows, dots, grips).
+ */
+export function Icon({
+	icon: IconComponent,
+	mode,
+	size = "md",
+	selected,
+	className,
+	...rest
+}: {
+	icon: IconType
+	/** Explicit weight override; `selected` and the style preference lose
+	    to it. */
+	mode?: IconMode
+	size?: IconSize
+	/** Selected state — renders the icon's `"bold"` weight. */
+	selected?: boolean
+	className?: string
+} & Record<string, unknown>) {
+	return (
+		<IconComponent
+			mode={mode ?? (selected === true ? "bold" : undefined)}
+			className={cn("hd-icon", sizeClasses[size], className)}
+			{...rest}
+		/>
+	)
+}

package/src/components/image-crop-panel.test.tsx

@@ -0,0 +1,167 @@
+import { screen, waitFor, within } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+import { renderWithI18n } from "../test/i18n"
+import { AppDialog } from "./app-dialog"
+import { ImageCropPanel } from "./image-crop-panel"
+
+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"
+
+describe("ImageCropPanel", () => {
+	it("constrains the image within the provided crop stage bounds", async () => {
+		renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				cropStageWidth={260}
+				cropStageHeight={500}
+				hideActionButton
+				onSave={vi.fn()}
+			/>,
+		)
+
+		const img = await screen.findByRole("img")
+		expect(img).toHaveStyle({
+			"max-width": "260px",
+			"max-height": "500px",
+		})
+	})
+
+	it("uses default bounds when crop stage dimensions are omitted", async () => {
+		renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				hideActionButton
+				onSave={vi.fn()}
+			/>,
+		)
+
+		const img = await screen.findByRole("img")
+		expect(img).toHaveStyle({
+			"max-width": "320px",
+			"max-height": "240px",
+		})
+	})
+
+	it("keeps the crop stage wrapper within the effective bounds", async () => {
+		const { container } = renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				cropStageWidth={200}
+				cropStageHeight={200}
+				hideActionButton
+				onSave={vi.fn()}
+			/>,
+		)
+
+		const stage = container.querySelector("[data-testid='image-crop-frame']")
+		expect(stage).toBeNull()
+
+		const wrapper = container.querySelector(
+			".overflow-hidden.rounded-md.border",
+		)
+		await waitFor(() => expect(wrapper).toBeInTheDocument())
+		expect(wrapper).toHaveStyle({
+			width: "200px",
+			height: "200px",
+			"max-width": "200px",
+			"max-height": "200px",
+		})
+	})
+
+	it("does not render the live preview when hidden", async () => {
+		renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				hideActionButton
+				hidePreview
+				onSave={vi.fn()}
+			/>,
+		)
+
+		await screen.findByRole("img")
+		expect(screen.queryByTestId("image-crop-preview")).not.toBeInTheDocument()
+	})
+
+	it("stretches the stage to fill its parent width when filling", async () => {
+		const { container } = renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				cropStageWidth={13}
+				cropStageHeight={25}
+				hideActionButton
+				fillWidth
+				onSave={vi.fn()}
+			/>,
+		)
+
+		const img = await screen.findByRole("img")
+		expect(img).toHaveStyle({ "max-width": "100%" })
+
+		const wrapper = container.querySelector(
+			".overflow-hidden.rounded-md.border",
+		)
+		await waitFor(() => expect(wrapper).toBeInTheDocument())
+		expect(wrapper).toHaveStyle({ "aspect-ratio": "13 / 25" })
+		expect(wrapper).not.toHaveStyle({ width: "13px" })
+		expect(wrapper?.parentElement).toHaveClass("w-full")
+	})
+
+	it("renders the save button on the same footer row as the dialog's cancel", async () => {
+		renderWithI18n(
+			<AppDialog
+				open
+				title="Cover"
+				onOpenChange={() => {}}
+				footer={
+					<button type="button" data-testid="dialog-cancel">
+						Cancel
+					</button>
+				}
+			>
+				<ImageCropPanel
+					initialSrc={TALL_IMAGE_SRC}
+					onSave={vi.fn()}
+				/>
+			</AppDialog>,
+		)
+
+		await screen.findByRole("img")
+		// The dialog renders into a portal, so the footer lives on the
+		// document rather than the render container.
+		const footer = document.querySelector('[data-slot="dialog-footer"]')
+		expect(footer).not.toBeNull()
+		// The panel contributes its action through DialogFooterActions, so
+		// save and cancel share the dialog's footer row.
+		expect(
+			within(footer as HTMLElement).getByTestId("image-crop-save"),
+		).toHaveTextContent("Save")
+		expect(
+			within(footer as HTMLElement).getByTestId("dialog-cancel"),
+		).toBeInTheDocument()
+	})
+
+	it("renders the action button as an inline panel row outside a dialog", () => {
+		const { container } = renderWithI18n(
+			<ImageCropPanel onClear={vi.fn()} onSave={vi.fn()} />,
+		)
+
+		expect(screen.getByTestId("image-crop-frame")).toBeInTheDocument()
+		// No image selected: the action button becomes "Remove".
+		const remove = screen.getByTestId("image-crop-save")
+		expect(remove).toHaveTextContent("Remove")
+		expect(container.querySelector('[data-slot="dialog-footer"]')).toBeNull()
+	})
+
+	it("hides the action button when hideActionButton is set", async () => {
+		renderWithI18n(
+			<ImageCropPanel
+				initialSrc={TALL_IMAGE_SRC}
+				hideActionButton
+				onSave={vi.fn()}
+			/>,
+		)
+
+		await screen.findByRole("img")
+		expect(screen.queryByTestId("image-crop-save")).not.toBeInTheDocument()
+	})
+})

package/src/components/image-crop-panel.tsx

@@ -0,0 +1,465 @@
+import {
+	DialogFooterActions,
+	useDialogFooterActions,
+} from "@hoardodile/ui/components/app-dialog"
+import { Button } from "@hoardodile/ui/components/button"
+import { Label } from "@hoardodile/ui/components/label"
+import { Switch } from "@hoardodile/ui/components/switch"
+import { toast } from "@hoardodile/ui/components/toast"
+import { Gallery, RefreshCircle, Upload } from "@hoardodile/ui/icons/registry"
+import { cn } from "@hoardodile/ui/lib/utils"
+import { useCallback, useEffect, useId, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+import type { CroppedImage } from "./image-cropper"
+import { ImageCropper } from "./image-cropper"
+
+export type ImageCropPanelProps = {
+	readonly aspect?: number
+	readonly mimeType?: "image/png" | "image/jpeg" | "image/webp"
+	readonly accept?: string
+	readonly previewShape?: "square" | "circle"
+	readonly previewWidth?: number
+	readonly previewHeight?: number
+	/**
+	 * Called when the user clicks "save". Receives the cropped image
+	 * payload. Should return a promise that resolves once the upload is
+	 * complete; the panel then notifies via {@link onSaved}.
+	 *
+	 * @throws The implementation may throw to surface an error toast.
+	 */
+	readonly onSave: (cropped: CroppedImage) => Promise<unknown>
+	readonly onSaved?: () => void
+	/**
+	 * Called when the user clicks the action button but no image has been
+	 * selected. The parent (e.g. {@link ImageEditPanel}) can treat this as a
+	 * request to remove the existing image.
+	 */
+	readonly onClear?: () => void
+	/**
+	 * When set (e.g. canvas snapshot object URL), skips the empty picker and
+	 * shows the cropper immediately.
+	 */
+	readonly initialSrc?: string
+	/**
+	 * When false, hides file pick / drag-drop and "reselect" (preset image only).
+	 */
+	readonly allowChangeSource?: boolean
+	/** Notifies parent when an async save starts / finishes (for dialog guards). */
+	readonly onSavingChange?: (saving: boolean) => void
+	/** Exact size (px) of the empty picker frame / crop stage. Overrides the default 240×240. */
+	readonly cropStageWidth?: number
+	readonly cropStageHeight?: number
+	/**
+	 * When true, the right-hand live preview is hidden until the user turns
+	 * the switch on (saves work over large captures / WebGL snapshots).
+	 */
+	readonly showPreviewSwitch?: boolean
+	/**
+	 * When true, the live preview pane is never rendered — the crop stage is
+	 * the only surface. Used by creation forms whose panel column has no
+	 * room for a side-by-side preview.
+	 */
+	readonly hidePreview?: boolean
+	/**
+	 * When true, the crop stage fills its parent width and keeps the aspect
+	 * ratio implied by {@link cropStageWidth} / {@link cropStageHeight}
+	 * (full-bleed `aspect-square w-full` panels). Ignored when only
+	 * one stage dimension is given.
+	 */
+	readonly fillWidth?: boolean
+	/** Extra classes on the root panel wrapper. */
+	readonly panelClassName?: string
+	/** Extra classes on the row that holds the crop stage + preview. */
+	readonly containerClassName?: string
+	/** Extra classes on the column wrapping the crop stage (e.g. flex-1 min-w-0). */
+	readonly cropColumnClassName?: string
+	/** Extra classes on the bordered crop stage box (merged with defaults via tailwind-merge). */
+	readonly cropStageClassName?: string
+	/** When true, the bottom save/remove action button is hidden. */
+	readonly hideActionButton?: boolean
+	/**
+	 * When true, automatically calls {@link onSave} after the user finishes
+	 * adjusting the crop (debounced by 600 ms). Useful when the action button
+	 * is hidden and the parent only needs the final crop at form-submit time.
+	 */
+	readonly autoSaveOnCrop?: boolean
+}
+
+/**
+ * Inline image picker + cropper with live preview.
+ */
+export function ImageCropPanel(props: ImageCropPanelProps) {
+	const {
+		aspect,
+		mimeType = "image/png",
+		accept = "image/*",
+		previewShape = "square",
+		previewWidth: previewWidthProp,
+		previewHeight: previewHeightProp,
+		onSave,
+		onSaved,
+		onClear,
+		initialSrc,
+		allowChangeSource = true,
+		onSavingChange,
+		cropStageWidth,
+		cropStageHeight,
+		showPreviewSwitch = false,
+		hidePreview = false,
+		fillWidth = false,
+		panelClassName,
+		containerClassName,
+		cropColumnClassName,
+		cropStageClassName,
+		hideActionButton = false,
+		autoSaveOnCrop = false,
+	} = props
+	const { t } = useTranslation("ui", { useSuspense: false })
+	const footerSlot = useDialogFooterActions()
+	const previewWidth = previewWidthProp ?? cropStageWidth ?? 200
+	const previewHeight = previewHeightProp ?? cropStageHeight ?? 200
+	const effectiveCropWidth = cropStageWidth ?? 320
+	const effectiveCropHeight = cropStageHeight ?? 240
+	// Full-bleed stage: the aspect ratio of the requested stage dimensions,
+	// stretched to whatever width the parent column gives us.
+	const stageAspectRatio =
+		fillWidth && cropStageWidth !== undefined && cropStageHeight !== undefined
+			? `${cropStageWidth} / ${cropStageHeight}`
+			: undefined
+	const previewToggleId = useId()
+	const fileInputRef = useRef<HTMLInputElement | null>(null)
+	const [imageSrc, setImageSrc] = useState<string | undefined>(initialSrc)
+	const renderRef = useRef<(() => Promise<CroppedImage>) | undefined>(undefined)
+	const [previewDataUrl, setPreviewDataUrl] = useState<string | undefined>(
+		undefined,
+	)
+	const [previewPaneOn, setPreviewPaneOn] = useState(false)
+	const [dragOver, setDragOver] = useState(false)
+	const [saving, setSaving] = useState(false)
+	const previewVisible = !hidePreview && (!showPreviewSwitch || previewPaneOn)
+	const autoSaveTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+		undefined,
+	)
+	const callbacksRef = useRef({ onSave, onSaved, onSavingChange, t })
+	callbacksRef.current = { onSave, onSaved, onSavingChange, t }
+
+	useEffect(
+		function syncInitialSrc() {
+			if (initialSrc !== undefined) setImageSrc(initialSrc)
+		},
+		[initialSrc],
+	)
+
+	const handleCropReady = useCallback(
+		(render: () => Promise<CroppedImage>) => {
+			renderRef.current = render
+			if (autoSaveOnCrop) {
+				if (autoSaveTimerRef.current) {
+					clearTimeout(autoSaveTimerRef.current)
+				}
+				autoSaveTimerRef.current = setTimeout(() => {
+					render()
+						.then(async (cropped) => {
+							const { onSave, onSaved, onSavingChange, t } =
+								callbacksRef.current
+							try {
+								setSaving(true)
+								onSavingChange?.(true)
+								await onSave(cropped)
+								onSaved?.()
+							} catch (err) {
+								const msg = err instanceof Error ? err.message : String(err)
+								toast.add({
+									title: msg || t("imageCrop.saveFailed"),
+									type: "error",
+								})
+							} finally {
+								setSaving(false)
+								onSavingChange?.(false)
+							}
+						})
+						.catch((err) => {
+							const { t } = callbacksRef.current
+							const msg = err instanceof Error ? err.message : String(err)
+							toast.add({
+								title: msg || t("imageCrop.saveFailed"),
+								type: "error",
+							})
+						})
+				}, 600)
+			}
+		},
+		[autoSaveOnCrop],
+	)
+
+	const handlePreviewChange = useCallback((dataUrl: string) => {
+		setPreviewDataUrl(dataUrl)
+	}, [])
+
+	function handlePreviewToggle(on: boolean) {
+		setPreviewPaneOn(on)
+		if (!on) setPreviewDataUrl(undefined)
+	}
+
+	function handleFileChange(e: React.ChangeEvent<HTMLInputElement>) {
+		const file = e.target.files?.[0]
+		if (file === undefined) return
+		readFileAsDataUrl(file)
+	}
+
+	function handleDrop(e: React.DragEvent<HTMLElement>) {
+		e.preventDefault()
+		setDragOver(false)
+		const file = e.dataTransfer.files?.[0]
+		if (file !== undefined) readFileAsDataUrl(file)
+	}
+
+	function readFileAsDataUrl(file: File) {
+		const reader = new FileReader()
+		reader.addEventListener("load", () => {
+			const result = reader.result
+			if (typeof result === "string") setImageSrc(result)
+		})
+		reader.readAsDataURL(file)
+	}
+
+	function handleReselect() {
+		if (autoSaveTimerRef.current) {
+			clearTimeout(autoSaveTimerRef.current)
+			autoSaveTimerRef.current = undefined
+		}
+		setImageSrc(undefined)
+		renderRef.current = undefined
+		setPreviewDataUrl(undefined)
+		setPreviewPaneOn(false)
+		fileInputRef.current?.click()
+	}
+
+	async function handleSave() {
+		const render = renderRef.current
+		if (render === undefined) {
+			onClear?.()
+			return
+		}
+		setSaving(true)
+		onSavingChange?.(true)
+		try {
+			const cropped = await render()
+			await onSave(cropped)
+			onSaved?.()
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err)
+			toast.add({
+				title: msg || t("imageCrop.saveFailed"),
+				type: "error",
+			})
+		} finally {
+			setSaving(false)
+			onSavingChange?.(false)
+		}
+	}
+
+	const previewRadiusClass =
+		previewShape === "circle" ? "rounded-full" : "rounded"
+
+	const actionButton = (
+		<Button
+			type="button"
+			onClick={handleSave}
+			disabled={saving}
+			data-testid="image-crop-save"
+		>
+			{saving
+				? t("imageCrop.saving")
+				: imageSrc === undefined
+					? t("imageCrop.remove")
+					: t("imageCrop.save")}
+		</Button>
+	)
+
+	return (
+		<div className={cn("flex flex-col gap-4", panelClassName)}>
+			{allowChangeSource ? (
+				<input
+					ref={fileInputRef}
+					type="file"
+					accept={accept}
+					className="hidden"
+					onChange={handleFileChange}
+					data-testid="image-crop-file-input"
+				/>
+			) : null}
+
+			<div
+				className={cn(
+					"flex flex-col items-center gap-6 py-2 sm:flex-row sm:items-center sm:justify-center",
+					containerClassName,
+				)}
+			>
+				<div
+					className={cn(
+						"flex flex-col items-center gap-2",
+						stageAspectRatio !== undefined && "w-full",
+						cropColumnClassName,
+					)}
+				>
+					{imageSrc === undefined ? (
+						allowChangeSource ? (
+							<button
+								type="button"
+								onClick={() => fileInputRef.current?.click()}
+								onDragOver={(e) => {
+									e.preventDefault()
+									setDragOver(true)
+								}}
+								onDragLeave={() => setDragOver(false)}
+								onDrop={handleDrop}
+								className={cn(
+									"flex select-none flex-col items-center justify-center gap-2 rounded-md border border-border bg-muted text-muted-foreground transition-colors duration-300 hover:bg-accent hover:text-accent-foreground",
+									dragOver && "bg-accent text-accent-foreground",
+									stageAspectRatio !== undefined && "w-full",
+								)}
+								data-testid="image-crop-frame"
+								style={
+									stageAspectRatio !== undefined
+										? { aspectRatio: stageAspectRatio }
+										: {
+												width: cropStageWidth ?? 240,
+												height: cropStageHeight ?? 240,
+											}
+								}
+							>
+								<Upload className="size-5" />
+								<p className="text-sm">{t("imageCrop.pickHint")}</p>
+							</button>
+						) : (
+							<div
+								className={cn(
+									"flex items-center justify-center rounded-md border border-dashed border-border text-sm text-muted-foreground",
+									stageAspectRatio !== undefined && "w-full",
+								)}
+								style={
+									stageAspectRatio !== undefined
+										? { aspectRatio: stageAspectRatio }
+										: {
+												width: cropStageWidth ?? 240,
+												height: cropStageHeight ?? 240,
+											}
+								}
+							>
+								{t("imageCrop.pickHint")}
+							</div>
+						)
+					) : (
+						<div
+							className={cn(
+								"flex min-h-0 items-center justify-center overflow-hidden rounded-md border border-border bg-card",
+								stageAspectRatio === undefined && "max-w-90",
+								cropStageClassName,
+								stageAspectRatio !== undefined && "w-full",
+							)}
+							style={
+								stageAspectRatio !== undefined
+									? { aspectRatio: stageAspectRatio }
+									: {
+											minHeight: `${cropStageHeight}px`,
+											minWidth: `${cropStageWidth}px`,
+											width: effectiveCropWidth,
+											height: effectiveCropHeight,
+											maxWidth: effectiveCropWidth,
+											maxHeight: effectiveCropHeight,
+										}
+							}
+						>
+							<ImageCropper
+								src={imageSrc}
+								aspect={aspect}
+								mimeType={mimeType}
+								displayMaxWidth={
+									stageAspectRatio !== undefined ? "100%" : effectiveCropWidth
+								}
+								displayMaxHeight={
+									stageAspectRatio !== undefined
+										? undefined
+										: effectiveCropHeight
+								}
+								onCropReady={handleCropReady}
+								onPreviewChange={
+									previewVisible ? handlePreviewChange : undefined
+								}
+						/>
+					</div>
+					)}
+					{imageSrc !== undefined && allowChangeSource ? (
+						<Button
+							type="button"
+							size="sm"
+							variant="ghost"
+							onClick={handleReselect}
+							className="text-muted-foreground text-xs"
+						>
+							<RefreshCircle className="mr-1 h-3.5 w-3.5" />
+							{t("imageCrop.reselect")}
+						</Button>
+					) : null}
+				</div>
+
+				{previewVisible ? (
+					<>
+						<div className={cn("hidden w-px bg-border sm:block h-40")} />
+						<div className={cn("block bg-border sm:hidden h-px w-32")} />
+
+						<div className={cn("flex shrink-0 flex-col items-center gap-1.5")}>
+							<div
+								style={{ width: previewWidth, height: previewHeight }}
+								className={cn(
+									"flex items-center justify-center overflow-hidden border border-border bg-muted text-muted-foreground",
+									previewRadiusClass,
+								)}
+								data-testid="image-crop-preview"
+								title={t("imageCrop.previewLabel")}
+							>
+								{previewDataUrl !== undefined ? (
+									<img
+										src={previewDataUrl}
+										alt={t("imageCrop.previewAlt")}
+										className="max-h-full max-w-full object-cover"
+									/>
+								) : (
+									<Gallery className="h-10 w-10 opacity-60" />
+								)}
+							</div>
+						</div>
+					</>
+				) : null}
+			</div>
+
+			{showPreviewSwitch && imageSrc !== undefined ? (
+				<div className={cn("flex items-center justify-center gap-2")}>
+					<Switch
+						id={previewToggleId}
+						checked={previewPaneOn}
+						onCheckedChange={handlePreviewToggle}
+						data-testid="image-crop-preview-toggle"
+					/>
+					<Label
+						htmlFor={previewToggleId}
+						className="text-muted-foreground cursor-pointer text-sm font-normal"
+					>
+						{t("imageCrop.showPreview")}
+					</Label>
+				</div>
+			) : null}
+
+			{/* The save/remove action lands on the surrounding dialog's
+			    footer row — side by side with Cancel. Outside a dialog it
+			    falls back to an inline row at the panel's bottom. */}
+			{!hideActionButton &&
+				(footerSlot === null ? (
+					<div className={cn("flex justify-end pt-2")}>{actionButton}</div>
+				) : (
+					<DialogFooterActions>{actionButton}</DialogFooterActions>
+				))}
+		</div>
+	)
+}