gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/holders/beneficial-view.tsx

@@ -0,0 +1,241 @@
+import { useCallback, useMemo, useState } from "react";
+import { TextAttributes, useRendererHost } from "../../../ui";
+import {
+  DataTableView,
+  EmptyState,
+  PaneStatusBody,
+  usePaneFooter,
+  usePaneNoticeFooter,
+  type DataTableCell,
+  type DataTableKeyEvent,
+} from "../../../components";
+import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { colors, priceColor } from "../../../theme/colors";
+import { isPlainKey } from "../../../utils/keyboard";
+import { nextHeaderSort } from "../../../utils/sort-values";
+import { usePluginAppActions, usePluginPaneState } from "../../runtime";
+import { SignInWall } from "../cloud/auth-actions";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { openSecFilingInPane } from "../sec/command-bar-search";
+import { cachedBeneficialOwners, loadBeneficialOwners } from "./beneficial-client";
+import { beneficialCoverageNotices, beneficialListUnreadable } from "./beneficial-report";
+import {
+  buildBeneficialColumns,
+  buildBeneficialRows,
+  DEFAULT_BENEFICIAL_SORT,
+  formatFilerName,
+  formatOwnerShares,
+  formatPercentOfClass,
+  formatPointChange,
+  sortBeneficialRows,
+  stakeMarker,
+  type BeneficialColumn,
+  type BeneficialColumnId,
+  type BeneficialOwnerRow,
+  type BeneficialSortPreference,
+} from "./beneficial-model";
+import type { Holder13FMatch } from "./thirteenf-match";
+import type { HolderRow } from "./types";
+
+const STALE_SEGMENT = { id: "stale", parts: [{ text: "stale", tone: "warning" as const }] };
+
+/**
+ * The 13D/G tab: who disclosed more than 5% of the class, the stake each
+ * filer's latest report gives and how it moved, one row per filer, joined to
+ * the Table tab's 13F holders for the quarter's action. A latest report is
+ * the latest disclosure, not today's position.
+ */
+export function BeneficialOwnersView({
+  focused,
+  width,
+  symbol,
+  holderRows,
+  fundMatches,
+  onCycleView,
+  onRefreshHolders,
+}: {
+  focused: boolean;
+  width: number;
+  symbol: string | null;
+  holderRows: readonly HolderRow[];
+  fundMatches: ReadonlyMap<string, Holder13FMatch>;
+  onCycleView: () => void;
+  onRefreshHolders: () => void;
+}) {
+  const rendererHost = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const session = useResearchCloudSession();
+  const [sortPreference, setSortPreference] = usePluginPaneState<BeneficialSortPreference>(
+    "beneficialSort",
+    DEFAULT_BENEFICIAL_SORT,
+  );
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  // A session change retries a request the sign-in wall was shown for.
+  const loader = useMemo(
+    () => symbol ? (force: boolean) => loadBeneficialOwners(symbol, force) : null,
+    [symbol, session.requestKey],
+  );
+  const resource = useAsyncResource(loader, {
+    initialData: () => symbol ? cachedBeneficialOwners(symbol) : null,
+    clearOnError: (error) => error instanceof Error && isCloudSessionRequired(error.message),
+  });
+  useAutoRefresh(resource.updatedAt, resource.load);
+  const payload = resource.data?.payload ?? null;
+
+  const rows = useMemo(
+    () => buildBeneficialRows(payload?.owners ?? [], holderRows, fundMatches),
+    [fundMatches, holderRows, payload],
+  );
+  const sortedRows = useMemo(() => sortBeneficialRows(rows, sortPreference), [rows, sortPreference]);
+  const columns = useMemo(() => buildBeneficialColumns(width), [width]);
+  const selectedRow = sortedRows.find((row) => row.id === selectedId) ?? sortedRows[0] ?? null;
+
+  const openFiling = useCallback((row: BeneficialOwnerRow | null | undefined) => {
+    if (!row || !symbol) return;
+    openSecFilingInPane({ createPaneFromTemplate }, symbol, row.filing.accessionNumber);
+  }, [createPaneFromTemplate, symbol]);
+
+  const openFilingUrl = useCallback(() => {
+    const url = selectedRow?.filing.filingUrl;
+    if (url) void rendererHost.openExternal(url);
+  }, [rendererHost, selectedRow]);
+
+  const refresh = useCallback(() => {
+    void resource.reload();
+    onRefreshHolders();
+  }, [onRefreshHolders, resource]);
+
+  const handleKeyDown = useCallback((event: DataTableKeyEvent) => {
+    if (handleRefreshKey(event, refresh, { stopPropagation: true })) return true;
+    if (isPlainKey(event, "s")) {
+      event.preventDefault?.();
+      event.stopPropagation?.();
+      onCycleView();
+      return true;
+    }
+    return false;
+  }, [onCycleView, refresh]);
+
+  const handleHeaderClick = useCallback((columnId: string) => {
+    setSortPreference((current) => nextHeaderSort(current, columnId as BeneficialColumnId, {
+      firstDirection: (id) => id === "filer" || id === "form" ? "asc" : "desc",
+    }));
+  }, [setSortPreference]);
+
+  const renderCell = useCallback((
+    row: BeneficialOwnerRow,
+    column: BeneficialColumn,
+    _index: number,
+    rowState: { selected: boolean },
+  ): DataTableCell => {
+    const { filing } = row;
+    // A report of zero reads as history; a stake under 5% is still a stake.
+    const exited = row.stake === "exited";
+    const tone = exited ? colors.textMuted : colors.text;
+    switch (column.id) {
+      case "filer":
+        return {
+          text: formatFilerName(filing.filerName, Math.max(0, filing.reportingPersons.length - 1), column.width),
+          value: filing.filerName,
+          color: exited ? colors.textMuted : rowState.selected ? colors.selectedText : colors.textBright,
+          attributes: exited ? undefined : TextAttributes.BOLD,
+        };
+      case "form":
+        return { text: row.formLabel, color: tone };
+      case "percentOfClass": {
+        // A column too narrow for `4.9% <5%` keeps the figure alone.
+        const marker = column.width >= formatPercentOfClass(row, { marker: true }).length;
+        return {
+          text: formatPercentOfClass(row, { marker }),
+          value: filing.percentOfClass,
+          color: row.stake === "holder" ? colors.textBright : stakeMarker(row.stake) ? colors.textDim : colors.text,
+        };
+      }
+      case "change":
+        return {
+          text: formatPointChange(row.changePoints),
+          value: row.changePoints,
+          color: row.changePoints == null || row.changePoints === 0 ? colors.textDim : priceColor(row.changePoints),
+        };
+      case "shares":
+        return { text: formatOwnerShares(filing.shares), value: filing.shares, color: tone };
+      case "eventDate":
+        return { text: filing.eventDate ?? "-", value: filing.eventDate, color: colors.textDim };
+      case "filingDate":
+        return { text: filing.filingDate, value: filing.filingDate, color: colors.textDim };
+      case "thirteenF": {
+        const action = row.thirteenF;
+        if (!action) return { text: "-", value: null, color: colors.textDim };
+        return { text: action.label, color: action.value === 0 ? colors.textDim : priceColor(action.value) };
+      }
+    }
+  }, []);
+
+  const authWall = !payload && isCloudSessionRequired(resource.error);
+  const error = authWall ? null : resource.error;
+  // Listed filings that could not be read are a failure, not "no filings".
+  const unreadable = !!payload && beneficialListUnreadable(payload);
+  const coverageNotices = useMemo(
+    () => unreadable ? [] : beneficialCoverageNotices(payload?.coverage),
+    [payload, unreadable],
+  );
+  usePaneNoticeFooter({
+    registrationId: "holders-13dg:coverage",
+    notices: coverageNotices,
+    focused,
+    title: "13D/13G coverage",
+  });
+  usePaneFooter("holders-13dg", () => ({
+    info: [
+      ...(payload?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${payload.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []),
+      ...(payload && resource.data?.stale ? [STALE_SEGMENT] : []),
+      ...loadingErrorFooterInfo(resource.loading, payload ? error : null),
+    ],
+    hints: selectedRow?.filing.filingUrl
+      ? [{ id: "filing", key: "o", label: "pen filing", onPress: openFilingUrl }]
+      : [],
+  }), [error, openFilingUrl, payload, resource.data?.stale, resource.loading, selectedRow]);
+
+  if (!symbol) return <EmptyState title="No ticker selected." />;
+  if (authWall) {
+    return <SignInWall placement="holders-13dg-signin" action="view 13D/13G filings" needsVerification={session.needsVerification} />;
+  }
+
+  return (
+    <PaneStatusBody
+      loading={resource.loading && !payload}
+      error={!payload ? error
+        : unreadable ? `${payload.coverage?.filings ?? 0} filings are listed for ${symbol} but none could be read this time. A refresh retries them.`
+        : null}
+      subject="13D/13G filings"
+      empty={!!payload && sortedRows.length === 0}
+      emptyTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}
+    >
+      <DataTableView<BeneficialOwnerRow, BeneficialColumn>
+        focused={focused}
+        selection={{
+          kind: "id",
+          selectedId: selectedRow?.id ?? null,
+          getId: (row) => row.id,
+          onChange: (id) => setSelectedId(id),
+        }}
+        onActivate={openFiling}
+        onRootKeyDown={handleKeyDown}
+        resetScrollKey={symbol}
+        rootWidth={width}
+        columns={columns}
+        items={sortedRows}
+        sortColumnId={sortPreference.columnId}
+        sortDirection={sortPreference.direction}
+        onHeaderClick={handleHeaderClick}
+        getItemKey={(row) => row.id}
+        renderCell={renderCell}
+        selectedTextOverridesCellColor
+        emptyStateTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}
+      />
+    </PaneStatusBody>
+  );
+}

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

