@miragon/pulse-analytics-connector 0.0.0-bootstrap.0 → 0.21.0

package/src/widgets/version-compare.tsx

@@ -0,0 +1,96 @@
+import { Badge } from "@miragon/mcp-toolkit-ui"
+import type { VersionCompareResult } from "@miragon/pulse-analytics-client"
+import {
+  HandOffButton,
+  ViewMeta,
+  formatLookback,
+  formatNumber,
+} from "@miragon/pulse-widget-shell/widgets"
+import { useT } from "../messages/use-t.js"
+import {
+  ComparisonCard,
+  ComparisonEmptyState,
+  SuppressedBadge,
+  buildComparisonMetrics,
+  deltaFacts,
+} from "./comparison-shared.js"
+import { engineIdsOf, useHandOff, type HandOff } from "./hand-off.js"
+import { enginesMeta } from "./view-meta.js"
+
+export type VersionCompareData = VersionCompareResult | null
+
+/**
+ * Interpret a version comparison. The comparison is process-wide: the tool
+ * takes no element scope (#336).
+ */
+export function versionCompareHandOff(data: VersionCompareResult): HandOff {
+  return {
+    intent: "askAi.versionCompare",
+    ids: {
+      engine: engineIdsOf(data.engines),
+      processDefinitionKey: data.processDefinitionKey,
+      versionA: data.versionA,
+      versionB: data.versionB,
+      windowDays: data.windowDays,
+    },
+    facts: deltaFacts(data.delta, data.suppressed),
+    tools: ["analytics_version_compare", "analytics_element_bottleneck"],
+  }
+}
+
+export function VersionCompareWidget({ data }: { data: VersionCompareData }) {
+  const t = useT()
+  const { ask } = useHandOff()
+  if (!data) return <ComparisonEmptyState>{t("aVersionCompare.emptyNoData")}</ComparisonEmptyState>
+
+  const a = data.kpis.find((k) => k.bucket === "versionA")
+  const b = data.kpis.find((k) => k.bucket === "versionB")
+  if (!a || !b) {
+    return <ComparisonEmptyState>{t("aVersionCompare.emptyIncomplete")}</ComparisonEmptyState>
+  }
+
+  const metrics = buildComparisonMetrics(t, a, b, data.delta)
+
+  return (
+    <ComparisonCard
+      title={t("aVersionCompare.title")}
+      tableLabel={t("aVersionCompare.tableLabel")}
+      beforeLabel={`v${data.versionA}`}
+      afterLabel={`v${data.versionB}`}
+      metrics={metrics}
+      suppressed={data.suppressed}
+      actions={
+        <HandOffButton
+          action="assess"
+          prompt={ask(versionCompareHandOff(data))}
+          variant="primary"
+        />
+      }
+      meta={
+        <ViewMeta
+          period={formatLookback(`${data.windowDays}d`)}
+          engines={enginesMeta(data.engines)}
+          asOf={data.asOf}
+        />
+      }
+      badges={
+        <>
+          <Badge>{data.processDefinitionKey}</Badge>
+          <Badge variant="secondary">
+            {t("aVersionCompare.versionsBadge", {
+              versionA: data.versionA,
+              versionB: data.versionB,
+            })}
+          </Badge>
+          {data.suppressed && (
+            <SuppressedBadge>
+              {t("aVersionCompare.badgeInsufficientSignal", {
+                min: formatNumber(data.minBucketSize),
+              })}
+            </SuppressedBadge>
+          )}
+        </>
+      }
+    />
+  )
+}

package/src/widgets/view-meta.ts

@@ -0,0 +1,18 @@
+import type { ViewMetaEngines } from "@miragon/pulse-widget-shell/widgets"
+
+/**
+ * The engine part of an analytics view's meta line (U7) from the result's
+ * echo: how many engines the figures add up and, where the result names
+ * the reporting ones, how many of them send no metrics. `null` for an
+ * unscoped result (every engine Prometheus holds), which names none.
+ */
+export function enginesMeta(
+  engines: readonly string[] | null | undefined,
+  reporting?: readonly string[],
+): ViewMetaEngines | null {
+  if (!engines || engines.length === 0) return null
+  return {
+    count: engines.length,
+    silent: reporting ? engines.filter((id) => !reporting.includes(id)).length : null,
+  }
+}

