@velion-la/onboarding-sdk-react-native 1.4.0-beta.7 → 1.4.0-beta.9

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 (135) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +82 -1
  3. package/lib/commonjs/core/VelionOnboarding.js +156 -46
  4. package/lib/commonjs/core/VelionOnboarding.js.map +1 -1
  5. package/lib/commonjs/core/routingCommands.js +33 -0
  6. package/lib/commonjs/core/routingCommands.js.map +1 -1
  7. package/lib/commonjs/core/sessionStateMapper.js +48 -36
  8. package/lib/commonjs/core/sessionStateMapper.js.map +1 -1
  9. package/lib/commonjs/i18n/strings/en.js +27 -0
  10. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  11. package/lib/commonjs/i18n/strings/es.js +27 -0
  12. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  13. package/lib/commonjs/index.js +6 -0
  14. package/lib/commonjs/index.js.map +1 -1
  15. package/lib/commonjs/steps/CustomFormStep.js +348 -0
  16. package/lib/commonjs/steps/CustomFormStep.js.map +1 -0
  17. package/lib/commonjs/steps/EntityTypeSelectionStep.js +194 -0
  18. package/lib/commonjs/steps/EntityTypeSelectionStep.js.map +1 -0
  19. package/lib/commonjs/steps/customForm.js +251 -0
  20. package/lib/commonjs/steps/customForm.js.map +1 -0
  21. package/lib/commonjs/steps/entityType.js +30 -0
  22. package/lib/commonjs/steps/entityType.js.map +1 -0
  23. package/lib/commonjs/steps/submissionOutcome.js +101 -0
  24. package/lib/commonjs/steps/submissionOutcome.js.map +1 -0
  25. package/lib/commonjs/steps/unsupportedStep.js +33 -0
  26. package/lib/commonjs/steps/unsupportedStep.js.map +1 -0
  27. package/lib/commonjs/transport/api.js +9 -0
  28. package/lib/commonjs/transport/api.js.map +1 -1
  29. package/lib/commonjs/types/index.js +60 -4
  30. package/lib/commonjs/types/index.js.map +1 -1
  31. package/lib/commonjs/ui/VelionOnboardingScreen.js +20 -3
  32. package/lib/commonjs/ui/VelionOnboardingScreen.js.map +1 -1
  33. package/lib/commonjs/ui/primitives/RadioCard.js +120 -0
  34. package/lib/commonjs/ui/primitives/RadioCard.js.map +1 -0
  35. package/lib/commonjs/ui/primitives/Select.js +60 -7
  36. package/lib/commonjs/ui/primitives/Select.js.map +1 -1
  37. package/lib/commonjs/ui/primitives/index.js +7 -0
  38. package/lib/commonjs/ui/primitives/index.js.map +1 -1
  39. package/lib/commonjs/utils/sdkVersion.js +1 -1
  40. package/lib/module/core/VelionOnboarding.js +158 -48
  41. package/lib/module/core/VelionOnboarding.js.map +1 -1
  42. package/lib/module/core/routingCommands.js +33 -0
  43. package/lib/module/core/routingCommands.js.map +1 -1
  44. package/lib/module/core/sessionStateMapper.js +47 -36
  45. package/lib/module/core/sessionStateMapper.js.map +1 -1
  46. package/lib/module/i18n/strings/en.js +27 -0
  47. package/lib/module/i18n/strings/en.js.map +1 -1
  48. package/lib/module/i18n/strings/es.js +27 -0
  49. package/lib/module/i18n/strings/es.js.map +1 -1
  50. package/lib/module/index.js +1 -1
  51. package/lib/module/index.js.map +1 -1
  52. package/lib/module/steps/CustomFormStep.js +345 -0
  53. package/lib/module/steps/CustomFormStep.js.map +1 -0
  54. package/lib/module/steps/EntityTypeSelectionStep.js +189 -0
  55. package/lib/module/steps/EntityTypeSelectionStep.js.map +1 -0
  56. package/lib/module/steps/customForm.js +237 -0
  57. package/lib/module/steps/customForm.js.map +1 -0
  58. package/lib/module/steps/entityType.js +24 -0
  59. package/lib/module/steps/entityType.js.map +1 -0
  60. package/lib/module/steps/submissionOutcome.js +94 -0
  61. package/lib/module/steps/submissionOutcome.js.map +1 -0
  62. package/lib/module/steps/unsupportedStep.js +30 -0
  63. package/lib/module/steps/unsupportedStep.js.map +1 -0
  64. package/lib/module/transport/api.js +9 -0
  65. package/lib/module/transport/api.js.map +1 -1
  66. package/lib/module/types/index.js +68 -3
  67. package/lib/module/types/index.js.map +1 -1
  68. package/lib/module/ui/VelionOnboardingScreen.js +21 -4
  69. package/lib/module/ui/VelionOnboardingScreen.js.map +1 -1
  70. package/lib/module/ui/primitives/RadioCard.js +116 -0
  71. package/lib/module/ui/primitives/RadioCard.js.map +1 -0
  72. package/lib/module/ui/primitives/Select.js +62 -9
  73. package/lib/module/ui/primitives/Select.js.map +1 -1
  74. package/lib/module/ui/primitives/index.js +1 -0
  75. package/lib/module/ui/primitives/index.js.map +1 -1
  76. package/lib/module/utils/sdkVersion.js +1 -1
  77. package/lib/typescript/core/VelionOnboarding.d.ts +42 -5
  78. package/lib/typescript/core/VelionOnboarding.d.ts.map +1 -1
  79. package/lib/typescript/core/routingCommands.d.ts +23 -0
  80. package/lib/typescript/core/routingCommands.d.ts.map +1 -1
  81. package/lib/typescript/core/sessionStateMapper.d.ts +13 -5
  82. package/lib/typescript/core/sessionStateMapper.d.ts.map +1 -1
  83. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  84. package/lib/typescript/i18n/strings/es.d.ts +27 -0
  85. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  86. package/lib/typescript/index.d.ts +3 -3
  87. package/lib/typescript/index.d.ts.map +1 -1
  88. package/lib/typescript/steps/CustomFormStep.d.ts +28 -0
  89. package/lib/typescript/steps/CustomFormStep.d.ts.map +1 -0
  90. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts +24 -0
  91. package/lib/typescript/steps/EntityTypeSelectionStep.d.ts.map +1 -0
  92. package/lib/typescript/steps/customForm.d.ts +99 -0
  93. package/lib/typescript/steps/customForm.d.ts.map +1 -0
  94. package/lib/typescript/steps/entityType.d.ts +15 -0
  95. package/lib/typescript/steps/entityType.d.ts.map +1 -0
  96. package/lib/typescript/steps/submissionOutcome.d.ts +43 -0
  97. package/lib/typescript/steps/submissionOutcome.d.ts.map +1 -0
  98. package/lib/typescript/steps/types.d.ts +5 -0
  99. package/lib/typescript/steps/types.d.ts.map +1 -1
  100. package/lib/typescript/steps/unsupportedStep.d.ts +15 -0
  101. package/lib/typescript/steps/unsupportedStep.d.ts.map +1 -0
  102. package/lib/typescript/transport/api.d.ts +1 -0
  103. package/lib/typescript/transport/api.d.ts.map +1 -1
  104. package/lib/typescript/types/index.d.ts +139 -14
  105. package/lib/typescript/types/index.d.ts.map +1 -1
  106. package/lib/typescript/ui/VelionOnboardingScreen.d.ts +21 -2
  107. package/lib/typescript/ui/VelionOnboardingScreen.d.ts.map +1 -1
  108. package/lib/typescript/ui/primitives/RadioCard.d.ts +22 -0
  109. package/lib/typescript/ui/primitives/RadioCard.d.ts.map +1 -0
  110. package/lib/typescript/ui/primitives/Select.d.ts +9 -3
  111. package/lib/typescript/ui/primitives/Select.d.ts.map +1 -1
  112. package/lib/typescript/ui/primitives/index.d.ts +1 -0
  113. package/lib/typescript/ui/primitives/index.d.ts.map +1 -1
  114. package/lib/typescript/utils/sdkVersion.d.ts +1 -1
  115. package/package.json +1 -1
  116. package/src/core/VelionOnboarding.ts +168 -55
  117. package/src/core/routingCommands.ts +42 -0
  118. package/src/core/sessionStateMapper.ts +63 -52
  119. package/src/i18n/strings/en.ts +28 -0
  120. package/src/i18n/strings/es.ts +28 -0
  121. package/src/index.ts +10 -0
  122. package/src/steps/CustomFormStep.tsx +400 -0
  123. package/src/steps/EntityTypeSelectionStep.tsx +207 -0
  124. package/src/steps/customForm.ts +302 -0
  125. package/src/steps/entityType.ts +25 -0
  126. package/src/steps/submissionOutcome.ts +93 -0
  127. package/src/steps/types.ts +5 -0
  128. package/src/steps/unsupportedStep.ts +32 -0
  129. package/src/transport/api.ts +16 -1
  130. package/src/types/index.ts +151 -17
  131. package/src/ui/VelionOnboardingScreen.tsx +38 -1
  132. package/src/ui/primitives/RadioCard.tsx +127 -0
  133. package/src/ui/primitives/Select.tsx +73 -7
  134. package/src/ui/primitives/index.ts +1 -0
  135. package/src/utils/sdkVersion.ts +1 -1
