use-vibes 0.4.15 → 0.5.0

package/README.md

@@ -8,11 +8,276 @@ A lightweight library that transforms any DOM element into an AI-powered micro-a
 pnpm add use-vibes
 ```
 
-### CSS Loading
+## Basic Usage
 
-The ImgGen component requires CSS styles. You can include them in two ways:
+```jsx
+import { ImgGen } from 'use-vibes';
+import 'use-vibes/style-loader'; // Quick setup for CSS
+
+function MyComponent() {
+  // You can use ImgGen without any props - it includes its own form UI
+  return <ImgGen />;
+  
+  // Or provide a prompt directly (bypasses the form UI completely)
+  // return <ImgGen prompt="A futuristic cityscape with flying cars" />;
+}
+```
+
+For image manipulation using base64 data:
+
+```jsx
+import { base64ToFile } from 'use-vibes';
+
+// Convert API response to a File object
+const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');
+```
+
+## Core Features
+
+### Interactive Image Generation
+
+- **Zero-config Implementation**: Add AI image generation to any React app without any configuration
+
+  ```jsx
+  {/* Includes a built-in form UI for prompt entry and image upload */}
+  <ImgGen />
+  ```
+
+- **One-line Implementation**: Directly specify a prompt for immediate generation (bypasses the form UI)
+
+  ```jsx
+  {/* Starts generating immediately, no form shown to the user */}
+  <ImgGen prompt="A sunset over mountains" />
+  ```
+
+- **Automatic Database Integration**: All images are automatically stored in Fireproof database with version history
+
+  ```jsx
+  // Custom database name
+  <ImgGen prompt="Forest landscape" database="MyCustomDB" />
+
+  // Or pass a database instance
+  <ImgGen prompt="Forest landscape" database={myDbInstance} />
+  ```
+
+### Prompt Management
+
+- **Prompt Versioning**: Tracks the history of different prompts used to generate an image
+
+  - Uses a structured `prompts` object with timestamp-based keys
+  - Maintains `currentPromptKey` to reference the active prompt
+
+- **Prompt Editing**: Users can edit prompts directly in the overlay UI
+  - Double-click the prompt text to edit
+  - Press Enter to submit and regenerate with new prompt
+  - App receives updates via `onPromptEdit` callback
+  ```jsx
+  <ImgGen
+    prompt="Initial prompt"
+    onPromptEdit={(id, newPrompt) => {
+      console.log(`Document ${id} updated with new prompt: ${newPrompt}`);
+    }}
+  />
+  ```
+
+### Image Control & Manipulation
+
+- **Image Regeneration**: One-click regeneration with the same or edited prompt
+
+  - Preserves document history and adds new versions
+  - Uses a unique `generationId` to trigger regeneration while maintaining context
+
+- **Image Quality Control**: Set quality levels for output images
+
+  ```jsx
+  <ImgGen prompt="Detailed artwork" options={{ quality: 'high' }} />
+  ```
+
+- **Image Editing with Uploads**: Process existing images with AI
+
+  ```jsx
+  <ImgGen prompt="Turn this photo into a watercolor painting" images={[myImageFile]} />
+  ```
+
+- **Multiple Image Inputs**: Combine multiple images in one generation
+  ```jsx
+  <ImgGen prompt="Create a collage of these photos" images={[photo1, photo2, photo3]} />
+  ```
+
+### User Interface Components
+
+- **Interactive Overlay**: Toggle-able information and controls overlay
+
+  - Shows prompt text (editable)
+  - Version navigation controls
+  - Regenerate/refresh button
+  - Delete button
+
+  ```jsx
+  // Disable overlay for a minimal UI
+  <ImgGen prompt="Clean interface" overlay={false} />
+  ```
+
+- **Progress Visualization**: Shows generation progress with visual indicators
+
+  - Progress bar updates in real-time
+  - Automatic placeholder display during generation
+
+- **Error Handling UI**: Clean error states with informative messages
+  ```jsx
+  <ImgGen
+    prompt="Test error handling"
+    onError={(error) => {
+      console.error('Generation failed:', error.message);
+    }}
+  />
+  ```
+
+### File Management
+
+- **File Upload Interface**: Built-in support for image uploads
+
+  - Drag-and-drop capabilities
+  - File selection dialog
+  - Preview of uploaded content
+
+- **Base64 Conversion**: Convert between base64 and File objects
+
+  ```jsx
+  import { base64ToFile } from 'use-vibes';
+
+  // Convert API response to a File object
+  const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');
+  ```
+
+## Integration Features
+
+### Event Callbacks
+
+- **Generation Lifecycle Events**: Track the complete generation process
+  ```jsx
+  <ImgGen
+    prompt="Track this generation"
+    onComplete={() => console.log('Generation complete!')}
+    onError={(error) => console.error('Generation failed:', error)}
+    onDelete={(id) => console.log(`Document ${id} deleted`)}
+    onDocumentCreated={(id) => console.log(`New document created: ${id}`)}
+  />
+  ```
 
-#### Option A: Explicit CSS link (recommended for production)
+### State Management
+
+- **Loading States**: Component handles all loading states internally
+
+  - Initial waiting state
+  - Generation in progress state
+  - Upload waiting state
+  - Display state for completed images
+  - Error state
+
+- **Document Identity Tracking**: Smart re-mounting based on document changes
+  - Uses internal `mountKey` system to ensure clean state transitions
+  - Detects identity changes through document ID, prompt, or uploaded file documents
+
+### UI Customization
+
+- **Extensive Styling Options**: Multiple ways to customize appearance
+
+  - CSS Variables for global styling
+
+  ```css
+  :root {
+    --imggen-text-color: #222;
+    --imggen-overlay-bg: rgba(245, 245, 245, 0.85);
+    --imggen-accent: #0088ff;
+    --imggen-border-radius: 4px;
+  }
+  ```
+
+  - Custom classes for component-level styling
+
+  ```jsx
+  <ImgGen
+    prompt="Styled component"
+    classes={{
+      root: 'my-custom-container',
+      image: 'rounded-xl shadow-lg',
+      overlay: 'bg-slate-800/70 text-white',
+      progress: 'h-2 bg-green-500',
+    }}
+  />
+  ```
+
+### Gallery Integration
+
+- **Thumbnail Support**: Easily create image galleries
+
+  ```jsx
+  <div className="image-grid">
+    {imageDocuments.map((doc) => (
+      <ImgGen key={doc._id} _id={doc._id} className="thumbnail" />
+    ))}
+  </div>
+  ```
+
+- **Document Reuse**: Load existing documents by ID
+  ```jsx
+  <ImgGen _id="existing-document-id" />
+  ```
+
+## Implementation Modes
+
+The ImgGen component has several operational modes that it switches between automatically:
+
+1. **Placeholder Mode**: Initial state when no prompt or document ID is provided
+2. **Upload Waiting Mode**: When files are uploaded but waiting for a prompt
+3. **Generating Mode**: During the image generation process
+4. **Display Mode**: When showing a generated image with controls
+5. **Error Mode**: When an error occurs during generation
+
+The component automatically determines which mode to use based on the current state, providing a seamless experience for both developers and end-users.
+
+## Advanced Usage
+
+### Debug Mode
+
+Enable debug mode to see detailed console logs about component state:
+
+```jsx
+<ImgGen prompt="Debug this" options={{ debug: true }} />
+```
+
+### Custom Image Sizing
+
+Control output image dimensions with the size option:
+
+```jsx
+<ImgGen
+  prompt="Landscape format"
+  options={{ size: '1536x1024' }} // Landscape
+/>
+
+<ImgGen
+  prompt="Portrait format"
+  options={{ size: '1024x1536' }} // Portrait
+/>
+```
+
+# Advanced Usage
+
+This guide covers the implementation, configuration, and best practices for using the ImgGen component from the use-vibes library.
+
+## Installation
+
+```bash
+pnpm add use-vibes
+```
+
+### CSS Setup
+
+The ImgGen component requires CSS styles. You have two options:
+
+#### Option A: Explicit CSS Link (Recommended for Production)
 
 Add a CSS link tag to your HTML:
 
@@ -20,13 +285,13 @@ Add a CSS link tag to your HTML:
 <link rel="stylesheet" href="/node_modules/use-vibes/dist/components/ImgGen.css" />
 ```
 
