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

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 (45) hide show
  1. package/lib/commonjs/camera/DocumentCapture.js +67 -26
  2. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  3. package/lib/commonjs/i18n/strings/en.js +1 -0
  4. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  5. package/lib/commonjs/i18n/strings/es.js +1 -0
  6. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  7. package/lib/commonjs/steps/DocumentsOcrStep.js +105 -23
  8. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  9. package/lib/commonjs/steps/PhoneContactStep.js +10 -4
  10. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  11. package/lib/commonjs/steps/PhoneOtpStep.js +17 -6
  12. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  13. package/lib/commonjs/utils/documentCrop.js +115 -0
  14. package/lib/commonjs/utils/documentCrop.js.map +1 -0
  15. package/lib/module/camera/DocumentCapture.js +67 -26
  16. package/lib/module/camera/DocumentCapture.js.map +1 -1
  17. package/lib/module/i18n/strings/en.js +1 -0
  18. package/lib/module/i18n/strings/en.js.map +1 -1
  19. package/lib/module/i18n/strings/es.js +1 -0
  20. package/lib/module/i18n/strings/es.js.map +1 -1
  21. package/lib/module/steps/DocumentsOcrStep.js +105 -23
  22. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  23. package/lib/module/steps/PhoneContactStep.js +10 -4
  24. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  25. package/lib/module/steps/PhoneOtpStep.js +17 -6
  26. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  27. package/lib/module/utils/documentCrop.js +109 -0
  28. package/lib/module/utils/documentCrop.js.map +1 -0
  29. package/lib/typescript/camera/DocumentCapture.d.ts +20 -8
  30. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  31. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  32. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  33. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  34. package/lib/typescript/steps/DocumentsOcrStep.d.ts +8 -6
  35. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  36. package/lib/typescript/utils/documentCrop.d.ts +62 -0
  37. package/lib/typescript/utils/documentCrop.d.ts.map +1 -0
  38. package/package.json +1 -1
  39. package/src/camera/DocumentCapture.tsx +66 -25
  40. package/src/i18n/strings/en.ts +1 -0
  41. package/src/i18n/strings/es.ts +1 -0
  42. package/src/steps/DocumentsOcrStep.tsx +129 -24
  43. package/src/steps/PhoneContactStep.tsx +9 -3
  44. package/src/steps/PhoneOtpStep.tsx +14 -4
  45. package/src/utils/documentCrop.ts +138 -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,55 @@ 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
+ // Probe pass: a no-op manipulate returns the *orientation-normalized*
416
+ // dimensions (portrait when the device is portrait). Relying on raw
417
+ // `photo.width/height` is unsafe — iOS reports landscape sensor dims with an
418
+ // EXIF rotation flag, which would mismatch the screen-space guide.
419
+ const probe = await ImageManipulator.manipulateAsync(source, [], {
420
+ compress: 1,
421
+ format: ImageManipulator.SaveFormat.JPEG,
422
+ });
423
+
424
+ const crop = computeGuideCropRect({
425
+ screenW: guide.screenW,
426
+ screenH: guide.screenH,
427
+ imageW: probe.width,
428
+ imageH: probe.height,
429
+ cutout: guide.cutout,
430
+ });
431
+
432
+ // Crop to the guide, then resize the long edge to MAX_LONG_EDGE (never
433
+ // upscale — the crop can leave a small region) and recompress to ~78%.
434
+ const actions: ImageManipulator.Action[] = [
435
+ {
436
+ crop: {
437
+ originX: crop.x,
438
+ originY: crop.y,
439
+ width: crop.width,
440
+ height: crop.height,
441
+ },
442
+ },
443
+ ];
444
+ const longEdge = Math.max(crop.width, crop.height);
445
+ if (longEdge > MAX_LONG_EDGE) {
446
+ actions.push({
447
+ resize:
448
+ crop.width >= crop.height
449
+ ? { width: MAX_LONG_EDGE }
450
+ : { height: MAX_LONG_EDGE },
451
+ });
452
+ }
453
+
454
+ const result = await ImageManipulator.manipulateAsync(probe.uri, actions, {
455
+ compress: COMPRESS_QUALITY,
456
+ format: ImageManipulator.SaveFormat.JPEG,
457
+ });
382
458
  const byteLength = await fetchByteLength(result.uri);
383
459
  return {
384
460
  uri: result.uri,
@@ -411,6 +487,25 @@ async function fetchByteLength(uri: string): Promise<number> {
411
487
  return blob.size;
412
488
  }
413
489
 
490
+ /**
491
+ * Fit a `width/height` box of the given aspect ratio inside `boxW × boxH`
492
+ * (contain). Returns the largest size that keeps the aspect ratio and fits —
493
+ * so the framed preview hugs the capture with no empty bands.
494
+ */
495
+ function fitContain(
496
+ aspect: number,
497
+ boxW: number,
498
+ boxH: number,
499
+ ): { width: number; height: number } {
500
+ let width = boxW;
501
+ let height = boxW / aspect;
502
+ if (height > boxH) {
503
+ height = boxH;
504
+ width = boxH * aspect;
505
+ }
506
+ return { width, height };
507
+ }
508
+
414
509
  function normalizeFileUri(uri: string): string {
415
510
  // Vision-camera returns paths with a leading `/var/mobile/...` on iOS
416
511
  // (no scheme) — `expo-image-manipulator` requires a `file://` prefix.
@@ -467,6 +562,16 @@ const styles = StyleSheet.create({
467
562
  alignItems: 'center',
468
563
  justifyContent: 'center',
469
564
  },
565
+ previewCard: {
566
+ borderWidth: 1,
567
+ overflow: 'hidden',
568
+ // Subtle lift so the framed capture reads as a deliberate card.
569
+ shadowColor: '#000',
570
+ shadowOpacity: 0.12,
571
+ shadowRadius: 10,
572
+ shadowOffset: { width: 0, height: 4 },
573
+ elevation: 3,
574
+ },
470
575
  preview: {
471
576
  width: '100%',
472
577
  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
@@ -0,0 +1,138 @@
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
+ export function computeGuideCropRect(params: {
92
+ screenW: number;
93
+ screenH: number;
94
+ imageW: number;
95
+ imageH: number;
96
+ cutout: CutoutRect;
97
+ margin?: number;
98
+ }): PixelRect {
99
+ const {
100
+ screenW,
101
+ screenH,
102
+ imageW,
103
+ imageH,
104
+ cutout,
105
+ margin = DEFAULT_CROP_MARGIN,
106
+ } = params;
107
+
108
+ const scale = Math.max(screenW / imageW, screenH / imageH);
109
+ // Image pixels hidden off each edge by the cover crop.
110
+ const offsetX = (imageW - screenW / scale) / 2;
111
+ const offsetY = (imageH - screenH / scale) / 2;
112
+
113
+ let x = offsetX + cutout.left / scale;
114
+ let y = offsetY + cutout.top / scale;
115
+ let width = cutout.width / scale;
116
+ let height = cutout.height / scale;
117
+
118
+ // Expand by the safety margin.
119
+ const mx = width * margin;
120
+ const my = height * margin;
121
+ x -= mx;
122
+ y -= my;
123
+ width += mx * 2;
124
+ height += my * 2;
125
+
126
+ // Clamp to image bounds.
127
+ x = Math.max(0, x);
128
+ y = Math.max(0, y);
129
+ width = Math.min(width, imageW - x);
130
+ height = Math.min(height, imageH - y);
131
+
132
+ return {
133
+ x: Math.round(x),
134
+ y: Math.round(y),
135
+ width: Math.round(width),
136
+ height: Math.round(height),
137
+ };
138
+ }