@remit/web-client 0.0.324 → 0.0.326

package/dist/src/hooks/useEmptyTrash.js

@@ -0,0 +1,130 @@
+/**
+ * Emptying an account's Trash, and the refusal the server answers it with.
+ *
+ * The press always reaches the server (#847): the client's `/config` is a read
+ * that can be stale, so a folder-role refusal is the server's to make, and the
+ * 409 is the only authority the surface listens to. On that refusal the strip
+ * states it in place and the repair opens the appointment prompt, which replays
+ * the empty once a folder is confirmed (#887 D16 item 1).
+ */
+import { configOperationsGetConfigQueryKey, mailboxOperationsListMailboxesQueryKey, trashOperationsEmptyTrashMutation, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { useRoleAppointmentPrompt } from "../components/mail/RoleAppointmentPromptProvider";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "../components/ui/error-banners";
+import { isFolderRoleRefusal, } from "../components/ui/folder-role-refusal";
+import { softErrorStatuses } from "../lib/error-classifier";
+import { invalidateThreadListQueries, threadListCacheKeys, } from "../lib/thread-list-cache";
+import { useTrashByAccount } from "./useArchiveMailbox";
+/**
+ * What a report or a refusal is about. Both are facts about one account's
+ * Trash as it resolved at the time, so neither may survive the mailbox or the
+ * account changing under a pane that never remounts — nor a resolution
+ * repaired elsewhere, which is the "or the resolution changes" the refusal
+ * persists until.
+ */
+const scopeOf = (accountId, mailboxId, trashMailboxId, source) => `${accountId ?? ""}|${mailboxId}|${trashMailboxId ?? ""}|${source ?? ""}`;
+export const useEmptyTrash = ({ accountId, mailboxId, }) => {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const { requestAppointment } = useRoleAppointmentPrompt();
+    const { trashByAccount } = useTrashByAccount();
+    const trash = accountId ? trashByAccount.get(accountId) : undefined;
+    const scope = scopeOf(accountId, mailboxId, trash?.mailboxId, trash?.source);
+    const [run, setRun] = useState({ scope });
+    if (run.scope !== scope)
+        setRun({ scope });
+    const current = run.scope === scope ? run : undefined;
+    /**
+     * The Trash as `/config` reads *now*, straight from the cache. After a
+     * repair the appointment names a different folder, and the replay must
+     * invalidate that folder's listing rather than the one this pane opened —
+     * a render has not necessarily flushed by the time the replay is called.
+     */
+    const listMailboxIdNow = useCallback(() => {
+        const config = queryClient.getQueryData(configOperationsGetConfigQueryKey());
+        const account = config?.accounts.find((one) => one.accountId === accountId);
+        const appointed = account?.folderAppointments.find((one) => one.role === "Trash")?.mailboxId;
+        return appointed ?? mailboxId;
+    }, [queryClient, accountId, mailboxId]);
+    // What the run in flight is about, for the same reason: a press on one
+    // folder must not read as a press on the next one the pane opens.
+    const inFlight = useRef(undefined);
+    const { mutateAsync, isPending } = useMutation({
+        ...trashOperationsEmptyTrashMutation(),
+        // The refusal is rendered in the pane, so it must not also take the whole
+        // screen. Only 409 — every other status is still the fatal page's (#1059).
+        meta: softErrorStatuses(409),
+        onMutate: () => {
+            inFlight.current = scope;
+            return { scope, listMailboxId: listMailboxIdNow() };
+        },
+        onSuccess: (data, _variables, context) => {
+            if (context.scope !== scope)
+                return;
+            // The service's count, never a local tally. A second press re-marks the
+            // same rows and reports N again — that is what the folder still holds,
+            // and reporting 0 over an expunge is the failure #887 is about.
+            setRun({ scope, deletedCount: data.deletedCount });
+        },
+        onError: (error, _variables, context) => {
+            const refused = isFolderRoleRefusal(error);
+            if (!refused) {
+                pushError({
+                    title: "Couldn't empty Trash",
+                    detail: formatErrorDetail(error),
+                    error,
+                });
+                return;
+            }
+            // A refusal that outlived what it was about states somebody else's
+            // problem over this folder.
+            if (context?.scope !== scope)
+                return;
+            setRun({ scope, refusal: refused });
+        },
+        onSettled: (_data, _error, _variables, context) => {
+            if (inFlight.current === context?.scope)
+                inFlight.current = undefined;
+            invalidateThreadListQueries(queryClient, threadListCacheKeys([context?.listMailboxId ?? mailboxId]));
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: mailboxOperationsListMailboxesQueryKey({
+                    path: { accountId },
+                }),
+            });
+        },
+    });
+    // `onError` above has already stated the failure; the rejection reaching the
+    // caller would only report it a second time.
+    const issue = useCallback(() => {
+        if (!accountId)
+            return Promise.resolve();
+        setRun({ scope });
+        return mutateAsync({ path: { accountId } }).then(() => { }, () => { });
+    }, [accountId, scope, mutateAsync]);
+    const emptyTrash = useCallback(() => {
+        void issue();
+    }, [issue]);
+    const repair = useCallback(() => {
+        const refusal = current?.refusal;
+        if (!refusal)
+            return;
+        requestAppointment({
+            accountId: refusal.accountId,
+            role: refusal.role,
+            reason: refusal.reason,
+            action: { kind: "emptyTrash" },
+            onAppointed: issue,
+        });
+    }, [current, requestAppointment, issue]);
+    return {
+        emptyTrash,
+        isEmptying: isPending && inFlight.current === scope,
+        deletedCount: current?.deletedCount,
+        refusal: current?.refusal,
+        repair,
+    };
+};

