@octane-xplat/ui 0.6.0 → 0.7.1

package/src/ios/UIModal.ios.tsrx

@@ -0,0 +1,68 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useRef } from 'octane';
+import type { ModalProps } from "../props";
+import { Frame, GridLayout } from '@nativescript/core';
+import { createNativeScriptRoot } from '@nativescript-community/octane';
+import type { UniversalComponent } from 'octane/universal';
+import { applyThemeClasses } from '../theme/theme-scheme';
+import { modalPresenter } from '../modal-presenter.mobile';
+
+// The modal's content renders inside a separate Octane root on a GridLayout
+// host — modals never share context with their presenter (decision #9).
+// GridLayout because the root host must be multi-child: ContentView assigns
+// each child to `.content`, so a fragment of siblings would keep only the
+// last; grid children all fill the cell (single-child layout unchanged).
+// Children arrive as an already-created element: element data evaluates in
+// whichever root renders it, so re-parenting through the second root is safe.
+function Panel(props: { children?: any }) @{
+	<>{props.children}</>
+}
+
+/** UIModal — declarative `open` drives the platform modal presentation
+ *  (`showModal`; fullscreen=false is an iOS form sheet). Renders nothing
+ *  inline; the content lives on the modal's own root above the whole tree.
+ *  The shared `ui` surface has no Modal — `Overlay`/`Sheet` are the
+ *  self-drawn in-window versions. */
+export function UIModal(props: ModalProps) @{
+	const shown = useRef<{ host: GridLayout; root: any; unbindTheme?: () => void } | null>(null);
+
+	useEffect(() => {
+		if (props.open && !shown.current) {
+			const presenter = modalPresenter(Frame.topmost());
+			if (!presenter) {
+				// Dropped, not deferred: the effect only re-runs when props
+				// change, so warn loudly instead of silently swallowing open.
+				console.warn('[Modal] open dropped — no live presenter (currentPage mid-navigation or no active frame).');
+				return;
+			}
+
+			const host = new GridLayout();
+			const unbindTheme = applyThemeClasses(host, 'vx-modal-host');
+			const root = createNativeScriptRoot(host);
+			shown.current = { host, root, unbindTheme };
+			if (props.component) {
+				root.render(props.component as UniversalComponent, props.params ?? {});
+			} else {
+				root.render(Panel as unknown as UniversalComponent, { children: props.children });
+			}
+
+			// Signature is showModal(viewToShow, options) — not an options bag.
+			const fullscreen = props.presentation
+				? props.presentation === 'fullscreen'
+				: props.fullscreen ?? true;
+
+			presenter.showModal(host, {
+				context: {},
+				closeCallback: (result?: unknown) => { shown.current?.unbindTheme?.(); shown.current = null; props.onClose?.(result); },
+				fullscreen,
+				animated: true,
+			});
+		} else if (!props.open && shown.current) {
+			const { host } = shown.current;
+			shown.current = null;
+			host.closeModal();
+		}
+	}, [props.open]);
+
+	<></>
+}

package/src/ios/UISlider.ios.tsrx

@@ -0,0 +1,20 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { PlatformWidgetProps, SliderProps } from '../props';
+import { cx } from '../cx';
+import { applyNativeProps } from '../platformProps';
+
+/** UISlider — the platform widget (UIKit UISlider via NativeScript `slider`).
+ *  The self-drawn shared `Slider` lives in the root export. */
+export function UISlider(props: PlatformWidgetProps<SliderProps>) @{
+	<slider
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		value={props.value}
+		minValue={props.minValue ?? 0}
+		maxValue={props.maxValue ?? 100}
+		isEnabled={props.disabled ? false : true}
+		onValueChange={(e: any) => props.onValueChange?.(e.value)}
+		ref={(el: any) => applyNativeProps(el, props)}
+	/>
+}

