rl-core-front 0.15.6 → 0.16.1

package/src/contexts/jobs-context.tsx

@@ -0,0 +1,146 @@
+"use client";
+
+import type { JSX, ReactNode } from "react";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+
+import { api } from "#core/_services/api/axios.factory";
+import { JobDock } from "#core/components/job-dock";
+import {
+  JobCompletedData,
+  JobFailedData,
+  JobHandle,
+  JobProgressData,
+  JobsStore,
+  TrackedJob,
+} from "#core/contexts/jobs-store";
+import { useSocket } from "#core/contexts/socket-context";
+
+/** Eventos que a fila do backend empurra (ver `queue.constants.ts` do core). */
+const JOB_PROGRESS_EVENT = "job:progress";
+const JOB_COMPLETED_EVENT = "job:completed";
+const JOB_FAILED_EVENT = "job:failed";
+
+/** `GET /jobs/:id` — a mesma informação, para quem perdeu os eventos. */
+interface JobStatusResponse<TSummary> {
+  id: string;
+  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown";
+  progress: { percent: number; message?: string } | null;
+  summary: TSummary | null;
+  error: { code: string | null; message: string } | null;
+}
+
+export interface JobsContextType {
+  jobs: TrackedJob[];
+  start: <TSummary>(label: string) => JobHandle<TSummary>;
+  dismiss: (localId: string) => void;
+}
+
+const JobsContext = createContext<JobsContextType | undefined>(undefined);
+
+/**
+ * Os trabalhos em segundo plano que esta aba está acompanhando.
+ *
+ * Vive **no provider**, e não na tela — é isso que mantém o acompanhamento
+ * quando a pessoa navega para outra rota no meio de um upload. O painel
+ * (`JobDock`) é renderizado aqui pelo mesmo motivo.
+ *
+ * A regra mora na `JobsStore`, fora do React; aqui ficam só as três ligações
+ * com o mundo: os eventos do socket, a reconciliação por HTTP quando a conexão
+ * volta, e a leitura do estado pela tela.
+ */
+export function JobsProvider({ children }: { children: ReactNode }): JSX.Element {
+  const { on, status, reconnectCount } = useSocket();
+  // Instância estável pelo inicializador do `useState`, e não por um ref: ler
+  // `ref.current` durante o render é justamente o que as regras do React 19
+  // proíbem — e aqui a store precisa existir já no primeiro render, porque o
+  // `useSyncExternalStore` a assina.
+  const [store] = useState(() => new JobsStore());
+
+  const jobs = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    // O servidor renderiza sem job nenhum: a lista só existe nesta aba.
+    store.getSnapshot,
+  );
+
+  useEffect(() => {
+    store.setOffline(status !== "connected");
+  }, [status, store]);
+
+  useEffect(() => {
+    const offProgress = on<JobProgressData>(JOB_PROGRESS_EVENT, store.onProgress);
+    const offCompleted = on<JobCompletedData>(
+      JOB_COMPLETED_EVENT,
+      store.onCompleted,
+    );
+    const offFailed = on<JobFailedData>(JOB_FAILED_EVENT, store.onFailed);
+
+    return () => {
+      offProgress();
+      offCompleted();
+      offFailed();
+    };
+  }, [on, store]);
+
+  /**
+   * Reconciliação a cada reconexão.
+   *
+   * O que passou enquanto o socket esteve fora não volta sozinho — e é
+   * justamente aí que está o job que terminou sem ninguém ver.
+   */
+  useEffect(() => {
+    if (reconnectCount === 0) {
+      return;
+    }
+
+    for (const jobId of store.pendingJobIds()) {
+      void api
+        .get<JobStatusResponse<unknown>>(`/jobs/${jobId}`)
+        .then(({ data }) =>
+          store.reconcile(
+            jobId,
+            data.state,
+            data.progress?.percent ?? null,
+            data.progress?.message ?? null,
+            data.summary,
+            data.error?.message ?? null,
+          ),
+        )
+        .catch(() => {
+          // Job expirado ou fora de alcance: o socket ainda pode trazer o fim,
+          // e derrubar a sessão por causa da consulta de apoio seria pior.
+        });
+    }
+  }, [reconnectCount, store]);
+
+  useEffect(() => () => store.destroy(), [store]);
+
+  const value = useMemo<JobsContextType>(
+    () => ({ jobs, start: store.start, dismiss: store.dismiss }),
+    [jobs, store],
+  );
+
+  return (
+    <JobsContext.Provider value={value}>
+      {children}
+      <JobDock />
+    </JobsContext.Provider>
+  );
+}
+
+export function useJobs(): JobsContextType {
+  const context = useContext(JobsContext);
+
+  if (!context) {
+    throw new Error("useJobs precisa estar dentro de <JobsProvider>");
+  }
+
+  return context;
+}

