feat: refine widget interactions

This commit is contained in:
Thomas Camlong authored and ajnart committed 2026-08-14 11:07:08 +02:00
1 parent a8a7545f40
commit 842e86012d
107 files changed
+3144 -1233

No files matched your search

+1 -1
View File
@@ -38,7 +38,7 @@ import editOn from "./img/edit.png";
### Editing
When the permissions of the user allows it, you can enter the editing of the text by clicking the following button in the top right.
When your permissions allow it, hover the widget, focus within it, or use a touch device to reveal the edit button in the top right. You can also double-click the document to edit it directly.
![](./img/notebook-enter-editing.webp)
@@ -1,11 +1,11 @@
import { IconArrowsMaximize, IconMouse2, IconPlus } from "@tabler/icons-react";
import { IconArrowsMaximize, IconLayoutGrid, IconMouse2, IconPlus } from "@tabler/icons-react";
const interactions = [
{
icon: IconArrowsMaximize,
title: "Advanced view",
description:
"Hold Shift while hovering (then pin it), press Shift + Enter, or choose Open advanced view from the widget menu.",
"Hold Shift while hovering for an in-place preview, press Shift + Enter, or choose Open advanced view from the widget menu.",
},
{
icon: IconMouse2,
@@ -19,6 +19,12 @@ const interactions = [
description:
"With board changes allowed, right-click or touch and hold empty grid space to add there. Keyboard users can press Shift + F10.",
},
{
icon: IconLayoutGrid,
title: "Adaptive detail",
description:
"Resize a widget to tune its density. Compact views keep primary status visible, then reveal details and controls as space or intent allows.",
},
] as const;
export const WidgetInteractionGuide = () => (
@@ -30,7 +36,7 @@ export const WidgetInteractionGuide = () => (
Hide shortcuts
</span>
</summary>
<div className="grid gap-3 border-0 border-t border-solid border-[#e5e7eb] p-4 md:grid-cols-3 dark:border-[#333]">
<div className="grid gap-3 border-0 border-t border-solid border-[#e5e7eb] p-4 md:grid-cols-2 xl:grid-cols-4 dark:border-[#333]">
{interactions.map(({ icon: Icon, title, description }) => (
<div key={title} className="rounded-lg bg-white p-3 shadow-sm dark:bg-gray-950">
<Icon aria-hidden size={20} stroke={1.5} className="mb-2 stroke-red-500" />
@@ -40,8 +46,8 @@ export const WidgetInteractionGuide = () => (
))}
</div>
<p className="m-0 px-4 pb-4 text-xs text-[#696969] dark:text-[#999]">
Advanced view reuses the widget&apos;s live data and cache. Touch devices expose a maximize control; board actions
respect your permissions and right-click preference.
Advanced view reuses the widget&apos;s live data and cache. The rest of the board stays visible but dimmed. Touch
devices expose a maximize control; app tiles stay compact.
</p>
</details>
);
@@ -1,28 +1,18 @@
.focusScope {
height: 100%;
}
.backdrop {
position: fixed;
inset: 0;
z-index: 198;
background: rgba(0, 0, 0, 0.64);
backdrop-filter: blur(6px) saturate(0.75);
touch-action: none;
pointer-events: none;
animation: focus-backdrop-in 180ms cubic-bezier(0.16, 1, 0.3, 1);
}
.surface {
position: fixed;
z-index: 199;
z-index: 1;
pointer-events: auto;
overflow: hidden;
background: var(--mantine-color-body);
box-shadow: var(--mantine-shadow-lg);
box-shadow: var(--mantine-shadow-md);
overscroll-behavior: contain;
animation: focus-surface-in 220ms cubic-bezier(0.16, 1, 0.3, 1);
animation: focus-surface-in 180ms cubic-bezier(0.16, 1, 0.3, 1);
transform-origin: top left;
padding-top: 60px;
}
.backdropClosing {
@@ -45,7 +35,7 @@
.surfaceHostAdvanced {
position: fixed;
inset: 0;
z-index: 199;
z-index: calc(var(--mantine-z-index-modal) - 1);
width: auto;
height: auto;
pointer-events: none;
@@ -58,33 +48,8 @@
pointer-events: none;
}
.surfaceControlsAdvanced {
right: 0;
bottom: auto;
height: 60px;
background: color-mix(in srgb, var(--mantine-color-body) 92%, transparent);
border-bottom: 1px solid var(--mantine-color-default-border);
}
.surfaceTitle {
position: absolute;
top: 20px;
right: 120px;
left: 16px;
}
.closeButton {
position: absolute;
top: 8px;
right: 8px;
z-index: 2;
pointer-events: auto;
}
.pinButton {
position: absolute;
top: 8px;
right: 60px;
position: fixed;
z-index: 2;
pointer-events: auto;
}
@@ -141,8 +106,7 @@
@media (forced-colors: active) {
.backdrop {
backdrop-filter: none;
background: Canvas;
opacity: 0.8;
opacity: 0.4;
}
}
@@ -2,7 +2,7 @@
import type { PropsWithChildren } from "react";
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
import { Box, Portal, RemoveScroll } from "@mantine/core";
import { Overlay, Portal } from "@mantine/core";
import { useEditMode } from "@homarr/boards/edit-mode";
@@ -14,17 +14,21 @@ interface ActiveFocus {
itemId: string;
source: HTMLElement;
sourceRect: FocusRect;
pinned: boolean;
activation: "preview" | "manual";
autofocusClose: boolean;
phase: "visible" | "closing";
}
interface OpenAdvancedFocusOptions {
activation?: ActiveFocus["activation"];
autofocusClose?: boolean;
}
interface AdvancedFocusContextValue {
active: ActiveFocus | null;
open: (itemId: string, source: HTMLElement, pinned?: boolean) => void;
open: (itemId: string, source: HTMLElement, options?: OpenAdvancedFocusOptions) => void;
close: (restoreFocus?: boolean) => void;
dismiss: (itemId: string) => void;
pin: (autofocusClose?: boolean) => void;
hover: (itemId: string, source: HTMLElement) => void;
leave: (itemId: string) => void;
}
@@ -64,7 +68,7 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
}, []);
const open = useCallback(
(itemId: string, source: HTMLElement, pinned = false) => {
(itemId: string, source: HTMLElement, options: OpenAdvancedFocusOptions = {}) => {
if (isEditMode) return;
cancelHoverTimer();
cancelCloseTimer();
@@ -73,8 +77,8 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
itemId,
source,
sourceRect: { left: rect.left, top: rect.top, width: rect.width, height: rect.height },
pinned,
autofocusClose: pinned,
activation: options.activation ?? "manual",
autofocusClose: options.autofocusClose ?? false,
phase: "visible",
});
},
@@ -101,15 +105,23 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
cancelHoverTimer();
const hovered = hoveredRef.current;
if (!hovered || !shiftHeldRef.current || activeRef.current) return;
hoverTimerRef.current = setTimeout(() => open(hovered.itemId, hovered.source), HOVER_DELAY_MS);
hoverTimerRef.current = setTimeout(
() => open(hovered.itemId, hovered.source, { activation: "preview" }),
HOVER_DELAY_MS,
);
}, [cancelHoverTimer, open]);
const hover = useCallback(
(itemId: string, source: HTMLElement) => {
hoveredRef.current = { itemId, source };
const current = activeRef.current;
if (current?.activation === "preview" && current.itemId !== itemId) {
cancelCloseTimer();
updateActive(null);
}
startHoverTimer();
},
[startHoverTimer],
[cancelCloseTimer, startHoverTimer, updateActive],
);
const leave = useCallback(
@@ -130,15 +142,6 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
[cancelCloseTimer, cancelHoverTimer, updateActive],
);
const pin = useCallback(
(autofocusClose = false) => {
const current = activeRef.current;
if (!current || current.pinned || current.phase === "closing") return;
updateActive({ ...current, pinned: true, autofocusClose });
},
[updateActive],
);
useEffect(() => {
const handleKeyDown = (event: KeyboardEvent) => {
if (event.key === "Escape" && activeRef.current) {
@@ -151,7 +154,7 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
}
if (isEditMode) return;
if (event.key !== "Shift" || event.repeat || isEditableTarget(event.target)) return;
if (activeRef.current?.pinned) return;
if (activeRef.current?.activation === "manual") return;
shiftHeldRef.current = true;
startHoverTimer();
};
@@ -159,12 +162,12 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
if (event.key !== "Shift") return;
shiftHeldRef.current = false;
cancelHoverTimer();
if (activeRef.current && !activeRef.current.pinned) close(false);
if (activeRef.current?.activation === "preview") close(false);
};
const handleBlur = () => {
shiftHeldRef.current = false;
cancelHoverTimer();
if (activeRef.current && !activeRef.current.pinned) close(false);
if (activeRef.current?.activation === "preview") close(false);
};
window.addEventListener("keydown", handleKeyDown);
@@ -184,20 +187,22 @@ export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
}, [close, isEditMode]);
const value = useMemo(
() => ({ active, open, close, dismiss, pin, hover, leave }),
[active, close, dismiss, hover, leave, open, pin],
() => ({ active, open, close, dismiss, hover, leave }),
[active, close, dismiss, hover, leave, open],
);
return (
<AdvancedFocusContext.Provider value={value}>
<RemoveScroll enabled={active !== null} className={classes.focusScope}>
{children}
</RemoveScroll>
{children}
{active && (
<Portal>
<Box
<Overlay
fixed
data-advanced-focus-overlay
backgroundOpacity={0.38}
blur={0}
zIndex="calc(var(--mantine-z-index-modal) - 2)"
className={`${classes.backdrop} ${active.phase === "closing" ? classes.backdropClosing : ""}`}
onPointerDown={() => close()}
aria-hidden
/>
</Portal>
@@ -5,7 +5,7 @@ import { isEscapeOwnedByNestedOverlay } from "./escape";
describe("isEscapeOwnedByNestedOverlay", () => {
test("allows Escape from the advanced surface itself", () => {
const surface = document.createElement("section");
surface.setAttribute("role", "dialog");
surface.setAttribute("role", "region");
const button = document.createElement("button");
surface.append(button);
@@ -14,7 +14,7 @@ describe("isEscapeOwnedByNestedOverlay", () => {
test("leaves Escape to a nested Mantine modal", () => {
const surface = document.createElement("section");
surface.setAttribute("role", "dialog");
surface.setAttribute("role", "region");
const modal = document.createElement("section");
modal.setAttribute("role", "dialog");
const input = document.createElement("input");
@@ -25,7 +25,7 @@ describe("isEscapeOwnedByNestedOverlay", () => {
test.each(["menu", "listbox"])("leaves Escape to a nested %s overlay", (role) => {
const surface = document.createElement("section");
surface.setAttribute("role", "dialog");
surface.setAttribute("role", "region");
const overlay = document.createElement("div");
overlay.setAttribute("role", role);
const target = document.createElement("button");
@@ -36,7 +36,7 @@ describe("isEscapeOwnedByNestedOverlay", () => {
test("honors Mantine's stop-propagation marker for menus and comboboxes", () => {
const surface = document.createElement("section");
surface.setAttribute("role", "dialog");
surface.setAttribute("role", "region");
const target = document.createElement("button");
target.setAttribute("data-mantine-stop-propagation", "true");
surface.append(target);
@@ -46,7 +46,7 @@ describe("isEscapeOwnedByNestedOverlay", () => {
test("does not mistake the compact widget source for a nested overlay", () => {
const surface = document.createElement("section");
surface.setAttribute("role", "dialog");
surface.setAttribute("role", "region");
const source = document.createElement("button");
expect(isEscapeOwnedByNestedOverlay(source, surface)).toBe(false);
@@ -1,15 +1,14 @@
import { describe, expect, it } from "vitest";
import { getAdvancedFocusRect } from "./geometry";
import { getAdvancedFocusClosePosition, getAdvancedFocusRect } from "./geometry";
describe("getAdvancedFocusRect", () => {
it("expands a widget and keeps it inside the viewport", () => {
const rect = getAdvancedFocusRect({ left: 10, top: 10, width: 300, height: 200 }, { width: 1200, height: 800 });
it("expands around the widget instead of centering a modal", () => {
const rect = getAdvancedFocusRect({ left: 450, top: 300, width: 300, height: 200 }, { width: 1200, height: 800 });
expect(rect.left).toBe(120);
expect(rect.top).toBeCloseTo(118.6);
expect(rect.width).toBe(960);
expect(rect.height).toBeCloseTo(622.8);
expect(rect).toEqual({ left: 200, top: 120, width: 800, height: 560 });
expect(rect.left + rect.width / 2).toBe(600);
expect(rect.top + rect.height / 2).toBe(400);
});
it("uses the available viewport on small screens", () => {
@@ -22,9 +21,34 @@ describe("getAdvancedFocusRect", () => {
});
it("keeps controls below the fixed board header on short screens", () => {
const rect = getAdvancedFocusRect({ left: 0, top: 0, width: 500, height: 500 }, { width: 1366, height: 768 });
const rect = getAdvancedFocusRect({ left: 1200, top: 700, width: 500, height: 500 }, { width: 1366, height: 768 });
expect(rect.top).toBeGreaterThanOrEqual(84);
expect(rect.top + rect.height).toBeLessThanOrEqual(744);
expect(rect.left).toBeGreaterThanOrEqual(16);
expect(rect.left + rect.width).toBeLessThanOrEqual(1350);
expect(rect.top).toBeGreaterThanOrEqual(76);
expect(rect.top + rect.height).toBeLessThanOrEqual(752);
});
});
describe("getAdvancedFocusClosePosition", () => {
it("keeps the close control outside the surface when the right side has room", () => {
expect(getAdvancedFocusClosePosition({ left: 16, top: 76, width: 800, height: 560 }, 1280)).toEqual({
left: 824,
top: 76,
});
});
it("uses the left side when the surface is anchored to the right edge", () => {
expect(getAdvancedFocusClosePosition({ left: 464, top: 76, width: 800, height: 560 }, 1280)).toEqual({
left: 412,
top: 76,
});
});
it("falls back to the inside corner on narrow screens", () => {
expect(getAdvancedFocusClosePosition({ left: 8, top: 68, width: 374, height: 624 }, 390)).toEqual({
left: 330,
top: 76,
});
});
});
@@ -7,22 +7,48 @@ export interface FocusRect {
height: number;
}
export interface FocusClosePosition {
left: number;
top: number;
}
const closeButtonSize = 44;
const closeButtonGap = 8;
export const getAdvancedFocusRect = (source: FocusRect, viewport: { width: number; height: number }): FocusRect => {
const margin = viewport.width < 640 ? 8 : 24;
const margin = viewport.width < 640 ? 8 : 16;
const availableWidth = Math.max(0, viewport.width - margin * 2);
const availableHeight = Math.max(0, viewport.height - appShellHeaderHeight - margin * 2);
const preferredWidth = viewport.width < 640 ? availableWidth : Math.min(960, availableWidth * 0.9);
const preferredHeight = viewport.width < 640 ? availableHeight : Math.min(720, availableHeight * 0.9);
const preferredWidth = viewport.width < 640 ? availableWidth : Math.min(800, availableWidth);
const preferredHeight = viewport.width < 640 ? availableHeight : Math.min(560, availableHeight);
const width = Math.min(availableWidth, Math.max(source.width, preferredWidth));
const height = Math.min(availableHeight, Math.max(source.height, preferredHeight));
const minimumTop = appShellHeaderHeight + margin;
const maximumLeft = Math.max(margin, viewport.width - margin - width);
const maximumTop = Math.max(minimumTop, viewport.height - margin - height);
return {
left: Math.max(margin, (viewport.width - width) / 2),
top: Math.max(
appShellHeaderHeight + margin,
appShellHeaderHeight + (viewport.height - appShellHeaderHeight - height) / 2,
),
left: Math.min(maximumLeft, Math.max(margin, source.left - (width - source.width) / 2)),
top: Math.min(maximumTop, Math.max(minimumTop, source.top - (height - source.height) / 2)),
width,
height,
};
};
export const getAdvancedFocusClosePosition = (surface: FocusRect, viewportWidth: number): FocusClosePosition => {
const outsideOffset = closeButtonSize + closeButtonGap;
const surfaceRight = surface.left + surface.width;
if (viewportWidth - surfaceRight >= outsideOffset) {
return { left: surfaceRight + closeButtonGap, top: surface.top };
}
if (surface.left >= outsideOffset) {
return { left: surface.left - outsideOffset, top: surface.top };
}
return {
left: Math.max(0, Math.min(viewportWidth - closeButtonSize, surfaceRight - outsideOffset)),
top: surface.top + closeButtonGap,
};
};