@djangocfg/ui-tools 2.1.200 → 2.1.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.200",
+  "version": "2.1.201",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -78,8 +78,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.200",
-    "@djangocfg/ui-core": "^2.1.200",
+    "@djangocfg/i18n": "^2.1.201",
+    "@djangocfg/ui-core": "^2.1.201",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -112,10 +112,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.200",
+    "@djangocfg/i18n": "^2.1.201",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.200",
-    "@djangocfg/ui-core": "^2.1.200",
+    "@djangocfg/typescript-config": "^2.1.201",
+    "@djangocfg/ui-core": "^2.1.201",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/Uploader/README.md

@@ -132,6 +132,7 @@ Custom overlay:
 |------|-------------|
 | `useUploadEvents` | Subscribe to upload lifecycle events |
 | `useUploadProvider` | Access uploady context |
+| `useClipboardPaste` | Ctrl+V paste-to-upload (files, screenshots, base64, URLs) |
 | `useAbortAll` | Abort all uploads |
 | `useAbortBatch` | Abort batch by ID |
 | `useAbortItem` | Abort single item |
@@ -208,9 +209,66 @@ Use `onUploadComplete` callback to access raw response:
 />
 ```
 
+## Paste to Upload (Ctrl+V / Cmd+V)
+
+Enable clipboard paste globally via the `pasteEnabled` prop. All cases are handled automatically:
+
+| Clipboard content | What happens |
+|-------------------|-------------|
+| File(s) copied from OS | Upload directly |
+| Screenshot (PrintScreen / Cmd+Shift+4) | Detected as `image/png`, uploaded |
+| "Copy Image" from browser | Blob extracted and uploaded |
+| `data:image/png;base64,…` in text | Decoded and uploaded as File |
+| `https://…/photo.jpg` in text | Fetched and uploaded as File |
+| `<img src="…">` in HTML clipboard | src extracted, treated as URL |
+| Plain text, non-image URL | Ignored |
+
+```tsx
+// Simplest — enable on the all-in-one component
+<Uploader
+  destination="/api/upload"
+  accept={['image']}
+  pasteEnabled
+  onPasteNoMatch={() => toast.info('Nothing to upload in clipboard')}
+/>
+```
+
+```tsx
+// Enable on UploadDropzone directly
+<UploadDropzone
+  accept={['image', 'video']}
+  pasteEnabled
+  onPasteNoMatch={() => console.log('no match')}
+/>
+```
+
+```tsx
+// Use the hook standalone for custom paste zones
+import { useClipboardPaste } from '@djangocfg/ui-tools/upload';
+import { useUploadProvider } from '@djangocfg/ui-tools/upload';
+
+function MyCustomZone() {
+  const { upload } = useUploadProvider();
+
+  useClipboardPaste({
+    enabled: true,
+    acceptTypes: ['image', 'video'],  // MIME prefixes
+    maxBytes: 10 * 1024 * 1024,       // 10 MB
+    onFiles: (files) => upload(files),
+    onNoMatch: () => console.log('nothing pasteable'),
+  });
+
+  return <div>Paste here (Ctrl+V)</div>;
+}
+```
+
+> **Note:** Paste listeners skip `<input>`, `<textarea>`, and `contentEditable` elements
+> so text editing is never interrupted.
+
 ## Features
 
 - Drag & drop with visual feedback
+- Paste to upload (Ctrl+V) — files, screenshots, images, base64, URLs
 - Multiple file upload
 - Concurrent uploads (configurable)
 - Progress tracking per file

package/src/tools/Uploader/Uploader.story.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react';
 import { defineStory, useBoolean, useNumber } from '@djangocfg/playground';
 import { Card, CardContent, CardHeader, CardTitle } from '@djangocfg/ui-core/components';
-import { ImageIcon } from 'lucide-react';
+import { ImageIcon, ClipboardPaste } from 'lucide-react';
 import { Uploader } from './components/Uploader';
 import { logger } from './utils';
 import { UploadProvider } from './context';
@@ -9,6 +9,8 @@ import { UploadDropzone } from './components/UploadDropzone';
 import { UploadPreviewList } from './components/UploadPreviewList';
 import { UploadAddButton } from './components/UploadAddButton';
 import { useUploadEvents } from './hooks/useUploadEvents';
