@12-apps/discounts 1.12.0 → 1.13.0

package/src/react/schedule-copy.ts

@@ -0,0 +1,74 @@
+/**
+ * The weekly schedule editor and the sentence it reads back (FUT-996).
+ *
+ * The read-back is the highest-value thing on this screen — a grid of chips and
+ * two clocks is data, and "Toda sexta, das 16:00 às 20:00" is the promise the
+ * operator is actually making. It follows the free-units builder's rule: the
+ * sentence appears only once the values make a real offer, so it is never
+ * confirmation of something that cannot be saved.
+ *
+ * Day names are three separate records because Portuguese needs them to be.
+ * `dayShort` is a chip ("Seg"), `dayLong` is a list item ("segunda"), and
+ * `dayEvery` is a sentence opener whose article follows the day's GENDER
+ * ("Toda segunda", "Todo sábado"). Deriving the third from the second would
+ * mean encoding Portuguese grammar in a package that must not know which
+ * language it is rendering.
+ */
+export interface DiscountsScheduleCopy {
+  /** Section heading over the period and the repetition. */
+  readonly sectionTitle: string;
+  readonly periodTitle: string;
+  readonly periodHint: string;
+  readonly repetitionTitle: string;
+  /** The two repetition choices. */
+  readonly always: string;
+  readonly specific: string;
+  /** The builder. */
+  readonly builderTitle: string;
+  readonly addWindow: string;
+  readonly removeWindow: string;
+  readonly fromLabel: string;
+  readonly toLabel: string;
+  /** Preset buttons that write into the chips rather than replacing them. */
+  readonly presetEveryDay: string;
+  readonly presetWeekdays: string;
+  readonly presetWeekend: string;
+  /** Monday-first, 0..6. */
+  readonly dayShort: readonly string[];
+  readonly dayLong: readonly string[];
+  readonly dayEvery: readonly string[];
+  /** Joining a day list: "segunda, terça e quarta". */
+  readonly listSeparator: string;
+  readonly listLast: string;
+  /** Collapsed day sets, so a common week reads as a phrase not a list. */
+  readonly allDays: string;
+  readonly weekdays: string;
+  readonly weekend: string;
+  /** The read-back. `{days}`, `{from}`, `{to}`. */
+  readonly summary: string;
+  /** The same, when the window runs past midnight. */
+  readonly summaryOvernight: string;
+  /** Whose clock these times are in. `{timezone}`. */
+  readonly timezoneNote: string;
+  /**
+   * What the shopper is promised — stated where the merchant promises it.
+   * FUT-996 decision 2: the price follows the moment the item entered the cart.
+   */
+  readonly guaranteeNote: string;
+  /**
+   * The ORDER-scope asymmetry, shown ONLY for that combination because it is
+   * otherwise invisible: an order-wide rule has no line to anchor to, so it is
+   * judged at checkout while every other scope is judged per line.
+   */
+  readonly orderScopeNote: string;
+  /** Grid: the campaign window and the schedule in one cell. `{window}`, `{schedule}`. */
+  readonly windowWithSchedule: string;
+  /** Grid: a compact schedule, plus "+N" when there are more rows. `{count}`. */
+  readonly moreWindows: string;
+  /** Grid + card: this rule's hours are running at this moment. */
+  readonly activeNow: string;
+  /** Refusals. */
+  readonly daysRequired: string;
+  readonly timesRequired: string;
+  readonly windowsRequired: string;
+}

package/src/react/schedule-summary.ts

