Skip to content

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

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

/**
 * @file NavigationStackScrollEdge.interaction.browser.spec.ts
 * @input The built "Scrolling" NavigationStack story on the touch phone
 *   profile, programmatic and real-touch scrolls, and the interaction harness
 * @output Proofs of the bar's iOS 26 look under a finger. The bar paints no
 *   background or hairline, and each screen's veil switches at 10px. A push
 *   and a pop keep each screen's veil, and a finger's scroll fades it. A
 *   screen a pop reveals shows the veil for its own scroll. On a large-title
 *   screen the veil comes on as the bar's title takes over. The veil is
 *   hidden from assistive technology. A mouse keeps the bar's surface and
 *   runs no veil.
 * @position Interaction proof for NavigationStack.tsx and Lab's
 *   internal/useScrollEdgeEffect.ts, run by `pnpm test:interaction`. The
 *   phone profile's coarse pointer is the touch case in both engines.
 */

import {
  expect,
  test,
  type Locator,
  type Page,
} from '@astryxdesign/a11y-spec/playwright';
import {
  animationStoryboard,
  armHold,
  drag,
  frames,
  openStory,
  releaseAnimations,
  touchDriver,
  waitForRest,
  withStorybook,
} from '@astryxdesign/interaction-harness';

const storybook = withStorybook(test);

const STORY = 'lab-navigationstack--scrolling';

const card = (page: Page, screen: string) =>
  page.locator(`[data-navigation-screen="${screen}"]`);
const veil = (page: Page, screen: string) =>
  card(page, screen).locator(':scope > [data-navigation-scroll-edge]');
const scroller = (page: Page, screen: string) =>
  card(page, screen).locator(':scope > :first-child');

async function presentedOpacity(layer: Locator): Promise<number> {
  return layer.evaluate(element => Number(getComputedStyle(element).opacity));
}

/** Scrolls a screen, lets the observer report, waits for the fade to end. */
async function settleAt(page: Page, screen: string, top: number) {
  await scroller(page, screen).evaluate((element, y) => {
    element.scrollTop = y;
  }, top);
  await frames(page, 3);
  await waitForRest(veil(page, screen));
  return presentedOpacity(veil(page, screen));
}

// A report that never comes leaves the finger down for about a second.
const REPORT_FRAMES = 60;

/**
 * Scrolls a screen while a finger rests on its content, and lifts the finger
 * once the observer has reported: the veil then animates or changes. The
 * gesture host reads the scroll as the finger's, so the veil fades. The scroll
 * ends under the resting finger, so a lift before a late report would make
 * the scroll the program's. A page starved of frames reports late. Resolves
 * with the frames from the scroll to the veil's first change, or null when it
 * did not change within REPORT_FRAMES.
 */
async function fingerScrollTo(
  page: Page,
  screen: string,
  top: number,
): Promise<number | null> {
  return scroller(page, screen).evaluate(
    (element, {y, maxFrames}) =>
      new Promise<number | null>(resolve => {
        const target = element.lastElementChild ?? element;
        const touch = {identifier: 7, clientX: 100, clientY: 400, target};
        const fire = (type: string, touches: (typeof touch)[]) => {
          const event = new Event(type, {bubbles: true, cancelable: true});
          Object.defineProperty(event, 'changedTouches', {value: [touch]});
          Object.defineProperty(event, 'touches', {value: touches});
          target.dispatchEvent(event);
        };
        const layer = element.parentElement?.querySelector(
          ':scope > [data-navigation-scroll-edge]',
        );
        const animationsBefore = new Set(layer?.getAnimations() ?? []);
        const opacityBefore =
          layer == null ? null : getComputedStyle(layer).opacity;
        fire('touchstart', [touch]);
        element.scrollTop = y;
        let frames = 0;
        const liftAfter = (changedAt: number | null) => () => {
          fire('touchend', []);
          resolve(changedAt);
        };
        const check = () => {
          frames += 1;
          const changed =
            layer == null ||
            layer
              .getAnimations()
              .some(animation => !animationsBefore.has(animation)) ||
            getComputedStyle(layer).opacity !== opacityBefore;
          if (changed) {
            requestAnimationFrame(liftAfter(frames));
          } else if (frames >= maxFrames) {
            requestAnimationFrame(liftAfter(null));
          } else {
            requestAnimationFrame(check);
          }
        };
        requestAnimationFrame(check);
      }),
    {y: top, maxFrames: REPORT_FRAMES},
  );
}

