Skip to content

Commit b721c6d

Browse files
tonyfromundefinedclaude
tonyfromundefined
and
claude
committed
docs(tech-specs): add PR #695 review follow-up task breakdown
Split ENvironmentSet's review feedback on PR #695 into 6 follow-up PR tasks (06a/06b/06c/07a/08/09) and drop `@stackflow/compat-await-push` from the deletion plan per reviewer objection. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 59d9e9c commit b721c6d

7 files changed

Lines changed: 483 additions & 12 deletions

‎.tech-specs/tasks/01-delete-deprecated-packages.md‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,13 @@
44
55
## 목적
66

7-
Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체된 패키지 3개를 삭제한다.
7+
Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체된 패키지 2개를 삭제한다.
88

9-
## 삭제 대상
10-
11-
### 1. `@stackflow/compat-await-push`
9+
> `@stackflow/compat-await-push`는 삭제 계획에서 제외됨 (ENvironmentSet 반대, PR #695)
1210
13-
- **경로:** `extensions/compat-await-push/`
14-
- **이유:** Old API의 `await push()` 패턴 호환 레이어. Future API에서는 사용하지 않음
15-
- **작업:**
16-
- `extensions/compat-await-push/` 디렉토리 전체 삭제
17-
- 루트 `package.json` 워크스페이스 설정에서 제거 (해당하는 경우)
18-
- 다른 패키지의 dependency/peerDependency에서 참조 제거
11+
## 삭제 대상
1912

20-
### 2. `@stackflow/plugin-preload`
13+
### 1. `@stackflow/plugin-preload`
2114

2215
- **경로:** `extensions/plugin-preload/`
2316
- **이유:** Future API의 `usePrepare()` 훅으로 대체
@@ -28,7 +21,7 @@ Stable API에서만 사용되거나 Future API에 내장된 기능으로 대체
2821
- 플러그인 문서 삭제: `docs/pages/api-references/plugins/plugin-preload.{en,ko}.mdx`
2922
- `docs/pages/api-references/plugins/_meta.{en,ko}.json`에서 항목 제거
3023

31-
### 3. `@stackflow/plugin-map-initial-activity`
24+
### 2. `@stackflow/plugin-map-initial-activity`
3225

3326
- **경로:** `extensions/plugin-map-initial-activity/`
3427
- **이유:** Future API의 `config.initialActivity`로 대체

‎.tech-specs/tasks/06a-fix-docs-code-examples.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# PR 6a: 문서 코드 예제 수정
2+
3+
> 선행 PR: PR 3, PR 4 (API 승격 완료 후)
4+
> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129)
5+
6+
## 목적
7+
8+
PR #695에서 ENvironmentSet이 지적한 문서 코드 예제 오류를 수정한다. (삭제/rename은 PR 6b로, structured-activity 문서 개선은 PR 6c로 분리.)
9+
10+
## 작업
11+
12+
### 1. `stackflow()` 반환값에서 `useFlow` destructuring 제거
13+
14+
실제 `StackflowOutput` 타입 (`integrations/react/src/stackflow.tsx:46-50`):
15+
16+
```ts
17+
export type StackflowOutput = {
18+
Stack: StackComponentType;
19+
actions: Actions;
20+
stepActions: StepActions<ActivityBaseParams>;
21+
};
22+
```
23+
24+
`useFlow`는 반환값에 포함되지 않으며, `@stackflow/react`에서 독립 훅으로 직접 import해야 한다.
25+
26+
**수정 파일:**
27+
28+
| 파일 | 라인 |
29+
|------|------|
30+
| `docs/pages/docs/get-started/installation.en.mdx` | L40, L70 |
31+
| `docs/pages/docs/get-started/installation.ko.mdx` | L40, L71 |
32+
| `docs/pages/docs/get-started/activity.en.mdx` | L81 |
33+
| `docs/pages/docs/get-started/activity.ko.mdx` | L84 |
34+
| `docs/pages/docs/advanced/history-sync.en.mdx` | L43 |
35+
| `docs/pages/docs/advanced/history-sync.ko.mdx` | L43 |
36+
| `docs/pages/docs/migration-v2.en.mdx` | L52 ("After") |
37+
| `docs/pages/docs/migration-v2.ko.mdx` | L52 ("변경 후") |
38+
39+
**수정 방향:**
40+
```diff
41+
- const { Stack, useFlow } = stackflow(...)
42+
+ const { Stack } = stackflow(...)
43+
+ import { useFlow } from "@stackflow/react";
44+
```
45+
46+
### 2. `ActivityComponentType` v1 → v2 타입 패턴 변경
47+
48+
v2 `ActivityComponentType`은 params 객체 타입 대신 activity 이름 string literal을 받는다. 기존 params 객체 방식은 `ActivityComponentTypeByParams`로 rename.
49+
50+
**수정 파일:**
51+
- `docs/pages/docs/get-started/navigating-activities.en.mdx` L141-145
52+
- `docs/pages/docs/get-started/navigating-activities.ko.mdx` L143-147
53+
54+
**수정 방향:**
55+
```diff
56+
- type ArticleParams = { title: string; };
57+
- const Article: ActivityComponentType<ArticleParams> = ({ params }) => {
58+
+ declare module "@stackflow/config" {
59+
+ interface Register {
60+
+ Article: { title: string };
61+
+ }
62+
+ }
63+
+ const Article: ActivityComponentType<"Article"> = ({ params }) => {
64+
```
65+
66+
### 3. `ActivityLoaderArgs` import 경로 오류
67+
68+
`ActivityLoaderArgs`는 `@stackflow/config`에서만 export된다 (`config/src/index.ts:4`). `@stackflow/react`에서는 내부 사용만 하며 re-export하지 않는다.
69+
70+
**수정 파일:**
71+
72+
| 파일 | 라인 |
73+
|------|------|
74+
| `docs/pages/docs/advanced/loader-api.en.mdx` | L6 |
75+
| `docs/pages/docs/advanced/loader-api.ko.mdx` | L6 |
76+
| `docs/pages/docs/advanced/preloading.en.mdx` | L12 |
77+
| `docs/pages/docs/advanced/preloading.ko.mdx` | L12 |
78+
79+
> `loader-api.{en,ko}.mdx`는 PR 6b에서 삭제 예정. PR 6b와 머지 시점 조율 필요.
80+
81+
**수정 방향:**
82+
```diff
83+
- import { ActivityLoaderArgs, useLoaderData } from "@stackflow/react";
84+
+ import type { ActivityLoaderArgs } from "@stackflow/config";
85+
+ import { useLoaderData } from "@stackflow/react";
86+
```
87+
88+
### 4. `@stackflow/link` API 레퍼런스 수정
89+
90+
#### 4-a. `animate` 기본값 설명 오류
91+
92+
현재 문서 (`link.en.mdx:45`, `link.ko.mdx:45`):
93+
> "If not provided, it defaults to no animation."
94+
95+
실제 동작 (`extensions/link/src/Link.tsx:89-99`): `animate`를 생략하면 빈 옵션 `{}`가 전달되어 push/replace의 기본 동작(**애니메이션 ON**)이 적용된다. 설명을 "기본 애니메이션 적용"으로 수정.
96+
97+
#### 4-b. 존재하지 않는 `urlPatternOptions` prop 제거
98+
99+
실제 `LinkProps` (`Link.tsx:24-31`):
100+
```ts
101+
export interface LinkProps<K extends RegisteredActivityName> extends AnchorProps {
102+
ref?: React.RefObject<HTMLAnchorElement>;
103+
activityName: K;
104+
activityParams: InferActivityParams<K>;
105+
animate?: boolean;
106+
replace?: boolean;
107+
}
108+
```
109+
110+
`urlPatternOptions`는 `config.historySync`에서 내부적으로 사용될 뿐 사용자 prop이 아니다.
111+
112+
**수정 파일:**
113+
- `docs/pages/api-references/plugins/link.en.mdx` L47 — prop 문서 제거
114+
- `docs/pages/api-references/plugins/link.ko.mdx` L47 — prop 문서 제거
115+
116+
#### 4-c. Link ref 타입 오류
117+
118+
문서에는 `React.ForwardedRef<HTMLAnchorElement>`로 기재되어 있으나 실제는 `React.RefObject<HTMLAnchorElement>`.
119+
120+
**수정 파일:**
121+
- `docs/pages/api-references/plugins/link.en.mdx` L48
122+
- `docs/pages/api-references/plugins/link.ko.mdx` L48
123+
124+
### 5. `plugin-history-sync` 문서 v2 업데이트
125+
126+
현재 v1 API 패턴을 그대로 사용 중:
127+
- `const { Stack, useFlow } = stackflow({ activities: { ... } })`
128+
- `routes` 옵션 (v2에서는 config에 선언)
129+
130+
v2 config-first 패턴으로 전면 업데이트.
131+
132+
**수정 파일:**
133+
- `docs/pages/api-references/plugins/plugin-history-sync.en.mdx`
134+
- `docs/pages/api-references/plugins/plugin-history-sync.ko.mdx`
135+
136+
### 6. `migration-v2` 문서 개선
137+
138+
#### 6-a. 5단계 "Before" 예시 확장
139+
140+
현재:
141+
```ts
142+
import { useFlow } from "./stackflow";
143+
```
144+
145+
`./stackflow`라는 파일 경로가 묵시적이어서 이해가 어렵다. `stackflow()` 팩토리에서 `useFlow`를 destructuring하여 export하는 **전체 맥락**을 보여주도록 확장.
146+
147+
#### 6-b. API 대응표에서 `./stackflow` → `stackflow()` 팩토리 표현으로 변경
148+
149+
현재:
150+
```
151+
| `useFlow()` from `./stackflow` | `useFlow()` from `@stackflow/react` |
152+
```
153+
154+
파일 경로 대신 `stackflow()` 팩토리라는 표현으로 수정.
155+
156+
**수정 파일:**
157+
- `docs/pages/docs/migration-v2.en.mdx`
158+
- `docs/pages/docs/migration-v2.ko.mdx`
159+
160+
### 7. `write-plugin` 문서 수정
161+
162+
#### 7-a. 오타
163+
164+
`write-plugin.ko.mdx:262`: `G현재 스택의 상태를 가져올 수 있어요` → `현재 스택의 상태를 가져올 수 있어요`
165+
166+
#### 7-b. 존재하지 않는 lifecycle hook 이름 수정
167+
168+
`initialPushedEvent`는 존재하지 않는 훅. 올바른 이름은 `overrideInitialEvents`.
169+
170+
**수정 파일:**
171+
- `docs/pages/docs/advanced/write-plugin.en.mdx` L261, L272
172+
- `docs/pages/docs/advanced/write-plugin.ko.mdx` L269, L280
173+
174+
## 확인 사항
175+
176+
- [ ] 수정된 모든 파일에서 `useFlow`가 `@stackflow/react`에서 직접 import
177+
- [ ] `stackflow()` destructuring에 `useFlow` 미포함
178+
- [ ] `ActivityComponentType<ParamsObject>` → `ActivityComponentType<"ActivityName">`
179+
- [ ] `ActivityLoaderArgs` import 경로가 `@stackflow/config`로 수정
180+
- [ ] `animate` 기본값 설명 정정
181+
- [ ] `urlPatternOptions` prop 문서 제거
182+
- [ ] Link ref 타입 `React.RefObject`로 수정
183+
- [ ] `plugin-history-sync` 문서 v2 패턴
184+
- [ ] `migration-v2` Before 예시/대응표 수정
185+
- [ ] `write-plugin` 오타/lifecycle hook 이름 수정
186+
- [ ] EN/KO 양쪽 동기화
187+
- [ ] 문서 사이트 로컬 빌드 정상

