Skip to content

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

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

/**
 * @file timeGridProbe.ts
 * @input A Playwright page showing a built Lab/Schedule week or day story
 * @output Geometry, block, and focus readings of the painted time grid, plus a
 *   receipt writer that pairs each reading with a screenshot
 * @position Shared by the Schedule time-grid browser contracts. Every lookup
 *   works from text, computed style, and geometry rather than class names, so
 *   the same readings describe a build that predates a contract and one that
 *   implements it.
 */

import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import type {Page} from '@playwright/test';
import {
  DEFAULT_STORYBOOK_DIR,
  serveStorybook,
  type StaticServer,
} from '@astryxdesign/a11y-spec/storybook';

export const OUTPUT = path.resolve('test-results/schedule-time-grid-evidence');
export const WEEKLY = 'lab-schedule--weekly';
export const WEEKLY_FIXED_HEIGHT = 'lab-schedule--weekly-fixed-height';
export const DAY = 'lab-schedule--day';
export const OVERLAPPING = 'lab-schedule--overlapping-events';
export const WIDE = {width: 1280, height: 900};
export const NARROW = {width: 760, height: 700};
// One hour of the week/day stories; the contract's lead context is one hour.
export const HOUR_HEIGHT = 100;

export interface Box {
  readonly left: number;
  readonly right: number;
  readonly top: number;
  readonly bottom: number;
  readonly width: number;
  readonly height: number;
}

export interface TimeGridReading {
  readonly direction: 'ltr' | 'rtl';
  readonly scroller: {
    readonly box: Box;
    readonly scrollTop: number;
    readonly scrollLeft: number;
    readonly scrollHeight: number;
    readonly clientHeight: number;
    readonly scrollWidth: number;
    readonly clientWidth: number;
    readonly verticalScrollbarWidth: number;
  } | null;
  readonly headerCells: ReadonlyArray<Box>;
  readonly bodyColumns: ReadonlyArray<Box>;
  readonly hourLabels: ReadonlyArray<{
    readonly text: string;
    readonly left: number;
  }>;
  readonly nowLine: {readonly topInContent: number} | null;
  readonly firstColumnTopInContent: number | null;
  readonly horizontalScrollerCount: number;
  readonly pageOverflows: boolean;
}

export interface Receipt {
  readonly test: string;
  readonly story: string;
  readonly viewport: {readonly width: number; readonly height: number};
  readonly direction: 'ltr' | 'rtl';
  readonly browser: string;
  readonly checkout: string;
  readonly head: string;
  readonly measured: unknown;
  readonly screenshot: string;
}

export interface Evidence {
  readonly storybook: StaticServer;
  readonly checkoutSha: string;
  readonly receipts: Receipt[];
}

/** Serves the built Storybook and prepares the evidence directory. */
export async function startEvidence(): Promise<Evidence> {
  const checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
    encoding: 'utf8',
  }).trim();
  fs.mkdirSync(OUTPUT, {recursive: true});
  const storybook = await serveStorybook(
    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
  );
  return {storybook, checkoutSha, receipts: []};
}

/** Writes the receipts of one contract file and stops the server. */
export async function finishEvidence(
  evidence: Evidence | undefined,
  name: string,
): Promise<void> {
  if (evidence == null) {
    return;
  }
  fs.writeFileSync(
    path.join(OUTPUT, `receipts-${name}.json`),
    `${JSON.stringify(evidence.receipts, null, 2)}\n`,
  );
  await evidence.storybook.close();
}

export function storyUrl(
  evidence: Evidence,
  id: string,
  globals?: string,
): string {
  const query = globals == null ? '' : `&globals=${globals}`;
  return `${evidence.storybook.origin}/iframe.html?id=${id}&viewMode=story${query}`;
}

export async function openStory(
  evidence: Evidence,
  page: Page,
  id: string,
  viewport: {width: number; height: number},
  globals?: string,
): Promise<void> {
  await page.setViewportSize(viewport);
  await page.goto(storyUrl(evidence, id, globals), {waitUntil: 'load'});
  await page.locator('.astryx-schedule').waitFor();
  // Fonts and the first layout pass settle before anything is measured.
  await page.evaluate(() => document.fonts.ready);
  await page.waitForTimeout(100);
}

