@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Item/__tests__/ItemSwipePinchZoom.a11y.chromium.spec.ts

@@ -0,0 +1,186 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
+
+/**
+ * @file ItemSwipePinchZoom.a11y.chromium.spec.ts
+ * @input The checked-in Core/Item › Swipe Actions story, a built Storybook and
+ *   real Chromium two-finger touch input (CDP) on a phone viewport
+ * @output Browser evidence that a pinch which starts on a swipeable row zooms
+ *   the page and leaves the row where it is, whichever finger lands first and
+ *   wherever the second one lands, while a one-finger sideways drag still
+ *   swipes (WCAG 1.4.4)
+ * @position Chromium proof for Item's swipe-row `touch-action` and the
+ *   gesture's hand-off of a second finger
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+// A phone: the viewport meta applies and the page can pinch-zoom.
+test.use({
+  hasTouch: true,
+  isMobile: true,
+  viewport: {width: 390, height: 844},
+  deviceScaleFactor: 3,
+});
+
+const sleep = async (ms: number) =>
+  new Promise(resolve => setTimeout(resolve, ms));
+
+type Point = {x: number; y: number};
+type Box = {x: number; y: number; width: number; height: number};
+
+async function openStory(page: Page) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-item--swipe-actions&viewMode=story`,
+  );
+  const rows = page.locator('.astryx-item');
+  const row = rows.first();
+  await expect(row.getByText('Message 1')).toBeVisible();
+  // The gesture arrives with the lazily loaded swipe layer; its panel is the
+  // sign the row can be dragged.
+  await expect(row.locator('[data-swipe-panel="leading"]')).toBeAttached();
+  const box = (await row.boundingBox()) as Box;
+  const next = (await rows.nth(1).boundingBox()) as Box;
+  expect(await page.evaluate(() => window.visualViewport?.scale)).toBe(1);
+  // Record how far the first row ever moves sideways while fingers are down.
+  await page.evaluate(() => {
+    const el = document.querySelector('.astryx-item') as HTMLElement;
+    const w = window as unknown as {__maxTravel: number};
+    w.__maxTravel = 0;
+    const tick = () => {
+      const travel = Math.abs(new DOMMatrix(getComputedStyle(el).transform).e);
+      w.__maxTravel = Math.max(w.__maxTravel, travel);
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+  const cdp = await page.context().newCDPSession(page);
+  return {box, next, cdp};
+}
+
+const zoom = async (page: Page) =>
+  page.evaluate(() => window.visualViewport?.scale ?? 1);
+const maxTravel = async (page: Page) =>
+  page.evaluate(() => (window as unknown as {__maxTravel: number}).__maxTravel);
+
+// Two fingers land one after the other and spread apart, as a person pinches.
+// The spread is wide enough to clear the browser's minimum pinch span.
+async function pinch(cdp: CDPSession, first: Point, second: Point) {
+  const steps = 12;
+  const spread = 3;
+  const mid = {x: (first.x + second.x) / 2, y: (first.y + second.y) / 2};
+  const at = (p: Point, k: number, id: number) => ({
+    x: mid.x + (p.x - mid.x) * k,
+    y: mid.y + (p.y - mid.y) * k,
+    id,
+  });
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [at(first, 1, 1)],
+  });
+  await sleep(30);
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [at(first, 1, 1), at(second, 1, 2)],
+  });
+  for (let i = 1; i <= steps; i++) {
+    await sleep(16);
+    const k = 1 + ((spread - 1) * i) / steps;
+    await cdp.send('Input.dispatchTouchEvent', {
+      type: 'touchMove',
+      touchPoints: [at(first, k, 1), at(second, k, 2)],
+    });
+  }
+  await sleep(16);
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchEnd',
+    touchPoints: [],
+  });
+  await sleep(600);
+}
+
+test('a sideways pinch on a swipeable row zooms the page and the row stays put', async ({
+  page,
+}) => {
+  const {box, cdp} = await openStory(page);
+  const y = box.y + box.height / 2;
+  const x = box.x + box.width / 2;
+  await pinch(cdp, {x: x - 30, y}, {x: x + 30, y});
+  expect(await zoom(page)).toBeGreaterThan(1.2);
+  expect(await maxTravel(page)).toBeLessThan(1);
+});
+
+test('a vertical pinch starting on a swipeable row zooms the page', async ({
+  page,
+}) => {
+  const {box, next, cdp} = await openStory(page);
+  const x = box.x + box.width / 2;
+  await pinch(
+    cdp,
+    {x, y: box.y + box.height / 2},
+    {x, y: next.y + next.height / 2},
+  );
+  expect(await zoom(page)).toBeGreaterThan(1.2);
+  expect(await maxTravel(page)).toBeLessThan(1);
+});
+
+test('a pinch with the first finger on the row and the second off it zooms the page', async ({
+  page,
+}) => {
+  const {box, cdp} = await openStory(page);
+  const y = box.y + box.height / 2;
+  // The page below the list: no row, no swipe.
+  await pinch(cdp, {x: box.x + 120, y}, {x: box.x + 220, y: 700});
+  expect(await zoom(page)).toBeGreaterThan(1.2);
+  expect(await maxTravel(page)).toBeLessThan(1);
+});
+
+test('a pinch with the first finger off the row and the second on it zooms the page', async ({
+  page,
+}) => {
+  const {box, cdp} = await openStory(page);
+  const y = box.y + box.height / 2;
+  await pinch(cdp, {x: box.x + 220, y: 700}, {x: box.x + 120, y});
+  expect(await zoom(page)).toBeGreaterThan(1.2);
+  expect(await maxTravel(page)).toBeLessThan(1);
+});
+
+test('a one-finger sideways drag still swipes the row and leaves the zoom alone', async ({
+  page,
+}) => {
+  const {box, cdp} = await openStory(page);
+  const y = box.y + box.height / 2;
+  const startX = box.x + 24;
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [{x: startX, y}],
+  });
+  for (const dx of [6, 14, 28, 44, 60]) {
+    await cdp.send('Input.dispatchTouchEvent', {
+      type: 'touchMove',
+      touchPoints: [{x: startX + dx, y}],
+    });
+    await sleep(40);
+  }
+  await expect.poll(async () => maxTravel(page)).toBeGreaterThan(50);
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchEnd',
+    touchPoints: [],
+  });
+  expect(await zoom(page)).toBe(1);
+});

package/src/Item/useSwipeAction.ts

@@ -32,6 +32,12 @@
  * signal WebKit honours. Before the axis is decided, and for a drag the
  * scroller got, nothing is cancelled.
  *
+ * A pinch is the browser's: the root's `touch-action` keeps `pinch-zoom`, and
+ * a second finger that lands anywhere before the axis is decided turns the
+ * touch into a pinch, so the row lets it go and cancels nothing. A finger
+ * that is not the first one down never starts a drag. Once the row owns a
+ * drag, a second finger does not break it.
+ *
  * The drag's travel is one custom property written on the root, coalesced to
  * one write per frame; the root's transform reads it and the panels'
  * transforms read its negation, so the row moves and the panel appears fixed
@@ -211,6 +217,8 @@ export function useSwipeAction({
   const settleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const frameRef = useRef<number | null>(null);
   const pendingRef = useRef<number | null>(null);
+  /** Removes the document listener that watches for a pinch's second finger. */
+  const stopPinchWatchRef = useRef<(() => void) | null>(null);
   const [state, setState] = useState<SwipeState>(IDLE_STATE);
   const stateRef = useRef(state);
   stateRef.current = state;
