@elogroup-sereduc/portal-aluno-tour 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# Portal Aluno Tour
+
+Componente de tour guiado customizado usando HeroUI para o Portal do Aluno.
+
+## Instalação
+
+```bash
+npm install @elogroup-sereduc/portal-aluno-tour
+```
+
+## Uso
+
+```tsx
+import { Tour } from "@elogroup-sereduc/portal-aluno-tour";
+import { useState } from "react";
+
+function MyComponent() {
+  const [tourEnabled, setTourEnabled] = useState(false);
+
+  const steps = [
+    {
+      element: ".my-element",
+      intro: "Este é o primeiro passo do tour",
+      position: "bottom",
+    },
+    {
+      element: ".another-element",
+      intro: "Este é o segundo passo",
+      position: "right",
+    },
+  ];
+
+  return (
+    <>
+      <button onClick={() => setTourEnabled(true)}>Iniciar Tour</button>
+      <Tour
+        enabled={tourEnabled}
+        steps={steps}
+        onExit={() => setTourEnabled(false)}
+        options={{
+          nextLabel: "Próximo",
+          prevLabel: "Anterior",
+          skipLabel: "Pular",
+          doneLabel: "Concluir",
+        }}
+      />
+    </>
+  );
+}
+```
+
+## Props
+
+### TourProps
+
+- `enabled: boolean` - Se o tour está ativo
+- `steps: TourStep[]` - Array de passos do tour
+- `initialStep?: number` - Passo inicial (padrão: 0)
+- `options?: TourOptions` - Opções de configuração
+- `onExit?: () => void` - Callback quando o tour é encerrado
+- `onComplete?: () => void` - Callback quando o tour é concluído
+
+### TourStep
+
+- `element: string` - Seletor CSS do elemento
+- `intro: string` - Texto explicativo
+- `position?: "top" | "bottom" | "left" | "right"` - Posição da tooltip
+- `title?: string` - Título do passo (opcional)
+
+### TourOptions
+
+- `nextLabel?: string` - Label do botão "Próximo"
+- `prevLabel?: string` - Label do botão "Anterior"
+- `skipLabel?: string` - Label do botão "Pular"
+- `doneLabel?: string` - Label do botão "Concluir"
+- `showProgress?: boolean` - Mostrar barra de progresso
+- `showBullets?: boolean` - Mostrar bullets de navegação
+- `exitOnOverlayClick?: boolean` - Permitir fechar clicando no overlay
+- `exitOnEsc?: boolean` - Permitir fechar com ESC
+

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@elogroup-sereduc/portal-aluno-tour",
+  "version": "1.0.0",
+  "description": "Componente de tour guiado customizado usando HeroUI para o Portal do Aluno",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "@heroui/button": "^2.0.0",
+    "@heroui/system": "^2.0.0",
+    "react-icons": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "tour",
+    "onboarding",
+    "heroui",
+    "react"
+  ],
+  "author": "Leandro Passos - Elogroup",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/components/Tour.tsx

