Skip to content

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

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

/**
 * @file tooltip.fixtures.ts
 * @input Plain HTML tooltips on a trigger between two page buttons, conforming and deliberately violating
 * @output TOOLTIP_FIXTURES, their subject and relation selectors, and the expectation → violating-fixture map
 * @position Contract self-test data for tooltip.jsdom.test.ts and tooltip.chromium.spec.ts
 */

import type {TooltipStateFacts} from './tooltip';

export const SUBJECT_SELECTOR = '#trigger';

/** The fixture tooltip's show delay on hover, which every fixture declares. */
const SHOW_DELAY_MS = 200;

/**
 * How the fixture tooltip behaves. One script reads these from the trigger's
 * data attributes, so a violating fixture changes exactly one behavior.
 */
interface Behavior {
  /** What keyboard focus on the trigger does: show the tooltip, nothing, or show it and move focus into it. */
  readonly focus?: 'show' | 'ignore' | 'steal';
  /** When Escape hides the tooltip: always, only while the trigger has focus, or never. */
  readonly escape?: 'always' | 'focused-only' | 'never';
  /** Whether focus leaving the trigger hides the tooltip. */
  readonly blurHides?: boolean;
  /** Whether hovering the trigger shows the tooltip. */
  readonly hoverShows?: boolean;
  /** Leaving the trigger: hide after a short bridge, hide at once, or never hide. */
  readonly leave?: 'bridge' | 'no-bridge' | 'stay';
  /** Hide the tooltip on its own after this many milliseconds, hovered or not. */
  readonly autoHideMs?: number | null;
}

/**
 * The smallest tooltip: focus shows it at once, hover after a delay; leaving
 * hides it after a bridge that entering the tooltip cancels; blur and Escape
 * hide it. jsdom does not run it; the jsdom lane reads DOM attributes only.
 */
const SCRIPT = `<script>(() => {
  const trigger = document.getElementById('trigger');
  const tip = document.getElementById('tip');
  const d = trigger.dataset;
  let showTimer = null;
  let hideTimer = null;
  let autoTimer = null;
  const clear = () => { clearTimeout(showTimer); clearTimeout(hideTimer); };
  const hide = () => { clear(); clearTimeout(autoTimer); tip.hidden = true; };
  const show = () => {
    clear();
    tip.hidden = false;
    if (d.autoHide !== '') {
      clearTimeout(autoTimer);
      autoTimer = setTimeout(hide, Number(d.autoHide));
    }
  };
  trigger.addEventListener('focus', () => {
    if (d.focus === 'ignore') return;
    show();
    if (d.focus === 'steal') tip.focus();
  });
  trigger.addEventListener('blur', () => { if (d.blurHides === 'true' && d.focus !== 'steal') hide(); });
  trigger.addEventListener('mouseenter', () => {
    if (d.hoverShows !== 'true') return;
    clear();
    showTimer = setTimeout(show, ${SHOW_DELAY_MS});
  });
  trigger.addEventListener('mouseleave', () => {
    clearTimeout(showTimer);
    if (d.leave === 'bridge') hideTimer = setTimeout(hide, 100);
    else if (d.leave === 'no-bridge') hide();
  });
  tip.addEventListener('mouseenter', () => clearTimeout(hideTimer));
  tip.addEventListener('mouseleave', () => { if (d.leave !== 'stay') hideTimer = setTimeout(hide, 100); });
  document.addEventListener('keydown', event => {
    if (event.key !== 'Escape' || tip.hidden) return;
    if (d.escape === 'always' || (d.escape === 'focused-only' && document.activeElement === trigger)) hide();
  });
})();</script>`;

