"use client"
/**
* ExamLockTemplate — locked assessment shell (exam / proctored delivery).
*
* Brand-tint canvas (`bg-sidebar`) + transparent `ExamLockAppHeader` + inset main card
* (`rounded-xl`, margin, shadow). Focus shells keep a deliberate card canvas;
* product hubs use flush `SidebarInset` instead.
*
* Hides workspace chrome via `App.tsx` + `SidebarAutoCollapse`.
*
* Reference: `@/components/exam-lock` + `components/exam-lock-showcase-client.tsx` (Design OS).
*/
import * as React from "react"
import { ExamLockAppHeader, type ExamLockLearnerIdentity } from "@/components/exam-lock/exam-lock-app-header"
import { SidebarAutoCollapse } from "@/components/sidebar"
import { useScrollStuck } from "@/hooks/use-scroll-stuck"
import { useSidebarReflowZoom } from "@/hooks/use-sidebar-reflow-zoom"
import { cn } from "@/lib/utils"
export type { ExamLockLearnerIdentity }
export interface ExamLockTemplateProps {
/** Exam title — rendered as the page `
` in the lock app header. */
title: string
/** Optional descriptor below the title (omit for exam lock delivery). */
subtitle?: React.ReactNode
/** Answered-question progress — flush at the top of the main card. */
progress?: React.ReactNode
/** When true, warns on tab close / refresh via `beforeunload`. */
sessionActive: boolean
/** After submit — replaces body with a no-navigation confirmation screen. */
submitted?: boolean
/** Optional timer node (right-aligned in the app header). */
timer?: React.ReactNode
/** Keyboard, calculator, settings — rendered before timer / submit. */
headerToolbar?: React.ReactNode
/** Right-aligned header actions (default: none — caller supplies Submit in `headerActions`). */
headerActions?: React.ReactNode
/** Learner identity — avatar at the far right of the app header. */
learner?: ExamLockLearnerIdentity
/**
* Soft session notices (sync lag, non-blocking hints) below the header.
* Hard integrity pauses use `interruption` + `useExamLockSessionController`.
*/
sessionAlert?: React.ReactNode
/** Pause surface behind the question card — revealed when the card slides down. */
interruption?: React.ReactNode
/** When true, the question card slides down to reveal `interruption`. */
sessionPaused?: boolean
/** Applied to the scrollable body below the header (e.g. display mode classes). */
surfaceClassName?: string
maxWidthClassName?: string
bodyClassName?: string
contentClassName?: string
/** Custom submitted screen; default copy is exam-safe (no links). */
submittedContent?: React.ReactNode
children: React.ReactNode
}
function DefaultSubmittedScreen({ title }: { title: string }) {
return (
Exam submitted
Your answers for {title} were
recorded. You may close this window. There is no return path to the workspace from
this session.
If you need assistance, contact your program coordinator. Do not use the browser Back
button.
)
}
/** Inset main card — mirrors `SidebarInset` surface; outer `p-2` on the shell owns the gutter when active. */
const EXAM_LOCK_MAIN_CARD_CLASS =
"relative flex min-h-0 min-w-0 flex-1 flex-col self-stretch overflow-x-hidden bg-background outline-none"
type ExamLockLayoutMode = "paused" | "contained" | "scroll"
/** Class fragments per layout mode (paused card slid down / contained fixed-height / free scroll). */
const EXAM_LOCK_LAYOUT_CLASSES: Record<
ExamLockLayoutMode,
{ main: string; card: string; widthWrap: string; content: string }
> = {
paused: {
main: "ring-2 ring-inset ring-border/60",
card: "pointer-events-none translate-y-full motion-reduce:translate-y-full",
widthWrap: "",
content: "",
},
contained: {
main: "min-h-0",
card: "min-h-0 overflow-hidden",
widthWrap: "min-h-0 flex-1",
content: "flex min-h-0 flex-1 flex-col overflow-hidden",
},
scroll: {
main: "overflow-y-auto",
card: "overflow-y-auto",
widthWrap: "",
content: "",
},
}
function examLockLayoutMode(showPauseSurface: boolean, containLayout: boolean): ExamLockLayoutMode {
if (showPauseSurface) return "paused"
return containLayout ? "contained" : "scroll"
}
/** Warns on tab close / refresh while a session is live. */
function useBeforeUnloadGuard(active: boolean) {
React.useEffect(() => {
if (!active) return
const onBeforeUnload = (event: BeforeUnloadEvent) => {
event.preventDefault()
event.returnValue = ""
}
window.addEventListener("beforeunload", onBeforeUnload)
return () => window.removeEventListener("beforeunload", onBeforeUnload)
}, [active])
}
function ExamLockStickyHeader({
isStuck,
sessionAlert,
headerProps,
}: {
isStuck: boolean
sessionAlert?: React.ReactNode
headerProps: React.ComponentProps
}) {
return (
{sessionAlert ? (
{sessionAlert}
) : null}
)
}
function ExamLockCardBody({
mode,
title,
submitted,
progress,
maxWidthClassName,
surfaceClassName,
contentClassName,
submittedContent,
children,
}: {
mode: ExamLockLayoutMode
title: string
submitted: boolean
progress?: React.ReactNode
maxWidthClassName: string
surfaceClassName?: string
contentClassName?: string
submittedContent?: React.ReactNode
children: React.ReactNode
}) {
const layout = EXAM_LOCK_LAYOUT_CLASSES[mode]
return (
{!submitted && progress ?
{progress}
: null}
{submitted ? (
{title}
) : null}
{submitted ? (submittedContent ?? ) : children}
)
}
export function ExamLockTemplate({
title,
subtitle,
progress,
sessionActive,
submitted = false,
timer,
headerToolbar,
headerActions,
learner,
sessionAlert,
interruption,
sessionPaused = false,
surfaceClassName,
maxWidthClassName = "max-w-5xl",
bodyClassName,
contentClassName,
submittedContent,
children,
}: ExamLockTemplateProps) {
useBeforeUnloadGuard(sessionActive && !submitted)
const reflowZoom = useSidebarReflowZoom()
const containLayout = sessionActive && !submitted && !reflowZoom
const isStuck = useScrollStuck()
const showPauseSurface = sessionPaused && interruption != null && !submitted
const mode = examLockLayoutMode(showPauseSurface, containLayout)
return (
{submitted ? null : (
)}
{showPauseSurface ? (
{interruption}
) : null}
{children}
)
}