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

package/README.md

@@ -148,54 +148,124 @@ For a more complete example in the codebase, see the `useSetQuoteQueryData` hook
 
 ### Styling components
 
-Components are styled through two complementary layers:
+`appearance` is the one styling API. Set it on `BunnyProvider` to restyle every component inside it, or on a component to restyle just that one: a component's `appearance` is merged over the provider's. `className` and `style` on a component position its root element (margins, width, a wrapper); they are not for changing how it looks.
 
-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.
-2. **Bunny CSS classes** — custom surfaces (e.g. PlanPicker, PlanFeatures, PriceListCard) expose stable class names you can target with plain CSS.
-
-#### Antd tokens
+**Requirements.** TypeScript 5 or newer to consume the package types: the public `.d.ts` references `gql.tada` types.
 
 ```tsx
-import { ConfigProvider } from 'antd';
-
-<ConfigProvider
-  theme={{
-    token: { colorPrimary: '#9B59B6', borderRadius: 16 },
-    components: {
-      Button: { defaultBorderColor: '#FF8C00' },
+import { BunnyProvider, Signup } from '@bunnyapp/components';
+
+<BunnyProvider
+  apiHost="https://your-subdomain.bunny.com"
+  token={token}
+  appearance={{
+    variables: {
+      colorPrimary: '#14532d',
+      colorBackgroundSecondary: '#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' },
+    },
+    fonts: [{ cssSrc: 'https://fonts.googleapis.com/css2?family=Source+Serif+4:wght@400;600&display=swap' }],
   }}
 >
-  <Upgrade ... />
-</ConfigProvider>
+  {/* Same look as everything else, except this button. */}
+  <Signup priceListCode="..." appearance={{ rules: { '.Button': { backgroundColor: '#1c1917', padding: '14px 16px' } } }} />
+</BunnyProvider>
 ```
 
-#### Bunny CSS classes
+**How it resolves.** Each component starts from defaults built from your Bunny branding (the brand color is the default `colorPrimary`). The provider's `appearance` is applied over that, then the component's own. `variables` are spread, so a later one wins. `rules` are merged per selector and then per property: a component that sets `'.Button': { padding }` keeps the provider's `'.Button'` color. `fonts` are concatenated. An unset value (`undefined`, `null` or `''`) is ignored, so it never replaces a set one. `variables` feed the default rules, and your `rules` are applied after every default. The TypeScript types are the contract: a key they do not allow, or a value containing `{`, `}`, `;`, `<`, `@import` or `url(`, is ignored, with a console warning in development.
 
-No special API — just target the class with plain CSS. Defaults live in `src/styles/*-tokens.less`.
+**Which rule wins.** A rule wins over every other rule at the same or lower specificity, and every rule, yours or ours, counts only its role and its state: `.Button`, `'.Summary .Button'` and our own restyled buttons weigh the same, and yours come later, so yours win. A state is a separate key: our `.Button:hover` beats your `.Button`, so when you restyle the button, set `.Button:hover` too. A scoped key beats your plain one (`'.Summary .Button'` over `.Button`), but not a state. A role drawn on top of `.Text` also counts `.Text`: `.Heading` beats `.Text`, whichever you wrote first.
 
