@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/keyboard/avoidance.d.ts

@@ -0,0 +1,24 @@
+type Editor = HTMLInputElement | HTMLTextAreaElement;
+/** Where the keyboard leaves room, in visual-viewport coordinates. */
+export type KeyboardClearance = Readonly<{
+    /** The visual viewport's pan: layout coordinates minus this are on-screen coordinates. */
+    offsetTop: number;
+    /** The bottom of the room above the keyboard (the tallest one measured at this size). */
+    bottom: number;
+}>;
+/**
+ * Keyboard avoidance for the focused editor, as SwiftUI's keyboard safe area does it: every
+ * scroll surface around the editor gets room below its content for the keyboard and scrolls the
+ * editor (a tall editor: its caret line) above the keyboard, innermost first. An editor on a page
+ * whose surfaces cannot bring it up (a screen without a scroll surface, or a nested scroller pinned
+ * under the keyboard) lifts the screen's content layer by scrolling that layer, which clips its
+ * content and is never touch-scrollable; the navigation bar stays where it is. The document and
+ * the visual viewport never move. Everything is restored when editing ends, and whenever no
+ * keyboard shows while the field stays focused (rotation, the app in the background, a hardware
+ * keyboard attached, the keyboard hidden by its own key); it is applied again when one returns.
+ */
+export declare function createKeyboardAvoidance(): {
+    reveal: (editor: Editor, presentation: Element | null, clearance: KeyboardClearance, withCaret: boolean, keyboardShown?: boolean) => void;
+    releaseAll: () => void;
+};
+export {};

package/dist/keyboard/avoidance.js

