feat(core/hooks): add 'useList' hook (#341)

Author: sukvvon

.changeset/swift-birds-glow.md

@@ -0,0 +1,5 @@
+---
+'react-simplikit': patch
+---
+
+feat(core/hooks): add 'useList' hook

packages/core/src/hooks/useList/index.ts

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

packages/core/src/hooks/useList/ko/useList.md

@@ -0,0 +1,55 @@
+# useList
+
+리액트 훅으로, 배열을 상태로 관리해요. 효율적인 상태 관리를 제공하고 안정적인 액션 함수를 제공해요.
+
+## 인터페이스
+
+```ts
+function useList<T>(initialState?: T[]): UseListReturn<T>;
+```
+
+### 파라미터
+
+<Interface
+  name="initialState"
+  type="T[]"
+  description="초기 배열 상태예요. 기본값은 빈 배열이에요."
+/>
+
+### 반환 값
+
+튜플 `[list, actions]`를 반환해요.
+
+<Interface name="list" type="ReadonlyArray<T>" description="현재 배열 상태예요." />
+
+<Interface name="actions.push" type="(value: T) => void" description="리스트의 끝에 값을 추가해요." />
+<Interface name="actions.insertAt" type="(index: number, value: T) => void" description="지정된 인덱스에 값을 삽입해요." />
+<Interface name="actions.updateAt" type="(index: number, value: T) => void" description="지정된 인덱스의 값을 업데이트해요." />
+<Interface name="actions.removeAt" type="(index: number) => void" description="지정된 인덱스의 값을 제거해요." />
+<Interface name="actions.setAll" type="(values: T[]) => void" description="전체 리스트를 새 배열로 교체해요." />
+<Interface name="actions.reset" type="() => void" description="리스트를 초기 상태로 되돌려요." />
+
+## 예시
+
+```tsx
+import { useList } from 'react-simplikit';
+
+function TodoList() {
+  const [todos, actions] = useList<string>(['Buy milk', 'Walk the dog']);
+
+  return (
+    <div>
+      <ul>
+        {todos.map((todo, index) => (
+          <li key={index}>
+            {todo}
+            <button onClick={() => actions.removeAt(index)}>Delete</button>
+          </li>
+        ))}
+      </ul>
+      <button onClick={() => actions.push('New todo')}>Add</button>
+      <button onClick={() => actions.reset()}>Reset</button>
+    </div>
+  );
+}
+```

packages/core/src/hooks/useList/useList.md

@@ -0,0 +1,55 @@
+# useList
+
+A React hook that manages an array as state. Provides efficient state management and stable action functions.
+
+## Interface
+
+```ts
+function useList<T>(initialState?: T[]): UseListReturn<T>;
+```
+
+### Parameters
+
+<Interface
+  name="initialState"
+  type="T[]"
+  description="Initial array state. Defaults to an empty array."
+/>
+
+### Return Value
+
+Returns a tuple `[list, actions]`.
+
+<Interface name="list" type="ReadonlyArray<T>" description="The current array state." />
+
+<Interface name="actions.push" type="(value: T) => void" description="Appends a value to the end of the list." />
+<Interface name="actions.insertAt" type="(index: number, value: T) => void" description="Inserts a value at the specified index." />
+<Interface name="actions.updateAt" type="(index: number, value: T) => void" description="Updates the value at the specified index." />
+<Interface name="actions.removeAt" type="(index: number) => void" description="Removes the value at the specified index." />
+<Interface name="actions.setAll" type="(values: T[]) => void" description="Replaces the entire list with a new array." />
+<Interface name="actions.reset" type="() => void" description="Resets the list to its initial state." />
+
+## Example
+
+```tsx
+import { useList } from 'react-simplikit';
+
+function TodoList() {
+  const [todos, actions] = useList<string>(['Buy milk', 'Walk the dog']);
+
+  return (
+    <div>
+      <ul>
+        {todos.map((todo, index) => (
+          <li key={index}>
+            {todo}
+            <button onClick={() => actions.removeAt(index)}>Delete</button>
+          </li>
+        ))}
+      </ul>
+      <button onClick={() => actions.push('New todo')}>Add</button>
+      <button onClick={() => actions.reset()}>Reset</button>
+    </div>
+  );
+}
+```

packages/core/src/hooks/useList/useList.spec.ts

@@ -0,0 +1,188 @@
+import { act } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { renderHookSSR } from '../../_internal/test-utils/renderHookSSR.tsx';
+
+import { useList } from './useList.ts';
+
+describe('useList', () => {
+  it('is safe on server side rendering', () => {
+    const result = renderHookSSR.serverOnly(() => useList(['a', 'b']));
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+  });
+
+  it('should initialize with an array', async () => {
+    const { result } = await renderHookSSR(() => useList(['a', 'b']));
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+  });
+
+  it('should initialize with an empty array when no arguments provided', async () => {
+    const { result } = await renderHookSSR(() => useList());
+
+    expect(result.current[0]).toEqual([]);
+  });
+
+  it('should push a value to the end of the list', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.push('b');
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+  });
+
+  it('should insert a value at the specified index', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.insertAt(1, 'b');
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should insert at the beginning when index is 0', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['b', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.insertAt(0, 'a');
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should update a value at the specified index', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.updateAt(1, 'x');
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'x', 'c']);
+  });
+
+  it('should remove a value at the specified index', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.removeAt(1);
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'c']);
+  });
+
+  it('should remove the first item', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.removeAt(0);
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['b', 'c']);
+  });
+
+  it('should remove the last item', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b', 'c']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.removeAt(2);
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+  });
+
+  it('should replace all values with setAll', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.setAll(['x', 'y', 'z']);
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['x', 'y', 'z']);
+  });
+
+  it('should reset the list to its initial state', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a', 'b']));
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.push('c');
+      actions.removeAt(0);
+      rerender();
+    });
+
+    expect(result.current[0]).not.toEqual(['a', 'b']);
+
+    await act(async () => {
+      actions.reset();
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+  });
+
+  it('should reset to empty array when initialized with empty array', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList<string>());
+    const [, actions] = result.current;
+
+    await act(async () => {
+      actions.push('a');
+      actions.push('b');
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual(['a', 'b']);
+
+    await act(async () => {
+      actions.reset();
+      rerender();
+    });
+
+    expect(result.current[0]).toEqual([]);
+  });
+
+  it('should create a new array reference when values change', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList(['a']));
+    const [originalRef] = result.current;
+
+    await act(async () => {
+      result.current[1].push('b');
+      rerender();
+    });
+
+    expect(originalRef).not.toBe(result.current[0]);
+  });
+
+  it('should maintain stable actions reference after list changes', async () => {
+    const { result, rerender } = await renderHookSSR(() => useList<string>());
+    const [, originalActions] = result.current;
+
+    expect(result.current[1]).toBe(originalActions);
+
+    await act(async () => {
+      originalActions.push('a');
+      rerender();
+    });
+
+    expect(result.current[1]).toBe(originalActions);
+  });
+});