-Or for ESM/CDN environments like importmap scenarios:
+Or for ESM/CDN environments:
 
 ```html
-<link rel="stylesheet" href="https://esm.sh/use-vibes@0.4.11/dist/components/ImgGen.css" />
+<link rel="stylesheet" href="https://esm.sh/use-vibes@latest/dist/components/ImgGen.css" />
 ```
 
-#### Option B: Automatic CSS loading (convenient for prototyping)
+#### Option B: Automatic CSS Loading (Convenient for Prototyping)
 
 Import the style-loader early in your application:
 
@@ -34,13 +299,13 @@ Import the style-loader early in your application:
 import 'use-vibes/style-loader'; // Auto-loads CSS when imported
 ```
 
-This approach is perfect for quick prototypes but for production sites, Option A gives you better control over CSS loading order and timing.
+This approach is perfect for quick prototypes, but for production sites, Option A gives you better control over CSS loading order and timing.
 
-## Components
+## Basic Usage
 
-### ImgGen
+### Simple Image Generation
 
-A React component for generating images with AI:
+Add AI image generation to any React app with minimal code:
 
 ```jsx
 import { ImgGen } from 'use-vibes';
@@ -54,62 +319,161 @@ function MyComponent() {
 }
 ```
 
-#### Props
+### Configuration Options
+
+Configure image generation with the `options` prop:
+
+```jsx
+<ImgGen
+  prompt="A detailed cityscape"
+  options={{
+    model: 'gpt-image-1',
+    quality: 'high',
+    size: '1024x1024',
+    debug: false,
+  }}
+/>
+```
+
+### Available Props
+
+| Prop                | Type               | Description                                                             |
+| ------------------- | ------------------ | ----------------------------------------------------------------------- |
+| `prompt`            | string             | Text prompt for image generation (required unless `_id` is provided)    |
+| `_id`               | string             | Document ID to load a specific image instead of generating a new one    |
+| `className`         | string             | CSS class name for the image element                                    |
+| `alt`               | string             | Alt text for the image (defaults to prompt)                             |
+| `images`            | File[]             | Array of images to edit or combine with AI                              |
+| `options`           | object             | Configuration options (see table below)                                 |
+| `database`          | string \| Database | Database name or instance to use for storing images                     |
+| `onComplete`        | function           | Callback when image load completes successfully                         |
+| `onError`           | function           | Callback when image load fails, receives the error as parameter         |
+| `onDelete`          | function           | Callback when an image is deleted, receives the document ID             |
+| `onPromptEdit`      | function           | Callback when the prompt is edited, receives document ID and new prompt |
+| `onDocumentCreated` | function           | Callback when a new document is created via drop or file picker         |
+| `overlay`           | boolean            | Whether to show overlay controls and info button (default: `true`)      |
+| `classes`           | object             | Custom CSS classes for styling component parts                          |
+| `debug`             | boolean            | Enable debug logging                                                    |
+
+### Options Object Properties
+
+| Property  | Type    | Description                                                              |
+| --------- | ------- | ------------------------------------------------------------------------ |
+| `model`   | string  | Model to use for image generation, defaults to 'gpt-image-1'             |
+| `size`    | string  | Size of the generated image (1024x1024, 1536x1024, 1024x1536, or 'auto') |
+| `quality` | string  | Quality of the generated image (high, medium, low, or auto)              |
+| `debug`   | boolean | Enable debug logging, defaults to false                                  |
+
+## Advanced Features
+
+### Prompt Management
+
+The ImgGen component tracks the history of different prompts used to generate an image:
+
+```jsx
+<ImgGen
+  prompt="Initial prompt"
+  onPromptEdit={(id, newPrompt) => {
+    console.log(`Document ${id} updated with new prompt: ${newPrompt}`);
+  }}
+/>
+```
+
+Users can edit prompts directly by double-clicking the prompt text in the overlay UI, then pressing Enter to submit and regenerate with the new prompt.
 
-- `prompt`: Text prompt for image generation (required unless `_id` is provided)
-- `_id`: Document ID to load a specific image instead of generating a new one
-- `options` (object, optional): Configuration options for image generation
+### Image Control & Manipulation
 
-  - `model` (string, optional): Model to use for image generation, defaults to 'gpt-image-1'
-  - `size` (string, optional): Size of the generated image (Must be one of 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or 'auto' (default value) for gpt-image-1, and one of 256x256, 512x512, or 1024x1024 for dall-e-2.)
-  - `quality` (string, optional): Quality of the generated image (high, medium and low are only supported for gpt-image-1. dall-e-2 only supports standard quality. Defaults to auto.)
-  - `debug` (boolean, optional): Enable debug logging, defaults to false
+#### Image Regeneration
 
-- `className`: CSS class name for the image element (optional)
-- `alt`: Alt text for the image (defaults to prompt)
-- `overlay`: Whether to show overlay controls and info button (default: `true`)
-- `database`: Database name or instance to use for storing images (default: `'ImgGen'`)
-- `onComplete`: Callback when image load completes successfully
-- `onError`: Callback when image load fails, receives the error as parameter
-- `onDelete`: Callback when an image is deleted, receives the document ID
-- `onPromptEdit`: Callback when the prompt is edited, receives document ID and new prompt
-- `editedPrompt`: Custom prompt text to use for regeneration (overrides document prompt)
-- `generationId`: Optional ID to trigger regeneration of existing images
-- `classes`: Object containing custom CSS classes for styling component parts (see Styling section)
+The component supports one-click regeneration, preserving document history while adding new versions:
 
-#### Features
+```jsx
+// The regeneration happens internally when the user clicks the refresh button
+// or when a new prompt is submitted
+```
 
-##### Overlay Controls
+#### Image Quality Control
 
-By default, the ImgGen component shows an info button in the bottom-left corner. Clicking it reveals an overlay with:
+Set quality levels for output images:
 
-- The prompt text (double-clickable to edit)
-- Version navigation buttons (if multiple versions exist)
-- Refresh button to generate a new version
-- Delete button
+```jsx
+<ImgGen prompt="Detailed artwork" options={{ quality: 'high' }} />
+```
+
+#### Image Editing with Uploads
+
+Process existing images with AI:
+
+```jsx
+<ImgGen prompt="Turn this photo into a watercolor painting" images={[myImageFile]} />
+```
+
+#### Multiple Image Inputs
+
+Combine multiple images in one generation:
 
-Setting `overlay={false}` will hide all these controls, showing only the image.
+```jsx
+<ImgGen prompt="Create a collage of these photos" images={[photo1, photo2, photo3]} />
+```
+
+### Database Integration
+
+All images are automatically stored in a Fireproof database with version history:
+
+```jsx
+// Custom database name
+<ImgGen prompt="Forest landscape" database="MyCustomDB" />
+
+// Or pass a database instance
+<ImgGen prompt="Forest landscape" database={myDbInstance} />
+```
+
+### Event Callbacks
+
+Track the complete generation process with lifecycle events:
+
+```jsx
+<ImgGen
+  prompt="Track this generation"
+  onComplete={() => console.log('Generation complete!')}
+  onError={(error) => console.error('Generation failed:', error)}
+  onDelete={(id) => console.log(`Document ${id} deleted`)}
+  onDocumentCreated={(id) => console.log(`New document created: ${id}`)}
+/>
+```
+
+### UI Controls
+
+Toggle the information overlay and controls:
+
+```jsx
+// Disable overlay for a minimal UI
+<ImgGen prompt="Clean interface" overlay={false} />
+```
 
-##### Prompt Editing
+The overlay includes:
 
-Double-click the prompt text in the overlay to edit it. Press Enter to submit changes and regenerate the image with the new prompt.
+- Prompt text (editable)
+- Version navigation controls
+- Regenerate/refresh button
+- Delete button
 
-##### Image Regeneration
+### File Management
 
-When regenerating images, the component will:
+#### Base64 Conversion
 
-- Use the edited prompt if one has been provided (via `editedPrompt` prop, `onPromptEdit` callback, or direct editing in the UI)
-- Fall back to the original prompt from the document if no edits were made
-- Preserve versions under the same document ID to maintain history
-- Add the new image as a version to the existing document instead of creating a new one
+Convert between base64 and File objects:
 
-This allows for iterative refinement of images while maintaining version history.
+```jsx
+import { base64ToFile } from 'use-vibes';
 
