@livx.cc/native-kit 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -12,6 +12,7 @@ import { DeviceModule } from '../modules/device';
 import { GeoModule } from '../modules/geo';
 import { HapticsModule } from '../modules/haptics';
 import { HealthModule } from '../modules/health';
+import { KeyboardModule } from '../modules/keyboard';
 import { LifecycleModule } from '../modules/lifecycle';
 import { MediaModule } from '../modules/media';
 import { MotionModule } from '../modules/motion';
@@ -70,6 +71,7 @@ export class NativeKit {
   public readonly haptics = new HapticsModule(this);
   public readonly share = new ShareModule(this);
   public readonly screen = new ScreenModule(this);
+  public readonly keyboard = new KeyboardModule(this);
   public readonly storage = new StorageModule(this);
   public readonly toast = new ToastModule(this);
   public readonly ui = new UiModule(this);

package/src/core/web-adapter.ts

@@ -54,6 +54,7 @@ export class WebAdapter implements NativeKitAdapter {
       photos: 'web',
       network: 'web',
       screen: 'wakeLock' in n ? 'web' : 'none',
+      keyboard: (window as any).visualViewport ? 'web' : 'none', // VisualViewport resize ≈ keyboard show/hide
       dialogs: 'web',
       reviews: 'none',
       themeColor: 'web', // the browser honors <meta name="theme-color"> itself
@@ -180,6 +181,11 @@ export class WebAdapter implements NativeKitAdapter {
       case 'screen.orientation.current':
         return (((screen as any)?.orientation?.type ?? '').startsWith('landscape') ? 'landscape' : 'portrait') as T;
 
+      case 'keyboard.hide':
+        // No programmatic IME on web — blurring the focused field dismisses it.
+        (document.activeElement as HTMLElement | null)?.blur?.();
+        return undefined as T;
+
       case 'reviews.requestReview':
         throw new KitError('UNSUPPORTED', 'No in-app review prompt on web');
 
@@ -371,6 +377,22 @@ export class WebAdapter implements NativeKitAdapter {
       so.addEventListener('change', fire);
       return () => so.removeEventListener('change', fire);
     }
+    if (event === 'keyboard.show' || event === 'keyboard.hide') {
+      const vv = (window as any).visualViewport;
+      if (!vv) return () => {};
+      let shown = false;
+      const onResize = () => {
+        // The keyboard shrinks the visual viewport; the hidden band ≈ its height.
+        const height = Math.max(0, window.innerHeight - vv.height - vv.offsetTop);
+        const nowShown = height > 120; // threshold filters URL-bar/toolbar resizes
+        if (nowShown === shown) return;
+        shown = nowShown;
+        if (event === 'keyboard.show' && nowShown) cb({ height: Math.round(height) });
+        if (event === 'keyboard.hide' && !nowShown) cb(undefined);
+      };
+      vv.addEventListener('resize', onResize);
+      return () => vv.removeEventListener('resize', onResize);
+    }
     if (event === 'app.pause' || event === 'app.resume') {
       const handler = () => {
         const paused = document.visibilityState === 'hidden';

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
 export type { ImpactStyle, NotifyType } from './modules/haptics';
 export type { SharePayload, ShareFile } from './modules/share';
 export type { Orientation, OrientationLock } from './modules/screen';
+export type { KeyboardInfo } from './modules/keyboard';
 export type { DeviceInfo } from './modules/device';
 export type { ScheduleOptions } from './modules/notifications';
 export type { PushMessage, PushPlatform, PushToken } from './modules/push';

package/src/modules/keyboard.ts

@@ -0,0 +1,44 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/** Payload of {@link KeyboardModule.onShow}: the on-screen keyboard's height in CSS pixels,
+ *  so the page can pad/scroll content above it. */
+export interface KeyboardInfo {
+  /** Keyboard height in CSS px (0 when unknown). */
+  height: number;
+}
+
+/**
+ * Software-keyboard control + observation — ONE API across platforms.
+ *
+ * The classic webview pain: the keyboard slides up and covers the focused input.
+ * Native emits `show` with the keyboard height (CSS px) and `hide`, so the page can
+ * lift content above it; `hide()` dismisses the keyboard programmatically.
+ *
+ * Native (iOS `UIKeyboardWillShow/Hide`, Android global-layout/IME insets) reports
+ * `capability === 'native'`. Web maps to the VisualViewport API where present
+ * (`'web'`), else `'none'`. Branch on {@link capability}, not try/catch.
+ */
+export class KeyboardModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where VisualViewport exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('keyboard');
+  }
+
+  /** Dismiss the software keyboard (resign first responder / hide the IME). */
+  hide(): Promise<void> {
+    return this.kit.invoke('keyboard.hide');
+  }
+
+  /** Keyboard shown — payload carries its height in CSS pixels. */
+  onShow(cb: (info: KeyboardInfo) => void): Unsubscribe {
+    return this.kit.on('keyboard.show', (p) => cb(p as KeyboardInfo));
+  }
+
+  /** Keyboard dismissed. */
+  onHide(cb: () => void): Unsubscribe {
+    return this.kit.on('keyboard.hide', () => cb());
+  }
+}