docs(materials): common logic docs

apps/docs/components/form-materials/common/disable-declaration-plugin.tsx

@@ -0,0 +1,36 @@
+/**
+ * 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 { createDisableDeclarationPlugin } from '@flowgram.ai/form-materials';
+
+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
+    plugins={() => [createDisableDeclarationPlugin()]}
+    formMeta={{
+      render: () => (
+        <>
+          <FormHeader />
+          <Field<string[] | undefined> name="variable_selector">
+            {({ field }) => (
+              <VariableSelector value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+        </>
+      ),
+    }}
+  />
+);

apps/docs/components/form-materials/common/json-schema-preset.css

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+.json-schema-color-picker-container {
+  .semi-colorPicker-popover-defaultChildren {
+    width: 100%;
+  }
+}

apps/docs/components/form-materials/common/json-schema-preset.tsx

@@ -0,0 +1,114 @@
+/**
+ * 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 {
+  ConditionRow,
+  ConditionRowValueType,
+  createTypePresetPlugin,
+  DynamicValueInput,
+  IFlowConstantRefValue,
+  type IJsonSchema,
+} from '@flowgram.ai/form-materials';
+import { ColorPicker } from '@douyinfe/semi-ui';
+import { IconColorPalette } from '@douyinfe/semi-icons';
+
+import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';
+
+import './json-schema-preset.css';
+
+const TypeSelector = React.lazy(() =>
+  import('@flowgram.ai/form-materials').then((module) => ({
+    default: module.TypeSelector,
+  }))
+);
+
+export const BasicStory = () => (
+  <FreeFormMetaStoryBuilder
+    filterEndNode
+    transformInitialNode={{
+      start_0: (node) => {
+        node.data.outputs = {
+          type: 'object',
+          properties: {
+            color_output: {
+              type: 'color',
+            },
+          },
+        };
+        return node;
+      },
+    }}
+    plugins={() => [
+      createTypePresetPlugin({
+        types: [
+          {
+            type: 'color',
+            icon: <IconColorPalette />,
+            label: 'Color',
+            ConstantRenderer: ({ value, onChange }) => (
+              <div className="json-schema-color-picker-container ">
+                <ColorPicker
+                  alpha={true}
+                  usePopover={true}
+                  value={value ? ColorPicker.colorStringToValue(value) : undefined}
+                  onChange={(_value) => onChange?.(_value.hex)}
+                />
+              </div>
+            ),
+            conditionRule: {
+              eq: { type: 'color' },
+            },
+          },
+        ],
+      }),
+    ]}
+    formMeta={{
+      render: () => (
+        <>
+          <FormHeader />
+          <b>Type Selector: </b>
+          <Field<Partial<IJsonSchema> | undefined>
+            name="type_selector"
+            defaultValue={{ type: 'color' }}
+          >
+            {({ field }) => (
+              <TypeSelector value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+          <br />
+
+          <b>DynamicValueInput: </b>
+          <Field<IFlowConstantRefValue | undefined>
+            name="dynamic_value_input"
+            defaultValue={{ type: 'constant', schema: { type: 'color' }, content: '#b5ed0c' }}
+          >
+            {({ field }) => (
+              <DynamicValueInput value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+          <br />
+
+          <b>Condition: </b>
+          <Field<ConditionRowValueType | undefined>
+            name="condition_row"
+            defaultValue={{
+              left: { type: 'ref', content: ['start_0', 'color_output'] },
+              operator: 'eq',
+              right: { type: 'ref', content: ['start_0', 'color_output'] },
+            }}
+          >
+            {({ field }) => (
+              <ConditionRow value={field.value} onChange={(value) => field.onChange(value)} />
+            )}
+          </Field>
+          <br />
+        </>
+      ),
+    }}
+  />
+);

apps/docs/components/form-materials/components/condition-row.tsx

@@ -22,7 +22,23 @@ export const BasicStory = () => (
       render: () => (
         <>
           <FormHeader />
-          <Field<any | undefined> name="condition_row">
+          <Field<any | undefined>
+            name="condition_row"
+            defaultValue={{
+              left: {
+                type: 'ref',
+                content: ['start_0', 'str'],
+              },
+              operator: 'eq',
+              right: {
+                type: 'constant',
+                content: 'Hello World!',
+                schema: {
+                  type: 'string',
+                },
+              },
+            }}
+          >
             {({ field }) => (
               <ConditionRow value={field.value} onChange={(value) => field.onChange(value)} />
             )}

apps/docs/src/en/materials/common/disable-declaration-plugin.mdx

@@ -1,11 +1,84 @@
 import { SourceCode } from '@theme';
+import { BasicStory } from 'components/form-materials/common/disable-declaration-plugin';
+
+# DisableDeclarationPlugin
+
+:::note{title=""}
+
+In the design of the materials library, **"nodes themselves" are defined as VariableDeclaration**.
+
+Components in the materials library such as [`VariableSelector`](../components/variable-selector), [`PromptEditorWithVariables`](../components/prompt-editor-with-variables), and [`SQLEditorWithVariables`](../components/sql-editor-with-variables) all support selecting **"node"** by default.
 
-:::warning
-The material has been developed and the documentation is still being improved. Contributions are welcome.
 :::
 
-# DisableDeclarationPlugin (WIP)
+DisableDeclarationPlugin can **disable variable declarations (only allowing drilling down)** , making "node" unselectable.
+
+## Demo
+
+
+### Basic Usage
+
+<BasicStory />
+
+```tsx pure title="use-editor-props.tsx"
+import { createDisableDeclarationPlugin } from '@flowgram.ai/form-materials';
+
+// ...
+{
+  plugins: () => [createDisableDeclarationPlugin()],
+}
+// ...
+```
+
+## API
+
+### createDisableDeclarationPlugin
+
+Used to create a plugin that disables variable declarations. This plugin intercepts events from the variable engine and marks all variable declarations as disabled.
+
+```ts
+export const createDisableDeclarationPlugin = definePluginCreator<void>({...});
+```
+
+**Parameters**: None
+
+**Return Value**: A plugin instance that can be directly added to the Editor's plugin list.
+
+## Source Code Guide
 
 <SourceCode
-  href="https://github.com/bytedance/flowgram.ai/tree/main/packages/materials/form-materials/src/plugins/disable-declaration-plugin"
-/>
+  href="https://github.com/bytedance/flowgram.ai/blob/main/packages/materials/form-materials/src/plugins/disable-declaration-plugin/create-disable-declaration-plugin.ts"
+/>
+
+You can copy the source code locally using the CLI command:
+
+```bash
+npx @flowgram.ai/cli@latest materials plugins/disable-declaration-plugin
+```
+
+### Directory Structure
+
+```plaintext
+packages/materials/form-materials/src/plugins/disable-declaration-plugin/
+└── create-disable-declaration-plugin.ts  # Main implementation file of the plugin
+```
+
+### Core Implementation
+
+The core implementation of DisableDeclarationPlugin is very concise, mainly including the following steps:
+
+1. **Plugin Initialization**: Create the plugin through `definePluginCreator` and obtain the variable engine instance in the `onInit` hook
+2. **Event Listening**: Listen to the `NewAST` and `UpdateAST` events of the variable engine
+3. **Processing Logic**: When a variable declaration type (`VariableDeclaration`) AST node is detected, set its `meta.disabled` property to `true`
+
+This implementation ensures that all newly created or updated variable declarations are automatically disabled, making them unselectable in variable selectors and other components.
+
+### Dependencies
+
+#### flowgram API
+
+[**@flowgram.ai/editor**](https://github.com/bytedance/flowgram.ai/tree/main/packages/client/editor)
+- [`ASTMatch`](https://flowgram.ai/auto-docs/editor/modules/ASTMatch): A utility class for matching and determining AST node types
+- [`definePluginCreator`](https://flowgram.ai/auto-docs/core/functions/definePluginCreator): A function to define plugin creators
+- [`GlobalEventActionType`](https://flowgram.ai/auto-docs/editor/interfaces/GlobalEventActionType): Type definitions for global event actions
+- [`VariableEngine`](https://flowgram.ai/auto-docs/editor/classes/VariableEngine): Variable engine responsible for managing and processing variable-related operations

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

@@ -1,12 +1,12 @@
 import { SourceCode } from '@theme';
 
-# Flow Value
+# FlowValue
 
-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.
+FlowValue 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
+## FlowValue Types
 
-Flow Value supports the following four types:
+FlowValue 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.
@@ -59,7 +59,7 @@ The expression type is currently in WIP status and does not support type derivat
 
 ## FlowValueUtils Utility Class
 
-FlowValueUtils provides rich utility functions for handling Flow Values:
+FlowValueUtils provides rich utility functions for handling FlowValues:
 
 ### Type Checking Functions
 
@@ -68,17 +68,17 @@ FlowValueUtils provides rich utility functions for handling Flow Values:
 - `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
+- `isFlowValue(value)` - Check if it's a valid FlowValue type
 
 ### Traversal and Extraction Functions
 
-- `traverse(value, options)` - Traverse all Flow Values in an object, with type filtering support
+- `traverse(value, options)` - Traverse all FlowValues 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
+- `inferJsonSchema(values, scope)` - Infer corresponding JSON Schema based on FlowValue
 
 ## Usage Examples
 
@@ -90,7 +90,7 @@ if (FlowValueUtils.isConstant(value)) {
   console.log('This is a constant value:', value.content);
 }
 
-// Traverse Flow Values
+// Traverse FlowValues
 for (const { value, path } of FlowValueUtils.traverse(data, {
   includeTypes: ['ref', 'template']
 })) {
@@ -108,9 +108,9 @@ console.log('Template variables:', templatePaths); // [['user', 'name'], ['count
   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:
+The core type definitions of FlowValue include:
 
-- `IFlowValue` - Union type of Flow Value
+- `IFlowValue` - Union type of FlowValue
 - `IFlowConstantValue` - Constant type interface
 - `IFlowRefValue` - Reference type interface
 - `IFlowExpressionValue` - Expression type interface
@@ -135,12 +135,12 @@ npx @flowgram.ai/cli@latest materials shared/flow-value
 ```
 flow-value/
 ├── index.ts           # Main entry file, exports all types and utility functions
-├── types.ts           # Type definitions file, contains all Flow Value interface definitions
+├── types.ts           # Type definitions file, contains all FlowValue 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.
+- [Zod](https://v3.zod.dev/): Used for type validation and data parsing to determine if FlowValue schemas meet expectations.