@@ -25,6 +25,11 @@
25
25
  * - `ECONOMIC_ACTIVITY_DECLARATION`: pick exactly one economic activity from a searchable list.
26
26
  * - `TERMS_AND_CONDITIONS`: accept configured T&C items.
27
27
  * - `FACE_MATCH`: server-side face comparison after liveness (no user input; SDK waits).
28
+ * - `CUSTOM_FORM`: form built from the workflow's `form_fields`. A workflow may hold
29
+ * several, told apart by their `step_key`.
30
+ * - `ENTITY_TYPE_SELECTION`: the person picks HUMAN or LEGAL; the backend branches on it.
31
+ *
32
+ * A code outside this list fails the flow with {@link SdkErrorCode.UNSUPPORTED_STEP}.
28
33
  */
29
34
  export type OnboardingStep =
30
35
  | 'DEVICE_FINGERPRINT'
@@ -43,7 +48,9 @@ export type OnboardingStep =
43
48
  | 'DOCUMENTS_OCR'
44
49
  | 'LIVENESS_MATCH'
45
50
  | 'FACE_MATCH'
46
- | 'TERMS_AND_CONDITIONS';
51
+ | 'TERMS_AND_CONDITIONS'
52
+ | 'CUSTOM_FORM'
53
+ | 'ENTITY_TYPE_SELECTION';
47
54
 
