@flowgram.ai/form-materials 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/hooks/use-object-list/index.tsx

@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { useEffect, useState } from 'react';
+
+import { nanoid } from 'nanoid';
+import { difference, get, isObject, set } from 'lodash';
+
+function genId() {
+  return nanoid();
+}
+
+interface ListItem<ValueType> {
+  id: string;
+  key?: string;
+  value?: ValueType;
+}
+
+type ObjectType<ValueType> = Record<string, ValueType | undefined>;
+
+export function useObjectList<ValueType>({
+  value,
+  onChange,
+  sortIndexKey,
+}: {
+  value?: ObjectType<ValueType>;
+  onChange: (value?: ObjectType<ValueType>) => void;
+  sortIndexKey?: string;
+}) {
+  const [list, setList] = useState<ListItem<ValueType>[]>([]);
+
+  useEffect(() => {
+    setList((_prevList) => {
+      const newKeys = Object.entries(value || {})
+        .sort((a, b) => get(a[1], sortIndexKey || 0) - get(b[1], sortIndexKey || 0))
+        .map(([key]) => key);
+
+      const oldKeys = _prevList.map((item) => item.key).filter(Boolean) as string[];
+      const addKeys = difference(newKeys, oldKeys);
+
+      return _prevList
+        .filter((item) => !item.key || newKeys.includes(item.key))
+        .map((item) => ({
+          id: item.id,
+          key: item.key,
+          value: item.key ? value?.[item.key!] : item.value,
+        }))
+        .concat(
+          addKeys.map((_key) => ({
+            id: genId(),
+            key: _key,
+            value: value?.[_key],
+          }))
+        );
+    });
+  }, [value]);
+
+  const add = () => {
+    setList((prevList) => [
+      ...prevList,
+      {
+        id: genId(),
+      },
+    ]);
+  };
+
+  const updateValue = (itemId: string, value: ValueType) => {
+    setList((prevList) => {
+      const nextList = prevList.map((_item) => {
+        if (_item.id === itemId) {
+          return {
+            ..._item,
+            value,
+          };
+        }
+        return _item;
+      });
+
+      onChange(
+        Object.fromEntries(
+          nextList
+            .filter((item) => item.key)
+            .map((item) => [item.key!, item.value])
+            .map((_res, idx) => {
+              if (isObject(_res[1]) && sortIndexKey) {
+                set(_res[1], sortIndexKey, idx);
+              }
+              return _res;
+            })
+        )
+      );
+
+      return nextList;
+    });
+  };
+
+  const updateKey = (itemId: string, key: string) => {
+    setList((prevList) => {
+      const nextList = prevList.map((_item) => {
+        if (_item.id === itemId) {
+          return {
+            ..._item,
+            key,
+          };
+        }
+        return _item;
+      });
+
+      onChange(
+        Object.fromEntries(
+          nextList.filter((item) => item.key).map((item) => [item.key!, item.value])
+        )
+      );
+
+      return nextList;
+    });
+  };
+
+  const remove = (itemId: string) => {
+    setList((prevList) => {
+      const nextList = prevList.filter((_item) => _item.id !== itemId);
+
+      onChange(
+        Object.fromEntries(
+          nextList.filter((item) => item.key).map((item) => [item.key!, item.value])
+        )
+      );
+
+      return nextList;
+    });
+  };
+
+  return { list, add, updateKey, updateValue, remove };
+}

package/src/index.ts

@@ -5,6 +5,8 @@
 
 export * from './components';
 export * from './effects';
-export * from './utils';
+export * from './shared';
 export * from './typings';
 export * from './form-plugins';
+export * from './plugins';
+export * from './validate';

package/src/{utils/format-legacy-refs → plugins/disable-declaration-plugin}/config.json

@@ -1,5 +1,5 @@
 {
-  "name": "format-legacy-ref",
+  "name": "disable-declaration-plugin",
   "depMaterials": [],
   "depPackages": []
 }

package/src/plugins/disable-declaration-plugin/create-disable-declaration-plugin.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  ASTMatch,
+  definePluginCreator,
+  type GlobalEventActionType,
+  VariableEngine,
+} from '@flowgram.ai/editor';
+
+export const createDisableDeclarationPlugin = definePluginCreator<void>({
+  onInit(ctx) {
+    const variableEngine = ctx.get(VariableEngine);
+
+    const handleEvent = (action: GlobalEventActionType) => {
+      if (ASTMatch.isVariableDeclaration(action.ast)) {
+        if (!action.ast.meta?.disabled) {
+          action.ast.updateMeta({
+            ...(action.ast.meta || {}),
+            disabled: true,
+          });
+        }
+      }
+    };
+
+    variableEngine.onGlobalEvent('NewAST', handleEvent);
+    variableEngine.onGlobalEvent('UpdateAST', handleEvent);
+  },
+});

