rl-core-front 0.16.3 → 0.16.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "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/_utils/calc.ts

@@ -0,0 +1,303 @@
+/**
+ * Avaliador de conta escrita à mão — o que a calculadora do campo de dinheiro
+ * usa para transformar `120+35*2` em `190`.
+ *
+ * **Não usa `eval` nem `new Function`.** O que se digita num campo é texto de
+ * usuário, e texto de usuário que vira código executável é a porta aberta
+ * clássica; além disso, `eval` aceitaria `1+1;alert(1)` e devolveria número,
+ * enquanto este parser recusa o que não entende em vez de tentar adivinhar.
+ *
+ * O que ele entende: `+ - * / %`, parênteses, sinal negativo, e número no
+ * formato brasileiro (ponto de milhar, vírgula decimal).
+ */
+
+/**
+ * Por que a conta não fechou. É código e não frase pronta porque a mensagem é
+ * texto de tela: quem traduz é o componente, com o dicionário de quem está
+ * olhando.
+ */
+export enum CalcErrorCode {
+  /** Apareceu um caractere que não é número nem operador. */
+  UNKNOWN_CHARACTER = "unknownCharacter",
+  /** O que parece número não é: `1,2,3`. */
+  INVALID_NUMBER = "invalidNumber",
+  /** A conta para no meio: `120+`. */
+  INCOMPLETE = "incomplete",
+  /** Abriu parêntese e não fechou. */
+  UNCLOSED_PAREN = "unclosedParen",
+  /** Fechou parêntese que ninguém abriu, ou sobrou algo depois do fim. */
+  TRAILING = "trailing",
+  DIVISION_BY_ZERO = "divisionByZero",
+}
+
+/** O erro que o parser lança. O `code` é o que vira mensagem. */
+export class CalcError extends Error {
+  constructor(
+    readonly code: CalcErrorCode,
+    /** O caractere recusado, quando o código é `UNKNOWN_CHARACTER`. */
+    readonly character?: string,
+  ) {
+    super(code);
+    this.name = "CalcError";
+  }
+}
+
+type SymbolType = "+" | "-" | "*" | "/" | "%" | "(" | ")";
+
+interface NumberToken {
+  type: "number";
+  value: number;
+}
+
+interface SymbolToken {
+  type: SymbolType;
+}
+
+type Token = NumberToken | SymbolToken;
+
+/** O que compõe um número: dígito, ponto de milhar e vírgula decimal. */
+const NUMBER_PART = /[0-9.,]/;
+
+/**
+ * Os operadores que a tela desenha diferente de como o parser os lê.
+ *
+ * Uma tabela só, percorrida nos dois sentidos: daqui saem o desenho das teclas
+ * e o texto do visor, e por ela o tokenizador volta ao símbolo canônico. Antes
+ * o `×` estava escrito em três lugares, e acrescentar um operador significava
+ * lembrar dos três.
+ */
+const OPERATOR_GLYPHS: ReadonlyArray<readonly [SymbolType, string]> = [
+  ["*", "×"],
+  ["/", "÷"],
+  ["-", "−"],
+];
+
+const GLYPH_TO_SYMBOL = new Map<string, SymbolType>([
+  ...OPERATOR_GLYPHS.map(([symbol, glyph]) => [glyph, symbol] as const),
+  // O `x` do teclado de quem aprendeu a multiplicar assim.
+  ["x", "*"] as const,
+  ["X", "*"] as const,
+]);
+
+const SYMBOL_TO_GLYPH = new Map<string, string>(OPERATOR_GLYPHS);
+
+const SYMBOLS = "+-*/%()";
+
+/**
+ * A conta como se lê na tela: `120*2+10%` vira `120×2+10%`.
+ *
+ * Mora aqui, junto do que faz o caminho de volta, e não no componente: são a
+ * mesma correspondência, e separadas elas saem de sincronia calada.
+ */
+export const toDisplayExpression = (source: string): string =>
+  Array.from(source)
+    .map((character) => SYMBOL_TO_GLYPH.get(character) ?? character)
+    .join("");
+
+/**
+ * O caractere pode entrar numa conta?
+ *
+ * É o que o teclado físico consulta antes de escrever. Sem isso, a lista de
+ * caracteres aceitos existiria duas vezes — aqui e num regex do componente —,
+ * e um operador novo entraria pelo botão mas não pela tecla.
+ */
+export const isCalcCharacter = (character: string): boolean =>
+  NUMBER_PART.test(character) ||
+  SYMBOLS.includes(character) ||
+  GLYPH_TO_SYMBOL.has(character);
+
+/**
+ * Número brasileiro para `number`.
+ *
+ * A ambiguidade real é o ponto sozinho: `1.200` é mil e duzentos para quem
+ * digita em reais, e 1,2 para o `Number`. A regra é a do país — havendo
+ * vírgula, todo ponto é milhar; sem vírgula, o ponto ainda é milhar quando
+ * separa exatamente três dígitos no fim, ou quando aparece mais de uma vez.
+ */
+const toNumber = (raw: string): number => {
+  let text: string = raw;
+
+  if (text.includes(",")) {
+    text = text.replace(/\./g, "").replace(/,/g, ".");
+  } else if ((text.match(/\./g) ?? []).length > 1 || /\d\.\d{3}$/.test(text)) {
+    text = text.replace(/\./g, "");
+  }
+
+  const parsed: number = Number(text);
+  if (text === "" || !Number.isFinite(parsed)) {
+    throw new CalcError(CalcErrorCode.INVALID_NUMBER);
+  }
+
+  return parsed;
+};
+
+const tokenize = (source: string): Token[] => {
+  const tokens: Token[] = [];
+  let index = 0;
+
+  while (index < source.length) {
+    const character: string = source[index];
+
+    if (character === " ") {
+      index += 1;
+      continue;
+    }
+
+    if (NUMBER_PART.test(character)) {
+      let end: number = index;
+      while (end < source.length && NUMBER_PART.test(source[end])) {
+        end += 1;
+      }
+      tokens.push({ type: "number", value: toNumber(source.slice(index, end)) });
+      index = end;
+      continue;
+    }
+
+    const symbol: string = GLYPH_TO_SYMBOL.get(character) ?? character;
+    if (SYMBOLS.includes(symbol)) {
+      tokens.push({ type: symbol as SymbolType });
+      index += 1;
+      continue;
+    }
+
+    throw new CalcError(CalcErrorCode.UNKNOWN_CHARACTER, character);
+  }
+
+  return tokens;
+};
+
+/**
+ * Um pedaço já resolvido da conta.
+ *
+ * `percent` marca o número que ainda espera o contexto do operador anterior: é
+ * o que faz `200+10%` valer 220 e `200*10%` valer 20 — a porcentagem da
+ * calculadora de bolso, que é a que quem lança despesa tem na cabeça.
+ */
+interface Operand {
+  value: number;
+  percent: boolean;
+}
+
+const parse = (tokens: Token[]): number => {
+  let position = 0;
+
+  const peek = (): Token | undefined => tokens[position];
+
+  const eat = (type: SymbolType): boolean => {
+    const token: Token | undefined = peek();
+    if (token && token.type === type) {
+      position += 1;
+      return true;
+    }
+    return false;
+  };
+
+  const primary = (): Operand => {
+    const token: Token | undefined = peek();
+    if (!token) {
+      throw new CalcError(CalcErrorCode.INCOMPLETE);
+    }
+
+    if (token.type === "number") {
+      position += 1;
+      return { value: token.value, percent: false };
+    }
+
+    if (token.type === "(") {
+      position += 1;
+      const inner: Operand = expression();
+      if (!eat(")")) {
+        throw new CalcError(CalcErrorCode.UNCLOSED_PAREN);
+      }
+      return { value: inner.value, percent: false };
+    }
+
+    // Sinal na frente do número: `-50` e `+50`.
+    if (token.type === "-") {
+      position += 1;
+      const operand: Operand = unary();
+      return { value: -operand.value, percent: operand.percent };
+    }
+    if (token.type === "+") {
+      position += 1;
+      return unary();
+    }
+
+    throw new CalcError(CalcErrorCode.INCOMPLETE);
+  };
+
+  const unary = (): Operand => {
+    const base: Operand = primary();
+    return eat("%") ? { value: base.value, percent: true } : base;
+  };
+
+  const term = (): Operand => {
+    let left: Operand = unary();
+
+    while (peek()?.type === "*" || peek()?.type === "/") {
+      const operator: SymbolType = (tokens[position] as SymbolToken).type;
+      position += 1;
+      const right: Operand = unary();
+      // Multiplicando ou dividindo, `10%` é simplesmente 0,1.
+      const factor: number = right.percent ? right.value / 100 : right.value;
+
+      if (operator === "/" && factor === 0) {
+        throw new CalcError(CalcErrorCode.DIVISION_BY_ZERO);
+      }
+
+      left = {
+        value: operator === "*" ? left.value * factor : left.value / factor,
+        percent: false,
+      };
+    }
+
+    return left;
+  };
+
+  const expression = (): Operand => {
+    let left: Operand = term();
+
+    while (peek()?.type === "+" || peek()?.type === "-") {
+      const operator: SymbolType = (tokens[position] as SymbolToken).type;
+      position += 1;
+      const right: Operand = term();
+      // Somando ou subtraindo, `10%` é 10% do que veio antes.
+      const delta: number = right.percent
+        ? (left.value * right.value) / 100
+        : right.value;
+
+      left = {
+        value: operator === "+" ? left.value + delta : left.value - delta,
+        percent: false,
+      };
+    }
+
+    return left;
+  };
+
+  const result: Operand = expression();
+  if (position < tokens.length) {
+    throw new CalcError(CalcErrorCode.TRAILING);
+  }
+
+  return result.value;
+};
+
+/**
+ * Resolve a conta e devolve o valor **já arredondado em centavos**.
+ *
+ * O arredondamento não é enfeite: `0,1+0,2` em ponto flutuante dá
+ * 0,30000000000000004, e o destino do resultado é uma coluna `decimal(12,2)`.
+ *
+ * Lança `CalcError` quando a conta não fecha — inclusive para texto vazio, que
+ * é `INCOMPLETE`.
+ */
+export const evaluateExpression = (source: string): number => {
+  const value: number = parse(tokenize(source));
+
+  if (!Number.isFinite(value)) {
+    throw new CalcError(CalcErrorCode.INVALID_NUMBER);
+  }
+
+  return Math.round((value + Number.EPSILON) * 100) / 100;
+};

