@carlonicora/nextjs-jsonapi 0.0.1 → 1.0.4

package/src/hooks/useDataListRetriever.ts

@@ -0,0 +1,349 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AbstractService } from "../core";
+
+export type PageInfo = {
+  startItem: number;
+  endItem: number;
+  pageSize: number;
+};
+
+export type DataListRetriever<T> = {
+  ready?: boolean;
+  setReady: (state: boolean) => void;
+  isLoaded: boolean;
+  data: T[] | undefined;
+  next?: (onlyNewRecords?: boolean) => Promise<void>;
+  previous?: (onlyNewRecords?: boolean) => Promise<void>;
+  search: (search: string) => Promise<void>;
+  refresh: () => Promise<void>;
+  addAdditionalParameter: (key: string, value: any | null) => void;
+  removeAdditionalParameter: (key: string) => void;
+  setRefreshedElement: (element: T) => void;
+  removeElement: (element: T) => void;
+  isSearch: boolean;
+  pageInfo?: PageInfo;
+};
+
+export function useDataListRetriever<T>(params: {
+  ready?: boolean;
+  retriever: (params: any) => Promise<T[]>;
+  retrieverParams?: any;
+  search?: string;
+  addAdditionalParameter?: (key: string, value: any | null) => void;
+  requiresSearch?: boolean;
+  module: any;
+}): DataListRetriever<T> {
+  const [data, setData] = useState<T[] | undefined>(undefined);
+  const [nextPage, setNextPage] = useState<string | undefined>(undefined);
+  const [previousPage, setPreviousPage] = useState<string | undefined>(undefined);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [ready, setReady] = useState<boolean>(params.ready ?? true);
+  const searchTermRef = useRef<string>("");
+  const additionalParamsRef = useRef<any>({});
+  const requestIdRef = useRef(0);
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const isFetchingRef = useRef(false);
+
+  const resolvedType = params.module;
+  const resolvedService = AbstractService; // We'll just use AbstractService directly for pagination
+
+  // Helper to parse page params from pagination URLs
+  const parsePageParams = useCallback((url: string | undefined): { offset: number; size: number } | null => {
+    if (!url) return null;
+    try {
+      const urlObj = new URL(url);
+      const offset = parseInt(urlObj.searchParams.get("page[offset]") || "0", 10);
+      const size = parseInt(urlObj.searchParams.get("page[size]") || "25", 10);
+      return { offset, size };
+    } catch {
+      return null;
+    }
+  }, []);
+
+  // Helper to adjust pagination URL offset (used when removing elements)
+  const adjustPaginationUrl = useCallback((url: string | undefined, delta: number): string | undefined => {
+    if (!url) return undefined;
+    try {
+      const urlObj = new URL(url);
+      const currentOffset = parseInt(urlObj.searchParams.get("page[offset]") || "0", 10);
+      const newOffset = Math.max(0, currentOffset + delta);
+      urlObj.searchParams.set("page[offset]", String(newOffset));
+      return urlObj.toString();
+    } catch {
+      return url;
+    }
+  }, []);
+
+  // Calculate pageInfo from pagination URLs and current data
+  const pageInfo = useMemo((): PageInfo | undefined => {
+    if (!data || data.length === 0) return undefined;
+
+    // Try to determine current offset and page size from pagination URLs
+    const nextParams = parsePageParams(nextPage);
+    const prevParams = parsePageParams(previousPage);
+
+    let currentOffset = 0;
+    let pageSize = 25; // default
+
+    if (nextParams) {
+      // If we have a next page, current offset = next offset - page size
+      pageSize = nextParams.size;
+      currentOffset = Math.max(0, nextParams.offset - pageSize);
+    } else if (prevParams) {
+      // If we only have a previous page (we're on the last page)
+      pageSize = prevParams.size;
+      currentOffset = prevParams.offset + pageSize;
+    }
+
+    const startItem = currentOffset + 1;
+    const endItem = currentOffset + data.length;
+
+    return { startItem, endItem, pageSize };
+  }, [data, nextPage, previousPage, parsePageParams]);
+
+  const stableParams = useMemo(
+    () => ({
+      service: resolvedService,
+      type: resolvedType,
+      retriever: params.retriever,
+      retrieverParams: params.retrieverParams,
+      requiresSearch: params.requiresSearch,
+    }),
+    [resolvedService, resolvedType, params.retriever, params.retrieverParams, params.requiresSearch],
+  );
+
+  const fetchData = useCallback(
+    async (fetchParams?: { isRefine?: boolean; isRefresh?: boolean; callNext?: boolean; callPrevious?: boolean }) => {
+      if (ready === false) {
+        return;
+      }
+
+      // Prevent concurrent fetches (unless it's a pagination call)
+      if (isFetchingRef.current && !fetchParams?.callNext && !fetchParams?.callPrevious) {
+        return;
+      }
+
+      const thisRequestId = ++requestIdRef.current;
+      isFetchingRef.current = true;
+
+      if (stableParams.requiresSearch === true && fetchParams?.isRefine !== true && fetchParams?.isRefresh !== true)
+        return;
+
+      if (
+        !nextPage &&
+        !previousPage &&
+        isLoaded &&
+        fetchParams?.callNext !== true &&
+        fetchParams?.callPrevious !== true &&
+        params.search === searchTermRef.current
+      )
+        return;
+
+      const currentSearchTerm = searchTermRef.current;
+
+      setIsLoaded(false);
+
+      try {
+        let response: T[];
+        const nextRef = { next: undefined };
+        const previousRef = { previous: undefined };
+        const selfRef = { self: undefined };
+
+        if (nextPage && fetchParams?.callNext && fetchParams?.isRefine !== true) {
+          const ServiceClass = stableParams.service as typeof AbstractService;
+
+          response = await ServiceClass.next<T[]>({
+            type: stableParams.type,
+            endpoint: nextPage,
+            next: nextRef,
+            previous: previousRef,
+            self: selfRef,
+          });
+        } else if (previousPage && fetchParams?.callPrevious && fetchParams?.isRefine !== true) {
+          const ServiceClass = stableParams.service as typeof AbstractService;
+
+          response = await ServiceClass.previous<T[]>({
+            type: stableParams.type,
+            endpoint: previousPage,
+            next: nextRef,
+            previous: previousRef,
+            self: selfRef,
+          });
+        } else {
+          let retrieverParams = stableParams.retrieverParams ? { ...stableParams.retrieverParams } : {};
+
+          retrieverParams = {
+            ...retrieverParams,
+            ...additionalParamsRef.current,
+          };
+
+          retrieverParams.search = currentSearchTerm;
+          retrieverParams.next = nextRef;
+          retrieverParams.previous = previousRef;
+          retrieverParams.self = selfRef;
+
+          response = await stableParams.retriever(retrieverParams);
+        }
+
+        // Only update state if this is still the latest request and wasn't aborted
+        if (thisRequestId === requestIdRef.current && !abortControllerRef.current?.signal.aborted) {
+          if (fetchParams?.isRefresh === true) {
+            setData(response);
+          } else {
+            setData((prevData) => [...(prevData ? (prevData as T[]) : []), ...response]);
+          }
+          setIsLoaded(true);
+          setNextPage(nextRef.next ? nextRef.next : undefined);
+          setPreviousPage(previousRef.previous ? previousRef.previous : undefined);
+        }
+      } catch (error) {
+        // Don't update state if request was aborted (AbortController disabled)
+        if (thisRequestId === requestIdRef.current) {
+          setIsLoaded(true);
+          console.error("Error fetching data:", error);
+        }
+      } finally {
+        // Always reset fetching flag when done
+        if (thisRequestId === requestIdRef.current) {
+          isFetchingRef.current = false;
+        }
+      }
+    },
+    [stableParams, ready, params.search],
+  );
+
+  const setRefreshedElement = useCallback(
+    (element: T) => {
+      setData((prevData) => {
+        if (!prevData) return prevData;
+
+        const index = prevData.findIndex((data) => (data as any).id === (element as any).id);
+        if (index === -1) return prevData;
+
+        // Use immutable update pattern instead of mutation
+        return prevData.map((item, i) => (i === index ? element : item));
+      });
+    },
+    [setData],
+  );
+
+  const removeElement = useCallback(
+    (element: T) => {
+      setData((prevData) => {
+        if (!prevData) return prevData;
+
+        const index = prevData.findIndex((data) => (data as any).id === (element as any).id);
+
+        if (index === -1) return prevData;
+
+        // Adjust nextPage offset since we're removing an item
+        setNextPage((prev) => adjustPaginationUrl(prev, -1));
+
+        const newData = [...prevData];
+        newData.splice(index, 1);
+        return newData;
+      });
+    },
+    [adjustPaginationUrl],
+  );
+
+  // Consolidated effect: Only fetch once when ready and not loaded
+  // This prevents the duplicate API calls that occurred when both the mount effect
+  // and ready effect fired simultaneously on initial render
+  useEffect(() => {
+    // Only fetch if ready and haven't loaded yet
+    if (ready && !isLoaded) {
+      fetchData({ isRefresh: true });
+    }
+  }, [ready, fetchData]);
+
+  const loadNext = useCallback(
+    async (onlyNewRecords?: boolean) => {
+      if (nextPage) fetchData({ isRefresh: onlyNewRecords, callNext: true });
+    },
+    [fetchData, nextPage],
+  );
+
+  const loadPrevious = useCallback(
+    async (onlyNewRecords?: boolean) => {
+      if (previousPage) fetchData({ isRefresh: onlyNewRecords, callPrevious: true });
+    },
+    [fetchData, previousPage],
+  );
+
+  const addAdditionalParameter = useCallback(
+    (key: string, value: any | null) => {
+      if (value === null) {
+        delete additionalParamsRef.current[key];
+      } else {
+        additionalParamsRef.current[key] = value;
+      }
+
+      setReady(true);
+      setNextPage(undefined);
+      setPreviousPage(undefined);
+      fetchData({ isRefine: true, isRefresh: true });
+    },
+    [fetchData],
+  );
+
+  const removeAdditionalParameter = useCallback(
+    (key: string) => {
+      if (additionalParamsRef.current[key] !== undefined) {
+        delete additionalParamsRef.current[key];
+        setNextPage(undefined);
+        setPreviousPage(undefined);
+        fetchData({ isRefine: true, isRefresh: true });
+      }
+    },
+    [fetchData],
+  );
+
+  const search = useCallback(
+    async (search: string) => {
+      if (search === searchTermRef.current) return;
+
+      setNextPage(undefined);
+      setPreviousPage(undefined);
+      searchTermRef.current = search;
+      fetchData({ isRefine: true, isRefresh: true });
+    },
+    [fetchData],
+  );
+
+  const isSearch = !!searchTermRef.current;
+
+  const refresh = useCallback(async () => {
+    setNextPage(undefined);
+    setPreviousPage(undefined);
+    fetchData({ isRefresh: true });
+  }, [fetchData]);
+
+  // Cleanup abort controller on unmount
+  useEffect(() => {
+    return () => {
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+    };
+  }, []);
+
+  return {
+    ready,
+    setReady,
+    isLoaded: isLoaded,
+    data: data as T[],
+    next: nextPage ? loadNext : undefined,
+    previous: previousPage ? loadPrevious : undefined,
+    search: search,
+    addAdditionalParameter: addAdditionalParameter,
+    removeAdditionalParameter: removeAdditionalParameter,
+    refresh: refresh,
+    setRefreshedElement: setRefreshedElement,
+    isSearch: isSearch,
+    removeElement: removeElement,
+    pageInfo: pageInfo,
+  };
+}

