# doct-ui-auth-kit

A composable React auth SDK for building authentication and onboarding experiences. Built with React composition patterns for maximum flexibility and scalability.

## Install

```bash
npm install doct-ui-auth-kit
```

Peer dependencies (install in your app if not already present):

```bash
npm install react react-dom docthub-core-components react-hook-form zod
```

## Global styles

Import the kit CSS once in your app (e.g. in `main.tsx` or `_app.tsx`) so Tailwind and base styles apply:

```tsx
import 'doct-ui-auth-kit/style.css';
```

If you use `docthub-core-components`, import its styles first, then the auth kit:

```tsx
import 'docthub-core-components/style.css';
import 'doct-ui-auth-kit/style.css';
```

## Required static assets

When using **`MainLoginPage`** or **`AuthLayoutWrapper`** with `layoutType="withSlider"`, the kit references static paths that are served from **your app’s** `public/` folder. The published npm package does not include these files, so you must add them yourself.

| Asset | Path in your app | Used for |
|-------|------------------|----------|
| Logo | `public/main-logo.svg` | Main login page logo (or pass a custom `logo` prop to `AuthLayoutWrapper`) |
| Slider images | `public/slider/slide-1.png` … `public/slider/slide-5.png` | Marketing slider on the left panel (or pass custom `sliderImages` to `AuthLayoutWrapper`) |

**To get the default assets:** copy from this repo’s `public/main-logo.svg` and `public/slider/*.png` into your app’s `public/` (and `public/slider/`) if you have the kit source. Otherwise use your own logo and slider images. You can also override at runtime by passing the `logo` and `sliderImages` props to `AuthLayoutWrapper` (or equivalent) where the API supports it.

## Consumer imports

Install the package and import components, layouts, and types from the library:

```tsx
import {
  AuthLayout,
  OtpVerification,
  type OtpVerificationProps,
} from 'doct-ui-auth-kit';

function Example() {
  const handleSubmit: OtpVerificationProps['onSubmit'] = (otp) => {
    // handle OTP
  };

  return (
    <AuthLayout.Root variant="mobile" maxWidth="sm">
      <AuthLayout.Main>
        <AuthLayout.Body>
          <OtpVerification
            mode="phone"
            recipientDisplay="+91 9825910X0X"
            onSubmit={handleSubmit}
          />
        </AuthLayout.Body>
      </AuthLayout.Main>
    </AuthLayout.Root>
  );
}
```

## Components

### AuthLayout

A compound component system for authentication pages using composition pattern. Provides consistent spacing, responsive centering, and flexible content organization.

#### Design Philosophy

The `AuthLayout` uses compound components (slot-based pattern) to provide maximum flexibility. Each slot can be independently composed, reordered, or omitted based on your needs.

#### Usage

```tsx
import { AuthLayout } from '@/components/layout';

<AuthLayout.Root variant="desktop" maxWidth="md">
  <AuthLayout.Header>
    <EnterpriseLoginBadge />
  </AuthLayout.Header>
  <AuthLayout.Main>
    <AuthLayout.Logo>
      <img src="/logo.svg" alt="Docthub" />
    </AuthLayout.Logo>
    <AuthLayout.Title>
      <h1>The Healthcare Career App</h1>
    </AuthLayout.Title>
    <AuthLayout.Description>
      <p>Continue to Signup, If you already have an account we'll log you in.</p>
    </AuthLayout.Description>
    <AuthLayout.Body>
      <button>Continue with Mobile</button>
      <button>Continue with Email</button>
    </AuthLayout.Body>
  </AuthLayout.Main>
  <AuthLayout.Footer>
    <p>Terms and Privacy links</p>
  </AuthLayout.Footer>
</AuthLayout.Root>
```

#### Components

**`AuthLayout.Root`**
- Main container providing layout context to all child slots
- Props:
  - `variant?: 'mobile' | 'desktop'` - Layout variant (default: 'mobile')
  - `maxWidth?: 'sm' | 'md' | 'lg'` - Content width constraint (default: 'sm')
  - `className?: string` - Additional root className
  - `contentClassName?: string` - Additional content wrapper className

**`AuthLayout.Header`**
- Optional header slot, renders top-right in desktop variant, above logo in mobile

**`AuthLayout.Main`**
- Main content wrapper that centers and constrains width of inner slots

**`AuthLayout.Logo`**
- Logo slot with centered alignment

**`AuthLayout.Title`**
- Title slot with centered alignment

**`AuthLayout.Description`**
- Description slot with centered alignment

**`AuthLayout.Body`**
- Main content area for forms, buttons, etc. with vertical spacing

**`AuthLayout.Footer`**
- Optional footer slot for terms, privacy links, etc.