package/src/ios/UISwitch.ios.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { PlatformWidgetProps, SwitchProps } from "../props";
+import { cx } from "../cx";
+import { applyEscapeProps } from "../escape-props";
+
+/** UISwitch — the platform widget (UIKit UISwitch via NativeScript `switch`).
+ *  OS chrome is the point here; the self-drawn shared `Switch` lives in the
+ *  root export. */
+export function UISwitch(props: PlatformWidgetProps<SwitchProps>) @{
+	<switch
+		ref={(v: any) => applyEscapeProps(v, props)}
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		checked={props.checked}
+		onCheckedChange={(e: any) => props.onCheckedChange?.(e.value)}
+	/>
+}

package/src/ios/UITabBar.ios.tsrx

@@ -0,0 +1,172 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { memo } from 'octane';
+import { Frame, GridLayout, Page, TabView, TabViewItem } from '@nativescript/core';
+import { createNativeScriptRoot } from '@nativescript-community/octane';
+import type { UniversalComponent } from 'octane/universal';
+import { registerStack } from '../stacks';
+import { cx } from '../cx';
+import { getIcon } from '../icons';
+import type { PlatformTabSpec, PlatformTabsProps, PlatformWidgetProps } from '../props';
+import { applyEscapeProps } from '../escape-props';
+
+export type { PlatformTabSpec as TabSpec } from '../props';
+
+// TabViewItem content is a plain native view — the driver can't parent
+// reconciled children into <tabviewitem>, so each pane is a GridLayout
+// hosting its own universal root (same shape as List cells). GridLayout,
+// not ContentView: the host must be multi-child — a pane render producing
+// more than one root view would keep only the last under `.content`
+// assignment. Grid children all fill the cell, so single-child panes are
+// unaffected.
+type TabPaneProps = { render: () => any };
+function TabPane(props: TabPaneProps) @{
+	<>{props.render()}</>
+}
+
+const paneRoots = new WeakMap<GridLayout, any>();
+const tabsByView = new WeakMap<GridLayout, () => any>();
+const itemsCache = new WeakMap<readonly PlatformTabSpec[], TabViewItem[]>();
+const iconWarned = new Set<string>();
+
+// Registered glyph → UITabBarItem image. `src` passes to iconSource
+// verbatim (sys:// = SF Symbol, res://, font://, file path); `font` and
+// `text` glyphs draw through font://. svg/markup can't become a UIImage
+// synchronously — warn once, render title-only.
+function applyIcon(item: TabViewItem, name: string): void {
+	if (name.startsWith('sys://') || name.startsWith('res://')) {
+		item.iconSource = name;
+		return;
+	}
+	const glyph = getIcon(name);
+	if (!glyph) {
+		warnIconOnce(name, `tab icon '${name}' isn't registered — call registerIcons() at boot.`);
+		return;
+	}
+
+	if (glyph.src) {
+		item.iconSource = glyph.src;
+	} else if (glyph.font) {
+		item.iconSource = 'font://' + glyph.font.glyph;
+		item.iconFontFamily = glyph.font.family;
+	} else if (glyph.text) {
+		// font:// with no iconFontFamily draws through the default font.
+		item.iconSource = 'font://' + glyph.text;
+	} else {
+		warnIconOnce(
+			name,
+			`tab icon '${name}' has no src/font/text representation — UITabBarItem can't render svg/markup glyphs.`,
+		);
+	}
+}
+
+function warnIconOnce(name: string, msg: string): void {
+	if (iconWarned.has(name)) return;
+	iconWarned.add(name);
+	console.warn('[octane-xplat] ' + msg);
+}
+
+function itemsFor(tabs: readonly PlatformTabSpec[]): TabViewItem[] {
+	let items = itemsCache.get(tabs);
+	if (items !== undefined) return items;
+	items = tabs.map((t) => {
+		const item = new TabViewItem();
+		item.title = t.title;
+		if (t.icon != null) applyIcon(item, t.icon);
+		if (t.stack) {
+			// Parallel-stack pane: the item's view IS a Frame whose default
+			// page hosts the pane's own Octane root. Pushes land inside the
+			// tab; the tab bar stays visible.
+			// Navigate on `loaded`, not eagerly: a navigate issued before the
+			// frame enters the window hierarchy leaves _executingContext
+			// stuck (iOS's delegate never sees didShow) and every later push
+			// queues forever.
+			const frame = new Frame();
+			frame.once('loaded', () => {
+				frame.navigate({
+					create: () => {
+						const page = new Page();
+						page.actionBarHidden = true;
+						// Page is a ContentView — single-child. Root on a
+						// GridLayout child for the same multi-child guarantee.
+						const pane = new GridLayout();
+						page.content = pane;
+						createNativeScriptRoot(pane).render(
+							TabPane as unknown as UniversalComponent, { render: t.render });
+
+						return page;
+					},
+				});
+			});
+
+			registerStack(t.stack, frame);
+			item.view = frame;
+			return item;
+		}
+
+		const cv = new GridLayout();
+		tabsByView.set(cv, t.render);
+		item.view = cv;
+		return item;
+	});
+
+	itemsCache.set(tabs, items);
+	return items;
+}
+
+// Panes mount lazily: a pane view that isn't loaded yet would render into
+// nothing — mount on the tabview's loaded event, all at once.
+function mountPanes(e: any) {
+	const tv = e.object as TabView;
+	for (const item of tv.items as TabViewItem[]) {
+		const cv = item.view as GridLayout;
+		if (!(cv instanceof GridLayout) || paneRoots.has(cv)) continue;
+		const render = tabsByView.get(cv);
+		if (!render) continue;
+		const root = createNativeScriptRoot(cv);
+		paneRoots.set(cv, root);
+		root.render(TabPane as unknown as UniversalComponent, { render });
+	}
+}
+
+function TabBarInner(props: {
+	className?: any;
+	style?: any;
+	id?: string;
+	tabs: readonly PlatformTabSpec[];
+	selectedIndex?: number;
+	onSelectedIndexChanged?: (index: number) => void;
+	ios?: Record<string, any>;
+	modifiers?: PlatformWidgetProps<PlatformTabsProps>['modifiers'];
+}) @{
+	<tabview
+		ref={(v: any) => applyEscapeProps(v, props)}
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		items={itemsFor(props.tabs)}
+		selectedIndex={props.selectedIndex}
+		onSelectedIndexChanged={(e: any) => props.onSelectedIndexChanged?.(e.value)}
+		onLoaded={mountPanes}
+	/>
+}
+
+// Memoized on the tabs array — TabView.item writes rebuild the native
+// structure, and the driver re-applies props every render.
+const MemoTabBar = memo(TabBarInner, (a, b) => a.tabs === b.tabs && a.selectedIndex === b.selectedIndex && a.modifiers === b.modifiers);
+
+/** UITabBar — the platform tab bar (UIKit UITabBarController-backed TabView).
+ *  Real per-pane Frames: each `stack` tab keeps a native navigation stack
+ *  inside its pane. The self-drawn shared `Tabs` lives in the root export.
+ *  `tabs` is identity-stable (module const preferred). */
+export function UITabBar(props: PlatformWidgetProps<PlatformTabsProps>) @{
+	<MemoTabBar
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		tabs={props.tabs}
+		selectedIndex={props.selectedIndex}
+		ios={props.ios}
+		onSelectedIndexChanged={props.onSelectedIndexChanged}
+		modifiers={props.modifiers}
+	/>
+}

