@remit/web-client 0.0.324 → 0.0.326

package/dist/src/hooks/useLabels.js

@@ -0,0 +1,98 @@
+import { labelDetailOperationsDeleteLabelMutation, labelDetailOperationsUpdateLabelMutation, labelOperationsCreateLabelMutation, labelOperationsListLabelsOptions, labelOperationsListLabelsQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+/**
+ * The query key the label list reads and every mutation invalidates on
+ * success — the same contract `buildFilterListKey` pins for filters, so the
+ * settings list and the rule editor's label picker never go stale after a
+ * label is created, renamed, recolored, or deleted (issue #26).
+ */
+export const buildLabelListKey = (accountId) => labelOperationsListLabelsQueryKey({ path: { accountId } });
+/** List the account's labels. */
+export const useLabelList = (accountId) => {
+    const query = useQuery({
+        ...labelOperationsListLabelsOptions({
+            path: { accountId: accountId ?? "" },
+        }),
+        enabled: !!accountId,
+    });
+    return {
+        labels: query.data?.items ?? [],
+        isPending: query.isPending,
+        isError: query.isError,
+        error: query.error,
+        refetch: query.refetch,
+    };
+};
+export const useCreateLabel = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...labelOperationsCreateLabelMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({ queryKey: buildLabelListKey(accountId) });
+        },
+    });
+    const { mutateAsync } = mutation;
+    const createLabel = useCallback((name, color = "Default") => {
+        if (!accountId)
+            return Promise.reject(new Error("No account"));
+        return mutateAsync({ path: { accountId }, body: { name, color } });
+    }, [accountId, mutateAsync]);
+    return {
+        createLabel,
+        isPending: mutation.isPending,
+        isError: mutation.isError,
+        error: mutation.error,
+        reset: mutation.reset,
+    };
+};
+export const useUpdateLabel = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...labelDetailOperationsUpdateLabelMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({ queryKey: buildLabelListKey(accountId) });
+        },
+    });
+    const { mutate } = mutation;
+    const updateLabel = useCallback((labelId, input) => {
+        if (!accountId)
+            return;
+        mutate({ path: { accountId, labelId }, body: input });
+    }, [accountId, mutate]);
+    return {
+        updateLabel,
+        isPending: mutation.isPending,
+        updatingLabelId: mutation.isPending
+            ? mutation.variables?.path.labelId
+            : undefined,
+    };
+};
+export const useDeleteLabel = (accountId) => {
+    const queryClient = useQueryClient();
+    const mutation = useMutation({
+        ...labelDetailOperationsDeleteLabelMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({ queryKey: buildLabelListKey(accountId) });
+        },
+    });
+    const { mutate } = mutation;
+    const deleteLabel = useCallback((labelId) => {
+        if (!accountId)
+            return;
+        mutate({ path: { accountId, labelId } });
+    }, [accountId, mutate]);
+    return {
+        deleteLabel,
+        isPending: mutation.isPending,
+        deletingLabelId: mutation.isPending
+            ? mutation.variables?.path.labelId
+            : undefined,
+    };
+};

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

@@ -0,0 +1,33 @@
+/**
+ * Responsive layout tiers for the mail shell:
+ *   - `phone`   (< 768px)        single pane: list → reading swaps in place.
+ *   - `tablet`  (768–1023px, or any width on a touch screen held upright)
+ *                                single pane, nav rail is drawer-backed.
+ *   - `desktop` (>= 1024px, not portrait-on-touch)
+ *                                full four-pane shell (nav · list · reading · pane 4).
+ *
+ * Pane 4 (intelligence) is desktop-only; `useIsDesktop` stays the pane-4 gate.
+ */
+export type LayoutTier = "phone" | "tablet" | "desktop";
+export declare const TABLET_MIN_WIDTH = 768;
+export interface ViewportProfile {
+    width: number;
+    orientation: "portrait" | "landscape";
+    pointer: "coarse" | "fine";
+}
+/** Pure tier resolution, so the logic is testable without a DOM. */
+export declare const resolveLayoutTier: ({ width, orientation, pointer, }: ViewportProfile) => LayoutTier;
+/**
+ * Whether the mail shell shows a SINGLE pane (no reading pane) at this tier.
+ * AppShellSlotted mounts the reading pane only at desktop, so both phone AND
+ * tablet are single-pane: the one pane swaps in place between the list, an
+ * open thread, and the compose surface. Compose therefore must mount via the
+ * single-pane view at tablet too — keying the pane choice off "phone" alone
+ * left tablet with no compose surface ("c" / FAB opened nothing).
+ */
+export declare const isSinglePaneTier: (tier: LayoutTier) => boolean;
+/**
+ * Returns the current layout tier. SSR-safe (falls back to `phone` before
+ * hydration, matching `useMatchMedia`'s server default).
+ */
+export declare const useLayoutTier: () => LayoutTier;

