feat: modernize dashboard widgets

apps/nextjs/src/components/board/advanced-focus/advanced-focus.module.css

@@ -0,0 +1,132 @@
+.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;
+  animation: focus-backdrop-in 180ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.surface {
+  position: fixed;
+  z-index: 199;
+  pointer-events: auto;
+  overflow: hidden;
+  background: var(--mantine-color-body);
+  box-shadow: var(--mantine-shadow-lg);
+  overscroll-behavior: contain;
+  animation: focus-surface-in 220ms cubic-bezier(0.16, 1, 0.3, 1);
+  transform-origin: top left;
+}
+
+.backdropClosing {
+  animation: focus-backdrop-out 180ms ease-in forwards;
+}
+
+.surfaceClosing {
+  animation: focus-surface-out 180ms ease-in forwards;
+}
+
+.sourcePlaceholder {
+  pointer-events: none;
+}
+
+.surfaceHost {
+  width: 100%;
+  height: 100%;
+}
+
+.surfaceHostAdvanced {
+  position: fixed;
+  inset: 0;
+  z-index: 199;
+  width: auto;
+  height: auto;
+  pointer-events: none;
+}
+
+.surfaceControls {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  pointer-events: none;
+}
+
+.closeButton {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  z-index: 2;
+  pointer-events: auto;
+}
+
+.pinButton {
+  position: absolute;
+  top: 8px;
+  right: 52px;
+  z-index: 2;
+  pointer-events: auto;
+}
+
+.touchButton {
+  position: absolute;
+  right: 8px;
+  bottom: 8px;
+  z-index: 2;
+  display: none;
+  pointer-events: auto;
+}
+
+@media (pointer: coarse) {
+  .touchButton {
+    display: inline-flex;
+  }
+}
+
+@keyframes focus-backdrop-in {
+  from {
+    opacity: 0;
+  }
+}
+
+@keyframes focus-surface-in {
+  from {
+    transform: translate(var(--focus-translate-x), var(--focus-translate-y))
+      scale(var(--focus-scale-x), var(--focus-scale-y));
+    opacity: 0.72;
+  }
+}
+
+@keyframes focus-backdrop-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes focus-surface-out {
+  to {
+    transform: translate(var(--focus-translate-x), var(--focus-translate-y))
+      scale(var(--focus-scale-x), var(--focus-scale-y));
+    opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .backdrop,
+  .surface {
+    animation-duration: 1ms;
+  }
+}
+
+@media (forced-colors: active) {
+  .backdrop {
+    backdrop-filter: none;
+    background: Canvas;
+    opacity: 0.8;
+  }
+}

apps/nextjs/src/components/board/advanced-focus/context.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Box, Portal, RemoveScroll } from "@mantine/core";
+
+import { useEditMode } from "@homarr/boards/edit-mode";
+
+import classes from "./advanced-focus.module.css";
+import { isEscapeOwnedByNestedOverlay } from "./escape";
+import type { FocusRect } from "./geometry";
+
+interface ActiveFocus {
+  itemId: string;
+  source: HTMLElement;
+  sourceRect: FocusRect;
+  pinned: boolean;
+  autofocusClose: boolean;
+  phase: "visible" | "closing";
+}
+
+interface AdvancedFocusContextValue {
+  active: ActiveFocus | null;
+  open: (itemId: string, source: HTMLElement, pinned?: boolean) => void;
+  close: (restoreFocus?: boolean) => void;
+  dismiss: (itemId: string) => void;
+  pin: (autofocusClose?: boolean) => void;
+  hover: (itemId: string, source: HTMLElement) => void;
+  leave: (itemId: string) => void;
+}
+
+const AdvancedFocusContext = createContext<AdvancedFocusContextValue | null>(null);
+const HOVER_DELAY_MS = 150;
+const CLOSE_DURATION_MS = 180;
+
+const isEditableTarget = (target: EventTarget | null) =>
+  target instanceof HTMLElement &&
+  (target.matches("input, textarea, select, [contenteditable='true']") || target.isContentEditable);
+
+export const BoardAdvancedFocusProvider = ({ children }: PropsWithChildren) => {
+  const [isEditMode] = useEditMode();
+  const [active, setActive] = useState<ActiveFocus | null>(null);
+  const activeRef = useRef<ActiveFocus | null>(null);
+  const hoveredRef = useRef<{ itemId: string; source: HTMLElement } | null>(null);
+  const shiftHeldRef = useRef(false);
+  const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelHoverTimer = useCallback(() => {
+    if (hoverTimerRef.current === null) return;
+    clearTimeout(hoverTimerRef.current);
+    hoverTimerRef.current = null;
+  }, []);
+
+  const updateActive = useCallback((next: ActiveFocus | null) => {
+    activeRef.current = next;
+    setActive(next);
+  }, []);
+
+  const cancelCloseTimer = useCallback(() => {
+    if (closeTimerRef.current === null) return;
+    clearTimeout(closeTimerRef.current);
+    closeTimerRef.current = null;
+  }, []);
+
+  const open = useCallback(
+    (itemId: string, source: HTMLElement, pinned = false) => {
+      if (isEditMode) return;
+      cancelHoverTimer();
+      cancelCloseTimer();
+      const rect = source.getBoundingClientRect();
+      updateActive({
+        itemId,
+        source,
+        sourceRect: { left: rect.left, top: rect.top, width: rect.width, height: rect.height },
+        pinned,
+        autofocusClose: pinned,
+        phase: "visible",
+      });
+    },
+    [cancelCloseTimer, cancelHoverTimer, isEditMode, updateActive],
+  );
+
+  const close = useCallback(
+    (restoreFocus = true) => {
+      cancelHoverTimer();
+      const current = activeRef.current;
+      if (!current || current.phase === "closing") return;
+      updateActive({ ...current, phase: "closing" });
+      const closeDuration = window.matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : CLOSE_DURATION_MS;
+      closeTimerRef.current = setTimeout(() => {
+        closeTimerRef.current = null;
+        updateActive(null);
+        if (restoreFocus && current.source.isConnected) requestAnimationFrame(() => current.source.focus());
+      }, closeDuration);
+    },
+    [cancelHoverTimer, updateActive],
+  );
+
+  const startHoverTimer = useCallback(() => {
+    cancelHoverTimer();
+    const hovered = hoveredRef.current;
+    if (!hovered || !shiftHeldRef.current || activeRef.current) return;
+    hoverTimerRef.current = setTimeout(() => open(hovered.itemId, hovered.source), HOVER_DELAY_MS);
+  }, [cancelHoverTimer, open]);
+
+  const hover = useCallback(
+    (itemId: string, source: HTMLElement) => {
+      hoveredRef.current = { itemId, source };
+      startHoverTimer();
+    },
+    [startHoverTimer],
+  );
+
+  const leave = useCallback(
+    (itemId: string) => {
+      if (hoveredRef.current?.itemId === itemId) hoveredRef.current = null;
+      cancelHoverTimer();
+    },
+    [cancelHoverTimer],
+  );
+
+  const dismiss = useCallback(
+    (itemId: string) => {
+      if (activeRef.current?.itemId !== itemId) return;
+      cancelHoverTimer();
+      cancelCloseTimer();
+      updateActive(null);
+    },
+    [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) {
+        const advancedSurface = document.querySelector(`.${classes.surface}`);
+        if (event.defaultPrevented || event.isComposing || isEscapeOwnedByNestedOverlay(event.target, advancedSurface))
+          return;
+        event.preventDefault();
+        close();
+        return;
+      }
+      if (isEditMode) return;
+      if (event.key !== "Shift" || event.repeat || isEditableTarget(event.target)) return;
+      if (activeRef.current?.pinned) return;
+      shiftHeldRef.current = true;
+      startHoverTimer();
+    };
+    const handleKeyUp = (event: KeyboardEvent) => {
+      if (event.key !== "Shift") return;
+      shiftHeldRef.current = false;
+      cancelHoverTimer();
+      if (activeRef.current && !activeRef.current.pinned) close(false);
+    };
+    const handleBlur = () => {
+      shiftHeldRef.current = false;
+      cancelHoverTimer();
+      if (activeRef.current && !activeRef.current.pinned) close(false);
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    window.addEventListener("keyup", handleKeyUp);
+    window.addEventListener("blur", handleBlur);
+    return () => {
+      window.removeEventListener("keydown", handleKeyDown);
+      window.removeEventListener("keyup", handleKeyUp);
+      window.removeEventListener("blur", handleBlur);
+      cancelHoverTimer();
+      cancelCloseTimer();
+    };
+  }, [cancelCloseTimer, cancelHoverTimer, close, isEditMode, startHoverTimer]);
+
+  useEffect(() => {
+    if (isEditMode && activeRef.current) close(false);
+  }, [close, isEditMode]);
+
+  const value = useMemo(
+    () => ({ active, open, close, dismiss, pin, hover, leave }),
+    [active, close, dismiss, hover, leave, open, pin],
+  );
+
+  return (
+    <AdvancedFocusContext.Provider value={value}>
+      <RemoveScroll enabled={active !== null} className={classes.focusScope}>
+        {children}
+      </RemoveScroll>
+      {active && (
+        <Portal>
+          <Box
+            className={`${classes.backdrop} ${active.phase === "closing" ? classes.backdropClosing : ""}`}
+            onPointerDown={() => close()}
+            aria-hidden
+          />
+        </Portal>
+      )}
+    </AdvancedFocusContext.Provider>
+  );
+};
+
+export const useAdvancedFocus = () => {
+  const context = useContext(AdvancedFocusContext);
+  if (!context) throw new Error("useAdvancedFocus must be used within BoardAdvancedFocusProvider");
+  return context;
+};