package/src/ios/UITableView.ios.tsrx

@@ -0,0 +1,186 @@
+/** @jsxImportSource @nativescript-community/octane */
+// Universal hooks import from 'octane' — the compiler retargets them to the
+// nativescript runtime, and the dev server serves them via HTTP-ESM.
+import { memo, useEffect, useRef } from 'octane';
+import { ScrollView } from '@nativescript/core';
+import type { ListProps, PlatformWidgetProps } from "../props";
+import type { RefreshConfig, RefreshController } from '../refresh';
+import { cx } from "../cx";
+import { ActivityIndicator } from '../ActivityIndicator.tsrx';
+import { applyEscapeProps } from '../escape-props';
+import { REFRESH_HEADER_HEIGHT } from '../refresh-metrics';
+import { createPullToRefresh } from '../refresh';
+
+function rejectNestedScrollView(event: any) {
+	let parent = event.object?.parent;
+	while (parent) {
+		if (parent instanceof ScrollView) {
+			throw new Error('[UITableView] cannot be nested inside native ScrollView. Use ScrollBox so the list owns scrolling.');
+		}
+
+		parent = parent.parent;
+	}
+}
+
+/** Stable ref bag across the memo boundary — refresh callbacks are fresh
+ *  closures each parent render, so the props live behind refs and the
+ *  memo compare just sees the same bag. */
+interface RefreshBag {
+	cfg: { current: RefreshConfig };
+	indicator: { current: any };
+	ctl: { current: RefreshController | null };
+}
+
+// Cell machinery is driver-owned since @nativescript-community/octane 0.2.1
+// (upstream #7, closes our issue #1): `renderItem` on <listview> makes
+// itemTemplate vend a ContentView per recycled cell, each with its own
+// universal root; itemLoading binds items[index] and skips unchanged rows;
+// a changed renderItem re-binds live cells; discard unmounts the roots.
+// The cell ContentView is single-child — a renderItem returning multiple
+// roots would silently drop siblings — so output wraps in a gridlayout.
+function UITableViewInner(props: {
+	className?: any;
+	style?: any;
+	id?: string;
+	items: any[];
+	renderItem: (item: any, index: number) => any;
+	estimatedItemHeight?: number;
+	onEndReached?: () => void;
+	ios?: Record<string, any>;
+	modifiers?: PlatformWidgetProps<ListProps>['modifiers'];
+	refresh?: RefreshBag;
+}) @{
+	const lv = useRef<any>(null);
+	useEffect(() => {
+		const bag = props.refresh;
+		if (!bag || !lv.current) return;
+		bag.ctl.current = createPullToRefresh({
+			scroller: lv.current,
+			indicator: bag.indicator.current,
+			isAtTop: () => true, // iOS reads contentOffset directly — unused
+			cfg: bag.cfg,
+		});
+
+		return () => {
+			bag.ctl.current?.detach();
+			bag.ctl.current = null;
+		};
+	}, []);
+
+	<listview
+		ref={(v: any) => {
+			lv.current = v;
+			applyEscapeProps(v, props);
+		}}
+		id={props.id}
+		className={cx(props.className)}
+		style={props.style}
+		items={props.items}
+		iosEstimatedRowHeight={props.estimatedItemHeight}
+		onLoadMoreItems={props.onEndReached}
+		onLoaded={rejectNestedScrollView}
+		renderItem={(item: any, index: number) => <gridlayout>{props.renderItem(item, index)}</gridlayout>}
+		{...props.ios}
+	/>
+}
+
+// The listview subtree is memoized on `items` and list configuration: the
+// universal driver re-applies props on every render (no value diffing), and
+// each write can trigger view-level side effects — measured: every unrelated
+// parent re-render refired itemLoading for all visible cells. Memoized on the
+// items reference and list configuration, unrelated parent re-renders skip
+// this subtree. Constraint: `renderItem` should be identity-stable (a
+// useCallback-style ref) — a fresh closure each render is deliberately
+// not part of the compare. (`UITableViewInner` must precede this — compiled
+// components are consts, not hoisted functions.)
+const MemoListView = memo(UITableViewInner, (a, b) =>
+	a.items === b.items &&
+	a.className === b.className &&
+	a.style === b.style &&
+	a.id === b.id &&
+	a.estimatedItemHeight === b.estimatedItemHeight &&
+	a.onEndReached === b.onEndReached &&
+	a.ios === b.ios &&
+	a.modifiers === b.modifiers &&
+	a.refresh === b.refresh
+);
+
+/** UITableView — the platform recycling list (UIKit UITableView via
+ *  NativeScript `listview`). `items` is a plain array, ItemsSource, or
+ *  ObservableArray — the driver binds `items[index]` into the recycled
+ *  cell's root and skips rebinds whose row, item, and renderer are
+ *  unchanged. Cell identity = the recycled host view, not the item.
+ *  The shared `ui` export has no List — compose ScrollView + mapped
+ *  children there.
+ *
+ *  `refreshing`/`onRefresh`/`refreshThreshold` enable pull-to-refresh:
+ *  the indicator is self-drawn (vx-spinner), the pull rides UITableView's
+ *  own bounce, and the docked phase holds via contentInset — the same
+ *  mechanics UIRefreshControl uses, without its OS spinner. */
+export function UITableView(props: PlatformWidgetProps<ListProps>) @{
+	const refreshCapable = props.onRefresh != null || props.refreshing != null;
+	const cfg = useRef<RefreshConfig>({});
+	cfg.current = {
+		onRefresh: props.onRefresh,
+		refreshing: props.refreshing,
+		threshold: props.refreshThreshold,
+	};
+
+	const indicator = useRef<any>(null);
+	const ctl = useRef<RefreshController | null>(null);
+	const refresh = useRef<RefreshBag>({ cfg, indicator, ctl });
+
+	useEffect(() => {
+		ctl.current?.sync();
+	}, [props.refreshing]);
+
+	@if (props.items.length > 0) {
+		@if (refreshCapable) {
+			<gridlayout
+				ref={(v: any) => {
+					// iOS doesn't clip children — the resting indicator sits
+					// translated above the wrapper's top edge without it.
+					if (v?.ios) v.ios.clipsToBounds = true;
+				}}
+				className={cx('vx-refresh-wrap', props.className)}
+				style={props.style}
+			>
+				<MemoListView
+					id={props.id}
+					items={props.items}
+					renderItem={props.renderItem}
+					estimatedItemHeight={props.estimatedItemHeight}
+					onEndReached={props.onEndReached}
+					ios={props.ios}
+					modifiers={props.modifiers}
+					refresh={refresh.current}
+				/>
+				<flexboxlayout
+					ref={(v: any) => {
+						indicator.current = v;
+					}}
+					className="vx-refresh"
+					verticalAlignment="top"
+					height={REFRESH_HEADER_HEIGHT}
+					translateY={-REFRESH_HEADER_HEIGHT}
+				>
+					<ActivityIndicator />
+				</flexboxlayout>
+			</gridlayout>
+		} @else {
+			<MemoListView
+				id={props.id}
+				items={props.items}
+				className={props.className}
+				style={props.style}
+				renderItem={props.renderItem}
+				estimatedItemHeight={props.estimatedItemHeight}
+				onEndReached={props.onEndReached}
+				ios={props.ios}
+				modifiers={props.modifiers}
+			/>
+		}
+	} @else {
+		<>{props.renderEmpty?.()}</>
+	}
+}

