@tarsis/toolkit 0.7.3 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tarsis/toolkit",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "publishConfig": {
     "access": "public"
   },
@@ -30,21 +30,21 @@
     },
     "./hooks": {
       "import": {
-        "types": "./dist/hooks.d.ts",
+        "types": "./dist/hooks/index.d.ts",
         "default": "./dist/hooks.js"
       },
       "require": {
-        "types": "./dist/hooks.d.ts",
+        "types": "./dist/hooks/index.d.ts",
         "default": "./dist/hooks.cjs"
       }
     },
     "./utils": {
       "import": {
-        "types": "./dist/utils.d.ts",
+        "types": "./dist/utils/index.d.ts",
         "default": "./dist/utils.js"
       },
       "require": {
-        "types": "./dist/utils.d.ts",
+        "types": "./dist/utils/index.d.ts",
         "default": "./dist/utils.cjs"
       }
     },
@@ -101,7 +101,7 @@
     "test:coverage": "vitest run --coverage",
     "test:visual": "npx --yes chromatic --build-script-name build:storybook --exit-zero-on-changes",
     "build:storybook": "storybook build",
-    "build": "yarn docs && tsc && vite build",
+    "build": "yarn docs && yarn typecheck && vite build && node scripts/build-types.mjs",
     "package:smoke": "yarn build && node scripts/package-smoke.mjs",
     "typecheck": "tsc --noEmit",
     "typecheck:stories": "tsc -p tsconfig.stories.json --noEmit",
@@ -145,15 +145,15 @@
     "@changesets/changelog-github": "0.6.0",
     "@changesets/cli": "2.30.0",
     "@chromatic-com/storybook": "5.1.1",
-    "@eslint/compat": "2.0.4",
+    "@eslint/compat": "2.0.5",
     "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
     "@faker-js/faker": "10.4.0",
-    "@storybook/addon-a11y": "10.3.4",
-    "@storybook/addon-docs": "10.3.4",
-    "@storybook/addon-links": "10.3.4",
-    "@storybook/addon-onboarding": "10.3.4",
-    "@storybook/react-vite": "10.3.4",
+    "@storybook/addon-a11y": "10.3.5",
+    "@storybook/addon-docs": "10.3.5",
+    "@storybook/addon-links": "10.3.5",
+    "@storybook/addon-onboarding": "10.3.5",
+    "@storybook/react-vite": "10.3.5",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.2",
@@ -165,8 +165,8 @@
     "@types/node": "22.19.15",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
-    "@typescript-eslint/eslint-plugin": "8.58.0",
-    "@typescript-eslint/parser": "8.58.0",
+    "@typescript-eslint/eslint-plugin": "8.58.1",
+    "@typescript-eslint/parser": "8.58.1",
     "@vitejs/plugin-react": "6.0.1",
     "@vitest/coverage-v8": "3.2.4",
     "@vitest/ui": "3.2.4",
@@ -178,29 +178,29 @@
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.0.1",
     "eslint-plugin-react-refresh": "0.5.2",
-    "eslint-plugin-storybook": "10.3.3",
+    "eslint-plugin-storybook": "10.3.5",
     "expect-type": "1.3.0",
     "globals": "15.14.0",
     "husky": "9.1.7",
-    "jsdom": "29.0.1",
-    "postcss": "8.5.8",
+    "jsdom": "29.0.2",
+    "postcss": "8.5.9",
     "postcss-preset-env": "11.2.0",
-    "prettier": "3.8.1",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "sass": "1.98.0",
-    "storybook": "10.3.4",
+    "prettier": "3.8.2",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "sass": "1.99.0",
+    "storybook": "10.3.5",
     "tsx": "4.21.0",
     "typescript": "6.0.2",
