@hoardodile/ui 0.0.0

package/src/components/tooltip.tsx

@@ -0,0 +1,64 @@
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+
+import { cn } from "@hoardodile/ui/lib/utils"
+
+function TooltipProvider({
+  delay = 0,
+  ...props
+}: TooltipPrimitive.Provider.Props) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delay={delay}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  side = "top",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  children,
+  ...props
+}: TooltipPrimitive.Popup.Props &
+  Pick<
+    TooltipPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <TooltipPrimitive.Popup
+          data-slot="tooltip-content"
+          className={cn(
+            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 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-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 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}
+        >
+          {children}
+          <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

package/src/hooks/use-dialog-footer-actions.ts

@@ -0,0 +1,23 @@
+import { createContext, type ReactNode, useContext } from "react"
+
+/**
+ * Footer action slot plumbing for `AppDialog` — the context shared
+ * between the dialog shell (`@hoardodile/ui/components/app-dialog`) and
+ * body panels that contribute their primary action through
+ * `DialogFooterActions`, so action buttons land in the footer instead of
+ * the body.
+ */
+
+type DialogFooterActionsValue = {
+	readonly setFooterActions: (node: ReactNode | null) => void
+}
+
+const DialogFooterActionsContext =
+	createContext<DialogFooterActionsValue | null>(null)
+
+/** The nearest dialog's footer action slot, or null outside a dialog. */
+function useDialogFooterActions(): DialogFooterActionsValue | null {
+	return useContext(DialogFooterActionsContext)
+}
+
+export { DialogFooterActionsContext, useDialogFooterActions }

package/src/hooks/use-form-field.ts

@@ -0,0 +1,62 @@
+import * as React from "react"
+import {
+	type FieldPath,
+	type FieldValues,
+	useFormContext,
+	useFormState,
+} from "react-hook-form"
+
+/**
+ * Field-state plumbing shared by the `Form*` components in
+ * `@hoardodile/ui/components/form`: connects a `<FormField>` (the
+ * react-hook-form `Controller` wrapper) to its `<FormItem>` via two
+ * private contexts and exposes the resolved field state — id parts and
+ * error — to the label/control/description/message render pieces.
+ */
+
+type FormFieldContextValue<
+	TFieldValues extends FieldValues = FieldValues,
+	TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> = {
+	name: TName
+}
+
+const FormFieldContext = React.createContext<FormFieldContextValue | undefined>(
+	undefined,
+)
+
+type FormItemContextValue = {
+	id: string
+}
+
+const FormItemContext = React.createContext<FormItemContextValue | undefined>(
+	undefined,
+)
+
+function useFormField() {
+	const fieldContext = React.useContext(FormFieldContext)
+	const itemContext = React.useContext(FormItemContext)
+	const { getFieldState } = useFormContext()
+	const formState = useFormState({ name: fieldContext?.name })
+
+	if (!fieldContext) {
+		throw new Error("useFormField should be used within <FormField>")
+	}
+	if (!itemContext) {
+		throw new Error("useFormField should be used within <FormItem>")
+	}
+
+	const fieldState = getFieldState(fieldContext.name, formState)
+	const { id } = itemContext
+
+	return {
+		id,
+		name: fieldContext.name,
+		formItemId: `${id}-form-item`,
+		formDescriptionId: `${id}-form-item-description`,
+		formMessageId: `${id}-form-item-message`,
+		...fieldState,
+	}
+}
+
+export { FormFieldContext, FormItemContext, useFormField }

package/src/hooks/use-mobile.ts

@@ -0,0 +1,54 @@
+import {
+	MOBILE_QUERY,
+	PANEL_QUERY,
+	SIDEBAR_QUERY,
+} from "@hoardodile/ui/viewport"
+import { useMedia } from "react-use"
+
+/**
+ * One-shot check for viewports below the `md` breakpoint (< 768 px).
+ *
+ * Prefer {@link useBelowMd} in React components so they re-render when the
+ * viewport crosses the breakpoint. Use this helper only in event handlers,
+ * utility functions, or effects where a reactive hook is not appropriate.
+ */
+export function isBelowMd(): boolean {
+	if (typeof window === "undefined") return false
+	return window.matchMedia(MOBILE_QUERY).matches
+}
+
+export function useBelowMd(): boolean {
+	return useMedia(MOBILE_QUERY, false)
+}
+
+/**
+ * Reactive check for viewports below the app-shell sidebar breakpoint
+ * (`max-sidebar`), where the fixed sidebar is replaced by the hamburger
+ * drawer. Keep in sync with `SIDEBAR_BREAKPOINT_PX` and the
+ * `sidebar:` / `max-sidebar:` CSS variants. The shell alone decides its own chrome;
+ * compact-UI consumers keep using {@link useBelowMd}.
+ */
+export function useBelowSidebar(): boolean {
+	return useMedia(SIDEBAR_QUERY, false)
+}
+
+/**
+ * Reactive check for viewports below the filter-rail breakpoint
+ * (< 1440 px), where the rail becomes a drawer instead of a fixed right
+ * column. Keep in sync with `PANEL_BREAKPOINT_PX` and the
+ * `panel:` / `max-panel:` CSS variants.
+ */
+export function useBelowPanel(): boolean {
+	return useMedia(PANEL_QUERY, false)
+}
+
+/**
+ * Compatibility alias for official shadcn-generated components (e.g.
+ * `sidebar.tsx`), which import `useIsMobile` from this module. Mobile
+ * detection rules are owned by THIS file for the whole repo (apps and
+ * plugins alike) — never let the registry version of `use-mobile.ts`
+ * replace it; restore after every `shadcn add`.
+ */
+export function useIsMobile(): boolean {
+	return useBelowMd()
+}

package/src/hooks/use-pinch-pan.test.tsx

@@ -0,0 +1,42 @@
+// @vitest-environment node
+import { describe, expect, test } from "vitest"
+import {
+	clampViewportScale,
+	isTapGesture,
+	panViewport,
+	type ViewportTransform,
+	zoomViewportAt,
+} from "./use-pinch-pan"
+
+const RANGE = { minScale: 0.5, maxScale: 4 }
+
+describe("viewport transform math", () => {
+	test("clamps zoom into the viewer range", () => {
+		expect(clampViewportScale(8, RANGE)).toBe(4)
+		expect(clampViewportScale(0.1, RANGE)).toBe(0.5)
+		expect(clampViewportScale(1.5, RANGE)).toBe(1.5)
+	})
+
+	test("pans by screen-space pixels", () => {
+		const start: ViewportTransform = { x: 10, y: -4, scale: 2 }
+		expect(panViewport(start, { x: 5, y: 7 })).toEqual({
+			x: 15,
+			y: 3,
+			scale: 2,
+		})
+	})
+
+	test("zooms while keeping the anchor point fixed", () => {
+		const start: ViewportTransform = { x: 10, y: 20, scale: 1 }
+		expect(zoomViewportAt(start, { x: 40, y: -10 }, 2, RANGE)).toEqual({
+			x: -30,
+			y: 30,
+			scale: 2,
+		})
+	})
+
+	test("a move within the threshold is a tap", () => {
+		expect(isTapGesture({ x: 0, y: 0 }, { x: 5, y: 5 }, 8)).toBe(true)
+		expect(isTapGesture({ x: 0, y: 0 }, { x: 8, y: 0 }, 8)).toBe(false)
+	})
+})

package/src/hooks/use-pinch-pan.ts

@@ -0,0 +1,340 @@
+import { type RefObject, useEffect, useRef, useState } from "react"
+
+/**
+ * Shared pinch/pan viewport gesture for media viewers. One finger pans,
+ * two fingers zoom around their midpoint, a quick tap reports a click,
+ * and a second quick tap reports a double tap. The transform is
+ * `translate(x, y) scale(scale)` with the target's center as origin.
+ */
+
+export type ViewportTransform = {
+	readonly x: number
+	readonly y: number
+	readonly scale: number
+}
+
+export type ViewportPoint = {
+	readonly x: number
+	readonly y: number
+}
+
+export type PinchPanOptions = {
+	readonly target: RefObject<HTMLElement | null>
+	readonly initial?: ViewportTransform
+	readonly minScale?: number
+	readonly maxScale?: number
+	/** Max travel for a tap before it becomes a drag, in CSS pixels. */
+	readonly tapThreshold?: number
+	/** When this value changes, the viewport returns to `initial`. */
+	readonly resetKey?: string | number
+	readonly onChange?: (next: ViewportTransform) => void
+	readonly onTap?: (point: ViewportPoint) => void
+	readonly onDoubleTap?: (point: ViewportPoint) => void
+}
+
+const DEFAULT_TRANSFORM: ViewportTransform = { x: 0, y: 0, scale: 1 }
+
+type ActivePointer = {
+	readonly id: number
+	readonly x: number
+	readonly y: number
+	readonly startX: number
+	readonly startY: number
+}
+
+type GestureSession = {
+	readonly pointers: ReadonlyMap<number, ActivePointer>
+	readonly start: ViewportTransform
+	readonly startDistance: number
+	readonly startMidpoint: ViewportPoint
+	moved: boolean
+}
+
+/**
+ * Clamp a scale into the viewer's zoom range. Pure so tests can hold the
+ * same arithmetic the DOM hook uses.
+ */
+export function clampViewportScale(
+	scale: number,
+	options: { readonly minScale: number; readonly maxScale: number },
+): number {
+	return Math.max(options.minScale, Math.min(options.maxScale, scale))
+}
+
+/** Pan a transform by screen-space pixels. */
+export function panViewport(
+	transform: ViewportTransform,
+	delta: ViewportPoint,
+): ViewportTransform {
+	return { ...transform, x: transform.x + delta.x, y: transform.y + delta.y }
+}
+
+/**
+ * Zoom `transform` to `nextScale` while keeping the content under
+ * `anchor` (relative to the transform origin) visually fixed.
+ */
+export function zoomViewportAt(
+	transform: ViewportTransform,
+	anchor: ViewportPoint,
+	nextScale: number,
+	options: { readonly minScale: number; readonly maxScale: number },
+): ViewportTransform {
+	const scale = clampViewportScale(nextScale, options)
+	const scaleDelta = scale - transform.scale
+	return {
+		scale,
+		x: transform.x - anchor.x * scaleDelta,
+		y: transform.y - anchor.y * scaleDelta,
+	}
+}
+
+/** True when a press counts as a tap rather than a drag. */
+export function isTapGesture(
+	start: ViewportPoint,
+	end: ViewportPoint,
+	tapThreshold: number,
+): boolean {
+	return Math.hypot(end.x - start.x, end.y - start.y) < tapThreshold
+}
+
+export function usePinchPan(options: PinchPanOptions): {
+	readonly transform: ViewportTransform
+	readonly reset: () => void
+} {
+	const {
+		target,
+		initial = DEFAULT_TRANSFORM,
+		minScale = 0.5,
+		maxScale = 4,
+		tapThreshold = 8,
+		resetKey,
+		onChange,
+		onTap,
+		onDoubleTap,
+	} = options
+	const [transform, setTransform] = useState<ViewportTransform>(initial)
+	const initialRef = useRef(initial)
+	initialRef.current = initial
+	const transformRef = useRef(transform)
+	transformRef.current = transform
+	const sessionRef = useRef<GestureSession | null>(null)
+	const lastTapRef = useRef<{
+		readonly point: ViewportPoint
+		readonly time: number
+	} | null>(null)
+	const boundsRef = useRef({ minScale, maxScale, tapThreshold })
+	boundsRef.current = { minScale, maxScale, tapThreshold }
+
+	function update(next: ViewportTransform) {
+		setTransform(next)
+		onChange?.(next)
+	}
+
+	function reset() {
+		update({ ...DEFAULT_TRANSFORM })
+	}
+
+	useEffect(() => {
+		if (resetKey === undefined) return
+		update({ ...initialRef.current })
+	}, [resetKey])
+
+	useEffect(() => {
+		const currentTarget = target.current
+		if (currentTarget === null) return
+		const element: HTMLElement = currentTarget
+
+		function startPointer(event: PointerEvent): void {
+			const current = transformRef.current
+			const session = sessionRef.current
+			if (session === null) {
+				sessionRef.current = {
+					pointers: new Map([[event.pointerId, activePointer(event)]]),
+					start: current,
+					startDistance: 0,
+					startMidpoint: eventPoint(event),
+					moved: false,
+				}
+				element.setPointerCapture(event.pointerId)
+				return
+			}
+			const pointers = new Map(session.pointers)
+			pointers.set(event.pointerId, activePointer(event))
+			const entries = [...pointers.values()]
+			if (entries.length >= 2) {
+				const first = entries[0]
+				const second = entries[1]
+				if (first !== undefined && second !== undefined) {
+					sessionRef.current = {
+						pointers,
+						start: current,
+						startDistance: distance(first, second),
+						startMidpoint: midpoint(first, second),
+						moved: session.moved,
+					}
+				}
+			}
+			element.setPointerCapture(event.pointerId)
+		}
+
+		function movePointer(event: PointerEvent): void {
+			const session = sessionRef.current
+			if (session === null) return
+			const pointers = new Map(session.pointers)
+			pointers.set(
+				event.pointerId,
+				activePointer(event, session.pointers.get(event.pointerId)),
+			)
+			const entries = [...pointers.values()]
+			if (entries.length === 0) return
+
+			if (entries.length === 1) {
+				const pointer = entries[0]
+				if (pointer === undefined) return
+				const delta = {
+					x: pointer.x - pointer.startX,
+					y: pointer.y - pointer.startY,
+				}
+				if (
+					!isTapGesture(
+						session.startMidpoint,
+						pointer,
+						boundsRef.current.tapThreshold,
+					)
+				) {
+					session.moved = true
+				}
+				sessionRef.current = {
+					...session,
+					pointers,
+					moved:
+						session.moved ||
+						movedBeyondTap(pointer, boundsRef.current.tapThreshold),
+				}
+				update(panViewport(session.start, delta))
+				return
+			}
+
+			const first = entries[0]
+			const second = entries[1]
+			if (first === undefined || second === undefined) return
+			const nextDistance = Math.max(1, distance(first, second))
+			const ratio = nextDistance / Math.max(1, session.startDistance)
+			const nextMidpoint = midpoint(first, second)
+			const centerMidpoint = relativeMidpoint(element, nextMidpoint)
+			const next = zoomViewportAt(
+				session.start,
+				centerMidpoint,
+				session.start.scale * ratio,
+				{
+					minScale: boundsRef.current.minScale,
+					maxScale: boundsRef.current.maxScale,
+				},
+			)
+			sessionRef.current = { ...session, pointers, moved: true }
+			update(next)
+		}
+
+		function endPointer(event: PointerEvent): void {
+			const session = sessionRef.current
+			if (session === null) return
+			const pointers = new Map(session.pointers)
+			pointers.delete(event.pointerId)
+			if (pointers.size > 0) {
+				sessionRef.current = { ...session, pointers }
+				return
+			}
+			sessionRef.current = null
+			if (!session.moved && session.pointers.size === 1) {
+				const point = eventPoint(event)
+				handleTap(point)
+			}
+		}
+
+		function cancelPointer(event: PointerEvent): void {
+			const session = sessionRef.current
+			if (session === null) return
+			const pointers = new Map(session.pointers)
+			pointers.delete(event.pointerId)
+			sessionRef.current = pointers.size > 0 ? { ...session, pointers } : null
+		}
+
+		function handleTap(point: ViewportPoint): void {
+			onTap?.(point)
+			const now = performance.now()
+			const last = lastTapRef.current
+			lastTapRef.current = { point, time: now }
+			if (
+				last !== null &&
+				now - last.time < 300 &&
+				Math.hypot(point.x - last.point.x, point.y - last.point.y) < 30
+			) {
+				lastTapRef.current = null
+				onDoubleTap?.(point)
+			}
+		}
+
+		element.addEventListener("pointerdown", startPointer)
+		element.addEventListener("pointermove", movePointer)
+		element.addEventListener("pointerup", endPointer)
+		element.addEventListener("pointercancel", cancelPointer)
+		return () => {
+			element.removeEventListener("pointerdown", startPointer)
+			element.removeEventListener("pointermove", movePointer)
+			element.removeEventListener("pointerup", endPointer)
+			element.removeEventListener("pointercancel", cancelPointer)
+		}
+	}, [target, onTap, onDoubleTap, onChange])
+
+	return { transform, reset }
+}
+
+function activePointer(
+	event: PointerEvent,
+	start?: ActivePointer | ViewportPoint,
+): ActivePointer {
+	const origin = start ?? eventPoint(event)
+	return {
+		id: event.pointerId,
+		x: event.clientX,
+		y: event.clientY,
+		startX: origin.x,
+		startY: origin.y,
+	}
+}
+
+function eventPoint(event: {
+	readonly clientX: number
+	readonly clientY: number
+}): ViewportPoint {
+	return { x: event.clientX, y: event.clientY }
+}
+
+function distance(a: ViewportPoint, b: ViewportPoint): number {
+	return Math.hypot(a.x - b.x, a.y - b.y)
+}
+
+function midpoint(a: ViewportPoint, b: ViewportPoint): ViewportPoint {
+	return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }
+}
+
+function movedBeyondTap(pointer: ActivePointer, tapThreshold: number): boolean {
+	return (
+		isTapGesture(
+			{ x: pointer.startX, y: pointer.startY },
+			{ x: pointer.x, y: pointer.y },
+			tapThreshold,
+		) === false
+	)
+}
+
+function relativeMidpoint(
+	element: HTMLElement,
+	point: ViewportPoint,
+): ViewportPoint {
+	const rect = element.getBoundingClientRect()
+	return {
+		x: point.x - (rect.left + rect.width / 2),
+		y: point.y - (rect.top + rect.height / 2),
+	}
+}