package/src/_utils/format.ts

@@ -73,3 +73,24 @@ export function formatCurrencyBR(value: number | null | undefined): string {
   }
   return maskCurrencyBR(String(Math.round(value * 100)));
 }
+
+/**
+ * Real por extenso, com o símbolo: `R$ 1.234,56`.
+ *
+ * Diferente do `formatCurrencyBR`, que é a máscara do campo e por isso não tem
+ * símbolo — este é para leitura: extrato, cartão, eixo de gráfico, o visor da
+ * calculadora do `MoneyInput`. Escrever `"R$ " + formatCurrencyBR(v)` na tela
+ * parece a mesma coisa e não é: perde o espaço não-quebrável que o `Intl` põe
+ * entre símbolo e número, e o valor quebra linha no meio.
+ *
+ * Aceita texto porque `decimal` chega da API como string, e `Number(null)` é 0:
+ * o campo ausente vira `R$ 0,00` em vez de `R$ NaN`.
+ */
+export function formatMoneyBR(
+  value: number | string | null | undefined,
+): string {
+  return Number(value ?? 0).toLocaleString("pt-BR", {
+    style: "currency",
+    currency: "BRL",
+  });
+}

package/src/components/app-shell.tsx

@@ -178,6 +178,16 @@ const ADMIN_CHILDREN: NavItem[] = [
   },
   { key: "nav.rbac", href: "/rbac", icon: ShieldCheck, perm: "roles:read:any" },
   { key: "nav.logs", href: "/logs", icon: ScrollText, perm: "audit:read:any" },
