@codeleap/hooks 5.8.21 → 6.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/hooks",
-  "version": "5.8.21",
+  "version": "6.1.2",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -9,22 +9,22 @@
     "directory": "packages/hooks"
   },
   "devDependencies": {
-    "@codeleap/config": "5.8.21",
-    "@codeleap/types": "5.8.21",
-    "@codeleap/utils": "5.8.21",
-    "@codeleap/logger": "5.8.21",
+    "@codeleap/config": "6.1.2",
+    "@codeleap/types": "6.1.2",
+    "@codeleap/utils": "6.1.2",
+    "@codeleap/logger": "6.1.2",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
     "build": "echo 'No build needed'"
   },
   "peerDependencies": {
-    "@codeleap/types": "5.8.21",
-    "@codeleap/utils": "5.8.21",
-    "@codeleap/logger": "5.8.21",
+    "@codeleap/types": "6.1.2",
+    "@codeleap/utils": "6.1.2",
+    "@codeleap/logger": "6.1.2",
     "axios": "^1.7.9",
     "typescript": "5.5.2",
-    "react": "18.2.0",
+    "react": "19.1.0",
     "@tanstack/react-query": "5.89.0"
   }
 }

package/package.json.bak

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/hooks",
-  "version": "5.8.21",
+  "version": "6.1.2",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -24,7 +24,7 @@
     "@codeleap/logger": "workspace:*",
     "axios": "^1.7.9",
     "typescript": "5.5.2",
-    "react": "18.2.0",
+    "react": "19.1.0",
     "@tanstack/react-query": "5.89.0"
   }
 }

package/src/index.ts

