xertica-ui 2.1.2 → 2.1.4

package/components/ui/file-upload/file-upload.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { FileUpload } from './file-upload';
+import { useFileUpload } from './use-file-upload';
 import React from 'react';
+import { Upload, X, FileIcon, AlertCircle } from 'lucide-react';
 
 const meta: Meta<typeof FileUpload> = {
   title: 'UI/FileUpload',
@@ -51,3 +53,101 @@ export const ImageOnly: Story = {
     </div>
   ),
 };
+
+/**
+ * ## useFileUpload — Headless Hook
+ *
+ * Use `useFileUpload` when you need the full drag-and-drop logic but want to
+ * render a completely custom drop-zone UI. The hook returns all state and
+ * handlers; you wire them to whatever markup you like.
+ *
+ * ```tsx
+ * import { useFileUpload } from '@xertica/ui/file-upload';
+ *
+ * const {
+ *   files, dragActive, errorMessage, inputRef,
+ *   handleDrag, handleDrop, handleChange, removeFile, openFileDialog,
+ * } = useFileUpload({ maxFiles: 3, maxSize: 10 * 1024 * 1024 });
+ * ```
+ */
+export const HeadlessHook: Story = {
+  name: 'useFileUpload (headless)',
+  render: () => {
+    const {
+      files,
+      dragActive,
+      errorMessage,
+      inputRef,
+      handleDrag,
+      handleDrop,
+      handleChange,
+      removeFile,
+      openFileDialog,
+    } = useFileUpload({
+      maxFiles: 3,
+      maxSize: 2 * 1024 * 1024, // 2MB
+      onFilesChange: (f) => console.log('files changed', f),
+    });
+
+    return (
+      <div className="w-[500px] space-y-3">
+        {/* Custom drop-zone — completely different from the default FileUpload UI */}
+        <div
+          onDragEnter={handleDrag}
+          onDragLeave={handleDrag}
+          onDragOver={handleDrag}
+          onDrop={handleDrop}
+          onClick={openFileDialog}
+          className={[
+            'flex cursor-pointer flex-col items-center gap-2 rounded-xl border-2 border-dashed p-10 text-center transition-all',
+            dragActive
+              ? 'border-blue-500 bg-blue-50 text-blue-700'
+              : 'border-gray-300 bg-gray-50 text-gray-500 hover:border-gray-400',
+          ].join(' ')}
+        >
+          <Upload className="h-8 w-8" />
+          <p className="text-sm font-medium">
+            {dragActive ? 'Drop files here…' : 'Drag files or click to browse'}
+          </p>
+          <p className="text-xs text-gray-400">Up to 3 files · Max 2 MB each</p>
+          <input
+            ref={inputRef}
+            type="file"
+            className="hidden"
+            multiple
+            onChange={handleChange}
+          />
+        </div>
+
+        {errorMessage && (
+          <div className="flex items-center gap-2 rounded-lg bg-red-50 px-3 py-2 text-sm text-red-600">
+            <AlertCircle className="h-4 w-4 shrink-0" />
+            {errorMessage}
+          </div>
+        )}
+
+        {files.length > 0 && (
+          <ul className="space-y-1">
+            {files.map((file, i) => (
+              <li
+                key={i}
+                className="flex items-center justify-between rounded-lg border bg-white px-3 py-2 text-sm"
+              >
+                <span className="flex items-center gap-2">
+                  <FileIcon className="h-4 w-4 text-gray-400" />
+                  {file.name}
+                </span>
+                <button
+                  onClick={() => removeFile(i)}
+                  className="text-gray-400 hover:text-red-500"
+                >
+                  <X className="h-4 w-4" />
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    );
+  },
+};

package/components/ui/file-upload/file-upload.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { Upload, X, FileIcon, AlertCircle } from "lucide-react";
 import { cn } from "../../shared/utils";
 import { Button } from "../button";
+import { useFileUpload } from "./use-file-upload";
 
 interface FileUploadProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'onError'> {
   onFilesChange?: (files: File[]) => void;
@@ -20,6 +21,8 @@ interface FileUploadProps extends Omit<React.InputHTMLAttributes<HTMLInputElemen
  * for file uploads. Supports click-to-browse and drag-and-drop. Shows a preview
  * list of selected files with per-file remove buttons.
  *
+ * Headless logic is available via `useFileUpload` for custom drop-zone UIs.
+ *
  * @ai-rules
  * 1. Use `onFilesChange` to capture the selected files array in your form state.
  * 2. `maxFiles` defaults to 1 (single file). Set to a higher number for multi-upload.
@@ -39,80 +42,17 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
     disabled,
     ...props
   }, ref) => {
-    const [files, setFiles] = React.useState<File[]>([]);
-    const [dragActive, setDragActive] = React.useState(false);
-    const [errorMessage, setErrorMessage] = React.useState<string | null>(null);
-    const inputRef = React.useRef<HTMLInputElement>(null);
-
-    const handleFiles = (newFiles: FileList | null) => {
-      if (!newFiles) return;
-      setErrorMessage(null);
-
-      const filesArray = Array.from(newFiles);
-
-      const oversized = filesArray.filter(f => f.size > maxSize);
-      const validFiles = filesArray.filter(f => f.size <= maxSize);
-
-      if (oversized.length > 0) {
-        const limitMB = (maxSize / 1024 / 1024).toFixed(0);
-        setErrorMessage(`${oversized.length} file(s) exceed the ${limitMB}MB limit and were not added.`);
-        onError?.(oversized, 'size');
-      }
-
-      const merged = maxFiles === 1
-        ? validFiles.slice(0, 1)
-        : [...files, ...validFiles].slice(0, maxFiles);
-
-      const countRejected = maxFiles === 1
-        ? validFiles.slice(1)
-        : [...files, ...validFiles].slice(maxFiles);
-
-      if (countRejected.length > 0) {
-        setErrorMessage(`Only ${maxFiles} file(s) allowed. ${countRejected.length} file(s) were not added.`);
-        onError?.(countRejected, 'count');
-      }
-
-      setFiles(merged);
-      onFilesChange?.(merged);
-    };
-
-    const handleDrag = (e: React.DragEvent) => {
-      e.preventDefault();
-      e.stopPropagation();
-      if (e.type === "dragenter" || e.type === "dragover") {
-        setDragActive(true);
-      } else if (e.type === "dragleave") {
-        setDragActive(false);
-      }
-    };
-
-    const handleDrop = (e: React.DragEvent) => {
-      e.preventDefault();
-      e.stopPropagation();
-      setDragActive(false);
-      if (disabled) return;
-      handleFiles(e.dataTransfer.files);
-    };
-
-    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-      e.preventDefault();
-      if (disabled) return;
-      handleFiles(e.target.files);
-    };
-
-    const removeFile = (index: number) => {
-      const updatedFiles = files.filter((_, i) => i !== index);
-      setFiles(updatedFiles);
-      onFilesChange?.(updatedFiles);
-      if (updatedFiles.length === 0) setErrorMessage(null);
-    };
-
-    const openFileDialog = () => {
-      if (!disabled) {
-        setErrorMessage(null);
-        inputRef.current?.click();
-      }
-    };
+    const {
+      files,
+      dragActive,
+      errorMessage,
+      inputRef,
+      handleDrag,
+      handleDrop,
+      handleChange,
+      removeFile,
+      openFileDialog,
+    } = useFileUpload({ maxFiles, maxSize, onFilesChange, onError, disabled });
 
     return (
       <div ref={ref} className={cn("w-full", className)}>

package/components/ui/file-upload/index.ts

@@ -1 +1,2 @@
 export * from './file-upload';
+export * from './use-file-upload';

package/components/ui/file-upload/use-file-upload.ts

@@ -0,0 +1,181 @@
+import { useState, useRef, useCallback } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface UseFileUploadProps {
+    /** Maximum number of files allowed. @default 1 */
+    maxFiles?: number;
+    /** Maximum file size in bytes. @default 5MB */
+    maxSize?: number;
+    /** Called with the current accepted file list whenever it changes. */
+    onFilesChange?: (files: File[]) => void;
+    /** Called when files are rejected due to size or count limits. */
+    onError?: (rejectedFiles: File[], reason: 'size' | 'count') => void;
+    /** Whether the upload area is disabled. */
+    disabled?: boolean;
+}
+
+export interface UseFileUploadReturn {
+    // ── State ─────────────────────────────────────────────────────────────────
+    /** Currently accepted files. */
+    files: File[];
+    /** Whether a drag operation is currently active over the drop zone. */
+    dragActive: boolean;
+    /** Inline error message, or `null` when there is no error. */
+    errorMessage: string | null;
+
+    // ── Refs ──────────────────────────────────────────────────────────────────
+    /** Attach to the hidden `<input type="file">` element. */
+    inputRef: React.RefObject<HTMLInputElement>;
+
+    // ── Handlers ──────────────────────────────────────────────────────────────
+    /** Process a `FileList` from any source (input change, drop, paste, etc.). */
+    handleFiles: (newFiles: FileList | null) => void;
+    /** Drag enter / over / leave handler — attach to all three events. */
+    handleDrag: (e: React.DragEvent) => void;
+    /** Drop handler — attach to the drop zone element. */
+    handleDrop: (e: React.DragEvent) => void;
+    /** Input `onChange` handler — attach to the hidden `<input>`. */
+    handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Remove a file by its index in the `files` array. */
+    removeFile: (index: number) => void;
+    /** Programmatically open the native file picker dialog. */
+    openFileDialog: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless hook for drag-and-drop file upload logic.
+ *
+ * @description
+ * Encapsulates all stateful behaviour for a file upload area: file validation
+ * (size and count limits), drag-active tracking, error messaging, and the
+ * hidden-input ref. Pair with any custom drop-zone UI.
+ *
+ * @example
+ * ```tsx
+ * const { files, dragActive, errorMessage, inputRef, handleDrag, handleDrop, handleChange, removeFile, openFileDialog } =
+ *   useFileUpload({ maxFiles: 3, maxSize: 10 * 1024 * 1024 });
+ * ```
+ */
+export function useFileUpload({
+    maxFiles = 1,
+    maxSize = 5 * 1024 * 1024,
+    onFilesChange,
+    onError,
+    disabled = false,
+}: UseFileUploadProps = {}): UseFileUploadReturn {
+    const [files, setFiles] = useState<File[]>([]);
+    const [dragActive, setDragActive] = useState(false);
+    const [errorMessage, setErrorMessage] = useState<string | null>(null);
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const handleFiles = useCallback(
+        (newFiles: FileList | null) => {
+            if (!newFiles) return;
+            setErrorMessage(null);
+
+            const filesArray = Array.from(newFiles);
+
+            const oversized = filesArray.filter(f => f.size > maxSize);
+            const validFiles = filesArray.filter(f => f.size <= maxSize);
+
+            if (oversized.length > 0) {
+                const limitMB = (maxSize / 1024 / 1024).toFixed(0);
+                setErrorMessage(
+                    `${oversized.length} file(s) exceed the ${limitMB}MB limit and were not added.`
+                );
+                onError?.(oversized, 'size');
+            }
+
+            const merged =
+                maxFiles === 1
+                    ? validFiles.slice(0, 1)
+                    : [...files, ...validFiles].slice(0, maxFiles);
+
+            const countRejected =
+                maxFiles === 1
+                    ? validFiles.slice(1)
+                    : [...files, ...validFiles].slice(maxFiles);
+
+            if (countRejected.length > 0) {
+                setErrorMessage(
+                    `Only ${maxFiles} file(s) allowed. ${countRejected.length} file(s) were not added.`
+                );
+                onError?.(countRejected, 'count');
+            }
+
+            setFiles(merged);
+            onFilesChange?.(merged);
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [files, maxFiles, maxSize, onError, onFilesChange]
+    );
+
+    const handleDrag = useCallback((e: React.DragEvent) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if (e.type === 'dragenter' || e.type === 'dragover') {
+            setDragActive(true);
+        } else if (e.type === 'dragleave') {
+            setDragActive(false);
+        }
+    }, []);
+
+    const handleDrop = useCallback(
+        (e: React.DragEvent) => {
+            e.preventDefault();
+            e.stopPropagation();
+            setDragActive(false);
+            if (disabled) return;
+            handleFiles(e.dataTransfer.files);
+        },
+        [disabled, handleFiles]
+    );
+
+    const handleChange = useCallback(
+        (e: React.ChangeEvent<HTMLInputElement>) => {
+            e.preventDefault();
+            if (disabled) return;
+            handleFiles(e.target.files);
+        },
+        [disabled, handleFiles]
+    );
+
+    const removeFile = useCallback(
+        (index: number) => {
+            setFiles(prev => {
+                const updated = prev.filter((_, i) => i !== index);
+                onFilesChange?.(updated);
+                if (updated.length === 0) setErrorMessage(null);
+                return updated;
+            });
+        },
+        [onFilesChange]
+    );
+
+    const openFileDialog = useCallback(() => {
+        if (!disabled) {
+            setErrorMessage(null);
+            inputRef.current?.click();
+        }
+    }, [disabled]);
+
+    return {
+        files,
+        dragActive,
+        errorMessage,
+        inputRef,
+        handleFiles,
+        handleDrag,
+        handleDrop,
+        handleChange,
+        removeFile,
+        openFileDialog,
+    };
+}

package/components/ui/pagination/index.ts

@@ -1 +1,3 @@
 export * from './pagination';
+export { usePagination } from './use-pagination';
+export type { PaginationPageItem, UsePaginationProps, UsePaginationReturn } from './use-pagination';

package/components/ui/pagination/pagination.stories.tsx

@@ -8,7 +8,9 @@ import {
   PaginationNext,
   PaginationPrevious,
 } from './pagination';
+import { usePagination } from './use-pagination';
 import React, { useState } from 'react';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
 
 type PaginationStoryProps = React.ComponentProps<typeof Pagination> & {
   activePage?: number;
@@ -104,3 +106,95 @@ export const Controlled: Story = {
     );
   },
 };
+
+/**
+ * ## usePagination — Headless Hook
+ *
+ * Use `usePagination` when you need page state, ellipsis logic, and slice
+ * indices but want to render a completely custom pagination UI — or when you
+ * need to drive a data-fetch without any visual pagination bar at all.
+ *
+ * The hook computes `items` (an ordered list of page numbers + ellipsis
+ * markers) so you never have to calculate which pages to show manually.
+ *
+ * ```tsx
+ * import { usePagination } from '@xertica/ui/pagination';
+ *
+ * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
+ *   usePagination({ totalItems: 200, pageSize: 20 });
+ * ```
+ */
+export const HeadlessHook: Story = {
+  name: 'usePagination (headless)',
+  render: () => {
+    const {
+      currentPage,
+      totalPages,
+      items,
+      next,
+      prev,
+      goTo,
+      canGoPrev,
+      canGoNext,
+      startIndex,
+      endIndex,
+    } = usePagination({ totalItems: 237, pageSize: 20, siblingCount: 1 });
+
+    return (
+      <div className="space-y-4">
+        {/* Data slice info */}
+        <p className="text-sm text-muted-foreground">
+          Showing items <span className="font-medium text-foreground">{startIndex + 1}–{endIndex}</span> of{' '}
+          <span className="font-medium text-foreground">237</span>
+        </p>
+
+        {/* Fully custom pagination bar */}
+        <div className="flex items-center gap-1">
+          <button
+            onClick={prev}
+            disabled={!canGoPrev}
+            className="flex h-8 w-8 items-center justify-center rounded-md border text-sm disabled:opacity-40 hover:bg-muted transition-colors"
+            aria-label="Previous page"
+          >
+            <ChevronLeft className="h-4 w-4" />
+          </button>
+
+          {items.map((item) =>
+            item.type === 'ellipsis' ? (
+              <span key={item.key} className="flex h-8 w-8 items-center justify-center text-muted-foreground text-sm">
+                …
+              </span>
+            ) : (
+              <button
+                key={item.page}
+                onClick={() => goTo(item.page)}
+                className={[
+                  'flex h-8 w-8 items-center justify-center rounded-md border text-sm font-medium transition-colors',
+                  item.page === currentPage
+                    ? 'bg-primary text-primary-foreground border-primary'
+                    : 'hover:bg-muted',
+                ].join(' ')}
+                aria-current={item.page === currentPage ? 'page' : undefined}
+              >
+                {item.page}
+              </button>
+            )
+          )}
+
+          <button
+            onClick={next}
+            disabled={!canGoNext}
+            className="flex h-8 w-8 items-center justify-center rounded-md border text-sm disabled:opacity-40 hover:bg-muted transition-colors"
+            aria-label="Next page"
+          >
+            <ChevronRight className="h-4 w-4" />
+          </button>
+        </div>
+
+        <p className="text-xs text-muted-foreground">
+          Page {currentPage} of {totalPages}
+        </p>
+      </div>
+    );
+  },
+};