rl-core-front 0.16.7 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.16.7",
+  "version": "0.17.0",
   "description": "Telas e componentes Next.js do core: login com 2FA, usuários, RBAC, auditoria, logs e listagens com filtro dinâmico",
   "author": "Rodrigo Liberti",
   "license": "MIT",

package/src/components/breadcrumbs.tsx

@@ -9,6 +9,7 @@ import {
   breadcrumbTrail,
 } from "#core/_utils/breadcrumb-trail";
 import { useI18n } from "#core/contexts";
+import { useDocumentTitle } from "#core/hooks/use-document-title";
 
 /**
  * Rótulo das telas do próprio core — o projeto não precisa cadastrá-las.
@@ -36,6 +37,11 @@ export function Breadcrumbs({ navItems }: BreadcrumbsProps): JSX.Element {
 
   const trail = breadcrumbTrail(pathname, navItems, SEGMENT_LABELS);
 
+  // A aba do navegador acompanha a migalha: o último degrau é a tela, e é o
+  // mesmo nome nos dois lugares — inclusive nas telas do próprio core.
+  const ultimo = trail[trail.length - 1];
+  useDocumentTitle(ultimo ? t(ultimo.label) : null);
+
   return (
     <nav className="mb-4 flex items-center gap-1.5 text-sm text-muted-foreground">
       <button

package/src/components/ui/combobox.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Check, ChevronDown, X } from "lucide-react";
+import { Check, ChevronDown, Plus, X } from "lucide-react";
 import type { JSX } from "react";
 import { useEffect, useId, useMemo, useRef, useState } from "react";
 
@@ -39,8 +39,26 @@ export interface ComboboxProps {
   searchPlaceholder?: string;
   emptyMessage?: string;
   disabled?: boolean;
+  /**
+   * Deixa criar o que foi digitado quando nenhuma opção tem exatamente esse
+   * nome. A linha "Criar" aparece no fim da lista e o Enter a escolhe quando
+   * ela é a apontada. Quem recebe o texto é o `onCreate` — o componente não
+   * sabe se isso vira POST ou só um valor no formulário.
+   */
+  creatable?: boolean;
+  /** Chamado com o texto digitado, já sem espaços nas pontas. */
+  onCreate?: (text: string) => void;
+  /** Texto da linha de criação. Ausente, `Criar "{text}"`. */
+  createLabel?: (text: string) => string;
 }
 
