@liiift-studio/sanity-visitor-insights 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liiift-studio/sanity-visitor-insights",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Visitor-behaviour analytics for type-foundry Sanity Studios \u2014 GA4, Vercel and order data reconciled honestly",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/core/core.test.ts

@@ -237,3 +237,20 @@ describe('validateSiteConfig', () => {
 		expect(validateSiteConfig({}).length).toBeGreaterThan(1)
 	})
 })
+
+describe('vercel granularity', () => {
+	it('picks a granularity the API will actually accept', async () => {
+		const { granularityFor } = await import('../server/vercel')
+		// Limits measured against the live API: day caps at 62 days, week at 26 weeks. Exceeding
+		// either is a 400, not a truncated series, so the year view fails outright if this is wrong.
+		expect(granularityFor('2026-08-01', '2026-08-30')).toBe('day')
+		expect(granularityFor('2026-07-01', '2026-08-31')).toBe('day')
+		expect(granularityFor('2026-06-01', '2026-08-30')).toBe('week')
+		// Exact boundaries: 62 days is still day, 63 is not; 182 days is still week, 183 is not.
+		expect(granularityFor('2026-01-01', '2026-03-03')).toBe('day')
+		expect(granularityFor('2026-01-01', '2026-03-04')).toBe('week')
+		expect(granularityFor('2026-01-01', '2026-07-01')).toBe('week')
+		expect(granularityFor('2026-01-01', '2026-07-02')).toBe('month')
+		expect(granularityFor('2025-08-30', '2026-08-30')).toBe('month')
+	})
+})

package/src/server/vercel.ts

@@ -28,6 +28,22 @@ export interface VercelClient {
 	pageviews(start: string, end: string): Promise<VercelPageviews>
 }
 
