@metrifox/react-sdk 0.0.20-beta.4 → 0.0.20-beta.6

package/README.md

@@ -4,6 +4,21 @@ A fully-configurable **React SDK** providing ready-to-use widgets for SaaS and b
 
 ---
 
+## ⚠️ Version notice – breaking changes
+
+**If you are upgrading from an earlier version of the SDK, please read this.**
+
+This release introduces a **new theme structure** for both **Customer Portal** and **Pricing Table**. The theme API has been reorganized and is **not backward compatible** with previous versions.
+
+- **Theme is now a single object** passed via `metrifoxInit({ theme })` with two keys: `customerPortal` and `pricingTable`. The previous top-level `pricingTableTheme` option is **deprecated**; use `theme.pricingTable` instead.
+- **Customer Portal theme** uses a new grouped shape: `general`, `tabs`, `sections`, `buttons`, `lineItems`, `tables`, `modals`, and `plans`. Property names and nesting have changed from older versions.
+- **Pricing Table theme** now strictly follows the same nested structure as Customer Portal: all plan-related keys must be under `plans` (e.g. `plans.planCards`, `plans.planToggle`). Top-level plan keys are no longer supported.
+- **Both widgets** accept an optional `theme` prop per instance to override or extend the global theme from `metrifoxInit`.
+
+If you were using custom themes before, you will need to **migrate your theme objects** to the new structure. Omit any keys you don't need; the SDK merges your values with defaults. See the [Styling](#styling) section below for the full theme shapes and examples.
+
+---
+
 ## Installation
 
 ```bash
@@ -59,12 +74,13 @@ export default function MyPortalPage() {
         { key: "plan", component: MyCustomPlan, props: { foo: "bar" } },
         { key: "billingHistory", hidden: true },
       ]}
+      theme={{ general: { linkColor: "#2563eb" } }}
     />
   )
 }
 ```
 
----
+Optional **`theme`** prop: pass a `CustomerPortalTheme` object to override or extend the global theme from `metrifoxInit` for this instance only.
 
 #### Section Configuration
 
@@ -115,7 +131,13 @@ Displays subscription plans and one-time purchases in a configurable pricing tab
 import { PricingTable } from "@metrifox/react-sdk"
 
 export default function PricingPage() {
-  return <PricingTable checkoutUsername="your-checkout-username" productKey="your-product-key" />
+  return (
+    <PricingTable
+      checkoutUsername="your-checkout-username"
+      productKey="your-product-key"
+      theme={{ plans: { planCards: { background: "#ffffff" } } }}
+    />
+  )
 }
 ```
 
@@ -125,19 +147,20 @@ export default function PricingPage() {
 
 The props control how the pricing table is configured.
 
-| Property              | Type      | Required | Default | Description                                                                      |
-| --------------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------- |
-| `checkoutUsername`    | `string`  | Yes      | —       | Unique username used for checkout. This can be found in **Settings → Checkout**. |
-| `productKey`          | `string`  | Yes      | —       | Unique product identifier. This can be found on the product page.                |
-| `plansOnly`           | `boolean` | No       | `false` | Controls whether only subscription plans are rendered.                           |
-| `singlePurchasesOnly` | `boolean` | No       | `false` | Controls whether only single purchases are rendered.                             |
-| `showTabHeader`       | `boolean` | No       | `true`  | Controls whether the tab header for switching between offerings is rendered.     |
+| Property              | Type               | Required | Default | Description                                                                      |
+| --------------------- | ------------------ | -------- | ------- | -------------------------------------------------------------------------------- |
+| `checkoutUsername`    | `string`           | Yes      | —       | Unique username used for checkout. This can be found in **Settings → Checkout**. |
+| `productKey`          | `string`           | Yes      | —       | Unique product identifier. This can be found on the product page.                |
+| `plansOnly`           | `boolean`          | No       | `false` | Controls whether only subscription plans are rendered.                           |
+| `singlePurchasesOnly` | `boolean`          | No       | `false` | Controls whether only single purchases are rendered.                             |
+| `showTabHeader`       | `boolean`          | No       | `true`  | Controls whether the tab header for switching between offerings is rendered.     |
+| `theme`               | `PricingTableTheme`| No       | —       | Optional theme override for this instance (merged with global theme from `metrifoxInit`). |
 
 > **Note:** If both `plansOnly` and `singlePurchasesOnly` are `false` or undefined, both plans and single purchases are displayed.
 
 ## Styling
 
-Import the SDK’s global styles into your app entry (e.g., `src/index.tsx` or `_app.tsx`):
+Import the SDK's global styles into your app entry (e.g., `src/index.tsx` or `_app.tsx`):
 
 ```tsx
 import "@metrifox/react-sdk/dist/styles.css"
