rl-core-front 0.1.0

package/src/hooks/use-list-query.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import type { SortingState } from "@tanstack/react-table";
+import type { Dispatch, SetStateAction } from "react";
+import { useEffect, useMemo, useState } from "react";
+
+import type { ListQuery } from "#core/_services/api/list-query";
+import type { FiltersState } from "#core/hooks/use-filters";
+import { useFilters } from "#core/hooks/use-filters";
+
+export interface UseListQueryResult {
+  /** Pronta para o `.service.ts` da feature. */
+  query: ListQuery;
+  page: number;
+  pageSize: number;
+  sorting: SortingState;
+  setPage: Dispatch<SetStateAction<number>>;
+  setPageSize: Dispatch<SetStateAction<number>>;
+  setSorting: Dispatch<SetStateAction<SortingState>>;
+  /** Repassar direto para o `DataTable`. */
+  filters: FiltersState;
+}
+
+/**
+ * Paginação, ordenação e filtros de uma listagem, num lugar só.
+ *
+ * O hook da feature continua dono do fetch e das ações; o que era igual nos
+ * quatro (page/pageSize/sorting, e agora o filtro) mora aqui.
+ */
+export function useListQuery(
+  schemaUrl: string,
+  initialPageSize = 10,
+): UseListQueryResult {
+  const filters = useFilters(schemaUrl);
+  const { filter } = filters;
+
+  const [page, setPage] = useState(0);
+  const [pageSize, setPageSize] = useState(initialPageSize);
+  const [sorting, setSorting] = useState<SortingState>([]);
+
+  // Trocar o filtro volta para a primeira página: a página 3 de um resultado
+  // que agora tem uma página só voltaria vazia.
+  useEffect(() => {
+    setPage(0);
+  }, [filter]);
+
+  const sort = sorting[0];
+  const query = useMemo<ListQuery>(
+    () => ({
+      page,
+      limit: pageSize,
+      sortBy: sort?.id,
+      sortDir: sort ? (sort.desc ? "DESC" : "ASC") : undefined,
+      filter,
+    }),
+    [page, pageSize, sort, filter],
+  );
+
+  return {
+    query,
+    page,
+    pageSize,
+    sorting,
+    setPage,
+    setPageSize,
+    setSorting,
+    filters,
+  };
+}

package/src/hooks/use-request.ts