async function openStack(page: Page, story = STORY) {
  await openStory(page, storybook(), story);
  await expect(page.getByTestId('navigation-stack')).toBeVisible();
  await expect(veil(page, 'root')).toBeAttached();
}

test('the bar paints no background and no hairline under a finger', async ({
  page,
}) => {
  await openStack(page);
  const background = await page
    .getByTestId('navigation-stack')
    .evaluate(stack => {
      const bar = stack.firstElementChild as HTMLElement;
      const style = getComputedStyle(bar.firstElementChild as HTMLElement);
      return {
        color: style.backgroundColor,
        border: style.borderBottomWidth,
      };
    });
  expect(background).toEqual({color: 'rgba(0, 0, 0, 0)', border: '0px'});
});

test('a scroll the program drives switches a screen’s veil at once: off through 10px, on beyond, both ways', async ({
  page,
}) => {
  await openStack(page);
  const steps: [number, number][] = [
    [0, 0],
    [5, 0],
    [10, 0],
    [11, 1],
    [200, 1],
    [10, 0],
    [0, 0],
  ];
  const seen: {top: number; opacity: number}[] = [];
  for (const [top, expected] of steps) {
    const opacity = await settleAt(page, 'root', top);
    seen.push({top, opacity});
    expect(opacity, `${top}px under the bar`).toBe(expected);
    // At once: the WebKit workaround (no fade on the program's scroll).
    expect(
      await veil(page, 'root').evaluate(
        element => element.getAnimations().length,
      ),
    ).toBe(0);
  }
  test
    .info()
    .annotations.push({type: 'switch', description: JSON.stringify(seen)});
});

test('a push brings the new screen’s own veil; a pop returns to the scrolled screen’s', async ({
  page,
}) => {
  await openStack(page);
  expect(await settleAt(page, 'root', 300)).toBe(1);
  await page.getByRole('button', {name: /Message 9\b/}).click();
  await expect(card(page, 'screen-Message 9')).toHaveAttribute(
    'data-navigation-top',
    'true',
  );
  await waitForRest(card(page, 'screen-Message 9'));
  await waitForRest(veil(page, 'screen-Message 9'));
  // The new screen sits at its top: its own veil is off. The covered screen
  // keeps its own, on.
  expect(await presentedOpacity(veil(page, 'screen-Message 9'))).toBe(0);
  expect(await presentedOpacity(veil(page, 'root'))).toBe(1);
  await page.getByRole('button', {name: 'Inbox'}).click();
  await expect(card(page, 'root')).toHaveAttribute(
    'data-navigation-top',
    'true',
  );
  await waitForRest(card(page, 'root'));
  expect(await presentedOpacity(veil(page, 'root'))).toBe(1);
});

test('a screen a pop reveals shows the veil for its own scroll: off at its top', async ({
  page,
}) => {
  // The story opens two screens deep, so the root mounts hidden.
  await openStack(page, 'lab-navigationstack--pushed');
  const back = page.locator('[data-navigation-back]');
  await back.click();
  await expect(card(page, 'screen-About')).toHaveCount(0);
  await waitForRest(card(page, 'screen-General'));
  await back.click();
  await expect(card(page, 'root')).toHaveAttribute(
    'data-navigation-top',
    'true',
  );
  await waitForRest(card(page, 'root'));
  await waitForRest(veil(page, 'root'));
  // The veil is there and laid out, so an opacity of 0 is a real reading.
  const box = await veil(page, 'root').boundingBox();
  expect(box?.width ?? 0).toBeGreaterThan(0);
  expect(box?.height ?? 0).toBeGreaterThan(0);
  expect(
    await scroller(page, 'root').evaluate(element => element.scrollTop),
  ).toBe(0);
  expect(await presentedOpacity(veil(page, 'root'))).toBe(0);
});

