Skip to content

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

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

/**
 * @file useTableStickyColumns.test.tsx
 * @input useTableStickyColumns, Table, React testing utilities
 * @output Functional tests for the sticky-columns plugin
 * @position Test file; validates pinning, cumulative offsets, edges, no-op
 *
 * Note: `position: sticky` and the z-index/background are applied via StyleX
 * (compiled to classNames), which jsdom does not resolve to `element.style`.
 * The plugin sets the per-column *offset* (`insetInlineStart`/`insetInlineEnd`)
 * as an inline style, so these tests assert on those inline offsets — the
 * jsdom-visible, plugin-owned signal that a column is pinned and at what offset.
 */

import {afterEach, describe, it, expect, vi} from 'vitest';
import {render, screen} from '@testing-library/react';
import {Table} from '../../Table';
import {useTableStickyColumns} from './useTableStickyColumns';
import {useTableColumnResize} from '../columnResize/useTableColumnResize';
import {useTableRowIndex} from '../rowIndex/useTableRowIndex';
import {pixel, proportional} from '../../columnUtils';
import type {TableColumn} from '../../types';

// =============================================================================
// Test Data
// =============================================================================

interface Row extends Record<string, unknown> {
  id: string;
  name: string;
  email: string;
  team: string;
  status: string;
}

const data: Row[] = [
  {id: '1', name: 'Alice', email: '[email protected]', team: 'DS', status: 'Active'},
  {id: '2', name: 'Bob', email: '[email protected]', team: 'Plat', status: 'Away'},
];

const columns: TableColumn<Row>[] = [
  {key: 'name', header: 'Name', width: pixel(180)},
  {key: 'email', header: 'Email', width: pixel(220)},
  {key: 'team', header: 'Team', width: pixel(160)},
  {key: 'status', header: 'Status', width: pixel(140)},
];

function getHeader(name: string): HTMLElement {
  return screen.getByRole('columnheader', {name});
}

// =============================================================================
// Tests
// =============================================================================