‎.tech-specs/tasks/06b-restructure-docs.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# PR 6b: 문서 구조 변경 (삭제/rename/네비게이션)
2+
3+
> 선행 PR: PR 3, PR 4
4+
> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129 추가 리뷰)
5+
6+
## 목적
7+
8+
ENvironmentSet이 지적한 중복/불필요 문서를 정리하고, 네비게이션 라벨을 수정한다.
9+
10+
## 작업
11+
12+
### 1. `resolving-circular-reference` 문서 삭제
13+
14+
v2에서는 `useFlow`를 `@stackflow/react`에서 직접 import하므로 순환참조 문제가 발생하지 않는다. 또한 문서에서 참조하는 `useActions`는 v2에 존재하지 않는 API이다.
15+
16+
**삭제:**
17+
- `docs/pages/docs/advanced/resolving-circular-reference.en.mdx`
18+
- `docs/pages/docs/advanced/resolving-circular-reference.ko.mdx`
19+
20+
**반영:**
21+
- `docs/pages/docs/advanced/_meta.en.json`에서 항목 제거
22+
- `docs/pages/docs/advanced/_meta.ko.json`에서 항목 제거
23+
24+
### 2. `loader-api` 문서 삭제 + `preloading`을 "Loader API"로 rename
25+
26+
`loader-api`와 `preloading` 문서 내용이 중복된다. `loader-api` 삭제 후 `preloading`의 제목을 "Loader API"로 변경한다.
27+
28+
**삭제:**
29+
- `docs/pages/docs/advanced/loader-api.en.mdx`
30+
- `docs/pages/docs/advanced/loader-api.ko.mdx`
31+
32+
**변경:**
33+
- `docs/pages/docs/advanced/preloading.en.mdx` — 제목 → "Loader API"
34+
- `docs/pages/docs/advanced/preloading.ko.mdx` — 제목 → "Loader API"
35+
36+
**반영:**
37+
- `docs/pages/docs/advanced/_meta.en.json` — `loader-api` 제거, `preloading` 라벨 → "Loader API"
38+
- `docs/pages/docs/advanced/_meta.ko.json` — 동일
39+
40+
> 파일명(`preloading.mdx`)까지 변경할지, 라우팅 리다이렉트가 필요한지는 PR에서 별도 결정.
41+
42+
### 3. `@stackflow/config` 네비게이션 이름 변경 (ko)
43+
44+
**수정 파일:**
45+
- `docs/pages/api-references/_meta.ko.json`
46+
47+
**변경:**
48+
```diff
49+
- "@stackflow/config": "@stackflow/config"
50+
+ "@stackflow/config": "설정"
51+
```
52+
53+
## 확인 사항
54+
55+
- [ ] `resolving-circular-reference` 파일 2개 삭제 + meta 반영
56+
- [ ] `loader-api` 파일 2개 삭제 + meta 반영
57+
- [ ] `preloading` 제목 "Loader API"로 변경 (meta에도 반영)
58+
- [ ] `@stackflow/config` 한국어 라벨 "설정"
59+
- [ ] 삭제된 문서를 링크하는 다른 문서 없는지 확인 (있으면 링크 수정)
60+
- [ ] 문서 사이트 로컬 빌드 정상 (404 없음)

