@form-engine-ts/react 4.3.1 → 4.3.2

package/README.md

@@ -39,6 +39,17 @@ export function ContactForm() {
 
 Use any compatible `TranslationAdapter` in place of the mock translator.
 
+## Choice field layout
+
+Radio and checkbox questions use the flat layout by default. Set `appearance.choiceField` to `"grouped"` to render
+them as bordered, accessible `<fieldset>` groups with `<legend>` titles:
+
+```tsx
+<FormRenderer appearance={{ choiceField: "grouped" }} />
+```
+
+`groupedChoiceFields={true}` remains available as a deprecated compatibility alias.
+
 Define `schema.pages` to enable Back/Next navigation, page validation, conditional page skipping, and an accessible
 progress indicator. Pass `autoSaveKey` to persist a versioned draft in `localStorage` after a 500ms debounce and restore it
 on the next mount:

package/dist/index.cjs

@@ -3276,8 +3276,11 @@ function describedBy(field, error, helpId, errorId) {
   );
   return ids.length === 0 ? void 0 : ids.join(" ");
 }
-function RequiredMark({ required }) {
-  return required ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "fe-required", "aria-hidden": "true", children: [
+function RequiredMark({
+  required,
+  className = "fe-required"
+}) {
+  return required ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className, "aria-hidden": "true", children: [
     " ",
     "*"
   ] }) : null;
@@ -3288,13 +3291,59 @@ function FieldMessage({ props }) {
     props.error === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { id: props.errorId, className: "fe-error", children: props.translate(props.error.messageKey, props.error.params) })
   ] });
 }
-function DefaultField(props) {
+function GroupedChoiceDescription({ props }) {
+  return props.field.description === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { id: props.helpId, className: "fe-field-description", children: props.field.description });
+}
+function GroupedChoiceError({ props }) {
+  return props.error === void 0 ? null : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { id: props.errorId, className: "fe-field-error", role: "alert", children: props.translate(props.error.messageKey, props.error.params) });
+}
+function DefaultField({
+  groupedChoiceFields,
+  ...props
+}) {
   const { field, value, setValue, inputId, error, translate } = props;
   const ariaProps = {
     "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
     "aria-invalid": error === void 0 ? void 0 : true
   };
   if (field.type === "checkbox") {
+    if (groupedChoiceFields) {
+      return (
+        // biome-ignore lint/a11y/useAriaPropsSupportedByRole: The grouped fieldset exposes the required state for the complete choice question.
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+          "fieldset",
+          {
+            className: "fe-choice-group fe-field--checkbox",
+            "data-field-id": field.id,
+            "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+            "aria-invalid": Boolean(error),
+            "aria-required": field.required,
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("legend", { className: "fe-choice-legend", children: [
+                field.title,
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RequiredMark, { required: field.required, className: "fe-required-badge" })
+              ] }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(GroupedChoiceDescription, { props }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "fe-choice-options", children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("label", { className: "fe-choice-option", htmlFor: inputId, children: [
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+                  "input",
+                  {
+                    id: inputId,
+                    name: field.id,
+                    type: "checkbox",
+                    checked: value === true,
+                    "aria-label": field.title,
+                    onChange: (event) => setValue(event.currentTarget.checked)
+                  }
+                ),
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: field.title })
+              ] }) }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(GroupedChoiceError, { props })
+            ]
+          }
+        )
+      );
+    }
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-field fe-field--checkbox", "data-field-id": field.id, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("label", { className: "fe-check-label", htmlFor: inputId, children: [
         /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
