@tarsis/toolkit 0.6.6 → 0.7.1

package/dist/hooks.d.ts

@@ -1,7 +1,42 @@
 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;
@@ -16,6 +51,8 @@ declare interface UseBowserResult {
     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.
@@ -80,6 +117,37 @@ export declare function useEffectEvent<TArgs extends any[], TReturn>(callback: (
 
 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
@@ -109,6 +177,8 @@ 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;
 
 /**
@@ -162,6 +232,8 @@ export declare const usePreviousState: <T>(value: T) => T | undefined;
  */
 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.
  *