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

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, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-DvICo5H2.mjs';
-export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as DailyPoint, i as DateRange, j as DiagnosticCheck, E as EmailCampaign, k as EventCutover, l as JourneyOutcome, m as JourneyStep, L as LandingPage, P as PREEXISTING, n as REPORT_NAMES, o as ReportError, S as SiteAnalyticsConfig, p as SourceName, q as SourceRow, r as SourceStatus, s as TypefaceInterestRow, U as UnavailableReason, t as coverageForRange, u as estimated, v as isReportName, w as ok, x as partial, y as previousRange, z as resolveRange, B as unavailable, F as validateSiteConfig, G as valueOrNull } from './ranges-DvICo5H2.mjs';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-B_OrmcdP.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-B_OrmcdP.mjs';
 
 /**
  * The Visitor Insights Studio tool.
@@ -162,6 +162,33 @@ interface ComparisonBarProps {
  * Studio bundle and the theme-token bridging that a chart library would need for light and dark.
  */
 declare function ComparisonBar({ label, metric, max, tone }: ComparisonBarProps): React.ReactElement;
+/** One bar of a proportion chart. */
+interface ProportionBar {
+    key: string;
+    label: string;
+    sublabel?: string;
+    value: number;
+}
+/** Props for ProportionChart. */
+interface ProportionChartProps {
+    bars: ProportionBar[];
+    /** How to write each value out. */
+    format: (value: number) => string;
+    /** What the bars sum to, named — a share is meaningless without its denominator stated. */
+    totalLabel: string;
+}
+/**
+ * A ranked part-to-whole bar chart.
+ *
+ * For a breakdown whose rows sum to something meaningful — licence revenue by tier, say. Each bar
+ * carries its share of the total AND its absolute value, because a share alone hides that the
+ * leading row might be two orders, and an absolute alone hides that it is most of the business.
+ *
+ * Bars scale against the SUM rather than against the largest row, so the widths read as shares of
+ * the whole. Scaling to the max would make the top row full-width whatever it was worth, which is
+ * the same misreading the funnel avoids by anchoring to its entry step.
+ */
+declare function ProportionChart({ bars, format, totalLabel }: ProportionChartProps): React.ReactElement | null;
 /** One rung of the funnel, already filtered to steps that are actually measured. */
 interface FunnelStage {
     key: string;
@@ -285,6 +312,97 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * One time axis, every source stacked against it.
+ *
+ * This is the only view in the tool that answers a question no single source can: did the thing we
+ * did move the thing we care about. A campaign goes out on Tuesday — did traffic rise, did revenue
+ * follow, and did GA4 even see it. Vercel knows the traffic, Sanity knows the money, Mailchimp
+ * knows the send date, and GA4 knows a lossy fraction of the behaviour in between.
+ *
+ * SMALL MULTIPLES, NOT A DUAL AXIS. Putting pageviews and revenue on one pair of axes requires
+ * choosing a scale factor between them, and whatever is chosen manufactures a visual correlation
+ * that the data did not claim — two lines can be made to cross, diverge or track by nothing more
+ * than the ratio picked. Stacked rows sharing one x axis show the same co-movement and assert
+ * nothing about relative magnitude, because each row carries its own y axis and its own units.
+ *
+ * COMPLETENESS IS DRAWN. A series from a source that misses things is dashed and carries a shaded
+ * band up to its estimated true value; a complete source is a solid line. The reader learns which
+ * numbers are facts and which are a fifth of the facts without being told twice.
+ *
+ * d3 is used for scales and path generation only — pure functions in, path strings out. No
+ * d3-selection, so nothing here touches the DOM and the whole chart renders under
+ * renderToStaticMarkup, which is how the tests exercise it.
+ */
+
+/** One point on one series. `value` null where the source reported nothing for that day. */
+interface SeriesPoint {
+    date: string;
+    value: number | null;
+}
+/** 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;
+    /** Which upstream the LINE came from. */
+    source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
+    /** Whether the line's source sees everything. Drives the stroke and the wording. */
+    complete: boolean;
+    unit: SeriesUnit;
+    points: SeriesPoint[];
+    /**
+     * 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;
+}
+/** A dated event drawn through every row, e.g. a campaign send. */
+interface TimelineMarker {
+    date: string;
+    label: string;
+    detail?: string;
+}
+/** Props for CrossSourceTimeline. */
+interface CrossSourceTimelineProps {
+    series: Series[];
+    markers?: TimelineMarker[];
+    /** ISO 4217 code for any `money` series. */
+    currency?: string | null;
+}
+/**
+ * The cross-source timeline.
+ *
+ * Renders nothing rather than an empty frame when there is not enough to plot — two points cannot
+ * show a shape, and an axis with one dot on it invites a reading it cannot support.
+ */
+declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceTimelineProps): React.ReactElement | null;
+
 /**
  * The four report panels.
  *
@@ -375,4 +493,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionData, AcquisitionPanel, ComparisonBar, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, type SortColumn, SortableTable, type SortableTableProps, TrendChart, TypefaceInterestData, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatMoney, formatPercent, useReport, visitorInsights };
+export { AcquisitionData, AcquisitionPanel, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, type ProportionBar, ProportionChart, type ProportionChartProps, RangeKey, ReportEnvelope, ReportName, type ReportState, type Series, type SeriesPoint, type SortColumn, SortableTable, type SortableTableProps, type TimelineMarker, TrendChart, TypefaceInterestData, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatMoney, formatPercent, useReport, visitorInsights };

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, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-DvICo5H2.js';
-export { C as CaptureBasis, d as CaptureEstimate, e as CaptureModel, f as CheckStatus, g as Coverage, h as DailyPoint, i as DateRange, j as DiagnosticCheck, E as EmailCampaign, k as EventCutover, l as JourneyOutcome, m as JourneyStep, L as LandingPage, P as PREEXISTING, n as REPORT_NAMES, o as ReportError, S as SiteAnalyticsConfig, p as SourceName, q as SourceRow, r as SourceStatus, s as TypefaceInterestRow, U as UnavailableReason, t as coverageForRange, u as estimated, v as isReportName, w as ok, x as partial, y as previousRange, z as resolveRange, B as unavailable, F as validateSiteConfig, G as valueOrNull } from './ranges-DvICo5H2.js';
+import { R as ReportEnvelope, a as ReportName, b as RangeKey, M as MetricValue, A as AcquisitionData, D as DiagnosticReport, J as JourneyData, c as MeasurementHealthData, T as TypefaceInterestData } from './ranges-B_OrmcdP.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-B_OrmcdP.js';
 
 /**
  * The Visitor Insights Studio tool.
@@ -162,6 +162,33 @@ interface ComparisonBarProps {
  * Studio bundle and the theme-token bridging that a chart library would need for light and dark.
  */
 declare function ComparisonBar({ label, metric, max, tone }: ComparisonBarProps): React.ReactElement;