package/dist/src/hooks/useEscalatedActions.d.ts

@@ -0,0 +1,83 @@
+import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
+import { type BulkRunRequest } from "../components/mail/BulkRunProvider";
+import type { BulkActionProgress, BulkActionTarget, BulkRunStart, EscalatedAction } from "../lib/bulk-actions";
+/** The predicate a search-scoped run re-issues on every page — the same
+ *  filters the visible list is searching with, minus pagination/count knobs. */
+export type EscalationSearchQuery = Pick<NonNullable<ThreadOperationsSearchThreadsData["query"]>, "order" | "query" | "subject" | "from" | "unread" | "starred" | "attachments" | "category">;
+export type EscalationPhase = {
+    kind: "idle";
+} | {
+    kind: "counting";
+} | {
+    kind: "escalated";
+    total: number;
+};
+interface UseEscalatedActionsOptions {
+    mailboxId: string;
+    /** The mailbox in the user's words, for a commit refused while this runs. */
+    mailboxLabel?: string;
+    /** Owning account, forwarded to the unseen-count invalidation on completion. */
+    accountId?: string;
+    /** Disables escalation entirely (e.g. not searching). Resets any in-flight
+     *  phase back to idle. */
+    enabled: boolean;
+    /** Identifies the active predicate; escalation resets to idle whenever this
+     *  changes (a different search is a different question). */
+    predicateKey: string;
+    searchQuery: EscalationSearchQuery;
+    /**
+     * States how a run ended, for a user who is no longer looking at any screen
+     * that could show it. Handed to the run's owner rather than called here, so
+     * an ending that lands after this hook unmounted is still said (#112).
+     */
+    reportEnding?: BulkRunRequest["reportEnding"];
+}
+export interface UseEscalatedActionsResult {
+    phase: EscalationPhase;
+    /** Ask the server how many messages the predicate matches, and switch the
+     *  selection to that predicate once it answers. */
+    escalate: () => void;
+    /**
+     * Stop whatever this mailbox has running — its count, and the run when the
+     * run is its own. The request in flight is aborted and nothing further leaves
+     * (#113); a delete the server has already accepted still applies, so the
+     * batch on the wire is what a stop is worth. A no-op when nothing is running.
+     * Cancelling a count here never reaches a run in another mailbox: that run is
+     * not what this screen is offering to stop, and ending it would be silent.
+     * The only thing that ends a run in flight: leaving the selection, the
+     * wizard, the search or the mailbox does not.
+     */
+    stop: () => void;
+    /**
+     * Drop an escalated selection back to bounded without confirming anything.
+     * A run in flight owns the phase and holds it until it ends, so this is a
+     * no-op then — the selection the user is leaving and the run they started
+     * from it are two different things.
+     */
+    clear: () => void;
+    /** True while a chunked run (bounded->100 ids, or the escalated predicate)
+     *  over this mailbox is in flight, whichever screen started it. */
+    isRunning: boolean;
+    /** The action currently in flight, for status and progress wording. */
+    runningAction: EscalatedAction | undefined;
+    progress: BulkActionProgress | undefined;
+    /**
+     * Runs `action` in chunks. Pass `targets` for a materialized (bounded)
+     * selection; omit them to run against the escalated predicate (`phase` must
+     * be "escalated"). Each target names the account that owns it, so a
+     * selection spanning accounts is sent as one batch per account rather than
+     * as one batch the endpoint refuses whole (#872). Resolves once the run ends
+     * for any reason — cancelled, errored, or complete — with a
+     * `done`/`failedIds` outcome the caller reads to decide what is still
+     * outstanding, or with the refusal of a run that never started because
+     * another one is still going.
+     *
+     * The run itself belongs to `BulkRunProvider`, which outlives every screen
+     * that can show it: the caches, the refusal replay, the failure banner and
+     * the ending are its, so none of them are lost when the surface that started
+     * the run goes (#112).
+     */
+    runAction: (action: EscalatedAction, targets?: readonly BulkActionTarget[], claimEnding?: BulkRunRequest["claimEnding"]) => Promise<BulkRunStart>;
+}
+export declare const useEscalatedActions: ({ mailboxId, mailboxLabel, accountId, enabled, predicateKey, searchQuery, reportEnding, }: UseEscalatedActionsOptions) => UseEscalatedActionsResult;
+export {};

