### Install and Start FlowGram Project

Source: https://github.com/bytedance/flowgram.ai/blob/main/README.md

After creating a new project, navigate to the project directory, install dependencies, and start the development server.

```sh
cd demo-free-layout
npm install
npm start
```

--------------------------------

### Run the development server

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/demo-nextjs/README.md

Use these commands to start the local development environment. Ensure the appropriate package manager is installed.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### CLI Output Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/cli.mdx

Example output after running the materials command.

```console
🚀 Welcome to @flowgram.ai form-materials CLI!
📁 Project: /path/to/your/project
🎯 Flowgram Version: 1.0.0
  - Target material root: /path/to/your/project/src/form-materials

🚀 The following materials will be added to your project
📦 components/json-schema-editor
📦 components/variable-selector
📦 effect/provideJsonSchemaOutputs

✅ These npm dependencies is added to your package.json
- @semi-design/icons
- lodash-es
- classnames

➡️ Please run npm install to install dependencies
```

--------------------------------

### Start FlowGram NodeJS Server

Source: https://github.com/bytedance/flowgram.ai/blob/main/packages/runtime/nodejs/README.md

Use this command to start the development server. Ensure dependencies are installed.

```bash
pnpm dev
```

--------------------------------

### Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/plugin/background-plugin.mdx

An example demonstrating how to use the background configuration within editor properties.

```APIDOC
## Usage Example

This example shows how to apply the background configuration directly within the editor's properties.

### Request Body Example

```json
{
  "background": {
    "backgroundColor": "#1a1a1a",
    "dotColor": "#ffffff",
    "dotSize": 1,
    "gridSize": 20,
    "dotOpacity": 0.3,
    "logo": {
      "text": "FLOWGRAM.AI",
      "position": "center",
      "size": 200,
      "opacity": 0.25,
      "color": "#ffffff",
      "fontFamily": "Arial, sans-serif",
      "fontWeight": "bold",
      "neumorphism": {
        "enabled": true,
        "textColor": "#E0E0E0",
        "lightShadowColor": "rgba(255,255,255,0.9)",
        "darkShadowColor": "rgba(0,0,0,0.15)",
        "shadowOffset": 6,
        "shadowBlur": 12,
        "intensity": 0.6,
        "raised": true
      }
    }
  }
}
```
```

--------------------------------

### Source Code Installation

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/inputs-values-tree.mdx

Instructions on how to install the InputsValuesTree component locally using the CLI.

```APIDOC
## Source Code Installation

### Description
Use the following CLI command to copy the source code of the InputsValuesTree component to your local project.

### Command

```bash
npx @flowgram.ai/cli@latest materials components/inputs-values-tree
```

### Directory Structure

```plaintext
components/inputs-values-tree/
├── index.tsx          # Component entry file
├── row.tsx            # Tree row component, handles display and editing of individual nodes
├── types.ts           # Type definitions
├── icon.tsx           # Icon components
├── styles.css         # Component styles
└── hooks/
    └── use-child-list.tsx # Custom hook for handling child node lists
```
```

--------------------------------

### Install project dependencies

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/quick-start.mdx

Install the necessary packages for the project.

```npm
npm install
```

```pnpm
pnpm install
```

```yarn
yarn install
```

```bun
bun install
```

--------------------------------

### Install dependencies

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/README.md

Run this command to install all project dependencies using Rush.

```bash
rush update
```

--------------------------------

### Install styled-components

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/free-layout.mdx

Install styled-components if it is not already present in your project.

```bash
npm install styled-components
```

```bash
pnpm add styled-components
```

```bash
yarn add styled-components
```

```bash
bun add styled-components
```

--------------------------------

### Start development server

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/quick-start.mdx

Launch the local development environment.

```npm
npm run dev
```

```pnpm
pnpm dev
```

```yarn
yarn dev
```

```bun
bun dev
```

--------------------------------

### Run development server

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/README.md

Navigate to the documentation directory and start the development server.

```bash
cd apps/docs
rushx dev
```

--------------------------------

### Run development environments

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/contributing.mdx

Start the documentation site or specific demo layouts.

```bash
rush dev:docs                  # Start the documentation site in apps/docs (with incremental build)
rush dev:demo-fixed-layout     # Run the fixed layout example
rush dev:demo-free-layout      # Run the free layout example
```

--------------------------------

### Install Flowgram.ai Plugins

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/free-layout.mdx

Install the free snap and minimap plugins using your preferred package manager.

```bash
npm install @flowgram.ai/free-snap-plugin @flowgram.ai/minimap-plugin
```

```bash
pnpm add @flowgram.ai/free-snap-plugin @flowgram.ai/minimap-plugin
```

```bash
yarn add @flowgram.ai/free-snap-plugin @flowgram.ai/minimap-plugin
```

