@remit/ui 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "files": [
     "src"

package/src/components/button.render.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { Button } from "./button.js";
+
+describe("Button", () => {
+	it("defaults to the md size", () => {
+		const html = renderToString(createElement(Button, {}, "Save"));
+		assert.match(html, /h-9/);
+		assert.doesNotMatch(html, /h-11/);
+	});
+
+	it("renders the sm size at 28px", () => {
+		const html = renderToString(createElement(Button, { size: "sm" }, "Save"));
+		assert.match(html, /h-7/);
+	});
+
+	it("renders the touch size at 44px square", () => {
+		const html = renderToString(
+			createElement(Button, {
+				size: "touch",
+				"aria-label": "Delete",
+			}),
+		);
+		assert.match(html, /h-11/);
+		assert.match(html, /w-11/);
+	});
+});

package/src/components/button.tsx

@@ -1,8 +1,12 @@
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import type {
+	AnchorHTMLAttributes,
+	ButtonHTMLAttributes,
+	ReactNode,
+} from "react";
 import { cn } from "../lib/cn.js";
 
 type Variant = "primary" | "secondary" | "ghost" | "danger";
-type Size = "sm" | "md";
+type Size = "sm" | "md" | "touch";
 
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
 	variant?: Variant;
@@ -25,6 +29,10 @@ const variants: Record<Variant, string> = {
 const sizes: Record<Size, string> = {
 	sm: "h-7 px-2.5 text-xs",
 	md: "h-9 px-3.5 text-sm",
+	/** 44px square — the touch-target floor (HIG 44 / Material 48-ish). For an
+	 *  icon-only control; a control carrying a text label should size itself
+	 *  with `md` plus an explicit `min-h-11` instead of stretching to square. */
+	touch: "h-11 w-11 text-sm",
 };
 
 export function Button({
@@ -46,3 +54,37 @@ export function Button({
 		</button>
 	);
 }
+
+export interface ButtonLinkProps
+	extends AnchorHTMLAttributes<HTMLAnchorElement> {
+	variant?: Variant;
+	size?: Size;
+	icon?: ReactNode;
+	/** Opens in a new tab with the repo's standard `rel` hardening. */
+	external?: boolean;
+}
+
+/**
+ * An anchor that carries the button styling — same base, so it keeps the
+ * focus-visible ring a hand-rolled `<a className="bg-accent …">` drops.
+ */
+export function ButtonLink({
+	variant = "primary",
+	size = "md",
+	icon,
+	external,
+	className,
+	children,
+	...props
+}: ButtonLinkProps) {
+	return (
+		<a
+			className={cn(base, variants[variant], sizes[size], className)}
+			{...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+			{...props}
+		>
+			{icon}
+			{children}
+		</a>
+	);
+}

package/src/components/primitives.stories.tsx

@@ -30,6 +30,12 @@ export const Buttons: Story = {
 			<Button variant="primary" disabled>
 				Disabled
 			</Button>
+			<Button
+				variant="ghost"
+				size="touch"
+				icon={<Mail className="size-4" />}
+				aria-label="Touch-sized icon button"
+			/>
 		</div>
 	),
 };

package/src/components/progress-bar.render.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ProgressBar } from "./progress-bar.js";
+
+describe("ProgressBar", () => {
+	it("renders progressbar role with the aria value triad", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 1200, max: 3412 }),
+		);
+		assert.match(html, /role="progressbar"/);
+		assert.match(html, /aria-valuenow="1200"/);
+		assert.match(html, /aria-valuemin="0"/);
+		assert.match(html, /aria-valuemax="3412"/);
+	});
+
+	it("computes the fill width as a percentage of value/max", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 25, max: 100 }),
+		);
+		assert.match(html, /width:25%/);
+	});
+
+	it("clamps the fill at 100% when value exceeds max", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 500, max: 100 }),
+		);
+		assert.match(html, /width:100%/);
+	});
+
+	it("omits the aria value triad when indeterminate", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 0, max: 0, indeterminate: true }),
+		);
+		assert.doesNotMatch(html, /aria-valuenow/);
+		assert.doesNotMatch(html, /aria-valuemax/);
+	});
+
+	it("applies the tone's fill color", () => {
+		const html = renderToString(
+			createElement(ProgressBar, { value: 1, max: 2, tone: "danger" }),
+		);
+		assert.match(html, /bg-danger/);
+	});
+});

