@bunnyapp/components 1.8.0-beta.55 → 1.8.0-beta.56

package/README.md

@@ -148,6 +148,8 @@ For a more complete example in the codebase, see the `useSetQuoteQueryData` hook
 
 ### Styling components
 
+Signup and Checkout are styled through their `appearance` prop instead of the two layers below; see [Styling Signup and Checkout](#styling-signup-and-checkout).
+
 Components are styled through two complementary layers:
 
 1. **Ant Design tokens** — for properties that drive antd primitives (Button, Input, Card, etc.). Set globally or per-component via `ConfigProvider`. See antd's [Customize Theme docs](https://ant.design/docs/react/customize-theme) for the full token reference.
@@ -197,6 +199,67 @@ Currently exposed for the Upgrade component:
 
 For a live example combining both layers, see the `PrideTheme` story in `Upgrade.stories.tsx`.
 
+#### Styling Signup and Checkout
+
+Signup and Checkout render the same screen and are styled the same way: through the `appearance` prop. It is the only styling surface for this screen, and it is modelled on Stripe's Appearance API (same variable names, selector syntax and state suffixes).
+
+```tsx
+import { BunnyProvider, Signup } from '@bunnyapp/components';
+
+<BunnyProvider apiHost="https://your-subdomain.bunny.com" token={token}>
+  <Signup
+    priceListCode="..."
+    appearance={{
+      variables: {
+        colorPrimary: '#14532d',
+        colorBackgroundSummary: '#f6f1e7',
+        fontFamily: '"Source Serif 4", Georgia, serif',
+        borderRadius: '0px',
+      },
+      rules: {
+        '.Label': { textTransform: 'uppercase', letterSpacing: '0.08em' },
+        '.Input:focus': { borderColor: '#14532d', boxShadow: '0 0 0 1px #14532d' },
+        '.Button': { backgroundColor: '#1c1917', padding: '14px 16px' },
+      },
+      fonts: [{ cssSrc: 'https://fonts.googleapis.com/css2?family=Source+Serif+4:wght@400;600&display=swap' }],
+    }}
+  />
+</BunnyProvider>
+```
+
+`<Checkout>` takes the same prop. `variables` feed the default rules; your `rules` are then merged over those defaults, selector by selector and property by property. The result styles Bunny's own fields and is handed to the payment provider's hosted fields (Stripe's Payment Element) as well, so the two always match. There is no runtime validation: the TypeScript types are the contract.
+
+The types, exported from the package, are the reference: every variable, selector (with its states) and allowed property is documented there with what it controls and its default. Hover `appearance` and its keys in your editor, or read `dist/index.d.ts`. Shared selectors (such as `.Input` and `.Tab`) also reach the payment fields; Bunny-only ones (such as `.Button`) can additionally size their element. `--invalid` is a field that failed validation and `--selected` the chosen payment method; the other suffixes are CSS pseudo-classes. A state rule only needs the properties that change.
+
+**Use literal values.** Write real CSS values (`#14532d`, `12px`, `"Space Grotesk", sans-serif`), never `var(--my-token)`: variables and the shared rules are sent into the payment iframe, where your page's custom properties do not exist. Use a plain color (hex or `rgb()`) for `colorPrimary` and `colorSuccess`, as shades are computed from them.
+
+**Sizing.** There is no `height` property. An input's height is its vertical padding + `lineHeight` + borders, because that is how hosted payment fields are sized (44px by default). Raise the `.Input` padding to make Bunny's fields and the payment fields taller together; the primary button is sized the same way through `.Button` padding. `.Summary` and `.Form` are capped at `36rem` with `4rem` of padding (`1.5rem` on phones): change these with `maxWidth` and `padding`.
+
+**Fonts.** The components never load a font: by default their text inherits your page's font. Hosted payment fields are the exception: they render in an iframe, which can be told your font's name but cannot see fonts loaded on your page. If your page uses a web font, declare it in `appearance.fonts` (a stylesheet of `@font-face` rules, `{ cssSrc: 'https://...' }`, or a single file, `{ family, src, weight }`) so the iframe loads it too; system fonts need no entry. To give this screen a different font from the rest of your page, set `variables.fontFamily`, declare the font in `fonts`, and load it on your page yourself. Fonts are fixed once the payment form has mounted: changing `fonts` afterwards remounts the payment fields and clears anything typed into them, so set them once, up front.
+
+**Dark mode.** `<BunnyProvider darkMode>` picks the base: dark default variables and the payment provider's dark theme. `appearance` is applied on top, exactly as in light mode. For a dark design, set `darkMode` and override what you need; dark colors alone leave everything you did not override on the light defaults.
+
+**Relation to `configProviderProps`.** `BunnyProvider`'s antd theme (your Bunny brand color) still supplies the variables' defaults, so a brand color or border radius set there reaches this screen without any `appearance`. Where both are set, `appearance` wins. The exception is antd's `fontFamily`, which does not reach this screen: text inherits your page's font unless you set `variables.fontFamily`.
+
+**Not covered yet.**
+
+- DemoPay's test card fields (shown when no real payment provider is configured) only partly follow `appearance`.
+- The pricing tooltip on tiered line items and the tags ("Paid", "Trial", an applied coupon) use antd's theme.
+- Every other component in the library is still styled through the two layers above.
+
+**Migrating from the earlier styling hooks.** The `data-slot` attributes, the `.bunny-signup` / `.bunny-checkout` classes and the `--bunny-signup-bg` / `--bunny-checkout-bg` CSS variables were removed from this screen:
+
+| Before | Now |
+| --- | --- |
+| `--bunny-signup-bg`, `--bunny-checkout-bg` | `variables.colorBackgroundSummary` |
+| `[data-slot="signup-summary"]` / `[data-slot="checkout-summary"]` | the `.Summary` rule |
+| `[data-slot="signup-form"]` / `[data-slot="checkout-form"]` | the `.Form` rule |
+| `[data-slot="signup-root"]` / `[data-slot="checkout-root"]` | the component's `style` prop |
+
+The other slots (summary header, receipt, quote document, footer, success panel) have no replacement selector; their colors, borders and fonts follow the variables.
+
+Two complete themes built only with `appearance` are in Storybook: see [Appearance theme stories](#appearance-theme-stories).
+
 ### Deprecating @bunnyapp/common
 
 We are gradually deprecating `@bunnyapp/common` and moving types and enums locally to this repository. When something is moved from `@bunnyapp/common`, follow this pattern:
@@ -220,7 +283,97 @@ We are gradually deprecating `@bunnyapp/common` and moving types and enums local
 
 ### Storybook stories
 
-To view the storybook stories, run `npx storybook dev`.
+Storybook is where components are developed and checked against mocked API data. Stories live next to their component as `*.stories.tsx`.
+
+#### Running Storybook
+
+```bash
+npm run storybook
+```
+
+This serves Storybook on [http://localhost:6006](http://localhost:6006) with hot reloading. `npm run build-storybook` writes a static build to `storybook-static/`.
+
+#### Where stories get their data
+
+Stories never reach a real API. Requests are intercepted by [MSW](https://mswjs.io/) through `msw-storybook-addon`:
+
+- `src/mocks/handlers.ts` holds the shared handlers (GraphQL queries and mutations by operation name, plus a few HTTP routes). `src/mocks/checkoutHandlers.ts` adds what the Signup and Checkout stories request, and is included in the shared list.
+- `.storybook/preview.tsx` starts MSW with the shared handlers (`initialize({}, handlers)`) and registers the `mswLoader`, which applies a story's own handlers on top.
+- A story, or a whole stories file through its `meta`, overrides a handler with `parameters.msw.handlers`:
+
+  ```tsx
+  export const StoredPaymentMethod: Story = {
+    args: { ...basicArgs },
+    parameters: {
+      msw: { handlers: [savedPaymentMethodHandler] },
+    },
+  };
+  ```
+
+The mock payloads are modelled on real API responses, so keep the shape of a real response when you add or change one. The `apiHost` and `token` passed to `BunnyProvider` in stories are placeholders.
+
+If a story hangs on a loading state, a request is most likely unmocked. Open the browser console and look for MSW's warning about a request "without a matching request handler"; it names the operation. Add a handler for it to `src/mocks/handlers.ts` (or to the story's `parameters.msw.handlers` if only that story needs it).
+
+#### Stripe in stories
+
+Stripe.js only loads with a real publishable key, so the mocks include the Stripe plugin only when one is configured. Add a test key to `.env` (see `.env.example`):
+
+```
+STORYBOOK_STRIPE_PUBLISHABLE_KEY=pk_test_...
+```
+
+Restart Storybook after changing it. Without the key, stories that take a payment fall back to DemoPay's test card fields. `.env*` files are gitignored (only `.env.example` is committed), so the key stays local.
+
+#### Writing a story
+
+Components need a `BunnyProvider` around them. Add it as a decorator in the file's `meta`, reading `darkMode` from the story's parameters:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BunnyProvider from '../BunnyProvider/BunnyProvider';
+import { DarkModeParams } from '../../storybook-utils';
+import Signup from './Signup';
+
+const meta: Meta<typeof Signup> = {
+  component: Signup,
+  decorators: [
+    (Story, { parameters }) => (
+      <BunnyProvider apiHost="https://your-subdomain.bunny.com" token="your-token-here" darkMode={parameters.darkMode}>
+        <Story />
+      </BunnyProvider>
+    ),
+  ],
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { priceListCode: 'your-price-list-code-here' },
+};
+
+// Dark mode: `DarkModeParams` sets `darkMode` for the decorator and a dark canvas.
+export const DarkMode: Story = {
+  args: { ...Default.args },
+  parameters: { ...DarkModeParams },
+};
+
+// Phone layout: renders the story in a 320px wide iframe.
+export const Mobile: Story = {
+  args: { ...Default.args },
+  globals: { viewport: { value: 'mobile1', isRotated: false } },
+};
+```
+
+Set the viewport through story-level `globals`, as above. The installed Storybook (10) ignores the older `parameters: { viewport: { defaultViewport: 'mobile1' } }` form, which leaves the story at full width, so components that switch layout on window width render their desktop layout. The available names are Storybook's default set (`mobile1`, `mobile2`, `tablet`, `desktop`); the Signup and Checkout stories share the value as `mobileGlobals` from `CheckoutShared/stories/themes.ts`.
+
+The `autodocs` tag generates a docs page for the component from its props and stories.
+
+#### Appearance theme stories
+
+Signup and Checkout each have `Ledger` and `Midnight` stories (with `LedgerMobile` and `MidnightMobile`). The two themes are defined once in `src/components/CheckoutShared/stories/themes.ts` using only the public `appearance` prop, and look nothing like the default or each other. They are the check that the styling API works: after changing anything under `CheckoutShared/appearance/`, open both, with a Stripe key set, and confirm that Bunny's fields and Stripe's fields still match. Every Signup and Checkout story also exposes `appearance` as an editable control in the Controls panel.
 
 #### Visual tests