package/src/contexts/jobs-store.ts

@@ -0,0 +1,391 @@
+/**
+ * A máquina dos trabalhos em segundo plano, **fora do React**.
+ *
+ * Mora aqui, e não em `useState` dentro do provider, por dois motivos que
+ * andam juntos: o estado é mutável e recebe muitos eventos (progresso chega em
+ * rajada), e ele precisa sobreviver a re-render sem recriar timers nem
+ * promessas. Com a máquina separada, o provider vira uma casca — e esta parte,
+ * que é onde mora a regra, fica testável sem montar componente.
+ *
+ * Desenho portado do `lw-tagvirtual`, onde roda em produção. As guardas que
+ * vieram de lá estão todas aqui: sessão que morre no desfecho, evento sem
+ * sessão guardado para reaplicar, prazos para nada ficar eterno e tolerância
+ * com o socket fora.
+ */
+
+/** Prazo para o job dar o primeiro sinal depois de enfileirado. */
+export const START_TIMEOUT_MS = 30_000;
+/** Prazo entre um sinal e o próximo. */
+export const PROGRESS_TIMEOUT_MS = 45_000;
+/**
+ * Quanto se espera com o socket fora antes de desistir.
+ *
+ * Enquanto o transporte está caído o job **continua correndo** no servidor:
+ * desistir aqui apagaria da vista um trabalho vivo.
+ */
+export const OFFLINE_GRACE_MS = 300_000;
+/** Quanto tempo o job concluído fica visível antes de sair sozinho. */
+export const SUCCESS_LINGER_MS = 1_500;
+/**
+ * Progresso que chega antes de o POST responder não tem sessão para onde ir.
+ * Guardar e reaplicar no bind evita perder o evento de fim de um trabalho
+ * rápido — no upload de imagem, esse é o caso comum.
+ */
+export const MAX_BUFFERED_EVENTS = 50;
+
+export type TrackedJobState = "running" | "completed" | "failed";
+
+/** Um trabalho em andamento, do jeito que o painel o mostra. */
+export interface TrackedJob {
+  /** Id local, que existe desde antes de o servidor responder. */
+  localId: string;
+  jobId: string | null;
+  label: string;
+  state: TrackedJobState;
+  /** Inteiro de 0 a 100. Fica em 0 enquanto o job não reporta etapa. */
+  percent: number;
+  message: string | null;
+  error: string | null;
+}
+
+/** O que quem inicia um trabalho recebe de volta. */
+export interface JobHandle<TSummary = unknown> {
+  localId: string;
+  /** Chamado quando a resposta HTTP traz o `jobId`. */
+  bind: (jobId: string) => void;
+  /** Encerra com resultado — para o trabalho que terminou na própria resposta. */
+  settle: (summary: TSummary) => void;
+  fail: (message: string) => void;
+  /** Resolve no desfecho: é o que o `await` de quem chamou espera. */
+  done: Promise<TSummary>;
+}
+
+export interface JobProgressData {
+  jobId: string;
+  percent: number;
+  message?: string;
+}
+
+export interface JobCompletedData<TSummary = unknown> {
+  jobId: string;
+  summary: TSummary;
+}
+
+export interface JobFailedData {
+  jobId: string;
+  message: string;
+}
+
+/** O controle de uma sessão — nada disto chega à tela. */
+interface Control {
+  resolve: (summary: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Desde quando o socket está fora; zero quando está de pé. */
+  offlineSince: number;
+  finished: boolean;
+}
+
+const MENSAGEM_SEM_RESPOSTA =
+  "Sem resposta do servidor. Recarregue para conferir se terminou";
+
+export class JobsStore {
+  private jobs = new Map<string, TrackedJob>();
+  private controls = new Map<string, Control>();
+  /** `jobId` do servidor → id local. */
+  private index = new Map<string, string>();
+  private buffered = new Map<string, Array<() => void>>();
+  private listeners = new Set<() => void>();
+  private snapshot: TrackedJob[] = [];
+  private offline = false;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => this.listeners.delete(listener);
+  };
+
+  /**
+   * O mesmo array enquanto nada muda.
+   *
+   * `useSyncExternalStore` compara por identidade e entra em laço infinito se
+   * cada leitura devolver um array novo.
+   */
+  getSnapshot = (): TrackedJob[] => this.snapshot;
+
+  /** Registra uma sessão. O `jobId` chega depois, no `bind`. */
+  start = <TSummary,>(label: string): JobHandle<TSummary> => {
+    const localId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let resolve: (summary: TSummary) => void = () => undefined;
+    let reject: (error: Error) => void = () => undefined;
+
+    const done = new Promise<TSummary>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    this.jobs.set(localId, {
+      localId,
+      jobId: null,
+      label,
+      state: "running",
+      percent: 0,
+      message: null,
+      error: null,
+    });
+    this.controls.set(localId, {
+      resolve: resolve as (summary: unknown) => void,
+      reject,
+      timer: null,
+      offlineSince: this.offline ? Date.now() : 0,
+      finished: false,
+    });
+
+    this.arm(localId, START_TIMEOUT_MS);
+    this.publish();
+
+    return {
+      localId,
+      done,
+      bind: (jobId: string) => this.bind(localId, jobId),
+      settle: (summary: TSummary) => this.settle(localId, summary),
+      fail: (message: string) => this.fail(localId, message),
+    };
+  };
+
+  /** Tira da tela um job que o usuário fechou. */
+  dismiss = (localId: string): void => {
+    this.forget(localId);
+    this.publish();
+  };
+
+  onProgress = (data: JobProgressData): void => {
+    this.withSession(data.jobId, (localId) => {
+      this.patch(localId, {
+        state: "running",
+        percent: data.percent,
+        message: data.message ?? null,
+      });
+      this.arm(localId, PROGRESS_TIMEOUT_MS);
+      this.publish();
+    });
+  };
+
+  onCompleted = <TSummary,>(data: JobCompletedData<TSummary>): void => {
+    this.withSession(data.jobId, (localId) => this.settle(localId, data.summary));
+  };
+
+  onFailed = (data: JobFailedData): void => {
+    this.withSession(data.jobId, (localId) => this.fail(localId, data.message));
+  };
+
+  /**
+   * Marca o transporte como fora ou de volta.
+   *
+   * Com o socket fora, o prazo passa a ser o de tolerância: o trabalho segue
+   * do outro lado, e o que se perde é só a notícia dele.
+   */
+  setOffline = (offline: boolean): void => {
+    this.offline = offline;
+
+    for (const control of this.controls.values()) {
+      control.offlineSince = offline ? control.offlineSince || Date.now() : 0;
+    }
+  };
+
+  /** Os jobs que já têm id no servidor — os que a reconciliação consulta. */
+  pendingJobIds = (): string[] =>
+    [...this.jobs.values()]
+      .filter((job) => job.jobId && !this.controls.get(job.localId)?.finished)
+      .map((job) => job.jobId as string);
+
+  /**
+   * Aplica o que o `GET /jobs/:id` respondeu.
+   *
+   * É a rede de segurança do socket: o que passou enquanto a conexão esteve
+   * fora não volta sozinho.
+   */
+  reconcile = <TSummary,>(
+    jobId: string,
+    state: string,
+    percent: number | null,
+    message: string | null,
+    summary: TSummary | null,
+    errorMessage: string | null,
+  ): void => {
+    this.withSession(
+      jobId,
+      (localId) => {
+        if (state === "completed") {
+          this.settle(localId, summary);
+          return;
+        }
+        if (state === "failed") {
+          this.fail(localId, errorMessage ?? "Falha ao processar");
+          return;
+        }
+
+        this.patch(localId, {
+          percent: percent ?? this.jobs.get(localId)?.percent ?? 0,
+          message: message ?? this.jobs.get(localId)?.message ?? null,
+        });
+        this.publish();
+      },
+      // Sem buffer: reconciliação de job que esta aba não acompanha não
+      // interessa a ninguém, e guardá-la seguraria memória sem consumidor.
+      false,
+    );
+  };
+
+  /** Solta timers e sessões — chamado quando o provider desmonta. */
+  destroy = (): void => {
+    this.controls.forEach((control) => this.clearTimer(control));
+    this.controls.clear();
+    this.jobs.clear();
+    this.index.clear();
+    this.buffered.clear();
+    this.publish();
+  };
+
+  private bind(localId: string, jobId: string): void {
+    if (!this.jobs.has(localId)) {
+      return;
+    }
+
+    this.patch(localId, { jobId });
+    this.index.set(jobId, localId);
+    this.arm(localId, PROGRESS_TIMEOUT_MS);
+    this.publish();
+
+    // O que chegou antes de existir sessão vale agora.
+    const buffered = this.buffered.get(jobId);
+    this.buffered.delete(jobId);
+    buffered?.forEach((replay) => replay());
+  }
+
+  private settle(localId: string, summary: unknown): void {
+    const control = this.controls.get(localId);
+
+    if (!control || control.finished) {
+      return;
+    }
+
+    control.finished = true;
+    this.clearTimer(control);
+    this.patch(localId, { state: "completed", percent: 100, error: null });
+    control.resolve(summary);
+    this.publish();
+
+    // Sai da lista por remoção, e não por uma classe que o esconde: painel que
+    // "fica escondido" é exatamente como nasce o painel encalhado.
+    setTimeout(() => {
+      this.forget(localId);
+      this.publish();
+    }, SUCCESS_LINGER_MS).unref?.();
+  }
+
+  private fail(localId: string, message: string): void {
+    const control = this.controls.get(localId);
+
+    if (!control || control.finished) {
+      return;
+    }
+
+    control.finished = true;
+    this.clearTimer(control);
+    this.patch(localId, { state: "failed", error: message });
+    control.reject(new Error(message));
+    // Falha **não** sai sozinha: é a única forma de a pessoa saber o motivo se
+    // já tiver saído da tela que pediu. Sai no `dismiss`.
+    this.publish();
+  }
+
+  /**
+   * Resolve a sessão de um `jobId` e executa a ação.
+   *
+   * Sem sessão, a ação vai para o buffer daquele `jobId` — o caso do evento que
+   * chega antes de o POST responder.
+   */
+  private withSession(
+    jobId: string,
+    action: (localId: string) => void,
+    buffer = true,
+  ): void {
+    const localId = this.index.get(jobId);
+
+    if (localId && this.jobs.has(localId)) {
+      action(localId);
+      return;
+    }
+    if (!buffer) {
+      return;
+    }
+
+    const pendentes = this.buffered.get(jobId) ?? [];
+
+    if (pendentes.length < MAX_BUFFERED_EVENTS) {
+      pendentes.push(() => this.withSession(jobId, action, false));
+      this.buffered.set(jobId, pendentes);
+    }
+  }
+
+  private arm(localId: string, delay: number): void {
+    const control = this.controls.get(localId);
+
+    if (!control) {
+      return;
+    }
+
+    this.clearTimer(control);
+    control.timer = setTimeout(() => {
+      const atual = this.controls.get(localId);
+
+      if (!atual || atual.finished) {
+        return;
+      }
+      // Socket fora não é motivo para desistir: o job segue no servidor.
+      if (atual.offlineSince > 0 && Date.now() - atual.offlineSince < OFFLINE_GRACE_MS) {
+        this.arm(localId, PROGRESS_TIMEOUT_MS);
+        return;
+      }
+
+      this.fail(localId, MENSAGEM_SEM_RESPOSTA);
+    }, delay);
+    control.timer.unref?.();
+  }
+
+  private clearTimer(control: Control): void {
+    if (control.timer) {
+      clearTimeout(control.timer);
+      control.timer = null;
+    }
+  }
+
+  private patch(localId: string, changes: Partial<TrackedJob>): void {
+    const job = this.jobs.get(localId);
+
+    if (job) {
+      this.jobs.set(localId, { ...job, ...changes });
+    }
+  }
+
+  private forget(localId: string): void {
+    const job = this.jobs.get(localId);
+    const control = this.controls.get(localId);
+
+    if (control) {
+      this.clearTimer(control);
+    }
+    if (job?.jobId) {
+      this.index.delete(job.jobId);
+      this.buffered.delete(job.jobId);
+    }
+    this.jobs.delete(localId);
+    this.controls.delete(localId);
+  }
+
+  private publish(): void {
+    this.snapshot = [...this.jobs.values()];
+    this.listeners.forEach((listener) => listener());
+  }
+}

