@octane-xplat/keyboard 0.0.1 → 0.17.1

package/src/viewport.android.ts

@@ -0,0 +1,238 @@
+import { leaseKeyboardProperty } from '@octane-xplat/platform/keyboard-property'
+import type { KeyboardPropertyLease } from '@octane-xplat/platform/keyboard-property'
+import type { KeyboardViewportLease } from './viewport-types'
+
+type Entry = {
+	owner: any
+	native: any
+	previous: string
+	count: number
+	padding: KeyboardPropertyLease[]
+	listener: (event: any) => void
+}
+
+const entries = new WeakMap<object, Entry>()
+const ownedPolicy = 'dont-apply'
+const noLease = (supported: boolean): KeyboardViewportLease => ({
+	supported,
+	update() {},
+	release() {},
+})
+
+const nativeFor = (view: any) => view?.nativeViewProtected ?? view?.android
+const supportsPadding = (native: any) =>
+	native && typeof native.getEdgeInsets === 'function' && typeof native.getImeInsets === 'function'
+
+const paddingOf = (native: any): number[] => {
+	const edges = native.getEdgeInsets(),
+		ime = native.getImeInsets()
+	// Own base padding, not the automatically applied strip. This remains valid
+	// if another owner changes the overflow policy while the lease is active.
+	return [
+		native.getPaddingLeft() - edges.left,
+		native.getPaddingTop() - edges.top,
+		native.getPaddingRight() - edges.right,
+		native.getPaddingBottom() - Math.max(edges.bottom, ime.bottom),
+	]
+}
+
+const paddingLeases = (native: any) =>
+	[0, 1, 2, 3].map((index) =>
+		leaseKeyboardProperty(
+			() => paddingOf(native)[index],
+			(value) => {
+				const values = paddingOf(native)
+				values[index] = value
+				native.setPadding(...values)
+			},
+		),
+	)
+
+const applyBars = (entry: Entry, inset: any) => {
+	const cutout = entry.previous.includes('cutout')
+	const values = [inset.left, inset.top, inset.right, inset.bottom]
+	const cuts = [
+		inset.cutoutLeft ?? 0,
+		inset.cutoutTop ?? 0,
+		inset.cutoutRight ?? 0,
+		inset.cutoutBottom ?? 0,
+	]
+	entry.padding.forEach((lease, index) =>
+		lease.set(Math.max(0, values[index] ?? 0, cutout ? cuts[index] : 0)),
+	)
+}
+
+const requestInsets = (native: any) =>
+	(globalThis as any).androidx?.core?.view?.ViewCompat?.requestApplyInsets(native)
+
+const seedBars = (entry: Entry) => {
+	const core = (globalThis as any).androidx?.core?.view
+	const insets = core?.ViewCompat?.getRootWindowInsets(entry.native)
+	const type = core?.WindowInsetsCompat?.Type
+	if (!insets || !type) {
+		return
+	}
+	const bars = insets.getInsets(type.systemBars())
+	const cutout = type.displayCutout ? insets.getInsets(type.displayCutout()) : undefined
+	applyBars(entry, {
+		left: bars.left,
+		top: bars.top,
+		right: bars.right,
+		bottom: bars.bottom,
+		cutoutLeft: cutout?.left,
+		cutoutTop: cutout?.top,
+		cutoutRight: cutout?.right,
+		cutoutBottom: cutout?.bottom,
+	})
+}
+
+const update = (entry: Entry, request = true) => {
+	if (entry.owner.androidOverflowEdge !== ownedPolicy) {
+		return
+	}
+	const native = nativeFor(entry.owner)
+	if (!supportsPadding(native) || entry.native === native) {
+		return
+	}
+	// A detached native view no longer owns the replacement's properties.
+	entry.padding.forEach((lease) => lease.release())
+	entry.native = native
+	entry.padding = paddingLeases(native)
+	if (request) {
+		seedBars(entry)
+		requestInsets(native)
+	}
+}
+
+/** Lease NativeScript's public inset-distribution event. Its default Page
+ * pads by max(navigation, IME) independently of softInputMode. We retain bars
+ * and consume IME here so consumers can follow measured frames themselves.
+ * No listener on the Activity/decor is replaced. @internal */
+export function leaseKeyboardViewport(host: any): KeyboardViewportLease {
+	const chain: any[] = []
+	for (let view = host; view; view = view.parent) {
+		chain.push(view)
+	}
+	chain.reverse()
+	let owner: any
+	for (const view of chain) {
+		if (entries.has(view)) {
+			owner = view
+			break
+		}
+
+		const policy = view.androidOverflowEdge
+		if (policy === 'none' || policy === 'none,cutout') {
+			owner = view
+			break
+		}
+
+		if (policy && policy !== 'ignore') {
+			return noLease(false)
+		}
+	}
+	if (!owner) {
+		return noLease(!!host?.page)
+	}
+	let entry = entries.get(owner)
+	if (!entry) {
+		const native = nativeFor(owner)
+		if (
+			!supportsPadding(native) ||
+			typeof native.setPadding !== 'function' ||
+			owner.hasListeners?.('androidOverflowInset')
+		) {
+			return noLease(false)
+		}
+
+		const previous = owner.androidOverflowEdge
+		// Clear the old automatically applied strip before capturing base padding.
+		owner.androidOverflowEdge = 'ignore'
+		entry = {
+			owner,
+			native,
+			previous,
+			count: 0,
+			padding: paddingLeases(native),
+			listener: () => {},
+		}
+
+		const own = entry
+		own.listener = (event) => {
+			if (own.owner.androidOverflowEdge !== ownedPolicy || !event.inset) {
+				return
+			}
+			update(own, false)
+			if (own.native !== nativeFor(own.owner)) {
+				return
+			}
+			const inset = event.inset
+			applyBars(own, inset)
+			inset.leftConsumed = inset.topConsumed = inset.rightConsumed = inset.bottomConsumed = true
+			inset.imeBottom = 0
+			inset.imeBottomConsumed = true
+			if (own.previous.includes('cutout')) {
+				inset.cutoutLeftConsumed =
+					inset.cutoutTopConsumed =
+					inset.cutoutRightConsumed =
+					inset.cutoutBottomConsumed =
+						true
+			}
+		}
+
+		entries.set(owner, own)
+		try {
+			owner.on('androidOverflowInset', own.listener)
+			owner.androidOverflowEdge = ownedPolicy
+			seedBars(own)
+			requestInsets(native)
+		} catch (error) {
+			entries.delete(owner)
+			owner.off('androidOverflowInset', own.listener)
+			if (owner.androidOverflowEdge === ownedPolicy || owner.androidOverflowEdge === 'ignore') {
+				own.padding.forEach((lease) => lease.release())
+				owner.androidOverflowEdge = previous
+			}
+
+			throw error
+		}
+	}
+	const own = entry
+	own.count++
+	let active = true
+	return {
+		get supported() {
+			return (
+				active &&
+				own.owner.androidOverflowEdge === ownedPolicy &&
+				own.native === nativeFor(own.owner)
+			)
+		},
+		update() {
+			if (active) {
+				update(own)
+			}
+		},
+		release() {
+			if (!active) {
+				return
+			}
+			active = false
+			if (--own.count) {
+				return
+			}
+			entries.delete(own.owner)
+			own.owner.off('androidOverflowInset', own.listener)
+			if (own.native === nativeFor(own.owner)) {
+				own.padding.forEach((lease) => lease.release())
+			}
+			if (own.owner.androidOverflowEdge === ownedPolicy) {
+				own.owner.androidOverflowEdge = own.previous
+				const native = nativeFor(own.owner)
+				if (native) {
+					requestInsets(native)
+				}
+			}
+		},
+	}
+}

