@remit/web-client 0.0.325 → 0.0.326

package/dist/src/lib/format.js

@@ -0,0 +1,269 @@
+import { trashSourceMeetsAssurance, } from "@remit/data-ports/folder-role";
+/**
+ * Get the user's preferred locale from browser settings.
+ * Falls back to 'en-US' if unavailable.
+ */
+const getLocale = () => {
+    if (typeof navigator !== "undefined") {
+        return navigator.language || navigator.languages?.[0] || "en-US";
+    }
+    return "en-US";
+};
+/**
+ * Format a number according to user's locale.
+ */
+export const formatNumber = (value, options) => {
+    return new Intl.NumberFormat(getLocale(), options).format(value);
+};
+const EPOCH_STRING = /^-?\d+$/;
+/**
+ * Coerce any accepted date input into a Date. An all-digit string is treated as
+ * an epoch (the Postgres read path serializes int64 columns as numeric strings);
+ * any other string goes through the normal Date parser.
+ */
+export const toDate = (value) => {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === "number")
+        return new Date(value);
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (EPOCH_STRING.test(trimmed))
+            return new Date(Number(trimmed));
+        return new Date(trimmed);
+    }
+    return new Date(Number.NaN);
+};
+const isValidDate = (date) => Number.isFinite(date.getTime());
+/**
+ * Format a date according to user's locale. A missing or unparseable date
+ * renders as an empty string instead of throwing — display must never crash the
+ * view over one bad row.
+ */
+export const formatDate = (date, options) => {
+    const d = toDate(date);
+    if (!isValidDate(d))
+        return "";
+    return new Intl.DateTimeFormat(getLocale(), options).format(d);
+};
+/**
+ * Format date with common presets.
+ */
+export const formatDatePreset = (date, preset) => {
+    const presets = {
+        short: { month: "short", day: "numeric" },
+        medium: { month: "short", day: "numeric", year: "numeric" },
+        long: { month: "long", day: "numeric", year: "numeric" },
+        full: { weekday: "long", month: "long", day: "numeric", year: "numeric" },
+        time: { hour: "numeric", minute: "numeric" },
+        datetime: {
+            month: "short",
+            day: "numeric",
+            hour: "numeric",
+            minute: "numeric",
+        },
+    };
+    return formatDate(date, presets[preset]);
+};
+/**
+ * Format relative time (e.g., "2 hours ago", "in 3 days").
+ */
+export const formatRelativeTime = (date) => {
+    const d = toDate(date);
+    if (!isValidDate(d))
+        return "";
+    const rtf = new Intl.RelativeTimeFormat(getLocale(), { numeric: "auto" });
+    const now = Date.now();
+    const diff = d.getTime() - now;
+    const diffSeconds = Math.round(diff / 1000);
+    const diffMinutes = Math.round(diff / (1000 * 60));
+    const diffHours = Math.round(diff / (1000 * 60 * 60));
+    const diffDays = Math.round(diff / (1000 * 60 * 60 * 24));
+    const diffWeeks = Math.round(diff / (1000 * 60 * 60 * 24 * 7));
+    if (Math.abs(diffSeconds) < 60) {
+        return rtf.format(diffSeconds, "second");
+    }
+    if (Math.abs(diffMinutes) < 60) {
+        return rtf.format(diffMinutes, "minute");
+    }
+    if (Math.abs(diffHours) < 24) {
+        return rtf.format(diffHours, "hour");
+    }
+    if (Math.abs(diffDays) < 7) {
+        return rtf.format(diffDays, "day");
+    }
+    if (Math.abs(diffWeeks) < 4) {
+        return rtf.format(diffWeeks, "week");
+    }
+    return formatDatePreset(d, "medium");
+};
+/**
+ * Format email date intelligently based on age.
+ * - Today: "10:42" (time only)
+ * - Yesterday: "Yesterday"
+ * - This week: "Tuesday" (day name)
+ * - Older: "Jan 17" (or "Jan 17, 2023" if different year)
+ */
+export const formatEmailDate = (date) => {
+    const d = toDate(date);
+    if (!isValidDate(d))
+        return "";
+    const now = new Date();
+    const isToday = d.toDateString() === now.toDateString();
+    const yesterday = new Date(now);
+    yesterday.setDate(yesterday.getDate() - 1);
+    const isYesterday = d.toDateString() === yesterday.toDateString();
+    const sixDaysAgo = new Date(now);
+    sixDaysAgo.setDate(sixDaysAgo.getDate() - 6);
+    const isThisWeek = d >= sixDaysAgo && d < now;
+    const isThisYear = d.getFullYear() === now.getFullYear();
+    if (isToday) {
+        return formatDate(d, { hour: "numeric", minute: "numeric" });
+    }
+    if (isYesterday) {
+        return "Yesterday";
+    }
+    if (isThisWeek) {
+        return formatDate(d, { weekday: "long" });
+    }
+    if (isThisYear) {
+        return formatDate(d, { month: "short", day: "numeric" });
+    }
+    return formatDate(d, { month: "short", day: "numeric", year: "numeric" });
+};
+/**
+ * Confirmation title for the move-to-Trash delete flow. Reflects that delete
+ * moves messages to Trash (not a permanent delete) and pluralizes on count.
+ * The count is always a concrete list of ids — every predicate delete ends on
+ * the wizard's review screen instead, which states what the predicate covers.
+ */
+export const formatDeleteToTrashTitle = (count) => {
+    const quantity = count === 1 ? "1" : formatNumber(count);
+    const noun = count === 1 ? "message" : "messages";
+    return `Move ${quantity} ${noun} to Trash?`;
+};
+/**
+ * The outcome of deleting `targets`.
+ *
+ * One row bound for an expunge makes the whole delete unrecoverable, so a mixed
+ * set is permanent: the wording may overstate what is destroyed, never what is
+ * kept. One row on an account with no Trash refuses the whole call, so that
+ * outranks both. An expunge on a Trash nobody confirmed outranks a plain
+ * expunge in turn — the server refuses it (#876), so the dialog asks for the
+ * same confirmation up front rather than offering a confirm that 409s. Pure,
+ * so every branch — the failure ones above all — is testable without a DOM.
+ */
+export const deleteOutcomeFor = ({ targets, trashByAccount, hasAppointments, isError, }) => {
+    if (isError)
+        return "unavailable";
+    if (!hasAppointments)
+        return "unknown";
+    if (targets.length === 0)
+        return "unknown";
+    let expunges = false;
+    let expungesUnconfirmed = false;
+    for (const target of targets) {
+        if (target.accountId === undefined)
+            return "unknown";
+        const trash = trashByAccount.get(target.accountId);
+        if (trash === undefined)
+            return "unknown";
+        if (trash.source === "Stale")
+            return "staleTrash";
+        if (trash.mailboxId === undefined)
+            return "noTrash";
+        if (trash.mailboxId === target.mailboxId) {
+            expunges = true;
+            if (!trashSourceMeetsAssurance(trash.source, "confirmed"))
+                expungesUnconfirmed = true;
+        }
+    }
+    if (expungesUnconfirmed)
+        return "unconfirmed";
+    return expunges ? "permanent" : "trash";
+};
+/**
+ * The delete erases mail rather than filing it. Both outcomes a row already
+ * inside Trash produces say so — `unconfirmed` is only ever reached that way
+ * (#876) — and anything that reports what a delete did reads this rather than
+ * testing for `permanent`, which is how a run of expunged mail came to be
+ * announced as "moved to Trash".
+ */
+export const deleteExpunges = (outcome) => outcome === "permanent" || outcome === "unconfirmed";
+/**
+ * The confirmation for a delete, worded for what the delete actually does.
+ * Deleting mail that already sits in Trash expunges it on the server and
+ * nothing survives that, so it is asked as a permanent delete — a dialog that
+ * says "Move to Trash" over an expunge collects an answer to a question the
+ * user was never asked.
+ *
+ * `noTrash`, `staleTrash`, `unconfirmed` and `unavailable` are not
+ * confirmations at all but refusals: nothing is deleted, and the label names
+ * the way out rather than the delete. The first three are answered in place by
+ * the appointment prompt — a link to Settings as the only remedy leaves the
+ * user to reassemble what they were doing. `unavailable` still routes to
+ * re-authentication, because an account read that fails is a session that ended
+ * under the reader far more often than it is anything else.
+ */
+export const deleteConfirmationCopy = (count, outcome, context = {}) => {
+    const quantity = count === 1 ? "1" : formatNumber(count);
+    const noun = count === 1 ? "message" : "messages";
+    const { trashFolderLabel, staleFolderLabel } = context;
+    if (outcome === "noTrash") {
+        return {
+            title: `Can't delete ${quantity} ${noun} yet`,
+            description: "No folder on this account is set as Trash, so there is nowhere to move the mail. Nothing has been deleted.",
+            confirmLabel: "Pick a Trash folder",
+        };
+    }
+    if (outcome === "staleTrash") {
+        return {
+            title: `Can't delete ${quantity} ${noun} yet`,
+            description: staleFolderLabel
+                ? `The folder you set as this account's Trash — ${staleFolderLabel} — is gone from the mail server. Nothing has been deleted.`
+                : "The folder you set as this account's Trash is gone from the mail server. Nothing has been deleted.",
+            confirmLabel: "Pick another folder",
+        };
+    }
+    if (outcome === "unconfirmed") {
+        const folderClause = trashFolderLabel
+            ? `reader files this account's deleted mail in ${trashFolderLabel} because of its name — nobody confirmed it.`
+            : "reader files this account's deleted mail in a folder it matched by name — nobody confirmed it.";
+        // count === 0: Empty Trash, acting on everything the folder holds. A
+        // positive count: a delete whose rows already sit in that folder, so
+        // this expunges them specifically, not the folder's whole contents.
+        return {
+            title: "Confirm this account's Trash folder",
+            description: count > 0
+                ? `${folderClause} Deleting ${quantity} ${noun} there erases them from the mail server, and that cannot be restored. Nothing has been deleted.`
+                : `${folderClause} Emptying a folder erases everything in it from the mail server, and that cannot be restored. Nothing has been emptied.`,
+            confirmLabel: "Confirm the folder",
+        };
+    }
+    if (outcome === "unavailable") {
+        return {
+            title: `Can't delete ${quantity} ${noun}`,
+            description: "reader couldn't read this account's folder settings, so it can't say whether this would move the mail to Trash or erase it. Nothing has been deleted.",
+            confirmLabel: "Sign in again",
+        };
+    }
+    if (outcome === "unknown") {
+        return {
+            title: `Delete ${quantity} ${noun}?`,
+            description: "Checking where this account files deleted mail…",
+            confirmLabel: "Delete",
+        };
+    }
+    if (outcome === "permanent") {
+        return {
+            title: `Permanently delete ${quantity} ${noun}?`,
+            description: "They are erased from the mail server and cannot be restored.",
+            confirmLabel: "Delete permanently",
+        };
+    }
+    return {
+        title: formatDeleteToTrashTitle(count),
+        description: "You can restore them from Trash later.",
+        confirmLabel: "Move to Trash",
+    };
+};