+import { useClipboardPaste } from './hooks/useClipboardPaste';
+import { useUploadProvider } from './hooks/useUploadProvider';
 import type { UploadedAsset, AssetType } from './types';
 
 export default defineStory({
@@ -226,6 +228,75 @@ export const CustomContent = () => (
   </div>
 );
 
+// Paste to upload
+export const PasteToUpload = () => {
+  const [pasteEnabled] = useBoolean('pasteEnabled', {
+    defaultValue: true,
+    label: 'Paste Enabled (Ctrl+V)',
+  });
+
+  return (
+    <div className="max-w-2xl space-y-4">
+      <Card>
+        <CardContent className="pt-4">
+          <p className="text-sm text-muted-foreground flex items-center gap-2">
+            <ClipboardPaste className="h-4 w-4" />
+            Copy an image anywhere, then press <kbd className="px-1 py-0.5 rounded bg-muted text-xs font-mono">Ctrl+V</kbd> to upload it.
+            Supports: files, screenshots, copied images, base64 URLs, remote image URLs.
+          </p>
+        </CardContent>
+      </Card>
+      <Uploader
+        destination={MOCK_DESTINATION}
+        accept={['image']}
+        pasteEnabled={pasteEnabled}
+        onPasteNoMatch={() => logger.info('Paste: no uploadable content found')}
+      />
+    </div>
+  );
+};
+
+// useClipboardPaste hook standalone
+function ClipboardPasteHookContent() {
+  const { upload } = useUploadProvider();
+  const [lastPaste, setLastPaste] = useState<string | null>(null);
+
+  useClipboardPaste({
+    enabled: true,
+    acceptTypes: ['image'],
+    onFiles: (files) => {
+      setLastPaste(`Pasted ${files.length} file(s): ${files.map((f) => f.name).join(', ')}`);
+      upload(files);
+    },
+    onNoMatch: () => setLastPaste('Paste detected but no image found in clipboard'),
+  });
+
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardContent className="pt-4 space-y-2">
+          <p className="text-sm text-muted-foreground flex items-center gap-2">
+            <ClipboardPaste className="h-4 w-4" />
+            Using <code className="text-xs bg-muted px-1 rounded">useClipboardPaste</code> hook directly — paste anywhere on the page.
+          </p>
+          {lastPaste && (
+            <p className="text-xs font-mono bg-muted rounded p-2">{lastPaste}</p>
+          )}
+        </CardContent>
+      </Card>
+      <UploadPreviewList />
+    </div>
+  );
+}
+
+export const ClipboardPasteHook = () => (
+  <div className="max-w-2xl">
+    <UploadProvider destination={{ url: MOCK_DESTINATION }}>
+      <ClipboardPasteHookContent />
+    </UploadProvider>
+  </div>
+);
+
 // Page-level drop zone
 function PageDropContent() {
   return (

package/src/tools/Uploader/components/UploadDropzone.tsx

@@ -6,6 +6,7 @@ import { Upload } from 'lucide-react';
 import { cn } from '@djangocfg/ui-core/lib';
 import { useT } from '@djangocfg/i18n';
 import { buildAcceptString, logger } from '../utils';
+import { useClipboardPaste } from '../hooks/useClipboardPaste';
 import type { UploadDropzoneProps } from '../types';
 
 export function UploadDropzone({
@@ -17,6 +18,8 @@ export function UploadDropzone({
   className,
   children,
   onFilesSelected,
+  pasteEnabled = true,
+  onPasteNoMatch,
 }: UploadDropzoneProps) {
   const t = useT();
   const { upload } = useUploady();
@@ -69,6 +72,24 @@ export function UploadDropzone({
     }
   }, [upload, maxBytes, maxSizeMB, onFilesSelected]);
 
+  // Build accept MIME types for clipboard paste (e.g. ['image', 'video'] → ['image', 'video'])
+  const pasteAcceptTypes = useMemo(
+    () => accept.map((assetType) => (assetType === 'document' ? '' : assetType)).filter(Boolean),
+    [accept],
+  );
+
+  useClipboardPaste({
+    enabled: pasteEnabled && !disabled,
+    acceptTypes: pasteAcceptTypes.length ? pasteAcceptTypes : undefined,
+    maxBytes: maxBytes,
+    onFiles: (files) => {
+      const toUpload = multiple ? files : files.slice(0, 1);
+      onFilesSelected?.(toUpload);
+      upload(toUpload);
+    },
+    onNoMatch: onPasteNoMatch,
+  });
+
   const handleDragEnter = useCallback((e: React.DragEvent) => {
     e.preventDefault();
     e.stopPropagation();

package/src/tools/Uploader/components/Uploader.tsx

@@ -12,6 +12,8 @@ interface UploaderContentProps {
   multiple?: UploaderProps['multiple'];
   compact?: UploaderProps['compact'];
   showPreview?: UploaderProps['showPreview'];
+  pasteEnabled?: UploaderProps['pasteEnabled'];
+  onPasteNoMatch?: UploaderProps['onPasteNoMatch'];
   className?: UploaderProps['className'];
   dropzoneClassName?: UploaderProps['dropzoneClassName'];
   previewClassName?: UploaderProps['previewClassName'];
@@ -24,6 +26,8 @@ function UploaderContent({
   multiple,
   compact,
   showPreview,
+  pasteEnabled,
+  onPasteNoMatch,
   className,
   dropzoneClassName,
   previewClassName,
@@ -36,6 +40,8 @@ function UploaderContent({
         maxSizeMB={maxSizeMB}
         multiple={multiple}
         compact={compact}
+        pasteEnabled={pasteEnabled}
+        onPasteNoMatch={onPasteNoMatch}
         className={dropzoneClassName}
       >
         {children}

package/src/tools/Uploader/hooks/index.ts

@@ -1,2 +1,4 @@
 export { useUploadEvents } from './useUploadEvents';
 export { useUploadProvider, useAbortAll, useAbortBatch, useAbortItem } from './useUploadProvider';
+export { useClipboardPaste } from './useClipboardPaste';
+export type { ClipboardPasteOptions } from './useClipboardPaste';

package/src/tools/Uploader/hooks/useClipboardPaste.ts

@@ -0,0 +1,205 @@
+'use client';
+
+import { useEffect, useCallback, useRef, type RefObject } from 'react';
+import { logger } from '../utils/logger';
+
+export interface ClipboardPasteOptions {
+  /** Whether paste is enabled */
+  enabled?: boolean;
+  /** Accept only these MIME type prefixes, e.g. ['image'] */
+  acceptTypes?: string[];
+  /** Max file size in bytes (optional) */
+  maxBytes?: number;
+  /** Called with resolved File objects from clipboard */
+  onFiles: (files: File[]) => void;
+  /** Called when paste happened but no suitable content found */
+  onNoMatch?: () => void;
+}
+
+/**
+ * Resolves clipboard data into File objects.
+ *
+ * Handles all real-world cases:
+ *  1. Native file(s) copied from OS (e.g. Finder, Explorer)
+ *  2. Screenshots (PrintScreen / Cmd+Shift+4) — come as image/png blob
+ *  3. Images copied from browser ("Copy Image") — image/* blob
+ *  4. Base64 data: URI in clipboard text  (data:image/png;base64,…)
+ *  5. Remote image URL in clipboard text  (https://…/img.jpg)
+ *  6. HTML with <img src="…"> — extracts first src and treats as case 4/5
+ */
+async function resolveClipboardFiles(
+  e: ClipboardEvent,
+  acceptTypes: string[],
+  maxBytes: number | undefined,
+): Promise<File[]> {
+  const cd = e.clipboardData;
+  if (!cd) return [];
+
+  // ── 1 & 2 & 3: native files / blobs ─────────────────────────────────────
+  const nativeFiles: File[] = [];
+  for (const item of Array.from(cd.items)) {
+    if (item.kind === 'file') {
+      const file = item.getAsFile();
+      if (!file) continue;
+      if (!matchesAccept(file.type, acceptTypes)) continue;
+      if (maxBytes && file.size > maxBytes) {
+        logger.warn(`Clipboard file "${file.name}" exceeds size limit`);
+        continue;
+      }
+      nativeFiles.push(file);
+    }
+  }
+  if (nativeFiles.length > 0) return nativeFiles;
+
+  // ── 4 & 5 & 6: text-based payloads ──────────────────────────────────────
+  const text = cd.getData('text/plain').trim();
+  const html = cd.getData('text/html').trim();
+
+  // 6: extract src from HTML <img>
+  const imgSrc = extractImgSrc(html);
+  const source = imgSrc || text;
+
+  if (!source) return [];
+
+  // 4: base64 data URI
+  if (source.startsWith('data:')) {
+    const file = dataUriToFile(source);
+    if (!file) return [];
+    if (!matchesAccept(file.type, acceptTypes)) return [];
+    if (maxBytes && file.size > maxBytes) {
+      logger.warn('Pasted base64 image exceeds size limit');
+      return [];
+    }
+    return [file];
+  }
+
+  // 5: remote URL
+  if (/^https?:\/\//i.test(source)) {
+    const mimeHint = guessMimeFromUrl(source);
+    if (!matchesAccept(mimeHint, acceptTypes)) return [];
+    try {
+      const file = await fetchUrlAsFile(source);
+      if (!file) return [];
+      if (!matchesAccept(file.type, acceptTypes)) return [];
+      if (maxBytes && file.size > maxBytes) {
+        logger.warn('Pasted URL image exceeds size limit');
+        return [];
+      }
+      return [file];
+    } catch (err) {
+      logger.warn('Failed to fetch pasted URL', err);
+      return [];
+    }
+  }
+
+  return [];
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function matchesAccept(mimeType: string, acceptTypes: string[]): boolean {
+  if (!acceptTypes.length) return true;
+  return acceptTypes.some((accept) => {
+    if (accept.endsWith('/*')) return mimeType.startsWith(accept.slice(0, -1));
+    return mimeType === accept || mimeType.startsWith(accept + '/');
+  });
+}
+
+function extractImgSrc(html: string): string | null {
+  if (!html) return null;
+  const match = html.match(/<img[^>]+src=["']([^"']+)["']/i);
+  return match?.[1] ?? null;
+}
+
+function dataUriToFile(dataUri: string): File | null {
+  try {
+    const [header, base64] = dataUri.split(',');
+    const mimeMatch = header.match(/data:([^;]+)/);
+    if (!mimeMatch) return null;
+    const mime = mimeMatch[1];
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    const ext = mime.split('/')[1]?.split('+')[0] ?? 'bin';
+    return new File([bytes], `paste.${ext}`, { type: mime });
+  } catch {
+    return null;
+  }
+}
+
+function guessMimeFromUrl(url: string): string {
+  const ext = url.split('?')[0].split('.').pop()?.toLowerCase() ?? '';
+  const map: Record<string, string> = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png',
+    gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml',
+    avif: 'image/avif', mp4: 'video/mp4', webm: 'video/webm',
+    mp3: 'audio/mpeg', wav: 'audio/wav', pdf: 'application/pdf',
+  };
+  return map[ext] ?? 'application/octet-stream';
+}
+
+async function fetchUrlAsFile(url: string): Promise<File | null> {
+  const resp = await fetch(url);
+  if (!resp.ok) return null;
+  const blob = await resp.blob();
+  const ext = url.split('?')[0].split('.').pop()?.toLowerCase() ?? 'bin';
+  const name = url.split('/').pop()?.split('?')[0] ?? `paste.${ext}`;
+  return new File([blob], name, { type: blob.type || guessMimeFromUrl(url) });
+}
+
+// ── hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Listens for paste events (Ctrl+V / Cmd+V) on the given element or
+ * globally on `document` and resolves clipboard content into File objects.
+ *
+ * Supports: native files, screenshots, copied images, base64 URIs, remote URLs.
+ */
+export function useClipboardPaste(
+  options: ClipboardPasteOptions,
+  elementRef?: RefObject<HTMLElement | null>,
+) {
+  const {
+    enabled = true,
+    acceptTypes = ['image'],
+    maxBytes,
+    onFiles,
+    onNoMatch,
+  } = options;
+
+  // Keep stable refs so we don't re-bind the listener on every render
+  const onFilesRef = useRef(onFiles);
+  const onNoMatchRef = useRef(onNoMatch);
+  onFilesRef.current = onFiles;
+  onNoMatchRef.current = onNoMatch;
+
+  const handlePaste = useCallback(
+    async (e: Event) => {
+      const clipEvent = e as ClipboardEvent;
+      // Don't hijack paste inside text inputs / contentEditable
+      const target = e.target as HTMLElement;
+      if (
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target.isContentEditable
+      ) return;
+
+      const files = await resolveClipboardFiles(clipEvent, acceptTypes, maxBytes);
+      if (files.length > 0) {
+        e.preventDefault();
+        onFilesRef.current(files);
+      } else {
+        onNoMatchRef.current?.();
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [acceptTypes.join(','), maxBytes],
+  );
+
+  useEffect(() => {
+    if (!enabled) return;
+    const target: EventTarget = elementRef?.current ?? document;
+    target.addEventListener('paste', handlePaste);
+    return () => target.removeEventListener('paste', handlePaste);
+  }, [enabled, elementRef, handlePaste]);
+}

package/src/tools/Uploader/index.ts

@@ -12,6 +12,8 @@ export { UploadProvider } from './context';
 // Hooks
 export { useUploadEvents } from './hooks/useUploadEvents';
 export { useUploadProvider, useAbortAll, useAbortBatch, useAbortItem } from './hooks/useUploadProvider';
+export { useClipboardPaste } from './hooks/useClipboardPaste';
+export type { ClipboardPasteOptions } from './hooks/useClipboardPaste';
 
 // Utils
 export {

package/src/tools/Uploader/types/index.ts

@@ -41,6 +41,10 @@ export interface UploaderProps {
   autoUpload?: boolean;
   /** Show preview list (default: true) */
   showPreview?: boolean;
+  /** Enable Ctrl+V / Cmd+V paste-to-upload (default: true) */
+  pasteEnabled?: boolean;
+  /** Called when paste fires but no uploadable content was found */
+  onPasteNoMatch?: () => void;
   /** Compact mode (smaller dropzone) */
   compact?: boolean;
   /** Max concurrent uploads (default: 3) */
@@ -82,6 +86,10 @@ export interface UploadDropzoneProps {
   className?: string;
   children?: React.ReactNode;
   onFilesSelected?: (files: File[]) => void;
+  /** Enable Ctrl+V / Cmd+V paste-to-upload (default: true) */
+  pasteEnabled?: boolean;
+  /** Called when paste fires but no uploadable content was found */
+  onPasteNoMatch?: () => void;
 }
 
 export interface UploadPreviewListProps {