@instruments/materia-ui 0.1.0

package/dist/compositions/file-upload/file-upload-dropzone.js

@@ -0,0 +1,50 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CloudUpload } from "lucide-react";
+import { useCallback } from "react";
+import { Center } from "../../components/center.js";
+import { Icon } from "../../components/icon.js";
+import { VStack } from "../../components/stack.js";
+import { Text } from "../../components/text.js";
+/**
+ * FileUploadDropzone - A drag-and-drop zone for file uploads.
+ * Use with the useFileUpload hook for full functionality.
+ *
+ * @example
+ * ```tsx
+ * const [{ isDragging }, actions] = useFileUpload();
+ *
+ * <FileUploadDropzone
+ *   dragging={isDragging}
+ *   onDragEnter={actions.handleDragEnter}
+ *   onDragLeave={actions.handleDragLeave}
+ *   onDragOver={actions.handleDragOver}
+ *   onDrop={actions.handleDrop}
+ *   onClick={actions.openFileDialog}
+ * />
+ * ```
+ *
+ * @bestPractice `FileUploadDropzone` is presentational - wire it to the `useFileUpload` hook for the actual file input, drag state, and file list; it stores nothing itself.
+ * @bestPractice Forward the hook's `handleDragEnter/Leave/Over/Drop` and drag state into `dragging` so the drag styling matches the real drop-target state.
+ * @bestPractice Keep `title`/`description` (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via `children` when needed.
+ * @category inputs
+ */
+export const FileUploadDropzone = ({ ref, dragging = false, disabled = false, icon, title = "Drop files here or click to upload", description = "PNG, JPG, GIF up to 10MB", onDragEnter, onDragLeave, onDragOver, onDrop, onClick, className, children, }) => {
+    const handleClick = useCallback(() => {
+        if (!disabled && onClick) {
+            onClick();
+        }
+    }, [disabled, onClick]);
+    return (_jsx("button", { "aria-disabled": disabled || undefined, className: cn(
+        // Base styles
+        "group duration-normal relative flex min-h-45 cursor-pointer flex-col items-center justify-center gap-3 rounded-3xl border-2 border-dashed p-6 transition-colors", 
+        // Default state
+        "border-gray-200 bg-gray-50/50 hover:border-gray-300 hover:bg-gray-100/50", 
+        // Dragging state
+        dragging && "border-primary bg-primary/5 ring-primary/10 ring-4", 
+        // Disabled state
+        disabled && "pointer-events-none cursor-not-allowed opacity-50", className), disabled: disabled, onClick: handleClick, onDragEnter: onDragEnter, onDragLeave: onDragLeave, onDragOver: onDragOver, onDrop: onDrop, ref: ref, tabIndex: disabled ? -1 : 0, type: "button", children: children ?? (_jsxs(_Fragment, { children: [_jsx(Center, { className: cn("size-12 rounded-full transition-colors", dragging
+                        ? "bg-primary/10 text-primary"
+                        : "bg-gray-100 text-gray-400 group-hover:bg-gray-200 group-hover:text-gray-500"), children: _jsx(Icon, { icon: icon ?? CloudUpload, size: "lg" }) }), _jsxs(VStack, { align: "center", className: "text-center", gap: "2xs", children: [_jsx(Text, { className: cn("font-medium transition-colors", dragging ? "text-primary" : "text-foreground"), children: dragging ? "Drop to upload" : title }), description && (_jsx(Text, { className: "text-muted-foreground", size: "paragraph-sm", children: description }))] })] })) }));
+};

package/dist/compositions/file-upload/file-upload-item.d.ts