package/src/features/login/hooks/use-login-flow.ts

@@ -49,7 +49,7 @@ export function useLoginFlow(): UseLoginFlowResult {
   const router = useRouter();
   const { notify } = useToast();
   const { t } = useI18n();
-  const { run, loading, error, setError } = useRequest();
+  const { run, loading, error, setError } = useRequest({ silent: true });
   const { refreshProfile } = useAuth();
 
   const [step, setStep] = useState<LoginStep>("credentials");

package/src/features/notifications/components/notification-item.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { AlertTriangle, CheckCircle2, Info, XCircle } from "lucide-react";
+import { AlertTriangle, CheckCircle2, Info, X, XCircle } from "lucide-react";
 import type { JSX } from "react";
 
 import { formatDateTime } from "#core/_utils/format";
@@ -23,26 +23,37 @@ const ICONS: Record<NotificationType, JSX.Element> = {
 export interface NotificationItemProps {
   notification: UserNotification;
   onSelect: (notification: UserNotification) => void;
+  /** Tira esta notificação da caixa. */
+  onDismiss: (id: string) => void;
 }
 
 export function NotificationItem({
   notification,
   onSelect,
+  onDismiss,
 }: NotificationItemProps): JSX.Element {
-  const { locale } = useI18n();
+  const { locale, t } = useI18n();
 
   return (
-    <button
-      type="button"
-      onClick={() => onSelect(notification)}
+    /*
+      O `×` é irmão do botão, e não filho: botão dentro de botão é HTML
+      inválido, e o clique de um dispararia o outro — descartar abriria a rota
+      da notificação no caminho.
+    */
+    <div
       className={cn(
-        "flex w-full gap-3 border-b border-border px-4 py-3 text-left transition-colors hover:bg-accent",
+        "group/notice relative border-b border-border transition-colors hover:bg-accent",
         !notification.read && "bg-accent/40",
       )}
     >
-      <span className="mt-0.5 shrink-0">{ICONS[notification.type]}</span>
+      <button
+        type="button"
+        onClick={() => onSelect(notification)}
+        className="flex w-full gap-3 px-4 py-3 pr-10 text-left"
+      >
+        <span className="mt-0.5 shrink-0">{ICONS[notification.type]}</span>
 
-      <span className="min-w-0 flex-1">
+        <span className="min-w-0 flex-1">
         <span className="flex items-center gap-2">
           <span
             className={cn(
@@ -63,7 +74,20 @@ export function NotificationItem({
         <span className="mt-1 block text-[11px] text-muted-foreground">
           {formatDateTime(notification.createdAt, locale)}
         </span>
-      </span>
-    </button>
+        </span>
+      </button>
+
+      {/* Só no hover: um `×` fixo em cada linha vira ruído numa lista de vinte,
+          e o gesto de descartar não é o que se procura ao abrir o sino. */}
+      <button
+        type="button"
+        onClick={() => onDismiss(notification.id)}
+        aria-label={t("notifications.dismiss")}
+        title={t("notifications.dismiss")}
+        className="absolute right-2 top-3 hidden rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground group-hover/notice:block"
+      >
+        <X className="h-3.5 w-3.5" />
+      </button>
+    </div>
   );
 }

package/src/features/notifications/hooks/use-notifications.ts

@@ -20,6 +20,10 @@ export interface UseNotificationsResult {
   fetch: () => Promise<void>;
   markAsRead: (id: string) => Promise<void>;
   markAllAsRead: () => Promise<void>;
+  /** Tira uma da caixa deste usuário. */
+  dismiss: (id: string) => Promise<void>;
+  /** Limpa as já lidas — o "não deixa acumular". */
+  dismissRead: () => Promise<void>;
 }
 
 export function useNotifications(): UseNotificationsResult {
@@ -74,5 +78,32 @@ export function useNotifications(): UseNotificationsResult {
     await run(() => notificationsService.markAllAsRead());
   }, [run]);
 
-  return { items, unread, loading, fetch, markAsRead, markAllAsRead };
+  /*
+    A lista recarrega em vez de tirar o item na mão: a paginação é do servidor,
+    e remover local deixaria a página com um registro a menos até o próximo
+    fetch — some uma notificação da contagem sem que ela tenha sido descartada.
+  */
+  const dismiss = useCallback(
+    async (id: string): Promise<void> => {
+      await notificationsService.dismiss(id);
+      await fetch();
+    },
+    [fetch],
+  );
+
+  const dismissRead = useCallback(async (): Promise<void> => {
+    await notificationsService.dismissRead();
+    await fetch();
+  }, [fetch]);
+
+  return {
+    items,
+    unread,
+    loading,
+    fetch,
+    markAsRead,
+    markAllAsRead,
+    dismiss,
+    dismissRead,
+  };
 }