gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/earnings/calendar.tsx

@@ -0,0 +1,338 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { CompanyLogoMark } from "../../../components/company-logo";
+import { PaneStatusBody } from "../../../components";
+import { ClippedText } from "../../../components/ui/display";
+import { FILL_REST } from "../../../components/ui/fill";
+import { afterLayout, revealInScrollBox } from "../../../components/ui/reveal-in-scroll-box";
+import { useDoubleClickActivation } from "../../../components/use-double-click-activation";
+import { useShortcut } from "../../../react/input";
+import { useRegisterPaneScrollBox } from "../../../state/pane-scroll-registry";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box, ScrollBox, Text, TextAttributes, type BoxRenderable, type ScrollBoxRenderable } from "../../../ui";
+import { isPlainKey } from "../../../utils/keyboard";
+import type { BoardReport } from "./board-model";
+import { calendarGroupKey, type CalendarDay, type CalendarGroup } from "./calendar-model";
+import { epsText, signedPercent, TIMING_LABEL } from "./format";
+
+/** Cells a logo and its ticker take side by side: a five-letter ticker and a cell between. A day fits as many as its width holds. */
+const CALENDAR_SLOT_CELLS = 6;
+/** Rows of logos a session shows before its last slot counts the rest. */
+export const CALENDAR_GROUP_ROWS = 5;
+/** The columns between two days. */
+const DAY_GAP_CELLS = 1;
+
+/** Logos per row in each day column of a calendar `width` cells wide. */
+export function calendarSlotsPerRow(width: number): number {
+  const day = Math.floor((Math.max(0, width - 2) - DAY_GAP_CELLS * 4) / 5);
+  return Math.max(1, Math.floor(day / CALENDAR_SLOT_CELLS));
+}
+
+/** One spot in the week: a day, a row of its logos, and a slot in that row. */
+interface Position { day: number; row: number; slot: number }
+
+/** A group's last slot when it has more reports than it draws: "+N more", which expands it. */
+interface MoreSlot { kind: "more"; key: string; day: CalendarDay; group: CalendarGroup }
+type Slot = BoardReport | MoreSlot;
+
+const isMore = (slot: Slot): slot is MoreSlot => "kind" in slot && slot.kind === "more";
+
+/** A group's logos as the rows it draws them in, its "+N more" slot last. */
+function groupRows(day: CalendarDay, group: CalendarGroup, perRow: number): Slot[][] {
+  const more: MoreSlot[] = group.more > 0
+    ? [{ kind: "more", key: `more:${calendarGroupKey(day.date, group.session)}`, day, group }]
+    : [];
+  return chunk<Slot>([...group.reports, ...more], perRow);
+}
+
+function chunk<T>(items: readonly T[], size: number): T[][] {
+  const rows: T[][] = [];
+  for (let index = 0; index < items.length; index += size) rows.push(items.slice(index, index + size));
+  return rows;
+}
+
+/**
+ * Where an arrow key moves from `from`: up and down by a row of the same
+ * day, left and right along the row and on into the next day at the same
+ * depth. Null when there is nowhere to go.
+ */
+export function moveInWeek<T>(grid: readonly (readonly (readonly T[])[])[], from: Position, direction: "up" | "down" | "left" | "right"): Position | null {
+  const rows = grid[from.day] ?? [];
+  if (direction === "up" || direction === "down") {
+    const row = from.row + (direction === "down" ? 1 : -1);
+    const target = rows[row];
+    return target ? { day: from.day, row, slot: Math.min(from.slot, target.length - 1) } : null;
+  }
+  const step = direction === "right" ? 1 : -1;
+  const slot = from.slot + step;
+  if (rows[from.row]?.[slot]) return { ...from, slot };
+  for (let day = from.day + step; day >= 0 && day < grid.length; day += step) {
+    const next = grid[day]!;
+    if (next.length === 0) continue;
+    const row = Math.min(from.row, next.length - 1);
+    return { day, row, slot: step > 0 ? 0 : next[row]!.length - 1 };
+  }
+  return null;
+}
+
+function locate(grid: readonly Slot[][][], key: string | null): Position | null {
+  if (!key) return null;
+  for (const [day, rows] of grid.entries()) {
+    for (const [row, reports] of rows.entries()) {
+      const slot = reports.findIndex((entry) => entry.key === key);
+      if (slot >= 0) return { day, row, slot };
+    }
+  }
+  return null;
+}
+
+/** What hovering a logo says: the company, when it reports and, once out, how it did. */
+function reportTitle(report: BoardReport): string {
+  const when = report.timing ? TIMING_LABEL[report.timing] : "time not set";
+  const figures = report.epsActual != null
+    ? `EPS ${epsText(report.epsActual)} vs ${epsText(report.epsEstimate)} est${report.epsSurprise != null ? `, ${signedPercent(report.epsSurprise)}` : ""}`
+    : report.epsEstimate != null ? `EPS est ${epsText(report.epsEstimate)}` : null;
+  return [`${report.symbol} · ${report.name}`, when, figures].filter(Boolean).join(" · ");
+}
+
+interface CalendarViewProps {
+  days: readonly CalendarDay[];
+  width: number;
+  focused: boolean;
+  /** A report's key, or the key of a "+N more" slot. */
+  selectedKey: string | null;
+  onSelect: (key: string) => void;
+  /** Enter, or a second click: the company's reports, as a table row opens them. */
+  onOpen: (report: BoardReport) => void;
+  /** A click on a "+N more" slot, or Enter on it: draw the whole group. */
+  onMore: (day: CalendarDay, group: CalendarGroup) => void;
+  /** The week is not read yet; `days` are empty until it is. */
+  loading?: boolean;
+  /** The week could not be read. */
+  error?: string | null;
+  emptyTitle: string;
+}
+
+/**
+ * ERN's week on the desktop and the web: a column per day, and in each the
+ * companies reporting before the open and after the close as their logos,
+ * largest first, each with its ticker under it. A reported company's ticker
+ * takes the colour of its surprise.
+ */
+export function EarningsCalendarView({
+  days, width, focused, selectedKey, onSelect, onOpen, onMore, loading = false, error = null, emptyTitle,
+}: CalendarViewProps) {
+  const colors = useThemeColors();
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  // The page keys scroll the week.
+  useRegisterPaneScrollBox(scrollRef, { enabled: true });
+  const tiles = useRef(new Map<string, BoxRenderable>());
+  const perRow = calendarSlotsPerRow(width);
+  // Each day's groups as rows of slots; the keys walk the day's rows, groups one after another.
+  const layout = useMemo(() => days.map((day) => day.groups.map((group) => groupRows(day, group, perRow))), [days, perRow]);
+  const grid = useMemo(() => layout.map((groups) => groups.flat()), [layout]);
+  const position = locate(grid, selectedKey);
+  const empty = days.every((day) => day.groups.length === 0);
+  const ready = !loading && !error;
+
+  // The cursor starts on the first company of the week.
+  useEffect(() => {
+    if (position || empty) return;
+    const first = grid.flat(2).find((slot) => !isMore(slot));
+    if (first) onSelect(first.key);
+  }, [empty, grid, onSelect, position]);
+
+  // Keeps the cursor in view, after a key moves it or a "+N more" slot draws the rest of its group.
+  useEffect(() => {
+    if (!selectedKey) return;
+    afterLayout(() => revealInScrollBox(scrollRef.current, tiles.current.get(selectedKey) ?? null));
+  }, [selectedKey]);
+  const tileRef = useCallback((key: string) => (node: BoxRenderable | null) => {
+    if (node) tiles.current.set(key, node);
+    else tiles.current.delete(key);
+  }, []);
+  const press = useDoubleClickActivation<BoardReport>({ onSelect: (report) => onSelect(report.key), onActivate: onOpen });
+
+  useShortcut((event) => {
+    if (!focused || !position) return;
+    const direction = isPlainKey(event, "down", "j") ? "down" : isPlainKey(event, "up", "k") ? "up"
+      : isPlainKey(event, "left") ? "left" : isPlainKey(event, "right") ? "right" : null;
+    if (direction) {
+      const next = moveInWeek(grid, position, direction);
+      event.preventDefault();
+      event.stopPropagation();
+      if (next) onSelect(grid[next.day]![next.row]![next.slot]!.key);
+      return;
+    }
+    if (isPlainKey(event, "return", "enter")) {
+      const slot = grid[position.day]?.[position.row]?.[position.slot];
+      if (!slot) return;
+      event.preventDefault();
+      event.stopPropagation();
+      if (isMore(slot)) onMore(slot.day, slot.group);
+      else onOpen(slot);
+    }
+  });
+
+  // The days are the week's columns, headed as a table's are: bold and dim on the panel, today bright.
+  const header = (
+    <Box
+      flexDirection="row"
+      paddingX={1}
+      columnGap={DAY_GAP_CELLS}
+      flexShrink={0}
+      alignItems="center"
+      backgroundColor={colors.panel}
+      style={HEADER_STYLE}
+      data-gloom-role="earnings-calendar-days"
+    >
+      {days.map((day) => (
+        <Box key={day.date} flexGrow={1} flexBasis={0} minWidth={0} flexDirection="row" columnGap={1} overflow="hidden">
+          <ClippedText
+            text={`${day.weekday} ${day.label}`}
+            width={20}
+            fg={day.today ? colors.textBright : colors.textDim}
+            attributes={TextAttributes.BOLD}
+          />
+          {/* A holiday says so, unless companies report on it anyway; no count before the week is read. */}
+          {day.closed && day.total === 0 ? <Text fg={colors.textMuted}>closed</Text>
+            : ready ? <Text fg={colors.textMuted}>{String(day.total)}</Text> : null}
+        </Box>
+      ))}
+    </Box>
+  );
+
+  return (
+    <Box flexDirection="column" {...FILL_REST}>
+      {header}
+      <PaneStatusBody loading={loading} error={error} empty={ready && empty} emptyTitle={emptyTitle} subject="the earnings calendar">
+        <ScrollBox ref={scrollRef} {...FILL_REST} scrollY focusable={false}>
+          <Box flexDirection="row" alignItems="flex-start" paddingX={1} columnGap={DAY_GAP_CELLS} data-gloom-role="earnings-calendar-week">
+            {days.map((day, dayIndex) => (
+              <Box
+                key={day.date}
+                flexGrow={1}
+                flexBasis={0}
+                minWidth={0}
+                flexDirection="column"
+                data-gloom-role="earnings-calendar-day"
+                data-date={day.date}
+              >
+                {day.groups.map((group, groupIndex) => (
+                  <Box key={group.session ?? "unset"} flexDirection="column" style={{ paddingTop: "var(--gloom-space-sm)" }}>
+                    <Box flexDirection="row" columnGap={1} height={1} overflow="hidden">
+                      <Text fg={colors.textBright} attributes={TextAttributes.BOLD}>{group.label}</Text>
+                      <Text fg={colors.textMuted}>{String(group.reports.length + group.more)}</Text>
+                    </Box>
+                    {layout[dayIndex]![groupIndex]!.map((slots, rowIndex) => (
+                      <Box key={rowIndex} flexDirection="row">
+                        {Array.from({ length: perRow }, (_, index) => {
+                          const slot = slots[index];
+                          // The last row's room past its logos.
+                          if (!slot) return <Box key={index} flexGrow={1} flexBasis={0} minWidth={0} />;
+                          if (isMore(slot)) {
+                            return (
+                              <MoreTile key={slot.key} count={group.more} selected={slot.key === selectedKey}
+                                onPress={() => onMore(day, group)} tileRef={tileRef(slot.key)} />
+                            );
+                          }
+                          return (
+                            <ReportTile
+                              key={slot.key}
+                              report={slot}
+                              selected={slot.key === selectedKey}
+                              onPress={(event) => press(slot.key, slot, event)}
+                              tileRef={tileRef(slot.key)}
+                            />
+                          );
+                        })}
+                      </Box>
+                    ))}
+                  </Box>
+                ))}
+              </Box>
+            ))}
+          </Box>
+        </ScrollBox>
+      </PaneStatusBody>
+    </Box>
+  );
+}
+
+/** A table header's height, the chrome row. */
+const HEADER_STYLE = { height: "var(--chrome-h)" } as const;
+const TILE_STYLE = {
+  padding: "var(--gloom-space-xs) 0",
+  borderRadius: "var(--gloom-radius-sm)",
+  rowGap: "var(--gloom-space-xs)",
+} as const;
+/** The logo of a calendar tile: a square near two cells tall, most of the slot's width. */
+const LOGO_STYLE = { width: "calc(var(--cell-h) * 1.75)", height: "calc(var(--cell-h) * 1.75)", flexShrink: 0 } as const;
+
+function ReportTile({ report, selected, onPress, tileRef }: {
+  report: BoardReport;
+  selected: boolean;
+  onPress: (event: { detail?: number }) => void;
+  tileRef: (node: BoxRenderable | null) => void;
+}) {
+  const colors = useThemeColors();
+  const surprise = report.epsSurprise;
+  const ink = selected ? colors.selectedText
+    : surprise == null || surprise === 0 ? colors.text : surprise > 0 ? colors.positive : colors.negative;
+  return (
+    <Box
+      ref={tileRef}
+      flexGrow={1}
+      flexBasis={0}
+      minWidth={0}
+      flexDirection="column"
+      alignItems="center"
+      backgroundColor={selected ? colors.selected : undefined}
+      hoverBackgroundColor={selected ? undefined : "var(--gloom-hover-fill)"}
+      onMouseDown={onPress}
+      title={reportTitle(report)}
+      data-gloom-interactive="true"
+      data-gloom-role="earnings-calendar-report"
+      data-selected={selected ? "true" : undefined}
+      data-symbol={report.symbol}
+      style={TILE_STYLE}
+    >
+      <Box style={LOGO_STYLE}>
+        <CompanyLogoMark symbol={report.symbol} name={report.name} size="lead" />
+      </Box>
+      <ClippedText text={report.symbol} width={CALENDAR_SLOT_CELLS - 1} fg={ink} attributes={TextAttributes.BOLD} />
+    </Box>
+  );
+}
+
+function MoreTile({ count, selected, onPress, tileRef }: {
+  count: number;
+  selected: boolean;
+  onPress: () => void;
+  tileRef: (node: BoxRenderable | null) => void;
+}) {
+  const colors = useThemeColors();
+  return (
+    <Box
+      ref={tileRef}
+      flexGrow={1}
+      flexBasis={0}
+      minWidth={0}
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      backgroundColor={selected ? colors.selected : undefined}
+      hoverBackgroundColor={selected ? undefined : "var(--gloom-hover-fill)"}
+      onMouseDown={onPress}
+      title={`Show the other ${count}`}
+      data-gloom-interactive="true"
+      data-gloom-role="earnings-calendar-more"
+      data-selected={selected ? "true" : undefined}
+      style={TILE_STYLE}
+    >
+      <Box style={LOGO_STYLE} alignItems="center" justifyContent="center">
+        <Text fg={selected ? colors.selectedText : colors.textDim} attributes={TextAttributes.BOLD}>{`+${count}`}</Text>
+      </Box>
+      <Text fg={selected ? colors.selectedText : colors.textMuted}>more</Text>
+    </Box>
+  );
+}

