@voila.dev/ui 1.1.9

package/src/components/ui/gallery.tsx

@@ -0,0 +1,161 @@
+import { ImageIcon } from "@phosphor-icons/react";
+import * as React from "react";
+import {
+	Carousel,
+	type CarouselApi,
+	CarouselContent,
+	CarouselItem,
+	CarouselNext,
+	CarouselPrevious,
+} from "#/components/ui/carousel.tsx";
+import { Dialog, DialogContent, DialogTitle } from "#/components/ui/dialog.tsx";
+import {
+	Empty,
+	EmptyDescription,
+	EmptyHeader,
+	EmptyMedia,
+	EmptyTitle,
+} from "#/components/ui/empty.tsx";
+import { cn } from "#/lib/utils.ts";
+
+type GalleryImage = { src: string; alt?: string };
+
+/**
+ * Full-screen image viewer built on Dialog + Carousel. Controlled via `open`
+ * / `onOpenChange`; `startIndex` selects which image is shown first. Swipe or
+ * use the prev/next controls (embla handles touch on mobile).
+ */
+function Lightbox({
+	images,
+	open,
+	onOpenChange,
+	startIndex = 0,
+}: {
+	images: ReadonlyArray<GalleryImage>;
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	startIndex?: number;
+}) {
+	const [api, setApi] = React.useState<CarouselApi>();
+
+	// Jump to the requested slide whenever the lightbox (re)opens.
+	React.useEffect(() => {
+		if (open && api) api.scrollTo(startIndex, true);
+	}, [open, api, startIndex]);
+
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent
+				size="xl"
+				closeButtonLabel="Close gallery"
+				// The width override repeats the `data-[size=xl]` variant so it beats
+				// the size recipe's own `data-[size=xl]:sm:max-w-xl`.
+				className="bg-background p-2 data-[size=xl]:sm:max-w-3xl"
+			>
+				<DialogTitle className="sr-only">Image gallery</DialogTitle>
+				<Carousel
+					setApi={setApi}
+					opts={{ startIndex, loop: images.length > 1 }}
+					data-slot="lightbox-carousel"
+					className="w-full"
+				>
+					<CarouselContent>
+						{images.map((image, index) => (
+							<CarouselItem key={image.src ?? index}>
+								<div className="flex items-center justify-center">
+									<img
+										src={image.src}
+										alt={image.alt ?? ""}
+										data-slot="lightbox-image"
+										className="max-h-[80dvh] w-auto rounded-lg object-contain"
+									/>
+								</div>
+							</CarouselItem>
+						))}
+					</CarouselContent>
+					{images.length > 1 ? (
+						<>
+							<CarouselPrevious inset />
+							<CarouselNext inset />
+						</>
+					) : null}
+				</Carousel>
+			</DialogContent>
+		</Dialog>
+	);
+}
+
+/**
+ * Responsive thumbnail grid that opens a full-screen `Lightbox` on click.
+ * Renders an `Empty` state when there are no images. Thumbnails are buttons so
+ * they're keyboard-navigable; the lightbox itself is swipeable on mobile.
+ */
+function Gallery({
+	images,
+	emptyLabel = "No photos yet",
+	emptyDescription,
+	className,
+	...props
+}: Omit<React.ComponentProps<"div">, "children"> & {
+	images: ReadonlyArray<GalleryImage>;
+	emptyLabel?: React.ReactNode;
+	emptyDescription?: React.ReactNode;
+}) {
+	const [openIndex, setOpenIndex] = React.useState<number | null>(null);
+
+	if (images.length === 0) {
+		return (
+			<Empty bordered className={className} {...props}>
+				<EmptyHeader>
+					<EmptyMedia variant="icon">
+						<ImageIcon />
+					</EmptyMedia>
+					<EmptyTitle>{emptyLabel}</EmptyTitle>
+					{emptyDescription ? (
+						<EmptyDescription>{emptyDescription}</EmptyDescription>
+					) : null}
+				</EmptyHeader>
+			</Empty>
+		);
+	}
+
+	return (
+		<div data-slot="gallery" className={className} {...props}>
+			<div
+				data-slot="gallery-grid"
+				className="grid grid-cols-2 gap-2 sm:grid-cols-3 md:grid-cols-4"
+			>
+				{images.map((image, index) => (
+					<button
+						key={image.src ?? index}
+						type="button"
+						data-slot="gallery-thumbnail"
+						aria-label={image.alt ?? `Open image ${index + 1}`}
+						className="group/thumb relative aspect-square touch-manipulation overflow-hidden rounded-lg bg-muted outline-none ring-1 ring-foreground/10 transition focus-visible:ring-2 focus-visible:ring-ring/50"
+						onClick={() => setOpenIndex(index)}
+					>
+						<img
+							src={image.src}
+							alt={image.alt ?? ""}
+							loading="lazy"
+							className={cn(
+								"size-full object-cover transition-transform duration-200",
+								"group-hover/thumb:scale-105",
+							)}
+						/>
+					</button>
+				))}
+			</div>
+			<Lightbox
+				images={images}
+				open={openIndex !== null}
+				startIndex={openIndex ?? 0}
+				onOpenChange={(next) => {
+					if (!next) setOpenIndex(null);
+				}}
+			/>
+		</div>
+	);
+}
+
+export { Gallery, type GalleryImage, Lightbox };