interface TriggerOptions {
  readonly behavior?: Behavior;
  /** The popup's role; null for none. */
  readonly role?: string | null;
  /** The trigger's aria-describedby; null for none. */
  readonly describedBy?: string | null;
  /** The trigger's own accessible name and visible text. */
  readonly label?: string;
  /** An aria-label that names an icon-only trigger instead of its text. */
  readonly ariaLabel?: string | null;
  /** A visible hint the trigger is already described by, besides the tooltip. */
  readonly hint?: string | null;
}

const TOOLTIP_TEXT = 'Saves your changes to this draft';

function tooltipHtml({
  behavior = {},
  role = 'tooltip',
  describedBy = 'tip',
  label = 'Save',
  ariaLabel = null,
  hint = null,
}: TriggerOptions): string {
  const b: Required<Behavior> = {
    focus: 'show',
    escape: 'always',
    blurHides: true,
    hoverShows: true,
    leave: 'bridge',
    autoHideMs: null,
    ...behavior,
  };
  const data = `data-focus="${b.focus}" data-escape="${b.escape}" data-blur-hides="${b.blurHides}" data-hover-shows="${b.hoverShows}" data-leave="${b.leave}" data-auto-hide="${b.autoHideMs ?? ''}"`;
  const triggerAttributes = [
    'type="button"',
    'id="trigger"',
    ariaLabel == null ? null : `aria-label="${ariaLabel}"`,
    describedBy == null ? null : `aria-describedby="${describedBy}"`,
    data,
  ]
    .filter(attribute => attribute != null)
    .join(' ');
  const tipAttributes = [
    'id="tip"',
    role == null ? null : `role="${role}"`,
    'tabindex="-1"',
    'hidden',
    'style="position:absolute;inset-block-start:100%;inset-inline-start:0;padding:4px 8px;background:#222;color:#fff;white-space:nowrap"',
  ]
    .filter(attribute => attribute != null)
    .join(' ');
  return `<div style="padding:48px"><button type="button" id="before">Before the trigger</button> <span style="position:relative;display:inline-block"><button ${triggerAttributes}>${label}</button><div ${tipAttributes}>${TOOLTIP_TEXT}</div></span>${hint == null ? '' : ` <span id="hint">${hint}</span>`} <button type="button" id="after">After the trigger</button></div>${SCRIPT}`;
}

export interface TooltipFixture {
  readonly id: string;
  readonly summary: string;
  readonly facts: TooltipStateFacts;
  /** Relation name → selector inside the fixture. */
  readonly relations: Readonly<Record<string, string>>;
  readonly html: string;
}

const RELATIONS = {
  tooltip: '#tip',
  before: '#before',
  after: '#after',
} as const;

const FACTS: TooltipStateFacts = {
  showsOnHover: true,
  showDelayMs: SHOW_DELAY_MS,
};

function tooltip(
  id: string,
  summary: string,
  {
    facts = FACTS,
    ...options
  }: TriggerOptions & {facts?: TooltipStateFacts} = {},
): TooltipFixture {
  return {
    id,
    summary,
    facts,
    relations: RELATIONS,
    html: tooltipHtml(options),
  };
}

