@octane-xplat/keyboard 0.0.1 → 0.17.0

package/src/controller.ts

@@ -0,0 +1,243 @@
+import { keyboardBottomOverlap } from '@octane-xplat/platform/keyboard-geometry'
+import { leaseKeyboardProperty } from '@octane-xplat/platform/keyboard-property'
+import type { KeyboardPropertyLease } from '@octane-xplat/platform/keyboard-property'
+import { observeKeyboardViewport } from '@octane-xplat/platform/keyboard-viewport'
+import type { KeyboardViewportLease } from '@octane-xplat/platform/keyboard-viewport'
+import type { KeyboardWindowState } from '@octane-xplat/platform/keyboard-state'
+import { keyboardRuntime } from './runtime'
+import type { KeyboardBindingOptions, KeyboardHostBinding } from './binding-types'
+import type { KeyboardSnapshot, SoftwareKeyboardController } from './types'
+
+const snapshots = new WeakMap<KeyboardWindowState, KeyboardSnapshot>()
+const snapshot = (state: KeyboardWindowState): KeyboardSnapshot => {
+	let value = snapshots.get(state)
+	if (!value) {
+		value = {
+			inset: state.inset,
+			windowRect: state.windowRect,
+			currentFrame: state.currentFrame,
+			targetFrame: state.targetFrame,
+			source: state.source,
+			capabilities: {
+				geometry: !!state.windowRect && state.source !== 'unknown',
+				nativeFrames: state.motion?.nativeFrames ?? state.source === 'native-frames',
+				interactive: state.motion?.interactive ?? false,
+				floating: state.motion?.floating ?? false,
+			},
+			phase: state.motion?.phase ?? 'idle',
+			transitionId: state.motion?.transitionId ?? 0,
+			timestampMs: state.motion?.timestampMs ?? 0,
+			durationMs: state.motion?.durationMs ?? null,
+		}
+
+		snapshots.set(state, value)
+	}
+	return value
+}
+
+const observeState = (host: object, listener: (state: KeyboardWindowState) => void) => {
+	const deactivate = keyboardRuntime.activate()
+	let active = true
+	let off: () => void
+	try {
+		off = keyboardRuntime.subscribe(host, (state) => {
+			if (active) {
+				listener(state)
+			}
+		})
+	} catch (error) {
+		active = false
+		deactivate()
+		throw error
+	}
+	return () => {
+		if (!active) {
+			return
+		}
+		active = false
+		try {
+			off()
+		} finally {
+			deactivate()
+		}
+	}
+}
+
+const observe = (host: object, listener: (state: KeyboardSnapshot) => void) =>
+	observeState(host, (state) => listener(snapshot(state)))
+
+const validateBindingOptions = (options: KeyboardBindingOptions) => {
+	for (const value of [options.openOffset, options.closedOffset, options.consumedBottom]) {
+		if (value !== undefined && !Number.isFinite(value)) {
+			throw new RangeError('Keyboard offsets must be finite')
+		}
+	}
+}
+
+type Binding = {
+	lease: KeyboardPropertyLease
+	viewport: KeyboardViewportLease
+	owners: { read(): KeyboardBindingOptions }[]
+	state?: KeyboardWindowState
+	openExtent: number
+	off: () => void
+}
+
+const bindings = new WeakMap<object, Binding>()
+
+const apply = (host: object, binding: Binding) => {
+	const measured = binding.state,
+		options = binding.owners.at(-1)?.read()
+	if (!measured || !options) {
+		return
+	}
+	validateBindingOptions(options)
+	const state = measured.bindingFrame
+		? { ...measured, currentFrame: measured.bindingFrame }
+		: measured
+	binding.viewport.update()
+	const frame = state.currentFrame ?? state.targetFrame
+	const current = keyboardBottomOverlap(state.windowRect, frame)
+	const target = keyboardBottomOverlap(state.windowRect, state.targetFrame)
+	if (target > 0) {
+		binding.openExtent = target
+	} else if (!binding.openExtent && current > 0) {
+		binding.openExtent = current
+	}
+	const progress =
+		state.source === 'native-frames'
+			? Math.min(1, Math.max(0, binding.openExtent ? current / binding.openExtent : 0))
+			: state.inset > 0
+				? 1
+				: 0
+	const extra =
+		(options.closedOffset ?? 0) +
+		((options.openOffset ?? 0) - (options.closedOffset ?? 0)) * progress
+	const overlap = keyboardRuntime.overlap(host, state, binding.lease.offset)
+	const budget = Math.max(
+		0,
+		Math.max(state.inset, current, overlap) - Math.max(0, options.consumedBottom ?? 0),
+	)
+	binding.lease.set(-Math.min(overlap, budget) - extra)
+	if (current === 0 && target === 0) {
+		binding.openExtent = 0
+	}
+}
+
+/** Software-keyboard observation and movement; separate from hardware useKeyboard.
+ * @example
+ * ```ts
+ * import { KeyboardController } from '@octane-xplat/keyboard'
+ * function observe(host: object) {
+ *   return KeyboardController.subscribe(host, state => console.log(state.phase))
+ * }
+ * ```
+ */
+export const KeyboardController: SoftwareKeyboardController = {
+	activate: () => keyboardRuntime.activate(),
+	getSnapshot: (host) => snapshot(keyboardRuntime.getSnapshot(host)),
+	onMove: observe,
+	subscribe(host, listener) {
+		let previous: KeyboardSnapshot | undefined
+		return observe(host, (state) => {
+			const rect = state.targetFrame,
+				before = previous?.targetFrame
+			const changed =
+				!previous ||
+				state.source !== previous.source ||
+				state.inset !== previous.inset ||
+				rect?.x !== before?.x ||
+				rect?.y !== before?.y ||
+				rect?.width !== before?.width ||
+				rect?.height !== before?.height ||
+				state.windowRect?.width !== previous.windowRect?.width ||
+				state.windowRect?.height !== previous.windowRect?.height ||
+				state.capabilities.nativeFrames !== previous.capabilities.nativeFrames ||
+				state.capabilities.interactive !== previous.capabilities.interactive ||
+				state.capabilities.floating !== previous.capabilities.floating ||
+				(state.phase !== 'move' &&
+					(state.phase !== previous.phase || state.transitionId !== previous.transitionId))
+			previous = state
+			if (changed) {
+				listener(state)
+			}
+		})
+	},
+}
+
+/** @internal Bind only framework-owned native movement hosts. */
+export function bindKeyboardHost(
+	host: object,
+	options: KeyboardBindingOptions | (() => KeyboardBindingOptions) = {},
+): KeyboardHostBinding {
+	const read = typeof options === 'function' ? options : () => options
+	const initial = read()
+	const inert = () => Object.assign(() => {}, { update() {} })
+	if (initial.enabled === false) {
+		return inert()
+	}
+	validateBindingOptions(initial)
+	let binding = bindings.get(host)
+	const owned = { read }
+	if (!binding) {
+		const property = keyboardRuntime.property(host)
+		if (!property) {
+			return inert()
+		}
+
+		binding = {
+			lease: leaseKeyboardProperty(property.read, property.write),
+			viewport: observeKeyboardViewport(host),
+			owners: [owned],
+			openExtent: 0,
+			off: () => {},
+		}
+
+		bindings.set(host, binding)
+		const entry = binding
+		try {
+			entry.off = observeState(host, (state) => {
+				entry.state = state
+				apply(host, entry)
+			})
+		} catch (error) {
+			bindings.delete(host)
+			entry.lease.release()
+			entry.viewport.release()
+			throw error
+		}
+	} else {
+		binding.owners.push(owned)
+		apply(host, binding)
+	}
+	const entry = binding
+	let active = true
+	const release = () => {
+		if (!active) {
+			return
+		}
+		active = false
+		entry.owners.splice(entry.owners.indexOf(owned), 1)
+		if (entry.owners.length) {
+			apply(host, entry)
+			return
+		}
+		bindings.delete(host)
+		try {
+			entry.off()
+		} finally {
+			try {
+				entry.lease.release()
+			} finally {
+				entry.viewport.release()
+			}
+		}
+	}
+	return Object.assign(release, {
+		update() {
+			if (active) {
+				apply(host, entry)
+			}
+		},
+	})
+}