package/src/components/ui/hover-card.tsx

@@ -0,0 +1,77 @@
+import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card";
+
+import { cn } from "#/lib/utils.ts";
+
+/**
+ * Rich hover preview (Base UI PreviewCard) for link/mention triggers — an
+ * avatar, a bio, a few stats. For a plain text hint on any control, use
+ * Tooltip instead: a hover card is for content worth lingering on, so it opens
+ * slower and stays open while the pointer is over the card itself.
+ */
+function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
+	return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />;
+}
+
+/**
+ * Opens the card after `delay` (600ms Base UI default) and closes it after
+ * `closeDelay` (300ms default) — both are tuned here, on the trigger.
+ */
+function HoverCardTrigger({ ...props }: PreviewCardPrimitive.Trigger.Props) {
+	return (
+		<PreviewCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+	);
+}
+
+function HoverCardContent({
+	className,
+	align = "center",
+	alignOffset = 0,
+	side = "bottom",
+	sideOffset = 8,
+	collisionPadding = 8,
+	positionerProps,
+	...props
+}: PreviewCardPrimitive.Popup.Props &
+	Pick<
+		PreviewCardPrimitive.Positioner.Props,
+		"align" | "alignOffset" | "collisionPadding" | "side" | "sideOffset"
+	> & {
+		// Escape hatch for the Positioner props not surfaced as dedicated props
+		// (sticky, anchor, positionMethod, arrowPadding…).
+		positionerProps?: Omit<
+			PreviewCardPrimitive.Positioner.Props,
+			| "align"
+			| "alignOffset"
+			| "collisionPadding"
+			| "side"
+			| "sideOffset"
+			| "children"
+		>;
+	}) {
+	const { className: positionerClassName, ...restPositionerProps } =
+		positionerProps ?? {};
+	return (
+		<PreviewCardPrimitive.Portal data-slot="hover-card-portal">
+			<PreviewCardPrimitive.Positioner
+				align={align}
+				alignOffset={alignOffset}
+				collisionPadding={collisionPadding}
+				side={side}
+				sideOffset={sideOffset}
+				className={cn("isolate z-50", positionerClassName)}
+				{...restPositionerProps}
+			>
+				<PreviewCardPrimitive.Popup
+					data-slot="hover-card-content"
+					className={cn(
+						"z-50 w-72 origin-(--transform-origin) rounded-lg bg-popover p-2.5 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 motion-reduce:animate-none",
+						className,
+					)}
+					{...props}
+				/>
+			</PreviewCardPrimitive.Positioner>
+		</PreviewCardPrimitive.Portal>
+	);
+}
+
+export { HoverCard, HoverCardContent, HoverCardTrigger };

package/src/components/ui/icon-picker.tsx

