@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/keyboard/keyboardLayoutGuide.ts

@@ -0,0 +1,266 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file keyboardLayoutGuide.ts
+ * @input The keyboard module's reports (subscribeKeyboardHeight) and
+ *   createKeyboardModel
+ * @output getKeyboardLayoutGuide (a window's one guide), bringsUpKeyboard and
+ *   the KeyboardLayoutGuide type
+ * @position The web's UIKeyboardLayoutGuide: where the software keyboard
+ *   covers the layout viewport and how it moves. Touch presentations read it
+ *   to keep content above the keyboard. It is internal to core.
+ *
+ * SYNC: When modified, update /packages/core/src/keyboard/README.md
+ */
+
+import {
+  getKeyboardHeight,
+  isTextEntryControl,
+  subscribeKeyboardHeight,
+  type KeyboardHeightEvent,
+} from './keyboardHeight';
+import {
+  createKeyboardModel,
+  type KeyboardModel,
+  type KeyboardProfile,
+  type KeyboardTransition,
+} from './keyboardModel';
+
+/**
+ * Whose keyboard schedule the guide reads: `chromium` where the browser has
+ * the VirtualKeyboard API, else null. Without the profile, no surface rides
+ * the guide. Chrome reports the keyboard as each slide starts. The profile is
+ * a capability, never the user agent. motion/android/keyboard.ts holds the
+ * measured timing.
+ */
+export function keyboardProfileOf(win: Window): KeyboardProfile | null {
+  return 'virtualKeyboard' in win.navigator ? 'chromium' : null;
+}
+
+/** A window's keyboard layout guide. */
+export interface KeyboardLayoutGuide {
+  /** The inset the keyboard rests at (or is heading to), CSS px. */
+  readonly inset: number;
+  /** The latest transition. */
+  readonly transition: KeyboardTransition;
+  /** The inset presented at `time` (default now), CSS px. */
+  presentation(time?: number): number;
+  /**
+   * Calls `listener` with every transition, inside the event that revealed
+   * it, until the caller runs the returned function.
+   */
+  subscribe(listener: (transition: KeyboardTransition) => void): () => void;
+  /** Whose keyboard schedule the guide reads (keyboardProfileOf). */
+  readonly profile: KeyboardProfile | null;
+}
+
+// Extra time after a predicted transition's end before checking it.
+const VERIFY_SLACK_MS = 150;
+// How long after a field gains focus Chrome may still report the keyboard
+// gone for a moment (measured: back within 50 ms of the move).
+const FOCUS_HANDOFF_MS = 150;
+
+// Controls whose picker Chrome on Android opens over the page while the
+// keyboard goes away; on iOS the picker takes the keyboard's place.
+const PICKER_INPUT_TYPES = new Set([
+  'date',
+  'datetime-local',
+  'month',
+  'time',
+  'week',
+]);
+
+/**
+ * Whether focusing `target` brings up a software keyboard (or another input
+ * view in its place, as a select's picker does).
+ */
+export function bringsUpKeyboard(target: EventTarget | null): boolean {
+  const element = target instanceof Element ? target : null;
+  return (
+    isTextEntryControl(element) ||
+    (element instanceof HTMLSelectElement && !element.disabled)
+  );
+}
+
+// Whether `target` is a select, or a date or time field, which Chrome on
+// Android edits in a picker over the page.
+function opensPickerOverPage(target: EventTarget | null): boolean {
+  const element = target as HTMLElement | null;
+  if (element == null || element.nodeType !== 1) {
+    return false;
+  }
+  return (
+    element.tagName === 'SELECT' ||
+    (element.tagName === 'INPUT' &&
+      PICKER_INPUT_TYPES.has((element as HTMLInputElement).type))
+  );
+}
+
+const guides = new WeakMap<Window, KeyboardLayoutGuide>();
+
+/**
+ * The window's keyboard layout guide, created on first use.
+ *
+ * One guide serves each window. It subscribes to the keyboard module only
+ * while something subscribes to it. It owns no listener and measures nothing.
+ * It feeds the model the module's reports, the keyboard height and the focus
+ * changes that start a hide. It hands each transition to its subscribers.
+ * What it adds is timing: when a show started, a hide predicted from the
+ * blur, and the motion in between. Layout follows the keyboard height
+ * itself, and the guide's transitions only time the optional ride on top.
+ *
+ * The model reads Chrome's measured schedule: Chrome reports each slide just
+ * after it starts. A surface rides the guide only where the VirtualKeyboard
+ * API reports the keyboard. Focus can move from one field to another through
+ * something that brings no keyboard, such as a popover's container. Chrome
+ * then reports the keyboard gone for a moment and then back. So a hide
+ * reported while a field that just got focus still has it waits until the
+ * move settles.
+ *
+ * @example
+ * ```
+ * const guide = getKeyboardLayoutGuide(window);
+ * const unsubscribe = guide.subscribe(t => {
+ *   rideKeyboard(animator, {y: -t.to}, t);
+ * });
+ * ```
+ */
+export function getKeyboardLayoutGuide(win: Window): KeyboardLayoutGuide {
+  let guide = guides.get(win);
+  if (guide == null) {
+    guide = createGuide(win);
+    guides.set(win, guide);
+  }
+  return guide;
+}
+
+function createGuide(win: Window): KeyboardLayoutGuide {
+  const listeners = new Set<(transition: KeyboardTransition) => void>();
+  let profile = keyboardProfileOf(win);
+  let model: KeyboardModel = createKeyboardModel(getKeyboardHeight(win));
+  let verifyTimer: ReturnType<typeof setTimeout> | null = null;
+  let detach: (() => void) | null = null;
+
+  const publish = (transition: KeyboardTransition | null) => {
+    if (transition == null) {
+      return;
+    }
+    if (transition.predicted) {
+      scheduleVerify(transition);
+    }
+    for (const listener of [...listeners]) {
+      listener(transition);
+    }
+  };
+  const scheduleVerify = (transition: KeyboardTransition) => {
+    if (verifyTimer != null) {
+      clearTimeout(verifyTimer);
+    }
+    const due =
+      transition.start + (transition.curve?.durationMs ?? 0) + VERIFY_SLACK_MS;
+    verifyTimer = setTimeout(
+      () => {
+        verifyTimer = null;
+        publish(model.verify(getKeyboardHeight(win), win.performance.now()));
+      },
+      Math.max(0, due - win.performance.now()),
+    );
+  };
+
+  const attach = () => {
+    profile = keyboardProfileOf(win);
+    model = createKeyboardModel(getKeyboardHeight(win));
+    // Whether focusing `target` keeps an input view where the keyboard is. On
+    // iOS, a select's picker or a date or time field's picker takes the
+    // keyboard's place. Chrome on Android opens it over the page, and the
+    // keyboard goes away.
+    const keepsInputView = (target: EventTarget | null): boolean =>
+      bringsUpKeyboard(target) &&
+      !(profile === 'chromium' && opensPickerOverPage(target));
+    // When a field that brings up a keyboard last gained focus.
+    let keyboardFocusAt = -Infinity;
+    let handoffTimer: ReturnType<typeof setTimeout> | null = null;
+    const report = (
+      height: number,
+      time: number,
+    ): KeyboardTransition | null => {
+      if (handoffTimer != null) {
+        clearTimeout(handoffTimer);
+        handoffTimer = null;
+      }
+      const settled = keyboardFocusAt + FOCUS_HANDOFF_MS;
+      if (
+        profile === 'chromium' &&
+        height < 0.5 &&
+        model.inset >= 0.5 &&
+        time < settled &&
+        keepsInputView(win.document.activeElement)
+      ) {
+        // Focus just moved to another field: Chrome reports the keyboard
+        // gone before it reports it back. Hold the hide until the move
+        // settles, then believe whatever the keyboard is doing.
+        handoffTimer = setTimeout(() => {
+          handoffTimer = null;
+          publish(model.report(getKeyboardHeight(win), settled));
+        }, settled - time);
+        return null;
+      }
+      return model.report(height, time);
+    };
+    const onReport = (event: KeyboardHeightEvent) => {
+      if (event.type === 'viewport') {
+        publish(report(event.height, event.timeStamp));
+      } else if (event.type === 'focusin') {
+        if (keepsInputView(event.target)) {
+          keyboardFocusAt = event.timeStamp;
+          publish(model.focused(event.timeStamp));
+        }
+      } else if (
+        keepsInputView(event.target) &&
+        !keepsInputView(event.relatedTarget)
+      ) {
+        publish(model.blurred(event.timeStamp));
+      }
+    };
+    const unsubscribe = subscribeKeyboardHeight(win, onReport, {focus: true});
+    return () => {
+      unsubscribe();
+      if (handoffTimer != null) {
+        clearTimeout(handoffTimer);
+        handoffTimer = null;
+      }
+      if (verifyTimer != null) {
+        clearTimeout(verifyTimer);
+        verifyTimer = null;
+      }
+    };
+  };
+
+  return {
+    get profile() {
+      return profile;
+    },
+    get inset() {
+      return model.inset;
+    },
+    get transition() {
+      return model.transition;
+    },
+    presentation(time = win.performance.now()) {
+      return model.presentation(time);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      if (detach == null) {
+        detach = attach();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0 && detach != null) {
+          detach();
+          detach = null;
+        }
+      };
+    },
+  };
+}

