@remit/ui 0.0.145 → 0.0.147

package/package.json

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

package/src/components/calendar-types.ts

@@ -82,6 +82,26 @@ export interface CalendarEventData {
 	status: "confirmed" | "tentative";
 }
 
+/**
+ * One clock a zoneless time could be on. Present only when the source genuinely
+ * did not say which, and the reader is the one who settles it.
+ */
+export interface ZoneOption {
+	/** IANA zone, and the identity of the choice. */
+	timeZone: string;
+	/** The time as this clock reads it — "20:25 in Lisbon". */
+	label: string;
+	/** What that means on the reader's own clock. */
+	note: string;
+}
+
+/**
+ * The clocks a zoneless time could be on. Never empty: a question with no
+ * answers is a card the reader can look at and never get past, so having no
+ * question to ask is the absent list, not the empty one.
+ */
+export type ZoneOptions = readonly [ZoneOption, ...ZoneOption[]];
+
 /**
  * A candidate read out of mail. It is deliberately not a `CalendarEventData`:
  * nothing reaches the grid until a person confirms it, so a suggestion cannot
@@ -107,6 +127,11 @@ export interface EventSuggestion {
 	suggestedCalendarId: string;
 	timeZone: string;
 	zoneCertainty: ZoneCertainty;
+	/**
+	 * The clocks the time could be on. Absent when the source said which, which
+	 * is the only case where `timeZone` above can be trusted on its own.
+	 */
+	zoneOptions?: ZoneOptions;
 }
 
 /** Which instances of a series an edit applies to, chosen before the edit. */

package/src/components/event-suggestion-card.render.test.ts

@@ -23,11 +23,13 @@ const suggestion: EventSuggestion = {
 	zoneCertainty: "explicit",
 };
 
-const render = (overrides: Partial<EventSuggestion>) =>
+const render = (overrides: Partial<EventSuggestion>, zoneChoice?: string) =>
 	renderToString(
 		createElement(EventSuggestionCard, {
 			suggestion: { ...suggestion, ...overrides },
 			whenText: "Friday 19 June – Monday 22 June",
+			zoneChoice,
+			onZoneChoice: () => undefined,
 			onAdd: () => undefined,
 			onReview: () => undefined,
 			onDismiss: () => undefined,
@@ -35,6 +37,21 @@ const render = (overrides: Partial<EventSuggestion>) =>
 		}),
 	);
 
