@bunnyapp/components 1.8.6 → 2.0.0-beta.2

package/README.md

@@ -24,7 +24,101 @@ pnpm add @bunnyapp/components
 bun add @bunnyapp/components
 ```
 
-Ensure all peer dependencies in the package.json are installed.
+Ensure all peer dependencies in the package.json are installed. React and react-dom must be `^18.3.1` (React 19 is not supported) and `antd` `^5`.
+
+Until 2.0.0 is released, install the prerelease with `npm i @bunnyapp/components@beta` (2.0.0-beta.N).
+
+## Components
+
+`Checkout` (an existing account subscribes to a price list), `Signup` (a new customer creates an account and subscribes), `Subscriptions`, `Upgrade`, `BillingDetails`, `Invoice`, `Invoices`, `Quote`, `Quotes`, `Transactions` and `Footer`, all inside one `BunnyProvider`. Usage, props and tokens are documented at [docs.bunny.com](https://docs.bunny.com/developer/bunny-components/bunny-components).
+
+## Styling components
+
+`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.
+
+```tsx
+import { BunnyProvider, Checkout, 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' }],
+  }}
+>
+  {/* Same look as everything else, except this button. */}
+  <Checkout priceListCode="..." appearance={{ rules: { '.Button': { backgroundColor: '#1c1917', padding: '14px 16px' } } }} />
+</BunnyProvider>
+```
+
+**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. Later `variables` win, `rules` merge per selector and then per property (a component that sets `'.Button': { padding }` keeps the provider's `'.Button'` color), and `fonts` are concatenated. Your `rules` are applied after every default, so they win. 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.
+
+**States.** A state is a separate key: our `.Button:hover` beats your plain `.Button`, so when you restyle a button, set `.Button:hover` too. A scoped key (`'.Summary .Button'`) beats your plain one, but not a state.
+
+**Use literal values.** Write real CSS values (`#14532d`, `12px`, `"Space Grotesk", sans-serif`), never `var(--my-token)`: the payment fields render in an 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).
+
+**What you can style.** The exported types `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. Type `appearance={{` in your editor and use autocomplete and hover.
+
+Selectors are **roles**, kinds of element that appear across components (`.Text`, `.Heading`, `.Button`, `.Card`, `.TableRow`, ...), and **regions**, the root of each component (`.Invoice`, `.Quote`, `.Upgrade`, `.Invoices`, ...) and shared areas (`.Summary` and `.Form` in Signup and Checkout, `.Drawer`, `.Modal`). `.Input`, `.Label`, `.Error` and `.Tab` also style the payment fields and take only the properties those accept. A rule for a role reaches all its variants, and `.Text` reaches all text, including headings, which can be styled further with `.Heading`.
+
+To style a role inside one region, write the region, a space and the role: `'.Summary .Button'`, `'.Invoices .Heading'`. This works for every role except the shared payment-field ones (`.Input`, `.Label`, `.Error`, `.Tab`). A selector that a component does not draw is ignored, so one `appearance` on `BunnyProvider` can hold rules for every component.
+
+A state is a suffix on the selector: `--invalid`, `--selected` (a payment method, a plan, a billing period), `--checked` (a switch or checkbox), `--alternate` (every other table row), `--display` (the one large amount of a screen), `--compact` (the 32px `.Input`, `.Button` and `.ButtonSecondary`), or a CSS pseudo-class (`:hover`, `:focus`, `:disabled`, `::placeholder`). A state rule only needs the properties that change.
+
+**Text on the primary color.** Text and icons on `colorPrimary` surfaces (the primary button's label, a ticked checkbox) take `variables.colorOnPrimary`, white by default; it does not follow `colorPrimary`. With a light `colorPrimary`, set `colorOnPrimary` to a dark color.
+
+**Sizing.** There is no `height` property. An input's height is its vertical padding + `lineHeight` + borders, which is also how the payment fields are sized. 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. Resize the compact controls with `.Input--compact`, `.Button--compact` and `.ButtonSecondary--compact`. Layout (widths, gaps) is not part of `appearance`.
+
+**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, so your page needn't load them itself. System fonts need no entry; leave `fontFamily` unset to inherit your page's font. Set `fonts` once, up front: changing them after the payment form has mounted remounts the payment fields and clears anything typed into them.
+
+### Dark designs
+
+To build a dark look, set the full set of color 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 everything else on the light defaults.
+
+### Payment fields
+
+On Signup and Checkout, your `.Input`, `.Label`, `.Error` and `.Tab` rules and the color and font variables also style the card fields, so they match the rest of the form.
+
+### Tooltips, dropdowns and notifications
+
+These follow `appearance.variables` (colors, font, radius) only; `rules` do not reach them. Modals and drawers are the `.Modal` and `.Drawer` regions, so `rules` reach them and the roles inside them (`'.Modal .Button'`).
+
+### 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.
+
+## Using with an AI assistant
+
+The package ships a `bunny-components` skill (install, tokens, Checkout and Signup, and the styling recipes above), version-matched to the installed package:
+
+```sh
+npx skills add ./node_modules/@bunnyapp/components   # Claude Code, Cursor, Codex, Copilot, Gemini...
+```
+
+## Migrating to 2.0
+
+| Before | Now |
+| --- | --- |
+| `<BunnyProvider darkMode>` | `appearance.variables` with a full dark set (see [Dark designs](#dark-designs)) |
+| `configProviderProps` | `appearance.variables` (`colorPrimary`, `borderRadius`, `fontFamily`, ...) |
+| A `ConfigProvider` nested inside `BunnyProvider` | `appearance.variables` on the provider |
+| `[data-slot="..."]`, `.bunny-*`, `--bunny-*` and other internal class selectors | gone: use `rules` with the role and region selectors above |
+| `shadow` (Invoice, Quote, Upgrade), `displayOptions.shadow` (Invoices, Quotes, Transactions), `styles` (Subscriptions) | `rules`, e.g. `rules['.Document'].boxShadow`, `rules['.Table'].boxShadow`, `rules['.Subscriptions .Card'].boxShadow` |
+| `'.Button': { color }` for a light `colorPrimary` | `variables.colorOnPrimary` |
+| `<Signup defaultFormValues={...}>` | `<Signup form={{ defaultValues: ... }}>` |
+| `<Signup requiredBillingDetails={...}>` | `<Signup form={{ requiredBillingDetails: ... }}>` |
+| `<Signup paymentRequiredToAcceptQuote>`, `<Signup documentTemplateId>` | removed (`Checkout` keeps `documentTemplateId`) |
+| `onInvoiceLoaded` (Invoice) received an untyped invoice | it receives the exported `FormattedInvoice` type |
 
 ## Development
 
@@ -146,81 +240,121 @@ setFruitQueryData('123', { id: '123', name: 'Apple' });
 
 For a more complete example in the codebase, see the `useSetQuoteQueryData` hook in the `quantityChangeDrawer` module.
 
-### Styling components
+### Deprecating @bunnyapp/common
 
-Components are styled through two complementary layers:
+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:
 
-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.
+1. **Create local definitions**:
 
-#### Antd tokens
+   - **Enums** → Create in `src/enums/` directory (e.g., `src/enums/SubscriptionState.ts`)
+   - **Types** → Create in `src/types/` directory (e.g., `src/types/billingDetails.ts`)
 
-```tsx
-import { ConfigProvider } from 'antd';
+2. **Update imports incrementally**: Only update the files that need the change. Other files can continue importing from `@bunnyapp/common` until they need to be updated.
 
-<ConfigProvider
-  theme={{
-    token: { colorPrimary: '#9B59B6', borderRadius: 16 },
-    components: {
-      Button: { defaultBorderColor: '#FF8C00' },
-    },
-  }}
->
-  <Upgrade ... />
-</ConfigProvider>
+3. **Example pattern**:
+
+   ```typescript
+   // Before (from @bunnyapp/common)
+   import { SubscriptionState } from '@bunnyapp/common';
+
+   // After (local enum)
+   import SubscriptionState from '../enums/SubscriptionState';
+   ```
+
+### Storybook stories
+
+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
 ```
 
-#### Bunny CSS classes
+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.
 
-No special API — just target the class with plain CSS. Defaults live in `src/styles/*-tokens.less`.
+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).
 
-```css
-.bunny-feature-group {
-  background-color: #00E5FF;
-  border-radius: 24px;
-}
+#### Stripe in stories
 
-.bunny-price-list-card-price-description {
-  color: #E91E63;
-  font-weight: 700;
-}
+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_...
 ```
 
-Currently exposed for the Upgrade component:
+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.
 
-- `.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
+#### Writing a story
 
-For a live example combining both layers, see the `PrideTheme` story in `Upgrade.stories.tsx`.
+Components need a `BunnyProvider` around them. Add it as a decorator in the file's `meta`:
 
-### Deprecating @bunnyapp/common
+```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'],
+};
 
-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:
+export default meta;
 
-1. **Create local definitions**:
+type Story = StoryObj<typeof meta>;
 
-   - **Enums** → Create in `src/enums/` directory (e.g., `src/enums/SubscriptionState.ts`)
-   - **Types** → Create in `src/types/` directory (e.g., `src/types/billingDetails.ts`)
+export const Default: Story = {
+  args: { priceListCode: 'your-price-list-code-here' },
+};
 
-2. **Update imports incrementally**: Only update the files that need the change. Other files can continue importing from `@bunnyapp/common` until they need to be updated.
+// 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 },
+};
 
-3. **Example pattern**:
+// Phone layout: renders the story in a 320px wide iframe.
+export const Mobile: Story = {
+  args: { ...Default.args },
+  globals: { viewport: { value: 'mobile1', isRotated: false } },
+};
+```
 
-   ```typescript
-   // Before (from @bunnyapp/common)
-   import { SubscriptionState } from '@bunnyapp/common';
+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`.
 
-   // After (local enum)
-   import SubscriptionState from '../enums/SubscriptionState';
-   ```
+The `autodocs` tag generates a docs page for the component from its props and stories.
 
-### Storybook stories
+#### Appearance theme stories
 
-To view the storybook stories, run `npx storybook dev`.
+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