Skip to content

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

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

/**
 * @file FieldLabel.test.tsx
 * @input Uses vitest, @testing-library/react, FieldLabel component
 * @output Unit tests for FieldLabel component behavior
 * @position Testing; validates FieldLabel.tsx implementation
 *
 * SYNC: When FieldLabel.tsx changes, update tests to match new behavior
 */

import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TestIcon} from '../__tests__/TestIcon';
import {InternationalizationProvider} from '../i18n';
import {FieldLabel} from './FieldLabel';
import {Switch} from '../Switch/Switch';
import {themeProps} from '../utils/themeProps';
import {__resetInteractionModalityForTest} from '../utils/interactionModality';

describe('FieldLabel', () => {
  it('renders label text', () => {
    render(<FieldLabel label="Email" inputID="email-input" />);
    expect(screen.getByText('Email')).toBeInTheDocument();
  });

  it('associates label with input via htmlFor', () => {
    render(<FieldLabel label="Email" inputID="email-input" />);
    const label = screen.getByText('Email').closest('label');
    expect(label).toHaveAttribute('for', 'email-input');
  });

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

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

  it('localizes the required indicator via the i18n provider', () => {
    render(
      <InternationalizationProvider
        locale="fr"
        overrides={{fr: {'@astryx.field.required': 'Obligatoire'}}}>
        <FieldLabel label="Nom" inputID="name-input" isRequired />
      </InternationalizationProvider>,
    );
    expect(screen.getByText(/Obligatoire/)).toBeInTheDocument();
    expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
  });

  it('localizes the optional indicator via the i18n provider', () => {
    render(
      <InternationalizationProvider
        locale="fr"
        overrides={{fr: {'@astryx.field.optional': 'Facultatif'}}}>
        <FieldLabel label="Nom" inputID="name-input" isOptional />
      </InternationalizationProvider>,
    );
    expect(screen.getByText(/Facultatif/)).toBeInTheDocument();
    expect(screen.queryByText(/Optional/)).not.toBeInTheDocument();
  });

  it('shows Optional when both isOptional and isRequired are true', () => {
    render(
      <FieldLabel label="Name" inputID="name-input" isOptional isRequired />,
    );
    expect(screen.getByText(/Optional/)).toBeInTheDocument();
    expect(screen.queryByText(/Required/)).not.toBeInTheDocument();
  });

  it('renders labelIcon when provided', () => {
    render(
      <FieldLabel
        label="Starred"
        inputID="starred-input"
        labelIcon={TestIcon}
      />,
    );
    const svg = document.querySelector('svg');
    expect(svg).toBeInTheDocument();
  });

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

  it('keeps a standalone label as its parent layout item', () => {
    const {container} = render(
      <FieldLabel
        label="Name"
        inputID="name-input"
        className="consumer-label"
        style={{order: 2}}
      />,
    );
    const label = screen.getByText('Name').closest('label');
    expect(label).toHaveClass('consumer-label');
    expect(label).toHaveStyle({order: '2'});
    expect(container.firstElementChild).toBe(label);
  });

  it('renders an info button named after the label, after the label element and outside it', () => {
    render(
      <>
        <FieldLabel
          label="Help"
          inputID="help-input"
          labelTooltip="This is helpful information"
        />
        <input id="help-input" type="text" />
      </>,
    );
    const button = screen.getByRole('button', {name: 'About Help'});
    const label = screen.getByText('Help').closest('label');
    // No button inside a label: a press on it would also activate the control.
    expect(button.closest('label')).toBeNull();
    expect(label?.nextElementSibling).toBe(button);
    expect(button).toHaveAccessibleDescription('This is helpful information');
    // The field's name stays the label alone.
    expect(screen.getByRole('textbox')).toHaveAccessibleName('Help');
  });

  it('keeps a hidden label’s info button reachable by keyboard', () => {
    render(
      <>
        <FieldLabel
          label="Search"
          inputID="search-input"
          isLabelHidden
          labelTooltip="Searches titles only"
        />
        <input id="search-input" type="text" />
      </>,
    );
    expect(screen.getByRole('button', {name: 'About Search'})).toHaveProperty(
      'tabIndex',
      0,
    );
  });

  it('does not render extra icon when labelTooltip is not provided', () => {
    render(<FieldLabel label="Name" inputID="name-input" />);
    // No SVGs should be present when no icons are provided
    expect(document.querySelector('svg')).not.toBeInTheDocument();
  });

  it('renders labelTooltip with Optional indicator together', () => {
    render(
      <FieldLabel
        label="Field"
        inputID="field-input"
        isOptional
        labelTooltip="Help text"
      />,
    );
    expect(screen.getByText(/Optional/)).toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'About Field'}),
    ).toBeInTheDocument();
  });

  describe('labelTooltip under each pointer', () => {
    const originalShowPopover = HTMLElement.prototype.showPopover;
    const originalHidePopover = HTMLElement.prototype.hidePopover;
    const originalMatches = HTMLElement.prototype.matches;
    beforeEach(() => {
      __resetInteractionModalityForTest();
      // jsdom has no Popover API: keep the open state where the test reads it.
      HTMLElement.prototype.showPopover = function (this: HTMLElement) {
        this.setAttribute('popover-open', '');
      };
      HTMLElement.prototype.hidePopover = function (this: HTMLElement) {
        this.removeAttribute('popover-open');
      };
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      (HTMLElement.prototype as any).matches = function (
        this: HTMLElement,
        selector: string,
      ): boolean {
        return selector === ':popover-open'
          ? this.hasAttribute('popover-open')
          : originalMatches.call(this, selector);
      };
    });
    afterEach(() => {
      HTMLElement.prototype.showPopover = originalShowPopover;
      HTMLElement.prototype.hidePopover = originalHidePopover;
      HTMLElement.prototype.matches = originalMatches;
    });

    /** A finger's (or a pen's) tap, in the order a browser dispatches it. */
    const tap = (element: HTMLElement, pointerType = 'touch') => {
      fireEvent.pointerEnter(element, {pointerType});
      fireEvent.pointerDown(element, {pointerType});
      fireEvent.pointerUp(element, {pointerType});
      fireEvent.mouseEnter(element);
      fireEvent.click(element);
    };

    /** The info button after the label. */
    const infoIcon = (labelText: string) =>
      screen.getByRole('button', {name: `About ${labelText}`});

    it('opens the help on a tap of its icon and leaves a checkbox alone', async () => {
      render(
        <>
          <FieldLabel
            label="Notifications"
            inputID="notify"
            labelTooltip="Sends one digest a day"
          />
          <input type="checkbox" id="notify" />
        </>,
      );

      tap(infoIcon('Notifications'));

      await waitFor(() => {
        expect(screen.getByRole('tooltip', {hidden: true})).toHaveAttribute(
          'popover-open',
        );
      });
      // The tap asked for the help, not for the label's control.
      expect(screen.getByRole('checkbox')).not.toBeChecked();
    });

    it('opens the help on a pen tap of its icon and leaves a checkbox alone', async () => {
      render(
        <>
          <FieldLabel
            label="Alerts"
            inputID="alerts"
            labelTooltip="Only for failed runs"
          />
          <input type="checkbox" id="alerts" />
        </>,
      );

      tap(infoIcon('Alerts'), 'pen');

      await waitFor(() => {
        expect(screen.getByRole('tooltip', {hidden: true})).toHaveAttribute(
          'popover-open',
        );
      });
      expect(screen.getByRole('checkbox')).not.toBeChecked();
    });

    it('opens the help on Space on its button and leaves a checkbox alone', async () => {
      const user = userEvent.setup();
      render(
        <>
          <FieldLabel
            label="Digest"
            inputID="digest"
            labelTooltip="One email a week"
          />
          <input type="checkbox" id="digest" />
        </>,
      );

      infoIcon('Digest').focus();
      await user.keyboard(' ');

      await waitFor(() => {
        expect(infoIcon('Digest')).toHaveAttribute('aria-expanded', 'true');
      });
      expect(screen.getByRole('checkbox')).not.toBeChecked();
    });

    it('leaves a Switch alone when its label’s info button is clicked', async () => {
      const user = userEvent.setup();
      const onChange = vi.fn();
      render(
        <Switch
          label="Auto-save"
          labelTooltip="Saves each change"
          value={false}
          onChange={onChange}
        />,
      );

      await user.click(infoIcon('Auto-save'));

      expect(onChange).not.toHaveBeenCalled();
    });

    it('opens the help on a mouse click of its button and leaves a checkbox alone', async () => {
      render(
        <>
          <FieldLabel
            label="Auto-save"
            inputID="autosave"
            labelTooltip="Saves each change as you type"
          />
          <input type="checkbox" id="autosave" />
        </>,
      );

      const icon = infoIcon('Auto-save');
      fireEvent.pointerDown(icon, {pointerType: 'mouse'});
      fireEvent.pointerUp(icon, {pointerType: 'mouse'});
      fireEvent.click(icon);

      await waitFor(() => {
        expect(screen.getByRole('tooltip', {hidden: true})).toHaveAttribute(
          'popover-open',
        );
      });
      // The button sits outside the label, so a click is for its help only.
      expect(screen.getByRole('checkbox')).not.toBeChecked();
    });
  });

  describe('description click forwarding', () => {
    // Renders a real control with the target id so click-forwarding has
    // something to hit, alongside the label whose description forwards clicks.
    function renderWithControl(props: {
      isGroupLabel?: boolean;
      controlType?: string;
      description?: React.ReactNode;
    }) {
      const {isGroupLabel, controlType = 'checkbox', description} = props;
      const onClick = vi.fn();
      render(
        <>
          <input id="ctrl" type={controlType} onClick={onClick} />
          <FieldLabel
            label="Notify"
            inputID="ctrl"
            description={description ?? "We'll email you"}
            descriptionID="ctrl-desc"
            isGroupLabel={isGroupLabel}
          />
        </>,
      );
      return onClick;
    }

    it('forwards a description click to a click-activatable control (checkbox)', async () => {
      const user = userEvent.setup();
      const onClick = renderWithControl({controlType: 'checkbox'});
      await user.click(screen.getByText("We'll email you"));
      expect(onClick).toHaveBeenCalledTimes(1);
    });

    it('focuses (does not click) a text input on description click', async () => {
      const user = userEvent.setup();
      const onClick = renderWithControl({controlType: 'text'});
      await user.click(screen.getByText("We'll email you"));
      // Text inputs focus rather than click — matching native label behavior,
      // so no synthetic click fires but the control receives focus.
      expect(onClick).not.toHaveBeenCalled();
      expect(document.getElementById('ctrl')).toHaveFocus();
    });

    it('does NOT forward description clicks for a group label', async () => {
      const user = userEvent.setup();
      const onClick = renderWithControl({isGroupLabel: true});
      await user.click(screen.getByText("We'll email you"));
      expect(onClick).not.toHaveBeenCalled();
    });

    it('does NOT hijack clicks on interactive content inside the description', async () => {
      const user = userEvent.setup();
      const linkClick = vi.fn();
      const onClick = renderWithControl({
        description: (
          <>
            See our{' '}
            <a href="#terms" onClick={linkClick}>
              terms
            </a>
          </>
        ),
      });
      await user.click(screen.getByRole('link', {name: 'terms'}));
      // The nested link handles its own click; the control is not toggled.
      expect(linkClick).toHaveBeenCalledTimes(1);
      expect(onClick).not.toHaveBeenCalled();
    });

    it('keeps the description a sibling of the label (not nested inside it)', () => {
      renderWithControl({});
      const description = screen.getByText("We'll email you");
      // The description must not live inside the <label> — nesting it there
      // would fold it into the control's accessible name.
      expect(description.closest('label')).toBeNull();
    });
  });

  describe('a control can name its own label target', () => {
    it('composes a passed target onto the field-label one', () => {
      // How CheckboxInput and Switch reach their label: the control spreads
      // its own themeProps in, and both classes end up on the same element,
      // so a theme can style every label or just this kind.
      render(
        <FieldLabel
          {...themeProps('checkbox-label')}
          label="Notify me"
          inputID="notify-input"
        />,
      );
      const label = screen.getByText('Notify me').closest('label');
      expect(label).toHaveClass('astryx-field-label');
      expect(label).toHaveClass('astryx-checkbox-label');
    });

    it('describes no placement of its own', () => {
      // The label cannot know how its caller arranged it, so it says nothing:
      // a `data-layout` here would be a claim that is wrong for at least one
      // caller (Field's horizontal-labels puts a label beside its control),
      // and a consumer could set it untruthfully.
      render(<FieldLabel label="Email" inputID="email-input" />);
      const label = screen.getByText('Email').closest('label');
      expect(label).not.toHaveAttribute('data-layout');
    });
  });
});