@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/fe/sources/toss-ff/readability-magic-number.md

@@ -0,0 +1,53 @@
+---
+title: 매직 넘버에 이름 붙이기
+source: https://frontend-fundamentals.com/code-quality/code/examples/magic-number-readability.html
+fetched: 2026-05-18
+principle: readability
+---
+
+# 매직 넘버에 이름 붙이기
+
+**매직 넘버**(Magic Number)란 정확한 뜻을 밝히지 않고 소스 코드 안에 직접 숫자 값을 넣는 것을 말해요.
+
+예를 들어, 찾을 수 없음(Not Found)을 나타내는 HTTP 상태 코드로 `404` 값을 바로 사용하는 것이나,
+하루를 나타내는 `86400`초를 그대로 사용하는 것이 있어요.
+
+## 📝 코드 예시
+
+다음 코드는 좋아요 버튼을 눌렀을 때 좋아요 개수를 새로 내려받는 함수예요.
+
+```typescript
+async function onLikeClick() {
+  await postLike(url);
+  await delay(300);
+  await refetchPostLike();
+}
+```
+
+## 👃 코드 냄새 맡아보기
+
+### 가독성
+
+이 코드는 `delay` 함수에 전달된 `300`이라고 하는 값이 어떤 맥락으로 쓰였는지 알 수 없어요.
+
+- 애니메이션이 완료될 때까지 기다리는 걸까?
+- 좋아요 반영에 시간이 걸려서 기다리는 걸까?
+- 테스트 코드였는데, 깜빡하고 안 지운 걸까?
+
+## ✏️ 개선해보기
+
+숫자 `300`의 맥락을 정확하게 표시하기 위해서 상수 `ANIMATION_DELAY_MS`로 선언할 수 있어요.
+
+```typescript
+const ANIMATION_DELAY_MS = 300;
+
+async function onLikeClick() {
+  await postLike(url);
+  await delay(ANIMATION_DELAY_MS);
+  await refetchPostLike();
+}
+```
+
+## 🔍 더 알아보기
+
+매직 넘버는 응집도 관점에서도 살펴볼 수 있어요. [매직 넘버 없애서 응집도 높이기](./cohesion-magic-number.md) 문서도 참고해 보세요.

package/assets/dev-guide/fe/sources/toss-ff/readability-submit-button.md

@@ -0,0 +1,73 @@
+---
+title: 같이 실행되지 않는 코드 분리하기
+source: https://frontend-fundamentals.com/code-quality/code/examples/submit-button.html
+fetched: 2026-05-18
+principle: readability
+---
+
+# 같이 실행되지 않는 코드 분리하기
+
+동시에 실행되지 않는 코드가 하나의 함수 또는 컴포넌트에 있으면, 동작을 한눈에 파악하기 어려워요.
+구현 부분에 많은 숫자의 분기가 들어가서, 어떤 역할을 하는지 이해하기 어렵기도 해요.
+
+## 📝 코드 예시
+
+다음 `<SubmitButton />` 컴포넌트는 사용자의 권한에 따라서 다르게 동작해요.
+
+- 사용자의 권한이 보기 전용(`"viewer"`)이면, 초대 버튼은 비활성화되어 있고, 애니메이션도 재생하지 않아요.
+- 사용자가 일반 사용자이면, 초대 버튼을 사용할 수 있고, 애니메이션도 재생해요.
+
+```tsx
+function SubmitButton() {
+  const isViewer = useRole() === "viewer";
+
+  useEffect(() => {
+    if (isViewer) {
+      return;
+    }
+    showButtonAnimation();
+  }, [isViewer]);
+
+  return isViewer ? (
+    <TextButton disabled>Submit</TextButton>
+  ) : (
+    <Button type="submit">Submit</Button>
+  );
+}
+```
+
+## 👃 코드 냄새 맡아보기
+
+### 가독성
+
+`<SubmitButton />` 컴포넌트에서는 사용자가 가질 수 있는 2가지의 권한 상태를 하나의 컴포넌트 안에서 한 번에 처리하고 있어요.
+그래서 코드를 읽는 사람이 한 번에 고려해야 하는 맥락이 많아요.
+
+동시에 실행되지 않는 코드가 교차되어서 나타나서 코드를 이해할 때 부담을 줘요.
+
+## ✏️ 개선해보기
+
+다음 코드는 사용자가 보기 전용 권한을 가질 때와 일반 사용자일 때를 완전히 나누어서 관리하도록 하는 코드예요.
+
+```tsx
+function SubmitButton() {
+  const isViewer = useRole() === "viewer";
+
+  return isViewer ? <ViewerSubmitButton /> : <AdminSubmitButton />;
+}
+
+function ViewerSubmitButton() {
+  return <TextButton disabled>Submit</TextButton>;
+}
+
+function AdminSubmitButton() {
+  useEffect(() => {
+    showButtonAnimation();
+  }, []);
+
+  return <Button type="submit">Submit</Button>;
+}
+```
+
+- `<SubmitButton />` 코드 곳곳에 있던 분기가 단 하나로 합쳐지면서, 분기가 줄어들었어요.
+- `<ViewerSubmitButton />`과 `<AdminSubmitButton />` 에서는 하나의 분기만 관리하기 때문에, 코드를 읽는 사람이 한 번에 고려해야 할 맥락이 적어요.

