rl-core-front 0.19.2 → 0.19.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.19.2",
+  "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/_services/api/schema.d.ts

@@ -1581,6 +1581,11 @@ export interface components {
              * @example /usuarios
              */
             route?: string | null;
+            /**
+             * @description Módulo de origem, que agrupa o sino. Nulo quando veio do próprio sistema.
+             * @example Contas
+             */
+            source?: string | null;
             read: boolean;
             /** Format: date-time */
             createdAt: string;
@@ -1605,7 +1610,7 @@ export interface components {
             body: string;
             type: components["schemas"]["NotificationType"];
             targets: components["schemas"]["NotificationTargetCommand"][];
-            /** @description Dado extra. `route` é usado pelo cliente para navegar. */
+            /** @description Dado extra. `route` é usado pelo cliente para navegar; `source` é o módulo de origem, que agrupa o sino. */
             payload?: Record<string, never>;
         };
         RequestExportCommand: {

package/src/_utils/format.ts

@@ -25,6 +25,63 @@ export function formatDateTime(value: string | Date, locale: string): string {
   }).format(date);
 }
 
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+
+const sameDay = (a: Date, b: Date): boolean =>
+  a.getFullYear() === b.getFullYear() &&
+  a.getMonth() === b.getMonth() &&
+  a.getDate() === b.getDate();
+
+/**
+ * Há quanto tempo, do jeito que uma caixa de entrada mostra: "agora",
+ * "há 6 min", "há 2 h" no mesmo dia, "ontem, 18:02" e, antes disso, só a data
+ * curta — o que importa num aviso de três dias atrás é *qual* dia, não a hora.
+ *
+ * `now` é parâmetro para o teste fixar o relógio; em uso normal fica o padrão.
+ */
+export function formatRelativeTime(
+  value: string | Date,
+  locale: string,
+  now: Date = new Date(),
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return String(value);
+  }
+
+  const relative = new Intl.RelativeTimeFormat(locale, {
+    numeric: "auto",
+    style: "short",
+  });
+  const elapsed = now.getTime() - date.getTime();
+
+  if (elapsed < MINUTE_MS) {
+    return relative.format(0, "second");
+  }
+  if (elapsed < HOUR_MS) {
+    return relative.format(-Math.floor(elapsed / MINUTE_MS), "minute");
+  }
+  if (sameDay(date, now)) {
+    return relative.format(-Math.floor(elapsed / HOUR_MS), "hour");
+  }
+
+  const yesterday = new Date(now);
+  yesterday.setDate(now.getDate() - 1);
+  if (sameDay(date, yesterday)) {
+    const time = new Intl.DateTimeFormat(locale, { timeStyle: "short" }).format(
+      date,
+    );
+    return `${relative.format(-1, "day")}, ${time}`;
+  }
+
+  return new Intl.DateTimeFormat(locale, {
+    day: "2-digit",
+    month: "2-digit",
+    ...(date.getFullYear() !== now.getFullYear() && { year: "numeric" }),
+  }).format(date);
+}
+
 /** Aplica máscara de telefone BR enquanto digita: (00) 00000-0000 */
 export function maskPhoneBR(value: string): string {
   const d = value.replace(/\D/g, "").slice(0, 11);

package/src/_utils/text.ts

@@ -0,0 +1,25 @@
+/**
+ * O texto pronto para comparar: minúsculo e sem acento.
+ *
+ * `"Óleo"` vira `"oleo"` — é o que faz digitar `oleo` achar "Óleo do motor"
+ * num select. O banco já compara assim (collation *accent-insensitive*); no
+ * navegador, `includes` compara byte a byte, e o acento separava o que a
+ * pessoa digitou do que estava cadastrado.
+ *
+ * `NFD` separa a letra do acento, e a faixa `\p{Diacritic}` é o acento —
+ * removê-la deixa a letra. Vale para qualquer alfabeto latino, não só o
+ * nosso.
+ */
+export const normalizeText = (text: string): string =>
+  text
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase();
+
+/** `text` contém `term`, ignorando acento e caixa. Termo vazio casa com tudo. */
+export const matchesText = (text: string, term: string): boolean =>
+  normalizeText(text).includes(normalizeText(term.trim()));
+
+/** Os dois são o mesmo nome, ignorando acento, caixa e espaços nas pontas. */
+export const sameText = (a: string, b: string): boolean =>
+  normalizeText(a.trim()) === normalizeText(b.trim());

package/src/components/ui/combobox.tsx

@@ -4,6 +4,7 @@ import { Check, ChevronDown, Plus, X } from "lucide-react";
 import type { JSX } from "react";
 import { useEffect, useId, useMemo, useRef, useState } from "react";
 
+import { matchesText, sameText } from "#core/_utils/text";
 import { Badge } from "#core/components/ui/badge";
 import { Button } from "#core/components/ui/button";
 import {
@@ -46,8 +47,17 @@ export interface ComboboxProps {
    * 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;
+  /**
+   * Chamado com o texto digitado, já sem espaços nas pontas.
+   *
+   * Pode devolver o id do que criou — direto ou em promessa. Quando devolve,
+   * o item novo fica selecionado (no múltiplo, marcado junto aos outros):
+   * quem digitou "Kronos" e mandou criar quer a despesa na Kronos, não a
+   * lista fechada e o campo vazio. Quem não devolve nada, como o campo que
+   * só guarda o texto no formulário, continua como antes. Erro é de quem
+   * cria — o toast é dele; aqui só não se seleciona nada.
+   */
+  onCreate?: (text: string) => CreateResult | Promise<CreateResult>;
   /** Texto da linha de criação. Ausente, `Criar "{text}"`. */
   createLabel?: (text: string) => string;
   /**
@@ -64,6 +74,9 @@ export interface ComboboxProps {
   idleCloseMs?: number;
 }
 
+/** O que o `onCreate` devolve: o id do item criado, ou nada. */
+export type CreateResult = string | null | undefined | void;
+
 /** Id da linha de criação na lista apontável — nenhuma opção real o usa. */
 const CREATE_ID = "\u0000create";
 
@@ -160,23 +173,24 @@ export function Combobox({
     [options, value],
   );
 
+  /*
+    Sem acento e sem caixa, dos dois lados: digitar "oleo" acha "Óleo do
+    motor". É como o banco já compara — e o select, que filtra no navegador,
+    não podia ser mais exigente que ele.
+  */
   const termo = search.trim();
   const filtradas = useMemo(
-    () =>
-      options.filter((option) =>
-        option.name.toLowerCase().includes(termo.toLowerCase()),
-      ),
+    () => options.filter((option) => matchesText(option.name, termo)),
     [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.
+   * A linha "Criar" só quando há texto e nenhuma opção tem esse nome — com
+   * "Kronos" na lista, digitar "kronos" deve escolher, não criar; e com
+   * "Óleo", digitar "oleo" também.
    */
   const podeCriar =
-    creatable &&
-    termo !== "" &&
-    !options.some((option) => option.name.toLowerCase() === termo.toLowerCase());
+    creatable && termo !== "" && !options.some((option) => sameText(option.name, termo));
 
   /** O que se aponta pelo teclado: as opções filtradas e, no fim, a de criar. */
   const visiveis = useMemo(
@@ -184,6 +198,26 @@ export function Combobox({
     [filtradas, podeCriar, termo],
   );
 
+  /*
+   * O valor do momento em que a criação termina, e não o do clique: no
+   * múltiplo, quem marcou outro item enquanto o POST corria não pode perder
+   * a marca quando o novo chega.
+   */
+  const valorAtual = useRef(value);
+  useEffect(() => {
+    valorAtual.current = value;
+  }, [value]);
+
+  const criar = (texto: string): void => {
+    Promise.resolve(onCreate?.(texto))
+      .then((novo) => {
+        if (novo) {
+          onChange(multiple ? [...valorAtual.current, novo] : [novo]);
+        }
+      })
+      .catch(() => undefined);
+  };
+
   /** A posição do apontado; sem ele — ou fora da busca — é a do primeiro. */
   const ativo = Math.max(
     visiveis.findIndex((option) => option.id === apontado),
@@ -192,7 +226,7 @@ export function Combobox({
 
   const alternar = (id: string): void => {
     if (id === CREATE_ID) {
-      onCreate?.(termo);
+      criar(termo);
       setSearch("");
       if (!multiple) {
         setOpen(false);

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/components/ui/index.ts

@@ -32,6 +32,7 @@ export * from "./password-requirements";
 export * from "./period-nav";
 export * from "./popover";
 export * from "./row-actions";
+export * from "./searchable-select";
 export * from "./segmented-control";
 export * from "./select";
 export * from "./separator";

package/src/components/ui/searchable-select.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import type { JSX } from "react";
+
+import { Combobox, type CreateResult } from "#core/components/ui/combobox";
+import type { SelectOption } from "#core/components/ui/simple-select";
+
+export interface SearchableSelectProps {
+  value: string;
+  onChange: (value: string) => void;
+  /** O mesmo formato do `SimpleSelect` — a troca entre os dois é o nome. */
+  options: SelectOption[];
+  placeholder?: string;
+  searchPlaceholder?: string;
+  /** Mostra o X que devolve o campo ao vazio. Só onde o vazio é resposta. */
+  clearable?: boolean;
+  disabled?: boolean;
+  /**
+   * Deixa criar o que foi digitado quando nenhuma opção tem esse nome.
+   *
+   * É a flag por campo: o select de categoria da despesa liga, o filtro do
+   * extrato não. Quem cria é o `onCreate`, que devolve o id do registro
+   * novo — e o campo fica com ele selecionado, como se a pessoa tivesse
+   * escolhido da lista.
+   */
+  creatable?: boolean;
+  onCreate?: (text: string) => CreateResult | Promise<CreateResult>;
+  /** Texto da linha de criação. Ausente, `Criar "{text}"`. */
+  createLabel?: (text: string) => string;
+}
+
+/**
+ * Escolha de **um** valor, com busca — o `Combobox` no formato de select.
+ *
+ * O `Combobox` fala em lista (`string[]`), porque também serve à escolha
+ * múltipla; aqui dentro fica a conversão que todo campo de um valor faria
+ * igual, e a tela continua passando `value`/`onChange` de texto como já
+ * fazia com o `SimpleSelect`.
+ *
+ * Por que não o `SimpleSelect` nesses campos: com uma dúzia de categorias
+ * cadastradas, achar "Combustível" numa lista sem busca é rolar até
+ * encontrar, e o teclado do Radix só salta para a opção — não filtra.
+ */
+export const SearchableSelect = ({
+  value,
+  onChange,
+  options,
+  placeholder,
+  searchPlaceholder,
+  clearable,
+  disabled,
+  creatable,
+  onCreate,
+  createLabel,
+}: SearchableSelectProps): JSX.Element => (
+  <Combobox
+    options={options.map((option) => ({ id: option.value, name: option.label }))}
+    // Campo vazio é lista vazia: `[""]` seria uma opção de id em branco.
+    value={value ? [value] : []}
+    onChange={(ids) => onChange(ids[0] ?? "")}
+    placeholder={placeholder}
+    searchPlaceholder={searchPlaceholder}
+    clearable={clearable}
+    disabled={disabled}
+    creatable={creatable}
+    onCreate={onCreate}
+    createLabel={createLabel}
+  />
+);

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

@@ -3,22 +3,35 @@
 import { AlertTriangle, CheckCircle2, Info, X, XCircle } from "lucide-react";
 import type { JSX } from "react";
 
-import { formatDateTime } from "#core/_utils/format";
+import { formatDateTime, formatRelativeTime } from "#core/_utils/format";
 import { useI18n } from "#core/contexts";
 import { NotificationType } from "#core/features/notifications/enums/notification-type.enum";
 import type { UserNotification } from "#core/features/notifications/services/notifications.service";
 import { cn } from "#core/lib/utils";
 
-const ICONS: Record<NotificationType, JSX.Element> = {
-  [NotificationType.INFO]: <Info className="h-4 w-4 text-sky-500" />,
-  [NotificationType.SUCCESS]: (
-    <CheckCircle2 className="h-4 w-4 text-emerald-500" />
-  ),
-  [NotificationType.WARNING]: (
-    <AlertTriangle className="h-4 w-4 text-amber-500" />
-  ),
-  [NotificationType.ERROR]: <XCircle className="h-4 w-4 text-destructive" />,
-};
+/**
+ * Ícone e filete lateral saem da mesma cor: a severidade se lê no filete
+ * antes de ler o ícone, e as duas pistas discordando confundiriam.
+ */
+const SEVERITY: Record<NotificationType, { icon: JSX.Element; rail: string }> =
+  {
+    [NotificationType.INFO]: {
+      icon: <Info className="h-4 w-4 text-sky-500" />,
+      rail: "border-l-sky-500",
+    },
+    [NotificationType.SUCCESS]: {
+      icon: <CheckCircle2 className="h-4 w-4 text-emerald-500" />,
+      rail: "border-l-emerald-500",
+    },
+    [NotificationType.WARNING]: {
+      icon: <AlertTriangle className="h-4 w-4 text-amber-500" />,
+      rail: "border-l-amber-500",
+    },
+    [NotificationType.ERROR]: {
+      icon: <XCircle className="h-4 w-4 text-destructive" />,
+      rail: "border-l-destructive",
+    },
+  };
 
 export interface NotificationItemProps {
   notification: UserNotification;
@@ -27,12 +40,18 @@ export interface NotificationItemProps {
   onDismiss: (id: string) => void;
 }
 
+/**
+ * Uma linha compacta: título e hora na mesma linha, corpo em uma só. O sino é
+ * um popover, e cada linha a mais é uma notificação a menos visível sem rolar;
+ * o texto inteiro fica no `title` para o hover.
+ */
 export function NotificationItem({
   notification,
   onSelect,
   onDismiss,
 }: NotificationItemProps): JSX.Element {
   const { locale, t } = useI18n();
+  const severity = SEVERITY[notification.type];
 
   return (
     /*
@@ -42,38 +61,44 @@ export function NotificationItem({
     */
     <div
       className={cn(
-        "group/notice relative border-b border-border transition-colors hover:bg-accent",
-        !notification.read && "bg-accent/40",
+        "group/notice relative border-l-[3px] border-l-transparent transition-colors",
+        // O filete só na não lida: é ele que diz "isto ainda pede atenção".
+        !notification.read && cn("bg-accent/35", severity.rail),
       )}
     >
       <button
         type="button"
         onClick={() => onSelect(notification)}
-        className="flex w-full gap-3 px-4 py-3 pr-10 text-left"
+        className="flex w-full items-start gap-2.5 py-2 pl-3 pr-9 text-left hover:bg-accent"
       >
-        <span className="mt-0.5 shrink-0">{ICONS[notification.type]}</span>
+        <span className="mt-0.5 shrink-0">{severity.icon}</span>
 
         <span className="min-w-0 flex-1">
-        <span className="flex items-center gap-2">
+          <span className="flex items-baseline gap-2">
+            <span
+              title={notification.title}
+              className={cn(
+                "min-w-0 flex-1 truncate text-sm",
+                !notification.read && "font-semibold",
+              )}
+            >
+              {notification.title}
+            </span>
+            <time
+              dateTime={notification.createdAt}
+              title={formatDateTime(notification.createdAt, locale)}
+              className="shrink-0 text-[11px] tabular-nums text-muted-foreground"
+            >
+              {formatRelativeTime(notification.createdAt, locale)}
+            </time>
+          </span>
+
           <span
-            className={cn(
-              "truncate text-sm",
-              notification.read ? "text-foreground" : "font-semibold",
-            )}
+            title={notification.body}
+            className="block truncate text-xs text-muted-foreground"
           >
-            {notification.title}
+            {notification.body}
           </span>
-          {!notification.read && (
-            <span className="h-2 w-2 shrink-0 rounded-full bg-primary" />
-          )}
-        </span>
-
-        <span className="mt-0.5 block text-xs text-muted-foreground">
-          {notification.body}
-        </span>
-        <span className="mt-1 block text-[11px] text-muted-foreground">
-          {formatDateTime(notification.createdAt, locale)}
-        </span>
         </span>
       </button>
 
@@ -84,7 +109,7 @@ export function NotificationItem({
         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"
+        className="absolute right-2 top-2 hidden rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground group-hover/notice:block group-focus-within/notice:block"
       >
         <X className="h-3.5 w-3.5" />
       </button>

package/src/features/notifications/notifications-center.tsx

@@ -20,9 +20,44 @@ import { cn } from "#core/lib/utils";
 
 type Tab = "all" | "unread" | "read";
 
+const TABS: readonly Tab[] = ["all", "unread", "read"];
+
 /** Acima disso o número não cabe no badge sem empurrar o layout. */
 const BADGE_LIMIT = 99;
 
+interface NotificationGroup {
+  source: string;
+  items: UserNotification[];
+  unread: number;
+}
+
+/**
+ * Agrupa pela origem (`source`), na ordem em que cada uma aparece na lista —
+ * como a lista vem da mais nova para a mais velha, o grupo com a notificação
+ * mais recente fica no topo. O sino não conhece os módulos do produto, então
+ * não existe ordem fixa para impor; quem não declarou origem cai no grupo
+ * padrão ("Sistema").
+ */
+export function groupBySource(
+  items: UserNotification[],
+  defaultSource: string,
+): NotificationGroup[] {
+  const groups = new Map<string, NotificationGroup>();
+
+  for (const item of items) {
+    const source = item.source ?? defaultSource;
+    const group = groups.get(source) ?? { source, items: [], unread: 0 };
+
+    group.items.push(item);
+    if (!item.read) {
+      group.unread += 1;
+    }
+    groups.set(source, group);
+  }
+
+  return [...groups.values()];
+}
+
 export function NotificationsCenter(): JSX.Element {
   const { t } = useI18n();
   const router = useRouter();
@@ -30,6 +65,9 @@ export function NotificationsCenter(): JSX.Element {
     useNotifications();
   const [tab, setTab] = useState<Tab>("all");
 
+  const read = items.length - unread;
+  const counts: Record<Tab, number> = { all: items.length, unread, read };
+
   const visible =
     tab === "unread"
       ? items.filter((i) => !i.read)
@@ -37,7 +75,7 @@ export function NotificationsCenter(): JSX.Element {
         ? items.filter((i) => i.read)
         : items;
 
-  const lidas = items.filter((i) => i.read).length;
+  const groups = groupBySource(visible, t("notifications.sourceDefault"));
 
   const onSelect = (notification: UserNotification): void => {
     if (!notification.read) {
@@ -68,24 +106,8 @@ export function NotificationsCenter(): JSX.Element {
       </DropdownMenuTrigger>
 
       <DropdownMenuContent align="end" className="w-96 p-0">
-        <div className="flex items-center justify-between border-b border-border px-4 py-2">
-          <div className="flex gap-3">
-            {(["all", "unread", "read"] as const).map((value) => (
-              <button
-                key={value}
-                type="button"
-                onClick={() => setTab(value)}
-                className={cn(
-                  "border-b-2 pb-1 text-sm transition-colors",
-                  tab === value
-                    ? "border-primary font-medium text-foreground"
-                    : "border-transparent text-muted-foreground hover:text-foreground",
-                )}
-              >
-                {t(`notifications.${value}`)}
-              </button>
-            ))}
-          </div>
+        <div className="flex items-center justify-between px-4 pt-3">
+          <h2 className="text-sm font-semibold">{t("notifications.title")}</h2>
 
           {/*
             A ação do cabeçalho segue a aba. Em "Lidas" o que se quer é
@@ -96,7 +118,7 @@ export function NotificationsCenter(): JSX.Element {
             <button
               type="button"
               onClick={() => void dismissRead()}
-              disabled={lidas === 0}
+              disabled={read === 0}
               className="text-xs font-medium text-primary hover:underline disabled:cursor-not-allowed disabled:text-muted-foreground disabled:no-underline"
             >
               {t("notifications.clearRead")}
@@ -113,6 +135,39 @@ export function NotificationsCenter(): JSX.Element {
           )}
         </div>
 
+        <div
+          role="tablist"
+          className="flex gap-1 border-b border-border px-3 pt-2"
+        >
+          {TABS.map((value) => (
+            <button
+              key={value}
+              type="button"
+              role="tab"
+              aria-selected={tab === value}
+              onClick={() => setTab(value)}
+              className={cn(
+                "-mb-px inline-flex items-center gap-1.5 border-b-2 px-1.5 pb-2 pt-1 text-sm transition-colors",
+                tab === value
+                  ? "border-primary font-medium text-foreground"
+                  : "border-transparent text-muted-foreground hover:text-foreground",
+              )}
+            >
+              {t(`notifications.${value}`)}
+              <span
+                className={cn(
+                  "grid h-[18px] min-w-[18px] place-items-center rounded-full px-1.5 text-[10.5px] font-semibold",
+                  tab === value
+                    ? "bg-primary/15 text-primary"
+                    : "bg-muted text-muted-foreground",
+                )}
+              >
+                {counts[value]}
+              </span>
+            </button>
+          ))}
+        </div>
+
         <div className="max-h-96 overflow-y-auto">
           {loading && items.length === 0 && (
             <div className="flex justify-center py-8">
@@ -126,13 +181,39 @@ export function NotificationsCenter(): JSX.Element {
             </p>
           )}
 
-          {visible.map((notification) => (
-            <NotificationItem
-              key={notification.id}
-              notification={notification}
-              onSelect={onSelect}
-              onDismiss={(id) => void dismiss(id)}
-            />
+          {groups.map((group) => (
+            <section key={group.source} aria-label={group.source}>
+              <header className="flex items-baseline justify-between px-3 pb-1 pt-2.5">
+                <span className="text-[10.5px] font-semibold uppercase tracking-wider text-muted-foreground">
+                  {group.source}
+                </span>
+                <span className="text-[11px] tabular-nums text-muted-foreground">
+                  {group.unread > 0 && (
+                    <>
+                      <span className="font-semibold text-primary">
+                        {group.unread}
+                      </span>{" "}
+                      {t(
+                        group.unread === 1
+                          ? "notifications.unreadOne"
+                          : "notifications.unreadMany",
+                      )}
+                      {" · "}
+                    </>
+                  )}
+                  {group.items.length}
+                </span>
+              </header>
+
+              {group.items.map((notification) => (
+                <NotificationItem
+                  key={notification.id}
+                  notification={notification}
+                  onSelect={onSelect}
+                  onDismiss={(id) => void dismiss(id)}
+                />
+              ))}
+            </section>
           ))}
         </div>
       </DropdownMenuContent>

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/i18n/messages/en.ts

@@ -272,6 +272,9 @@ export const en: Messages = {
     dismiss: "Remove from list",
     markAllRead: "Mark all as read",
     empty: "No notifications",
+    sourceDefault: "System",
+    unreadOne: "unread",
+    unreadMany: "unread",
   },
   calculator: {
     open: "Open the calculator",

package/src/i18n/messages/pt.ts

@@ -275,6 +275,9 @@ export const pt = {
     dismiss: "Tirar da lista",
     markAllRead: "Marcar todas como lidas",
     empty: "Nenhuma notificação",
+    sourceDefault: "Sistema",
+    unreadOne: "não lida",
+    unreadMany: "não lidas",
   },
   calculator: {
     open: "Abrir a calculadora",

package/src/index.ts

@@ -64,10 +64,12 @@ export { anyOrTeam } from "#core/_utils/permission";
 export {
   formatCurrencyBR,
   formatMoneyBR,
+  formatRelativeTime,
   maskCurrencyBR,
   maskPhoneBR,
   parseCurrencyBR,
 } from "#core/_utils/format";
+export { matchesText, normalizeText, sameText } from "#core/_utils/text";
 
 // ---------------------------------------------------------------------------
 // Hooks de listagem, requisição e filtro
@@ -129,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";