@astryxdesign/core 0.7.8-canary.ffd29c5 → 0.7.8

package/dist/keyboard/keyboardLayoutGuide.js

@@ -0,0 +1,207 @@
+// 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 } from "./keyboardHeight.js";
+import { createKeyboardModel } from "./keyboardModel.js";
+
+/**
+ * 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) {
+  return 'virtualKeyboard' in win.navigator ? 'chromium' : null;
+}
+
+/** A window's keyboard layout guide. */
+
+// 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) {
+  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) {
+  const element = target;
+  if (element == null || element.nodeType !== 1) {
+    return false;
+  }
+  return element.tagName === 'SELECT' || element.tagName === 'INPUT' && PICKER_INPUT_TYPES.has(element.type);
+}
+const guides = new WeakMap();
+
+/**
+ * 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) {
+  let guide = guides.get(win);
+  if (guide == null) {
+    guide = createGuide(win);
+    guides.set(win, guide);
+  }
+  return guide;
+}
+function createGuide(win) {
+  const listeners = new Set();
+  let profile = keyboardProfileOf(win);
+  let model = createKeyboardModel(getKeyboardHeight(win));
+  let verifyTimer = null;
+  let detach = null;
+  const publish = transition => {
+    if (transition == null) {
+      return;
+    }
+    if (transition.predicted) {
+      scheduleVerify(transition);
+    }
+    for (const listener of [...listeners]) {
+      listener(transition);
+    }
+  };
+  const scheduleVerify = transition => {
+    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 => bringsUpKeyboard(target) && !(profile === 'chromium' && opensPickerOverPage(target));
+    // When a field that brings up a keyboard last gained focus.
+    let keyboardFocusAt = -Infinity;
+    let handoffTimer = null;
+    const report = (height, time) => {
+      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 => {
+      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/dist/keyboard/keyboardModel.d.ts

@@ -0,0 +1,93 @@
+/** 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;
+}
+/**
+ * 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 declare function createKeyboardModel(initialInset?: number): KeyboardModel;
+//# sourceMappingURL=keyboardModel.d.ts.map

package/dist/keyboard/keyboardModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboardModel.d.ts","sourceRoot":"","sources":["../../src/keyboard/keyboardModel.ts"],"names":[],"mappings":"AAkBA,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5D;AAED,wCAAwC;AACxC,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEhE,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAED,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,6CAA6C;IAC7C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACtE;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACjD,wDAAwD;IACxD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACjD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;CACvE;AAUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,SAAI,GAAG,aAAa,CAkLnE"}

package/dist/keyboard/keyboardModel.js

@@ -0,0 +1,220 @@
+// 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.js";
+import { cubicBezier } from "../motion/bezier.js";
+
+/** Which browser's keyboard reports the guide reads. */
+
+/** An eased slide: the curve a transition plays (Gboard going up or down). */
+
+/** How the keyboard's cover changes. */
+
+/** One change of the keyboard's cover, as the guide reports it. */
+
+/** The guide's clock-free core: inputs carry their own times. */
+
+const EPSILON = 0.5;
+
+/** The inset and its velocity, seconds after a transition's start. */
+
+/**
+ * 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) {
+  let transition = {
+    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 = null;
+  // An eased slide's value and velocity.
+  const easedCurve = (from, to, slide) => {
+    const span = slide.durationMs / 1000;
+    const ease = cubicBezier(slide.points);
+    const value = t => from + (to - from) * ease(Math.min(1, Math.max(0, t / span)));
+    return {
+      value,
+      velocity: t => {
+        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 = {
+    durationMs: androidKeyboard.showMs,
+    points: androidKeyboard.showCurve
+  };
+  const hideSlide = {
+    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 => {
+    // 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 => {
+    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, to, start, {
+    animated = true,
+    predicted = false
+  } = {}) => {
+    // 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 = () => {
+    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/dist/keyboard/rideKeyboard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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, MotionHandle, MotionValues } from '../motion/animator.js';
+import type { KeyboardTransition } from './keyboardModel.js';
+/** 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 declare function rideKeyboard(animator: Animator, to: MotionValues, transition: KeyboardTransition, { entrance }?: RideOptions): MotionHandle | null;
+//# sourceMappingURL=rideKeyboard.d.ts.map

package/dist/keyboard/rideKeyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rideKeyboard.d.ts","sourceRoot":"","sources":["../../src/keyboard/rideKeyboard.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,YAAY,EAEZ,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAExD,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,kBAAkB,EAC9B,EAAC,QAAgB,EAAC,GAAE,WAAgB,GACnC,YAAY,GAAG,IAAI,CA0CrB"}

package/dist/keyboard/rideKeyboard.js

@@ -0,0 +1,77 @@
+// 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 { cubicBezier } from "../motion/bezier.js";
+
+/** How a ride treats Reduce Motion. */
+
+/**
+ * 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, to, transition, {
+  entrance = false
+} = {}) {
+  // 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'
+  } : {
+    at: transition.start
+  };
+  const span = transition.curve.durationMs / 1000;
+  const ease = cubicBezier(transition.curve.points);
+  const curves = {};
+  for (const [property, target] of Object.entries(to)) {
+    const from = animator.get(property, transition.start);
+    const at = t => 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);
+}