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

package/src/ui/primitives/Input.tsx

@@ -0,0 +1,110 @@
+/**
+ * Themed text input with optional inline error message.
+ *
+ * Matches `.vl-hbi__input` semantics:
+ *   - 44 px min height tap target.
+ *   - Border switches to `errorColor` and a subtle ring when `errorMessage` is set.
+ *   - Pairs an externally controlled label rendered above (see `<Field>` helper).
+ */
+
+import { forwardRef, useId } from 'react';
+import {
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+  type StyleProp,
+  type TextInputProps,
+  type ViewStyle,
+} from 'react-native';
+import { useTheme } from '../theme';
+
+export interface InputProps extends Omit<TextInputProps, 'style'> {
+  label?: string;
+  errorMessage?: string | null;
+  required?: boolean;
+  containerStyle?: StyleProp<ViewStyle>;
+}
+
+export const Input = forwardRef<TextInput, InputProps>(function Input(
+  { label, errorMessage, required, containerStyle, ...rest },
+  ref,
+) {
+  const theme = useTheme();
+  const errorId = useId();
+  const hasError = Boolean(errorMessage && errorMessage.length > 0);
+
+  return (
+    <View style={[styles.wrap, containerStyle]}>
+      {label ? (
+        <Text style={[styles.label, { color: theme.textColor }]}>
+          {label}
+          {required ? (
+            <Text style={[styles.required, { color: theme.textSecondaryColor }]}>
+              {' '}*
+            </Text>
+          ) : null}
+        </Text>
+      ) : null}
+      <TextInput
+        ref={ref}
+        accessibilityLabel={rest.accessibilityLabel ?? label}
+        accessibilityState={{ disabled: rest.editable === false }}
+        accessibilityHint={hasError ? errorMessage ?? undefined : undefined}
+        placeholderTextColor={theme.textSecondaryColor}
+        {...rest}
+        style={[
+          styles.input,
+          {
+            color: theme.textColor,
+            backgroundColor: theme.backgroundColor,
+            borderRadius: theme.borderRadiusPx,
+            borderColor: hasError ? theme.errorColor : theme.borderColor,
+          },
+          hasError && {
+            shadowColor: theme.errorColor,
+            shadowOpacity: 0.18,
+            shadowRadius: 6,
+            shadowOffset: { width: 0, height: 0 },
+          },
+        ]}
+      />
+      {hasError ? (
+        <Text
+          nativeID={errorId}
+          accessibilityLiveRegion="polite"
+          style={[styles.error, { color: theme.errorColor }]}
+        >
+          {errorMessage}
+        </Text>
+      ) : null}
+    </View>
+  );
+});
+
+const styles = StyleSheet.create({
+  wrap: {
+    width: '100%',
+    marginBottom: 4,
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: '500',
+    marginBottom: 4,
+  },
+  required: {
+    fontWeight: '400',
+  },
+  input: {
+    minHeight: 44,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    fontSize: 15,
+    borderWidth: 1,
+  },
+  error: {
+    fontSize: 13,
+    marginTop: 4,
+    lineHeight: 18,
+  },
+});

package/src/ui/primitives/Select.tsx

