Skip to content

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

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

'use client';

/**
 * @file useChatKeyboard.ts
 * @input React refs, the keyboard module's height, focus routes and layout
 *   guide, the stream scroll's lock, the motion engine, the touch query and
 *   layout viewport height
 * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message
 *   area, and the refs for its dock, message area and composer region
 * @position ChatLayout's keyboard behavior (Chat/ChatLayout.tsx); internal
 *
 * The composer sits on the keyboard, as in Messages on iOS. Where the layout
 * guide publishes the keyboard's slide, the dock rides it on the compositor.
 *
 * SYNC: update Chat/ChatLayout.tsx, ChatLayout.doc.mjs and keyboard/README.md
 */

import {useRef, useState, useSyncExternalStore, type RefObject} from 'react';
import {createMotionEngine, type Animator} from '../motion/animator';
import {
  claimTapFocus,
  findTextEntryControl,
  getKeyboardHeight,
  isTextEntryControl,
  refuseFocusReveal,
  subscribeKeyboardHeight,
} from '../keyboard/keyboardHeight';
import {
  getKeyboardLayoutGuide,
  keyboardProfileOf,
} from '../keyboard/keyboardLayoutGuide';
import {
  deliverTap,
  followsKeyboard,
  watchPans,
} from '../keyboard/keyboardTarget';
import type {KeyboardTransition} from '../keyboard/keyboardModel';
import {rideKeyboard} from '../keyboard/rideKeyboard';
import {layoutViewportHeight} from '../utils/layoutViewport';
import {
  useInteractionModalityTrackingFor,
  type InteractionModality,
} from '../utils/interactionModality';
import {focusForLastInputTemporarily} from '../utils/focusReturn';
import {isCoarsePointer} from '../utils/coarsePointer';
import {useTouchPresentation} from '../utils/touchPresentation';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {
  isFollowingNewest,
  type UseChatStreamScrollReturn,
} from './useChatStreamScroll';

export interface UseChatKeyboardOptions {
  /** ChatLayout's root. */
  rootRef: RefObject<HTMLElement | null>;
  /** The element that scrolls the transcript (the root, or an outer one). */
  scrollRef: RefObject<HTMLElement | null>;
  /**
   * Whether the root scrolls itself (a sticky dock at its bottom) rather
   * than an outer scroller (a fixed dock at the layout viewport's bottom).
   */
  isSelfScrolling: boolean;
  /**
   * The stream scroll's jump to the newest message (useChatStreamScroll), the
   * owner of the transcript's lock.
   */
  scrollToBottom: UseChatStreamScrollReturn['scrollToBottom'];
}

export interface UseChatKeyboardResult {
  /**
   * The part of the keyboard over the dock, CSS px: the dock's offset from
   * its bottom and the room the message area's end padding adds.
   */
  lift: number;
  /** Callback ref for the dock container. */
  dockRef: (element: HTMLElement | null) => void;
  /** Callback ref for the message area. */
  messagesRef: (element: HTMLElement | null) => void;
  /**
   * Ref for the composer region. Its text taps are claimed, and Done parks
   * focus on it.
   */
  composerRef: RefObject<HTMLDivElement | null>;
}

// The lift the layout shows: a store the ride's end and keyboard reports
// write, and render reads.
function createLiftStore() {
  let value = 0;
  const listeners = new Set<() => void>();
  return {
    get: () => value,
    set: (next: number) => {
      if (next !== value) {
        value = next;
        for (const listener of listeners) {
          listener();
        }
      }
    },
    subscribe: (listener: () => void) => {
      listeners.add(listener);
      return () => {
        listeners.delete(listener);
      };
    },
  };
}

// Controls inside the composer's text (a token's button or link, an island
// that is not editable) keep their own taps, as ChatComposer's click-to-focus
// leaves them.
const OWN_TAPS =
  '[contenteditable="false"], button, a, [role="button"], [data-astryx-token]';

/**
 * The composer's text a touch landed in, when that tap would bring up the
 * keyboard and the text has no focus yet. It is contenteditable text, or a
 * text control passed as the composer's input. The browser would reveal
 * either by scrolling the page. Exported for its tests.
 */
