@solvapay/react 1.0.7 → 1.0.8-preview.2

package/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to @solvapay/react
+
+This package ships two tiers:
+
+- **`@solvapay/react`** — default tree. Drop-in components (`CheckoutLayout`, `PaymentForm`, …) that render a golden-path UI. Internally, they are thin shims over the primitives.
+- **`@solvapay/react/primitives`** — unstyled compound primitives. Consumers compose these to build fully custom UIs.
+
+This file is the canonical contract for primitives until the cross-repo Mintlify docs land. Every primitive you add or edit MUST follow these rules.
+
+## Primitive contract
+
+### Compound API
+
+Every primitive is a compound: a `Root` plus named subcomponents.
+
+```tsx
+<PlanSelector.Root>
+  <PlanSelector.Heading />
+  <PlanSelector.Grid>
+    <PlanSelector.Card>
+      <PlanSelector.CardName />
+      <PlanSelector.CardPrice />
+    </PlanSelector.Card>
+  </PlanSelector.Grid>
+</PlanSelector.Root>
+```
+
+- Export subcomponents as properties on the `Root` (`PlanSelector.Card`) **and** as named exports from `./primitives` for tree-shake-friendly use.
+- No render-prop children. No `classNames` prop. No `unstyled` flag.
+
+### `asChild`
+
+Every leaf subcomponent accepts `asChild?: boolean`. When `true`, it renders its single child via `<Slot>` and merges props/ref onto the child.
+
+```tsx
+<PlanSelector.Card asChild>
+  <Card>{/* shadcn/ui card */}</Card>
+</PlanSelector.Card>
+```
+
+Use `Slot` from `./primitives/slot`. Refs are merged via `composeRefs`; event handlers are chained via `composeEventHandlers` (consumer runs first; `preventDefault()` skips the primitive handler).
+
+### `data-state` vocabulary
+
+Every stateful subcomponent emits a `data-state` attribute from a fixed, documented vocabulary. States are driven by context (`PlanSelectionContext`, `PaymentFormContext`), never by subcomponent-local state.
+
+| Primitive | `data-state` values |
+| --- | --- |
+| `PlanSelector.Card` | `idle` \| `selected` \| `current` \| `disabled` |
+| `PaymentForm.SubmitButton` | `idle` \| `processing` \| `disabled` |
+| `ActivationFlow.Root` | `summary` \| `activating` \| `selectAmount` \| `topupPayment` \| `retrying` \| `activated` \| `error` |
+| `CreditGate.Root` | `allowed` \| `blocked` \| `loading` |
+| `PurchaseGate.Root` | `allowed` \| `blocked` \| `loading` |
+| `CancelledPlanNotice.Root` | `active` \| `expired` |
+| `CancelPlanButton` | `idle` \| `cancelling` |
+| `BalanceBadge` | `loading` \| `zero` \| `low` \| `ok` |
+| `AmountPicker.Option` | `idle` \| `selected` \| `disabled` |
+
+Secondary flags use `data-<flag>` (e.g. `data-free`, `data-popular`, `data-has-reason`).
+
+### Opaque selectors
+
+Every primitive root emits `data-solvapay-<primitive>` (and subcomponents emit `data-solvapay-<primitive>-<part>` when they need to be targetable). Do not rely on internal class names; those are not a public API.
+
+### `.Loading` and `.Error`
+
+Every async primitive exposes `.Loading` and `.Error` subcomponents that render when the context reports loading/error. They render `null` otherwise. Always provide a fallback UI path — don't rely on consumers remembering to add them.
+
+### Errors self-heal
+
+Throw structured errors from `src/utils/errors.ts` for wiring mistakes:
+
+- `MissingProviderError` — primitive rendered outside `<SolvaPayProvider>`.
+- `MissingEnvVarError` — required env var not set.
+- `MissingApiRouteError` — backend route not installed.
+- `MissingProductRefError` — primitive needs `productRef` and none was provided.
+
+Each error includes `code`, `message` (fix + docs URL), and `docsUrl`.
+
+## Prohibited patterns
+
+When touching a primitive, these must stay gone:
+
+- `classNames` prop, `unstyled` prop, `RenderArgs` / function-child overloads.
+- Inline `style={{ ... }}` inside `src/primitives/**`.
+- `next/*` imports (the package must bundle on Vite/Remix).
+- `as any`, `as unknown as ...` except when unavoidable; justify with a comment.
+- Implicit `enum`; use union types.
+
+## TDD checklist per primitive
+
+Write the primitive and its test file in the same commit. Every primitive test covers:
+
+1. **Default render** — subcomponents render the expected DOM.
+2. **`asChild` composition** — refs merge, handlers chain, `data-*` + `aria-*` forward to the child element.
+3. **`data-state` transitions** — context-driven state flips the attribute correctly.
+4. **`.Loading` / `.Error`** — rendered when context signals loading/error.
+5. **Provider-missing + env-missing** — the correct structured error class is thrown with its docs URL.
+
+Delete legacy tests that assert on `classNames` / function-child / `RenderArgs` **before** landing the rewrite.
+
+## Adding a new primitive (checklist)
+
+1. Write the test file following the TDD checklist above.
+2. Create `src/primitives/<Name>.tsx` with `Root` + subcomponents + `asChild` + `data-state`.
+3. Re-export from `src/primitives/index.ts`.
+4. If the primitive is part of the default tree, update the shim in `src/components/<Name>.tsx` to render it with the golden-path children.
+5. Update the `data-state` table in this file if you introduce a new state.
+6. Keep the package-local README cheat sheet in sync.
+
+## Commands
+
+```bash
+pnpm --filter @solvapay/react test        # run the primitive + component tests
+pnpm --filter @solvapay/react build       # tsup build (top-level + primitives entry)
+pnpm --filter @solvapay/react lint        # eslint
+```

