import { Canvas, Meta } from "@storybook/blocks";
import { FunctionArgument, FunctionArguments } from "vibe-storybook-components";
import * as UseDebounceEventStories from "./useDebounceEvent.stories";

<Meta of={UseDebounceEventStories} />

# useDebounceEvent

- [Overview](#overview)
- [Arguments](#arguments)
- [Returns](#returns)
- [Usage](#usage)
- [Use cases and examples](#use-cases-and-examples)
- [Feedback](#feedback)

## Overview

This hook generates an easy to use debounced value updater.

<Canvas of={UseDebounceEventStories.Overview} />

## Arguments

<FunctionArguments>
  <FunctionArgument name="options" type="Object">
    <FunctionArgument name="trim" type="boolean" description="Whether to trim the value or not." default="false" />
    <FunctionArgument
      name="onChange"
      type="(value: string) => void"
      description="Callback function to execute on changes."
      default="() => null"
    />
    <FunctionArgument
      name="delay"
      type="number"
      description="The amount of time (in ms) to delay the value's update."
      default="0"
    />
    <FunctionArgument name="initialStateValue" type="any" description="The initial value." />
  </FunctionArgument>
</FunctionArguments>

## Returns

<FunctionArguments>
  <FunctionArgument name="result" type="Object">
    <FunctionArgument name="inputValue" type="any" description="The hook's value." />
    <FunctionArgument
      name="onEventChanged"
      type="(event: Event) => void"
      description={
        <>
          A wrapper around the passed <code>onChange</code> function.
        </>
      }
    />
    <FunctionArgument name="clearValue" type="() => void" description="Clears the current value." />
    <FunctionArgument name="updateValue" type="(value: any) => void" description="Updates the current value." />
  </FunctionArgument>
</FunctionArguments>

## Usage

<UsageGuidelines guidelines={["Use this hook when you need to debounce value updates (for example, text inputs)."]} />

## Use cases and examples

### Passing an initial value

<Canvas of={UseDebounceEventStories.PassingAnInitialValue} />

### Passing an `onChange` handler

<Canvas of={UseDebounceEventStories.PassingAnOnChangeHandler} />

### Trimming the value

<Canvas of={UseDebounceEventStories.WithTrim} />