Skip to content

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

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

/** Plain-HTML positive and mutation fixtures for the Table contract. */

import type {TableStateFacts} from './table';

export const TABLE_SUBJECT_SELECTOR = '[data-a11y-table]';
export const TABLE_COLUMN_HEADER_SELECTOR = '[data-a11y-table-column-header]';
export const TABLE_ROW_SELECTOR = '[data-a11y-table-row]';
export const TABLE_ROW_HEADER_SELECTOR = '[data-a11y-table-row-header]';
export const TABLE_CELL_SELECTOR = '[data-a11y-table-cell]';

export interface TableFixture {
  readonly id: string;
  readonly summary: string;
  readonly facts: TableStateFacts;
  readonly html: string;
}

const COLUMNS = ['Name', 'Role', 'Location'] as const;
const ROWS = [
  ['Ada', 'Engineer', 'London'],
  ['Grace', 'Admiral', 'Arlington'],
] as const;

interface Options {
  /** The table element's role attribute, or null for the native role. */
  readonly role?: string | null;
  /** `aria-label` on the table, or null for none. */
  readonly label?: string | null;
  /** Name the table from a visible heading through `aria-labelledby`. */
  readonly labelledBy?: string;
  /** An explicit role that overrides the column header cells' native role. */
  readonly columnHeaderRole?: string;
  /** An `aria-label` that replaces the second column header's name. */
  readonly columnHeaderRename?: string;
  /** An explicit role that overrides the first body row's native role. */
  readonly rowRole?: string;
  /** Render each body row's first cell as a row header. */
  readonly rowHeaders?: boolean;
  /** Element used for row header cells. */
  readonly rowHeaderTag?: 'th' | 'td';
  /** An `aria-label` that replaces the first row header's name. */
  readonly rowHeaderRename?: string;
  /** Render the designated data cell as a column header instead. */
  readonly cellAsHeader?: boolean;
  /** Designate a data cell that sits outside the table. */
  readonly cellOutside?: boolean;
  /**
   * Move one designated part into a second, separately labelled data table,
   * keeping its role and name, so only its place in the subject table is wrong.
   */
  readonly otherTable?: 'row' | 'column-header' | 'row-header' | 'cell';
}

function attr(name: string, value: string | null | undefined): string {
  return value == null ? '' : `${name}="${value}"`;
}

function html(options: Options = {}): string {
  const role = options.role ?? null;
  const label = options.label === undefined ? 'Team members' : options.label;
  const rowHeaderTag = options.rowHeaderTag ?? 'th';
  const heading =
    options.labelledBy == null
      ? ''
      : `<h2 id="a11y-table-heading">${options.labelledBy}</h2>`;
  const headers = COLUMNS.map((column, index) => {
    const role = attr('role', options.columnHeaderRole);
    const rename =
      index === 1 ? attr('aria-label', options.columnHeaderRename) : '';
    const designated =
      index === 2 && options.otherTable === 'column-header'
        ? ''
        : 'data-a11y-table-column-header';
    return `<th ${designated} scope="col" ${role} ${rename}>${column}</th>`;
  }).join('');
  const body = ROWS.map((row, rowIndex) => {
    const cells = row
      .map((value, cellIndex) => {
        if (options.rowHeaders && cellIndex === 0) {
          const scope = rowHeaderTag === 'th' ? 'scope="row"' : '';
          const rename =
            rowIndex === 0 ? attr('aria-label', options.rowHeaderRename) : '';
          const designated =
            rowIndex === 1 && options.otherTable === 'row-header'
              ? ''
              : 'data-a11y-table-row-header';
          return `<${rowHeaderTag} ${designated} ${scope} ${rename}>${value}</${rowHeaderTag}>`;
        }
        const designated =
          rowIndex === 0 &&
          cellIndex === 1 &&
          !options.cellOutside &&
          options.otherTable !== 'cell';
        if (designated && options.cellAsHeader) {
          return `<th data-a11y-table-cell scope="col">${value}</th>`;
        }
        return `<td ${designated ? 'data-a11y-table-cell' : ''}>${value}</td>`;
      })
      .join('');
    const role = rowIndex === 0 ? attr('role', options.rowRole) : '';
    const designated =
      rowIndex === 1 && options.otherTable === 'row'
        ? ''
        : 'data-a11y-table-row';
    return `<tr ${designated} ${role}>${cells}</tr>`;
  }).join('');
  const outside = options.cellOutside
    ? '<div data-a11y-table-cell>Engineer</div>'
    : '';
  const other = options.otherTable;
  // The second table keeps a header cell so the browser treats it as a data
  // table rather than a layout table; its moved part keeps its role and name.
  const otherTable =
    other == null
      ? ''
      : `
    <table aria-label="Other team">
      <thead><tr>${
        other === 'column-header'
          ? '<th data-a11y-table-column-header scope="col">Location</th>'
          : '<th scope="col">Team</th>'
      }<th scope="col">Note</th></tr></thead>
      <tbody><tr ${other === 'row' ? 'data-a11y-table-row' : ''}>${
        other === 'row-header'
          ? '<th data-a11y-table-row-header scope="row">Grace</th>'
          : '<td>Other</td>'
      }${
        other === 'cell'
          ? '<td data-a11y-table-cell>Engineer</td>'
          : '<td>Note</td>'
      }</tr></tbody>
    </table>`;
  return `
    ${heading}
    <table data-a11y-table ${attr('role', role)} ${attr('aria-label', label)} ${
      options.labelledBy == null ? '' : 'aria-labelledby="a11y-table-heading"'
    }>
      <thead><tr data-a11y-table-row>${headers}</tr></thead>
      <tbody>${body}</tbody>
    </table>
    ${outside}
    ${otherTable}
  `;
}

