npm package: @playful_process/components
Description: Shared auth components for Recursive.eco projects (DualAuth, AuthProvider, PageModals)
Author: PlayfulProcess
Latest version: 1.0.9

# Recursive Components

**NPM Package:** `@playful_process/components`

Shared UI components for the Recursive.eco ecosystem, published to npm for easy installation across all projects.

## Quick Start

```bash
npm install @playful_process/components
```

```typescript
// Auth components (from npm package)
import { OTPAuth, AuthProvider, useAuth, PageModals } from '@playful_process/components';

// Layout components (create locally in your project - see recursive-starter for reference)
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';
```

## Projects Using This Package

- **recursive-channels-fresh** (channels.recursive.eco)
- **jongu-tool-best-possible-self** (journal.recursive.eco)
- **recursive-creator** (creator.recursive.eco)
- **recursive-starter** - Minimal Next.js 15 starter template

## New to Recursive.eco?

Use **[recursive-starter](../recursive-starter/)** as your starting point:
- Production-tested auth (email + OTP)
- All components pre-configured
- Supabase integration ready
- Just copy, customize, and deploy!

## 🎯 Hybrid Approach: Auth in NPM, Layout Local

**Why this approach?**

✅ **Auth components in npm package** (OTPAuth, AuthProvider, PageModals)
- Security-critical code shared across all projects
- Updates propagate automatically via `npm update`
- One tested implementation, no divergence

✅ **Layout components local to each project** (Header, Footer)
- Each project has different navigation needs
- Easy to customize without fighting shared code
- No version conflicts when you want project-specific changes

**Best of both worlds:** Shared auth security + layout flexibility!

## 📁 What's Included in NPM Package

**Auth components only** - layout components (Header/Footer) are kept local to each project for customization.

```
@playful_process/components/
├── components/
│   ├── OTPAuth.tsx            # OTP-based authentication component
│   ├── AuthProvider.tsx        # Auth context provider
│   └── PageModals.tsx          # Modal management component
└── lib/
    ├── supabase-client.ts      # Client-side Supabase config
    └── supabase-server.ts      # Server-side Supabase config
```

**Note:** Header and Footer components are in `inactive/layout/` for reference. Copy them to your project from **recursive-starter** and customize as needed.

## 🔄 How to Use These Components

### 1. Install the Package

```bash
npm install @playful_process/components
```

### 2. Import Auth Components

```typescript
// From npm package
import {
  OTPAuth,
  AuthProvider,
  useAuth,
  PageModals
} from '@playful_process/components';

// From your local components (copy from recursive-starter)
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';
```

### 3. Set Up Supabase

Create `.env.local` with your Supabase credentials:

```env
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
```

### 4. Add AuthProvider to Layout

```typescript
// app/layout.tsx
import { AuthProvider } from '@playful_process/components';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}
```

### 5. Use Components in Your App

```typescript
// app/page.tsx
import { useAuth, PageModals } from '@playful_process/components';

export default function Home() {
  const { user, status, signOut } = useAuth();

  return (
    <>
      <main>
        {status === 'authenticated' ? (
          <p>Welcome, {user?.email}!</p>
        ) : (
          <p>Please sign in</p>
        )}
      </main>
      <PageModals />
    </>
  );
}
```

## Updating to Latest Version

```bash
npm install @playful_process/components@latest
```

## 🛠️ Component Details

### OTPAuth.tsx
- **Purpose**: OTP-based email authentication
- **Features**:
  - **Standard flow**: Email entry → OTP code verification
  - **Direct entry**: "Already have a code?" - Enter email + OTP together
  - Auto-closes on successful auth
  - Escape key to close
  - Clean, dark-mode-ready UI
- **Use case**: Direct entry helps when user already has the OTP code from their email
- **Uses**: AuthProvider (via useAuth hook)

### AuthProvider.tsx
- **Purpose**: React Context for global auth state
- **Provides**:
  - `user`: Current Supabase user object
  - `status`: 'loading' | 'authenticated' | 'unauthenticated'
  - `signOut`: Function to sign out

### Supabase Utilities
- **supabase-client.ts**: Client-side Supabase client (environment-aware cookies)
- **supabase-server.ts**: Server-side Supabase client (Next.js server components)

## 📝 Development Workflow

### For Component Maintainers:

1. **Update component** in `recursive-components`
2. **Build package**: `npm run build`
3. **Bump version** in package.json (follow semver)
4. **Publish to npm**: `npm publish`
5. **Update projects**: Run `npm install @playful_process/components@latest` in each project

## 🎨 Styling Notes

All components use **Tailwind CSS** utility classes with dark mode support:
- Light mode: `bg-white`, `text-gray-900`
- Dark mode: `dark:bg-gray-900`, `dark:text-gray-100`

## 🔐 Environment Variables

All projects using these components need these Supabase env vars:

```env
NEXT_PUBLIC_SUPABASE_URL=https://evixjvagwjmjdjpbazuj.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key  # Server-side only
```

## 📌 Version History

- **v1.0.8** (2025-11-07): Adopted hybrid approach - auth in npm, layouts local
- **v1.0.5** (2025-11-07): Fixed path alias issue (`@/lib` → `../lib`) for proper npm imports
- **v1.0.4** (2025-11-05): Added direct OTP entry mode
- **v1.0.3**: PageModals component added
- **v1.0.1**: Initial npm publication
- **2025-01-05**: Project started with Header, Footer, OTPAuth, AuthProvider

## 🛠️ Contributing

This is the source code for the npm package. To contribute:

1. Clone this repo
2. Make changes to components
3. Test locally with `npm run build`
4. Submit PR or publish new version if you're a maintainer

## 📚 Learn More

- **Starter Template**: See [recursive-starter](../recursive-starter/) for complete setup example
- **Supabase Docs**: [supabase.com/docs](https://supabase.com/docs)
- **Next.js Docs**: [nextjs.org/docs](https://nextjs.org/docs)

## 📄 License

CC BY-SA 4.0

Built with curiosity. Shared with courage. Maintained with kindness. Exploring beauty.

— PlayfulProcess