@octane-xplat/keyboard 0.0.1 → 0.17.1

package/src/scroll-types.ts

@@ -0,0 +1,24 @@
+/** Geometry policy for vertical focused-input scrolling. */
+export interface KeyboardScrollOptions {
+	/** Minimum gap around the input/caret, in window layout units. @default 8 */
+	clearance?: number
+	/** Pause after a user scroll until focus/selection changes or recheck. @default 'pause' */
+	manualScroll?: 'pause' | 'follow'
+	/** Keep the resulting offset, or restore untouched offsets on close. @default 'preserve' */
+	keyboardClose?: 'preserve' | 'restore'
+}
+
+export interface KeyboardScrollBinding {
+	/** Explicitly resume visibility enforcement after validation or manual scrolling. */
+	recheck(): void
+	/** Apply changed options without restarting window observation. */
+	update(options: KeyboardScrollOptions): void
+	/** Release observation; preserves the current scroll position. */
+	release(): void
+}
+
+export interface KeyboardScrollService {
+	/** Attach to a vertical scroll viewport. Only scroll ancestors through this
+	 * viewport are eligible; unrelated fields in the same window are ignored. */
+	bind(host: object, options?: KeyboardScrollOptions): KeyboardScrollBinding
+}

package/src/source.android.ts

@@ -0,0 +1,179 @@
+import { Utils } from '@nativescript/core'
+import { android } from '@octane-xplat/platform/android'
+import type { KeyboardWindowSource } from '@octane-xplat/platform/keyboard-registry'
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+import { observeKeyboardDestination } from '@octane-xplat/ui/nativescript/keyboard'
+import { createKeyboardMotion } from './motion'
+import { keyboardNativeScope } from './native-scope'
+
+let AnimationCallback: any
+const callbackClass = (core: any) => {
+	if (!AnimationCallback) {
+		AnimationCallback = core.WindowInsetsAnimationCompat.Callback.extend({
+			onPrepare(this: any, animation: any) {
+				this.handlers?.prepare(animation)
+			},
+			onStart(this: any, animation: any, bounds: any) {
+				this.handlers?.start(animation)
+				return bounds
+			},
+			onProgress(this: any, insets: any) {
+				this.handlers?.progress(insets)
+				return insets
+			},
+			onEnd(this: any, animation: any) {
+				this.handlers?.end(animation)
+			},
+		})
+	}
+	return AnimationCallback
+}
+
+/** Callback lives only on our helper; decor/foreign callbacks remain untouched. */
+export const observeKeyboardMotion: KeyboardWindowSource<KeyboardWindowState> = (key, publish) => {
+	const decor = key as any
+	const core = (globalThis as any).androidx?.core?.view
+	if (
+		!core?.WindowInsetsAnimationCompat ||
+		android.os.Build.VERSION.SDK_INT < 30 ||
+		!decor.addView
+	) {
+		return observeKeyboardDestination(key, publish)
+	}
+	const scope = keyboardNativeScope()
+	try {
+		const helper = new android.view.View(decor.getContext())
+		helper.setImportantForAccessibility(2)
+		helper.setFocusable(false)
+		helper.setClickable(false)
+		decor.addView(helper, new android.view.ViewGroup.LayoutParams(0, 0))
+		scope.defer(() => {
+			const remove = () => {
+				if (helper.getParent() === decor) {
+					decor.removeView(helper)
+				}
+			}
+			// A reader may release from a child's native detach callback. Android
+			// is still iterating decor children then; removing one corrupts that walk.
+			setTimeout(remove, 0)
+		})
+
+		const type = core.WindowInsetsCompat.Type
+		const dip = Utils.layout.toDeviceIndependentPixels
+		let targetInset = 0
+		const motion = createKeyboardMotion((state) => publish({ ...state, inset: targetInset }), {
+			interactive: false,
+			floating: false,
+		})
+
+		let active = true
+		scope.defer(() => {
+			active = false
+		})
+
+		let animation: any
+		let target: any
+		const geometry = (insets: any) => {
+			const width = dip(decor.getWidth()),
+				height = dip(decor.getHeight())
+			const ime = dip(insets?.getInsets(type.ime()).bottom ?? 0)
+			return {
+				window: { x: 0, y: 0, width, height },
+				frame: { x: 0, y: height - ime, width, height: ime },
+			}
+		}
+
+		const read = () => core.ViewCompat.getRootWindowInsets(decor)
+		const destination = () => {
+			const insets = read()
+			if (!insets) {
+				return
+			}
+			target = geometry(insets).frame
+			targetInset = dip(
+				Math.max(
+					0,
+					insets.getInsets(type.ime()).bottom - insets.getInsets(type.systemBars()).bottom,
+				),
+			)
+		}
+
+		const measure = (insets: any) => {
+			if (!active || !insets) {
+				return
+			}
+			const value = geometry(insets)
+			if (value.window.width > 0 && value.window.height > 0) {
+				motion.measure(value.window, value.frame, target ?? value.frame)
+			}
+		}
+
+		const callback = new (callbackClass(core))(1)
+		callback.handlers = {
+			prepare(next: any) {
+				if (!active || !(next.getTypeMask() & type.ime())) {
+					return
+				}
+				// Replacing a running animation cancels it before the new start.
+				if (animation) {
+					motion.cancel()
+				}
+				animation = next
+			},
+			start(next: any) {
+				if (!active || next !== animation) {
+					return
+				}
+				destination()
+				motion.begin(target, Number(next.getDurationMillis()))
+			},
+			progress(insets: any) {
+				measure(insets)
+			},
+			end(next: any) {
+				if (!active || next !== animation) {
+					return
+				}
+				measure(read())
+				motion.end()
+				animation = undefined
+			},
+		}
+
+		scope.defer(() => {
+			callback.handlers = undefined
+			core.ViewCompat.setWindowInsetsAnimationCallback(helper, null)
+		})
+
+		core.ViewCompat.setWindowInsetsAnimationCallback(helper, callback)
+		const layoutListener = new android.view.ViewTreeObserver.OnGlobalLayoutListener({
+			onGlobalLayout() {
+				if (!active || animation) {
+					return
+				}
+				destination()
+				measure(read())
+			},
+		})
+
+		scope.defer(() => {
+			const tree = decor.getViewTreeObserver()
+			if (tree.isAlive()) {
+				tree.removeOnGlobalLayoutListener(layoutListener)
+			}
+		})
+
+		decor.getViewTreeObserver().addOnGlobalLayoutListener(layoutListener)
+		destination()
+		measure(read())
+		return () => scope.release()
+	} catch (error) {
+		try {
+			scope.release()
+		} catch (cleanup) {
+			throw new AggregateError([error, cleanup], 'Keyboard native attachment failed')
+		}
+
+		throw error
+	}
+}

