@liiift-studio/sanity-visitor-insights 0.20.0 → 0.22.0

package/dist/index.d.mts

@@ -52,6 +52,7 @@ type ReportState<T> = {
     status: 'ready';
     envelope: ReportEnvelope<T>;
     stale?: boolean;
+    revalidationError?: string;
 } | {
     status: 'error';
     message: string;
@@ -159,8 +160,15 @@ interface ComparisonBarProps {
     metric: MetricValue;
     /** Largest value across the sibling bars, used to scale width. */
     max: number;
-    /** Tone conveys category, but never carries meaning on its own. */
-    tone?: 'primary' | 'positive' | 'caution' | 'default';
+    /**
+     * What full width means, named.
+     *
+     * A ComparisonBar scales to the largest sibling, so a full bar means only "biggest of these" —
+     * and unlike the other two bar idioms, which print their share and their total, this one said
+     * nothing at all. There was a `tone` prop instead, which both call sites passed different
+     * values to and which the component destructured and never used.
+     */
+    outOf?: string;
 }
 /**
  * A horizontal bar with its value printed alongside.
@@ -169,7 +177,29 @@ interface ComparisonBarProps {
  * values, which a labelled bar does as well as a chart while avoiding a large dependency in the
  * 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;
+declare function ComparisonBar({ label, metric, max, outOf }: 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;
@@ -305,6 +335,8 @@ interface SortableTableProps<Row> {
     exportName?: string;
     /** Shown under the table when the server truncated the row set. */
     truncatedNote?: string;
+    /** Allow per-row exclusion even without a filter box. */
+    onExclude?: boolean;
 }
 /**
  * A table whose columns sort.
@@ -318,7 +350,7 @@ interface SortableTableProps<Row> {
  * unavailable metric is not a zero, and letting it lead an ascending sort would restate exactly the
  * confusion the MetricValue type exists to prevent.
  */
-declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, }: SortableTableProps<Row>): React.ReactElement;
+declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
 /**
  * One time axis, every source stacked against it.
@@ -394,6 +426,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.
@@ -401,10 +444,10 @@ 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.
+ * The report panels.
  *
  * Every panel renders a table or labelled bars rather than a chart, and every one surfaces its own
  * caveats inline. Tables are the accessible representation as well as the visual one, so there is
@@ -418,11 +461,6 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * undefined". A panel must degrade to showing less, never to a stack trace.
  */
 
-/**
- * Measurement Health — how much of reality each source sees.
- * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
- * subtracted from a pageview count.
- */
 /**
  * Overview — the five-minute read.
  *
@@ -432,9 +470,11 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * 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 }: {
+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.
@@ -512,4 +552,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionData, AcquisitionPanel, 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 };
+export { AcquisitionData, AcquisitionPanel, ChartData, type ChartDataProps, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, DataHealthPanel, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, DataHealthPanel as MeasurementHealthPanel, 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

@@ -52,6 +52,7 @@ type ReportState<T> = {
     status: 'ready';
     envelope: ReportEnvelope<T>;
     stale?: boolean;
+    revalidationError?: string;
 } | {
     status: 'error';
     message: string;
@@ -159,8 +160,15 @@ interface ComparisonBarProps {
     metric: MetricValue;
     /** Largest value across the sibling bars, used to scale width. */
     max: number;
-    /** Tone conveys category, but never carries meaning on its own. */
-    tone?: 'primary' | 'positive' | 'caution' | 'default';
+    /**
+     * What full width means, named.
+     *
+     * A ComparisonBar scales to the largest sibling, so a full bar means only "biggest of these" —
+     * and unlike the other two bar idioms, which print their share and their total, this one said
+     * nothing at all. There was a `tone` prop instead, which both call sites passed different
+     * values to and which the component destructured and never used.
+     */
+    outOf?: string;
 }
 /**
  * A horizontal bar with its value printed alongside.
@@ -169,7 +177,29 @@ interface ComparisonBarProps {
  * values, which a labelled bar does as well as a chart while avoiding a large dependency in the
  * 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;
+declare function ComparisonBar({ label, metric, max, outOf }: 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;
@@ -305,6 +335,8 @@ interface SortableTableProps<Row> {
     exportName?: string;
     /** Shown under the table when the server truncated the row set. */
     truncatedNote?: string;
+    /** Allow per-row exclusion even without a filter box. */
+    onExclude?: boolean;
 }
 /**
  * A table whose columns sort.
@@ -318,7 +350,7 @@ interface SortableTableProps<Row> {
  * unavailable metric is not a zero, and letting it lead an ascending sort would restate exactly the
  * confusion the MetricValue type exists to prevent.
  */
-declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, }: SortableTableProps<Row>): React.ReactElement;
+declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
 /**
  * One time axis, every source stacked against it.
@@ -394,6 +426,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.
@@ -401,10 +444,10 @@ 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.
+ * The report panels.
  *
  * Every panel renders a table or labelled bars rather than a chart, and every one surfaces its own
  * caveats inline. Tables are the accessible representation as well as the visual one, so there is
@@ -418,11 +461,6 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * undefined". A panel must degrade to showing less, never to a stack trace.
  */
 
-/**
- * Measurement Health — how much of reality each source sees.
- * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
- * subtracted from a pageview count.
- */
 /**
  * Overview — the five-minute read.
  *
@@ -432,9 +470,11 @@ declare function CrossSourceTimeline({ series, markers, currency }: CrossSourceT
  * 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 }: {
+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.
@@ -512,4 +552,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionData, AcquisitionPanel, 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 };
+export { AcquisitionData, AcquisitionPanel, ChartData, type ChartDataProps, ComparisonBar, CrossSourceTimeline, type CrossSourceTimelineProps, DataHealthPanel, Delta, type DeltaProps, DiagnosticReport, DiagnosticsPanel, FunnelChart, JourneyData, JourneyPanel, MeasurementHealthData, DataHealthPanel as MeasurementHealthPanel, 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 };