Skip to content

Commit 36eede2

Browse files
tonyfromundefinedclaude
tonyfromundefined
and
claude
committed
docs: update plugin-history-sync, structured-activity, and meta files
- plugin-history-sync.{en,ko}.mdx: migrate to config-first pattern (routes in defineConfig, config passed to historySyncPlugin) - structured-activity.{en,ko}.mdx: simplify content example to use params prop, fix line highlights ({3,7}→{2,6}, {3,4,8,9}→{2,7}, {8}→{2,9}), remove API Reference section, fix import type→import for loader, fix loader-api link to preloading - api-references/_meta.ko.json: translate @stackflow/config label to 설정 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 3285d37 commit 36eede2

5 files changed

Lines changed: 65 additions & 95 deletions

File tree

‎docs/pages/api-references/_meta.ko.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
2-
"config": "@stackflow/config",
2+
"config": "설정",
33
"plugins": "플러그인"
44
}

‎docs/pages/api-references/plugins/plugin-history-sync.en.mdx‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,30 +12,40 @@ npm install @stackflow/plugin-history-sync
1212

1313
## Usage
1414

15+
```ts showLineNumbers filename="stackflow.config.ts" copy
16+
import { defineConfig } from "@stackflow/config";
17+
18+
export const config = defineConfig({
19+
activities: [
20+
/**
21+
* You can link the registered activity with the URL template.
22+
*/
23+
{ name: "MyHome", route: "/" },
24+
{ name: "MyArticle", route: "/articles/:articleId" },
25+
{ name: "NotFoundPage", route: "/404" },
26+
],
27+
transitionDuration: 350,
28+
});
29+
```
30+
1531
```ts showLineNumbers filename="stackflow.ts" copy
1632
import { stackflow } from "@stackflow/react";
1733
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
34+
import { config } from "./stackflow.config";
1835
import { MyHome } from "./MyHome";
1936
import { MyArticle } from "./MyArticle";
2037
import { NotFoundPage } from "./NotFoundPage";
2138

22-
const { Stack, useFlow } = stackflow({
23-
activities: {
39+
export const { Stack } = stackflow({
40+
config,
41+
components: {
2442
MyHome,
2543
MyArticle,
2644
NotFoundPage,
2745
},
2846
plugins: [
29-
// ...
3047
historySyncPlugin({
31-
routes: {
32-
/**
33-
* You can link the registered activity with the URL template.
34-
*/
35-
MyHome: "/",
36-
MyArticle: "/articles/:articleId",
37-
NotFoundPage: "/404",
38-
},
48+
config,
3949
/**
4050
* If a URL that does not correspond to the URL template is given, it moves to the `fallbackActivity`.
4151
*/
@@ -54,8 +64,8 @@ const { Stack, useFlow } = stackflow({
5464
<APITable>
5565
| | | |
5666
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57-
| routes | `object` | Connects activities with URL templates. You can represent activity parameters as Path Parameters. If an activity's parameter is not in the URL template, it will automatically be represented as a Query Parameter. |
58-
| fallbackActivity | `(args: { initialContext: any }) => K` | Determines which activity to navigate to if there is no matching URL when first entering. Typically, you create a 404 page and assign it here. |
67+
| config | `Config` | The config object from `defineConfig()`. Routes are declared per-activity in `stackflow.config.ts`. |
68+
| fallbackActivity | `(args: { initialContext: any }) => K` | Determines which activity to navigate to if there is no matching URL when first entering. Typically, you create a 404 page and assign it here. |
5969
| useHash | `boolean` (optional) | Determines if hash-based routing should be used. Defaults to false. |
6070
| history | `History` (optional) | A custom history object used for managing navigation state. Defaults to browser or memory history. |
6171
| urlPatternOptions | `UrlPatternOptions` (optional) | Options for URL pattern matching and generation, affecting how URLs are constructed and parsed. |

‎docs/pages/api-references/plugins/plugin-history-sync.ko.mdx‎

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,36 +13,46 @@ npm install @stackflow/plugin-history-sync
1313

1414
## 사용법
1515

16+
```ts showLineNumbers filename="stackflow.config.ts" copy
17+
import { defineConfig } from "@stackflow/config";
18+
19+
export const config = defineConfig({
20+
activities: [
21+
/**
22+
* 등록된 액티비티와 URL 템플릿을 연결해요.
23+
*/
24+
{ name: "MyHome", route: "/" },
25+
{ name: "MyArticle", route: "/articles/:articleId" },
26+
{ name: "NotFoundPage", route: "/404" },
27+
],
28+
transitionDuration: 350,
29+
});
30+
```
31+
1632
```ts showLineNumbers filename="stackflow.ts" copy
1733
import { stackflow } from "@stackflow/react";
1834
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
35+
import { config } from "./stackflow.config";
1936
import { MyHome } from "./MyHome";
2037
import { MyArticle } from "./MyArticle";
2138
import { NotFoundPage } from "./NotFoundPage";
2239

