npm package: @heymantle/polaris-web-react
Description: Mantle's React components using Shopify Polaris Web Components
Author: Mantle
Latest version: 0.1.1

# @heymantle/polaris-web-react

React components for Shopify billing UIs using [Polaris Web Components](https://shopify.dev/docs/api/app-home/polaris-web-components).

## Installation

```bash
npm install @heymantle/polaris-web-react
```

## Setup

Wrap your app with `PolarisWebProvider` to automatically load the required CDN scripts:

```tsx
// _app.tsx or your app layout
import { PolarisWebProvider } from '@heymantle/polaris-web-react';

export default function App({ Component, pageProps }) {
  return (
    <PolarisWebProvider apiKey={process.env.NEXT_PUBLIC_SHOPIFY_API_KEY}>
      <Component {...pageProps} />
    </PolarisWebProvider>
  );
}
```

If you've already loaded the Polaris web component scripts via CDN in your `_document.tsx`, you can skip auto-injection:

```tsx
<PolarisWebProvider skipScriptInjection>
  {/* ... */}
</PolarisWebProvider>
```

## Components

### PlansPage

Full-page plan selection with optional monthly/yearly toggle:

```tsx
import { PlansPage } from '@heymantle/polaris-web-react';

export default function Plans() {
  const { customer, plans, subscribe } = useMantle();

  return (
    <PlansPage
      plans={plans}
      customer={customer}
      onSubscribe={async (plan, discount) => {
        const result = await subscribe({ planId: plan.id, discountId: discount?.id });
        if (result?.confirmationUrl) {
          window.location.href = result.confirmationUrl;
        }
      }}
      backUrl="/app"
      showIntervalToggle
    />
  );
}
```

### PlanCard

Individual plan card:

```tsx
import { PlanCard } from '@heymantle/polaris-web-react';

<PlanCard
  plan={plan}
  discount={discount}
  isRecommended
  onSelect={(plan) => console.log('Selected:', plan)}
/>
```

### PlanCardStack

Grid of plan cards:

```tsx
import { PlanCardStack } from '@heymantle/polaris-web-react';

<PlanCardStack
  plans={plans}
  customer={customer}
  interval="EVERY_30_DAYS"
  onSelectPlan={(plan) => console.log('Selected:', plan)}
/>
```

### SubscriptionCard

Display current subscription status:

```tsx
import { SubscriptionCard } from '@heymantle/polaris-web-react';

<SubscriptionCard
  subscription={customer.subscription}
  onChangePlan={() => navigate('/plans')}
  cancelSubscription={async () => {
    await cancelSubscription();
  }}
  onCancelled={() => {
    refetch();
  }}
/>
```

### ChecklistCard

Progress checklist:

```tsx
import { ChecklistCard } from '@heymantle/polaris-web-react';

<ChecklistCard
  title="Getting Started"
  steps={[
    { id: '1', name: 'Install the app', completed: true },
    { id: '2', name: 'Configure settings', completed: false },
    { id: '3', name: 'Add your first product', completed: false },
  ]}
  onToggleStep={(id, completed) => updateStep(id, completed)}
  showProgress
/>
```

### BundleCard

Promote app bundles:

```tsx
import { BundleCard } from '@heymantle/polaris-web-react';

<BundleCard
  title="Bundle and save!"
  apps={[
    {
      id: 'app1',
      name: 'Related App',
      description: 'Enhance your workflow',
      iconUrl: 'https://...',
      discountPercentage: 20,
      installUrl: 'https://...',
    },
  ]}
  onInstall={(app) => window.open(app.installUrl)}
/>
```

## TypeScript

This package includes TypeScript declarations for both the components and the Polaris web components (`s-*` elements). The JSX types are automatically available when you import from this package.

## Integration with @heymantle/react

This package works seamlessly with `@heymantle/react` for data management:

```tsx
import { MantleProvider, useMantle } from '@heymantle/react';
import { PolarisWebProvider, PlansPage } from '@heymantle/polaris-web-react';

function App() {
  return (
    <MantleProvider appId="..." customerApiToken="...">
      <PolarisWebProvider>
        <PlansPage
          plans={plans}
          onSubscribe={handleSubscribe}
        />
      </PolarisWebProvider>
    </MantleProvider>
  );
}
```

## License

MIT