Skip to content

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

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

/**
 * @file TransferListSelector.test.tsx
 * @input Uses TransferListSelector, React state, Vitest, and Testing Library
 * @output Unit coverage for immediate and staged commits, uncontrolled dismissal, synchronization, disabled states, defaults, and prop forwarding
 * @position Lab component test; validates the TransferListSelector public contract
 *
 * SYNC: When TransferListSelector.tsx behavior changes, update this test.
 */

import {Profiler, useMemo, useRef, useState} from 'react';
import {afterAll, beforeEach, describe, expect, it, vi} from 'vitest';
import {
  fireEvent,
  render,
  screen,
  waitFor,
  within,
} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {
  TransferListSelector,
  type TransferListSelectorProps,
} from './TransferListSelector';
import type {TransferListOption} from './TransferList';
import {createReorderable} from '@astryxdesign/core';

type Column = 'name' | 'owner' | 'status' | 'updated';

const OPTIONS: ReadonlyArray<TransferListOption<Column>> = [
  {value: 'name', label: 'Name'},
  {value: 'owner', label: 'Owner'},
  {value: 'status', label: 'Status'},
  {value: 'updated', label: 'Updated'},
];

const hidden = {hidden: true} as const;
const originalMatches = HTMLElement.prototype.matches;

beforeEach(() => {
  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
    this.setAttribute('popover-open', '');
    const event = new Event('toggle');
    Object.defineProperty(event, 'newState', {value: 'open'});
    this.dispatchEvent(event);
  });
  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
    this.removeAttribute('popover-open');
    const event = new Event('toggle');
    Object.defineProperty(event, 'newState', {value: 'closed'});
    this.dispatchEvent(event);
  });
  Object.defineProperty(HTMLElement.prototype, 'matches', {
    configurable: true,
    value: function (this: HTMLElement, selector: string): boolean {
      if (selector === ':popover-open') {
        return this.hasAttribute('popover-open');
      }
      return originalMatches.call(this, selector);
    },
  });
});

afterAll(() => {
  Object.defineProperty(HTMLElement.prototype, 'matches', {
    configurable: true,
    value: originalMatches,
  });
});

type HarnessProps = {
  initialValue?: readonly Column[];
  onCommit: (value: readonly Column[]) => void;
  /** The owner's reorderable object's `isReorderable`. */
  isMovable?: (value: Column) => boolean;
  selectorProps?: Partial<
    Omit<
      TransferListSelectorProps<Column>,
      'label' | 'options' | 'value' | 'onChange'
    >
  >;
};

function Harness({
  initialValue = ['name', 'status'],
  onCommit,
  selectorProps,
  isMovable,
}: HarnessProps) {
  const [value, setValue] = useState<readonly Column[]>(initialValue);
  const valueRef = useRef(value);
  valueRef.current = value;
  // The owner's reorder: each move it is handed applies to its value.
  const reorderable = useMemo(
    () =>
      createReorderable<Column>({
        onReorder: ({key, to}) => {
          const rest = valueRef.current.filter(item => item !== key);
          const next = [...rest.slice(0, to), key, ...rest.slice(to)];
          onCommit(next);
          setValue(next);
        },
        isReorderable: isMovable,
      }),
    [isMovable, onCommit],
  );

  return (
    <>
      <output data-testid="applied-value">{JSON.stringify(value)}</output>
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={value}
        onChange={nextValue => {
          onCommit(nextValue);
          setValue(nextValue);
        }}
        reorderable={reorderable}
        {...selectorProps}
      />
    </>
  );
}

async function openSelector(
  name = 'Visible fields',
): Promise<HTMLButtonElement> {
  const trigger = screen.getByRole('combobox', {
    name,
  }) as HTMLButtonElement;
  fireEvent.keyDown(trigger, {key: 'ArrowDown'});
  await waitFor(() => {
    expect(trigger).toHaveAttribute('aria-expanded', 'true');
  });
  return trigger;
}

/** The selector moves the focus into its panel once open; wait for it. */
async function waitForPanelFocus(trigger: HTMLElement): Promise<void> {
  await waitFor(() => {
    expect(document.activeElement).not.toBe(document.body);
    expect(document.activeElement).not.toBe(trigger);
  });
}