```bash
bun add @flowgram.ai/free-snap-plugin @flowgram.ai/minimap-plugin
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/bytedance/flowgram.ai/blob/main/e2e/fixed-layout/README.md

Use these commands to install project dependencies and execute the end-to-end tests. Ensure you are in the correct directory before running.

```bash
rush update
```

```bash
cd e2e/fixed-layout & npm run e2e:test
```

```bash
cd e2e/fixed-layout & npm run e2e:update-screenshot
```

--------------------------------

### Install Node.js LTS

Source: https://github.com/bytedance/flowgram.ai/blob/main/CONTRIBUTING.md

Installs and sets the default Node.js version using nvm. Recommended for project compatibility.

```bash
nvm install lts/hydrogen
nvm alias default lts/hydrogen # set default node version
nvm use lts/hydrogen
```

--------------------------------

### Install and Run CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/cli.mdx

Execute the CLI tool directly using npx.

```bash
npx @flowgram.ai/cli@latest [command]
```

--------------------------------

### Install Rush Globally

Source: https://github.com/bytedance/flowgram.ai/blob/main/CLAUDE.md

Install the Rush tool globally to execute commands across the repository.

```bash
npm install -g @microsoft/rush
```

--------------------------------

### Run Development Server

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/examples/free-layout/free-layout-simple.mdx

Command to start the local development environment.

```bash
npm run dev
```

--------------------------------

### BatchVariableSelector CLI Installation

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/materials/components/batch-variable-selector.mdx

Instructions on how to install the BatchVariableSelector component locally using the FlowGram CLI.

```APIDOC
## Source Code

You can copy the source code locally using the following CLI command:

```bash
npx @flowgram.ai/cli@latest materials components/batch-variable-selector
```
```

--------------------------------

### Install Fixed Layout Editor Dependencies

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/guide/getting-started/fixed-layout.mdx

Install the necessary editor and materials packages using your preferred package manager. Also, ensure styled-components is installed if not already present.

```bash
npm install @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials
```

```bash
pnpm add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials
```

```bash
yarn add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials
```

```bash
bun add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials
```

```bash
npm install styled-components
```

```bash
pnpm add styled-components
```

```bash
yarn add styled-components
```

```bash
bun add styled-components
```

--------------------------------

### Install Materials via CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/batch-outputs.mdx

Command to copy the batch-outputs source code locally.

```bash
npx @flowgram.ai/cli@latest materials components/batch-outputs
```

--------------------------------

### Install Free Layout Editor Package

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/free-layout.mdx

Install the editor package using your preferred package manager.

```bash
npm install @flowgram.ai/free-layout-editor
```

```bash
pnpm add @flowgram.ai/free-layout-editor
```

```bash
yarn add @flowgram.ai/free-layout-editor
```

```bash
bun add @flowgram.ai/free-layout-editor
```

--------------------------------

### Start FlowGram Runtime Service

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/runtime/quick-start.mdx

Navigate to the runtime directory and start the Node.js server using npm. This command initiates the FlowGram Runtime service.

```bash
cd packages/runtime/nodejs
npm run dev
```

--------------------------------

### Install Editor Dependencies

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/fixed-layout.mdx

Install the core editor packages and styled-components using your preferred package manager.

```bash
npm install @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials

```

```bash
pnpm add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials

```

```bash
yarn add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials

```

```bash
bun add @flowgram.ai/fixed-layout-editor @flowgram.ai/fixed-semi-materials

```

```bash
npm install styled-components

```

```bash
pnpm add styled-components

```

```bash
yarn add styled-components

```

```bash
bun add styled-components

```

--------------------------------

### Install @flowgram.ai/free-auto-layout-plugin

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/guide/plugin/free-auto-layout-plugin.mdx

Use this command to install the auto layout plugin via npm or yarn.

```bash
npm install @flowgram.ai/free-auto-layout-plugin
# or
yarn add @flowgram.ai/free-auto-layout-plugin
```

--------------------------------

### Register Start Node Configuration

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/examples/free-layout/free-feature-overview.mdx

Defines the configuration for the 'start' node, including its type, metadata (like non-deletable and non-copyable), default ports, size, and information.

```typescript
export const StartNodeRegistry: FlowNodeRegistry = {
  type: WorkflowNodeType.Start,
  meta: {
    isStart: true,
    deleteDisable: true,        // Not deletable
    copyDisable: true,          // Not copyable
    nodePanelVisible: false,    // Hidden in node panel
    defaultPorts: [{ type: 'output' }],
    size: { width: 360, height: 211 }
  },
  info: {
    icon: iconStart,
    description: 'The starting node of the workflow, used to set up information needed to launch the workflow.'
  },
  formMeta,
  canAdd() { return false; }    // Disallow multiple start nodes
};
```

--------------------------------

### Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/db-condition-row.mdx

Demonstrates the basic usage of the DBConditionRow component with predefined options.

```APIDOC
## Basic Usage

