More Form elements

Author: Pigna

src/components/Form/ConditionalField/ConditionalField.module.scss

@@ -0,0 +1,7 @@
+.keepMounted {
+  /* Wrapper used only when keepMounted=true */
+}
+
+.hidden {
+  display: none;
+}

src/components/Form/ConditionalField/ConditionalField.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { ConditionalField } from './ConditionalField';
+import { Checkbox } from '../Checkbox';
+import { Select } from '../Select';
+import { Input } from '../Input';
+import { FormGroup } from '../FormGroup';
+
+const meta: Meta<typeof ConditionalField> = {
+  title: 'Form/ConditionalField',
+  component: ConditionalField,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof ConditionalField>;
+
+/** Show an extra field when a checkbox is checked. */
+export const CheckboxDriven: Story = {
+  render: function Example() {
+    const [hasAlias, setHasAlias] = useState(false);
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <Checkbox
+          label="I go by a different name"
+          checked={hasAlias}
+          onChange={(e) => setHasAlias(e.target.checked)}
+        />
+        <ConditionalField show={hasAlias}>
+          <Input label="Preferred name" placeholder="e.g. Alex" />
+        </ConditionalField>
+      </div>
+    );
+  },
+};
+
+/** Show a group of fields based on a select value. */
+export const SelectDriven: Story = {
+  render: function Example() {
+    const [deliveryType, setDeliveryType] = useState('');
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <Select
+          label="Delivery method"
+          placeholder="Choose…"
+          options={[
+            { value: 'pickup', label: 'Store pickup' },
+            { value: 'delivery', label: 'Home delivery' },
+          ]}
+          value={deliveryType}
+          onChange={(e) => setDeliveryType(e.target.value)}
+        />
+        <ConditionalField show={deliveryType === 'delivery'}>
+          <FormGroup title="Delivery Address">
+            <Input label="Street" />
+            <Input label="City" />
+            <Input label="Postal code" />
+          </FormGroup>
+        </ConditionalField>
+      </div>
+    );
+  },
+};
+
+/**
+ * With `keepMounted`, the hidden content stays in the DOM (aria-hidden).
+ * Useful when you need to preserve controlled state across visibility toggles.
+ */
+export const KeepMounted: Story = {
+  render: function Example() {
+    const [show, setShow] = useState(false);
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <Checkbox
+          label="Show secondary contact (keepMounted)"
+          checked={show}
+          onChange={(e) => setShow(e.target.checked)}
+        />
+        <ConditionalField show={show} keepMounted>
+          <Input label="Secondary email" placeholder="backup@example.com" />
+        </ConditionalField>
+      </div>
+    );
+  },
+};