package/README.md

@@ -34,6 +34,126 @@ By default, `SolvaPayProvider` uses:
 - `/api/check-purchase` for purchase checks
 - `/api/create-payment-intent` for payment creation
 - `/api/process-payment` for payment processing
+- `/api/merchant` for merchant identity (`useMerchant`, `MandateText`)
+- `/api/get-product` for single-product lookup (`useProduct`, `CheckoutSummary`)
+
+## Golden path — `<CheckoutLayout>` one-liner
+
+`<CheckoutLayout>` handles the full flow: plan selection, payment (paid/free),
+and usage-based activation. For 90% of integrations this is the only
+component you need.
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout } from '@solvapay/react'
+
+export function BuyNow({ email }: { email: string }) {
+  return (
+    <SolvaPayProvider>
+      <CheckoutLayout
+        productRef="prd_myapi"
+        prefillCustomer={{ email }}
+        requireTermsAcceptance
+        onResult={result => {
+          // result.kind === 'paid' | 'activated'
+        }}
+      />
+    </SolvaPayProvider>
+  )
+}
+```
+
+What happens based on what `<CheckoutLayout>` resolves:
+
+| Product shape | Flow |
+|---|---|
+| One active plan | Auto-skip selection → pay or activate |
+| Multiple plans | Styled `<PlanSelector>` → pay or activate |
+| Free plan (`requiresPayment: false`) | Skip Stripe entirely → `useActivation` |
+| Usage-based plan | `<ActivationFlow>` (summary → top-up → retry → activated) |
+
+Pass `planRef` explicitly to skip the selector and keep today's payment-only
+behavior byte-for-byte (backwards compatible with pre-selector integrations).
+
+### Skipping plan selection
+
+```tsx
+<CheckoutLayout
+  planRef="pln_premium"
+  productRef="prd_myapi"
+  prefillCustomer={{ email }}
+  requireTermsAcceptance
+  size="auto"
+  onSuccess={() => console.log('paid')}
+/>
+```
+
+The section below ("Drop-in checkout with `<CheckoutLayout>`") is the original
+single-plan form — still supported, still works the same.
+
+## Drop-in checkout with `<CheckoutLayout>`
+
+For a fixed plan checkout (summary, SCA mandate, Stripe PaymentElement,
+prefilled customer echo, optional terms checkbox):
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout } from '@solvapay/react'
+
+export function BuyNow({ email }: { email: string }) {
+  return (
+    <SolvaPayProvider>
+      <CheckoutLayout
+        planRef="pln_premium"
+        productRef="prd_myapi"
+        prefillCustomer={{ email }}
+        requireTermsAcceptance
+        size="auto"
+        onSuccess={() => console.log('paid')}
+      />
+    </SolvaPayProvider>
+  )
+}
+```
+
+`size="auto"` uses a `ResizeObserver`, so the same component reflows cleanly
+in chat bubbles, phone viewports, and desktop iframes.
+
+## Composition: slot subcomponents
+
+When you need custom layout, compose `<PaymentForm>` with slot children:
+
+```tsx
+<PaymentForm planRef="pln_premium" productRef="prd_myapi" prefillCustomer={{ email }}>
+  <PaymentForm.Summary />
+  <PaymentForm.CustomerFields />
+  <PaymentForm.PaymentElement />
+  <PaymentForm.MandateText />
+  <PaymentForm.TermsCheckbox />
+  <PaymentForm.SubmitButton />
+</PaymentForm>
+```
+
+Passing no children keeps the current default tree for backwards compatibility.
+
+## Localization
+
+English ships by default. Swap the locale (which also flows through to Stripe
+Elements) and override any strings you like:
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout, type PartialSolvaPayCopy } from '@solvapay/react'
+
+const svSECopy: PartialSolvaPayCopy = {
+  cta: { subscribe: 'Prenumerera', processing: 'Bearbetar...' },
+  terms: { checkboxLabel: 'Jag godkänner villkoren och integritetspolicyn' },
+}
+
+<SolvaPayProvider config={{ locale: 'sv-SE', copy: svSECopy }}>
+  <CheckoutLayout planRef="..." productRef="..." />
+</SolvaPayProvider>
+```
+
+Currency formatting is already locale-correct — `formatPrice` uses
+`Intl.NumberFormat` with the provider locale and the plan's `currency` field.
 
 ### Custom API Routes
 
@@ -316,9 +436,122 @@ const {
 All components and hooks are fully typed. Import types as needed:
 
 ```tsx