package/dist/src/hooks/useEscalatedActions.js

@@ -0,0 +1,175 @@
+import { messageBulkOperationsDeleteMessages, messageBulkOperationsMoveMessages, messageBulkOperationsUpdateFlags, threadOperationsSearchThreads, } from "@remit/api-http-client/sdk.gen.ts";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useBulkRun, } from "../components/mail/BulkRunProvider";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "../components/ui/error-banners";
+/** Page size for the execution loop. Set to the write side's own 100-id cap so
+ *  an execution page IS a write chunk — no in-memory accumulation step between
+ *  reading ids and sending them. */
+const PAGE_SIZE = 100;
+export const useEscalatedActions = ({ mailboxId, mailboxLabel, accountId, enabled, predicateKey, searchQuery, reportEnding, }) => {
+    const [phase, setPhase] = useState({ kind: "idle" });
+    // The count's own signal, which is not the run's: leaving the search ends a
+    // count, and never a run (#112).
+    const countAbortRef = useRef(undefined);
+    const { run, start, stop: stopRun } = useBulkRun();
+    const { pushError } = useErrorBanners();
+    // The live run, when it is this mailbox's. A run is mail leaving one mailbox,
+    // so it reports on that mailbox's list — not on whichever list is on screen.
+    const activeRun = run?.mailboxId === mailboxId ? run : undefined;
+    const isRunning = activeRun !== undefined;
+    // Read by callbacks that must not close over a stale render's answer.
+    const isRunningRef = useRef(false);
+    isRunningRef.current = isRunning;
+    // A different search (or leaving search/desktop) makes any in-flight
+    // escalation meaningless — it would otherwise keep counting or offering to
+    // act on a predicate the visible list no longer reflects. The selection goes;
+    // a run already going does not. It pages the predicate it was started
+    // against and reports what it reached, wherever the list moved on to.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: enabled/predicateKey are trigger-only — the reset itself reads neither.
+    useEffect(() => {
+        countAbortRef.current?.abort();
+        setPhase({ kind: "idle" });
+    }, [enabled, predicateKey]);
+    const searchQueryRef = useRef(searchQuery);
+    searchQueryRef.current = searchQuery;
+    const fetchPagesOf = useCallback((query) => async (continuationToken, signal) => {
+        const { data } = await threadOperationsSearchThreads({
+            path: { mailboxId },
+            query: { ...query, continuationToken, limit: PAGE_SIZE },
+            signal,
+            throwOnError: true,
+        });
+        return {
+            ids: (data.items ?? []).map((item) => item.messageId),
+            continuationToken: data.continuationToken,
+        };
+    }, [mailboxId]);
+    /**
+     * How many messages the predicate matches, straight from the server that
+     * resolves it (#509). One count-only request: `limit` is a page size and has
+     * no bearing on the answer, so nothing is paged to arrive at it.
+     */
+    const fetchMatchCount = useCallback(async (signal) => {
+        const { data } = await threadOperationsSearchThreads({
+            path: { mailboxId },
+            query: { ...searchQueryRef.current, count: true, results: false },
+            signal,
+            throwOnError: true,
+        });
+        if (data.count === undefined) {
+            throw new Error("the search returned no count for the selection");
+        }
+        return data.count;
+    }, [mailboxId]);
+    const applyBatchFor = useCallback((action) => async (ids, signal) => {
+        if (action.kind === "move") {
+            const { data } = await messageBulkOperationsMoveMessages({
+                body: {
+                    messageIds: ids,
+                    destinationMailboxId: action.destinationMailboxId,
+                },
+                signal,
+                throwOnError: true,
+            });
+            return data;
+        }
+        if (action.kind === "markRead") {
+            const { data } = await messageBulkOperationsUpdateFlags({
+                body: { messageIds: ids, isRead: true },
+                signal,
+                throwOnError: true,
+            });
+            return data;
+        }
+        const { data } = await messageBulkOperationsDeleteMessages({
+            body: { messageIds: ids },
+            signal,
+            throwOnError: true,
+        });
+        return data;
+    }, []);
+    const escalate = useCallback(() => {
+        const controller = new AbortController();
+        countAbortRef.current = controller;
+        setPhase({ kind: "counting" });
+        fetchMatchCount(controller.signal).then((total) => {
+            if (controller.signal.aborted) {
+                setPhase({ kind: "idle" });
+                return;
+            }
+            setPhase({ kind: "escalated", total });
+        }, (error) => {
+            // A stopped count rejects with its own abort. That is the press the
+            // user made, not a failure to report back to them.
+            if (controller.signal.aborted) {
+                setPhase({ kind: "idle" });
+                return;
+            }
+            pushError(buildMutationErrorBanner("Couldn't count matching messages", "The count didn't finish.", error));
+            setPhase({ kind: "idle" });
+        });
+    }, [fetchMatchCount, pushError]);
+    const stop = useCallback(() => {
+        countAbortRef.current?.abort();
+        if (isRunningRef.current)
+            stopRun(mailboxId);
+    }, [stopRun, mailboxId]);
+    const clear = useCallback(() => {
+        if (isRunningRef.current)
+            return;
+        countAbortRef.current?.abort();
+        setPhase({ kind: "idle" });
+    }, []);
+    const runAction = useCallback(async (action, targets, claimEnding) => {
+        // Read before the run clears the phase below, so a refusal can say how
+        // many messages the appointment's replay is about.
+        const matched = targets?.length ?? (phase.kind === "escalated" ? phase.total : 0);
+        // The predicate as it read when the run was confirmed. The run outlives
+        // the screen that started it, so reading the live query on every page
+        // would let a search typed afterwards redirect what is being deleted.
+        const source = targets !== undefined
+            ? { kind: "targets", targets }
+            : {
+                kind: "predicate",
+                fetchPage: fetchPagesOf(searchQueryRef.current),
+            };
+        const started = await start({
+            action,
+            mailboxId,
+            mailboxLabel,
+            accountId,
+            matched,
+            source,
+            applyBatch: applyBatchFor(action),
+            reportEnding,
+            claimEnding,
+        });
+        // The escalated selection was what the run was confirmed from, and the
+        // run has now happened to it. A refused commit leaves it standing: the
+        // selection is still the question, and stopping the other run is what
+        // makes it answerable.
+        if (started.kind === "ran")
+            setPhase({ kind: "idle" });
+        return started;
+    }, [
+        applyBatchFor,
+        fetchPagesOf,
+        phase,
+        mailboxId,
+        mailboxLabel,
+        accountId,
+        reportEnding,
+        start,
+    ]);
+    return {
+        phase,
+        escalate,
+        stop,
+        clear,
+        isRunning,
+        runningAction: activeRun?.action,
+        progress: activeRun?.progress,
+        runAction,
+    };
+};

