@turnix-co/konva-editor 2.0.0

package/README.md

@@ -0,0 +1,558 @@
+# @turnix-co/konva-editor
+
+A powerful, private multi-slide canvas editor built with React, Konva, and Redux. Features drawing tools, media support, recording capabilities, and more.
+
+## 🔒 Private Package
+
+This package is **private** and only available to authorized Turnix team members via GitHub Packages.
+
+## 📦 Installation
+
+### For Team Members
+
+**Step 1:** Install the package from GitHub Packages:
+```bash
+npm install @turnix-co/konva-editor --registry=https://npm.pkg.github.com --legacy-peer-deps
+```
+
+**Step 2:** Install peer dependencies:
+```bash
+npm install konva react-konva react-konva-utils
+```
+
+**Why separate?** Konva has platform-specific code (browser vs Node.js). Installing it separately ensures Next.js correctly resolves the browser version and avoids SSR errors.
+
+### Setup Authentication
+
+Contact your team lead for authentication credentials (.npmrc file).
+
+## ⚠️ CRITICAL SETUP REQUIREMENTS
+
+**Before you start**, understand these requirements or features WON'T work:
+
+1. **Layout Container Required**: Components MUST be wrapped in a div with:
+   - `width: '100vw'` and `height: '100vh'`
+   - `display: 'flex'` and `flexDirection: 'column'`
+   - Canvas wrapper needs `flex: 1` and `position: 'relative'`
+
+2. **stageRef Required**: For video recording, you MUST:
+   - Create a `stageRef` with `useRef<Konva.Stage | null>(null)`
+   - Pass it to both `<Toolbar stageRef={stageRef} />` and `<Canvas onStageReady={...} />`
+
+3. **CSS Import Required**: Import the package's CSS in your root layout
+
+❌ **Common Mistakes** (these will break video recording):
+```tsx
+// ❌ WRONG - No layout wrapper, no stageRef
+<ReduxProvider store={store}>
+  <Toolbar />
+  <Canvas />
+  <SlideNavigation />
+</ReduxProvider>
+```
+
+✅ **Correct Setup** (see Quick Start below)
+
+## 🚀 Quick Start
+
+### 1. Import the CSS styles
+
+**IMPORTANT:** You must import the package's CSS file for components to display properly.
+
+In your root layout or main CSS file (e.g., `app/layout.tsx` or `app/globals.css`):
+
+```tsx
+// In your layout.tsx or _app.tsx
+import '@turnix-co/konva-editor/styles.css';
+```
+
+Or in your CSS file:
+```css
+@import '@turnix-co/konva-editor/styles.css';
+```
+
+### 2. Create your editor page with auto-save
+
+**IMPORTANT:** To enable IndexedDB persistence (auto-save), you must call the `useSlidesPersistence()` hook.
+
+**CRITICAL FOR VIDEO RECORDING:** You MUST wrap components in a properly styled container for video recording to work correctly!
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import {
+  Canvas,
+  Toolbar,
+  SlideNavigation,
+  ReduxProvider,
+  store,
+  useSlidesPersistence
+} from '@turnix-co/konva-editor';
+import '@turnix-co/konva-editor/styles.css';
+import type Konva from 'konva';
+
+// Wrapper component to load persisted slides
+function PersistenceLoader({ children }: { children: React.ReactNode }) {
+  useSlidesPersistence(); // ← This loads slides from IndexedDB on mount
+  return <>{children}</>;
+}
+
+export default function EditorPage() {
+  const stageRef = useRef<Konva.Stage | null>(null);
+
+  return (
+    <ReduxProvider store={store}>
+      <PersistenceLoader>
+        {/* CRITICAL: This wrapper is REQUIRED for video recording to work */}
+        <div style={{
+          width: '100vw',
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'hidden' // Prevents scrollbars
+        }}>
+          <Toolbar stageRef={stageRef} />
+
+          {/* CRITICAL: Canvas wrapper needs flex: 1 and position: relative */}
+          <div style={{ flex: 1, position: 'relative' }}>
+            <Canvas onStageReady={(ref) => { stageRef.current = ref.current; }} />
+          </div>
+
+          <SlideNavigation />
+        </div>
+      </PersistenceLoader>
+    </ReduxProvider>
+  );
+}
+```
+
+**Important:**
+- Always add `'use client'` at the top!
+- Call `useSlidesPersistence()` inside `ReduxProvider` to enable auto-save
+- **MUST** have the wrapper div with `width: '100vw'` and `height: '100vh'`
+- **MUST** pass `stageRef` to both Toolbar and Canvas for recording to work
+
+### 3. Add Publishing (Optional)
+
+The package includes **automatic data persistence via IndexedDB + Redux**:
+- ✅ **Auto-save**: Slides are automatically saved to browser storage on every change
+- ✅ **Auto-restore**: Slides are automatically loaded when the page refreshes
+- ✅ **No backend needed**: Data persists in the user's browser
+
+**How it works:**
+1. `useSlidesPersistence()` hook loads slides from IndexedDB on mount
+2. Redux middleware automatically saves changes to IndexedDB (500ms debounce)
+3. Works completely offline - no server required!
+
+If you want to publish slides to your backend:
+
+```tsx
+'use client';
+
+import { useRef } from 'react';
+import {
+  Canvas,
+  Toolbar,
+  SlideNavigation,
+  PublishButton,
+  ReduxProvider,
+  store,
+  useSlidesPersistence,
+  type PublishProgress,
+  type PublishResponse,
+  type Slide
+} from '@turnix-co/konva-editor';
+import '@turnix-co/konva-editor/styles.css';
+import type Konva from 'konva';
+
+// Wrapper component for persistence
+function PersistenceLoader({ children }: { children: React.ReactNode }) {
+  useSlidesPersistence();
+  return <>{children}</>;
+}
+
+export default function EditorPage() {
+  const stageRef = useRef<Konva.Stage | null>(null);
+
+  // Your custom publish logic
+  const handlePublish = async (
+    slides: Slide[],
+    onProgress?: (progress: PublishProgress) => void
+  ): Promise<PublishResponse> => {
+    // Update progress
+    onProgress?.({
+      current: 0,
+      total: slides.length,
+      status: 'Preparing slides...'
+    });
+
+    // Call your API endpoint
+    const response = await fetch('/api/publish', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ slides })
+    });
+
+    const data = await response.json();
+
+    onProgress?.({
+      current: slides.length,
+      total: slides.length,
+      status: 'Published successfully!'
+    });
+
+    return {
+      success: true,
+      message: 'Slides published successfully!',
+      projectId: data.id,
+      url: data.url
+    };
+  };
+
+  return (
+    <ReduxProvider store={store}>
+      <PersistenceLoader>
+        {/* CRITICAL: This wrapper is REQUIRED */}
+        <div style={{
+          width: '100vw',
+          height: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'hidden'
+        }}>
+          <Toolbar stageRef={stageRef} />
+
+          <div style={{ flex: 1, position: 'relative' }}>
+            <Canvas onStageReady={(ref) => { stageRef.current = ref.current; }} />
+          </div>
+
+          <SlideNavigation />
+
+          {/* Add PublishButton with your custom publish function */}
+          <PublishButton
+            onPublish={handlePublish}
+            label="Save to Cloud"
+          />
+        </div>
+      </PersistenceLoader>
+    </ReduxProvider>
+  );
+}
+```
+
+## 📚 Components
+
+### Core Components
+
+- **`<Canvas />`** - Main canvas component with drawing, images, videos, and text
+- **`<Toolbar />`** - Toolbar with drawing tools, colors, and actions
+- **`<SlideNavigation />`** - Multi-slide navigation and management
+- **`<ScreenRecorder />`** - Screen recording functionality
+- **`<PublishButton />`** - Customizable publish button with progress tracking
+
+### Redux Setup
+
+- **`ReduxProvider`** - Redux provider (from react-redux)
+- **`store`** - Pre-configured Redux store
+
+## 🎥 Using the Recording Feature
+
+The Toolbar component includes a built-in recording button. To enable it, you need to pass the stage reference from the Canvas component to the Toolbar:
+
+```tsx
+'use client';
+
+import { useState, useRef } from 'react';
+import {
+  Canvas,
+  Toolbar,
+  SlideNavigation,
+  ReduxProvider,
+  store,
+  type CanvasProps,
+  type ToolbarProps
+} from '@turnix-co/konva-editor';
+import Konva from 'konva';
+
+export default function EditorPage() {
+  const stageRef = useRef<Konva.Stage | null>(null);
+
+  return (
+    <ReduxProvider store={store}>
+      <div style={{ width: '100vw', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+        {/* Pass stageRef to Toolbar to enable recording */}
+        <Toolbar stageRef={stageRef} />
+
+        <div style={{ flex: 1, position: 'relative' }}>
+          {/* Canvas provides the stageRef via onStageReady callback */}
+          <Canvas
+            onStageReady={(ref) => {
+              stageRef.current = ref.current;
+            }}
+          />
+        </div>
+
+        <SlideNavigation />
+      </div>
+    </ReduxProvider>
+  );
+}
+```
+
+**Key points:**
+1. Create a `stageRef` using `useRef<Konva.Stage | null>(null)`
+2. Pass the `stageRef` to the `<Toolbar>` component
+3. Use the `onStageReady` callback on `<Canvas>` to populate the stageRef
+4. **IMPORTANT**: Wrap Canvas in a container with `flex: 1` and `position: 'relative'`
+5. **IMPORTANT**: The parent container MUST have `width: '100vw'` and `height: '100vh'` for recorded videos to display in full screen
+6. The recording button in the Toolbar will now work correctly
+
+Alternatively, you can handle recording externally:
+
+```tsx
+'use client';
+
+import { useState, useRef } from 'react';
+import {
+  Canvas,
+  Toolbar,
+  ScreenRecorder,
+  ReduxProvider,
+  store
+} from '@turnix-co/konva-editor';
+import Konva from 'konva';
+
+export default function EditorPage() {
+  const stageRef = useRef<Konva.Stage | null>(null);
+  const [showRecorder, setShowRecorder] = useState(false);
+
+  const handleRecordingComplete = (videoBlob: Blob, thumbnailDataUrl: string) => {
+    // Handle the recorded video
+    console.log('Recording completed', videoBlob);
+  };
+
+  return (
+    <ReduxProvider store={store}>
+      <div style={{ width: '100vw', height: '100vh' }}>
+        {/* Toolbar with custom recording handler */}
+        <Toolbar
+          onScreenRecord={() => setShowRecorder(true)}
+        />
+
+        <Canvas
+          onStageReady={(ref) => {
+            stageRef.current = ref.current;
+          }}
+        />
+
+        {/* External ScreenRecorder component */}
+        {showRecorder && (
+          <ScreenRecorder
+            onClose={() => setShowRecorder(false)}
+            stageRef={stageRef}
+            onRecordingComplete={handleRecordingComplete}
+          />
+        )}
+      </div>
+    </ReduxProvider>
+  );
+}
+```
+
+## 🎨 Features
+
+- ✏️ **Drawing tools** - Pen and eraser with customizable colors and sizes
+- 🖼️ **Image support** - Drag & drop, resize, rotate with context menu
+- 🎥 **Video support** - Upload and playback with thumbnail previews
+- 📝 **Text elements** - Add and edit text on canvas
+- 🎙️ **Audio recording** - Record voice notes for individual objects
+- 📹 **Screen recording** - Record entire canvas with audio
+- 📊 **Multi-slide presentations** - Create up to 20 slides
+- ↩️ **Undo/Redo** - Full history management
+- 💾 **Auto-save** - Automatic persistence with IndexedDB + Redux
+- 📤 **Export** - Export slides as images
+- 🚀 **Publishing** - Customizable publish button with progress tracking
+
+## 🔧 Advanced Usage
+
+### Custom Actions
+
+```tsx
+import { useDispatch, addImage, setTool } from '@turnix/konva-editor';
+
+function CustomControls() {
+  const dispatch = useDispatch();
+
+  const handleAddImage = () => {
+    dispatch(addImage({
+      id: 'custom-id',
+      src: 'https://example.com/image.jpg',
+      x: 100,
+      y: 100,
+      width: 200,
+      height: 200,
+    }));
+  };
+
+  return <button onClick={handleAddImage}>Add Image</button>;
+}
+```
+
+### TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { RootState, ImageElement, CanvasState } from '@turnix/konva-editor';
+```
+
+## 📖 API Reference
+
+### PublishButton Props
+
+```tsx
+interface PublishButtonProps {
+  // Custom publish function (required)
+  onPublish?: (
+    slides: Slide[],
+    onProgress?: (progress: PublishProgress) => void
+  ) => Promise<PublishResponse>;
+
+  // Custom button label (optional, default: "Publish Slides")
+  label?: string;
+
+  // Custom className for positioning/styling (optional)
+  className?: string;
+}
+
+interface PublishProgress {
+  current: number;    // Current progress (e.g., 5)
+  total: number;      // Total items (e.g., 10)
+  status: string;     // Status message (e.g., "Uploading...")
+}
+
+interface PublishResponse {
+  success: boolean;   // Whether publish succeeded
+  message: string;    // Success/error message
+  projectId?: string; // Optional: ID from your backend
+  url?: string;       // Optional: URL to published project
+}
+```
+
+**Example API Endpoint** (`app/api/publish/route.ts`):
+```tsx
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const { slides } = await request.json();
+
+  // Save to your database
+  const project = await db.project.create({
+    data: {
+      slides: JSON.stringify(slides),
+      createdAt: new Date(),
+    }
+  });
+
+  return NextResponse.json({
+    id: project.id,
+    url: `/projects/${project.id}`,
+  });
+}
+```
+
+### Redux Actions
+
+**Canvas Actions:**
+- `addImage(payload)` - Add image to canvas
+- `addVideo(payload)` - Add video to canvas
+- `addText(payload)` - Add text to canvas
+- `clearCanvas()` - Clear current slide
+- `undo()` - Undo last action
+- `redo()` - Redo undone action
+- `deleteElement(id)` - Delete element by ID
+
+**Slide Actions:**
+- `addSlide()` - Create new slide
+- `deleteSlide(id)` - Delete slide
+- `setCurrentSlide(id)` - Switch to slide
+- `duplicateSlide(id)` - Duplicate slide
+
+**Toolbar Actions:**
+- `setTool(tool)` - Set active tool ('pen' | 'eraser' | 'text')
+- `setPenColor(color)` - Set pen color
+- `setStrokeWidth(width)` - Set stroke width
+
+### Utilities
+
+- `exportSlideAsImage(slideId)` - Export slide as PNG
+- `exportSlideAsPDF(slideId)` - Export slide as PDF
+
+## 🏗️ Architecture
+
+The package uses:
+- **React 19** for UI
+- **Konva** for canvas rendering
+- **Redux Toolkit** for state management
+- **IndexedDB** for persistence
+- **TypeScript** for type safety
+
+## 🔐 Security
+
+⚠️ **This is a private package.** Do not:
+- Share authentication credentials
+- Publish package code publicly
+- Include in public repositories
+
+## 📝 License
+
+UNLICENSED - Private and proprietary software for Turnix team use only.
+
+## 🆘 Support
+
+For issues or questions, contact the Turnix development team.
+
+## 🐛 Troubleshooting
+
+### Recorded Video Not Displaying Full Screen
+
+If your recorded video doesn't display in full screen when played:
+
+1. **Check Container Styling**: Ensure the Canvas is wrapped in a container that fills the viewport:
+   ```tsx
+   <div style={{ width: '100vw', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+     <Toolbar stageRef={stageRef} />
+     <div style={{ flex: 1, position: 'relative' }}>
+       <Canvas onStageReady={(ref) => stageRef.current = ref.current} />
+     </div>
+   </div>
+   ```
+
+2. **Verify stageRef is Passed**: Make sure you're passing the `stageRef` to the Toolbar component:
+   ```tsx
+   <Toolbar stageRef={stageRef} />
+   ```
+
+3. **Check onStageReady Callback**: Ensure the Canvas component's `onStageReady` callback is properly setting the stageRef:
+   ```tsx
+   <Canvas onStageReady={(ref) => { stageRef.current = ref.current; }} />
+   ```
+
+4. **No Fixed Dimensions**: Avoid setting fixed width/height on the Canvas container. Use `flex: 1` instead to allow it to fill available space.
+
+### Download and Re-record Buttons Not Visible
+
+After recording stops, you should see a preview dialog with three buttons:
+- **Add to Canvas** - Adds the video to the canvas (clears existing content)
+- **Download** - Downloads the video file locally
+- **Re-record** - Discards the recording and starts over
+
+If you don't see these buttons, ensure you're using version `1.3.3` or later:
+```bash
+npm install @turnix-co/konva-editor@latest --registry=https://npm.pkg.github.com
+```
+
+---
+
+**Built with ❤️ by the Turnix team**