package/assets/dev-guide/fe/sources/toss-ff/readability-ternary-operator.md

@@ -0,0 +1,38 @@
+---
+title: 삼항 연산자 단순하게 하기
+source: https://frontend-fundamentals.com/code-quality/code/examples/ternary-operator.html
+fetched: 2026-05-18
+principle: readability
+---
+
+# 삼항 연산자 단순하게 하기
+
+삼항 연산자를 복잡하게 사용하면 조건의 구조가 명확하게 보이지 않아서 코드를 읽기 어려울 수 있어요.
+
+## 📝 코드 예시
+
+다음 코드는 `A조건`과 `B조건`에 따라서 `"BOTH"`, `"A"`, `"B"` 또는 `"NONE"` 중 하나를 `status`에 지정하는 코드예요.
+
+```typescript
+const status =
+  A조건 && B조건 ? "BOTH" : A조건 || B조건 ? (A조건 ? "A" : "B") : "NONE";
+```
+
+## 👃 코드 냄새 맡아보기
+
+### 가독성
+
+이 코드는 여러 삼항 연산자가 중첩되어 사용되어서, 정확하게 어떤 조건으로 값이 계산되는지 한눈에 파악하기 어려워요.
+
+## ✏️ 개선해보기
+
+다음과 같이 조건을 `if` 문으로 풀어서 사용하면 보다 명확하고 간단하게 조건을 드러낼 수 있어요.
+
+```typescript
+const status = (() => {
+  if (A조건 && B조건) return "BOTH";
+  if (A조건) return "A";
+  if (B조건) return "B";
+  return "NONE";
+})();
+```

package/assets/dev-guide/fe/sources/toss-ff/readability-use-page-state.md

