@voila.dev/ui 1.1.9

package/src/components/ui/translation-input.tsx

@@ -0,0 +1,126 @@
+import type * as React from "react";
+import {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupInput,
+} from "#/components/ui/input-group.tsx";
+import { cn } from "#/lib/utils.ts";
+
+/** A value carrying one string per locale, keyed by locale tag. */
+type TranslationValue = Record<string, string>;
+
+const isBlank = (text: string | undefined): boolean =>
+	(text ?? "").trim().length === 0;
+
+/**
+ * Writes `text` to `locale`, carrying it into every locale that is still blank
+ * so a value written once is complete. Locales that already hold their own
+ * wording are left alone - this only ever fills gaps, never overwrites a
+ * translation.
+ */
+function writeLocale(
+	value: TranslationValue,
+	locales: ReadonlyArray<string>,
+	locale: string,
+	text: string,
+): TranslationValue {
+	const next: TranslationValue = { ...value, [locale]: text };
+	for (const tag of locales) {
+		if (tag !== locale && isBlank(value[tag])) {
+			next[tag] = text;
+		}
+	}
+	return next;
+}
+
+type TranslationInputProps = Omit<
+	React.ComponentProps<typeof InputGroupInput>,
+	"type" | "value" | "onChange" | "onValueChange"
+> & {
+	/** The whole per-locale record; only the active locale's string is shown. */
+	value: TranslationValue;
+	/** Receives the whole record with the active locale's string replaced. */
+	onValueChange: (value: TranslationValue) => void;
+	/** Locale whose string is currently being edited. */
+	locale: string;
+	/** Locale tags offered by the select, in display order. */
+	locales: ReadonlyArray<string>;
+	/** Receives the newly selected locale. */
+	onLocaleChange: (locale: string) => void;
+	/** Accessible name for the locale select. */
+	localeLabel: string;
+	/** Short display code per locale (e.g. `{ "fr-FR": "FR" }`). Falls back to the tag. */
+	localeCodes?: Record<string, string>;
+	/** Wrapper class (width/layout), forwarded to the `InputGroup`. */
+	className?: string;
+};
+
+/**
+ * A translated text input: one field editing the active locale's string, with a
+ * trailing locale select to switch between them. The whole per-locale record is
+ * the value, so a consumer binds one field instead of one per language and a
+ * switch never loses what the other locales hold.
+ *
+ * The select marks locales that are still empty with a dot, so a partially
+ * translated value is visible without opening each language in turn.
+ *
+ * A locale that is still EMPTY follows what you type, so writing the wording
+ * once yields a complete value instead of forcing the author through every
+ * language before the field can be saved. As soon as a locale has its own
+ * wording it stops following and is only edited directly.
+ */
+function TranslationInput({
+	value,
+	onValueChange,
+	locale,
+	locales,
+	onLocaleChange,
+	localeLabel,
+	localeCodes,
+	className,
+	...props
+}: TranslationInputProps) {
+	return (
+		<InputGroup
+			// The input has no intrinsic width, so under `table-layout: auto` a
+			// grid cell would collapse it to a couple of characters. A floor keeps
+			// the text readable wherever it is dropped.
+			className={cn("min-w-44", className)}
+			data-slot="translation-input"
+		>
+			<InputGroupInput
+				type="text"
+				value={value[locale] ?? ""}
+				onChange={(event) =>
+					onValueChange(writeLocale(value, locales, locale, event.target.value))
+				}
+				{...props}
+			/>
+			<InputGroupAddon align="inline-end">
+				<select
+					data-slot="translation-input-locale"
+					aria-label={localeLabel}
+					value={locale}
+					onChange={(event) => onLocaleChange(event.target.value)}
+					className={cn(
+						"cursor-pointer appearance-none bg-transparent pr-1 text-sm font-medium text-muted-foreground outline-none",
+					)}
+				>
+					{locales.map((tag) => {
+						const filled = (value[tag] ?? "").trim().length > 0;
+						const code = localeCodes?.[tag] ?? tag;
+						// The bullet flags a locale with nothing in it yet; `<option>`
+						// cannot host markup, so the status rides in the text.
+						return (
+							<option key={tag} value={tag}>
+								{filled ? code : `• ${code}`}
+							</option>
+						);
+					})}
+				</select>
+			</InputGroupAddon>
+		</InputGroup>
+	);
+}
+
+export { TranslationInput, type TranslationInputProps, type TranslationValue };

