@mohasinac/appkit 2.1.3 → 2.3.0

package/src/react/ErrorBoundary.tsx

@@ -1,130 +0,0 @@
-"use client";
-
-/**
- * Generic React Error Boundary
- *
- * Catches errors anywhere in the wrapped component tree and renders a
- * configurable fallback UI. Pass `fallback` for a fully custom view, or
- * `renderFallback` for a render-prop version that receives the caught error
- * and a reset handler.
- */
-
-import { Component, type ReactNode, type ErrorInfo } from "react";
-import { Logger } from "../core";
-import {
-  trackError,
-  ErrorCategory,
-  ErrorSeverity,
-} from "../monitoring/error-tracking";
-
-export interface ErrorBoundaryProps {
-  children: ReactNode;
-  /** Static fallback node — shown instead of the default error UI. */
-  fallback?: ReactNode;
-  /** Render-prop fallback — receives the error and a reset callback. */
-  renderFallback?: (error: Error | null, reset: () => void) => ReactNode;
-  /** Optional callback invoked after componentDidCatch. */
-  onError?: (error: Error, errorInfo: ErrorInfo) => void;
-}
-
-interface State {
-  hasError: boolean;
-  error: Error | null;
-}
-
-function DefaultFallback({
-  error,
-  onReset,
-}: {
-  error: Error | null;
-  onReset: () => void;
-}) {
-  return (
-    <div
-      role="alert"
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        alignItems: "center",
-        justifyContent: "center",
-        minHeight: "100vh",
-        padding: "2rem",
-        textAlign: "center",
-      }}
-    >
-      <h1 style={{ fontSize: "1.5rem", marginBottom: "0.5rem" }}>
-        Something went wrong
-      </h1>
-      <p style={{ marginBottom: "1.5rem", opacity: 0.7 }}>
-        An unexpected error occurred. Please try again.
-      </p>
-      {process.env.NODE_ENV === "development" && error && (
-        <pre
-          style={{
-            fontSize: "0.75rem",
-            padding: "1rem",
-            background: "#f3f4f6",
-            borderRadius: "0.5rem",
-            textAlign: "left",
-            maxWidth: "40rem",
-            overflow: "auto",
-            marginBottom: "1.5rem",
-          }}
-        >
-          {error.message}
-        </pre>
-      )}
-      <button onClick={onReset} type="button">
-        Try again
-      </button>
-    </div>
-  );
-}
-
-export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
-  private readonly log = Logger.getInstance({ enableConsole: true });
-
-  constructor(props: ErrorBoundaryProps) {
-    super(props);
-    this.state = { hasError: false, error: null };
-  }
-
-  static getDerivedStateFromError(error: Error): State {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    this.log.error("ErrorBoundary caught an error", {
-      error: error.message,
-      stack: error.stack,
-      componentStack: errorInfo.componentStack,
-      timestamp: new Date().toISOString(),
-    });
-
-    trackError(error, ErrorCategory.UI, ErrorSeverity.HIGH);
-
-    this.props.onError?.(error, errorInfo);
-  }
-
-  handleReset = () => {
-    this.setState({ hasError: false, error: null });
-  };
-
-  render() {
-    if (!this.state.hasError) {
-      return this.props.children;
-    }
-
-    if (this.props.renderFallback) {
-      return this.props.renderFallback(this.state.error, this.handleReset);
-    }
-
-    if (this.props.fallback) {
-      return this.props.fallback;
-    }
-
-    return (
-      <DefaultFallback error={this.state.error} onReset={this.handleReset} />
-    );
-  }
-}

package/src/react/hooks/useBreakpoint.ts

