@velion-la/onboarding-sdk-react-native 1.1.0-beta.2 → 1.1.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +40 -0
  2. package/lib/commonjs/steps/AddressInfoStep.js +41 -13
  3. package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
  4. package/lib/commonjs/steps/DocumentsOcrStep.js +37 -31
  5. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  6. package/lib/commonjs/steps/EconomicActivityStep.js +53 -52
  7. package/lib/commonjs/steps/EconomicActivityStep.js.map +1 -1
  8. package/lib/commonjs/ui/ScreenScaffold.js +99 -0
  9. package/lib/commonjs/ui/ScreenScaffold.js.map +1 -0
  10. package/lib/commonjs/ui/StepShell.js +23 -42
  11. package/lib/commonjs/ui/StepShell.js.map +1 -1
  12. package/lib/commonjs/ui/VelionOnboardingScreen.js +13 -10
  13. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  14. package/lib/commonjs/ui/forms/index.js +7 -0
  15. package/lib/commonjs/ui/forms/index.js.map +1 -1
  16. package/lib/commonjs/ui/forms/useFieldChain.js +56 -0
  17. package/lib/commonjs/ui/forms/useFieldChain.js.map +1 -0
  18. package/lib/commonjs/ui/keyboard.js +147 -0
  19. package/lib/commonjs/ui/keyboard.js.map +1 -0
  20. package/lib/commonjs/ui/screenInsets.js +67 -0
  21. package/lib/commonjs/ui/screenInsets.js.map +1 -0
  22. package/lib/module/steps/AddressInfoStep.js +41 -13
  23. package/lib/module/steps/AddressInfoStep.js.map +1 -1
  24. package/lib/module/steps/DocumentsOcrStep.js +37 -31
  25. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  26. package/lib/module/steps/EconomicActivityStep.js +54 -53
  27. package/lib/module/steps/EconomicActivityStep.js.map +1 -1
  28. package/lib/module/ui/ScreenScaffold.js +94 -0
  29. package/lib/module/ui/ScreenScaffold.js.map +1 -0
  30. package/lib/module/ui/StepShell.js +24 -43
  31. package/lib/module/ui/StepShell.js.map +1 -1
  32. package/lib/module/ui/VelionOnboardingScreen.js +13 -10
  33. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  34. package/lib/module/ui/forms/index.js +1 -0
  35. package/lib/module/ui/forms/index.js.map +1 -1
  36. package/lib/module/ui/forms/useFieldChain.js +52 -0
  37. package/lib/module/ui/forms/useFieldChain.js.map +1 -0
  38. package/lib/module/ui/keyboard.js +143 -0
  39. package/lib/module/ui/keyboard.js.map +1 -0
  40. package/lib/module/ui/screenInsets.js +61 -0
  41. package/lib/module/ui/screenInsets.js.map +1 -0
  42. package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
  43. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  44. package/lib/typescript/steps/EconomicActivityStep.d.ts.map +1 -1
  45. package/lib/typescript/ui/ScreenScaffold.d.ts +57 -0
  46. package/lib/typescript/ui/ScreenScaffold.d.ts.map +1 -0
  47. package/lib/typescript/ui/StepShell.d.ts +1 -3
  48. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  49. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  50. package/lib/typescript/ui/forms/index.d.ts +1 -0
  51. package/lib/typescript/ui/forms/index.d.ts.map +1 -1
  52. package/lib/typescript/ui/forms/useFieldChain.d.ts +30 -0
  53. package/lib/typescript/ui/forms/useFieldChain.d.ts.map +1 -0
  54. package/lib/typescript/ui/keyboard.d.ts +69 -0
  55. package/lib/typescript/ui/keyboard.d.ts.map +1 -0
  56. package/lib/typescript/ui/screenInsets.d.ts +68 -0
  57. package/lib/typescript/ui/screenInsets.d.ts.map +1 -0
  58. package/package.json +5 -1
  59. package/src/steps/AddressInfoStep.tsx +37 -0
  60. package/src/steps/DocumentsOcrStep.tsx +50 -36
  61. package/src/steps/EconomicActivityStep.tsx +54 -44
  62. package/src/ui/ScreenScaffold.tsx +130 -0
  63. package/src/ui/StepShell.tsx +27 -56
  64. package/src/ui/VelionOnboardingScreen.tsx +16 -13
  65. package/src/ui/forms/index.ts +1 -0
  66. package/src/ui/forms/useFieldChain.ts +63 -0
  67. package/src/ui/keyboard.tsx +196 -0
  68. package/src/ui/screenInsets.ts +89 -0