package/src/components/ui/user-avatar.tsx

@@ -0,0 +1,74 @@
+import type * as React from "react";
+import {
+	Avatar,
+	AvatarBadge,
+	AvatarFallback,
+	AvatarImage,
+} from "#/components/ui/avatar.tsx";
+
+import { cn } from "#/lib/utils.ts";
+
+/** Derive up-to-two-letter initials from a full name ("Camille Dubois" → "CD"). */
+function getInitials(name: string): string {
+	const words = name.trim().split(/\s+/).filter(Boolean);
+	const firstLetter = words[0]?.[0] ?? "";
+	const lastLetter = words.length > 1 ? (words.at(-1)?.[0] ?? "") : "";
+	return `${firstLetter}${lastLetter}`.toUpperCase();
+}
+
+/**
+ * Identity row pairing an Avatar with a name and an optional role line - the
+ * recurring pattern in chat headers, tables and cards. Initials are derived
+ * from `name` when the image is missing or fails to load.
+ */
+function UserAvatar({
+	className,
+	name,
+	description,
+	src,
+	status,
+	size = "default",
+	...props
+}: React.ComponentProps<"div"> & {
+	name: string;
+	description?: React.ReactNode;
+	src?: string;
+	status?: React.ComponentProps<typeof AvatarBadge>["status"];
+	size?: React.ComponentProps<typeof Avatar>["size"];
+}) {
+	return (
+		<div
+			data-slot="user-avatar"
+			data-size={size}
+			className={cn(
+				"group/user-avatar flex min-w-0 items-center gap-2",
+				className,
+			)}
+			{...props}
+		>
+			<Avatar size={size}>
+				{src ? <AvatarImage src={src} alt={name} /> : null}
+				<AvatarFallback>{getInitials(name)}</AvatarFallback>
+				{status ? <AvatarBadge status={status} /> : null}
+			</Avatar>
+			<div className="flex min-w-0 flex-col">
+				<span
+					data-slot="user-avatar-name"
+					className="truncate text-sm leading-tight font-medium"
+				>
+					{name}
+				</span>
+				{description ? (
+					<span
+						data-slot="user-avatar-description"
+						className="truncate text-xs leading-tight text-muted-foreground"
+					>
+						{description}
+					</span>
+				) : null}
+			</div>
+		</div>
+	);
+}
+
+export { getInitials, UserAvatar };

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+// Side-effect CSS imports (e.g. maplibre-gl's stylesheet) carry no type
+// declarations; the app bundlers get this from `vite/client`, but this package
+// typechecks standalone, so declare the module shape here.
+declare module "*.css" {}

package/src/hooks/use-command-palette.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+
+/**
+ * Open/close state for a CommandDialog bound to a global hotkey
+ * (⌘+key on macOS, Ctrl+key elsewhere). Defaults to ⌘K / Ctrl+K.
+ */
+export function useCommandPalette(key = "k") {
+	const [open, setOpen] = React.useState(false);
+
+	React.useEffect(() => {
+		const onKeyDown = (event: KeyboardEvent) => {
+			// Synthetic keydowns (browser autofill, IME composition) can arrive
+			// without a `key`, so guard before lowercasing it.
+			if (
+				event.key !== undefined &&
+				event.key.toLowerCase() === key.toLowerCase() &&
+				(event.metaKey || event.ctrlKey)
+			) {
+				event.preventDefault();
+				setOpen((previousOpen) => !previousOpen);
+			}
+		};
+		document.addEventListener("keydown", onKeyDown);
+		return () => document.removeEventListener("keydown", onKeyDown);
+	}, [key]);
+
+	return { open, setOpen };
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+	const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+		undefined,
+	);
+
+	React.useEffect(() => {
+		const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+		const onChange = () => {
+			setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		};
+		mql.addEventListener("change", onChange);
+		setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		return () => mql.removeEventListener("change", onChange);
+	}, []);
+
+	return !!isMobile;
+}

package/src/hooks/use-pagination.ts

