@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-src/create-geolocation.ts

@@ -0,0 +1,140 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateGeolocationOptions extends PositionOptions {
+  /** Whether to start watching position immediately upon primitive initialization. Defaults to true. */
+  immediate?: boolean;
+}
+
+export interface GeolocationState {
+  /** Current latitude coordinate in degrees. */
+  latitude: number | null;
+  /** Current longitude coordinate in degrees. */
+  longitude: number | null;
+  /** Current altitude above sea level in meters. */
+  altitude: number | null;
+  /** Position accuracy level in meters. */
+  accuracy: number | null;
+  /** Altitude accuracy in meters. */
+  altitudeAccuracy: number | null;
+  /** Current heading direction in degrees relative to true north. */
+  heading: number | null;
+  /** Current speed in meters per second. */
+  speed: number | null;
+  /** Timestamp when location was captured. */
+  timestamp: number | null;
+}
+
+export interface CreateGeolocationReturn {
+  /** Signal accessor containing current geolocation coordinates and metrics. */
+  coords: Accessor<GeolocationState>;
+  /** Signal accessor indicating whether position retrieval is in progress. */
+  loading: Accessor<boolean>;
+  /** Signal accessor containing GeolocationPositionError if request failed. */
+  error: Accessor<GeolocationPositionError | Error | null>;
+  /** Signal accessor indicating whether Geolocation API is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+  /** Imperative function to fetch current position once. */
+  getCurrentPosition: () => void;
+}
+
+const initialCoords: GeolocationState = {
+  latitude: null,
+  longitude: null,
+  altitude: null,
+  accuracy: null,
+  altitudeAccuracy: null,
+  heading: null,
+  speed: null,
+  timestamp: null,
+};
+
+/**
+ * SolidJS reactive primitive for tracking user geographic location and GPS metrics.
+ */
+export function createGeolocation(
+  options: CreateGeolocationOptions = {}
+): CreateGeolocationReturn {
+  const [coords, setCoords] = createSignal<GeolocationState>(initialCoords);
+  const [loading, setLoading] = createSignal(false);
+  const [error, setError] = createSignal<GeolocationPositionError | Error | null>(null);
+
+  const isSupported = (): boolean => {
+    if (typeof window === "undefined" || typeof navigator === "undefined") return false;
+    return "geolocation" in navigator;
+  };
+
+  const getOptions = (): PositionOptions => ({
+    timeout: options.timeout ?? 10000,
+    maximumAge: options.maximumAge ?? 5000,
+    enableHighAccuracy: options.enableHighAccuracy ?? false,
+  });
+
+  let watchId: number | null = null;
+
+  const updatePosition = (position: GeolocationPosition): void => {
+    setCoords({
+      latitude: position.coords.latitude,
+      longitude: position.coords.longitude,
+      altitude: position.coords.altitude,
+      accuracy: position.coords.accuracy,
+      altitudeAccuracy: position.coords.altitudeAccuracy,
+      heading: position.coords.heading,
+      speed: position.coords.speed,
+      timestamp: position.timestamp,
+    });
+    setLoading(false);
+    setError(null);
+  };
+
+  const handleError = (err: GeolocationPositionError): void => {
+    setError(err);
+    setLoading(false);
+  };
+
+  const getCurrentPosition = (): void => {
+    if (!isSupported()) {
+      setError(new Error("Geolocation API is not supported in this browser environment."));
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    navigator.geolocation.getCurrentPosition(
+      (pos) => {
+        updatePosition(pos);
+      },
+      (err) => {
+        handleError(err);
+      },
+      getOptions()
+    );
+  };
+
+  createEffect(() => {
+    if (!isSupported()) return;
+
+    if (options.immediate ?? true) {
+      setLoading(true);
+      watchId = navigator.geolocation.watchPosition(
+        updatePosition,
+        handleError,
+        getOptions()
+      );
+    }
+
+    onCleanup(() => {
+      if (watchId !== null && typeof window !== "undefined" && "geolocation" in navigator) {
+        navigator.geolocation.clearWatch(watchId);
+      }
+    });
+  });
+
+  return {
+    coords,
+    loading,
+    error,
+    isSupported,
+    getCurrentPosition,
+  };
+}

package/dist/vendor/hooks-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/dist/vendor/hooks-src/create-hover.ts

@@ -0,0 +1,88 @@
+import { createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateHoverOptions {
+  /** Delay in milliseconds before setting hover state to true */
+  delayEnter?: number;
+  /** Delay in milliseconds before setting hover state to false */
+  delayLeave?: number;
+  /** Callback fired when hover state transitions to true */
+  onHoverStart?: () => void;
+  /** Callback fired when hover state transitions to false */
+  onHoverEnd?: () => void;
+}
+
+export interface CreateHoverReturn {
+  /** Accessor indicating whether target element is hovered */
+  isHovered: Accessor<boolean>;
+  /** Event listeners props to spread onto target JSX element */
+  props: {
+    onPointerEnter: (e: PointerEvent) => void;
+    onPointerLeave: (e: PointerEvent) => void;
+  };
+}
+
+/**
+ * SolidJS reactive primitive for tracking element hover state with optional entrance/exit delays.
+ *
+ * @param options Configuration options for hover delays and callbacks.
+ */
+export function createHover(options: CreateHoverOptions = {}): CreateHoverReturn {
+  const [isHovered, setIsHovered] = createSignal(false);
+  let enterTimer: ReturnType<typeof setTimeout> | undefined;
+  let leaveTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearTimers = () => {
+    if (enterTimer) {
+      clearTimeout(enterTimer);
+      enterTimer = undefined;
+    }
+    if (leaveTimer) {
+      clearTimeout(leaveTimer);
+      leaveTimer = undefined;
+    }
+  };
+
+  const onPointerEnter = () => {
+    clearTimers();
+    const delay = options.delayEnter ?? 0;
+
+    if (delay > 0) {
+      enterTimer = setTimeout(() => {
+        setIsHovered(true);
+        options.onHoverStart?.();
+        enterTimer = undefined;
+      }, delay);
+    } else {
+      setIsHovered(true);
+      options.onHoverStart?.();
+    }
+  };
+
+  const onPointerLeave = () => {
+    clearTimers();
+    const delay = options.delayLeave ?? 0;
+
+    if (delay > 0) {
+      leaveTimer = setTimeout(() => {
+        setIsHovered(false);
+        options.onHoverEnd?.();
+        leaveTimer = undefined;
+      }, delay);
+    } else {
+      setIsHovered(false);
+      options.onHoverEnd?.();
+    }
+  };
+
+  onCleanup(() => {
+    clearTimers();
+  });
+
+  return {
+    isHovered,
+    props: {
+      onPointerEnter,
+      onPointerLeave,
+    },
+  };
+}

package/dist/vendor/hooks-src/create-idle.ts

@@ -0,0 +1,109 @@
+import { createSignal, onMount, onCleanup, type Accessor } from "solid-js";
+import { isServer } from "solid-js/web";
+
+export interface CreateIdleOptions {
+  /** Timeout in milliseconds before user is considered idle (default: 60000 = 60s) */
+  timeout?: number;
+  /** Initial idle state (default: false) */
+  initialState?: boolean;
+  /** DOM events to listen for user activity */
+  events?: string[];
+  /** Callback fired when user becomes idle */
+  onIdle?: () => void;
+  /** Callback fired when user becomes active after being idle */
+  onActive?: () => void;
+}
+
+export interface CreateIdleReturn {
+  /** Accessor returning true if user has been inactive for timeout period */
+  isIdle: Accessor<boolean>;
+  /** Accessor returning timestamp in ms of last detected user interaction */
+  lastActive: Accessor<number>;
+  /** Reset idle state and restart timer */
+  reset: () => void;
+}
+
+const DEFAULT_EVENTS = [
+  "mousemove",
+  "mousedown",
+  "keydown",
+  "touchstart",
+  "scroll",
+  "wheel",
+];
+
+/**
+ * SolidJS reactive primitive for detecting user inactivity (idle state) with customizable timeout and event triggers.
+ *
+ * @param options Configuration options including timeout in ms and event handlers.
+ */
+export function createIdle(options: CreateIdleOptions = {}): CreateIdleReturn {
+  const initialIdle = options.initialState ?? false;
+
+  // SSR: return static defaults — no timers, no listeners
+  if (isServer) {
+    const [isIdle] = createSignal(initialIdle);
+    const [lastActive] = createSignal(0);
+    return { isIdle, lastActive, reset: () => {} };
+  }
+
+  const timeoutMs = options.timeout ?? 60000;
+  const events = options.events ?? DEFAULT_EVENTS;
+
+  const [isIdle, setIsIdle] = createSignal(initialIdle);
+  const [lastActive, setLastActive] = createSignal(0);
+
+  let timerId: any = null;
+
+  const startTimer = () => {
+    if (timerId) clearTimeout(timerId);
+    timerId = setTimeout(() => {
+      if (!isIdle()) {
+        setIsIdle(true);
+        if (options.onIdle) options.onIdle();
+      }
+    }, timeoutMs);
+  };
+
+  const handleUserActivity = () => {
+    setLastActive(Date.now());
+
+    if (isIdle()) {
+      setIsIdle(false);
+      if (options.onActive) options.onActive();
+    }
+
+    startTimer();
+  };
+
+  const reset = () => {
+    setLastActive(Date.now());
+    setIsIdle(false);
+    startTimer();
+  };
+
+  onMount(() => {
+    // Set initial lastActive to now on client mount
+    setLastActive(Date.now());
+
+    events.forEach((evt) => {
+      window.addEventListener(evt, handleUserActivity, { passive: true });
+    });
+
+    startTimer();
+
+    onCleanup(() => {
+      if (timerId) clearTimeout(timerId);
+      events.forEach((evt) => {
+        window.removeEventListener(evt, handleUserActivity);
+      });
+    });
+  });
+
+  return {
+    isIdle,
+    lastActive,
+    reset,
+  };
+}
+

package/dist/vendor/hooks-src/create-infinite-scroll.ts

@@ -0,0 +1,90 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateInfiniteScrollOptions {
+  /** Target element to observe or trigger scroll on. Defaults to document / scroll parent. */
+  target?: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Distance threshold from bottom in pixels to trigger fetch. Defaults to 100. */
+  threshold?: number;
+  /** Whether loading is currently enabled or auto-fetching is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Callback function when scrolled near bottom to fetch next items. */
+  onLoadMore: () => Promise<void> | void;
+}
+
+export interface CreateInfiniteScrollReturn {
+  /** Sentinel ref function to bind to a DOM element at the bottom of the list. */
+  setSentinelRef: (el: HTMLElement | null) => void;
+  /** Signal indicating whether fetching is currently in progress. */
+  isLoading: Accessor<boolean>;
+  /** Signal indicating whether an error occurred during last fetch. */
+  error: Accessor<Error | null>;
+  /** Imperative function to manually trigger next page load. */
+  loadMore: () => Promise<void>;
+}
+
+/**
+ * SolidJS reactive primitive for dynamic infinite scrolling / auto-fetching.
+ */
+export function createInfiniteScroll(
+  options: CreateInfiniteScrollOptions
+): CreateInfiniteScrollReturn {
+  const [sentinelEl, setSentinelEl] = createSignal<HTMLElement | null>(null);
+  const [isLoading, setIsLoading] = createSignal(false);
+  const [error, setError] = createSignal<Error | null>(null);
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  const loadMore = async (): Promise<void> => {
+    if (isLoading() || !isEnabled()) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      await options.onLoadMore();
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined" || !window.IntersectionObserver) return;
+    if (!isEnabled()) return;
+
+    const el = sentinelEl();
+    if (!el) return;
+
+    const rootMargin = `${options.threshold ?? 100}px`;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (entry?.isIntersecting && !isLoading()) {
+          loadMore();
+        }
+      },
+      {
+        rootMargin,
+        threshold: 0,
+      }
+    );
+
+    observer.observe(el);
+
+    onCleanup(() => {
+      observer.disconnect();
+    });
+  });
+
+  return {
+    setSentinelRef: setSentinelEl,
+    isLoading,
+    error,
+    loadMore,
+  };
+}