src/components/Form/ConditionalField/ConditionalField.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { ConditionalField } from './ConditionalField';
+
+describe('ConditionalField', () => {
+  it('renders children when show is true', () => {
+    render(
+      <ConditionalField show>
+        <span data-testid="content">hello</span>
+      </ConditionalField>,
+    );
+    expect(screen.getByTestId('content')).toBeInTheDocument();
+  });
+
+  it('does not render children when show is false (default unmount)', () => {
+    render(
+      <ConditionalField show={false}>
+        <span data-testid="content">hello</span>
+      </ConditionalField>,
+    );
+    expect(screen.queryByTestId('content')).not.toBeInTheDocument();
+  });
+
+  it('keeps children in DOM when keepMounted and show is false', () => {
+    render(
+      <ConditionalField show={false} keepMounted>
+        <span data-testid="content">hello</span>
+      </ConditionalField>,
+    );
+    expect(screen.getByTestId('content')).toBeInTheDocument();
+  });
+
+  it('sets aria-hidden on wrapper when keepMounted and hidden', () => {
+    const { container } = render(
+      <ConditionalField show={false} keepMounted>
+        <span>inner</span>
+      </ConditionalField>,
+    );
+    expect(container.firstChild).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('does not set aria-hidden when keepMounted and visible', () => {
+    const { container } = render(
+      <ConditionalField show keepMounted>
+        <span>inner</span>
+      </ConditionalField>,
+    );
+    expect(container.firstChild).not.toHaveAttribute('aria-hidden');
+  });
+
+  it('renders nothing (null) when show is false without keepMounted', () => {
+    const { container } = render(
+      <ConditionalField show={false}>
+        <span>inner</span>
+      </ConditionalField>,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+});

src/components/Form/ConditionalField/ConditionalField.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+import styles from './ConditionalField.module.scss';
+
+export interface ConditionalFieldProps {
+  /** When true, children are shown. When false, they are hidden (or unmounted). */
+  show: boolean;
+  /**
+   * When true, children remain in the DOM but are visually hidden when `show` is false.
+   * Useful for preserving controlled input state across visibility toggles.
+   * @default false
+   */
+  keepMounted?: boolean;
+  /** Additional class name for the wrapper element (only rendered when keepMounted). */
+  className?: string;
+  children: ReactNode;
+}
+
+/**
+ * Conditionally shows or hides content based on a boolean expression.
+ *
+ * By default, children are **unmounted** when `show` is false — this is the
+ * accessible default (hidden content is not in the DOM or focus order).
+ *
+ * Set `keepMounted` to preserve DOM state (e.g. controlled inputs that must
+ * retain their value while hidden).
+ *
+ * @example
+ * ```tsx
+ * // Unmounts when condition is false (default)
+ * <ConditionalField show={country === 'us'}>
+ *   <Input label="State" />
+ * </ConditionalField>
+ *
+ * // Keeps mounted but visually hidden
+ * <ConditionalField show={hasBillingAddress} keepMounted>
+ *   <FormGroup title="Billing Address">...</FormGroup>
+ * </ConditionalField>
+ * ```
+ */
+export function ConditionalField({
+  show,
+  keepMounted = false,
+  className,
+  children,
+}: ConditionalFieldProps) {
+  if (keepMounted) {
+    const wrapperClasses = [styles.keepMounted, !show ? styles.hidden : '', className]
+      .filter(Boolean)
+      .join(' ');
+    return (
+      <div className={wrapperClasses} aria-hidden={!show || undefined} inert={!show || undefined}>
+        {children}
+      </div>
+    );
+  }
+
+  return show ? <>{children}</> : null;
+}

src/components/Form/ConditionalField/index.ts

@@ -0,0 +1,2 @@
+export { ConditionalField } from './ConditionalField';
+export type { ConditionalFieldProps } from './ConditionalField';

src/components/Form/FormGroup/FormGroup.module.scss

@@ -0,0 +1,30 @@
+@use '../../../styles/mixins' as *;
+
+.group {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  padding: var(--space-5) var(--space-6);
+  margin: 0;
+  font-family: var(--font-family);
+}
+
+.legend {
+  padding: 0 var(--space-2);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-semibold);
+  color: var(--color-text-primary);
+  line-height: var(--line-height-normal);
+}
+
+.description {
+  margin: 0 0 var(--space-4);
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+  line-height: var(--line-height-normal);
+}
+
+.fields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}

src/components/Form/FormGroup/FormGroup.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { FormGroup } from './FormGroup';
+import { Input } from '../Input';
+import { Select } from '../Select';
+
+const meta: Meta<typeof FormGroup> = {
+  title: 'Form/FormGroup',
+  component: FormGroup,
+  tags: ['autodocs'],
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj<typeof FormGroup>;
+
+/** A basic group of related fields with a legend. */
+export const Default: Story = {
+  render: () => (
+    <FormGroup title="Personal Information">
+      <Input label="First name" placeholder="Jane" />
+      <Input label="Last name" placeholder="Doe" />
+    </FormGroup>
+  ),
+};
+
+/** With an optional description below the legend. */
+export const WithDescription: Story = {
+  render: () => (
+    <FormGroup title="Address" description="Enter your shipping address.">
+      <Input label="Street" placeholder="123 Main St" />
+      <Input label="City" placeholder="Amsterdam" />
+      <Select
+        label="Country"
+        options={[
+          { value: 'nl', label: 'Netherlands' },
+          { value: 'de', label: 'Germany' },
+          { value: 'us', label: 'United States' },
+        ]}
+      />
+    </FormGroup>
+  ),
+};

src/components/Form/FormGroup/FormGroup.test.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { FormGroup } from './FormGroup';
+
+describe('FormGroup', () => {
+  it('renders a fieldset with legend', () => {
+    render(<FormGroup title="Personal Info"><input /></FormGroup>);
+    expect(screen.getByRole('group', { name: 'Personal Info' })).toBeInTheDocument();
+  });
+
+  it('renders legend text', () => {
+    render(<FormGroup title="Address"><input /></FormGroup>);
+    expect(screen.getByText('Address')).toBeInTheDocument();
+  });
+
+  it('renders description when provided', () => {
+    render(
+      <FormGroup title="Settings" description="Adjust your preferences">
+        <input />
+      </FormGroup>,
+    );
+    expect(screen.getByText('Adjust your preferences')).toBeInTheDocument();
+  });
+
+  it('does not render description when omitted', () => {
+    render(<FormGroup title="Settings"><input /></FormGroup>);
+    expect(screen.queryByRole('paragraph')).not.toBeInTheDocument();
+  });
+
+  it('renders children inside the fields wrapper', () => {
+    render(
+      <FormGroup title="Test">
+        <input data-testid="child-input" />
+      </FormGroup>,
+    );
+    expect(screen.getByTestId('child-input')).toBeInTheDocument();
+  });
+
+  it('forwards className to fieldset', () => {
+    const { container } = render(
+      <FormGroup title="Test" className="custom">
+        <input />
+      </FormGroup>,
+    );
+    expect(container.querySelector('fieldset')).toHaveClass('custom');
+  });
+});

src/components/Form/FormGroup/FormGroup.tsx

@@ -0,0 +1,43 @@
+import type { FieldsetHTMLAttributes, Ref } from 'react';
+import styles from './FormGroup.module.scss';
+
+export interface FormGroupProps extends FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** Ref forwarded to the `<fieldset>`. */
+  ref?: Ref<HTMLFieldSetElement>;
+  /** Legend text — displayed as the group heading. */
+  title: string;
+  /** Optional description rendered below the legend. */
+  description?: string;
+}
+
+/**
+ * Semantic grouping of related form controls using `<fieldset>` + `<legend>`.
+ *
+ * Use inside a `<FormSection>` to build structured multi-group forms.
+ *
+ * @example
+ * ```tsx
+ * <FormGroup title="Personal Information" description="Required fields are marked *">
+ *   <Input label="First name" required />
+ *   <Input label="Last name" required />
+ * </FormGroup>
+ * ```
+ */
+export function FormGroup({
+  title,
+  description,
+  children,
+  className,
+  ref,
+  ...rest
+}: FormGroupProps) {
+  const classNames = [styles.group, className].filter(Boolean).join(' ');
+
+  return (
+    <fieldset ref={ref} className={classNames} {...rest}>
+      <legend className={styles.legend}>{title}</legend>
+      {description && <p className={styles.description}>{description}</p>}
+      <div className={styles.fields}>{children}</div>
+    </fieldset>
+  );
+}

src/components/Form/FormGroup/index.ts

@@ -0,0 +1,2 @@
+export { FormGroup } from './FormGroup';
+export type { FormGroupProps } from './FormGroup';