@@ -0,0 +1,81 @@
+import * as React from "react";
+
+/** Marker emitted by `getPaginationRange` where page numbers are elided. */
+export const PAGINATION_ELLIPSIS = "ellipsis";
+
+export type PaginationRangeItem = number | typeof PAGINATION_ELLIPSIS;
+
+export type PaginationRangeOptions = {
+	/** Zero-based index of the current page. */
+	page: number;
+	/** Total number of pages. */
+	pageCount: number;
+	/** Pages shown on each side of the current page. */
+	siblingCount?: number;
+	/** Pages always shown at the start and end of the range. */
+	boundaryCount?: number;
+};
+
+function range(start: number, end: number): number[] {
+	return Array.from({ length: end - start + 1 }, (_, index) => start + index);
+}
+
+/**
+ * Windows a page range into at most
+ * `2 * boundaryCount + 2 * siblingCount + 3` items (current page + siblings,
+ * both boundaries, and up to two ellipsis markers). Items are zero-based page
+ * indexes; render `item + 1` for the visible page number.
+ */
+export function getPaginationRange({
+	page,
+	pageCount,
+	siblingCount = 1,
+	boundaryCount = 1,
+}: PaginationRangeOptions): PaginationRangeItem[] {
+	if (pageCount <= 0) {
+		return [];
+	}
+
+	// An ellipsis only ever hides 2+ pages: with windows this small it is
+	// cheaper to show every page than to elide one.
+	if (pageCount <= 2 * boundaryCount + 2 * siblingCount + 3) {
+		return range(0, pageCount - 1);
+	}
+
+	const startBoundary = range(0, boundaryCount - 1);
+	const endBoundary = range(pageCount - boundaryCount, pageCount - 1);
+
+	// Clamp the sibling window so it always spans the same number of pages,
+	// sliding it inward when the current page sits near either boundary.
+	const siblingStart = Math.max(
+		Math.min(
+			page - siblingCount,
+			pageCount - boundaryCount - 2 * siblingCount - 2,
+		),
+		boundaryCount + 1,
+	);
+	const siblingEnd = siblingStart + 2 * siblingCount;
+
+	return [
+		...startBoundary,
+		siblingStart > boundaryCount + 1 ? PAGINATION_ELLIPSIS : boundaryCount,
+		...range(siblingStart, siblingEnd),
+		siblingEnd < pageCount - boundaryCount - 2
+			? PAGINATION_ELLIPSIS
+			: pageCount - boundaryCount - 1,
+		...endBoundary,
+	];
+}
+
+/** Memoized `getPaginationRange` for render-time use. */
+export function usePagination({
+	page,
+	pageCount,
+	siblingCount = 1,
+	boundaryCount = 1,
+}: PaginationRangeOptions): PaginationRangeItem[] {
+	return React.useMemo(
+		() => getPaginationRange({ page, pageCount, siblingCount, boundaryCount }),
+		[page, pageCount, siblingCount, boundaryCount],
+	);
+}

package/src/hooks/use-picker-state.ts

@@ -0,0 +1,44 @@
+import * as React from "react";
+
+/**
+ * The controlled/uncontrolled plumbing shared by every popover picker
+ * (date, date range, date-time, time): an optionally controlled value —
+ * `undefined` means uncontrolled, `null` a controlled empty selection — and an
+ * optionally controlled open state whose setter always notifies `onOpenChange`.
+ */
+export function usePickerState<Value>({
+	value: controlledValue,
+	defaultValue,
+	open: controlledOpen,
+	defaultOpen,
+	onOpenChange,
+}: {
+	value?: Value | null;
+	defaultValue?: Value;
+	open?: boolean;
+	defaultOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+}): {
+	isControlled: boolean;
+	value: Value | null | undefined;
+	setUncontrolledValue: (value: Value | undefined) => void;
+	open: boolean;
+	setOpen: (open: boolean) => void;
+} {
+	const isControlled = controlledValue !== undefined;
+	const [uncontrolledValue, setUncontrolledValue] = React.useState<
+		Value | undefined
+	>(defaultValue);
+	const value = isControlled ? controlledValue : uncontrolledValue;
+
+	const [uncontrolledOpen, setUncontrolledOpen] = React.useState(
+		defaultOpen ?? false,
+	);
+	const open = controlledOpen ?? uncontrolledOpen;
+	const setOpen = (next: boolean) => {
+		setUncontrolledOpen(next);
+		onOpenChange?.(next);
+	};
+
+	return { isControlled, value, setUncontrolledValue, open, setOpen };
+}

package/src/lib/cva.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "cva";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Project-wide `cva` (the class-variance-authority successor, v1 beta),
+ * configured to run every generated class string through `tailwind-merge`. This
+ * is the single source of variant styling for both the app and the marketing
+ * site - always import `cva`/`cx`/`compose` from here (or `@voila.dev/ui/cva`),
+ * never from the raw `cva` package, so conflicting Tailwind utilities resolve
+ * consistently everywhere.
+ */
+export const { cva, cx, compose } = defineConfig({
+	hooks: {
+		onComplete: (className) => twMerge(className),
+	},
+});
+
+export type { VariantProps } from "cva";

