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

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 (59) hide show
  1. package/CHANGELOG.md +16 -1
  2. package/lib/commonjs/camera/DocumentCapture.js +78 -26
  3. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  4. package/lib/commonjs/i18n/strings/en.js +3 -2
  5. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  6. package/lib/commonjs/i18n/strings/es.js +3 -2
  7. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  8. package/lib/commonjs/steps/DocumentsOcrStep.js +152 -35
  9. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  10. package/lib/commonjs/steps/PhoneContactStep.js +10 -4
  11. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  12. package/lib/commonjs/steps/PhoneOtpStep.js +17 -6
  13. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  14. package/lib/commonjs/ui/StepShell.js +122 -12
  15. package/lib/commonjs/ui/StepShell.js.map +1 -1
  16. package/lib/commonjs/ui/overlays/ProgressBar.js +8 -2
  17. package/lib/commonjs/ui/overlays/ProgressBar.js.map +1 -1
  18. package/lib/commonjs/utils/documentCrop.js +136 -0
  19. package/lib/commonjs/utils/documentCrop.js.map +1 -0
  20. package/lib/module/camera/DocumentCapture.js +78 -26
  21. package/lib/module/camera/DocumentCapture.js.map +1 -1
  22. package/lib/module/i18n/strings/en.js +3 -2
  23. package/lib/module/i18n/strings/en.js.map +1 -1
  24. package/lib/module/i18n/strings/es.js +3 -2
  25. package/lib/module/i18n/strings/es.js.map +1 -1
  26. package/lib/module/steps/DocumentsOcrStep.js +152 -34
  27. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  28. package/lib/module/steps/PhoneContactStep.js +10 -4
  29. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  30. package/lib/module/steps/PhoneOtpStep.js +17 -6
  31. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  32. package/lib/module/ui/StepShell.js +122 -13
  33. package/lib/module/ui/StepShell.js.map +1 -1
  34. package/lib/module/ui/overlays/ProgressBar.js +8 -1
  35. package/lib/module/ui/overlays/ProgressBar.js.map +1 -1
  36. package/lib/module/utils/documentCrop.js +129 -0
  37. package/lib/module/utils/documentCrop.js.map +1 -0
  38. package/lib/typescript/camera/DocumentCapture.d.ts +20 -8
  39. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  40. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  41. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  42. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  43. package/lib/typescript/steps/DocumentsOcrStep.d.ts +8 -6
  44. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  45. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  46. package/lib/typescript/ui/overlays/ProgressBar.d.ts +6 -0
  47. package/lib/typescript/ui/overlays/ProgressBar.d.ts.map +1 -1
  48. package/lib/typescript/utils/documentCrop.d.ts +78 -0
  49. package/lib/typescript/utils/documentCrop.d.ts.map +1 -0
  50. package/package.json +1 -1
  51. package/src/camera/DocumentCapture.tsx +76 -25
  52. package/src/i18n/strings/en.ts +3 -2
  53. package/src/i18n/strings/es.ts +3 -2
  54. package/src/steps/DocumentsOcrStep.tsx +180 -32
  55. package/src/steps/PhoneContactStep.tsx +9 -3
  56. package/src/steps/PhoneOtpStep.tsx +14 -4
  57. package/src/ui/StepShell.tsx +114 -12
  58. package/src/ui/overlays/ProgressBar.tsx +8 -1
  59. package/src/utils/documentCrop.ts +159 -0
@@ -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,24 @@
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';
20
28
  import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
21
29
 
