@effect-tui/react 0.12.3 → 0.13.0

package/src/hooks/use-scroll.ts

@@ -2,6 +2,7 @@
 
 import type { KeyMsg } from "@effect-tui/core"
 import { useCallback, useLayoutEffect, useMemo, useReducer, useRef } from "react"
+import type { ScrollProps } from "../hosts/scroll.js"
 import { useTerminalSize } from "../renderer.js"
 import { useKeyboard } from "./use-keyboard.js"
 
@@ -85,33 +86,65 @@ class MacOSScrollAccel implements ScrollAcceleration {
 // ============================================================================
 
 export interface ScrollState {
-	/** Current scroll offset (pixels from start) */
+	/** Current scroll offset (pixels from start) for the primary axis */
 	offset: number
-	/** Maximum scroll offset */
+	/** Maximum scroll offset for the primary axis */
 	maxOffset: number
-	/** Viewport height (or width for horizontal) */
+	/** Viewport size for the primary axis */
 	viewportSize: number
-	/** Whether viewport size has been measured by the host */
+	/** Whether viewport size has been measured by the host (primary axis) */
 	viewportMeasured: boolean
-	/** Total content size */
+	/** Total content size for the primary axis */
 	contentSize: number
-	/** Whether we're at the start edge */
+	/** Whether we're at the start edge (primary axis) */
 	atStart: boolean
-	/** Whether we're at the end edge */
+	/** Whether we're at the end edge (primary axis) */
 	atEnd: boolean
+	/** Current horizontal offset (pixels from start) */
+	offsetX: number
+	/** Maximum horizontal offset */
+	maxOffsetX: number
+	/** Horizontal viewport size */
+	viewportSizeX: number
+	/** Whether horizontal viewport size has been measured */
+	viewportMeasuredX: boolean
+	/** Total horizontal content size */
+	contentSizeX: number
+	/** Whether we're at the horizontal start edge */
+	atStartX: boolean
+	/** Whether we're at the horizontal end edge */
+	atEndX: boolean
 }
 
 export interface UseScrollOptions {
-	/** Scroll axis: "vertical" (default) or "horizontal" */
-	axis?: "vertical" | "horizontal"
-	/** Controlled content size (skips host measurement when provided) */
+	/** Scroll axis: "vertical" (default), "horizontal", or "both" */
+	axis?: "vertical" | "horizontal" | "both"
+	/** Controlled content size for the primary axis (skips host measurement when provided) */
 	contentSize?: number
+	/** Controlled content width (skips host measurement when provided) */
+	contentWidth?: number
+	/** Controlled content height (skips host measurement when provided) */
+	contentHeight?: number
 	/** @internal Initial viewport size override (useful for tests) */
 	initialViewportSize?: number
+	/** @internal Initial viewport width override (useful for tests) */
+	initialViewportWidth?: number
+	/** @internal Initial viewport height override (useful for tests) */
+	initialViewportHeight?: number
 	/** @internal Initial content size override (useful for tests) */
 	initialContentSize?: number
-	/** Initial scroll offset */
+	/** @internal Initial content width override (useful for tests) */
+	initialContentWidth?: number
+	/** @internal Initial content height override (useful for tests) */
+	initialContentHeight?: number
+	/** Initial scroll offset for the primary axis */
 	initialOffset?: number
+	/** Initial horizontal scroll offset */
+	initialOffsetX?: number
+	/** Alignment when content is smaller than viewport */
+	align?: "start" | "end"
+	/** Whether to show scrollbars */
+	showScrollbar?: boolean
 	/** Enable keyboard navigation (default: true) */
 	enableKeyboard?: boolean
 	/** Enable mouse wheel (default: true) */
@@ -129,14 +162,22 @@ export interface UseScrollOptions {
 export interface UseScrollReturn {
 	/** Current scroll state */
 	state: ScrollState
-	/** Set scroll offset directly */
+	/** Set scroll offset directly (primary axis) */
 	setOffset: (offset: number) => void
-	/** Scroll by delta pixels */
+	/** Set horizontal scroll offset directly */
+	setOffsetX: (offsetX: number) => void
+	/** Scroll by delta pixels (primary axis) */
 	scrollBy: (delta: number) => void
-	/** Scroll to start */
+	/** Scroll by delta pixels horizontally */
+	scrollByX: (delta: number) => void
+	/** Scroll to start (primary axis) */
 	scrollToStart: () => void
-	/** Scroll to end */
+	/** Scroll to end (primary axis) */
 	scrollToEnd: () => void
+	/** Scroll to horizontal start */
+	scrollToStartX: () => void
+	/** Scroll to horizontal end */
+	scrollToEndX: () => void
 	/**
 	 * Scroll to make a position visible in the viewport.
 	 * Useful for keeping a selected item in view.
@@ -144,17 +185,17 @@ export interface UseScrollReturn {
 	 * @param itemSize - Size of each item (default: 1 for row-based lists)
 	 * @param padding - Extra padding around the item (default: 0)
 	 * @param totalSize - Optional known total content size (avoids stale state issues)
+	 * @param axis - Axis to scroll (defaults to vertical)
 	 */
-	scrollToVisible: (position: number, itemSize?: number, padding?: number, totalSize?: number) => void
+	scrollToVisible: (
+		position: number,
+		itemSize?: number,
+		padding?: number,
+		totalSize?: number,
+		axis?: "vertical" | "horizontal",
+	) => void
 	/** Props to spread on <scroll> element */
-	scrollProps: {
-		offset: number
-		axis: "vertical" | "horizontal"
-		onContentSize: (width: number, height: number) => void
-		onViewportSize: (width: number, height: number) => void
-		onEffectiveOffset?: (offset: number) => void
-		onRect?: (x: number, y: number, w: number, h: number) => void
-	}
+	scrollProps: ScrollProps
 }
 
 type ScrollInternalState = {
@@ -246,10 +287,19 @@ const reduceScroll = (state: ScrollInternalState, action: ScrollAction): ScrollI
 export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	const {
 		axis = "vertical",
-		contentSize: controlledContentSize,
+		contentSize,
+		contentWidth,
+		contentHeight,
 		initialViewportSize,
+		initialViewportWidth,
+		initialViewportHeight,
 		initialContentSize,
+		initialContentWidth,
+		initialContentHeight,
 		initialOffset = 0,
+		initialOffsetX = 0,
+		align = "start",
+		showScrollbar = true,
 		enableKeyboard = true,
 		enableMouseWheel = true,
 		enableAcceleration = true,
@@ -259,85 +309,186 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	} = options
 
 	const { width: termWidth, height: termHeight } = useTerminalSize()
-	const baseViewportSize = initialViewportSize ?? (axis === "vertical" ? termHeight : termWidth)
-	const baseContentSize = controlledContentSize ?? initialContentSize ?? 0
-
-	const [internal, dispatch] = useReducer(reduceScroll, {
-		offset: clampOffset(initialOffset, baseContentSize, baseViewportSize),
-		contentSize: baseContentSize,
-		viewportSize: baseViewportSize,
+	const enableY = axis === "vertical" || axis === "both"
+	const enableX = axis === "horizontal" || axis === "both"
+	const primaryAxis: "vertical" | "horizontal" = axis === "horizontal" ? "horizontal" : "vertical"
+
+	const controlledContentHeight = contentHeight ?? (axis !== "horizontal" ? contentSize : undefined)
+	const controlledContentWidth = contentWidth ?? (axis === "horizontal" ? contentSize : undefined)
+
+	const baseViewportHeight =
+		initialViewportHeight ?? (axis !== "horizontal" ? initialViewportSize : undefined) ?? termHeight
+	const baseViewportWidth =
+		initialViewportWidth ?? (axis === "horizontal" ? initialViewportSize : undefined) ?? termWidth
+
+	const baseContentHeight =
+		controlledContentHeight ?? initialContentHeight ?? (axis !== "horizontal" ? initialContentSize : undefined) ?? 0
+	const baseContentWidth =
+		controlledContentWidth ?? initialContentWidth ?? (axis === "horizontal" ? initialContentSize : undefined) ?? 0
+
+	const initialOffsetY = axis === "horizontal" ? 0 : initialOffset
+	const initialOffsetXResolved = axis === "horizontal" ? initialOffset : initialOffsetX
+
+	const [internalY, dispatchY] = useReducer(reduceScroll, {
+		offset: clampOffset(initialOffsetY, baseContentHeight, baseViewportHeight),
+		contentSize: baseContentHeight,
+		viewportSize: baseViewportHeight,
 		viewportMeasured: false,
 		sticky,
 	})
-	const stateRef = useRef(internal)
-	stateRef.current = internal
-	const viewportSizeRef = useRef(baseViewportSize)
+	const [internalX, dispatchX] = useReducer(reduceScroll, {
+		offset: clampOffset(initialOffsetXResolved, baseContentWidth, baseViewportWidth),
+		contentSize: baseContentWidth,
+		viewportSize: baseViewportWidth,
+		viewportMeasured: false,
+		sticky,
+	})
+	const stateYRef = useRef(internalY)
+	const stateXRef = useRef(internalX)
+	stateYRef.current = internalY
+	stateXRef.current = internalX
+	const viewportYRef = useRef(baseViewportHeight)
+	const viewportXRef = useRef(baseViewportWidth)
 
 	// Scroll acceleration
-	const accel = useMemo(
+	const accelY = useMemo<ScrollAcceleration>(
+		() => (enableAcceleration ? new MacOSScrollAccel() : { tick: () => 1, reset: () => {} }),
+		[enableAcceleration],
+	)
+	const accelX = useMemo<ScrollAcceleration>(
 		() => (enableAcceleration ? new MacOSScrollAccel() : { tick: () => 1, reset: () => {} }),
 		[enableAcceleration],
 	)
 
 	// Fractional accumulator for smooth sub-pixel scrolling
-	const accumulatorRef = useRef(0)
+	const accumulatorYRef = useRef(0)
+	const accumulatorXRef = useRef(0)
 
 	// Keep sticky state in sync when options change
 	useLayoutEffect(() => {
-		dispatch({ type: "set-sticky", sticky })
+		dispatchY({ type: "set-sticky", sticky })
+		dispatchX({ type: "set-sticky", sticky })
 	}, [sticky])
 
 	// Scroll by delta with accumulator for fractional scrolling
 	// Uses functional state updates to avoid stale closures during rapid scrolling
-	const scrollBy = useCallback(
+	const scrollByY = useCallback(
+		(delta: number) => {
+			if (!enableY) return
+			accumulatorYRef.current += delta
+			const integerDelta = Math.trunc(accumulatorYRef.current)
+			if (integerDelta !== 0) {
+				dispatchY({ type: "scroll-by", delta: integerDelta })
+				accumulatorYRef.current -= integerDelta
+			}
+		},
+		[dispatchY, enableY],
+	)
+
+	const scrollByX = useCallback(
 		(delta: number) => {
-			accumulatorRef.current += delta
-			const integerDelta = Math.trunc(accumulatorRef.current)
+			if (!enableX) return
+			accumulatorXRef.current += delta
+			const integerDelta = Math.trunc(accumulatorXRef.current)
 			if (integerDelta !== 0) {
-				dispatch({ type: "scroll-by", delta: integerDelta })
-				accumulatorRef.current -= integerDelta
+				dispatchX({ type: "scroll-by", delta: integerDelta })
+				accumulatorXRef.current -= integerDelta
 			}
 		},
-		[dispatch],
+		[dispatchX, enableX],
 	)
 
+	const scrollBy = useCallback(
+		(delta: number) => {
+			if (primaryAxis === "horizontal") {
+				scrollByX(delta)
+			} else {
+				scrollByY(delta)
+			}
+		},
+		[primaryAxis, scrollByX, scrollByY],
+	)
+
+	const scrollToStartY = useCallback(() => {
+		dispatchY({ type: "set-offset", offset: 0 })
+		accumulatorYRef.current = 0
+		accelY.reset()
+	}, [dispatchY, accelY])
+
+	const scrollToStartX = useCallback(() => {
+		dispatchX({ type: "set-offset", offset: 0 })
+		accumulatorXRef.current = 0
+		accelX.reset()
+	}, [dispatchX, accelX])
+
 	const scrollToStart = useCallback(() => {
-		dispatch({ type: "set-offset", offset: 0 })
-		accumulatorRef.current = 0
-		accel.reset()
-	}, [dispatch, accel])
+		if (primaryAxis === "horizontal") {
+			scrollToStartX()
+		} else {
+			scrollToStartY()
+		}
+	}, [primaryAxis, scrollToStartX, scrollToStartY])
 
-	const scrollToEnd = useCallback(() => {
-		const current = stateRef.current
+	const scrollToEndY = useCallback(() => {
+		const current = stateYRef.current
 		const maxOffset = Math.max(0, current.contentSize - current.viewportSize)
-		dispatch({ type: "set-offset", offset: maxOffset })
-		accumulatorRef.current = 0
-		accel.reset()
-	}, [dispatch, accel])
+		dispatchY({ type: "set-offset", offset: maxOffset })
+		accumulatorYRef.current = 0
+		accelY.reset()
+	}, [dispatchY, accelY])
+
+	const scrollToEndX = useCallback(() => {
+		const current = stateXRef.current
+		const maxOffset = Math.max(0, current.contentSize - current.viewportSize)
+		dispatchX({ type: "set-offset", offset: maxOffset })
+		accumulatorXRef.current = 0
+		accelX.reset()
+	}, [dispatchX, accelX])
+
+	const scrollToEnd = useCallback(() => {
+		if (primaryAxis === "horizontal") {
+			scrollToEndX()
+		} else {
+			scrollToEndY()
+		}
+	}, [primaryAxis, scrollToEndX, scrollToEndY])
 
 	// Handle content size changes (for sticky scroll)
 	const handleContentSize = useCallback(
 		(width: number, height: number) => {
-			if (controlledContentSize !== undefined) return
-			const newSize = axis === "vertical" ? height : width
-			dispatch({ type: "set-content", size: newSize })
+			if (enableY && controlledContentHeight === undefined) {
+				dispatchY({ type: "set-content", size: height })
+			}
+			if (enableX && controlledContentWidth === undefined) {
+				dispatchX({ type: "set-content", size: width })
+			}
 		},
-		[axis, controlledContentSize],
+		[controlledContentHeight, controlledContentWidth, dispatchX, dispatchY, enableX, enableY],
 	)
 
 	useLayoutEffect(() => {
-		if (controlledContentSize === undefined) return
-		dispatch({ type: "set-content", size: controlledContentSize })
-	}, [controlledContentSize])
+		if (!enableY || controlledContentHeight === undefined) return
+		dispatchY({ type: "set-content", size: controlledContentHeight })
+	}, [controlledContentHeight, dispatchY, enableY])
+
+	useLayoutEffect(() => {
+		if (!enableX || controlledContentWidth === undefined) return
+		dispatchX({ type: "set-content", size: controlledContentWidth })
+	}, [controlledContentWidth, dispatchX, enableX])
 
 	// Handle viewport size changes (reported by scroll component)
 	const handleViewportSize = useCallback(
 		(width: number, height: number) => {
-			const newSize = axis === "vertical" ? height : width
-			viewportSizeRef.current = newSize
-			dispatch({ type: "set-viewport", size: newSize })
+			if (enableY) {
+				viewportYRef.current = height
+				dispatchY({ type: "set-viewport", size: height })
+			}
+			if (enableX) {
+				viewportXRef.current = width
+				dispatchX({ type: "set-viewport", size: width })
+			}
 		},
-		[axis, dispatch],
+		[dispatchX, dispatchY, enableX, enableY],
 	)
 
 	// Keyboard handler
@@ -346,36 +497,66 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			// Mouse wheel comes as pageup/pagedown with meta=true
 			// Handle separately from keyboard since enableKeyboard shouldn't disable mouse
 			if (key.meta && enableMouseWheel && (key.name === "pageup" || key.name === "pagedown")) {
-				const multiplier = accel.tick()
+				const multiplier = primaryAxis === "horizontal" && !enableY ? accelX.tick() : accelY.tick()
 				const delta = Math.ceil(arrowSpeed * multiplier)
-				scrollBy(key.name === "pageup" ? -delta : delta)
+				if (axis === "horizontal") {
+					scrollByX(key.name === "pageup" ? -delta : delta)
+				} else {
+					scrollByY(key.name === "pageup" ? -delta : delta)
+				}
 				return
 			}
 
 			if (!enableKeyboard) return
 
-			const isVertical = axis === "vertical"
-			const upKey = isVertical ? "up" : "left"
-			const downKey = isVertical ? "down" : "right"
+			if (axis === "horizontal") {
+				switch (key.name) {
+					case "left":
+						scrollByX(-arrowSpeed)
+						break
+					case "right":
+						scrollByX(arrowSpeed)
+						break
+					case "pageup":
+						scrollByX(-Math.floor(viewportXRef.current * pageSpeed))
+						break
+					case "pagedown":
+						scrollByX(Math.floor(viewportXRef.current * pageSpeed))
+						break
+					case "home":
+						scrollToStartX()
+						break
+					case "end":
+						scrollToEndX()
+						break
+				}
+				return
+			}
 
 			switch (key.name) {
-				case upKey:
-					scrollBy(-arrowSpeed)
+				case "up":
+					scrollByY(-arrowSpeed)
+					break
+				case "down":
+					scrollByY(arrowSpeed)
 					break
-				case downKey:
-					scrollBy(arrowSpeed)
+				case "left":
+					if (axis === "both") scrollByX(-arrowSpeed)
+					break
+				case "right":
+					if (axis === "both") scrollByX(arrowSpeed)
 					break
 				case "pageup":
-					scrollBy(-Math.floor(viewportSizeRef.current * pageSpeed))
+					scrollByY(-Math.floor(viewportYRef.current * pageSpeed))
 					break
 				case "pagedown":
-					scrollBy(Math.floor(viewportSizeRef.current * pageSpeed))
+					scrollByY(Math.floor(viewportYRef.current * pageSpeed))
 					break
 				case "home":
-					scrollToStart()
+					scrollToStartY()
 					break
 				case "end":
-					scrollToEnd()
+					scrollToEndY()
 					break
 			}
 		},
@@ -385,10 +566,16 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			arrowSpeed,
 			pageSpeed,
 			enableMouseWheel,
-			accel,
-			scrollBy,
-			scrollToStart,
-			scrollToEnd,
+			accelX,
+			accelY,
+			enableY,
+			primaryAxis,
+			scrollByX,
+			scrollByY,
+			scrollToEndX,
+			scrollToEndY,
+			scrollToStartX,
+			scrollToStartY,
 		],
 	)
 
@@ -399,10 +586,17 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	// so selection effects can re-run after measurement updates.
 	// Bypasses clampOffset because it uses totalSize for accurate clamping
 	const scrollToVisible = useCallback(
-		(position: number, itemSize = 1, padding = 0, totalSize?: number) => {
-			const current = stateRef.current
+		(
+			position: number,
+			itemSize = 1,
+			padding = 0,
+			totalSize?: number,
+			axisOverride: "vertical" | "horizontal" = "vertical",
+		) => {
+			const useHorizontal = axisOverride === "horizontal"
+			const current = useHorizontal ? stateXRef.current : stateYRef.current
 			const currentOffset = current.offset
-			const currentViewportSize = viewportSizeRef.current
+			const currentViewportSize = useHorizontal ? viewportXRef.current : viewportYRef.current
 			const itemStart = position * itemSize
 			const itemEnd = itemStart + itemSize
 			// Use provided totalSize if available (more accurate than potentially stale contentSize)
@@ -413,59 +607,105 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			// If item is above viewport, scroll up to show it
 			if (isAbove) {
 				const newOffset = Math.max(0, itemStart - padding)
-				dispatch({ type: "set-offset", offset: newOffset })
+				;(useHorizontal ? dispatchX : dispatchY)({ type: "set-offset", offset: newOffset })
 			}
 			// If item is below viewport, scroll down to show it
 			else if (isBelow) {
 				const currentMaxOffset = Math.max(0, effectiveContentSize - currentViewportSize)
 				const newOffset = Math.min(currentMaxOffset, itemEnd - currentViewportSize + padding)
-				dispatch({ type: "set-offset", offset: newOffset })
+				;(useHorizontal ? dispatchX : dispatchY)({ type: "set-offset", offset: newOffset })
 			}
 		},
-		[dispatch],
+		[dispatchX, dispatchY],
+	)
+
+	const setOffsetY = useCallback(
+		(newOffset: number) => {
+			dispatchY({ type: "set-offset", offset: newOffset })
+		},
+		[dispatchY],
+	)
+
+	const setOffsetX = useCallback(
+		(newOffset: number) => {
+			dispatchX({ type: "set-offset", offset: newOffset })
+		},
+		[dispatchX],
 	)
 
 	const setOffset = useCallback(
 		(newOffset: number) => {
-			dispatch({ type: "set-offset", offset: newOffset })
+			if (primaryAxis === "horizontal") {
+				setOffsetX(newOffset)
+			} else {
+				setOffsetY(newOffset)
+			}
 		},
-		[dispatch],
+		[primaryAxis, setOffsetX, setOffsetY],
 	)
 
 	// Calculate derived state
-	const maxOffset = Math.max(0, internal.contentSize - internal.viewportSize)
-	const atStart = internal.offset <= 0
-	const atEnd = internal.offset >= maxOffset
+	const maxOffsetY = Math.max(0, internalY.contentSize - internalY.viewportSize)
+	const maxOffsetX = Math.max(0, internalX.contentSize - internalX.viewportSize)
+	const atStartY = internalY.offset <= 0
+	const atEndY = internalY.offset >= maxOffsetY
+	const atStartX = internalX.offset <= 0
+	const atEndX = internalX.offset >= maxOffsetX
+
+	const primaryState = primaryAxis === "horizontal" ? internalX : internalY
+	const primaryMaxOffset = primaryAxis === "horizontal" ? maxOffsetX : maxOffsetY
+	const primaryAtStart = primaryAxis === "horizontal" ? atStartX : atStartY
+	const primaryAtEnd = primaryAxis === "horizontal" ? atEndX : atEndY
 
 	const state: ScrollState = {
-		offset: internal.offset,
-		maxOffset,
-		viewportSize: internal.viewportSize,
-		viewportMeasured: internal.viewportMeasured,
-		contentSize: internal.contentSize,
-		atStart,
-		atEnd,
+		offset: primaryState.offset,
+		maxOffset: primaryMaxOffset,
+		viewportSize: primaryState.viewportSize,
+		viewportMeasured: primaryState.viewportMeasured,
+		contentSize: primaryState.contentSize,
+		atStart: primaryAtStart,
+		atEnd: primaryAtEnd,
+		offsetX: internalX.offset,
+		maxOffsetX,
+		viewportSizeX: internalX.viewportSize,
+		viewportMeasuredX: internalX.viewportMeasured,
+		contentSizeX: internalX.contentSize,
+		atStartX,
+		atEndX,
 	}
 
 	// Handle effective offset sync from host (when sticky adjusts the offset)
 	const handleEffectiveOffset = useCallback((effectiveOffset: number) => {
-		dispatch({ type: "sync-effective-offset", offset: effectiveOffset })
-	}, [dispatch])
+		dispatchY({ type: "sync-effective-offset", offset: effectiveOffset })
+	}, [dispatchY])
+
+	const handleEffectiveOffsetX = useCallback((effectiveOffsetX: number) => {
+		dispatchX({ type: "sync-effective-offset", offset: effectiveOffsetX })
+	}, [dispatchX])
 
