use-vibes 0.0.6-dev-ci-test

package/README.md

@@ -0,0 +1,604 @@
+# use-vibes
+
+A lightweight library that transforms any DOM element into an AI-powered micro-app.
+
+## Installation
+
+```bash
+pnpm add use-vibes
+```
+
+## Basic Usage
+
+```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}`)}
+  />
+  ```
+
+### 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:
+
+```html
+<link rel="stylesheet" href="/node_modules/use-vibes/dist/components/ImgGen.css" />
+```
+
+Or for ESM/CDN environments:
+
+```html
+<link rel="stylesheet" href="https://esm.sh/use-vibes@latest/dist/components/ImgGen.css" />
+```
+
+#### Option B: Automatic CSS Loading (Convenient for Prototyping)
+
+Import the style-loader early in your application:
+
+```js
+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.
+
+## Basic Usage
+
+### Simple Image Generation
+
+Add AI image generation to any React app with minimal code:
+
+```jsx
+import { ImgGen } from 'use-vibes';
+
+function MyComponent() {
+  return (
+    <div>
+      <ImgGen prompt="A sunset over mountains" />
+    </div>
+  );
+}
+```
+
+### 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.
+
+### Image Control & Manipulation
+
+#### Image Regeneration
+
+The component supports one-click regeneration, preserving document history while adding new versions:
+
+```jsx
+// The regeneration happens internally when the user clicks the refresh button
+// or when a new prompt is submitted
+```
+
+#### 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]} />
+```
+
+### 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} />
+```
+
+The overlay includes:
+
+- Prompt text (editable)
+- Version navigation controls
+- Regenerate/refresh button
+- Delete button
+
+### File Management
+
+#### 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');
+```
+
+## Styling and Customization
+
+### CSS Variables
+
+Override the default styles by setting CSS custom properties in your CSS:
+
+```css
+/* In your CSS file */
+:root {
+  --imggen-text-color: #222;
+  --imggen-overlay-bg: rgba(245, 245, 245, 0.85);
+  --imggen-accent: #0088ff;
+  --imggen-border-radius: 4px;
+}
+
+/* Dark theme example */
+.dark-theme {
+  --imggen-text-color: #f0f0f0;
+  --imggen-overlay-bg: rgba(25, 25, 25, 0.85);
+  --imggen-accent: #66b2ff;
+}
+```
+
+### 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="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',
+    button: 'hover:bg-blue-600',
+  }}
+/>
+```
+
+### Available Class Slots
+
+| Class Property  | Description                      |
+| --------------- | -------------------------------- |
+| `root`          | Main container element           |
+| `image`         | The image element                |
+| `container`     | Container for image and controls |
+| `overlay`       | Overlay panel with controls      |
+| `progress`      | Progress indicator               |
+| `placeholder`   | Placeholder shown during loading |
+| `error`         | Error message container          |
+| `controls`      | Control buttons container        |
+| `button`        | Individual buttons               |
+| `prompt`        | Prompt text/input container      |
+| `deleteOverlay` | Delete confirmation dialog       |
+
+## Gallery Implementation
+
+### 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
+
+Load existing documents by ID:
+
+```jsx
+<ImgGen _id="existing-document-id" />
+```
+
+## 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
+
+## Advanced Usage Examples
+
+### 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
+
+This library is compatible with all modern browsers that support React 18+ and ES6 features.
+
+## License
+
+MIT+Apache

package/components/ControlsBar.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { ImgGenClasses } from '../utils/style-utils.js';
+interface ControlsBarProps {
+    readonly handleDeleteConfirm: () => void;
+    readonly handlePrevVersion: () => void;
+    readonly handleNextVersion: () => void;
+    readonly handleRegen: () => void;
+    readonly versionIndex: number;
+    readonly totalVersions: number;
+    readonly classes?: Partial<ImgGenClasses>;
+    readonly showControls?: boolean;
+    readonly editedPrompt: string | null;
+    readonly promptText: string;
+    readonly progress?: number;
+    readonly showDelete?: boolean;
+    readonly versionFlash?: boolean;
+    readonly isRegenerating?: boolean;
+}
+export declare function ControlsBar({ handleDeleteConfirm, handlePrevVersion, handleNextVersion, handleRegen, versionIndex, totalVersions, classes, showControls, editedPrompt, promptText, progress, showDelete, versionFlash, isRegenerating }: ControlsBarProps): React.JSX.Element;
+export {};