package/dist/src/hooks/useFilters.d.ts

@@ -0,0 +1,57 @@
+import type { RemitImapCreateFilterResponse } from "@remit/api-http-client/types.gen.ts";
+import { type OrganizeDraft, type OrganizeScope } from "../lib/organize/organize-model";
+/**
+ * The query key the filter list reads and both mutations invalidate on success.
+ * Extracted so create/delete invalidate exactly the key `useFilterList`
+ * subscribes to — a drift here would leave the settings list stale after a
+ * filter is created or deleted (the same contract `buildMailboxListKey` pins
+ * for trigger-sync).
+ */
+export declare const buildFilterListKey: (accountId: string) => [Pick<import("@remit/api-http-client").Options<import("@remit/api-http-client").FilterOperationsListFiltersData>, "query" | "body" | "headers" | "path" | "baseUrl"> & {
+    _id: string;
+    _infinite?: boolean;
+    tags?: ReadonlyArray<string>;
+}];
+/**
+ * List the account's standing filters (Standing + Temporary). Expired
+ * Temporary filters stay in the list — they are shown distinctly, never hidden
+ * (RFC 034 Decision 1.2).
+ */
+export declare const useFilterList: (accountId: string | undefined) => {
+    filters: import("@remit/api-http-client").RemitImapFilterResponse[];
+    isPending: boolean;
+    isError: boolean;
+    error: import("@remit/api-http-client").FilterOperationsListFiltersError | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<{
+        continuationToken?: import("@remit/api-http-client").String800;
+        items: Array<import("@remit/api-http-client").RemitImapFilterResponse>;
+    }>, import("@remit/api-http-client").FilterOperationsListFiltersError>>;
+};
+/**
+ * Create the standing (`"these and new mail like this"`) or temporary
+ * (`"until <date>"`) filter for an organize draft. The two one-time scopes
+ * never create a filter (RFC 034 recap) and are not handled here.
+ */
+export declare const useCreateFilter: (accountId: string | undefined) => {
+    createFilter: (draft: OrganizeDraft, scope: Extract<OrganizeScope, "standing" | "temporary">, name: string) => void;
+    createFilterAsync: (draft: OrganizeDraft, scope: Extract<OrganizeScope, "standing" | "temporary">, name: string) => Promise<RemitImapCreateFilterResponse | undefined>;
+    data: RemitImapCreateFilterResponse | undefined;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    error: import("@remit/api-http-client").ApiError | import("@remit/api-http-client").ValidationError | null;
+    reset: () => void;
+};
+export declare const useDeleteFilter: (accountId: string | undefined) => {
+    deleteFilter: (filterId: string) => void;
+    isPending: boolean;
+    deletingFilterId: string | undefined;
+};
+export declare const useToggleFilter: (accountId: string | undefined) => {
+    toggleFilter: (filterId: string, enabled: boolean) => void;
+    retry: () => void;
+    togglingFilterId: string | undefined;
+    isError: boolean;
+    error: import("@remit/api-http-client").ApiError | null;
+    enabling: boolean;
+};