-	const scrollProps = {
-		offset: internal.offset,
+	const scrollProps: ScrollProps = {
+		offset: enableY ? internalY.offset : 0,
+		offsetX: enableX ? internalX.offset : 0,
 		axis,
+		align,
+		sticky,
+		showScrollbar,
 		onContentSize: handleContentSize,
 		onViewportSize: handleViewportSize,
-		onEffectiveOffset: handleEffectiveOffset,
+		onEffectiveOffset: enableY ? handleEffectiveOffset : undefined,
+		onEffectiveOffsetX: enableX ? handleEffectiveOffsetX : undefined,
 	}
 
 	return {
 		state,
 		setOffset,
+		setOffsetX,
 		scrollBy,
+		scrollByX,
 		scrollToStart,
 		scrollToEnd,
+		scrollToStartX,
+		scrollToEndX,
 		scrollToVisible,
 		scrollProps,
 	}

package/src/hooks/use-shortcut.ts

@@ -0,0 +1,54 @@
+import type { KeyMsg } from "@effect-tui/core"
+import { useRef } from "react"
+import { isKey, type Shortcut, type ShortcutMatchOptions } from "../shortcuts.js"
+import { useKeyboard } from "./use-keyboard.js"
+
+export type ShortcutHandler = (key: KeyMsg) => void
+
+export type ShortcutMap = Record<string, ShortcutHandler>
+
+export type UseShortcutOptions = {
+	/** Which phase to listen for; defaults to "press" and treats missing phase as "press". */
+	phase?: "press" | "repeat" | "release" | "any"
+	/** Require that unspecified modifiers are not pressed (default: true). */
+	exact?: boolean
+	/**
+	 * If true, call preventDefault when available before invoking handler.
+	 * This stops further renderer-level handlers.
+	 */
+	stopPropagation?: boolean
+}
+
+type ParsedEntry = {
+	shortcut: Shortcut
+	handler: ShortcutHandler
+}
+
+export function useShortcut(shortcuts: ShortcutMap, options: UseShortcutOptions = {}): void {
+	const entriesRef = useRef<ParsedEntry[]>([])
+	const matchOptionsRef = useRef<ShortcutMatchOptions>({ exact: options.exact ?? true })
+	const stopRef = useRef(options.stopPropagation ?? false)
+
+	entriesRef.current = Object.entries(shortcuts).map(([shortcut, handler]) => ({
+		shortcut,
+		handler,
+	}))
+	matchOptionsRef.current = { exact: options.exact ?? true }
+	stopRef.current = options.stopPropagation ?? false
+
+	useKeyboard(
+		(key) => {
+			const entries = entriesRef.current
+			const matchOptions = matchOptionsRef.current
+			const stop = stopRef.current
+
+			for (const entry of entries) {
+				if (!isKey(key, entry.shortcut, matchOptions)) continue
+				if (stop && key.preventDefault) key.preventDefault()
+				entry.handler(key)
+				if (stop) break
+			}
+		},
+		{ phase: options.phase },
+	)
+}