@@ -237,10 +245,48 @@ export function useSwipeAction({
       if (frameRef.current != null) {
         cancelAnimationFrame(frameRef.current);
       }
+      stopPinchWatchRef.current?.();
+      stopPinchWatchRef.current = null;
     },
     [],
   );
 
+  const stopWatchingForPinch = useCallback(() => {
+    stopPinchWatchRef.current?.();
+    stopPinchWatchRef.current = null;
+  }, []);
+
+  /**
+   * Until the axis is decided, a second finger anywhere on the page makes
+   * the touch a pinch: the row gives it up and cancels nothing, so the
+   * browser zooms. The finger can land off the row, so the document listens.
+   */
+  const watchForPinch = useCallback(
+    (drag: DragState) => {
+      stopWatchingForPinch();
+      const onAnyPointerDown = (event: PointerEvent) => {
+        if (
+          event.pointerType === 'touch' &&
+          event.pointerId !== drag.pointerId &&
+          drag.claimed === null
+        ) {
+          drag.claimed = false;
+          stopWatchingForPinch();
+        }
+      };
+      document.addEventListener('pointerdown', onAnyPointerDown, {
+        capture: true,
+        passive: true,
+      });
+      stopPinchWatchRef.current = () => {
+        document.removeEventListener('pointerdown', onAnyPointerDown, {
+          capture: true,
+        });
+      };
+    },
+    [stopWatchingForPinch],
+  );
+
   /** Write the travel (physical px) the transforms read. */
   const writeTravel = useCallback(
     (travel: number) => {
@@ -446,10 +492,24 @@ export function useSwipeAction({
   const onPointerDown = useCallback(
     (event: ReactPointerEvent) => {
       const current = stateRef.current;
+      const inFlight = dragRef.current;
+      if (inFlight != null) {
+        // A second finger before the axis is decided: a pinch, not a swipe.
+        if (
+          event.pointerType === 'touch' &&
+          event.pointerId !== inFlight.pointerId &&
+          inFlight.claimed === null
+        ) {
+          inFlight.claimed = false;
+          stopWatchingForPinch();
+        }
+        return;
+      }
       if (
         !isEnabled ||
         event.pointerType !== 'touch' ||
-        dragRef.current != null ||
+        // Another finger is already down: this one is part of a pinch.
+        event.isPrimary === false ||
         current.phase === 'settling' ||
         current.phase === 'held'
       ) {
@@ -459,7 +519,7 @@ export function useSwipeAction({
       const inlineSign: 1 | -1 = isRtlElement(root) ? -1 : 1;
       inlineSignRef.current = inlineSign;
       const startTime = now();
-      dragRef.current = {
+      const drag: DragState = {
         // Logical: the physical travel through the inline sign.
         baseTravel: travelRef.current * inlineSign,
         claimed: null,
@@ -476,8 +536,10 @@ export function useSwipeAction({
         startY: event.clientY,
         travel: 0,
       };
+      dragRef.current = drag;
+      watchForPinch(drag);
     },
-    [isEnabled, rootRef],
+    [isEnabled, rootRef, stopWatchingForPinch, watchForPinch],
   );
 
   const onPointerMove = useCallback(
@@ -497,6 +559,9 @@ export function useSwipeAction({
         if (Math.max(Math.abs(deltaX), Math.abs(deltaY)) < AXIS_LOCK_PX) {
           return;
         }
+        // The axis is decided now, whichever way: a later finger is the
+        // swipe's to ignore or the scroller's to use.
+        stopWatchingForPinch();
         // More horizontal than vertical is the row's, the rest the scroller's.
         if (Math.abs(deltaX) <= Math.abs(deltaY)) {
           drag.claimed = false;
@@ -555,7 +620,7 @@ export function useSwipeAction({
       drag.lastTime = now();
       paintOnNextFrame(sign * drag.inlineSign * offset);
     },
-    [paintOnNextFrame, rootRef, writeDuration],
+    [paintOnNextFrame, rootRef, stopWatchingForPinch, writeDuration],
   );
 
   const endGesture = useCallback(
@@ -565,6 +630,7 @@ export function useSwipeAction({
         return;
       }
       dragRef.current = null;
+      stopWatchingForPinch();
       if (drag.claimed !== true) {
         return;
       }
@@ -598,7 +664,7 @@ export function useSwipeAction({
       }
       settle(side, 0, 'idle');
     },
-    [rootRef, settle, slideOutAndFire],
+    [rootRef, settle, slideOutAndFire, stopWatchingForPinch],
   );
 
   const onPointerUp = useCallback(

package/src/Kbd/Kbd.test.tsx

@@ -12,6 +12,7 @@
 import {render, screen} from '@testing-library/react';
 import {describe, it, expect, afterEach, vi} from 'vitest';
 import {Kbd} from './Kbd';
+import {InternationalizationProvider} from '../i18n';
 
 describe('Kbd', () => {
   const originalPlatform = navigator.platform;
@@ -186,6 +187,100 @@ describe('Kbd', () => {
     expect(el).toHaveAttribute('aria-label', 'Control + K');
   });
 
+  it.each([
+    {platform: 'Linux', key: 'control', expectedGlyph: 'Ctrl'},
+    {platform: 'MacIntel', key: 'command', expectedGlyph: '⌘'},
+  ])(
+    'localizes modifier labels on $platform without changing the glyph',
+    ({platform, key, expectedGlyph}) => {
+      Object.defineProperty(navigator, 'platform', {
+        value: platform,
+        configurable: true,
+      });
+      const overrides = {
+        fr: {
+          [`@astryx.kbd.key.${key}`]: 'Modificateur',
+          '@astryx.kbd.key.shift': 'Majuscule',
+        },
+      };
+      const {rerender} = render(
+        <InternationalizationProvider locale="fr" overrides={overrides}>
+          <Kbd keys="mod+shift+k" />
+        </InternationalizationProvider>,
+      );
+      expect(screen.getByRole('img')).toHaveAccessibleName(
+        'Modificateur + Majuscule + K',
+      );
+      expect(screen.getByText(expectedGlyph)).toBeInTheDocument();
+      expect(screen.getByText('⇧')).toBeInTheDocument();
+      rerender(
+        <InternationalizationProvider locale="en" overrides={overrides}>
+          <Kbd keys="mod+shift+k" />
+        </InternationalizationProvider>,
+      );
+      expect(screen.getByRole('img')).toHaveAccessibleName(
+        `${key === 'command' ? 'Command' : 'Control'} + Shift + K`,
+      );
+    },
+  );
+
+  it.each([
+    'ctrl',
+    'alt',
+    'shift',
+    'enter',
+    'backspace',
+    'escape',
+    'tab',
+    'up',
+    'down',
+    'left',
+    'right',
+    'plus',
+    'esc',
+    'return',
+  ])('uses a catalog entry for the %s spoken key', key => {
+    const canonical =
+      key === 'ctrl'
+        ? 'control'
+        : key === 'esc'
+          ? 'escape'
+          : key === 'return'
+            ? 'enter'
+            : key;
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {[`@astryx.kbd.key.${canonical}`]: 'Touche traduite'}}}>
+        <Kbd keys={key} />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByRole('img')).toHaveAccessibleName('Touche traduite');
+  });
+
+  it('localizes visible key text and the spoken shortcut combination', () => {
+    render(
+      <InternationalizationProvider
+        locale="de"
+        overrides={{
+          de: {
+            '@astryx.kbd.key.controlShort': 'Strg',
+            '@astryx.kbd.key.escapeShort': 'Abbr',
+            '@astryx.kbd.key.control': 'Steuerung',
+            '@astryx.kbd.key.escape': 'Abbrechen',
+            '@astryx.kbd.shortcut': '{key} mit {shortcut}',
+          },
+        }}>
+        <Kbd keys="mod+esc" />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByText('Strg')).toBeInTheDocument();
+    expect(screen.getByText('Abbr')).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAccessibleName(
+      'Abbrechen mit Steuerung',
+    );
+  });
+
   it('computed role and aria-label win over consumer-passed overrides', () => {
     // Contract props the component computes must not be clobbered by
     // pass-through attributes: {...rest} is spread before role/aria-label.

package/src/Kbd/Kbd.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
- * @output Exports Kbd component and KbdProps with canonical shortcut labels
+ * @input Uses React, StyleX, theme tokens, shortcut key names, aliases, provider-bound translator
+ * @output Exports Kbd component and KbdProps with localized shortcut text
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -19,6 +19,7 @@ import {mergeProps} from '../utils';
 import {isApplePlatform} from '../utils/isApplePlatform';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator, type TranslatorFn} from '../i18n';
 import {
   colorVars,
   spacingVars,
@@ -67,7 +68,6 @@ const KEY_DISPLAY = new Map<string, string>([
   ['shift', '\u21E7'], // ⇧
   ['enter', '\u21B5'], // ↵
   ['backspace', '\u232B'], // ⌫
-  ['escape', 'Esc'],
   ['tab', '\u21E5'], // ⇥
   ['up', '\u2191'],
   ['down', '\u2193'],
@@ -86,10 +86,11 @@ const KBD_KEY_ALIASES = new Map<string, string>([
  * `mod` key (⌘ on macOS, Ctrl on other platforms) and falls back to
  * KEY_DISPLAY or uppercased key name.
  */
-function getKeyDisplay(key: string, isMac: boolean): string {
+function getKeyDisplay(key: string, isMac: boolean, t: TranslatorFn): string {
   if (key === 'mod') {
-    return isMac ? '\u2318' : 'Ctrl';
+    return isMac ? '\u2318' : t('@astryx.kbd.key.controlShort');
   }
+  if (key === 'escape') return t('@astryx.kbd.key.escapeShort');
   return KEY_DISPLAY.get(key) ?? key.toUpperCase();
 }
 
@@ -99,25 +100,26 @@ function getKeyDisplay(key: string, isMac: boolean): string {
  * accessible name for the shortcut is built from these words instead.
  */
 const KEY_LABEL = new Map<string, string>([
-  ['ctrl', 'Control'],
-  ['alt', 'Alt'],
-  ['shift', 'Shift'],
-  ['enter', 'Enter'],
-  ['backspace', 'Backspace'],
-  ['escape', 'Escape'],
-  ['tab', 'Tab'],
-  ['up', 'Up arrow'],
-  ['down', 'Down arrow'],
-  ['left', 'Left arrow'],
-  ['right', 'Right arrow'],
-  ['plus', 'Plus'],
+  ['ctrl', '@astryx.kbd.key.control'],
+  ['alt', '@astryx.kbd.key.alt'],
+  ['shift', '@astryx.kbd.key.shift'],
+  ['enter', '@astryx.kbd.key.enter'],
+  ['backspace', '@astryx.kbd.key.backspace'],
+  ['escape', '@astryx.kbd.key.escape'],
+  ['tab', '@astryx.kbd.key.tab'],
+  ['up', '@astryx.kbd.key.up'],
+  ['down', '@astryx.kbd.key.down'],
+  ['left', '@astryx.kbd.key.left'],
+  ['right', '@astryx.kbd.key.right'],
+  ['plus', '@astryx.kbd.key.plus'],
 ]);
 
-function getKeyLabel(key: string, isMac: boolean): string {
+function getKeyLabel(key: string, isMac: boolean, t: TranslatorFn): string {
   if (key === 'mod') {
-    return isMac ? 'Command' : 'Control';
+    return t(isMac ? '@astryx.kbd.key.command' : '@astryx.kbd.key.control');
   }
-  return KEY_LABEL.get(key) ?? key.toUpperCase();
+  const labelKey = KEY_LABEL.get(key);
+  return labelKey ? t(labelKey) : key.toUpperCase();
 }
 
 function subscribeToPlatformChanges(): () => void {
@@ -164,6 +166,7 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
  * ```
  */
 export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
+  const t = useTranslator();
   const isMac = useSyncExternalStore(
     subscribeToPlatformChanges,
     isApplePlatform,
@@ -186,8 +189,12 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
   // the visual glyphs below are announced meaninglessly by assistive tech.
   const accessibleName = parts
-    .map(({key}) => getKeyLabel(key, isMac))
-    .join(' + ');
+    .map(({key}) => getKeyLabel(key, isMac, t))
+    .reduce(
+      (shortcut, key, index) =>
+        index === 0 ? key : t('@astryx.kbd.shortcut', {shortcut, key}),
+      '',
+    );
 
   return (
     <span
@@ -203,7 +210,7 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
       )}>
       {parts.map(({key, reactKey}) => (
         <kbd key={reactKey} aria-hidden="true" {...stylex.props(styles.kbd)}>
-          {getKeyDisplay(key, isMac)}
+          {getKeyDisplay(key, isMac, t)}
         </kbd>
       ))}
     </span>