-#### Styling
+// Convert API response to a File object
+const imageFile = base64ToFile(imageResponse.data[0].b64_json, 'my-image.png');
+```
 
-The ImgGen component uses CSS custom properties (variables) for styling, making it easy to customize the appearance while maintaining consistency. There are two primary ways to customize styling:
+## Styling and Customization
 
-##### 1. CSS Variables
+### CSS Variables
 
 Override the default styles by setting CSS custom properties in your CSS:
 
@@ -130,13 +494,26 @@ Override the default styles by setting CSS custom properties in your CSS:
 }
 ```
 
-##### 2. Custom Classes
+### Available CSS Variables
+
+| Variable                 | Default                    | Description                       |
+| ------------------------ | -------------------------- | --------------------------------- |
+| `--imggen-text-color`    | `#333`                     | Main text color                   |
+| `--imggen-background`    | `#333333`                  | Background color for placeholder  |
+| `--imggen-overlay-bg`    | `rgba(255, 255, 255, 0.5)` | Overlay panel background          |
+| `--imggen-accent`        | `#0066cc`                  | Accent color (progress bar, etc.) |
+| `--imggen-error-text`    | `#ff6666`                  | Error message text color          |
+| `--imggen-border-radius` | `8px`                      | Border radius for containers      |
+| `--imggen-button-bg`     | `rgba(255, 255, 255, 0.7)` | Button background color           |
+| `--imggen-font-size`     | `14px`                     | Default font size                 |
+
+### Custom Classes
 
 For more granular control, provide a `classes` object with custom CSS classes for specific component parts:
 
 ```jsx
 <ImgGen
-  prompt="A futuristic cityscape"
+  prompt="Styled component"
   classes={{
     root: 'my-custom-container',
     image: 'rounded-xl shadow-lg',
@@ -147,22 +524,7 @@ For more granular control, provide a `classes` object with custom CSS classes fo
 />
 ```
 