package/dist/vendor/hooks-src/create-input-mask.ts

@@ -0,0 +1,109 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateInputMaskOptions {
+  /** Mask pattern template (e.g. '+995 ### ##-##-##' or '#### #### #### ####') */
+  mask: string;
+  /** Initial default value */
+  defaultValue?: string;
+}
+
+export interface CreateInputMaskReturn {
+  /** Accessor returning formatted masked input string */
+  value: Accessor<string>;
+  /** Accessor returning raw unmasked user digits string */
+  unmaskedValue: Accessor<string>;
+  /** Function to programmatically update input value */
+  setValue: (val: string) => void;
+  /** JSX props object to spread onto target HTMLInputElement */
+  props: {
+    value: () => string;
+    onInput: (e: Event & { currentTarget: HTMLInputElement }) => void;
+  };
+}
+
+/**
+ * Format raw unmasked text against a mask pattern template.
+ */
+export function formatMask(rawInput: string, pattern: string): { masked: string; unmasked: string } {
+  if (!rawInput) {
+    return { masked: "", unmasked: "" };
+  }
+
+  // Find static prefix of pattern before first slot placeholder (#, 0, X)
+  let staticPrefix = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "#" || char === "0" || char === "X") break;
+    staticPrefix += char;
+  }
+  const staticPrefixDigits = staticPrefix.replace(/\D/g, "");
+
+  let digits = rawInput.replace(/\D/g, "");
+
+  // Strip static prefix digits if present at the start
+  if (staticPrefixDigits && digits.startsWith(staticPrefixDigits)) {
+    digits = digits.slice(staticPrefixDigits.length);
+  }
+
+  if (!digits) {
+    return { masked: "", unmasked: "" };
+  }
+
+  let masked = "";
+  let digitIndex = 0;
+
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "#" || char === "0" || char === "X") {
+      if (digitIndex < digits.length) {
+        masked += digits[digitIndex++];
+      } else {
+        break;
+      }
+    } else {
+      if (digitIndex < digits.length) {
+        masked += char;
+      } else {
+        break;
+      }
+    }
+  }
+
+  return { masked, unmasked: digits };
+}
+
+/**
+ * SolidJS reactive primitive for input value masking (phone numbers, credit cards, dates).
+ *
+ * @param options Configuration options including mask pattern.
+ */
+export function createInputMask(options: CreateInputMaskOptions): CreateInputMaskReturn {
+  const initial = formatMask(options.defaultValue || "", options.mask);
+  const [value, setFormattedValue] = createSignal(initial.masked);
+  const [unmaskedValue, setRawValue] = createSignal(initial.unmasked);
+
+  const setValue = (newVal: string) => {
+    const formatted = formatMask(newVal, options.mask);
+    setFormattedValue(formatted.masked);
+    setRawValue(formatted.unmasked);
+  };
+
+  const onInput = (e: Event & { currentTarget: HTMLInputElement }) => {
+    const inputVal = e.currentTarget.value;
+    const formatted = formatMask(inputVal, options.mask);
+
+    setFormattedValue(formatted.masked);
+    setRawValue(formatted.unmasked);
+    e.currentTarget.value = formatted.masked;
+  };
+
+  return {
+    value,
+    unmaskedValue,
+    setValue,
+    props: {
+      value: () => value(),
+      onInput,
+    },
+  };
+}