Merge pull request #454 from acelaya-forks/feature/labelled-help-text

acelaya · web-flow · commit 52845030d409 · 2025-04-27T11:11:15.000+02:00
Add support to pass help text to labelled form control variants
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,9 +4,9 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org).
 
-## [Unreleased]
+## [0.8.13] - 2025-04-27
 ### Added
-* *Nothing*
+* Allow help text to be passed to labelled form control tailwind-based components.
 
 ### Changed
 * Define bootstrap breakpoints in tailwind preset, so that migration can be done progressively.
diff --git a/dev/tailwind/form/InputsPage.tsx b/dev/tailwind/form/InputsPage.tsx
@@ -48,7 +48,8 @@ export const InputsPage: FC = () => {
         <Input placeholder="Error input" feedback="error" />
         <Input placeholder="Disabled input" disabled />
         <Input placeholder="Readonly input" readOnly />
-        <LabelledInput label="Labelled input" />
+        <LabelledInput label="Labelled input" helpText="This is the help text under the input" />
+        <LabelledInput label="Error labelled input" error="This input is invalid!" />
         <Input placeholder="Large input" size="lg" />
         <Input placeholder="Small input" size="sm" />
         <LabelledRevealablePasswordInput label="Revealable password input" defaultValue="some_password" />
diff --git a/src/tailwind/form/FormControlWithFeedback.tsx b/src/tailwind/form/FormControlWithFeedback.tsx
@@ -0,0 +1,30 @@
+import type { FC, PropsWithChildren, ReactNode } from 'react';
+
+export type FormControlWithFeedbackProps = PropsWithChildren<{
+  /** An error message to display under the input. Will cause the input to be set with `error` feedback. */
+  error?: ReactNode;
+  /** Informative help to be display under the input */
+  helpText?: ReactNode;
+
+  'data-testid'?: string;
+}>;
+
+/**
+ * This component should not be exported from the module. It's designed to reuse as a helper wrapper
+ */
+export const FormControlWithFeedback: FC<FormControlWithFeedbackProps> = (
+  { children, helpText, error, 'data-testid': testId },
+) => (
+  <div className="tw:flex tw:flex-col tw:gap-1" data-testid={testId}>
+    {children}
+    {helpText && (
+      <small
+        data-testid={testId ? `${testId}-help-text` : 'help-text'}
+        className="tw:text-gray-500 tw:dark:text-gray-400"
+      >
+        {helpText}
+      </small>
+    )}
+    {error && <span data-testid={testId ? `${testId}-error` : 'error'} className="tw:text-danger">{error}</span>}
+  </div>
+);
diff --git a/src/tailwind/form/LabelledInput.tsx b/src/tailwind/form/LabelledInput.tsx
@@ -1,25 +1,26 @@
-import { forwardRef , useId } from 'react';
+import { forwardRef, useId } from 'react';
 import type { RequiredReactNode } from '../types';
+import type { FormControlWithFeedbackProps } from './FormControlWithFeedback';
+import { FormControlWithFeedback } from './FormControlWithFeedback';
 import type { InputProps } from './Input';
 import { Input } from './Input';
 import { Label } from './Label';
 
-export type LabelledInputProps = Omit<InputProps, 'className' | 'id' | 'feedback'> & {
+export type LabelledInputProps = Omit<InputProps, 'className' | 'id' | 'feedback'> & FormControlWithFeedbackProps & {
   label: RequiredReactNode;
   inputClassName?: string;
-  error?: string;
 
   /** Alternative to `required`. Causes the input to be required, without displaying an asterisk */
   hiddenRequired?: boolean;
 };
 
 export const LabelledInput = forwardRef<HTMLInputElement, LabelledInputProps>((
-  { label, inputClassName, required, hiddenRequired, error, ...rest },
+  { label, inputClassName, required, hiddenRequired, error, helpText, 'data-testid': testId, ...rest },
   ref,
 ) => {
   const id = useId();
   return (
-    <div className="tw:flex tw:flex-col tw:gap-1">
+    <FormControlWithFeedback error={error} helpText={helpText} data-testid={testId}>
       <Label htmlFor={id} required={required}>{label}</Label>
       <Input
         ref={ref}
@@ -29,7 +30,6 @@ export const LabelledInput = forwardRef<HTMLInputElement, LabelledInputProps>((
         feedback={error ? 'error' : undefined}
         {...rest}
       />
-      {error && <span className="tw:text-danger">{error}</span>}
-    </div>
+    </FormControlWithFeedback>
   );
 });
diff --git a/src/tailwind/form/LabelledRevealablePasswordInput.tsx b/src/tailwind/form/LabelledRevealablePasswordInput.tsx
@@ -1,26 +1,27 @@
 import { forwardRef , useId } from 'react';
 import type { RequiredReactNode } from '../types';
+import type { FormControlWithFeedbackProps } from './FormControlWithFeedback';
+import { FormControlWithFeedback } from './FormControlWithFeedback';
 import { Label } from './Label';
 import type { RevealablePasswordInputProps } from './RevealablePasswordInput';
 import { RevealablePasswordInput } from './RevealablePasswordInput';
 
 export type LabelledRevealablePasswordInputProps =
-  Omit<RevealablePasswordInputProps, 'className' | 'id' | 'feedback'> & {
+  Omit<RevealablePasswordInputProps, 'className' | 'id' | 'feedback'> & FormControlWithFeedbackProps & {
     label: RequiredReactNode;
     inputClassName?: string;
-    error?: string;
 
     /** Alternative to `required`. Causes the input to be required, without displaying an asterisk */
     hiddenRequired?: boolean;
   };
 
 export const LabelledRevealablePasswordInput = forwardRef<HTMLInputElement, LabelledRevealablePasswordInputProps>((
-  { label, inputClassName, required, hiddenRequired, error, ...rest },
+  { label, inputClassName, required, hiddenRequired, error, helpText, 'data-testid': testId, ...rest },
   ref,
 ) => {
   const id = useId();
   return (
-    <div className="tw:flex tw:flex-col tw:gap-1">
+    <FormControlWithFeedback error={error} helpText={helpText} data-testid={testId}>
       <Label htmlFor={id} required={required}>{label}</Label>
       <RevealablePasswordInput
         ref={ref}
@@ -30,7 +31,6 @@ export const LabelledRevealablePasswordInput = forwardRef<HTMLInputElement, Labe
         feedback={error ? 'error' : undefined}
         {...rest}
       />
-      {error && <span className="tw:text-danger">{error}</span>}
-    </div>
+    </FormControlWithFeedback>
   );
 });
diff --git a/src/tailwind/form/LabelledSelect.tsx b/src/tailwind/form/LabelledSelect.tsx
@@ -1,10 +1,12 @@
-import { forwardRef , useId } from 'react';
+import { forwardRef, useId } from 'react';
 import type { RequiredReactNode } from '../types';
+import type { FormControlWithFeedbackProps } from './FormControlWithFeedback';
+import { FormControlWithFeedback } from './FormControlWithFeedback';
 import { Label } from './Label';
 import type { SelectProps } from './Select';
 import { Select } from './Select';
 
-export type LabelledSelectProps = Omit<SelectProps, 'className' | 'id'> & {
+export type LabelledSelectProps = Omit<SelectProps, 'className' | 'id'> & FormControlWithFeedbackProps & {
   label: RequiredReactNode;
   selectClassName?: string;
 
@@ -13,14 +15,21 @@ export type LabelledSelectProps = Omit<SelectProps, 'className' | 'id'> & {
 };
 
 export const LabelledSelect = forwardRef<HTMLSelectElement, LabelledSelectProps>((
-  { selectClassName, label, required, hiddenRequired, ...rest },
+  { selectClassName, label, error, helpText, required, hiddenRequired, 'data-testid': testId, ...rest },
   ref,
 ) => {
   const id = useId();
   return (
-    <div className="tw:flex tw:flex-col tw:gap-1">
+    <FormControlWithFeedback error={error} helpText={helpText} data-testid={testId}>
       <Label htmlFor={id} required={required}>{label}</Label>
-      <Select ref={ref} id={id} className={selectClassName} required={required || hiddenRequired} {...rest} />
-    </div>
+      <Select
+        ref={ref}
+        id={id}
+        className={selectClassName}
+        required={required || hiddenRequired}
+        feedback={error ? 'error' : undefined}
+        {...rest}
+      />
+    </FormControlWithFeedback>
   );
 });
diff --git a/test/tailwind/feedback/CardModal.test.tsx b/test/tailwind/feedback/CardModal.test.tsx
@@ -68,7 +68,7 @@ describe('<CardModal />', () => {
   ])('renders expected size', (size) => {
     const { container } = setUp({ size });
     // We need to match against the container's parent (the body) since dialogs are rendered there via portals
-    expect(container.parentNode).toMatchSnapshot();
+    expect(container.parentNode?.querySelector('dialog')).toMatchSnapshot();
   });
 
   it.each([
@@ -78,7 +78,7 @@ describe('<CardModal />', () => {
   ])('renders expected variant', (props) => {
     const { container } = setUp(props);
     // We need to match against the container's parent (the body) since dialogs are rendered there via portals
-    expect(container.parentNode).toMatchSnapshot();
+    expect(container.parentNode?.querySelector('dialog')).toMatchSnapshot();
   });
 
   it('defers closing the modal until the transition has finished', async () => {
diff --git a/test/tailwind/feedback/__snapshots__/CardModal.test.tsx.snap b/test/tailwind/feedback/__snapshots__/CardModal.test.tsx.snap
diff --git a/test/tailwind/form/LabelledInput.test.tsx b/test/tailwind/form/LabelledInput.test.tsx