@@ -0,0 +1,259 @@
+/**
+ * Lightweight select — uses a modal-anchored option list. Matches the rhythm
+ * of `<Input>` (label, 44 px tap target, error styling) so step forms can mix
+ * the two primitives interchangeably.
+ *
+ * Intentionally simple: no search, no virtualisation. For searchable country
+ * pickers use `CountrySelect`.
+ */
+
+import { useId, useMemo, useState } from 'react';
+import {
+  Modal,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { useTheme, withAlpha } from '../theme';
+
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+export interface SelectProps {
+  label?: string;
+  options: SelectOption[];
+  value: string | null;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  errorMessage?: string | null;
+  required?: boolean;
+  disabled?: boolean;
+  containerStyle?: StyleProp<ViewStyle>;
+}
+
+export function Select({
+  label,
+  options,
+  value,
+  onChange,
+  placeholder,
+  errorMessage,
+  required,
+  disabled = false,
+  containerStyle,
+}: SelectProps) {
+  const theme = useTheme();
+  const errorId = useId();
+  const [open, setOpen] = useState(false);
+  const hasError = Boolean(errorMessage && errorMessage.length > 0);
+
+  const selected = useMemo(
+    () => options.find((o) => o.value === value) ?? null,
+    [options, value],
+  );
+
+  return (
+    <View style={[styles.wrap, containerStyle]}>
+      {label ? (
+        <Text style={[styles.label, { color: theme.textColor }]}>
+          {label}
+          {required ? (
+            <Text style={[styles.required, { color: theme.textSecondaryColor }]}>
+              {' '}*
+            </Text>
+          ) : null}
+        </Text>
+      ) : null}
+      <Pressable
+        accessibilityRole="combobox"
+        accessibilityState={{ disabled, expanded: open }}
+        accessibilityLabel={label}
+        disabled={disabled}
+        onPress={() => setOpen(true)}
+        style={[
+          styles.trigger,
+          {
+            backgroundColor: theme.backgroundColor,
+            borderColor: hasError ? theme.errorColor : theme.borderColor,
+            borderRadius: theme.borderRadiusPx,
+          },
+          disabled && styles.disabled,
+        ]}
+      >
+        <Text
+          numberOfLines={1}
+          style={[
+            styles.triggerText,
+            {
+              color: selected ? theme.textColor : theme.textSecondaryColor,
+            },
+          ]}
+        >
+          {selected?.label ?? placeholder ?? ''}
+        </Text>
+        <Text style={[styles.chevron, { color: theme.textSecondaryColor }]}>
+          ▾
+        </Text>
+      </Pressable>
+
+      {hasError ? (
+        <Text
+          nativeID={errorId}
+          accessibilityLiveRegion="polite"
+          style={[styles.error, { color: theme.errorColor }]}
+        >
+          {errorMessage}
+        </Text>
+      ) : null}
+
+      <Modal
+        visible={open}
+        transparent
+        animationType="fade"
+        onRequestClose={() => setOpen(false)}
+      >
+        <Pressable
+          style={styles.backdrop}
+          onPress={() => setOpen(false)}
+          accessibilityLabel="Close"
+        >
+          <Pressable
+            style={[
+              styles.sheet,
+              {
+                backgroundColor: theme.backgroundColor,
+                borderRadius: theme.borderRadiusPx,
+                borderColor: theme.borderColor,
+              },
+            ]}
+            onPress={() => undefined}
+          >
+            {label ? (
+              <Text style={[styles.sheetTitle, { color: theme.textColor }]}>
+                {label}
+              </Text>
+            ) : null}
+            <ScrollView style={styles.sheetList}>
+              {options.map((opt) => {
+                const isSelected = opt.value === value;
+                return (
+                  <Pressable
+                    key={opt.value}
+                    accessibilityRole="menuitem"
+                    accessibilityState={{ selected: isSelected }}
+                    onPress={() => {
+                      onChange(opt.value);
+                      setOpen(false);
+                    }}
+                    style={({ pressed }) => [
+                      styles.option,
+                      isSelected && {
+                        backgroundColor: withAlpha(theme.primaryColor, 0.12),
+                      },
+                      pressed && {
+                        backgroundColor: withAlpha(theme.primaryColor, 0.18),
+                      },
+                    ]}
+                  >
+                    <Text
+                      style={[
+                        styles.optionText,
+                        {
+                          color: isSelected
+                            ? theme.primaryColor
+                            : theme.textColor,
+                          fontWeight: isSelected ? '600' : '400',
+                        },
+                      ]}
+                    >
+                      {opt.label}
+                    </Text>
+                  </Pressable>
+                );
+              })}
+            </ScrollView>
+          </Pressable>
+        </Pressable>
+      </Modal>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    width: '100%',
+    marginBottom: 4,
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: '500',
+    marginBottom: 4,
+  },
+  required: {
+    fontWeight: '400',
+  },
+  trigger: {
+    minHeight: 44,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    borderWidth: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+  triggerText: {
+    fontSize: 15,
+    flex: 1,
+  },
+  chevron: {
+    fontSize: 14,
+    marginLeft: 8,
+  },
+  disabled: {
+    opacity: 0.5,
+  },
+  error: {
+    fontSize: 13,
+    marginTop: 4,
+    lineHeight: 18,
+  },
+  backdrop: {
+    flex: 1,
+    backgroundColor: 'rgba(0,0,0,0.4)',
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 20,
+  },
+  sheet: {
+    width: '100%',
+    maxWidth: 420,
+    maxHeight: '70%',
+    borderWidth: 1,
+    paddingTop: 12,
+    paddingBottom: 6,
+  },
+  sheetTitle: {
+    fontSize: 16,
+    fontWeight: '600',
+    paddingHorizontal: 16,
+    marginBottom: 8,
+  },
+  sheetList: {
+    flexShrink: 1,
+  },
+  option: {
+    minHeight: 44,
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    justifyContent: 'center',
+  },
+  optionText: {
+    fontSize: 15,
+  },
+});

package/src/ui/primitives/Spinner.tsx

@@ -0,0 +1,17 @@
+/**
+ * Activity spinner that respects reduced-motion. RN ships `ActivityIndicator`
+ * natively which already complies with platform accessibility settings.
+ */
+
+import { ActivityIndicator } from 'react-native';
+import { useTheme } from '../theme';
+
+export interface SpinnerProps {
+  size?: number | 'small' | 'large';
+  color?: string;
+}
+
+export function Spinner({ size = 'large', color }: SpinnerProps) {
+  const theme = useTheme();
+  return <ActivityIndicator size={size} color={color ?? theme.primaryColor} />;
+}

package/src/ui/primitives/index.ts

@@ -0,0 +1,9 @@
+export { Button, type ButtonProps, type ButtonVariant } from './Button';
+export { Input, type InputProps } from './Input';
+export { Select, type SelectProps, type SelectOption } from './Select';
+export { Card, type CardProps } from './Card';
+export { Banner, type BannerProps } from './Banner';
+export { Spinner, type SpinnerProps } from './Spinner';
+export { Checkbox, type CheckboxProps } from './Checkbox';
+export { DatePicker, type DatePickerProps } from './DatePicker';
+export { CountrySelect, type CountrySelectProps } from './CountrySelect';

package/src/ui/theme/ThemeProvider.tsx

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview ThemeProvider + hooks.
+ *
+ * - `ThemeProvider` resolves tokens from `VelionConfig.theme` + colorMode and
+ *   exposes them to descendants.
+ * - `useTheme()` returns the active `ResolvedTheme`.
+ * - `useReducedMotion()` honours the OS-level `prefers-reduced-motion` flag —
+ *   components disable animations when true.
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { AccessibilityInfo, useColorScheme } from 'react-native';
+import type { VelionTheme } from '../../types';
+import { resolveTheme, type ResolvedTheme } from './tokens';
+
+interface ThemeContextValue {
+  theme: ResolvedTheme;
+  reduceMotion: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export interface ThemeProviderProps {
+  /** Consumer-supplied overrides (subset of tokens). */
+  themeOverrides?: VelionTheme | undefined;
+  /** Explicit mode. `'auto'` follows the system color scheme. */
+  colorMode?: 'light' | 'dark' | 'auto' | undefined;
+  children: ReactNode;
+}
+
+export function ThemeProvider({
+  themeOverrides,
+  colorMode = 'auto',
+  children,
+}: ThemeProviderProps) {
+  const systemScheme = useColorScheme();
+  const reduceMotion = useReducedMotionInternal();
+
+  const resolvedMode: 'light' | 'dark' = useMemo(() => {
+    if (colorMode === 'light' || colorMode === 'dark') return colorMode;
+    return systemScheme === 'dark' ? 'dark' : 'light';
+  }, [colorMode, systemScheme]);
+
+  const theme = useMemo(
+    () => resolveTheme(themeOverrides, resolvedMode),
+    [themeOverrides, resolvedMode],
+  );
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ theme, reduceMotion }),
+    [theme, reduceMotion],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}
+
+export function useTheme(): ResolvedTheme {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error(
+      'useTheme must be used inside <ThemeProvider>. Did you mount <VelionOnboardingScreen> at the root of your screen?',
+    );
+  }
+  return ctx.theme;
+}
+
+export function useReducedMotion(): boolean {
+  const ctx = useContext(ThemeContext);
+  return ctx?.reduceMotion ?? false;
+}
+
+function useReducedMotionInternal(): boolean {
+  const [enabled, setEnabled] = useState(false);
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled()
+      .then((v) => {
+        if (mounted) setEnabled(v);
+      })
+      .catch(() => {
+        // The API is best-effort on every platform; default to false on error.
+      });
+    const sub = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      (v) => setEnabled(v),
+    );
+    return () => {
+      mounted = false;
+      sub.remove();
+    };
+  }, []);
+  return enabled;
+}

