Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
26.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Field.test.tsx
 * @input Uses Vitest, Testing Library, StyleX, Field, FormLayoutContext
 * @output Unit tests for Field component behavior
 * @position Testing; validates Field.tsx implementation
 *
 * SYNC: When Field.tsx changes, update tests to match new behavior
 */

import {describe, it, expect, vi, afterEach} from 'vitest';
import {render, screen, waitFor, fireEvent} from '@testing-library/react';
import * as stylex from '@stylexjs/stylex';
import {Field} from './Field';
import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';

const testStyles = stylex.create({
  root: {
    minWidth: '123px',
  },
});

function politeRegion(): HTMLElement | null {
  return document.querySelector('[data-astryx-live-region="polite"]');
}
function assertiveRegion(): HTMLElement | null {
  return document.querySelector('[data-astryx-live-region="assertive"]');
}

afterEach(() => {
  __resetLiveRegionsForTest();
});

describe('Field', () => {
  it.each(['sm', 'md', 'lg'] as const)(
    'provides a half-height overlap for an attached %s control',
    size => {
      render(
        <Field
          label="Username"
          inputID="username"
          status={{type: 'warning', message: 'This username may be taken'}}>
          <div data-size={size}>Control</div>
        </Field>,
      );

      const status = screen.getByText('This username may be taken');
      expect(
        getComputedStyle(status.parentElement!).getPropertyValue(
          '--_field-status-overlap',
        ),
      ).toBe(`calc(var(--size-element-${size}) / 2)`);
    },
  );

  it('layers an attached status behind a custom control', () => {
    render(
      <Field
        label="Username"
        inputID="username"
        status={{type: 'warning', message: 'This username may be taken'}}>
        <input id="username" />
      </Field>,
    );

    const status = screen.getByText('This username may be taken');
    const wrapper = status.parentElement!;

    expect(getComputedStyle(wrapper).isolation).toBe('isolate');
    expect(getComputedStyle(status).position).toBe('relative');
    expect(getComputedStyle(status).zIndex).toBe('-1');
  });

  it('renders with label', () => {
    render(
      <Field label="Email" inputID="email-input">
        <input id="email-input" />
      </Field>,
    );
    expect(screen.getByLabelText('Email')).toBeInTheDocument();
  });

  it('renders description text', () => {
    render(
      <Field
        label="Email"
        inputID="email-input"
        description="We'll never share your email"
        descriptionID="email-desc">
        <input id="email-input" aria-describedby="email-desc" />
      </Field>,
    );
    expect(
      screen.getByText("We'll never share your email"),
    ).toBeInTheDocument();
  });

  it('associates description with correct ID', () => {
    render(
      <Field
        label="Email"
        inputID="email-input"
        description="Description text"
        descriptionID="email-desc">
        <input id="email-input" aria-describedby="email-desc" />
      </Field>,
    );
    const description = screen.getByText('Description text');
    expect(description).toHaveAttribute('id', 'email-desc');
  });

  it('visually hides label when isLabelHidden is true', () => {
    render(
      <Field label="Search" isLabelHidden inputID="search-input">
        <input id="search-input" />
      </Field>,
    );
    const label = screen.getByText('Search');
    expect(label).toBeInTheDocument();
    // Label should still be accessible
    expect(screen.getByLabelText('Search')).toBeInTheDocument();
  });

  it('visually hides description when isLabelHidden is true', () => {
    render(
      <Field
        label="Search"
        isLabelHidden
        description="Search for items"
        inputID="search-input"
        descriptionID="search-desc">
        <input id="search-input" />
      </Field>,
    );
    // Description should still be in the DOM for screen readers
    const description = screen.getByText('Search for items');
    expect(description).toBeInTheDocument();
    // But should have the visually-hidden styles applied
    expect(description.className).toContain('srOnly');
  });

  it('shows label visually by default', () => {
    render(
      <Field label="Email" inputID="email-input">
        <input id="email-input" />
      </Field>,
    );
    const label = screen.getByText('Email');
    expect(label).toBeVisible();
  });

  it('renders a single-control label as a <label> with htmlFor', () => {
    render(
      <Field label="Email" inputID="email-input">
        <input id="email-input" />
      </Field>,
    );
    const labelEl = screen.getByText('Email');
    expect(labelEl.tagName).toBe('LABEL');
    expect(labelEl).toHaveAttribute('for', 'email-input');
  });

  it('renders a group label as a <span> (not <label>) with no htmlFor', () => {
    render(
      <Field
        label="Plan"
        inputID="plan-group"
        labelID="plan-label"
        isGroupLabel>
        <div role="radiogroup" aria-labelledby="plan-label" />
      </Field>,
    );
    const labelEl = screen.getByText('Plan');
    // A group's accessible-name element must not be a literal <label>.
    expect(labelEl.tagName).toBe('SPAN');
    expect(labelEl.closest('label')).toBeNull();
    expect(labelEl).not.toHaveAttribute('for');
    // labelID is applied to the label element and referenced by the group.
    expect(labelEl).toHaveAttribute('id', 'plan-label');
    const group = screen.getByRole('radiogroup', {name: 'Plan'});
    expect(group.getAttribute('aria-labelledby')).toBe(labelEl.id);
  });

  it('forwards ref correctly', () => {
    const ref = vi.fn();
    render(
      <Field ref={ref} label="Name" inputID="name-input">
        <input id="name-input" />
      </Field>,
    );
    expect(ref).toHaveBeenCalledWith(expect.any(HTMLDivElement));
  });

  it('renders description without ID attribute when descriptionID is not provided', () => {
    render(
      <Field label="Email" inputID="email-input" description="Description text">
        <input id="email-input" />
      </Field>,
    );
    const description = screen.getByText('Description text');
    expect(description).toBeInTheDocument();
    expect(description).toHaveAttribute('id', 'email-input-desc');
  });

  it('renders Optional text when isOptional is set', () => {
    render(
      <Field label="Name" inputID="name-input" isOptional>
        <input id="name-input" />
      </Field>,
    );
    expect(screen.getByText('Name')).toBeInTheDocument();
    expect(screen.getByText(/Optional/)).toBeInTheDocument();
  });

  it('renders Required text when isRequired is set', () => {
    render(
      <Field label="Name" inputID="name-input" isRequired>
        <input id="name-input" />
      </Field>,
    );
    expect(screen.getByText('Name')).toBeInTheDocument();
    expect(screen.getByText(/Required/)).toBeInTheDocument();
  });

  it('renders description and Optional text when both are set', () => {
    render(
      <Field
        label="Name"
        inputID="name-input"
        description="Enter your name"
        descriptionID="name-desc"
        isOptional>
        <input id="name-input" aria-describedby="name-desc" />
      </Field>,
    );
    expect(screen.getByText('Enter your name')).toBeInTheDocument();
    expect(screen.getByText(/Optional/)).toBeInTheDocument();
  });

  it('renders description and Required text when both are set', () => {
    render(
      <Field
        label="Name"
        inputID="name-input"
        description="This field is mandatory"
        descriptionID="name-desc"
        isRequired>
        <input id="name-input" aria-describedby="name-desc" />
      </Field>,
    );
    expect(screen.getByText('This field is mandatory')).toBeInTheDocument();
    expect(screen.getByText(/Required/)).toBeInTheDocument();
  });

  it('renders Optional text with bullet separator', () => {
    render(
      <Field label="Name" inputID="name-input" isOptional>
        <input id="name-input" />
      </Field>,
    );
    expect(screen.getByText('Name')).toBeInTheDocument();
    expect(
      screen.getByText('∙', {selector: '[aria-hidden="true"]'}),
    ).toBeInTheDocument();
    expect(screen.getByText(/Optional/)).toBeInTheDocument();
  });

  it('renders tooltip info icon when labelTooltip is provided', () => {
    render(
      <Field label="Help" inputID="help-input" labelTooltip="Helpful info">
        <input id="help-input" />
      </Field>,
    );
    expect(
      screen.getByRole('button', {name: 'About Help'}),
    ).toBeInTheDocument();
  });

  it('does not render tooltip icon when labelTooltip is not provided', () => {
    render(
      <Field label="Name" inputID="name-input">
        <input id="name-input" />
      </Field>,
    );
    expect(document.querySelector('svg')).not.toBeInTheDocument();
  });

  // The status message is announced through the persistent useAnnounce live
  // regions rather than role/aria-live on the (conditionally mounted)
  // FieldStatus element itself — regions born with their content are not
  // reliably announced by assistive technology.
  it('announces error status assertively via the persistent live region', async () => {
    render(
      <Field
        label="Email"
        inputID="email-input"
        status={{type: 'error', message: 'Invalid email'}}>
        <input id="email-input" />
      </Field>,
    );
    expect(screen.getByText('Invalid email')).not.toHaveAttribute('role');
    await waitFor(() => {
      expect(assertiveRegion()).toHaveTextContent('Invalid email');
    });
  });

  it('announces warning status politely via the persistent live region', async () => {
    render(
      <Field
        label="Email"
        inputID="email-input"
        status={{type: 'warning', message: 'Check this'}}>
        <input id="email-input" />
      </Field>,
    );
    expect(screen.getByText('Check this')).not.toHaveAttribute('aria-live');
    await waitFor(() => {
      expect(politeRegion()).toHaveTextContent('Check this');
    });
  });

  // Regression: the status live region must NOT be born together with its
  // content. A message that appears after mount (the common validation flow)
  // has to land in the persistent announce region.
  it('announces a status message that appears after mount', async () => {
    const {rerender} = render(
      <Field label="Email" inputID="email-input">
        <input id="email-input" />
      </Field>,
    );
    expect(assertiveRegion()).toBeNull();

    rerender(
      <Field
        label="Email"
        inputID="email-input"
        status={{type: 'error', message: 'Email is required'}}>
        <input id="email-input" />
      </Field>,
    );
    await waitFor(() => {
      expect(assertiveRegion()).toHaveTextContent('Email is required');
    });
  });

  // The tooltip placement renders no FieldStatus, so Field itself must speak
  // the message; otherwise a screen-reader user is never told it appeared.
  describe('tooltip status placement', () => {
    /** Every non-empty text written into a live region, in order. */
    function recordAnnouncements(): string[] {
      const spoken: string[] = [];
      const observer = new MutationObserver(records => {
        for (const record of records) {
          const target =
            record.target instanceof HTMLElement
              ? record.target
              : record.target.parentElement;
          const text = target
            ?.closest('[data-astryx-live-region]')
            ?.textContent?.trim();
          if (text) {
            spoken.push(text);
          }
        }
      });
      observer.observe(document.body, {
        childList: true,
        characterData: true,
        subtree: true,
      });
      return spoken;
    }

    it('announces a warning that appears after mount, politely', async () => {
      const {rerender} = render(
        <Field label="Email" inputID="email-input" statusVariant="tooltip">
          <input id="email-input" />
        </Field>,
      );
      expect(politeRegion()).toBeNull();

      rerender(
        <Field
          label="Email"
          inputID="email-input"
          statusVariant="tooltip"
          status={{type: 'warning', message: 'Check this'}}>
          <input id="email-input" />
        </Field>,
      );
      // No message box renders for this placement; the text lives only in
      // the live region (and in the member's tooltip, which Field does not own).
      expect(screen.queryByText('Check this')).toBeNull();
      await waitFor(() => {
        expect(politeRegion()).toHaveTextContent('Check this');
      });
      expect(assertiveRegion()).toHaveTextContent('');
    });

    it('announces an error assertively, matching the message box placements', async () => {
      render(
        <Field
          label="Email"
          inputID="email-input"
          statusVariant="tooltip"
          status={{type: 'error', message: 'Email is required'}}>
          <input id="email-input" />
        </Field>,
      );
      await waitFor(() => {
        expect(assertiveRegion()).toHaveTextContent('Email is required');
      });
    });

    it('speaks a message once, and again only when it changes', async () => {
      const spoken = recordAnnouncements();
      const field = (message: string) => (
        <Field
          label="Email"
          inputID="email-input"
          statusVariant="tooltip"
          status={{type: 'warning', message}}>
          <input id="email-input" />
        </Field>
      );
      const {rerender} = render(field('First'));
      await waitFor(() => expect(spoken).toEqual(['First']));

      rerender(field('First'));
      rerender(field('Second'));
      await waitFor(() => expect(spoken).toEqual(['First', 'Second']));
    });

    it.each(['attached', 'detached'] as const)(
      'does not add a second announcement to the %s message box',
      async statusVariant => {
        const spoken = recordAnnouncements();
        render(
          <Field
            label="Email"
            inputID="email-input"
            statusVariant={statusVariant}
            status={{type: 'warning', message: 'Check this'}}>
            <input id="email-input" />
          </Field>,
        );
        await waitFor(() => expect(spoken).toEqual(['Check this']));
        // Give a duplicate announcement's animation frame time to land.
        await new Promise(resolve => setTimeout(resolve, 50));
        expect(spoken).toEqual(['Check this']);
      },
    );

    it('does not announce a status without a message', () => {
      render(
        <Field
          label="Email"
          inputID="email-input"
          statusVariant="tooltip"
          status={{type: 'error'}}>
          <input id="email-input" />
        </Field>,
      );
      expect(assertiveRegion()).toBeNull();
      expect(politeRegion()).toBeNull();
    });
  });

  it('auto-generates description ID as {inputID}-desc when descriptionID is not provided', () => {
    render(
      <Field label="Email" inputID="my-input" description="Help text">
        <input id="my-input" />
      </Field>,
    );
    expect(screen.getByText('Help text')).toHaveAttribute(
      'id',
      'my-input-desc',
    );
  });

  it('auto-generates status message ID as {inputID}-status when messageID is not provided', () => {
    render(
      <Field
        label="Email"
        inputID="my-input"
        status={{type: 'error', message: 'Required'}}>
        <input id="my-input" />
      </Field>,
    );
    expect(screen.getByText('Required')).toHaveAttribute(
      'id',
      'my-input-status',
    );
  });

  it('warns when isOptional and isRequired are both set', () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    render(
      <Field label="Name" inputID="name-input" isOptional isRequired>
        <input id="name-input" />
      </Field>,
    );
    expect(warnSpy).toHaveBeenCalledWith(
      'Field: isOptional and isRequired are mutually exclusive. isOptional takes precedence.',
    );
    warnSpy.mockRestore();
  });

  // ─── width prop (#2755) ───────────────────────────────────────────────

  describe('width prop', () => {
    it('applies a string width to the outer field root', () => {
      render(
        <Field
          label="Name"
          inputID="name-input"
          width="100%"
          data-testid="field">
          <input id="name-input" data-testid="control" />
        </Field>,
      );
      const field = screen.getByTestId('field');
      // StyleX compiles the dynamic width to an inline CSS custom property.
      expect(field.getAttribute('style')).toContain('100%');
      expect(field.className).toContain('dynamicStyles.width');
    });

    it('applies a numeric width (treated as pixels)', () => {
      render(
        <Field
          label="Name"
          inputID="name-input"
          width={240}
          data-testid="field">
          <input id="name-input" />
        </Field>,
      );
      const field = screen.getByTestId('field');
      expect(field.getAttribute('style')).toContain('240');
    });

    it('does not size the inner control element', () => {
      render(
        <Field
          label="Name"
          inputID="name-input"
          width="100%"
          data-testid="field">
          <input id="name-input" data-testid="control" />
        </Field>,
      );
      const control = screen.getByTestId('control');
      // The width var lives on the field root, not the control itself.
      expect(control.getAttribute('style') ?? '').not.toContain('100%');
    });

    it('omits width styling when the prop is not provided', () => {
      render(
        <Field label="Name" inputID="name-input" data-testid="field">
          <input id="name-input" />
        </Field>,
      );
      const field = screen.getByTestId('field');
      expect(field.className).not.toContain('dynamicStyles.width');
    });
  });

  // ─── Horizontal-labels context ────────────────────────────────────────

  describe('horizontal-labels layout', () => {
    const horizontalLabelsWrapper = ({
      children,
    }: {
      children: React.ReactNode;
    }) => (
      <FormLayoutContext value={{direction: 'horizontal-labels'}}>
        {children}
      </FormLayoutContext>
    );

    it('composes root props without letting callers replace layout semantics', () => {
      const onClick = vi.fn();
      const expectedXstyleClass = stylex.props(testStyles.root).className;
      if (expectedXstyleClass == null) {
        throw new Error('Expected the test xstyle to produce a class name.');
      }

      render(
        <Field
          label="Name"
          inputID="name-input"
          data-testid="field"
          data-layout="consumer"
          data-owner="consumer"
          className="consumer-class"
          style={{width: '321px'}}
          xstyle={testStyles.root}
          onClick={onClick}>
          <input id="name-input" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );

      const field = screen.getByTestId('field');
      expect(field).toHaveClass('astryx-field', 'consumer-class');
      expect(field).toHaveClass(expectedXstyleClass);
      expect(field).toHaveAttribute('data-layout', 'horizontal-labels');
      expect(field).toHaveAttribute('data-owner', 'consumer');
      expect(field).toHaveStyle({width: '321px'});
      fireEvent.click(field);
      expect(onClick).toHaveBeenCalledOnce();
    });

    it('visually hides the description in horizontal-label mode when the label is hidden', () => {
      render(
        <Field
          label="Search"
          inputID="search-input"
          isLabelHidden
          description="Search for items"
          descriptionID="search-desc">
          <input id="search-input" aria-describedby="search-desc" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );

      const description = screen.getByText('Search for items');
      expect(description.className).toContain('visuallyHidden');
      expect(description).toHaveAttribute('id', 'search-desc');
    });

    it('applies display:contents when in horizontal-labels context', () => {
      const {container} = render(
        <Field label="Name" inputID="name-input">
          <input id="name-input" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );
      const field = container.firstChild as HTMLElement;
      expect(field.className).toContain('horizontalLabels');
    });

    it('renders label and input as direct grid children via display:contents', () => {
      render(
        <Field label="Name" inputID="name-input" data-testid="field">
          <input id="name-input" data-testid="name" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );
      const field = screen.getByTestId('field');
      // With display:contents, the field's children participate in the parent grid.
      // The field should contain: label alignment wrapper + input wrapper div
      const label = screen.getByText('Name');
      expect(label.tagName).toBe('LABEL');
      expect(field.contains(label)).toBe(true);
      expect(field.contains(screen.getByTestId('name'))).toBe(true);
    });

    it('groups description with input in column 2', () => {
      render(
        <Field
          label="Email"
          inputID="email-input"
          description="We won't share it"
          descriptionID="email-desc"
          data-testid="field">
          <input id="email-input" data-testid="email" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );
      const descEl = screen.getByText("We won't share it");
      const inputEl = screen.getByTestId('email');
      // Both description and input should be inside the same wrapper div (column 2)
      expect(descEl.parentElement).toBe(inputEl.parentElement);
    });

    it('groups status message with input in column 2', () => {
      render(
        <Field
          label="Email"
          inputID="email-input"
          status={{type: 'error', message: 'Required'}}
          data-testid="field">
          <input id="email-input" data-testid="email" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );
      const statusEl = screen.getByText('Required');
      const inputEl = screen.getByTestId('email');
      // Both status and input should be inside the same wrapper div (column 2)
      expect(statusEl.parentElement).toBe(inputEl.parentElement);
    });

    it('does not apply display:contents in vertical context', () => {
      const {container} = render(
        <Field label="Name" inputID="name-input">
          <input id="name-input" />
        </Field>,
      );
      const field = container.firstChild as HTMLElement;
      expect(field.className).not.toContain('horizontalLabels');
      expect(field.className).toContain('container');
    });

    it('wraps label in alignment div with top padding', () => {
      render(
        <Field label="Name" inputID="name-input" data-testid="field">
          <input id="name-input" />
        </Field>,
        {wrapper: horizontalLabelsWrapper},
      );
      const field = screen.getByTestId('field');
      // First child should be the label alignment wrapper
      const labelWrapper = field.children[0] as HTMLElement;
      expect(labelWrapper.tagName).toBe('DIV');
      expect(labelWrapper.className).toContain('horizontalLabelAlign');
      // Label should be inside
      expect(labelWrapper.querySelector('label')).not.toBeNull();
    });
  });

  describe('local stacking ownership', () => {
    // Input wrappers paint their surface above the attached status message
    // box through a local z-index, so that layer must be contained by a
    // Field-owned isolation boundary. Otherwise a detached or tooltip field
    // — whose input wrapper renders outside the attached-status wrapper —
    // competes with page-level stacking (AppShell sticky header, later
    // siblings) and can paint over unrelated chrome (#5689).
    it.each(['attached', 'detached', 'tooltip'] as const)(
      'isolates the field surface for the %s status variant',
      variant => {
        render(
          <Field
            label="Name"
            inputID="name-input"
            status={{type: 'error', message: 'Required'}}
            statusVariant={variant}
            data-testid="field">
            <input id="name-input" data-testid="control" />
          </Field>,
        );
        const field = screen.getByTestId('field');
        // The Field root is the isolation owner: it stays at its normal
        // parent paint level (it carries no positioning or z-index of its
        // own) while containing every local layer — the input wrapper's 1
        // and the attached status -1.
        expect(getComputedStyle(field).isolation).toBe('isolate');
        // Unpositioned and unranked — the owner never competes itself.
        expect(getComputedStyle(field).zIndex).toBe('');
      },
    );

    it('keeps a custom control without status isolated too', () => {
      render(
        <Field label="Name" inputID="name-input" data-testid="field">
          <input id="name-input" data-testid="control" />
        </Field>,
      );
      const field = screen.getByTestId('field');
      expect(getComputedStyle(field).isolation).toBe('isolate');
    });
  });
});

describe('Field in a narrow row', () => {
  it('lets a row shrink the field below its control width', () => {
    const {container} = render(
      <Field label="Search" inputID="search">
        <input id="search" />
      </Field>,
    );
    const root = container.querySelector('.astryx-field')!;
    expect(getComputedStyle(root).minWidth).toBe('0');
  });

  it('keeps an explicit width, which a row may still shrink', () => {
    const {container} = render(
      <Field label="Search" inputID="search" width={240}>
        <input id="search" />
      </Field>,
    );
    const root = container.querySelector('.astryx-field')!;
    expect(root.getAttribute('style')).toContain('240');
    expect(getComputedStyle(root).minWidth).toBe('0');
  });

  it('leaves horizontal-labels mode (display: contents) untouched', () => {
    const {container} = render(
      <FormLayoutContext value={{direction: 'horizontal-labels'}}>
        <Field label="Name" inputID="name">
          <input id="name" />
        </Field>
      </FormLayoutContext>,
    );
    const root = container.firstChild as HTMLElement;
    expect(getComputedStyle(root).display).toBe('contents');
    expect(getComputedStyle(root).minWidth).not.toBe('0');
  });
});