helix-lang 11.0.0

package/library/file-upload/components/upload/DropZone.tsx

@@ -0,0 +1,268 @@
+'use client';
+
+import { useState, useRef, useCallback, type DragEvent, type ChangeEvent } from 'react';
+import FilePreview from './FilePreview';
+import UploadProgress from './UploadProgress';
+
+interface UploadedFile {
+    file: File;
+    previewUrl?: string;
+    progress: number;
+    status: 'pending' | 'uploading' | 'complete' | 'error';
+    error?: string;
+}
+
+interface DropZoneProps {
+    endpoint?: string;
+    maxFileSize?: number;
+    maxFiles?: number;
+    allowedTypes?: string[];
+    onUploadComplete?: (files: { name: string; url: string }[]) => void;
+    onError?: (error: string) => void;
+}
+
+export default function DropZone({
+    endpoint = '/api/upload',
+    maxFileSize = 10 * 1024 * 1024,
+    maxFiles = 5,
+    allowedTypes,
+    onUploadComplete,
+    onError,
+}: DropZoneProps) {
+    const [files, setFiles] = useState<UploadedFile[]>([]);
+    const [isDragOver, setIsDragOver] = useState(false);
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const validateFile = useCallback(
+        (file: File): string | null => {
+            if (file.size > maxFileSize) {
+                return `File too large. Max size: ${(maxFileSize / 1024 / 1024).toFixed(0)}MB`;
+            }
+            if (allowedTypes && allowedTypes.length > 0) {
+                const ext = file.name.split('.').pop()?.toLowerCase() || '';
+                const typeMatch = allowedTypes.some(
+                    (t) => file.type === t || `.${ext}` === t || t === `${file.type.split('/')[0]}/*`
+                );
+                if (!typeMatch) {
+                    return `File type not allowed. Accepted: ${allowedTypes.join(', ')}`;
+                }
+            }
+            return null;
+        },
+        [maxFileSize, allowedTypes]
+    );
+
+    const addFiles = useCallback(
+        (newFiles: FileList | File[]) => {
+            const fileArray = Array.from(newFiles);
+            const remaining = maxFiles - files.length;
+
+            if (remaining <= 0) {
+                onError?.(`Maximum ${maxFiles} files allowed`);
+                return;
+            }
+
+            const toAdd = fileArray.slice(0, remaining);
+            const uploadFiles: UploadedFile[] = [];
+
+            for (const file of toAdd) {
+                const error = validateFile(file);
+                if (error) {
+                    onError?.(error);
+                    continue;
+                }
+
+                const previewUrl = file.type.startsWith('image/')
+                    ? URL.createObjectURL(file)
+                    : undefined;
+
+                uploadFiles.push({
+                    file,
+                    previewUrl,
+                    progress: 0,
+                    status: 'pending',
+                });
+            }
+
+            setFiles((prev) => [...prev, ...uploadFiles]);
+
+            // Auto-upload each file
+            uploadFiles.forEach((uf) => {
+                uploadFile(uf);
+            });
+        },
+        [files.length, maxFiles, validateFile, onError]
+    );
+
+    const uploadFile = async (uploadedFile: UploadedFile) => {
+        const formData = new FormData();
+        formData.append('file', uploadedFile.file);
+
+        setFiles((prev) =>
+            prev.map((f) =>
+                f.file === uploadedFile.file ? { ...f, status: 'uploading' as const, progress: 0 } : f
+            )
+        );
+
+        try {
+            const xhr = new XMLHttpRequest();
+
+            xhr.upload.addEventListener('progress', (e) => {
+                if (e.lengthComputable) {
+                    const pct = Math.round((e.loaded / e.total) * 100);
+                    setFiles((prev) =>
+                        prev.map((f) =>
+                            f.file === uploadedFile.file ? { ...f, progress: pct } : f
+                        )
+                    );
+                }
+            });
+
+            await new Promise<void>((resolve, reject) => {
+                xhr.addEventListener('load', () => {
+                    if (xhr.status >= 200 && xhr.status < 300) {
+                        const response = JSON.parse(xhr.responseText);
+                        setFiles((prev) =>
+                            prev.map((f) =>
+                                f.file === uploadedFile.file
+                                    ? { ...f, status: 'complete' as const, progress: 100 }
+                                    : f
+                            )
+                        );
+                        onUploadComplete?.([{ name: uploadedFile.file.name, url: response.url || '' }]);
+                        resolve();
+                    } else {
+                        reject(new Error(`Upload failed: ${xhr.statusText}`));
+                    }
+                });
+
+                xhr.addEventListener('error', () => reject(new Error('Network error')));
+                xhr.open('POST', endpoint);
+                xhr.send(formData);
+            });
+        } catch (err: unknown) {
+            const msg = err instanceof Error ? err.message : 'Upload failed';
+            setFiles((prev) =>
+                prev.map((f) =>
+                    f.file === uploadedFile.file
+                        ? { ...f, status: 'error' as const, error: msg }
+                        : f
+                )
+            );
+        }
+    };
+
+    const removeFile = (index: number) => {
+        setFiles((prev) => {
+            const file = prev[index];
+            if (file.previewUrl) URL.revokeObjectURL(file.previewUrl);
+            return prev.filter((_, i) => i !== index);
+        });
+    };
+
+    const handleDrop = (e: DragEvent) => {
+        e.preventDefault();
+        setIsDragOver(false);
+        if (e.dataTransfer.files.length > 0) {
+            addFiles(e.dataTransfer.files);
+        }
+    };
+
+    const handleDragOver = (e: DragEvent) => {
+        e.preventDefault();
+        setIsDragOver(true);
+    };
+
+    const handleDragLeave = (e: DragEvent) => {
+        e.preventDefault();
+        setIsDragOver(false);
+    };
+
+    const handleInputChange = (e: ChangeEvent<HTMLInputElement>) => {
+        if (e.target.files && e.target.files.length > 0) {
+            addFiles(e.target.files);
+            e.target.value = '';
+        }
+    };
+
+    return (
+        <div className="space-y-4">
+            {/* Drop zone */}
+            <div
+                onDrop={handleDrop}
+                onDragOver={handleDragOver}
+                onDragLeave={handleDragLeave}
+                onClick={() => inputRef.current?.click()}
+                className={`relative cursor-pointer border-2 border-dashed rounded-2xl p-8 text-center transition-all ${
+                    isDragOver
+                        ? 'border-cyan-500 bg-cyan-500/5'
+                        : 'border-white/10 bg-white/[0.02] hover:border-white/20 hover:bg-white/[0.04]'
+                }`}
+            >
+                <input
+                    ref={inputRef}
+                    type="file"
+                    multiple={maxFiles > 1}
+                    accept={allowedTypes?.join(',')}
+                    onChange={handleInputChange}
+                    className="hidden"
+                />
+
+                <div className="flex flex-col items-center gap-3">
+                    <div className={`p-3 rounded-xl transition-colors ${isDragOver ? 'bg-cyan-500/10' : 'bg-white/5'}`}>
+                        <svg
+                            className={`w-8 h-8 ${isDragOver ? 'text-cyan-400' : 'text-white/30'}`}
+                            fill="none"
+                            viewBox="0 0 24 24"
+                            stroke="currentColor"
+                            strokeWidth={1.5}
+                        >
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5" />
+                        </svg>
+                    </div>
+                    <div>
+                        <p className="text-sm text-white/70">
+                            <span className="text-cyan-400 font-medium">Click to upload</span> or drag and drop
+                        </p>
+                        <p className="text-xs text-white/30 mt-1">
+                            Max {maxFiles} file{maxFiles > 1 ? 's' : ''}, up to {(maxFileSize / 1024 / 1024).toFixed(0)}MB each
+                        </p>
+                    </div>
+                </div>
+            </div>
+
+            {/* File previews */}
+            {files.some((f) => f.status === 'pending' || f.previewUrl) && (
+                <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3">
+                    {files.map((f, i) => (
+                        <FilePreview
+                            key={`${f.file.name}-${i}`}
+                            file={f.file}
+                            previewUrl={f.previewUrl}
+                            onRemove={() => removeFile(i)}
+                        />
+                    ))}
+                </div>
+            )}
+
+            {/* Upload progress */}
+            {files.some((f) => f.status !== 'pending') && (
+                <div className="space-y-2">
+                    {files
+                        .filter((f) => f.status !== 'pending')
+                        .map((f, i) => (
+                            <UploadProgress
+                                key={`progress-${f.file.name}-${i}`}
+                                filename={f.file.name}
+                                progress={f.progress}
+                                status={f.status === 'pending' ? 'uploading' : f.status}
+                                error={f.error}
+                                onCancel={() => removeFile(files.indexOf(f))}
+                                onRetry={() => uploadFile(f)}
+                            />
+                        ))}
+                </div>
+            )}
+        </div>
+    );
+}

