@mohasinac/appkit 2.1.3 → 2.3.0

package/src/react/hooks/useUrlTable.ts

@@ -1,189 +0,0 @@
-"use client";
-
-/**
- * useUrlTable
- *
- * Manages list/table state (filters, sort, pagination, view mode) entirely
- * through URL query params via `router.replace()` — no local state, fully
- * shareable and bookmark-able.
- *
- * Key rules:
- * - `set(key, value)` resets `page` to `'1'` unless the key is `'page'`,
- *   `'pageSize'`, or `'view'`.
- * - `setMany(updates)` resets `page` to `'1'` unless every key in
- *   `updates` is `'page'`, `'pageSize'`, or `'view'`.
- * - Always uses `router.replace()` so filter changes don't pollute history.
- *
- * @example
- * ```tsx
- * const table = useUrlTable({ defaults: { pageSize: '25', sort: '-createdAt' } });
- *
- * // Read
- * table.get('status')        // string | ''
- * table.getNumber('page', 1) // number
- *
- * // Write
- * table.set('status', 'active')   // resets page → 1
- * table.setPage(3)
- * table.setSort('-price')
- * table.setMany({ status: 'active', role: 'seller' })
- *
- * // Build API query strings
- * table.buildSieveParams('status==published')
- * table.buildSearchParams()
- * ```
- */
-
-import { useRouter, usePathname, useSearchParams } from "next/navigation";
-import { useCallback, useRef } from "react";
-
-export interface UseUrlTableOptions {
-  /** Default param values used when a param is absent from the URL */
-  defaults?: Record<string, string>;
-  /**
-   * Override the router used for navigation. Pass a locale-aware router
-   * (e.g. from next-intl) to preserve locale prefixes on replace.
-   */
-  router?: { replace: (url: string) => void };
-  /** Override the current pathname (e.g. from a locale-aware usePathname). */
-  pathname?: string;
-  /**
-   * Override the URLSearchParams instance. Useful when driving the hook
-   * from a non-standard location source.
-   */
-  searchParams?: URLSearchParams;
-}
-
-const NON_RESETTING_KEYS = ["page", "pageSize", "view"] as const;
-
-export function useUrlTable(options?: UseUrlTableOptions) {
-  // Always call native hooks unconditionally (React rules).
-  const nativeRouter = useRouter();
-  const nativePathname = usePathname();
-  const nativeSearchParams = useSearchParams();
-
-  // Callers may inject locale-aware overrides; fall back to native.
-  const router = options?.router ?? nativeRouter;
-  const pathname = options?.pathname ?? nativePathname;
-  const searchParams = options?.searchParams ?? nativeSearchParams;
-
-  // Stabilise defaults — callers often pass object literals inline, which
-  // would recreate all useCallback deps on every render without this ref.
-  const defaultsRef = useRef(options?.defaults ?? {});
-  const defaults = defaultsRef.current;
-
-  const get = useCallback(
-    (key: string) => searchParams.get(key) ?? defaults[key] ?? "",
-    [searchParams, defaults],
-  );
-
-  const getNumber = useCallback(
-    (key: string, fallback = 0) => {
-      const v = get(key);
-      if (!v) return fallback;
-      const n = Number(v);
-      return isNaN(n) ? fallback : n;
-    },
-    [get],
-  );
-
-  const buildParams = useCallback(
-    (updates: Record<string, string>) => {
-      const p = new URLSearchParams(searchParams.toString());
-      for (const [k, v] of Object.entries(updates)) {
-        if (v === "" || v === undefined) p.delete(k);
-        else p.set(k, v);
-      }
-      return p;
-    },
-    [searchParams],
-  );
-
-  const set = useCallback(
-    (key: string, value: string) => {
-      const p = buildParams({ [key]: value });
-      if (
-        !NON_RESETTING_KEYS.includes(key as (typeof NON_RESETTING_KEYS)[number])
-      ) {
-        p.set("page", "1");
-      }
-      router.replace(`${pathname}?${p.toString()}`);
-    },
-    [buildParams, pathname, router],
-  );
-
-  const setMany = useCallback(
-    (updates: Record<string, string>) => {
-      const p = buildParams(updates);
-      const keys = Object.keys(updates);
-      const allNonResetting = keys.every((k) =>
-        NON_RESETTING_KEYS.includes(k as (typeof NON_RESETTING_KEYS)[number]),
-      );
-      if (!allNonResetting && !keys.includes("page")) {
-        p.set("page", "1");
-      }
-      router.replace(`${pathname}?${p.toString()}`);
-    },
-    [buildParams, pathname, router],
-  );
-
-  const clear = useCallback(
-    (keys?: string[]) => {
-      if (keys) {
-        const p = new URLSearchParams(searchParams.toString());
-        keys.forEach((k) => p.delete(k));
-        p.set("page", "1");
-        router.replace(`${pathname}?${p.toString()}`);
-      } else {
-        router.replace(pathname);
-      }
-    },
-    [searchParams, pathname, router],
-  );
-
-  const setPage = (page: number) => set("page", String(page));
-  const setPageSize = (size: number) => set("pageSize", String(size));
-  const setSort = (sort: string) => set("sort", sort);
-
-  const buildSieveParams = useCallback(
-    (sieveFilters: string) => {
-      const page = get("page") || "1";
-      const pageSize = get("pageSize") || defaults["pageSize"] || "25";
-      const sort = get("sort") || defaults["sort"] || "-createdAt";
-      const parts = new URLSearchParams();
-      if (sieveFilters) parts.set("filters", sieveFilters);
-      parts.set("sorts", sort);
-      parts.set("page", page);
-      parts.set("pageSize", pageSize);
-      return `?${parts.toString()}`;
-    },
-    [get, defaults],
-  );
-
-  const buildSearchParams = useCallback(() => {
-    const p = new URLSearchParams();
-    const addIfPresent = (k: string) => {
-      const v = get(k);
-      if (v) p.set(k, v);
-    };
-    ["q", "category", "minPrice", "maxPrice"].forEach(addIfPresent);
-    p.set("sort", get("sort") || defaults["sort"] || "-createdAt");
-    p.set("page", get("page") || "1");
-    p.set("pageSize", get("pageSize") || defaults["pageSize"] || "24");
-    return `?${p.toString()}`;
-  }, [get, defaults]);
-
-  return {
-    params: searchParams,
-    get,
-    getNumber,
-    set,
-    setMany,
-    clear,
-    setPage,
-    setPageSize,
-    setSort,
-    buildSieveParams,
-    buildSearchParams,
-  };
-}

