tf-checkout-react 1.7.30 → 2.0.0-beta.0

package/src/ui/CheckoutProvider.tsx

@@ -0,0 +1,172 @@
+/**
+ * `<CheckoutProvider>` — wrap your checkout UI once. It:
+ *   - provides the checkout to every section via context — so `<Tickets/>`,
+ *     `<Payment/>`, … just read it, no prop-drilling. By default it runs
+ *     `useCheckout()` for you (the web-wired engine: Stripe/Xendit + shared
+ *     store); pass your own instance as `value` to bring your own;
+ *   - applies the `theme` as `--tf-checkout-*` CSS variables on its root and
+ *     scopes all styles under `.tf-checkout`.
+ *
+ * This is the single styling + context boundary shared by all three usage
+ * tiers: the batteries-included `<EmbeddedCheckout/>`, à-la-carte sections, and (via
+ * `value`) a consumer who already holds a `useCheckout()` of their own.
+ *
+ * Styles load automatically from the package entry point.
+ */
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type FC,
+  type ReactNode,
+} from 'react'
+
+import type { LocaleCode, Messages, UseCheckout } from 'tf-checkout-shared'
+
+import { useCheckout } from '../useCheckout'
+import { cx } from './cx'
+import { I18nProvider } from './I18nProvider'
+import { useInstallmentPicker } from './InstallmentPicker'
+import { themeToVars, type CheckoutTheme } from './theme'
+
+const CheckoutCtx = createContext<UseCheckout | null>(null)
+const CheckoutValidationCtx = createContext<{
+  attempt: number
+  requestValidation: () => void
+} | null>(null)
+
+export interface CheckoutProviderProps {
+  /**
+   * Bring your own checkout instance (from a top-level `useCheckout()`). Omit
+   * and the provider runs `useCheckout()` itself. Either way the sections read
+   * the same shared cart (the engine store is a module singleton).
+   */
+  value?: UseCheckout
+  /** Retheme via design tokens. */
+  theme?: CheckoutTheme
+  /**
+   * Language for the checkout's own copy. Defaults to `en-GB`, so omitting it
+   * leaves every existing consumer's rendering byte-for-byte unchanged.
+   */
+  locale?: LocaleCode
+  /**
+   * Per-key overrides merged over the locale, for brands that need to reword
+   * individual strings without shipping a whole catalogue.
+   */
+  messages?: Partial<Messages>
+  /** Extra class on the `.tf-checkout` root. */
+  className?: string
+  children: ReactNode
+}
+
+/** The `.tf-checkout` root + context — given a resolved checkout instance. */
+const CheckoutRoot: FC<{
+  checkout: UseCheckout
+  theme?: CheckoutTheme
+  className?: string
+  children: ReactNode
+}> = ({ checkout, theme, className, children }) => {
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const [attempt, setAttempt] = useState(0)
+  const requestValidation = useCallback(() => setAttempt((current) => current + 1), [])
+
+  // Every section marks its own invalid controls. Keeping the navigation here
+  // makes validation work for EmbeddedCheckout and for consumers composing the
+  // sections themselves.
+  useEffect(() => {
+    if (attempt === 0) return
+    const frame = window.requestAnimationFrame(() => {
+      const invalid = rootRef.current?.querySelector<HTMLElement>(
+        '[data-checkout-invalid="true"]'
+      )
+      if (!invalid) return
+      const behavior = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+        ? 'auto'
+        : 'smooth'
+      invalid.scrollIntoView({ behavior, block: 'center' })
+      const focusTarget = invalid.matches('input, select, textarea, button')
+        ? invalid
+        : invalid.querySelector<HTMLElement>('input, select, textarea, button')
+      focusTarget?.focus({ preventScroll: true })
+    })
+    return () => window.cancelAnimationFrame(frame)
+  }, [attempt])
+
+  return (
+    <CheckoutCtx.Provider value={checkout}>
+      <CheckoutValidationCtx.Provider value={{ attempt, requestValidation }}>
+        <div
+          ref={rootRef}
+          className={cx(
+            'tf-checkout',
+            // No colorScheme → auto-follow the OS/browser (prefers-color-scheme).
+            // Set it to force one: 'dark' → --dark, 'light' → --light (opt out of auto-dark).
+            theme?.colorScheme === 'dark' && 'tf-checkout--dark',
+            theme?.colorScheme === 'light' && 'tf-checkout--light',
+            className
+          )}
+          style={themeToVars(theme)}
+        >
+          {children}
+        </div>
+      </CheckoutValidationCtx.Provider>
+    </CheckoutCtx.Provider>
+  )
+}
+
+/** Default path: the provider owns the `useCheckout()` call. Wires the MSI
+ *  installment picker so Mexican card payments can split into installments. */
+const SelfProvidedCheckout: FC<Omit<CheckoutProviderProps, 'value'>> = ({
+  children,
+  ...rest
+}) => {
+  const { onInstallmentOffers, picker } = useInstallmentPicker()
+  const checkout = useCheckout({ ports: { onInstallmentOffers } })
+  return (
+    <CheckoutRoot checkout={checkout} {...rest}>
+      {children}
+      {picker}
+    </CheckoutRoot>
+  )
+}
+
+export const CheckoutProvider: FC<CheckoutProviderProps> = ({
+  value,
+  locale,
+  messages,
+  ...rest
+}) => (
+  // I18n wraps the whole checkout tree so every section can call `useT()`.
+  // Outside CheckoutRoot so the translator is in scope for the provider's own
+  // children as well as the sections.
+  <I18nProvider locale={locale} messages={messages}>
+    {
+      // `value` present ⇒ don't call `useCheckout()` at all (no second
+      // binding); absent ⇒ the self-providing branch owns it. The choice is
+      // static per mount, so the two branches never swap and violate the rules
+      // of hooks.
+      value ? <CheckoutRoot checkout={value} {...rest} /> : <SelfProvidedCheckout {...rest} />
+    }
+  </I18nProvider>
+)
+
+/** Read the shared checkout inside any component under `<CheckoutProvider>`. */
+export const useCheckoutContext = (): UseCheckout => {
+  const ctx = useContext(CheckoutCtx)
+  if (!ctx) {
+    throw new Error('useCheckoutContext must be used within <CheckoutProvider>.')
+  }
+  return ctx
+}
+
+/** Coordinate submit-attempt validation across separately composed sections. */
+export const useCheckoutValidation = () => {
+  const ctx = useContext(CheckoutValidationCtx)
+  if (!ctx) {
+    throw new Error('useCheckoutValidation must be used within <CheckoutProvider>.')
+  }
+  return ctx
+}

