@nikala-ui/hooks 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikala-ui/hooks",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Reactive SolidJS primitives and primitives for Nikala UI",
   "type": "module",
   "main": "./src/index.ts",

package/src/create-chat-scroll.ts

@@ -0,0 +1,113 @@
+import { createSignal, createEffect, onCleanup, onMount, type Accessor } from "solid-js";
+
+export interface CreateChatScrollOptions {
+  /** Target scrollable container element or accessor */
+  target: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Dependency accessor (e.g. messages length or content signal) that triggers auto-scroll when changed */
+  trigger?: Accessor<any>;
+  /** Threshold in pixels from bottom to consider the container "at bottom". Defaults to 40. */
+  threshold?: number;
+  /** Whether auto-scroll is enabled. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Scroll behavior: "smooth" or "auto". Defaults to "smooth". */
+  behavior?: ScrollBehavior;
+}
+
+export interface CreateChatScrollReturn {
+  /** Accessor indicating whether the container is currently scrolled to the bottom */
+  isAtBottom: Accessor<boolean>;
+  /** Accessor indicating whether user has manually scrolled up away from bottom */
+  isScrolledUp: Accessor<boolean>;
+  /** Programmatically scroll container directly to the bottom */
+  scrollToBottom: (options?: { smooth?: boolean }) => void;
+}
+
+/**
+ * SolidJS reactive primitive for chat and streaming message auto-scrolling with user scroll detection.
+ *
+ * @param options Chat scroll configuration options.
+ */
+export function createChatScroll(options: CreateChatScrollOptions): CreateChatScrollReturn {
+  const [isAtBottom, setIsAtBottom] = createSignal<boolean>(true);
+  const isScrolledUp = () => !isAtBottom();
+
+  const getElement = (): HTMLElement | undefined => {
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | undefined>)();
+    }
+    return options.target;
+  };
+
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return (options.enabled as Accessor<boolean>)();
+    }
+    return options.enabled ?? true;
+  };
+
+  const threshold = options.threshold ?? 40;
+
+  const checkIfAtBottom = () => {
+    const el = getElement();
+    if (!el) return true;
+    const distanceToBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    return distanceToBottom <= threshold;
+  };
+
+  const scrollToBottom = (opts?: { smooth?: boolean }) => {
+    const el = getElement();
+    if (!el) return;
+
+    const useSmooth = opts?.smooth ?? (options.behavior === "smooth" || options.behavior === undefined);
+
+    el.scrollTo({
+      top: el.scrollHeight,
+      behavior: useSmooth ? "smooth" : "auto",
+    });
+    setIsAtBottom(true);
+  };
+
+  const handleScroll = () => {
+    const atBottom = checkIfAtBottom();
+    setIsAtBottom(atBottom);
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const el = getElement();
+    if (el) {
+      el.addEventListener("scroll", handleScroll, { passive: true });
+      setIsAtBottom(checkIfAtBottom());
+    }
+  });
+
+  onCleanup(() => {
+    if (typeof window === "undefined") return;
+    const el = getElement();
+    if (el) {
+      el.removeEventListener("scroll", handleScroll);
+    }
+  });
+
+  // Watch trigger dependencies (e.g. messages length or stream tokens)
+  if (options.trigger) {
+    createEffect(() => {
+      // Track trigger dependency
+      options.trigger!();
+
+      if (isEnabled() && isAtBottom()) {
+        // Run after microtask/DOM paint
+        setTimeout(() => {
+          scrollToBottom({ smooth: true });
+        }, 10);
+      }
+    });
+  }
+
+  return {
+    isAtBottom,
+    isScrolledUp,
+    scrollToBottom,
+  };
+}

package/src/create-drop-zone.ts

