@carlonicora/nextjs-jsonapi 1.34.0 → 1.36.0

package/src/features/onboarding/contexts/OnboardingContext.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import { createRoot, Root } from "react-dom/client";
+import Shepherd from "shepherd.js";
+import "shepherd.js/dist/css/shepherd.css";
+import { OnboardingCard } from "../components/OnboardingCard";
+import {
+  DEFAULT_ONBOARDING_LABELS,
+  OnboardingContextValue,
+  OnboardingProviderProps,
+  OnboardingStepConfig,
+} from "../interfaces";
+import "../styles/onboarding.css";
+
+const OnboardingContext = createContext<OnboardingContextValue | null>(null);
+
+export function OnboardingProvider({
+  children,
+  tours = [],
+  tourPaths = {},
+  labels = DEFAULT_ONBOARDING_LABELS,
+  renderCard,
+  zIndex = 9999,
+}: OnboardingProviderProps) {
+  const [isTourActive, setIsTourActive] = useState(false);
+  const [activeTourId, setActiveTourId] = useState<string | null>(null);
+  const [currentStepIndex, setCurrentStepIndex] = useState(0);
+  const [totalSteps, setTotalSteps] = useState(0);
+
+  const tourRef = useRef<InstanceType<typeof Shepherd.Tour> | null>(null);
+  const rootsRef = useRef<Map<string, Root>>(new Map());
+
+  const cleanupRoots = useCallback(() => {
+    rootsRef.current.forEach((root) => {
+      try {
+        root.unmount();
+      } catch (e) {
+        // Root may already be unmounted
+      }
+    });
+    rootsRef.current.clear();
+  }, []);
+
+  const closeTour = useCallback(() => {
+    if (tourRef.current) {
+      tourRef.current.cancel();
+      tourRef.current = null;
+    }
+    cleanupRoots();
+    setIsTourActive(false);
+    setActiveTourId(null);
+    setCurrentStepIndex(0);
+    setTotalSteps(0);
+  }, [cleanupRoots]);
+
+  const nextStep = useCallback(() => {
+    if (tourRef.current) {
+      tourRef.current.next();
+    }
+  }, []);
+
+  const previousStep = useCallback(() => {
+    if (tourRef.current) {
+      tourRef.current.back();
+    }
+  }, []);
+
+  const goToStep = useCallback((index: number) => {
+    if (tourRef.current) {
+      tourRef.current.show(index);
+    }
+  }, []);
+
+  const startTour = useCallback(
+    (tourId: string, steps?: OnboardingStepConfig[]) => {
+      if (typeof window === "undefined") return;
+
+      // Close any existing tour
+      if (tourRef.current) {
+        closeTour();
+      }
+
+      // Get steps from provided steps or find tour by ID
+      let tourSteps = steps;
+      if (!tourSteps) {
+        const tour = tours.find((t) => t.id === tourId);
+        tourSteps = tour?.steps;
+      }
+
+      if (!tourSteps || tourSteps.length === 0) {
+        console.warn(`No steps found for tour: ${tourId}`);
+        return;
+      }
+
+      setTotalSteps(tourSteps.length);
+      setActiveTourId(tourId);
+
+      const tour = new Shepherd.Tour({
+        useModalOverlay: true,
+        defaultStepOptions: {
+          classes: "shepherd-theme-custom",
+          scrollTo: { behavior: "smooth", block: "center" },
+          cancelIcon: { enabled: false },
+        },
+      });
+
+      // Set up tour event listeners
+      tour.on("show", () => setIsTourActive(true));
+      tour.on("cancel", () => {
+        cleanupRoots();
+        setIsTourActive(false);
+        setActiveTourId(null);
+        setCurrentStepIndex(0);
+        setTotalSteps(0);
+        tourRef.current = null;
+      });
+      tour.on("complete", () => {
+        cleanupRoots();
+        setIsTourActive(false);
+        setActiveTourId(null);
+        setCurrentStepIndex(0);
+        setTotalSteps(0);
+        tourRef.current = null;
+      });
+
+      tourSteps.forEach((stepConfig, index) => {
+        const stepId = stepConfig.id || `step-${index}`;
+
+        tour.addStep({
+          id: stepId,
+          attachTo: stepConfig.selector ? { element: stepConfig.selector, on: stepConfig.side || "bottom" } : undefined,
+          arrow: true,
+          // Use text callback to return DOM element with React content
+          text: () => {
+            const container = document.createElement("div");
+            const root = createRoot(container);
+            rootsRef.current.set(stepId, root);
+
+            const cardProps = {
+              step: stepConfig,
+              currentIndex: index,
+              totalSteps: tourSteps!.length,
+              labels,
+              onNext: () => tour.next(),
+              onPrevious: () => tour.back(),
+              onClose: () => tour.cancel(),
+              onSkip: () => tour.cancel(),
+              isFirst: index === 0,
+              isLast: index === tourSteps!.length - 1,
+            };
+
+            root.render(renderCard ? renderCard(cardProps) : <OnboardingCard {...cardProps} />);
+
+            return container;
+          },
+          buttons: [], // Empty - our card handles navigation
+          beforeShowPromise: stepConfig.showDelay
+            ? () => new Promise((resolve) => setTimeout(resolve, stepConfig.showDelay))
+            : undefined,
+          canClickTarget: stepConfig.canClickTarget ?? false,
+          modalOverlayOpeningPadding: 8,
+          modalOverlayOpeningRadius: 8,
+          when: {
+            show: () => {
+              setCurrentStepIndex(index);
+              stepConfig.onShow?.();
+            },
+            hide: () => {
+              stepConfig.onHide?.();
+            },
+          },
+        });
+      });
+
+      tourRef.current = tour;
+      tour.start();
+    },
+    [tours, labels, renderCard, closeTour, cleanupRoots],
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (tourRef.current) {
+        tourRef.current.cancel();
+      }
+      cleanupRoots();
+    };
+  }, [cleanupRoots]);
+
+  const value: OnboardingContextValue = {
+    startTour,
+    closeTour,
+    nextStep,
+    previousStep,
+    goToStep,
+    isTourActive,
+    activeTourId,
+    currentStepIndex,
+    totalSteps,
+  };
+
+  return <OnboardingContext.Provider value={value}>{children}</OnboardingContext.Provider>;
+}
+
+export function useOnboarding(): OnboardingContextValue {
+  const context = useContext(OnboardingContext);
+  if (!context) {
+    throw new Error("useOnboarding must be used within an OnboardingProvider");
+  }
+  return context;
+}