@@ -0,0 +1,283 @@
+import { caretLineAt } from './caretMirror.js';
+import { revealDelta } from './geometry.js';
+const SURFACE = '[data-satin-scroll-axis="vertical"]';
+const SCREEN_LAYER = '[data-satin-navigation-motion-layer="true"]';
+const NAVIGATION_CHROME = '[data-satin-navigation-chrome="true"]';
+/** Space kept between a revealed field (or caret line) and the keyboard or the bar above it. */
+const REVEAL_GAP = 12;
+/**
+ * A caret-line reveal can stop at any offset that keeps the caret line in the room; prefer one
+ * that keeps the whole editor inside the surface's box. Measured on the iPhone Simulator (Tall
+ * lab, a TextEditor capped to the room): ~20 ms after the keyboard arrives WebKit centres a focused
+ * editor that a scroll ancestor cuts off, in that ancestor's full box with the keyboard ignored,
+ * which put the caret line back under the keyboard. An editor wholly inside is left alone.
+ */
+function keepEditorInBox(delta, editor, box, offsetTop, room) {
+    // Keeping the whole card in its box is never a reason to move an already visible caret.
+    if (delta === 0)
+        return 0;
+    // Every offset in [lowest, highest] keeps the caret line in the room.
+    const lowest = room.targetBottom - (room.bottom - REVEAL_GAP);
+    const highest = room.targetTop - (room.top + REVEAL_GAP);
+    // Every offset in [inside, outside] keeps the editor inside the box.
+    const inside = editor.bottom - (box.bottom - offsetTop);
+    const outside = editor.top - (box.top - offsetTop);
+    const low = Math.max(lowest, inside);
+    const high = Math.min(highest, outside);
+    if (low > high)
+        return delta;
+    return Math.min(high, Math.max(low, delta));
+}
+/**
+ * Keyboard avoidance for the focused editor, as SwiftUI's keyboard safe area does it: every
+ * scroll surface around the editor gets room below its content for the keyboard and scrolls the
+ * editor (a tall editor: its caret line) above the keyboard, innermost first. An editor on a page
+ * whose surfaces cannot bring it up (a screen without a scroll surface, or a nested scroller pinned
+ * under the keyboard) lifts the screen's content layer by scrolling that layer, which clips its
+ * content and is never touch-scrollable; the navigation bar stays where it is. The document and
+ * the visual viewport never move. Everything is restored when editing ends, and whenever no
+ * keyboard shows while the field stays focused (rotation, the app in the background, a hardware
+ * keyboard attached, the keyboard hidden by its own key); it is applied again when one returns.
+ */
+export function createKeyboardAvoidance() {
+    const avoiding = new Map();
+    // An app render can rewrite a surface's inline style (ScrollSurface spreads `style`): put the
+    // keyboard room back on top of the app's new padding.
+    const styleObserver = typeof MutationObserver === 'undefined'
+        ? undefined
+        : new MutationObserver(records => {
+            for (const record of records) {
+                const surface = record.target;
+                const state = avoiding.get(surface);
+                if (!state || state.lift || surface.style.paddingBottom === state.written)
+                    continue;
+                const room = parseFloat(state.written) - state.originalPadding;
+                state.restorePadding = surface.style.paddingBottom;
+                state.originalPadding = parseFloat(getComputedStyle(surface).paddingBottom) || 0;
+                state.written = `${state.originalPadding + room}px`;
+                surface.style.paddingBottom = state.written;
+            }
+        });
+    const release = (surface) => {
+        const state = avoiding.get(surface);
+        if (!state)
+            return;
+        avoiding.delete(surface);
+        if (avoiding.size === 0)
+            styleObserver?.disconnect();
+        // A node React has already removed (a new screen key) has nothing to put back.
+        if (!surface.isConnected)
+            return;
+        if (state.lift) {
+            state.lift.spacer?.remove();
+            surface.scrollTop = state.lift.scrollTop;
+        }
+        else
+            surface.style.paddingBottom = state.restorePadding;
+        surface.removeAttribute('data-satin-keyboard-avoiding');
+    };
+    const releaseAll = () => {
+        for (const surface of [...avoiding.keys()])
+            release(surface);
+    };
+    /** Room below a surface's content for the part of it the keyboard covers. */
+    const makeRoom = (surface, clearance) => {
+        let state = avoiding.get(surface);
+        if (!state) {
+            state = {
+                restorePadding: surface.style.paddingBottom,
+                originalPadding: parseFloat(getComputedStyle(surface).paddingBottom) || 0,
+                written: '',
+                lift: null,
+            };
+            avoiding.set(surface, state);
+            styleObserver?.observe(surface, { attributes: true, attributeFilter: ['style'] });
+        }
+        const overlap = Math.max(0, surface.getBoundingClientRect().bottom - clearance.offsetTop - clearance.bottom);
+        state.written = `${state.originalPadding + overlap}px`;
+        surface.style.paddingBottom = state.written;
+        surface.dataset.satinKeyboardAvoiding = 'true';
+    };
+    /** Room to lift a screen layer: a spacer under its box (its own padding may not count as overflow). */
+    const makeLiftRoom = (layer, clearance, requiredLift) => {
+        let state = avoiding.get(layer);
+        if (!state) {
+            state = {
+                restorePadding: '',
+                originalPadding: 0,
+                written: '',
+                lift: { scrollTop: layer.scrollTop, spacer: null },
+            };
+            avoiding.set(layer, state);
+        }
+        const lift = state.lift;
+        // React may have replaced the layer's children (a remount): the spacer went with them.
+        if (lift.spacer && lift.spacer.parentElement !== layer)
+            lift.spacer = null;
+        if (!lift.spacer) {
+            // Its own element name, every declaration important: page rules cannot change its box.
+            const spacer = layer.ownerDocument.createElement('satin-keyboard-spacer');
+            spacer.setAttribute('aria-hidden', 'true');
+            const box = {
+                display: 'block',
+                position: 'absolute',
+                top: '100%',
+                left: '0',
+                width: '1px',
+                margin: '0',
+                padding: '0',
+                visibility: 'hidden',
+                'pointer-events': 'none',
+            };
+            for (const [property, value] of Object.entries(box))
+                spacer.style.setProperty(property, value, 'important');
+            layer.append(spacer);
+            lift.spacer = spacer;
+        }
+        const overlap = Math.max(0, layer.getBoundingClientRect().bottom - clearance.offsetTop - clearance.bottom);
+        // Rotation can leave app content taller than the new layer. Keyboard overlap alone
+        // cannot provide enough scroll range to reveal a field beyond that layer's bottom.
+        const room = Math.max(overlap, requiredLift);
+        lift.spacer.style.setProperty('height', `${room}px`, 'important');
+        layer.dataset.satinKeyboardAvoiding = 'true';
+    };
+    /** The bottom of the navigation bar drawn over this editor's screen (none in a presentation). */
+    const barBottom = (editor, offsetTop) => {
+        const field = editor.getBoundingClientRect();
+        let bottom = 0;
+        const bars = document.querySelectorAll?.(NAVIGATION_CHROME) ?? [];
+        for (const bar of bars) {
+            const rect = bar.getBoundingClientRect();
+            if (rect.height <= 0 || rect.right <= field.left || rect.left >= field.right)
+                continue;
+            bottom = Math.max(bottom, rect.bottom - offsetTop);
+        }
+        return bottom;
+    };
+    /**
+     * Bring the editor (a tall one: its caret line) into the room above the keyboard.
+     * `withCaret` measures the caret line; it is set after a focus or a keyboard change, not while
+     * typing (WebKit keeps the caret in view as the text changes). With no keyboard on screen
+     * (`keyboardShown` false) owned geometry is released and no surface is scrolled.
+     */
+    function reveal(editor, presentation, clearance, withCaret, keyboardShown = true) {
+        for (const tracked of [...avoiding.keys()])
+            if (!tracked.isConnected)
+                release(tracked);
+        if (!keyboardShown) {
+            releaseAll();
+            return;
+        }
+        // A safe-area accessory already participates in the keyboard's layout region.
+        // Only its own nested scrollers may reveal a caret. Lifting the presenting
+        // screen would apply avoidance twice and move the conversation with it.
+        const accessory = editor.closest('[data-satin-inset-accessory="true"]');
+        const surfaces = [];
+        let surface = editor.closest(SURFACE);
+        while (surface) {
+            // A top-layer field is not part of the presenting page's scroll geometry.
+            if (presentation && !presentation.contains(surface))
+                break;
+            if (accessory && !accessory.contains(surface))
+                break;
+            surfaces.push(surface);
+            surface = surface.parentElement?.closest(SURFACE) ?? null;
+        }
+        const screenLayer = presentation || accessory || !keyboardShown ? null : editor.closest(SCREEN_LAYER);
+        // A layer that is itself a declared surface is revealed as a surface.
+        const layer = screenLayer && !surfaces.includes(screenLayer) ? screenLayer : null;
+        for (const tracked of [...avoiding.keys()]) {
+            if (!surfaces.includes(tracked) && tracked !== layer)
+                release(tracked);
+        }
+        // A keyboard subscriber can move the field after our first reveal. Recompute a screen
+        // lift from its resting position, otherwise a now-visible caret preserves the old lift
+        // and applies avoidance twice. This is synchronous with the replacement reveal, so an
+        // unchanged layout keeps the same painted position. Typing keeps WebKit's caret ownership.
+        if (layer && (withCaret || !(editor instanceof HTMLTextAreaElement)))
+            release(layer);
+        if (keyboardShown)
+            for (const declared of surfaces)
+                makeRoom(declared, clearance);
+        // Once editing is established, WebKit keeps the caret visible. A textarea's card
+        // is not the reveal target: aligning its bottom on input moves readable content.
+        // Focus and keyboard changes explicitly request a fresh caret-line reveal.
+        if (editor instanceof HTMLTextAreaElement && !withCaret)
+            return;
+        const offsetTop = clearance.offsetTop;
+        const clearTop = presentation ? 0 : barBottom(editor, offsetTop);
+        const room = clearance.bottom - clearTop - 2 * REVEAL_GAP;
+        const fieldRect = () => {
+            const rect = editor.getBoundingClientRect();
+            return { top: rect.top - offsetTop, bottom: rect.bottom - offsetTop };
+        };
+        const fits = fieldRect().bottom - fieldRect().top <= room;
+        const scrollsInside = editor.scrollHeight > editor.clientHeight + 1;
+        // A field that does not fit, or text scrolled inside its editor: the caret line is the target.
+        let caret = null;
+        if (withCaret && (editor instanceof HTMLTextAreaElement || !fits || scrollsInside)) {
+            const end = editor.selectionDirection === 'backward' ? editor.selectionStart : editor.selectionEnd;
+            const line = caretLineAt(editor, end ?? 0);
+            caret = line && { top: line.top - offsetTop, bottom: line.bottom - offsetTop };
+        }
+        // While typing in a field taller than the room, WebKit keeps its caret in view.
+        if (!fits && !caret)
+            return;
+        const scrollBy = (scroller, delta) => {
+            const before = scroller.scrollTop;
+            scroller.scrollTop = before + delta;
+            const moved = scroller.scrollTop - before;
+            if (caret)
+                caret = { top: caret.top - moved, bottom: caret.bottom - moved };
+            return moved;
+        };
+        // The caret line inside the editor's own scrolled text first.
+        if (caret && scrollsInside) {
+            const box = editor.getBoundingClientRect();
+            const style = getComputedStyle(editor);
+            const top = box.top - offsetTop + (parseFloat(style.paddingTop) || 0);
+            const bottom = box.bottom - offsetTop - (parseFloat(style.paddingBottom) || 0);
+            const delta = revealDelta(caret.top, caret.bottom, top, bottom, Infinity, 0);
+            if (delta)
+                scrollBy(editor, delta);
+        }
+        const target = () => caret ?? fieldRect();
+        // Innermost first; a second pass reveals within an inner surface that an outer one brought up.
+        for (let pass = 0; pass < 2; pass++) {
+            for (const scroller of [...surfaces, ...(layer ? [layer] : [])]) {
+                const box = scroller.getBoundingClientRect();
+                const top = Math.max(box.top - offsetTop, clearTop);
+                const bottom = Math.min(box.bottom - offsetTop, clearance.bottom);
+                const { top: targetTop, bottom: targetBottom } = target();
+                // This surface's visible part cannot hold the target (it is under the keyboard): an outer
+                // surface or the screen layer moves it first.
+                if (scroller !== layer && bottom - top - 2 * REVEAL_GAP < targetBottom - targetTop)
+                    continue;
+                // A visible caret already satisfies the reveal contract. Do not align the rest of its
+                // card or add a preferred gap by scrolling content that the user can already read.
+                if (caret && targetTop >= top && targetBottom <= bottom)
+                    continue;
+                let delta = revealDelta(targetTop, targetBottom, top, bottom, clearance.bottom, REVEAL_GAP);
+                if (!fits && scroller !== layer)
+                    delta = keepEditorInBox(delta, fieldRect(), box, offsetTop, {
+                        targetTop,
+                        targetBottom,
+                        top,
+                        bottom,
+                    });
+                if (!delta)
+                    continue;
+                // The screen layer only lifts content that is under the keyboard; it never pushes it down
+                // below where the app laid it out.
+                if (scroller === layer) {
+                    if (delta > 0)
+                        makeLiftRoom(layer, clearance, layer.scrollTop + delta);
+                    else if (!avoiding.has(layer))
+                        continue;
+                }
+                scrollBy(scroller, delta);
+            }
+        }
+    }
+    return { reveal, releaseAll };
+}

