@liiift-studio/sanity-visitor-insights 0.17.0 → 0.18.0

package/dist/index.d.mts

@@ -342,22 +342,43 @@ interface SeriesPoint {
 }
 /** How a value should be written out. */
 type SeriesUnit = 'count' | 'money' | 'percent';
-/** One row of the chart. */
+/**
+ * One row of the chart: one answer, with what a lossier source saw underneath it.
+ *
+ * A row shows a SINGLE line by default. Two peer lines make the reader reconcile before they get
+ * an answer, and at a glance a foundry owner wants "how much", not "here are two measurements that
+ * disagree". The disagreement is still drawn — as a filled region, and in full on hover — because
+ * hiding it entirely would switch off the alarm: the 24 August collapse was visible precisely
+ * because two lines came apart.
+ */
 interface Series {
     key: string;
     label: string;
-    /** Which upstream this came from, shown so the reader can weigh it. */
+    /** Which upstream the LINE came from. */
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
-    /**
-     * Whether the source sees everything. GA4 does not; the others do.
-     * Drives the dashed stroke and the uncertainty band rather than a footnote nobody reads.
-     */
+    /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
     unit: SeriesUnit;
     points: SeriesPoint[];
     /**
-     * Multiplier from observed to estimated-true, for a lossy series. 1 means no correction known.
-     * Drawn as a band above the line, never as a replacement for it — the measured line stays.
+     * What a lossier source saw of the same thing.
+     *
+     * Drawn as a filled region between the two, NOT as a symmetric uncertainty band. There is no
+     * doubt about the traffic here: Vercel counted it server-side. What is uncertain is how much of
+     * it the analytics could see, and the honest way to draw that is the area it missed — a
+     * quantity, visible to scale, rather than a percentage on another tab.
+     */
+    shortfall?: {
+        label: string;
+        source: Series['source'];
+        points: SeriesPoint[];
+    };
+    /**
+     * Multiplier from observed to estimated-true, where the line itself is the lossy source.
+     *
+     * This one IS a symmetric band, because it is genuine uncertainty rather than a known blind
+     * spot. The two must not look alike: one says "we do not know exactly", the other says "we know
+     * exactly, and this much was invisible".
      */
     grossUpFactor?: number;
 }

package/dist/index.d.ts

@@ -342,22 +342,43 @@ interface SeriesPoint {
 }
 /** How a value should be written out. */
 type SeriesUnit = 'count' | 'money' | 'percent';
-/** One row of the chart. */
+/**
+ * One row of the chart: one answer, with what a lossier source saw underneath it.
+ *
+ * A row shows a SINGLE line by default. Two peer lines make the reader reconcile before they get
+ * an answer, and at a glance a foundry owner wants "how much", not "here are two measurements that
+ * disagree". The disagreement is still drawn — as a filled region, and in full on hover — because
+ * hiding it entirely would switch off the alarm: the 24 August collapse was visible precisely
+ * because two lines came apart.
+ */
 interface Series {
     key: string;
     label: string;
-    /** Which upstream this came from, shown so the reader can weigh it. */
+    /** Which upstream the LINE came from. */
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
-    /**
-     * Whether the source sees everything. GA4 does not; the others do.
-     * Drives the dashed stroke and the uncertainty band rather than a footnote nobody reads.
-     */
+    /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
     unit: SeriesUnit;
     points: SeriesPoint[];
     /**
-     * Multiplier from observed to estimated-true, for a lossy series. 1 means no correction known.
-     * Drawn as a band above the line, never as a replacement for it — the measured line stays.
+     * What a lossier source saw of the same thing.
+     *
+     * Drawn as a filled region between the two, NOT as a symmetric uncertainty band. There is no
+     * doubt about the traffic here: Vercel counted it server-side. What is uncertain is how much of
+     * it the analytics could see, and the honest way to draw that is the area it missed — a
+     * quantity, visible to scale, rather than a percentage on another tab.
+     */
+    shortfall?: {
+        label: string;
+        source: Series['source'];
+        points: SeriesPoint[];
+    };
+    /**
+     * Multiplier from observed to estimated-true, where the line itself is the lossy source.
+     *
+     * This one IS a symmetric band, because it is genuine uncertainty rather than a known blind
+     * spot. The two must not look alike: one says "we do not know exactly", the other says "we know
+     * exactly, and this much was invisible".
      */
     grossUpFactor?: number;
 }

package/dist/index.js

