@nikala-ui/hooks 0.8.0 → 0.9.0

package/src/create-event-source.ts

@@ -0,0 +1,126 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type EventSourceStatus = "CONNECTING" | "OPEN" | "CLOSED";
+
+export interface CreateEventSourceOptions {
+  /** Event names to listen to on the EventSource. Defaults to ['message']. */
+  events?: string[];
+  /** Include credentials in CORS requests. */
+  withCredentials?: boolean;
+  /** Whether to open connection immediately. Defaults to true. */
+  immediate?: boolean;
+  /** Callback fired when connection is opened. */
+  onOpen?: (event: Event) => void;
+  /** Callback fired when message event is received. */
+  onMessage?: (event: MessageEvent) => void;
+  /** Callback fired when error occurs. */
+  onError?: (event: Event) => void;
+}
+
+export interface CreateEventSourceReturn<T = unknown> {
+  /** Signal accessor containing latest received SSE event data (parsed if JSON). */
+  data: Accessor<T | null>;
+  /** Signal accessor containing current EventSource status. */
+  status: Accessor<EventSourceStatus>;
+  /** Signal accessor containing last raw MessageEvent. */
+  event: Accessor<MessageEvent | null>;
+  /** Open or reconnect EventSource stream. */
+  open: () => void;
+  /** Close active EventSource stream. */
+  close: () => void;
+  /** Signal accessor indicating whether EventSource is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for subscribing to Server-Sent Events (SSE) streams.
+ */
+export function createEventSource<T = unknown>(
+  url: string | Accessor<string>,
+  options: CreateEventSourceOptions = {}
+): CreateEventSourceReturn<T> {
+  const [data, setData] = createSignal<T | null>(null);
+  const [event, setEvent] = createSignal<MessageEvent | null>(null);
+  const [status, setStatus] = createSignal<EventSourceStatus>("CLOSED");
+
+  const getUrl = (): string => (typeof url === "function" ? url() : url);
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" && "EventSource" in window;
+
+  let es: EventSource | null = null;
+
+  const close = (): void => {
+    if (es) {
+      es.close();
+      es = null;
+      setStatus("CLOSED");
+    }
+  };
+
+  const open = (): void => {
+    if (!isSupported()) return;
+
+    close();
+
+    setStatus("CONNECTING");
+
+    try {
+      const source = new EventSource(getUrl(), {
+        withCredentials: options.withCredentials,
+      });
+      es = source;
+
+      source.onopen = (e) => {
+        setStatus("OPEN");
+        options.onOpen?.(e);
+      };
+
+      source.onerror = (e) => {
+        if (source.readyState === EventSource.CLOSED) {
+          setStatus("CLOSED");
+        } else if (source.readyState === EventSource.CONNECTING) {
+          setStatus("CONNECTING");
+        }
+        options.onError?.(e);
+      };
+
+      const eventList = options.events ?? ["message"];
+      eventList.forEach((eventName) => {
+        source.addEventListener(eventName, (e) => {
+          const msgEvt = e as MessageEvent;
+          setEvent(() => msgEvt);
+          try {
+            const parsed = JSON.parse(msgEvt.data);
+            setData(() => parsed);
+          } catch {
+            setData(() => msgEvt.data as unknown as T);
+          }
+          options.onMessage?.(msgEvt);
+        });
+      });
+    } catch {
+      setStatus("CLOSED");
+      es = null;
+    }
+  };
+
+  createEffect(() => {
+    if (options.immediate ?? true) {
+      open();
+    }
+
+    onCleanup(() => {
+      close();
+    });
+  });
+
+  return {
+    data,
+    status,
+    event,
+    open,
+    close,
+    isSupported,
+  };
+}

package/src/create-favicon.ts

@@ -0,0 +1,52 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFaviconOptions {
+  /** Favicon rel attribute value. Defaults to 'icon'. */
+  rel?: string;
+  /** Favicon image mime-type format (e.g., 'image/x-icon', 'image/svg+xml', 'image/png'). */
+  type?: string;
+  /** Whether to restore original favicon on component unmount. Defaults to true. */
+  restoreOnUnmount?: boolean;
+}
+
+/**
+ * SolidJS reactive primitive for dynamically updating browser favicon element.
+ */
+export function createFavicon(
+  href: string | Accessor<string>,
+  options: CreateFaviconOptions = {}
+): void {
+  const getHref = (): string => (typeof href === "function" ? href() : href);
+
+  createEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const rel = options.rel ?? "icon";
+    let linkElement: HTMLLinkElement | null = document.querySelector(
+      `link[rel*="${rel}"]`
+    );
+
+    const originalHref = linkElement ? linkElement.href : "";
+
+    if (!linkElement) {
+      linkElement = document.createElement("link");
+      linkElement.rel = rel;
+      if (options.type) linkElement.type = options.type;
+      document.head.appendChild(linkElement);
+    }
+
+    const newHref = getHref();
+    if (newHref) {
+      linkElement.href = newHref;
+      if (options.type) linkElement.type = options.type;
+    }
+
+    onCleanup(() => {
+      if (typeof document !== "undefined" && (options.restoreOnUnmount ?? true) && linkElement) {
+        if (originalHref) {
+          linkElement.href = originalHref;
+        }
+      }
+    });
+  });
+}