package/src/focus-clock.macos.ts

@@ -0,0 +1,13 @@
+import { NSTimer, NSRunLoop } from '@octane-xplat/platform/macos'
+
+/** @internal Owned metadata polling, including during AppKit tracking modes. */
+export function startFocusClock(read: () => void): () => void {
+	const timer = NSTimer.timerWithTimeIntervalRepeatsBlock(1 / 60, true, read)
+	try {
+		NSRunLoop.mainRunLoop.addTimerForMode(timer, 'kCFRunLoopCommonModes')
+	} catch (error) {
+		timer.invalidate()
+		throw error
+	}
+	return () => timer.invalidate()
+}

package/src/focus-geometry.ts

@@ -0,0 +1,34 @@
+import { isKeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import type { KeyboardRect } from '@octane-xplat/platform/keyboard-geometry'
+import { unknownFocusedInputState } from '@octane-xplat/platform/focused-input-state'
+import type { FocusedInputState } from '@octane-xplat/platform/focused-input-state'
+
+/** @internal Convert a plain CGRect/NSRect value, never an SDK object in shared policy. */
+export function focusRect(value: any): KeyboardRect | null {
+	const rect = value && {
+		x: value.origin?.x,
+		y: value.origin?.y,
+		width: value.size?.width,
+		height: value.size?.height,
+	}
+	return isKeyboardRect(rect) ? rect : null
+}
+
+/** @internal Selection metadata only; invalid native ranges are unavailable. */
+export function focusSelection(start: number, end: number): FocusedInputState['selection'] {
+	return Number.isSafeInteger(start) && Number.isSafeInteger(end) && start >= 0 && end >= 0
+		? { start, end }
+		: null
+}
+
+/** @internal A supported window without an editing input. */
+export function emptyFocus(
+	windowRect: KeyboardRect | null,
+	caretBounds: FocusedInputState['capabilities']['caretBounds'],
+): FocusedInputState {
+	return {
+		...unknownFocusedInputState(),
+		windowRect,
+		capabilities: { inputBounds: true, caretBounds, selection: true },
+	}
+}

package/src/focus-publish.ts

@@ -0,0 +1,14 @@
+import { sameFocusedInput } from '@octane-xplat/platform/focused-input-state'
+import type { FocusedInputState } from '@octane-xplat/platform/focused-input-state'
+
+/** @internal Stable snapshots across idle polling frames. */
+export function focusPublisher(publish: (state: FocusedInputState) => void) {
+	let previous: FocusedInputState | undefined
+	return (next: FocusedInputState) => {
+		if (previous && sameFocusedInput(previous, next)) {
+			return
+		}
+		previous = { ...next, timestampMs: Date.now() }
+		publish(previous)
+	}
+}

package/src/focus-runtime-types.ts

@@ -0,0 +1,9 @@
+import type { FocusedInputState } from '@octane-xplat/platform/focused-input-state'
+
+/** @internal Platform-owned window resolution and observation. */
+export interface FocusRuntime {
+	activate(): () => void
+	getSnapshot(host: object): FocusedInputState
+	subscribe(host: object, listener: (state: FocusedInputState) => void): () => void
+	recheck(host: object): void
+}

package/src/focus-runtime.macos.ts

@@ -0,0 +1,62 @@
+import {
+	focusedInputWindows,
+	unknownFocusedInputState,
+} from '@octane-xplat/platform/focused-input-state'
+
+import { observeFocusedInput, focusRechecks } from './focus-source'
+import { startFocusClock } from './focus-clock'
+import type { FocusRuntime } from './focus-runtime-types'
+
+const inactive = unknownFocusedInputState()
+const owner = (host: any): object | undefined => (host?.native ?? host)?.window ?? undefined
+
+export const focusRuntime: FocusRuntime = {
+	activate: () => focusedInputWindows.install(observeFocusedInput),
+	getSnapshot(host) {
+		const key = owner(host)
+		return key ? focusedInputWindows.getSnapshot(key) : inactive
+	},
+	recheck(host) {
+		const key = owner(host)
+		if (key) {
+			focusRechecks.get(key)?.()
+		}
+	},
+	subscribe(host, listener) {
+		let active = true
+		let key: object | undefined,
+			initialized = false
+		let off = () => {}
+		const rebind = () => {
+			if (!active) {
+				return
+			}
+			const next = owner(host)
+			if (initialized && key === next) {
+				return
+			}
+			initialized = true
+			key = next
+			off()
+			off = () => {}
+			if (next) {
+				off = focusedInputWindows.subscribe(next, listener)
+			} else {
+				listener(inactive)
+			}
+		}
+		rebind()
+		let stop: () => void
+		try {
+			stop = startFocusClock(rebind)
+		} catch (error) {
+			off()
+			throw error
+		}
+		return () => {
+			active = false
+			stop()
+			off()
+		}
+	},
+}

package/src/focus-runtime.mobile.ts

@@ -0,0 +1,57 @@
+import {
+	focusedInputWindows,
+	unknownFocusedInputState,
+} from '@octane-xplat/platform/focused-input-state'
+
+import {
+	keyboardWindowForHost,
+	subscribeKeyboardState,
+} from '@octane-xplat/ui/nativescript/keyboard'
+
+import { observeFocusedInput, focusRechecks } from './focus-source'
+import type { FocusRuntime } from './focus-runtime-types'
+
+const inactive = unknownFocusedInputState()
+const unwrap = (host: any) => host?.native ?? host
+
+export const focusRuntime: FocusRuntime = {
+	activate: () => focusedInputWindows.install(observeFocusedInput),
+	getSnapshot(host) {
+		const key = keyboardWindowForHost(unwrap(host))
+		return key ? focusedInputWindows.getSnapshot(key) : inactive
+	},
+	recheck(host) {
+		const key = keyboardWindowForHost(unwrap(host))
+		if (key) {
+			focusRechecks.get(key)?.()
+		}
+	},
+	subscribe(host, listener) {
+		let key: object | undefined
+		let offFocus = () => {}
+		let initialized = false
+		const offWindow = subscribeKeyboardState(
+			(_state, next) => {
+				if (initialized && key === next) {
+					return
+				}
+				initialized = true
+				offFocus()
+				key = next
+				offFocus = next ? focusedInputWindows.subscribe(next, listener) : () => {}
+				if (!next) {
+					listener(inactive)
+				}
+			},
+			unwrap(host),
+			false,
+		)
+		return () => {
+			try {
+				offWindow()
+			} finally {
+				offFocus()
+			}
+		}
+	},
+}

package/src/focus-runtime.ts

@@ -0,0 +1,14 @@
+import { unknownFocusedInputState } from '@octane-xplat/platform/focused-input-state'
+import type { FocusRuntime } from './focus-runtime-types'
+
+const inactive = unknownFocusedInputState()
+/** Neutral fallback for hosts without qualified input geometry adapters. */
+export const focusRuntime: FocusRuntime = {
+	activate: () => () => {},
+	getSnapshot: () => inactive,
+	subscribe(_host, listener) {
+		listener(inactive)
+		return () => {}
+	},
+	recheck() {},
+}

package/src/focus-runtime.web.ts

@@ -0,0 +1,139 @@
+import {
+	focusedInputWindows,
+	unknownFocusedInputState,
+} from '@octane-xplat/platform/focused-input-state'
+
+import { observeFocusedInput, focusRechecks } from './focus-source'
+import type { FocusRuntime } from './focus-runtime-types'
+
+const inactive = unknownFocusedInputState()
+const lifecycles = new WeakMap<Document, { readers: number; paused: boolean }>()
+const view = (host: any): HTMLElement | undefined => host?.native ?? host
+// A WindowProxy survives navigation; the document is its observation generation.
+const owner = (host: object): Document | undefined => {
+	const element = view(host),
+		document = element?.ownerDocument,
+		window = document?.defaultView
+	try {
+		return element?.isConnected &&
+			window &&
+			!window.closed &&
+			window.document === document &&
+			!lifecycles.get(document!)?.paused
+			? document
+			: undefined
+	} catch {
+		return undefined
+	}
+}
+
+const watchWindow = (document: Document, rebind: () => void) => {
+	const window = document.defaultView!
+	let state = lifecycles.get(document)
+	if (!state) {
+		state = { readers: 0, paused: false }
+		lifecycles.set(document, state)
+	}
+	const owned = state
+	owned.readers++
+	let active = true
+	const hide = () => {
+		if (active) {
+			owned.paused = true
+			rebind()
+		}
+	}
+	const show = () => {
+		if (active) {
+			owned.paused = false
+			rebind()
+		}
+	}
+	window.addEventListener('pagehide', hide)
+	window.addEventListener('pageshow', show)
+	return () => {
+		if (!active) {
+			return
+		}
+		active = false
+		window.removeEventListener('pagehide', hide)
+		window.removeEventListener('pageshow', show)
+		if (!--owned.readers) {
+			lifecycles.delete(document)
+		}
+	}
+}
+
+export const focusRuntime: FocusRuntime = {
+	activate: () => focusedInputWindows.install(observeFocusedInput),
+	getSnapshot(host) {
+		const key = owner(host)
+		return key ? focusedInputWindows.getSnapshot(key) : inactive
+	},
+	recheck(host) {
+		const key = owner(host)
+		if (key) {
+			focusRechecks.get(key)?.()
+		}
+	},
+	subscribe(host, listener) {
+		let active = true
+		let key: Document | undefined,
+			document: Document | undefined,
+			initialized = false
+		let observer: MutationObserver | undefined
+		let offWindow = () => {}
+		let off = () => {}
+		const rebind = () => {
+			if (!active) {
+				return
+			}
+			const nextDocument = view(host)?.ownerDocument
+			if (nextDocument !== document) {
+				observer?.disconnect()
+				offWindow()
+				offWindow = () => {}
+				document = nextDocument
+				const Observer = document?.defaultView?.MutationObserver
+				observer = Observer ? new Observer(rebind) : undefined
+				if (document) {
+					observer?.observe(document, { childList: true, subtree: true })
+				}
+
+				if (document?.defaultView) {
+					offWindow = watchWindow(document, rebind)
+				}
+			}
+			const next = owner(host)
+			if (initialized && key === next) {
+				return
+			}
+			initialized = true
+			off()
+			off = () => {}
+			key = next
+			if (next) {
+				off = focusedInputWindows.subscribe(next, listener)
+			} else {
+				listener(inactive)
+			}
+		}
+		try {
+			rebind()
+		} catch (error) {
+			observer?.disconnect()
+			offWindow()
+			off()
+			throw error
+		}
+		return () => {
+			if (!active) {
+				return
+			}
+			active = false
+			observer?.disconnect()
+			offWindow()
+			off()
+		}
+	},
+}