@@ -0,0 +1,77 @@
+---
+title: 로직 종류에 따라 합쳐진 함수 쪼개기
+source: https://frontend-fundamentals.com/code-quality/code/examples/use-page-state-readability.html
+fetched: 2026-05-18
+principle: readability
+---
+
+# 로직 종류에 따라 합쳐진 함수 쪼개기
+
+쿼리 파라미터, 상태, API 호출과 같은 로직의 종류에 따라서 함수나 컴포넌트, Hook을 만들지 마세요. 한 번에 다루는 맥락의 종류가 많아져서 이해하기 힘들고 수정하기 어려운 코드가 돼요.
+
+## 📝 코드 예시
+
+다음 `usePageState()` Hook은 페이지 전체의 URL 쿼리 파라미터를 한 번에 관리해요.
+
+```typescript
+export function usePageState() {
+  const [query, setQuery] = useQueryParams({
+    cardId: NumberParam,
+    statementId: NumberParam,
+    dateFrom: DateParam,
+    dateTo: DateParam,
+    statusList: ArrayParam
+  });
+
+  return useMemo(
+    () => ({
+      values: {
+        cardId: query.cardId ?? undefined,
+        statementId: query.statementId ?? undefined,
+        dateFrom: query.dateFrom == null ? defaultDateFrom : moment(query.dateFrom),
+        dateTo: query.dateTo == null ? defaultDateTo : moment(query.dateTo),
+        statusList: query.statusList as StatementStatusType[] | undefined
+      },
+      controls: {
+        setCardId: (cardId: number) => setQuery({ cardId }, "replaceIn"),
+        setStatementId: (statementId: number) => setQuery({ statementId }, "replaceIn"),
+        setDateFrom: (date?: Moment) => setQuery({ dateFrom: date?.toDate() }, "replaceIn"),
+        setDateTo: (date?: Moment) => setQuery({ dateTo: date?.toDate() }, "replaceIn"),
+        setStatusList: (statusList?: StatementStatusType[]) => setQuery({ statusList }, "replaceIn")
+      }
+    }),
+    [query, setQuery]
+  );
+}
+```
+
+## 👃 코드 냄새 맡아보기
+
+### 가독성
+
+이 Hook이 가지고 있는 책임이 "페이지가 필요로 하는 모든 쿼리 파라미터를 관리하는 것" 임을 고려했을 때, 이 Hook이 담당할 책임이 무제한적으로 늘어날 가능성이 있어요.
+
+점점 Hook이 담당하고 있는 영역이 넓어지면서, 구현이 길어지고, 어떤 역할을 하는 Hook인지 파악하기 힘들어져요.
+
+### 성능
+
+이 Hook을 쓰는 컴포넌트는, 이 Hook이 관리하는 어떤 쿼리 파라미터가 수정되더라도 리렌더링이 발생해요.
+
+## ✏️ 개선해보기
+
+다음 코드와 같이 각각의 쿼리 파라미터별로 별도의 Hook을 작성할 수 있어요.
+
+```typescript
+export function useCardIdQueryParam() {
+  const [cardId, _setCardId] = useQueryParam("cardId", NumberParam);
+
+  const setCardId = useCallback((cardId: number) => {
+    _setCardId({ cardId }, "replaceIn");
+  }, []);
+
+  return [cardId ?? undefined, setCardId] as const;
+}
+```
+
+Hook이 담당하는 책임을 분리했기 때문에, 기존 `usePageState()` Hook보다 명확한 이름을 가져요.
+또한 Hook을 수정했을 때 영향이 갈 범위를 좁혀서, 예상하지 못한 변경이 생기는 것을 막을 수 있어요.

package/assets/dev-guide/fe/sources/toss-ff/readability-user-policy.md

@@ -0,0 +1,98 @@
+---
+title: 시점 이동 줄이기
+source: https://frontend-fundamentals.com/code-quality/code/examples/user-policy.html
+fetched: 2026-05-18
+principle: readability
+---
+
+# 시점 이동 줄이기
+
+코드를 읽을 때 코드의 위아래를 왔다갔다 하면서 읽거나, 여러 파일이나 함수, 변수를 넘나들면서 읽는 것을 **시점 이동**이라고 해요.
+시점이 여러 번 이동할수록 코드를 파악하는 데에 시간이 더 걸리고, 맥락을 파악하는 데에 어려움이 있을 수 있어요.
+
+## 📝 코드 예시
+
+다음 코드에서는 사용자의 권한에 따라서 버튼을 다르게 보여줘요.
+
+```tsx
+function Page() {
+  const user = useUser();
+  const policy = getPolicyByRole(user.role);
+
+  return (
+    <div>
+      <Button disabled={!policy.canInvite}>Invite</Button>
+      <Button disabled={!policy.canView}>View</Button>
+    </div>
+  );
+}
+
+function getPolicyByRole(role) {
+  const policy = POLICY_SET[role];
+
+  return {
+    canInvite: policy.includes("invite"),
+    canView: policy.includes("view")
+  };
+}
+
+const POLICY_SET = {
+  admin: ["invite", "view"],
+  viewer: ["view"]
+};
+```
+
+## 👃 코드 냄새 맡아보기
+
+### 가독성
+
+이 코드에서 `Invite` 버튼이 비활성화된 이유를 이해하려고 한다면, `policy.canInvite` → `getPolicyByRole(user.role)` → `POLICY_SET` 순으로 코드를 위아래를 오가며 읽어야 해요.
+이 과정에서 3번의 시점 이동이 발생해서, 코드를 읽는 사람이 맥락을 유지해 가며 읽기 어려워졌어요.
+
+## ✏️ 개선해보기
+
+### A. 조건을 펼쳐서 그대로 드러내기
+
+```tsx
+function Page() {
+  const user = useUser();
+
+  switch (user.role) {
+    case "admin":
+      return (
+        <div>
+          <Button disabled={false}>Invite</Button>
+          <Button disabled={false}>View</Button>
+        </div>
+      );
+    case "viewer":
+      return (
+        <div>
+          <Button disabled={true}>Invite</Button>
+          <Button disabled={false}>View</Button>
+        </div>
+      );
+    default:
+      return null;
+  }
+}
+```
+
+### B. 조건을 한눈에 볼 수 있는 객체로 만들기
+
+```tsx
+function Page() {
+  const user = useUser();
+  const policy = {
+    admin: { canInvite: true, canView: true },
+    viewer: { canInvite: false, canView: true }
+  }[user.role];
+
+  return (
+    <div>
+      <Button disabled={!policy.canInvite}>Invite</Button>
+      <Button disabled={!policy.canView}>View</Button>
+    </div>
+  );
+}
+```