@@ -0,0 +1,100 @@
+import type { DiscountSchedule, DiscountScheduleWindow } from "../engine/schedule";
+import { toMinutes } from "../engine/schedule";
+
+import { fill, type DiscountsWebCopy } from "./copy";
+
+/**
+ * The read-back sentence: "Toda sexta, das 16:00 às 20:00." (FUT-996)
+ *
+ * The highest-value thing on the schedule editor. A row of day chips and two
+ * clocks is DATA; this is the promise the operator is actually making, in the
+ * words they would use to describe it out loud, and it is the only thing on the
+ * screen they can check against what they meant.
+ *
+ * It follows `summaryOf` in the free-units builder exactly: **nothing is
+ * rendered until the values make a real offer.** A sentence over a half-built
+ * window would read as confirmation of something the validator is about to
+ * refuse, which is worse than no sentence at all.
+ *
+ * Its own module because it is pure string assembly the builder, the grid cell
+ * and the card all want, and a copy of it in each is how three surfaces start
+ * describing one promotion three ways.
+ */
+
+const ALL_DAYS = [0, 1, 2, 3, 4, 5, 6];
+const WEEKDAYS = [0, 1, 2, 3, 4];
+const WEEKEND = [5, 6];
+
+function sameDays(days: readonly number[], expected: readonly number[]): boolean {
+  const unique = [...new Set(days)].sort((a, b) => a - b);
+  return unique.length === expected.length && unique.every((day, i) => day === expected[i]);
+}
+
+/**
+ * The day set as a phrase.
+ *
+ * Collapsed sets come first so a common week reads as a phrase rather than a
+ * list — "De segunda a sexta" beats "segunda, terça, quarta, quinta e sexta",
+ * which is the same fact spelled at four times the length.
+ *
+ * A SINGLE day uses the pack's `dayEvery` form ("Toda sexta", "Todo sábado")
+ * rather than the bare name, because that is how a merchant says it. The
+ * article follows the day's gender in Portuguese, which is why the pack carries
+ * all seven rather than the code prefixing a word.
+ */
+function formatDays(days: readonly number[], copy: DiscountsWebCopy): string | null {
+  const unique = [...new Set(days)].sort((a, b) => a - b);
+  if (unique.length === 0) return null;
+  if (unique.some((day) => day < 0 || day > 6)) return null;
+  const { schedule } = copy;
+  if (sameDays(unique, ALL_DAYS)) return schedule.allDays;
+  if (sameDays(unique, WEEKDAYS)) return schedule.weekdays;
+  if (sameDays(unique, WEEKEND)) return schedule.weekend;
+  if (unique.length === 1) return schedule.dayEvery[unique[0] as number] ?? null;
+  const names = unique.map((day) => schedule.dayLong[day] ?? String(day));
+  const last = names[names.length - 1] as string;
+  return names.slice(0, -1).join(schedule.listSeparator) + schedule.listLast + last;
+}
+
+/**
+ * One window as a sentence, or null when it is not yet an offer.
+ *
+ * An overnight window gets its OWN sentence rather than the same one, because
+ * "das 22:00 às 02:00" is ambiguous on a screen and unambiguous only once it
+ * says which day the 02:00 belongs to. An operator who typed it by mistake sees
+ * it; one who meant it gets confirmation.
+ */
+export function formatScheduleWindow(
+  window: DiscountScheduleWindow,
+  copy: DiscountsWebCopy,
+): string | null {
+  const days = formatDays(window.days, copy);
+  const from = toMinutes(window.from);
+  const to = toMinutes(window.to);
+  if (days === null || from === null || to === null || from === to) return null;
+  const template = to < from ? copy.schedule.summaryOvernight : copy.schedule.summary;
+  return fill(template, { days, from: window.from, to: window.to });
+}
+
+/**
+ * The COMPACT form for a grid cell: "sex 16:00–20:00", plus "+N" when the rule
+ * has more windows than the column can show.
+ *
+ * Short day names rather than the sentence, because a table cell is read in a
+ * column of forty and the sentence is read once, deliberately, in a form.
+ */
+export function formatScheduleCell(
+  schedule: DiscountSchedule | null | undefined,
+  copy: DiscountsWebCopy,
+): string | null {
+  if (schedule === null || schedule === undefined) return null;
+  const [first, ...rest] = schedule.windows;
+  if (first === undefined) return null;
+  const days = [...new Set(first.days)]
+    .sort((a, b) => a - b)
+    .map((day) => copy.schedule.dayShort[day] ?? String(day))
+    .join(" ");
+  const head = `${days} ${first.from}–${first.to}`;
+  if (rest.length === 0) return head;
+  return `${head} ${fill(copy.schedule.moreWindows, { count: rest.length })}`;
+}