apps/nextjs/src/components/board/advanced-focus/escape.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "vitest";
+
+import { isEscapeOwnedByNestedOverlay } from "./escape";
+
+describe("isEscapeOwnedByNestedOverlay", () => {
+  test("allows Escape from the advanced surface itself", () => {
+    const surface = document.createElement("section");
+    surface.setAttribute("role", "dialog");
+    const button = document.createElement("button");
+    surface.append(button);
+
+    expect(isEscapeOwnedByNestedOverlay(button, surface)).toBe(false);
+  });
+
+  test("leaves Escape to a nested Mantine modal", () => {
+    const surface = document.createElement("section");
+    surface.setAttribute("role", "dialog");
+    const modal = document.createElement("section");
+    modal.setAttribute("role", "dialog");
+    const input = document.createElement("input");
+    modal.append(input);
+
+    expect(isEscapeOwnedByNestedOverlay(input, surface)).toBe(true);
+  });
+
+  test.each(["menu", "listbox"])("leaves Escape to a nested %s overlay", (role) => {
+    const surface = document.createElement("section");
+    surface.setAttribute("role", "dialog");
+    const overlay = document.createElement("div");
+    overlay.setAttribute("role", role);
+    const target = document.createElement("button");
+    overlay.append(target);
+
+    expect(isEscapeOwnedByNestedOverlay(target, surface)).toBe(true);
+  });
+
+  test("honors Mantine's stop-propagation marker for menus and comboboxes", () => {
+    const surface = document.createElement("section");
+    surface.setAttribute("role", "dialog");
+    const target = document.createElement("button");
+    target.setAttribute("data-mantine-stop-propagation", "true");
+    surface.append(target);
+
+    expect(isEscapeOwnedByNestedOverlay(target, surface)).toBe(true);
+  });
+
+  test("does not mistake the compact widget source for a nested overlay", () => {
+    const surface = document.createElement("section");
+    surface.setAttribute("role", "dialog");
+    const source = document.createElement("button");
+
+    expect(isEscapeOwnedByNestedOverlay(source, surface)).toBe(false);
+  });
+});