@@ -1,41 +0,0 @@
-"use client";
-
-import { useMediaQuery } from "./useMediaQuery";
-
-/**
- * useBreakpoint Hook
- *
- * Convenience hook for detecting common Tailwind breakpoints.
- * Returns boolean flags and the current breakpoint name.
- *
- * Breakpoints (Tailwind defaults):
- * - Mobile: < 768px
- * - Tablet: 768px - 1023px
- * - Desktop: >= 1024px
- *
- * @returns Object with breakpoint detection flags
- *
- * @example
- * ```tsx
- * const { isMobile, isTablet, isDesktop, breakpoint } = useBreakpoint();
- *
- * if (isMobile) {
- *   return <MobileView />;
- * }
- * return <DesktopView />;
- * ```
- */
-export function useBreakpoint() {
-  const isMobile = useMediaQuery("(max-width: 767px)");
-  const isTablet = useMediaQuery("(min-width: 768px) and (max-width: 1023px)");
-  const isDesktop = useMediaQuery("(min-width: 1024px)");
-
-  const breakpoint = isMobile ? "mobile" : isTablet ? "tablet" : "desktop";
-
-  return {
-    isMobile,
-    isTablet,
-    isDesktop,
-    breakpoint: breakpoint as "mobile" | "tablet" | "desktop",
-  };
-}

package/src/react/hooks/useBulkAction.ts

@@ -1,161 +0,0 @@
-"use client";
-
-import { useState, useCallback, useRef } from "react";
-
-// ---------------------------------------------------------------------------
-// Shared types — safe to use in any project consuming @mohasinac/react
-// ---------------------------------------------------------------------------
-
-export interface BulkActionItemFailure {
-  id: string;
-  reason: string;
-}
-
-export interface BulkActionSummary {
-  total: number;
-  succeeded: number;
-  skipped: number;
-  failed: number;
-}
-
-export interface BulkActionResult<TData = Record<string, unknown>> {
-  action: string;
-  summary: BulkActionSummary;
-  succeeded: string[];
-  skipped: string[];
-  failed: BulkActionItemFailure[];
-  data?: TData;
-}
-
-export interface BulkActionPayload {
-  action: string;
-  ids: string[];
-}
-
-// ---------------------------------------------------------------------------
-// useBulkAction
-// ---------------------------------------------------------------------------
-
-export interface UseBulkActionOptions<
-  TPayload extends BulkActionPayload,
-  TData = Record<string, unknown>,
-> {
-  /**
-   * Async function that POSTs to the bulk endpoint.
-   * Must return `Promise<BulkActionResult<TData>>`.
-   */
-  mutationFn: (payload: TPayload) => Promise<BulkActionResult<TData>>;
-  /**
-   * Called when `mutationFn` resolves (even for partial failures).
-   * Inspect `result.summary` to build feedback.
-   */
-  onSuccess?: (
-    result: BulkActionResult<TData>,
-    payload: TPayload,
-  ) => void | Promise<void>;
-  /**
-   * Called when `mutationFn` rejects.
-   */
-  onError?: (error: Error, payload: TPayload) => void;
-  /**
-   * When `true`, `execute()` parks the payload in `pendingPayload` instead of
-   * running immediately. The caller renders a confirm modal wired to
-   * `confirmAndExecute` / `cancelConfirm`.
-   */
-  requiresConfirm?: boolean;
-}
-
-export interface UseBulkActionReturn<
-  TPayload extends BulkActionPayload,
-  TData = Record<string, unknown>,
-> {
-  execute: (payload: TPayload) => Promise<void>;
-  isLoading: boolean;
-  result: BulkActionResult<TData> | null;
-  error: Error | null;
-  reset: () => void;
-  pendingPayload: TPayload | null;
-  confirmAndExecute: () => Promise<void>;
-  cancelConfirm: () => void;
-}
-
-/**
- * useBulkAction
- *
- * Generic mutation hook for any `/bulk` endpoint.
- * Handles loading state, partial-success result tracking, and an optional
- * confirmation flow for destructive operations.
- *
- * Pair with `useBulkSelection` and a `BulkActionBar` component for the
- * full admin list pattern.
- */
-export function useBulkAction<
-  TPayload extends BulkActionPayload = BulkActionPayload,
-  TData = Record<string, unknown>,
->(
-  options: UseBulkActionOptions<TPayload, TData>,
-): UseBulkActionReturn<TPayload, TData> {
-  const [isLoading, setIsLoading] = useState(false);
-  const [result, setResult] = useState<BulkActionResult<TData> | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-  const [pendingPayload, setPendingPayload] = useState<TPayload | null>(null);
-
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  const runMutation = useCallback(async (payload: TPayload) => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      const res = await optionsRef.current.mutationFn(payload);
-      setResult(res);
-      await optionsRef.current.onSuccess?.(res, payload);
-    } catch (err) {
-      const error =
-        err instanceof Error
-          ? err
-          : new Error((err as { message?: string })?.message ?? "Unexpected error");
-      setError(error);
-      optionsRef.current.onError?.(error, payload);
-    } finally {
-      setIsLoading(false);
-    }
-  }, []);
-
-  const execute = useCallback(
-    async (payload: TPayload) => {
-      if (optionsRef.current.requiresConfirm) {
-        setPendingPayload(payload);
-        return;
-      }
-      await runMutation(payload);
-    },
-    [runMutation],
-  );
-
-  const confirmAndExecute = useCallback(async () => {
-    if (!pendingPayload) return;
-    const payload = pendingPayload;
-    setPendingPayload(null);
-    await runMutation(payload);
-  }, [pendingPayload, runMutation]);
-
-  const cancelConfirm = useCallback(() => setPendingPayload(null), []);
-
-  const reset = useCallback(() => {
-    setResult(null);
-    setError(null);
-    setPendingPayload(null);
-  }, []);
-
-  return {
-    execute,
-    isLoading,
-    result,
-    error,
-    reset,
-    pendingPayload,
-    confirmAndExecute,
-    cancelConfirm,
-  };
-}

