@nikala-ui/hooks 0.8.0

package/README.md

@@ -0,0 +1,78 @@
+# @nikala-ui/hooks
+
+Reactive SolidJS state primitives and custom hooks for **Nikala UI**.
+
+Honoring the iconic Georgian painter **Niko Pirosmani (Nikala)**.
+
+Official Documentation & Interactive Demos: [nikala.magradze.dev](https://nikala.magradze.dev)
+
+---
+
+## Overview
+
+This package provides reusable, fine-grained reactive primitives designed natively for SolidJS applications. It simplifies managing complex component state such as controlled and uncontrolled inputs, state synchronization, and reactive event callbacks.
+
+---
+
+## Core Features & Available Hooks
+
+- **`createControllableSignal`** — SolidJS reactive primitive for managing state supporting both controlled and uncontrolled modes with a unified setter API.
+- **`createClickOutside`** — SolidJS reactive primitive for detecting user interactions outside specified element(s) or refs.
+- **`createClipboard`** — SolidJS reactive primitive for copying text to clipboard with automatic status reset.
+- **`createKeybindings` / `createEscapeKey`** — SolidJS reactive primitives for listening to keyboard shortcuts, key combinations, and Escape key presses.
+- **`createLockScroll`** — SolidJS reactive primitive for locking body or container scrolling when overlays are active.
+- **`createDisclosure`** — SolidJS reactive primitive for managing boolean open/close state with toggle, open, and close helpers.
+- **`createMediaQuery` / `createBreakpoint`** — SolidJS reactive primitives for tracking CSS media queries and responsive Tailwind breakpoints.
+- **`createDebounce` / `createThrottle`** — SolidJS reactive primitives for debouncing and throttling rate-limited function execution.
+- **`createIntersectionObserver` / `createInView`** — SolidJS reactive primitives for detecting element viewport visibility and scroll animation triggers.
+- **`createTimer` / `createCountdown`** — SolidJS reactive primitives for recurring interval ticks and formatted countdown timers.
+- **`createResizeObserver` / `createElementSize`** — SolidJS reactive primitives for tracking element width and height dimensions dynamically.
+- **`createWindowSize`** — SolidJS reactive primitive for tracking window viewport inner width and height.
+- **`createScrollPosition`** — SolidJS reactive primitive for tracking scroll position, scroll direction, and top/bottom container status.
+- **`createFocusTrap`** — SolidJS reactive primitive for trapping keyboard focus inside target container element for accessibility (WCAG).
+- **`createMousePosition`** — SolidJS reactive primitive for tracking global and element-relative mouse pointer coordinates.
+- **`createLongPress`** — SolidJS reactive primitive for detecting long press / hold touch and pointer interactions.
+- **`createHover`** — SolidJS reactive primitive for tracking element hover state with entrance/exit delays.
+- **`createLocalStorage` / `createSessionStorage`** — SolidJS reactive primitives for Web Storage state synchronization across tabs.
+- **`createPrevious`** — SolidJS reactive primitive for tracking previous value of a signal accessor.
+- **`createNetworkStatus` / `createOnline`** — SolidJS reactive primitives for tracking browser network connectivity and connection quality metrics.
+- **`createColorMode`** — SolidJS reactive primitive for managing dark/light themes and system preferences.
+- **`createForm`** — SolidJS reactive primitive for form state management, field validation, errors, and submission.
+- **`createInputMask`** — SolidJS reactive primitive for input value masking (phone numbers, credit cards, dates).
+- **`createIdle`** — SolidJS reactive primitive for detecting user inactivity with customizable timeout and activity events.
+- **`createActiveElement`** — SolidJS reactive primitive for tracking the currently focused DOM element.
+- **Native SolidJS Reactivity** — Zero-dependency, fine-grained reactivity built directly on SolidJS signals.
+- **TypeScript First** — Fully typed options, getters, and return tuple interfaces.
+
+---
+
+## Installation & Usage
+
+Install the hooks package via your preferred package manager:
+
+```bash
+bun add @nikala-ui/hooks
+# or
+npm install @nikala-ui/hooks
+```
+
+Import hooks directly into your SolidJS components:
+
+```tsx
+import { createControllableSignal } from "@nikala-ui/hooks";
+
+const [value, setValue] = createControllableSignal({
+  defaultValue: "Uncontrolled Initial State",
+});
+```
+
+---
+
+## Documentation & Links
+
+- Repository: [github.com/nikala-ui/ui](https://github.com/nikala-ui/ui)
+- Hooks Documentation: [nikala.magradze.dev/docs/hooks](https://nikala.magradze.dev/docs/hooks)
+
+## License
+
+[MIT](https://github.com/nikala-ui/ui/blob/main/LICENSE)

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@nikala-ui/hooks",
+  "version": "0.8.0",
+  "description": "Reactive SolidJS primitives and primitives for Nikala UI",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikala-ui/ui.git",
+    "directory": "packages/hooks"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0"
+  }
+}

package/src/create-active-element.ts

@@ -0,0 +1,51 @@
+import { createSignal, onMount, onCleanup, type Accessor } from "solid-js";
+import { isServer } from "solid-js/web";
+
+export interface CreateActiveElementReturn {
+  /** Accessor returning the currently focused DOM element, or null */
+  activeElement: Accessor<Element | null>;
+  /** Accessor returning true if any element (non-body) is focused */
+  hasFocus: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for tracking the currently focused (active) DOM element.
+ * Listens to focus/blur events on the document and reactively updates `activeElement` and `hasFocus`.
+ */
+export function createActiveElement(): CreateActiveElementReturn {
+  // SSR: return static defaults
+  if (isServer) {
+    const [activeElement] = createSignal<Element | null>(null);
+    const [hasFocus] = createSignal(false);
+    return { activeElement, hasFocus };
+  }
+
+  const [activeElement, setActiveElement] = createSignal<Element | null>(null);
+
+  const hasFocus = () => {
+    const el = activeElement();
+    return el !== null && el !== document.body;
+  };
+
+  const handleFocusChange = () => {
+    setActiveElement(document.activeElement);
+  };
+
+  onMount(() => {
+    // Set initial value
+    setActiveElement(document.activeElement);
+
+    document.addEventListener("focusin", handleFocusChange, true);
+    document.addEventListener("focusout", handleFocusChange, true);
+
+    onCleanup(() => {
+      document.removeEventListener("focusin", handleFocusChange, true);
+      document.removeEventListener("focusout", handleFocusChange, true);
+    });
+  });
+
+  return {
+    activeElement,
+    hasFocus,
+  };
+}

package/src/create-click-outside.ts

@@ -0,0 +1,82 @@
+import { onMount, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateClickOutsideOptions {
+  /** Target HTML element or accessor returning the container element */
+  target:
+    | HTMLElement
+    | Accessor<HTMLElement | undefined>
+    | (HTMLElement | Accessor<HTMLElement | undefined>)[];
+  /** Callback fired when a click/pointer event occurs outside the target element(s) */
+  onInteractOutside: (event: MouseEvent | PointerEvent | TouchEvent) => void;
+  /** Whether the listener is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Optional element or accessor to ignore when checking outside clicks (e.g. trigger button) */
+  ignore?:
+    | HTMLElement
+    | Accessor<HTMLElement | undefined>
+    | (HTMLElement | Accessor<HTMLElement | undefined>)[];
+}
+
+/**
+ * SolidJS reactive primitive for detecting user interactions outside specified element(s).
+ *
+ * @param options Configuration options including target element(s), callback, and optional ignore elements.
+ */
+export function createClickOutside(options: CreateClickOutsideOptions): void {
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  const getElement = (
+    el: HTMLElement | Accessor<HTMLElement | undefined> | undefined
+  ): HTMLElement | undefined => {
+    if (!el) return undefined;
+    if (typeof el === "function") {
+      return (el as Accessor<HTMLElement | undefined>)();
+    }
+    return el;
+  };
+
+  const getElements = (
+    targets:
+      | HTMLElement
+      | Accessor<HTMLElement | undefined>
+      | (HTMLElement | Accessor<HTMLElement | undefined>)[]
+      | undefined
+  ): HTMLElement[] => {
+    if (!targets) return [];
+    const list = Array.isArray(targets) ? targets : [targets];
+    return list.map(getElement).filter((e): e is HTMLElement => e !== undefined);
+  };
+
+  const handlePointerDown = (event: MouseEvent | PointerEvent | TouchEvent) => {
+    if (!isEnabled()) return;
+
+    const targetNode = event.target as Node | null;
+    if (!targetNode) return;
+
+    const mainElements = getElements(options.target);
+    if (mainElements.length === 0) return;
+
+    const isInsideTarget = mainElements.some((el) => el.contains(targetNode));
+    if (isInsideTarget) return;
+
+    const ignoreElements = getElements(options.ignore);
+    const isInsideIgnore = ignoreElements.some((el) => el.contains(targetNode));
+    if (isInsideIgnore) return;
+
+    options.onInteractOutside(event);
+  };
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("pointerdown", handlePointerDown, true);
+    onCleanup(() => {
+      window.removeEventListener("pointerdown", handlePointerDown, true);
+    });
+  });
+}

package/src/create-clipboard.ts

@@ -0,0 +1,69 @@
+import { createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateClipboardOptions {
+  /** Time in milliseconds to maintain the copied state before resetting. Defaults to 2000ms. */
+  timeout?: number;
+}
+
+export interface CreateClipboardReturn {
+  /** Signal accessor indicating if content was recently copied */
+  copied: Accessor<boolean>;
+  /** Function to copy text to clipboard */
+  copy: (text: string) => Promise<boolean>;
+  /** Error state if clipboard write fails */
+  error: Accessor<Error | undefined>;
+}
+
+/**
+ * SolidJS reactive primitive for copying text to clipboard with automatic reset state.
+ *
+ * @param options Configuration options including copied status reset timeout duration.
+ */
+export function createClipboard(options: CreateClipboardOptions = {}): CreateClipboardReturn {
+  const timeoutDuration = options.timeout ?? 2000;
+  const [copied, setCopied] = createSignal(false);
+  const [error, setError] = createSignal<Error | undefined>(undefined);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearTimer = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const copy = async (text: string): Promise<boolean> => {
+    clearTimer();
+    setError(undefined);
+
+    try {
+      if (typeof window !== "undefined" && navigator.clipboard && navigator.clipboard.writeText) {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+
+        timer = setTimeout(() => {
+          setCopied(false);
+        }, timeoutDuration);
+
+        return true;
+      }
+
+      throw new Error("Clipboard API not supported");
+    } catch (err) {
+      const copyError = err instanceof Error ? err : new Error(String(err));
+      setError(copyError);
+      setCopied(false);
+      return false;
+    }
+  };
+
+  onCleanup(() => {
+    clearTimer();
+  });
+
+  return {
+    copied,
+    copy,
+    error,
+  };
+}

package/src/create-color-mode.ts

@@ -0,0 +1,115 @@
+import { createEffect, createSignal, onCleanup, onMount, type Accessor } from "solid-js";
+
+export type ColorMode = "light" | "dark" | "system";
+
+export interface CreateColorModeOptions {
+  /** Initial color mode fallback. Defaults to 'system'. */
+  initialValue?: ColorMode;
+  /** LocalStorage key for persisting color mode state. Defaults to 'nikala-color-mode'. */
+  storageKey?: string;
+  /** HTML attribute to apply dark mode class on document.documentElement. Defaults to 'class'. */
+  attribute?: string;
+}
+
+export interface CreateColorModeReturn {
+  /** Accessor for current active color mode ('light', 'dark', 'system') */
+  mode: Accessor<ColorMode>;
+  /** Function to update current color mode */
+  setMode: (mode: ColorMode) => void;
+  /** Function to toggle color mode between 'light' and 'dark' */
+  toggleColorMode: () => void;
+  /** Accessor indicating if current resolved mode is dark */
+  isDark: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for managing dark/light color mode themes and system preferences.
+ *
+ * @param options Configuration options including storage key and initial mode.
+ */
+export function createColorMode(
+  options: CreateColorModeOptions = {}
+): CreateColorModeReturn {
+  const initialMode = options.initialValue ?? "system";
+  const storageKey = options.storageKey ?? "nikala-color-mode";
+  const attribute = options.attribute ?? "class";
+
+  const [mode, setModeSignal] = createSignal<ColorMode>(initialMode);
+  const [systemDark, setSystemDark] = createSignal(false);
+
+  const isDark = () => {
+    const currentMode = mode();
+    if (currentMode === "system") return systemDark();
+    return currentMode === "dark";
+  };
+
+  const applyTheme = (dark: boolean) => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    if (attribute === "class") {
+      if (dark) root.classList.add("dark");
+      else root.classList.remove("dark");
+    } else {
+      root.setAttribute(attribute, dark ? "dark" : "light");
+    }
+  };
+
+  const setMode = (newMode: ColorMode) => {
+    setModeSignal(newMode);
+    if (typeof window !== "undefined") {
+      try {
+        localStorage.setItem(storageKey, newMode);
+      } catch (e) {
+        console.warn(`[nikala-ui/hooks] Error setting color mode storage:`, e);
+      }
+    }
+  };
+
+  const toggleColorMode = () => {
+    const next = isDark() ? "light" : "dark";
+    setMode(next);
+  };
+
+  createEffect(() => {
+    applyTheme(isDark());
+  });
+
+  onMount(() => {
+    if (typeof window === "undefined") return;
+
+    // Check system preference
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    setSystemDark(mediaQuery.matches);
+
+    const handleMediaChange = (e: MediaQueryListEvent) => {
+      setSystemDark(e.matches);
+    };
+
+    if (mediaQuery.addEventListener) {
+      mediaQuery.addEventListener("change", handleMediaChange);
+    }
+
+    // Check localStorage
+    try {
+      const stored = localStorage.getItem(storageKey) as ColorMode | null;
+      if (stored && ["light", "dark", "system"].includes(stored)) {
+        setModeSignal(stored);
+      }
+    } catch (e) {
+      console.warn(`[nikala-ui/hooks] Error reading color mode storage:`, e);
+    }
+
+    onCleanup(() => {
+      if (mediaQuery.removeEventListener) {
+        mediaQuery.removeEventListener("change", handleMediaChange);
+      }
+    });
+  });
+
+  return {
+    mode,
+    setMode,
+    toggleColorMode,
+    isDark,
+  };
+}

package/src/create-controllable-signal.ts

@@ -0,0 +1,56 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateControllableSignalOptions<T> {
+  /** Controlled value accessor or raw value */
+  value?: Accessor<T | undefined> | T;
+  /** Uncontrolled default initial value */
+  defaultValue?: T;
+  /** Callback fired whenever the value changes */
+  onChange?: (value: T) => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing state supporting both controlled and uncontrolled modes.
+ *
+ * @param options Configuration options for value, defaultValue, and onChange callback.
+ * @returns A tuple containing [valueAccessor, setValueFunction].
+ */
+export function createControllableSignal<T>(
+  options: CreateControllableSignalOptions<T>
+): [Accessor<T | undefined>, (nextValue: T | ((prev: T | undefined) => T)) => void] {
+  const [internalValue, setInternalValue] = createSignal<T | undefined>(
+    options.defaultValue
+  );
+
+  const getValue = (): T | undefined => {
+    if (typeof options.value === "function") {
+      return (options.value as Accessor<T | undefined>)();
+    }
+    return options.value;
+  };
+
+  const isControlled = () => getValue() !== undefined;
+
+  const value = () => {
+    const controlledVal = getValue();
+    return controlledVal !== undefined ? controlledVal : internalValue();
+  };
+
+  const setValue = (nextValue: T | ((prev: T | undefined) => T)) => {
+    const current = value();
+    const resolvedNext =
+      typeof nextValue === "function"
+        ? (nextValue as (prev: T | undefined) => T)(current)
+        : nextValue;
+
+    if (!isControlled()) {
+      setInternalValue(resolvedNext as any);
+    }
+
+    if (typeof options.onChange === "function") {
+      options.onChange(resolvedNext);
+    }
+  };
+
+  return [value, setValue];
+}

package/src/create-debounce.ts

@@ -0,0 +1,90 @@
+import { onCleanup, type Accessor } from "solid-js";
+
+export interface DebounceThrottleReturn<T extends (...args: any[]) => any> {
+  (...args: Parameters<T>): void;
+  clear: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for debouncing function execution.
+ *
+ * @param fn Function to debounce.
+ * @param delay Delay in milliseconds (number or accessor).
+ */
+export function createDebounce<T extends (...args: any[]) => any>(
+  fn: T,
+  delay: number | Accessor<number>
+): DebounceThrottleReturn<T> {
+  const getDelay = (): number => (typeof delay === "function" ? delay() : delay);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const debounced = (...args: Parameters<T>) => {
+    clear();
+    timer = setTimeout(() => {
+      fn(...args);
+    }, getDelay());
+  };
+
+  debounced.clear = clear;
+
+  onCleanup(() => {
+    clear();
+  });
+
+  return debounced;
+}
+
+/**
+ * SolidJS reactive primitive for throttling function execution.
+ *
+ * @param fn Function to throttle.
+ * @param delay Interval in milliseconds (number or accessor).
+ */
+export function createThrottle<T extends (...args: any[]) => any>(
+  fn: T,
+  delay: number | Accessor<number>
+): DebounceThrottleReturn<T> {
+  const getDelay = (): number => (typeof delay === "function" ? delay() : delay);
+  let lastCall = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const throttled = (...args: Parameters<T>) => {
+    const now = Date.now();
+    const interval = getDelay();
+    const remaining = interval - (now - lastCall);
+
+    if (remaining <= 0) {
+      clear();
+      lastCall = now;
+      fn(...args);
+    } else if (!timer) {
+      timer = setTimeout(() => {
+        lastCall = Date.now();
+        timer = undefined;
+        fn(...args);
+      }, remaining);
+    }
+  };
+
+  throttled.clear = clear;
+
+  onCleanup(() => {
+    clear();
+  });
+
+  return throttled;
+}

package/src/create-disclosure.ts

@@ -0,0 +1,82 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateDisclosureOptions {
+  /** Uncontrolled initial open state. Defaults to false. */
+  defaultIsOpen?: boolean;
+  /** Controlled open state accessor */
+  isOpen?: boolean | Accessor<boolean | undefined>;
+  /** Callback triggered when state transitions to open */
+  onOpen?: () => void;
+  /** Callback triggered when state transitions to closed */
+  onClose?: () => void;
+  /** Callback triggered whenever open state changes */
+  onChange?: (isOpen: boolean) => void;
+}
+
+export interface CreateDisclosureReturn {
+  /** Signal accessor indicating if disclosure is open */
+  isOpen: Accessor<boolean>;
+  /** Function to open the disclosure */
+  open: () => void;
+  /** Function to close the disclosure */
+  close: () => void;
+  /** Function to toggle the disclosure open state */
+  toggle: () => void;
+  /** Setter function to programmatically set open state */
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing boolean disclosure (open/close) state with controlled and uncontrolled support.
+ *
+ * @param options Configuration options including initial state and callbacks.
+ */
+export function createDisclosure(options: CreateDisclosureOptions = {}): CreateDisclosureReturn {
+  const [internalOpen, setInternalOpen] = createSignal<boolean>(
+    options.defaultIsOpen ?? false
+  );
+
+  const isControlled = () => {
+    if (typeof options.isOpen === "function") {
+      return options.isOpen() !== undefined;
+    }
+    return options.isOpen !== undefined;
+  };
+
+  const isOpen = (): boolean => {
+    if (typeof options.isOpen === "function") {
+      const val = options.isOpen();
+      return val !== undefined ? val : internalOpen();
+    }
+    return options.isOpen !== undefined ? options.isOpen : internalOpen();
+  };
+
+  const setOpenState = (nextState: boolean) => {
+    const currentState = isOpen();
+    if (currentState === nextState) return;
+
+    if (!isControlled()) {
+      setInternalOpen(nextState);
+    }
+
+    options.onChange?.(nextState);
+
+    if (nextState) {
+      options.onOpen?.();
+    } else {
+      options.onClose?.();
+    }
+  };
+
+  const open = () => setOpenState(true);
+  const close = () => setOpenState(false);
+  const toggle = () => setOpenState(!isOpen());
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle,
+    setOpen: setOpenState,
+  };
+}