package/src/ios/icon.ios.ts

@@ -0,0 +1,8 @@
+import type { PlatformIconChoice } from '../props'
+
+/** Selector for glyphs used by iOS-authentic widgets; the shared root Icon is unchanged. */
+export const Icon = {
+	select(choice: PlatformIconChoice): string {
+		return choice.ios.startsWith('sys://') ? choice.ios : `sys://${choice.ios}`
+	},
+}

package/src/ios/index.ts

@@ -0,0 +1,42 @@
+// @octane-xplat/ui/ios — iOS-authentic widgets. OS chrome is the point:
+// these resolve only in native builds (the `ui/ios` subpath has no `web`
+// export condition). Use inside `.ios.tsrx`/`.mobile.tsrx` files, or behind
+// `isIOS` in native-default code — a shared `.tsrx` that imports this path fails
+// the web build on purpose.
+
+export { UISwitch } from './UISwitch.ios.tsrx'
+export { UISlider } from './UISlider.ios.tsrx'
+export { UIActivityIndicatorView } from './UIActivityIndicatorView.ios.tsrx'
+export { UITableView } from './UITableView.ios.tsrx'
+export { UITabBar } from './UITabBar.ios.tsrx'
+export type { PlatformTabSpec as TabSpec } from '../props'
+export { UIModal } from './UIModal.ios.tsrx'
+export { openModal } from './openModal.ios'
+export { SideDrawer } from './SideDrawer.ios.tsrx'
+export { LiquidGlass } from './LiquidGlass.ios.tsrx'
+export { LiquidGlassContainer } from './LiquidGlassContainer.ios.tsrx'
+export { Icon } from './icon.ios'
+export { modifier } from '../modifier-factories'
+
+export type {
+	SwitchProps,
+	SliderProps,
+	ActivityIndicatorProps,
+	ListProps,
+	TabsProps,
+	ModalProps,
+	ModalOpenOptions,
+	ModalOpenResult,
+	OpenModal,
+	DrawerProps,
+	LiquidGlassProps,
+	LiquidGlassContainerProps,
+	GlassConfig,
+	NativeModifier,
+	NativeModifierValue,
+	PlatformIconChoice,
+	PlatformTabSpec,
+	PlatformTabsProps,
+	PlatformWidgetProps,
+	RefreshProps,
+} from '../props'

