@growth-labs/cms 0.5.5 → 0.5.6

package/src/ui/commands.ts

@@ -1,6 +1,7 @@
 // src/ui/commands.ts — the ⌘K command set + the pure filter. "create"/"jump"
 // are static; "doc" entries are fed in from the /admin/api/search results.
-import type { ContentType } from '../schema/types.js'
+import type { CmsRole, ContentType } from '../schema/types.js'
+import { canViewSurveyResponses } from '../surveys/access.js'
 import { ROUTES, type Route } from './hash-router.js'
 
 export type Command =
@@ -24,6 +25,7 @@ const JUMP_LABELS: Record<Route, string> = {
 	topics: 'Topics & tags',
 	'content-insights': 'Content Insights',
 	subscriptions: 'Subscriptions',
+	'survey-responses': 'Survey responses',
 	'social-share': 'Social Share',
 	settings: 'Settings',
 }
@@ -37,6 +39,7 @@ const JUMP_ICONS: Record<Route, string> = {
 	topics: 'tag',
 	'content-insights': 'sparkle',
 	subscriptions: 'inbox',
+	'survey-responses': 'chart',
 	'social-share': 'share',
 	settings: 'settings',
 }
@@ -57,6 +60,16 @@ export const baseCommands: Command[] = [
 	),
 ]
 