+  // Logo abaixo do log de requisições, que é o vizinho natural: os dois contam
+  // o que aconteceu no sistema, um por chamada e outro por alteração de dado.
+  // Restrito a administradores — só quem tem audit:read-trail:any (só Super
+  // Admin) vê este item.
+  {
+    key: "nav.audit",
+    href: "/auditoria",
+    icon: History,
+    perm: "audit:read-trail:any",
+  },
   // Só aparece para quem opera a fila — em ambiente sem Redis ninguém tem a
   // permissão, e o item some sozinho.
   {
@@ -186,13 +196,6 @@ const ADMIN_CHILDREN: NavItem[] = [
     icon: ListChecks,
     perm: "queues:read:any",
   },
-  // Restrito a administradores — só quem tem audit:read-trail:any (só Super Admin) vê este item.
-  {
-    key: "nav.audit",
-    href: "/auditoria",
-    icon: History,
-    perm: "audit:read-trail:any",
-  },
 ];
 
 export interface AppShellProps {

package/src/components/ui/button.tsx

@@ -2,6 +2,7 @@
 
 import { Slot } from "@radix-ui/react-slot";
 import { cva, type VariantProps } from "class-variance-authority";
+import { Loader2 } from "lucide-react";
 import * as React from "react";
 
 import { cn } from "#core/lib/utils";
@@ -43,22 +44,54 @@ export interface ButtonProps
     React.ButtonHTMLAttributes<HTMLButtonElement>,
     VariantProps<typeof buttonVariants> {
   asChild?: boolean;
+  /**
+   * A ação está em curso: mostra o giro e recusa clique.
+   *
+   * As duas coisas juntas de propósito. Salvar sem sinal nenhum é o que faz
+   * clicar de novo, e clicar de novo é o que duplica o lançamento — desabilitar
+   * sem mostrar por quê parece que o botão quebrou. Quem passa `loading` não
+   * precisa lembrar de passar `disabled` também.
+   *
+   * Ignorado com `asChild`: ali o filho é que decide o que desenha.
+   */
+  loading?: boolean;
 }
 
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, size, asChild = false, ...props }, ref) => {
+  (
+    { className, variant, size, asChild = false, loading = false, children, ...props },
+    ref,
+  ) => {
     const Comp = asChild ? Slot : "button";
+
+    // O giro entra ANTES do conteúdo, no lugar onde o ícone do botão já ficava:
+    // aparecendo depois, o texto pula para a esquerda quando ele some.
+    const conteudo =
+      loading && !asChild ? (
+        <>
+          <Loader2 className="animate-spin" aria-hidden />
+          {children}
+        </>
+      ) : (
+        children
+      );
+
     return (
       <Comp
         className={cn(buttonVariants({ variant, size, className }))}
         ref={ref}
+        {...(asChild ? {} : { disabled: loading || props.disabled })}
+        // Quem usa leitor de tela não vê o giro: é o `aria-busy` que conta.
+        {...(loading && !asChild ? { "aria-busy": true } : {})}
         // `<button>` sem `type` nasce `submit`: dentro de um form, um botão que
         // só abre um modal acabava salvando o registro junto. Quem submete
         // declara `type="submit"` — o spread abaixo deixa isso sobrescrever.
         // Com `asChild` o filho pode não ser um `<button>`, então não força.
         {...(asChild ? {} : { type: "button" as const })}
         {...props}
-      />
+      >
+        {conteudo}
+      </Comp>
     );
   },
 );