package/src/ios/openModal.ios.ts

@@ -0,0 +1,55 @@
+import { Frame, GridLayout } from '@nativescript/core'
+import { createNativeScriptRoot } from '@nativescript-community/octane'
+import type { UniversalComponent } from 'octane/universal'
+import type { ModalOpenOptions, ModalOpenResult, OpenModal } from '../props'
+import { applyThemeClasses } from '../theme/theme-scheme'
+import { modalPresenter } from '../modal-presenter.mobile'
+
+/** Open a component in its own NativeScript modal root and resolve on close. */
+export const openModal: OpenModal = (Component, params, options = {}) =>
+	new Promise<ModalOpenResult>((resolve, reject) => {
+		const presenter = modalPresenter(Frame.topmost())
+		if (!presenter) {
+			reject(
+				new Error(
+					'openModal dropped — no live presenter. The topmost frame has no loaded currentPage (a page mid-navigation), or no frame is active yet.',
+				),
+			)
+
+			return
+		}
+
+		const host = new GridLayout()
+		const unbindTheme = applyThemeClasses(host, 'vx-modal-host')
+		const root = createNativeScriptRoot(host) as any
+		let finished = false
+		const finish = (result?: ModalOpenResult) => {
+			if (finished) {
+				return
+			}
+
+			finished = true
+			unbindTheme()
+			root.unmount?.()
+			host.removeChildren?.()
+			resolve(result)
+		}
+
+		const close = (result?: ModalOpenResult) => host.closeModal(result)
+		root.render(Component as UniversalComponent, { params, close })
+
+		const fullscreen = options.presentation
+			? options.presentation === 'fullscreen'
+			: (options.fullscreen ?? true)
+
+		// showModal takes (viewToShow, options). On iOS fullscreen=false is a
+		// form sheet.
+		presenter.showModal(host, {
+			context: {},
+			closeCallback: finish,
+			fullscreen,
+			animated: options.animated ?? true,
+		})
+	})
+
+export type { ModalOpenOptions }

