@nikala-ui/hooks 0.8.0 → 0.9.0

package/src/create-orientation.ts

@@ -0,0 +1,129 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type ScreenOrientationType =
+  | "portrait-primary"
+  | "portrait-secondary"
+  | "landscape-primary"
+  | "landscape-secondary"
+  | "portrait"
+  | "landscape"
+  | "unknown";
+
+export interface CreateOrientationOptions {
+  /** Callback fired when screen orientation changes. */
+  onChange?: (orientation: ScreenOrientationType, angle: number) => void;
+}
+
+export interface CreateOrientationReturn {
+  /** Signal indicating current orientation type. */
+  type: Accessor<ScreenOrientationType>;
+  /** Signal indicating current orientation angle in degrees (0, 90, 180, 270). */
+  angle: Accessor<number>;
+  /** Signal indicating if device screen is in portrait mode. */
+  isPortrait: Accessor<boolean>;
+  /** Signal indicating if device screen is in landscape mode. */
+  isLandscape: Accessor<boolean>;
+  /** Lock screen orientation if supported by device/browser. */
+  lock: (orientation: string) => Promise<void>;
+  /** Unlock screen orientation. */
+  unlock: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for observing mobile/desktop screen orientation and angle.
+ */
+export function createOrientation(
+  options: CreateOrientationOptions = {}
+): CreateOrientationReturn {
+  const [type, setType] = createSignal<ScreenOrientationType>("unknown");
+  const [angle, setAngle] = createSignal<number>(0);
+
+  const getOrientationState = (): { type: ScreenOrientationType; angle: number } => {
+    if (typeof window === "undefined") {
+      return { type: "unknown", angle: 0 };
+    }
+
+    if (window.screen?.orientation) {
+      return {
+        type: window.screen.orientation.type as ScreenOrientationType,
+        angle: window.screen.orientation.angle || 0,
+      };
+    }
+
+    /* Fallback for older browsers using window.orientation */
+    const legacyAngle = (window as unknown as { orientation?: number }).orientation ?? 0;
+    const isPortraitMode = Math.abs(legacyAngle) !== 90;
+    return {
+      type: isPortraitMode ? "portrait" : "landscape",
+      angle: Number(legacyAngle),
+    };
+  };
+
+  createEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const updateState = (): void => {
+      const state = getOrientationState();
+      setType(state.type);
+      setAngle(state.angle);
+      options.onChange?.(state.type, state.angle);
+    };
+
+    updateState();
+
+    if (window.screen?.orientation) {
+      window.screen.orientation.addEventListener("change", updateState);
+      onCleanup(() => {
+        window.screen.orientation.removeEventListener("change", updateState);
+      });
+    } else {
+      window.addEventListener("orientationchange", updateState);
+      window.addEventListener("resize", updateState);
+      onCleanup(() => {
+        window.removeEventListener("orientationchange", updateState);
+        window.removeEventListener("resize", updateState);
+      });
+    }
+  });
+
+  const isPortrait = (): boolean => {
+    const currentType = type();
+    return currentType.startsWith("portrait");
+  };
+
+  const isLandscape = (): boolean => {
+    const currentType = type();
+    return currentType.startsWith("landscape");
+  };
+
+  const lock = async (orientation: string): Promise<void> => {
+    if (typeof window !== "undefined" && window.screen?.orientation) {
+      const orientationApi = window.screen.orientation as unknown as {
+        lock?: (orient: string) => Promise<void>;
+      };
+      if (typeof orientationApi.lock === "function") {
+        await orientationApi.lock(orientation);
+      }
+    }
+  };
+
+  const unlock = (): void => {
+    if (typeof window !== "undefined" && window.screen?.orientation) {
+      const orientationApi = window.screen.orientation as unknown as {
+        unlock?: () => void;
+      };
+      if (typeof orientationApi.unlock === "function") {
+        orientationApi.unlock();
+      }
+    }
+  };
+
+  return {
+    type,
+    angle,
+    isPortrait,
+    isLandscape,
+    lock,
+    unlock,
+  };
+}

package/src/create-permission.ts

