@growth-labs/cms 0.5.29 → 0.5.31

package/src/ui/screens/SurveyResponsesScreen.tsx

@@ -1,11 +1,18 @@
-import { useCallback, useEffect, useState } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import type { CmsRole } from '../../schema/types.js'
+import { canViewSurveyVerbatims } from '../../surveys/access.js'
 import {
 	isSurveyErrorCode,
 	SURVEY_ERROR_CODE_HEADER,
 	SURVEY_ERROR_DEFINITIONS,
 	type SurveyErrorCode,
 } from '../../surveys/errors.js'
-import { type SurveyResults, SurveyResultsSchema } from '../../surveys/schema.js'
+import {
+	type SurveyQuestion,
+	type SurveyResults,
+	SurveyResultsSchema,
+} from '../../surveys/schema.js'
+import { useWorkspace } from '../workspace-context.js'
 
 export type SurveyResponsesState =
 	| { kind: 'loading' }
@@ -14,6 +21,7 @@ export type SurveyResponsesState =
 	| { kind: 'unavailable' }
 	| { kind: 'malformed' }
 	| { kind: 'not_found' }
+	| { kind: 'auth_failed' }
 	| { kind: 'retryable' }
 
 export function parseSurveyResultsPayload(value: unknown): SurveyResults | null {
@@ -34,8 +42,10 @@ export async function classifySurveyResultsResponse(
 		return { kind: 'forbidden' }
 	}
 	if (response.status === 404 && code === 'survey_not_found') return { kind: 'not_found' }
-	if (response.status === 502 && code === 'survey_provider_malformed') {
-		return { kind: 'malformed' }
+	if (response.status === 502 && code === 'survey_provider_malformed') return { kind: 'malformed' }
+	if (response.status === 502 && code === 'survey_invalid_response') return { kind: 'malformed' }
+	if (response.status === 502 && code === 'survey_upstream_auth_failed') {
+		return { kind: 'auth_failed' }
 	}
 	if (response.status === 503 && code === 'survey_provider_unavailable') {
 		return { kind: 'unavailable' }
@@ -43,61 +53,104 @@ export async function classifySurveyResultsResponse(
 	return { kind: 'retryable' }
 }
 
+const PAGE_SIZE = 100
+
 export function SurveyResponsesScreen({ surveyId }: { surveyId: string }) {
 	const [state, setState] = useState<SurveyResponsesState>({ kind: 'loading' })
-	const load = useCallback(async () => {
-		setState({ kind: 'loading' })
-		try {
-			const response = await fetch(`/admin/api/surveys/${encodeURIComponent(surveyId)}`)
-			setState(await classifySurveyResultsResponse(response))
-		} catch {
-			setState({ kind: 'retryable' })
-		}
-	}, [surveyId])
+	const [offset, setOffset] = useState(0)
+	const load = useCallback(
+		async (nextOffset: number) => {
+			setState({ kind: 'loading' })
+			try {
+				const response = await fetch(
+					`/admin/api/surveys/${encodeURIComponent(surveyId)}?offset=${nextOffset}`,
+				)
+				setState(await classifySurveyResultsResponse(response))
+			} catch {
+				setState({ kind: 'retryable' })
+			}
+		},
+		[surveyId],
+	)
 
 	useEffect(() => {
-		void load()
-	}, [load])
+		void load(offset)
+	}, [load, offset])
+
+	const { state: workspace } = useWorkspace()
 
-	return <SurveyResponsesBody surveyId={surveyId} state={state} onRetry={load} />
+	return (
+		<SurveyResponsesBody
+			surveyId={surveyId}
+			state={state}
+			offset={offset}
+			role={workspace.user?.role ?? null}
+			onRetry={() => void load(offset)}
+			onOffsetChange={setOffset}
+		/>
+	)
 }
 
 export function SurveyResponsesBody({
 	surveyId,
 	state,
+	offset = 0,
+	role = null,
 	onRetry,
+	onOffsetChange,
 }: {
 	surveyId: string
 	state: SurveyResponsesState
+	offset?: number
+	role?: CmsRole | null
 	onRetry?: () => void
+	onOffsetChange?: (offset: number) => void
 }) {
+	const canSeeVerbatims = canViewSurveyVerbatims(role)
+
 	if (state.kind === 'loading') return <StatusPage title="Loading survey responses…" />
 	if (state.kind === 'forbidden')
 		return <StatusPage title="You do not have permission to view survey responses." />
 	if (state.kind === 'unavailable')
 		return <StatusPage title="Survey reporting is not configured for this site." />
+	if (state.kind === 'auth_failed')
+		return (
+			<StatusPage
+				title="Survey reporting rejected this site’s credentials."
+				detail="The signing secret shared with the reporting upstream is missing or does not match."
+				retry={onRetry}
+			/>
+		)
 	if (state.kind === 'malformed')
 		return <StatusPage title="Masthead received invalid survey data." retry={onRetry} />
 	if (state.kind === 'not_found')
 		return <StatusPage title="The configured survey could not be found." />
 	if (state.kind === 'retryable')
-		return <StatusPage title="Survey responses could not be loaded." retry={onRetry} />
+		return (
+			<StatusPage
+				title="Survey responses could not be loaded."
+				detail="The request did not reach the reporting upstream, or it failed before replying."
+				retry={onRetry}
+			/>
+		)
 
 	const { data } = state
-	const freeTextByQuestion = new Map<string, SurveyResults['freeText']>()
-	for (const entry of data.freeText) {
-		const entries = freeTextByQuestion.get(entry.questionId) ?? []
-		entries.push(entry)
-		freeTextByQuestion.set(entry.questionId, entries)
-	}
+	const shown = data.responses.length
+	const total = data.survey.responseCount
+	const rangeStart = total === 0 ? 0 : offset + 1
+	const rangeEnd = offset + shown
+	const hasMore = rangeEnd < total
 
 	return (
 		<div className="page page-wide fade-in" style={{ maxWidth: 1340 }}>
 			<div className="page-head">
 				<div>
 					<h1 className="page-title">{data.survey.title}</h1>
+					{/* Never a truncated list under a full count: say exactly what is on screen. */}
 					<div className="page-sub">
-						{data.survey.responseCount} {data.survey.responseCount === 1 ? 'response' : 'responses'}{' '}
+						{total === 0
+							? 'No responses yet'
+							: `Showing ${rangeStart}–${rangeEnd} of ${total} ${total === 1 ? 'response' : 'responses'}`}{' '}
 						· {data.survey.status}
 					</div>
 				</div>
@@ -109,92 +162,271 @@ export function SurveyResponsesBody({
 				</a>
 			</div>
 
-			{data.survey.responseCount === 0 ? (
+			{total === 0 ? (
 				<div className="card" role="status">
 					<h2 className="card-title">No responses yet</h2>
-					<p className="page-sub">Aggregates and free-text answers will appear after submission.</p>
+					<p className="page-sub">Aggregates and answers will appear after submission.</p>
 				</div>
 			) : (
-				<section className="card" aria-labelledby="survey-response-list">
-					<h2 className="card-title" id="survey-response-list">
-						Recent responses
-					</h2>
-					<div className="masthead-rule" />
-					<table className="tbl">
-						<thead>
-							<tr>
-								<th>Submitted</th>
-								<th>Channel</th>
-								<th>Audience</th>
-								<th>Attribution</th>
-							</tr>
-						</thead>
-						<tbody>
-							{data.responses.map((response) => (
-								<tr key={response.id}>
-									<td>
-										<time dateTime={response.submittedAt}>{formatTime(response.submittedAt)}</time>
-									</td>
-									<td>{response.channel}</td>
-									<td>{segmentLabel(response.respondentSegment)}</td>
-									<td>{response.anonymous ? 'Anonymous' : 'Known respondent'}</td>
-								</tr>
-							))}
-						</tbody>
-					</table>
-				</section>
+				<>
+					<HeadlineScale questions={data.questions} />
+
+					{canSeeVerbatims ? (
+						<VerbatimFeed data={data} />
+					) : (
+						<div className="card" role="status" style={{ marginTop: 24 }}>
+							<h2 className="card-title">Individual answers are restricted</h2>
+							<p className="page-sub">
+								Aggregates below are available to your role. Verbatim answers and respondent
+								attribution require owner or senior editor.
+							</p>
+						</div>
+					)}
+
+					<Aggregates data={data} />
+
+					{(offset > 0 || hasMore) && onOffsetChange ? (
+						<div className="page-head" style={{ marginTop: 24 }}>
+							<button
+								className="btn"
+								type="button"
+								disabled={offset === 0}
+								onClick={() => onOffsetChange(Math.max(offset - PAGE_SIZE, 0))}
+							>
+								Previous
+							</button>
+							<button
+								className="btn"
+								type="button"
+								disabled={!hasMore}
+								onClick={() => onOffsetChange(offset + PAGE_SIZE)}
+							>
+								Next
+							</button>
+						</div>
+					) : null}
+				</>
 			)}
+		</div>
+	)
+}
 
-			<section aria-labelledby="survey-aggregates" style={{ marginTop: 24 }}>
-				<h2 className="page-title" id="survey-aggregates" style={{ fontSize: 22 }}>
-					Question aggregates
-				</h2>
-				<div className="grid-split-wide" style={{ alignItems: 'start', marginTop: 12 }}>
-					{data.questions.map((question) => (
-						<article className="card" key={question.id}>
+// The first scale question is the survey's headline number. Leading with the
+// distribution keeps one harsh verbatim from setting the tone of a readout.
+function HeadlineScale({ questions }: { questions: SurveyResults['questions'] }) {
+	const scale = questions.find((question) => question.kind === 'scale')
+	if (!scale || scale.kind !== 'scale' || scale.answerCount === 0) return null
+	const midpoint = (scale.options.min + scale.options.max) / 2
+	const favourable = Object.entries(scale.distribution)
+		.filter(([value]) => Number(value) > midpoint)
+		.reduce((sum, [, count]) => sum + count, 0)
+	const share = Math.round((favourable / scale.answerCount) * 100)
+
+	return (
+		<section className="card" aria-labelledby="survey-headline" style={{ marginTop: 24 }}>
+			<div className="kicker">{scale.prompt}</div>
+			<h2 className="card-title" id="survey-headline">
+				{share}% rate {midpoint.toFixed(1)} or better · average{' '}
+				{scale.average === null ? '—' : scale.average.toFixed(2)}
+			</h2>
+			<CountTable values={scale.distribution} />
+		</section>
+	)
+}
+
+function VerbatimFeed({ data }: { data: SurveyResults }) {
+	const textQuestionIds = new Set(
+		data.questions.filter((question) => question.kind === 'text').map((question) => question.id),
+	)
+	const promptById = new Map(data.questions.map((question) => [question.id, question.prompt]))
+	const freeTextByResponse = new Map<string, string[]>()
+	for (const entry of data.freeText) {
+		const entries = freeTextByResponse.get(entry.responseId) ?? []
+		entries.push(entry.value)
+		freeTextByResponse.set(entry.responseId, entries)
+	}
+
+	return (
+		<section aria-labelledby="survey-verbatims" style={{ marginTop: 24 }}>
+			<h2 className="page-title" id="survey-verbatims" style={{ fontSize: 22 }}>
+				Responses
+			</h2>
+			<div style={{ marginTop: 12 }}>
+				{data.responses.map((response) => {
+					const written = freeTextByResponse.get(response.id) ?? []
+					const choices = (response.answers ?? []).filter(
+						(answer) => !textQuestionIds.has(answer.questionId),
+					)
+					return (
+						<article className="card" key={response.id} style={{ marginTop: 12 }}>
 							<div className="kicker">
-								Q{question.position + 1} · {questionAudienceLabel(question.audience)}
+								<time dateTime={response.submittedAt}>{formatTime(response.submittedAt)}</time> ·{' '}
+								{segmentLabel(response.respondentSegment)} · {respondentLabel(response)}
 							</div>
-							<h3 className="card-title">{question.prompt}</h3>
-							{question.counts && <CountTable values={question.counts} />}
-							{question.distribution && (
-								<>
-									<p className="page-sub">
-										Average: {question.average === null ? '—' : question.average.toFixed(2)}
-									</p>
-									<CountTable values={question.distribution} />
-								</>
-							)}
-							{question.kind === 'text' && (
-								<p className="page-sub">{question.responseCount ?? 0} free-text responses</p>
+							{written.length === 0 ? (
+								<p className="page-sub">No written answer.</p>
+							) : (
+								written.map((value, index) => (
+									// biome-ignore lint/suspicious/noArrayIndexKey: values are free text with no stable id
+									<blockquote key={`${response.id}:${index}`}>{value}</blockquote>
+								))
 							)}
+							<div className="chip-row">
+								{choices.map((answer) => (
+									<span
+										className="chip"
+										key={`${response.id}:${answer.questionId}`}
+										title={promptById.get(answer.questionId) ?? answer.questionId}
+									>
+										{formatAnswerValue(answer.value)}
+									</span>
+								))}
+							</div>
 						</article>
-					))}
-				</div>
-			</section>
+					)
+				})}
+			</div>
+		</section>
+	)
+}
+
+function Aggregates({ data }: { data: SurveyResults }) {
+	// Flat counts cannot express the finding that matters most — how one cohort
+	// differs from another — so every aggregate can be split by another question.
+	const splitCandidates = data.questions.filter(
+		(question) => question.kind === 'single_choice' || question.kind === 'scale',
+	)
+	const [splitBy, setSplitBy] = useState<string>('')
+	const splitQuestion = splitCandidates.find((question) => question.id === splitBy)
 
-			<section aria-labelledby="survey-free-text" style={{ marginTop: 24 }}>
-				<h2 className="page-title" id="survey-free-text" style={{ fontSize: 22 }}>
-					Free-text responses
+	const answersByResponse = useMemo(() => {
+		const map = new Map<string, Map<string, unknown>>()
+		for (const response of data.responses) {
+			map.set(
+				response.id,
+				new Map((response.answers ?? []).map((answer) => [answer.questionId, answer.value])),
+			)
+		}
+		return map
+	}, [data.responses])
+
+	const cohorts = useMemo(() => {
+		if (!splitQuestion) return null
+		const buckets = new Map<string, string[]>()
+		for (const response of data.responses) {
+			const value = answersByResponse.get(response.id)?.get(splitQuestion.id)
+			if (value === undefined) continue
+			const key = formatAnswerValue(value)
+			const ids = buckets.get(key) ?? []
+			ids.push(response.id)
+			buckets.set(key, ids)
+		}
+		return buckets
+	}, [answersByResponse, data.responses, splitQuestion])
+
+	return (
+		<section aria-labelledby="survey-aggregates" style={{ marginTop: 24 }}>
+			<div className="page-head">
+				<h2 className="page-title" id="survey-aggregates" style={{ fontSize: 22 }}>
+					Question aggregates
 				</h2>
-				{data.questions
-					.filter((question) => question.kind === 'text')
-					.map((question) => (
-						<div className="card" key={question.id} style={{ marginTop: 12 }}>
-							<h3 className="card-title">{question.prompt}</h3>
-							{(freeTextByQuestion.get(question.id) ?? []).length === 0 ? (
-								<p className="page-sub">No free-text responses.</p>
-							) : (
-								<ul>
-									{(freeTextByQuestion.get(question.id) ?? []).map((entry) => (
-										<li key={`${entry.responseId}:${entry.submittedAt}`}>{entry.value}</li>
-									))}
-								</ul>
-							)}
+				<label>
+					<span className="page-sub">Split by </span>
+					<select value={splitBy} onChange={(event) => setSplitBy(event.target.value)}>
+						<option value="">No split</option>
+						{splitCandidates.map((question) => (
+							<option key={question.id} value={question.id}>
+								{question.prompt}
+							</option>
+						))}
+					</select>
+				</label>
+			</div>
+			<div className="grid-split-wide" style={{ alignItems: 'start', marginTop: 12 }}>
+				{data.questions.map((question) => (
+					<article className="card" key={question.id}>
+						<div className="kicker">
+							Q{question.position + 1} · {questionAudienceLabel(question.audience)}
 						</div>
+						<h3 className="card-title">{question.prompt}</h3>
+						{question.counts && <CountTable values={question.counts} />}
+						{question.distribution && (
+							<>
+								<p className="page-sub">
+									Average: {question.average === null ? '—' : question.average.toFixed(2)}
+								</p>
+								<CountTable values={question.distribution} />
+							</>
+						)}
+						{question.kind === 'text' && (
+							<p className="page-sub">{question.responseCount ?? 0} written answers</p>
+						)}
+						{cohorts && splitQuestion && splitQuestion.id !== question.id ? (
+							<CrossTab
+								question={question}
+								cohorts={cohorts}
+								answersByResponse={answersByResponse}
+							/>
+						) : null}
+					</article>
+				))}
+			</div>
+		</section>
+	)
+}
+
+function CrossTab({
+	question,
+	cohorts,
+	answersByResponse,
+}: {
+	question: SurveyQuestion
+	cohorts: Map<string, string[]>
+	answersByResponse: Map<string, Map<string, unknown>>
+}) {
+	const rows = [...cohorts.entries()].map(([cohort, responseIds]) => {
+		const values = responseIds
+			.map((id) => answersByResponse.get(id)?.get(question.id))
+			.filter((value) => value !== undefined)
+		if (question.kind === 'scale') {
+			const numbers = values.filter((value): value is number => typeof value === 'number')
+			const average = numbers.length
+				? numbers.reduce((sum, value) => sum + value, 0) / numbers.length
+				: null
+			return { cohort, n: values.length, summary: average === null ? '—' : average.toFixed(2) }
+		}
+		const counts = new Map<string, number>()
+		for (const value of values.flatMap((value) => (Array.isArray(value) ? value : [value]))) {
+			const key = formatAnswerValue(value)
+			counts.set(key, (counts.get(key) ?? 0) + 1)
+		}
+		const top = [...counts.entries()].sort((left, right) => right[1] - left[1])[0]
+		return { cohort, n: values.length, summary: top ? `${top[0]} (${top[1]})` : '—' }
+	})
+
+	if (rows.length === 0) return null
+	return (
+		<>
+			<div className="masthead-rule" />
+			<table className="tbl">
+				<thead>
+					<tr>
+						<th>Cohort</th>
+						<th>n</th>
+						<th>{question.kind === 'scale' ? 'Average' : 'Most common'}</th>
+					</tr>
+				</thead>
+				<tbody>
+					{rows.map((row) => (
+						<tr key={row.cohort}>
+							<td>{row.cohort}</td>
+							<td>{row.n}</td>
+							<td>{row.summary}</td>
+						</tr>
 					))}
-			</section>
-		</div>
+				</tbody>
+			</table>
+		</>
 	)
 }
 
@@ -215,6 +447,20 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+function respondentLabel(response: SurveyResults['responses'][number]): string {
+	if (response.respondent?.label) {
+		return response.respondent.detail
+			? `${response.respondent.label} · ${response.respondent.detail}`
+			: response.respondent.label
+	}
+	return response.anonymous ? 'Anonymous' : 'Known respondent'
+}
+
+function formatAnswerValue(value: unknown): string {
+	if (Array.isArray(value)) return value.join(', ')
+	return String(value)
+}
+
 function StatusPage({
 	title,
 	detail,
@@ -228,44 +474,46 @@ function StatusPage({
 		<div className="page" role="status">
 			<h1 className="page-title">Survey responses</h1>
 			<p className="page-sub">{title}</p>
-			{detail && <p className="page-sub">{detail}</p>}
-			{retry && (
-				<button type="button" className="btn" onClick={retry}>
+			{detail ? <p className="page-sub">{detail}</p> : null}
+			{retry ? (
+				<button className="btn" onClick={retry} type="button">
 					Retry
 				</button>
-			)}
+			) : null}
 		</div>
 	)
 }
 
 function CountTable({ values }: { values: Record<string, number> }) {
+	const total = Object.values(values).reduce((sum, count) => sum + count, 0)
 	return (
-		<table className="tbl">
-			<tbody>
-				{Object.entries(values).map(([label, count]) => (
-					<tr key={label}>
-						<th scope="row">{label}</th>
-						<td className="tnum">{count}</td>
-					</tr>
-				))}
-			</tbody>
-		</table>
+		<dl className="count-list">
+			{Object.entries(values).map(([label, count]) => (
+				<div key={label}>
+					<dt>{label}</dt>
+					<dd>
+						{count}
+						{total > 0 ? ` · ${Math.round((count / total) * 100)}%` : ''}
+					</dd>
+				</div>
+			))}
+		</dl>
 	)
 }
 
-function formatTime(value: string): string {
-	const date = new Date(value)
-	return Number.isNaN(date.getTime()) ? value : date.toLocaleString()
+function segmentLabel(segment: 'member' | 'non_member' | 'unknown'): string {
+	if (segment === 'member') return 'Member'
+	if (segment === 'non_member') return 'Non-member'
+	return 'Unknown'
 }
 
-function segmentLabel(value: 'member' | 'non_member' | 'unknown'): string {
-	if (value === 'member') return 'Member'
-	if (value === 'non_member') return 'Non-member'
-	return 'Unknown'
+function questionAudienceLabel(audience: 'all' | 'member' | 'non_member'): string {
+	if (audience === 'member') return 'Members'
+	if (audience === 'non_member') return 'Non-members'
+	return 'Everyone'
 }
 
-function questionAudienceLabel(value: 'all' | 'member' | 'non_member'): string {
-	if (value === 'member') return 'Members only'
-	if (value === 'non_member') return 'Non-members only'
-	return 'All respondents'
+function formatTime(value: string): string {
+	const date = new Date(value)
+	return Number.isNaN(date.getTime()) ? value : date.toLocaleString()
 }