material-component-doc

FlowGram documentation organization structure

• English documentation: apps/docs/src/en
• Chinese documentation: apps/docs/src/zh
• Story component: apps/docs/components/form-materials/components
• Material source code: packages/materials/form-materials/src/components
• Documentation template: ./templates/material.mdx

Component material documentation writing process

1. Source code location

In the packages/materials/form-materials/src/components directory, confirm the material source code location.

Operations：

• Use the Glob tool to search for material files
• Confirm the directory structure (whether there are hooks.ts, context.tsx, etc.)
• Record the export names and file paths

2. Requirements gathering

Ask the user for material usage examples and specific requirements.

Collect information：

• Main usage scenarios
• Typical code examples (1-2)
• Special configurations or advanced usage
• Whether illustrations are needed

3. Function analysis

Read the source code in depth to understand the material functions.

Analysis points：

• Props interface (types, default values, descriptions)
• Core functions and implementation methods
• Dependencies (FlowGram API, other materials, third-party libraries)
• Hooks and Context
• Special logic (conditional rendering, side effects, etc.)

4. Story creation

Create the Story component under apps/docs/components/form-materials/components (see the Story specification below for details).

5. Documentation writing

Based on the template ./templates/material.mdx , write the complete documentation.

Documentation location：

• Chinese:apps/docs/src/zh/materials/components/{物料名称}.mdx
• English:apps/docs/src/en/materials/components/{物料名称}.mdx(after translation)

6. Quality check

Checklist：

• The Story component runs properly
• The code examples are accurate
• The API table is complete
• The dependency links are correct and accessible
• The image paths are correct
• The Mermaid flowchart syntax is correct
• The CLI command paths are accurate

After the user confirms the writing of the Chinese documentation, then execute the translation。 After the user confirms the writing of the Chinese documentation, then execute the translation。 After the user confirms the writing of the Chinese documentation, then execute the translation。

Story component specification

Reference examples: apps/docs/components/form-materials/components/variable-selector.tsx

Naming conventions

File naming: kebab-case, consistent with the material name

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

Story export naming: PascalCase + "Story" suffix

• BasicStory - Basic usage (required)
• WithSchemaStory - With Schema constraints
• DisabledStory - Disabled state
• CustomFilterStory - Custom filtering
• Name according to the material characteristics, so the name conveys the meaning

Code requirements

1. Lazy loading imports

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

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

2. Wrapper component

// ✅ 正确
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. Type annotations

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

// ❌ 错误
<Field<any> name="variable_selector">

4. Language conventions

Code and comments use only English, with no Chinese.

Complete example

/**
 * 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>
        </>
      ),
    }}
  />
);

---

Material documentation format

Using the template

Template file: ./templates/material.mdx

The documentation must be written strictly according to the template format, including the following sections:

1. Import statement
2. Title and introduction (with optional illustrations)
3. Case demonstration (basic usage + advanced usage)
4. API reference (Props table)
5. Source code guide (directory structure, core implementation, flowcharts, dependency analysis)

Reference examples

• dynamic-value-input.mdx - Complete flowcharts and dependency descriptions
• variable-selector.mdx - Multiple API tables and warning notices

Key considerations

API table requirements：

• Must include all public Props
• Types use backticks (e.g. `string`）
• Descriptions are clear and concise
• Multiple related types are listed separately

Source code guide requirements：

• Directory structure: display the file list and descriptions
• Core implementation: use code snippets to explain key logic
• Overall flow: Mermaid flowchart (recommended)
• Dependency analysis: list FlowGram APIs, other materials, and third-party libraries by category

---

Image handling guide

Screenshot requirements

1. Timing: After the Story component is completed, run the docs site to take screenshots
2. Content: Capture the material's typical usage state, clearly visible
3. Format: PNG, appropriately compressed

Naming and storage

• Naming: {物料名称}.png（kebab-case）
• Storage: apps/docs/src/public/materials/{物料名称}.png
• Reference: /materials/{物料名称}.png

Use in documentation

<br />
<div>
  <img loading="lazy" src="/materials/{物料名称}.png" alt="{物料名称} 组件" style={{ width: '50%' }} />
</div>

---

Translation workflow

Translation timing

• ✅ The user explicitly requests translation
• ✅ The Chinese documentation has been reviewed and confirmed by the user
• ❌ The documentation is still being modified
• ❌ The user has not confirmed the final version

Translation principles

Terminology consistency：

• ComponentName → ComponentName (component names are not translated)
• Terms such as Props, Hook, and Schema remain in their original form

Code is not translated：

• All code blocks, commands, and paths remain unchanged

Link handling：

• Internal links:/zh/ → /en/
• External links and GitHub links: remain unchanged

Format preservation：

• Markdown formatting, indentation, and blank lines are exactly the same

Translation checklist

• Titles and descriptions have been translated
• Code examples have not been translated
• Commands and paths remain unchanged
• Internal documentation links have been updated
• The description column of the API table has been translated
• Chinese nodes in the Mermaid diagram have been translated
• Terminology usage is consistent

---

Best practices

Props extraction techniques

1. Find the interface or type definition
2. Check the component function parameter types
3. Find defaultProps to confirm default values
4. Read JSDoc to extract descriptions

Dependency analysis methods

1. Check import statements (direct dependencies)
2. Analyze Hook calls (FlowGram APIs)
3. Find component references (other materials)
4. Check package.json (third-party libraries)

Mermaid flowchart suggestions

1. Concise and clear, focus on the core flow
2. Use sequence diagrams to draw

Avoiding common mistakes

❌ Directly importing materials without using React.lazy ❌ Missing Props in API table ❌ Broken dependency links ❌ Mixed use of Chinese and English ❌ Incorrect path format

✅ Refer to excellent examples ✅ Read the source code carefully ✅ Verify all links ✅ Keep language and format consistent ✅ Use the path format agreed upon by the project

---

Related tools and resources

Development Commands

# 启动文档站点
rush dev:docs

# 查看修改
git diff
git diff --cached

Key Directories

Directory	Description
packages/materials/form-materials/src/components	Material source code
apps/docs/src/zh/materials/components	Chinese documentation
apps/docs/src/en/materials/components	English documentation
apps/docs/components/form-materials/components	Story component
apps/docs/src/public/materials	Image assets
./templates	Documentation template