@remit/web-client 0.0.324 → 0.0.326

package/dist/src/hooks/useOrganizeJob.js

@@ -0,0 +1,95 @@
+import { organizeJobDetailOperationsGetOrganizeJobOptions, organizeOperationsCreateOrganizeJobMutation, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useCallback, useState } from "react";
+import { buildOrganizeInput, buildRunFilterInput, } from "../lib/organize/organize-model";
+import { isTerminalJobState, nextPollDelayMs, } from "../lib/organize/organize-poll";
+const organizeJobFailure = (createError, statusError, passAlreadyRun) => {
+    if (createError) {
+        return {
+            kind: passAlreadyRun ? "restartFailed" : "startFailed",
+            error: createError,
+        };
+    }
+    if (statusError)
+        return { kind: "statusUnreadable", error: statusError };
+    return undefined;
+};
+/**
+ * "All like these" — start a one-time retroactive back-apply (POST /organize)
+ * and poll its status to completion (GET /organize/{organizeJobId}). Polling
+ * backs off exponentially and stops the instant the job reaches a terminal
+ * state (Complete / Failed), surfacing matched / applied / failed counts. The
+ * back-apply itself scans the corpus server-side; the client only reads a
+ * single job row per poll.
+ */
+export const useOrganizeJob = (accountId) => {
+    const [organizeJobId, setOrganizeJobId] = useState();
+    const createMutation = useMutation({
+        ...organizeOperationsCreateOrganizeJobMutation(),
+        onSuccess: (data) => setOrganizeJobId(data.organizeJobId),
+    });
+    const { mutate: createJob } = createMutation;
+    const jobQuery = useQuery({
+        ...organizeJobDetailOperationsGetOrganizeJobOptions({
+            path: {
+                accountId: accountId ?? "",
+                organizeJobId: organizeJobId ?? "",
+            },
+        }),
+        enabled: !!accountId && !!organizeJobId,
+        refetchInterval: (query) => {
+            const state = query.state.data?.state;
+            if (isTerminalJobState(state))
+                return false;
+            return nextPollDelayMs(query.state.dataUpdateCount);
+        },
+    });
+    const start = useCallback((draft) => {
+        if (!accountId)
+            return;
+        createJob({
+            path: { accountId },
+            body: buildOrganizeInput(draft),
+        });
+    }, [accountId, createJob]);
+    /** Run a saved filter over the inbox, the same pass its create queued. */
+    const startForFilter = useCallback((filterId) => {
+        if (!accountId)
+            return;
+        createJob({
+            path: { accountId },
+            body: buildRunFilterInput(filterId),
+        });
+    }, [accountId, createJob]);
+    const { refetch } = jobQuery;
+    // Looks at the job already in flight again. Distinct from `start`, which
+    // queues a second pass over the same mail.
+    const refreshStatus = useCallback(() => {
+        void refetch();
+    }, [refetch]);
+    // The last pass this client read. A restart replaces it only once the server
+    // hands back a job id: while the create is in flight those counts are not this
+    // pass's, and a create that fails leaves them standing (#552).
+    const lastPass = jobQuery.data;
+    const job = createMutation.isPending ? undefined : lastPass;
+    const state = job?.state ?? createMutation.data?.state;
+    const isDone = isTerminalJobState(job?.state);
+    const progress = {
+        state,
+        matchedCount: job?.matchedCount ?? 0,
+        appliedCount: job?.appliedCount ?? 0,
+        failedCount: job?.failedCount ?? 0,
+        errorMessage: job?.errorMessage ?? "",
+    };
+    return {
+        start,
+        startForFilter,
+        watch: setOrganizeJobId,
+        refreshStatus,
+        progress,
+        isStarting: createMutation.isPending,
+        isRunning: !!organizeJobId && !isDone,
+        isDone,
+        failure: organizeJobFailure(createMutation.error, jobQuery.error, !!lastPass),
+    };
+};

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

@@ -0,0 +1,17 @@
+import { type OverlayPanel } from "../routing";
+export interface RailPanels {
+    /** The overlay the address holds: the nav slide-over or the shortcuts sheet. */
+    openOverlay: OverlayPanel | undefined;
+    /** Whether pane 4 is up, by the reader's standing answer or a raise. */
+    intelligenceOpen: boolean;
+    showOverlay: (overlay: OverlayPanel | undefined) => void;
+    /**
+     * The reader's own control, which is what a stored preference is made of —
+     * except over a rail only a raise has up, where it ends the raise and stores
+     * nothing.
+     */
+    toggleIntelligence: () => void;
+    /** Puts the rail up for the message in front of the reader, and no further. */
+    raiseIntelligence: () => void;
+}
+export declare const useRailPanels: () => RailPanels;

package/dist/src/hooks/useRailPanels.js

@@ -0,0 +1,94 @@
+/**
+ * The binding between the address, this device's stored preference and what the
+ * `/mail` shell has up: pane 4 and the one overlay that may cover it.
+ *
+ * The rail goes up two ways and they are not the same fact. The reader's own
+ * control states where they want the rail from now on, so it writes both the
+ * preference and the address. A raise — the DKIM auto-open, the authenticity
+ * banner's "Why?" — surfaces the rail for the message in front of them and is
+ * held here, in memory, against that message: it never writes the preference,
+ * and opening anything else ends it. One message signed by the wrong domain used
+ * to mean the rail was up for every later thread and every later session (#778).
+ *
+ * The raise stays out of the address because its whole copy is computed from the
+ * open message — reload the URL and the mismatch raises it again on its own, so
+ * putting it in the fragment would be a second owner of a fact the message
+ * already holds (`docs/architecture/url-state.md`, R6).
+ */
+import { useCallback, useState } from "react";
+import { readIntelligencePref, resolveRailOpen, writeIntelligencePref, } from "../lib/intelligence-pref";
+import { isOverlayPanel, useOpenPanels, useOpenThreadPath, useSetOpenPanels, } from "../routing";
+import { useLayoutTier } from "./useLayoutTier";
+export const useRailPanels = () => {
+    const tier = useLayoutTier();
+    // The panels the address carries (#722): the intelligence rail, the nav
+    // slide-over and the shortcuts sheet. The rail is a pane and the other two
+    // cover it, so the address holds a pane and an overlay at once — a sheet
+    // opening never takes the rail down — while two overlays cannot both be up.
+    const openPanels = useOpenPanels();
+    const setOpenPanels = useSetOpenPanels();
+    const openOverlay = openPanels.find(isOverlayPanel);
+    // Pane 4 on desktop, the details drawer below it. `resolveRailOpen` is the
+    // one place the address and the stored preference meet: the address decides
+    // whenever it says anything at all, and the preference opens the rail with
+    // the thread where it is silent (#782).
+    const openThread = useOpenThreadPath();
+    // Held in state, not read back from storage each render: closing the rail
+    // where the address is silent changes nothing about the address, and the
+    // answer has to move anyway.
+    const [prefersRail, setPrefersRail] = useState(readIntelligencePref);
+    // The message a raise belongs to. Naming it by address is what ends the raise
+    // when the reader opens anything else, without a teardown that has to run.
+    const openMessage = openThread
+        ? `${openThread.threadId}/${openThread.messageId ?? ""}`
+        : null;
+    const [raisedFor, setRaisedFor] = useState(null);
+    const visibility = {
+        panels: openPanels,
+        prefersOpen: prefersRail,
+        isDesktop: tier === "desktop",
+        hasThread: openThread !== undefined,
+        openMessage,
+    };
+    const intelligenceOpen = resolveRailOpen({ ...visibility, raisedFor });
+    // What the reader themselves have the rail at, which is what an address write
+    // states. A raise is left out of it on purpose: a sheet opening over a
+    // surfaced rail must not write that rail into the address as a choice.
+    const chosenOpen = resolveRailOpen({ ...visibility, raisedFor: null });
+    // Every write states the whole set, because it is composed from what is
+    // showing rather than from what the address happens to spell: the rail open
+    // by preference alone is still open, and an overlay must not close it.
+    const showPanels = useCallback((rail, overlay) => {
+        setOpenPanels([
+            ...(rail ? ["intelligence"] : []),
+            ...(overlay ? [overlay] : []),
+        ]);
+    }, [setOpenPanels]);
+    const showOverlay = useCallback((overlay) => {
+        showPanels(chosenOpen, overlay);
+    }, [chosenOpen, showPanels]);
+    const toggleIntelligence = useCallback(() => {
+        // Putting away a rail that only a raise has up answers the surfacing, not
+        // the question of where the reader wants the rail — the answer they gave
+        // last stands, and the address never carried this rail to rewrite.
+        if (intelligenceOpen && !chosenOpen) {
+            setRaisedFor(null);
+            return;
+        }
+        const open = !intelligenceOpen;
+        writeIntelligencePref(open);
+        setPrefersRail(open);
+        setRaisedFor(null);
+        showPanels(open, openOverlay);
+    }, [chosenOpen, intelligenceOpen, openOverlay, showPanels]);
+    const raiseIntelligence = useCallback(() => {
+        setRaisedFor(openMessage);
+    }, [openMessage]);
+    return {
+        openOverlay,
+        intelligenceOpen,
+        showOverlay,
+        toggleIntelligence,
+        raiseIntelligence,
+    };
+};

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

