@metrifox/react-sdk 0.0.6 → 0.0.8

package/README.md

@@ -105,6 +105,174 @@ Use these anchors when embedding the SDK or sharing deep links (e.g., `https://a
 
 ---
 
+## Core Widget: `PriceCard`
+
+Display individual pricing plan cards with detailed pricing information, entitlements, and call-to-action buttons. Ideal for pricing pages, plan comparison views, or standalone plan displays.
+
+```tsx
+import { PriceCard } from "@metrifox/react-sdk"
+
+export default function PricingPage() {
+  const plan = {
+    id: "plan-123",
+    name: "Professional Plan",
+    description: "Perfect for growing teams",
+    is_visible: true,
+    is_free: false,
+    is_custom: false,
+    is_current_plan: false,
+    price_options: [
+      {
+        id: "price-1",
+        amount: 2900, // $29.00 in cents
+        currency: "USD",
+        interval: "monthly",
+      },
+    ],
+    entitlements: [
+      {
+        id: "ent-1",
+        feature_id: "users",
+        feature_key: "users",
+        feature_name: "Team Members",
+        limit_value: 10,
+        is_visible: true,
+      },
+    ],
+    // ... other plan properties
+  }
+
+  const featureOrderMap = new Map([
+    ["users", 0],
+    ["storage", 1],
+  ])
+
+  return (
+    <PriceCard
+      plan={plan}
+      interval="monthly"
+      featureOrderMap={featureOrderMap}
+      buttonText="Start Free Trial"
+      buttonAction={() => window.open(plan.checkout_url, "_blank")}
+      isPricePage={true}
+    />
+  )
+}
+```
+
+### PriceCard Props
+
+| Property           | Type                  | Required | Description                                                  |
+| ------------------ | --------------------- | -------- | ------------------------------------------------------------ |
+| `plan`             | `Offering`            | ✅       | The plan/offering object containing pricing and feature data |
+| `interval`         | `string`              | ✅       | Billing interval to display (e.g., "monthly", "yearly")      |
+| `featureOrderMap`  | `Map<string, number>` | ✅       | Map defining the display order of features                   |
+| `isPricePage`      | `boolean`             | ❌       | Enable pricing page mode with enhanced styling               |
+| `isCustomerPortal` | `boolean`             | ❌       | Enable customer portal mode for subscription management      |
+| `buttonText`       | `string`              | ❌       | Custom text for the action button                            |
+| `buttonAction`     | `() => void`          | ❌       | Function called when action button is clicked                |
+| `isCurrentPlan`    | `boolean`             | ❌       | Highlight card as the customer's current plan                |
+| `statusTag`        | `React.ReactNode`     | ❌       | Custom status indicator (e.g., "Popular", "Recommended")     |
+| `addPriceButton`   | `React.ReactNode`     | ❌       | Additional custom button element                             |
+| `planActions`      | `React.ReactNode`     | ❌       | Custom actions area (e.g., edit, delete buttons)             |
+| `cardAction`       | `() => void`          | ❌       | Function called when the entire card is clicked              |
+
+### Plan Data Structure (Offering)
+
+The `plan` prop expects an object with the following structure:
+
+```tsx
+interface Offering {
+  id: string
+  name: string
+  description: string
+  is_visible: boolean
+  is_free: boolean
+  is_custom: boolean
+  is_current_plan: boolean
+  checkout_url?: string
+  custom_cta_text?: string
+  trial_duration_unit?: string
+  trial_duration_value?: number
+
+  // Pricing options for different intervals
+  price_options: PriceOption[]
+  entitlement_price_options: PriceOption[]
+  credit_attachment_price_options: PriceOption[]
+
+  // Features and entitlements
+  entitlements: Entitlement[]
+  credit_attachments?: CreditSystemProps[]
+  base_entitlements_plan_name?: string
+
+  // Metadata
+  version_id: string
+  status: string
+  // ... other properties
+}
+```
+
+### Usage Patterns
+
+#### Basic Pricing Page
+
+```tsx
+const plans = [
+  { /* Basic plan data */ },
+  { /* Pro plan data */ },
+  { /* Enterprise plan data */ }
+]
+
+const featureOrderMap = new Map([
+  ["users", 0],
+  ["storage", 1],
+  ["api_calls", 2]
+])
+
+return (
+  <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+    {plans.map(plan => (
+      <PriceCard
+        key={plan.id}
+        plan={plan}
+        interval={selectedInterval}
+        featureOrderMap={featureOrderMap}
+        isPricePage={true}
+        buttonAction={() => handlePlanSelection(plan)}
+      />
+    ))}
+  </div>
+)
+```
+
+#### Customer Portal Integration
+
+```tsx
+<PriceCard
+  plan={plan}
+  interval={selectedInterval}
+  featureOrderMap={featureOrderMap}
+  isCustomerPortal={true}
+  isCurrentPlan={plan.is_current_plan}
+  buttonText={plan.is_current_plan ? "Current Plan" : "Upgrade"}
+  buttonAction={() => handleUpgrade(plan.checkout_url)}
+/>
+```
+
+#### With Custom Status Tags
+
+```tsx
+<PriceCard
+  plan={plan}
+  interval="monthly"
+  featureOrderMap={featureOrderMap}
+  statusTag={<span className="bg-blue-500 text-white px-2 py-1 rounded text-xs">Most Popular</span>}
+  buttonAction={() => selectPlan(plan)}
+/>
+```
+
+---
+
 ## Styling
 
 Import the SDK’s global styles into your app entry (e.g., `src/index.tsx` or `_app.tsx`):