@velion-la/onboarding-sdk-react-native 1.0.0-beta.8 → 1.0.0

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 (83) hide show
  1. package/lib/commonjs/camera/DocumentCapture.js +78 -29
  2. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  3. package/lib/commonjs/camera/LivenessCamera.js +18 -3
  4. package/lib/commonjs/camera/LivenessCamera.js.map +1 -1
  5. package/lib/commonjs/camera/MapAddressPicker.js +12 -22
  6. package/lib/commonjs/camera/MapAddressPicker.js.map +1 -1
  7. package/lib/commonjs/i18n/strings/en.js +3 -2
  8. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  9. package/lib/commonjs/i18n/strings/es.js +3 -2
  10. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  11. package/lib/commonjs/steps/DocumentsOcrStep.js +121 -23
  12. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  13. package/lib/commonjs/steps/PhoneContactStep.js +10 -4
  14. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  15. package/lib/commonjs/steps/PhoneOtpStep.js +17 -6
  16. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  17. package/lib/commonjs/ui/StepShell.js +134 -9
  18. package/lib/commonjs/ui/StepShell.js.map +1 -1
  19. package/lib/commonjs/ui/VelionOnboardingScreen.js +52 -13
  20. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  21. package/lib/commonjs/ui/overlays/ProgressBar.js +8 -2
  22. package/lib/commonjs/ui/overlays/ProgressBar.js.map +1 -1
  23. package/lib/commonjs/utils/documentCrop.js +115 -0
  24. package/lib/commonjs/utils/documentCrop.js.map +1 -0
  25. package/lib/commonjs/utils/useSafeAreaInsets.js +41 -0
  26. package/lib/commonjs/utils/useSafeAreaInsets.js.map +1 -0
  27. package/lib/module/camera/DocumentCapture.js +78 -29
  28. package/lib/module/camera/DocumentCapture.js.map +1 -1
  29. package/lib/module/camera/LivenessCamera.js +18 -3
  30. package/lib/module/camera/LivenessCamera.js.map +1 -1
  31. package/lib/module/camera/MapAddressPicker.js +12 -23
  32. package/lib/module/camera/MapAddressPicker.js.map +1 -1
  33. package/lib/module/i18n/strings/en.js +3 -2
  34. package/lib/module/i18n/strings/en.js.map +1 -1
  35. package/lib/module/i18n/strings/es.js +3 -2
  36. package/lib/module/i18n/strings/es.js.map +1 -1
  37. package/lib/module/steps/DocumentsOcrStep.js +121 -23
  38. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  39. package/lib/module/steps/PhoneContactStep.js +10 -4
  40. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  41. package/lib/module/steps/PhoneOtpStep.js +17 -6
  42. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  43. package/lib/module/ui/StepShell.js +134 -10
  44. package/lib/module/ui/StepShell.js.map +1 -1
  45. package/lib/module/ui/VelionOnboardingScreen.js +55 -14
  46. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  47. package/lib/module/ui/overlays/ProgressBar.js +8 -1
  48. package/lib/module/ui/overlays/ProgressBar.js.map +1 -1
  49. package/lib/module/utils/documentCrop.js +109 -0
  50. package/lib/module/utils/documentCrop.js.map +1 -0
  51. package/lib/module/utils/useSafeAreaInsets.js +37 -0
  52. package/lib/module/utils/useSafeAreaInsets.js.map +1 -0
  53. package/lib/typescript/camera/DocumentCapture.d.ts +20 -8
  54. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  55. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  56. package/lib/typescript/camera/MapAddressPicker.d.ts.map +1 -1
  57. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  58. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  59. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  60. package/lib/typescript/steps/DocumentsOcrStep.d.ts +8 -6
  61. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  62. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  63. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  64. package/lib/typescript/ui/overlays/ProgressBar.d.ts +6 -0
  65. package/lib/typescript/ui/overlays/ProgressBar.d.ts.map +1 -1
  66. package/lib/typescript/utils/documentCrop.d.ts +62 -0
  67. package/lib/typescript/utils/documentCrop.d.ts.map +1 -0
  68. package/lib/typescript/utils/useSafeAreaInsets.d.ts +26 -0
  69. package/lib/typescript/utils/useSafeAreaInsets.d.ts.map +1 -0
  70. package/package.json +2 -1
  71. package/src/camera/DocumentCapture.tsx +78 -28
  72. package/src/camera/LivenessCamera.tsx +10 -3
  73. package/src/camera/MapAddressPicker.tsx +12 -18
  74. package/src/i18n/strings/en.ts +3 -2
  75. package/src/i18n/strings/es.ts +3 -2
  76. package/src/steps/DocumentsOcrStep.tsx +145 -24
  77. package/src/steps/PhoneContactStep.tsx +9 -3
  78. package/src/steps/PhoneOtpStep.tsx +14 -4
  79. package/src/ui/StepShell.tsx +129 -10
  80. package/src/ui/VelionOnboardingScreen.tsx +53 -13
  81. package/src/ui/overlays/ProgressBar.tsx +8 -1
  82. package/src/utils/documentCrop.ts +138 -0
  83. package/src/utils/useSafeAreaInsets.ts +37 -0