@@ -0,0 +1,91 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type PermissionNameType =
+  | "geolocation"
+  | "notifications"
+  | "persistent-storage"
+  | "push"
+  | "screen-wake-lock"
+  | "clipboard-read"
+  | "clipboard-write"
+  | "camera"
+  | "microphone"
+  | (string & {});
+
+export type PermissionStatusState = "granted" | "denied" | "prompt" | "unknown";
+
+export interface CreatePermissionOptions {
+  /** Permission descriptor or name to query. */
+  name: PermissionNameType;
+}
+
+export interface CreatePermissionReturn {
+  /** Signal accessor containing current permission status ('granted', 'denied', 'prompt', 'unknown'). */
+  state: Accessor<PermissionStatusState>;
+  /** Signal accessor indicating whether Permissions API is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+  /** Imperative function to re-query permission status manually. */
+  query: () => Promise<PermissionStatusState>;
+}
+
+/**
+ * SolidJS reactive primitive for querying and observing browser permission status changes.
+ */
+export function createPermission(
+  options: PermissionNameType | CreatePermissionOptions
+): CreatePermissionReturn {
+  const [state, setState] = createSignal<PermissionStatusState>("unknown");
+
+  const permissionName = typeof options === "string" ? options : options.name;
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    "permissions" in navigator;
+
+  let permissionStatus: PermissionStatus | null = null;
+
+  const query = async (): Promise<PermissionStatusState> => {
+    if (!isSupported()) {
+      setState("unknown");
+      return "unknown";
+    }
+
+    try {
+      const status = await navigator.permissions.query({
+        name: permissionName as PermissionName,
+      });
+
+      permissionStatus = status;
+      const currentState = status.state as PermissionStatusState;
+      setState(currentState);
+
+      status.onchange = () => {
+        setState(status.state as PermissionStatusState);
+      };
+
+      return currentState;
+    } catch {
+      setState("unknown");
+      return "unknown";
+    }
+  };
+
+  createEffect(() => {
+    if (!isSupported()) return;
+
+    query();
+
+    onCleanup(() => {
+      if (permissionStatus) {
+        permissionStatus.onchange = null;
+      }
+    });
+  });
+
+  return {
+    state,
+    isSupported,
+    query,
+  };
+}

package/src/create-scroll-into-view.ts

@@ -0,0 +1,57 @@
+import { createEffect, onCleanup, type Accessor } from "solid-js";
+
+export interface CreateScrollIntoViewOptions extends ScrollIntoViewOptions {
+  /** Whether the element should scroll into view automatically. Defaults to true. */
+  enabled?: boolean | Accessor<boolean>;
+  /** Delay in milliseconds before executing scrollIntoView. Defaults to 0. */
+  delay?: number;
+}
+
+/**
+ * SolidJS reactive primitive for scrolling a target element into view smooth or auto behavior.
+ */
+export function createScrollIntoView(
+  target: HTMLElement | Accessor<HTMLElement | null | undefined> | null | undefined,
+  options: CreateScrollIntoViewOptions = {}
+): void {
+  const getTarget = (): HTMLElement | null | undefined => {
+    if (typeof target === "function") {
+      return target();
+    }
+    return target;
+  };
+
+  const isEnabled = (): boolean => {
+    if (typeof options.enabled === "function") {
+      return options.enabled();
+    }
+    return options.enabled ?? true;
+  };
+
+  createEffect(() => {
+    if (!isEnabled()) return;
+
+    const el = getTarget();
+    if (!el || typeof window === "undefined") return;
+
+    const scrollOptions: ScrollIntoViewOptions = {
+      behavior: options.behavior ?? "smooth",
+      block: options.block ?? "nearest",
+      inline: options.inline ?? "nearest",
+    };
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    if (options.delay && options.delay > 0) {
+      timer = setTimeout(() => {
+        el.scrollIntoView(scrollOptions);
+      }, options.delay);
+    } else {
+      el.scrollIntoView(scrollOptions);
+    }
+
+    onCleanup(() => {
+      if (timer) clearTimeout(timer);
+    });
+  });
+}

package/src/create-undo-redo.ts