-import type { PaymentFormProps, PurchaseStatus, PaymentIntentResult } from '@solvapay/react'
+import type {
+  PaymentFormProps,
+  PurchaseStatus,
+  PaymentIntentResult,
+  CheckoutResult,
+  PaymentResult,
+  ActivationResult,
+} from '@solvapay/react'
 ```
 
+## Plan lifecycle
+
+Beyond checkout itself, three thin styled-default components cover the
+post-purchase experience without requiring custom UI.
+
+### `<CancelPlanButton>`
+
+Wraps `usePurchaseActions.cancelRenewal` with a built-in confirm dialog,
+loading state, and plan-type-aware copy (subscription vs usage-based).
+Auto-reads the active purchase from `usePurchase()`.
+
+```tsx
+import { CancelPlanButton } from '@solvapay/react'
+
+<CancelPlanButton onCancelled={() => router.push('/')} />
+```
+
+Use `confirm={false}` for a single-click cancel, or pass a string to override
+the default copy. The render-prop form exposes `{ cancel, isCancelling,
+disabled, purchase }` for fully custom UI.
+
+### `<CancelledPlanNotice>`
+
+Surfaces automatically when the customer has a cancelled-but-still-active
+purchase. Renders the expiration date, days remaining, cancellation reason,
+and a reactivate CTA. Renders nothing when there's nothing to show.
+
+```tsx
+import { CancelledPlanNotice } from '@solvapay/react'
+
+<CancelledPlanNotice onReactivated={() => refetch()} />
+```
+
+### `<CreditGate>`
+
+Companion to `<PurchaseGate>` for usage-based flows. Blocks access when the
+customer's credit balance falls below a threshold; renders an embedded
+`<TopupForm>` by default.
+
+```tsx
+import { CreditGate } from '@solvapay/react'
+
+<CreditGate minCredits={10}>
+  <ExpensiveFeature />
+</CreditGate>
+```
+
+Customize via the `fallback` prop, or use the render-prop form
+(`children: ({ balance, hasCredits, topup }) => …`) for fully custom UI.
+
+## Server-side usage tracking
+
+There is intentionally no `useTrackUsage()` client hook. Client-reported usage
+is trivially gamed — a user can simply block the fetch to conserve credits.
+Instead, record usage from your server when the expensive work actually runs:
+
+```ts
+// app/api/do-thing/route.ts
+import { trackUsage } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const result = await doTheExpensiveThing()
+  await trackUsage(request, { units: 1 })
+  return NextResponse.json(result)
+}
+```
+
+The same pattern works from a Supabase Edge Function — see below.
+
+## Using with Supabase Edge Functions
+
+Lovable-style apps deploy React frontends against Supabase Edge Functions
+(Deno runtime). The SDK's `api` URL overrides let the exact same
+`<CheckoutLayout>` drop-in work against `/functions/v1/*` routes:
+
+```tsx
+<SolvaPayProvider
+  config={{
+    api: {
+      checkPurchase: `${SUPABASE_URL}/functions/v1/check-purchase`,
+      createPayment: `${SUPABASE_URL}/functions/v1/create-payment-intent`,
+      processPayment: `${SUPABASE_URL}/functions/v1/process-payment`,
+      listPlans: `${SUPABASE_URL}/functions/v1/list-plans`,
+      getMerchant: `${SUPABASE_URL}/functions/v1/get-merchant`,
+      getProduct: `${SUPABASE_URL}/functions/v1/get-product`,
+      // …same pattern for every other endpoint
+    },
+    auth: {
+      adapter: createSupabaseAuthAdapter({ supabaseUrl, supabaseAnonKey }),
+    },
+  }}
+>
+  <CheckoutLayout
+    productRef="prd_myapi"
+    prefillCustomer={{ email }}
+    requireTermsAcceptance
+  />
+</SolvaPayProvider>
+```
+
+The matching Deno edge functions ship in
+[`@solvapay/supabase`](../../packages/supabase) — see
+[`examples/supabase-edge`](../../examples/supabase-edge) for one-liner
+`Deno.serve(handler)` files covering every handler including the new
+`get-merchant` and `get-product` endpoints.
+
 ## More Information
 
 See [`docs/contributing/architecture.md`](../../docs/contributing/architecture.md) for contributor