@@ -5,13 +5,15 @@
5
5
  * intro → captureFront → reviewFront → captureBack → reviewBack →
6
6
  * POST /documents-init → PUT image/jpeg × 2 → POST /documents-verify → done.
7
7
  *
8
- * No edge detection / OpenCV port (intentional MVP scope per the brief). The
9
- * camera shows the ID-1 frame guide and the user fills it; the backend OCR
10
- * pipeline handles cropping.
8
+ * Crop: on capture we receive the on-screen guide rectangle and crop the photo
9
+ * to it (OSDKR-2) — a geometric crop to the visible ID-1 frame, NOT edge
10
+ * detection / OpenCV. This trims the camera background, improves OCR framing
11
+ * and shrinks the upload. The backend's Document AI still runs OCR + its own
12
+ * face crop on top, so we keep a safety margin around the guide.
11
13
  *
12
- * Compression: vision-camera writes a high-quality JPEG. We re-compress with
13
- * `expo-image-manipulator` before upload so we keep the payload under the
14
- * 5 MB ceiling Velion's storage layer expects.
14
+ * Compression: vision-camera writes a high-quality JPEG. After cropping we
15
+ * resize + re-compress with `expo-image-manipulator` before upload so we keep
16
+ * the payload under the 5 MB ceiling Velion's storage layer expects.
15
17
  */
16
18
 
17
19
  import { useCallback, useEffect, useMemo, useState } from 'react';
@@ -43,7 +45,8 @@ import { useTheme, mixHex } from '../ui/theme';
43
45
  import { getStrings } from '../i18n';
44
46
  import { resolveCaptureModeFromStepConfig } from '../utils/stepConfig';
45
47
  import { log } from '../utils/log';
46
- import { DocumentCapture } from '../camera/DocumentCapture';
48
+ import { DocumentCapture, type CaptureGuide } from '../camera/DocumentCapture';
49
+ import { computeGuideCropRect } from '../utils/documentCrop';
47
50
  import type { ApiCaller } from '../transport/api';
48
51
  import type { StepDeps, StepModule } from './types';
49
52
  import { toSubmissionError } from './_shared';
