@lockerverse/react 0.2.155 → 0.2.157

package/guides/integration.md

@@ -0,0 +1,259 @@
+# Lockerverse integration guide
+
+Package: @lockerverse/react@0.2.157
+
+Generated from this release's maintained documentation. Do not edit this copy.
+
+## Installed SDK integration guides
+
+## Read the installed contract first
+
+For an installed project, read `node_modules/@lockerverse/react/guides/integration.md`
+and the guide for the requested resource:
+
+- `node_modules/@lockerverse/react/guides/auctions.md`
+- `node_modules/@lockerverse/react/guides/payment-widgets.md`
+- `node_modules/@lockerverse/react/guides/events.md`
+- `node_modules/@lockerverse/react/guides/signup.md`
+
+These files ship with each release. Their contract matches that installed
+release. Also read its `README.md`, `package.json` exports, peer dependencies,
+and public `.d.ts` declarations. Do not import private `dist` modules. Online
+examples can describe a newer release. These guides are generated from the same
+maintained documentation as the website; do not edit generated guide copies.
+
+## Install or upgrade without downgrading
+
+Inspect the package manager, lockfile, and installed versions first. Treat a
+version in the admin prompt as the minimum supported stable release, not a
+request to replace an existing newer release. Keep `@lockerverse/react` and
+`@lockerverse/sdk` on the same exact stable version. If both are already on a
+newer matching stable version, keep them and read their installed guides. If the
+pair is missing, older, mismatched, or lacks the required guide, select a
+published matching stable release that meets the prompt minimum and is not
+older than either installed stable package. Verify that both versions exist
+before installing. Do not choose a development dist-tag or downgrade a package.
+Use the existing package manager and update its lockfile.
+
+Keep compatible React and React DOM versions. The current SDK supports
+`^18.2.0 || ^19.2.0`; check the selected release's manifest. Do not upgrade a
+compatible React 18 site to React 19. If an upgrade is needed, update React and
+React DOM together without replacing the framework or router. Native payment
+and auction checkout need the optional `@stripe/react-stripe-js` and
+`@stripe/stripe-js` peers specified by the installed manifest. Catalog, Events,
+and signup code must use their narrow imports and must not load Stripe.
+
+## Preserve the existing host and saved resource
+
+Use the existing framework, router, page structure, components, and theme.
+Connect the matching existing section and controls. Add one section only when
+none exists. Do not create a second application, backend, router, or duplicate
+interface. Change only files needed for this integration; do not edit generated
+route trees. Match light/dark theme to the host and use supported props and
+`--lockerverse-*` tokens with complete valid CSS values. Do not override private
+SDK selectors or rebuild the supplied auction, checkout, or signup controls.
+
+The admin prompt supplies public resource identity and requested behavior.
+Load current settings from Lockerverse on each page load or refresh. Do not
+copy item names, prices, order, images, dates, quantities, availability, fees,
+shipping rules, or form definitions into permanent local configuration. Use
+only the requested community and saved resource. Encode route values and keep
+host search parameters. A URL must not select a different configured community
+or resource. A mounted hook keeps one identity; remount deliberately when the
+resource changes, never during an unresolved submission.
+
+Use the supplied `apiBaseUrl` and `environment` exactly. API base URLs include
+`/api`. Production is the default when neither is supplied. Do not infer the
+environment from the host domain or silently use development. Lockerverse
+supplies Stripe publishable keys and connected-account options. Do not add
+secret keys, an unrelated Stripe account, Supabase payment tables, guessed
+endpoints, or an independent payment flow.
+
+## Server rendering and static sites
+
+On an existing SSR host, load public data with the matching SDK client in the
+framework's server route or server function. Seed the matching React hook and
+keep available content visible during refresh. Render public text, images,
+links, and metadata in the first HTTP response. Keep Stripe initialization and
+browser-storage access in the browser. Use the product guide for exact seed
+arguments and loading behavior.
+
+On an existing static Vite site, preserve its client-loaded flow. Explain that
+current item-specific first-response content and metadata require an SSR
+response or another static build. Do not add a per-site server or replace the
+framework solely for this integration. A browser-only title change is not
+server-rendered metadata. The host owns canonical URLs, document metadata,
+sitemaps, robots rules, and its indexing policy.
+
+## Private data and submission state
+
+Never put contact details, payment tokens, or recovery records in URLs, public
+loader data, metadata, analytics, or logs. Use public read data only in SSR
+responses. Do not submit live payments, bids, or signup records during an
+implementation check. Use the product's completion callback as documented;
+navigation, dialog closure, and receipt amounts are not proof of payment.
+
+Payment-widget recovery and auction recovery have different contracts. Payment
+widget recovery contains a payment reference and connected account and can be
+stored as specified in its guide. Auction purchase recovery includes buyer data
+and a Stripe token: keep it private and in memory by default. Do not persist it
+merely because widget recovery can be persisted. Never replace an unresolved
+operation with a fresh payment or automatically retry an uncertain bid.
+
+## Verify the integration
+
+Build with the host's existing commands. Check desktop and 390 by 844 mobile
+layouts for overflow, readable content, and reachable controls. Check loading,
+empty, error, retry, unavailable, and ready states as applicable. Check route
+direct entry, reload, Back/Forward, and native new-tab links. For SSR, inspect
+the raw first HTTP response, then check hydration and live refresh. Open
+checkout only to inspect saved settings; do not submit a transaction. Use SDK
+simulation pages for result layouts. Report verified checks and any limits.
+
+## Configuration and environment
+
+Production is the default. Payment, signup, auction, and Events hooks accept
+`apiBaseUrl` and `environment` together. A custom URL requires an explicit
+environment; `environment: "development"` also requires a URL. Include `/api`
+in the API base URL. Do not infer the environment from the host website's URL.
+Use the public community and resource slugs from the intended integration.
+Signup uses `signupSlug`; payment uses `widgetSlug`.
+
+The backend supplies the Stripe publishable key and connected account. Do not
+hard-code either value or pass a secret key. The default Stripe loader handles
+initialization. If a host supplies `stripeLoader={loadStripe}`, preserve all
+loader arguments, including the connected-account options.
+
+```tsx
+const widget = useLockerverseWidget({
+  apiBaseUrl: "https://portal-dev.lockerverse.com/api",
+  communitySlug: "luis-c",
+  environment: "development",
+  widgetSlug: "new-payment-widget",
+});
+
+<LockerversePayment
+  selection={[{ productSlug: "adult", quantity: 1 }]}
+  widget={widget}
+/>
+```
+
+## Server rendering
+
+Load public data with the matching core SDK client in a server route or loader,
+then pass that validated snapshot to the React hook. The second argument is
+optional; without it, the hook keeps its loading state until the browser read
+completes. The seed is read once on mount and is retained if revalidation
+fails. A later seed prop change does not replace live data. Remount with a new
+React `key` when the resource identity changes.
+
+```tsx
+import { createLockerversePublicEventsClient } from "@lockerverse/sdk/public-events";
+
+// Call this from a server route or loader.
+export async function loadPublicEvents() {
+  return createLockerversePublicEventsClient({ communitySlug: "auburn" }).list();
+}
+```
+
+```tsx
+import type { LockerversePublicEvent } from "@lockerverse/sdk/public-events";
+import { useLockerversePublicEvents } from "@lockerverse/react/public-events";
+
+export function CommunityEvents({ initialEvents }: { initialEvents: LockerversePublicEvent[] }) {
+  const events = useLockerversePublicEvents(
+    { communitySlug: "auburn" },
+    { initialEvents }
+  );
+  return <h1>{events.events?.[0]?.name ?? "Events"}</h1>;
+}
+```
+
+Payment uses `createLockerverseCheckoutClient(options).load()` on the server
+and `useLockerverseWidget(options, { initialCatalog })` in the React component.
+Signup uses `createLockerverseSignupClient(options).load()` and
+`useLockerverseSignup(options, { initialSignup })`. Use matching options on
+both sides. An empty `initialEvents: []` is valid. Use the exact public SDK
+client result, not unvalidated server JSON or a stored payment quote. Do not
+put personal information, secret keys, or payment recovery data in the seed.
+The browser still requests current public data after mount. A failed refresh
+retains the last good snapshot and exposes `error` and `refresh`; loading means
+a read is in progress, not that the snapshot is unavailable. Signup and event
+content remain visible during refresh. Payment shows the seeded catalog heading
+and public base product prices, but keeps submit controls behind a loading state
+until the catalog refresh finishes. Payment quotes remain authoritative from
+the checkout client. A refreshed signup definition removes obsolete custom
+field choices from the form and submission while preserving valid answers.
+
+In Next.js, use a request-local server loader (for example, `React.cache`) to
+avoid duplicate reads in one request. Use `no-store` for changing public
+auction data and allow the auction hook to refresh after mount. A static site
+can refresh after hydration but cannot produce item-specific first-response
+metadata without a build or server response for each item.
+
+Keep browser storage and payment recovery behind a client-only boundary where
+the host needs one. Keep those accesses in effects, not at module scope or
+during server rendering. For TanStack Router, import `ClientOnly` from
+`@tanstack/react-router` and put the recovery owner and checkout interaction
+inside it:
+
+```tsx
+import { ClientOnly } from "@tanstack/react-router";
+
+<ClientOnly fallback={<p>Loading checkout...</p>}>
+  <Checkout />
+</ClientOnly>
+```
+
+The host supplies this boundary; TanStack Router is not an SDK dependency.
+Public catalog and item content can remain outside it. Wait for saved recovery
+state to load before mounting payment. Remount the recovery owner when its
+resource or recovery key changes.
+
+## Resource identity
+
+A mounted hook or widget keeps one resource identity. Do not change its API,
+environment, community slug, widget slug, or signup slug. To show a different
+resource, remount the owning component with a new React `key`:
+
+```tsx
+<Checkout
+  key={`${communitySlug}:${widgetSlug}`}
+  communitySlug={communitySlug}
+  widgetSlug={widgetSlug}
+/>
+```
+
+Selection, theme, callbacks, and other view properties can change without a
+remount. `refresh()` reloads the same resource.
+
+## Styling
+
+Auction checkout, payment, and signup use common email, phone, field-error, and checkbox controls. Payment and signup share the custom-field renderer. Phone fields use the lightweight payment/signup country list, normalization, and Valibot format validation. The shared phone control is imported directly, with no separate phone chunk or metadata library. Each flow keeps its existing field configuration and backend rules.
+
+Payment and auction Stripe forms resolve the rendered SDK font and theme tokens before passing them to Stripe. Custom font files are not loaded into Stripe by a font family name alone. See [the shared form foundation](https://github.com/Lockerverse/lockerverse-sdk/blob/main/docs/shared-form-foundation.md) for module boundaries and bundle measurement.
+
+Use `theme="dark"` or `theme="light"` to match the host background. The outer payment, signup, auction, and Events widgets are transparent, so the host controls their canvas. Lockerverse applies the community branding returned by the widget API. Pass the same `LockerverseStyle` object to payment, signup, and donate launcher components.
+
+```tsx
+import type { LockerverseStyle } from "@lockerverse/react";
+
+const lockerverseStyle = {
+  "--lockerverse-accent": "#ff6b35",
+  "--lockerverse-bg": "#fffaf0",
+  "--lockerverse-control": "#f5eddf",
+  "--lockerverse-radius": "14px",
+  "--lockerverse-text": "#211c17",
+} satisfies LockerverseStyle;
+
+<LockerversePayment
+  selection={selection}
+  style={lockerverseStyle}
+  widget={widget}
+/>
+```
+
+The canonical `--lockerverse-*` tokens control every component. Existing
+`--lockerverse-signup-*` tokens remain supported as signup-only aliases.
+
+The package keeps React, React DOM, and Stripe's React libraries as peer dependencies so it does not ship duplicate framework code. `LockerversePayment` leaves product selection to its host. `LockerverseDonateLauncher` provides selection from the existing widget catalog. Neither component depends on Lockerverse's Next.js application components.