package/src/widgets/widget-render.test-support.tsx

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, vi } from "vitest"
+import type { ComponentType } from "react"
+import { cleanup, render, screen, within } from "@testing-library/react"
+import { LocaleProvider, queryClient } from "@miragon/mcp-toolkit-ui"
+import { WidgetFixtureHost } from "@miragon/mcp-toolkit-ui/app"
+import { setFormatLocale } from "@miragon/pulse-widget-shell/testing"
+
+/**
+ * Rendering the analytics widgets as a person reads them, for the DOM suites
+ * (`*-widgets.test.tsx`): a widget in a language, at a fixed clock, and the
+ * readers those suites share.
+ */
+
+export const NOW = "2026-10-10T12:40:00.000Z"
+export const AS_OF = "2026-10-10T12:32:00.000Z"
+
+/** Fixes the clock at {@link NOW} and resets the view state after each test. */
+export function withWidgetClock() {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ["Date"] })
+    vi.setSystemTime(new Date(NOW))
+  })
+  afterEach(() => {
+    cleanup()
+    queryClient.clear()
+    setFormatLocale(undefined)
+    vi.useRealTimers()
+  })
+}
+
+export function renderIn(
+  language: "de" | "en",
+  Widget: ComponentType<{ data: never }>,
+  data: unknown,
+  /** The tools a self-fetching widget calls (e.g. the heatmap's diagram feed). */
+  tools?: Record<string, unknown>,
+) {
+  setFormatLocale({
+    language,
+    locale: language === "de" ? "de-DE" : "en-GB",
+    timeZone: "Europe/Berlin",
+  })
+  return render(
+    <LocaleProvider locale={language}>
+      <WidgetFixtureHost
+        widget={Widget as unknown as ComponentType<Record<string, unknown>>}
+        data={data as Record<string, unknown>}
+        tools={tools}
+      />
+    </LocaleProvider>,
+  )
+}
+
+const NBSP = String.fromCharCode(0xa0)
+
+/** Text with the formatters' no-break spaces as plain spaces. */
+export const plain = (s: string | null | undefined) => s?.replaceAll(NBSP, " ")
+export const metaLine = () => plain(document.querySelector("[data-view-meta]")?.textContent)
+export const iconOf = (el: HTMLElement) => el.querySelector("svg")?.getAttribute("class") ?? ""
+
+/** The tone of the KPI cell labelled `label` (its dot), or undefined for a neutral one. */
+export const kpiTone = (label: string) =>
+  screen.getByText(label).closest("[data-tone]")?.getAttribute("data-tone") ?? undefined
+
+/**
+ * The column heads, the ones a narrow region hides included: happy-dom has no
+ * layout, so every `hideBelow` container query reads as "too narrow". The
+ * heads of a column GROUP (the row above, `data-list-table-groups`) are not
+ * column heads.
+ */
+export const headers = (table: HTMLElement) =>
+  within(table)
+    .getAllByRole("columnheader", { hidden: true })
+    .filter((th) => th.getAttribute("scope") === "col" && !inGroupRow(th))
+    .map((th) => plain(th.textContent)?.trim())
+
+const inGroupRow = (th: HTMLElement) => th.closest("tr")?.hasAttribute("data-list-table-groups")
+
+/** The heads of the column groups: their text and how many columns each spans. */
+export const groupHeads = (table: HTMLElement) =>
+  within(table)
+    .getAllByRole("columnheader", { hidden: true })
+    .filter(inGroupRow)
+    .map((th) => [plain(th.textContent)?.trim(), th.getAttribute("colspan")])
+
+/**
+ * Each "—" for a missing figure (`Figure`) as each reader gets it: the sign
+ * on screen (hidden from assistive tech), the reason a screen reader reads in
+ * its place, and the tooltip.
+ */
+export const missingFigures = (root: ParentNode) =>
+  [...root.querySelectorAll<HTMLElement>("[data-figure='missing']")].map((el) => ({
+    shown: el.querySelector("[aria-hidden='true']")?.textContent,
+    read: el.querySelector(".sr-only")?.textContent,
+    title: el.getAttribute("title"),
+  }))
+
+/** One missing figure as {@link missingFigures} reports it: "—", its reason read out and as the tooltip. */
+export const missing = (why: string) => ({ shown: "—", read: why, title: why })
+
+/** The notes under the tables (`Legend`), as text. */
+export const legendLines = () =>
+  [...document.querySelectorAll("[data-legend]")].map((p) => plain(p.textContent)?.trim())