+const twoClocks: Partial<EventSuggestion> = {
+	zoneOptions: [
+		{
+			timeZone: "Europe/Lisbon",
+			label: "16:00 in Lisbon",
+			note: "17:00 on your own clock.",
+		},
+		{
+			timeZone: "Europe/Amsterdam",
+			label: "16:00 in Amsterdam",
+			note: "15:00 where she is.",
+		},
+	],
+};
+
 describe("EventSuggestionCard", () => {
 	it("says it is a suggestion and not an event", () => {
 		const html = render({});
@@ -63,4 +80,28 @@ describe("EventSuggestionCard", () => {
 	it("needs a person to press Add", () => {
 		assert.match(render({}), />Add</);
 	});
+
+	it("asks nothing about the clock when the mail stated one", () => {
+		const html = render({});
+		assert.doesNotMatch(html, /Which clock is this on\?/);
+		assert.doesNotMatch(html, /Pick a clock first/);
+		assert.doesNotMatch(html, /aria-describedby/);
+	});
+
+	it("offers the clocks and dims Add while none is picked", () => {
+		const html = render(twoClocks);
+		assert.match(html, /Which clock is this on\?/);
+		assert.match(html, /16:00 in Lisbon/);
+		assert.match(html, /Pick a clock first/);
+		assert.match(html, /aria-describedby/);
+		assert.match(html, /opacity-55/);
+	});
+
+	it("undims Add once one of the clocks is picked", () => {
+		const html = render(twoClocks, "Europe/Lisbon");
+		assert.match(html, /aria-pressed="true"/);
+		assert.doesNotMatch(html, /Pick a clock first/);
+		assert.doesNotMatch(html, /aria-describedby/);
+		assert.doesNotMatch(html, /opacity-55/);
+	});
 });

package/src/components/event-suggestion-card.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import type { EventSuggestion } from "./calendar-types.js";
+import { useState } from "react";
+import type { EventSuggestion, ZoneOptions } from "./calendar-types.js";
 import { EventSuggestionCard } from "./event-suggestion-card.js";
 
 /**
@@ -81,6 +82,77 @@ export const WithAmbiguity: Story = {
 	),
 };
 
+const twoClocks: ZoneOptions = [
+	{
+		timeZone: "Europe/Lisbon",
+		label: "16:00 in Lisbon",
+		note: "17:00 on your own clock. The hour she keeps.",
+	},
+	{
+		timeZone: "Europe/Amsterdam",
+		label: "16:00 in Amsterdam",
+		note: "15:00 where she is.",
+	},
+];
+
+const call: EventSuggestion = {
+	...base,
+	id: "s3",
+	title: "Kickoff call — Lisbon venue",
+	allDay: false,
+	location: "Meet link",
+	threadSubject: "Kickoff call on Wednesday at 16:00",
+	sender: "Rita Sousa",
+	confidence: 0.66,
+	ambiguity:
+		"Rita writes from Lisbon and names 16:00 without a clock. Lisbon runs an hour behind Amsterdam.",
+	timeZone: "",
+	zoneCertainty: "ambiguous",
+	zoneOptions: twoClocks,
+};
+
+function GatedCall({ picked }: { picked: string }) {
+	const [zoneChoice, setZoneChoice] = useState(picked);
+	const [carried, setCarried] = useState("");
+	return (
+		<div className="flex flex-col gap-2">
+			<EventSuggestionCard
+				suggestion={call}
+				whenText="Wednesday 17 June · 16:00 – 17:00"
+				zoneChoice={zoneChoice}
+				onZoneChoice={setZoneChoice}
+				onAdd={(timeZone) => setCarried(`Added on ${timeZone}`)}
+				onReview={(timeZone) => setCarried(`Editor opened on ${timeZone}`)}
+				onDismiss={() => {}}
+				onOpenThread={() => {}}
+			/>
+			<p className="text-2xs text-fg-subtle">
+				{carried === "" ? "Nothing has left the card yet." : carried}
+			</p>
+		</div>
+	);
+}
+
+/**
+ * The mail printed an hour and never said whose clock it is on. Both ways out
+ * of the card are dimmed and stay dimmed until one is picked — an hour guessed
+ * wrong is a call missed, and an editor opened on that hour hides the guess
+ * behind a field the reader is invited to trust.
+ */
+export const ZoneWeCannotDetermine: Story = {
+	name: "The zone we cannot determine",
+	render: () => <GatedCall picked="" />,
+};
+
+/**
+ * Answered. Both buttons are live, and each carries the clock that was named —
+ * Add books it, Change first opens on it.
+ */
+export const ZonePicked: Story = {
+	name: "The clock is picked",
+	render: () => <GatedCall picked="Europe/Lisbon" />,
+};
+
 /** The same card sized for a phone sheet. */
 export const Touch: Story = {
 	render: () => (

package/src/components/event-suggestion-card.tsx

@@ -1,16 +1,67 @@
-import { AlertTriangle, Mail, Plus, SlidersHorizontal, X } from "lucide-react";
+import {
+	AlertTriangle,
+	Globe,
+	Mail,
+	Plus,
+	SlidersHorizontal,
+	X,
+} from "lucide-react";
+import { useId, useState } from "react";
 import { cn } from "../lib/cn.js";
+import { BlockedReason } from "./blocked-reason.js";
 import { Button } from "./button.js";
 import type { EventSuggestion } from "./calendar-types.js";
 
+export const ZONE_UNSETTLED_REASON =
+	"Pick a clock first. The mail never said, and the reader will not choose for you.";
+
+/**
+ * Which zone the suggestion would be booked on. `timeZone` is empty when the
+ * source said it itself and the reader settled nothing.
+ */
+export type ZoneSettlement =
+	| { settled: true; timeZone: string }
+	| { settled: false; reason: string };
+
+/**
+ * A time nobody stated a zone for is an hour nobody stated. The choice has to
+ * come from the reader and it has to be one of the clocks offered — a stale or
+ * unrecognised choice leaves the suggestion unsettled rather than guessing, and
+ * nothing here reads the zone the browser happens to be in.
+ *
+ * This is the only place the rule is written. Every surface that offers the
+ * clocks — the card here, the seam's strip, the phone deck behind it — asks
+ * this, so none of them can disagree about whether a suggestion is answered.
+ */
+export function settleZone(
+	suggestion: EventSuggestion,
+	zoneChoice: string,
+): ZoneSettlement {
+	const options = suggestion.zoneOptions;
+	if (options === undefined) return { settled: true, timeZone: "" };
+	if (options.some((option) => option.timeZone === zoneChoice))
+		return { settled: true, timeZone: zoneChoice };
+	return { settled: false, reason: ZONE_UNSETTLED_REASON };
+}
+
 export interface EventSuggestionCardProps {
 	suggestion: EventSuggestion;
 	/** Already formatted by the caller. */
 	whenText: string;
-	onAdd: () => void;
-	onReview: () => void;
+	/** The zone the reader settled on, empty when the mail already knew. */
+	onAdd: (timeZone: string) => void;
+	/**
+	 * Correcting the reading first. It is handed the same settled zone Add is,
+	 * and is refused on the same terms — an editor opened on an hour nobody has
+	 * placed on a clock seeds the draft with the wrong time, which is the
+	 * mistake Add is dimmed to prevent.
+	 */
+	onReview: (timeZone: string) => void;
 	onDismiss: () => void;
 	onOpenThread: () => void;
+	/** The clock picked so far. Omit to let the card hold the choice itself. */
+	zoneChoice?: string;
+	onZoneChoice?: (timeZone: string) => void;
 	touch?: boolean;
 	className?: string;
 }
@@ -27,6 +78,11 @@ function confidenceText(confidence: number): string {
  * dashed card, and only a person pressing Add puts anything on the calendar —
  * a machine reading of a mail never becomes a provisional block that someone
  * has to notice and remove.
+ *
+ * Where the mail never said which clock a time is on, every way out of the card
+ * that carries the time — Add, and correcting it first — is dimmed until the
+ * reader picks one and refuses the press until then: booking the wrong hour is
+ * worse than asking, and so is opening an editor already filled with it.
  */
 export function EventSuggestionCard({
 	suggestion,
@@ -35,11 +91,32 @@ export function EventSuggestionCard({
 	onReview,
 	onDismiss,
 	onOpenThread,
+	zoneChoice,
+	onZoneChoice,
 	touch,
 	className,
 }: EventSuggestionCardProps) {
+	const [ownChoice, setOwnChoice] = useState("");
+	const [nudged, setNudged] = useState(false);
+	const reasonId = useId();
+	const choice = zoneChoice ?? ownChoice;
+	const pickZone = (timeZone: string) => {
+		setNudged(false);
+		if (onZoneChoice) onZoneChoice(timeZone);
+		else setOwnChoice(timeZone);
+	};
+	const settlement = settleZone(suggestion, choice);
+	const carryingTheZone = (act: (timeZone: string) => void) => () => {
+		if (!settlement.settled) {
+			setNudged(true);
+			return;
+		}
+		act(settlement.timeZone);
+	};
+
 	return (
-		<div
+		<article
+			aria-label={suggestion.title}
 			className={cn(
 				"flex flex-col gap-2 rounded-lg border border-dashed border-line-strong bg-surface-sunken p-3",
 				className,
@@ -91,13 +168,57 @@ export function EventSuggestionCard({
 				</span>
 			</button>
 
+			{suggestion.zoneOptions && (
+				<div className="flex flex-col gap-1.5 rounded-md border border-warning/40 p-2">
+					<p className="flex items-center gap-1.5 text-2xs font-semibold text-warning">
+						<Globe className="size-3 shrink-0" aria-hidden />
+						Which clock is this on?
+					</p>
+					{suggestion.zoneOptions.map((option) => (
+						<button
+							key={option.timeZone}
+							type="button"
+							aria-pressed={choice === option.timeZone}
+							onClick={() => pickZone(option.timeZone)}
+							className={cn(
+								"rounded-md border px-2 py-1 text-left outline-none focus-visible:ring-2 focus-visible:ring-ring",
+								touch && "min-h-11",
+								choice === option.timeZone
+									? "border-accent bg-accent-soft"
+									: "border-line bg-surface hover:border-line-strong",
+							)}
+						>
+							<span className="block text-xs font-medium text-fg">
+								{option.label}
+							</span>
+							<span className="block text-2xs text-fg-subtle">
+								{option.note}
+							</span>
+						</button>
+					))}
+				</div>
+			)}
+
+			{!settlement.settled && (
+				<BlockedReason
+					id={reasonId}
+					reason={settlement.reason}
+					nudged={nudged}
+					className="text-2xs text-warning"
+				/>
+			)}
+
 			<div className="flex items-center gap-2">
 				<Button
 					variant="primary"
 					size={touch ? "md" : "sm"}
 					icon={<Plus className="size-3.5" />}
-					onClick={onAdd}
-					className={touch ? "min-h-11 flex-1" : ""}
+					onClick={carryingTheZone(onAdd)}
+					aria-describedby={settlement.settled ? undefined : reasonId}
+					className={cn(
+						touch && "min-h-11 flex-1",
+						!settlement.settled && "opacity-55",
+					)}
 				>
 					Add
 				</Button>
@@ -105,12 +226,16 @@ export function EventSuggestionCard({
 					variant="secondary"
 					size={touch ? "md" : "sm"}
 					icon={<SlidersHorizontal className="size-3.5" />}
-					onClick={onReview}
-					className={touch ? "min-h-11" : ""}
+					onClick={carryingTheZone(onReview)}
+					aria-describedby={settlement.settled ? undefined : reasonId}
+					className={cn(
+						touch && "min-h-11",
+						!settlement.settled && "opacity-55",
+					)}
 				>
 					Change first
 				</Button>
 			</div>
-		</div>
+		</article>
 	);
 }

package/src/components/event-suggestion-card.zone-gate.test.ts

@@ -0,0 +1,328 @@
+/**
+ * The zone gate — mounted against jsdom rather than `renderToString`, because
+ * what has to be proven is that pressing either way out of the card does
+ * nothing while the clock is unsettled.
+ *
+ * Nothing here may read the zone the process happens to run in, so the cases
+ * offer clocks the ambient zone is never one of, assert the exact zone that
+ * comes back, and move the machine between zones themselves rather than leaving
+ * that to whoever runs the suite.
+ */
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { EventSuggestion, ZoneOptions } from "./calendar-types.js";
+import {
+	EventSuggestionCard,
+	settleZone,
+	ZONE_UNSETTLED_REASON,
+} from "./event-suggestion-card.js";
+
+const LISBON = "Europe/Lisbon";
+const AUCKLAND = "Pacific/Auckland";
+
+const suggestion: EventSuggestion = {
+	id: "sug_lisbon_call",
+	title: "Kickoff call — Lisbon venue",
+	start: "2026-06-17T16:00:00+02:00",
+	end: "2026-06-17T17:00:00+02:00",
+	allDay: false,
+	location: "Meet link",
+	threadId: "thr_lisbon_call",
+	threadSubject: "Kickoff call on Wednesday at 16:00",
+	sender: "Rita Sousa",
+	senderAddress: "rita@aldeia.example",
+	confidence: 0.66,
+	ambiguity: "",
+	suggestedCalendarId: "c5",
+	timeZone: "",
+	zoneCertainty: "ambiguous",
+};
+
+const zoneless: EventSuggestion = {
+	...suggestion,
+	zoneOptions: [
+		{ timeZone: LISBON, label: "16:00 in Lisbon", note: "17:00 for you." },
+		{ timeZone: AUCKLAND, label: "16:00 in Auckland", note: "03:00 for you." },
+	],
+};
+
+const stated: EventSuggestion = {
+	...suggestion,
+	timeZone: LISBON,
+	zoneCertainty: "explicit",
+};
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	dom = new JSDOMCtor(
+		"<!doctype html><html><body><div id=root></div></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.MouseEvent = dom.window.MouseEvent;
+	Object.defineProperty(globalThis, "navigator", {
+		value: dom.window.navigator,
+		configurable: true,
+	});
+	(
+		globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+	).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+after(() => {
+	dom.window.close();
+});
+
+beforeEach(() => {
+	container = dom.window.document.getElementById(
+		"root",
+	) as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+});
+
+interface Answers {
+	onAdd?: (timeZone: string) => void;
+	onReview?: (timeZone: string) => void;
+}
+
+function mount(entry: EventSuggestion, answers: Answers = {}) {
+	act(() => {
+		root.render(
+			createElement(EventSuggestionCard, {
+				suggestion: entry,
+				whenText: "Friday 19 June · 18:40 – 20:25",
+				onAdd: answers.onAdd ?? (() => undefined),
+				onReview: answers.onReview ?? (() => undefined),
+				onDismiss: () => undefined,
+				onOpenThread: () => undefined,
+			}),
+		);
+	});
+}
+
+function buttonNamed(text: string): HTMLElement {
+	const found = Array.from(container.querySelectorAll("button")).find(
+		(candidate) => candidate.textContent?.includes(text),
+	);
+	assert.ok(found, `no button reading ${text}`);
+	return found as unknown as HTMLElement;
+}
+
+function press(target: HTMLElement) {
+	act(() => {
+		target.dispatchEvent(new dom.window.MouseEvent("click", { bubbles: true }));
+	});
+}
+
+/** The paragraph the dimmed Add points at through `aria-describedby`. */
+function describedReason(): HTMLElement | null {
+	const id = buttonNamed("Add").getAttribute("aria-describedby");
+	if (id === null) return null;
+	return dom.window.document.getElementById(id);
+}
+
+function announced(): string {
+	return Array.from(container.querySelectorAll('[role="status"]'))
+		.map((node) => node.textContent ?? "")
+		.join(" ");
+}
+
+describe("the zone gate", () => {
+	it("refuses Add until a clock is picked, and says why", () => {
+		const added: string[] = [];
+		mount(zoneless, { onAdd: (timeZone) => added.push(timeZone) });
+
+		assert.equal(announced(), "");
+		assert.equal(describedReason()?.textContent, ZONE_UNSETTLED_REASON);
+		assert.ok(describedReason()?.classList.contains("sr-only"));
+
+		press(buttonNamed("Add"));
+
+		assert.deepEqual(added, []);
+		assert.match(announced(), /Pick a clock first/);
+		assert.equal(describedReason()?.classList.contains("sr-only"), false);
+	});
+
+	it("adds on the clock that was picked, never on the ambient one", () => {
+		const added: string[] = [];
+		mount(zoneless, { onAdd: (timeZone) => added.push(timeZone) });
+
+		press(buttonNamed("16:00 in Auckland"));
+		press(buttonNamed("Add"));
+
+		assert.deepEqual(added, [AUCKLAND]);
+		assert.notEqual(
+			AUCKLAND,
+			Intl.DateTimeFormat().resolvedOptions().timeZone,
+			"the case only proves anything while the ambient zone is a different one",
+		);
+	});
+
+	it("settles nothing when the mail already stated the clock", () => {
+		const added: string[] = [];
+		mount(stated, { onAdd: (timeZone) => added.push(timeZone) });
+
+		press(buttonNamed("Add"));
+
+		assert.deepEqual(added, [""]);
+		assert.equal(announced(), "");
+	});
+});
+
+/**
+ * Correcting the reading first is the other way the time leaves the card, and
+ * an editor seeded with the unconverted hour books the wrong one just as
+ * quietly as Add would.
+ */
+describe("the same gate on Change first", () => {
+	it("refuses Change first until a clock is picked, and says why", () => {
+		const reviewed: string[] = [];
+		mount(zoneless, { onReview: (timeZone) => reviewed.push(timeZone) });
+
+		const describes =
+			buttonNamed("Change first").getAttribute("aria-describedby");
+		assert.equal(
+			describes,
+			buttonNamed("Add").getAttribute("aria-describedby"),
+		);
+		assert.equal(
+			describes === null
+				? null
+				: dom.window.document.getElementById(describes)?.textContent,
+			ZONE_UNSETTLED_REASON,
+		);
+
+		press(buttonNamed("Change first"));
+
+		assert.deepEqual(reviewed, []);
+		assert.match(announced(), /Pick a clock first/);
+	});
+
+	it("opens on the clock that was picked, never on an empty one", () => {
+		const reviewed: string[] = [];
+		mount(zoneless, { onReview: (timeZone) => reviewed.push(timeZone) });
+
+		press(buttonNamed("16:00 in Auckland"));
+		press(buttonNamed("Change first"));
+
+		assert.deepEqual(reviewed, [AUCKLAND]);
+	});
+
+	it("stays live when the mail already stated the clock", () => {
+		const reviewed: string[] = [];
+		mount(stated, { onReview: (timeZone) => reviewed.push(timeZone) });
+
+		press(buttonNamed("Change first"));
+
+		assert.deepEqual(reviewed, [""]);
+		assert.equal(
+			buttonNamed("Change first").getAttribute("aria-describedby"),
+			null,
+		);
+	});
+});
+
+describe("the clocks a suggestion offers", () => {
+	it("cannot be an empty list, which would ask with nothing to press", () => {
+		// @ts-expect-error
+		const none: ZoneOptions = [];
+		assert.equal(none.length, 0);
+	});
+
+	it("never asks the question without a clock to answer it with", () => {
+		mount(zoneless);
+		assert.ok(container.textContent?.includes("Which clock is this on?"));
+		assert.equal(container.querySelectorAll("[aria-pressed]").length, 2);
+
+		mount(stated);
+		assert.equal(
+			container.textContent?.includes("Which clock is this on?"),
+			false,
+		);
+		assert.equal(container.querySelectorAll("[aria-pressed]").length, 0);
+	});
+});
+
+/**
+ * The zones the machine might be in. The hour is what noon UTC reads as there,
+ * asserted so a Node that ignored the switch could not pass the body silently.
+ */
+const ZONES = [
+	{ name: "UTC", hourAtNoonUtc: 12 },
+	{ name: "Europe/Amsterdam", hourAtNoonUtc: 14 },
+	{ name: "Pacific/Kiritimati", hourAtNoonUtc: 2 },
+];
+
+function inEveryZone(body: () => void): void {
+	const before = process.env.TZ;
+	try {
+		for (const zone of ZONES) {
+			process.env.TZ = zone.name;
+			assert.equal(
+				new Date("2026-06-17T12:00:00Z").getHours(),
+				zone.hourAtNoonUtc,
+				`the machine never moved to ${zone.name}`,
+			);
+			body();
+		}
+	} finally {
+		if (before === undefined) delete process.env.TZ;
+		else process.env.TZ = before;
+	}
+}
+
+describe("settleZone", () => {
+	it("settles a suggestion that carries no clocks to answer", () => {
+		inEveryZone(() => {
+			assert.deepEqual(settleZone(stated, ""), { settled: true, timeZone: "" });
+		});
+	});
+
+	it("holds a suggestion whose clock nobody has picked", () => {
+		inEveryZone(() => {
+			assert.deepEqual(settleZone(zoneless, ""), {
+				settled: false,
+				reason: ZONE_UNSETTLED_REASON,
+			});
+		});
+	});
+
+	it("holds a choice that is not one of the clocks offered", () => {
+		inEveryZone(() => {
+			assert.deepEqual(settleZone(zoneless, "Europe/Amsterdam"), {
+				settled: false,
+				reason: ZONE_UNSETTLED_REASON,
+			});
+			assert.deepEqual(settleZone(zoneless, "UTC"), {
+				settled: false,
+				reason: ZONE_UNSETTLED_REASON,
+			});
+		});
+	});
+
+	it("carries the picked clock through untouched", () => {
+		inEveryZone(() => {
+			assert.deepEqual(settleZone(zoneless, LISBON), {
+				settled: true,
+				timeZone: LISBON,
+			});
+		});
+	});
+});

package/src/components/folder-tree-picker.tsx

@@ -102,6 +102,12 @@ export interface FolderTreePickerProps {
 	) => Promise<FolderTreeNode>;
 	/** Escape. The picker never owns its presentation, so it cannot close itself. */
 	onCancel?: () => void;
+	/**
+	 * Takes focus on mount. A picker that opens away from where it was triggered
+	 * — a portalled popover — leaves the keyboard behind on the trigger, so Tab
+	 * walks the surrounding toolbar instead of entering the tree.
+	 */
+	autoFocusFilter?: boolean;
 	/** The provider's hierarchy separator. */
 	delimiter?: string;
 	labels?: FolderTreePickerLabels;
@@ -147,6 +153,7 @@ export const FolderTreePicker = ({
 	onCancel,
 	delimiter = "/",
 	labels,
+	autoFocusFilter = false,
 }: FolderTreePickerProps) => {
 	const text = { ...defaultLabels, ...labels };
 	const [query, setQuery] = useState("");
@@ -163,10 +170,16 @@ export const FolderTreePicker = ({
 	const [focusedIndex, setFocusedIndex] = useState(-1);
 
 	const rowRefs = useRef<Array<HTMLButtonElement | null>>([]);
+	const filterRef = useRef<HTMLInputElement>(null);
 	const roving = useRef(false);
 	const createAbort = useRef<AbortController | null>(null);
 	useEffect(() => () => createAbort.current?.abort(), []);
 
+	useEffect(() => {
+		if (!autoFocusFilter) return;
+		filterRef.current?.focus();
+	}, [autoFocusFilter]);
+
 	const trimmedQuery = query.trim().toLowerCase();
 	const ordered = useMemo(
 		() => orderFolderNodes(folders, delimiter),
@@ -413,6 +426,7 @@ export const FolderTreePicker = ({
 	return (
 		<div className="flex min-h-0 w-full min-w-0 flex-col">
 			<Input
+				ref={filterRef}
 				variant="inline"
 				className="border-b border-line px-3 py-2"
 				icon={<Search className="size-4" aria-hidden="true" />}

package/src/components/popover-menu.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Mail, MailOpen, Tag } from "lucide-react";
-import { PopoverMenu } from "./popover-menu.js";
+import { useState } from "react";
+import { PopoverMenu, PopoverMenuRow } from "./popover-menu.js";
 
 const meta: Meta<typeof PopoverMenu> = {
 	title: "Kit/PopoverMenu",
@@ -78,6 +79,50 @@ export const ManyItems: Story = {
 	},
 };
 
+function GrowingMenu() {
+	const [rows, setRows] = useState(2);
+	return (
+		<div className="flex h-screen items-end justify-end p-4">
+			<PopoverMenu
+				triggerLabel="More actions"
+				items={Array.from({ length: rows }, (_, i) => ({
+					key: `label-${i}`,
+					label: `Label ${i + 1}`,
+					icon: <Tag className="size-4" />,
+					onSelect: () => undefined,
+				}))}
+			>
+				<PopoverMenuRow
+					label="Show more"
+					onSelect={() => setRows((current) => current + 10)}
+				/>
+			</PopoverMenu>
+		</div>
+	);
+}
+
+/**
+ * A panel that grows after it has been placed — a list arriving from a fetch,
+ * a confirmation bar appearing on a pick. It stays anchored to its trigger as
+ * it grows, rather than keeping the position it was given at its opening size
+ * and running off the bottom of the screen.
+ */
+export const GrowsAfterOpening: Story = {
+	name: "Panel grows after it opens",
+	parameters: { layout: "fullscreen" },
+	render: () => <GrowingMenu />,
+	play: async ({ canvasElement }) => {
+		canvasElement
+			.querySelector<HTMLButtonElement>('[aria-label="More actions"]')
+			?.click();
+		await new Promise((resolve) => setTimeout(resolve, 60));
+		// The panel is portalled onto the body, so it is outside the canvas.
+		Array.from(document.body.querySelectorAll<HTMLButtonElement>("button"))
+			.find((button) => button.textContent?.trim() === "Show more")
+			?.click();
+	},
+};
+
 export const WithNestedPicker: Story = {
 	args: {
 		triggerLabel: "More actions",

package/src/components/popover-menu.tsx

@@ -53,8 +53,11 @@ function clampToViewport(
 /**
  * Measures the anchor and the panel's own size, then keeps the panel's fixed
  * position clamped to the viewport for as long as it is open — reset on every
- * resize and on scroll anywhere in the ancestor chain, since a fixed position
- * does not follow a scrolled anchor on its own.
+ * resize, on scroll anywhere in the ancestor chain (a fixed position does not
+ * follow a scrolled anchor on its own), and whenever the panel's own box
+ * changes. A panel placed once at the size it opened with runs off the bottom
+ * as soon as its content arrives: a loading line gives way to a full list, a
+ * confirmation bar appears on a pick, a filter shrinks it back.
  */
 function useAnchoredPlacement(
 	panelRef: RefObject<HTMLElement | null>,
@@ -92,7 +95,14 @@ function useAnchoredPlacement(
 		place();
 		window.addEventListener("resize", place);
 		window.addEventListener("scroll", place, true);
+		const panel = panelRef.current;
+		let observer: ResizeObserver | null = null;
+		if (panel && typeof ResizeObserver !== "undefined") {
+			observer = new ResizeObserver(place);
+			observer.observe(panel);
+		}
 		return () => {
+			observer?.disconnect();
 			window.removeEventListener("resize", place);
 			window.removeEventListener("scroll", place, true);
 		};
@@ -116,6 +126,11 @@ export interface PopoverMenuPortalProps {
  * page — the compose body, a card, anything with its own `overflow` — no
  * matter how high its `z-index` climbs; escaping that ancestor takes leaving
  * its DOM subtree, which only a portal does.
+ *
+ * The wrapper carries the menu layer's own `z-50`: as a body child it would
+ * otherwise stack by document order alone and lose to every fixed surface
+ * already on the page. `z-[60]` stays above it, for confirmation dialogs and
+ * error banners that must cover an open menu.
  */
 export function PopoverMenuPortal({
 	open,
@@ -127,7 +142,10 @@ export function PopoverMenuPortal({
 	const style = useAnchoredPlacement(panelRef, open, align, getAnchor);
 	if (!open) return null;
 	return createPortal(
-		<div style={style ?? { position: "fixed", visibility: "hidden" }}>
+		<div
+			className="z-50"
+			style={style ?? { position: "fixed", visibility: "hidden" }}
+		>
 			{children}
 		</div>,
 		document.body,

package/src/index.ts

@@ -148,6 +148,8 @@ export {
 	type RecurrenceScope,
 	type RsvpState,
 	type ZoneCertainty,
+	type ZoneOption,
+	type ZoneOptions,
 } from "./components/calendar-types.js";
 export {
 	Card,
@@ -254,6 +256,9 @@ export {
 export {
 	EventSuggestionCard,
 	type EventSuggestionCardProps,
+	settleZone,
+	ZONE_UNSETTLED_REASON,
+	type ZoneSettlement,
 } from "./components/event-suggestion-card.js";
 export {
 	FieldLabel,
@@ -488,6 +493,7 @@ export {
 	type PopoverMenuItem,
 	PopoverMenuPanel,
 	type PopoverMenuPanelProps,
+	PopoverMenuPortal,
 	type PopoverMenuProps,
 	PopoverMenuRow,
 	type PopoverMenuRowProps,