@@ -0,0 +1,130 @@
1
+ /**
2
+ * @fileoverview The one place that owns safe-area chrome for a full-screen
3
+ * surface (OSDKR-14).
4
+ *
5
+ * Every screen in the flow is edge-to-edge: the content fills the window and
6
+ * the system bars are drawn over it. Getting that right means padding the
7
+ * chrome — never the content — by the device insets, and screens that rolled
8
+ * their own layout kept forgetting to (CTAs ended up under the Android
9
+ * navigation bar, "back" controls under the status bar and the ProgressBar).
10
+ *
11
+ * `ScreenScaffold` makes that structural instead of a thing to remember:
12
+ *
13
+ * ┌──────────────────────────┐
14
+ * │ header (padded by topChrome: status bar + ProgressBar)
15
+ * ├──────────────────────────┤
16
+ * │ children (flex, untouched — cameras/maps stay full-bleed)
17
+ * ├──────────────────────────┤
18
+ * │ footer (padded by the bottom inset, lifted over the keyboard)
19
+ * └──────────────────────────┘
20
+ *
21
+ * `StepShell` is the scrollable variant built on top of this — form steps go
22
+ * through it. Screens with a pinned CTA (a list plus "Continuar", a capture
23
+ * preview plus its actions) use the scaffold directly with a `footer`.
24
+ */
25
+
26
+ import type { ReactNode } from 'react';
27
+ import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
28
+ import { useTheme } from './theme';
29
+ import { PROGRESS_BAR_HEIGHT } from './overlays/ProgressBar';
30
+ import { useKeyboardHeight } from './keyboard';
31
+ import {
32
+ bottomChromeInset,
33
+ computeScreenInsets,
34
+ type ScreenInsets,
35
+ } from './screenInsets';
36
+ import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
37
+
38
+ /** Horizontal gutter shared by the header, footer and (by default) content. */
39
+ export const SCREEN_GUTTER = 18;
40
+ /** Gap between the content and a pinned footer. */
41
+ const FOOTER_TOP_GAP = 12;
42
+
43
+ /**
44
+ * Chrome insets for the current screen. Prefer `<ScreenScaffold>`; reach for
45
+ * the hook directly only when a screen positions chrome absolutely over a
46
+ * full-bleed surface (the camera overlays do).
47
+ */
48
+ export function useScreenInsets(): ScreenInsets {
49
+ const raw = useSafeAreaInsets();
50
+ return computeScreenInsets(raw, PROGRESS_BAR_HEIGHT);
51
+ }
52
+
53
+ export interface ScreenScaffoldProps {
54
+ children: ReactNode;
55
+ /**
56
+ * Chrome pinned to the top, below the ProgressBar — typically a back
57
+ * control. Padded so it can never overlap the status bar or the bar itself.
58
+ */
59
+ header?: ReactNode | undefined;
60
+ /**
61
+ * Chrome pinned to the bottom — typically the step's CTA row. Padded clear
62
+ * of the navigation bar / home indicator, and lifted above the keyboard
63
+ * while it is open.
64
+ */
65
+ footer?: ReactNode | undefined;
66
+ /** Horizontal padding for header, footer and content. Defaults to 18. */
67
+ gutter?: number | undefined;
68
+ /** Extra style for the content area (between header and footer). */
69
+ contentStyle?: StyleProp<ViewStyle> | undefined;
70
+ /** Paint the theme background behind the screen. Defaults to `true`. */
71
+ opaque?: boolean | undefined;
72
+ }
73
+
74
+ export function ScreenScaffold({
75
+ children,
76
+ header,
77
+ footer,
78
+ gutter = SCREEN_GUTTER,
79
+ contentStyle,
80
+ opaque = true,
81
+ }: ScreenScaffoldProps) {
82
+ const theme = useTheme();
83
+ const insets = useScreenInsets();
84
+ const keyboardHeight = useKeyboardHeight();
85
+
86
+ return (
87
+ <View
88
+ style={[
89
+ styles.root,
90
+ opaque ? { backgroundColor: theme.backgroundColor } : null,
91
+ ]}
92
+ >
93
+ {header ? (
94
+ <View
95
+ style={{ paddingTop: insets.topChrome, paddingHorizontal: gutter }}
96
+ >
97
+ {header}
98
+ </View>
99
+ ) : null}
100
+
101
+ <View style={[styles.content, contentStyle]}>{children}</View>
102
+
103
+ {footer ? (
104
+ <View
105
+ style={[
106
+ styles.footer,
107
+ {
108
+ paddingHorizontal: gutter,
109
+ paddingBottom: bottomChromeInset(insets, keyboardHeight),
110
+ },
111
+ ]}
112
+ >
113
+ {footer}
114
+ </View>
115
+ ) : null}
116
+ </View>
117
+ );
118
+ }
119
+
120
+ const styles = StyleSheet.create({
121
+ root: {
122
+ flex: 1,
123
+ },
124
+ content: {
125
+ flex: 1,
126
+ },
127
+ footer: {
128
+ paddingTop: FOOTER_TOP_GAP,
129
+ },
130
+ });
@@ -8,14 +8,7 @@
8
8
 
