@nikala-ui/hooks 0.8.0

package/src/create-resize-observer.ts

@@ -0,0 +1,89 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateResizeObserverOptions extends ResizeObserverOptions {
+  /** Whether the observer is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for observing element size changes via ResizeObserver.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param callback Observer callback invoked on element resize events.
+ * @param options ResizeObserver options (box, enabled).
+ */
+export function createResizeObserver(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  callback: ResizeObserverCallback,
+  options: CreateResizeObserverOptions = {}
+): void {
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof target === "function") {
+      return (target as Accessor<HTMLElement | undefined>)();
+    }
+    return target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined" || !window.ResizeObserver) {
+      return;
+    }
+
+    if (!isEnabled()) return;
+
+    const el = getTarget();
+    if (!el) return;
+
+    const observer = new ResizeObserver(callback);
+    observer.observe(el, { box: options.box });
+
+    onCleanup(() => {
+      observer.disconnect();
+    });
+  });
+}
+
+export interface CreateElementSizeReturn {
+  /** Accessor for element width in pixels */
+  width: Accessor<number>;
+  /** Accessor for element height in pixels */
+  height: Accessor<number>;
+}
+
+/**
+ * SolidJS reactive primitive returning width and height accessors for a target HTML element.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param options ResizeObserver options.
+ */
+export function createElementSize(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  options: CreateResizeObserverOptions = {}
+): CreateElementSizeReturn {
+  const [width, setWidth] = createSignal(0);
+  const [height, setHeight] = createSignal(0);
+
+  createResizeObserver(
+    target,
+    (entries) => {
+      const entry = entries[0];
+      if (entry) {
+        setWidth(entry.contentRect.width);
+        setHeight(entry.contentRect.height);
+      }
+    },
+    options
+  );
+
+  return {
+    width,
+    height,
+  };
+}

package/src/create-scroll-position.ts

@@ -0,0 +1,129 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export type ScrollDirection = "up" | "down" | "left" | "right" | "none";
+
+export interface CreateScrollPositionOptions {
+  /** Target element to observe scroll events on. Defaults to window. */
+  target?: HTMLElement | Window | Accessor<HTMLElement | Window | undefined>;
+}
+
+export interface CreateScrollPositionReturn {
+  /** Accessor for horizontal scroll position (scrollLeft / pageXOffset) */
+  x: Accessor<number>;
+  /** Accessor for vertical scroll position (scrollTop / pageYOffset) */
+  y: Accessor<number>;
+  /** Accessor indicating if element is actively scrolling */
+  isScrolling: Accessor<boolean>;
+  /** Accessor for current scroll direction ('up', 'down', 'left', 'right', 'none') */
+  direction: Accessor<ScrollDirection>;
+  /** Accessor indicating if scroll is at top (y <= 0) */
+  isAtTop: Accessor<boolean>;
+  /** Accessor indicating if scroll is at bottom of container */
+  isAtBottom: Accessor<boolean>;
+  /** Function to programmatically scroll target element */
+  scrollTo: (options: ScrollToOptions) => void;
+}
+
+/**
+ * SolidJS reactive primitive for tracking target element or window scroll position and scroll metrics.
+ *
+ * @param options Configuration options including target element.
+ */
+export function createScrollPosition(
+  options: CreateScrollPositionOptions = {}
+): CreateScrollPositionReturn {
+  const [x, setX] = createSignal(0);
+  const [y, setY] = createSignal(0);
+  const [isScrolling, setIsScrolling] = createSignal(false);
+  const [direction, setDirection] = createSignal<ScrollDirection>("none");
+  const [isAtTop, setIsAtTop] = createSignal(true);
+  const [isAtBottom, setIsAtBottom] = createSignal(false);
+
+  let scrollTimeout: ReturnType<typeof setTimeout> | undefined;
+  let lastX = 0;
+  let lastY = 0;
+
+  const getTarget = (): HTMLElement | Window | undefined => {
+    if (typeof window === "undefined") return undefined;
+    if (!options.target) return window;
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | Window | undefined>)();
+    }
+    return options.target;
+  };
+
+  const updateScroll = () => {
+    const target = getTarget();
+    if (!target) return;
+
+    let currentX = 0;
+    let currentY = 0;
+    let maxScrollY = 0;
+
+    if (target === window) {
+      currentX = window.scrollX || window.pageXOffset;
+      currentY = window.scrollY || window.pageYOffset;
+      maxScrollY = document.documentElement.scrollHeight - window.innerHeight;
+    } else {
+      const el = target as HTMLElement;
+      currentX = el.scrollLeft;
+      currentY = el.scrollTop;
+      maxScrollY = el.scrollHeight - el.clientHeight;
+    }
+
+    // Determine direction
+    const deltaX = currentX - lastX;
+    const deltaY = currentY - lastY;
+
+    if (Math.abs(deltaY) > Math.abs(deltaX)) {
+      if (deltaY > 0) setDirection("down");
+      else if (deltaY < 0) setDirection("up");
+    } else if (Math.abs(deltaX) > 0) {
+      if (deltaX > 0) setDirection("right");
+      else if (deltaX < 0) setDirection("left");
+    }
+
+    lastX = currentX;
+    lastY = currentY;
+
+    setX(currentX);
+    setY(currentY);
+    setIsAtTop(currentY <= 0);
+    setIsAtBottom(maxScrollY > 0 && currentY >= maxScrollY - 1);
+    setIsScrolling(true);
+
+    if (scrollTimeout) clearTimeout(scrollTimeout);
+    scrollTimeout = setTimeout(() => {
+      setIsScrolling(false);
+    }, 150);
+  };
+
+  createEffect(() => {
+    const target = getTarget();
+    if (!target) return;
+
+    updateScroll();
+
+    target.addEventListener("scroll", updateScroll, { passive: true });
+    onCleanup(() => {
+      target.removeEventListener("scroll", updateScroll);
+      if (scrollTimeout) clearTimeout(scrollTimeout);
+    });
+  });
+
+  const scrollTo = (scrollOptions: ScrollToOptions) => {
+    const target = getTarget();
+    if (!target) return;
+    target.scrollTo(scrollOptions);
+  };
+
+  return {
+    x,
+    y,
+    isScrolling,
+    direction,
+    isAtTop,
+    isAtBottom,
+    scrollTo,
+  };
+}