package/src/features/onboarding/contexts/index.ts

@@ -0,0 +1,2 @@
+export * from "./OnboardingContext";
+export * from "../interfaces";

package/src/features/onboarding/index.ts

@@ -0,0 +1,3 @@
+export * from "./interfaces";
+export * from "./contexts";
+export * from "./components";

package/src/features/onboarding/interfaces/index.ts

@@ -0,0 +1 @@
+export * from "./onboarding.interface";

package/src/features/onboarding/interfaces/onboarding.interface.ts

@@ -0,0 +1,93 @@
+import { ReactNode } from "react";
+
+export type OnboardingStepSide =
+  | "top"
+  | "top-start"
+  | "top-end"
+  | "bottom"
+  | "bottom-start"
+  | "bottom-end"
+  | "left"
+  | "left-start"
+  | "left-end"
+  | "right"
+  | "right-start"
+  | "right-end";
+
+export interface OnboardingStepConfig {
+  id: string;
+  title: string;
+  content: ReactNode;
+  selector?: string;
+  side?: OnboardingStepSide;
+  onShow?: () => void;
+  onHide?: () => void;
+  action?: { label: string; onClick: () => void };
+  showDelay?: number;
+  canClickTarget?: boolean;
+  className?: string;
+}
+
+export interface OnboardingTourConfig {
+  id: string;
+  name: string;
+  description?: string;
+  steps: OnboardingStepConfig[];
+  routes?: string[];
+}
+
+export interface OnboardingTourPaths {
+  [routePattern: string]: string;
+}
+
+export interface OnboardingLabels {
+  next: string;
+  previous: string;
+  finish: string;
+  skip: string;
+  close: string;
+  stepCounter: (current: number, total: number) => string;
+}
+
+export const DEFAULT_ONBOARDING_LABELS: OnboardingLabels = {
+  next: "Next",
+  previous: "Previous",
+  finish: "Finish",
+  skip: "Skip",
+  close: "Close",
+  stepCounter: (current, total) => `${current} of ${total}`,
+};
+
+export interface OnboardingContextValue {
+  startTour: (tourId: string, steps?: OnboardingStepConfig[]) => void;
+  closeTour: () => void;
+  nextStep: () => void;
+  previousStep: () => void;
+  goToStep: (index: number) => void;
+  isTourActive: boolean;
+  activeTourId: string | null;
+  currentStepIndex: number;
+  totalSteps: number;
+}
+
+export interface OnboardingProviderProps {
+  children: React.ReactNode;
+  tours?: OnboardingTourConfig[];
+  tourPaths?: OnboardingTourPaths;
+  labels?: OnboardingLabels;
+  renderCard?: (props: OnboardingCardRenderProps) => ReactNode;
+  zIndex?: number;
+}
+
+export interface OnboardingCardRenderProps {
+  step: OnboardingStepConfig;
+  currentIndex: number;
+  totalSteps: number;
+  labels: OnboardingLabels;
+  onNext: () => void;
+  onPrevious: () => void;
+  onClose: () => void;
+  onSkip: () => void;
+  isFirst: boolean;
+  isLast: boolean;
+}

