@astryxdesign/core 0.7.8-canary.ffd29c5 → 0.7.8

package/dist/keyboard/keyboardHeight.d.ts

@@ -0,0 +1,149 @@
+export declare const KEYBOARD_EPSILON = 1;
+/**
+ * Whether this window measures the keyboard: a top-level document with a
+ * visual viewport. Capabilities decide it, never the user agent or the
+ * pointer. The module measures a browser with its own keyboard geometry API,
+ * such as Chrome on Android with the VirtualKeyboard API, the same way.
+ * Its visual viewport shrinks for the keyboard while the layout viewport keeps
+ * its height, as everywhere else. A desktop browser's visual viewport never
+ * shrinks for a keyboard, so it reads 0. Where the app sets
+ * `interactive-widget=resizes-content`, Chrome shrinks the layout viewport
+ * with the keyboard. The height is then 0 too, and nothing rides, because the
+ * browser has made the room itself.
+ */
+export declare function isKeyboardMeasurable(win: Window): boolean;
+/**
+ * The on-screen keyboard's height over the layout viewport, CSS px. It is 0
+ * when none is shown, also while pinch-zoomed, and wherever
+ * `isKeyboardMeasurable` is false.
+ */
+export declare function measureKeyboardHeight(win: Window): number;
+/** A report from the keyboard module, in the order the window raised them. */
+export type KeyboardHeightEvent = {
+    /** The visual viewport or the window changed size or position. */
+    type: 'viewport';
+    /** The keyboard height after this report. */
+    height: number;
+    /** The report's event time (the document timeline). */
+    timeStamp: number;
+} | {
+    /** Focus moved into (`focusin`) or out of (`focusout`) `target`. */
+    type: 'focusin' | 'focusout';
+    height: number;
+    timeStamp: number;
+    target: EventTarget | null;
+    relatedTarget: EventTarget | null;
+};
+export declare function isNodeTarget(target: EventTarget | null): boolean;
+/**
+ * Calls `listener` with every report of `win`'s keyboard until the caller
+ * runs the returned function. It reports the viewport's changes, and focus
+ * moves too when the caller sets `focus`. All subscribers of a window share
+ * one set of listeners, and its focus listeners exist only while a subscriber
+ * asks for focus moves.
+ *
+ * @example
+ * ```
+ * const stop = subscribeKeyboardHeight(window, event => {
+ *   if (event.type === 'viewport') layout(event.height);
+ * });
+ * ```
+ */
+export declare function subscribeKeyboardHeight(win: Window, listener: (event: KeyboardHeightEvent) => void, { focus }?: {
+    focus?: boolean;
+}): () => void;
+/**
+ * `win`'s keyboard height. While the module listens, it is the height
+ * measured at the last report. Every reader of a keyboard change, such as
+ * each component's hook, shares that one layout read. Every change of the
+ * visual viewport or the window is a report, so a reader between two reports
+ * sees the current height. With nothing listening yet, the call measures the
+ * height now.
+ */
+export declare function getKeyboardHeight(win: Window): number;
+/**
+ * Whether focusing `element` brings up a keyboard for typing text. A control
+ * with `inputmode="none"` brings up none.
+ */
+export declare function isTextEntryControl(element: Element | null): element is HTMLElement;
+/** The text-entry control inside `container` that `target` is or labels. */
+export declare function findTextEntryControl(target: EventTarget | null, container: HTMLElement): HTMLElement | null;
+/** The caller's rules for refuseFocusReveal. */
+export interface RefuseFocusRevealOptions {
+    /** Whether to claim at all just now, checked on every blur. */
+    isActive?: () => boolean;
+    /** The control a focus move is heading to, when this caller claims it. */
+    claim: (destination: EventTarget | null) => HTMLElement | null;
+    /** Focus left `origin` for nothing (the keyboard's Done): park it, if at all. */
+    park?: (origin: EventTarget | null) => void;
+}
+/**
+ * Delivers the focus moves `claim` accepts with `preventScroll`, so the
+ * browser never reveals their destination itself. It stops when the caller
+ * runs the returned function.
+ *
+ * The browser dispatches `blur` in the capture phase ahead of its own focus
+ * step, and `blur` names the destination in `relatedTarget`. Focusing it there
+ * with preventScroll settles the change. The browser's step then finds the
+ * element already active, so it dispatches nothing further and reveals
+ * nothing.
+ *
+ * @example
+ * ```
+ * const stop = refuseFocusReveal(document, {
+ *   claim: target => findTextEntryControl(target, body),
+ *   park: () => sheet.focus({preventScroll: true}),
+ * });
+ * ```
+ */
+export declare function refuseFocusReveal(doc: Document, { isActive, claim, park }: RefuseFocusRevealOptions): () => void;
+/**
+ * Test-only: how many callers refuse the focus reveal in `doc`, through its
+ * one shared subscription. Not part of the runtime API.
+ *
+ * @internal
+ */
+export declare function __focusTakeoverCallersForTest(doc: Document): number;
+/** The caller's rules for watchRevealPan. */
+export interface WatchRevealPanOptions {
+    /** Whether the focused field is the caller's to keep in view. */
+    owns: (focused: HTMLElement) => boolean;
+    /** Called on every touch start, which ends the watch for the report. */
+    onTouch?: () => void;
+}
+/** A watch for the browser's own reveal pan (see watchRevealPan). */
+export interface RevealPanWatch {
+    /** A report changed the keyboard's height: remember where everything sat. */
+    report: () => void;
+    /** Whether the visual viewport has since moved down as a reveal pan. */
+    isRevealPan: (height: number) => boolean;
+    /**
+     * Pans the visual viewport back to where it sat at the report, without
+     * scrolling the document. It scrolls `anchor` into view, an element fixed at
+     * the layout viewport's top, or else a probe fixed where the viewport sat.
+     */
+    putBack: (anchor?: Element | null) => void;
+    /** Ends the watch; the shared touch subscription goes with the last watch. */
+    stop: () => void;
+}
+/**
+ * Some browsers reveal a focused field themselves, after the keyboard's
+ * report, by panning the visual viewport to it while the keyboard still
+ * covers it. Firefox for Android pans 54 to 143 ms after the report. Chrome
+ * on Android animates a pan of the keyboard's whole height from about 100 to
+ * 170 ms after it. The page gets no frame until that pan ends. Such a pan
+ * moves the visual viewport down within the
+ * layout viewport. Since the report there is no touch, document scroll or
+ * zoom, and a text field the caller owns has focus. The watch reads the
+ * behavior, never the user agent. The caller lands its field itself and
+ * puts the pan back. Every keyboard-aware surface can use it.
+ *
+ * @example
+ * ```
+ * const watch = watchRevealPan(window, {owns: field => region.contains(field)});
+ * // On a report that changes the height: watch.report();
+ * // On any later report: if (watch.isRevealPan(height)) watch.putBack();
+ * ```
+ */
+export declare function watchRevealPan(win: Window, { owns, onTouch }: WatchRevealPanOptions): RevealPanWatch;
+//# sourceMappingURL=keyboardHeight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyboardHeight.d.ts","sourceRoot":"","sources":["../../src/keyboard/keyboardHeight.ts"],"names":[],"mappings":"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"}

