@flowgram-vue/form-materials 0.2.0

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

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Component } from 'vue';
+import {
+  type IJsonSchema,
+  JsonSchemaTypeRegistry as OriginJsonSchemaTypeRegistry,
+} from '@flowgram-vue/json-schema';
+
+import { IConditionRule, IConditionRuleFactory } from '@/components/condition-context/types';
+
+export interface ConstantRendererProps<Value = any> {
+  value?: Value;
+  onChange?: (value: Value) => void;
+  readonly?: boolean;
+  schema?: IJsonSchema;
+  [key: string]: any;
+}
+
+export interface JsonSchemaTypeRegistry<Value = any> extends OriginJsonSchemaTypeRegistry {
+  ConstantRenderer: Component;
+  conditionRule?: IConditionRule | IConditionRuleFactory;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { defineComponent, h, type PropType } from 'vue';
+import {
+  type IJsonSchema,
+  useTypeManager as useOriginTypeManager,
+  TypePresetProvider as OriginTypePresetProvider,
+  JsonSchemaTypeManager,
+} from '@flowgram-vue/json-schema';
+
+import { type JsonSchemaTypeRegistry } from './types';
+import { initRegistries, jsonSchemaTypePreset } from './type-definition';
+
+initRegistries();
+
+export const useTypeManager = () =>
+  useOriginTypeManager() as unknown as JsonSchemaTypeManager<IJsonSchema, JsonSchemaTypeRegistry>;
+
+export const JsonSchemaTypePresetProvider = defineComponent({
+  name: 'JsonSchemaTypePresetProvider',
+  props: {
+    types: {
+      type: Array as PropType<JsonSchemaTypeRegistry[]>,
+      default: () => [],
+    },
+  },
+  setup(props, { slots }) {
+    return () =>
+      h(
+        OriginTypePresetProvider,
+        { types: [...jsonSchemaTypePreset, ...props.types] },
+        () => slots.default?.()
+      );
+  },
+});

package/src/shared/flow-value/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { FlowValueUtils } from './utils';
+export {
+  type IFlowValueExtra,
+  type FlowValueType,
+  type IFlowValue,
+  type IFlowConstantValue,
+  type IFlowRefValue,
+  type IFlowExpressionValue,
+  type IFlowTemplateValue,
+  type IFlowConstantRefValue,
+  type IInputsValues,
+} from './types';

package/src/shared/flow-value/schema.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import z from 'zod';
+
+// Shared extra schema for flow value types
+export const extraSchema = z
+  .object({
+    index: z.number().optional(),
+  })
+  .optional();
+
+export const constantSchema = z.object({
+  type: z.literal('constant'),
+  content: z.any().optional(),
+  schema: z.any().optional(),
+  extra: extraSchema,
+});
+
+export const refSchema = z.object({
+  type: z.literal('ref'),
+  content: z.array(z.string()).optional(),
+  extra: extraSchema,
+});
+
+export const expressionSchema = z.object({
+  type: z.literal('expression'),
+  content: z.string().optional(),
+  extra: extraSchema,
+});
+
+export const templateSchema = z.object({
+  type: z.literal('template'),
+  content: z.string().optional(),
+  extra: extraSchema,
+});

package/src/shared/flow-value/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { IJsonSchema } from '@flowgram-vue/json-schema';
+
+export interface IFlowValueExtra {
+  index?: number;
+}
+
+export type FlowValueType = 'constant' | 'ref' | 'expression' | 'template';
+
+export interface IFlowConstantValue {
+  type: 'constant';
+  content?: any;
+  schema?: IJsonSchema;
+  extra?: IFlowValueExtra;
+}
+
+export interface IFlowRefValue {
+  type: 'ref';
+  content?: string[];
+  extra?: IFlowValueExtra;
+}
+
+export interface IFlowExpressionValue {
+  type: 'expression';
+  content?: string;
+  extra?: IFlowValueExtra;
+}
+
+export interface IFlowTemplateValue {
+  type: 'template';
+  content?: string;
+  extra?: IFlowValueExtra;
+}
+
+export type IFlowValue =
+  | IFlowConstantValue
+  | IFlowRefValue
+  | IFlowExpressionValue
+  | IFlowTemplateValue;
+
+export type IFlowConstantRefValue = IFlowConstantValue | IFlowRefValue;
+
+export interface IInputsValues {
+  [key: string]: IInputsValues | IFlowValue | undefined;
+}

package/src/shared/flow-value/utils.ts

@@ -0,0 +1,213 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { isArray, isObject, isPlainObject, uniq } from 'lodash-es';
+import { IJsonSchema, JsonSchemaUtils } from '@flowgram-vue/json-schema';
+import { Scope } from '@flowgram-vue/variable-core';
+
+import {
+  IFlowConstantValue,
+  IFlowRefValue,
+  IFlowExpressionValue,
+  IFlowTemplateValue,
+  IFlowValue,
+  IFlowConstantRefValue,
+  FlowValueType,
+} from './types';
+import { constantSchema, refSchema, expressionSchema, templateSchema } from './schema';
+
+export namespace FlowValueUtils {
+  /**
+   * Check if the value is a constant type
+   */
+  export function isConstant(value: any): value is IFlowConstantValue {
+    return constantSchema.safeParse(value).success;
+  }
+
+  /**
+   * Check if the value is a reference type
+   */
+  export function isRef(value: any): value is IFlowRefValue {
+    return refSchema.safeParse(value).success;
+  }
+
+  /**
+   * Check if the value is an expression type
+   */
+  export function isExpression(value: any): value is IFlowExpressionValue {
+    return expressionSchema.safeParse(value).success;
+  }
+
+  /**
+   * Check if the value is a template type
+   */
+  export function isTemplate(value: any): value is IFlowTemplateValue {
+    return templateSchema.safeParse(value).success;
+  }
+
+  /**
+   * Check if the value is either a constant or reference type
+   */
+  export function isConstantOrRef(value: any): value is IFlowConstantRefValue {
+    return isConstant(value) || isRef(value);
+  }
+
+  /**
+   * Check if the value is a valid flow value type
+   */
+  export function isFlowValue(value: any): value is IFlowValue {
+    return isConstant(value) || isRef(value) || isExpression(value) || isTemplate(value);
+  }
+
+  /**
+   * Traverse all flow values in the given value
+   * @param value The value to traverse
+   * @param options The options to traverse
+   * @returns A generator of flow values
+   */
+  export function* traverse(
+    value: any,
+    options: {
+      includeTypes: FlowValueType[];
+      path?: string;
+      pathArr?: string[];
+    }
+  ): Generator<{ value: IFlowValue; path: string; pathArr: string[] }> {
+    const {
+      includeTypes = ['ref', 'template', 'expression', 'constant'],
+      path = '',
+      pathArr = [],
+    } = options || {};
+
+    if (isPlainObject(value)) {
+      if (isRef(value) && includeTypes.includes('ref')) {
+        yield { value, path, pathArr };
+        return;
+      }
+
+      if (isTemplate(value) && includeTypes.includes('template')) {
+        yield { value, path, pathArr };
+        return;
+      }
+
+      if (isExpression(value) && includeTypes.includes('expression')) {
+        yield { value, path, pathArr };
+        return;
+      }
+
+      if (isConstant(value) && includeTypes.includes('constant')) {
+        yield { value, path, pathArr };
+        return;
+      }
+
+      for (const [_key, _value] of Object.entries(value)) {
+        yield* traverse(_value, {
+          ...options,
+          path: path ? `${path}.${_key}` : _key,
+          pathArr: [...pathArr, _key],
+        });
+      }
+      return;
+    }
+
+    if (isArray(value)) {
+      for (const [_idx, _value] of value.entries()) {
+        yield* traverse(_value, {
+          ...options,
+          path: path ? `${path}[${_idx}]` : `[${_idx}]`,
+          pathArr: [...pathArr, `[${_idx}]`],
+        });
+      }
+      return;
+    }
+
+    return;
+  }
+
+  /**
+   * Get all key paths in the template value
+   * @param value The template value
+   * @returns A list of key paths
+   */
+  export function getTemplateKeyPaths(value: IFlowTemplateValue) {
+    // find all keyPath wrapped in {{}}
+    const keyPathReg = /\{\{([^\}\{]+)\}\}/g;
+    return uniq(value.content?.match(keyPathReg) || []).map((_keyPath) =>
+      _keyPath.slice(2, -2).split('.')
+    );
+  }
+
+  /**
+   * Infer the schema of the constant value
+   * @param value
+   * @returns
+   */
+  export function inferConstantJsonSchema(value: IFlowConstantValue): IJsonSchema | undefined {
+    if (value?.schema) {
+      return value.schema;
+    }
+
+    if (typeof value.content === 'string') {
+      return {
+        type: 'string',
+      };
+    }
+
+    if (typeof value.content === 'number') {
+      return {
+        type: 'number',
+      };
+    }
+
+    if (typeof value.content === 'boolean') {
+      return {
+        type: 'boolean',
+      };
+    }
+
+    if (isObject(value.content)) {
+      return {
+        type: 'object',
+      };
+    }
+    return undefined;
+  }
+
+  /**
+   * Infer the schema of the flow value
+   * @param values The flow value or object contains flow value
+   * @param scope
+   * @returns
+   */
+  export function inferJsonSchema(values: any, scope: Scope): IJsonSchema | undefined {
+    if (isPlainObject(values)) {
+      if (isConstant(values)) {
+        return inferConstantJsonSchema(values);
+      }
+
+      if (isRef(values)) {
+        const variable = scope.available.getByKeyPath(values?.content);
+        const schema = variable?.type ? JsonSchemaUtils.astToSchema(variable?.type) : undefined;
+
+        return schema;
+      }
+
+      if (isTemplate(values)) {
+        return { type: 'string' };
+      }
+
+      return {
+        type: 'object',
+        properties: Object.keys(values).reduce((acc, key) => {
+          const schema = inferJsonSchema((values as any)[key], scope);
+          if (schema) {
+            acc[key] = schema;
+          }
+          return acc;
+        }, {} as Record<string, IJsonSchema>),
+      };
+    }
+  }
+}

package/src/shared/format-legacy-refs/index.ts

@@ -0,0 +1,158 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { isObject } from 'lodash-es';
+
+interface LegacyFlowRefValueSchema {
+  type: 'ref';
+  content: string;
+}
+
+interface NewFlowRefValueSchema {
+  type: 'ref';
+  content: string[];
+}
+
+/**
+ * In flowgram 0.2.0, for introducing Loop variable functionality,
+ * the FlowRefValueSchema type definition is updated:
+ *
+ * interface LegacyFlowRefValueSchema {
+ *  type: 'ref';
+ *  content: string;
+ * }
+ *
+ * interface NewFlowRefValueSchema {
+ *  type: 'ref';
+ *  content: string[];
+ * }
+ *
+ *
+ * For making sure backend json will not be changed, we provide format legacy ref utils for updating the formData
+ *
+ * How to use:
+ *
+ * 1. Call formatLegacyRefOnSubmit on the formData before submitting
+ * 2. Call formatLegacyRefOnInit on the formData after submitting
+ *
+ * Example:
+ * import { formatLegacyRefOnSubmit, formatLegacyRefOnInit } from '@flowgram-vue/form-materials';
+ * formMeta: {
+ *  formatOnSubmit: (data) => formatLegacyRefOnSubmit(data),
+ *  formatOnInit: (data) => formatLegacyRefOnInit(data),
+ * }
+ */
+export function formatLegacyRefOnSubmit(value: any): any {
+  if (isObject(value)) {
+    if (isLegacyFlowRefValueSchema(value)) {
+      return formatLegacyRefToNewRef(value);
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, value]: [string, any]) => [
+        key,
+        formatLegacyRefOnSubmit(value),
+      ])
+    );
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(formatLegacyRefOnSubmit);
+  }
+
+  return value;
+}
+
+/**
+ * In flowgram 0.2.0, for introducing Loop variable functionality,
+ * the FlowRefValueSchema type definition is updated:
+ *
+ * interface LegacyFlowRefValueSchema {
+ *  type: 'ref';
+ *  content: string;
+ * }
+ *
+ * interface NewFlowRefValueSchema {
+ *  type: 'ref';
+ *  content: string[];
+ * }
+ *
+ *
+ * For making sure backend json will not be changed, we provide format legacy ref utils for updating the formData
+ *
+ * How to use:
+ *
+ * 1. Call formatLegacyRefOnSubmit on the formData before submitting
+ * 2. Call formatLegacyRefOnInit on the formData after submitting
+ *
+ * Example:
+ * import { formatLegacyRefOnSubmit, formatLegacyRefOnInit } from '@flowgram-vue/form-materials';
+ *
+ * formMeta: {
+ *  formatOnSubmit: (data) => formatLegacyRefOnSubmit(data),
+ *  formatOnInit: (data) => formatLegacyRefOnInit(data),
+ * }
+ */
+export function formatLegacyRefOnInit(value: any): any {
+  if (isObject(value)) {
+    if (isNewFlowRefValueSchema(value)) {
+      return formatNewRefToLegacyRef(value);
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, value]: [string, any]) => [
+        key,
+        formatLegacyRefOnInit(value),
+      ])
+    );
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(formatLegacyRefOnInit);
+  }
+
+  return value;
+}
+
+export function isLegacyFlowRefValueSchema(value: any): value is LegacyFlowRefValueSchema {
+  return (
+    isObject(value) &&
+    Object.keys(value).length === 2 &&
+    (value as any).type === 'ref' &&
+    typeof (value as any).content === 'string'
+  );
+}
+
+export function isNewFlowRefValueSchema(value: any): value is NewFlowRefValueSchema {
+  return (
+    isObject(value) &&
+    Object.keys(value).length === 2 &&
+    (value as any).type === 'ref' &&
+    Array.isArray((value as any).content)
+  );
+}
+
+export function formatLegacyRefToNewRef(value: LegacyFlowRefValueSchema) {
+  const keyPath = value.content.split('.');
+
+  if (keyPath[1] === 'outputs') {
+    return {
+      type: 'ref',
+      content: [`${keyPath[0]}.${keyPath[1]}`, ...(keyPath.length > 2 ? keyPath.slice(2) : [])],
+    };
+  }
+
+  return {
+    type: 'ref',
+    content: keyPath,
+  };
+}
+
+export function formatNewRefToLegacyRef(value: NewFlowRefValueSchema) {
+  return {
+    type: 'ref',
+    content: value.content.join('.'),
+  };
+}