package/src/components/progress-bar.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ProgressBar } from "./progress-bar.js";
+
+const meta: Meta<typeof ProgressBar> = {
+	title: "Components/ProgressBar",
+	component: ProgressBar,
+	parameters: { layout: "padded" },
+	render: (args) => (
+		<div className="w-80">
+			<ProgressBar {...args} />
+		</div>
+	),
+};
+export default meta;
+
+type Story = StoryObj<typeof ProgressBar>;
+
+export const Started: Story = { args: { value: 340, max: 3412 } };
+
+export const Halfway: Story = { args: { value: 1706, max: 3412 } };
+
+export const NearlyDone: Story = { args: { value: 3072, max: 3412 } };
+
+export const Success: Story = {
+	args: { value: 3412, max: 3412, tone: "success" },
+};
+
+export const Danger: Story = {
+	args: { value: 1200, max: 3412, tone: "danger" },
+};
+
+/** Total is unknown — a paging search count, before the first page resolves. */
+export const Indeterminate: Story = {
+	args: { value: 0, max: 0, indeterminate: true },
+};

package/src/components/progress-bar.tsx

@@ -0,0 +1,62 @@
+import { cn } from "../lib/cn.js";
+import type { BannerTone } from "./banner.js";
+
+export interface ProgressBarProps {
+	/** Units completed so far. Ignored when `indeterminate`. */
+	value: number;
+	/** Total units. Ignored when `indeterminate`. */
+	max: number;
+	tone?: BannerTone;
+	/** Unknown total (or unknown rate) — an animated fill with no fixed end. */
+	indeterminate?: boolean;
+	className?: string;
+}
+
+const tones: Record<BannerTone, string> = {
+	info: "bg-accent-2",
+	success: "bg-positive",
+	warning: "bg-warning",
+	danger: "bg-danger",
+};
+
+/**
+ * Determinate (or indeterminate) progress meter for a bulk operation, e.g. a
+ * multi-thousand-message delete running in batches. A bare running count
+ * gives no sense of rate over a long operation; a filling bar answers "is
+ * this stuck?" pre-attentively.
+ */
+export function ProgressBar({
+	value,
+	max,
+	tone = "info",
+	indeterminate = false,
+	className,
+}: ProgressBarProps) {
+	const pct = indeterminate
+		? 100
+		: max <= 0
+			? 0
+			: Math.min(100, Math.max(0, (value / max) * 100));
+
+	return (
+		<div
+			role="progressbar"
+			aria-valuenow={indeterminate ? undefined : value}
+			aria-valuemin={indeterminate ? undefined : 0}
+			aria-valuemax={indeterminate ? undefined : max}
+			className={cn(
+				"h-1.5 w-full overflow-hidden rounded-full bg-surface-sunken",
+				className,
+			)}
+		>
+			<div
+				className={cn(
+					"h-full rounded-full transition-[width] duration-300 ease-out",
+					tones[tone],
+					indeterminate && "w-1/3 animate-pulse",
+				)}
+				style={indeterminate ? undefined : { width: `${pct}%` }}
+			/>
+		</div>
+	);
+}

package/src/components/quarantine-bug-dialog.tsx

