@whop/elements-react-native 0.1.0

package/src/elements/tax-id.tsx

@@ -0,0 +1,143 @@
+import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import {
+	defaultTaxIdType,
+	isTaxIdType,
+	TAX_ID_TYPE_META,
+	TAX_ID_TYPES,
+	type TaxIdType,
+	useTaxIdTypeLabels,
+} from '../core/payments/tax-id-catalog';
+import { useT } from '../i18n';
+import { ElementFrame } from '../ui/element-frame';
+import { Field, FieldSkeleton, Stack } from '../ui/primitives';
+import { Select } from '../ui/select';
+
+export interface TaxIdChangePayload {
+	taxId: { type: TaxIdType; value: string };
+}
+
+export interface TaxIdElementProps {
+	/**
+	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`. EU and
+	 * unmapped or empty values select `eu_vat`. A manual selection persists across country changes.
+	 */
+	country?: string;
+	/** Initial `type` and `value` from a resumed session. An unsupported type falls back. */
+	defaultValue?: { type: string; value: string };
+	/** Disables both fields while the host saves the last committed registration. */
+	disabled?: boolean;
+	/** API validation error shown below the value input. */
+	error?: string;
+	style?: StyleProp<ViewStyle>;
+	fallback?: ReactNode;
+	onChange?: (payload: TaxIdChangePayload) => void;
+	onReady?: () => void;
+	onError?: (error: { message: string; code?: string }) => void;
+}
+
+/**
+ * Collects a business tax registration. `onChange` emits committed pairs only — on blur or submit
+ * with a non-empty value, or on a type change while a value is present. Identical consecutive
+ * values fire once, and clearing the value does not fire, so the host must clear stored
+ * registrations itself.
+ */
+export function TaxIdElement({
+	country = '',
+	defaultValue,
+	disabled = false,
+	error,
+	style,
+	fallback,
+	onChange,
+	onReady,
+	onError,
+}: TaxIdElementProps) {
+	const t = useT();
+	const labels = useTaxIdTypeLabels();
+
+	const seededType = defaultValue && isTaxIdType(defaultValue.type) ? defaultValue.type : undefined;
+	const [type, setType] = useState<TaxIdType>(() => seededType ?? defaultTaxIdType(country));
+	const [value, setValue] = useState(() => defaultValue?.value ?? '');
+	const manuallyPicked = useRef(Boolean(seededType));
+	const lastCommitted = useRef<string | null>(null);
+
+	// A manual selection outranks the country default, so a later country change leaves it alone.
+	useEffect(() => {
+		if (manuallyPicked.current) return;
+		setType(defaultTaxIdType(country));
+	}, [country]);
+
+	const options = useMemo(
+		() =>
+			TAX_ID_TYPES.map((candidate) => ({ value: candidate, label: labels[candidate] })).sort((a, b) =>
+				a.label.localeCompare(b.label),
+			),
+		[labels],
+	);
+
+	const latestChange = useRef(onChange);
+	latestChange.current = onChange;
+
+	const commit = useCallback(
+		(nextType: TaxIdType, nextValue: string) => {
+			const trimmed = nextValue.trim();
+			if (!trimmed) return;
+			const key = `${nextType}:${trimmed}`;
+			if (lastCommitted.current === key) return;
+			lastCommitted.current = key;
+			latestChange.current?.({ taxId: { type: nextType, value: trimmed } });
+		},
+		[],
+	);
+
+	const pickType = (next: string) => {
+		if (!isTaxIdType(next)) return;
+		manuallyPicked.current = true;
+		setType(next);
+		commit(next, value);
+	};
+
+	return (
+		<ElementFrame
+			style={style}
+			fallback={fallback}
+			skeleton={
+				<Stack>
+					<FieldSkeleton />
+					<FieldSkeleton />
+				</Stack>
+			}
+			ready
+			onReady={onReady}
+			onError={onError}
+		>
+			<Stack>
+				<Select
+					label={t('Tax registration')}
+					value={type}
+					options={options}
+					onChange={pickType}
+					disabled={disabled}
+					searchable
+					partName="whop-Select"
+				/>
+				<Field
+					label={labels[type]}
+					value={value}
+					onChangeText={setValue}
+					onBlur={() => commit(type, value)}
+					onSubmitEditing={() => commit(type, value)}
+					placeholder={TAX_ID_TYPE_META[type].placeholder}
+					error={error}
+					disabled={disabled}
+					autoCapitalize="characters"
+					autoCorrect={false}
+					returnKeyType="done"
+					accessibilityLabel={labels[type]}
+				/>
+			</Stack>
+		</ElementFrame>
+	);
+}