package/src/keyboard-inset.mobile.ts

@@ -0,0 +1,89 @@
+import { Application } from '@nativescript/core';
+
+// One shared observer tracks the keyboard's current bottom inset — a sheet
+// opened while the keyboard is ALREADY up must lift immediately (a
+// WillChangeFrame observer only learns about changes after binding), and a
+// focused field keeps the inset live across sheet swaps.
+const bound = new Set<any>();
+let inset = 0;
+let wired = false;
+
+const apply = () => {
+	bound.forEach((host) => {
+		host.translateY = -inset;
+	});
+};
+
+
+const wireIos = () => {
+	if (wired) { return; }
+	wired = true;
+	NSNotificationCenter.defaultCenter.addObserverForNameObjectQueueUsingBlock(
+		UIKeyboardWillChangeFrameNotification,
+		null,
+		NSOperationQueue.mainQueue,
+		(note: any) => {
+			// UIKeyboardFrameEndUserInfoKey arrives boxed as NSValue whose
+			// `CGRectValue` marshals to a plain CGRect object (not a call).
+			const raw = note.userInfo.objectForKey(UIKeyboardFrameEndUserInfoKey);
+			const boxed = raw?.CGRectValue;
+			const frame = typeof boxed === 'function' ? raw.CGRectValue() : (boxed ?? raw);
+			inset = Math.max(0, UIScreen.mainScreen.bounds.size.height - (frame?.origin?.y ?? UIScreen.mainScreen.bounds.size.height));
+			apply();
+		},
+	);
+};
+
+/** Lift a bottom-anchored overlay host above the software keyboard.
+ *  iOS: a shared UIKeyboardWillChangeFrame observer tracks the inset and
+ *  translateY shifts the host — reliable on popup views regardless of how
+ *  the RootLayout passes margins through. The current inset is applied at
+ *  bind time so hosts opened over an already-visible keyboard still lift.
+ *  Android: when the window runs `adjustResize` (KeyboardAvoiding sets it)
+ *  the RootLayout resizes and the host follows on its own; otherwise the
+ *  decor view's IME inset supplies the lift. Returns an unbind that
+ *  restores the transform — call it when the host detaches. */
+export function bindBottomInsetToKeyboard(host: any): () => void {
+	if (Application.ios) {
+		wireIos();
+		bound.add(host);
+		host.translateY = -inset;
+		return () => {
+			bound.delete(host);
+			host.translateY = 0;
+		};
+	}
+
+	if (Application.android) {
+		const nativeWindow = Application.android.foregroundActivity?.window;
+		if (!nativeWindow) { return () => {}; }
+		const params = (globalThis as any).android?.view?.WindowManager?.LayoutParams;
+		if (!params) { return () => {}; }
+		// adjustResize resizes the RootLayout for us — an extra offset would
+		// double-lift the host.
+		if ((nativeWindow.attributes.softInputMode & params.SOFT_INPUT_MASK_ADJUST) === params.SOFT_INPUT_ADJUST_RESIZE) {
+			return () => {};
+		}
+
+		const ViewCompat = (globalThis as any).androidx?.core?.view?.ViewCompat;
+		const WindowInsetsCompat = (globalThis as any).androidx?.core?.view?.WindowInsetsCompat;
+		if (!ViewCompat || !WindowInsetsCompat) { return () => {}; }
+		const decorView = nativeWindow.decorView;
+		const listener = new ViewCompat.OnApplyWindowInsetsListener({
+			onApplyWindowInsets: (v: any, insets: any) => {
+				const ime = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom;
+				const nav = insets.getInsets(WindowInsetsCompat.Type.systemBars()).bottom;
+				host.translateY = -Math.max(0, ime - nav);
+				return insets;
+			},
+		});
+
+		ViewCompat.setOnApplyWindowInsetsListener(decorView, listener);
+		return () => {
+			host.translateY = 0;
+			ViewCompat.setOnApplyWindowInsetsListener(decorView, null);
+		};
+	}
+
+	return () => {};
+}