@nikala-ui/docs 0.12.0

package/dist/vendor/hooks-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;
+}

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

@@ -0,0 +1,148 @@
+import { onMount, onCleanup, type Accessor } from "solid-js";
+
+export interface KeybindingDefinition {
+  /** Key combination string, e.g. "meta+k", "ctrl+k", "Escape", "Shift+Enter" */
+  key: string | string[];
+  /** Callback handler invoked when the key combination is triggered */
+  handler: (event: KeyboardEvent) => void;
+  /** Whether to prevent default browser action. Defaults to false. */
+  preventDefault?: boolean;
+  /** Whether to stop event propagation. Defaults to false. */
+  stopPropagation?: boolean;
+}
+
+export interface CreateKeybindingsOptions {
+  /** Event target to attach listener to. Defaults to window. */
+  target?: HTMLElement | Window | Accessor<HTMLElement | Window | undefined>;
+  /** Event type: "keydown" (default) or "keyup" */
+  eventType?: "keydown" | "keyup";
+  /** Whether keybinding listeners are active. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+/**
+ * Normalizes key string into standardized combination signature (e.g. "ctrl+meta+k").
+ */
+function normalizeKeyCombination(keyStr: string): string {
+  const parts = keyStr.toLowerCase().split("+").map((p) => p.trim());
+  const modifiers = new Set<string>();
+  let mainKey = "";
+
+  for (const part of parts) {
+    if (part === "meta" || part === "cmd" || part === "command" || part === "⌘") {
+      modifiers.add("meta");
+    } else if (part === "ctrl" || part === "control") {
+      modifiers.add("ctrl");
+    } else if (part === "alt" || part === "option" || part === "⌥") {
+      modifiers.add("alt");
+    } else if (part === "shift" || part === "⇧") {
+      modifiers.add("shift");
+    } else {
+      mainKey = part;
+    }
+  }
+
+  const sortedMods = Array.from(modifiers).sort();
+  return [...sortedMods, mainKey].join("+");
+}
+
+/**
+ * Checks if a KeyboardEvent matches a normalized key combination.
+ */
+function isEventMatch(event: KeyboardEvent, targetCombination: string): boolean {
+  const modifiers = new Set<string>();
+  if (event.metaKey) modifiers.add("meta");
+  if (event.ctrlKey) modifiers.add("ctrl");
+  if (event.altKey) modifiers.add("alt");
+  if (event.shiftKey) modifiers.add("shift");
+
+  const mainKey = event.key.toLowerCase();
+  const eventCombination = [...Array.from(modifiers).sort(), mainKey].join("+");
+
+  return eventCombination === targetCombination;
+}
+
+/**
+ * SolidJS reactive primitive for listening to single or multiple keyboard shortcuts.
+ *
+ * @param bindings Array of keybinding definitions or single definition object.
+ * @param options Configuration options including target, event type, and enabled state.
+ */
+export function createKeybindings(
+  bindings: KeybindingDefinition | KeybindingDefinition[],
+  options: CreateKeybindingsOptions = {}
+): void {
+  const bindingList = Array.isArray(bindings) ? bindings : [bindings];
+
+  const isEnabled = () => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  const getTargetElement = (): HTMLElement | Window | undefined => {
+    if (!options.target) {
+      return typeof window !== "undefined" ? window : undefined;
+    }
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | Window | undefined>)();
+    }
+    return options.target;
+  };
+
+  const handleKeyboardEvent = (event: KeyboardEvent) => {
+    if (!isEnabled()) return;
+
+    for (const binding of bindingList) {
+      const keys = Array.isArray(binding.key) ? binding.key : [binding.key];
+
+      for (const keyCombo of keys) {
+        const normalizedCombo = normalizeKeyCombination(keyCombo);
+
+        if (isEventMatch(event, normalizedCombo)) {
+          if (binding.preventDefault) {
+            event.preventDefault();
+          }
+          if (binding.stopPropagation) {
+            event.stopPropagation();
+          }
+          binding.handler(event);
+          break;
+        }
+      }
+    }
+  };
+
+  onMount(() => {
+    const target = getTargetElement();
+    if (!target) return;
+
+    const eventType = options.eventType || "keydown";
+    target.addEventListener(eventType, handleKeyboardEvent as EventListener);
+
+    onCleanup(() => {
+      target.removeEventListener(eventType, handleKeyboardEvent as EventListener);
+    });
+  });
+}
+
+/**
+ * SolidJS primitive specialized for handling Escape key presses.
+ *
+ * @param handler Callback invoked when Escape key is pressed.
+ * @param options Keybindings options.
+ */
+export function createEscapeKey(
+  handler: (event: KeyboardEvent) => void,
+  options: CreateKeybindingsOptions = {}
+): void {
+  createKeybindings(
+    {
+      key: "Escape",
+      handler,
+      preventDefault: true,
+    },
+    options
+  );
+}

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