package/dist/src/hooks/useLayoutTier.js

@@ -0,0 +1,33 @@
+import { DESKTOP_MEDIA_QUERY, DESKTOP_MIN_WIDTH, useMatchMedia, } from "@remit/ui";
+export const TABLET_MIN_WIDTH = 768;
+/** Pure tier resolution, so the logic is testable without a DOM. */
+export const resolveLayoutTier = ({ width, orientation, pointer, }) => {
+    const heldUpright = orientation === "portrait" && pointer === "coarse";
+    if (width >= DESKTOP_MIN_WIDTH && !heldUpright)
+        return "desktop";
+    if (width >= TABLET_MIN_WIDTH)
+        return "tablet";
+    return "phone";
+};
+/**
+ * Whether the mail shell shows a SINGLE pane (no reading pane) at this tier.
+ * AppShellSlotted mounts the reading pane only at desktop, so both phone AND
+ * tablet are single-pane: the one pane swaps in place between the list, an
+ * open thread, and the compose surface. Compose therefore must mount via the
+ * single-pane view at tablet too — keying the pane choice off "phone" alone
+ * left tablet with no compose surface ("c" / FAB opened nothing).
+ */
+export const isSinglePaneTier = (tier) => tier !== "desktop";
+/**
+ * Returns the current layout tier. SSR-safe (falls back to `phone` before
+ * hydration, matching `useMatchMedia`'s server default).
+ */
+export const useLayoutTier = () => {
+    const isTabletUp = useMatchMedia(`(min-width: ${TABLET_MIN_WIDTH}px)`);
+    const isDesktop = useMatchMedia(DESKTOP_MEDIA_QUERY);
+    if (isDesktop)
+        return "desktop";
+    if (isTabletUp)
+        return "tablet";
+    return "phone";
+};

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

@@ -0,0 +1,18 @@
+interface MailboxAccountResolution {
+    accountId: string | undefined;
+    isLoading: boolean;
+}
+/**
+ * Resolve the owning account for a single mailbox by id.
+ *
+ * The mailbox-list query is keyed by accountId, so we fan out to every
+ * configured account's mailbox list (cached forever, see sidebar) and find
+ * the one containing this mailboxId. Returns `accountId: undefined` while
+ * the lookup is still loading or if the mailbox isn't found in any account.
+ *
+ * Used by per-message Move actions where the `MessageActionMenu` only knows
+ * the mailboxId — the picker must scope to the correct account or the
+ * destination list would mix folders from unrelated accounts.
+ */
+export declare const useMailboxAccount: (mailboxId: string | undefined) => MailboxAccountResolution;
+export {};

package/dist/src/hooks/useMailboxAccount.js

