feat(ui): add validation for form fields (#1934)

Author: PetrBulanek

apps/agentstack-sdk-ts/src/client/a2a/extensions/common/form/schemas.ts

@@ -8,7 +8,7 @@ import z from 'zod';
 export const baseFieldSchema = z.object({
   id: z.string().nonempty(),
   label: z.string().nonempty(),
-  required: z.boolean(),
+  required: z.boolean().nullish(),
   col_span: z.int().min(1).max(4).nullish(),
 });
 
@@ -30,36 +30,27 @@ export const fileFieldSchema = baseFieldSchema.extend({
   accept: z.array(z.string()),
 });
 
+export const selectFieldOptionSchema = z.object({
+  id: z.string().nonempty(),
+  label: z.string().nonempty(),
+});
+
 export const singleSelectFieldSchema = baseFieldSchema.extend({
   type: z.literal('singleselect'),
-  options: z
-    .array(
-      z.object({
-        id: z.string().nonempty(),
-        label: z.string().nonempty(),
-      }),
-    )
-    .nonempty(),
+  options: z.array(selectFieldOptionSchema).nonempty(),
   default_value: z.string().nullish(),
 });
 
 export const multiSelectFieldSchema = baseFieldSchema.extend({
   type: z.literal('multiselect'),
-  options: z
-    .array(
-      z.object({
-        id: z.string().nonempty(),
-        label: z.string().nonempty(),
-      }),
-    )
-    .nonempty(),
+  options: z.array(selectFieldOptionSchema).nonempty(),
   default_value: z.array(z.string()).nullish(),
 });
 
 export const checkboxFieldSchema = baseFieldSchema.extend({
   type: z.literal('checkbox'),
   content: z.string(),
-  default_value: z.boolean(),
+  default_value: z.boolean().nullish(),
 });
 
 export const formFieldSchema = z.discriminatedUnion('type', [
@@ -119,11 +110,11 @@ export const formFieldValueSchema = z.discriminatedUnion('type', [
 ]);
 
 export const formRenderSchema = z.object({
+  fields: z.array(formFieldSchema).nonempty(),
   title: z.string().nullish(),
   description: z.string().nullish(),
   columns: z.int().min(1).max(4).nullish(),
   submit_label: z.string().nullish(),
-  fields: z.array(formFieldSchema).nonempty(),
 });
 
 export const formValuesSchema = z.record(z.string(), formFieldValueSchema);

apps/agentstack-sdk-ts/src/client/a2a/extensions/common/form/types.ts

@@ -19,6 +19,7 @@ import type {
   formValuesSchema,
   multiSelectFieldSchema,
   multiSelectFieldValueSchema,
+  selectFieldOptionSchema,
   singleSelectFieldSchema,
   singleSelectFieldValueSchema,
   textFieldSchema,
@@ -28,6 +29,7 @@ import type {
 export type TextField = z.infer<typeof textFieldSchema>;
 export type DateField = z.infer<typeof dateFieldSchema>;
 export type FileField = z.infer<typeof fileFieldSchema>;
+export type SelectFieldOption = z.infer<typeof selectFieldOptionSchema>;
 export type SingleSelectField = z.infer<typeof singleSelectFieldSchema>;
 export type MultiSelectField = z.infer<typeof multiSelectFieldSchema>;
 export type CheckboxField = z.infer<typeof checkboxFieldSchema>;

apps/agentstack-ui/src/components/FormRequirement/FormRequirement.tsx

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 © BeeAI a Series of LF Projects, LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { PropsWithChildren } from 'react';
+
+export function FormRequirement({ children }: PropsWithChildren) {
+  return <div className="cds--form-requirement">{children}</div>;
+}

apps/agentstack-ui/src/components/TextAreaAutoHeight/TextAreaAutoHeight.module.scss

@@ -68,6 +68,13 @@ $padding-inline: $spacing-05;
     border-radius: $border-radius;
   }
 
+  &[data-invalid] {
+    &::after,
+    > textarea {
+      padding-inline-end: $spacing-08;
+    }
+  }
+
   &.lg {
     --padding-top: #{rem(14px)};
     --padding-bottom: #{rem(14px)};

apps/agentstack-ui/src/components/TextAreaAutoHeight/TextAreaAutoHeight.tsx

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { WarningFilled } from '@carbon/icons-react';
 import clsx from 'clsx';
 import type { ChangeEvent, CSSProperties, TextareaHTMLAttributes } from 'react';
 import { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
@@ -15,10 +16,11 @@ type Props = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value'> & {
   maxRows?: number;
   resizable?: boolean;
   size?: 'lg';
+  invalid?: boolean;
 };
 
 export const TextAreaAutoHeight = forwardRef<HTMLTextAreaElement, Props>(function TextAreaAutoHeight(
-  { className, resizable, maxRows, size, onChange, ...rest },
+  { className, resizable, maxRows, size, invalid, onChange, ...rest },
   ref,
 ) {
   const [value, setValue] = useState(rest.defaultValue ?? '');
@@ -68,10 +70,18 @@ export const TextAreaAutoHeight = forwardRef<HTMLTextAreaElement, Props>(functio
       className={clsx(classes.root, className, sizeClassName, {
         [classes.resized]: Boolean(manualHeight),
       })}
+      data-invalid={invalid}
       data-replicated-value={value}
       style={maxRows ? ({ '--max-rows': `${maxRows}` } as CSSProperties) : undefined}
     >
-      <textarea ref={mergeRefs([ref, textareaRef])} {...rest} onChange={handleChange} />
+      <textarea
+        ref={mergeRefs([ref, textareaRef])}
+        {...rest}
+        className={clsx({ 'cds--text-input--invalid': invalid })}
+        onChange={handleChange}
+      />
+
+      {invalid && <WarningFilled className="cds--text-input__invalid-icon" />}
     </div>
   );
 

apps/agentstack-ui/src/modules/form/components/FormActionBar.tsx

@@ -13,12 +13,12 @@ import { useRunSettingsDialog } from '#modules/runs/settings/useRunSettingsDialo
 import classes from './FormActionBar.module.scss';
 
 interface Props {
-  showSubmitButton?: boolean;
   submitLabel: string;
+  showSubmit?: boolean;
   showRunSettings?: boolean;
 }
 
-export function FormActionBar({ showSubmitButton = true, submitLabel, showRunSettings }: Props) {
+export function FormActionBar({ submitLabel, showSubmit = true, showRunSettings }: Props) {
   const modelsDialog = useRunSettingsDialog({ blockOffset: 8 });
   const settingsDialog = useRunSettingsDialog({ blockOffset: 8 });
   const formRefs = useMergeRefs([modelsDialog.refs.setPositionReference, settingsDialog.refs.setPositionReference]);
@@ -32,7 +32,8 @@ export function FormActionBar({ showSubmitButton = true, submitLabel, showRunSet
           <RunModels dialog={modelsDialog} iconOnly={false} />
         </div>
       )}
-      {showSubmitButton && (
+
+      {showSubmit && (
         <div className={classes.buttons}>
           <Button type="submit" size="md">
             {submitLabel}

apps/agentstack-ui/src/modules/form/components/FormRenderer.tsx

@@ -37,14 +37,18 @@ export function FormRenderer({
 
   const defaultValues = getDefaultValues(fields);
 
-  const form = useForm<RunFormValues>({ defaultValues });
+  const form = useForm<RunFormValues>({
+    mode: 'onChange',
+    defaultValues,
+  });
+  const { handleSubmit } = form;
 
   const showHeading = showHeadingProp && isNotNull(heading);
   const showHeader = showHeading || Boolean(description);
 
   return (
     <FormProvider {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)}>
+      <form onSubmit={handleSubmit(onSubmit)}>
         <fieldset disabled={isDisabled} className={classes.root}>
           {showHeader && (
             <AgentRunHeader heading={showHeading ? heading : undefined}>
@@ -56,8 +60,8 @@ export function FormRenderer({
 
           <FormActionBar
             submitLabel={submit_label ?? 'Submit'}
+            showSubmit={!isDisabled}
             showRunSettings={showRunSettings}
-            showSubmitButton={!isDisabled}
           />
         </fieldset>
       </form>

apps/agentstack-ui/src/modules/form/components/fields/CheckboxField.tsx

@@ -7,20 +7,25 @@ import { Checkbox, FormGroup } from '@carbon/react';
 import type { CheckboxField } from 'agentstack-sdk';
 import { useFormContext } from 'react-hook-form';
 
+import { useFormFieldValidation } from '#modules/form/hooks/useFormFieldValidation.ts';
 import type { ValuesOfField } from '#modules/form/types.ts';
+import { getFieldName } from '#modules/form/utils.ts';
 
 interface Props {
   field: CheckboxField;
 }
 
 export function CheckboxField({ field }: Props) {
-  const { id, label, content, required } = field;
+  const { id, label, content } = field;
 
-  const { register } = useFormContext<ValuesOfField<CheckboxField>>();
+  const { register, formState } = useFormContext<ValuesOfField<CheckboxField>>();
+  const { rules, invalid, invalidText } = useFormFieldValidation({ field, formState });
+
+  const inputProps = register(getFieldName(field), rules);
 
   return (
     <FormGroup legendText={label}>
-      <Checkbox id={id} labelText={content} {...register(`${id}.value`, { required: Boolean(required) })} />
+      <Checkbox id={id} labelText={content} invalid={invalid} invalidText={invalidText} {...inputProps} />
     </FormGroup>
   );
 }

apps/agentstack-ui/src/modules/form/components/fields/DateField.tsx

@@ -7,7 +7,9 @@ import { DatePicker, DatePickerInput } from '@carbon/react';
 import type { DateField } from 'agentstack-sdk';
 import { Controller, useFormContext } from 'react-hook-form';
 
+import { useFormFieldValidation } from '#modules/form/hooks/useFormFieldValidation.ts';
 import type { ValuesOfField } from '#modules/form/types.ts';
+import { getFieldName } from '#modules/form/utils.ts';
 
 interface Props {
   field: DateField;
@@ -16,20 +18,29 @@ interface Props {
 export function DateField({ field }: Props) {
   const { id, label, placeholder } = field;
 
-  const { control } = useFormContext<ValuesOfField<DateField>>();
+  const { control, formState } = useFormContext<ValuesOfField<DateField>>();
+  const { rules, invalid, invalidText } = useFormFieldValidation({ field, formState });
 
   return (
     <Controller
-      name={`${id}.value`}
+      name={getFieldName(field)}
       control={control}
+      rules={rules}
       render={({ field: { value, onChange } }) => (
         <DatePicker
           datePickerType="single"
           value={value ?? undefined}
           onChange={(_, currentDateString) => onChange(currentDateString)}
           allowInput
+          invalid={invalid}
         >
-          <DatePickerInput id={id} size="lg" labelText={label} placeholder={placeholder ?? undefined} />
+          <DatePickerInput
+            id={id}
+            size="lg"
+            labelText={label}
+            placeholder={placeholder ?? undefined}
+            invalidText={invalidText}
+          />
         </DatePicker>
       )}
     />

apps/agentstack-ui/src/modules/form/components/fields/FileField.tsx

@@ -9,12 +9,15 @@ import type { FileField } from 'agentstack-sdk';
 import { useEffect } from 'react';
 import { useController, useFormContext } from 'react-hook-form';
 
+import { FormRequirement } from '#components/FormRequirement/FormRequirement.tsx';
+import { usePrevious } from '#hooks/usePrevious.ts';
 import { FileCard } from '#modules/files/components/FileCard.tsx';
 import { FileCardsList } from '#modules/files/components/FileCardsList.tsx';
 import { FileUploadProvider } from '#modules/files/contexts/FileUploadProvider.tsx';
 import { useFileUpload } from '#modules/files/contexts/index.ts';
+import { useFormFieldValidation } from '#modules/form/hooks/useFormFieldValidation.ts';
 import type { ValuesOfField } from '#modules/form/types.ts';
-import { convertFileToFileFieldValue } from '#modules/form/utils.ts';
+import { convertFileToFileFieldValue, getFieldName } from '#modules/form/utils.ts';
 import { isNotNull } from '#utils/helpers.ts';
 
 import classes from './FileField.module.scss';
@@ -32,29 +35,41 @@ export function FileField({ field }: Props) {
 }
 
 export function FileFieldComponent({ field }: Props) {
-  const { id, label } = field;
+  const { label } = field;
 
-  const { dropzone, isDisabled, files, removeFile } = useFileUpload();
-  const { control } = useFormContext<ValuesOfField<FileField>>();
+  const { dropzone, isDisabled, isPending, files, removeFile } = useFileUpload();
+  const { control, formState } = useFormContext<ValuesOfField<FileField>>();
+  const { rules, invalid: invalidState, invalidText } = useFormFieldValidation({ field, formState });
   const {
     field: { onChange },
-  } = useController({ control, name: `${id}.value` });
+  } = useController({ control, name: getFieldName(field), rules });
+
+  const invalid = invalidState && !isPending;
 
   const hasFiles = files.length > 0;
+  const filesKey = files
+    .map(({ uploadFile }) => (uploadFile ? uploadFile.id : null))
+    .filter(isNotNull)
+    .join('|');
+  const prevFilesKey = usePrevious(filesKey);
 
   useEffect(() => {
+    if (prevFilesKey === filesKey) {
+      return;
+    }
+
     const newValue = files.map(convertFileToFileFieldValue).filter(isNotNull);
 
     onChange(newValue);
-  }, [files, onChange]);
+  }, [filesKey, prevFilesKey, files, onChange]);
 
   if (!dropzone) {
     return null;
   }
 
   return (
     <FormGroup {...dropzone.getRootProps()} legendText={label}>
-      <input type="file" {...dropzone.getInputProps()} />
+      <input type="file" {...dropzone.getInputProps()} data-invalid={invalid} />
 
       {hasFiles ? (
         <FileCardsList className={classes.files}>
@@ -76,6 +91,8 @@ export function FileFieldComponent({ field }: Props) {
           Upload
         </Button>
       )}
+
+      {invalid && <FormRequirement>{invalidText}</FormRequirement>}
     </FormGroup>
   );
 }