package/dist/keyboard/caretMirror.d.ts

@@ -0,0 +1,13 @@
+type Editor = HTMLInputElement | HTMLTextAreaElement;
+export type CaretLine = Readonly<{
+    top: number;
+    bottom: number;
+}>;
+/** The text offset under a point of the editor (WebKit hides the input's internal text node). */
+export declare function caretOffsetAt(editor: Editor, x: number, y: number): number | null;
+/**
+ * The line box of the caret at `offset` in a multi-line editor, in viewport coordinates, as the
+ * editor draws it now (its own scroll included). Null for single-line fields (the field is the line).
+ */
+export declare function caretLineAt(editor: Editor, offset: number): CaretLine | null;
+export {};

package/dist/keyboard/caretMirror.js

@@ -0,0 +1,122 @@
+import { EDITOR_TEXT_LAYOUT_PROPERTIES } from '../text-input/editorTextLayout.js';
+/** A password is drawn as discs: the mirror draws the same discs and never holds the text. */
+function isSecure(editor, computed) {
+    const security = computed.getPropertyValue('-webkit-text-security');
+    return editor.type === 'password' || (security !== '' && security !== 'none');
+}
+function setImportant(element, property, value) {
+    element.style.setProperty(property, value, 'important');
+}
+/**
+ * A hidden copy of the editor's text box at the editor's place, isolated from the page's styles
+ * (`all: initial`, its own element name, every declaration important), so that inherited body
+ * styles and `div` rules cannot move its text. Removed by the caller.
+ */
+function createMirror(editor, text, marker) {
+    const document = editor.ownerDocument;
+    const rect = editor.getBoundingClientRect();
+    const computed = getComputedStyle(editor);
+    const secure = isSecure(editor, computed);
+    const mirror = document.createElement('satin-caret-mirror');
+    setImportant(mirror, 'all', 'initial');
+    for (const property of EDITOR_TEXT_LAYOUT_PROPERTIES)
+        setImportant(mirror, property, computed.getPropertyValue(property));
+    const layout = {
+        display: 'block',
+        position: 'fixed',
+        left: `${rect.left}px`,
+        top: `${rect.top}px`,
+        width: `${rect.width}px`,
+        height: `${rect.height}px`,
+        margin: '0',
+        'box-sizing': 'border-box',
+        'border-style': 'solid',
+        'border-color': 'transparent',
+        opacity: '0',
+        visibility: 'visible',
+        'pointer-events': 'auto',
+        'z-index': '2147483647',
+        overflow: 'hidden',
+        'white-space': editor instanceof HTMLTextAreaElement ? 'pre-wrap' : 'pre',
+        '-webkit-text-security': secure ? 'disc' : 'none',
+    };
+    for (const [property, value] of Object.entries(layout))
+        setImportant(mirror, property, value);
+    // A secure field's characters are all drawn as the same disc: the mirror holds placeholders.
+    const shown = secure ? '*'.repeat(text.length) : text;
+    const content = document.createTextNode(marker ? shown.slice(0, marker.before) : shown);
+    mirror.append(content);
+    const caret = marker ? createMarker(document) : null;
+    if (caret)
+        mirror.append(caret, shown.slice(marker.before));
+    (editor.closest('dialog') ?? document.body).append(mirror);
+    // A dialog has `contain: layout`, which makes it the containing block of a fixed box: measure
+    // where the mirror landed and move it onto the editor.
+    const placed = mirror.getBoundingClientRect();
+    if (placed.left !== rect.left || placed.top !== rect.top) {
+        setImportant(mirror, 'left', `${2 * rect.left - placed.left}px`);
+        setImportant(mirror, 'top', `${2 * rect.top - placed.top}px`);
+    }
+    mirror.scrollLeft = editor.scrollLeft;
+    mirror.scrollTop = editor.scrollTop;
+    return { mirror, content, caret };
+}
+/** An inline box at the caret, inheriting the mirror's text style and nothing from the page. */
+function createMarker(document) {
+    const marker = document.createElement('satin-caret-marker');
+    setImportant(marker, 'all', 'inherit');
+    const reset = {
+        display: 'inline',
+        position: 'static',
+        width: 'auto',
+        height: 'auto',
+        margin: '0',
+        padding: '0',
+        'border-width': '0',
+        'text-indent': '0',
+        overflow: 'visible',
+    };
+    for (const [property, value] of Object.entries(reset))
+        setImportant(marker, property, value);
+    marker.textContent = '\u200b';
+    return marker;
+}
+/** The text offset under a point of the editor (WebKit hides the input's internal text node). */
+export function caretOffsetAt(editor, x, y) {
+    const document = editor.ownerDocument;
+    const { mirror, content } = createMirror(editor, editor.value || '​');
+    try {
+        const caret = document.caretPositionFromPoint?.(x, y);
+        if (caret?.offsetNode === content)
+            return Math.min(caret.offset, editor.value.length);
+        const range = document.caretRangeFromPoint?.(x, y);
+        if (range?.startContainer === content)
+            return Math.min(range.startOffset, editor.value.length);
+        return null;
+    }
+    finally {
+        mirror.remove();
+    }
+}
+/**
+ * The line box of the caret at `offset` in a multi-line editor, in viewport coordinates, as the
+ * editor draws it now (its own scroll included). Null for single-line fields (the field is the line).
+ */
+export function caretLineAt(editor, offset) {
+    if (!(editor instanceof HTMLTextAreaElement))
+        return null;
+    const before = Math.max(0, Math.min(offset, editor.value.length));
+    const { mirror, caret } = createMirror(editor, editor.value, { before });
+    try {
+        const line = caret.getBoundingClientRect();
+        const box = mirror.getBoundingClientRect();
+        const editorBox = editor.getBoundingClientRect();
+        const lineHeight = parseFloat(getComputedStyle(editor).lineHeight) || line.height || 22;
+        // The mirror scrolled like the editor; place the line relative to the editor itself.
+        const top = editorBox.top + (line.top - box.top);
+        return { top, bottom: top + Math.max(line.height, lineHeight) };
+    }
+    finally {
+        mirror.remove();
+    }
+}