@@ -3318,6 +3367,85 @@ function DefaultField(props) {
   }
   if (field.type === "radio" || field.type === "multi-select") {
     const selected = Array.isArray(value) ? value : [];
+    if (field.type === "radio" && groupedChoiceFields) {
+      return (
+        // biome-ignore lint/a11y/useAriaPropsSupportedByRole: The grouped fieldset exposes the required state for the complete choice question.
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+          "fieldset",
+          {
+            className: "fe-choice-group fe-field--radio",
+            "data-field-id": field.id,
+            "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+            "aria-invalid": Boolean(error),
+            "aria-required": field.required,
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("legend", { className: "fe-choice-legend", children: [
+                field.title,
+                /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RequiredMark, { required: field.required, className: "fe-required-badge" })
+              ] }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(GroupedChoiceDescription, { props }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "fe-choice-options", children: field.options.map((option, index) => {
+                const optionId = `${inputId}-${index}`;
+                const checked = value === option.id;
+                return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("label", { className: "fe-choice-option", htmlFor: optionId, children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+                    "input",
+                    {
+                      id: optionId,
+                      name: field.id,
+                      type: "radio",
+                      value: option.id,
+                      checked,
+                      onKeyDown: (event) => {
+                        if (event.key !== "ArrowDown" && event.key !== "ArrowRight" && event.key !== "ArrowUp" && event.key !== "ArrowLeft")
+                          return;
+                        event.preventDefault();
+                        const offset = event.key === "ArrowDown" || event.key === "ArrowRight" ? 1 : -1;
+                        const nextIndex = (index + offset + field.options.length) % field.options.length;
+                        const nextOption = field.options[nextIndex];
+                        if (nextOption === void 0) return;
+                        setValue(nextOption.id);
+                        document.getElementById(`${inputId}-${nextIndex}`)?.focus();
+                      },
+                      onChange: () => setValue(option.id)
+                    }
+                  ),
+                  /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: option.label })
+                ] }, option.id);
+              }) }),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(GroupedChoiceError, { props })
+            ]
+          }
+        )
+      );
+    }
+    if (field.type === "radio") {
+      return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-field fe-field--radio", "data-field-id": field.id, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "fe-label", children: [
+          field.title,
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RequiredMark, { required: field.required })
+        ] }),
+        field.options.map((option, index) => {
+          const optionId = `${inputId}-${index}`;
+          return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("label", { className: "fe-check-label", htmlFor: optionId, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+              "input",
+              {
+                ...ariaProps,
+                id: optionId,
+                name: field.id,
+                type: "radio",
+                value: option.id,
+                checked: value === option.id,
+                onChange: () => setValue(option.id)
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: option.label })
+          ] }, option.id);
+        }),
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(FieldMessage, { props })
+      ] });
+    }
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("fieldset", { className: `fe-field fe-field--${field.type}`, "data-field-id": field.id, ...ariaProps, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("legend", { className: "fe-label", children: [
         field.title,
@@ -3567,6 +3695,8 @@ function ContextFormRenderer({
   beforeSubmit,
   onDraftSave,
   successRenderMode = "append",
+  appearance,
+  groupedChoiceFields = false,
   submissionConfirmation,
   submissionConfirmationRenderMode,
   showHiddenFieldsInSummary = false,
@@ -3579,6 +3709,7 @@ function ContextFormRenderer({
   slots = {}
 }) {
   const form = useForm();
+  const isGroupedMode = appearance?.choiceField === "grouped" || groupedChoiceFields;
   const prefix = (0, import_react5.useId)().replace(/:/g, "");
   const formRef = (0, import_react5.useRef)(null);
   const loadedDraftKey = (0, import_react5.useRef)(null);
@@ -4085,7 +4216,7 @@ function ContextFormRenderer({
                 }) }, field.id);
               }
               const Component = components[field.type];
-              return Component === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DefaultField, { ...props }, field.id) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Component, { ...props }, field.id);
+              return Component === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(DefaultField, { ...props, groupedChoiceFields: isGroupedMode }, field.id) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(Component, { ...props }, field.id);
             });
             const fieldClassName = `fe-fields${fieldsClassName === void 0 ? "" : ` ${fieldsClassName}`}`;
             return slots.renderFields?.({ children: fieldChildren, className: fieldClassName }) ?? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: fieldClassName, children: fieldChildren });