@@ -17,6 +17,30 @@ import {
 import { buildRows, sortRows } from "./table-model";
 import type { HolderData } from "../../../types/financials";
 import type { HolderColumnId } from "./types";
+import { SEC_FILINGS } from "../shared/report-freshness";
+import {
+  holderValueBasis,
+  holdersHeaderLine,
+  moneyColumnHeader,
+  nonUsHolderCaveat,
+  sharedReportDate,
+} from "./report-header";
+
+/** Columns a source fills only when it reports the quarter's change. */
+const CHANGE_COLUMN_KEYS = new Set(["changeShares", "changePercent"]);
+import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
+import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
+import type { BeneficialColumnId } from "./beneficial-model";
+import {
+  BENEFICIAL_REPORT_COLUMNS,
+  beneficialCoverageNotices,
+  beneficialListComplete,
+  beneficialListFacts,
+  beneficialRouteForm,
+  buildBeneficialReportRows,
+  HOLDER_FORMS,
+  parseHolderForm,
+} from "./beneficial-report";
 
 const HOLDER_COLUMNS: HeadlessPaneColumn[] = [
   { key: "name", header: "Holder" },
@@ -71,6 +95,17 @@ const SORT_COLUMNS: Record<string, HolderColumnId> = {
   date: "reportDate",
 };
 
+/** The same sort keys order the 13D/13G rows; `value` and `held` are the percent of class. */
+const BENEFICIAL_SORT_COLUMNS: Record<string, BeneficialColumnId> = {
+  holder: "filer",
+  value: "percentOfClass",
+  shares: "shares",
+  change: "change",
+  "change-percent": "thirteenF",
+  held: "percentOfClass",
+  date: "filingDate",
+};
+
 interface HolderSnapshot {
   data: HolderData;
   marketCap?: number;
@@ -82,17 +117,28 @@ export interface HoldersHeadlessDependencies {
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
   ): Promise<HolderSnapshot>;
+  loadBeneficialOwners(
+    symbol: string,
+    request: BeneficialOwnersRequest,
+    ctx: HeadlessPaneContext,
+  ): Promise<BeneficialOwnersPayload>;
 }
 
 const defaultDependencies: HoldersHeadlessDependencies = {
   loadSnapshot: (symbol, _args, ctx) => loadHolderSnapshot(ctx.marketData, symbol),
+  loadBeneficialOwners: (symbol, request, ctx) => fetchBeneficialOwners(symbol, request, {
+    client: ctx.apiClient,
+    signal: ctx.signal,
+  }),
 };
 
 export function createHoldersHeadless(
-  dependencies: HoldersHeadlessDependencies = defaultDependencies,
+  overrides: Partial<HoldersHeadlessDependencies> = {},
 ): HeadlessPaneDefinition<"rows"> {
+  const dependencies = { ...defaultDependencies, ...overrides };
   return {
     shape: "rows",
+    freshness: { ...SEC_FILINGS, basis: "13F filings" },
     argument: {
       kind: "ticker",
       placeholder: "ticker",
@@ -124,23 +170,79 @@ export function createHoldersHeadless(
       },
       {
         key: "view",
-        description: "Rendered pane view: the holder table or the ownership treemap.",
+        description: "Rendered pane view: the holder table, the ownership treemap or the 13D/13G beneficial owners.",
         type: "enum",
-        values: [{ value: "table" }, { value: "chart" }],
+        values: [{ value: "table" }, { value: "chart" }, { value: "13dg", aliases: ["beneficial"] }],
         defaultValue: "table",
         pluginState: { pluginId: "ticker-research", key: "viewMode" },
       },
+      {
+        key: "form",
+        description: "Rows: 13f for institutional holders, 13d or 13g for beneficial owners over 5% of the class (activists, crowding into large stakes), all for both kinds.",
+        type: "enum",
+        values: HOLDER_FORMS.map((value) => ({ value })),
+        defaultValue: "13f",
+      },
+      {
+        key: "history",
+        description: "With a 13d, 13g or all form, every report newest first instead of the latest per filer.",
+        type: "boolean",
+        defaultValue: false,
+      },
     ],
     columns: HOLDER_COLUMNS,
     describe: (args) => `Holders | ${args.symbols[0]}`,
     async load(args, ctx) {
       const symbol = args.symbols[0]!;
+      const requestedForm = parseHolderForm(args.options.form) ?? "13f";
+      // The 13D/G view reports what it shows when no form is asked for.
+      const form = requestedForm === "13f" && args.options.view === "13dg" ? "all" : requestedForm;
+      if (form !== "13f") {
+        const history = args.options.history === true;
+        const [payload, snapshot] = await Promise.all([
+          dependencies.loadBeneficialOwners(symbol, { form: beneficialRouteForm(form), history }, ctx),
+          // The 13F column is a join; the 13D/13G rows stand without it.
+          dependencies.loadSnapshot(symbol, args, ctx).catch(() => null),
+        ]);
+        const rows = buildBeneficialReportRows(payload, {
+          history,
+          holders: snapshot?.data ?? null,
+          sort: {
+            columnId: BENEFICIAL_SORT_COLUMNS[String(args.options.sort)] ?? "percentOfClass",
+            direction: args.options.order === "asc" ? "asc" : "desc",
+          },
+        });
+        const limited = rows.slice(0, Number(args.options.limit));
+        return {
+          columns: BENEFICIAL_REPORT_COLUMNS,
+          rows: limited,
+          // Reports that could not be read this time are missing from the rows.
+          complete: beneficialListComplete(payload),
+          freshness: { ...SEC_FILINGS, basis: "13D/13G filings", observedKey: "filingDate" },
+          metadata: {
+            symbol: payload.ticker || symbol,
+            name: payload.companyName || null,
+            cik: payload.cik || null,
+            form,
+            history,
+            asOf: payload.asOf,
+            coverage: payload.coverage,
+            notices: [
+              [payload.companyName || symbol, ...beneficialListFacts(payload, form, rows.length, history)].join(" · "),
+              ...beneficialCoverageNotices(payload.coverage),
+            ],
+            returned: limited.length,
+            total: rows.length,
+          },
+        };
+      }
       const { data, marketCap } = await dependencies.loadSnapshot(symbol, args, ctx);
       const currency = data.currency ?? "USD";
-      const rows = sortRows(buildRows(data), {
+      const sorted = sortRows(buildRows(data), {
         columnId: SORT_COLUMNS[String(args.options.sort)] ?? "value",
         direction: args.options.order === "asc" ? "asc" : "desc",
-      }, marketCap)
+      }, marketCap);
+      const rows = sorted
         .slice(0, Number(args.options.limit))
         .map((row) => ({
           name: row.name,
@@ -153,14 +255,46 @@ export function createHoldersHeadless(
           reportDate: row.reportDate ?? null,
           currency,
         }));
+      const total = data.summary?.institutionsCount ?? null;
+      const changeReported = rows.some((row) => row.changeShares != null || row.changePercent != null);
+      const reportDate = sharedReportDate(rows);
+      const valueBasis = holderValueBasis(reportDate);
+      const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(data.exchange, currency) : null;
+      // The title names the ticker and the closing line carries the as-of date.
+      const header = holdersHeaderLine({
+        name: data.name,
+        symbol: data.symbol && data.symbol !== symbol ? data.symbol : null,
+        exchange: data.exchange,
+        currency,
+        shown: rows.length,
+        reported: sorted.length,
+        total,
+      });
+      const basis = rows.length === 0 ? null : [
+        `Mkt value = ${valueBasis}.`,
+        changeReported ? "" : `Change vs prior quarter: not reported by this source; see fn 13F ${symbol}`,
+      ].filter(Boolean).join(" ");
       return {
+        // A change column that is empty on every row says nothing; the line above explains it once.
+        columns: HOLDER_COLUMNS
+          .filter((column) => changeReported || !CHANGE_COLUMN_KEYS.has(column.key))
+          .map((column) => column.key === "value" ? { ...column, header: moneyColumnHeader(column.header, currency) } : column),
         rows,
         metadata: {
           symbol: data.symbol || symbol,
           name: data.name ?? null,
+          exchange: data.exchange ?? null,
           currency,
           asOf: data.asOf ?? null,
           summary: data.summary ?? null,
+          shown: rows.length,
+          reported: sorted.length,
+          total,
+          truncated: rows.length < (total ?? sorted.length),
+          valueBasis,
+          changeReported,
+          positionsBasis,
+          notices: [header, basis, positionsBasis].filter((line): line is string => !!line),
         },
       };
     },

package/src/plugins/builtin/holders/index.tsx

@@ -1,11 +1,12 @@
 import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { beneficialOwnersCache } from "./beneficial-client";
 import { holdersHeadless } from "./headless";
 import { HoldersView } from "./pane";
 
-
 export const holdersModule: PluginModule = {
   setup(ctx) {
+    beneficialOwnersCache.attach(ctx.persistence);
     ctx.registerTickerResearchTab({
       id: "holders",
       name: "Holders",
@@ -14,6 +15,9 @@ export const holdersModule: PluginModule = {
       instruments: ["equity"],
     });
   },
+  dispose() {
+    beneficialOwnersCache.reset();
+  },
 
   panes: [
     {
@@ -35,8 +39,11 @@ export const holdersModule: PluginModule = {
         id: "holders-pane",
         paneId: "holders",
         label: "Holders",
-        description: "Institutional holders for the selected ticker.",
-        keywords: ["holders", "ownership", "institutional", "owners", "hds"],
+        description: "Institutional holders from 13F filings, and 13D/13G beneficial owners: activist and passive stakes over 5% of the class.",
+        keywords: [
+          "holders", "ownership", "institutional", "owners", "hds",
+          "13d", "13g", "13d/g", "schedule 13d", "schedule 13g", "beneficial owners", "beneficial ownership", "activist", "activists",
+        ],
         shortcut: "HDS",
       }),
       headless: holdersHeadless,

package/src/plugins/builtin/holders/pane.tsx

@@ -30,13 +30,16 @@ import {
 } from "./format";
 import {
   buildColumns,
+  hasHolderChanges,
   buildRows,
   DEFAULT_SORT,
+  nextViewMode,
   sortRows,
   VIEW_TABS,
 } from "./table-model";
 import { loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
+import { BeneficialOwnersView } from "./beneficial-view";
 import type { HolderColumn, HolderColumnId, HolderRow, SortPreference, ViewMode } from "./types";
 import { loadHolder13FMatches, type Holder13FMatch } from "./thirteenf-match";
 import { useSampledValue, useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
@@ -77,7 +80,9 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   const marketCap = useSampledValue(liveMarketCap, HOLDER_MARKET_CAP_SAMPLE_MS, `${symbol ?? ""}:${currency}`);
   const rows = useMemo(() => buildRows(data), [data]);
   const sortedRows = useMemo(() => sortRows(rows, sortPreference, marketCap), [marketCap, rows, sortPreference]);
-  const columns = useMemo(() => buildColumns(width), [width]);
+  // Change columns only when the source reports a change; otherwise they read "-" on every row.
+  const showChange = useMemo(() => hasHolderChanges(rows), [rows]);
+  const columns = useMemo(() => buildColumns(width, showChange), [showChange, width]);
   const selectedIdx = selectedId
     ? sortedRows.findIndex((row) => row.id === selectedId)
     : -1;
@@ -145,7 +150,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
   }, [setSortPreference]);
 
   const toggleView = useCallback(() => {
-    setViewMode((current) => current === "table" ? "chart" : "table");
+    setViewMode(nextViewMode);
   }, [setViewMode]);
 
   const refresh = useCallback(() => {
@@ -250,7 +255,9 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     }
   }, [currency, fundMatches, marketCap]);
 
+  // The 13D/G tab registers its own footer.
   usePaneFooter("holders", () => {
+    if (viewMode === "13dg") return null;
     return {
       info: [
         ...(data?.asOf ? [{ id: "as-of", parts: [{ text: data.asOf, tone: "value" as const }] }] : []),
@@ -264,7 +271,7 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
         ...(selectedFundMatch ? [{ id: "fund", key: "o", label: "pen 13F", onPress: () => openFundDetail(selectedRow) }] : []),
       ],
     };
-  }, [data, error, fundMatching, loading, openFundDetail, selectedFundMatch, selectedRow]);
+  }, [data, error, fundMatching, loading, openFundDetail, selectedFundMatch, selectedRow, viewMode]);
 
   const selectView = useCallback((value: string) => setViewMode(value as ViewMode), [setViewMode]);
   // As a research tab, h/l move between research tabs; `s` switches the view.
@@ -316,6 +323,16 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
           selectedTextOverridesCellColor
           emptyStateTitle={statusTitle ?? "No holders available"}
         />
+      ) : viewMode === "13dg" ? (
+        <BeneficialOwnersView
+          focused={focused}
+          width={width}
+          symbol={symbol ?? null}
+          holderRows={rows}
+          fundMatches={fundMatches}
+          onCycleView={toggleView}
+          onRefreshHolders={refresh}
+        />
       ) : (
         <HoldersTreemap
           rows={sortedRows}

package/src/plugins/builtin/holders/report-header.ts

@@ -0,0 +1,95 @@
+import { currencyUnitLabel, resolveCurrencyUnit } from "../../../utils/currency-units";
+import { canonicalExchange, isUsListingExchange, resolveExchangeTimeZone } from "../../../utils/exchanges";
+
+/**
+ * The lines above a holder table in text reports (`holders`, `insider`,
+ * `13f`, `fn HDS`): which listing, in which unit, and how much of the list
+ * is shown. Holder lists come as the source's own top holders, usually
+ * without a total, so the count says that rather than implying a full list.
+ */
+export interface HolderReportFacts {
+  name?: string | null;
+  /** Left out when the report title already names it. */
+  symbol?: string | null;
+  exchange?: string | null;
+  currency?: string | null;
+  /** Left out when the report's closing line already carries it. */
+  asOf?: string | null;
+  /** Rows printed. */
+  shown: number;
+  /** Rows the source returned, before any limit. */
+  reported: number;
+  /** Every holder the source counts, when it says so. */
+  total?: number | null;
+}
+
+/** "Value (GBp)": a money column names its unit. */
+export function moneyColumnHeader(label: string, currency?: string | null): string {
+  const unit = currency?.trim();
+  return unit ? `${label} (${unit})` : label;
+}
+
+function holderCountText(shown: number, reported: number, total?: number | null): string {
+  if (total != null && Number.isFinite(total) && total >= reported) {
+    return `${shown.toLocaleString("en-US")} of ${total.toLocaleString("en-US")} holders`;
+  }
+  if (reported === 0) return "none reported";
+  // Without a total the source's list is its largest holders, cut where it cuts it.
+  return shown < reported ? `${shown} of top ${reported} reported` : `top ${reported} reported`;
+}
+
+/** A venue the app knows by its short name (NasdaqGS is NASDAQ); any other as the source wrote it. */
+function venueLabel(exchange?: string | null): string {
+  const canonical = canonicalExchange(exchange ?? "");
+  return resolveExchangeTimeZone(canonical) ? canonical : (exchange ?? "").trim();
+}
+
+/** What the list is, after the listing is named: its unit, date and how much of it is shown. */
+export function holderListFacts(
+  facts: Pick<HolderReportFacts, "currency" | "asOf" | "shown" | "reported" | "total">,
+): string[] {
+  return [
+    currencyUnitLabel(facts.currency),
+    facts.asOf ? `as of ${facts.asOf}` : "",
+    holderCountText(facts.shown, facts.reported, facts.total),
+  ].filter(Boolean);
+}
+
+export function holdersHeaderLine(facts: HolderReportFacts): string {
+  const name = facts.name?.trim();
+  const symbol = facts.symbol?.trim();
+  const identity = name && symbol && name !== symbol ? `${name} (${symbol})` : name || symbol || "";
+  return [identity, venueLabel(facts.exchange), ...holderListFacts(facts)].filter(Boolean).join(" | ");
+}
+
+/** The one report date every row shares, or null when they differ or none has one. */
+export function sharedReportDate(rows: ReadonlyArray<{ reportDate?: unknown }>): string | null {
+  const dates = new Set(rows.map((row) => (typeof row.reportDate === "string" ? row.reportDate : "")));
+  const [only] = dates;
+  return dates.size === 1 && only ? only : null;
+}
+
+/** How a holder value was reached: reported shares times a current price, not the filing's own value. */
+export function holderValueBasis(reportDate: string | null): string {
+  return `shares reported${reportDate ? ` at ${reportDate}` : ""} x latest price`;
+}
+
+/** A listing outside the US, by its venue, or by a currency other than the dollar. */
+function isNonUsHolderListing(exchange?: string | null, currency?: string | null): boolean {
+  const venue = canonicalExchange(exchange ?? "");
+  if (venue && !isUsListingExchange(venue) && resolveExchangeTimeZone(venue)) return true;
+  const unit = resolveCurrencyUnit(currency).currency;
+  return unit !== "" && unit !== "USD";
+}
+
+/**
+ * Holder lists are institutions' quarterly filings, mostly US 13F. On a
+ * listing outside the US they are not that market's share register, which a
+ * reader would otherwise assume.
+ */
+export function nonUsHolderCaveat(exchange?: string | null, currency?: string | null): string | null {
+  if (!isNonUsHolderListing(exchange, currency)) return null;
+  const canonical = canonicalExchange(exchange ?? "");
+  const venue = resolveExchangeTimeZone(canonical) ? canonical : "local";
+  return `Positions come from institutional filings (mostly US 13F), not the ${venue} share register.`;
+}