@remit/web-client 0.0.325 → 0.0.326

package/dist/src/hooks/useArchiveMailbox.js

@@ -0,0 +1,120 @@
+import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+/**
+ * RFC 032 exclusive-folder-appointment (#976): every "which mailbox plays
+ * role X" question resolves from the account's `folderAppointments` map, not
+ * from independently re-detecting SPECIAL-USE flags or hardcoded name lists.
+ * The map is server-resolved (persisted user choice, or a proposal for
+ * anything unfilled), so a single shared lookup replaces what used to be four
+ * near-identical flag-then-name detectors.
+ */
+const useFolderRoleMailbox = (accountId, role) => {
+    const { data: config, isLoading } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+        enabled: !!accountId,
+    });
+    const mailboxId = useMemo(() => {
+        if (!accountId)
+            return undefined;
+        const account = config?.accounts.find((a) => a.accountId === accountId);
+        return account?.folderAppointments.find((fa) => fa.role === role)
+            ?.mailboxId;
+    }, [config, accountId, role]);
+    return { mailboxId, isLoading };
+};
+/**
+ * Returns the account's appointed Archive mailbox id. `undefined` while
+ * loading or when no folder is appointed to (or proposed for) the role.
+ */
+export const useArchiveMailbox = (accountId) => {
+    const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Archive");
+    return { archiveMailboxId: mailboxId, isLoading };
+};
+/**
+ * Returns the account's appointed Drafts mailbox id. Used by the mailbox
+ * route to decide whether to render the segmented Drafts view (Remit drafts +
+ * IMAP Drafts) in place of the flat message list (issue #505).
+ */
+export const useDraftsMailbox = (accountId) => {
+    const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Drafts");
+    return { draftsMailboxId: mailboxId, isLoading };
+};
+/**
+ * Returns the account's Inbox mailbox id — the destination for "Not spam"
+ * (issue #594), which moves a message out of Junk back to the inbox.
+ */
+export const useInboxMailbox = (accountId) => {
+    const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Inbox");
+    return { inboxMailboxId: mailboxId, isLoading };
+};
+/**
+ * Returns the account's appointed Junk/Spam mailbox id, used by the triage
+ * `!` (mark junk) key (#429). The message-flags API has no `$Junk` keyword
+ * field, so "mark junk" is realized as a move to the Junk mailbox.
+ */
+export const useJunkMailbox = (accountId) => {
+    const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Junk");
+    return { junkMailboxId: mailboxId, isLoading };
+};
+/**
+ * Returns the account's appointed Trash mailbox id, which is how the mailbox
+ * pane tells it is looking at Trash and may offer to empty it (#847).
+ */
+export const useTrashMailbox = (accountId) => {
+    const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Trash");
+    return { trashMailboxId: mailboxId, isLoading };
+};
+/**
+ * Each account's appointed Trash mailbox, keyed by account. The delete
+ * confirmation needs it to tell a move-to-Trash apart from a delete inside
+ * Trash, which is an unrecoverable expunge and has to be asked as one (#845),
+ * and apart from an account that appoints no Trash at all, where the server
+ * refuses the delete outright (#846).
+ *
+ * A map rather than a set of ids, because the brief and Flagged answer for
+ * selections that span accounts (#855): "is this row in Trash" is a question
+ * about the row's own account, and "does any Trash exist" has to be answerable
+ * as "no" rather than as silence.
+ *
+ * `hasAppointments` is data presence, never `!isLoading`. React Query v5
+ * computes `isLoading` as `isPending && isFetching`, so an offline query is
+ * paused and reports neither loading nor error while `data` is still
+ * undefined — which read as "no Trash anywhere", and promised a reversible
+ * move over an expunge that would replay on reconnect.
+ */
+export const useTrashByAccount = () => {
+    const { data: config, isError } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+    });
+    const trashByAccount = useMemo(() => {
+        const byAccount = new Map();
+        for (const account of config?.accounts ?? []) {
+            const trash = account.folderAppointments.find((appointment) => appointment.role === "Trash");
+            byAccount.set(account.accountId, {
+                mailboxId: trash?.mailboxId,
+                source: trash?.source ?? "None",
+                staleFolderPath: trash?.staleAppointmentPath,
+            });
+        }
+        return byAccount;
+    }, [config]);
+    return { trashByAccount, hasAppointments: config !== undefined, isError };
+};
+/**
+ * Returns an account's full role→mailbox appointment map, for callers that
+ * need more than one role at once (e.g. the Move-to picker excluding both
+ * Drafts and Sent, and ordering system folders by role). Empty while loading
+ * or when `accountId` is undefined.
+ */
+export const useFolderAppointments = (accountId) => {
+    const { data: config } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+        enabled: !!accountId,
+    });
+    return useMemo(() => config?.accounts.find((a) => a.accountId === accountId)
+        ?.folderAppointments ?? [], [config, accountId]);
+};

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

