@remit/web-client 0.0.324 → 0.0.326

package/dist/src/routing/wizard-history.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The selection wizard's step in the URL, and the history entries it owns
+ * (#477 clause 1.6). TanStack Router owns history here: the step is a validated
+ * `wizard` search param on /mail, pushed with `navigate({ search })`, so
+ * `router.state.location` and `window.location` never disagree.
+ *
+ * The wizard is rooted on an entry that carries no step, so the entries it owns
+ * are the pushes that reached the current step: one for the opening step, one
+ * per advance. A document that loads straight into a step has no such root, and
+ * no answers behind the step either, so it is re-rooted at the opening step
+ * before anything else — otherwise the number of entries to rewind is a guess
+ * about a tab this code never saw.
+ *
+ * Which steps Back leaves the wizard from is `backExits` in the step model, and
+ * the shell reads it to route Back to exit rather than to a step. These are the
+ * two movements it routes between: `goBack` pops one entry, `closeWizard`
+ * rewinds every entry the wizard owns.
+ */
+import { type StepId, type Verb } from "@remit/ui";
+import { z } from "zod";
+export declare const wizardStepFromParam: (value: unknown) => StepId | undefined;
+/**
+ * Which affordance opened the wizard. Absent is the selection bar; `search` is
+ * the make-filter affordance in the search results header, whose clauses come
+ * from the query rather than from ticked rows (#477 1.8).
+ *
+ * It rides the URL beside the step for the same reason the step does: a
+ * reloaded document has to know which walk it is in the middle of, and the
+ * query it was seeded from is in the URL already. It decides two things and no
+ * more — which step the wizard opens on, and whether the query seeds the
+ * clauses (#477 3.4). One host answers either way.
+ */
+declare const wizardEntry: z.ZodLiteral<"search">;
+export type WizardEntry = z.infer<typeof wizardEntry>;
+export declare const wizardEntryFromParam: (value: unknown) => WizardEntry | undefined;
+export declare const wizardEntryValue: z.ZodEffects<z.ZodUnknown, "search" | undefined, unknown>;
+export declare const useWizardEntryValue: () => WizardEntry | undefined;
+/**
+ * The route's `wizard` field. A value the wizard cannot be on reads as no step
+ * rather than as a validation failure, so a truncated or hand-typed link lands
+ * on the mail list instead of the router's error screen.
+ */
+export declare const wizardStepValue: z.ZodEffects<z.ZodUnknown, "name" | "match" | "run" | "folder" | "rule" | "review" | "properties" | undefined, unknown>;
+export declare const ownedHistoryEntries: (steps: readonly StepId[], step: StepId) => number;
+export declare const useWizardStepValue: () => StepId | undefined;
+/**
+ * Opens the wizard on a step, from a surface that does not drive it — a verb on
+ * the selection bar, or the make-filter affordance on a search. The push is the
+ * wizard's first owned entry, so the back that leaves it lands on the list with
+ * the selection still ticked.
+ */
+export declare const useOpenWizard: () => ((step: StepId, entry?: WizardEntry) => void);
+export interface SelectionWizardControl {
+    /** The verb the wizard was opened for, for the host that renders it. */
+    verb: Verb;
+    /** Opens the wizard on a verb, from the match step — every bar verb, and
+     *  every keyboard verb aimed at a selection, comes through here. */
+    start: (verb: Verb) => void;
+    /** Opens it on the search entry instead: the property step, with the query
+     *  converted (#477 1.8). The route for a verb whose match is a predicate
+     *  rather than a set of clauses. */
+    startFromSearch: () => void;
+    /**
+     * A step is held, so the wizard owns the screen. Every selection surface
+     * suspends its keyboard layer on this: a shortcut acting behind the screen
+     * already asking about an action is a second flow nobody asked for.
+     */
+    isOpen: boolean;
+}
+/**
+ * The wizard as a selection surface drives it. The step lives in the URL and
+ * the verb beside it in state, in one place rather than one copy per surface —
+ * three of them had drifted apart on which verbs they even offered.
+ */
+export declare const useSelectionWizard: () => SelectionWizardControl;
+export interface WizardStepNavigation {
+    step: StepId | undefined;
+    goToStep: (step: StepId) => void;
+    goBack: () => void;
+    closeWizard: (steps: readonly StepId[], step: StepId) => void;
+}
+export declare const useWizardStep: (openingStep: StepId) => WizardStepNavigation;
+export {};

package/dist/src/routing/wizard-history.js

@@ -0,0 +1,153 @@
+/**
+ * The selection wizard's step in the URL, and the history entries it owns
+ * (#477 clause 1.6). TanStack Router owns history here: the step is a validated
+ * `wizard` search param on /mail, pushed with `navigate({ search })`, so
+ * `router.state.location` and `window.location` never disagree.
+ *
+ * The wizard is rooted on an entry that carries no step, so the entries it owns
+ * are the pushes that reached the current step: one for the opening step, one
+ * per advance. A document that loads straight into a step has no such root, and
+ * no answers behind the step either, so it is re-rooted at the opening step
+ * before anything else — otherwise the number of entries to rewind is a guess
+ * about a tab this code never saw.
+ *
+ * Which steps Back leaves the wizard from is `backExits` in the step model, and
+ * the shell reads it to route Back to exit rather than to a step. These are the
+ * two movements it routes between: `goBack` pops one entry, `closeWizard`
+ * rewinds every entry the wizard owns.
+ */
+import { stepIndex } from "@remit/ui";
+import { useNavigate, useRouter, useSearch } from "@tanstack/react-router";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { z } from "zod";
+const stepId = z.enum([
+    "match",
+    "properties",
+    "folder",
+    "rule",
+    "name",
+    "review",
+    "run",
+]);
+export const wizardStepFromParam = (value) => {
+    const parsed = stepId.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+};
+/**
+ * Which affordance opened the wizard. Absent is the selection bar; `search` is
+ * the make-filter affordance in the search results header, whose clauses come
+ * from the query rather than from ticked rows (#477 1.8).
+ *
+ * It rides the URL beside the step for the same reason the step does: a
+ * reloaded document has to know which walk it is in the middle of, and the
+ * query it was seeded from is in the URL already. It decides two things and no
+ * more — which step the wizard opens on, and whether the query seeds the
+ * clauses (#477 3.4). One host answers either way.
+ */
+const wizardEntry = z.literal("search");
+export const wizardEntryFromParam = (value) => {
+    const parsed = wizardEntry.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+};
+export const wizardEntryValue = z.unknown().transform(wizardEntryFromParam);
+export const useWizardEntryValue = () => useSearch({ from: "/mail", select: (search) => search.wizardFrom });
+/**
+ * The route's `wizard` field. A value the wizard cannot be on reads as no step
+ * rather than as a validation failure, so a truncated or hand-typed link lands
+ * on the mail list instead of the router's error screen.
+ */
+export const wizardStepValue = z.unknown().transform(wizardStepFromParam);
+export const ownedHistoryEntries = (steps, step) => stepIndex(steps, step) + 1;
+export const useWizardStepValue = () => useSearch({ from: "/mail", select: (search) => search.wizard });
+/**
+ * Opens the wizard on a step, from a surface that does not drive it — a verb on
+ * the selection bar, or the make-filter affordance on a search. The push is the
+ * wizard's first owned entry, so the back that leaves it lands on the list with
+ * the selection still ticked.
+ */
+export const useOpenWizard = () => {
+    const navigate = useNavigate();
+    return useCallback((step, entry) => {
+        navigate({
+            to: ".",
+            search: (prev) => ({ ...prev, wizard: step, wizardFrom: entry }),
+        });
+    }, [navigate]);
+};
+/**
+ * The wizard as a selection surface drives it. The step lives in the URL and
+ * the verb beside it in state, in one place rather than one copy per surface —
+ * three of them had drifted apart on which verbs they even offered.
+ */
+export const useSelectionWizard = () => {
+    const step = useWizardStepValue();
+    const openWizard = useOpenWizard();
+    const [verb, setVerb] = useState("organize");
+    const start = useCallback((next) => {
+        setVerb(next);
+        openWizard("match");
+    }, [openWizard]);
+    const startFromSearch = useCallback(() => {
+        openWizard("properties", "search");
+    }, [openWizard]);
+    return { verb, start, startFromSearch, isOpen: step !== undefined };
+};
+export const useWizardStep = (openingStep) => {
+    const router = useRouter();
+    const navigate = useNavigate();
+    const step = useWizardStepValue();
+    const entry = useWizardEntryValue();
+    // Whether this document loaded already holding a step, which is the one
+    // entrance that leaves the wizard unrooted. A step the app itself pushed
+    // arrives rooted, so re-rooting it would duplicate the entry underneath it.
+    const loadedHoldingStep = useRef(step !== undefined);
+    // The entry that step was reached by, so the root the wizard is put back on
+    // carries neither the step nor the affordance that opened it, and the entry
+    // pushed over it carries both.
+    const loadedEntry = useRef(entry);
+    const pushedTo = useRef(undefined);
+    // Two taps on Continue land before the URL settles, and both would push the
+    // same step — leaving a back that appears to do nothing.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the guard is cleared because the step changed, which is only knowable from the dependency.
+    useEffect(() => {
+        pushedTo.current = undefined;
+    }, [step]);
+    useEffect(() => {
+        if (!loadedHoldingStep.current)
+            return;
+        loadedHoldingStep.current = false;
+        const openingEntry = loadedEntry.current;
+        void (async () => {
+            await navigate({
+                to: ".",
+                search: (prev) => ({
+                    ...prev,
+                    wizard: undefined,
+                    wizardFrom: undefined,
+                }),
+                replace: true,
+            });
+            await navigate({
+                to: ".",
+                search: (prev) => ({
+                    ...prev,
+                    wizard: openingStep,
+                    wizardFrom: openingEntry,
+                }),
+            });
+        })();
+    }, [openingStep, navigate]);
+    const goToStep = useCallback((next) => {
+        if (next === step || pushedTo.current === next)
+            return;
+        pushedTo.current = next;
+        navigate({ to: ".", search: (prev) => ({ ...prev, wizard: next }) });
+    }, [navigate, step]);
+    const goBack = useCallback(() => {
+        router.history.back();
+    }, [router]);
+    const closeWizard = useCallback((steps, current) => {
+        router.history.go(-ownedHistoryEntries(steps, current));
+    }, [router]);
+    return { step, goToStep, goBack, closeWizard };
+};

package/dist/src/runtime-config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deploy-specific configuration, read at runtime from `window.__REMIT_CONFIG__`
+ * (set by `/config.js`, loaded before the app bundle). One built artifact serves
+ * every deployment: the self-host image ships a default `config.js`, the AWS
+ * deploy writes one with Cognito values, and the dev server injects one from
+ * `REMIT_RUNTIME_CONFIG`. Nothing here is baked at build time.
+ */
+export interface CognitoConfig {
+    userPoolId: string;
+    clientId: string;
+    domain: string;
+    region: string;
+}
+export interface RumConfig {
+    appMonitorId: string;
+    identityPoolId: string;
+    region: string;
+}
+/**
+ * The deployment's TLS termination, mirroring TLS_MODE (deploy/vps/remit.env.template).
+ * "internal" is the only mode with a locally-signed root CA worth offering for
+ * download — the others are already publicly trusted or plain HTTP.
+ */
+export type TlsMode = "internal" | "acme" | "tailscale" | "off";
+export type UpdateMode = "self" | "managed";
+export interface RemitRuntimeConfig {
+    apiUrl: string;
+    appOrigin: string;
+    betterAuthEnabled: boolean;
+    cognito: CognitoConfig;
+    rum: RumConfig;
+    mailboxPollIntervalSeconds?: string;
+    disableDevtools: boolean;
+    tlsMode: TlsMode;
+    issuesUrl: string;
+    updateMode: UpdateMode;
+}
+interface RawRuntimeConfig {
+    apiUrl?: string;
+    appOrigin?: string;
+    betterAuthEnabled?: boolean;
+    cognito?: Partial<CognitoConfig>;
+    rum?: Partial<RumConfig>;
+    mailboxPollIntervalSeconds?: string | number;
+    disableDevtools?: boolean;
+    tlsMode?: string;
+    issuesUrl?: string;
+    updateMode?: string;
+}
+declare global {
+    var __REMIT_CONFIG__: RawRuntimeConfig | undefined;
+}
+/**
+ * Read `window.__REMIT_CONFIG__` fresh on each call and normalize it. Reading at
+ * call time (not module load) keeps it re-evaluable: the browser sets the global
+ * once before boot, and tests swap it between cases.
+ */
+export declare const getRuntimeConfig: () => RemitRuntimeConfig;
+export {};

package/dist/src/runtime-config.js

@@ -0,0 +1,42 @@
+/**
+ * Deploy-specific configuration, read at runtime from `window.__REMIT_CONFIG__`
+ * (set by `/config.js`, loaded before the app bundle). One built artifact serves
+ * every deployment: the self-host image ships a default `config.js`, the AWS
+ * deploy writes one with Cognito values, and the dev server injects one from
+ * `REMIT_RUNTIME_CONFIG`. Nothing here is baked at build time.
+ */
+const DEFAULT_ISSUES_URL = "https://github.com/remit-mail/reader/issues/new";
+const TLS_MODES = ["internal", "acme", "tailscale", "off"];
+const UPDATE_MODES = ["self", "managed"];
+const oneOf = (values, raw, fallback) => values.find((value) => value === raw) ?? fallback;
+/**
+ * Read `window.__REMIT_CONFIG__` fresh on each call and normalize it. Reading at
+ * call time (not module load) keeps it re-evaluable: the browser sets the global
+ * once before boot, and tests swap it between cases.
+ */
+export const getRuntimeConfig = () => {
+    const raw = globalThis.__REMIT_CONFIG__ ?? {};
+    return {
+        apiUrl: raw.apiUrl ?? "/api",
+        appOrigin: raw.appOrigin ?? "",
+        betterAuthEnabled: raw.betterAuthEnabled ?? false,
+        cognito: {
+            userPoolId: raw.cognito?.userPoolId ?? "",
+            clientId: raw.cognito?.clientId ?? "",
+            domain: raw.cognito?.domain ?? "",
+            region: raw.cognito?.region ?? "",
+        },
+        rum: {
+            appMonitorId: raw.rum?.appMonitorId ?? "",
+            identityPoolId: raw.rum?.identityPoolId ?? "",
+            region: raw.rum?.region ?? "eu-west-1",
+        },
+        mailboxPollIntervalSeconds: raw.mailboxPollIntervalSeconds != null
+            ? String(raw.mailboxPollIntervalSeconds)
+            : undefined,
+        disableDevtools: raw.disableDevtools ?? false,
+        tlsMode: oneOf(TLS_MODES, raw.tlsMode, "off"),
+        issuesUrl: raw.issuesUrl ?? DEFAULT_ISSUES_URL,
+        updateMode: oneOf(UPDATE_MODES, raw.updateMode, "self"),
+    };
+};

package/dist/src/shell/index.d.ts

@@ -0,0 +1,17 @@
+import { type AuthProvider } from "../auth/provider";
+import "../lib/i18n";
+import "../index.css";
+import "../lib/client";
+export interface MountOptions {
+    /** The identity system this build composes. */
+    authProvider: AuthProvider;
+    /** Element to mount into. Defaults to `#root`. */
+    rootElementId?: string;
+}
+/**
+ * Boot the web client against a composed auth provider. This is the app shell:
+ * providers, router, telemetry, and the global fail-fast query wiring — every
+ * primitive a deployment shares, with the identity system supplied by the
+ * distributor rather than baked in.
+ */
+export declare const mountApp: ({ authProvider, rootElementId, }: MountOptions) => void;

package/dist/src/shell/index.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MutationCache, QueryCache, QueryClient, QueryClientProvider, } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+import { RouterProvider } from "@tanstack/react-router";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { installAuthInterceptor } from "../auth/auth-interceptor";
+import { AuthProviderProvider } from "../auth/provider";
+import { install as installConsoleErrorCatcher } from "../lib/console-errors";
+import { setFatalErrorTelemetry } from "../lib/fatal-error";
+import { handleMutationCacheError, handleQueryCacheError, } from "../lib/query-error-handler";
+import { initRum } from "../lib/rum-adapter";
+import { installStaleBuildReload } from "../lib/stale-build";
+import { TelemetryContext } from "../lib/telemetry-context";
+import { installThemeSync } from "../lib/theme";
+import { createAppRouter } from "../router";
+import { getRuntimeConfig } from "../runtime-config";
+import "../lib/i18n";
+import "../index.css";
+import "../lib/client"; // Initialize client with error interceptor
+/**
+ * Boot the web client against a composed auth provider. This is the app shell:
+ * providers, router, telemetry, and the global fail-fast query wiring — every
+ * primitive a deployment shares, with the identity system supplied by the
+ * distributor rather than baked in.
+ */
+export const mountApp = ({ authProvider, rootElementId = "root", }) => {
+    installConsoleErrorCatcher();
+    installThemeSync();
+    authProvider.configure();
+    installAuthInterceptor(authProvider);
+    const telemetry = initRum();
+    // Plug the live telemetry adapter into the single fatal-error seam.
+    setFatalErrorTelemetry(telemetry);
+    // Every query and mutation error flows through the global fail-fast
+    // classifier (#1059): a non-2xx escalates to the full-screen red overlay by
+    // DEFAULT — a 5xx always escalates (even on a background refetch). Only
+    // aborts, statusless connectivity blips, and non-5xx errors a call site
+    // explicitly opted out of via `meta.softError` stay soft. This is the v5
+    // equivalent of `defaultOptions.queries.onError` / `.mutations.onError`.
+    const queryClient = new QueryClient({
+        queryCache: new QueryCache({ onError: handleQueryCacheError }),
+        mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+        defaultOptions: {
+            queries: {
+                staleTime: 30_000,
+                gcTime: 5 * 60_000,
+                retry: 1,
+            },
+        },
+    });
+    installStaleBuildReload();
+    const router = createAppRouter(queryClient, telemetry);
+    telemetry.recordPageView(window.location.pathname);
+    const rootElement = document.getElementById(rootElementId);
+    if (!rootElement) {
+        throw new Error(`Root element not found: #${rootElementId}`);
+    }
+    const { Shell } = authProvider;
+    createRoot(rootElement).render(_jsx(StrictMode, { children: _jsx(TelemetryContext.Provider, { value: telemetry, children: _jsxs(QueryClientProvider, { client: queryClient, children: [_jsx(AuthProviderProvider, { value: authProvider, children: _jsx(Shell, { children: _jsx(RouterProvider, { router: router }) }) }), !import.meta.env.PROD && !getRuntimeConfig().disableDevtools && (_jsx(ReactQueryDevtools, { initialIsOpen: false }))] }) }) }));
+};