```tsx
import { DBConditionRow } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<any | undefined> name="db_condition_row">
        {({ field }) => (
          <DBConditionRow
            options={[
              {
                label: 'TransactionID',
                value: 'transaction_id',
                schema: { type: 'integer' },
              },
              {
                label: 'Amount',
                value: 'amount',
                schema: { type: 'number' },
              },
              {
                label: 'Description',
                value: 'description',
                schema: { type: 'string' },
              },
              {
                label: 'Archived',
                value: 'archived',
                schema: { type: 'boolean' },
              },
              {
                label: 'CreateTime',
                value: 'create_time',
                schema: { type: 'date-time' },
              },
            ]}
            value={field.value}
            onChange={(value) => field.onChange(value)}
          />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/materials/components/dynamic-value-input.mdx

Demonstrates the basic implementation of the DynamicValueInput component.

```APIDOC
## Basic Usage

### Code Example

```tsx
import { DynamicValueInput } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<any> name="dynamic_value_input">
        {({ field }) => (
          <DynamicValueInput value={field.value} onChange={(value) => field.onChange(value)} />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Install DisplaySchemaTree Component

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/display-schema-tree.mdx

Use this CLI command to copy the source code for the DisplaySchemaTree component locally. This command requires the @flowgram.ai/cli to be installed.

```bash
npx @flowgram.ai/cli@latest materials components/display-schema-tree
```

--------------------------------

### CLI Installation Command

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/inputs-values-tree.mdx

Command to copy the source code for the InputsValuesTree component locally.

```bash
npx @flowgram.ai/cli@latest materials components/inputs-values-tree
```

--------------------------------

### Install Plugin via CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/form-plugins/infer-inputs-plugin.mdx

Command to copy the plugin source code into the local project.

```bash
npx @flowgram.ai/cli@latest materials form-plugins/infer-inputs-plugin
```

--------------------------------

### Start Node Registry Configuration

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/examples/free-layout/free-feature-overview.mdx

Configuration for the 'Start' node, specifying its metadata, information, form structure, and behavior constraints.

```typescript
export const StartNodeRegistry: FlowNodeRegistry = {
  type: WorkflowNodeType.Start,
  meta: {
    isStart: true,
    deleteDisable: true,        // 不可删除
    copyDisable: true,          // 不可复制
    nodePanelVisible: false,    // 不在节点面板显示
    defaultPorts: [{ type: 'output' }],
    size: { width: 360, height: 211 }
  },
  info: {
    icon: iconStart,
    description: '工作流的起始节点，用于设置启动工作流所需的信息。'
  },
  formMeta,
  canAdd() { return false; }    // 不允许添加多个开始节点
};
```

--------------------------------

### Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/prompt-editor-with-variables.mdx

Demonstrates the basic integration of PromptEditorWithVariables in a form.

```APIDOC
## Basic Usage

To use the `PromptEditorWithVariables`, you can integrate it within a form context. Trigger the variable selector by typing `@` or `{` in the editor. Selecting a variable inserts it in the `{{variable.path}}` format.

### Request Example (form-meta.tsx)

