void-snippets-monorepo 0.1.1

package/packages/react/src/hooks/useAlertMessage.ts

@@ -0,0 +1,45 @@
+import { type ReactNode, useCallback, useState } from "react";
+
+export type VSAlertVariant = "success" | "info" | "error";
+
+export interface VSAlertState {
+  message: ReactNode | string;
+  type: VSAlertVariant;
+  isVisible: boolean;
+}
+
+/**
+ * Manages alert/toast message state with optional auto-hide.
+ *
+ * @param autoHideDuration - ms before alert hides automatically. Pass 0 to disable. Default: 3000
+ *
+ * @example
+ * const { alert, showAlert, hideAlert } = useAlertMessage();
+ * showAlert('Saved successfully!', 'success');
+ * showAlert(<b>Something went wrong</b>, 'error');
+ */
+export function useAlertMessage(autoHideDuration = 3000) {
+  const [alert, setAlert] = useState<VSAlertState>({
+    message: null,
+    type: "info",
+    isVisible: false,
+  });
+
+  const showAlert = useCallback(
+    (message: ReactNode | string, type: VSAlertVariant = "info") => {
+      setAlert({ message, type, isVisible: true });
+      if (autoHideDuration) {
+        setTimeout(() => {
+          setAlert((prev) => ({ ...prev, isVisible: false }));
+        }, autoHideDuration);
+      }
+    },
+    [autoHideDuration]
+  );
+
+  const hideAlert = useCallback(() => {
+    setAlert((prev) => ({ ...prev, isVisible: false }));
+  }, []);
+
+  return { alert, showAlert, hideAlert };
+}

package/packages/react/src/hooks/useAsyncState.ts

