@nikala-ui/hooks 0.10.1 → 0.11.0-nightly.b01fa01

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-global-shortcut.ts

@@ -0,0 +1,140 @@
+import { onMount, onCleanup } from "solid-js";
+import { isTauriEnvironment } from "./create-tauri-window";
+
+export interface CreateGlobalShortcutOptions {
+  /** Shortcut key combination, e.g. 'CommandOrControl+Shift+P' or 'Alt+Space'. */
+  shortcut: string | string[];
+  /** Handler invoked when global shortcut is triggered. */
+  onTrigger: (shortcut: string) => void;
+  /** Automatically register shortcut on mount. Defaults to true. */
+  autoRegister?: boolean;
+}
+
+export interface CreateGlobalShortcutReturn {
+  /** Register the configured global shortcut with Tauri / Browser. */
+  register: () => Promise<boolean>;
+  /** Unregister the shortcut. */
+  unregister: () => Promise<void>;
+  /** Indicates whether the shortcut is currently registered. */
+  isRegistered: () => boolean;
+}
+
+/**
+ * SolidJS reactive primitive for registering native OS global hotkeys via Tauri v2 global shortcut plugin,
+ * with automatic fallback to browser DOM keyboard listeners.
+ */
+export function createGlobalShortcut(
+  options: CreateGlobalShortcutOptions
+): CreateGlobalShortcutReturn {
+  let registered = false;
+  const shortcuts = Array.isArray(options.shortcut) ? options.shortcut : [options.shortcut];
+
+  const getTauriShortcutPlugin = async () => {
+    if (typeof window === "undefined") return null;
+    try {
+      if ((window as any).__TAURI__?.globalShortcut) {
+        return (window as any).__TAURI__.globalShortcut;
+      }
+      // Variable prevents Vite dev server from static module resolution
+      const moduleName = "@tauri-apps/plugin-global-shortcut";
+      // @ts-ignore - Optional runtime dependency in Tauri apps
+      const plugin = await import(/* @vite-ignore */ moduleName).catch(() => null);
+      return plugin;
+    } catch {
+      return null;
+    }
+  };
+
+  const normalizeKey = (k: string) => {
+    const key = k.toLowerCase().trim();
+    if (key === " " || key === "space" || key === "spacebar") return "space";
+    if (key === "esc" || key === "escape") return "escape";
+    if (key === "return" || key === "enter") return "enter";
+    return key;
+  };
+
+  const handleBrowserKeydown = (e: KeyboardEvent) => {
+    const eventKey = normalizeKey(e.key);
+    const eventCode = normalizeKey(e.code.replace(/^Key|^Digit/, ""));
+
+    for (const keyCombo of shortcuts) {
+      const parts = keyCombo.toLowerCase().split("+");
+      const hasCtrlOrCmd = parts.includes("commandorcontrol") || parts.includes("ctrl") || parts.includes("cmd");
+      const hasShift = parts.includes("shift");
+      const hasAlt = parts.includes("alt");
+      const mainKey = parts.find((p) => !["commandorcontrol", "ctrl", "cmd", "shift", "alt"].includes(p));
+
+      const ctrlMatch = hasCtrlOrCmd ? e.ctrlKey || e.metaKey : !e.ctrlKey && !e.metaKey;
+      const shiftMatch = hasShift ? e.shiftKey : !e.shiftKey;
+      const altMatch = hasAlt ? e.altKey : !e.altKey;
+      const keyMatch = mainKey
+        ? eventKey === normalizeKey(mainKey) || eventCode === normalizeKey(mainKey)
+        : false;
+
+      if (ctrlMatch && shiftMatch && altMatch && keyMatch) {
+        e.preventDefault();
+        options.onTrigger(keyCombo);
+        break;
+      }
+    }
+  };
+
+  const register = async (): Promise<boolean> => {
+    if (typeof window === "undefined") return false;
+
+    if (isTauriEnvironment()) {
+      const plugin = await getTauriShortcutPlugin();
+      if (plugin?.register) {
+        try {
+          for (const s of shortcuts) {
+            await plugin.register(s, () => options.onTrigger(s));
+          }
+          registered = true;
+          return true;
+        } catch {
+          // Fallback to web listener
+        }
+      }
+    }
+
+    window.addEventListener("keydown", handleBrowserKeydown);
+    registered = true;
+    return true;
+  };
+
+  const unregister = async (): Promise<void> => {
+    if (typeof window === "undefined") return;
+
+    if (isTauriEnvironment()) {
+      const plugin = await getTauriShortcutPlugin();
+      if (plugin?.unregister) {
+        try {
+          for (const s of shortcuts) {
+            await plugin.unregister(s);
+          }
+        } catch {
+          // Handled
+        }
+      }
+    }
+
+    window.removeEventListener("keydown", handleBrowserKeydown);
+    registered = false;
+  };
+
+  onMount(() => {
+    if (options.autoRegister !== false) {
+      register();
+    }
+  });
+
+  onCleanup(() => {
+    unregister();
+  });
+
+  return {
+    register,
+    unregister,
+    isRegistered: () => registered,
+  };
+}

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,
+  };
+}