alma-oss · crishpeen · Mar 13, 2026
@@ -2,10 +2,12 @@
 
 import classNames from 'classnames';
 import React, { type ForwardedRef, forwardRef } from 'react';
-import { useAriaDescribedBy, useStyleProps } from '../../hooks';
-import { type ForwardRefComponent, type SpiritCheckboxProps } from '../../types';
-import { HelperText, Label, ValidationText, useAriaIds } from '../Field';
+import { PropsProvider } from '../../context';
+import { useAriaDescribedBy, useAriaIds, useStyleProps } from '../../hooks';
+import { FormFieldVariants, type ForwardRefComponent, type SpiritCheckboxProps } from '../../types';
+import { Label, ValidationText } from '../Field';
 import { useValidationTextRole } from '../Field/useValidationTextRole';
+import { HelperText } from '../HelperText';
 import { useCheckboxStyleProps } from './useCheckboxStyleProps';
 
 const _Checkbox = (props: SpiritCheckboxProps, ref: ForwardedRef<HTMLInputElement>): JSX.Element => {
@@ -17,6 +19,7 @@ const _Checkbox = (props: SpiritCheckboxProps, ref: ForwardedRef<HTMLInputElemen
     id,
     isChecked,
     isDisabled,
+    isItem,
     isRequired,
     label,
     validationState,
@@ -33,41 +36,43 @@ const _Checkbox = (props: SpiritCheckboxProps, ref: ForwardedRef<HTMLInputElemen
   });
 
   return (
-    <div style={styleProps.style} className={classNames(classProps.root, styleProps.className)}>
-      <input
-        {...otherProps}
-        {...ariaDescribedByProp}
-        type="checkbox"
-        id={id}
-        className={classProps.input}
-        disabled={isDisabled}
-        required={isRequired}
-        checked={isChecked}
-        value={value}
-        ref={ref}
-      />
-      <div className={classProps.text}>
-        <Label UNSAFE_className={classProps.label} htmlFor={id}>
-          {label}
-        </Label>
-        <HelperText
-          UNSAFE_className={classProps.helperText}
-          id={`${id}__helperText`}
-          registerAria={register}
-          helperText={helperText}
+    <PropsProvider
+      value={{
+        isDisabled,
+        formFieldVariant: isItem ? FormFieldVariants.ITEM : FormFieldVariants.INLINE,
+      }}
+    >
+      <div style={styleProps.style} className={classNames(classProps.root, styleProps.className)}>
+        <input
+          {...otherProps}
+          {...ariaDescribedByProp}
+          type="checkbox"
+          id={id}
+          className={classProps.input}
+          disabled={isDisabled}
+          required={isRequired}
+          checked={isChecked}
+          value={value}
+          ref={ref}
         />
-        {validationState && (
-          <ValidationText
-            UNSAFE_className={classProps.validationText}
-            id={`${id}__validationText`}
-            {...(hasValidationIcon && { hasValidationStateIcon: validationState })}
-            validationText={validationText}
-            registerAria={register}
-            role={validationTextRole}
-          />
-        )}
+        <div className={classProps.text}>
+          <Label UNSAFE_className={classProps.label} htmlFor={id}>
+            {label}
+          </Label>
+          <HelperText id={`${id}__helperText`} registerAria={register} helperText={helperText} />
+          {validationState && (
+            <ValidationText
+              UNSAFE_className={classProps.validationText}
+              id={`${id}__validationText`}
+              {...(hasValidationIcon && { hasValidationStateIcon: validationState })}
+              validationText={validationText}
+              registerAria={register}
+              role={validationTextRole}
+            />
+          )}
+        </div>
       </div>
-    </div>
+    </PropsProvider>
   );
 };
 

@@ -71,7 +71,6 @@ describe('Checkbox', () => {
     const element = screen.getByText('text');
 
     expect(element).toBeInTheDocument();
-    expect(element).toHaveClass('Checkbox__helperText');
   });
 
   it('should render label with html tags', () => {

@@ -14,7 +14,6 @@ describe('useCheckboxStyleProps', () => {
       input: 'Checkbox__input',
       label: 'Checkbox__label',
       validationText: 'Checkbox__validationText',
-      helperText: 'Checkbox__helperText',
     });
   });
 

@@ -10,7 +10,6 @@ export interface CheckboxStyles {
     text: string;
     label: string;
     input: string;
-    helperText: string;
     validationText: string;
   };
   /** props to be passed to the input element */
@@ -30,7 +29,6 @@ export function useCheckboxStyleProps(props: SpiritCheckboxProps): CheckboxStyle
   const checkboxLabelClass = `${checkboxClass}__label`;
   const checkboxLabelRequiredClass = `${checkboxClass}__label--required`;
   const checkboxLabelHiddenClass = `${checkboxClass}__label--hidden`;
-  const checkboxHelperTextClass = `${checkboxClass}__helperText`;
   const checkboxValidationTextClass = `${checkboxClass}__validationText`;
   const checkboxValidationClass = `${checkboxClass}--${validationState}`;
 
@@ -51,7 +49,6 @@ export function useCheckboxStyleProps(props: SpiritCheckboxProps): CheckboxStyle
       text: checkboxTextClass,
       label: labelStyles,
       input: checkboxInputClass,
