@liiift-studio/sanity-visitor-insights 0.28.0 → 0.30.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, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-D1A9JY7h.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-D1A9JY7h.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-B3BWyG3q.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-B3BWyG3q.mjs';
 
 /**
  * Data hook for the Studio panels.
@@ -100,6 +100,62 @@ interface VisitorInsightsToolComponentProps extends Partial<VisitorInsightsToolP
 }
 declare function VisitorInsightsTool(props: VisitorInsightsToolComponentProps): React.ReactElement;
 
+/**
+ * The tool's view, in the URL — so a finding can be sent to someone.
+ *
+ * Every piece of state here was component-local: tab, range, and the custom window. A Studio
+ * reload, a browser back, or an accidental navigation discarded the whole investigation, and
+ * "Acquisition, 24 August to 7 September" — the exact view in which someone notices the thing worth
+ * noticing — could not be handed to a colleague or returned to by the person who found it. There is
+ * a "Copy as CSV" in this tool precisely because sharing a finding is the real task; the view
+ * itself was the one thing that could not be shared.
+ *
+ * The HASH, not the path or the query. Sanity's own router owns the path, and writing to it would
+ * fight the Studio for control of navigation; the hash is unclaimed, survives a reload, is carried
+ * by a copied link, and is ignored by every server. The value is namespaced because other tools in
+ * the same Studio may want the same trick.
+ *
+ * Everything here is a pure string transformation, so it is testable without a DOM — which matters,
+ * because the alternative is a feature whose only proof is clicking around a deployed Studio.
+ */
+/** The part of the tool's state worth putting in a link. */
+interface ViewState {
+    /** Tab id, e.g. `overview`. */
+    tab?: string;
+    /** Range key, e.g. `week` or `custom`. */
+    range?: string;
+    /** Custom window start, ISO date. Only meaningful when `range` is `custom`. */
+    from?: string;
+    /** Custom window end, ISO date. */
+    to?: string;
+}
+/**
+ * Serialise a view to the hash fragment it should occupy.
+ *
+ * Returns an empty string for an empty view, so a default view leaves the URL clean rather than
+ * decorating it with state nobody set.
+ *
+ * @param view - the state to encode
+ */
+declare function encodeView(view: ViewState): string;
+/**
+ * Read a view out of a hash fragment.
+ *
+ * Every field is validated and an unrecognised one is dropped rather than defaulted, so a truncated
+ * or hand-edited link degrades to whatever it could parse instead of failing or, worse, silently
+ * requesting a window nobody chose.
+ *
+ * @param hash - `window.location.hash`, with or without its leading `#`
+ */
+declare function decodeView(hash: string): ViewState;
+/**
+ * Replace our fragment in a hash, preserving anyone else's.
+ *
+ * @param hash - the current hash
+ * @param view - the state to write
+ */
+declare function mergeIntoHash(hash: string, view: ViewState): string;
+
 /**
  * Shared renderers for metric values and comparison bars.
  *
@@ -426,6 +482,15 @@ interface Series {
      * event, on a date, of a size. Days with nothing draw nothing, which is the truth.
      */
     mark?: 'line' | 'events';
+    /**
+     * A fixed y domain, instead of scaling the row to its own peak.
+     *
+     * Small multiples normally scale each row to itself, which is right for quantities whose
+     * absolute size is not comparable between rows. It is wrong for a proportion: a coverage row
+     * auto-scaled to its own maximum would redraw 100% at whatever the best day happened to be, so
+     * a site running at a flat 20% would show a full-height line and read as healthy.
+     */
+    domain?: [number, number];
     points: SeriesPoint[];
     /**
      * What a lossier source saw of the same thing.
@@ -465,12 +530,6 @@ interface CrossSourceTimelineProps {
      */
     onBrush?: (start: string, end: string) => void;
 }