package/src/create-storage.ts

@@ -0,0 +1,106 @@
+import { createSignal, onMount, onCleanup, type Accessor } from "solid-js";
+
+export type StorageType = "local" | "session";
+
+/**
+ * Helper to safely read item from Web Storage.
+ */
+function readStorage<T>(key: string, storage: Storage | undefined, fallback: T): T {
+  if (!storage) return fallback;
+  try {
+    const item = storage.getItem(key);
+    return item !== null ? JSON.parse(item) : fallback;
+  } catch (error) {
+    console.warn(`[nikala-ui/hooks] Error reading storage key "${key}":`, error);
+    return fallback;
+  }
+}
+
+/**
+ * SolidJS reactive primitive for Web Storage (localStorage / sessionStorage) synchronization.
+ *
+ * @param key Storage key name.
+ * @param initialValue Default initial value if key doesn't exist.
+ * @param type Storage type: "local" (default) or "session".
+ */
+export function createStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>,
+  type: StorageType = "local"
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  const getStorage = (): Storage | undefined => {
+    if (typeof window === "undefined") return undefined;
+    return type === "local" ? window.localStorage : window.sessionStorage;
+  };
+
+  const getFallback = (): T => (typeof initialValue === "function" ? (initialValue as Accessor<T>)() : initialValue);
+
+  const [value, setInternalValue] = createSignal<T>(getFallback());
+
+  const setValue = (val: T | ((prev: T) => T)) => {
+    const storage = getStorage();
+    const currentValue = value();
+    const nextValue = typeof val === "function" ? (val as (prev: T) => T)(currentValue) : val;
+
+    setInternalValue(() => nextValue);
+
+    if (storage) {
+      try {
+        storage.setItem(key, JSON.stringify(nextValue));
+      } catch (error) {
+        console.warn(`[nikala-ui/hooks] Error setting storage key "${key}":`, error);
+      }
+    }
+  };
+
+  const remove = () => {
+    const storage = getStorage();
+    setInternalValue(() => getFallback());
+    if (storage) {
+      storage.removeItem(key);
+    }
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const storage = getStorage();
+    if (storage) {
+      const stored = readStorage<T>(key, storage, getFallback());
+      setInternalValue(() => stored);
+    }
+
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === key) {
+        setInternalValue(() => (event.newValue !== null ? JSON.parse(event.newValue) : getFallback()));
+      }
+    };
+
+    window.addEventListener("storage", handleStorageChange);
+    onCleanup(() => {
+      window.removeEventListener("storage", handleStorageChange);
+    });
+  });
+
+  return [value, setValue, remove];
+}
+
+/**
+ * SolidJS reactive primitive for localStorage synchronization across components and browser tabs.
+ */
+export function createLocalStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  return createStorage<T>(key, initialValue, "local");
+}
+
+/**
+ * SolidJS reactive primitive for sessionStorage synchronization.
+ */
+export function createSessionStorage<T>(
+  key: string,
+  initialValue: T | Accessor<T>
+): [value: Accessor<T>, setValue: (val: T | ((prev: T) => T)) => void, remove: () => void] {
+  return createStorage<T>(key, initialValue, "session");
+}

package/src/create-timer.ts