describe('useTableStickyColumns', () => {
  it('pins a start column at inset-inline-start: 0', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
  });

  it("adds a row-number column's windowed extra width to the pinned offsets after it", () => {
    function Harness() {
      const rowIndex = useTableRowIndex<Row>();
      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{rowIndex, stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    // The number column comes first, so Name sits after its 48px floor plus
    // whatever extra width a windowed table gives it (none here).
    expect(getHeader('Name').getAttribute('style')).toContain(
      'calc(48px + var(--_table-logical-extra-0, 0px))',
    );
    expect(screen.getByRole('table').getAttribute('style') ?? '').not.toContain(
      '--_table-logical-extra',
    );
  });

  it('computes cumulative start offsets for contiguous pinned columns', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({
        startKeys: ['name', 'email'],
      });
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    // name is first → offset 0; email follows → offset = name width (180px)
    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
    expect(getHeader('Email').style.insetInlineStart).toBe('180px');
  });

  it('uses the width-less floor for cumulative pinned offsets', () => {
    const widthLessColumns: TableColumn<Row>[] = [
      {key: 'name', header: 'Name'},
      {key: 'email', header: 'Email'},
      {key: 'team', header: 'Team'},
    ];

    function Harness() {
      const sticky = useTableStickyColumns<Row>({
        startKeys: ['name', 'email'],
      });
      return (
        <Table
          data={data}
          columns={widthLessColumns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }

    render(<Harness />);
    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
    expect(getHeader('Email').style.insetInlineStart).toBe('60px');
  });

  it('offsets a pinned column by the rendered width of a width-less neighbor', () => {
    // At overflow the table sits at its minimum width (3 × 120px here), so the
    // width-less Name column renders at 120px, not its own 60px floor.
    const mixedColumns: TableColumn<Row>[] = [
      {key: 'name', header: 'Name'},
      {key: 'email', header: 'Email', width: proportional(1)},
      {key: 'team', header: 'Team', width: proportional(1)},
    ];

    function Harness() {
      const sticky = useTableStickyColumns<Row>({
        startKeys: ['name', 'email'],
      });
      return (
        <Table
          data={data}
          columns={mixedColumns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }

    render(<Harness />);
    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
    expect(getHeader('Email').style.insetInlineStart).toBe('120px');
  });

  it('pins an end column at inset-inline-end: 0', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({endKeys: ['status']});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    expect(getHeader('Status').style.insetInlineEnd).toBe('0px');
  });

  it('pins body cells, not just headers', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    const firstBodyCell = screen.getByText('Alice').closest('td');
    expect(firstBodyCell).not.toBeNull();
    expect(firstBodyCell!.style.insetInlineStart).toBe('0px');
  });

  it('is a no-op with an empty config — no cell gets an offset', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    for (const header of ['Name', 'Email', 'Team', 'Status']) {
      const th = getHeader(header);
      expect(th.style.insetInlineStart).toBe('');
      expect(th.style.insetInlineEnd).toBe('');
    }
  });

  it('only pins configured columns, leaving others unset', () => {
    function Harness() {
      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={{stickyColumns: sticky}}
        />
      );
    }
    render(<Harness />);
    expect(getHeader('Name').style.insetInlineStart).toBe('0px');
    expect(getHeader('Team').style.insetInlineStart).toBe('');
    expect(getHeader('Team').style.insetInlineEnd).toBe('');
  });

  /**
   * Composition with the resize plugin. Both plugins contribute `position` to
   * the same header cell — resize appends `relative` for its handle's
   * containing block — so the pin has to survive either insertion order. The
   * plugin writes `position` inline for exactly that reason, which also makes
   * it the jsdom-visible signal.
   */
  describe('composition with the column-resize plugin', () => {
    /**
     * With the resize plugin mounted, each header cell also contains the
     * handle's own labelled element, so the cell's accessible name is no
     * longer just its header text. Address the cell by its column key.
     */
    function getHeaderCell(key: string): HTMLElement {
      const cell = document.querySelector<HTMLElement>(
        `th[data-column-key="${key}"]`,
      );
      if (!cell) {
        throw new Error(`header cell not found: ${key}`);
      }
      return cell;
    }

    function StickyResizeHarness({
      resizeFirst,
    }: {
      resizeFirst: boolean;
    }): React.ReactElement {
      const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
      const resize = useTableColumnResize<Row>({
        columns: columns as TableColumn<Record<string, unknown>>[],
      });
      return (
        <Table
          data={data}
          columns={columns}
          idKey="id"
          plugins={
            resizeFirst
              ? {resize, stickyColumns: sticky}
              : {stickyColumns: sticky, resize}
          }
        />
      );
    }

    it('keeps a pinned column sticky with resize declared first', () => {
      render(<StickyResizeHarness resizeFirst={true} />);
      expect(getHeaderCell('name').style.position).toBe('sticky');
      expect(getHeaderCell('name').style.insetInlineStart).toBe('0px');
    });

    it('keeps a pinned column sticky with sticky declared first', () => {
      render(<StickyResizeHarness resizeFirst={false} />);
      expect(getHeaderCell('name').style.position).toBe('sticky');
      expect(getHeaderCell('name').style.insetInlineStart).toBe('0px');
    });

    it('leaves unpinned columns to the resize plugin', () => {
      render(<StickyResizeHarness resizeFirst={true} />);
      // Only pinned cells get an inline position; the rest keep whatever the
      // resize plugin's own styles give them.
      expect(getHeaderCell('team').style.position).toBe('');
    });
  });

  describe('the scroll container attaches once', () => {
    afterEach(() => {
      vi.unstubAllGlobals();
    });

    it.each([true, false])(
      'keeps one attach across renders with column resize composed (resize first: %s)',
      resizeFirst => {
        let observers = 0;
        vi.stubGlobal(
          'ResizeObserver',
          class {
            constructor() {
              observers += 1;
            }
            observe() {}
            unobserve() {}
            disconnect() {}
          },
        );
        function Harness({tick}: {tick: number}) {
          const sticky = useTableStickyColumns<Row>({startKeys: ['name']});
          const resize = useTableColumnResize<Row>({
            columns: columns as TableColumn<Record<string, unknown>>[],
          });
          return (
            <Table
              data={data}
              columns={columns}
              idKey="id"
              aria-describedby={`tick-${tick}`}
              plugins={
                resizeFirst
                  ? {resize, stickyColumns: sticky}
                  : {stickyColumns: sticky, resize}
              }
            />
          );
        }
        const {rerender} = render(<Harness tick={0} />);
        const attached = observers;
        rerender(<Harness tick={1} />);
        rerender(<Harness tick={2} />);
        rerender(<Harness tick={3} />);
        // Three plain re-renders: no plugin's scroll container re-attaches.
        expect(observers).toBe(attached);
      },
    );
  });
});