@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/react/suspense.md

@@ -0,0 +1,218 @@
+---
+title: Suspense & Streaming
+source: https://react.dev/reference/react/Suspense
+fetched: 2026-05-18
+category: suspense
+react_version: 19
+---
+
+## 개요
+
+`<Suspense>`는 자식 컴포넌트가 로딩 완료될 때까지 fallback UI를 표시하는 React 컴포넌트.
+
+```js
+<Suspense fallback={<Loading />}>
+  <SomeComponent />
+</Suspense>
+```
+
+---
+
+## Props
+
+| Prop | 설명 |
+|------|------|
+| `children` | 렌더링할 실제 UI. suspend 시 fallback으로 전환 |
+| `fallback` | 로딩 중 대체 UI (스피너, 스켈레톤 등 경량 노드) |
+
+---
+
+## 핵심 Caveats
+
+1. **State 리셋**: 마운트 전 suspend된 렌더의 state는 보존되지 않음 — 컴포넌트 로드 시 처음부터 재시도
+2. **Fallback 재표시**: Suspense가 콘텐츠를 표시하다가 다시 suspend되면 fallback 재표시 (단, `startTransition`/`useDeferredValue`로 발생한 업데이트는 예외)
+3. **Layout Effects 정리**: 콘텐츠 숨김 시 layout Effect 정리, 다시 표시 시 재실행
+4. **Streaming 내장**: Streaming Server Rendering + Selective Hydration 최적화 포함
+
+---
+
+## Suspense를 트리거하는 데이터 소스
+
+- Relay, Next.js 등 Suspense 지원 프레임워크
+- `lazy()`로 지연 로딩된 컴포넌트
+- `use()`로 읽는 캐시된 Promise
+
+> ⚠️ Effect나 이벤트 핸들러 내부의 데이터 페칭은 감지하지 못함.
+
+---
+
+## 사용 패턴
+
+### 1. 기본 fallback 표시
+
+```js
+<Suspense fallback={<Loading />}>
+  <Albums />
+</Suspense>
+```
+
+### 2. 함께 나타나는 콘텐츠 그룹
+
+```js
+<Suspense fallback={<Loading />}>
+  <Biography />
+  <Panel>
+    <Albums />
+  </Panel>
+</Suspense>
+```
+
+> 두 컴포넌트가 서로 기다려 함께 나타남.
+
+### 3. 중첩 Suspense로 순차 표시 (Streaming)
+
+```js
+<Suspense fallback={<BigSpinner />}>
+  <Biography />
+  <Suspense fallback={<AlbumsGlimmer />}>
+    <Panel>
+      <Albums />
+    </Panel>
+  </Suspense>
+</Suspense>
+```
+
+**순서:**
+1. Biography 로딩 중 → `BigSpinner` 표시
+2. Biography 완료 → `AlbumsGlimmer` 표시
+3. Albums 완료 → 최종 UI
+
+### 4. 새 콘텐츠 로딩 중 이전 콘텐츠 유지 (`useDeferredValue`)
+
+```js
+import { Suspense, useState, useDeferredValue } from 'react';
+
+export default function App() {
+  const [query, setQuery] = useState('');
+  const deferredQuery = useDeferredValue(query);
+  const isStale = query !== deferredQuery;
+
+  return (
+    <>
+      <label>
+        Search albums:
+        <input value={query} onChange={e => setQuery(e.target.value)} />
+      </label>
+      <Suspense fallback={<h2>Loading...</h2>}>
+        <div style={{ opacity: isStale ? 0.5 : 1 }}>
+          <SearchResults query={deferredQuery} />
+        </div>
+      </Suspense>
+    </>
+  );
+}
+```
+
+입력은 즉시 업데이트, 이전 결과는 opacity 0.5로 표시되다가 새 결과 로드 시 전환.
+
+### 5. 표시 중인 콘텐츠가 fallback으로 교체되지 않도록 (`startTransition`)
+
+```js
+import { useTransition } from 'react';
+
+function Router() {
+  const [page, setPage] = useState('/');
+  const [isPending, startTransition] = useTransition();
+
+  function navigate(url) {
+    startTransition(() => {
+      setPage(url);
+    });
+  }
+
+  return (
+    <Layout isPending={isPending}>
+      {content}
+    </Layout>
+  );
+}
+```
+
+### 6. 네비게이션 시 Suspense 경계 리셋 (`key`)
+
+```js
+<ProfilePage key={queryParams.id} />
+```
+
+> `key`가 변경되면 중첩된 모든 Suspense 경계가 리셋됨.
+
+### 7. 클라이언트 전용 콘텐츠
+
+```js
+<Suspense fallback={<Loading />}>
+  <Chat />
+</Suspense>
+
+function Chat() {
+  if (typeof window === 'undefined') {
+    throw Error('Chat should only render on the client.');
+  }
+  // ...
+}
+```
+
+서버 HTML에서는 fallback, 클라이언트에서 컴포넌트로 교체.
+
+---
+
+## 완전한 예시
+
+```js
+import { Suspense, useState, useTransition } from 'react';
+
+export default function ArtistPage({ artist }) {
+  return (
+    <>
+      <h1>{artist.name}</h1>
+      <Suspense fallback={<LoadingBio />}>
+        <Biography artistId={artist.id} />
+      </Suspense>
+      <Suspense fallback={<LoadingAlbums />}>
+        <Albums artistId={artist.id} />
+      </Suspense>
+    </>
+  );
+}
+
+function Biography({ artistId }) {
+  const bio = use(fetchData(`/${artistId}/bio`));
+  return <section><p>{bio}</p></section>;
+}
+
+function Albums({ artistId }) {
+  const albums = use(fetchData(`/${artistId}/albums`));
+  return (
+    <ul>
+      {albums.map(album => (
+        <li key={album.id}>{album.title} ({album.year})</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Troubleshooting
+
+**업데이트 시 원치 않는 fallback 방지:**
+
+```js
+function handleNextPageClick() {
+  startTransition(() => {
+    setCurrentPage(currentPage + 1);
+  });
+}
+```
+
+> `startTransition`으로 긴급하지 않은 업데이트 표시 → 충분한 데이터가 로드될 때까지 fallback 표시 지연. 긴급 업데이트는 여전히 즉시 fallback 표시.

package/assets/dev-guide/fe/sources/react/use-action-state.md

@@ -0,0 +1,123 @@
+---
+title: useActionState
+source: https://react.dev/reference/react/useActionState
+fetched: 2026-05-18
+category: api
+react_version: 19
+---
+
+## 개요
+
+Action(비동기 작업)의 결과로 state를 관리하는 Hook. 폼 제출 및 비동기 작업에 특히 유용.
+
+---
+
+## 시그니처
+
+```js
+const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState, permalink?);
+```
+
+### Parameters
+- `reducerAction`: `(previousState, actionPayload) => newState` — 사이드 이펙트 수행 후 새 state 반환
+- `initialState`: 초기 state (첫 dispatch 이후 무시됨)
+- `permalink?` (optional): Server Components 점진적 향상을 위한 URL
+
+### Returns
+1. **현재 state** — 초기엔 `initialState`, 이후엔 `reducerAction` 반환값
+2. **`dispatchAction`** — action을 트리거하는 함수
+3. **`isPending`** — action 처리 중 여부 boolean
+
+---
+
+## 사용 패턴
+
+### 기본 사용
+
+```js
+const [count, dispatchAction, isPending] = useActionState(
+  async (prevCount) => await addToCart(prevCount),
+  0
+);
+
+function handleClick() {
+  startTransition(() => {
+    dispatchAction();
+  });
+}
+```
+
+### 여러 액션 타입 처리
+
+```js
+async function updateCartAction(prevCount, actionPayload) {
+  switch (actionPayload.type) {
+    case 'ADD':
+      return await addToCart(prevCount);
+    case 'REMOVE':
+      return await removeFromCart(prevCount);
+  }
+  return prevCount;
+}
+
+const [count, dispatchAction, isPending] = useActionState(updateCartAction, 0);
+dispatchAction({ type: 'ADD' });
+```
+
+### Form Action과 함께 사용
+
+```js
+<form action={dispatchAction}>
+  <input name="quantity" type="number" />
+  <button type="submit">Add to Cart</button>
+</form>
+```
+
+> form과 함께 사용 시 `reducerAction`은 `(previousState, formData)`를 받음.
+
+### useOptimistic과 조합
+
+```js
+const [count, dispatchAction, isPending] = useActionState(updateCartAction, 0);
+const [optimisticCount, setOptimisticCount] = useOptimistic(count);
+
+function handleAdd() {
+  startTransition(() => {
+    setOptimisticCount(c => c + 1);
+    dispatchAction({ type: 'ADD' });
+  });
+}
+```
+
+### 에러 처리
+
+```js
+async function updateCartAction(prevState, quantity) {
+  const result = await addToCart(prevState.count, quantity);
+  if (result.error) {
+    return { ...prevState, error: result.error };
+  }
+  return { count: result.count, error: null };
+}
+```
+
+---
+
+## 주요 Caveats
+
+- 최상위에서만 호출 (loop/조건문 내 불가)
+- `dispatchAction` 호출은 순서대로 큐에 쌓여 실행됨
+- **반드시 Transition 내에서 호출**: `startTransition` 또는 Action prop (form은 자동 래핑)
+- `dispatchAction`은 안정적 참조 → Effect 의존성 트리거 안 함
+- Server 사용 시 `initialState`와 `actionPayload`는 직렬화 가능해야 함
+- `reducerAction`에서 throw 시 큐 취소 + Error Boundary 트리거 → throw 대신 에러 state 반환 권장
+
+---
+
+## Troubleshooting
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| `isPending`이 업데이트 안 됨 | `startTransition` 누락 | `dispatchAction`을 `startTransition` 안에서 호출 |
+| form data 못 읽음 | 두 번째 파라미터가 `formData` | `(prevState, formData)` 시그니처 확인 |
+| Action이 스킵됨 | `reducerAction`에서 throw | throw 대신 에러 state 반환 |

package/assets/dev-guide/fe/sources/react/use-form-status.md

@@ -0,0 +1,158 @@
+---
+title: useFormStatus / form action={} 패턴
+source: https://react.dev/reference/react-dom/hooks/useFormStatus
+fetched: 2026-05-18
+category: api
+react_version: 19
+---
+
+## 개요
+
+`useFormStatus`는 가장 가까운 부모 `<form>`의 제출 상태 정보를 제공하는 Hook.
+
+```js
+const { pending, data, method, action } = useFormStatus();
+```
+
+---
+
+## 반환값
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `pending` | `boolean` | 부모 `<form>` 제출 중이면 `true` |
+| `data` | `FormData \| null` | 제출 중인 폼 데이터; 없으면 `null` |
+| `method` | `string` | HTTP 메서드 (`'get'` \| `'post'`, 기본 `'get'`) |
+| `action` | `function \| null` | 부모 `<form>`의 `action` prop 함수; URI이거나 없으면 `null` |
+
+---
+
+## 핵심 제약 (Critical)
+
+> `useFormStatus`를 호출하는 컴포넌트는 반드시 `<form>` **내부**에 렌더링되어야 함.
+> `<form>`을 렌더링하는 **같은 컴포넌트**에서는 호출 불가.
+
+❌ 잘못된 패턴:
+```js
+function Form() {
+  const { pending } = useFormStatus(); // 🚩 pending은 절대 true가 되지 않음
+  return <form action={submit}></form>;
+}
+```
+
+✅ 올바른 패턴:
+```js
+function Submit() {
+  const { pending } = useFormStatus(); // ✅
+  return <button disabled={pending}>...</button>;
+}
+
+function Form() {
+  return (
+    <form action={submit}>
+      <Submit />
+    </form>
+  );
+}
+```
+
+---
+
+## 사용 패턴
+
+### 제출 중 버튼 비활성화
+
+```js
+import { useFormStatus } from "react-dom";
+import action from './actions';
+
+function Submit() {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? "Submitting..." : "Submit"}
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <form action={action}>
+      <Submit />
+    </form>
+  );
+}
+```
+
+### 제출 중인 폼 데이터 표시
+
+```js
+import { useFormStatus } from 'react-dom';
+
+export default function UsernameForm() {
+  const { pending, data } = useFormStatus();
+
+  return (
+    <div>
+      <h3>Request a Username: </h3>
+      <input type="text" name="username" disabled={pending} />
+      <button type="submit" disabled={pending}>Submit</button>
+      <p>{data ? `Requesting ${data?.get("username")}...` : ''}</p>
+    </div>
+  );
+}
+```
+
+```js
+import UsernameForm from './UsernameForm';
+import { submitForm } from "./actions.js";
+import { useRef } from 'react';
+
+export default function App() {
+  const ref = useRef(null);
+  return (
+    <form
+      ref={ref}
+      action={async (formData) => {
+        await submitForm(formData);
+        ref.current.reset();
+      }}
+    >
+      <UsernameForm />
+    </form>
+  );
+}
+```
+
+---
+
+## form action={} 패턴
+
+React 19에서 `<form>`의 `action` prop에 함수를 직접 전달:
+
+```js
+// Server Function을 직접 action으로 전달
+import { updateName } from './actions'; // "use server" 함수
+
+function UpdateName() {
+  return (
+    <form action={updateName}>
+      <input type="text" name="name" />
+      <button type="submit">Update</button>
+    </form>
+  );
+}
+```
+
+- 성공 시 React가 자동으로 폼 리셋
+- `useActionState`와 조합 시 pending state, 이전 응답 접근 가능
+- JavaScript 로드 전에도 동작하는 점진적 향상 지원
+
+---
+
+## Troubleshooting
+
+**`status.pending`이 항상 `false`인 경우:**
+1. `useFormStatus` 호출 컴포넌트가 `<form>` 자식으로 렌더링되는지 확인
+2. `<form>`을 렌더링하는 같은 컴포넌트에서 호출하지 않았는지 확인
+3. 컴포넌트가 `<form>` 경계 내부에 있는지 확인

package/assets/dev-guide/fe/sources/react/use-hook.md

@@ -0,0 +1,153 @@
+---
+title: use() Hook
+source: https://react.dev/reference/react/use
+fetched: 2026-05-18
+category: api
+react_version: 19
+---
+
+## 개요
+
+`use`는 Promise 또는 Context 값을 읽을 수 있는 React API.
+
+```js
+const value = use(resource);
+```
+
+**일반 Hook과의 차이점:**
+- `if`, `for` 등 조건문·반복문 안에서도 호출 가능
+- Component 또는 Hook 내부에서만 호출 가능
+
+---
+
+## 시그니처
+
+### `use(resource)`
+
+#### Parameters
+- `resource`: 읽을 데이터 소스. Promise 또는 Context.
+
+#### Returns
+Promise의 resolved 값 또는 Context 값.
+
+#### Caveats
+1. Component 또는 Hook 안에서만 호출
+2. Server Component에서는 `use` 대신 `async/await` 선호
+3. Client Component에서 Promise를 생성하면 렌더마다 재생성됨 → Server Component에서 생성해 props로 전달
+
+---
+
+## 사용 패턴
+
+### Context 읽기
+
+```js
+import { use } from 'react';
+
+function Button() {
+  const theme = use(ThemeContext);
+  // ...
+}
+```
+
+**조건부 호출 (일반 Hook은 불가, use는 가능):**
+```js
+function HorizontalRule({ show }) {
+  if (show) {
+    const theme = use(ThemeContext);
+    return <hr className={theme} />;
+  }
+  return false;
+}
+```
+
+> `use(context)`는 컴포넌트 자신이 아닌 가장 가까운 상위 Provider를 탐색.
+
+---
+
+### 서버→클라이언트 데이터 스트리밍
+
+**Server Component:**
+```js
+import { fetchMessage } from './lib.js';
+import { Message } from './message.js';
+
+export default function App() {
+  const messagePromise = fetchMessage();
+  return (
+    <Suspense fallback={<p>waiting for message...</p>}>
+      <Message messagePromise={messagePromise} />
+    </Suspense>
+  );
+}
+```
+
+**Client Component:**
+```js
+// message.js
+'use client';
+
+import { use } from 'react';
+
+export function Message({ messagePromise }) {
+  const messageContent = use(messagePromise);
+  return <p>Here is the message: {messageContent}</p>;
+}
+```
+
+> Promise resolved 값은 직렬화 가능해야 함 (함수 전달 불가).
+
+---
+
+### 거부된 Promise 처리
+
+**Error Boundary 사용:**
+```js
+import { use, Suspense } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+
+export function MessageContainer({ messagePromise }) {
+  return (
+    <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
+      <Suspense fallback={<p>⌛Downloading message...</p>}>
+        <Message messagePromise={messagePromise} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+**Promise.catch 사용:**
+```js
+const messagePromise = new Promise((resolve, reject) => {
+  reject();
+}).catch(() => {
+  return "no new message found.";
+});
+```
+
+> `use`는 try-catch 블록 안에서 호출 불가. Error Boundary 또는 Promise.catch 사용.
+
+---
+
+## Troubleshooting
+
+**"Suspense Exception: This is not a real error!"**
+- `use`를 React Component/Hook 외부에서 호출했거나
+- try-catch 블록 안에서 호출한 경우
+
+❌ 잘못된 예:
+```jsx
+function MessageComponent({ messagePromise }) {
+  function download() {
+    const message = use(messagePromise); // 중첩 함수 내부 → 오류
+  }
+}
+```
+
+✅ 올바른 예:
+```jsx
+function MessageComponent({ messagePromise }) {
+  const message = use(messagePromise); // 컴포넌트 최상위 → 정상
+}
+```