@@ -0,0 +1,37 @@
+interface FileUploadItemProps {
+    /** Additional class names */
+    className?: string | undefined;
+    /** Error message if upload failed */
+    error?: string | undefined;
+    /** Whether upload is complete */
+    complete?: boolean | undefined;
+    /** File name */
+    name: string;
+    /** Callback when remove button is clicked */
+    onRemove?: (() => void) | undefined;
+    /** Preview URL for images */
+    previewUrl?: string | undefined;
+    /** Upload progress (0-100), undefined means not uploading */
+    progress?: number | undefined;
+    /** File size in bytes */
+    size: number;
+    /** File MIME type */
+    type: string;
+}
+/**
+ * FileUploadItem - Displays a single file with preview, progress, and actions.
+ *
+ * @example
+ * ```tsx
+ * <FileUploadItem
+ *   name="photo.jpg"
+ *   size={1024000}
+ *   type="image/jpeg"
+ *   previewUrl="/preview.jpg"
+ *   progress={75}
+ *   onRemove={() => removeFile(id)}
+ * />
+ * ```
+ */
+export declare const FileUploadItem: ({ name, size, type, previewUrl, progress, error, complete, onRemove, className, }: FileUploadItemProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/file-upload/file-upload-item.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { File, FileImage, FileText, FileVideo, Trash2, X } from "lucide-react";
+import { useMemo } from "react";
+import { Button } from "../../components/button.js";
+import { Center } from "../../components/center.js";
+import { Icon } from "../../components/icon.js";
+import { Progress } from "../../components/progress.js";
+import { HStack, VStack } from "../../components/stack.js";
+import { Text } from "../../components/text.js";
+import { hasText } from "../../utils/type-guards.js";
+import { formatBytes } from "../file-upload/use-file-upload.js";
+/** Get icon based on file type */
+const getFileIcon = (type) => {
+    if (type.startsWith("image/")) {
+        return _jsx(Icon, { icon: FileImage });
+    }
+    if (type.startsWith("video/")) {
+        return _jsx(Icon, { icon: FileVideo });
+    }
+    if (type.startsWith("text/") || type.includes("pdf")) {
+        return _jsx(Icon, { icon: FileText });
+    }
+    return _jsx(Icon, { icon: File });
+};
+/** Leading preview thumbnail (image) or a type-based file icon. */
+const FilePreview = ({ isImage, name, previewUrl, type, }) => (_jsx(Center, { className: cn("size-12 shrink-0 overflow-hidden rounded-md", isImage ? "bg-gray-100" : "bg-gray-100 text-gray-400"), children: hasText(previewUrl) && isImage ? (_jsx("img", { alt: `Preview of ${name}`, className: "size-full object-cover", height: 48, src: previewUrl, width: 48 })) : (getFileIcon(type)) }));
+/** Remove button - switches to a destructive trash style on error. */
+const RemoveButton = ({ hasError, name, onRemove, }) => (_jsx(Button, { emphasis: "ghost", "aria-label": `Remove ${name}`, className: cn("size-8 shrink-0 opacity-0 transition-opacity group-hover:opacity-100", hasError && "opacity-100"), icon: hasError ? Trash2 : X, onClick: onRemove, radius: "full", size: "icon-sm", tone: hasError ? "danger" : "neutral" }));
+/**
+ * FileUploadItem - Displays a single file with preview, progress, and actions.
+ *
+ * @example
+ * ```tsx
+ * <FileUploadItem
+ *   name="photo.jpg"
+ *   size={1024000}
+ *   type="image/jpeg"
+ *   previewUrl="/preview.jpg"
+ *   progress={75}
+ *   onRemove={() => removeFile(id)}
+ * />
+ * ```
+ */
+export const FileUploadItem = ({ name, size, type, previewUrl, progress, error, complete, onRemove, className, }) => {
+    const hasError = hasText(error);
+    const isUploading = progress !== undefined && progress < 100 && !hasError;
+    const isImage = type.startsWith("image/");
+    const formattedSize = useMemo(() => formatBytes(size), [size]);
+    return (_jsxs(HStack, { align: "center", className: cn("group bg-background relative rounded-lg border p-3 transition-colors", hasError && "border-destructive/50 bg-destructive/5", complete === true && !hasError && "border-green-500/50 bg-green-50/50", !hasError && complete !== true && "border-border hover:bg-accent/50", className), gap: "sm", children: [_jsx(FilePreview, { isImage: isImage, name: name, previewUrl: previewUrl, type: type }), _jsxs(VStack, { className: "min-w-0 flex-1", gap: "none", children: [_jsx(Text, { className: "truncate font-medium", size: "paragraph-sm", children: name }), _jsxs(HStack, { align: "center", gap: "xs", children: [_jsx(Text, { className: "text-muted-foreground", size: "caption", children: formattedSize }), hasError && (_jsx(Text, { className: "text-destructive", size: "caption", children: error })), complete === true && !hasError && (_jsx(Text, { className: "text-green-600", size: "caption", children: "Uploaded" }))] }), isUploading && (_jsx("div", { className: "mt-2", children: _jsx(Progress, { className: "h-1.5", value: progress }) }))] }), onRemove && (_jsx(RemoveButton, { hasError: hasError, name: name, onRemove: onRemove }))] }));
+};

package/dist/compositions/file-upload/file-upload-list.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+import type { Orientation } from "../../tokens/orientation.js";
+import type { FileWithPreview } from "../file-upload/use-file-upload.js";
+interface FileUploadListProps {
+    /** Whether the list should animate */
+    animated?: boolean;
+    /** Additional class names */
+    className?: string;
+    /** Completed files (keyed by file id) */
+    completed?: Record<string, boolean>;
+    /** Errors for each file (keyed by file id) */
+    errors?: Record<string, string>;
+    /** Array of files to display */
+    files: FileWithPreview[];
+    /** Callback when a file's remove button is clicked */
+    onRemove?: (id: string) => void;
+    /** Orientation of the list */
+    orientation?: Orientation;
+    /** Upload progress for each file (keyed by file id) */
+    progress?: Record<string, number>;
+    /** Render custom item content */
+    renderItem?: (file: FileWithPreview) => ReactNode;
+}
+/**
+ * FileUploadList - Displays a list of uploaded files with animations.
+ *
+ * @example
+ * ```tsx
+ * const [{ files }, { removeFile }] = useFileUpload({ multiple: true });
+ *
+ * <FileUploadList
+ *   files={files}
+ *   onRemove={removeFile}
+ *   progress={{ "file-1": 75 }}
+ * />
+ * ```
+ */
+export declare const FileUploadList: ({ files, onRemove, progress, errors, completed, animated, orientation, className, renderItem, }: FileUploadListProps) => import("react").JSX.Element | null;
+export {};

package/dist/compositions/file-upload/file-upload-list.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { Stack } from "../../components/stack.js";
+import { springs } from "../../tokens/motion.js";
+import { FileUploadItem } from "../file-upload/file-upload-item.js";
+// Stable empty defaults so undefined props don't create fresh objects per render.
+const EMPTY_PROGRESS = {};
+const EMPTY_ERRORS = {};
+const EMPTY_COMPLETED = {};
+/**
+ * FileUploadList - Displays a list of uploaded files with animations.
+ *
+ * @example
+ * ```tsx
+ * const [{ files }, { removeFile }] = useFileUpload({ multiple: true });
+ *
+ * <FileUploadList
+ *   files={files}
+ *   onRemove={removeFile}
+ *   progress={{ "file-1": 75 }}
+ * />
+ * ```
+ */
+export const FileUploadList = ({ files, onRemove, progress = EMPTY_PROGRESS, errors = EMPTY_ERRORS, completed = EMPTY_COMPLETED, animated = true, orientation = "vertical", className, renderItem, }) => {
+    if (files.length === 0) {
+        return null;
+    }
+    const content = files.map((file) => {
+        const fileProgress = progress[file.id];
+        const fileError = errors[file.id];
+        const fileCompleted = completed[file.id];
+        const item = renderItem ? (renderItem(file)) : (_jsx(FileUploadItem, { error: fileError, complete: fileCompleted, name: file.file.name, onRemove: onRemove
+                ? () => {
+                    onRemove(file.id);
+                }
+                : undefined, previewUrl: file.preview, progress: fileProgress, size: file.file.size, type: file.file instanceof File ? file.file.type : file.file.type }, file.id));
+        if (!animated) {
+            return _jsx("div", { children: item }, file.id);
+        }
+        return (_jsx(m.div, { animate: { opacity: 1, scale: 1, y: 0 }, exit: { opacity: 0, scale: 0.95, y: -10 }, initial: { opacity: 0, scale: 0.95, y: 10 }, layout: true, transition: springs.swift, children: item }, file.id));
+    });
+    return (_jsx(Stack, { className: cn(orientation === "horizontal" && "flex-wrap", className), direction: orientation === "horizontal" ? "row" : "column", gap: "xs", children: animated ? (_jsx(AnimatePresence, { mode: "popLayout", children: content })) : (content) }));
+};

package/dist/compositions/file-upload/file-upload-trigger.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode, Ref } from "react";
+import type { ButtonProps } from "../../components/button.js";
+interface FileUploadTriggerProps extends Omit<ButtonProps, "onClick"> {
+    /** Custom children (overrides default button content) */
+    children?: ReactNode;
+    /** Click handler to open file dialog */
+    onClick?: () => void;
+    /** Ref for the button element */
+    ref?: Ref<HTMLButtonElement>;
+    /** Whether files are currently being uploaded */
+    uploading?: boolean;
+    /** Custom label when uploading */
+    uploadingLabel?: string;
+}
+/**
+ * FileUploadTrigger - A button that opens the file dialog.
+ * Use with the useFileUpload hook for full functionality.
+ *
+ * @example
+ * ```tsx
+ * const [state, actions] = useFileUpload({ accept: "image/*" });
+ *
+ * <FileUploadTrigger onClick={actions.openFileDialog}>
+ *   Upload image
+ * </FileUploadTrigger>
+ * <input {...actions.getInputProps()} className="sr-only" />
+ * ```
+ */
+export declare const FileUploadTrigger: ({ ref, onClick, uploading, uploadingLabel, children, disabled, className, ...buttonProps }: FileUploadTriggerProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/file-upload/file-upload-trigger.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Upload } from "lucide-react";
+import { useCallback } from "react";
+import { Button } from "../../components/button.js";
+/**
+ * FileUploadTrigger - A button that opens the file dialog.
+ * Use with the useFileUpload hook for full functionality.
+ *
+ * @example
+ * ```tsx
+ * const [state, actions] = useFileUpload({ accept: "image/*" });
+ *
+ * <FileUploadTrigger onClick={actions.openFileDialog}>
+ *   Upload image
+ * </FileUploadTrigger>
+ * <input {...actions.getInputProps()} className="sr-only" />
+ * ```
+ */
+export const FileUploadTrigger = ({ ref, onClick, uploading = false, uploadingLabel = "Uploading…", children, disabled, className, ...buttonProps }) => {
+    const handleClick = useCallback(() => {
+        if (disabled !== true && !uploading && onClick !== undefined) {
+            onClick();
+        }
+    }, [disabled, uploading, onClick]);
+    return (_jsx(Button, { className: cn(className), disabled: disabled === true || uploading, icon: Upload, loading: uploading, loadingLabel: uploadingLabel, onClick: handleClick, ref: ref, type: "button", ...buttonProps, children: children ?? "Upload file" }));
+};

