@strands.gg/accui 0.0.4 → 0.0.6

package/README.md

@@ -1,49 +1,278 @@
 # @strands.gg/accui
 
-Strands Authentication UI Components for Vue 3
+Modern authentication UI components for Vue 3 with magic link support and OAuth integration.
 
-## Installation
+## 🚀 Features
+
+- **Magic Link Authentication** - Passwordless signup flow
+- **OAuth Providers** - Dynamic OAuth provider discovery from API
+- **Vue 3 Composition API** - Built with modern Vue patterns
+- **TypeScript Support** - Full type safety
+- **Nuxt Module** - First-class Nuxt 3 support
+- **Customizable UI** - Consistent design system with Tailwind CSS
+- **Responsive Design** - Mobile-first approach
+
+## 📦 Installation
 
 ```bash
 npm install @strands.gg/accui
 ```
 
-## Usage
+### Import Styles
+
+```javascript
+// Import the CSS in your main.js or app.vue
+import '@strands.gg/accui/style.css'
+```
+
+## 🎯 Quick Start
+
+### Basic Vue 3 Usage
 
 ```vue
 <template>
   <div>
+    <!-- Combined Auth Component with tabs -->
+    <StrandsAuth 
+      @success="handleSuccess" 
+      @error="handleError"
+      redirect-url="/dashboard"
+    />
+    
+    <!-- Or use individual components -->
     <StrandsSignIn @success="handleSignInSuccess" />
+    <StrandsSignUp @success="handleSignUpSuccess" />
   </div>
 </template>
 
 <script setup lang="ts">
-import { StrandsSignIn } from "@strands.gg/accui";
+import { 
+  StrandsAuth, 
+  StrandsSignIn, 
+  StrandsSignUp,
+  useStrandsAuth 
+} from "@strands.gg/accui"
+
+// Access auth state globally
+const { user, isAuthenticated, signOut } = useStrandsAuth()
+
+const handleSuccess = (userData: any) => {
+  console.log("Authentication successful:", userData)
+}
+
+const handleError = (error: string) => {
+  console.error("Authentication error:", error)
+}
+
+const handleSignUpSuccess = (data: { email: string }) => {
+  console.log("Magic link sent to:", data.email)
+}
+</script>
+```
+
+### Nuxt 3 Module
+
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@strands.gg/accui/nuxt'],
+  strandsAuth: {
+    apiBaseUrl: 'https://your-api.com',
+    // Other configuration options
+  }
+})
+```
+
+## 🧩 Components
+
+### Authentication Components
+
+| Component | Description | Use Case |
+|-----------|-------------|----------|
+| `StrandsAuth` | Combined auth with tabs | All-in-one solution |
+| `StrandsSignIn` | Email + password sign in | Traditional login |
+| `StrandsSignUp` | Magic link signup | Passwordless registration |
+| `StrandsPasswordReset` | Password reset form | Recovery flow |
+| `StrandsUserProfile` | Profile management | User settings |
+| `StrandsMFASetup` | Multi-factor auth setup | Security enhancement |
+
+### Utility Components
+
+| Component | Description |
+|-----------|-------------|
+| `SignedIn` | Conditional rendering for authenticated users |
+| `SignedOut` | Conditional rendering for unauthenticated users |
+| `StrandsConfigProvider` | Scoped configuration provider |
+| `StrandsLogo` | Strands branding logo |
+| `StrandsSecuredFooter` | "Secured by Strands" footer |
+
+### UI Components
+
+| Component | Description | Props |
+|-----------|-------------|-------|
+| `UiButton` | Styled button | `variant`, `size`, `loading`, `disabled` |
+| `UiInput` | Form input field | `type`, `label`, `error`, `placeholder` |
+| `UiCard` | Container card | `variant`, `shadow`, `padding` |
+| `UiTabs` | Tab navigation | `tabs`, `modelValue` |
+| `UiAlert` | Status messages | `variant`, `message` |
+| `UiLink` | Styled link | `variant`, `size` |
+
+## 🔧 Composables
+
+### `useStrandsAuth()`
+
+Global authentication state management:
+
+```typescript
+const {
+  user,           // Current user object
+  isAuthenticated, // Boolean auth status
+  isLoading,      // Loading state
+  signOut,        // Sign out function
+  refreshUser     // Refresh user data
+} = useStrandsAuth()
+```
+
+### `useStrandsConfig()`
+
+Configuration management:
+
+```typescript
+const { 
+  config,    // Current configuration
+  getUrl     // Helper to build API URLs
+} = useStrandsConfig()
+```
+
+### `useOAuthProviders()`
+
+OAuth provider management:
+
+```typescript
+const {
+  enabledProviders,    // Available OAuth providers
+  loading,            // Loading state
+  error,              // Error state
+  fetchProviders,     // Fetch providers from API
+  redirectToProvider  // Initiate OAuth flow
+} = useOAuthProviders()
+```
+
+## 🎨 Magic Link Flow
+
+The signup component uses a modern magic link approach:
+
+```vue
+<template>
+  <!-- User enters email only -->
+  <StrandsSignUp @success="handleMagicLinkSent" />
+</template>
+
+<script setup lang="ts">
+// User receives magic link via email
+// Clicking link completes registration
+const handleMagicLinkSent = (data: { email: string }) => {
+  // Show success message
+  console.log(`Magic link sent to ${data.email}`)
+}
+</script>
+```
+
+## 🔐 Configuration
+
+### Global Configuration
+
+```typescript
+import { setStrandsConfig } from '@strands.gg/accui'
 
