gloomberb 0.15.2 → 0.15.4

package/src/plugins/builtin/ipo-calendar/headless.ts

@@ -0,0 +1,159 @@
+import type { IpoCalendarPayload, IpoDeal, IpoStatus } from "../../../api-client/ipo";
+import type {
+  HeadlessPaneColumn,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+  HeadlessRowsResult,
+} from "../../../types/plugin";
+import { fetchIpoCalendar } from "./client";
+import {
+  filterIpoDeals,
+  formatIpoPrice,
+  formatIpoReturn,
+  formatIpoSize,
+  IPO_STATUSES,
+  isIpoTab,
+  marketsBehind,
+  marketsBehindText,
+  sortIpoDeals,
+  DEFAULT_IPO_SORT,
+  type IpoTab,
+} from "./model";
+
+const COLUMNS: HeadlessPaneColumn[] = [
+  { key: "ticker", header: "Ticker" },
+  { key: "company", header: "Company" },
+  { key: "venue", header: "Market" },
+  { key: "listingDate", header: "Date" },
+  { key: "status", header: "Status" },
+  { key: "price", header: "Price", align: "right" },
+  { key: "offerSizeUsd", header: "Size", align: "right", format: (value) => formatIpoSize(value as number | null) },
+  { key: "firstDayReturn", header: "Return", align: "right", format: (value) => formatIpoReturn(value as number | null) },
+];
+
+type StatusOption = IpoStatus | "all";
+
+function regionOption(args: HeadlessPaneLoadArgs): IpoTab {
+  const value = args.options.region;
+  return isIpoTab(value) ? value : "all";
+}
+
+function statusOption(args: HeadlessPaneLoadArgs): StatusOption {
+  const value = String(args.options.status ?? "all");
+  return (IPO_STATUSES as readonly string[]).includes(value) ? value as IpoStatus : "all";
+}
+
+function toRow(deal: IpoDeal) {
+  return {
+    id: deal.id,
+    ticker: deal.symbol,
+    exchange: deal.exchange,
+    mic: deal.mic,
+    company: deal.company,
+    companyLocal: deal.companyLocal,
+    venue: deal.venue,
+    segment: deal.segment,
+    country: deal.country,
+    region: deal.region,
+    listingDate: deal.listingDate,
+    dateKind: deal.dateKind,
+    subscriptionOpen: deal.subscriptionOpen,
+    subscriptionClose: deal.subscriptionClose,
+    status: deal.status,
+    listingType: deal.listingType,
+    currency: deal.currency,
+    price: formatIpoPrice(deal),
+    priceLow: deal.priceLow,
+    priceHigh: deal.priceHigh,
+    offerPrice: deal.offerPrice,
+    sharesOffered: deal.sharesOffered,
+    offerSize: deal.offerSize,
+    offerSizeUsd: deal.offerSizeUsd,
+    firstDayClose: deal.firstDay?.close ?? null,
+    firstDayReturn: deal.firstDay?.returnPct ?? null,
+    filedDate: deal.filedDate,
+  };
+}
+
+export function projectIpoCalendarHeadless(payload: IpoCalendarPayload, args: HeadlessPaneLoadArgs): HeadlessRowsResult {
+  const query = typeof args.argument === "string" ? args.argument.trim() : "";
+  const region = regionOption(args);
+  const status = statusOption(args);
+  const limit = Number(args.options.limit ?? 50);
+  const matching = sortIpoDeals(
+    filterIpoDeals(payload.deals, region, query).filter((deal) => status === "all" || deal.status === status),
+    DEFAULT_IPO_SORT,
+  );
+  const rows = matching.slice(0, limit).map(toRow);
+  const behind = marketsBehindText(marketsBehind(payload.sources, region, payload.deals));
+  return {
+    columns: COLUMNS,
+    rows,
+    ...(behind ? { errors: [behind] } : {}),
+    metadata: {
+      asOf: payload.asOf,
+      total: matching.length,
+      returned: rows.length,
+      truncated: rows.length < matching.length,
+      query: query || null,
+      region,
+      status,
+    },
+  };
+}
+
+export const ipoCalendarHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows",
+  argument: {
+    kind: "free-text",
+    placeholder: "company or ticker",
+    description: "Optional company, ticker, market, country or status filter.",
+    optional: true,
+  },
+  discovery: {
+    dataRequirements: ["Gloom Cloud IPO calendar, merged from each exchange's own listings"],
+    limitations: ["First-day return needs an offer price and the first session's close"],
+  },
+  options: [
+    {
+      key: "region",
+      description: "Region of the listing venue.",
+      type: "enum",
+      defaultValue: "all",
+      values: ["all", "us", "apac", "europe"].map((value) => ({ value })),
+      // The pane's tab, so a screenshot shows the region the report lists.
+      pluginState: { pluginId: "ipo-calendar", key: "region" },
+    },
+    {
+      key: "status",
+      description: "IPO stage to include.",
+      type: "enum",
+      defaultValue: "all",
+      // `trading` was the plugin's word for a deal that has listed.
+      values: ["all", ...IPO_STATUSES].map((value) => (value === "listed" ? { value, aliases: ["trading"] } : { value })),
+    },
+    {
+      key: "limit",
+      description: "Maximum IPO rows to return.",
+      type: "integer",
+      defaultValue: 50,
+      minimum: 1,
+      maximum: 500,
+    },
+  ],
+  columns: COLUMNS,
+  describe: (args) => {
+    const parts = ["IPO Calendar"];
+    const region = regionOption(args);
+    const status = statusOption(args);
+    if (region !== "all") parts.push(region === "us" ? "US" : region === "apac" ? "APAC" : "Europe");
+    if (status !== "all") parts.push(status);
+    return parts.join(" | ");
+  },
+  async load(args, ctx) {
+    // The default window has no filed or withdrawn deals, so a stage is asked for by name.
+    const status = statusOption(args);
+    const params = status === "all" ? {} : { status };
+    return projectIpoCalendarHeadless(await fetchIpoCalendar(ctx.apiClient, ctx.signal, params), args);
+  },
+};

