gloomberb 0.18.4 → 0.19.0

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

@@ -1,3 +1,5 @@
+import { currencyPairSpelling } from "../utils/currency-pair";
+
 /**
  * What a price counts, read from its unit: the currency it is in and the
  * quantity one unit of that currency buys ("USD / gallon"), as futures
@@ -7,9 +9,22 @@
 /** Gallons in one US oil barrel: heating oil and gasoline quote per gallon, crude per barrel. */
 export const GALLONS_PER_BARREL = 42;
 
+/**
+ * Barrels in a metric tonne of a refined product, the conversions a formula
+ * knows by their number: gasoil 7.45 bbl/t (ICE gasoil's own), gasoline 8.45.
+ * Times one, a price per barrel is a price per tonne.
+ */
+const BARRELS_PER_TONNE = { gasoil: 7.45, gasoline: 8.45 } as const;
+
+/** Whether a formula's multiplier is the barrels in a tonne of a product (7.45 or 8.45). */
+export function isBarrelsPerTonne(value: number): boolean {
+  return Object.values(BARRELS_PER_TONNE).includes(value as 7.45 | 8.45);
+}
+
 const US_CENTS = /^us\s*cents?$/i;
 const GALLON = /^(?:gallons?|gal)$/i;
 const BARREL = /^(?:barrels?|bbl)$/i;
+const TONNE = /^(?:tonnes?|metric tons?|mt|t)$/i;
 
 /**
  * The currency code a unit's leading factor names: `USD` for "USD", `USX`
@@ -41,10 +56,43 @@ export function contractPriceUnit(unit: string | null | undefined, currency: str
   return parts.currency.toUpperCase() === currency.trim().toUpperCase() ? unit!.trim() : null;
 }
 
-/** One name for a quantity however it is written: "gal" and "gallons" are a gallon, "bbl" a barrel. */
+/** One name for a quantity however it is written: "gal" and "gallons" are a gallon, "bbl" a barrel, "t" a tonne. */
 export function quantityIdentity(quantity: string): string {
   const token = quantity.trim().toLowerCase();
-  return GALLON.test(token) ? "gallon" : BARREL.test(token) ? "barrel" : token.replace(/^shares$/, "share");
+  return GALLON.test(token) ? "gallon" : BARREL.test(token) ? "barrel" : TONNE.test(token) ? "tonne"
+    : token.replace(/^shares$/, "share");
+}
+
+/**
+ * The physical quantities a price can count, each by one name: what sets a
+ * price's scale, so a per-gallon and a per-barrel price never share an axis.
+ * A share, a unit or a currency is none of them.
+ */
+const PHYSICAL_QUANTITIES: ReadonlyArray<readonly [RegExp, string]> = [
+  [GALLON, "gallon"],
+  [BARREL, "barrel"],
+  [TONNE, "tonne"],
+  [/^(?:dry\s+metric\s+tons?|dmtu?)$/i, "dry metric ton"],
+  [/^(?:short\s+)?tons?$/i, "short ton"],
+  [/^(?:bushels?|bu)$/i, "bushel"],
+  [/^(?:pounds?|lbs?)$/i, "pound"],
+  [/^(?:troy\s+)?(?:ounces?|oz)$/i, "troy ounce"],
+  [/^(?:hundredweight|cwt)$/i, "hundredweight"],
+  [/^(?:kilograms?|kg)$/i, "kilogram"],
+  [/^mmbtu$/i, "MMBtu"],
+  [/^therms?$/i, "therm"],
+  [/^gj$/i, "GJ"],
+  [/^mwh$/i, "MWh"],
+  [/^kwh$/i, "kWh"],
+  [/^(?:board\s+feet|mbf)$/i, "board feet"],
+  [/^(?:litres?|liters?)$/i, "litre"],
+  [/^(?:cubic\s+met(?:er|re)s?|m3)$/i, "cubic metre"],
+];
+
+/** The physical quantity a unit's denominator names ("barrel" for "bbl"), or null for a share, a unit or a currency. */
+export function physicalQuantity(quantity: string): string | null {
+  const token = quantity.trim();
+  return PHYSICAL_QUANTITIES.find(([pattern]) => pattern.test(token))?.[1] ?? null;
 }
 
 /** A price per gallon: "USD / gallon", "USD/gallon". */