-const handleSignInSuccess = (user: any) => {
-  console.log("User signed in:", user);
-};
+setStrandsConfig({
+  apiBaseUrl: 'https://your-api.com',
+  clientId: 'your-client-id',
+  // Additional options
+})
+```
+
+### Scoped Configuration
+
+```vue
+<template>
+  <StrandsConfigProvider :config="scopedConfig">
+    <StrandsAuth />
+  </StrandsConfigProvider>
+</template>
+
+<script setup lang="ts">
+const scopedConfig = {
+  apiBaseUrl: 'https://different-api.com'
+}
 </script>
 ```
 
-## Available Components
+## 🎯 OAuth Integration
+
+OAuth providers are dynamically loaded from your API endpoint:
+
+```javascript
+// GET /api/v1/oauth/providers
+{
+  "providers": [
+    {
+      "id": "google",
+      "name": "Google",
+      "displayName": "Google",
+      "iconUrl": "https://example.com/google-icon.svg",
+      "enabled": true
+    }
+  ]
+}
+```
+
+## 📱 Responsive Design
+
+All components are mobile-first and responsive:
 
-- `StrandsSignIn` - Sign in form component
-- `StrandsSignUp` - Sign up form component
-- `StrandsUserProfile` - User profile management component
-- `StrandsPasswordReset` - Password reset component
-- `StrandsMFASetup` - Multi-factor authentication setup
-- `StrandsDeviceManager` - Device management component
+- **Mobile**: Optimized touch targets and layouts
+- **Tablet**: Adaptive spacing and sizing
+- **Desktop**: Full-featured experience
+
+## 🎨 Theming
+
+Components use CSS custom properties for theming:
+
+```css
+:root {
+  --strands-primary: #your-brand-color;
+  --strands-secondary: #your-secondary-color;
+  /* Additional theme variables */
+}
+```
+
+## 📋 TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import type { 
+  StrandsUser, 
+  StrandsSession, 
+  StrandsAuthConfig,
+  ButtonVariant,
+  InputType 
+} from '@strands.gg/accui'
+```
 
-## Composables
+## 🔧 Requirements
 
-- `useStrandsAuth` - Authentication state management composable
+- **Vue**: 3.5+ 
+- **Node**: 16+
+- **TypeScript**: 5+ (optional but recommended)
 
-## Requirements
+## 📄 License
 
-- Vue 3.4+
+MIT © Strands Services Limited
 
-## License
+---
 
-MIT
+**Need help?** Check out our [documentation](https://docs.strands.gg) or open an issue on GitHub.