docs(materials): materials docs in nav (#917)

* docs(material): flow value

* docs(material): adjust nav

* docs: adjust

* feat: add wip

* feat: translate docs

* fix: build error

apps/demo-materials/src/components/free-editor/hooks/use-editor-props.tsx

@@ -40,6 +40,10 @@ export const useEditorProps = ({ registries, initialData, plugins, onSave }: Edi
        * 初始化数据
        */
       initialData,
+
+      scroll: {
+        enableScrollLimit: true,
+      },
       /**
        * Node registries
        * 节点注册

apps/docs/components/form-materials/effects/auto-rename-ref.tsx

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import React from 'react';
+
+import { autoRenameRefEffect } from '@flowgram.ai/form-materials';
+import { Field } from '@flowgram.ai/fixed-layout-editor';
+
+import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';
+
+const InputsValues = React.lazy(() =>
+  import('@flowgram.ai/form-materials').then((module) => ({
+    default: module.InputsValues,
+  }))
+);
+
+export const BasicStory = () => (
+  <FreeFormMetaStoryBuilder
+    filterEndNode
+    formMeta={{
+      effect: {
+        inputsValues: autoRenameRefEffect,
+      },
+      render: () => (
+        <>
+          <FormHeader />
+          <Field<Record<string, any> | undefined>
+            name="inputsValues"
+            defaultValue={{
+              a: {
+                type: 'ref',
+                content: ['start_0', 'str'],
+              },
+            }}
+          >
+            {({ field }) => (
+              <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+        </>
+      ),
+    }}
+  />
+);

apps/docs/components/form-materials/effects/listen-ref-schema-change.tsx

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import React from 'react';
+
+import { listenRefSchemaChange } from '@flowgram.ai/form-materials';
+import { Field } from '@flowgram.ai/fixed-layout-editor';
+
+import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';
+
+const InputsValues = React.lazy(() =>
+  import('@flowgram.ai/form-materials').then((module) => ({
+    default: module.InputsValues,
+  }))
+);
+
+export const BasicStory = () => (
+  <FreeFormMetaStoryBuilder
+    filterEndNode
+    formMeta={{
+      effect: {
+        'inputsValues.*': listenRefSchemaChange(({ name, schema, form, formValues }) => {
+          form.setValueIn(
+            `log`,
+            `${form.getValueIn(`log`) || ''}* ${name}: ${JSON.stringify(schema)} \n`
+          );
+        }),
+      },
+      render: () => (
+        <>
+          <FormHeader />
+          <Field<Record<string, any> | undefined>
+            name="inputsValues"
+            defaultValue={{
+              a: {
+                type: 'ref',
+                content: ['start_0', 'str'],
+              },
+            }}
+          >
+            {({ field }) => (
+              <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+          <br />
+          <Field<any> name="log" defaultValue={'When schema updated, log changes:\n'}>
+            {({ field }) => (
+              <pre style={{ padding: 4, background: '#f5f5f5', fontSize: 12 }}>{field.value}</pre>
+            )}
+          </Field>
+        </>
+      ),
+    }}
+  />
+);

apps/docs/components/form-materials/effects/listen-ref-value-change.tsx

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import React from 'react';
+
+import { listenRefValueChange } from '@flowgram.ai/form-materials';
+import { Field } from '@flowgram.ai/fixed-layout-editor';
+
+import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';
+
+const InputsValues = React.lazy(() =>
+  import('@flowgram.ai/form-materials').then((module) => ({
+    default: module.InputsValues,
+  }))
+);
+
+export const BasicStory = () => (
+  <FreeFormMetaStoryBuilder
+    filterEndNode
+    formMeta={{
+      effect: {
+        'inputsValues.*': listenRefValueChange(({ name, variable, form }) => {
+          form.setValueIn(
+            `log`,
+            `${form.getValueIn(`log`) || ''}* ${name}: ${JSON.stringify({
+              name: variable?.name,
+              type: variable?.type,
+              value: variable?.value,
+            })} \n`
+          );
+        }),
+      },
+      render: () => (
+        <>
+          <FormHeader />
+          <Field<Record<string, any> | undefined>
+            name="inputsValues"
+            defaultValue={{
+              a: {
+                type: 'ref',
+                content: ['start_0', 'str'],
+              },
+            }}
+          >
+            {({ field }) => (
+              <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+          <br />
+          <Field<any> name="log" defaultValue={'When variable value updated, log changes:\n'}>
+            {({ field }) => (
+              <pre style={{ padding: 4, background: '#f5f5f5', fontSize: 12 }}>{field.value}</pre>
+            )}
+          </Field>
+        </>
+      ),
+    }}
+  />
+);

apps/docs/rspress.config.ts

@@ -69,8 +69,8 @@ export default defineConfig({
       '/en/examples/free-layout/free-layout-simple',
       '/en/examples/fixed-layout/fixed-feature-overview',
       '/en/examples/free-layout/free-feature-overview',
-      /\/en\/guide\/materials\/.*\/.*/,
-      /\/guide\/materials\/.*\/.*/,
+      /\/en\/materials\/.*\/.*/,
+      /\/materials\/.*\/.*/,
       '/examples/node-form/basic',
       '/examples/node-form/array',
       '/examples/node-form/dynamic',

apps/docs/src/en/_nav.json

@@ -4,13 +4,18 @@
     "link": "/guide/introduction",
     "activeMatch": "/guide/introduction"
   },
+  {
+    "text": "Materials",
+    "link": "/materials/introduction",
+    "activeMatch": "/materials/introduction"
+  },
   {
     "text": "Examples",
     "link": "/examples/",
     "activeMatch": "/examples/"
   },
   {
-    "text": "Common APIs",
+    "text": "API",
     "link": "/api/",
     "activeMatch": "/api/"
   },

apps/docs/src/en/guide/_meta.json

@@ -26,11 +26,6 @@
     "name": "variable",
     "label": "Variable"
   },