22
30
  export interface StepShellProps {
@@ -53,26 +61,41 @@ export function StepShell({
53
61
  const insets = useSafeAreaInsets();
54
62
 
55
63
  const showIconCircle = !theme.hideStepIcons && iconNode != null;
64
+ const showBack = onBack != null;
56
65
 
57
- const body = (
58
- <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
59
78
  style={styles.scroll}
60
- // Add the device safe-area insets to the base padding so the header
61
- // (icon + title) clears the top camera / notch and the trailing CTA
62
- // clears the bottom navigation bar / gesture area on edge-to-edge
63
- // Android and on iOS devices with a home indicator.
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.
64
90
  contentContainerStyle={[
65
91
  styles.scrollBody,
66
92
  {
67
- paddingTop: BASE_PADDING_TOP + insets.top,
93
+ paddingTop: showBack ? BASE_PADDING_TOP : BASE_PADDING_TOP + insets.top,
68
94
  paddingBottom: BASE_PADDING_BOTTOM + insets.bottom,
69
95
  },
70
96
  ]}
71
97
  keyboardShouldPersistTaps="handled"
72
98
  >
73
- {onBack ? (
74
- <BackButton label={backLabel} onPress={onBack} disabled={backDisabled} />
75
- ) : null}
76
99
  <View style={styles.header}>
77
100
  {showIconCircle ? (
78
101
  <View
@@ -99,7 +122,66 @@ export function StepShell({
99
122
  ) : null}
100
123
  </View>
101
124
  <View style={styles.column}>{children}</View>
102
- </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>
103
185
  );
104
186
 
105
187
  if (avoidKeyboard) {
@@ -119,6 +201,14 @@ export function StepShell({
119
201
  // of these at render time (see `contentContainerStyle` above).
120
202
  const BASE_PADDING_TOP = 12;
121
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;
122
212
 
123
213
  const styles = StyleSheet.create({
124
214
  flex: {
@@ -127,6 +217,18 @@ const styles = StyleSheet.create({
127
217
  scroll: {
128
218
  flex: 1,
129
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
+ },
130
232
  scrollBody: {
131
233
  paddingHorizontal: 18,
132
234
  paddingTop: BASE_PADDING_TOP,
@@ -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
  },
@@ -0,0 +1,159 @@
1
+ /**
2
+ * @fileoverview Geometry for the document capture guide + crop.
3
+ *
4
+ * Two pure helpers, shared between the camera overlay and the post-capture
5
+ * crop so the pixels we keep are *exactly* the rectangle the user framed:
6
+ *
7
+ * - `computeCutout` — the on-screen ID-1 guide rectangle (screen px).
8
+ * - `computeGuideCropRect` — maps that guide rectangle into the captured
9
+ * photo's pixel space, compensating for the camera preview's `cover` fit
10
+ * (the preview center-crops the sensor frame to the screen aspect ratio).
11
+ *
12
+ * This is a *geometric* crop to a fixed guide, NOT edge detection / OpenCV —
13
+ * we never inspect pixels. The backend's Document AI still runs OCR and its
14
+ * own face crop on top, so we keep a safety margin around the guide to avoid
15
+ * clipping the document (or the portrait the backend needs).
16
+ */
17
+
18
+ import type { DocumentOrientation } from '../types';
19
+
20
+ export interface CutoutRect {
21
+ left: number;
22
+ top: number;
23
+ width: number;
24
+ height: number;
25
+ }
26
+
27
+ export interface PixelRect {
28
+ x: number;
29
+ y: number;
30
+ width: number;
31
+ height: number;
32
+ }
33
+
34
+ // ID-1 aspect ratios (width / height). Portrait ≈ 0.625 (held vertically),
35
+ // landscape ≈ 1.586 (the real ID-1 card ratio, 85.6 × 53.98 mm).
36
+ const PORTRAIT_ASPECT = 0.625;
37
+ const LANDSCAPE_ASPECT = 1.586;
38
+
39
+ // The guide is 85% of screen width, but never taller than 62% of screen height
40
+ // (portrait ID-1 on tall phones would otherwise overflow).
41
+ const CUTOUT_WIDTH_RATIO = 0.85;
42
+ const CUTOUT_MAX_HEIGHT_RATIO = 0.62;
43
+
44
+ /** Default crop margin: expand each side of the guide by this fraction of the
45
+ * guide size, so a document slightly overflowing the frame isn't clipped. */
46
+ export const DEFAULT_CROP_MARGIN = 0.07;
47
+
48
+ /**
49
+ * The on-screen guide rectangle, in screen pixels. Mirrors what the mask
50
+ * overlay draws so the crop matches the visible cutout exactly.
51
+ */
52
+ export function computeCutout(
53
+ screenW: number,
54
+ screenH: number,
55
+ orientation: DocumentOrientation,
56
+ ): CutoutRect {
57
+ const aspectRatio =
58
+ orientation === 'portrait' ? PORTRAIT_ASPECT : LANDSCAPE_ASPECT;
59
+
60
+ let width = screenW * CUTOUT_WIDTH_RATIO;
61
+ let height = width / aspectRatio;
62
+ const maxH = screenH * CUTOUT_MAX_HEIGHT_RATIO;
63
+ if (height > maxH) {
64
+ height = maxH;
65
+ width = height * aspectRatio;
66
+ }
67
+ return {
68
+ left: (screenW - width) / 2,
69
+ top: (screenH - height) / 2,
70
+ width,
71
+ height,
72
+ };
73
+ }
74
+
75
+ /**
76
+ * Map the on-screen guide rectangle into the captured photo's pixel space.
77
+ *
78
+ * The preview renders the photo with `cover` fit: the sensor frame is scaled
79
+ * up until it fills the screen and the overflow is center-cropped. So a screen
80
+ * point `(sx, sy)` maps to photo pixel `((W_img - W_screen/s)/2 + sx/s, …)`,
81
+ * where `s = max(W_screen/W_img, H_screen/H_img)`.
82
+ *
83
+ * `imageW`/`imageH` MUST be the photo's *display* (orientation-normalized)
84
+ * dimensions — i.e. portrait when the device is portrait — not the raw sensor
85
+ * dimensions, which are often landscape with an EXIF rotation flag.
86
+ *
87
+ * The result is expanded by `margin` (fraction of the mapped guide) and
88
+ * clamped to the image bounds, then rounded to integers (the manipulator
89
+ * rejects fractional crop rects).
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
+
112
+ export function computeGuideCropRect(params: {
113
+ screenW: number;
114
+ screenH: number;
115
+ imageW: number;
116
+ imageH: number;
117
+ cutout: CutoutRect;
118
+ margin?: number;
119
+ }): PixelRect {
120
+ const {
121
+ screenW,
122
+ screenH,
123
+ imageW,
124
+ imageH,
125
+ cutout,
126
+ margin = DEFAULT_CROP_MARGIN,
127
+ } = params;
128
+
129
+ const scale = Math.max(screenW / imageW, screenH / imageH);
130
+ // Image pixels hidden off each edge by the cover crop.
131
+ const offsetX = (imageW - screenW / scale) / 2;
132
+ const offsetY = (imageH - screenH / scale) / 2;
133
+
134
+ let x = offsetX + cutout.left / scale;
135
+ let y = offsetY + cutout.top / scale;
136
+ let width = cutout.width / scale;
137
+ let height = cutout.height / scale;
138
+
139
+ // Expand by the safety margin.
140
+ const mx = width * margin;
141
+ const my = height * margin;
142
+ x -= mx;
143
+ y -= my;
144
+ width += mx * 2;
145
+ height += my * 2;
146
+
147
+ // Clamp to image bounds.
148
+ x = Math.max(0, x);
149
+ y = Math.max(0, y);
150
+ width = Math.min(width, imageW - x);
151
+ height = Math.min(height, imageH - y);
152
+
153
+ return {
154
+ x: Math.round(x),
155
+ y: Math.round(y),
156
+ width: Math.round(width),
157
+ height: Math.round(height),
158
+ };
159
+ }