@@ -0,0 +1,349 @@
+import { useEffect, useState, useCallback, useRef } from "react";
+import { Button } from "@heroui/button";
+import { TourProps, TourStep } from "../types";
+import { HiX, HiChevronLeft, HiChevronRight } from "react-icons/hi2";
+
+/**
+ * Componente de tour guiado customizado usando HeroUI
+ */
+export function Tour({
+  enabled,
+  steps,
+  initialStep = 0,
+  options = {},
+  onExit,
+  onComplete,
+}: TourProps) {
+  const [currentStep, setCurrentStep] = useState(initialStep);
+  const [highlightedElement, setHighlightedElement] = useState<HTMLElement | null>(null);
+  const [tooltipPosition, setTooltipPosition] = useState<{ top: number; left: number } | null>(null);
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+
+  const {
+    nextLabel = "Próximo",
+    prevLabel = "Anterior",
+    skipLabel = "Pular",
+    doneLabel = "Concluir",
+    showProgress = true,
+    showBullets = true,
+    exitOnOverlayClick = false,
+    exitOnEsc = true,
+  } = options;
+
+  // Calcula a posição da tooltip baseado no elemento destacado
+  const calculateTooltipPosition = useCallback((element: HTMLElement, position: string = "bottom") => {
+    const rect = element.getBoundingClientRect();
+    const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+    const scrollLeft = window.pageXOffset || document.documentElement.scrollLeft;
+
+    let top = 0;
+    let left = 0;
+
+    switch (position) {
+      case "top":
+        top = rect.top + scrollTop - 10;
+        left = rect.left + scrollLeft + rect.width / 2;
+        break;
+      case "bottom":
+        top = rect.bottom + scrollTop + 10;
+        left = rect.left + scrollLeft + rect.width / 2;
+        break;
+      case "left":
+        top = rect.top + scrollTop + rect.height / 2;
+        left = rect.left + scrollLeft - 10;
+        break;
+      case "right":
+        top = rect.top + scrollTop + rect.height / 2;
+        left = rect.right + scrollLeft + 10;
+        break;
+      default:
+        top = rect.bottom + scrollTop + 10;
+        left = rect.left + scrollLeft + rect.width / 2;
+    }
+
+    return { top, left };
+  }, []);
+
+  // Destaca o elemento atual
+  useEffect(() => {
+    if (!enabled || currentStep < 0 || currentStep >= steps.length) {
+      setHighlightedElement(null);
+      setTooltipPosition(null);
+      return;
+    }
+
+    const step = steps[currentStep];
+    const element = document.querySelector(step.element) as HTMLElement;
+
+    if (!element) {
+      console.warn(`Elemento não encontrado: ${step.element}`);
+      return;
+    }
+
+    setHighlightedElement(element);
+
+    // Scroll para o elemento
+    element.scrollIntoView({ behavior: "smooth", block: "center" });
+
+    // Calcula posição da tooltip após um pequeno delay para garantir que o scroll terminou
+    setTimeout(() => {
+      const position = calculateTooltipPosition(element, step.position);
+      setTooltipPosition(position);
+    }, 300);
+  }, [enabled, currentStep, steps, calculateTooltipPosition]);
+
+  // Adiciona overlay e highlight ao elemento
+  useEffect(() => {
+    if (!highlightedElement) {
+      // Remove highlights anteriores
+      document.querySelectorAll(".tour-highlight").forEach((el) => {
+        el.classList.remove("tour-highlight");
+      });
+      return;
+    }
+
+    // Adiciona classe de highlight
+    highlightedElement.classList.add("tour-highlight");
+
+    return () => {
+      highlightedElement.classList.remove("tour-highlight");
+    };
+  }, [highlightedElement]);
+
+  // Handler de teclado (ESC)
+  useEffect(() => {
+    if (!enabled || !exitOnEsc) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        handleExit();
+      } else if (e.key === "ArrowRight") {
+        handleNext();
+      } else if (e.key === "ArrowLeft") {
+        handlePrev();
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [enabled, exitOnEsc, currentStep, steps.length]);
+
+  const handleNext = useCallback(() => {
+    if (currentStep < steps.length - 1) {
+      setCurrentStep(currentStep + 1);
+    } else {
+      handleComplete();
+    }
+  }, [currentStep, steps.length]);
+
+  const handlePrev = useCallback(() => {
+    if (currentStep > 0) {
+      setCurrentStep(currentStep - 1);
+    }
+  }, [currentStep]);
+
+  const handleSkip = useCallback(() => {
+    handleExit();
+  }, []);
+
+  const handleComplete = useCallback(() => {
+    onComplete?.();
+    handleExit();
+  }, [onComplete]);
+
+  const handleExit = useCallback(() => {
+    setCurrentStep(initialStep);
+    setHighlightedElement(null);
+    setTooltipPosition(null);
+    onExit?.();
+  }, [initialStep, onExit]);
+
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (exitOnOverlayClick && e.target === overlayRef.current) {
+        handleExit();
+      }
+    },
+    [exitOnOverlayClick, handleExit]
+  );
+
+  if (!enabled) {
+    return null;
+  }
+
+  const currentStepData = steps[currentStep];
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === steps.length - 1;
+  const progress = ((currentStep + 1) / steps.length) * 100;
+
+  return (
+    <>
+      {/* Overlay escuro */}
+      <div
+        ref={overlayRef}
+        className="fixed inset-0 bg-black/60 z-[9998]"
+        onClick={handleOverlayClick}
+        style={{ pointerEvents: exitOnOverlayClick ? "auto" : "none" }}
+      />
+
+      {/* Tooltip */}
+      {tooltipPosition && currentStepData && highlightedElement && (
+        <div
+          ref={tooltipRef}
+          className="fixed z-[9999] max-w-sm"
+          style={{
+            top: currentStepData.position === "bottom" ? `${tooltipPosition.top}px` : undefined,
+            bottom: currentStepData.position === "top" ? `${window.innerHeight - tooltipPosition.top}px` : undefined,
+            left: currentStepData.position === "left" || currentStepData.position === "right" 
+              ? `${tooltipPosition.left}px` 
+              : `${tooltipPosition.left}px`,
+            transform: currentStepData.position === "left" || currentStepData.position === "right"
+              ? "translate(0, -50%)"
+              : "translate(-50%, 0)",
+          }}
+        >
+          <div className="bg-white rounded-lg shadow-xl p-6 relative">
+            {/* Botão fechar */}
+            <button
+              onClick={handleExit}
+              className="absolute top-2 right-2 p-1 rounded-full hover:bg-gray-100 transition-colors"
+              aria-label="Fechar tour"
+            >
+              <HiX className="w-5 h-5 text-gray-500" />
+            </button>
+
+            {/* Título (se fornecido) */}
+            {currentStepData.title && (
+              <h3 className="text-lg font-semibold text-gray-900 mb-2 pr-6">
+                {currentStepData.title}
+              </h3>
+            )}
+
+            {/* Conteúdo */}
+            <p className="text-gray-700 mb-4">{currentStepData.intro}</p>
+
+            {/* Progresso */}
+            {showProgress && (
+              <div className="mb-4">
+                <div className="w-full bg-gray-200 rounded-full h-2">
+                  <div
+                    className="bg-brand-primary h-2 rounded-full transition-all duration-300"
+                    style={{ width: `${progress}%` }}
+                  />
+                </div>
+                <p className="text-xs text-gray-500 mt-1 text-center">
+                  {currentStep + 1} de {steps.length}
+                </p>
+              </div>
+            )}
+
+            {/* Bullets */}
+            {showBullets && (
+              <div className="flex justify-center gap-1 mb-4">
+                {steps.map((_, index) => (
+                  <button
+                    key={index}
+                    onClick={() => setCurrentStep(index)}
+                    className={`w-2 h-2 rounded-full transition-all ${
+                      index === currentStep
+                        ? "bg-brand-primary w-6"
+                        : "bg-gray-300 hover:bg-gray-400"
+                    }`}
+                    aria-label={`Ir para passo ${index + 1}`}
+                  />
+                ))}
+              </div>
+            )}
+
+            {/* Botões de navegação */}
+            <div className="flex justify-between items-center gap-2">
+              <div className="flex gap-2">
+                {!isFirstStep && (
+                  <Button
+                    variant="bordered"
+                    onPress={handlePrev}
+                    startContent={<HiChevronLeft className="w-4 h-4" />}
+                  >
+                    {prevLabel}
+                  </Button>
+                )}
+              </div>
+
+              <div className="flex gap-2">
+                <Button variant="light" onPress={handleSkip}>
+                  {skipLabel}
+                </Button>
+                <Button
+                  color="primary"
+                  onPress={isLastStep ? handleComplete : handleNext}
+                  endContent={!isLastStep ? <HiChevronRight className="w-4 h-4" /> : undefined}
+                >
+                  {isLastStep ? doneLabel : nextLabel}
+                </Button>
+              </div>
+            </div>
+          </div>
+
+          {/* Seta indicadora */}
+          {currentStepData.position === "bottom" && (
+            <div
+              className="absolute w-0 h-0 border-8 border-transparent"
+              style={{
+                top: "-16px",
+                left: "50%",
+                transform: "translateX(-50%)",
+                borderColor: "transparent transparent white transparent",
+              }}
+            />
+          )}
+          {currentStepData.position === "top" && (
+            <div
+              className="absolute w-0 h-0 border-8 border-transparent"
+              style={{
+                bottom: "-16px",
+                left: "50%",
+                transform: "translateX(-50%)",
+                borderColor: "white transparent transparent transparent",
+              }}
+            />
+          )}
+          {currentStepData.position === "right" && (
+            <div
+              className="absolute w-0 h-0 border-8 border-transparent"
+              style={{
+                left: "-16px",
+                top: "50%",
+                transform: "translateY(-50%)",
+                borderColor: "transparent white transparent transparent",
+              }}
+            />
+          )}
+          {currentStepData.position === "left" && (
+            <div
+              className="absolute w-0 h-0 border-8 border-transparent"
+              style={{
+                right: "-16px",
+                top: "50%",
+                transform: "translateY(-50%)",
+                borderColor: "transparent transparent transparent white",
+              }}
+            />
+          )}
+        </div>
+      )}
+
+      {/* Estilos inline para highlight */}
+      <style>{`
+        .tour-highlight {
+          position: relative;
+          z-index: 9999 !important;
+          outline: 3px solid var(--brand-primary, #0056b0) !important;
+          outline-offset: 2px;
+          border-radius: 4px;
+        }
+      `}</style>
+    </>
+  );
+}
+