package/src/react/hooks/useBulkSelection.ts

@@ -1,119 +0,0 @@
-"use client";
-
-/**
- * useBulkSelection
- *
- * Generic multi-select state hook for list/table rows.
- * Pairs with any table component that accepts `selectedIds` and
- * `onSelectionChange` props.
- *
- * @example
- * ```tsx
- * const selection = useBulkSelection({ items, keyExtractor: (p) => p.id });
- *
- * <DataTable
- *   selectable
- *   selectedIds={selection.selectedIds}
- *   onSelectionChange={selection.setSelectedIds}
- * />
- * ```
- */
-
-import { useState, useCallback, useMemo } from "react";
-import type { Dispatch, SetStateAction } from "react";
-
-/** Default API limit — match the `z.array().max(N)` on your bulk endpoint */
-const BULK_MAX_IDS = 100;
-
-export interface UseBulkSelectionOptions<T> {
-  /** The current page / list of items being displayed. */
-  items: T[];
-  /** Extract a stable unique key from each item (e.g. `item => item.id`). */
-  keyExtractor: (item: T) => string;
-  /**
-   * Maximum number of IDs that can be selected at once.
-   * @default 100
-   */
-  maxSelection?: number;
-}
-
-export interface UseBulkSelectionReturn {
-  selectedIds: string[];
-  selectedCount: number;
-  /** Returns `true` if the given ID is currently selected. */
-  isSelected: (id: string) => boolean;
-  /** `true` when every item on the current page is selected. */
-  isAllSelected: boolean;
-  /**
-   * `true` when some — but not all — items are selected.
-   * Use to set the indeterminate state on the header checkbox.
-   */
-  isIndeterminate: boolean;
-  /** Toggle one item in or out of the selection. Respects `maxSelection`. */
-  toggle: (id: string) => void;
-  /**
-   * Select all items on the current page (up to `maxSelection`),
-   * or deselect all if every item is already selected.
-   */
-  toggleAll: () => void;
-  /** Deselect everything. Call this after a bulk action completes. */
-  clearSelection: () => void;
-  /**
-   * Direct state setter — pass straight to a table's `onSelectionChange`
-   * or use when you need to replace the entire selection programmatically.
-   */
-  setSelectedIds: Dispatch<SetStateAction<string[]>>;
-}
-
-export function useBulkSelection<T>({
-  items,
-  keyExtractor,
-  maxSelection = BULK_MAX_IDS,
-}: UseBulkSelectionOptions<T>): UseBulkSelectionReturn {
-  const [selectedIds, setSelectedIds] = useState<string[]>([]);
-
-  const allIds = useMemo(() => items.map(keyExtractor), [items, keyExtractor]);
-
-  const isSelected = useCallback(
-    (id: string) => selectedIds.includes(id),
-    [selectedIds],
-  );
-
-  const toggle = useCallback(
-    (id: string) => {
-      setSelectedIds((prev) => {
-        if (prev.includes(id)) return prev.filter((s) => s !== id);
-        if (prev.length >= maxSelection) return prev;
-        return [...prev, id];
-      });
-    },
-    [maxSelection],
-  );
-
-  const toggleAll = useCallback(() => {
-    setSelectedIds((prev) => {
-      const allSelected = prev.length === allIds.length && allIds.length > 0;
-      if (allSelected) return [];
-      return allIds.slice(0, maxSelection);
-    });
-  }, [allIds, maxSelection]);
-
-  const clearSelection = useCallback(() => setSelectedIds([]), []);
-
-  const isAllSelected =
-    allIds.length > 0 && selectedIds.length === allIds.length;
-  const isIndeterminate =
-    selectedIds.length > 0 && selectedIds.length < allIds.length;
-
-  return {
-    selectedIds,
-    selectedCount: selectedIds.length,
-    isSelected,
-    isAllSelected,
-    isIndeterminate,
-    toggle,
-    toggleAll,
-    clearSelection,
-    setSelectedIds,
-  };
-}