+/** One bar of a proportion chart. */
+interface ProportionBar {
+    key: string;
+    label: string;
+    sublabel?: string;
+    value: number;
+}
+/** Props for ProportionChart. */
+interface ProportionChartProps {
+    bars: ProportionBar[];
+    /** How to write each value out. */
+    format: (value: number) => string;
+    /** What the bars sum to, named — a share is meaningless without its denominator stated. */
+    totalLabel: string;
+}
+/**
+ * A ranked part-to-whole bar chart.
+ *
+ * For a breakdown whose rows sum to something meaningful — licence revenue by tier, say. Each bar
+ * carries its share of the total AND its absolute value, because a share alone hides that the
+ * leading row might be two orders, and an absolute alone hides that it is most of the business.
+ *
+ * Bars scale against the SUM rather than against the largest row, so the widths read as shares of
+ * the whole. Scaling to the max would make the top row full-width whatever it was worth, which is
+ * the same misreading the funnel avoids by anchoring to its entry step.
+ */
+declare function ProportionChart({ bars, format, totalLabel }: ProportionChartProps): React.ReactElement | null;
 /** One rung of the funnel, already filtered to steps that are actually measured. */
 interface FunnelStage {
     key: string;
@@ -285,6 +312,97 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * One time axis, every source stacked against it.
+ *
+ * This is the only view in the tool that answers a question no single source can: did the thing we
+ * did move the thing we care about. A campaign goes out on Tuesday — did traffic rise, did revenue
+ * follow, and did GA4 even see it. Vercel knows the traffic, Sanity knows the money, Mailchimp
+ * knows the send date, and GA4 knows a lossy fraction of the behaviour in between.
+ *
+ * SMALL MULTIPLES, NOT A DUAL AXIS. Putting pageviews and revenue on one pair of axes requires
+ * choosing a scale factor between them, and whatever is chosen manufactures a visual correlation
+ * that the data did not claim — two lines can be made to cross, diverge or track by nothing more
+ * than the ratio picked. Stacked rows sharing one x axis show the same co-movement and assert
+ * nothing about relative magnitude, because each row carries its own y axis and its own units.
+ *
+ * COMPLETENESS IS DRAWN. A series from a source that misses things is dashed and carries a shaded
+ * band up to its estimated true value; a complete source is a solid line. The reader learns which
+ * numbers are facts and which are a fifth of the facts without being told twice.
+ *
+ * d3 is used for scales and path generation only — pure functions in, path strings out. No
+ * d3-selection, so nothing here touches the DOM and the whole chart renders under
+ * renderToStaticMarkup, which is how the tests exercise it.
+ */
+
+/** One point on one series. `value` null where the source reported nothing for that day. */
+interface SeriesPoint {
+    date: string;
+    value: number | null;
+}
+/** 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;
+    /** Which upstream the LINE came from. */
+    source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
+    /** Whether the line's source sees everything. Drives the stroke and the wording. */
+    complete: boolean;
+    unit: SeriesUnit;
+    points: SeriesPoint[];
+    /**
+     * 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;
+}
+/** A dated event drawn through every row, e.g. a campaign send. */
+interface TimelineMarker {
+    date: string;
+    label: string;
+    detail?: string;
+}
+/** Props for CrossSourceTimeline. */
+interface CrossSourceTimelineProps {
+    series: Series[];
+    markers?: TimelineMarker[];
+    /** ISO 4217 code for any `money` series. */
+    currency?: string | null;
+}
+/**
+ * The cross-source timeline.
+ *
+ * Renders nothing rather than an empty frame when there is not enough to plot — two points cannot
+ * show a shape, and an axis with one dot on it invites a reading it cannot support.
+ */
+declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceTimelineProps): React.ReactElement | null;
+
 /**
  * The four report panels.
  *
@@ -375,4 +493,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionData, AcquisitionPanel, ComparisonBar, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, type SortColumn, SortableTable, type SortableTableProps, TrendChart, TypefaceInterestData, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatMoney, formatPercent, useReport, visitorInsights };
+export { AcquisitionData, AcquisitionPanel, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, type ProportionBar, ProportionChart, type ProportionChartProps, RangeKey, ReportEnvelope, ReportName, type ReportState, type Series, type SeriesPoint, type SortColumn, SortableTable, type SortableTableProps, type TimelineMarker, TrendChart, TypefaceInterestData, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatMoney, formatPercent, useReport, visitorInsights };