@djangocfg/ui-tools 2.1.200 → 2.1.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.200",
+  "version": "2.1.202",
   "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.202",
+    "@djangocfg/ui-core": "^2.1.202",
     "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.202",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.200",
-    "@djangocfg/ui-core": "^2.1.200",
+    "@djangocfg/typescript-config": "^2.1.202",
+    "@djangocfg/ui-core": "^2.1.202",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/Uploader/README.md

@@ -49,7 +49,32 @@ All-in-one component with dropzone and preview list.
 />
 ```
 
-### Custom Composition
+### Standalone — custom upload handler (no UploadProvider)
+
+If you handle uploads yourself (custom API hooks, multipart POST, etc.), pass `uploadFn` instead of wrapping with `UploadProvider`. Supports drag/drop, click, and Ctrl+V paste.
+
+```tsx
+import { UploadDropzone } from '@djangocfg/ui-tools/upload';
+
+function MyUploader() {
+  const { uploadAsset } = useAssets(); // your own API hook
+
+  return (
+    <UploadDropzone
+      accept={['image', 'video']}
+      maxSizeMB={50}
+      pasteEnabled
+      uploadFn={async (files) => {
+        for (const file of files) {
+          await uploadAsset({ file, name: file.name });
+        }
+      }}
+    />
+  );
+}
+```
+
+### Custom Composition (with rpldy)
 
 ```tsx
 import {
@@ -116,11 +141,11 @@ Custom overlay:
 
 ### Components
 
-| Component | Description |
-|-----------|-------------|
-| `Uploader` | All-in-one (Provider + Dropzone + Preview) |
-| `UploadProvider` | Context provider wrapping @rpldy/uploady |
-| `UploadDropzone` | Drag-drop zone with file input |
+| Component | Needs UploadProvider | Description |
+|-----------|---------------------|-------------|
+| `Uploader` | Yes | All-in-one (Provider + Dropzone + Preview) |
+| `UploadDropzone` | **Optional** | Drag-drop zone — use `uploadFn` for standalone mode |
+| `UploadProvider` | — | Context provider wrapping @rpldy/uploady |
 | `UploadPreviewList` | List of upload items with progress |
 | `UploadPreviewItem` | Single item (thumbnail, status, actions) |
 | `UploadAddButton` | Button to add files |
@@ -132,6 +157,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 +234,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 (
@@ -298,3 +369,47 @@ export const PageDropCustomOverlay = () => (
     </UploadProvider>
   </div>
 );
+
+// Standalone — uploadFn instead of UploadProvider (custom API hooks, no rpldy)
+export const StandaloneWithUploadFn = () => {
+  const [files, setFiles] = useState<string[]>([]);
+
+  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" />
+            No <code className="text-xs bg-muted px-1 rounded">UploadProvider</code> needed.
+            Pass <code className="text-xs bg-muted px-1 rounded">uploadFn</code> to handle files yourself.
+            Drag, click, or paste (Ctrl+V).
+          </p>
+        </CardContent>
+      </Card>
+      <UploadDropzone
+        accept={['image', 'document']}
+        maxSizeMB={10}
+        pasteEnabled
+        uploadFn={(selected) => {
+          setFiles((prev) => [...prev, ...selected.map((f) => f.name)]);
+          logger.info('Custom uploadFn received: ' + selected.map((f) => f.name).join(', '));
+        }}
+        onPasteNoMatch={() => logger.info('Paste: no uploadable content found')}
+      />
+      {files.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm">Received by uploadFn</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <ul className="text-sm space-y-1">
+              {files.map((name, i) => (
+                <li key={i} className="text-muted-foreground">{name}</li>
+              ))}
+            </ul>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+};

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

@@ -6,8 +6,20 @@ 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';
 
+function useOptionalUploady(uploadFn?: (files: File[]) => void) {
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const { upload } = useUploady();
+    return uploadFn ?? upload;
+  } catch {
+    // Not inside UploadProvider — use uploadFn if provided, otherwise noop
+    return uploadFn ?? (() => {});
+  }
+}
+
 export function UploadDropzone({
   accept = ['image', 'audio', 'video', 'document'],
   multiple = true,
@@ -17,9 +29,12 @@ export function UploadDropzone({
   className,
   children,
   onFilesSelected,
+  uploadFn,
+  pasteEnabled = true,
+  onPasteNoMatch,
 }: UploadDropzoneProps) {
   const t = useT();
-  const { upload } = useUploady();
+  const upload = useOptionalUploady(uploadFn);
   const inputRef = useRef<HTMLInputElement>(null);
   const [isDragging, setIsDragging] = useState(false);
   const dragCounter = useRef(0);
@@ -69,6 +84,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/UploadPreviewItem.tsx

@@ -13,7 +13,7 @@ import {
   Skeleton,
 } from '@djangocfg/ui-core/components';
 import { useT } from '@djangocfg/i18n';
-import { formatFileSize } from '../utils';
+import { formatFileSize, truncateFilename } from '../utils';
 import type { UploadPreviewItemProps, AssetType, UploadStatus } from '../types';
 
 const ASSET_ICONS: Record<AssetType, typeof FileIcon> = {
@@ -53,6 +53,7 @@ export function UploadPreviewItem({
   }, [file.type]);
 
   const fileSize = useMemo(() => formatFileSize(file.size), [file.size]);
+  const shortName = useMemo(() => truncateFilename(file.name), [file.name]);
   const progressPercent = Math.round(progress);
 
   // Prepare visibility flags
@@ -144,11 +145,15 @@ export function UploadPreviewItem({
       <div className="flex-1 min-w-0">
         <Tooltip>
           <TooltipTrigger asChild>
-            <p className="text-sm font-medium truncate cursor-default">{file.name}</p>
+            <p className="text-sm font-medium cursor-default leading-tight">
+              {shortName}
+            </p>
           </TooltipTrigger>
-          <TooltipContent side="top" className="max-w-xs">
-            <p className="break-all">{file.name}</p>
-          </TooltipContent>
+          {shortName !== file.name && (
+            <TooltipContent side="top" className="max-w-xs">
+              <p className="break-all">{file.name}</p>
+            </TooltipContent>
+          )}
         </Tooltip>
 
         <p className="text-xs text-muted-foreground tabular-nums">{fileSize}</p>

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 {
@@ -19,6 +21,7 @@ export {
   buildAcceptString,
   formatFileSize,
   formatDuration,
+  truncateFilename,
 } from './utils';
 
 // Types

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) */
@@ -81,7 +85,18 @@ export interface UploadDropzoneProps {
   disabled?: boolean;
   className?: string;
   children?: React.ReactNode;
+  /** Called with validated files on drop/click/paste */
   onFilesSelected?: (files: File[]) => void;
+  /**
+   * Custom upload function. If provided, rpldy upload is skipped — files go only here.
+   * Use this when you handle uploads yourself (e.g. custom API hooks).
+   * Requires no UploadProvider ancestor.
+   */
+  uploadFn?: (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 {

package/src/tools/Uploader/utils/formatters.ts

@@ -1,3 +1,31 @@
+/**
+ * Middle-truncates a filename preserving the extension and a meaningful suffix.
+ *
+ * "telegram-cloud-photo-size-5-6152015652357607055-y.jpg"
+ *   → "telegram-cloud-photo-…7055-y.jpg"  (maxLength=32)
+ *
+ * Short names are returned as-is.
+ */
+export function truncateFilename(filename: string, maxLength = 32): string {
+  if (filename.length <= maxLength) return filename;
+
+  const dotIdx = filename.lastIndexOf('.');
+  const ext = dotIdx > 0 ? filename.slice(dotIdx) : '';          // ".jpg"
+  const base = dotIdx > 0 ? filename.slice(0, dotIdx) : filename; // without ext
+
+  // How many chars we can show from the start vs. end of the base
+  const available = maxLength - ext.length - 1; // 1 for '…'
+  if (available <= 2) return `…${ext}`;          // extreme edge case
+
+  const headLen = Math.ceil(available * 0.55);
+  const tailLen = available - headLen;
+
+  const head = base.slice(0, headLen);
+  const tail = tailLen > 0 ? base.slice(-tailLen) : '';
+
+  return `${head}…${tail}${ext}`;
+}
+
 export function formatFileSize(bytes: number): string {
   if (bytes === 0) return '0 B';
 

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

@@ -5,7 +5,7 @@ export {
   buildAcceptString,
 } from './assetTypes';
 
-export { formatFileSize, formatDuration } from './formatters';
+export { formatFileSize, formatDuration, truncateFilename } from './formatters';
 
 export { logger } from './logger';