package/src/react/screen-bindings.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useServerDataViews } from "@12-apps/app-shell/react";
+
+import type { DiscountsPagination, WireTargetGroup } from "./api";
+import type { MenuBinding, DiscountsScreenProps } from "./discounts-screen";
+import { discountsQueryToParams } from "./table-config";
+
+/**
+ * The two bindings {@link DiscountsScreen} hands down — pagination and the row
+ * menu — lifted out of it.
+ *
+ * Neither is a second concern; they live here because that component is at both
+ * the size and the complexity ceilings, and these are the parts of it that are
+ * pure plumbing rather than layout.
+ */
+
+/**
+ * The grid's server-side pagination binding, with the defaults a page that has
+ * not loaded yet needs.
+ *
+ * Its own hook so the three `??` fallbacks are not branches inside
+ * {@link DiscountsScreen}, which sits at the complexity ceiling.
+ */
+export function usePagedServer(
+  pagination: DiscountsPagination | undefined,
+): ReturnType<typeof useServerDataViews> {
+  return useServerDataViews({
+    totalCount: pagination?.total ?? 0,
+    page: pagination?.page ?? 1,
+    pageSize: pagination?.pageSize ?? 20,
+    toParams: discountsQueryToParams,
+  });
+}
+
+/**
+ * The binding every row menu, tile and card receives — built once so an edit
+ * opened from any of the three offers the same pickers.
+ *
+ * A helper rather than an inline literal: the optional `timezoneLabel` is a
+ * conditional spread, and {@link DiscountsScreen} is at the complexity ceiling.
+ */
+export function toMenuBinding(
+  props: DiscountsScreenProps,
+  groups: readonly WireTargetGroup[] | undefined,
+): MenuBinding {
+  const { api, copy, formatters, currencyField, onError, timezoneLabel } = props;
+  return {
+    api,
+    copy,
+    formatters,
+    currencyField,
+    groups,
+    onError,
+    ...(timezoneLabel ? { timezoneLabel } : {}),
+  };
+}

package/src/react/table-config.ts

@@ -76,6 +76,21 @@ export function discountColumns(copy: DiscountsWebCopy): DataViewColumn<Discount
       searchable: true,
     },
     { id: "window", header: copy.screen.columns.window, accessor: (row) => row.windowLabel },
