rl-core-front 0.19.5 → 0.19.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.19.5",
+  "version": "0.19.6",
   "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/ui/data-table.tsx

@@ -280,6 +280,25 @@ interface DataTableProps<T extends RowData> {
    * (a receber / recebidas) declara esta lista.
    */
   groupOrder?: string[];
+  /**
+   * A linha que um link aponta — pelo id de `getRowId`.
+   *
+   * A tabela abre a seção em que ela está, rola até ela e a destaca por alguns
+   * segundos: é o que faz o aviso "luz venceu" cair na linha da luz, e não no
+   * topo de um mês de trinta lançamentos. Acontece quando o id troca e quando
+   * a linha chega (o dado costuma vir depois do link); fora disso a linha é
+   * uma linha como as outras — o destaque é um sinal, não um estado.
+   *
+   * Exige `getRowId`. Id que não está em `data` não faz nada.
+   */
+  highlightRowId?: string | null;
+  /**
+   * A seção que um link aponta — pela chave de `groupBy`.
+   *
+   * O mesmo gesto, na faixa: para o aviso que fala da fatura inteira, e não de
+   * uma parcela dela.
+   */
+  highlightGroupKey?: string | null;
 }
 
 /** Uma seção da listagem, como o cabeçalho de grupo a recebe. */