package/src/viewport.ios.ts

@@ -0,0 +1,6 @@
+import type { KeyboardViewportLease } from './viewport-types'
+
+/** @internal UIKit's owning-window keyboard guide needs no ancestor padding lease. */
+export function leaseKeyboardViewport(_host: object): KeyboardViewportLease {
+	return { supported: true, update() {}, release() {} }
+}

package/src/viewport.ts

@@ -0,0 +1,6 @@
+import type { KeyboardViewportLease } from './viewport-types'
+
+/** @internal Unsupported software-keyboard targets retain their native viewport. */
+export function leaseKeyboardViewport(_host: object): KeyboardViewportLease {
+	return { supported: false, update() {}, release() {} }
+}

package/types/focus-types.d.ts

@@ -0,0 +1,17 @@
+import type { FocusedInputState } from '@octane-xplat/platform/focused-input-state';
+/** Focused input geometry in device-independent window coordinates. Identity
+ * and scroll owners are opaque native/DOM handles. No text contents are read.
+ * Unsupported targets return null geometry and false capabilities. */
+export type FocusedInputSnapshot = FocusedInputState;
+/** A vertical scroll viewport containing the input, nearest owner first. */
+export type { FocusedInputScrollOwner } from '@octane-xplat/platform/focused-input-state';
+/** Separate focus/selection geometry from software-keyboard movement. */
+export interface FocusedInputService {
+    /** Cached read; does not start observation. */
+    getSnapshot(host: object): FocusedInputSnapshot;
+    /** Observe identity, selection and layout changes; release on host removal.
+     * Geometry callbacks can occur each frame during native layout movement. */
+    subscribe(host: object, listener: (snapshot: FocusedInputSnapshot) => void): () => void;
+    /** Refresh an actively observed host. No-op without a reader. */
+    recheck(host: object): void;
+}

package/types/index.d.ts

@@ -0,0 +1,20 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { KeyboardProviderProps } from './props.js'
+import type { SoftwareKeyboardController } from './types.js'
+import type { FocusedInputService } from './focus-types.js'
+
+export type * from './types.js'
+export type * from './props.js'
+export type * from './focus-types.js'
+
+/** Share native tracking across roots and existing UI keyboard consumers. */
+export declare const KeyboardProvider: UniversalComponent<KeyboardProviderProps>
+export declare const KeyboardController: SoftwareKeyboardController
+/** Focus/selection geometry without collecting text contents. */
+export declare const FocusedInputController: FocusedInputService
+
+export type * from './scroll-types.js'
+export declare const KeyboardScrollController: import('./scroll-types.js').KeyboardScrollService
+export declare const KeyboardAwareScrollView: UniversalComponent<import('./props.js').KeyboardAwareScrollViewProps>
+
+export declare const KeyboardStickyView: UniversalComponent<import('./props.js').KeyboardStickyViewProps>

package/types/props.d.ts

@@ -0,0 +1,35 @@
+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/types/scroll-types.d.ts

@@ -0,0 +1,22 @@
+/** 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/types/types.d.ts

@@ -0,0 +1,40 @@
+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/index.js

@@ -1 +0,0 @@
-throw new Error('This is the keyboard bootstrap stub. Install a supported release instead.');