gloomberb 0.11.2 → 0.12.0

package/src/plugins/builtin/econ-statistics/detail.tsx

@@ -0,0 +1,154 @@
+import { useMemo, useState } from "react";
+import { CompositeChart } from "../../../components/chart/composite";
+import { ExternalLinkText } from "../../../components/ui";
+import { blendHex, colors } from "../../../theme/colors";
+import type { ResolvedSeries } from "../../../time-series/types";
+import { Box, Text } from "../../../ui";
+import { formatNumber } from "../../../utils/format";
+import { categoryLabel, type StatDef } from "./defs";
+import type { StatPoint } from "./transform";
+import type { StatViewModel } from "./view";
+
+const AXIS_WIDTH = 8;
+const PANELS = [{ id: "main" }];
+
+function seriesFor(
+  stat: StatDef,
+  id: string,
+  label: string,
+  color: string,
+  points: readonly StatPoint[],
+): ResolvedSeries {
+  return {
+    id,
+    label,
+    color,
+    unit: stat.axisUnit,
+    unitGroup: stat.axisUnit === "%" ? "economic-percent" : "economic",
+    nativeFrequency: "monthly",
+    dataShape: "scalar",
+    style: "line",
+    transform: "raw",
+    axis: "left",
+    panelId: "main",
+    interpolation: "none",
+    points: points.map((point) => {
+      const date = new Date(point.date);
+      return { date, observedAt: date, value: point.value };
+    }),
+  };
+}
+
+function flatSeries(
+  stat: StatDef,
+  id: string,
+  label: string,
+  value: number,
+  color: string,
+  points: readonly StatPoint[],
+): ResolvedSeries | null {
+  if (points.length === 0 || !Number.isFinite(value)) return null;
+  return seriesFor(stat, id, label, color, [
+    { date: points[0]!.date, value },
+    { date: points[points.length - 1]!.date, value },
+  ]);
+}
+
+export function StatDetail({
+  view,
+  width,
+  height,
+  focused = false,
+}: {
+  view: StatViewModel;
+  width: number;
+  height: number;
+  focused?: boolean;
+}) {
+  const stat = view.stat;
+  const [userViewport, setUserViewport] = useState<{ start: Date; end: Date } | null>(null);
+  const chartWidth = Math.max(24, width - 2);
+  const chartHeight = Math.max(8, Math.min(26, height - 14));
+  const visible = view.visible;
+
+  const series = useMemo(() => {
+    const markers = [
+      stat.reference
+        ? flatSeries(stat, "reference", stat.reference.label, stat.reference.value, colors.textDim, visible)
+        : null,
+      flatSeries(stat, "mean", "mean", view.mean, blendHex(colors.textDim, colors.bg, 0.35), visible),
+    ].filter((entry) => entry != null);
+    return [...markers, seriesFor(stat, stat.id, stat.shortLabel, colors.textBright, visible)];
+  }, [stat, view.mean, visible]);
+
+  const legendSeries = useMemo(
+    () => series.filter((entry) => entry.id === "reference" || entry.id === "mean"),
+    [series],
+  );
+
+  const viewport = useMemo(() => {
+    if (userViewport) return userViewport;
+    if (visible.length < 2) return undefined;
+    return { start: new Date(visible[0]!.date), end: new Date(visible.at(-1)!.date) };
+  }, [userViewport, visible]);
+
+  return (
+    <Box flexDirection="column" width={width} paddingX={1} gap={1}>
+      {visible.length >= 2 ? (
+        <CompositeChart
+          series={series}
+          legendSeries={legendSeries}
+          panels={PANELS}
+          width={chartWidth}
+          height={chartHeight}
+          focused={focused}
+          interactive
+          axisWidth={AXIS_WIDTH}
+          showLegend
+          viewport={viewport}
+          viewportResetKey={`${stat.id}:${view.range}`}
+          onViewportChange={setUserViewport}
+          formatValue={(value) => stat.formatValue(value)}
+          emptyMessage="Not enough chart data"
+        />
+      ) : (
+        <Box height={chartHeight} justifyContent="center" alignItems="center">
+          <Text fg={colors.textMuted}>Not enough chart data</Text>
+        </Box>
+      )}
+
+      <Box flexDirection="column" gap={0}>
+        <Box flexDirection="row" height={1} overflow="hidden">
+          <Text fg={colors.textDim}>1Y ago </Text>
+          <Text fg={colors.text}>
+            {view.yearAgo ? stat.formatValue(view.yearAgo.value) : "--"}
+          </Text>
+          <Text fg={colors.textDim}>{"  mean "}</Text>
+          <Text fg={colors.text}>{stat.formatValue(view.mean)}</Text>
+          <Text fg={colors.textDim}>{"  %ile "}</Text>
+          <Text fg={colors.textBright}>{formatNumber(view.percentile, 0)}</Text>
+        </Box>
+        <Box flexDirection="row" height={1} overflow="hidden">
+          <Text fg={colors.textDim}>High </Text>
+          <Text fg={colors.text}>{`${stat.formatValue(view.high.value)} ${view.high.date}`}</Text>
+          <Text fg={colors.textDim}>{"  Low "}</Text>
+          <Text fg={colors.text}>{`${stat.formatValue(view.low.value)} ${view.low.date}`}</Text>
+        </Box>
+        <Box flexDirection="row" height={1} overflow="hidden">
+          <Text fg={colors.textDim}>{`${categoryLabel(stat.category)} · FRED ${stat.seriesId}`}</Text>
+        </Box>
+      </Box>
+
+      <Box flexDirection="column" gap={1} width={Math.max(1, width - 2)}>
+        <Text fg={colors.textDim} wrapMode="word" wrapText>{stat.note}</Text>
+        <Box flexDirection="row" height={1} overflow="hidden">
+          <ExternalLinkText
+            url={`https://fred.stlouisfed.org/series/${stat.seriesId}`}
+            label={`${stat.label}, FRED`}
+            color={colors.text}
+          />
+        </Box>
+      </Box>
+    </Box>
+  );
+}

