@octane-xplat/keyboard 0.0.1 → 0.17.0

package/README.md

@@ -1,3 +1,155 @@
 # @octane-xplat/keyboard
 
-Bootstrap stub for trusted publishing. This version has no supported API. Real releases ship through https://github.com/octane-xplat/octane-xplat.
+Keep a form above the phone keyboard while it moves. Add the optional keyboard
+package around the existing UI wrapper:
+
+```sh
+pnpm add @octane-xplat/keyboard
+```
+
+```tsx
+import { KeyboardProvider } from '@octane-xplat/keyboard'
+import { Field, KeyboardAvoiding, TextInput } from '@octane-xplat/ui'
+
+export function MessageForm() {
+	return <KeyboardProvider>
+		<KeyboardAvoiding keyboardVerticalOffset={8}>
+			<Field label="Message">
+				<TextInput placeholder="Write a message" />
+			</Field>
+		</KeyboardAvoiding>
+	</KeyboardProvider>
+}
+```
+
+On supported native hosts, the padding follows measured keyboard frames without
+rendering the component on each animation frame. Native tracking uses the public
+UIKit keyboard guide on iOS 17+ and AndroidX animation callbacks on Android 11+.
+Runtime qualification currently covers iOS 27 and Android API 35 with NativeScript
+9.1.3. Older or incompatible native contexts retain destination-only avoidance;
+web and desktop retain neutral software-keyboard behavior.
+
+```tsx
+// Pausing tracking retains the form's children and the UI wrapper's fallback.
+<KeyboardProvider enabled={false}>
+	<KeyboardAvoiding>
+		<TextInput placeholder="Write a message" />
+	</KeyboardAvoiding>
+</KeyboardProvider>
+```
+
+On iOS, a fresh observer needs one native keyboard completion before it can
+advertise measured movement. Until then, avoidance uses the destination, the
+current frame is unavailable, and the native-frame capability is false. This
+also applies when starting observation over an already-moving keyboard. Readers
+that share a running window source reuse its available measurements.
+
+```ts
+import { KeyboardController } from '@octane-xplat/keyboard'
+
+export function canFollowMeasuredFrames(host: object) {
+	return KeyboardController.getSnapshot(host).capabilities.nativeFrames
+}
+```
+
+For native integrations, `KeyboardController` separates lifecycle subscriptions
+from measured movement. Supply a mounted native host from your platform leaf,
+and release subscriptions when that host detaches. These operations activate
+tracking for their own lifetime; a Provider is optional for these readers.
+
+```ts
+import { KeyboardController } from '@octane-xplat/keyboard'
+
+export function observeHost(host: object) {
+	const stop = KeyboardController.subscribe(host, state => {
+		console.log(state.phase, state.capabilities.nativeFrames)
+	})
+	const stopMoving = KeyboardController.onMove(host, state => {
+		// Use measured geometry for native work; avoid rendering on every frame.
+		const top = state.currentFrame?.y
+		if (top !== undefined) updateNativeMeasurement(top)
+	})
+	return () => { stopMoving(); stop() }
+}
+
+function updateNativeMeasurement(_top: number) {}
+```
+
+Frames use device-independent coordinates in the owning window. The destination
+can change before the measured current frame reaches it. Read capability flags
+before depending on native tracking; floating-keyboard tracking and Android interactive dismissal are not yet
+qualified. The supported iOS guide path tracks interactive dismissal when its
+scroll host enables that gesture. No text contents are collected.
+
+```ts
+import { KeyboardController } from '@octane-xplat/keyboard'
+
+export function readHost(host: object) {
+	const state = KeyboardController.getSnapshot(host)
+	return {
+		current: state.currentFrame,
+		destination: state.targetFrame,
+		canTrackMovement: state.capabilities.nativeFrames,
+	}
+}
+```
+
+The [maintained example](./examples/KeyboardMotionDemo.tsrx) uses the shared UI API.
+Native layout and presentation limits are recorded in the framework's
+[software keyboard notes](../../.agents/docs/keyboard.md).
+
+`FocusedInputController` observes input identity, selection, input/caret bounds,
+and scroll ancestors independently of keyboard motion. Coordinates use the
+owning window. Caret precision is explicit; browser text fields expose box
+bounds without a caret rectangle. Release subscriptions when the host is removed.
+
+```ts
+import { FocusedInputController } from '@octane-xplat/keyboard'
+
+export function observeEditing(host: object) {
+	return FocusedInputController.subscribe(host, state => {
+		console.log(state.inputRect, state.capabilities.caretBounds)
+	})
+}
+```
+
+See the [focused-input guide](../../docs/app/software-keyboard.md#read-focused-input-geometry)
+for capability limits, selection units, and immediate rechecks.
+
+Use `KeyboardAwareScrollView` for long forms. It exposes the focused field or
+caret with minimal scrolling, pauses after manual scrolling by default, and
+provides a binding ref for explicit visibility rechecks.
+
+```tsx
+import { KeyboardAwareScrollView } from '@octane-xplat/keyboard'
+import { Field, TextInput } from '@octane-xplat/ui'
+
+export function LongForm() {
+	return <KeyboardAwareScrollView clearance={12} extraScrollSpace={40}>
+		<Field label="Message"><TextInput placeholder="Write a message" /></Field>
+	</KeyboardAwareScrollView>
+}
+```
+
+The [form guide](../../docs/app/software-keyboard.md#keep-the-editing-field-visible)
+explains scroll policies and the [maintained form example](./examples/KeyboardFormDemo.tsrx)
+shows an explicit recheck.
+
+`KeyboardStickyView` translates a bottom control independently of surrounding
+layout on supported native hosts. Existing transforms compose with its owned
+vertical channel; disabling releases that channel. Browser and desktop keep a
+neutral View.
+
+```tsx
+import { KeyboardStickyView } from '@octane-xplat/keyboard'
+import { TextInput } from '@octane-xplat/ui'
+
+export function Composer() {
+	return <KeyboardStickyView openOffset={8}>
+		<TextInput placeholder="Write a message" />
+	</KeyboardStickyView>
+}
+```
+
+Place it at the screen's bottom. See the [sticky guide](../../docs/app/software-keyboard.md#keep-a-composer-beside-the-keyboard)
+and [maintained composer](./examples/KeyboardComposerDemo.tsrx).

package/UPSTREAM.md

@@ -0,0 +1,12 @@
+# Keyboard implementation references
+
+The separation of measured keyboard frames, native movement bindings, focused
+input geometry, and scroll policy is informed by
+[react-native-keyboard-controller 1.22.0](https://github.com/kirillzyusko/react-native-keyboard-controller/tree/b80086f1207e36d634f93afabb65eb886fe1a2fe)
+(MIT; copyright 2021 Kiryl Ziusko). This package does not copy its React
+Native/Reanimated implementation or private keyboard-view discovery.
+
+Native adapters use the public UIKit keyboard layout guide and CADisplayLink,
+and AndroidX WindowInsetsAnimationCompat on an owned helper view. NativeScript
+Page inset distribution is leased through its public androidOverflowInset event.
+The package owns these helpers and releases them with its final window reader.

package/package.json

@@ -1,20 +1,88 @@
 {
   "name": "@octane-xplat/keyboard",
-  "version": "0.0.1",
-  "description": "Bootstrap stub for trusted publishing; no supported API.",
-  "main": "index.js",
+  "version": "0.17.0",
+  "description": "Window-scoped software keyboard tracking and native movement for Octane Xplat",
+  "keywords": [
+    "android",
+    "cross-platform",
+    "ios",
+    "keyboard",
+    "nativescript",
+    "octane",
+    "xplat"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/keyboard",
   "repository": {
     "type": "git",
     "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/keyboard"
   },
+  "type": "module",
+  "files": [
+    "src",
+    "types",
+    "UPSTREAM.md",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "index.js",
-    "README.md",
-    "LICENSE"
-  ]
-}
+  "dependencies": {
+    "@octane-xplat/platform": "0.17.0",
+    "@octane-xplat/ui": "0.17.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@octanejs/vite-plugin": "0.1.61",
+    "@octane-xplat/jsx": "0.17.0",
+    "octane": "0.14.0",
+    "tsrx-typegen": "0.4.0",
+    "typescript": "5.9.3",
+    "vite": "8.3.0",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.11.0 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typegen": "tsc -p tsconfig.types.json",
+    "typecheck": "node ../../scripts/typecheck.ts",
+    "test": "vitest run",
+    "test:motion:ios": "node ../../scripts/probe.ts run tests/fixtures/motion.ios.tsrx --target ios",
+    "test:motion:android": "node ../../scripts/probe.ts run tests/fixtures/motion.android.tsrx --target android",
+    "test:interactive:ios": "node ../../scripts/probe.ts run tests/fixtures/interactive.ios.tsrx --target ios",
+    "pack:check": "tsrx-typegen --pack-check",
+    "test:focus:web": "node ../../scripts/probe.ts run tests/fixtures/focus.web.tsrx --target web",
+    "test:focus:ios": "node ../../scripts/probe.ts run tests/fixtures/focus.ios.tsrx --target ios",
+    "test:focus:android": "node ../../scripts/probe.ts run tests/fixtures/focus.android.tsrx --target android",
+    "test:focus:macos": "node ../../scripts/probe.ts run tests/fixtures/focus.macos.tsrx --target macos",
+    "test:scroll:web": "node ../../scripts/probe.ts run tests/fixtures/scroll.web.tsrx --target web",
+    "test:scroll:ios": "node ../../scripts/probe.ts run tests/fixtures/scroll.ios.tsrx --target ios",
+    "test:scroll:android": "node ../../scripts/probe.ts run tests/fixtures/scroll.android.tsrx --target android",
+    "test:scroll:macos": "node ../../scripts/probe.ts run tests/fixtures/scroll.macos.tsrx --target macos",
+    "test:sticky:web": "node ../../scripts/probe.ts run tests/fixtures/sticky.web.tsrx --target web",
+    "test:sticky:ios": "node ../../scripts/probe.ts run tests/fixtures/sticky.ios.tsrx --target ios",
+    "test:sticky:android": "node ../../scripts/probe.ts run tests/fixtures/sticky.android.tsrx --target android",
+    "test:packed": "node tests/packed-consumer.mjs",
+    "test:os-input": "node tests/os-input.mjs"
+  }
+}

package/src/KeyboardAwareScrollView.mobile.tsrx

@@ -0,0 +1,54 @@
+/** @jsxImportSource @octane-xplat/jsx */
+import { useCallback, useEffect, useRef, useState } from 'octane'
+import { KeyboardAvoiding } from '@octane-xplat/ui'
+import { KeyboardScrollController } from './scroll-controller'
+import type { KeyboardAwareScrollViewProps } from './props'
+import type { KeyboardScrollBinding } from './scroll-types'
+
+export function KeyboardAwareScrollView(props: KeyboardAwareScrollViewProps) @{
+	const [host, setHost] = useState<any>(null)
+	const attach = useCallback((next: any) => setHost(next), [])
+	const binding = useRef<KeyboardScrollBinding | null>(null)
+	const latest = useRef(props)
+	latest.current = props
+	const enabled = props.enabled ?? true
+	if (!Number.isFinite(props.extraScrollSpace ?? 0) || (props.extraScrollSpace ?? 0) < 0) {
+		throw new RangeError('Extra keyboard scroll space must be finite and nonnegative')
+	}
+
+	useEffect(() => {
+		if (!host || !enabled) {
+			return
+		}
+
+		const own = KeyboardScrollController.bind(host, latest.current)
+		binding.current = own
+		return () => {
+			own.release()
+			binding.current = null
+		}
+	}, [host, enabled])
+
+	useEffect(() => {
+		props.ref?.(binding.current)
+		return () => props.ref?.(null)
+	}, [host, enabled, props.ref])
+
+	useEffect(() => {
+		binding.current?.update(props)
+	}, [props.clearance, props.manualScroll, props.keyboardClose])
+
+	<KeyboardAvoiding
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		ref={attach}
+		enabled={enabled}
+		keyboardVerticalOffset={(props.keyboardVerticalOffset ?? 0) + (props.extraScrollSpace ?? 0)}
+		ios={props.ios}
+		android={props.android}
+		web={props.web}
+	>
+		{props.children}
+	</KeyboardAvoiding>
+}

package/src/KeyboardAwareScrollView.tsrx

@@ -0,0 +1,53 @@
+import { useCallback, useEffect, useRef, useState } from 'octane'
+import { ScrollableArea } from '@octane-xplat/ui'
+import { KeyboardScrollController } from './scroll-controller'
+import type { KeyboardAwareScrollViewProps } from './props'
+import type { KeyboardScrollBinding } from './scroll-types'
+
+/** Desktop/browser focus scrolling; software-keyboard movement remains neutral. */
+export function KeyboardAwareScrollView(props: KeyboardAwareScrollViewProps) @{
+	const [host, setHost] = useState<any>(null)
+	const attach = useCallback((next: any) => setHost(next?.native ?? null), [])
+	const binding = useRef<KeyboardScrollBinding | null>(null)
+	const latest = useRef(props)
+	latest.current = props
+	const enabled = props.enabled ?? true
+	if (!Number.isFinite(props.extraScrollSpace ?? 0) || (props.extraScrollSpace ?? 0) < 0) {
+		throw new RangeError('Extra keyboard scroll space must be finite and nonnegative')
+	}
+
+	useEffect(() => {
+		if (!host || !enabled) {
+			return
+		}
+
+		const own = KeyboardScrollController.bind(host, latest.current)
+		binding.current = own
+		return () => {
+			own.release()
+			binding.current = null
+		}
+	}, [host, enabled])
+
+	useEffect(() => {
+		props.ref?.(binding.current)
+		return () => props.ref?.(null)
+	}, [host, enabled, props.ref])
+
+	useEffect(() => {
+		binding.current?.update(props)
+	}, [props.clearance, props.manualScroll, props.keyboardClose])
+
+	<ScrollableArea
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		ref={attach}
+		axis="block"
+		ios={props.ios}
+		android={props.android}
+		web={props.web}
+	>
+		{props.children}
+	</ScrollableArea>
+}

package/src/KeyboardStickyView.mobile.tsrx

@@ -0,0 +1,66 @@
+/** @jsxImportSource @octane-xplat/jsx */
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'octane'
+import { View } from '@octane-xplat/ui'
+import {
+	ConsumedInsetsContext,
+	KeyboardAvoidanceContext,
+	keyboardWindowForHost,
+} from '@octane-xplat/ui/nativescript/keyboard'
+
+import { bindKeyboardHost } from './controller'
+import type { KeyboardHostBinding } from './binding-types'
+import type { KeyboardStickyViewProps } from './props'
+
+export function KeyboardStickyView(props: KeyboardStickyViewProps) @{
+	const [host, setHost] = useState<any>(null)
+	const attach = useCallback((next: any) => setHost(next), [])
+	const forwarded = useMemo(() => [attach, props.ref], [attach, props.ref])
+	const safe = useContext(ConsumedInsetsContext)
+	const ancestor = useContext(KeyboardAvoidanceContext)
+	const latest = useRef({ props, safe, ancestor })
+	latest.current = { props, safe, ancestor }
+	const binding = useRef<KeyboardHostBinding | null>(null)
+	const enabled = props.enabled ?? true
+	useEffect(() => {
+		if (!host || !enabled) {
+			return
+		}
+
+		const own = bindKeyboardHost(host, () => {
+			const current = latest.current
+			return {
+				openOffset: current.props.openOffset,
+				closedOffset: current.props.closedOffset,
+				consumedBottom:
+					Math.max(0, current.safe.bottom) +
+					(current.ancestor.window === keyboardWindowForHost(host) ? current.ancestor.bottom : 0),
+			}
+		})
+
+		binding.current = own
+		return () => {
+			binding.current = null
+			own()
+		}
+	}, [host, enabled])
+
+	useEffect(() => {
+		binding.current?.update()
+	}, [
+		props.openOffset,
+		props.closedOffset,
+		props.style,
+		props.className,
+		props.ios,
+		props.android,
+		safe.bottom,
+		ancestor.window,
+		ancestor.bottom,
+	])
+
+	const { enabled: _enabled, openOffset: _openOffset, closedOffset: _closedOffset, ...view } = props
+
+	<View {...view} ref={forwarded}>
+		{props.children}
+	</View>
+}

package/src/KeyboardStickyView.tsrx

@@ -0,0 +1,9 @@
+import { View } from '@octane-xplat/ui'
+import type { KeyboardStickyViewProps } from './props'
+
+/** Neutral layout on hosts without measured software-keyboard movement. */
+export function KeyboardStickyView(props: KeyboardStickyViewProps) @{
+	const { enabled: _enabled, openOffset: _openOffset, closedOffset: _closedOffset, ...view } = props
+
+	<View {...view}>{props.children}</View>
+}

package/src/Provider.tsrx

@@ -0,0 +1,11 @@
+import { useEffect } from 'octane'
+import { KeyboardController } from './controller'
+import type { KeyboardProviderProps } from './props'
+
+/** Activate shared tracking without adding a layout host. */
+export function KeyboardProvider(props: KeyboardProviderProps) @{
+	const enabled = props.enabled ?? true
+	useEffect(() => (enabled ? KeyboardController.activate() : undefined), [enabled])
+
+	<>{props.children}</>
+}

package/src/binding-types.ts

@@ -0,0 +1,16 @@
+/** @internal Native host policy used by framework-owned movement bindings. */
+/** Low-level native translation policy. Offsets are device-independent pixels. */
+export interface KeyboardBindingOptions {
+	/** Do not observe or move the host while disabled. @default true */
+	enabled?: boolean
+	/** Additional upward clearance while the keyboard is open. @default 0 */
+	openOffset?: number
+	/** Upward displacement while closed. @default 0 */
+	closedOffset?: number
+	/** Space supplied by a safe-area/avoidance ancestor in the same window.
+	 * Actual native resizing is measured separately. @default 0 */
+	consumedBottom?: number
+}
+
+/** @internal Options can change without replacing the shared window source. */
+export type KeyboardHostBinding = (() => void) & { update(): void }