package/src/shared/format-legacy-refs/readme.md

@@ -0,0 +1,38 @@
+# Notice
+
+In `@flowgram-vue/form-materials@0.2.0`, for introducing loop-related materials,
+
+The FlowRefValueSchema type definition is updated:
+
+```typescript
+interface LegacyFlowRefValueSchema {
+  type: 'ref';
+  content: string;
+}
+
+interface NewFlowRefValueSchema {
+  type: 'ref';
+  content: string[];
+}
+```
+
+
+
+For making sure backend json will not be changed in your application, we provide `format-legacy-ref` utils for upgrading
+
+
+How to use:
+
+1. Call formatLegacyRefOnSubmit on the formData before submitting
+2. Call formatLegacyRefOnInit on the formData after submitting
+
+Example:
+
+```typescript
+import { formatLegacyRefOnSubmit, formatLegacyRefOnInit } from '@flowgram-vue/form-materials';
+
+formMeta: {
+  formatOnSubmit: (data) => formatLegacyRefOnSubmit(data),
+  formatOnInit: (data) => formatLegacyRefOnInit(data),
+}
+```

package/src/shared/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export {
+  FlowValueUtils,
+  type FlowValueType,
+  type IFlowConstantRefValue,
+  type IFlowConstantValue,
+  type IFlowExpressionValue,
+  type IFlowRefValue,
+  type IFlowTemplateValue,
+  type IFlowValue,
+  type IFlowValueExtra,
+  type IInputsValues,
+} from './flow-value';
+export {
+  formatLegacyRefOnInit,
+  formatLegacyRefOnSubmit,
+  formatLegacyRefToNewRef,
+  formatNewRefToLegacyRef,
+  isLegacyFlowRefValueSchema,
+  isNewFlowRefValueSchema,
+} from './format-legacy-refs';
+export { createInjectMaterial } from './inject-material';
+export { lazySuspense, withSuspense } from './lazy-suspense';
+export {
+  polyfillCreateRoot,
+  unstableSetCreateRoot,
+  type IPolyfillRoot,
+} from './polyfill-create-root';