package/src/ui/CustomFields.tsx

@@ -0,0 +1,195 @@
+/**
+ * Data-driven custom fields. The event describes what to collect
+ * (`EventCustomField[]`, order- / ticket- / add-on-scoped); these render it —
+ * text, textarea, phone, email, select, radio, checkbox, multi-select — and
+ * report values back. No per-brand form code: pass the group, hold the values.
+ *
+ *   const [vals, setVals] = useState<CustomFieldValues>({})
+ *   <CustomFieldGroupFields group={group} values={vals}
+ *     onChange={(name, v) => setVals(s => ({ ...s, [name]: v }))} />
+ */
+import React, { type FC, type ReactNode } from 'react'
+
+import type {
+  CustomFieldValues,
+  EventCustomField,
+  EventCustomFieldGroup,
+} from 'tf-checkout-shared'
+import { ticketFieldsFor } from 'tf-checkout-shared'
+
+import { Checkbox, Field, Input, Select, Textarea } from './Field'
+
+type FieldValue = string | string[]
+
+const asString = (v: FieldValue | undefined): string =>
+  Array.isArray(v) ? (v[0] ?? '') : (v ?? '')
+const asArray = (v: FieldValue | undefined): string[] =>
+  Array.isArray(v) ? v : v ? [v] : []
+
+export interface CustomFieldInputProps {
+  field: EventCustomField
+  value: FieldValue | undefined
+  onChange: (value: FieldValue) => void
+  error?: ReactNode
+}
+
+/** Render one custom field by its declared `type`. */
+export const CustomFieldInput: FC<CustomFieldInputProps> = ({
+  field,
+  value,
+  onChange,
+  error,
+}) => {
+  const label = `${field.label}${field.required ? ' *' : ''}`
+  const invalid = error != null
+  const desc = field.description ? (
+    <span className="tf-checkout-field__hint">{field.description}</span>
+  ) : undefined
+
+  switch (field.type) {
+    case 'textarea':
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <Textarea
+            value={asString(value)}
+            invalid={invalid}
+            aria-invalid={invalid}
+            onChange={(e) => onChange(e.target.value)}
+          />
+        </Field>
+      )
+    case 'select':
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <Select
+            value={asString(value)}
+            invalid={invalid}
+            aria-invalid={invalid}
+            onChange={(e) => onChange(e.target.value)}
+          >
+            <option value="">— select —</option>
+            {field.options.map((o) => (
+              <option key={o.id} value={o.value}>
+                {o.name}
+              </option>
+            ))}
+          </Select>
+        </Field>
+      )
+    case 'radio':
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <div className="tf-checkout-choices">
+            {field.options.map((o) => (
+              <label key={o.id} className="tf-checkout-choice">
+                <input
+                  type="radio"
+                  name={field.name}
+                  checked={asString(value) === o.value}
+                  onChange={() => onChange(o.value)}
+                />
+                <span>{o.name}</span>
+              </label>
+            ))}
+          </div>
+        </Field>
+      )
+    case 'select_multi': {
+      const picked = asArray(value)
+      const toggle = (v: string, on: boolean) =>
+        onChange(on ? [...picked, v] : picked.filter((x) => x !== v))
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <div className="tf-checkout-choices">
+            {field.options.map((o) => (
+              <Checkbox
+                key={o.id}
+                checked={picked.includes(o.value)}
+                onChange={(e) => toggle(o.value, e.target.checked)}
+                label={o.name}
+              />
+            ))}
+          </div>
+        </Field>
+      )
+    }
+    case 'checkbox':
+      return (
+        <div
+          className={invalid ? 'tf-checkout-consent--error' : undefined}
+          data-checkout-invalid={invalid || undefined}
+        >
+          <Checkbox
+            checked={asString(value) === '1'}
+            aria-invalid={invalid}
+            onChange={(e) => onChange(e.target.checked ? '1' : '')}
+            label={label}
+          />
+          {error != null && <div className="tf-checkout-consent__error">{error}</div>}
+        </div>
+      )
+    case 'image':
+      // File capture needs an upload rail the SDK doesn't own yet — surface it
+      // rather than silently dropping a required field.
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <span className="tf-checkout-note">
+            Image upload isn’t supported in this build.
+          </span>
+        </Field>
+      )
+    default:
+      // text / phone / email
+      return (
+        <Field label={label} error={error} invalid={invalid}>
+          {desc}
+          <Input
+            type={
+              field.type === 'email' ? 'email' : field.type === 'phone' ? 'tel' : 'text'
+            }
+            value={asString(value)}
+            invalid={invalid}
+            aria-invalid={invalid}
+            onChange={(e) => onChange(e.target.value)}
+          />
+        </Field>
+      )
+  }
+}
+
+export interface CustomFieldGroupFieldsProps {
+  group: EventCustomFieldGroup
+  values: CustomFieldValues
+  onChange: (name: string, value: FieldValue) => void
+  /** Restrict to fields scoped to this holder's ticket type (ticket groups). */
+  ticketTypeId?: string
+}
+
+/** Render every field in a group, wired to a values map. */
+export const CustomFieldGroupFields: FC<CustomFieldGroupFieldsProps> = ({
+  group,
+  values,
+  onChange,
+  ticketTypeId,
+}) => (
+  <>
+    {ticketFieldsFor(group.fields, ticketTypeId).map((f) => (
+      <CustomFieldInput
+        key={f.id}
+        field={f}
+        value={values[f.name]}
+        onChange={(v) => onChange(f.name, v)}
+      />
+    ))}
+  </>
+)
+
+/** True when every required field in the group has a non-empty value.
+ *  Re-exported from the SDK so web, native and the engine preflight all apply
+ *  one rule (including its "image uploads are server-authoritative" carve-out). */
+export { customFieldsComplete } from 'tf-checkout-shared'