+/** Id da linha de criação na lista apontável — nenhuma opção real o usa. */
+const CREATE_ID = "\u0000create";
+
+/** Id DOM do item, para o `aria-activedescendant`. O caractere nulo não vai para o HTML. */
+const idDoItem = (lista: string, id: string): string =>
+  `${lista}-${id === CREATE_ID ? "create" : id}`;
+
 /**
  * Escolha com busca, de um valor ou de vários.
  *
@@ -52,8 +70,10 @@ export interface ComboboxProps {
  * marcar: a busca, a lista e o painel são os mesmos. Dois componentes seriam o
  * mesmo arquivo duas vezes.
  *
- * Só escolhe — não cria. Quem cadastra o item nem sempre é quem pode cadastrar
- * na origem, e um "criar" aqui daria um botão que falha na cara de quem clicou.
+ * Por padrão só escolhe — não cria. Quem cadastra o item nem sempre é quem
+ * pode cadastrar na origem, e um "criar" aqui daria um botão que falha na
+ * cara de quem clicou. Com `creatable`, a decisão é de quem usa: a lista
+ * ganha a linha "Criar" e o texto sai pelo `onCreate`.
  *
  * **O foco nunca sai do campo de busca.** Quem aponta o item é o `ativo`, e não
  * o foco do navegador: dentro do menu do Radix, foco em item entrega as teclas
@@ -70,6 +90,9 @@ export function Combobox({
   searchPlaceholder,
   emptyMessage,
   disabled,
+  creatable = false,
+  onCreate,
+  createLabel,
 }: ComboboxProps): JSX.Element {
   const { t } = useI18n();
   const [open, setOpen] = useState(false);
@@ -98,7 +121,7 @@ export function Combobox({
   );
 
   const termo = search.trim();
-  const visiveis = useMemo(
+  const filtradas = useMemo(
     () =>
       options.filter((option) =>
         option.name.toLowerCase().includes(termo.toLowerCase()),
@@ -106,6 +129,21 @@ export function Combobox({
     [options, termo],
   );
 
+  /**
+   * A linha "Criar" só quando há texto e nenhuma opção tem exatamente esse
+   * nome — com "Kronos" na lista, digitar "kronos" deve escolher, não criar.
+   */
+  const podeCriar =
+    creatable &&
+    termo !== "" &&
+    !options.some((option) => option.name.toLowerCase() === termo.toLowerCase());
+
+  /** O que se aponta pelo teclado: as opções filtradas e, no fim, a de criar. */
+  const visiveis = useMemo(
+    () => (podeCriar ? [...filtradas, { id: CREATE_ID, name: termo }] : filtradas),
+    [filtradas, podeCriar, termo],
+  );
+
   /** A posição do apontado; sem ele — ou fora da busca — é a do primeiro. */
   const ativo = Math.max(
     visiveis.findIndex((option) => option.id === apontado),
@@ -113,6 +151,15 @@ export function Combobox({
   );
 
   const alternar = (id: string): void => {
+    if (id === CREATE_ID) {
+      onCreate?.(termo);
+      setSearch("");
+      if (!multiple) {
+        setOpen(false);
+      }
+      return;
+    }
+
     if (!multiple) {
       onChange([id]);
       setOpen(false);
@@ -296,7 +343,7 @@ export function Combobox({
             // Quem lê a tela precisa saber qual item as setas apontam: o foco
             // fica aqui, então é este atributo que conta a navegação.
             aria-activedescendant={
-              visiveis[ativo] ? `${idLista}-${visiveis[ativo].id}` : undefined
+              visiveis[ativo] ? idDoItem(idLista, visiveis[ativo].id) : undefined
             }
             onChange={(event) => setSearch(event.target.value)}
             /*
@@ -348,10 +395,10 @@ export function Combobox({
           />
         </div>
 
-        {visiveis.map((option, indice) => (
+        {filtradas.map((option, indice) => (
           <DropdownMenuItem
             key={option.id}
-            id={`${idLista}-${option.id}`}
+            id={idDoItem(idLista, option.id)}
             ref={(node) => {
               itensRef.current[option.id] = node;
             }}
@@ -383,6 +430,32 @@ export function Combobox({
           </DropdownMenuItem>
         ))}
 
+        {podeCriar && (
+          <DropdownMenuItem
+            id={idDoItem(idLista, CREATE_ID)}
+            ref={(node) => {
+              itensRef.current[CREATE_ID] = node;
+            }}
+            className={cn(
+              "flex w-full items-center gap-2",
+              ativo === filtradas.length && "bg-accent text-accent-foreground",
+            )}
+            onPointerMove={(event) => {
+              event.preventDefault();
+              setApontado(CREATE_ID);
+            }}
+            onSelect={(event) => {
+              event.preventDefault();
+              alternar(CREATE_ID);
+            }}
+          >
+            <Plus className="h-4 w-4 shrink-0" />
+            <span className="truncate">
+              {createLabel ? createLabel(termo) : t("common.createNamed", { text: termo })}
+            </span>
+          </DropdownMenuItem>
+        )}
+
         {visiveis.length === 0 && (
           <p className="px-2 py-3 text-center text-sm text-muted-foreground">
             {emptyMessage ?? t("common.noResults")}

package/src/components/ui/export-button.tsx

@@ -14,28 +14,30 @@ export interface ExportButtonProps extends Omit<ButtonProps, "children"> {
   query?: ExportQuery;
   /** Texto do botão. Ausente, "Exportar". */
   label?: string;
+  /** O que o painel de jobs mostra enquanto gera. Ausente, "Relatório". */
+  jobLabel?: string;
 }
 
 /**
  * Baixa a listagem em planilha.
  *
- * O relatório é gerado fora da requisição, então o botão não trava a tela: ele
- * vira contador de linhas enquanto o arquivo é escrito e baixa sozinho no fim.
- * Fica desabilitado durante a geração porque um segundo pedido só faria a mesma
- * planilha duas vezes. A falha vira toast aqui dentro — a tela que usa o botão
- * não escreve tratamento de erro nenhum.
+ * O relatório é gerado fora da requisição, então o botão não trava a tela: o
+ * andamento aparece no painel de jobs do canto, e o arquivo baixa sozinho no
+ * fim. Fica desabilitado durante a geração porque um segundo pedido só faria a
+ * mesma planilha duas vezes. A falha vira toast aqui dentro — a tela que usa o
+ * botão não escreve tratamento de erro nenhum.
  */
 const ExportButton = React.forwardRef<HTMLButtonElement, ExportButtonProps>(
-  ({ handler, query, label, variant = "outline", ...props }, ref) => {
+  ({ handler, query, label, jobLabel, variant = "outline", ...props }, ref) => {
     const { t } = useI18n();
     const { notify } = useToast();
-    const { request, generating, processed } = useExport();
+    const { request, generating } = useExport();
 
     // O aviso é do botão, não da tela: quem usa o componente não deveria
     // precisar escrever tratamento de erro para ganhar o comportamento.
     const run = async (): Promise<void> => {
       try {
-        await request(handler, query);
+        await request(handler, query, { label: jobLabel });
       } catch (error) {
         notify((error as Error).message || t("export.failed"), "error");
       }
@@ -52,9 +54,7 @@ const ExportButton = React.forwardRef<HTMLButtonElement, ExportButtonProps>(
         {generating ? (
           <>
             <Loader2 className="h-4 w-4 animate-spin" />
-            {processed > 0
-              ? t("export.progress", { rows: processed.toLocaleString() })
-              : t("export.starting")}
+            {t("export.starting")}
           </>
         ) : (
           <>

package/src/hooks/use-document-title.ts

@@ -0,0 +1,40 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * O título com que a página carregou — o que o `metadata` do projeto mandou.
+ *
+ * Lido uma vez por carregamento e nunca reescrito: é o sufixo de todos os
+ * títulos daqui em diante, e o projeto não precisa dizer duas vezes como se
+ * chama (o prefixo "Dev - " que ele põe no `metadata` vem junto de graça).
+ */
+let baseTitle: string | null = null;
+
+/** O que fica entre o nome da tela e o do sistema. */
+const SEPARATOR = " · ";
+
+/**
+ * A aba do navegador diz em que tela se está.
+ *
+ * Com cinco abas do sistema abertas, todas se chamavam só pelo nome dele — e
+ * achar a do financeiro era clicar uma a uma. A tela vem **antes** do nome do
+ * sistema, e não depois: a aba trunca pelo fim, e "ControlX - Controle
+ * fina…" vira "ControlX" em todas.
+ *
+ * `null` devolve o título de origem — é o que a tela sem migalha faz.
+ */
+export const useDocumentTitle = (title: string | null): void => {
+  useEffect(() => {
+    if (baseTitle === null) {
+      baseTitle = document.title;
+    }
+
+    if (!title) {
+      document.title = baseTitle;
+      return;
+    }
+
+    document.title = baseTitle ? `${title}${SEPARATOR}${baseTitle}` : title;
+  }, [title]);
+};

package/src/hooks/use-export.ts

@@ -1,44 +1,54 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useState } from "react";
 
 import { api } from "#core/_services/api/axios.factory";
+import { useI18n } from "#core/contexts/i18n-context";
+import { useJobs } from "#core/contexts/jobs-context";
 
-/** De quanto em quanto tempo a tela pergunta como está o relatório. */
-const POLL_INTERVAL_MS = 1500;
-
-/** O recorte que vai junto — o mesmo da listagem. */
+/** O recorte que vai junto — o mesmo da listagem, ou os parâmetros do documento. */
 export interface ExportQuery {
   filter?: string;
   search?: string;
   sortBy?: string;
   sortDir?: "ASC" | "DESC";
+  /**
+   * Parâmetros de um relatório em **documento** (mês, ids escolhidos…),
+   * validados pelo handler ainda na rota. Planilha ignora.
+   */
+  params?: Record<string, unknown>;
+}
+
+export interface ExportOptions {
+  /** O que o painel de jobs mostra enquanto gera. Ausente, "Relatório". */
+  label?: string;
 }
 
-interface ExportStatus {
-  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown";
-  processed: number;
+/** O que o processador devolve — o nome do arquivo é o que o download usa. */
+interface ExportJobSummary {
+  fileName: string;
   totalRows: number | null;
-  fileName: string | null;
-  errorMessage: string | null;
 }
 
 export interface UseExportResult {
-  /** Pede o relatório. Devolve quando ele terminou — ou lança, se falhou. */
-  request: (handler: string, query?: ExportQuery) => Promise<void>;
-  /** Há um relatório sendo gerado agora. */
+  /** Pede o relatório. Devolve quando ele foi baixado — ou lança, se falhou. */
+  request: (
+    handler: string,
+    query?: ExportQuery,
+    options?: ExportOptions,
+  ) => Promise<void>;
+  /** Há um relatório pedido por este hook sendo gerado agora. */
   generating: boolean;
-  /** Linhas já escritas. Sem total: em stream ele só é conhecido no fim. */
-  processed: number;
 }
 
 /**
  * Pede um relatório e o entrega quando fica pronto.
  *
- * Por consulta, e não por socket: o único evento que interessa aqui é "acabou",
- * e perguntar de segundo em segundo custa menos que manter um caminho de tempo
- * real que precisa de rede de segurança de qualquer forma — aba reaberta,
- * conexão caída. A contagem de linhas vem de carona na mesma resposta.
+ * O acompanhamento é do `JobsProvider`: o pedido vira uma sessão no painel
+ * de jobs do canto — o mesmo do upload de imagem — que recebe progresso pelo
+ * socket e se reconcilia por HTTP quando a conexão cai. Sair da tela não
+ * interrompe o acompanhamento; o download automático, sim, porque a promessa
+ * dele morre com quem a esperava — o arquivo continua na pasta até a faxina.
  *
  * ```tsx
  * const { request, generating } = useExport();
@@ -46,23 +56,18 @@ export interface UseExportResult {
  * ```
  */
 export function useExport(): UseExportResult {
+  const { t } = useI18n();
+  const { start } = useJobs();
   const [generating, setGenerating] = useState(false);
-  const [processed, setProcessed] = useState(0);
-
-  // Evita continuar perguntando por um relatório de uma tela que já saiu.
-  const activeRef = useRef(true);
-
-  useEffect(() => {
-    activeRef.current = true;
-    return () => {
-      activeRef.current = false;
-    };
-  }, []);
 
   const request = useCallback(
-    async (handler: string, query: ExportQuery = {}): Promise<void> => {
+    async (
+      handler: string,
+      query: ExportQuery = {},
+      options: ExportOptions = {},
+    ): Promise<void> => {
       setGenerating(true);
-      setProcessed(0);
+      const job = start<ExportJobSummary>(options.label ?? t("export.job"));
 
       try {
         const { data } = await api.post<{ jobId: string }>(
@@ -70,46 +75,29 @@ export function useExport(): UseExportResult {
           query,
         );
 
-        const status = await waitUntilDone(data.jobId, activeRef, setProcessed);
+        job.bind(data.jobId);
 
-        if (!status) {
-          return;
-        }
-        if (status.state === "failed") {
-          throw new Error(status.errorMessage ?? "A geração do relatório falhou");
-        }
+        const summary = await job.done;
 
-        await download(data.jobId, status.fileName);
+        await download(data.jobId, summary.fileName);
+      } catch (error) {
+        // `fail` é idempotente para quem chama: se o socket já trouxe a
+        // falha, isto não duplica nada — mas se foi o HTTP que recusou, é o
+        // que tira a sessão do painel.
+        job.fail(messageOf(error, t("export.failed")));
+        throw error;
       } finally {
         setGenerating(false);
       }
     },
-    [],
+    [start, t],
   );
 
-  return { request, generating, processed };
+  return { request, generating };
 }
 
-const waitUntilDone = async (
-  jobId: string,
-  active: { current: boolean },
-  onProgress: (processed: number) => void,
-): Promise<ExportStatus | null> => {
-  for (;;) {
-    if (!active.current) {
-      return null;
-    }
-
-    const { data } = await api.get<ExportStatus>(`/exports/${jobId}/status`);
-    onProgress(data.processed);
-
-    if (data.state === "completed" || data.state === "failed") {
-      return data;
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-  }
-};
+const messageOf = (error: unknown, fallback: string): string =>
+  error instanceof Error && error.message ? error.message : fallback;
 
 /**
  * Baixa o arquivo.
@@ -119,10 +107,7 @@ const waitUntilDone = async (
  * `revokeObjectURL` devolve a memória do blob, que senão fica presa até a aba
  * fechar.
  */
-const download = async (
-  jobId: string,
-  fileName: string | null,
-): Promise<void> => {
+const download = async (jobId: string, fileName: string): Promise<void> => {
   const { data } = await api.get<Blob>(`/exports/${jobId}`, {
     responseType: "blob",
   });
@@ -131,7 +116,7 @@ const download = async (
   const link = document.createElement("a");
 
   link.href = url;
-  link.download = fileName ?? "relatorio.xlsx";
+  link.download = fileName;
   document.body.appendChild(link);
   link.click();
   link.remove();

package/src/i18n/messages/en.ts

@@ -170,7 +170,7 @@ export const en: Messages = {
   export: {
     label: "Export",
     starting: "Generating...",
-    progress: "{rows} rows",
+    job: "Report",
     failed: "Could not generate the report",
   },
   table: {
@@ -294,6 +294,7 @@ export const en: Messages = {
     deleteWarning:
       "This action cannot be undone. The record leaves the lists and stops appearing in the system.",
     create: "Create",
+    createNamed: 'Create "{text}"',
     confirm: "Confirm",
     send: "Send",
     yes: "Yes",

package/src/i18n/messages/pt.ts

@@ -172,7 +172,7 @@ export const pt = {
   export: {
     label: "Exportar",
     starting: "Gerando...",
-    progress: "{rows} linhas",
+    job: "Relatório",
     failed: "Não foi possível gerar o relatório",
   },
   table: {
@@ -297,6 +297,7 @@ export const pt = {
     deleteWarning:
       "Esta ação não pode ser desfeita. O registro sai das listas e deixa de aparecer no sistema.",
     create: "Criar",
+    createNamed: 'Criar "{text}"',
     confirm: "Confirmar",
     send: "Enviar",
     yes: "Sim",

package/src/index.ts

@@ -82,7 +82,12 @@ export type {
   UseConfirmResult,
 } from "#core/hooks/use-confirm";
 export { useConfirm } from "#core/hooks/use-confirm";
-export type { ExportQuery, UseExportResult } from "#core/hooks/use-export";
+export { useDocumentTitle } from "#core/hooks/use-document-title";
+export type {
+  ExportOptions,
+  ExportQuery,
+  UseExportResult,
+} from "#core/hooks/use-export";
 export { useExport } from "#core/hooks/use-export";
 export type { UseFilterSchemaResult } from "#core/hooks/use-filter-schema";
 export { useFilterSchema } from "#core/hooks/use-filter-schema";