package/src/plugins/disable-declaration-plugin/index.tsx

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { createDisableDeclarationPlugin } from './create-disable-declaration-plugin';

package/src/plugins/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './json-schema-preset';
+export * from './disable-declaration-plugin';

package/src/plugins/json-schema-preset/config.json

@@ -0,0 +1,9 @@
+{
+  "name": "json-schema-preset",
+  "depMaterials": [
+    "components/code-editor-mini"
+  ],
+  "depPackages": [
+    "@flowgram.ai/json-schema"
+  ]
+}

package/src/plugins/json-schema-preset/create-type-preset-plugin.tsx

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  BaseTypeManager,
+  jsonSchemaContainerModule,
+  JsonSchemaTypeManager,
+} from '@flowgram.ai/json-schema';
+import { definePluginCreator } from '@flowgram.ai/editor';
+
+import { jsonSchemaTypePreset } from './type-definition';
+import { JsonSchemaTypeRegistry } from './manager';
+
+export const createTypePresetPlugin = definePluginCreator<{
+  types?: Partial<JsonSchemaTypeRegistry> & Pick<JsonSchemaTypeRegistry, 'type'>[];
+  unregisterTypes?: string[];
+}>({
+  onInit(ctx, opts) {
+    const typeManager = ctx.get(BaseTypeManager) as JsonSchemaTypeManager;
+    jsonSchemaTypePreset.forEach((_type) => typeManager.register(_type));
+
+    opts.types?.forEach((_type) => typeManager.register(_type));
+    opts.unregisterTypes?.forEach((_type) => typeManager.unregister(_type));
+  },
+  containerModules: [jsonSchemaContainerModule],
+});

package/src/plugins/json-schema-preset/index.tsx

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import React from 'react';
+
+import {
+  type IJsonSchema,
+  JsonSchemaUtils,
+  useTypeManager as useOriginTypeManager,
+  TypePresetProvider as OriginTypePresetProvider,
+  JsonSchemaTypeManager,
+  type JsonSchemaBasicType,
+} from '@flowgram.ai/json-schema';
+
+import { jsonSchemaTypePreset } from './type-definition';
+import { type JsonSchemaTypeRegistry, type ConstantRendererProps } from './manager';
+import { createTypePresetPlugin } from './create-type-preset-plugin';
+
+const useTypeManager = () =>
+  useOriginTypeManager() as JsonSchemaTypeManager<IJsonSchema, JsonSchemaTypeRegistry>;
+
+const JsonSchemaTypePresetProvider = ({
+  types = [],
+  children,
+}: React.PropsWithChildren<{ types: JsonSchemaTypeRegistry[] }>) => (
+  <OriginTypePresetProvider types={[...jsonSchemaTypePreset, ...types]}>
+    {children}
+  </OriginTypePresetProvider>
+);
+
+export {
+  createTypePresetPlugin,
+  useTypeManager,
+  JsonSchemaTypePresetProvider,
+  IJsonSchema,
+  JsonSchemaUtils,
+  JsonSchemaTypeRegistry,
+  ConstantRendererProps,
+  JsonSchemaBasicType,
+};

package/src/plugins/json-schema-preset/manager.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { JsonSchemaTypeRegistry as OriginJsonSchemaTypeRegistry } from '@flowgram.ai/json-schema';
+
+export interface ConstantRendererProps<Value = any> {
+  value?: Value;
+  onChange?: (value: Value) => void;
+  readonly?: boolean;
+}
+export interface JsonSchemaTypeRegistry<Value = any> extends OriginJsonSchemaTypeRegistry {
+  /**
+   * Render Constant Input
+   */
+  ConstantRenderer: React.FC<ConstantRendererProps<Value>>;
+}