+export function commandsForAccess(options: {
+	surveyResultsEnabled: boolean
+	role: CmsRole | null
+}): Command[] {
+	const canViewSurvey = options.surveyResultsEnabled && canViewSurveyResponses(options.role)
+	return baseCommands.filter(
+		(command) => command.kind !== 'jump' || command.route !== 'survey-responses' || canViewSurvey,
+	)
+}
+
 export function filterCommands(query: string, all: Command[]): Command[] {
 	const q = query.trim().toLowerCase()
 	if (!q) return all.slice(0, 9)

package/src/ui/components/CmsApp.tsx

@@ -1,9 +1,12 @@
 import { Component, type ReactNode, useEffect, useState } from 'react'
+import type { CmsRole } from '../../schema/types.js'
+import { canViewSurveyResponses } from '../../surveys/access.js'
 import type { BootState } from '../client/boot-state.js'
+import { commandsForAccess } from '../commands.js'
 import type { Route } from '../hash-router.js'
 import { useHashRouter } from '../use-hash-router.js'
 import { useTweaks } from '../use-tweaks.js'
-import { WorkspaceProvider, type WorkspaceState } from '../workspace-context.js'
+import { useWorkspace, WorkspaceProvider, type WorkspaceState } from '../workspace-context.js'
 import { CommandPalette } from './CommandPalette.js'
 import { NoAccessScreen } from './NoAccessScreen.js'
 import { Sidebar } from './Sidebar.js'
@@ -33,6 +36,7 @@ export function CmsApp(props: {
 
 function Shell({ screens }: { screens: ScreenRegistry }) {
 	const { route, navigate } = useHashRouter()
+	const { state } = useWorkspace()
 	const { t, setTweak } = useTweaks()
 	const [cmd, setCmd] = useState(false)
 	const [collapsed, setCollapsed] = useState(false)
@@ -47,10 +51,15 @@ function Shell({ screens }: { screens: ScreenRegistry }) {
 		window.addEventListener('keydown', h)
 		return () => window.removeEventListener('keydown', h)
 	}, [])
-	const screen = screens[route]
+	const screen = resolveScreenForAccess(screens, route, state.user?.role ?? null)
 	return (
 		<div className="app" data-collapsed={collapsed}>
-			<Sidebar route={route} navigate={navigate} collapsed={collapsed} />
+			<Sidebar
+				route={route}
+				navigate={navigate}
+				collapsed={collapsed}
+				surveyResultsEnabled={Boolean(screens['survey-responses'])}
+			/>
 			<div className="main">
 				<Topbar
 					collapsed={collapsed}
@@ -70,12 +79,25 @@ function Shell({ screens }: { screens: ScreenRegistry }) {
 					onClose={() => setCmd(false)}
 					navigate={navigate}
 					openDoc={() => setCmd(false)}
+					commands={commandsForAccess({
+						surveyResultsEnabled: Boolean(screens['survey-responses']),
+						role: state.user?.role ?? null,
+					})}
 				/>
 			)}
 		</div>
 	)
 }
 
+export function resolveScreenForAccess(
+	screens: ScreenRegistry,
+	route: Route,
+	role: CmsRole | null,
+): (() => ReactNode) | undefined {
+	if (route === 'survey-responses' && !canViewSurveyResponses(role)) return undefined
+	return screens[route]
+}
+
 function EmptyRoute({ route }: { route: Route }) {
 	return (
 		<div className="page" style={{ padding: 40, color: 'var(--ink-muted)' }}>

package/src/ui/components/CommandPalette.tsx

@@ -12,6 +12,7 @@ export function CommandPalette(props: {
 	onClose: () => void
 	navigate: (r: Route) => void
 	openDoc: (id: string | null, type?: string) => void
+	commands?: Command[]
 }) {
 	const [q, setQ] = useState('')
 	const [docs, setDocs] = useState<Command[]>([])
@@ -35,7 +36,7 @@ export function CommandPalette(props: {
 			.catch(() => {})
 		return () => ctrl.abort()
 	}, [q])
-	const all = [...baseCommands, ...docs]
+	const all = [...(props.commands ?? baseCommands), ...docs]
 	const filtered = filterCommands(q, all)
 	function run(c: Command) {
 		if (c.kind === 'jump') props.navigate(c.route)

package/src/ui/components/Sidebar.tsx

@@ -5,10 +5,18 @@ import { navItems } from '../nav.js'
 import { useWorkspace } from '../workspace-context.js'
 import { SiteSwitcher } from './SiteSwitcher.js'
 
-export function Sidebar(props: { route: Route; navigate: (r: Route) => void; collapsed: boolean }) {
+export function Sidebar(props: {
+	route: Route
+	navigate: (r: Route) => void
+	collapsed: boolean
+	surveyResultsEnabled?: boolean
+}) {
 	const { state } = useWorkspace()
-	const groups = navItems()
 	const user = state.user
+	const groups = navItems(
+		{},
+		{ surveyResultsEnabled: props.surveyResultsEnabled, role: user?.role },
+	)
 	const initial = user?.name?.[0]?.toUpperCase() ?? user?.email?.[0]?.toUpperCase() ?? '?'
 
 	return (

package/src/ui/hash-router.ts

@@ -11,6 +11,7 @@ export const ROUTES = [
 	'topics',
 	'content-insights',
 	'subscriptions',
+	'survey-responses',
 	'social-share',
 	'settings',
 ] as const

package/src/ui/nav.ts

@@ -1,6 +1,8 @@
 // src/ui/nav.ts — the Masthead sidebar nav model. Two groups, 11 items
 // (spec §6: Social Share added between Subscriptions and Settings).
 
+import type { CmsRole } from '../schema/types.js'
+import { canViewSurveyResponses } from '../surveys/access.js'
 import type { Route } from './hash-router.js'
 import type { IconName } from './icons.js'
 
@@ -33,6 +35,7 @@ export const NAV_MODEL: NavGroup[] = [
 			{ id: 'topics', label: 'Topics & tags', icon: 'tag' },
 			{ id: 'content-insights', label: 'Content Insights', icon: 'sparkle' },
 			{ id: 'subscriptions', label: 'Subscriptions', icon: 'inbox' },
+			{ id: 'survey-responses', label: 'Survey responses', icon: 'chart' },
 			{ id: 'social-share', label: 'Social Share', icon: 'share' },
 			{ id: 'settings', label: 'Settings', icon: 'settings' },
 		],
@@ -40,9 +43,19 @@ export const NAV_MODEL: NavGroup[] = [
 ]
 
 /** Build the nav with live counts merged onto matching item ids. */
-export function navItems(counts: Partial<Record<Route, number>> = {}): NavGroup[] {
+export function navItems(
+	counts: Partial<Record<Route, number>> = {},
+	options: { surveyResultsEnabled?: boolean; role?: CmsRole | null } = {
+		surveyResultsEnabled: true,
+		role: 'owner',
+	},
+): NavGroup[] {
+	const canViewSurvey =
+		options.surveyResultsEnabled !== false && canViewSurveyResponses(options.role)
 	return NAV_MODEL.map((g) => ({
 		group: g.group,
-		items: g.items.map((i) => (counts[i.id] != null ? { ...i, count: counts[i.id] } : { ...i })),
+		items: g.items
+			.filter((item) => item.id !== 'survey-responses' || canViewSurvey)
+			.map((i) => (counts[i.id] != null ? { ...i, count: counts[i.id] } : { ...i })),
 	}))
 }

package/src/ui/screens/SurveyResponsesScreen.tsx

@@ -0,0 +1,271 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+	isSurveyErrorCode,
+	SURVEY_ERROR_CODE_HEADER,
+	SURVEY_ERROR_DEFINITIONS,
+	type SurveyErrorCode,
+} from '../../surveys/errors.js'
+import { type SurveyResults, SurveyResultsSchema } from '../../surveys/schema.js'
+
+export type SurveyResponsesState =
+	| { kind: 'loading' }
+	| { kind: 'ready'; data: SurveyResults }
+	| { kind: 'forbidden' }
+	| { kind: 'unavailable' }
+	| { kind: 'malformed' }
+	| { kind: 'not_found' }
+	| { kind: 'retryable' }
+
+export function parseSurveyResultsPayload(value: unknown): SurveyResults | null {
+	const parsed = SurveyResultsSchema.safeParse(value)
+	return parsed.success ? parsed.data : null
+}
+
+export async function classifySurveyResultsResponse(
+	response: Response,
+): Promise<SurveyResponsesState> {
+	if (response.ok) {
+		const data = parseSurveyResultsPayload(await response.json().catch(() => null))
+		return data ? { kind: 'ready', data } : { kind: 'malformed' }
+	}
+
+	const code = await readSurveyErrorCode(response)
+	if ((response.status === 401 || response.status === 403) && code === 'survey_forbidden') {
+		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 === 503 && code === 'survey_provider_unavailable') {
+		return { kind: 'unavailable' }
+	}
+	return { kind: 'retryable' }
+}
+
+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])
+
+	useEffect(() => {
+		void load()
+	}, [load])
+
+	return <SurveyResponsesBody surveyId={surveyId} state={state} onRetry={load} />
+}
+
+export function SurveyResponsesBody({
+	surveyId,
+	state,
+	onRetry,
+}: {
+	surveyId: string
+	state: SurveyResponsesState
+	onRetry?: () => void
+}) {
+	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 === '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} />
+
+	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)
+	}
+
+	return (
+		<div className="page page-wide fade-in" style={{ maxWidth: 1340 }}>
+			<div className="page-head">
+				<div>
+					<h1 className="page-title">{data.survey.title}</h1>
+					<div className="page-sub">
+						{data.survey.responseCount} {data.survey.responseCount === 1 ? 'response' : 'responses'}{' '}
+						· {data.survey.status}
+					</div>
+				</div>
+				<a
+					className="btn"
+					href={`/admin/api/surveys/${encodeURIComponent(surveyId)}/responses.csv`}
+				>
+					Export CSV
+				</a>
+			</div>
+
+			{data.survey.responseCount === 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>
+				</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>
+			)}
+
+			<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}>
+							<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} free-text responses</p>
+							)}
+						</article>
+					))}
+				</div>
+			</section>
+
+			<section aria-labelledby="survey-free-text" style={{ marginTop: 24 }}>
+				<h2 className="page-title" id="survey-free-text" style={{ fontSize: 22 }}>
+					Free-text responses
+				</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>
+							)}
+						</div>
+					))}
+			</section>
+		</div>
+	)
+}
+
+async function readSurveyErrorCode(response: Response): Promise<SurveyErrorCode | null> {
+	const headerCode = response.headers.get(SURVEY_ERROR_CODE_HEADER)
+	if (!isSurveyErrorCode(headerCode)) return null
+	if (headerCode === 'survey_forbidden' && (response.status === 401 || response.status === 403)) {
+		return headerCode
+	}
+
+	const body = await response.json().catch(() => null)
+	if (!isPlainRecord(body) || Object.keys(body).length !== 2) return null
+	if (!isSurveyErrorCode(body.code) || body.code !== headerCode) return null
+	return body.error === SURVEY_ERROR_DEFINITIONS[body.code].error ? body.code : null
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function StatusPage({
+	title,
+	detail,
+	retry,
+}: {
+	title: string
+	detail?: string
+	retry?: () => void
+}) {
+	return (
+		<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}>
+					Retry
+				</button>
+			)}
+		</div>
+	)
+}
+
+function CountTable({ values }: { values: Record<string, number> }) {
+	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>
+	)
+}
+
+function formatTime(value: string): string {
+	const date = new Date(value)
+	return Number.isNaN(date.getTime()) ? value : date.toLocaleString()
+}
+
+function segmentLabel(value: 'member' | 'non_member' | 'unknown'): string {
+	if (value === 'member') return 'Member'
+	if (value === 'non_member') return 'Non-member'
+	return 'Unknown'
+}
+
+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'
+}