package/src/components/ui/hover-tip.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import type { FocusEvent, JSX, MouseEvent, ReactNode } from "react";
+import { useState } from "react";
+import { createPortal } from "react-dom";
+
+export interface HoverTipProps {
+  /** O que o tooltip diz. Vazio não desenha nada. */
+  label: string;
+  children: ReactNode;
+}
+
+/** Onde o rótulo aparece na tela, em coordenada de viewport. */
+interface TipPosition {
+  x: number;
+  y: number;
+}
+
+/** A folga entre o gatilho e o rótulo. */
+const GAP = 6;
+
+/**
+ * O rótulo que aparece **na hora** ao passar o mouse.
+ *
+ * Existe pelo mesmo motivo do `HoverLabel` dos gráficos: o `title` do HTML só
+ * aparece depois de cerca de um segundo parado, e um segundo é tempo suficiente
+ * para quem passou o mouse concluir que não há nada ali e seguir em frente.
+ * Numa coluna de cinco ícones, isso é a diferença entre descobrir o que cada um
+ * faz e clicar para descobrir.
+ *
+ * Abre **embaixo**, e sai do documento por um portal com posição fixa. As duas
+ * decisões são a mesma: o `Table` do core envolve a tabela num `overflow-x-auto`
+ * e, quando um eixo rola, o navegador recorta o outro também — dentro da célula,
+ * o rótulo da última linha era cortado pela borda da tabela. Abrir à esquerda,
+ * como já se tentou, cabia na caixa mas cobria o conteúdo da própria linha: na
+ * lista de receitas, o "Recebido" do botão tapava o "Pendente" da situação, que
+ * é justamente o dado que se confere antes de clicar.
+ *
+ * O estado mora aqui dentro e guarda só a coordenada. Ele re-renderiza este
+ * componente e o rótulo — não a linha da tabela, que entra por `children` e
+ * chega pronta de fora.
+ */
+export const HoverTip = ({ label, children }: HoverTipProps): JSX.Element => {
+  const [position, setPosition] = useState<TipPosition | null>(null);
+
+  const show = (event: MouseEvent<HTMLElement> | FocusEvent<HTMLElement>): void => {
+    const box = event.currentTarget.getBoundingClientRect();
+
+    setPosition({ x: box.left + box.width / 2, y: box.bottom + GAP });
+  };
+
+  const hide = (): void => setPosition(null);
+
+  return (
+    <span
+      className="relative inline-flex"
+      onMouseEnter={show}
+      onMouseLeave={hide}
+      // Chegando por teclado o rótulo também aparece: quem navega com Tab
+      // precisa do mesmo texto que o mouse mostra.
+      onFocus={show}
+      onBlur={hide}
+    >
+      {children}
+      {label &&
+        position &&
+        createPortal(
+          <span
+            role="tooltip"
+            style={{ left: position.x, top: position.y }}
+            className="pointer-events-none fixed z-100 max-w-[90vw] -translate-x-1/2 whitespace-nowrap rounded-md border border-border bg-popover px-2 py-0.5 text-[11px] font-medium text-popover-foreground shadow-lg"
+          >
+            {label}
+          </span>,
+          document.body,
+        )}
+    </span>
+  );
+};

package/src/components/ui/index.ts

@@ -20,10 +20,12 @@ export * from "./filter-field";
 export * from "./filter-group";
 export * from "./filter-rule";
 export * from "./filter-sheet";
+export * from "./hover-tip";
 export * from "./image-upload";
 export * from "./input";
 export * from "./job-progress";
 export * from "./label";
+export * from "./money-input";
 export * from "./password-requirements";
 export * from "./popover";
 export * from "./row-actions";

package/src/components/ui/money-input.tsx

