From 0924171c0f108f59c858c73362367f0f13cccc08 Mon Sep 17 00:00:00 2001
From: diondiondion <mail@diondiondion.com>
Date: Thu, 22 Jan 2026 17:08:57 +0100
Subject: [PATCH] Add form field components: `TextInputField`, `TextAreaField`,
 `SelectField` (#37578)

---
 .../mastodon/components/form_fields/index.ts  |   3 +
 .../form_fields/select_field.stories.tsx      |  55 ++++++++++
 .../components/form_fields/select_field.tsx   |  38 +++++++
 .../form_fields/text_area_field.stories.tsx   |  45 ++++++++
 .../form_fields/text_area_field.tsx           |  31 ++++++
 .../form_fields/text_input_field.stories.tsx  |  45 ++++++++
 .../form_fields/text_input_field.tsx          |  36 +++++++
 .../components/form_fields/wrapper.tsx        | 100 ++++++++++++++++++
 .../mastodon/features/lists/new.tsx           | 100 +++++++-----------
 .../mastodon/features/onboarding/profile.tsx  |  60 ++++-------
 app/javascript/mastodon/locales/en.json       |   1 +
 11 files changed, 418 insertions(+), 96 deletions(-)
 create mode 100644 app/javascript/mastodon/components/form_fields/index.ts
 create mode 100644 app/javascript/mastodon/components/form_fields/select_field.stories.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/select_field.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/text_area_field.stories.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/text_area_field.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/text_input_field.stories.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/text_input_field.tsx
 create mode 100644 app/javascript/mastodon/components/form_fields/wrapper.tsx

diff --git a/app/javascript/mastodon/components/form_fields/index.ts b/app/javascript/mastodon/components/form_fields/index.ts
new file mode 100644
index 0000000000..2aa8764514
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/index.ts
@@ -0,0 +1,3 @@
+export { TextInputField } from './text_input_field';
+export { TextAreaField } from './text_area_field';
+export { SelectField } from './select_field';
diff --git a/app/javascript/mastodon/components/form_fields/select_field.stories.tsx b/app/javascript/mastodon/components/form_fields/select_field.stories.tsx
new file mode 100644
index 0000000000..30897adda1
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/select_field.stories.tsx
@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { SelectField } from './select_field';
+
+const meta = {
+  title: 'Components/Form Fields/SelectField',
+  component: SelectField,
+  args: {
+    label: 'Fruit preference',
+    hint: 'Select your favourite fruit or not. Up to you.',
+  },
+  render(args) {
+    // Component styles require a wrapper class at the moment
+    return (
+      <div className='simple_form'>
+        <SelectField {...args}>
+          <option>Apple</option>
+          <option>Banana</option>
+          <option>Kiwi</option>
+          <option>Lemon</option>
+          <option>Mango</option>
+          <option>Orange</option>
+          <option>Pomelo</option>
+          <option>Strawberries</option>
+          <option>Something else</option>
+        </SelectField>
+      </div>
+    );
+  },
+} satisfies Meta<typeof SelectField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Simple: Story = {};
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+};
+
+export const Optional: Story = {
+  args: {
+    required: false,
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    required: false,
+    hasError: true,
+  },
+};
diff --git a/app/javascript/mastodon/components/form_fields/select_field.tsx b/app/javascript/mastodon/components/form_fields/select_field.tsx
new file mode 100644
index 0000000000..aa058fc782
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/select_field.tsx
@@ -0,0 +1,38 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import { forwardRef } from 'react';
+
+import { FormFieldWrapper } from './wrapper';
+import type { CommonFieldWrapperProps } from './wrapper';
+
+interface Props
+  extends ComponentPropsWithoutRef<'select'>, CommonFieldWrapperProps {}
+
+/**
+ * A simple form field for single-item selections.
+ * Provide selectable items via nested `<option>` elements.
+ *
+ * Accepts an optional `hint` and can be marked as required
+ * or optional (by explicitly setting `required={false}`)
+ */
+
+export const SelectField = forwardRef<HTMLSelectElement, Props>(
+  ({ id, label, hint, required, hasError, children, ...otherProps }, ref) => (
+    <FormFieldWrapper
+      label={label}
+      hint={hint}
+      required={required}
+      hasError={hasError}
+      inputId={id}
+    >
+      {(inputProps) => (
+        <div className='select-wrapper'>
+          <select {...otherProps} {...inputProps} ref={ref}>
+            {children}
+          </select>
+        </div>
+      )}
+    </FormFieldWrapper>
+  ),
+);
+
+SelectField.displayName = 'SelectField';
diff --git a/app/javascript/mastodon/components/form_fields/text_area_field.stories.tsx b/app/javascript/mastodon/components/form_fields/text_area_field.stories.tsx
new file mode 100644
index 0000000000..f06a8a223a
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/text_area_field.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { TextAreaField } from './text_area_field';
+
+const meta = {
+  title: 'Components/Form Fields/TextAreaField',
+  component: TextAreaField,
+  args: {
+    label: 'Label',
+    hint: 'This is a description of this form field',
+  },
+  render(args) {
+    // Component styles require a wrapper class at the moment
+    return (
+      <div className='simple_form'>
+        <TextAreaField {...args} />
+      </div>
+    );
+  },
+} satisfies Meta<typeof TextAreaField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Simple: Story = {};
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+};
+
+export const Optional: Story = {
+  args: {
+    required: false,
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    required: false,
+    hasError: true,
+  },
+};
diff --git a/app/javascript/mastodon/components/form_fields/text_area_field.tsx b/app/javascript/mastodon/components/form_fields/text_area_field.tsx
new file mode 100644
index 0000000000..bfd5ce8a41
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/text_area_field.tsx
@@ -0,0 +1,31 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import { forwardRef } from 'react';
+
+import { FormFieldWrapper } from './wrapper';
+import type { CommonFieldWrapperProps } from './wrapper';
+
+interface Props
+  extends ComponentPropsWithoutRef<'textarea'>, CommonFieldWrapperProps {}
+
+/**
+ * A simple form field for multi-line text.
+ *
+ * Accepts an optional `hint` and can be marked as required
+ * or optional (by explicitly setting `required={false}`)
+ */
+
+export const TextAreaField = forwardRef<HTMLTextAreaElement, Props>(
+  ({ id, label, hint, required, hasError, ...otherProps }, ref) => (
+    <FormFieldWrapper
+      label={label}
+      hint={hint}
+      required={required}
+      hasError={hasError}
+      inputId={id}
+    >
+      {(inputProps) => <textarea {...otherProps} {...inputProps} ref={ref} />}
+    </FormFieldWrapper>
+  ),
+);
+
+TextAreaField.displayName = 'TextAreaField';
diff --git a/app/javascript/mastodon/components/form_fields/text_input_field.stories.tsx b/app/javascript/mastodon/components/form_fields/text_input_field.stories.tsx
new file mode 100644
index 0000000000..e1ee57fdf5
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/text_input_field.stories.tsx
@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { TextInputField } from './text_input_field';
+
+const meta = {
+  title: 'Components/Form Fields/TextInputField',
+  component: TextInputField,
+  args: {
+    label: 'Label',
+    hint: 'This is a description of this form field',
+  },
+  render(args) {
+    // Component styles require a wrapper class at the moment
+    return (
+      <div className='simple_form'>
+        <TextInputField {...args} />
+      </div>
+    );
+  },
+} satisfies Meta<typeof TextInputField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Simple: Story = {};
+
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+};
+
+export const Optional: Story = {
+  args: {
+    required: false,
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    required: false,
+    hasError: true,
+  },
+};
diff --git a/app/javascript/mastodon/components/form_fields/text_input_field.tsx b/app/javascript/mastodon/components/form_fields/text_input_field.tsx
new file mode 100644
index 0000000000..3baafbc57c
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/text_input_field.tsx
@@ -0,0 +1,36 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import { forwardRef } from 'react';
+
+import { FormFieldWrapper } from './wrapper';
+import type { CommonFieldWrapperProps } from './wrapper';
+
+interface Props
+  extends ComponentPropsWithoutRef<'input'>, CommonFieldWrapperProps {}
+
+/**
+ * A simple form field for single-line text.
+ *
+ * Accepts an optional `hint` and can be marked as required
+ * or optional (by explicitly setting `required={false}`)
+ */
+
+export const TextInputField = forwardRef<HTMLInputElement, Props>(
+  (
+    { id, label, hint, hasError, required, type = 'text', ...otherProps },
+    ref,
+  ) => (
+    <FormFieldWrapper
+      label={label}
+      hint={hint}
+      required={required}
+      hasError={hasError}
+      inputId={id}
+    >
+      {(inputProps) => (
+        <input type={type} {...otherProps} {...inputProps} ref={ref} />
+      )}
+    </FormFieldWrapper>
+  ),
+);
+
+TextInputField.displayName = 'TextInputField';
diff --git a/app/javascript/mastodon/components/form_fields/wrapper.tsx b/app/javascript/mastodon/components/form_fields/wrapper.tsx
new file mode 100644
index 0000000000..afec04b9f5
--- /dev/null
+++ b/app/javascript/mastodon/components/form_fields/wrapper.tsx
@@ -0,0 +1,100 @@
+/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
+
+import type { ReactNode, FC } from 'react';
+import { useId } from 'react';
+
+import { FormattedMessage } from 'react-intl';
+
+import classNames from 'classnames';
+
+interface InputProps {
+  id: string;
+  required?: boolean;
+  'aria-describedby'?: string;
+}
+
+interface FieldWrapperProps {
+  label: ReactNode;
+  hint?: ReactNode;
+  required?: boolean;
+  hasError?: boolean;
+  inputId?: string;
+  children: (inputProps: InputProps) => ReactNode;
+}
+
+/**
+ * These types can be extended when creating individual field components.
+ */
+export type CommonFieldWrapperProps = Pick<
+  FieldWrapperProps,
+  'label' | 'hint' | 'hasError'
+>;
+
+/**
+ * A simple form field wrapper for adding a label and hint to enclosed components.
+ * Accepts an optional `hint` and can be marked as required
+ * or optional (by explicitly setting `required={false}`)
+ */
+
+export const FormFieldWrapper: FC<FieldWrapperProps> = ({
+  inputId: inputIdProp,
+  label,
+  hint,
+  required,
+  hasError,
+  children,
+}) => {
+  const uniqueId = useId();
+  const inputId = inputIdProp || `${uniqueId}-input`;
+  const hintId = `${inputIdProp || uniqueId}-hint`;
+  const hasHint = !!hint;
+
+  const inputProps: InputProps = {
+    required,
+    id: inputId,
+  };
+  if (hasHint) {
+    inputProps['aria-describedby'] = hintId;
+  }
+
+  return (
+    <div
+      className={classNames('input with_block_label', {
+        field_with_errors: hasError,
+      })}
+    >
+      <div className='label_input'>
+        <label htmlFor={inputId}>
+          {label}
+          {required !== undefined && <RequiredMark required={required} />}
+        </label>
+
+        {hasHint && (
+          <span className='hint' id={hintId}>
+            {hint}
+          </span>
+        )}
+
+        <div className='label_input__wrapper'>{children(inputProps)}</div>
+      </div>
+    </div>
+  );
+};
+
+/**
+ * If `required` is explicitly set to `false` rather than `undefined`,
+ * the field will be visually marked as "optional".
+ */
+
+const RequiredMark: FC<{ required?: boolean }> = ({ required }) =>
+  required ? (
+    <>
+      {' '}
+      <abbr aria-hidden='true'>*</abbr>
+    </>
+  ) : (
+    <>
+      {' '}
+      <FormattedMessage id='form_field.optional' defaultMessage='(optional)' />
+    </>
+  );
diff --git a/app/javascript/mastodon/features/lists/new.tsx b/app/javascript/mastodon/features/lists/new.tsx
index d89f27478f..53084fb568 100644
--- a/app/javascript/mastodon/features/lists/new.tsx
+++ b/app/javascript/mastodon/features/lists/new.tsx
@@ -20,6 +20,7 @@ import { Avatar } from 'mastodon/components/avatar';
 import { AvatarGroup } from 'mastodon/components/avatar_group';
 import { Column } from 'mastodon/components/column';
 import { ColumnHeader } from 'mastodon/components/column_header';