package/src/shared/inject-material/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { defineComponent, h, type Component } from 'vue';
+import { FlowRendererComponentType, FlowRendererRegistry } from '@flowgram-vue/renderer';
+import { usePlaygroundContainer } from '@flowgram-vue/core';
+
+type WithRenderKey<T> = T & { renderKey?: string };
+
+/**
+ * Wraps a Vue material so consumers can replace it via FlowRendererRegistry.
+ */
+export function createInjectMaterial<Props>(
+  Component: WithRenderKey<Component>,
+  params?: {
+    renderKey?: string;
+  }
+): WithRenderKey<Component> {
+  const renderKey =
+    params?.renderKey || Component.renderKey || (Component as { name?: string }).name || '';
+
+  const InjectComponent = defineComponent({
+    name: `Inject${(Component as { name?: string }).name || 'Material'}`,
+    inheritAttrs: false,
+    setup(_props, { attrs, slots }) {
+      const container = usePlaygroundContainer();
+
+      return () => {
+        if (!container?.isBound?.(FlowRendererRegistry)) {
+          return h(Component, attrs, slots);
+        }
+
+        const rendererRegistry = container.get(FlowRendererRegistry);
+        const renderer = rendererRegistry.tryToGetRendererComponent(renderKey);
+
+        if (renderer?.type !== FlowRendererComponentType.VUE) {
+          return h(Component, attrs, slots);
+        }
+
+        return h(renderer.renderer as Component, attrs, slots);
+      };
+    },
+  }) as WithRenderKey<Component>;
+
+  InjectComponent.renderKey = renderKey;
+
+  return InjectComponent;
+}

package/src/shared/lazy-suspense/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { defineAsyncComponent, h, type AsyncComponentLoader, type Component } from 'vue';
+
+export function withSuspense<T extends Component>(Component: T, _fallback?: Component): T {
+  return Component;
+}
+
+export function lazySuspense(loader: AsyncComponentLoader, fallback?: Component) {
+  return defineAsyncComponent({
+    loader,
+    loadingComponent: fallback || {
+      name: 'FgSkeleton',
+      render: () => h('div', { class: 'fg-skeleton' }),
+    },
+  });
+}