+    {
+      // The live answer to "is my happy hour on right now?" (FUT-996).
+      //
+      // Its own column rather than a widening of the vigência pill beside it:
+      // those three values are resolved by a store-side SQL predicate, and a
+      // recurrence predicate is not expressible there. This one is computed in
+      // the browser from the store's timezone, so it can be SHOWN but not
+      // FILTERED — and a cell is honest about that in a way a pill would not be.
+      //
+      // Blank, not "Não", for a rule with no schedule: there is nothing
+      // intermittent to report, and a column of "Não" would read as a fault.
+      id: "activeNow",
+      header: copy.schedule.activeNow,
+      accessor: (row) => (row.activeNow ? copy.schedule.activeNow : EMPTY),
+    },
     {
       id: "usageCount",
       header: copy.screen.columns.usageCount,

package/src/server/copy.ts

@@ -34,6 +34,8 @@ export interface DiscountsServerCopy {
   readonly invalidDate: string;
   /** 422 — the window closes at or before it opens, so it is never open. */
   readonly endsBeforeStarts: string;
+  /** The weekly schedule is not one the engine can act on (FUT-996). */
+  readonly invalidSchedule: string;
   /** 422 — a minimum-basket threshold of zero or less. */
   readonly invalidMinSubtotal: string;
   /** 422 — a global redemption cap of zero or less. */
@@ -79,6 +81,7 @@ const COPY_KEYS: readonly (keyof DiscountsServerCopy)[] = [
   "itemTargetRequired",
   "invalidDate",
   "endsBeforeStarts",
+  "invalidSchedule",
   "invalidMinSubtotal",
   "invalidUsageLimit",
   "invalidPerBuyerLimit",

package/src/server/en-US.ts

@@ -23,6 +23,7 @@ export const EN_US_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
   // would send an operator to type something the endpoint rejects.
   invalidDate: "Invalid date. Use the format YYYY-MM-DD.",
   endsBeforeStarts: "The end date must be after the start date.",
+  invalidSchedule: "Invalid promotion schedule. Pick at least one day, and a start and end time that differ.",
   invalidMinSubtotal: "The minimum order must be greater than zero (or left blank).",
   invalidUsageLimit: "The usage limit must be greater than zero (or left blank).",
   invalidPerBuyerLimit: "The per-customer limit must be greater than zero (or left blank).",

package/src/server/mcp.ts

@@ -17,6 +17,7 @@ import {
   MAX_COMBO_SLOT_QUANTITY,
   MAX_PERCENT_OFF_BP,
 } from "../engine/kinds";
+import { MAX_SCHEDULE_WINDOWS } from "../engine/schedule";
 import { discountSearchConfig } from "./search";
 
 /**
@@ -66,6 +67,35 @@ export const comboRequirementSchema = z.object({
   quantity: z.number().int().min(1).max(MAX_COMBO_SLOT_QUANTITY),
 });
 
+/**
+ * A `HH:MM` clock time, 24-hour — the schedule's own wire format (FUT-996).
+ *
+ * A string rather than minutes-since-midnight because it is what an operator
+ * typed and what a card reads back; converting at the edge would mean two
+ * representations of one fact and a conversion to get wrong in each direction.
+ */
+const clockTimeSchema = z
+  .string()
+  .regex(/^([01]\d|2[0-3]):[0-5]\d$/, "Use HH:MM, 24-hour");
+
+/**
+ * One "these days, these hours" row. `days` is **Monday-first, 0..6** — the
+ * same axis every hours surface uses, and NOT `Date#getDay()`'s Sunday-first.
+ *
+ * `to` earlier than `from` is legal and means the window runs past midnight: a
+ * bar shutting at 02:00 is the most common happy hour there is.
+ */
+const scheduleWindowSchema = z.object({
+  days: z.array(z.number().int().min(0).max(6)).min(1).max(7),
+  from: clockTimeSchema,
+  to: clockTimeSchema,
+});
+
+/** The weekly schedule. Null = always, within the campaign window. */
+const discountScheduleSchema = z.object({
+  windows: z.array(scheduleWindowSchema).min(1).max(MAX_SCHEDULE_WINDOWS),
+});
+
 /**
  * A discount as the API returns it (JSON-serialized: dates become ISO
  * strings). The two join tables are flattened into id arrays.
@@ -93,6 +123,7 @@ export const discountSchema = z.object({
   code: z.string().nullable(),
   startsAt: z.string().nullable(),
   endsAt: z.string().nullable(),
+  schedule: discountScheduleSchema.nullable().optional(),
   minSubtotalCents: z.number().int().nullable(),
   usageLimit: z.number().int().nullable(),
   perBuyerLimit: z.number().int().nullable(),
@@ -150,6 +181,7 @@ const discountWriteShape = {
   code: z.string().min(1).max(64).nullable().optional(),
   startsAt: calendarDateSchema.nullable().optional(),
   endsAt: calendarDateSchema.nullable().optional(),
+  schedule: discountScheduleSchema.nullable().optional(),
   minSubtotalCents: z.number().int().positive().nullable().optional(),
   usageLimit: z.number().int().positive().nullable().optional(),
   perBuyerLimit: z.number().int().positive().nullable().optional(),

package/src/server/pt-BR.ts

@@ -20,6 +20,7 @@ export const PT_BR_DISCOUNTS_SERVER_COPY: DiscountsServerCopy = {
   itemTargetRequired: "Selecione ao menos um produto para este desconto.",
   invalidDate: "Data inválida. Use o formato AAAA-MM-DD.",
   endsBeforeStarts: "A data de término deve ser posterior à data de início.",
+  invalidSchedule: "Horários da promoção inválidos. Escolha ao menos um dia e um horário de início e fim diferentes.",
   invalidMinSubtotal: "O pedido mínimo deve ser maior que zero (ou deixe em branco).",
   invalidUsageLimit: "O limite de usos deve ser maior que zero (ou deixe em branco).",
   invalidPerBuyerLimit: "O limite por cliente deve ser maior que zero (ou deixe em branco).",

package/src/server/store.ts

@@ -1,6 +1,7 @@
 import type { PaginatedResult, ParsedSearchInput } from "@12-apps/shared-helpers/search";
 
 import type { DiscountScope, DiscountTrigger, DiscountType } from "../engine/kinds";
+import type { DiscountSchedule } from "../engine/schedule";
 import type { ComboRequirement } from "../engine/types";
 import type { DiscountScalars, DiscountTargets } from "./validate";
 
@@ -33,6 +34,13 @@ export interface DiscountRecord {
   code: string | null;
   startsAt: Date | null;
   endsAt: Date | null;
+  /**
+   * The WEEKLY schedule (FUT-996), OPTIONAL for the reason the combo columns
+   * below are: a host that has not added the column keeps compiling and keeps
+   * answering the record it always did. Null or absent = always, within the
+   * campaign window.
+   */
+  schedule?: DiscountSchedule | null;
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;

package/src/server/validate.ts

@@ -5,6 +5,7 @@ import {
   type DiscountTrigger,
   type DiscountType,
 } from "../engine/kinds";
+import { isUsableSchedule, type DiscountSchedule } from "../engine/schedule";
 import type { ComboRequirement } from "../engine/types";
 import type { DiscountsServerCopy } from "./copy";
 import { comboRequirementsForScope, toComboColumns } from "./validate-combo";
@@ -50,6 +51,15 @@ export interface DiscountWriteInput {
   /** Calendar dates (`YYYY-MM-DD`) as the form sends them, or null. */
   startsAt: string | null;
   endsAt: string | null;
+  /**
+   * The WEEKLY schedule inside that window (FUT-996), or null for "always".
+   * Validated here rather than trusted: it is stored as JSON, so the database
+   * cannot check its shape and this is the only gate in front of it.
+   *
+   * Optional so a caller assembling a write input by hand — a test, a script,
+   * an older adopter — does not have to name a field it has no opinion about.
+   */
+  schedule?: DiscountSchedule | null;
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
@@ -168,6 +178,32 @@ function assertWindow(
   return { startsAt, endsAt };
 }
 
+/**
+ * The weekly schedule, or null (FUT-996).
+ *
+ * Every failure here is ONE message rather than a per-window field error,
+ * because the operator does not edit this as fields: they edit a row of day
+ * chips and two clocks, and "a linha 2 não tem dias" points at something the
+ * form can highlight while `schedule.windows[1].days` does not.
+ *
+ * A `to` earlier than `from` is NOT an error — it is a bar shutting at 02:00,
+ * which is the most common happy hour there is. The only refusals are the ones
+ * that cannot mean anything: no windows at all, a row naming no day, a day off
+ * the Monday-first axis, a malformed clock, and a zero-length window.
+ */
+function assertSchedule(
+  input: DiscountWriteInput,
+  copy: DiscountsServerCopy,
+): DiscountSchedule | null {
+  const { schedule } = input;
+  // `== null` catches BOTH, deliberately: the field is required on the type,
+  // but a caller assembling a write input by hand omits what it does not use,
+  // and "absent" and "explicitly none" are the same promotion.
+  if (schedule == null) return null;
+  if (!isUsableSchedule(schedule)) throw invalid("schedule", copy.invalidSchedule);
+  return { windows: schedule.windows.map((w) => ({ days: [...w.days], from: w.from, to: w.to })) };
+}
+
 /** A cap of zero is not a cap, it is a discount that can never be used. */
 function assertPositiveOrNull(value: number | null, field: string, message: string): void {
   if (value === null) return;
@@ -194,6 +230,8 @@ export interface DiscountScalars {
   code: string | null;
   startsAt: Date | null;
   endsAt: Date | null;
+  /** The weekly schedule, or null. Persisted as a JSON column. */
+  schedule: DiscountSchedule | null;
   minSubtotalCents: number | null;
   usageLimit: number | null;
   perBuyerLimit: number | null;
@@ -233,6 +271,7 @@ export function toDiscountScalars(
   const code = assertTrigger(input, copy);
   assertTargets(input, copy);
   const { startsAt, endsAt } = assertWindow(input, copy);
+  const schedule = assertSchedule(input, copy);
   assertLimits(input, copy);
   const combo = toComboColumns(input, copy);
 
@@ -249,6 +288,7 @@ export function toDiscountScalars(
     code,
     startsAt,
     endsAt,
+    schedule,
     minSubtotalCents: input.minSubtotalCents,
     usageLimit: input.usageLimit,
     perBuyerLimit: input.perBuyerLimit,
@@ -277,6 +317,8 @@ export interface DiscountWriteBody {
   code?: string | null;
   startsAt?: string | null;
   endsAt?: string | null;
+  /** The weekly schedule, or null/omitted for "always" (FUT-996). */
+  schedule?: DiscountSchedule | null;
   minSubtotalCents?: number | null;
   usageLimit?: number | null;
   perBuyerLimit?: number | null;
@@ -311,6 +353,7 @@ export function toDiscountWriteInput(body: DiscountWriteBody): DiscountWriteInpu
     code: orNull(body.code),
     startsAt: orNull(body.startsAt),
     endsAt: orNull(body.endsAt),
+    schedule: orNull(body.schedule),
     minSubtotalCents: orNull(body.minSubtotalCents),
     usageLimit: orNull(body.usageLimit),
     perBuyerLimit: orNull(body.perBuyerLimit),

package/src/timezone.ts

@@ -0,0 +1,96 @@
+import type { LocalClock } from "./engine/schedule";
+
+/**
+ * Resolve an instant into a store's own wall clock (FUT-996).
+ *
+ * Deliberately NOT part of the engine, and exported from its own subpath rather
+ * than the root. The engine's contract is that it reaches no clock and no
+ * locale data — it runs in an offline tool generator, a browser bundle and a
+ * worker — and this function reads `Intl`, which is exactly the dependency that
+ * contract exists to keep out. Everything here produces the two integers the
+ * engine consumes; nothing here decides anything about a discount.
+ *
+ * It lives in the PACKAGE rather than in each host because there must be one
+ * implementation. The admin grid's "ativa agora" dot runs in a browser, the
+ * price a shopper is charged is computed on a server, and a second copy of
+ * "which weekday is it in São Paulo at 23:50" is how those two start
+ * disagreeing about the same minute — silently, and only for the hour that
+ * matters.
+ */
+
+/**
+ * `Intl` reports a Sunday-first weekday; the schedule axis is Monday-first, the
+ * same one `WeekHours` and every hours screen uses. This table is the whole
+ * conversion, written as data so it cannot be got subtly wrong by arithmetic.
+ */
+const MONDAY_FIRST: Readonly<Record<string, number>> = {
+  Mon: 0,
+  Tue: 1,
+  Wed: 2,
+  Thu: 3,
+  Fri: 4,
+  Sat: 5,
+  Sun: 6,
+};
+
+/**
+ * The store's weekday and minute-of-day at `instant`, or null when the zone is
+ * not one this runtime knows.
+ *
+ * NULL rather than a fallback, and the CALLER decides what that means — which
+ * is the only honest split, because the two callers need opposite things. A
+ * cart must keep pricing (a scheduled rule fires; see `scheduleCovers`), and a
+ * teaser must stay quiet rather than promise an hour it cannot name. A default
+ * chosen here would silently impose one of those on both.
+ */
+export function resolveLocalClock(instant: Date, timeZone: string): LocalClock | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      weekday: "short",
+      hour: "2-digit",
+      minute: "2-digit",
+      hour12: false,
+    }).formatToParts(instant);
+    const read = (type: string): string =>
+      parts.find((part) => part.type === type)?.value ?? "";
+    const weekday = MONDAY_FIRST[read("weekday")];
+    const hour = Number(read("hour"));
+    const minute = Number(read("minute"));
+    if (weekday === undefined || !Number.isFinite(hour) || !Number.isFinite(minute)) return null;
+    // `hour12: false` yields 24 for midnight in some ICU versions — a real,
+    // once-a-day discrepancy that would put every midnight instant outside
+    // every window.
+    return { weekday, minutes: (hour % 24) * 60 + minute };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The zone as a PERSON would read it, in their own language — "Horário Padrão
+ * de Brasília", "Brasilia Standard Time".
+ *
+ * Derived rather than configured, and that is the point: a host passing a
+ * display name would be passing COPY, which this repo's own rules say must
+ * ship bilingual. `Intl` already knows every zone's name in every locale, so
+ * asking it is both less to maintain and correct in languages nobody here
+ * speaks.
+ *
+ * Falls back to the IANA id with its separators softened ("America/Sao_Paulo"
+ * → "Sao Paulo"), which is wrong-looking but never blank — a caption is not
+ * worth an exception for.
+ */
+export function timeZoneLabel(timeZone: string, locale: string): string {
+  try {
+    const parts = new Intl.DateTimeFormat(locale, {
+      timeZone,
+      timeZoneName: "longGeneric",
+    }).formatToParts(new Date());
+    const name = parts.find((part) => part.type === "timeZoneName")?.value;
+    if (name !== undefined && name !== "") return name;
+  } catch {
+    // fall through
+  }
+  return (timeZone.split("/").pop() ?? timeZone).replace(/_/g, " ");
+}