package/src/source.ios.ts

@@ -0,0 +1,283 @@
+import {
+	NSObject,
+	CADisplayLink,
+	NSRunLoop,
+	UIView,
+	NSLayoutConstraint,
+	NSNotificationCenter,
+	NSOperationQueue,
+} from '@octane-xplat/platform/ios'
+
+import { isKeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import type { KeyboardWindowSource } from '@octane-xplat/platform/keyboard-registry'
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+import { observeKeyboardDestination } from '@octane-xplat/ui/nativescript/keyboard'
+import { createKeyboardMotion } from './motion'
+import { nextKeyboardPosition } from './prediction'
+import { keyboardNativeScope } from './native-scope'
+
+let DisplayTarget: any
+const displayTarget = () => {
+	if (!DisplayTarget) {
+		const interop = (globalThis as any).interop
+		DisplayTarget = (NSObject as any).extend(
+			{
+				['tick:'](this: any, link: any) {
+					this.onTick?.(link)
+				},
+			},
+			{ exposedMethods: { 'tick:': { returns: interop.types.void, params: [CADisplayLink] } } },
+		)
+	}
+	return DisplayTarget.new()
+}
+
+const rect = (value: any): KeyboardRect => ({
+	x: value.origin.x,
+	y: value.origin.y,
+	width: value.size.width,
+	height: value.size.height,
+})
+
+/** Own every guide, constraint and display-link target; never mutate a host guide. */
+export const observeKeyboardMotion: KeyboardWindowSource<KeyboardWindowState> = (key, publish) => {
+	const window = key as any
+	const root = window.rootViewController?.view
+	if (!root?.keyboardLayoutGuide?.respondsToSelector('setUsesBottomSafeArea:')) {
+		return observeKeyboardDestination(key, publish)
+	}
+	const scope = keyboardNativeScope()
+	try {
+		const container = UIView.new()
+		container.translatesAutoresizingMaskIntoConstraints = false
+		container.userInteractionEnabled = false
+		container.accessibilityElementsHidden = true
+		root.addSubview(container)
+		scope.defer(() => container.removeFromSuperview())
+		const guide = container.keyboardLayoutGuide
+		guide.usesBottomSafeArea = false
+		const tracker = UIView.new()
+		tracker.translatesAutoresizingMaskIntoConstraints = false
+		tracker.userInteractionEnabled = false
+		container.addSubview(tracker)
+		const constraints = [
+			container.leadingAnchor.constraintEqualToAnchor(root.leadingAnchor),
+			container.trailingAnchor.constraintEqualToAnchor(root.trailingAnchor),
+			container.topAnchor.constraintEqualToAnchor(root.topAnchor),
+			container.bottomAnchor.constraintEqualToAnchor(root.bottomAnchor),
+			tracker.leadingAnchor.constraintEqualToAnchor(container.leadingAnchor),
+			tracker.trailingAnchor.constraintEqualToAnchor(container.trailingAnchor),
+			tracker.bottomAnchor.constraintEqualToAnchor(guide.topAnchor),
+			tracker.heightAnchor.constraintEqualToConstant(0),
+		]
+
+		scope.defer(() => NSLayoutConstraint.deactivateConstraints(constraints))
+		NSLayoutConstraint.activateConstraints(constraints)
+		root.layoutIfNeeded()
+		// A newly constrained view starts at the guide's model destination. It
+		// cannot measure a transition that began before it existed. Wait for a
+		// native completion and matching presentation before advertising frames.
+		let calibrated = false
+		let confirmedFrame: KeyboardRect | null = null
+		let bootstrapPhase: 'idle' | 'start' = 'idle'
+		let coarseKey = ''
+		const motion = createKeyboardMotion(
+			(state) => {
+				if (calibrated) {
+					publish(state)
+					return
+				}
+				const key = JSON.stringify([
+					state.windowRect,
+					state.targetFrame,
+					bootstrapPhase,
+					state.motion?.transitionId,
+				])
+				if (key === coarseKey) {
+					return
+				}
+				coarseKey = key
+				publish({
+					...state,
+					source: 'destination',
+					currentFrame: null,
+					bindingFrame: undefined,
+					motion: state.motion && {
+						...state.motion,
+						phase: bootstrapPhase,
+						nativeFrames: false,
+						interactive: false,
+					},
+				})
+			},
+			{ interactive: true, floating: false },
+		)
+
+		let active = true
+		scope.defer(() => {
+			active = false
+		})
+
+		let moving = false
+		let settled = 0
+		let lastY = NaN
+		let lastTimestamp = NaN
+		let lastWidth = NaN
+		let lastHeight = NaN
+		let targetFrame: KeyboardRect | null = null
+		const read = (link?: any) => {
+			if (!active || container.window !== window) {
+				return
+			}
+			const bounds = rect(window.bounds)
+			const current = tracker.layer.presentationLayer()?.frame ?? tracker.frame
+			const local = container.convertRectToView(current, window)
+			const y = local.origin.y
+			const frame = {
+				x: bounds.x,
+				y,
+				width: bounds.width,
+				height: Math.max(0, bounds.y + bounds.height - y),
+			}
+			if (!isKeyboardRect(bounds) || !isKeyboardRect(frame)) {
+				return
+			}
+			const destination = rect(container.convertRectToView(guide.layoutFrame, window))
+			if (!targetFrame) {
+				targetFrame = destination
+			}
+			const justCalibrated =
+				!calibrated &&
+				confirmedFrame !== null &&
+				Math.abs(y - confirmedFrame.y) < 0.5 &&
+				Math.abs(destination.y - confirmedFrame.y) < 0.5
+			if (justCalibrated) {
+				calibrated = true
+			}
+			if (!moving && Number.isFinite(lastY) && Math.abs(lastY - y) > 0.1) {
+				motion.begin(targetFrame)
+				moving = true
+			}
+			// Stable reads do not wake consumers at display refresh rate.
+			if (
+				justCalibrated ||
+				moving ||
+				!Number.isFinite(lastY) ||
+				Math.abs(lastY - y) > 0.01 ||
+				lastWidth !== bounds.width ||
+				lastHeight !== bounds.height
+			) {
+				const nextY =
+					moving && link
+						? nextKeyboardPosition({
+								current: y,
+								previous: lastY,
+								elapsedMs: (link.timestamp - lastTimestamp) * 1000,
+								nextMs: (link.targetTimestamp - link.timestamp) * 1000,
+								target: targetFrame.y,
+								top: bounds.y,
+								bottom: bounds.y + bounds.height,
+							})
+						: y
+
+				motion.measure(bounds, frame, targetFrame, {
+					...frame,
+					y: nextY,
+					height: Math.max(0, bounds.y + bounds.height - nextY),
+				})
+
+				if (justCalibrated) {
+					motion.end(true)
+				}
+			}
+			if (moving) {
+				settled = Math.abs(y - destination.y) < 0.5 && Math.abs(y - lastY) < 0.1 ? settled + 1 : 0
+				if (settled >= 2) {
+					moving = false
+					motion.end()
+				}
+			}
+			lastY = y
+			lastTimestamp = link?.timestamp ?? NaN
+			lastWidth = bounds.width
+			lastHeight = bounds.height
+		}
+
+		read()
+		const target = displayTarget()
+		target.onTick = read
+		const link = CADisplayLink.displayLinkWithTargetSelector(target, 'tick:')
+		scope.defer(() => {
+			target.onTick = undefined
+			link.invalidate()
+		})
+
+		link.addToRunLoopForMode(NSRunLoop.mainRunLoop, 'kCFRunLoopCommonModes')
+		const center = NSNotificationCenter.defaultCenter
+		const token = center.addObserverForNameObjectQueueUsingBlock(
+			UIKeyboardWillChangeFrameNotification,
+			null,
+			NSOperationQueue.mainQueue,
+			(note: any) => {
+				if (!active || (note.object?.coordinateSpace && note.object !== window.screen)) {
+					return
+				}
+				const raw = note.userInfo.objectForKey(UIKeyboardFrameEndUserInfoKey)
+				const value = typeof raw?.CGRectValue === 'function' ? raw.CGRectValue() : raw?.CGRectValue
+				if (!value) {
+					return
+				}
+				const local = window.screen?.coordinateSpace
+					? window.convertRectFromCoordinateSpace(value, window.screen.coordinateSpace)
+					: window.convertRectFromWindow(value, null)
+				targetFrame = rect(local)
+				bootstrapPhase = 'start'
+				confirmedFrame = null
+				const duration =
+					Number(note.userInfo.objectForKey(UIKeyboardAnimationDurationUserInfoKey)) * 1000
+				motion.begin(targetFrame, Number.isFinite(duration) ? duration : null)
+				moving = true
+				settled = 0
+			},
+		)
+
+		scope.defer(() => center.removeObserver(token))
+		const completion = center.addObserverForNameObjectQueueUsingBlock(
+			UIKeyboardDidChangeFrameNotification,
+			null,
+			NSOperationQueue.mainQueue,
+			(note: any) => {
+				if (
+					!active ||
+					calibrated ||
+					(note.object?.coordinateSpace && note.object !== window.screen)
+				) {
+					return
+				}
+				const raw = note.userInfo.objectForKey(UIKeyboardFrameEndUserInfoKey)
+				const value = typeof raw?.CGRectValue === 'function' ? raw.CGRectValue() : raw?.CGRectValue
+				if (!value) {
+					return
+				}
+				confirmedFrame = rect(
+					window.screen?.coordinateSpace
+						? window.convertRectFromCoordinateSpace(value, window.screen.coordinateSpace)
+						: window.convertRectFromWindow(value, null),
+				)
+				targetFrame = confirmedFrame
+			},
+		)
+
+		scope.defer(() => center.removeObserver(completion))
+		return () => scope.release()
+	} catch (error) {
+		try {
+			scope.release()
+		} catch (cleanup) {
+			throw new AggregateError([error, cleanup], 'Keyboard native attachment failed')
+		}
+
+		throw error
+	}
+}

package/src/source.ts

@@ -0,0 +1,5 @@
+import type { KeyboardWindowSource } from '@octane-xplat/platform/keyboard-registry'
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+
+/** Unsupported native contexts retain destination observation. */
+export const observeKeyboardMotion: KeyboardWindowSource<KeyboardWindowState> | null = null

package/src/tsconfig.json

@@ -0,0 +1 @@
+{"extends":"../../../tsconfig.base.json"}

package/src/types.ts

@@ -0,0 +1,45 @@
+import type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+
+export type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+
+/** Lifecycle of one keyboard transition. An interrupted transition cancels
+ * before the replacement starts; current geometry never jumps to its target. */
+export type KeyboardPhase = 'idle' | 'start' | 'move' | 'end' | 'cancel'
+
+/** Capabilities belong to the actual host window and active adapter. */
+export interface KeyboardCapabilities {
+	readonly geometry: boolean
+	readonly nativeFrames: boolean
+	readonly interactive: boolean
+	readonly floating: boolean
+}
+
+/** Geometry is in device-independent coordinates in the owning window.
+ * Null frames are unavailable; source distinguishes unknown from measured hidden.
+ * A destination frame is never presented as measured intermediate movement. */
+export interface KeyboardSnapshot {
+	readonly inset: number
+	readonly windowRect: KeyboardRect | null
+	readonly currentFrame: KeyboardRect | null
+	readonly targetFrame: KeyboardRect | null
+	readonly source: 'unknown' | 'destination' | 'native-frames'
+	readonly capabilities: KeyboardCapabilities
+	readonly phase: KeyboardPhase
+	readonly transitionId: number
+	/** Unix milliseconds at delivery. */
+	readonly timestampMs: number
+	/** Native destination transition duration, or null when unknown. */
+	readonly durationMs: number | null
+}
+
+export interface SoftwareKeyboardController {
+	/** Activate shared native tracking until release. Observation starts only
+	 * when a window has readers. Repeated activations share ownership. */
+	activate(): () => void
+	/** Read available cached state without activating observation. */
+	getSnapshot(host: object): KeyboardSnapshot
+	/** Observe destination/lifecycle changes, excluding per-frame movement. */
+	subscribe(host: object, listener: (snapshot: KeyboardSnapshot) => void): () => void
+	/** Observe measured movement directly; callbacks must not render per frame. */
+	onMove(host: object, listener: (snapshot: KeyboardSnapshot) => void): () => void
+}

package/src/viewport-types.ts

@@ -0,0 +1,7 @@
+/** @internal A consumer-owned native viewport policy, separate from observation. */
+export interface KeyboardViewportLease {
+	readonly supported: boolean
+	/** Follow replacement native views belonging to the same framework host. */
+	update(): void
+	release(): void
+}