package/src/plugins/builtin/earnings/client.ts

@@ -59,7 +59,8 @@ function validateEarningsHistory(payload: EarningsHistoryPayload, symbol: string
 type CalendarClient = Pick<typeof apiClient, "getCloudEarningsCalendar">;
 type HistoryClient = Pick<typeof apiClient, "getCloudEarningsHistory">;
 
-const calendarKey = (query: EarningsCalendarQuery) =>
+/** Names a calendar query: the cache's key, and how the board tells one week's reports from another's. */
+export const earningsCalendarKey = (query: EarningsCalendarQuery) =>
   `${query.from}:${query.to}:${query.perDay ?? ""}:${[...(query.symbols ?? [])].sort().join(",")}`;
 
 export async function fetchEarningsCalendar(query: EarningsCalendarQuery, client: CalendarClient = apiClient) {
@@ -79,11 +80,11 @@ export async function fetchEarningsHistory(symbol: string, client: HistoryClient
 }
 
 export function cachedEarningsCalendar(query: EarningsCalendarQuery) {
-  return cachedCloudResource(calendarCache, calendarKey(query), validateEarningsCalendar);
+  return cachedCloudResource(calendarCache, earningsCalendarKey(query), validateEarningsCalendar);
 }
 
 export function loadEarningsBoard(query: EarningsCalendarQuery, force = false) {
-  return loadCloudResource(calendarCache, calendarKey(query), () => fetchEarningsCalendar(query),
+  return loadCloudResource(calendarCache, earningsCalendarKey(query), () => fetchEarningsCalendar(query),
     { force, validate: validateEarningsCalendar });
 }
 

package/src/plugins/builtin/earnings/headless.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import type { EarningsCalendarPayload, EarningsHistoryPayload } from "../../../api-client/earnings";
 import type {
   HeadlessPaneColumn,
@@ -8,7 +9,8 @@ import type {
   HeadlessRowsResult,
 } from "../../../types/plugin";
 import type { EarningsEvent } from "../../../types/data-provider";
-import { addDays, boardReport, fallbackReport, marketDays, MIN_AVERAGE_REPORTS, newYorkToday } from "./board-model";
+import { addDays, boardReport, fallbackReport, MIN_AVERAGE_REPORTS, newYorkToday } from "./board-model";
+import { BOARD_WEEKS, boardRangeDays, boardRangeLabel, isBoardWeek, requestedBoardRange, type BoardRange } from "./calendar-model";
 import { fetchEarningsCalendar, fetchEarningsHistory } from "./client";
 import { loadEarningsCalendar } from "./data/cache";
 import { epsText, impliedText, moneyText, moveSize, signedPercent, TIMING_LABEL } from "./format";
@@ -20,6 +22,8 @@ import { listingAbroadVenue } from "../../../utils/sec";
 import { findUsListingOfCompany } from "../../../tickers/us-listing";
 import { shortCompanyName } from "../../../tickers/company-name";
 import { REPORT_ROWS } from "../shared/headless-options";
+import { DATE_OPTION_EXAMPLES, isoDateOption } from "../../../utils/calendar-date";
+import type { HeadlessPaneOptionDef } from "../../../types/headless";
 
 const right = "right" as const;
 const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : null);
@@ -93,29 +97,35 @@ function boardTickerNotice(symbol: string, board: ReadonlyArray<{ symbol: string
   // The board lists US tickers; a listing named abroad is never one of them.
   const report = venue && !isUsListingExchange(venue) ? undefined : board.find((entry) => entry.symbol.toUpperCase() === bare);
   const where = report ? `${symbol} reports on ${report.date}` : `${symbol} is not on it`;
+  const days = from === to ? from : `${from} to ${to}`;
   return {
-    notice: `EVTS is the market's earnings board for ${from} to ${to}, not one company's: ${where}. For ${symbol}'s own report dates run \`gloomberb fn ERN ${symbol}\`.`,
+    notice: `EVTS is the market's earnings board for ${days}, not one company's: ${where}. For ${symbol}'s own report dates run \`gloom fn ERN ${symbol}\`.`,
     date: report?.date ?? null,
   };
 }
 
-async function boardRows(args: HeadlessPaneLoadArgs, context: HeadlessPaneContext, deps: EarningsHeadlessDependencies, highlight?: string): Promise<HeadlessRowsResult> {
+async function boardRows(args: HeadlessPaneLoadArgs, context: HeadlessPaneContext, deps: EarningsHeadlessDependencies, highlight?: string, range: BoardRange = ""): Promise<HeadlessRowsResult> {
   const today = newYorkToday();
   const named = args.symbols;
-  const days = marketDays(today);
-  const query = named.length
+  const days = boardRangeDays(range, today);
+  // Named companies' upcoming reports by default; a chosen week or day reads that range for them as for the market.
+  const query = named.length && !range
     ? { from: today, to: addDays(today, 90), perDay: 0, symbols: named }
-    : { from: days[0]!.from, to: days.at(-1)!.to, perDay: 200, symbols: [] };
+    : { from: days[0]!.from, to: days.at(-1)!.to, perDay: named.length ? 0 : 200, symbols: named };
+  const inRange = (event: EarningsEvent) => {
+    const date = event.earningsDate.toISOString().slice(0, 10);
+    return !range || (date >= query.from && date <= query.to);
+  };
   const [cloud, fallback] = await Promise.allSettled([
     deps.calendar(query, context),
-    named.length ? deps.upcoming(named, context) : Promise.resolve([]),
+    named.length ? deps.upcoming(named, context).then((events) => events.filter(inRange)) : Promise.resolve([]),
   ]);
   if (cloud.status === "rejected" && (!named.length || fallback.status === "rejected")) throw cloud.reason;
   const payload = cloud.status === "fulfilled" ? cloud.value : null;
   const reports = (payload?.reports ?? []).map((report) => boardReport(report, NO_OWNERSHIP));
   const covered = new Set(reports.map((report) => report.symbol));
   const extra = fallback.status === "fulfilled"
-    ? fallback.value.filter((event) => !covered.has(event.symbol)).map((event) => fallbackReport(event, NO_OWNERSHIP))
+    ? fallback.value.filter((event) => !covered.has(event.symbol)).map((event) => fallbackReport(event, NO_OWNERSHIP, today))
     : [];
   const limit = Number(args.options.limit ?? 200);
   const all = [...reports, ...extra].sort((left, right) => left.date.localeCompare(right.date) || (right.marketCap ?? 0) - (left.marketCap ?? 0));
@@ -180,7 +190,7 @@ async function historyReport(symbol: string, context: HeadlessPaneContext, deps:
   const payload = history.status === "fulfilled" ? history.value : null;
   const next = upcoming.status === "fulfilled" ? upcoming.value[0] ?? null : null;
   const notice = abroad
-    ? await abroadHistoryNotice(symbol, next?.name ?? await context.marketData.getQuote(symbol, "").then((quote) => quote.name ?? null, () => null), context)
+    ? await abroadHistoryNotice(symbol, next?.name ?? await context.marketData.getQuote(symbol, "").then((quote) => quote.name ?? null, logFailure("earnings.headless", "Load earnings company name failed", null)), context)
     : null;
   const rows = historyRows(payload, newYorkToday(), next).map((row) => ({
     date: row.date,
@@ -223,18 +233,36 @@ async function historyReport(symbol: string, context: HeadlessPaneContext, deps:
 /** EVTS: the market board, whatever ticker is given. */
 export const EARNINGS_CALENDAR: HeadlessPaneFreshness = { status: "not-a-feed", basis: "calendar" };
 
+/** The board's days, as the pane's Range saves them: a day, a week, or the days ahead. */
+const BOARD_RANGE_OPTIONS: HeadlessPaneOptionDef[] = [
+  { key: "date", type: "string", settingKey: "date", placeholder: "date", example: "--date 2026-10-15", exampleWithoutArgument: true,
+    description: `One day's reports, past or ahead, as ${DATE_OPTION_EXAMPLES}.`, normalize: (value) => isoDateOption(value, "date") },
+  { key: "week", type: "enum", settingKey: "week", values: BOARD_WEEKS.map((value) => ({ value })), example: "--week last", exampleWithoutArgument: true,
+    description: "A week's reports, Monday to Friday: last, this or next. Without it or --date, the days ahead." },
+];
+
+/** The days `--date` or `--week` asks for; the days ahead without either. */
+function boardRange(options: HeadlessPaneLoadArgs["options"]): BoardRange {
+  if (options.date && isBoardWeek(options.week)) throw new Error("Use --date or --week, not both.");
+  return requestedBoardRange(options.date, options.week);
+}
+
 export function createEarningsBoardHeadless(deps: EarningsHeadlessDependencies = defaultDependencies): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
     freshness: EARNINGS_CALENDAR,
     argument: { kind: "ticker", placeholder: "ticker", description: "Optional; the board is the same.", minimum: 0, maximum: 1 },
     options: [
+      ...BOARD_RANGE_OPTIONS,
       { key: "limit", shot: REPORT_ROWS, description: "Maximum rows.", type: "integer", defaultValue: 200, minimum: 1, maximum: 1000 },
     ],
     columns: BOARD_COLUMNS,
-    describe: () => "Earnings Calendar",
-    load(args, context) {
-      return boardRows({ ...args, symbols: [] }, context, deps, args.symbols[0]);
+    describe: (args) => {
+      const range = boardRangeLabel(boardRange(args.options), newYorkToday());
+      return range ? `Earnings Calendar | ${range}` : "Earnings Calendar";
+    },
+    async load(args, context) {
+      return boardRows({ ...args, symbols: [] }, context, deps, args.symbols[0], boardRange(args.options));
     },
   };
 }
@@ -251,12 +279,22 @@ export function createEarningsHeadless(deps: EarningsHeadlessDependencies = defa
       maximum: 100,
     },
     options: [
+      ...BOARD_RANGE_OPTIONS,
       { key: "limit", shot: REPORT_ROWS, description: "Maximum rows on the market board or a ticker list.", type: "integer", defaultValue: 200, minimum: 1, maximum: 1000 },
     ],
     columns: BOARD_COLUMNS,
-    describe: (args) => (args.symbols.length === 0 ? "Earnings Calendar" : `ERN ${args.symbols.join(", ")}`),
-    load(args, context) {
-      return args.symbols.length === 1 ? historyReport(args.symbols[0]!, context, deps) : boardRows(args, context, deps);
+    describe: (args) => {
+      const range = args.symbols.length === 1 ? null : boardRangeLabel(boardRange(args.options), newYorkToday());
+      const title = args.symbols.length === 0 ? "Earnings Calendar" : `ERN ${args.symbols.join(", ")}`;
+      return range ? `${title} | ${range}` : title;
+    },
+    async load(args, context) {
+      const range = boardRange(args.options);
+      if (args.symbols.length === 1 && range) {
+        const symbol = args.symbols[0]!;
+        throw new Error(`ERN ${symbol} is its report history, past reports included; --date and --week pick the board's days. Run \`gloom fn EVTS ${symbol} ${args.options.date ? `--date ${args.options.date}` : `--week ${args.options.week}`}\` for the market's.`);
+      }
+      return args.symbols.length === 1 ? historyReport(args.symbols[0]!, context, deps) : boardRows(args, context, deps, undefined, range);
     },
   };
 }

package/src/plugins/builtin/earnings/history-model.ts

@@ -4,9 +4,9 @@ import { scalarPoint } from "../../../components/chart/static/series";
 import type { TimeSeriesPoint } from "../../../time-series/types";
 import type { EarningsEvent } from "../../../types/data-provider";
 import type { EarningsDateStatus, EarningsEpsBasis } from "../../../types/financials";
-import { dateStatusFromEstimateFlag, earningsDateStatus, earningsEpsBasis, isProvisionalActual } from "../shared/earnings-report";
+import { earningsDateStatus, earningsEpsBasis, isProvisionalActual } from "../shared/earnings-report";
+import { resolveReportRows, type ReportRowAdapter } from "../shared/earnings-calendar";
 import { addDays, MIN_AVERAGE_REPORTS } from "./board-model";
-import { coherentEarningsValue } from "./estimate-basis";
 import { datedYear, impliedText, moveSize, shortDate, surprise, TIMING_LABEL } from "./format";
 
 export interface HistoryRow {
@@ -45,12 +45,57 @@ export interface HistoryRow {
 const HISTORY_QUARTERS = 12;
 const AVERAGE_OVER = 8;
 
+/** A report today stays upcoming until its first close after the report prices a move. */
+const isUpcoming = (date: string, move: number | null, today: string) => date >= today && move == null;
+
+/** ERN's rows as the shared calendar resolver reads and rebuilds them. */
+const historyAdapter = (today: string): ReportRowAdapter<HistoryRow> => ({
+  slot: (row) => ({ date: row.date, dateStatus: row.dateStatus, epsActual: row.epsActual }),
+  reported: (row, epsActual) => {
+    const actual = row.epsActual ?? epsActual;
+    return { ...row, dateStatus: "reported", epsActual: actual, epsSurprise: surprise(actual, row.epsEstimate) };
+  },
+  fromCalendar(report, row) {
+    // The calendar's consensus goes with its date; without one, the record's stays.
+    const estimate = report.epsEstimate != null;
+    const epsEstimate = estimate ? report.epsEstimate : row?.epsEstimate ?? null;
+    const epsActual = report.epsActual ?? row?.epsActual ?? null;
+    const move = row?.move ?? null;
+    return {
+      key: report.date,
+      date: report.date,
+      timing: report.timing ?? row?.timing ?? null,
+      expectedTiming: report.timing == null && !!row?.expectedTiming,
+      fiscalPeriod: row?.fiscalPeriod ?? report.fiscalPeriod,
+      upcoming: isUpcoming(report.date, move, today),
+      dateStatus: report.dateStatus,
+      epsEstimate,
+      epsAnalysts: estimate ? report.epsAnalysts : row?.epsAnalysts ?? null,
+      epsActual,
+      provisional: row?.provisional ?? false,
+      epsBasis: estimate ? report.epsBasis : row?.epsBasis ?? null,
+      epsSurprise: surprise(epsActual, epsEstimate),
+      revenueEstimate: report.revenueEstimate ?? row?.revenueEstimate ?? null,
+      revenueActual: row?.revenueActual ?? null,
+      revenueProvisional: row?.revenueProvisional ?? false,
+      revenueSurprise: row?.revenueSurprise ?? null,
+      implied: row?.implied ?? null,
+      impliedMethod: row?.impliedMethod ?? null,
+      impliedExpiry: row?.impliedExpiry ?? null,
+      move,
+      moveRatio: row?.moveRatio ?? null,
+    };
+  },
+});
+
 /**
- * Newest first, the upcoming report leading. A report today stays upcoming
- * until its first close after the report prices a move.
+ * Newest first, the upcoming report leading. The calendar's next report is
+ * resolved against the history as every earnings surface resolves it
+ * (shared/earnings-calendar): a confirmed date beats a projected one, a date
+ * gone by is reported, and a date past the stored calendar's horizon is added.
  */
 export function historyRows(payload: EarningsHistoryPayload | null, today: string, upcoming: EarningsEvent | null): HistoryRow[] {
-  const rows: HistoryRow[] = (payload?.reports ?? []).map((report) => {
+  const recorded: HistoryRow[] = (payload?.reports ?? []).map((report) => {
     const move = report.realized?.move ?? null;
     const implied = report.implied?.move ?? null;
     return {
@@ -59,7 +104,7 @@ export function historyRows(payload: EarningsHistoryPayload | null, today: strin
       timing: report.timing,
       expectedTiming: report.timingSource === "history",
       fiscalPeriod: report.fiscalPeriod,
-      upcoming: report.date >= today && move == null,
+      upcoming: isUpcoming(report.date, move, today),
       dateStatus: earningsDateStatus(report.dateStatus),
       epsEstimate: report.epsEstimate,
       epsAnalysts: report.epsAnalysts,
@@ -78,36 +123,8 @@ export function historyRows(payload: EarningsHistoryPayload | null, today: strin
       moveRatio: move != null && implied ? Math.abs(move) / implied : null,
     };
   });
-  // Past the stored calendar's horizon the per-ticker calendar still knows the next date.
-  if (upcoming && !rows.some((row) => row.upcoming)) {
-    const date = upcoming.earningsDate.toISOString().slice(0, 10);
-    if (date >= today) {
-      rows.unshift({
-        key: date,
-        date,
-        timing: upcoming.timing === "BMO" ? "bmo" : upcoming.timing === "AMC" ? "amc" : null,
-        expectedTiming: false,
-        fiscalPeriod: null,
-        upcoming: true,
-        dateStatus: dateStatusFromEstimateFlag(upcoming.isDateEstimate),
-        epsEstimate: coherentEarningsValue(upcoming, "epsEstimate"),
-        epsAnalysts: coherentEarningsValue(upcoming, "epsAnalysts"),
-        epsActual: null,
-        provisional: false,
-        epsBasis: earningsEpsBasis(upcoming.epsBasis),
-        epsSurprise: null,
-        revenueEstimate: coherentEarningsValue(upcoming, "revenueEstimate"),
-        revenueActual: null,
-        revenueProvisional: false,
-        revenueSurprise: null,
-        implied: null,
-        impliedMethod: null,
-        impliedExpiry: null,
-        move: null,
-        moveRatio: null,
-      });
-    }
-  }
+  const rows = resolveReportRows(recorded, upcoming, today, historyAdapter(today))
+    .sort((left, right) => right.date.localeCompare(left.date));
   const upcomingRows = rows.filter((row) => row.upcoming).slice(-1);
   return [...upcomingRows, ...rows.filter((row) => !row.upcoming).slice(0, HISTORY_QUARTERS)];
 }