@@ -458,6 +477,20 @@ function shrinkClass(columnDef: { meta?: unknown }): string | undefined {
  */
 const CELL_MAX_WIDTH = "24rem";
 
+/**
+ * Quanto tempo a linha apontada fica destacada.
+ *
+ * O bastante para o olho chegar depois da rolagem e curto o bastante para não
+ * parecer seleção: passado isso, a cor esmaece e a linha volta ao normal.
+ */
+const HIGHLIGHT_MS = 3000;
+
+/** O que está destacado agora — a linha, a faixa, ou nada. */
+interface Spotlight {
+  rowId: string | null;
+  groupKey: string | null;
+}
+
 /**
  * Como a célula se comporta quando o conteúdo não cabe: corta com reticências.
  *
@@ -571,6 +604,8 @@ export function DataTable<T extends RowData>({
   groupOrder,
   collapsibleGroups = false,
   defaultCollapsedGroups,
+  highlightRowId = null,
+  highlightGroupKey = null,
 }: DataTableProps<T>): JSX.Element {
   const { t } = useI18n();
   const [colsOpen, setColsOpen] = useState(false);
@@ -578,6 +613,93 @@ export function DataTable<T extends RowData>({
   const [collapsedGroups, setCollapsedGroups] = useState<string[]>(
     () => defaultCollapsedGroups ?? [],
   );
+  /*
+    O que está apontado e se ainda está aceso.
+
+    Dois estados porque a transição de cor fica ligada na linha apontada mesmo
+    depois de a cor sair: se ela morasse só enquanto acesa, sumiria junto com
+    a cor e o esmaecer viraria um corte. E só nessa linha, e não em todas —
+    com a transição na tabela inteira, o hover de cada linha demoraria para
+    acender.
+  */
+  const [spotlight, setSpotlight] = useState<Spotlight | null>(null);
+  const [lit, setLit] = useState(false);
+  /** O pedido já atendido — para o mesmo link não acender a linha a cada render. */
+  const [seenHighlight, setSeenHighlight] = useState<string | null>(null);
+  const bodyRef = useRef<HTMLTableSectionElement>(null);
+
+  /*
+    A linha apontada, se ela está em `data`; e a seção dela, para abrir.
+
+    Procurada em `data` e não no modelo da tabela: fechada, a seção tira as
+    linhas do modelo, e a linha que se quer abrir é justamente a que está
+    escondida.
+  */
+  const highlightedRow =
+    highlightRowId !== null && getRowId
+      ? data.find((row) => getRowId(row) === highlightRowId)
+      : undefined;
+  const highlightedGroup =
+    highlightGroupKey ??
+    (highlightedRow !== undefined && groupBy ? groupBy(highlightedRow) : null);
+  const highlightTarget =
+    highlightedRow !== undefined ||
+    (highlightGroupKey !== null && Boolean(groupBy) &&
+      data.some((row) => groupBy?.(row) === highlightGroupKey));
+  const highlightKey = highlightTarget
+    ? `${highlightRowId ?? ""}|${highlightGroupKey ?? ""}`
+    : null;
+
+  /*
+    Reage ao link no próprio render, e não num efeito: é o padrão do React
+    para "estado que depende da prop anterior", e poupa o quadro em que a
+    seção ainda estaria fechada. Quando o alvo some da lista (a tela trocou de
+    mês), o pedido é esquecido — e a linha acende de novo se voltar.
+  */
+  if (highlightKey !== seenHighlight) {
+    setSeenHighlight(highlightKey);
+
+    if (highlightKey !== null) {
+      setSpotlight({ rowId: highlightRowId, groupKey: highlightGroupKey });
+      setLit(true);
+
+      if (highlightedGroup !== null) {
+        setCollapsedGroups((atual) =>
+          atual.filter((fechada) => fechada !== highlightedGroup),
+        );
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (!lit) {
+      return;
+    }
+
+    const timer = window.setTimeout(() => setLit(false), HIGHLIGHT_MS);
+
+    return () => window.clearTimeout(timer);
+    // `spotlight` entra para o relógio recomeçar quando o alvo troca com a
+    // linha anterior ainda acesa.
+  }, [lit, spotlight]);
+
+  // Rola depois de a seção abrir: a linha só existe no DOM depois do render
+  // que a abriu, e um efeito roda justamente depois dele.
+  useEffect(() => {
+    if (spotlight === null) {
+      return;
+    }
+
+    const selector =
+      spotlight.rowId !== null
+        ? `[data-row-id="${CSS.escape(spotlight.rowId)}"]`
+        : spotlight.groupKey !== null
+          ? `[data-group-key="${CSS.escape(spotlight.groupKey)}"]`
+          : null;
+    const alvo = selector ? bodyRef.current?.querySelector(selector) : null;
+
+    alvo?.scrollIntoView({ block: "center", behavior: "smooth" });
+  }, [spotlight]);
   const [filtersOpen, setFiltersOpen] = useState(false);
   /** A linha na mão e a linha embaixo do dedo, enquanto o arrasto dura. */
   const [draggedRow, setDraggedRow] = useState<string | null>(null);
@@ -1102,7 +1224,7 @@ export function DataTable<T extends RowData>({
                 </TableRow>
               ))}
             </TableHeader>
-            <TableBody>
+            <TableBody ref={bodyRef}>
               {loading && (
                 <TableRow>
                   <TableCell colSpan={colSpan} className="h-24 text-center">
@@ -1124,13 +1246,21 @@ export function DataTable<T extends RowData>({
                 sections.map((section) => (
                   <Fragment key={section.key}>
                     {section.header && renderGroupHeader && (
-                      <TableRow className="hover:bg-transparent">
+                      <TableRow
+                        data-group-key={section.key}
+                        className="hover:bg-transparent"
+                      >
                         {/* Uma célula atravessando a tabela: é o que faz a
                             faixa parecer cabeçalho, e não registro sem
                             dados. */}
                         <TableCell
                           colSpan={colSpan}
-                          className="bg-muted/40 py-2"
+                          className={cn(
+                            "bg-muted/40 py-2",
+                            spotlight?.groupKey === section.key &&
+                              "transition-colors duration-700",
+                            lit && spotlight?.groupKey === section.key && "bg-primary/15",
+                          )}
                         >
                           {collapsibleGroups ? (
                             <button
@@ -1174,6 +1304,13 @@ export function DataTable<T extends RowData>({
                             dragging &&
                               "relative z-20 bg-card shadow-xl ring-1 ring-primary/50",
                             draggedRow !== null && "select-none",
+                            // A linha apontada acende e esmaece: a cor some
+                            // sozinha quando o destaque acaba, e a transição
+                            // é o que faz isso parecer "olhe aqui", e não
+                            // uma seleção que ficou.
+                            spotlight?.rowId === row.id &&
+                              "transition-colors duration-700",
+                            lit && spotlight?.rowId === row.id && "bg-primary/15",
                             /*
                           A transição existe só enquanto o arrasto dura, e só nas
                           linhas paradas: na que segue o dedo ela viraria atraso,

package/src/hooks/use-tab-state.ts

@@ -1,16 +1,11 @@
 "use client";
 
-import {
-  useCallback,
-  useEffect,
-  useLayoutEffect,
-  useRef,
-  useSyncExternalStore,
-} from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
 
 import { safeStorage } from "#core/_utils/storage";
 import { useIsHydrated } from "#core/hooks/use-is-hydrated";
 import { useStoredValue } from "#core/hooks/use-stored-value";
+import { readUrlParam, useUrlParam } from "#core/hooks/use-url-param";
 
 const STORAGE_PREFIX = "tab:";
 const DEFAULT_PARAM = "tab";
@@ -33,35 +28,6 @@ export interface UseTabStateResult<T extends string> {
   setTab: (next: string) => void;
 }
 
-const readFromUrl = (param: string): string | null =>
-  new URLSearchParams(window.location.search).get(param);
-
-/** Quem lê a querystring, para saber que ela mudou por aqui. */
-const urlListeners = new Set<() => void>();
-
-const subscribeUrl = (onChange: () => void): (() => void) => {
-  urlListeners.add(onChange);
-  // O "voltar" do navegador também troca a aba, e esse não passa por aqui.
-  window.addEventListener("popstate", onChange);
-  return () => {
-    urlListeners.delete(onChange);
-    window.removeEventListener("popstate", onChange);
-  };
-};
-
-/** Troca só o próprio parâmetro, preservando o resto — o `?filter=` da listagem mora ao lado. */
-const writeToUrl = (param: string, value: string): void => {
-  const params = new URLSearchParams(window.location.search);
-  params.set(param, value);
-  window.history.replaceState(null, "", `${window.location.pathname}?${params.toString()}`);
-
-  // `replaceState` não dispara evento nenhum: sem este aviso, a tela ficaria
-  // na aba antiga até o próximo render por outro motivo.
-  for (const listener of urlListeners) {
-    listener();
-  }
-};
-
 /**
  * Em qual aba a pessoa deixou a tela, por `storageKey`.
  *
@@ -93,11 +59,7 @@ export function useTabState<T extends string>(
   // dentro de um efeito: no primeiro render do Next não há `window`, e a
   // leitura do cliente entra assim que ele hidrata, sem um quadro na aba
   // errada.
-  const urlTab = useSyncExternalStore(
-    subscribeUrl,
-    () => readFromUrl(param),
-    () => null,
-  );
+  const [urlTab, writeUrlTab] = useUrlParam(param);
   const storedTab = useStoredValue(`${STORAGE_PREFIX}${storageKey}`);
 
   const isTab = (value: string | null): value is T =>
@@ -127,10 +89,10 @@ export function useTabState<T extends string>(
     if (!hydrated) {
       return;
     }
-    if (tab !== undefined && readFromUrl(param) !== tab) {
-      writeToUrl(param, tab);
+    if (tab !== undefined && readUrlParam(param) !== tab) {
+      writeUrlTab(tab);
     }
-  }, [hydrated, tab, param]);
+  }, [hydrated, tab, param, writeUrlTab]);
 
   const setTab = useCallback(
     (next: string): void => {
@@ -139,10 +101,10 @@ export function useTabState<T extends string>(
       }
 
       // Escrever nos dois já avisa quem lê: a aba vem da URL e do storage.
-      writeToUrl(param, next);
+      writeUrlTab(next);
       safeStorage.set(`${STORAGE_PREFIX}${storageKey}`, next);
     },
-    [storageKey, param],
+    [storageKey, writeUrlTab],
   );
 
   return { tab, setTab };

package/src/hooks/use-url-param.ts

@@ -0,0 +1,80 @@
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+
+/** Quem lê a querystring, para saber que ela mudou por aqui. */
+const listeners = new Set<() => void>();
+
+const subscribe = (onChange: () => void): (() => void) => {
+  listeners.add(onChange);
+  // O "voltar" do navegador também troca o valor, e esse não passa por aqui.
+  window.addEventListener("popstate", onChange);
+  return () => {
+    listeners.delete(onChange);
+    window.removeEventListener("popstate", onChange);
+  };
+};
+
+/** O valor de um parâmetro da URL, ou `null` quando ele não está lá. */
+export const readUrlParam = (name: string): string | null =>
+  new URLSearchParams(window.location.search).get(name);
+
+/**
+ * Troca só o próprio parâmetro, preservando o resto — o `?filter=` da listagem
+ * mora ao lado. `null` o remove.
+ *
+ * `replaceState`, e não `router.replace`: trocar um parâmetro não é navegação,
+ * e empilhar histórico faria o "voltar" percorrer valor por valor antes de sair
+ * da tela.
+ */
+export const writeUrlParam = (name: string, value: string | null): void => {
+  const params = new URLSearchParams(window.location.search);
+
+  if (value === null) {
+    params.delete(name);
+  } else {
+    params.set(name, value);
+  }
+
+  const query = params.toString();
+  window.history.replaceState(
+    null,
+    "",
+    query ? `${window.location.pathname}?${query}` : window.location.pathname,
+  );
+
+  // `replaceState` não dispara evento nenhum: sem este aviso, quem lê o
+  // parâmetro ficaria com o valor antigo até o próximo render por outro motivo.
+  for (const listener of listeners) {
+    listener();
+  }
+};
+
+/**
+ * Um parâmetro da querystring como estado: `[valor, trocar]`.
+ *
+ * É o que faz o F5 voltar onde estava e transforma o estado em link
+ * compartilhável — o mês em exibição, a linha que um aviso aponta. Lido no
+ * próprio render, e não copiado para um estado num efeito: no primeiro render
+ * do Next não há `window`, e a leitura do cliente entra assim que ele hidrata,
+ * sem um quadro no valor errado.
+ *
+ * O servidor sempre enxerga `null`: quem tem padrão aplica na leitura
+ * (`value ?? padrao`), e o padrão vale nos dois lados.
+ */
+export function useUrlParam(
+  name: string,
+): [value: string | null, set: (value: string | null) => void] {
+  const value = useSyncExternalStore(
+    subscribe,
+    () => readUrlParam(name),
+    () => null,
+  );
+
+  const set = useCallback(
+    (next: string | null): void => writeUrlParam(name, next),
+    [name],
+  );
+
+  return [value, set];
+}

package/src/index.ts

@@ -131,6 +131,7 @@ export type { UseTabStateOptions, UseTabStateResult } from "#core/hooks/use-tab-
 export { useTabState } from "#core/hooks/use-tab-state";
 export type { TableView, UseTableViewResult } from "#core/hooks/use-table-view";
 export { useTableView } from "#core/hooks/use-table-view";
+export { useUrlParam } from "#core/hooks/use-url-param";
 // RequestOperation é enum (valor, não só tipo): sem ele o projeto não consegue
 // pedir o toast padrão de criado/alterado/removido que o core já traduz.
 export { RequestOperation, useRequest } from "#core/hooks/use-request";