package/src/ui/Field.tsx

@@ -0,0 +1,114 @@
+import React, {
+  forwardRef,
+  type FC,
+  type InputHTMLAttributes,
+  type ReactNode,
+  type SelectHTMLAttributes,
+  type TextareaHTMLAttributes,
+} from 'react'
+
+import { cx } from './cx'
+
+/** Labeled wrapper — owns the label + error row so controls stay consistent. */
+export const Field: FC<{
+  label?: ReactNode
+  error?: ReactNode
+  invalid?: boolean
+  className?: string
+  children: ReactNode
+}> = ({ label, error, invalid, className, children }) => (
+  <label
+    className={cx(
+      'tf-checkout-field',
+      invalid && 'tf-checkout-field--invalid',
+      className
+    )}
+    data-checkout-invalid={invalid || undefined}
+  >
+    {label != null && <span className="tf-checkout-field__label">{label}</span>}
+    {children}
+    {error != null && (
+      <span className="tf-checkout-field__error" role="alert">
+        {error}
+      </span>
+    )}
+  </label>
+)
+
+/** Lay out two fields side by side. */
+export const FieldRow: FC<{ className?: string; children: ReactNode }> = ({
+  className,
+  children,
+}) => (
+  <div className={cx('tf-checkout-field', 'tf-checkout-field--row', className)}>
+    {children}
+  </div>
+)
+
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  invalid?: boolean
+}
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ invalid, className, ...rest }, ref) => (
+    <input
+      ref={ref}
+      className={cx(
+        'tf-checkout-input',
+        invalid && 'tf-checkout-input--invalid',
+        className
+      )}
+      {...rest}
+    />
+  )
+)
+Input.displayName = 'Input'
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  invalid?: boolean
+}
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ invalid, className, ...rest }, ref) => (
+    <textarea
+      ref={ref}
+      className={cx(
+        'tf-checkout-input',
+        'tf-checkout-textarea',
+        invalid && 'tf-checkout-input--invalid',
+        className
+      )}
+      {...rest}
+    />
+  )
+)
+Textarea.displayName = 'Textarea'
+
+export interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+  invalid?: boolean
+}
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(
+  ({ invalid, className, children, ...rest }, ref) => (
+    <select
+      ref={ref}
+      className={cx(
+        'tf-checkout-select',
+        invalid && 'tf-checkout-select--invalid',
+        className
+      )}
+      {...rest}
+    >
+      {children}
+    </select>
+  )
+)
+Select.displayName = 'Select'
+
+export interface CheckboxProps extends InputHTMLAttributes<HTMLInputElement> {
+  label?: ReactNode
+}
+/** A checkbox is its own label — don't wrap it in `<Field>`. */
+export const Checkbox: FC<CheckboxProps> = ({ label, className, ...rest }) => (
+  <label className={cx('tf-checkout-checkbox', className)}>
+    <input type="checkbox" className="tf-checkout-checkbox__box" {...rest} />
+    {label != null && <span className="tf-checkout-checkbox__label">{label}</span>}
+  </label>
+)