@@ -0,0 +1,317 @@
+import { createSignal, onCleanup, onMount, type Accessor } from "solid-js";
+
+export interface FileRejection {
+  file: File;
+  errors: Array<{
+    code: "file-invalid-type" | "file-too-large" | "file-too-small" | "too-many-files";
+    message: string;
+  }>;
+}
+
+export interface CreateDropZoneOptions {
+  /** Accepted file types: MIME types (e.g. "image/*", "application/pdf") or extensions (e.g. ".png", ".jpg") */
+  accept?: string | string[];
+  /** Maximum number of files allowed */
+  maxFiles?: number;
+  /** Maximum file size in bytes */
+  maxSize?: number;
+  /** Minimum file size in bytes */
+  minSize?: number;
+  /** Whether multiple files are allowed. Defaults to true */
+  multiple?: boolean;
+  /** Whether the drop zone is disabled */
+  disabled?: boolean | Accessor<boolean>;
+  /** Prevents browser default behavior of opening files dropped outside dropzone. Defaults to true */
+  preventDropOnDocument?: boolean;
+  /** Callback fired when valid files are dropped */
+  onDrop?: (files: File[], event: DragEvent) => void;
+  /** Callback fired when some or all files fail validation */
+  onDropRejected?: (rejectedFiles: FileRejection[], event: DragEvent) => void;
+  /** Callback fired when drag enters the dropzone */
+  onDragEnter?: (event: DragEvent) => void;
+  /** Callback fired when drag leaves the dropzone */
+  onDragLeave?: (event: DragEvent) => void;
+  /** Callback fired when dragging over the dropzone */
+  onDragOver?: (event: DragEvent) => void;
+  /** Callback fired whenever accepted files list changes */
+  onFilesChanged?: (files: File[]) => void;
+}
+
+export interface CreateDropZoneReturn {
+  /** Whether drag operation is currently active over the target drop zone */
+  isOver: Accessor<boolean>;
+  /** Whether files are currently being dragged anywhere on the window */
+  isDragging: Accessor<boolean>;
+  /** Currently accepted dropped files */
+  files: Accessor<File[]>;
+  /** Currently rejected files with error details */
+  rejectedFiles: Accessor<FileRejection[]>;
+  /** Clear all accepted and rejected files */
+  clear: () => void;
+  /** Programmatically set files (e.g. from an <input type="file" /> change event) */
+  setFiles: (files: File[]) => void;
+  /** Programmatically open the native browser file selector dialog */
+  openFileDialog: () => void;
+  /** Ref callback to attach to target DOM element */
+  ref: (el: HTMLElement) => void;
+  /** Event handler props to spread directly onto target JSX element */
+  props: {
+    onDragEnter: (e: DragEvent) => void;
+    onDragLeave: (e: DragEvent) => void;
+    onDragOver: (e: DragEvent) => void;
+    onDrop: (e: DragEvent) => void;
+  };
+}
+
+function matchesAccept(file: File, acceptList: string[]): boolean {
+  if (acceptList.length === 0) return true;
+  const fileName = file.name.toLowerCase();
+  const fileType = file.type.toLowerCase();
+
+  return acceptList.some((pattern) => {
+    const p = pattern.trim().toLowerCase();
+    if (p.startsWith(".")) {
+      return fileName.endsWith(p);
+    }
+    if (p.endsWith("/*")) {
+      const typePrefix = p.slice(0, -2);
+      return fileType.startsWith(typePrefix + "/");
+    }
+    return fileType === p;
+  });
+}
+
+function validateFiles(
+  incomingFiles: File[],
+  options: CreateDropZoneOptions
+): { accepted: File[]; rejected: FileRejection[] } {
+  const acceptList = options.accept
+    ? (Array.isArray(options.accept) ? options.accept : options.accept.split(","))
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+
+  const maxFiles = options.maxFiles ?? (options.multiple === false ? 1 : Infinity);
+  const maxSize = options.maxSize;
+  const minSize = options.minSize;
+
+  const accepted: File[] = [];
+  const rejected: FileRejection[] = [];
+
+  incomingFiles.forEach((file, index) => {
+    const errors: FileRejection["errors"] = [];
+
+    if (index >= maxFiles) {
+      errors.push({
+        code: "too-many-files",
+        message: `Maximum allowed files is ${maxFiles}.`,
+      });
+    }
+
+    if (acceptList.length > 0 && !matchesAccept(file, acceptList)) {
+      errors.push({
+        code: "file-invalid-type",
+        message: `File type "${file.type || file.name.split(".").pop()}" is not allowed.`,
+      });
+    }
+
+    if (maxSize !== undefined && file.size > maxSize) {
+      errors.push({
+        code: "file-too-large",
+        message: `File size exceeds ${(maxSize / (1024 * 1024)).toFixed(1)}MB limit.`,
+      });
+    }
+
+    if (minSize !== undefined && file.size < minSize) {
+      errors.push({
+        code: "file-too-small",
+        message: `File size is below ${(minSize / 1024).toFixed(1)}KB limit.`,
+      });
+    }
+
+    if (errors.length > 0) {
+      rejected.push({ file, errors });
+    } else {
+      accepted.push(file);
+    }
+  });
+
+  return { accepted, rejected };
+}
+
+/**
+ * SolidJS reactive primitive for managing file drag & drop zones with validation and file dialog support.
+ *
+ * @param options Configuration options for file acceptance, size limits, and callbacks.
+ */
+export function createDropZone(options: CreateDropZoneOptions = {}): CreateDropZoneReturn {
+  const [isOver, setIsOver] = createSignal(false);
+  const [isDragging, setIsDragging] = createSignal(false);
+  const [files, setFilesInternal] = createSignal<File[]>([]);
+  const [rejectedFiles, setRejectedFilesInternal] = createSignal<FileRejection[]>([]);
+
+  let dragCounter = 0;
+  let windowDragCounter = 0;
+  let targetElement: HTMLElement | null = null;
+
+  const isDisabled = () => {
+    if (typeof options.disabled === "function") {
+      return (options.disabled as Accessor<boolean>)();
+    }
+    return options.disabled ?? false;
+  };
+
+  const processFiles = (incomingFiles: File[], event: DragEvent) => {
+    const { accepted, rejected } = validateFiles(incomingFiles, options);
+
+    setFilesInternal(accepted);
+    setRejectedFilesInternal(rejected);
+
+    if (accepted.length > 0) {
+      options.onDrop?.(accepted, event);
+      options.onFilesChanged?.(accepted);
+    }
+
+    if (rejected.length > 0) {
+      options.onDropRejected?.(rejected, event);
+    }
+  };
+
+  const onDragEnter = (e: DragEvent) => {
+    if (isDisabled()) return;
+    e.preventDefault();
+    dragCounter++;
+    if (dragCounter === 1) {
+      setIsOver(true);
+      options.onDragEnter?.(e);
+    }
+  };
+
+  const onDragOver = (e: DragEvent) => {
+    if (isDisabled()) return;
+    e.preventDefault();
+    if (e.dataTransfer) {
+      e.dataTransfer.dropEffect = "copy";
+    }
+    options.onDragOver?.(e);
+  };
+
+  const onDragLeave = (e: DragEvent) => {
+    if (isDisabled()) return;
+    e.preventDefault();
+    dragCounter--;
+    if (dragCounter <= 0) {
+      dragCounter = 0;
+      setIsOver(false);
+      options.onDragLeave?.(e);
+    }
+  };
+
+  const onDrop = (e: DragEvent) => {
+    if (isDisabled()) return;
+    e.preventDefault();
+    dragCounter = 0;
+    setIsOver(false);
+
+    if (e.dataTransfer?.files && e.dataTransfer.files.length > 0) {
+      processFiles(Array.from(e.dataTransfer.files), e);
+    }
+  };
+
+  const clear = () => {
+    setFilesInternal([]);
+    setRejectedFilesInternal([]);
+    options.onFilesChanged?.([]);
+  };
+
+  const setFiles = (newFiles: File[]) => {
+    const dummyEvent = new Event("drop") as unknown as DragEvent;
+    processFiles(newFiles, dummyEvent);
+  };
+
+  const openFileDialog = () => {
+    if (typeof document === "undefined" || isDisabled()) return;
+    const input = document.createElement("input");
+    input.type = "file";
+    if (options.multiple !== false && (options.maxFiles === undefined || options.maxFiles > 1)) {
+      input.multiple = true;
+    }
+    if (options.accept) {
+      input.accept = Array.isArray(options.accept) ? options.accept.join(",") : options.accept;
+    }
+    input.onchange = (e) => {
+      const target = e.target as HTMLInputElement;
+      if (target.files && target.files.length > 0) {
+        processFiles(Array.from(target.files), e as unknown as DragEvent);
+      }
+    };
+    input.click();
+  };
+
+  const ref = (el: HTMLElement) => {
+    targetElement = el;
+  };
+
+  // Window-level drag detection and document drop prevention
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const handleWindowDragEnter = (e: DragEvent) => {
+      windowDragCounter++;
+      if (windowDragCounter === 1) {
+        setIsDragging(true);
+      }
+    };
+
+    const handleWindowDragLeave = (e: DragEvent) => {
+      windowDragCounter--;
+      if (windowDragCounter <= 0) {
+        windowDragCounter = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleWindowDrop = (e: DragEvent) => {
+      windowDragCounter = 0;
+      setIsDragging(false);
+      if (options.preventDropOnDocument !== false) {
+        e.preventDefault();
+      }
+    };
+
+    const handleWindowDragOver = (e: DragEvent) => {
+      if (options.preventDropOnDocument !== false) {
+        e.preventDefault();
+      }
+    };
+
+    window.addEventListener("dragenter", handleWindowDragEnter);
+    window.addEventListener("dragleave", handleWindowDragLeave);
+    window.addEventListener("dragover", handleWindowDragOver);
+    window.addEventListener("drop", handleWindowDrop);
+
+    onCleanup(() => {
+      window.removeEventListener("dragenter", handleWindowDragEnter);
+      window.removeEventListener("dragleave", handleWindowDragLeave);
+      window.removeEventListener("dragover", handleWindowDragOver);
+      window.removeEventListener("drop", handleWindowDrop);
+    });
+  });
+
+  return {
+    isOver,
+    isDragging,
+    files,
+    rejectedFiles,
+    clear,
+    setFiles,
+    openFileDialog,
+    ref,
+    props: {
+      onDragEnter,
+      onDragLeave,
+      onDragOver,
+      onDrop,
+    },
+  };
+}