export function editableToClaim(target: unknown): HTMLElement | null {
  let node = target as Node | null;
  if (node != null && node.nodeType !== 1) {
    node = node.parentNode;
  }
  const element = node as Element | null;
  if (element == null || typeof element.closest !== 'function') {
    return null;
  }
  const editable = isTextEntryControl(element)
    ? element
    : element.closest<HTMLElement>(
        '[contenteditable]:not([contenteditable="false"])',
      );
  if (editable == null || !isTextEntryControl(editable)) {
    return null;
  }
  const own = element.closest(OWN_TAPS);
  if (own != null && editable.contains(own)) {
    return null;
  }
  const active = editable.ownerDocument.activeElement;
  return active === editable || editable.contains(active) ? null : editable;
}

/**
 * Done's park: focus rests on the composer region. It is focusable for the
 * park alone, so a click or a tap beside the composer never focuses it. The
 * region gives the focus stop up as soon as focus leaves it. It shows the
 * focus ring only after keyboard input, as other script focus does.
 */
function parkFocus(region: HTMLElement, modality: InteractionModality): void {
  // WebKit ignores `focusVisible: false`, so a park after touch input also
  // hides the ring inline until focus leaves.
  if (modality !== 'keyboard') {
    region.style.setProperty('outline', 'none');
    region.addEventListener(
      'blur',
      () => region.style.removeProperty('outline'),
      {once: true},
    );
  }
  focusForLastInputTemporarily(region, {preventScroll: true}, modality);
}

/**
 * Keeps ChatLayout's composer on top of the software keyboard.
 *
 * @example
 * ```
 * const keyboard = useChatKeyboard({rootRef, scrollRef, isSelfScrolling, scrollToBottom});
 * <div ref={keyboard.messagesRef} {...stylex.props(styles.messages(keyboard.lift))}>…</div>
 * <div ref={keyboard.dockRef} {...stylex.props(styles.dock(keyboard.lift))}>
 *   <div ref={keyboard.composerRef}>…</div>
 * </div>
 * ```
 */