package/src/i18n/catalogs.ts

@@ -0,0 +1,100 @@
+/**
+ * Keys are the English source strings, matching the web elements' `useExtracted()` keys exactly, so
+ * a translation written for one surface fits the other. English needs no catalog: a miss renders the
+ * key, which is already the English copy.
+ */
+export const CATALOGS: Record<string, Record<string, string> | undefined> = {
+	es: {
+		'Card number': 'Número de tarjeta',
+		Expiration: 'Vencimiento',
+		'Security code': 'Código de seguridad',
+		Email: 'Correo electrónico',
+		Country: 'País',
+		'Address line 1': 'Dirección línea 1',
+		'Address line 2': 'Dirección línea 2',
+		City: 'Ciudad',
+		'Postal code': 'Código postal',
+		State: 'Estado',
+		Province: 'Provincia',
+		Name: 'Nombre',
+		'First name': 'Nombre',
+		'Last name': 'Apellido',
+		Organization: 'Organización',
+		'Tax registration': 'Registro fiscal',
+		'Add address line 2': 'Agregar dirección línea 2',
+		'Powered by': 'Con tecnología de',
+		Terms: 'Términos',
+		Privacy: 'Privacidad',
+		'Payment method': 'Método de pago',
+		'No payment methods are available': 'No hay métodos de pago disponibles',
+		'Enter a valid email address': 'Ingresa un correo electrónico válido',
+		Required: 'Obligatorio',
+		"That doesn't look right": 'Eso no parece correcto',
+		Business: 'Empresa',
+		Individual: 'Particular',
+		Unavailable: 'No disponible',
+		'Save this payment method': 'Guardar este método de pago',
+	},
+	de: {
+		'Card number': 'Kartennummer',
+		Expiration: 'Ablaufdatum',
+		'Security code': 'Sicherheitscode',
+		Email: 'E-Mail',
+		Country: 'Land',
+		'Address line 1': 'Adresszeile 1',
+		'Address line 2': 'Adresszeile 2',
+		City: 'Stadt',
+		'Postal code': 'Postleitzahl',
+		State: 'Bundesland',
+		Province: 'Provinz',
+		Name: 'Name',
+		'First name': 'Vorname',
+		'Last name': 'Nachname',
+		Organization: 'Organisation',
+		'Tax registration': 'Steuernummer',
+		'Add address line 2': 'Adresszeile 2 hinzufügen',
+		'Powered by': 'Bereitgestellt von',
+		Terms: 'Bedingungen',
+		Privacy: 'Datenschutz',
+		'Payment method': 'Zahlungsmethode',
+		'No payment methods are available': 'Keine Zahlungsmethoden verfügbar',
+		'Enter a valid email address': 'Gib eine gültige E-Mail-Adresse ein',
+		Required: 'Erforderlich',
+		"That doesn't look right": 'Das sieht nicht richtig aus',
+		Business: 'Unternehmen',
+		Individual: 'Privatperson',
+		Unavailable: 'Nicht verfügbar',
+		'Save this payment method': 'Diese Zahlungsmethode speichern',
+	},
+	fr: {
+		'Card number': 'Numéro de carte',
+		Expiration: 'Expiration',
+		'Security code': 'Code de sécurité',
+		Email: 'E-mail',
+		Country: 'Pays',
+		'Address line 1': 'Adresse ligne 1',
+		'Address line 2': 'Adresse ligne 2',
+		City: 'Ville',
+		'Postal code': 'Code postal',
+		State: 'État',
+		Province: 'Province',
+		Name: 'Nom',
+		'First name': 'Prénom',
+		'Last name': 'Nom de famille',
+		Organization: 'Organisation',
+		'Tax registration': 'Numéro fiscal',
+		'Add address line 2': "Ajouter l'adresse ligne 2",
+		'Powered by': 'Propulsé par',
+		Terms: 'Conditions',
+		Privacy: 'Confidentialité',
+		'Payment method': 'Moyen de paiement',
+		'No payment methods are available': 'Aucun moyen de paiement disponible',
+		'Enter a valid email address': 'Saisis une adresse e-mail valide',
+		Required: 'Obligatoire',
+		"That doesn't look right": 'Cela ne semble pas correct',
+		Business: 'Entreprise',
+		Individual: 'Particulier',
+		Unavailable: 'Indisponible',
+		'Save this payment method': 'Enregistrer ce moyen de paiement',
+	},
+};