/**
 * Reads the painted time grid by what it is, not by how it is classed: the
 * scroll owner is the first element whose block axis overflows, header cells
 * hold the day headings, body columns are the stacks of empty hour slots, and
 * the now-line is the two-pixel rule.
 */
export function readTimeGrid(page: Page): Promise<TimeGridReading> {
  return page.evaluate((hourHeight): TimeGridReading => {
    const toBox = (rect: DOMRect) => ({
      left: rect.left,
      right: rect.right,
      top: rect.top,
      bottom: rect.bottom,
      width: rect.width,
      height: rect.height,
    });
    const root = document.querySelector<HTMLElement>('.astryx-schedule');
    if (root == null) {
      throw new Error('No Schedule root in the story');
    }
    const direction: 'ltr' | 'rtl' =
      getComputedStyle(root).direction === 'rtl' ? 'rtl' : 'ltr';
    const all = [...root.querySelectorAll<HTMLElement>('*')];
    const scrollsOn = (element: HTMLElement, axis: 'x' | 'y') => {
      const style = getComputedStyle(element);
      const overflow = axis === 'x' ? style.overflowX : style.overflowY;
      const excess =
        axis === 'x'
          ? element.scrollWidth - element.clientWidth
          : element.scrollHeight - element.clientHeight;
      return (overflow === 'auto' || overflow === 'scroll') && excess > 1;
    };
    const scrollerElement =
      all.find(element => scrollsOn(element, 'y')) ?? null;
    const scrollerBox = scrollerElement?.getBoundingClientRect();
    const inScroller = (element: Element) =>
      scrollerElement != null && scrollerElement.contains(element);

    const headerCells = [...root.querySelectorAll<HTMLElement>('h3')]
      .map(heading => heading.parentElement)
      .filter((cell): cell is HTMLElement => cell != null)
      .map(cell => toBox(cell.getBoundingClientRect()));

    const isEmptyBox = (element: HTMLElement) =>
      element.children.length === 0 && element.textContent?.trim() === '';
    const slots = all.filter(element => {
      if (!inScroller(element) || !isEmptyBox(element)) {
        return false;
      }
      const rect = element.getBoundingClientRect();
      return Math.abs(rect.height - hourHeight) <= 2 && rect.width > 20;
    });
    const columnsByLeft = new Map<number, Box>();
    for (const slot of slots) {
      const rect = slot.getBoundingClientRect();
      const key = Math.round(rect.left);
      const existing = columnsByLeft.get(key);
      if (existing == null) {
        columnsByLeft.set(key, toBox(rect));
      } else {
        columnsByLeft.set(key, {
          ...existing,
          top: Math.min(existing.top, rect.top),
          bottom: Math.max(existing.bottom, rect.bottom),
        });
      }
    }
    const bodyColumns = [...columnsByLeft.values()].sort((a, b) =>
      direction === 'rtl' ? b.left - a.left : a.left - b.left,
    );
    const sortedHeaderCells = [...headerCells].sort((a, b) =>
      direction === 'rtl' ? b.left - a.left : a.left - b.left,
    );

    const hourLabels = all
      .filter(
        element =>
          inScroller(element) &&
          element.children.length === 0 &&
          /^\d{1,2}(:\d{2})?\s?(AM|PM)$/i.test(
            element.textContent?.trim() ?? '',
          ),
      )
      .map(element => ({
        text: element.textContent?.trim() ?? '',
        left: element.getBoundingClientRect().left,
      }));

    const nowLineElement = all.find(element => {
      if (!inScroller(element) || !isEmptyBox(element)) {
        return false;
      }
      const style = getComputedStyle(element);
      return (
        style.position === 'absolute' &&
        style.borderTopWidth === '2px' &&
        element.getBoundingClientRect().height <= 2
      );
    });
    const contentTop = (element: Element) =>
      scrollerElement == null || scrollerBox == null
        ? null
        : element.getBoundingClientRect().top -
          scrollerBox.top +
          scrollerElement.scrollTop;
    const firstSlotOfFirstColumn = slots
      .map(slot => ({slot, rect: slot.getBoundingClientRect()}))
      .filter(
        ({rect}) =>
          bodyColumns[0] != null &&
          Math.round(rect.left) === Math.round(bodyColumns[0].left),
      )
      .sort((a, b) => a.rect.top - b.rect.top)[0]?.slot;

    const horizontalScrollerCount = all.filter(element =>
      scrollsOn(element, 'x'),
    ).length;

    return {
      direction,
      scroller:
        scrollerElement == null || scrollerBox == null
          ? null
          : {
              box: toBox(scrollerBox),
              scrollTop: scrollerElement.scrollTop,
              scrollLeft: scrollerElement.scrollLeft,
              scrollHeight: scrollerElement.scrollHeight,
              clientHeight: scrollerElement.clientHeight,
              scrollWidth: scrollerElement.scrollWidth,
              clientWidth: scrollerElement.clientWidth,
              verticalScrollbarWidth:
                scrollerElement.offsetWidth - scrollerElement.clientWidth,
            },
      headerCells: sortedHeaderCells,
      bodyColumns,
      hourLabels,
      nowLine:
        nowLineElement == null
          ? null
          : {topInContent: contentTop(nowLineElement) ?? Number.NaN},
      firstColumnTopInContent:
        firstSlotOfFirstColumn == null
          ? null
          : contentTop(firstSlotOfFirstColumn),
      horizontalScrollerCount,
      pageOverflows:
        document.documentElement.scrollWidth >
        document.documentElement.clientWidth,
    };
  }, HOUR_HEIGHT);
}