package/src/plugins/builtin/econ-statistics/headless.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createTestDataProvider } from "../../../test-support/data-provider";
+import { createDefaultConfig } from "../../../types/config";
+import type { HeadlessPaneContext, HeadlessPaneLoadArgs } from "../../../types/plugin";
+import { statsCache } from "./cache";
+import { econStatisticsHeadless } from "./headless";
+
+beforeEach(() => statsCache.reset());
+afterEach(() => statsCache.reset());
+
+function monthlyCpi() {
+  return Array.from({ length: 25 }, (_, index) => {
+    const year = 2024 + Math.floor(index / 12);
+    const month = (index % 12) + 1;
+    return {
+      date: `${year}-${String(month).padStart(2, "0")}-01`,
+      value: 300 + index,
+    };
+  });
+}
+
+const args: HeadlessPaneLoadArgs = {
+  rawArgument: "cpi",
+  argument: "cpi",
+  symbols: [],
+  options: { range: "5Y" },
+};
+
+describe("economic statistics headless model", () => {
+  test("loads through the injected cloud client and produces category sections", async () => {
+    const requested: string[] = [];
+    const apiClient = {
+      getCloudFredSeries: async (seriesId: string) => {
+        requested.push(seriesId);
+        return { seriesId, observations: monthlyCpi() };
+      },
+    } as unknown as HeadlessPaneContext["apiClient"];
+    const context: HeadlessPaneContext = {
+      marketData: createTestDataProvider(),
+      apiClient,
+      config: createDefaultConfig("/tmp/gloomberb-headless-econ"),
+      signal: new AbortController().signal,
+    };
+
+    const result = await econStatisticsHeadless.load(args, context);
+
+    expect(requested).toEqual(["CPIAUCSL"]);
+    expect(result.sections.map(({ title }) => title)).toEqual(["Inflation", "CPI"]);
+    expect(result.sections[0]).toMatchObject({
+      rows: [{ id: "cpi-yoy", indicator: "CPI y/y" }],
+    });
+    expect(result.metadata).toMatchObject({ range: "5Y", selected: "cpi-yoy" });
+  });
+});

package/src/plugins/builtin/econ-statistics/headless.ts