package/dist/src/hooks/useFilters.js

@@ -0,0 +1,147 @@
+import { filterDetailOperationsDeleteFilterMutation, filterDetailOperationsUpdateFilterMutation, filterOperationsCreateFilterMutation, filterOperationsListFiltersOptions, filterOperationsListFiltersQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { buildCreateFilterInput, } from "../lib/organize/organize-model";
+/**
+ * The query key the filter list reads and both mutations invalidate on success.
+ * Extracted so create/delete invalidate exactly the key `useFilterList`
+ * subscribes to — a drift here would leave the settings list stale after a
+ * filter is created or deleted (the same contract `buildMailboxListKey` pins
+ * for trigger-sync).
+ */
+export const buildFilterListKey = (accountId) => filterOperationsListFiltersQueryKey({ path: { accountId } });
+/**
+ * List the account's standing filters (Standing + Temporary). Expired
+ * Temporary filters stay in the list — they are shown distinctly, never hidden
+ * (RFC 034 Decision 1.2).
+ */
+export const useFilterList = (accountId) => {
+    const query = useQuery({
+        ...filterOperationsListFiltersOptions({
+            path: { accountId: accountId ?? "" },
+        }),
+        enabled: !!accountId,
+    });
+    return {
+        filters: query.data?.items ?? [],
+        isPending: query.isPending,
+        isError: query.isError,
+        error: query.error,
+        refetch: query.refetch,
+    };
+};
+/**
+ * Create the standing (`"these and new mail like this"`) or temporary
+ * (`"until <date>"`) filter for an organize draft. The two one-time scopes
+ * never create a filter (RFC 034 recap) and are not handled here.
+ */
+export const useCreateFilter = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...filterOperationsCreateFilterMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: buildFilterListKey(accountId),
+            });
+        },
+    });
+    const { mutate, mutateAsync } = mutation;
+    const createFilter = useCallback((draft, scope, name) => {
+        if (!accountId)
+            return;
+        mutate({
+            path: { accountId },
+            body: buildCreateFilterInput(draft, scope, name),
+        });
+    }, [accountId, mutate]);
+    /**
+     * The same create, resolved once the server has the filter, for work that has
+     * to follow it — the pass over the mail already in the mailbox. Chaining that
+     * to the request rather than to the surface is what keeps it running when the
+     * surface is closed while the create is still in flight.
+     *
+     * `undefined` means the create did not land. The failure itself is on
+     * `isError`, which is what the surface reports and retries from, so it is not
+     * raised a second time here.
+     */
+    const createFilterAsync = useCallback(async (draft, scope, name) => {
+        if (!accountId)
+            return undefined;
+        return mutateAsync({
+            path: { accountId },
+            body: buildCreateFilterInput(draft, scope, name),
+        }).then((created) => created, () => undefined);
+    }, [accountId, mutateAsync]);
+    return {
+        createFilter,
+        createFilterAsync,
+        data: mutation.data,
+        isPending: mutation.isPending,
+        isSuccess: mutation.isSuccess,
+        isError: mutation.isError,
+        error: mutation.error,
+        reset: mutation.reset,
+    };
+};
+export const useDeleteFilter = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...filterDetailOperationsDeleteFilterMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: buildFilterListKey(accountId),
+            });
+        },
+    });
+    const { mutate } = mutation;
+    const deleteFilter = useCallback((filterId) => {
+        if (!accountId)
+            return;
+        mutate({ path: { accountId, filterId } });
+    }, [accountId, mutate]);
+    return {
+        deleteFilter,
+        isPending: mutation.isPending,
+        deletingFilterId: mutation.isPending
+            ? mutation.variables?.path.filterId
+            : undefined,
+    };
+};
+export const useToggleFilter = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...filterDetailOperationsUpdateFilterMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: buildFilterListKey(accountId),
+            });
+        },
+    });
+    const { mutate, variables } = mutation;
+    const toggleFilter = useCallback((filterId, enabled) => {
+        if (!accountId)
+            return;
+        mutate({
+            path: { accountId, filterId },
+            body: { state: enabled ? "Active" : "Disabled" },
+        });
+    }, [accountId, mutate]);
+    const retry = useCallback(() => {
+        if (variables)
+            mutate(variables);
+    }, [mutate, variables]);
+    return {
+        toggleFilter,
+        retry,
+        togglingFilterId: mutation.isPending ? variables?.path.filterId : undefined,
+        isError: mutation.isError,
+        error: mutation.error,
+        enabling: variables?.body?.state === "Active",
+    };
+};