@@ -0,0 +1,48 @@
+import { configOperationsGetConfigOptions, mailboxOperationsListMailboxesOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+/**
+ * Resolve the owning account for a single mailbox by id.
+ *
+ * The mailbox-list query is keyed by accountId, so we fan out to every
+ * configured account's mailbox list (cached forever, see sidebar) and find
+ * the one containing this mailboxId. Returns `accountId: undefined` while
+ * the lookup is still loading or if the mailbox isn't found in any account.
+ *
+ * Used by per-message Move actions where the `MessageActionMenu` only knows
+ * the mailboxId — the picker must scope to the correct account or the
+ * destination list would mix folders from unrelated accounts.
+ */
+export const useMailboxAccount = (mailboxId) => {
+    // Disabled where there is no mailbox to resolve, the way the fan-out below
+    // already is. A caller that already knows its account passes `undefined` and
+    // this subscribes to nothing — which keeps the hook from pulling `/config`
+    // into trees that never asked for it.
+    const { data: config, isLoading: isConfigLoading } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+        enabled: !!mailboxId,
+    });
+    const accountIds = useMemo(() => (config?.accounts ?? []).map((account) => account.accountId), [config?.accounts]);
+    const mailboxQueries = useQueries({
+        queries: accountIds.map((accountId) => ({
+            ...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
+            staleTime: Infinity,
+            enabled: !!mailboxId,
+        })),
+    });
+    const isLoading = isConfigLoading || mailboxQueries.some((query) => query.isLoading);
+    const accountId = useMemo(() => {
+        if (!mailboxId)
+            return undefined;
+        for (let i = 0; i < accountIds.length; i++) {
+            const result = mailboxQueries[i];
+            const items = result.data?.items ?? [];
+            if (items.some((mailbox) => mailbox.mailboxId === mailboxId)) {
+                return accountIds[i];
+            }
+        }
+        return undefined;
+    }, [mailboxId, accountIds, mailboxQueries]);
+    return { accountId, isLoading };
+};

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

@@ -0,0 +1,2 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+export declare function useMailboxNameIndex(accounts: RemitImapAccountResponse[]): ReadonlyMap<string, string>;

package/dist/src/hooks/useMailboxNameIndex.js

@@ -0,0 +1,21 @@
+/**
+ * Fans out the per-account mailbox-list query (mirrors `MailSidebarAdapter` /
+ * `useMailboxAccount` — cached forever, react-query dedupes the identical
+ * query key across call sites) and reduces it to the name index `in:` tokens
+ * resolve against (#428 follow-up, see doc/design/flows/06-search.md).
+ */
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { buildMailboxNameIndex } from "../lib/search-token-index";
+export function useMailboxNameIndex(accounts) {
+    const mailboxQueries = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+    });
+    return useMemo(() => buildMailboxNameIndex(mailboxQueries.map((query) => query.data?.items ?? [])), [mailboxQueries]);
+}

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

@@ -0,0 +1,59 @@
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+interface UseMarkAsReadOptions {
+    messages: RemitImapThreadMessageResponse[];
+    expandedIds: Set<string>;
+    threadId: string;
+    mailboxId: string;
+    accountId?: string;
+}
+/**
+ * Dwell before a message the user is viewing is marked read. A glance closed
+ * within this window leaves it unread (#140). Applied by the single shared
+ * trigger below, so the daily brief and the mailbox thread views agree.
+ */
+export declare const MARK_READ_DELAY_MS = 3000;
+/**
+ * Fire `markRead` for `messageIds` after `delayMs`. Returns a canceller the
+ * caller runs on unmount or when the selection changes before the dwell
+ * elapses; an empty list schedules nothing, and a non-positive delay fires at
+ * once. Framework-agnostic so the timing can be exercised with fake timers.
+ */
+export declare const scheduleMarkRead: (messageIds: string[], delayMs: number, markRead: (ids: string[]) => void) => (() => void);
+/**
+ * The mailboxes whose cached listings a batch of message mutations affects.
+ *
+ * A conversation spans mailboxes (#46), so marking a thread read can touch a
+ * received message in INBOX and the user's own reply in Sent at once, and each
+ * one's lists live under its own mailbox key. Falls back to the browsed mailbox
+ * for ids the thread's messages do not cover.
+ */
+export declare const resolveMailboxesForMessages: (messageIds: Iterable<string>, messages: RemitImapThreadMessageResponse[], fallbackMailboxId: string) => string[];
+export declare const setReadOnItems: (items: RemitImapThreadMessageResponse[], messageIds: Set<string>, isRead: boolean) => RemitImapThreadMessageResponse[];
+/**
+ * Pure helper: pick the message IDs that should be marked as read.
+ *
+ * A message is eligible when it is currently unread, currently expanded,
+ * and has not already been marked (or is mid-flight) during this thread
+ * view. Extracted so the policy can be exercised without rendering React.
+ */
+export declare const selectMessagesToMarkRead: (messages: RemitImapThreadMessageResponse[], expandedIds: Set<string>, alreadyMarked: Set<string>, pending: Set<string>) => string[];
+export declare const useMarkAsRead: ({ messages, expandedIds, threadId, mailboxId, accountId, }: UseMarkAsReadOptions) => void;
+/**
+ * Standalone hook that exposes a `toggleReadFor` function to mark a set of
+ * messages as read or unread. Designed for multi-select mark-read (PR 1)
+ * and swipe-to-read (PR 2) use cases that operate outside a thread view.
+ */
+export declare const useToggleReadFor: (options: {
+    mailboxId: string;
+    accountId?: string;
+    /**
+     * The threads the ids may come from, when the caller has them. A selection in
+     * the brief or Flagged spans mailboxes, so the listings to invalidate are the
+     * ones each message actually lives in.
+     */
+    messages?: RemitImapThreadMessageResponse[];
+}) => {
+    toggleReadFor: (messageIds: string[], isRead: boolean) => void;
+    isPending: boolean;
+};
+export {};