@@ -13,9 +13,7 @@ import {
 
 export * from './useConditionalState'
 export * from './usePromise'
-export * from './useListState'
 export * from './useUncontrolled'
-export * from './useCounter'
 export * from './useForceRender'
 export * from './useDebounce'
 export * from './useInterval'
@@ -34,6 +32,13 @@ export * from './usePartialState'
 export * from './useIsMounted'
 export * from './useComponentTestId'
 export * from './useId'
+export * from './useAnimatedState'
+export * from './useDebounceCallback'
+export * from './useDerivedRef'
+export * from './useDerivedState'
+export * from './useFilteredList'
+export * from './useLazyStore'
+export * from './useOptions'
 
 export {
   useEffect,

package/src/onMount.ts

@@ -1,6 +1,15 @@
 import { useEffect } from 'react'
 import { AnyFunction } from '@codeleap/types'
 
+/**
+ * Hook that runs a function once when the component mounts.
+ *
+ * @example
+ * onMount(() => {
+ *   console.log('Component mounted')
+ *   return () => console.log('Component unmounted')
+ * })
+ */
 export const onMount = (func: AnyFunction) => {
   useEffect(() => {
     return func()

package/src/onUpdate.ts

@@ -1,6 +1,14 @@
 import { useEffect } from 'react'
 import { AnyFunction } from '@codeleap/types'
 
+/**
+ * Hook that runs a function when specified dependencies change.
+ *
+ * @example
+ * onUpdate(() => {
+ *   console.log('Count changed:', count)
+ * }, [count])
+ */
 export const onUpdate = (func: AnyFunction, listeners = []) => {
   useEffect(() => {
     return func()

package/src/useAnimatedState.ts

@@ -0,0 +1,42 @@
+import { useState, useCallback } from 'react'
+import { SharedValue, useSharedValue, useDerivedValue, runOnJS, isSharedValue } from 'react-native-reanimated'
+
+/**
+ * Hook that synchronizes a React state with a Reanimated SharedValue.
+ *
+ * @example
+ * const [value, setValue, sharedValue] = useAnimatedState(0)
+ * setValue(10) // Updates both React state and SharedValue
+ */
+export function useAnimatedState<T>(initialValue: SharedValue<T> | T) {
+  const sharedValue = isSharedValue(initialValue)
+    ? initialValue
+    : useSharedValue<T>(initialValue)
+
+  const [value, _setValue] = useState<T>(
+    isSharedValue(initialValue) ? initialValue.value : initialValue,
+  )
+
+  useDerivedValue(() => {
+    runOnJS(_setValue)(sharedValue.value)
+  })
+
+  const setValue = useCallback((newValue: T) => {
+    sharedValue.value = newValue
+    if (isSharedValue(initialValue)) initialValue.value = newValue
+    _setValue(newValue)
+  }, [])
+
+  return [value, setValue, sharedValue] as const
+}
+
+/**
+ * Hook that extracts and synchronizes the value from a SharedValue.
+ *
+ * @example
+ * const value = useAnimatedValue(sharedValue)
+ */
+export function useAnimatedValue<T>(initialValue: SharedValue<T> | T): T {
+  const [value] = useAnimatedState(initialValue)
+  return value
+}

package/src/useBooleanToggle.ts

@@ -1,5 +1,13 @@
 import { useState } from 'react'
 
+/**
+ * Hook that manages a boolean state with toggle functionality.
+ *
+ * @example
+ * const [isOpen, toggleOpen] = useBooleanToggle(false)
+ * toggleOpen() // Toggles the value
+ * toggleOpen(true) // Sets to true
+ */
 export function useBooleanToggle(initial: boolean) {
   const [v, setV] = useState(initial)
 

package/src/useComponentTestId.ts

@@ -13,8 +13,7 @@ const simpleHash = (str: string): string => {
 const normalizeProps = <P extends AnyRecord>(props: P, keys: Array<keyof P>): Partial<P> => {
   return keys.reduce((acc, key) => {
     if (key === 'children') {
-      acc[key] = Children.map(props[key], (child) =>
-        typeof child === 'object' ? '[Component]' : child
+      acc[key] = Children.map(props[key], (child) => typeof child === 'object' ? '[Component]' : child,
       )
     } else {
       acc[key] = props[key]
@@ -28,17 +27,25 @@ const normalizeDebugName = (debugName: string) => {
 }
 
 const generateComponentTestId = <P extends AnyRecord>(componentName: string, props: P, keys: Array<keyof P>) => {
-  const hasDebugName = typeof props?.['debugName'] === 'string'
-  if (hasDebugName) return `${componentName}:${normalizeDebugName(props?.['debugName'])}`
+  const hasDebugName = typeof props?.debugName === 'string'
+  if (hasDebugName) return `${componentName}:${normalizeDebugName(props?.debugName)}`
   const extractedProps = normalizeProps(props, keys)
   return `${componentName}:${simpleHash(JSON.stringify(extractedProps))}`
 }
 
+/**
+ * Hook that generates a stable test ID for a component based on its props.
+ * Uses debugName if available, otherwise generates a hash from specified prop keys.
+ *
+ * @example
+ * const testId = useComponentTestId(Button, props, ['label', 'variant'])
+ * // Returns: "Button:debug-name" or "Button:123456"
+ */
 export const useComponentTestId = <P extends AnyRecord>(
   Component: any,
   props: P,
-  keys: Array<keyof P>
+  keys: Array<keyof P>,
 ) => {
   const testIdRef = useRef(generateComponentTestId(Component.styleRegistryName, props, keys))
   return testIdRef.current
-}
+}

package/src/useConditionalState.ts

@@ -9,10 +9,21 @@ type UseConditionalStateOptions<T> = {
 
 type SetState<T> = Dispatch<SetStateAction<T>> & ((value: T) => void) & (() => void)
 
+/**
+ * Hook that uses external state if provided, otherwise creates internal state.
+ * Useful for creating controlled/uncontrolled component patterns.
+ *
+ * @example
+ * // Controlled mode
+ * const [value, setValue] = useConditionalState(props.value, props.onChange)
+ *
+ * // Uncontrolled mode
+ * const [value, setValue] = useConditionalState(undefined, undefined, { initialValue: 'default' })
+ */
 export const useConditionalState = <T>(
   value: T | undefined,
   setter: AnyFunction,
-  options: UseConditionalStateOptions<T> = {}
+  options: UseConditionalStateOptions<T> = {},
 ): [T, SetState<T>] => {
   const state = options?.isBooleanToggle
     ? useBooleanToggle(options?.initialValue as boolean)

package/src/useDebounce.ts

@@ -1,5 +1,12 @@
 import { useEffect, useRef, useState } from 'react'
 
+/**
+ * Hook that debounces a value, updating it after a specified delay.
+ *
+ * @example
+ * const [debouncedSearch, resetDebounce] = useDebounce(searchTerm, 500)
+ * // debouncedSearch updates 500ms after searchTerm stops changing
+ */
 export function useDebounce<T>(
   value: T,
   debounce: number,

package/src/useDebounceCallback.ts

@@ -0,0 +1,47 @@
+import { useRef, useCallback } from 'react'
+
+/**
+ * Hook that creates debounced, flush, and cancel functions for a callback.
+ *
+ * @example
+ * const { debounce, flush, cancel } = useDebounceCallback((value) => {
+ *   console.log(value)
+ * }, 500)
+ *
+ * debounce('hello') // Will call callback after 500ms
+ * flush('immediate') // Calls callback immediately
+ * cancel() // Cancels pending debounced call
+ */
+export function useDebounceCallback<T extends any[]>(
+  callback: (...args: T) => void,
+  delay = 1000,
+) {
+  const timeoutRef = useRef(null)
+
+  const debounce = useCallback((...args: T) => {
+    cancel()
+
+    timeoutRef.current = setTimeout(() => {
+      callback(...args)
+      timeoutRef.current = null
+    }, delay)
+  }, [callback])
+
+  const flush = useCallback((...args: T) => {
+    cancel()
+    callback(...args)
+  }, [callback])
+
+  const cancel = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+  }, [])
+
+  return {
+    debounce,
+    flush,
+    cancel,
+  }
+}

package/src/useDerivedRef.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * Hook that creates a ref that automatically updates when a derived value changes.
+ *
+ * @example
+ * const userNameRef = useDerivedRef(user, (u) => u.name)
+ * // userNameRef.current will always contain the latest user name
+ */
+export const useDerivedRef = <T, D>(
+  derivedValue: D,
+  getValue: (derivedValue: D) => T,
+): React.MutableRefObject<T> => {
+  const ref = useRef(getValue(derivedValue))
+
+  useEffect(() => {
+    ref.current = getValue(derivedValue)
+  }, [derivedValue])
+
+  return ref
+}

package/src/useDerivedState.ts

@@ -0,0 +1,42 @@
+import { deepEqual } from '@codeleap/utils'
+import { useState, useEffect } from 'react'
+
+type Options<T, D> = {
+  areEqual?: (currentState: T, derivedValue: D) => boolean
+  transform?: (value: D | T) => any
+  getValue?: (derivedValue: D) => T
+}
+
+/**
+ * Hook that creates a state that synchronizes with a derived value, with customizable equality check.
+ *
+ * @example
+ * const [state, setState] = useDerivedState(props.value, {
+ *   getValue: (v) => v.id,
+ *   areEqual: (a, b) => a === b.id
+ * })
+ */
+export const useDerivedState = <T, D = T>(
+  derivedValue: D,
+  options: Options<T, D> = {},
+): [T, React.Dispatch<React.SetStateAction<T>>] => {
+  const {
+    getValue = (value: any) => value as T,
+    transform = (value) => value,
+    areEqual = (currentState, derivedValue) => deepEqual(currentState, derivedValue),
+  } = options
+
+  const [state, setState] = useState<T>(() => getValue(derivedValue))
+
+  useEffect(() => {
+    const newValue = getValue(derivedValue)
+
+    const stateAreEqual = areEqual(transform(state), transform(derivedValue))
+
+    if (!stateAreEqual) {
+      setState(newValue)
+    }
+  }, [derivedValue])
+
+  return [state, setState]
+}

package/src/useEffectOnce.ts

@@ -1,5 +1,14 @@
 import { EffectCallback, useEffect } from 'react'
 
+/**
+ * Hook that runs an effect only once when the component mounts.
+ *
+ * @example
+ * useEffectOnce(() => {
+ *   console.log('Runs only once on mount')
+ *   return () => console.log('Cleanup on unmount')
+ * })
+ */
 export const useEffectOnce = (effect: EffectCallback) => {
   useEffect(effect, [])
 }

package/src/useFilteredList.ts

@@ -0,0 +1,21 @@
+import { useMemo } from 'react'
+
+/**
+ * Hook that filters out the first item from a list that matches a predicate.
+ *
+ * @example
+ * const filteredUsers = useFilteredList(users, (user) => user.id === deletedId)
+ * // Returns users array without the first user matching the predicate
+ */
+export function useFilteredList<T>(list: T[], predicate: (item: T) => boolean): T[] {
+  return useMemo(() => {
+    if (!list) return []
+
+    const index = list.findIndex(predicate)
+    if (index === -1) return list
+
+    const newList = [...list]
+    newList.splice(index, 1)
+    return newList
+  }, [list, predicate])
+}

package/src/useForceRender.ts

@@ -1,5 +1,12 @@
 import { useReducer } from 'react'
 
+/**
+ * Hook that returns a function to force a component re-render.
+ *
+ * @example
+ * const forceRender = useForceRender()
+ * forceRender() // Forces component to re-render
+ */
 export function useForceRender() {
   const [_, forceRender] = useReducer((x) => x + 1, 0)
   return forceRender

package/src/useId.ts

@@ -1,8 +1,15 @@
 import { useRef, useId as _useId } from 'react'
 
+/**
+ * Hook that returns a stable ID, using provided ID if available or generating one.
+ *
+ * @example
+ * const id = useId('custom-id') // Returns 'custom-id'
+ * const id = useId() // Returns generated ID like ':r1:'
+ */
 export function useId<T>(id?: T) {
   const defaultId = _useId()
   const idRef = useRef(id)
 
   return idRef.current ?? defaultId
-}
+}

package/src/useInterval.ts

@@ -1,17 +1,51 @@
-import { useRef } from 'react'
+import { useRef, useCallback, useEffect } from 'react'
 import { AnyFunction } from '@codeleap/types'
 
-export function useInterval(callback: AnyFunction, interval: number) {
-  const intervalRef = useRef(null)
+type UseIntervalHandler = (clear: AnyFunction) => void
 
-  function clear() {
-    clearInterval(intervalRef.current)
-    intervalRef.current = null
-  }
+/**
+ * Hook that manages an interval with start and clear controls.
+ * The handler receives a clear function to stop the interval from within.
+ *
+ * @example
+ * const { start, clear } = useInterval((clearFn) => {
+ *   console.log('Tick')
+ *   if (shouldStop) clearFn()
+ * }, 1000)
+ *
+ * start() // Starts the interval
+ * clear() // Stops the interval
+ */
+export function useInterval(handler: UseIntervalHandler, interval: number) {
+  const intervalRef = useRef<NodeJS.Timer | null>(null)
+  const handlerRef = useRef<UseIntervalHandler>(handler)
 
-  function start() {
-    intervalRef.current = setInterval(callback, interval)
-  }
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  const clear = useCallback(() => {
+    if (intervalRef.current != null) {
+      clearInterval(intervalRef.current)
+      intervalRef.current = null
+    }
+  }, [])
+
+  const start = useCallback(() => {
+    clear()
+
+    if (intervalRef.current == null) {
+      intervalRef.current = setInterval(() => {
+        handlerRef.current(clear)
+      }, interval)
+    }
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      clear()
+    }
+  }, [clear])
 
   return {
     clear,

package/src/useIsMounted.ts

@@ -7,7 +7,12 @@ const useIsomorphicLayoutEffect =
 
 /**
  * Hook to check if the component has mounted. SSR safe.
- * @return true after the component's html is mounted in the browser.
+ *
+ * @example
+ * const isMounted = useIsMounted()
+ * if (isMounted) {
+ *   // Safe to use browser APIs
+ * }
  */
 export function useIsMounted() {
   const [mounted, setMounted] = useState(false)
@@ -22,7 +27,12 @@ export function useIsMounted() {
 /**
  * Hook to check if the code is running on the client-side.
  * NOTE: This is just a mirror of `useIsMounted` for retrocompatibility reasons
- * @return `isClient: true` after the component is mounted in the browser.
+ *
+ * @example
+ * const { isClient } = useIsClient()
+ * if (isClient) {
+ *   // Safe to use browser APIs
+ * }
  */
 export function useIsClient() {
   return {

package/src/useLazyStore.ts

@@ -0,0 +1,18 @@
+import { globalState } from '@codeleap/store'
+import { useMemo } from 'react'
+
+/**
+ * Hook that lazily creates a global store with an initial value.
+ * The store is created only once and persists across re-renders.
+ *
+ * @example
+ * const counterStore = useLazyStore(0)
+ * // Store is created once and can be used across components
+ */
+export function useLazyStore<T>(initialValue: T) {
+  const store = useMemo(() => {
+    return globalState(initialValue)
+  }, [])
+
+  return store
+}

package/src/useModal.ts

@@ -1,6 +1,16 @@
 import { TypeGuards } from '@codeleap/types'
 import { useState } from 'react'
 
+/**
+ * Hook that manages modal visibility state with open, close, and toggle functions.
+ *
+ * @example
+ * const modal = useModal()
+ * modal.open() // Opens modal
+ * modal.close() // Closes modal
+ * modal.toggle() // Toggles visibility
+ * modal.toggle(true) // Forces open
+ */
 export function useModal(startsOpen = false) {
   const [visible, setVisible] = useState(startsOpen)
 
@@ -17,7 +27,7 @@ export function useModal(startsOpen = false) {
   }
 
   return {
-    visible, 
+    visible,
     toggle,
     open,
     close,

package/src/useOptions.ts

@@ -0,0 +1,27 @@
+import { useMemo, useState } from 'react'
+
+/**
+ * Hook that manages selected option state with boolean flags for each option.
+ *
+ * @example
+ * const { selectedOption, setSelectedOption, isSelected } = useOptions(['light', 'dark'] as const)
+ * // isSelected = { light: true, dark: false }
+ * setSelectedOption('dark')
+ * // isSelected = { light: false, dark: true }
+ */
+export function useOptions<T extends string>(options: readonly T[], initialOptions: T = options[0]) {
+  const [selectedOption, setSelectedOption] = useState<T>(initialOptions)
+
+  const isSelected = useMemo(() => {
+    return options.reduce((acc, option) => {
+      acc[option] = option === selectedOption
+      return acc
+    }, {} as Record<T, boolean>)
+  }, [selectedOption, options])
+
+  return {
+    selectedOption,
+    setSelectedOption,
+    isSelected,
+  }
+}

package/src/usePartialState.ts

@@ -4,6 +4,14 @@ import { deepMerge } from '@codeleap/utils'
 
 type SetPartialStateCallback<T> = (value: T) => DeepPartial<T>
 
+/**
+ * Hook that manages state with partial updates using deep merge.
+ *
+ * @example
+ * const [user, setUser] = usePartialState({ name: 'John', age: 30 })
+ * setUser({ age: 31 }) // Only updates age, keeps name
+ * setUser(prev => ({ age: prev.age + 1 })) // Functional update
+ */
 export function usePartialState<T= any>(initial: T | (() => T)) {
   const [state, setState] = useState(initial)
 

package/src/usePlaces.ts

@@ -13,6 +13,9 @@ type Params = {
   showDetails?: boolean
 }
 
+/**
+ * Retrieves detailed information for a specific Google Place.
+ */
 export const retrievePlaceDetails = async (placeId: string, apiKey: string) => {
   const response = await axios.get(BASE_URL_DETAILS, {
     params: {
@@ -24,6 +27,10 @@ export const retrievePlaceDetails = async (placeId: string, apiKey: string) => {
   return response?.data?.result
 }
 
+/**
+ * Retrieves places from Google Places API or Geocoding API.
+ * Supports both text search and lat/lng coordinates.
+ */
 export const retrievePlaces = async (params: Params) => {
   let response
   const inputWithoutSpaces = params?.input?.replace(/\s/g, '')
@@ -53,6 +60,17 @@ export const retrievePlaces = async (params: Params) => {
 
 export type UsePlacesParams = Params
 
+/**
+ * Hook that fetches Google Places using React Query.
+ * Automatically handles caching and refetching.
+ *
+ * @example
+ * const places = usePlaces({
+ *   input: 'New York',
+ *   key: 'YOUR_API_KEY',
+ *   showDetails: true
+ * })
+ */
 export const usePlaces = (params: Params) => {
   const places = useQuery({
     queryKey: ['places', params],

package/src/usePlacesAutocompleteUtils.ts

@@ -7,6 +7,22 @@ export type UsePlacesAutocompleteUtilsProps<T extends Record<string, any>> = {
   onPress?: (address: string, item: T) => void
 }
 
+/**
+ * Hook that manages address autocomplete state with debounced input handling.
+ * Useful for Google Places autocomplete implementations.
+ *
+ * @example
+ * const {
+ *   address,
+ *   handleChangeAddress,
+ *   handlePressAddress,
+ *   isTyping
+ * } = usePlacesAutocompleteUtils({
+ *   debounce: 500,
+ *   onValueChange: (addr) => fetchPlaces(addr),
+ *   onPress: (addr, item) => console.log('Selected:', item)
+ * })
+ */
 export const usePlacesAutocompleteUtils = <T extends Record<string, any>>(props: UsePlacesAutocompleteUtilsProps<T>) => {
   const {
     debounce = 250,

package/src/usePrevious.ts

@@ -1,7 +1,17 @@
 import { useEffect, useRef } from 'react'
 
+/**
+ * Hook that returns the previous value of a variable.
+ * The value is updated after render is committed to the DOM.
+ *
+ * @example
+ * const [count, setCount] = useState(0)
+ * const prevCount = usePrevious(count)
+ * // On first render: count=0, prevCount=null
+ * // After setCount(1): count=1, prevCount=0
+ */
 export const usePrevious = <T>(value: T) => {
-  const ref = useRef<T>()
+  const ref = useRef<T>(null)
   useEffect(() => {
     ref.current = value
   })

package/src/usePromise.ts

@@ -8,10 +8,24 @@ type UsePromiseOptions<T = any> = {
   debugName?: string
 }
 
+/**
+ * Hook that creates a deferred promise with manual resolve/reject control.
+ * Useful for coordinating asynchronous operations across component lifecycle.
+ *
+ * @example
+ * const promise = usePromise({ timeout: 5000 })
+ * const handleClick = async () => {
+ *   const result = await promise._await()
+ *   console.log(result)
+ * }
+ * // Later, from another callback:
+ * promise.resolve('success')
+ */
 export const usePromise = <T = any>(options?: UsePromiseOptions<T>) => {
-  const rejectRef = useRef<AnyFunction>()
-  const resolveRef = useRef<(v:T) => any>()
+  const rejectRef = useRef<AnyFunction>(null)
+  const resolveRef = useRef<(v:T) => any>(null)
   const timeoutRef = useRef(null)
+
   const reject = async (err: any) => {
     await rejectRef.current?.(err)
     options?.onReject?.(err)

package/src/useSearch/index.ts

@@ -3,6 +3,22 @@ import { useBooleanToggle } from '../useBooleanToggle'
 import { useSearchParams } from './types'
 import { TypeGuards } from '@codeleap/types'
 
+/**
+ * Hook that manages searchable select/autocomplete state with async loading support.
+ * Handles both local filtering and remote data fetching.
+ *
+ * @example
+ * const search = useSearch({
+ *   value: 'selected-value',
+ *   multiple: false,
+ *   defaultOptions: [...],
+ *   loadOptions: async (query) => fetchOptions(query),
+ *   filterItems: (query, opts) => opts.filter(o => o.label.includes(query))
+ * })
+ *
+ * search.onChangeSearch('query')
+ * search.load()
+ */
 export function useSearch<T extends string|number = string, Multi extends boolean = false>(props: useSearchParams<T, Multi>) {
   const {
     value,

package/src/useToggle.ts

@@ -1,5 +1,13 @@
 import { useState } from 'react'
 
+/**
+ * Hook that toggles between two values.
+ *
+ * @example
+ * const [theme, toggleTheme] = useToggle(['light', 'dark'] as const, 'light')
+ * toggleTheme() // Switches to 'dark'
+ * toggleTheme('light') // Sets to 'light'
+ */
 export function useToggle<T extends readonly [any, any], V extends T[0] | T[1]>(
   options: T,
   initial: V,

package/src/useUncontrolled.ts

@@ -11,6 +11,18 @@ export interface UncontrolledOptions<T> {
   rule: (value: T | null | undefined) => boolean
 }
 
+/**
+ * Hook that manages controlled/uncontrolled component pattern with smooth transitions.
+ *
+ * @example
+ * const [value, handleChange, mode] = useUncontrolled({
+ *   value: props.value,
+ *   defaultValue: 'default',
+ *   finalValue: '',
+ *   rule: (v) => v !== undefined,
+ *   onChange: (v) => props.onChange?.(v)
+ * })
+ */
 export function useUncontrolled<T>({
   value,
   defaultValue,

package/src/useUnmount.ts

@@ -1,6 +1,16 @@
 import { useRef } from 'react'
 import { useEffectOnce } from './useEffectOnce'
 
+/**
+ * Hook that runs a cleanup function when the component unmounts.
+ * The function reference is updated on each render to always use the latest version.
+ *
+ * @example
+ * useUnmount(() => {
+ *   console.log('Component unmounting')
+ *   // Cleanup logic here
+ * })
+ */
 export const useUnmount = (fn: () => any): void => {
   const fnRef = useRef(fn)
 

package/src/useCounter.ts

@@ -1,5 +0,0 @@
-import { useReducer } from 'react'
-
-export function useCounter() {
-  return useReducer((x) => x + 1, 0)
-}

package/src/useListState.ts

@@ -1,92 +0,0 @@
-import { useState } from 'react'
-
-export interface UseListStateHandler<T> {
-  setState: React.Dispatch<React.SetStateAction<T[]>>
-  append: (...items: T[]) => void
-  prepend: (...items: T[]) => void
-  insert: (index: number, ...items: T[]) => void
-  pop: () => void
-  shift: () => void
-  apply: (fn: (item: T, index?: number) => T) => void
-  applyWhere: (
-    condition: (item: T, index: number) => boolean,
-    fn: (item: T, index?: number) => T
-  ) => void
-  remove: (...indices: number[]) => void
-  reorder: ({ from, to }: { from: number; to: number }) => void
-  setItem: (index: number, item: T) => void
-  setItemProp: <K extends keyof T, U extends T[K]>(index: number, prop: K, value: U) => void
-}
-
-export type UseListState<T> = [T[], UseListStateHandler<T>]
-
-export function useListState<T>(initialValue: (T[] | (() => T[])) = []): UseListState<T> {
-  const [state, setState] = useState(initialValue)
-
-  const append = (...items: T[]) => setState((current) => [...current, ...items])
-  const prepend = (...items: T[]) => setState((current) => [...items, ...current])
-
-  const insert = (index: number, ...items: T[]) => setState((current) => [...current.slice(0, index), ...items, ...current.slice(index)])
-
-  const apply = (fn: (item: T, index?: number) => T) => setState((current) => current.map((item, index) => fn(item, index)))
-
-  const remove = (...indices: number[]) => setState((current) => current.filter((_, index) => !indices.includes(index)))
-
-  const pop = () => setState((current) => {
-    const cloned = [...current]
-    cloned.pop()
-    return cloned
-  })
-
-  const shift = () => setState((current) => {
-    const cloned = [...current]
-    cloned.shift()
-    return cloned
-  })
-
-  const reorder = ({ from, to }: { from: number; to: number }) => setState((current) => {
-    const cloned = [...current]
-    const item = current[from]
-
-    cloned.splice(from, 1)
-    cloned.splice(to, 0, item)
-
-    return cloned
-  })
-
-  const setItem = (index: number, item: T) => setState((current) => {
-    const cloned = [...current]
-    cloned[index] = item
-    return cloned
-  })
-
-  const setItemProp = <K extends keyof T, U extends T[K]>(index: number, prop: K, value: U) => setState((current) => {
-    const cloned = [...current]
-    cloned[index] = { ...cloned[index], [prop]: value }
-    return cloned
-  })
-
-  const applyWhere = (
-    condition: (item: T, index: number) => boolean,
-    fn: (item: T, index?: number) => T,
-  ) => setState((current) => current.map((item, index) => (condition(item, index) ? fn(item, index) : item)),
-  )
-
-  return [
-    state,
-    {
-      setState,
-      append,
-      prepend,
-      insert,
-      pop,
-      shift,
-      apply,
-      applyWhere,
-      remove,
-      reorder,
-      setItem,
-      setItemProp,
-    },
-  ]
-}