Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { Button } from '@/components/ui/button';
import * as AlertDialog from '@radix-ui/react-alert-dialog';
import { Flame, Zap, Wrench, Flower, ChevronDown } from 'lucide-react';
import {
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from 'react';
import { useTranslation } from 'react-i18next';
import type {
ReleaseNoteItem,
ReleaseNoteSection,
ReleaseNoteTopic,
ReleaseNotes,
} from '@/release-notes';
import type { UpdateNoticeMode } from '@/hooks/useUpdateNotice';
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu';
import { Spinner } from '@/components/ui/spinner';
import { cn } from '@/lib/utils';
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
interface UpdateNoticeDialogProps {
open: boolean;
mode: UpdateNoticeMode | null;
/**
* Auto mode: pre-loaded diff range, newest-first.
* Manual mode: `[appVersionNotes]` — just the top block preloaded; the rest
* is discovered via `allVersions` and hydrated lazily via `loadVersion`.
*/
releaseNotes: ReleaseNotes[] | null;
/**
* Manual mode only: full history of versions on CDN (`≤ appVersion`),
* newest-first. Each entry becomes a placeholder in the scroll body that
* hydrates on view via `loadVersion`. Null in auto mode.
*/
allVersions: string[] | null;
/**
* Fetch a single version's notes. Returns null on 404 / parse / network.
* Backed by two-tier cache (main + renderer) — safe to call repeatedly.
*/
loadVersion: (version: string) => Promise<ReleaseNotes | null>;
onDismiss: () => void;
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/** Format date: '2026-04-18' -> locale-specific long date. */
function formatDate(dateStr: string, locale: string): string {
const [year, month, day] = dateStr.split('-').map(Number);
const date = new Date(year, month - 1, day);
return date.toLocaleDateString(locale, {
year: 'numeric',
month: 'long',
day: 'numeric',
});
}
/** Shared content column: one reading measure for every block in the dialog. */
const CONTENT_COLUMN = 'w-full max-w-[800px]';
// ---------------------------------------------------------------------------
// Sub-components
// ---------------------------------------------------------------------------
interface VersionBadgeProps {
label: string;
/** Renders a small chevron on the right and hover state — used by dropdown trigger. */
clickable?: boolean;
/** Leading flame glyph. Off for the header's version-jump chip, which is a count, not a version. */
icon?: boolean;
}
function VersionBadge({ label, clickable = false, icon = true }: VersionBadgeProps) {
return (
<span
className={cn(
'inline-flex items-center gap-1.5 rounded-full px-3 py-1 whitespace-nowrap',
'bg-[var(--chat-input-chip-bg)]',
// Chip text must use the chip's own semantic color. The previous
// `--settings-section-desc` resolves to a mid grey that lands at
// 2.33:1 against the chip background in dark mode (fails WCAG AA);
// `--chat-input-chip-text` is the sanctioned pairing (7.46:1 dark,
// 12:1 light).
'text-xs font-medium text-[var(--chat-input-chip-text)]',
clickable && 'cursor-pointer hover:bg-[var(--cmd-palette-item-hover)] transition-colors',
)}
>
{icon && <Flame className="h-[13px] w-[13px] shrink-0" />}
{label}
{clickable && <ChevronDown className="h-[13px] w-[13px] shrink-0 opacity-70" />}
</span>
);
}
const SECTION_ICONS = { zap: Zap, wrench: Wrench } as const;
function groupItemsByAuthor(
items: ReleaseNoteItem[],
): Array<{ author: string; items: ReleaseNoteItem[] }> {
const order: string[] = [];
const buckets = new Map<string, ReleaseNoteItem[]>();
for (const item of items) {
if (!buckets.has(item.by)) {
buckets.set(item.by, []);
order.push(item.by);
}
buckets.get(item.by)!.push(item);
}
return order.map((author) => ({ author, items: buckets.get(author)! }));
}
/**
* Legacy (author-grouped) body, rendered in the SAME single column as the v2
* topic layout. Previously this was a two-column split (features | fixes),
* which left half the dialog empty on bugfix-only releases and — more
* importantly — made scrolling through history alternate between two very
* different layouts, since only the newest release uses the topic format.
*
* Empty sections are dropped rather than rendered as a bare heading.
*/
function SectionList({ sections }: { sections: ReleaseNoteSection[] }) {
const { t } = useTranslation();
// Only the two canonical titles get translated. The legacy schema allows an
// arbitrary section title, and headings are now per-section rather than
// per-column, so mapping "anything that isn't Bug Fixes" to "New Features"
// would mislabel unknown sections and print the same heading twice when a
// payload carries several non-bugfix sections. Unknown titles pass through
// verbatim.
const labelFor = (title: string) => {
if (title === 'Bug Fixes') {
return { text: t('update.notice.bugFixes'), Icon: SECTION_ICONS.wrench };
}
if (title === 'New Features') {
return { text: t('update.notice.newFeatures'), Icon: SECTION_ICONS.zap };
}
return { text: title, Icon: SECTION_ICONS.zap };
};
const filled = sections.filter((s) => s.items.length > 0);
return (
<>
{filled.map((section, i) => {
const { text, Icon } = labelFor(section.title);
const groups = groupItemsByAuthor(section.items);
return (
<div key={`${i}-${section.title}`} className={cn(CONTENT_COLUMN, 'pt-4 pb-1')}>
<div className="mb-2.5 flex items-center gap-1.5">
<Icon className="h-3.5 w-3.5 shrink-0 text-[var(--cmd-palette-item-meta)]" />
<span className="text-13 font-medium text-[var(--cmd-palette-item-meta)]">
{text}
</span>
</div>
<div className="flex flex-col gap-3.5">
{groups.map((group) => (
<AuthorGroup key={group.author} author={group.author} items={group.items} />
))}
</div>
</div>
);
})}
</>
);
}
function AuthorGroup({ author, items }: { author: string; items: ReleaseNoteItem[] }) {
return (
<div>
<div
className={cn(
'mb-2 text-15 font-semibold leading-none tracking-tight',
'text-[var(--msg-assistant-text)]',
)}
>
{author}
</div>
<ul className="flex flex-col gap-1 list-none">
{items.map((item) => (
<li key={item.text} className="flex gap-2">
<span className="shrink-0 text-sm leading-[1.5] text-[var(--settings-section-desc)]">
•
</span>
<span className="text-sm leading-[1.5] text-[var(--msg-assistant-text)]">
{item.text}
</span>
</li>
))}
</ul>
</div>
);
}
/**
* Per-version thanks line, closing out that version's block like film credits.
*
* It used to live in the dialog chrome, which meant the same list was rendered
* twice at once (chrome + the version block's own subheader) and, at ~30
* contributors, turned the top of the dialog into a two-line wall of names.
* Anchoring it to the end of the version it belongs to removes the duplication
* and makes the attribution unambiguous. Regular weight + secondary color keeps
* it a closing note rather than a heading.
*/
function ThanksLine({ contributors }: { contributors: string[] }) {
const { t } = useTranslation();
if (contributors.length === 0) return null;
return (
<div
className={cn(
CONTENT_COLUMN,
'mt-3 flex items-start gap-1.5 border-t border-[var(--cmd-palette-border)] pt-4',
'text-12 leading-[1.7] select-text',
)}
>
<Flower
className="mt-[3px] h-3.5 w-3.5 shrink-0 text-[var(--status-bar-accent)]"
strokeWidth={2.25}
/>
<span className="shrink-0 text-[var(--cmd-palette-item-meta)]">
{t('update.notice.thanksTo')}
</span>
<span className="min-w-0 break-words text-[var(--cmd-palette-item-meta)]">
{contributors.join(' · ')}
</span>
</div>
);
}
// ---------------------------------------------------------------------------
// Topic-format (v2) body: single centered column of theme blocks. Replaces
// the two-column author-grouped layout for payloads that carry `topics` —
// notably fixes the half-empty dialog on bugfix-only releases.
// ---------------------------------------------------------------------------
function TopicList({ intro, topics }: { intro?: string; topics: ReleaseNoteTopic[] }) {
return (
<>
{intro && (
<div
className={cn(
CONTENT_COLUMN,
'pt-3 pb-1 text-sm leading-[1.7] break-words text-[var(--cmd-palette-item-meta)]',
)}
>
{intro}
</div>
)}
{topics.map((topic, i) => (
<div key={`${i}-${topic.title}`} className={cn(CONTENT_COLUMN, 'py-3')}>
{/* flex-wrap + min-w-0: long titles shrink/wrap and an overlong
contributor list drops to its own right-aligned line instead of
overflowing the dialog at narrow widths. */}
<div className="mb-1.5 flex flex-wrap items-baseline gap-x-2 gap-y-1">
{topic.emoji && <span className="text-15 leading-none">{topic.emoji}</span>}
<span
className={cn(
'min-w-0 break-words text-15 font-medium leading-tight tracking-tight',
'text-[var(--msg-assistant-text)]',
)}
>
{topic.title}
</span>
{topic.contributors.length > 0 && (
<span className="ml-auto max-w-full break-words text-right text-12 text-[var(--cmd-palette-item-meta)]">
{topic.contributors.join(' · ')}
</span>
)}
</div>
<div className="text-sm leading-[1.7] break-words text-[var(--msg-assistant-text)]">
{topic.text}
</div>
</div>
))}
</>
);
}
/**
* One version's block, single column throughout:
*
* [v0.1.21] 2026年7月29日 <- subheader: version + date only
* intro / topics (v2) or sections (legacy)
* ─────────────────────────
* 🌸 感谢 A · B · C <- closing thanks line
*
* The subheader deliberately no longer repeats the contributor list: it is the
* thanks line's job, once, at the end. The outer container owns scrolling.
*/
function VersionBlock({ notes, locale }: { notes: ReleaseNotes; locale: string }) {
const isTopicFormat = notes.topics.length > 0;
const formattedDate = formatDate(notes.date, locale);
return (
<div className="flex flex-col items-center px-7 pb-2">
<div className={cn(CONTENT_COLUMN, 'flex items-center gap-2 pt-5')}>
<VersionBadge label={`v${notes.version}`} />
{/* nowrap: a long date must not be squeezed into three lines by
whatever sits next to it (the old subheader did exactly that). */}
<span className="whitespace-nowrap text-13 text-[var(--cmd-palette-item-meta)]">
{formattedDate}
</span>
</div>
{isTopicFormat ? (
<TopicList intro={notes.intro} topics={notes.topics} />
) : (
<SectionList sections={notes.sections} />
)}
<ThanksLine contributors={notes.contributors} />
</div>
);
}
/**
* Placeholder for a manual-mode version whose notes haven't been loaded yet
* (either not yet in view, or in flight, or permanently 404). Uses a fixed
* min-height so scroll offsets stay stable when the real content swaps in.
*
* Error state is terminal (see ManualBody's startLoad guard) — but users can
* hit the retry button to explicitly re-fire the fetch, useful when a CDN
* eventually-consistent publish catches up after the initial miss.
*/
function PlaceholderBlock({
version,
isLoading,
isError,
onRetry,
}: {
version: string;
/**
* True only while a fetch is actually in flight. `idle` (queued but not yet
* observed) must NOT set this: every off-screen version used to render a
* spinner + "loading", so a user opening the history saw a dozen versions
* apparently stuck loading forever when in fact nothing had been requested.
*/
isLoading: boolean;
isError: boolean;
onRetry?: () => void;
}) {
const { t } = useTranslation();
return (
<div className="flex min-h-[180px] flex-col items-center px-7">
<div className={cn(CONTENT_COLUMN, 'flex items-center gap-3 pt-5')}>
<VersionBadge label={`v${version}`} />
{isLoading && (
<span className="inline-flex items-center gap-1.5 text-12 text-[var(--cmd-palette-item-meta)]">
<Spinner size={14} />
{t('update.notice.loading')}
</span>
)}
{isError && (
<span className="inline-flex items-center gap-2 text-12 text-[var(--cmd-palette-item-meta)]">
{t('update.notice.loadFailed')}
{onRetry && (
<Button variant="secondary" size="xxs" compact type="button" onClick={onRetry}>
{t('update.notice.retry')}
</Button>
)}
</span>
)}
</div>
{/* Idle (not yet scrolled near, nothing in flight) renders as reserved
blank space, not as a spinner — see PlaceholderBlock's isLoading doc. */}
<div className="flex min-h-[120px] flex-1 items-center justify-center" aria-hidden />
</div>
);
}
// ---------------------------------------------------------------------------
// Manual-mode dropdown: click header badge to jump to any version.
// ---------------------------------------------------------------------------
interface VersionDropdownProps {
versions: string[];
currentVersion: string;
onSelect: (version: string) => void;
triggerLabel: string;
/**
* Accessible name for the trigger. Must be given separately from
* `triggerLabel`: the visible chip only shows a version *count*, so reusing
* it as the accessible name would leave screen-reader users with no way to
* tell which version they are currently on without opening the menu.
*/
triggerAriaLabel: string;
/**
* Bubble open state up so the parent AlertDialog can guard its own
* dismissal while the dropdown is open or has just closed.
*/
onOpenChange?: (open: boolean) => void;
}
export function VersionDropdown({
versions,
currentVersion,
onSelect,
triggerLabel,
triggerAriaLabel,
onOpenChange,
}: VersionDropdownProps) {
return (
<DropdownMenu onOpenChange={onOpenChange} modal>
<DropdownMenuTrigger asChild>
<button
type="button"
className="inline-flex outline-none"
aria-label={triggerAriaLabel}
>
{/* The trigger now reads "N versions", not a version number, so the
flame glyph would be misleading — hence icon={false}. */}
<VersionBadge label={triggerLabel} clickable icon={false} />
</button>
</DropdownMenuTrigger>
<DropdownMenuContent
side="bottom"
align="end"
sideOffset={6}
// Stop clicks inside dropdown content from bubbling — belt-and-
// suspenders on top of `modal` prop + parent dropdownOpenRef guard.
onClick={(e) => e.stopPropagation()}
// Above the AlertDialog layer; long version lists scroll.
className="z-[10001] max-h-[400px] overflow-y-auto"
>
{/* The version on screen is the checked radio row. Each row still calls
onSelect on activation, the current one included, as before. */}
<DropdownMenuRadioGroup value={currentVersion}>
{versions.map((v) => (
<DropdownMenuRadioItem key={v} value={v} onSelect={() => onSelect(v)}>
<span className="tabular-nums">v{v}</span>
</DropdownMenuRadioItem>
))}
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenu>
);
}
// ---------------------------------------------------------------------------
// Auto-mode body: static header badge (v<oldest> → v<newest>), preloaded
// blocks stacked.
// ---------------------------------------------------------------------------
function AutoBody({
releaseNotes,
locale,
onStickyChange,
}: {
releaseNotes: ReleaseNotes[];
locale: string;
onStickyChange: (version: string) => void;
}) {
const scrollRef = useRef<HTMLDivElement | null>(null);
const blockRefs = useRef<Map<string, HTMLDivElement>>(new Map());
// Sticky-header observer: track which version block is at the top of the
// scroll area so the header badge can follow. Only active for multi-version
// auto mode — single-version stays at its initial value.
useEffect(() => {
const root = scrollRef.current;
if (!root || releaseNotes.length <= 1) return;
const observer = new IntersectionObserver(
(entries) => {
let best: { v: string; top: number } | null = null;
for (const entry of entries) {
if (!entry.isIntersecting) continue;
const v = (entry.target as HTMLElement).dataset.version;
if (!v) continue;
const top = entry.boundingClientRect.top;
// Pick the entry whose top is closest to the container top
// (largest top = nearest to 0, i.e. the version the user is reading).
if (best === null || top > best.top) best = { v, top };
}
if (best) onStickyChange(best.v);
},
{ root, rootMargin: '0px 0px -99% 0px', threshold: 0 },
);
for (const el of blockRefs.current.values()) observer.observe(el);
return () => observer.disconnect();
}, [releaseNotes, onStickyChange]);
// Fallback: when scrolled to the bottom, pick the last version so the header
// badge updates even if the last version is too short to reach the observation
// zone at the top. When leaving the bottom, recompute the visible version so
// the badge doesn't stay stuck on the last version.
const lastVersion = releaseNotes[releaseNotes.length - 1]?.version;
const handleAutoScroll = useCallback(() => {
const el = scrollRef.current;
if (!el || !lastVersion) return;
// Guard: only apply the bottom override when the content is actually
// scrollable. A +1 px threshold prevents sub-pixel rounding at
// non-integer zoom from making scrollHeight − clientHeight = 1 while
// the content is visually unscrollable; otherwise scrollTop is always
// 0 and the condition would trivially hold at the top, causing the
// header to show the last version.
if (
el.scrollHeight > el.clientHeight + 1 &&
el.scrollTop + el.clientHeight >= el.scrollHeight - 1
) {
onStickyChange(lastVersion);
return;
}
// Leaving the bottom: find the version block currently closest to the
// container top. This mirrors the IntersectionObserver's sticky-header
// logic but runs on every scroll event when not at the very bottom,
// clearing the bottom override that the IO cannot undo on its own.
const containerTop = el.getBoundingClientRect().top;
let best: { v: string; top: number } | null = null;
for (const [version, blockEl] of blockRefs.current.entries()) {
const top = blockEl.getBoundingClientRect().top;
if (top > containerTop + 9) continue; // block far below container top (9px = py-2 padding + 1px tolerance)
if (best === null || top > best.top) best = { v: version, top };
}
if (best) onStickyChange(best.v);
}, [lastVersion, onStickyChange]);
return (
<div
ref={scrollRef}
onScroll={handleAutoScroll}
className="flex flex-1 min-h-0 flex-col overflow-y-auto py-2 select-text"
>
{releaseNotes.map((notes, i) => (
<div
key={notes.version}
ref={(el) => {
if (el) blockRefs.current.set(notes.version, el);
else blockRefs.current.delete(notes.version);
}}
data-version={notes.version}
className="flex flex-col"
>
{i > 0 && <div className="mx-auto h-px w-full max-w-[800px] bg-[var(--cmd-palette-border)]" />}
<VersionBlock notes={notes} locale={locale} />
</div>
))}
</div>
);
}
// ---------------------------------------------------------------------------
// Manual-mode body: full history with lazy hydration.
// ---------------------------------------------------------------------------
/** State of a single version's fetch. */
type LoadState = 'idle' | 'loading' | 'loaded' | 'error';
interface ManualBodyProps {
allVersions: string[];
initialLoaded: Map<string, ReleaseNotes>;
loadVersion: (v: string) => Promise<ReleaseNotes | null>;
locale: string;
/** Called when the topmost visible version changes, so header can update. */
onStickyChange: (version: string) => void;
/** Setter registered by parent so `jumpToVersion` can programmatically scroll. */
registerJump: (fn: (v: string) => void) => void;
}
function ManualBody({
allVersions,
initialLoaded,
loadVersion,
locale,
onStickyChange,
registerJump,
}: ManualBodyProps) {
const scrollRef = useRef<HTMLDivElement | null>(null);
const blockRefs = useRef<Map<string, HTMLDivElement>>(new Map());
const [notesMap, setNotesMap] = useState<Map<string, ReleaseNotes>>(initialLoaded);
const [stateMap, setStateMap] = useState<Map<string, LoadState>>(() => {
const m = new Map<string, LoadState>();
for (const v of allVersions) {
m.set(v, initialLoaded.has(v) ? 'loaded' : 'idle');
}
return m;
});
const inFlightRef = useRef<Map<string, number>>(new Map());
const localeGenerationRef = useRef(0);
const previousLocaleRef = useRef(locale);
const notesMapRef = useRef(notesMap);
// Ref mirror of stateMap so `startLoad` doesn't need it in useCallback deps.
// Without this, every setStateMap → new startLoad identity → observer
// useEffect re-runs → new observer immediately fires callbacks for still-
// intersecting blocks → for `error` state blocks, retriggers fetch → error
// again → infinite loading↔failed flicker (the bug this refactor fixes).
const stateMapRef = useRef(stateMap);
useEffect(() => { stateMapRef.current = stateMap; }, [stateMap]);
useEffect(() => { notesMapRef.current = notesMap; }, [notesMap]);
// Parent-owned seed notes change when the app locale changes. Merge them
// into the manual body's local map instead of remounting the scroll area.
useEffect(() => {
if (initialLoaded.size === 0) return;
setNotesMap((prev) => {
const next = new Map(prev);
for (const [version, notes] of initialLoaded) next.set(version, notes);
notesMapRef.current = next;
return next;
});
setStateMap((prev) => {
const next = new Map(prev);
for (const version of initialLoaded.keys()) next.set(version, 'loaded');
stateMapRef.current = next;
return next;
});
}, [initialLoaded]);
// Refresh every already-loaded history block in place on locale changes.
// Blocks that have never loaded stay idle and will use the new locale later.
useEffect(() => {
if (previousLocaleRef.current === locale) return;
previousLocaleRef.current = locale;
const generation = localeGenerationRef.current + 1;
localeGenerationRef.current = generation;
inFlightRef.current.clear();
setStateMap((prev) => {
const next = new Map(prev);
for (const [version, state] of next) {
if (state === 'loading') next.set(version, 'idle');
}
stateMapRef.current = next;
return next;
});
const loadedVersions = [...notesMapRef.current.keys()];
if (loadedVersions.length === 0) return;
let cancelled = false;
void Promise.all(loadedVersions.map((version) => loadVersion(version)))
.then((results) => {
if (cancelled || localeGenerationRef.current !== generation) return;
setNotesMap((prev) => {
const next = new Map(prev);
results.forEach((notes, index) => {
if (notes) next.set(loadedVersions[index], notes);
});
notesMapRef.current = next;
return next;
});
})
.catch(() => {
// Keep the previous-language content visible; individual retry/loading
// behavior remains unchanged and the next locale change can retry.
});
return () => { cancelled = true; };
}, [locale, loadVersion]);
const startLoad = useCallback(
async (version: string) => {
if (inFlightRef.current.has(version)) return;
const current = stateMapRef.current.get(version);
// Terminal states — never retry automatically. Loaded needs no work,
// loading is already in flight (also guarded by inFlightRef), error is
// sticky until user hits the retry button (see `retryVersion`).
if (current === 'loaded' || current === 'loading' || current === 'error') return;
const generation = localeGenerationRef.current;
inFlightRef.current.set(version, generation);
setStateMap((prev) => new Map(prev).set(version, 'loading'));
try {
const notes = await loadVersion(version);
if (localeGenerationRef.current !== generation) return;
if (notes) {
setNotesMap((prev) => {
const next = new Map(prev).set(version, notes);
notesMapRef.current = next;
return next;
});
setStateMap((prev) => new Map(prev).set(version, 'loaded'));
} else {
setStateMap((prev) => new Map(prev).set(version, 'error'));
}
} catch {
if (localeGenerationRef.current !== generation) return;
setStateMap((prev) => new Map(prev).set(version, 'error'));
} finally {
if (inFlightRef.current.get(version) === generation) {
inFlightRef.current.delete(version);
}
}
},
[loadVersion],
);
// Manual retry from the error placeholder's button. Only meaningful for
// 'error' state (idle/loading/loaded are no-ops). Resets state to idle so
// startLoad's guard passes, then kicks off a fresh fetch. Sync-mutates the
// ref so the immediate startLoad call sees the reset — the paired
// setStateMap keeps React state consistent for rendering.
const retryVersion = useCallback(
(version: string) => {
if (stateMapRef.current.get(version) !== 'error') return;
const next = new Map(stateMapRef.current);
next.set(version, 'idle');
stateMapRef.current = next;
setStateMap(next);
void startLoad(version);
},
[startLoad],
);
// Lazy-load observer: fires when a block enters or is within 400px of the
// viewport so hydration starts before the user actually reaches it.
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
const observer = new IntersectionObserver(
(entries) => {
for (const entry of entries) {
if (!entry.isIntersecting) continue;
const v = (entry.target as HTMLElement).dataset.version;
if (v) void startLoad(v);
}
},
{ root, rootMargin: '400px 0px 400px 0px', threshold: 0 },
);
for (const el of blockRefs.current.values()) observer.observe(el);
return () => observer.disconnect();
}, [allVersions, startLoad]);
// Sticky-header observer: narrow band at the very top of the scroll area
// tells us which version block the user is currently reading. Whichever
// entry's top edge is closest to (but not past) the scroll-container top
// wins the badge.
useEffect(() => {
const root = scrollRef.current;
if (!root) return;
// rootMargin trick: negative bottom margin equal to (100% - 1px) shrinks
// the intersection zone to a 1px band at the top. Any element crossing
// that band is by definition the topmost currently-scrolled-to element.
const observer = new IntersectionObserver(
(entries) => {
// Pick the entry whose top is closest to the container top
// (largest top = nearest to 0, i.e. the version the user is reading).
let best: { v: string; top: number } | null = null;
for (const entry of entries) {
if (!entry.isIntersecting) continue;
const v = (entry.target as HTMLElement).dataset.version;
if (!v) continue;
const top = entry.boundingClientRect.top;
if (best === null || top > best.top) best = { v, top };
}
if (best) onStickyChange(best.v);
},
{ root, rootMargin: '0px 0px -99% 0px', threshold: 0 },
);
for (const el of blockRefs.current.values()) observer.observe(el);
return () => observer.disconnect();
}, [allVersions, onStickyChange]);
// Fallback: when scrolled to the bottom, pick the last version so the header
// badge updates even if the last version is too short to reach the top
// observation zone. When leaving the bottom, recompute the visible version so
// the badge doesn't stay stuck on the last version.
const lastVersion = allVersions[allVersions.length - 1];
const handleManualScroll = useCallback(() => {
const el = scrollRef.current;
if (!el || !lastVersion) return;
// Guard: only apply the bottom override when the content is actually
// scrollable. A +1 px threshold prevents sub-pixel rounding at
// non-integer zoom from making scrollHeight − clientHeight = 1 while
// the content is visually unscrollable; otherwise scrollTop is always
// 0 and the condition would trivially hold at the top, causing the
// header to show the last version.
if (
el.scrollHeight > el.clientHeight + 1 &&
el.scrollTop + el.clientHeight >= el.scrollHeight - 1
) {
onStickyChange(lastVersion);
return;
}
// Leaving the bottom: find the version block currently closest to the
// container top. This mirrors the IntersectionObserver's sticky-header
// logic but runs on every scroll event when not at the very bottom,
// clearing the bottom override that the IO cannot undo on its own.
const containerTop = el.getBoundingClientRect().top;
let best: { v: string; top: number } | null = null;
for (const [version, blockEl] of blockRefs.current.entries()) {
const top = blockEl.getBoundingClientRect().top;
if (top > containerTop + 9) continue; // block far below container top (9px = py-2 padding + 1px tolerance)
if (best === null || top > best.top) best = { v: version, top };
}
if (best) onStickyChange(best.v);
}, [lastVersion, onStickyChange]);
// Programmatic jump handler exposed to parent (header dropdown).
useEffect(() => {
registerJump((v: string) => {
const el = blockRefs.current.get(v);
if (!el) return;
// Use instant scroll to avoid triggering IntersectionObserver for all
// intermediate placeholders (smooth scroll would fan out CDN requests).
el.scrollIntoView({ behavior: 'instant', block: 'start' });
void startLoad(v);
});
}, [registerJump, startLoad]);
return (
<div
ref={scrollRef}
onScroll={handleManualScroll}
className="flex flex-1 min-h-0 flex-col overflow-y-auto py-2 select-text"
>
{allVersions.map((v, i) => {
const notes = notesMap.get(v);
const state = stateMap.get(v) ?? 'idle';
return (
<div
key={v}
ref={(el) => {
if (el) blockRefs.current.set(v, el);
else blockRefs.current.delete(v);
}}
data-version={v}
className="flex flex-col"
>
{i > 0 && <div className="mx-auto h-px w-full max-w-[800px] bg-[var(--cmd-palette-border)]" />}
{notes ? (
<VersionBlock notes={notes} locale={locale} />
) : (
<PlaceholderBlock
version={v}
isLoading={state === 'loading'}
isError={state === 'error'}
onRetry={() => retryVersion(v)}
/>
)}
</div>
);
})}
</div>
);
}
// ---------------------------------------------------------------------------
// Main component
// ---------------------------------------------------------------------------
export function UpdateNoticeDialog({
open,
mode,
releaseNotes,
allVersions,
loadVersion,
onDismiss,
}: UpdateNoticeDialogProps) {
const { t, i18n } = useTranslation();
// Memo-ize the seed Map so ManualBody's useState(initialLoaded) doesn't
// receive a new object identity on every parent re-render. The Map is only
// read once at ManualBody mount, but avoiding the allocation cost is free.
const initialLoaded = useMemo(
() => new Map((releaseNotes ?? []).map((n) => [n.version, n])),
[releaseNotes],
);
// Sticky version state — used only in manual mode; defaults to the newest
// preloaded version so the header badge is populated from the very first
// frame (no null flash while IntersectionObserver hasn't fired yet).
const initialSticky = releaseNotes?.[0]?.version ?? '';
const [stickyVersion, setStickyVersion] = useState<string>(initialSticky);
const jumpRef = useRef<((v: string) => void) | null>(null);
const registerJump = useCallback((fn: (v: string) => void) => {
jumpRef.current = fn;
}, []);
// Track version-dropdown open state + timestamp of most recent close, so a
// dismissal aimed at the dropdown (e.g. Escape) never cascades into closing
// the whole dialog. Any dismissal within `GRACE_MS` of a dropdown close is
// treated as part of the same gesture and bounces.
const DROPDOWN_CLOSE_GRACE_MS = 200;
const dropdownOpenRef = useRef(false);
const dropdownClosedAtRef = useRef(0);
const dismissIfDialogOnly = useCallback(() => {
if (dropdownOpenRef.current) return;
if (Date.now() - dropdownClosedAtRef.current < DROPDOWN_CLOSE_GRACE_MS) return;
onDismiss();
}, [onDismiss]);
// Reset sticky when dialog re-opens (avoids showing last-session's badge).
// Preserve the current sticky version across locale refreshes — when the
// dialog is already open and releaseNotes changes only because of a locale
// switch, the scroll position in ManualBody remains in place so the badge
// should not jump back to the newest version.
const wasOpenRef = useRef(false);
useEffect(() => {
if (open) {
if (!wasOpenRef.current) {
setStickyVersion(releaseNotes?.[0]?.version ?? '');
}
}
wasOpenRef.current = open;
}, [open, releaseNotes]);
if (!releaseNotes || !mode || releaseNotes.length === 0) {
return null;
}
const isManual = mode === 'manual';
const newest = releaseNotes[0];
const oldestLoaded = releaseNotes[releaseNotes.length - 1];
const isAutoMulti = mode === 'auto' && releaseNotes.length > 1;
// Aria description reads differently for each mode so screen-readers get
// a sensible summary instead of a generic "release notes for vX".
const ariaDescription = isManual
? t('update.notice.ariaDescriptionSpan', {
from: (allVersions && allVersions.length > 0)
? allVersions[allVersions.length - 1]
: newest.version,
count: allVersions?.length ?? 1,
})
: isAutoMulti
? t('update.notice.ariaDescriptionSpan', {
from: oldestLoaded.version,
count: releaseNotes.length,
})
: t('update.notice.ariaDescription', { version: newest.version });
// Header's right cell: version badge that follows scroll.
// - Manual multi: v<version> badge + dropdown for history navigation.
// - Auto multi: v<version> badge, updates as user scrolls.
// - Auto / manual single: static v<version> badge.
return (
<AlertDialog.Root
open={open}
// Route Radix-driven dismissal (Escape key) through dismissIfDialogOnly:
// dropdownOpenRef + grace window prevent spurious closes triggered by
// the version dropdown's own dismissal.
onOpenChange={(v) => { if (!v) dismissIfDialogOnly(); }}
>
<AlertDialog.Portal>
<AlertDialog.Overlay
className={cn(
'modal-scrim fixed inset-0 z-[10000]',
)}
style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
// No scrim click-to-dismiss (DESIGN.md closing affordance): the
// dialog closes only via 「知道了」 or Escape.
/>
<AlertDialog.Content
className={cn(
'modal-panel fixed left-1/2 top-1/2 z-[10000] -translate-x-1/2 -translate-y-1/2',
// 920px, not the previous 1240px: the body is a single ~800px
// reading column now, so the extra width only produced dead margins
// and made the full-width chrome visibly mismatch the narrow body.
'w-[920px] h-[838px] max-w-[95vw] max-h-[90vh] flex flex-col',
)}
style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
>
<AlertDialog.Description className="sr-only">
{ariaDescription}
</AlertDialog.Description>
{/* ---- Header ----
3-column grid instead of flex-justify-between so the right cell's
width changes never shift the centered title: each 1fr cell is
exactly a third of the header width, so the title always sits at
the true horizontal middle. The left cell is intentionally empty —
it exists to balance the grid. `min-w-0` keeps a long right label
from blowing out its track. */}
<div className="grid grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 px-6 pt-4 pb-3.5">
<span aria-hidden />
<AlertDialog.Title className="text-20 leading-[1.4] font-medium text-[var(--msg-assistant-text)] justify-self-center whitespace-nowrap">
{t('update.notice.title')}
</AlertDialog.Title>
<div className="min-w-0 justify-self-end">
{isManual && allVersions && allVersions.length > 1 ? (
<VersionDropdown
versions={allVersions}
currentVersion={stickyVersion || newest.version}
triggerLabel={`v${stickyVersion || newest.version}`}
triggerAriaLabel={t('update.notice.versionJumpAria', {
count: allVersions.length,
version: stickyVersion || newest.version,
})}
onSelect={(v) => jumpRef.current?.(v)}
onOpenChange={(dropOpen) => {
dropdownOpenRef.current = dropOpen;
// Record close timestamp so dismissIfDialogOnly can treat
// a dismissal within the grace window as part of the
// same close gesture and bounce it.
if (!dropOpen) dropdownClosedAtRef.current = Date.now();
}}
/>
) : (
<VersionBadge label={`v${stickyVersion || newest.version}`} />
)}
</div>
</div>
<div className="h-px bg-[var(--cmd-palette-border)]" />
{/* ---- Content ---- */}
{/* Auto single-version no longer needs its own branch: VersionBlock
carries the version, date and thanks itself, so one block and N
blocks render through the same path. */}
{isManual && allVersions ? (
<ManualBody
allVersions={allVersions}
initialLoaded={initialLoaded}
loadVersion={loadVersion}
locale={i18n.language}
onStickyChange={setStickyVersion}
registerJump={registerJump}
/>
) : (
<AutoBody
releaseNotes={releaseNotes}
locale={i18n.language}
onStickyChange={setStickyVersion}
/>
)}
<div className="h-px bg-[var(--cmd-palette-border)]" />
{/* ---- Footer ---- */}
<div className="flex justify-center px-7 pt-4 pb-5">
{/* flex-wrap + min-w-0: long titles shrink/wrap and an overlong
contributor list drops to its own right-aligned line instead of
overflowing the dialog at narrow widths. */}
<Button variant="primary" size="lg" type="button" onClick={onDismiss}>
{t('update.notice.gotIt')}
</Button>
</div>
</AlertDialog.Content>
</AlertDialog.Portal>
</AlertDialog.Root>
);
}