package/dist/index.d.cts

@@ -477,6 +477,15 @@ type SubmissionGuardResult = {
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
 type FormSuccessRenderMode = "append" | "replace";
+type ChoiceFieldLayoutMode = "default" | "grouped";
+interface FormRendererAppearance {
+    /**
+     * Layout preset for radio and checkbox questions.
+     * - "default": keep the flat question layout.
+     * - "grouped": render a bordered fieldset and legend.
+     */
+    readonly choiceField?: ChoiceFieldLayoutMode;
+}
 type SubmissionConfirmationRenderMode = "inline" | "replace" | "dialog";
 interface SubmissionConfirmationOptions {
     readonly enabled?: boolean;
@@ -671,6 +680,9 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    readonly appearance?: FormRendererAppearance;
+    /** @deprecated Use appearance.choiceField="grouped" instead. */
+    readonly groupedChoiceFields?: boolean;
     /**
      * Controls where the completion message is rendered after a successful submission.
      * Defaults to "append" for backwards compatibility.
@@ -704,4 +716,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.d.ts

@@ -477,6 +477,15 @@ type SubmissionGuardResult = {
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
 type FormSuccessRenderMode = "append" | "replace";
+type ChoiceFieldLayoutMode = "default" | "grouped";
+interface FormRendererAppearance {
+    /**
+     * Layout preset for radio and checkbox questions.
+     * - "default": keep the flat question layout.
+     * - "grouped": render a bordered fieldset and legend.
+     */
+    readonly choiceField?: ChoiceFieldLayoutMode;
+}
 type SubmissionConfirmationRenderMode = "inline" | "replace" | "dialog";
 interface SubmissionConfirmationOptions {
     readonly enabled?: boolean;
@@ -671,6 +680,9 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    readonly appearance?: FormRendererAppearance;
+    /** @deprecated Use appearance.choiceField="grouped" instead. */
+    readonly groupedChoiceFields?: boolean;
     /**
      * Controls where the completion message is rendered after a successful submission.
      * Defaults to "append" for backwards compatibility.
@@ -704,4 +716,4 @@ interface StandaloneFormRendererProps extends FormRendererPresentationProps {
 type FormRendererProps = FormRendererPresentationProps | StandaloneFormRendererProps;
 declare function FormRenderer(props: FormRendererProps): react.JSX.Element;
 
-export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };
+export { BUILDER_TRANSLATION_ALIASES, BUILDER_TRANSLATION_KEYS, type BeforeSubmit, type BuilderActionContext, type BuilderActionError, type BuilderActionIconType, type BuilderActionResult, type BuilderButtonProps, type BuilderCheckboxProps, type BuilderErrorMessageProps, type BuilderFactories, type BuilderFieldEditorSlotProps, type BuilderFieldsetProps, type BuilderIconButtonProps, type BuilderIdKind, type BuilderLocalizationSlotProps, type BuilderOptionEditorSlotProps, type BuilderPagesSlotProps, type BuilderPolicy, type BuilderSectionProps, type BuilderSelectOption, type BuilderSelectProps, type BuilderSlotActions, type BuilderTextAreaProps, type BuilderTextInputProps, type BuilderTextTarget, type BuilderToolbarSlotProps, type BuilderTranslationActionsSlotProps, type BuilderTranslationKey, type ChoiceFieldLayoutMode, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldPropertyControlMode, type FieldState, type FieldTypeSelectOptionsConfig, type FieldTypeSelectOptionsContext, type FieldTypeSelectOptionsSorter, type FieldTypeSelectOptionsTransformer, type FieldTypeSelectSlotProps, FormBuilder, type FormBuilderActions, type FormBuilderComponents, type FormBuilderFeatures, type FormBuilderOptions, type FormBuilderProps, type FormBuilderResult, type FormBuilderSectionName, type FormBuilderSlots, type FormCompletionSlotProps, type FormContextValue, type FormFieldsSlotProps, FormProvider, type FormProviderProps, FormRenderer, type FormRendererAppearance, type FormRendererMessages, type FormRendererPresentationProps, type FormRendererProps, type FormRendererSlots, type FormServerErrorPayload, FormSubmissionError, type FormSubmitHandler, type FormSubmitState, type FormSubmitStatus, type FormSubmittedAnswerItem, type FormSuccessRenderMode, type IconButtonProps, type InputComponentProps, type LocalizationSummaryContext, type ManualTranslationContext, type ManualTranslationTarget, type RenderSubmitButtonProps, type SelectComponentProps, type StandaloneFormRendererProps, type SubmissionAttempt, type SubmissionAttemptStore, type SubmissionConfirmationOptions, type SubmissionConfirmationRenderMode, type SubmissionConfirmationSlotProps, type SubmissionGuard, type SubmissionGuardResult, type SubmissionProtectionProps, type SubmissionReceipt, type SubmissionReceiptQuery, type SubmissionReceiptStore, type SubmitContext, type SubmitResponse, type SubmitResult, type SubmitStatus, type UseSubmissionReceiptsResult, createLocalStorageSubmissionAttemptStore, createLocalStorageSubmissionReceiptStore, isTranslationUnresolved, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.js

@@ -3259,8 +3259,11 @@ function describedBy(field, error, helpId, errorId) {
   );
   return ids.length === 0 ? void 0 : ids.join(" ");
 }
-function RequiredMark({ required }) {
-  return required ? /* @__PURE__ */ jsxs2("span", { className: "fe-required", "aria-hidden": "true", children: [
+function RequiredMark({
+  required,
+  className = "fe-required"
+}) {
+  return required ? /* @__PURE__ */ jsxs2("span", { className, "aria-hidden": "true", children: [
     " ",
     "*"
   ] }) : null;
@@ -3271,13 +3274,59 @@ function FieldMessage({ props }) {
     props.error === void 0 ? null : /* @__PURE__ */ jsx3("div", { id: props.errorId, className: "fe-error", children: props.translate(props.error.messageKey, props.error.params) })
   ] });
 }
-function DefaultField(props) {
+function GroupedChoiceDescription({ props }) {
+  return props.field.description === void 0 ? null : /* @__PURE__ */ jsx3("div", { id: props.helpId, className: "fe-field-description", children: props.field.description });
+}
+function GroupedChoiceError({ props }) {
+  return props.error === void 0 ? null : /* @__PURE__ */ jsx3("div", { id: props.errorId, className: "fe-field-error", role: "alert", children: props.translate(props.error.messageKey, props.error.params) });
+}
+function DefaultField({
+  groupedChoiceFields,
+  ...props
+}) {
   const { field, value, setValue, inputId, error, translate } = props;
   const ariaProps = {
     "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
     "aria-invalid": error === void 0 ? void 0 : true
   };
   if (field.type === "checkbox") {
+    if (groupedChoiceFields) {
+      return (
+        // biome-ignore lint/a11y/useAriaPropsSupportedByRole: The grouped fieldset exposes the required state for the complete choice question.
+        /* @__PURE__ */ jsxs2(
+          "fieldset",
+          {
+            className: "fe-choice-group fe-field--checkbox",
+            "data-field-id": field.id,
+            "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+            "aria-invalid": Boolean(error),
+            "aria-required": field.required,
+            children: [
+              /* @__PURE__ */ jsxs2("legend", { className: "fe-choice-legend", children: [
+                field.title,
+                /* @__PURE__ */ jsx3(RequiredMark, { required: field.required, className: "fe-required-badge" })
+              ] }),
+              /* @__PURE__ */ jsx3(GroupedChoiceDescription, { props }),
+              /* @__PURE__ */ jsx3("div", { className: "fe-choice-options", children: /* @__PURE__ */ jsxs2("label", { className: "fe-choice-option", htmlFor: inputId, children: [
+                /* @__PURE__ */ jsx3(
+                  "input",
+                  {
+                    id: inputId,
+                    name: field.id,
+                    type: "checkbox",
+                    checked: value === true,
+                    "aria-label": field.title,
+                    onChange: (event) => setValue(event.currentTarget.checked)
+                  }
+                ),
+                /* @__PURE__ */ jsx3("span", { children: field.title })
+              ] }) }),
+              /* @__PURE__ */ jsx3(GroupedChoiceError, { props })
+            ]
+          }
+        )
+      );
+    }
     return /* @__PURE__ */ jsxs2("div", { className: "fe-field fe-field--checkbox", "data-field-id": field.id, children: [
       /* @__PURE__ */ jsxs2("label", { className: "fe-check-label", htmlFor: inputId, children: [
         /* @__PURE__ */ jsx3(
@@ -3301,6 +3350,85 @@ function DefaultField(props) {
   }
   if (field.type === "radio" || field.type === "multi-select") {
     const selected = Array.isArray(value) ? value : [];
+    if (field.type === "radio" && groupedChoiceFields) {
+      return (
+        // biome-ignore lint/a11y/useAriaPropsSupportedByRole: The grouped fieldset exposes the required state for the complete choice question.
+        /* @__PURE__ */ jsxs2(
+          "fieldset",
+          {
+            className: "fe-choice-group fe-field--radio",
+            "data-field-id": field.id,
+            "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+            "aria-invalid": Boolean(error),
+            "aria-required": field.required,
+            children: [
+              /* @__PURE__ */ jsxs2("legend", { className: "fe-choice-legend", children: [
+                field.title,
+                /* @__PURE__ */ jsx3(RequiredMark, { required: field.required, className: "fe-required-badge" })
+              ] }),
+              /* @__PURE__ */ jsx3(GroupedChoiceDescription, { props }),
+              /* @__PURE__ */ jsx3("div", { className: "fe-choice-options", children: field.options.map((option, index) => {
+                const optionId = `${inputId}-${index}`;
+                const checked = value === option.id;
+                return /* @__PURE__ */ jsxs2("label", { className: "fe-choice-option", htmlFor: optionId, children: [
+                  /* @__PURE__ */ jsx3(
+                    "input",
+                    {
+                      id: optionId,
+                      name: field.id,
+                      type: "radio",
+                      value: option.id,
+                      checked,
+                      onKeyDown: (event) => {
+                        if (event.key !== "ArrowDown" && event.key !== "ArrowRight" && event.key !== "ArrowUp" && event.key !== "ArrowLeft")
+                          return;
+                        event.preventDefault();
+                        const offset = event.key === "ArrowDown" || event.key === "ArrowRight" ? 1 : -1;
+                        const nextIndex = (index + offset + field.options.length) % field.options.length;
+                        const nextOption = field.options[nextIndex];
+                        if (nextOption === void 0) return;
+                        setValue(nextOption.id);
+                        document.getElementById(`${inputId}-${nextIndex}`)?.focus();
+                      },
+                      onChange: () => setValue(option.id)
+                    }
+                  ),
+                  /* @__PURE__ */ jsx3("span", { children: option.label })
+                ] }, option.id);
+              }) }),
+              /* @__PURE__ */ jsx3(GroupedChoiceError, { props })
+            ]
+          }
+        )
+      );
+    }
+    if (field.type === "radio") {
+      return /* @__PURE__ */ jsxs2("div", { className: "fe-field fe-field--radio", "data-field-id": field.id, children: [
+        /* @__PURE__ */ jsxs2("div", { className: "fe-label", children: [
+          field.title,
+          /* @__PURE__ */ jsx3(RequiredMark, { required: field.required })
+        ] }),
+        field.options.map((option, index) => {
+          const optionId = `${inputId}-${index}`;
+          return /* @__PURE__ */ jsxs2("label", { className: "fe-check-label", htmlFor: optionId, children: [
+            /* @__PURE__ */ jsx3(
+              "input",
+              {
+                ...ariaProps,
+                id: optionId,
+                name: field.id,
+                type: "radio",
+                value: option.id,
+                checked: value === option.id,
+                onChange: () => setValue(option.id)
+              }
+            ),
+            /* @__PURE__ */ jsx3("span", { children: option.label })
+          ] }, option.id);
+        }),
+        /* @__PURE__ */ jsx3(FieldMessage, { props })
+      ] });
+    }
     return /* @__PURE__ */ jsxs2("fieldset", { className: `fe-field fe-field--${field.type}`, "data-field-id": field.id, ...ariaProps, children: [
       /* @__PURE__ */ jsxs2("legend", { className: "fe-label", children: [
         field.title,
@@ -3550,6 +3678,8 @@ function ContextFormRenderer({
   beforeSubmit,
   onDraftSave,
   successRenderMode = "append",
+  appearance,
+  groupedChoiceFields = false,
   submissionConfirmation,
   submissionConfirmationRenderMode,
   showHiddenFieldsInSummary = false,
@@ -3562,6 +3692,7 @@ function ContextFormRenderer({
   slots = {}
 }) {
   const form = useForm();
+  const isGroupedMode = appearance?.choiceField === "grouped" || groupedChoiceFields;
   const prefix = useId().replace(/:/g, "");
   const formRef = useRef2(null);
   const loadedDraftKey = useRef2(null);
@@ -4068,7 +4199,7 @@ function ContextFormRenderer({
                 }) }, field.id);
               }
               const Component = components[field.type];
-              return Component === void 0 ? /* @__PURE__ */ jsx3(DefaultField, { ...props }, field.id) : /* @__PURE__ */ jsx3(Component, { ...props }, field.id);
+              return Component === void 0 ? /* @__PURE__ */ jsx3(DefaultField, { ...props, groupedChoiceFields: isGroupedMode }, field.id) : /* @__PURE__ */ jsx3(Component, { ...props }, field.id);
             });
             const fieldClassName = `fe-fields${fieldsClassName === void 0 ? "" : ` ${fieldsClassName}`}`;
             return slots.renderFields?.({ children: fieldChildren, className: fieldClassName }) ?? /* @__PURE__ */ jsx3("div", { className: fieldClassName, children: fieldChildren });

package/dist/styles.css

@@ -123,6 +123,41 @@
 .fe-check-label input {
   margin-top: 0.22rem;
 }
+.fe-choice-group {
+  background-color: var(--fe-bg-color, #ffffff);
+  border: 1px solid var(--fe-border-color, #e2e8f0);
+  border-radius: var(--fe-radius, 8px);
+  box-sizing: border-box;
+  margin: 0 0 1.25rem;
+  padding: 1rem 1.25rem;
+}
+.fe-choice-legend {
+  color: var(--fe-text-color, #1a202c);
+  font-size: 0.95rem;
+  font-weight: 600;
+  padding: 0 0.5rem;
+}
+.fe-choice-options {
+  display: flex;
+  flex-direction: column;
+  gap: 0.625rem;
+  margin-top: 0.5rem;
+}
+.fe-choice-option {
+  align-items: center;
+  cursor: pointer;
+  display: flex;
+  gap: 0.5rem;
+}
+.fe-field-description {
+  color: #667085;
+  font-size: 0.875rem;
+}
+.fe-field-error {
+  color: #b42318;
+  font-size: 0.875rem;
+  font-weight: 600;
+}
 .fe-rating-options {
   display: flex;
   flex-wrap: wrap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/react",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "publishConfig": {
     "access": "public"
   },
@@ -42,8 +42,8 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "4.3.1",
-    "@form-engine-ts/privacy": "4.3.1"
+    "@form-engine-ts/core": "4.3.2",
+    "@form-engine-ts/privacy": "4.3.2"
   },
   "peerDependencies": {
     "react": ">=18.2 <20",