test('on a large-title screen the veil comes on as the bar’s title takes over', async ({
  page,
}) => {
  await openStack(page, 'lab-navigationstack--large-title');
  const geometry = await card(page, 'root').evaluate(element => {
    const title = element.querySelector('h1');
    const sentinel = element.querySelector(
      '[data-navigation-scroll-edge-sentinel]',
    );
    const bar = document.querySelector('[data-navigation-bar="root"]');
    if (title == null || sentinel == null || bar == null) {
      return null;
    }
    const titleBox = title.getBoundingClientRect();
    const sentinelBox = sentinel.getBoundingClientRect();
    return {
      titleHeight: Math.round(titleBox.height),
      titleBottom: Math.round(titleBox.bottom),
      sentinelBottom: Math.round(sentinelBox.bottom),
      sentinelHeight: Math.round(sentinelBox.height),
      // How far the root scrolls before the large title's bottom meets the
      // bar's, where the bar's title takes over.
      collapseAt: Math.round(
        titleBox.bottom - bar.getBoundingClientRect().bottom,
      ),
    };
  });
  if (geometry == null) {
    throw new Error('no large title, scroll edge sentinel or bar');
  }
  const {collapseAt, ...ends} = geometry;
  expect(ends.titleHeight).toBeGreaterThan(20);
  expect(ends.sentinelHeight).toBe(10);
  expect(ends.sentinelBottom).toBe(ends.titleBottom);
  expect(collapseAt).toBeGreaterThan(10);
  const barTitle = page.locator('[data-navigation-bar="root"] h2');
  // Short of it the large title shows: the bar's title is hidden, no veil.
  expect(await settleAt(page, 'root', collapseAt - 4)).toBe(0);
  await waitForRest(barTitle);
  expect(await presentedOpacity(barTitle)).toBe(0);
  // Past it the bar's title shows, over the veil.
  expect(await settleAt(page, 'root', collapseAt + 4)).toBe(1);
  await waitForRest(barTitle);
  expect(await presentedOpacity(barTitle)).toBe(1);
});

test('a finger scrolling the screen fades the veil in', async ({
  page,
  browserName,
}) => {
  test.skip(
    browserName !== 'chromium',
    'native scrolling from injected touches is Chromium-only (harness README)',
  );
  await openStack(page);
  const driver = await touchDriver(page);
  await driver.play(
    drag({x: 200, y: 560}, {x: 200, y: 460}, {durationMs: 300, restMs: 450}),
  );
  await waitForRest(veil(page, 'root'));
  const top = await scroller(page, 'root').evaluate(
    element => element.scrollTop,
  );
  expect(top).toBeGreaterThan(10);
  expect(await presentedOpacity(veil(page, 'root'))).toBe(1);
});

/**
 * Holds the page's IntersectionObserver reports from `holdObserverReports()`
 * until the finger's scroll has ended. That is after the `scrollend` that
 * follows the lift, or after the lift when the scroll ended under the resting
 * finger. A busy page runs a report that late. Each entry keeps its own
 * `time`. `releasedReports` counts the reports held, so a test can see the
 * hold.
 */
async function holdReportsPastTheScroll(page: Page) {
  await page.addInitScript(() => {
    const Observer = window.IntersectionObserver;
    const held: Array<() => void> = [];
    let isHolding = false;
    let isLifted = false;
    let hasScrollEnded = false;
    const release = () => {
      isHolding = false;
      // After the gesture host and the finger-scroll watch hear the event.
      setTimeout(() => {
        const runs = held.splice(0);
        Object.assign(window, {releasedReports: runs.length});
        for (const run of runs) {
          run();
        }
      });
    };
    Object.assign(window, {
      releasedReports: 0,
      holdObserverReports: () => {
        isHolding = true;
        isLifted = false;
        hasScrollEnded = false;
      },
    });
    document.addEventListener(
      'touchend',
      () => {
        if (isHolding) {
          isLifted = true;
          if (hasScrollEnded) {
            release();
          }
        }
      },
      true,
    );
    document.addEventListener(
      'scrollend',
      () => {
        if (isHolding) {
          hasScrollEnded = true;
          if (isLifted) {
            release();
          }
        }
      },
      true,
    );
    window.IntersectionObserver = class extends Observer {
      constructor(
        callback: IntersectionObserverCallback,
        options?: IntersectionObserverInit,
      ) {
        super((entries, observer) => {
          if (isHolding) {
            held.push(() => callback(entries, observer));
          } else {
            callback(entries, observer);
          }
        }, options);
      }
    };
  });
}

