@sigx/lynx-keyboard 0.4.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @sigx/lynx-keyboard
+
+Soft-keyboard handling for [SignalX](https://github.com/signalxjs) on Lynx, with an API mirroring React Native's (`KeyboardAvoidingView`, `KeyboardStickyView`/`InputAccessoryView`, `useKeyboard`). Keeps a composer input — and an accessory toolbar above it — pinned to the top edge of the on-screen keyboard.
+
+Keyboard height reaches JS through the safe-area bridge ([`@sigx/lynx-safe-area`](../lynx-safe-area)): the native publisher reports the IME height as the `keyboard` inset on every `safeAreaChanged` event. This package turns that inset into ready-made layout primitives — no extra native module needed. Keyboard handling stays a separate concern from safe-area, mirroring the RN ecosystem split (`react-native` core / `react-native-keyboard-controller` vs `react-native-safe-area-context`).
+
+## Installation
+
+```bash
+pnpm add @sigx/lynx-keyboard
+```
+
+Requires `<SafeAreaProvider>` (from `@sigx/lynx-safe-area`) at the app root — the same provider every safe-area hook already needs.
+
+## Quick start
+
+The proven chat-screen shape: the content area shrinks (`KeyboardAvoidingView`), the composer bar rides the keyboard (`KeyboardStickyView`). The bar's translate and the area's padding are both `max(0, keyboard - bottomInset)`, so the list bottom always ends exactly where the bar lands.
+
+```tsx
+import { component } from '@sigx/lynx';
+import { KeyboardAvoidingView, KeyboardStickyView } from '@sigx/lynx-keyboard';
+
+const ChatScreen = component(() => () => (
+  <view style={{ display: 'flex', flexDirection: 'column', flexGrow: 1, flexShrink: 1, flexBasis: 0 }}>
+    <KeyboardAvoidingView behavior="padding">
+      <scroll-view style={{ flexGrow: 1, flexShrink: 1, flexBasis: 0 }}>
+        {/* messages */}
+      </scroll-view>
+    </KeyboardAvoidingView>
+    <KeyboardStickyView>
+      {/* toolbar row (formatting buttons, attachments, …) */}
+      {/* input row */}
+    </KeyboardStickyView>
+  </view>
+));
+```
+
+Use **one** primitive per subtree: a bar inside both a padding `KeyboardAvoidingView` *and* a `KeyboardStickyView` lifts twice.
+
+## API
+
+### `<KeyboardStickyView>`
+
+Pins its children to the keyboard's top edge with an MT-animated `translateY` (smooth 60fps, no per-frame thread crossing). When the keyboard is closed the bar rests in its natural flex position. Aliases: `KeyboardAccessoryView`, `KeyboardToolbar`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `offset` | `number` | `0` | Extra gap (dp) above the keyboard. |
+| `animated` | `boolean` | `true` | `false` = discrete BG re-render (debug fallback). |
+| `discountBottomInset` | `boolean` | `true` | Subtract the bottom safe-area inset from the lift. Keep `true` when an ancestor `<SafeAreaView edges={['bottom']}>` already pads the home indicator. |
+
+Note: the bar's `transform` is controlled internally (the MT binding writes `translateY` via `setStyleProperties`; the non-animated path writes an inline transform). A `transform` passed through `style` will be overridden — wrap children in their own view if you need an additional transform.
+
+### `<KeyboardAvoidingView>`
+
+Wraps content and keeps it above the keyboard. Layout-affecting, so it applies inline BG styles (the same pattern as `<SafeAreaView>` — MT-driven layout writes don't reflow `<scroll-view>`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `behavior` | `'padding' \| 'translate' \| 'height'` | `'padding'` | `padding` shrinks the column; `translate` shifts it; `height` appends a spacer. |
+| `keyboardVerticalOffset` | `number` | `0` | Added to the computed lift (RN parity). |
+| `discountBottomInset` | `boolean` | `true` | Same as on `KeyboardStickyView` — set `false` to lift by the full keyboard height when no ancestor pads the bottom inset. |
+
+### Hooks
+
+- `useKeyboard(): Computed<{ height, visible }>` — BG-reactive keyboard state.
+- `useKeyboardLift(discountBottomInset?, offset?): Computed<number>` — the raw lift value.
+- `useKeyboardLiftSV(discountBottomInset?, offset?, duration?): SharedValue<number>` — smoothly animated MT SharedValue tracking the lift; bind with `useAnimatedStyle(ref, sv, 'translateY', { factor: -1 })`.
+
+## How it works
+
+- **Height source** — `useSafeAreaInsets().value.keyboard`. There is no separate keyboard event API in Lynx; the safe-area publisher is canonical.
+- **The lift** — `max(0, keyboard - bottomInset)`: the keyboard covers the home-indicator region, so a bar that already sits above the bottom inset only needs to rise by the difference. Never add both.
+- **BG→MT bridge** — the keyboard inset is a BG-only signal (deliberately not a SharedValue in lynx-safe-area). `useKeyboardLiftSV` watches it from a BG effect and dispatches an MT `withTiming` (from [`@sigx/lynx-motion`](../lynx-motion)) toward each new target; the tween then runs entirely on the main thread.
+- **Transform vs layout** — only `translateY` is MT-animated. Padding/height go through inline BG styles because MT layout writes land after the first layout pass and `<scroll-view>` won't reflow.
+
+## Demo
+
+See the **Keyboard lab** screen in [`examples/showcase`](../../examples/showcase) (Settings tab → Keyboard lab).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { KeyboardAvoidingView } from './keyboard-avoiding-view.js';
+export { KeyboardStickyView, KeyboardStickyView as KeyboardAccessoryView, KeyboardStickyView as KeyboardToolbar, } from './keyboard-sticky-view.js';
+export { useKeyboard, useKeyboardLift, useKeyboardLiftSV } from './use-keyboard.js';
+export type { KeyboardAvoidingBehavior, KeyboardAvoidingViewProps, KeyboardState, KeyboardStickyViewProps, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,kBAAkB,EAGlB,kBAAkB,IAAI,qBAAqB,EAC3C,kBAAkB,IAAI,eAAe,GACtC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACpF,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// Public API for @sigx/lynx-keyboard.
+//
+// Soft-keyboard handling with an RN-mirroring API. Keyboard height reaches
+// JS through the safe-area bridge (`@sigx/lynx-safe-area`) — this package
+// turns that inset into ready-made layout primitives. Keyboard handling is
+// its own concern, separate from safe-area, mirroring the RN ecosystem
+// (react-native core / react-native-keyboard-controller vs
+// react-native-safe-area-context).
+export { KeyboardAvoidingView } from './keyboard-avoiding-view.js';
+export { KeyboardStickyView, 
+// RN aliases: core's InputAccessoryView role is covered by the sticky
+// view; react-native-keyboard-controller names for the same shape.
+KeyboardStickyView as KeyboardAccessoryView, KeyboardStickyView as KeyboardToolbar, } from './keyboard-sticky-view.js';
+export { useKeyboard, useKeyboardLift, useKeyboardLiftSV } from './use-keyboard.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,uEAAuE;AACvE,2DAA2D;AAC3D,mCAAmC;AAEnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,kBAAkB;AAClB,sEAAsE;AACtE,mEAAmE;AACnE,kBAAkB,IAAI,qBAAqB,EAC3C,kBAAkB,IAAI,eAAe,GACtC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/keyboard-avoiding-view.d.ts

@@ -0,0 +1,24 @@
+import type { KeyboardAvoidingViewProps } from './types.js';
+/**
+ * RN-mirroring `KeyboardAvoidingView`: wraps screen content and keeps it
+ * above the soft keyboard. Default `behavior="padding"` squeezes the flex
+ * column so nothing hides behind the keyboard.
+ *
+ * Implementation: BG signal + inline style, the same pattern as
+ * lynx-safe-area's `<SafeAreaView>` — layout-affecting properties must NOT
+ * be driven from the main thread (`setStyleProperties` layout writes fire
+ * after the first layout pass and `<scroll-view>` won't reflow), so the
+ * padding snaps to the final value in one re-render. The native keyboard
+ * slide masks the snap. For a smoothly *animated* bar, use
+ * `<KeyboardStickyView>` (transform-based, MT-animated) instead — and use
+ * one or the other on a given subtree, not both, or it double-lifts.
+ *
+ * The bottom safe-area inset is discounted from the lift
+ * (`max(0, keyboard - bottom + keyboardVerticalOffset)`) because an
+ * ancestor `<SafeAreaView edges={['bottom']}>` typically already pads the
+ * home indicator, which the keyboard covers when open.
+ */
+export declare const KeyboardAvoidingView: import("@sigx/runtime-core").ComponentFactory<KeyboardAvoidingViewProps, void, {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
+//# sourceMappingURL=keyboard-avoiding-view.d.ts.map

package/dist/keyboard-avoiding-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-avoiding-view.d.ts","sourceRoot":"","sources":["../src/keyboard-avoiding-view.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB;;EAmC/B,CAAC"}

package/dist/keyboard-avoiding-view.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@sigx/lynx/jsx-runtime";
+import { component } from '@sigx/lynx';
+import { useSafeAreaInsets } from '@sigx/lynx-safe-area';
+/**
+ * RN-mirroring `KeyboardAvoidingView`: wraps screen content and keeps it
+ * above the soft keyboard. Default `behavior="padding"` squeezes the flex
+ * column so nothing hides behind the keyboard.
+ *
+ * Implementation: BG signal + inline style, the same pattern as
+ * lynx-safe-area's `<SafeAreaView>` — layout-affecting properties must NOT
+ * be driven from the main thread (`setStyleProperties` layout writes fire
+ * after the first layout pass and `<scroll-view>` won't reflow), so the
+ * padding snaps to the final value in one re-render. The native keyboard
+ * slide masks the snap. For a smoothly *animated* bar, use
+ * `<KeyboardStickyView>` (transform-based, MT-animated) instead — and use
+ * one or the other on a given subtree, not both, or it double-lifts.
+ *
+ * The bottom safe-area inset is discounted from the lift
+ * (`max(0, keyboard - bottom + keyboardVerticalOffset)`) because an
+ * ancestor `<SafeAreaView edges={['bottom']}>` typically already pads the
+ * home indicator, which the keyboard covers when open.
+ */
+export const KeyboardAvoidingView = component(({ props, slots }) => {
+    const insets = useSafeAreaInsets();
+    const behavior = props.behavior ?? 'padding';
+    const kvo = props.keyboardVerticalOffset ?? 0;
+    const discountBottomInset = props.discountBottomInset ?? true;
+    return () => {
+        const i = insets.value;
+        const lift = i.keyboard > 0
+            ? Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + kvo)
+            : 0;
+        // Fill-parent defaults, mirroring SafeAreaView: Lynx resolves the
+        // `flex: 1` shorthand with `flexBasis: 'auto'`, which sizes to content
+        // and collapses the chain — long-form `flexBasis: 0` is the only
+        // reliable "fill remaining space".
+        const base = {
+            flexGrow: 1,
+            flexShrink: 1,
+            flexBasis: 0,
+            minHeight: 0,
+            display: 'flex',
+            flexDirection: 'column',
+        };
+        if (behavior === 'padding') {
+            base['paddingBottom'] = `${lift}px`;
+        }
+        else if (behavior === 'translate') {
+            base['transform'] = `translateY(-${lift}px)`;
+        }
+        return (_jsxs("view", { class: props.class, style: props.style ? { ...base, ...props.style } : base, children: [slots.default?.(), behavior === 'height' ? _jsx("view", { style: { height: `${lift}px`, flexShrink: 0 } }) : null] }));
+    };
+});
+//# sourceMappingURL=keyboard-avoiding-view.js.map

package/dist/keyboard-avoiding-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-avoiding-view.js","sourceRoot":"","sources":["../src/keyboard-avoiding-view.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAA4B,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IAC5F,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,sBAAsB,IAAI,CAAC,CAAC;IAC9C,MAAM,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,IAAI,IAAI,CAAC;IAE9D,OAAO,GAAG,EAAE;QACV,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC;YACzB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YACtE,CAAC,CAAC,CAAC,CAAC;QACN,kEAAkE;QAClE,uEAAuE;QACvE,iEAAiE;QACjE,mCAAmC;QACnC,MAAM,IAAI,GAAoC;YAC5C,QAAQ,EAAE,CAAC;YACX,UAAU,EAAE,CAAC;YACb,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,QAAQ;SACxB,CAAC;QACF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,eAAe,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC;QACtC,CAAC;aAAM,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;YACpC,IAAI,CAAC,WAAW,CAAC,GAAG,eAAe,IAAI,KAAK,CAAC;QAC/C,CAAC;QACD,OAAO,CACL,gBAAM,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,aAC9E,KAAK,CAAC,OAAO,EAAE,EAAE,EACjB,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAM,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,GAAI,CAAC,CAAC,CAAC,IAAI,IAClF,CACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/keyboard-sticky-view.d.ts

@@ -0,0 +1,36 @@
+import type { KeyboardStickyViewProps } from './types.js';
+/**
+ * Pins its children to the top edge of the soft keyboard — the home for a
+ * chat composer / input-accessory toolbar. (RN names: `KeyboardStickyView`
+ * in react-native-keyboard-controller, `InputAccessoryView` in core.)
+ *
+ * The bar flows as a normal bottom flex sibling; when the keyboard opens it
+ * is lifted with `transform: translateY(-lift)` where
+ * `lift = max(0, keyboard - bottomInset + offset)`. Transform doesn't
+ * reflow layout, so (unlike padding/height) it is safe to drive from the
+ * main thread via `useAnimatedStyle` — see lynx-safe-area's
+ * `safe-area-view.tsx` for why MT-driven *layout* writes are a trap.
+ *
+ * Note: because the bar is translated rather than re-laid-out, content
+ * behind it (e.g. the bottom of a message list) does not shrink — it can
+ * sit behind the keyboard. Pair with `<KeyboardAvoidingView
+ * behavior="padding">` around the *content area only* (never around the bar
+ * itself, or it double-lifts) when the content must stay fully visible.
+ *
+ * @example
+ * ```tsx
+ * <Col class="flex-fill">
+ *   <KeyboardAvoidingView behavior="padding">
+ *     <ScrollView class="flex-1">{messages}</ScrollView>
+ *   </KeyboardAvoidingView>
+ *   <KeyboardStickyView>
+ *     <Toolbar />
+ *     <Composer />
+ *   </KeyboardStickyView>
+ * </Col>
+ * ```
+ */
+export declare const KeyboardStickyView: import("@sigx/runtime-core").ComponentFactory<KeyboardStickyViewProps, void, {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
+//# sourceMappingURL=keyboard-sticky-view.d.ts.map

package/dist/keyboard-sticky-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-sticky-view.d.ts","sourceRoot":"","sources":["../src/keyboard-sticky-view.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,kBAAkB;;EAmC7B,CAAC"}

package/dist/keyboard-sticky-view.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component, useAnimatedStyle, useMainThreadRef, } from '@sigx/lynx';
+import { useKeyboardLift, useKeyboardLiftSV } from './use-keyboard.js';
+/**
+ * Pins its children to the top edge of the soft keyboard — the home for a
+ * chat composer / input-accessory toolbar. (RN names: `KeyboardStickyView`
+ * in react-native-keyboard-controller, `InputAccessoryView` in core.)
+ *
+ * The bar flows as a normal bottom flex sibling; when the keyboard opens it
+ * is lifted with `transform: translateY(-lift)` where
+ * `lift = max(0, keyboard - bottomInset + offset)`. Transform doesn't
+ * reflow layout, so (unlike padding/height) it is safe to drive from the
+ * main thread via `useAnimatedStyle` — see lynx-safe-area's
+ * `safe-area-view.tsx` for why MT-driven *layout* writes are a trap.
+ *
+ * Note: because the bar is translated rather than re-laid-out, content
+ * behind it (e.g. the bottom of a message list) does not shrink — it can
+ * sit behind the keyboard. Pair with `<KeyboardAvoidingView
+ * behavior="padding">` around the *content area only* (never around the bar
+ * itself, or it double-lifts) when the content must stay fully visible.
+ *
+ * @example
+ * ```tsx
+ * <Col class="flex-fill">
+ *   <KeyboardAvoidingView behavior="padding">
+ *     <ScrollView class="flex-1">{messages}</ScrollView>
+ *   </KeyboardAvoidingView>
+ *   <KeyboardStickyView>
+ *     <Toolbar />
+ *     <Composer />
+ *   </KeyboardStickyView>
+ * </Col>
+ * ```
+ */
+export const KeyboardStickyView = component(({ props, slots }) => {
+    const discountBottomInset = props.discountBottomInset ?? true;
+    const offset = props.offset ?? 0;
+    // Hooks register unconditionally (same rule as NavDrawer's backdrop
+    // binding): a runtime `animated` toggle must keep working in both
+    // directions, and a binding created inside `if (animated)` would be
+    // missing after a false→true flip. The reactive accessor form binds /
+    // unbinds the MT transform as the prop changes.
+    const barRef = useMainThreadRef(null);
+    const liftSV = useKeyboardLiftSV(discountBottomInset, offset);
+    const liftBG = useKeyboardLift(discountBottomInset, offset);
+    useAnimatedStyle(barRef, () => (props.animated ?? true)
+        // factor -1: the SV stays a positive height; the mapper negates it so
+        // the bar moves UP.
+        ? { sv: liftSV, mapperName: 'translateY', params: { factor: -1 } }
+        : null);
+    return () => {
+        const animated = props.animated ?? true;
+        return (_jsx("view", { "main-thread:ref": barRef, class: props.class, 
+            // Debug / fallback path (`animated={false}`): discrete BG re-render,
+            // no tween — the MT binding above is unregistered then.
+            style: animated
+                ? props.style
+                : { ...props.style, transform: `translateY(-${liftBG.value}px)` }, children: slots.default?.() }));
+    };
+});
+//# sourceMappingURL=keyboard-sticky-view.js.map

package/dist/keyboard-sticky-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-sticky-view.js","sourceRoot":"","sources":["../src/keyboard-sticky-view.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAA0B,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IACxF,MAAM,mBAAmB,GAAG,KAAK,CAAC,mBAAmB,IAAI,IAAI,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAEjC,oEAAoE;IACpE,kEAAkE;IAClE,oEAAoE;IACpE,sEAAsE;IACtE,gDAAgD;IAChD,MAAM,MAAM,GAAG,gBAAgB,CAA4B,IAAI,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,iBAAiB,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,eAAe,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IAC5D,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAC5B,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACtB,sEAAsE;QACtE,oBAAoB;QACpB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;QAClE,CAAC,CAAC,IAAI,CAAC,CAAC;IAEZ,OAAO,GAAG,EAAE;QACV,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;QACxC,OAAO,CACL,kCACmB,MAAM,EACvB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,qEAAqE;YACrE,wDAAwD;YACxD,KAAK,EAAE,QAAQ;gBACb,CAAC,CAAC,KAAK,CAAC,KAAK;gBACb,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,eAAe,MAAM,CAAC,KAAK,KAAK,EAAE,YAElE,KAAK,CAAC,OAAO,EAAE,EAAE,GACb,CACR,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import type { Define } from '@sigx/lynx';
+/**
+ * RN-mirroring behavior modes for `<KeyboardAvoidingView>`:
+ * - `'padding'`  — add `paddingBottom` equal to the keyboard overlap, squeezing
+ *   the flex column so ALL content stays above the keyboard.
+ * - `'translate'` — shift the whole container up by the overlap (content at the
+ *   top moves off-screen; layout does not reflow).
+ * - `'height'`   — append a trailing spacer view of the overlap height, so
+ *   the content above is squeezed without touching the container's padding.
+ *   (Closest analogue of RN's height-resizing behavior; the implementation
+ *   differs — RN shrinks the container's own height, this inserts a spacer.)
+ */
+export type KeyboardAvoidingBehavior = 'padding' | 'translate' | 'height';
+/** BG-reactive keyboard state returned by `useKeyboard()`. */
+export interface KeyboardState {
+    /** Soft-keyboard height in dp; 0 when hidden. */
+    height: number;
+    visible: boolean;
+}
+export type KeyboardAvoidingViewProps = Define.Prop<'behavior', KeyboardAvoidingBehavior, false> & Define.Prop<'keyboardVerticalOffset', number, false>
+/**
+ * Subtract the bottom safe-area inset from the lift (default `true`).
+ * Keep `true` when an ancestor `<SafeAreaView edges={['bottom']}>` already
+ * pads the home-indicator inset; set `false` to lift by the full keyboard
+ * height when no ancestor applies the bottom inset.
+ */
+ & Define.Prop<'discountBottomInset', boolean, false> & Define.Prop<'class', string, false> & Define.Prop<'style', Record<string, string | number>, false> & Define.Slot<'default'>;
+export type KeyboardStickyViewProps = 
+/** Extra gap (dp) between the bar and the keyboard's top edge. */
+Define.Prop<'offset', number, false>
+/**
+ * `true` (default): smooth MT-driven translateY via SharedValue + timing.
+ * `false`: plain BG re-render with an inline transform (debug fallback).
+ */
+ & Define.Prop<'animated', boolean, false>
+/**
+ * Subtract the bottom safe-area inset from the lift (default `true`).
+ * Keep `true` when an ancestor `<SafeAreaView edges={['bottom']}>` already
+ * pads the home-indicator inset — the keyboard covers that region, so the
+ * bar only needs to rise by the difference. Set `false` if no ancestor
+ * applies the bottom inset.
+ */
+ & Define.Prop<'discountBottomInset', boolean, false> & Define.Prop<'class', string, false> & Define.Prop<'style', Record<string, string | number>, false> & Define.Slot<'default'>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1E,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,yBAAyB,GACjC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,wBAAwB,EAAE,KAAK,CAAC,GACxD,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE,MAAM,EAAE,KAAK,CAAC;AACtD;;;;;GAKG;GACD,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,OAAO,EAAE,KAAK,CAAC,GAClD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,GAC5D,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAE3B,MAAM,MAAM,uBAAuB;AACjC,kEAAkE;AAChE,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AACtC;;;GAGG;GACD,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC;AACzC;;;;;;GAMG;GACD,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,OAAO,EAAE,KAAK,CAAC,GAClD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,GAC5D,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/use-keyboard.d.ts

@@ -0,0 +1,38 @@
+import { type Computed, type SharedValue } from '@sigx/lynx';
+import type { KeyboardState } from './types.js';
+/**
+ * BG-reactive soft-keyboard state. The height comes from the safe-area
+ * bridge (`useSafeAreaInsets().value.keyboard`, fed by the native
+ * `safeAreaChanged` event) — Lynx has no separate keyboard event API.
+ * Consumers re-render on keyboard show/hide.
+ *
+ * Must be used under `<SafeAreaProvider>` (same requirement as every
+ * safe-area hook); without one it reads zero insets and warns in dev.
+ */
+export declare function useKeyboard(): Computed<KeyboardState>;
+/**
+ * BG-reactive "lift" — how far a bottom-anchored bar must rise to clear the
+ * keyboard. `max(0, keyboard - bottomInset + offset)` while the keyboard is
+ * visible, 0 otherwise. The bottom inset is discounted because an ancestor
+ * `<SafeAreaView edges={['bottom']}>` typically already keeps the bar above
+ * the home indicator, and the keyboard covers that region when open.
+ */
+export declare function useKeyboardLift(discountBottomInset?: boolean, offset?: number): Computed<number>;
+/**
+ * Smoothly animated MT SharedValue tracking the keyboard lift, for
+ * `useAnimatedStyle(ref, sv, 'translateY', { factor: -1 })` bindings.
+ *
+ * The keyboard inset is BG-only (deliberately not a SharedValue in
+ * lynx-safe-area's provider), so this hook is the BG→MT bridge: a BG effect
+ * watches the inset signal and dispatches an MT `withTiming` toward the new
+ * target each time it changes. `withTiming` is itself a `'main thread'`
+ * worklet, so referencing it from the dispatched worklet survives `_c`
+ * capture; the timing loop then runs entirely on MT (no per-frame thread
+ * crossing). The watcher effect is stopped on unmount (`effect` comes from
+ * `@sigx/reactivity` and is NOT lifecycle-scoped — same manual-stop pattern
+ * as lynx-safe-area's provider).
+ */
+export declare function useKeyboardLiftSV(discountBottomInset?: boolean, offset?: number, 
+/** Tween duration in seconds (lynx-motion convention). */
+duration?: number): SharedValue<number>;
+//# sourceMappingURL=use-keyboard.d.ts.map

package/dist/use-keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard.d.ts","sourceRoot":"","sources":["../src/use-keyboard.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAAC,aAAa,CAAC,CAMrD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,mBAAmB,UAAO,EAC1B,MAAM,SAAI,GACT,QAAQ,CAAC,MAAM,CAAC,CAOlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,mBAAmB,UAAO,EAC1B,MAAM,SAAI;AACV,0DAA0D;AAC1D,QAAQ,SAAO,GACd,WAAW,CAAC,MAAM,CAAC,CAqCrB"}

package/dist/use-keyboard.js

@@ -0,0 +1,85 @@
+import { computed, effect, onUnmounted, runOnMainThread, useSharedValue, } from '@sigx/lynx';
+import { useSafeAreaInsets } from '@sigx/lynx-safe-area';
+import { withTiming } from '@sigx/lynx-motion';
+/**
+ * BG-reactive soft-keyboard state. The height comes from the safe-area
+ * bridge (`useSafeAreaInsets().value.keyboard`, fed by the native
+ * `safeAreaChanged` event) — Lynx has no separate keyboard event API.
+ * Consumers re-render on keyboard show/hide.
+ *
+ * Must be used under `<SafeAreaProvider>` (same requirement as every
+ * safe-area hook); without one it reads zero insets and warns in dev.
+ */
+export function useKeyboard() {
+    const insets = useSafeAreaInsets();
+    return computed(() => {
+        const height = insets.value.keyboard;
+        return { height, visible: height > 0 };
+    });
+}
+/**
+ * BG-reactive "lift" — how far a bottom-anchored bar must rise to clear the
+ * keyboard. `max(0, keyboard - bottomInset + offset)` while the keyboard is
+ * visible, 0 otherwise. The bottom inset is discounted because an ancestor
+ * `<SafeAreaView edges={['bottom']}>` typically already keeps the bar above
+ * the home indicator, and the keyboard covers that region when open.
+ */
+export function useKeyboardLift(discountBottomInset = true, offset = 0) {
+    const insets = useSafeAreaInsets();
+    return computed(() => {
+        const i = insets.value;
+        if (i.keyboard <= 0)
+            return 0;
+        return Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + offset);
+    });
+}
+/**
+ * Smoothly animated MT SharedValue tracking the keyboard lift, for
+ * `useAnimatedStyle(ref, sv, 'translateY', { factor: -1 })` bindings.
+ *
+ * The keyboard inset is BG-only (deliberately not a SharedValue in
+ * lynx-safe-area's provider), so this hook is the BG→MT bridge: a BG effect
+ * watches the inset signal and dispatches an MT `withTiming` toward the new
+ * target each time it changes. `withTiming` is itself a `'main thread'`
+ * worklet, so referencing it from the dispatched worklet survives `_c`
+ * capture; the timing loop then runs entirely on MT (no per-frame thread
+ * crossing). The watcher effect is stopped on unmount (`effect` comes from
+ * `@sigx/reactivity` and is NOT lifecycle-scoped — same manual-stop pattern
+ * as lynx-safe-area's provider).
+ */
+export function useKeyboardLiftSV(discountBottomInset = true, offset = 0, 
+/** Tween duration in seconds (lynx-motion convention). */
+duration = 0.25) {
+    const insets = useSafeAreaInsets();
+    const computeLift = (i) => i.keyboard > 0
+        ? Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + offset)
+        : 0;
+    // Seed from the CURRENT insets — a screen that mounts while the keyboard
+    // is already open (modal presented over a focused composer, back-nav to a
+    // focused field) must paint at the lifted position on the first frame,
+    // not animate up from 0. Same "correct on first paint" rule as the
+    // safe-area provider.
+    const initialLift = computeLift(insets.value);
+    const lift = useSharedValue(initialLift);
+    const animateTo = runOnMainThread((target, seconds) => {
+        'main thread';
+        void withTiming(lift, target, { duration: seconds });
+    });
+    // Dedupe by last dispatched target: the inset signal also fires for
+    // changes that don't affect the lift (rotation, status-bar changes, the
+    // mount-time run), and animate() doesn't short-circuit zero-delta tweens
+    // — it would still schedule rAF ticks for the full duration and
+    // cancel/restart any in-flight animation. Seeded with the SharedValue's
+    // initial value so the mount-time run dispatches nothing.
+    let lastTarget = initialLift;
+    const watcher = effect(() => {
+        const target = computeLift(insets.value);
+        if (target === lastTarget)
+            return;
+        lastTarget = target;
+        void animateTo(target, duration);
+    });
+    onUnmounted(() => watcher.stop());
+    return lift;
+}
+//# sourceMappingURL=use-keyboard.js.map

package/dist/use-keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-keyboard.js","sourceRoot":"","sources":["../src/use-keyboard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sigx/lynx-keyboard",
+  "version": "0.4.6",
+  "description": "Soft-keyboard handling for sigx-lynx — KeyboardStickyView, KeyboardAvoidingView and keyboard hooks",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "keywords": [
+    "sigx",
+    "lynx",
+    "keyboard",
+    "keyboard-avoiding",
+    "input-accessory",
+    "ime"
+  ],
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "dependencies": {
+    "@sigx/lynx": "^0.4.6",
+    "@sigx/lynx-motion": "^0.4.6",
+    "@sigx/lynx-safe-area": "^0.4.6"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "@sigx/lynx-plugin": "^0.4.6",
+    "@sigx/lynx-testing": "^0.4.6",
+    "@sigx/lynx-runtime-main": "^0.4.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-keyboard"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-keyboard",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Public API for @sigx/lynx-keyboard.
+//
+// Soft-keyboard handling with an RN-mirroring API. Keyboard height reaches
+// JS through the safe-area bridge (`@sigx/lynx-safe-area`) — this package
+// turns that inset into ready-made layout primitives. Keyboard handling is
+// its own concern, separate from safe-area, mirroring the RN ecosystem
+// (react-native core / react-native-keyboard-controller vs
+// react-native-safe-area-context).
+
+export { KeyboardAvoidingView } from './keyboard-avoiding-view.js';
+export {
+  KeyboardStickyView,
+  // RN aliases: core's InputAccessoryView role is covered by the sticky
+  // view; react-native-keyboard-controller names for the same shape.
+  KeyboardStickyView as KeyboardAccessoryView,
+  KeyboardStickyView as KeyboardToolbar,
+} from './keyboard-sticky-view.js';
+export { useKeyboard, useKeyboardLift, useKeyboardLiftSV } from './use-keyboard.js';
+export type {
+  KeyboardAvoidingBehavior,
+  KeyboardAvoidingViewProps,
+  KeyboardState,
+  KeyboardStickyViewProps,
+} from './types.js';

package/src/keyboard-avoiding-view.tsx

@@ -0,0 +1,59 @@
+import { component } from '@sigx/lynx';
+import { useSafeAreaInsets } from '@sigx/lynx-safe-area';
+import type { KeyboardAvoidingViewProps } from './types.js';
+
+/**
+ * RN-mirroring `KeyboardAvoidingView`: wraps screen content and keeps it
+ * above the soft keyboard. Default `behavior="padding"` squeezes the flex
+ * column so nothing hides behind the keyboard.
+ *
+ * Implementation: BG signal + inline style, the same pattern as
+ * lynx-safe-area's `<SafeAreaView>` — layout-affecting properties must NOT
+ * be driven from the main thread (`setStyleProperties` layout writes fire
+ * after the first layout pass and `<scroll-view>` won't reflow), so the
+ * padding snaps to the final value in one re-render. The native keyboard
+ * slide masks the snap. For a smoothly *animated* bar, use
+ * `<KeyboardStickyView>` (transform-based, MT-animated) instead — and use
+ * one or the other on a given subtree, not both, or it double-lifts.
+ *
+ * The bottom safe-area inset is discounted from the lift
+ * (`max(0, keyboard - bottom + keyboardVerticalOffset)`) because an
+ * ancestor `<SafeAreaView edges={['bottom']}>` typically already pads the
+ * home indicator, which the keyboard covers when open.
+ */
+export const KeyboardAvoidingView = component<KeyboardAvoidingViewProps>(({ props, slots }) => {
+  const insets = useSafeAreaInsets();
+  const behavior = props.behavior ?? 'padding';
+  const kvo = props.keyboardVerticalOffset ?? 0;
+  const discountBottomInset = props.discountBottomInset ?? true;
+
+  return () => {
+    const i = insets.value;
+    const lift = i.keyboard > 0
+      ? Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + kvo)
+      : 0;
+    // Fill-parent defaults, mirroring SafeAreaView: Lynx resolves the
+    // `flex: 1` shorthand with `flexBasis: 'auto'`, which sizes to content
+    // and collapses the chain — long-form `flexBasis: 0` is the only
+    // reliable "fill remaining space".
+    const base: Record<string, string | number> = {
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: 0,
+      minHeight: 0,
+      display: 'flex',
+      flexDirection: 'column',
+    };
+    if (behavior === 'padding') {
+      base['paddingBottom'] = `${lift}px`;
+    } else if (behavior === 'translate') {
+      base['transform'] = `translateY(-${lift}px)`;
+    }
+    return (
+      <view class={props.class} style={props.style ? { ...base, ...props.style } : base}>
+        {slots.default?.()}
+        {behavior === 'height' ? <view style={{ height: `${lift}px`, flexShrink: 0 }} /> : null}
+      </view>
+    );
+  };
+});

package/src/keyboard-sticky-view.tsx

@@ -0,0 +1,76 @@
+import {
+  component,
+  useAnimatedStyle,
+  useMainThreadRef,
+  type MainThread,
+} from '@sigx/lynx';
+import { useKeyboardLift, useKeyboardLiftSV } from './use-keyboard.js';
+import type { KeyboardStickyViewProps } from './types.js';
+
+/**
+ * Pins its children to the top edge of the soft keyboard — the home for a
+ * chat composer / input-accessory toolbar. (RN names: `KeyboardStickyView`
+ * in react-native-keyboard-controller, `InputAccessoryView` in core.)
+ *
+ * The bar flows as a normal bottom flex sibling; when the keyboard opens it
+ * is lifted with `transform: translateY(-lift)` where
+ * `lift = max(0, keyboard - bottomInset + offset)`. Transform doesn't
+ * reflow layout, so (unlike padding/height) it is safe to drive from the
+ * main thread via `useAnimatedStyle` — see lynx-safe-area's
+ * `safe-area-view.tsx` for why MT-driven *layout* writes are a trap.
+ *
+ * Note: because the bar is translated rather than re-laid-out, content
+ * behind it (e.g. the bottom of a message list) does not shrink — it can
+ * sit behind the keyboard. Pair with `<KeyboardAvoidingView
+ * behavior="padding">` around the *content area only* (never around the bar
+ * itself, or it double-lifts) when the content must stay fully visible.
+ *
+ * @example
+ * ```tsx
+ * <Col class="flex-fill">
+ *   <KeyboardAvoidingView behavior="padding">
+ *     <ScrollView class="flex-1">{messages}</ScrollView>
+ *   </KeyboardAvoidingView>
+ *   <KeyboardStickyView>
+ *     <Toolbar />
+ *     <Composer />
+ *   </KeyboardStickyView>
+ * </Col>
+ * ```
+ */
+export const KeyboardStickyView = component<KeyboardStickyViewProps>(({ props, slots }) => {
+  const discountBottomInset = props.discountBottomInset ?? true;
+  const offset = props.offset ?? 0;
+
+  // Hooks register unconditionally (same rule as NavDrawer's backdrop
+  // binding): a runtime `animated` toggle must keep working in both
+  // directions, and a binding created inside `if (animated)` would be
+  // missing after a false→true flip. The reactive accessor form binds /
+  // unbinds the MT transform as the prop changes.
+  const barRef = useMainThreadRef<MainThread.Element | null>(null);
+  const liftSV = useKeyboardLiftSV(discountBottomInset, offset);
+  const liftBG = useKeyboardLift(discountBottomInset, offset);
+  useAnimatedStyle(barRef, () =>
+    (props.animated ?? true)
+      // factor -1: the SV stays a positive height; the mapper negates it so
+      // the bar moves UP.
+      ? { sv: liftSV, mapperName: 'translateY', params: { factor: -1 } }
+      : null);
+
+  return () => {
+    const animated = props.animated ?? true;
+    return (
+      <view
+        main-thread:ref={barRef}
+        class={props.class}
+        // Debug / fallback path (`animated={false}`): discrete BG re-render,
+        // no tween — the MT binding above is unregistered then.
+        style={animated
+          ? props.style
+          : { ...props.style, transform: `translateY(-${liftBG.value}px)` }}
+      >
+        {slots.default?.()}
+      </view>
+    );
+  };
+});

package/src/types.ts

@@ -0,0 +1,55 @@
+import type { Define } from '@sigx/lynx';
+
+/**
+ * RN-mirroring behavior modes for `<KeyboardAvoidingView>`:
+ * - `'padding'`  — add `paddingBottom` equal to the keyboard overlap, squeezing
+ *   the flex column so ALL content stays above the keyboard.
+ * - `'translate'` — shift the whole container up by the overlap (content at the
+ *   top moves off-screen; layout does not reflow).
+ * - `'height'`   — append a trailing spacer view of the overlap height, so
+ *   the content above is squeezed without touching the container's padding.
+ *   (Closest analogue of RN's height-resizing behavior; the implementation
+ *   differs — RN shrinks the container's own height, this inserts a spacer.)
+ */
+export type KeyboardAvoidingBehavior = 'padding' | 'translate' | 'height';
+
+/** BG-reactive keyboard state returned by `useKeyboard()`. */
+export interface KeyboardState {
+  /** Soft-keyboard height in dp; 0 when hidden. */
+  height: number;
+  visible: boolean;
+}
+
+export type KeyboardAvoidingViewProps =
+  & Define.Prop<'behavior', KeyboardAvoidingBehavior, false>
+  & Define.Prop<'keyboardVerticalOffset', number, false>
+  /**
+   * Subtract the bottom safe-area inset from the lift (default `true`).
+   * Keep `true` when an ancestor `<SafeAreaView edges={['bottom']}>` already
+   * pads the home-indicator inset; set `false` to lift by the full keyboard
+   * height when no ancestor applies the bottom inset.
+   */
+  & Define.Prop<'discountBottomInset', boolean, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;
+
+export type KeyboardStickyViewProps =
+  /** Extra gap (dp) between the bar and the keyboard's top edge. */
+  & Define.Prop<'offset', number, false>
+  /**
+   * `true` (default): smooth MT-driven translateY via SharedValue + timing.
+   * `false`: plain BG re-render with an inline transform (debug fallback).
+   */
+  & Define.Prop<'animated', boolean, false>
+  /**
+   * Subtract the bottom safe-area inset from the lift (default `true`).
+   * Keep `true` when an ancestor `<SafeAreaView edges={['bottom']}>` already
+   * pads the home-indicator inset — the keyboard covers that region, so the
+   * bar only needs to rise by the difference. Set `false` if no ancestor
+   * applies the bottom inset.
+   */
+  & Define.Prop<'discountBottomInset', boolean, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;

package/src/use-keyboard.ts

@@ -0,0 +1,106 @@
+import {
+  computed,
+  effect,
+  onUnmounted,
+  runOnMainThread,
+  useSharedValue,
+  type Computed,
+  type SharedValue,
+} from '@sigx/lynx';
+import { useSafeAreaInsets } from '@sigx/lynx-safe-area';
+import { withTiming } from '@sigx/lynx-motion';
+import type { KeyboardState } from './types.js';
+
+/**
+ * BG-reactive soft-keyboard state. The height comes from the safe-area
+ * bridge (`useSafeAreaInsets().value.keyboard`, fed by the native
+ * `safeAreaChanged` event) — Lynx has no separate keyboard event API.
+ * Consumers re-render on keyboard show/hide.
+ *
+ * Must be used under `<SafeAreaProvider>` (same requirement as every
+ * safe-area hook); without one it reads zero insets and warns in dev.
+ */
+export function useKeyboard(): Computed<KeyboardState> {
+  const insets = useSafeAreaInsets();
+  return computed(() => {
+    const height = insets.value.keyboard;
+    return { height, visible: height > 0 };
+  });
+}
+
+/**
+ * BG-reactive "lift" — how far a bottom-anchored bar must rise to clear the
+ * keyboard. `max(0, keyboard - bottomInset + offset)` while the keyboard is
+ * visible, 0 otherwise. The bottom inset is discounted because an ancestor
+ * `<SafeAreaView edges={['bottom']}>` typically already keeps the bar above
+ * the home indicator, and the keyboard covers that region when open.
+ */
+export function useKeyboardLift(
+  discountBottomInset = true,
+  offset = 0,
+): Computed<number> {
+  const insets = useSafeAreaInsets();
+  return computed(() => {
+    const i = insets.value;
+    if (i.keyboard <= 0) return 0;
+    return Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + offset);
+  });
+}
+
+/**
+ * Smoothly animated MT SharedValue tracking the keyboard lift, for
+ * `useAnimatedStyle(ref, sv, 'translateY', { factor: -1 })` bindings.
+ *
+ * The keyboard inset is BG-only (deliberately not a SharedValue in
+ * lynx-safe-area's provider), so this hook is the BG→MT bridge: a BG effect
+ * watches the inset signal and dispatches an MT `withTiming` toward the new
+ * target each time it changes. `withTiming` is itself a `'main thread'`
+ * worklet, so referencing it from the dispatched worklet survives `_c`
+ * capture; the timing loop then runs entirely on MT (no per-frame thread
+ * crossing). The watcher effect is stopped on unmount (`effect` comes from
+ * `@sigx/reactivity` and is NOT lifecycle-scoped — same manual-stop pattern
+ * as lynx-safe-area's provider).
+ */
+export function useKeyboardLiftSV(
+  discountBottomInset = true,
+  offset = 0,
+  /** Tween duration in seconds (lynx-motion convention). */
+  duration = 0.25,
+): SharedValue<number> {
+  const insets = useSafeAreaInsets();
+
+  const computeLift = (i: { keyboard: number; bottom: number }): number =>
+    i.keyboard > 0
+      ? Math.max(0, i.keyboard - (discountBottomInset ? i.bottom : 0) + offset)
+      : 0;
+
+  // Seed from the CURRENT insets — a screen that mounts while the keyboard
+  // is already open (modal presented over a focused composer, back-nav to a
+  // focused field) must paint at the lifted position on the first frame,
+  // not animate up from 0. Same "correct on first paint" rule as the
+  // safe-area provider.
+  const initialLift = computeLift(insets.value);
+  const lift = useSharedValue(initialLift);
+
+  const animateTo = runOnMainThread((target: number, seconds: number) => {
+    'main thread';
+    void withTiming(lift, target, { duration: seconds });
+  });
+
+  // Dedupe by last dispatched target: the inset signal also fires for
+  // changes that don't affect the lift (rotation, status-bar changes, the
+  // mount-time run), and animate() doesn't short-circuit zero-delta tweens
+  // — it would still schedule rAF ticks for the full duration and
+  // cancel/restart any in-flight animation. Seeded with the SharedValue's
+  // initial value so the mount-time run dispatches nothing.
+  let lastTarget = initialLift;
+  const watcher = effect(() => {
+    const target = computeLift(insets.value);
+    if (target === lastTarget) return;
+    lastTarget = target;
+    void animateTo(target, duration);
+  });
+  onUnmounted(() => watcher.stop());
+
+  return lift;
+}