package/src/hooks/useDebounce.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useRef } from "react";
+
+export function useDebounce<T extends (...args: any[]) => any>(callback: T, delay: number): T & { cancel: () => void } {
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  const debouncedFunction = useCallback(
+    (...args: Parameters<T>) => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+      timeoutRef.current = setTimeout(() => {
+        callbackRef.current(...args);
+      }, delay);
+    },
+    [delay],
+  );
+
+  // Attach a cancel method to clear pending timeout
+  const cancel = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+  };
+
+  return Object.assign(debouncedFunction, { cancel }) as T & { cancel: () => void };
+}
+
+export default useDebounce;

package/src/hooks/usePageUrlGenerator.ts

@@ -0,0 +1,50 @@
+import { PageUrl } from "../permissions/types";
+
+export function usePageUrlGenerator(): (params: {
+  page?: PageUrl | string;
+  id?: string;
+  childPage?: PageUrl | string;
+  childId?: string;
+  additionalParameters?: { [key: string]: string | string[] | undefined };
+  language?: string;
+}) => string {
+  const generateUrl = (params: {
+    page?: PageUrl | string;
+    id?: string;
+    childPage?: PageUrl | string;
+    childId?: string;
+    additionalParameters?: { [key: string]: string | string[] | undefined };
+    language?: string;
+  }): string => {
+    if (!params.page) return "/";
+
+    const pathParams: string[] = [
+      `${params.language ? `/${params.language}` : ""}${typeof params.page === "string" ? params.page : params.page.pageUrl}`,
+    ];
+
+    if (params.id) {
+      pathParams.push(params.id);
+      if (params.childPage) {
+        pathParams.push(typeof params.childPage === "string" ? params.childPage : (params.childPage.pageUrl ?? ""));
+        if (params.childId) {
+          pathParams.push(params.childId);
+        }
+      }
+    }
+    const response = pathParams.join(`/`);
+
+    if (params.additionalParameters) {
+      const searchParams = new URLSearchParams();
+      for (const key in params.additionalParameters) {
+        if (params.additionalParameters[key]) {
+          searchParams.append(key, params.additionalParameters[key] as string);
+        }
+      }
+      return `${response}?${searchParams.toString()}`;
+    }
+
+    return response;
+  };
+
+  return generateUrl;
+}

