rl-core-front 0.15.6 → 0.16.0

package/src/contexts/jobs-store.ts

@@ -0,0 +1,391 @@
+/**
+ * A máquina dos trabalhos em segundo plano, **fora do React**.
+ *
+ * Mora aqui, e não em `useState` dentro do provider, por dois motivos que
+ * andam juntos: o estado é mutável e recebe muitos eventos (progresso chega em
+ * rajada), e ele precisa sobreviver a re-render sem recriar timers nem
+ * promessas. Com a máquina separada, o provider vira uma casca — e esta parte,
+ * que é onde mora a regra, fica testável sem montar componente.
+ *
+ * Desenho portado do `lw-tagvirtual`, onde roda em produção. As guardas que
+ * vieram de lá estão todas aqui: sessão que morre no desfecho, evento sem
+ * sessão guardado para reaplicar, prazos para nada ficar eterno e tolerância
+ * com o socket fora.
+ */
+
+/** Prazo para o job dar o primeiro sinal depois de enfileirado. */
+export const START_TIMEOUT_MS = 30_000;
+/** Prazo entre um sinal e o próximo. */
+export const PROGRESS_TIMEOUT_MS = 45_000;
+/**
+ * Quanto se espera com o socket fora antes de desistir.
+ *
+ * Enquanto o transporte está caído o job **continua correndo** no servidor:
+ * desistir aqui apagaria da vista um trabalho vivo.
+ */
+export const OFFLINE_GRACE_MS = 300_000;
+/** Quanto tempo o job concluído fica visível antes de sair sozinho. */
+export const SUCCESS_LINGER_MS = 1_500;
+/**
+ * Progresso que chega antes de o POST responder não tem sessão para onde ir.
+ * Guardar e reaplicar no bind evita perder o evento de fim de um trabalho
+ * rápido — no upload de imagem, esse é o caso comum.
+ */
+export const MAX_BUFFERED_EVENTS = 50;
+
+export type TrackedJobState = "running" | "completed" | "failed";
+
+/** Um trabalho em andamento, do jeito que o painel o mostra. */
+export interface TrackedJob {
+  /** Id local, que existe desde antes de o servidor responder. */
+  localId: string;
+  jobId: string | null;
+  label: string;
+  state: TrackedJobState;
+  /** Inteiro de 0 a 100. Fica em 0 enquanto o job não reporta etapa. */
+  percent: number;
+  message: string | null;
+  error: string | null;
+}
+
+/** O que quem inicia um trabalho recebe de volta. */
+export interface JobHandle<TSummary = unknown> {
+  localId: string;
+  /** Chamado quando a resposta HTTP traz o `jobId`. */
+  bind: (jobId: string) => void;
+  /** Encerra com resultado — para o trabalho que terminou na própria resposta. */
+  settle: (summary: TSummary) => void;
+  fail: (message: string) => void;
+  /** Resolve no desfecho: é o que o `await` de quem chamou espera. */
+  done: Promise<TSummary>;
+}
+
+export interface JobProgressData {
+  jobId: string;
+  percent: number;
+  message?: string;
+}
+
+export interface JobCompletedData<TSummary = unknown> {
+  jobId: string;
+  summary: TSummary;
+}
+
+export interface JobFailedData {
+  jobId: string;
+  message: string;
+}
+
+/** O controle de uma sessão — nada disto chega à tela. */
+interface Control {
+  resolve: (summary: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** Desde quando o socket está fora; zero quando está de pé. */
+  offlineSince: number;
+  finished: boolean;
+}
+
+const MENSAGEM_SEM_RESPOSTA =
+  "Sem resposta do servidor. Recarregue para conferir se terminou";
+
+export class JobsStore {
+  private jobs = new Map<string, TrackedJob>();
+  private controls = new Map<string, Control>();
+  /** `jobId` do servidor → id local. */
+  private index = new Map<string, string>();
+  private buffered = new Map<string, Array<() => void>>();
+  private listeners = new Set<() => void>();
+  private snapshot: TrackedJob[] = [];
+  private offline = false;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => this.listeners.delete(listener);
+  };
+
+  /**
+   * O mesmo array enquanto nada muda.
+   *
+   * `useSyncExternalStore` compara por identidade e entra em laço infinito se
+   * cada leitura devolver um array novo.
+   */
+  getSnapshot = (): TrackedJob[] => this.snapshot;
+
+  /** Registra uma sessão. O `jobId` chega depois, no `bind`. */
+  start = <TSummary,>(label: string): JobHandle<TSummary> => {
+    const localId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let resolve: (summary: TSummary) => void = () => undefined;
+    let reject: (error: Error) => void = () => undefined;
+
+    const done = new Promise<TSummary>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    this.jobs.set(localId, {
+      localId,
+      jobId: null,
+      label,
+      state: "running",
+      percent: 0,
+      message: null,
+      error: null,
+    });
+    this.controls.set(localId, {
+      resolve: resolve as (summary: unknown) => void,
+      reject,
+      timer: null,
+      offlineSince: this.offline ? Date.now() : 0,
+      finished: false,
+    });
+
+    this.arm(localId, START_TIMEOUT_MS);
+    this.publish();
+
+    return {
+      localId,
+      done,
+      bind: (jobId: string) => this.bind(localId, jobId),
+      settle: (summary: TSummary) => this.settle(localId, summary),
+      fail: (message: string) => this.fail(localId, message),
+    };
+  };
+
+  /** Tira da tela um job que o usuário fechou. */
+  dismiss = (localId: string): void => {
+    this.forget(localId);
+    this.publish();
+  };
+
+  onProgress = (data: JobProgressData): void => {
+    this.withSession(data.jobId, (localId) => {
+      this.patch(localId, {
+        state: "running",
+        percent: data.percent,
+        message: data.message ?? null,
+      });
+      this.arm(localId, PROGRESS_TIMEOUT_MS);
+      this.publish();
+    });
+  };
+
+  onCompleted = <TSummary,>(data: JobCompletedData<TSummary>): void => {
+    this.withSession(data.jobId, (localId) => this.settle(localId, data.summary));
+  };
+
+  onFailed = (data: JobFailedData): void => {
+    this.withSession(data.jobId, (localId) => this.fail(localId, data.message));
+  };
+
+  /**
+   * Marca o transporte como fora ou de volta.
+   *
+   * Com o socket fora, o prazo passa a ser o de tolerância: o trabalho segue
+   * do outro lado, e o que se perde é só a notícia dele.
+   */
+  setOffline = (offline: boolean): void => {
+    this.offline = offline;
+
+    for (const control of this.controls.values()) {
+      control.offlineSince = offline ? control.offlineSince || Date.now() : 0;
+    }
+  };
+
+  /** Os jobs que já têm id no servidor — os que a reconciliação consulta. */
+  pendingJobIds = (): string[] =>
+    [...this.jobs.values()]
+      .filter((job) => job.jobId && !this.controls.get(job.localId)?.finished)
+      .map((job) => job.jobId as string);
+
+  /**
+   * Aplica o que o `GET /jobs/:id` respondeu.
+   *
+   * É a rede de segurança do socket: o que passou enquanto a conexão esteve
+   * fora não volta sozinho.
+   */
+  reconcile = <TSummary,>(
+    jobId: string,
+    state: string,
+    percent: number | null,
+    message: string | null,
+    summary: TSummary | null,
+    errorMessage: string | null,
+  ): void => {
+    this.withSession(
+      jobId,
+      (localId) => {
+        if (state === "completed") {
+          this.settle(localId, summary);
+          return;
+        }
+        if (state === "failed") {
+          this.fail(localId, errorMessage ?? "Falha ao processar");
+          return;
+        }
+
+        this.patch(localId, {
+          percent: percent ?? this.jobs.get(localId)?.percent ?? 0,
+          message: message ?? this.jobs.get(localId)?.message ?? null,
+        });
+        this.publish();
+      },
+      // Sem buffer: reconciliação de job que esta aba não acompanha não
+      // interessa a ninguém, e guardá-la seguraria memória sem consumidor.
+      false,
+    );
+  };
+
+  /** Solta timers e sessões — chamado quando o provider desmonta. */
+  destroy = (): void => {
+    this.controls.forEach((control) => this.clearTimer(control));
+    this.controls.clear();
+    this.jobs.clear();
+    this.index.clear();
+    this.buffered.clear();
+    this.publish();
+  };
+
+  private bind(localId: string, jobId: string): void {
+    if (!this.jobs.has(localId)) {
+      return;
+    }
+
+    this.patch(localId, { jobId });
+    this.index.set(jobId, localId);
+    this.arm(localId, PROGRESS_TIMEOUT_MS);
+    this.publish();
+
+    // O que chegou antes de existir sessão vale agora.
+    const buffered = this.buffered.get(jobId);
+    this.buffered.delete(jobId);
+    buffered?.forEach((replay) => replay());
+  }
+
+  private settle(localId: string, summary: unknown): void {
+    const control = this.controls.get(localId);
+
+    if (!control || control.finished) {
+      return;
+    }
+
+    control.finished = true;
+    this.clearTimer(control);
+    this.patch(localId, { state: "completed", percent: 100, error: null });
+    control.resolve(summary);
+    this.publish();
+
+    // Sai da lista por remoção, e não por uma classe que o esconde: painel que
+    // "fica escondido" é exatamente como nasce o painel encalhado.
+    setTimeout(() => {
+      this.forget(localId);
+      this.publish();
+    }, SUCCESS_LINGER_MS).unref?.();
+  }
+
+  private fail(localId: string, message: string): void {
+    const control = this.controls.get(localId);
+
+    if (!control || control.finished) {
+      return;
+    }
+
+    control.finished = true;
+    this.clearTimer(control);
+    this.patch(localId, { state: "failed", error: message });
+    control.reject(new Error(message));
+    // Falha **não** sai sozinha: é a única forma de a pessoa saber o motivo se
+    // já tiver saído da tela que pediu. Sai no `dismiss`.
+    this.publish();
+  }
+
+  /**
+   * Resolve a sessão de um `jobId` e executa a ação.
+   *
+   * Sem sessão, a ação vai para o buffer daquele `jobId` — o caso do evento que
+   * chega antes de o POST responder.
+   */
+  private withSession(
+    jobId: string,
+    action: (localId: string) => void,
+    buffer = true,
+  ): void {
+    const localId = this.index.get(jobId);
+
+    if (localId && this.jobs.has(localId)) {
+      action(localId);
+      return;
+    }
+    if (!buffer) {
+      return;
+    }
+
+    const pendentes = this.buffered.get(jobId) ?? [];
+
+    if (pendentes.length < MAX_BUFFERED_EVENTS) {
+      pendentes.push(() => this.withSession(jobId, action, false));
+      this.buffered.set(jobId, pendentes);
+    }
+  }
+
+  private arm(localId: string, delay: number): void {
+    const control = this.controls.get(localId);
+
+    if (!control) {
+      return;
+    }
+
+    this.clearTimer(control);
+    control.timer = setTimeout(() => {
+      const atual = this.controls.get(localId);
+
+      if (!atual || atual.finished) {
+        return;
+      }
+      // Socket fora não é motivo para desistir: o job segue no servidor.
+      if (atual.offlineSince > 0 && Date.now() - atual.offlineSince < OFFLINE_GRACE_MS) {
+        this.arm(localId, PROGRESS_TIMEOUT_MS);
+        return;
+      }
+
+      this.fail(localId, MENSAGEM_SEM_RESPOSTA);
+    }, delay);
+    control.timer.unref?.();
+  }
+
+  private clearTimer(control: Control): void {
+    if (control.timer) {
+      clearTimeout(control.timer);
+      control.timer = null;
+    }
+  }
+
+  private patch(localId: string, changes: Partial<TrackedJob>): void {
+    const job = this.jobs.get(localId);
+
+    if (job) {
+      this.jobs.set(localId, { ...job, ...changes });
+    }
+  }
+
+  private forget(localId: string): void {
+    const job = this.jobs.get(localId);
+    const control = this.controls.get(localId);
+
+    if (control) {
+      this.clearTimer(control);
+    }
+    if (job?.jobId) {
+      this.index.delete(job.jobId);
+      this.buffered.delete(job.jobId);
+    }
+    this.jobs.delete(localId);
+    this.controls.delete(localId);
+  }
+
+  private publish(): void {
+    this.snapshot = [...this.jobs.values()];
+    this.listeners.forEach((listener) => listener());
+  }
+}

