@form-engine-ts/react 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,64 +1,97 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode, ComponentType } from 'react';
3
- import { FieldType, FormSchema, FormField, SchemaIssue, TranslationAdapter, AsyncTranslationAdapter, ValidationError, FormValue, ValidationIssue, FormValues, AnswerValidationResult } from '@form-engine-ts/core';
3
+ import { QuestionType, FormField, ChoiceOption, FormPage, FormPolicy, FormSchema, DisplayCondition, JsonValue, SchemaIssue, ValidationError, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, TranslationReport, FormValue, ValidationIssue, FormValues, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
4
4
 
5
- interface BuilderPolicy {
6
- readonly allowedFieldTypes?: readonly FieldType[];
7
- readonly maxFields?: number;
8
- readonly maxOptionsPerField?: number;
9
- readonly maxTextLength?: number;
10
- readonly requiredLocales?: readonly string[];
5
+ /** @deprecated Import FormPolicy from @form-engine-ts/core instead. */
6
+ type BuilderPolicy = FormPolicy;
7
+ type BuilderIdKind = "field" | "option" | "page";
8
+ interface BuilderFactories {
9
+ readonly createField?: (type: QuestionType, id: string) => FormField;
10
+ readonly createOption?: (field: FormField, id: string) => ChoiceOption;
11
+ readonly createPage?: (id: string, questionIds: string[]) => FormPage;
12
+ }
13
+ interface BuilderTextTarget {
14
+ readonly kind: "form" | "page" | "field" | "option";
15
+ readonly id?: string;
11
16
  }
12
17
  interface FormBuilderOptions {
13
18
  readonly schema: FormSchema;
14
19
  readonly onChange: (schema: FormSchema) => void;
15
- readonly policy?: BuilderPolicy;
16
- readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
20
+ readonly policy?: FormPolicy;
21
+ readonly idFactory?: (kind: BuilderIdKind, existingIds: ReadonlySet<string>) => string;
22
+ readonly factories?: BuilderFactories;
17
23
  }
18
24
  type BuilderActionError = {
25
+ readonly type: "invalid_id";
26
+ readonly kind: BuilderIdKind;
27
+ readonly id: string;
28
+ } | {
19
29
  readonly type: "max_fields_exceeded";
20
30
  readonly max: number;
21
31
  } | {
22
32
  readonly type: "max_options_exceeded";
23
33
  readonly max: number;
34
+ } | {
35
+ readonly type: "max_text_length_exceeded";
36
+ readonly max: number;
24
37
  } | {
25
38
  readonly type: "disallowed_field_type";
26
- readonly fieldType: FieldType;
39
+ readonly fieldType: QuestionType;
40
+ } | {
41
+ readonly type: "node_not_found";
42
+ readonly kind: BuilderTextTarget["kind"];
43
+ readonly id: string;
27
44
  } | {
28
45
  readonly type: "invalid_operation";
29
46
  readonly message: string;
30
47
  };
31
- interface BuilderActionResult {
32
- readonly success: boolean;
33
- readonly error?: BuilderActionError;
34
- }
48
+ type BuilderActionResult = {
49
+ readonly success: true;
50
+ } | {
51
+ readonly success: false;
52
+ readonly error: BuilderActionError;
53
+ };
35
54
  interface FormBuilderResult {
36
55
  readonly schema: FormSchema;
37
- readonly addField: (type: FieldType, pageId?: string) => BuilderActionResult;
38
- readonly removeField: (fieldId: string) => void;
39
- readonly moveField: (fieldId: string, targetIndex: number) => void;
40
- readonly updateField: (fieldId: string, updater: (field: FormField) => FormField) => void;
56
+ readonly addField: (type: QuestionType, pageId?: string) => BuilderActionResult;
57
+ readonly removeField: (fieldId: string) => BuilderActionResult;
58
+ readonly moveField: (fieldId: string, targetIndex: number) => BuilderActionResult;
59
+ readonly updateField: (fieldId: string, updater: (field: FormField) => FormField) => BuilderActionResult;
60
+ readonly changeFieldType: (fieldId: string, type: QuestionType) => BuilderActionResult;
41
61
  readonly addOption: (fieldId: string) => BuilderActionResult;
42
- readonly removeOption: (fieldId: string, optionId: string) => void;
43
- readonly moveOption: (fieldId: string, optionId: string, targetIndex: number) => void;
44
- readonly addPage: (questionId?: string) => void;
45
- readonly removePage: (pageId: string) => void;
46
- readonly setLocaleTranslation: (locale: string, target: "form" | string, property: string, text: string) => void;
62
+ readonly updateOption: (fieldId: string, optionId: string, updater: (option: ChoiceOption) => ChoiceOption) => BuilderActionResult;
63
+ readonly removeOption: (fieldId: string, optionId: string) => BuilderActionResult;
64
+ readonly moveOption: (fieldId: string, optionId: string, targetIndex: number) => BuilderActionResult;
65
+ readonly addPage: (questionId?: string) => BuilderActionResult;
66
+ readonly updatePage: (pageId: string, updater: (page: FormPage) => FormPage) => BuilderActionResult;
67
+ readonly removePage: (pageId: string) => BuilderActionResult;
68
+ readonly movePage: (pageId: string, targetIndex: number) => BuilderActionResult;
69
+ readonly assignFieldToPage: (fieldId: string, pageId: string | null) => BuilderActionResult;
70
+ readonly setDisplayCondition: (fieldId: string, condition?: DisplayCondition) => BuilderActionResult;
71
+ readonly setSourceText: (target: BuilderTextTarget, property: string, text: string) => BuilderActionResult;
72
+ readonly setLocaleTranslation: (locale: string, target: BuilderTextTarget, property: string, text: string, options?: {
73
+ readonly metadata?: Readonly<Record<string, JsonValue>>;
74
+ }) => BuilderActionResult;
75
+ readonly addLocale: (locale: string) => BuilderActionResult;
76
+ readonly setDefaultLocale: (locale: string) => BuilderActionResult;
47
77
  readonly validationIssues: readonly SchemaIssue[];
48
78
  }
49
- declare function useFormBuilder({ schema, onChange, policy, idFactory }: FormBuilderOptions): FormBuilderResult;
79
+ declare function useFormBuilder({ schema, onChange, policy, idFactory, factories }: FormBuilderOptions): FormBuilderResult;
50
80
 
51
- interface FormBuilderProps {
52
- readonly schema: FormSchema;
53
- readonly onChange: (newSchema: FormSchema) => void;
54
- readonly locale?: string;
55
- readonly translator?: TranslationAdapter;
56
- readonly translationAdapter?: AsyncTranslationAdapter;
57
- readonly policy?: BuilderPolicy;
58
- readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
81
+ interface BuilderActionContext {
82
+ readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "assignFieldToPage" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation";
83
+ readonly targetId?: string;
84
+ readonly params?: Record<string, unknown>;
85
+ }
86
+ interface ManualTranslationContext {
87
+ readonly locale: string;
88
+ readonly kind: "form" | "page" | "field" | "option";
89
+ readonly nodeId: string;
90
+ readonly property: "title" | "description" | "label" | "completionMessage";
91
+ readonly sourceText: string;
92
+ readonly translatedText: string;
93
+ readonly existingTranslationMetadata?: Readonly<Record<string, JsonValue>>;
59
94
  }
60
- declare function FormBuilder({ schema, onChange, locale, translator, translationAdapter, policy, idFactory }: FormBuilderProps): react.JSX.Element;
61
-
62
95
  type SubmitResult = {
63
96
  readonly status: "invalid";
64
97
  readonly issues: readonly ValidationError[];
@@ -75,6 +108,11 @@ interface FormRendererSlots {
75
108
  readonly title: string;
76
109
  readonly description?: string;
77
110
  }) => ReactNode;
111
+ readonly renderPageHeader?: (props: {
112
+ readonly page: FormPage;
113
+ readonly pageIndex: number;
114
+ readonly totalPages: number;
115
+ }) => ReactNode;
78
116
  readonly renderField?: (props: {
79
117
  readonly question: FormField;
80
118
  readonly value: unknown;
@@ -99,9 +137,32 @@ interface FormRendererSlots {
99
137
  readonly renderCompletion?: (props: {
100
138
  readonly message: string;
101
139
  }) => ReactNode;
140
+ readonly renderSubmitError?: (props: {
141
+ readonly error: Error;
142
+ readonly onRetry?: () => void;
143
+ }) => ReactNode;
102
144
  }
103
145
  type BeforeSubmit = (values: Readonly<Record<string, unknown>>) => "continue" | "cancel" | Promise<"continue" | "cancel">;
104
146
 
147
+ declare function resolveInitialFieldType(defaultType?: QuestionType, allowedTypes?: readonly QuestionType[]): QuestionType | null;
148
+ interface FormBuilderProps {
149
+ readonly schema: FormSchema;
150
+ readonly onChange: (newSchema: FormSchema) => void;
151
+ readonly locale?: string;
152
+ readonly translator?: TranslationAdapter;
153
+ readonly translationAdapter?: AsyncTranslationAdapter;
154
+ readonly translationOptions?: PopulateTranslationOptions;
155
+ readonly onTranslationReport?: (report: TranslationReport) => void;
156
+ readonly policy?: FormPolicy;
157
+ readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
158
+ readonly factories?: BuilderFactories;
159
+ readonly className?: string;
160
+ readonly defaultFieldType?: QuestionType;
161
+ readonly onActionError?: (error: BuilderActionError, context: BuilderActionContext) => void;
162
+ readonly createManualTranslationMetadata?: (context: ManualTranslationContext) => Readonly<Record<string, JsonValue>> | undefined;
163
+ }
164
+ declare function FormBuilder({ schema, onChange, locale, translator, translationAdapter, translationOptions, onTranslationReport, policy, idFactory, factories, className, defaultFieldType, onActionError, createManualTranslationMetadata }: FormBuilderProps): react.JSX.Element;
165
+
105
166
  type SubmitStatus = "idle" | "submitting" | "success" | "error";
106
167
  interface FormContextValue {
107
168
  readonly schema: FormSchema;
@@ -172,4 +233,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
172
233
  type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
173
234
  declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
174
235
 
175
- export { type BeforeSubmit, type BuilderActionError, type BuilderActionResult, type BuilderPolicy, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type StandaloneFormRendererProps, type SubmitResult, type SubmitStatus, useField, useForm, useFormBuilder };
236
+ export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderFactories, type BuilderIdKind, type BuilderPolicy, type BuilderTextTarget, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmitResult, type SubmitStatus, resolveInitialFieldType, useField, useForm, useFormBuilder };
package/dist/index.d.ts CHANGED
@@ -1,64 +1,97 @@
1
1
  import * as react from 'react';
2
2
  import { ReactNode, ComponentType } from 'react';
3
- import { FieldType, FormSchema, FormField, SchemaIssue, TranslationAdapter, AsyncTranslationAdapter, ValidationError, FormValue, ValidationIssue, FormValues, AnswerValidationResult } from '@form-engine-ts/core';
3
+ import { QuestionType, FormField, ChoiceOption, FormPage, FormPolicy, FormSchema, DisplayCondition, JsonValue, SchemaIssue, ValidationError, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, TranslationReport, FormValue, ValidationIssue, FormValues, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
4
4
 
5
- interface BuilderPolicy {
6
- readonly allowedFieldTypes?: readonly FieldType[];
7
- readonly maxFields?: number;
8
- readonly maxOptionsPerField?: number;
9
- readonly maxTextLength?: number;
10
- readonly requiredLocales?: readonly string[];
5
+ /** @deprecated Import FormPolicy from @form-engine-ts/core instead. */
6
+ type BuilderPolicy = FormPolicy;
7
+ type BuilderIdKind = "field" | "option" | "page";
8
+ interface BuilderFactories {
9
+ readonly createField?: (type: QuestionType, id: string) => FormField;
10
+ readonly createOption?: (field: FormField, id: string) => ChoiceOption;
11
+ readonly createPage?: (id: string, questionIds: string[]) => FormPage;
12
+ }
13
+ interface BuilderTextTarget {
14
+ readonly kind: "form" | "page" | "field" | "option";
15
+ readonly id?: string;
11
16
  }
12
17
  interface FormBuilderOptions {
13
18
  readonly schema: FormSchema;
14
19
  readonly onChange: (schema: FormSchema) => void;
15
- readonly policy?: BuilderPolicy;
16
- readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
20
+ readonly policy?: FormPolicy;
21
+ readonly idFactory?: (kind: BuilderIdKind, existingIds: ReadonlySet<string>) => string;
22
+ readonly factories?: BuilderFactories;
17
23
  }
18
24
  type BuilderActionError = {
25
+ readonly type: "invalid_id";
26
+ readonly kind: BuilderIdKind;
27
+ readonly id: string;
28
+ } | {
19
29
  readonly type: "max_fields_exceeded";
20
30
  readonly max: number;
21
31
  } | {
22
32
  readonly type: "max_options_exceeded";
23
33
  readonly max: number;
34
+ } | {
35
+ readonly type: "max_text_length_exceeded";
36
+ readonly max: number;
24
37
  } | {
25
38
  readonly type: "disallowed_field_type";
26
- readonly fieldType: FieldType;
39
+ readonly fieldType: QuestionType;
40
+ } | {
41
+ readonly type: "node_not_found";
42
+ readonly kind: BuilderTextTarget["kind"];
43
+ readonly id: string;
27
44
  } | {
28
45
  readonly type: "invalid_operation";
29
46
  readonly message: string;
30
47
  };
31
- interface BuilderActionResult {
32
- readonly success: boolean;
33
- readonly error?: BuilderActionError;
34
- }
48
+ type BuilderActionResult = {
49
+ readonly success: true;
50
+ } | {
51
+ readonly success: false;
52
+ readonly error: BuilderActionError;
53
+ };
35
54
  interface FormBuilderResult {
36
55
  readonly schema: FormSchema;
37
- readonly addField: (type: FieldType, pageId?: string) => BuilderActionResult;
38
- readonly removeField: (fieldId: string) => void;
39
- readonly moveField: (fieldId: string, targetIndex: number) => void;
40
- readonly updateField: (fieldId: string, updater: (field: FormField) => FormField) => void;
56
+ readonly addField: (type: QuestionType, pageId?: string) => BuilderActionResult;
57
+ readonly removeField: (fieldId: string) => BuilderActionResult;
58
+ readonly moveField: (fieldId: string, targetIndex: number) => BuilderActionResult;
59
+ readonly updateField: (fieldId: string, updater: (field: FormField) => FormField) => BuilderActionResult;
60
+ readonly changeFieldType: (fieldId: string, type: QuestionType) => BuilderActionResult;
41
61
  readonly addOption: (fieldId: string) => BuilderActionResult;
42
- readonly removeOption: (fieldId: string, optionId: string) => void;
43
- readonly moveOption: (fieldId: string, optionId: string, targetIndex: number) => void;
44
- readonly addPage: (questionId?: string) => void;
45
- readonly removePage: (pageId: string) => void;
46
- readonly setLocaleTranslation: (locale: string, target: "form" | string, property: string, text: string) => void;
62
+ readonly updateOption: (fieldId: string, optionId: string, updater: (option: ChoiceOption) => ChoiceOption) => BuilderActionResult;
63
+ readonly removeOption: (fieldId: string, optionId: string) => BuilderActionResult;
64
+ readonly moveOption: (fieldId: string, optionId: string, targetIndex: number) => BuilderActionResult;
65
+ readonly addPage: (questionId?: string) => BuilderActionResult;
66
+ readonly updatePage: (pageId: string, updater: (page: FormPage) => FormPage) => BuilderActionResult;
67
+ readonly removePage: (pageId: string) => BuilderActionResult;
68
+ readonly movePage: (pageId: string, targetIndex: number) => BuilderActionResult;
69
+ readonly assignFieldToPage: (fieldId: string, pageId: string | null) => BuilderActionResult;
70
+ readonly setDisplayCondition: (fieldId: string, condition?: DisplayCondition) => BuilderActionResult;
71
+ readonly setSourceText: (target: BuilderTextTarget, property: string, text: string) => BuilderActionResult;
72
+ readonly setLocaleTranslation: (locale: string, target: BuilderTextTarget, property: string, text: string, options?: {
73
+ readonly metadata?: Readonly<Record<string, JsonValue>>;
74
+ }) => BuilderActionResult;
75
+ readonly addLocale: (locale: string) => BuilderActionResult;
76
+ readonly setDefaultLocale: (locale: string) => BuilderActionResult;
47
77
  readonly validationIssues: readonly SchemaIssue[];
48
78
  }
49
- declare function useFormBuilder({ schema, onChange, policy, idFactory }: FormBuilderOptions): FormBuilderResult;
79
+ declare function useFormBuilder({ schema, onChange, policy, idFactory, factories }: FormBuilderOptions): FormBuilderResult;
50
80
 
51
- interface FormBuilderProps {
52
- readonly schema: FormSchema;
53
- readonly onChange: (newSchema: FormSchema) => void;
54
- readonly locale?: string;
55
- readonly translator?: TranslationAdapter;
56
- readonly translationAdapter?: AsyncTranslationAdapter;
57
- readonly policy?: BuilderPolicy;
58
- readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
81
+ interface BuilderActionContext {
82
+ readonly action: "addField" | "removeField" | "moveField" | "changeFieldType" | "updateField" | "addOption" | "removeOption" | "moveOption" | "updateOption" | "addPage" | "removePage" | "movePage" | "assignFieldToPage" | "setDisplayCondition" | "setSourceText" | "setLocaleTranslation";
83
+ readonly targetId?: string;
84
+ readonly params?: Record<string, unknown>;
85
+ }
86
+ interface ManualTranslationContext {
87
+ readonly locale: string;
88
+ readonly kind: "form" | "page" | "field" | "option";
89
+ readonly nodeId: string;
90
+ readonly property: "title" | "description" | "label" | "completionMessage";
91
+ readonly sourceText: string;
92
+ readonly translatedText: string;
93
+ readonly existingTranslationMetadata?: Readonly<Record<string, JsonValue>>;
59
94
  }
60
- declare function FormBuilder({ schema, onChange, locale, translator, translationAdapter, policy, idFactory }: FormBuilderProps): react.JSX.Element;
61
-
62
95
  type SubmitResult = {
63
96
  readonly status: "invalid";
64
97
  readonly issues: readonly ValidationError[];
@@ -75,6 +108,11 @@ interface FormRendererSlots {
75
108
  readonly title: string;
76
109
  readonly description?: string;
77
110
  }) => ReactNode;
111
+ readonly renderPageHeader?: (props: {
112
+ readonly page: FormPage;
113
+ readonly pageIndex: number;
114
+ readonly totalPages: number;
115
+ }) => ReactNode;
78
116
  readonly renderField?: (props: {
79
117
  readonly question: FormField;
80
118
  readonly value: unknown;
@@ -99,9 +137,32 @@ interface FormRendererSlots {
99
137
  readonly renderCompletion?: (props: {
100
138
  readonly message: string;
101
139
  }) => ReactNode;
140
+ readonly renderSubmitError?: (props: {
141
+ readonly error: Error;
142
+ readonly onRetry?: () => void;
143
+ }) => ReactNode;
102
144
  }
103
145
  type BeforeSubmit = (values: Readonly<Record<string, unknown>>) => "continue" | "cancel" | Promise<"continue" | "cancel">;
104
146
 
147
+ declare function resolveInitialFieldType(defaultType?: QuestionType, allowedTypes?: readonly QuestionType[]): QuestionType | null;
148
+ interface FormBuilderProps {
149
+ readonly schema: FormSchema;
150
+ readonly onChange: (newSchema: FormSchema) => void;
151
+ readonly locale?: string;
152
+ readonly translator?: TranslationAdapter;
153
+ readonly translationAdapter?: AsyncTranslationAdapter;
154
+ readonly translationOptions?: PopulateTranslationOptions;
155
+ readonly onTranslationReport?: (report: TranslationReport) => void;
156
+ readonly policy?: FormPolicy;
157
+ readonly idFactory?: (kind: "field" | "option" | "page", existingIds: ReadonlySet<string>) => string;
158
+ readonly factories?: BuilderFactories;
159
+ readonly className?: string;
160
+ readonly defaultFieldType?: QuestionType;
161
+ readonly onActionError?: (error: BuilderActionError, context: BuilderActionContext) => void;
162
+ readonly createManualTranslationMetadata?: (context: ManualTranslationContext) => Readonly<Record<string, JsonValue>> | undefined;
163
+ }
164
+ declare function FormBuilder({ schema, onChange, locale, translator, translationAdapter, translationOptions, onTranslationReport, policy, idFactory, factories, className, defaultFieldType, onActionError, createManualTranslationMetadata }: FormBuilderProps): react.JSX.Element;
165
+
105
166
  type SubmitStatus = "idle" | "submitting" | "success" | "error";
106
167
  interface FormContextValue {
107
168
  readonly schema: FormSchema;
@@ -172,4 +233,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
172
233
  type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
173
234
  declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
174
235
 
175
- export { type BeforeSubmit, type BuilderActionError, type BuilderActionResult, type BuilderPolicy, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type StandaloneFormRendererProps, type SubmitResult, type SubmitStatus, useField, useForm, useFormBuilder };
236
+ export { type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionResult, type BuilderFactories, type BuilderIdKind, type BuilderPolicy, type BuilderTextTarget, type FieldComponentProps, type FieldComponents, type FieldState, FormBuilder, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormContextValue, FormProvider, type FormProviderProps, FormRenderer, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type ManualTranslationContext, type StandaloneFormRendererProps, type SubmitResult, type SubmitStatus, resolveInitialFieldType, useField, useForm, useFormBuilder };