package/src/ui/theme/index.ts

@@ -0,0 +1,17 @@
+export {
+  ThemeProvider,
+  useTheme,
+  useReducedMotion,
+  type ThemeProviderProps,
+} from './ThemeProvider';
+export {
+  LIGHT_TOKENS,
+  DARK_TOKENS,
+  getDefaultThemeTokens,
+  resolveTheme,
+  mixHex,
+  withAlpha,
+  isHexDark,
+  type ResolvedTheme,
+  type ThemeTokenSet,
+} from './tokens';

package/src/ui/theme/tokens.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Theme tokens for the React Native SDK.
+ *
+ * Exposes logical tokens as a plain JS object that components consume via
+ * `useTheme()`.
+ *
+ * Light and dark are tuned independently (Material Design 3 / Apple HIG dark
+ * pairing). Consumer overrides from `VelionConfig.theme` are layered on top.
+ */
+
+import type { VelionTheme } from '../../types';
+
+/** Tonal token set. Shape matches `VelionTheme` (all required, no undefineds). */
+export type ThemeTokenSet = Required<VelionTheme>;
+
+/**
+ * Resolved values that components actually read from. We keep colors as plain
+ * hex strings; consumers that want to layer translucency use `mixHex` instead
+ * of CSS `color-mix()` (which does not exist in RN).
+ */
+export interface ResolvedTheme extends ThemeTokenSet {
+  /** The mode that components should consider active (post-luminance check). */
+  effectiveMode: 'light' | 'dark';
+  /** The numeric pixel value parsed from `borderRadius` (the SDK-wide default). */
+  borderRadiusPx: number;
+}
+
+export const LIGHT_TOKENS: ThemeTokenSet = {
+  primaryColor: '#2563EB',
+  secondaryColor: '#1D4ED8',
+  backgroundColor: '#FFFFFF',
+  textColor: '#111827',
+  textSecondaryColor: '#6B7280',
+  borderRadius: '8px',
+  fontFamily: 'System',
+  errorColor: '#DC2626',
+  successColor: '#16A34A',
+  warningColor: '#D97706',
+  borderColor: '#E5E7EB',
+  cardShadow: '0 4px 6px -1px rgba(0,0,0,0.10), 0 2px 4px -2px rgba(0,0,0,0.10)',
+  hideStepIcons: false,
+  hideProgressBar: false,
+};
+
+export const DARK_TOKENS: ThemeTokenSet = {
+  primaryColor: '#3B82F6',
+  secondaryColor: '#60A5FA',
+  backgroundColor: '#0B1220',
+  textColor: '#F1F5F9',
+  textSecondaryColor: '#94A3B8',
+  borderRadius: '8px',
+  fontFamily: 'System',
+  errorColor: '#F87171',
+  successColor: '#34D399',
+  warningColor: '#FBBF24',
+  borderColor: '#1E293B',
+  cardShadow: '0 8px 18px -4px rgba(0,0,0,0.55), 0 4px 8px -4px rgba(0,0,0,0.40)',
+  hideStepIcons: false,
+  hideProgressBar: false,
+};
+
+export function getDefaultThemeTokens(
+  colorMode: 'light' | 'dark' = 'light',
+): ThemeTokenSet {
+  return colorMode === 'dark' ? { ...DARK_TOKENS } : { ...LIGHT_TOKENS };
+}
+
+/** Layers consumer overrides on top of the base tokens for the requested mode. */
+export function resolveTheme(
+  theme: VelionTheme | undefined,
+  colorMode: 'light' | 'dark',
+): ResolvedTheme {
+  const base = colorMode === 'dark' ? DARK_TOKENS : LIGHT_TOKENS;
+  const merged: ThemeTokenSet = { ...base, ...theme };
+  // Recompute the effective mode from the resolved background luminance, so a
+  // consumer that passes `colorMode: "light"` but overrides `backgroundColor`
+  // with a dark hex still gets icons / images that branch on the mode right.
+  const effectiveMode: 'light' | 'dark' = isHexDark(merged.backgroundColor)
+    ? 'dark'
+    : 'light';
+  const borderRadiusPx = parsePx(merged.borderRadius, 8);
+  return { ...merged, effectiveMode, borderRadiusPx };
+}
+
+/** WCAG relative-luminance check. Returns false on unparsable input. */
+export function isHexDark(hex: string): boolean {
+  const parsed = parseHex(hex);
+  if (!parsed) return false;
+  const linearize = (c: number): number => {
+    const n = c / 255;
+    return n <= 0.03928 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
+  };
+  const luminance =
+    0.2126 * linearize(parsed.r) +
+    0.7152 * linearize(parsed.g) +
+    0.0722 * linearize(parsed.b);
+  return luminance < 0.5;
+}
+
+/**
+ * Mix two hex colors at the given ratio (0–100). Cheap stand-in for the web's
+ * `color-mix(in srgb, A x%, B)` so we can render the soft halos and tinted
+ * backgrounds the design system uses (.vl-retry-dialog, .vl-sworn__option).
+ */
+export function mixHex(a: string, b: string, ratioOfA: number): string {
+  const ar = clamp(ratioOfA, 0, 100) / 100;
+  const ca = parseHex(a);
+  const cb = parseHex(b);
+  if (!ca || !cb) return a;
+  const r = Math.round(ca.r * ar + cb.r * (1 - ar));
+  const g = Math.round(ca.g * ar + cb.g * (1 - ar));
+  const blue = Math.round(ca.b * ar + cb.b * (1 - ar));
+  return `#${toHex(r)}${toHex(g)}${toHex(blue)}`;
+}
+
+/**
+ * Returns an `rgba()` string with the supplied alpha (0–1). Use for translucent
+ * borders / fills that should not blend with the host background.
+ */
+export function withAlpha(hex: string, alpha: number): string {
+  const c = parseHex(hex);
+  if (!c) return hex;
+  const a = clamp(alpha, 0, 1);
+  return `rgba(${c.r}, ${c.g}, ${c.b}, ${a})`;
+}
+
+function parseHex(hex: string): { r: number; g: number; b: number } | null {
+  const match = hex.match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!match || !match[1]) return null;
+  const raw = match[1];
+  const full =
+    raw.length === 3
+      ? raw[0]! + raw[0]! + raw[1]! + raw[1]! + raw[2]! + raw[2]!
+      : raw;
+  return {
+    r: parseInt(full.slice(0, 2), 16),
+    g: parseInt(full.slice(2, 4), 16),
+    b: parseInt(full.slice(4, 6), 16),
+  };
+}
+
+function toHex(n: number): string {
+  return clamp(n, 0, 255).toString(16).padStart(2, '0').toUpperCase();
+}
+
+function clamp(n: number, min: number, max: number): number {
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+
+function parsePx(value: string, fallback: number): number {
+  const m = value.trim().match(/^(\d+(?:\.\d+)?)\s*px$/i);
+  if (m && m[1]) {
+    const parsed = Number(m[1]);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}