package/src/ui/I18nProvider.tsx

@@ -0,0 +1,36 @@
+import React, { createContext, useContext, useMemo, type FC, type ReactNode } from 'react'
+import {
+  createTranslator,
+  DEFAULT_LOCALE,
+  type LocaleCode,
+  type Messages,
+  type Translate,
+} from 'tf-checkout-shared'
+
+/**
+ * React binding for the shared core's translator.
+ *
+ * The resolution itself lives in `tf-checkout-shared` so native gets the same
+ * behaviour; this file only carries it through React context.
+ *
+ * The default context value is a real English translator, not null, so any
+ * component calling `useT()` outside a provider still renders correct copy.
+ * That keeps this change backwards compatible: a host that never passes
+ * `locale` sees exactly the strings it saw before.
+ */
+const I18nCtx = createContext<Translate>(createTranslator({ locale: DEFAULT_LOCALE }))
+
+export interface I18nProviderProps {
+  locale?: LocaleCode
+  /** Per-key overrides, merged over the locale. */
+  messages?: Partial<Messages>
+  children?: ReactNode
+}
+
+export const I18nProvider: FC<I18nProviderProps> = ({ locale, messages, children }) => {
+  const t = useMemo(() => createTranslator({ locale, messages }), [locale, messages])
+  return <I18nCtx.Provider value={t}>{children}</I18nCtx.Provider>
+}
+
+/** Returns the active translator. Safe to call anywhere in the SDK tree. */
+export const useT = (): Translate => useContext(I18nCtx)