package/src/react/hooks/useVisibleItems.ts

@@ -1,110 +0,0 @@
-// appkit/src/react/hooks/useVisibleItems.ts
-"use client";
-import { useRef, useState, useEffect, useCallback } from "react";
-
-export interface UseVisibleItemsOptions {
-  /** Total number of items */
-  total: number;
-  /** Minimum width of each item in pixels */
-  minItemWidth: number;
-  /** Width reserved for each scroll arrow button (default: 36) */
-  arrowWidth?: number;
-  /** Gap between items in pixels (default: 8) */
-  gap?: number;
-}
-
-export interface UseVisibleItemsResult {
-  /** Attach to the scroll container element */
-  containerRef: React.RefObject<HTMLElement | null>;
-  /** Number of items that fit in the current container width */
-  visibleCount: number;
-  /** Whether any items are hidden (arrows should be shown) */
-  hasOverflow: boolean;
-  /** Index of the first visible item */
-  scrollOffset: number;
-  setScrollOffset: React.Dispatch<React.SetStateAction<number>>;
-  /** Scroll left by one page */
-  scrollLeft: () => void;
-  /** Scroll right by one page */
-  scrollRight: () => void;
-  canScrollLeft: boolean;
-  canScrollRight: boolean;
-}
-
-/**
- * `useVisibleItems` — compute how many items fit in a container, handling
- * arrow button reservations. Powers `HorizontalScroller` and `TabStrip`.
- *
- * **Formula** (when overflow exists):
- * `visible = floor((containerWidth - 2 × (arrowWidth + gap) + gap) / (minItemWidth + gap))`
- *
- * When all items fit without arrows, no arrows are shown.
- */
-export function useVisibleItems({
-  total,
-  minItemWidth,
-  arrowWidth = 36,
-  gap = 8,
-}: UseVisibleItemsOptions): UseVisibleItemsResult {
-  const containerRef = useRef<HTMLElement>(null);
-  const [visibleCount, setVisibleCount] = useState(total);
-  const [scrollOffset, setScrollOffset] = useState(0);
-
-  useEffect(() => {
-    const el = containerRef.current;
-    if (!el) return;
-
-    const compute = (width: number) => {
-      // Check if all items fit without scrolling
-      const totalItemsWidth = total * minItemWidth + Math.max(0, total - 1) * gap;
-      if (totalItemsWidth <= width) {
-        setVisibleCount(total);
-        return;
-      }
-      // Reserve space for both arrows
-      const usable = width - 2 * (arrowWidth + gap);
-      const raw = Math.floor((usable + gap) / (minItemWidth + gap));
-      setVisibleCount(Math.max(1, raw));
-    };
-
-    const ro = new ResizeObserver(([entry]) => {
-      if (entry) compute(entry.contentRect.width);
-    });
-    ro.observe(el);
-    compute(el.getBoundingClientRect().width);
-
-    return () => ro.disconnect();
-  }, [total, minItemWidth, arrowWidth, gap]);
-
-  // Clamp scroll offset when visibleCount or total changes
-  useEffect(() => {
-    setScrollOffset((o) => Math.min(o, Math.max(0, total - visibleCount)));
-  }, [visibleCount, total]);
-
-  const hasOverflow = visibleCount < total;
-
-  const scrollLeft = useCallback(
-    () => setScrollOffset((o) => Math.max(0, o - visibleCount)),
-    [visibleCount],
-  );
-
-  const scrollRight = useCallback(
-    () =>
-      setScrollOffset((o) =>
-        Math.min(total - visibleCount, o + visibleCount),
-      ),
-    [visibleCount, total],
-  );
-
-  return {
-    containerRef,
-    visibleCount,
-    hasOverflow,
-    scrollOffset,
-    setScrollOffset,
-    scrollLeft,
-    scrollRight,
-    canScrollLeft: scrollOffset > 0,
-    canScrollRight: scrollOffset + visibleCount < total,
-  };
-}