-  {
-    "type": "dir",
-    "name": "materials",
-    "label": "Official Materials (WIP)"
-  },
   {
     "type": "dir",
     "name": "plugin",

apps/docs/src/en/guide/form/form-materials.mdx

@@ -1,103 +1,3 @@
-import { PackageManagerTabs } from '@theme';
-import { MaterialDisplay } from '../../../../components/materials';
-
 # Official Form Materials
 
-## How to Use?
-
-See: [Material Quickstart](/guide/materials/introduction.html)
-
-
-## Currently Supported Component Materials
-
-Documents are transferred to [Components](/guide/materials/components/type-selector.html)
-
-## Currently Supported Effect Materials
-
-### provideBatchInput
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/provide-batch-input.png', caption: 'Type of item is automatically inferred based on preceding type.' }]}
-  filePath="effects/provide-batch-input/index.ts"
-  exportName="provideBatchInputEffect"
->
-  provideBatchInputEffect is used for configuring loop batch input derivation. It automatically derives two variables based on the input:
-  - item: Derived from the input variable array type, representing each item in the loop.
-  - index: Numeric type, representing the iteration count.
-</MaterialDisplay>
-
-### autoRenameRef
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/auto-rename-ref.gif', caption: 'When the query variable name changes, automatically rename references in downstream inputs.' }]}
-  filePath="effects/auto-rename-ref/index.ts"
-  exportName="autoRenameRefEffect"
->
-  When the name of a preceding output variable changes:
-  - All references to that variable in form items are automatically renamed.
-</MaterialDisplay>
-
-### syncVariableTitle
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/sync-variable-title.gif'  }]}
-  filePath="effects/sync-variable-title/index.ts"
-  exportName="syncVariableTitle"
->
-  The node name in the variable system changes automatically.
-</MaterialDisplay>
-
-### provideJsonSchemaOutputs
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/json-schema-editor.png' }]}
-  filePath="effects/provide-json-schema-outputs/index.ts"
-  exportName="provideJsonSchemaOutputs"
->
-  The node JsonSchema is synchronized to the node output of the variable system, so that the downstream of the node can be selected.
-</MaterialDisplay>
-
-## Currently Supported FormPlugin Materials
-
-### batch-outputs-plugin
-
-<MaterialDisplay
-  imgs={[
-    { src: '/materials/batch-outputs-plugin-1.png', caption: 'The plugin limits the loop scope to only reference variables of nodes within the loop' },
-    { src: '/materials/batch-outputs-plugin-2.png', caption: 'Downstream nodes are automatically inferred based on the process' }
-  ]}
-  filePath="form-plugins/batch-outputs-plugin/index.ts"
-  exportName="createBatchOutputsFormPlugin"
->
-  Loop output plugin, needs to be used with the `BatchOutputs` material
-
-  ```typescript
-  const formMeta = {
-    plugins: [createBatchOutputsFormPlugin({ outputKey: 'loopOutputs' })],
-  }
-  ```
-</MaterialDisplay>
-
-
-### infer-inputs-plugin
-
-<MaterialDisplay
-  imgs={[
-    { src: '/materials/infer-inputs-plugin.png', caption: 'inputs is the JsonSchema type of inputsValues' },
-  ]}
-  filePath="form-plugins/infer-inputs-plugin/index.ts"
-  exportName="inferInputsPlugin"
->
-  When passing to the backend, the JsonSchema type of inputsValues is automatically calculated based on the variable engine
-
-  ```typescript
-  const formMeta = {
-    plugins: [
-      // headers stores the type definition of headersValues
-      createInferInputsPlugin({ sourceKey: 'headersValues', targetKey: 'headers' }),
-      // params stores the type definition of paramsValues
-      createInferInputsPlugin({ sourceKey: 'paramsValues', targetKey: 'params' }),
-    ],
-  }
-  ```
-</MaterialDisplay>
+Transferred to [Introduction](/en/materials/introduction)

apps/docs/src/en/guide/materials/_meta.json

@@ -1,10 +0,0 @@
-[
-  "introduction",
-  "cli",
-  {
-    "type": "dir",
-    "name": "components",
-    "label": "Components",
-    "collapsed": true
-  }
-]

apps/docs/src/en/materials/_meta.json

@@ -0,0 +1,24 @@
+[
+  "introduction",
+  "cli",
+  {
+    "type": "dir",
+    "name": "components",
+    "label": "Form Components"
+  },
+  {
+    "type": "dir",
+    "name": "effects",
+    "label": "Form Effects"
+  },
+  {
+    "type": "dir",
+    "name": "form-plugins",
+    "label": "Form Plugins"
+  },
+  {
+    "type": "dir",
+    "name": "common",
+    "label": "Common"
+  }
+]

apps/docs/src/en/materials/common/_meta.json

@@ -0,0 +1,3 @@
+[
+  "flow-value"
+]

apps/docs/src/en/materials/common/flow-value.mdx

@@ -0,0 +1,146 @@
+import { SourceCode } from '@theme';
+
+# Flow Value
+
+Flow Value is a special type used in Flowgram Official Materials to represent data. It can be a constant, reference, expression, or template, providing a flexible way for data transfer and processing in workflows.
+
+## Flow Value Types
+
+Flow Value supports the following four types:
+
+### 1. Constant
+A fixed value that does not change at runtime. It can contain any type of data, such as strings, numbers, booleans, or objects.
+
+```typescript
+{
+  type: 'constant',
+  content: 'Hello World', // Can be any type
+  schema?: { type: "string" },    // Optional JSON Schema definition
+  extra?: { index: 1 }  // Additional information, such as ordering, etc.
+}
+```
+
+### 2. Reference
+A reference to other variables or data in the workflow, specifying the reference location through a path array.
+
+```typescript
+{
+  type: 'ref',
+  content: ['variable', 'name'], // Reference path array
+  extra?: { index: 1 }  // Additional information, such as ordering, etc.
+}
+```
+
+### 3. Template
+A string template containing variable placeholders, using the `{{variable}}` syntax to embed variables.
+
+```typescript
+{
+  type: 'template',
+  content: 'Hello {{user.name}}!', // Template string
+  extra?: { index: 1 }  // Additional information, such as ordering, etc.
+}
+```
+
+### 4. WIP: Expression
+A JavaScript expression that will be evaluated at runtime.
+
+```typescript
+{
+  type: 'expression',
+  content: 'a + b', // JavaScript, Python, etc. expression string
+  extra?: { index: 1 }  // Additional information, such as ordering, etc.
+}
+```
+
+::: warning
+The expression type is currently in WIP status and does not support type derivation capabilities at the moment. There may be breaking changes in the future.
+:::
+
+## FlowValueUtils Utility Class
+
+FlowValueUtils provides rich utility functions for handling Flow Values:
+
+### Type Checking Functions
+
+- `isConstant(value)` - Check if it's a constant type
+- `isRef(value)` - Check if it's a reference type
+- `isExpression(value)` - Check if it's an expression type
+- `isTemplate(value)` - Check if it's a template type
+- `isConstantOrRef(value)` - Check if it's a constant or reference type
+- `isFlowValue(value)` - Check if it's a valid Flow Value type
+
+### Traversal and Extraction Functions
+
+- `traverse(value, options)` - Traverse all Flow Values in an object, with type filtering support
+- `getTemplateKeyPaths(templateValue)` - Extract all variable paths from templates
+
+### Schema Inference Functions
+
+- `inferConstantJsonSchema(constantValue)` - Infer JSON Schema based on constant value
+- `inferJsonSchema(values, scope)` - Infer corresponding JSON Schema based on Flow Value
+
+## Usage Examples
+
+### Using Utility Functions
+
+```typescript
+// Type checking
+if (FlowValueUtils.isConstant(value)) {
+  console.log('This is a constant value:', value.content);
+}
+
+// Traverse Flow Values
+for (const { value, path } of FlowValueUtils.traverse(data, {
+  includeTypes: ['ref', 'template']
+})) {
+  console.log(`Found ${value.type} at path: ${path}`);
+}
+
+// Extract template variables
+const templatePaths = FlowValueUtils.getTemplateKeyPaths(templateValue);
+console.log('Template variables:', templatePaths); // [['user', 'name'], ['count']]
+```
+
+## Type Definitions
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/shared/flow-value/types.ts"
+/>
+
+The core type definitions of Flow Value include:
+
+- `IFlowValue` - Union type of Flow Value
+- `IFlowConstantValue` - Constant type interface
+- `IFlowRefValue` - Reference type interface
+- `IFlowExpressionValue` - Expression type interface
+- `IFlowTemplateValue` - Template type interface
+- `IFlowConstantRefValue` - Union type of constant or reference types
+- `IInputsValues` - Mapping type of input values
+
+## Source Code Guide
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/shared/flow-value"
+/>
+
+Use CLI command to copy source code locally:
+
+```bash
+npx @flowgram.ai/cli@latest materials shared/flow-value
+```
+
+### Directory Structure
+
+```
+flow-value/
+├── index.ts           # Main entry file, exports all types and utility functions
+├── types.ts           # Type definitions file, contains all Flow Value interface definitions
+├── schema.ts          # Zod schema definitions for runtime type validation
+├── utils.ts           # Complete implementation of FlowValueUtils utility class
+└── README.md          # Module documentation
+```
+
+### Third-party APIs Used
+
+- [Zod](https://v3.zod.dev/): Used for type validation and data parsing to determine if Flow Value schemas meet expectations.

apps/docs/src/en/materials/effects/_meta.json

@@ -0,0 +1,4 @@
+[
+  "auto-rename-ref",
+  "listen-ref-schema-change"
+]

apps/docs/src/en/materials/effects/auto-rename-ref.mdx

@@ -0,0 +1,156 @@
+# autoRenameRef
+
+autoRenameRef is an automatic reference renaming effect that automatically updates all reference values and template values referencing that field when the key name of a form field changes.
+
+<br />
+<div>
+  <img loading="lazy" src="/materials/auto-rename-ref.gif" alt="autoRenameRef Effect" style={{ width: '80%' }} />
+  *When the query variable name changes, automatically rename references in downstream inputs*
+</div>
+
+## Demo
+
+import { BasicStory } from 'components/form-materials/effects/auto-rename-ref';
+
+### Basic Usage
+
+<BasicStory />
+
+```tsx pure title="form-meta.tsx"
+import { autoRenameRefEffect } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effects: {
+    "inputsValues": autoRenameRefEffect,
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<any> name="inputsValues">
+        {({ field }) => (
+          <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+        )}
+      </Field>
+    </>
+  ),
+}
+```
+
+### Usage in Complex Forms
+
+```tsx pure title="form-meta.tsx"
+import { autoRenameRefEffect } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effects: {
+    // Apply automatic renaming effect to multiple fields
+    "inputsValues": autoRenameRefEffect,
+    "outputsValues": autoRenameRefEffect,
+    "config.data": autoRenameRefEffect,
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<any> name="inputsValues"> {/* inputsValues implementation */} </Field>
+      <Field<any> name="outputsValues"> {/* outputsValues implementation */} </Field>
+      <Field<any> name="config.data"> {/* config.data implementation */} </Field>
+    </>
+  ),
+}
+```
+
+## API Reference
+
+### Supported Value Types
+
+The automatic renaming of autoRenameEffect is only triggered when the data under the specified key meets the following conditions:
+
+- **Reference Value (ref)**: `{ type: 'ref', content: ['field', 'path'] }`
+- **Template Value (template)**: `{ type: 'template', content: 'Hello {{user.name}}' }`
+- **Complex Structure Containing Reference and Template Values**:
+  ```json
+  {
+    "a": {
+      "type": "ref",
+      "content": ["start_0", "str"]
+    },
+    "b": {
+      "c": {
+        "type": "template",
+        "content": "Hello {{a}}"
+      }
+    }
+  }
+  ```
+
+## Source Code Guide
+
+import { SourceCode } from '@theme';
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram/tree/main/packages/materials/form-materials/src/effects/auto-rename-ref"
+/>
+
+Copy source code locally using CLI command:
+
+```bash
+npx @flowgram.ai/cli@latest materials effects/auto-rename-ref
+```
+
+### Core Process
+
+1. **Listen to Rename Events**: Listen for field key name changes through `VariableFieldKeyRenameService`
+2. **Traverse Reference Values**: Find all reference values and template values
+3. **Match Key Paths**: Check if the reference path matches the path before the change
+4. **Update References**: Update matching reference paths to the new key path
+
+```mermaid
+graph TD
+    A[Listen to Rename Events] --> B[renameService.onRename triggered]
+    B --> C[Traverse all values traverseRef]
+
+    C --> D{Value Type Judgment}
+
+    D -->|ref type| E[Check path match
+    isKeyPathMatch]
+
+    D -->|template type| F[Check template path match
+    traverse + isKeyPathMatch]
+
+    E -->|Match| G[Update reference path
+    value.content = newPath]
+
+    E -->|No match| I
+
+    F -->|Match| H[Replace template content
+    value.content.replace]
+
+    F -->|No match| I
+
+    G --> I[Update form value
+    form.setValueIn]
+
+    H --> I
+
+    I --> J{More values to process?}
+    J -->|Yes| C
+    J -->|No| K[Complete]
+
+    style A fill:#e1f5fe
+    style K fill:#e8f5e8
+    style B fill:#fff3e0
+    style G fill:#ffebee
+    style H fill:#ffebee
+```
+
+### Core APIs Used
+
+#### @flowgram.ai/variable-core
+- `VariableFieldKeyRenameService`: Field key name rename listener
+
+#### @flowgram.ai/node
+- `DataEvent.onValueInit`: Value initialization event
+- `Effect`: Effect type definition
+
+#### FlowValueUtils
+- `FlowValueUtils.getTemplateKeyPaths()`: Extract all key paths from templates

apps/docs/src/en/materials/effects/listen-ref-schema-change.mdx

@@ -0,0 +1,118 @@
+# listenRefSchemaChange
+
+Listen to JSON schema changes of reference variable types and trigger callback functions when changes occur.
+
+## Demo
+
+import { BasicStory } from 'components/form-materials/effects/listen-ref-schema-change';
+
+### Basic Usage
+
+<BasicStory />
+
+```tsx pure title="form-meta.tsx"
+import { listenRefSchemaChange } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effect: {
+    'inputsValues.*': listenRefSchemaChange(({ name, schema, form, formValues }) => {
+      form.setValueIn(
+        `log`,
+        `${form.getValueIn(`log`) || ''}* ${name}: ${JSON.stringify(schema)} \n`
+      );
+    }),
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<Record<string, any> | undefined>
+        name="inputsValues"
+        defaultValue={{
+          a: {
+            type: 'ref',
+            content: ['start_0', 'str'],
+          },
+        }}
+      >
+        {({ field }) => (
+          <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+        )}
+      </Field>
+      <br />
+      <Field<any> name="log" defaultValue={'When schema updated, log changes:\n'}>
+        {({ field }) => (
+          <pre style={{ padding: 4, background: '#f5f5f5', fontSize: 12 }}>{field.value}</pre>
+        )}
+      </Field>
+    </>
+  ),
+}
+```
+
+## API Reference
+
+### listenRefSchemaChange
+
+```typescript
+listenRefSchemaChange(
+  cb: (props: EffectFuncProps<IFlowRefValue> & { schema?: IJsonSchema }) => void
+): EffectOptions[]
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|----------|------|-------------|
+| `cb` | `(props: EffectFuncProps<IFlowRefValue> & { schema?: IJsonSchema }) => void` | Callback function triggered when the referenced schema changes |
+
+#### Callback Function Parameters
+
+| Parameter | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Field name |
+| `value` | `IFlowRefValue` | Reference value object |
+| `form` | `IForm` | Form instance |
+| `schema` | `IJsonSchema` | Converted JSON Schema |
+
+### Supported Value Types
+
+- `IFlowRefValue`: Reference type value, contains `type: 'ref'` and `content: string[]`
+
+## Source Code Guide
+
+import { SourceCode } from '@theme';
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/effects/listen-ref-schema-change"
+/>
+
+Copy source code locally using CLI command:
+
+```bash
+npx @flowgram.ai/cli@latest materials effects/listen-ref-schema-change
+```
+
+### Directory Structure
+
+```
+listen-ref-schema-change/
+└── index.ts          # Main entry file
+```
+
+### How It Works
+
+1. **Value Change Listening**: Listen to `DataEvent.onValueInitOrChange` events
+2. **Type Checking**: Check if the value is of `ref` type
+3. **Path Tracking**: Use `trackByKeyPath` to track reference paths
+4. **Schema Conversion**: Convert AST type to JSON Schema
+5. **Callback Trigger**: Trigger callback when the referenced type changes
+
+### Flowgram APIs Used
+
+#### @flowgram.ai/variable-core
+
+- `getNodeScope(context.node).available.trackByKeyPath`: Track value changes for specified paths, trigger callbacks when values corresponding to paths change.
+
+#### @flowgram.ai/json-schema
+
+- `JsonSchemaUtils.astToSchema`: Convert AST type nodes to JSON Schema objects.

apps/docs/src/en/materials/form-plugins/_meta.json

@@ -0,0 +1 @@
+[]

apps/docs/src/zh/_nav.json

@@ -4,13 +4,18 @@
     "link": "/guide/introduction",
     "activeMatch": "/guide/introduction"
   },
+  {
+    "text": "物料",
+    "link": "/materials/introduction",
+    "activeMatch": "/materials/introduction"
+  },
   {
     "text": "例子",
     "link": "/examples/",
     "activeMatch": "/examples/"
   },
   {
-    "text": "常用 API",
+    "text": "API",
     "link": "/api/",
     "activeMatch": "/api/"
   },

apps/docs/src/zh/guide/_meta.json

@@ -26,11 +26,6 @@
     "name": "variable",
     "label": "变量"
   },
-  {
-    "type": "dir",
-    "name": "materials",
-    "label": "官方物料库 (WIP)"
-  },
   {
     "type": "dir",
     "name": "plugin",

apps/docs/src/zh/guide/form/form-materials.mdx

@@ -1,102 +1,3 @@
-import { PackageManagerTabs } from '@theme';
-import { MaterialDisplay } from '../../../../components/materials';
-
 # 官方表单物料
 
-## 如何使用？
-
-详见：[物料快速入门](/guide/materials/introduction.html)
-
-## 当前支持的 Component 物料
-
-文档已迁移到 [组件](/guide/materials/components/type-selector.html)
-
-## 当前支持的 Effect 物料
-
-### provideBatchInput
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/provide-batch-input.png', caption: 'item 的类型会自动根据前置类型联动推导' }]}
-  filePath="effects/provide-batch-input/index.ts"
-  exportName="provideBatchInputEffect"
->
-  provideBatchInputEffect 用于配置循环批处理输入推导，会根据输入自动推导出两个变量：
-  - item：根据输入变量数组类型自动推导，代表循环的每一项
-  - index：数字类型，代表循环第几次
-</MaterialDisplay>
-
-### autoRenameRef
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/auto-rename-ref.gif', caption: 'query 变量名变化时，自动重命名下游 inputs 中的引用' }]}
-  filePath="effects/auto-rename-ref/index.ts"
-  exportName="autoRenameRefEffect"
->
-  当前置输出变量名发生变化时:
-  - 表单项中所有的对该变量的引用，自动重命名
-</MaterialDisplay>
-
-### syncVariableTitle
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/sync-variable-title.gif'  }]}
-  filePath="effects/sync-variable-title/index.ts"
-  exportName="syncVariableTitle"
->
-  变量系统中节点名自动联动变化
-</MaterialDisplay>
-
-### provideJsonSchemaOutputs
-
-<MaterialDisplay
-  imgs={[{ src: '/materials/json-schema-editor.png' }]}
-  filePath="effects/provide-json-schema-outputs/index.ts"
-  exportName="provideJsonSchemaOutputs"
->
-  节点 JsonSchema 同步到变量系统节点输出，使节点下游可以选择
-</MaterialDisplay>
-
-## 当前支持的 FormPlugin 物料
-
-### batch-outputs-plugin
-
-<MaterialDisplay
-  imgs={[
-    { src: '/materials/batch-outputs-plugin-1.png', caption: '插件限制循环作用域只能引用循环体内节点的变量' },
-    { src: '/materials/batch-outputs-plugin-2.png', caption: '下游节点自动根据进行推导' }
-  ]}
-  filePath="form-plugins/batch-outputs-plugin/index.ts"
-  exportName="createBatchOutputsFormPlugin"
->
-  循环输出插件，需要配置 `BatchOutputs` 物料使用
-
-  ```typescript
-  const formMeta = {
-    plugins: [createBatchOutputsFormPlugin({ outputKey: 'loopOutputs' })],
-  }
-  ```
-</MaterialDisplay>
-
-
-### infer-inputs-plugin
-
-<MaterialDisplay
-  imgs={[
-    { src: '/materials/infer-inputs-plugin.png', caption: 'inputs 为 inputsValues 的 JsonSchema 类型' },
-  ]}
-  filePath="form-plugins/infer-inputs-plugin/index.ts"
-  exportName="inferInputsPlugin"
->
-  传到后端时，基于变量引擎自动计算出 inputsValues 的 JsonSchema 类型
-
-  ```typescript
-  const formMeta = {
-    plugins: [
-      // headers 存储 headersValues 的类型定义
-      createInferInputsPlugin({ sourceKey: 'headersValues', targetKey: 'headers' }),
-      // params 存储 paramsValues 的类型定义
-      createInferInputsPlugin({ sourceKey: 'paramsValues', targetKey: 'params' }),
-    ],
-  }
-  ```
-</MaterialDisplay>
+文档已迁移到：[物料](/materials/introduction.html)

apps/docs/src/zh/guide/materials/_meta.json

@@ -1,10 +0,0 @@
-[
-  "introduction",
-  "cli",
-  {
-    "type": "dir",
-    "name": "components",
-    "label": "组件",
-    "collapsed": true
-  }
-]

apps/docs/src/zh/materials/_meta.json

@@ -0,0 +1,24 @@
+[
+  "introduction",
+  "cli",
+  {
+    "type": "dir",
+    "name": "components",
+    "label": "表单组件"
+  },
+  {
+    "type": "dir",
+    "name": "effects",
+    "label": "表单副作用"
+  },
+  {
+    "type": "dir",
+    "name": "form-plugins",
+    "label": "表单插件 (WIP)"
+  },
+  {
+    "type": "dir",
+    "name": "common",
+    "label": "通用逻辑"
+  }
+]

apps/docs/src/zh/materials/common/_meta.json

@@ -0,0 +1,3 @@
+[
+  "flow-value"
+]

apps/docs/src/zh/materials/common/flow-value.mdx

@@ -0,0 +1,146 @@
+import { SourceCode } from '@theme';
+
+# Flow Value
+
+Flow Value 是指在 Flowgram 官方物料库 中用于表示数据的一种特殊类型。它可以是常量、引用、表达式或模板，为流程中的数据传递和处理提供了灵活的方式。
+
+## Flow Value 类型
+
+Flow Value 支持以下四种类型：
+
+### 1. 常量 (Constant)
+固定值，在运行时不会改变。可以包含任意类型的数据，如字符串、数字、布尔值或对象。
+
+```typescript
+{
+  type: 'constant',
+  content: 'Hello World', // 可以是任意类型
+  schema?: { type: "string" },    // 可选的 JSON Schema 定义
+  extra?: { index: 1 }  // 额外信息，如排序等
+}
+```
+
+### 2. 引用 (Reference)
+对流程中其他变量或数据的引用，通过路径数组来指定引用的位置。
+
+```typescript
+{
+  type: 'ref',
+  content: ['variable', 'name'], // 引用路径数组
+  extra?: { index: 1 }  // 额外信息，如排序等
+}
+```
+
+### 3. 模板 (Template)
+包含变量占位符的字符串模板，使用 `{{variable}}` 语法来嵌入变量。
+
+```typescript
+{
+  type: 'template',
+  content: 'Hello {{user.name}}!', // 模板字符串
+  extra?: { index: 1 }  // 额外信息，如排序等
+}
+```
+
+### 4. WIP: 表达式 (Expression)
+JavaScript 表达式，在运行时会进行求值计算。
+
+```typescript
+{
+  type: 'expression',
+  content: 'a + b', // JavaScript、Python 等表达式字符串
+  extra?: { index: 1 }  // 额外信息，如排序等
+}
+```
+
+::: warning
+表达式类型当前为 WIP 状态，目前暂不支持类型推导能力，未来可能会有 breaking change。
+:::
+
+## FlowValueUtils 工具类
+
+FlowValueUtils 提供了丰富的工具函数来处理 Flow Value：
+
+### 类型判断函数
+
+- `isConstant(value)` - 判断是否为常量类型
+- `isRef(value)` - 判断是否为引用类型
+- `isExpression(value)` - 判断是否为表达式类型
+- `isTemplate(value)` - 判断是否为模板类型
+- `isConstantOrRef(value)` - 判断是否为常量或引用类型
+- `isFlowValue(value)` - 判断是否为有效的 Flow Value 类型
+
+### 遍历和提取函数
+
+- `traverse(value, options)` - 遍历对象中的所有 Flow Value，支持按类型筛选
+- `getTemplateKeyPaths(templateValue)` - 提取模板中所有的变量路径
+
+### Schema 推断函数
+
+- `inferConstantJsonSchema(constantValue)` - 根据常量值推断 JSON Schema
+- `inferJsonSchema(values, scope)` - 根据 Flow Value 推断对应的 JSON Schema
+
+## 使用示例
+
+### 使用工具函数
+
+```typescript
+// 类型判断
+if (FlowValueUtils.isConstant(value)) {
+  console.log('This is a constant value:', value.content);
+}
+
+// 遍历 Flow Values
+for (const { value, path } of FlowValueUtils.traverse(data, {
+  includeTypes: ['ref', 'template']
+})) {
+  console.log(`Found ${value.type} at path: ${path}`);
+}
+
+// 提取模板变量
+const templatePaths = FlowValueUtils.getTemplateKeyPaths(templateValue);
+console.log('Template variables:', templatePaths); // [['user', 'name'], ['count']]
+```
+
+## 类型定义
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/shared/flow-value/types.ts"
+/>
+
+Flow Value 的核心类型定义包括：
+
+- `IFlowValue` - Flow Value 的联合类型
+- `IFlowConstantValue` - 常量类型接口
+- `IFlowRefValue` - 引用类型接口
+- `IFlowExpressionValue` - 表达式类型接口
+- `IFlowTemplateValue` - 模板类型接口
+- `IFlowConstantRefValue` - 常量或引用类型的联合类型
+- `IInputsValues` - 输入值的映射类型
+
+## 源码导读
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/shared/flow-value"
+/>
+
+使用 CLI 命令可以复制源代码到本地：
+
+```bash
+npx @flowgram.ai/cli@latest materials shared/flow-value
+```
+
+### 目录结构讲解
+
+```
+flow-value/
+├── index.ts           # 主入口文件，导出所有类型和工具函数
+├── types.ts           # 类型定义文件，包含所有 Flow Value 接口定义
+├── schema.ts          # Zod 模式定义，用于运行时类型验证
+├── utils.ts           # FlowValueUtils 工具类的完整实现
+└── README.md          # 模块说明文档
+```
+
+### 使用到的第三方 API
+
+- [Zod](https://v3.zod.dev/): 用于类型验证和数据解析，判断 Flow Value 的 Schema 是否符合预期。

apps/docs/src/zh/materials/effects/_meta.json

@@ -0,0 +1,4 @@
+[
+  "auto-rename-ref",
+  "listen-ref-schema-change"
+]

apps/docs/src/zh/materials/effects/auto-rename-ref.mdx

@@ -0,0 +1,157 @@
+
+import { SourceCode } from '@theme';
+import { BasicStory } from 'components/form-materials/effects/auto-rename-ref';
+
+# autoRenameRef
+
+autoRenameRef 是一个自动重命名引用效果，当表单字段的键名发生变化时，自动更新所有引用该字段的引用值和模板值。
+
+<br />
+<div>
+  <img loading="lazy" src="/materials/auto-rename-ref.gif" alt="autoRenameRef 效果" style={{ width: '80%' }} />
+  *query 变量名变化时，自动重命名下游 inputs 中的引用*
+</div>
+
+## 案例演示
+
+### 基本使用
+
+<BasicStory />
+
+```tsx pure title="form-meta.tsx"
+import { autoRenameRefEffect } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effects: {
+    "inputsValues": autoRenameRefEffect,
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<any> name="inputsValues">
+        {({ field }) => (
+          <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+        )}
+      </Field>
+    </>
+  ),
+}
+```
+
+### 在复杂表单中使用
+
+```tsx pure title="form-meta.tsx"
+import { autoRenameRefEffect } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effects: {
+    // 为多个字段应用自动重命名效果
+    "inputsValues": autoRenameRefEffect,
+    "outputsValues": autoRenameRefEffect,
+    "config.data": autoRenameRefEffect,
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<any> name="inputsValues"> {/* inputsValues 实现 */} </Field>
+      <Field<any> name="outputsValues"> {/* outputsValues 实现 */} </Field>
+      <Field<any> name="config.data"> {/* config.data 实现 */} </Field>
+    </>
+  ),
+}
+```
+
+## API 介绍
+
+### 支持的值类型
+
+当指定 key 下对应的数据满足以下条件时，autoRenameEffect 的自动重命名才会被触发：
+
+- **引用值 (ref)**：`{ type: 'ref', content: ['field', 'path'] }`
+- **模板值 (template)**：`{ type: 'template', content: 'Hello {{user.name}}' }`
+- **包含引用值和模板值的复杂结构**：
+  ```json
+  {
+    "a": {
+      "type": "ref",
+      "content": ["start_0", "str"]
+    },
+    "b": {
+      "c": {
+        "type": "template",
+        "content": "Hello {{a}}"
+      }
+    }
+  }
+  ```
+
+## 源码导读
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/effects/auto-rename-ref"
+/>
+
+使用 CLI 命令可以复制源代码到本地：
+
+```bash
+npx @flowgram.ai/cli@latest materials effects/auto-rename-ref
+```
+
+### 核心流程
+
+1. **监听重命名事件**：通过 `VariableFieldKeyRenameService` 监听字段键名变更
+2. **遍历引用值**：查找所有引用值和模板值
+3. **匹配键路径**：检查引用路径是否与变更前的路径匹配
+4. **更新引用**：将匹配的引用路径更新为新的键路径
+
+```mermaid
+graph TD
+    A[监听重命名事件] --> B[renameService.onRename触发]
+    B --> C[遍历所有值 traverseRef]
+
+    C --> D{值类型判断}
+
+    D -->|ref类型| E[检查路径匹配
+    isKeyPathMatch]
+
+    D -->|template类型| F[检查模板路径匹配
+    遍历+isKeyPathMatch]
+
+    E -->|匹配| G[更新引用路径
+    value.content = newPath]
+
+    E -->|不匹配| I
+
+    F -->|匹配| H[替换模板内容
+    value.content.replace]
+
+    F -->|不匹配| I
+
+    G --> I[更新表单值
+    form.setValueIn]
+
+    H --> I
+
+    I --> J{还有值需要处理?}
+    J -->|是| C
+    J -->|否| K[完成]
+
+    style A fill:#e1f5fe
+    style K fill:#e8f5e8
+    style B fill:#fff3e0
+    style G fill:#ffebee
+    style H fill:#ffebee
+```
+
+### 使用到的核心 API
+
+#### @flowgram.ai/variable-core
+- `VariableFieldKeyRenameService`: 字段键名重命名监听
+
+
+#### @flowgram.ai/node
+- `DataEvent.onValueInit`: 值初始化事件
+- `Effect`: 效果类型定义
+
+#### FlowValueUtils
+- `FlowValueUtils.getTemplateKeyPaths()`: 提取模板中的所有键路径

apps/docs/src/zh/materials/effects/listen-ref-schema-change.mdx

@@ -0,0 +1,128 @@
+
+
+# listenRefSchemaChange
+
+监听引用变量类型的 json schema 变化，并在变化时触发回调函数。
+
+## 案例演示
+
+import { BasicStory } from 'components/form-materials/effects/listen-ref-schema-change';
+
+### 基本使用
+
+<BasicStory />
+
+
+```tsx pure title="form-meta.tsx"
+import { listenRefSchemaChange } from '@flowgram.ai/form-materials';
+
+const formMeta = {
+  effect: {
+    'inputsValues.*': listenRefSchemaChange(({ name, schema, form, formValues }) => {
+      form.setValueIn(
+        `log`,
+        `${form.getValueIn(`log`) || ''}* ${name}: ${JSON.stringify(schema)} \n`
+      );
+    }),
+  },
+  render: () => (
+    <>
+      <FormHeader />
+      <Field<Record<string, any> | undefined>
+        name="inputsValues"
+        defaultValue={{
+          a: {
+            type: 'ref',
+            content: ['start_0', 'str'],
+          },
+        }}
+      >
+        {({ field }) => (
+          <InputsValues value={field.value} onChange={(value) => field.onChange(value)} />
+        )}
+      </Field>
+      <br />
+      <Field<any> name="log" defaultValue={'When schema updated, log changes:\n'}>
+        {({ field }) => (
+          <pre style={{ padding: 4, background: '#f5f5f5', fontSize: 12 }}>{field.value}</pre>
+        )}
+      </Field>
+    </>
+  ),
+}
+```
+
+## API 介绍
+
+### listenRefSchemaChange
+
+```typescript
+listenRefSchemaChange(
+  cb: (props: EffectFuncProps<IFlowRefValue> & { schema?: IJsonSchema }) => void
+): EffectOptions[]
+```
+
+#### 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `cb` | `(props: EffectFuncProps<IFlowRefValue> & { schema?: IJsonSchema }) => void` | 回调函数，当引用的 schema 发生变化时触发 |
+
+#### 回调函数参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `name` | `string` | 字段名称 |
+| `value` | `IFlowRefValue` | 引用值对象 |
+| `form` | `IForm` | 表单实例 |
+| `schema` | `IJsonSchema` | 转换后的 JSON Schema |
+
+
+
+### 支持值类型
+
+- `IFlowRefValue`：引用类型值，包含 `type: 'ref'` 和 `content: string[]`
+
+
+## 源码导读
+
+import { SourceCode } from '@theme';
+
+
+<SourceCode
+  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/effects/listen-ref-schema-change"
+/>
+
+使用 CLI 命令可以复制源代码到本地：
+
+```bash
+npx @flowgram.ai/cli@latest materials effects/listen-ref-schema-change
+```
+
+### 目录结构
+
+```
+listen-ref-schema-change/
+└── index.ts          # 主入口文件
+```
+
+### 工作原理
+
+1. **监听值变化**：监听 `DataEvent.onValueInitOrChange` 事件
+2. **类型检查**：检查值是否为 `ref` 类型
+3. **路径跟踪**：使用 `trackByKeyPath` 跟踪引用路径
+4. **Schema 转换**：将 AST 类型转换为 JSON Schema
+5. **回调触发**：当引用的类型发生变化时触发回调
+
+### 使用到的 flowgram API
+
+#### @flowgram.ai/variable-core
+
+- `getNodeScope(context.node).available.trackByKeyPath`: 跟踪指定路径的值变化，当路径对应的值发生变化时触发回调。
+
+#### @flowgram.ai/json-schema
+
+- `JsonSchemaUtils.astToSchema`: 将 AST 类型节点转换为 JSON Schema 对象。
+
+
+

apps/docs/src/zh/materials/form-plugins/_meta.json

@@ -0,0 +1 @@
+[]