FlowGram ドキュメントの組織構造

• 英文ドキュメント: apps/docs/src/en
• 中文ドキュメント: apps/docs/src/zh
• Story コンポーネント: apps/docs/components/form-materials/components
• 物料ソースコード: packages/materials/form-materials/src/components
• ドキュメントテンプレート: ./templates/material.mdx

コンポーネント物料ドキュメント作成フロー

1. ソースコードの特定

packages/materials/form-materials/src/components ディレクトリで物料のソースコードの場所を確認します。

操作:

• Glob ツールを使用して物料ファイルを検索します
• ディレクトリ構造を確認します（hooks.ts、context.tsx などがあるか）
• エクスポート名とファイルパスを記録します

2. 要件収集

ユーザーに物料の使用例と具体的な要件を尋ねます。

収集情報:

• 主な使用シナリオ
• 典型的なコード例（1〜2個）
• 特殊な設定または高度な使用法
• 図が必要かどうか

3. 機能分析

ソースコードを深く読み込み、物料の機能を理解します。

分析の要点:

• Props インターフェース（型、デフォルト値、説明）
• コア機能と実装方法
• 依存関係（FlowGram API、他の物料、サードパーティライブラリ）
• Hooks と Context
• 特殊なロジック（条件付きレンダリング、副作用など）

4. Story の作成

apps/docs/components/form-materials/components に Story コンポーネントを作成します（以下の Story 規約を参照）。

5. ドキュメントの作成

テンプレート ./templates/material.mdx に基づいて完全なドキュメントを作成します。

ドキュメントの場所:

• 中国語：apps/docs/src/zh/materials/components/{物料名称}.mdx
• 英語：apps/docs/src/en/materials/components/{物料名称}.mdx（翻訳後）

6. 品質チェック

チェックリスト:

• [ ] Story コンポーネントが正常に動作する
• [ ] コード例が正確である
• [ ] API テーブルが完全である
• [ ] 依存関係リンクが正しくアクセス可能である
• [ ] 画像パスが正しい
• [ ] Mermaid フローチャートの構文が正しい
• [ ] CLI コマンドパスが正確である

ユーザーが中国語ドキュメントの作成を確認した後、翻訳を実行します。 ユーザーが中国語ドキュメントの作成を確認した後、翻訳を実行します。 ユーザーが中国語ドキュメントの作成を確認した後、翻訳を実行します。

Story コンポーネント規約

参考例: apps/docs/components/form-materials/components/variable-selector.tsx

命名規約

ファイル命名: kebab-case、物料名と一致

• ✅ variable-selector.tsx
• ✅ dynamic-value-input.tsx
• ❌ VariableSelector.tsx

Story エクスポート命名: PascalCase + "Story" サフィックス

• BasicStory - 基本的な使用（必須）
• WithSchemaStory - Schema 制約付き
• DisabledStory - 無効状態
• CustomFilterStory - カスタムフィルタ
• 物料の特性に応じて、意味がわかるように命名します

コード要件

1. 遅延ロードインポート

// ✅ 正しい
const VariableSelector = React.lazy(() =>
  import('@flowgram.ai/form-materials').then((module) => ({
    default: module.VariableSelector,
  }))
);

// ❌ 誤り
import { VariableSelector } from '@flowgram.ai/form-materials';

2. ラップコンポーネント

// ✅ 正しい
export const BasicStory = () => (
  <FreeFormMetaStoryBuilder
    filterEndNode
    formMeta={{
      render: () => (
        <>
          <FormHeader />
          <Field<string[]> name="variable_selector">
            {({ field }) => (
              <VariableSelector
                value={field.value}
                onChange={(value) => field.onChange(value)}
              />
            )}
          </Field>
        </>
      ),
    }}
  />
);

// ❌ 誤り：ラップがない
export const BasicStory = () => (
  <VariableSelector value={[]} onChange={() => {}} />
);

3. 型注釈

// ✅ 正しい
<Field<string[] | undefined> name="variable_selector">

// ❌ 誤り
<Field<any> name="variable_selector">

4. 言語規約

コードとコメントは英語のみを使用し、中国語は使用しません。

完全な例

/**
 * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
 * SPDX-License-Identifier: MIT
 */

import React from 'react';
import { Field } from '@flowgram.ai/free-layout-editor';
import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';

const VariableSelector = React.lazy(() =>
  import('@flowgram.ai/form-materials').then((module) => ({
    default: module.VariableSelector,
  }))
);

export const BasicStory = () => (
  <FreeFormMetaStoryBuilder
    filterEndNode
    formMeta={{
      render: () => (
        <>
          <FormHeader />
          <Field<string[] | undefined> name="variable_selector">
            {({ field }) => (
              <VariableSelector
                value={field.value}
                onChange={(value) => field.onChange(value)}
              />
            )}
          </Field>
        </>
      ),
    }}
  />
);

