@djangocfg/ui-tools 2.1.161 → 2.1.162

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.161",
+  "version": "2.1.162",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -52,6 +52,11 @@
       "import": "./src/tools/Mermaid/index.tsx",
       "require": "./src/tools/Mermaid/index.tsx"
     },
+    "./upload": {
+      "types": "./src/tools/Uploader/index.ts",
+      "import": "./src/tools/Uploader/index.ts",
+      "require": "./src/tools/Uploader/index.ts"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
@@ -68,8 +73,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.161",
-    "@djangocfg/ui-core": "^2.1.161",
+    "@djangocfg/i18n": "^2.1.162",
+    "@djangocfg/ui-core": "^2.1.162",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -78,6 +83,7 @@
     "consola": "^3.4.2"
   },
   "dependencies": {
+    "@rpldy/uploady": "^1.8.5",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
@@ -101,10 +107,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.161",
+    "@djangocfg/i18n": "^2.1.162",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.161",
-    "@djangocfg/ui-core": "^2.1.161",
+    "@djangocfg/typescript-config": "^2.1.162",
+    "@djangocfg/ui-core": "^2.1.162",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/Uploader/README.md

@@ -0,0 +1,223 @@
+# Uploader
+
+Drag-drop file uploader built on `@rpldy/uploady` with shadcn/ui styling.
+
+## Installation
+
+```bash
+pnpm add @djangocfg/ui-tools
+```
+
+## Basic Usage
+
+```tsx
+import { Uploader } from '@djangocfg/ui-tools/upload';
+
+function MyPage() {
+  return (
+    <Uploader
+      destination="/api/upload"
+      accept={['image', 'document']}
+      maxSizeMB={10}
+      onUploadComplete={(asset) => console.log('Uploaded:', asset)}
+    />
+  );
+}
+```
+
+## Components
+
+### Uploader
+
+All-in-one component with dropzone and preview list.
+
+```tsx
+<Uploader
+  destination="/api/upload"    // Upload URL
+  accept={['image', 'video']}  // Asset types: image, audio, video, document
+  maxSizeMB={50}               // Max file size
+  multiple={true}              // Allow multiple files
+  autoUpload={true}            // Auto-upload on drop
+  showPreview={true}           // Show upload queue
+  compact={false}              // Compact dropzone mode
+  concurrent={3}               // Max concurrent uploads
+  headers={{ 'X-Token': '...' }}
+  params={{ folder: 'uploads' }}
+  onUploadComplete={(asset, rawResponse) => {}}
+  onUploadError={(error, file, rawResponse) => {}}
+  onBatchComplete={(assets) => {}}
+/>
+```
+
+### Custom Composition
+
+```tsx
+import {
+  UploadProvider,
+  UploadDropzone,
+  UploadPreviewList,
+  UploadAddButton,
+  useUploadEvents,
+} from '@djangocfg/ui-tools/upload';
+
+function CustomUploader() {
+  useUploadEvents({
+    onFileComplete: (asset, rawResponse) => saveToState(asset),
+    onError: (error, fileName, rawResponse) => toast.error(error),
+  });
+
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      <UploadDropzone accept={['image']} />
+      <UploadPreviewList />
+    </div>
+  );
+}
+
+<UploadProvider destination={{ url: '/api/upload' }}>
+  <CustomUploader />
+</UploadProvider>
+```
+
+### Page-Level Drop
+
+Enable drag-drop anywhere on the page:
+
+```tsx
+<UploadProvider
+  destination={{ url: '/api/upload' }}
+  pageDropEnabled
+  pageDropProps={{
+    accept: ['image'],
+    maxSizeMB: 10,
+  }}
+>
+  <YourApp />
+</UploadProvider>
+```
+
+Custom overlay:
+
+```tsx
+<UploadProvider
+  destination={{ url: '/api/upload' }}
+  pageDropEnabled
+  pageDropOverlay={
+    <div className="p-12 bg-primary/10 rounded-xl border-dashed border-2">
+      <p className="text-xl">Drop files here!</p>
+    </div>
+  }
+>
+  <YourApp />
+</UploadProvider>
+```
+
+## Exports
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `Uploader` | All-in-one (Provider + Dropzone + Preview) |
+| `UploadProvider` | Context provider wrapping @rpldy/uploady |
+| `UploadDropzone` | Drag-drop zone with file input |
+| `UploadPreviewList` | List of upload items with progress |
+| `UploadPreviewItem` | Single item (thumbnail, status, actions) |
+| `UploadAddButton` | Button to add files |
+| `UploadPageDropOverlay` | Full-page drop overlay |
+
+### Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useUploadEvents` | Subscribe to upload lifecycle events |
+| `useUploadProvider` | Access uploady context |
+| `useAbortAll` | Abort all uploads |
+| `useAbortBatch` | Abort batch by ID |
+| `useAbortItem` | Abort single item |
+
+### Utils
+
+| Function | Description |
+|----------|-------------|
+| `getAssetTypeFromMime(mime)` | Get asset type from MIME |
+| `buildAcceptString(types)` | Build accept string for input |
+| `formatFileSize(bytes)` | Format bytes to human readable |
+| `formatDuration(seconds)` | Format seconds to mm:ss |
+
+### Types
+
+```ts
+type AssetType = 'image' | 'audio' | 'video' | 'document';
+
+type UploadStatus = 'pending' | 'uploading' | 'complete' | 'error' | 'aborted';
+
+interface UploadedAsset {
+  id: string;
+  name: string;
+  type: AssetType;
+  url: string;
+  thumbnailUrl?: string;
+  size: number;
+  mimeType: string;
+  duration?: number;
+}
+
+interface UploadItem {
+  id: string;
+  file: File;
+  status: UploadStatus;
+  progress: number;
+  previewUrl?: string;
+  asset?: UploadedAsset;
+  error?: string;
+}
+```
+
+## Server Response
+
+Expected response format:
+
+```json
+{
+  "id": "abc123",
+  "url": "https://cdn.example.com/file.jpg",
+  "thumbnail_url": "https://cdn.example.com/file_thumb.jpg",
+  "duration": 120
+}
+```
+
+Also supports: `uuid`, `file`, `file_url`, `thumbnail`, `thumb_url`, `preview_url`.
+
+### Custom Response Handling
+
+Use `onUploadComplete` callback to access raw response:
+
+```tsx
+<Uploader
+  destination="/api/upload"
+  onUploadComplete={(asset, rawResponse) => {
+    // asset - parsed asset with defaults
+    // rawResponse - original API response for custom handling
+    console.log('Custom field:', rawResponse.my_custom_field);
+  }}
+  onUploadError={(error, file, rawResponse) => {
+    // error - parsed error message
+    // rawResponse - original error response for custom handling
+  }}
+/>
+```
+
+## Features
+
+- Drag & drop with visual feedback
+- Multiple file upload
+- Concurrent uploads (configurable)
+- Progress tracking per file
+- Image preview thumbnails
+- File type validation
+- Size validation
+- Abort/cancel uploads
+- Page-level drop zone
+- Tooltips for long filenames
+- Error handling with retry

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

@@ -0,0 +1,300 @@
+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 { Uploader } from './components/Uploader';
+import { logger } from './utils';
+import { UploadProvider } from './context';
+import { UploadDropzone } from './components/UploadDropzone';
+import { UploadPreviewList } from './components/UploadPreviewList';
+import { UploadAddButton } from './components/UploadAddButton';
+import { useUploadEvents } from './hooks/useUploadEvents';
+import type { UploadedAsset, AssetType } from './types';
+
+export default defineStory({
+  title: 'Tools/Uploader',
+  component: Uploader,
+  description: 'Drag-drop file uploader with progress tracking and preview.',
+});
+
+// Mock upload endpoint that simulates server response
+const MOCK_DESTINATION = 'https://httpbin.org/post';
+
+export const Interactive = () => {
+  const [compact] = useBoolean('compact', {
+    defaultValue: false,
+    label: 'Compact Mode',
+  });
+
+  const [showPreview] = useBoolean('showPreview', {
+    defaultValue: true,
+    label: 'Show Preview',
+  });
+
+  const [multiple] = useBoolean('multiple', {
+    defaultValue: true,
+    label: 'Multiple Files',
+  });
+
+  const [maxSizeMB] = useNumber('maxSizeMB', {
+    defaultValue: 10,
+    min: 1,
+    max: 100,
+    label: 'Max Size (MB)',
+  });
+
+  const [concurrent] = useNumber('concurrent', {
+    defaultValue: 3,
+    min: 1,
+    max: 10,
+    label: 'Concurrent Uploads',
+  });
+
+  const [uploadedFiles, setUploadedFiles] = useState<string[]>([]);
+
+  return (
+    <div className="max-w-2xl space-y-4">
+      <Uploader
+        destination={MOCK_DESTINATION}
+        compact={compact}
+        showPreview={showPreview}
+        multiple={multiple}
+        maxSizeMB={maxSizeMB}
+        concurrent={concurrent}
+        accept={['image', 'document']}
+        onUploadComplete={(asset) => {
+          setUploadedFiles((prev) => [...prev, asset.name]);
+        }}
+      />
+
+      {uploadedFiles.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm">Uploaded Files</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <ul className="text-sm space-y-1">
+              {uploadedFiles.map((name, i) => (
+                <li key={i} className="text-muted-foreground">
+                  {name}
+                </li>
+              ))}
+            </ul>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+};
+
+export const Default = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      accept={['image', 'video', 'document']}
+    />
+  </div>
+);
+
+export const ImagesOnly = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      accept={['image']}
+      maxSizeMB={5}
+    />
+  </div>
+);
+
+export const Compact = () => (
+  <div className="max-w-md">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      compact
+      accept={['image', 'document']}
+    />
+  </div>
+);
+
+export const NoPreview = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      showPreview={false}
+      accept={['image', 'document']}
+    />
+  </div>
+);
+
+export const SingleFile = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      multiple={false}
+      accept={['image']}
+    />
+  </div>
+);
+
+// Custom composition example
+function CustomUploaderContent() {
+  const [assets, setAssets] = useState<UploadedAsset[]>([]);
+
+  useUploadEvents({
+    onFileComplete: (asset) => {
+      setAssets((prev) => [...prev, asset]);
+    },
+    onError: (error, fileName) => {
+      logger.error(`Error uploading ${fileName}: ${error}`);
+    },
+  });
+
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      <div>
+        <h3 className="text-sm font-medium mb-2">Drop Zone</h3>
+        <UploadDropzone accept={['image']} />
+      </div>
+      <div>
+        <h3 className="text-sm font-medium mb-2">Upload Queue</h3>
+        <UploadPreviewList />
+      </div>
+    </div>
+  );
+}
+
+export const CustomComposition = () => (
+  <div className="max-w-3xl">
+    <UploadProvider destination={{ url: MOCK_DESTINATION }}>
+      <CustomUploaderContent />
+    </UploadProvider>
+  </div>
+);
+
+// With add button
+function WithAddButtonContent() {
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <UploadAddButton accept={['image', 'document']} />
+        <span className="text-sm text-muted-foreground">
+          Click to add files
+        </span>
+      </div>
+      <UploadPreviewList />
+    </div>
+  );
+}
+
+export const WithAddButton = () => (
+  <div className="max-w-2xl">
+    <UploadProvider destination={{ url: MOCK_DESTINATION }}>
+      <WithAddButtonContent />
+    </UploadProvider>
+  </div>
+);
+
+export const DocumentsOnly = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      accept={['document']}
+      maxSizeMB={20}
+    >
+      <div className="text-center">
+        <p className="text-muted-foreground">Drop PDF, DOC, or XLS files</p>
+        <p className="text-xs text-muted-foreground/60 mt-1">
+          Max 20MB per file
+        </p>
+      </div>
+    </Uploader>
+  </div>
+);
+
+export const CustomContent = () => (
+  <div className="max-w-2xl">
+    <Uploader
+      destination={MOCK_DESTINATION}
+      accept={['image']}
+      compact
+    >
+      <div className="flex items-center gap-2">
+        <span className="text-2xl">+</span>
+        <span className="text-sm">Add images</span>
+      </div>
+    </Uploader>
+  </div>
+);
+
+// Page-level drop zone
+function PageDropContent() {
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm">Page Drop Enabled</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm text-muted-foreground mb-4">
+            Drag files anywhere on the page to upload. An overlay will appear when dragging.
+          </p>
+          <UploadPreviewList />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export const PageDrop = () => (
+  <div className="max-w-2xl">
+    <UploadProvider
+      destination={{ url: MOCK_DESTINATION }}
+      pageDropEnabled
+      pageDropProps={{
+        accept: ['image', 'document'],
+        maxSizeMB: 10,
+      }}
+    >
+      <PageDropContent />
+    </UploadProvider>
+  </div>
+);
+
+// Page drop with custom overlay
+function PageDropCustomOverlayContent() {
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm">Custom Page Drop Overlay</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm text-muted-foreground mb-4">
+            This example uses a custom overlay design.
+          </p>
+          <UploadPreviewList />
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export const PageDropCustomOverlay = () => (
+  <div className="max-w-2xl">
+    <UploadProvider
+      destination={{ url: MOCK_DESTINATION }}
+      pageDropEnabled
+      pageDropProps={{
+        accept: ['image'],
+      }}
+      pageDropOverlay={
+        <div className="text-center p-12 bg-primary/10 rounded-2xl border-4 border-dashed border-primary">
+          <ImageIcon className="h-16 w-16 text-primary mx-auto mb-4" />
+          <p className="text-xl font-bold text-primary">Drop your images here!</p>
+        </div>
+      }
+    >
+      <PageDropCustomOverlayContent />
+    </UploadProvider>
+  </div>
+);

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

@@ -0,0 +1,92 @@
+'use client';
+
+import { useCallback, useRef, useMemo } from 'react';
+import { useUploady } from '@rpldy/uploady';
+import { Plus } from 'lucide-react';
+import { Button } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { buildAcceptString, logger } from '../utils';
+import type { AssetType } from '../types';
+
+interface UploadAddButtonProps {
+  accept?: AssetType[];
+  multiple?: boolean;
+  maxSizeMB?: number;
+  disabled?: boolean;
+  className?: string;
+  variant?: 'default' | 'outline' | 'ghost' | 'secondary';
+  size?: 'default' | 'sm' | 'lg' | 'icon';
+  children?: React.ReactNode;
+}
+
+export function UploadAddButton({
+  accept = ['image', 'audio', 'video', 'document'],
+  multiple = true,
+  maxSizeMB = 100,
+  disabled = false,
+  className,
+  variant = 'outline',
+  size = 'default',
+  children,
+}: UploadAddButtonProps) {
+  const { upload } = useUploady();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const acceptString = useMemo(() => buildAcceptString(accept), [accept]);
+
+  const handleFiles = useCallback((files: FileList | File[]) => {
+    const fileArray = Array.from(files);
+    const maxBytes = maxSizeMB * 1024 * 1024;
+
+    const validFiles = fileArray.filter(file => {
+      if (file.size > maxBytes) {
+        logger.warn(`File ${file.name} exceeds max size of ${maxSizeMB}MB`);
+        return false;
+      }
+      return true;
+    });
+
+    if (validFiles.length > 0) {
+      upload(validFiles);
+    }
+  }, [upload, maxSizeMB]);
+
+  const handleClick = useCallback(() => {
+    inputRef.current?.click();
+  }, []);
+
+  const handleInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    if (e.target.files?.length) {
+      handleFiles(e.target.files);
+    }
+    e.target.value = '';
+  }, [handleFiles]);
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={acceptString}
+        multiple={multiple}
+        onChange={handleInputChange}
+        className="hidden"
+        disabled={disabled}
+      />
+      <Button
+        variant={variant}
+        size={size}
+        disabled={disabled}
+        onClick={handleClick}
+        className={cn(className)}
+      >
+        {children || (
+          <>
+            <Plus className="h-4 w-4 mr-2" />
+            Add Files
+          </>
+        )}
+      </Button>
+    </>
+  );
+}