gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/holders/beneficial-model.ts

@@ -30,9 +30,22 @@ export interface ThirteenFAction {
   value: number;
 }
 
+/** The stake a report's shares make of today's count, where the report's own base differs. */
+export interface StakeToday {
+  /** Percent of today's shares outstanding. */
+  percent: number;
+  sharesOutstanding: number;
+}
+
 export interface BeneficialOwnerRow {
   id: string;
   filing: BeneficialOwnerFiling;
+  /** Who the row is: the reporting person whose stake it shows. */
+  holderName: string;
+  /** The other reporting persons on the same report: a group's members, a fund's adviser or principal. */
+  otherPersons: number;
+  /** The report's shares over today's count, when that count is no longer the report's base. */
+  today: StakeToday | null;
   /** `13G/A`: the kind, and `/A` for an amendment. */
   formLabel: string;
   /** Percent points against the filer's report before this one. */
@@ -93,6 +106,71 @@ export function thirteenFAction(holder: HolderRecord | undefined): ThirteenFActi
   return null;
 }
 
+const ALL_CAPS = /^[^a-z]*[A-Z][^a-z]*$/;
+
+function sameEntity(left: string, right: string): boolean {
+  const key = (name: string) => name.toLowerCase().replace(/[^a-z0-9 ]+/g, " ")
+    .replace(/\b(the|inc|llc|ltd|lp|llp|corp|corporation|co|company|plc|n a|s a)\b/g, " ").replace(/\s+/g, " ").trim();
+  return key(left) === key(right);
+}
+
+/**
+ * The name a row goes by, one rule for every report: the reporting person
+ * whose stake the row shows (the highest percent, then shares, the filer's
+ * own entry on a tie), not the EDGAR filer, which only some reports name.
+ * When that person is the filer and the cover spells it in capitals, the
+ * filer's own spelling is kept (`SRS Investment Management, LLC`).
+ */
+export function beneficialHolderName(
+  filing: Pick<BeneficialOwnerFiling, "filerName" | "filerCik" | "reportingPersons">,
+): string {
+  let best: BeneficialOwnerFiling["reportingPersons"][number] | null = null;
+  for (const person of filing.reportingPersons) {
+    if (!person.name.trim()) continue;
+    if (!best) { best = person; continue; }
+    const percent = person.percentOfClass ?? -1;
+    const bestPercent = best.percentOfClass ?? -1;
+    if (percent !== bestPercent) { if (percent > bestPercent) best = person; continue; }
+    const shares = person.shares ?? -1;
+    const bestShares = best.shares ?? -1;
+    if (shares !== bestShares) { if (shares > bestShares) best = person; continue; }
+    if (filing.filerCik && person.cik === filing.filerCik && best.cik !== filing.filerCik) best = person;
+  }
+  const name = best?.name.trim();
+  if (!name) return filing.filerName;
+  const isFiler = (!!filing.filerCik && best?.cik === filing.filerCik) || sameEntity(name, filing.filerName);
+  return isFiler && ALL_CAPS.test(name) && !ALL_CAPS.test(filing.filerName) ? filing.filerName : name;
+}
+
+/** Today's count against the report's own base outside this range is another class or unit, not the same shares. */
+const BASE_RANGE = [2 / 3, 3 / 2] as const;
+
+/**
+ * The report's shares as a percent of today's shares outstanding, when the
+ * count the filer divided by (shares over the filed percent) is no longer
+ * today's. A filed percent is rounded, so a gap within that rounding (0.1
+ * point, or 2% of the stake) is not a new count. Null for an exit, a report
+ * without both figures, or a count that cannot be this class's.
+ */
+export function stakeToday(
+  filing: Pick<BeneficialOwnerFiling, "shares" | "percentOfClass">,
+  sharesOutstanding: number | null | undefined,
+): StakeToday | null {
+  const { shares, percentOfClass: filed } = filing;
+  if (sharesOutstanding == null || !(sharesOutstanding > 0) || shares == null || !(shares > 0) || filed == null || !(filed > 0)) return null;
+  const base = shares / (filed / 100);
+  const ratio = base / sharesOutstanding;
+  if (ratio < BASE_RANGE[0] || ratio > BASE_RANGE[1]) return null;
+  const percent = (shares / sharesOutstanding) * 100;
+  if (Math.abs(percent - filed) < Math.max(0.1, filed * 0.02)) return null;
+  return { percent, sharesOutstanding };
+}
+
+/** `about 49.4% on 35.26M sh today`. */
+export function formatStakeToday(today: StakeToday): string {
+  return `about ${formatClassPercent(today.percent)} on ${formatCompact(today.sharesOutstanding)} sh today`;
+}
+
 function beneficialFormLabel(filing: Pick<BeneficialOwnerFiling, "kind" | "amendment">): string {
   return `${filing.kind}${filing.amendment ? "/A" : ""}`;
 }
