@liiift-studio/sanity-visitor-insights 0.46.0 → 0.48.0

package/README.md

@@ -19,7 +19,23 @@ only as a conversion anchor and a count; no revenue, and no customer data.
 | **Typeface interest** | Which families get viewed, tested and bought? |
 | **Diagnostics** | What to fix before trusting any of the above? |
 
-Each panel offers a week, quarter or year range.
+Each panel offers a week, quarter or year range, a custom window, and a choice of what the changes
+are measured against — the preceding window, or the same window a year earlier. Type sales are
+seasonal, so a quiet August against a quiet July often says less than August against last August.
+Both cost the same: one comparison window either way.
+
+Four figures are derived from the ones above rather than measured separately:
+
+| Figure | How it is arrived at |
+|---|---|
+| **Average order value** | Revenue over the orders that *carry an amount*, not over every counted order. Marked partial, naming both counts, whenever those differ. |
+| **Visitors per order** | Vercel visitors over orders. Vercel because it is server-side and complete; GA4 sessions would flatter the ratio by roughly the shortfall. |
+| **Orders after a send** | What the order book records in the three days following each email, ending early if another send lands first, so no order is counted twice. |
+| **Revenue per 1,000 sent** | The same window's revenue scaled to a thousand addresses — per send it is fractions of a cent and every campaign renders as the same zero. |
+
+The last two are **what happened next, not what the send caused**. They are built from send times and
+order times, both of which are exact, rather than from GA4's campaign attribution, which at a
+foundry's volumes is withheld for being too thin to divide revenue by.
 
 ---
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as sanity from 'sanity';
 import React from 'react';
-import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-CWGvBi3C.mjs';
-export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as CrossSourceDay, i as DailyPoint, j as DateRange, k as DiagnosticCheck, E as EmailCampaign, l as EventCutover, m as JourneyOutcome, n as JourneyStep, L as LandingPage, o as LicenceTierRow, P as PREEXISTING, p as REPORT_NAMES, q as ReportError, S as SiteAnalyticsConfig, r as SourceName, s as SourceRow, t as SourceStatus, u as TimelineEvent, v as TypefaceInterestRow, U as UnavailableReason, w as coverageForRange, x as estimated, y as isReportName, z as ok, B as partial, F as previousRange, G as resolveRange, H as unavailable, I as validateSiteConfig, K as valueOrNull } from './ranges-CWGvBi3C.mjs';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-CeB8esIA.mjs';
+export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as CrossSourceDay, i as DailyPoint, j as DateRange, k as DiagnosticCheck, E as EmailCampaign, l as EventCutover, m as JourneyOutcome, n as JourneyStep, L as LandingPage, o as LicenceTierRow, P as PREEXISTING, p as REPORT_NAMES, q as ReportError, S as SiteAnalyticsConfig, r as SourceName, s as SourceRow, t as SourceStatus, u as TimelineEvent, v as TypefaceInterestRow, U as UnavailableReason, w as coverageForRange, x as estimated, y as isReportName, z as ok, B as partial, F as previousRange, G as resolveRange, H as unavailable, I as validateSiteConfig, K as valueOrNull } from './ranges-CeB8esIA.mjs';
 
 /**
  * Data hook for the Studio panels.
@@ -51,6 +51,8 @@ interface UseReportOptions {
     apiBaseUrl: string;
     report: ReportName;
     range: RangeKey;
+    /** Which baseline the deltas are measured against. Defaults to the preceding window. */
+    compare?: 'previous-period' | 'same-period-last-year';
     /**
      * Whether to fetch at all. Defaults to true.
      *
@@ -64,7 +66,7 @@ interface UseReportOptions {
  *
  * @returns the current state plus a `reload` for manual refresh
  */