package/src/hooks/useTableGenerator.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import { UseTableStructureHook, UseTableStructureHookParams, UseTableStructureHookReturn } from "./types";
+import { ModuleWithPermissions } from "../permissions";
+import { tableGeneratorRegistry } from "./TableGeneratorRegistry";
+
+export function registerTableGenerator<T, U>(type: ModuleWithPermissions, hook: UseTableStructureHook<T, U>): void {
+  tableGeneratorRegistry.register(type.name, hook);
+}
+
+export function useTableGenerator<T, U>(
+  type: ModuleWithPermissions,
+  params: UseTableStructureHookParams<T, U>,
+): UseTableStructureHookReturn<T> {
+  return tableGeneratorRegistry.get(type.name, params);
+}

package/src/i18n/config.ts

@@ -0,0 +1,73 @@
+import { ComponentType } from "react";
+
+// Types for injected hooks
+export interface I18nRouter {
+  push: (href: string) => void;
+  replace: (href: string) => void;
+  back: () => void;
+  forward: () => void;
+  refresh: () => void;
+  prefetch: (href: string) => void;
+}
+
+export type UseRouterHook = () => I18nRouter;
+export type UseTranslationsHook = (namespace?: string) => (key: string, values?: Record<string, any>) => string;
+export type UseLocaleHook = () => string;
+
+export type UseDateFnsLocaleHook = () => any; // date-fns Locale type
+export type LinkComponent = ComponentType<{ href: string; children: React.ReactNode; [key: string]: any }>;
+
+export interface I18nConfig {
+  useRouter: UseRouterHook;
+  useTranslations: UseTranslationsHook;
+  useLocale?: UseLocaleHook;
+  useDateFnsLocale?: UseDateFnsLocaleHook;
+  Link: LinkComponent;
+}
+
+// Private storage
+let _config: I18nConfig | null = null;
+
+// Configuration function (called by app at startup)
+export function configureI18n(config: I18nConfig): void {
+  _config = config;
+}
+
+// Hooks for library components to use
+export function useI18nRouter(): I18nRouter {
+  if (!_config?.useRouter) {
+    throw new Error("i18n not configured. Call configureI18n() at app startup.");
+  }
+  return _config.useRouter();
+}
+
+export function useI18nTranslations(namespace?: string): (key: string, values?: Record<string, any>) => string {
+  if (!_config?.useTranslations) {
+    // Fallback: return key as-is (safe for server/client)
+    return (key: string) => key;
+  }
+  return _config.useTranslations(namespace);
+}
+
+export function getI18nLink(): LinkComponent {
+  if (!_config?.Link) {
+    throw new Error("i18n not configured. Call configureI18n() at app startup.");
+  }
+  return _config.Link;
+}
+
+export function useI18nLocale(): string {
+  if (_config?.useLocale) {
+    return _config.useLocale();
+  }
+  // Fallback to English (safe for server/client)
+  return "en";
+}
+
+export function useI18nDateFnsLocale(): any {
+  if (_config?.useDateFnsLocale) {
+    return _config.useDateFnsLocale();
+  }
+  // Fallback to undefined (Calendar will use default)
+  return undefined;
+}