export function useChatKeyboard({
  rootRef,
  scrollRef,
  isSelfScrolling,
  scrollToBottom,
}: UseChatKeyboardOptions): UseChatKeyboardResult {
  const dock = useElementAnimator();
  const messages = useElementAnimator();
  const composerRef = useRef<HTMLDivElement>(null);
  // The lift the layout shows (read in render, so styles carry it) and its
  // mirror for the handlers below.
  const [liftStore] = useState(createLiftStore);
  const lift = useSyncExternalStore(
    liftStore.subscribe,
    liftStore.get,
    liftStore.get,
  );
  const liftRef = useRef(0);
  // Set while the guide's ride is under way: the layout waits for it. Each
  // ride's number, so only the latest one hands its translate back.
  const ridingRef = useRef(false);
  const rideRef = useRef(0);
  // Where the last ride took the dock's and the transcript's translates
  // (null: the transcript did not ride), until the layout takes them over.
  const dockTargetRef = useRef<number | null>(null);
  const messagesTargetRef = useRef<number | null>(null);
  // Whether the transcript followed its newest message, and where it was
  // scrolled, just before the layout's last change.
  const atEndRef = useRef(false);
  const scrollBeforeRef = useRef(0);
  const touchPresentation = useTouchPresentation();
  const readModality = useInteractionModalityTrackingFor(composerRef);

  const isTouch = touchPresentation.isTouch;

  // Synchronizes the layout with the keyboard: it subscribes to the layout
  // guide's transitions for the ride, and takes the height a mount finds.
  useIsomorphicLayoutEffect(() => {
    const root = rootRef.current;
    const win = root?.ownerDocument.defaultView;
    if (root == null || win == null) {
      return undefined;
    }
    // A sticky dock rests at the root's bottom edge, which may sit above or
    // below the layout viewport's; a fixed dock rests at the viewport's.
    // While a keyboard is up the dock rises until it clears the keyboard's
    // cover; without one it rests where the layout puts it.
    const liftFor = (inset: number) => {
      if (inset <= 0) {
        return 0;
      }
      // In layout px, as the root's rect is, under a pinch zoom too.
      const viewportBottom = layoutViewportHeight(win);
      const bottom = isSelfScrolling
        ? root.getBoundingClientRect().bottom
        : viewportBottom;
      return Math.max(0, bottom - (viewportBottom - inset));
    };
    // The stream scroll's lock decides whether the transcript follows its
    // newest message, as it does for new content. Its mark changes with the
    // lock, before any render.
    const isAtEnd = () => {
      const scroller = scrollRef.current;
      return scroller != null && isFollowingNewest(scroller);
    };
    // The layout takes the keyboard height's lift once no ride is under way.
    const commit = () => {
      if (ridingRef.current) {
        return;
      }
      const next = liftFor(getKeyboardHeight(win));
      if (Math.abs(next - liftRef.current) < 0.5) {
        return;
      }
      atEndRef.current = isAtEnd();
      scrollBeforeRef.current = scrollRef.current?.scrollTop ?? 0;
      liftStore.set(next);
    };

    // The ride plays the curve the guide publishes with each transition: the
    // keyboard's own motion. These are values, not motion roles, since the
    // system moves the keyboard on them whatever the page does.
    const follow = (transition: KeyboardTransition) => {
      // The ride: the dock goes where the guide says the keyboard will be,
      // from the keyboard's start, relative to the layout it rests in now.
      const target = liftRef.current - liftFor(transition.to);
      const atEnd = isAtEnd();
      dockTargetRef.current = target;
      messagesTargetRef.current = atEnd ? target : null;
      if (!transition.animated) {
        rideRef.current += 1;
        ridingRef.current = false;
        dock.animator.set({y: target});
        if (atEnd) {
          messages.animator.set({y: target});
        }
        commit();
        return;
      }
      // Under Reduce Motion the animator's default applies: no travel, a
      // cross-fade on a touch screen.
      const shown = {y: target};
      ridingRef.current = true;
      rideRef.current += 1;
      const ride = rideRef.current;
      // On the keyboard's own motion: Gboard's slide.
      const rides = [
        rideKeyboard(dock.animator, shown, transition)?.finished ??
          Promise.resolve(true),
      ];
      if (atEnd) {
        rides.push(
          rideKeyboard(messages.animator, shown, transition)?.finished ??
            Promise.resolve(true),
        );
      }
      void Promise.all(rides)
        .then(async done => {
          // A newer ride took over: it commits when it ends.
          if (!done.every(Boolean) || ride !== rideRef.current) {
            return;
          }
          // Hand back only once the presented animations are over too. So a
          // paused animation, as an inspector holds, is never left on top of
          // the new layout.
          const element = dock.animator.element;
          await Promise.all(
            (element?.getAnimations?.() ?? []).map(async animation =>
              animation.finished.catch(() => undefined),
            ),
          );
          if (ride === rideRef.current) {
            ridingRef.current = false;
            commit();
          }
        })
        .catch(() => undefined);
    };
    // The ride attaches only under a coarse primary pointer, where the guide
    // publishes the keyboard's own slide: Gboard's, in Chrome on Android.
    // Elsewhere the layout follows the height alone.
    const unsubscribe =
      isTouch && keyboardProfileOf(win) === 'chromium'
        ? getKeyboardLayoutGuide(win).subscribe(follow)
        : undefined;
    // A height change the guide has no ride for, as for a resize or a
    // rotation, takes its lift at once. This listener comes after the guide's,
    // so a ride claims the change first.
    let reportedHeight = getKeyboardHeight(win);
    const unsubscribeHeight = subscribeKeyboardHeight(win, event => {
      if (event.type === 'viewport' && event.height !== reportedHeight) {
        reportedHeight = event.height;
        commit();
      }
    });
    // Mounted under a keyboard that is already up: take its place at once.
    commit();
    return () => {
      unsubscribeHeight();
      unsubscribe?.();
      ridingRef.current = false;
    };
  }, [
    rootRef,
    scrollRef,
    isSelfScrolling,
    isTouch,
    dock.animator,
    messages.animator,
    liftStore,
  ]);

  // Synchronizes the dock's and the transcript's translates, and the
  // transcript's scroll, with the lift the layout just took. The translates
  // take the difference, so nothing moves on screen. The newest message stays
  // in view.
  useIsomorphicLayoutEffect(() => {
    const moved = lift - liftRef.current;
    if (Math.abs(moved) < 0.5) {
      return;
    }
    liftRef.current = lift;
    const dockTarget = dockTargetRef.current;
    const messagesTarget = messagesTargetRef.current;
    dockTargetRef.current = null;
    messagesTargetRef.current = null;
    // A ride that ended hands its translate (its target) to the layout; a
    // change no ride covered (a resize) is the layout's alone.
    if (dockTarget != null) {
      dock.animator.set({y: dockTarget + moved});
    }
    const scroller = scrollRef.current;
    if (scroller == null) {
      return;
    }
    // WebKit counts a translated transcript in the scroller's range. So the
    // ride's translate goes before the scroll is set. Otherwise the scroll
    // can stop past the content's end, and the sticky dock rises to meet it.
    if (messagesTarget != null) {
      messages.animator.set({y: 0});
    }
    if (atEndRef.current) {
      scrollToBottom({behavior: 'instant'});
    }
    // The padding's change may have clamped the scroll already: measure from
    // where it was before the layout changed.
    const shifted = scroller.scrollTop - scrollBeforeRef.current;
    if (messagesTarget != null && Math.abs(messagesTarget + shifted) >= 0.5) {
      messages.animator.set({y: messagesTarget + shifted});
    }
  }, [lift, scrollRef, dock.animator, messages.animator, scrollToBottom]);

  // Synchronizes the keyboard module's tap route on the composer with the
  // touch presentation. A tap on the composer's text that would bring up the
  // keyboard takes that route. It focuses here without Safari's reveal,
  // with the caret where the finger lifted, and raises the tap's click once.
  // Under a fine primary pointer no touch listener is registered. Inside an
  // iframe nothing changes.
  useIsomorphicLayoutEffect(() => {
    const composer = composerRef.current;
    const win = composer?.ownerDocument.defaultView ?? null;
    if (
      !touchPresentation.isTouch ||
      composer == null ||
      !followsKeyboard(win)
    ) {
      return undefined;
    }
    return claimTapFocus(composer, {
      claim: editableToClaim,
      deliver: deliverTap,
    });
  }, [touchPresentation.isTouch]);

  // A browser that reveals the composer itself pans the visual viewport after
  // the keyboard's report, while the composer still rides up. Chrome 124 on
  // Android pans by the keyboard's whole height. The keyboard module's
  // reveal-pan watch puts the pan back, so the page does not move.
  // Synchronizes the keyboard module's reports, under a finger only.
  useIsomorphicLayoutEffect(() => {
    const composer = composerRef.current;
    const win = composer?.ownerDocument.defaultView ?? null;
    if (
      !touchPresentation.isTouch ||
      composer == null ||
      !followsKeyboard(win)
    ) {
      return undefined;
    }
    const pans = watchPans(win, focused => composer.contains(focused));
    const unsubscribe = subscribeKeyboardHeight(win, event => {
      if (event.type === 'viewport') {
        pans.report(event.height);
      }
    });
    return () => {
      unsubscribe();
      pans.stop();
    };
  }, [touchPresentation.isTouch]);

  // Synchronizes the keyboard module's focus takeover, and the region's group
  // role, with the touch presentation. Every other move into the composer's
  // text takes it, under a finger only and where the keyboard is measured. A
  // desktop browser keeps its own focus. The pointer is read again on every
  // blur, so a tablet that docks a mouse drops the takeover. When Done ends
  // entry, focus moves to the composer region, a group that is no tab stop.
  // The next tap or Tab then starts from the composer.
  useIsomorphicLayoutEffect(() => {
    const composer = composerRef.current;
    const win = composer?.ownerDocument.defaultView ?? null;
    if (
      !touchPresentation.isTouch ||
      composer == null ||
      !followsKeyboard(win)
    ) {
      return undefined;
    }
    // The region is a group only while it is the park's target. It has no
    // accessible name: the layout names none of the caller's regions.
    composer.setAttribute('role', 'group');
    const stopTakeover = refuseFocusReveal(composer.ownerDocument, {
      isActive: () => isCoarsePointer(win),
      claim: destination => findTextEntryControl(destination, composer),
      park: origin => {
        if (findTextEntryControl(origin, composer) != null) {
          parkFocus(composer, readModality());
        }
      },
    });
    return () => {
      stopTakeover();
      composer.removeAttribute('role');
    };
  }, [touchPresentation.isTouch, readModality]);

  return {
    lift,
    dockRef: dock.ref,
    messagesRef: messages.ref,
    composerRef,
  };
}

/** A compositor animator for one element, bound through a stable callback ref. */
function useElementAnimator(): {
  readonly ref: (element: HTMLElement | null) => void;
  readonly animator: Animator;
} {
  const [result] = useState(() => {
    const animator = createMotionEngine(null);
    return {
      animator,
      ref: (element: HTMLElement | null) => animator.attach(element),
    };
  });
  return result;
}