@@ -0,0 +1,110 @@
+import { useCallback, useMemo, useState } from "react";
+import { catchError } from "@void-snippets/core";
+
+export type VSAsyncStatus = "idle" | "pending" | "success" | "error";
+
+interface VSAsyncState<T> {
+  data: T | null;
+  status: VSAsyncStatus;
+  error: Error | null;
+}
+
+export interface VSUseAsyncStateReturn<T> extends VSAsyncState<T> {
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+
+  setData: (data: T | null) => void;
+  setError: (error: Error | null) => void;
+  reset: () => void;
+
+  /**
+   * Executes an async function, updates state, and returns a [err, data] tuple.
+   * Allows immediate result handling without try/catch.
+   *
+   * @example
+   * const [err, data] = await execute(() => ContactsApis.create(payload));
+   * if (err) return showAlert(err.message, 'error');
+   * showAlert('Created!', 'success');
+   */
+  execute: (
+    asyncFn: () => Promise<T>,
+    options?: {
+      onSuccess?: (data: T) => void;
+      onError?: (error: Error) => void;
+    }
+  ) => Promise<[Error, null] | [null, T]>;
+}
+
+/**
+ * Generic async state machine — tracks data, status, and error for any async operation.
+ * Pair with any async function: API calls, file reads, timers, etc.
+ *
+ * @param initialData - Optional initial data value. Default: null
+ *
+ * @example
+ * const { data, isLoading, isError, execute } = useAsyncState<User>();
+ *
+ * const handleSubmit = async () => {
+ *   const [err, user] = await execute(() => fetchUser(id));
+ *   if (err) return;
+ *   console.log(user.name);
+ * };
+ */
+export function useAsyncState<T>(
+  initialData: T | null = null
+): VSUseAsyncStateReturn<T> {
+  const [state, setState] = useState<VSAsyncState<T>>({
+    data: initialData,
+    status: "idle",
+    error: null,
+  });
+
+  const setData = useCallback((data: T | null) => {
+    setState({ data, status: "success", error: null });
+  }, []);
+
+  const setError = useCallback((error: Error | null) => {
+    setState((prev) => ({ ...prev, error, status: "error" }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setState({ data: initialData, status: "idle", error: null });
+  }, [initialData]);
+
+  const execute = useCallback(
+    async (
+      asyncFn: () => Promise<T>,
+      options?: {
+        onSuccess?: (data: T) => void;
+        onError?: (error: Error) => void;
+      }
+    ): Promise<[Error, null] | [null, T]> => {
+      setState((prev) => ({ ...prev, status: "pending", error: null }));
+
+      const [err, res] = await catchError(asyncFn());
+
+      if (err) {
+        setState((prev) => ({ ...prev, status: "error", error: err }));
+        options?.onError?.(err);
+        return [err, null];
+      }
+
+      setState({ data: res as T, status: "success", error: null });
+      options?.onSuccess?.(res as T);
+      return [null, res as T];
+    },
+    []
+  );
+
+  const flags = useMemo(
+    () => ({
+      isLoading: state.status === "pending",
+      isSuccess: state.status === "success",
+      isError: state.status === "error",
+    }),
+    [state.status]
+  );
+
+  return { ...state, ...flags, setData, setError, reset, execute };
+}

package/packages/react/src/hooks/useCallTimer.ts

@@ -0,0 +1,37 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Tracks elapsed time from a given start timestamp — useful for call durations,
+ * countdowns, or any elapsed-time display.
+ *
+ * @param startedAt - Unix timestamp in ms (e.g. Date.now()). Pass null/undefined to reset.
+ * @returns Formatted duration string "MM:SS"
+ *
+ * @example
+ * const duration = useCallTimer(call.startedAt);
+ * // duration → "02:45"
+ *
+ * // Reset when no active call
+ * const duration = useCallTimer(activeCall ? activeCall.startedAt : null);
+ */
+export function useCallTimer(startedAt?: number | null): string {
+  const [duration, setDuration] = useState("00:00");
+
+  useEffect(() => {
+    if (!startedAt) {
+      setDuration("00:00");
+      return;
+    }
+
+    const interval = setInterval(() => {
+      const diffInSeconds = Math.floor((Date.now() - startedAt) / 1000);
+      const minutes = Math.floor(diffInSeconds / 60).toString().padStart(2, "0");
+      const seconds = (diffInSeconds % 60).toString().padStart(2, "0");
+      setDuration(`${minutes}:${seconds}`);
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [startedAt]);
+
+  return duration;
+}

package/packages/react/src/hooks/useModal.ts

@@ -0,0 +1,71 @@
+import { useCallback, useState } from "react";
+
+export interface VSModalReturn<T> {
+  isOpen: boolean;
+  data: T | null;
+  isLoading: boolean;
+  openCreateModal: () => void;
+  openEditModal: (editData: T) => void;
+  setLoading: (loading: boolean) => void;
+  closeModal: () => void;
+  setModal: (open: boolean, editData?: T | null) => void;
+}
+
+/**
+ * Manages modal open/close state with optional data payload and loading state.
+ * Works for both create and edit modals — pass data to distinguish the mode.
+ *
+ * @typeParam T - The type of data the modal operates on (e.g. a Contact, User, etc.)
+ *
+ * @example
+ * const modal = useModal<Contact.Base>();
+ *
+ * modal.openCreateModal();      // data → null (create mode)
+ * modal.openEditModal(contact); // data → contact (edit mode)
+ *
+ * if (modal.data) {
+ *   // Edit mode — modal.data is Contact.Base
+ * } else {
+ *   // Create mode
+ * }
+ */
+export function useModal<T = unknown>(): VSModalReturn<T> {
+  const [isOpen, setIsOpen] = useState(false);
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const openCreateModal = useCallback(() => {
+    setIsOpen(true);
+    setData(null);
+  }, []);
+
+  const openEditModal = useCallback((editData: T) => {
+    setIsOpen(true);
+    setData(editData);
+  }, []);
+
+  const setLoading = useCallback((loading: boolean) => {
+    setIsLoading(loading);
+  }, []);
+
+  const closeModal = useCallback(() => {
+    setIsOpen(false);
+    setData(null);
+  }, []);
+
+  const setModal = useCallback((open: boolean, editData?: T | null) => {
+    setIsOpen(open);
+    setData(editData ?? null);
+  }, []);
+
+  return {
+    isOpen,
+    data,
+    isLoading,
+    openCreateModal,
+    openEditModal,
+    setLoading,
+    closeModal,
+    setModal,
+  };
+}

package/packages/react/src/hooks/usePagination.ts

@@ -0,0 +1,57 @@
+import { useCallback, useState } from "react";
+import type { VSQueryParams } from "@void-snippets/core";
+
+export interface VSPaginationReturn {
+  page: number;
+  limit: number;
+  onPaginationChange: (newPage: number, newLimit: number) => void;
+  resetPagination: () => void;
+  setPage: (page: number) => void;
+  setLimit: (limit: number) => void;
+  /** Ready-to-use query params object — pass directly to useList() */
+  queryParams: VSQueryParams;
+}
+
+/**
+ * Manages pagination state and produces a ready-to-use queryParams object
+ * compatible with createResourceHooks' useList() and useInfinite().
+ *
+ * @param initialPage  - Starting page. Default: 1
+ * @param initialLimit - Items per page. Default: 10
+ *
+ * @example
+ * const { queryParams, onPaginationChange } = usePagination(1, 20);
+ *
+ * const { list, isLoading } = contactHooks.useList(queryParams);
+ *
+ * <Pagination onChange={onPaginationChange} total={pagination.totalDocuments} />
+ */
+export function usePagination(
+  initialPage = 1,
+  initialLimit = 10
+): VSPaginationReturn {
+  const [page, setPage] = useState(initialPage);
+  const [limit, setLimit] = useState(initialLimit);
+
+  const onPaginationChange = useCallback(
+    (newPage: number, newLimit: number) => {
+      setPage(newPage);
+      setLimit(newLimit);
+    },
+    []
+  );
+
+  const resetPagination = useCallback(() => {
+    setPage(1);
+  }, []);
+
+  return {
+    page,
+    limit,
+    onPaginationChange,
+    resetPagination,
+    setPage,
+    setLimit,
+    queryParams: { page, limit },
+  };
+}

package/packages/react/src/index.ts

@@ -0,0 +1,43 @@
+// Resource hooks factory
+export { createResourceHooks } from "./hooks/createResourceHooks";
+export type {
+  VSUseListReturn,
+  VSUseGetReturn,
+  VSResourceHooksOptions,
+  VSOptimisticHandlers,
+  VSOptimisticOperation,
+} from "./hooks/createResourceHooks";
+
+// Socket.IO hooks factory
+export { createSocketHooks } from "./socket/createSocketHooks";
+export type { VSSocketConnectionReturn } from "./socket/createSocketHooks";
+
+// Route contract factory
+export {
+  createRouteContract,
+  defineRoute,
+  useTypedSearchParams,
+} from "./routing/createRouteContract";
+export type {
+  RouteMetadata,
+  RouteDefinition,
+  ProcessedRoute,
+} from "./routing/createRouteContract";
+
+// General-purpose React hooks
+export { useAlertMessage } from "./hooks/useAlertMessage";
+export type { VSAlertVariant, VSAlertState } from "./hooks/useAlertMessage";
+
+export { useAsyncState } from "./hooks/useAsyncState";
+export type {
+  VSAsyncStatus,
+  VSUseAsyncStateReturn,
+} from "./hooks/useAsyncState";
+
+export { useCallTimer } from "./hooks/useCallTimer";
+
+export { useModal } from "./hooks/useModal";
+export type { VSModalReturn } from "./hooks/useModal";
+
+export { usePagination } from "./hooks/usePagination";
+export type { VSPaginationReturn } from "./hooks/usePagination";