@pyreon/hooks 0.3.0 → 0.11.0

package/lib/index.d.ts

@@ -13,6 +13,33 @@ declare function useBreakpoint(breakpoints?: BreakpointMap): () => string;
  */
 declare function useClickOutside(getEl: () => HTMLElement | null, handler: () => void): void;
 //#endregion
+//#region src/useClipboard.d.ts
+interface UseClipboardResult {
+  /** Copy text to clipboard. Returns true on success. */
+  copy: (text: string) => Promise<boolean>;
+  /** Whether the last copy succeeded (resets after timeout). */
+  copied: () => boolean;
+  /** The last successfully copied text. */
+  text: () => string;
+}
+/**
+ * Reactive clipboard access — copy text and track copied state.
+ *
+ * @param options.timeout - ms before `copied` resets to false (default: 2000)
+ *
+ * @example
+ * ```tsx
+ * const { copy, copied } = useClipboard()
+ *
+ * <button onClick={() => copy("hello")}>
+ *   {() => copied() ? "Copied!" : "Copy"}
+ * </button>
+ * ```
+ */
+declare function useClipboard(options?: {
+  timeout?: number;
+}): UseClipboardResult;
+//#endregion
 //#region src/useColorScheme.d.ts
 /**
  * Returns the OS color scheme preference as 'light' or 'dark'.
@@ -57,6 +84,39 @@ declare const useDebouncedCallback: UseDebouncedCallback;
  */
 declare function useDebouncedValue<T>(getter: () => T, delayMs: number): () => T;
 //#endregion