export const FilterSchemaStory = () => (
  <FreeFormMetaStoryBuilder
    filterEndNode
    formMeta={{
      render: () => (
        <>
          <FormHeader />
          <Field<string[] | undefined> name="variable_selector">
            {({ field }) => (
              <VariableSelector
                value={field.value}
                onChange={(value) => field.onChange(value)}
                includeSchema={{ type: 'string' }}
              />
            )}
          </Field>
        </>
      ),
    }}
  />
);

物料ドキュメント形式

テンプレートの使用

テンプレートファイル: ./templates/material.mdx

ドキュメントは、テンプレート形式に厳密に従って作成する必要があり、次の章が含まれます。

1. Import ステートメント
2. タイトルと概要（オプションの図付き）
3. ケースデモ（基本的な使用法 + 高度な使用法）
4. API リファレンス（Props テーブル）
5. ソースコードリーディング（ディレクトリ構造、コア実装、フローチャート、依存関係の整理）

参考例

• dynamic-value-input.mdx - 完全なフローチャートと依存関係の説明
• variable-selector.mdx - 複数の API テーブルと警告メッセージ

重要な注意事項

API テーブルの要件:

• すべての公開された Props を含める必要があります
• 型はバッククォートを使用します（例：`string`）
• 説明は明確かつ簡潔である必要があります
• 複数の関連する型を個別にリストします

ソースコードリーディングの要件:

• ディレクトリ構造：ファイルリストと説明を表示します
• コア実装：コードスニペットを使用してキーロジックを説明します
• 全体的なフロー：Mermaid フローチャート（推奨）
• 依存関係の整理：FlowGram API、他の物料、サードパーティライブラリを分類してリストします

画像処理ガイド

スクリーンショットの要件

1. タイミング: Story コンポーネントが完了したら、docs サイトを実行してスクリーンショットを撮ります
2. 内容: 物料の典型的な使用状態をキャプチャし、明確に表示します
3. 形式: PNG、適切に圧縮します

命名と保存

• 命名: {物料名称}.png（kebab-case）
• 保存: apps/docs/src/public/materials/{物料名称}.png
• 参照: /materials/{物料名称}.png

ドキュメントでの使用

<br />
<div>
  <img loading="lazy" src="/materials/{物料名称}.png" alt="{物料名称} コンポーネント" style={{ width: '50%' }} />
</div>

翻訳フロー

翻訳のタイミング

• ✅ ユーザーが明確に翻訳を要求した場合
• ✅ 中国語ドキュメントがユーザーによって承認された場合
• ❌ ドキュメントがまだ変更中の場合
• ❌ ユーザーが最終バージョンを確認していない場合

翻訳の原則

用語の一貫性:

• ComponentName → ComponentName（コンポーネント名は翻訳しない）
• Props、Hook、Schema などの用語は原文のまま

コードは翻訳しない:

• すべてのコードブロック、コマンド、パスは元のまま

リンク処理:

• 内部リンク：/zh/ → /en/
• 外部リンクと GitHub リンク：変更なし

形式の維持:

• Markdown 形式、インデント、空行は完全に一致

翻訳チェックリスト

• [ ] タイトルと説明が翻訳されている
• [ ] コード例が翻訳されていない
• [ ] コマンドとパスが元のまま
• [ ] 内部ドキュメントリンクが更新されている
• [ ] API テーブルの説明列が翻訳されている
• [ ] Mermaid 図の中国語ノードが翻訳されている
• [ ] 用語の使用が一貫している

ベストプラクティス

Props 抽出のヒント

1. interface または type 定義を検索します
2. コンポーネント関数のパラメータ型を確認します
3. defaultProps を検索してデフォルト値を確認します
4. JSDoc を読んで説明を抽出します

依存関係分析の方法

1. import ステートメントを確認します（直接的な依存関係）
2. Hook 呼び出しを分析します（FlowGram API）
3. コンポーネント参照を検索します（他の物料）
4. package.json を確認します（サードパーティライブラリ）

Mermaid フローチャートの推奨事項

1. 簡潔明瞭で、コアフローに焦点を当てます
2. シーケンス図を使用して描画します

よくある間違いの回避

❌ React.lazy を使用せずに物料を直接インポートする ❌ API テーブルで Props が欠落している ❌ 依存関係リンクが無効になっている ❌ 中国語と英語が混在している ❌ パス形式が間違っている

✅ 優れた例を参照する ✅ ソースコードを注意深く読む ✅ すべてのリンクを検証する ✅ 言語と形式の一貫性を保つ ✅ プロジェクトで合意されたパス形式を使用する

関連ツールとリソース

開発コマンド

# ドキュメントサイトを起動する
rush dev:docs

# 変更を確認する
git diff
git diff --cached

重要なディレクトリ

(原文がここで切り詰められています)