rl-core-front 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "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/dialog.tsx

@@ -8,6 +8,7 @@ import { Button, type ButtonProps } from "#core/components/ui/button";
 import {
   EXPAND_SHORTCUT_KEY,
   EXPAND_SHORTCUT_LABEL,
+  SUBMIT_SHORTCUT_KEY,
   useShortcut,
 } from "#core/hooks/use-shortcut";
 import { cn } from "#core/lib/utils";
@@ -428,10 +429,32 @@ const DialogContent = React.forwardRef<
 );
 DialogContent.displayName = DialogPrimitive.Content.displayName;
 
+/**
+ * O modal aberto por cima de todos os outros.
+ *
+ * O Radix pendura cada modal no fim do `body`, então o último no DOM é o que
+ * está por cima. É como o formulário sabe se o atalho é dele: com uma
+ * confirmação aberta sobre o cadastro, os dois têm formulário e só o de cima
+ * pode responder ao `Ctrl + Enter`.
+ */
+const topmostDialog = (): Element | null => {
+  const open = document.querySelectorAll('[role="dialog"][data-state="open"]');
+
+  return open[open.length - 1] ?? null;
+};
+
 /**
  * Corpo do modal como formulário — é o que faz o `Enter` submeter.
  * O `preventDefault` fica aqui porque, sem ele, o Enter recarrega a página.
  *
+ * E o `Ctrl + Enter` envia de **qualquer lugar** do modal. O Enter sozinho só
+ * envia a partir de um campo de texto: num select ele abre a lista, numa
+ * caixa de marcar ele marca, num texto longo ele quebra a linha — e quem está
+ * com o foco ali ficava sem saída pelo teclado. O atalho passa pelo mesmo
+ * caminho do botão Salvar (`requestSubmit` com ele como `submitter`), então
+ * a validação do HTML roda igual e o botão desativado — salvando, ou sem
+ * permissão — continua mandando.
+ *
  * O `DialogFooter` é separado dos demais filhos e fica **fora da área
  * rolável**, ainda dentro do `<form>`. As duas metades importam: fora do
  * scroll porque `sticky` deixa o conteúdo correr por baixo dos botões — com
@@ -449,10 +472,33 @@ const DialogForm = React.forwardRef<
   const items = React.Children.toArray(children);
   const footerAt = indexOfChild(items, "DialogFooter");
   const hasFooter = footerAt >= 0;
+  const formRef = React.useRef<HTMLFormElement>(null);
+
+  const submitFromAnywhere = (): void => {
+    const form = formRef.current;
+
+    if (!form || form.closest('[role="dialog"]') !== topmostDialog()) {
+      return;
+    }
+
+    const submitter = form.querySelector<HTMLButtonElement>('button[type="submit"]');
+
+    if (submitter?.disabled) {
+      return;
+    }
+
+    form.requestSubmit(submitter ?? undefined);
+  };
+
+  useShortcut(SUBMIT_SHORTCUT_KEY, submitFromAnywhere, {
+    ctrl: true,
+    allowInDialog: true,
+    allowWhileTyping: true,
+  });
 
   return (
     <form
-      ref={ref}
+      ref={mergeRefs(ref, formRef)}
       onSubmit={(e) => {
         e.preventDefault();
         onSubmit?.(e);
@@ -478,6 +524,19 @@ const DialogForm = React.forwardRef<
 });
 DialogForm.displayName = "DialogForm";
 
+/** O ref de quem usa e o nosso, no mesmo elemento. */
+const mergeRefs =
+  <T,>(...refs: React.Ref<T>[]) =>
+  (node: T | null): void => {
+    for (const ref of refs) {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        (ref as React.MutableRefObject<T | null>).current = node;
+      }
+    }
+  };
+
 const DialogTitle = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Title>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>

package/src/components/ui/help-hint.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { HelpCircle } from "lucide-react";
+import type { JSX } from "react";
+
+import { HoverTip } from "#core/components/ui/hover-tip";
+
+export interface HelpHintProps {
+  /** O texto que explica a tela. */
+  text: string;
+  /** Como o botão se apresenta a quem usa leitor de tela. */
+  label: string;
+}
+
+/**
+ * A explicação da tela, atrás de um ícone.
+ *
+ * O texto vivia solto acima da tabela, e ali ele é lido uma vez e depois vira
+ * uma linha que empurra a lista para baixo todo dia. No ícone ele continua ao
+ * alcance de quem chegou agora, sem ocupar espaço de quem já sabe.
+ *
+ * É um `HoverTip` com o botão de interrogação dentro: abre ao passar o mouse
+ * — ler uma explicação não deveria custar um clique — e também no foco, que é
+ * como ela chega a quem está no teclado.
+ */
+export const HelpHint = ({ text, label }: HelpHintProps): JSX.Element => (
+  <HoverTip label={text}>
+    <button
+      type="button"
+      aria-label={label}
+      className="flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <HelpCircle className="h-4 w-4" />
+    </button>
+  </HoverTip>
+);

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

@@ -1,79 +1,105 @@
 "use client";
 
-import type { FocusEvent, JSX, MouseEvent, ReactNode } from "react";
-import { useState } from "react";
-import { createPortal } from "react-dom";
+import type { JSX, ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
+
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+} from "#core/components/ui/popover";
+import { cn } from "#core/lib/utils";
 
 export interface HoverTipProps {
   /** O que o tooltip diz. Vazio não desenha nada. */
   label: string;
   children: ReactNode;
+  /** Classe extra do painel — para alargar quando o texto é uma explicação. */
+  className?: string;
 }
 
-/** 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;
+/**
+ * Quanto o fechar espera, em milissegundos.
+ *
+ * Entre o gatilho e o painel existe a folga do `sideOffset`: fechando no
+ * primeiro `mouseleave`, o texto sumia no meio do caminho de quem foi até ele
+ * para ler inteiro.
+ */
+const CLOSE_GRACE_MS = 150;
 
 /**
  * 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.
+ * Existe porque 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.
+ *
+ * É o `Popover` do core por baixo, e por isso tem a cara dele — o mesmo
+ * painel da explicação de tela (`HelpHint`) e do calendário: um desenho só
+ * para tudo que flutua. Do Radix vêm o portal (o painel não é cortado pela
+ * borda da tabela nem do modal) e a virada para cima quando não cabe embaixo.
  *
- * 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.
+ * Ancorado, e não gatilhado: um `PopoverTrigger` faria do botão de editar um
+ * "abre um diálogo" para o leitor de tela. Aqui quem abre é o mouse e o foco,
+ * e o painel se apresenta como `tooltip`.
  *
- * 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.
+ * Abre também no foco — quem navega com Tab precisa do mesmo texto que o
+ * mouse mostra — e não rouba o foco ao abrir: aberto pelo mouse, ele levaria
+ * o cursor de teclado para longe do botão que a pessoa nem clicou.
  */
-export const HoverTip = ({ label, children }: HoverTipProps): JSX.Element => {
-  const [position, setPosition] = useState<TipPosition | null>(null);
+export const HoverTip = ({ label, children, className }: HoverTipProps): JSX.Element => {
+  const [open, setOpen] = useState(false);
+  const closing = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const show = (event: MouseEvent<HTMLElement> | FocusEvent<HTMLElement>): void => {
-    const box = event.currentTarget.getBoundingClientRect();
+  const show = (): void => {
+    if (closing.current) {
+      clearTimeout(closing.current);
+      closing.current = null;
+    }
+    setOpen(true);
+  };
 
-    setPosition({ x: box.left + box.width / 2, y: box.bottom + GAP });
+  const hide = (): void => {
+    closing.current = setTimeout(() => setOpen(false), CLOSE_GRACE_MS);
   };
 
-  const hide = (): void => setPosition(null);
+  // O timer pendente não pode sobreviver ao componente: a linha da tabela
+  // some ao excluir, e o `setOpen` chegaria num componente desmontado.
+  useEffect(
+    () => () => {
+      if (closing.current) {
+        clearTimeout(closing.current);
+      }
+    },
+    [],
+  );
 
   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>
+    <Popover open={open && label !== ""} onOpenChange={setOpen}>
+      <PopoverAnchor asChild>
+        <span
+          className="relative inline-flex"
+          onMouseEnter={show}
+          onMouseLeave={hide}
+          onFocus={show}
+          onBlur={hide}
+        >
+          {children}
+        </span>
+      </PopoverAnchor>
+      <PopoverContent
+        role="tooltip"
+        side="bottom"
+        align="center"
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        onCloseAutoFocus={(event) => event.preventDefault()}
+        onMouseEnter={show}
+        onMouseLeave={hide}
+        className={cn("max-w-xs text-xs leading-relaxed text-muted-foreground", className)}
+      >
+        {label}
+      </PopoverContent>
+    </Popover>
   );
 };

package/src/components/ui/index.ts

@@ -21,6 +21,7 @@ export * from "./filter-field";
 export * from "./filter-group";
 export * from "./filter-rule";
 export * from "./filter-sheet";
+export * from "./help-hint";
 export * from "./hover-tip";
 export * from "./image-upload";
 export * from "./input";
@@ -28,6 +29,7 @@ export * from "./job-progress";
 export * from "./label";
 export * from "./money-input";
 export * from "./password-requirements";
+export * from "./period-nav";
 export * from "./popover";
 export * from "./row-actions";
 export * from "./segmented-control";

package/src/components/ui/period-nav.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { JSX } from "react";
+
+import { Button } from "#core/components/ui/button";
+import { useI18n } from "#core/contexts";
+import { NEXT_ARROW_KEY, PREVIOUS_ARROW_KEY, useShortcut } from "#core/hooks/use-shortcut";
+import { cn } from "#core/lib/utils";
+
+export interface PeriodNavProps {
+  /** O período em exibição, já formatado — "setembro de 2026", "2026". */
+  label: string;
+  onPrevious: () => void;
+  onNext: () => void;
+  /** O nome do gesto, para o leitor de tela: "Mês anterior". Ausente, "Período anterior". */
+  previousLabel?: string;
+  /** Idem: "Próximo mês". Ausente, "Próximo período". */
+  nextLabel?: string;
+  /**
+   * Classe do rótulo — é onde se fixa a largura.
+   *
+   * Fixa, e não do tamanho do texto: sem isso "março" e "setembro" empurram
+   * o botão da direita para lugares diferentes, e a seta que a pessoa ia
+   * clicar sai de baixo do mouse ao trocar o mês.
+   */
+  labelClassName?: string;
+  /** Desliga os dois botões e o atalho, enquanto a tela carrega. */
+  disabled?: boolean;
+}
+
+/**
+ * Anda de período — mês, ano — na tela que tem um só para tudo.
+ *
+ * Os dois botões e, junto deles, as setas do teclado: `←` volta, `→` avança.
+ * Existe como componente pelo mesmo motivo do `CreateButton`: quem põe o
+ * seletor ganha o atalho no mesmo gesto, e tela nova nasce com ele em vez de
+ * herdá-lo por disciplina.
+ *
+ * A seta é solta — sem `Alt`, que é o "voltar" do navegador no Windows —, e
+ * vale com o foco em qualquer lugar da tela, inclusive numa aba: as abas do
+ * core não andam por seta solta justamente para a tecla ter um dono só
+ * (`Alt` + seta é o delas). O `useShortcut` ainda cede a vez a menu, lista
+ * e slider, que andam por setas dentro de si.
+ *
+ * Sem dica nos botões: o atalho está na tela de atalhos, e o painel a cada
+ * passada do mouse atrapalhava mais do que ensinava.
+ *
+ * ```tsx
+ * <PeriodNav
+ *   label={formatMonthLong(month)}
+ *   onPrevious={() => setMonth(shiftMonth(month, -1))}
+ *   onNext={() => setMonth(shiftMonth(month, 1))}
+ *   previousLabel={t("finance.month.previous")}
+ *   nextLabel={t("finance.month.next")}
+ *   labelClassName="w-40"
+ * />
+ * ```
+ */
+export const PeriodNav = ({
+  label,
+  onPrevious,
+  onNext,
+  previousLabel,
+  nextLabel,
+  labelClassName,
+  disabled = false,
+}: PeriodNavProps): JSX.Element => {
+  const { t } = useI18n();
+  const previousText = previousLabel ?? t("common.previousPeriod");
+  const nextText = nextLabel ?? t("common.nextPeriod");
+
+  useShortcut(PREVIOUS_ARROW_KEY, onPrevious, { enabled: !disabled });
+  useShortcut(NEXT_ARROW_KEY, onNext, { enabled: !disabled });
+
+  return (
+    <div className="flex items-center gap-1">
+      <Button
+        variant="outline"
+        size="iconSm"
+        aria-label={previousText}
+        disabled={disabled}
+        onClick={onPrevious}
+      >
+        <ChevronLeft className="h-4 w-4" />
+      </Button>
+      <span
+        className={cn("text-center text-sm font-medium tabular-nums", labelClassName)}
+        aria-live="polite"
+      >
+        {label}
+      </span>
+      <Button
+        variant="outline"
+        size="iconSm"
+        aria-label={nextText}
+        disabled={disabled}
+        onClick={onNext}
+      >
+        <ChevronRight className="h-4 w-4" />
+      </Button>
+    </div>
+  );
+};

package/src/components/ui/tab-shortcuts.tsx

@@ -2,76 +2,50 @@
 
 import type { JSX } from "react";
 
-import { MAX_TAB_SHORTCUTS, useShortcut } from "#core/hooks/use-shortcut";
+import {
+  NEXT_ARROW_KEY,
+  PREVIOUS_ARROW_KEY,
+  useShortcut,
+} from "#core/hooks/use-shortcut";
 
 export interface TabShortcutsProps {
   /** Os valores das abas, na ordem em que aparecem. */
   values: readonly string[];
+  /** A aba aberta — é dela que se conta a anterior e a seguinte. */
+  value: string;
   onSelect: (value: string) => void;
 }
 
 /**
- * O rótulo do atalho de uma aba, para a dica que a própria aba mostra.
+ * `Alt` + `←`/`→` troca de aba. Não desenha nada.
  *
- * `⌥` no Mac e `Alt` no resto: é a mesma tecla física, mas ninguém procura
- * "Alt" num teclado da Apple. Fora do navegador (SSR) responde `Alt`, que é o
- * que o primeiro render precisa escrever — a correção vem no cliente.
- */
-export const tabShortcutLabel = (index: number): string => {
-  const mac =
-    typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
-
-  return `${mac ? "⌥" : "Alt"} ${index + 1}`;
-};
-
-/**
- * Um atalho, uma instância.
+ * Com `Alt`, e não a seta solta: a seta solta é o atalho de período da tela
+ * (`PeriodNav`), e uma tecla com dois donos é o conflito que só aparece na
+ * tela onde os dois existem. `Alt` + número, que já foi o atalho daqui, pedia
+ * decorar a posição de cada aba; a seta só pede saber para que lado ir.
  *
- * O `useShortcut` aceita uma lista de teclas mas chama o handler sem dizer
- * **qual** disparou. Com um componente por aba, cada instância fica com a sua
- * tecla e a sua ação, e nenhum hook roda dentro de laço — que é o que a regra
- * dos hooks proíbe.
- */
-const TabShortcut = ({
-  digit,
-  value,
-  onSelect,
-}: {
-  digit: number;
-  value: string;
-  onSelect: (value: string) => void;
-}): null => {
-  /*
-    Por `code`, e não por `key`: no macOS o `Option` + número não produz o
-    número — `⌥1` chega como `¡` e `⌥2` como `™`. Declarado como "1", o atalho
-    funcionava no Windows e falhava no Mac, que é o pior desfecho possível.
-  */
-  useShortcut(`Digit${digit}`, () => onSelect(value), { alt: true, byCode: true });
-
-  return null;
-};
-
-/**
- * `Alt` + `1..9` troca de aba. Não desenha nada.
- *
- * Com `Alt`, e não a tecla sozinha: os números precisam continuar sendo
- * digitáveis, e o `1` sem modificador já é o atalho de abrir cadastro — dois
- * donos para a mesma tecla é o conflito que só aparece na tela onde os dois
- * existem.
+ * Dá a volta: da última, `→` vai para a primeira. É o que o `Ctrl + Tab` do
+ * navegador faz, e é o que a mão espera de uma fila.
  *
- * A ordem das abas é a fonte da numeração: passe a mesma lista que desenha os
+ * A ordem das abas é a fonte da sequência: passe a mesma lista que desenha os
  * gatilhos, e não uma cópia. Duas fontes para a mesma ordem é o jeito garantido
- * de `Alt + 3` abrir a aba errada no dia em que alguém reordenar a barra.
+ * de a seta pular para a aba errada no dia em que alguém reordenar a barra.
  */
-export const TabShortcuts = ({ values, onSelect }: TabShortcutsProps): JSX.Element => (
-  <>
-    {values.slice(0, MAX_TAB_SHORTCUTS).map((value, index) => (
-      <TabShortcut
-        key={value}
-        digit={index + 1}
-        value={value}
-        onSelect={onSelect}
-      />
-    ))}
-  </>
-);
+export const TabShortcuts = ({ values, value, onSelect }: TabShortcutsProps): JSX.Element => {
+  const step = (offset: number): void => {
+    if (values.length === 0) {
+      return;
+    }
+    // Aba desconhecida (a URL trouxe um valor que já não existe) conta como a
+    // primeira: a seta leva a uma aba real em vez de a lugar nenhum.
+    const current = Math.max(values.indexOf(value), 0);
+    const next = (current + offset + values.length) % values.length;
+
+    onSelect(values[next]);
+  };
+
+  useShortcut(PREVIOUS_ARROW_KEY, () => step(-1), { alt: true });
+  useShortcut(NEXT_ARROW_KEY, () => step(1), { alt: true });
+
+  return <></>;
+};

package/src/components/ui/tabs.tsx

@@ -30,13 +30,33 @@ const TabsList = React.forwardRef<
 ));
 TabsList.displayName = TabsPrimitive.List.displayName;
 
+/** As teclas com que o Radix andaria de aba — e que aqui ficam para a tela. */
+const ARROW_KEYS = new Set(["ArrowLeft", "ArrowRight"]);
+
+/**
+ * A aba do core **não anda por seta**.
+ *
+ * O Radix trocaria de aba com `←`/`→` enquanto o foco está numa delas — e a
+ * aba já tem atalho, `Alt` + número, que funciona de qualquer lugar. Deixar
+ * os dois fazia a seta ter dois donos na mesma tela: depois de clicar numa
+ * aba, `→` trocava a aba; clicando no fundo, trocava o mês. Impedir o padrão
+ * aqui, antes do handler do Radix, devolve a seta ao atalho da tela.
+ */
 const TabsTrigger = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Trigger>,
   React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
->(({ className, ...props }, ref) => (
+>(({ className, onKeyDown, ...props }, ref) => (
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(TRACK_ITEM_CLASS, className)}
+    // O Radix só trata a tecla se ninguém impediu o padrão antes: o
+    // `onKeyDown` de quem usa continua valendo, e o nosso vem em seguida.
+    onKeyDown={(event) => {
+      onKeyDown?.(event);
+      if (ARROW_KEYS.has(event.key)) {
+        event.preventDefault();
+      }
+    }}
     {...props}
   />
 ));

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

@@ -1,11 +1,12 @@
 "use client";
 
 import {
+  ArrowLeftRight,
+  CalendarRange,
   CornerDownLeft,
   Keyboard,
   Maximize2,
   PlusSquare,
-  Rows3,
   XSquare,
 } from "lucide-react";
 import type { JSX } from "react";
@@ -17,9 +18,12 @@ import {
 } from "#core/features/shortcuts/components/shortcut-card";
 import {
   ALT_KEY_LABELS,
+  ARROW_KEY_LABELS,
+  ARROW_KEYS_LABEL,
   CREATE_SHORTCUT_KEYS,
+  CTRL_KEY_LABELS,
   EXPAND_SHORTCUT_KEY,
-  TAB_SHORTCUT_DIGITS,
+  SUBMIT_SHORTCUT_KEY,
 } from "#core/hooks/use-shortcut";
 
 /**
@@ -45,10 +49,10 @@ const SHORTCUTS: Shortcut[] = [
     name: "shortcuts.tabs.name",
     // `Alt` e `⌥` são a mesma tecla: viram duas combinações e o card escreve
     // "ou" entre elas, em vez de a diferença virar nota de rodapé.
-    combos: ALT_KEY_LABELS.map((alt) => [alt, TAB_SHORTCUT_DIGITS]),
+    combos: ALT_KEY_LABELS.map((alt) => [alt, ARROW_KEYS_LABEL]),
     where: "shortcuts.tabs.where",
     caveat: "shortcuts.tabs.caveat",
-    icon: Rows3,
+    icon: ArrowLeftRight,
   },
   {
     name: "shortcuts.expand.name",
@@ -57,9 +61,23 @@ const SHORTCUTS: Shortcut[] = [
     caveat: "shortcuts.expand.caveat",
     icon: Maximize2,
   },
+  {
+    name: "shortcuts.period.name",
+    // Uma seta para cada lado: são dois atalhos, e o card escreve "ou" entre
+    // eles como faz com as duas grafias do Alt.
+    combos: ARROW_KEY_LABELS.map((key) => [key]),
+    where: "shortcuts.period.where",
+    caveat: "shortcuts.period.caveat",
+    icon: CalendarRange,
+  },
   {
     name: "shortcuts.submit.name",
-    combos: [["Enter"]],
+    // O Enter sozinho é o submit do HTML; com Ctrl (⌘ no Mac) é o nosso, que
+    // vale de qualquer campo do modal.
+    combos: [
+      [SUBMIT_SHORTCUT_KEY],
+      ...CTRL_KEY_LABELS.map((ctrl) => [ctrl, SUBMIT_SHORTCUT_KEY]),
+    ],
     where: "shortcuts.submit.where",
     caveat: "shortcuts.submit.caveat",
     icon: CornerDownLeft,

package/src/hooks/use-shortcut.ts

@@ -8,6 +8,49 @@ const DOUBLE_PRESS_WINDOW_MS = 500;
 /** Onde a tecla é texto, e não comando. */
 const TYPING_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"]);
 
+/** As teclas que andam dentro de um widget — e que ele espera receber. */
+const NAVIGATION_KEYS = new Set([
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "Home",
+  "End",
+]);
+
+/**
+ * Os widgets que usam as setas para andar por dentro de si.
+ *
+ * Menus, listas de opções, rádios, sliders e grades seguem o padrão ARIA de
+ * foco itinerante: a seta troca o item focado. Com o foco num deles, a tecla
+ * é do widget — um atalho global de seta que também disparasse andaria o
+ * menu **e** o período no mesmo aperto.
+ *
+ * A aba **não** está aqui de propósito: o `Tabs` do core desliga a seta
+ * solta (a aba anda com `Alt` + seta), para `←`/`→` ter um dono só na tela.
+ *
+ * Por `closest`, e não pelo alvo: a opção do select é um item dentro do
+ * `listbox`, e a célula é um botão dentro do `grid`.
+ */
+const NAVIGATION_WIDGET_SELECTOR = [
+  "menu",
+  "menubar",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "listbox",
+  "option",
+  "radiogroup",
+  "radio",
+  "slider",
+  "spinbutton",
+  "grid",
+  "tree",
+  "treeitem",
+]
+  .map((role) => `[role="${role}"]`)
+  .join(", ");
+
 /**
  * As teclas que abrem o formulário de cadastro, em toda tela que tiver um.
  *
@@ -47,6 +90,26 @@ export const EXPAND_SHORTCUT_KEY = "Enter";
 /** Como ele se apresenta ao usuário. */
 export const EXPAND_SHORTCUT_LABEL = "Alt + Enter";
 
+/**
+ * A tecla que envia o formulário de qualquer lugar do modal, com `Ctrl`.
+ *
+ * O `Enter` sozinho já envia — é o submit implícito do HTML —, mas só de um
+ * campo de texto: num select ele abre a lista, numa caixa de marcar ele marca,
+ * num texto longo ele quebra a linha. `Ctrl + Enter` (`⌘ + Enter` no Mac) é
+ * a convenção de "enviar mesmo assim" que chat e editor já ensinaram, e não
+ * escreve nada em lugar nenhum.
+ */
+export const SUBMIT_SHORTCUT_KEY = "Enter";
+
+/**
+ * O modificador do `Ctrl`, escrito das duas formas que os teclados usam.
+ *
+ * `Ctrl` e `⌘` **não** são a mesma tecla física, mas são a mesma na cabeça
+ * de quem usa — e o hook aceita as duas por `ctrl: true`. A tela de atalhos
+ * mostra as duas pelo mesmo motivo do `Alt`/`⌥`.
+ */
+export const CTRL_KEY_LABELS = ["Ctrl", "⌘"] as const;
+
 /**
  * O modificador do `Alt`, escrito das duas formas que os teclados usam.
  *
@@ -57,15 +120,24 @@ export const EXPAND_SHORTCUT_LABEL = "Alt + Enter";
 export const ALT_KEY_LABELS = ["Alt", "⌥"] as const;
 
 /**
- * Quantas abas o atalho numera.
+ * As setas — as duas teclas de "anterior" e "seguinte" do sistema.
+ *
+ * Soltas, andam de período (mês, ano) na tela que tem um seletor; com `Alt`,
+ * andam de aba. A tecla é a mesma e o modificador diz o quê: a seta solta não
+ * escreve nada e não é atalho de navegador, e o que ela faz por conta própria
+ * — andar dentro de menus e listas — o hook respeita cedendo a vez.
  *
- * Nove porque `Alt + 0` não segue a sequência, e porque ninguém conta abas além
- * disso sem olhar.
+ * `Alt + ←` é o "voltar" do navegador no Windows; o hook impede o padrão
+ * quando o atalho dispara, e fora de uma tela com abas a tecla segue livre.
  */
-export const MAX_TAB_SHORTCUTS = 9;
+export const PREVIOUS_ARROW_KEY = "ArrowLeft";
+export const NEXT_ARROW_KEY = "ArrowRight";
 
-/** Como o atalho de abas se apresenta: `Alt` + `1…9`. */
-export const TAB_SHORTCUT_DIGITS = `1…${MAX_TAB_SHORTCUTS}`;
+/** Como as setas se apresentam, uma para cada lado. */
+export const ARROW_KEY_LABELS = ["←", "→"] as const;
+
+/** As duas setas num rótulo só, para o atalho que usa qualquer uma delas. */
+export const ARROW_KEYS_LABEL = "← →";
 
 export interface ShortcutOptions {
   /**
@@ -162,6 +234,9 @@ export interface ShortcutOptions {
  *   ele — senão o atalho abriria um segundo por cima do primeiro.
  * - **Modificador não pedido cancela.** `Ctrl`/`Cmd`/`Alt` + a tecla costuma ser
  *   atalho do navegador ou do sistema; quem quiser um deles declara `ctrl`.
+ * - **Seta com o foco num widget que anda por setas é dele.** Menu, lista,
+ *   rádio, slider e grade trocam o item focado com `←`/`→`; o atalho global
+ *   de seta não dispara ali.
  *
  * ```tsx
  * // Na listagem: duas batidas abrem o cadastro.
@@ -244,6 +319,9 @@ export function useShortcut(
       if (typing && !allowWhileTyping) {
         return;
       }
+      if (isNavigatingWidget(event)) {
+        return;
+      }
       if (!allowInDialog && hasOpenDialog()) {
         return;
       }
@@ -304,6 +382,20 @@ const isTyping = (target: EventTarget | null): boolean => {
   return TYPING_TAGS.has(target.tagName) || target.isContentEditable;
 };
 
+/**
+ * A tecla é de navegação e o foco está num widget que a consome?
+ *
+ * Checado aqui, e não por `event.defaultPrevented`, porque o hook ouve na
+ * fase de captura: quando ele vê a tecla, o widget ainda não a tratou.
+ */
+const isNavigatingWidget = (event: KeyboardEvent): boolean => {
+  if (!NAVIGATION_KEYS.has(event.key) || !(event.target instanceof HTMLElement)) {
+    return false;
+  }
+
+  return event.target.closest(NAVIGATION_WIDGET_SELECTOR) !== null;
+};
+
 /**
  * Há um modal aberto?
  *

package/src/i18n/messages/en.ts

@@ -145,7 +145,7 @@ export const en: Messages = {
     tabs: {
       name: "Switch tab",
       where:
-        "On any screen with tabs, the number opens the tab in that position — 1 is the first.",
+        "On any screen with tabs: the left arrow goes to the previous tab, the right one to the next — and from the last it wraps to the first.",
       caveat: "Does not fire inside a text field or with a modal open",
     },
     expand: {
@@ -156,16 +156,24 @@ export const en: Messages = {
     },
     submit: {
       name: "Submit the form",
-      where: "With a create dialog open, saves without clicking.",
-      caveat: "Inside a long text field, Enter adds a line break",
+      where:
+        "With a create dialog open, saves without clicking. Enter alone submits from a text field; with Ctrl it submits from anywhere in the dialog — a select, a checkbox or a long text, where Enter alone opens, toggles or adds a line break.",
+      caveat: "With the Save button disabled, neither one submits",
     },
     close: {
       name: "Close the dialog",
       where: "Closes the open dialog, same as the close button.",
       caveat: "A changed form asks for confirmation before leaving",
     },
+    period: {
+      name: "Change the period",
+      where:
+        "On a screen with a month or year selector at the top: the left arrow goes back one period, the right one moves forward.",
+      caveat:
+        "Does not fire inside a text field, with a dialog open, or with focus on a tab, list or calendar — there the arrow is theirs",
+    },
     footer:
-      "Two keys open the create form because keyboards differ: the backslash moves around depending on the layout, while the number is always in the same place.",
+      "Two keys open the create form because keyboards differ: the backslash moves around depending on the layout, while the number is always in the same place. The arrows do two things and Alt tells which: alone they change the period, with Alt they switch tabs.",
   },
   export: {
     label: "Export",
@@ -306,6 +314,8 @@ export const en: Messages = {
     no: "No",
     actions: "Actions",
     shortcutHint: "Shortcut: {keys}",
+    previousPeriod: "Previous period",
+    nextPeriod: "Next period",
     loading: "Loading...",
     description: "Description",
     language: "Language",

package/src/i18n/messages/pt.ts

@@ -147,7 +147,7 @@ export const pt = {
     tabs: {
       name: "Trocar de aba",
       where:
-        "Em qualquer tela com abas, o número abre a aba naquela posição — 1 é a primeira.",
+        "Em qualquer tela com abas: a seta para a esquerda vai para a aba anterior, a da direita para a seguinte — e da última volta para a primeira.",
       caveat: "Não dispara dentro de um campo de texto nem com um modal aberto",
     },
     expand: {
@@ -158,16 +158,24 @@ export const pt = {
     },
     submit: {
       name: "Enviar o formulário",
-      where: "Com um modal de cadastro aberto, salva sem precisar clicar.",
-      caveat: "Dentro de um campo de texto longo, o Enter quebra a linha",
+      where:
+        "Com um modal de cadastro aberto, salva sem precisar clicar. O Enter sozinho envia a partir de um campo de texto; com Ctrl envia de qualquer lugar do modal — de um select, de uma caixa de marcar ou de um texto longo, onde o Enter sozinho abre, marca ou quebra a linha.",
+      caveat: "Com o botão Salvar desativado, nenhum dos dois envia",
     },
     close: {
       name: "Fechar o modal",
       where: "Fecha o modal aberto, como o botão de fechar.",
       caveat: "Um formulário alterado pede confirmação antes de sair",
     },
+    period: {
+      name: "Mudar o período",
+      where:
+        "Na tela que tem um seletor de mês ou ano no topo: a seta para a esquerda volta um período, a da direita avança.",
+      caveat:
+        "Não dispara dentro de um campo de texto, com um modal aberto, nem com o foco numa aba, lista ou calendário — ali a seta é deles",
+    },
     footer:
-      "Duas teclas para abrir o cadastro porque o teclado não é um só: a barra invertida muda de lugar conforme o layout, e o número está sempre na mesma posição. Já o atalho de ampliar leva Alt porque precisa valer dentro dos campos — e uma tecla que escreve não pode servir de comando ali.",
+      "Duas teclas para abrir o cadastro porque o teclado não é um só: a barra invertida muda de lugar conforme o layout, e o número está sempre na mesma posição. As setas fazem duas coisas e o Alt diz qual: soltas andam de período, com Alt andam de aba. Já o atalho de ampliar leva Alt porque precisa valer dentro dos campos — e uma tecla que escreve não pode servir de comando ali.",
   },
   export: {
     label: "Exportar",
@@ -309,6 +317,8 @@ export const pt = {
     no: "Não",
     actions: "Ações",
     shortcutHint: "Atalho: {keys}",
+    previousPeriod: "Período anterior",
+    nextPeriod: "Próximo período",
     loading: "Carregando...",
     description: "Descrição",
     language: "Idioma",

package/src/index.ts

@@ -113,12 +113,16 @@ export type { RunOptions, UseRequestResult } from "#core/hooks/use-request";
 export type { ShortcutOptions } from "#core/hooks/use-shortcut";
 export {
   ALT_KEY_LABELS,
+  ARROW_KEY_LABELS,
+  ARROW_KEYS_LABEL,
   CREATE_SHORTCUT_KEYS,
   CREATE_SHORTCUT_LABEL,
+  CTRL_KEY_LABELS,
   EXPAND_SHORTCUT_KEY,
   EXPAND_SHORTCUT_LABEL,
-  MAX_TAB_SHORTCUTS,
-  TAB_SHORTCUT_DIGITS,
+  NEXT_ARROW_KEY,
+  PREVIOUS_ARROW_KEY,
+  SUBMIT_SHORTCUT_KEY,
   useShortcut,
 } from "#core/hooks/use-shortcut";
 export type { UseTabStateOptions, UseTabStateResult } from "#core/hooks/use-tab-state";