package/src/plugins/builtin/ipo-calendar/index.tsx

@@ -0,0 +1,47 @@
+import type { GloomPlugin } from "../../../types/plugin";
+import { ipoCalendarCache } from "./client";
+import { ipoCalendarHeadless } from "./headless";
+import { IPO_CALENDAR_PANE_ID } from "./model";
+import { IpoCalendarPane } from "./pane";
+
+export const ipoCalendarPlugin: GloomPlugin = {
+  id: "ipo-calendar",
+  name: "IPO Calendar",
+  version: "1.0.0",
+  description: "Upcoming and recent IPOs worldwide",
+  toggleable: true,
+
+  setup(ctx) {
+    ipoCalendarCache.attach(ctx.persistence);
+  },
+
+  dispose() {
+    ipoCalendarCache.reset();
+  },
+
+  panes: [
+    {
+      id: IPO_CALENDAR_PANE_ID,
+      name: "IPO Calendar",
+      icon: "I",
+      component: IpoCalendarPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 110, height: 28 },
+      tableExport: true,
+    },
+  ],
+
+  paneTemplates: [
+    {
+      id: "ipo-calendar-pane",
+      paneId: IPO_CALENDAR_PANE_ID,
+      label: "IPO Calendar",
+      description: "Upcoming and recent IPOs in the US, Asia-Pacific and Europe: offer price, deal size and first-day return.",
+      keywords: ["ipo", "ipos", "initial", "public", "offering", "new", "listing", "listings", "debut", "flotation", "float"],
+      shortcut: { prefix: "IPO" },
+      headless: ipoCalendarHeadless,
+      createInstance: () => ({ placement: "floating" }),
+    },
+  ],
+};

package/src/plugins/builtin/ipo-calendar/model.ts