23-
const { Stack, useFlow } = stackflow({
24-
activities: {
40+
export const { Stack } = stackflow({
41+
config,
42+
components: {
2543
MyHome,
2644
MyArticle,
2745
NotFoundPage,
2846
},
2947
plugins: [
30-
// ...
3148
historySyncPlugin({
32-
routes: {
33-
/**
34-
* You can link the registered activity with the URL template.
35-
*/
36-
MyHome: "/",
37-
MyArticle: "/articles/:articleId",
38-
NotFoundPage: "/404",
39-
},
49+
config,
4050
/**
41-
* If a URL that does not correspond to the URL template is given, it moves to the `fallbackActivity`.
51+
* 첫 진입 시 현재 URL과 매핑되는 URL이 없는 경우 어떤 액티비티로 보낼지 결정해요.
4252
*/
4353
fallbackActivity: ({ context }) => "NotFoundPage",
4454
/**
45-
* Uses the hash portion of the URL (i.e. window.location.hash)
55+
* URL의 해시 부분(window.location.hash)을 사용해요.
4656
*/
4757
useHash: false,
4858
}),
@@ -55,8 +65,8 @@ const { Stack, useFlow } = stackflow({
5565
<APITable>
5666
| | | |
5767
| ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
58-
| routes | `object` | 액티비티와 URL 템플릿을 연결해요. 액티비티의 파라미터를 Path Parameter로 표현할 수 있어요. 만약 액티비티의 파라미터가 해당 URL 템플릿에 없다면 자동으로 Query Parameter로 표현돼요. |
59-
| fallbackActivity | `(args: { initialContext: any }) => K` | 첫 진입시에 현재 URL과 매핑되는 URL이 없는 경우 어떤 액티비티로 보낼지 결정해요. 일반적으로 404 페이지를 만들고 여기에 할당해요. |
68+
| config | `Config` | `defineConfig()`의 config 객체예요. 라우트는 `stackflow.config.ts`의 각 액티비티 선언에서 지정해요. |
69+
| fallbackActivity | `(args: { initialContext: any }) => K` | 첫 진입시에 현재 URL과 매핑되는 URL이 없는 경우 어떤 액티비티로 보낼지 결정해요. 일반적으로 404 페이지를 만들고 여기에 할당해요. |
6070
| useHash | `boolean` (optional) | 해시 기반 라우팅을 사용할지를 결정해요. 기본값은 false예요. |
6171
| history | `History` (optional) | 네비게이션 상태를 관리하는 데 사용되는 사용자 정의 히스토리 객체예요. 기본적으로 브라우저나 메모리 히스토리예요. |
6272
| urlPatternOptions | `UrlPatternOptions` (optional) | URL 패턴 매칭 및 생성과 관련된 옵션으로, URL이 어떻게 구성되고 해석되는지에 영향을 줘요. |

‎docs/pages/docs/advanced/structured-activity.en.mdx‎

Lines changed: 8 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -54,25 +54,19 @@ export const Article = structuredActivityComponent<"Article">({
5454
`Article.content.tsx` exports a `content()` helper:
5555

5656
```tsx showLineNumbers filename="Article.content.tsx" copy
57-
import { content, useActivityParams } from "@stackflow/react";
58-
59-
const ArticleContent = content<"Article">(() => {
60-
const { title } = useActivityParams<"Article">();
57+
import { content } from "@stackflow/react";
6158

59+
const ArticleContent = content<"Article">(({ params }) => {
6260
return (
6361
<div>
64-
<h1>{title}</h1>
62+
<h1>{params.title}</h1>
6563
</div>
6664
);
6765
});
6866

6967
export default ArticleContent;
7068
```
7169

72-
<Callout emoji="💡">
73-
`useActivityParams()` reads the current activity's params. It's a convenient alternative to receiving `params` as a prop inside `content()`.
74-
</Callout>
75-
7670
## Loading State
7771

7872
Provide a `loading` component to show while the content bundle or loader data is being fetched. It renders as the Suspense fallback.
@@ -87,7 +81,7 @@ const ArticleLoading = loading<"Article">(() => {
8781
export default ArticleLoading;
8882
```
8983

90-
```tsx showLineNumbers filename="Article.tsx" copy {3,7}
84+
```tsx showLineNumbers filename="Article.tsx" copy {2,6}
9185
import { structuredActivityComponent } from "@stackflow/react";
9286
import ArticleLoading from "./Article.loading";
9387

@@ -116,7 +110,7 @@ const ArticleLayout = layout<"Article">(({ params: { title }, children }) => {
116110
export default ArticleLayout;
117111
```
118112

119-
```tsx showLineNumbers filename="Article.tsx" copy {3,4,8,9}
113+
```tsx showLineNumbers filename="Article.tsx" copy {2,7}
120114
import { structuredActivityComponent } from "@stackflow/react";
121115
import ArticleLayout from "./Article.layout";
122116
import ArticleLoading from "./Article.loading";
@@ -174,7 +168,7 @@ const ArticleError = errorHandler<"Article">(
174168

175169
## With Loader API
176170

177-
Structured activities work seamlessly with the [Loader API](/docs/advanced/loader-api). Define the loader in `stackflow.config.ts` and use `useLoaderData()` inside `content()`.
171+
Structured activities work seamlessly with the [Loader API](/docs/advanced/preloading). Define the loader in `stackflow.config.ts` and use `useLoaderData()` inside `content()`.
178172

179173
```tsx showLineNumbers filename="Article.loader.ts" copy
180174
import type { ActivityLoaderArgs } from "@stackflow/config";
@@ -185,7 +179,7 @@ export async function articleLoader({ params }: ActivityLoaderArgs<"Article">) {
185179
}
186180
```
187181

188-
```tsx showLineNumbers filename="stackflow.config.ts" copy {8}
182+
```tsx showLineNumbers filename="stackflow.config.ts" copy {2,9}
189183
import { defineConfig } from "@stackflow/config";
190184
import { articleLoader } from "./Article.loader";
191185

@@ -203,7 +197,7 @@ export const config = defineConfig({
203197

204198
```tsx showLineNumbers filename="Article.content.tsx" copy
205199
import { content, useActivityParams, useLoaderData } from "@stackflow/react";
206-
import type { articleLoader } from "./Article.loader";
200+
import { articleLoader } from "./Article.loader";
207201

208202
const ArticleContent = content<"Article">(() => {
209203
const { title } = useActivityParams<"Article">();
@@ -234,22 +228,3 @@ activities/
234228
└── Article.loader.ts # loader
235229
```
236230

237-
## API Reference
238-
239-
### `structuredActivityComponent<ActivityName>(options)`
240-
241-
| Option | Type | Description |
242-
|--------|------|-------------|
243-
| `content` | `Content \| (() => Promise<{ default: Content }>)` | Main content component, or an async import for code splitting |
244-
| `layout` | `Layout` (optional) | Wraps the content and loading/error states |
245-
| `loading` | `Loading` (optional) | Rendered as the Suspense fallback |
246-
| `errorHandler` | `ErrorHandler` (optional) | Rendered when content throws |
247-
248-
### Helper Functions
249-
250-
| Function | Description |
251-
|----------|-------------|
252-
| `content<ActivityName>(component)` | Creates a content descriptor |
253-
| `layout<ActivityName>(component)` | Creates a layout descriptor; receives `params` and `children` |
254-
| `loading<ActivityName>(component)` | Creates a loading descriptor; receives `params` |
255-
| `errorHandler<ActivityName>(component, options?)` | Creates an error handler descriptor; receives `params`, `error`, `reset` |

‎docs/pages/docs/advanced/structured-activity.ko.mdx‎

Lines changed: 8 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -54,25 +54,19 @@ export const Article = structuredActivityComponent<"Article">({
5454
`Article.content.tsx`는 `content()` 헬퍼를 사용해 export해요.
5555

5656
```tsx showLineNumbers filename="Article.content.tsx" copy
57-
import { content, useActivityParams } from "@stackflow/react";
58-
59-
const ArticleContent = content<"Article">(() => {
60-
const { title } = useActivityParams<"Article">();
57+
import { content } from "@stackflow/react";
6158

59+
const ArticleContent = content<"Article">(({ params }) => {
6260
return (
6361
<div>
64-
<h1>{title}</h1>
62+
<h1>{params.title}</h1>
6563
</div>
6664
);
6765
});
6866

6967
export default ArticleContent;
7068
```
7169

72-
<Callout emoji="💡">
73-
`useActivityParams()`는 현재 액티비티의 params를 가져와요. `content()` 내부에서 props로 받는 것의 편리한 대안이에요.
74-
</Callout>
75-
7670
## 로딩 상태
7771

7872
콘텐츠 번들이나 로더 데이터를 가져오는 동안 보여줄 `loading` 컴포넌트를 제공해요. Suspense fallback으로 렌더링돼요.
@@ -87,7 +81,7 @@ const ArticleLoading = loading<"Article">(() => {
8781
export default ArticleLoading;
8882
```
8983

90-
```tsx showLineNumbers filename="Article.tsx" copy {3,7}
84+
```tsx showLineNumbers filename="Article.tsx" copy {2,6}
9185
import { structuredActivityComponent } from "@stackflow/react";
9286
import ArticleLoading from "./Article.loading";
9387

@@ -116,7 +110,7 @@ const ArticleLayout = layout<"Article">(({ params: { title }, children }) => {
116110
export default ArticleLayout;
117111
```
118112

119-
```tsx showLineNumbers filename="Article.tsx" copy {3,4,8,9}
113+
```tsx showLineNumbers filename="Article.tsx" copy {2,7}
120114
import { structuredActivityComponent } from "@stackflow/react";
121115
import ArticleLayout from "./Article.layout";
122116
import ArticleLoading from "./Article.loading";
@@ -174,7 +168,7 @@ const ArticleError = errorHandler<"Article">(
174168

175169
## Loader API와 함께 사용하기
176170

177-
구조화된 액티비티는 [Loader API](/docs/advanced/loader-api)와 자연스럽게 연동돼요. `stackflow.config.ts`에 로더를 정의하고 `content()` 내부에서 `useLoaderData()`로 가져와요.
171+
구조화된 액티비티는 [Loader API](/docs/advanced/preloading)와 자연스럽게 연동돼요. `stackflow.config.ts`에 로더를 정의하고 `content()` 내부에서 `useLoaderData()`로 가져와요.
178172

179173
```tsx showLineNumbers filename="Article.loader.ts" copy
180174
import type { ActivityLoaderArgs } from "@stackflow/config";
@@ -185,7 +179,7 @@ export async function articleLoader({ params }: ActivityLoaderArgs<"Article">) {
185179
}
186180
```
187181

188-
```tsx showLineNumbers filename="stackflow.config.ts" copy {8}
182+
```tsx showLineNumbers filename="stackflow.config.ts" copy {2,9}
189183
import { defineConfig } from "@stackflow/config";
190184
import { articleLoader } from "./Article.loader";
191185

@@ -203,7 +197,7 @@ export const config = defineConfig({
203197

204198
```tsx showLineNumbers filename="Article.content.tsx" copy
205199
import { content, useActivityParams, useLoaderData } from "@stackflow/react";
206-
import type { articleLoader } from "./Article.loader";
200+
import { articleLoader } from "./Article.loader";
207201

208202
const ArticleContent = content<"Article">(() => {
209203
const { title } = useActivityParams<"Article">();
@@ -234,22 +228,3 @@ activities/
234228
└── Article.loader.ts # loader
235229
```
236230

237-
## API 레퍼런스
238-
239-
### `structuredActivityComponent<ActivityName>(options)`
240-
241-
| 옵션 | 타입 | 설명 |
242-
|------|------|------|
243-
| `content` | `Content \| (() => Promise<{ default: Content }>)` | 메인 콘텐츠 컴포넌트, 또는 코드 스플리팅을 위한 async import |
244-
| `layout` | `Layout` (선택) | 콘텐츠와 로딩/에러 상태를 감싸는 래퍼 |
245-
| `loading` | `Loading` (선택) | Suspense fallback으로 렌더링되는 컴포넌트 |
246-
| `errorHandler` | `ErrorHandler` (선택) | 콘텐츠에서 에러 발생 시 렌더링되는 컴포넌트 |
247-
248-
### 헬퍼 함수
249-
250-
| 함수 | 설명 |
251-
|------|------|
252-
| `content<ActivityName>(component)` | content 디스크립터 생성 |
253-
| `layout<ActivityName>(component)` | layout 디스크립터 생성; `params`와 `children`을 받아요 |
254-
| `loading<ActivityName>(component)` | loading 디스크립터 생성; `params`를 받아요 |
255-
| `errorHandler<ActivityName>(component, options?)` | error handler 디스크립터 생성; `params`, `error`, `reset`을 받아요 |

0 commit comments

Comments
 (0)