‎.tech-specs/tasks/06c-structured-activity-docs.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# PR 6c: structured-activity 문서 개선
2+
3+
> 선행 PR: PR 3
4+
> PR #695 ENvironmentSet 리뷰 반영 (FEP-2129 추가 리뷰)
5+
6+
## 목적
7+
8+
`structured-activity` 관련 문서의 예시와 line highlighting을 소스 실제 구조에 맞게 개선한다.
9+
10+
## 작업
11+
12+
### 1. `content` 예시 단순화
13+
14+
`content` 컴포넌트가 `useActivityParams`를 쓰는 대신 매개변수로 `params`를 직접 받도록 예시 변경. (복잡한 훅 사용보다 props 패턴이 이해에 용이)
15+
16+
### 2. API 섹션 제거
17+
18+
추후 전체 API를 다루는 별도 페이지가 만들어질 예정. 현재 문서의 API 섹션은 제거.
19+
20+
### 3. Line highlighting 수정 (한/영 모두)
21+
22+
현재 하이라이트 라인이 의미 없는 위치(빈 줄, 닫는 괄호)를 가리키고 있음. 실제 의미 있는 줄을 가리키도록 수정.
23+
24+
| 섹션 | 현재 | 수정 | 이유 |
25+
|------|------|------|------|
26+
| Loading State (`Article.tsx`) | `{3,7}` | `{2,6}` | import와 `loading:` 줄 |
27+
| Layout (`Article.tsx`) | `{3,4,8,9}` | `{2,7}` | import와 `layout:` 줄 |
28+
| With Loader API (`stackflow.config.ts`) | `{8}` | `{2,9}` | `import articleLoader`와 `loader:` 줄 |
29+
30+
**수정 파일:**
31+
- `docs/pages/docs/advanced/structured-activity.en.mdx`
32+
- `docs/pages/docs/advanced/structured-activity.ko.mdx`
33+
34+
## 확인 사항
35+
36+
- [ ] `content` 예시가 매개변수로 `params`를 받는 패턴으로 단순화
37+
- [ ] API 섹션 제거
38+
- [ ] 3개 섹션의 line highlighting이 실제 의미 있는 줄을 가리킴
39+
- [ ] EN/KO 양쪽 동기화

0 commit comments

Comments
 (0)