# @shopplus/membership-ui

Membership platform UI SDK for ShopPlus / Shopify / ShopLine stores. Pre-built Web Components with Shadow DOM isolation, theme support, and 12-language i18n.

## Features

- Pre-built membership UI components (member center, points, coupons, referral, check-in)
- Auth components (login form, register form, OAuth buttons, verification code, password reset)
- Shadow DOM isolation — no CSS conflicts with host site
- Theme customization via CSS variables
- 12 built-in languages with RTL support
- Works with any framework (React, Vue, Svelte, vanilla HTML)
- Responsive and accessible (WCAG 2.1 AA)

## Install

```bash
npm install @shopplus/membership-ui
```

## Quick Start

```typescript
import { registerAllComponents, initMembership } from '@shopplus/membership-ui';

// Register all custom elements
registerAllComponents();

// Initialize SDK connection
initMembership({
  baseUrl: 'https://api.membership.example.com',
  tenantId: 'your_tenant_id',
  locale: 'en-US',
});
```

```html
<!-- Use components directly in HTML -->
<ms-member-center></ms-member-center>
<ms-points-detail></ms-points-detail>
<ms-level-progress></ms-level-progress>
```

## Available Components

### Page Components

| Component | Tag | Description |
|---|---|---|
| MemberCenter | `<ms-member-center>` | Member profile overview with navigation |
| PointsDetail | `<ms-points-detail>` | Points transaction history |
| LevelProgress | `<ms-level-progress>` | Level progress bar and benefits |
| CouponList | `<ms-coupon-list>` | Coupon list with tabs (available/used/expired) |
| ReferralShare | `<ms-referral-share>` | Referral code, link, and invite stats |
| CheckinCalendar | `<ms-checkin-calendar>` | Daily check-in calendar with streak rewards |

### Auth Components

| Component | Tag | Description |
|---|---|---|
| LoginForm | `<ms-login-form>` | Email/password login with OAuth buttons |
| RegisterForm | `<ms-register-form>` | Registration form with password validation |
| OAuthButtons | `<ms-oauth-buttons>` | Social login buttons (Google, Facebook, Apple, Line) |
| VerifyCode | `<ms-verify-code>` | Verification code input |
| ForgotPassword | `<ms-forgot-password>` | Password reset flow |
| SignupFlow | `<ms-signup-flow>` | Complete registration flow (register → verify → done) |

## Selective Registration

Register only the components you need:

```typescript
import {
  registerMemberCenter,
  registerPointsDetail,
  registerAuthComponents,
} from '@shopplus/membership-ui';

registerMemberCenter();
registerPointsDetail();
registerAuthComponents(); // registers all auth components
```

## Theme Customization

Customize appearance via CSS variables:

```css
ms-member-center {
  --ms-primary: #6366f1;
  --ms-font-family: 'Inter', sans-serif;
  --ms-radius: 8px;
  --ms-spacing-md: 16px;
  --ms-text-primary: #1f2937;
  --ms-border-color: #e5e7eb;
  --ms-error: #ef4444;
}
```

Or use the ThemeManager programmatically:

```typescript
import { ThemeManager } from '@shopplus/membership-ui';

ThemeManager.setTheme({
  primary: '#6366f1',
  radius: '8px',
  fontFamily: 'Inter, sans-serif',
});
```

## Events

Components emit custom events for integration:

```typescript
// Login form submit
document.querySelector('ms-login-form')
  .addEventListener('ms-login-submit', (e) => {
    const { email, password } = e.detail;
    // handle login via SDK
  });

// Navigation events
document.querySelector('ms-member-center')
  .addEventListener('ms-navigate', (e) => {
    const { page } = e.detail; // 'pointsDetail', 'levelDetail', etc.
  });
```

## Component Configuration

Configure components via attributes or JavaScript:

```html
<ms-login-form tenant-id="site_001" locale="zh-CN"></ms-login-form>
```

```typescript
const form = document.querySelector('ms-login-form');
form.configure({
  tenantId: 'site_001',
  showOAuth: true,
  oauthProviders: ['google', 'facebook'],
  showRegisterLink: true,
  showForgotPassword: true,
});
```

## Framework Integration

### React

```tsx
function App() {
  return <ms-member-center tenant-id="site_001" />;
}
```

### Vue

```vue
<template>
  <ms-member-center :tenant-id="tenantId" />
</template>
```

### Vanilla HTML

```html
<script src="https://unpkg.com/@shopplus/membership-ui"></script>
<script>
  ShopPlusMembershipUI.registerAllComponents();
</script>
<ms-member-center tenant-id="site_001"></ms-member-center>
```

## Module Formats

| Format | File | Usage |
|---|---|---|
| ESM | `dist/index.es.js` | `import` in bundlers |
| UMD | `dist/index.umd.js` | `<script>` tag (global `ShopPlusMembershipUI`) |
| Types | `dist/index.d.ts` | TypeScript support |

## Dependencies

This package automatically installs:
- `@shopplus/membership-sdk` — Data SDK for API communication
- `@shopplus/membership-i18n` — Internationalization and formatting

## Browser Support

ES2017+ (Chrome 61+, Firefox 63+, Safari 12.1+, Edge 79+)

Requires native Custom Elements and Shadow DOM support.

## License

MIT