@liiift-studio/sanity-visitor-insights 0.19.0 → 0.21.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 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-BUZuS1c-.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-BUZuS1c-.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-BUZuS1c-.mjs';
 
 /**
@@ -51,6 +51,7 @@ type ReportState<T> = {
 } | {
     status: 'ready';
     envelope: ReportEnvelope<T>;
+    stale?: boolean;
 } | {
     status: 'error';
     message: string;
@@ -67,13 +68,20 @@ interface UseReportOptions {
     apiBaseUrl: string;
     report: ReportName;
     range: RangeKey;
+    /**
+     * Whether to fetch at all. Defaults to true.
+     *
+     * Lets a panel declare a secondary report it only needs on one tab, without the other four
+     * paying a request for data they will not draw.
+     */
+    enabled?: boolean;
 }
 /**
  * Fetch a report, re-fetching when the range changes.
  *
  * @returns the current state plus a `reload` for manual refresh
  */
-declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOptions): {
+declare function useReport<T>({ apiBaseUrl, report, range, custom, enabled }: UseReportOptions): {
     state: ReportState<T>;
     reload: () => void;
 };
@@ -162,6 +170,28 @@ 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;
+/** Props for ChartData. */
+interface ChartDataProps<Row> {
+    /** What the disclosure is called. Names the chart it belongs to. */
+    label: string;
+    rows: Row[];
+    columns: Array<SortColumn<Row>>;
+    rowKey: (row: Row) => string;
+    exportName?: string;
+}
+/**
+ * The figures behind a chart, as a table, collapsed by default.
+ *
+ * A chart is a picture of the data and not the data. Every other panel here renders a table for
+ * exactly that reason — the file header used to say so, and it stopped being true the moment the
+ * charts landed, leaving two time series with no equivalent anywhere in the tool.
+ *
+ * One disclosure serves four readers at once: someone using a screen reader, for whom an SVG under
+ * `role="img"` is a single opaque node; someone navigating by keyboard; someone who cannot resolve
+ * axis type at any size; and anyone who wants these numbers in a spreadsheet, since the table
+ * brings sorting and CSV copy with it. Collapsed, so it costs a sighted reader one line.
+ */
+declare function ChartData<Row>({ label, rows, columns, rowKey, exportName }: ChartDataProps<Row>): React.ReactElement | null;
 /** One bar of a proportion chart. */
 interface ProportionBar {
     key: string;
@@ -386,6 +416,17 @@ interface CrossSourceTimelineProps {
     markers?: TimelineMarker[];
     /** ISO 4217 code for any `money` series. */
     currency?: string | null;
+    /**
+     * Called when the reader drags across a span, with inclusive ISO dates.
+     *
+     * Time is the only dimension all four sources genuinely share, which makes it the only thing
+     * worth linking on — a referrer row carries no date and a funnel step carries no source, so
+     * value-based cross-filtering would need dimensions the reports do not request and could not
+     * afford. Dragging a span and having every panel reflow to it is the whole of the cross-filter
+     * this data model supports, and it costs one callback: the range state already drives
+     * everything.
+     */
+    onBrush?: (start: string, end: string) => void;
 }
 /**
  * The cross-source timeline.
@@ -393,7 +434,7 @@ interface CrossSourceTimelineProps {
  * 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;
+declare function CrossSourceTimeline({ series, markers, currency, onBrush }: CrossSourceTimelineProps): React.ReactElement | null;
 
 /**
  * The four report panels.
@@ -415,9 +456,30 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
  * subtracted from a pageview count.
  */
-declare function MeasurementHealthPanel({ data, previous }: {
+/**
+ * Overview — the five-minute read.
+ *
+ * Revenue, orders, the mailing list, the cross-source timeline and the campaign table all used to
+ * live on a tab called "Measurement health", whose own blurb announced it was about how much of
+ * reality each source sees. Four of the five questions a foundry owner opens this for were filed
+ * under plumbing, on tab four, behind a door labelled for the instrument. This is the same data,
+ * first, under a heading that says what it is.
+ */
+declare function OverviewPanel({ data, previous, onBrush }: {
     data: MeasurementHealthData;
     previous?: MeasurementHealthData;
+    /** Narrow every panel to a span dragged on the timeline. */
+    onBrush?: (start: string, end: string) => void;
+}): React.ReactElement;
+/**
+ * Data health — the instrument, deliberately last.
+ *
+ * Everything here answers one question: can I trust the numbers on the other tabs. It was two
+ * separate tabs answering that question, which is one more than it deserves out of five.
+ */
+declare function DataHealthPanel({ data, diagnostics }: {
+    data: MeasurementHealthData;
+    diagnostics?: DiagnosticReport;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
 declare function AcquisitionPanel({ data, previous }: {
@@ -485,4 +547,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-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 };
+export { AcquisitionData, AcquisitionPanel, ChartData, type ChartDataProps, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, DataHealthPanel, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MetricFigure, MetricValue, NoticeList, OverviewPanel, 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,6 +1,6 @@
 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-BUZuS1c-.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-BUZuS1c-.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-BUZuS1c-.js';
 
 /**
@@ -51,6 +51,7 @@ type ReportState<T> = {
 } | {
     status: 'ready';
     envelope: ReportEnvelope<T>;
+    stale?: boolean;
 } | {
     status: 'error';
     message: string;
@@ -67,13 +68,20 @@ interface UseReportOptions {
     apiBaseUrl: string;
     report: ReportName;
     range: RangeKey;
+    /**
+     * Whether to fetch at all. Defaults to true.
+     *
+     * Lets a panel declare a secondary report it only needs on one tab, without the other four
+     * paying a request for data they will not draw.
+     */
+    enabled?: boolean;
 }
 /**
  * Fetch a report, re-fetching when the range changes.
  *
  * @returns the current state plus a `reload` for manual refresh
  */
-declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOptions): {
+declare function useReport<T>({ apiBaseUrl, report, range, custom, enabled }: UseReportOptions): {
     state: ReportState<T>;
     reload: () => void;
 };
@@ -162,6 +170,28 @@ 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;
+/** Props for ChartData. */
+interface ChartDataProps<Row> {
+    /** What the disclosure is called. Names the chart it belongs to. */
+    label: string;
+    rows: Row[];
+    columns: Array<SortColumn<Row>>;
+    rowKey: (row: Row) => string;
+    exportName?: string;
+}
+/**
+ * The figures behind a chart, as a table, collapsed by default.
+ *
+ * A chart is a picture of the data and not the data. Every other panel here renders a table for
+ * exactly that reason — the file header used to say so, and it stopped being true the moment the
+ * charts landed, leaving two time series with no equivalent anywhere in the tool.
+ *
+ * One disclosure serves four readers at once: someone using a screen reader, for whom an SVG under
+ * `role="img"` is a single opaque node; someone navigating by keyboard; someone who cannot resolve
+ * axis type at any size; and anyone who wants these numbers in a spreadsheet, since the table
+ * brings sorting and CSV copy with it. Collapsed, so it costs a sighted reader one line.
+ */
+declare function ChartData<Row>({ label, rows, columns, rowKey, exportName }: ChartDataProps<Row>): React.ReactElement | null;
 /** One bar of a proportion chart. */
 interface ProportionBar {
     key: string;
@@ -386,6 +416,17 @@ interface CrossSourceTimelineProps {
     markers?: TimelineMarker[];
     /** ISO 4217 code for any `money` series. */
     currency?: string | null;
+    /**
+     * Called when the reader drags across a span, with inclusive ISO dates.
+     *
+     * Time is the only dimension all four sources genuinely share, which makes it the only thing
+     * worth linking on — a referrer row carries no date and a funnel step carries no source, so
+     * value-based cross-filtering would need dimensions the reports do not request and could not
+     * afford. Dragging a span and having every panel reflow to it is the whole of the cross-filter
+     * this data model supports, and it costs one callback: the range state already drives
+     * everything.
+     */
+    onBrush?: (start: string, end: string) => void;
 }
 /**
  * The cross-source timeline.
@@ -393,7 +434,7 @@ interface CrossSourceTimelineProps {
  * 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;
+declare function CrossSourceTimeline({ series, markers, currency, onBrush }: CrossSourceTimelineProps): React.ReactElement | null;
 
 /**
  * The four report panels.
@@ -415,9 +456,30 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
  * subtracted from a pageview count.
  */
-declare function MeasurementHealthPanel({ data, previous }: {
+/**
+ * Overview — the five-minute read.
+ *
+ * Revenue, orders, the mailing list, the cross-source timeline and the campaign table all used to
+ * live on a tab called "Measurement health", whose own blurb announced it was about how much of
+ * reality each source sees. Four of the five questions a foundry owner opens this for were filed
+ * under plumbing, on tab four, behind a door labelled for the instrument. This is the same data,
+ * first, under a heading that says what it is.
+ */
+declare function OverviewPanel({ data, previous, onBrush }: {
     data: MeasurementHealthData;
     previous?: MeasurementHealthData;
+    /** Narrow every panel to a span dragged on the timeline. */
+    onBrush?: (start: string, end: string) => void;
+}): React.ReactElement;
+/**
+ * Data health — the instrument, deliberately last.
+ *
+ * Everything here answers one question: can I trust the numbers on the other tabs. It was two
+ * separate tabs answering that question, which is one more than it deserves out of five.
+ */
+declare function DataHealthPanel({ data, diagnostics }: {
+    data: MeasurementHealthData;
+    diagnostics?: DiagnosticReport;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
 declare function AcquisitionPanel({ data, previous }: {
@@ -485,4 +547,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-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 };
+export { AcquisitionData, AcquisitionPanel, ChartData, type ChartDataProps, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, DataHealthPanel, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, MetricFigure, MetricValue, NoticeList, OverviewPanel, 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 };