package/src/hooks/use-image-upload.ts

@@ -0,0 +1,169 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  ImageAccepted,
+  ImageJobSummary,
+  ImageProfileInfo,
+  imagesService,
+} from "#core/_services/images";
+import { useI18n } from "#core/contexts/i18n-context";
+import { useJobs } from "#core/contexts/jobs-context";
+
+export interface UseImageUploadResult {
+  /** O formato de saída que o servidor declarou. `null` enquanto carrega. */
+  profile: ImageProfileInfo | null;
+  sending: boolean;
+  error: string | null;
+  /** Envia um arquivo e devolve o caminho quando a conversão termina. */
+  upload: (file: File) => Promise<string | null>;
+  /** Manda o servidor buscar a imagem num endereço. */
+  uploadFromUrl: (url: string) => Promise<string | null>;
+  clearError: () => void;
+}
+
+/**
+ * Orquestra o envio de uma imagem: pergunta o perfil, valida o que dá para
+ * validar antes de gastar rede, envia e espera o desfecho.
+ *
+ * A espera não abre socket nenhum: ela registra uma sessão no `JobsProvider`,
+ * que já escuta a conexão do `AppShell` — e é a mesma sessão que o painel do
+ * rodapé mostra. Quando a resposta já traz o `path` (imagem pequena, ou
+ * ambiente sem fila), o job se encerra na hora, sem esperar evento que não vem.
+ */
+export function useImageUpload(profileName: string): UseImageUploadResult {
+  const { t } = useI18n();
+  const { start } = useJobs();
+  const [profile, setProfile] = useState<ImageProfileInfo | null>(null);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let ativo = true;
+
+    void imagesService
+      .profile(profileName)
+      .then((data) => {
+        if (ativo) {
+          setProfile(data);
+        }
+      })
+      .catch(() => {
+        // Perfil que não responde não derruba a tela: o envio segue possível, e
+        // quem recusa de verdade é o servidor.
+      });
+
+    return () => {
+      ativo = false;
+    };
+  }, [profileName]);
+
+  /** O caminho comum aos dois envios: sessão, espera e tradução do erro. */
+  const send = useCallback(
+    async (
+      label: string,
+      request: () => Promise<ImageAccepted>,
+    ): Promise<string | null> => {
+      setSending(true);
+      setError(null);
+
+      const job = start<ImageJobSummary>(label);
+
+      try {
+        const accepted = await request();
+
+        // Já terminou: encerra a sessão com o resultado em vez de esperar um
+        // evento que não vai chegar.
+        if (accepted.path) {
+          job.settle({ path: accepted.path, width: 0, height: 0, bytes: 0 });
+          return accepted.path;
+        }
+
+        if (!accepted.jobId) {
+          throw new Error(t("image.failed"));
+        }
+
+        job.bind(accepted.jobId);
+
+        const summary = await job.done;
+        return summary.path;
+      } catch (err) {
+        const message = messageOf(err, t("image.failed"));
+
+        // `fail` é idempotente do ponto de vista de quem chama: se o job já
+        // terminou em falha (foi o socket que trouxe o erro), isto não duplica
+        // nada — mas se a falha foi no próprio HTTP, é o que tira a sessão do
+        // painel.
+        job.fail(message);
+        setError(message);
+        return null;
+      } finally {
+        setSending(false);
+      }
+    },
+    [start, t],
+  );
+
+  const upload = useCallback(
+    async (file: File): Promise<string | null> => {
+      // As duas validações que dá para fazer aqui, e que evitam subir megabytes
+      // para receber 400: tipo e tamanho, ambos vindos do perfil.
+      if (profile && !profile.accept.includes(file.type)) {
+        setError(t("image.invalidType"));
+        return null;
+      }
+      if (profile && file.size > profile.maxBytes) {
+        setError(
+          t("image.tooLarge", {
+            size: Math.round(profile.maxBytes / (1024 * 1024)),
+          }),
+        );
+        return null;
+      }
+
+      return await send(file.name, () => imagesService.upload(profileName, file));
+    },
+    [profile, profileName, send, t],
+  );
+
+  const uploadFromUrl = useCallback(
+    async (url: string): Promise<string | null> =>
+      await send(labelOf(url), () => imagesService.fromUrl(profileName, url)),
+    [profileName, send],
+  );
+
+  return {
+    profile,
+    sending,
+    error,
+    upload,
+    uploadFromUrl,
+    clearError: () => setError(null),
+  };
+}
+
+/** O nome no fim da URL, para rotular a barra. */
+const labelOf = (url: string): string =>
+  url.split("?")[0].split("/").filter(Boolean).pop()?.slice(0, 60) ?? "imagem";
+
+/**
+ * A mensagem que o backend escreveu, quando existe.
+ *
+ * O core devolve texto pronto para ler em erro de negócio ("A imagem passa do
+ * limite de 8MB"), e trocá-lo por um genérico esconderia justamente o que a
+ * pessoa precisa saber para resolver.
+ */
+const messageOf = (error: unknown, fallback: string): string => {
+  const response = (error as { response?: { data?: { message?: unknown } } })
+    ?.response?.data?.message;
+
+  if (typeof response === "string") {
+    return response;
+  }
+  if (Array.isArray(response) && typeof response[0] === "string") {
+    return response[0];
+  }
+
+  return (error as Error)?.message || fallback;
+};