+//#region src/useDialog.d.ts
+interface UseDialogResult {
+  /** Whether the dialog is currently open. */
+  open: () => boolean;
+  /** Open the dialog. */
+  show: () => void;
+  /** Open as modal (with backdrop, traps focus). */
+  showModal: () => void;
+  /** Close the dialog. */
+  close: () => void;
+  /** Toggle open/closed state. */
+  toggle: () => void;
+  /** Ref callback — pass to `ref` prop on a `<dialog>` element. */
+  ref: (el: HTMLDialogElement) => void;
+}
+/**
+ * Signal-driven dialog management for the native `<dialog>` element.
+ *
+ * @example
+ * ```tsx
+ * const dialog = useDialog()
+ *
+ * <button onClick={dialog.showModal}>Open</button>
+ * <dialog ref={dialog.ref}>
+ *   <p>Modal content</p>
+ *   <button onClick={dialog.close}>Close</button>
+ * </dialog>
+ * ```
+ */
+declare function useDialog(options?: {
+  onClose?: () => void;
+}): UseDialogResult;
+//#endregion
 //#region src/useElementSize.d.ts
 interface Size {
   width: number;
@@ -67,6 +127,25 @@ interface Size {
  */
 declare function useElementSize(getEl: () => HTMLElement | null): () => Size;
 //#endregion
+//#region src/useEventListener.d.ts
+/**
+ * Attach an event listener with automatic cleanup on unmount.
+ * Works with Window, Document, HTMLElement, or any EventTarget.
+ *
+ * @example
+ * ```tsx
+ * useEventListener("keydown", (e) => {
+ *   if (e.key === "Escape") close()
+ * })
+ *
+ * useEventListener("scroll", handleScroll, { passive: true })
+ *
+ * // On a specific element:
+ * useEventListener("click", handler, {}, () => buttonRef.current)
+ * ```
+ */
+declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (e: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions, target?: () => EventTarget | null | undefined): void;
+//#endregion
 //#region src/useFocus.d.ts
 interface UseFocusResult {
   focused: () => boolean;
@@ -105,6 +184,50 @@ interface UseHoverResult {
  */
 declare function useHover(): UseHoverResult;
 //#endregion
+//#region src/useInfiniteScroll.d.ts
+interface UseInfiniteScrollOptions {
+  /** Distance from bottom (px) to trigger load. Default: 100 */
+  threshold?: number;
+  /** Whether loading is in progress (prevents duplicate calls). */
+  loading?: () => boolean;
+  /** Whether there's more data to load. Default: true */
+  hasMore?: () => boolean;
+  /** Scroll direction. Default: "down" */
+  direction?: "up" | "down";
+}
+interface UseInfiniteScrollResult {
+  /** Attach to the scroll container element. */
+  ref: (el: HTMLElement | null) => void;
+  /** Whether the sentinel is currently visible. */
+  triggered: () => boolean;
+}
+/**
+ * Signal-driven infinite scroll using IntersectionObserver.
+ * Calls `onLoadMore` when the user scrolls near the end of the container.
+ *
+ * @example
+ * ```tsx
+ * const items = signal<Item[]>([])
+ * const loading = signal(false)
+ * const hasMore = signal(true)
+ *
+ * const { ref } = useInfiniteScroll(() => {
+ *   loading.set(true)
+ *   const next = await fetchMore()
+ *   items.update(prev => [...prev, ...next])
+ *   hasMore.set(next.length > 0)
+ *   loading.set(false)
+ * }, { loading, hasMore })
+ *
+ * <div ref={ref} style={{ overflowY: "auto", height: "400px" }}>
+ *   <For each={items()} by={i => i.id}>
+ *     {item => <div>{item.name}</div>}
+ *   </For>
+ * </div>
+ * ```
+ */
+declare function useInfiniteScroll(onLoadMore: () => void | Promise<void>, options?: UseInfiniteScrollOptions): UseInfiniteScrollResult;
+//#endregion
 //#region src/useIntersection.d.ts
 /**
  * Observe element intersection reactively.
@@ -178,6 +301,21 @@ type UseMergedRef = <T>(...refs: (Ref<T> | undefined)[]) => (node: T | null) =>
  */
 declare const useMergedRef: <T>(...refs: (Ref<T> | undefined)[]) => ((node: T | null) => void);
 //#endregion
+//#region src/useOnline.d.ts
+/**
+ * Reactive online/offline status.
+ * Tracks `navigator.onLine` and updates on connectivity changes.
+ *
+ * @example
+ * ```tsx
+ * const online = useOnline()
+ * <Show when={!online()} fallback={<App />}>
+ *   <OfflineBanner />
+ * </Show>
+ * ```
+ */
+declare function useOnline(): () => boolean;
+//#endregion
 //#region src/usePrevious.d.ts
 /**
  * Track the previous value of a reactive getter.
@@ -261,6 +399,37 @@ type UseThrottledCallback = <T extends (...args: any[]) => any>(callback: T, del
  */
 declare const useThrottledCallback: UseThrottledCallback;
 //#endregion
+//#region src/useTimeAgo.d.ts
+type TimeUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+interface UseTimeAgoOptions {
+  /** Custom formatter. Receives the value, unit, and whether it's in the past. */
+  formatter?: (value: number, unit: TimeUnit, isPast: boolean) => string;
+  /** Update interval override in ms. If not set, adapts based on age. */
+  interval?: number;
+}
+/**
+ * Reactive relative time that auto-updates.
+ * Returns a signal that displays "2 minutes ago", "just now", etc.
+ *
+ * @param date - Date object, timestamp, or reactive getter
+ *
+ * @example
+ * ```tsx
+ * const timeAgo = useTimeAgo(post.createdAt)
+ * <span>{timeAgo}</span>
+ * // Renders: "5 minutes ago" → "6 minutes ago" (auto-updates)
+ *
+ * // With reactive date:
+ * const timeAgo = useTimeAgo(() => selectedPost().createdAt)
+ *
+ * // With custom formatter (e.g. for i18n):
+ * const timeAgo = useTimeAgo(date, {
+ *   formatter: (value, unit, isPast) => t('time.' + unit, { count: value })
+ * })
+ * ```
+ */
+declare function useTimeAgo(date: Date | number | (() => Date | number), options?: UseTimeAgoOptions): () => string;
+//#endregion
 //#region src/useTimeout.d.ts
 type UseTimeout = (callback: () => void, delay: number | null) => {
   reset: () => void;
@@ -308,5 +477,5 @@ interface WindowSize {
  */
 declare function useWindowResize(throttleMs?: number): () => WindowSize;
 //#endregion
-export { type BreakpointMap, type Size, type UseControllableState, type UseDebouncedCallback, type UseFocusResult, type UseHoverResult, type UseInterval, type UseIsomorphicLayoutEffect, type UseLatest, type UseMergedRef, type UseRootSize, type UseSpacing, type UseThemeValue, type UseThrottledCallback, type UseTimeout, type UseToggleResult, type UseUpdateEffect, type WindowSize, useBreakpoint, useClickOutside, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useElementSize, useFocus, useFocusTrap, useHover, useIntersection, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMediaQuery, useMergedRef, usePrevious, useReducedMotion, useRootSize, useScrollLock, useSpacing, useThemeValue, useThrottledCallback, useTimeout, useToggle, useUpdateEffect, useWindowResize };
+export { type BreakpointMap, type Size, type UseClipboardResult, type UseControllableState, type UseDebouncedCallback, type UseDialogResult, type UseFocusResult, type UseHoverResult, type UseInfiniteScrollOptions, type UseInfiniteScrollResult, type UseInterval, type UseIsomorphicLayoutEffect, type UseLatest, type UseMergedRef, type UseRootSize, type UseSpacing, type UseThemeValue, type UseThrottledCallback, type UseTimeAgoOptions, type UseTimeout, type UseToggleResult, type UseUpdateEffect, type WindowSize, useBreakpoint, useClickOutside, useClipboard, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useDialog, useElementSize, useEventListener, useFocus, useFocusTrap, useHover, useInfiniteScroll, useIntersection, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMediaQuery, useMergedRef, useOnline, usePrevious, useReducedMotion, useRootSize, useScrollLock, useSpacing, useThemeValue, useThrottledCallback, useTimeAgo, useTimeout, useToggle, useUpdateEffect, useWindowResize };
 //# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -1,5 +1,5 @@
 import { onMount, onUnmount } from "@pyreon/core";
-import { computed, effect, signal, watch } from "@pyreon/reactivity";
+import { computed, effect, onCleanup, signal, watch } from "@pyreon/reactivity";
 import { useTheme } from "@pyreon/styler";
 import { get, throttle } from "@pyreon/ui-core";
 
@@ -64,6 +64,50 @@ function useClickOutside(getEl, handler) {
 	});
 }
 
+//#endregion
+//#region src/useClipboard.ts
+/**
+* Reactive clipboard access — copy text and track copied state.
+*
+* @param options.timeout - ms before `copied` resets to false (default: 2000)
+*
+* @example
+* ```tsx
+* const { copy, copied } = useClipboard()
+*
+* <button onClick={() => copy("hello")}>
+*   {() => copied() ? "Copied!" : "Copy"}
+* </button>
+* ```
+*/
+function useClipboard(options) {
+	const timeout = options?.timeout ?? 2e3;
+	const copied = signal(false);
+	const text = signal("");
+	let timer;
+	const copy = async (value) => {
+		try {
+			await navigator.clipboard.writeText(value);
+			text.set(value);
+			copied.set(true);
+			if (timer) clearTimeout(timer);
+			timer = setTimeout(() => copied.set(false), timeout);
+			return true;
+		} catch {
+			copied.set(false);
+			return false;
+		}
+	};
+	onCleanup(() => {
+		if (timer) clearTimeout(timer);
+	});
+	return {
+		copy,
+		copied,
+		text
+	};
+}
+
 //#endregion
 //#region src/useMediaQuery.ts
 /**
@@ -184,6 +228,64 @@ function useDebouncedValue(getter, delayMs) {
 	return debounced;
 }
 
+//#endregion
+//#region src/useDialog.ts
+/**
+* Signal-driven dialog management for the native `<dialog>` element.
+*
+* @example
+* ```tsx
+* const dialog = useDialog()
+*
+* <button onClick={dialog.showModal}>Open</button>
+* <dialog ref={dialog.ref}>
+*   <p>Modal content</p>
+*   <button onClick={dialog.close}>Close</button>
+* </dialog>
+* ```
+*/
+function useDialog(options) {
+	const open = signal(false);
+	let dialogEl = null;
+	let closeHandler = null;
+	const show = () => {
+		dialogEl?.show();
+		open.set(true);
+	};
+	const showModal = () => {
+		dialogEl?.showModal();
+		open.set(true);
+	};
+	const close = () => {
+		dialogEl?.close();
+		open.set(false);
+	};
+	const toggle = () => {
+		if (open()) close();
+		else showModal();
+	};
+	const ref = (el) => {
+		if (dialogEl && closeHandler) dialogEl.removeEventListener("close", closeHandler);
+		dialogEl = el;
+		closeHandler = () => {
+			open.set(false);
+			options?.onClose?.();
+		};
+		el.addEventListener("close", closeHandler);
+	};
+	onCleanup(() => {
+		if (dialogEl && closeHandler) dialogEl.removeEventListener("close", closeHandler);
+	});
+	return {
+		open,
+		show,
+		showModal,
+		close,
+		toggle,
+		ref
+	};
+}
+
 //#endregion
 //#region src/useElementSize.ts
 /**
@@ -219,6 +321,31 @@ function useElementSize(getEl) {
 	return size;
 }
 
+//#endregion
+//#region src/useEventListener.ts
+/**
+* Attach an event listener with automatic cleanup on unmount.
+* Works with Window, Document, HTMLElement, or any EventTarget.
+*
+* @example
+* ```tsx
+* useEventListener("keydown", (e) => {
+*   if (e.key === "Escape") close()
+* })
+*
+* useEventListener("scroll", handleScroll, { passive: true })
+*
+* // On a specific element:
+* useEventListener("click", handler, {}, () => buttonRef.current)
+* ```
+*/
+function useEventListener(event, handler, options, target) {
+	if (!(typeof window !== "undefined")) return;
+	const el = target?.() ?? window;
+	el.addEventListener(event, handler, options);
+	onCleanup(() => el.removeEventListener(event, handler, options));
+}
+
 //#endregion
 //#region src/useFocus.ts
 /**
@@ -288,6 +415,88 @@ function useHover() {
 	};
 }
 
+//#endregion
+//#region src/useInfiniteScroll.ts
+/**
+* Signal-driven infinite scroll using IntersectionObserver.
+* Calls `onLoadMore` when the user scrolls near the end of the container.
+*
+* @example
+* ```tsx
+* const items = signal<Item[]>([])
+* const loading = signal(false)
+* const hasMore = signal(true)
+*
+* const { ref } = useInfiniteScroll(() => {
+*   loading.set(true)
+*   const next = await fetchMore()
+*   items.update(prev => [...prev, ...next])
+*   hasMore.set(next.length > 0)
+*   loading.set(false)
+* }, { loading, hasMore })
+*
+* <div ref={ref} style={{ overflowY: "auto", height: "400px" }}>
+*   <For each={items()} by={i => i.id}>
+*     {item => <div>{item.name}</div>}
+*   </For>
+* </div>
+* ```
+*/
+function useInfiniteScroll(onLoadMore, options) {
+	const threshold = options?.threshold ?? 100;
+	const direction = options?.direction ?? "down";
+	const triggered = signal(false);
+	let observer = null;
+	let sentinel = null;
+	let containerEl = null;
+	const handleIntersect = (entries) => {
+		const entry = entries[0];
+		if (!entry) return;
+		triggered.set(entry.isIntersecting);
+		if (entry.isIntersecting) {
+			if (options?.loading?.()) return;
+			if (options?.hasMore && !options.hasMore()) return;
+			onLoadMore();
+		}
+	};
+	const setup = (el) => {
+		cleanup();
+		containerEl = el;
+		sentinel = document.createElement("div");
+		sentinel.style.height = "1px";
+		sentinel.style.width = "100%";
+		sentinel.style.pointerEvents = "none";
+		sentinel.setAttribute("aria-hidden", "true");
+		if (direction === "down") el.appendChild(sentinel);
+		else el.insertBefore(sentinel, el.firstChild);
+		observer = new IntersectionObserver(handleIntersect, {
+			root: el,
+			rootMargin: direction === "down" ? `0px 0px ${threshold}px 0px` : `${threshold}px 0px 0px 0px`,
+			threshold: 0
+		});
+		observer.observe(sentinel);
+	};
+	const cleanup = () => {
+		if (observer) {
+			observer.disconnect();
+			observer = null;
+		}
+		if (sentinel && containerEl) {
+			sentinel.remove();
+			sentinel = null;
+		}
+	};
+	const ref = (el) => {
+		if (el) setup(el);
+		else cleanup();
+	};
+	onCleanup(cleanup);
+	return {
+		ref,
+		triggered
+	};
+}
+
 //#endregion
 //#region src/useIntersection.ts
 /**
@@ -388,6 +597,36 @@ const useMergedRef = (...refs) => {
 	};
 };
 
+//#endregion
+//#region src/useOnline.ts
+/**
+* Reactive online/offline status.
+* Tracks `navigator.onLine` and updates on connectivity changes.
+*
+* @example
+* ```tsx
+* const online = useOnline()
+* <Show when={!online()} fallback={<App />}>
+*   <OfflineBanner />
+* </Show>
+* ```
+*/
+function useOnline() {
+	const isBrowser = typeof window !== "undefined";
+	const online = signal(isBrowser ? navigator.onLine : true);
+	if (isBrowser) {
+		const setOnline = () => online.set(true);
+		const setOffline = () => online.set(false);
+		window.addEventListener("online", setOnline);
+		window.addEventListener("offline", setOffline);
+		onCleanup(() => {
+			window.removeEventListener("online", setOnline);
+			window.removeEventListener("offline", setOffline);
+		});
+	}
+	return online;
+}
+
 //#endregion
 //#region src/usePrevious.ts
 /**
@@ -519,6 +758,119 @@ const useThrottledCallback = (callback, delay) => {
 	return throttled;
 };
 
+//#endregion
+//#region src/useTimeAgo.ts
+const INTERVALS = [
+	{
+		unit: "year",
+		seconds: 31536e3
+	},
+	{
+		unit: "month",
+		seconds: 2592e3
+	},
+	{
+		unit: "week",
+		seconds: 604800
+	},
+	{
+		unit: "day",
+		seconds: 86400
+	},
+	{
+		unit: "hour",
+		seconds: 3600
+	},
+	{
+		unit: "minute",
+		seconds: 60
+	},
+	{
+		unit: "second",
+		seconds: 1
+	}
+];
+/**
+* Determine how often to update based on the age of the timestamp.
+* Recent times update more frequently.
+*/
+function getRefreshInterval(diffSeconds) {
+	if (diffSeconds < 60) return 1e3;
+	if (diffSeconds < 3600) return 3e4;
+	if (diffSeconds < 86400) return 3e5;
+	return 36e5;
+}
+/**
+* Default English formatter using Intl.RelativeTimeFormat.
+*/
+const defaultFormatter = (() => {
+	const rtf = typeof Intl !== "undefined" ? new Intl.RelativeTimeFormat("en", { numeric: "auto" }) : void 0;
+	return (value, unit, isPast) => {
+		if (rtf) return rtf.format(isPast ? -value : value, unit);
+		const label = value === 1 ? unit : `${unit}s`;
+		return isPast ? `${value} ${label} ago` : `in ${value} ${label}`;
+	};
+})();
+/**
+* Compute the relative time string for a given timestamp.
+*/
+function computeTimeAgo(date, formatter) {
+	const now = Date.now();
+	const target = typeof date === "number" ? date : date.getTime();
+	const diff = Math.abs(now - target);
+	const diffSeconds = Math.floor(diff / 1e3);
+	const isPast = target < now;
+	if (diffSeconds < 5) return "just now";
+	for (const { unit, seconds } of INTERVALS) {
+		const value = Math.floor(diffSeconds / seconds);
+		if (value >= 1) return formatter(value, unit, isPast);
+	}
+	return "just now";
+}
+/**
+* Reactive relative time that auto-updates.
+* Returns a signal that displays "2 minutes ago", "just now", etc.
+*
+* @param date - Date object, timestamp, or reactive getter
+*
+* @example
+* ```tsx
+* const timeAgo = useTimeAgo(post.createdAt)
+* <span>{timeAgo}</span>
+* // Renders: "5 minutes ago" → "6 minutes ago" (auto-updates)
+*
+* // With reactive date:
+* const timeAgo = useTimeAgo(() => selectedPost().createdAt)
+*
+* // With custom formatter (e.g. for i18n):
+* const timeAgo = useTimeAgo(date, {
+*   formatter: (value, unit, isPast) => t('time.' + unit, { count: value })
+* })
+* ```
+*/
+function useTimeAgo(date, options) {
+	const formatter = options?.formatter ?? defaultFormatter;
+	const resolveDate = typeof date === "function" ? date : () => date;
+	const result = signal(computeTimeAgo(resolveDate(), formatter));
+	let timer;
+	let disposed = false;
+	function tick() {
+		if (disposed) return;
+		const d = resolveDate();
+		result.set(computeTimeAgo(d, formatter));
+		const target = typeof d === "number" ? d : d.getTime();
+		const diffSeconds = Math.floor(Math.abs(Date.now() - target) / 1e3);
+		const interval = options?.interval ?? getRefreshInterval(diffSeconds);
+		timer = setTimeout(tick, interval);
+	}
+	timer = setTimeout(tick, 0);
+	onCleanup(() => {
+		disposed = true;
+		if (timer) clearTimeout(timer);
+	});
+	return result;
+}
+
 //#endregion
 //#region src/useTimeout.ts
 /**
@@ -613,5 +965,5 @@ function useWindowResize(throttleMs = 200) {
 }
 
 //#endregion
-export { useBreakpoint, useClickOutside, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useElementSize, useFocus, useFocusTrap, useHover, useIntersection, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMediaQuery, useMergedRef, usePrevious, useReducedMotion, useRootSize, useScrollLock, useSpacing, useThemeValue, useThrottledCallback, useTimeout, useToggle, useUpdateEffect, useWindowResize };
+export { useBreakpoint, useClickOutside, useClipboard, useColorScheme, useControllableState, useDebouncedCallback, useDebouncedValue, useDialog, useElementSize, useEventListener, useFocus, useFocusTrap, useHover, useInfiniteScroll, useIntersection, useInterval, useIsomorphicLayoutEffect, useKeyboard, useLatest, useMediaQuery, useMergedRef, useOnline, usePrevious, useReducedMotion, useRootSize, useScrollLock, useSpacing, useThemeValue, useThrottledCallback, useTimeAgo, useTimeout, useToggle, useUpdateEffect, useWindowResize };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@pyreon/hooks",
-  "version": "0.3.0",
+  "version": "0.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pyreon/ui-system",
-    "directory": "packages/hooks"
+    "directory": "packages/fundamentals/hooks"
   },
   "description": "Signal-based reactive utilities for Pyreon",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "bun": "./src/index.ts",
     "source": "./src/index.ts",
     "import": "./lib/index.js",
     "types": "./lib/index.d.ts"
@@ -25,7 +26,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">= 18"
+    "node": ">= 22"
   },
   "publishConfig": {
     "access": "public"
@@ -41,13 +42,13 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@pyreon/core": ">=0.4.0 <1.0.0",
-    "@pyreon/reactivity": ">=0.4.0 <1.0.0",
-    "@pyreon/styler": ">=0.3.0",
-    "@pyreon/ui-core": ">=0.3.0"
+    "@pyreon/core": "^0.11.0",
+    "@pyreon/reactivity": "^0.11.0",
+    "@pyreon/styler": "^0.11.0",
+    "@pyreon/ui-core": "^0.11.0"
   },
   "devDependencies": {
     "@vitus-labs/tools-rolldown": "^1.15.3",
-    "@pyreon/typescript": "^0.7.4"
+    "@pyreon/typescript": "^0.11.0"
   }
 }