package/dist/keyboard/expectedKeyboard.d.ts

@@ -0,0 +1,10 @@
+/** A viewport occlusion this tall is a software keyboard (the iPad hardware-keyboard bar is 55-70 pt). */
+export declare const SOFTWARE_KEYBOARD_MIN_HEIGHT = 120;
+/** Apply the same plausibility limit to live reports and remembered geometry. */
+export declare function isPlausibleKeyboardHeight(width: number, layoutHeight: number, keyboardHeight: number): boolean;
+export declare function defaultSoftwareKeyboardHeight(width: number, height: number): number;
+/** The tallest software keyboard WebKit has reported at this window size, in an earlier launch too. */
+export declare function readMeasuredKeyboardHeight(width: number, height: number): number | null;
+export declare function rememberKeyboardHeight(width: number, height: number, keyboardHeight: number): void;
+/** The keyboard height to plan for: the tallest measured one, else the device default. */
+export declare function expectedKeyboardHeight(width: number, height: number): number;

package/dist/keyboard/expectedKeyboard.js

@@ -0,0 +1,60 @@
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+/** A viewport occlusion this tall is a software keyboard (the iPad hardware-keyboard bar is 55-70 pt). */
+export const SOFTWARE_KEYBOARD_MIN_HEIGHT = 120;
+const STORAGE_PREFIX = 'satin-keyboard-height:';
+/** Baseline upper share, with the existing short phone landscape allowance below. */
+const MAX_KEYBOARD_SHARE = 0.7;
+/** Apply the same plausibility limit to live reports and remembered geometry. */
+export function isPlausibleKeyboardHeight(width, layoutHeight, keyboardHeight) {
+    // The phone landscape default can exceed 70% in a short window. Preserve that
+    // existing allowance instead of rejecting the geometry we already plan for.
+    const maximum = Math.min(layoutHeight, Math.max(layoutHeight * MAX_KEYBOARD_SHARE, defaultSoftwareKeyboardHeight(width, layoutHeight)));
+    return Number.isFinite(keyboardHeight) && keyboardHeight >= 0 && keyboardHeight <= maximum;
+}
+/*
+ * The software keyboard's height before WebKit has ever reported one at this window size.
+ *
+ * It only has to be at least as tall as the real keyboard: presentations use it to keep a text
+ * field clear of the keyboard that has not arrived yet, and the first report replaces it.
+ * References: iPad Pro 13-inch landscape (1366 x 1024) reports 498 pt with the predictive bar
+ * (installed, iOS 27.0); iPhone 17 Pro Max portrait raises a stock alert for a 347 pt keyboard
+ * (measured-reference native recording), and a web text field adds the 44 pt form accessory bar.
+ * The other classes are estimates until a device reports them.
+ */
+export function defaultSoftwareKeyboardHeight(width, height) {
+    const landscape = width > height;
+    if (readDeviceIdiom() === 'pad')
+        return Math.round(height * (landscape ? 0.4865 : 0.31));
+    if (landscape)
+        return 250;
+    return height >= 800 ? 391 : 304;
+}
+const storageKey = (width, height) => `${STORAGE_PREFIX}${width}x${height}`;
+/** The tallest software keyboard WebKit has reported at this window size, in an earlier launch too. */
+export function readMeasuredKeyboardHeight(width, height) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        const stored = Number(localStorage.getItem(storageKey(width, height)));
+        const plausible = stored >= SOFTWARE_KEYBOARD_MIN_HEIGHT && isPlausibleKeyboardHeight(width, height, stored);
+        return plausible ? stored : null;
+    }
+    catch {
+        // Storage can be unavailable (private mode, a test double): the default stands in.
+        return null;
+    }
+}
+export function rememberKeyboardHeight(width, height, keyboardHeight) {
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.setItem(storageKey(width, height), String(keyboardHeight));
+    }
+    catch {
+        // A full or unavailable store only costs the next launch its measured height.
+    }
+}
+/** The keyboard height to plan for: the tallest measured one, else the device default. */
+export function expectedKeyboardHeight(width, height) {
+    return readMeasuredKeyboardHeight(width, height) ?? defaultSoftwareKeyboardHeight(width, height);
+}