@@ -0,0 +1,97 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateLockScrollOptions {
+  /** Target element to lock scroll for. Defaults to document.body. */
+  target?: HTMLElement | Accessor<HTMLElement | undefined>;
+  /** Initial lock state. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+}
+
+export interface CreateLockScrollReturn {
+  /** Accessor indicating whether scroll is currently locked */
+  isLocked: Accessor<boolean>;
+  /** Setter function to programmatically lock or unlock scroll */
+  setLocked: (locked: boolean) => void;
+}
+
+/**
+ * SolidJS reactive primitive for locking target element (or document.body) scroll.
+ *
+ * @param options Configuration options including target element and initial enabled state.
+ */
+export function createLockScroll(options: CreateLockScrollOptions = {}): CreateLockScrollReturn {
+  const [internalLocked, setInternalLocked] = createSignal(false);
+
+  const getTarget = (): HTMLElement | undefined => {
+    if (typeof window === "undefined") return undefined;
+
+    if (!options.target) {
+      return document.body;
+    }
+    if (typeof options.target === "function") {
+      return (options.target as Accessor<HTMLElement | undefined>)();
+    }
+    return options.target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  let originalOverflow: string | undefined;
+
+  const applyLock = (element: HTMLElement) => {
+    if (originalOverflow === undefined) {
+      originalOverflow = element.style.overflow;
+    }
+    element.style.overflow = "hidden";
+    setInternalLocked(true);
+  };
+
+  const removeLock = (element: HTMLElement) => {
+    if (originalOverflow !== undefined) {
+      element.style.overflow = originalOverflow;
+      originalOverflow = undefined;
+    } else {
+      element.style.overflow = "";
+    }
+    setInternalLocked(false);
+  };
+
+  createEffect(() => {
+    const el = getTarget();
+    if (!el) return;
+
+    if (isEnabled()) {
+      applyLock(el);
+    } else {
+      removeLock(el);
+    }
+  });
+
+  onCleanup(() => {
+    const el = getTarget();
+    if (el) {
+      removeLock(el);
+    }
+  });
+
+  const setLocked = (locked: boolean) => {
+    const el = getTarget();
+    if (!el) return;
+
+    if (locked) {
+      applyLock(el);
+    } else {
+      removeLock(el);
+    }
+  };
+
+  return {
+    isLocked: internalLocked,
+    setLocked,
+  };
+}

package/dist/vendor/hooks-src/create-long-press.ts

@@ -0,0 +1,85 @@
+import { createSignal, onCleanup } from "solid-js";
+
+export interface CreateLongPressOptions {
+  /** Long press hold threshold duration in milliseconds. Defaults to 500. */
+  threshold?: number;
+  /** Callback fired when long press hold starts */
+  onStart?: () => void;
+  /** Callback fired when long press is successfully completed */
+  onFinish?: () => void;
+  /** Callback fired when long press is cancelled before threshold */
+  onCancel?: () => void;
+}
+
+export interface CreateLongPressReturn {
+  /** Accessor indicating if long press is currently being held */
+  isPressed: () => boolean;
+  /** JSX Event Handlers object to spread or attach onto target element */
+  props: {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onPointerLeave: (e: PointerEvent) => void;
+    onCancel: (e: Event) => void;
+  };
+}
+
+/**
+ * SolidJS reactive primitive for detecting long press / hold interactions on elements.
+ *
+ * @param handler Callback function invoked when long press threshold is reached.
+ * @param options Options for threshold duration and state callbacks.
+ */
+export function createLongPress(
+  handler: (event: Event) => void,
+  options: CreateLongPressOptions = {}
+): CreateLongPressReturn {
+  const threshold = options.threshold ?? 500;
+  const [isPressed, setIsPressed] = createSignal(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const cancel = (e?: Event) => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    if (isPressed()) {
+      setIsPressed(false);
+      options.onCancel?.();
+    }
+  };
+
+  const start = (e: Event) => {
+    cancel();
+    setIsPressed(true);
+    options.onStart?.();
+
+    timer = setTimeout(() => {
+      handler(e);
+      options.onFinish?.();
+      timer = undefined;
+    }, threshold);
+  };
+
+  const finish = (e: Event) => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+      options.onCancel?.();
+    }
+    setIsPressed(false);
+  };
+
+  onCleanup(() => {
+    cancel();
+  });
+
+  return {
+    isPressed,
+    props: {
+      onPointerDown: start,
+      onPointerUp: finish,
+      onPointerLeave: cancel,
+      onCancel: cancel,
+    },
+  };
+}