package/assets/dev-guide/fe/sources/vue/INDEX.md

@@ -0,0 +1,17 @@
+---
+title: Vue/Nuxt 문서 인덱스
+fetched: 2026-05-18
+---
+
+# Vue/Nuxt FE 가이드 소스 인덱스
+
+| 파일 | 카테고리 | 소스 |
+|------|----------|------|
+| [style-guide-priority-a.md](./style-guide-priority-a.md) | style-guide | vuejs.org/style-guide/rules-essential |
+| [style-guide-priority-b.md](./style-guide-priority-b.md) | style-guide | vuejs.org/style-guide/rules-strongly-recommended |
+| [style-guide-priority-c.md](./style-guide-priority-c.md) | style-guide | vuejs.org/style-guide/rules-recommended |
+| [style-guide-priority-d.md](./style-guide-priority-d.md) | style-guide | vuejs.org/style-guide/rules-use-with-caution |
+| [composition-api.md](./composition-api.md) | composition-api | vuejs.org (composition-api-faq + sfc-script-setup) |
+| [pinia-state-management.md](./pinia-state-management.md) | state | pinia.vuejs.org/core-concepts/ |
+| [nuxt-data-fetching.md](./nuxt-data-fetching.md) | nuxt | nuxt.com/docs/getting-started/data-fetching |
+| [reactivity-pitfalls.md](./reactivity-pitfalls.md) | reactivity | vuejs.org/guide/extras/reactivity-in-depth |

package/assets/dev-guide/fe/sources/vue/composition-api.md