@@ -0,0 +1,41 @@
+/** How the redirect ended: this window came back, or it never left. */
+export type RedirectEnd = "returned" | "stalled";
+/**
+ * Long enough for a slow provider fetch to take the page away, short enough
+ * that a control which is never going anywhere does not read as busy.
+ */
+export declare const REDIRECT_STALL_MS = 20000;
+export declare const REDIRECT_STALL_MESSAGE = "Couldn't open Microsoft's sign-in page. Check your connection, and anything blocking redirects, then try again.";
+/**
+ * Run `onEnded` when the window that left for an external identity provider is
+ * being looked at again, and hand back the marker to call as it leaves.
+ *
+ * A control that starts a redirect stays busy until the redirect is over, and
+ * neither the mutation settling nor the next look at this window proves that:
+ * `window.location.assign` returns with the page still here while the browser
+ * fetches the provider's, and an app-switch away and back during that fetch is
+ * a look at a window that never left. Installed to a home screen there is no
+ * address bar and app-switching is how people move around, so that early look
+ * is the common case, not the corner one (#646). The page having actually been
+ * hidden is what separates the two.
+ *
+ * Every return leg, not just the first: a user who came back mid-sign-in to
+ * read a password has finished nothing, so the watch stays armed.
+ *
+ * The listeners are on from mount and `markRedirectStarted` runs synchronously
+ * on the line before `assign`, so nothing here depends on a render landing
+ * first.
+ *
+ * A page restored from the back-forward cache — browser Back out of the
+ * provider's consent screen — is a return leg on its own evidence. Without it a
+ * control that was left busy has nothing to clear it and stays busy for good.
+ *
+ * An `assign` that never navigates hides nothing and restores nothing, so no
+ * return leg is ever coming and the control would read as busy until a reload
+ * (#964). A page that has stayed visible for `REDIRECT_STALL_MS` since the
+ * redirect started is that case: the watch ends as `"stalled"` so the caller
+ * states the failure instead of settling in silence. Only visible time counts —
+ * any hide is evidence the redirect did happen, so it stops the watch and
+ * leaves the return leg to end it.
+ */
+export declare const useRedirectEnded: (onEnded: (end: RedirectEnd) => void) => (() => void);

package/dist/src/hooks/useRedirectEnded.js