package/library/file-upload/components/upload/FilePreview.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+interface FilePreviewProps {
+    file: File;
+    previewUrl?: string;
+    onRemove?: () => void;
+}
+
+function formatFileSize(bytes: number): string {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+
+function getFileIcon(type: string): string {
+    if (type.startsWith('image/')) return 'image';
+    if (type === 'application/pdf') return 'pdf';
+    if (type.includes('spreadsheet') || type.includes('csv')) return 'spreadsheet';
+    if (type.includes('document') || type.includes('word')) return 'document';
+    return 'file';
+}
+
+export default function FilePreview({ file, previewUrl, onRemove }: FilePreviewProps) {
+    const fileType = getFileIcon(file.type);
+    const isImage = file.type.startsWith('image/');
+
+    return (
+        <div className="relative group backdrop-blur-xl bg-white/5 border border-white/10 rounded-xl overflow-hidden">
+            {/* Preview area */}
+            <div className="aspect-square flex items-center justify-center bg-white/[0.02]">
+                {isImage && previewUrl ? (
+                    <img
+                        src={previewUrl}
+                        alt={file.name}
+                        className="w-full h-full object-cover"
+                    />
+                ) : (
+                    <div className="flex flex-col items-center gap-2 p-4">
+                        {fileType === 'pdf' && (
+                            <svg className="w-10 h-10 text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                                <path strokeLinecap="round" strokeLinejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" />
+                            </svg>
+                        )}
+                        {fileType === 'document' && (
+                            <svg className="w-10 h-10 text-blue-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                                <path strokeLinecap="round" strokeLinejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" />
+                            </svg>
+                        )}
+                        {(fileType === 'file' || fileType === 'spreadsheet' || fileType === 'image') && (
+                            <svg className="w-10 h-10 text-white/30" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                                <path strokeLinecap="round" strokeLinejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" />
+                            </svg>
+                        )}
+                        <span className="text-xs text-white/30 uppercase font-medium">
+                            {file.name.split('.').pop()}
+                        </span>
+                    </div>
+                )}
+            </div>
+
+            {/* File info */}
+            <div className="p-3 border-t border-white/5">
+                <p className="text-sm text-white/70 truncate">{file.name}</p>
+                <p className="text-xs text-white/30 mt-0.5">{formatFileSize(file.size)}</p>
+            </div>
+
+            {/* Remove button */}
+            {onRemove && (
+                <button
+                    onClick={onRemove}
+                    className="absolute top-2 right-2 p-1.5 bg-black/60 backdrop-blur rounded-lg text-white/60 hover:text-white opacity-0 group-hover:opacity-100 transition-all"
+                >
+                    <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                        <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                </button>
+            )}
+        </div>
+    );
+}

package/library/file-upload/components/upload/UploadProgress.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+interface UploadProgressProps {
+    filename: string;
+    progress: number;
+    status: 'uploading' | 'complete' | 'error';
+    error?: string;
+    onCancel?: () => void;
+    onRetry?: () => void;
+}
+
+export default function UploadProgress({
+    filename,
+    progress,
+    status,
+    error,
+    onCancel,
+    onRetry,
+}: UploadProgressProps) {
+    const clampedProgress = Math.min(100, Math.max(0, progress));
+
+    return (
+        <div className="flex items-center gap-3 p-3 bg-white/5 border border-white/10 rounded-lg">
+            {/* File icon */}
+            <div className="flex-shrink-0">
+                {status === 'complete' ? (
+                    <div className="w-8 h-8 rounded-lg bg-emerald-500/10 flex items-center justify-center">
+                        <svg className="w-4 h-4 text-emerald-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+                        </svg>
+                    </div>
+                ) : status === 'error' ? (
+                    <div className="w-8 h-8 rounded-lg bg-red-500/10 flex items-center justify-center">
+                        <svg className="w-4 h-4 text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                        </svg>
+                    </div>
+                ) : (
+                    <div className="w-8 h-8 rounded-lg bg-cyan-500/10 flex items-center justify-center">
+                        <svg className="w-4 h-4 text-cyan-400 animate-pulse" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12" />
+                        </svg>
+                    </div>
+                )}
+            </div>
+
+            {/* Info */}
+            <div className="flex-1 min-w-0">
+                <p className="text-sm text-white/80 truncate">{filename}</p>
+                {status === 'error' && error ? (
+                    <p className="text-xs text-red-400 mt-0.5">{error}</p>
+                ) : status === 'complete' ? (
+                    <p className="text-xs text-emerald-400 mt-0.5">Upload complete</p>
+                ) : (
+                    <div className="mt-1.5">
+                        <div className="w-full h-1.5 bg-white/5 rounded-full overflow-hidden">
+                            <div
+                                className="h-full bg-cyan-500 rounded-full transition-all duration-300"
+                                style={{ width: `${clampedProgress}%` }}
+                            />
+                        </div>
+                        <p className="text-xs text-white/30 mt-0.5">{clampedProgress}%</p>
+                    </div>
+                )}
+            </div>
+
+            {/* Actions */}
+            <div className="flex-shrink-0">
+                {status === 'uploading' && onCancel && (
+                    <button
+                        onClick={onCancel}
+                        className="p-1 text-white/30 hover:text-white/60 transition-colors"
+                    >
+                        <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                        </svg>
+                    </button>
+                )}
+                {status === 'error' && onRetry && (
+                    <button
+                        onClick={onRetry}
+                        className="p-1 text-cyan-400 hover:text-cyan-300 transition-colors"
+                    >
+                        <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+                        </svg>
+                    </button>
+                )}
+            </div>
+        </div>
+    );
+}

package/library/file-upload/components/upload/fileStorage.ts

@@ -0,0 +1,142 @@
+/**
+ * File storage utility for handling uploads.
+ *
+ * Default implementation stores files locally.
+ * Replace with S3, Cloudflare R2, or other cloud storage as needed.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+export interface StoredFile {
+    id: string;
+    filename: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    url: string;
+    storedAt: Date;
+}
+
+export interface StorageConfig {
+    uploadDir: string;
+    publicUrlPrefix: string;
+    maxFileSize: number;
+    allowedMimeTypes: string[];
+}
+
+const defaultConfig: StorageConfig = {
+    uploadDir: path.join(process.cwd(), 'public', 'uploads'),
+    publicUrlPrefix: '/uploads',
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    allowedMimeTypes: [
+        'image/jpeg',
+        'image/png',
+        'image/gif',
+        'image/webp',
+        'application/pdf',
+        'text/csv',
+        'application/json',
+    ],
+};
+
+function ensureDir(dir: string): void {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+
+function generateFilename(originalName: string): string {
+    const ext = path.extname(originalName);
+    const hash = crypto.randomUUID().replace(/-/g, '').slice(0, 16);
+    const timestamp = Date.now();
+    return `${timestamp}-${hash}${ext}`;
+}
+
+/**
+ * Store a file buffer to local disk.
+ */
+export async function storeFile(
+    buffer: Buffer,
+    originalName: string,
+    mimeType: string,
+    config: Partial<StorageConfig> = {}
+): Promise<StoredFile> {
+    const cfg = { ...defaultConfig, ...config };
+
+    // Validate size
+    if (buffer.length > cfg.maxFileSize) {
+        throw new Error(`File exceeds maximum size of ${(cfg.maxFileSize / 1024 / 1024).toFixed(0)}MB`);
+    }
+
+    // Validate type
+    if (cfg.allowedMimeTypes.length > 0 && !cfg.allowedMimeTypes.includes(mimeType)) {
+        throw new Error(`File type ${mimeType} is not allowed`);
+    }
+
+    ensureDir(cfg.uploadDir);
+
+    const filename = generateFilename(originalName);
+    const filePath = path.join(cfg.uploadDir, filename);
+
+    await fs.promises.writeFile(filePath, buffer);
+
+    return {
+        id: crypto.randomUUID(),
+        filename,
+        originalName,
+        mimeType,
+        size: buffer.length,
+        url: `${cfg.publicUrlPrefix}/${filename}`,
+        storedAt: new Date(),
+    };
+}
+
+/**
+ * Delete a stored file.
+ */
+export async function deleteFile(
+    filename: string,
+    config: Partial<StorageConfig> = {}
+): Promise<void> {
+    const cfg = { ...defaultConfig, ...config };
+    const filePath = path.join(cfg.uploadDir, filename);
+
+    if (fs.existsSync(filePath)) {
+        await fs.promises.unlink(filePath);
+    }
+}
+
+/**
+ * List stored files.
+ */
+export async function listFiles(
+    config: Partial<StorageConfig> = {}
+): Promise<StoredFile[]> {
+    const cfg = { ...defaultConfig, ...config };
+
+    ensureDir(cfg.uploadDir);
+
+    const entries = await fs.promises.readdir(cfg.uploadDir, { withFileTypes: true });
+    const files: StoredFile[] = [];
+
+    for (const entry of entries) {
+        if (!entry.isFile()) continue;
+
+        const filePath = path.join(cfg.uploadDir, entry.name);
+        const stat = await fs.promises.stat(filePath);
+
+        files.push({
+            id: entry.name,
+            filename: entry.name,
+            originalName: entry.name,
+            mimeType: 'application/octet-stream',
+            size: stat.size,
+            url: `${cfg.publicUrlPrefix}/${entry.name}`,
+            storedAt: stat.birthtime,
+        });
+    }
+
+    return files;
+}

package/library/file-upload/manifest.json

@@ -0,0 +1,21 @@
+{
+    "name": "file-upload",
+    "version": "1.0.0",
+    "description": "Drag-and-drop file upload with preview, progress tracking, and server-side handling",
+    "author": "AD AI Engine",
+    "category": "media",
+    "dependencies": [],
+    "files": {
+        "components": [
+            "components/upload/DropZone.tsx",
+            "components/upload/FilePreview.tsx",
+            "components/upload/UploadProgress.tsx",
+            "components/upload/fileStorage.ts"
+        ],
+        "api": [
+            "app/api/upload/route.ts"
+        ]
+    },
+    "schema": null,
+    "instructions": "1. Import DropZone into your page for drag-and-drop uploads\n2. DropZone handles file selection, previews, and progress internally\n3. The API route at /api/upload stores files to the configured directory\n4. Customize fileStorage.ts for S3/cloud storage integration\n5. Set MAX_FILE_SIZE and ALLOWED_TYPES in the DropZone props"
+}