@@ -0,0 +1,114 @@
+"use client";
+
+import { AxiosError } from "axios";
+import { Dispatch, SetStateAction, useCallback, useState } from "react";
+
+import { useI18n, useToast } from "#core/contexts";
+
+/** Corpo de erro padronizado pelo AllExceptionsFilter do backend. */
+interface ApiErrorBody {
+  message?: string | string[];
+  errorCode?: string | null;
+}
+
+/** Operação concluída — define o texto padrão do toast de sucesso. */
+export enum RequestOperation {
+  Create = "create",
+  Update = "update",
+  Delete = "delete",
+}
+
+const SUCCESS_KEY: Record<RequestOperation, string> = {
+  [RequestOperation.Create]: "common.createdSuccess",
+  [RequestOperation.Update]: "common.updatedSuccess",
+  [RequestOperation.Delete]: "common.deletedSuccess",
+};
+
+const isOperation = (value: string): value is RequestOperation =>
+  (Object.values(RequestOperation) as string[]).includes(value);
+
+export interface RunOptions {
+  /**
+   * Toast de sucesso. Uma operação usa o texto padrão do `common.*`; uma string
+   * é exibida como veio, para quando a tela tem algo melhor a dizer que
+   * "Registro criado" (ex.: "Link de primeiro acesso enviado").
+   */
+  success?: RequestOperation | string;
+}
+
+export interface UseRequestResult {
+  run: <T>(fn: () => Promise<T>, options?: RunOptions) => Promise<T | null>;
+  loading: boolean;
+  error: string | null;
+  setError: Dispatch<SetStateAction<string | null>>;
+}
+
+/**
+ * Hook genérico para chamadas assíncronas com estados de loading/erro.
+ * Ex.: const { run, loading, error } = useRequest();
+ *      await run(() => authService.login(email, senha));
+ */
+export function useRequest(): UseRequestResult {
+  const { t } = useI18n();
+  const { notify } = useToast();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  /**
+   * Ordem de preferência da mensagem:
+   * 1. tradução do `errorCode` — texto do produto, no idioma do usuário;
+   * 2. `message` do servidor — usada quando o código não tem tradução, porque
+   *    costuma carregar dado dinâmico (ex.: "Restam 3 tentativas");
+   * 3. genérico.
+   *
+   * O `t()` devolve a própria chave quando ela não existe: é assim que se sabe
+   * que aquele código não tem texto próprio no cliente.
+   */
+  const messageFor = useCallback(
+    (body: ApiErrorBody | undefined): string => {
+      if (body?.errorCode) {
+        const key = `errors.codes.${body.errorCode}`;
+        const translated = t(key);
+        if (translated !== key) {
+          return translated;
+        }
+      }
+      const msg = body?.message;
+      if (Array.isArray(msg)) {
+        return msg.join(", ");
+      }
+      return msg ?? t("errors.unexpected");
+    },
+    [t],
+  );
+
+  /** Operação cai no texto padrão; string livre é a mensagem já pronta. */
+  const successMessage = useCallback(
+    (success: RequestOperation | string): string =>
+      isOperation(success) ? t(SUCCESS_KEY[success]) : success,
+    [t],
+  );
+
+  const run = useCallback(
+    async <T>(fn: () => Promise<T>, options?: RunOptions): Promise<T | null> => {
+      setLoading(true);
+      setError(null);
+      try {
+        const result = await fn();
+        if (options?.success) {
+          notify(successMessage(options.success), "success");
+        }
+        return result;
+      } catch (e) {
+        const err = e as AxiosError<ApiErrorBody>;
+        setError(messageFor(err.response?.data));
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [messageFor, notify, successMessage],
+  );
+
+  return { run, loading, error, setError };
+}

package/src/i18n/messages/en.ts

@@ -0,0 +1,296 @@
+import type { Messages } from "./pt";
+
+export const en: Messages = {
+  app: { name: "Core App" },
+  nav: {
+    home: "Home",
+    admin: "Administration",
+    dashboard: "Dashboard",
+    users: "Users",
+    rbac: "Roles & Permissions",
+    profile: "My profile",
+    logs: "Logs",
+    audit: "Audit",
+  },
+  logs: {
+    title: "Logs",
+    subtitle:
+      "Every API request — success and error, route, status and duration.",
+    tabRequests: "Requests",
+    tabErrors: "Errors",
+    date: "Date/time",
+    route: "Route",
+    status: "Status",
+    duration: "Duration",
+    user: "User",
+    systemUser: "System",
+    ip: "IP",
+    requestId: "Request ID",
+    type: "Type",
+    message: "Message",
+    viewDetails: "View details",
+    detailsTitle: "Error details",
+    stackTrace: "Stack trace",
+  },
+  auditTrail: {
+    title: "Audit Trail",
+    subtitle: "Data change history — who changed what, and when.",
+    entity: "Entity",
+    action: "Action",
+    actionCreate: "Create",
+    actionUpdate: "Update",
+    actionDelete: "Delete",
+    user: "User",
+    systemUser: "System",
+    date: "Date/time",
+    ip: "IP",
+    viewChanges: "View changes",
+    changesTitle: "Changes",
+    field: "Field",
+    before: "Before",
+    after: "After",
+    noFields: "No fields recorded for this change.",
+    showTechnical: "Show technical fields",
+  },
+  auditFields: {
+    name: "Name",
+    lastName: "Last name",
+    email: "Email",
+    phone: "Phone",
+    isActive: "Active",
+    avatar: "Avatar",
+    twoFactorEnabled: "2FA enabled",
+    failedLoginAttempts: "Failed login attempts",
+    mustChangePassword: "Must change password",
+    passwordChangedAt: "Password changed at",
+    createdAt: "Created at",
+    updatedAt: "Updated at",
+    deletedAt: "Deleted at",
+    description: "Description",
+    code: "Code",
+    permissions: "Permissions",
+    roles: "Roles",
+  },
+  table: {
+    columns: "Columns",
+    columnsButton: "Columns",
+    columnsTitle: "Configure column visibility",
+    columnsHint: "Select the columns you want to see in the table.",
+    atLeastOne: "At least one column must remain visible",
+    results: "results",
+    perPage: "per page",
+    empty: "No records",
+  },
+  filters: {
+    button: "Filters",
+    title: "Filters",
+    hint: "Fill in only the fields you want to use. All of them are combined with AND.",
+    apply: "Apply",
+    clear: "Clear",
+    clearAll: "Clear all",
+    empty: "This listing has no filters yet.",
+    noOptions: "No options available",
+    all: "All",
+    from: "From",
+    to: "To",
+    fromChip: "from",
+    toChip: "until",
+    selectPeriod: "Select a period",
+    lastDays: "{days} days",
+    previousMonth: "Previous month",
+    nextMonth: "Next month",
+    simple: "Simple",
+    advanced: "Advanced",
+    advancedHint:
+      "Build the expression: each group combines its conditions with AND or OR.",
+    addCondition: "Condition",
+    addGroup: "Group",
+    and: "AND",
+    or: "OR",
+    emptyGroup: "Group with no conditions.",
+    removeRule: "Remove condition",
+    removeGroup: "Remove group",
+    advancedSummary: "Advanced filter · {count} conditions",
+    field: "Field",
+    operator: "Operator",
+    value: "Value",
+    null: "Empty (null)",
+    listHint: "Separate with commas",
+    tooDeep: "Groups nested too deep — the limit is 3 levels.",
+    tooManyConditions: "Too many conditions — the limit is 50.",
+    tooManyItems: "Too many items in a list — the limit is 100.",
+    operators: {
+      EQ: "equals",
+      NE: "not equal to",
+      IS: "is",
+      NOT: "is not",
+      GT: "greater than",
+      GTE: "greater or equal to",
+      LT: "less than",
+      LTE: "less or equal to",
+      BETWEEN: "between",
+      NOTBETWEEN: "not between",
+      IN: "in",
+      NOTIN: "not in",
+      LIKE: "matches",
+      NOTLIKE: "does not match",
+      STARTSWITH: "starts with",
+      ENDSWITH: "ends with",
+      SUBSTRING: "contains",
+    },
+  },
+  notifications: {
+    title: "Notifications",
+    all: "All",
+    unread: "Unread",
+    markAllRead: "Mark all as read",
+    empty: "No notifications",
+  },
+  common: {
+    save: "Save",
+    cancel: "Cancel",
+    edit: "Edit",
+    delete: "Delete",
+    create: "Create",
+    confirm: "Confirm",
+    send: "Send",
+    yes: "Yes",
+    no: "No",
+    actions: "Actions",
+    loading: "Loading...",
+    language: "Language",
+    theme: "Theme",
+    light: "Light",
+    dark: "Dark",
+    system: "System",
+    // Mensagens de sucesso genéricas — só para tela reaproveitada, que não sabe
+    // qual entidade está editando. Tela de entidade fixa usa texto próprio.
+    createdSuccess: "Record created successfully",
+    updatedSuccess: "Record updated successfully",
+    deletedSuccess: "Record deleted successfully",
+  },
+  auth: {
+    loginTitle: "Sign in",
+    email: "Email",
+    password: "Password",
+    enter: "Sign in",
+    entering: "Signing in...",
+    forgotPassword: "Forgot my password",
+    twoFactorSetupTitle: "Set up 2FA",
+    twoFactorVerifyTitle: "Two-factor verification",
+    backupTitle: "Backup codes",
+    setupHint:
+      "Set up two-factor authentication (required). Scan the QR code with a free authenticator app (Google Authenticator, Microsoft Authenticator, Authy...) and enter the code.",
+    manualKey: "Can't scan? Use the manual key:",
+    codeApp: "App code (6 digits)",
+    confirmActivate: "Confirm and enable 2FA",
+    confirming: "Confirming...",
+    verifyHint:
+      "Enter the code from your authenticator app. No access to the app? Use a backup code or receive a code by email.",
+    codeAny: "Code (TOTP, email or backup)",
+    verify: "Validate code",
+    verifying: "Validating...",
+    receiveByEmail: "Receive code by email",
+    sendingEmail: "Sending...",
+    backupWarning:
+      "These codes are shown only now. Each can be used once if you lose access to the app.",
+    copy: "Copy",
+    codesCopied: "Backup codes copied",
+    savedContinue: "Saved, continue",
+    loginSuccess: "Signed in successfully",
+    twoFactorConfigured: "2FA configured successfully",
+    codeSent: "Code sent to your email",
+  },
+  recovery: {
+    forgotTitle: "Recover password",
+    forgotHint:
+      "Enter your email and we'll send a link to reset your password.",
+    sendLink: "Send link",
+    sending: "Sending...",
+    forgotSuccess: "If the email exists, we sent the reset instructions.",
+    backToLogin: "Back to sign in",
+    resetTitle: "Reset password",
+    newPassword: "New password",
+    confirmPassword: "Confirm new password",
+    resetCta: "Reset password",
+    resetSuccess: "Password reset successfully",
+    checking: "Checking the link...",
+    firstAccessTitle: "Set your first access password",
+    firstAccessHint:
+      "Create your password to access the system. On your first sign in you will also set up 2FA.",
+    linkExpired: "This link has expired. Request a new one to set your password.",
+    linkUsed: "This link has already been used. Request a new one.",
+    linkInvalid: "Invalid link. Request a new one to set your password.",
+    requestNewLink: "Request a new link",
+  },
+  user: { menuProfile: "My profile", logout: "Sign out" },
+  dashboard: {
+    welcome: "Welcome, {name}",
+    roles: "Roles",
+    permissions: "Permissions",
+    security: "Security",
+    twoFactorActive: "2FA active",
+    twoFactorPending: "2FA pending",
+  },
+  users: {
+    title: "Users",
+    newUser: "New user",
+    name: "Name",
+    lastName: "Last name",
+    phone: "Phone",
+    email: "Email",
+    roles: "Roles",
+    status: "Status",
+    active: "Active",
+    inactive: "Inactive",
+    locked: "Locked",
+    passwordByEmailHint:
+      "The user will receive a link by email to set their own password. No password is set here.",
+    sendFirstAccessLink: "Send first access link",
+    sendPasswordResetLink: "Send password reset link",
+    passwordResetLinkSent:
+      "Reset link sent — the user's active sessions were terminated",
+    firstAccessLinkSent: "First access link sent to the user's email",
+    resetTwoFactor: "Reset 2FA",
+    twoFactorReset: "2FA reset — user reconfigures on next login",
+  },
+  profile: {
+    title: "My profile",
+    data: "Data",
+    changePassword: "Change password",
+    currentPassword: "Current password",
+    newPassword: "New password",
+    confirmPassword: "Confirm new password",
+    changed: "Password changed successfully",
+    forceProvisional:
+      "You are using a temporary password. Set a new one to continue.",
+    forceExpired: "Your password has expired. Set a new one to continue.",
+    changeAvatar: "Change photo",
+    cropTitle: "Crop photo",
+    cropHint: "Drag to reposition and use the zoom to adjust.",
+    cropZoom: "Zoom",
+    saved: "Profile updated",
+    avatarUpdated: "Profile photo updated",
+    avatarRemoved: "Profile photo removed",
+  },
+  rbac: { title: "Roles & Permissions" },
+  validation: {
+    required: "Required field",
+    email: "Invalid email",
+    passwordStrong: "Min. 8 chars with uppercase, lowercase, number and symbol",
+    passwordsNotMatch: "Passwords do not match",
+    codeShort: "Code too short",
+  },
+  errors: {
+    unexpected: "Unexpected error",
+    codes: {
+      ACCOUNT_INACTIVE:
+        "Account deactivated. Please contact the system administrator.",
+      ACCOUNT_LOCKED:
+        "Account locked after too many attempts. Ask an administrator to send you a new link to set your password.",
+      PASSWORD_REUSED:
+        "This password has already been used. Choose one you have never used in this system.",
+      TOO_MANY_REQUESTS: "Too many attempts. Wait a moment and try again.",
+    },
+  },
+};