-      helperText: checkboxHelperTextClass,
       validationText: checkboxValidationTextClass,
     },
     props: {

@@ -41,37 +41,6 @@ On top of the API options, the components accept [additional attributes][readme-
 If you need more control over the styling of a component, you can use [style props][readme-style-props]
 and [escape hatches][readme-escape-hatches].
 
-## HelperText
-
-The HelperText subcomponent displays helper texts for Field components like TextField, TextArea, Checkbox, FileUploader, etc.
-
-```tsx
-<HelperText UNSAFE_className="Component__helperText" helperText="Helper text" />
-```
-
-Advanced example:
-
-```tsx
-<HelperText
-  id="component__helperText"
-  UNSAFE_className="Component__helperText"
-  elementType="span"
-  helperText="Helper text"
-/>
-```
-
-### API
-
-| Name          | Type                            | Default | Required | Description                                                                                    |
-| ------------- | ------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `elementType` | \[`span` \| `div`]              | `div`   | ✕        | Type of element used as main wrapper (applied only for single validation text, otherwise `ul`) |
-| `helperText`  | \[`ReactNode` \| `ReactNode[]`] | —       | ✕        | Validation text, only visible if validationState is                                            |
-| `id`          | `string`                        | —       | ✕        | Component id                                                                                   |
-
-On top of the API options, the components accept [additional attributes][readme-additional-attributes].
-If you need more control over the styling of a component, you can use [style props][readme-style-props]
-and [escape hatches][readme-escape-hatches].
-
 ## Label
 
 The `Label` component is used to associate text with a form control, such as an input, checkbox, or radio button.

@@ -1,5 +1,2 @@
-export { default as HelperText } from './HelperText';
 export { default as Label } from './Label';
-export { default as useAriaIds } from './useAriaIds';
 export { default as ValidationText } from './ValidationText';
-export * from './useAriaIds';
@@ -1,6 +1,11 @@
-import { type ElementType, type ReactNode } from 'react';
-import { type ChildrenProps, type StyleProps, type TransferProps, type ValidationTextProp } from '../../types';
-import { type RegisterType } from './useAriaIds';
+import { type ElementType } from 'react';
+import {
+  type ChildrenProps,
+  type RegisterType,
+  type StyleProps,
+  type TransferProps,
+  type ValidationTextProp,
+} from '../../types';
 
 export interface FieldElementTypeProps<E extends ElementType = 'div'> {
   /**
@@ -16,10 +21,5 @@ export interface FieldProps<E extends ElementType = 'div'> extends FieldElementT
   registerAria?: RegisterType;
 }
 
-export interface HelperTextProps<T extends ElementType = 'div'>
-  extends FieldProps<T>, StyleProps, ChildrenProps, TransferProps {
-  helperText: ReactNode;
-}
-
 export interface ValidationTextProps<T extends ElementType = 'div'>
   extends FieldProps<T>, ValidationTextProp, StyleProps, ChildrenProps, TransferProps {}
@@ -2,10 +2,12 @@
 
 import classNames from 'classnames';
 import React from 'react';
-import { useAriaDescribedBy, useStyleProps } from '../../hooks';
-import { type SpiritFieldGroupProps } from '../../types';
-import { HelperText, ValidationText, useAriaIds } from '../Field';
+import { PropsProvider } from '../../context';
+import { useAriaDescribedBy, useAriaIds, useStyleProps } from '../../hooks';
+import { FormFieldVariants, type SpiritFieldGroupProps } from '../../types';
+import { ValidationText } from '../Field';
 import { useValidationTextRole } from '../Field/useValidationTextRole';
+import { HelperText } from '../HelperText';
 import { VisuallyHidden } from '../VisuallyHidden';
 import { useFieldGroupStyleProps } from './useFieldGroupStyleProps';
 
@@ -36,37 +38,34 @@ const FieldGroup = (props: SpiritFieldGroupProps) => {
   });
 
   return (
-    <fieldset
-      {...transferProps}
-      {...styleProps}
-      {...ariaDescribedByProp}
-      className={classNames(classProps.root, styleProps.className)}
-      disabled={isDisabled}
-    >
-      <VisuallyHidden elementType="legend">{label}</VisuallyHidden>
-      {!isLabelHidden && (
-        <div className={classProps.label} aria-hidden="true">
-          {label}
-        </div>
-      )}
-      <div className={classProps.fields}>{children}</div>
-      <HelperText
-        UNSAFE_className={classProps.helperText}
-        id={`${id}__helperText`}
-        registerAria={register}
-        helperText={helperText}
-      />
-      {validationState && (
-        <ValidationText
-          UNSAFE_className={classProps.validationText}
-          {...(hasValidationIcon && { hasValidationStateIcon: validationState })}
-          id={`${id}__helperText`}
-          validationText={validationText}
-          registerAria={register}
-          role={validationTextRole}
-        />
-      )}
-    </fieldset>
+    <PropsProvider value={{ isDisabled, formFieldVariant: FormFieldVariants.BOX }}>
+      <fieldset
+        {...transferProps}
+        {...styleProps}
+        {...ariaDescribedByProp}
+        className={classNames(classProps.root, styleProps.className)}
+        disabled={isDisabled}
+      >
+        <VisuallyHidden elementType="legend">{label}</VisuallyHidden>
+        {!isLabelHidden && (
+          <div className={classProps.label} aria-hidden="true">
+            {label}
+          </div>
+        )}
+        <div className={classProps.fields}>{children}</div>
+        <HelperText id={`${id}__helperText`} registerAria={register} helperText={helperText} />
+        {validationState && (
+          <ValidationText
+            UNSAFE_className={classProps.validationText}
+            {...(hasValidationIcon && { hasValidationStateIcon: validationState })}
+            id={`${id}__helperText`}
+            validationText={validationText}
+            registerAria={register}
+            role={validationTextRole}
+          />
+        )}
+      </fieldset>
+    </PropsProvider>
   );
 };
 

@@ -116,7 +116,6 @@ describe('FieldGroup', () => {
     const element = screen.getByText('helper text');
 
     expect(element).toBeInTheDocument();
-    expect(element).toHaveClass('FieldGroup__helperText');
   });
 
   it('should have correct id', () => {