npm package: @reemwsw/auth-ui
Description: A flexible, customizable authentication UI library for React
Author: Your Name
Latest version: 1.1.0

# @reemwsw/auth-ui

A flexible, customizable authentication UI library for React. Works with any backend and styling solution.

## Features

- 🎨 **Fully Customizable** - CSS variables, component injection, or use defaults
- 🔌 **Backend Agnostic** - Works with any API structure via adapters
- 📦 **Zero UI Dependencies** - No shadcn/ui or other UI libraries required
- 🌙 **Dark Mode Ready** - Built-in dark mode support
- 🔐 **OAuth Support** - Google, GitHub, Facebook, Apple, Twitter, LINE, Threads
- 📱 **Responsive** - Mobile-first design with multiple layouts
- 🔄 **TypeScript** - Full type safety

## Installation

```bash
npm install @reemwsw/auth-ui
# or
yarn add @reemwsw/auth-ui
# or
pnpm add @reemwsw/auth-ui
```

## Quick Start

```tsx
import { AuthProvider, AuthContainer, AuthForm, OAuthButtons } from '@reemwsw/auth-ui';

function LoginPage() {
  return (
    <AuthProvider>
      <AuthContainer layout="center" title="Sign In">
        <OAuthButtons providers={['google', 'github']} showDivider />
        <AuthForm showRememberMe showForgotPassword />
      </AuthContainer>
    </AuthProvider>
  );
}
```

## Configuration

### Basic Configuration

```tsx
import { AuthProvider } from '@reemwsw/auth-ui';

function App({ children }) {
  return (
    <AuthProvider
      config={{
        endpoints: {
          login: '/api/auth/login',
          register: '/api/auth/register',
          oauth: '/api/auth/oauth',
          me: '/api/auth/me',
          logout: '/api/auth/logout',
        },
        storageType: 'localStorage', // or 'sessionStorage' or 'none'
        storagePrefix: 'myapp_auth_',
      }}
    >
      {children}
    </AuthProvider>
  );
}
```

### Custom API Adapter

For complete control over API calls:

```tsx
import { AuthProvider, AuthApiAdapter } from '@reemwsw/auth-ui';

const myApiAdapter: AuthApiAdapter = {
  login: async (credentials) => {
    const res = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify(credentials),
    });
    const data = await res.json();
    return {
      success: res.ok,
      user: data.user,
      token: data.token,
    };
  },
  register: async (data) => { /* ... */ },
  logout: async () => { /* ... */ },
  getUser: async () => { /* ... */ },
};

<AuthProvider config={{ apiAdapter: myApiAdapter }}>
  {children}
</AuthProvider>
```

### Custom UI Components

Inject your own UI components (e.g., shadcn/ui):

```tsx
import { AuthProvider } from '@reemwsw/auth-ui';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Checkbox } from '@/components/ui/checkbox';
import { Label } from '@/components/ui/label';
import { Alert } from '@/components/ui/alert';

<AuthProvider
  components={{
    Button: ({ children, loading, ...props }) => (
      <Button disabled={loading} {...props}>
        {loading && <Spinner />}
        {children}
      </Button>
    ),
    Input: ({ error, ...props }) => (
      <Input className={error ? 'border-red-500' : ''} {...props} />
    ),
    Checkbox: ({ onCheckedChange, ...props }) => (
      <Checkbox onCheckedChange={onCheckedChange} {...props} />
    ),
    Label,
    Alert: ({ variant, children }) => (
      <Alert variant={variant === 'destructive' ? 'destructive' : 'default'}>
        {children}
      </Alert>
    ),
  }}
>
  {children}
</AuthProvider>
```

## Components

### AuthContainer

Layout wrapper with three modes:

