rl-core-front 0.19.5 → 0.19.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-front",
-  "version": "0.19.5",
+  "version": "0.19.7",
   "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/column-visibility-modal.tsx

@@ -81,7 +81,7 @@ export function ColumnVisibilityModal({
           {t("table.columnsHint")}
         </p>
 
-        <div className="flex max-h-[55vh] flex-col divide-y divide-border overflow-y-auto">
+        <div className="flex max-h-[55vh] flex-col divide-y divide-border overflow-y-auto overscroll-contain">
           <div className="flex items-center justify-between py-3">
             <span className="text-sm font-semibold">{t("table.columns")}</span>
             <Switch checked={areAllVisible} onCheckedChange={toggleAll} />

package/src/components/ui/combobox.tsx

@@ -422,7 +422,7 @@ export function Combobox({
          * campo sem cobri-lo.
          */
         className={cn(
-          "max-h-[min(18rem,var(--radix-dropdown-menu-content-available-height))] w-(--radix-dropdown-menu-trigger-width) overflow-y-auto p-1",
+          "max-h-[min(18rem,var(--radix-dropdown-menu-content-available-height))] w-(--radix-dropdown-menu-trigger-width) overflow-y-auto overscroll-contain p-1",
           !multiple && "data-[side=bottom]:-mt-(--radix-dropdown-menu-trigger-height)",
         )}
         align="start"

package/src/components/ui/data-table.tsx

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

package/src/components/ui/dialog.tsx

@@ -515,7 +515,7 @@ const DialogForm = React.forwardRef<
           vertical cortava a borda de baixo do último campo — que é o que
           aparece em todo modal com um campo colado no rodapé.
           `-m-1` devolve o recuo para o conteúdo seguir alinhado. */}
-      <div className="-m-1 flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-1 [scrollbar-width:thin]">
+      <div className="-m-1 flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto overscroll-contain p-1">
         {hasFooter ? items.slice(0, footerAt) : items}
       </div>
       {hasFooter && items.slice(footerAt)}

package/src/components/ui/field.tsx

@@ -6,13 +6,31 @@ interface FieldProps {
   label?: string;
   error?: string;
   htmlFor?: string;
+  /**
+   * Marca o rótulo com o "*" de obrigatório.
+   *
+   * Fica no rótulo, e não no controle, porque é o único lugar comum a todos
+   * eles: `Input`, `Combobox`, `MoneyInput` e `DatePicker` desenham a caixa de
+   * um jeito cada um, e a marca precisa aparecer no mesmo ponto nos quatro.
+   */
+  required?: boolean;
   children: React.ReactNode;
 }
 
-export function Field({ label, error, htmlFor, children }: FieldProps): JSX.Element {
+export function Field({
+  label,
+  error,
+  htmlFor,
+  required,
+  children,
+}: FieldProps): JSX.Element {
   return (
     <div className="space-y-1.5">
-      {label && <Label htmlFor={htmlFor}>{label}</Label>}
+      {label && (
+        <Label htmlFor={htmlFor} required={required}>
+          {label}
+        </Label>
+      )}
       {children}
       {error && <p className="text-xs font-medium text-destructive">{error}</p>}
     </div>

package/src/components/ui/filter-field.tsx

@@ -140,7 +140,7 @@ export function FilterFieldControl({
       <fieldset className="space-y-2">
         <legend className="text-sm font-medium">{label}</legend>
         {field.options?.length ? (
-          <div className="max-h-44 space-y-2 overflow-y-auto rounded-md border border-border p-3">
+          <div className="max-h-44 space-y-2 overflow-y-auto overscroll-contain rounded-md border border-border p-3">
             {field.options.map((option) => (
               <label
                 key={option.value}

package/src/components/ui/label.tsx

@@ -5,10 +5,23 @@ import * as React from "react";
 
 import { cn } from "#core/lib/utils";
 
+export interface LabelProps
+  extends React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> {
+  /**
+   * Campo obrigatório: acrescenta o "*" vermelho depois do texto.
+   *
+   * A marca é só visual (`aria-hidden`) — quem usa leitor de tela ouve a
+   * obrigatoriedade do próprio controle, então o campo também precisa do
+   * `required`/`aria-required`. Um asterisco lido em voz alta no meio do
+   * rótulo não diz nada; o atributo no controle diz.
+   */
+  required?: boolean;
+}
+
 const Label = React.forwardRef<
   React.ElementRef<typeof LabelPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
->(({ className, ...props }, ref) => (
+  LabelProps
+>(({ className, required, children, ...props }, ref) => (
   <LabelPrimitive.Root
     ref={ref}
     className={cn(
@@ -16,7 +29,14 @@ const Label = React.forwardRef<
       className,
     )}
     {...props}
-  />
+  >
+    {children}
+    {required && (
+      <span aria-hidden className="ml-0.5 text-destructive">
+        *
+      </span>
+    )}
+  </LabelPrimitive.Root>
 ));
 Label.displayName = LabelPrimitive.Root.displayName;
 

package/src/components/ui/popover.tsx

@@ -45,7 +45,7 @@ const PopoverContent = React.forwardRef<
         // com a última linha rente ao fim da tela.
         collisionPadding={8}
         className={cn(
-          "z-50 max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-xl border border-border bg-popover p-3 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+          "z-50 max-h-(--radix-popover-content-available-height) overflow-y-auto overscroll-contain rounded-xl border border-border bg-popover p-3 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
           className,
         )}
         {...props}

package/src/components/ui/sheet.tsx

@@ -66,7 +66,7 @@ const SheetBody = ({
   className,
   ...props
 }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element => (
-  <div className={cn("flex-1 overflow-y-auto", className)} {...props} />
+  <div className={cn("flex-1 overflow-y-auto overscroll-contain", className)} {...props} />
 );
 SheetBody.displayName = "SheetBody";
 

package/src/features/login/components/login-form.tsx

@@ -46,7 +46,7 @@ export function LoginForm({
       onSubmit={handleSubmit((d) => onSubmit(d.email, d.password))}
       className="flex flex-col gap-4"
     >
-      <Field label={t("auth.email")} error={errors.email?.message}>
+      <Field label={t("auth.email")} error={errors.email?.message} required>
         <Input
           type="email"
           autoComplete="email"
@@ -55,7 +55,7 @@ export function LoginForm({
           {...register("email")}
         />
       </Field>
-      <Field label={t("auth.password")} error={errors.password?.message}>
+      <Field label={t("auth.password")} error={errors.password?.message} required>
         <PasswordField
           autoComplete="current-password"
           autoFocus={!!defaultEmail}

package/src/features/login/components/two-factor-setup.tsx

@@ -64,7 +64,7 @@ export function TwoFactorSetup({
         onSubmit={handleSubmit((d) => onConfirm(d.code))}
         className="flex flex-col gap-4"
       >
-        <Field label={t("auth.codeApp")} error={errors.code?.message}>
+        <Field label={t("auth.codeApp")} error={errors.code?.message} required>
           <Input
             autoFocus
             inputMode="numeric"

package/src/features/login/components/two-factor-verify.tsx

@@ -35,7 +35,7 @@ export function TwoFactorVerify({ loading, onVerify, onRequestEmail }: Props): J
         onSubmit={handleSubmit((d) => onVerify(d.code))}
         className="flex flex-col gap-4"
       >
-        <Field label={t("auth.codeAny")} error={errors.code?.message}>
+        <Field label={t("auth.codeAny")} error={errors.code?.message} required>
           <Input autoFocus {...register("code")} />
         </Field>
         <Button type="submit" size="lg" disabled={loading}>

package/src/features/profile/force-password-change.tsx

@@ -79,6 +79,7 @@ export function ForcePasswordChange({
           <Field
             label={t("profile.currentPassword")}
             error={errors.currentPassword?.message}
+            required
           >
             <PasswordField
               error={!!errors.currentPassword}
@@ -88,6 +89,7 @@ export function ForcePasswordChange({
           <Field
             label={t("profile.newPassword")}
             error={errors.newPassword?.message}
+            required
           >
             <PasswordField
               error={!!errors.newPassword}
@@ -98,6 +100,7 @@ export function ForcePasswordChange({
           <Field
             label={t("profile.confirmPassword")}
             error={errors.confirm?.message}
+            required
           >
             <PasswordField
               error={!!errors.confirm}

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

@@ -249,13 +249,13 @@ export function ProfileScreen(): JSX.Element {
             </div>
 
             <h2 className="text-lg font-semibold">{t("profile.data")}</h2>
-            <Field label={t("users.name")} error={formErrors.name}>
+            <Field label={t("users.name")} error={formErrors.name} required>
               <Input
                 value={form.name}
                 onChange={(e) => setForm({ ...form, name: e.target.value })}
               />
             </Field>
-            <Field label={t("users.lastName")} error={formErrors.lastName}>
+            <Field label={t("users.lastName")} error={formErrors.lastName} required>
               <Input
                 value={form.lastName}
                 onChange={(e) => setForm({ ...form, lastName: e.target.value })}
@@ -354,6 +354,7 @@ export function ProfileScreen(): JSX.Element {
                 <Field
                   label={t("profile.currentPassword")}
                   error={errors.currentPassword?.message}
+                  required
                 >
                   <PasswordField
                     error={!!errors.currentPassword}
@@ -363,6 +364,7 @@ export function ProfileScreen(): JSX.Element {
                 <Field
                   label={t("profile.newPassword")}
                   error={errors.newPassword?.message}
+                  required
                 >
                   <PasswordField
                     error={!!errors.newPassword}
@@ -373,6 +375,7 @@ export function ProfileScreen(): JSX.Element {
                 <Field
                   label={t("profile.confirmPassword")}
                   error={errors.confirm?.message}
+                  required
                 >
                   <PasswordField
                     error={!!errors.confirm}

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

@@ -219,7 +219,7 @@ export function CatalogPanel({
             </DialogTitle>
           </DialogHeader>
           <DialogForm onSubmit={() => void save()}>
-            <Field label="Name">
+            <Field label="Name" required>
               <Input
                 placeholder={namePlaceholder}
                 value={form.name}

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

@@ -250,7 +250,7 @@ export function GroupsPanel(): JSX.Element {
             </DialogTitle>
           </DialogHeader>
           <DialogForm onSubmit={() => void save()}>
-            <Field label={t("users.name")}>
+            <Field label={t("users.name")} required>
               <Input
                 value={form.name}
                 onChange={(e) => setForm({ ...form, name: e.target.value })}

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

@@ -180,7 +180,7 @@ export function PermissionsPanel(): JSX.Element {
             </DialogTitle>
           </DialogHeader>
           <DialogForm onSubmit={() => void save()}>
-            <Field label="Code (resource:action:scope)">
+            <Field label="Code (resource:action:scope)" required>
               <Input
                 placeholder="users:read:any"
                 value={form.code}

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

@@ -201,7 +201,7 @@ export function RolesPanel(): JSX.Element {
           </DialogHeader>
           <DialogForm onSubmit={handleSubmit((values) => void save(values))}>
             <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
-              <Field label={t("rbac.roleName")} error={errors.name?.message}>
+              <Field label={t("rbac.roleName")} error={errors.name?.message} required>
                 <Input {...register("name")} />
               </Field>
               <Field

package/src/features/recovery/forgot-password-screen.tsx

@@ -48,7 +48,7 @@ export function ForgotPasswordScreen(): JSX.Element {
             <p className="text-sm text-muted-foreground">
               {t("recovery.forgotHint")}
             </p>
-            <Field label={t("auth.email")} error={errors.email?.message}>
+            <Field label={t("auth.email")} error={errors.email?.message} required>
               <Input type="email" autoFocus {...register("email")} />
             </Field>
             <Button type="submit" size="lg" disabled={loading}>

package/src/features/recovery/reset-password-screen.tsx

@@ -159,6 +159,7 @@ export function ResetPasswordScreen(): JSX.Element {
                 <Field
                   label={t("recovery.newPassword")}
                   error={errors.newPassword?.message}
+                  required
                 >
                   <PasswordField
                     error={!!errors.newPassword}
@@ -169,6 +170,7 @@ export function ResetPasswordScreen(): JSX.Element {
                 <Field
                   label={t("recovery.confirmPassword")}
                   error={errors.confirm?.message}
+                  required
                 >
                   <PasswordField
                     error={!!errors.confirm}

package/src/features/users/components/user-form-dialog.tsx

@@ -135,7 +135,7 @@ export function UserFormDialog({
 
         <DialogForm onSubmit={submit}>
           <div className="flex max-h-[70vh] flex-col gap-4 overflow-y-auto px-1">
-            <Field label={t("users.name")} error={errors.name?.message}>
+            <Field label={t("users.name")} error={errors.name?.message} required>
               <Input {...register("name")} />
             </Field>
             <Field label={t("users.lastName")} error={errors.lastName?.message}>
@@ -154,7 +154,7 @@ export function UserFormDialog({
                 </Field>
               )}
             />
-            <Field label={t("users.email")} error={errors.email?.message}>
+            <Field label={t("users.email")} error={errors.email?.message} required>
               <Input type="email" {...register("email")} />
             </Field>
             {!isEdit && (
@@ -169,6 +169,7 @@ export function UserFormDialog({
                   <Field
                     label={t("users.team")}
                     error={errors.groupId?.message}
+                    required
                   >
                     <SimpleSelect
                       value={field.value ?? ""}

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

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

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

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

package/src/index.ts

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

package/src/styles/core.css

@@ -180,6 +180,54 @@
     letter-spacing: -0.02em;
   }
 
+  /*
+   * Barra de rolagem — uma só, em todo lugar.
+   *
+   * A nativa é grossa (15px no macOS/Windows), tem trilho pintado e ignora o
+   * raio do que está rolando: dentro de um menu de 18rem, ela ocupa um décimo
+   * da largura e corta o canto arredondado. Aqui ela vira uma pílula fina sem
+   * trilho, na cor do texto secundário — presente enquanto se rola, discreta
+   * quando parada.
+   *
+   * As duas declarações não se somam: `scrollbar-width`/`scrollbar-color` são
+   * o padrão (Firefox, Chrome 121+, Safari 18.4+) e, onde valem, o browser
+   * ignora os pseudo-elementos `::-webkit-scrollbar` abaixo — que ficam para
+   * o WebKit mais antigo. Manter as duas é o que faz a barra ser igual nos
+   * dois lados.
+   *
+   * A cor sai de `--muted-foreground`, então ela acompanha o tema sozinha: no
+   * escuro clareia, no claro escurece, sem uma segunda regra em `.dark`.
+   */
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: hsl(var(--muted-foreground) / 0.35) transparent;
+  }
+
+  ::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  /*
+   * A borda transparente com `background-clip: content-box` é o que desenha a
+   * folga dos dois lados da pílula: sem ela a barra encosta na borda do menu.
+   */
+  ::-webkit-scrollbar-thumb {
+    background-color: hsl(var(--muted-foreground) / 0.35);
+    border: 2px solid transparent;
+    background-clip: content-box;
+    border-radius: 9999px;
+  }
+  ::-webkit-scrollbar-thumb:hover {
+    background-color: hsl(var(--muted-foreground) / 0.55);
+  }
+  /* O quadradinho onde as duas barras se encontram, que fica cinza por padrão. */
+  ::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+
   /*
    * Preenchimento automático (gerenciador de senhas). O `background-color` do
    * campo preenchido é intocável por CSS de autor — o Chrome o declara com