package/dist/src/lib/fresh-mailbox-count.d.ts

@@ -0,0 +1,76 @@
+/**
+ * How many messages a folder holds *on the mail server*, rather than how many
+ * the last sync round left in the local row.
+ *
+ * Every count the client can read — the mailbox row's `messageCount`, and so
+ * the folder list and the sync-status projection over it — is whatever the last
+ * round wrote. Mail that arrived since is invisible in it, which is fine for a
+ * badge and fatal for a delete: `deleteMailbox` takes the folder's mail with it
+ * and IMAP has no undo.
+ *
+ * So the count is taken from a round asked for on the spot: trigger a sync,
+ * then wait for the folder's `lastSyncedAt` to advance past the stamp read
+ * before the trigger, and read the count that round wrote alongside it (every
+ * message-sync round writes both from the same IMAP STATUS).
+ *
+ * What the advancing stamp proves is that *some* round's write landed after the
+ * baseline read — not necessarily the round this triggered. A round already in
+ * flight can land first and satisfy the wait. That is accepted: its STATUS was
+ * taken within milliseconds of the baseline, and the error it can carry is a
+ * count from a moment too early, which either agrees with the trigger's round
+ * or reports mail the folder had and the delete then refuses. The mistake lands
+ * on the side of not deleting.
+ *
+ * Nothing here decides on a count read before the trigger, and every way out
+ * other than an advanced stamp throws or reports `pending`: a folder missing
+ * from the account, a failed read, an aborted wait. Uncertainty about what a
+ * folder holds is never permission to delete it.
+ */
+/** The read fields the wait needs off a sync-status entry. */
+export interface MailboxCountReading {
+    mailboxId: string;
+    messagesTotal: number;
+    lastSyncedAt?: number;
+}
+/** A count from a round that reported after the baseline, or no round yet. */
+export type FreshCountOutcome = {
+    status: "fresh";
+    messageCount: number;
+} | {
+    status: "pending";
+};
+export interface AwaitFreshMailboxCountOptions {
+    /** Reads every mailbox's sync-status entry; called once per poll. */
+    readMailboxes: () => Promise<readonly MailboxCountReading[]>;
+    /** The folder to count. */
+    mailboxId: string;
+    /** The folder's `lastSyncedAt` as read before the sync was triggered. */
+    since: number;
+    /** Aborts the wait; a round that lands afterwards resolves nothing. */
+    signal?: AbortSignal;
+    /** How long this stretch of waiting runs before reporting `pending`. */
+    segmentMs?: number;
+    pollIntervalMs?: number;
+    /** Injectable clock/sleep for tests. */
+    delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * How long one stretch of waiting runs before handing the decision back to the
+ * user. An explicit sync fans the whole account out on one FIFO group with
+ * INBOX first, so a folder on a large account can sit behind minutes of other
+ * mailboxes: this is not long enough to conclude anything, only long enough
+ * that someone watching a spinner deserves to be asked whether to keep waiting.
+ */
+export declare const FRESH_COUNT_SEGMENT_MS = 120000;
+export declare const FRESH_COUNT_POLL_INTERVAL_MS = 2000;
+export declare const FRESH_COUNT_MISSING_MESSAGE = "This folder is no longer in the account's folder list, so nothing was deleted.";
+/** The folder's last sync stamp, or a refusal when the account does not list it. */
+export declare const mailboxSyncStamp: (mailboxes: readonly MailboxCountReading[], mailboxId: string) => number;
+/**
+ * Poll for one segment. Resolves `fresh` with the count once a round reports
+ * past `since`, `pending` when the segment runs out with the folder still
+ * unreported — the caller asks the user whether to wait on, and calling again
+ * with the same `since` resumes without triggering a second round.
+ */
+export declare function awaitFreshMailboxCount({ readMailboxes, mailboxId, since, signal, segmentMs, pollIntervalMs, delay, now, }: AwaitFreshMailboxCountOptions): Promise<FreshCountOutcome>;

package/dist/src/lib/fresh-mailbox-count.js

@@ -0,0 +1,37 @@
+import { abortableDelay } from "./mailbox-sync-wait";
+/**
+ * How long one stretch of waiting runs before handing the decision back to the
+ * user. An explicit sync fans the whole account out on one FIFO group with
+ * INBOX first, so a folder on a large account can sit behind minutes of other
+ * mailboxes: this is not long enough to conclude anything, only long enough
+ * that someone watching a spinner deserves to be asked whether to keep waiting.
+ */
+export const FRESH_COUNT_SEGMENT_MS = 120_000;
+export const FRESH_COUNT_POLL_INTERVAL_MS = 2_000;
+export const FRESH_COUNT_MISSING_MESSAGE = "This folder is no longer in the account's folder list, so nothing was deleted.";
+const entryFor = (mailboxes, mailboxId) => {
+    const entry = mailboxes.find((mailbox) => mailbox.mailboxId === mailboxId);
+    if (!entry)
+        throw new Error(FRESH_COUNT_MISSING_MESSAGE);
+    return entry;
+};
+/** The folder's last sync stamp, or a refusal when the account does not list it. */
+export const mailboxSyncStamp = (mailboxes, mailboxId) => entryFor(mailboxes, mailboxId).lastSyncedAt ?? 0;
+/**
+ * Poll for one segment. Resolves `fresh` with the count once a round reports
+ * past `since`, `pending` when the segment runs out with the folder still
+ * unreported — the caller asks the user whether to wait on, and calling again
+ * with the same `since` resumes without triggering a second round.
+ */
+export async function awaitFreshMailboxCount({ readMailboxes, mailboxId, since, signal, segmentMs = FRESH_COUNT_SEGMENT_MS, pollIntervalMs = FRESH_COUNT_POLL_INTERVAL_MS, delay = abortableDelay, now = Date.now, }) {
+    const deadline = now() + segmentMs;
+    for (;;) {
+        signal?.throwIfAborted();
+        const entry = entryFor(await readMailboxes(), mailboxId);
+        if ((entry.lastSyncedAt ?? 0) > since)
+            return { status: "fresh", messageCount: entry.messagesTotal };
+        if (now() >= deadline)
+            return { status: "pending" };
+        await delay(pollIntervalMs, signal);
+    }
+}

package/dist/src/lib/hot-sync-window.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A short window of faster background syncing, opened by a person pressing
+ * refresh.
+ *
+ * Pressing refresh says "I am waiting on mail", and the reply people expect is
+ * not one round but the next few minutes: a reply lands, a colleague answers,
+ * the transfer confirms. The ambient cadence alone would leave that mail up to
+ * a full interval away, so the press widens the tab's own poll for a few
+ * minutes and then lets it fall back.
+ *
+ * Module state rather than context: the press happens in the refresh control
+ * and the polling happens in `useStaleAccountSync`, two hooks with no common
+ * ancestor that owns this, and the window belongs to the tab either way.
+ */
+/** How long a press keeps the tab polling on the hot cadence. */
+export declare const HOT_WINDOW_MS: number;
+/** The cadence inside the window. Never faster: `POST /sync` skips the
+ * server's per-mailbox freshness gate, so every tick is a real folder-by-folder
+ * fan-out for every open account. */
+export declare const HOT_POLL_INTERVAL_MS: number;
+/** Open (or re-open) the window. Called on a refresh press, never on a timer. */
+export declare const startHotSyncWindow: (now?: number) => void;
+export declare const isHotSyncWindowActive: (now?: number) => boolean;
+/** Notifies on every press so a poll loop already asleep on the ambient
+ * interval can reschedule onto the hot one instead of finishing its long wait
+ * first. */
+export declare const subscribeHotSyncWindow: (listener: () => void) => (() => void);
+export declare const __resetHotSyncWindow: () => void;

package/dist/src/lib/hot-sync-window.js

@@ -0,0 +1,41 @@
+/**
+ * A short window of faster background syncing, opened by a person pressing
+ * refresh.
+ *
+ * Pressing refresh says "I am waiting on mail", and the reply people expect is
+ * not one round but the next few minutes: a reply lands, a colleague answers,
+ * the transfer confirms. The ambient cadence alone would leave that mail up to
+ * a full interval away, so the press widens the tab's own poll for a few
+ * minutes and then lets it fall back.
+ *
+ * Module state rather than context: the press happens in the refresh control
+ * and the polling happens in `useStaleAccountSync`, two hooks with no common
+ * ancestor that owns this, and the window belongs to the tab either way.
+ */
+/** How long a press keeps the tab polling on the hot cadence. */
+export const HOT_WINDOW_MS = 3 * 60 * 1000;
+/** The cadence inside the window. Never faster: `POST /sync` skips the
+ * server's per-mailbox freshness gate, so every tick is a real folder-by-folder
+ * fan-out for every open account. */
+export const HOT_POLL_INTERVAL_MS = 30 * 1000;
+let hotUntil = 0;
+const listeners = new Set();
+/** Open (or re-open) the window. Called on a refresh press, never on a timer. */
+export const startHotSyncWindow = (now = Date.now()) => {
+    hotUntil = now + HOT_WINDOW_MS;
+    for (const listener of listeners)
+        listener();
+};
+export const isHotSyncWindowActive = (now = Date.now()) => now < hotUntil;
+/** Notifies on every press so a poll loop already asleep on the ambient
+ * interval can reschedule onto the hot one instead of finishing its long wait
+ * first. */
+export const subscribeHotSyncWindow = (listener) => {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+};
+export const __resetHotSyncWindow = () => {
+    hotUntil = 0;
+};

package/dist/src/lib/i18n.d.ts

@@ -0,0 +1,2 @@
+import i18n from "i18next";
+export default i18n;

package/dist/src/lib/i18n.js

@@ -0,0 +1,29 @@
+import i18n from "i18next";
+import LanguageDetector from "i18next-browser-languagedetector";
+import Backend from "i18next-http-backend";
+import { initReactI18next } from "react-i18next";
+i18n
+    .use(Backend)
+    .use(LanguageDetector)
+    .use(initReactI18next)
+    .init({
+    fallbackLng: "en",
+    supportedLngs: ["en", "nl", "de", "fr"],
+    ns: ["common", "mail"],
+    defaultNS: "common",
+    backend: {
+        loadPath: "/locales/{{lng}}/{{ns}}.json",
+    },
+    detection: {
+        order: ["navigator", "htmlTag"],
+        caches: [],
+    },
+    interpolation: {
+        escapeValue: false,
+    },
+    react: {
+        useSuspense: true,
+        bindI18n: "languageChanged loaded",
+    },
+});
+export default i18n;

package/dist/src/lib/inbox-filters.d.ts

@@ -0,0 +1,76 @@
+import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
+import { type FilterReach } from "@remit/ui";
+/** The request `threadOperationsSearchThreads` takes, whole. */
+export type ThreadSearchQuery = NonNullable<ThreadOperationsSearchThreadsData["query"]>;
+/**
+ * The parameters the filter chips set on a thread listing.
+ *
+ * Named for the inbox, which had them first, but shared: `listAllThreads` takes
+ * the same four (#308), so the Flagged view sends the chips through this rather
+ * than growing a second translation of the same chip ids.
+ */
+export type InboxFilterParams = Pick<ThreadSearchQuery, "category" | "unread" | "starred" | "attachments">;
+/** The chip state a filtered list holds: one category, any number of attributes. */
+export interface InboxFilterCriteria {
+    /** A category id, or `"all"` when the category is cleared. */
+    category: string;
+    attributes: ReadonlySet<string>;
+}
+/** Whether the chips narrow the list at all — `"all"` and no attributes do not. */
+export declare const hasInboxFilter: (criteria: InboxFilterCriteria) => boolean;
+/**
+ * The chips as search parameters, so the server returns a page of matches
+ * rather than a page the browser then thins out. A category chip that names no
+ * category — `"all"`, or an id the enum no longer carries — sets no parameter,
+ * and `uncategorized` is a category like any other: the pending state's name,
+ * never the absence of one (issue #45).
+ *
+ * Only the parameters a chip switches on are present, so this merges with the
+ * search tokens (`is:unread`, `has:attachment`) as a union: where a chip and a
+ * token set the same parameter they agree on `true`.
+ */
+export declare const inboxFilterParams: (criteria: InboxFilterCriteria) => InboxFilterParams;
+/**
+ * How much of the mailbox a request reaches, read off the request itself.
+ *
+ * Every criterion the inbox sends today is a column on the row, so the server
+ * answers with a `where` over the whole mailbox and an empty result means the
+ * folder holds no matching mail. `senderTrust` and `dkimMismatch` are resolved
+ * by enriching a bounded window instead (design D7, D10), so a request carrying
+ * either has only seen the pages it read. Derived rather than declared: the
+ * completeness sentence the empty state renders is true of the query that was
+ * issued, not of the criteria that happen to ship today.
+ */
+export declare const filterReach: (query: ThreadSearchQuery) => FilterReach;
+/**
+ * A list request's narrowing parameters, as far as the previous-data guard
+ * reads them. The chips, plus the two scopes a view sets for itself: the
+ * account the pills name, and whether muted senders are in.
+ *
+ * The text parameters are deliberately absent, `from` and `subject` with the
+ * free text: all three are typed in one field, and a query being refined is the
+ * one change that may keep the previous answer on screen while the next is in
+ * flight.
+ */
+export type ListFilterParams = InboxFilterParams & {
+    accountId?: string;
+    muted?: boolean;
+};
+/**
+ * Whether a cached list query was fetched under the same filter the request
+ * being made now carries.
+ *
+ * `keepPreviousData` renders the previous key's rows while a new page is in
+ * flight. That is right for a query the user is still typing and wrong the
+ * moment the filter changes: the previous predicate's mail would show under the
+ * new chip for one round trip, which is the failure this correction is about
+ * (design D18). An unrecognized key answers `false`, so the doubtful case
+ * restarts the list rather than rendering rows it cannot vouch for.
+ */
+export declare const sameInboxFilter: (queryKey: unknown, params: ListFilterParams) => boolean;
+/**
+ * The label the empty state names an active category filter by, or undefined
+ * when the id names no category — `"all"` is how the category is cleared, not a
+ * category.
+ */
+export declare const categoryLabel: (id: string) => string | undefined;

package/dist/src/lib/inbox-filters.js

@@ -0,0 +1,95 @@
+import { MessageCategory } from "@remit/domain-enums";
+import { categoryLabels, isThreadCategory } from "@remit/ui";
+/**
+ * The search parameter each attribute chip sets. `flagged` is the wire name for
+ * IMAP \Flagged, which the API calls `starred`; the label is "Starred".
+ */
+const ATTRIBUTE_PARAMS = {
+    unread: "unread",
+    flagged: "starred",
+    attachment: "attachments",
+};
+const CATEGORY_VALUES = new Set(Object.values(MessageCategory));
+const isMessageCategory = (id) => CATEGORY_VALUES.has(id);
+/** Whether the chips narrow the list at all — `"all"` and no attributes do not. */
+export const hasInboxFilter = (criteria) => isMessageCategory(criteria.category) || criteria.attributes.size > 0;
+/**
+ * The chips as search parameters, so the server returns a page of matches
+ * rather than a page the browser then thins out. A category chip that names no
+ * category — `"all"`, or an id the enum no longer carries — sets no parameter,
+ * and `uncategorized` is a category like any other: the pending state's name,
+ * never the absence of one (issue #45).
+ *
+ * Only the parameters a chip switches on are present, so this merges with the
+ * search tokens (`is:unread`, `has:attachment`) as a union: where a chip and a
+ * token set the same parameter they agree on `true`.
+ */
+export const inboxFilterParams = (criteria) => {
+    const params = {};
+    if (isMessageCategory(criteria.category)) {
+        params.category = [criteria.category];
+    }
+    for (const id of criteria.attributes) {
+        const param = ATTRIBUTE_PARAMS[id];
+        if (param)
+            params[param] = true;
+    }
+    return params;
+};
+/**
+ * How much of the mailbox a request reaches, read off the request itself.
+ *
+ * Every criterion the inbox sends today is a column on the row, so the server
+ * answers with a `where` over the whole mailbox and an empty result means the
+ * folder holds no matching mail. `senderTrust` and `dkimMismatch` are resolved
+ * by enriching a bounded window instead (design D7, D10), so a request carrying
+ * either has only seen the pages it read. Derived rather than declared: the
+ * completeness sentence the empty state renders is true of the query that was
+ * issued, not of the criteria that happen to ship today.
+ */
+export const filterReach = (query) => (query.senderTrust?.length ?? 0) > 0 || query.dkimMismatch !== undefined
+    ? "loaded-pages"
+    : "whole-folder";
+const FILTER_PARAM_NAMES = [
+    "category",
+    "unread",
+    "starred",
+    "attachments",
+    "accountId",
+    "muted",
+];
+const filterIdentity = (query) => JSON.stringify(FILTER_PARAM_NAMES.map((name) => query?.[name] ?? null));
+const queryOf = (queryKey) => {
+    if (!Array.isArray(queryKey))
+        return undefined;
+    const [entry] = queryKey;
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const query = entry.query;
+    if (typeof query !== "object" || query === null)
+        return undefined;
+    return query;
+};
+/**
+ * Whether a cached list query was fetched under the same filter the request
+ * being made now carries.
+ *
+ * `keepPreviousData` renders the previous key's rows while a new page is in
+ * flight. That is right for a query the user is still typing and wrong the
+ * moment the filter changes: the previous predicate's mail would show under the
+ * new chip for one round trip, which is the failure this correction is about
+ * (design D18). An unrecognized key answers `false`, so the doubtful case
+ * restarts the list rather than rendering rows it cannot vouch for.
+ */
+export const sameInboxFilter = (queryKey, params) => {
+    const previous = queryOf(queryKey);
+    if (!previous)
+        return false;
+    return filterIdentity(previous) === filterIdentity(params);
+};
+/**
+ * The label the empty state names an active category filter by, or undefined
+ * when the id names no category — `"all"` is how the category is cleared, not a
+ * category.
+ */
+export const categoryLabel = (id) => isThreadCategory(id) ? categoryLabels[id] : undefined;