@form-engine-ts/core 1.1.0 → 2.1.0

package/dist/index.d.cts

@@ -1,6 +1,23 @@
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
+interface FormPolicy {
+    readonly allowedFieldTypes?: readonly FieldType[];
+    readonly maxFields?: number;
+    readonly maxOptionsPerField?: number;
+    readonly requiredLocales?: readonly string[];
+    readonly maxTextLength?: number;
+    readonly maxSchemaBytes?: number;
+}
 type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
 type ConditionValue = string | number | boolean;
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
+interface ExtensibleNode {
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /** Locale -> translated property -> metadata created for that translation. */
+    readonly translationMetadata?: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, JsonValue>>>>>>;
+}
 interface DisplayCondition {
     readonly questionId: string;
     readonly operator: ConditionOperator;
@@ -9,15 +26,16 @@ interface DisplayCondition {
 interface LocalizedText {
     readonly title?: string;
     readonly description?: string;
+    readonly completionMessage?: string;
 }
 type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
-interface FieldOption {
+interface FieldOption extends ExtensibleNode {
     readonly id: string;
     readonly label: string;
     readonly translations?: Readonly<Record<string, string>>;
 }
-interface BaseField {
+interface BaseField extends ExtensibleNode {
     readonly id: string;
     readonly type: FieldType;
     readonly title: string;
@@ -61,7 +79,7 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
-interface FormPage {
+interface FormPage extends ExtensibleNode {
     readonly id: string;
     readonly title?: string;
     readonly description?: string;
@@ -69,11 +87,12 @@ interface FormPage {
     readonly displayCondition?: DisplayCondition;
     readonly translations?: SchemaTranslations;
 }
-interface FormSchema {
+interface FormSchema extends ExtensibleNode {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
+    readonly completionMessage?: string;
     readonly submitLabelKey?: string;
     readonly defaultLocale?: string;
     readonly supportedLocales?: readonly string[];
@@ -102,6 +121,7 @@ interface ValidationIssue {
     readonly messageKey: string;
     readonly params: Readonly<Record<string, string | number>>;
 }
+type ValidationError = ValidationIssue;
 type AnswerValidationResult = {
     readonly valid: true;
     readonly issues: readonly [];
@@ -109,7 +129,7 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmission {
+interface FormSubmission extends ExtensibleNode {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
@@ -182,7 +202,13 @@ interface FormAnalytics {
 type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
-type FormResponse = FormSubmission;
+interface FormResponse extends ExtensibleNode {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly sourceLocale?: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly submittedAt: string;
+}
 interface CrossTabulationResult {
     readonly rowQuestionId: string;
     readonly colQuestionId: string;
@@ -206,9 +232,10 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
-declare function escapeCsvCell(value: string | number | null | undefined): string;
+declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
+    readonly neutralizeFormulas?: boolean;
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
@@ -233,6 +260,12 @@ interface WebhookDispatchResult {
 }
 declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig, fetchImpl?: typeof fetch): Promise<WebhookDispatchResult>;
 
+/**
+ * Changes only the type-specific shape of a field. Authoring content and extension
+ * data are deliberately retained so UI adapters cannot accidentally discard them.
+ */
+declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -243,18 +276,45 @@ interface SchemaStructureIssue {
 declare function validateSchemaStructure(schema: FormSchema): SchemaStructureIssue[];
 declare function sanitizeSchema(schema: FormSchema): FormSchema;
 
-declare function validateFormSchema(input: unknown): SchemaValidationResult;
+interface ValidateFormSchemaOptions {
+    readonly policy?: FormPolicy;
+}
+declare function validateFormSchema(input: unknown, options?: ValidateFormSchemaOptions): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
-interface CreateSubmissionOptions {
+interface CreateSubmissionOptions extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+interface TranslationSlot {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly nodeId: string;
+    readonly property: "title" | "description" | "label" | "completionMessage";
+    readonly locale: string;
+    readonly sourceText: string;
+    readonly existingText?: string;
+    readonly nodeMetadata?: Readonly<Record<string, JsonValue>>;
+    readonly existingTranslationMetadata?: Readonly<Record<string, JsonValue>>;
+    /** @deprecated Use nodeMetadata instead. */
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface PopulateTranslationOptions {
+    readonly overwrite?: "missing-only" | "all";
+    readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
+    readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+}
+interface TranslationReport {
+    readonly updatedSlots: readonly TranslationSlot[];
+    readonly skippedSlots: readonly TranslationSlot[];
+}
 declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
-declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter, options?: PopulateTranslationOptions): Promise<{
+    readonly schema: FormSchema;
+    readonly report: TranslationReport;
+}>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
@@ -266,4 +326,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -1,6 +1,23 @@
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
+interface FormPolicy {
+    readonly allowedFieldTypes?: readonly FieldType[];
+    readonly maxFields?: number;
+    readonly maxOptionsPerField?: number;
+    readonly requiredLocales?: readonly string[];
+    readonly maxTextLength?: number;
+    readonly maxSchemaBytes?: number;
+}
 type ConditionOperator = "equals" | "not_equals" | "contains" | "not_empty";
 type ConditionValue = string | number | boolean;
+type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
+interface ExtensibleNode {
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /** Locale -> translated property -> metadata created for that translation. */
+    readonly translationMetadata?: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, JsonValue>>>>>>;
+}
 interface DisplayCondition {
     readonly questionId: string;
     readonly operator: ConditionOperator;
@@ -9,15 +26,16 @@ interface DisplayCondition {
 interface LocalizedText {
     readonly title?: string;
     readonly description?: string;
+    readonly completionMessage?: string;
 }
 type SchemaTranslations = Readonly<Record<string, LocalizedText>>;
 type ValidationCode = "required" | "invalid_type" | "min_length" | "max_length" | "pattern" | "min" | "max" | "step" | "invalid_option" | "min_selections" | "max_selections" | "unknown_field";
-interface FieldOption {
+interface FieldOption extends ExtensibleNode {
     readonly id: string;
     readonly label: string;
     readonly translations?: Readonly<Record<string, string>>;
 }
-interface BaseField {
+interface BaseField extends ExtensibleNode {
     readonly id: string;
     readonly type: FieldType;
     readonly title: string;
@@ -61,7 +79,7 @@ interface CheckboxField extends BaseField {
     readonly type: "checkbox";
 }
 type FormField = TextField | NumberField | RatingField | SelectField | MultiSelectField | CheckboxField;
-interface FormPage {
+interface FormPage extends ExtensibleNode {
     readonly id: string;
     readonly title?: string;
     readonly description?: string;
@@ -69,11 +87,12 @@ interface FormPage {
     readonly displayCondition?: DisplayCondition;
     readonly translations?: SchemaTranslations;
 }
-interface FormSchema {
+interface FormSchema extends ExtensibleNode {
     readonly id: string;
     readonly version: number;
     readonly title: string;
     readonly description?: string;
+    readonly completionMessage?: string;
     readonly submitLabelKey?: string;
     readonly defaultLocale?: string;
     readonly supportedLocales?: readonly string[];
@@ -102,6 +121,7 @@ interface ValidationIssue {
     readonly messageKey: string;
     readonly params: Readonly<Record<string, string | number>>;
 }
+type ValidationError = ValidationIssue;
 type AnswerValidationResult = {
     readonly valid: true;
     readonly issues: readonly [];
@@ -109,7 +129,7 @@ type AnswerValidationResult = {
     readonly valid: false;
     readonly issues: readonly ValidationIssue[];
 };
-interface FormSubmission {
+interface FormSubmission extends ExtensibleNode {
     readonly id: string;
     readonly formId: string;
     readonly formVersion: number;
@@ -182,7 +202,13 @@ interface FormAnalytics {
 type Question = FormField;
 type QuestionType = FieldType;
 type ChoiceOption = FieldOption;
-type FormResponse = FormSubmission;
+interface FormResponse extends ExtensibleNode {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly sourceLocale?: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly submittedAt: string;
+}
 interface CrossTabulationResult {
     readonly rowQuestionId: string;
     readonly colQuestionId: string;
@@ -206,9 +232,10 @@ declare function calculateChoiceDistribution(responses: readonly FormSubmission[
 declare function calculateNumericSummary(responses: readonly FormSubmission[], questionId: string): NumericSummary;
 declare function calculateCrossTabulation(responses: readonly FormSubmission[], rowQuestionId: string, colQuestionId: string): CrossTabulationResult;
 declare function aggregateResponses(schema: FormSchema, submissions: readonly FormSubmission[]): FormAnalytics;
-declare function escapeCsvCell(value: string | number | null | undefined): string;
+declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
 interface CsvExportOptions {
     readonly withBom?: boolean;
+    readonly neutralizeFormulas?: boolean;
 }
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
@@ -233,6 +260,12 @@ interface WebhookDispatchResult {
 }
 declare function dispatchWebhook<T>(event: FormEvent<T>, config: WebhookConfig, fetchImpl?: typeof fetch): Promise<WebhookDispatchResult>;
 
+/**
+ * Changes only the type-specific shape of a field. Authoring content and extension
+ * data are deliberately retained so UI adapters cannot accidentally discard them.
+ */
+declare function transformFieldType(field: FormField, nextType: QuestionType): FormField;
+
 type SchemaStructureIssueType = "dangling_condition_reference" | "duplicate_question_id" | "duplicate_choice_id" | "self_condition_reference" | "cyclic_condition_reference";
 interface SchemaStructureIssue {
     readonly type: SchemaStructureIssueType;
@@ -243,18 +276,45 @@ interface SchemaStructureIssue {
 declare function validateSchemaStructure(schema: FormSchema): SchemaStructureIssue[];
 declare function sanitizeSchema(schema: FormSchema): FormSchema;
 
-declare function validateFormSchema(input: unknown): SchemaValidationResult;
+interface ValidateFormSchemaOptions {
+    readonly policy?: FormPolicy;
+}
+declare function validateFormSchema(input: unknown, options?: ValidateFormSchemaOptions): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
-interface CreateSubmissionOptions {
+interface CreateSubmissionOptions extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
 }
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 
+interface TranslationSlot {
+    readonly kind: "form" | "page" | "field" | "option";
+    readonly nodeId: string;
+    readonly property: "title" | "description" | "label" | "completionMessage";
+    readonly locale: string;
+    readonly sourceText: string;
+    readonly existingText?: string;
+    readonly nodeMetadata?: Readonly<Record<string, JsonValue>>;
+    readonly existingTranslationMetadata?: Readonly<Record<string, JsonValue>>;
+    /** @deprecated Use nodeMetadata instead. */
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface PopulateTranslationOptions {
+    readonly overwrite?: "missing-only" | "all";
+    readonly shouldOverwrite?: (slot: TranslationSlot) => boolean;
+    readonly createMetadata?: (slot: TranslationSlot, translatedText: string) => Readonly<Record<string, JsonValue>>;
+}
+interface TranslationReport {
+    readonly updatedSlots: readonly TranslationSlot[];
+    readonly skippedSlots: readonly TranslationSlot[];
+}
 declare function resolveLocalizedSchema(schema: FormSchema, targetLocale: string): FormSchema;
-declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter): Promise<FormSchema>;
+declare function populateSchemaTranslations(schema: FormSchema, targetLocales: readonly string[], adapter: AsyncTranslationAdapter, options?: PopulateTranslationOptions): Promise<{
+    readonly schema: FormSchema;
+    readonly report: TranslationReport;
+}>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
 declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
@@ -266,4 +326,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type ValidationCode, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvExportOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type JsonValue, type LocalizedText, type MultiSelectField, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PopulateTranslationOptions, type Question, type QuestionAggregate, type QuestionType, type RatingField, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, createSubmission, dispatchWebhook, escapeCsvCell, exportResponsesToCsv, isDisplayConditionSatisfied, isQuestionVisible, populateSchemaTranslations, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };