gloomberb 0.16.2 → 0.16.3

package/src/ui/index.tsx

@@ -1,6 +1,7 @@
 import { createElement, forwardRef, useCallback, useRef, type ComponentProps } from "react";
 import { useForwardedScrollBoxRef, useRegisterPaneScrollBox } from "../state/pane-scroll-registry";
 import { useUiHost, type UiHost } from "./host";
+import { scrollBoxScrollsVertically } from "./scroll-box-axis";
 import { useRemoteUiNode } from "../remote/semantic-tree";
 import { assignRef } from "../react/assign-ref";
 import {
@@ -48,6 +49,7 @@ export type {
   MediaSurfaceHandle,
   MediaSurfaceProps,
   InputRenderable,
+  LiveBoxFrame,
   NativeCursorState,
   NativeRendererHost,
   NativePostProcessFn,
@@ -128,8 +130,11 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
   const { ScrollBox: HostScrollBox } = useUiHost();
   const localRef = useForwardedScrollBoxRef<any>(ref);
   const rawProps = props as Record<string, unknown>;
+  // The same rule the hosts scroll by: a ScrollBox that omits scrollY scrolls,
+  // so it is a scrollbox to the remote tree and to the pane scroll keys.
+  const scrollsVertically = scrollBoxScrollsVertically(props);
   const remoteNodeId = useRemoteUiNode(
-    props.scrollY === true
+    scrollsVertically
       ? {
         role: remotePropRole(rawProps, "scrollbox"),
         label: remotePropLabel(rawProps),
@@ -150,7 +155,7 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
           ...remoteMetadataFromProps(rawProps),
           width: rawProps.width,
           height: rawProps.height,
-          scrollY: props.scrollY === true,
+          scrollY: true,
           scrollTop: localRef.current?.scrollTop,
           viewportHeight: localRef.current?.viewport?.height,
         },
@@ -158,7 +163,7 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
       : null,
   );
   useRegisterPaneScrollBox(localRef, {
-    enabled: props.scrollY === true,
+    enabled: scrollsVertically,
     onScrollActivity: typeof props.onMouseScroll === "function"
       ? props.onMouseScroll as (event: { scroll: { direction: "up" | "down"; delta: number } }) => void
       : undefined,

package/src/ui/scroll-box-axis.ts

@@ -0,0 +1,26 @@
+/**
+ * Which axes a ScrollBox scrolls on, decided from its props. The terminal and
+ * DOM hosts and the pane keyboard scroll registration all read it here, so a
+ * ScrollBox that omits `scrollY` behaves the same everywhere: it scrolls
+ * vertically, with the wheel and with the arrows, PageUp, PageDown, Home and
+ * End. Pass `scrollY={false}` to turn that off.
+ */
+interface ScrollBoxAxisProps {
+  scrollX?: unknown;
+  scrollY?: unknown;
+  height?: unknown;
+}
+
+/**
+ * A one-row strip that only scrolls sideways: tab bars, table headers and
+ * chart legends. It is not a vertical scroller even though `scrollY` is
+ * omitted.
+ */
+export function isHeaderStripScrollBox(props: ScrollBoxAxisProps): boolean {
+  return props.scrollX === true && props.scrollY !== true && props.height === 1;
+}
+
+/** Whether the ScrollBox scrolls vertically: unless `scrollY` is false, and never a header strip. */
+export function scrollBoxScrollsVertically(props: ScrollBoxAxisProps): boolean {
+  return props.scrollY !== false && !isHeaderStripScrollBox(props);
+}

package/src/utils/currency-units.ts

@@ -13,11 +13,16 @@ const SUB_UNIT_NAMES: Record<string, string> = {
   ZAc: "cents",
 };
 
-/** A currency code as a reader should see it; a sub-unit says which one: "GBp (pence)". */
-export function currencyUnitLabel(code?: string | null): string {
+/**
+ * A currency code as a reader should see it; a sub-unit says which one,
+ * "GBp (pence)", and with `ofMajor` what it divides: "ILA (agorot, 1/100 ILS)".
+ */
+export function currencyUnitLabel(code?: string | null, { ofMajor = false }: { ofMajor?: boolean } = {}): string {
   const raw = (code ?? "").trim();
   const unit = SUB_UNIT_NAMES[raw];
-  return unit ? `${raw} (${unit})` : raw;
+  const major = SUB_UNIT_CURRENCIES[raw];
+  if (!unit) return raw;
+  return ofMajor && major ? `${raw} (${unit}, 1/${major.divisor} ${major.currency})` : `${raw} (${unit})`;
 }
 
 const LIKELY_UNIT_MISMATCH_RATIOS: Record<string, number[]> = {

package/src/utils/depositary-receipt.ts

@@ -1,26 +1,70 @@
+import type { Fundamentals, Quote, ShareBasis } from "../types/financials";
+
 // A word of its own, so a company called "ADS-TEC" is not one.
 const DEPOSITARY_NAME = /(?:^|\s)(?:ADRs?|ADSs?|American depositary (?:receipts?|shares?))(?=$|[\s,)])/i;
 const DEPOSITARY_TYPES = new Set(["ADR", "ADS", "DEPOSITARYRECEIPT"]);
 /** A profile that opens by naming the security: "Toyota Motor Corporation Sponsored ADR is ...". */
 const DEPOSITARY_SUBJECT = /^.{0,160}?\s(?:ADRs?|ADSs?|American depositary (?:receipts?|shares?)) is\s/i;
 
-/**
- * Whether a US listing is a depositary receipt, as far as its data says. A
- * quote carries no ADR flag or ratio, so this reads the instrument type, the
- * name, and the security name a profile description opens with. Its share
- * count and market cap are then counted in receipts, not ordinary shares. A
- * listing in another currency is the ordinary line even when its profile
- * mentions the receipts.
- */
-export function isDepositaryReceipt(input: {
+interface ListingEvidence {
+  /** Gloom Cloud's verdict; absent when it has no evidence either way. */
+  isDepositaryReceipt?: boolean | null;
   instrumentType?: string | null;
   name?: string | null;
   currency?: string | null;
   description?: string | null;
-}): boolean {
+}
+
+/**
+ * Whether a listing is a depositary receipt. Gloom Cloud's flag decides when
+ * it is set. Without it (an older service, or a listing it has no evidence
+ * for) this reads the instrument type, the name, and the security name a
+ * profile description opens with. A listing in another currency is the
+ * ordinary line even when its profile mentions the receipts.
+ */
+export function isDepositaryReceipt(input: ListingEvidence): boolean {
+  if (typeof input.isDepositaryReceipt === "boolean") return input.isDepositaryReceipt;
   const currency = input.currency?.trim().toUpperCase();
   if (currency && currency !== "USD") return false;
   if (DEPOSITARY_TYPES.has((input.instrumentType ?? "").replace(/[\s_-]/g, "").toUpperCase())) return true;
   if (input.name && DEPOSITARY_NAME.test(input.name)) return true;
   return DEPOSITARY_SUBJECT.test(input.description?.trim() ?? "");
 }
+
+/**
+ * Whether a record's share counts are in receipts. Gloom Cloud says so with
+ * `shareBasis`; without it, a receipt's counts are read as receipts, as its
+ * market cap is.
+ */
+function sharesInReceipts(input: ListingEvidence & { shareBasis?: ShareBasis | null }): boolean {
+  if (input.shareBasis === "depositary_receipt") return true;
+  if (input.shareBasis === "ordinary") return false;
+  return isDepositaryReceipt(input);
+}
+
+/**
+ * Whether a listing's shares outstanding are counted in receipts: the
+ * fundamentals' basis, else the listing's flag (the fundamentals' or the
+ * quote's), else what the quote and profile say.
+ */
+export function sharesOutstandingInReceipts(
+  quote: Pick<Quote, "isDepositaryReceipt" | "instrumentType" | "name" | "currency"> | null | undefined,
+  fundamentals: Pick<Fundamentals, "isDepositaryReceipt" | "shareBasis"> | null | undefined,
+  description?: string | null,
+): boolean {
+  return sharesInReceipts({
+    instrumentType: quote?.instrumentType,
+    name: quote?.name,
+    currency: quote?.currency,
+    description,
+    isDepositaryReceipt: fundamentals?.isDepositaryReceipt ?? quote?.isDepositaryReceipt,
+    shareBasis: fundamentals?.shareBasis,
+  });
+}
+
+/** "1 ADR = 2 ordinary shares", or null without a usable ratio. */
+export function adrRatioText(ratio: number | null | undefined): string | null {
+  if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0) return null;
+  const count = Number.isInteger(ratio) ? String(ratio) : String(Number(ratio.toPrecision(6)));
+  return `1 ADR = ${count} ordinary share${ratio === 1 ? "" : "s"}`;
+}

package/src/utils/display-number.ts

@@ -0,0 +1,63 @@
+/**
+ * Reading back a number a table or report drew ("+1.25%", "1.20B", "$1,234.50"),
+ * so a CSV export can write the number a spreadsheet uses and name the unit
+ * in its header instead of in every cell.
+ */
+
+/** What a cell draws for a missing value: a dash, a run of dashes, or the loading ellipsis. */
+export const DISPLAY_PLACEHOLDER = /^(?:[-\u2013\u2014]{1,3}|\u2026|\.\.\.)$/;
+
+/**
+ * A number as a table draws it: sign, currency symbol, thousands commas,
+ * decimals, a compact scale (12.3k, 1.20B) and a unit (%, x, bp, USD, or c
+ * for the cents grain futures quote in).
+ */
+const DISPLAY_NUMBER = /^([+-]?)([A-Z]{0,3}[$\u20ac\u00a3\u00a5\u20b9\u20a9\u20bd\u20ba\u20aa\u20ab\u0e3f])?(?=\.?\d)(\d{1,3}(?:,\d{3})+|\d*)(?:\.(\d+))?([kKMBT])?(%|x|c|\u00a2| ?bps?| [A-Z]{3})?$/;
+
+const SCALE_DIGITS: Record<string, number> = { k: 3, K: 3, M: 6, B: 9, T: 12 };
+
+export interface DisplayNumber {
+  /** Plain decimal text: no sign for positives, no commas, no scale letter. */
+  number: string;
+  /** What the column header has to name once the cells are bare numbers. */
+  unit: string;
+  /** The place value of the last digit drawn: 0.01 for "1.25%", 10,000,000 for "1.20B". */
+  step: number;
+}
+
+export const BLANK_DISPLAY = "blank";
+
+/** Moves the decimal point right without going through a float, so 1.23B is exactly 1230000000. */
+function scaleDecimal(integer: string, fraction: string, digits: number): string {
+  const whole = `${integer}${fraction.padEnd(digits, "0").slice(0, digits)}`.replace(/^0+(?=\d)/, "") || "0";
+  const rest = fraction.slice(digits);
+  return rest ? `${whole}.${rest}` : whole;
+}
+
+export function parseDisplayNumber(text: string): DisplayNumber | typeof BLANK_DISPLAY | null {
+  // A direction arrow beside a signed move repeats the sign.
+  const trimmed = text.trim().replace(/\u2212/g, "-").replace(/\s*[\u2191\u2193]$/, "");
+  if (!trimmed || DISPLAY_PLACEHOLDER.test(trimmed)) return BLANK_DISPLAY;
+  const match = DISPLAY_NUMBER.exec(trimmed);
+  if (!match) return null;
+  const [, sign, currency = "", grouped, fraction = "", scale, unitText = ""] = match;
+  const integer = grouped!.replace(/,/g, "") || "0";
+  const digits = scale ? SCALE_DIGITS[scale]! : 0;
+  const magnitude = digits ? scaleDecimal(integer, fraction, digits) : fraction ? `${integer}.${fraction}` : integer;
+  const unit = unitText.trim().replace(/^bps$/, "bp").replace(/^\u00a2$/, "c");
+  return {
+    number: `${sign === "-" ? "-" : ""}${magnitude}`,
+    unit: [currency, unit].filter(Boolean).join(" "),
+    step: 10 ** (digits - fraction.length),
+  };
+}
+
+/** Adds the unit the cells dropped, unless the label already names it. */
+export function labelWithUnit(label: string, unit: string): string {
+  if (!unit) return label;
+  // A word unit has to stand alone: "Max" does not name x.
+  const named = unit === "bp" ? /\bbps?\b/i.test(label)
+    : /^[A-Za-z]+$/.test(unit) ? new RegExp(`\\b${unit}\\b`, "i").test(label)
+      : label.includes(unit);
+  return named ? label : `${label} (${unit})`;
+}

package/src/utils/fundamentals.ts

@@ -1,4 +1,4 @@
-import type { Fundamentals } from "../types/financials";
+import type { Fundamentals, TickerFinancials } from "../types/financials";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
 
@@ -13,3 +13,19 @@ export function redactUnavailableFundamentals(value: Fundamentals | undefined):
   for (const field of unavailableFields) delete result[field];
   return result;
 }
+
+/** A source's enterprise value, or undefined when it has none: banks and insurers come back as 0, which is a gap, not a value. */
+export function reportedEnterpriseValue(fundamentals: Pick<Fundamentals, "enterpriseValue"> | undefined): number | undefined {
+  const value = fundamentals?.enterpriseValue;
+  return typeof value === "number" && Number.isFinite(value) && value !== 0 ? value : undefined;
+}
+
+/**
+ * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare, else the
+ * one the statements report in. Never the quote's, which a depositary receipt can differ from (USD quote, TWD books).
+ */
+export function fundamentalsCurrency(
+  financials: Pick<TickerFinancials, "fundamentals" | "financialCurrency"> | null | undefined,
+): string | undefined {
+  return financials?.fundamentals?.financialCurrency?.trim() || financials?.financialCurrency?.trim() || undefined;
+}

package/src/utils/price-history-integrity.ts

@@ -27,13 +27,26 @@ function above(left: number, right: number): boolean {
   return left - right > 8 * Number.EPSILON * Math.max(Math.abs(left), Math.abs(right));
 }
 
-/** Missing OHLC fields are not contradictory: close-only histories remain usable. */
-export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
+/**
+ * Each way a bar's prices contradict each other, as short codes such as
+ * `high<open` or `low>close`; empty when they agree. Missing OHLC fields are
+ * not contradictory: close-only histories remain usable.
+ */
+export function pricePointIntegrityFlags(point: PricePoint): string[] {
   const { open, high, low, close } = point;
-  const invalid = (isFiniteNumber(high) && isFiniteNumber(low) && above(low, high))
-    || [open, close].some((value) => isFiniteNumber(value)
-      && ((isFiniteNumber(high) && above(value, high)) || (isFiniteNumber(low) && above(low, value))));
-  if (!invalid) return undefined;
+  const flags: string[] = [];
+  for (const [name, value] of [["open", open], ["close", close]] as const) {
+    if (isFiniteNumber(value) && isFiniteNumber(high) && above(value, high)) flags.push(`high<${name}`);
+  }
+  for (const [name, value] of [["open", open], ["close", close]] as const) {
+    if (isFiniteNumber(value) && isFiniteNumber(low) && above(low, value)) flags.push(`low>${name}`);
+  }
+  if (isFiniteNumber(high) && isFiniteNumber(low) && above(low, high)) flags.push("low>high");
+  return flags;
+}
+
+export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
+  if (pricePointIntegrityFlags(point).length === 0) return undefined;
   const date = new Date(point.date);
   return Object.freeze({
     reason: "inconsistent-ohlc",