package/dist/keyboard/geometry.d.ts

@@ -0,0 +1,10 @@
+/** The keyboard overlap and viewport dimensions in points. */
+export type KeyboardGeometry = Readonly<{
+    height: number;
+    visible: boolean;
+    viewportHeight: number;
+    offsetTop: number;
+    layoutHeight: number;
+}>;
+export declare function keyboardGeometry(layoutHeight: number, visualHeight: number, offsetTop: number, scale: number, engaged: boolean): KeyboardGeometry;
+export declare function revealDelta(fieldTop: number, fieldBottom: number, surfaceTop: number, surfaceBottom: number, viewportBottom: number, gap?: number): number;

package/dist/keyboard/geometry.js

@@ -0,0 +1,21 @@
+export function keyboardGeometry(layoutHeight, visualHeight, offsetTop, scale, engaged) {
+    // Zoom is not keyboard occlusion. Hardware keyboards produce zero occlusion.
+    const height = engaged && Math.abs(scale - 1) < 0.01 ? Math.max(0, layoutHeight - visualHeight) : 0;
+    return {
+        height,
+        visible: height > 0,
+        viewportHeight: Math.max(0, layoutHeight - height),
+        offsetTop: height > 0 ? Math.max(0, offsetTop) : 0,
+        layoutHeight,
+    };
+}
+export function revealDelta(fieldTop, fieldBottom, surfaceTop, surfaceBottom, viewportBottom, gap = 12) {
+    const top = Math.max(0, surfaceTop) + gap;
+    const bottom = Math.min(surfaceBottom, viewportBottom) - gap;
+    if (fieldTop < top)
+        return fieldTop - top;
+    // Tall editors reveal their top; the native textarea owns caret scrolling.
+    if (fieldBottom - fieldTop > bottom - top)
+        return fieldTop - top;
+    return Math.max(0, fieldBottom - bottom);
+}