@@ -0,0 +1,328 @@
+"use client";
+
+import { Calculator, Delete } from "lucide-react";
+import type { JSX, KeyboardEvent } from "react";
+import { useRef, useState } from "react";
+
+import {
+  CalcError,
+  CalcErrorCode,
+  evaluateExpression,
+  isCalcCharacter,
+  toDisplayExpression,
+} from "#core/_utils/calc";
+import {
+  formatCurrencyBR,
+  formatMoneyBR,
+  maskCurrencyBR,
+  parseCurrencyBR,
+} from "#core/_utils/format";
+import { Button } from "#core/components/ui/button";
+import { Input } from "#core/components/ui/input";
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+  PopoverTrigger,
+} from "#core/components/ui/popover";
+import { useI18n } from "#core/contexts";
+import { cn } from "#core/lib/utils";
+
+export interface MoneyInputProps {
+  /** O valor já mascarado — `1.234,56`. É o que o formulário guarda. */
+  value: string;
+  onChange: (value: string) => void;
+  onBlur?: () => void;
+  name?: string;
+  id?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  /**
+   * Foca o campo ao montar.
+   *
+   * Existe porque num modal cujo primeiro campo é o valor — a meta do mês, o
+   * ajuste de saldo — o `DialogContent` entrega o foco ao botão de fechar do
+   * cabeçalho, e quem abriu para digitar um número precisa de um Tab antes de
+   * começar.
+   */
+  autoFocus?: boolean;
+}
+
+/**
+ * O maior valor que a máscara do core representa: onze dígitos, dois deles
+ * centavos. Passar disso não dá erro — `maskCurrencyBR` corta os dígitos que
+ * sobram e devolve outro número, calado. Por isso a calculadora recusa antes.
+ */
+const MAX_MASKED_VALUE = 999_999_999.99;
+
+/** O que uma tecla faz: escreve na conta, ou mexe no que já está escrito. */
+type KeyRole = "digit" | "operator" | "aux";
+
+interface CalcKey {
+  /**
+   * O que a tecla acrescenta à conta — e também o seu desenho, passado pelo
+   * `toDisplayExpression`: a tecla do `*` mostra `×` sem que o glifo precise
+   * ser escrito aqui de novo.
+   */
+  input?: string;
+  role: KeyRole;
+  /** Rótulo acessível e desenho da tecla que não escreve na conta. */
+  labelKey?: string;
+  label?: string;
+  action?: "clear" | "backspace";
+}
+
+const KEYS: readonly CalcKey[] = [
+  { role: "aux", label: "C", action: "clear", labelKey: "calculator.clear" },
+  { role: "aux", input: "(" },
+  { role: "aux", input: ")" },
+  { role: "operator", input: "/" },
+  { role: "digit", input: "7" },
+  { role: "digit", input: "8" },
+  { role: "digit", input: "9" },
+  { role: "operator", input: "*" },
+  { role: "digit", input: "4" },
+  { role: "digit", input: "5" },
+  { role: "digit", input: "6" },
+  { role: "operator", input: "-" },
+  { role: "digit", input: "1" },
+  { role: "digit", input: "2" },
+  { role: "digit", input: "3" },
+  { role: "operator", input: "+" },
+  { role: "operator", input: "%" },
+  { role: "digit", input: "0" },
+  { role: "digit", input: "," },
+  { role: "aux", action: "backspace", labelKey: "calculator.backspace" },
+];
+
+/** O resultado da conta, ou o motivo de ela não poder ser usada. */
+interface CalcOutcome {
+  value: number | null;
+  message: string | null;
+}
+
+/**
+ * Campo de dinheiro com calculadora — a máscara do core mais um lugar para
+ * fazer a conta antes de lançar o valor.
+ *
+ * A conta acontece num painel, e não no próprio campo, porque a máscara entra
+ * **pela direita**, como caixa de supermercado: cada tecla empurra o valor uma
+ * casa, e um `+` digitado ali seria descartado antes de virar operador.
+ *
+ * Vem do core e não de cada projeto porque campo de dinheiro é o mesmo em
+ * todos: sem ele aqui, cada sistema remonta o par `Input` + `maskCurrencyBR` à
+ * mão em cada formulário, e a segunda cópia é a que esquece de recusar o
+ * resultado negativo.
+ */
+export const MoneyInput = ({
+  value,
+  onChange,
+  onBlur,
+  name,
+  id,
+  placeholder,
+  disabled = false,
+  autoFocus = false,
+}: MoneyInputProps): JSX.Element => {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const [expression, setExpression] = useState("");
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  /**
+   * Traduz o erro do parser. O código vem do `calc.util`, que não conhece
+   * idioma nenhum — quem escolhe a frase é quem sabe quem está olhando.
+   */
+  const messageOf = (error: unknown): string => {
+    if (error instanceof CalcError) {
+      return t(`calculator.error.${error.code}`, {
+        character: error.character ?? "",
+      });
+    }
+    return t(`calculator.error.${CalcErrorCode.INCOMPLETE}`);
+  };
+
+  const outcome = ((): CalcOutcome => {
+    if (expression.trim() === "") {
+      return { value: null, message: null };
+    }
+
+    try {
+      const result: number = evaluateExpression(expression);
+
+      // A máscara não guarda sinal: um resultado negativo entraria no campo
+      // como positivo, e ninguém veria a troca acontecer.
+      if (result <= 0) {
+        return { value: null, message: t("calculator.error.notPositive") };
+      }
+      if (result > MAX_MASKED_VALUE) {
+        return { value: null, message: t("calculator.error.outOfRange") };
+      }
+
+      return { value: result, message: null };
+    } catch (error) {
+      return { value: null, message: messageOf(error) };
+    }
+  })();
+
+  /** Abrir semeia a conta com o que já está no campo, para somar em cima. */
+  const handleOpenChange = (next: boolean): void => {
+    if (next) {
+      setExpression(parseCurrencyBR(value) > 0 ? value : "");
+    }
+    setOpen(next);
+  };
+
+  const press = (key: CalcKey): void => {
+    if (key.action === "clear") {
+      setExpression("");
+      return;
+    }
+    if (key.action === "backspace") {
+      setExpression((current) => current.slice(0, -1));
+      return;
+    }
+    setExpression((current) => current + (key.input ?? ""));
+  };
+
+  const apply = (): void => {
+    if (outcome.value === null) {
+      return;
+    }
+    onChange(maskCurrencyBR(formatCurrencyBR(outcome.value)));
+    setOpen(false);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
+    const onButton: boolean =
+      event.target instanceof HTMLElement && event.target.tagName === "BUTTON";
+
+    // Com o foco numa tecla, o Enter é o clique dela — mexer nisso quebraria
+    // quem navega por Tab.
+    if (event.key === "Enter" && !onButton) {
+      event.preventDefault();
+      apply();
+      return;
+    }
+    if (event.key === "Backspace") {
+      event.preventDefault();
+      setExpression((current) => current.slice(0, -1));
+      return;
+    }
+    if (event.key.length === 1 && isCalcCharacter(event.key)) {
+      event.preventDefault();
+      // No teclado numérico o decimal é ponto; em reais, é vírgula.
+      setExpression((current) => current + (event.key === "." ? "," : event.key));
+    }
+  };
+
+  return (
+    <Popover open={open} onOpenChange={handleOpenChange}>
+      <PopoverAnchor asChild>
+        <div className="relative">
+          <Input
+            id={id}
+            name={name}
+            value={value}
+            onChange={(event) => onChange(maskCurrencyBR(event.target.value))}
+            onBlur={onBlur}
+            placeholder={placeholder}
+            disabled={disabled}
+            autoFocus={autoFocus}
+            prefix="R$"
+            inputMode="decimal"
+            className="pr-11"
+          />
+          <PopoverTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              size="iconSm"
+              disabled={disabled}
+              aria-label={t("calculator.open")}
+              className={cn(
+                "absolute right-1 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-primary",
+                open && "bg-primary/15 text-primary",
+              )}
+            >
+              <Calculator />
+            </Button>
+          </PopoverTrigger>
+        </div>
+      </PopoverAnchor>
+
+      <PopoverContent
+        ref={panelRef}
+        align="end"
+        aria-label={t("calculator.title")}
+        onKeyDown={handleKeyDown}
+        // O foco fica no painel, e não na primeira tecla: assim o Enter usa o
+        // valor em vez de apertar o "C".
+        onOpenAutoFocus={(event) => {
+          event.preventDefault();
+          panelRef.current?.focus();
+        }}
+        tabIndex={-1}
+        className="w-72"
+      >
+        <div className="flex min-h-14 flex-col justify-between gap-1 rounded-md border border-border bg-muted/50 px-3 py-1.5 text-right">
+          <span className="min-h-5 break-all font-mono text-xs text-muted-foreground">
+            {toDisplayExpression(expression)}
+          </span>
+          {outcome.message ? (
+            <span className="break-words text-xs text-destructive">{outcome.message}</span>
+          ) : (
+            <span className="break-all font-mono text-base font-medium tabular-nums">
+              {formatMoneyBR(outcome.value ?? 0)}
+            </span>
+          )}
+        </div>
+
+        <div className="mt-2 grid grid-cols-4 gap-1">
+          {KEYS.map((key, index) => (
+            <Button
+              key={key.label ?? key.action ?? index}
+              type="button"
+              variant={key.role === "aux" ? "outline" : "secondary"}
+              aria-label={key.labelKey ? t(key.labelKey) : undefined}
+              onClick={() => press(key)}
+              className={cn(
+                "h-8 px-0 font-mono text-sm",
+                key.role === "operator" && "text-primary",
+                key.role === "aux" && "text-muted-foreground",
+              )}
+            >
+              {key.label ?? (key.input ? toDisplayExpression(key.input) : <Delete />)}
+            </Button>
+          ))}
+        </div>
+
+        {/*
+          A dica saiu daqui e virou o `title` do botão: num notebook de 768px o
+          painel inteiro não cabe na altura disponível, e o `PopoverContent`
+          passa a rolar — o teclado de uma calculadora com barra de rolagem é
+          pior que uma dica a menos.
+        */}
+        <div className="mt-2 flex gap-1">
+          <Button
+            type="button"
+            variant="outline"
+            className="h-8 flex-1"
+            onClick={() => setOpen(false)}
+          >
+            {t("calculator.cancel")}
+          </Button>
+          <Button
+            type="button"
+            className="h-8 flex-1"
+            title={t("calculator.hint")}
+            disabled={outcome.value === null}
+            onClick={apply}
+          >
+            {t("calculator.apply")}
+          </Button>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+};

package/src/features/rbac/panels/catalog-panel.tsx

@@ -17,6 +17,7 @@ import {
   DialogHeader,
   DialogTitle,
   Field,
+  HoverTip,
   Input,
   RowActions,
 } from "#core/components/ui";
@@ -157,23 +158,29 @@ export function CatalogPanel({
         cell: ({ row }) => (
           <RowActions>
             {canUpdate && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                onClick={() => openEdit(row.original)}
-              >
-                <Pencil className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.edit")}>
+                <Button
+                  aria-label={t("common.edit")}
+                  variant="ghost"
+                  size="iconSm"
+                  onClick={() => openEdit(row.original)}
+                >
+                  <Pencil className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
             {canDelete && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                className="text-destructive"
-                onClick={() => removeItem(row.original)}
-              >
-                <Trash2 className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.delete")}>
+                <Button
+                  aria-label={t("common.delete")}
+                  variant="ghost"
+                  size="iconSm"
+                  className="text-destructive"
+                  onClick={() => removeItem(row.original)}
+                >
+                  <Trash2 className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
           </RowActions>
         ),

package/src/features/rbac/panels/groups-panel.tsx

@@ -18,6 +18,7 @@ import {
   DialogHeader,
   DialogTitle,
   Field,
+  HoverTip,
   Input,
   Label,
   RowActions,
@@ -188,23 +189,29 @@ export function GroupsPanel(): JSX.Element {
         cell: ({ row }) => (
           <RowActions>
             {hasPermission("groups:update:any") && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                onClick={() => openEdit(row.original)}
-              >
-                <Pencil className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.edit")}>
+                <Button
+                  aria-label={t("common.edit")}
+                  variant="ghost"
+                  size="iconSm"
+                  onClick={() => openEdit(row.original)}
+                >
+                  <Pencil className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
             {hasPermission("groups:delete:any") && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                className="text-destructive"
-                onClick={() => remove(row.original)}
-              >
-                <Trash2 className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.delete")}>
+                <Button
+                  aria-label={t("common.delete")}
+                  variant="ghost"
+                  size="iconSm"
+                  className="text-destructive"
+                  onClick={() => remove(row.original)}
+                >
+                  <Trash2 className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
           </RowActions>
         ),

package/src/features/rbac/panels/permissions-panel.tsx

@@ -16,6 +16,7 @@ import {
   DialogHeader,
   DialogTitle,
   Field,
+  HoverTip,
   Input,
   RowActions,
 } from "#core/components/ui";
@@ -118,23 +119,29 @@ export function PermissionsPanel(): JSX.Element {
         cell: ({ row }) => (
           <RowActions>
             {hasPermission("permissions:update:any") && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                onClick={() => openEdit(row.original)}
-              >
-                <Pencil className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.edit")}>
+                <Button
+                  aria-label={t("common.edit")}
+                  variant="ghost"
+                  size="iconSm"
+                  onClick={() => openEdit(row.original)}
+                >
+                  <Pencil className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
             {hasPermission("permissions:delete:any") && (
-              <Button
-                variant="ghost"
-                size="iconSm"
-                className="text-destructive"
-                onClick={() => remove(row.original)}
-              >
-                <Trash2 className="h-4 w-4" />
-              </Button>
+              <HoverTip label={t("common.delete")}>
+                <Button
+                  aria-label={t("common.delete")}
+                  variant="ghost"
+                  size="iconSm"
+                  className="text-destructive"
+                  onClick={() => remove(row.original)}
+                >
+                  <Trash2 className="h-4 w-4" />
+                </Button>
+              </HoverTip>
             )}
           </RowActions>
         ),

package/src/features/users/users-screen.tsx

@@ -26,6 +26,7 @@ import {
   CreateButton,
   DataTable,
   DataTableFeatures,
+  HoverTip,
   RowActions,
 } from "#core/components/ui";
 import { useAuth, useI18n } from "#core/contexts";
@@ -152,74 +153,82 @@ export function UsersScreen(): JSX.Element {
           return (
             <RowActions>
               {canUpdate && (
-                <Button
-                  variant="ghost"
-                  size="iconSm"
-                  title={t("common.edit")}
-                  onClick={() => openEdit(item)}
-                >
-                  <Pencil className="h-4 w-4" />
-                </Button>
+                <HoverTip label={t("common.edit")}>
+                  <Button
+                    variant="ghost"
+                    size="iconSm"
+                    aria-label={t("common.edit")}
+                    onClick={() => openEdit(item)}
+                  >
+                    <Pencil className="h-4 w-4" />
+                  </Button>
+                </HoverTip>
               )}
               {canInvite && (
-                <Button
-                  variant="ghost"
-                  size="iconSm"
-                  title={t("users.sendFirstAccessLink")}
-                  onClick={() => {
-                    void confirm({
-                      title: t("users.sendFirstAccessLink"),
-                      description: item.email,
-                      confirmLabel: t("common.send"),
-                    }).then((ok) => {
-                      if (ok) {
-                        void u.sendFirstAccessLink(item.id);
-                      }
-                    });
-                  }}
-                >
-                  <MailPlus className="h-4 w-4" />
-                </Button>
+                <HoverTip label={t("users.sendFirstAccessLink")}>
+                  <Button
+                    variant="ghost"
+                    size="iconSm"
+                    aria-label={t("users.sendFirstAccessLink")}
+                    onClick={() => {
+                      void confirm({
+                        title: t("users.sendFirstAccessLink"),
+                        description: item.email,
+                        confirmLabel: t("common.send"),
+                      }).then((ok) => {
+                        if (ok) {
+                          void u.sendFirstAccessLink(item.id);
+                        }
+                      });
+                    }}
+                  >
+                    <MailPlus className="h-4 w-4" />
+                  </Button>
+                </HoverTip>
               )}
               {canReset && (
-                <Button
-                  variant="ghost"
-                  size="iconSm"
-                  title={t("users.sendPasswordResetLink")}
-                  onClick={() => {
-                    void confirm({
-                      title: t("users.sendPasswordResetLink"),
-                      description: item.email,
-                      confirmLabel: t("common.send"),
-                    }).then((ok) => {
-                      if (ok) {
-                        void u.sendPasswordResetLink(item.id);
-                      }
-                    });
-                  }}
-                >
-                  <KeyRound className="h-4 w-4" />
-                </Button>
+                <HoverTip label={t("users.sendPasswordResetLink")}>
+                  <Button
+                    variant="ghost"
+                    size="iconSm"
+                    aria-label={t("users.sendPasswordResetLink")}
+                    onClick={() => {
+                      void confirm({
+                        title: t("users.sendPasswordResetLink"),
+                        description: item.email,
+                        confirmLabel: t("common.send"),
+                      }).then((ok) => {
+                        if (ok) {
+                          void u.sendPasswordResetLink(item.id);
+                        }
+                      });
+                    }}
+                  >
+                    <KeyRound className="h-4 w-4" />
+                  </Button>
+                </HoverTip>
               )}
               {canReset2fa && item.twoFactorEnabled && (
-                <Button
-                  variant="ghost"
-                  size="iconSm"
-                  title={t("users.resetTwoFactor")}
-                  onClick={() => {
-                    void confirm({
-                      title: t("users.resetTwoFactor"),
-                      description: item.name,
-                      destructive: true,
-                    }).then((ok) => {
-                      if (ok) {
-                        void u.resetTwoFactor(item.id);
-                      }
-                    });
-                  }}
-                >
-                  <ShieldOff className="h-4 w-4" />
-                </Button>
+                <HoverTip label={t("users.resetTwoFactor")}>
+                  <Button
+                    variant="ghost"
+                    size="iconSm"
+                    aria-label={t("users.resetTwoFactor")}
+                    onClick={() => {
+                      void confirm({
+                        title: t("users.resetTwoFactor"),
+                        description: item.name,
+                        destructive: true,
+                      }).then((ok) => {
+                        if (ok) {
+                          void u.resetTwoFactor(item.id);
+                        }
+                      });
+                    }}
+                  >
+                    <ShieldOff className="h-4 w-4" />
+                  </Button>
+                </HoverTip>
               )}
               {canDeactivate && (
                 <Button
@@ -238,26 +247,28 @@ export function UsersScreen(): JSX.Element {
                 </Button>
               )}
               {canDelete && (
-                <Button
-                  variant="ghost"
-                  size="iconSm"
-                  className="text-destructive"
-                  title={t("common.delete")}
-                  onClick={() => {
-                    void confirm({
-                      title: t("common.delete"),
-                      description: item.name,
-                      confirmLabel: t("common.delete"),
-                      destructive: true,
-                    }).then((ok) => {
-                      if (ok) {
-                        void u.remove(item.id);
-                      }
-                    });
-                  }}
-                >
-                  <Trash2 className="h-4 w-4" />
-                </Button>
+                <HoverTip label={t("common.delete")}>
+                  <Button
+                    variant="ghost"
+                    size="iconSm"
+                    className="text-destructive"
+                    aria-label={t("common.delete")}
+                    onClick={() => {
+                      void confirm({
+                        title: t("common.delete"),
+                        description: item.name,
+                        confirmLabel: t("common.delete"),
+                        destructive: true,
+                      }).then((ok) => {
+                        if (ok) {
+                          void u.remove(item.id);
+                        }
+                      });
+                    }}
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                </HoverTip>
               )}
             </RowActions>
           );

package/src/i18n/messages/en.ts

@@ -265,6 +265,25 @@ export const en: Messages = {
     markAllRead: "Mark all as read",
     empty: "No notifications",
   },
+  calculator: {
+    open: "Open the calculator",
+    title: "Calculator",
+    apply: "Use value",
+    cancel: "Cancel",
+    clear: "Clear",
+    backspace: "Delete last character",
+    hint: "Enter uses the value · Esc closes",
+    error: {
+      unknownCharacter: "“{character}” cannot be used in a calculation",
+      invalidNumber: "That is not a number",
+      incomplete: "The calculation is unfinished",
+      unclosedParen: "A parenthesis was left open",
+      trailing: "There is something after the end of the calculation",
+      divisionByZero: "Cannot divide by zero",
+      notPositive: "The result must be greater than zero",
+      outOfRange: "The result is above the highest value this field takes",
+    },
+  },
   common: {
     save: "Save",
     optional: "optional",

package/src/i18n/messages/pt.ts

@@ -268,6 +268,25 @@ export const pt = {
     markAllRead: "Marcar todas como lidas",
     empty: "Nenhuma notificação",
   },
+  calculator: {
+    open: "Abrir a calculadora",
+    title: "Calculadora",
+    apply: "Usar valor",
+    cancel: "Cancelar",
+    clear: "Limpar a conta",
+    backspace: "Apagar o último caractere",
+    hint: "Enter usa o valor · Esc fecha",
+    error: {
+      unknownCharacter: "Não dá para usar “{character}” numa conta",
+      invalidNumber: "Esse número não existe",
+      incomplete: "Falta terminar a conta",
+      unclosedParen: "Falta fechar o parêntese",
+      trailing: "Sobrou algo depois do fim da conta",
+      divisionByZero: "Não dá para dividir por zero",
+      notPositive: "O resultado precisa ser maior que zero",
+      outOfRange: "O resultado passa do maior valor que o campo aceita",
+    },
+  },
   common: {
     save: "Salvar",
     optional: "opcional",

package/src/index.ts

@@ -63,6 +63,7 @@ export { anyOrTeam } from "#core/_utils/permission";
 // segunda cópia é sempre a que esquece o teto de dígitos.
 export {
   formatCurrencyBR,
+  formatMoneyBR,
   maskCurrencyBR,
   maskPhoneBR,
   parseCurrencyBR,