@liiift-studio/sanity-visitor-insights 0.13.0 → 0.14.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-CiTnQEnz.mjs';
-export { C as Coverage, d as DateRange, E as EventCutover, P as PREEXISTING, e as REPORT_NAMES, f as ReportError, S as SiteAnalyticsConfig, g as SourceName, h as SourceStatus, U as UnavailableReason, i as coverageForRange, j as isReportName, o as ok, p as partial, k as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-CiTnQEnz.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-CEHxJQE6.mjs';
+export { C as CheckStatus, d as Coverage, e as DailyPoint, f as DateRange, g as DiagnosticCheck, E as EventCutover, h as JourneyOutcome, i as JourneyStep, L as LandingPage, P as PREEXISTING, j as REPORT_NAMES, k as ReportError, S as SiteAnalyticsConfig, l as SourceName, m as SourceRow, n as SourceStatus, o as TypefaceInterestRow, U as UnavailableReason, p as coverageForRange, q as isReportName, r as ok, s as partial, t as previousRange, u as resolveRange, v as unavailable, w as validateSiteConfig, x as valueOrNull } from './ranges-CEHxJQE6.mjs';
 
 /**
  * The Visitor Insights Studio tool.
@@ -93,6 +93,35 @@ declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOp
 declare function formatCount(value: number): string;
 /** Format a 0–1 ratio as a percentage. */
 declare function formatPercent(ratio: number, digits?: number): string;
+/** Props for MetricFigure. */
+/** Format a money value in the site's currency, falling back to a plain number. */
+declare function formatMoney(value: number, currency: string | null): string;
+/** Props for Delta. */
+interface DeltaProps {
+    /** This period's value, or null when it could not be measured. */
+    current: number | null;
+    /** The previous equivalent period's value, or null when there is no comparison. */
+    previous: number | null;
+    /**
+     * Whether a rise is good. Sessions and revenue: yes. A shortfall or a bounce figure: no.
+     * Drives only the wording and the tone, never whether the number is shown.
+     */
+    riseIsGood?: boolean;
+    /** Render as a percentage-point change rather than a percentage change of a percentage. */
+    unit?: 'count' | 'percent';
+}
+/**
+ * A period-over-period change.
+ *
+ * Every figure in this tool used to be a bare level, which at these volumes is close to
+ * meaningless: "389 sessions" is neither good nor bad without last week beside it, and the
+ * 24 August collapse would have announced itself on every panel as a delta while going unnoticed
+ * for over a week as a level.
+ *
+ * Renders nothing at all when there is no comparison — an absent delta must never be drawn as
+ * "no change", which is a different and much more reassuring claim.
+ */
+declare function Delta({ current, previous, riseIsGood, unit }: DeltaProps): React.ReactElement | null;
 interface MetricFigureProps {
     metric: MetricValue;
     /** Accessible label describing what this number counts. */
@@ -133,6 +162,38 @@ 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 rung of the funnel, already filtered to steps that are actually measured. */
+interface FunnelStage {
+    key: string;
+    label: string;
+    /** Distinct users at this step. */
+    value: number;
+    /** Share of the previous shown step, or null when it could not be computed. */
+    conversionFromPrevious: number | null;
+}
+/** Props for FunnelChart. */
+interface FunnelChartProps {
+    stages: FunnelStage[];
+    /**
+     * Whether the stages are a tracked sequence or independent totals. The drawing is the same
+     * shape either way, but the words between stages are not: a fallback's gap is a difference
+     * between two counts, not people who dropped out.
+     */
+    measurement: 'sequence' | 'independent-totals';
+}
+/**
+ * A funnel.
+ *
+ * Widths are a share of the FIRST stage rather than of the largest, which is what makes it read as
+ * a funnel: every rung answers "of everyone who arrived, how many got this far". Anchoring to the
+ * max instead would make the widest stage full-width wherever it sat, and a mid-funnel step wider
+ * than entry — which happens on the independent-totals fallback, where `add_to_cart` can exceed
+ * `page_view` — would silently rescale everything above it.
+ *
+ * Stages are focusable so the figures are reachable without a pointer; the readout is rendered as
+ * text under the stage rather than as a floating tooltip so it is also visible on touch.
+ */
+declare function FunnelChart({ stages, measurement }: FunnelChartProps): React.ReactElement | null;
 /** Props for NoticeList. */
 interface NoticeListProps {
     notices: string[];
@@ -142,6 +203,87 @@ interface NoticeListProps {
  * Rendered in the panel rather than a README: a caveat nobody sees does not prevent a wrong read.
  */
 declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
+/** Props for TrendChart. */
+interface TrendChartProps {
+    /** Daily points, oldest first. */
+    points: Array<{
+        date: string;
+        ga4: number | null;
+        vercel: number | null;
+    }>;
+    /** Accessible description of what the two lines are. */
+    label?: string;
+}
+/**
+ * Daily GA4 against Vercel, with axes, dated ticks and a hover readout.
+ *
+ * The shaded band between the lines is the point of the chart rather than decoration: it IS the
+ * measurement gap, and seeing where it opens is what distinguishes an incident from a standing
+ * difference. Darden's opened overnight on 2026-08-24 and stayed open for over a week, which no
+ * scalar on this panel could have shown.
+ *
+ * Inline SVG with no charting library — one dependency-free element in a Studio that already loads
+ * a great deal, and it renders on the server so the tests can assert on it. Strokes use
+ * currentColor so the whole thing follows the Studio's theme without a palette of its own.
+ */
+declare function TrendChart({ points, label }: TrendChartProps): React.ReactElement | null;
+/** One column of a sortable table. */
+interface SortColumn<Row> {
+    /** Stable key, also used as the sort key. */
+    key: string;
+    label: string;
+    /** Right-aligned and sorted high-to-low first, the way a reader expects of a figure. */
+    numeric?: boolean;
+    /**
+     * Value to sort on. Return null for "no value" — those always sort last regardless of
+     * direction, because an unmeasured row is not a small one and must not lead an ascending sort.
+     */
+    sortValue: (row: Row) => number | string | null;
+    /**
+     * Value written to the CSV, when it differs from the sort key.
+     *
+     * Defaults to `sortValue`, which is right for a plain count and wrong for anything formatted:
+     * a rate sorts on 0.4318 and displays 43%, revenue sorts on a bare number and displays a
+     * currency, and a column with a fallback displays something `sortValue` returns null for.
+     */
+    exportValue?: (row: Row) => number | string | null;
+    render: (row: Row) => React.ReactNode;
+}
+/** Props for SortableTable. */
+interface SortableTableProps<Row> {
+    caption: string;
+    columns: Array<SortColumn<Row>>;
+    rows: Row[];
+    rowKey: (row: Row) => string;
+    /** Column sorted on first load. Defaults to the server's own ordering. */
+    initialSort?: string;
+    /**
+     * The text a row is matched against when filtering. Omit to render no filter box.
+     *
+     * Sorting was the tool's entire interaction budget, which meant a reader who spotted an
+     * unrelated site's traffic in the table had no way to take it out and see what was left.
+     */
+    filterOn?: (row: Row) => string;
+    /** Placeholder for the filter box, naming what is searched. */
+    filterPlaceholder?: string;
+    /** Base filename for the CSV export. Omit to render no export control. */
+    exportName?: string;
+    /** Shown under the table when the server truncated the row set. */
+    truncatedNote?: string;
+}
+/**
+ * A table whose columns sort.
+ *
+ * Both data tables arrived in one server-chosen order — sessions descending, views descending — so
+ * the only question they could answer was the one that order encoded. Sorting by any column turns
+ * the same rows into several different questions: which family is tested most relative to views,
+ * which source is least attributed, which typeface sells without being looked at.
+ *
+ * Rows with no value for the active column sort last in both directions. That is deliberate: an
+ * 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;
 
 /**
  * The four report panels.
@@ -163,8 +305,9 @@ declare function NoticeList({ notices }: NoticeListProps): React.ReactElement |
  * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
  * subtracted from a pageview count.
  */
-declare function MeasurementHealthPanel({ data }: {
+declare function MeasurementHealthPanel({ data, previous }: {
     data: MeasurementHealthData;
+    previous?: MeasurementHealthData;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
 declare function AcquisitionPanel({ data, previous }: {
@@ -232,4 +375,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionPanel, ComparisonBar, DiagnosticsPanel, JourneyPanel, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };
+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 };

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-CiTnQEnz.js';
-export { C as Coverage, d as DateRange, E as EventCutover, P as PREEXISTING, e as REPORT_NAMES, f as ReportError, S as SiteAnalyticsConfig, g as SourceName, h as SourceStatus, U as UnavailableReason, i as coverageForRange, j as isReportName, o as ok, p as partial, k as previousRange, r as resolveRange, u as unavailable, v as validateSiteConfig, l as valueOrNull } from './ranges-CiTnQEnz.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-CEHxJQE6.js';
+export { C as CheckStatus, d as Coverage, e as DailyPoint, f as DateRange, g as DiagnosticCheck, E as EventCutover, h as JourneyOutcome, i as JourneyStep, L as LandingPage, P as PREEXISTING, j as REPORT_NAMES, k as ReportError, S as SiteAnalyticsConfig, l as SourceName, m as SourceRow, n as SourceStatus, o as TypefaceInterestRow, U as UnavailableReason, p as coverageForRange, q as isReportName, r as ok, s as partial, t as previousRange, u as resolveRange, v as unavailable, w as validateSiteConfig, x as valueOrNull } from './ranges-CEHxJQE6.js';
 
 /**
  * The Visitor Insights Studio tool.
@@ -93,6 +93,35 @@ declare function useReport<T>({ apiBaseUrl, report, range, custom }: UseReportOp
 declare function formatCount(value: number): string;
 /** Format a 0–1 ratio as a percentage. */
 declare function formatPercent(ratio: number, digits?: number): string;
+/** Props for MetricFigure. */
+/** Format a money value in the site's currency, falling back to a plain number. */
+declare function formatMoney(value: number, currency: string | null): string;
+/** Props for Delta. */
+interface DeltaProps {
+    /** This period's value, or null when it could not be measured. */
+    current: number | null;
+    /** The previous equivalent period's value, or null when there is no comparison. */
+    previous: number | null;
+    /**
+     * Whether a rise is good. Sessions and revenue: yes. A shortfall or a bounce figure: no.
+     * Drives only the wording and the tone, never whether the number is shown.
+     */
+    riseIsGood?: boolean;
+    /** Render as a percentage-point change rather than a percentage change of a percentage. */
+    unit?: 'count' | 'percent';
+}
+/**
+ * A period-over-period change.
+ *
+ * Every figure in this tool used to be a bare level, which at these volumes is close to
+ * meaningless: "389 sessions" is neither good nor bad without last week beside it, and the
+ * 24 August collapse would have announced itself on every panel as a delta while going unnoticed
+ * for over a week as a level.
+ *
+ * Renders nothing at all when there is no comparison — an absent delta must never be drawn as
+ * "no change", which is a different and much more reassuring claim.
+ */
+declare function Delta({ current, previous, riseIsGood, unit }: DeltaProps): React.ReactElement | null;
 interface MetricFigureProps {
     metric: MetricValue;
     /** Accessible label describing what this number counts. */
@@ -133,6 +162,38 @@ 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 rung of the funnel, already filtered to steps that are actually measured. */
+interface FunnelStage {
+    key: string;
+    label: string;
+    /** Distinct users at this step. */
+    value: number;
+    /** Share of the previous shown step, or null when it could not be computed. */
+    conversionFromPrevious: number | null;
+}
+/** Props for FunnelChart. */
+interface FunnelChartProps {
+    stages: FunnelStage[];
+    /**
+     * Whether the stages are a tracked sequence or independent totals. The drawing is the same
+     * shape either way, but the words between stages are not: a fallback's gap is a difference
+     * between two counts, not people who dropped out.
+     */
+    measurement: 'sequence' | 'independent-totals';
+}
+/**
+ * A funnel.
+ *
+ * Widths are a share of the FIRST stage rather than of the largest, which is what makes it read as
+ * a funnel: every rung answers "of everyone who arrived, how many got this far". Anchoring to the
+ * max instead would make the widest stage full-width wherever it sat, and a mid-funnel step wider
+ * than entry — which happens on the independent-totals fallback, where `add_to_cart` can exceed
+ * `page_view` — would silently rescale everything above it.
+ *
+ * Stages are focusable so the figures are reachable without a pointer; the readout is rendered as
+ * text under the stage rather than as a floating tooltip so it is also visible on touch.
+ */
+declare function FunnelChart({ stages, measurement }: FunnelChartProps): React.ReactElement | null;
 /** Props for NoticeList. */
 interface NoticeListProps {
     notices: string[];
@@ -142,6 +203,87 @@ interface NoticeListProps {
  * Rendered in the panel rather than a README: a caveat nobody sees does not prevent a wrong read.
  */
 declare function NoticeList({ notices }: NoticeListProps): React.ReactElement | null;
+/** Props for TrendChart. */
+interface TrendChartProps {
+    /** Daily points, oldest first. */
+    points: Array<{
+        date: string;
+        ga4: number | null;
+        vercel: number | null;
+    }>;
+    /** Accessible description of what the two lines are. */
+    label?: string;
+}
+/**
+ * Daily GA4 against Vercel, with axes, dated ticks and a hover readout.
+ *
+ * The shaded band between the lines is the point of the chart rather than decoration: it IS the
+ * measurement gap, and seeing where it opens is what distinguishes an incident from a standing
+ * difference. Darden's opened overnight on 2026-08-24 and stayed open for over a week, which no
+ * scalar on this panel could have shown.
+ *
+ * Inline SVG with no charting library — one dependency-free element in a Studio that already loads
+ * a great deal, and it renders on the server so the tests can assert on it. Strokes use
+ * currentColor so the whole thing follows the Studio's theme without a palette of its own.
+ */
+declare function TrendChart({ points, label }: TrendChartProps): React.ReactElement | null;
+/** One column of a sortable table. */
+interface SortColumn<Row> {
+    /** Stable key, also used as the sort key. */
+    key: string;
+    label: string;
+    /** Right-aligned and sorted high-to-low first, the way a reader expects of a figure. */
+    numeric?: boolean;
+    /**
+     * Value to sort on. Return null for "no value" — those always sort last regardless of
+     * direction, because an unmeasured row is not a small one and must not lead an ascending sort.
+     */
+    sortValue: (row: Row) => number | string | null;
+    /**
+     * Value written to the CSV, when it differs from the sort key.
+     *
+     * Defaults to `sortValue`, which is right for a plain count and wrong for anything formatted:
+     * a rate sorts on 0.4318 and displays 43%, revenue sorts on a bare number and displays a
+     * currency, and a column with a fallback displays something `sortValue` returns null for.
+     */
+    exportValue?: (row: Row) => number | string | null;
+    render: (row: Row) => React.ReactNode;
+}
+/** Props for SortableTable. */
+interface SortableTableProps<Row> {
+    caption: string;
+    columns: Array<SortColumn<Row>>;
+    rows: Row[];
+    rowKey: (row: Row) => string;
+    /** Column sorted on first load. Defaults to the server's own ordering. */
+    initialSort?: string;
+    /**
+     * The text a row is matched against when filtering. Omit to render no filter box.
+     *
+     * Sorting was the tool's entire interaction budget, which meant a reader who spotted an
+     * unrelated site's traffic in the table had no way to take it out and see what was left.
+     */
+    filterOn?: (row: Row) => string;
+    /** Placeholder for the filter box, naming what is searched. */
+    filterPlaceholder?: string;
+    /** Base filename for the CSV export. Omit to render no export control. */
+    exportName?: string;
+    /** Shown under the table when the server truncated the row set. */
+    truncatedNote?: string;
+}
+/**
+ * A table whose columns sort.
+ *
+ * Both data tables arrived in one server-chosen order — sessions descending, views descending — so
+ * the only question they could answer was the one that order encoded. Sorting by any column turns
+ * the same rows into several different questions: which family is tested most relative to views,
+ * which source is least attributed, which typeface sells without being looked at.
+ *
+ * Rows with no value for the active column sort last in both directions. That is deliberate: an
+ * 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;
 
 /**
  * The four report panels.
@@ -163,8 +305,9 @@ declare function NoticeList({ notices }: NoticeListProps): React.ReactElement |
  * Compares pageviews to pageviews. Sessions and orders sit alongside as context and are never
  * subtracted from a pageview count.
  */
-declare function MeasurementHealthPanel({ data }: {
+declare function MeasurementHealthPanel({ data, previous }: {
     data: MeasurementHealthData;
+    previous?: MeasurementHealthData;
 }): React.ReactElement;
 /** Acquisition — where visitors came from, with design-industry referrers called out. */
 declare function AcquisitionPanel({ data, previous }: {
@@ -232,4 +375,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-export { AcquisitionPanel, ComparisonBar, DiagnosticsPanel, JourneyPanel, MeasurementHealthPanel, MetricFigure, MetricValue, NoticeList, RangeKey, ReportEnvelope, ReportName, type ReportState, TypefaceInterestPanel, type UseReportOptions, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, visitorInsights as default, formatCount, formatPercent, useReport, visitorInsights };
+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 };