@@ -0,0 +1,100 @@
+import { createSignal, type Accessor } from "solid-js";
+
+export interface CreateUndoRedoOptions<T> {
+  /** Maximum number of history states to retain. Defaults to 50. */
+  maxHistory?: number;
+}
+
+export interface CreateUndoRedoReturn<T> {
+  /** Signal containing the current state value. */
+  state: Accessor<T>;
+  /** Update state value and append to history. */
+  set: (nextState: T | ((prev: T) => T)) => void;
+  /** Revert to previous state history entry. */
+  undo: () => void;
+  /** Advance to next state history entry. */
+  redo: () => void;
+  /** Signal indicating whether undo is available. */
+  canUndo: Accessor<boolean>;
+  /** Signal indicating whether redo is available. */
+  canRedo: Accessor<boolean>;
+  /** History stack of past states. */
+  history: Accessor<T[]>;
+  /** Reset history to initial state value. */
+  reset: (initialState?: T) => void;
+}
+
+/**
+ * SolidJS reactive primitive for undo/redo state history management.
+ */
+export function createUndoRedo<T>(
+  initialValue: T | Accessor<T>,
+  options: CreateUndoRedoOptions<T> = {}
+): CreateUndoRedoReturn<T> {
+  const getInitial = (): T => {
+    return typeof initialValue === "function"
+      ? (initialValue as Accessor<T>)()
+      : initialValue;
+  };
+
+  const maxHistory = options.maxHistory ?? 50;
+
+  const [history, setHistory] = createSignal<T[]>([getInitial()]);
+  const [pointer, setPointer] = createSignal<number>(0);
+
+  const state = (): T => history()[pointer()] ?? getInitial();
+
+  const canUndo = (): boolean => pointer() > 0;
+  const canRedo = (): boolean => pointer() < history().length - 1;
+
+  const set = (nextState: T | ((prev: T) => T)): void => {
+    const current = state();
+    const resolved =
+      typeof nextState === "function"
+        ? (nextState as (prev: T) => T)(current)
+        : nextState;
+
+    if (Object.is(resolved, current)) return;
+
+    /* Slice history up to current pointer and push new state */
+    const sliced = history().slice(0, pointer() + 1);
+    const updated = [...sliced, resolved];
+
+    /* Trim to maxHistory limit */
+    if (updated.length > maxHistory) {
+      updated.shift();
+    }
+
+    setHistory(updated);
+    setPointer(updated.length - 1);
+  };
+
+  const undo = (): void => {
+    if (canUndo()) {
+      setPointer((p) => p - 1);
+    }
+  };
+
+  const redo = (): void => {
+    if (canRedo()) {
+      setPointer((p) => p + 1);
+    }
+  };
+
+  const reset = (newInitial?: T): void => {
+    const init = newInitial !== undefined ? newInitial : getInitial();
+    setHistory([init]);
+    setPointer(0);
+  };
+
+  return {
+    state,
+    set,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    history,
+    reset,
+  };
+}

package/src/create-web-notification.ts