apps/nextjs/src/components/board/advanced-focus/escape.ts

@@ -0,0 +1,13 @@
+const escapeOwnerSelector = [
+  '[data-mantine-stop-propagation="true"]',
+  '[role="dialog"]',
+  '[role="menu"]',
+  '[role="listbox"]',
+].join(", ");
+
+export const isEscapeOwnedByNestedOverlay = (target: EventTarget | null, advancedSurface: Element | null) => {
+  if (!(target instanceof Element)) return false;
+
+  const escapeOwner = target.closest(escapeOwnerSelector);
+  return escapeOwner !== null && escapeOwner !== advancedSurface;
+};

apps/nextjs/src/components/board/advanced-focus/geometry.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { getAdvancedFocusRect } from "./geometry";
+
+describe("getAdvancedFocusRect", () => {
+  it("expands a widget and keeps it inside the viewport", () => {
+    expect(getAdvancedFocusRect({ left: 10, top: 10, width: 300, height: 200 }, { width: 1200, height: 800 })).toEqual({
+      left: 240,
+      top: 190,
+      width: 720,
+      height: 480,
+    });
+  });
+
+  it("uses the available viewport on small screens", () => {
+    expect(getAdvancedFocusRect({ left: 0, top: 0, width: 400, height: 500 }, { width: 390, height: 700 })).toEqual({
+      left: 8,
+      top: 68,
+      width: 374,
+      height: 624,
+    });
+  });
+
+  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 });
+
+    expect(rect.top).toBeGreaterThanOrEqual(84);
+    expect(rect.top + rect.height).toBeLessThanOrEqual(744);
+  });
+});

apps/nextjs/src/components/board/advanced-focus/geometry.ts

@@ -0,0 +1,26 @@
+import { appShellHeaderHeight } from "../../layout/constants";
+
+export interface FocusRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export const getAdvancedFocusRect = (source: FocusRect, viewport: { width: number; height: number }): FocusRect => {
+  const margin = viewport.width < 640 ? 8 : 24;
+  const availableWidth = Math.max(0, viewport.width - margin * 2);
+  const availableHeight = Math.max(0, viewport.height - appShellHeaderHeight - margin * 2);
+  const width = Math.min(availableWidth, Math.max(source.width, Math.min(960, source.width * 2.4)));
+  const height = Math.min(availableHeight, Math.max(source.height, Math.min(720, source.height * 2.4)));
+
+  return {
+    left: Math.max(margin, (viewport.width - width) / 2),
+    top: Math.max(
+      appShellHeaderHeight + margin,
+      appShellHeaderHeight + (viewport.height - appShellHeaderHeight - height) / 2,
+    ),
+    width,
+    height,
+  };
+};