package/dist/compositions/file-upload/file-upload-types.d.ts

@@ -0,0 +1,45 @@
+/** Describes a pre-existing (already-uploaded) file passed via `initialFiles`. */
+export interface FileMetadata {
+    id: string;
+    name: string;
+    /** File size in bytes. */
+    size: number;
+    /** MIME type. */
+    type: string;
+    /** Remote URL used as the preview source. */
+    url: string;
+}
+/** A tracked file plus its stable id and preview source. */
+export interface FileWithPreview {
+    /** The freshly picked `File`, or the `FileMetadata` for an initial file. */
+    file: File | FileMetadata;
+    id: string;
+    /** Preview source: an object URL for images, or the metadata `url`. */
+    preview?: string | undefined;
+}
+/** Options for {@link useFileUpload}. */
+export interface FileUploadOptions {
+    /** `accept` filter applied to added files. @default "*" */
+    accept?: string;
+    /** Files to seed the list with (treated as already uploaded). */
+    initialFiles?: FileMetadata[];
+    /** Maximum number of files. @default Infinity */
+    maxFiles?: number;
+    /** Maximum size per file, in bytes. @default Infinity */
+    maxSize?: number;
+    /** Allow selecting multiple files; when false, adding replaces the current file. @default false */
+    multiple?: boolean;
+    /** Called with validation error messages when files are rejected. */
+    onError?: (errors: string[]) => void;
+    /** Called with the newly accepted files each time files are added. */
+    onFilesAdded?: (addedFiles: FileWithPreview[]) => void;
+    /** Called with the full file list whenever it changes. */
+    onFilesChange?: (files: FileWithPreview[]) => void;
+}
+/** Reactive state returned by {@link useFileUpload}. */
+export interface FileUploadState {
+    errors: string[];
+    files: FileWithPreview[];
+    /** True while files are being dragged over the dropzone. */
+    isDragging: boolean;
+}

