@tarsis/toolkit 0.7.3 → 0.7.5

package/dist/{gl-B0NhVYRl.cjs → gl-DEE7rq9M.cjs}

@@ -1,15 +1,15 @@
 const require_chunk = require("./chunk-CKQMccvm.cjs");
 const require_assets = require("./assets-BMqH4phf.cjs");
 let three = require("three");
-three = require_chunk.__toESM(three);
+three = require_chunk.__toESM(three, 1);
 let load_bmfont = require("load-bmfont");
-load_bmfont = require_chunk.__toESM(load_bmfont);
+load_bmfont = require_chunk.__toESM(load_bmfont, 1);
 let three_bmfont_text = require("three-bmfont-text");
-three_bmfont_text = require_chunk.__toESM(three_bmfont_text);
+three_bmfont_text = require_chunk.__toESM(three_bmfont_text, 1);
 let three_bmfont_text_shaders_msdf = require("three-bmfont-text/shaders/msdf");
-three_bmfont_text_shaders_msdf = require_chunk.__toESM(three_bmfont_text_shaders_msdf);
+three_bmfont_text_shaders_msdf = require_chunk.__toESM(three_bmfont_text_shaders_msdf, 1);
 let three_orbit_controls = require("three-orbit-controls");
-three_orbit_controls = require_chunk.__toESM(three_orbit_controls);
+three_orbit_controls = require_chunk.__toESM(three_orbit_controls, 1);
 //#region src/components/Loaders/EndlessLoader/shaders.ts
 var vertexShader = `
   varying vec2 vUv;

package/dist/global.d.ts

@@ -0,0 +1,87 @@
+declare module '*.css' {
+  const src: string
+  export default src
+}
+
+declare module '*.module.css' {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+declare module '*.module.scss' {
+  const classes: { [key: string]: string }
+  export default classes
+}
+
+declare module '*.svg' {
+  const src: string
+  export default src
+}
+
+declare module '*.png' {
+  const src: string
+  export default src
+}
+
+declare module '*.wav' {
+  const src: string
+  export default src
+}
+
+declare module '*.mp3' {
+  const src: string
+  export default src
+}
+
+declare module '*.ogg' {
+  const src: string
+  export default src
+}
+
+declare module '*.fnt' {
+  const src: string
+  export default src
+}
+
+declare module '*?url' {
+  const src: string
+  export default src
+}
+
+declare module 'three-orbit-controls' {
+  const value: any
+  export default value
+}
+
+declare module 'load-bmfont' {
+  const value: any
+  export default value
+}
+
+declare module 'three-bmfont-text' {
+  const value: any
+  export default value
+}
+
+declare module 'three-bmfont-text/shaders/msdf' {
+  const value: any
+  export default value
+}
+
+declare module 'swiper/css'
+
+declare module 'p5' {
+  interface P5Instance {
+    [key: string]: any
+  }
+  type p5 = P5Instance
+  const p5: {
+    new (
+      sketch: (p: P5Instance) => void,
+      node?: HTMLElement | null,
+    ): {
+      remove: VoidFunction
+    }
+  }
+  export default p5
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,20 @@
+/// <reference path="../global.d.ts" />
+export * from './useAnimatedText';
+export * from './useControllableState';
+export * from './useMergeRefs';
+export * from './useBowser';
+export * from './useDebounce';
+export * from './useEffectEvent';
+export * from './useInterval';
+export * from './useLiveRef';
+export * from './useMatchMedia';
+export * from './useOklch';
+export * from './useOutsideClick';
+export * from './usePrevious';
+export * from './useRaf';
+export * from './useThrottle';
+export * from './useTimeout';
+export * from './useWindowReady';
+export * from './useReducedMotion';
+export * from './useGsapContext';
+export * from './useFormField';

package/dist/hooks/useAnimatedText/index.d.ts

@@ -0,0 +1 @@
+export * from './useAnimatedText';

package/dist/hooks/useAnimatedText/useAnimatedText.d.ts

@@ -0,0 +1 @@
+export declare function useAnimatedText(text: string, delimiter?: 'letter' | 'word'): string;

package/dist/hooks/useBowser.d.ts

@@ -0,0 +1,11 @@
+interface UseBowserResult {
+    isMobile: boolean;
+    isDesktop: boolean;
+    isMacOS: boolean;
+    isIOS: boolean;
+    isSafari: boolean;
+    isFirefox: boolean;
+    isChrome: boolean;
+}
+export declare const useBowser: () => UseBowserResult | null;
+export {};

package/dist/hooks/useControllableState.d.ts

@@ -0,0 +1,2 @@
+declare function useControllableState<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [T, (next: T | ((prev: T) => T)) => void];
+export { useControllableState };

package/dist/hooks/useDebounce.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Custom hook that debounces a callback function to delay its execution until after
+ * a specified wait time has elapsed since the last time it was invoked.
+ *
+ * Debouncing ensures that the callback is only executed once after a series of rapid calls,
+ * waiting for a pause in the calls before executing.
+ *
+ * @param callback - The function to debounce
+ * @param delay - The delay time (in milliseconds) to wait before executing the callback
+ * @param options - Optional configuration object
+ * @param options.maxWait - Maximum time before function must be invoked
+ * @param options.leading - If true, invoke on the leading edge
+ * @returns A debounced version of the callback function with a `cancel` method
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useDebounce((query: string) => {
+ *   console.log('Searching for:', query)
+ * }, 300)
+ *
+ * return <input onChange={(e) => debouncedSearch(e.target.value)} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With maxWait and leading options
+ * const debouncedSearch = useDebounce(
+ *   (query: string) => console.log('Searching for:', query),
+ *   300,
+ *   { maxWait: 1000, leading: true }
+ * )
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Cancel pending debounced call
+ * const debouncedSearch = useDebounce((query: string) => {
+ *   console.log('Searching for:', query)
+ * }, 300)
+ *
+ * debouncedSearch('test')
+ * debouncedSearch.cancel() // Cancels the pending call
+ * ```
+ */
+export declare const useDebounce: <T extends (...args: any[]) => any>(callback: T, delay: number, { maxWait, leading }?: {
+    maxWait?: number;
+    leading?: boolean;
+}) => T & {
+    cancel: VoidFunction;
+};

