@liiift-studio/sanity-visitor-insights 0.47.0 → 0.49.0

package/dist/index.d.mts

@@ -363,6 +363,13 @@ interface SortColumn<Row> {
      * currency, and a column with a fallback displays something `sortValue` returns null for.
      */
     exportValue?: (row: Row) => number | string | null;
+    /**
+     * Keep this column even when every value in it is blank or zero.
+     *
+     * For the column that identifies the row — a table whose first column collapsed would be a list
+     * of numbers belonging to nothing — and for any column whose emptiness is itself the finding.
+     */
+    alwaysShow?: boolean;
     render: (row: Row) => React.ReactNode;
 }
 /** Props for SortableTable. */
@@ -403,6 +410,34 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * The series palette, and the rules that keep it honest.
+ *
+ * Every chart in this package was drawn in `currentColor` at varying alpha, so five series on one
+ * chart were five greys separated by dash pattern alone. That is legible in a screenshot and not
+ * in use: a reader tracking co-movement between GA4 and Vercel had to keep which-line-is-which in
+ * their head while looking at the shape.
+ *
+ * Three constraints decided these values, and all three are enforced by tests rather than asserted
+ * here:
+ *
+ * 1. ONE SET FOR BOTH THEMES. The Studio ships light and dark and this component is not told which
+ *    it is in. Rather than swap palettes at a breakpoint we cannot observe, every colour clears
+ *    3:1 — the WCAG floor for a graphical object — against BOTH a white card and Sanity's dark
+ *    card. That is what pins them to mid-lightness.
+ *
+ * 2. HUE FAMILY MEANS SOURCE. The two GA4 series are deliberately neighbours in the warm range,
+ *    because they are the same instrument measuring two things; Vercel, orders and revenue each
+ *    get their own family. So the palette carries a fact rather than just distinguishing rows.
+ *
+ * 3. COLOUR IS NEVER THE ONLY CHANNEL. Completeness stays encoded as a dash pattern and every
+ *    value stays readable in the tooltip. The two GA4 hues are close enough to converge for a
+ *    deuteranope — which is acceptable precisely because dash and label still separate them, and
+ *    unacceptable for any pair that does not have that second channel.
+ */
+/** One series colour. The key names what it measures, not what it looks like. */
+type SeriesKey = 'vercel' | 'ga4Pageviews' | 'ga4Sessions' | 'orders' | 'revenue';
+
 /**
  * One time axis, every source stacked against it.
  *
@@ -433,15 +468,6 @@ interface SeriesPoint {
 }
 /** 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;
@@ -449,6 +475,15 @@ interface Series {
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
     /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
+    /**
+     * Which series colour this row draws in.
+     *
+     * Optional, and falling back to the row's `source`, so a caller that adds a row gets a colour
+     * consistent with every other row from the same upstream rather than an uncoloured one. Set it
+     * explicitly only where the source does not decide the meaning — coverage is computed FROM GA4
+     * and Vercel and belongs to neither.
+     */
+    color?: SeriesKey;
     unit: SeriesUnit;
     /**
      * How the row is drawn. Defaults to `line`.
@@ -494,6 +529,8 @@ interface Series {
      */
     shortfall?: {
         label: string;
+        /** The lossier source's colour. Falls back to its `source`, as the row's own does. */
+        color?: SeriesKey;
         source: Series['source'];
         points: SeriesPoint[];
     };

package/dist/index.d.ts

@@ -363,6 +363,13 @@ interface SortColumn<Row> {
      * currency, and a column with a fallback displays something `sortValue` returns null for.
      */
     exportValue?: (row: Row) => number | string | null;
+    /**
+     * Keep this column even when every value in it is blank or zero.
+     *
+     * For the column that identifies the row — a table whose first column collapsed would be a list
+     * of numbers belonging to nothing — and for any column whose emptiness is itself the finding.
+     */
+    alwaysShow?: boolean;
     render: (row: Row) => React.ReactNode;
 }
 /** Props for SortableTable. */
@@ -403,6 +410,34 @@ interface SortableTableProps<Row> {
  */
 declare function SortableTable<Row>({ caption, columns, rows, rowKey, initialSort, filterPlaceholder, filterOn, exportName, truncatedNote, onExclude, }: SortableTableProps<Row>): React.ReactElement;
 
+/**
+ * The series palette, and the rules that keep it honest.
+ *
+ * Every chart in this package was drawn in `currentColor` at varying alpha, so five series on one
+ * chart were five greys separated by dash pattern alone. That is legible in a screenshot and not
+ * in use: a reader tracking co-movement between GA4 and Vercel had to keep which-line-is-which in
+ * their head while looking at the shape.
+ *
+ * Three constraints decided these values, and all three are enforced by tests rather than asserted
+ * here:
+ *
+ * 1. ONE SET FOR BOTH THEMES. The Studio ships light and dark and this component is not told which
+ *    it is in. Rather than swap palettes at a breakpoint we cannot observe, every colour clears
+ *    3:1 — the WCAG floor for a graphical object — against BOTH a white card and Sanity's dark
+ *    card. That is what pins them to mid-lightness.
+ *
+ * 2. HUE FAMILY MEANS SOURCE. The two GA4 series are deliberately neighbours in the warm range,
+ *    because they are the same instrument measuring two things; Vercel, orders and revenue each
+ *    get their own family. So the palette carries a fact rather than just distinguishing rows.
+ *
+ * 3. COLOUR IS NEVER THE ONLY CHANNEL. Completeness stays encoded as a dash pattern and every
+ *    value stays readable in the tooltip. The two GA4 hues are close enough to converge for a
+ *    deuteranope — which is acceptable precisely because dash and label still separate them, and
+ *    unacceptable for any pair that does not have that second channel.
+ */
+/** One series colour. The key names what it measures, not what it looks like. */
+type SeriesKey = 'vercel' | 'ga4Pageviews' | 'ga4Sessions' | 'orders' | 'revenue';
+
 /**
  * One time axis, every source stacked against it.
  *
@@ -433,15 +468,6 @@ interface SeriesPoint {
 }
 /** 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;
@@ -449,6 +475,15 @@ interface Series {
     source: 'GA4' | 'Vercel' | 'Sanity' | 'Mailchimp';
     /** Whether the line's source sees everything. Drives the stroke and the wording. */
     complete: boolean;
+    /**
+     * Which series colour this row draws in.
+     *
+     * Optional, and falling back to the row's `source`, so a caller that adds a row gets a colour
+     * consistent with every other row from the same upstream rather than an uncoloured one. Set it
+     * explicitly only where the source does not decide the meaning — coverage is computed FROM GA4
+     * and Vercel and belongs to neither.
+     */
+    color?: SeriesKey;
     unit: SeriesUnit;
     /**
      * How the row is drawn. Defaults to `line`.
@@ -494,6 +529,8 @@ interface Series {
      */
     shortfall?: {
         label: string;
+        /** The lossier source's colour. Falls back to its `source`, as the row's own does. */
+        color?: SeriesKey;
         source: Series['source'];
         points: SeriesPoint[];
     };