@@ -110,10 +188,14 @@ export function buildBeneficialRows(
   filings: readonly BeneficialOwnerFiling[],
   holders: readonly JoinableHolder[] = [],
   fundMatches: ReadonlyMap<string, Pick<Holder13FMatch, "cik">> = new Map(),
+  sharesOutstanding?: number | null,
 ): BeneficialOwnerRow[] {
   return filings.map((filing) => ({
     id: `${filing.accessionNumber}:${filing.filerCik ?? filing.filerName}`,
     filing,
+    holderName: beneficialHolderName(filing),
+    otherPersons: Math.max(0, filing.reportingPersons.length - 1),
+    today: stakeToday(filing, sharesOutstanding),
     formLabel: beneficialFormLabel(filing),
     changePoints: pointChange(filing),
     thirteenF: thirteenFAction(matchFilerToHolder(filing, holders, fundMatches)),
@@ -123,7 +205,7 @@ export function buildBeneficialRows(
 
 function sortValue(row: BeneficialOwnerRow, columnId: BeneficialColumnId): string | number | null {
   switch (columnId) {
-    case "filer": return row.filing.filerName;
+    case "filer": return row.holderName;
     case "form": return row.formLabel;
     case "percentOfClass": return row.filing.percentOfClass;
     case "change": return row.changePoints;
@@ -148,7 +230,7 @@ export function sortBeneficialRows(rows: readonly BeneficialOwnerRow[], preferen
   return [...rows].sort((left, right) => stakeGroup(left) - stakeGroup(right)
     || compareSortValues(sortValue(left, preference.columnId), sortValue(right, preference.columnId), preference.direction)
     || right.filing.filingDate.localeCompare(left.filing.filingDate)
-    || left.filing.filerName.localeCompare(right.filing.filerName));
+    || left.holderName.localeCompare(right.holderName));
 }
 
 // Widths as the table draws them: never narrower than the header and its sort marker.
@@ -249,14 +331,19 @@ export function formatOwnerShares(value: number | null): string {
 export function beneficialReportRow(row: BeneficialOwnerRow) {
   const { filing } = row;
   return {
-    filer: filing.filerName,
+    filer: row.holderName,
+    /** The other reporting persons on the report, which text marks `+N` after the name. */
+    otherPersons: row.otherPersons,
     filerCik: filing.filerCik,
     form: row.formLabel,
     formType: filing.form,
     kind: filing.kind,
     amendment: filing.amendment,
     amendmentNo: filing.amendmentNo,
+    /** As filed: the filer's shares over the share count it used. */
     percentOfClass: filing.percentOfClass,
+    /** The same shares over today's shares outstanding, only when that count is no longer the report's base. */
+    percentToday: row.today ? Number(row.today.percent.toFixed(2)) : null,
     previousPercent: filing.previousPercent ?? null,
     changePoints: row.changePoints,
     shares: filing.shares,

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

@@ -5,6 +5,7 @@ import {
   buildBeneficialRows,
   DEFAULT_BENEFICIAL_SORT,
   formatClassPercent,
+  formatFilerName,
   formatOwnerShares,
   formatPointChange,
   stakeMarker,
@@ -13,6 +14,7 @@ import {
   type BeneficialSortPreference,
 } from "./beneficial-model";
 import { buildRows } from "./table-model";
+import { formatCompact } from "../../../utils/format";
 
 /** What `holders --form` lists: the 13F table, or the 13D/13G beneficial owners. */
 export type HolderForm = "13f" | "13d" | "13g" | "all";
@@ -27,9 +29,23 @@ export function beneficialRouteForm(form: Exclude<HolderForm, "13f">): Beneficia
   return form === "13d" ? "13D" : form === "13g" ? "13G" : "all";
 }
 
-/** Text columns for the 13D/13G rows; CSV and JSON keep the raw values. */
+const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+
+/**
+ * Columns for the 13D/13G rows. `textFormat` is what text prints (`holders
+ * --form` and `fn HDS --form`); `fn HDS --csv` reads `format`, and `holders
+ * --csv` and JSON keep the raw values. `% Class` is as filed; `% Today` is
+ * the same shares over today's count, only where that count is no longer the
+ * report's base.
+ */
 export const BENEFICIAL_REPORT_COLUMNS = [
-  { key: "filer", header: "Filer", maxWidth: 32 },
+  {
+    key: "filer",
+    header: "Filer",
+    maxWidth: 32,
+    // `+N` counts the report's other reporting persons; a long name gives way before it does.
+    textFormat: (value: unknown, row: Record<string, unknown>) => formatFilerName(String(value ?? ""), num(row.otherPersons) ?? 0, 32),
+  },
   { key: "form", header: "Form" },
   {
     key: "percentOfClass",
@@ -41,6 +57,13 @@ export const BENEFICIAL_REPORT_COLUMNS = [
       return marker ? `${formatClassPercent(value)} ${marker}` : formatClassPercent(value);
     },
   },
+  {
+    key: "percentToday",
+    header: "% Today",
+    align: "right" as const,
+    format: (value: unknown) => num(value) == null ? "" : `${num(value)!.toFixed(2)}%`,
+    textFormat: (value: unknown) => num(value) == null ? "" : `about ${formatClassPercent(num(value)!)}`,
+  },
   {
     key: "changePoints",
     header: "Chg",
@@ -58,6 +81,28 @@ export const BENEFICIAL_REPORT_COLUMNS = [
   { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : "-" },
 ];
 
+/** The 13D/13G columns these rows fill: `% Today` only when a report's base is no longer today's count. */
+export function beneficialReportColumns(rows: readonly BeneficialReportRow[]): typeof BENEFICIAL_REPORT_COLUMNS {
+  const today = rows.some((row) => row.percentToday != null);
+  return BENEFICIAL_REPORT_COLUMNS.filter((column) => today || column.key !== "percentToday");
+}
+
+/**
+ * The legend under the 13D/13G table, one line: the percent is as filed, what
+ * `% Today` divides by, and what `+N` after a name counts.
+ */
+export function beneficialReportLegend(
+  rows: readonly BeneficialReportRow[],
+  sharesOutstanding: number | null | undefined,
+): string | null {
+  if (rows.length === 0) return null;
+  const today = sharesOutstanding != null && rows.some((row) => row.percentToday != null)
+    ? `; % Today is the same shares over ${formatCompact(sharesOutstanding)} shares outstanding today`
+    : "";
+  const others = rows.some((row) => row.otherPersons > 0) ? " +N after a name: other reporting persons on the same report." : "";
+  return `% Class is as filed${today}.${others}`;
+}
+
 const filings = (count: number) => `${count} ${count === 1 ? "filing" : "filings"}`;
 
 /**
@@ -114,13 +159,20 @@ export function buildBeneficialReportRows(
     history = false,
     holders = null,
     sort = DEFAULT_BENEFICIAL_SORT,
-  }: { history?: boolean; holders?: HolderData | null; sort?: BeneficialSortPreference } = {},
+    sharesOutstanding = null,
+  }: {
+    history?: boolean;
+    holders?: HolderData | null;
+    sort?: BeneficialSortPreference;
+    /** Today's shares outstanding in the class's own unit, for `percentToday`. */
+    sharesOutstanding?: number | null;
+  } = {},
 ): BeneficialReportRow[] {
   const holderRows = buildRows(holders);
   if (history) {
     const filings = [...(payload.filings ?? payload.owners)]
       .sort((left, right) => right.filingDate.localeCompare(left.filingDate));
-    return buildBeneficialRows(filings, holderRows).map(beneficialReportRow);
+    return buildBeneficialRows(filings, holderRows, undefined, sharesOutstanding).map(beneficialReportRow);
   }
-  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows), sort).map(beneficialReportRow);
+  return sortBeneficialRows(buildBeneficialRows(payload.owners, holderRows, undefined, sharesOutstanding), sort).map(beneficialReportRow);
 }

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

@@ -1,5 +1,5 @@
 import { useCallback, useMemo, useState } from "react";
-import { TextAttributes, useRendererHost } from "../../../ui";
+import { Box, Text, TextAttributes, useRendererHost } from "../../../ui";
 import {
   DataTableView,
   EmptyState,
@@ -30,6 +30,7 @@ import {
   formatOwnerShares,
   formatPercentOfClass,
   formatPointChange,
+  formatStakeToday,
   sortBeneficialRows,
   stakeMarker,
   type BeneficialColumn,
@@ -42,6 +43,24 @@ import type { HolderRow } from "./types";
 
 const STALE_SEGMENT = { id: "stale", parts: [{ text: "stale", tone: "warning" as const }] };
 
+/**
+ * A table line: a filer's row, or the line beneath it giving the same shares
+ * against today's count when the report's base is no longer today's.
+ */
+type BeneficialItem =
+  | { kind: "row"; id: string; row: BeneficialOwnerRow }
+  | { kind: "today"; id: string; row: BeneficialOwnerRow };
+
+const isFilerItem = (item: BeneficialItem) => item.kind === "row";
+
+/** What the figures are, in one line under the table: the percent is as filed, `+N` counts other reporting persons. */
+function beneficialLegend(rows: readonly BeneficialOwnerRow[]): string | null {
+  if (rows.length === 0) return null;
+  return rows.some((row) => row.otherPersons > 0)
+    ? "% class as filed · +N other reporting persons on the same report"
+    : "% class as filed";
+}
+
 /**
  * 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
@@ -54,6 +73,7 @@ export function BeneficialOwnersView({
   symbol,
   holderRows,
   fundMatches,
+  sharesOutstanding,
   onCycleView,
   onRefreshHolders,
   listing,
@@ -65,6 +85,8 @@ export function BeneficialOwnersView({
   listing?: IssuerListingParams;
   holderRows: readonly HolderRow[];
   fundMatches: ReadonlyMap<string, Holder13FMatch>;
+  /** Today's shares outstanding, which a report's shares are set against when its own base is out of date. */
+  sharesOutstanding?: number | null;
   onCycleView: () => void;
   onRefreshHolders: () => void;
 }) {
@@ -90,10 +112,16 @@ export function BeneficialOwnersView({
   const payload = resource.data?.payload ?? null;
 
   const rows = useMemo(
-    () => buildBeneficialRows(payload?.owners ?? [], holderRows, fundMatches),
-    [fundMatches, holderRows, payload],
+    () => buildBeneficialRows(payload?.owners ?? [], holderRows, fundMatches, sharesOutstanding),
+    [fundMatches, holderRows, payload, sharesOutstanding],
   );
   const sortedRows = useMemo(() => sortBeneficialRows(rows, sortPreference), [rows, sortPreference]);
+  // A stake set against today's count reads on the line beneath its row.
+  const items = useMemo<BeneficialItem[]>(() => sortedRows.flatMap((row) => [
+    { kind: "row" as const, id: row.id, row },
+    ...(row.today ? [{ kind: "today" as const, id: `${row.id}:today`, row }] : []),
+  ]), [sortedRows]);
+  const legend = useMemo(() => beneficialLegend(sortedRows), [sortedRows]);
   const columns = useMemo(() => buildBeneficialColumns(width), [width]);
   const selectedRow = sortedRows.find((row) => row.id === selectedId) ?? sortedRows[0] ?? null;
 
@@ -101,6 +129,7 @@ export function BeneficialOwnersView({
     if (!row || !symbol) return;
     openSecFilingInPane({ createPaneFromTemplate }, symbol, row.filing.accessionNumber);
   }, [createPaneFromTemplate, symbol]);
+  const activateItem = useCallback((item: BeneficialItem) => openFiling(item.row), [openFiling]);
 
   const openFilingUrl = useCallback(() => {
     const url = selectedRow?.filing.filingUrl;
@@ -129,12 +158,20 @@ export function BeneficialOwnersView({
     }));
   }, [setSortPreference]);
 
+  const renderTodayLine = useCallback((item: BeneficialItem) => (
+    item.kind === "today" && item.row.today
+      // Indented under its row's name; no-break spaces, which the desktop table does not collapse.
+      ? { text: `\u00a0\u00a0${formatStakeToday(item.row.today)}`, color: colors.textDim, attributes: TextAttributes.NONE }
+      : null
+  ), []);
+
   const renderCell = useCallback((
-    row: BeneficialOwnerRow,
+    item: BeneficialItem,
     column: BeneficialColumn,
     _index: number,
     rowState: { selected: boolean },
   ): DataTableCell => {
+    const { row } = item;
     const { filing } = row;
     // A report of zero reads as history; a stake under 5% is still a stake.
     const exited = row.stake === "exited";
@@ -142,8 +179,8 @@ export function BeneficialOwnersView({
     switch (column.id) {
       case "filer":
         return {
-          text: formatFilerName(filing.filerName, Math.max(0, filing.reportingPersons.length - 1), column.width),
-          value: filing.filerName,
+          text: formatFilerName(row.holderName, row.otherPersons, column.width),
+          value: row.holderName,
           color: exited ? colors.textMuted : rowState.selected ? colors.selectedText : colors.textBright,
           attributes: exited ? undefined : TextAttributes.BOLD,
         };
@@ -218,24 +255,31 @@ export function BeneficialOwnersView({
       empty={!!payload && sortedRows.length === 0}
       emptyTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}
     >
-      <DataTableView<BeneficialOwnerRow, BeneficialColumn>
+      <DataTableView<BeneficialItem, BeneficialColumn>
         focused={focused}
         selection={{
           kind: "id",
           selectedId: selectedRow?.id ?? null,
-          getId: (row) => row.id,
+          getId: (item) => item.id,
           onChange: (id) => setSelectedId(id),
         }}
-        onActivate={openFiling}
+        isNavigable={isFilerItem}
+        onActivate={activateItem}
         onRootKeyDown={handleKeyDown}
         resetScrollKey={symbol}
         rootWidth={width}
+        rootAfter={legend ? (
+          <Box paddingX={1} height={1} flexShrink={0}>
+            <Text fg={colors.textDim}>{legend}</Text>
+          </Box>
+        ) : undefined}
         columns={columns}
-        items={sortedRows}
+        items={items}
         sortColumnId={sortPreference.columnId}
         sortDirection={sortPreference.direction}
         onHeaderClick={handleHeaderClick}
-        getItemKey={(row) => row.id}
+        getItemKey={(item) => item.id}
+        renderSectionHeader={renderTodayLine}
         renderCell={renderCell}
         selectedTextOverridesCellColor
         emptyStateTitle={`No 13D/13G filings in the last 4 years for ${symbol}.`}

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

@@ -1,5 +1,5 @@
 import type { DataProvider, MarketDataRequestContext } from "../../../types/data-provider";
-import type { HolderData } from "../../../types/financials";
+import type { HolderData, TickerFinancials } from "../../../types/financials";
 import { holderStakeMarketCap, holderValueCurrency } from "./format";
 
 export async function loadHolderData(
@@ -12,15 +12,34 @@ export async function loadHolderData(
   return provider.getHolders(symbol, exchange, context);
 }
 
+/**
+ * Today's shares outstanding in ordinary shares, the count a 13D/13G percent
+ * of class divides; on a depositary receipt the ordinary shares behind it,
+ * or null when they are not given.
+ */
+export function classSharesToday(financials: Pick<TickerFinancials, "quote" | "fundamentals"> | null | undefined): number | null {
+  const fundamentals = financials?.fundamentals;
+  if (!fundamentals) return null;
+  const receipt = fundamentals.shareBasis === "depositary_receipt"
+    || fundamentals.isDepositaryReceipt === true
+    || financials?.quote?.isDepositaryReceipt === true;
+  const count = receipt ? fundamentals.underlyingOrdinaryShares : fundamentals.sharesOutstanding;
+  return count != null && Number.isFinite(count) && count > 0 ? count : null;
+}
+
 export async function loadHolderSnapshot(
   provider: DataProvider,
   symbol: string,
   exchange = "",
-): Promise<{ data: HolderData; marketCap?: number }> {
+): Promise<{ data: HolderData; marketCap?: number; sharesOutstanding?: number | null }> {
   const [data, financials] = await Promise.all([
     loadHolderData(provider, symbol, exchange),
     provider.getTickerFinancials(symbol, exchange).catch(() => null),
   ]);
   const quote = financials?.quote;
-  return { data, marketCap: holderStakeMarketCap(quote?.marketCap, quote?.currency, holderValueCurrency(data)) };
+  return {
+    data,
+    marketCap: holderStakeMarketCap(quote?.marketCap, quote?.currency, holderValueCurrency(data)),
+    sharesOutstanding: classSharesToday(financials),
+  };
 }

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

@@ -50,14 +50,29 @@ export function resolveHolderOwnershipPercent(row: Pick<HolderRecord, "percentHe
   return row.value / marketCap;
 }
 
-/** A stake too small for two decimals reads "<0.01%", not a zero. */
-export function formatHolderOwnershipPercent(value: number | undefined): string {
-  if (value == null) return "-";
+/**
+ * A stake or a change in percent (0.59 for 0.59%), as reports carry it. A
+ * source gives a fraction (0.0059) or, above 1, percent points; the pane reads
+ * them the same way. Six significant digits drop a source's float noise.
+ */
+export function holderPercent(value: number | null | undefined): number | null {
+  if (value == null || !Number.isFinite(value)) return null;
   const percent = Math.abs(value) <= 1 ? value * 100 : value;
+  return Number(percent.toPrecision(6));
+}
+
+/** A stake in percent too small for two decimals reads "<0.01%", not a zero. */
+export function formatPercentHeld(percent: number | null | undefined): string {
+  if (percent == null) return "-";
   if (percent > 0 && percent < 0.005) return "<0.01%";
   return `${percent.toFixed(2)}%`;
 }
 
+/** A stake too small for two decimals reads "<0.01%", not a zero. */
+export function formatHolderOwnershipPercent(value: number | undefined): string {
+  return formatPercentHeld(holderPercent(value));
+}
+
 export function formatHolderOwnershipLine(row: HolderRow, marketCap: number | undefined): string | null {
   const ownership = resolveHolderOwnershipPercent(row, marketCap);
   return ownership == null ? null : `${formatHolderOwnershipPercent(ownership)} held`;