@@ -0,0 +1,150 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateTimerOptions {
+  /** Whether the timer starts running automatically on mount. Defaults to false. */
+  autostart?: boolean;
+}
+
+export interface CreateTimerReturn {
+  /** Accessor indicating if timer is actively running */
+  isRunning: Accessor<boolean>;
+  /** Function to start or resume the timer */
+  start: () => void;
+  /** Function to pause/stop the timer */
+  stop: () => void;
+  /** Function to reset and restart the timer */
+  reset: () => void;
+  /** Function to toggle running state */
+  toggle: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for recurring interval timers.
+ *
+ * @param intervalMs Interval duration in milliseconds.
+ * @param callback Function to execute on each interval tick.
+ * @param options Configuration options including autostart.
+ */
+export function createTimer(
+  intervalMs: number | Accessor<number>,
+  callback: () => void,
+  options: CreateTimerOptions = {}
+): CreateTimerReturn {
+  const [isRunning, setIsRunning] = createSignal<boolean>(options.autostart ?? false);
+  let timerId: ReturnType<typeof setInterval> | undefined;
+
+  const getInterval = () => (typeof intervalMs === "function" ? intervalMs() : intervalMs);
+
+  const stop = () => {
+    if (timerId) {
+      clearInterval(timerId);
+      timerId = undefined;
+    }
+    setIsRunning(false);
+  };
+
+  const start = () => {
+    stop();
+    const delay = getInterval();
+    if (delay <= 0) return;
+
+    setIsRunning(true);
+    timerId = setInterval(() => {
+      callback();
+    }, delay);
+  };
+
+  const reset = () => {
+    start();
+  };
+
+  const toggle = () => {
+    if (isRunning()) {
+      stop();
+    } else {
+      start();
+    }
+  };
+
+  createEffect(() => {
+    if (isRunning()) {
+      start();
+    }
+  });
+
+  onCleanup(() => {
+    stop();
+  });
+
+  return {
+    isRunning,
+    start,
+    stop,
+    reset,
+    toggle,
+  };
+}
+
+export interface CreateCountdownOptions extends CreateTimerOptions {
+  /** Callback fired when countdown reaches zero */
+  onComplete?: () => void;
+}
+
+export interface CreateCountdownReturn extends CreateTimerReturn {
+  /** Accessor for remaining seconds */
+  remainingSeconds: Accessor<number>;
+  /** Accessor for formatted time string (MM:SS) */
+  formatted: Accessor<string>;
+}
+
+/**
+ * SolidJS reactive primitive for countdown timers.
+ *
+ * @param durationSeconds Total countdown duration in seconds.
+ * @param options Configuration options including autostart and onComplete callback.
+ */
+export function createCountdown(
+  durationSeconds: number | Accessor<number>,
+  options: CreateCountdownOptions = {}
+): CreateCountdownReturn {
+  const getInitialDuration = () =>
+    typeof durationSeconds === "function" ? durationSeconds() : durationSeconds;
+
+  const [remaining, setRemaining] = createSignal<number>(getInitialDuration());
+
+  const timer = createTimer(
+    1000,
+    () => {
+      setRemaining((prev) => {
+        if (prev <= 1) {
+          timer.stop();
+          options.onComplete?.();
+          return 0;
+        }
+        return prev - 1;
+      });
+    },
+    { autostart: options.autostart }
+  );
+
+  const reset = () => {
+    setRemaining(getInitialDuration());
+    timer.start();
+  };
+
+  const formatted = (): string => {
+    const total = remaining();
+    const minutes = Math.floor(total / 60);
+    const seconds = total % 60;
+    const mm = String(minutes).padStart(2, "0");
+    const ss = String(seconds).padStart(2, "0");
+    return `${mm}:${ss}`;
+  };
+
+  return {
+    ...timer,
+    remainingSeconds: remaining,
+    formatted,
+    reset,
+  };
+}

package/src/create-window-size.ts

@@ -0,0 +1,41 @@
+import { createSignal, onMount, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateWindowSizeReturn {
+  /** Accessor for current window inner width in pixels */
+  width: Accessor<number>;
+  /** Accessor for current window inner height in pixels */
+  height: Accessor<number>;
+}
+
+/**
+ * SolidJS reactive primitive for tracking window viewport dimensions (width and height).
+ */
+export function createWindowSize(): CreateWindowSizeReturn {
+  const [width, setWidth] = createSignal<number>(
+    typeof window !== "undefined" ? window.innerWidth : 0
+  );
+  const [height, setHeight] = createSignal<number>(
+    typeof window !== "undefined" ? window.innerHeight : 0
+  );
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    const handleResize = () => {
+      setWidth(window.innerWidth);
+      setHeight(window.innerHeight);
+    };
+
+    handleResize();
+
+    window.addEventListener("resize", handleResize);
+    onCleanup(() => {
+      window.removeEventListener("resize", handleResize);
+    });
+  });
+
+  return {
+    width,
+    height,
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./create-controllable-signal";
+export * from "./create-click-outside";
+export * from "./create-clipboard";
+export * from "./create-keybindings";
+export * from "./create-lock-scroll";
+export * from "./create-disclosure";
+export * from "./create-media-query";
+export * from "./create-debounce";
+export * from "./create-intersection-observer";
+export * from "./create-timer";
+export * from "./create-resize-observer";
+export * from "./create-window-size";
+export * from "./create-scroll-position";
+export * from "./create-focus-trap";
+export * from "./create-mouse-position";
+export * from "./create-long-press";
+export * from "./create-hover";
+export * from "./create-storage";
+export * from "./create-previous";
+export * from "./create-network-status";
+export * from "./create-color-mode";
+export * from "./create-form";
+export * from "./create-input-mask";
+export * from "./create-idle";
+export * from "./create-active-element";