-    "vite": "8.0.5",
+    "vite": "8.0.8",
     "vite-plugin-dts": "4.5.4",
     "vite-plugin-static-copy": "4.0.1",
     "vitest": "3.2.4",
     "vitest-axe": "1.0.0-pre.5"
   },
   "peerDependencies": {
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4"
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
   },
   "resolutions": {
     "parse5": "7.3.0"

package/dist/hooks.d.ts

@@ -1,291 +0,0 @@
-import { default as default_2 } from 'react';
-import { DependencyList } from 'react';
-import { Ref } from 'react';
-import { RefCallback } from 'react';
-import { RefObject } from 'react';
-
-declare type FormFieldAria = {
-    'aria-describedby'?: string;
-    'aria-invalid'?: boolean;
-    'aria-errormessage'?: string;
-    id: string;
-};
-
-export declare type FormFieldIds = {
-    fieldId: string;
-    labelId: string;
-    errorId: string;
-    hintId: string;
-    descriptionId: string;
-};
-
-declare type GsapCallable = (...args: unknown[]) => unknown;
-
-declare type GsapCleanup = () => void;
-
-export declare 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;
-};
-
-export declare function mergeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
-
-declare type PossibleRef<T> = Ref<T> | undefined | null;
-
-export declare function useAnimatedText(text: string, delimiter?: 'letter' | 'word'): string;
-
-export declare const useBowser: () => UseBowserResult | null;
-
-declare interface UseBowserResult {
-    isMobile: boolean;
-    isDesktop: boolean;
-    isMacOS: boolean;
-    isIOS: boolean;
-    isSafari: boolean;
-    isFirefox: boolean;
-    isChrome: boolean;
-}
-
-export declare function useControllableState<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [T, (next: T | ((prev: T) => T)) => void];
-
-/**
- * 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;
-};
-
-/**
- * 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;
-
-export declare function useFormField(options?: UseFormFieldOptions): UseFormFieldReturn;
-
-export declare type UseFormFieldOptions = {
-    id?: string;
-    hasError?: boolean;
-    hasHint?: boolean;
-};
-
-export declare type UseFormFieldReturn = {
-    ids: FormFieldIds;
-    labelProps: {
-        htmlFor: string;
-        id: string;
-    };
-    fieldProps: FormFieldAria;
-    errorProps: {
-        id: string;
-        role: 'alert';
-    };
-    hintProps: {
-        id: string;
-    };
-};
-
-/**
- * Creates a GSAP context scoped to the given ref.
- * All animations created inside the callback are automatically
- * reverted on unmount — preventing DOM leak bugs.
- */
-export declare function useGsapContext(scope: RefObject<HTMLElement | null>, callback: (ctx: GsapContextLike) => void | GsapCleanup, deps?: unknown[]): RefObject<GsapContextLike | null>;
-
-/**
- * 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;
-
-export declare const useLiveRef: <T>(value: T) => RefObject<T>;
-
-export declare const useMatchMedia: (query: string) => boolean | null;
-
-export declare function useMergeRefs<T>(...refs: PossibleRef<T>[]): RefCallback<T>;
-
-export declare const useOklch: () => void;
-
-/**
- * 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;
-
-export declare const usePreviousRender: <T>(value: T) => T | undefined;
-
-export declare const usePreviousState: <T>(value: T) => T | undefined;
-
-/**
- * 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;
-
-export declare function useReducedMotion(): boolean;
-
-/**
- * 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;
-
-/**
- * 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;
-
-/**
- * Universal layout effect that uses useLayoutEffect in browser environments
- * and falls back to useEffect in SSR environments
- */
-export declare const useUniversalLayoutEffect: typeof default_2.useEffect;
-
-export declare const useWindowReady: () => boolean;
-
-export { }

package/dist/utils.d.ts