+/**
+ * Pick a time granularity the aggregate endpoint will accept.
+ *
+ * It rejects any grouping that would return more than 62 buckets — a quarter or a year grouped by
+ * day is a 400, not an empty result. Stepping the granularity up keeps long ranges working instead
+ * of failing outright, which is what the year view needs.
+ */
+export function granularityFor(start: string, end: string): 'day' | 'week' | 'month' {
+	const days = Math.round((Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000) + 1
+	// Measured against the live API: day is capped at 62 days, week at 26 weeks. Both limits are
+	// on buckets returned, and exceeding either is a 400 rather than a truncated result.
+	if (days <= 62) return 'day'
+	if (days <= 26 * 7) return 'week'
+	return 'month'
+}
+
 /** Shape of the aggregate response rows. */
 interface AggregateRow {
 	timestamp?: string
@@ -65,6 +81,7 @@ export function createVercelClient(projectId: string, token: string, teamId?: st
 			// Two calls on purpose. The count endpoint gives range totals with visitors deduped
 			// across the whole window; summing the daily rows would overcount visitors, because a
 			// person returning on three days is three daily visitors but one range visitor.
+			// It also has no range limit, unlike the aggregate below.
 			const [totals, series] = await Promise.all([
 				query<{ data?: { pageviews?: number; visitors?: number } }>('visits/count', {
 					since: start,
@@ -73,8 +90,13 @@ export function createVercelClient(projectId: string, token: string, teamId?: st
 				query<{ data?: AggregateRow[] }>('visits/aggregate', {
 					since: start,
 					until: end,
-					by: 'day',
+					by: granularityFor(start, end),
 					limit: '100',
+				}).catch((e: Error) => {
+					// The series is supplementary — it feeds sparklines, not the headline figure.
+					// Losing it must not cost the totals, which is what the panel actually compares.
+					console.error('Visitor insights: Vercel series unavailable:', e.message)
+					return { data: [] as AggregateRow[] }
 				}),
 			])
 

package/src/studio/Figure.tsx

@@ -10,7 +10,7 @@
  */
 
 import React from 'react'
-import { Badge, Box, Flex, Stack, Text, Tooltip } from '@liiift-studio/sanity-ui-compat'
+import { Badge, Box, Card, Flex, Stack, Text, Tooltip } from '@liiift-studio/sanity-ui-compat'
 import type { MetricValue, UnavailableReason } from '../types'
 
 /** Human-readable explanation for each unavailable reason. */
@@ -109,39 +109,19 @@ export function ComparisonBar({ label, metric, max, tone = 'default' }: Comparis
 
 			{value === null ? (
 				// A dashed rail, not a zero-width bar: absence must not read as a measured zero.
-				<Box
+				<Card
 					aria-hidden="true"
-					style={{
-						height: 8,
-						borderRadius: 4,
-						border: '1px dashed var(--card-border-color)',
-					}}
+					radius={2}
+					tone="transparent"
+					border
+					style={{ height: 8, borderStyle: 'dashed' }}
 				/>
 			) : (
-				<Box
-					aria-hidden="true"
-					style={{
-						height: 8,
-						borderRadius: 4,
-						background: 'var(--card-border-color)',
-						overflow: 'hidden',
-					}}
-				>
-					<Box
-						style={{
-							width: `${width}%`,
-							height: '100%',
-							background:
-								tone === 'primary'
-									? 'var(--card-focus-ring-color)'
-									: tone === 'positive'
-										? 'var(--card-badge-positive-dot-color, var(--card-focus-ring-color))'
-										: tone === 'caution'
-											? 'var(--card-badge-caution-dot-color, var(--card-muted-fg-color))'
-											: 'var(--card-muted-fg-color)',
-						}}
-					/>
-				</Box>
+				// Track and fill are both Cards so the palette comes from the Studio theme tokens
+				// rather than hand-picked CSS variables, and follows light/dark without extra work.
+				<Card aria-hidden="true" radius={2} tone="transparent" border style={{ height: 8, overflow: 'hidden' }}>
+					<Card tone={tone === 'default' ? 'default' : tone} radius={2} style={{ width: `${width}%`, height: '100%' }} />
+				</Card>
 			)}
 		</Stack>
 	)
@@ -165,10 +145,12 @@ export function NoticeList({ notices }: NoticeListProps): React.ReactElement | n
 		<ul style={{ listStyle: 'none', margin: 0, padding: 0, display: 'grid', gap: 8 }}>
 			{notices.map((notice) => (
 				<li key={notice}>
-					<Flex gap={2} align="flex-start">
-						<Text size={1} muted aria-hidden="true">⚠</Text>
-						<Text size={1} muted>{notice}</Text>
-					</Flex>
+					<Card padding={3} radius={2} tone="caution" border>
+						<Flex gap={3} align="flex-start">
+							<Badge tone="caution" fontSize={0}>Caveat</Badge>
+							<Text size={1}>{notice}</Text>
+						</Flex>
+					</Card>
 				</li>
 			))}
 		</ul>

package/src/studio/panels.tsx

@@ -7,7 +7,7 @@
  */
 
 import React from 'react'
-import { Box, Card, Flex, Heading, Stack, Text } from '@liiift-studio/sanity-ui-compat'
+import { Badge, Box, Card, Flex, Grid, Heading, Label, Stack, Text } from '@liiift-studio/sanity-ui-compat'
 import { ComparisonBar, MetricFigure, NoticeList, formatCount, formatPercent } from './Figure'
 import type {
 	AcquisitionData,
@@ -28,6 +28,8 @@ function maxOf(metrics: MetricValue[]): number {
 const tableWrap: React.CSSProperties = { overflowX: 'auto', width: '100%' }
 const table: React.CSSProperties = { width: '100%', borderCollapse: 'collapse', minWidth: 420 }
 const cell: React.CSSProperties = { padding: '8px 12px', textAlign: 'left', borderBottom: '1px solid var(--card-border-color)' }
+// @sanity/ui ships no Table primitive, so the element is native — but every cell's content is a
+// Sanity UI component, and the table sits inside a Card, so it themes with the rest of the Studio.
 const numericCell: React.CSSProperties = { ...cell, textAlign: 'right' }
 
 /**
@@ -66,20 +68,26 @@ export function MeasurementHealthPanel({ data }: { data: MeasurementHealthData }
 				<Text size={1} muted>
 					Different units to the figures above, and to each other. Shown for scale, never differenced.
 				</Text>
-				<Flex gap={4} wrap="wrap">
-					<Stack space={2}>
-						<Text size={1} muted>GA4 sessions</Text>
-						<MetricFigure metric={data.ga4Sessions} label="GA4 sessions" />
-					</Stack>
-					<Stack space={2}>
-						<Text size={1} muted>Orders</Text>
-						<MetricFigure metric={data.orders} label="Orders" />
-					</Stack>
-					<Stack space={2}>
-						<Text size={1} muted>Consent granted</Text>
-						<MetricFigure metric={data.consentRate} label="Consent granted, percent of sessions" />
-					</Stack>
-				</Flex>
+				<Grid columns={[1, 3]} gap={4}>
+					<Card padding={3} radius={2} tone="transparent" border>
+						<Stack space={3}>
+							<Label size={1} muted>GA4 sessions</Label>
+							<MetricFigure metric={data.ga4Sessions} label="GA4 sessions" />
+						</Stack>
+					</Card>
+					<Card padding={3} radius={2} tone="transparent" border>
+						<Stack space={3}>
+							<Label size={1} muted>Orders</Label>
+							<MetricFigure metric={data.orders} label="Orders" />
+						</Stack>
+					</Card>
+					<Card padding={3} radius={2} tone="transparent" border>
+						<Stack space={3}>
+							<Label size={1} muted>Consent granted</Label>
+							<MetricFigure metric={data.consentRate} label="Consent granted, percent of sessions" />
+						</Stack>
+					</Card>
+				</Grid>
 			</Stack>
 		</Stack>
 	)
@@ -89,35 +97,41 @@ export function MeasurementHealthPanel({ data }: { data: MeasurementHealthData }
 export function AcquisitionPanel({ data }: { data: AcquisitionData }): React.ReactElement {
 	return (
 		<Stack space={4}>
-			<Flex gap={4} wrap="wrap">
-				<Stack space={2}>
-					<Text size={1} muted>Sessions</Text>
-					<Text size={4}>{formatCount(data.totalSessions)}</Text>
-				</Stack>
-				{data.designIndustryShare !== null && (
-					<Stack space={2}>
-						<Text size={1} muted>From design-industry referrers</Text>
-						<Text size={4}>{formatPercent(data.designIndustryShare, 1)}</Text>
+			<Grid columns={[1, 3]} gap={4}>
+				<Card padding={3} radius={2} tone="transparent" border>
+					<Stack space={3}>
+						<Label size={1} muted>Sessions</Label>
+						<Text size={4}>{formatCount(data.totalSessions)}</Text>
 					</Stack>
+				</Card>
+				{data.designIndustryShare !== null && (
+					<Card padding={3} radius={2} tone="transparent" border>
+						<Stack space={3}>
+							<Label size={1} muted>From design-industry referrers</Label>
+							<Text size={4}>{formatPercent(data.designIndustryShare, 1)}</Text>
+						</Stack>
+					</Card>
 				)}
 				{data.unattributedShare !== null && (
-					<Stack space={2}>
-						<Text size={1} muted>Unattributed</Text>
-						<Text size={4}>{formatPercent(data.unattributedShare, 1)}</Text>
-					</Stack>
+					<Card padding={3} radius={2} tone="transparent" border>
+						<Stack space={3}>
+							<Label size={1} muted>Unattributed</Label>
+							<Text size={4}>{formatPercent(data.unattributedShare, 1)}</Text>
+						</Stack>
+					</Card>
 				)}
-			</Flex>
+			</Grid>
 
-			<Box style={tableWrap}>
+			<Card radius={2} tone="transparent" border style={tableWrap}>
 				<table style={table}>
 					<caption style={{ textAlign: 'left', paddingBottom: 8 }}>
 						<Text size={1} muted>Traffic sources by sessions</Text>
 					</caption>
 					<thead>
 						<tr>
-							<th scope="col" style={cell}><Text size={1} weight="semibold">Source</Text></th>
-							<th scope="col" style={cell}><Text size={1} weight="semibold">Channel</Text></th>
-							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Sessions</Text></th>
+							<th scope="col" style={cell}><Label size={1} muted>Source</Label></th>
+							<th scope="col" style={cell}><Label size={1} muted>Channel</Label></th>
+							<th scope="col" style={numericCell}><Label size={1} muted>Sessions</Label></th>
 						</tr>
 					</thead>
 					<tbody>
@@ -126,8 +140,8 @@ export function AcquisitionPanel({ data }: { data: AcquisitionData }): React.Rea
 								<th scope="row" style={cell}>
 									<Flex gap={2} align="center">
 										<Text size={1}>{row.source}</Text>
-										{row.designIndustry && <Text size={0} muted>· design industry</Text>}
-										{row.unattributed && <Text size={0} muted>· unattributed</Text>}
+										{row.designIndustry && <Badge tone="primary" fontSize={0}>design industry</Badge>}
+										{row.unattributed && <Badge tone="caution" fontSize={0}>unattributed</Badge>}
 									</Flex>
 								</th>
 								<td style={cell}><Text size={1} muted>{row.channel}</Text></td>
@@ -136,7 +150,7 @@ export function AcquisitionPanel({ data }: { data: AcquisitionData }): React.Rea
 						))}
 					</tbody>
 				</table>
-			</Box>
+			</Card>
 
 			{data.rowsWithheld && (
 				<NoticeList notices={['GA4 withheld some low-traffic rows for privacy, so this list is shorter than reality.']} />
@@ -169,12 +183,12 @@ export function JourneyPanel({ data }: { data: JourneyData }): React.ReactElemen
 			{data.topExitPages.length > 0 && (
 				<Stack space={3}>
 					<Heading size={1}>Where sessions ended</Heading>
-					<Box style={tableWrap}>
+					<Card radius={2} tone="transparent" border style={tableWrap}>
 						<table style={table}>
 							<thead>
 								<tr>
-									<th scope="col" style={cell}><Text size={1} weight="semibold">Page</Text></th>
-									<th scope="col" style={numericCell}><Text size={1} weight="semibold">Exits</Text></th>
+									<th scope="col" style={cell}><Label size={1} muted>Page</Label></th>
+									<th scope="col" style={numericCell}><Label size={1} muted>Exits</Label></th>
 								</tr>
 							</thead>
 							<tbody>
@@ -186,7 +200,7 @@ export function JourneyPanel({ data }: { data: JourneyData }): React.ReactElemen
 								))}
 							</tbody>
 						</table>
-					</Box>
+					</Card>
 				</Stack>
 			)}
 		</Stack>
@@ -201,18 +215,18 @@ export function TypefaceInterestPanel({ data }: { data: TypefaceInterestData }):
 				<Text size={1} muted>{data.interpretationNote}</Text>
 			</Card>
 
-			<Box style={tableWrap}>
+			<Card radius={2} tone="transparent" border style={tableWrap}>
 				<table style={table}>
 					<caption style={{ textAlign: 'left', paddingBottom: 8 }}>
 						<Text size={1} muted>Engagement by typeface</Text>
 					</caption>
 					<thead>
 						<tr>
-							<th scope="col" style={cell}><Text size={1} weight="semibold">Typeface</Text></th>
-							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Viewed</Text></th>
-							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Tested</Text></th>
-							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Bought</Text></th>
-							<th scope="col" style={numericCell}><Text size={1} weight="semibold">Test rate</Text></th>
+							<th scope="col" style={cell}><Label size={1} muted>Typeface</Label></th>
+							<th scope="col" style={numericCell}><Label size={1} muted>Viewed</Label></th>
+							<th scope="col" style={numericCell}><Label size={1} muted>Tested</Label></th>
+							<th scope="col" style={numericCell}><Label size={1} muted>Bought</Label></th>
+							<th scope="col" style={numericCell}><Label size={1} muted>Test rate</Label></th>
 						</tr>
 					</thead>
 					<tbody>
@@ -229,7 +243,7 @@ export function TypefaceInterestPanel({ data }: { data: TypefaceInterestData }):
 						))}
 					</tbody>
 				</table>
-			</Box>
+			</Card>
 		</Stack>
 	)
 }
@@ -278,9 +292,7 @@ export function DiagnosticsPanel({ data }: { data: DiagnosticReport }): React.Re
 						<Stack space={3}>
 							<Flex align="center" justify="space-between" gap={3}>
 								<Text size={1} weight="semibold">{item.label}</Text>
-								<Card padding={2} radius={2} tone={CHECK_TONE[item.status]}>
-									<Text size={0} weight="medium">{CHECK_WORD[item.status]}</Text>
-								</Card>
+								<Badge tone={CHECK_TONE[item.status]} fontSize={0}>{CHECK_WORD[item.status]}</Badge>
 							</Flex>
 							<Text size={1} muted>{item.detail}</Text>
 							{item.remedy && <Text size={1}>{item.remedy}</Text>}