@@ -151,11 +154,16 @@ function DocumentsOcrView({
151
154
  const [bannerError, setBannerError] = useState<string | null>(null);
152
155
  const [busyLabel, setBusyLabel] = useState<string | null>(null);
153
156
  const [retry, setRetry] = useState<{ message: string } | null>(null);
157
+ // Measured size of the preview area, used to fit the framed card to the
158
+ // capture's exact aspect ratio (no empty letterbox bands around the crop).
159
+ const [previewBox, setPreviewBox] = useState<{ w: number; h: number } | null>(
160
+ null,
161
+ );
154
162
 
155
163
  const handleCaptured = useCallback(
156
- async (photo: PhotoFile, side: DocumentSide) => {
164
+ async (photo: PhotoFile, side: DocumentSide, guide: CaptureGuide) => {
157
165
  try {
158
- const compressed = await compressJpeg(photo.path);
166
+ const compressed = await compressJpeg(photo.path, guide);
159
167
  if (compressed.byteLength > MAX_BYTES) {
160
168
  setBannerError(t.documents_ocr.fileTooLarge);
161
169
  // Stay on the capture phase so the user can retake immediately.
@@ -249,6 +257,7 @@ function DocumentsOcrView({
249
257
  permissionDeniedLabel={t.documents_ocr.cameraPermissionDenied}
250
258
  retryLabel={t.documents_ocr.cameraTryAgain}
251
259
  cancelLabel={t.common.cancel}
260
+ processingLabel={t.documents_ocr.processing}
252
261
  onCancel={() =>
253
262
  setPhase(side === 'FRONT' ? 'intro' : 'reviewFront')
254
263
  }
@@ -270,12 +279,39 @@ function DocumentsOcrView({
270
279
  <Text style={[styles.reviewTitle, { color: theme.textColor }]}>
271
280
  {side === 'FRONT' ? t.documents_ocr.frontTitle : t.documents_ocr.backTitle}
272
281
  </Text>
273
- <View style={styles.previewWrap}>
274
- <Image
275
- source={{ uri: captured.uri }}
276
- style={styles.preview}
277
- resizeMode="contain"
278
- />
282
+ <View
283
+ style={styles.previewWrap}
284
+ onLayout={(e) =>
285
+ setPreviewBox({
286
+ w: e.nativeEvent.layout.width,
287
+ h: e.nativeEvent.layout.height,
288
+ })
289
+ }
290
+ >
291
+ {previewBox ? (
292
+ <View
293
+ style={[
294
+ styles.previewCard,
295
+ fitContain(
296
+ captured.width / captured.height,
297
+ previewBox.w,
298
+ previewBox.h,
299
+ ),
300
+ {
301
+ borderColor: theme.borderColor,
302
+ borderRadius: theme.borderRadiusPx,
303
+ },
304
+ ]}
305
+ >
306
+ <Image
307
+ source={{ uri: captured.uri }}
308
+ style={styles.preview}
309
+ // Card matches the capture's aspect ratio exactly, so `cover`
310
+ // fills it edge to edge with no distortion and no bands.
311
+ resizeMode="cover"
312
+ />
313
+ </View>
314
+ ) : null}
279
315
  </View>
280
316
  {bannerError ? <Banner message={bannerError} /> : null}
281
317
  <View style={styles.reviewActions}>
@@ -370,15 +406,53 @@ function DocumentsOcrView({
370
406
  );
371
407
  }
372
408
 
373
- async function compressJpeg(uri: string): Promise<CapturedSide> {
374
- // Vision-camera produces 4 K JPEGs on modern phones — well past the 5 MB
375
- // budget. Resize the long edge to 1800 px and recompress to ~78% quality;
376
- // empirically that lands at < 600 KB while keeping OCR-grade legibility.
377
- const result = await ImageManipulator.manipulateAsync(
378
- normalizeFileUri(uri),
379
- [{ resize: { width: MAX_LONG_EDGE } }],
380
- { compress: COMPRESS_QUALITY, format: ImageManipulator.SaveFormat.JPEG },
381
- );
409
+ async function compressJpeg(
410
+ uri: string,
411
+ guide: CaptureGuide,
412
+ ): Promise<CapturedSide> {
413
+ const source = normalizeFileUri(uri);
414
+
415
+ // Display dimensions of the captured photo — exactly the orientation the
416
+ // user saw framed in the preview (the live camera and the captured image are
417
+ // both shown upright with `cover` fit). We crop strictly to the on-screen
418
+ // guide rectangle the user centred the document in; we never inspect pixels
419
+ // and we never try to detect/rotate based on how the phone was held.
420
+ const { width: imageW, height: imageH } = await getDisplaySize(source);
421
+
422
+ const crop = computeGuideCropRect({
423
+ screenW: guide.screenW,
424
+ screenH: guide.screenH,
425
+ imageW,
426
+ imageH,
427
+ cutout: guide.cutout,
428
+ });
429
+
430
+ // Crop to the guide, then resize the long edge to MAX_LONG_EDGE (never
431
+ // upscale — the crop can leave a small region) and recompress to ~78%.
432
+ const actions: ImageManipulator.Action[] = [
433
+ {
434
+ crop: {
435
+ originX: crop.x,
436
+ originY: crop.y,
437
+ width: crop.width,
438
+ height: crop.height,
439
+ },
440
+ },
441
+ ];
442
+ const longEdge = Math.max(crop.width, crop.height);
443
+ if (longEdge > MAX_LONG_EDGE) {
444
+ actions.push({
445
+ resize:
446
+ crop.width >= crop.height
447
+ ? { width: MAX_LONG_EDGE }
448
+ : { height: MAX_LONG_EDGE },
449
+ });
450
+ }
451
+
452
+ const result = await ImageManipulator.manipulateAsync(source, actions, {
453
+ compress: COMPRESS_QUALITY,
454
+ format: ImageManipulator.SaveFormat.JPEG,
455
+ });
382
456
  const byteLength = await fetchByteLength(result.uri);
383
457
  return {
384
458
  uri: result.uri,
@@ -388,6 +462,24 @@ async function compressJpeg(uri: string): Promise<CapturedSide> {
388
462
  };
389
463
  }
390
464
 
465
+ /**
466
+ * Resolve the captured photo's *display* dimensions (upright, EXIF applied) —
467
+ * what the user saw in the preview. `Image.getSize` reads the header without a
468
+ * full re-encode, so it's both cheap and the source of truth for the crop
469
+ * mapping. No orientation guessing: the value is the displayed size, period.
470
+ */
471
+ function getDisplaySize(
472
+ uri: string,
473
+ ): Promise<{ width: number; height: number }> {
474
+ return new Promise((resolve, reject) => {
475
+ Image.getSize(
476
+ uri,
477
+ (width, height) => resolve({ width, height }),
478
+ (err) => reject(err instanceof Error ? err : new Error(String(err))),
479
+ );
480
+ });
481
+ }
482
+
391
483
  async function uploadJpeg(uri: string, signedUrl: string): Promise<void> {
392
484
  const response = await fetch(uri);
393
485
  if (!response.ok) {
@@ -411,6 +503,25 @@ async function fetchByteLength(uri: string): Promise<number> {
411
503
  return blob.size;
412
504
  }
413
505
 
506
+ /**
507
+ * Fit a `width/height` box of the given aspect ratio inside `boxW × boxH`
508
+ * (contain). Returns the largest size that keeps the aspect ratio and fits —
509
+ * so the framed preview hugs the capture with no empty bands.
510
+ */
511
+ function fitContain(
512
+ aspect: number,
513
+ boxW: number,
514
+ boxH: number,
515
+ ): { width: number; height: number } {
516
+ let width = boxW;
517
+ let height = boxW / aspect;
518
+ if (height > boxH) {
519
+ height = boxH;
520
+ width = boxH * aspect;
521
+ }
522
+ return { width, height };
523
+ }
524
+
414
525
  function normalizeFileUri(uri: string): string {
415
526
  // Vision-camera returns paths with a leading `/var/mobile/...` on iOS
416
527
  // (no scheme) — `expo-image-manipulator` requires a `file://` prefix.
@@ -467,6 +578,16 @@ const styles = StyleSheet.create({
467
578
  alignItems: 'center',
468
579
  justifyContent: 'center',
469
580
  },
581
+ previewCard: {
582
+ borderWidth: 1,
583
+ overflow: 'hidden',
584
+ // Subtle lift so the framed capture reads as a deliberate card.
585
+ shadowColor: '#000',
586
+ shadowOpacity: 0.12,
587
+ shadowRadius: 10,
588
+ shadowOffset: { width: 0, height: 4 },
589
+ elevation: 3,
590
+ },
470
591
  preview: {
471
592
  width: '100%',
472
593
  height: '100%',
@@ -114,6 +114,8 @@ function PhoneContactView({
114
114
  }
115
115
  }, [api, phone, onComplete, sessionId, t, validation]);
116
116
 
117
+ const phoneField = validation.bind('phone', phone);
118
+
117
119
  if (retry) {
118
120
  return (
119
121
  <RetryDialog
@@ -141,8 +143,9 @@ function PhoneContactView({
141
143
  backDisabled={submitting}
142
144
  >
143
145
  <Input
144
- label={t.phone_contact.label}
145
- required
146
+ // No visible label — the step title already names the field. Keep an
147
+ // accessibility label so screen readers still announce it.
148
+ accessibilityLabel={t.phone_contact.label}
146
149
  autoCapitalize="none"
147
150
  autoCorrect={false}
148
151
  autoComplete="tel"
@@ -150,7 +153,10 @@ function PhoneContactView({
150
153
  keyboardType="phone-pad"
151
154
  placeholder="+5491112345678"
152
155
  value={phone}
153
- {...validation.bind('phone', phone)}
156
+ {...phoneField}
157
+ // Strip whitespace so a pasted "+54 911 1234 5678" lands as E.164.
158
+ // Overrides the spread `onChangeText` from `bind`.
159
+ onChangeText={(text) => phoneField.onChangeText(text.replace(/\s+/g, ''))}
154
160
  />
155
161
  {bannerError ? <Banner message={bannerError} /> : null}
156
162
  <Button
@@ -149,6 +149,9 @@ function PhoneOtpView({
149
149
  }
150
150
  }, [api, onComplete, otp, otpValidation, sessionId, t]);
151
151
 
152
+ const phoneField = phoneValidation.bind('phone', phone);
153
+ const otpField = otpValidation.bind('otp', otp);
154
+
152
155
  if (retry) {
153
156
  return (
154
157
  <RetryDialog
@@ -176,8 +179,9 @@ function PhoneOtpView({
176
179
  backDisabled={busy !== null}
177
180
  >
178
181
  <Input
179
- label={t.phone_otp.phoneLabel}
180
- required
182
+ // No visible label — the step title already names the field. Keep an
183
+ // accessibility label so screen readers still announce it.
184
+ accessibilityLabel={t.phone_otp.phoneLabel}
181
185
  autoCapitalize="none"
182
186
  autoCorrect={false}
183
187
  autoComplete="tel"
@@ -186,7 +190,9 @@ function PhoneOtpView({
186
190
  placeholder="+5491112345678"
187
191
  editable={stage === 'request'}
188
192
  value={phone}
189
- {...phoneValidation.bind('phone', phone)}
193
+ {...phoneField}
194
+ // Strip whitespace so a pasted "+54 911 1234 5678" lands as E.164.
195
+ onChangeText={(text) => phoneField.onChangeText(text.replace(/\s+/g, ''))}
190
196
  />
191
197
  {stage === 'request' ? (
192
198
  <Button
@@ -198,6 +204,8 @@ function PhoneOtpView({
198
204
  ) : (
199
205
  <>
200
206
  <Input
207
+ // Label kept here: in the verify stage the phone field is also
208
+ // visible, so the label disambiguates which field is the code.
201
209
  label={t.phone_otp.otpLabel}
202
210
  required
203
211
  autoCapitalize="none"
@@ -206,7 +214,9 @@ function PhoneOtpView({
206
214
  textContentType="oneTimeCode"
207
215
  maxLength={6}
208
216
  value={otp}
209
- {...otpValidation.bind('otp', otp)}
217
+ {...otpField}
218
+ // Strip whitespace so a pasted code (e.g. "123 456") becomes "123456".
219
+ onChangeText={(text) => otpField.onChangeText(text.replace(/\s+/g, ''))}
210
220
  />
211
221
  {bannerError ? <Banner message={bannerError} /> : null}
212
222
  <Button
@@ -7,16 +7,25 @@
7
7
  */
8
8
 
9
9
  import type { ReactNode } from 'react';
10
+ import { useRef } from 'react';
10
11
  import {
12
+ Animated,
11
13
  KeyboardAvoidingView,
12
14
  Platform,
13
- ScrollView,
14
15
  StyleSheet,
15
16
  Text,
16
17
  View,
17
18
  } from 'react-native';
19
+ import Svg, {
20
+ Defs,
21
+ LinearGradient as SvgLinearGradient,
22
+ Rect,
23
+ Stop,
24
+ } from 'react-native-svg';
18
25
  import { useTheme, withAlpha } from './theme';
19
26
  import { BackButton } from './primitives/BackButton';
27
+ import { PROGRESS_BAR_HEIGHT } from './overlays/ProgressBar';
28
+ import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
20
29
 
21
30
  export interface StepShellProps {
22
31
  title: string;
@@ -49,18 +58,44 @@ export function StepShell({
49
58
  backDisabled = false,
50
59
  }: StepShellProps) {
51
60
  const theme = useTheme();
61
+ const insets = useSafeAreaInsets();
52
62
 
53
63
  const showIconCircle = !theme.hideStepIcons && iconNode != null;
64
+ const showBack = onBack != null;
54
65
 
55
- const body = (
56
- <ScrollView
66
+ // Drive the top-fade opacity from the scroll offset so the gradient is fully
67
+ // invisible at rest (scrollY = 0) — the header/icon reads crisp — and only
68
+ // ramps in as the content scrolls up under the fixed back strip (OSDKR-12).
69
+ const scrollY = useRef(new Animated.Value(0)).current;
70
+ const fadeOpacity = scrollY.interpolate({
71
+ inputRange: [0, FADE_RAMP_DISTANCE],
72
+ outputRange: [0, 1],
73
+ extrapolate: 'clamp',
74
+ });
75
+
76
+ const scroll = (
77
+ <Animated.ScrollView
57
78
  style={styles.scroll}
58
- contentContainerStyle={styles.scrollBody}
79
+ scrollEventThrottle={16}
80
+ onScroll={Animated.event(
81
+ [{ nativeEvent: { contentOffset: { y: scrollY } } }],
82
+ { useNativeDriver: true },
83
+ )}
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.
90
+ contentContainerStyle={[
91
+ styles.scrollBody,
92
+ {
93
+ paddingTop: showBack ? BASE_PADDING_TOP : BASE_PADDING_TOP + insets.top,
94
+ paddingBottom: BASE_PADDING_BOTTOM + insets.bottom,
95
+ },
96
+ ]}
59
97
  keyboardShouldPersistTaps="handled"
60
98
  >
61
- {onBack ? (
62
- <BackButton label={backLabel} onPress={onBack} disabled={backDisabled} />
63
- ) : null}
64
99
  <View style={styles.header}>
65
100
  {showIconCircle ? (
66
101
  <View
@@ -87,7 +122,66 @@ export function StepShell({
87
122
  ) : null}
88
123
  </View>
89
124
  <View style={styles.column}>{children}</View>
90
- </ScrollView>
125
+ </Animated.ScrollView>
126
+ );
127
+
128
+ // The back control lives in a fixed strip OUTSIDE the ScrollView so it stays
129
+ // 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
+ >
141
+ <BackButton
142
+ label={backLabel}
143
+ onPress={onBack}
144
+ disabled={backDisabled}
145
+ />
146
+ </View>
147
+ ) : null}
148
+ <View style={styles.scrollWrap}>
149
+ {scroll}
150
+ {/* Soft top fade: the ScrollView hard-clips content at its top edge,
151
+ which reads as an abrupt cut as the header scrolls up under the
152
+ fixed back strip. A short background-to-transparent gradient lets
153
+ the content dissolve instead (OSDKR-12). Its opacity is tied to the
154
+ scroll offset so it stays invisible at rest and only appears once
155
+ the user scrolls. pointerEvents="none" so it never intercepts
156
+ touches / scroll. */}
157
+ <Animated.View
158
+ pointerEvents="none"
159
+ style={[styles.topFade, { height: TOP_FADE_HEIGHT, opacity: fadeOpacity }]}
160
+ >
161
+ <Svg width="100%" height="100%">
162
+ <Defs>
163
+ <SvgLinearGradient id="stepTopFade" x1="0" y1="0" x2="0" y2="1">
164
+ {/* Eased falloff (not linear): opaque near the top, then a long
165
+ gentle tail toward transparent, so the dissolve has no
166
+ perceptible edge. */}
167
+ <Stop offset="0" stopColor={theme.backgroundColor} stopOpacity={1} />
168
+ <Stop offset="0.35" stopColor={theme.backgroundColor} stopOpacity={0.85} />
169
+ <Stop offset="0.6" stopColor={theme.backgroundColor} stopOpacity={0.5} />
170
+ <Stop offset="0.82" stopColor={theme.backgroundColor} stopOpacity={0.18} />
171
+ <Stop offset="1" stopColor={theme.backgroundColor} stopOpacity={0} />
172
+ </SvgLinearGradient>
173
+ </Defs>
174
+ <Rect
175
+ x="0"
176
+ y="0"
177
+ width="100%"
178
+ height="100%"
179
+ fill="url(#stepTopFade)"
180
+ />
181
+ </Svg>
182
+ </Animated.View>
183
+ </View>
184
+ </View>
91
185
  );
92
186
 
93
187
  if (avoidKeyboard) {
@@ -103,6 +197,19 @@ export function StepShell({
103
197
  return body;
104
198
  }
105
199
 
200
+ // Base vertical padding for the scroll body. Safe-area insets are added on top
201
+ // of these at render time (see `contentContainerStyle` above).
202
+ const BASE_PADDING_TOP = 12;
203
+ const BASE_PADDING_BOTTOM = 28;
204
+ // Height of the background-to-transparent gradient masking the ScrollView's
205
+ // top clip edge. Tall on purpose: a long band makes the dissolve a gradual
206
+ // transition rather than a visible line.
207
+ const TOP_FADE_HEIGHT = 120;
208
+ // Scroll distance (px) over which the fade ramps from invisible (at rest) to
209
+ // fully active. Decoupled from TOP_FADE_HEIGHT so the long gradient still kicks
210
+ // in promptly as the user starts scrolling.
211
+ const FADE_RAMP_DISTANCE = 36;
212
+
106
213
  const styles = StyleSheet.create({
107
214
  flex: {
108
215
  flex: 1,
@@ -110,10 +217,22 @@ const styles = StyleSheet.create({
110
217
  scroll: {
111
218
  flex: 1,
112
219
  },
220
+ scrollWrap: {
221
+ flex: 1,
222
+ },
223
+ topFade: {
224
+ position: 'absolute',
225
+ top: 0,
226
+ left: 0,
227
+ right: 0,
228
+ },
229
+ backStrip: {
230
+ paddingHorizontal: 18,
231
+ },
113
232
  scrollBody: {
114
233
  paddingHorizontal: 18,
115
- paddingTop: 12,
116
- paddingBottom: 28,
234
+ paddingTop: BASE_PADDING_TOP,
235
+ paddingBottom: BASE_PADDING_BOTTOM,
117
236
  },
118
237
  header: {
119
238
  alignItems: 'center',
@@ -31,6 +31,27 @@ import {
31
31
  activateScreenKeepAwake,
32
32
  deactivateScreenKeepAwake,
33
33
  } from '../utils/keepAwake';
34
+ import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
35
+
36
+ /**
37
+ * Mounts `react-native-safe-area-context`'s `SafeAreaProvider` so descendant
38
+ * `useSafeAreaInsets()` calls resolve real device insets (notch / nav bar). The
39
+ * library is loaded dynamically with a fail-safe: hosts that strip it (or that
40
+ * already mount their own provider higher up) still render — a nested provider
41
+ * returns correct insets, and a missing module degrades to zero insets.
42
+ */
43
+ function SafeAreaBoundary({ children }: { children: ReactNode }) {
44
+ try {
45
+ // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
46
+ const mod = require('react-native-safe-area-context');
47
+ const Provider = mod.SafeAreaProvider;
48
+ return (
49
+ <Provider initialMetrics={mod.initialWindowMetrics}>{children}</Provider>
50
+ );
51
+ } catch {
52
+ return <>{children}</>;
53
+ }
54
+ }
34
55
 
35
56
  export interface VelionOnboardingScreenProps {
36
57
  config: VelionConfig;
@@ -69,17 +90,19 @@ export function VelionOnboardingScreen({
69
90
  onExit,
70
91
  }: VelionOnboardingScreenProps) {
71
92
  return (
72
- <ThemeProvider
73
- themeOverrides={config.theme}
74
- colorMode={config.colorMode ?? 'auto'}
75
- >
76
- <VelionOnboardingInner
77
- config={config}
78
- onComplete={onComplete}
79
- onFail={onFail}
80
- onExit={onExit}
81
- />
82
- </ThemeProvider>
93
+ <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>
105
+ </SafeAreaBoundary>
83
106
  );
84
107
  }
85
108
 
@@ -90,6 +113,7 @@ function VelionOnboardingInner({
90
113
  onExit,
91
114
  }: VelionOnboardingScreenProps) {
92
115
  const theme = useTheme();
116
+ const insets = useSafeAreaInsets();
93
117
  const t = getStrings(config.locale);
94
118
  const [state, setState] = useState<ViewState>(INITIAL_STATE);
95
119
  const [progress, setProgress] = useState(0);
@@ -214,10 +238,20 @@ function VelionOnboardingInner({
214
238
 
215
239
  return (
216
240
  <View style={[styles.root, { backgroundColor: theme.backgroundColor }]}>
241
+ {/* Content fills the screen edge-to-edge so camera / map steps stay
242
+ full-bleed. The progress bar floats on top, pushed below the top
243
+ safe-area inset (status bar / notch / punch-hole). Form steps offset
244
+ their own header via StepShell, and camera steps offset their chrome
245
+ internally — so we never inset the content container here. */}
246
+ <View style={styles.content}>{renderBody()}</View>
217
247
  {showProgress ? (
218
- <ProgressBar value={progress} hidden={progressHidden} />
248
+ <View
249
+ pointerEvents="none"
250
+ style={[styles.progressOverlay, { paddingTop: insets.top }]}
251
+ >
252
+ <ProgressBar value={progress} hidden={progressHidden} />
253
+ </View>
219
254
  ) : null}
220
- <View style={styles.content}>{renderBody()}</View>
221
255
  {showLoadingOverlay ? <LoadingOverlay message={loadingText} /> : null}
222
256
  </View>
223
257
  );
@@ -231,6 +265,12 @@ const styles = StyleSheet.create({
231
265
  flex: 1,
232
266
  overflow: 'hidden',
233
267
  },
268
+ progressOverlay: {
269
+ position: 'absolute',
270
+ top: 0,
271
+ left: 0,
272
+ right: 0,
273
+ },
234
274
  message: {
235
275
  flex: 1,
236
276
  alignItems: 'center',
@@ -11,6 +11,13 @@ import { useEffect, useRef } from 'react';
11
11
  import { Animated, StyleSheet } from 'react-native';
12
12
  import { mixHex, useReducedMotion, useTheme } from '../theme';
13
13
 
14
+ /**
15
+ * Height of the progress track, in px. Exported so layout-aware chrome (e.g.
16
+ * `StepShell`'s fixed back-button strip) can sit flush below the bar without
17
+ * duplicating the magic number.
18
+ */
19
+ export const PROGRESS_BAR_HEIGHT = 4;
20
+
14
21
  export interface ProgressBarProps {
15
22
  /** 0–100. Components compute the trickling logic externally and pass it in. */
16
23
  value: number;
@@ -89,7 +96,7 @@ export const PROGRESS_BAR = {
89
96
 
90
97
  const styles = StyleSheet.create({
91
98
  track: {
92
- height: 4,
99
+ height: PROGRESS_BAR_HEIGHT,
93
100
  width: '100%',
94
101
  overflow: 'hidden',
95
102
  },