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

package/README.md

@@ -148,115 +148,122 @@ 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).
+`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.
 
-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.
-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';
+import { BunnyProvider, Signup } from '@bunnyapp/components';
 
-<ConfigProvider
-  theme={{
-    token: { colorPrimary: '#9B59B6', borderRadius: 16 },
-    components: {
-      Button: { defaultBorderColor: '#FF8C00' },
+<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:
 
-Currently exposed for the Upgrade component:
+- **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.
 
-- `.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
+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.
 
-For a live example combining both layers, see the `PrideTheme` story in `Upgrade.stories.tsx`.
+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.
 
-#### Styling Signup and Checkout
+**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.
 
-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).
+**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.
 
-```tsx
-import { BunnyProvider, Signup } from '@bunnyapp/components';
+**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.
 
-<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>
-```
+#### Dark designs
 
-`<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.
+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.
 
-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.
+#### Payment fields
 
-**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.
+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.
 
-**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`.
+#### Which components take `appearance`
 
-**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.
+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.
 
-**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.
+#### What antd still draws
 
-**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`.
+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.
 
-**Not covered yet.**
+#### Content Security Policy
 
-- 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.
+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 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:
+#### Migrating
 
 | Before | Now |
 | --- | --- |
-| `--bunny-signup-bg`, `--bunny-checkout-bg` | `variables.colorBackgroundSummary` |
+| `<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"]` | the component's `style` prop |
+| `[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:
 
-The other slots (summary header, receipt, quote document, footer, success panel) have no replacement selector; their colors, borders and fonts follow the variables.
+| 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).
 
@@ -326,19 +333,19 @@ Restart Storybook after changing it. Without the key, stories that take a paymen
 
 #### 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:
+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 { DarkModeParams } from '../../storybook-utils';
+import { midnightStory } from '@/ui/appearance/stories/themes';
 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 apiHost="https://your-subdomain.bunny.com" token="your-token-here">
         <Story />
       </BunnyProvider>
     ),
@@ -354,10 +361,11 @@ 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 },
+// 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.
@@ -367,13 +375,13 @@ export const Mobile: Story = {
 };
 ```
 
-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`.
+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
 
-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.
+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