package/src/plugins/json-schema-preset/type-definition/array.tsx

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+
+import { CodeEditorMini } from '@/components/code-editor-mini';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const arrayRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'array',
+  ConstantRenderer: (props) => (
+    <CodeEditorMini
+      value={props.value}
+      languageId="json"
+      onChange={(v) => props.onChange?.(v)}
+      placeholder={I18n.t('Please Input Array')}
+      readonly={props.readonly}
+    />
+  ),
+};

package/src/plugins/json-schema-preset/type-definition/boolean.tsx

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+import { Select } from '@douyinfe/semi-ui';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const booleanRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'boolean',
+  ConstantRenderer: (props) => {
+    const { value, onChange, ...rest } = props;
+    return (
+      <Select
+        placeholder={I18n.t('Please Select Boolean')}
+        size="small"
+        disabled={props.readonly}
+        optionList={[
+          { label: I18n.t('True'), value: 1 },
+          { label: I18n.t('False'), value: 0 },
+        ]}
+        value={value ? 1 : 0}
+        onChange={(value) => onChange?.(!!value)}
+        {...rest}
+      />
+    );
+  },
+};

package/src/plugins/json-schema-preset/type-definition/index.tsx

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { jsonSchemaTypeManager } from '@flowgram.ai/json-schema';
+
+import { stringRegistry } from './string';
+import { objectRegistry } from './object';
+import { numberRegistry } from './number';
+import { integerRegistry } from './integer';
+import { booleanRegistry } from './boolean';
+import { arrayRegistry } from './array';
+
+export const jsonSchemaTypePreset = [
+  stringRegistry,
+  objectRegistry,
+  numberRegistry,
+  integerRegistry,
+  booleanRegistry,
+  arrayRegistry,
+];
+
+jsonSchemaTypePreset.forEach((_type) => jsonSchemaTypeManager.register(_type));

package/src/plugins/json-schema-preset/type-definition/integer.tsx

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+import { InputNumber } from '@douyinfe/semi-ui';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const integerRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'integer',
+  ConstantRenderer: (props) => (
+    <InputNumber
+      placeholder={I18n.t('Please Input Integer')}
+      size="small"
+      disabled={props.readonly}
+      precision={0}
+      {...props}
+    />
+  ),
+};

package/src/plugins/json-schema-preset/type-definition/number.tsx

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+import { InputNumber } from '@douyinfe/semi-ui';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const numberRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'number',
+  ConstantRenderer: (props) => (
+    <InputNumber
+      placeholder={I18n.t('Please Input Number')}
+      size="small"
+      disabled={props.readonly}
+      hideButtons
+      {...props}
+    />
+  ),
+};

package/src/plugins/json-schema-preset/type-definition/object.tsx

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+
+import { CodeEditorMini } from '@/components/code-editor-mini';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const objectRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'object',
+  ConstantRenderer: (props) => (
+    <CodeEditorMini
+      value={props.value}
+      onChange={(v) => props.onChange?.(v)}
+      languageId="json"
+      placeholder={I18n.t('Please Input Object')}
+      readonly={props.readonly}
+    />
+  ),
+};

package/src/plugins/json-schema-preset/type-definition/string.tsx

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/* eslint-disable react/prop-types */
+import React from 'react';
+
+import { I18n } from '@flowgram.ai/editor';
+import { Input } from '@douyinfe/semi-ui';
+
+import { type JsonSchemaTypeRegistry } from '../manager';
+
+export const stringRegistry: Partial<JsonSchemaTypeRegistry> = {
+  type: 'string',
+  ConstantRenderer: (props) => (
+    <Input
+      placeholder={I18n.t('Please Input String')}
+      size="small"
+      disabled={props.readonly}
+      {...props}
+    />
+  ),
+};

package/src/{utils → shared}/index.ts

@@ -4,4 +4,4 @@
  */
 
 export * from './format-legacy-refs';
-export * from './json-schema';
+export * from './inject-material';

package/src/shared/inject-material/README.md