-The component uses these classes in addition to the default ones, allowing you to extend or override styles as needed.
-
-##### Available CSS Variables
-
-| Variable                 | Default                    | Description                       |
-| ------------------------ | -------------------------- | --------------------------------- |
-| `--imggen-text-color`    | `#333`                     | Main text color                   |
-| `--imggen-background`    | `#333333`                  | Background color for placeholder  |
-| `--imggen-overlay-bg`    | `rgba(255, 255, 255, 0.5)` | Overlay panel background          |
-| `--imggen-accent`        | `#0066cc`                  | Accent color (progress bar, etc.) |
-| `--imggen-error-text`    | `#ff6666`                  | Error message text color          |
-| `--imggen-border-radius` | `8px`                      | Border radius for containers      |
-| `--imggen-button-bg`     | `rgba(255, 255, 255, 0.7)` | Button background color           |
-| `--imggen-font-size`     | `14px`                     | Default font size                 |
-
-##### Available Class Slots
+### Available Class Slots
 
 | Class Property  | Description                      |
 | --------------- | -------------------------------- |
@@ -178,27 +540,63 @@ The component uses these classes in addition to the default ones, allowing you t
 | `prompt`        | Prompt text/input container      |
 | `deleteOverlay` | Delete confirmation dialog       |
 