package/dist/hooks/useEffectEvent.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+/**
+ * Universal layout effect that uses useLayoutEffect in browser environments
+ * and falls back to useEffect in SSR environments
+ */
+export declare const useUniversalLayoutEffect: typeof React.useEffect;
+/**
+ * A React hook that implements the useEffectEvent pattern from React RFC.
+ * This hook allows you to define an event handler that can access the latest props/state
+ * without triggering effect dependency lists when the handler changes.
+ * @see https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md#internal-implementation
+ * @react https://react.dev/learn/separating-events-from-effects
+ */
+export declare function useEffectEvent<TArgs extends any[], TReturn extends undefined>(callback: undefined): (...args: TArgs) => TReturn;
+export declare function useEffectEvent<TArgs extends any[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+export declare function useEffectEvent<TArgs extends any[], TReturn>(callback: ((...args: TArgs) => TReturn) | undefined): (...args: TArgs) => TReturn | undefined;

package/dist/hooks/useFormField.d.ts

@@ -0,0 +1,36 @@
+type FormFieldIds = {
+    fieldId: string;
+    labelId: string;
+    errorId: string;
+    hintId: string;
+    descriptionId: string;
+};
+type FormFieldAria = {
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
+    'aria-errormessage'?: string;
+    id: string;
+};
+type UseFormFieldOptions = {
+    id?: string;
+    hasError?: boolean;
+    hasHint?: boolean;
+};
+type UseFormFieldReturn = {
+    ids: FormFieldIds;
+    labelProps: {
+        htmlFor: string;
+        id: string;
+    };
+    fieldProps: FormFieldAria;
+    errorProps: {
+        id: string;
+        role: 'alert';
+    };
+    hintProps: {
+        id: string;
+    };
+};
+declare function useFormField(options?: UseFormFieldOptions): UseFormFieldReturn;
+export { useFormField };
+export type { UseFormFieldReturn, UseFormFieldOptions, FormFieldIds };

package/dist/hooks/useGsapContext.d.ts

@@ -0,0 +1,20 @@
+import { type RefObject } from 'react';
+type GsapCallable = (...args: unknown[]) => unknown;
+type GsapContextLike = {
+    add(methodName: string, func: GsapCallable, scope?: Element | string | object): GsapCallable;
+    add<T extends GsapCallable>(func: T, scope?: Element | string | object): ReturnType<T>;
+    ignore(func: GsapCallable): void;
+    kill(revert?: boolean): void;
+    revert(config?: object): void;
+    clear(): void;
+    isReverted: boolean;
+};
+type GsapCleanup = () => void;
+/**
+ * Creates a GSAP context scoped to the given ref.
+ * All animations created inside the callback are automatically
+ * reverted on unmount — preventing DOM leak bugs.
+ */
+declare function useGsapContext(scope: RefObject<HTMLElement | null>, callback: (ctx: GsapContextLike) => void | GsapCleanup, deps?: unknown[]): RefObject<GsapContextLike | null>;
+export { useGsapContext };
+export type { GsapContextLike };

package/dist/hooks/useInterval.d.ts

@@ -0,0 +1,25 @@
+import { DependencyList } from 'react';
+/**
+ * Custom hook that manages an interval with automatic cleanup.
+ * Provides a reliable way to handle intervals that are properly cleaned up
+ * on component unmount or when dependencies change.
+ *
+ * @param callback - The function to execute on each interval
+ * @param delay - The delay in milliseconds (null to clear the interval)
+ * @param deps - Optional dependency array. If provided, interval restarts when deps change.
+ *               If not provided, callback updates via ref without restarting interval.
+ *
+ * @example
+ * ```tsx
+ * // Runs continuously, callback updates via ref
+ * useInterval(() => {
+ *   console.log('This runs every second')
+ * }, 1000)
+ *
+ * // Restarts interval when count changes
+ * useInterval(() => {
+ *   console.log('Count:', count)
+ * }, 1000, [count])
+ * ```
+ */
+export declare const useInterval: (callback: VoidFunction, delay?: number | null, deps?: DependencyList) => void;

package/dist/hooks/useLiveRef.d.ts

@@ -0,0 +1 @@
+export declare const useLiveRef: <T>(value: T) => import("react").RefObject<T>;

package/dist/hooks/useMatchMedia.d.ts

@@ -0,0 +1 @@
+export declare const useMatchMedia: (query: string) => boolean | null;

package/dist/hooks/useMergeRefs.d.ts

@@ -0,0 +1,5 @@
+import { type Ref, type RefCallback } from 'react';
+type PossibleRef<T> = Ref<T> | undefined | null;
+export declare function mergeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
+export declare function useMergeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
+export {};

package/dist/hooks/useOklch.d.ts

@@ -0,0 +1 @@
+export declare const useOklch: () => void;

package/dist/hooks/useOutsideClick.d.ts

@@ -0,0 +1,22 @@
+import { RefObject } from 'react';
+/**
+ * Custom hook that detects clicks outside of a specified element and triggers a callback.
+ *
+ * Useful for implementing dropdown menus, modals, or any component that should close
+ * when the user clicks outside of it.
+ *
+ * @param ref - React ref object pointing to the element to monitor
+ * @param callback - Function to call when a click occurs outside the element
+ * @param isActive - Whether the outside click detection should be active (default: true)
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null)
+ * const [isOpen, setIsOpen] = useState(false)
+ *
+ * useOutsideClick(ref, () => setIsOpen(false), isOpen)
+ *
+ * return <div ref={ref}>...</div>
+ * ```
+ */
+export declare const useOutsideClick: <T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, callback: VoidFunction, isActive?: boolean) => void;