48
55
  /**
49
56
  * Status of an individual onboarding step (matches backend OnboardingStepStatus).
@@ -56,10 +63,16 @@ export type OnboardingStepStatus =
56
63
  | 'FAILED';
57
64
 
58
65
  /**
59
- * Type of onboarding session (matches backend OnboardingType).
60
- * Constrains which steps are valid: HUMAN allows biometric steps, LEGAL uses entity data.
66
+ * Choice of the `ENTITY_TYPE_SELECTION` step (`selected_type`): a natural
67
+ * person (`HUMAN`) or a legal entity (`LEGAL`).
68
+ */
69
+ export type EntityType = 'HUMAN' | 'LEGAL';
70
+
71
+ /**
72
+ * @deprecated The session DTO no longer carries an `onboarding_type`; the
73
+ * person picks it in `ENTITY_TYPE_SELECTION`. Use {@link EntityType}.
61
74
  */
62
- export type OnboardingType = 'HUMAN' | 'LEGAL';
75
+ export type OnboardingType = EntityType;
63
76
 
64
77
  /** Which face of the ID document is being captured. */
65
78
  export type DocumentSide = 'FRONT' | 'BACK';
@@ -212,8 +225,59 @@ export interface TermsAndConditionsStepConfig {
212
225
  terms?: Array<{ title?: string; url?: string }>;
213
226
  }
214
227
 
215
- /** Generic per-step runtime config map carried by session state and SSE. */
216
- export type StepConfigMap = Partial<Record<OnboardingStep, Record<string, unknown>>>;
228
+ /**
229
+ * Field types a `CUSTOM_FORM` can declare. The SDK renders a field whose type it
230
+ * does not know as `TEXT` when it is optional, and fails the step with
231
+ * `UNSUPPORTED_STEP` when it is required.
232
+ */
233
+ export type CustomFormFieldType = 'TEXT' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'LIST';
234
+
235
+ /** One field of a `CUSTOM_FORM` (`config.form_fields[]`). */
236
+ export interface CustomFormField {
237
+ /** Key of the answer in `responses`. */
238
+ field_key: string;
239
+ /** Label shown to the person. */
240
+ name: string;
241
+ /** Optional help text under the label. */
242
+ description?: string | null;
243
+ /** Field type; a string the SDK does not know is handled as described in {@link CustomFormFieldType}. */
244
+ type: CustomFormFieldType | string;
245
+ required?: boolean;
246
+ /** Choices of a `LIST` field (single selection). */
247
+ options?: string[] | null;
248
+ }
249
+
250
+ /** STEP config for CUSTOM_FORM (`current_step.config`, SSE `step_config`). */
251
+ export interface CustomFormStepConfig {
252
+ /** Screen title; the SDK shows its own generic title when absent. */
253
+ title?: string | null;
254
+ /** Screen subtitle; omitted when absent. */
255
+ subtitle?: string | null;
256
+ form_fields?: CustomFormField[];
257
+ reversible?: boolean;
258
+ }
259
+
260
+ /** A `CUSTOM_FORM` answer, typed per {@link CustomFormFieldType}: DATE is `yyyy-MM-dd`, LIST one of `options`. */
261
+ export type CustomFormResponseValue = string | number | boolean;
262
+
263
+ /**
264
+ * POST /sessions/:id/custom-form/:stepKey. An optional field left unanswered is
265
+ * omitted, never sent as `null`.
266
+ */
267
+ export interface CustomFormSubmitPayload {
268
+ responses: Record<string, CustomFormResponseValue>;
269
+ }
270
+
271
+ /** POST /sessions/:id/entity-type. */
272
+ export interface EntityTypeSelectionPayload {
273
+ selected_type: EntityType;
274
+ }
275
+
276
+ /**
277
+ * Per-step runtime config cache carried by session state and SSE, keyed by the
278
+ * step instance (`step_key`, or the step code when the backend sends no key).
279
+ */
280
+ export type StepConfigMap = Record<string, Record<string, unknown>>;
217
281
 
