gloomberb 0.18.2 → 0.18.4

package/src/time-series/price-comparison.ts

@@ -1,9 +1,13 @@
 import { scalarPointValue } from "./alignment";
 import { getTimeSeriesField } from "./field-catalog";
 import type { ChartSpec, ResolvedSeries, TimeSeriesPoint } from "./types";
-import type { ManualChartResolution } from "./resolution";
+import { chartBarSizeSource, type ManualChartResolution } from "./resolution";
+import type { TimeRange } from "./range";
 import { zonedDateTimeParts } from "../utils/zoned-date-time";
 import { barLastSession } from "../market-data/market/bar-period";
+import {
+  barCloseDay, isIntradayDailyBar, isReturnPeriod, LATEST_INTRADAY_TEXT, periodBaseDay, periodBaseIndex, periodDayText,
+} from "../market-data/market/period-return";
 
 const PRICE_COMPARISON_BASIS = "Price returns in each listing's currency; cash distributions and FX conversion excluded.";
 
@@ -15,6 +19,26 @@ export interface PriceComparison {
   notice: string;
   alignment?: "session-date" | "timestamp";
   sourceBounds?: Record<string, { start: number; end: number }>;
+  /**
+   * Each compared leg's base and end as the notice names them, `YYYY-MM-DD`:
+   * the day its base close is from, the day of its newest observation, and
+   * whether that observation is the session still trading.
+   */
+  legs?: Record<string, { baseDay: string; endDay: string; intraday: boolean }>;
+  /** Legs left out of the comparison, by the symbol asked for, and why; the rest still compare. */
+  dropped?: Array<{ seriesId: string; label: string; reason: string }>;
+}
+
+export interface PriceComparisonOptions {
+  /**
+   * The chart's untouched preset range; null for authored dates or a view
+   * panned or zoomed off it. A preset's legs each run to their own newest
+   * observation, so one that is behind does not cut the others short, and a
+   * calendar range (1W to 5Y) is measured from the close on or before the
+   * same date a range before (periodBaseDay), as RETURN is.
+   */
+  preset?: TimeRange | null;
+  now?: number;
 }
 
 export function observationDate(time: number, series: Pick<ResolvedSeries, "timeBasis">): string {
@@ -47,6 +71,8 @@ export function priceObservationWindowFilter(
 }
 
 export function priceComparisonBoundsForSeries(series: ResolvedSeries, comparison: PriceComparison | null) {
+  // A leg left out of the comparison shows nothing of it.
+  if (comparison?.dropped?.some((entry) => entry.seriesId === series.id)) return { start: null, end: null };
   return comparison?.sourceBounds?.[series.id] ?? comparison;
 }
 
@@ -55,6 +81,20 @@ function displayDate(time: number): string {
   return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso.replace("T", " ").replace(".000Z", " UTC");
 }
 
+/** "Mon 21 Sep close (EWJ Fri 18 Sep close)": the text most legs share, then the others by symbol. */
+function legsText(entries: ReadonlyArray<{ label: string; text: string }>): string {
+  const groups = new Map<string, string[]>();
+  for (const { label, text } of entries) groups.set(text, [...groups.get(text) ?? [], label]);
+  const [main, ...rest] = [...groups].sort((left, right) => right[1].length - left[1].length);
+  if (!main) return "";
+  return rest.length ? `${main[0]} (${rest.map(([text, labels]) => `${labels.join(", ")} ${text}`).join("; ")})` : main[0];
+}
+
+/** A leg's venue, whose sessions say whether its newest bar is still trading. */
+function legVenue(series: ResolvedSeries | undefined): string | undefined {
+  return series?.timeBasis?.exchange || series?.listing?.exchange || undefined;
+}
+
 /** Comparable normalized closing-price legs share observed endpoints. Other chart meanings are unchanged. */
 export function priceComparisonSeriesIds(spec: ChartSpec): string[] | null {
   if (spec.viewport.maxPoints !== undefined) return null;
@@ -71,58 +111,163 @@ export function priceComparisonSeriesIds(spec: ChartSpec): string[] | null {
   return visible.map((entry) => entry.id);
 }
 
+interface ComparedLeg {
+  id: string;
+  label: string;
+  entry: ResolvedSeries;
+  /** Every priced observation by key, chronological: a period's base can be before the window. */
+  keys: string[];
+  points: Map<string, TimeSeriesPoint>;
+  /** The keys inside the window. */
+  window: string[];
+}
+
+/**
+ * Where each compared leg starts and ends, and what the comparison says of it.
+ *
+ * Calendar bars compare by session date. An untouched preset range measures
+ * each leg from its own close on or before the same date a range before the
+ * newest observation of the chart (periodBaseDay), the convention RETURN
+ * and every period return share, and runs each leg to its own newest
+ * observation. Authored dates and a panned view start every leg at the first
+ * date they share and end them at the last. A leg with no prices, or one,
+ * is left out with its reason and the others still compare.
+ */
 export function resolvePriceComparison(
   spec: ChartSpec,
   series: readonly ResolvedSeries[],
   bounds: { start: number | null; end: number | null },
-  resolution: ManualChartResolution | "auto" = spec.viewport.resolution,
+  resolution: ManualChartResolution | "auto" = spec.viewport.resolution === "auto" ? "auto" : chartBarSizeSource(spec.viewport.resolution),
   dateWindow: ChartSpec["viewport"]["dateWindow"] | null = spec.viewport.dateWindow,
+  options: PriceComparisonOptions = {},
 ): PriceComparison | null {
   const seriesIds = priceComparisonSeriesIds(spec);
   if (!seriesIds) return null;
+  const now = options.now ?? Date.now();
   const byId = new Map(series.map((entry) => [entry.id, entry]));
   const calendarBars = resolution === "1d" || resolution === "1wk" || resolution === "1mo";
-  const observations = seriesIds.map((id) => {
-    const entry = byId.get(id);
-    if (!entry) return new Map<string, TimeSeriesPoint>();
+  const order = (left: string, right: string) => calendarBars ? left.localeCompare(right) : Number(left) - Number(right);
+  const symbolOf = (id: string) => {
+    const source = spec.series.find((entry) => entry.id === id)?.source;
+    return source?.kind === "security" ? source.instrument.symbol : id;
+  };
+  // A leg not loaded yet (a seed from cached history) has not failed: nothing compares until it is.
+  const unavailable = `${PRICE_COMPARISON_BASIS} Comparison unavailable: need two shared dates and a nonzero baseline.`;
+  if (seriesIds.some((id) => !byId.has(id))) return { seriesIds, start: null, end: null, notice: unavailable };
+  const dropped: NonNullable<PriceComparison["dropped"]> = [];
+  const reported = new Set<string>();
+  const legs: ComparedLeg[] = [];
+  for (const id of seriesIds) {
+    const entry = byId.get(id)!;
     const inWindow = priceObservationWindowFilter(entry, bounds, resolution, dateWindow);
-    return new Map(entry.points.flatMap((point) => {
+    const points = new Map<string, TimeSeriesPoint>();
+    const window = new Set<string>();
+    for (const point of entry.points) {
       const time = point.date.getTime();
-      if (!inWindow(time) || scalarPointValue(point) === null) return [];
-      return [[calendarBars ? observationDate(time, entry) : String(time), point] as const];
-    }));
-  });
-  const shared = [...observations[0]!.keys()].filter((key) => observations.every((points) => points.has(key)))
-    .sort((a, b) => calendarBars ? a.localeCompare(b) : Number(a) - Number(b));
-  const start = shared.find((key) => observations.every((points) => {
-    const point = points.get(key);
-    return point && scalarPointValue(point) !== 0;
-  }));
-  const end = shared.at(-1);
-  if (start === undefined || end === undefined || start === end) return {
-    seriesIds, start: null, end: null,
-    notice: `${PRICE_COMPARISON_BASIS} Comparison unavailable: need two shared dates and a nonzero baseline.`,
-  };
+      if (!Number.isFinite(time) || scalarPointValue(point) === null) continue;
+      const key = calendarBars ? observationDate(time, entry) : String(time);
+      points.set(key, point);
+      if (inWindow(time)) window.add(key);
+    }
+    const leg = { id, label: symbolOf(id), entry, keys: [...points.keys()].sort(order), points, window: [...window].sort(order) };
+    if (leg.window.length) legs.push(leg);
+    else if (entry.warning?.trim()) {
+      // A leg that failed to load: the chart's errors already say why.
+      dropped.push({ seriesId: id, label: leg.label, reason: entry.warning.trim() });
+      reported.add(id);
+    } else dropped.push({ seriesId: id, label: leg.label, reason: "no prices in this range" });
+  }
+  const nonzero = (leg: ComparedLeg, key: string) => scalarPointValue(leg.points.get(key)!) !== 0;
   // A weekly or monthly bar's close is from the last session of its period, which the notice dates it by.
-  const period = resolution === "1wk" ? "week" : resolution === "1mo" ? "month" : null;
-  const venue = byId.get(seriesIds[0]!)?.timeBasis?.exchange || byId.get(seriesIds[0]!)?.listing?.exchange || undefined;
-  const sessionDay = (key: string) => (period ? barLastSession(key, period, venue, Date.now()) : null) ?? key;
-  const sourceBounds = Object.fromEntries(seriesIds.map((id, index) => [id, {
-    start: observations[index]!.get(start)!.date.getTime(),
-    end: observations[index]!.get(end)!.date.getTime(),
+  const barPeriod = resolution === "1wk" ? "week" : resolution === "1mo" ? "month" : null;
+  const venue = legVenue(byId.get(seriesIds[0]!));
+  const sessionDay = (key: string) => (barPeriod ? barLastSession(key, barPeriod, venue, now) : null) ?? key;
+  const dayOf = (leg: ComparedLeg, key: string) => calendarBars ? key : observationDate(Number(key), leg.entry);
+  const preset = options.preset ?? null;
+  const period = !dateWindow && isReturnPeriod(preset) ? preset : null;
+  const ownEnds = preset !== null && !dateWindow;
+  const shared = (keys: (leg: ComparedLeg) => readonly string[]) => {
+    const sets = legs.map((leg) => new Set(keys(leg)));
+    return legs.length ? keys(legs[0]!).filter((key) => sets.every((set) => set.has(key))) : [];
+  };
+  const sharedWindow = shared((leg) => leg.window);
+  const sharedStart = sharedWindow.find((key) => legs.every((leg) => nonzero(leg, key)));
+  // The period is measured back from the chart's newest observation, by its session day.
+  const anchor = period && legs.length
+    ? legs.map((leg) => calendarBars ? sessionDay(leg.window.at(-1)!) : dayOf(leg, leg.window.at(-1)!)).sort().at(-1)!
+    : null;
+  const baseDay = anchor && period ? periodBaseDay(anchor, period) : null;
+  const closeDay = (leg: ComparedLeg, key: string) => calendarBars && resolution !== "1d" ? barCloseDay(key, resolution, legVenue(leg.entry)) : key;
+  // Intraday bars share their times, so their base is the last bar the legs share on or before the base day.
+  const sharedBase = baseDay && !calendarBars ? (() => {
+    const keys = shared((leg) => leg.keys).filter((key) => legs.every((leg) => nonzero(leg, key)));
+    const index = periodBaseIndex(keys.map((key) => dayOf(legs[0]!, key)), baseDay);
+    return index < 0 ? undefined : keys[index];
+  })() : undefined;
+  const startOf = (leg: ComparedLeg): string | undefined => {
+    if (!baseDay) return sharedStart;
+    if (!calendarBars) return sharedBase ?? sharedStart;
+    const index = periodBaseIndex(leg.keys.map((key) => closeDay(leg, key)), baseDay);
+    const base = index < 0 ? undefined : leg.keys[index];
+    // Without a close on or before the base day (a listing younger than the range), its first close in range.
+    return base !== undefined && nonzero(leg, base) ? base : leg.window.find((key) => nonzero(leg, key));
+  };
+  const sharedEnd = sharedWindow.at(-1);
+  // Legs that share their dates compare over two of them or not at all; a leg that runs on its own is left out alone.
+  const sharedSpan = sharedStart !== undefined && sharedEnd !== undefined && order(sharedStart, sharedEnd) < 0;
+  const compared = baseDay || ownEnds || sharedSpan ? legs.flatMap((leg) => {
+    const start = startOf(leg);
+    const end = ownEnds ? leg.window.at(-1) : sharedEnd;
+    if (start !== undefined && end !== undefined && order(start, end) < 0) return [{ leg, start, end }];
+    if (baseDay || sharedStart !== undefined) {
+      dropped.push({ seriesId: leg.id, label: leg.label, reason: start === undefined ? "no nonzero price to measure from in this range" : "only one price in this range" });
+    }
+    return [];
+  }) : [];
+  // "Left out: VIX; EWJ (only one price in this range)."
+  const droppedText = dropped.length
+    ? ` Left out: ${dropped.map((entry) => reported.has(entry.seriesId) ? entry.label : `${entry.label} (${entry.reason})`).join("; ")}.`
+    : "";
+  if (!compared.length) return { seriesIds, start: null, end: null, notice: unavailable, ...(dropped.length ? { dropped } : {}) };
+  const sourceBounds = Object.fromEntries(compared.map(({ leg, start, end }) => [leg.id, {
+    start: leg.points.get(start)!.date.getTime(),
+    end: leg.points.get(end)!.date.getTime(),
   }]));
+  const currentYear = new Date(now).getUTCFullYear();
+  const legDays = Object.fromEntries(compared.map(({ leg, start, end }) => {
+    const endDay = calendarBars ? sessionDay(end) : dayOf(leg, end);
+    // A daily bar of the session still trading, or a week or month running through it.
+    return [leg.id, { baseDay: calendarBars ? sessionDay(start) : dayOf(leg, start), endDay,
+      intraday: calendarBars && isIntradayDailyBar(endDay, legVenue(leg.entry), now) }];
+  }));
+  const span = calendarBars
+    ? (() => {
+      const from = legsText(compared.map(({ leg }) => ({ label: leg.label, text: `${periodDayText(legDays[leg.id]!.baseDay, currentYear)} close` })));
+      const to = legsText(compared.map(({ leg }) => ({ label: leg.label, text: legDays[leg.id]!.intraday
+        ? `${periodDayText(legDays[leg.id]!.endDay, currentYear)}, ${LATEST_INTRADAY_TEXT}`
+        : `${periodDayText(legDays[leg.id]!.endDay, currentYear)} close` })));
+      return `From ${from} to ${to}; market session times may differ.`;
+    })()
+    : baseDay && sharedBase !== undefined
+      ? `From ${periodDayText(legDays[compared[0]!.leg.id]!.baseDay, currentYear)} close to ${displayDate(Math.max(...Object.values(sourceBounds).map((range) => range.end)))}.`
+      : `Shared observations: ${displayDate(Math.min(...Object.values(sourceBounds).map((range) => range.start)))} to ${displayDate(Math.max(...Object.values(sourceBounds).map((range) => range.end)))}.`;
   return {
     seriesIds,
     start: Math.min(...Object.values(sourceBounds).map((range) => range.start)),
     end: Math.max(...Object.values(sourceBounds).map((range) => range.end)),
     alignment: calendarBars ? "session-date" : "timestamp",
     sourceBounds,
-    notice: calendarBars
-      ? `${PRICE_COMPARISON_BASIS} Shared calendar dates: ${sessionDay(start)} to ${sessionDay(end)}; market session times may differ.`
-      : `${PRICE_COMPARISON_BASIS} Shared observations: ${displayDate(Number(start))} to ${displayDate(Number(end))}.`,
+    legs: legDays,
+    ...(dropped.length ? { dropped } : {}),
+    notice: `${PRICE_COMPARISON_BASIS} ${span}${droppedText}`,
   };
 }
 
+/** Whether a comparison's newest point is the session still trading on any leg. */
+export function priceComparisonEndsIntraday(comparison: PriceComparison | null | undefined): boolean {
+  return Object.values(comparison?.legs ?? {}).some((leg) => leg.intraday);
+}
+
 /**
  * The bars a compared leg pans and zooms over: inside the view only its shared
  * dates, as the chart shows them, and every loaded bar past either edge of the

package/src/time-series/range.ts

@@ -1,5 +1,13 @@
 export type TimeRange = "1D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "5Y" | "ALL";
-export type ChartResolution = "auto" | "1m" | "5m" | "15m" | "30m" | "45m" | "1h" | "1d" | "1wk" | "1mo";
+/** A bar size's unit: minutes, hours, days, weeks and months. */
+export type ChartBarSizeUnit = "m" | "h" | "d" | "wk" | "mo";
+/**
+ * A bar size a chart builds from the bars a source serves: `10m` from 5-minute
+ * bars, `4h` from hourly ones, `2d` from daily ones. Always in the form
+ * `parseChartBarSize` returns; sources and brokers never see one.
+ */
+export type CustomChartResolution = `${number}${ChartBarSizeUnit}`;
+export type ChartResolution = "auto" | "1m" | "5m" | "15m" | "30m" | "45m" | "1h" | "1d" | "1wk" | "1mo" | CustomChartResolution;
 
 export interface ChartDateWindow {
   start: Date | null;

package/src/time-series/resolution.ts

@@ -1,8 +1,11 @@
-import type { ChartResolution, TimeRange } from "./range";
+import type { ChartBarSizeUnit, ChartResolution, CustomChartResolution, TimeRange } from "./range";
 import { CHART_RESOLUTIONS, TIME_RANGES } from "./range";
 import { isDateWindowWithinTimeRange } from "./date-window";
 
-export type ManualChartResolution = Exclude<ChartResolution, "auto">;
+/** The bar sizes sources and brokers serve, and the only ones they are asked for. */
+export type ManualChartResolution = "1m" | "5m" | "15m" | "30m" | "45m" | "1h" | "1d" | "1wk" | "1mo";
+/** Any bar size a chart draws: one a source serves, or one built from them. */
+export type ChartBarSize = Exclude<ChartResolution, "auto">;
 
 export interface ChartResolutionSupport {
   resolution: ManualChartResolution;
@@ -13,7 +16,7 @@ export interface ChartResolutionSupport {
 export const TIME_RANGE_ORDER = TIME_RANGES;
 const CHART_RESOLUTION_ORDER = CHART_RESOLUTIONS;
 
-const CHART_RESOLUTION_LABELS: Record<ChartResolution, string> = {
+const CHART_RESOLUTION_LABELS: Record<ManualChartResolution | "auto", string> = {
   auto: "AUTO",
   "1m": "1M",
   "5m": "5M",
@@ -39,7 +42,7 @@ const RANGE_PRESET_RESOLUTION: Record<TimeRange, ManualChartResolution> = {
 
 /**
  * The bar size a price history for a range is served in, unlike the chart
- * presets above: what `gloomberb history` and the historical prices pane get.
+ * presets above: what `gloom history` and the historical prices pane get.
  */
 export const RANGE_HISTORY_RESOLUTION: Readonly<Record<TimeRange, ManualChartResolution>> = {
   "1D": "5m",
@@ -137,21 +140,153 @@ function compareTimeRange(left: TimeRange, right: TimeRange): number {
   return getTimeRangeIndex(left) - getTimeRangeIndex(right);
 }
 
-function isChartResolution(value: unknown): value is ChartResolution {
-  return CHART_RESOLUTION_ORDER.includes(value as ChartResolution);
+export function isManualChartResolution(value: unknown): value is ManualChartResolution {
+  return value !== "auto" && CHART_RESOLUTION_ORDER.includes(value as ChartResolution);
 }
 
-function isManualChartResolution(value: unknown): value is ManualChartResolution {
-  return value !== "auto" && CHART_RESOLUTION_ORDER.includes(value as ChartResolution);
+const BAR_SIZE_UNIT_MS: Readonly<Record<ChartBarSizeUnit, number>> = {
+  m: 60_000,
+  h: 60 * 60_000,
+  d: 24 * 60 * 60_000,
+  wk: 7 * 24 * 60 * 60_000,
+  mo: 30 * 24 * 60 * 60_000,
+};
+
+/** The longest bar of each unit: a day of minutes or hours, a year of days, weeks or months. */
+const BAR_SIZE_MAX_COUNT: Readonly<Record<ChartBarSizeUnit, number>> = { m: 1440, h: 24, d: 365, wk: 52, mo: 12 };
+
+const BAR_SIZE_UNITS: Readonly<Record<string, ChartBarSizeUnit>> = {
+  m: "m", min: "m", mins: "m", minute: "m", minutes: "m",
+  h: "h", hr: "h", hrs: "h", hour: "h", hours: "h",
+  d: "d", day: "d", days: "d",
+  w: "wk", wk: "wk", week: "wk", weeks: "wk",
+  mo: "mo", mon: "mo", month: "mo", months: "mo",
+};
+
+/** A bar size in its one stored form: `90m`, `4h` (not `240m`), `2d`, `1wk`, `3mo`. */
+function canonicalBarSize(count: number, unit: ChartBarSizeUnit): ChartBarSize | null {
+  if (!Number.isSafeInteger(count) || count <= 0) return null;
+  if (unit === "m" && count % 60 === 0) return canonicalBarSize(count / 60, "h");
+  if (count > BAR_SIZE_MAX_COUNT[unit]) return null;
+  return `${count}${unit}` as ChartBarSize;
+}
+
+/** A stored bar size's count and unit; null for anything that is not one. */
+export function chartBarSizeParts(size: unknown): { count: number; unit: ChartBarSizeUnit } | null {
+  if (typeof size !== "string") return null;
+  const match = /^([1-9]\d{0,3})(m|h|d|wk|mo)$/.exec(size);
+  if (!match) return null;
+  const count = Number(match[1]);
+  const unit = match[2] as ChartBarSizeUnit;
+  return canonicalBarSize(count, unit) === size ? { count, unit } : null;
+}
+
+/** A stored bar size (`4h`, `2d`, `1wk`); `auto` is not one. */
+function isChartBarSize(value: unknown): value is ChartBarSize {
+  return chartBarSizeParts(value) !== null;
+}
+
+/** Any value a chart's resolution may hold: `auto` or a stored bar size. */
+export function isChartResolution(value: unknown): value is ChartResolution {
+  return value === "auto" || isChartBarSize(value);
+}
+
+/** A bar size the source does not serve, which the chart builds from one it does. */
+export function isCustomChartResolution(value: unknown): value is CustomChartResolution {
+  return isChartBarSize(value) && !isManualChartResolution(value);
+}
+
+/**
+ * Reads a bar size as typed: `10m`, `10 min`, `4h`, `240` (minutes), `2D`,
+ * `3 days`, `2W`, `3mo`, `1Y`. A capital `M` alone is read as nothing: the
+ * chart labels months `M` and the command line minutes `1M`, so `3M` could be
+ * either. Null for anything else, and for bars longer than a day of minutes
+ * or hours, a year of days or weeks, or twelve months.
+ */
+export function parseChartBarSize(value: unknown): ChartBarSize | null {
+  if (typeof value !== "string") return null;
+  const match = /^(\d{1,4})\s*([A-Za-z]*)$/.exec(value.trim());
+  if (!match) return null;
+  const count = Number(match[1]);
+  const written = match[2]!;
+  if (written === "") return canonicalBarSize(count, "m");
+  if (written === "M") return null;
+  const lower = written.toLowerCase();
+  if (lower === "y" || lower === "yr" || lower === "year" || lower === "years") return canonicalBarSize(count * 12, "mo");
+  const unit = BAR_SIZE_UNITS[lower];
+  return unit ? canonicalBarSize(count, unit) : null;
+}
+
+/** A chart resolution as typed or stored: `auto`, or any bar size `parseChartBarSize` reads. */
+export function parseChartResolution(value: unknown): ChartResolution | null {
+  if (typeof value === "string" && value.trim().toLowerCase() === "auto") return "auto";
+  return parseChartBarSize(value);
+}
+
+/** How long one bar is; a month counts as 30 days. */
+export function chartBarSizeStepMs(size: ChartBarSize): number {
+  const parts = chartBarSizeParts(size);
+  return parts ? parts.count * BAR_SIZE_UNIT_MS[parts.unit] : Number.NaN;
+}
+
+/** Source bar sizes that can make up minute and hour bars, longest first. */
+const INTRADAY_SOURCE_RESOLUTIONS: readonly ManualChartResolution[] = ["1h", "45m", "30m", "15m", "5m", "1m"];
+
+/**
+ * The bars a source serves that a bar size is built from: the longest that
+ * divide it (1h for 4h, 5m for 10m, 30m for 90m), among those the source
+ * serves when `support` says. Day, week and month multiples come from 1d, 1wk
+ * and 1mo bars. `openMinute`, minutes after local midnight, is when sessions
+ * open on a listing whose source bars start on the clock rather than at the
+ * open (futures): its source bars must also divide it, or a bar would straddle
+ * the open. A bar size the source serves is its own.
+ */
+export function chartBarSizeSource(
+  size: ChartBarSize,
+  support: readonly ChartResolutionSupport[] = [],
+  openMinute: number | null = null,
+): ManualChartResolution {
+  if (isManualChartResolution(size)) return size;
+  const parts = chartBarSizeParts(size);
+  if (!parts) return "1d";
+  if (parts.unit === "d") return "1d";
+  if (parts.unit === "wk") return "1wk";
+  if (parts.unit === "mo") return "1mo";
+  const minutes = parts.unit === "h" ? parts.count * 60 : parts.count;
+  const candidates = INTRADAY_SOURCE_RESOLUTIONS.filter((resolution) => {
+    const step = CHART_RESOLUTION_STEP_MS[resolution] / 60_000;
+    return minutes % step === 0 && (openMinute === null || openMinute % step === 0);
+  });
+  const served = support.length > 0
+    ? candidates.find((resolution) => getSupportMaxRange(support, resolution) !== null)
+    : undefined;
+  return served ?? candidates[0] ?? "1m";
+}
+
+/**
+ * Every bar size the chart lists, shortest first: the ones sources serve and
+ * the ones most asked for that it builds from them. Any other is typed in.
+ */
+export const CHART_BAR_SIZE_PRESETS: readonly ChartBarSize[] = [
+  "1m", "5m", "10m", "15m", "30m", "45m", "1h", "2h", "4h", "1d", "2d", "3d", "1wk", "1mo",
+];
+
+/** Orders bar sizes from the shortest bar to the longest. */
+export function sortChartBarSizes<T extends ChartBarSize>(sizes: readonly T[]): T[] {
+  return [...sizes].sort((left, right) => chartBarSizeStepMs(left) - chartBarSizeStepMs(right));
 }
 
-/** @deprecated Slated for removal. Check the value against `CHART_RESOLUTIONS` instead. */
+/** @deprecated Slated for removal. Check the value with `isChartResolution` instead. */
 export function normalizeChartResolution(value: unknown, fallback: ChartResolution = "auto"): ChartResolution {
   return isChartResolution(value) ? value : fallback;
 }
 
+const CUSTOM_BAR_UNIT_LABELS: Readonly<Record<ChartBarSizeUnit, string>> = { m: "M", h: "H", d: "D", wk: "W", mo: "MO" };
+
 export function getChartResolutionLabel(resolution: ChartResolution): string {
-  return CHART_RESOLUTION_LABELS[resolution];
+  if (isManualChartResolution(resolution) || resolution === "auto") return CHART_RESOLUTION_LABELS[resolution];
+  const parts = chartBarSizeParts(resolution);
+  return parts ? `${parts.count}${CUSTOM_BAR_UNIT_LABELS[parts.unit]}` : String(resolution).toUpperCase();
 }
 
 export function getPresetResolution(range: TimeRange): ManualChartResolution {
@@ -199,11 +334,11 @@ export function getExpandedBufferRange(
   const nextCandidate = getNextBufferRange(bufferRange);
   const nextBufferRange = resolution === "auto"
     ? nextCandidate
-    : clampTimeRangeToMaxRange(nextCandidate, supportMap.get(resolution) ?? bufferRange);
+    : clampTimeRangeToMaxRange(nextCandidate, supportMap.get(chartBarSizeSource(resolution)) ?? bufferRange);
   return isTimeRangeAtOrBelow(nextBufferRange, bufferRange) ? null : nextBufferRange;
 }
 
-export function sortChartResolutions<T extends ChartResolution>(resolutions: readonly T[]): T[] {
+export function sortChartResolutions<T extends "auto" | ManualChartResolution>(resolutions: readonly T[]): T[] {
   return [...resolutions].sort((left, right) => (
     CHART_RESOLUTION_ORDER.indexOf(left) - CHART_RESOLUTION_ORDER.indexOf(right)
   ));
@@ -267,6 +402,31 @@ export function getSupportMaxRange(
   return normalizeChartResolutionSupport(support).find((entry) => entry.resolution === resolution)?.maxRange ?? null;
 }
 
+function viewportSpanMs(range: TimeRange, dateWindow?: { start: string | Date; end: string | Date }): number {
+  const start = dateWindow ? new Date(dateWindow.start).getTime() : Number.NaN;
+  const end = dateWindow ? new Date(dateWindow.end).getTime() : Number.NaN;
+  return Number.isFinite(start) && Number.isFinite(end) && start <= end
+    ? end - start
+    : TIME_RANGE_APPROXIMATE_DAYS[range] * CHART_RESOLUTION_STEP_MS["1d"];
+}
+
+/**
+ * The bar sizes of `sizes` a chart of this range or window can draw: each
+ * one's source bars reach back over it, and it holds at least two bars.
+ */
+export function getSupportedChartBarSizesForViewport<T extends ChartBarSize>(
+  range: TimeRange,
+  support: readonly ChartResolutionSupport[],
+  sizes: readonly T[],
+  dateWindow?: { start: string | Date; end: string | Date },
+  openMinute: number | null = null,
+): T[] {
+  const served = new Set<ManualChartResolution>(getSupportedChartResolutionsForViewport(range, support, dateWindow));
+  const span = viewportSpanMs(range, dateWindow);
+  return sizes.filter((size) => served.has(chartBarSizeSource(size, support, openMinute))
+    && span / chartBarSizeStepMs(size) >= MINIMUM_USEFUL_CHART_POINTS);
+}
+
 export function getSupportedChartResolutionsForViewport(
   range: TimeRange,
   support: readonly ChartResolutionSupport[],
@@ -279,9 +439,7 @@ export function getSupportedChartResolutionsForViewport(
     && !!end
     && Number.isFinite(end.getTime())
     && start.getTime() <= end.getTime();
-  const viewportSpanMs = hasValidDateWindow
-    ? Math.max(end.getTime() - start.getTime(), 0)
-    : TIME_RANGE_APPROXIMATE_DAYS[range] * CHART_RESOLUTION_STEP_MS["1d"];
+  const spanMs = viewportSpanMs(range, dateWindow);
   return normalizeChartResolutionSupport(support)
     .filter((entry) => (
       hasValidDateWindow
@@ -289,7 +447,7 @@ export function getSupportedChartResolutionsForViewport(
         : isTimeRangeAtOrBelow(range, entry.maxRange)
     ))
     .filter((entry) => (
-      viewportSpanMs / CHART_RESOLUTION_STEP_MS[entry.resolution]
+      spanMs / CHART_RESOLUTION_STEP_MS[entry.resolution]
         >= MINIMUM_USEFUL_CHART_POINTS
     ))
     .map((entry) => entry.resolution);