@remit/web-client 0.0.325 → 0.0.327

package/dist/src/lib/search-tokens.js

@@ -0,0 +1,206 @@
+/**
+ * Filter-token parser for the mail search field (#428). Recognizes a fixed set
+ * of `word:value` tokens typed inline with the free-text query and turns them
+ * into removable chips. Only tokens the search APIs can actually honor are
+ * recognized — everything else is left untouched as ordinary free-text words.
+ *
+ * The vocabulary is the search parameters `threadOperationsSearchThreads`
+ * takes, said in words:
+ *
+ * | token                  | thread search      |
+ * | ---------------------- | ------------------ |
+ * | `from:`                | `from`             |
+ * | `subject:`             | `subject`          |
+ * | `category:`            | `category[]`       |
+ * | `is:unread` / `is:read`| `unread`           |
+ * | `is:starred`           | `starred`          |
+ * | `has:attachment`       | `attachments`      |
+ * | `before:` / `after:`   | —                  |
+ * | `in:`                  | route scope        |
+ * | `account:`             | —                  |
+ *
+ * A token an engine has no parameter for is applied client-side over the rows
+ * that engine returned (`matchesSearchTokens` in `lib/brief.ts`), never dropped.
+ *
+ * `in:<mailbox>` and `account:<name>` resolve against a name index the caller
+ * supplies via `SearchTokenContext` (built from the loaded mailboxes/accounts —
+ * see `lib/search-token-index.ts`). An unresolvable name (no index, or no
+ * match in it) is left as free text rather than becoming a chip for a filter
+ * that can't actually apply. `category:` resolves the same way against a fixed
+ * vocabulary, so `category:nonsense` stays free text too.
+ *
+ * Token names are case-insensitive. Terms are cut from the query by
+ * `search-query-words.ts` in the kit, which the brief's chips also write and
+ * remove terms with, so a quoted value is one term to both.
+ *
+ * Pure functions only: no React, no fetch — the name index is injected, not
+ * fetched here. `MailListHeader` renders the chips and the callers that issue
+ * search requests (`MailboxPane`, `DailyBrief`, `FlaggedList`) apply the
+ * parsed tokens to the params each engine's API actually supports.
+ */
+import { MessageCategory } from "@remit/domain-enums";
+import { categoryLabels, quoteSearchTokenValue, searchTokenTerm, splitSearchTerm, splitSearchWords, } from "@remit/ui";
+export { quoteSearchTokenValue, searchTokenTerm, splitSearchTerm, splitSearchWords, };
+const CATEGORY_OPTIONS = Object.values(MessageCategory).map((value) => ({ value, label: categoryLabels[value] }));
+/**
+ * Spellings that resolve to a category beyond the enum values themselves — the
+ * label the chips show, so what the user reads is also what the user can type.
+ */
+const CATEGORY_ALIASES = {
+    unclassified: "uncategorized",
+};
+/** The whole vocabulary, in the order a suggestion list offers it. */
+export const SEARCH_TOKEN_SPECS = [
+    { name: "from", label: "Sender", values: "contact" },
+    { name: "subject", label: "Subject", values: "text" },
+    {
+        name: "category",
+        label: "Category",
+        values: "fixed",
+        options: CATEGORY_OPTIONS,
+    },
+    {
+        name: "is",
+        label: "State",
+        values: "fixed",
+        options: [
+            { value: "unread", label: "Unread" },
+            { value: "read", label: "Read" },
+            { value: "starred", label: "Starred" },
+        ],
+    },
+    {
+        name: "has",
+        label: "Contents",
+        values: "fixed",
+        options: [{ value: "attachment", label: "Has attachment" }],
+    },
+    { name: "in", label: "Folder", values: "mailbox" },
+    { name: "account", label: "Account", values: "account" },
+    { name: "after", label: "Sent on or after", values: "date" },
+    { name: "before", label: "Sent before", values: "date" },
+];
+const SPECS_BY_NAME = new Map(SEARCH_TOKEN_SPECS.map((spec) => [spec.name, spec]));
+/** The spec for a token name, or `undefined` when the name is not one of ours. */
+export const searchTokenSpec = (name) => SPECS_BY_NAME.get(name.toLowerCase());
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+function parseDateToken(type, raw, value) {
+    if (!DATE_PATTERN.test(value))
+        return undefined;
+    const epochMs = Date.parse(`${value}T00:00:00Z`);
+    if (Number.isNaN(epochMs))
+        return undefined;
+    return { type, raw, value, epochSeconds: Math.floor(epochMs / 1000) };
+}
+/** The category a `category:` value names, by enum value or by chip label. */
+export function resolveCategory(value) {
+    const lower = value.toLowerCase();
+    const alias = CATEGORY_ALIASES[lower];
+    if (alias)
+        return alias;
+    const known = Object.values(MessageCategory).find((c) => c === lower);
+    return known;
+}
+function parseStateToken(raw, value) {
+    switch (value.toLowerCase()) {
+        case "unread":
+            return { type: "isUnread", raw };
+        case "read":
+            return { type: "isRead", raw };
+        // `flagged` is the wire name for IMAP \Flagged; "starred" is the word the
+        // chips use. Both are typed, so both parse.
+        case "starred":
+        case "flagged":
+            return { type: "isStarred", raw };
+        default:
+            return undefined;
+    }
+}
+function parseWord(word, context) {
+    const parts = splitSearchTerm(word);
+    if (!parts || parts.value.length === 0)
+        return undefined;
+    const { name, value } = parts;
+    switch (name) {
+        case "from":
+            return { type: "from", raw: word, value };
+        case "subject":
+            return { type: "subject", raw: word, value };
+        case "category": {
+            const category = resolveCategory(value);
+            if (!category)
+                return undefined;
+            return { type: "category", raw: word, value, category };
+        }
+        case "is":
+            return parseStateToken(word, value);
+        case "has":
+            return value.toLowerCase() === "attachment"
+                ? { type: "hasAttachment", raw: word }
+                : undefined;
+        case "before":
+        case "after":
+            return parseDateToken(name, word, value);
+        case "in": {
+            const mailboxId = context.mailboxesByName?.get(value.toLowerCase());
+            if (!mailboxId)
+                return undefined;
+            return { type: "in", raw: word, value, mailboxId };
+        }
+        case "account": {
+            const accountId = context.accountsByName?.get(value.toLowerCase());
+            if (!accountId)
+                return undefined;
+            return { type: "account", raw: word, value, accountId };
+        }
+        default:
+            return undefined;
+    }
+}
+/** Split a query into recognized filter tokens and the remaining free text. */
+export function parseSearchTokens(query, context = {}) {
+    const tokens = [];
+    const freeWords = [];
+    for (const word of splitSearchWords(query)) {
+        const token = parseWord(word.raw, context);
+        if (token)
+            tokens.push(token);
+        else
+            freeWords.push(word.raw);
+    }
+    return { freeText: freeWords.join(" "), tokens };
+}
+/** Remove one parsed token's raw text from the original query string. */
+export function removeSearchToken(query, token) {
+    return splitSearchWords(query)
+        .filter((word) => word.raw !== token.raw)
+        .map((word) => word.raw)
+        .join(" ");
+}
+/** Human label for the removable chip. */
+export function searchTokenLabel(token) {
+    switch (token.type) {
+        case "from":
+            return `From: ${token.value}`;
+        case "subject":
+            return `Subject: ${token.value}`;
+        case "category":
+            return `Category: ${categoryLabels[token.category]}`;
+        case "hasAttachment":
+            return "Has attachment";
+        case "isUnread":
+            return "Unread";
+        case "isRead":
+            return "Read";
+        case "isStarred":
+            return "Starred";
+        case "before":
+            return `Before ${token.value}`;
+        case "after":
+            return `After ${token.value}`;
+        case "in":
+            return `In: ${token.value}`;
+        case "account":
+            return `Account: ${token.value}`;
+    }
+}