package/src/i18n/index.ts

@@ -0,0 +1,18 @@
+export {
+  configureI18n,
+  useI18nRouter,
+  useI18nTranslations,
+  useI18nLocale,
+  useI18nDateFnsLocale,
+  getI18nLink,
+} from "./config";
+
+export type {
+  I18nConfig,
+  I18nRouter,
+  UseRouterHook,
+  UseTranslationsHook,
+  UseLocaleHook,
+  UseDateFnsLocaleHook,
+  LinkComponent,
+} from "./config";

package/src/index.ts

@@ -0,0 +1,16 @@
+// Unified API (auto-detects environment)
+export * from "./unified";
+
+// Core exports for convenience
+export * from "./core";
+
+// Permissions
+export * from "./permissions";
+
+// I18n configuration (NOT hooks - those are in /hooks with "use client")
+export { configureI18n } from "./i18n";
+export type { I18nConfig } from "./i18n";
+
+// Roles configuration
+export { configureRoles, getRoleId, isRolesConfigured } from "./roles";
+export type { RoleIdConfig } from "./roles";

package/src/interfaces/breadcrumb.item.data.interface.ts

@@ -0,0 +1,4 @@
+export type BreadcrumbItemData = {
+  name: string;
+  href?: string;
+};

package/src/interfaces/d3.link.interface.ts

@@ -0,0 +1,7 @@
+import { D3Node } from "./d3.node.interface";
+
+export interface D3Link extends d3.SimulationLinkDatum<D3Node> {
+  source: string | D3Node;
+  target: string | D3Node;
+  relationshipType?: string;
+}

package/src/interfaces/d3.node.interface.ts

@@ -0,0 +1,12 @@
+import { LucideIcon } from "lucide-react";
+
+export interface D3Node extends d3.SimulationNodeDatum {
+  id: string;
+  name: string;
+  instanceType: string;
+  relationshipType?: string;
+  isBrowsableNode?: boolean;
+  icon?: LucideIcon;
+  visible?: boolean;
+  washedOut?: boolean;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,3 @@
+export * from "./breadcrumb.item.data.interface";
+export * from "./d3.link.interface";
+export * from "./d3.node.interface";