package/src/create-fetch.ts

@@ -0,0 +1,93 @@
+import { createSignal, createEffect, type Accessor } from "solid-js";
+
+export interface CreateFetchOptions<T> extends RequestInit {
+  /** Whether the request should be refetched automatically on window focus. Defaults to false. */
+  refetchOnFocus?: boolean;
+  /** Custom transform function to process raw JSON / text response into required shape. */
+  transform?: (data: unknown) => T;
+  /** Whether the initial request should execute immediately. Defaults to true. */
+  immediate?: boolean;
+}
+
+export interface CreateFetchReturn<T> {
+  /** Signal containing fetched data. */
+  data: Accessor<T | null>;
+  /** Signal indicating whether request is loading. */
+  isLoading: Accessor<boolean>;
+  /** Signal containing request error if fetch failed. */
+  error: Accessor<Error | null>;
+  /** Imperative function to refetch data manually. */
+  refetch: () => Promise<void>;
+  /** Abort ongoing HTTP request. */
+  abort: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for handling HTTP fetch requests, loading states, errors, and manual refetching.
+ */
+export function createFetch<T = unknown>(
+  url: string | Accessor<string>,
+  options: CreateFetchOptions<T> = {}
+): CreateFetchReturn<T> {
+  const [data, setData] = createSignal<T | null>(null);
+  const [isLoading, setIsLoading] = createSignal(options.immediate ?? true);
+  const [error, setError] = createSignal<Error | null>(null);
+
+  let controller: AbortController | null = null;
+
+  const getUrl = (): string => {
+    return typeof url === "function" ? url() : url;
+  };
+
+  const abort = (): void => {
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+  };
+
+  const executeFetch = async (): Promise<void> => {
+    if (typeof window === "undefined") return;
+
+    abort();
+    controller = new AbortController();
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch(getUrl(), {
+        ...options,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`);
+      }
+
+      const raw = await response.json();
+      const result = options.transform ? options.transform(raw) : (raw as T);
+
+      setData(() => result);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  createEffect(() => {
+    if (options.immediate ?? true) {
+      executeFetch();
+    }
+  });
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: executeFetch,
+    abort,
+  };
+}

package/src/create-fullscreen.ts

@@ -0,0 +1,105 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFullscreenOptions {
+  /** Target element accessor or reference. Defaults to document.documentElement. */
+  target?: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Callback fired when entering fullscreen mode. */
+  onEnter?: () => void;
+  /** Callback fired when exiting fullscreen mode. */
+  onExit?: () => void;
+  /** Callback fired when fullscreen request fails. */
+  onError?: (err: Event) => void;
+}
+
+export interface CreateFullscreenReturn {
+  /** Signal indicating whether fullscreen mode is currently active. */
+  isFullscreen: Accessor<boolean>;
+  /** Request full screen mode for target element. */
+  enter: () => Promise<void>;
+  /** Exit full screen mode. */
+  exit: () => Promise<void>;
+  /** Toggle full screen mode. */
+  toggle: () => Promise<void>;
+}
+
+/**
+ * SolidJS reactive primitive for requesting and monitoring element fullscreen status.
+ */
+export function createFullscreen(
+  options: CreateFullscreenOptions = {}
+): CreateFullscreenReturn {
+  const [isFullscreen, setIsFullscreen] = createSignal(false);
+
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof document === "undefined") return undefined;
+    if (typeof options.target === "function") {
+      return options.target() ?? document.documentElement;
+    }
+    return options.target ?? document.documentElement;
+  };
+
+  const updateStatus = (): void => {
+    if (typeof document === "undefined") return;
+    const activeEl = document.fullscreenElement;
+    const isTargetFullscreen = Boolean(activeEl && activeEl === getTarget());
+    setIsFullscreen(isTargetFullscreen);
+  };
+
+  const enter = async (): Promise<void> => {
+    if (typeof window === "undefined") return;
+    const el = getTarget();
+    if (el?.requestFullscreen) {
+      await el.requestFullscreen();
+    }
+  };
+
+  const exit = async (): Promise<void> => {
+    if (typeof document === "undefined") return;
+    if (document.fullscreenElement && document.exitFullscreen) {
+      await document.exitFullscreen();
+    }
+  };
+
+  const toggle = async (): Promise<void> => {
+    if (isFullscreen()) {
+      await exit();
+    } else {
+      await enter();
+    }
+  };
+
+  createEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const handleFullscreenChange = (): void => {
+      const activeEl = document.fullscreenElement;
+      const isTarget = Boolean(activeEl && activeEl === getTarget());
+      setIsFullscreen(isTarget);
+
+      if (isTarget) {
+        options.onEnter?.();
+      } else {
+        options.onExit?.();
+      }
+    };
+
+    const handleFullscreenError = (err: Event): void => {
+      options.onError?.(err);
+    };
+
+    document.addEventListener("fullscreenchange", handleFullscreenChange);
+    document.addEventListener("fullscreenerror", handleFullscreenError);
+
+    onCleanup(() => {
+      document.removeEventListener("fullscreenchange", handleFullscreenChange);
+      document.removeEventListener("fullscreenerror", handleFullscreenError);
+    });
+  });
+
+  return {
+    isFullscreen,
+    enter,
+    exit,
+    toggle,
+  };
+}

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