@velion-la/onboarding-sdk-react-native 1.1.0-beta.1 → 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 (82) hide show
  1. package/CHANGELOG.md +16 -1
  2. package/README.md +40 -0
  3. package/lib/commonjs/camera/DocumentCapture.js +11 -0
  4. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  5. package/lib/commonjs/steps/AddressInfoStep.js +41 -13
  6. package/lib/commonjs/steps/AddressInfoStep.js.map +1 -1
  7. package/lib/commonjs/steps/DocumentsOcrStep.js +115 -90
  8. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  9. package/lib/commonjs/steps/EconomicActivityStep.js +53 -52
  10. package/lib/commonjs/steps/EconomicActivityStep.js.map +1 -1
  11. package/lib/commonjs/ui/ScreenScaffold.js +99 -0
  12. package/lib/commonjs/ui/ScreenScaffold.js.map +1 -0
  13. package/lib/commonjs/ui/StepShell.js +23 -42
  14. package/lib/commonjs/ui/StepShell.js.map +1 -1
  15. package/lib/commonjs/ui/VelionOnboardingScreen.js +13 -10
  16. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  17. package/lib/commonjs/ui/forms/index.js +7 -0
  18. package/lib/commonjs/ui/forms/index.js.map +1 -1
  19. package/lib/commonjs/ui/forms/useFieldChain.js +56 -0
  20. package/lib/commonjs/ui/forms/useFieldChain.js.map +1 -0
  21. package/lib/commonjs/ui/keyboard.js +147 -0
  22. package/lib/commonjs/ui/keyboard.js.map +1 -0
  23. package/lib/commonjs/ui/screenInsets.js +67 -0
  24. package/lib/commonjs/ui/screenInsets.js.map +1 -0
  25. package/lib/commonjs/utils/documentCrop.js +21 -0
  26. package/lib/commonjs/utils/documentCrop.js.map +1 -1
  27. package/lib/module/camera/DocumentCapture.js +11 -0
  28. package/lib/module/camera/DocumentCapture.js.map +1 -1
  29. package/lib/module/steps/AddressInfoStep.js +41 -13
  30. package/lib/module/steps/AddressInfoStep.js.map +1 -1
  31. package/lib/module/steps/DocumentsOcrStep.js +116 -90
  32. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  33. package/lib/module/steps/EconomicActivityStep.js +54 -53
  34. package/lib/module/steps/EconomicActivityStep.js.map +1 -1
  35. package/lib/module/ui/ScreenScaffold.js +94 -0
  36. package/lib/module/ui/ScreenScaffold.js.map +1 -0
  37. package/lib/module/ui/StepShell.js +24 -43
  38. package/lib/module/ui/StepShell.js.map +1 -1
  39. package/lib/module/ui/VelionOnboardingScreen.js +13 -10
  40. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  41. package/lib/module/ui/forms/index.js +1 -0
  42. package/lib/module/ui/forms/index.js.map +1 -1
  43. package/lib/module/ui/forms/useFieldChain.js +52 -0
  44. package/lib/module/ui/forms/useFieldChain.js.map +1 -0
  45. package/lib/module/ui/keyboard.js +143 -0
  46. package/lib/module/ui/keyboard.js.map +1 -0
  47. package/lib/module/ui/screenInsets.js +61 -0
  48. package/lib/module/ui/screenInsets.js.map +1 -0
  49. package/lib/module/utils/documentCrop.js +20 -0
  50. package/lib/module/utils/documentCrop.js.map +1 -1
  51. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  52. package/lib/typescript/steps/AddressInfoStep.d.ts.map +1 -1
  53. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  54. package/lib/typescript/steps/EconomicActivityStep.d.ts.map +1 -1
  55. package/lib/typescript/ui/ScreenScaffold.d.ts +57 -0
  56. package/lib/typescript/ui/ScreenScaffold.d.ts.map +1 -0
  57. package/lib/typescript/ui/StepShell.d.ts +1 -3
  58. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  59. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  60. package/lib/typescript/ui/forms/index.d.ts +1 -0
  61. package/lib/typescript/ui/forms/index.d.ts.map +1 -1
  62. package/lib/typescript/ui/forms/useFieldChain.d.ts +30 -0
  63. package/lib/typescript/ui/forms/useFieldChain.d.ts.map +1 -0
  64. package/lib/typescript/ui/keyboard.d.ts +69 -0
  65. package/lib/typescript/ui/keyboard.d.ts.map +1 -0
  66. package/lib/typescript/ui/screenInsets.d.ts +68 -0
  67. package/lib/typescript/ui/screenInsets.d.ts.map +1 -0
  68. package/lib/typescript/utils/documentCrop.d.ts +16 -0
  69. package/lib/typescript/utils/documentCrop.d.ts.map +1 -1
  70. package/package.json +5 -1
  71. package/src/camera/DocumentCapture.tsx +10 -0
  72. package/src/steps/AddressInfoStep.tsx +37 -0
  73. package/src/steps/DocumentsOcrStep.tsx +138 -97
  74. package/src/steps/EconomicActivityStep.tsx +54 -44
  75. package/src/ui/ScreenScaffold.tsx +130 -0
  76. package/src/ui/StepShell.tsx +27 -56
  77. package/src/ui/VelionOnboardingScreen.tsx +16 -13
  78. package/src/ui/forms/index.ts +1 -0
  79. package/src/ui/forms/useFieldChain.ts +63 -0
  80. package/src/ui/keyboard.tsx +196 -0
  81. package/src/ui/screenInsets.ts +89 -0
  82. package/src/utils/documentCrop.ts +21 -0