@@ -0,0 +1,56 @@
+import type { RemitImapAutoMovedInfo, RemitImapMessageSpamReport } from "@remit/api-http-client/types.gen.ts";
+interface UseAutoMovedBadgeOptions {
+    accountId: string | undefined;
+    messageId: string;
+    threadId: string;
+    /** The message's current mailbox — the row/card it's rendered in. */
+    mailboxId: string;
+    autoMoved: RemitImapAutoMovedInfo | undefined;
+    /**
+     * Present when the user reported this message as spam and the report has
+     * not been undone (issue #648). Takes precedence over `autoMoved`: a
+     * report can be a no-op move (the provider's own filter already placed the
+     * message in Junk), so it carries its own badge independent of the
+     * message's current folder, unlike a classifier/filter move.
+     */
+    spamReport: RemitImapMessageSpamReport | undefined;
+}
+export interface AutoMovedBadgeState {
+    /** Whether the move is still in effect and the badge should render. */
+    show: boolean;
+    label: string;
+    /** Present only when the undo target mailbox resolved. */
+    onUndo?: () => void;
+    isUndoing: boolean;
+    /**
+     * Settings › Filters link, present only for a standing-filter move — undo
+     * returns the message but never disables the filter, so the badge points to
+     * where the filter can be managed.
+     */
+    filtersHref?: string;
+}
+/**
+ * Composes the account's mailboxes with the message's `autoMoved` and
+ * `spamReport` projections into everything the `AutoMovedBadge` kit component
+ * needs: the derived "still in effect" gate, the plain-language label, and a
+ * one-click undo.
+ *
+ * Three provenances are handled, `spamReport` taking priority when present:
+ * - A spam report (issue #648) undoes via `POST /messages/not-spam`, which
+ *   resolves its own restore target server-side — the client never needs an
+ *   Inbox/Junk lookup for it, and the badge shows regardless of the message's
+ *   current folder (a report can be a no-op move).
+ * - A classifier move resolves its Inbox/Junk role mailboxes and undoes via a
+ *   plain move back to the source role.
+ * - A standing-filter move names an arbitrary source folder, whose display
+ *   name is resolved from the account's mailbox list, and carries a
+ *   Settings › Filters link so the filter that keeps moving mail is one tap
+ *   away — undo does not disable it.
+ *
+ * `show` re-derives on every render from `mailboxId` (or from `spamReport`'s
+ * presence) — no local dismissed flag. Once the undo mutation settles, its
+ * query invalidation refetches the thread row with its updated state, and the
+ * badge naturally stops showing (doc/rules/data-flow.md).
+ */
+export declare const useAutoMovedBadge: ({ accountId, messageId, threadId, mailboxId, autoMoved, spamReport, }: UseAutoMovedBadgeOptions) => AutoMovedBadgeState;
+export {};

package/dist/src/hooks/useAutoMovedBadge.js