218
282
  /**
219
283
  * Request body for POST /sessions/:sessionId/documents-init.
@@ -363,6 +427,14 @@ export enum SdkErrorCode {
363
427
  */
364
428
  INTEGRITY_FAILED = 'INTEGRITY_FAILED',
365
429
 
430
+ /**
431
+ * The backend routed the session to a step this SDK version cannot render: a
432
+ * step code it does not know, or a `CUSTOM_FORM` with a required field of an
433
+ * unknown type. `stepCode` and `stepKey` name the step. The step is not
434
+ * skipped (the session would be declined); update the SDK to continue.
435
+ */
436
+ UNSUPPORTED_STEP = 'UNSUPPORTED_STEP',
437
+
366
438
  UNKNOWN = 'UNKNOWN',
367
439
  }
368
440
 
@@ -394,13 +466,21 @@ export interface SdkError {
394
466
  */
395
467
  readonly stepCode?: string;
396
468
  /**
397
- * Localized headline resolved by the SDK for SESSION_DECLINED and SESSION_CANCELLED.
469
+ * Instance key of the step (`step_key`), present when it identifies the step
470
+ * better than `stepCode` alone — e.g. one of several `CUSTOM_FORM`s on
471
+ * `UNSUPPORTED_STEP`.
472
+ */
473
+ readonly stepKey?: string;
474
+ /**
475
+ * Localized headline resolved by the SDK for SESSION_DECLINED, SESSION_CANCELLED
476
+ * and UNSUPPORTED_STEP.
398
477
  * Useful when hosts hide the built-in final result screen but still want
399
478
  * the same user-facing text in custom UI.
400
479
  */
401
480
  readonly declineTitle?: string;
402
481
  /**
403
- * Localized body message resolved by the SDK for SESSION_DECLINED and SESSION_CANCELLED.
482
+ * Localized body message resolved by the SDK for SESSION_DECLINED, SESSION_CANCELLED
483
+ * and UNSUPPORTED_STEP.
404
484
  * Mirrors the text shown in the built-in final result screen.
405
485
  */
406
486
  readonly declineMessage?: string;
@@ -417,6 +497,40 @@ export interface SdkError {
417
497
  readonly cause?: unknown;
418
498
  }
419
499
 
500
+ /**
501
+ * Why `cancelSession()` rejected. The flow keeps running in every case: only a
502
+ * cancellation the backend confirmed ends it.
503
+ */
504
+ export enum CancelSessionErrorCode {
505
+ /**
506
+ * The session is no longer open (409 `VOB-40913`): it already reached a
507
+ * verdict or was closed. Nothing to cancel.
508
+ */
509
+ SESSION_NOT_OPEN = 'SESSION_NOT_OPEN',
510
+ /**
511
+ * The session token was rejected (401/403) or has expired. Rotate it with
512
+ * `refreshSessionToken()` and call `cancelSession()` again.
513
+ */
514
+ UNAUTHORIZED = 'UNAUTHORIZED',
515
+ /**
516
+ * The request did not get through: no connectivity, or the backend answered
517
+ * with an unexpected status (`httpStatus` is set when it answered). Safe to
518
+ * retry.
519
+ */
520
+ NETWORK = 'NETWORK',
521
+ }
522
+
523
+ /** Rejection value of `cancelSession()`. */
524
+ export interface CancelSessionError {
525
+ readonly code: CancelSessionErrorCode;
526
+ /** Developer-facing description. Not intended for end users. */
527
+ readonly message: string;
528
+ /** HTTP status of the backend answer, when there was one. */
529
+ readonly httpStatus?: number;
530
+ /** The underlying error, for debugging. */
531
+ readonly cause?: unknown;
532
+ }
533
+
420
534
  // ─────────────────────────────────────────────────────────────────────────────
421
535
  // THEMING
422
536
  // ─────────────────────────────────────────────────────────────────────────────
@@ -904,6 +1018,12 @@ export interface VelionConfig extends VelionCallbacks {
904
1018
  */
905
1019
  export interface OnboardingStepDto {
906
1020
  code: string;
1021
+ /**
1022
+ * Instance key of the step within the workflow. Equals `code` except for
1023
+ * `CUSTOM_FORM`, whose key is the form slug. Absent on older backends: the
1024
+ * SDK then uses `code`.
1025
+ */
1026
+ step_key?: string;
907
1027
  name?: string;
908
1028
  description?: string;
909
1029
  order?: number;
@@ -911,6 +1031,8 @@ export interface OnboardingStepDto {
911
1031
  required?: boolean;
912
1032
  /** Step-specific payload (e.g. OCR fields, fingerprint, T&amp;C items). */
913
1033
  result?: Record<string, unknown>;
1034
+ /** Step configuration (e.g. `form_fields` of a CUSTOM_FORM). */
1035
+ config?: Record<string, unknown>;
914
1036
  /**
915
1037
  * Whether the user may navigate back into this step after completing it.
916
1038
  * Resolved by the backend (step-type default merged with the workflow
@@ -928,10 +1050,14 @@ export interface OnboardingStepDto {
928
1050
  export interface OnboardingDtoResponse {
929
1051
  id?: string;
930
1052
  related_id?: string;
931
- onboarding_type?: string;
932
1053
  status?: string;
1054
+ /** Step to run. May be omitted; the SDK then takes the first unfinished step of `steps`. */
933
1055
  current_step?: {
934
1056
  code?: string;
1057
+ /** Instance key of the current step (see {@link OnboardingStepDto.step_key}). */
1058
+ step_key?: string;
1059
+ name?: string;
1060
+ description?: string;
935
1061
  status?: string;
936
1062
  config?: Record<string, unknown>;
937
1063
  /** When `true`, the SDK renders the "back" control for this step. */
@@ -970,8 +1096,13 @@ export interface OnboardingDtoResponse {
970
1096
  * (OnboardingDto): steps sorted by order → requiredSteps, first non-completed index → currentStepIndex.
971
1097
  */
972
1098
  export interface SessionState {
973
- /** Current runnable step reported by backend session state. */
1099
+ /** Current runnable step reported by backend session state. Decides the screen. */
974
1100
  currentStep?: OnboardingStep;
1101
+ /**
1102
+ * Instance key of {@link currentStep} (`step_key`, or the code when the backend
1103
+ * sends none). Decides which step instance the SDK answers to.
1104
+ */
1105
+ currentStepKey?: string;
975
1106
  /** Step-specific config for `currentStep` from GET /sessions/:id `current_step.config`. */
976
1107
  currentStepConfig?: Record<string, unknown>;
977
1108
  /**
@@ -986,17 +1117,15 @@ export interface SessionState {
986
1117
  * not carry the flag): a step can go back when any earlier step is reversible
987
1118
  * or the step itself is the first reversible one (back exits).
988
1119
  */
989
- stepReversibility?: Array<{ code: OnboardingStep; reversible: boolean }>;
1120
+ stepReversibility?: Array<{ code: OnboardingStep; stepKey: string; reversible: boolean }>;
990
1121
  /**
991
1122
  * Previously-captured data for `currentStep`, used as form prefill after a
992
1123
  * reverse navigation re-opens a completed step. Sourced from GET
993
1124
  * `current_step.result`.
994
1125
  */
995
1126
  currentStepResult?: Record<string, unknown>;
996
- /** Cached configs discovered from GET session and SSE `step_config`. */
1127
+ /** Cached configs discovered from GET session and SSE `step_config`, keyed by step key. */
997
1128
  stepConfigs?: StepConfigMap;
998
- /** Session type (HUMAN or LEGAL). Constrains which steps are applicable. */
999
- onboardingType?: OnboardingType;
1000
1129
  /** Arbitrary session metadata the backend may attach. */
1001
1130
  metadata?: Record<string, unknown>;
1002
1131
  /**
@@ -1339,8 +1468,13 @@ export interface OnboardingSessionEvent {
1339
1468
  session_id?: number;
1340
1469
  /** Discriminator: STEP_UPDATED | ROUTING_COMMAND | SESSION_APPROVED | SESSION_MANUAL_REVIEW | SESSION_DECLINED | SESSION_CANCELLED */
1341
1470
  event_type?: string;
1342
- /** Present for STEP_UPDATED or ROUTING_COMMAND (next step code). */
1471
+ /** Present for STEP_UPDATED or ROUTING_COMMAND (next step code). Decides the screen. */
1343
1472
  step_code?: string;
1473
+ /**
1474
+ * Instance key of `step_code` on STEP_UPDATED and ROUTING_COMMAND. Tells two
1475
+ * `CUSTOM_FORM`s apart. Absent on older backends: the SDK uses `step_code`.
1476
+ */
1477
+ step_key?: string;
1344
1478
  /** Present for STEP_UPDATED; e.g. COMPLETED. */
1345
1479
  step_status?: string;
1346
1480
  /** Present for terminal events; e.g. APPROVED | MANUAL_REVIEW | REJECTED | DECLINED | CANCELLED. */
@@ -1466,8 +1600,8 @@ export type SdkEventName =
1466
1600
  * @internal
1467
1601
  */
1468
1602
  export interface SdkEventMap extends Record<string, unknown> {
1469
- 'step:change': { step: OnboardingStep; index: number };
1470
- 'step:complete': { step: OnboardingStep };
1603
+ 'step:change': { step: OnboardingStep; stepKey: string; index: number };
1604
+ 'step:complete': { step: OnboardingStep; stepKey: string };
1471
1605
  'session:loaded': SessionState;
1472
1606
  'flow:complete': OnboardingResult;
1473
1607
  'flow:exit': OnboardingExit;
@@ -10,10 +10,12 @@
10
10
  import React, {
11
11
  useCallback,
12
12
  useEffect,
13
+ useImperativeHandle,
13
14
  useMemo,
14
15
  useRef,
15
16
  useState,
16
17
  type ReactNode,
18
+ type Ref,
17
19
  } from 'react';
18
20
  import {
19
21
  StyleSheet,
@@ -58,6 +60,24 @@ function SafeAreaBoundary({ children }: { children: ReactNode }) {
58
60
  }
59
61
  }
60
62
 
63
+ /**
64
+ * Imperative handle exposed through the `ref` of `VelionOnboardingScreen`.
65
+ *
66
+ * @example
67
+ * const ref = useRef<VelionOnboardingScreenHandle>(null);
68
+ * <VelionOnboardingScreen ref={ref} config={config} onFail={onFail} />;
69
+ * await ref.current?.cancelSession();
70
+ */
71
+ export interface VelionOnboardingScreenHandle {
72
+ /** See {@link VelionOnboarding.cancelSession}. */
73
+ cancelSession(): Promise<void>;
74
+ /**
75
+ * See {@link VelionOnboarding.refreshSessionToken}. Rotate the token after
76
+ * `cancelSession()` rejected with `UNAUTHORIZED`, then call it again.
77
+ */
78
+ refreshSessionToken(token: string, expiresAt?: string): void;
79
+ }
80
+
61
81
  export interface VelionOnboardingScreenProps {
62
82
  config: VelionConfig;
63
83
  onComplete?: ((result: OnboardingResult) => void) | undefined;
@@ -69,6 +89,8 @@ export interface VelionOnboardingScreenProps {
69
89
  * context. Mirrors `VelionConfig.onExit`.
70
90
  */
71
91
  onExit?: ((exit: OnboardingExit) => void) | undefined;
92
+ /** Receives the {@link VelionOnboardingScreenHandle} (e.g. `cancelSession()`). */
93
+ ref?: Ref<VelionOnboardingScreenHandle> | undefined;
72
94
  }
73
95
 
74
96
  interface ViewState {
@@ -93,6 +115,7 @@ export function VelionOnboardingScreen({
93
115
  onComplete,
94
116
  onFail,
95
117
  onExit,
118
+ ref,
96
119
  }: VelionOnboardingScreenProps) {
97
120
  return (
98
121
  <SafeAreaBoundary>
@@ -106,6 +129,7 @@ export function VelionOnboardingScreen({
106
129
  onComplete={onComplete}
107
130
  onFail={onFail}
108
131
  onExit={onExit}
132
+ handleRef={ref}
109
133
  />
110
134
  </ThemeProvider>
111
135
  </KeyboardBoundary>
@@ -118,7 +142,10 @@ function VelionOnboardingInner({
118
142
  onComplete,
119
143
  onFail,
120
144
  onExit,
121
- }: VelionOnboardingScreenProps) {
145
+ handleRef,
146
+ }: Omit<VelionOnboardingScreenProps, 'ref'> & {
147
+ handleRef: Ref<VelionOnboardingScreenHandle> | undefined;
148
+ }) {
122
149
  const theme = useTheme();
123
150
  const insets = useScreenInsets();
124
151
  const t = getStrings(config.locale);
@@ -136,6 +163,16 @@ function VelionOnboardingInner({
136
163
  const sdkRef = useRef(sdk);
137
164
  sdkRef.current = sdk;
138
165
 
166
+ useImperativeHandle(
167
+ handleRef,
168
+ () => ({
169
+ cancelSession: () => sdkRef.current.cancelSession(),
170
+ refreshSessionToken: (token: string, expiresAt?: string) =>
171
+ sdkRef.current.refreshSessionToken(token, expiresAt),
172
+ }),
173
+ [],
174
+ );
175
+
139
176
  const onCompleteRef = useRef(onComplete);
140
177
  const onFailRef = useRef(onFail);
141
178
  const onExitRef = useRef(onExit);
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Single-choice option rendered as a tinted card with a radio dot.
3
+ *
4
+ * Same visual family as `Checkbox` `card`, but with `radio` semantics: one card
5
+ * of a group is selected at a time and pressing the selected one keeps it. Used
6
+ * by ENTITY_TYPE_SELECTION (HUMAN / LEGAL) and by the Yes / No answer of a
7
+ * CUSTOM_FORM `BOOLEAN` field, which must tell "no" apart from "not answered".
8
+ */
9
+
10
+ import { Pressable, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
11
+ import { Text } from './Text';
12
+ import { mixHex, useTheme } from '../theme';
13
+
14
+ export interface RadioCardProps {
15
+ selected: boolean;
16
+ onPress: () => void;
17
+ title: string;
18
+ description?: string | undefined;
19
+ disabled?: boolean | undefined;
20
+ /** Draws the border in the error color (the group has a validation error). */
21
+ invalid?: boolean | undefined;
22
+ style?: StyleProp<ViewStyle> | undefined;
23
+ testID?: string | undefined;
24
+ }
25
+
26
+ export function RadioCard({
27
+ selected,
28
+ onPress,
29
+ title,
30
+ description,
31
+ disabled = false,
32
+ invalid = false,
33
+ style,
34
+ testID,
35
+ }: RadioCardProps) {
36
+ const theme = useTheme();
37
+ const bgIdle = mixHex(theme.primaryColor, theme.backgroundColor, 8);
38
+ const bgActive = mixHex(theme.primaryColor, theme.backgroundColor, 14);
39
+ const borderColor = selected
40
+ ? theme.primaryColor
41
+ : invalid
42
+ ? theme.errorColor
43
+ : theme.borderColor;
44
+
45
+ return (
46
+ <Pressable
47
+ accessibilityRole="radio"
48
+ accessibilityState={{ disabled, selected, checked: selected }}
49
+ accessibilityLabel={title}
50
+ accessibilityHint={description}
51
+ disabled={disabled}
52
+ testID={testID}
53
+ onPress={onPress}
54
+ style={({ pressed }) => [
55
+ styles.card,
56
+ {
57
+ borderColor,
58
+ backgroundColor: selected ? bgActive : bgIdle,
59
+ borderRadius: theme.borderRadiusPx,
60
+ minHeight: Math.max(theme.inputHeightPx, 44),
61
+ },
62
+ pressed && !disabled && { opacity: 0.85 },
63
+ disabled && styles.disabled,
64
+ style,
65
+ ]}
66
+ >
67
+ <View
68
+ style={[
69
+ styles.ring,
70
+ { borderColor: selected ? theme.primaryColor : theme.borderColor },
71
+ ]}
72
+ >
73
+ {selected ? (
74
+ <View style={[styles.dot, { backgroundColor: theme.primaryColor }]} />
75
+ ) : null}
76
+ </View>
77
+ <View style={styles.copy}>
78
+ <Text style={[styles.title, { color: theme.textColor }]}>{title}</Text>
79
+ {description ? (
80
+ <Text style={[styles.description, { color: theme.textSecondaryColor }]}>
81
+ {description}
82
+ </Text>
83
+ ) : null}
84
+ </View>
85
+ </Pressable>
86
+ );
87
+ }
88
+
89
+ const styles = StyleSheet.create({
90
+ card: {
91
+ flexDirection: 'row',
92
+ alignItems: 'center',
93
+ gap: 10,
94
+ paddingHorizontal: 12,
95
+ paddingVertical: 10,
96
+ borderWidth: 1,
97
+ },
98
+ disabled: {
99
+ opacity: 0.5,
100
+ },
101
+ ring: {
102
+ width: 22,
103
+ height: 22,
104
+ borderWidth: 2,
105
+ borderRadius: 11,
106
+ alignItems: 'center',
107
+ justifyContent: 'center',
108
+ },
109
+ dot: {
110
+ width: 10,
111
+ height: 10,
112
+ borderRadius: 5,
113
+ },
114
+ copy: {
115
+ flex: 1,
116
+ gap: 3,
117
+ },
118
+ title: {
119
+ fontSize: 15,
120
+ fontWeight: '600',
121
+ lineHeight: 20,
122
+ },
123
+ description: {
124
+ fontSize: 13,
125
+ lineHeight: 18,
126
+ },
127
+ });
@@ -3,11 +3,12 @@
3
3
  * of `<Input>` (label, 44 px tap target, error styling) so step forms can mix
4
4
  * the two primitives interchangeably.
5
5
  *
6
- * Intentionally simple: no search, no virtualisation. For searchable country
7
- * pickers use `CountrySelect`.
6
+ * Intentionally simple: no virtualisation. `searchable` adds a filter field on
7
+ * top of the option list for longer lists (e.g. a CUSTOM_FORM `LIST` with many
8
+ * options). For country pickers use `CountrySelect`.
8
9
  */
9
10
 
10
- import { useId, useMemo, useState } from 'react';
11
+ import { useCallback, useId, useMemo, useState } from 'react';
11
12
  import {
12
13
  Modal,
13
14
  Pressable,
@@ -17,8 +18,9 @@ import {
17
18
  type StyleProp,
18
19
  type ViewStyle,
19
20
  } from 'react-native';
20
- import { Text } from './Text';
21
+ import { Text, TextInput } from './Text';
21
22
  import { useTheme, withAlpha } from '../theme';
23
+ import { filterSearchableOptions } from './searchableSingleSelectFilter';
22
24
 
23
25
  export interface SelectOption {
24
26
  value: string;
@@ -35,6 +37,11 @@ export interface SelectProps {
35
37
  required?: boolean;
36
38
  disabled?: boolean;
37
39
  containerStyle?: StyleProp<ViewStyle>;
40
+ /** Shows a search field above the options that filters them by label. */
41
+ searchable?: boolean;
42
+ searchPlaceholder?: string;
43
+ /** Shown when the search matches no option. */
44
+ emptyText?: string;
38
45
  }
39
46
 
40
47
  export function Select({
@@ -47,17 +54,37 @@ export function Select({
47
54
  required,
48
55
  disabled = false,
49
56
  containerStyle,
57
+ searchable = false,
58
+ searchPlaceholder,
59
+ emptyText,
50
60
  }: SelectProps) {
51
61
  const theme = useTheme();
52
62
  const errorId = useId();
53
- const [open, setOpen] = useState(false);
63
+ const [open, setOpenState] = useState(false);
64
+ const [query, setQuery] = useState('');
54
65
  const hasError = Boolean(errorMessage && errorMessage.length > 0);
55
66
 
67
+ const setOpen = useCallback((next: boolean) => {
68
+ setOpenState(next);
69
+ if (!next) setQuery('');
70
+ }, []);
71
+
56
72
  const selected = useMemo(
57
73
  () => options.find((o) => o.value === value) ?? null,
58
74
  [options, value],
59
75
  );
60
76
 
77
+ const visibleOptions = useMemo(() => {
78
+ if (!searchable) return options;
79
+ const matches = new Set(
80
+ filterSearchableOptions(
81
+ options.map((o) => ({ id: o.value, label: o.label })),
82
+ query,
83
+ ).map((o) => o.id),
84
+ );
85
+ return options.filter((o) => matches.has(o.value));
86
+ }, [options, query, searchable]);
87
+
61
88
  return (
62
89
  <View style={[styles.wrap, containerStyle]}>
63
90
  {label ? (
@@ -140,8 +167,34 @@ export function Select({
140
167
  {label}
141
168
  </Text>
142
169
  ) : null}
143
- <ScrollView style={styles.sheetList}>
144
- {options.map((opt) => {
170
+ {searchable ? (
171
+ <TextInput
172
+ autoCapitalize="none"
173
+ autoCorrect={false}
174
+ accessibilityLabel={searchPlaceholder ?? label}
175
+ placeholder={searchPlaceholder ?? ''}
176
+ placeholderTextColor={theme.textSecondaryColor}
177
+ value={query}
178
+ onChangeText={setQuery}
179
+ style={[
180
+ styles.search,
181
+ { minHeight: theme.inputHeightPx },
182
+ {
183
+ color: theme.textColor,
184
+ backgroundColor: theme.backgroundColor,
185
+ borderColor: theme.borderColor,
186
+ borderRadius: theme.borderRadiusPx,
187
+ },
188
+ ]}
189
+ />
190
+ ) : null}
191
+ <ScrollView style={styles.sheetList} keyboardShouldPersistTaps="handled">
192
+ {searchable && visibleOptions.length === 0 && emptyText ? (
193
+ <Text style={[styles.empty, { color: theme.textSecondaryColor }]}>
194
+ {emptyText}
195
+ </Text>
196
+ ) : null}
197
+ {visibleOptions.map((opt) => {
145
198
  const isSelected = opt.value === value;
146
199
  return (
147
200
  <Pressable
@@ -247,6 +300,19 @@ const styles = StyleSheet.create({
247
300
  sheetList: {
248
301
  flexShrink: 1,
249
302
  },
303
+ search: {
304
+ marginHorizontal: 16,
305
+ marginBottom: 8,
306
+ paddingHorizontal: 12,
307
+ paddingVertical: 8,
308
+ fontSize: 15,
309
+ borderWidth: 1,
310
+ },
311
+ empty: {
312
+ paddingHorizontal: 16,
313
+ paddingVertical: 12,
314
+ fontSize: 14,
315
+ },
250
316
  option: {
251
317
  minHeight: 44,
252
318
  paddingHorizontal: 16,
@@ -15,3 +15,4 @@ export {
15
15
  type SearchableSingleSelectListProps,
16
16
  type SearchableListOption,
17
17
  } from './SearchableSingleSelectList';
18
+ export { RadioCard, type RadioCardProps } from './RadioCard';
@@ -5,4 +5,4 @@
5
5
  * GENERATED by `sdk/scripts/sync-sdk-version.js` from `sdk/package.json`:
6
6
  * do not edit by hand. The build and the CI version bump regenerate it.
7
7
  */
8
- export const SDK_VERSION = '1.4.0-beta.7' as const;
8
+ export const SDK_VERSION = '1.4.0-beta.9' as const;