@@ -0,0 +1,111 @@
+import { createSignal, createEffect, type Accessor } from "solid-js";
+
+export interface CreateWebNotificationOptions extends NotificationOptions {
+  /** Title of the notification. */
+  title?: string;
+  /** Callback fired when notification is clicked. */
+  onClick?: (event: Event) => void;
+  /** Callback fired when notification is closed. */
+  onClose?: (event: Event) => void;
+  /** Callback fired when notification error occurs. */
+  onError?: (event: Event) => void;
+  /** Callback fired when notification is shown. */
+  onShow?: (event: Event) => void;
+}
+
+export interface CreateWebNotificationReturn {
+  /** Signal accessor containing current Notification permission state. */
+  permission: Accessor<NotificationPermission>;
+  /** Signal accessor indicating whether Web Notifications API is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+  /** Function to show a web notification. */
+  show: (overrideTitle?: string, overrideOptions?: NotificationOptions) => Notification | null;
+  /** Request notification permission from browser. */
+  requestPermission: () => Promise<NotificationPermission>;
+  /** Close active notification. */
+  close: () => void;
+}
+
+/**
+ * SolidJS reactive primitive for sending browser desktop notifications and managing notification permissions.
+ */
+export function createWebNotification(
+  defaultOptions: CreateWebNotificationOptions = {}
+): CreateWebNotificationReturn {
+  const [permission, setPermission] = createSignal<NotificationPermission>("default");
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" &&
+    "Notification" in window;
+
+  let activeNotification: Notification | null = null;
+
+  const updatePermission = (): void => {
+    if (isSupported()) {
+      setPermission(Notification.permission);
+    } else {
+      setPermission("denied");
+    }
+  };
+
+  const requestPermission = async (): Promise<NotificationPermission> => {
+    if (!isSupported()) return "denied";
+
+    try {
+      const result = await Notification.requestPermission();
+      setPermission(result);
+      return result;
+    } catch {
+      updatePermission();
+      return permission();
+    }
+  };
+
+  const close = (): void => {
+    if (activeNotification) {
+      activeNotification.close();
+      activeNotification = null;
+    }
+  };
+
+  const show = (
+    overrideTitle?: string,
+    overrideOptions?: NotificationOptions
+  ): Notification | null => {
+    if (!isSupported() || permission() !== "granted") return null;
+
+    const title = overrideTitle ?? defaultOptions.title ?? "Notification";
+    const options: NotificationOptions = {
+      ...defaultOptions,
+      ...overrideOptions,
+    };
+
+    close();
+
+    try {
+      const notification = new Notification(title, options);
+      activeNotification = notification;
+
+      if (defaultOptions.onClick) notification.onclick = (e) => defaultOptions.onClick?.(e);
+      if (defaultOptions.onClose) notification.onclose = (e) => defaultOptions.onClose?.(e);
+      if (defaultOptions.onError) notification.onerror = (e) => defaultOptions.onError?.(e);
+      if (defaultOptions.onShow) notification.onshow = (e) => defaultOptions.onShow?.(e);
+
+      return notification;
+    } catch {
+      return null;
+    }
+  };
+
+  createEffect(() => {
+    updatePermission();
+  });
+
+  return {
+    permission,
+    isSupported,
+    show,
+    requestPermission,
+    close,
+  };
+}

package/src/create-websocket.ts