function facts(overrides: Partial<TableStateFacts> = {}): TableStateFacts {
  return {
    label: 'Team members',
    columnHeaders: [...COLUMNS],
    rows: 3,
    rowHeaders: [],
    cells: 1,
    ...overrides,
  };
}

const ROW_HEADERS = ROWS.map(row => row[0]);

export const TABLE_FIXTURES: readonly TableFixture[] = [
  {
    id: 'conforming-labelled',
    summary: 'a labelled data table with column headers and data cells',
    facts: facts(),
    html: html(),
  },
  {
    id: 'conforming-labelledby-row-headers',
    summary: 'a table named by a visible heading, with a row header per row',
    facts: facts({label: 'Crew roster', rowHeaders: ROW_HEADERS}),
    html: html({label: null, labelledBy: 'Crew roster', rowHeaders: true}),
  },
  {
    id: 'conforming-unlabelled',
    summary: 'a table whose binding declares no label',
    facts: facts({label: null}),
    html: html({label: null}),
  },
  {
    id: 'violating-role-grid',
    summary: 'a static table that claims the interactive grid role',
    facts: facts(),
    html: html({role: 'grid'}),
  },
  {
    id: 'violating-role-presentation',
    // Unlabelled: a global ARIA attribute such as aria-label makes the browser
    // ignore a presentational role, so a labelled table keeps its semantics.
    summary:
      'an unlabelled table whose semantics are removed with role="presentation"',
    facts: facts(),
    html: html({role: 'presentation', label: null}),
  },
  {
    id: 'violating-name-missing',
    summary: 'a table that drops its declared label',
    facts: facts(),
    html: html({label: null}),
  },
  {
    id: 'violating-name-wrong',
    summary: 'a table exposing a different label',
    facts: facts(),
    html: html({label: 'Members'}),
  },
  {
    id: 'violating-column-header-cell',
    summary:
      'column titles whose header role is overridden to an ordinary cell',
    facts: facts(),
    html: html({columnHeaderRole: 'cell'}),
  },
  {
    id: 'violating-column-header-name',
    summary: 'a column header whose computed name differs from its title',
    facts: facts(),
    html: html({columnHeaderRename: 'Column 2'}),
  },
  {
    id: 'violating-row-group',
    summary: 'a body row whose row role is overridden to a group',
    facts: facts(),
    html: html({rowRole: 'group'}),
  },
  {
    id: 'violating-row-other-table',
    summary: 'a designated row that belongs to a second table',
    facts: facts(),
    html: html({otherTable: 'row'}),
  },
  {
    id: 'violating-column-header-other-table',
    summary: 'a correctly named column header that belongs to a second table',
    facts: facts(),
    html: html({otherTable: 'column-header'}),
  },
  {
    id: 'violating-row-header-other-table',
    summary: 'a correctly named row header that belongs to a second table',
    facts: facts({rowHeaders: ROW_HEADERS}),
    html: html({rowHeaders: true, otherTable: 'row-header'}),
  },
  {
    id: 'violating-cell-other-table',
    summary: 'a data cell that belongs to a second table',
    facts: facts(),
    html: html({otherTable: 'cell'}),
  },
  {
    id: 'violating-row-header-td',
    summary: 'row titles rendered as ordinary data cells',
    facts: facts({rowHeaders: ROW_HEADERS}),
    html: html({rowHeaders: true, rowHeaderTag: 'td'}),
  },
  {
    id: 'violating-row-header-name',
    summary: 'a row header whose computed name differs from its title',
    facts: facts({rowHeaders: ROW_HEADERS}),
    html: html({rowHeaders: true, rowHeaderRename: 'Row 1'}),
  },
  {
    id: 'violating-cell-as-header',
    summary: 'a data value marked up as a column header',
    facts: facts(),
    html: html({cellAsHeader: true}),
  },
  {
    id: 'violating-cell-outside',
    summary: 'a data value rendered outside the table it belongs to',
    facts: facts(),
    html: html({cellOutside: true}),
  },
];

export const CONFORMING_TABLE_FIXTURES = TABLE_FIXTURES.filter(fixture =>
  fixture.id.startsWith('conforming-'),
).map(fixture => fixture.id);

export const TABLE_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
  'table.role.exposed': ['violating-role-grid', 'violating-role-presentation'],
  'table.name.exposed': ['violating-name-missing', 'violating-name-wrong'],
  'table.column-headers.exposed': [
    'violating-column-header-cell',
    'violating-column-header-name',
    'violating-column-header-other-table',
  ],
  'table.rows.exposed': [
    'violating-row-group',
    'violating-row-other-table',
    'violating-cell-outside',
  ],
  'table.row-headers.exposed': [
    'violating-row-header-td',
    'violating-row-header-name',
    'violating-row-header-other-table',
  ],
  'table.cells.exposed': [
    'violating-cell-as-header',
    'violating-cell-outside',
    'violating-cell-other-table',
  ],
};

export function tableFixture(id: string): TableFixture {
  const fixture = TABLE_FIXTURES.find(candidate => candidate.id === id);
  if (fixture == null) {
    throw new Error(`unknown Table fixture "${id}"`);
  }
  return fixture;
}