package/dist/vendor/hooks-src/create-media-query.ts

@@ -0,0 +1,94 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export const DEFAULT_BREAKPOINTS = {
+  sm: "(min-width: 640px)",
+  md: "(min-width: 768px)",
+  lg: "(min-width: 1024px)",
+  xl: "(min-width: 1280px)",
+  "2xl": "(min-width: 1536px)",
+};
+
+/**
+ * SolidJS reactive primitive for tracking CSS media query match state.
+ *
+ * @param query Media query string or accessor returning media query string.
+ */
+export function createMediaQuery(query: string | Accessor<string>): Accessor<boolean> {
+  const getQuery = (): string => {
+    return typeof query === "function" ? query() : query;
+  };
+
+  const [matches, setMatches] = createSignal<boolean>(false);
+
+  createEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) {
+      setMatches(false);
+      return;
+    }
+
+    const currentQuery = getQuery();
+    const mediaQueryList = window.matchMedia(currentQuery);
+
+    setMatches(mediaQueryList.matches);
+
+    const listener = (event: MediaQueryListEvent) => {
+      setMatches(event.matches);
+    };
+
+    if (mediaQueryList.addEventListener) {
+      mediaQueryList.addEventListener("change", listener);
+      onCleanup(() => mediaQueryList.removeEventListener("change", listener));
+    } else {
+      mediaQueryList.addListener(listener);
+      onCleanup(() => mediaQueryList.removeListener(listener));
+    }
+  });
+
+  return matches;
+}
+
+export interface CreateBreakpointReturn {
+  /** Accessor returning active breakpoint key (e.g. 'sm', 'md', 'lg') */
+  active: Accessor<string>;
+  /** Accessor indicating if screen width matches mobile (<768px) */
+  isMobile: Accessor<boolean>;
+  /** Accessor indicating if screen width matches tablet (768px - 1024px) */
+  isTablet: Accessor<boolean>;
+  /** Accessor indicating if screen width matches desktop (>=1024px) */
+  isDesktop: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for tracking responsive Tailwind CSS design breakpoints.
+ *
+ * @param customBreakpoints Custom breakpoint definitions mapping key names to media query strings.
+ */
+export function createBreakpoint(
+  customBreakpoints: Record<string, string> = DEFAULT_BREAKPOINTS
+): CreateBreakpointReturn {
+  const isSm = createMediaQuery(customBreakpoints.sm || DEFAULT_BREAKPOINTS.sm);
+  const isMd = createMediaQuery(customBreakpoints.md || DEFAULT_BREAKPOINTS.md);
+  const isLg = createMediaQuery(customBreakpoints.lg || DEFAULT_BREAKPOINTS.lg);
+  const isXl = createMediaQuery(customBreakpoints.xl || DEFAULT_BREAKPOINTS.xl);
+  const is2Xl = createMediaQuery(customBreakpoints["2xl"] || DEFAULT_BREAKPOINTS["2xl"]);
+
+  const active = (): string => {
+    if (is2Xl()) return "2xl";
+    if (isXl()) return "xl";
+    if (isLg()) return "lg";
+    if (isMd()) return "md";
+    if (isSm()) return "sm";
+    return "xs";
+  };
+
+  const isMobile = (): boolean => !isMd();
+  const isTablet = (): boolean => isMd() && !isLg();
+  const isDesktop = (): boolean => isLg();
+
+  return {
+    active,
+    isMobile,
+    isTablet,
+    isDesktop,
+  };
+}

package/dist/vendor/hooks-src/create-mouse-position.ts

@@ -0,0 +1,87 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateMousePositionOptions {
+  /** Target element to calculate element-relative mouse coordinates for. Defaults to window. */
+  target?: HTMLElement | Window | Accessor<HTMLElement | Window | undefined>;
+}
+
+export interface CreateMousePositionReturn {
+  /** Accessor for global page X mouse position */
+  x: Accessor<number>;
+  /** Accessor for global page Y mouse position */
+  y: Accessor<number>;
+  /** Accessor for element-relative X mouse coordinate */
+  elementX: Accessor<number>;
+  /** Accessor for element-relative Y mouse coordinate */
+  elementY: Accessor<number>;
+  /** Accessor indicating if mouse pointer is inside target element bounds */
+  isInside: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for tracking global and element-relative mouse pointer coordinates.
+ *
+ * @param options Configuration options including target element.
+ */
+export function createMousePosition(
+  options: CreateMousePositionOptions = {}
+): CreateMousePositionReturn {
+  const [x, setX] = createSignal(0);
+  const [y, setY] = createSignal(0);
+  const [elementX, setElementX] = createSignal(0);
+  const [elementY, setElementY] = createSignal(0);
+  const [isInside, setIsInside] = createSignal(false);
+
+  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 handleMouseMove = (event: MouseEvent) => {
+    const pageX = event.pageX;
+    const pageY = event.pageY;
+
+    setX(pageX);
+    setY(pageY);
+
+    const target = getTarget();
+    if (target && target !== window) {
+      const el = target as HTMLElement;
+      const rect = el.getBoundingClientRect();
+      const relX = event.clientX - rect.left;
+      const relY = event.clientY - rect.top;
+
+      setElementX(relX);
+      setElementY(relY);
+
+      const inside =
+        relX >= 0 && relX <= rect.width && relY >= 0 && relY <= rect.height;
+      setIsInside(inside);
+    } else {
+      setElementX(pageX);
+      setElementY(pageY);
+      setIsInside(true);
+    }
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("mousemove", handleMouseMove, { passive: true });
+    onCleanup(() => {
+      window.removeEventListener("mousemove", handleMouseMove);
+    });
+  });
+
+  return {
+    x,
+    y,
+    elementX,
+    elementY,
+    isInside,
+  };
+}

package/dist/vendor/hooks-src/create-network-status.ts

@@ -0,0 +1,100 @@
+import { createEffect, createSignal, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateNetworkStatusReturn {
+  /** Accessor indicating if browser is currently connected to the network */
+  isOnline: Accessor<boolean>;
+  /** Date timestamp when network went offline, if applicable */
+  offlineAt: Accessor<Date | undefined>;
+  /** Date timestamp when network re-connected online, if applicable */
+  onlineAt: Accessor<Date | undefined>;
+  /** Network connection estimated downlink speed in Mbps */
+  downlink: Accessor<number | undefined>;
+  /** Network connection estimated round-trip time in ms */
+  rtt: Accessor<number | undefined>;
+  /** Network connection data saver mode enabled status */
+  saveData: Accessor<boolean | undefined>;
+  /** Network connection effective type ('slow-2g', '2g', '3g', '4g') */
+  effectiveType: Accessor<"slow-2g" | "2g" | "3g" | "4g" | undefined>;
+}
+
+/**
+ * SolidJS reactive primitive for tracking browser network connectivity and connection quality metrics.
+ */
+export function createNetworkStatus(): CreateNetworkStatusReturn {
+  const getInitialOnline = () => (typeof navigator !== "undefined" ? navigator.onLine : true);
+
+  const [isOnline, setIsOnline] = createSignal(getInitialOnline());
+  const [offlineAt, setOfflineAt] = createSignal<Date | undefined>(undefined);
+  const [onlineAt, setOnlineAt] = createSignal<Date | undefined>(undefined);
+
+  const getNetworkConnection = () => {
+    if (typeof navigator === "undefined") return undefined;
+    return (navigator as any).connection || (navigator as any).mozConnection || (navigator as any).webkitConnection;
+  };
+
+  const conn = getNetworkConnection();
+
+  const [downlink, setDownlink] = createSignal<number | undefined>(conn?.downlink);
+  const [rtt, setRtt] = createSignal<number | undefined>(conn?.rtt);
+  const [saveData, setSaveData] = createSignal<boolean | undefined>(conn?.saveData);
+  const [effectiveType, setEffectiveType] = createSignal<"slow-2g" | "2g" | "3g" | "4g" | undefined>(conn?.effectiveType);
+
+  const updateNetworkInfo = () => {
+    const currentConn = getNetworkConnection();
+    if (currentConn) {
+      setDownlink(currentConn.downlink);
+      setRtt(currentConn.rtt);
+      setSaveData(currentConn.saveData);
+      setEffectiveType(currentConn.effectiveType);
+    }
+  };
+
+  const handleOnline = () => {
+    setIsOnline(true);
+    setOnlineAt(new Date());
+    updateNetworkInfo();
+  };
+
+  const handleOffline = () => {
+    setIsOnline(false);
+    setOfflineAt(new Date());
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+
+    const currentConn = getNetworkConnection();
+    if (currentConn && currentConn.addEventListener) {
+      currentConn.addEventListener("change", updateNetworkInfo);
+    }
+
+    onCleanup(() => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+      if (currentConn && currentConn.removeEventListener) {
+        currentConn.removeEventListener("change", updateNetworkInfo);
+      }
+    });
+  });
+
+  return {
+    isOnline,
+    offlineAt,
+    onlineAt,
+    downlink,
+    rtt,
+    saveData,
+    effectiveType,
+  };
+}
+
+/**
+ * SolidJS reactive primitive for checking if browser is connected online.
+ */
+export function createOnline(): Accessor<boolean> {
+  const { isOnline } = createNetworkStatus();
+  return isOnline;
+}