package/dist/compositions/file-upload/file-upload-types.js

@@ -0,0 +1 @@
+export {};

package/dist/compositions/file-upload/file-upload-utils.d.ts

@@ -0,0 +1,20 @@
+import type { FileMetadata, FileWithPreview } from "../file-upload/file-upload-types.js";
+export interface ValidateFileOptions {
+    accept: string;
+    maxSize: number;
+    multiple: boolean;
+}
+export interface PrepareFileAdditionsOptions extends ValidateFileOptions {
+    createPreview: (file: File | FileMetadata) => string | undefined;
+    existingFiles: FileWithPreview[];
+    generateUniqueId: (file: File | FileMetadata) => string;
+    maxFiles: number;
+    newFiles: (File | FileMetadata)[];
+}
+export interface PreparedFileAdditions {
+    errors: string[];
+    validFiles: FileWithPreview[];
+}
+export declare const formatBytes: (bytes: number, decimals?: number) => string;
+export declare const validateFile: (file: File | FileMetadata, options: ValidateFileOptions) => string | null;
+export declare const prepareFileAdditions: (options: PrepareFileAdditionsOptions) => PreparedFileAdditions;

package/dist/compositions/file-upload/file-upload-utils.js

@@ -0,0 +1,75 @@
+export const formatBytes = (bytes, decimals = 2) => {
+    if (bytes === 0) {
+        return "0 Bytes";
+    }
+    const k = 1024;
+    const dm = Math.max(0, decimals);
+    const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Number((bytes / k ** i).toFixed(dm))}${sizes[i]}`;
+};
+const getFileType = (file) => file instanceof File ? file.type || "" : file.type;
+const getFileExtension = (file) => `.${file.name.split(".").pop() ?? ""}`;
+const buildFileSizeError = (file, maxSize, multiple) => multiple
+    ? `Some files exceed the maximum size of ${formatBytes(maxSize)}.`
+    : `File "${file.name}" exceeds the maximum size of ${formatBytes(maxSize)}.`;
+const isAcceptedType = (file, accept) => {
+    if (accept === "*") {
+        return true;
+    }
+    const fileType = getFileType(file);
+    const fileExtension = getFileExtension(file);
+    return accept
+        .split(",")
+        .map((type) => type.trim())
+        .some((acceptedType) => {
+        if (acceptedType.startsWith(".")) {
+            return fileExtension.toLowerCase() === acceptedType.toLowerCase();
+        }
+        if (acceptedType.endsWith("/*")) {
+            const [baseType] = acceptedType.split("/");
+            return fileType.startsWith(`${baseType}/`);
+        }
+        return fileType === acceptedType;
+    });
+};
+const isDuplicateFile = (file, existingFiles) => existingFiles.some((existingFile) => existingFile.file.name === file.name &&
+    existingFile.file.size === file.size);
+export const validateFile = (file, options) => {
+    if (file.size > options.maxSize) {
+        return buildFileSizeError(file, options.maxSize, options.multiple);
+    }
+    if (!isAcceptedType(file, options.accept)) {
+        return `File "${file.name}" is not an accepted file type.`;
+    }
+    return null;
+};
+export const prepareFileAdditions = (options) => {
+    const { existingFiles, maxFiles, multiple, newFiles } = options;
+    const errors = [];
+    if (multiple &&
+        maxFiles !== Number.POSITIVE_INFINITY &&
+        existingFiles.length + newFiles.length > maxFiles) {
+        return {
+            errors: [`You can only upload a maximum of ${maxFiles} files.`],
+            validFiles: [],
+        };
+    }
+    const validFiles = [];
+    for (const file of newFiles) {
+        if (multiple && isDuplicateFile(file, existingFiles)) {
+            continue;
+        }
+        const error = validateFile(file, options);
+        if (error !== undefined && error !== null && error !== "") {
+            errors.push(error);
+            continue;
+        }
+        validFiles.push({
+            file,
+            id: options.generateUniqueId(file),
+            preview: options.createPreview(file),
+        });
+    }
+    return { errors, validFiles };
+};

package/dist/compositions/file-upload/use-file-upload.d.ts

@@ -0,0 +1,33 @@
+import type React from "react";
+import type { ChangeEvent, DragEvent, InputHTMLAttributes } from "react";
+import type { FileUploadOptions, FileUploadState } from "../file-upload/file-upload-types.js";
+export type { FileMetadata, FileUploadOptions, FileUploadState, FileWithPreview, } from "../file-upload/file-upload-types.js";
+/** Imperative actions returned by {@link useFileUpload} for driving the upload UI. */
+export interface FileUploadActions {
+    /** Add and validate files against `accept`/`maxFiles`/`maxSize`, appending or replacing per `multiple`. */
+    addFiles: (files: FileList | File[]) => void;
+    clearErrors: () => void;
+    clearFiles: () => void;
+    /** Props (including a managed `ref`) to spread onto a hidden `<input type="file">`. */
+    getInputProps: (props?: InputHTMLAttributes<HTMLInputElement>) => InputHTMLAttributes<HTMLInputElement> & {
+        ref: React.Ref<HTMLInputElement>;
+    };
+    handleDragEnter: (e: DragEvent<HTMLElement>) => void;
+    handleDragLeave: (e: DragEvent<HTMLElement>) => void;
+    handleDragOver: (e: DragEvent<HTMLElement>) => void;
+    handleDrop: (e: DragEvent<HTMLElement>) => void;
+    handleFileChange: (e: ChangeEvent<HTMLInputElement>) => void;
+    openFileDialog: () => void;
+    removeFile: (id: string) => void;
+}
+/**
+ * Manages file-selection state for the FileUpload components: the selected
+ * files (with previews), drag state, and validation errors.
+ *
+ * Returns a `[state, actions]` tuple. Wire `actions` to a
+ * {@link FileUploadDropzone}/{@link FileUploadTrigger} and spread
+ * `actions.getInputProps()` onto a hidden `<input>`. Object-URL previews for
+ * image files are created on add and revoked on remove/clear automatically.
+ */
+export declare const useFileUpload: (options?: FileUploadOptions) => [FileUploadState, FileUploadActions];
+export { formatBytes } from "../file-upload/file-upload-utils.js";