Make the admin timezone an explicit manual picker (task ade35bd5)

Replace the free-text Timezone box with a select of curated IANA zones,
an "API host local time" choice that clears the zone, and an "Other IANA
zone…" choice that opens a text entry for any other zone. A saved zone
outside the list opens in that entry on load. Helper text states this is
the application timezone and the source of local time for the panel,
scheduler and admin app. Saving still patches only changed fields, so a
timezone change sends exactly {"timezone": ...}; nothing is written on
load and the browser zone is never read.

API tests add invalid-zone 422 cases, a non-admin timezone PATCH refusal,
and a lone timezone PATCH sticking on a fresh database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

admin/src/settings/SettingsScreen.css

@@ -258,6 +258,12 @@
   color: var(--nq-a-ink-secondary);
 }
 
+.settings-hint {
+  margin: 0;
+  font-size: 12.5px;
+  color: var(--nq-a-ink-secondary);
+}
+
 .settings-input {
   width: 100%;
   min-height: var(--nq-a-tap-min);

admin/src/settings/SettingsScreen.test.tsx

@@ -499,37 +499,37 @@ describe("SettingsScreen — preferences", () => {
     expect(writes()).toHaveLength(1);
   });
 
-  it("a changed timezone patches exactly the timezone", async () => {
+  it("a timezone picked from the list patches exactly the timezone", async () => {
     const { form } = await renderPreferences();
-    const input = field(form, "Timezone");
+    fireEvent.change(field(form, "Timezone"), { target: { value: "America/New_York" } });
-    expect(input.getAttribute("list")).toBe("settings-timezones");
-    fireEvent.change(input, { target: { value: " Europe/London " } });
     save(form);
     await screen.findByText("Preferences saved.");
     expect(writes()).toEqual([
-      { method: "PATCH", path: SETTINGS_PATH, body: { timezone: "Europe/London" } },
+      { method: "PATCH", path: SETTINGS_PATH, body: { timezone: "America/New_York" } },
     ]);
     const reloaded = screen.getByRole("form", { name: "Preferences" });
-    expect(field(reloaded, "Timezone").value).toBe("Europe/London");
+    expect(field(reloaded, "Timezone").value).toBe("America/New_York");
   });
 
   it.each(["New York", "America/New York", "EST5EDT?", "/Chicago"])(
-    "an invalid timezone %j is rejected before any request",
+    "an invalid other timezone %j is rejected before any request",
     async (value) => {
       const { form } = await renderPreferences();
-      fireEvent.change(field(form, "Timezone"), { target: { value } });
+      fireEvent.change(field(form, "Timezone"), { target: { value: "__other__" } });
+      fireEvent.change(field(form, "Other timezone"), { target: { value } });
       save(form);
       expect(screen.getByTestId("preferences-message").textContent).toBe(
         "Timezone must be an IANA zone like America/New_York, or UTC.",
       );
-      expect(field(form, "Timezone").value).toBe(value);
+      expect(field(form, "Other timezone").value).toBe(value);
       expect(writes()).toEqual([]);
     },
   );
 
   it("a 422 on an unknown timezone shows the API detail and keeps the edit", async () => {
     const { form } = await renderPreferences();
-    fireEvent.change(field(form, "Timezone"), { target: { value: "Mars/Olympus_Mons" } });
+    fireEvent.change(field(form, "Timezone"), { target: { value: "__other__" } });
+    fireEvent.change(field(form, "Other timezone"), { target: { value: "Mars/Olympus_Mons" } });
     writeResponse = () =>
       jsonResponse({ detail: "timezone must be an IANA time zone name such as 'America/New_York'" }, 422);
     save(form);
@@ -537,8 +537,9 @@ describe("SettingsScreen — preferences", () => {
     expect(message.textContent).toBe(
       "The preferences could not be saved: timezone must be an IANA time zone name such as 'America/New_York'",
     );
-    expect(field(form, "Timezone").value).toBe("Mars/Olympus_Mons");
+    expect(field(form, "Other timezone").value).toBe("Mars/Olympus_Mons");
-    expect(field(form, "Timezone").disabled).toBe(false);
+    expect(field(form, "Other timezone").disabled).toBe(false);
+    expect(settings.timezone).toBe("America/Chicago");
   });
 
   it("a failed load shows the reason and Try again refetches", async () => {
@@ -643,3 +644,150 @@ describe("SettingsScreen — no timezone auto-set", () => {
     expect(field(screen.getByRole("form", { name: "Preferences" }), "Timezone").value).toBe("");
   });
 });
+
+describe("SettingsScreen — manual timezone control", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    children = [child(1, "Declan", 1)];
+    settings = { ...DEFAULT_SETTINGS, timezone: "" };
+    writeResponse = null;
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  async function renderForm() {
+    render(<SettingsScreen onClose={vi.fn()} />);
+    await screen.findByTestId("settings-child-1");
+    return screen.findByRole("form", { name: "Preferences" });
+  }
+
+  function save(form: HTMLElement) {
+    fireEvent.click(within(form).getByRole("button", { name: "Save preferences" }));
+  }
+
+  /** The Timezone control, which must be a real select, not a free-text box. */
+  function picker(form: HTMLElement): HTMLSelectElement {
+    const control = within(form).getByRole("combobox", { name: "Timezone" });
+    expect(control).toBeInstanceOf(HTMLSelectElement);
+    return control as HTMLSelectElement;
+  }
+
+  it("is a picker of curated zones with host-local and other-zone choices", async () => {
+    const form = await renderForm();
+    const select = picker(form);
+    const values = Array.from(select.options).map((o) => o.value);
+    expect(values[0]).toBe("");
+    expect(select.options[0].textContent).toBe("API host local time (no zone set)");
+    for (const zone of [
+      "UTC",
+      "America/New_York",
+      "America/Chicago",
+      "America/Denver",
+      "America/Phoenix",
+      "America/Los_Angeles",
+      "America/Anchorage",
+      "Pacific/Honolulu",
+    ]) {
+      expect(values).toContain(zone);
+    }
+    expect(select.options[select.options.length - 1].textContent).toBe("Other IANA zone…");
+    expect(select.value).toBe("");
+    expect(within(form).queryByLabelText("Other timezone")).toBeNull();
+  });
+
+  it("explains that it is the application timezone for every surface", async () => {
+    const form = await renderForm();
+    const help = document.getElementById(picker(form).getAttribute("aria-describedby") ?? "");
+    expect(help?.textContent).toMatch(/application timezone/);
+    expect(help?.textContent).toMatch(/panel, the scheduler and this admin app/);
+    expect(help?.textContent).toMatch(/API host's local time/);
+  });
+
+  it("a picked zone saves via PATCH and is shown after a reload", async () => {
+    const form = await renderForm();
+    expect(writes()).toEqual([]);
+    fireEvent.change(picker(form), { target: { value: "America/New_York" } });
+    save(form);
+    await screen.findByText("Preferences saved.");
+    expect(writes()).toEqual([
+      { method: "PATCH", path: SETTINGS_PATH, body: { timezone: "America/New_York" } },
+    ]);
+    cleanup();
+    const reloaded = await renderForm();
+    expect(picker(reloaded).value).toBe("America/New_York");
+    expect(writes()).toHaveLength(1);
+  });
+
+  it("an other zone typed by hand saves via PATCH and is shown after a reload", async () => {
+    const form = await renderForm();
+    fireEvent.change(picker(form), { target: { value: "__other__" } });
+    const entry = within(form).getByLabelText("Other timezone") as HTMLInputElement;
+    expect(entry.value).toBe("");
+    fireEvent.change(entry, { target: { value: " America/Boise " } });
+    save(form);
+    await screen.findByText("Preferences saved.");
+    expect(writes()).toEqual([
+      { method: "PATCH", path: SETTINGS_PATH, body: { timezone: "America/Boise" } },
+    ]);
+    cleanup();
+    const reloaded = await renderForm();
+    expect(picker(reloaded).value).toBe("__other__");
+    expect((within(reloaded).getByLabelText("Other timezone") as HTMLInputElement).value).toBe(
+      "America/Boise",
+    );
+  });
+
+  it("a saved zone outside the list is shown in the other-zone entry on load", async () => {
+    settings = { ...DEFAULT_SETTINGS, timezone: "Asia/Kathmandu" };
+    const form = await renderForm();
+    expect(picker(form).value).toBe("__other__");
+    expect((within(form).getByLabelText("Other timezone") as HTMLInputElement).value).toBe(
+      "Asia/Kathmandu",
+    );
+    expect(writes()).toEqual([]);
+  });
+
+  it("choosing API host local time clears the zone and persists after a reload", async () => {
+    settings = { ...DEFAULT_SETTINGS, timezone: "America/Denver" };
+    const form = await renderForm();
+    expect(picker(form).value).toBe("America/Denver");
+    fireEvent.change(picker(form), { target: { value: "" } });
+    save(form);
+    await screen.findByText("Preferences saved.");
+    expect(writes().map((w) => w.body)).toEqual([{ timezone: "" }]);
+    cleanup();
+    const reloaded = await renderForm();
+    expect(picker(reloaded).value).toBe("");
+  });
+
+  it("picking a zone and then the saved one again sends nothing", async () => {
+    settings = { ...DEFAULT_SETTINGS, timezone: "UTC" };
+    const form = await renderForm();
+    fireEvent.change(picker(form), { target: { value: "Europe/Paris" } });
+    fireEvent.change(picker(form), { target: { value: "UTC" } });
+    save(form);
+    expect(screen.getByTestId("preferences-message").textContent).toBe("No changes to save.");
+    expect(writes()).toEqual([]);
+  });
+
+  it("never sends a timezone_configured field", async () => {
+    const form = await renderForm();
+    fireEvent.change(picker(form), { target: { value: "America/Los_Angeles" } });
+    save(form);
+    await screen.findByText("Preferences saved.");
+    const again = screen.getByRole("form", { name: "Preferences" });
+    fireEvent.change(picker(again), { target: { value: "" } });
+    save(again);
+    await waitFor(() => expect(writes()).toHaveLength(2));
+    for (const write of writes()) {
+      expect(Object.keys(write.body as object)).toEqual(["timezone"]);
+      expect(write.body).not.toHaveProperty("timezone_configured");
+    }
+  });
+});

admin/src/settings/SettingsScreen.tsx

@@ -6,7 +6,8 @@
  *
  * Preferences: the household settings (planning horizon, day rollover,
  * timezone, notifications). Save patches only the changed fields. The
- * timezone is only ever set by the admin saving it here.
+ * timezone — the application's source of local time — is only ever set by
+ * the admin picking or typing a zone here and saving it.
  *
  * One write at a time across both sections.
  */
@@ -256,7 +257,7 @@ const HH_MM = /^([01]\d|2[0-3]):[0-5]\d$/;
 /** "UTC" or an IANA-looking "Area/Location" (the API checks it resolves). */
 const IANA_ZONE = /^(UTC|[A-Za-z]+(\/[A-Za-z0-9_+-]+)+)$/;
 
-/** The Timezone field's suggestions; any other IANA zone can be typed. */
+/** The Timezone picker's zones; any other IANA zone can be typed via "Other". */
 export const COMMON_TIMEZONES = [
   "UTC",
   "America/New_York",
@@ -290,6 +291,9 @@ export const COMMON_TIMEZONES = [
   "Pacific/Auckland",
 ];
 
+/** The picker's "Other IANA zone…" option; never sent to the API. */
+const OTHER_ZONE = "__other__";
+
 /** The form's working copy: the number is text so it can be mid-edit. */
 type PreferencesDraft = Omit<HouseholdSettings, "horizon_days"> & { horizon_days: string };
 
@@ -348,6 +352,10 @@ function PreferencesForm({
 }) {
   const [draft, setDraft] = useState<PreferencesDraft>(() => preferencesDraft(settings));
   const update = (patch: Partial<PreferencesDraft>) => setDraft((d) => ({ ...d, ...patch }));
+  // A saved zone outside the curated list opens in the free-text entry.
+  const [otherZone, setOtherZone] = useState(
+    () => settings.timezone !== "" && !COMMON_TIMEZONES.includes(settings.timezone),
+  );
   const disabled = saving || locked;
 
   function submit(event: FormEvent) {
@@ -400,25 +408,49 @@ function PreferencesForm({
         />
       </label>
       {timeInput("day_rollover_time", "Day rollover")}
-      <label className="settings-field">
+      <div className="settings-field">
-        <span className="settings-label">Timezone</span>
+        <label className="settings-label" htmlFor="settings-timezone">
-        <input
+          Timezone
+        </label>
+        <select
+          id="settings-timezone"
           className="settings-input"
-          type="text"
+          aria-describedby="settings-timezone-help"
-          list="settings-timezones"
+          value={otherZone ? OTHER_ZONE : draft.timezone}
-          placeholder="Host local time"
-          autoComplete="off"
-          spellCheck={false}
-          value={draft.timezone}
           disabled={disabled}
-          onChange={(event) => update({ timezone: event.target.value })}
+          onChange={(event) => {
-        />
+            const choice = event.target.value;
-      </label>
+            setOtherZone(choice === OTHER_ZONE);
-      <datalist id="settings-timezones">
+            if (choice !== OTHER_ZONE) update({ timezone: choice });
-        {COMMON_TIMEZONES.map((zone) => (
+          }}
-          <option key={zone} value={zone} />
+        >
-        ))}
+          <option value="">API host local time (no zone set)</option>
-      </datalist>
+          {COMMON_TIMEZONES.map((zone) => (
+            <option key={zone} value={zone}>
+              {zone}
+            </option>
+          ))}
+          <option value={OTHER_ZONE}>Other IANA zone…</option>
+        </select>
+        {otherZone ? (
+          <input
+            className="settings-input"
+            type="text"
+            aria-label="Other timezone"
+            placeholder="Area/Location, e.g. America/Boise"
+            autoComplete="off"
+            spellCheck={false}
+            value={draft.timezone}
+            disabled={disabled}
+            onChange={(event) => update({ timezone: event.target.value })}
+          />
+        ) : null}
+        <p className="settings-hint" id="settings-timezone-help">
+          The application timezone: the source of local time for the panel, the scheduler and this
+          admin app. It changes only when you save it here; with no zone set, the API host&apos;s
+          local time is used.
+        </p>
+      </div>
       <label className="settings-field">
         <span className="settings-label">Notify target</span>
         <input

tests/test_api_admin_settings.py

@@ -270,6 +270,24 @@ async def test_manual_timezone_patch_persists_and_is_returned(
     assert "timezone_configured" not in stored
 
 
+@pytest.mark.parametrize("zone", ["America/Los_Angeles", ""])
+async def test_timezone_alone_sticks_on_a_fresh_database(
+    settings_client: SimpleNamespace, zone: str
+) -> None:
+    """A lone ``timezone`` PATCH needs no other field to persist."""
+    client = settings_client.client
+    patched = await client.patch(
+        "/api/v1/admin/settings",
+        json={"timezone": zone},
+        headers=_admin_headers(),
+    )
+    assert patched.status_code == 200
+    reread = await client.get(
+        "/api/v1/admin/settings", headers=_admin_headers()
+    )
+    assert reread.json() == {**DEFAULT_SETTINGS, "timezone": zone}
+
+
 async def test_timezone_configured_is_an_unknown_field(
     settings_client: SimpleNamespace,
 ) -> None:
@@ -320,6 +338,9 @@ async def test_stored_legacy_timezone_configured_key_is_ignored(
         ({"morning_summary_enabled": "yes"}, "morning_summary_enabled"),
         ({"celebration_enabled": 1}, "celebration_enabled"),
         ({"notify_target": 5}, "notify_target"),
+        ({"timezone": "Mars/Olympus_Mons"}, "timezone"),
+        ({"timezone": "America/New York"}, "timezone"),
+        ({"timezone": 5}, "timezone"),
     ],
 )
 async def test_invalid_value_is_rejected_and_stored_settings_unchanged(
@@ -474,6 +495,13 @@ async def test_settings_routes_refuse_non_admin_and_absent_credentials(
     )
     assert absent_patch.status_code == 401
 
+    forbidden_zone = await client.patch(
+        "/api/v1/admin/settings",
+        json={"timezone": "America/New_York"},
+        headers={"Authorization": f"Bearer {non_admin}"},
+    )
+    assert forbidden_zone.status_code == 403
+
     # No refused request changed anything: the settings are untouched.
     after = await client.get(
         "/api/v1/admin/settings", headers=_admin_headers()