feat(ui): add situational tips system (#6648)

This commit is contained in:
Thomas authored and GitHub committed 2026-08-21 18:58:52 +02:00
1 parent 3c2f95d529
commit f0f9539466
20 files changed
+694 -493

No files matched your search

@@ -139,6 +139,49 @@ describe("BoardAdvancedFocusProvider preview interaction", () => {
expect(focus.active).toBeNull();
});
test("promotes a Shift preview to a persistent view with Shift+Control", async () => {
await startPreview();
await act(async () => vi.advanceTimersByTime(500));
expect(focus.active?.activation).toBe("preview");
await act(async () =>
window.dispatchEvent(
new KeyboardEvent("keydown", { key: "Control", ctrlKey: true, shiftKey: true, cancelable: true }),
),
);
expect(focus.active?.activation).toBe("manual");
await act(async () => window.dispatchEvent(new KeyboardEvent("keyup", { key: "Shift" })));
expect(focus.active?.activation).toBe("manual");
});
test("promotes a Shift preview to a persistent view with Shift+Meta", async () => {
await startPreview();
await act(async () => vi.advanceTimersByTime(500));
await act(async () =>
window.dispatchEvent(
new KeyboardEvent("keydown", { key: "Meta", metaKey: true, shiftKey: true, cancelable: true }),
),
);
expect(focus.active?.activation).toBe("manual");
});
test("opens a persistent view when the keep-open modifiers are held before the delay", async () => {
const source = host.querySelector<HTMLElement>("[data-testid='source']");
if (!source) throw new Error("Expected source fixture");
await act(async () => {
focus.hover("widget-1", source);
window.dispatchEvent(new KeyboardEvent("keydown", { key: "Control", ctrlKey: true }));
window.dispatchEvent(
new KeyboardEvent("keydown", { key: "Shift", ctrlKey: true, shiftKey: true, cancelable: true }),
);
});
await act(async () => vi.advanceTimersByTime(500));
expect(focus.active?.activation).toBe("manual");
});
test("cancels the hold feedback and activation when the source is left early", async () => {
await startPreview();
@@ -55,6 +55,7 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
const activeRef = useRef<ActiveFocus | null>(null);
const hoveredRef = useRef<{ itemId: string; source: HTMLElement } | null>(null);
const shiftHeldRef = useRef(false);
const keepOpenHeldRef = useRef(false);
const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const previewLeaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -151,10 +152,31 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
hoverTimerRef.current = setTimeout(() => {
hoverTimerRef.current = null;
setIsHoldPending(false);
open(hovered.itemId, hovered.source, { activation: "preview" });
const activation = keepOpenHeldRef.current ? "manual" : "preview";
open(hovered.itemId, hovered.source, {
activation,
autofocusClose: activation === "manual",
restoreFocusTarget: hovered.source,
});
}, HOVER_DELAY_MS);
}, [cancelHoverTimer, open]);
const promotePreviewToManual = useCallback(() => {
const current = activeRef.current;
if (!current || current.activation !== "preview") return false;
cancelHoverTimer();
cancelPreviewLeaveTimer();
cancelCloseTimer();
updateActive({
...current,
activation: "manual",
autofocusClose: true,
restorePreviewFocus: false,
phase: "visible",
});
return true;
}, [cancelCloseTimer, cancelHoverTimer, cancelPreviewLeaveTimer, updateActive]);
const hover = useCallback(
(itemId: string, source: HTMLElement) => {
hoveredRef.current = { itemId, source };
@@ -268,19 +290,37 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
return;
}
if (isEditMode) return;
if (event.key !== "Shift" || event.repeat || isEditableTarget(event.target)) return;
if (event.repeat || isEditableTarget(event.target)) return;
const isKeepOpenModifier = event.key === "Control" || event.key === "Meta";
const hasKeepOpenShortcut = event.shiftKey && (event.ctrlKey || event.metaKey);
if (isKeepOpenModifier && hasKeepOpenShortcut) {
event.preventDefault();
keepOpenHeldRef.current = true;
if (!promotePreviewToManual()) startHoverTimer();
return;
}
if (event.key !== "Shift") return;
if (activeRef.current?.activation === "manual") return;
shiftHeldRef.current = true;
keepOpenHeldRef.current = hasKeepOpenShortcut;
startHoverTimer();
};
const handleKeyUp = (event: KeyboardEvent) => {
if (event.key === "Control" || event.key === "Meta") {
keepOpenHeldRef.current = false;
return;
}
if (event.key !== "Shift") return;
shiftHeldRef.current = false;
keepOpenHeldRef.current = false;
cancelHoverTimer();
if (activeRef.current?.activation === "preview") close(false);
};
const handleBlur = () => {
shiftHeldRef.current = false;
keepOpenHeldRef.current = false;
cancelHoverTimer();
if (activeRef.current?.activation === "preview") close(false);
};
@@ -296,7 +336,15 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
cancelPreviewLeaveTimer();
cancelCloseTimer();
};
}, [cancelCloseTimer, cancelHoverTimer, cancelPreviewLeaveTimer, close, isEditMode, startHoverTimer]);
}, [
cancelCloseTimer,
cancelHoverTimer,
cancelPreviewLeaveTimer,
close,
isEditMode,
promotePreviewToManual,
startHoverTimer,
]);
useEffect(() => {
if (isEditMode && activeRef.current) close(false);