package/src/features/onboarding/styles/onboarding.css

@@ -0,0 +1,38 @@
+/* Shepherd Modal Overlay */
+.shepherd-modal-overlay-container.shepherd-modal-is-visible {
+  opacity: 1 !important;
+}
+
+.shepherd-modal-overlay-container path {
+  fill: rgba(0, 0, 0, 0.75) !important;
+}
+
+/* Remove default shepherd styling - we use custom React card */
+.shepherd-element {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 0 !important;
+  max-width: none !important;
+}
+
+.shepherd-content,
+.shepherd-text {
+  padding: 0 !important;
+}
+
+/* Arrow styling to match card background */
+.shepherd-arrow::before {
+  background: hsl(var(--card)) !important;
+}
+
+/* Hide default Shepherd header and footer - we render custom ones */
+.shepherd-header,
+.shepherd-footer {
+  display: none !important;
+}
+
+/* Dark mode support */
+.dark .shepherd-arrow::before {
+  background: hsl(var(--card)) !important;
+}

package/src/features/user/contexts/CurrentUserContext.tsx

@@ -33,7 +33,7 @@ export interface CurrentUserContextType<T extends UserInterface = UserInterface>
   hasAccesToFeature: (featureIdentifier: string) => boolean;
   matchUrlToModule: (prarms?: { path: string }) => ModuleWithPermissions | undefined;
   hasRole: (roleId: string) => boolean;
-  refreshUser: () => Promise<void>;
+  refreshUser: (options?: { skipCookieUpdate?: boolean }) => Promise<void>;
   isRefreshing: boolean;
 }
 
@@ -136,27 +136,36 @@ export const CurrentUserProvider = ({ children }: { children: React.ReactNode })
   const [isRefreshing, setIsRefreshing] = useState(false);
 
   // Function to refresh user data from the API