-## Development
+## Gallery Implementation
 
-```bash
-# Install dependencies
-pnpm install
+### Creating an Image Gallery
+
+Easily create image galleries using document IDs:
+
+```jsx
+<div className="image-grid">
+  {imageDocuments.map((doc) => (
+    <ImgGen key={doc._id} _id={doc._id} className="thumbnail" />
+  ))}
+</div>
+```
+
+### Loading Existing Documents
 
-# Build the library
-pnpm build
+Load existing documents by ID:
 
-# Run tests
-pnpm test
+```jsx
+<ImgGen _id="existing-document-id" />
 ```
 
-### Testing Notes
+## Operation Modes
+
+The ImgGen component has several operational modes that it switches between automatically:
+
+1. **Placeholder Mode**: Initial state when no prompt or document ID is provided
+2. **Upload Waiting Mode**: When files are uploaded but waiting for a prompt
+3. **Generating Mode**: During the image generation process
+4. **Display Mode**: When showing a generated image with controls
+5. **Error Mode**: When an error occurs during generation
 
-When writing tests for components that use the image generation functionality:
+## Advanced Usage Examples
 
-- Use the provided mock implementations for `call-ai` and `use-fireproof`
-- Wrap React state updates in `act()` to prevent test warnings
-- Use `vi.useFakeTimers()` and `vi.advanceTimersByTime()` to control async behavior
-- Be aware that `imageGen` API calls need to be properly mocked
+### Debug Mode
+
+Enable debug mode to see detailed console logs about component state:
+
+```jsx
+<ImgGen prompt="Debug this" options={{ debug: true }} />
+```
+
+### Custom Image Sizing
+
+Control output image dimensions with the size option:
+
+```jsx
+<ImgGen
+  prompt="Landscape format"
+  options={{ size: '1536x1024' }} // Landscape
+/>
+
+<ImgGen
+  prompt="Portrait format"
+  options={{ size: '1024x1536' }} // Portrait
+/>
+```
 
 ### Browser Compatibility
 
@@ -206,4 +604,4 @@ This library is compatible with all modern browsers that support React 18+ and E
 
 ## License
 
-MIT
+MIT+Apache