@@ -0,0 +1,170 @@
+# InjectMaterial Component
+
+A material component wrapper with dependency injection support for implementing dynamic component replacement mechanisms.
+
+## Why Dependency Injection Matters
+
+### ❌ Tight Coupling: Traditional Dependency Issues
+
+```mermaid
+graph TD
+    A[Material A] --> B[Material B]
+    B --> D[Material D]
+    C[Material C] --> D
+
+    style D fill:#ff4757
+    style A fill:#ffa502
+    style B fill:#ffa502
+    style C fill:#ffa502
+
+    note["💥 Problem: D changes require modifications to A, B, C"]
+```
+
+**Issues:** Chain reactions, high maintenance costs
+
+### ✅ Decoupling: Dependency Injection Solution
+
+```mermaid
+graph TD
+    A[Material A] --> RenderKey[Material D RenderKey]
+    B[Material B] --> RenderKey
+    C[Material C] --> RenderKey
+
+    RenderKey -.-> BaseD[Origin D]
+    CustomD[Custom D] -.-> RenderKey
+
+    style RenderKey fill:#5f27cd
+    style BaseD fill:#2ed573
+    style CustomD fill:#26d0ce
+    style A fill:#a55eea
+    style B fill:#a55eea
+    style C fill:#a55eea
+
+    note2["✅ A, B, C depend on abstract interface, decoupled from D"]
+```
+
+**Benefits:** Hot-swapping, parallel development, version compatibility
+
+## Features
+
+- 🔧 **Dependency Injection**: Support dynamic component replacement via FlowRendererRegistry
+- 🔄 **Smart Fallback**: Automatically use default component when no custom component is registered
+- 🎯 **Type Safety**: Full TypeScript type inference support
+- 📦 **Zero Configuration**: Works out of the box without additional setup
+
+## Usage
+
+### 1. Create Injectable Material Component
+
+```tsx
+import { createInjectMaterial } from '@flowgram.ai/form-materials';
+import { VariableSelector } from './VariableSelector';
+
+// Create injectable material wrapper component
+const InjectVariableSelector = createInjectMaterial(VariableSelector);
+
+// Now you can use it like a regular component
+function MyComponent() {
+  return <InjectVariableSelector value={value} onChange={handleChange} />;
+}
+```
+
+### 2. Register Custom Components
+
+Configure custom renderer in `use-editor-props.tsx`:
+
+```tsx
+import { useEditorProps } from '@flowgram.ai/editor';
+import { YourCustomVariableSelector } from './YourCustomVariableSelector';
+import { VariableSelector } from '@flowgram.ai/form-materials';
+
+function useCustomEditorProps() {
+  const editorProps = useEditorProps({
+    materials: {
+      components: {
+        // Use component's renderKey or component name as key
+        [VariableSelector.renderKey]: YourCustomVariableSelector,
+        [TypeSelector.renderKey]: YourCustomTypeSelector,
+      }
+    }
+  });
+
+  return editorProps;
+}
+```
+
+### 3. Use Custom renderKey
+
+If your component requires a specific renderKey:
+
+```tsx
+const InjectCustomComponent = createInjectMaterial(MyComponent, {
+  renderKey: 'my-custom-key'
+});
+
+// When registering
+{
+  materials: {
+    components: {
+      'my-custom-key': MyCustomRenderer
+    }
+  }
+}
+```
+
+## Sequence Diagram
+
+Complete component registration and rendering sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Editor as use-editor-props
+    participant Registry as FlowRendererRegistry
+    participant Inject as InjectMaterial
+    participant Default as Default Component
+    participant Custom as Custom Component
+
+    Note over App,Custom: Component Registration Phase
+    App->>Editor: Call use-editor-props()
+    Editor->>Editor: Configure materials.components
+    Editor->>Registry: Register component to FlowRendererRegistry
+    Registry->>Registry: Store mapping relationship
+    Registry-->>App: Registration complete
+
+    Note over App,Custom: Component Rendering Phase
+    App->>Inject: Render InjectMaterial component
+    Inject->>Registry: Query renderer (getRendererComponent)
+
+    alt Custom renderer exists
+        Registry-->>Inject: Return custom React component
+        Inject->>Custom: Render with custom component
+        Custom-->>App: Render custom UI
+    else No custom renderer
+        Registry-->>Inject: Return null or type mismatch
+        Inject->>Default: Render with default component
+        Default-->>App: Render default UI
+    end
+```
+
+## Render Key Priority
+
+Component render key determination follows this priority order:
+
+1. `params.renderKey` (second parameter of createInjectMaterial)
+2. `Component.renderKey` (component's own renderKey property)
+3. `Component.name` (component's display name)
+4. Empty string (final fallback)
+
+## Type Definition
+
+```typescript
+interface CreateInjectMaterialOptions {
+  renderKey?: string;
+}
+
+function createInjectMaterial<Props>(
+  Component: React.FC<Props> & { renderKey?: string },
+  params?: CreateInjectMaterialOptions
+): React.FC<Props>
+```