hope-events/frontend/src/hooks/useHelpGuide.ts

"use client";

import { useEffect, useState } from "react";

/**
 * Open/close state for a help guide, with per-page "don't show again"
 * persistence. `storageKey` should be a stable slug identifying the guide's
 * content (e.g. "reports", "dashboard-user", "general") — each slug gets an
 * independent dismissal flag, so dismissing one page's guide doesn't
 * suppress another's.
 */
export function useHelpGuide(storageKey: string) {
  const [open, setOpen] = useState(false);
  const dismissedKey = `hope_events_help_dismissed_${storageKey}`;

  // Show automatically on first visit to this guide, unless dismissed for good.
  useEffect(() => {
    try {
      if (typeof window !== "undefined" && window.localStorage.getItem(dismissedKey) !== "1") {
        setOpen(true);
      }
    } catch {
      // localStorage unavailable (private browsing, etc.) — just don't auto-show.
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [dismissedKey]);

  const openGuide = () => setOpen(true);

  const closeGuide = (dontShowAgain: boolean) => {
    setOpen(false);
    if (dontShowAgain) {
      try {
        window.localStorage.setItem(dismissedKey, "1");
      } catch {
        // ignore
      }
    }
  };

  return { open, openGuide, closeGuide };
}