package/src/react/index.ts

@@ -1,99 +0,0 @@
-/**
- * @mohasinac/react — Generic React hooks
- *
- * Stage F2: 10 pure browser/React hooks extracted from the app.
- * Zero domain dependencies — safe for use in any React project.
- */
-
-// Viewport / media breakpoints
-export { useMediaQuery } from "./hooks/useMediaQuery";
-export { useBreakpoint } from "./hooks/useBreakpoint";
-
-// DOM interaction
-export { useClickOutside } from "./hooks/useClickOutside";
-export type { UseClickOutsideOptions } from "./hooks/useClickOutside";
-export { useKeyPress } from "./hooks/useKeyPress";
-export type { KeyModifiers, UseKeyPressOptions } from "./hooks/useKeyPress";
-export { useLongPress } from "./hooks/useLongPress";
-
-// Touch / gesture
-export { useGesture } from "./hooks/useGesture";
-export type { GestureType, UseGestureOptions } from "./hooks/useGesture";
-export { useSwipe } from "./hooks/useSwipe";
-export type { SwipeDirection, UseSwipeOptions } from "./hooks/useSwipe";
-export { usePullToRefresh } from "./hooks/usePullToRefresh";
-export type {
-  UsePullToRefreshOptions,
-  UsePullToRefreshReturn,
-} from "./hooks/usePullToRefresh";
-
-// Timer / countdown
-export { useCountdown } from "./hooks/useCountdown";
-export type { CountdownRemaining } from "./hooks/useCountdown";
-
-// Device / hardware
-export { useCamera } from "./hooks/useCamera";
-export type { UseCameraOptions, UseCameraReturn } from "./hooks/useCamera";
-
-// Multi-select / bulk operations
-export { useBulkSelection } from "./hooks/useBulkSelection";
-export type {
-  UseBulkSelectionOptions,
-  UseBulkSelectionReturn,
-} from "./hooks/useBulkSelection";
-
-// URL-driven table / list state
-export { useUrlTable } from "./hooks/useUrlTable";
-export type { UseUrlTableOptions } from "./hooks/useUrlTable";
-
-// Staged (pending) filter management
-export { usePendingFilters } from "./hooks/usePendingFilters";
-export type {
-  UsePendingFiltersOptions,
-  UsePendingFiltersReturn,
-} from "./hooks/usePendingFilters";
-export { usePendingTable } from "./hooks/usePendingTable";
-export type {
-  PendingTable,
-  UsePendingTableReturn,
-} from "./hooks/usePendingTable";
-
-// Unsaved changes tracking
-export { useUnsavedChanges, UNSAVED_CHANGES_EVENT } from "./hooks/useUnsavedChanges";
-export type {
-  UseUnsavedChangesOptions,
-  UseUnsavedChangesReturn,
-} from "./hooks/useUnsavedChanges";
-
-// Bulk action mutation
-export { useBulkAction } from "./hooks/useBulkAction";
-export type {
-  BulkActionPayload,
-  BulkActionResult,
-  BulkActionSummary,
-  BulkActionItemFailure,
-  UseBulkActionOptions,
-  UseBulkActionReturn,
-} from "./hooks/useBulkAction";
-
-// Container-aware fluid grid column counter (ResizeObserver-based)
-export { useContainerGrid } from "./hooks/useContainerGrid";
-export type {
-  UseContainerGridOptions,
-  UseContainerGridResult,
-} from "./hooks/useContainerGrid";
-
-// Visible-items counter for tab strips and overflow scrollers
-export { useVisibleItems } from "./hooks/useVisibleItems";
-export type {
-  UseVisibleItemsOptions,
-  UseVisibleItemsResult,
-} from "./hooks/useVisibleItems";
-
-// Modal stack management
-export { useModalStack } from "./useModalStack";
-export type { ModalEntry } from "./useModalStack";
-
-// Error boundary
-export { ErrorBoundary } from "./ErrorBoundary";
-export type { ErrorBoundaryProps } from "./ErrorBoundary";