@@ -67,3 +115,25 @@ export function isPerBarrelUnit(unit: string): boolean {
 export function perBarrelUnit(unit: string): string {
   return isPerGallonUnit(unit) ? unit.replace(/(\/\s*)\S.*$/, "$1barrel") : unit;
 }
+
+/**
+ * The per-tonne unit a per-barrel price takes once multiplied by the barrels
+ * in a tonne (7.45 for gasoil), in the same wording: "USD / barrel" is
+ * "USD / tonne". Any other unit is returned as it is.
+ */
+export function perTonneUnit(unit: string): string {
+  return isPerBarrelUnit(unit) ? unit.replace(/(\/\s*)\S.*$/, "$1tonne") : unit;
+}
+
+/**
+ * What a currency pair's price counts: the quote currency one unit of the
+ * base buys, so EURUSD=X is USD / EUR and USDJPY=X JPY / USD. Null for a
+ * listing that is not a pair, or whose quote is in another currency.
+ */
+export function currencyPairPriceUnit(symbol: string, exchange: string | undefined, currency: string | null | undefined): string | null {
+  const pair = currencyPairSpelling(symbol, exchange);
+  if (!pair || pair.ambiguous || !currency) return null;
+  const base = pair.symbol.slice(0, 3);
+  const quote = pair.symbol.slice(3, 6);
+  return quote === currency.trim().toUpperCase() ? `${quote} / ${base}` : null;
+}

package/src/time-series/resolve-context.ts

@@ -3,7 +3,8 @@ import type { PriceHistoryResult } from "../types/price-history";
 import { LiveBarAccumulator } from "./live-bars";
 import type { ChartResolutionSupport, ManualChartResolution } from "./resolution";
 import type { DataProvider, MarketDataRequestContext } from "../types/data-provider";
-import type { Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
+import type { CorporateActionsData, EarningsAction, Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
+import type { EarningsHistoryPayload } from "../api-client/earnings";
 import type { FredSeriesLoadResult, FredSeriesRequest } from "../sources/gloomberb-cloud/fred-series";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
 import { publicTickerKey } from "../utils/exchanges";
@@ -16,6 +17,8 @@ import type {
 export interface ChartResolveSources {
   dataProvider: DataProvider | null;
   loadFredSeries: (request: FredSeriesRequest) => Promise<FredSeriesLoadResult>;
+  /** Dated releases from the same history the earnings calendar reads. US listings only. */
+  loadEarningsHistory?: (symbol: string) => Promise<EarningsHistoryPayload>;
   now?: Date;
   /** Latest streamed quote per security identity, layered over snapshot data. */
   quoteOverrides?: ReadonlyMap<string, Quote>;
@@ -74,6 +77,9 @@ export interface LiveTailRequest {
 /** Raw source data retained while live quotes recompute the chart tail. */
 export class ChartResolveCache {
   readonly financialsByInstrument = new Map<string, Promise<TickerFinancials | null>>();
+  readonly earningsReleasesByInstrument = new Map<string, Promise<EarningsAction[]>>();
+  /** Each listing's cash distribution history, for the charts that draw total returns. */
+  readonly distributionsByInstrument = new Map<string, Promise<CorporateActionsData | null>>();
   readonly quoteMetadataByInstrument = new Map<string, Promise<QuoteMetadata | null>>();
   /** Each futures symbol's contract price unit, asked once per chart once known. */
   readonly futuresPriceUnits = new Map<string, Promise<string | null>>();

package/src/time-series/resolve.ts

@@ -23,7 +23,7 @@ import {
 import { aggregatePriceBars, futuresOpenMinuteOf, withBuiltBarSize } from "./bar-aggregation";
 import { TIME_RANGES, type TimeRange } from "./range";
 import type { DataProvider } from "../types/data-provider";
-import type { Quote, TickerFinancials } from "../types/financials";
+import type { CorporateActionsData, EarningsAction, Quote, TickerFinancials } from "../types/financials";
 import { mergeQuoteMetadata, quoteMetadataFromQuote, quoteMetadataMatchesTarget } from "../market-data/quotes/metadata";
 import type { FredSeriesRequest } from "../sources/gloomberb-cloud/fred-series";
 import { fredCreditCoverageNotice } from "./economic";
@@ -44,12 +44,14 @@ import { VALUATION_CURRENCY_WARNING_PREFIX } from "./valuation-currency";
 import { chartPriceHistoryIntegrityNotices } from "./market";
 import { maxStudyWarmupPoints, resolveStudies } from "./studies";
 import { clipSeriesToWindow } from "./alignment";
+import { totalReturnSeries } from "./total-return";
 import {
   bufferPriceComparison,
   clipPriceComparison,
   priceComparisonBoundsForSeries,
   priceComparisonSeriesIds,
   resolvePriceComparison,
+  totalReturnLevelsNotice,
 } from "./price-comparison";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
 import { chartSeriesSourceKey } from "../capabilities/chart-series";
@@ -266,6 +268,13 @@ export async function resolveChartSpecData(
   return result;
 }
 
+/** The price fields whose returns a distribution adds to. */
+function totalReturnFieldId(fieldId: string): boolean {
+  const canonical = getTimeSeriesField(fieldId)?.id ?? fieldId;
+  return canonical === "market.ohlcv" || canonical === "market.close" || canonical === "market.open"
+    || canonical === "market.high" || canonical === "market.low";
+}
+
 async function resolveChartSpecPass(
   spec: ChartSpec,
   sources: ChartResolveSources,
@@ -277,6 +286,7 @@ async function resolveChartSpecPass(
     && entry.source.kind === "security" && isFundamentalFieldId(entry.source.fieldId))
     ? [FINANCIAL_VINTAGE_NOTICE] : [];
   const priorityWarnings: string[] = [];
+  const coverageNotices: string[] = [];
   const delistings = new Map<string, { symbol: string; label: string; notice: string }>();
   const baseSeriesIds = new Set(spec.series.map((entry) => entry.id));
   const visibleSeriesIds = new Set(spec.series
@@ -300,9 +310,9 @@ async function resolveChartSpecPass(
     const fieldId = getTimeSeriesField(source.fieldId)?.id ?? source.fieldId;
     // Calendar-window research needs the same full source bundle as a period
     // count. The extended bundle also carries the estimate history behind the
-    // forward multiples; PEG alone has no historical series.
+    // forward multiples; daily PEG also needs consecutive trailing years.
     const statementHistory = /^(fundamental|valuation)\./.test(fieldId)
-      && fieldId !== "valuation.pegRatio"
+      && (fieldId !== "valuation.pegRatio" || source.period === "daily")
       ? "extended" as const : undefined;
     const key = `${instrumentKey(source)}|history:${statementHistory ?? "default"}`;
     let pending = cache.financialsByInstrument.get(key);
@@ -330,6 +340,53 @@ async function resolveChartSpecPass(
     }
     return pending;
   };
+  const loadEarningsReleases = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
+    const key = instrumentKey(source);
+    let pending = cache.earningsReleasesByInstrument.get(key);
+    if (!pending) {
+      pending = (async () => {
+        const [events, history] = await Promise.allSettled([
+          sources.dataProvider?.getCorporateActions?.(source.instrument.symbol, source.instrument.exchange, requestContext(source)),
+          isUsListingExchange(source.instrument.exchange) ? sources.loadEarningsHistory?.(source.instrument.symbol) : undefined,
+        ]);
+        const releases: EarningsAction[] = [];
+        if (history.status === "fulfilled") for (const report of history.value?.reports ?? []) {
+          if (report.dateStatus !== "reported") continue;
+          releases.push({ date: report.date, dateType: "announcement", dateStatus: "reported",
+            fiscalPeriod: report.fiscalPeriod ?? undefined, reportedAt: report.reportedAt ?? undefined,
+            time: report.timingSource !== "history" ? report.timing ?? undefined : undefined });
+        }
+        else logFailure("time-series-resolve", "Loading earnings release history failed")(history.reason);
+        if (events.status === "fulfilled") releases.push(...events.value?.earnings ?? []);
+        else logFailure("time-series-resolve", "Loading earnings release events failed")(events.reason);
+        if (events.status === "rejected" || history.status === "rejected") cache.earningsReleasesByInstrument.delete(key);
+        return releases;
+      })();
+      cache.earningsReleasesByInstrument.set(key, pending);
+      cache.revision += 1;
+    }
+    return pending;
+  };
+  // Total returns reinvest the cash a listing paid; each listing's history is read once per chart.
+  const loadDistributions = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
+    const key = instrumentKey(source);
+    let pending = cache.distributionsByInstrument.get(key);
+    if (!pending) {
+      pending = (async (): Promise<CorporateActionsData | null> => {
+        const read = sources.dataProvider?.getCorporateActions;
+        if (!read) return null;
+        try {
+          return await read.call(sources.dataProvider, source.instrument.symbol, source.instrument.exchange, requestContext(source));
+        } catch (error) {
+          cache.distributionsByInstrument.delete(key);
+          throw error;
+        }
+      })();
+      cache.distributionsByInstrument.set(key, pending);
+      cache.revision += 1;
+    }
+    return pending;
+  };
   const loadQuoteMetadata = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
     const key = instrumentKey(source);
     let pending = cache.quoteMetadataByInstrument.get(key);
@@ -496,8 +553,16 @@ async function resolveChartSpecPass(
     all = false,
   ) => {
     const support = await loadResolutionSupport(source, priceOnly);
-    const maxRange = getSupportMaxRange(support, initialResolution);
+    const dailyValuation = source.period === "daily" && source.fieldId.startsWith("valuation.");
+    const sourceResolution = dailyValuation ? "1d" : initialResolution;
+    const maxRange = getSupportMaxRange(support, sourceResolution);
     const ahead = movedWindow ? barsAhead(requestVisibleBounds, maxRange, referenceNow.getTime()) : 0;
+    // Bars ahead that reach the present end wherever the clock is on this pass.
+    // Such a window is named by its start and the present, so every pass shares
+    // one acquisition and the stale-copy refresh below keeps it current. Named
+    // by the clock, each live pass fetched and kept another copy of the history.
+    const toPresent = ahead > 0 && requestVisibleBounds.end !== null
+      && requestVisibleBounds.end + ahead >= referenceNow.getTime();
     const durationEnd = rangeDurationBounds(spec, initialCalculationBounds).end;
     const historyBounds = clampHistoryBoundsToSupport(
       ahead > 0 && initialCalculationBounds.end !== null
@@ -517,8 +582,8 @@ async function resolveChartSpecPass(
       explicitWindow: hasExplicitWindow,
       authoredWindow: hasExplicitWindow && !movedWindow,
       fallbackRange,
-      resolution: initialResolution,
-      allowProviderDefaultFallback: spec.viewport.resolution === "auto",
+      resolution: sourceResolution,
+      allowProviderDefaultFallback: !dailyValuation && spec.viewport.resolution === "auto",
       support,
       requiredWarmupPoints: maxStudyWarmupPoints(spec.studies),
       ...(extendedHoursFor(source, initialResolution) ? { historySession: "extended" as const } : {}),
@@ -531,7 +596,9 @@ async function resolveChartSpecPass(
       request.allowProviderDefaultFallback ? "auto" : "manual",
       isMarketFieldId(source.fieldId) ? source.period ?? "auto" : "auto",
       ...(request.explicitWindow
-        ? [request.bounds.start ?? "open", request.bounds.end ?? "open"]
+        ? toPresent
+          ? [initialCalculationBounds.start ?? "open", "present"]
+          : [request.bounds.start ?? "open", request.bounds.end ?? "open"]
         : []),
       // A moved view can chart retained bars that the same authored dates cannot.
       ...(request.explicitWindow && !request.authoredWindow && !request.allowProviderDefaultFallback ? ["moved"] : []),
@@ -774,7 +841,10 @@ async function resolveChartSpecPass(
         const result = baseEconomicSeries(seriesSpec, fred, index);
         const coverageNotice = fredCreditCoverageNotice(seriesSpec.source.seriesId, fred.data.info,
           requestVisibleBounds.start, fred.data.observations);
-        if (result && coverageNotice) priorityWarnings.push(`${result.label}: ${coverageNotice}`);
+        if (result && coverageNotice) {
+          priorityWarnings.push(`${result.label}: ${coverageNotice}`);
+          coverageNotices.push(`${result.label}: ${coverageNotice}`);
+        }
         const freshnessWarning = staleFredWarning(fred);
         if (result && freshnessWarning) priorityWarnings.push(`${result.label}: ${freshnessWarning}`);
         return result;
@@ -782,8 +852,9 @@ async function resolveChartSpecPass(
 
       const source = seriesSpec.source;
       const marketField = isMarketFieldId(source.fieldId);
+      const dailyValuation = source.period === "daily" && source.fieldId.startsWith("valuation.");
       const quoteDerivedValuation = valuationSeriesUsesLiveQuote(source.fieldId);
-      const historyPricedValuation = valuationSeriesUsesPriceHistory(source.fieldId);
+      const historyPricedValuation = valuationSeriesUsesPriceHistory(source.fieldId, source.period);
       // Forward P/E only prices a history when the bundle carries estimates;
       // otherwise the provider's single figure stands and history is not required.
       const forwardPE = getTimeSeriesField(source.fieldId)?.id === "valuation.forwardPE";
@@ -833,6 +904,10 @@ async function resolveChartSpecPass(
       let merged = financials ?? (history ? emptyFinancials() : null);
       if (merged && quoteOverride) merged = { ...merged, quote: latestQuote(merged.quote, quoteOverride) };
       if (!merged) throw new Error(`No financial data is available for ${instrumentLabel(source)}.`);
+      if (dailyValuation && source.fieldId !== "valuation.forwardPE" && source.fieldId !== "valuation.realizedNtmPE"
+        && merged.earningsReleases === undefined) {
+        merged = { ...merged, earningsReleases: await loadEarningsReleases(resolvedSource) };
+      }
       // Historical labels can retain listing facts after the live price is
       // unavailable. Reuse existing facts before requesting a price-free snapshot.
       const existingMetadata = merged.quoteMetadata && quoteMetadataMatchesTarget(merged.quoteMetadata, resolvedSource.instrument.symbol, resolvedSource.instrument.exchange)
@@ -883,17 +958,23 @@ async function resolveChartSpecPass(
       // Keep provider history separate from quote-extended display bars. A live
       // mark is not a daily closing observation, including on snapshot replay.
       const historical = history ? { ...merged, priceHistory: history.points } : merged;
-      sources.onSecurityData?.(resolvedSpec, history?.session || realizedVolInputs.has(seriesSpec.id) ? historical : sourceBars, history !== null);
+      sources.onSecurityData?.(resolvedSpec, dailyValuation || history?.session || realizedVolInputs.has(seriesSpec.id) ? historical : sourceBars, history !== null);
       const base = baseSecuritySeries(
         resolvedSpec,
-        merged,
+        dailyValuation ? historical : merged,
         index,
         history?.resolution,
         quoteMetadata,
         contractUnit,
       );
       if (!base) throw new Error(`Unknown field ${source.fieldId}.`);
-      const result = builtBars ? withBuiltBarSize(base, builtBars) : base;
+      let result = builtBars ? withBuiltBarSize(base, builtBars) : base;
+      if (spec.viewport.totalReturn === true && totalReturnFieldId(source.fieldId)) {
+        const outcome = await totalReturnSeries(result, () => loadDistributions(resolvedSource),
+          merged.quote?.currency || quoteMetadata?.currency, referenceNow);
+        result = outcome.series;
+        if (outcome.notice) warnings.push(`${instrumentLabel(resolvedSource)}: ${outcome.notice}`);
+      }
       if (marketField && history?.historyStart !== undefined && Number.isFinite(history.historyStart)) {
         result.historyStart = new Date(history.historyStart);
       }
@@ -909,7 +990,7 @@ async function resolveChartSpecPass(
         if (historicalResult) historicalPriceSeries.set(seriesSpec.id, historicalResult);
       }
       const reportedForwardPE = merged.fundamentals?.forwardPE;
-      if (source.fieldId === "valuation.forwardPE" && merged.epsEstimates) {
+      if (source.fieldId === "valuation.forwardPE" && merged.epsEstimates && !dailyValuation) {
         warnings.push(FORWARD_PE_BASIS_NOTICE);
       } else if (source.fieldId === "valuation.forwardPE" && reportedForwardPE != null
         && Number.isFinite(reportedForwardPE) && reportedForwardPE <= 0) {
@@ -918,7 +999,7 @@ async function resolveChartSpecPass(
       if (source.fieldId === "valuation.realizedNtmPE" && merged.epsEstimates) {
         warnings.push(REALIZED_NTM_PE_BASIS_NOTICE);
       }
-      if (isFundamentalFieldId(source.fieldId) && fundamentalSeriesUsesAvailabilityFallback(merged, source)) {
+      if (!dailyValuation && isFundamentalFieldId(source.fieldId) && fundamentalSeriesUsesAvailabilityFallback(merged, source)) {
         result.warning = [result.warning, "Publication dates are unavailable for some observations; period-end dates are used as a fallback."].filter(Boolean).join(" ");
       }
       return result;
@@ -943,9 +1024,24 @@ async function resolveChartSpecPass(
     ? latestSessionView(primaryRaw, rawSeries.filter((entry) => entry.observationKind === "market"),
       extendedHistories.has(primaryRaw?.id ?? ""), quoteReferences.get(primaryRaw?.id ?? ""))
     : null;
+  const dailyValuationView = spec.series.filter((entry) => entry.visible !== false);
+  const shortDailyValuation = !hasExplicitWindow && (spec.viewport.range === "1D" || spec.viewport.range === "1W")
+    && rawSeries.every(series => series.nativeFrequency === "daily")
+    && dailyValuationView.length > 0 && dailyValuationView.every(({ source }) => source.kind === "security"
+      && source.period === "daily" && source.fieldId.startsWith("valuation."));
+  const dailyTimes = shortDailyValuation ? [...new Set(rawSeries.flatMap((entry) => entry.points.map((point) => point.date.getTime())))]
+    .filter(Number.isFinite).sort((a, b) => a - b) : [];
+  const latestDaily = dailyTimes.at(-1);
+  // A daily multiple has no intraday observations. The day tab compares its
+  // last two closes; the week tab ends at the last close even on a weekend.
+  const dailyBounds = latestDaily === undefined ? null : {
+    start: spec.viewport.range === "1D" ? dailyTimes.at(-2) ?? latestDaily - CHART_RESOLUTION_STEP_MS["1d"]
+      : latestDaily - 7 * CHART_RESOLUTION_STEP_MS["1d"],
+    end: latestDaily,
+  };
   const bounds = hasExplicitWindow
     ? requestVisibleBounds
-    : sessionView?.bounds ?? (isDatasetChart(spec)
+    : dailyBounds ?? sessionView?.bounds ?? (isDatasetChart(spec)
       ? endAtNewestObservation(initialVisibleBounds, rawSeries)
       : followLatestMarketObservation(initialVisibleBounds, rawSeries));
   if (sessionView?.priorClose != null && primaryRaw?.transform === "raw"
@@ -1024,6 +1120,9 @@ async function resolveChartSpecPass(
     bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow ?? null,
   );
   if (priceComparison) warnings.push(priceComparison.notice);
+  // A raw-price chart of total returns is no comparison, and its levels say what they are instead.
+  const returnBasisNotice = priceComparison ? null : totalReturnLevelsNotice(spec, rawSeries);
+  if (returnBasisNotice) warnings.push(returnBasisNotice);
   warnings.push(...chartPriceHistoryIntegrityNotices(priceHistoryIntegrity));
   warnings.push(...financialPeriodCoverageWarnings(financialPeriodCoverage(spec, resolved)));
   const resolvedById = new Map(resolved.map((entry) => [entry.id, entry] as const));
@@ -1081,6 +1180,8 @@ async function resolveChartSpecPass(
     loading: false,
     errors,
     warnings: [...new Set([...priorityWarnings, ...warnings])],
+    ...(coverageNotices.length ? { coverageNotices: [...new Set(coverageNotices)] } : {}),
+    ...(returnBasisNotice ? { returnBasisNotice } : {}),
     ...(delistings.size ? { delistings: [...delistings.values()] } : {}),
     viewport,
     resolution,

package/src/time-series/series-presentation.ts

@@ -13,6 +13,8 @@ import {
   type PriceComparison,
 } from "./price-comparison";
 import { parsePublicTickerKey, publicTickerKey } from "../utils/exchanges";
+import { physicalQuantity } from "./price-units";
+import { isCurrencyCode } from "../utils/currency-pair";
 import type {
   ChartSeriesSpec,
   ChartSpec,
@@ -40,33 +42,65 @@ export function resolvePriceHistoryIntegrity(
   ];
 }
 
+/**
+ * What sets a price's scale beyond its currency: the physical quantity it
+ * counts ("gallon" for USD / gallon, "barrel" for USD/bbl), or "currency" for
+ * an FX rate (USD / EUR). Null for a bare currency, a share or a unit, which
+ * scale as any price in their currency does.
+ */
+function scaleQuantity(unit: string): string | null {
+  const slash = unit.indexOf("/");
+  if (slash < 0) return null;
+  const per = unit.slice(slash + 1).trim();
+  return physicalQuantity(per) ?? (/^[A-Z]{3}$/.test(per) && isCurrencyCode(per) ? "currency" : null);
+}
+
+/**
+ * Each series' axis: one a spec names, else the side whose series count the
+ * same unit. Prices in one currency per different physical quantities
+ * (heating oil USD / gallon beside Brent USD / barrel), or a price beside an
+ * FX rate, scale on axes of their own; per-share and per-unit prices, and FX
+ * rates quoted in one currency, share one as any prices in that currency do.
+ */
 export function assignAxes(
   series: ResolvedSeries[],
   specs: readonly { id: string; axis: ChartSeriesSpec["axis"] }[],
   warnings: string[],
 ): ResolvedSeries[] {
+  type AxisUnit = { group: string; quantity: string | null };
   const requested = new Map(specs.map((spec) => [spec.id, spec.axis] as const));
-  const groupsByPanel = new Map<string, Partial<Record<"left" | "right", string>>>();
+  const groupsByPanel = new Map<string, Partial<Record<"left" | "right", AxisUnit>>>();
   return series.map((entry) => {
     const groups = groupsByPanel.get(entry.panelId) ?? {};
     groupsByPanel.set(entry.panelId, groups);
+    const quantity = scaleQuantity(entry.unit);
+    const sameGroup = (side: "left" | "right") => groups[side]?.group === entry.unitGroup;
+    const fits = (side: "left" | "right") => {
+      const held = groups[side];
+      return sameGroup(side) && (!held!.quantity || !quantity || held!.quantity === quantity);
+    };
     const preferred = requested.get(entry.id);
     let axis: "left" | "right";
     if (preferred === "left" || preferred === "right") {
       axis = preferred;
-    } else if (groups.left === entry.unitGroup) {
+    } else if (fits("left")) {
       axis = "left";
-    } else if (groups.right === entry.unitGroup) {
+    } else if (fits("right")) {
       axis = "right";
     } else if (!groups.left) {
       axis = "left";
-    } else {
+    } else if (!groups.right || !sameGroup("left")) {
       axis = "right";
+    } else {
+      // Both axes taken: a third quantity in the same currency shares as it would without them.
+      axis = "left";
     }
-    if (groups[axis] && groups[axis] !== entry.unitGroup) {
+    const held = groups[axis];
+    if (held && held.group !== entry.unitGroup) {
       warnings.push(`${entry.label} shares the ${axis} axis with a different unit; choose an explicit panel for independent scaling.`);
     }
-    groups[axis] ??= entry.unitGroup;
+    if (!held) groups[axis] = { group: entry.unitGroup, quantity };
+    else if (!held.quantity && quantity && fits(axis)) held.quantity = quantity;
     return { ...entry, axis };
   });
 }

package/src/time-series/session-bar.ts

@@ -136,3 +136,14 @@ export function withSessionBar(
   }
   return points;
 }
+
+/**
+ * The daily bars `history` shows as final, which alerts on a daily close read
+ * too: the bars as served, less the bar of a session still trading
+ * (withSessionBar, which `history` rebuilds from the quote and marks partial)
+ * and any bar the source marks partial. A close `history` prints without
+ * `partial` is final here, and one it prints with it is not.
+ */
+export function finalDailyBars(points: PricePoint[], options: SessionBarOptions): PricePoint[] {
+  return withSessionBar(points, null, options).filter((point) => !point.partial);
+}

package/src/time-series/spec.ts

@@ -37,7 +37,7 @@ import { isLeverageFactor } from "./leverage";
 const RANGE_SET = new Set<TimeRange>(TIME_RANGES);
 const PERIODS = new Set<SeriesPeriod>(["auto", "daily", "weekly", "monthly", "quarterly", "annual", "ttm"]);
 // `band` only stays on a capability series: a field's styles and an economic series' leave it out.
-const STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points", "candles", "ohlc", "hlc", "band"]);
+const STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points", "candles", "hollow", "heikin-ashi", "ohlc", "hlc", "band"]);
 const ECONOMIC_STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points"]);
 const TRANSFORMS = new Set<SeriesTransform>(["raw", "percent", "index100", "yoy", "qoq", "log"]);
 const AXES = new Set<SeriesAxis>(["auto", "left", "right"]);
@@ -71,7 +71,7 @@ export function isDatasetChart(spec: Pick<ChartSpec, "series">): boolean {
 }
 
 export function isOhlcSeriesStyle(style: SeriesStyle): boolean {
-  return style === "candles" || style === "ohlc" || style === "hlc";
+  return style === "candles" || style === "hollow" || style === "heikin-ashi" || style === "ohlc" || style === "hlc";
 }
 
 export function coerceSeriesTransformForStyle(
@@ -333,6 +333,7 @@ export function normalizeChartSpec(value: unknown, fallback: ChartSpec = DEFAULT
         ? Math.min(10_000, Math.floor(viewport.maxPoints))
         : undefined,
       ...(viewport?.extendedHours === true ? { extendedHours: true } : {}),
+      ...(viewport?.totalReturn === true ? { totalReturn: true } : {}),
     },
     panels,
     series,
@@ -448,7 +449,8 @@ export function validateChartSpec(spec: ChartSpec): ChartSpecValidationResult {
           ));
         }
         if ((definition.id.startsWith("fundamental.") || definition.id.startsWith("valuation."))
-          && (entry.source.period === "daily" || entry.source.period === "weekly" || entry.source.period === "monthly")) {
+          && ((entry.source.period === "daily" && !definition.id.startsWith("valuation."))
+            || entry.source.period === "weekly" || entry.source.period === "monthly")) {
           errors.push(issue(`${path}.source.period`, "unsupported-period", "Financial fields support automatic, quarterly, annual, or TTM periods."));
         }
         const groups = unitGroupsByPanel.get(entry.panelId) ?? new Set<string>();