bigblocks/README.md

Complete Bitcoin UI component library - authentication, social, wallet, market, inscriptions, and blockchain interactions for React

# BigBlocks

Production-ready Bitcoin UI components for React applications. Copy, paste, customize.

[![npm version](https://img.shields.io/npm/v/bigblocks.svg)](https://www.npmjs.com/package/bigblocks)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

## What is BigBlocks?

A comprehensive Bitcoin development ecosystem featuring beautifully designed, accessible UI components that you can copy and paste into your apps. Built with TypeScript, shadcn/ui, and BSV blockchain integration.

**This is NOT a traditional component library.** It's a collection of copy-and-paste components that you own. Use the CLI to selectively add components to your project, or install the full library via npm.

**Complete ecosystem includes:** Component library, comprehensive documentation, theme gallery, CLI tools, VS Code extension, and MCP server integration - all available at **[bigblocks.dev](https://bigblocks.dev)**.

### Features

- 🔐 **Authentication** - Complete Bitcoin wallet authentication flows
- 💬 **Social** - Posts, likes, follows, messaging on Bitcoin
- 💰 **Wallet** - Send BSV, view balances, manage tokens
- 🏪 **Market** - Create and purchase listings
- 👤 **Profile** - User profiles and identity management
- 🎨 **Accessible** - Built with shadcn/ui for accessibility
- 🚀 **Customizable** - Copy to your project and make it yours
- ⚡ **Modern** - TypeScript, React 18+, ES modules
- 🌐 **Framework Agnostic** - Works with Express, Next.js, Astro, any framework!

## 📚 Documentation

**[→ Full Documentation](https://bigblocks.dev/docs)** - Complete component documentation, guides, and examples
**[→ CLI Documentation](./docs/CLI.md)** - Complete CLI command reference and usage guide

## 🚀 Quick Start

**[→ Complete Quick Start Guide](https://bigblocks.dev/quickstart)** - Comprehensive setup guide with detailed examples

### ⚠️ Required: shadcn/ui Setup

**BigBlocks extends shadcn/ui and requires it as a dependency.** Install shadcn/ui first:

```bash
# 1. Install shadcn/ui (Required)
npx shadcn@latest init

# 2. Verify it works
npx shadcn@latest add button
```

### Method 1: CLI (Recommended)

Use the CLI to selectively install only the components you need:

```bash
npx bigblocks@latest init
```

This will set up your project and guide you through the installation process.

```bash
# Browse all available components
npx bigblocks list

# Add specific components
npx bigblocks add auth-flow
npx bigblocks add social-feed wallet-overview
```

**CLI creates `bigblocks.config.json` and copies components to your project. You own the code.**

### Method 2: NPM Package

> ⚠️ **Don't mix approaches!** Choose either CLI (copy-paste) OR npm (library). Don't use both.

Install the complete library:

```bash
# Just Authentication (Recommended Start)
npm install bigblocks

# With Wallet/Social Features
npm install bigblocks @tanstack/react-query

# Everything (All Features)
npm install bigblocks @tanstack/react-query js-1sat-ord sigma-protocol
```

> 💡 **Which method to choose?** 
> - **CLI**: Best for production - only includes components you use, keeps bundle small
> - **NPM**: Great for prototyping - get everything at once

## 📚 Documentation

- [Quick Start Guide](./docs/getting-started/quick-start.md) - Complete setup instructions
- [Component Registry](./registry/registry.json) - All available components
- [Examples](./examples/) - Real-world usage examples

## 📝 Usage Examples

### CLI Usage (Copy-Paste Components)

After running `npx bigblocks init` and `npx bigblocks add auth-flow`:

```tsx
// BigBlocks uses shadcn/ui components - ensure you have Tailwind CSS configured
import { BigBlocksThemeProvider, BitcoinAuthProvider } from 'bigblocks';
import { AuthFlowOrchestrator } from './components/bigblocks/AuthFlowOrchestrator';

function App() {
  return (
    <BigBlocksThemeProvider>
      <BitcoinAuthProvider>
        <AuthFlowOrchestrator
          flowType="unified"
          onSuccess={(user) => {
            console.log('User authenticated:', user);
          }}
        />
      </BitcoinAuthProvider>
    </BigBlocksThemeProvider>
  );
}
```

### NPM Package Usage

If you installed via npm:

```tsx
// BigBlocks uses shadcn/ui components - ensure you have Tailwind CSS configured
import { BigBlocksThemeProvider, BitcoinAuthProvider, AuthFlowOrchestrator } from 'bigblocks';

function App() {
  return (
    <BigBlocksThemeProvider>
      <BitcoinAuthProvider>
        <AuthFlowOrchestrator
          flowType="unified"
          onSuccess={(user) => {
            console.log('User authenticated:', user);
          }}
        />
      </BitcoinAuthProvider>
    </BigBlocksThemeProvider>
  );
}
```

### Social Media App

```tsx
import { PostButton, SocialFeed, LikeButton } from 'bigblocks';

function SocialApp() {
  return (
    <div>
      <PostButton onSuccess={() => console.log('Posted!')} />
      <SocialFeed />
    </div>
  );
}
```

### Bitcoin Wallet

```tsx
import { WalletOverview, SendBSVButton } from 'bigblocks';

function WalletApp() {
  return (
    <div>
      <WalletOverview />
      <SendBSVButton 
        onSuccess={(txid) => console.log('Sent!', txid)}
      />
    </div>
  );
}
```

### Framework-Agnostic Authentication (NEW!)

Use BigBlocks with any JavaScript framework:

```typescript
// Express.js
import { createExpressBigBlocks } from 'bigblocks/express';
app.use('/api/auth', createExpressBigBlocks().handler);

// Next.js
import { createNextJSBigBlocks } from 'bigblocks/nextjs';
export const { GET, POST } = createNextJSBigBlocks();

// Astro
import { createAstroBigBlocks } from 'bigblocks/astro';
export const { GET, POST } = createAstroBigBlocks();
```

[→ Framework Usage Guide](./examples/framework-agnostic-usage.md)

## 📦 Available Components (98 Total)

BigBlocks includes 98 production-ready React components across all Bitcoin development needs:

> **📊 Component Count**: Run `bun run count-components` to get the latest accurate count from the registry. Use `bigblocks count` for detailed breakdowns by category.

### 🔐 Authentication (6 components)
- `AuthButton` - Main authentication button
- `LoginForm` - Bitcoin wallet login form
- `SignupFlow` - New user registration flow

- `OAuthRestoreFlow` - OAuth wallet restoration
- `AuthFlowOrchestrator` - Complete authentication orchestrator

### 💬 Social Features (9 components)
- `PostButton` - Create posts on Bitcoin
- `SocialFeed` - Display social media feed
- `LikeButton` - Like posts on the network
- `FollowButton` - Follow other users
- `MessageDisplay` - Display messages
- `PostCard` - Individual post display
- `FriendsDialog` - Friends management
- `CompactPostButton` - Compact post creation
- `CompactMessageButton` - Compact messaging

### 💰 Wallet Components (8 components)
- `WalletOverview` - Complete wallet dashboard
- `SendBSVButton` - Send Bitcoin transactions
- `TokenBalance` - Display token balances
- `DonateButton` - Donation functionality
- Plus compact/quick variants for each

### 👤 Profile Management (8 components)
- `ProfileDropdownMenu` - Complete user menu with wallet & themes
- `ProfileCard` - Display user profile information
- `ProfileEditor` - Edit profile details
- `ProfileSwitcher` - Switch between multiple profiles
- `ProfileViewer` - View profile details
- `ProfileManager` - Manage multiple profiles
- `ProfilePopover` - Profile info popover
- `ProfilePublisher` - Publish profiles to blockchain

### 🏪 Market Components (6 components)
- `MarketTable` - Display marketplace listings
- `CreateListingButton` - Create new listings
- `BuyListingButton` - Purchase items
- Plus compact/quick variants for each

### 🎨 UI Components (14 components)
- `PasswordInput` - Secure password field
- `LoadingButton` - Button with loading states
- `ErrorDisplay` - Error message display
- `BitcoinAvatar` - User avatars
- `TransactionProgress` - Blockchain transaction status
- `ErrorRecovery` - Smart error handling
- `Modal` - Dialog modals
- `QRCodeRenderer` - QR code display
- `CodeBlock` - Code syntax highlighting
- `WarningCard` - Warning messages
- `StepIndicator` - Multi-step processes
- `DecorativeBox` - Styled containers
- `BitcoinImage` - Bitcoin-themed images
- Plus layout components

### 🔧 Additional Categories
- **Backup/Recovery (8 components)** - BackupImport, BackupDownload, MnemonicDisplay, IdentityGeneration, FileImport, DeviceLinkQR, MemberExport, CloudBackupManager
- **Layout Components (6 components)** - AuthLayout, CenteredLayout, AuthCard, LoadingLayout, ErrorLayout, SuccessLayout  
- **Wallet Integration (5 components)** - OAuthProviders, OAuthConflictModal, OAuthRestoreForm, YoursWalletConnector, HandCashConnector
- **Developer Tools (4 components)** - ArtifactDisplay, ShamirSecretSharing, Type42KeyDerivation, KeyManager
- **BAP Identity (3 components)** - BapKeyRotationManager, BapFileSigner, BapEncryptionSuite
- **Providers (3 components)** - BitcoinAuthProvider, BigBlocksThemeProvider, BigBlocksQueryProvider
- **Droplit Integration (3 components)** - TapButton, DataPushButton, DataPushForm

### 📐 Layout System & Responsive Design (NEW!)
- **Intelligent Responsive Components** - All components now adapt beautifully to any screen size
- **Responsive Design** - Mobile-first responsive components
- **Centralized Layout Constants** - Consistent sizing across all components
- **Responsive Utilities** - Smart breakpoint system with `initial`, `sm`, `md`, `lg` values
- **8px Grid System** - Harmonious spacing scale
- **Container Widths** - Responsive pages, cards, modals, popovers, forms
- **Layout Dimensions** - Adaptive sidebars, panels, headers
- **TypeScript Support** - Fully typed constants and responsive values
- **Mobile-First Design** - Optimized for mobile with progressive enhancement

[View all components →](./docs/getting-started/quick-start.md#component-examples)

## 🌐 Client-Side Library

**Important**: BigBlocks is a client-side library. Components require browser APIs for:
- Bitcoin wallet operations
- File handling (backups)
- Cryptographic operations
- Clipboard access

For SSR frameworks, disable server rendering:
- Next.js: Use dynamic imports with `ssr: false`
- Astro: Use `client:only` directives
- Remix: Use `.client.tsx` files

## 🛠️ CLI Commands

```bash
# Initialize BigBlocks
npx bigblocks@latest init

# List all available components
bigblocks list

# Add specific components
bigblocks add auth-flow
bigblocks add social-feed wallet-overview

# Check registry status
bigblocks status

# View documentation
bigblocks docs
```

### 🔗 Blockchain Registry (Experimental)

Enable decentralized component fetching from BSV blockchain:

```bash
# Set your private key (WIF format)
export BIGBLOCKS_WIF="your-private-key-here"

# Components will now be fetched from both GitHub and blockchain
bigblocks list
```

> ⚠️ **Experimental Feature**: Blockchain registry is currently in development. Components are fetched via MAP protocol queries on BSV blockchain.

## 🎨 Styling & Theming

BigBlocks uses **CSS variables** for automatic theme support. Components automatically adapt to theme changes without manual intervention.

### Quick Styling Example

```tsx
// ✅ Good - Automatic theme support
<div style={{
  background: 'var(--gray-1)',
  color: 'var(--accent-9)',
  border: '1px solid var(--gray-7)',
  borderRadius: 'var(--radius-3)',
  padding: 'var(--space-4)'
}}>
  Content adapts to any theme
</div>

// ❌ Avoid - Won't respond to theme changes  
<div style={{
  background: '#ffffff',
  color: '#f7931a'
}}>
  Static colors
</div>
```

### Bitcoin Themes

```tsx
<BigBlocksThemeProvider defaultTheme="purple">   {/* Purple */}
<BigBlocksThemeProvider defaultTheme="cyberpunk"> {/* Cyberpunk */}
<BigBlocksThemeProvider defaultTheme="ocean">     {/* Ocean */}
<BigBlocksThemeProvider defaultTheme="dark">      {/* Dark Mode */}
```

### 🎨 60+ Pre-configured Themes

BigBlocks includes 60+ beautiful theme presets ready to use:

```tsx
import { BigBlocksThemeProvider, getThemePreset, themeCategories } from 'bigblocks';

// Use a pre-configured theme
<BigBlocksThemeProvider defaultTheme="cyberpunk">
  <App />
</BigBlocksThemeProvider>

// Access theme metadata
const theme = getThemePreset('ocean');
console.log(theme); // { name: 'Ocean', description: 'Cool cyan theme...', accentColor: 'cyan', ... }

// Browse available themes by category
console.log(themeCategories.sophisticated); // ['neo', 'cyberpunk', 'neon', 'noir', ...]
console.log(themeCategories.nature);        // ['forest', 'ocean', 'sunset', 'midnight', ...]
console.log(themeCategories.elegant);       // ['rose', 'lavender', 'emerald', 'sapphire', ...]
console.log(themeCategories.artistic);      // ['vintage', 'sepia', 'monochrome', 'pastel', ...]
```

**Theme Categories:**
- **Sophisticated** (8 themes): Neo, Cyberpunk, Neon, Noir, Aurora, Nebula, Prism, Vortex
- **Nature** (8 themes): Forest, Ocean, Sunset, Midnight, Dawn, Twilight, Storm, Arctic  
- **Elegant** (8 themes): Rose, Lavender, Emerald, Sapphire, Ruby, Topaz, Onyx, Pearl
- **Artistic** (8 themes): Vintage, Sepia, Monochrome, Pastel, Vibrant, Minimal, Luxury, Cosmic
- **Tweakcn Themes**: 37+ themes including modern-minimal, twitter, catppuccin, cyberpunk, claude, vercel, neo-brutalism, and more

**[📖 Complete Styling Guide →](./docs/STYLING_GUIDE.md)**

### Layout Constants

BigBlocks provides centralized layout constants for consistent sizing:

```tsx
import { CONTAINER_WIDTHS, SPACING, HEIGHTS } from 'bigblocks';

// Consistent card widths
<Card style={{ maxWidth: CONTAINER_WIDTHS.CARD_MEDIUM }}>

// Responsive popovers
<Popover.Content style={{ minWidth: CONTAINER_WIDTHS.POPOVER_LARGE }}>

// Harmonious spacing
<Box style={{ padding: SPACING.MD, gap: SPACING.SM }}>

// Fixed header height
<Header style={{ height: HEIGHTS.HEADER_DESKTOP }}>
```

**[📐 Layout Constants Guide →](./docs/LAYOUT_CONSTANTS_GUIDE.md)**

## ⚠️ Important Implementation Notes

### Password Field is ALWAYS Required
A common mistake is labeling the password field as "Password (if encrypted)" or hiding it conditionally. **The password field must ALWAYS be shown**:

- **Encrypted backups**: Password decrypts the backup
- **Unencrypted backups**: Password encrypts for secure storage  
- **New users**: Password encrypts the generated backup

```tsx
// ❌ WRONG
<PasswordInput label="Password (if encrypted)" />

// ✅ CORRECT  
<PasswordInput label="Password" />
```

See the [Integration Guide](./docs/INTEGRATION_GUIDE.md#common-implementation-mistakes) for more details.

## 📚 Documentation & Resources

### 🌐 **Complete Documentation**
**[bigblocks.dev](https://bigblocks.dev)** - Your one-stop resource for everything BigBlocks

### 📖 **Key Resources**

- **[📋 Quick Start Guide](https://bigblocks.dev/quickstart)** - Get up and running in minutes
- **[📚 Full Documentation](https://bigblocks.dev/docs)** - Comprehensive guides and API references  
- **[🎨 Component Library](https://bigblocks.dev/components)** - Browse all available components with live examples
- **[🎨 Theme Gallery](https://bigblocks.dev/themes)** - Explore Bitcoin-inspired color themes
- **[🔌 MCP Server](https://bigblocks.dev/mcp-server)** - Model Context Protocol integration for AI assistants

### 🛠️ **Developer Tools**

- **[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Satchmo.bitcoin)** - Bitcoin development tools for VS Code
- **[GitHub Repository](https://github.com/bigblocks-dev/bigblocks)** - Source code and issue tracking

## 👨‍💻 Contributing

We welcome contributions! BigBlocks is open source and built for the Bitcoin community.

### Adding Components

1. Create your component in `src/components/`
2. Add it to `registry/registry.json`
3. Add stories for Storybook
4. Submit a pull request

### Component Guidelines

- Built with TypeScript and shadcn/ui
- Accessible by default
- Include comprehensive prop documentation
- Follow existing patterns and conventions

### Testing

BigBlocks includes comprehensive visual testing using Playwright:

```bash
# Run all screenshot tests
bun run test:screenshots

# Run specific test suites
bun run test:screenshots:components  # Component screenshots
bun run test:screenshots:themes      # shadcn/ui theme screenshots
bun run test:screenshots:tweakcn     # Tweakcn theme screenshots
```

Screenshots are generated in the `screenshots/` directory (gitignored) and are useful for:
- Visual regression testing
- Documentation
- Showcasing components with different themes
- Design reviews

See [tests/README.md](./tests/README.md) for more information about testing.

## 🔗 Links

- [GitHub Repository](https://github.com/b-open-io/bigblocks)
- [NPM Package](https://www.npmjs.com/package/bigblocks)
- [Quick Start Guide](./docs/getting-started/quick-start.md)
- [Component Examples](./examples/)

## 📜 License

MIT © [BigBlocks Team](https://github.com/bigblocks-dev)

---

**Built with ❤️ for the Bitcoin community**

# BigBlocks

A comprehensive React component library for Bitcoin authentication, wallet integration, and blockchain interactions.

## 🚨 IMPORTANT: Backend Setup Required

**Before using `LoginForm` or authentication components, you must implement backend endpoints.**

BigBlocks extends NextAuth but requires additional API endpoints. See **[Backend Setup Guide](./examples/backend-setup-guide.md)** for complete instructions.

**Missing the `/api/auth/signin` endpoint will cause LoginForm to show "Loading..." forever.**

## Quick Start

### 1. Install
```bash
npm install bigblocks
```

### 2. Setup Backend (REQUIRED)
```typescript
// app/api/auth/signin/route.ts
export async function POST(request) {
  // Your Bitcoin signature verification here
  // See examples/backend-setup-guide.md for complete code
  return NextResponse.json({ success: true });
}
```

### 3. Use Components
```tsx
import { BitcoinAuthProvider, LoginForm } from 'bigblocks';

<BitcoinAuthProvider config={{ apiUrl: '/api' }}>
  <LoginForm onSuccess={(user) => console.log('Logged in:', user)} />
</BitcoinAuthProvider>
```

### 4. Configure Blockchain Services (NEW!)

BigBlocks now supports flexible API key configuration for blockchain services:

```tsx
// Proxy Mode (Recommended - keeps API keys secure)
<BitcoinAuthProvider config={{
  apiUrl: '/api',
  blockchainService: {
    mode: 'proxy',
    proxy: {
      endpoint: '/api/blockchain',
      headers: { 'Authorization': 'Bearer token' }
    }
  }
}}>

// Client Mode (for development/testing)
<BitcoinAuthProvider config={{
  apiUrl: '/api',
  blockchainService: {
    mode: 'client',
    client: {
      apiKeys: {
        whatsonchain: 'your-api-key',
        taal: 'your-taal-key'
      },
      preferredService: 'whatsonchain'
    }
  }
}}>
```

📖 **[API Key Configuration Guide](./docs/API_KEY_CONFIGURATION.md)** - Complete guide for configuring blockchain services

📖 **[Backend Setup Guide](./examples/backend-setup-guide.md)** - Full backend implementation details

---

## Components

// ... existing code ...