package/src/ui/InstallmentPicker.tsx

@@ -0,0 +1,69 @@
+/**
+ * MSI (meses sin intereses) picker. Mexican card payments can be split into
+ * interest-free installments: mid-payment the engine calls `onInstallmentOffers`
+ * with the available plans and waits for the buyer's choice. This hook bridges
+ * that callback to an overlay — `<CheckoutProvider>` wires it by default, so
+ * `<EmbeddedCheckout/>` gets MSI for free. Returns the port + the overlay to render.
+ */
+import React, { useCallback, useState } from 'react'
+
+import type { InstallmentOffer } from 'tf-checkout-shared'
+
+import { Button } from './Button'
+
+export const useInstallmentPicker = () => {
+  const [pending, setPending] = useState<{
+    offers: InstallmentOffer[]
+    resolve: (o: InstallmentOffer | null) => void
+  } | null>(null)
+
+  // Stable across renders (useCheckout reads ports once) — resolves when the
+  // buyer picks a plan (or declines) below.
+  const onInstallmentOffers = useCallback(
+    (offers: InstallmentOffer[]) =>
+      new Promise<InstallmentOffer | null>((resolve) => setPending({ offers, resolve })),
+    []
+  )
+
+  const choose = (o: InstallmentOffer | null) => {
+    pending?.resolve(o)
+    setPending(null)
+  }
+
+  const picker = pending ? (
+    <div
+      className="tf-checkout-installments"
+      role="dialog"
+      aria-label="Choose installments"
+    >
+      <div className="tf-checkout-installments__box">
+        <strong>Pay in installments?</strong>
+        <div className="tf-checkout-installments__list">
+          {pending.offers.map((o, i) => (
+            <button
+              key={i}
+              type="button"
+              className="tf-checkout-installments__opt"
+              onClick={() => choose(o)}
+            >
+              <span>
+                {o.count} × {o.per_installment_formatted ?? o.per_installment}
+              </span>
+              <span className="tf-checkout-installments__meta">
+                {o.total_formatted ? `${o.total_formatted} total` : ''}
+                {o.diff_from_original_formatted
+                  ? ` · ${o.diff_from_original_formatted}`
+                  : ''}
+              </span>
+            </button>
+          ))}
+        </div>
+        <Button variant="ghost" block onClick={() => choose(null)}>
+          Pay in full instead
+        </Button>
+      </div>
+    </div>
+  ) : null
+
+  return { onInstallmentOffers, picker }
+}

package/src/ui/Loader.tsx

@@ -0,0 +1,12 @@
+import React, { type FC } from 'react'
+
+import { cx } from './cx'
+
+/** A spinner that inherits `currentColor` (so it works inside buttons/text). */
+export const Loader: FC<{ className?: string }> = ({ className }) => (
+  <span
+    className={cx('tf-checkout-loader', className)}
+    role="status"
+    aria-label="Loading"
+  />
+)