package/src/react/useModalStack.ts

@@ -1,86 +0,0 @@
-"use client";
-
-import { useCallback, useRef, useState } from "react";
-
-// ─── ModalEntry ───────────────────────────────────────────────────────────────
-
-export interface ModalEntry<T = unknown> {
-  id: string;
-  data?: T;
-}
-
-// ─── useModalStack ────────────────────────────────────────────────────────────
-
-/**
- * useModalStack — manages a LIFO stack of modal/drawer instances.
- *
- * Supports nested modal flows (e.g. confirmation on top of form).
- * The topmost entry in the stack is the "active" modal.
- *
- * @example
- * ```tsx
- * const { open, close, closeAll, isOpen, peek } = useModalStack<ReviewData>();
- *
- * // open a modal with optional payload:
- * <Button onClick={() => open("review-modal", review)}>Write Review</Button>
- *
- * const active = peek();          // { id: "review-modal", data: review }
- * const visible = isOpen("review-modal");
- * ```
- */
-export function useModalStack<T = unknown>() {
-  const [stack, setStack] = useState<ModalEntry<T>[]>([]);
-  const idCounter = useRef(0);
-
-  const open = useCallback((id: string, data?: T) => {
-    setStack((prev) => [...prev, { id, data }]);
-  }, []);
-
-  const close = useCallback(() => {
-    setStack((prev) => prev.slice(0, -1));
-  }, []);
-
-  const closeAll = useCallback(() => {
-    setStack([]);
-  }, []);
-
-  const closeById = useCallback((id: string) => {
-    setStack((prev) => prev.filter((e) => e.id !== id));
-  }, []);
-
-  const peek = useCallback((): ModalEntry<T> | undefined => {
-    return stack[stack.length - 1];
-  }, [stack]);
-
-  const isOpen = useCallback(
-    (id: string): boolean => {
-      return stack.some((e) => e.id === id);
-    },
-    [stack],
-  );
-
-  const isTopmost = useCallback(
-    (id: string): boolean => {
-      return stack[stack.length - 1]?.id === id;
-    },
-    [stack],
-  );
-
-  const nextId = useCallback(() => {
-    idCounter.current++;
-    return `modal-${idCounter.current}`;
-  }, []);
-
-  return {
-    stack,
-    open,
-    close,
-    closeAll,
-    closeById,
-    peek,
-    isOpen,
-    isTopmost,
-    nextId,
-    depth: stack.length,
-  };
-}