@@ -0,0 +1,72 @@
+import { Copy, ExternalLink } from "lucide-react";
+import { Button, ButtonLink } from "./button.js";
+import { Dialog } from "./dialog.js";
+import {
+	formatQuarantineReport,
+	type QuarantineEntry,
+} from "./quarantine-report.js";
+
+export interface QuarantineBugDialogProps {
+	entry: QuarantineEntry | null;
+	onClose: () => void;
+	/**
+	 * Prefilled new-issue URL, built by the app's shared bug-report helper so
+	 * the URL budget and the repository constant stay in one place.
+	 */
+	issueUrl: string;
+	onCopy: (report: string) => void;
+}
+
+/**
+ * The report, in full, before it goes anywhere. Filing opens the user's own
+ * GitHub session with the issue prefilled — Remit never posts on their behalf,
+ * and nothing is sent that is not on this screen.
+ */
+export function QuarantineBugDialog({
+	entry,
+	onClose,
+	issueUrl,
+	onCopy,
+}: QuarantineBugDialogProps) {
+	if (!entry) return null;
+	const report = formatQuarantineReport(entry);
+
+	return (
+		<Dialog open onClose={onClose} title="Report this message">
+			<div className="flex max-h-[80vh] flex-col">
+				<header className="space-y-1 border-b border-line px-4 py-3">
+					<h3 className="text-sm font-semibold text-fg">Report this message</h3>
+					<p className="text-xs text-fg-muted">
+						This is everything the report contains. It describes the shape of
+						the message — never its contents, addresses, subject, attachment
+						names, or the parser's own error text.
+					</p>
+				</header>
+				<pre className="flex-1 overflow-auto bg-surface-sunken px-4 py-3 text-2xs leading-relaxed whitespace-pre-wrap text-fg-muted">
+					{report}
+				</pre>
+				<footer className="flex flex-wrap items-center justify-end gap-2 border-t border-line px-4 py-3">
+					<Button variant="ghost" size="sm" onClick={onClose}>
+						Cancel
+					</Button>
+					<Button
+						variant="secondary"
+						size="sm"
+						icon={<Copy className="size-3.5" />}
+						onClick={() => onCopy(report)}
+					>
+						Copy report
+					</Button>
+					<ButtonLink
+						external
+						size="sm"
+						href={issueUrl}
+						icon={<ExternalLink className="size-3.5" />}
+					>
+						Open on GitHub
+					</ButtonLink>
+				</footer>
+			</div>
+		</Dialog>
+	);
+}

package/src/components/quarantine-entry-row.tsx

@@ -0,0 +1,71 @@
+import { Bug } from "lucide-react";
+import { Badge } from "./badge.js";
+import { Button } from "./button.js";
+import { canonicalRoleLabel, providerLeaf } from "./folder-role.js";
+import {
+	type QuarantineEntry,
+	quarantineSummary,
+} from "./quarantine-report.js";
+
+export interface QuarantineEntryRowProps {
+	entry: QuarantineEntry;
+	onCutBug: (entry: QuarantineEntry) => void;
+}
+
+function formatQuarantinedAt(epochMillis: number): string {
+	return new Date(epochMillis).toLocaleString(undefined, {
+		dateStyle: "medium",
+		timeStyle: "short",
+	});
+}
+
+/**
+ * One quarantined message. Leads with what went wrong in plain language, then
+ * the parser's own words — which stay on this screen and never enter a report
+ * — and the folder, uid and time as identifying detail.
+ */
+export function QuarantineEntryRow({
+	entry,
+	onCutBug,
+}: QuarantineEntryRowProps) {
+	return (
+		<li className="flex flex-col gap-2 border-b border-line px-row-inset py-3 last:border-b-0 sm:flex-row sm:items-start sm:justify-between">
+			<div className="min-w-0 space-y-1">
+				<p className="text-sm text-fg">
+					{quarantineSummary(entry.failureStage)}
+				</p>
+				<p
+					className="truncate text-xs text-fg-muted"
+					title={entry.failureMessage}
+				>
+					{entry.failureMessage}
+				</p>
+				<p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-2xs text-fg-subtle">
+					<Badge tone="warning">{canonicalRoleLabel(entry.mailboxRole)}</Badge>
+					<span className="truncate" title={entry.mailboxPath}>
+						{providerLeaf(entry.mailboxPath)}
+					</span>
+					<span aria-hidden>·</span>
+					<span>{`uid ${entry.uid}`}</span>
+					<span aria-hidden>·</span>
+					<span>{formatQuarantinedAt(entry.quarantinedAt)}</span>
+					{entry.attempts > 1 && (
+						<>
+							<span aria-hidden>·</span>
+							<span>{`${entry.attempts} attempts`}</span>
+						</>
+					)}
+				</p>
+			</div>
+			<Button
+				variant="secondary"
+				size="sm"
+				className="shrink-0"
+				icon={<Bug className="size-3.5" />}
+				onClick={() => onCutBug(entry)}
+			>
+				Cut a bug
+			</Button>
+		</li>
+	);
+}

package/src/components/quarantine-fixtures.ts