@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useRef } from "react";
+import { useReturnFromRedirect } from "./useReturnFromRedirect";
+/**
+ * Long enough for a slow provider fetch to take the page away, short enough
+ * that a control which is never going anywhere does not read as busy.
+ */
+export const REDIRECT_STALL_MS = 20_000;
+export const REDIRECT_STALL_MESSAGE = "Couldn't open Microsoft's sign-in page. Check your connection, and anything blocking redirects, then try again.";
+/**
+ * Run `onEnded` when the window that left for an external identity provider is
+ * being looked at again, and hand back the marker to call as it leaves.
+ *
+ * A control that starts a redirect stays busy until the redirect is over, and
+ * neither the mutation settling nor the next look at this window proves that:
+ * `window.location.assign` returns with the page still here while the browser
+ * fetches the provider's, and an app-switch away and back during that fetch is
+ * a look at a window that never left. Installed to a home screen there is no
+ * address bar and app-switching is how people move around, so that early look
+ * is the common case, not the corner one (#646). The page having actually been
+ * hidden is what separates the two.
+ *
+ * Every return leg, not just the first: a user who came back mid-sign-in to
+ * read a password has finished nothing, so the watch stays armed.
+ *
+ * The listeners are on from mount and `markRedirectStarted` runs synchronously
+ * on the line before `assign`, so nothing here depends on a render landing
+ * first.
+ *
+ * A page restored from the back-forward cache — browser Back out of the
+ * provider's consent screen — is a return leg on its own evidence. Without it a
+ * control that was left busy has nothing to clear it and stays busy for good.
+ *
+ * An `assign` that never navigates hides nothing and restores nothing, so no
+ * return leg is ever coming and the control would read as busy until a reload
+ * (#964). A page that has stayed visible for `REDIRECT_STALL_MS` since the
+ * redirect started is that case: the watch ends as `"stalled"` so the caller
+ * states the failure instead of settling in silence. Only visible time counts —
+ * any hide is evidence the redirect did happen, so it stops the watch and
+ * leaves the return leg to end it.
+ */
+export const useRedirectEnded = (onEnded) => {
+    const armed = useRef(false);
+    const hidden = useRef(false);
+    const stallTimer = useRef(null);
+    const latest = useRef(onEnded);
+    latest.current = onEnded;
+    const stopStallWatch = useCallback(() => {
+        if (stallTimer.current === null)
+            return;
+        clearTimeout(stallTimer.current);
+        stallTimer.current = null;
+    }, []);
+    const settle = useCallback(() => {
+        if (!armed.current || !hidden.current)
+            return;
+        stopStallWatch();
+        hidden.current = false;
+        latest.current("returned");
+    }, [stopStallWatch]);
+    useEffect(() => {
+        const markHidden = () => {
+            hidden.current = true;
+            stopStallWatch();
+        };
+        const handleVisibility = () => {
+            if (document.visibilityState !== "hidden")
+                return;
+            markHidden();
+        };
+        const handlePageShow = (event) => {
+            if (!event.persisted)
+                return;
+            // A restored page is the whole round trip in one event: the hide that
+            // preceded it belongs to the document this one resumes, and nothing
+            // else is going to report it.
+            markHidden();
+            settle();
+        };
+        document.addEventListener("visibilitychange", handleVisibility);
+        window.addEventListener("pagehide", markHidden);
+        window.addEventListener("pageshow", handlePageShow);
+        return () => {
+            document.removeEventListener("visibilitychange", handleVisibility);
+            window.removeEventListener("pagehide", markHidden);
+            window.removeEventListener("pageshow", handlePageShow);
+            stopStallWatch();
+        };
+    }, [settle, stopStallWatch]);
+    // Always listening: the gate is the pair of refs above, which a redirect
+    // arms and a hidden interval satisfies, not whether this hook is mounted
+    // with a flag already flipped.
+    useReturnFromRedirect(true, settle);
+    return useCallback(() => {
+        armed.current = true;
+        hidden.current = false;
+        stopStallWatch();
+        stallTimer.current = setTimeout(() => {
+            stallTimer.current = null;
+            // The redirect is over as far as this window is concerned: it decided
+            // nothing, and a later look at a page that never left is not a return.
+            armed.current = false;
+            hidden.current = false;
+            latest.current("stalled");
+        }, REDIRECT_STALL_MS);
+    }, [stopStallWatch]);
+};

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