package/src/security/authorization.ts

@@ -1,92 +0,0 @@
-/**
- * Authorization Guards
- *
- * Pure utility functions that throw AuthenticationError / AuthorizationError.
- * Suitable for API routes, Server Actions, and middleware.
- *
- * Note: getUserFromRequest / requireAuthFromRequest are intentionally omitted —
- * they depend on Firebase Admin and the user repository; implement them in your
- * app layer using these primitives.
- */
-
-import { AuthenticationError, AuthorizationError } from "../errors";
-
-export type UserRole = "admin" | "moderator" | "seller" | "user";
-
-const ROLE_HIERARCHY: Record<UserRole, number> = {
-  admin: 4,
-  moderator: 3,
-  seller: 2,
-  user: 1,
-};
-
-const MSG = {
-  NOT_AUTHENTICATED: "Please log in to continue",
-  FORBIDDEN: "You do not have permission to perform this action",
-  EMAIL_NOT_VERIFIED: "Please verify your email address before logging in",
-  ACCOUNT_DISABLED: "Your account has been disabled. Please contact support",
-};
-
-export function requireAuth(user: unknown): void {
-  if (!user) {
-    throw new AuthenticationError(MSG.NOT_AUTHENTICATED);
-  }
-}
-
-export function requireRole(
-  user: Record<string, unknown> | null | undefined,
-  roles: UserRole | UserRole[],
-): void {
-  if (!user) throw new AuthenticationError(MSG.NOT_AUTHENTICATED);
-  const requiredRoles = Array.isArray(roles) ? roles : [roles];
-  const userRole = (user.role as UserRole) || "user";
-  if (!requiredRoles.includes(userRole)) {
-    throw new AuthorizationError(MSG.FORBIDDEN);
-  }
-}
-
-export function requireOwnership(
-  user: Record<string, unknown> | null | undefined,
-  resourceOwnerId: string,
-): void {
-  if (!user) throw new AuthenticationError(MSG.NOT_AUTHENTICATED);
-  if (user.uid !== resourceOwnerId) {
-    throw new AuthorizationError(MSG.FORBIDDEN);
-  }
-}
-
-export function requireEmailVerified(
-  user: Record<string, unknown> | null | undefined,
-): void {
-  if (!user) throw new AuthenticationError(MSG.NOT_AUTHENTICATED);
-  if (!user.emailVerified) throw new AuthorizationError(MSG.EMAIL_NOT_VERIFIED);
-}
-
-export function requireActiveAccount(
-  user: Record<string, unknown> | null | undefined,
-): void {
-  if (!user) throw new AuthenticationError(MSG.NOT_AUTHENTICATED);
-  if (user.disabled) throw new AuthorizationError(MSG.ACCOUNT_DISABLED);
-}
-
-/**
- * Check if currentUserRole is allowed to change a target user's role.
- * - admin:     can change anyone's role
- * - moderator: can only change user → seller
- */
-export function canChangeRole(
-  currentUserRole: UserRole,
-  targetCurrentRole: UserRole,
-  targetNewRole: UserRole,
-): boolean {
-  if (currentUserRole === "admin") return true;
-  if (currentUserRole === "moderator") {
-    return targetCurrentRole === "user" && targetNewRole === "seller";
-  }
-  return false;
-}
-
-/** Return the numeric hierarchy level for a role. */
-export function getRoleLevel(role: UserRole): number {
-  return ROLE_HIERARCHY[role] ?? 0;
-}