@@ -913,6 +913,7 @@ function tickLabel(date) {
 }
 function CrossSourceTimeline({ series, markers = [], currency }) {
   const [hoverIndex, setHoverIndex] = (0, import_react3.useState)(null);
+  const [pinned, setPinned] = (0, import_react3.useState)(false);
   const frameRef = (0, import_react3.useRef)(null);
   const dates = (0, import_react3.useMemo)(() => {
     const all = /* @__PURE__ */ new Set();
@@ -940,6 +941,7 @@ function CrossSourceTimeline({ series, markers = [], currency }) {
   );
   if (dates.length < 3 || series.length === 0 || !x) return null;
   const hoveredDate = hoverIndex !== null ? dates[hoverIndex] : null;
+  const revealed = pinned || hoverIndex !== null;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Stack, { space: 3, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: frameStyle, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
       "svg",
@@ -960,16 +962,24 @@ function CrossSourceTimeline({ series, markers = [], currency }) {
             const peak = (0, import_d3_array.max)(values) ?? 0;
             const grossed = row.grossUpFactor && row.grossUpFactor > 1 ? peak * row.grossUpFactor : peak;
             const y = (0, import_d3_scale.scaleLinear)().domain([0, grossed || 1]).nice().range([bottom, top]);
+            const at = (p) => x(/* @__PURE__ */ new Date(`${p.date}T00:00:00Z`));
             const defined = (p) => p.value !== null;
-            const lineGen = (0, import_d3_shape.line)().defined(defined).x((p) => x(/* @__PURE__ */ new Date(`${p.date}T00:00:00Z`))).y((p) => y(p.value)).curve(import_d3_shape.curveMonotoneX);
-            const bandGen = (0, import_d3_shape.area)().defined(defined).x((p) => x(/* @__PURE__ */ new Date(`${p.date}T00:00:00Z`))).y0((p) => y(p.value)).y1((p) => y(p.value * row.grossUpFactor)).curve(import_d3_shape.curveMonotoneX);
+            const lineGen = (0, import_d3_shape.line)().defined(defined).x(at).y((p) => y(p.value)).curve(import_d3_shape.curveMonotoneX);
+            const shortfallPoints = row.shortfall?.points ?? [];
+            const byDate = new Map(shortfallPoints.map((p) => [p.date, p.value]));
+            const gapGen = (0, import_d3_shape.area)().defined((p) => p.value !== null && byDate.get(p.date) != null).x(at).y0((p) => y(byDate.get(p.date))).y1((p) => y(p.value)).curve(import_d3_shape.curveMonotoneX);
+            const bandGen = (0, import_d3_shape.area)().defined(defined).x(at).y0((p) => y(p.value)).y1((p) => y(p.value * row.grossUpFactor)).curve(import_d3_shape.curveMonotoneX);
             const path = lineGen(row.points) ?? "";
+            const gap = row.shortfall ? gapGen(row.points) ?? "" : "";
             const band = row.grossUpFactor && row.grossUpFactor > 1 ? bandGen(row.points) ?? "" : "";
+            const shortfallLine = row.shortfall && revealed ? lineGen(shortfallPoints.filter((p) => p.value !== null)) ?? "" : "";
             return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("g", { children: [
               /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("line", { x1: GUTTER, x2: GUTTER + plotWidth, y1: bottom, y2: bottom, stroke: "currentColor", strokeWidth: 0.15, opacity: 0.25 }),
               /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("text", { x: GUTTER - 4, y: top + 5, textAnchor: "end", fontSize: 3, fill: "currentColor", opacity: 0.55, children: formatValue(grossed, row.unit, currency) }),
               /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("text", { x: GUTTER - 4, y: bottom, textAnchor: "end", fontSize: 3, fill: "currentColor", opacity: 0.55, children: "0" }),
+              gap && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { d: gap, fill: "currentColor", opacity: revealed ? 0.16 : 0.09 }),
               band && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { d: band, fill: "currentColor", opacity: 0.1 }),
+              shortfallLine && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("path", { d: shortfallLine, fill: "none", stroke: "currentColor", strokeWidth: 0.35, strokeDasharray: "1.5 1", opacity: 0.75 }),
               /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
                 "path",
                 {
@@ -1039,11 +1049,18 @@ function CrossSourceTimeline({ series, markers = [], currency }) {
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, weight: "medium", children: hoveredDate ? tickLabel(/* @__PURE__ */ new Date(`${hoveredDate}T00:00:00Z`)) : "Hover the chart to read a day" }),
       hoveredDate && series.map((row) => {
         const point = row.points.find((p) => p.date === hoveredDate);
+        const seen = row.shortfall?.points.find((p) => p.date === hoveredDate);
         return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: [
           row.label,
           ":",
           " ",
-          point && point.value !== null ? formatValue(point.value, row.unit, currency) : "\u2014"
+          point && point.value !== null ? formatValue(point.value, row.unit, currency) : "\u2014",
+          seen && seen.value !== null && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_jsx_runtime2.Fragment, { children: [
+            " \xB7 ",
+            row.shortfall?.source,
+            " saw ",
+            formatValue(seen.value, row.unit, currency)
+          ] })
         ] }, row.key);
       }),
       hoveredDate && markers.filter((m) => m.date === hoveredDate).map((m) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Text, { size: 0, children: [
@@ -1052,6 +1069,19 @@ function CrossSourceTimeline({ series, markers = [], currency }) {
       ] }, m.label))
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: legendRow2, children: [
+      series.some((row) => row.shortfall) && // Hover is not available on touch and not reachable by keyboard, so the reveal
+      // has an explicit control too. Without it the detail would exist only for people
+      // using a mouse.
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "button",
+        {
+          type: "button",
+          style: revealButton,
+          "aria-pressed": pinned,
+          onClick: () => setPinned((current) => !current),
+          children: pinned ? "Hide what each source saw" : "Show what each source saw"
+        }
+      ),
       series.map((row) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { "aria-hidden": "true", children: row.complete ? "\u2500\u2500\u2500" : "\u254C\u254C\u254C" }),
         " ",
@@ -1060,7 +1090,8 @@ function CrossSourceTimeline({ series, markers = [], currency }) {
         row.source,
         ")"
       ] }, row.key)),
