DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"use client";
import {
useCallback,
useEffect,
useLayoutEffect,
useRef,
useState,
} from "react";
import {
AnimatePresence,
m as motion,
useAnimationControls,
useReducedMotion,
} from "framer-motion";
import { pickerFlight, peekPickerOrigin } from "@/lib/picker-origin";
// Ref-count of currently-open PickerShells. While any are open we mark the
// <body> so global CSS can freeze ambient background animations (the sidebar
// "running session" pulse / breathing titles). Those repaints were being
// re-sampled by the modal's `backdrop-blur`, which read as a constant flicker
// behind the frosted scrim. Freezing them keeps the backdrop rock-steady.
let openShellCount = 0;
function acquireBodyFlag() {
openShellCount += 1;
if (typeof document !== "undefined") {
document.body.setAttribute("data-picker-open", "");
}
}
function releaseBodyFlag() {
openShellCount = Math.max(0, openShellCount - 1);
if (openShellCount === 0 && typeof document !== "undefined") {
document.body.removeAttribute("data-picker-open");
}
}
/**
* Behavioral wrapper for fullscreen pickers (NotebookRecordPicker,
* HistorySessionPicker, MemoryPicker, QuestionBankPicker, PersonaPicker,
* BookReferencePicker, SaveToNotebookModal, …). Each of those was rolled
* by hand and skipped the basic dialog-behavior contract — Escape, backdrop
* click, body scroll lock, focus trap, ARIA roles. This component lifts
* that contract into one place so the pickers themselves only have to
* render their *content*.
*
* Design notes:
* - The shell renders the centered backdrop. Callers render the picker
* card as `children` — they keep full control over the card's chrome,
* width, padding, etc. (see existing pickers).
* - `onClose` fires on Escape, on backdrop click, and is reachable
* programmatically (e.g. a Cancel button inside the card).
* - Focus management: on open we move focus to the first focusable element
* inside the dialog (typically the search input). On close we restore
* focus to wherever it was when the picker opened. This is what users
* expect from a modal but every hand-rolled picker had skipped it.
* - Focus trap: Tab from the last focusable element wraps to the first,
* Shift+Tab from the first wraps to the last. The dialog is the only
* thing screen-reader / keyboard users can interact with while open.
*/
export interface PickerShellProps {
open: boolean;
onClose: () => void;
children: React.ReactNode;
/**
* id of an element inside `children` that names the dialog. Required for
* proper `aria-labelledby`. If the picker has no visible title, pass an
* `aria-label` instead via `ariaLabel`.
*/
labelledBy?: string;
ariaLabel?: string;
/**
* Z-index for the backdrop. Defaults to 85 to match the existing
* picker convention; raise it if stacking under another picker.
*/
zIndex?: number;
/**
* Outer container layout. Most pickers center their card; some use a
* full-bleed layout. Defaults to centered.
*/
align?: "center" | "start";
/**
* Extra classes applied to the inner backdrop wrapper. Allows pickers
* to opt out of the default `flex items-center justify-center` for
* bespoke layouts.
*/
className?: string;
/**
* Override the default `bg-[var(--overlay)]` backdrop (a theme-aware scrim:
* warm/cool tint matches the active palette). Pass any opacity / blur /
* tint combo for pickers that want a frosted-glass look or a lighter scrim.
*/
backdropClass?: string;
}
const FOCUSABLE_SELECTOR =
'a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), iframe, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
export default function PickerShell({
open,
onClose,
children,
labelledBy,
ariaLabel,
zIndex = 85,
align = "center",
className,
backdropClass = "bg-[var(--overlay)]",
}: PickerShellProps) {
const dialogRef = useRef<HTMLDivElement>(null);
const previouslyFocusedRef = useRef<HTMLElement | null>(null);
const reduceMotion = useReducedMotion();
const cardControls = useAnimationControls();
const departureRef = useRef({
x: 0,
y: 8,
scaleX: 0.98,
scaleY: 0.98,
});
// Capture the trigger's rect at the moment `open` flips true so the card can
// expand outward from it. Derived during render (React's documented
// adjust-state-on-prop-change pattern) so it is available for the very first
// animated frame — an effect would run a frame too late.
const [originRect, setOriginRect] = useState<DOMRect | null>(null);
const [wasOpen, setWasOpen] = useState(false);
if (open !== wasOpen) {
setWasOpen(open);
if (open) setOriginRect(peekPickerOrigin());
}
useLayoutEffect(() => {
const card = dialogRef.current;
if (!open || !card) return;
// Read the final layout before paint, independently of an interrupted exit.
card.style.transform = "none";
const target = card.getBoundingClientRect();
const from =
!reduceMotion && originRect
? pickerFlight(originRect, target)
: {
x: 0,
y: reduceMotion ? 0 : 8,
scaleX: reduceMotion ? 1 : 0.98,
scaleY: reduceMotion ? 1 : 0.98,
};
departureRef.current = from;
cardControls.set({ ...from, opacity: originRect && !reduceMotion ? 1 : 0 });
void cardControls.start(
{ x: 0, y: 0, scaleX: 1, scaleY: 1, opacity: 1 },
{
type: "spring",
duration: reduceMotion ? 0 : originRect ? 0.48 : 0.24,
bounce: originRect ? 0.06 : 0,
opacity: { duration: reduceMotion ? 0 : 0.12 },
},
);
return () => cardControls.stop();
}, [open, originRect, reduceMotion, cardControls]);
// Freeze ambient background animations while this shell is open.
useEffect(() => {
if (!open) return;
acquireBodyFlag();
return () => releaseBodyFlag();
}, [open]);
// Stash the focused element when the picker opens so we can return focus
// there on close. Reset on every open so reopening returns to the latest
// trigger.
useEffect(() => {
if (!open) return;
previouslyFocusedRef.current =
(document.activeElement as HTMLElement | null) ?? null;
}, [open]);
// Body scroll lock. Preserve the user's prior overflow so we don't trample
// a parent that already had a lock in place.
useEffect(() => {
if (!open) return;
const prev = document.body.style.overflow;
document.body.style.overflow = "hidden";
return () => {
document.body.style.overflow = prev;
};
}, [open]);
// Move initial focus into the dialog on open. We defer to the next frame
// so the rendered card has measured + focusable elements are in the DOM.
useEffect(() => {
if (!open) return;
const id = window.requestAnimationFrame(() => {
const node = dialogRef.current;
if (!node) return;
// Prefer an explicit autofocus marker, then the first focusable child.
const explicit = node.querySelector<HTMLElement>("[data-autofocus]");
const target =
explicit ??
node.querySelector<HTMLElement>(
'input[type="search"], input[type="text"], input:not([type]), textarea',
) ??
node.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
target?.focus({ preventScroll: true });
});
return () => window.cancelAnimationFrame(id);
}, [open]);
// Restore focus to the trigger on close. Guarded by document.contains so
// we never call focus() on a detached element (e.g. the trigger was
// unmounted while the picker was open).
useEffect(() => {
if (open) return;
const trigger = previouslyFocusedRef.current;
const activeDialog = document.activeElement?.closest('[role="dialog"]');
if (
trigger &&
document.contains(trigger) &&
(!activeDialog || activeDialog === dialogRef.current)
) {
trigger.focus();
}
previouslyFocusedRef.current = null;
}, [open]);
const handleKeyDown = useCallback(
(e: React.KeyboardEvent) => {
if (e.key === "Escape") {
e.stopPropagation();
onClose();
return;
}
if (e.key !== "Tab") return;
// Focus trap. Cycle within the dialog so Tab can never escape into
// the page chrome behind us.
const node = dialogRef.current;
if (!node) return;
const focusables = Array.from(
node.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
).filter((el) => !el.hasAttribute("data-focus-skip"));
if (focusables.length === 0) return;
const first = focusables[0];
const last = focusables[focusables.length - 1];
const active = document.activeElement as HTMLElement | null;
if (e.shiftKey && active === first) {
e.preventDefault();
last.focus();
} else if (!e.shiftKey && active === last) {
e.preventDefault();
first.focus();
}
},
[onClose],
);
const handleBackdropMouseDown = useCallback(
(e: React.MouseEvent) => {
if (e.target === e.currentTarget) {
onClose();
}
},
[onClose],
);
const alignmentClass =
align === "center" ? "items-center justify-center" : "items-start";
// The surface starts at the clicked row's exact bounds. Fade its contents
// in after the shell has begun expanding so text never looks stretched.
const scrimTransition = { duration: reduceMotion ? 0 : 0.2 };
const cardExit = () =>
reduceMotion
? { opacity: 0, transition: { duration: 0 } }
: {
...departureRef.current,
opacity: 0,
transition: {
duration: originRect ? 0.28 : 0.16,
ease: [0.4, 0, 0.2, 1] as const,
opacity: { duration: 0.12, delay: originRect ? 0.14 : 0 },
},
};
return (
<AnimatePresence>
{open && (
<motion.div
// Backdrop. mousedown rather than click so dragging out of a search
// input doesn't dismiss the picker on the eventual mouseup.
key="picker-backdrop"
onMouseDown={handleBackdropMouseDown}
className={`fixed inset-0 flex ${alignmentClass} ${
className?.replace(/backdrop-blur-\w+/g, "") ?? ""
}`}
style={{ zIndex }}
initial={false}
exit={{ opacity: 1 }}
>
<motion.div
aria-hidden="true"
className={`pointer-events-none absolute inset-0 ${backdropClass}`}
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={scrimTransition}
/>
<motion.div
ref={dialogRef}
className="relative rounded-2xl bg-[var(--card)]"
role="dialog"
aria-modal="true"
aria-labelledby={labelledBy}
aria-label={labelledBy ? undefined : ariaLabel}
onKeyDown={handleKeyDown}
// Stop propagation so a click *inside* the dialog never reaches the
// backdrop's mousedown handler above. Width/layout decisions stay
// with the picker that renders the card inside.
onMouseDown={(e) => e.stopPropagation()}
// Own GPU layer keeps the expand transform crisp (no sub-pixel
// shimmer) and isolates it from the blurred backdrop's compositing.
style={{
willChange: "transform, opacity",
backfaceVisibility: "hidden",
}}
initial={{ opacity: 0 }}
animate={cardControls}
variants={{ depart: cardExit }}
exit="depart"
>
<motion.div
initial={{ opacity: originRect && !reduceMotion ? 0 : 1 }}
animate={{ opacity: 1 }}
exit={{
opacity: 0,
transition: { duration: reduceMotion ? 0 : 0.08 },
}}
transition={{
duration: reduceMotion ? 0 : 0.18,
delay: originRect && !reduceMotion ? 0.1 : 0,
}}
>
{children}
</motion.div>
</motion.div>
</motion.div>
)}
</AnimatePresence>
);
}