@form-engine-ts/react 4.3.1 → 4.4.0

package/README.md

@@ -39,6 +39,28 @@ export function ContactForm() {
 
 Use any compatible `TranslationAdapter` in place of the mock translator.
 
+## Choice field layout
+
+Radio, checkbox, and multi-select 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" }} />
+```
+
+Use an object to configure each choice type independently. Unspecified types remain flat:
+
+```tsx
+<FormRenderer appearance={{ choiceField: { radio: "grouped", checkbox: "default" } }} />
+```
+
+Grouped wrappers can be replaced with `slots.renderChoiceGroup`; `slotProps.choiceGroup` accepts a class name and
+inline style for the default wrapper. The exported `ChoiceGroupSlotProps` includes the field, translated error, and
+option-list children. Group styling is controlled by the public `--fe-choice-group-*`, `--fe-choice-legend-*`, and
+`--fe-choice-options-gap` CSS custom properties.
+
+`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

@@ -29,6 +29,7 @@ __export(index_exports, {
   createLocalStorageSubmissionAttemptStore: () => createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore: () => createLocalStorageSubmissionReceiptStore,
   isTranslationUnresolved: () => isTranslationUnresolved,
+  resolveChoiceFieldLayout: () => resolveChoiceFieldLayout,
   resolveFieldEditorControls: () => resolveFieldEditorControls,
   resolveFieldTypeSelectOptions: () => resolveFieldTypeSelectOptions,
   resolveInitialFieldType: () => resolveInitialFieldType,
@@ -3270,14 +3271,25 @@ function useSubmissionReceipts(store, queries) {
 var import_core4 = require("@form-engine-ts/core");
 var import_react5 = require("react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
+var isChoiceFieldType = (type) => type === "radio" || type === "checkbox" || type === "multi-select" || type === "select";
+function resolveChoiceFieldLayout(type, appearance, groupedChoiceFieldsLegacy = false) {
+  if (groupedChoiceFieldsLegacy) return "grouped";
+  const config = appearance?.choiceField;
+  if (config === void 0) return "default";
+  if (typeof config === "string") return config;
+  return config[type] ?? "default";
+}
 function describedBy(field, error, helpId, errorId) {
   const ids = [field.description === void 0 ? void 0 : helpId, error === void 0 ? void 0 : errorId].filter(
     Boolean
   );
   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 +3300,106 @@ 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 ChoiceGroupFrame({
+  props,
+  children,
+  className,
+  slotProps,
+  renderChoiceGroup,
+  disabled,
+  readOnly
+}) {
+  const { field, error, translate } = props;
+  const groupError = error === void 0 ? void 0 : { ...error, message: translate(error.messageKey, error.params) };
+  const groupProps = {
+    field,
+    title: field.title,
+    ...field.description === void 0 ? {} : { description: field.description },
+    ...field.required === void 0 ? {} : { required: field.required },
+    ...groupError === void 0 ? {} : { error: groupError },
+    ...disabled === void 0 ? {} : { disabled },
+    ...readOnly === void 0 ? {} : { readOnly },
+    children,
+    className
+  };
+  if (renderChoiceGroup !== void 0) return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_jsx_runtime3.Fragment, { children: renderChoiceGroup(groupProps) });
+  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,
+        "data-field-id": field.id,
+        disabled,
+        "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+        "aria-invalid": Boolean(error),
+        "aria-required": field.required,
+        style: slotProps?.style,
+        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 }),
+          children,
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(GroupedChoiceError, { props })
+        ]
+      }
+    )
+  );
+}
+function DefaultField({
+  groupedChoiceFields,
+  appearance,
+  choiceGroupSlotProps,
+  renderChoiceGroup,
+  disabled,
+  readOnly,
+  ...props
+}) {
   const { field, value, setValue, inputId, error, translate } = props;
+  const isGroupedChoiceField = isChoiceFieldType(field.type) && resolveChoiceFieldLayout(field.type, appearance, groupedChoiceFields) === "grouped";
+  const choiceGroupClassName = ["fe-choice-group", `fe-field--${field.type}`, choiceGroupSlotProps?.className].filter((item) => item !== void 0 && item.length > 0).join(" ");
   const ariaProps = {
     "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
     "aria-invalid": error === void 0 ? void 0 : true
   };
   if (field.type === "checkbox") {
+    if (isGroupedChoiceField) {
+      return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        ChoiceGroupFrame,
+        {
+          props,
+          className: choiceGroupClassName,
+          slotProps: choiceGroupSlotProps,
+          renderChoiceGroup,
+          disabled,
+          readOnly,
+          children: /* @__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,
+                disabled,
+                readOnly,
+                onChange: (event) => setValue(event.currentTarget.checked)
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: field.title })
+          ] }) })
+        }
+      );
+    }
     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 +3423,84 @@ function DefaultField(props) {
   }
   if (field.type === "radio" || field.type === "multi-select") {
     const selected = Array.isArray(value) ? value : [];
+    if (isGroupedChoiceField) {
+      const isRadio = field.type === "radio";
+      return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        ChoiceGroupFrame,
+        {
+          props,
+          className: choiceGroupClassName,
+          slotProps: choiceGroupSlotProps,
+          renderChoiceGroup,
+          disabled,
+          readOnly,
+          children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "fe-choice-options", children: field.options.map((option, index) => {
+            const optionId = `${inputId}-${index}`;
+            const checked = isRadio ? value === option.id : selected.includes(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: isRadio ? "radio" : "checkbox",
+                  value: option.id,
+                  checked,
+                  disabled,
+                  readOnly,
+                  onKeyDown: isRadio ? (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();
+                  } : void 0,
+                  onChange: (event) => {
+                    if (isRadio) setValue(option.id);
+                    else
+                      setValue(
+                        event.currentTarget.checked ? [...selected, option.id] : selected.filter((item) => item !== option.id)
+                      );
+                  }
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: option.label })
+            ] }, option.id);
+          }) })
+        }
+      );
+    }
+    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,
@@ -3425,6 +3608,7 @@ function DefaultField(props) {
         ...ariaProps,
         id: inputId,
         name: field.id,
+        disabled,
         value: typeof value === "string" ? value : "",
         onChange: (event) => setValue(event.currentTarget.value || void 0),
         children: [
@@ -3448,6 +3632,20 @@ function DefaultField(props) {
       }
     );
   }
+  if (isGroupedChoiceField) {
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+      ChoiceGroupFrame,
+      {
+        props,
+        className: choiceGroupClassName,
+        slotProps: choiceGroupSlotProps,
+        renderChoiceGroup,
+        disabled,
+        readOnly,
+        children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "fe-choice-options", children: control })
+      }
+    );
+  }
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: `fe-field fe-field--${field.type}`, "data-field-id": field.id, children: [
     label,
     control,
@@ -3567,6 +3765,9 @@ function ContextFormRenderer({
   beforeSubmit,
   onDraftSave,
   successRenderMode = "append",
+  appearance,
+  slotProps,
+  groupedChoiceFields = false,
   submissionConfirmation,
   submissionConfirmationRenderMode,
   showHiddenFieldsInSummary = false,
@@ -4085,7 +4286,18 @@ 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,
+                  appearance,
+                  choiceGroupSlotProps: slotProps?.choiceGroup,
+                  renderChoiceGroup: slots.renderChoiceGroup,
+                  disabled: interactionLocked
+                },
+                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 });
@@ -4225,6 +4437,7 @@ function FormRenderer(props) {
   createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
   isTranslationUnresolved,
+  resolveChoiceFieldLayout,
   resolveFieldEditorControls,
   resolveFieldTypeSelectOptions,
   resolveInitialFieldType,

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, Question, FieldOption, TranslationReport, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, ValidationIssue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
+import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, Question, FieldOption, TranslationReport, ValidationIssue, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
 export { QuestionType } from '@form-engine-ts/core';
 import * as react from 'react';
-import { ReactNode, ComponentType, KeyboardEvent, MouseEvent } from 'react';
+import { ReactNode, ComponentType, KeyboardEvent, MouseEvent, CSSProperties } from 'react';
 import { SensitiveDataFinding } from '@form-engine-ts/privacy';
 
 interface SubmissionAttempt {
@@ -477,6 +477,25 @@ type SubmissionGuardResult = {
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
 type FormSuccessRenderMode = "append" | "replace";
+type ChoiceFieldLayoutMode = "default" | "grouped";
+interface ChoiceFieldTypeLayoutMap {
+    readonly radio?: ChoiceFieldLayoutMode;
+    readonly checkbox?: ChoiceFieldLayoutMode;
+    readonly "multi-select"?: ChoiceFieldLayoutMode;
+    readonly select?: ChoiceFieldLayoutMode;
+}
+type FieldError = ValidationIssue & {
+    readonly message: string;
+};
+interface FormRendererAppearance {
+    /**
+     * Layout preset for choice questions (radio, checkbox, and multi-select).
+     * - "default": keep the flat question layout.
+     * - "grouped": render a bordered fieldset and legend.
+     * - An object can configure each choice question type independently.
+     */
+    readonly choiceField?: ChoiceFieldLayoutMode | ChoiceFieldTypeLayoutMap;
+}
 type SubmissionConfirmationRenderMode = "inline" | "replace" | "dialog";
 interface SubmissionConfirmationOptions {
     readonly enabled?: boolean;
@@ -504,6 +523,23 @@ interface FormFieldsSlotProps {
     readonly children: ReactNode;
     readonly className?: string;
 }
+interface ChoiceGroupSlotProps {
+    readonly field: Question;
+    readonly title: string;
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly error?: FieldError;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly children: ReactNode;
+    readonly className?: string;
+}
+interface FormRendererSlotProps {
+    readonly choiceGroup?: {
+        readonly className?: string;
+        readonly style?: CSSProperties;
+    };
+}
 interface FormRendererSlots {
     readonly renderHeader?: (props: {
         readonly title: string;
@@ -554,6 +590,7 @@ interface FormRendererSlots {
         readonly current: number;
         readonly max: number;
     }) => ReactNode;
+    readonly renderChoiceGroup?: (props: ChoiceGroupSlotProps) => ReactNode;
 }
 interface SubmissionProtectionProps {
     readonly submissionGuards?: readonly SubmissionGuard[];
@@ -656,6 +693,7 @@ declare const BUILDER_TRANSLATION_ALIASES: Readonly<Record<string, string>>;
 declare function isTranslationUnresolved(result: unknown, key: string, aliases?: readonly string[]): boolean;
 declare function resolveTranslation(key: string, aliases: readonly string[], adapter?: TranslationAdapter, defaultCatalog?: Readonly<Record<string, string>>, params?: Readonly<Record<string, unknown>>, locale?: string): string;
 
+declare function resolveChoiceFieldLayout(type: FieldType, appearance?: FormRendererAppearance, groupedChoiceFieldsLegacy?: boolean): "default" | "grouped";
 interface FieldComponentProps {
     readonly field: FormField;
     readonly value: FormValue;
@@ -671,6 +709,10 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    readonly appearance?: FormRendererAppearance;
+    readonly slotProps?: FormRendererSlotProps;
+    /** @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 +746,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 ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldError, 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 FormRendererSlotProps, 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, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, Question, FieldOption, TranslationReport, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, ValidationIssue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
+import { QuestionType, FormField, ChoiceOption, FormPage, FormSchema, DisplayCondition, JsonValue, SchemaIssue, FormPolicy, Question, FieldOption, TranslationReport, ValidationIssue, ValidationError, FormValues, TranslationAdapter, AsyncTranslationAdapter, PopulateTranslationOptions, FormValue, AnswerValidationResult, FieldType } from '@form-engine-ts/core';
 export { QuestionType } from '@form-engine-ts/core';
 import * as react from 'react';
-import { ReactNode, ComponentType, KeyboardEvent, MouseEvent } from 'react';
+import { ReactNode, ComponentType, KeyboardEvent, MouseEvent, CSSProperties } from 'react';
 import { SensitiveDataFinding } from '@form-engine-ts/privacy';
 
 interface SubmissionAttempt {
@@ -477,6 +477,25 @@ type SubmissionGuardResult = {
 };
 type SubmissionGuard = (schema: FormSchema, values: Record<string, unknown>) => SubmissionGuardResult | Promise<SubmissionGuardResult>;
 type FormSuccessRenderMode = "append" | "replace";
+type ChoiceFieldLayoutMode = "default" | "grouped";
+interface ChoiceFieldTypeLayoutMap {
+    readonly radio?: ChoiceFieldLayoutMode;
+    readonly checkbox?: ChoiceFieldLayoutMode;
+    readonly "multi-select"?: ChoiceFieldLayoutMode;
+    readonly select?: ChoiceFieldLayoutMode;
+}
+type FieldError = ValidationIssue & {
+    readonly message: string;
+};
+interface FormRendererAppearance {
+    /**
+     * Layout preset for choice questions (radio, checkbox, and multi-select).
+     * - "default": keep the flat question layout.
+     * - "grouped": render a bordered fieldset and legend.
+     * - An object can configure each choice question type independently.
+     */
+    readonly choiceField?: ChoiceFieldLayoutMode | ChoiceFieldTypeLayoutMap;
+}
 type SubmissionConfirmationRenderMode = "inline" | "replace" | "dialog";
 interface SubmissionConfirmationOptions {
     readonly enabled?: boolean;
@@ -504,6 +523,23 @@ interface FormFieldsSlotProps {
     readonly children: ReactNode;
     readonly className?: string;
 }
+interface ChoiceGroupSlotProps {
+    readonly field: Question;
+    readonly title: string;
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly error?: FieldError;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly children: ReactNode;
+    readonly className?: string;
+}
+interface FormRendererSlotProps {
+    readonly choiceGroup?: {
+        readonly className?: string;
+        readonly style?: CSSProperties;
+    };
+}
 interface FormRendererSlots {
     readonly renderHeader?: (props: {
         readonly title: string;
@@ -554,6 +590,7 @@ interface FormRendererSlots {
         readonly current: number;
         readonly max: number;
     }) => ReactNode;
+    readonly renderChoiceGroup?: (props: ChoiceGroupSlotProps) => ReactNode;
 }
 interface SubmissionProtectionProps {
     readonly submissionGuards?: readonly SubmissionGuard[];
@@ -656,6 +693,7 @@ declare const BUILDER_TRANSLATION_ALIASES: Readonly<Record<string, string>>;
 declare function isTranslationUnresolved(result: unknown, key: string, aliases?: readonly string[]): boolean;
 declare function resolveTranslation(key: string, aliases: readonly string[], adapter?: TranslationAdapter, defaultCatalog?: Readonly<Record<string, string>>, params?: Readonly<Record<string, unknown>>, locale?: string): string;
 
+declare function resolveChoiceFieldLayout(type: FieldType, appearance?: FormRendererAppearance, groupedChoiceFieldsLegacy?: boolean): "default" | "grouped";
 interface FieldComponentProps {
     readonly field: FormField;
     readonly value: FormValue;
@@ -671,6 +709,10 @@ type FieldComponents = Partial<Record<FieldType, ComponentType<FieldComponentPro
 interface FormRendererPresentationProps extends SubmissionProtectionProps {
     readonly components?: FieldComponents;
     readonly className?: string;
+    readonly appearance?: FormRendererAppearance;
+    readonly slotProps?: FormRendererSlotProps;
+    /** @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 +746,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 ChoiceFieldTypeLayoutMap, type ChoiceGroupSlotProps, type ComponentBaseProps, type FieldComponentProps, type FieldComponents, type FieldEditorControlsConfig, type FieldEditorHeaderSlotProps, type FieldError, 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 FormRendererSlotProps, 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, resolveChoiceFieldLayout, resolveFieldEditorControls, resolveFieldTypeSelectOptions, resolveInitialFieldType, resolveTranslation, submissionReceiptQueryKey, useField, useForm, useFormBuilder, useSubmissionReceipts };

package/dist/index.js

@@ -3253,14 +3253,25 @@ import {
   useState as useState4
 } from "react";
 import { Fragment as Fragment3, jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+var isChoiceFieldType = (type) => type === "radio" || type === "checkbox" || type === "multi-select" || type === "select";
+function resolveChoiceFieldLayout(type, appearance, groupedChoiceFieldsLegacy = false) {
+  if (groupedChoiceFieldsLegacy) return "grouped";
+  const config = appearance?.choiceField;
+  if (config === void 0) return "default";
+  if (typeof config === "string") return config;
+  return config[type] ?? "default";
+}
 function describedBy(field, error, helpId, errorId) {
   const ids = [field.description === void 0 ? void 0 : helpId, error === void 0 ? void 0 : errorId].filter(
     Boolean
   );
   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 +3282,106 @@ 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 ChoiceGroupFrame({
+  props,
+  children,
+  className,
+  slotProps,
+  renderChoiceGroup,
+  disabled,
+  readOnly
+}) {
+  const { field, error, translate } = props;
+  const groupError = error === void 0 ? void 0 : { ...error, message: translate(error.messageKey, error.params) };
+  const groupProps = {
+    field,
+    title: field.title,
+    ...field.description === void 0 ? {} : { description: field.description },
+    ...field.required === void 0 ? {} : { required: field.required },
+    ...groupError === void 0 ? {} : { error: groupError },
+    ...disabled === void 0 ? {} : { disabled },
+    ...readOnly === void 0 ? {} : { readOnly },
+    children,
+    className
+  };
+  if (renderChoiceGroup !== void 0) return /* @__PURE__ */ jsx3(Fragment3, { children: renderChoiceGroup(groupProps) });
+  return (
+    // biome-ignore lint/a11y/useAriaPropsSupportedByRole: The grouped fieldset exposes the required state for the complete choice question.
+    /* @__PURE__ */ jsxs2(
+      "fieldset",
+      {
+        className,
+        "data-field-id": field.id,
+        disabled,
+        "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
+        "aria-invalid": Boolean(error),
+        "aria-required": field.required,
+        style: slotProps?.style,
+        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 }),
+          children,
+          /* @__PURE__ */ jsx3(GroupedChoiceError, { props })
+        ]
+      }
+    )
+  );
+}
+function DefaultField({
+  groupedChoiceFields,
+  appearance,
+  choiceGroupSlotProps,
+  renderChoiceGroup,
+  disabled,
+  readOnly,
+  ...props
+}) {
   const { field, value, setValue, inputId, error, translate } = props;
+  const isGroupedChoiceField = isChoiceFieldType(field.type) && resolveChoiceFieldLayout(field.type, appearance, groupedChoiceFields) === "grouped";
+  const choiceGroupClassName = ["fe-choice-group", `fe-field--${field.type}`, choiceGroupSlotProps?.className].filter((item) => item !== void 0 && item.length > 0).join(" ");
   const ariaProps = {
     "aria-describedby": describedBy(field, error, props.helpId, props.errorId),
     "aria-invalid": error === void 0 ? void 0 : true
   };
   if (field.type === "checkbox") {
+    if (isGroupedChoiceField) {
+      return /* @__PURE__ */ jsx3(
+        ChoiceGroupFrame,
+        {
+          props,
+          className: choiceGroupClassName,
+          slotProps: choiceGroupSlotProps,
+          renderChoiceGroup,
+          disabled,
+          readOnly,
+          children: /* @__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,
+                disabled,
+                readOnly,
+                onChange: (event) => setValue(event.currentTarget.checked)
+              }
+            ),
+            /* @__PURE__ */ jsx3("span", { children: field.title })
+          ] }) })
+        }
+      );
+    }
     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 +3405,84 @@ function DefaultField(props) {
   }
   if (field.type === "radio" || field.type === "multi-select") {
     const selected = Array.isArray(value) ? value : [];
+    if (isGroupedChoiceField) {
+      const isRadio = field.type === "radio";
+      return /* @__PURE__ */ jsx3(
+        ChoiceGroupFrame,
+        {
+          props,
+          className: choiceGroupClassName,
+          slotProps: choiceGroupSlotProps,
+          renderChoiceGroup,
+          disabled,
+          readOnly,
+          children: /* @__PURE__ */ jsx3("div", { className: "fe-choice-options", children: field.options.map((option, index) => {
+            const optionId = `${inputId}-${index}`;
+            const checked = isRadio ? value === option.id : selected.includes(option.id);
+            return /* @__PURE__ */ jsxs2("label", { className: "fe-choice-option", htmlFor: optionId, children: [
+              /* @__PURE__ */ jsx3(
+                "input",
+                {
+                  id: optionId,
+                  name: field.id,
+                  type: isRadio ? "radio" : "checkbox",
+                  value: option.id,
+                  checked,
+                  disabled,
+                  readOnly,
+                  onKeyDown: isRadio ? (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();
+                  } : void 0,
+                  onChange: (event) => {
+                    if (isRadio) setValue(option.id);
+                    else
+                      setValue(
+                        event.currentTarget.checked ? [...selected, option.id] : selected.filter((item) => item !== option.id)
+                      );
+                  }
+                }
+              ),
+              /* @__PURE__ */ jsx3("span", { children: option.label })
+            ] }, option.id);
+          }) })
+        }
+      );
+    }
+    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,
@@ -3408,6 +3590,7 @@ function DefaultField(props) {
         ...ariaProps,
         id: inputId,
         name: field.id,
+        disabled,
         value: typeof value === "string" ? value : "",
         onChange: (event) => setValue(event.currentTarget.value || void 0),
         children: [
@@ -3431,6 +3614,20 @@ function DefaultField(props) {
       }
     );
   }
+  if (isGroupedChoiceField) {
+    return /* @__PURE__ */ jsx3(
+      ChoiceGroupFrame,
+      {
+        props,
+        className: choiceGroupClassName,
+        slotProps: choiceGroupSlotProps,
+        renderChoiceGroup,
+        disabled,
+        readOnly,
+        children: /* @__PURE__ */ jsx3("div", { className: "fe-choice-options", children: control })
+      }
+    );
+  }
   return /* @__PURE__ */ jsxs2("div", { className: `fe-field fe-field--${field.type}`, "data-field-id": field.id, children: [
     label,
     control,
@@ -3550,6 +3747,9 @@ function ContextFormRenderer({
   beforeSubmit,
   onDraftSave,
   successRenderMode = "append",
+  appearance,
+  slotProps,
+  groupedChoiceFields = false,
   submissionConfirmation,
   submissionConfirmationRenderMode,
   showHiddenFieldsInSummary = false,
@@ -4068,7 +4268,18 @@ 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,
+                  appearance,
+                  choiceGroupSlotProps: slotProps?.choiceGroup,
+                  renderChoiceGroup: slots.renderChoiceGroup,
+                  disabled: interactionLocked
+                },
+                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 });
@@ -4207,6 +4418,7 @@ export {
   createLocalStorageSubmissionAttemptStore,
   createLocalStorageSubmissionReceiptStore,
   isTranslationUnresolved,
+  resolveChoiceFieldLayout,
   resolveFieldEditorControls,
   resolveFieldTypeSelectOptions,
   resolveInitialFieldType,

package/dist/styles.css

@@ -1,4 +1,15 @@
 /* src/styles.css */
+:root {
+  --fe-choice-group-border: 1px solid var(--fe-border-color, #e2e8f0);
+  --fe-choice-group-radius: var(--fe-radius, 8px);
+  --fe-choice-group-padding: 1rem 1.25rem;
+  --fe-choice-group-margin-bottom: 1.25rem;
+  --fe-choice-group-bg: var(--fe-bg-color, transparent);
+  --fe-choice-legend-font-weight: 600;
+  --fe-choice-legend-font-size: 0.95rem;
+  --fe-choice-legend-color: var(--fe-text-color, inherit);
+  --fe-choice-options-gap: 0.625rem;
+}
 .fe-form {
   color: #17202a;
   display: grid;
@@ -123,6 +134,41 @@
 .fe-check-label input {
   margin-top: 0.22rem;
 }
+.fe-choice-group {
+  background-color: var(--fe-choice-group-bg);
+  border: var(--fe-choice-group-border);
+  border-radius: var(--fe-choice-group-radius);
+  box-sizing: border-box;
+  margin: 0 0 var(--fe-choice-group-margin-bottom);
+  padding: var(--fe-choice-group-padding);
+}
+.fe-choice-legend {
+  color: var(--fe-choice-legend-color);
+  font-size: var(--fe-choice-legend-font-size);
+  font-weight: var(--fe-choice-legend-font-weight);
+  padding: 0 0.5rem;
+}
+.fe-choice-options {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fe-choice-options-gap);
+  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.4.0",
   "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.4.0",
+    "@form-engine-ts/privacy": "4.4.0"
   },
   "peerDependencies": {
     "react": ">=18.2 <20",