package/dist/src/hooks/useMarkAsRead.js

@@ -0,0 +1,206 @@
+import { mailboxOperationsListMailboxesQueryKey, messageBulkOperationsUpdateFlagsMutation, threadDetailOperationsListThreadMessagesQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "../components/ui/error-banners";
+import { runChunkedMutation } from "../lib/bulk-actions";
+import { softErrorMeta } from "../lib/error-classifier";
+import { cancelThreadListQueries, invalidateThreadListQueries, patchThreadListQueries, restoreThreadListQueries, snapshotThreadListQueries, threadListCacheKeys, } from "../lib/thread-list-cache";
+/**
+ * Dwell before a message the user is viewing is marked read. A glance closed
+ * within this window leaves it unread (#140). Applied by the single shared
+ * trigger below, so the daily brief and the mailbox thread views agree.
+ */
+export const MARK_READ_DELAY_MS = 3000;
+/**
+ * Fire `markRead` for `messageIds` after `delayMs`. Returns a canceller the
+ * caller runs on unmount or when the selection changes before the dwell
+ * elapses; an empty list schedules nothing, and a non-positive delay fires at
+ * once. Framework-agnostic so the timing can be exercised with fake timers.
+ */
+export const scheduleMarkRead = (messageIds, delayMs, markRead) => {
+    if (messageIds.length === 0)
+        return () => { };
+    if (delayMs <= 0) {
+        markRead(messageIds);
+        return () => { };
+    }
+    const timer = setTimeout(() => markRead(messageIds), delayMs);
+    return () => clearTimeout(timer);
+};
+/**
+ * The mailboxes whose cached listings a batch of message mutations affects.
+ *
+ * A conversation spans mailboxes (#46), so marking a thread read can touch a
+ * received message in INBOX and the user's own reply in Sent at once, and each
+ * one's lists live under its own mailbox key. Falls back to the browsed mailbox
+ * for ids the thread's messages do not cover.
+ */
+export const resolveMailboxesForMessages = (messageIds, messages, fallbackMailboxId) => {
+    const byMessageId = new Map(messages.map((message) => [message.messageId, message.mailboxId]));
+    const mailboxIds = new Set();
+    for (const messageId of messageIds) {
+        mailboxIds.add(byMessageId.get(messageId) ?? fallbackMailboxId);
+    }
+    return [...mailboxIds];
+};
+export const setReadOnItems = (items, messageIds, isRead) => items.map((item) => messageIds.has(item.messageId) ? { ...item, isRead } : item);
+/**
+ * Pure helper: pick the message IDs that should be marked as read.
+ *
+ * A message is eligible when it is currently unread, currently expanded,
+ * and has not already been marked (or is mid-flight) during this thread
+ * view. Extracted so the policy can be exercised without rendering React.
+ */
+export const selectMessagesToMarkRead = (messages, expandedIds, alreadyMarked, pending) => messages
+    .filter((m) => !m.isRead &&
+    expandedIds.has(m.threadMessageId) &&
+    !alreadyMarked.has(m.messageId) &&
+    !pending.has(m.messageId))
+    .map((m) => m.messageId);
+export const useMarkAsRead = ({ messages, expandedIds, threadId, mailboxId, accountId, }) => {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const markedAsReadRef = useRef(new Set());
+    const pendingRef = useRef(new Set());
+    // Nobody asked for this write and nobody is waiting on it — it fires after a
+    // dwell on an open message. The rollback and the banner below are the whole
+    // of its failure, so a refusal must not take the screen down with it.
+    const { mutate: markAsRead } = useMutation({
+        ...messageBulkOperationsUpdateFlagsMutation(),
+        meta: softErrorMeta,
+        onMutate: async (variables) => {
+            const messageIds = new Set(variables.body.messageIds ?? []);
+            const isRead = variables.body.isRead ?? true;
+            const threadMessagesPrefix = threadDetailOperationsListThreadMessagesQueryKey({
+                path: { threadId },
+            });
+            const listPrefixes = threadListCacheKeys(resolveMailboxesForMessages(messageIds, messages, mailboxId));
+            await Promise.all([
+                queryClient.cancelQueries({ queryKey: threadMessagesPrefix }),
+                cancelThreadListQueries(queryClient, listPrefixes),
+            ]);
+            const previousThreadMessages = queryClient
+                .getQueriesData({ queryKey: threadMessagesPrefix })
+                .filter((entry) => entry[1] !== undefined)
+                .map(([queryKey, data]) => ({ queryKey, data }));
+            const previousThreadsList = snapshotThreadListQueries(queryClient, listPrefixes);
+            queryClient.setQueriesData({ queryKey: threadMessagesPrefix }, (old) => {
+                if (!old)
+                    return old;
+                return {
+                    ...old,
+                    items: setReadOnItems(old.items, messageIds, isRead),
+                };
+            });
+            patchThreadListQueries(queryClient, listPrefixes, (items) => setReadOnItems(items, messageIds, isRead));
+            return {
+                threadMessagesPrefix,
+                listPrefixes,
+                previousThreadMessages,
+                previousThreadsList,
+            };
+        },
+        onSuccess: (_data, variables) => {
+            const messageIds = variables.body.messageIds ?? [];
+            for (const id of messageIds) {
+                markedAsReadRef.current.add(id);
+                pendingRef.current.delete(id);
+            }
+        },
+        onError: (error, variables, context) => {
+            const messageIds = variables.body.messageIds ?? [];
+            for (const id of messageIds) {
+                pendingRef.current.delete(id);
+            }
+            if (context) {
+                for (const entry of context.previousThreadMessages) {
+                    queryClient.setQueryData(entry.queryKey, entry.data);
+                }
+                restoreThreadListQueries(queryClient, context.previousThreadsList);
+            }
+            const isRead = variables.body.isRead ?? true;
+            pushError({
+                title: isRead ? "Couldn't mark as read" : "Couldn't mark as unread",
+                detail: formatErrorDetail(error),
+                error,
+            });
+        },
+        onSettled: (_data, _err, _vars, context) => {
+            if (!context)
+                return;
+            queryClient.invalidateQueries({ queryKey: context.threadMessagesPrefix });
+            invalidateThreadListQueries(queryClient, context.listPrefixes);
+            // Refresh the sidebar mailbox list so the unread badge picks up the
+            // next backend `unseenCount` (which is owned by IMAP sync).
+            if (accountId) {
+                queryClient.invalidateQueries({
+                    queryKey: mailboxOperationsListMailboxesQueryKey({
+                        path: { accountId },
+                    }),
+                });
+            }
+        },
+    });
+    const markMessagesRead = useCallback((messageIds) => {
+        const idsToMark = messageIds.filter((id) => !markedAsReadRef.current.has(id) && !pendingRef.current.has(id));
+        if (idsToMark.length === 0)
+            return;
+        for (const id of idsToMark) {
+            pendingRef.current.add(id);
+        }
+        markAsRead({
+            body: {
+                messageIds: idsToMark,
+                isRead: true,
+            },
+        });
+    }, [markAsRead]);
+    const eligibleIds = useMemo(() => selectMessagesToMarkRead(messages, expandedIds, markedAsReadRef.current, pendingRef.current), [messages, expandedIds]);
+    // Mark as read after a short dwell on the open message. Changing the
+    // selection or leaving the view before the dwell elapses cancels the pending
+    // mark, so a glance stays unread (#140).
+    useEffect(() => scheduleMarkRead(eligibleIds, MARK_READ_DELAY_MS, markMessagesRead), [eligibleIds, markMessagesRead]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally clears state on threadId change; adding threadId to deps causes stale closure issues
+    useEffect(() => {
+        markedAsReadRef.current.clear();
+        pendingRef.current.clear();
+    }, [threadId]);
+};
+/**
+ * Standalone hook that exposes a `toggleReadFor` function to mark a set of
+ * messages as read or unread. Designed for multi-select mark-read (PR 1)
+ * and swipe-to-read (PR 2) use cases that operate outside a thread view.
+ */
+export const useToggleReadFor = (options) => {
+    const { mailboxId, accountId, messages } = options;
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const { mutateAsync, isPending } = useMutation({
+        ...messageBulkOperationsUpdateFlagsMutation(),
+        onError: (error, variables) => {
+            const isRead = variables.body.isRead ?? true;
+            pushError({
+                title: isRead ? "Couldn't mark as read" : "Couldn't mark as unread",
+                detail: formatErrorDetail(error),
+                error,
+            });
+        },
+        onSettled: (_data, _error, variables) => {
+            invalidateThreadListQueries(queryClient, threadListCacheKeys(resolveMailboxesForMessages(variables.body.messageIds ?? [], messages ?? [], mailboxId)));
+            if (accountId) {
+                queryClient.invalidateQueries({
+                    queryKey: mailboxOperationsListMailboxesQueryKey({
+                        path: { accountId },
+                    }),
+                });
+            }
+        },
+    });
+    const toggleReadFor = useCallback((messageIds, isRead) => {
+        if (messageIds.length === 0)
+            return;
+        void runChunkedMutation(messageIds, (chunk) => mutateAsync({ body: { messageIds: chunk, isRead } }));
+    }, [mutateAsync]);
+    return { toggleReadFor, isPending };
+};

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

@@ -0,0 +1,30 @@
+import { type WizardMessage } from "@remit/ui";
+import type { EscalationSearchQuery } from "./useEscalatedActions";
+/**
+ * The members of a match, read from the server that matched them.
+ *
+ * A widened match reaches mail the list never loaded, so these rows cannot come
+ * from the browser's own cache: an intersection with whatever happens to be
+ * loaded shows a handful of rows, or none, beside a server count of hundreds —
+ * which reads as "this matches nothing", the one conclusion #477 3.5 exists to
+ * prevent. The ids the count was counted over are the match, and the server
+ * describes each of them.
+ *
+ * Bounded to the first {@link SAMPLE_LIMIT}: the screen shows a sample in its
+ * own scrolling region and states the total beside it, so describing the whole
+ * match would be requests nobody reads.
+ */
+export declare const SAMPLE_LIMIT = 12;
+export interface MatchSample {
+    messages: WizardMessage[];
+    /** No rows yet because they are still arriving, which is not "no rows". */
+    isPending: boolean;
+}
+/**
+ * The members of an escalated predicate's match (#508). The predicate is the
+ * search the list is showing, so the search endpoint that resolved it is what
+ * names its members — one bounded request rather than the browser's own loaded
+ * rows, which stop at the page the list happens to have reached.
+ */
+export declare const useSearchMatchSample: (mailboxId: string | undefined, query: EscalationSearchQuery | undefined) => MatchSample;
+export declare const useMatchSample: (messageIds: readonly string[]) => MatchSample;

package/dist/src/hooks/useMatchSample.js

@@ -0,0 +1,74 @@
+import { messageOperationsDescribeMessageOptions, threadOperationsSearchThreadsOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { senderLabel } from "@remit/ui";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { formatEmailDate } from "../lib/format";
+/**
+ * The members of a match, read from the server that matched them.
+ *
+ * A widened match reaches mail the list never loaded, so these rows cannot come
+ * from the browser's own cache: an intersection with whatever happens to be
+ * loaded shows a handful of rows, or none, beside a server count of hundreds —
+ * which reads as "this matches nothing", the one conclusion #477 3.5 exists to
+ * prevent. The ids the count was counted over are the match, and the server
+ * describes each of them.
+ *
+ * Bounded to the first {@link SAMPLE_LIMIT}: the screen shows a sample in its
+ * own scrolling region and states the total beside it, so describing the whole
+ * match would be requests nobody reads.
+ */
+export const SAMPLE_LIMIT = 12;
+const toWizardMessage = (described) => {
+    const { envelope } = described;
+    const from = envelope.from[0];
+    return {
+        id: envelope.messageId,
+        sender: from
+            ? senderLabel({
+                normalizedEmail: from.normalizedEmail,
+                displayName: from.displayName,
+            })
+            : "Unknown",
+        subject: envelope.subject ?? "(No subject)",
+        date: formatEmailDate(envelope.date),
+    };
+};
+/**
+ * The members of an escalated predicate's match (#508). The predicate is the
+ * search the list is showing, so the search endpoint that resolved it is what
+ * names its members — one bounded request rather than the browser's own loaded
+ * rows, which stop at the page the list happens to have reached.
+ */
+export const useSearchMatchSample = (mailboxId, query) => {
+    const enabled = mailboxId !== undefined && query !== undefined;
+    const { data, isLoading } = useQuery({
+        ...threadOperationsSearchThreadsOptions({
+            path: { mailboxId: mailboxId ?? "" },
+            query: { ...query, limit: SAMPLE_LIMIT },
+        }),
+        enabled,
+        staleTime: 30_000,
+    });
+    return {
+        messages: (data?.items ?? []).map(toSearchWizardMessage),
+        isPending: enabled && isLoading,
+    };
+};
+const toSearchWizardMessage = (row) => ({
+    id: row.messageId,
+    sender: row.fromName || row.fromEmail || "Unknown",
+    subject: row.subject ?? "(No subject)",
+    date: formatEmailDate(row.sentDate),
+});
+export const useMatchSample = (messageIds) => useQueries({
+    queries: messageIds.slice(0, SAMPLE_LIMIT).map((messageId) => ({
+        ...messageOperationsDescribeMessageOptions({ path: { messageId } }),
+        staleTime: Number.POSITIVE_INFINITY,
+    })),
+    combine: (results) => ({
+        messages: results
+            .map((result) => result.data)
+            .filter((data) => data !== undefined)
+            .map(toWizardMessage),
+        isPending: results.some((result) => result.isPending),
+    }),
+});

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

@@ -0,0 +1,11 @@
+/**
+ * True at desktop (Tailwind `lg:` and up): at least 1024px wide and not a
+ * touch screen held upright. Everything else renders the single-pane mobile
+ * layout — phones, narrow tablets, and a large tablet in portrait, which is
+ * 1024px wide but has no room for the three-pane desktop grid (#682).
+ *
+ * The CSS-gated mobile chrome (ComposeFab) uses `lg:hidden`, and the
+ * `lg` variant is redefined in `@remit/ui`'s token sheet with the same
+ * condition — change `DESKTOP_MEDIA_QUERY` and both move together.
+ */
+export declare const useIsDesktop: () => boolean;

package/dist/src/hooks/useMediaQuery.js

@@ -0,0 +1,12 @@
+import { DESKTOP_MEDIA_QUERY, useMatchMedia } from "@remit/ui";
+/**
+ * True at desktop (Tailwind `lg:` and up): at least 1024px wide and not a
+ * touch screen held upright. Everything else renders the single-pane mobile
+ * layout — phones, narrow tablets, and a large tablet in portrait, which is
+ * 1024px wide but has no room for the three-pane desktop grid (#682).
+ *
+ * The CSS-gated mobile chrome (ComposeFab) uses `lg:hidden`, and the
+ * `lg` variant is redefined in `@remit/ui`'s token sheet with the same
+ * condition — change `DESKTOP_MEDIA_QUERY` and both move together.
+ */
+export const useIsDesktop = () => useMatchMedia(DESKTOP_MEDIA_QUERY);