@@ -0,0 +1,179 @@
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+
+export type WebSocketReadyState = "CONNECTING" | "OPEN" | "CLOSING" | "CLOSED";
+
+export interface CreateWebSocketOptions {
+  /** Subprotocol or list of subprotocols. */
+  protocols?: string | string[];
+  /** Whether to automatically reconnect upon disconnect. Defaults to true. */
+  autoReconnect?: boolean;
+  /** Reconnection delay in milliseconds. Defaults to 3000ms. */
+  reconnectInterval?: number;
+  /** Maximum reconnection attempts. Defaults to 5. */
+  maxReconnectAttempts?: number;
+  /** Whether to open connection immediately upon initialization. Defaults to true. */
+  immediate?: boolean;
+  /** Callback fired when WebSocket connection opens. */
+  onConnected?: (ws: WebSocket) => void;
+  /** Callback fired when WebSocket connection closes. */
+  onDisconnected?: (event: CloseEvent) => void;
+  /** Callback fired when WebSocket receives a message. */
+  onMessage?: (event: MessageEvent) => void;
+  /** Callback fired when WebSocket encounters an error. */
+  onError?: (event: Event) => void;
+}
+
+export interface CreateWebSocketReturn<T = unknown> {
+  /** Signal accessor containing latest received message data (parsed if JSON). */
+  data: Accessor<T | null>;
+  /** Signal accessor containing current WebSocket ready state. */
+  readyState: Accessor<WebSocketReadyState>;
+  /** Signal accessor containing last raw MessageEvent. */
+  lastMessage: Accessor<MessageEvent | null>;
+  /** Send string data or object payload (auto JSON stringified). */
+  send: (data: string | object | ArrayBufferLike | Blob) => boolean;
+  /** Open or reconnect WebSocket connection. */
+  open: () => void;
+  /** Close active WebSocket connection. */
+  close: (code?: number, reason?: string) => void;
+  /** Signal accessor indicating whether WebSocket is supported in browser environment. */
+  isSupported: Accessor<boolean>;
+}
+
+/**
+ * SolidJS reactive primitive for WebSocket client connections, auto-reconnection, and message passing.
+ */
+export function createWebSocket<T = unknown>(
+  url: string | Accessor<string>,
+  options: CreateWebSocketOptions = {}
+): CreateWebSocketReturn<T> {
+  const [data, setData] = createSignal<T | null>(null);
+  const [lastMessage, setLastMessage] = createSignal<MessageEvent | null>(null);
+  const [readyState, setReadyState] = createSignal<WebSocketReadyState>("CLOSED");
+
+  const getUrl = (): string => (typeof url === "function" ? url() : url);
+
+  const isSupported = (): boolean =>
+    typeof window !== "undefined" && "WebSocket" in window;
+
+  let ws: WebSocket | null = null;
+  let reconnectCount = 0;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const mapReadyState = (state: number): WebSocketReadyState => {
+    switch (state) {
+      case WebSocket.CONNECTING:
+        return "CONNECTING";
+      case WebSocket.OPEN:
+        return "OPEN";
+      case WebSocket.CLOSING:
+        return "CLOSING";
+      case WebSocket.CLOSED:
+      default:
+        return "CLOSED";
+    }
+  };
+
+  const close = (code?: number, reason?: string): void => {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    if (ws) {
+      const socket = ws;
+      ws = null;
+      socket.close(code, reason);
+      setReadyState("CLOSED");
+    }
+  };
+
+  const send = (payload: string | object | ArrayBufferLike | Blob): boolean => {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+
+    try {
+      if (typeof payload === "object" && !(payload instanceof ArrayBuffer) && !(payload instanceof Blob)) {
+        ws.send(JSON.stringify(payload));
+      } else {
+        ws.send(payload as any);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const open = (): void => {
+    if (!isSupported()) return;
+
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+
+    setReadyState("CONNECTING");
+
+    try {
+      const targetUrl = getUrl();
+      const socket = new WebSocket(targetUrl, options.protocols);
+      ws = socket;
+
+      socket.onopen = () => {
+        reconnectCount = 0;
+        setReadyState("OPEN");
+        options.onConnected?.(socket);
+      };
+
+      socket.onmessage = (event: MessageEvent) => {
+        setLastMessage(() => event);
+        try {
+          const parsed = JSON.parse(event.data);
+          setData(() => parsed);
+        } catch {
+          setData(() => event.data as unknown as T);
+        }
+        options.onMessage?.(event);
+      };
+
+      socket.onerror = (event: Event) => {
+        options.onError?.(event);
+      };
+
+      socket.onclose = (event: CloseEvent) => {
+        setReadyState("CLOSED");
+        ws = null;
+        options.onDisconnected?.(event);
+
+        if (
+          (options.autoReconnect ?? false) &&
+          reconnectCount < (options.maxReconnectAttempts ?? 5)
+        ) {
+          reconnectCount++;
+          reconnectTimer = setTimeout(open, options.reconnectInterval ?? 3000);
+        }
+      };
+    } catch {
+      setReadyState("CLOSED");
+      ws = null;
+    }
+  };
+
+  createEffect(() => {
+    if (options.immediate ?? true) {
+      open();
+    }
+
+    onCleanup(() => {
+      close();
+    });
+  });
+
+  return {
+    data,
+    readyState,
+    lastMessage,
+    send,
+    open,
+    close,
+    isSupported,
+  };
+}

package/src/index.ts

@@ -22,4 +22,19 @@ export * from "./create-color-mode";
 export * from "./create-form";
 export * from "./create-input-mask";
 export * from "./create-idle";
-export * from "./create-active-element";
+export * from "./create-active-element";
+export * from "./create-infinite-scroll";
+export * from "./create-fullscreen";
+export * from "./create-audio-video";
+export * from "./create-orientation";
+export * from "./create-undo-redo";
+export * from "./create-fetch";
+export * from "./create-geolocation";
+export * from "./create-permission";
+export * from "./create-battery";
+export * from "./create-web-notification";
+export * from "./create-websocket";
+export * from "./create-document-title";
+export * from "./create-favicon";
+export * from "./create-event-source";
+export * from "./create-scroll-into-view";