package/src/keyboard/keyboardModel.ts

@@ -0,0 +1,301 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file keyboardModel.ts
+ * @input `keyboard` from the Android table: Gboard's slides and Chrome's
+ *   report timings
+ * @output createKeyboardModel, the keyboard layout guide's clock-free core,
+ *   and the KeyboardTransition and KeyboardModel types
+ * @position The state of the keyboard layout guide (keyboardLayoutGuide.ts).
+ *   It infers the keyboard's transition from the visual viewport's reports
+ *   and focus changes, each input with its own time. It is internal to core.
+ *
+ * SYNC: When modified, update /packages/core/src/keyboard/README.md
+ */
+
+import {keyboard as androidKeyboard} from '../motion/android/keyboard';
+import {cubicBezier} from '../motion/bezier';
+
+/** Which browser's keyboard reports the guide reads. */
+export type KeyboardProfile = 'chromium';
+
+/** An eased slide: the curve a transition plays (Gboard going up or down). */
+export interface KeyboardCurve {
+  /** Length, ms. */
+  readonly durationMs: number;
+  /** Cubic-bézier control points. */
+  readonly points: readonly [number, number, number, number];
+}
+
+/** How the keyboard's cover changes. */
+export type KeyboardTransitionKind = 'show' | 'hide' | 'change';
+
+/** One change of the keyboard's cover, as the guide reports it. */
+export interface KeyboardTransition {
+  readonly kind: KeyboardTransitionKind;
+  /** Inset presented at `start`, CSS px. */
+  readonly from: number;
+  /** Inset the keyboard comes to rest at, CSS px. */
+  readonly to: number;
+  /**
+   * When the keyboard starts to move, ms on the document timeline
+   * (`performance.now()`). For a slide Chrome reported, the guide dates it
+   * back to Gboard's start. For a hide after a blur, it is shortly ahead.
+   */
+  readonly start: number;
+  /** The inset's velocity at `start`, px/s (0 unless it interrupts one). */
+  readonly velocity: number;
+  /** False when the inset jumps at `start` (another keyboard while one is up). */
+  readonly animated: boolean;
+  /** True until the visual viewport confirms a transition the guide inferred. */
+  readonly predicted: boolean;
+  /**
+   * The eased slide the keyboard moves on (Gboard in Chrome on Android), or
+   * null when the inset jumps. A surface riding the keyboard plays it from
+   * `start`, as rideKeyboard does. It is the keyboard's own motion, with no
+   * motion role.
+   */
+  readonly curve: KeyboardCurve | null;
+}
+
+/** The guide's clock-free core: inputs carry their own times. */
+export interface KeyboardModel {
+  /** The inset the keyboard rests at (or is heading to), CSS px. */
+  readonly inset: number;
+  /** The latest transition. */
+  readonly transition: KeyboardTransition;
+  /** The inset presented at `time`, CSS px. */
+  presentation(time: number): number;
+  /** The presented inset's velocity at `time`, px/s. */
+  velocity(time: number): number;
+  /**
+   * The visual viewport reports an inset (null when unknown) at `time` (the
+   * event's timestamp). Returns the transition the report starts, if any.
+   */
+  report(inset: number | null, time: number): KeyboardTransition | null;
+  /**
+   * A control that brings up a keyboard lost focus to nothing that brings
+   * up one.
+   */
+  blurred(time: number): KeyboardTransition | null;
+  /** A control that brings up a keyboard gained focus. */
+  focused(time: number): KeyboardTransition | null;
+  /**
+   * Checks a predicted transition against the viewport once it should have
+   * ended; moves to what the viewport says when they disagree.
+   */
+  verify(inset: number | null, time: number): KeyboardTransition | null;
+}
+
+const EPSILON = 0.5;
+
+/** The inset and its velocity, seconds after a transition's start. */
+interface InsetCurve {
+  value(t: number): number;
+  velocity(t: number): number;
+}
+
+/**
+ * Creates the guide's core. Tests drive it with explicit times, and the
+ * window's guide feeds it events.
+ *
+ * Chrome reports each keyboard slide through the visual viewport just after
+ * it starts (README.md, "What the page sees"). Content rides Gboard's own
+ * slides, fitted on Chromium 158 with Gboard (motion/android/keyboard.ts).
+ *
+ * - Show: from the report, dated back `androidKeyboard.showReportLagMs`, on
+ *   `showCurve` over `showMs`, joining the slide where it is. The report's
+ *   first painted frame trails Gboard's first moved frame by 14 to 35 ms. An
+ *   `<input>` that brings an accessory bar first gives a smaller report
+ *   before the keyboard's. It rides to the last keyboard's height instead, as
+ *   a prediction, and the keyboard's report confirms it.
+ * - Hide: on `hideCurve` over `hideMs`. It starts
+ *   `androidKeyboard.hideAfterBlurMs` after a blur that brings no keyboard,
+ *   as a prediction, because Gboard starts down at the blur. When nothing
+ *   predicted it, as with Back, it starts from Chrome's report, dated back
+ *   `hideReportLagMs`, the lag measured on blurs.
+ * - A keyboard that changes while up, such as another keyboard, lays out at
+ *   once.
+ *
+ * A prediction the viewport has not confirmed by its end gives way to what
+ * the viewport says (`verify`).
+ */
+export function createKeyboardModel(initialInset = 0): KeyboardModel {
+  let transition: KeyboardTransition = {
+    kind: 'change',
+    from: initialInset,
+    to: initialInset,
+    start: -Infinity,
+    velocity: 0,
+    animated: false,
+    predicted: false,
+    curve: null,
+  };
+  // The inset over seconds since the transition's start.
+  let curve: InsetCurve | null = null;
+  // An eased slide's value and velocity.
+  const easedCurve = (
+    from: number,
+    to: number,
+    slide: KeyboardCurve,
+  ): InsetCurve => {
+    const span = slide.durationMs / 1000;
+    const ease = cubicBezier(slide.points);
+    const value = (t: number) =>
+      from + (to - from) * ease(Math.min(1, Math.max(0, t / span)));
+    return {
+      value,
+      velocity: (t: number) => {
+        if (t >= span) {
+          return 0;
+        }
+        const a = Math.max(0, t - 0.001);
+        const b = Math.min(span, t + 0.001);
+        return (value(b) - value(a)) / (b - a);
+      },
+    };
+  };
+  // Gboard's slides, as Chrome draws them: the table's show and hide curves.
+  const showSlide: KeyboardCurve = {
+    durationMs: androidKeyboard.showMs,
+    points: androidKeyboard.showCurve,
+  };
+  const hideSlide: KeyboardCurve = {
+    durationMs: androidKeyboard.hideMs,
+    points: androidKeyboard.hideCurve,
+  };
+  // How long the current transition moves for.
+  const lengthOf = () =>
+    transition.curve != null ? transition.curve.durationMs : 0;
+  // The inset of the last keyboard that was up, for a hide that turns back.
+  let shownInset = initialInset;
+
+  const presentation = (time: number): number => {
+    // A jump has happened at its start; a curve starts from `from`.
+    if (time < transition.start) {
+      return transition.from;
+    }
+    if (curve == null || time >= transition.start + lengthOf()) {
+      return transition.to;
+    }
+    return curve.value((time - transition.start) / 1000);
+  };
+  const velocity = (time: number): number => {
+    if (time <= transition.start) {
+      return transition.velocity;
+    }
+    if (curve == null || time >= transition.start + lengthOf()) {
+      return 0;
+    }
+    return curve.velocity((time - transition.start) / 1000);
+  };
+
+  const begin = (
+    kind: KeyboardTransitionKind,
+    to: number,
+    start: number,
+    {animated = true, predicted = false} = {},
+  ): KeyboardTransition => {
+    // Never date a transition before the one it interrupts.
+    const at = Math.max(start, transition.start);
+    const from = presentation(at);
+    const v = animated ? velocity(at) : 0;
+    const slide = animated ? (to > from ? showSlide : hideSlide) : null;
+    transition = {
+      kind,
+      from,
+      to,
+      start: at,
+      velocity: v,
+      animated,
+      predicted,
+      curve: slide,
+    };
+    curve =
+      slide != null && Math.abs(to - from) + Math.abs(v) > 0
+        ? easedCurve(from, to, slide)
+        : null;
+    if (to > EPSILON) {
+      shownInset = to;
+    }
+    return transition;
+  };
+  const confirm = (): null => {
+    if (transition.predicted) {
+      transition = {...transition, predicted: false};
+    }
+    return null;
+  };
+
+  return {
+    get inset() {
+      return transition.to;
+    },
+    get transition() {
+      return transition;
+    },
+    presentation,
+    velocity,
+    report(inset, time) {
+      if (inset == null) {
+        return null;
+      }
+      const target = transition.to;
+      if (Math.abs(inset - target) < EPSILON) {
+        return confirm();
+      }
+      if (inset <= EPSILON) {
+        // A hide nothing predicted (Back): Chrome reports it just after
+        // Gboard starts down, so it rides from that moment.
+        return begin('hide', 0, time - androidKeyboard.hideReportLagMs);
+      }
+      if (target <= EPSILON) {
+        // Chrome reports the show just after Gboard starts up: ride from
+        // that moment, joining the slide where it is. A smaller first
+        // report is the accessory bar, the keyboard's own following: ride
+        // to the last keyboard's height and let its report confirm it.
+        const predicted = shownInset > inset + EPSILON;
+        return begin(
+          'show',
+          predicted ? shownInset : inset,
+          time - androidKeyboard.showReportLagMs,
+          {predicted},
+        );
+      }
+      // The keyboard changed while up (another keyboard, or the keyboard's
+      // report after the accessory bar's): Chrome lays the page out at once.
+      return begin('change', inset, time, {animated: false});
+    },
+    blurred(time) {
+      if (transition.to <= EPSILON) {
+        return null;
+      }
+      return begin('hide', 0, time + androidKeyboard.hideAfterBlurMs, {
+        predicted: true,
+      });
+    },
+    focused(time) {
+      if (transition.kind !== 'hide' || !transition.predicted) {
+        return null;
+      }
+      // Focus came back before the predicted hide finished: the keyboard
+      // turns back to the inset it had.
+      return begin('show', shownInset, Math.max(time, transition.start), {
+        predicted: true,
+      });
+    },
+    verify(inset, time) {
+      if (
+        !transition.predicted ||
+        inset == null ||
+        time < transition.start + lengthOf()
+      ) {
+        return null;
+      }
+      if (Math.abs(inset - transition.to) < EPSILON) {
+        return confirm();
+      }
+      return begin(inset > transition.to ? 'show' : 'hide', inset, time);
+    },
+  };
+}