package/dist/hooks/usePrevious.d.ts

@@ -0,0 +1,2 @@
+export declare const usePreviousState: <T>(value: T) => T | undefined;
+export declare const usePreviousRender: <T>(value: T) => T | undefined;

package/dist/hooks/useRaf.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Custom hook that provides a requestAnimationFrame-based callback execution.
+ * Useful for performance-critical animations and continuous updates that should
+ * be synchronized with the browser's refresh rate.
+ *
+ * The callback will be executed on the next animation frame, and can be
+ * controlled with an enabled flag for conditional execution.
+ *
+ * @param callback - The function to execute on each animation frame
+ * @param enabled - Whether the animation loop should be active (default: true)
+ * @returns A function to manually trigger the animation frame callback
+ *
+ * @example
+ * ```tsx
+ * const animate = useRaf(() => {
+ *   // Animation logic here
+ *   console.log('Animation frame')
+ * }, isAnimating)
+ *
+ * // Manually trigger
+ * animate()
+ * ```
+ */
+export declare const useRaf: (callback: VoidFunction, enabled?: boolean) => VoidFunction;

package/dist/hooks/useReducedMotion.d.ts

@@ -0,0 +1,2 @@
+declare function useReducedMotion(): boolean;
+export { useReducedMotion };

package/dist/hooks/useThrottle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Custom hook that throttles a callback function to limit how often it can be invoked.
+ *
+ * Throttling ensures that the callback is executed at most once per specified time interval,
+ * regardless of how many times the throttled function is called.
+ *
+ * @param callback - The function to throttle
+ * @param delay - The minimum time interval (in milliseconds) between executions
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```tsx
+ * const throttledClick = useThrottle(() => {
+ *   console.log('Button clicked')
+ * }, 500)
+ *
+ * return <button onClick={throttledClick}>Click me</button>
+ * ```
+ */
+export declare const useThrottle: <T extends (...args: any[]) => any>(callback: T, delay: number) => T;

