gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/credit-documents/headless.ts

@@ -1,5 +1,6 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import { fetchCreditDocuments, fetchCreditInstrument, fetchCreditScreen } from "./client";
+import type { CreditDocumentsPayload } from "../../../api-client/credit-documents";
+import { creditIssuerSymbol, fetchCreditDocuments, fetchCreditInstrument, fetchCreditScreen } from "./client";
 import { CREDIT_TABS } from "./model";
 import { SEC_FILINGS } from "../shared/report-freshness";
 
@@ -8,8 +9,8 @@ export const creditHeadless: HeadlessPaneDefinition<"bundle"> = {
   freshness: SEC_FILINGS,
   argument: { kind: "ticker", description: "Issuer ticker, including exchange-qualified global symbols.", placeholder: "ticker" },
   discovery: { aliases: ["CRDOC"], dataRequirements: ["Gloom Cloud credit-document evidence"], limitations: [
-    "Pro dataset; free accounts see a limited preview", "SEC credit documents with global issuer identifiers; other jurisdictions depend on connected sources",
-    "Undisclosed terms remain unavailable", "Headroom requires exact covenant definitions and supported reported financials", "Amounts retain their native currency",
+    "Pro dataset; free accounts see a limited preview.", "SEC credit documents with global issuer identifiers; other jurisdictions depend on connected sources.",
+    "Undisclosed terms remain unavailable.", "Headroom requires exact covenant definitions and supported reported financials.", "Amounts retain their native currency.",
   ] },
   options: [
     { key: "tab", type: "enum", settingKey: "tab", defaultValue: "capital", values: CREDIT_TABS.map(({ value }) => ({ value })), description: "Capital structure, covenants, maturity wall or global risk screen." },
@@ -28,6 +29,12 @@ export const creditHeadless: HeadlessPaneDefinition<"bundle"> = {
     }
     const data = await fetchCreditDocuments(args.symbols[0]!, ctx.apiClient);
     const instrument = args.options.instrument ? await fetchCreditInstrument(data.symbol, String(args.options.instrument), ctx.apiClient) : null;
+    const reason = instrument ? null : creditEmptyReason(data, args.symbols[0]!);
+    // Nothing on file says why once, instead of four empty sections.
+    if (reason) {
+      return { complete: false, errors: data.warnings, sections: [],
+        metadata: { symbol: data.symbol, issuer: data.issuer, asOf: data.asOf, access: data.access, lockedRows: data.lockedRows, status: data.status, reason, notices: [reason] } };
+    }
     return { complete: data.status === "available" && data.lockedRows === 0, errors: [...data.warnings, ...(data.lockedRows ? ["Full credit documents and history require Gloom Pro"] : [])],
       sections: instrument ? [{ title: instrument.name, rows: [{ ...instrument }] }, { title: "Current terms", rows: instrument.facts.map((row) => ({ ...row })) }, { title: "Amendment history", rows: (instrument.history ?? []).map((row) => ({ ...row })) }]
         : [{ title: "Capital structure", rows: data.instruments.map((row) => ({ ...row })) }, { title: "Covenants", rows: data.covenants.map((row) => ({ ...row })) }, { title: "Maturity wall", rows: data.maturities.map((row) => ({ ...row })) }, { title: "Change of control", rows: data.changeOfControl.map((row) => ({ ...row })) }],
@@ -35,6 +42,29 @@ export const creditHeadless: HeadlessPaneDefinition<"bundle"> = {
   },
 };
 
+/** An issuer whose documents the catalog and the docs use as the example. */
+const CREDIT_EXAMPLE_SYMBOL = "FICO";
+
+/**
+ * Why an issuer's report has no rows at all, from the payload: no issuer on
+ * file for the symbol, or an issuer with no debt instrument read from its
+ * filings yet; with the command for an issuer that has documents. Null when
+ * any section has a row.
+ */
+export function creditEmptyReason(
+  data: Pick<CreditDocumentsPayload, "symbol" | "issuer" | "instruments" | "covenants" | "maturities" | "changeOfControl" | "lockedRows">,
+  requested: string,
+): string | null {
+  const rows = data.instruments.length + data.covenants.length + data.maturities.length + data.changeOfControl.length;
+  if (rows > 0 || data.lockedRows > 0) return null;
+  const symbol = requested.trim().toUpperCase();
+  const why = data.issuer
+    ? `No credit documents on file for ${data.issuer.name} (${symbol}): no debt instrument has been read from its filings yet.`
+    : `No credit documents on file for ${symbol}: it is not an issuer the credit-document set covers.`;
+  const example = creditIssuerSymbol(symbol) === CREDIT_EXAMPLE_SYMBOL ? "" : ` Try \`gloomberb fn CRDOC ${CREDIT_EXAMPLE_SYMBOL}\` for an issuer with documents.`;
+  return `${why}${example}`;
+}
+
 export const covenantsHeadless: HeadlessPaneDefinition<"bundle"> = {
   ...creditHeadless,
   discovery: { ...creditHeadless.discovery, aliases: ["COVN"] },

package/src/plugins/builtin/credit-documents/pane.tsx

@@ -12,6 +12,7 @@ import type { PaneProps } from "../../../types/plugin";
 import { Box, Text, useUiCapabilities } from "../../../ui";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { useOpenDescription } from "../shared/open-description";
 import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedCredit, creditIssuerSymbol, CREDIT_UNAVAILABLE, fetchCreditScreen, loadCredit, validateCreditDocuments } from "./client";
@@ -34,6 +35,7 @@ export function CreditDocumentsPane(props: PaneProps) {
 function CreditView({ symbol, width, height, focused, accessKey, needsVerification }: PaneProps & { symbol: string | null; accessKey: string; needsVerification: boolean }) {
   const colors = useThemeColors(), desktop = !!useUiCapabilities().nativePaneChrome;
   const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const openUpgrade = useCloudUpgradeAction("crdoc");
   const [openingTab] = usePaneSettingValue("tab", "capital");
   const [savedTab, setTab] = usePluginPaneState<string>("credit:tab", openingTab);
@@ -103,7 +105,7 @@ function CreditView({ symbol, width, height, focused, accessKey, needsVerificati
   const target = activeSymbol ?? symbol ?? "";
   const allHints: PaneHint[] = [
     ...(symbol ? [
-      { id: "credit:des", key: "d", label: "es", title: "Description (DES)", onPress: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol: target }) },
+      { id: "credit:des", key: "d", label: "es", title: "Description (DES)", onPress: () => openDescription(target) },
       { id: "credit:fa", key: "f", label: "a", title: "Financial analysis (FA)", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: target }) },
       { id: "credit:graph", key: "g", label: "raph", title: "Price chart (G)", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: target }) },
       { id: "credit:ddis", key: "m", label: "aturities", title: "DDIS maturity schedule", onPress: () => createPaneFromTemplate("debt-maturities-pane", { symbol: target }) },

package/src/plugins/builtin/crypto-board/headless.ts

@@ -2,7 +2,7 @@ import type { CryptoAssetKind } from "../../../api-client/crypto-markets";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { formatCompact } from "../../../utils/format";
 import { fetchCryptoMarkets } from "./client";
-import { buildCryptoRows, formatCryptoPercent } from "./model";
+import { buildCryptoRows, CRYPTO_BOARD_FRESHNESS, formatCryptoPercent } from "./model";
 
 const NO_QUOTES = new Map();
 const number = (value: unknown) => (typeof value === "number" ? value : null);
@@ -41,8 +41,7 @@ export const cryptoBoardHeadless: HeadlessPaneDefinition<"rows"> = {
     dataRequirements: ["Gloom Cloud crypto markets"],
   },
   // A board snapshot refreshed every few minutes; the pane streams, the report does not.
-  // Crypto trades around the clock, so a snapshot an hour old has stopped refreshing.
-  freshness: { status: "delayed", maxAgeMinutes: 60 },
+  freshness: { status: "delayed", ...CRYPTO_BOARD_FRESHNESS },
   async load(args, ctx) {
     const kind = args.options.list === "stablecoin" ? "stablecoin" : "coin" satisfies CryptoAssetKind;
     const data = await fetchCryptoMarkets(ctx.apiClient);

package/src/plugins/builtin/crypto-board/index.tsx

@@ -3,8 +3,10 @@ import { LIVE_STREAMING_QUICK_SETTING, withLiveStreamingSetting } from "../../..
 import { cryptoMarketsCache } from "./client";
 import { cryptoBoardHeadless } from "./headless";
 import { CryptoBoardPane } from "./pane";
+import { CRYPTO_SERIES } from "./series";
 
 export const cryptoBoardModule: PluginModule = {
+  series: CRYPTO_SERIES,
   panes: [
     {
       id: "crypto-board",

package/src/plugins/builtin/crypto-board/model.ts

@@ -4,11 +4,18 @@ import { getTableWidth } from "../../../components/ui/table-layout";
 import { buildQuoteKey, resolveEntryData } from "../../../market-data/selectors";
 import type { QueryEntry } from "../../../market-data/result-types";
 import type { PricePoint, Quote } from "../../../types/financials";
+import type { HeadlessPaneFreshness } from "../../../types/headless";
 import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
 import { isFiniteNumber } from "../../../utils/guards";
 
 const DAY_MS = 86_400_000;
 
+/**
+ * How the board's report, capture and footer date its prices: crypto trades around the clock, so a price an hour old
+ * has stopped refreshing, and coins are quoted apart, so the line says how old the oldest is.
+ */
+export const CRYPTO_BOARD_FRESHNESS: HeadlessPaneFreshness = { maxAgeMinutes: 60, oldestAge: true };
+
 export const CRYPTO_TABS: Array<{ value: CryptoAssetKind; label: string }> = [
   { value: "coin", label: "Coins" },
   { value: "stablecoin", label: "Stablecoins" },
@@ -148,6 +155,11 @@ export function buildCryptoRows(
     });
 }
 
+/** What a capture and the footer read of each row: when its price is from, and whether it is streaming live. */
+export function cryptoRowObservations(rows: readonly CryptoRow[]): Array<{ quoteTime: string; dataSource: "live" | "delayed" }> {
+  return rows.flatMap((row) => row.updatedAt == null ? [] : [{ quoteTime: new Date(row.updatedAt).toISOString(), dataSource: row.live ? "live" as const : "delayed" as const }]);
+}
+
 /**
  * Four significant digits and never fewer than two decimals, with trailing
  * zeros kept, so a column running from 84,399.24 to 0.000005660 reads evenly.

package/src/plugins/builtin/crypto-board/pane.tsx

@@ -14,6 +14,9 @@ import { handleRefreshKey } from "../../../components/data-table/table-pane";
 import type { CryptoAssetKind, CryptoMarketAsset } from "../../../api-client/crypto-markets";
 import { isAccessDenied } from "../../../api-client/errors";
 import { useAsyncResource } from "../../../react/async-resource";
+import { useAgeClock } from "../../../react/auto-refresh";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { deriveHeadlessFreshness, paneStatusLine } from "../../../cli/pane-functions/freshness";
 import { usePaneVisible } from "../../../state/app/activity";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import { colors, priceColor } from "../../../theme/colors";
@@ -32,7 +35,9 @@ import { cachedCryptoMarkets, loadCryptoMarkets } from "./client";
 import {
   buildCryptoColumns,
   buildCryptoRows,
+  CRYPTO_BOARD_FRESHNESS,
   CRYPTO_TABS,
+  cryptoRowObservations,
   DEFAULT_CRYPTO_SORT,
   formatCryptoPercent,
   nextCryptoSort,
@@ -151,10 +156,18 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
     if (!selectedId || !rows.some((row) => row.id === selectedId)) setSelectedId(rows[0]!.id);
   }, [rows, selectedId, setSelectedId]);
 
-  const latestUpdate = rows.reduce<number | null>(
-    (latest, row) => (row.updatedAt != null && (latest == null || row.updatedAt > latest) ? row.updatedAt : latest),
-    null,
-  );
+  // Dated by the rows on screen while they stream, as `fn CRYP` and `shot CRYP` date the board.
+  const observations = useMemo(() => cryptoRowObservations(liveStreaming && streamedIds.size > 0
+    ? rows.filter((row) => streamedIds.has(row.id)) : rows), [liveStreaming, rows, streamedIds]);
+  const now = useAgeClock(resource.updatedAt);
+  useRemoteUiNode(observations.length ? {
+    role: "report-freshness",
+    label: "Price freshness",
+    getMetadata: () => ({ ...CRYPTO_BOARD_FRESHNESS, observations }),
+  } : null);
+  const statusLine = useMemo(() => observations.length
+    ? paneStatusLine(deriveHeadlessFreshness({ shape: "rows" }, { rows: observations, freshness: CRYPTO_BOARD_FRESHNESS }, now))
+    : null, [now, observations]);
   const columns = useMemo(() => buildCryptoColumns(width), [width]);
 
   const tabItems = CRYPTO_TABS.map((tab) => ({
@@ -178,16 +191,10 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
       // Background refreshes run every 15s; only the first load is worth a label.
       ...(resource.loading && !data ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
       ...(data && resource.error ? [{ id: "refresh", parts: [{ text: "refresh failed", tone: "warning" as const }] }] : []),
-      ...(latestUpdate != null ? [{
-        id: "updated",
-        parts: [{
-          text: new Date(latestUpdate).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }),
-          tone: "muted" as const,
-        }],
-      }] : []),
+      ...(statusLine ? [{ id: "updated", asOf: true, parts: [{ text: statusLine, tone: "muted" as const }] }] : []),
       ...(resource.data?.stale ? [{ id: "cached", parts: [{ text: "cached", tone: "warning" as const }] }] : []),
     ],
-  }), [data, latestUpdate, resource.data?.stale, resource.error, resource.loading]);
+  }), [data, statusLine, resource.data?.stale, resource.error, resource.loading]);
 
   const handleKeyDown = useCallback((event: DataTableKeyEvent) => (
     handleRefreshKey(event, () => void resource.reload(), { stopPropagation: true })

package/src/plugins/builtin/crypto-board/series.ts

@@ -0,0 +1,48 @@
+import type { SeriesDefinition } from "../../../series/types";
+
+const PAIRS: ReadonlyArray<{ symbol: string; name: string }> = [
+  { symbol: "BTC-USD", name: "Bitcoin" },
+  { symbol: "ETH-USD", name: "Ethereum" },
+  { symbol: "SOL-USD", name: "Solana" },
+  { symbol: "XRP-USD", name: "XRP" },
+  { symbol: "BNB-USD", name: "BNB" },
+  { symbol: "DOGE-USD", name: "Dogecoin" },
+  { symbol: "ADA-USD", name: "Cardano" },
+  { symbol: "AVAX-USD", name: "Avalanche" },
+  { symbol: "LINK-USD", name: "Chainlink" },
+  { symbol: "DOT-USD", name: "Polkadot" },
+  { symbol: "LTC-USD", name: "Litecoin" },
+  { symbol: "UNI-USD", name: "Uniswap" },
+  { symbol: "ATOM-USD", name: "Cosmos" },
+  { symbol: "NEAR-USD", name: "NEAR" },
+  { symbol: "APT-USD", name: "Aptos" },
+  { symbol: "SUI-USD", name: "Sui" },
+  { symbol: "TON-USD", name: "Toncoin" },
+  { symbol: "SHIB-USD", name: "Shiba Inu" },
+];
+
+/**
+ * The large pairs by name, and the price of any pair: the board's sparklines
+ * and the price a pair on the user's lists charts.
+ */
+export const CRYPTO_SERIES: readonly SeriesDefinition[] = [
+  ...PAIRS.map((pair): SeriesDefinition => ({
+    id: `crypto:${pair.symbol}`,
+    name: `${pair.name} (${pair.symbol})`,
+    unit: "USD",
+    frequency: "intraday",
+    group: "Crypto",
+    tags: [pair.symbol.split("-")[0]!, "crypto", "coin"],
+    expression: `${pair.symbol}:price`,
+  })),
+  {
+    id: "crypto:price",
+    name: "Price",
+    unit: "currency",
+    frequency: "intraday",
+    group: "Crypto",
+    tags: ["crypto", "pair"],
+    input: "crypto",
+    expression: "{ticker}:price",
+  },
+];

package/src/plugins/builtin/custom-view/live-quotes.ts

@@ -1,5 +1,5 @@
 import { resolveEntryValue } from "../../../market-data/coordinator";
-import { currencyMinorDigits } from "../../../market-data/market/format";
+import { currencyPriceMinDigits } from "../../../market-data/market/format";
 import type { QueryEntry } from "../../../market-data/result-types";
 import type { QuoteSubscriptionTarget } from "../../../types/data-provider";
 import type { Quote } from "../../../types/financials";
@@ -64,7 +64,7 @@ export function liveViewDecimalFloors(rows: readonly ViewRow[], fields: Readonly
 function rowsMinorDigits(rows: readonly ViewRow[]): number {
   const currencies = new Set(rows.map((row) => (typeof row.currency === "string" ? row.currency.trim() : "")));
   if (currencies.size === 0) return 2;
-  return Math.max(...[...currencies].map((currency) => Math.min(2, currencyMinorDigits(currency || undefined))));
+  return Math.max(...[...currencies].map((currency) => currencyPriceMinDigits(currency || undefined)));
 }
 
 export function viewRowSymbol(row: ViewRow, symbolKey: string | null): string | null {

package/src/plugins/builtin/debt-maturities/headless.ts

@@ -1,9 +1,13 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchDebtMaturities } from "./client";
-import { bucketShare, debtNotices } from "./model";
+import { bucketShare, debtAmount, debtNotices, debtPercent } from "./model";
 import { SEC_FILINGS } from "../shared/report-freshness";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 
+/** Amounts and shares as the pane prints them (952.00M, 12.5%); exports keep the whole number. */
+const amount = (value: unknown) => debtAmount(typeof value === "number" ? value : null);
+const percent = (value: unknown) => debtPercent(typeof value === "number" ? value : null);
+
 export const debtMaturitiesHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
   freshness: SEC_FILINGS,
@@ -16,11 +20,11 @@ export const debtMaturitiesHeadless: HeadlessPaneDefinition<"bundle"> = {
     aliases: ["DDIS"],
     dataRequirements: ["Gloom Cloud SEC principal maturity schedules"],
     limitations: [
-      "Six relative fiscal maturity buckets; thereafter is open ended",
-      "Reported principal obligations, not carrying debt; scope can include short-term borrowing and hedges",
-      "Native currency; unsupported or missing facts remain null",
-      "No inferred weighted coupon or duration",
-      "Ten-year percentiles require five comparable annual observations",
+      "Six relative fiscal maturity buckets; thereafter is open ended.",
+      "Reported principal obligations, not carrying debt; scope can include short-term borrowing and hedges.",
+      "Native currency; unsupported or missing facts remain null.",
+      "No inferred weighted coupon or duration.",
+      "Ten-year percentiles require five comparable annual observations.",
     ],
   },
   options: [
@@ -49,9 +53,9 @@ export const debtMaturitiesHeadless: HeadlessPaneDefinition<"bundle"> = {
           title: "Principal maturity schedule",
           columns: [
             { key: "label", header: "Maturity" },
-            { key: "value", header: "Principal", align: "right" },
+            { key: "value", header: "Principal", align: "right", textFormat: amount },
             { key: "currency", header: "Currency" },
-            { key: "share", header: "% total", align: "right" },
+            { key: "share", header: "% total", align: "right", textFormat: percent },
             { key: "asOf", header: "As of" },
             { key: "filed", header: "Filed" },
           ],
@@ -68,18 +72,20 @@ export const debtMaturitiesHeadless: HeadlessPaneDefinition<"bundle"> = {
           title: "Annual filing history",
           columns: [
             { key: "asOf", header: "As of" },
-            { key: "totalPrincipal", header: "Principal", align: "right" },
-            { key: "next12MonthsShare", header: "Next 12m %", align: "right" },
-            { key: "next3YearsShare", header: "Next 3y %", align: "right" },
+            { key: "totalPrincipal", header: "Principal", align: "right", textFormat: amount },
+            { key: "next12MonthsShare", header: "Next 12m %", align: "right", textFormat: percent },
+            { key: "next3YearsShare", header: "Next 3y %", align: "right", textFormat: percent },
             {
               key: "interestExpense",
               header: "Interest expense",
               align: "right",
+              textFormat: amount,
             },
             {
               key: "borrowingCostPercent",
               header: "Cost proxy %",
               align: "right",
+              textFormat: percent,
             },
             { key: "currency", header: "Currency" },
             { key: "filed", header: "Filed" },

package/src/plugins/builtin/debt-maturities/index.tsx

@@ -3,8 +3,10 @@ import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { debtMaturitiesCache } from "./client";
 import { debtMaturitiesHeadless } from "./headless";
 import { DebtMaturitiesPane } from "./pane";
+import { DEBT_MATURITY_SERIES } from "./series";
 
 export const debtMaturitiesModule: PluginModule = {
+  series: DEBT_MATURITY_SERIES,
   panes: [
     {
       id: "debt-maturities",

package/src/plugins/builtin/debt-maturities/series.ts

@@ -0,0 +1,45 @@
+import type { DebtHistoryPoint } from "../../../api-client/debt-maturities";
+import type { SeriesDefinition } from "../../../series/types";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadDebtMaturities } from "./client";
+
+type HistoryField = "totalPrincipal" | "next12MonthsShare" | "next3YearsShare";
+
+const FIELDS: ReadonlyArray<{ id: string; field: HistoryField; name: string; unit: string; tags: readonly string[]; description: string }> = [
+  { id: "total-principal", field: "totalPrincipal", name: "Debt principal total", unit: "USD", tags: ["principal", "total debt"],
+    description: "The principal the company reports maturing, all years summed, at each annual filing, as DDIS charts it." },
+  { id: "due-12m-share", field: "next12MonthsShare", name: "Debt due in the next 12 months", unit: "%", tags: ["near-term maturities", "refinancing"],
+    description: "Share of reported debt principal maturing within a year of each annual filing, as DDIS charts it." },
+  { id: "due-3y-share", field: "next3YearsShare", name: "Debt due in the next 3 years", unit: "%", tags: ["near-term maturities", "refinancing"],
+    description: "Share of reported debt principal maturing within three years of each annual filing, as DDIS charts it." },
+];
+
+/**
+ * A company's maturity wall across its annual filings, as DDIS reads it: the
+ * principal it reports and how much of it falls due soon. The wall itself is
+ * a schedule by year and stays in the pane.
+ */
+export const DEBT_MATURITY_SERIES: readonly SeriesDefinition[] = FIELDS.map(({ id, field, name, unit, tags, description }): SeriesDefinition => ({
+  id: `debt-maturities:${id}`,
+  name,
+  unit,
+  frequency: "annual",
+  group: "Credit",
+  tags: ["debt maturities", "maturity wall", "DDIS", ...tags],
+  description,
+  publisher: "SEC",
+  input: "ticker",
+  style: "step",
+  load: async ({ ticker }) => {
+    const resource = await loadDebtMaturities(ticker!);
+    if (!resource.payload.history.length) throw new Error(`No maturity schedule reported for ${ticker}.`);
+    // An amount stays in the unit it is listed in: a filing in another currency is a gap, not a converted figure.
+    const listed = (point: DebtHistoryPoint) => unit !== "USD" || point.currency === "USD";
+    const other = resource.payload.history.find((point) => !listed(point))?.currency;
+    const warning = other ? `Filings reported in ${other} are left out.` : cachedSeriesWarning(resource);
+    return {
+      points: resource.payload.history.map((point) => ({ date: point.asOf, value: listed(point) ? point[field] : null })),
+      ...(warning ? { warning } : {}),
+    };
+  },
+}));

package/src/plugins/builtin/dividend-yield/client.ts

@@ -149,6 +149,8 @@ export function buildDividendMetrics(
     ? trailingCashAt(eligible, now)
     : options.summaryRatesComparable !== false ? quoteFields?.trailingAnnualDividendRate ?? null : null;
   const forwardRate = options.summaryRatesComparable !== false ? quoteFields?.forwardAnnualDividendRate ?? null : null;
+  const forwardRateAsOf = forwardRate != null && /^\d{4}-\d{2}-\d{2}$/.test(quoteFields?.forwardRateAsOf ?? "")
+    ? quoteFields!.forwardRateAsOf! : null;
   const growth1Y = options.historyAvailable !== false ? computeGrowth(eligible, 1, now) : null;
   const growth3Y = options.historyAvailable !== false ? computeGrowth(eligible, 3, now) : null;
 
@@ -170,6 +172,7 @@ export function buildDividendMetrics(
     forwardYield: null,
     trailingRate,
     forwardRate,
+    forwardRateAsOf,
     payoutRatio: quoteFields?.payoutRatio ?? null,
     growth1Y,
     growth3Y,

package/src/plugins/builtin/dividend-yield/headless.ts

@@ -8,7 +8,8 @@ import { dividendReferencePrice, fetchDividendData, type DividendData } from "./
 import type { DividendPayment } from "./types";
 import { formatDividendYield, toDividendRows } from "./view";
 import { formatDistributionAmount, formatPercent } from "../../../utils/format";
-import { currencyMinorDigits, formatMarketPriceWithCurrency } from "../../../market-data/market/format";
+import { forwardDividendBasis } from "../../../utils/forward-dividend";
+import { currencyPriceMinDigits, formatMarketPriceWithCurrency } from "../../../market-data/market/format";
 import type { Quote } from "../../../types/financials";
 import { dividendPriceStatus, dividendQuotePriceMetadata } from "./reference-price";
 
@@ -85,13 +86,14 @@ export function projectDividendYieldHeadless(
       {
         title: "Dividend metrics",
         entries: [
-          { label: "Price", value: data.price, ...(data.price != null && currency ? { formatted: formatMarketPriceWithCurrency(data.price, currency, { minimumFractionDigits: Math.min(2, currencyMinorDigits(currency)) }) } : {}) },
+          { label: "Price", value: data.price, ...(data.price != null && currency ? { formatted: formatMarketPriceWithCurrency(data.price, currency, { minimumFractionDigits: currencyPriceMinDigits(currency) }) } : {}) },
           ...(data.stale ? [{ label: "History status", value: "Stale cash history; recent distributions may be missing." }] : []),
           ...(priceStatus ? [{ label: "Price status", value: priceStatus === "stale"
             ? "Stale reference price; cash yield may be out of date."
             : "Reference price time unavailable; cash yield may be out of date." }] : []),
           { label: "Trailing yield", value: metrics.trailingYield, formatted: formatDividendYield(metrics.trailingYield) },
-          { label: "Forward yield", value: metrics.forwardYield, formatted: formatDividendYield(metrics.forwardYield) },
+          { label: "Forward yield", value: metrics.forwardYield, formatted: metrics.forwardYield == null ? formatDividendYield(null)
+            : `${formatDividendYield(metrics.forwardYield)} (${forwardDividendBasis(metrics.forwardRateAsOf)})` },
           { label: "Trailing rate", value: metrics.trailingRate, formatted: currency ? formatDistributionAmount(metrics.trailingRate ?? undefined, currency) : "—" },
           { label: "Forward rate", value: metrics.forwardRate, formatted: currency ? formatDistributionAmount(metrics.forwardRate ?? undefined, currency) : "—" },
           { label: "Earnings Payout", value: metrics.payoutRatio, formatted: formatDividendYield(metrics.payoutRatio) },
@@ -127,7 +129,8 @@ export function projectDividendYieldHeadless(
       priceStale: data.priceStale ?? null,
       limitations: data.notes ?? [],
       yieldMethod: "Cash distributions with ex-dates in the preceding 12 months, one payment per period for a regular cadence, divided by the reference share price; excludes reinvestment and is not SEC yield or total return.",
-      forwardRateMethod: "Provider indicated annual cash rate, only when its currency units are comparable with the share price.",
+      forwardRateAsOf: metrics.forwardRateAsOf,
+      forwardRateMethod: "Indicated annual cash rate, the one fundamentals use: the latest regular distribution annualized, dated by its ex-date (forwardRateAsOf). Only when its currency units are comparable with the share price.",
       paymentFrequencyMethod: "Cadence inferred from ex-dates in the last two years, unavailable when no cash was reported in the last year; not an announced payment schedule.",
     },
   };

package/src/plugins/builtin/dividend-yield/index.tsx

@@ -1,4 +1,5 @@
 import type { PluginModule } from "../plugin-module";
+import { DIVIDEND_SERIES } from "./series";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import {
   attachDividendYieldHealth,
@@ -19,6 +20,7 @@ function createDividendYieldModule({
 } = {}): PluginModule {
   let disposeConnection: (() => void) | null = null;
   return {
+    series: DIVIDEND_SERIES,
     setup(ctx) {
       if (marketConnection) {
         attachDividendYieldHealth(ctx.connectionHealth);
@@ -67,7 +69,7 @@ function createDividendYieldModule({
           id: "dividend-yield-pane",
           paneId: "dividend-yield",
           label: "Dividend Yield",
-          description: "Cash distribution history, trailing cash yield, indicated rates when available, and growth. Future payments are not forecast.",
+          description: "Cash distribution history, trailing cash yield, forward yield from the latest distribution, and growth. Future payments are not forecast.",
           keywords: ["dividend", "yield", "dvd", "income", "payout", "ex-date", "distribution"],
           shortcut: "DVD",
         }),

package/src/plugins/builtin/dividend-yield/pane.tsx

@@ -77,7 +77,9 @@ function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory
     : hasHistory ? [] : [{ id: "last-ex", label: "Last ex", value: formatDate(metrics.lastExDividendDate) }];
   return [
     { id: "ttm-yield", label: short ? "TTM yld" : "TTM yield", value: formatDividendYield(metrics.trailingYield), color: priceColor(metrics.trailingYield ?? 0) },
-    { id: "forward-yield", label: short ? "Fwd yld" : "Fwd yield", value: formatDividendYield(metrics.forwardYield), color: priceColor(metrics.forwardYield ?? 0) },
+    // Dated by the distribution it annualizes; docs/research-data.md says how it is built.
+    { id: "forward-yield", label: short ? "Fwd yld" : "Fwd yield", value: formatDividendYield(metrics.forwardYield), color: priceColor(metrics.forwardYield ?? 0),
+      ...(metrics.forwardYield != null && metrics.forwardRateAsOf ? { detail: `as of ${metrics.forwardRateAsOf}` } : {}) },
     { id: "ttm-rate", label: short ? "TTM/sh" : "TTM/share", value: formatRate(metrics.trailingRate, currency) },
     { id: "forward-rate", label: short ? "Fwd/sh" : "Fwd/share", value: formatRate(metrics.forwardRate, currency) },
     { id: "growth-1y", label: short ? "1Y chg" : "1Y growth", value: formatGrowth(metrics.growth1Y), color: priceColor(metrics.growth1Y ?? 0) },

package/src/plugins/builtin/dividend-yield/series.ts

@@ -0,0 +1,20 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchDividendData } from "./client";
+import { buildTrailingCashChartPoints } from "./view";
+
+/** A ticker's trailing twelve months of cash dividends, stepping at each payment, as DVD charts it. */
+export const DIVIDEND_SERIES: readonly SeriesDefinition[] = [{
+  id: "dividends:ttm-cash",
+  name: "Trailing 12-month dividends",
+  unit: "currency/share",
+  frequency: "irregular",
+  group: "Securities",
+  tags: ["dividends", "income", "payout", "DVD"],
+  input: "ticker",
+  style: "step",
+  load: async ({ ticker }) => {
+    const data = await fetchDividendData(ticker!, null);
+    if (data.historyAvailable === false) throw new Error(data.historyError ?? `No dividend history for ${ticker}.`);
+    return buildTrailingCashChartPoints(data.payments).map((point) => ({ date: point.date, value: point.close }));
+  },
+}];

package/src/plugins/builtin/dividend-yield/types.ts

@@ -13,6 +13,8 @@ export interface DividendMetrics {
   forwardYield: number | null;
   trailingRate: number | null;
   forwardRate: number | null;
+  /** The ex-date of the distribution the forward rate annualizes, YYYY-MM-DD. */
+  forwardRateAsOf: string | null;
   payoutRatio: number | null;
   growth1Y: number | null;
   growth3Y: number | null;