package/components/ControlsBar.js

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import { combineClasses, defaultClasses } from '../utils/style-utils.js';
+import { logDebug } from '../utils/debug.js';
+export function ControlsBar({ handleDeleteConfirm, handlePrevVersion, handleNextVersion, handleRegen, versionIndex, totalVersions, classes = defaultClasses, showControls = true, editedPrompt, promptText, progress = 100, showDelete = true, versionFlash = false, isRegenerating = false, }) {
+    const [showConfirmation, setShowConfirmation] = React.useState(false);
+    const cancelTimerRef = React.useRef(null);
+    const isConfirming = showConfirmation;
+    const onDeleteClick = () => {
+        if (isConfirming) {
+            logDebug('ControlsBar: Delete confirmed, calling handleDeleteConfirm');
+            handleDeleteConfirm();
+            setShowConfirmation(false);
+            if (cancelTimerRef.current) {
+                window.clearTimeout(cancelTimerRef.current);
+                cancelTimerRef.current = null;
+            }
+        }
+        else {
+            logDebug('ControlsBar: Showing delete confirmation');
+            setShowConfirmation(true);
+            cancelTimerRef.current = window.setTimeout(() => {
+                setShowConfirmation(false);
+            }, 6500);
+        }
+    };
+    React.useEffect(() => {
+        return () => {
+            if (cancelTimerRef.current) {
+                window.clearTimeout(cancelTimerRef.current);
+            }
+        };
+    }, []);
+    return (React.createElement(React.Fragment, null, progress < 100 && (React.createElement("div", { className: "imggen-progress", style: {
+            width: `${progress}%`,
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            height: 'var(--imggen-progress-height)',
+            zIndex: 20,
+        } })), React.createElement("div", { className: combineClasses('imggen-controls', classes.controls) }, showControls ? (React.createElement(React.Fragment, null, React.createElement("div", { style: { display: 'flex', gap: '6px', alignItems: 'center', flex: 1 } }, showDelete && (React.createElement("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' } }, React.createElement("button", { "aria-label": "Delete image", onClick: onDeleteClick, className: combineClasses('imggen-button imggen-delete-button', classes.button), style: {
+            position: 'static',
+            width: 'var(--imggen-button-size)',
+            height: 'var(--imggen-button-size)',
+            backgroundColor: isConfirming ? 'var(--imggen-error-border)' : undefined,
+            color: isConfirming ? 'white' : undefined,
+            opacity: isConfirming ? 1 : undefined,
+        } }), isConfirming && (React.createElement("div", { className: "fade-transition", style: { animationDelay: '6s' } }, React.createElement("button", { onClick: () => {
+            handleDeleteConfirm();
+            setShowConfirmation(false);
+        }, "aria-label": "Confirm delete", style: {
+            fontSize: 'var(--imggen-font-size)',
+            fontWeight: 'bold',
+            whiteSpace: 'nowrap',
+            border: '1px solid var(--imggen-error-border, #ff3333)',
+            background: 'var(--imggen-error-border, #ff3333)',
+            color: 'white',
+            borderRadius: '4px',
+            cursor: 'pointer',
+            padding: '2px 8px',
+        } }, "Delete image"), React.createElement("button", { onClick: () => {
+            logDebug('ControlsBar: Delete canceled');
+            setShowConfirmation(false);
+            if (cancelTimerRef.current) {
+                window.clearTimeout(cancelTimerRef.current);
+            }
+        }, "aria-label": "Cancel delete", style: {
+            fontSize: 'var(--imggen-font-size)',
+            whiteSpace: 'nowrap',
+            border: 'none',
+            background: 'none',
+            color: 'var(--imggen-font-color)',
+            cursor: 'pointer',
+            padding: '0 4px',
+        } }, "Cance")))))), React.createElement("div", { className: "imggen-control-group" }, totalVersions > 1 && (React.createElement("button", { "aria-label": "Previous version", disabled: versionIndex === 0, onClick: handlePrevVersion, className: combineClasses('imggen-button', classes.button) }, "\u25C0")), totalVersions > 1 && (React.createElement("span", { className: `imggen-version-indicator version-indicator ${versionFlash ? 'imggen-version-flash' : ''}`, "aria-live": "polite" }, versionIndex + 1, " / ", totalVersions)), totalVersions > 1 && (React.createElement("button", { "aria-label": "Next version", disabled: versionIndex >= totalVersions - 1, onClick: handleNextVersion, className: combineClasses('imggen-button', classes.button) }, "\u25B6")), React.createElement("button", { "aria-label": "Regenerate image", onClick: () => {
+            handleRegen();
+        }, disabled: isRegenerating, className: combineClasses('imggen-button', classes.button, editedPrompt !== null && editedPrompt.trim() !== promptText
+            ? 'imggen-button-highlight'
+            : '', isRegenerating ? 'imggen-button-disabled' : '') }, React.createElement("span", { className: isRegenerating ? 'imggen-regen-spinning' : '' }, "\u27F3"))))) : progress < 100 ? (React.createElement("div", { className: "imggen-status-text" }, "Generating...")) : null)));
+}
+//# sourceMappingURL=ControlsBar.js.map