-```css
-.bunny-feature-group {
-  background-color: #00E5FF;
-  border-radius: 24px;
-}
+**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 hex or `rgb()` color for `colorPrimary`, `colorSuccess` and `colorText`, as shades are computed from them (a color name reads as black there).
 
-.bunny-price-list-card-price-description {
-  color: #E91E63;
-  font-weight: 700;
-}
-```
+**What you can style.** The types, exported from the package as `Appearance`, `AppearanceVariables` and `AppearanceRules`, 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`. Selectors come in two kinds:
+
+- **Roles** are kinds of element that appear across components, such as `.Text`, `.Heading`, `.Button`, `.Card` or `.TableRow`. `.Input`, `.Label`, `.Error` and `.Tab` are shared with the payment fields and take only the properties those accept; the others, Bunny-only, also take `background`, `opacity` and `fontVariantNumeric`. Most variants of a role (a heading's level, a tag's state colour) have no selector of their own: a rule for the role reaches every variant. The compact controls are the exception (`--compact`, below). `.Text` is all text: muted text, headings, amounts and overlines are each a `.Text` with their own role on top, so a `.Text` rule reaches them all, but a rule for their own role (ours included, such as a heading's size) beats it.
+- **Regions** are the root of each component (`.Invoice`, `.Quote`, `.Upgrade`, and `.Invoices`, `.Quotes` and `.Transactions` for the lists) and the areas several screens share: `.Summary` and `.Form` in Signup and Checkout, and the panels of drawers and modals (`.Drawer`, `.Modal`). A region is styleable itself. An area inside one screen (Upgrade's plans, its feature comparison) is not a region: reach the roles in it through the component's root.
+
+To style a role inside one region only, write the region, a space and the role: `'.Summary .Button': { backgroundColor: '#1c1917' }` restyles the button in the summary; `'.Invoices .Heading'` restyles only the invoices list's title, and `'.Upgrade .Heading'` the plan names. This works for Bunny-only roles and their states (`'.Summary .Button:hover'`); shared roles cannot be scoped, so the payment fields always match your own. These scoped keys have no hover documentation of their own in your editor: read the role's and the region's. Scoped keys are never sent to the payment fields.
+
+A state is a suffix on the selector: `--invalid` is a field that failed validation, `--selected` the one chosen of several (a payment method, a plan's card, a billing period), `--checked` a control switched on or ticked (a switch, a checkbox), `--alternate` every other table row, `--display` the one large amount of a screen, `--compact` the 32px variant of `.Input`, `.Button` and `.ButtonSecondary` (Bunny's own, never sent to the payment fields), and the others are CSS pseudo-classes (`:hover`, `:focus`, `:disabled`, `::placeholder`). A state rule only needs the properties that change. A selector that a component does not draw is ignored there, so one `appearance` on `BunnyProvider` can hold rules for every component.
+
+**Text on the primary color.** Text and icons on `colorPrimary` surfaces (the primary button's label, a ticked checkbox, the plan picker's ticks) take `variables.colorOnPrimary`, white by default; it does not follow `colorPrimary`. With a light `colorPrimary`, set `colorOnPrimary` to a dark color so they stay readable.
+
+**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). Controls have a 1px border until `borderWidth` is set, and their padding gives up whatever the border takes, so the height stays. 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. The compact 32px inputs and buttons (a list's search box, the billing details' form, the quote's toolbar) keep their size under those rules: resize them with `.Input--compact`, `.Button--compact` and `.ButtonSecondary--compact`. `.Summary` and `.Form` are capped at `36rem` with `4rem` of padding (`1.5rem` on phones): change the padding with `padding`. Layout (widths, gaps) is not part of `appearance`: `maxWidth` and `minHeight` still work but are deprecated.
+
+**Fonts.** Set the font once, on `BunnyProvider`: `variables.fontFamily` is the font stack, and any web font in it goes in `fonts` (a stylesheet of `@font-face` rules, `{ cssSrc: 'https://...' }`, or a single file, `{ family, src, weight }`). The components load those fonts onto the page and into the payment fields (which render in an iframe), so your page needn't load them itself. The font reaches every component and the content you render inside `BunnyProvider`. System fonts need no entry. Leave `fontFamily` unset to inherit your page's font. 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 designs
+
+There is no dark mode switch. A dark look is a full set of variables: background, secondary background, text, secondary text, placeholder, border, and the primary and status colors, usually with a few rules for filled inputs. Setting only a dark `colorBackground` leaves text, borders and everything else you did not set on the light defaults. The `Midnight` stories (see [Appearance theme stories](#appearance-theme-stories)) are a complete example.
+
+#### Payment fields
+
+On Signup, Checkout and PaymentForm, the shared rules (`.Input` and its states, `.Label`, `.Error`, `.Tab` and its states) and the variables Stripe has too are handed to Stripe's Payment Element, so it is drawn like the form's own fields. The payment method tiles (saved payment methods, "New card" and, with more than one payment plugin, the plugins) are `.Tab`s too, so Stripe's tabs and ours match.
+
+#### Which components take `appearance`
 
-Currently exposed for the Upgrade component:
+Every component takes it except PaymentForm, which follows the appearance of the provider, or of the component it sits in (Invoice, Quote, BillingDetails), and the deprecated MiniCreditCard, which keeps its old look.
 
-- `.bunny-feature-group` — feature-list group surface
-- `.bunny-plan-features-feature-title-group` — group title text
-- `.bunny-plan-picker-grid-cell-divider` — divider between plan columns
-- `.bunny-plan-picker-price-list-cards` — price-list cards surface
-- `.bunny-plan-picker-checkout-bar` — checkout bar surface
-- `.bunny-price-list-card-price-description` — price description text
+#### What antd still draws
 
-For a live example combining both layers, see the `PrideTheme` story in `Upgrade.stories.tsx`.
+Modals and drawers are Ant Design overlays whose panels are the `.Modal` and `.Drawer` regions, so `rules` reach them and the roles inside them (`'.Modal .Button'`). Their title is always a `.Text`; a rule for the title alone is not supported yet (`'.Modal .Text'` also reaches the content's text). The small confirmation bubble (cancelling a subscription) has no selector of its own, but its text and buttons are `.Text`, `.Button` and `.ButtonSecondary`, so those rules reach it. Tooltips, dropdowns and notifications are still Ant Design components with no selectors: they follow `appearance.variables` only (colors, font, radius) through a theme we derive from them, and `rules` do not reach them. `BunnyProvider`'s `configProviderProps` has been removed: set `appearance.variables` instead. A `ConfigProvider` of your own nested inside `BunnyProvider` no longer affects anything we draw.
+
+#### Content Security Policy
+
+Every `BunnyProvider` and every component given an `appearance` injects a `<style>` element, so your Content Security Policy must allow inline styles (`style-src 'unsafe-inline'`); a nonce strategy is not supported. Fonts listed in `fonts` also need their host allowed: `style-src` for a stylesheet (`cssSrc`) and `font-src` for the font files it (or a `src`) loads.
+
+#### Migrating
+
+| Before | Now |
+| --- | --- |
+| `<BunnyProvider darkMode>` | `appearance.variables` with a full dark set, such as the `Midnight` story's |
+| `configProviderProps` (removed) | `appearance.variables` (`colorPrimary`, `borderRadius`, `fontFamily`, ...) |
+| A `ConfigProvider` nested inside `BunnyProvider` | `appearance.variables` on the provider |
+| `--bunny-signup-bg`, `--bunny-checkout-bg` | `variables.colorBackgroundSecondary` |
+| `colorBackgroundSummary` | `variables.colorBackgroundSecondary` |
+| `[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"]` | `variables.colorBackgroundSecondary` for the background; `className`/`style` only to position or size the root |
+| `shadow` (Invoice) | `rules['.Document'].boxShadow` (or `'.Invoice .Document'` for the invoice alone) |
+| `shadow` (Quote) | `rules['.Document'].boxShadow` (or `'.Quote .Document'` for the quote alone) |
+| `[data-slot="billing-details-root"]`, `.bunny-billing-details`, `--bunny-billing-details-*` | the `.BillingDetails` rule (`backgroundColor`, `borderRadius`, `boxShadow`) |
+| `displayOptions.shadow` (Invoices, Quotes, Transactions) | `rules['.Table'].boxShadow` |
+| `--row-background`, `--row-background-alternate` | `.Table` (background) and `.TableRow--alternate` |
+| `.InvoiceDocument` | `.Document` |
+| `.ResourceTable` | `.Invoices`, `.Quotes`, `.Transactions` |
+| `.TableTitle` | `'.Invoices .Heading'` (and `.Quotes`, `.Transactions`) |
+| `.Subheading` | `.Heading` (scope it to a region to change one place) |
+| `styles.gap` (Subscriptions) | `'.Subscriptions .Card': { marginBottom }` (added to the cards' spacing) |
+| `styles.shadow` (Subscriptions) | `rules['.Subscriptions .Card'].boxShadow` |
+| `styles.subscriptionProductNameStyle` (Subscriptions) | `'.Subscriptions .Heading'` |
+| `shadow` (Upgrade) | `rules['.Upgrade .Card'].boxShadow` |
+| `.bunny-plan-picker-price-list-cards` | `'.Upgrade .Card'` |
+| `.bunny-price-list-card-price-description` | `'.Upgrade .TextSecondary'` |
+| `.bunny-plan-picker-grid-cell-divider` | `variables.colorBorder` (the dividers take it) |
+| `.bunny-feature-group` | `'.Upgrade .Card'` |
+| `.bunny-plan-features-feature-title-group` | `'.Upgrade .Overline'` |
+| `.bunny-plan-picker-checkout-bar` | `'.Upgrade .Card'` |
+| `'.Button': { color }` for a light `colorPrimary` | `variables.colorOnPrimary` |
+| The `AppearanceBlockStyle`, `AppearanceRuleStyle` and `RuleProperty` types | still exported, deprecated: use `AppearanceStyle` (Bunny-only selectors) and `AppearanceSharedStyle` (shared ones); `AppearanceFont` is no longer deprecated |
+
+Props that changed outside styling:
+
+| Before | Now |
+| --- | --- |
+| `<Signup defaultFormValues={...}>` | `<Signup form={{ defaultValues: ... }}>` |
+| `<Signup requiredBillingDetails={...}>` | `<Signup form={{ requiredBillingDetails: ... }}>` |
+| `<Signup paymentRequiredToAcceptQuote>` | removed |
+| `<Signup documentTemplateId>` | removed from Signup (`Checkout` keeps `documentTemplateId`) |
+| `onInvoiceLoaded` (Invoice) received an untyped invoice | it receives the exported `FormattedInvoice` type |
+| `styles` (Subscriptions) | removed: see the `styles.*` rows above |
+
+The other Signup and Checkout slots (summary header, receipt, footer, success panel) have no selector of their own: their text, dividers and buttons are roles (`'.Summary .Divider'`, `'.Form .TextSecondary'`), and the quote PDF's frame is `'.Summary .Document'`.
+
+Two complete themes built only with `appearance` are in Storybook: see [Appearance theme stories](#appearance-theme-stories).
 
 ### Deprecating @bunnyapp/common
 
@@ -220,7 +290,98 @@ 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`:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import BunnyProvider from '../BunnyProvider/BunnyProvider';
+import { midnightStory } from '@/ui/appearance/stories/themes';
+import Signup from './Signup';
+
+const meta: Meta<typeof Signup> = {
+  component: Signup,
+  decorators: [
+    Story => (
+      <BunnyProvider apiHost="https://your-subdomain.bunny.com" token="your-token-here">
+        <Story />
+      </BunnyProvider>
+    ),
+  ],
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { priceListCode: 'your-price-list-code-here' },
+};
+
+// A dark design is a variable set: `midnightStory` passes the Midnight theme as `appearance`,
+// plus its page font and a dark canvas.
+export const Midnight: Story = {
+  ...midnightStory,
+  args: { ...Default.args, ...midnightStory.args },
+};
+
+// 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 stories share the value as `mobileGlobals` from `src/ui/appearance/stories/themes.ts`.
+
+The `autodocs` tag generates a docs page for the component from its props and stories.
+
+#### Appearance theme stories
+
+Every component that takes `appearance` has `Ledger` and `Midnight` stories (Footer, Invoice, Quote, BillingDetails, Invoices, Quotes, Transactions, Signup and Checkout so far). There are no theme-plus-mobile variants: the plain `Mobile` story shows the phone layout. The two themes are defined once in `src/ui/appearance/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 `src/ui/appearance/`, open both, with a Stripe key set, and confirm that Bunny's fields and Stripe's fields still match. Every one of these stories also exposes `appearance` as an editable control in the Controls panel.
 
 #### Visual tests