```tsx
import { PromptEditorWithVariables } from '@flowgram.ai/form-materials';
import { Field } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <Field<any> name="prompt_template" defaultValue={{
              type: 'template',
              content: `# Role\nYou are a helpful assistant\n# Query\n{{start_0.str}}`,
            }}>
        {({ field }) => (
          <PromptEditorWithVariables
            value={field.value}
            onChange={(value) => field.onChange(value)}
          />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/inputs-values-tree.mdx

Demonstrates the basic implementation of the InputsValuesTree component within a form.

```APIDOC
## Basic Usage Example

### Description
This example shows how to integrate the InputsValuesTree component into a form, providing an initial nested structure for input values.

### Code

```tsx
import { InputsValuesTree } from '@flowgram.ai/form-materials';
import { FormHeader } from 'components/form-header'; // Assuming FormHeader is available
import { Field } from '@formily/react'; // Assuming Field is from Formily

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<Record<string, any> | undefined>
        name="inputs_values"
        defaultValue={{
          a: {
            b: {
              type: 'ref',
              content: ['start_0', 'str'],
            },
            c: {
              type: 'constant',
              content: 'hello',
            },
          },
          d: {
            type: 'constant',
            content: '{ "a": "b"}',
            schema: { type: 'object' },
          },
        }}
      >
        {({ field }) => (
          <InputsValuesTree value={field.value} onChange={(value) => field.onChange(value)} />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Install listenRefValueChange via CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/effects/listen-ref-value-change.mdx

Command to copy the source code for the listenRefValueChange effect locally.

```bash
npx @flowgram.ai/cli@latest materials effects/listen-ref-value-change
```

--------------------------------

### Install Batch Outputs Plugin CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/form-plugins/batch-outputs-plugin.mdx

CLI command to copy the source code locally.

```bash
npx @flowgram.ai/cli@latest materials form-plugins/batch-outputs-plugin
```

--------------------------------

### Initialize Project Environment

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/examples/free-layout/free-layout-simple.mdx

Use the scaffolding tool to generate a new project and install necessary dependencies.

```bash
# Use the scaffolding tool to quickly create a project
npx @flowgram.ai/create-app@latest free-layout-simple

# Enter the project directory
cd free-layout-simple

# Install dependencies
npm install
```

--------------------------------

### Get Variable Tree via useVariableTree Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/variable-selector.mdx

Demonstrates fetching the variable tree data using the `useVariableTree` hook and rendering it.

```APIDOC
## Get Variable Tree via useVariableTree

### Code Example

```tsx
import { useVariableTree } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => {
    const treeData = useVariableTree({});

    return (
      <VariableSelectorProvider skipVariable={(variable) => variable?.key === 'str'}>
        <FormHeader />
        <Tree treeData={treeData} defaultExpandAll />
      </VariableSelectorProvider>
    );
  },
}
```

### Related Components

`useVariableTree` is also utilized in components such as [`PromptEditorWithVariables`](./prompt-editor-with-variables), [`SQLEditorWithVariables`](./sql-editor-with-variables), and [`JsonEditorWithVariables`](./json-editor-with-variables) to retrieve the variable tree for the current scope.
```

--------------------------------

### Apply Preset Styles

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/guide/plugin/background-plugin.mdx

Provides examples for classic dark and minimalist white theme configurations.

```tsx
const editorProps = {
  background: {
    backgroundColor: '#1a1a1a',
    dotColor: '#ffffff',
    dotSize: 1,
    gridSize: 20,
    dotOpacity: 0.3,
    logo: {
      text: '您的品牌',
      position: 'center',
      size: 200,
      opacity: 0.25,
      color: '#ffffff',
      neumorphism: {
        enabled: true,
        textColor: '#E0E0E0',
        lightShadowColor: 'rgba(255,255,255,0.9)',
        darkShadowColor: 'rgba(0,0,0,0.15)',
        shadowOffset: 6,
        shadowBlur: 12,
        intensity: 0.6,
        raised: true
      }
    }
  }
}
```

```tsx
const editorProps = {
  background: {
    backgroundColor: '#ffffff',
    dotColor: '#000000',
    dotSize: 1,
    gridSize: 20,
    dotOpacity: 0.1,
    logo: {
      text: '您的品牌',
      position: 'center',
      size: 200,
      opacity: 0.1,
      color: '#000000'
    }
  }
}
```

--------------------------------

### Define Initial Canvas Data Structure

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/fixed-layout/load.mdx

Configure flow data using a nested block structure. This example shows the basic structure for nodes, including start, condition, and end nodes with their respective data and blocks.

```tsx
import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';

/**
 * Configure flow data, data is in blocks nested format
 */
export const initialData: FlowDocumentJSON = {
  nodes: [
    // Start node
    {
      id: 'start_0',
      type: 'start',
      data: {
        title: 'Start',
        content: 'start content'
      },
      blocks: [],
    },
    // Condition node
    {
      id: 'condition_0',
      type: 'condition',
      data: {
        title: 'Condition'
      },
      blocks: [
        {
          id: 'branch_0',
          type: 'block',
          data: {
            title: 'Branch 0',
            content: 'branch 1 content'
          },
          blocks: [
            {
              id: 'custom_0',
              type: 'custom',
              data: {
                title: 'Custom',
                content: 'custrom content'
              },
            },
          ],
        },
        {
          id: 'branch_1',
          type: 'block',
          data: {
            title: 'Branch 1',
            content: 'branch 1 content'
          },
          blocks: [],
        },
      ],
    },
    // End node
    {
      id: 'end_0',
      type: 'end',
      data: {
        title: 'End',
        content: 'end content'
      },
    },
  ],
};
```

--------------------------------

### Set up Node.js environment

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/contributing.mdx

Configure the required Node.js version using nvm.

```bash
nvm install lts/hydrogen
nvm alias default lts/hydrogen # Set as the default Node version
nvm use lts/hydrogen
```

--------------------------------

### Comprehensive Global Scope Operations in Plugin

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/variable/variable-output.mdx

Demonstrates CRUD operations for global variables, including setting, getting, and clearing variables, both globally and within specific namespaces. This example illustrates the full capability of the GlobalScope API within a plugin's `onInit` lifecycle.

```tsx
import {
  GlobalScope,
} from '@flowgram.ai/fixed-layout-editor';

// ...

onInit(ctx, options) {
  const globalScope = ctx.get(GlobalScope);

  // 1. Create, Update, Read, Delete Variable in GlobalScope
  globalScope.setVar(
    ASTFactory.createVariableDeclaration({
      meta: {
        title: `Your Output Variable Title`,
      },
      key: `your_variable_global_unique_key`,
      type: ASTFactory.createString(),
    })
  )

  console.log(globalScope.getVar())

  globalScope.clearVar()

  // 2. Create, Update, Read, Delete Variable in GlobalScope's namespace: 'namespace_1'
    globalScope.setVar(
      'namespace_1',
      ASTFactory.createVariableDeclaration({
        meta: {
          title: `Your Output Variable Title 2`,
        },
        key: `uid_2`,
        type: ASTFactory.createString(),
      })
  )

  console.log(globalScope.getVar('namespace_1'))

  globalScope.clearVar('namespace_1')

  // ...
}

```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/bytedance/flowgram.ai/blob/main/AGENTS.md

Use this command to install all project dependencies managed by Rush. Ensure Node.js 18 LTS and pnpm 10.6.5 are installed.

```bash
rush install
```

--------------------------------

### Sync Workflow Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/cli.mdx

A complete workflow to find used materials and sync them to a custom directory.

```bash
npx @flowgram.ai/cli@latest find-used-materials
```

```console
📦 All used materials:
components/json-schema-editor,components/variable-selector
```

```bash
npx @flowgram.ai/cli@latest materials components/json-schema-editor,components/variable-selector \
  --target-material-root-dir src/custom-materials \
  --refresh-project-imports
```

--------------------------------

### Commit message example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/contributing.mdx

Example of a conventional commit message format.

```text
feat(editor): Support batch alignment of nodes
```

--------------------------------

### Preview production build

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/README.md

Serve the production build locally to verify the site before deployment.

```bash
rushx preview
```

--------------------------------

### Install @flowgram.ai/export-plugin

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/plugin/export-plugin.mdx

Use this command to install the export plugin via npm.

```bash
npm install @flowgram.ai/export-plugin
```

--------------------------------

### Install @flowgram.ai/minimap-plugin

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/plugin/minimap-plugin.mdx

Use the package manager command to install the minimap plugin dependency.

```bash
npm install @flowgram.ai/minimap-plugin
```

--------------------------------

### DisplayFlowValue Component Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/materials/components/display-flow-value.mdx

Example of how to use the DisplayFlowValue component within a form.

```APIDOC
## DisplayFlowValue Component Usage Example

### Description

This example demonstrates how to integrate the `DisplayFlowValue` component into a form using `form-meta.tsx`. It shows how to handle dynamic value inputs and display them using `DisplayFlowValue`.

### Code Example

```tsx
import { Field } from '@formily/react';
import { DynamicValueInput } from 'components/form-materials/components/dynamic-value-input'; // Assuming this path
import { DisplayFlowValue } from 'components/form-materials/components/display-flow-value'; // Assuming this path

const formMeta = {
  render: () => (
    <>
      <Field<any> name="dynamic_value_input">
        {({ field }) => (
          <DynamicValueInput value={field.value} onChange={(value) => field.onChange(value)} />
        )}
      </Field>
      <Field<any> name="dynamic_value_input">
        {({ field }) => <DisplayFlowValue value={field.value} title="Display Flow Value" />}
      </Field>
    </>
  ),
};
```

### Notes

- The example assumes the existence of `DynamicValueInput` and `DisplayFlowValue` components at the specified import paths.
- The `Field` component is likely from a form library like Formily.
```

--------------------------------

### Install BlurInput via CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/blur-input.mdx

Command to copy the BlurInput component source code to a local project.

```bash
npx @flowgram.ai/cli@latest materials components/blur-input
```

--------------------------------

### Start Node

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/demo-fixed-layout/README.zh_CN.md

Definition for the 'Start' node. This node marks the beginning of the flow execution.

```typescript
│   ├── start/                 # 开始节点
```

```typescript
│   │   ├── index.ts
```

```typescript
│   │   └── form-meta.tsx
```

--------------------------------

### Run Docs or Demo

Source: https://github.com/bytedance/flowgram.ai/blob/main/CONTRIBUTING.md

Commands to run the project's documentation site or demo applications.

```bash
rush dev:docs # docs
rush dev:demo-fixed-layout
rush dev:demo-free-layout
```

--------------------------------

### Install Minimap Plugin

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/fixed-layout.mdx

Install the minimap plugin dependency using your preferred package manager.

```npm
npm install @flowgram.ai/minimap-plugin
```

```pnpm
pnpm add @flowgram.ai/minimap-plugin
```

```yarn
yarn add @flowgram.ai/minimap-plugin
```

```bun
bun add @flowgram.ai/minimap-plugin
```

--------------------------------

### Install FlowGram.AI Fixed Layout

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/demo-fixed-layout/README.md

Use the npx command to initialize a new project with the fixed-layout template.

```shell
npx @flowgram.ai/create-app@latest fixed-layout
```

--------------------------------

### Build for production

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/README.md

Compile the website for production deployment.

```bash
rushx build
```

--------------------------------

### Value Structure Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/batch-outputs.mdx

An example illustrating the expected structure of the value when using the BatchOutputs component.

```APIDOC
## Value Structure Example

This example demonstrates the typical structure of the data managed by the BatchOutputs component, particularly when dealing with references to variables within loops.

```typescript
{
  names: { type: 'ref', content: ['loop_1_locals', 'item', 'name'] },
  ages: { type: 'ref', content: ['loop_1_locals', 'item', 'age'] },
  scores: { type: 'ref', content: ['loop_1_locals', 'item', 'score'] },
}
```
```

--------------------------------

### Navigate to project directory

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/quick-start.mdx

Change into the directory created by the scaffolding tool.

```sh
cd [project-name]
```

--------------------------------

### initial-data.ts - Step 5

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/free-layout.mdx

Provides the initial nodes and edges for the editor. This example includes custom nodes and multiple connections.

```ts
import type {
  EditorNode,
  EditorEdge,
  EditorState,
} from "@flowgram.ai/editor";

export interface InitialData extends EditorState {
  nodes: EditorNode[];
  edges: EditorEdge[];
}

export const initialData: InitialData = {
  nodes: [
    { id: "node-1", type: "custom", data: { title: "Node A" } },
    { id: "node-2", type: "custom", data: { title: "Node B" } },
    { id: "node-3", type: "custom", data: { title: "Node C" } },
    { id: "node-4", type: "custom", data: { title: "Node D" } },
    { id: "node-5", type: "custom", data: { title: "Node E" } },
  ],
  edges: [
    { id: "edge-1", source: "node-1", target: "node-2" },
    { id: "edge-2", source: "node-2", target: "node-3" },
    { id: "edge-3", source: "node-3", target: "node-4" },
    { id: "edge-4", source: "node-4", target: "node-5" },
    { id: "edge-5", source: "node-1", target: "node-3" },
  ],
};

```

--------------------------------

### Install Global Dependencies

Source: https://github.com/bytedance/flowgram.ai/blob/main/CONTRIBUTING.md

Installs required global Node.js packages, pnpm and Rush, with specific versions.

```bash
npm i -g pnpm@10.6.5 @microsoft/rush@5.150.0
```

--------------------------------

### AssignRow Component Usage Examples

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/assign-row.mdx

Examples demonstrating how to use the AssignRow component in both assignment and declaration modes.

```APIDOC
## Assignment Mode Example

AssignRow defaults to assignment mode. In this mode, the left side is a variable selector, and the right side is a dynamic value input.

```tsx
import { AssignRow } from '@flowgram.ai/form-materials';
import { AssignValueType } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<AssignValueType | undefined> name="assign_row">
        {({ field }) => (
          <AssignRow value={field.value} onChange={(value) => field.onChange(value)} />
        )}
      </Field>
    </>
  ),
}
```

## Declaration Mode Example

In declaration mode, the left side is a text input for a new variable name, and the right side is a dynamic value input.

```tsx
import { AssignRow } from '@flowgram.ai/form-materials';
import { AssignValueType } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<AssignValueType | undefined> name="assign_row">
        {({ field }) => (
          <AssignRow
            value={{
              operator: 'declare',
              left: 'newVariable',
              right: {
                type: 'constant',
                content: 'Hello World',
                schema: { type: 'string' },
              },
            }}
            onChange={(value) => field.onChange(value)} />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Install Plugin via CLI

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/common/disable-declaration-plugin.mdx

Use the CLI to copy the plugin source code into your local project.

```bash
npx @flowgram.ai/cli@latest materials plugins/disable-declaration-plugin
```

--------------------------------

### Install DisplayOutputs Component Locally

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/display-outputs.mdx

Use this CLI command to copy the source code for the DisplayOutputs component locally. This is useful for development or customization.

```bash
npx @flowgram.ai/cli@latest materials display-outputs
```

--------------------------------

### DBConditionRow Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/zh/materials/components/db-condition-row.mdx

Example demonstrating the basic usage of the DBConditionRow component with form meta configuration.

```APIDOC
```tsx
import { DBConditionRow } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      <Field<any | undefined> name="db_condition_row">
        {({ field }) => (
          <DBConditionRow
            options={[
              {
                label: 'TransactionID',
                value: 'transaction_id',
                schema: { type: 'integer' },
              },
              {
                label: 'Amount',
                value: 'amount',
                schema: { type: 'number' },
              },
              {
                label: 'Description',
                value: 'description',
                schema: { type: 'string' },
              },
              {
                label: 'Archived',
                value: 'archived',
                schema: { type: 'boolean' },
              },
              {
                label: 'CreateTime',
                value: 'create_time',
                schema: { type: 'date-time' },
              },
            ]}
            value={field.value}
            onChange={(value) => field.onChange(value)}
          />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### BatchVariableSelector Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/batch-variable-selector.mdx

Example demonstrating how to use the BatchVariableSelector component within a form, contrasting it with the standard VariableSelector.

```APIDOC
## Basic Usage

```tsx pure title="form-meta.tsx"
import { BatchVariableSelector, VariableSelector } from '@flowgram.ai/form-materials';

const formMeta = {
  render: () => (
    <>
      <FormHeader />
      {/* BatchVariableSelector only shows array-type variables */}
      <Field<string[] | undefined> name="batch_variable">
        {( { field } ) => (
          <BatchVariableSelector
            value={field.value}
            onChange={(value) => field.onChange(value)}
          />
        )}
      </Field>

      {/* VariableSelector shows all variable types */}
      <Field<string[] | undefined> name="normal_variable">
        {( { field } ) => (
          <VariableSelector
            value={field.value}
            onChange={(value) => field.onChange(value)}
          />
        )}
      </Field>
    </>
  ),
}
```
```

--------------------------------

### Provide Batch Input Effect - Source Code Guide

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/effects/provide-batch-input.mdx

Instructions on how to access and use the source code for the provideBatchInputEffect, including a CLI command to copy it locally and a description of the directory structure.

```APIDOC
## Source Code Guide

Use the CLI command to copy the source code locally:

```bash
npx @flowgram.ai/cli@latest materials effects/provide-batch-input
```

### Directory Structure

```
provide-batch-input/
└── index.ts           # Main implementation file, exports provideBatchInputEffect form effect
```
```

--------------------------------

### Example Barrel File

Source: https://github.com/bytedance/flowgram.ai/blob/main/AGENTS.md

Public API surfaces should be documented via barrel files. This example shows exporting from `index.ts`.

```typescript
export * from "./core";
export * from "./utils";
```

--------------------------------

### Create Application Entry Point

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/examples/free-layout/free-layout-simple.mdx

Sets up the React application entry point, rendering the main Editor component into the DOM. This is the root of the application. Ensure a DOM element with the ID 'root' exists.

```tsx
import React from 'react';
import ReactDOM from 'react-dom';

import { Editor } from './editor';

ReactDOM.render(<Editor />, document.getElementById('root'))
```

--------------------------------

### Infer Assign Plugin - Basic Usage Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/form-plugins/infer-assign-plugin.mdx

Example demonstrating the basic usage of the inferAssignPlugin within a form, including variable declarations and assignments.

```APIDOC
## Basic Usage Example

### Description
This example shows how to integrate the `inferAssignPlugin` into a form using `AssignRows` and `DisplayOutputs`.

### Code
```tsx
import { createInferAssignPlugin, AssignRows, DisplayOutputs } from '@flowgram.ai/form-materials';

export const VariableFormRender = ({ form }) => {
  return (
    <>
      <FormHeader />
      <AssignRows
        name="assign"
        defaultValue={[
          // Declare variable from constant
          {
            operator: 'declare',
            left: 'userName',
            right: {
              type: 'constant',
              content: 'John Doe',
              schema: { type: 'string' },
            },
          },
          // Declare variable from variable
          {
            operator: 'declare',
            left: 'userInfo',
            right: {
              type: 'ref',
              content: ['start_0', 'obj'],
            },
          },
          // Assign existing variable
          {
            operator: 'assign',
            left: {
              type: 'ref',
              content: ['start_0', 'str'],
            },
            right: {
              type: 'constant',
              content: 'Hello Flowgram',
              schema: { type: 'string' },
            },
          },
        ]} />
      <DisplayOutputs displayFromScope />
    </>
  );
};

export const formMeta: FormMeta = {
  render: VariableFormRender,
  plugins: [
    createInferAssignPlugin({
      assignKey: 'assign',
      outputKey: 'outputs'
    })
  ],
};
```

### Notes
- The `assignKey` option in `createInferAssignPlugin` specifies the form field where assignment operations are stored.
- The `outputKey` option specifies the form field where the generated JSON Schema for output variables will be stored.
- Refer to the Debug panel in the demo to view the JSON data sent to the backend.
```

--------------------------------

### Install Flowgram.ai fixed-layout-simple app

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/examples/fixed-layout/fixed-composite-nodes.mdx

Use this command to scaffold a new project using the fixed-layout-simple template.

```bash
npx @flowgram.ai/create-app@latest fixed-layout-simple
```

--------------------------------

### Development Commands for Demos

Source: https://github.com/bytedance/flowgram.ai/blob/main/CLAUDE.md

Commands to launch documentation and various demo applications with hot reloading.

```bash
# Run docs site with hot reload
rush dev:docs

# Run specific demo apps with hot reload
rush dev:demo-free-layout
rush dev:demo-fixed-layout
rush dev:demo-fixed-layout-simple
rush dev:demo-free-layout-simple
rush dev:demo-nextjs
rush dev:demo-nextjs-antd
```

--------------------------------

### Execute Rush via Install-Run Script

Source: https://github.com/bytedance/flowgram.ai/blob/main/CLAUDE.md

Use the local install-run script if Rush is not installed globally.

```bash
node common/scripts/install-run-rush.js <command>
```

--------------------------------

### Run Hot-Reloading Demos

Source: https://github.com/bytedance/flowgram.ai/blob/main/AGENTS.md

Starts hot-reloading development servers for demos. Use specific demo commands like `rush dev:demo-free-layout` for targeted development.

```bash
rush dev:docs
```

```bash
rush dev:demo-free-layout
```

--------------------------------

### Compile and Run FlowGram Runtime Service

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/runtime/quick-start.mdx

Compile the service using npm run build and then start the Node.js server from the dist directory. This is an alternative method to starting the service.

```bash
cd packages/runtime/nodejs
npm run build
node dist/index.js
```

--------------------------------

### Project File Structure

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/getting-started/fixed-layout.mdx

Recommended file structure for splitting editor configuration and components.

```sh
- use-editor-props.tsx # Canvas configuration (centralized management of Provider's props)
- node-render.tsx      # Node rendering (including delete button)
- initial-data.ts      # Initial data (start/custom/end)
- node-registries.tsx  # Node registration (example only registers 'custom')
- adder.tsx            # Custom "Add Node" component (adds a custom node on click)
- App.tsx              # Canvas entry point (mounts EditorRenderer)
```

--------------------------------

### Infer Assign Plugin - Core Implementation Guide

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/form-plugins/infer-assign-plugin.mdx

A guide to the core implementation details of the inferAssignPlugin, including its role in variable declaration, type inference, and JSON Schema generation.

```APIDOC
## Core Implementation Guide

### Description
This section details the internal workings of the `inferAssignPlugin`, explaining how it handles variable declarations, infers types, and generates JSON Schema.

### Capabilities
- **Variable Declaration (`declare`)**: Automatically generates output variables. The variable name is derived from the left-hand side of the `declare` operator. The variable type is inferred from the `right` value.
- **JSON Schema Generation**: When submitting data to the backend, it automatically generates the corresponding JSON Schema based on the inferred output variable types.

### Sequence Diagram
```mermaid
sequenceDiagram
    participant Form as Form
    participant Plugin as inferAssignPlugin
    participant Provider as VariableProvider
    participant Scope as Variable Scope
    participant Runtime as Backend Runtime

    Form->>Plugin: onSetupFormMeta()
    Plugin->>Form: Register variable provision side effects

    loop Iterate through each assignment operation
        alt operator = 'declare'
          Plugin->>Plugin: Generate variable declaration (left -> VariableDeclaration)
        end
    end

    Plugin->>Provider: Provide variables to scope
    Provider->>Scope: Register output variables
    Plugin-->>Runtime: Derive output variable JSON Schema
```

### Dependencies
#### flowgram API
- **@flowgram.ai/editor**
  - `defineFormPluginCreator`: Factory function for defining form plugins
  - `FormPlugin`: Form plugin type definition
  - `FormPluginSetupMetaCtx`: Plugin setup context, provides `mergeEffect`, `addFormatOnSubmit` methods
- **@flowgram.ai/variable-core**
- **@flowgram.ai/json-schema**
  - `IJsonSchema`: JSON Schema type definition

#### Other Dependencies
- **FlowValue**
  - `FlowValueUtils.inferJsonSchema()`: Infers JSON Schema from IFlowValue
  - `FlowValueUtils.isConstant()`, `FlowValueUtils.isRef()`: Type checking utilities
  - `IFlowValue`: Union type for Flow values
  - `IFlowRefValue`: Variable reference type
  - `IFlowConstantValue`: Constant type
```

--------------------------------

### Provide Batch Input Effect - AST Structure Example

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/effects/provide-batch-input.mdx

An example of the Abstract Syntax Tree (AST) structure generated by the provideBatchInputEffect for a loop, assuming the input variable path is `['start_0', 'list']`.

```APIDOC
## Generated AST Structure Example

Assuming the loop input variable path is `['start_0', 'list']`, the generated AST structure is:

```typescript
{
  kind: 'VariableDeclaration',
  key: 'loop_1_locals',
  meta: {
    title: 'Loop Node',
    icon: 'loop-icon'
  },
  type: {
    kind: 'ObjectType',
    properties: [
      {
        kind: 'Property',
        key: 'item',
        initializer: {
          kind: 'EnumerateExpression',
          enumerateFor: {
            kind: 'KeyPathExpression',
            keyPath: ['start_0', 'list']
          }
        }
      },
      {
        kind: 'Property',
        key: 'index',
        type: { kind: 'NumberType' }
      }
    ]
  }
}
```
```

--------------------------------

### Source Code Installation

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/materials/components/json-schema-creator.mdx

Instructions on how to copy the source code of the JsonSchemaCreator component locally using the CLI.

```APIDOC
## Source Code Installation

Use the CLI command to copy the source code locally:

```bash
npx @flowgram.ai/cli@latest materials components/json-schema-creator
```
```

--------------------------------

### ReduxStore Setup for Nodes and Edges

Source: https://github.com/bytedance/flowgram.ai/blob/main/apps/docs/src/en/guide/concepts/ecs.mdx

This setup uses a centralized Redux store to manage nodes and edges. It's simple for basic data management but can lead to performance issues with complex data.

```jsx
const store = () => ({
  nodes: [{
    position: any
    form: any
    data3: any

  }],
  edges: []
})

function Playground() {
  const { nodes } = useStore(store)

  return nodes.map(node => <Node data={node} />)
}
```