@@ -145,274 +168,209 @@ import "@metrifox/react-sdk/dist/styles.css"
 
 > This is required for proper styling of all widgets.
 
-#### Widget Styling
-
-The SDK accepts an optional `theme` object during initialization. This theme is applied to Widgets and UI elements within them to match your brand styles.
+### Theme configuration (new structure)
 
-Any values not provided will fall back to the default theme.
+Theming is driven by a single `theme` object passed to `metrifoxInit`. It has two top-level keys: `customerPortal` and `pricingTable`. Any value you omit falls back to the SDK default. You can also pass an optional `theme` prop to `<CustomerPortal />` or `<PricingTable />` to override or extend the global theme for that instance.
 
 ```ts
+// Passed to metrifoxInit({ theme })
 theme?: {
   customerPortal?: CustomerPortalTheme
   pricingTable?: PricingTableTheme
 }
 ```
 
-```ts
-// Customer portal theme (CustomerPortalTheme). All properties are optional.
-customerPortal?: {
-  general?: {
-    linkColor?: string
-    backgroundColor?: string
-    borderRadius?: string
-    fontFamily?: string
-    containerPadding?: string
-  }
+> **Deprecated:** The previous root-level `pricingTableTheme` option is no longer supported. Use `theme.pricingTable` instead.
 
-  tabs?: {
-    tabBackground?: string
-    tabBorderColor?: string
-    activeTabBackground?: string
-    activeTabTextColor?: string
-    inactiveTabTextColor?: string
-  }
+---
 
-  sections?: {
-    background?: string
-    padding?: string
-    borderColor?: string
-    borderRadius?: string
-    emptyTextColor?: string
-    usage?: { barColor?: string; trackColor?: string }
-    content?: { background?: string; padding?: string; borderColor?: string; borderRadius?: string }
-    summary?: { background?: string; padding?: string; borderColor?: string; borderRadius?: string }
-    header?: { fontSize?: string; fontWeight?: string; color?: string }
-    label?: { fontSize?: string; fontWeight?: string; color?: string }
-    value?: { fontSize?: string; fontWeight?: string; color?: string }
-  }
+### Customer Portal theme (`CustomerPortalTheme`)
 
-  buttons?: {
-    primary?: {
-      backgroundColor?: string
-      border?: { color?: string; width?: string; radius?: string }
-      typography?: { fontSize?: string; fontWeight?: string; color?: string }
-    }
-    secondary?: {
-      backgroundColor?: string
-      border?: { color?: string; width?: string; radius?: string }
-      typography?: { fontSize?: string; fontWeight?: string; color?: string }
-    }
-  }
+All properties are optional. The shape is grouped by area of the UI:
 
-  lineItems?: {
-    parentRow?: {
-      background?: string
-      borderColor?: string
-      typography?: { label?: { color?: string }; quantity?: { color?: string } }
-    }
-    childRow?: {
-      background?: string
-      borderColor?: string
-      typography?: { label?: { color?: string }; quantity?: { color?: string } }
-    }
-  }
+| Group | Description |
+| ----- | ----------- |
+| `general` | Page-level: link color, background, border radius, font family, container padding |
+| `tabs` | Tab bar (e.g. Wallet balance tabs): background, border, active/inactive states |
+| `sections` | Section cards: background, padding, borders, content/summaryBalance sub-styles, header/label/value typography, usage bars, empty text |
+| `buttons` | Primary and secondary buttons: background, border (color/width/radius), typography |
+| `lineItems` | Subscription line items: parentRow/childRow background, border, typography (label/quantity) |
+| `tables` | Tables (e.g. billing history): header/row colors, border, cell padding, expand icon, typography |
+| `modals` | Modal overlay, background, border, close button; header/title/description typography; footer primary/secondary buttons |
+| `plans` | Plan cards when shown in portal: currentPlanCard, planCards (border as `{ color, width, radius }`), planFeatures, planButton, planToggle, planTags |
 
-  tables?: {
-    headerBackground?: string
-    headerTextColor?: string
-    rowBackgroundOdd?: string
-    rowBackgroundEven?: string
-    rowTextColor?: string
-    borderColor?: string
-    cellPadding?: string
-    expandIconColor?: string
-    typography?: {
-      fontSize?: string
-      fontWeight?: string
-      headerFontSize?: string
-      headerFontWeight?: string
-    }
-  }
+**Example – minimal override:**
 
-  modals?: {
-    overlayColor?: string
-    background?: string
-    borderColor?: string
-    borderRadius?: string
-    closeButtonColor?: string
-    header?: { fontSize?: string; fontWeight?: string; color?: string }
-    title?: { fontSize?: string; fontWeight?: string; color?: string }
-    description?: { fontSize?: string; fontWeight?: string; color?: string }
-    footer?: {
-      primary?: { backgroundColor?: string; textColor?: string }
-      secondary?: { backgroundColor?: string; textColor?: string; borderColor?: string; borderWidth?: string }
-    }
-  }
-
-  plans?: {
-    currentPlanCard?: {
-      header?: { background?: string; textColor?: string }
-      gradientColor?: string
-    }
-    planCards?: {
-      background?: string
-      borderColor?: string
-      descriptionColor?: string
-      header?: { background?: string; textColor?: string }
-      description?: { textColor?: string; textButtonColor?: string }
-      price?: {
-        amountColor?: string
-        primaryTextColor?: string
-        secondaryTextColor?: string
-        background?: string
-        borderColor?: string
-      }
-    }
-    planFeatures?: { textColor?: string; iconColor?: string }
-    planButton?: { background?: string; textColor?: string }
-    planToggle?: {
-      background?: string
-      activeBackground?: string
-      activeText?: string
-      inactiveText?: string
-    }
-    planTags?: { freeTrialBackground?: string; freeTrialText?: string }
-  }
+```ts
+customerPortal: {
+  general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
+  tabs: {
+    tabBackground: "#ffffff",
+    tabBorderColor: "#e5e7eb",
+    activeTabBackground: "#2563eb",
+    activeTabTextColor: "#ffffff",
+    inactiveTabTextColor: "#6b7280",
+  },
+  sections: {
+    background: "#ffffff",
+    content: { background: "#f4f4f5", borderRadius: "8px" },
+    header: { fontSize: "16px", fontWeight: "600", color: "#52525b" },
+    label: { fontSize: "13px", color: "#71717a" },
+    value: { fontSize: "16px", color: "#52525b" },
+  },
+  buttons: {
+    primary: { backgroundColor: "#2563eb", border: { radius: "8px" }, typography: { color: "#ffffff" } },
+    secondary: { backgroundColor: "#e4e4e7", typography: { color: "#3f3f46" } },
+  },
+  plans: {
+    planCards: {
+      background: "#ffffff",
+      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
+      header: { background: "#e5e7eb", textColor: "#111827" },
+      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
+      price: { amountColor: "#111827", primaryTextColor: "#6b7280", secondaryTextColor: "#9ca3af" },
+    },
+    planButton: { background: "#2563eb", textColor: "#ffffff" },
+    planToggle: { background: "#e5e7eb", activeBackground: "#1f2937", activeText: "#ffffff", inactiveText: "#6b7280" },
+  },
 }
 ```
 
-```ts
-// Pricing table theme configuration
-pricingTableTheme?: {
-  card?: {
-    background?: string
-    borderColor?: string
-    descriptionColor?: string
-
-    header?: {
-      background?: string
-      textColor?: string
-    }
+---
 
-    description?: {
-      textColor?: string
-      textButtonColor?: string
-    }
+### Font customization
 
-    price?: {
-      amountColor?: string
-      primaryTextColor?: string
-      secondaryTextColor?: string
-      textButtonColor?: string
-      background?: string
-      borderColor?: string
-    }
-  }
+The SDK accepts **any font-family string** in your theme. The SDK applies it via CSS, but **your app must load the font** (Google Fonts, @font-face, etc.) before the SDK renders.
 
-  button?: {
-    background?: string
-    textColor?: string
-    secondaryBackground?: string
-    secondaryTextColor?: string
-    textButtonColor?: string
-  }
+**How it works:**
 
-  featureList?: {
-    textColor?: string
-    iconColor?: string
-  }
+1. **Load the font in your app** (HTML, CSS, or framework-specific):
 
-  tabs?: {
-    inactiveText?: string
-    activeText?: string
-    indicator?: string
-    borderColor?: string
-  }
+```html
+<!-- Option A: Google Fonts in your HTML <head> -->
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600&display=swap" rel="stylesheet">
+```
 
-  intervalToggle?: {
-    background?: string
-    activeBackground?: string
-    activeText?: string
-    inactiveText?: string
-  }
+```css
+/* Option B: @font-face in your global CSS */
+@font-face {
+  font-family: 'MyCustomFont';
+  src: url('/fonts/custom.woff2') format('woff2');
+}
+```
+
+2. **Pass the font-family to the SDK theme:**
 
-  currentSubscriptionCard?: {
-    header?: {
-      background?: string
-      textColor?: string
+```tsx
+metrifoxInit({
+  theme: {
+    customerPortal: {
+      general: { 
+        // Any font-family string works
+        fontFamily: '"Space Grotesk", "Inter", sans-serif'
+        // or: 'MyCustomFont, sans-serif'
+        // or: 'system-ui, -apple-system, sans-serif'
+      }
     }
-    gradientColor?: string
   }
+})
+```
 
-  freeTrialTag?: {
-    background?: string
-    textColor?: string
-  }
+If no `fontFamily` is provided, the SDK inherits the font from the host page. This means the SDK works with whatever font your app already uses — no extra configuration needed.
 
-  checkoutBar?: {
-    background?: string
-    borderColor?: string
-    textColor?: string
-    buttonBackground?: string
-    buttonTextColor?: string
-  }
-}
-```
+> **Important:** When using Google Fonts or custom fonts, load them in your app **before** the SDK initializes to prevent flash of unstyled text (FOUT).
 
-###### Example usage
+---
 
-```tsx
-import { metrifoxInit } from "@metrifox/react-sdk"
+### Pricing Table theme (`PricingTableTheme`)
 
-const pricingTableTheme = {
-  pricingTable: {
-    card: {
+The Pricing Table theme follows the same nested structure as Customer Portal. All plan-related keys must be nested under `plans`.
+
+| Key | Description |
+| --- | ----------- |
+| `plans` | Container for all plan-related styling |
+| `plans.currentPlanCard` | Current-plan highlight: header (background, textColor), gradientColor, description, borderRadius |
+| `plans.planCards` | Card style: background, border (`{ color, width, radius }`), header, description (textColor, textButtonColor), price (amountColor, primaryTextColor, secondaryTextColor, textButtonColor, background, borderColor) |
+| `plans.planFeatures` | Feature list: textColor, iconColor |
+| `plans.planButton` | CTA button: background, textColor; optional secondaryBackground, secondaryTextColor, textButtonColor |
+| `plans.planToggle` | Monthly/Yearly toggle: background, activeBackground, activeText, inactiveText |
+| `plans.planTags` | Tags (e.g. free trial): freeTrialBackground, freeTrialText |
+| `tabs` | Tabs (e.g. Plans vs Single purchases): inactiveText, activeText, indicator, borderColor |
+| `checkoutBar` | Bottom checkout bar: background, borderColor, textColor, buttonBackground, buttonTextColor |
+
+**Example – minimal override:**
+
+```ts
+pricingTable: {
+  plans: {
+    planCards: {
       background: "#ffffff",
-      price: {
-        amountColor: "#111827",
-        textButtonColor: "#2563eb",
-      },
-    },
-    button: {
-      background: "#2563eb",
-    },
-    tabs: {
-      activeText: "#2563eb",
+      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
+      header: { background: "#e5e7eb", textColor: "#111827" },
+      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
+      price: { amountColor: "#111827", primaryTextColor: "#6b7280", secondaryTextColor: "#9ca3af" },
     },
+    planButton: { background: "#2563eb", textColor: "#ffffff" },
+    planToggle: { background: "#e5e7eb", activeBackground: "#1f2937", activeText: "#ffffff", inactiveText: "#6b7280" },
+  },
+  tabs: { activeText: "#2563eb", indicator: "#2563eb", borderColor: "#9ca3af" },
+  checkoutBar: {
+    background: "#f9fafb",
+    borderColor: "#e5e7eb",
+    textColor: "#3f3f46",
+    buttonBackground: "#2563eb",
+    buttonTextColor: "#ffffff",
   },
 }
+```
 
-const customerPortalTheme = {
-  tabs: {
-    background: "#111827",
-    borderColor: "#243044",
-  },
+When the Pricing Table is embedded inside the Customer Portal, it automatically uses `theme.customerPortal.plans` for plan styling so both widgets stay consistent.
 
-  section: {
-    background: "#020617",
-  },
+---
 
-  card: {
-    titleColor: "#F9FAFB",
-    details: {
-      labelColor: "#CBD5E1",
-      valueColor: "#FFFFFF",
-    },
-  },
-}
+### Full example
 
-const theme = {
-  customerPortal: customerPortalTheme,
-  pricingTableTheme: pricingTableTheme,
-}
+```tsx
+import { metrifoxInit } from "@metrifox/react-sdk"
 
 metrifoxInit({
   clientKey: "your-client-key",
-  theme,
-  pricingTableTheme, // deprecated - Moved to `theme.pricingTable`
+  theme: {
+    customerPortal: {
+      general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
+      tabs: {
+        tabBackground: "#ffffff",
+        activeTabBackground: "#2563eb",
+        activeTabTextColor: "#ffffff",
+        inactiveTabTextColor: "#6b7280",
+      },
+      sections: {
+        background: "#ffffff",
+        content: { background: "#f4f4f5", borderRadius: "8px" },
+      },
+      buttons: {
+        primary: { backgroundColor: "#2563eb", typography: { color: "#ffffff" } },
+      },
+    },
+    pricingTable: {
+      plans: {
+        planCards: { background: "#ffffff", border: { color: "#e5e7eb", radius: "8px" } },
+        planButton: { background: "#2563eb", textColor: "#ffffff" },
+      },
+      tabs: { activeText: "#2563eb", indicator: "#2563eb" },
+      checkoutBar: { buttonBackground: "#2563eb", buttonTextColor: "#ffffff" },
+    },
+  },
 })
 ```
 
+Per-widget overrides (optional):
+
+```tsx
+<CustomerPortal customerKey="..." theme={{ general: { linkColor: "#1d4ed8" } }} />
+<PricingTable checkoutUsername="..." productKey="..." theme={{ plans: { planCards: { background: "#f8fafc" } } }} />
+```
+
 ---
 
 ## Local Development