package/dist/src/lib/search-view.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The field text after a view transition, or `undefined` when nothing changes
+ * (same view — typing, opening a result, mirroring `q` back to the URL).
+ *
+ * `typedInView` is the view the text in the field was written in, not the view
+ * of the previous render. The two differ for exactly one render after the
+ * address moves, which is where a keystroke that followed the move lands
+ * (#808); calling it the previous render's view re-seeded that keystroke away.
+ */
+export declare function searchInputForView(typedInView: string, viewKey: string, urlQuery: string): string | undefined;
+/**
+ * The committed query the search APIs run. Typing debounces, but an empty field
+ * commits immediately — otherwise a view change fires one more request for the
+ * query the user just left behind.
+ */
+export declare function committedSearchQuery(searchInput: string, debouncedSearchInput: string): string;
+export interface MirrorDecision {
+    /** The live field text. */
+    searchInput: string;
+    /** The debounced query the search APIs are running. */
+    committedQuery: string;
+    /** What the URL currently says the query is. */
+    urlQuery: string;
+    /** Where the router says the reader is, which is where a write would land. */
+    pathname: string;
+    /** The path of the list asking. */
+    listPath: string;
+}
+/**
+ * Whether a list may write the committed query into the URL.
+ *
+ * Only a settled query may: mid-debounce the committed value is the *previous*
+ * query, and writing it would overwrite the URL that a deep link or a saved
+ * search just arrived with — stripping `q` for as long as the debounce lasts,
+ * and taking the search with it. The mirror waits for the field and the
+ * committed query to agree, then writes only if the URL says something else.
+ *
+ * And only the list the reader is actually on may: a list stays mounted, effects
+ * and all, until the list they navigated to is ready to paint, by which time the
+ * address is already the new one. A write from the outgoing list in that window
+ * navigates back to itself, superseding the load in flight and replacing the
+ * entry the reader just pushed — they click Inbox and land on the brief.
+ *
+ * The mirror asks this again whenever the address moves, not only when the
+ * field does (#808), so a settled query the URL has drifted away from is
+ * written again. That cannot loop: the answer is false the moment the URL says
+ * the committed query, which is what every write makes it say. Nor does it let
+ * the mirror fight a query arriving by URL — that arrives mid-debounce, where
+ * the first rule already refuses, and by the time the debounce settles the
+ * field has been re-seeded from the address it landed on
+ * (`routing/search-field.ts`).
+ */
+export declare function shouldMirrorQuery({ searchInput, committedQuery, urlQuery, pathname, listPath, }: MirrorDecision): boolean;

package/dist/src/lib/search-view.js

@@ -0,0 +1,71 @@
+/**
+ * Search is a view-level mode, not a persistent global filter (#47).
+ *
+ * The query belongs to the location it was typed in: the URL's `q` is what a
+ * view is searching for, and the nav links already drop `q` when they switch
+ * mailbox. The search field, however, is local state in the /mail shell — which
+ * outlives every child route — so it kept the old text and went on querying the
+ * new mailbox with it (the confusing Mac Mail behaviour). These rules make the
+ * URL win on every view change: the field re-seeds from the location it lands
+ * on, so switching mailbox clears a stale query while a deep link or a saved
+ * search that carries `q` still arrives with the query intact.
+ *
+ * "Every view change" is the move the reader made, not every render that
+ * notices one. Text typed once the address already names the destination was
+ * typed in the destination, so it is that view's query and survives
+ * (`routing/search-field.ts`).
+ */
+import { locationIsOnList } from "./mail-route";
+/**
+ * The field text after a view transition, or `undefined` when nothing changes
+ * (same view — typing, opening a result, mirroring `q` back to the URL).
+ *
+ * `typedInView` is the view the text in the field was written in, not the view
+ * of the previous render. The two differ for exactly one render after the
+ * address moves, which is where a keystroke that followed the move lands
+ * (#808); calling it the previous render's view re-seeded that keystroke away.
+ */
+export function searchInputForView(typedInView, viewKey, urlQuery) {
+    if (typedInView === viewKey)
+        return undefined;
+    return urlQuery;
+}
+/**
+ * The committed query the search APIs run. Typing debounces, but an empty field
+ * commits immediately — otherwise a view change fires one more request for the
+ * query the user just left behind.
+ */
+export function committedSearchQuery(searchInput, debouncedSearchInput) {
+    return searchInput === "" ? "" : debouncedSearchInput;
+}
+/**
+ * Whether a list may write the committed query into the URL.
+ *
+ * Only a settled query may: mid-debounce the committed value is the *previous*
+ * query, and writing it would overwrite the URL that a deep link or a saved
+ * search just arrived with — stripping `q` for as long as the debounce lasts,
+ * and taking the search with it. The mirror waits for the field and the
+ * committed query to agree, then writes only if the URL says something else.
+ *
+ * And only the list the reader is actually on may: a list stays mounted, effects
+ * and all, until the list they navigated to is ready to paint, by which time the
+ * address is already the new one. A write from the outgoing list in that window
+ * navigates back to itself, superseding the load in flight and replacing the
+ * entry the reader just pushed — they click Inbox and land on the brief.
+ *
+ * The mirror asks this again whenever the address moves, not only when the
+ * field does (#808), so a settled query the URL has drifted away from is
+ * written again. That cannot loop: the answer is false the moment the URL says
+ * the committed query, which is what every write makes it say. Nor does it let
+ * the mirror fight a query arriving by URL — that arrives mid-debounce, where
+ * the first rule already refuses, and by the time the debounce settles the
+ * field has been re-seeded from the address it landed on
+ * (`routing/search-field.ts`).
+ */
+export function shouldMirrorQuery({ searchInput, committedQuery, urlQuery, pathname, listPath, }) {
+    if (!locationIsOnList(pathname, listPath))
+        return false;
+    if (committedQuery !== searchInput)
+        return false;
+    return committedQuery !== urlQuery;
+}

package/dist/src/lib/selection-account-scope.d.ts

@@ -0,0 +1,18 @@
+import type { SelectionRestriction } from "@remit/ui";
+/** The account a selection resolves to, and what that costs it. */
+export interface SelectionAccountScope {
+    /** The one account holding every selected row, when there is one. */
+    accountId: string | undefined;
+    /** Which scope the selection spans more of than Move can take. */
+    restriction: SelectionRestriction | undefined;
+    /** Why Move is withheld, in the toolbar's own words. */
+    moveDisabledHint: string | undefined;
+}
+/**
+ * Move applies within one account, so every surface offering it over a
+ * selection asks the same question of the same fact — each row's own
+ * `accountId`, never `accountConfigId`, which every account of one user shares
+ * and so can never differ (#456). A row that carries no account of its own is
+ * the caller's to fill in from its list scope before it gets here.
+ */
+export declare const resolveSelectionAccountScope: (accountIds: Iterable<string | undefined>) => SelectionAccountScope;

package/dist/src/lib/selection-account-scope.js

@@ -0,0 +1,26 @@
+/**
+ * Move applies within one account, so every surface offering it over a
+ * selection asks the same question of the same fact — each row's own
+ * `accountId`, never `accountConfigId`, which every account of one user shares
+ * and so can never differ (#456). A row that carries no account of its own is
+ * the caller's to fill in from its list scope before it gets here.
+ */
+export const resolveSelectionAccountScope = (accountIds) => {
+    const distinct = new Set();
+    for (const accountId of accountIds) {
+        if (accountId)
+            distinct.add(accountId);
+    }
+    if (distinct.size > 1) {
+        return {
+            accountId: undefined,
+            restriction: "spansAccounts",
+            moveDisabledHint: "Move only works within one account — clear selection or pick messages from a single account",
+        };
+    }
+    return {
+        accountId: distinct.size === 1 ? [...distinct][0] : undefined,
+        restriction: undefined,
+        moveDisabledHint: undefined,
+    };
+};

package/dist/src/lib/selection-mode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Selection-mode rules for the message list (#115, refs #92 requirements 9
+ * and 10). Pure so "one source of truth, one exit" is testable without a DOM.
+ */
+import type { StepId } from "@remit/ui";
+/** The subset of `@tanstack/history`'s `HistoryAction` a blocker can see. */
+export type NavigationAction = "PUSH" | "REPLACE" | "FORWARD" | "BACK" | "GO";
+/**
+ * Whether a history navigation should exit selection mode instead of leaving
+ * the route. Only the back gesture is intercepted, so a navigation the app
+ * itself starts (opening a message, switching mailboxes) is never blocked.
+ *
+ * While the selection wizard is open its own steps own the back gesture, and
+ * the selection is what the wizard is acting on — swallowing back there would
+ * clear the selection out from under the flow instead of popping a step.
+ */
+export declare const shouldExitSelectionOnNavigate: (action: NavigationAction, hasSelection: boolean, wizardStep: StepId | undefined) => boolean;

package/dist/src/lib/selection-mode.js

@@ -0,0 +1,14 @@
+/**
+ * Selection-mode rules for the message list (#115, refs #92 requirements 9
+ * and 10). Pure so "one source of truth, one exit" is testable without a DOM.
+ */
+/**
+ * Whether a history navigation should exit selection mode instead of leaving
+ * the route. Only the back gesture is intercepted, so a navigation the app
+ * itself starts (opening a message, switching mailboxes) is never blocked.
+ *
+ * While the selection wizard is open its own steps own the back gesture, and
+ * the selection is what the wizard is acting on — swallowing back there would
+ * clear the selection out from under the flow instead of popping a step.
+ */
+export const shouldExitSelectionOnNavigate = (action, hasSelection, wizardStep) => action === "BACK" && hasSelection && wizardStep === undefined;

package/dist/src/lib/self-update-state.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The self-update state machine, isolated from React.
+ *
+ * `GET /system/update` returns three independent things: the running version,
+ * the outcome of the last manifest check, and the state of the current or last
+ * run. This module folds that response — plus the run this client started and
+ * holds in memory, plus the clock — into the single `SelfUpdateState` the
+ * `@remit/ui` components render, and into the full-window blocking overlay.
+ *
+ * The design constraints (RFC 037 Interface, issue #135) live here:
+ *  - The server decides whether an update is running and how far along it is.
+ *    Every phase shown is one the server reported for this run; an answer the
+ *    client is still waiting for renders no phase at all.
+ *  - A held run turns a failed request into `applying`, never `unreachable`.
+ *  - Once the apply budget plus a margin has passed with no answer — a failed
+ *    request, or a server answering without accounting for the run — that
+ *    silence becomes "the server never came back", a state that never claims
+ *    the rollback ran, because from a dead connection the client cannot know.
+ *  - The check block and the run block are independent: a check that cannot
+ *    reach the update source is a failed check, never a failed update.
+ */
+import type { RemitImapSystemUpdatePhase, RemitImapSystemUpdateResponse, RemitImapSystemUpdateRun } from "@remit/api-http-client/types.gen.ts";
+import type { ReleaseInfo, SelfUpdateState, UpdatePhase } from "@remit/ui";
+/**
+ * The longest an apply can plausibly take — pull, snapshot, stop, start, gate —
+ * before a silent server is treated as gone rather than still working. A five
+ * minute margin is added on top before the client gives up entirely.
+ */
+export declare const APPLY_BUDGET_SECONDS = 600;
+export declare const NEVER_CAME_BACK_MARGIN_SECONDS = 300;
+/** Shown on the dead-connection screens, where no server-authored command exists. */
+export declare const FALLBACK_LOGS_COMMAND = "remit logs";
+/**
+ * The run this client asked for, kept in memory for as long as the page that
+ * asked lives. Nothing is written to storage: a run lasts about a minute and
+ * only the server knows how it ends, so a page that was not there for the
+ * request starts from the server's answer instead of from a record of its own.
+ */
+export interface HeldRun {
+    runId: string;
+    attemptedVersion: string;
+    previousVersion: string;
+    /** The phase the server reported when it accepted the run. */
+    phase: UpdatePhase;
+    /** Epoch millis when the client began holding this run. */
+    startedAt: number;
+}
+/**
+ * The check this page asked for, held for as long as the page that asked lives.
+ * The server records the request and answers with the state it already had, so
+ * the wait is the client's to keep: `since` is `check.lastCheckedAt` as the
+ * server reported it at the moment of the press, and the answer has landed once
+ * the server reports a different one. Comparing against that stored value rather
+ * than against the press's own clock keeps the rule honest on a box whose clock
+ * differs from the browser's.
+ */
+export interface CheckPress {
+    /** Epoch millis when the control was pressed, for the bounded wait. */
+    pressedAt: number;
+    since: string | undefined;
+}
+/**
+ * When this tab first saw the run the server reported as going, by its own
+ * clock. A run's `startedAt` is written on the box, and a box whose clock is
+ * twenty minutes behind the browser's would put that start far enough in the
+ * past to spend the whole apply budget before the first failed request — the
+ * screen would open on "the server never came back". `CheckPress` keeps its wait
+ * the client's own for the same reason. The runId travels with it so a second
+ * run never inherits the first one's wait.
+ */
+export interface RunSighting {
+    runId: string;
+    /** Epoch millis, this tab's clock, of the first answer that reported it going. */
+    observedAt: number;
+}
+export declare function checkAnswered(press: CheckPress, data: RemitImapSystemUpdateResponse | undefined): boolean;
+/**
+ * Why the request the press fired never reached the seam. The status is named
+ * because a 500 here is a real fault on the box — the control volume unwritable
+ * is the one seen in the wild — and a press that quietly re-served the old
+ * verdict is exactly how #599 stayed invisible for an hour.
+ */
+export declare function checkRequestFailureReason(error: unknown): string;
+export type UpdateOverlay = {
+    kind: "none";
+} | {
+    kind: "applying";
+    target: string;
+    phase: UpdatePhase;
+    elapsedSeconds: number;
+} | {
+    kind: "neverCameBack";
+    attemptedVersion: string;
+    previousVersion: string;
+    elapsedSeconds: number;
+    logsCommand: string;
+};
+export type UpdateSurface = {
+    status: "absent";
+} | {
+    status: "loading";
+} | {
+    status: "ready";
+    section: SelfUpdateState;
+    overlay: UpdateOverlay;
+};
+export interface DeriveInput {
+    data: RemitImapSystemUpdateResponse | undefined;
+    isError: boolean;
+    error: unknown;
+    held: HeldRun | null;
+    dismissedRunId: string | null;
+    /** The check this page pressed for, or null when it is not waiting on one. */
+    checkPress: CheckPress | null;
+    /** Why the request that press fired failed, or null when it did not. */
+    checkFailure: string | null;
+    /** When this tab first saw the server's run going, for a wait it can trust. */
+    sighting: RunSighting | null;
+    now: number;
+}
+export interface DeriveResult {
+    surface: UpdateSurface;
+    /** The held run should be dropped — the server has accounted for it. */
+    releaseHeld: boolean;
+}
+export declare function mapUpdatePhase(phase: RemitImapSystemUpdatePhase): UpdatePhase;
+/**
+ * The surface has no entry point for this caller: `404` (no manifest URL
+ * configured) or `401` (not authenticated). Both render nothing and stop the
+ * poll. `403` is treated the same way as defensive cover for any authenticated
+ * edge state, though the backend no longer distinguishes callers once the
+ * surface is on.
+ */
+export declare function isSurfaceAbsent(error: unknown): boolean;
+/**
+ * The run the server last reported as still going, or null when it reported
+ * none. The last answer outlives the failed requests that follow it, which is
+ * what lets any tab — not only the one that pressed install — know it is inside
+ * a restart rather than looking at an unreachable service (#468). A run the user
+ * has dismissed is not one either surface still speaks for.
+ */
+export declare function runInFlight(data: RemitImapSystemUpdateResponse | undefined, dismissedRunId: string | null): RemitImapSystemUpdateRun | null;
+/**
+ * The available release from the check block, or undefined when the check
+ * reports none. Independent of what the pane is currently showing, so a retry
+ * offered from a failed run can still open consent.
+ */
+export declare function releaseFromCheck(data: RemitImapSystemUpdateResponse | undefined, now: number): ReleaseInfo | undefined;
+/**
+ * Whether installing the latest release runs a schema migration during the
+ * offline window. Derived in the client from the two versions the surface
+ * carries — the API deliberately ships the versions, never a computed boolean.
+ * Silent unless both are present and the release is on a higher schema.
+ */
+export declare function appliesSchemaMigration(data: RemitImapSystemUpdateResponse | undefined): boolean;
+export declare function deriveUpdateSurface(input: DeriveInput): DeriveResult;