package/src/react/hooks/useCamera.ts

@@ -1,191 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useRef, useState } from "react";
-
-export interface UseCameraOptions {
-  facingMode?: "user" | "environment";
-  video?: boolean | MediaTrackConstraints;
-  audio?: boolean;
-}
-
-export interface UseCameraReturn {
-  isSupported: boolean;
-  isActive: boolean;
-  isCapturing: boolean;
-  stream: MediaStream | null;
-  error: string | null;
-  videoRef: React.RefObject<HTMLVideoElement | null>;
-  startCamera: (options?: UseCameraOptions) => Promise<void>;
-  stopCamera: () => void;
-  takePhoto: () => Blob | null;
-  startRecording: () => void;
-  stopRecording: () => Promise<Blob>;
-  switchCamera: () => Promise<void>;
-}
-
-/**
- * useCamera
- *
- * Provides access to the device camera via the MediaDevices API.
- * Zero domain imports. Safe to use in any Tier 1 / Tier 2 component.
- *
- * Lifecycle:
- * - Call `startCamera()` to open the stream and wire `videoRef` to a <video> element.
- * - `stopCamera()` releases hardware tracks (turns off the camera indicator light).
- * - `takePhoto()` captures the current frame as image/webp.
- * - `startRecording()` / `stopRecording()` use MediaRecorder (video/webm output).
- * - `useEffect` cleanup calls `stopCamera()` automatically on unmount.
- */
-export function useCamera(): UseCameraReturn {
-  const isSupported =
-    typeof navigator !== "undefined" &&
-    typeof navigator.mediaDevices !== "undefined" &&
-    typeof navigator.mediaDevices.getUserMedia === "function";
-
-  const videoRef = useRef<HTMLVideoElement>(null);
-  const streamRef = useRef<MediaStream | null>(null);
-  const mediaRecorderRef = useRef<MediaRecorder | null>(null);
-  const chunksRef = useRef<Blob[]>([]);
-  const currentFacingModeRef = useRef<"user" | "environment">("environment");
-  const stopRecordingResolveRef = useRef<((blob: Blob) => void) | null>(null);
-
-  const [stream, setStream] = useState<MediaStream | null>(null);
-  const [isActive, setIsActive] = useState(false);
-  const [isCapturing, setIsCapturing] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const stopCamera = useCallback(() => {
-    if (streamRef.current) {
-      streamRef.current.getTracks().forEach((t) => t.stop());
-      streamRef.current = null;
-    }
-    if (videoRef.current) {
-      videoRef.current.srcObject = null;
-    }
-    setStream(null);
-    setIsActive(false);
-    setIsCapturing(false);
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      stopCamera();
-    };
-  }, [stopCamera]);
-
-  const startCamera = useCallback(
-    async (options?: UseCameraOptions) => {
-      if (!isSupported) {
-        setError("Camera is not supported on this device");
-        return;
-      }
-      setError(null);
-      stopCamera();
-
-      const facingMode = options?.facingMode ?? "environment";
-      currentFacingModeRef.current = facingMode;
-
-      const videoConstraints: boolean | MediaTrackConstraints =
-        options?.video !== undefined ? options.video : { facingMode };
-
-      try {
-        const mediaStream = await navigator.mediaDevices.getUserMedia({
-          video: videoConstraints,
-          audio: options?.audio ?? false,
-        });
-        streamRef.current = mediaStream;
-        setStream(mediaStream);
-        setIsActive(true);
-        if (videoRef.current) {
-          videoRef.current.srcObject = mediaStream;
-        }
-      } catch (err) {
-        const message =
-          err instanceof DOMException && err.name === "NotAllowedError"
-            ? "Camera permission denied. Please allow access in your browser settings."
-            : "Camera unavailable";
-        setError(message);
-      }
-    },
-    [isSupported, stopCamera],
-  );
-
-  const takePhoto = useCallback((): Blob | null => {
-    const video = videoRef.current;
-    if (!video || !isActive) return null;
-
-    const canvas = document.createElement("canvas");
-    canvas.width = video.videoWidth;
-    canvas.height = video.videoHeight;
-    const ctx = canvas.getContext("2d");
-    if (!ctx) return null;
-    ctx.drawImage(video, 0, 0);
-
-    let result: Blob | null = null;
-    canvas.toBlob(
-      (blob) => {
-        result = blob;
-      },
-      "image/webp",
-      0.92,
-    );
-    return result;
-  }, [isActive]);
-
-  const startRecording = useCallback(() => {
-    if (!streamRef.current || !isActive) return;
-    chunksRef.current = [];
-    const recorder = new MediaRecorder(streamRef.current, {
-      mimeType: "video/webm",
-    });
-    recorder.ondataavailable = (e) => {
-      if (e.data.size > 0) chunksRef.current.push(e.data);
-    };
-    recorder.onstop = () => {
-      const blob = new Blob(chunksRef.current, { type: "video/webm" });
-      setIsCapturing(false);
-      if (stopRecordingResolveRef.current) {
-        stopRecordingResolveRef.current(blob);
-        stopRecordingResolveRef.current = null;
-      }
-    };
-    mediaRecorderRef.current = recorder;
-    recorder.start();
-    setIsCapturing(true);
-  }, [isActive]);
-
-  const stopRecording = useCallback((): Promise<Blob> => {
-    return new Promise((resolve) => {
-      stopRecordingResolveRef.current = resolve;
-      if (
-        mediaRecorderRef.current &&
-        mediaRecorderRef.current.state !== "inactive"
-      ) {
-        mediaRecorderRef.current.stop();
-      } else {
-        resolve(new Blob([], { type: "video/webm" }));
-      }
-    });
-  }, []);
-
-  const switchCamera = useCallback(async () => {
-    const next =
-      currentFacingModeRef.current === "environment" ? "user" : "environment";
-    await startCamera({ facingMode: next });
-  }, [startCamera]);
-
-  return {
-    isSupported,
-    isActive,
-    isCapturing,
-    stream,
-    error,
-    videoRef,
-    startCamera,
-    stopCamera,
-    takePhoto,
-    startRecording,
-    stopRecording,
-    switchCamera,
-  };
-}