@@ -1,165 +0,0 @@
-import { JSX } from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-
-export declare const animationLogger: BaseLogger;
-
-export declare const apiLogger: BaseLogger;
-
-export declare class BaseLogger {
-    protected prefix: string;
-    protected emoji: string;
-    constructor(prefix: string, emoji: string);
-    private log;
-    info(msg: string, data?: unknown): void;
-    debug(msg: string, data?: unknown): void;
-    success(msg: string, data?: unknown): void;
-    warn(msg: string, data?: unknown): void;
-    error(msg: string, detail?: unknown): void;
-    scope(msg: string, data?: unknown): void;
-    dir<T>(data: T): void;
-    time(label: string): {
-        end: (data?: unknown) => void;
-    };
-}
-
-export declare type BoundedMap<K, V> = ReturnType<typeof createBoundedMap<K, V>>;
-
-export declare type BoundedMapOptions = {
-    maxSize: number;
-    ttlMs?: number;
-};
-
-export declare const chain: (...elements: ReactNode[]) => JSX.Element[];
-
-export declare const clearSession: () => void;
-
-export declare const componentLogger: BaseLogger;
-
-declare type Constructor<T> = new (...args: any[]) => T;
-
-/**
- * LRU map with optional TTL. Evicts least-recently-used entries
- * when maxSize is exceeded, and expired entries on access.
- */
-export declare function createBoundedMap<K, V>(options: BoundedMapOptions): {
-    get(key: K): V | undefined;
-    has(key: K): boolean;
-    set(key: K, value: V): void;
-    delete(key: K): boolean;
-    clear(): void;
-    readonly size: number;
-};
-
-/**
- * Create standardized enter/exit motion variants using toolkit tokens.
- * Returns `{ initial, animate, exit }` for framer-motion / motion.
- */
-export declare const createPresenceVariants: (enter: Record<string, unknown>, exit: Record<string, unknown>, duration?: number, easingCurve?: readonly [number, number, number, number]) => PresenceVariants;
-
-export declare function delay(ms: number): Promise<unknown>;
-
-/**
- * Math utility functions for animations and interactions
- */
-export declare function distance(x1: number, x2: number, y1: number, y2: number): number;
-
-export declare const eventLogger: BaseLogger;
-
-export declare const fadePresence: PresenceVariants;
-
-/**
- * Formats seconds into MM:SS display string.
- */
-export declare function formatDuration(totalSeconds: number): string;
-
-/**
- * Formats milliseconds into MM:SS.ms display string.
- * Useful for timers and stopwatches.
- */
-export declare function formatTime(totalMs: number): string;
-
-export declare const getCurrentLogLevel: () => LogLevel;
-
-export declare function getPath(x: number, smoothing: number): string;
-
-export declare const hookLogger: BaseLogger;
-
-export declare const is: <T>(type: Constructor<T>) => (x: T) => boolean;
-
-export declare const isDebugEnabled: () => boolean;
-
-export declare const isNonNullable: <T>(value: T) => value is NonNullable<T>;
-
-export declare const keys: <T extends Record<string | number | symbol, any>>(value: T) => Array<`${keyof T & (string | number | boolean)}` | (keyof T & symbol)>;
-
-export declare function lerp(a: number, b: number, n: number): number;
-
-export declare function lineEq(y2: number, y1: number, x2: number, x1: number, currentVal: number): number;
-
-export declare const logger: BaseLogger;
-
-/**
- * Advanced logger utility for the toolkit
- * Provides consistent logging interface across components with emojis, session tracking, and performance timing
- */
-export declare type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
-
-export declare const move: <T>(source: T[], start: number, end: number) => T[];
-
-export declare const noop: (..._args: unknown[]) => void;
-
-/**
- * Normalises unknown thrown values into proper Error instances.
- * Preserves original Error objects; wraps strings and unknowns.
- */
-export declare function normalizeError(err: unknown): Error;
-
-export declare const notReachable: (arg: never) => never;
-
-export declare type PresenceVariants = {
-    initial: Record<string, unknown>;
-    animate: Record<string, unknown>;
-    exit: Record<string, unknown>;
-};
-
-export declare const scalePresence: PresenceVariants;
-
-export declare const setLogLevel: (level: LogLevel) => void;
-
-export declare const setRequestId: (id: string) => void;
-
-export declare const setSessionId: (id: string) => void;
-
-export declare const slideDownPresence: PresenceVariants;
-
-export declare const slideUpPresence: PresenceVariants;
-
-/**
- * Wrapper around the View Transitions API.
- * Uses `document.startViewTransition` when available (Chrome 111+, Safari 18+),
- * falls back to calling the callback directly on unsupported browsers.
- */
-export declare const startViewTransition: (callback: () => void | Promise<void>) => ViewTransitionReturn;
-
-export declare const storageLogger: BaseLogger;
-
-/**
- * Check if the View Transitions API is supported in the current browser.
- */
-export declare const supportsViewTransitions: () => boolean;
-
-export declare const times: <T>(fn: (index: number) => T, size: number) => T[];
-
-export declare const utilsLogger: BaseLogger;
-
-export declare const values: <T extends Record<string | number | symbol, any>>(input: T) => Array<T[keyof T]>;
-
-export declare type ViewTransitionReturn = {
-    finished: Promise<void>;
-    ready: Promise<void>;
-    updateCallbackDone: Promise<void>;
-};
-
-export declare const wait: (ms: number) => Promise<unknown>;
-
-export { }