```tsx
// Centered card
<AuthContainer layout="center" title="Sign In" subtitle="Welcome back">
  {children}
</AuthContainer>

// Split screen - form on left
<AuthContainer
  layout="left"
  title="Create Account"
  logo={<img src="/logo.svg" />}
  backgroundContent={<CustomBackground />}
>
  {children}
</AuthContainer>

// Split screen - form on right
<AuthContainer layout="right" title="Welcome">
  {children}
</AuthContainer>
```

### AuthForm

Complete login/register form:

```tsx
<AuthForm
  mode="login"                        // 'login' | 'register'
  showRememberMe={true}
  showForgotPassword={true}
  forgotPasswordUrl="/forgot"
  showRegisterLink={true}
  showTermsLink={true}
  termsUrl="/terms"
  privacyUrl="/privacy"
  onSuccess={(user) => router.push('/dashboard')}
  onError={(error) => console.error(error)}
  onModeChange={(mode) => console.log(mode)}
/>
```

### OAuthButtons

Social login buttons:

```tsx
<OAuthButtons
  providers={['google', 'github', 'facebook']}
  orientation="horizontal"           // 'horizontal' | 'vertical'
  showDivider={true}
  dividerText="or continue with"
  showLabels={true}                  // false = icons only
  onOAuthClick={(provider) => console.log(provider)}
/>
```

## Hooks

### useAuthContext

Access auth state and methods:

```tsx
import { useAuthContext } from '@reemwsw/auth-ui';

function MyComponent() {
  const { auth, components, config } = useAuthContext();

  const { user, isAuthenticated, loading, error } = auth;

  const handleLogout = () => auth.logout();

  return (
    <div>
      {isAuthenticated ? (
        <p>Welcome, {user.name}</p>
      ) : (
        <p>Please sign in</p>
      )}
    </div>
  );
}
```

### useAuth (standalone)

Use auth logic without the provider:

```tsx
import { useAuth } from '@reemwsw/auth-ui';

function MyComponent() {
  const auth = useAuth({
    config: {
      endpoints: { login: '/api/login' },
    },
  });

  // Same API as useAuthContext().auth
}
```

## Styling

### CSS Variables

Customize with CSS variables:

```css
:root {
  --auth-primary: #7c3aed;
  --auth-primary-hover: #6d28d9;
  --auth-radius: 0.75rem;
  --auth-shadow: 0 10px 40px rgba(0, 0, 0, 0.1);
}

/* Dark mode */
.dark {
  --auth-primary: #8b5cf6;
  --auth-background: #1e1e2e;
  --auth-foreground: #cdd6f4;
}
```

### Theme Presets

```html
<div data-auth-theme="purple">
  <!-- Purple theme -->
</div>
```

Available themes: `purple`, `green`, `red`, `orange`

## TypeScript

Full type definitions included:

```tsx
import type {
  AuthUser,
  AuthConfig,
  AuthApiAdapter,
  LoginCredentials,
  RegisterData,
  AuthResponse,
  AuthLayoutType,
  AuthProviderType,
} from '@reemwsw/auth-ui';
```

## API Reference

### AuthConfig

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `endpoints` | `AuthApiEndpoints` | `/api/auth/*` | API endpoint URLs |
| `apiAdapter` | `AuthApiAdapter` | - | Custom API handler |
| `components` | `AuthUIComponents` | Default components | UI component overrides |
| `theme` | `AuthThemeConfig` | - | Theme configuration |
| `storageType` | `'localStorage' \| 'sessionStorage' \| 'none'` | `localStorage` | Token storage |
| `storagePrefix` | `string` | `auth_` | Storage key prefix |
| `debug` | `boolean` | `false` | Enable debug logging |

### AuthApiEndpoints

| Property | Type | Default |
|----------|------|---------|
| `login` | `string` | `/api/auth/login` |
| `register` | `string` | `/api/auth/register` |
| `oauth` | `string` | `/api/auth/oauth` |
| `me` | `string` | `/api/auth/me` |
| `logout` | `string` | `/api/auth/logout` |
| `resetPassword` | `string` | `/api/auth/reset-password` |

## License

MIT