@@ -0,0 +1,341 @@
+import type { IpoDeal, IpoRegion, IpoSourceHealth, IpoStatus } from "../../../api-client/ipo";
+import type { DataTableColumn } from "../../../components";
+import { getTableWidth } from "../../../components/ui/table-layout";
+import { publicTickerKey } from "../../../utils/exchanges";
+import { displayWidth, formatCompact } from "../../../utils/format";
+import { compareSortValues, type SortPreference } from "../../../utils/sort-values";
+
+export const IPO_CALENDAR_PANE_ID = "ipo-calendar";
+export const MISSING = "—";
+
+export type IpoTab = "all" | Exclude<IpoRegion, "other">;
+
+/** Deals outside the three regions show only under All. */
+export const IPO_TABS: readonly { value: IpoTab; label: string }[] = [
+  { value: "all", label: "All" },
+  { value: "us", label: "US" },
+  { value: "apac", label: "APAC" },
+  { value: "europe", label: "Europe" },
+];
+
+export function isIpoTab(value: unknown): value is IpoTab {
+  return IPO_TABS.some((tab) => tab.value === value);
+}
+
+/** Every status, in the order a deal moves through them. */
+export const IPO_STATUSES: readonly IpoStatus[] = ["filed", "upcoming", "priced", "listed", "postponed", "withdrawn"];
+
+/**
+ * The market each venue answers to when its data is behind. A venue the
+ * server adds later reads as its MIC until it has a name here.
+ */
+const MARKETS: Record<string, { market: string; region: IpoRegion }> = {
+  XNAS: { market: "US", region: "us" },
+  XNYS: { market: "US", region: "us" },
+  XASE: { market: "US", region: "us" },
+  XHKG: { market: "Hong Kong", region: "apac" },
+  XSHG: { market: "China", region: "apac" },
+  XSHE: { market: "China", region: "apac" },
+  XNSE: { market: "India", region: "apac" },
+  XTKS: { market: "Japan", region: "apac" },
+  XASX: { market: "Australia", region: "apac" },
+  XLON: { market: "UK", region: "europe" },
+  XPAR: { market: "France", region: "europe" },
+  XAMS: { market: "Netherlands", region: "europe" },
+  XBRU: { market: "Belgium", region: "europe" },
+  XLIS: { market: "Portugal", region: "europe" },
+  XMIL: { market: "Italy", region: "europe" },
+  XDUB: { market: "Ireland", region: "europe" },
+  XOSL: { market: "Norway", region: "europe" },
+  XSTO: { market: "Sweden", region: "europe" },
+  XHEL: { market: "Finland", region: "europe" },
+  XCSE: { market: "Denmark", region: "europe" },
+  XSWX: { market: "Switzerland", region: "europe" },
+  XETR: { market: "Germany", region: "europe" },
+  XFRA: { market: "Germany", region: "europe" },
+};
+
+/**
+ * Markets the board cannot vouch for on this tab: a venue is behind when no
+ * source covering it answered, so a failed cross-check alone behind a working
+ * exchange feed is not a gap.
+ */
+export function marketsBehind(sources: readonly IpoSourceHealth[], tab: IpoTab, deals: readonly IpoDeal[] = []): string[] {
+  const covered = new Map<string, boolean>();
+  for (const source of sources) {
+    for (const mic of source.mics) covered.set(mic, (covered.get(mic) ?? false) || source.ok);
+  }
+  const markets: string[] = [];
+  for (const [mic, ok] of covered) {
+    if (ok) continue;
+    const known = MARKETS[mic];
+    const region = known?.region ?? deals.find((deal) => deal.mic === mic)?.region ?? "other";
+    if (tab !== "all" && region !== tab) continue;
+    const market = known?.market ?? mic;
+    if (!markets.includes(market)) markets.push(market);
+  }
+  return markets;
+}
+
+/** "India not updated", "UK, Switzerland and Germany not updated", "UK, France and 3 more not updated". */
+export function marketsBehindText(markets: readonly string[]): string | null {
+  if (markets.length === 0) return null;
+  if (markets.length === 1) return `${markets[0]} not updated`;
+  const named = markets.length <= 3
+    ? `${markets.slice(0, -1).join(", ")} and ${markets.at(-1)}`
+    : `${markets.slice(0, 2).join(", ")} and ${markets.length - 2} more`;
+  return `${named} not updated`;
+}
+
+const countryNames = new Map<string, string>();
+let regionNames: Intl.DisplayNames | null | undefined;
+
+/** "Japan" for JP, so a search can name the country. */
+function countryName(code: string): string {
+  let name = countryNames.get(code);
+  if (name === undefined) {
+    try {
+      regionNames ??= new Intl.DisplayNames(["en"], { type: "region" });
+      name = regionNames.of(code) ?? "";
+    } catch {
+      name = "";
+    }
+    countryNames.set(code, name);
+  }
+  return name;
+}
+
+/** Company in either script, symbol, venue, country code or name, and status. */
+export function matchesIpoQuery(deal: IpoDeal, query: string): boolean {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return true;
+  return [
+    deal.company, deal.companyLocal, deal.symbol, deal.venue, deal.mic, deal.exchange,
+    deal.country, countryName(deal.country), deal.segment, deal.status,
+  ].some((value) => !!value && value.toLowerCase().includes(needle));
+}
+
+export function filterIpoDeals(deals: readonly IpoDeal[], tab: IpoTab, query = ""): IpoDeal[] {
+  return deals.filter((deal) => (tab === "all" || deal.region === tab) && matchesIpoQuery(deal, query));
+}
+
+export type IpoColumnId = "ticker" | "company" | "market" | "date" | "status" | "price" | "size" | "return";
+export type IpoColumn = DataTableColumn & { id: IpoColumnId };
+export type IpoSortPreference = SortPreference<IpoColumnId>;
+
+/** No column: the calendar's own order. */
+export const DEFAULT_IPO_SORT: IpoSortPreference = { columnId: null, direction: "asc" };
+
+/** Upcoming first, then what priced or listed, then the pipeline, then deals that stopped. */
+function calendarGroup(status: IpoStatus): number {
+  switch (status) {
+    case "upcoming": return 0;
+    case "priced":
+    case "listed": return 1;
+    case "filed": return 2;
+    case "postponed":
+    case "withdrawn": return 3;
+  }
+}
+
+/**
+ * The date a deal sorts by in its group. An upcoming deal still in book
+ * building may have its subscription window before a listing date, and a
+ * deal priced on a Shenzhen or ASX book may have no listing date yet.
+ */
+export function calendarDate(deal: IpoDeal): string | null {
+  switch (deal.status) {
+    case "upcoming": return deal.listingDate ?? deal.subscriptionClose ?? deal.subscriptionOpen;
+    case "priced":
+    case "listed": return deal.listingDate ?? deal.firstDay?.session ?? deal.subscriptionClose ?? deal.subscriptionOpen;
+    case "filed": return deal.filedDate ?? deal.listingDate;
+    default: return deal.listingDate ?? deal.filedDate;
+  }
+}
+
+/** Upcoming deals soonest first; everything after them most recent first. */
+/** Days past its date before an upcoming deal counts as late rather than next. */
+const LATE_AFTER_DAYS = 7;
+
+/** Today's date where the board is read, YYYY-MM-DD. */
+function localToday(now = new Date()): string {
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+
+function daysBefore(date: string, days: number): string {
+  const day = new Date(`${date}T00:00:00Z`);
+  day.setUTCDate(day.getUTCDate() - days);
+  return day.toISOString().slice(0, 10);
+}
+
+/**
+ * Upcoming deals: the ones still ahead soonest first, then undated ones, then
+ * the ones a week or more past their date and still not listed (a pending
+ * HKEX listing, a book listing elsewhere), most recent first, so the board
+ * opens on what is next. Everything after them most recent first.
+ */
+function calendarOrder(today: string): (a: IpoDeal, b: IpoDeal) => number {
+  const lateBefore = daysBefore(today, LATE_AFTER_DAYS);
+  const upcomingRank = (deal: IpoDeal) => {
+    const date = calendarDate(deal);
+    return date === null ? 1 : date < lateBefore ? 2 : 0;
+  };
+  return (a, b) => {
+    const group = calendarGroup(a.status) - calendarGroup(b.status);
+    if (group !== 0) return group;
+    const upcoming = a.status === "upcoming";
+    const rank = upcoming ? upcomingRank(a) - upcomingRank(b) : 0;
+    if (rank !== 0) return rank;
+    const ascending = upcoming && upcomingRank(a) === 0;
+    const date = compareSortValues(calendarDate(a), calendarDate(b), ascending ? "asc" : "desc");
+    return date || a.company.localeCompare(b.company) || a.id.localeCompare(b.id);
+  };
+}
+
+/**
+ * Prices are in each deal's own currency, so across markets they sort in US
+ * dollars at the rate the size was converted at: USD size over local size.
+ */
+function usdPrice(deal: IpoDeal): number | null {
+  const price = deal.offerPrice ?? deal.priceLow ?? deal.priceHigh;
+  if (price == null || deal.offerSize == null || deal.offerSizeUsd == null || deal.offerSize <= 0) return null;
+  return price * (deal.offerSizeUsd / deal.offerSize);
+}
+
+function sortValue(columnId: IpoColumnId, deal: IpoDeal): string | number | null {
+  switch (columnId) {
+    case "ticker": return deal.symbol;
+    case "company": return deal.company;
+    case "market": return deal.venue;
+    case "date": return calendarDate(deal);
+    case "status": return IPO_STATUSES.indexOf(deal.status);
+    case "price": return usdPrice(deal);
+    case "size": return deal.offerSizeUsd;
+    case "return": return deal.firstDay?.returnPct ?? null;
+  }
+}
+
+export function sortIpoDeals(deals: readonly IpoDeal[], sort: IpoSortPreference, today = localToday()): IpoDeal[] {
+  const { columnId } = sort;
+  const order = calendarOrder(today);
+  if (!columnId) return [...deals].sort(order);
+  return [...deals].sort((a, b) => (
+    compareSortValues(sortValue(columnId, a), sortValue(columnId, b), sort.direction) || order(a, b)
+  ));
+}
+
+/** Names read A to Z first; dates soonest first; numbers largest first. */
+export function firstIpoSortDirection(columnId: IpoColumnId): "asc" | "desc" {
+  return columnId === "price" || columnId === "size" || columnId === "return" ? "desc" : "asc";
+}
+
+const COMPANY_MIN_WIDTH = 16;
+
+/** Every column at its narrowest; COMPANY takes what the pane has left. */
+const IPO_COLUMNS: readonly IpoColumn[] = [
+  // NSE symbols run to ten letters; the rest are far shorter.
+  { id: "ticker", label: "TICKER", width: 10, align: "left" },
+  { id: "company", label: "COMPANY", width: COMPANY_MIN_WIDTH, align: "left", flexGrow: 1 },
+  // Sized to the board's longest venue, see marketColumnWidth.
+  { id: "market", label: "MKT", width: 10, align: "left" },
+  { id: "date", label: "DATE", width: 8, align: "left" },
+  { id: "status", label: "STATUS", width: 9, align: "left" },
+  // "HK$26.20-28.50".
+  { id: "price", label: "PRICE", width: 14, align: "right" },
+  // "$218.82M".
+  { id: "size", label: "SIZE", width: 8, align: "right" },
+  { id: "return", label: "RETURN", width: 8, align: "right" },
+];
+
+/**
+ * What a narrow pane gives up first, so COMPANY and RETURN stay. SIZE is
+ * only filled once terms are out, STATUS follows from the calendar's order,
+ * the date and a return, and MKT goes before the date a deal lists on.
+ */
+const NARROW_DROP_ORDER: readonly IpoColumnId[] = ["size", "status", "price", "market", "date", "ticker"];
+
+/** The table's own width for these columns, plus a cell for the scrollbar. */
+export function ipoTableWidth(columns: readonly IpoColumn[]): number {
+  return getTableWidth(columns) + 1;
+}
+
+/** MKT fits the longest venue on the board ("NYSE American"), and no wider. */
+export function marketColumnWidth(deals: readonly IpoDeal[]): number {
+  const longest = deals.reduce((max, deal) => Math.max(max, displayWidth(deal.venue || deal.mic)), 0);
+  return Math.min(14, Math.max(5, longest));
+}
+
+export function buildIpoColumns(width: number, marketWidth = 10): IpoColumn[] {
+  let columns = IPO_COLUMNS.map((column) => (column.id === "market" ? { ...column, width: marketWidth } : column));
+  for (const id of NARROW_DROP_ORDER) {
+    if (ipoTableWidth(columns) <= width) break;
+    columns = columns.filter((column) => column.id !== id);
+  }
+  return columns;
+}
+
+/**
+ * A deal the app can open, keyed on its own venue so `0700` or `7203` never
+ * opens a US ticker. A venue with no exchange code (Dublin) has no key a
+ * provider resolves, so its rows do not open.
+ */
+export function ipoTickerKey(deal: IpoDeal): string | null {
+  if (!deal.symbol || !deal.exchange) return null;
+  return publicTickerKey(deal.symbol, deal.exchange);
+}
+
+const CURRENCY_SIGNS: Record<string, string> = {
+  USD: "$", HKD: "HK$", EUR: "€", GBP: "£", JPY: "¥", CNY: "¥", INR: "₹", KRW: "₩", AUD: "A$", CAD: "C$", SGD: "S$",
+};
+
+function amount(value: number): string {
+  const whole = Math.abs(value - Math.round(value)) < 1e-9;
+  return value.toLocaleString("en-US", { minimumFractionDigits: whole ? 0 : 2, maximumFractionDigits: 2 });
+}
+
+/** "$18", "HK$26.20-28.50", "240-260p", "CHF 45": the offer price once set, else the range. */
+export function formatIpoPrice(deal: IpoDeal): string {
+  const low = deal.offerPrice ?? deal.priceLow ?? deal.priceHigh;
+  if (low == null) return MISSING;
+  const high = deal.offerPrice == null && deal.priceLow != null && deal.priceHigh != null && deal.priceHigh !== deal.priceLow
+    ? deal.priceHigh
+    : null;
+  const figures = high == null ? amount(low) : `${amount(low)}-${amount(high)}`;
+  const code = deal.currency?.trim() ?? "";
+  if (code === "GBp" || code.toUpperCase() === "GBX") return `${figures}p`;
+  if (!code) return figures;
+  const sign = CURRENCY_SIGNS[code.toUpperCase()];
+  return sign ? `${sign}${figures}` : `${code.toUpperCase()} ${figures}`;
+}
+
+/** "$1.2B", "$85M". */
+export function formatIpoSize(valueUsd: number | null): string {
+  if (valueUsd == null || !Number.isFinite(valueUsd) || valueUsd <= 0) return MISSING;
+  return `$${formatCompact(valueUsd)}`;
+}
+
+/** A fraction, as the first day's move: 0.164 is "+16.4%". */
+export function formatIpoReturn(returnPct: number | null | undefined): string {
+  if (returnPct == null || !Number.isFinite(returnPct)) return MISSING;
+  const fixed = (returnPct * 100).toFixed(1);
+  if (!/[1-9]/.test(fixed)) return "0.0%";
+  return `${returnPct > 0 ? "+" : ""}${fixed}%`;
+}
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * "Oct 23" for dates near today, which is nearly every row on a calendar;
+ * "Dec 2024" for anything more than half a year off, where the year matters.
+ */
+export function formatIpoDate(value: string | null, now = new Date()): string {
+  if (!value) return MISSING;
+  const date = new Date(`${value}T00:00:00Z`);
+  if (!Number.isFinite(date.getTime())) return MISSING;
+  const month = date.toLocaleString("en-US", { month: "short", timeZone: "UTC" });
+  return Math.abs(date.getTime() - now.getTime()) <= 183 * MS_PER_DAY
+    ? `${month} ${date.getUTCDate()}`
+    : `${month} ${date.getUTCFullYear()}`;
+}