export function columnDeltas(reading: TimeGridReading) {
  return reading.headerCells.map((cell, index) => {
    const column = reading.bodyColumns[index];
    return {
      index,
      header: [Math.round(cell.left), Math.round(cell.right)],
      body:
        column == null
          ? null
          : [Math.round(column.left), Math.round(column.right)],
      deltaLeft: column == null ? null : Math.abs(cell.left - column.left),
      deltaRight: column == null ? null : Math.abs(cell.right - column.right),
    };
  });
}

export function setScrollLeft(page: Page, value: number): Promise<void> {
  return page.evaluate(scrollLeft => {
    const root = document.querySelector<HTMLElement>('.astryx-schedule');
    const scroller = [...(root?.querySelectorAll<HTMLElement>('*') ?? [])].find(
      element => {
        const style = getComputedStyle(element);
        return (
          (style.overflowY === 'auto' || style.overflowY === 'scroll') &&
          element.scrollHeight - element.clientHeight > 1
        );
      },
    );
    if (scroller != null) {
      scroller.scrollLeft = scrollLeft;
    }
  }, value);
}

export function setScrollTop(page: Page, value: number): Promise<void> {
  return page.evaluate(scrollTop => {
    const root = document.querySelector<HTMLElement>('.astryx-schedule');
    const scroller = [...(root?.querySelectorAll<HTMLElement>('*') ?? [])].find(
      element => {
        const style = getComputedStyle(element);
        return (
          (style.overflowY === 'auto' || style.overflowY === 'scroll') &&
          element.scrollHeight - element.clientHeight > 1
        );
      },
    );
    if (scroller != null) {
      scroller.scrollTop = scrollTop;
    }
  }, value);
}

export async function record(
  evidence: Evidence,
  page: Page,
  name: string,
  story: string,
  direction: 'ltr' | 'rtl',
  measured: unknown,
): Promise<void> {
  const viewport = page.viewportSize() ?? WIDE;
  const file = `${name}.png`;
  await page.screenshot({path: path.join(OUTPUT, file), fullPage: false});
  evidence.receipts.push({
    test: name,
    story,
    viewport,
    direction,
    browser: page.context().browser()?.version() ?? 'unknown',
    checkout: evidence.checkoutSha,
    head: process.env.ASTRYX_HEAD_SHA ?? evidence.checkoutSha,
    measured,
    screenshot: file,
  });
  // The job log is the durable copy of each measurement when artifacts expire.
  // eslint-disable-next-line no-console
  console.log(`[schedule-time-grid] ${name}: ${JSON.stringify(measured)}`);
}