package/src/i18n/index.tsx

@@ -0,0 +1,46 @@
+import { createContext, createElement, type ReactNode, useContext, useMemo } from 'react';
+
+import { deviceLocale } from '../core/payments/browser-info';
+import { CATALOGS } from './catalogs';
+
+/**
+ * Message lookup keyed by the English source string, the same shape `useExtracted()` gives the web
+ * elements — so a key here is the key there and translations move between them unchanged.
+ *
+ * A missing catalog entry renders the key, which IS the English copy. That is the correct failure:
+ * an untranslated string beats a blank one.
+ */
+export type Translate = (key: string, params?: Record<string, string | number>) => string;
+
+const LocaleContext = createContext<string | undefined>(undefined);
+
+export function LocaleProvider({ locale, children }: { locale?: string; children: ReactNode }): ReactNode {
+	return createElement(LocaleContext.Provider, { value: locale }, children);
+}
+
+export function useLocale(): string {
+	const explicit = useContext(LocaleContext);
+	return useMemo(() => normalize(explicit ?? deviceLocale()), [explicit]);
+}
+
+export function useT(): Translate {
+	const locale = useLocale();
+	return useMemo(() => translator(locale), [locale]);
+}
+
+export function translator(locale: string): Translate {
+	const exact = CATALOGS[locale];
+	const base = CATALOGS[locale.split('-')[0] ?? ''];
+	return (key, params) => {
+		const template = exact?.[key] ?? base?.[key] ?? key;
+		if (!params) return template;
+		return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+			Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : match,
+		);
+	};
+}
+
+function normalize(tag: string | undefined): string {
+	if (!tag) return 'en';
+	return tag.replace(/_/g, '-');
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * `@whop/elements-react-native` — native React Native components for collecting payments.
+ *
+ * The surface mirrors `@whop/elements-react`: a root provider, one namespace provider, one
+ * component per element, a hook for the live handle, and one `appearance` object. The deltas are
+ * documented on the types that carry them — `style` is a React Native style, `appearance.tokens`
+ * replaces CSS variables, `appearance.parts` replaces CSS classes, and there is no `elements`
+ * loader prop because there is no hosted script to load.
+ */
+
+export { WhopElements } from './provider';
+export type { WhopElementsConfig, WhopElementsProps } from './provider';
+
+export { Payments, usePayments } from './namespace';
+export type { PaymentsHandle, PaymentsProviderProps } from './namespace';
+export type { PaymentsOptions, PaymentsState } from './controller/store';
+export type {
+	CreateConfirmationTokenInput,
+	CreateConfirmationTokenResult,
+	HandleNextActionInput,
+	HandleNextActionResult,
+} from './controller/actions';
+
+export { PaymentElement } from './elements/payment';
+export type { PaymentChangePayload, PaymentElementProps } from './elements/payment';
+
+export { AddressElement } from './elements/address';
+export type { AddressChangePayload, AddressElementProps } from './elements/address';
+
+export { CardElement } from './elements/card';
+export type { CardElementProps } from './elements/card';
+
+export { CardCvcElement, CardExpiryElement, CardFields, CardNumberElement } from './elements/card-fields';
+export type { CardFieldProps, CardFieldsChangePayload, CardFieldsProps } from './elements/card-fields';
+
+export { EmailElement } from './elements/email';
+export type { EmailChangePayload, EmailElementProps } from './elements/email';
+
+export { TaxIdElement } from './elements/tax-id';
+export type { TaxIdChangePayload, TaxIdElementProps } from './elements/tax-id';
+
+export { BrandingElement } from './elements/branding';
+export type { BrandingElementProps } from './elements/branding';
+
+export type {
+	AccentColor,
+	Appearance,
+	GrayColor,
+	Parts,
+	PartName,
+	Theme,
+	Tokens,
+} from './theme/appearance';
+export { useTheme } from './theme/provider';
+export type { ResolvedTheme } from './theme/provider';
+
+export { API_BASES, WhopError } from './api/client';
+export type { WhopEnvironment } from './api/client';
+
+export { BrandingRequiredError, ChargeConfigError, PaymentTokenizationError } from './core/payments/errors';
+export { PaymentsRefusalError } from './core/payments/refusals';
+export type { PaymentsRefusalCode } from './core/payments/refusals';
+
+export type { TaxIdType } from './core/payments/tax-id-catalog';
+export type { EmittedAddress } from './core/address/engine';
+
+export { WhopAuthSession, WhopPlatformPay } from './native';
+export type { WalletCapability } from './native';

package/src/namespace.tsx

@@ -0,0 +1,231 @@
+import {
+	createContext,
+	forwardRef,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useImperativeHandle,
+	useMemo,
+	useRef,
+	useSyncExternalStore,
+} from 'react';
+import { type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+
+import {
+	createConfirmationToken,
+	type CreateConfirmationTokenInput,
+	type CreateConfirmationTokenResult,
+	handleNextAction,
+	type HandleNextActionInput,
+	type HandleNextActionResult,
+} from './controller/actions';
+import { type PaymentsOptions, type PaymentsState, PaymentsStore } from './controller/store';
+import { useRootConfig } from './provider';
+
+/** The live handle a `<Payments>` ref exposes — the same surface the vanilla handle carries. */
+export interface PaymentsHandle {
+	createConfirmationToken(input?: CreateConfirmationTokenInput): Promise<CreateConfirmationTokenResult>;
+	handleNextAction(input: HandleNextActionInput): Promise<HandleNextActionResult>;
+	getState(): PaymentsState;
+	subscribe(listener: () => void): () => void;
+	update(options: PaymentsOptions): void;
+	/** @internal the store the element components bind to */
+	readonly store: PaymentsStore;
+}
+
+const PaymentsContext = createContext<PaymentsHandle | null | undefined>(undefined);
+
+export function usePayments(): PaymentsHandle | null {
+	const handle = useContext(PaymentsContext);
+	if (handle === undefined) throw new Error('Payments element components must be used within <Payments>');
+	return handle;
+}
+
+/** @internal every element reads the store through this, never the context directly. */
+export function usePaymentsStore(): PaymentsStore {
+	const handle = usePayments();
+	if (!handle) throw new Error('Payments element components must be used within <Payments>');
+	return handle.store;
+}
+
+/** @internal a selected slice of controller state, re-rendering only when the slice moves. */
+export function usePaymentsState<T>(select: (state: PaymentsState) => T): T {
+	const store = usePaymentsStore();
+	const selector = useRef(select);
+	selector.current = select;
+	const getSnapshot = useCallback(() => selector.current(store.getSnapshot()), [store]);
+	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+export interface PaymentsProviderProps extends PaymentsOptions {
+	children?: ReactNode;
+	/** Shown until every child element has loaded. Grouped, exactly like the web provider's. */
+	fallback?: ReactNode;
+	style?: StyleProp<ViewStyle>;
+	onError?: (error: { message: string; code?: string }) => void;
+	onLoadingChange?: (loading: boolean) => void;
+}
+
+export const Payments = forwardRef<PaymentsHandle | null, PaymentsProviderProps>(function Payments(props, ref) {
+	const { children, fallback, style, onError, onLoadingChange, ...options } = props;
+	const config = useRootConfig();
+
+	// Read through a ref so the store never depends on getToken's IDENTITY. Every published sample
+	// passes an inline `getToken={() => ...}`, which is a new function each render: keying the store
+	// on it destroyed the store on any parent re-render, remounting card fields and dropping
+	// in-flight confirms.
+	const latestGetToken = useRef(config.getToken);
+	latestGetToken.current = config.getToken;
+
+	const store = useMemo(
+		() =>
+			new PaymentsStore(options, config.environment ?? 'production', async () => {
+				const token = await latestGetToken.current?.();
+				return token ?? null;
+			}),
+		// The store owns its own option updates below; recreating it on every prop change would
+		// remount every field and reload the tokenizer.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[config.environment],
+	);
+
+	useEffect(() => () => store.destroy(), [store]);
+
+	const latestOptions = useRef(options);
+	latestOptions.current = options;
+	useEffect(() => {
+		store.update(latestOptions.current);
+	});
+
+	const chargeError = usePaymentsStateOf(store, (s) => s.chargeError);
+	const latestOnError = useRef(onError);
+	latestOnError.current = onError;
+	useEffect(() => {
+		if (!chargeError) return;
+		const code = (chargeError as { code?: string }).code;
+		latestOnError.current?.({ message: chargeError.message, code });
+	}, [chargeError]);
+
+	const handle = useMemo<PaymentsHandle>(
+		() => ({
+			store,
+			createConfirmationToken: (input) => createConfirmationToken(store, input),
+			handleNextAction: (input) => handleNextAction(store, input),
+			getState: () => store.getSnapshot(),
+			subscribe: (listener) => store.subscribe(listener),
+			update: (next) => store.update(next),
+		}),
+		[store],
+	);
+	useImperativeHandle(ref, () => handle, [handle]);
+
+	const loading = useGroupLoading(store, onLoadingChange);
+	const hideChildren = loading && fallback != null;
+
+	return (
+		<PaymentsContext.Provider value={handle}>
+			<View style={style}>
+				{hideChildren ? fallback : null}
+				{/*
+				  Held children stay mounted, laid out, and merely invisible. `display: none` would
+				  collapse them to zero, and the Basis Theory fields measure themselves on mount — a
+				  collapsed field initializes at 0x0 and pops when revealed.
+				*/}
+				<View
+					style={hideChildren ? styles.held : undefined}
+					pointerEvents={hideChildren ? 'none' : 'auto'}
+					accessibilityElementsHidden={hideChildren}
+					importantForAccessibility={hideChildren ? 'no-hide-descendants' : 'auto'}
+				>
+					{children}
+				</View>
+			</View>
+		</PaymentsContext.Provider>
+	);
+});
+
+/** @internal element components call this on mount so the group latch knows to wait for them. */
+export function useGroupMember(): { ready: () => void } {
+	const store = usePaymentsStore();
+	const settled = useRef(false);
+	useEffect(() => {
+		const registry = groupRegistry(store);
+		registry.pending += 1;
+		registry.notify();
+		return () => {
+			if (settled.current) return;
+			registry.pending -= 1;
+			registry.notify();
+		};
+	}, [store]);
+
+	return {
+		ready: () => {
+			if (settled.current) return;
+			settled.current = true;
+			const registry = groupRegistry(store);
+			registry.pending -= 1;
+			registry.notify();
+		},
+	};
+}
+
+interface GroupRegistry {
+	pending: number;
+	listeners: Set<() => void>;
+	notify: () => void;
+}
+
+const REGISTRIES = new WeakMap<PaymentsStore, GroupRegistry>();
+
+function groupRegistry(store: PaymentsStore): GroupRegistry {
+	let registry = REGISTRIES.get(store);
+	if (!registry) {
+		const created: GroupRegistry = {
+			pending: 0,
+			listeners: new Set(),
+			notify: () => {
+				for (const listener of created.listeners) listener();
+			},
+		};
+		REGISTRIES.set(store, created);
+		registry = created;
+	}
+	return registry;
+}
+
+function useGroupLoading(store: PaymentsStore, onLoadingChange?: (loading: boolean) => void): boolean {
+	const subscribe = useCallback(
+		(listener: () => void) => {
+			const registry = groupRegistry(store);
+			registry.listeners.add(listener);
+			return () => {
+				registry.listeners.delete(listener);
+			};
+		},
+		[store],
+	);
+	// Nothing mounted eagerly means nothing will ever settle the latch, so an empty group is loaded.
+	const getSnapshot = useCallback(() => groupRegistry(store).pending > 0, [store]);
+	const loading = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+	const latest = useRef(onLoadingChange);
+	latest.current = onLoadingChange;
+	useEffect(() => {
+		latest.current?.(loading);
+	}, [loading]);
+
+	return loading;
+}
+
+function usePaymentsStateOf<T>(store: PaymentsStore, select: (state: PaymentsState) => T): T {
+	const selector = useRef(select);
+	selector.current = select;
+	const getSnapshot = useCallback(() => selector.current(store.getSnapshot()), [store]);
+	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+const styles = StyleSheet.create({
+	held: { position: 'absolute', top: 0, left: 0, right: 0, opacity: 0 },
+});