@nevios/storefront-kit 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,78 @@
+# @nevios/storefront-kit
+
+Themeable React commerce UI for [Nevios](https://nevios.io) storefronts —
+providers, hooks and whole screens built on
+[`@nevios/storefront-js`](https://www.npmjs.com/package/@nevios/storefront-js).
+
+You theme it with CSS variables and override individual slots; you don't rebuild
+it. Every component is styled through `--nv-*` tokens and renders unstyled-ish
+markup, so a shop's own design system can take over piece by piece.
+
+```sh
+pnpm add @nevios/storefront-kit @nevios/storefront-js
+```
+
+Peer dependencies: React 19 and React DOM 19.
+
+## Getting started
+
+```tsx
+import { createStorefrontClient } from "@nevios/storefront-js";
+import { NeviosProvider, I18nProvider } from "@nevios/storefront-kit";
+
+const client = createStorefrontClient({
+  publishableKey: process.env.NEXT_PUBLIC_NEVIOS_STOREFRONT_KEY!,
+  market: "cz",
+});
+
+export function App({ children }) {
+  return (
+    <NeviosProvider client={client}>
+      <I18nProvider locale="cs-CZ">{children}</I18nProvider>
+    </NeviosProvider>
+  );
+}
+```
+
+`I18nProvider` also decides how money is formatted. Pass the shopper's locale
+once and prices come out as `1 299,00 Kč` rather than the runtime default.
+
+## What's in it
+
+| Area | |
+|---|---|
+| Catalog | product + collection views, filters, responsive images |
+| Cart | line items, summary, the `useCart` hook |
+| Checkout | address, shipping picker, payment step, `CheckoutFlow` |
+| Order | `OrderConfirmation`, `OrderStatusPage`, `useOrderStatus` |
+| **Payment** | `PaymentPage`, `PaymentMethodPicker`, `TransferInstructions` |
+| Account | sign-in, addresses, order history |
+| SEO | JSON-LD for products, breadcrumbs, the organization |
+
+Everything is exported from the package root, and everything that fetches goes
+through the one client on context.
+
+## The payment page
+
+`PaymentPage` is the screen a customer reaches from a "finish your payment" link
+in an order e-mail — possibly days later, on another device. Give it the
+payment's token (the order status hands it over as `order.payment.token`) and it
+renders one of four situations: there is something to pay, pay by bank transfer
+(account, variable symbol, QR), already paid, or locked with the reason spelled
+out.
+
+```tsx
+<PaymentPage token={order.payment.token} statusHref={`/orders/${statusToken}`} />
+```
+
+A `null` token renders nothing — the server mints one only while money is owed,
+so its absence is the answer, not an error state to design around.
+
+## Localization
+
+Czech and English ship in the bundle; `I18nProvider` picks by language subtag.
+Bring your own pack with `messages={…}` for anything else.
+
+## License
+
+MIT