@@ -0,0 +1,193 @@
+import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox";
+import {
+	Icon,
+	type PhosphorIconName,
+	phosphorIconNames,
+} from "@voila.dev/ui-icon/components/icon";
+import { useMemo, useState } from "react";
+import { Button } from "#/components/ui/button.tsx";
+import {
+	Combobox,
+	ComboboxContent,
+	ComboboxEmpty,
+	ComboboxInput,
+	ComboboxList,
+	ComboboxRow,
+} from "#/components/ui/combobox.tsx";
+import { cn } from "#/lib/utils.ts";
+
+/**
+ * Cap on rendered swatches — the full Phosphor set (~1,500) would jank. The
+ * grid is not virtualized; matches beyond the cap are summarized by the
+ * "+N more" hint and reachable by refining the search.
+ */
+const RESULT_LIMIT = 120;
+
+const GRID_COLUMNS = 6;
+
+/** Human-friendly label for an icon name: "FirstAidKitIcon" → "First Aid Kit". */
+const formatIconName = (name: string): string =>
+	name.replace(/Icon$/, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+
+const chunkIntoRows = (
+	iconNames: readonly string[],
+	columns: number,
+): string[][] => {
+	const rows: string[][] = [];
+	for (let index = 0; index < iconNames.length; index += columns) {
+		rows.push(iconNames.slice(index, index + columns) as string[]);
+	}
+	return rows;
+};
+
+export function IconPicker({
+	value: controlledValue,
+	defaultValue = null,
+	onValueChange,
+	placeholder = "Select an icon",
+	searchPlaceholder = "Search icons…",
+	emptyLabel = "No icons found",
+	clearLabel = "Clear selection",
+	moreLabel,
+	name,
+	disabled = false,
+	closeOnSelect = true,
+	className,
+}: {
+	/** Controlled selection; omit to let the picker manage its own state. */
+	value?: PhosphorIconName | (string & {}) | null;
+	/** Initial selection for uncontrolled usage. */
+	defaultValue?: PhosphorIconName | (string & {}) | null;
+	onValueChange?: (name: string | null) => void;
+	placeholder?: string;
+	searchPlaceholder?: string;
+	emptyLabel?: string;
+	clearLabel?: string;
+	moreLabel?: (count: number) => string;
+	/** When set, renders a hidden input so plain form posts include the icon. */
+	name?: string;
+	disabled?: boolean;
+	/** Keep the popover open after a pick, for rapid-compare flows. */
+	closeOnSelect?: boolean;
+	className?: string;
+}) {
+	const [query, setQuery] = useState("");
+
+	const matches = useMemo(() => {
+		// Spaces are stripped so the human-formatted spelling shown on the
+		// trigger ("First Aid Kit") finds the camelCase export it came from.
+		const q = query.trim().toLowerCase().replace(/\s+/g, "");
+		if (q.length === 0) return phosphorIconNames;
+		const prefixMatches: string[] = [];
+		const substringMatches: string[] = [];
+		for (const iconName of phosphorIconNames) {
+			const lower = iconName.toLowerCase();
+			if (!lower.includes(q)) continue;
+			if (lower.startsWith(q)) prefixMatches.push(iconName);
+			else substringMatches.push(iconName);
+		}
+		return [...prefixMatches, ...substringMatches];
+	}, [query]);
+
+	const shown = matches.slice(0, RESULT_LIMIT);
+	const hidden = matches.length - shown.length;
+	const rows = useMemo(() => chunkIntoRows(shown, GRID_COLUMNS), [shown]);
+
+	return (
+		<Combobox<string>
+			grid
+			filteredItems={rows}
+			{...(controlledValue !== undefined && { value: controlledValue })}
+			defaultValue={defaultValue}
+			onValueChange={(next) => onValueChange?.(next ?? null)}
+			inputValue={query}
+			onInputValueChange={setQuery}
+			onOpenChange={(nextOpen, eventDetails) => {
+				if (
+					!nextOpen &&
+					!closeOnSelect &&
+					eventDetails.reason === "item-press"
+				) {
+					eventDetails.cancel();
+					return;
+				}
+				if (!nextOpen) setQuery("");
+			}}
+			name={name}
+			disabled={disabled}
+		>
+			<ComboboxPrimitive.Trigger
+				data-slot="icon-picker-trigger"
+				render={
+					<Button
+						type="button"
+						variant="outline"
+						disabled={disabled}
+						className={cn("w-full justify-start gap-2", className)}
+					/>
+				}
+			>
+				<ComboboxPrimitive.Value>
+					{(selected: string | null) => (
+						<>
+							{selected ? <Icon name={selected} className="size-4" /> : null}
+							<span className="truncate">
+								{selected ? formatIconName(selected) : placeholder}
+							</span>
+						</>
+					)}
+				</ComboboxPrimitive.Value>
+			</ComboboxPrimitive.Trigger>
+			{/* Fixed width keeps the 6-column grid compact: anchored to a wide
+			    (e.g. full-width) trigger, an anchor-width popup would stretch the
+			    swatches apart. max-w clamps to the viewport on small screens. */}
+			<ComboboxContent className="w-72 min-w-72 max-w-(--available-width)">
+				<ComboboxInput
+					placeholder={searchPlaceholder}
+					showTrigger={false}
+					data-slot="icon-picker-search"
+				/>
+				<ComboboxEmpty>{emptyLabel}</ComboboxEmpty>
+				<ComboboxList
+					aria-label={placeholder}
+					data-slot="icon-picker-grid"
+					className="space-y-1"
+				>
+					{(row: string[], rowIndex: number) => (
+						<ComboboxRow
+							key={row[0] ?? rowIndex}
+							className="grid grid-cols-6 gap-1"
+						>
+							{row.map((iconName) => (
+								<ComboboxPrimitive.Item
+									key={iconName}
+									value={iconName}
+									data-slot="icon-picker-swatch"
+									title={formatIconName(iconName)}
+									aria-label={formatIconName(iconName)}
+									className="flex aspect-square items-center justify-center rounded-md transition-colors duration-100 outline-none select-none data-highlighted:bg-muted data-selected:bg-accent data-selected:ring-1 data-selected:ring-primary"
+								>
+									<Icon name={iconName} className="size-5" />
+								</ComboboxPrimitive.Item>
+							))}
+						</ComboboxRow>
+					)}
+				</ComboboxList>
+				{hidden > 0 && (
+					<p className="pb-1 text-center text-xs text-muted-foreground">
+						{moreLabel
+							? moreLabel(hidden)
+							: `+${hidden} more — refine your search`}
+					</p>
+				)}
+				<ComboboxPrimitive.Clear
+					data-slot="icon-picker-clear"
+					render={<Button type="button" variant="ghost" size="sm" />}
+					className="m-1 mt-0"
+				>
+					{clearLabel}
+				</ComboboxPrimitive.Clear>
+			</ComboboxContent>
+		</Combobox>
+	);
+}