package/src/i18n/messages/en.ts

@@ -91,6 +91,21 @@ export const en: Messages = {
     running: "Processing…",
     completed: "Processing finished",
     failed: "The processing could not be completed",
+    dockRunning: "{count} in progress",
+    dockFailed: "Something went wrong",
+  },
+  image: {
+    empty: "Drag an image, paste it, or",
+    choose: "choose a file",
+    urlLabel: "Or paste an image address",
+    urlAction: "Fetch",
+    remove: "Remove image",
+    replace: "Replace image",
+    sending: "Sending…",
+    tooLarge: "The image exceeds the {size}MB limit",
+    invalidType: "Invalid format — use JPEG, PNG or WebP",
+    failed: "The image could not be sent",
+    hint: "The image is converted to {format} at up to {width}px.",
   },
   queues: {
     title: "Queues",
@@ -178,6 +193,7 @@ export const en: Messages = {
     hint: "Fill in only the fields you want to use. All of them are combined with AND.",
     apply: "Apply",
     clear: "Clear",
+    close: "Close",
     empty: "This listing has no filters yet.",
     noOptions: "No options available",
     all: "All",

package/src/i18n/messages/pt.ts

@@ -93,6 +93,21 @@ export const pt = {
     running: "Processando…",
     completed: "Processamento concluído",
     failed: "Não foi possível concluir o processamento",
+    dockRunning: "{count} em andamento",
+    dockFailed: "Algo não deu certo",
+  },
+  image: {
+    empty: "Arraste uma imagem, cole, ou",
+    choose: "escolha um arquivo",
+    urlLabel: "Ou cole o endereço de uma imagem",
+    urlAction: "Buscar",
+    remove: "Remover imagem",
+    replace: "Trocar imagem",
+    sending: "Enviando…",
+    tooLarge: "A imagem passa do limite de {size}MB",
+    invalidType: "Formato inválido — use JPEG, PNG ou WebP",
+    failed: "Não foi possível enviar a imagem",
+    hint: "A imagem é convertida para {format} em até {width}px.",
   },
   queues: {
     title: "Filas",
@@ -181,6 +196,7 @@ export const pt = {
     hint: "Preencha só os campos que quiser usar. Tudo é combinado com E.",
     apply: "Aplicar",
     clear: "Limpar",
+    close: "Fechar",
     empty: "Esta listagem ainda não tem filtros.",
     noOptions: "Nenhuma opção disponível",
     all: "Todos",

package/src/index.ts

@@ -87,6 +87,8 @@ export type { UseFilterSchemaResult } from "#core/hooks/use-filter-schema";
 export { useFilterSchema } from "#core/hooks/use-filter-schema";
 export type { FilterMode, FiltersState } from "#core/hooks/use-filters";
 export { useFilters } from "#core/hooks/use-filters";
+export type { UseImageUploadResult } from "#core/hooks/use-image-upload";
+export { useImageUpload } from "#core/hooks/use-image-upload";
 export type {
   JobState,
   UseJobProgressResult,
@@ -125,3 +127,30 @@ export { toListParams } from "#core/_services/api/list-query";
 export { en } from "#core/i18n/messages/en";
 export type { Messages } from "#core/i18n/messages/pt";
 export { pt } from "#core/i18n/messages/pt";
+
+// ---------------------------------------------------------------------------
+// Upload de imagem — o componente, o serviço e o painel de trabalhos
+// ---------------------------------------------------------------------------
+// O projeto declara o perfil no backend (tamanho, formato, pasta) e usa o
+// componente com o nome dele: `<ImageUpload profile="funkos" … />`. O
+// `JobsProvider` entra no layout, dentro do `SocketProvider` — é ele que
+// mantém o acompanhamento vivo quando a pessoa troca de tela no meio de um
+// upload, e é ele que renderiza o painel do rodapé.
+export type {
+  ImageAccepted,
+  ImageJobSummary,
+  ImageProfileInfo,
+} from "#core/_services/images";
+export { ImageFit, ImageFormat, imagesService } from "#core/_services/images";
+export { uploadUrlOf } from "#core/_utils/upload-url";
+export { JobDock } from "#core/components/job-dock";
+export type { ImageUploadProps } from "#core/components/ui/image-upload";
+export { ImageUpload } from "#core/components/ui/image-upload";
+export type { JobsContextType } from "#core/contexts/jobs-context";
+export { JobsProvider, useJobs } from "#core/contexts/jobs-context";
+export type {
+  JobHandle,
+  TrackedJob,
+  TrackedJobState,
+} from "#core/contexts/jobs-store";
+export { JobsStore } from "#core/contexts/jobs-store";

package/src/styles/core.css

@@ -237,3 +237,34 @@
     width: 0%;
   }
 }
+
+/*
+ * Listras andando na barra de progresso do painel de jobs.
+ *
+ * Existe porque um job de imagem não tem etapas contáveis: ele passa de "estou
+ * baixando" para "acabei" sem números no meio, e uma barra parada em 50% é
+ * indistinguível de uma barra travada. As listras dizem "ainda estou aqui" sem
+ * fingir precisão que o job não tem.
+ */
+.rl-job-stripes {
+  background-image: linear-gradient(
+    45deg,
+    rgb(255 255 255 / 0.3) 25%,
+    transparent 25%,
+    transparent 50%,
+    rgb(255 255 255 / 0.3) 50%,
+    rgb(255 255 255 / 0.3) 75%,
+    transparent 75%,
+    transparent
+  );
+  background-size: 1rem 1rem;
+  animation: rl-job-stripes 1s linear infinite;
+}
+@keyframes rl-job-stripes {
+  from {
+    background-position: 0 0;
+  }
+  to {
+    background-position: 1rem 0;
+  }
+}