@@ -0,0 +1,81 @@
+import type { QuarantineEntry } from "./quarantine-report.js";
+
+/**
+ * Demo entries backing the quarantine stories. Exported so the kit's own
+ * stories and the workbench settings screen render the same data — they had
+ * drifted on `appVersion` when each file carried its own copy.
+ */
+export const quarantineDemoEntries: readonly QuarantineEntry[] = [
+	{
+		quarantineId: "q-1",
+		accountId: "acct-1",
+		mailboxId: "mbx-inbox",
+		uid: 40217,
+		mailboxRole: "inbox",
+		mailboxPath: "INBOX",
+		failureStage: "BodyParse",
+		failureCode: "UnterminatedMultipartBoundary",
+		failureMessage: "multipart boundary was never closed",
+		failurePartPath: null,
+		quarantinedAt: Date.parse("2026-07-18T09:12:00Z"),
+		attempts: 3,
+		sizeBytes: 184_233,
+		contentType: "multipart/mixed",
+		transferEncoding: "7bit",
+		charset: "utf-8",
+		structure: {
+			contentType: "multipart/mixed",
+			parts: [
+				{
+					contentType: "multipart/alternative",
+					parts: [{ contentType: "text/plain" }, { contentType: "text/html" }],
+				},
+				{ contentType: "application/pdf" },
+			],
+		},
+		messageIdHash: "sha256:6f1c4a9d20",
+		appVersion: "worker 1.0.0",
+	},
+	{
+		quarantineId: "q-2",
+		accountId: "acct-1",
+		mailboxId: "mbx-archive",
+		uid: 40219,
+		mailboxRole: "archive",
+		mailboxPath: "Archive/2026",
+		failureStage: "BodyParse",
+		failureCode: "UnknownCharset",
+		failureMessage: "declared charset is not a known encoding",
+		failurePartPath: "1.2",
+		quarantinedAt: Date.parse("2026-07-18T14:40:00Z"),
+		attempts: 3,
+		sizeBytes: 9_812,
+		contentType: "text/plain",
+		transferEncoding: "quoted-printable",
+		charset: "x-user-defined",
+		structure: { contentType: "text/plain" },
+		messageIdHash: "sha256:b31e0744af",
+		appVersion: "worker 1.0.0",
+	},
+	{
+		quarantineId: "q-3",
+		accountId: "acct-1",
+		mailboxId: "mbx-junk",
+		uid: 40251,
+		mailboxRole: "junk",
+		mailboxPath: "Junk",
+		failureStage: "BodyParse",
+		failureCode: "TruncatedBody",
+		failureMessage: "stream ended before the declared body length",
+		failurePartPath: null,
+		quarantinedAt: Date.parse("2026-07-19T06:03:00Z"),
+		attempts: 1,
+		sizeBytes: 2_140,
+		contentType: "text/html",
+		transferEncoding: "base64",
+		charset: null,
+		structure: { contentType: "text/html" },
+		messageIdHash: "sha256:0a77de1c05",
+		appVersion: "worker 1.0.0",
+	},
+];

