@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-src/create-document-tabs.ts

@@ -0,0 +1,267 @@
+import {
+  createSignal,
+  createMemo,
+  onMount,
+  onCleanup,
+  type Accessor,
+} from "solid-js";
+
+export interface TabItem<T = any> {
+  id: string;
+  title: string;
+  icon?: any;
+  isDirty?: boolean;
+  isPinned?: boolean;
+  closable?: boolean;
+  data?: T;
+}
+
+export interface CreateDocumentTabsOptions<T = any> {
+  /** Initial array of tab items. */
+  initialTabs?: TabItem<T>[];
+  /** Default active tab id. Defaults to first tab if available. */
+  defaultActiveId?: string;
+  /** Whether to enable keyboard shortcuts (Ctrl/Cmd+W to close active, Ctrl/Cmd+T for new tab). */
+  enableKeybindings?: boolean;
+  /** Callback triggered when the active tab changes. */
+  onTabChange?: (tab: TabItem<T> | undefined) => void;
+  /** Callback triggered before or when a tab closes. Return false to prevent closing. */
+  onTabClose?: (tab: TabItem<T>) => boolean | void;
+  /** Callback triggered when a new tab is created. */
+  onTabAdd?: (tab: TabItem<T>) => void;
+}
+
+export interface CreateDocumentTabsReturn<T = any> {
+  /** All tabs list. */
+  tabs: Accessor<TabItem<T>[]>;
+  /** Currently active tab ID. */
+  activeTabId: Accessor<string>;
+  /** Currently active tab object. */
+  activeTab: Accessor<TabItem<T> | undefined>;
+  /** Pinned tabs only. */
+  pinnedTabs: Accessor<TabItem<T>[]>;
+  /** Standard unpinned tabs. */
+  unpinnedTabs: Accessor<TabItem<T>[]>;
+  /** Whether any open tab has unsaved changes (isDirty). */
+  hasDirtyTabs: Accessor<boolean>;
+  /** Count of total open tabs. */
+  count: Accessor<number>;
+  /** Add a new tab to the list. */
+  addTab: (tab: TabItem<T>, activate?: boolean) => void;
+  /** Close a tab by ID with auto-switching to adjacent tab. */
+  closeTab: (id: string) => boolean;
+  /** Set the active tab. */
+  setActiveTab: (id: string) => void;
+  /** Mark or unmark a tab as dirty (unsaved changes). */
+  markDirty: (id: string, isDirty?: boolean) => void;
+  /** Toggle pinned state of a tab. */
+  togglePin: (id: string) => void;
+  /** Close all tabs except the specified one. */
+  closeOthers: (id: string) => void;
+  /** Close all open unpinned tabs. */
+  closeAll: (includePinned?: boolean) => void;
+  /** Switch to the next tab in sequence. */
+  nextTab: () => void;
+  /** Switch to the previous tab in sequence. */
+  prevTab: () => void;
+  /** Reorder tabs from one position to another. */
+  reorderTabs: (fromIndex: number, toIndex: number) => void;
+}
+
+function findLastPinnedIndex<T>(items: TabItem<T>[]): number {
+  for (let i = items.length - 1; i >= 0; i--) {
+    if (items[i].isPinned) return i;
+  }
+  return -1;
+}
+
+/**
+ * SolidJS reactive primitive for managing multi-document tabs, editor buffers, and browser tab states.
+ */
+export function createDocumentTabs<T = any>(
+  options: CreateDocumentTabsOptions<T> = {}
+): CreateDocumentTabsReturn<T> {
+  const initial = options.initialTabs || [];
+  const [tabs, setTabs] = createSignal<TabItem<T>[]>(initial);
+  const [activeTabId, setActiveTabId] = createSignal<string>(
+    options.defaultActiveId || (initial.length > 0 ? initial[0].id : "")
+  );
+
+  const activeTab = createMemo(() => tabs().find((t) => t.id === activeTabId()));
+  const pinnedTabs = createMemo(() => tabs().filter((t) => t.isPinned));
+  const unpinnedTabs = createMemo(() => tabs().filter((t) => !t.isPinned));
+  const hasDirtyTabs = createMemo(() => tabs().some((t) => t.isDirty));
+  const count = createMemo(() => tabs().length);
+
+  const setActive = (id: string) => {
+    const target = tabs().find((t) => t.id === id);
+    if (target) {
+      setActiveTabId(id);
+      options.onTabChange?.(target);
+    }
+  };
+
+  const addTab = (tab: TabItem<T>, activate = true) => {
+    const existing = tabs().find((t) => t.id === tab.id);
+    if (existing) {
+      if (activate) setActive(tab.id);
+      return;
+    }
+
+    setTabs((prev) => {
+      if (tab.isPinned) {
+        const lastPinnedIdx = findLastPinnedIndex(prev);
+        if (lastPinnedIdx === -1) return [tab, ...prev];
+        const next = [...prev];
+        next.splice(lastPinnedIdx + 1, 0, tab);
+        return next;
+      }
+      return [...prev, tab];
+    });
+
+    if (activate) {
+      setActiveTabId(tab.id);
+      options.onTabChange?.(tab);
+    }
+    options.onTabAdd?.(tab);
+  };
+
+  const closeTab = (id: string): boolean => {
+    const currentTabs = tabs();
+    const tabToClose = currentTabs.find((t) => t.id === id);
+    if (!tabToClose) return false;
+
+    if (options.onTabClose && options.onTabClose(tabToClose) === false) {
+      return false;
+    }
+
+    const closeIdx = currentTabs.findIndex((t) => t.id === id);
+    const nextTabs = currentTabs.filter((t) => t.id !== id);
+    setTabs(nextTabs);
+
+    if (activeTabId() === id) {
+      if (nextTabs.length === 0) {
+        setActiveTabId("");
+        options.onTabChange?.(undefined);
+      } else {
+        const nextIdx = Math.min(closeIdx, nextTabs.length - 1);
+        const nextActive = nextTabs[nextIdx];
+        setActiveTabId(nextActive.id);
+        options.onTabChange?.(nextActive);
+      }
+    }
+    return true;
+  };
+
+  const markDirty = (id: string, isDirty = true) => {
+    setTabs((prev) =>
+      prev.map((t) => (t.id === id ? { ...t, isDirty } : t))
+    );
+  };
+
+  const togglePin = (id: string) => {
+    setTabs((prev) => {
+      const target = prev.find((t) => t.id === id);
+      if (!target) return prev;
+      const updated = { ...target, isPinned: !target.isPinned };
+      const remaining = prev.filter((t) => t.id !== id);
+
+      if (updated.isPinned) {
+        const lastPinnedIdx = findLastPinnedIndex(remaining);
+        if (lastPinnedIdx === -1) return [updated, ...remaining];
+        remaining.splice(lastPinnedIdx + 1, 0, updated);
+        return remaining;
+      }
+      return [...remaining, updated];
+    });
+  };
+
+  const closeOthers = (id: string) => {
+    setTabs((prev) => prev.filter((t) => t.id === id || t.isPinned));
+    setActive(id);
+  };
+
+  const closeAll = (includePinned = false) => {
+    if (includePinned) {
+      setTabs([]);
+      setActiveTabId("");
+      options.onTabChange?.(undefined);
+    } else {
+      const pinned = tabs().filter((t) => t.isPinned);
+      setTabs(pinned);
+      if (pinned.length > 0) {
+        setActiveTabId(pinned[0].id);
+        options.onTabChange?.(pinned[0]);
+      } else {
+        setActiveTabId("");
+        options.onTabChange?.(undefined);
+      }
+    }
+  };
+
+  const nextTab = () => {
+    const list = tabs();
+    if (list.length <= 1) return;
+    const currentIdx = list.findIndex((t) => t.id === activeTabId());
+    const nextIdx = (currentIdx + 1) % list.length;
+    setActive(list[nextIdx].id);
+  };
+
+  const prevTab = () => {
+    const list = tabs();
+    if (list.length <= 1) return;
+    const currentIdx = list.findIndex((t) => t.id === activeTabId());
+    const prevIdx = (currentIdx - 1 + list.length) % list.length;
+    setActive(list[prevIdx].id);
+  };
+
+  const reorderTabs = (fromIndex: number, toIndex: number) => {
+    setTabs((prev) => {
+      if (fromIndex < 0 || fromIndex >= prev.length || toIndex < 0 || toIndex >= prev.length) {
+        return prev;
+      }
+      const clone = [...prev];
+      const [moved] = clone.splice(fromIndex, 1);
+      clone.splice(toIndex, 0, moved);
+      return clone;
+    });
+  };
+
+  onMount(() => {
+    if (!options.enableKeybindings || typeof window === "undefined") return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isCmdOrCtrl = e.metaKey || e.ctrlKey;
+      if (isCmdOrCtrl && (e.key === "w" || e.key === "W")) {
+        const active = activeTabId();
+        if (active) {
+          e.preventDefault();
+          closeTab(active);
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    onCleanup(() => window.removeEventListener("keydown", handleKeyDown));
+  });
+
+  return {
+    tabs,
+    activeTabId,
+    activeTab,
+    pinnedTabs,
+    unpinnedTabs,
+    hasDirtyTabs,
+    count,
+    addTab,
+    closeTab,
+    setActiveTab: setActive,
+    markDirty,
+    togglePin,
+    closeOthers,
+    closeAll,
+    nextTab,
+    prevTab,
+    reorderTabs,
+  };
+}

package/dist/vendor/hooks-src/create-document-title.ts

@@ -0,0 +1,33 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateDocumentTitleOptions {
+  /** Whether to restore original title on component unmount. Defaults to true. */
+  restoreOnUnmount?: boolean;
+}
+
+/**
+ * SolidJS reactive primitive for managing document title dynamically.
+ */
+export function createDocumentTitle(
+  title: string | Accessor<string>,
+  options: CreateDocumentTitleOptions = {}
+): void {
+  const getTitle = (): string => (typeof title === "function" ? title() : title);
+
+  createEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const originalTitle = document.title;
+    const newTitle = getTitle();
+
+    if (newTitle) {
+      document.title = newTitle;
+    }
+
+    onCleanup(() => {
+      if (typeof document !== "undefined" && (options.restoreOnUnmount ?? true)) {
+        document.title = originalTitle;
+      }
+    });
+  });
+}

package/dist/vendor/hooks-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,
+    },
+  };
+}