package/dist/hooks/useTimeout.d.ts

@@ -0,0 +1,25 @@
+import { DependencyList } from 'react';
+/**
+ * Custom hook that manages a timeout with automatic cleanup.
+ * Provides a reliable way to handle timeouts that are properly cleaned up
+ * on component unmount or when dependencies change.
+ *
+ * @param callback - The function to execute after the delay
+ * @param delay - The delay in milliseconds (null to clear the timeout)
+ * @param deps - Optional dependency array. If provided, timeout restarts when deps change.
+ *               If not provided, callback updates via ref without restarting timeout.
+ *
+ * @example
+ * ```tsx
+ * // Runs once, callback updates via ref
+ * useTimeout(() => {
+ *   console.log('This runs after 1 second')
+ * }, 1000)
+ *
+ * // Restarts timeout when count changes
+ * useTimeout(() => {
+ *   console.log('Count:', count)
+ * }, 1000, [count])
+ * ```
+ */
+export declare const useTimeout: (callback: VoidFunction, delay?: number | null, deps?: DependencyList) => void;

package/dist/hooks/useWindowReady.d.ts

@@ -0,0 +1 @@
+export declare const useWindowReady: () => boolean;

package/dist/hooks.cjs

@@ -2,12 +2,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-CKQMccvm.cjs");
 const require_useMergeRefs = require("./useMergeRefs-C_l6omwU.cjs");
 let react = require("react");
-react = require_chunk.__toESM(react);
+react = require_chunk.__toESM(react, 1);
 let gsap = require("gsap");
-gsap = require_chunk.__toESM(gsap);
+gsap = require_chunk.__toESM(gsap, 1);
 let motion_react = require("motion/react");
 let bowser = require("bowser");