package/src/create-pagination.ts

@@ -0,0 +1,208 @@
+import { createSignal, createMemo, type Accessor } from "solid-js";
+
+export interface CreatePaginationOptions {
+  /** Total number of items across all pages, or total count. */
+  count?: number | Accessor<number>;
+  /** Explicit total number of pages. If provided, overrides count / pageSize calculation. */
+  totalPages?: number | Accessor<number>;
+  /** Controlled active page number (1-indexed). */
+  page?: number | Accessor<number>;
+  /** Default active page number for uncontrolled state. Defaults to 1. */
+  defaultPage?: number;
+  /** Number of items per page. Defaults to 10. */
+  pageSize?: number | Accessor<number>;
+  /** Number of sibling page buttons visible on each side of the current active page. Defaults to 1. */
+  siblingCount?: number | Accessor<number>;
+  /** Number of boundary pages visible at the beginning and end. Defaults to 1. */
+  boundaries?: number | Accessor<number>;
+  /** Callback fired whenever the active page changes. */
+  onChange?: (page: number) => void;
+}
+
+export interface CreatePaginationReturn {
+  /** Accessor returning the current active page number (1-indexed). */
+  page: Accessor<number>;
+  /** Accessor returning the calculated total number of pages. */
+  totalPages: Accessor<number>;
+  /** Accessor returning the active page size. */
+  pageSize: Accessor<number>;
+  /** Accessor returning an array of page numbers and "ellipsis" strings. */
+  range: Accessor<(number | "ellipsis")[]>;
+  /** Function to programmatically change to a specific page number. */
+  setPage: (page: number) => void;
+  /** Function to navigate to the next page. */
+  next: () => void;
+  /** Function to navigate to the previous page. */
+  previous: () => void;
+  /** Function to navigate to the first page (1). */
+  first: () => void;
+  /** Function to navigate to the last page (totalPages). */
+  last: () => void;
+  /** Accessor indicating whether a next page exists. */
+  hasNext: Accessor<boolean>;
+  /** Accessor indicating whether a previous page exists. */
+  hasPrevious: Accessor<boolean>;
+  /** 1-based start index of items on the current page (e.g. 1 for page 1 with pageSize 10). */
+  startIndex: Accessor<number>;
+  /** 1-based end index of items on the current page (e.g. 10 for page 1 with pageSize 10). */
+  endIndex: Accessor<number>;
+}
+
+/**
+ * SolidJS reactive primitive for computing pagination state, dynamic page range with ellipses, and navigation helpers.
+ *
+ * @param options Pagination configuration options.
+ */
+export function createPagination(options: CreatePaginationOptions = {}): CreatePaginationReturn {
+  const getCount = () => {
+    const raw = typeof options.count === "function" ? options.count() : options.count ?? 0;
+    return Math.max(0, raw);
+  };
+
+  const getPageSize = () => {
+    const raw = typeof options.pageSize === "function" ? options.pageSize() : options.pageSize ?? 10;
+    return Math.max(1, raw);
+  };
+
+  const getExplicitTotalPages = () => {
+    const raw = typeof options.totalPages === "function" ? options.totalPages() : options.totalPages;
+    return raw !== undefined ? Math.max(1, raw) : undefined;
+  };
+
+  const getSiblingCount = () => {
+    const raw = typeof options.siblingCount === "function" ? options.siblingCount() : options.siblingCount ?? 1;
+    return Math.max(0, raw);
+  };
+
+  const getBoundaries = () => {
+    const raw = typeof options.boundaries === "function" ? options.boundaries() : options.boundaries ?? 1;
+    return Math.max(0, raw);
+  };
+
+  const [internalPage, setInternalPage] = createSignal<number>(Math.max(1, options.defaultPage ?? 1));
+
+  const totalPages = createMemo<number>(() => {
+    const explicit = getExplicitTotalPages();
+    if (explicit !== undefined) {
+      return Math.max(1, explicit);
+    }
+    const count = getCount();
+    const size = getPageSize();
+    return Math.max(1, Math.ceil(count / size));
+  });
+
+  const rawPage = () => {
+    if (typeof options.page === "function") {
+      return options.page();
+    }
+    if (typeof options.page === "number") {
+      return options.page;
+    }
+    return internalPage();
+  };
+
+  const page = createMemo<number>(() => {
+    const p = rawPage();
+    const max = totalPages();
+    if (p < 1) return 1;
+    if (p > max) return max;
+    return p;
+  });
+
+  const setPage = (nextPage: number) => {
+    const max = totalPages();
+    const clamped = Math.max(1, Math.min(nextPage, max));
+    if (typeof options.page !== "function" && typeof options.page !== "number") {
+      setInternalPage(clamped);
+    }
+    options.onChange?.(clamped);
+  };
+
+  const next = () => setPage(page() + 1);
+  const previous = () => setPage(page() - 1);
+  const first = () => setPage(1);
+  const last = () => setPage(totalPages());
+
+  const hasNext = createMemo(() => page() < totalPages());
+  const hasPrevious = createMemo(() => page() > 1);
+
+  const startIndex = createMemo(() => {
+    const count = getCount();
+    if (count === 0 && getExplicitTotalPages() === undefined) return 0;
+    return (page() - 1) * getPageSize() + 1;
+  });
+
+  const endIndex = createMemo(() => {
+    const count = getCount();
+    const calculated = page() * getPageSize();
+    if (count > 0) {
+      return Math.min(calculated, count);
+    }
+    return calculated;
+  });
+
+  const range = createMemo<(number | "ellipsis")[]>(() => {
+    const total = totalPages();
+    const current = page();
+    const siblings = getSiblingCount();
+    const boundaries = getBoundaries();
+
+    if (total <= 1) {
+      return [1];
+    }
+
+    const pagesSet = new Set<number>();
+
+    // 1. Boundary pages at the start
+    for (let i = 1; i <= Math.min(boundaries, total); i++) {
+      pagesSet.add(i);
+    }
+
+    // 2. Sibling pages around current page
+    const leftSibling = Math.max(1, current - siblings);
+    const rightSibling = Math.min(total, current + siblings);
+    for (let i = leftSibling; i <= rightSibling; i++) {
+      pagesSet.add(i);
+    }
+
+    // 3. Boundary pages at the end
+    for (let i = Math.max(1, total - boundaries + 1); i <= total; i++) {
+      pagesSet.add(i);
+    }
+
+    const sortedPages = Array.from(pagesSet).sort((a, b) => a - b);
+    const result: (number | "ellipsis")[] = [];
+
+    for (let i = 0; i < sortedPages.length; i++) {
+      const currentPageNum = sortedPages[i];
+      if (i > 0) {
+        const prevPageNum = sortedPages[i - 1];
+        const gap = currentPageNum - prevPageNum;
+        if (gap === 2) {
+          result.push(prevPageNum + 1);
+        } else if (gap > 2) {
+          result.push("ellipsis");
+        }
+      }
+      result.push(currentPageNum);
+    }
+
+    return result;
+  });
+
+  return {
+    page,
+    totalPages,
+    pageSize: getPageSize,
+    range,
+    setPage,
+    next,
+    previous,
+    first,
+    last,
+    hasNext,
+    hasPrevious,
+    startIndex,
+    endIndex,
+  };
+}

package/src/index.ts

@@ -37,4 +37,7 @@ export * from "./create-websocket";
 export * from "./create-document-title";
 export * from "./create-favicon";
 export * from "./create-event-source";
-export * from "./create-scroll-into-view";
+export * from "./create-scroll-into-view";
+export * from "./create-drop-zone";
+export * from "./create-pagination";
+export * from "./create-chat-scroll";