package/src/keyboard/rideKeyboard.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rideKeyboard.ts
+ * @input An animator, target values and a keyboard transition, with its
+ *   start and the curve the guide publishes with it, and ride options
+ * @output rideKeyboard, which moves an element with the keyboard on the
+ *   keyboard's own motion
+ * @position Keyboard module, internal to core. A guide subscriber calls it
+ *   for each transition, as BottomSheet's hook does.
+ *
+ * SYNC: When modified, update /packages/core/src/keyboard/README.md
+ */
+
+import type {
+  Animator,
+  MotionCurve,
+  MotionHandle,
+  MotionProperty,
+  MotionValues,
+} from '../motion/animator';
+import {cubicBezier} from '../motion/bezier';
+import type {KeyboardTransition} from './keyboardModel';
+
+/** How a ride treats Reduce Motion. */
+export interface RideOptions {
+  /**
+   * Under Reduce Motion, lands the element at once and fades it in. Without
+   * it, the animator's own Reduce Motion plan applies.
+   */
+  readonly entrance?: boolean;
+}
+
+/**
+ * Moves `animator`'s element to `to` with the keyboard: on its curve from
+ * `transition.start`, or at once when the keyboard jumps.
+ *
+ * Android's keyboard moves on Gboard's slides up and down
+ * (motion/android/keyboard.ts). The transition publishes the slide
+ * (`curve`), and the ride plays it. Every ride starts at the transition's
+ * start, so content that joins a slide late lands where the keyboard is. A
+ * transition that is not animated lands at once, such as a keyboard changing
+ * while up. So does a slide that has ended by the call. These values are the
+ * keyboard's own motion, with no motion role. The system moves the keyboard
+ * on them whatever the page does, so any other curve would leave the element
+ * out of step.
+ *
+ * @example
+ * ```
+ * guide.subscribe(t => rideKeyboard(dock.animator, {y: -lift(t.to)}, t));
+ * ```
+ */
+export function rideKeyboard(
+  animator: Animator,
+  to: MotionValues,
+  transition: KeyboardTransition,
+  {entrance = false}: RideOptions = {},
+): MotionHandle | null {
+  // A frame after a busy task still draws an animation at that task's
+  // start. The ride sets a slide that has already ended, so no frame shows the
+  // element short of its target.
+  if (
+    !transition.animated ||
+    transition.curve == null ||
+    performance.now() >= transition.start + transition.curve.durationMs
+  ) {
+    animator.set(to);
+    return null;
+  }
+  // Under Reduce Motion nothing travels. The animator's default cross-fades
+  // the element to its new place on a touch screen, and elsewhere moves it at
+  // once. An entrance lands it at once and fades it in.
+  const options = entrance
+    ? {at: transition.start, crossfadeAs: 'entrance' as const}
+    : {at: transition.start};
+  const span = transition.curve.durationMs / 1000;
+  const ease = cubicBezier(transition.curve.points);
+  const curves: Partial<Record<MotionProperty, MotionCurve>> = {};
+  for (const [property, target] of Object.entries(to) as [
+    MotionProperty,
+    number,
+  ][]) {
+    const from = animator.get(property, transition.start);
+    const at = (t: number) =>
+      from + (target - from) * ease(Math.min(1, Math.max(0, t / span)));
+    curves[property] = {
+      duration: span,
+      at,
+      velocity: t => {
+        if (t >= span) {
+          return 0;
+        }
+        const a = Math.max(0, t - 0.001);
+        const b = Math.min(span, t + 0.001);
+        return (at(b) - at(a)) / (b - a);
+      },
+    };
+  }
+  return animator.play(curves, options);
+}