@@ -0,0 +1,97 @@
+import type { RemitImapSyncPhase } from "@remit/api-http-client/types.gen.ts";
+import type { RefreshControlState } from "@remit/ui";
+export type { RefreshControlState };
+/** How often the wait polls an account's own sync status once a round is
+ * enqueued — fast enough to feel responsive, far below the once-a-minute
+ * background cadence, and bounded by {@link REFRESH_TIMEOUT_MS} either way. */
+export declare const REFRESH_POLL_MS = 2000;
+/** A refresh that gets no answer must terminate in a stated failure rather
+ * than spin forever — this is that bound. */
+export declare const REFRESH_TIMEOUT_MS = 45000;
+export interface AccountOutcome {
+    accountId: string;
+    message?: string;
+}
+/** The fields of `getSyncStatus` this wait reads, named so it can be driven
+ * from a scripted sequence of readings. */
+export interface SyncStatusReading {
+    syncPhase?: RemitImapSyncPhase;
+    lastSyncAt?: number;
+    mailboxes?: readonly {
+        fullPath?: string;
+        lastSyncedAt?: number;
+    }[];
+}
+/**
+ * The account's INBOX stamp, or 0 when the account has no INBOX or has never
+ * synced one. `getSyncStatus` reports `lastSyncedAt` per mailbox, which is what
+ * lets the wait answer "the inbox is current" ahead of "the round is done".
+ */
+export declare const inboxSyncedAt: (reading: SyncStatusReading) => number;
+export interface WaitForSettledOptions {
+    accountId: string;
+    readStatus: () => Promise<SyncStatusReading>;
+    /** `lastSyncAt` as it read immediately before this refresh triggered. */
+    baselineLastSyncAt: number;
+    /** The INBOX `lastSyncedAt` from that same pre-trigger reading. */
+    baselineInboxSyncedAt?: number;
+    /** Called at most once, the moment INBOX's own stamp passes the baseline
+     * while the round is still running — never after the round has settled,
+     * which the caller already treats as the confirmed state. */
+    onInboxSynced?: () => void;
+    deadline: number;
+    pollMs?: number;
+}
+/**
+ * Poll one account's sync status until a round that started at or after this
+ * refresh triggered has settled, or `deadline` passes.
+ *
+ * `account.lastSyncAt` is the worker's own once-per-round stamp, and it is the
+ * only thing here that tells one round from another. A phase seen mid-flight
+ * does not: the tab's background poll, another tab, and every `GET /config`
+ * trigger rounds nobody clicked for, so a click landing while one of those is
+ * in flight used to confirm on it — a checkmark and an invalidated list with
+ * the clicked round still unrun, and the new mail it would have fetched unseen
+ * until the next poll (#953). Requiring the stamp to pass the reading taken
+ * before the trigger admits only a round that started after it.
+ *
+ * `POST /sync` enqueues and returns, so the first reading after triggering
+ * still shows the previous round — including a previous round's `error` phase,
+ * which is why that phase only speaks once the stamp has moved.
+ *
+ * A round is the whole account — every folder, in queue order — but the mail
+ * a person pressed refresh for is in their inbox. `onInboxSynced` fires the
+ * moment that one mailbox's own stamp passes the baseline, so the list on
+ * screen reloads then rather than after Junk and Trash have also gone by. The
+ * round-level stamp still decides the button's confirmed state.
+ *
+ * Read-only (`getSyncStatus`, no IMAP call, no queue write), so waiting costs
+ * a handful of cheap GETs — never a refetch of the account's own message
+ * list.
+ */
+export declare const waitForSettled: ({ accountId, readStatus, baselineLastSyncAt, baselineInboxSyncedAt, onInboxSynced, deadline, pollMs, }: WaitForSettledOptions) => Promise<AccountOutcome | undefined>;
+export interface UseRefreshControlOptions {
+    /** The caller's chance to invalidate whatever view-specific query (a
+     * mailbox's thread list, the brief's unified list) the sync may have
+     * changed, alongside the invalidation of the account's own mailbox-list
+     * query.
+     *
+     * Called more than once per press: once per account the moment its INBOX
+     * is current, and again once its whole round has settled. It must
+     * therefore be idempotent — an invalidation is. */
+    onSettled?: () => void;
+}
+export interface UseRefreshControlResult {
+    state: RefreshControlState;
+    errorMessage?: string;
+    refresh: () => void;
+}
+/**
+ * Drives the shared `RefreshButton` for one or more accounts: triggers a sync
+ * for each, waits for the server's own sync-status to settle — not just the
+ * enqueue ack — then invalidates the queries the caller names. A manual
+ * refresh is an explicit user action, so unlike the background poll it always
+ * shows the result; what it must never do is leave the button spinning with
+ * no answer.
+ */
+export declare const useRefreshControl: (accountIds: readonly string[], options?: UseRefreshControlOptions) => UseRefreshControlResult;