package/src/index.ts

@@ -0,0 +1,3 @@
+export { Tour } from "./components/Tour";
+export type { TourProps, TourStep, TourOptions } from "./types";
+

package/src/types/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Tipos para o componente de tour
+ */
+
+export interface TourStep {
+  /**
+   * Seletor CSS do elemento a ser destacado
+   */
+  element: string;
+
+  /**
+   * Texto explicativo do passo
+   */
+  intro: string;
+
+  /**
+   * Posição da tooltip em relação ao elemento
+   * @default "bottom"
+   */
+  position?: "top" | "bottom" | "left" | "right";
+
+  /**
+   * Título do passo (opcional)
+   */
+  title?: string;
+}
+
+export interface TourOptions {
+  /**
+   * Label do botão "Próximo"
+   * @default "Próximo"
+   */
+  nextLabel?: string;
+
+  /**
+   * Label do botão "Anterior"
+   * @default "Anterior"
+   */
+  prevLabel?: string;
+
+  /**
+   * Label do botão "Pular"
+   * @default "Pular"
+   */
+  skipLabel?: string;
+
+  /**
+   * Label do botão "Concluir"
+   * @default "Concluir"
+   */
+  doneLabel?: string;
+
+  /**
+   * Mostrar barra de progresso
+   * @default true
+   */
+  showProgress?: boolean;
+
+  /**
+   * Mostrar bullets de navegação
+   * @default true
+   */
+  showBullets?: boolean;
+
+  /**
+   * Permitir fechar clicando no overlay
+   * @default false
+   */
+  exitOnOverlayClick?: boolean;
+
+  /**
+   * Permitir fechar com ESC
+   * @default true
+   */
+  exitOnEsc?: boolean;
+}
+
+export interface TourProps {
+  /**
+   * Se o tour está habilitado/ativo
+   */
+  enabled: boolean;
+
+  /**
+   * Array de passos do tour
+   */
+  steps: TourStep[];
+
+  /**
+   * Passo inicial (índice)
+   * @default 0
+   */
+  initialStep?: number;
+
+  /**
+   * Opções de configuração do tour
+   */
+  options?: TourOptions;
+
+  /**
+   * Callback quando o tour é encerrado
+   */
+  onExit?: () => void;
+
+  /**
+   * Callback quando o tour é concluído
+   */
+  onComplete?: () => void;
+}
+

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+