@astryxdesign/core 0.7.5 → 0.7.6-canary.bb18c81

package/src/TopNav/TopNav.test.tsx

@@ -377,6 +377,33 @@ describe('TopNavHeading', () => {
       );
     });
 
+    it('moves focus one item per arrow key in a NavHeadingMenu (APG menu)', async () => {
+      __resetMenuPressForTest();
+      const user = userEvent.setup();
+      render(
+        <TopNavHeading
+          heading="My App"
+          menu={
+            <NavHeadingMenu>
+              <NavHeadingMenuItem label="One" onClick={() => {}} />
+              <NavHeadingMenuItem label="Two" onClick={() => {}} />
+              <NavHeadingMenuItem label="Three" onClick={() => {}} />
+            </NavHeadingMenu>
+          }
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Open menu'}));
+      const item = (name: string) =>
+        screen.getByRole('menuitem', {name, hidden: true});
+      item('One').focus();
+      fireEvent.keyDown(item('One'), {key: 'ArrowDown'});
+      expect(item('Two')).toHaveFocus();
+      fireEvent.keyDown(item('Two'), {key: 'ArrowDown'});
+      expect(item('Three')).toHaveFocus();
+      fireEvent.keyDown(item('Three'), {key: 'ArrowUp'});
+      expect(item('Two')).toHaveFocus();
+    });
+
     it('after a pointer pick, returns focus to the trigger without a keyboard ring (interaction-modality INV1)', async () => {
       __resetMenuPressForTest();
       const user = userEvent.setup();

package/src/Typeahead/Typeahead.test.tsx

@@ -2822,3 +2822,43 @@ describe('Typeahead consumer key handler target', () => {
     expect(onKeyDown).toHaveBeenCalledOnce();
   });
 });
+
+describe('Typeahead caller aria-labelledby', () => {
+  it('names the input by its label and a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="billing-heading">Billing</span>
+        <Typeahead
+          label="Fruit"
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          aria-labelledby="billing-heading"
+        />
+      </>,
+    );
+    expect(
+      screen.getByRole('combobox', {name: 'Fruit Billing'}),
+    ).toBeInTheDocument();
+  });
+
+  it('names a grouped input by the group, its label, and a caller aria-labelledby', () => {
+    render(
+      <>
+        <span id="billing-heading">Billing</span>
+        <InputGroup label="Contact">
+          <Typeahead
+            label="Fruit"
+            searchSource={fruitSource}
+            value={null}
+            onChange={() => {}}
+            aria-labelledby="billing-heading"
+          />
+        </InputGroup>
+      </>,
+    );
+    expect(
+      screen.getByRole('combobox', {name: 'Contact Fruit Billing'}),
+    ).toBeInTheDocument();
+  });
+});

package/src/Typeahead/Typeahead.tsx