-declare function useReport<T>({ apiBaseUrl, report, range, custom, enabled }: UseReportOptions): {
+declare function useReport<T>({ apiBaseUrl, report, range, custom, compare, enabled }: UseReportOptions): {
     state: ReportState<T>;
     reload: () => void;
 };
@@ -401,6 +403,34 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * The series palette, and the rules that keep it honest.
+ *
+ * Every chart in this package was drawn in `currentColor` at varying alpha, so five series on one
+ * chart were five greys separated by dash pattern alone. That is legible in a screenshot and not
+ * in use: a reader tracking co-movement between GA4 and Vercel had to keep which-line-is-which in
+ * their head while looking at the shape.
+ *
+ * Three constraints decided these values, and all three are enforced by tests rather than asserted
+ * here:
+ *
+ * 1. ONE SET FOR BOTH THEMES. The Studio ships light and dark and this component is not told which
+ *    it is in. Rather than swap palettes at a breakpoint we cannot observe, every colour clears
+ *    3:1 — the WCAG floor for a graphical object — against BOTH a white card and Sanity's dark
+ *    card. That is what pins them to mid-lightness.
+ *
+ * 2. HUE FAMILY MEANS SOURCE. The two GA4 series are deliberately neighbours in the warm range,
+ *    because they are the same instrument measuring two things; Vercel, orders and revenue each
+ *    get their own family. So the palette carries a fact rather than just distinguishing rows.
+ *
+ * 3. COLOUR IS NEVER THE ONLY CHANNEL. Completeness stays encoded as a dash pattern and every
+ *    value stays readable in the tooltip. The two GA4 hues are close enough to converge for a
+ *    deuteranope — which is acceptable precisely because dash and label still separate them, and
+ *    unacceptable for any pair that does not have that second channel.
+ */
+/** One series colour. The key names what it measures, not what it looks like. */
+type SeriesKey = 'vercel' | 'ga4Pageviews' | 'ga4Sessions' | 'orders' | 'revenue';
+
 /**
  * One time axis, every source stacked against it.
  *
@@ -431,15 +461,6 @@ interface SeriesPoint {
 }
 /** How a value should be written out. */
 type SeriesUnit = 'count' | 'money' | 'percent';
-/**
- * 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;
@@ -447,6 +468,15 @@ interface Series {
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
     /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
+    /**
+     * Which series colour this row draws in.
+     *
+     * Optional, and falling back to the row's `source`, so a caller that adds a row gets a colour
+     * consistent with every other row from the same upstream rather than an uncoloured one. Set it
+     * explicitly only where the source does not decide the meaning — coverage is computed FROM GA4
+     * and Vercel and belongs to neither.
+     */
+    color?: SeriesKey;
     unit: SeriesUnit;
     /**
      * How the row is drawn. Defaults to `line`.
@@ -492,6 +522,8 @@ interface Series {
      */
     shortfall?: {
         label: string;
+        /** The lossier source's colour. Falls back to its `source`, as the row's own does. */
+        color?: SeriesKey;
         source: Series['source'];
         points: SeriesPoint[];
     };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as sanity from 'sanity';
 import React from 'react';
-import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-CWGvBi3C.js';
-export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as CrossSourceDay, i as DailyPoint, j as DateRange, k as DiagnosticCheck, E as EmailCampaign, l as EventCutover, m as JourneyOutcome, n as JourneyStep, L as LandingPage, o as LicenceTierRow, P as PREEXISTING, p as REPORT_NAMES, q as ReportError, S as SiteAnalyticsConfig, r as SourceName, s as SourceRow, t as SourceStatus, u as TimelineEvent, v as TypefaceInterestRow, U as UnavailableReason, w as coverageForRange, x as estimated, y as isReportName, z as ok, B as partial, F as previousRange, G as resolveRange, H as unavailable, I as validateSiteConfig, K as valueOrNull } from './ranges-CWGvBi3C.js';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-CeB8esIA.js';
+export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as CrossSourceDay, i as DailyPoint, j as DateRange, k as DiagnosticCheck, E as EmailCampaign, l as EventCutover, m as JourneyOutcome, n as JourneyStep, L as LandingPage, o as LicenceTierRow, P as PREEXISTING, p as REPORT_NAMES, q as ReportError, S as SiteAnalyticsConfig, r as SourceName, s as SourceRow, t as SourceStatus, u as TimelineEvent, v as TypefaceInterestRow, U as UnavailableReason, w as coverageForRange, x as estimated, y as isReportName, z as ok, B as partial, F as previousRange, G as resolveRange, H as unavailable, I as validateSiteConfig, K as valueOrNull } from './ranges-CeB8esIA.js';
 
 /**
  * Data hook for the Studio panels.
@@ -51,6 +51,8 @@ interface UseReportOptions {
     apiBaseUrl: string;
     report: ReportName;
     range: RangeKey;
+    /** Which baseline the deltas are measured against. Defaults to the preceding window. */
+    compare?: 'previous-period' | 'same-period-last-year';
     /**
      * Whether to fetch at all. Defaults to true.
      *
@@ -64,7 +66,7 @@ interface UseReportOptions {
  *
  * @returns the current state plus a `reload` for manual refresh
  */