@@ -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
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * @fileoverview Chrome inset math for every full-screen surface (OSDKR-14).
3
+ *
4
+ * Pure functions, deliberately free of React and react-native imports so the
5
+ * geometry can be unit-tested. `ScreenScaffold` is the only component that
6
+ * should consume them directly — screens read the result off the scaffold.
7
+ *
8
+ * Two rules encoded here, both learned from real bugs:
9
+ *
10
+ * - **Floors.** `useSafeAreaInsets` degrades to zeros when the host strips
11
+ * `react-native-safe-area-context` or renders us outside a provider, and a
12
+ * device with no notch legitimately reports 0. A CTA flush against the
13
+ * screen edge is wrong in both cases, so every inset carries a minimum gap.
14
+ * - **The ProgressBar is chrome too.** It floats above the step content at the
15
+ * very top of the screen, so anything pinned to the top (a "back" control)
16
+ * must clear the status bar *and* the bar's own height, or the two overlap.
17
+ */
18
+
19
+ import type { EdgeInsets } from '../utils/useSafeAreaInsets';
20
+
21
+ /**
22
+ * Minimum breathing room between interactive chrome and the screen edge, used
23
+ * when the device (or a missing provider) reports a zero inset.
24
+ */
25
+ export const MIN_EDGE_GAP = 12;
26
+
27
+ export interface ScreenInsets {
28
+ /**
29
+ * Raw safe top inset — the status bar / notch / punch-hole. Deliberately
30
+ * *not* floored: the ProgressBar is painted flush under the status bar, and
31
+ * a floor would push it down on devices that legitimately report 0.
32
+ */
33
+ top: number;
34
+ /**
35
+ * Top inset for chrome pinned above the step content: the safe top (floored,
36
+ * because this chrome is interactive) plus the floating ProgressBar's
37
+ * height, so a "back" control never tucks under it.
38
+ */
39
+ topChrome: number;
40
+ /**
41
+ * Safe bottom inset, floored — clears the Android navigation bar (including
42
+ * the 3-button bar on edge-to-edge) and the iOS home indicator.
43
+ */
44
+ bottom: number;
45
+ left: number;
46
+ right: number;
47
+ }
48
+
49
+ /**
50
+ * Resolve the chrome insets for a full-screen surface.
51
+ *
52
+ * @param raw Device insets as reported by `react-native-safe-area-context`.
53
+ * @param progressBarHeight Height of the floating ProgressBar, or 0 when the
54
+ * flow hides it — `topChrome` collapses to `top` in that case.
55
+ */
56
+ export function computeScreenInsets(
57
+ raw: EdgeInsets,
58
+ progressBarHeight = 0,
59
+ ): ScreenInsets {
60
+ return {
61
+ top: Math.max(raw.top, 0),
62
+ topChrome: Math.max(raw.top, MIN_EDGE_GAP) + Math.max(progressBarHeight, 0),
63
+ bottom: Math.max(raw.bottom, MIN_EDGE_GAP),
64
+ left: Math.max(raw.left, 0),
65
+ right: Math.max(raw.right, 0),
66
+ };
67
+ }
68
+
69
+ /**
70
+ * Breathing room between a pinned CTA and whatever sits below it — the
71
+ * navigation bar, or the keyboard. Clearing the bar is not enough on its own:
72
+ * a button whose edge touches the system bar reads as clipped.
73
+ */
74
+ export const FOOTER_EDGE_GAP = 14;
75
+
76
+ /**
77
+ * Bottom padding for a strip pinned to the bottom of the screen (a CTA row).
78
+ *
79
+ * While the keyboard is up it must sit above the keyboard rather than the
80
+ * navigation bar — under Android edge-to-edge the window no longer shrinks, so
81
+ * the keyboard overlaps our layout and a plain safe-area inset would leave the
82
+ * CTA buried underneath it.
83
+ */
84
+ export function bottomChromeInset(
85
+ insets: ScreenInsets,
86
+ keyboardHeight: number,
87
+ ): number {
88
+ return Math.max(insets.bottom, keyboardHeight) + FOOTER_EDGE_GAP;
89
+ }
@@ -88,6 +88,27 @@ export function computeCutout(
88
88
  * clamped to the image bounds, then rounded to integers (the manipulator
89
89
  * rejects fractional crop rects).
90
90
  */
91
+ /**
92
+ * Whether the guide rectangle can be mapped onto the photo at all (OSDKR-13).
93
+ *
94
+ * `computeGuideCropRect` inverts a `cover` fit, which only makes sense when the
95
+ * screen and the photo are in the *same* orientation space — the photo is the
96
+ * preview the guide was drawn over. If the two disagree (a portrait screen and
97
+ * a landscape photo), something upstream rotated the capture and any rect we
98
+ * compute would address the wrong pixels. Callers should skip the crop and
99
+ * upload the full photo instead of shipping a garbage region.
100
+ */
101
+ export function isGuideSpaceConsistent(params: {
102
+ screenW: number;
103
+ screenH: number;
104
+ imageW: number;
105
+ imageH: number;
106
+ }): boolean {
107
+ const { screenW, screenH, imageW, imageH } = params;
108
+ if (imageW <= 0 || imageH <= 0 || screenW <= 0 || screenH <= 0) return false;
109
+ return screenW >= screenH === (imageW >= imageH);
110
+ }
111
+
91
112
  export function computeGuideCropRect(params: {
92
113
  screenW: number;
93
114
  screenH: number;