9
9
  import type { ReactNode } from 'react';
10
10
  import { useRef } from 'react';
11
- import {
12
- Animated,
13
- KeyboardAvoidingView,
14
- Platform,
15
- StyleSheet,
16
- Text,
17
- View,
18
- } from 'react-native';
11
+ import { Animated, StyleSheet, Text, View } from 'react-native';
19
12
  import Svg, {
20
13
  Defs,
21
14
  LinearGradient as SvgLinearGradient,
@@ -24,8 +17,8 @@ import Svg, {
24
17
  } from 'react-native-svg';
25
18
  import { useTheme, withAlpha } from './theme';
26
19
  import { BackButton } from './primitives/BackButton';
27
- import { PROGRESS_BAR_HEIGHT } from './overlays/ProgressBar';
28
- import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
20
+ import { FormScrollView } from './keyboard';
21
+ import { ScreenScaffold, useScreenInsets } from './ScreenScaffold';
29
22
 
30
23
  export interface StepShellProps {
31
24
  title: string;
@@ -33,8 +26,6 @@ export interface StepShellProps {
33
26
  /** Optional icon-bearing element (e.g. SVG). Falls back to a colored disc. */
34
27
  iconNode?: ReactNode | undefined;
35
28
  children: ReactNode;
36
- /** When true, the body is wrapped in a `KeyboardAvoidingView` (form-friendly). */
37
- avoidKeyboard?: boolean | undefined;
38
29
  /**
39
30
  * When provided, renders a top-left "back" (chevron) control. Only reversible
40
31
  * steps wire this — the orchestrator decides based on the backend's
@@ -52,13 +43,12 @@ export function StepShell({
52
43
  subtitle,
53
44
  iconNode,
54
45
  children,
55
- avoidKeyboard = true,
56
46
  onBack,
57
47
  backLabel = 'Atrás',
58
48
  backDisabled = false,
59
49
  }: StepShellProps) {
60
50
  const theme = useTheme();
61
- const insets = useSafeAreaInsets();
51
+ const insets = useScreenInsets();
62
52
 
63
53
  const showIconCircle = !theme.hideStepIcons && iconNode != null;
64
54
  const showBack = onBack != null;
@@ -74,27 +64,29 @@ export function StepShell({
74
64
  });
75
65
 
76
66
  const scroll = (
77
- <Animated.ScrollView
67
+ <FormScrollView
78
68
  style={styles.scroll}
79
69
  scrollEventThrottle={16}
80
70
  onScroll={Animated.event(
81
71
  [{ nativeEvent: { contentOffset: { y: scrollY } } }],
82
72
  { useNativeDriver: true },
83
73
  )}
84
- // When the fixed back strip is present it already clears the status bar +
85
- // progress bar, so the scroll body only needs its base top padding.
86
- // Without it, add the device safe-area insets so the header (icon + title)
87
- // clears the top camera / notch. The bottom inset always clears the
88
- // navigation bar / gesture area on edge-to-edge Android and on iOS devices
89
- // with a home indicator.
74
+ // When the fixed back strip is present the scaffold already cleared the
75
+ // status bar + progress bar, so the scroll body only needs its base top
76
+ // padding. Without it, the header (icon + title) has to clear that chrome
77
+ // itself. The bottom inset always clears the navigation bar / gesture
78
+ // area on edge-to-edge Android and the home indicator on iOS.
90
79
  contentContainerStyle={[
91
80
  styles.scrollBody,
92
81
  {
93
- paddingTop: showBack ? BASE_PADDING_TOP : BASE_PADDING_TOP + insets.top,
94
- paddingBottom: BASE_PADDING_BOTTOM + insets.bottom,
82
+ paddingTop: showBack
83
+ ? BASE_PADDING_TOP
84
+ : BASE_PADDING_TOP + insets.topChrome,
95
85
  },
96
86
  ]}
87
+ contentPaddingBottom={BASE_PADDING_BOTTOM + insets.bottom}
97
88
  keyboardShouldPersistTaps="handled"
89
+ keyboardDismissMode="on-drag"
98
90
  >
99
91
  <View style={styles.header}>
100
92
  {showIconCircle ? (
@@ -122,29 +114,26 @@ export function StepShell({
122
114
  ) : null}
123
115
  </View>
124
116
  <View style={styles.column}>{children}</View>
125
- </Animated.ScrollView>
117
+ </FormScrollView>
126
118
  );
127
119
 
128
120
  // The back control lives in a fixed strip OUTSIDE the ScrollView so it stays
129
121
  // pinned just below the (fixed) ProgressBar while the form scrolls behind it.
130
- // `paddingTop` clears the status-bar / notch inset plus the progress bar's
131
- // own height so "Atrás" never tucks under the bar (OSDKR-12).
132
- const body = (
133
- <View style={styles.flex}>
134
- {showBack ? (
135
- <View
136
- style={[
137
- styles.backStrip,
138
- { paddingTop: insets.top + PROGRESS_BAR_HEIGHT },
139
- ]}
140
- >
122
+ // `ScreenScaffold` pads that strip clear of the status bar / notch and of the
123
+ // progress bar's own height, so "Atrás" never tucks under either (OSDKR-12,
124
+ // OSDKR-14).
125
+ return (
126
+ <ScreenScaffold
127
+ header={
128
+ showBack ? (
141
129
  <BackButton
142
130
  label={backLabel}
143
131
  onPress={onBack}
144
132
  disabled={backDisabled}
145
133
  />
146
- </View>
147
- ) : null}
134
+ ) : undefined
135
+ }
136
+ >
148
137
  <View style={styles.scrollWrap}>
149
138
  {scroll}
150
139
  {/* Soft top fade: the ScrollView hard-clips content at its top edge,
@@ -181,20 +170,8 @@ export function StepShell({
181
170
  </Svg>
182
171
  </Animated.View>
183
172
  </View>
184
- </View>
173
+ </ScreenScaffold>
185
174
  );
186
-
187
- if (avoidKeyboard) {
188
- return (
189
- <KeyboardAvoidingView
190
- style={styles.flex}
191
- behavior={Platform.OS === 'ios' ? 'padding' : undefined}
192
- >
193
- {body}
194
- </KeyboardAvoidingView>
195
- );
196
- }
197
- return body;
198
175
  }
199
176
 
200
177
  // Base vertical padding for the scroll body. Safe-area insets are added on top
@@ -211,9 +188,6 @@ const TOP_FADE_HEIGHT = 120;
211
188
  const FADE_RAMP_DISTANCE = 36;
212
189
 
213
190
  const styles = StyleSheet.create({
214
- flex: {
215
- flex: 1,
216
- },
217
191
  scroll: {
218
192
  flex: 1,
219
193
  },
@@ -226,9 +200,6 @@ const styles = StyleSheet.create({
226
200
  left: 0,
227
201
  right: 0,
228
202
  },
229
- backStrip: {
230
- paddingHorizontal: 18,
231
- },
232
203
  scrollBody: {
233
204
  paddingHorizontal: 18,
234
205
  paddingTop: BASE_PADDING_TOP,
@@ -31,7 +31,8 @@ import {
31
31
  activateScreenKeepAwake,
32
32
  deactivateScreenKeepAwake,
33
33
  } from '../utils/keepAwake';
34
- import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
34
+ import { KeyboardBoundary } from './keyboard';
35
+ import { useScreenInsets } from './ScreenScaffold';
35
36
 
36
37
  /**
37
38
  * Mounts `react-native-safe-area-context`'s `SafeAreaProvider` so descendant
@@ -91,17 +92,19 @@ export function VelionOnboardingScreen({
91
92
  }: VelionOnboardingScreenProps) {
92
93
  return (
93
94
  <SafeAreaBoundary>
94
- <ThemeProvider
95
- themeOverrides={config.theme}
96
- colorMode={config.colorMode ?? 'auto'}
97
- >
98
- <VelionOnboardingInner
99
- config={config}
100
- onComplete={onComplete}
101
- onFail={onFail}
102
- onExit={onExit}
103
- />
104
- </ThemeProvider>
95
+ <KeyboardBoundary>
96
+ <ThemeProvider
97
+ themeOverrides={config.theme}
98
+ colorMode={config.colorMode ?? 'auto'}
99
+ >
100
+ <VelionOnboardingInner
101
+ config={config}
102
+ onComplete={onComplete}
103
+ onFail={onFail}
104
+ onExit={onExit}
105
+ />
106
+ </ThemeProvider>
107
+ </KeyboardBoundary>
105
108
  </SafeAreaBoundary>
106
109
  );
107
110
  }
@@ -113,7 +116,7 @@ function VelionOnboardingInner({
113
116
  onExit,
114
117
  }: VelionOnboardingScreenProps) {
115
118
  const theme = useTheme();
116
- const insets = useSafeAreaInsets();
119
+ const insets = useScreenInsets();
117
120
  const t = getStrings(config.locale);
118
121
  const [state, setState] = useState<ViewState>(INITIAL_STATE);
119
122
  const [progress, setProgress] = useState(0);
@@ -10,3 +10,4 @@ export {
10
10
  compose,
11
11
  type FieldValidator,
12
12
  } from './validators';
13
+ export { useFieldChain, type FieldChainProps } from './useFieldChain';
@@ -0,0 +1,63 @@
1
+ /**
2
+ * @fileoverview "Next field" chaining for multi-input forms (OSDKR-14).
3
+ *
4
+ * On a long form the keyboard's action key should walk the user down the form
5
+ * instead of just closing: tapping it on "Street" focuses "Number", and the
6
+ * scroll follows the focused input. Only the last field dismisses the keyboard,
7
+ * which is what puts the submit button back in reach — including on a
8
+ * `multiline` field, where the default Android behaviour is to insert a
9
+ * newline and leave the user stuck behind the keyboard.
10
+ *
11
+ * Usage — declare the visual order once, as a module constant so the returned
12
+ * callback stays stable across renders:
13
+ *
14
+ * ```ts
15
+ * const FIELDS = ['street', 'number', 'zip'] as const;
16
+ * const { field } = useFieldChain(FIELDS);
17
+ * <Input {...field('street')} … />
18
+ * ```
19
+ */
20
+
21
+ import { useCallback, useRef } from 'react';
22
+ import { Keyboard, type TextInput, type TextInputProps } from 'react-native';
23
+
24
+ export interface FieldChainProps {
25
+ ref: (node: TextInput | null) => void;
26
+ returnKeyType: TextInputProps['returnKeyType'];
27
+ submitBehavior: TextInputProps['submitBehavior'];
28
+ onSubmitEditing: () => void;
29
+ }
30
+
31
+ export function useFieldChain<K extends string>(
32
+ order: readonly K[],
33
+ ): { field: (key: K) => FieldChainProps } {
34
+ const refs = useRef<Partial<Record<K, TextInput | null>>>({});
35
+
36
+ const field = useCallback(
37
+ (key: K): FieldChainProps => {
38
+ const index = order.indexOf(key);
39
+ const next = index >= 0 ? order[index + 1] : undefined;
40
+
41
+ return {
42
+ ref: (node: TextInput | null) => {
43
+ refs.current[key] = node;
44
+ },
45
+ returnKeyType: next ? 'next' : 'done',
46
+ // `submit` keeps focus so we can move it ourselves; `blurAndSubmit`
47
+ // closes the keyboard on the last field (and overrides the newline
48
+ // default on `multiline` inputs).
49
+ submitBehavior: next ? 'submit' : 'blurAndSubmit',
50
+ onSubmitEditing: () => {
51
+ if (next) {
52
+ refs.current[next]?.focus();
53
+ } else {
54
+ Keyboard.dismiss();
55
+ }
56
+ },
57
+ };
58
+ },
59
+ [order],
60
+ );
61
+
62
+ return { field };
63
+ }
@@ -0,0 +1,196 @@
1
+ /**
2
+ * @fileoverview Keyboard handling, with `react-native-keyboard-controller` as
3
+ * an *optional* accelerator (OSDKR-14).
4
+ *
5
+ * Why this file exists: under Android edge-to-edge — the default since Expo
6
+ * SDK 54, and forced on Android 15 — the window no longer shrinks when the
7
+ * keyboard opens. `<KeyboardAvoidingView behavior={undefined}>` (React
8
+ * Native's Android default) is a no-op, so the keyboard simply covers the
9
+ * lower half of a form and the fields underneath become unreachable.
10
+ *
11
+ * Two paths, same contract:
12
+ *
13
+ * - **`react-native-keyboard-controller` present** — its `KeyboardProvider`
14
+ * is mounted at the root and `KeyboardAwareScrollView` drives the scroll,
15
+ * which keeps the focused input visible and animates in sync with the
16
+ * keyboard on both platforms.
17
+ * - **Absent** — we fall back to a plain scroll view whose content gains the
18
+ * measured keyboard height as bottom padding, so every field can still be
19
+ * scrolled into view.
20
+ *
21
+ * The library is a peer dependency the host may not have installed (it also
22
+ * pulls in `react-native-reanimated`, and both require a native rebuild), so
23
+ * it is loaded through a `require` in a try/catch — exactly like
24
+ * `react-native-safe-area-context` in `utils/useSafeAreaInsets.ts`. A host that
25
+ * skips it keeps a usable, if less polished, keyboard experience.
26
+ */
27
+
28
+ import { useEffect, useState, type ComponentProps, type ReactNode } from 'react';
29
+ import { Animated, Keyboard, Platform } from 'react-native';
30
+
31
+ /** Space kept between the focused input and the top of the keyboard. */
32
+ const FOCUSED_INPUT_GAP = 24;
33
+
34
+ interface KeyboardControllerModule {
35
+ KeyboardProvider: React.ComponentType<{ children?: ReactNode }>;
36
+ // Typed loosely on purpose: the module is resolved at runtime, so its props
37
+ // are not checked here. We only forward ScrollView props plus `bottomOffset`.
38
+ KeyboardAwareScrollView: React.ComponentType<Record<string, unknown>>;
39
+ KeyboardEvents: {
40
+ addListener: (
41
+ name:
42
+ | 'keyboardWillShow'
43
+ | 'keyboardDidShow'
44
+ | 'keyboardWillHide'
45
+ | 'keyboardDidHide',
46
+ cb: (e: { height: number }) => void,
47
+ ) => { remove: () => void };
48
+ };
49
+ }
50
+
51
+ // `undefined` = not probed yet, `null` = probed and unavailable. The result is
52
+ // constant for the lifetime of the bundle (the module is either installed or
53
+ // not), so components can branch on it without breaking the rules of hooks.
54
+ let cachedModule: KeyboardControllerModule | null | undefined;
55
+
56
+ function loadKeyboardController(): KeyboardControllerModule | null {
57
+ if (cachedModule !== undefined) return cachedModule;
58
+ try {
59
+ // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
60
+ const mod = require('react-native-keyboard-controller');
61
+ cachedModule =
62
+ mod?.KeyboardProvider && mod?.KeyboardAwareScrollView && mod?.KeyboardEvents
63
+ ? (mod as KeyboardControllerModule)
64
+ : null;
65
+ } catch {
66
+ cachedModule = null;
67
+ }
68
+ return cachedModule;
69
+ }
70
+
71
+ /**
72
+ * Mounts `KeyboardProvider` when the library is installed. Required for any of
73
+ * its hooks/components to work, and a no-op wrapper otherwise. Nesting a second
74
+ * provider (a host that already mounts one) is harmless.
75
+ */
76
+ export function KeyboardBoundary({ children }: { children: ReactNode }) {
77
+ const mod = loadKeyboardController();
78
+ if (!mod) return <>{children}</>;
79
+ const Provider = mod.KeyboardProvider;
80
+ return <Provider>{children}</Provider>;
81
+ }
82
+
83
+ /**
84
+ * Height of the on-screen keyboard, in dp, or 0 when it is closed.
85
+ *
86
+ * Prefers `react-native-keyboard-controller`'s events when the library is
87
+ * installed. This is not a nicety: on Android, React Native's own
88
+ * `keyboardDidShow` is tied to the window being resized by `adjustResize`,
89
+ * which edge-to-edge no longer does — the event can simply never fire, leaving
90
+ * a pinned footer stranded behind the keyboard. The library reads the IME
91
+ * insets directly and reports reliably on both platforms.
92
+ *
93
+ * The `Will` variants are used where available so chrome moves *with* the
94
+ * keyboard animation instead of snapping after it.
95
+ */
96
+ export function useKeyboardHeight(): number {
97
+ const [height, setHeight] = useState(0);
98
+
99
+ useEffect(() => {
100
+ const mod = loadKeyboardController();
101
+
102
+ if (mod) {
103
+ const show = mod.KeyboardEvents.addListener('keyboardWillShow', (e) =>
104
+ setHeight(e.height ?? 0),
105
+ );
106
+ const hide = mod.KeyboardEvents.addListener('keyboardWillHide', () =>
107
+ setHeight(0),
108
+ );
109
+ return () => {
110
+ show.remove();
111
+ hide.remove();
112
+ };
113
+ }
114
+
115
+ const show =
116
+ Platform.OS === 'ios'
117
+ ? Keyboard.addListener('keyboardWillChangeFrame', (e) =>
118
+ setHeight(e.endCoordinates?.height ?? 0),
119
+ )
120
+ : Keyboard.addListener('keyboardDidShow', (e) =>
121
+ setHeight(e.endCoordinates?.height ?? 0),
122
+ );
123
+ const hide =
124
+ Platform.OS === 'ios'
125
+ ? Keyboard.addListener('keyboardWillHide', () => setHeight(0))
126
+ : Keyboard.addListener('keyboardDidHide', () => setHeight(0));
127
+
128
+ return () => {
129
+ show.remove();
130
+ hide.remove();
131
+ };
132
+ }, []);
133
+
134
+ return height;
135
+ }
136
+
137
+ export interface FormScrollViewProps
138
+ extends ComponentProps<typeof Animated.ScrollView> {
139
+ /**
140
+ * Bottom padding for the scroll content — normally the screen's safe-area
141
+ * inset. Passed as a number instead of inside `contentContainerStyle` so the
142
+ * fallback path can add the keyboard height *on top of* it.
143
+ */
144
+ contentPaddingBottom?: number | undefined;
145
+ }
146
+
147
+ /**
148
+ * Scroll container for form bodies: keeps the focused input clear of the
149
+ * keyboard through `KeyboardAwareScrollView` when it is available, and pads
150
+ * the content by the keyboard height when it is not.
151
+ *
152
+ * Kept as an `Animated.ScrollView` in both paths (passed to the library as its
153
+ * `ScrollViewComponent`) so callers can drive native-driver scroll animations —
154
+ * `StepShell`'s top fade depends on it.
155
+ */
156
+ export function FormScrollView({
157
+ contentContainerStyle,
158
+ contentPaddingBottom = 0,
159
+ ...props
160
+ }: FormScrollViewProps) {
161
+ const mod = loadKeyboardController();
162
+ // Called unconditionally (the branch below is constant for the lifetime of
163
+ // the bundle) but only consumed by the fallback path.
164
+ const keyboardHeight = useKeyboardHeight();
165
+
166
+ if (mod) {
167
+ const KeyboardAware = mod.KeyboardAwareScrollView;
168
+ return (
169
+ <KeyboardAware
170
+ {...props}
171
+ ScrollViewComponent={Animated.ScrollView}
172
+ bottomOffset={FOCUSED_INPUT_GAP}
173
+ contentContainerStyle={[
174
+ contentContainerStyle,
175
+ { paddingBottom: contentPaddingBottom },
176
+ ]}
177
+ />
178
+ );
179
+ }
180
+
181
+ // No keyboard-aware scrolling available: grow the content by the keyboard
182
+ // height so every field below it can still be scrolled into view.
183
+ return (
184
+ <Animated.ScrollView
185
+ {...props}
186
+ contentContainerStyle={[
187
+ contentContainerStyle,
188
+ {
189
+ paddingBottom:
190
+ contentPaddingBottom +
191
+ (keyboardHeight > 0 ? keyboardHeight + FOCUSED_INPUT_GAP : 0),
192
+ },
193
+ ]}
194
+ />
195
+ );
196
+ }