feat(useCounter): add useCounter hook

Author: JeongHwan-dev

src/hooks/useCounter/index.ts

@@ -0,0 +1 @@
+export { useCounter } from './useCounter.ts';

src/hooks/useCounter/ko/useCounter.md

@@ -0,0 +1,129 @@
+# useCounter
+
+`useCounter`는 증가, 감소, 초기화 기능을 갖춘 숫자형 카운터 상태를 관리하는 리액트 훅이에요. 선택적으로 최소값과 최대값을 제공하여 카운터의 범위를 제한할 수 있어요.
+
+## 인터페이스
+
+```ts
+function useCounter(options?: UseCounterOptions): UseCounterReturn;
+
+type UseCounterOptions = {
+  /** 카운터의 초기값. 기본값은 0. */
+  initialValue?: number;
+  /** 카운터가 도달할 수 있는 최소값. 제공되지 않으면 하한이 없어요. */
+  min?: number;
+  /** 카운터가 도달할 수 있는 최대값. 제공되지 않으면 상한이 없어요. */
+  max?: number;
+  /** 증가 또는 감소할 값. 기본값은 1. */
+  step?: number;
+};
+
+type UseCounterReturn = {
+  /** 현재 카운터 값 */
+  count: number;
+  /** 단계 크기만큼 카운터 증가 */
+  increment: () => void;
+  /** 단계 크기만큼 카운터 감소 */
+  decrement: () => void;
+  /** 카운터를 초기값으로 재설정 */
+  reset: () => void;
+  /** 카운터를 제약 조건 내에서 특정 값으로 설정 */
+  setCount: (value: number | ((prev: number) => number)) => void;
+};
+```
+
+### 파라미터
+
+<Interface
+  name="options"
+  type="UseCounterOptions"
+  description="카운터의 선택적 설정이에요."
+  :nested="[
+    {
+      name: 'initialValue',
+      type: 'number',
+      description: '카운터의 초기값. 기본값은 0이에요.',
+    },
+    {
+      name: 'min',
+      type: 'number',
+      description: '카운터가 도달할 수 있는 최소값. 제공되지 않으면 하한이 없어요.',
+    },
+    {
+      name: 'max',
+      type: 'number',
+      description: '카운터가 도달할 수 있는 최대값. 제공되지 않으면 상한이 없어요.',
+    },
+    {
+      name: 'step',
+      type: 'number',
+      description: '증가 또는 감소할 값. 기본값은 1이에요.',
+    }
+  ]"
+/>
+
+### 반환 값
+
+<Interface
+  name=""
+  type="UseCounterReturn"
+  description="카운트 값과 제어 함수를 포함하는 객체에요."
+  :nested="[
+    {
+      name: 'count',
+      type: 'number',
+      description: '현재 카운트 값이에요.',
+    },
+    {
+      name: 'increment',
+      type: '() => void',
+      description: '단계 크기만큼 카운터 증가해요.',
+    },
+    {
+      name: 'decrement',
+      type: '() => void',
+      description: '단계 크기만큼 카운터 감소해요.',
+    },
+    {
+      name: 'reset',
+      type: '() => void',
+      description: '카운터를 초기값으로 재설정해요.',
+    },
+    {
+      name: 'setCount',
+      type: '(value: number | ((prev: number) => number)) => void',
+      description: '카운터를 제약 조건 내에서 특정 값으로 설정해요.',
+    }
+  ]"
+/>
+
+## 예시
+
+```tsx
+import { useCounter } from 'react-simplikit';
+
+function ShoppingCart() {
+  const { count, increment, decrement, reset } = useCounter({
+    initialValue: 1,
+    min: 1,
+    max: 10,
+  });
+
+  return (
+    <div>
+      <span>수량: {count}</span>
+      <button type="button" onClick={decrement}>-</button>
+      <button type="button" onClick={increment}>+</button>
+      <button type="button" onClick={reset}>초기화</button>
+    </div>
+  );
+}
+```
+
+## 제약 조건
+
+이 훅은 카운터가 지정된 범위 내에서 유지되도록 자동으로 보장해요:
+
+- 값이 `max`보다 커지면 자동으로 `max` 값으로 제한돼요.
+- 값이 `min`보다 작아지면 자동으로 `min` 값으로 제한돼요.
+- `setCount`를 사용할 때 범위를 벗어나는 값은 자동으로 가장 가까운 경계값으로 조정돼요.