package/src/lib/time-math.ts

@@ -0,0 +1,62 @@
+/**
+ * Minute-of-day arithmetic shared by the time pickers (`time-picker.tsx`,
+ * `date-time-picker.tsx`), which both model a time as minutes since midnight.
+ */
+
+/** Time-of-day formatting: short localized time (e.g. "2:30 PM" / "14:30"). */
+const DEFAULT_TIME_FORMAT: Intl.DateTimeFormatOptions = {
+	hour: "numeric",
+	minute: "2-digit",
+};
+
+/** Parse an "HH:mm" string to minutes since midnight (null when malformed). */
+export function parseTimeToMinutes(
+	time: string | null | undefined,
+): number | null {
+	if (!time) return null;
+	const match = /^(\d{1,2}):(\d{2})$/.exec(time);
+	if (!match) return null;
+	const hours = Number(match[1]);
+	const minutes = Number(match[2]);
+	if (hours > 23 || minutes > 59) return null;
+	return hours * 60 + minutes;
+}
+
+/** Serialize minutes since midnight back to a zero-padded "HH:mm" string. */
+export function minutesToTimeValue(totalMinutes: number): string {
+	const hours = Math.floor(totalMinutes / 60);
+	const minutes = totalMinutes % 60;
+	return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}
+
+/** Minutes since midnight of a `Date`'s local time-of-day. */
+export function minutesOfDay(date: Date): number {
+	return date.getHours() * 60 + date.getMinutes();
+}
+
+/** A copy of `date` with the time-of-day set to `totalMinutes` (seconds/ms zeroed). */
+export function withMinutes(date: Date, totalMinutes: number): Date {
+	const next = new Date(date);
+	next.setHours(Math.floor(totalMinutes / 60), totalMinutes % 60, 0, 0);
+	return next;
+}
+
+/**
+ * Localized label for a minute-of-day via the native `Intl.DateTimeFormat`, so
+ * AM/PM vs 24-hour follows the given BCP-47 locale (e.g. "2:30 PM" for `en-US`,
+ * "14:30" for `fr-FR`). `locale` undefined falls back to the runtime default.
+ */
+export function formatMinutesLabel(
+	totalMinutes: number,
+	locale: string | undefined,
+	options: Intl.DateTimeFormatOptions = DEFAULT_TIME_FORMAT,
+): string {
+	const date = new Date(
+		2000,
+		0,
+		1,
+		Math.floor(totalMinutes / 60),
+		totalMinutes % 60,
+	);
+	return new Intl.DateTimeFormat(locale, options).format(date);
+}

package/src/lib/utils.ts

@@ -0,0 +1,14 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}
+
+/**
+ * Inline-link affordance shared by the kit's long-form text containers
+ * (Alert title/description, Accordion content) so links read the same
+ * everywhere.
+ */
+export const proseLinkClassName =
+	"[&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground";

package/src/styles/globals.css

@@ -0,0 +1,36 @@
+@import "tailwindcss";
+@import "../styles.css";
+@import "tw-animate-css";
+@import "@voila.dev/ui-tokens/design-tokens.css";
+
+@layer base {
+	* {
+		@apply border-border outline-ring/50;
+	}
+	body {
+		@apply bg-background text-foreground;
+	}
+}
+
+/* Indeterminate progress: a half-width bar sweeping across the track. */
+@theme {
+	--animate-progress-indeterminate: progress-indeterminate 1.5s ease-in-out
+		infinite;
+
+	@keyframes progress-indeterminate {
+		from {
+			translate: -100% 0;
+		}
+		to {
+			translate: 200% 0;
+		}
+	}
+}
+
+/* Scrollable regions that hide their scrollbar (sidebar, command, combobox). */
+@utility no-scrollbar {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}

package/src/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind must scan this package or none of its classes are generated — the
+ * components ship as .tsx source, not as compiled CSS.
+ *
+ * `@source` resolves relative to the file that declares it, so this works
+ * wherever the package ends up: node_modules in an app, a symlink in a
+ * workspace. Consumers import this file and add nothing of their own.
+ */
+@source "./";
+@source not "./**/*.test.*";