-bowser = require_chunk.__toESM(bowser);
+bowser = require_chunk.__toESM(bowser, 1);
 //#region src/hooks/usePrevious.ts
 var usePreviousState = (value) => {
 	const previousRef = (0, react.useRef)(void 0);
@@ -283,44 +283,30 @@ var useInterval = (callback, delay = null, deps = DEFAULT_DEPENDENCIES$1) => {
 //#endregion
 //#region src/hooks/useMatchMedia.ts
 var hasMatchMedia = () => {
-	return typeof window?.matchMedia === "function";
+	return typeof window !== "undefined" && typeof window.matchMedia === "function";
+};
+var getMatchMedia = (query) => {
+	if (!hasMatchMedia()) return null;
+	try {
+		return window.matchMedia(query);
+	} catch {
+		return null;
+	}
 };
 var useMatchMedia = (query) => {
-	const [matches, setMatches] = (0, react.useState)(() => {
-		if (!hasMatchMedia()) return null;
-		try {
-			return window.matchMedia(query).matches;
-		} catch {
-			return null;
-		}
-	});
-	const matchMedia = (0, react.useMemo)(() => {
-		if (!hasMatchMedia()) return null;
-		try {
-			return window.matchMedia(query);
-		} catch {
-			return null;
-		}
-	}, [query]);
-	const handleChange = (0, react.useCallback)((event) => {
-		setMatches(event.matches);
-	}, []);
-	(0, react.useEffect)(() => {
-		if (!matchMedia) return;
-		requestAnimationFrame(() => {
-			setMatches(matchMedia.matches);
-		});
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => {
+		const matchMedia = getMatchMedia(query);
+		if (!matchMedia) return () => {};
 		if (matchMedia.addEventListener) {
-			matchMedia.addEventListener("change", handleChange);
-			return () => matchMedia.removeEventListener("change", handleChange);
+			matchMedia.addEventListener("change", onStoreChange);
+			return () => matchMedia.removeEventListener("change", onStoreChange);
 		}
-		const legacyHandler = (event) => {
-			handleChange(event);
-		};
+		const legacyHandler = () => onStoreChange();
 		matchMedia.addListener(legacyHandler);
 		return () => matchMedia.removeListener(legacyHandler);
-	}, [matchMedia, handleChange]);
-	return matches;
+	}, [query]), (0, react.useCallback)(() => {
+		return getMatchMedia(query)?.matches ?? null;
+	}, [query]), () => null);
 };
 //#endregion
 //#region src/hooks/useOklch.ts

package/dist/hooks.js

@@ -1,5 +1,5 @@
 import { n as useMergeRefs, t as mergeRefs } from "./useMergeRefs-BM2-gSLn.js";
-import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import gsap from "gsap";
 import { animate, useMotionValue } from "motion/react";
 import Bowser from "bowser";
@@ -278,44 +278,30 @@ var useInterval = (callback, delay = null, deps = DEFAULT_DEPENDENCIES$1) => {
 //#endregion
 //#region src/hooks/useMatchMedia.ts
 var hasMatchMedia = () => {
-	return typeof window?.matchMedia === "function";
+	return typeof window !== "undefined" && typeof window.matchMedia === "function";
+};
+var getMatchMedia = (query) => {
+	if (!hasMatchMedia()) return null;
+	try {
+		return window.matchMedia(query);
+	} catch {
+		return null;
+	}
 };
 var useMatchMedia = (query) => {
-	const [matches, setMatches] = useState(() => {
-		if (!hasMatchMedia()) return null;
-		try {
-			return window.matchMedia(query).matches;
-		} catch {
-			return null;
-		}
-	});
-	const matchMedia = useMemo(() => {
-		if (!hasMatchMedia()) return null;
-		try {
-			return window.matchMedia(query);
-		} catch {
-			return null;
-		}
-	}, [query]);
-	const handleChange = useCallback((event) => {
-		setMatches(event.matches);
-	}, []);
-	useEffect(() => {
-		if (!matchMedia) return;
-		requestAnimationFrame(() => {
-			setMatches(matchMedia.matches);
-		});
+	return useSyncExternalStore(useCallback((onStoreChange) => {
+		const matchMedia = getMatchMedia(query);
+		if (!matchMedia) return () => {};
 		if (matchMedia.addEventListener) {
-			matchMedia.addEventListener("change", handleChange);
-			return () => matchMedia.removeEventListener("change", handleChange);
+			matchMedia.addEventListener("change", onStoreChange);
+			return () => matchMedia.removeEventListener("change", onStoreChange);
 		}
-		const legacyHandler = (event) => {
-			handleChange(event);
-		};
+		const legacyHandler = () => onStoreChange();
 		matchMedia.addListener(legacyHandler);
 		return () => matchMedia.removeListener(legacyHandler);
-	}, [matchMedia, handleChange]);
-	return matches;
+	}, [query]), useCallback(() => {
+		return getMatchMedia(query)?.matches ?? null;
+	}, [query]), () => null);
 };
 //#endregion
 //#region src/hooks/useOklch.ts