package/src/ui/screens/registry.tsx

@@ -23,6 +23,7 @@ import { MediaScreen } from './MediaScreen.js'
 import { SettingsScreen } from './SettingsScreen.js'
 import { SocialShareScreen } from './SocialShareScreen.js'
 import { SubscriptionsScreen } from './SubscriptionsScreen.js'
+import { SurveyResponsesScreen } from './SurveyResponsesScreen.js'
 import { TopicsScreen } from './TopicsScreen.js'
 
 // Thin wrappers that supply the openDoc seam for screens that need it.
@@ -40,8 +41,10 @@ function CalendarRoute() {
 
 export function createCmsScreens({
 	allowInlineAuthorCreation = true,
+	surveyId,
 }: {
 	allowInlineAuthorCreation?: boolean
+	surveyId?: string
 } = {}): ScreenRegistry {
 	return {
 		content: () => <ContentRoute allowInlineAuthorCreation={allowInlineAuthorCreation} />,
@@ -53,6 +56,9 @@ export function createCmsScreens({
 		authors: () => <AuthorsScreen />,
 		topics: () => <TopicsScreen />,
 		subscriptions: () => <SubscriptionsScreen />,
+		...(surveyId
+			? { 'survey-responses': () => <SurveyResponsesScreen surveyId={surveyId} /> }
+			: {}),
 		'social-share': () => (
 			<SocialShareScreen allowInlineAuthorCreation={allowInlineAuthorCreation} />
 		),