test('a finger’s scroll fades the veil even when its report runs after the scroll ended', async ({
  page,
  browserName,
}) => {
  test.skip(
    browserName !== 'chromium',
    'native scrolling from injected touches is Chromium-only (harness README)',
  );
  await holdReportsPastTheScroll(page);
  await openStack(page);
  const layer = veil(page, 'root');
  const hold = await armHold(page, layer, {
    judges: {target: layer, property: 'opacity'},
    newOnly: true,
  });
  const driver = await touchDriver(page);
  await page.evaluate(() =>
    (
      window as unknown as {holdObserverReports: () => void}
    ).holdObserverReports(),
  );
  await driver.play(
    drag({x: 200, y: 560}, {x: 200, y: 460}, {durationMs: 300, restMs: 450}),
  );
  // A switch at once runs no animation, so the hold finds none.
  await hold.held();
  expect(
    await page.evaluate(
      () => (window as unknown as {releasedReports: number}).releasedReports,
    ),
  ).toBeGreaterThan(0);
  await releaseAnimations(page, {finish: true});
  expect(await presentedOpacity(layer)).toBe(1);
});

test('the veil and its sentinel are hidden from assistive technology', async ({
  page,
}) => {
  await openStack(page);
  const hidden = await card(page, 'root').evaluate(element => {
    const layer = element.querySelector('[data-navigation-scroll-edge]');
    const sentinel = element.querySelector(
      '[data-navigation-scroll-edge-sentinel]',
    );
    return {
      layer: layer?.getAttribute('aria-hidden'),
      sentinel: sentinel?.getAttribute('aria-hidden'),
      pointer: layer == null ? null : getComputedStyle(layer).pointerEvents,
    };
  });
  expect(hidden).toEqual({layer: 'true', sentinel: 'true', pointer: 'none'});
});

test.describe('with a mouse', () => {
  test.use({hasTouch: false, isMobile: false});

  test('the bar keeps its surface and hairline and runs no veil', async ({
    page,
  }) => {
    await openStack(page);
    expect(
      await page.evaluate(() => matchMedia('(pointer: coarse)').matches),
    ).toBe(false);
    const background = await page
      .getByTestId('navigation-stack')
      .evaluate(stack => {
        const bar = stack.firstElementChild as HTMLElement;
        const style = getComputedStyle(bar.firstElementChild as HTMLElement);
        return {color: style.backgroundColor, border: style.borderBottomWidth};
      });
    expect(background.color).not.toBe('rgba(0, 0, 0, 0)');
    expect(background.border).toBe('1px');
    await scroller(page, 'root').evaluate(element => {
      element.scrollTop = 200;
    });
    await frames(page, 5);
    expect(
      await veil(page, 'root').evaluate(element => ({
        display: getComputedStyle(element).display,
        running: element.getAnimations().length,
      })),
    ).toEqual({display: 'none', running: 0});
  });
});

test(
  'storyboard: a screen’s veil fading in',
  {tag: '@storyboard'},
  async ({page}, testInfo) => {
    await openStack(page);
    const layer = veil(page, 'root');
    const viewport = page.viewportSize() ?? {width: 402, height: 714};
    const clip = {x: 0, y: 0, width: viewport.width, height: 120};
    const hold = await armHold(page, layer, {
      judges: {target: layer, property: 'opacity'},
      newOnly: true,
    });
    const reportFrames = await fingerScrollTo(page, 'root', 120);
    // How long the finger rested: a slow reaction to the scroll shows here.
    testInfo.annotations.push({
      type: 'veil report frames',
      description: String(reportFrames),
    });
    const held = await hold.held();
    const {storyboard} = await animationStoryboard(page, {
      held,
      name: 'navigation-stack-scroll-edge-appear',
      clip,
      measure: async () => ({opacity: await presentedOpacity(layer)}),
      columns: 6,
      cellScale: 0.5,
    });
    await releaseAnimations(page, {finish: true});
    await storyboard.write(testInfo);
    const ins = storyboard.frames.map(f => f.data.opacity as number);
    expect(ins[0]).toBeLessThan(0.05);
    expect(ins.every((o, i) => i === 0 || o >= ins[i - 1] - 0.002)).toBe(true);
    expect(ins.at(-1)).toBeGreaterThan(0.99);
  },
);