package/dist/keyboard/modalTapFocus.d.ts

@@ -0,0 +1,41 @@
+type Editor = HTMLInputElement | HTMLTextAreaElement;
+/**
+ * Own every focus of an editor, so that each one carries `preventScroll`.
+ *
+ * Measured on the iPad (1366 x 1024, the alert's field): a focus WebKit makes itself pans the
+ * visual viewport by 238.5 pt in one step when the keyboard arrives, and the page is drawn there
+ * until the next script frame puts it back. On a phone WebKit always centres a field it focused
+ * (WKContentView forces the scroll where the form accessory bar is shown). A focus made with
+ * `preventScroll` is never revealed by WebKit; the keyboard adapter reveals it. The ways a finger
+ * focuses an editor:
+ * - a short tap: focused at pointer-up, inside the activation the keyboard needs;
+ * - a tap held longer than that, or one that moved: its mouse press is prevented and focused here
+ *   (a 450 ms tap panned the page before this; repeating the focus afterwards did not help);
+ * - a label: its click is prevented and its editor focused here;
+ * - focus moving from an owned editor to another one in the same scope while the keyboard is up
+ *   and no Tab key was pressed (the keyboard's next/previous keys; an app's focus call between two
+ *   fields is indistinguishable and ends on the same field): the new editor is focused with
+ *   `preventScroll` from the old one's focusout, so WebKit abandons the call that would have
+ *   panned (it pans at once while the keyboard is up). Never for an inert field, across a dialog
+ *   boundary, or while a presentation is still moving;
+ * - anything else (a long press, an app's focus call with no editor focused, an assistive
+ *   technology or keyboard activation of a label): the focus is repeated with `preventScroll` in
+ *   its focusin, which WebKit accepts while its keyboard is not up yet.
+ * A mouse or trackpad press stays native from pointer-down to click: its drag selects text.
+ *
+ * Every gesture in an editor that is already focused stays native (caret taps, double-tap word
+ * selection, selection and caret drags), whether or not a keyboard shrinks the viewport (a hardware
+ * keyboard, an undocked keyboard, the ~100 ms before WebKit reports a software keyboard) and
+ * however it was focused. An editor focused without a press (by the app, Tab, or the next key)
+ * while no keyboard shows gets one more framework focus with `preventScroll` at the pointer-down
+ * of its first tap, so the editing session that tap starts is not revealed with a pan; the tap
+ * itself stays WebKit's.
+ */
+export declare function installModalTapFocus(root: HTMLElement, isEditable: (target: EventTarget | null) => target is Editor, 
+/** Called once this tap has focused the editor (its keyboard is on the way). */
+onTapFocus?: (editor: Editor) => void, 
+/** False while no keyboard is shown: a tap on the focused editor must then bring it back. */
+keyboardShowing?: () => boolean, 
+/** Which editors are owned. The keyboard adapter owns every editor in its root (pages too). */
+owns?: (editor: Element) => boolean): () => void;
+export {};