package/dist/src/hooks/useFolderLabelTranslator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `labelForMailbox` expects a positional `(key, fallback)` translator; i18next's
+ * `t` reads its second argument as an options object, which drops the fallback.
+ * Memoized so callers can hold it as a `useMemo` dependency.
+ */
+export declare const useFolderLabelTranslator: () => ((key: string, fallback: string) => string);

package/dist/src/hooks/useFolderLabelTranslator.js

@@ -0,0 +1,11 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+/**
+ * `labelForMailbox` expects a positional `(key, fallback)` translator; i18next's
+ * `t` reads its second argument as an options object, which drops the fallback.
+ * Memoized so callers can hold it as a `useMemo` dependency.
+ */
+export const useFolderLabelTranslator = () => {
+    const { t } = useTranslation("mail", { useSuspense: false });
+    return useCallback((key, fallback) => t(key, { defaultValue: fallback }), [t]);
+};

package/dist/src/hooks/useFollowFocusOpen.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How long the cursor must sit still before its row loads. Comfortably above
+ * the ~30ms of a repeating key, so a held key coalesces into a single load,
+ * and short enough that a single press reads as immediate.
+ */
+export declare const FOLLOW_FOCUS_DELAY_MS = 120;
+interface UseFollowFocusOpenOptions {
+    /**
+     * The row a keyboard command last moved the cursor onto, and `undefined`
+     * whenever the cursor last moved some other way — a click, a row taking DOM
+     * focus, a thread opening, the list reshuffling under a refetch.
+     */
+    keyboardFocusedMessageId: string | undefined;
+    /** The row already in the reading pane, so an open row does not reload. */
+    openMessageId: string | undefined;
+    /**
+     * Whether the cursor may open rows at all. Desktop-only: on the single-pane
+     * tiers the reading pane replaces the list, so following the cursor would
+     * throw the user off the list they are scanning. Also off while rows are
+     * selected, where the cursor is building a selection rather than reading.
+     */
+    enabled: boolean;
+    /** Opens a row in the reading pane. */
+    open: (messageId: string) => void;
+    delayMs?: number;
+}
+export declare const useFollowFocusOpen: ({ keyboardFocusedMessageId, openMessageId, enabled, open, delayMs, }: UseFollowFocusOpenOptions) => void;
+export {};