export interface BlockReading {
  readonly title: string;
  readonly box: Box;
  readonly columnIsolation: string;
}

export function readBlocks(
  page: Page,
  titles: ReadonlyArray<string>,
): Promise<BlockReading[]> {
  return page.evaluate((wanted): BlockReading[] => {
    const root = document.querySelector<HTMLElement>('.astryx-schedule');
    if (root == null) {
      throw new Error('No Schedule root in the story');
    }
    const leaves = [...root.querySelectorAll<HTMLElement>('*')].filter(
      element =>
        element.children.length === 0 &&
        wanted.includes(element.textContent?.trim() ?? ''),
    );
    const seen = new Set<HTMLElement>();
    const blocks: Array<{title: string; box: Box; columnIsolation: string}> =
      [];
    for (const leaf of leaves) {
      let block: HTMLElement | null = leaf;
      while (block != null && getComputedStyle(block).position !== 'absolute') {
        block = block.parentElement;
      }
      if (block == null || seen.has(block)) {
        continue;
      }
      // The hidden read-only grid repeats titles inside aria-labels, never as
      // text nodes, so a text leaf is always a painted block.
      seen.add(block);
      const rect = block.getBoundingClientRect();
      blocks.push({
        title: leaf.textContent?.trim() ?? '',
        box: {
          left: rect.left,
          right: rect.right,
          top: rect.top,
          bottom: rect.bottom,
          width: rect.width,
          height: rect.height,
        },
        columnIsolation:
          block.parentElement == null
            ? ''
            : getComputedStyle(block.parentElement).isolation,
      });
    }
    return blocks;
  }, titles);
}

export function inlineOverlap(a: Box, b: Box): number {
  return Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left));
}

export function blockOverlap(a: Box, b: Box): number {
  const horizontal = inlineOverlap(a, b);
  const vertical = Math.max(
    0,
    Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top),
  );
  return horizontal * vertical;
}

/**
 * How much of each edge of a frame changed between two same-size PNG
 * buffers: the share of columns (top/bottom) or rows (left/right) in a
 * 4-pixel band along that edge with at least one changed pixel. A complete
 * focus ring scores near 1 on all four edges; a ring hidden under a pinned
 * part scores near 0 there.
 */
export function ringEdgeCoverage(
  before: {width: number; height: number; data: Uint8Array},
  after: {width: number; height: number; data: Uint8Array},
  band = 4,
): {top: number; bottom: number; left: number; right: number} {
  const {width, height} = before;
  const changed = (x: number, y: number) => {
    const index = (y * width + x) * 4;
    for (let channel = 0; channel < 3; channel += 1) {
      if (
        Math.abs(before.data[index + channel] - after.data[index + channel]) >
        24
      ) {
        return true;
      }
    }
    return false;
  };
  const columnChanged = (x: number, fromY: number, toY: number) => {
    for (let y = fromY; y < toY; y += 1) {
      if (changed(x, y)) {
        return true;
      }
    }
    return false;
  };
  const rowChanged = (y: number, fromX: number, toX: number) => {
    for (let x = fromX; x < toX; x += 1) {
      if (changed(x, y)) {
        return true;
      }
    }
    return false;
  };
  let top = 0;
  let bottom = 0;
  for (let x = 0; x < width; x += 1) {
    if (columnChanged(x, 0, band)) {
      top += 1;
    }
    if (columnChanged(x, height - band, height)) {
      bottom += 1;
    }
  }
  let left = 0;
  let right = 0;
  for (let y = 0; y < height; y += 1) {
    if (rowChanged(y, 0, band)) {
      left += 1;
    }
    if (rowChanged(y, width - band, width)) {
      right += 1;
    }
  }
  return {
    top: top / width,
    bottom: bottom / width,
    left: left / height,
    right: right / height,
  };
}