src/hooks/useCounter/useCounter.md

@@ -0,0 +1,129 @@
+# useCounter
+
+`useCounter` is a React hook that manages a numeric counter state with increment, decrement, and reset capabilities. Optionally, you can provide minimum and maximum values to constrain the counter's range.
+
+## Interface
+
+```ts
+function useCounter(options?: UseCounterOptions): UseCounterReturn;
+
+type UseCounterOptions = {
+  /** Initial value for the counter. Defaults to 0. */
+  initialValue?: number;
+  /** Minimum value the counter can reach. If not provided, there is no lower limit. */
+  min?: number;
+  /** Maximum value the counter can reach. If not provided, there is no upper limit. */
+  max?: number;
+  /** Value to increment or decrement by. Defaults to 1. */
+  step?: number;
+};
+
+type UseCounterReturn = {
+  /** Current count value */
+  count: number;
+  /** Increment the counter by the step amount */
+  increment: () => void;
+  /** Decrement the counter by the step amount */
+  decrement: () => void;
+  /** Reset the counter to its initial value */
+  reset: () => void;
+  /** Set the counter to a specific value within constraints */
+  setCount: (value: number | ((prev: number) => number)) => void;
+};
+```
+
+### Parameters
+
+<Interface
+  name="options"
+  type="UseCounterOptions"
+  description="Optional configuration for the counter."
+  :nested="[
+    {
+      name: 'initialValue',
+      type: 'number',
+      description: 'Initial value for the counter. Defaults to 0.',
+    },
+    {
+      name: 'min',
+      type: 'number',
+      description: 'Minimum value the counter can reach. If not provided, there is no lower limit.',
+    },
+    {
+      name: 'max',
+      type: 'number',
+      description: 'Maximum value the counter can reach. If not provided, there is no upper limit.',
+    },
+    {
+      name: 'step',
+      type: 'number',
+      description: 'Value to increment or decrement by. Defaults to 1.',
+    }
+  ]"
+/>
+
+### Return Value
+
+<Interface
+  name=""
+  type="UseCounterReturn"
+  description="An object with count value and control functions."
+  :nested="[
+    {
+      name: 'count',
+      type: 'number',
+      description: 'Current count value.',
+    },
+    {
+      name: 'increment',
+      type: '() => void',
+      description: 'Increment the counter by the step amount.',
+    },
+    {
+      name: 'decrement',
+      type: '() => void',
+      description: 'Decrement the counter by the step amount.',
+    },
+    {
+      name: 'reset',
+      type: '() => void',
+      description: 'Reset the counter to its initial value.',
+    },
+    {
+      name: 'setCount',
+      type: '(value: number | ((prev: number) => number)) => void',
+      description: 'Set the counter to a specific value within constraints.',
+    }
+  ]"
+/>
+
+## Example
+
+```tsx
+import { useCounter } from 'react-simplikit';
+
+function ShoppingCart() {
+  const { count, increment, decrement, reset } = useCounter({
+    initialValue: 1,
+    min: 1,
+    max: 10,
+  });
+
+  return (
+    <div>
+      <span>Quantity: {count}</span>
+      <button type="button" onClick={decrement}>-</button>
+      <button type="button" onClick={increment}>+</button>
+      <button type="button" onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
+## Constraints
+
+The hook automatically ensures that the counter stays within the specified bounds:
+
+- When incrementing beyond `max`, the value will stay at `max`
+- When decrementing below `min`, the value will stay at `min`
+- When using `setCount`, any value outside the bounds will be adjusted to the nearest boundary