describe('TransferListSelector', () => {
  it('commits each edit immediately by default and renders no footer', async () => {
    const user = userEvent.setup();
    const onCommit = vi.fn();
    const changeAction = vi.fn();
    render(<Harness onCommit={onCommit} selectorProps={{changeAction}} />);

    const trigger = await openSelector();
    const dialog = screen.getByRole('dialog', {
      name: 'Visible fields',
      ...hidden,
    });
    expect(
      within(dialog).queryByRole('button', {name: 'Apply', hidden: true}),
    ).not.toBeInTheDocument();
    expect(
      within(dialog).queryByRole('button', {name: 'Cancel', hidden: true}),
    ).not.toBeInTheDocument();

    await user.click(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    );

    expect(onCommit).toHaveBeenCalledOnce();
    expect(onCommit).toHaveBeenCalledWith(['name', 'status', 'owner']);
    await waitFor(() => {
      expect(changeAction).toHaveBeenCalledOnce();
    });
    expect(changeAction).toHaveBeenCalledWith(['name', 'status', 'owner']);
    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status","owner"]',
    );
    expect(trigger).toHaveTextContent('3 selected');
    expect(trigger).toHaveAttribute('aria-expanded', 'true');

    const popover = dialog.closest('[popover]');
    expect(popover).not.toBeNull();
    popover?.removeAttribute('popover-open');
    const dismissEvent = new Event('toggle');
    Object.defineProperty(dismissEvent, 'newState', {value: 'closed'});
    fireEvent(popover as HTMLElement, dismissEvent);
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'false');
    });

    await openSelector();
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();
    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status","owner"]',
    );
  });

  it('discards a staged draft whenever commit behavior changes', async () => {
    const user = userEvent.setup();
    const onChange = vi.fn();
    const view = render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'status']}
        onChange={onChange}
        commitBehavior="staged"
      />,
    );
    await openSelector();

    await user.click(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    );
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'status']}
        onChange={onChange}
        commitBehavior="immediate"
      />,
    );
    expect(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    ).toBeInTheDocument();
    expect(onChange).not.toHaveBeenCalled();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'status']}
        onChange={onChange}
        commitBehavior="staged"
      />,
    );
    await waitFor(() => {
      expect(
        screen.getByRole('button', {name: 'Add Owner', ...hidden}),
      ).toBeInTheDocument();
    });
    expect(
      screen.getByRole('button', {name: 'Remove Name', ...hidden}),
    ).toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'Remove Status', ...hidden}),
    ).toBeInTheDocument();
    expect(onChange).not.toHaveBeenCalled();
  });

  it('keeps edits in a staged draft and commits a changed ordered copy once', async () => {
    const user = userEvent.setup();
    const onCommit = vi.fn();
    const changeAction = vi.fn();
    render(
      <Harness
        onCommit={onCommit}
        selectorProps={{commitBehavior: 'staged', changeAction}}
      />,
    );

    const trigger = await openSelector();
    await user.click(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    );

    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status"]',
    );
    expect(trigger).toHaveTextContent('2 selected');
    expect(onCommit).not.toHaveBeenCalled();

    await user.click(screen.getByRole('button', {name: 'Apply', ...hidden}));

    expect(onCommit).toHaveBeenCalledOnce();
    expect(onCommit).toHaveBeenCalledWith(['name', 'status', 'owner']);
    await waitFor(() => {
      expect(changeAction).toHaveBeenCalledOnce();
    });
    expect(changeAction).toHaveBeenCalledWith(['name', 'status', 'owner']);
    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status","owner"]',
    );
    expect(trigger).toHaveTextContent('3 selected');
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
  });

  it('reorders a staged draft through its own reorder object: Cancel drops the move with the draft, Apply commits it', async () => {
    const user = userEvent.setup();
    const onCommit = vi.fn();
    render(
      <Harness
        initialValue={['name', 'status', 'updated']}
        onCommit={onCommit}
        selectorProps={{commitBehavior: 'staged'}}
      />,
    );
    await waitForPanelFocus(await openSelector());
    screen.getByRole('button', {name: 'Reorder Name', ...hidden}).focus();
    await user.keyboard('{Enter}{ArrowDown}{Escape}');
    expect(onCommit).not.toHaveBeenCalled();
    await user.click(screen.getByRole('button', {name: 'Cancel', ...hidden}));
    expect(onCommit).not.toHaveBeenCalled();
    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status","updated"]',
    );

    await waitForPanelFocus(await openSelector());
    screen.getByRole('button', {name: 'Reorder Name', ...hidden}).focus();
    await user.keyboard('{Enter}{ArrowDown}{Escape}');
    await user.click(screen.getByRole('button', {name: 'Apply', ...hidden}));
    expect(onCommit).toHaveBeenCalledOnce();
    expect(onCommit).toHaveBeenCalledWith(['status', 'name', 'updated']);
  });

  it('keeps in place the values the owner\u2019s isReorderable rejects, and hands immediate moves to the owner at once', async () => {
    const user = userEvent.setup();
    const onCommit = vi.fn();
    render(
      <Harness
        initialValue={['owner', 'name', 'status']}
        onCommit={onCommit}
        isMovable={value => value !== 'owner'}
      />,
    );
    await waitForPanelFocus(await openSelector());
    expect(
      screen.queryByRole('button', {name: 'Reorder Owner', ...hidden}),
    ).toBeNull();
    screen.getByRole('button', {name: 'Reorder Status', ...hidden}).focus();
    await user.keyboard('{Enter}{ArrowUp}{ArrowUp}{Escape}');
    // Owner leads the list, so Status stops below it.
    expect(onCommit).toHaveBeenCalledOnce();
    expect(onCommit).toHaveBeenCalledWith(['owner', 'status', 'name']);
  });

  it('closes unchanged Apply without calling onChange or changeAction', async () => {
    const user = userEvent.setup();
    const onChange = vi.fn();
    const changeAction = vi.fn();
    render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'status']}
        onChange={onChange}
        changeAction={changeAction}
        commitBehavior="staged"
      />,
    );

    const trigger = await openSelector();
    await user.click(screen.getByRole('button', {name: 'Apply', ...hidden}));

    expect(onChange).not.toHaveBeenCalled();
    expect(changeAction).not.toHaveBeenCalled();
    expect(trigger).toHaveAttribute('aria-expanded', 'false');
  });

  it('discards drafts after Cancel, Escape, and light dismiss', async () => {
    const user = userEvent.setup();
    const onCommit = vi.fn();
    render(
      <Harness
        onCommit={onCommit}
        selectorProps={{commitBehavior: 'staged'}}
      />,
    );

    let trigger = await openSelector();
    await user.click(
      screen.getByRole('button', {name: 'Remove Name', ...hidden}),
    );
    await user.click(screen.getByRole('button', {name: 'Cancel', ...hidden}));
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'false');
    });

    trigger = await openSelector();
    expect(
      screen.getByRole('button', {name: 'Remove Name', ...hidden}),
    ).toBeInTheDocument();
    await user.click(
      screen.getByRole('button', {name: 'Remove Status', ...hidden}),
    );
    await user.keyboard('{Escape}');
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'false');
    });

    trigger = await openSelector();
    expect(
      screen.getByRole('button', {name: 'Remove Status', ...hidden}),
    ).toBeInTheDocument();
    await user.click(
      screen.getByRole('button', {name: 'Remove Name', ...hidden}),
    );

    const popover = screen
      .getByRole('dialog', {name: 'Visible fields', ...hidden})
      .closest('[popover]');
    expect(popover).not.toBeNull();
    popover?.removeAttribute('popover-open');
    const dismissEvent = new Event('toggle');
    Object.defineProperty(dismissEvent, 'newState', {value: 'closed'});
    fireEvent(popover as HTMLElement, dismissEvent);
    await waitFor(() => {
      expect(trigger).toHaveAttribute('aria-expanded', 'false');
    });

    await openSelector();
    expect(
      screen.getByRole('button', {name: 'Remove Name', ...hidden}),
    ).toBeInTheDocument();
    expect(screen.getByTestId('applied-value')).toHaveTextContent(
      '["name","status"]',
    );
    expect(onCommit).not.toHaveBeenCalled();
  });

  it('syncs differing applied values without clearing a dirty draft for equal arrays', async () => {
    const user = userEvent.setup();
    const onChange = vi.fn();
    const view = render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'status']}
        onChange={onChange}
        commitBehavior="staged"
      />,
    );
    await openSelector();

    await user.click(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    );
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={[...(['name', 'status'] as const)]}
        onChange={onChange}
        commitBehavior="staged"
      />,
    );
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['owner', 'updated']}
        onChange={onChange}
        commitBehavior="staged"
      />,
    );
    await waitFor(() => {
      expect(
        screen.getByRole('button', {name: 'Remove Updated', ...hidden}),
      ).toBeInTheDocument();
    });
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'Add Name', ...hidden}),
    ).toBeInTheDocument();
  });

  it('defaults the trigger label to the applied selected count', () => {
    render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name', 'owner', 'updated']}
        onChange={() => {}}
      />,
    );

    expect(
      screen.getByRole('combobox', {name: 'Visible fields'}),
    ).toHaveTextContent('3 selected');
  });

  it('marks list controls disabled without the native attribute, keeping focus, but never when merely busy', async () => {
    const user = userEvent.setup();
    const onChange = vi.fn();
    const view = render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={onChange}
        hasSearch
      />,
    );
    await openSelector();
    const dialog = screen.getByRole('dialog', {
      name: 'Visible fields',
      ...hidden,
    });
    const addStatus = within(dialog).getByRole('button', {
      name: 'Add Status',
      hidden: true,
    });
    addStatus.focus();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={onChange}
        isDisabled
        hasSearch
      />,
    );
    const fieldset = dialog.querySelector('fieldset');
    expect(fieldset).not.toBeNull();
    // A focusable disabled group: no native `disabled`, which would blur the
    // focused control; aria-disabled marks every control in it.
    expect(fieldset).not.toHaveAttribute('disabled');
    expect(fieldset).toHaveAttribute('aria-disabled', 'true');
    expect(addStatus).toHaveFocus();
    await user.click(addStatus);
    expect(onChange).not.toHaveBeenCalled();
    // The search field is disabled but focusable.
    expect(
      within(dialog).getByRole('searchbox', {hidden: true}),
    ).toHaveAttribute('aria-disabled', 'true');
    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={() => {}}
        commitBehavior="staged"
        isDisabled
      />,
    );

    const cancel = within(dialog).getByRole('button', {
      name: 'Cancel',
      hidden: true,
    });
    const apply = within(dialog).getByRole('button', {
      name: 'Apply',
      hidden: true,
    });
    expect(cancel).toBeEnabled();
    expect(fieldset).not.toContainElement(cancel);
    expect(apply).toHaveAttribute('aria-disabled', 'true');
    expect(
      screen.getByRole('combobox', {name: 'Visible fields'}),
    ).toHaveAttribute('aria-disabled', 'true');

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={() => {}}
        commitBehavior="staged"
        isLoading
      />,
    );

    await waitFor(() => {
      expect(dialog.querySelector('[aria-busy="true"]')).not.toBeNull();
    });
    // A pending change is announced with aria-busy, never by disabling the
    // fieldset: `disabled` here would blur the row button the user just
    // activated and drop focus to <body>.
    expect(dialog.querySelector('fieldset')).toBeEnabled();
    expect(
      within(dialog).getByRole('button', {name: 'Cancel', hidden: true}),
    ).toBeEnabled();
    expect(
      within(dialog).getByRole('button', {name: 'Apply', hidden: true}),
    ).toHaveAttribute('aria-disabled', 'true');
  });

  it('keeps focus on the activated row control while a change is pending', async () => {
    const user = userEvent.setup();
    const view = render(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={() => {}}
      />,
    );
    await openSelector();
    const dialog = screen.getByRole('dialog', {
      name: 'Visible fields',
      ...hidden,
    });

    const addStatus = within(dialog).getByRole('button', {
      name: 'Add Status',
      hidden: true,
    });
    await user.click(addStatus);
    expect(addStatus).toHaveFocus();

    view.rerender(
      <TransferListSelector
        label="Visible fields"
        options={OPTIONS}
        value={['name']}
        onChange={() => {}}
        isLoading
      />,
    );

    await waitFor(() => {
      expect(dialog.querySelector('[aria-busy="true"]')).not.toBeNull();
    });
    expect(addStatus).toHaveFocus();
    expect(document.body).not.toHaveFocus();
  });

  it('forwards intentional selector shell and transfer-list content props', async () => {
    render(
      <TransferListSelector
        label="Table columns"
        description="Choose the columns shown in the table."
        options={OPTIONS}
        value={['name']}
        onChange={() => {}}
        triggerLabel="Customize columns"
        size="sm"
        placement="below"
        data-testid="column-selector"
        selectedLabel="Shown"
        availableLabel="Hidden"
        hasSearch
        searchPlaceholder="Find a column"
        hasSelectAll
        hasClear
        commitBehavior="staged"
        applyLabel="Save columns"
        cancelLabel="Discard changes"
      />,
    );

    expect(
      screen.getByText('Choose the columns shown in the table.'),
    ).toBeVisible();
    // data-testid lands on the trigger button inside the control box.
    expect(
      screen.getByTestId('column-selector').closest('.astryx-complex-selector'),
    ).toHaveAttribute('data-size', 'sm');
    expect(
      screen.getByRole('combobox', {name: 'Table columns'}),
    ).toHaveTextContent('Customize columns');
    expect(
      screen.getByTestId('column-selector').closest('.astryx-field'),
    ).toHaveStyle({
      '--x-width': 'min(41rem, calc(100vw - 32px))',
    });

    await openSelector('Table columns');
    await waitFor(() => {
      expect(
        screen.getByRole('dialog', {name: 'Table columns', ...hidden}),
      ).toBeInTheDocument();
    });
    expect(screen.getByPlaceholderText('Find a column')).toBeInTheDocument();
    expect(screen.getAllByText('Shown')).not.toHaveLength(0);
    expect(screen.getAllByText('Hidden')).not.toHaveLength(0);
    expect(
      screen.getByRole('button', {name: 'Save columns', ...hidden}),
    ).toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'Discard changes', ...hidden}),
    ).toBeInTheDocument();
    expect(
      screen.queryByRole('button', {name: 'Reorder Name', ...hidden}),
    ).not.toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'Add all', ...hidden}),
    ).toBeInTheDocument();
    expect(
      screen.getByRole('button', {name: 'Clear', ...hidden}),
    ).toBeInTheDocument();

    const popover = screen
      .getByRole('dialog', {name: 'Table columns', ...hidden})
      .closest('[popover]');
    expect(popover?.getAttribute('style')).toContain(
      'position-area: self-block-end span-self-inline-end',
    );
  });
});

describe('TransferListSelector draft reset timing', () => {
  it('replaces a staged draft in the same commit as an external value change', async () => {
    const user = userEvent.setup();
    const frames: boolean[] = [];
    const onRender = () =>
      frames.push(
        screen.queryByRole('button', {name: 'Remove Owner', ...hidden}) != null,
      );
    const ui = (value: string[]) => (
      <Profiler id="selector" onRender={onRender}>
        <TransferListSelector
          label="Visible fields"
          options={OPTIONS}
          value={value}
          onChange={() => {}}
          commitBehavior="staged"
        />
      </Profiler>
    );
    const view = render(ui(['name', 'status']));
    await openSelector();
    await user.click(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    );
    expect(
      screen.getByRole('button', {name: 'Remove Owner', ...hidden}),
    ).toBeInTheDocument();

    frames.length = 0;
    view.rerender(ui(['name']));

    expect(frames.length).toBeGreaterThan(0);
    expect(frames).not.toContain(true);
    expect(
      screen.getByRole('button', {name: 'Add Owner', ...hidden}),
    ).toBeInTheDocument();
  });
});