package/dist/keyboard/keyboardHeight.js

@@ -0,0 +1,432 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file keyboardHeight.ts
+ * @input The visual viewport, the window's input stream (focus, blur,
+ *   resize, scroll and touch), and the layout viewport's height
+ * @output The on-screen keyboard module: measureKeyboardHeight,
+ *   isKeyboardMeasurable, subscribeKeyboardHeight, getKeyboardHeight,
+ *   isTextEntryControl, findTextEntryControl, refuseFocusReveal and
+ *   watchRevealPan
+ * @position Core's one source for the on-screen keyboard. It is internal to
+ *   core and never exported from the package.
+ *
+ * SYNC: When modified, update /packages/core/src/keyboard/README.md
+ */
+import { subscribeInput } from "../utils/inputStream.js";
+import { layoutViewportHeight } from "../utils/layoutViewport.js";
+
+// A shortfall smaller than this is rounding, not a keyboard.
+export const KEYBOARD_EPSILON = 1;
+const NON_TEXT_INPUT_TYPES = new Set(['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit']);
+
+/**
+ * Whether this window measures the keyboard: a top-level document with a
+ * visual viewport. Capabilities decide it, never the user agent or the
+ * pointer. The module measures a browser with its own keyboard geometry API,
+ * such as Chrome on Android with the VirtualKeyboard API, the same way.
+ * Its visual viewport shrinks for the keyboard while the layout viewport keeps
+ * its height, as everywhere else. A desktop browser's visual viewport never
+ * shrinks for a keyboard, so it reads 0. Where the app sets
+ * `interactive-widget=resizes-content`, Chrome shrinks the layout viewport
+ * with the keyboard. The height is then 0 too, and nothing rides, because the
+ * browser has made the room itself.
+ */
+export function isKeyboardMeasurable(win) {
+  return win.visualViewport != null && win.self === win.top;
+}
+
+/**
+ * The on-screen keyboard's height over the layout viewport, CSS px. It is 0
+ * when none is shown, also while pinch-zoomed, and wherever
+ * `isKeyboardMeasurable` is false.
+ */
+export function measureKeyboardHeight(win) {
+  const viewport = win.visualViewport;
+  if (viewport == null || !isKeyboardMeasurable(win)) {
+    return 0;
+  }
+  const height = layoutViewportHeight(win) - viewport.height * (viewport.scale ?? 1);
+  return height > KEYBOARD_EPSILON ? Math.round(height * 100) / 100 : 0;
+}
+
+/** A report from the keyboard module, in the order the window raised them. */
+
+const stores = new WeakMap();
+
+// A window's capture phase also hears its document's events. A window's own
+// event has no node as its target.
+export function isNodeTarget(target) {
+  return target != null && typeof target.nodeType === 'number';
+}
+function storeOf(win) {
+  let store = stores.get(win);
+  if (store == null) {
+    store = {
+      height: 0,
+      listeners: new Set(),
+      focusListeners: new Set(),
+      detach: null,
+      detachFocus: null
+    };
+    stores.set(win, store);
+  }
+  return store;
+}
+function attach(win, store) {
+  const viewport = win.visualViewport;
+  store.height = measureKeyboardHeight(win);
+  const onViewport = event => {
+    store.height = measureKeyboardHeight(win);
+    const report = {
+      type: 'viewport',
+      height: store.height,
+      timeStamp: event.timeStamp
+    };
+    for (const listener of [...store.listeners]) {
+      listener(report);
+    }
+  };
+  viewport?.addEventListener('resize', onViewport);
+  viewport?.addEventListener('scroll', onViewport);
+  // Only the window's own resize reports.
+  const stopResize = subscribeInput(win, 'resize', event => {
+    if (!isNodeTarget(event.target)) {
+      onViewport(event);
+    }
+  });
+  return () => {
+    viewport?.removeEventListener('resize', onViewport);
+    viewport?.removeEventListener('scroll', onViewport);
+    stopResize();
+  };
+}
+
+// Focus moves are heard only while a subscriber asks for them. A viewport
+// reader, such as a Tall BottomSheet's hook under any pointer, adds no focus
+// listener.
+function attachFocus(win, store) {
+  const onFocus = event => {
+    const report = {
+      type: event.type === 'focusin' ? 'focusin' : 'focusout',
+      height: store.height,
+      timeStamp: event.timeStamp,
+      target: event.target,
+      relatedTarget: event.relatedTarget
+    };
+    for (const listener of [...store.focusListeners]) {
+      listener(report);
+    }
+  };
+  const stopFocusIn = subscribeInput(win, 'focusin', onFocus);
+  const stopFocusOut = subscribeInput(win, 'focusout', onFocus);
+  return () => {
+    stopFocusIn();
+    stopFocusOut();
+  };
+}
+
+/**
+ * Calls `listener` with every report of `win`'s keyboard until the caller
+ * runs the returned function. It reports the viewport's changes, and focus
+ * moves too when the caller sets `focus`. All subscribers of a window share
+ * one set of listeners, and its focus listeners exist only while a subscriber
+ * asks for focus moves.
+ *
+ * @example
+ * ```
+ * const stop = subscribeKeyboardHeight(window, event => {
+ *   if (event.type === 'viewport') layout(event.height);
+ * });
+ * ```
+ */
+export function subscribeKeyboardHeight(win, listener, {
+  focus = false
+} = {}) {
+  const store = storeOf(win);
+  store.listeners.add(listener);
+  if (store.detach == null) {
+    store.detach = attach(win, store);
+  }
+  if (focus) {
+    store.focusListeners.add(listener);
+    if (store.detachFocus == null) {
+      store.detachFocus = attachFocus(win, store);
+    }
+  }
+  return () => {
+    store.listeners.delete(listener);
+    if (focus) {
+      store.focusListeners.delete(listener);
+      if (store.focusListeners.size === 0 && store.detachFocus != null) {
+        store.detachFocus();
+        store.detachFocus = null;
+      }
+    }
+    if (store.listeners.size === 0 && store.detach != null) {
+      store.detach();
+      store.detach = null;
+    }
+  };
+}
+
+/**
+ * `win`'s keyboard height. While the module listens, it is the height
+ * measured at the last report. Every reader of a keyboard change, such as
+ * each component's hook, shares that one layout read. Every change of the
+ * visual viewport or the window is a report, so a reader between two reports
+ * sees the current height. With nothing listening yet, the call measures the
+ * height now.
+ */
+export function getKeyboardHeight(win) {
+  const store = stores.get(win);
+  return store?.detach != null ? store.height : measureKeyboardHeight(win);
+}
+
+/**
+ * Whether focusing `element` brings up a keyboard for typing text. A control
+ * with `inputmode="none"` brings up none.
+ */
+export function isTextEntryControl(element) {
+  if (element instanceof HTMLElement && element.getAttribute('inputmode') === 'none') {
+    return false;
+  }
+  if (element instanceof HTMLTextAreaElement) {
+    return !element.disabled && !element.readOnly;
+  }
+  if (element instanceof HTMLInputElement) {
+    return !element.disabled && !element.readOnly && !NON_TEXT_INPUT_TYPES.has((element.getAttribute('type') ?? 'text').toLowerCase());
+  }
+  return element instanceof HTMLElement && element.matches('[contenteditable]:not([contenteditable="false"])');
+}
+
+/** The text-entry control inside `container` that `target` is or labels. */
+export function findTextEntryControl(target, container) {
+  if (!(target instanceof Element)) {
+    return null;
+  }
+  const direct = target.closest('input, textarea, [contenteditable]:not([contenteditable="false"])');
+  if (container.contains(direct) && isTextEntryControl(direct)) {
+    return direct;
+  }
+  const label = target.closest('label');
+  const control = label instanceof HTMLLabelElement ? label.control : null;
+  return container.contains(control) && isTextEntryControl(control) ? control : null;
+}
+
+/** The caller's rules for refuseFocusReveal. */
+
+// One shared `blur` subscription per document serves every caller of
+// refuseFocusReveal in it, so listeners do not grow with the number of
+// instances. The first caller adds it, and the last removes it.
+const focusTakeovers = new WeakMap();
+
+/**
+ * Delivers the focus moves `claim` accepts with `preventScroll`, so the
+ * browser never reveals their destination itself. It stops when the caller
+ * runs the returned function.
+ *
+ * The browser dispatches `blur` in the capture phase ahead of its own focus
+ * step, and `blur` names the destination in `relatedTarget`. Focusing it there
+ * with preventScroll settles the change. The browser's step then finds the
+ * element already active, so it dispatches nothing further and reveals
+ * nothing.
+ *
+ * @example
+ * ```
+ * const stop = refuseFocusReveal(document, {
+ *   claim: target => findTextEntryControl(target, body),
+ *   park: () => sheet.focus({preventScroll: true}),
+ * });
+ * ```
+ */
+export function refuseFocusReveal(doc, {
+  isActive,
+  claim,
+  park
+}) {
+  const onBlur = event => {
+    if (isActive != null && !isActive()) {
+      return;
+    }
+    const destination = claim(event.relatedTarget);
+    if (destination != null) {
+      if (destination !== doc.activeElement) {
+        destination.focus({
+          preventScroll: true
+        });
+      }
+      return;
+    }
+    if (event.relatedTarget == null) {
+      park?.(event.target);
+    }
+  };
+  let shared = focusTakeovers.get(doc);
+  if (shared == null) {
+    const view = doc.defaultView;
+    if (view == null) {
+      return () => {};
+    }
+    const callers = new Set();
+    // Callers hear each blur in the order they came, as separate listeners
+    // would; one that stopped during this blur no longer hears it.
+    const listener = event => {
+      for (const caller of [...callers]) {
+        if (callers.has(caller)) {
+          caller(event);
+        }
+      }
+    };
+    // `blur` does not bubble: only the capture phase hears every one, and it
+    // runs before the browser's own focus step. The window's own blur moves
+    // no focus inside the document.
+    const stop = subscribeInput(view, 'blur', event => {
+      if (isNodeTarget(event.target)) {
+        listener(event);
+      }
+    });
+    shared = {
+      stop,
+      callers
+    };
+    focusTakeovers.set(doc, shared);
+  }
+  shared.callers.add(onBlur);
+  return () => {
+    const current = focusTakeovers.get(doc);
+    if (current == null || !current.callers.delete(onBlur)) {
+      return;
+    }
+    if (current.callers.size === 0) {
+      current.stop();
+      focusTakeovers.delete(doc);
+    }
+  };
+}
+
+/**
+ * Test-only: how many callers refuse the focus reveal in `doc`, through its
+ * one shared subscription. Not part of the runtime API.
+ *
+ * @internal
+ */
+export function __focusTakeoverCallersForTest(doc) {
+  return focusTakeovers.get(doc)?.callers.size ?? 0;
+}
+
+/** The caller's rules for watchRevealPan. */
+
+/** A watch for the browser's own reveal pan (see watchRevealPan). */
+
+// One shared touch subscription per document serves every reveal-pan watch
+// in it, so no instance adds a listener. The first watch adds it, and the
+// last removes it.
+const touchStartWatches = new WeakMap();
+function watchTouchStarts(doc, onTouchStart) {
+  let shared = touchStartWatches.get(doc);
+  if (shared == null) {
+    const view = doc.defaultView;
+    if (view == null) {
+      return () => {};
+    }
+    const watches = new Set();
+    const stop = subscribeInput(view, 'touchstart', () => {
+      for (const watch of [...watches]) {
+        watch();
+      }
+    });
+    shared = {
+      stop,
+      watches
+    };
+    touchStartWatches.set(doc, shared);
+  }
+  shared.watches.add(onTouchStart);
+  return () => {
+    const current = touchStartWatches.get(doc);
+    if (current == null || !current.watches.delete(onTouchStart)) {
+      return;
+    }
+    if (current.watches.size === 0) {
+      current.stop();
+      touchStartWatches.delete(doc);
+    }
+  };
+}
+
+/**
+ * Some browsers reveal a focused field themselves, after the keyboard's
+ * report, by panning the visual viewport to it while the keyboard still
+ * covers it. Firefox for Android pans 54 to 143 ms after the report. Chrome
+ * on Android animates a pan of the keyboard's whole height from about 100 to
+ * 170 ms after it. The page gets no frame until that pan ends. Such a pan
+ * moves the visual viewport down within the
+ * layout viewport. Since the report there is no touch, document scroll or
+ * zoom, and a text field the caller owns has focus. The watch reads the
+ * behavior, never the user agent. The caller lands its field itself and
+ * puts the pan back. Every keyboard-aware surface can use it.
+ *
+ * @example
+ * ```
+ * const watch = watchRevealPan(window, {owns: field => region.contains(field)});
+ * // On a report that changes the height: watch.report();
+ * // On any later report: if (watch.isRevealPan(height)) watch.putBack();
+ * ```
+ */
+export function watchRevealPan(win, {
+  owns,
+  onTouch
+}) {
+  const doc = win.document;
+  let atReport = null;
+  let touchedSinceReport = false;
+  const stopTouchStarts = watchTouchStarts(doc, () => {
+    touchedSinceReport = true;
+    onTouch?.();
+  });
+  return {
+    report: () => {
+      const viewport = win.visualViewport;
+      atReport = viewport == null ? null : {
+        x: win.scrollX,
+        y: win.scrollY,
+        top: viewport.offsetTop,
+        scale: viewport.scale
+      };
+      touchedSinceReport = false;
+    },
+    isRevealPan: height => {
+      const viewport = win.visualViewport;
+      const focused = doc.activeElement;
+      return viewport != null && atReport != null && !touchedSinceReport && height > 0 && viewport.offsetTop > atReport.top && viewport.scale === atReport.scale && win.scrollX === atReport.x && win.scrollY === atReport.y && focused instanceof HTMLElement && isTextEntryControl(focused) && owns(focused);
+    },
+    putBack: anchor => {
+      const options = {
+        block: 'start',
+        inline: 'nearest',
+        behavior: 'instant'
+      };
+      if (anchor != null) {
+        anchor.scrollIntoView(options);
+        return;
+      }
+      // A fixed element sits in the layout viewport, which the pan does not
+      // move: scrolling its top into view pans the visual viewport back.
+      const probe = doc.createElement('div');
+      probe.style.position = 'fixed';
+      probe.style.left = '0';
+      probe.style.top = `${atReport?.top ?? 0}px`;
+      probe.style.width = '1px';
+      probe.style.height = '1px';
+      probe.style.visibility = 'hidden';
+      probe.style.pointerEvents = 'none';
+      (doc.body ?? doc.documentElement).append(probe);
+      probe.scrollIntoView(options);
+      probe.remove();
+    },
+    stop: stopTouchStarts
+  };
+}

package/dist/keyboard/keyboardLayoutGuide.d.ts

@@ -0,0 +1,59 @@
+import { type KeyboardProfile, type KeyboardTransition } 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 declare function keyboardProfileOf(win: Window): KeyboardProfile | 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;
+}
+/**
+ * Whether focusing `target` brings up a software keyboard (or another input
+ * view in its place, as a select's picker does).
+ */
+export declare function bringsUpKeyboard(target: EventTarget | null): boolean;
+/**
+ * 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 declare function getKeyboardLayoutGuide(win: Window): KeyboardLayoutGuide;
+//# sourceMappingURL=keyboardLayoutGuide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyboardLayoutGuide.d.ts","sourceRoot":"","sources":["../../src/keyboard/keyboardLayoutGuide.ts"],"names":[],"mappings":"AAqBA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAErE;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,2DAA2D;IAC3D,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1E,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAkBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAMpE;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAOvE"}