-declare function useReport<T>({ apiBaseUrl, report, range, custom, enabled }: UseReportOptions): {
+declare function useReport<T>({ apiBaseUrl, report, range, custom, compare, enabled }: UseReportOptions): {
     state: ReportState<T>;
     reload: () => void;
 };
@@ -401,6 +403,34 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * The series palette, and the rules that keep it honest.
+ *
+ * Every chart in this package was drawn in `currentColor` at varying alpha, so five series on one
+ * chart were five greys separated by dash pattern alone. That is legible in a screenshot and not
+ * in use: a reader tracking co-movement between GA4 and Vercel had to keep which-line-is-which in
+ * their head while looking at the shape.
+ *
+ * Three constraints decided these values, and all three are enforced by tests rather than asserted
+ * here:
+ *
+ * 1. ONE SET FOR BOTH THEMES. The Studio ships light and dark and this component is not told which
+ *    it is in. Rather than swap palettes at a breakpoint we cannot observe, every colour clears
+ *    3:1 — the WCAG floor for a graphical object — against BOTH a white card and Sanity's dark
+ *    card. That is what pins them to mid-lightness.
+ *
+ * 2. HUE FAMILY MEANS SOURCE. The two GA4 series are deliberately neighbours in the warm range,
+ *    because they are the same instrument measuring two things; Vercel, orders and revenue each
+ *    get their own family. So the palette carries a fact rather than just distinguishing rows.
+ *
+ * 3. COLOUR IS NEVER THE ONLY CHANNEL. Completeness stays encoded as a dash pattern and every
+ *    value stays readable in the tooltip. The two GA4 hues are close enough to converge for a
+ *    deuteranope — which is acceptable precisely because dash and label still separate them, and
+ *    unacceptable for any pair that does not have that second channel.
+ */
+/** One series colour. The key names what it measures, not what it looks like. */
+type SeriesKey = 'vercel' | 'ga4Pageviews' | 'ga4Sessions' | 'orders' | 'revenue';
+
 /**
  * One time axis, every source stacked against it.
  *
@@ -431,15 +461,6 @@ interface SeriesPoint {
 }
 /** How a value should be written out. */
 type SeriesUnit = 'count' | 'money' | 'percent';
-/**
- * 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;
@@ -447,6 +468,15 @@ interface Series {
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
     /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
+    /**
+     * Which series colour this row draws in.
+     *
+     * Optional, and falling back to the row's `source`, so a caller that adds a row gets a colour
+     * consistent with every other row from the same upstream rather than an uncoloured one. Set it
+     * explicitly only where the source does not decide the meaning — coverage is computed FROM GA4
+     * and Vercel and belongs to neither.
+     */
+    color?: SeriesKey;
     unit: SeriesUnit;
     /**
      * How the row is drawn. Defaults to `line`.
@@ -492,6 +522,8 @@ interface Series {
      */
     shortfall?: {
         label: string;
+        /** The lossier source's colour. Falls back to its `source`, as the row's own does. */
+        color?: SeriesKey;
         source: Series['source'];
         points: SeriesPoint[];
     };