package/src/security/csp.ts

@@ -1,44 +0,0 @@
-/**
- * Content Security Policy helpers.
- * Generates a per-request nonce and builds the CSP header string.
- *
- * @example
- * ```ts
- * const nonce = generateNonce();
- * const csp   = buildCSP(nonce);
- * response.headers.set("Content-Security-Policy", csp);
- * requestHeaders.set("x-nonce", nonce);
- * ```
- */
-
-/** Generate a 16-byte base64 nonce for a single request. */
-export function generateNonce(): string {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  return btoa(String.fromCharCode(...bytes));
-}
-
-/** Build the full CSP header value for the given nonce. */
-export function buildCSP(nonce: string): string {
-  const isDev = process.env.NODE_ENV === "development";
-  return [
-    "default-src 'self'",
-    isDev
-      ? "script-src 'self' 'unsafe-eval' 'unsafe-inline'"
-      : `script-src 'self' 'nonce-${nonce}'`,
-    "style-src 'self' 'unsafe-inline'",
-    "img-src 'self' data: https: blob:",
-    "font-src 'self' data:",
-    [
-      "connect-src 'self'",
-      "https://*.googleapis.com",
-      "https://*.google.com",
-      "https://*.firebase.com",
-      "https://*.firebaseio.com",
-      "https://*.cloudfunctions.net",
-    ].join(" "),
-    "frame-src 'self' https://accounts.google.com",
-    "media-src 'self' https: blob:",
-    "worker-src 'self' blob:",
-  ].join("; ");
-}

package/src/security/index.ts

@@ -1,50 +0,0 @@
-export { generateNonce, buildCSP } from "./csp";
-export {
-  rateLimit,
-  applyRateLimit,
-  rateLimitByIdentifier,
-  RateLimitPresets,
-  clearRateLimitStore,
-} from "./rate-limit";
-export type { RateLimitConfig, RateLimitResult } from "./rate-limit";
-export {
-  requireAuth,
-  requireRole,
-  requireOwnership,
-  requireEmailVerified,
-  requireActiveAccount,
-  canChangeRole,
-  getRoleLevel,
-} from "./authorization";
-export type { UserRole } from "./authorization";
-export { redactPii } from "./pii-redact";
-export {
-  encryptValue,
-  decryptValue,
-  hmacBlindIndex,
-  encryptPiiFields,
-  decryptPiiFields,
-  ENC_PREFIX,
-  HMAC_PREFIX,
-} from "./pii-encrypt";
-
-// RBAC system
-export type {
-  Permission,
-  RoleDefinition,
-  RbacConfig,
-  ResolvedUser,
-  RbacHookReturn,
-} from "./rbac";
-export {
-  DEFAULT_ROLES,
-  resolvePermissions,
-  hasPermission,
-  hasAllPermissions,
-  hasAnyPermission,
-  createRbacHook,
-  Can,
-  createRequirePermission,
-  createRequirePermissionSync,
-  createRbacMiddleware,
-} from "./rbac";