-  const refreshUser = useCallback(async (): Promise<void> => {
-    if (isRefreshing) return;
+  // skipCookieUpdate: When true, only updates React state without calling the Server Action
+  // This prevents page reloads when refresh is triggered by WebSocket events
+  const refreshUser = useCallback(async (options?: { skipCookieUpdate?: boolean }): Promise<void> => {
+    if (isRefreshing) {
+      return;
+    }
 
     setIsRefreshing(true);
     try {
       const fullUser = await UserService.findFullUser();
       if (fullUser) {
-        setDehydratedUser(fullUser.dehydrate() as any);
+        const dehydrated = fullUser.dehydrate();
+
+        setDehydratedUser(dehydrated as any);
         setUser(fullUser);
 
         // Update authentication cookies with fresh user data
-        await getTokenHandler()?.updateToken({
-          userId: fullUser.id,
-          companyId: fullUser.company?.id,
-          roles: fullUser.roles.map((role) => role.id),
-          features: fullUser.company?.features?.map((feature) => feature.id) ?? [],
-          modules: fullUser.modules.map((module) => ({
-            id: module.id,
-            permissions: module.permissions,
-          })),
-        });
+        // Skip when triggered by WebSocket to prevent page reload (Server Actions modify cookies)
+        if (!options?.skipCookieUpdate) {
+          await getTokenHandler()?.updateToken({
+            userId: fullUser.id,
+            companyId: fullUser.company?.id,
+            roles: fullUser.roles.map((role) => role.id),
+            features: fullUser.company?.features?.map((feature) => feature.id) ?? [],
+            modules: fullUser.modules.map((module) => ({
+              id: module.id,
+              permissions: module.permissions,
+            })),
+          });
+        }
       }
     } catch (error) {
       console.error("Failed to refresh user data:", error);
@@ -175,23 +184,29 @@ export const CurrentUserProvider = ({ children }: { children: React.ReactNode })
   // Track refresh in progress to prevent duplicate API calls
   const isRefreshingRef = useRef(false);
 
-  // Listen for company:tokens_updated WebSocket events
+  // Listen for company WebSocket events that trigger user refresh
   useEffect(() => {
-    if (!socket || !isConnected || !currentUser?.company?.id) return;
+    if (!socket || !isConnected || !currentUser?.company?.id) {
+      return;
+    }
 
-    const handleTokensUpdated = (data: { companyId: string; type: string }) => {
+    const handleCompanyUpdate = (data: { companyId: string; type: string }) => {
       if (data.companyId === currentUser.company?.id && !isRefreshingRef.current) {
         isRefreshingRef.current = true;
-        refreshUserRef.current().finally(() => {
+        // Skip cookie update to prevent page reload - only update React state
+        refreshUserRef.current({ skipCookieUpdate: true }).finally(() => {
           isRefreshingRef.current = false;
         });
       }
     };
 
-    socket.on("company:tokens_updated", handleTokensUpdated);
+    // Both events trigger the same refresh behavior
+    socket.on("company:tokens_updated", handleCompanyUpdate);
+    socket.on("company:subscription_updated", handleCompanyUpdate);
 
     return () => {
-      socket.off("company:tokens_updated", handleTokensUpdated);
+      socket.off("company:tokens_updated", handleCompanyUpdate);
+      socket.off("company:subscription_updated", handleCompanyUpdate);
     };
   }, [socket, isConnected, currentUser?.company?.id]);
 

package/src/shadcnui/ui/card.tsx

@@ -1,20 +1,19 @@
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/utils"
+import { cn } from "@/lib/utils";
 
-function Card({
-  className,
-  size = "default",
-  ...props
-}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+function Card({ className, size = "default", ...props }: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
   return (
     <div
       data-slot="card"
       data-size={size}
-      className={cn("ring-foreground/10 bg-card text-card-foreground gap-4 overflow-hidden rounded-lg py-4 text-xs/relaxed ring-1 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 *:[img:first-child]:rounded-t-lg *:[img:last-child]:rounded-b-lg group/card flex flex-col", className)}
+      className={cn(
+        "ring-foreground/10 bg-card text-card-foreground gap-4 overflow-clip rounded-lg py-4 text-xs/relaxed ring-1 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 *:[img:first-child]:rounded-t-lg *:[img:last-child]:rounded-b-lg group/card flex flex-col",
+        className,
+      )}
       {...props}
     />
-  )
+  );
 }
 
 function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
@@ -23,72 +22,48 @@ function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
       data-slot="card-header"
       className={cn(
         "gap-1 rounded-t-lg px-4 group-data-[size=sm]/card:px-3 [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3 group/card-header @container/card-header grid auto-rows-min items-start has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto]",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      data-slot="card-title"
-      className={cn("text-sm font-medium", className)}
-      {...props}
-    />
-  )
+  return <div data-slot="card-title" className={cn("text-sm font-medium", className)} {...props} />;
 }
 
 function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
   return (
-    <div
-      data-slot="card-description"
-      className={cn("text-muted-foreground text-xs/relaxed", className)}
-      {...props}
-    />
-  )
+    <div data-slot="card-description" className={cn("text-muted-foreground text-xs/relaxed", className)} {...props} />
+  );
 }
 
 function CardAction({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-action"
-      className={cn(
-        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
-        className
-      )}
+      className={cn("col-start-2 row-span-2 row-start-1 self-start justify-self-end", className)}
       {...props}
     />
-  )
+  );
 }
 
 function CardContent({ className, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      data-slot="card-content"
-      className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
-      {...props}
-    />
-  )
+  return <div data-slot="card-content" className={cn("px-4 group-data-[size=sm]/card:px-3", className)} {...props} />;
 }
 
 function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="card-footer"
-      className={cn("rounded-b-lg px-4 group-data-[size=sm]/card:px-3 [.border-t]:pt-4 group-data-[size=sm]/card:[.border-t]:pt-3 flex items-center", className)}
+      className={cn(
+        "rounded-b-lg px-4 group-data-[size=sm]/card:px-3 [.border-t]:pt-4 group-data-[size=sm]/card:[.border-t]:pt-3 flex items-center",
+        className,
+      )}
       {...props}
     />
-  )
+  );
 }
 
-export {
-  Card,
-  CardHeader,
-  CardFooter,
-  CardTitle,
-  CardAction,
-  CardDescription,
-  CardContent,
-}
+export { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle };