rl-core-front 0.14.3 → 0.15.0

package/src/hooks/use-shortcut.ts

@@ -0,0 +1,267 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+/** Janela entre as duas batidas, em milissegundos. */
+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 abrem o formulário de cadastro, em toda tela que tiver um.
+ *
+ * Moram aqui, e não em cada tela, porque atalho que muda de tela para tela não
+ * é atalho — é armadilha.
+ *
+ * São **duas** porque teclado não é um só: `\` fica em lugares diferentes
+ * conforme o layout (e em alguns exige combinação), enquanto `1` está na mesma
+ * posição em qualquer um. Quem tem a barra usa a barra; quem não tem, usa o
+ * número. Nenhuma das duas compete com atalho de navegador.
+ */
+export const CREATE_SHORTCUT_KEYS = ["1", "\\"] as const;
+
+/** Como o atalho se apresenta ao usuário. */
+export const CREATE_SHORTCUT_LABEL = "11";
+
+/**
+ * A combinação que amplia e restaura o modal aberto: `Alt` + `Enter`.
+ *
+ * Foram descartadas, nesta ordem e por estes motivos:
+ *
+ * - **`+` sozinho** e **`Shift + E`**: produzem caractere. Dentro de um modal,
+ *   que é feito de campos, ou o atalho some ou ele dispara junto com a
+ *   digitação — não há terceira saída.
+ * - **`Ctrl + +` e `Ctrl + Shift + +`**: são a mesma combinação física do zoom
+ *   do navegador (`+` sai de `Shift` + `=` nos teclados brasileiro e
+ *   americano). O navegador resolve o zoom antes de a página ver a tecla, então
+ *   a página não tem como vencer.
+ *
+ * `Alt + Enter` não escreve nada, não é atalho de navegador, e é a convenção de
+ * maximizar que as pessoas já conhecem de outros programas. E `Enter` chega
+ * como `"Enter"` em qualquer layout — não depende de onde o teclado põe o
+ * símbolo.
+ */
+export const EXPAND_SHORTCUT_KEY = "Enter";
+
+/** Como ele se apresenta ao usuário. */
+export const EXPAND_SHORTCUT_LABEL = "Alt + Enter";
+
+export interface ShortcutOptions {
+  /**
+   * Exige duas batidas seguidas dentro de meio segundo.
+   *
+   * É o que permite usar uma tecla comum (`\`) sem modificador: sozinha ela é
+   * caractere, e duas vezes seguidas fora de um campo de texto não é coisa que
+   * alguém digite sem querer.
+   */
+  double?: boolean;
+  /** Desliga o atalho sem tirar o hook da tela — útil enquanto a lista carrega. */
+  enabled?: boolean;
+  /**
+   * Exige `Alt` (ou `Option`, no Mac) junto.
+   *
+   * Ausente, o `Alt` é recusado — é tecla de menu do sistema, e um atalho de
+   * uma tecla só não deve disparar com ela pressionada.
+   */
+  alt?: boolean;
+  /**
+   * Exige `Ctrl` (ou `Cmd`, no Mac) junto.
+   *
+   * Aceita os dois porque é a mesma tecla na cabeça de quem usa — obrigar
+   * `Ctrl` no Mac faria o atalho parecer quebrado ali. Ausente, os dois são
+   * recusados: sem isso, `Ctrl + tecla` dispararia o atalho de uma tecla só.
+   */
+  ctrl?: boolean;
+  /**
+   * O que fazer com o `Shift`: `true` exige, `false` recusa, ausente ignora.
+   *
+   * **Ignorar é o padrão, e é o certo para a maioria dos casos**, porque o
+   * caractere já carrega a informação: `+` no teclado brasileiro sai com
+   * `Shift`, no numérico sem — e nos dois `event.key` é `"+"`. Recusar o
+   * `Shift` bloquearia metade dos teclados; exigi-lo bloquearia a outra metade.
+   *
+   * Declare `true` só quando o modificador for parte do atalho (`Shift + E`), e
+   * `false` quando a tecla sem ele significar outra coisa.
+   */
+  shift?: boolean;
+  /**
+   * Deixa o atalho valer também com o cursor dentro de um campo.
+   *
+   * O padrão é ceder a vez: numa listagem, `11` tem de poder ser digitado. Mas
+   * o atalho que pertence ao modal precisa valer em qualquer lugar dele, como
+   * o `Esc` — e o modal é feito de campos.
+   *
+   * **A tecla não é engolida nesse caso.** `Esc` não produz caractere; `+`
+   * produz, e bloqueá-lo impediria de escrever `+55` num telefone. Aqui o
+   * atalho dispara *e* o caractere é digitado.
+   */
+  allowWhileTyping?: boolean;
+  /**
+   * Deixa o atalho valer **com** um modal aberto.
+   *
+   * O padrão é o contrário: com um formulário na tela, a tecla é dele. Isto é
+   * para o atalho que pertence ao próprio modal — ele nasce e morre junto do
+   * modal, então quem monta o hook já é quem tem o direito à tecla.
+   */
+  allowInDialog?: boolean;
+}
+
+/**
+ * Atalho de teclado de uma tela.
+ *
+ * Contraparte do `Esc` que o modal já entende: se uma tecla fecha, outra abre.
+ * A tela diz qual tecla e o que fazer; o resto — quando **não** disparar — é
+ * daqui:
+ *
+ * - **Campo de texto ganha**, salvo com `allowWhileTyping`. Digitar `11` num
+ *   input é digitar `11`, não abrir modal. Vale para `contenteditable` também.
+ * - **Modal aberto bloqueia.** Com um formulário na tela, a tecla pertence a
+ *   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`.
+ *
+ * ```tsx
+ * // Na listagem: duas batidas abrem o cadastro.
+ * useShortcut(CREATE_SHORTCUT_KEYS, openCreate, { double: true });
+ *
+ * // Dentro do modal: a tecla é dele, então `allowInDialog`.
+ * useShortcut(EXPAND_SHORTCUT_KEY, alternarTamanho, {
+ *   alt: true,
+ *   allowInDialog: true,
+ *   allowWhileTyping: true,
+ * });
+ * ```
+ */
+export function useShortcut(
+  keys: string | readonly string[],
+  handler: () => void,
+  options: ShortcutOptions = {},
+): void {
+  const {
+    double = false,
+    enabled = true,
+    alt = false,
+    ctrl = false,
+    shift,
+    allowInDialog = false,
+    allowWhileTyping = false,
+  } = options;
+
+  // Serializado para o efeito não se reinscrever a cada render quando a tela
+  // passa um array literal — `["1", "\\"]` é um objeto novo toda vez.
+  const keyList = typeof keys === "string" ? [keys] : keys;
+  const keySignature = keyList.join("\u0000");
+
+  // O handler entra por ref para o efeito não se reinscrever a cada render —
+  // a tela costuma passar uma arrow nova toda vez. A escrita vai num efeito
+  // próprio: mexer em ref durante o render é o que o React proíbe.
+  const handlerRef = useRef(handler);
+
+  useEffect(() => {
+    handlerRef.current = handler;
+  }, [handler]);
+
+  /**
+   * Qual tecla bateu por último, e quando.
+   *
+   * A tecla entra junto do instante porque o duplo é da **mesma** tecla: sem
+   * isso, digitar `1` e logo `\` valeria como duas batidas e abriria o modal
+   * sem ninguém ter pedido.
+   */
+  const lastPressRef = useRef<{ key: string; at: number }>({ key: "", at: 0 });
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const accepted = keySignature.split("\u0000");
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (!accepted.includes(event.key)) {
+        return;
+      }
+      if (event.altKey !== alt) {
+        return;
+      }
+      if (event.ctrlKey || event.metaKey ? !ctrl : ctrl) {
+        return;
+      }
+      if (shift !== undefined && event.shiftKey !== shift) {
+        return;
+      }
+      const typing = isTyping(event.target);
+
+      if (typing && !allowWhileTyping) {
+        return;
+      }
+      if (!allowInDialog && hasOpenDialog()) {
+        return;
+      }
+
+      if (double) {
+        const now = Date.now();
+        const previous = lastPressRef.current;
+        lastPressRef.current = { key: event.key, at: now };
+
+        if (
+          previous.key !== event.key ||
+          now - previous.at > DOUBLE_PRESS_WINDOW_MS
+        ) {
+          return;
+        }
+        // Zera para a terceira batida não valer como um segundo disparo.
+        lastPressRef.current = { key: "", at: 0 };
+      }
+
+      // Só depois de decidir que dispara: impedir o padrão antes disso
+      // engoliria a tecla de quem só queria digitá-la.
+      //
+      // Com modificador não há esse risco — `Alt + Enter` não escreve nada —, e
+      // aí engolir é necessário: sem isso o `Enter` ainda enviaria o formulário
+      // junto com o ampliar. Sem modificador e dentro de um campo, a tecla é
+      // das duas coisas ao mesmo tempo, e não se impede nada.
+      if (!typing || alt || ctrl) {
+        event.preventDefault();
+      }
+      handlerRef.current();
+    };
+
+    // **Fase de captura, e não de bolha.** Atalho global precisa ver a tecla
+    // antes de quem está no caminho: um componente entre o campo e a `window`
+    // que chame `stopPropagation()` no `keydown` — coisa comum em combobox,
+    // editor e tabela — engoliria o atalho, e o sintoma seria "funciona numa
+    // tela e não funciona na outra", que é o pior tipo de bug para achar.
+    window.addEventListener("keydown", onKeyDown, true);
+    return () => window.removeEventListener("keydown", onKeyDown, true);
+  }, [
+    keySignature,
+    double,
+    enabled,
+    alt,
+    ctrl,
+    shift,
+    allowInDialog,
+    allowWhileTyping,
+  ]);
+}
+
+const isTyping = (target: EventTarget | null): boolean => {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  return TYPING_TAGS.has(target.tagName) || target.isContentEditable;
+};
+
+/**
+ * Há um modal aberto?
+ *
+ * Pela marca que o Radix deixa no DOM, e não por um contexto próprio: o modal
+ * pode estar em qualquer lugar da árvore (ele vive num portal), e um contexto
+ * obrigaria toda tela a envolver o conteúdo num provider só para o atalho
+ * saber disso.
+ */
+const hasOpenDialog = (): boolean =>
+  document.querySelector('[role="dialog"][data-state="open"]') !== null;

package/src/i18n/messages/en.ts

@@ -12,6 +12,8 @@ export const en: Messages = {
     logs: "Logs",
     audit: "Audit",
     queues: "Queues",
+    shortcuts: "Shortcuts",
+    settings: "Settings",
   },
   logs: {
     outcomeSuccess: "Success",
@@ -109,6 +111,41 @@ export const en: Messages = {
     stateCompleted: "Completed",
     stateFailed: "Failed",
     stateDelayed: "Delayed",
+    queue: "Queue",
+    queueJobs: "General",
+    queueExports: "Reports",
+    payload: "Payload",
+  },
+  shortcuts: {
+    title: "Keyboard shortcuts",
+    subtitle:
+      "What you can do without leaving the keyboard. Shortcuts work on any screen that has the matching action.",
+    or: "or",
+    twice: "twice",
+    create: {
+      name: "Open the create form",
+      where: "On any listing with a create button.",
+      caveat: "Does not fire inside a text field or while a dialog is open",
+    },
+    expand: {
+      name: "Expand the dialog",
+      where:
+        "With a dialog open, toggles between normal and expanded size. Works anywhere in the dialog, like Esc.",
+      caveat: "Works in any field, and does not submit the form",
+      note: "On a Mac, Alt is the Option key (⌥) — most keyboards print both labels on it.",
+    },
+    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",
+    },
+    close: {
+      name: "Close the dialog",
+      where: "Closes the open dialog, same as the close button.",
+      caveat: "A changed form asks for confirmation before leaving",
+    },
+    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.",
   },
   table: {
     columns: "Columns",
@@ -122,6 +159,8 @@ export const en: Messages = {
     nextPage: "Next page",
     empty: "No records",
     emptyFiltered: "No records match this filter",
+    reorder: "Drag to reorder",
+    reorderSorted: "Clear the column sorting to drag rows",
   },
   filters: {
     button: "Filters",
@@ -209,6 +248,7 @@ export const en: Messages = {
     clear: "Clear",
     no: "No",
     actions: "Actions",
+    shortcutHint: "Shortcut: {keys}",
     loading: "Loading...",
     description: "Description",
     language: "Language",

package/src/i18n/messages/pt.ts

@@ -10,6 +10,8 @@ export const pt = {
     logs: "Logs",
     audit: "Auditoria",
     queues: "Filas",
+    shortcuts: "Atalhos",
+    settings: "Configurações",
   },
   logs: {
     outcomeSuccess: "Sucesso",
@@ -111,6 +113,41 @@ export const pt = {
     stateCompleted: "Concluídos",
     stateFailed: "Falhos",
     stateDelayed: "Agendados",
+    queue: "Fila",
+    queueJobs: "Geral",
+    queueExports: "Relatórios",
+    payload: "Conteúdo",
+  },
+  shortcuts: {
+    title: "Atalhos de teclado",
+    subtitle:
+      "O que dá para fazer sem tirar a mão do teclado. Os atalhos valem em qualquer tela que tenha a ação correspondente.",
+    or: "ou",
+    twice: "duas vezes",
+    create: {
+      name: "Abrir cadastro",
+      where: "Em qualquer listagem que tenha o botão de cadastrar.",
+      caveat: "Não dispara dentro de um campo de texto nem com um modal aberto",
+    },
+    expand: {
+      name: "Ampliar o modal",
+      where:
+        "Com um modal aberto, alterna entre o tamanho normal e o ampliado. Vale em qualquer lugar do modal, como o Esc.",
+      caveat: "Funciona em qualquer campo, e não envia o formulário junto",
+      note: "No Mac, o Alt é a tecla Option (⌥) — em boa parte dos teclados ela vem escrita das duas formas.",
+    },
+    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",
+    },
+    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",
+    },
+    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.",
   },
   table: {
     columns: "Colunas",
@@ -124,6 +161,9 @@ export const pt = {
     nextPage: "Próxima página",
     empty: "Nenhum registro",
     emptyFiltered: "Nenhum registro para este filtro",
+    reorder: "Arraste para reordenar",
+    reorderSorted:
+      "Limpe a ordenação por coluna para arrastar as linhas",
   },
   filters: {
     button: "Filtros",
@@ -211,6 +251,7 @@ export const pt = {
     clear: "Limpar",
     no: "Não",
     actions: "Ações",
+    shortcutHint: "Atalho: {keys}",
     loading: "Carregando...",
     description: "Descrição",
     language: "Idioma",

package/src/index.ts

@@ -33,6 +33,7 @@ export {
 export { RbacScreen } from "#core/features/rbac/rbac-screen";
 export { ForgotPasswordScreen } from "#core/features/recovery/forgot-password-screen";
 export { ResetPasswordScreen } from "#core/features/recovery/reset-password-screen";
+export { ShortcutsScreen } from "#core/features/shortcuts/shortcuts-screen";
 export { UsersScreen } from "#core/features/users/users-screen";
 
 // ---------------------------------------------------------------------------
@@ -70,6 +71,7 @@ export {
 // ---------------------------------------------------------------------------
 // Hooks de listagem, requisição e filtro
 // ---------------------------------------------------------------------------
+export type { CreateButtonProps } from "#core/components/ui/create-button";
 export type { UseColumnVisibilityResult } from "#core/hooks/use-column-visibility";
 export { useColumnVisibility } from "#core/hooks/use-column-visibility";
 export type {
@@ -97,6 +99,14 @@ export { useLatestRequest } from "#core/hooks/use-latest-request";
 export type { UseListQueryResult } from "#core/hooks/use-list-query";
 export { useListQuery } from "#core/hooks/use-list-query";
 export type { RunOptions, UseRequestResult } from "#core/hooks/use-request";
+export type { ShortcutOptions } from "#core/hooks/use-shortcut";
+export {
+  CREATE_SHORTCUT_KEYS,
+  CREATE_SHORTCUT_LABEL,
+  EXPAND_SHORTCUT_KEY,
+  EXPAND_SHORTCUT_LABEL,
+  useShortcut,
+} from "#core/hooks/use-shortcut";
 // 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";