@@ -0,0 +1,251 @@
+---
+title: Composition API + script setup 베스트 프랙티스
+source: https://vuejs.org/guide/extras/composition-api-faq.html, https://vuejs.org/api/sfc-script-setup.html
+fetched: 2026-05-18
+category: composition-api
+vue_version: 3
+---
+
+# Composition API + `<script setup>` 베스트 프랙티스
+
+---
+
+## Composition API란?
+
+임포트한 함수를 사용해 Vue 컴포넌트를 작성하는 API 세트.
+
+- **Reactivity API**: `ref()`, `reactive()` — 반응형 상태, computed, watcher 생성
+- **Lifecycle Hooks**: `onMounted()`, `onUnmounted()` — 생명주기 훅
+- **Dependency Injection**: `provide()`, `inject()` — 의존성 주입
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const count = ref(0)
+
+function increment() {
+  count.value++
+}
+
+onMounted(() => {
+  console.log(`Initial count is ${count.value}.`)
+})
+</script>
+
+<template>
+  <button @click="increment">Count is: {{ count }}</button>
+</template>
+```
+
+---
+
+## Composition API를 사용하는 이유
+
+### 1. 로직 재사용 (Composables)
+- 믹스인의 단점을 모두 해결
+- VueUse 같은 생태계 활용 가능
+
+### 2. 유연한 코드 구성
+- Options API: 관련 코드가 `data`, `methods`, `computed` 등에 분산됨
+- Composition API: 관련 로직을 같은 위치에 모아서 관리
+
+### 3. 뛰어난 타입 추론
+- 일반 변수/함수를 사용하므로 TypeScript 친화적
+- Options API의 복잡한 타입 체조 불필요
+
+### 4. 더 작은 번들 크기
+- `<script setup>`에서 템플릿이 같은 스코프의 함수로 컴파일됨
+- 인스턴스 프록시 없이 직접 변수 접근 → 더 나은 minification
+
+---
+
+## React Hooks와의 차이점
+
+| 항목 | React Hooks | Vue Composition API |
+|------|-------------|---------------------|
+| 호출 횟수 | 렌더링마다 재실행 | `setup()`이 한 번만 실행 |
+| Stale closures | 의존성 배열 관리 필요 | 런타임 반응형으로 자동 추적 |
+| 최적화 | `useMemo`, `useCallback` 필요 | 세밀한 반응성으로 자동 최적화 |
+| 조건부 사용 | 불가 | 자유롭게 사용 가능 |
+
+---
+
+## `<script setup>` 완전 가이드
+
+### 기본 문법
+
+```vue
+<script setup>
+// 최상위 바인딩(변수, 함수, import)이 템플릿에 자동 노출
+const msg = 'Hello!'
+
+function log() {
+  console.log(msg)
+}
+</script>
+
+<template>
+  <button @click="log">{{ msg }}</button>
+</template>
+```
+
+### defineProps()
+
+```vue
+<script setup>
+// 런타임 선언
+const props = defineProps({
+  foo: String,
+  bar: { type: Number, required: true }
+})
+
+// 타입 선언 (TypeScript)
+const props = defineProps<{
+  foo: string
+  bar?: number
+}>()
+</script>
+```
+
+**반응형 구조 분해 (Vue 3.5+):**
+```ts
+const { foo } = defineProps(['foo'])
+// foo 변경 시 watchEffect 자동 재실행
+watchEffect(() => { console.log(foo) })
+```
+
+**기본값 (Vue 3.5+ 권장):**
+```ts
+const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
+```
+
+**기본값 (Vue 3.4 이하):**
+```ts
+const props = withDefaults(defineProps<Props>(), {
+  msg: 'hello',
+  labels: () => ['one', 'two']  // 뮤터블 타입은 함수로 래핑
+})
+```
+
+### defineEmits()
+
+```vue
+<script setup>
+const emit = defineEmits(['change', 'delete'])
+
+// TypeScript
+const emit = defineEmits<{
+  change: [id: number]
+  update: [value: string]
+}>()
+</script>
+```
+
+### defineModel() (Vue 3.4+)
+
+```js
+// v-model 양방향 바인딩
+const model = defineModel()  // modelValue prop
+model.value = 'hello'
+
+// named model
+const count = defineModel('count', { type: Number, default: 0 })
+count.value++
+
+// modifier 처리
+const [modelValue, modelModifiers] = defineModel({
+  set(value) {
+    if (modelModifiers.trim) return value.trim()
+    return value
+  }
+})
+```
+
+### defineExpose()
+
+`<script setup>` 컴포넌트는 기본적으로 닫혀있다. 외부에서 접근할 속성은 명시적으로 노출한다.
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const a = 1
+const b = ref(2)
+
+defineExpose({ a, b })  // 부모의 template ref로 접근 가능
+</script>
+```
+
+### defineOptions() (Vue 3.3+)
+
+```vue
+<script setup>
+defineOptions({
+  inheritAttrs: false,
+  name: 'MyComponent'
+})
+</script>
+```
+
+### defineSlots() (Vue 3.3+)
+
+```vue
+<script setup lang="ts">
+const slots = defineSlots<{
+  default(props: { msg: string }): any
+}>()
+</script>
+```
+
+### useSlots() & useAttrs()
+
+```vue
+<script setup>
+import { useSlots, useAttrs } from 'vue'
+
+const slots = useSlots()
+const attrs = useAttrs()
+</script>
+```
+
+### Top-level await
+
+```vue
+<script setup>
+const post = await fetch('/api/post/1').then((r) => r.json())
+</script>
+```
+
+`async setup()`으로 컴파일됨. `<Suspense>`와 함께 사용해야 한다.
+
+### 제네릭 (TypeScript)
+
+```vue
+<script setup lang="ts" generic="T extends string | number, U extends Item">
+import type { Item } from './types'
+
+defineProps<{
+  id: T
+  list: U[]
+}>()
+</script>
+```
+
+---
+
+## 일반 `<script>`와 혼용
+
+```vue
+<script>
+// 모듈 스코프에서 1회 실행
+runSideEffectOnce()
+export default { inheritAttrs: false }
+</script>
+
+<script setup>
+// 각 인스턴스 setup() 스코프에서 실행
+</script>
+```
+
+기존 Options API 코드베이스와의 점진적 통합에만 사용. 일반적으로는 권장하지 않는다.