@nikala-ui/hooks 0.8.0

package/src/create-focus-trap.ts

@@ -0,0 +1,94 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateFocusTrapOptions {
+  /** Whether focus trap is actively enabled. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Whether to return focus to previously focused element on cleanup. Defaults to true. */
+  returnFocusOnDeactivate?: boolean;
+}
+
+const FOCUSABLE_SELECTOR =
+  'a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), iframe, object, embed, [tabindex]:not([tabindex="-1"]), [contenteditable]';
+
+/**
+ * SolidJS reactive primitive for trapping keyboard focus inside target container element.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param options Configuration options for focus trap behavior.
+ */
+export function createFocusTrap(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  options: CreateFocusTrapOptions = {}
+): 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" || !isEnabled()) return;
+
+    const container = getTarget();
+    if (!container) return;
+
+    const previousActiveElement = document.activeElement as HTMLElement | null;
+
+    const getFocusableElements = (): HTMLElement[] => {
+      return Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+        (el) => el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0
+      );
+    };
+
+    const focusable = getFocusableElements();
+    if (focusable.length > 0) {
+      focusable[0].focus();
+    } else {
+      container.focus();
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Tab") return;
+
+      const elements = getFocusableElements();
+      if (elements.length === 0) {
+        event.preventDefault();
+        return;
+      }
+
+      const firstElement = elements[0];
+      const lastElement = elements[elements.length - 1];
+      const activeElement = document.activeElement;
+
+      if (event.shiftKey) {
+        if (activeElement === firstElement || !container.contains(activeElement)) {
+          event.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        if (activeElement === lastElement || !container.contains(activeElement)) {
+          event.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+
+    onCleanup(() => {
+      document.removeEventListener("keydown", handleKeyDown);
+
+      if (options.returnFocusOnDeactivate !== false && previousActiveElement) {
+        previousActiveElement.focus?.();
+      }
+    });
+  });
+}

package/src/create-form.ts

@@ -0,0 +1,152 @@
+import { createSignal, createMemo, type Accessor } from "solid-js";
+
+export type FormErrors<T> = Partial<Record<keyof T, string>>;
+export type FormTouched<T> = Partial<Record<keyof T, boolean>>;
+
+export interface CreateFormOptions<T extends Record<string, any>> {
+  /** Initial form field values object */
+  initialValues: T;
+  /** Custom validation function returning error messages object */
+  validate?: (values: T) => FormErrors<T> | Promise<FormErrors<T>>;
+  /** Submit handler callback invoked when validation succeeds */
+  onSubmit?: (values: T) => void | Promise<void>;
+}
+
+export interface CreateFormReturn<T extends Record<string, any>> {
+  /** Accessor for current form field values */
+  values: Accessor<T>;
+  /** Accessor for form field validation error messages */
+  errors: Accessor<FormErrors<T>>;
+  /** Accessor for form field touched states */
+  touched: Accessor<FormTouched<T>>;
+  /** Accessor indicating if form is currently submitting */
+  isSubmitting: Accessor<boolean>;
+  /** Accessor indicating if form has zero validation errors */
+  isValid: Accessor<boolean>;
+  /** Accessor indicating if form values differ from initial values */
+  isDirty: Accessor<boolean>;
+  /** Update specific form field value */
+  setFieldValue: <K extends keyof T>(field: K, value: T[K]) => void;
+  /** Set specific form field validation error */
+  setFieldError: <K extends keyof T>(field: K, error: string | undefined) => void;
+  /** Set specific form field touched state */
+  setFieldTouched: <K extends keyof T>(field: K, isTouched?: boolean) => void;
+  /** Input change event listener helper factory function */
+  handleChange: <K extends keyof T>(field: K) => (e: Event & { currentTarget: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement }) => void;
+  /** Input blur event listener helper factory function */
+  handleBlur: <K extends keyof T>(field: K) => () => void;
+  /** Form onSubmit event handler */
+  handleSubmit: (e?: Event) => void;
+  /** Reset form values, errors, and touched states to initial values */
+  resetForm: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for managing form field state, validation, errors, and submission.
+ *
+ * @param options Form configuration options including initialValues and validate function.
+ */
+export function createForm<T extends Record<string, any>>(
+  options: CreateFormOptions<T>
+): CreateFormReturn<T> {
+  const initialValues = { ...options.initialValues };
+
+  const [values, setValues] = createSignal<T>({ ...initialValues });
+  const [errors, setErrors] = createSignal<FormErrors<T>>({});
+  const [touched, setTouched] = createSignal<FormTouched<T>>({});
+  const [isSubmitting, setIsSubmitting] = createSignal(false);
+
+  const isDirty = createMemo(() => {
+    const current = values();
+    return Object.keys(initialValues).some((key) => current[key] !== initialValues[key]);
+  });
+
+  const isValid = createMemo(() => {
+    const errs = errors();
+    return Object.keys(errs).length === 0;
+  });
+
+  const runValidation = async (currentValues: T): Promise<FormErrors<T>> => {
+    if (!options.validate) return {};
+    const result = await options.validate(currentValues);
+    const newErrors = result || {};
+    setErrors(() => newErrors);
+    return newErrors;
+  };
+
+  const setFieldValue = <K extends keyof T>(field: K, value: T[K]) => {
+    const next = { ...values(), [field]: value };
+    setValues(() => next);
+    runValidation(next);
+  };
+
+  const setFieldError = <K extends keyof T>(field: K, error: string | undefined) => {
+    setErrors((prev) => {
+      const next = { ...prev };
+      if (error) next[field] = error;
+      else delete next[field];
+      return next;
+    });
+  };
+
+  const setFieldTouched = <K extends keyof T>(field: K, isTouched = true) => {
+    setTouched((prev) => ({ ...prev, [field]: isTouched }));
+  };
+
+  const handleChange = <K extends keyof T>(field: K) => {
+    return (e: Event & { currentTarget: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement }) => {
+      const val = e.currentTarget.value;
+      setFieldValue(field, val as any);
+    };
+  };
+
+  const handleBlur = <K extends keyof T>(field: K) => {
+    return () => {
+      setFieldTouched(field, true);
+    };
+  };
+
+  const handleSubmit = async (e?: Event) => {
+    e?.preventDefault();
+    setIsSubmitting(true);
+
+    // Mark all fields as touched on submit
+    const allTouched = Object.keys(values()).reduce((acc, key) => {
+      acc[key as keyof T] = true;
+      return acc;
+    }, {} as FormTouched<T>);
+    setTouched(() => allTouched);
+
+    const validationErrors = await runValidation(values());
+    if (Object.keys(validationErrors).length === 0) {
+      if (options.onSubmit) {
+        await options.onSubmit(values());
+      }
+    }
+
+    setIsSubmitting(false);
+  };
+
+  const resetForm = () => {
+    setValues(() => ({ ...initialValues }));
+    setErrors(() => ({}));
+    setTouched(() => ({}));
+    setIsSubmitting(false);
+  };
+
+  return {
+    values,
+    errors,
+    touched,
+    isSubmitting,
+    isValid,
+    isDirty,
+    setFieldValue,
+    setFieldError,
+    setFieldTouched,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    resetForm,
+  };
+}

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

package/src/create-intersection-observer.ts

@@ -0,0 +1,82 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateIntersectionObserverOptions extends IntersectionObserverInit {
+  /** Whether the observer is active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for observing element visibility and intersection with viewport or root element.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param callback Observer callback invoked on intersection state change.
+ * @param options IntersectionObserver options (root, rootMargin, threshold, enabled).
+ */
+export function createIntersectionObserver(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  callback: IntersectionObserverCallback,
+  options: CreateIntersectionObserverOptions = {}
+): 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.IntersectionObserver) {
+      return;
+    }
+
+    if (!isEnabled()) return;
+
+    const el = getTarget();
+    if (!el) return;
+
+    const observer = new IntersectionObserver(callback, {
+      root: options.root,
+      rootMargin: options.rootMargin,
+      threshold: options.threshold,
+    });
+
+    observer.observe(el);
+
+    onCleanup(() => {
+      observer.disconnect();
+    });
+  });
+}
+
+/**
+ * SolidJS reactive primitive returning a boolean accessor indicating if element is currently visible in viewport.
+ *
+ * @param target Target element or accessor returning HTML element.
+ * @param options IntersectionObserver options.
+ */
+export function createInView(
+  target: HTMLElement | Accessor<HTMLElement | undefined>,
+  options: CreateIntersectionObserverOptions = {}
+): Accessor<boolean> {
+  const [isInView, setIsInView] = createSignal(false);
+
+  createIntersectionObserver(
+    target,
+    (entries) => {
+      const entry = entries[0];
+      if (entry) {
+        setIsInView(entry.isIntersecting);
+      }
+    },
+    options
+  );
+
+  return isInView;
+}