@@ -63,6 +63,7 @@ import {
   isImeKeyEvent,
   mergeProps,
 } from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {TrailingKeyDownContext} from './trailingKeyDown';
 import {
   type FieldInputBaseProps,
@@ -416,6 +417,7 @@ export function Typeahead<T extends SearchableItem>({
   controlStyle,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TypeaheadProps<T>) {
   const {rest, container} = useFieldInputStyling('Typeahead', restProps, {
@@ -428,6 +430,7 @@ export function Typeahead<T extends SearchableItem>({
   const generatedInputId = useId();
   const inputId = idProp ?? generatedInputId;
   const inputLabelId = useId();
+  const fieldLabelId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
@@ -609,6 +612,13 @@ export function Typeahead<T extends SearchableItem>({
     inputGroup,
   );
 
+  // A caller aria-labelledby names the input together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const inputLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelId, ariaLabelledByProp)
+      : ariaLabelledBy;
+
   const sizeStyle = wrapperSizeStyles[size];
 
   const typeaheadContent = (
@@ -684,7 +694,7 @@ export function Typeahead<T extends SearchableItem>({
                     .filter(Boolean)
                     .join(' ') || undefined
                 }
-                ariaLabelledBy={ariaLabelledBy}
+                ariaLabelledBy={inputLabelledBy}
                 onChangeQuery={onChangeQuery}
                 onOpenChange={onOpenChange}
                 debounceMs={debounceMs}
@@ -735,6 +745,7 @@ export function Typeahead<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
+      labelID={ariaLabelledByProp != null ? fieldLabelId : undefined}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/gestures/PinchGestureRecognizer.ts

@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file PinchGestureRecognizer.ts
+ * @input Touches from a GestureArena
+ * @output Exports PinchGestureRecognizer (UIPinchGestureRecognizer) and its
+ *   options
+ * @position Continuous two-finger recognizer of packages/core/src/gestures
+ *
+ * Tracks the first two fingers; more are ignored. Begins once the distance
+ * between them has changed by `hysteresis` px. As in UIKit, `scale` is then
+ * the current distance over the starting distance moved by the hysteresis
+ * toward the pinch, so it does not jump (settable to re-base it); `velocity`
+ * is scale per second. Lifting either finger ends an
+ * active pinch and fails a possible one.
+ *
+ * A host gives every element WITHOUT a pinch recognizer `pinch-zoom` in its
+ * `touch-action`, so the page stays zoomable (WCAG 1.4.4); attaching one
+ * takes the two-finger gesture for this element only.
+ */
+
+import {UIKIT_PINCH} from '../motion/uikit/gestures';
+import {centroid, distance} from './geometry';
+import {
+  GestureRecognizer,
+  isActive,
+  type GestureRecognizerOptions,
+  type NativeTouchBehavior,
+} from './GestureRecognizer';
+import type {GestureEventContext, GestureTouch, Point} from './types';
+import {VelocityTracker} from './VelocityTracker';
+
+export interface PinchGestureRecognizerOptions extends GestureRecognizerOptions<PinchGestureRecognizer> {
+  hysteresis?: number;
+}
+
+export class PinchGestureRecognizer extends GestureRecognizer {
+  hysteresis: number;
+  private initialSpan = 0;
+  private scaleValue = 1;
+  private readonly tracker = new VelocityTracker();
+  private lastTime = 0;
+
+  constructor(options: PinchGestureRecognizerOptions = {}) {
+    super(options);
+    this.hysteresis = options.hysteresis ?? UIKIT_PINCH.hysteresis.value;
+  }
+
+  /** Current span over the span the fingers started at. */
+  get scale(): number {
+    return this.scaleValue;
+  }
+
+  /** Re-base: from now on the scale reads `value` at the current span. */
+  set scale(value: number) {
+    const span = this.span();
+    if (span > 0 && value > 0) {
+      this.initialSpan = span / value;
+      this.scaleValue = value;
+      // The velocity continues from the re-based value, without a jump.
+      this.tracker.reset();
+      this.tracker.add(value, 0, this.lastTime);
+    }
+  }
+
+  /** Scale per second (UIKit's filter; measured for pans, assumed here). */
+  get velocity(): number {
+    return this.tracker.velocity().x;
+  }
+
+  /** The midpoint between the two fingers. */
+  focalPoint(): Point {
+    return centroid(this.touches.values());
+  }
+
+  /** Two fingers on this view are this recognizer's, not the browser's zoom. */
+  override get nativeTouchBehavior(): NativeTouchBehavior {
+    return {panX: true, panY: true, pinchZoom: false, doubleTapZoom: false};
+  }
+
+  protected override acceptsTouch(touch: GestureTouch): boolean {
+    return this.numberOfTouches < 2 && super.acceptsTouch(touch);
+  }
+
+  protected override touchesBegan(
+    _touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    this.lastTime = event.time;
+    if (this.numberOfTouches === 2) {
+      this.initialSpan = this.span();
+      this.scaleValue = 1;
+      this.tracker.reset();
+      this.tracker.add(1, 0, event.time);
+    }
+  }
+
+  protected override touchesMoved(
+    _touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    if (this.numberOfTouches < 2 || this.initialSpan <= 0) {
+      return;
+    }
+    this.lastTime = event.time;
+    const span = this.span();
+    // Once recognized, a pinch waiting on a recognizer it requires to fail
+    // keeps its re-based start: its moves only follow the fingers.
+    if (this.state === 'possible' && this.pending == null) {
+      if (Math.abs(span - this.initialSpan) >= this.hysteresis) {
+        // UIKit measures from the start moved by the hysteresis, and its
+        // first velocity spans from the touch-down (scale 1) to here.
+        this.initialSpan +=
+          Math.sign(span - this.initialSpan) * this.hysteresis;
+        this.scaleValue = span / this.initialSpan;
+        this.tracker.add(this.scaleValue, 0, event.time);
+        this.setState('began');
+      }
+      return;
+    }
+    this.scaleValue = span / this.initialSpan;
+    // Every move of the fingers is a sample: a span that holds while they
+    // move reads as no change, so the velocity never goes stale.
+    this.tracker.add(this.scaleValue, 0, event.time, {isMotion: true});
+    if (isActive(this.state)) {
+      this.setState('changed');
+    }
+  }
+
+  protected override touchesEnded(): void {
+    this.setState(isActive(this.state) ? 'ended' : 'failed');
+  }
+
+  protected override reset(): void {
+    this.initialSpan = 0;
+    this.scaleValue = 1;
+    this.tracker.reset();
+  }
+
+  private span(): number {
+    const [a, b] = this.trackedTouches;
+    return a == null || b == null ? 0 : distance(a, b);
+  }
+}

package/src/gestures/ScreenEdgePanGestureRecognizer.ts

@@ -0,0 +1,252 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ScreenEdgePanGestureRecognizer.ts
+ * @input Touches from a GestureArena; the viewport size and writing
+ *   direction from its environment
+ * @output Exports ScreenEdgePanGestureRecognizer
+ *   (UIScreenEdgePanGestureRecognizer), its options and edge type
+ * @position Continuous recognizer of packages/core/src/gestures, a pan that
+ *   only starts from a band at the edge of the viewport
+ *
+ * A touch that lands outside every requested band fails at once, so a
+ * recognizer that requires this one to fail is not held up by a touch in the
+ * middle of the screen. Inside a band, the pan begins on movement away from
+ * that edge. `leading` and `trailing` resolve against the view's writing
+ * direction: under RTL the leading edge is the right one, as the
+ * interactive pop gesture's is.
+ *
+ * Attach it to the edge zone: an element that lies within the band at its
+ * edge. There the pan takes the horizontal axis from the browser, which has
+ * nothing to scroll in so thin a band, so a touch in the band decides at
+ * UIKit's 15 px screen-edge hysteresis. On any other view, whose
+ * `touch-action` cannot claim per touch, it leaves the browser every touch
+ * behavior, so the author's scrolling there is untouched, and a touch in the
+ * band decides at FR19's 10 px like every other claim (spec:AST-094 FR18,
+ * DEC-22). The edges' physical sides and the edge zone are measured once,
+ * together, and serve both the element's `touch-action` and the touch-down
+ * decision; the host reports a layout change (layoutChanged), and a changed
+ * answer is announced (onTouchBehaviorChange) so `touch-action` follows it
+ * (FR19). The writing direction is read again at each touch-down: a view
+ * switched to RTL in place, with no resize, is measured again there and the
+ * change announced, so a `leading` back swipe follows the new leading edge
+ * (`design:bidirectionality` DR13). That touch landed under the touch-action
+ * from before, so it decides at FR19's 10 px unless that one claimed the
+ * axis.
+ */
+
+import {UIKIT_PAN, UIKIT_SCREEN_EDGE_PAN} from '../motion/uikit/gestures';
+import {ALL_NATIVE_TOUCH, type NativeTouchBehavior} from './GestureRecognizer';
+import {
+  PanGestureRecognizer,
+  type PanGestureRecognizerOptions,
+} from './PanGestureRecognizer';
+import type {GestureEventContext, GestureTouch} from './types';
+
+/**
+ * How far past `edgeRegion` a view still counts as the edge zone, px: layout
+ * snaps sizes to 1/64 px, so a strip authored at the region measures a hair
+ * wider; half a pixel takes that and nothing a pixel wider.
+ */
+const EDGE_ZONE_TOLERANCE = 0.5;
+
+/**
+ * An edge by writing direction: under RTL the leading edge is the right one.
+ * Top and bottom edges land with their first user.
+ */
+export type ScreenEdge = 'leading' | 'trailing';
+
+/** A physical horizontal edge of the viewport. */
+type PhysicalEdge = 'left' | 'right';
+
+/**
+ * What the pan measures of its view, once until a layout change: the
+ * writing direction it read, the physical sides its edges resolve to under
+ * that direction, and the sides whose band the view lies within.
+ */
+interface EdgeLayout {
+  readonly isRtl: boolean;
+  readonly watched: ReadonlyArray<PhysicalEdge>;
+  readonly zone: ReadonlySet<PhysicalEdge>;
+}
+
+/**
+ * A screen-edge pan is a finger's: it takes no `allowedPointerTypes`
+ * (`spec:AST-094` FR43).
+ */
+export interface ScreenEdgePanGestureRecognizerOptions extends Omit<
+  PanGestureRecognizerOptions,
+  'direction' | 'allowedPointerTypes'
+> {
+  /** The edges a touch may start from. @default ['leading'] */
+  edges?: ReadonlyArray<ScreenEdge>;
+  /** Width of the band at each edge, px. */
+  edgeRegion?: number;
+}
+
+export class ScreenEdgePanGestureRecognizer extends PanGestureRecognizer {
+  edges: ReadonlyArray<ScreenEdge>;
+  edgeRegion: number;
+  /** The physical edge the current gesture started from. */
+  activeEdge: PhysicalEdge | null = null;
+  /**
+   * @internal Set by the host while attached: called when the edge-zone
+   * answer changes, so the element's `touch-action` follows it
+   * (spec:AST-094 FR19, DEC-22).
+   */
+  onTouchBehaviorChange: (() => void) | null = null;
+  /** The hysteresis where the pan takes its axis (UIKit's 15 px). */
+  private readonly edgeHysteresis: number;
+  /** What the pan measured of its view (see EdgeLayout), until a layout change. */
+  private layout: EdgeLayout | null = null;
+
+  constructor(options: ScreenEdgePanGestureRecognizerOptions = {}) {
+    super({
+      maximumNumberOfTouches: 1,
+      hysteresis: UIKIT_SCREEN_EDGE_PAN.hysteresis.value,
+      ...options,
+      // A finger's only: under a mouse, a trackpad or a pen the screen-edge
+      // pan stays off (`spec:AST-094` FR43), whatever a caller passes.
+      allowedPointerTypes: ['touch'],
+    });
+    this.edges = options.edges ?? ['leading'];
+    this.edgeRegion =
+      options.edgeRegion ?? UIKIT_SCREEN_EDGE_PAN.edgeRegion.value;
+    this.edgeHysteresis = this.hysteresis;
+  }
+
+  /**
+   * The pan takes the horizontal axis only in its edge zone, a view within
+   * the band of an edge it watches; elsewhere it leaves the browser every
+   * touch behavior, so the author's scrolling is untouched (spec:AST-094
+   * FR18), never claiming across a whole wider element.
+   */
+  override get nativeTouchBehavior(): NativeTouchBehavior {
+    const {watched, zone} = this.measured();
+    if (!watched.some(edge => zone.has(edge))) {
+      return ALL_NATIVE_TOUCH;
+    }
+    return {
+      panX: false,
+      panY: true,
+      pinchZoom: true,
+      doubleTapZoom: false,
+    };
+  }
+
+  /**
+   * @internal Whether the edge zone depends on the viewport's width: the pan
+   * watches the right side, whose band moves with the viewport, so the host
+   * reports a viewport resize to it as well as its own box's (FR19, FR24).
+   */
+  get watchesViewport(): boolean {
+    return this.measured().watched.includes('right');
+  }
+
+  /**
+   * @internal The view's box may have changed (a resize): its edges' sides
+   * and the edge zone are measured again, and a changed answer calls
+   * onTouchBehaviorChange.
+   */
+  layoutChanged(): void {
+    const before = this.layout;
+    this.layout = null;
+    const after = this.measured();
+    if (
+      before == null ||
+      before.watched.join() !== after.watched.join() ||
+      before.zone.size !== after.zone.size ||
+      [...after.zone].some(edge => !before.zone.has(edge))
+    ) {
+      this.onTouchBehaviorChange?.();
+    }
+  }
+
+  protected override touchesBegan(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    if (this.numberOfTouches === touches.length) {
+      // The touch-action the browser applies to this touch was derived from
+      // the layout in force as it landed: whether that claimed the axis.
+      const inForce = this.measured();
+      const claimedAxis = inForce.watched.some(side => inForce.zone.has(side));
+      // A direction switched in place (no resize) moves the leading edge:
+      // measure again, and announce it so touch-action follows for the next
+      // touch (DR13).
+      if (inForce.isRtl !== this.environment.isRtl(this.view)) {
+        this.layoutChanged();
+      }
+      const edge = this.edgeAt(touches[0]);
+      if (edge == null) {
+        this.setState('failed');
+        return;
+      }
+      this.activeEdge = edge;
+      // On an element within the band, which takes the axis across the edge,
+      // a touch decides at UIKit's 15 px; on any other, which leaves the
+      // browser that axis, at FR19's 10 px, before the browser commits to a
+      // scroll (spec:AST-094 FR18, DEC-22). The answer is the one this
+      // touch's touch-action was derived from: a touch that measured again
+      // decides at 10 px unless the layout in force claimed the axis.
+      const offZone = !claimedAxis || !this.measured().zone.has(edge);
+      this.hysteresis = offZone
+        ? Math.min(this.edgeHysteresis, UIKIT_PAN.hysteresis.value)
+        : this.edgeHysteresis;
+      this.direction = edge === 'left' ? 'right' : 'left';
+    }
+    super.touchesBegan(touches, event);
+  }
+
+  /**
+   * The physical sides the pan's edges resolve to under the view's writing
+   * direction, and the sides whose band the view lies within, measured
+   * together once until a layout change: the view starts at that side and
+   * reaches no farther than `edgeRegion` from it, within layout's rounding
+   * (a strip authored at the 40.2 px region lays out at 40.203 px, on
+   * 1/64 px). A view that cannot be measured lies within none.
+   */
+  private measured(): EdgeLayout {
+    if (this.layout != null) {
+      return this.layout;
+    }
+    const isRtl = this.environment.isRtl(this.view);
+    const watched = this.edges.map(edge =>
+      (edge === 'leading') !== isRtl ? 'left' : 'right',
+    );
+    const zone = new Set<PhysicalEdge>();
+    const rect = this.environment.viewRect?.(this.view);
+    if (rect != null && rect.width > 0) {
+      const {width} = this.environment.viewportSize();
+      const right = rect.left + rect.width;
+      const band = this.edgeRegion + EDGE_ZONE_TOLERANCE;
+      if (rect.left >= -EDGE_ZONE_TOLERANCE && right <= band) {
+        zone.add('left');
+      }
+      if (rect.left >= width - band && right <= width + EDGE_ZONE_TOLERANCE) {
+        zone.add('right');
+      }
+    }
+    this.layout = {isRtl, watched, zone};
+    return this.layout;
+  }
+
+  protected override reset(): void {
+    super.reset();
+    this.activeEdge = null;
+  }
+
+  private edgeAt(touch: GestureTouch): PhysicalEdge | null {
+    const {width} = this.environment.viewportSize();
+    for (const physical of this.measured().watched) {
+      const inBand =
+        physical === 'left'
+          ? touch.startX <= this.edgeRegion
+          : touch.startX >= width - this.edgeRegion;
+      if (inBand) {
+        return physical;
+      }
+    }
+    return null;
+  }
+}