@@ -0,0 +1,86 @@
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
+import { useQuery } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { autoMovedLabel, isAutoMoveInEffect, resolveUndoTargetMailboxId, spamReportLabel, } from "../lib/auto-moved";
+import { useInboxMailbox, useJunkMailbox } from "./useArchiveMailbox";
+import { useMoveMessages } from "./useMoveMessages";
+import { useReportSpam } from "./useReportSpam";
+/**
+ * Composes the account's mailboxes with the message's `autoMoved` and
+ * `spamReport` projections into everything the `AutoMovedBadge` kit component
+ * needs: the derived "still in effect" gate, the plain-language label, and a
+ * one-click undo.
+ *
+ * Three provenances are handled, `spamReport` taking priority when present:
+ * - A spam report (issue #648) undoes via `POST /messages/not-spam`, which
+ *   resolves its own restore target server-side — the client never needs an
+ *   Inbox/Junk lookup for it, and the badge shows regardless of the message's
+ *   current folder (a report can be a no-op move).
+ * - A classifier move resolves its Inbox/Junk role mailboxes and undoes via a
+ *   plain move back to the source role.
+ * - A standing-filter move names an arbitrary source folder, whose display
+ *   name is resolved from the account's mailbox list, and carries a
+ *   Settings › Filters link so the filter that keeps moving mail is one tap
+ *   away — undo does not disable it.
+ *
+ * `show` re-derives on every render from `mailboxId` (or from `spamReport`'s
+ * presence) — no local dismissed flag. Once the undo mutation settles, its
+ * query invalidation refetches the thread row with its updated state, and the
+ * badge naturally stops showing (doc/rules/data-flow.md).
+ */
+export const useAutoMovedBadge = ({ accountId, messageId, threadId, mailboxId, autoMoved, spamReport, }) => {
+    const { inboxMailboxId } = useInboxMailbox(accountId);
+    const { junkMailboxId } = useJunkMailbox(accountId);
+    const { moveMessages, isPending: isMoveUndoing } = useMoveMessages({
+        mailboxId,
+        threadId,
+        accountId,
+    });
+    const { notSpam, isRestoring: isSpamUndoing } = useReportSpam({
+        mailboxId,
+        threadId,
+        accountId,
+    });
+    const { data: mailboxes } = useQuery({
+        ...mailboxOperationsListMailboxesOptions({
+            path: { accountId: accountId ?? "" },
+        }),
+        staleTime: Infinity,
+        enabled: !!accountId && autoMoved?.fromMailboxId !== undefined,
+    });
+    const roleMailboxes = { inboxMailboxId, junkMailboxId };
+    const undoTargetMailboxId = resolveUndoTargetMailboxId(autoMoved, roleMailboxes);
+    const handleUndoMove = useCallback(() => {
+        if (!undoTargetMailboxId)
+            return;
+        moveMessages([messageId], undoTargetMailboxId);
+    }, [moveMessages, messageId, undoTargetMailboxId]);
+    const handleUndoReport = useCallback(() => {
+        notSpam([messageId]);
+    }, [notSpam, messageId]);
+    if (spamReport) {
+        return {
+            show: true,
+            label: spamReportLabel,
+            onUndo: handleUndoReport,
+            isUndoing: isSpamUndoing,
+        };
+    }
+    const show = isAutoMoveInEffect(autoMoved, mailboxId, roleMailboxes);
+    if (!show || !autoMoved) {
+        return { show: false, label: "", isUndoing: false };
+    }
+    const sourceFolderName = autoMoved.fromMailboxId
+        ? mailboxes?.items
+            .filter((mailbox) => mailbox.mailboxId === autoMoved.fromMailboxId)
+            .map((mailbox) => mailboxLeafName(mailbox))[0]
+        : undefined;
+    return {
+        show: true,
+        label: autoMovedLabel(autoMoved, sourceFolderName),
+        onUndo: undoTargetMailboxId ? handleUndoMove : undefined,
+        isUndoing: isMoveUndoing,
+        ...(autoMoved.filterId ? { filtersHref: "/settings/filters" } : {}),
+    };
+};

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

