@mieweb/ui 0.10.0-dev.16 → 0.10.0-dev.18

package/dist/hooks/index.d.cts

@@ -226,6 +226,19 @@ declare const VISUAL_VIEWPORT_HEIGHT_VAR = "--mieweb-visual-viewport-height";
 declare const VISUAL_VIEWPORT_OFFSET_TOP_VAR = "--mieweb-visual-viewport-offset-top";
 /** Boolean attribute set on `<html>` while an on-screen keyboard is open. */
 declare const KEYBOARD_OPEN_ATTRIBUTE = "data-keyboard-open";
+/** Attribute on `<html>` naming the active {@link KeyboardInsetSource}. */
+declare const KEYBOARD_SOURCE_ATTRIBUTE = "data-keyboard-source";
+/**
+ * Where keyboard metrics come from.
+ *
+ * - `'visual-viewport'` — the Visual Viewport API. Works in any browser, but
+ *   iOS only reports the keyboard once its slide-in animation has finished.
+ * - `'native'` — `keyboardWillShow` / `keyboardWillHide` window events with a
+ *   `keyboardHeight` property, as fired by `cordova-plugin-ionic-keyboard` and
+ *   Capacitor's Keyboard plugin. They arrive *before* the keyboard animates,
+ *   so layout can move in step with it.
+ */
+type KeyboardInsetSource = 'visual-viewport' | 'native';
 interface KeyboardInsetState {
     /** Pixels of the layout viewport covered by the on-screen keyboard. */
     keyboardInset: number;
@@ -235,9 +248,26 @@ interface KeyboardInsetState {
 interface UseKeyboardInsetOptions {
     /** Track the keyboard; `false` stops tracking and clears the CSS variables. @default true */
     enabled?: boolean;
+    /** Where keyboard metrics come from. @default 'visual-viewport' */
+    source?: KeyboardInsetSource;
 }
 /**
- * Tracks the on-screen keyboard via the Visual Viewport API.
+ * Tracks the on-screen keyboard and publishes it on `<html>`.
+ *
+ * ### `source: 'native'` (Cordova / Capacitor apps)
+ *
+ * Listens for the native keyboard plugin's `keyboardWillShow` /
+ * `keyboardWillHide` window events. Configure the plugin so the WebView is
+ * neither resized nor panned (for `cordova-plugin-ionic-keyboard`:
+ * `KeyboardResize=false`), keep the app shell at full height, and move only
+ * the composer dock by `--mieweb-keyboard-inset` with a short transition
+ * (~250ms) so it rides up with the keyboard. Only `--mieweb-keyboard-inset`,
+ * `data-keyboard-open` and `data-keyboard-source` are published; the
+ * visual-viewport variables stay unset.
+ *
+ * ### `source: 'visual-viewport'` (browsers, default)
+ *
+ * Uses the Visual Viewport API.
  *
  * iOS Safari and WKWebView (Cordova) ignore
  * `interactive-widget=resizes-content`, and `dvh` does not shrink for the
@@ -255,6 +285,10 @@ interface UseKeyboardInsetOptions {
  * Android with `interactive-widget=resizes-content`) the inset stays 0 and
  * the variables simply mirror the layout viewport.
  *
+ * iOS reports the visual viewport only after the keyboard has finished
+ * animating, so a shell sized this way snaps into place once the keyboard
+ * lands. Prefer `source: 'native'` wherever a native keyboard plugin exists.
+ *
  * Mount it once, near the app root.
  *
  * @example
@@ -273,6 +307,23 @@ interface UseKeyboardInsetOptions {
  *   );
  * }
  * ```
+ *
+ * @example Native app (keyboard plugin with WebView resizing disabled)
+ * ```tsx
+ * function ComposerDock({ children }) {
+ *   useKeyboardInset({ source: 'native' });
+ *   return (
+ *     <div
+ *       style={{
+ *         paddingBottom: 'calc(var(--mieweb-keyboard-inset, 0px) + 0.5rem)',
+ *         transition: 'padding-bottom 250ms ease',
+ *       }}
+ *     >
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare function useKeyboardInset(options?: UseKeyboardInsetOptions): KeyboardInsetState;
 
@@ -952,4 +1003,4 @@ interface UseTranscriptEditsResult {
  */
 declare function useTranscriptEdits(options: UseTranscriptEditsOptions): UseTranscriptEditsResult;
 
-export { type AnchoredPlacement, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type FillerAnalysis, type HoverPreviewState, KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, type KeyboardInsetState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseKeyboardInsetOptions, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtlLocale, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useYouTubeHoverPreview };
+export { type AnchoredPlacement, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type FillerAnalysis, type HoverPreviewState, KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, KEYBOARD_SOURCE_ATTRIBUTE, type KeyboardInsetSource, type KeyboardInsetState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseKeyboardInsetOptions, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtlLocale, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useYouTubeHoverPreview };

package/dist/hooks/index.d.ts

@@ -226,6 +226,19 @@ declare const VISUAL_VIEWPORT_HEIGHT_VAR = "--mieweb-visual-viewport-height";
 declare const VISUAL_VIEWPORT_OFFSET_TOP_VAR = "--mieweb-visual-viewport-offset-top";
 /** Boolean attribute set on `<html>` while an on-screen keyboard is open. */
 declare const KEYBOARD_OPEN_ATTRIBUTE = "data-keyboard-open";
+/** Attribute on `<html>` naming the active {@link KeyboardInsetSource}. */
+declare const KEYBOARD_SOURCE_ATTRIBUTE = "data-keyboard-source";
+/**
+ * Where keyboard metrics come from.
+ *
+ * - `'visual-viewport'` — the Visual Viewport API. Works in any browser, but
+ *   iOS only reports the keyboard once its slide-in animation has finished.
+ * - `'native'` — `keyboardWillShow` / `keyboardWillHide` window events with a
+ *   `keyboardHeight` property, as fired by `cordova-plugin-ionic-keyboard` and
+ *   Capacitor's Keyboard plugin. They arrive *before* the keyboard animates,
+ *   so layout can move in step with it.
+ */
+type KeyboardInsetSource = 'visual-viewport' | 'native';
 interface KeyboardInsetState {
     /** Pixels of the layout viewport covered by the on-screen keyboard. */
     keyboardInset: number;
@@ -235,9 +248,26 @@ interface KeyboardInsetState {
 interface UseKeyboardInsetOptions {
     /** Track the keyboard; `false` stops tracking and clears the CSS variables. @default true */
     enabled?: boolean;
+    /** Where keyboard metrics come from. @default 'visual-viewport' */
+    source?: KeyboardInsetSource;
 }
 /**
- * Tracks the on-screen keyboard via the Visual Viewport API.
+ * Tracks the on-screen keyboard and publishes it on `<html>`.
+ *
+ * ### `source: 'native'` (Cordova / Capacitor apps)
+ *
+ * Listens for the native keyboard plugin's `keyboardWillShow` /
+ * `keyboardWillHide` window events. Configure the plugin so the WebView is
+ * neither resized nor panned (for `cordova-plugin-ionic-keyboard`:
+ * `KeyboardResize=false`), keep the app shell at full height, and move only
+ * the composer dock by `--mieweb-keyboard-inset` with a short transition
+ * (~250ms) so it rides up with the keyboard. Only `--mieweb-keyboard-inset`,
+ * `data-keyboard-open` and `data-keyboard-source` are published; the
+ * visual-viewport variables stay unset.
+ *
+ * ### `source: 'visual-viewport'` (browsers, default)
+ *
+ * Uses the Visual Viewport API.
  *
  * iOS Safari and WKWebView (Cordova) ignore
  * `interactive-widget=resizes-content`, and `dvh` does not shrink for the
@@ -255,6 +285,10 @@ interface UseKeyboardInsetOptions {
  * Android with `interactive-widget=resizes-content`) the inset stays 0 and
  * the variables simply mirror the layout viewport.
  *
+ * iOS reports the visual viewport only after the keyboard has finished
+ * animating, so a shell sized this way snaps into place once the keyboard
+ * lands. Prefer `source: 'native'` wherever a native keyboard plugin exists.
+ *
  * Mount it once, near the app root.
  *
  * @example
@@ -273,6 +307,23 @@ interface UseKeyboardInsetOptions {
  *   );
  * }
  * ```
+ *
+ * @example Native app (keyboard plugin with WebView resizing disabled)
+ * ```tsx
+ * function ComposerDock({ children }) {
+ *   useKeyboardInset({ source: 'native' });
+ *   return (
+ *     <div
+ *       style={{
+ *         paddingBottom: 'calc(var(--mieweb-keyboard-inset, 0px) + 0.5rem)',
+ *         transition: 'padding-bottom 250ms ease',
+ *       }}
+ *     >
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare function useKeyboardInset(options?: UseKeyboardInsetOptions): KeyboardInsetState;
 
@@ -952,4 +1003,4 @@ interface UseTranscriptEditsResult {
  */
 declare function useTranscriptEdits(options: UseTranscriptEditsOptions): UseTranscriptEditsResult;
 
-export { type AnchoredPlacement, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type FillerAnalysis, type HoverPreviewState, KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, type KeyboardInsetState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseKeyboardInsetOptions, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtlLocale, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useYouTubeHoverPreview };
+export { type AnchoredPlacement, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type FillerAnalysis, type HoverPreviewState, KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, KEYBOARD_SOURCE_ATTRIBUTE, type KeyboardInsetSource, type KeyboardInsetState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseKeyboardInsetOptions, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtlLocale, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useYouTubeHoverPreview };

package/dist/hooks/index.js

@@ -1,4 +1,4 @@
-export { KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, RTL_LOCALES, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, isRtlLocale, useCommandK, useDirection, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useMediaQuery } from '../chunk-LENW5YOC.js';
+export { KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, KEYBOARD_SOURCE_ATTRIBUTE, RTL_LOCALES, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, isRtlLocale, useCommandK, useDirection, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useMediaQuery } from '../chunk-GBUVIGD5.js';
 export { useYouTubeHoverPreview } from '../chunk-POWS35OT.js';
 export { useTheme } from '../chunk-KJZNEVYM.js';
 export { useStickToBottom, useStreamEndedBelowFold } from '../chunk-BM35CACB.js';