@octane-xplat/keyboard 0.0.1 → 0.17.0

package/src/focused-input.ts

@@ -0,0 +1,43 @@
+import { focusRuntime } from './focus-runtime'
+import type { FocusedInputService } from './focus-types'
+
+/** Observe input/caret layout without collecting text or owning editing delegates.
+ * @example
+ * ```ts
+ * import { FocusedInputController } from '@octane-xplat/keyboard'
+ * function observe(host: object) {
+ *   return FocusedInputController.subscribe(host, state => console.log(state.inputRect))
+ * }
+ * ```
+ */
+export const FocusedInputController: FocusedInputService = {
+	getSnapshot: (host) => focusRuntime.getSnapshot(host),
+	recheck: (host) => focusRuntime.recheck(host),
+	subscribe(host, listener) {
+		const deactivate = focusRuntime.activate()
+		let active = true
+		let off: () => void
+		try {
+			off = focusRuntime.subscribe(host, (state) => {
+				if (active) {
+					listener(state)
+				}
+			})
+		} catch (error) {
+			active = false
+			deactivate()
+			throw error
+		}
+		return () => {
+			if (!active) {
+				return
+			}
+			active = false
+			try {
+				off()
+			} finally {
+				deactivate()
+			}
+		}
+	},
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { KeyboardController } from './controller'
+export { FocusedInputController } from './focused-input'
+export type * from './focus-types'
+export { KeyboardProvider } from './Provider.tsrx'
+export type * from './types'
+export type * from './props'
+
+export { KeyboardScrollController } from './scroll-controller'
+export { KeyboardAwareScrollView } from './KeyboardAwareScrollView'
+export type * from './scroll-types'
+
+export { KeyboardStickyView } from './KeyboardStickyView'

package/src/motion.ts

@@ -0,0 +1,82 @@
+import { keyboardBottomOverlap } from '@octane-xplat/platform/keyboard-geometry'
+import type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+
+/** Native adapters supply measurements; this layer never interpolates geometry. */
+export function createKeyboardMotion(
+	publish: (state: KeyboardWindowState) => void,
+	capabilities: { interactive: boolean; floating: boolean },
+) {
+	let state: KeyboardWindowState | undefined
+	let transitionId = 0
+	let moving = false
+	let durationMs: number | null = null
+	const emit = (phase: NonNullable<KeyboardWindowState['motion']>['phase']) => {
+		if (!state) {
+			return
+		}
+		state = {
+			...state,
+			motion: {
+				phase,
+				transitionId,
+				timestampMs: Date.now(),
+				durationMs,
+				nativeFrames: true,
+				...capabilities,
+			},
+		}
+		publish(state)
+	}
+	return {
+		begin(target: KeyboardRect | null, duration: number | null = null) {
+			if (moving) {
+				emit('cancel')
+			}
+			transitionId++
+			moving = true
+			durationMs = duration !== null && Number.isFinite(duration) ? Math.max(0, duration) : null
+			if (state) {
+				state = {
+					...state,
+					targetFrame: target,
+					inset: keyboardBottomOverlap(state.windowRect, target),
+				}
+			}
+			emit('start')
+		},
+		measure(
+			windowRect: KeyboardRect,
+			currentFrame: KeyboardRect,
+			targetFrame?: KeyboardRect | null,
+			bindingFrame?: KeyboardRect,
+		) {
+			state = {
+				windowRect,
+				currentFrame,
+				bindingFrame,
+				targetFrame: targetFrame === undefined ? (state?.targetFrame ?? currentFrame) : targetFrame,
+				inset: keyboardBottomOverlap(
+					windowRect,
+					targetFrame === undefined ? (state?.targetFrame ?? currentFrame) : targetFrame,
+				),
+				source: 'native-frames',
+			}
+			emit(moving ? 'move' : 'idle')
+		},
+		end(confirmed = false) {
+			if (!moving && !confirmed) {
+				return
+			}
+			moving = false
+			emit('end')
+		},
+		cancel() {
+			if (!moving) {
+				return
+			}
+			moving = false
+			emit('cancel')
+		},
+	}
+}

package/src/native-scope.ts

@@ -0,0 +1,28 @@
+/** @internal Release every owned native resource, including failed attachment. */
+export function keyboardNativeScope() {
+	let active = true
+	const releases: (() => void)[] = []
+	return {
+		defer(release: () => void) {
+			releases.push(release)
+		},
+		release() {
+			if (!active) {
+				return
+			}
+			active = false
+			const errors: unknown[] = []
+			for (const release of releases.reverse()) {
+				try {
+					release()
+				} catch (error) {
+					errors.push(error)
+				}
+			}
+			releases.length = 0
+			if (errors.length) {
+				throw new AggregateError(errors, 'Keyboard native cleanup failed')
+			}
+		},
+	}
+}

package/src/prediction.ts

@@ -0,0 +1,32 @@
+/** UIKit presentation measurements describe the displayed frame. A property
+ * commit made in that display callback appears on the next refresh. Estimate
+ * only that bounded interval; current geometry stays a separate measurement.
+ * @internal */
+export function nextKeyboardPosition(options: {
+	current: number
+	previous: number
+	elapsedMs: number
+	nextMs: number
+	target: number
+	top: number
+	bottom: number
+}): number {
+	const { current, previous, elapsedMs, nextMs, target, top, bottom } = options
+	if (
+		![current, previous, elapsedMs, nextMs, target, top, bottom].every(Number.isFinite) ||
+		elapsedMs <= 0 ||
+		elapsedMs > 50 ||
+		nextMs <= 0 ||
+		nextMs > 34
+	) {
+		return current
+	}
+	const velocity = (current - previous) / elapsedMs
+	let estimate = current + velocity * nextMs
+	// A reversal may continue in the old direction before turning. Preserve
+	// that measured direction, but do not overshoot a target being approached.
+	if ((target - current) * velocity > 0) {
+		estimate = velocity > 0 ? Math.min(target, estimate) : Math.max(target, estimate)
+	}
+	return Math.max(top, Math.min(bottom, estimate))
+}

package/src/props.ts

@@ -0,0 +1,37 @@
+import type { KeyboardAvoidingProps, ViewProps } from '@octane-xplat/ui'
+/** Shared tracking for existing keyboard consumers. Native observers start with
+ * the first window reader and stop with the last. Web/desktop are neutral.
+ * @example
+ * ```tsx
+ * import { KeyboardProvider } from '@octane-xplat/keyboard'
+ * import { KeyboardAvoiding, TextInput } from '@octane-xplat/ui'
+ * <KeyboardProvider><KeyboardAvoiding><TextInput /></KeyboardAvoiding></KeyboardProvider>
+ * ```
+ */
+export interface KeyboardProviderProps {
+	children?: unknown
+	/** Activate native tracking; false retains children and fallback behavior. @default true */
+	enabled?: boolean
+}
+
+/** A vertical form that exposes the focused field/caret while the keyboard moves. */
+export interface KeyboardAwareScrollViewProps extends Omit<KeyboardAvoidingProps, 'ref'> {
+	/** Minimum visible gap; does not create scroll range. @default 8 */
+	clearance?: number
+	/** Additional bottom scroll range while the keyboard is open. @default 0 */
+	extraScrollSpace?: number
+	manualScroll?: 'pause' | 'follow'
+	keyboardClose?: 'preserve' | 'restore'
+	/** Mounted visibility binding; null on cleanup. */
+	ref?: (binding: import('./scroll-types').KeyboardScrollBinding | null) => void
+}
+
+/** Translate a control independently of surrounding layout as the native keyboard moves. */
+export interface KeyboardStickyViewProps extends ViewProps {
+	/** Disabled keeps its ordinary layout and releases native movement. @default true */
+	enabled?: boolean
+	/** Additional upward offset while open, in dips. @default 0 */
+	openOffset?: number
+	/** Upward offset while closed, in dips. @default 0 */
+	closedOffset?: number
+}

package/src/runtime-types.ts

@@ -0,0 +1,10 @@
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+
+/** @internal Platform adapter; shared policy never reads SDK or DOM objects. */
+export interface KeyboardRuntime {
+	activate(): () => void
+	subscribe(host: object, listener: (state: KeyboardWindowState) => void): () => void
+	getSnapshot(host: object): KeyboardWindowState
+	property(host: object): { read(): number; write(value: number): void } | null
+	overlap(host: object, state: KeyboardWindowState, translationY: number): number
+}

package/src/runtime.mobile.ts

@@ -0,0 +1,62 @@
+import { keyboardWindows } from '@octane-xplat/platform/keyboard-state'
+import { installKeyboardViewportAdapter } from '@octane-xplat/platform/keyboard-viewport'
+import {
+	keyboardHostDisplacement,
+	keyboardSnapshotForHost,
+	observeKeyboardDestination,
+	subscribeKeyboardState,
+} from '@octane-xplat/ui/nativescript/keyboard'
+
+import { observeKeyboardMotion } from './source'
+import type { KeyboardRuntime } from './runtime-types'
+import { leaseKeyboardViewport } from './viewport'
+import { focusRuntime } from './focus-runtime'
+
+export const keyboardRuntime: KeyboardRuntime = {
+	activate() {
+		const offFocus = focusRuntime.activate()
+		let offViewport = () => {}
+		let offSource: () => void
+		try {
+			offViewport = installKeyboardViewportAdapter(leaseKeyboardViewport)
+			offSource = keyboardWindows.install(observeKeyboardMotion ?? observeKeyboardDestination)
+		} catch (error) {
+			try {
+				offViewport()
+			} finally {
+				offFocus()
+			}
+
+			throw error
+		}
+		let active = true
+		return () => {
+			if (!active) {
+				return
+			}
+			active = false
+			try {
+				offSource()
+			} finally {
+				try {
+					offViewport()
+				} finally {
+					offFocus()
+				}
+			}
+		}
+	},
+	subscribe: (host, listener) => subscribeKeyboardState(listener, host, false),
+	getSnapshot: keyboardSnapshotForHost,
+	property(host: any) {
+		return host?.nativeViewProtected
+			? {
+					read: () => Number(host.translateY) || 0,
+					write: (value) => {
+						host.translateY = value
+					},
+				}
+			: null
+	},
+	overlap: keyboardHostDisplacement,
+}

package/src/runtime.ts

@@ -0,0 +1,16 @@
+import { unknownKeyboardState } from '@octane-xplat/platform/keyboard-state'
+import type { KeyboardRuntime } from './runtime-types'
+
+const state = unknownKeyboardState()
+
+/** Web and desktop retain neutral software-keyboard behavior. */
+export const keyboardRuntime: KeyboardRuntime = {
+	activate: () => () => {},
+	subscribe(_host, listener) {
+		listener(state)
+		return () => {}
+	},
+	getSnapshot: () => state,
+	property: () => null,
+	overlap: () => 0,
+}

package/src/scroll-controller.ts

@@ -0,0 +1,136 @@
+import { keyboardNativeScope } from './native-scope'
+import { KeyboardController } from './controller'
+import { FocusedInputController } from './focused-input'
+import { focusScrollPlan } from './scroll-geometry'
+import { scrollRuntime } from './scroll-runtime'
+import type { KeyboardScrollOptions, KeyboardScrollService } from './scroll-types'
+
+const checked = (options: KeyboardScrollOptions) => {
+	if (!Number.isFinite(options.clearance ?? 8) || (options.clearance ?? 8) < 0) {
+		throw new RangeError('Keyboard scroll clearance must be finite and nonnegative')
+	}
+	return { ...options }
+}
+
+/** Focus visibility without per-frame component rendering. */
+export const KeyboardScrollController: KeyboardScrollService = {
+	bind(host, initial = {}) {
+		let options = checked(initial),
+			active = true,
+			paused = false,
+			applying = false
+		let focus = FocusedInputController.getSnapshot(host)
+		let keyboard = KeyboardController.getSnapshot(host)
+		let open = false
+		const restoration = new Map<object, { before: number; expected: number }>()
+		const scope = keyboardNativeScope()
+		const apply = () => {
+			if (!active || applying) {
+				return
+			}
+			applying = true
+			try {
+				const root = scrollRuntime.owner(host)
+				const frame = keyboard.currentFrame ?? keyboard.targetFrame
+				const bottom = keyboard.windowRect && keyboard.windowRect.y + keyboard.windowRect.height
+				const nowOpen =
+					keyboard.inset > 0 || !!(frame && bottom && frame.height > 0 && frame.y < bottom)
+
+				if (open && !nowOpen) {
+					if (options.keyboardClose === 'restore') {
+						for (const [owner, saved] of restoration) {
+							const current = scrollRuntime.read(owner)
+							if (current !== null && Math.abs(current - saved.expected) < 1) {
+								scrollRuntime.write(owner, saved.before)
+							}
+						}
+					}
+
+					restoration.clear()
+					open = false
+					return
+				}
+
+				open = nowOpen
+				if (!root || paused) {
+					return
+				}
+
+				for (const operation of focusScrollPlan(focus, keyboard, root, options.clearance ?? 8)) {
+					if (nowOpen) {
+						const previous = restoration.get(operation.id)
+						restoration.set(operation.id, {
+							before: previous?.before ?? operation.from,
+							expected: operation.to,
+						})
+					}
+
+					scrollRuntime.write(operation.id, operation.to)
+				}
+			} finally {
+				applying = false
+			}
+		}
+		const release = () => {
+			if (!active) {
+				return
+			}
+			active = false
+			try {
+				scope.release()
+			} finally {
+				restoration.clear()
+			}
+		}
+		try {
+			scope.defer(
+				scrollRuntime.watchManual(host, () => {
+					paused = options.manualScroll !== 'follow'
+					restoration.clear()
+				}),
+			)
+
+			scope.defer(
+				KeyboardController.onMove(host, (state) => {
+					keyboard = state
+					apply()
+				}),
+			)
+
+			scope.defer(
+				FocusedInputController.subscribe(host, (state) => {
+					if (
+						state.input !== focus.input ||
+						state.selection?.start !== focus.selection?.start ||
+						state.selection?.end !== focus.selection?.end
+					) {
+						paused = false
+					}
+					focus = state
+					apply()
+				}),
+			)
+		} catch (error) {
+			release()
+			throw error
+		}
+		return {
+			release,
+			update(next) {
+				options = checked(next)
+				if (active) {
+					apply()
+				}
+			},
+			recheck() {
+				if (!active) {
+					return
+				}
+				paused = false
+				FocusedInputController.recheck(host)
+				focus = FocusedInputController.getSnapshot(host)
+				apply()
+			},
+		}
+	},
+}

package/src/scroll-geometry.ts

@@ -0,0 +1,72 @@
+import type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import type { FocusedInputSnapshot } from './focus-types'
+import type { KeyboardSnapshot } from './types'
+
+export interface FocusScrollOperation {
+	id: object
+	from: number
+	to: number
+}
+
+/** Plan nearest-first minimal scrolling; SDK writes live in platform leaves. */
+export function focusScrollPlan(
+	focus: FocusedInputSnapshot,
+	keyboard: KeyboardSnapshot,
+	root: object,
+	clearance: number,
+): FocusScrollOperation[] {
+	const end = focus.scrollOwners.findIndex((owner) => owner.id === root)
+	if (end < 0 || !focus.inputRect || !focus.windowRect) {
+		return []
+	}
+	const owners = focus.scrollOwners.slice(0, end + 1)
+	let target: KeyboardRect = { ...focus.inputRect }
+	let windowBottom = focus.windowRect.y + focus.windowRect.height
+	const frame = keyboard.currentFrame ?? keyboard.targetFrame
+	if (
+		frame &&
+		frame.y + frame.height >= windowBottom - 1 &&
+		frame.height > 0 &&
+		frame.x < target.x + target.width &&
+		frame.x + frame.width > target.x
+	) {
+		windowBottom = Math.min(windowBottom, frame.y)
+	}
+	const available =
+		Math.min(
+			...owners.map(
+				(owner) =>
+					Math.min(owner.rect.y + owner.rect.height, windowBottom) -
+					Math.max(owner.rect.y, focus.windowRect!.y),
+			),
+		) -
+		clearance * 2
+	if (target.height > available && focus.caretRect) {
+		target = { ...focus.caretRect }
+	}
+	const result: FocusScrollOperation[] = []
+	for (const owner of owners) {
+		const top = Math.max(owner.rect.y, focus.windowRect.y) + clearance
+		const bottom = Math.min(owner.rect.y + owner.rect.height, windowBottom) - clearance
+		if (bottom <= top) {
+			continue
+		}
+
+		const delta =
+			target.height > bottom - top
+				? target.y - top
+				: target.y < top
+					? target.y - top
+					: target.y + target.height > bottom
+						? target.y + target.height - bottom
+						: 0
+
+		const to = Math.max(owner.minOffsetY, Math.min(owner.maxOffsetY, owner.offsetY + delta))
+		const moved = to - owner.offsetY
+		if (Math.abs(moved) > 0.5) {
+			result.push({ id: owner.id, from: owner.offsetY, to })
+			target = { ...target, y: target.y - moved }
+		}
+	}
+	return result
+}

package/src/scroll-runtime-types.ts

@@ -0,0 +1,6 @@
+export interface FocusScrollRuntime {
+	owner(host: object): object | null
+	read(owner: object): number | null
+	write(owner: object, offset: number): void
+	watchManual(host: object, listener: () => void): () => void
+}

package/src/scroll-runtime.macos.ts

@@ -0,0 +1,41 @@
+import { NSNotificationCenter, NSOperationQueue } from '@octane-xplat/platform/macos'
+import type { FocusScrollRuntime } from './scroll-runtime-types'
+export const scrollRuntime: FocusScrollRuntime = {
+	owner: (host) => (host as any).native ?? host,
+	read(owner: any) {
+		const clip = owner.contentView,
+			content = owner.documentView
+		if (!clip || !content) {
+			return null
+		}
+		const flipped =
+			typeof content.isFlipped === 'function' ? content.isFlipped() : content.isFlipped
+		const max = Math.max(0, content.bounds.size.height - clip.bounds.size.height)
+		return flipped ? clip.bounds.origin.y : max - clip.bounds.origin.y
+	},
+	write(owner: any, offset) {
+		const clip = owner.contentView,
+			content = owner.documentView
+		if (!clip || !content) {
+			return
+		}
+		const flipped =
+			typeof content.isFlipped === 'function' ? content.isFlipped() : content.isFlipped
+		const max = Math.max(0, content.bounds.size.height - clip.bounds.size.height)
+		clip.scrollToPoint({
+			x: clip.bounds.origin.x,
+			y: flipped ? Math.max(0, Math.min(max, offset)) : max - Math.max(0, Math.min(max, offset)),
+		})
+		owner.reflectScrolledClipView(clip)
+	},
+	watchManual(host: any, listener) {
+		const center = NSNotificationCenter.defaultCenter
+		const token = center.addObserverForNameObjectQueueUsingBlock(
+			'NSScrollViewWillStartLiveScrollNotification',
+			host.native ?? host,
+			NSOperationQueue.mainQueue,
+			listener,
+		)
+		return () => center.removeObserver(token)
+	},
+}

package/src/scroll-runtime.mobile.ts

@@ -0,0 +1,46 @@
+import { Utils } from '@nativescript/core'
+import type { FocusScrollRuntime } from './scroll-runtime-types'
+const native = (host: any) => host.nativeViewProtected ?? host.ios ?? host.android
+export const scrollRuntime: FocusScrollRuntime = {
+	owner: (host) => native((host as any).native ?? host) ?? null,
+	read: (owner: any) =>
+		owner.setContentOffsetAnimated || typeof owner.mason_scrollTo !== 'function'
+			? (owner.contentOffset?.y ?? Utils.layout.toDeviceIndependentPixels(owner.getScrollY()))
+			: owner.mason_scrollTop,
+	write(owner: any, offset) {
+		if (owner.setContentOffsetAnimated) {
+			owner.setContentOffsetAnimated(
+				{
+					x: owner.contentOffset.x,
+					y: Math.max(
+						-(owner.adjustedContentInset?.top ?? 0),
+						Math.min(
+							offset,
+							Math.max(
+								-(owner.adjustedContentInset?.top ?? 0),
+								owner.contentSize.height -
+									owner.bounds.size.height +
+									(owner.adjustedContentInset?.bottom ?? 0),
+							),
+						),
+					),
+				},
+				false,
+			)
+		} else if (typeof owner.mason_scrollTo === 'function') {
+			owner.mason_scrollTo(NaN, offset, false)
+		} else {
+			owner.scrollTo(owner.getScrollX(), Utils.layout.toDevicePixels(offset))
+		}
+	},
+	watchManual(host: any, listener) {
+		const view = host.native ?? host
+		const touch = (event: any) => {
+			if (event.action === 'move') {
+				listener()
+			}
+		}
+		view.on('touch', touch)
+		return () => view.off('touch', touch)
+	},
+}

package/src/scroll-runtime.ts

@@ -0,0 +1,7 @@
+import type { FocusScrollRuntime } from './scroll-runtime-types'
+export const scrollRuntime: FocusScrollRuntime = {
+	owner: () => null,
+	read: () => null,
+	write() {},
+	watchManual: () => () => {},
+}

package/src/scroll-runtime.web.ts

@@ -0,0 +1,25 @@
+import type { FocusScrollRuntime } from './scroll-runtime-types'
+export const scrollRuntime: FocusScrollRuntime = {
+	owner: (host) => (host as any).native ?? host,
+	read: (owner) => (owner as HTMLElement).scrollTop,
+	write(owner, offset) {
+		;(owner as HTMLElement).scrollTop = offset
+	},
+	watchManual(host, listener) {
+		const view = ((host as any).native ?? host) as HTMLElement
+		const events = ['wheel', 'touchmove', 'pointermove']
+		const manual = (event: Event) => {
+			if (event.type !== 'pointermove' || (event as PointerEvent).buttons) {
+				listener()
+			}
+		}
+		for (const event of events) {
+			view.addEventListener(event, manual, { passive: true })
+		}
+		return () => {
+			for (const event of events) {
+				view.removeEventListener(event, manual)
+			}
+		}
+	},
+}