State Management

/**
 * Toggle between boolean values or custom array of values
 * @param options - Array of values to toggle between (default: [false, true])
 * @returns Tuple of current value and toggle function
 */
function useToggle<T = boolean>(options?: readonly T[]): UseToggleReturnValue<T>;

type UseToggleAction<T> = (value?: React.SetStateAction<T>) => void;
type UseToggleReturnValue<T> = [T, UseToggleAction<T>];

import { useToggle } from "@mantine/hooks";

// Boolean toggle
const [opened, toggle] = useToggle();
// toggle() switches between false/true
// toggle(true) sets to true

// Custom values toggle
const [theme, toggleTheme] = useToggle(['light', 'dark'] as const);
// toggleTheme() switches between 'light' and 'dark'
// toggleTheme('dark') sets to 'dark'

/**
 * Counter with increment/decrement handlers and optional constraints
 * @param initialValue - Initial counter value (default: 0)
 * @param options - Configuration with min/max constraints
 * @returns Tuple of current count and handler object
 */
function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturnValue;

interface UseCounterOptions {
  min?: number;
  max?: number;
}

interface UseCounterHandlers {
  increment: () => void;
  decrement: () => void;
  set: (value: number) => void;
  reset: () => void;
}

type UseCounterReturnValue = [number, UseCounterHandlers];

import { useCounter } from "@mantine/hooks";

// Basic counter
const [count, { increment, decrement, set, reset }] = useCounter(0);

// Counter with constraints
const [score, handlers] = useCounter(0, { min: 0, max: 100 });
// increment() won't go above 100
// decrement() won't go below 0

/**
 * Boolean state with open/close/toggle handlers and callbacks
 * @param initialState - Initial state (default: false)
 * @param options - Lifecycle callbacks
 * @returns Tuple of current state and handler object
 */
function useDisclosure(initialState?: boolean, options?: UseDisclosureOptions): UseDisclosureReturnValue;

interface UseDisclosureOptions {
  onOpen?: () => void;
  onClose?: () => void;
}

interface UseDisclosureHandlers {
  open: () => void;
  close: () => void;
  toggle: () => void;
}

type UseDisclosureReturnValue = [boolean, UseDisclosureHandlers];

import { useDisclosure } from "@mantine/hooks";

// Modal state management
const [opened, { open, close, toggle }] = useDisclosure(false, {
  onOpen: () => console.log('Modal opened'),
  onClose: () => console.log('Modal closed'),
});

// Usage in component
<Modal opened={opened} onClose={close}>
  Content
</Modal>

/**
 * Array state with comprehensive manipulation handlers
 * @param initialValue - Initial array value or function returning array
 * @returns Tuple of current array and handler object
 */
function useListState<T>(initialValue?: T[] | (() => T[])): UseListStateReturnValue<T>;

interface UseListStateHandlers<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;
  swap: ({ 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;
  filter: (fn: (item: T, i: number) => boolean) => void;
}

type UseListStateReturnValue<T> = [T[], UseListStateHandlers<T>];

import { useListState } from "@mantine/hooks";

const [todos, handlers] = useListState([
  { id: 1, text: 'Learn React', completed: false },
  { id: 2, text: 'Build app', completed: false },
]);

// Add new todo
handlers.append({ id: 3, text: 'Deploy app', completed: false });

// Toggle completion
handlers.setItemProp(0, 'completed', true);

// Remove completed todos
handlers.filter((todo) => !todo.completed);

// Reorder todos
handlers.reorder({ from: 0, to: 1 });

/**
 * Manage controlled/uncontrolled component state patterns
 * @param options - Configuration for value management
 * @returns Tuple of current value, setter, and controlled flag
 */
function useUncontrolled<T>(options: UseUncontrolledOptions<T>): UseUncontrolledReturnValue<T>;

interface UseUncontrolledOptions<T> {
  value?: T;
  defaultValue?: T;
  finalValue?: T;
  onChange?: (value: T, ...payload: any[]) => void;
}

type UseUncontrolledReturnValue<T> = [T, (value: T, ...payload: any[]) => void, boolean];

/**
 * Object state with partial updates like class components
 * @param initialState - Initial state object
 * @returns Tuple of current state and setter function
 */
function useSetState<T extends Record<string, any>>(initialState: T): UseSetStateReturnValue<T>;

type UseSetStateCallback<T> = (current: T) => Partial<T>;
type UseSetStateReturnValue<T> = [T, (statePartial: Partial<T> | UseSetStateCallback<T>) => void];

import { useSetState } from "@mantine/hooks";

const [state, setState] = useSetState({
  name: '',
  email: '',
  age: 0
});

// Partial updates
setState({ name: 'John' }); // Only updates name
setState((current) => ({ age: current.age + 1 })); // Functional update

/**
 * Input state handler for form inputs
 * @param initialValue - Initial input value
 * @returns Tuple of current value and change handler
 */
function useInputState<T>(initialValue: T): UseInputStateReturnValue<T>;

type UseInputStateReturnValue<T> = [T, (event: React.ChangeEvent<HTMLInputElement> | T) => void];

import { useInputState } from "@mantine/hooks";

const [value, setValue] = useInputState('');

// Use with input
<input value={value} onChange={setValue} />

// Or set directly
setValue('new value');

/**
 * State with validation function and validity tracking
 * @param initialValue - Initial value
 * @param validation - Validation function returning boolean
 * @returns Tuple of [value, isValid] and setter
 */
function useValidatedState<T>(initialValue: T, validation: (value: T) => boolean): UseValidatedStateReturnValue<T>;

type UseValidatedStateValue<T> = [T, boolean];
type UseValidatedStateReturnValue<T> = [UseValidatedStateValue<T>, (value: T) => void];

/**
 * Queue data structure with size limit and operations
 * @param options - Queue configuration
 * @returns Queue object with state and operations
 */
function useQueue<T>(options: UseQueueOptions<T>): UseQueueReturnValue<T>;

interface UseQueueOptions<T> {
  initialValues?: T[];
  limit: number;
}

interface UseQueueReturnValue<T> {
  queue: T[];
  state: T[];
  add: (...items: T[]) => void;
  update: (fn: (state: T[]) => T[]) => void;
  cleanQueue: () => void;
}

/**
 * State with history tracking and navigation
 * @param initialValue - Initial state value
 * @returns Tuple of history state and navigation handlers
 */
function useStateHistory<T>(initialValue: T): UseStateHistoryReturnValue<T>;

interface UseStateHistoryHandlers<T> {
  set: (value: T) => void;
  back: () => void;
  forward: () => void;
  go: (index: number) => void;
}

interface UseStateHistoryValue<T> {
  current: T;
  previous: T[];
  next: T[];
}

type UseStateHistoryReturnValue<T> = [UseStateHistoryValue<T>, UseStateHistoryHandlers<T>];

/**
 * Map data structure with reactive operations
 * @param initialValues - Initial map entries
 * @returns Enhanced Map with reactive methods
 */
function useMap<K, V>(initialValues?: Iterable<readonly [K, V]>): Map<K, V> & {
  set: (key: K, value: V) => void;
  setAll: (entries: Iterable<readonly [K, V]>) => void;
  remove: (key: K) => void;
  toggle: (key: K, value?: V) => void;
  reset: () => void;
};

/**
 * Set data structure with reactive operations
 * @param initialValues - Initial set values
 * @returns Enhanced Set with reactive methods
 */
function useSet<T>(initialValues?: Iterable<T>): Set<T> & {
  add: (value: T) => void;
  addAll: (values: Iterable<T>) => void;
  remove: (value: T) => void;
  toggle: (value: T) => void;
  reset: () => void;
};