gloomberb 0.18.4 → 0.19.0

package/src/plugins/builtin/chart-composer/editor.tsx

@@ -50,6 +50,7 @@ export function SeriesEditorDialog({ dialogId, resolve, initialSpec }: SeriesEdi
     quickAddItems,
     quickAddLoading,
     quickAddError,
+    retryQuickAdd,
     quickAddQuery,
     quickAddRef,
     quickAddSelection,
@@ -123,7 +124,7 @@ export function SeriesEditorDialog({ dialogId, resolve, initialSpec }: SeriesEdi
           onBlur={deactivateQuickAdd}
         />
 
-        {quickAddActive && quickAddQuery.trim() && (
+        {(quickAddActive || quickAddError) && quickAddQuery.trim() && (
           quickAddItems.length > 0 ? (
             <Box width={contentWidth} overflow="hidden">
               <ListView
@@ -138,13 +139,14 @@ export function SeriesEditorDialog({ dialogId, resolve, initialSpec }: SeriesEdi
                 onActivate={(_, index) => { beginQuickAdd(); addCatalogSuggestion(quickAddSuggestions[index]); }}
               />
             </Box>
-          ) : !quickAddLoading && quickAddError ? (
-            <EmptyState title={quickAddError} status="error" />
-          ) : (
+          ) : !quickAddError ? (
             <Text fg={colors.textMuted}>
               {quickAddLoading ? "Searching instruments…" : "No matching security or metric."}
             </Text>
-          )
+          ) : null
+        )}
+        {quickAddQuery.trim() && quickAddError && (
+          <EmptyState title={quickAddError} status="error" retry={{ onRetry: () => { beginQuickAdd(); return retryQuickAdd(); } }} />
         )}
 
         {items.length > 0 ? (

package/src/plugins/builtin/chart-composer/formula.ts

@@ -1,23 +1,29 @@
 import { currencyPairSpelling } from "../../../utils/currency-pair";
 import { dashedCoinPair } from "../../../utils/crypto-pair";
-import { GALLONS_PER_BARREL } from "../../../time-series/price-units";
+import { GALLONS_PER_BARREL, isBarrelsPerTonne } from "../../../time-series/price-units";
 import { MAX_CHART_COMPOSER_SERIES } from "./chart-spec";
 import { parseSeriesExpression, resolveChartFieldAlias, type ParsedSeriesExpression } from "./series-expression";
 import { getTimeSeriesField } from "../../../time-series/field-catalog";
 
 /**
  * Series formulas: a sum of series each times a number, the whole optionally
- * in brackets over a number.
+ * in brackets over or times numbers and series.
  *
  *   42*HO=F - CL=F                       heating-oil crack, USD per barrel
  *   HO=F*42 - BZ=F                       a multiplier on either side
  *   (2*42*RB=F + 42*HO=F - 3*CL=F)/3     3:2:1 crack, per barrel of crude
+ *   (42*HO=F - BZ=F)/EURUSD=X            the crack in EUR per barrel
+ *   7.45*42*HO=F - 7.45*BZ=F             a gasoil-style crack per tonne
  *
  * A literal 42 on a series is the 42 gallons of a barrel: it makes a price per
- * gallon a price per barrel. Any other number is a count and keeps the unit.
+ * gallon a price per barrel. A literal 7.45 or 8.45 is the barrels in a tonne
+ * of gasoil or gasoline: it makes a price per barrel a price per tonne. Any
+ * other number is a count and keeps the unit. A series the whole formula is
+ * divided or multiplied by changes its unit as the arithmetic does: over
+ * EURUSD=X (USD per EUR), dollars are euros.
  *
  * Grammar, no other precedence to learn:
- *   formula := sum | "(" sum ")" [ "/" number ]
+ *   formula := sum | "(" sum ")" { ( "/" | "*" ) factor }
  *   sum     := [ "+" | "-" ] term { ( "+" | "-" ) term }
  *   term    := factor { ( "*" | "×" ) factor }     with exactly one series
  *   factor  := number | series
@@ -29,17 +35,30 @@ interface FormulaLeg {
   weight: number;
   /** The leg was multiplied by a literal 42: the gallons in a barrel. */
   perBarrel: boolean;
+  /** The barrels in a tonne the leg was multiplied by (7.45 or 8.45), or null. */
+  perTonne: number | null;
   /** The leg as written: `HO=F`. */
   text: string;
 }
 
+/** A series the whole formula is multiplied (power 1) or divided (-1) by. */
+interface FormulaFactor {
+  series: ParsedSeriesExpression;
+  power: 1 | -1;
+  /** The series as written: `EURUSD=X`. */
+  text: string;
+}
+
 export interface ParsedFormula {
   legs: FormulaLeg[];
   /** What the whole sum is divided by; 1 when it is not. */
   divisor: number;
+  /** The series the whole sum is then multiplied or divided by, in the order written. */
+  factors: FormulaFactor[];
 }
 
 const EXAMPLE = "(2*42*RB=F + 42*HO=F - 3*CL=F)/3";
+const SCALED_EXAMPLE = "(42*HO=F - BZ=F)/EURUSD=X";
 
 type Token =
   | { kind: "number"; value: number; text: string }
@@ -75,9 +94,20 @@ function minusIsOperator(atom: string, previous: Token | undefined, rest: string
   )));
 }
 
+/**
+ * After the formula's closing bracket every `/` divides, except inside a
+ * currency or coin pair written with one: `(...)/EUR/USD` is over EUR/USD.
+ */
+function slashIsPairSpelling(atom: string, rest: string): boolean {
+  const quote = rest.match(/^[^\s*×+()/]*/)![0];
+  const symbol = `${atom}/${quote.split(":")[0]}`;
+  return /^[A-Za-z]{3,}$/.test(atom) && !!quote && (!!currencyPairSpelling(symbol) || !!dashedCoinPair(symbol));
+}
+
 function tokenize(expression: string): Token[] {
   const tokens: Token[] = [];
   let atom = "";
+  let closed = false;
   const flush = () => {
     if (!atom) return;
     tokens.push(NUMBER.test(atom) ? { kind: "number", value: Number(atom), text: atom } : { kind: "atom", text: atom });
@@ -89,11 +119,14 @@ function tokenize(expression: string): Token[] {
       flush();
     } else if (char === "*" || char === "×" || char === "+" || char === "(" || char === ")") {
       flush();
+      if (char === ")") closed = true;
       tokens.push({ kind: char === "×" ? "*" : char, text: char });
     } else if (char === "-" && (minusIsOperator(atom, tokens.at(-1), expression.slice(index + 1)) || /\s/.test(expression[index - 1] ?? " "))) {
       flush();
       tokens.push({ kind: "-", text: char });
-    } else if (char === "/" && !atom && tokens.at(-1)?.kind === ")") {
+    } else if (char === "/" && (!atom || (closed && !slashIsPairSpelling(atom, expression.slice(index + 1))))) {
+      // A slash on its own divides; inside a word it is part of a pair (EUR/USD), until the brackets close.
+      flush();
       tokens.push({ kind: "/", text: char });
     } else {
       atom += char;
@@ -111,7 +144,7 @@ function fail(message: string): never {
 function legSeries(text: string): ParsedSeriesExpression {
   const symbol = text.split(":")[0]!;
   if (symbol.includes("/") && !currencyPairSpelling(symbol) && !dashedCoinPair(symbol)) {
-    fail(`"${text}" divides inside the formula. Divide the whole formula by a number in brackets, as in ${EXAMPLE}; chart a ratio of two series as A / B on its own.`);
+    fail(`"${text}" divides inside the formula. Divide the whole formula in brackets by a number or a series, as in ${SCALED_EXAMPLE}; chart a ratio of two series as A / B on its own.`);
   }
   return parseSeriesExpression(text)
     ?? fail(`"${text}" is not a series. Use SYMBOL, SYMBOL:field, FUT:code, UST:maturity, FRED:series, GEO:series or CAP:capability-id:series-id.`);
@@ -143,7 +176,7 @@ export function parseFormulaExpression(expression: string): ParsedFormula | null
   const closes = tokens.filter((token) => token.kind === ")").length;
   if (opens !== closes) fail(`The brackets in "${trimmed}" do not pair up.`);
   if (opens > 1 || (opens === 1 && !bracketed)) {
-    fail(`Brackets go around the whole formula only, before an optional divisor: ${EXAMPLE}.`);
+    fail(`Brackets go around the whole formula only, then divide or multiply it: ${EXAMPLE}, ${SCALED_EXAMPLE}.`);
   }
 
   const legs: FormulaLeg[] = [];
@@ -158,6 +191,7 @@ export function parseFormulaExpression(expression: string): ParsedFormula | null
     // One term: numbers and exactly one series, multiplied.
     let weight = sign;
     let perBarrel = false;
+    let perTonne: number | null = null;
     const factors: Token[] = [];
     for (;;) {
       const factor = take();
@@ -171,6 +205,7 @@ export function parseFormulaExpression(expression: string): ParsedFormula | null
       if (factor.kind === "number") {
         if (factor.value === 0) fail("A multiplier of 0 removes its series; leave the term out instead.");
         if (factor.value === GALLONS_PER_BARREL && !perBarrel) perBarrel = true;
+        else if (isBarrelsPerTonne(factor.value) && perTonne === null) perTonne = factor.value;
         weight *= factor.value;
       }
       if (peek()?.kind !== "*") break;
@@ -189,14 +224,14 @@ export function parseFormulaExpression(expression: string): ParsedFormula | null
     if (legs.some((leg) => leg.text.toUpperCase() === text.toUpperCase())) {
       fail(`${text} appears twice. Write it once with its combined multiplier, such as 2*${text}.`);
     }
-    legs.push({ series: parsed, weight, perBarrel, text });
+    legs.push({ series: parsed, weight, perBarrel, perTonne, text });
     expectTerm = false;
 
     const next = peek();
     if (!next || next.kind === ")") break;
     if (next.kind !== "+" && next.kind !== "-") {
       fail(next.kind === "/"
-        ? `Divide the whole formula in brackets by a number, as in ${EXAMPLE}.`
+        ? `Divide the whole formula in brackets by a number or a series, as in ${SCALED_EXAMPLE}.`
         : `Expected + or - after ${written}, not "${next.text}".`);
     }
     take();
@@ -208,26 +243,44 @@ export function parseFormulaExpression(expression: string): ParsedFormula | null
   }
 
   let divisor = 1;
+  const scaleFactors: FormulaFactor[] = [];
   if (bracketed) {
     if (take()?.kind !== ")") fail(`The brackets in "${trimmed}" do not pair up.`);
-    if (peek()?.kind === "/") {
-      take();
+    while (peek()?.kind === "/" || peek()?.kind === "*") {
+      const divides = take()!.kind === "/";
       const value = take();
-      if (!value || value.kind !== "number") {
-        fail(`Divide the whole formula by a number, such as /3${value ? `, not ${value.text}` : ""}.`);
+      if (!value || (value.kind !== "number" && value.kind !== "atom")) {
+        fail(`${divides ? "Divide" : "Multiply"} the whole formula by a number or a series, such as ${divides ? "/3 or /EURUSD=X" : "*7.45 or *EURUSD=X"}${value ? `, not ${value.text}` : ""}.`);
+      }
+      if (value.kind === "number") {
+        if (value.value === 0) fail(divides ? "A formula cannot be divided by 0." : "A multiplier of 0 removes the formula; leave it out instead.");
+        if (divides) {
+          divisor *= value.value;
+        } else {
+          // A number times the whole sum multiplies each leg, converting its unit as it would there.
+          for (const leg of legs) {
+            if (value.value === GALLONS_PER_BARREL && !leg.perBarrel) leg.perBarrel = true;
+            else if (isBarrelsPerTonne(value.value) && leg.perTonne === null) leg.perTonne = value.value;
+            leg.weight *= value.value;
+          }
+        }
+        continue;
+      }
+      const text = value.text;
+      if ([...legs, ...scaleFactors].some((entry) => entry.text.toUpperCase() === text.toUpperCase())) {
+        fail(`${text} appears twice in the formula. Use each series once.`);
       }
-      if (value.value === 0) fail("A formula cannot be divided by 0.");
-      divisor = value.value;
+      scaleFactors.push({ series: legSeries(text), power: divides ? -1 : 1, text });
     }
   }
   const rest = tokens.slice(position);
   if (rest.length > 0) {
     fail(rest[0]!.kind === "/" || rest[0]!.kind === "*"
-      ? `Divide the whole formula in brackets by a number, as in ${EXAMPLE}.`
+      ? `Divide or multiply the whole formula in brackets, as in ${EXAMPLE} or ${SCALED_EXAMPLE}.`
       : `Unexpected "${rest.map((token) => token.text).join(" ")}" after the formula.`);
   }
-  if (legs.length > MAX_CHART_COMPOSER_SERIES) {
+  if (legs.length + scaleFactors.length > MAX_CHART_COMPOSER_SERIES) {
     fail(`A formula takes up to ${MAX_CHART_COMPOSER_SERIES} series.`);
   }
-  return { legs, divisor };
+  return { legs, divisor, factors: scaleFactors };
 }

package/src/plugins/builtin/chart-composer/headless-schema.ts

@@ -138,6 +138,12 @@ export const paneSchemas = {
         ],
         defaultValue: "percent",
       },
+      {
+        key: "totalReturn",
+        description: "Reinvest each cash distribution at its ex-date close, so the returns are total returns, not price returns.",
+        type: "boolean",
+        defaultValue: false,
+      },
       {
         key: "chartResolution",
         description: BAR_SIZE_DESCRIPTION,
@@ -151,7 +157,7 @@ export const paneSchemas = {
     discovery: {
       id: "price-comparison",
       aliases: ["stock comparison", "price performance comparison", "returns comparison", "compare stock prices"],
-      limitations: ["Compares closing-price changes in each listing's currency over shared observation dates. Cash distributions and FX conversion are excluded; these are not reinvested total returns."],
+      limitations: ["Compares closing-price changes in each listing's currency over shared observation dates. Cash distributions and FX conversion are excluded unless totalReturn is set, which reinvests each distribution at its ex-date close; FX conversion is never applied."],
       screenshotReadiness: "ready",
     },
   },
@@ -203,6 +209,13 @@ export const paneSchemas = {
   "valuation-graph-pane": {
     argument: { kind: "tickers" },
     options: [
+      {
+        key: "rangePreset",
+        description: "Chart history window.",
+        type: "enum",
+        aliases: ["range"],
+        values: HISTORY_RANGE_VALUES,
+      },
       {
         key: "metric",
         description: "Valuation metric to compare.",
@@ -219,9 +232,13 @@ export const paneSchemas = {
         // The same metric the GE template opens with in the app.
         defaultValue: "trailingPE",
       },
-      // Annual, as the GE template opens in the app.
-      FINANCIAL_PERIOD_OPTION,
-      FINANCIAL_PERIOD_COUNT_OPTION,
+      {
+        ...FINANCIAL_PERIOD_OPTION,
+        description: "Daily multiples, or one observation per reporting period.",
+        values: [{ value: "daily", aliases: ["d"] }, ...FINANCIAL_PERIOD_OPTION.values!, { value: "ttm" }],
+        defaultValue: "daily",
+      },
+      { ...FINANCIAL_PERIOD_COUNT_OPTION, description: "Keep only the latest N observations per ticker." },
     ],
     discovery: {
       id: "valuation-series",

package/src/plugins/builtin/chart-composer/headless.ts

@@ -37,7 +37,7 @@ import { futuresSessionOpenMinute } from "../../../market-data/market/trading-se
 import { cleanFloat32Price } from "../../../cli/history-rows";
 import { parseChartSpec } from "./chart-spec";
 import { paneSchemas } from "./headless-schema";
-import { barHistoryFreshness, REPORTED_DATA } from "../shared/report-freshness";
+import { barHistoryFreshness, DAILY_CLOSES, REPORTED_DATA } from "../shared/report-freshness";
 import type { BarPeriodToDate } from "../../../market-data/market/bar-period";
 import { closedHistoryBarDay, formingHistoryBar } from "../ticker-detail/data-panes/history-bars";
 import { inferSeriesFrequency } from "../../../series/csv";
@@ -151,6 +151,7 @@ export async function loadChartPaneModel(
     },
     resolveCapabilitySeries: headlessCapabilityResolver(context),
     loadFuturesPriceUnit: (symbol) => loadFuturesPriceUnit(symbol, (key) => loadFuturesContractTerms(key, context.apiClient)),
+    loadEarningsHistory: (symbol) => context.apiClient.getCloudEarningsHistory(symbol, 100),
     loadFredSeries: async (request) => ({
       data: await context.apiClient.getCloudFredSeries(request.seriesId, {
         startDate: request.startDate,
@@ -221,9 +222,14 @@ export async function loadChartPaneModel(
         kind, source.fieldId.split(".")[1]!, source.period === "quarterly" ? "quarterly" : "annual",
         source.instrument.symbol,
       ).map((row) => [row.date, row.growth])) : null;
+      // A formula or a converted price prints at its legs' decimals in text; JSON keeps every digit.
+      const { valueDecimals, ...reported } = series;
       return {
-        ...series,
+        ...reported,
         ...name ? { name } : {},
+        ...valueDecimals !== undefined ? { textDecimals: valueDecimals } : {},
+        // A company's reported total (revenue, market cap) reads as 63.33B in the report, as in the legend and the tables.
+        ...series.unitGroup.split(":")[0] === "currency-total" ? { textCompact: true } : {},
         derived: !ids.has(series.id),
         points: series.points.map((point) => ({
           ...point,
@@ -247,7 +253,7 @@ export async function loadChartPaneModel(
       ...(chart.priceHistoryIntegrity?.length ? { priceHistoryIntegrity: chart.priceHistoryIntegrity } : {}),
       ...(valuationPriceIssues.length ? { valuationPriceIssues } : {}),
       ...(periodCoverage.length ? { periodCoverage } : {}),
-      notices: [...chart.warnings.filter((warning) => warning === FINANCIAL_VINTAGE_NOTICE || warning === SEC_EPS_BASIS_NOTICE || warning === chart.priceComparison?.notice
+      notices: [...chart.coverageNotices ?? [], ...chart.returnBasisNotice ? [chart.returnBasisNotice] : [], ...chart.warnings.filter((warning) => warning === FINANCIAL_VINTAGE_NOTICE || warning === SEC_EPS_BASIS_NOTICE || warning === chart.priceComparison?.notice
         || chart.delistings?.some((delisting) => delisting.notice === warning)), ...integrityNotices],
       priceComparison: chart.priceComparison ?? null,
       summaries: chart.series.filter((series) => !series.profile).map((series) => ({ id: series.id, ...summarizeResolvedSeries(series) })),
@@ -346,6 +352,13 @@ function chartFreshness(
   // A leg that failed to load has no bars to date; the ones that loaded say what the chart is.
   const loaded = allSeries.filter((entry) => entry.points.length > 0);
   const series = loaded.length ? loaded : allSeries;
+  const visible = spec.series.filter((entry) => entry.visible !== false);
+  if (visible.length && series.every(entry => (entry as HeadlessSeries & Pick<ResolvedSeries, "nativeFrequency">).nativeFrequency === "daily")
+    && visible.every((entry) => entry.source.kind === "security"
+    && entry.source.period === "daily" && entry.source.fieldId.startsWith("valuation."))) {
+    const ends = series.flatMap((entry) => entry.points.at(-1)?.date ?? []).map((date) => new Date(date).toISOString().slice(0, 10)).sort();
+    return { ...DAILY_CLOSES, ...(ends.length ? { asOf: ends.at(-1)!, oldest: ends[0]! } : {}) };
+  }
   const resolutions = series.map((entry) => (entry as HeadlessSeries & { historyResolution?: string }).historyResolution);
   const dataset = isDatasetChart(spec);
   if (!series.length || resolutions.some((resolution) => !resolution)) {
@@ -712,6 +725,9 @@ export function chartHeadless(template: keyof typeof paneSchemas): HeadlessPaneD
         }, context.marketData) };
       }
       const model = await loadChartPaneModel(spec, context);
+      // A bare coin ticker charted as another listing (ETH, the Grayscale fund) says where the coin is, as `quote` does.
+      const coinNotes = (await Promise.all(listings.values())).flatMap((read) => read?.coinNote ?? []);
+      if (coinNotes.length) model.warnings = [...model.warnings ?? [], ...coinNotes];
       if (template === "graph-intraday-price-pane" && !intradayHistories.length && model.chart.viewport) {
         const { start, end } = model.chart.viewport;
         for (const { target, data } of [

package/src/plugins/builtin/chart-composer/index.tsx

@@ -453,7 +453,7 @@ const chartComposerTemplates: PaneTemplateDef[] = [
     prefix: "CMP",
     aliases: ["COMP", "TRA"],
     label: "Comparison Chart",
-    description: "Compare price returns over shared observation dates for two or more tickers. A leveraged or inverse fund gets its daily objective drawn from its index fund (3× daily QQQ beside TQQQ) and its decay against it.",
+    description: "Compare price returns over shared observation dates for two or more tickers, or total returns with distributions reinvested. A leveraged or inverse fund gets its daily objective drawn from its index fund (3× daily QQQ beside TQQQ) and its decay against it.",
     // Leveraged and inverse funds: the daily line and the decay come with the comparison.
     keywords: ["leveraged", "inverse", "decay", "daily-reset", "daily reset", "volatility decay"],
     argKind: "ticker-list",

package/src/plugins/builtin/chart-composer/pane.tsx

@@ -54,8 +54,10 @@ import {
 } from "../../../state/app/context";
 import { colors } from "../../../theme/colors";
 import { isUsListingExchange, parsePublicTickerKey, publicTickerKey } from "../../../utils/exchanges";
-import { isMarketFieldId } from "../../../time-series/field-catalog";
-import { isDatasetChart } from "../../../time-series/spec";
+import { getTimeSeriesField, isMarketFieldId } from "../../../time-series/field-catalog";
+import { isDatasetChart, isOhlcSeriesStyle } from "../../../time-series/spec";
+import { useThemeColors } from "../../../theme/theme-context";
+import { priceComparisonSeriesIds } from "../../../time-series/price-comparison";
 import { seriesMessageName, studyMessageName } from "../../../time-series/series-name";
 import { CHART_COMPOSER_PANE_ID } from "../../../types/config";
 import { useRemoteUiNode } from "../../../remote/semantic-tree";
@@ -117,6 +119,8 @@ import {
   CHART_BAR_SIZE_PRESETS,
   CHART_RANGES as RANGES,
   CHART_RESOLUTIONS,
+  CHART_CANDLE_COLOURS_SETTING_KEY,
+  chartCandleColours,
   chartStudyOptionsFor,
   chartStudyPeriodTitle,
   chartStudySettingLabel,
@@ -342,6 +346,14 @@ function ChartComposerSurface({
   // plausible time is dropped without pinning. This handle only sets the
   // pin; the chart it opens on is what shows and keeps it.
   const [pinnedMoment, setPinnedMoment] = usePaneSettingValue<unknown>(CHART_PINNED_MOMENT_SETTING_KEY, null);
+  const [candleColoursSetting] = usePaneSettingValue<unknown>(CHART_CANDLE_COLOURS_SETTING_KEY, null);
+  const gainColour = useThemeColors().positive;
+  // Rising candles in the gain colour; falling ones already take the loss colour.
+  const candleColour = useCallback((list: ResolvedSeries[]) => (
+    chartCandleColours(candleColoursSetting) === "change"
+      ? list.map((entry) => isOhlcSeriesStyle(entry.style) ? { ...entry, color: gainColour } : entry)
+      : list
+  ), [candleColoursSetting, gainColour]);
   const momentLink = useTabCursorLink(paneId ? `${paneId}:moment` : null, { viewer: false });
   useEffect(() => {
     if (pinnedMoment == null || !momentLink?.pin) return;
@@ -446,6 +458,14 @@ function ChartComposerSurface({
   const selectedPairStudies = getSelectedPairStudies(spec);
   const viewport = resolution.viewport;
   const baseSeriesIds = useMemo(() => new Set(spec.series.map((series) => series.id)), [spec.series]);
+  const rangeStatisticsSeriesId = spec.series.length === 1
+    && spec.series[0]!.source.kind === "security"
+    && spec.series[0]!.source.fieldId.startsWith("valuation.")
+    && spec.series[0]!.source.period === "daily"
+    && resolution.series.find(series => series.id === spec.series[0]!.id)?.nativeFrequency === "daily"
+    && spec.series[0]!.transform === "raw"
+    && spec.series[0]!.visible !== false
+    ? spec.series[0]!.id : undefined;
   // Hidden series are never loaded, so the resolver has nothing to report for
   // them. Without a placeholder they vanish from the legend entirely and the
   // only way back is the series dialog.
@@ -453,6 +473,12 @@ function ChartComposerSurface({
     // Each security series names its company once, beside its label: "AAPL Price · Apple".
     const named = new Set<string>();
     const resolved = (resolution.legendSeries ?? []).map((entry) => {
+      const authored = spec.series.find((series) => series.id === entry.id);
+      if (authored?.source.kind === "security" && authored.source.fieldId.startsWith("valuation.")) {
+        const field = getTimeSeriesField(authored.source.fieldId);
+        return { ...entry, label: authored.label?.trim()
+          || `${authored.source.instrument.symbol} ${field?.shortLabel ?? "Multiple"}` };
+      }
       const name = nameSeries ? listings.names.get(entry.id) : undefined;
       const company = name ? shortCompanyName(name) : "";
       if (!company || named.has(company)) return entry;
@@ -461,9 +487,9 @@ function ChartComposerSurface({
     });
     const resolvedIds = new Set(resolved.map((entry) => entry.id));
     const missing = spec.series.filter((entry) => !resolvedIds.has(entry.id));
-    if (missing.length === 0) return named.size > 0 ? resolved : resolution.legendSeries;
+    if (missing.length === 0) return candleColour(resolved);
     const bySpecOrder = new Map(spec.series.map((entry, index) => [entry.id, index] as const));
-    return [
+    return candleColour([
       ...resolved,
       ...missing.map((entry): ResolvedSeries => ({
         id: entry.id,
@@ -481,15 +507,15 @@ function ChartComposerSurface({
         hidden: true,
         points: [],
       })),
-    ].sort((a, b) => (bySpecOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (bySpecOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
-  }, [listings.names, nameSeries, resolution.legendSeries, spec.series]);
+    ].sort((a, b) => (bySpecOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (bySpecOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER)));
+  }, [candleColour, listings.names, nameSeries, resolution.legendSeries, spec.series]);
   const plottedSeries = useMemo(
-    () => projectVisibleChartSeries(
+    () => candleColour(projectVisibleChartSeries(
       spec,
       resolution.bufferedSeries ?? resolution.series,
       resolution.legendSeries,
-    ),
-    [resolution.bufferedSeries, resolution.legendSeries, resolution.series, spec],
+    )),
+    [candleColour, resolution.bufferedSeries, resolution.legendSeries, resolution.series, spec],
   );
   const { notify } = usePluginAppActions();
   const { runtime } = usePluginRenderContext();
@@ -1176,6 +1202,22 @@ function ChartComposerSurface({
     }]
     : [];
 
+  // Returns of two or more prices compare as price returns; the toggle reinvests their cash distributions.
+  const totalReturnOn = spec.viewport.totalReturn === true;
+  const totalReturnFilters = totalReturnOn || priceComparisonSeriesIds(spec) !== null
+    ? [{
+      id: "total-return",
+      kind: "toggle" as const,
+      label: "Total return",
+      short: "Total ret",
+      value: totalReturnOn,
+      onChange: (value: boolean) => {
+        const { totalReturn: _previous, ...viewport } = specRef.current.viewport;
+        updateSpec({ ...specRef.current, viewport: value ? { ...viewport, totalReturn: true } : viewport });
+      },
+    }]
+    : [];
+
   // A company that reports no quarterly figures says so, and where its annual ones are.
   const unreported = resolution.legendSeries?.find((entry) => entry.unreportedPeriod && entry.points.length === 0);
   const emptyMessage = spec.series.length === 0
@@ -1202,6 +1244,7 @@ function ChartComposerSurface({
             onChange: (value: string) => setRange(value as TimeRange) },
           ...genericFilters,
           ...extendedHoursFilters,
+          ...totalReturnFilters,
         ]}
         view={resolutionOptions.length > 1 ? {
           value: spec.viewport.resolution,
@@ -1272,6 +1315,7 @@ function ChartComposerSurface({
           timePick={timePick}
           pricePick={pricePick}
           levels={chartLevels}
+          rangeStatisticsSeriesId={rangeStatisticsSeriesId}
           emptyMessage={emptyMessage}
           emptyDetail={emptyDetail}
           legendAccessory={(

package/src/plugins/builtin/chart-composer/presets.ts

@@ -6,7 +6,7 @@ import {
 } from "../../../time-series/types";
 import type { ChartResolution, TimeRange } from "../../../components/chart/core/types";
 import { MAX_CHART_COMPOSER_SERIES } from "./chart-spec";
-import { appendChartSeries, appendPlacedSeries, buildCustomSeries, buildSeriesSpec, panelsForSeries } from "./chart-spec-edit";
+import { appendChartSeries, appendPlacedSeries, buildCustomSeries, buildSeriesSpec, nextGeneratedPanelId, panelsForSeries } from "./chart-spec-edit";
 import { currencyPairSpelling } from "../../../utils/currency-pair";
 import { dashedCoinPair } from "../../../utils/crypto-pair";
 import {
@@ -82,21 +82,51 @@ function placeFormulaLeg(formula: ParsedFormula, index: number, series: ChartSer
   return mixed && series.panelId === "main" && !formula.legs[index]!.perBarrel ? { ...series, axis: "right" } : series;
 }
 
-/** The study that weighs a formula's legs, charted as the given series, in the Formula panel. */
+/**
+ * A series the formula is divided or multiplied by (an FX rate) counts
+ * something else again: it is drawn in a panel of its own, not on the legs' axes.
+ */
+function placeFormulaFactor(spec: Pick<ChartSpec, "panels" | "series" | "studies">, series: ChartSeriesSpec): ChartSeriesSpec {
+  return { ...series, panelId: nextGeneratedPanelId(spec), axis: "auto" };
+}
+
+/** A factor's panel is shorter than a series panel, so the legs and the formula keep their room. */
+const FACTOR_PANEL_HEIGHT = 0.2;
+
+/** The panels with each new factor's last and short: the formula reads right under its legs. */
+function withFactorPanels(panels: ChartSpec["panels"], factors: readonly ChartSeriesSpec[]): ChartSpec["panels"] {
+  const ids = new Set(factors.map((series) => series.panelId));
+  return [
+    ...panels.filter((panel) => !ids.has(panel.id)),
+    ...panels.filter((panel) => ids.has(panel.id)).map((panel) => ({ ...panel, height: FACTOR_PANEL_HEIGHT })),
+  ];
+}
+
+/** The study that weighs a formula's legs and scales the sum, charted as the given series, in the Formula panel. */
 function formulaStudy(formula: ParsedFormula, inputSeriesIds: string[]): ChartStudySpec {
   const parameters: ChartStudySpec["parameters"] = { divisor: formula.divisor };
   formula.legs.forEach((leg, index) => {
     parameters[`weight${index + 1}`] = leg.weight;
     if (leg.perBarrel) parameters[`perBarrel${index + 1}`] = 1;
+    if (leg.perTonne) parameters[`perTonne${index + 1}`] = leg.perTonne;
+  });
+  formula.factors.forEach((factor, index) => {
+    parameters[`power${formula.legs.length + index + 1}`] = factor.power;
   });
   return { id: FORMULA_STUDY_ID, kind: "formula", inputSeriesIds, parameters, panelId: "formula", axis: "auto" };
 }
 
-/** A formula's legs as series, with the study that sums them in the Formula panel. */
+/** A formula's legs and factors as series, with the study that sums them in the Formula panel. */
 function formulaChartPreset(formula: ParsedFormula): ChartSpec {
-  const series = buildCustomSeries(formula.legs.map((leg) => leg.series))
-    .map((entry, index) => placeFormulaLeg(formula, index, entry));
-  return chartSpec(series, { studies: [formulaStudy(formula, series.map((entry) => entry.id))] });
+  const legs = buildCustomSeries([...formula.legs, ...formula.factors].map((entry) => entry.series));
+  const series: ChartSeriesSpec[] = [];
+  legs.forEach((entry, index) => {
+    series.push(index < formula.legs.length
+      ? placeFormulaLeg(formula, index, entry)
+      : placeFormulaFactor({ panels: [], series, studies: [] }, entry));
+  });
+  const spec = chartSpec(series, { studies: [formulaStudy(formula, series.map((entry) => entry.id))] });
+  return { ...spec, panels: withFactorPanels(spec.panels, series.slice(formula.legs.length)) };
 }
 
 /**
@@ -107,17 +137,22 @@ function appendChartFormula(spec: ChartSpec, expression: string): { spec: ChartS
   const formula = parseFormulaExpression(expression);
   if (!formula) throw new Error(`"${expression}" is not a formula.`);
   const key = (series: ChartSeriesSpec) => formatSeriesExpression(series).toLowerCase();
-  const legs = formula.legs.map((leg) => key(buildSeriesSpec(leg.series, 0)));
+  const terms = [...formula.legs, ...formula.factors];
+  const legs = terms.map((leg) => key(buildSeriesSpec(leg.series, 0)));
   const missing = legs.filter((leg) => !spec.series.some((series) => key(series) === leg)).length;
   if (spec.series.length + missing > MAX_CHART_COMPOSER_SERIES) {
     throw new Error(`Charts support up to ${MAX_CHART_COMPOSER_SERIES} base series.`);
   }
   let next: ChartSpec = { ...spec, studies: spec.studies.filter((study) => study.id !== FORMULA_STUDY_ID) };
-  const inputs = formula.legs.map((leg, index) => {
+  const placedFactors: ChartSeriesSpec[] = [];
+  const inputs = terms.map((leg, index) => {
     const charted = next.series.find((series) => key(series) === legs[index]);
     if (charted) return charted;
     const appended = appendChartSeries(next, leg.series);
-    const placed = placeFormulaLeg(formula, index, appended.series);
+    const placed = index < formula.legs.length
+      ? placeFormulaLeg(formula, index, appended.series)
+      : placeFormulaFactor(next, appended.series);
+    if (index >= formula.legs.length) placedFactors.push(placed);
     next = { ...appended.spec, series: appended.spec.series.map((series) => series.id === placed.id ? placed : series) };
     return placed;
   });
@@ -127,7 +162,10 @@ function appendChartFormula(spec: ChartSpec, expression: string): { spec: ChartS
     spec: {
       ...next,
       studies,
-      panels: [...next.panels, ...panelsForSeries(next.series, studies).filter((panel) => !known.has(panel.id))],
+      panels: withFactorPanels(
+        [...next.panels, ...panelsForSeries(next.series, studies).filter((panel) => !known.has(panel.id))],
+        placedFactors,
+      ),
     },
     series: inputs.at(-1)!,
   };
@@ -275,11 +313,8 @@ export function buildValuationChartPreset(
     const series = buildSeriesSpec(
       { kind: "security", ...instrument, fieldId: resolvedField },
       index,
-      { style: normalized.length === 1 ? "line" : "columns", axis: "left" },
+      { style: "line", axis: "left" },
     );
-    // Fiscal years: most US filers report no Q4 EPS, which charts do not
-    // reconstruct, so a quarterly trailing multiple has only its latest few
-    // quarters. Quarterly is the series' Period control away.
-    return series.source.kind === "security" ? { ...series, source: { ...series.source, period: "annual" } } : series;
+    return series.source.kind === "security" ? { ...series, source: { ...series.source, period: "daily" } } : series;
   }));
 }