Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: open Settings and the shortcuts list with one panel render and one focus move (#17042)

Daniel Hanc2a55951ebf2
diff --git a/studio/frontend/src/features/settings/settings-dialog.tsx b/studio/frontend/src/features/settings/settings-dialog.tsx
index de71f61ed8f..c9f909e60f5 100644
--- a/studio/frontend/src/features/settings/settings-dialog.tsx
+++ b/studio/frontend/src/features/settings/settings-dialog.tsx
@@ -45,8 +45,10 @@ import {
type ComponentType,
type FC,
type ReactNode,
+ type RefObject,
Suspense,
lazy,
+ memo,
useCallback,
useDeferredValue,
useEffect,
@@ -109,25 +111,64 @@ const TAB_LOADERS = {
import("./tabs/about-tab").then((m) => ({ default: m.AboutTab })),
} satisfies Record<SettingsTab, () => Promise<{ default: FC<SettingsPanelProps> }>>;
-function lazyTabs<
- T extends Record<string, () => Promise<{ default: FC<SettingsPanelProps> }>>,
->(
- loaders: T,
-): Record<keyof T, ComponentType<SettingsPanelProps>> {
- const out = {} as Record<keyof T, ComponentType<SettingsPanelProps>>;
- for (const id of Object.keys(loaders) as (keyof T)[]) {
- out[id] = lazy(loaders[id]);
+// Arrived panel modules (render without suspending) and requests in flight.
+const loadedTabs: Partial<Record<SettingsTab, FC<SettingsPanelProps>>> = {};
+const tabRequests: Partial<
+ Record<SettingsTab, Promise<{ default: FC<SettingsPanelProps> }>>
+> = {};
+
+function loadTab(id: SettingsTab): Promise<{ default: FC<SettingsPanelProps> }> {
+ let request = tabRequests[id];
+ if (!request) {
+ request = TAB_LOADERS[id]().then(
+ (m) => {
+ loadedTabs[id] = m.default;
+ return m;
+ },
+ (error: unknown) => {
+ // Not kept: a failed prefetch must not become the panel's own load, which tries afresh.
+ tabRequests[id] = undefined;
+ throw error;
+ },
+ );
+ tabRequests[id] = request;
+ }
+ return request;
+}
+
+// It warms panels nobody asked for yet, so a failed chunk must not surface as a rejection.
+function prefetchTab(id: SettingsTab): boolean {
+ if (loadedTabs[id] || tabRequests[id]) {
+ return false;
+ }
+ loadTab(id).catch(() => undefined);
+ return true;
+}
+
+function lazyTabs(): Record<SettingsTab, ComponentType<SettingsPanelProps>> {
+ const out = {} as Record<SettingsTab, ComponentType<SettingsPanelProps>>;
+ for (const id of Object.keys(TAB_LOADERS) as SettingsTab[]) {
+ out[id] = lazy(() => loadTab(id));
}
return out;
}
-const LAZY_TABS = lazyTabs(TAB_LOADERS);
+const LAZY_TABS = lazyTabs();
+// Panels already shown once; a first view paints the dialog first and the panel right after.
+const shownTabs = new Set<SettingsTab>();
+// Past the first paint and the chat's history load.
+const STARTUP_PREFETCH_DELAY_MS = 3000;
+// The other panels load once per page, one per idle slot after an open.
+const tabsLeftToPrefetch: SettingsTab[] = Object.keys(TAB_LOADERS) as SettingsTab[];
/** Marks the panel that has committed, from inside Suspense: while a panel is still loading its
* fallback replaces this whole subtree, so the marker is absent. A hidden empty element (no box,
* no text) rather than an effect on the pane: the pane's ref is not attached yet when a child's
* layout effect runs on first open. The long-chat gate's Settings sweep waits on it. */
function PanelCommitted({ tab, children }: { tab: SettingsTab; children: ReactNode }) {
+ useLayoutEffect(() => {
+ shownTabs.add(tab);
+ }, [tab]);
return (
<>
<span hidden aria-hidden="true" data-settings-panel-ready={tab} />
@@ -305,6 +346,132 @@ function useStackedLayout(): boolean {
return width > 1000 || narrow;
}
+interface PendingScroll {
+ tab: SettingsTab;
+ entry: string;
+}
+
+interface SettingsPanelPaneProps {
+ activeTab: SettingsTab;
+ isOwner: boolean;
+ pendingScroll: PendingScroll | null;
+ onPendingScrollDone: () => void;
+ scrollRef: RefObject<HTMLDivElement | null>;
+}
+
+/** The active tab's panel, mounted with the dialog content and memoised against its re-renders. */
+const SettingsPanelPane = memo(function SettingsPanelPane({
+ activeTab,
+ isOwner,
+ pendingScroll,
+ onPendingScrollDone,
+ scrollRef,
+}: SettingsPanelPaneProps) {
+ const t = useT();
+ const requestedTab = resolveSettingsTab(activeTab, isOwner);
+ // Deferred so the nav highlight updates first; null only for a tab's first view.
+ const deferredTab = useDeferredValue<SettingsTab | null>(
+ requestedTab,
+ shownTabs.has(requestedTab) ? undefined : null,
+ );
+ const panelTab = deferredTab === null ? null : resolveSettingsTab(deferredTab, isOwner);
+ // A module that has already arrived renders directly: lazy() would still suspend once on it.
+ // Picked once per tab while mounted, so the panel's component type never changes under it.
+ const Tab = useMemo(
+ () => (panelTab === null ? null : (loadedTabs[panelTab] ?? LAZY_TABS[panelTab])),
+ [panelTab],
+ );
+
+ // Shared scroller: reset per tab. panelTab, not activeTab, so the old panel does not jump mid-defer.
+ // Not on mount or for the first panel: the scroller mounts with the dialog, already at the top.
+ const scrolledTabRef = useRef(panelTab);
+ useLayoutEffect(() => {
+ const previous = scrolledTabRef.current;
+ if (previous === panelTab) {
+ return;
+ }
+ scrolledTabRef.current = panelTab;
+ if (previous !== null) {
+ scrollRef.current?.scrollTo({ top: 0, behavior: "instant" });
+ }
+ }, [panelTab, scrollRef]);
+
+ // Panels render deferred and load lazily, so observe until the target row exists.
+ useEffect(() => {
+ if (!pendingScroll) {
+ return;
+ }
+ // Wait for the destination tab, or a same-named row in the previous tab could match.
+ if (panelTab !== pendingScroll.tab) {
+ return;
+ }
+ const root = scrollRef.current;
+ if (!root) {
+ return;
+ }
+ const attempt = (): boolean => {
+ const target = [
+ ...root.querySelectorAll<HTMLElement>("[data-settings-label]"),
+ ].find((el) => el.dataset.settingsLabel === pendingScroll.entry);
+ if (target) {
+ target.scrollIntoView({ behavior: "smooth", block: "center" });
+ target.classList.add("settings-search-hit");
+ window.setTimeout(
+ () => target.classList.remove("settings-search-hit"),
+ 1600,
+ );
+ onPendingScrollDone();
+ return true;
+ }
+ return false;
+ };
+ const observer = new MutationObserver(() => {
+ if (attempt()) {
+ observer.disconnect();
+ }
+ });
+ observer.observe(root, { childList: true, subtree: true });
+ const frame = window.requestAnimationFrame(() => {
+ if (attempt()) {
+ observer.disconnect();
+ }
+ });
+ return () => {
+ observer.disconnect();
+ window.cancelAnimationFrame(frame);
+ };
+ }, [pendingScroll, panelTab, scrollRef, onPendingScrollDone]);
+
+ if (panelTab === null || Tab === null) {
+ return null;
+ }
+ return (
+ // Only a panel's first view waits, so the fallback is delayed and a
+ // promptly arriving panel never flashes it.
+ <SettingsPanelBoundary
+ tab={panelTab}
+ message={t("settings.dialog.panelFailed")}
+ reloadLabel={t("settings.dialog.panelReload")}
+ >
+ <Suspense
+ fallback={
+ <div className="fade-in fill-mode-both flex flex-1 animate-in items-center justify-center text-muted-foreground text-sm delay-300 duration-150">
+ {t("common.loading")}
+ </div>
+ }
+ >
+ <PanelCommitted tab={panelTab}>
+ <Tab
+ searchEntry={
+ pendingScroll?.tab === panelTab ? pendingScroll.entry : undefined
+ }
+ />
+ </PanelCommitted>
+ </Suspense>
+ </SettingsPanelBoundary>
+ );
+});
+
export function SettingsDialog() {
const t = useT();
const isOwner = useIsAccountOwner();
@@ -319,13 +486,13 @@ export function SettingsDialog() {
if (!node) {
return;
}
+ // Observer only (it fires once on observe): a read mid-commit forces layout.
const sync = () => {
const width = `${node.offsetWidth - node.clientWidth}px`;
- if (node.style.getPropertyValue("--rail-scrollbar") !== width) {
+ if ((node.style.getPropertyValue("--rail-scrollbar") || "0px") !== width) {
node.style.setProperty("--rail-scrollbar", width);
}
};
- sync();
const observer = new ResizeObserver(sync);
observer.observe(node);
return () => {
@@ -344,22 +511,42 @@ export function SettingsDialog() {
const opener = useSettingsDialogStore((s) => s.opener);
const openerFallback = useSettingsDialogStore((s) => s.openerFallback);
const reduced = useReducedMotion();
- // Deferred so the nav highlight updates before a heavy panel mounts.
- const deferredTab = useDeferredValue(activeTab);
- const panelTab = resolveSettingsTab(deferredTab, isOwner);
- const Tab = LAZY_TABS[panelTab];
const [query, setQuery] = useState("");
+ // On idle after startup: prefetch the opening tab and the shortcuts list.
+ useEffect(() => {
+ let cancelIdle: (() => void) | undefined;
+ const timer = window.setTimeout(() => {
+ cancelIdle = scheduleIdleTask(() => {
+ prefetchTab(resolveSettingsTab(useSettingsDialogStore.getState().activeTab, isOwner));
+ prefetchTab("keyboard-shortcuts");
+ }, 2000);
+ }, STARTUP_PREFETCH_DELAY_MS);
+ return () => {
+ window.clearTimeout(timer);
+ cancelIdle?.();
+ };
+ }, [isOwner]);
+
// Prefetch other panels on idle once opened; nothing runs while closed.
useEffect(() => {
- if (!open) {
+ if (!open || tabsLeftToPrefetch.length === 0) {
return;
}
- return scheduleIdleTask(() => {
- for (const load of Object.values(TAB_LOADERS)) {
- void load().catch(() => undefined);
+ let cancel: (() => void) | undefined;
+ const next = () => {
+ // Panels already loaded or loading cost no slot.
+ for (let id = tabsLeftToPrefetch.shift(); id; id = tabsLeftToPrefetch.shift()) {
+ if (prefetchTab(id)) {
+ break;
+ }
}
- });
+ if (tabsLeftToPrefetch.length > 0) {
+ cancel = scheduleIdleTask(next);
+ }
+ };
+ cancel = scheduleIdleTask(next);
+ return () => cancel?.();
}, [open]);
const results = useMemo(() => {
@@ -394,70 +581,16 @@ export function SettingsDialog() {
}).filter((r) => r.tabMatches || r.entries.length > 0);
}, [query, t, visibleTabs, hubSource, isOwner, canUpgradeToFullInstall]);
- const [pendingScroll, setPendingScroll] = useState<{
- tab: SettingsTab;
- entry: string;
- } | null>(null);
+ const [pendingScroll, setPendingScroll] = useState<PendingScroll | null>(null);
+ const clearPendingScroll = useCallback(() => setPendingScroll(null), []);
const mainScrollRef = useRef<HTMLDivElement | null>(null);
- // Shared scroller: reset per tab. panelTab, not activeTab, so the old panel does not jump mid-defer.
- // biome-ignore lint/correctness/useExhaustiveDependencies: panelTab is the trigger, not an input.
- useLayoutEffect(() => {
- mainScrollRef.current?.scrollTo({ top: 0, behavior: "instant" });
- }, [panelTab]);
-
const openResult = (tab: SettingsTab, entry?: string) => {
setActiveTab(tab);
setQuery("");
setPendingScroll(entry ? { tab, entry } : null);
};
- // Panels render deferred and load lazily, so observe until the target row exists.
- useEffect(() => {
- if (!pendingScroll) {
- return;
- }
- // Wait for the destination tab, or a same-named row in the previous tab could match.
- if (panelTab !== pendingScroll.tab) {
- return;
- }
- const root = mainScrollRef.current;
- if (!root) {
- return;
- }
- const attempt = (): boolean => {
- const target = [
- ...root.querySelectorAll<HTMLElement>("[data-settings-label]"),
- ].find((el) => el.dataset.settingsLabel === pendingScroll.entry);
- if (target) {
- target.scrollIntoView({ behavior: "smooth", block: "center" });
- target.classList.add("settings-search-hit");
- window.setTimeout(
- () => target.classList.remove("settings-search-hit"),
- 1600,
- );
- setPendingScroll(null);
- return true;
- }
- return false;
- };
- const observer = new MutationObserver(() => {
- if (attempt()) {
- observer.disconnect();
- }
- });
- observer.observe(root, { childList: true, subtree: true });
- const frame = window.requestAnimationFrame(() => {
- if (attempt()) {
- observer.disconnect();
- }
- });
- return () => {
- observer.disconnect();
- window.cancelAnimationFrame(frame);
- };
- }, [pendingScroll, panelTab]);
-
useEffect(() => {
if (open) {
return;
@@ -489,18 +622,32 @@ export function SettingsDialog() {
about: null,
});
+ const focusTabButton = useCallback((tab: SettingsTab): boolean => {
+ const button = tabButtonRefs.current[tab];
+ if (!button) {
+ return false;
+ }
+ button.focus({ preventScroll: true });
+ if (document.activeElement !== button) {
+ return false;
+ }
+ // "nearest" moves only the list, never the panel beside it.
+ button.scrollIntoView({ block: "nearest", inline: "nearest" });
+ return true;
+ }, []);
+
+ // Tab changes while open (a search result, a deep link): focus follows the active tab.
useEffect(() => {
if (!open) {
return;
}
const frame = window.requestAnimationFrame(() => {
- const button = tabButtonRefs.current[activeTab];
- button?.focus({ preventScroll: true });
- // "nearest" moves only the list, never the panel beside it.
- button?.scrollIntoView({ block: "nearest", inline: "nearest" });
+ if (document.activeElement !== tabButtonRefs.current[activeTab]) {
+ focusTabButton(activeTab);
+ }
});
return () => window.cancelAnimationFrame(frame);
- }, [open, activeTab]);
+ }, [open, activeTab, focusTabButton]);
return (
<>
@@ -508,6 +655,12 @@ export function SettingsDialog() {
<DialogContent
data-settings-dialog
showCloseButton={false}
+ // One focus move: each one restyles the page in WebKit.
+ onOpenAutoFocus={(e) => {
+ if (focusTabButton(activeTab)) {
+ e.preventDefault();
+ }
+ }}
overlayClassName="bg-black/40"
overlayTone="strong"
onCloseAutoFocus={(e) => {
@@ -718,31 +871,13 @@ export function SettingsDialog() {
ref={mainScrollRef}
className="hover-scrollbar flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto px-7 py-6 [scrollbar-gutter:stable]"
>
- {/* Only a panel's first view waits, so the fallback is delayed and a
- promptly arriving panel never flashes it. */}
- <SettingsPanelBoundary
- tab={panelTab}
- message={t("settings.dialog.panelFailed")}
- reloadLabel={t("settings.dialog.panelReload")}
- >
- <Suspense
- fallback={
- <div className="fade-in fill-mode-both flex flex-1 animate-in items-center justify-center text-muted-foreground text-sm delay-300 duration-150">
- {t("common.loading")}
- </div>
- }
- >
- <PanelCommitted tab={panelTab}>
- <Tab
- searchEntry={
- pendingScroll?.tab === panelTab
- ? pendingScroll.entry
- : undefined
- }
- />
- </PanelCommitted>
- </Suspense>
- </SettingsPanelBoundary>
+ <SettingsPanelPane
+ activeTab={activeTab}
+ isOwner={isOwner}
+ pendingScroll={pendingScroll}
+ onPendingScrollDone={clearPendingScroll}
+ scrollRef={mainScrollRef}
+ />
</div>
</DropdownGlowContext.Provider>
</main>
diff --git a/studio/frontend/tests/settings-tab-panel-loading.test.ts b/studio/frontend/tests/settings-tab-panel-loading.test.ts
index 1e3562f4b32..63eab6b062e 100644
--- a/studio/frontend/tests/settings-tab-panel-loading.test.ts
+++ b/studio/frontend/tests/settings-tab-panel-loading.test.ts
@@ -154,10 +154,49 @@ test("a panel that fails to load cannot take the app down with it", async () =>
);
});
-test("the panels are prefetched once the dialog opens", async () => {
+test("the panels are prefetched: the opening tab after startup, the rest after an open", async () => {
const source = await readFile(DIALOG, "utf8");
assert.match(source, /scheduleIdleTask/);
- assert.match(source, /Object\.values\(TAB_LOADERS\)/);
+ // Startup: the tab Settings opens on, plus the shortcuts list Mod+/ opens.
+ assert.match(
+ source,
+ /prefetchTab\(resolveSettingsTab\(useSettingsDialogStore\.getState\(\)\.activeTab, isOwner\)\);\s*prefetchTab\("keyboard-shortcuts"\);/,
+ );
+ // After an open: the rest, once per page and one per idle slot, nothing while closed.
+ assert.match(source, /if \(!open \|\| tabsLeftToPrefetch\.length === 0\)/);
+ assert.match(source, /tabsLeftToPrefetch\.shift\(\)/);
// It warms unselected panels, so a failed chunk must not surface as a rejection.
- assert.match(source, /load\(\)\.catch\(/);
+ assert.match(source, /loadTab\(id\)\.catch\(/);
+ // One request per panel, shared by the prefetch and the lazy component; a failed one is dropped.
+ assert.match(source, /lazy\(\(\) => loadTab\(id\)\)/);
+ assert.match(source, /tabRequests\[id\] = undefined;/);
+});
+
+test("an open renders the requested panel, never the one shown last", async () => {
+ // The deferred tab lives in the pane, which mounts with the dialog's content, so only tab
+ // switches made while open lag. A tab's first view in the page paints the dialog first (null,
+ // no panel) and renders the panel right after; once shown, an open renders it in the same pass.
+ const source = await readFile(DIALOG, "utf8");
+ const pane = source.slice(
+ source.indexOf("const SettingsPanelPane = memo("),
+ source.indexOf("export function SettingsDialog()"),
+ );
+ const dialog = source.slice(source.indexOf("export function SettingsDialog()"));
+ assert.match(
+ pane,
+ /useDeferredValue<SettingsTab \| null>\(\s*requestedTab,\s*shownTabs\.has\(requestedTab\) \? undefined : null,\s*\)/,
+ );
+ assert.match(source, /shownTabs\.add\(tab\)/);
+ assert.doesNotMatch(dialog, /useDeferredValue\(/);
+ assert.match(dialog, /<SettingsPanelPane\b/);
+});
+
+test("opening focuses the active tab once and forces no layout from the rail ref", async () => {
+ const source = await readFile(DIALOG, "utf8");
+ // Radix's default would focus the search box first, then the tab a frame later.
+ assert.match(source, /onOpenAutoFocus=\{\(e\) => \{\s*if \(focusTabButton\(activeTab\)\) \{\s*e\.preventDefault\(\);/);
+ // The rail's scroll bar width comes from the ResizeObserver only, never a read mid-commit.
+ const rail = source.slice(source.indexOf("const railRef = useCallback("), source.indexOf("const visibleTabs = useMemo("));
+ assert.match(rail, /new ResizeObserver\(sync\)/);
+ assert.doesNotMatch(rail, /^\s*sync\(\);/m);
});