package/src/components/quarantine-report.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { quarantineDemoEntries } from "./quarantine-fixtures.js";
+import {
+	formatQuarantineReport,
+	QUARANTINE_REPORT_DISCLAIMER,
+	type QuarantineEntry,
+	quarantineIssueTitle,
+	quarantineReportSections,
+	quarantineSummary,
+} from "./quarantine-report.js";
+
+const entry: QuarantineEntry = {
+	...quarantineDemoEntries[0],
+	mailboxPath: "Clients/Acme Holdings",
+	failureMessage: "invalid address: joan@acme-holdings.example",
+};
+
+describe("formatQuarantineReport", () => {
+	it("names the stage, the code and the build that failed", () => {
+		const report = formatQuarantineReport(entry);
+		assert.match(report, /BodyParse/);
+		assert.match(report, /UnterminatedMultipartBoundary/);
+		assert.match(report, /worker 1\.0\.0/);
+	});
+
+	it("renders the MIME tree as structure with no content", () => {
+		const report = formatQuarantineReport(entry);
+		assert.match(report, /\n- multipart\/mixed/);
+		assert.match(report, /\n {2}- multipart\/alternative/);
+		assert.match(report, /\n {4}- text\/html/);
+		assert.match(report, /\n {2}- application\/pdf/);
+	});
+
+	it("withholds the user's own folder name", () => {
+		const report = formatQuarantineReport(entry);
+		assert.doesNotMatch(report, /Acme Holdings/);
+		assert.match(report, /Folder role.*inbox/);
+	});
+
+	it("withholds the parser's own error text, which can quote the input", () => {
+		const report = formatQuarantineReport(entry);
+		assert.doesNotMatch(report, /joan@acme-holdings\.example/);
+		assert.doesNotMatch(report, /invalid address/);
+	});
+
+	it("strips content-type parameters, which carry attachment filenames", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			contentType: 'multipart/mixed; boundary="=_a1b2"',
+			structure: {
+				contentType: "multipart/mixed",
+				parts: [
+					{
+						contentType:
+							'application/octet-stream; name="Q3 payroll — Acme.pdf"',
+					},
+				],
+			},
+		});
+		assert.doesNotMatch(report, /payroll/);
+		assert.doesNotMatch(report, /boundary/);
+		assert.match(report, /- application\/octet-stream/);
+	});
+
+	it("says so when the failure is not attributable to one part", () => {
+		assert.match(formatQuarantineReport(entry), /Failing part.*whole message/);
+		assert.match(
+			formatQuarantineReport({ ...entry, failurePartPath: "1.2" }),
+			/Failing part.*`1\.2`/,
+		);
+	});
+
+	it("marks an undeclared charset rather than omitting it", () => {
+		const report = formatQuarantineReport({ ...entry, charset: null });
+		assert.match(report, /Charset.*not declared/);
+	});
+});
+
+describe("sender-controlled BODYSTRUCTURE strings", () => {
+	// charset, transferEncoding and contentType are arbitrary quoted strings
+	// chosen by whoever sent the message, echoed into an issue filed under the
+	// user's own account. They are hostile input.
+	const injection = "`\n\n**Click here:** https://evil.example\n\n`";
+
+	it("cannot break out of the code span and inject markdown", () => {
+		const report = formatQuarantineReport({ ...entry, charset: injection });
+		const line = report.split("\n").find((l) => l.startsWith("- **Charset**:"));
+		assert.ok(line, "Expected a charset line");
+		// Neutralised, not deleted: the payload survives as literal text inside
+		// a code span, which needs the value to carry no raw newline and no
+		// backtick beyond the two delimiters.
+		assert.equal((line.match(/`/g) ?? []).length, 2);
+		assert.doesNotMatch(report, /^\s*\*\*Click here:\*\*/m);
+	});
+
+	it("keeps the malformed value visible, since it is usually the bug", () => {
+		const report = formatQuarantineReport({ ...entry, charset: injection });
+		assert.match(report, /malformed/);
+		assert.match(report, /evil\.example/);
+	});
+
+	it("renders a conforming value as itself", () => {
+		const report = formatQuarantineReport({ ...entry, charset: "utf-8" });
+		assert.match(report, /\*\*Charset\*\*: `utf-8`/);
+		assert.doesNotMatch(report, /malformed/);
+	});
+
+	it("keeps a hostile node type from closing the MIME fence", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			structure: {
+				contentType: "multipart/mixed",
+				parts: [{ contentType: "```\n## Injected heading" }],
+			},
+		});
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+		assert.doesNotMatch(report, /^## Injected heading/m);
+	});
+});
+
+describe("quarantineReportSections", () => {
+	it("hands the MIME tree over unfenced, so it can be truncated safely", () => {
+		const { head, structure, disclaimer } = quarantineReportSections(entry);
+		assert.doesNotMatch(structure, /```/);
+		assert.doesNotMatch(head, /```/);
+		assert.equal(disclaimer, QUARANTINE_REPORT_DISCLAIMER);
+	});
+
+	it("assembles back into the fenced report the dialog shows", () => {
+		const report = formatQuarantineReport(entry);
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+		assert.ok(report.endsWith(QUARANTINE_REPORT_DISCLAIMER));
+	});
+});
+
+describe("quarantineIssueTitle", () => {
+	it("carries only the closed vocabulary", () => {
+		const title = quarantineIssueTitle(entry);
+		assert.match(title, /UnterminatedMultipartBoundary/);
+		assert.match(title, /BodyParse/);
+		assert.doesNotMatch(title, /joan@/);
+	});
+});
+
+describe("quarantineSummary", () => {
+	it("explains the stage without parser jargon", () => {
+		const summary = quarantineSummary("BodyParse");
+		assert.doesNotMatch(summary, /MIME|RFC|mailparser|charset=/i);
+	});
+});