+import { SelectField, TextInputField } from 'mastodon/components/form_fields';
 import { Icon } from 'mastodon/components/icon';
 import { LoadingIndicator } from 'mastodon/components/loading_indicator';
 import type { List } from 'mastodon/models/list';
@@ -149,68 +150,49 @@ const NewList: React.FC<{ list?: List | null }> = ({ list }) => {
   return (
     <form className='simple_form app-form' onSubmit={handleSubmit}>
       <div className='fields-group'>
-        <div className='input with_label'>
-          <div className='label_input'>
-            <label htmlFor='list_title'>
-              <FormattedMessage
-                id='lists.list_name'
-                defaultMessage='List name'
-              />
-            </label>
-
-            <div className='label_input__wrapper'>
-              <input
-                id='list_title'
-                type='text'
-                value={title}
-                onChange={handleTitleChange}
-                maxLength={30}
-                required
-                placeholder=' '
-              />
-            </div>
-          </div>
-        </div>
+        <TextInputField
+          required
+          maxLength={30}
+          label={
+            <FormattedMessage id='lists.list_name' defaultMessage='List name' />
+          }
+          value={title}
+          onChange={handleTitleChange}
+          id='list_title'
+        />
       </div>
 
       <div className='fields-group'>
-        <div className='input with_label'>
-          <div className='label_input'>
-            <label htmlFor='list_replies_policy'>
-              <FormattedMessage
-                id='lists.show_replies_to'
-                defaultMessage='Include replies from list members to'
-              />
-            </label>
-
-            <div className='label_input__wrapper'>
-              <select
-                id='list_replies_policy'
-                value={repliesPolicy}
-                onChange={handleRepliesPolicyChange}
-              >
-                <FormattedMessage
-                  id='lists.replies_policy.none'
-                  defaultMessage='No one'
-                >
-                  {(msg) => <option value='none'>{msg}</option>}
-                </FormattedMessage>
-                <FormattedMessage
-                  id='lists.replies_policy.list'
-                  defaultMessage='Members of the list'
-                >
-                  {(msg) => <option value='list'>{msg}</option>}
-                </FormattedMessage>
-                <FormattedMessage
-                  id='lists.replies_policy.followed'
-                  defaultMessage='Any followed user'
-                >
-                  {(msg) => <option value='followed'>{msg}</option>}
-                </FormattedMessage>
-              </select>
-            </div>
-          </div>
-        </div>
+        <SelectField
+          label={
+            <FormattedMessage
+              id='lists.show_replies_to'
+              defaultMessage='Include replies from list members to'
+            />
+          }
+          value={repliesPolicy}
+          onChange={handleRepliesPolicyChange}
+          id='list_replies_policy'
+        >
+          <FormattedMessage
+            id='lists.replies_policy.none'
+            defaultMessage='No one'
+          >
+            {(msg) => <option value='none'>{msg}</option>}
+          </FormattedMessage>
+          <FormattedMessage
+            id='lists.replies_policy.list'
+            defaultMessage='Members of the list'
+          >
+            {(msg) => <option value='list'>{msg}</option>}
+          </FormattedMessage>
+          <FormattedMessage
+            id='lists.replies_policy.followed'
+            defaultMessage='Any followed user'
+          >
+            {(msg) => <option value='followed'>{msg}</option>}
+          </FormattedMessage>
+        </SelectField>
       </div>
 
       {id && (
diff --git a/app/javascript/mastodon/features/onboarding/profile.tsx b/app/javascript/mastodon/features/onboarding/profile.tsx
index 7e725e97cc..3f1168abe5 100644
--- a/app/javascript/mastodon/features/onboarding/profile.tsx
+++ b/app/javascript/mastodon/features/onboarding/profile.tsx
@@ -16,6 +16,7 @@ import { closeOnboarding } from 'mastodon/actions/onboarding';
 import { Button } from 'mastodon/components/button';
 import { Column } from 'mastodon/components/column';
 import { ColumnHeader } from 'mastodon/components/column_header';
+import { TextAreaField, TextInputField } from 'mastodon/components/form_fields';
 import { Icon } from 'mastodon/components/icon';
 import { LoadingIndicator } from 'mastodon/components/loading_indicator';
 import { me } from 'mastodon/initial_state';
@@ -212,62 +213,47 @@ export const Profile: React.FC<{
           </div>
 
           <div className='fields-group'>
-            <div
-              className={classNames('input with_block_label', {
-                field_with_errors: !!errors?.display_name,
-              })}
-            >
-              <label htmlFor='display_name'>
+            <TextInputField
+              maxLength={30}
+              label={
                 <FormattedMessage
                   id='onboarding.profile.display_name'
                   defaultMessage='Display name'
                 />
-              </label>
-              <span className='hint'>
+              }
+              hint={
                 <FormattedMessage
                   id='onboarding.profile.display_name_hint'
                   defaultMessage='Your full name or your fun name…'
                 />
-              </span>
-              <div className='label_input'>
-                <input
-                  id='display_name'
-                  type='text'
-                  value={displayName}
-                  onChange={handleDisplayNameChange}
-                  maxLength={30}
-                />
-              </div>
-            </div>
+              }
+              value={displayName}
+              onChange={handleDisplayNameChange}
+              hasError={!!errors?.display_name}
+              id='display_name'
+            />
           </div>
 
           <div className='fields-group'>
-            <div
-              className={classNames('input with_block_label', {
-                field_with_errors: !!errors?.note,
-              })}
-            >
-              <label htmlFor='note'>
+            <TextAreaField
+              maxLength={500}
+              label={
                 <FormattedMessage
                   id='onboarding.profile.note'
                   defaultMessage='Bio'
                 />
-              </label>
-              <span className='hint'>
+              }
+              hint={
                 <FormattedMessage
                   id='onboarding.profile.note_hint'
                   defaultMessage='You can @mention other people or #hashtags…'
                 />
-              </span>
-              <div className='label_input'>
-                <textarea
-                  id='note'
-                  value={note}
-                  onChange={handleNoteChange}
-                  maxLength={500}
-                />
-              </div>
-            </div>
+              }
+              value={note}
+              onChange={handleNoteChange}
+              hasError={!!errors?.note}
+              id='note'
+            />
           </div>
 
           <label className='app-form__toggle'>
diff --git a/app/javascript/mastodon/locales/en.json b/app/javascript/mastodon/locales/en.json
index afccb03857..06548fa5f2 100644
--- a/app/javascript/mastodon/locales/en.json
+++ b/app/javascript/mastodon/locales/en.json
@@ -454,6 +454,7 @@
   "footer.source_code": "View source code",
   "footer.status": "Status",
   "footer.terms_of_service": "Terms of service",
+  "form_field.optional": "(optional)",
   "generic.saved": "Saved",
   "getting_started.heading": "Getting started",
   "hashtag.admin_moderation": "Open moderation interface for #{name}",