-/**
- * 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, onBrush }: CrossSourceTimelineProps): React.ReactElement | null;
 
 /**
@@ -579,4 +638,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-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, knownShortfall, 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 ViewState, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, decodeView, visitorInsights as default, encodeView, formatCount, formatMoney, formatPercent, knownShortfall, mergeIntoHash, 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, c as MeasurementHealthData, D as DiagnosticReport, J as JourneyData, T as TypefaceInterestData } from './ranges-D1A9JY7h.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-D1A9JY7h.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-B3BWyG3q.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-B3BWyG3q.js';
 
 /**
  * Data hook for the Studio panels.
@@ -100,6 +100,62 @@ interface VisitorInsightsToolComponentProps extends Partial<VisitorInsightsToolP
 }
 declare function VisitorInsightsTool(props: VisitorInsightsToolComponentProps): React.ReactElement;
 
+/**
+ * The tool's view, in the URL — so a finding can be sent to someone.
+ *
+ * Every piece of state here was component-local: tab, range, and the custom window. A Studio
+ * reload, a browser back, or an accidental navigation discarded the whole investigation, and
+ * "Acquisition, 24 August to 7 September" — the exact view in which someone notices the thing worth
+ * noticing — could not be handed to a colleague or returned to by the person who found it. There is
+ * a "Copy as CSV" in this tool precisely because sharing a finding is the real task; the view
+ * itself was the one thing that could not be shared.
+ *
+ * The HASH, not the path or the query. Sanity's own router owns the path, and writing to it would
+ * fight the Studio for control of navigation; the hash is unclaimed, survives a reload, is carried
+ * by a copied link, and is ignored by every server. The value is namespaced because other tools in
+ * the same Studio may want the same trick.
+ *
+ * Everything here is a pure string transformation, so it is testable without a DOM — which matters,
+ * because the alternative is a feature whose only proof is clicking around a deployed Studio.
+ */
+/** The part of the tool's state worth putting in a link. */
+interface ViewState {
+    /** Tab id, e.g. `overview`. */
+    tab?: string;
+    /** Range key, e.g. `week` or `custom`. */
+    range?: string;
+    /** Custom window start, ISO date. Only meaningful when `range` is `custom`. */
+    from?: string;
+    /** Custom window end, ISO date. */
+    to?: string;
+}
+/**
+ * Serialise a view to the hash fragment it should occupy.
+ *
+ * Returns an empty string for an empty view, so a default view leaves the URL clean rather than
+ * decorating it with state nobody set.
+ *
+ * @param view - the state to encode
+ */
+declare function encodeView(view: ViewState): string;
+/**
+ * Read a view out of a hash fragment.
+ *
+ * Every field is validated and an unrecognised one is dropped rather than defaulted, so a truncated
+ * or hand-edited link degrades to whatever it could parse instead of failing or, worse, silently
+ * requesting a window nobody chose.
+ *
+ * @param hash - `window.location.hash`, with or without its leading `#`
+ */
+declare function decodeView(hash: string): ViewState;
+/**
+ * Replace our fragment in a hash, preserving anyone else's.
+ *
+ * @param hash - the current hash
+ * @param view - the state to write
+ */
+declare function mergeIntoHash(hash: string, view: ViewState): string;
+
 /**
  * Shared renderers for metric values and comparison bars.
  *
@@ -426,6 +482,15 @@ interface Series {
      * event, on a date, of a size. Days with nothing draw nothing, which is the truth.
      */
     mark?: 'line' | 'events';
+    /**
+     * A fixed y domain, instead of scaling the row to its own peak.
+     *
+     * Small multiples normally scale each row to itself, which is right for quantities whose
+     * absolute size is not comparable between rows. It is wrong for a proportion: a coverage row
+     * auto-scaled to its own maximum would redraw 100% at whatever the best day happened to be, so
+     * a site running at a flat 20% would show a full-height line and read as healthy.
+     */
+    domain?: [number, number];
     points: SeriesPoint[];
     /**
      * What a lossier source saw of the same thing.
@@ -465,12 +530,6 @@ interface CrossSourceTimelineProps {
      */
     onBrush?: (start: string, end: string) => void;
 }
-/**
- * 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, onBrush }: CrossSourceTimelineProps): React.ReactElement | null;
 
 /**
@@ -579,4 +638,4 @@ interface VisitorInsightsPluginOptions {
  */
 declare const visitorInsights: sanity.Plugin<VisitorInsightsPluginOptions>;
 
-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, knownShortfall, 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 ViewState, type VisitorInsightsPluginOptions, VisitorInsightsTool, type VisitorInsightsToolProps, decodeView, visitorInsights as default, encodeView, formatCount, formatMoney, formatPercent, knownShortfall, mergeIntoHash, useReport, visitorInsights };