@@ -0,0 +1,171 @@
+import type {
+  HeadlessBundleResult,
+  HeadlessPaneDefinition,
+  HeadlessPaneEntry,
+  HeadlessPaneLoadArgs,
+} from "../../../types/plugin";
+import { formatNumber } from "../../../utils/format";
+import {
+  createStatSeriesLoader,
+  loadStatsBundle,
+  type StatSeriesLoader,
+  type StatsBundle,
+} from "./client";
+import { STAT_CATEGORIES } from "./defs";
+import { DEFAULT_STAT_ID, resolveStatArg, STATS } from "./stats";
+import { selectStatViews, type StatRangeId, type StatViewModel } from "./view";
+
+function signedSigma(value: number): string {
+  return `${value > 0 ? "+" : ""}${formatNumber(value, 1)}σ`;
+}
+
+function detailEntries(view: StatViewModel): HeadlessPaneEntry[] {
+  const format = view.stat.formatValue;
+  return [
+    { label: "Latest", value: view.latest.value, formatted: format(view.latest.value) },
+    {
+      label: "Previous",
+      value: view.previous?.value ?? null,
+      formatted: view.previous ? format(view.previous.value) : "-",
+    },
+    {
+      label: "1Y ago",
+      value: view.yearAgo?.value ?? null,
+      formatted: view.yearAgo ? format(view.yearAgo.value) : "-",
+    },
+    { label: "Mean", value: view.mean, formatted: format(view.mean) },
+    {
+      label: "Historical percentile",
+      value: view.percentile,
+      formatted: formatNumber(view.percentile, 0),
+    },
+    {
+      label: "Trend deviation",
+      value: view.sigmaVsTrend,
+      formatted: signedSigma(view.sigmaVsTrend),
+    },
+    {
+      label: "High",
+      value: view.high,
+      formatted: `${format(view.high.value)} ${view.high.date}`,
+    },
+    {
+      label: "Low",
+      value: view.low,
+      formatted: `${format(view.low.value)} ${view.low.date}`,
+    },
+    { label: "As of", value: view.latest.date },
+    { label: "Source", value: `FRED ${view.stat.seriesId}` },
+  ];
+}
+
+export function projectStatsHeadlessBundle(
+  bundle: StatsBundle,
+  range: StatRangeId,
+  selectedId: string,
+): HeadlessBundleResult {
+  const views = selectStatViews(bundle.builds, range);
+  const selected = views.find((view) => view.stat.id === selectedId) ?? views[0] ?? null;
+  const sections = STAT_CATEGORIES.flatMap((category) => {
+    const categoryViews = views.filter((view) => view.stat.category === category.id);
+    if (categoryViews.length === 0) return [];
+    return [{
+      title: category.label,
+      columns: [
+        { key: "indicator", header: "Indicator" },
+        {
+          key: "latest",
+          header: "Latest",
+          align: "right" as const,
+          format: (_value: unknown, row: Record<string, unknown>) => String(row.formattedLatest),
+        },
+        {
+          key: "previous",
+          header: "Previous",
+          align: "right" as const,
+          format: (_value: unknown, row: Record<string, unknown>) => String(row.formattedPrevious),
+        },
+        {
+          key: "percentile",
+          header: "%ile",
+          align: "right" as const,
+          format: (value: unknown) => formatNumber(Number(value), 0),
+        },
+        { key: "asOf", header: "As of" },
+      ],
+      rows: categoryViews.map((view) => ({
+        id: view.stat.id,
+        indicator: view.stat.shortLabel,
+        latest: view.latest.value,
+        formattedLatest: view.stat.formatValue(view.latest.value),
+        previous: view.previous?.value ?? null,
+        formattedPrevious: view.previous ? view.stat.formatValue(view.previous.value) : "-",
+        percentile: view.percentile,
+        asOf: view.latest.date,
+        stale: view.observationStale,
+      })),
+    }];
+  });
+
+  return {
+    sections: [
+      ...sections,
+      ...(selected ? [{ title: selected.stat.label, entries: detailEntries(selected) }] : []),
+    ],
+    errors: bundle.errors,
+    metadata: {
+      fetchedAt: bundle.fetchedAt,
+      range,
+      selected: selected?.stat.id ?? null,
+    },
+  };
+}
+
+export interface EconStatisticsHeadlessDependencies {
+  loadBundle(args: HeadlessPaneLoadArgs, loader: StatSeriesLoader): Promise<StatsBundle>;
+}
+
+const defaultDependencies: EconStatisticsHeadlessDependencies = {
+  loadBundle: (args, loader) => {
+    const requested = typeof args.argument === "string" ? resolveStatArg(args.argument) : null;
+    return loadStatsBundle({
+      loader,
+      ...(requested ? { stats: [requested] } : {}),
+    });
+  },
+};
+
+export function createEconStatisticsHeadless(
+  dependencies: EconStatisticsHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"bundle"> {
+  return {
+    shape: "bundle",
+    argument: {
+      kind: "free-text",
+      placeholder: "statistic",
+      description: "Optional statistic id, FRED series id, label, or prefix.",
+      optional: true,
+    },
+    options: [{
+      key: "range",
+      description: "History window used by the selected statistic view.",
+      type: "enum",
+      values: [{ value: "5Y" }, { value: "20Y" }, { value: "ALL", aliases: ["all"] }],
+      defaultValue: "20Y",
+    }],
+    describe: (args) => `Economic Statistics | ${String(args.options.range)}`,
+    async load(args, ctx) {
+      const requested = typeof args.argument === "string" ? resolveStatArg(args.argument) : null;
+      if (args.argument && !requested) {
+        throw new Error(
+          `Unknown economic statistic "${String(args.argument)}". Use one of: ${STATS.map(({ id }) => id).join(", ")}.`,
+        );
+      }
+      const range = args.options.range as StatRangeId;
+      const bundle = await dependencies.loadBundle(args, createStatSeriesLoader(ctx.apiClient));
+      return projectStatsHeadlessBundle(bundle, range, requested?.id ?? DEFAULT_STAT_ID);
+    },
+  };
+}
+
+export const econStatisticsHeadless = createEconStatisticsHeadless();

package/src/plugins/builtin/econ-statistics/index.tsx

@@ -0,0 +1,54 @@
+import type { PluginModule } from "../plugin-module";
+import { statsCache } from "./cache";
+import { STAT_CATEGORIES } from "./defs";
+import { econStatisticsHeadless } from "./headless";
+import { EconStatisticsPane } from "./pane";
+import { resolveStatArg, STATS, DEFAULT_STAT_ID } from "./stats";
+
+export { econStatisticsHeadless } from "./headless";
+
+const ECON_STATISTICS_PANE_ID = "econ-statistics";
+
+export const econStatisticsModule: PluginModule = {
+  panes: [{
+    id: ECON_STATISTICS_PANE_ID,
+    name: "Economic Statistics",
+    icon: "E",
+    component: EconStatisticsPane,
+    defaultPosition: "right",
+    defaultMode: "floating",
+    defaultFloatingSize: { width: 120, height: 36 },
+  }],
+  paneTemplates: [{
+    id: "econ-statistics-pane",
+    paneId: ECON_STATISTICS_PANE_ID,
+    label: "Economic Statistics",
+    description: "Inflation, labour, growth, housing and rates against their own history.",
+    keywords: [
+      "economic",
+      "statistics",
+      "macro",
+      "indicators",
+      "data",
+      ...STAT_CATEGORIES.map((entry) => entry.label.toLowerCase()),
+      ...STATS.map((entry) => entry.shortLabel.toLowerCase()),
+    ],
+    shortcut: {
+      prefix: "ECST",
+      argPlaceholder: "statistic",
+      argKind: "text",
+      argOptional: true,
+    },
+    headless: econStatisticsHeadless,
+    canCreate: () => true,
+    createInstance: (_context, options) => ({
+      settings: { stat: resolveStatArg(options?.arg)?.id ?? DEFAULT_STAT_ID },
+    }),
+  }],
+  setup(ctx) {
+    statsCache.attach(ctx.persistence);
+  },
+  dispose() {
+    statsCache.reset();
+  },
+};