#### Benefits of Composition Pattern

- **Flexible ordering**: Rearrange slots as needed without prop drilling
- **Selective rendering**: Only include the slots you need
- **Type safety**: Each slot has its own typed props
- **Extensibility**: Easy to add custom slots without breaking existing APIs
- **Better DX**: Clear component hierarchy in JSX

### MainLayout

Two-panel layout for authentication pages with marketing content on the left and auth content on the right.

#### Usage

```tsx
import { MainLayout } from '@/components/layout';
import { AuthLayout } from '@/components/layout';

<MainLayout
  sliderImages={['/image1.jpg', '/image2.jpg', '/image3.jpg']}
  sliderAutoPlayInterval={5000}
  ctaText="Get Healthcare Career App Now!"
>
  <AuthLayout.Root variant="desktop" maxWidth="sm" className="bg-transparent">
    <AuthLayout.Header>
      <EnterpriseLoginBadge />
    </AuthLayout.Header>
    <AuthLayout.Main>
      <AuthLayout.Logo>...</AuthLayout.Logo>
      <AuthLayout.Title>...</AuthLayout.Title>
      <AuthLayout.Body>...</AuthLayout.Body>
    </AuthLayout.Main>
    <AuthLayout.Footer>...</AuthLayout.Footer>
  </AuthLayout.Root>
</MainLayout>
```

#### Props

- `sliderImages?: string[]` - Array of image URLs for the slider (default: [])
- `sliderAutoPlayInterval?: number` - Auto-play interval in milliseconds (default: 5000, 0 to disable)
- `ctaText?: ReactNode | null` - Call-to-action text, set to null to hide
- `className?: string` - Additional root className
- `marketingClassName?: string` - Additional className for left marketing panel
- `contentClassName?: string` - Additional className for right content panel
- `children: ReactNode` - Auth content (typically AuthLayout.Root)

### ImageSlider

Image carousel component with indicator dots. Supports both controlled and uncontrolled modes.

#### Usage (Uncontrolled)

```tsx
import { ImageSlider } from '@/components/layout';

<ImageSlider
  images={['/image1.jpg', '/image2.jpg']}
  autoPlayInterval={3000}
  onSlideChange={(index) => console.log('Slide changed to', index)}
/>
```

#### Usage (Controlled)

```tsx
import { ImageSlider } from '@/components/layout';
import { useState } from 'react';

const [activeIndex, setActiveIndex] = useState(0);

<ImageSlider
  images={['/image1.jpg', '/image2.jpg']}
  activeIndex={activeIndex}
  onSlideChange={setActiveIndex}
  onNavigate={setActiveIndex}
  autoPlayInterval={5000}
/>
```

#### Props

- `images: string[]` - Array of image URLs
- `autoPlayInterval?: number` - Auto-play interval in ms (default: 5000, 0 to disable)
- `className?: string` - Additional root className
- `hideIndicators?: boolean` - Hide built-in indicators (default: false)
- `onSlideChange?: (index: number) => void` - Callback when slide changes
- `activeIndex?: number` - Controlled active index
- `onNavigate?: (index: number) => void` - Callback for manual navigation in controlled mode

## Migration Guide

If you were using the old prop-based `AuthLayout`, here's how to migrate:

### Before (Old API)

```tsx
<AuthLayout
  header={<Header />}
  logo={<Logo />}
  title="Welcome"
  description="Sign in to continue"
  footer={<Footer />}
>
  <LoginForm />
</AuthLayout>
```

### After (New Compound API)

```tsx
<AuthLayout.Root variant="mobile" maxWidth="sm">
  <AuthLayout.Header>
    <Header />
  </AuthLayout.Header>
  <AuthLayout.Main>
    <AuthLayout.Logo>
      <Logo />
    </AuthLayout.Logo>
    <AuthLayout.Title>Welcome</AuthLayout.Title>
    <AuthLayout.Description>Sign in to continue</AuthLayout.Description>
    <AuthLayout.Body>
      <LoginForm />
    </AuthLayout.Body>
  </AuthLayout.Main>
  <AuthLayout.Footer>
    <Footer />
  </AuthLayout.Footer>
</AuthLayout.Root>
```

## Documentation

See Storybook for interactive examples and visual documentation:

```bash
npm run storybook
```

## Publishing to npm

1. **Login** (one-time): `npm login`
2. **Build** (runs automatically on publish): `npm run build`
3. **Publish**:
   - First release: `npm publish`
   - Scoped package (if name is taken): set `"name": "@your-org/doct-ui-auth-kit"` then `npm publish --access public`
4. **Use in another project**: `npm install doct-ui-auth-kit`