export const TOOLTIP_FIXTURES: readonly TooltipFixture[] = [
  tooltip(
    'conforming-text-trigger',
    'a button described by its tooltip, shown by focus at once and by hover after a delay, kept while hovered, hidden by Escape, blur and leaving',
  ),
  tooltip(
    'conforming-icon-trigger',
    'an icon-only button named by aria-label and described by its tooltip',
    {label: '💾', ariaLabel: 'Save'},
  ),
  tooltip(
    'conforming-existing-description',
    'a button already described by a visible hint, whose aria-describedby names the hint and the tooltip',
    {describedBy: 'hint tip', hint: 'Last saved a minute ago'},
  ),
  tooltip(
    'conforming-focus-only',
    'a tooltip only keyboard focus shows, which claims no hover; the hover rows do not apply',
    {
      behavior: {hoverShows: false},
      facts: {...FACTS, showsOnHover: false},
    },
  ),
  tooltip(
    'violating-status-role',
    'the popup carries role status instead of tooltip',
    {role: 'status'},
  ),
  tooltip('violating-no-role', 'the popup carries no role', {role: null}),
  tooltip(
    'violating-not-described',
    'the trigger has no aria-describedby, so nothing ties the tooltip to it',
    {describedBy: null},
  ),
  tooltip(
    'violating-described-by-other',
    'the trigger is described only by a neighbouring hint, not by the tooltip',
    {describedBy: 'hint', hint: 'Last saved a minute ago'},
  ),
  tooltip(
    'violating-focus-ignored',
    'keyboard focus on the trigger does not show the tooltip',
    {behavior: {focus: 'ignore'}},
  ),
  tooltip(
    'violating-focus-moves-into-tooltip',
    'showing the tooltip on focus moves focus into the tooltip',
    {behavior: {focus: 'steal'}},
  ),
  tooltip('violating-escape-ignored', 'Escape does nothing', {
    behavior: {escape: 'never'},
  }),
  tooltip(
    'violating-escape-needs-focus',
    'Escape hides the tooltip only while the trigger has focus, so a hovered tooltip cannot be dismissed without moving the pointer',
    {behavior: {escape: 'focused-only'}},
  ),
  tooltip(
    'violating-blur-keeps',
    'focus leaving the trigger leaves the tooltip showing',
    {behavior: {blurHides: false}},
  ),
  tooltip(
    'violating-hover-ignored',
    'hovering the trigger does not show the tooltip',
    {behavior: {hoverShows: false}},
  ),
  tooltip(
    'violating-no-hover-bridge',
    'leaving the trigger hides the tooltip at once, even when the pointer moves onto the tooltip',
    {behavior: {leave: 'no-bridge'}},
  ),
  tooltip(
    'violating-times-out',
    'the tooltip hides itself half a second after it appears, though the pointer still rests on the trigger',
    {behavior: {autoHideMs: 500}},
  ),
  tooltip(
    'violating-focus-only-times-out',
    'a tooltip only keyboard focus shows, which hides itself half a second later though focus stays on the trigger',
    {
      behavior: {hoverShows: false, autoHideMs: 500},
      facts: {...FACTS, showsOnHover: false},
    },
  ),
  tooltip(
    'violating-leave-keeps',
    'the tooltip stays after the pointer leaves the trigger and the tooltip',
    {behavior: {leave: 'stay'}},
  ),
];

export function fixture(id: string): TooltipFixture {
  const found = TOOLTIP_FIXTURES.find(candidate => candidate.id === id);
  if (found == null) {
    throw new Error(`unknown tooltip fixture "${id}"`);
  }
  return found;
}

export const CONFORMING_FIXTURES: readonly string[] = TOOLTIP_FIXTURES.filter(
  candidate => candidate.id.startsWith('conforming-'),
).map(candidate => candidate.id);

export const TOOLTIP_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
  'tooltip.surface.role': ['violating-status-role', 'violating-no-role'],
  'tooltip.trigger.described-by-tooltip': [
    'violating-not-described',
    'violating-described-by-other',
  ],
  'tooltip.trigger.description': [
    'violating-not-described',
    'violating-described-by-other',
  ],
  'tooltip.focus.shows-on-keyboard-focus': [
    'violating-focus-ignored',
    'violating-focus-moves-into-tooltip',
    'violating-focus-only-times-out',
    'violating-times-out',
  ],
  'tooltip.keys.escape-dismisses': [
    'violating-escape-ignored',
    'violating-escape-needs-focus',
  ],
  'tooltip.focus.leaving-hides': ['violating-blur-keeps'],
  'tooltip.hover.shows-on-hover': ['violating-hover-ignored'],
  'tooltip.hover.stays-while-hovered': [
    'violating-no-hover-bridge',
    'violating-times-out',
  ],
  'tooltip.hover.leaving-hides': ['violating-leave-keeps'],
};