@@ -0,0 +1,70 @@
+import type { RemitImapMessageCategory, RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import type { ResultCount } from "@remit/ui";
+import type { BriefSectionParams } from "../lib/brief-criteria";
+/** The criteria every section request carries, its own category aside. */
+export interface BriefSectionsCriteria extends BriefSectionParams {
+    /**
+     * Committed free text, matched against subject, From and the body preview
+     * across folders.
+     */
+    query?: string;
+}
+export interface BriefSectionRows {
+    category: RemitImapMessageCategory;
+    rows: RemitImapThreadMessageResponse[];
+    total: ResultCount;
+    /** The request came back full, so the category holds more than these rows. */
+    atCap: boolean;
+    /** Nothing has arrived for this section yet. */
+    loading: boolean;
+    /** This section's own request failed; the others are unaffected. */
+    failed: boolean;
+    /** Ask this one section again. */
+    retry: () => void;
+}
+export interface UseBriefSectionsOptions {
+    /** The categories the brief is showing, in display order. */
+    categories: readonly RemitImapMessageCategory[];
+    criteria: BriefSectionsCriteria;
+    /** Rows per section. */
+    limit: number;
+    /**
+     * Whether the request saw every criterion on screen. False, no count is asked
+     * for and every section reports no number — see `briefCountsMatchRows`.
+     */
+    counted: boolean;
+}
+export interface UseBriefSections {
+    sections: BriefSectionRows[];
+    /** Nothing has arrived for any section — the brief has nothing to render. */
+    isLoading: boolean;
+    /** Every section failed. One failing section is the section's own state. */
+    isError: boolean;
+    refetch: () => void;
+}
+export declare function useBriefSections({ categories, criteria, limit, counted, }: UseBriefSectionsOptions): UseBriefSections;
+/** What a searched brief holds before the reader is told to narrow it. */
+export interface BriefSearchCriteria extends BriefSectionsCriteria {
+    /** A category the chips or a `category:` term narrowed the search to. */
+    category?: RemitImapMessageCategory[];
+}
+export interface UseBriefSearchRows {
+    /** Every match the request returned, in the order the server returned them. */
+    rows: RemitImapThreadMessageResponse[];
+    isLoading: boolean;
+    isError: boolean;
+    refetch: () => void;
+}
+/**
+ * The brief under a search: one request, one list — sender matches first, then
+ * mentions, each newest first.
+ *
+ * Not seven category queries stitched back together. A match's category must not
+ * lift it above a newer match, and section headers between the rows would do
+ * exactly that — an old newsletter above a mail that arrived this morning. The
+ * server orders the whole match set; the client renders it in that order (#312).
+ *
+ * Search mode also widens the scope past INBOX to every non-muted folder of every
+ * account, so this is the only request that reaches Archive, Sent and Spam.
+ */
+export declare function useBriefSearchRows(criteria: BriefSearchCriteria, limit: number, enabled: boolean): UseBriefSearchRows;

package/dist/src/hooks/useBriefSections.js

@@ -0,0 +1,210 @@
+/**
+ * The daily brief's rows: one `listAllThreads` request per section it shows,
+ * scoped to that section's category, plus one count of the whole category.
+ *
+ * The brief used to be a single non-paginated page of the newest 50 unified
+ * rows, and every section was "the Marketing rows among those 50" presented as
+ * Marketing. On a mailbox whose Marketing mail is all older than that window the
+ * section rendered empty above a header reading zero (#312). A category-scoped
+ * request answers over the whole scope, so a section holds that category's
+ * newest mail however far down the unified order it sits.
+ *
+ * The brief does not paginate as a whole; it paginates by section. Each section
+ * takes its newest {@link SECTION_ROW_CAP} rows and states its real size, and
+ * the way to the rest is the brief's own filtered list for that category — no
+ * cursor here, and no request that walks a mailbox.
+ *
+ * The counts are the second read. One per displayed section, keyed on the
+ * criteria alone so no page, cursor or expansion can trigger another, and held
+ * for a minute. The criteria are the caller's committed state — the query as it
+ * was submitted, and the chips as that query and the panel leave them — so
+ * nothing here is on a keystroke path.
+ *
+ * Each section loads and fails on its own. Seven requests are seven answers, and
+ * one category's failed request is not a reason to blank the six that came back:
+ * a section carries its own pending and error state, and the brief renders what
+ * it has. What reaches that state is a transport failure — a request that never
+ * got an answer. A 5xx is the API breaking rather than this section failing, and
+ * escalates globally on the fail-fast contract (`shouldEscalate`, #1059); there
+ * is no `meta` opt-out here and there must not be one.
+ *
+ * A refetch under the same predicate keeps the rows already on screen. Under a
+ * different one it does not — the previous chip's mail under the new chip is the
+ * defect `sameInboxFilter` exists to stop — so only a change of free text holds
+ * the previous answer while the next one is in flight.
+ *
+ * Sections are the unsearched brief only. Under a query the brief is one list in
+ * one order — see `useBriefSearchRows`.
+ */
+import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { unifiedThreadOperationsListAllThreads } from "@remit/api-http-client/sdk.gen.ts";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { sameInboxFilter } from "../lib/inbox-filters";
+import { toResultCount } from "../lib/result-count";
+/** A minute: a brief reopened straight away costs nothing. */
+const BRIEF_STALE_TIME_MS = 60_000;
+/** Half a minute: a query being refined re-asks sooner than the brief does. */
+const SEARCH_STALE_TIME_MS = 30_000;
+/** No number at all, which is what a section shows when nobody counted it. */
+const UNCOUNTED = { kind: "unknown" };
+/**
+ * Hold the previous answer while the next one is in flight, but only where the
+ * predicate is unchanged. A chip that changes what is being asked for takes its
+ * rows with it: the previous chip's mail under the new chip, for one round trip,
+ * is what `sameInboxFilter` was written to stop (design D18).
+ */
+const keepUnderSameFilter = (filter) => (previous, previousQuery) => sameInboxFilter(previousQuery?.queryKey, filter) ? previous : undefined;
+const sectionRowsQuery = (criteria, category, limit) => ({
+    ...criteria,
+    category: [category],
+    limit,
+    order: "desc",
+});
+// No `limit` and no cursor: the count is a property of the criteria, so growing
+// the page cannot change it and cannot ask for it again.
+const sectionCountQuery = (criteria, category) => ({
+    ...criteria,
+    category: [category],
+    order: "desc",
+    count: true,
+    results: false,
+});
+/**
+ * What a request under these criteria asks for, as `sameInboxFilter` reads it.
+ * Free text is deliberately not part of it: a query being refined is the one
+ * change that may keep the previous answer on screen.
+ */
+const sectionFilter = (criteria, category) => ({
+    category: [category],
+    ...(criteria.unread !== undefined ? { unread: criteria.unread } : {}),
+    ...(criteria.starred !== undefined ? { starred: criteria.starred } : {}),
+    ...(criteria.attachments !== undefined
+        ? { attachments: criteria.attachments }
+        : {}),
+    // The account pill is a scope, not text: switching it must take the previous
+    // account's rows off screen rather than render them for one round trip.
+    ...(criteria.accountId !== undefined
+        ? { accountId: criteria.accountId }
+        : {}),
+    ...(criteria.muted !== undefined ? { muted: criteria.muted } : {}),
+});
+export function useBriefSections({ categories, criteria, limit, counted, }) {
+    const rowQueries = useQueries({
+        queries: categories.map((category) => {
+            const query = sectionRowsQuery(criteria, category, limit);
+            const filter = sectionFilter(criteria, category);
+            return {
+                queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+                queryFn: async () => {
+                    const { data } = await unifiedThreadOperationsListAllThreads({
+                        query,
+                        throwOnError: true,
+                    });
+                    return data;
+                },
+                placeholderData: keepUnderSameFilter(filter),
+                staleTime: BRIEF_STALE_TIME_MS,
+            };
+        }),
+    });
+    const countQueries = useQueries({
+        queries: categories.map((category) => {
+            const query = sectionCountQuery(criteria, category);
+            const filter = sectionFilter(criteria, category);
+            return {
+                queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+                queryFn: async () => {
+                    const { data } = await unifiedThreadOperationsListAllThreads({
+                        query,
+                        throwOnError: true,
+                    });
+                    return data;
+                },
+                enabled: counted,
+                placeholderData: keepUnderSameFilter(filter),
+                staleTime: BRIEF_STALE_TIME_MS,
+            };
+        }),
+    });
+    const sections = useMemo(() => categories.map((category, index) => {
+        const rows = rowQueries[index];
+        const count = countQueries[index];
+        const items = rows?.data?.items ?? [];
+        return {
+            category,
+            rows: items,
+            // Read off the page rather than the rendered rows: muting and the
+            // thread collapse both shrink what is rendered, and neither means the
+            // category holds no more.
+            atCap: items.length >= limit,
+            // `enabled` gates the request, not the cache: a brief that asks for
+            // no count must not render the one an earlier, narrower brief left
+            // behind.
+            total: counted ? toResultCount(count?.data?.count) : UNCOUNTED,
+            // Pending, not fetching: a section holding the previous query's rows
+            // has something to render, and replacing it with a skeleton takes the
+            // brief off screen every time the search field is cleared.
+            loading: rows?.isPending ?? true,
+            failed: rows?.isError ?? false,
+            retry: () => {
+                rows?.refetch();
+                // `refetch` ignores `enabled`, so an uncounted brief would fetch a
+                // count it has already decided not to render.
+                if (counted)
+                    count?.refetch();
+            },
+        };
+    }), [categories, rowQueries, countQueries, counted, limit]);
+    const refetch = useCallback(() => {
+        for (const query of rowQueries)
+            query.refetch();
+        for (const query of countQueries)
+            query.refetch();
+    }, [rowQueries, countQueries]);
+    return {
+        sections,
+        // The whole-body states are the ones where there is genuinely nothing to
+        // show. A section that is still loading, or that failed on its own, says so
+        // in its own place while the rest of the brief stands.
+        isLoading: rowQueries.length > 0 && rowQueries.every((query) => query.isPending),
+        isError: rowQueries.length > 0 && rowQueries.every((query) => query.isError),
+        refetch,
+    };
+}
+/**
+ * The brief under a search: one request, one list — sender matches first, then
+ * mentions, each newest first.
+ *
+ * Not seven category queries stitched back together. A match's category must not
+ * lift it above a newer match, and section headers between the rows would do
+ * exactly that — an old newsletter above a mail that arrived this morning. The
+ * server orders the whole match set; the client renders it in that order (#312).
+ *
+ * Search mode also widens the scope past INBOX to every non-muted folder of every
+ * account, so this is the only request that reaches Archive, Sent and Spam.
+ */
+export function useBriefSearchRows(criteria, limit, enabled) {
+    const query = { ...criteria, limit, order: "desc" };
+    const { data, isLoading, isError, refetch } = useQuery({
+        queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+        queryFn: async () => {
+            const { data: page } = await unifiedThreadOperationsListAllThreads({
+                query,
+                throwOnError: true,
+            });
+            return page;
+        },
+        enabled,
+        staleTime: SEARCH_STALE_TIME_MS,
+    });
+    const rows = useMemo(() => (enabled ? (data?.items ?? []) : []), [data, enabled]);
+    return {
+        rows,
+        isLoading: enabled && isLoading,
+        isError: enabled && isError,
+        refetch: useCallback(() => {
+            refetch();
+        }, [refetch]),
+    };
+}

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

@@ -0,0 +1,37 @@
+/**
+ * What the calendar surfaces read, and the only place they read it from.
+ *
+ * The seam is here, and not inside the grid, because the grid is presentational
+ * and expands no recurrence of its own — the server returns instances and this
+ * turns them into what the kit draws. Every caller keeps the call it makes.
+ */
+import type { CalendarColorId, CalendarDescriptor, CalendarEventData, CalendarViewId } from "@remit/ui";
+import { type CalendarInstanceRef } from "./calendar";
+export interface CalendarDataRequest {
+    view: CalendarViewId;
+    /** The day the view is centred on, `YYYY-MM-DD`. */
+    date: string;
+    /** The calendars the address has ticked; empty means every one of them. */
+    calendarIds: readonly string[];
+    /**
+     * False where the zoom on screen draws nothing from this window. The agenda
+     * rolls its own range a week at a time, so asking for this view's week as
+     * well would fetch a window nothing renders — and the address rewriting on
+     * every scroll would ask again, with its neighbours, all the way down.
+     */
+    enabled?: boolean;
+}
+export interface CalendarData {
+    calendars: CalendarDescriptor[];
+    events: CalendarEventData[];
+    colorByCalendarId: Record<string, CalendarColorId>;
+    /** The zone each collection's times are read on — never the device's. */
+    timeZoneByCalendarId: Record<string, string>;
+    isLoading: boolean;
+    /** A refusal the calendar renders itself. Null when the read succeeded. */
+    error: unknown;
+    retry: () => void;
+    /** The resource and occurrence behind an event the grid selected. */
+    instanceOf: (eventId: string) => CalendarInstanceRef;
+}
+export declare function useCalendarData({ view, date, calendarIds, enabled, }: CalendarDataRequest): CalendarData;

package/dist/src/hooks/useCalendarData.js

@@ -0,0 +1,23 @@
+import { calendarWindow, readCalendarInstanceId, useCalendarEventWindow, useCalendarSelection, useDrawnEvents, usePrefetchAdjacentWindows, } from "./calendar";
+export function useCalendarData({ view, date, calendarIds, enabled = true, }) {
+    const { calendars, colorByCalendarId, timeZoneByCalendarId, shown, narrowed, resolved, isLoading, } = useCalendarSelection(calendarIds);
+    const window = calendarWindow(view, date);
+    const active = enabled && resolved;
+    const events = useCalendarEventWindow({
+        ...window,
+        calendarIds: narrowed,
+        enabled: active,
+    });
+    usePrefetchAdjacentWindows(view, date, narrowed, active);
+    const eventData = useDrawnEvents(events.instances, timeZoneByCalendarId, shown);
+    return {
+        calendars,
+        events: eventData,
+        colorByCalendarId,
+        timeZoneByCalendarId,
+        isLoading: isLoading || events.isLoading,
+        error: events.error,
+        retry: events.refetch,
+        instanceOf: readCalendarInstanceId,
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { ClauseField, Suggestion } from "@remit/ui";
+/** How long typing settles before the address lookup fires. */
+export declare const CLAUSE_SUGGESTION_DEBOUNCE_MS = 250;
+/**
+ * Values to offer for the clause being edited: the senders of the messages the
+ * user selected first — already in hand, and the likeliest answer — then the
+ * known addresses a lookup turns up for what has been typed.
+ *
+ * The lookup is the address search the compose recipient field already uses, on
+ * a debounce so a request does not fire per keystroke. The list narrows against
+ * the live value while a request is still out, so it never lags what is on
+ * screen; nothing it returns can change what the user typed.
+ */
+export declare const useClauseSuggestions: (field: ClauseField | undefined, value: string, selectionSenders: readonly string[]) => Suggestion[];

package/dist/src/hooks/useClauseSuggestions.js

@@ -0,0 +1,39 @@
+import { addressOperationsSearchAddressesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { buildClauseSuggestions, CLAUSE_SUGGESTION_LIMIT, fieldTakesAddressSuggestions, } from "../lib/organize/clause-suggestions";
+import { useDebouncedValue } from "./useDebouncedValue";
+/** How long typing settles before the address lookup fires. */
+export const CLAUSE_SUGGESTION_DEBOUNCE_MS = 250;
+/** The shortest query worth a round-trip. */
+const MIN_QUERY_LENGTH = 2;
+/**
+ * Values to offer for the clause being edited: the senders of the messages the
+ * user selected first — already in hand, and the likeliest answer — then the
+ * known addresses a lookup turns up for what has been typed.
+ *
+ * The lookup is the address search the compose recipient field already uses, on
+ * a debounce so a request does not fire per keystroke. The list narrows against
+ * the live value while a request is still out, so it never lags what is on
+ * screen; nothing it returns can change what the user typed.
+ */
+export const useClauseSuggestions = (field, value, selectionSenders) => {
+    const query = value.trim();
+    const debouncedQuery = useDebouncedValue(query, CLAUSE_SUGGESTION_DEBOUNCE_MS);
+    const offersAddresses = field !== undefined && fieldTakesAddressSuggestions(field);
+    const { data } = useQuery({
+        ...addressOperationsSearchAddressesOptions({
+            query: { q: debouncedQuery, limit: CLAUSE_SUGGESTION_LIMIT },
+        }),
+        enabled: offersAddresses && debouncedQuery.length >= MIN_QUERY_LENGTH,
+    });
+    if (!offersAddresses || field === undefined)
+        return [];
+    const addresses = [
+        ...selectionSenders.map((email) => ({ email, fromSelection: true })),
+        ...(data?.items ?? []).map((address) => ({
+            email: address.normalizedEmail,
+            ...(address.displayName ? { displayName: address.displayName } : {}),
+        })),
+    ];
+    return buildClauseSuggestions(field, query, addresses);
+};