-      series.some((row) => !row.complete) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: "Dashed means the source misses things. The shaded band is where the figure probably sits." }),
+      series.some((row) => row.shortfall) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: "The shaded area is what your analytics did not see. It is a quantity, not a margin of error \u2014 the traffic happened, GA4 just missed it." }),
+      series.some((row) => !row.complete && row.grossUpFactor) && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: "A dashed line is a lossy source; the band above it is where the true figure probably sits." }),
       markers.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_sanity_ui_compat2.Text, { size: 0, muted: true, children: "Vertical rules mark campaign sends." })
     ] })
   ] });
@@ -1073,6 +1104,18 @@ var readoutRow = {
   alignItems: "baseline",
   minHeight: 18
 };
+var revealButton = {
+  appearance: "none",
+  background: "transparent",
+  border: "1px solid var(--card-border-color, rgba(128,128,128,0.3))",
+  borderRadius: 3,
+  color: "inherit",
+  font: "inherit",
+  fontSize: "0.8em",
+  padding: "3px 8px",
+  cursor: "pointer",
+  whiteSpace: "nowrap"
+};
 var legendRow2 = {
   display: "flex",
   gap: 14,
@@ -1139,6 +1182,7 @@ function MeasurementHealthPanel({ data, previous }) {
     (data.crossSource?.length ?? 0) >= 3 && /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(import_sanity_ui_compat3.Stack, { space: 3, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Heading, { size: 1, style: sectionHeading, children: "Everything, on one time axis" }),
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, muted: true, children: "Each row keeps its own scale \u2014 traffic and revenue are not co-scaled, because whatever factor made them share an axis would invent a correlation the data never claimed. Aligned rows show the same co-movement and assert nothing about relative size." }),
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_sanity_ui_compat3.Text, { size: 1, muted: true, children: "One line per row is the truest figure available. Hover a day, or use the control below, to see what each source saw of it." }),
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
         CrossSourceTimeline,
         {
@@ -1146,23 +1190,21 @@ function MeasurementHealthPanel({ data, previous }) {
           markers: data.timelineEvents ?? [],
           series: [
             {
-              key: "vercel",
+              // One traffic row, not two. The line is what happened; GA4's view of it
+              // is the shaded area beneath. Two peer lines made the reader reconcile
+              // before getting an answer, and GA4 is not a competing estimate of
+              // pageviews — it is a lossy subset of them.
+              key: "traffic",
               label: "Pageviews",
               source: "Vercel",
               complete: true,
               unit: "count",
-              points: (data.crossSource ?? []).map((d) => ({ date: d.date, value: d.vercelPageviews }))
-            },
-            {
-              key: "ga4",
-              label: "Sessions",
-              source: "GA4",
-              complete: false,
-              unit: "count",
-              // The band runs from what GA4 measured up to where the capture model
-              // says it probably sits. The measured line is never replaced by it.
-              grossUpFactor: data.capture?.rate && data.capture.rate > 0 && data.capture.rate < 1 ? 1 / data.capture.rate : void 0,
-              points: (data.crossSource ?? []).map((d) => ({ date: d.date, value: d.ga4Sessions }))
+              points: (data.crossSource ?? []).map((d) => ({ date: d.date, value: d.vercelPageviews })),
+              shortfall: {
+                label: "Seen by GA4",
+                source: "GA4",
+                points: (data.crossSource ?? []).map((d) => ({ date: d.date, value: d.ga4Sessions }))
+              }
             },
             ...data.crossSource?.some((d) => d.revenue !== null) ? [{
               key: "revenue",