feat: modernize dashboard widgets

PRODUCT.md

@@ -0,0 +1,36 @@
+# Product
+
+## Register
+
+product
+
+## Users
+
+Homarr is for experienced self-hosters, homelab operators, and administrators who run several services and want one dashboard for monitoring and operating them. They understand technical data, value density, and spend time tuning dashboards to match their own workflows.
+
+## Product Purpose
+
+Homarr brings status, data, and safe day-to-day controls from self-hosted services into one customizable dashboard. Success means users can inspect problems, act on services, and reshape their workspace without repeatedly leaving the board.
+
+## Brand Personality
+
+Capable, precise, configurable. Homarr should feel calm under load, direct about system state, and rewarding to experts who refine details.
+
+## Anti-references
+
+- Consumer dashboards that hide useful detail behind simplified scores.
+- Decorative glass, oversized metric cards, and motion without state meaning.
+- Rigid layouts that force one workflow or require leaving the dashboard for routine actions.
+- Clever custom controls where familiar platform or Mantine interactions already work.
+
+## Design Principles
+
+- Preserve expert depth while prioritizing the most urgent information at small sizes.
+- Make routine inspection, filtering, configuration, and safe actions available from the board.
+- Reveal dense workspaces progressively through a consistent advanced focus mode.
+- Treat personalization as a core workflow, not a settings afterthought.
+- Show loading, stale, partial, empty, and failed states truthfully without discarding valid data.
+
+## Accessibility & Inclusion
+
+Target WCAG AA. Every pointer interaction needs a keyboard and coarse-pointer path. Focus must be visible and restored after overlays close. Motion must respect reduced-motion preferences, and status must never rely on color alone.

apps/docs/docs/advanced/keyboard-shortcuts/index.mdx

@@ -6,16 +6,23 @@ tags:
 
 Homarr has the following keyboard shortcuts:
 
-| Shortcut | Description |
-| -------- | ----------- |
-| `MOD` + `K` | Opens the search bar |
-| `MOD` + `J` | Toggles Dark Mode |
-| `MOD` + `E` | Toggles Edit Mode |
+| Shortcut                                   | Description                                                |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| `MOD` + `K`                                | Opens the search bar                                       |
+| `MOD` + `J`                                | Toggles Dark Mode                                          |
+| `MOD` + `E`                                | Toggles Edit Mode                                          |
+| Hold `Shift` while hovering a widget       | Opens its temporary advanced view                          |
+| `Shift` + `Enter` on a focused widget      | Opens and pins its advanced view                           |
+| `Esc`                                      | Closes an open advanced view or board menu                 |
+| `Shift` + `F10` on a focused board section | Opens the precise add-item menu at the next available cell |
 
 :::tip
 
 Here `MOD` refers to the modifier key, which is `Ctrl` on Windows and `Cmd` on macOS.
 
+Advanced view and precise placement are available outside edit mode. Precise placement still requires permission to
+change the board and the right-click interaction preference to be enabled.
+
 :::
 
 :::note

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -54,11 +54,7 @@ You must choose a username and password (both can later be changed).
 We enforce strict password requirements when you enter your password to protect your instance if you accidentally
 expose it to the internet.
 
-<img
-  src={imageStartFromScratchStepAdminUser}
-  alt={"Screenshot form to create admin user"}
-  width={300}
-/>
+<img src={imageStartFromScratchStepAdminUser} alt={"Screenshot form to create admin user"} width={300} />
 
 If you selected external providers (such as LDAP or OIDC), you'll be prompted to create an admin group.
 This group will be used to synchronize users from your provider to Homarr.
@@ -116,22 +112,14 @@ The onboarding can no longer be started again.
 From here you can click on one of the provided links to continue your journey.
 We recommend you to continue with the section [creating your first board on this page](#creating-your-first-board).
 
-<img
-  src={imageStartFromScratchStepFinish}
-  alt={"Screenshot of the finish onboarding process with links"}
-  width={300}
-/>
+<img src={imageStartFromScratchStepFinish} alt={"Screenshot of the finish onboarding process with links"} width={300} />
 
 ### Importing a ZIP from version before 1.0.0
 
 This is recommended when you used Homarr before and want to re-import your data.
 It is important that you first migrate correctly using [the list of breaking changes for 1.0](/blog/2024/09/23/version-1.0).
 
-<img
-  src={manageExportOldHomarr}
-  alt="Export from old Homarr"
-  style={{ maxWidth: 500 }}
-/>
+<img src={manageExportOldHomarr} alt="Export from old Homarr" style={{ maxWidth: 500 }} />
 
 **How to export and import data**
 
@@ -197,38 +185,29 @@ Here you have the following options in the header:
 
 When entering the edit mode, you'll get some additional buttons to work with:
 
-<img
-  src={manageBoardHeaderEditMode}
-  alt={"Screenshot of buttons in the edit mode"}
-  width={200}
-/>
+<img src={manageBoardHeaderEditMode} alt={"Screenshot of buttons in the edit mode"} width={200} />
 
 - **Add item**: Click this button to add new elements to your page.
-- **Exit edit mode**: Click this btuton to save your changes and exit edit mode.
+- **Exit edit mode**: Click this button to save your changes and exit edit mode.
+
+Outside edit mode, right-click a widget for its live status, refresh, settings, quick options, and supported actions.
+Hold `Shift` while hovering a widget for a temporary advanced view; use its pin control to keep it open. You can also
+focus the widget and press `Shift` + `Enter` to open it pinned. If you can change the board, right-click empty grid
+space to add an item at that position.
+On a touch device, touch and hold empty grid space for the same precise-placement menu.
 
 To continue, click the option "New Item":
 
-<img
-  src={manageBoardHeaderAddItem}
-  alt={"Screenshot of the add item menu"}
-  width={200}
-/>
+<img src={manageBoardHeaderAddItem} alt={"Screenshot of the add item menu"} width={200} />
 
 Next, you can choose what item you'd like to add.
 We will discuss the other options in the following sections - for now choose "App" to continue.
 
-<img
-  src={manageBoardHeaderChooseItem}
-  alt={"Screenshot of choosing the app item in the modal"}
-  width={300}
-/>
+<img src={manageBoardHeaderChooseItem} alt={"Screenshot of choosing the app item in the modal"} width={300} />
 
 As soon as you chose the app, the modal will close and you'll get the following item on your board:
 
-<img
-  src={manageBoardNoApp}
-  alt="Screenshot of the No app element on the board"
-/>
+<img src={manageBoardNoApp} alt="Screenshot of the No app element on the board" />
 
 This is expected, because you haven't told Homarr what app it should show in this item.
 To configure this, click on the small 3 dots at the top of the item in the edit mode and choose "Edit item" in the menu.

apps/docs/docs/management/boards/index.mdx

@@ -9,11 +9,11 @@ tags:
   - Layout
 ---
 
-import iconColorImage from './img/icon-color.png'
-import itemRadiusImage from './img/item-radius.png'
-import layoutLargeImage from './img/layout-large.png'
-import layoutMediumImage from './img/layout-medium.png'
-import layoutSmallImage from './img/layout-small.png'
+import iconColorImage from "./img/icon-color.png";
+import itemRadiusImage from "./img/item-radius.png";
+import layoutLargeImage from "./img/layout-large.png";
+import layoutMediumImage from "./img/layout-medium.png";
+import layoutSmallImage from "./img/layout-small.png";
 
 Each dashboard is called a "board".
 You can create as many boards as you want.
@@ -24,24 +24,29 @@ Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home)
 Names of boards must be unique because this will be used in the URL to load the desired board.
 
 ## Create a new board
+
 When creating a board, the availability of the board name will be checked for you.
 
 ![](./img/create-board-modal.png)
 
 ### Name
+
 The name must not include any special characters and must be at least one character long.
 Underscores and hyphen-minus are allowed.
 
 ### Column count
+
 Homarr has a complex drag and drop system that can be used from the browser.
 The column count defines how many horizontal columns are available to drag and drop elements to.
 
 ### Public
+
 This will enable public access for everyone - regardless of whether they are logged in or not.
 This can be really useful if you want to have public boards in your company or for family and fiends.
 Modifications for public boards must be allowed explicitly using user groups and their permissions.
 
 ## Board settings
+
 You navigate to the board settings by clicking on these three dots:
 
 ![](./img/navigate-to-settings.png)
@@ -51,7 +56,9 @@ Alternatively, you can also navigate from the board page itself using the cog ic
 ![](./img/navigate-to-settings-2.png)
 
 ### General
+
 #### Page title
+
 This is the title that will be visible at the top left in the navigation bar:
 
 ![](./img/page-title.png)
@@ -59,6 +66,7 @@ This is the title that will be visible at the top left in the navigation bar:
 This field is optional and Homarr will fall back to "Homarr" if nothing is set.
 
 #### Meta title
+
 This is the secondary title of the page that is not directly visible in the page itself.
 Browser will use it to set the title of tabs:
 
@@ -67,10 +75,12 @@ Browser will use it to set the title of tabs:
 Homarr will fall back to the board name and a suffix if nothing is set.
 
 #### Logo image URL
+
 This is the URL that is used for the image at the top left.
 Homarr will fall back to the Homarr logo if nothing is set.
 
 #### Favicon image URL
+
 This is the URL that is used for the favicon in the tab title.
 Homarr will fall back to the Homarr logo if nothing is set.
 
@@ -80,9 +90,10 @@ In this section you can configure the different responsive layouts. Depending on
 
 ![](./img/layout-settings.png)
 
-On each element the position and size of items can be changed seperately.
+On each element the position and size of items can be changed separately.
 When adding a new layout the position and sizes will automatically be generated depending on the column count.
-When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position.
+New widgets use their default size and the first available position on each layout. Adding from an empty grid cell anchors
+the widget near that cell on the active layout; Homarr still chooses safe free positions for the other responsive layouts.
 
 #### Name
 
@@ -94,51 +105,65 @@ Amount of columns for this layout. Defines how many items can be placed in a row
 
 #### Breakpoint
 
-Minimum width of the screen where the layout will be used. 
+Minimum width of the screen where the layout will be used.
 Once the minmum of the next layout is reached the layout will change.
 
 #### Preview
 
-<img src={layoutSmallImage}  height={256} />
-<img src={layoutMediumImage}  height={256} />
-<img src={layoutLargeImage}  height={256} />
+<img src={layoutSmallImage} height={256} />
+<img src={layoutMediumImage} height={256} />
+<img src={layoutLargeImage} height={256} />
 
 ### Background
+
 #### Background image URL
+
 Homarr can display a background image behind apps and widgets.
 This URL can be used to define what image should be shown.
 
 #### Background image attachment
+
 This defines whether the background should move when the user scrolls.
 
 #### Background image size
+
 This defines whether the background should cover the entire page (and possibly be cropped) or never be cropped but may not cover the entire page.
 
 #### Background image repeat
+
 This defines whether the background should be repeated if it cannot cover the entire page.
 This option can be useful if you have patterns that can be repeated easily (e.g. patterns):
 
 ![](./img/background-repeat.png)
 
 ### Appearance
+
 #### Primary color
+
 Color that can be chosen freely to give accents to active elements.
+
 #### Secondary color
+
 Color that can be chosen freely to give accents.
+
 #### Opacity
+
 Opacity of the colors.
+
 #### Icon color
+
 Change the color of your bookmark / app icons.
 
-<img src={iconColorImage}  height={100} />
+<img src={iconColorImage} height={100} />
 
 #### Item radius
+
 Change the radius of your items / categories.
 
-<img src={itemRadiusImage}  height={100} />
-
+<img src={itemRadiusImage} height={100} />
 
 ### Custom CSS
+
 This is the field where you can enter custom CSS.
 The styling will only be applied on the respective board page.
 
@@ -147,14 +172,29 @@ The styling will only be applied on the respective board page.
 ### Behaviour
 
 #### Disable app status
+
 This will disable the status check for apps.
 
+#### Work directly from the board
+
+Widgets expose their routine controls without requiring edit mode:
+
+- Hold `Shift` while hovering a widget for a temporary advanced view, then use its pin control to keep it open. Focus
+  the widget and press `Shift` + `Enter` to open it pinned, or use the maximize control on touch devices.
+- Right-click a widget to inspect its live query status, refresh its data, change quick options, open settings, or run
+  supported actions. Available controls follow your board and integration permissions.
+- If you can modify the board, right-click or touch and hold an empty grid cell to add an item there. Focus a board
+  section and press `Shift` + `F10` for the keyboard equivalent.
+
+Widget and empty-space context menus follow the **Enable right click on widgets** preference in your user settings.
+
 ### Access control
+
 With the access control, you can permit a single user or a group to your board.
 The users and groups can have one of these three levels of access:
 
 | **Permission Level** | View board | Edit mode | Settings | Danger zone (eg. delete) |
-|----------------------|------------|-----------|----------|--------------------------|
+| -------------------- | ---------- | --------- | -------- | ------------------------ |
 | View board           | X          |           |          |                          |
 | Modify board         | X          | X         | X        |                          |
 | Full access          | X          | X         | X        | X                        |
@@ -173,18 +213,23 @@ After editing permissions, the save button below the table must be pressed.
 Otherwise, all changes will be discarded.
 
 ### Danger zone
+
 #### Rename
+
 Renaming a board will break all existing links to it permanently with no redirect.
 
 #### Board visibility
+
 By default, boards will be private. This means only authenticated users that are authorized have access.
 Making a board public will expose it to everyone - including unauthenticated users.
 
 #### Delete
+
 This will permanently delete the board.
 This action is irreversible and cannot be undone.
 
 ## Delete boards
+
 The deletion of boards is permanent and cannot be undone.
 There are two ways to delete a board:
 
@@ -196,7 +241,7 @@ Both actions will execute the same deletion process.
 ## Duplicate boards
 
 :::note
-Duplicating a board will not copy the users and groups that have access to the board 
+Duplicating a board will not copy the users and groups that have access to the board
 nor the integrations the user does not have access to.
 :::
 
@@ -206,47 +251,51 @@ You can duplicate a board by clicking on the three dots in the list of boards an
 ![](./img/duplicate-board-modal.png)
 
 ## Setting boards as your home board
+
 The home board is the dashboard, that will be shown at the root path of Homarr or if no board name was passed in the URL.
 All the following paths will lead to the home board:
-- ``my-homarr.com``
-- ``my-homarr.com/boards``
+
+- `my-homarr.com`
+- `my-homarr.com/boards`
 
 Your home board will have a special small badge at the top right in the list of boards:
 
 ![](./img/home-board-flag.png)
 
 ### For yourself
+
 To set the home board yourself, the easiest option is to set it directly in the list of boards:
 
 ![](./img/set-as-home-board-menu.png)
 
 Alternatively, you can also define it via your user profile:
+
 1. Click on your user profile at the top right
-2. Click on ``Your preferences``
-3. Change the home board in the ``home board`` dropdown and click on ``Save``.
+2. Click on `Your preferences`
+3. Change the home board in the `home board` dropdown and click on `Save`.
 
 ### For other users
 
-1. Navigate to the users: ``Management`` > ``Users`` > ``Manage``
+1. Navigate to the users: `Management` > `Users` > `Manage`
 2. Click on the username of the user that you want to adjust
-3. Select the desired home board via the dropdown and click on ``Save`` \
-![](./img/set-home-board-other-user.png)
+3. Select the desired home board via the dropdown and click on `Save` \
+   ![](./img/set-home-board-other-user.png)
 
 ### For user groups
 
-1. Navigate to the user groups: ``Management`` > ``Users`` > ``Groups`` > ``Manage``
-2. Go to tab ``Settings``
-3. Select the desired home board via the dropdown and click on ``Save`` \
-![](./img/set-home-board-user-group.png)
+1. Navigate to the user groups: `Management` > `Users` > `Groups` > `Manage`
+2. Go to tab `Settings`
+3. Select the desired home board via the dropdown and click on `Save` \
+   ![](./img/set-home-board-user-group.png)
 
 ### For whole server
 
 You can also set a global home board that will be used for all users that have not set a home board themselves.
 It will also be used for anonymous users.
 
-1. Navigate to the settings: ``Management`` > ``Settings`` > ``Boards``
-2. Select the desired home board via the dropdown and click on ``Save`` \
-![](./img/set-home-board-global.png)
+1. Navigate to the settings: `Management` > `Settings` > `Boards`
+2. Select the desired home board via the dropdown and click on `Save` \
+   ![](./img/set-home-board-global.png)
 
 :::note
 For the global home board you can only select boards that are public.
@@ -255,4 +304,4 @@ For the global home board you can only select boards that are public.
 ### Mobile home board
 
 Same as the home board, you can also set a mobile home board.
-It will be used for devices that are detected as mobile devices. (Using User-Agent header)
+It will be used for devices that are detected as mobile devices. (Using User-Agent header)

apps/docs/docs/widgets/anchor-note/index.mdx

@@ -1,35 +1,37 @@
 ---
-title: 'Anchor Note'
-description: 'Display and edit a selected note from Anchor'
+title: "Anchor Note"
+description: "Display and edit a selected note from Anchor"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { anchorNoteWidget } from '.';
-import { anchorIntegration } from '@site/docs/integrations/anchor';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { anchorNoteWidget } from ".";
+import { anchorIntegration } from "@site/docs/integrations/anchor";
 
-<WidgetHeader
-  widget={anchorNoteWidget}
-  categories={['Notes']}
-/>
+<WidgetHeader widget={anchorNoteWidget} categories={["Notes"]} />
 
 The Anchor Note widget shows a selected note from your Anchor integration. If your note permissions allow it, you can also edit the note title and content directly in Homarr.
 
 ### Screenshots
 
-import anchorNoteWidgetScreenshot from './img/widget.png';
+import anchorNoteWidgetScreenshot from "./img/widget.png";
 
 <img src={anchorNoteWidgetScreenshot} alt="anchor-note-widget" width={256} height={256} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: anchorIntegration
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: anchorIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
@@ -37,6 +39,8 @@ import anchorNoteWidgetScreenshot from './img/widget.png';
 - Click **Save** to persist changes to Anchor.
 - Click **Cancel** to discard unsaved changes.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/app/index.mdx

@@ -1,37 +1,38 @@
 ---
-title: 'App'
-description: 'Embeds an app into the board.'
+title: "App"
+description: "Embeds an app into the board."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { appWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { appWidget } from ".";
 
-<WidgetHeader
-  widget={appWidget}
-  categories={['Links', 'Apps']}
-/>
+<WidgetHeader widget={appWidget} categories={["Links", "Apps"]} />
 
 The app widget allows you to add a link to an application or a website that you want to access quickly from your Homarr board.
 It also supports a status check to indicate whether Homarr can reach the application or website.
 
 ### Screenshots
 
-import githubApp from './img/github.png';
-import jellyseerrApp from './img/jellyseerr-description-tooltip.png';
-import piHoleApp from './img/pi-hole-ping-icon.png';
+import githubApp from "./img/github.png";
+import jellyseerrApp from "./img/jellyseerr-description-tooltip.png";
+import piHoleApp from "./img/pi-hole-ping-icon.png";
 
-<div className='flex gap-1'>
+<div className="flex gap-1">
   <img src={githubApp} alt="app github with-status-check" width={128 * 1.5} height={128 * 1.5} />
   <img src={piHoleApp} alt="app pi-hole with-status-check status-check-icon" width={128 * 1.5} height={128 * 1.5} />
   <img src={jellyseerrApp} alt="app jellyseerr with-description-tooltip" height={128 * 1.5} />
 </div>
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={appWidget.configuration} />

apps/docs/docs/widgets/archive-team-warrior/index.mdx

@@ -0,0 +1,38 @@
+---
+title: "ArchiveTeam Warrior"
+description: "Monitor ArchiveTeam Warrior status, projects, bandwidth, and active archival jobs."
+hide_title: true
+---
+
+import { archiveTeamWarriorIntegration } from "@site/docs/integrations/archiveteam-warrior";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+import { archiveTeamWarriorWidget } from ".";
+
+<WidgetHeader widget={archiveTeamWarriorWidget} categories={["Archiving", "Monitoring"]} />
+
+Use this widget to see what your ArchiveTeam Warrior is preserving without leaving Homarr. The compact view keeps the current project, runner state, job counts, bandwidth, and broadcast message visible. Advanced view adds the complete active-job list and exact update time.
+
+### Supported integration
+
+<WidgetIntegrations
+  items={[
+    {
+      integration: archiveTeamWarriorIntegration,
+      note: "Shows status and active archival work from one Warrior instance",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={archiveTeamWarriorWidget.configuration} />

apps/docs/docs/widgets/archive-team-warrior/index.ts

@@ -0,0 +1,19 @@
+import type { WidgetDefinition } from "@site/src/types";
+import { IconArchive } from "@tabler/icons-react";
+
+export const archiveTeamWarriorWidget: WidgetDefinition = {
+  icon: IconArchive,
+  name: "ArchiveTeam Warrior",
+  description: "Monitor ArchiveTeam Warrior status, projects, bandwidth, and active archival jobs.",
+  path: "../../widgets/archive-team-warrior",
+  configuration: {
+    items: [
+      {
+        name: "Show broadcast message",
+        description: "Show the message broadcast by the selected Warrior project when space allows.",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+    ],
+  },
+};

apps/docs/docs/widgets/audio-stats/index.mdx

@@ -4,6 +4,8 @@ description: "Displays media and listening statistics from Navidrome or Audioboo
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -36,6 +38,8 @@ Only options relevant to your linked integration are shown in the configuration
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/bazarr/index.mdx

@@ -1,26 +1,25 @@
 ---
-title: 'Bazarr'
-description: 'Displays missing subtitle counts and health indicators from your Bazarr instance.'
+title: "Bazarr"
+description: "Displays missing subtitle counts and health indicators from your Bazarr instance."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { bazarrWidget } from '.';
-import { bazarrIntegration } from '@site/docs/integrations/bazarr';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={bazarrWidget}
-  categories={['Subtitles', 'Media']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { bazarrWidget } from ".";
+import { bazarrIntegration } from "@site/docs/integrations/bazarr";
+
+<WidgetHeader widget={bazarrWidget} categories={["Subtitles", "Media"]} />
 
 This widget shows subtitle status from your Bazarr instance, including missing episode and movie subtitles, provider issues, and health warnings.
 
 ### Screenshots
 
-import widgetOverview from './img/widget-overview.png';
+import widgetOverview from "./img/widget-overview.png";
 
 <div className="flex flex-col gap-2">
   <img src={widgetOverview} alt="bazarr-widget-overview" width={128 * 4} />
@@ -28,14 +27,21 @@ import widgetOverview from './img/widget-overview.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: bazarrIntegration,
-  note: "Displays missing subtitle counts and health indicators"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: bazarrIntegration,
+      note: "Displays missing subtitle counts and health indicators",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={bazarrWidget.configuration} />

apps/docs/docs/widgets/beszel-alerts/index.mdx

@@ -1,22 +1,21 @@
 ---
-title: 'Beszel Alerts'
-description: 'View Beszel alert configurations and history with triggered/ok status indicators.'
+title: "Beszel Alerts"
+description: "View Beszel alert configurations and history with triggered/ok status indicators."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { beszelAlertsWidget } from '.';
-import { beszelIntegration } from '@site/docs/integrations/beszel';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-import beszelAlerts from './img/beszel-alerts.png';
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { beszelAlertsWidget } from ".";
+import { beszelIntegration } from "@site/docs/integrations/beszel";
 
-<WidgetHeader
-  widget={beszelAlertsWidget}
-  categories={['System Monitoring', 'Alerts']}
-/>
+import beszelAlerts from "./img/beszel-alerts.png";
+
+<WidgetHeader widget={beszelAlertsWidget} categories={["System Monitoring", "Alerts"]} />
 
 This widget displays your Beszel alert configurations separated by status (triggered and ok). It also shows alert history with timestamps. Alerts are updated in real time via WebSocket subscriptions.
 
@@ -26,14 +25,21 @@ This widget displays your Beszel alert configurations separated by status (trigg
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: beszelIntegration,
-  note: "Displays alert configurations and trigger history"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: beszelIntegration,
+      note: "Displays alert configurations and trigger history",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={beszelAlertsWidget.configuration} />

apps/docs/docs/widgets/beszel-system-grid/index.mdx

@@ -1,22 +1,21 @@
 ---
-title: 'Beszel Systems (Grid)'
-description: 'Card grid view of all Beszel-monitored systems with real-time metrics.'
+title: "Beszel Systems (Grid)"
+description: "Card grid view of all Beszel-monitored systems with real-time metrics."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { beszelSystemGridWidget } from '.';
-import { beszelIntegration } from '@site/docs/integrations/beszel';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-import beszelSystemGrid from './img/beszel-system-grid.png';
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { beszelSystemGridWidget } from ".";
+import { beszelIntegration } from "@site/docs/integrations/beszel";
 
-<WidgetHeader
-  widget={beszelSystemGridWidget}
-  categories={['System Monitoring']}
-/>
+import beszelSystemGrid from "./img/beszel-system-grid.png";
+
+<WidgetHeader widget={beszelSystemGridWidget} categories={["System Monitoring"]} />
 
 This widget displays all your Beszel-monitored systems as a responsive card grid. Each card shows real-time metrics like CPU, memory, disk, network, temperature, and more. Cards adapt their layout based on available space. If Beszel reports multiple filesystems, the disk bar exposes a hover breakdown for the root disk and each extra mount.
 
@@ -28,14 +27,21 @@ Select a system card to open the complete statistics view, including system, fil
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: beszelIntegration,
-  note: "Displays all monitored systems as a card grid"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: beszelIntegration,
+      note: "Displays all monitored systems as a card grid",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={beszelSystemGridWidget.configuration} />

apps/docs/docs/widgets/beszel-system-stats/index.mdx

@@ -4,6 +4,8 @@ description: "Time-series charts for CPU, memory, disk, network, and Docker cont
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -32,6 +34,8 @@ This widget displays time-series charts for a selected Beszel system, including
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/beszel-system-table/index.mdx

@@ -1,21 +1,19 @@
 ---
-title: 'Beszel Systems (Table)'
-description: 'Table view of all Beszel-monitored systems with sortable columns and status indicators.'
+title: "Beszel Systems (Table)"
+description: "Table view of all Beszel-monitored systems with sortable columns and status indicators."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { beszelSystemTableWidget } from '.';
-import { beszelIntegration } from '@site/docs/integrations/beszel';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { beszelSystemTableWidget } from ".";
+import { beszelIntegration } from "@site/docs/integrations/beszel";
 
-<WidgetHeader
-  widget={beszelSystemTableWidget}
-  categories={['System Monitoring']}
-/>
+<WidgetHeader widget={beszelSystemTableWidget} categories={["System Monitoring"]} />
 
 This widget displays all your Beszel-monitored systems in a sortable data table. Each row shows system metrics like CPU, memory, disk, network, temperature, and more. Columns can be toggled on or off, and the table supports sorting by any column. When Beszel reports extra filesystems, the disk column adds a hover breakdown for each mount alongside the root disk.
 
@@ -23,14 +21,21 @@ Select a system row to open the complete statistics view, including system, file
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: beszelIntegration,
-  note: "Displays all monitored systems in a sortable table"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: beszelIntegration,
+      note: "Displays all monitored systems in a sortable table",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={beszelSystemTableWidget.configuration} />

apps/docs/docs/widgets/bookmarks/index.mdx

@@ -1,29 +1,27 @@
 ---
-title: 'Bookmarks'
-description: 'Displays multiple app links'
+title: "Bookmarks"
+description: "Displays multiple app links"
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { bookmarksWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { bookmarksWidget } from ".";
 
-<WidgetHeader
-  widget={bookmarksWidget}
-  categories={['Links', 'Apps']}
-/>
+<WidgetHeader widget={bookmarksWidget} categories={["Links", "Apps"]} />
 
 The bookmarks widget allows you to display multiple app links in a single widget.
 You can add links to your favorite applications, websites, or any other resources you want quick access to.
 
 ### Screenshots
 
-import gridIconsOnly from './img/grid-icons-only.png';
-import gridWithTitle from './img/grid-with-title.png';
-import verticalListAll from './img/vertical-list-all.png';
-import vericalListSimple from './img/vertical-list-simple.png';
+import gridIconsOnly from "./img/grid-icons-only.png";
+import gridWithTitle from "./img/grid-with-title.png";
+import verticalListAll from "./img/vertical-list-all.png";
+import vericalListSimple from "./img/vertical-list-simple.png";
 
 <div className='flex gap-1'>
     <div className='flex flex-col gap-1'>
@@ -33,12 +31,15 @@ import vericalListSimple from './img/vertical-list-simple.png';
 
     <img src={gridWithTitle} alt="bookmarks grid with-title" width={256 + 4} height={256 + 4} />
     <img src={verticalListAll} alt="bookmarks vertical-list all-elements" width={128} height={256 + 4} />
+
 </div>
 
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={bookmarksWidget.configuration} />

apps/docs/docs/widgets/calendar/index.mdx

@@ -1,65 +1,73 @@
 ---
-title: 'Calendar'
-description: 'Display events from your integrations in a calendar view within a certain relative time period'
+title: "Calendar"
+description: "Display events from your integrations in a calendar view within a certain relative time period"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { calendarWidget } from '.';
-import { lidarrIntegration } from '@site/docs/integrations/lidarr';
-import { nextcloudIntegration } from '@site/docs/integrations/nextcloud';
-import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant';
-import { radarrIntegration } from '@site/docs/integrations/radarr';
-import { readarrIntegration } from '@site/docs/integrations/readarr';
-import { sonarrIntegration } from '@site/docs/integrations/sonarr';
-import { icalIntegration } from '@site/docs/integrations/ical';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { calendarWidget } from ".";
+import { lidarrIntegration } from "@site/docs/integrations/lidarr";
+import { nextcloudIntegration } from "@site/docs/integrations/nextcloud";
+import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant";
+import { radarrIntegration } from "@site/docs/integrations/radarr";
+import { readarrIntegration } from "@site/docs/integrations/readarr";
+import { sonarrIntegration } from "@site/docs/integrations/sonarr";
+import { icalIntegration } from "@site/docs/integrations/ical";
 
-
-<WidgetHeader
-  widget={calendarWidget}
-  categories={['Media manager', "Servarr"]}
-/>
+<WidgetHeader widget={calendarWidget} categories={["Media manager", "Servarr"]} />
 
 The calendar widget shows a month view of events from different integrations.
 It allows you to view calendar events or upcoming releases from your media managers.
 
 ### Screenshots
 
-import popover from './img/popover.png';
-import withIntegrations from './img/with-integrations.png';
-import withoutIntegrations from './img/without-integrations.png';
+import popover from "./img/popover.png";
+import withIntegrations from "./img/with-integrations.png";
+import withoutIntegrations from "./img/without-integrations.png";
 
-<div className='flex gap-1'>
-    <img src={withIntegrations} alt="calendar with-integrations big-size" width={256 + 4} height={256 + 4} />
-    <div className='flex flex-col gap-1'>
-        <img src={popover} alt="calendar popover-details the-mandalorian" width={128 * 3} height={128} />
-        <img src={withoutIntegrations} alt="calendar without-integrations small-size" width={256} height={128} />
-    </div>
+<div className="flex gap-1">
+  <img src={withIntegrations} alt="calendar with-integrations big-size" width={256 + 4} height={256 + 4} />
+  <div className="flex flex-col gap-1">
+    <img src={popover} alt="calendar popover-details the-mandalorian" width={128 * 3} height={128} />
+    <img src={withoutIntegrations} alt="calendar without-integrations small-size" width={256} height={128} />
+  </div>
 </div>
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: nextcloudIntegration,
-}, {
-  integration: lidarrIntegration,
-}, {
-  integration: radarrIntegration,
-}, {
-  integration: readarrIntegration,
-}, {
-  integration: sonarrIntegration,
-}, {
-  integration: icalIntegration
-}, {
-  integration: homeAssistantIntegration
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: nextcloudIntegration,
+    },
+    {
+      integration: lidarrIntegration,
+    },
+    {
+      integration: radarrIntegration,
+    },
+    {
+      integration: readarrIntegration,
+    },
+    {
+      integration: sonarrIntegration,
+    },
+    {
+      integration: icalIntegration,
+    },
+    {
+      integration: homeAssistantIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
@@ -67,9 +75,12 @@ import withoutIntegrations from './img/without-integrations.png';
 - Click on a marked date to pin the popover open (it will stay visible even after moving the mouse away).
 - Click the date again or click outside to close the pinned popover.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={calendarWidget.configuration} />

apps/docs/docs/widgets/clock/index.mdx

@@ -1,38 +1,38 @@
 ---
-title: 'Date and time'
-description: 'Displays the current date and time.'
+title: "Date and time"
+description: "Displays the current date and time."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { clockWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { clockWidget } from ".";
 
-<WidgetHeader
-  widget={clockWidget}
-  categories={['Time']}
-/>
+<WidgetHeader widget={clockWidget} categories={["Time"]} />
 
 The clock widget displays the current date and time in a customizable format.
 
 ### Screenshots
 
-import localClock from './img/local.png';
-import londonClock from './img/london-with-seconds.png';
-import tokyoClock from './img/tokyo-12-hour.png';
+import localClock from "./img/local.png";
+import londonClock from "./img/london-with-seconds.png";
+import tokyoClock from "./img/tokyo-12-hour.png";
 
-<div className='flex gap-1'>
-    <img src={localClock} alt="clock format-24-hours timezone-local" width={128} height={128} />
-    <img src={londonClock} alt="clock format-24-hours with-seconds timezone-london" width={256} height={128} />
-    <img src={tokyoClock} alt="clock format-12-hours timezone-tokyo" width={256} height={128} />
+<div className="flex gap-1">
+  <img src={localClock} alt="clock format-24-hours timezone-local" width={128} height={128} />
+  <img src={londonClock} alt="clock format-24-hours with-seconds timezone-london" width={256} height={128} />
+  <img src={tokyoClock} alt="clock format-12-hours timezone-tokyo" width={256} height={128} />
 </div>
 
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={clockWidget.configuration} />

apps/docs/docs/widgets/coolify/index.mdx

@@ -1,28 +1,33 @@
 ---
-title: 'Coolify'
-description: 'Overview of your Coolify instance with servers, applications, and services.'
+title: "Coolify"
+description: "Overview of your Coolify instance with servers, applications, and services."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { coolifyWidget } from '.';
-import { coolifyIntegration } from '@site/docs/integrations/coolify';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={coolifyWidget}
-  categories={['System monitoring', 'Deployment']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { coolifyWidget } from ".";
+import { coolifyIntegration } from "@site/docs/integrations/coolify";
+
+<WidgetHeader widget={coolifyWidget} categories={["System monitoring", "Deployment"]} />
 
 The Coolify widget displays a compact overview of your Coolify instance. It can show servers, applications, and services with status indicators, project and environment context, direct links to Coolify, and the installed Coolify version.
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: coolifyIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: coolifyIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
@@ -34,11 +39,11 @@ The Coolify widget displays a compact overview of your Coolify instance. It can
 
 ### Sections
 
-| Section | Description |
-|---|---|
-| **Servers** | Lists Coolify servers, reachability status, and application/service counts per server. |
+| Section          | Description                                                                                                                        |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **Servers**      | Lists Coolify servers, reachability status, and application/service counts per server.                                             |
 | **Applications** | Lists applications with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links. |
-| **Services** | Lists services with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links. |
+| **Services**     | Lists services with runtime status, project and environment context, public URL links, Coolify dashboard links, and log links.     |
 
 ### Notes
 

apps/docs/docs/widgets/custom-api/index.mdx

@@ -1,18 +1,16 @@
 ---
-title: 'Custom API'
-description: 'Displays data from a custom API endpoint using configurable display types and optional JSX templates.'
+title: "Custom API"
+description: "Displays data from a custom API endpoint using configurable display types and optional JSX templates."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { customApiWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { customApiWidget } from ".";
 
-<WidgetHeader
-  widget={customApiWidget}
-  categories={['Custom', 'API']}
-/>
+<WidgetHeader widget={customApiWidget} categories={["Custom", "API"]} />
 
 This widget fetches data from a custom API endpoint defined in [Custom Widgets management](/docs/management/custom-widgets) and renders it using configurable display types.
 
@@ -20,6 +18,8 @@ Custom API widgets are created and configured through the admin management page.
 
 See the [Custom Widgets documentation](/docs/management/custom-widgets) for full details on creating and configuring custom widgets.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/dns-hole-controls/index.mdx

@@ -1,57 +1,64 @@
 ---
-title: 'DNS Hole Controls'
+title: "DNS Hole Controls"
 description: "Control PiHole or AdGuard from your dashboard."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { dnsHoleControlsWidget } from '.';
-import { adguardHomeIntegration } from '@site/docs/integrations/adguard-home';
-import { piHoleIntegration } from '@site/docs/integrations/pi-hole';
-import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { dnsHoleControlsWidget } from ".";
+import { adguardHomeIntegration } from "@site/docs/integrations/adguard-home";
+import { piHoleIntegration } from "@site/docs/integrations/pi-hole";
+import { technitiumDnsIntegration } from "@site/docs/integrations/technitium-dns";
 
+<WidgetHeader widget={dnsHoleControlsWidget} categories={["DNS Hole"]} />
 
-<WidgetHeader
-  widget={dnsHoleControlsWidget}
-  categories={['DNS Hole']}
-/>
-
-This widget allows you to enable or disable your DNS Hole.
+This widget lets permitted users enable, disable, or temporarily pause one or more DNS services. It shares the summary query and cache with DNS Hole Summary. Advanced view exposes every selected source, while compact layouts reduce controls according to both widget width and height.
 
 ### Screenshots
 
-import bigSize from './img/big.png';
-import smallSize from './img/small.png';
-
+import bigSize from "./img/big.png";
+import smallSize from "./img/small.png";
 
 <img src={bigSize} alt="dns-hole-controls big-size with-toggle-all-buttons" width={256} height={128} />
 <img src={smallSize} alt="dns-hole-controls small-size no-toggle-all-buttons" width={128} height={128} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: adguardHomeIntegration,
-}, {
-  integration: piHoleIntegration,
-}, {
-  integration: technitiumDnsIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: adguardHomeIntegration,
+    },
+    {
+      integration: piHoleIntegration,
+    },
+    {
+      integration: technitiumDnsIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
-- Enable / Disable one dns-hole by clicking on the badge.
-- Disable one dns-hole in x seconds by clicking on the clock icon.
-- Do all of the above for all dns-holes by using the top button row.
+- Enable or disable one DNS service by clicking its status badge.
+- Temporarily disable one service with the clock action.
+- Apply an action to all available services from the top action row. Homarr keeps successful results visible and reports how many sources failed.
+- Interaction controls only appear when the current user has permission for that integration.
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={dnsHoleControlsWidget.configuration} />

apps/docs/docs/widgets/dns-hole-summary/index.mdx

@@ -1,38 +1,36 @@
 ---
-title: 'DNS Hole Summary'
+title: "DNS Hole Summary"
 description: "Displays the summary of your DNS Hole."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { dnsHoleSummaryWidget } from '.';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { dnsHoleSummaryWidget } from ".";
 
+<WidgetHeader widget={dnsHoleSummaryWidget} categories={["DNS Hole"]} />
 
-<WidgetHeader
-  widget={dnsHoleSummaryWidget}
-  categories={['DNS Hole']}
-/>
-
-This widget allows you to display statistics about your DNS Hole like total queries, blocked queries, and more.
+This widget combines statistics from every selected DNS service, including total queries, blocked queries, and blocklist size. Its data is cached under the same DNS query family as DNS Hole Controls, so placing both widgets on a board does not create a second integration request. Advanced view keeps the aggregate metrics visible and adds a named status chip for each source.
 
 ### Screenshots
 
-import gridLayout from './img/grid.png';
-import verticalLayout from './img/vertical.png';
-import horizontalLayout from './img/horizontal.png';
-import { adguardHomeIntegration } from '@site/docs/integrations/adguard-home';
-import { piHoleIntegration } from '@site/docs/integrations/pi-hole';
-import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns';
+import gridLayout from "./img/grid.png";
+import verticalLayout from "./img/vertical.png";
+import horizontalLayout from "./img/horizontal.png";
+import { adguardHomeIntegration } from "@site/docs/integrations/adguard-home";
+import { piHoleIntegration } from "@site/docs/integrations/pi-hole";
+import { technitiumDnsIntegration } from "@site/docs/integrations/technitium-dns";
 
-<div className='flex gap-2'>
+<div className="flex gap-2">
   <img src={gridLayout} alt="grid-layout pi-hole-colors" width={256 + 8} height={256 + 8} />
-  <div className='flex flex-col gap-2'>
+  <div className="flex flex-col gap-2">
     <img src={verticalLayout} alt="vertical-layout no-colors" width={128} height={128} />
     <img src={horizontalLayout} alt="horizontal-layout pi-hole-colors" width={128 * 3} height={128} />
   </div>
@@ -40,17 +38,26 @@ import { technitiumDnsIntegration } from '@site/docs/integrations/technitium-dns
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: adguardHomeIntegration,
-}, {
-  integration: piHoleIntegration,
-}, {
-  integration: technitiumDnsIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: adguardHomeIntegration,
+    },
+    {
+      integration: piHoleIntegration,
+    },
+    {
+      integration: technitiumDnsIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={dnsHoleSummaryWidget.configuration} />

apps/docs/docs/widgets/docker-containers/index.mdx

@@ -1,24 +1,22 @@
 ---
-title: 'Docker stats'
-description: 'Stats of your containers'
+title: "Docker stats"
+description: "Stats of your containers"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { dockerContainersWidget } from '.';
-import { dockerIntegration } from '@site/docs/integrations/docker';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { dockerContainersWidget } from ".";
+import { dockerIntegration } from "@site/docs/integrations/docker";
 
-
-<WidgetHeader
-  widget={dockerContainersWidget}
-  categories={['Containers']}
-/>
+<WidgetHeader widget={dockerContainersWidget} categories={["Containers"]} />
 
 This widget displays the resource usage of your Docker containers and allows you to manage them.
 
@@ -28,24 +26,31 @@ This widget can only be used with administrator privileges.
 
 ### Screenshots
 
-import dockerTable from './img/table.png';
+import dockerTable from "./img/table.png";
 
 <img src={dockerTable} alt="docker-stats table docker-containers" width={128 * 3} height={128 * 2} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: dockerIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: dockerIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
 Each container row has an action menu (accessible via the three-dot icon) with the following options:
+
 - **View logs** - opens a dedicated terminal page streaming the container's logs
 - **Start** / **Stop** / **Restart** - manage the container's state
 - **Remove** - remove the container
 - **Add to Homarr** - create a bookmark app from the container
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/downloads/index.mdx

@@ -1,43 +1,41 @@
 ---
-title: 'Download Client'
-description: 'Allows you to view and manage your Downloads from both Torrent and Usenet clients.'
+title: "Download Client"
+description: "Allows you to view and manage your Downloads from both Torrent and Usenet clients."
 hide_title: true
 ---
 
-import { aria2Integration } from '@site/docs/integrations/aria2';
-import { delugeIntegration } from '@site/docs/integrations/deluge';
-import { nzbgetIntegration } from '@site/docs/integrations/nzbget';
-import { qBittorentIntegration } from '@site/docs/integrations/q-bittorent';
-import { sabnzbdIntegration } from '@site/docs/integrations/sabnzbd';
-import { transmissionIntegration } from '@site/docs/integrations/transmission';
-import { slskdIntegration } from '@site/docs/integrations/slskd';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { downloadsWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { aria2Integration } from "@site/docs/integrations/aria2";
+import { delugeIntegration } from "@site/docs/integrations/deluge";
+import { nzbgetIntegration } from "@site/docs/integrations/nzbget";
+import { qBittorentIntegration } from "@site/docs/integrations/q-bittorent";
+import { sabnzbdIntegration } from "@site/docs/integrations/sabnzbd";
+import { transmissionIntegration } from "@site/docs/integrations/transmission";
+import { slskdIntegration } from "@site/docs/integrations/slskd";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { downloadsWidget } from ".";
 
-<WidgetHeader
-  widget={downloadsWidget}
-  categories={['Torrent client', 'Usenet client', 'Downloads']}
-/>
+<WidgetHeader widget={downloadsWidget} categories={["Torrent client", "Usenet client", "Downloads"]} />
 
 This widget displays a list of torrents or usenet-articles that are currently being downloaded, along with their progress and other relevant information. It supports 7 download client integrations and provides a rich, responsive table interface.
 
 ### Screenshots
 
-import downloadsCard from './img/screenshot.png';
-import contextMenuImg from './img/context-menu.png';
+import downloadsCard from "./img/screenshot.png";
+import contextMenuImg from "./img/context-menu.png";
 
 <div>
-    <img src={downloadsCard} alt="Downloads widget showing torrent and usenet items" width={128 * 4} />
+  <img src={downloadsCard} alt="Downloads widget showing torrent and usenet items" width={128 * 4} />
 </div>
 
 #### Right-click context menu
 
 <div>
-    <img src={contextMenuImg} alt="Downloads widget context menu with pause, delete, and copy actions" width={128 * 4} />
+  <img src={contextMenuImg} alt="Downloads widget context menu with pause, delete, and copy actions" width={128 * 4} />
 </div>
 
 ### Features
@@ -56,28 +54,38 @@ import contextMenuImg from './img/context-menu.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: sabnzbdIntegration,
-  note: "Usenet client"
-}, {
-  integration: nzbgetIntegration,
-  note: "Usenet client"
-}, {
-  integration: delugeIntegration,
-  note: "Torrent client"
-}, {
-  integration: transmissionIntegration,
-  note: "Torrent client"
-}, {
-  integration: qBittorentIntegration,
-  note: "Torrent client"
-}, {
-  integration: aria2Integration,
-  note: "Multi-protocol download client"
-}, {
-  integration: slskdIntegration,
-  note: "Soulseek client (read-only)"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: sabnzbdIntegration,
+      note: "Usenet client",
+    },
+    {
+      integration: nzbgetIntegration,
+      note: "Usenet client",
+    },
+    {
+      integration: delugeIntegration,
+      note: "Torrent client",
+    },
+    {
+      integration: transmissionIntegration,
+      note: "Torrent client",
+    },
+    {
+      integration: qBittorentIntegration,
+      note: "Torrent client",
+    },
+    {
+      integration: aria2Integration,
+      note: "Multi-protocol download client",
+    },
+    {
+      integration: slskdIntegration,
+      note: "Soulseek client (read-only)",
+    },
+  ]}
+/>
 
 ### Interactions
 
@@ -89,9 +97,12 @@ import contextMenuImg from './img/context-menu.png';
 - **Filter** by integration or status using the filter button in the footer
 - **Sort** by clicking column headers (with persistent sort direction)
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={downloadsWidget.configuration} />

apps/docs/docs/widgets/firewall/index.mdx

@@ -1,22 +1,20 @@
 ---
-title: 'Firewall Monitoring'
-description: 'Displays a summary of firewalls.'
+title: "Firewall Monitoring"
+description: "Displays a summary of firewalls."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { firewallWidget } from '.';
-import { opnsenseIntegration } from '../../integrations/opnsense';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { firewallWidget } from ".";
+import { opnsenseIntegration } from "../../integrations/opnsense";
 
-<WidgetHeader
-  widget={firewallWidget}
-  categories={['Firewall']}
-/>
+<WidgetHeader widget={firewallWidget} categories={["Firewall"]} />
 
 ### Screenshots
 
@@ -24,9 +22,15 @@ import { opnsenseIntegration } from '../../integrations/opnsense';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: opnsenseIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: opnsenseIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 

apps/docs/docs/widgets/health-monitoring/index.mdx

@@ -4,6 +4,8 @@ description: "Displays information showing the health and status of your system(
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -62,6 +64,8 @@ import { synologyIntegration } from "@site/docs/integrations/synology";
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/iframe/index.mdx

@@ -1,19 +1,17 @@
 ---
-title: 'iFrame'
-description: 'Embed any content from the internet. Some websites may restrict access.'
+title: "iFrame"
+description: "Embed any content from the internet. Some websites may restrict access."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { iframeWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { iframeWidget } from ".";
 
-<WidgetHeader
-  widget={iframeWidget}
-  categories={['Embed']}
-/>
+<WidgetHeader widget={iframeWidget} categories={["Embed"]} />
 
 If your application is not supported natively by Homarr, you can integrate it using the iframe widget.
 It uses the [iframe element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
@@ -22,14 +20,16 @@ This means, no traffic is routed through Homarr (and the URL must be reachable f
 
 ### Screenshots
 
-import wikipediaHomepage from './img/wikipedia.png';
-import youtubeStream from './img/nasa-iss-stream.png';
+import wikipediaHomepage from "./img/wikipedia.png";
+import youtubeStream from "./img/nasa-iss-stream.png";
 
 <div>
   <img src={wikipediaHomepage} alt="iframe wikipedia-homepage" width={128 * 3} />
   <img src={youtubeStream} alt="iframe youtube-iss-stream" width={128 * 3} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
@@ -50,12 +50,14 @@ the appropriate headers (such as `X-Frame-Options` or `Content-Security-Policy`)
 For example, to allow your site to be embedded in iframes from specific domains:
 
 **Apache (.htaccess or httpd.conf):**
+
 ```apache
 Header set Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com"
 Header set X-Frame-Options "ALLOW-FROM https://trusted-domain.com"
 ```
 
 **Nginx:**
+
 ```nginx
 add_header Content-Security-Policy "frame-ancestors 'self' https://trusted-domain.com";
 add_header X-Frame-Options "ALLOW-FROM https://trusted-domain.com";
@@ -67,6 +69,7 @@ add_header X-Frame-Options "ALLOW-FROM https://trusted-domain.com";
 - **Any YouTube video or stream:** https://www.youtube.com/embed/dQw4w9WgXcQ?si=MWUbbG66UNTla_Ni
 
 ### Configuration
+
 <WidgetConfig configuration={iframeWidget.configuration} />
 
 ### Transparent iframes
@@ -75,15 +78,16 @@ To create a transparent iframe like below you can use the following html code an
 
 ```html
 <html style="color-scheme: dark;">
-<body style="background: none; display: flex; justify-content: center; align-items: center;">
+  <body style="background: none; display: flex; justify-content: center; align-items: center;">
     <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/homarr.svg" width="90" height="90" />
-</body>
+  </body>
 </html>
 ```
 
 ![transparent iframe](./img/transparent-iframe.png)
 
 ### Third party content
+
 :::warning
 
 The content below is an overview of third party projects. All support requests/problems must be redirected to the appropriate repository.
@@ -92,11 +96,12 @@ We cannot guarantee the functionality nor security of these tools.
 :::
 
 ### homarr-iframes from Diogo Valentim
+
 The project [homarr-iframes](https://github.com/diogovalentte/homarr-iframes) has iframes designed to be used with Homarr, these iframes offer a minimalist view of other systems:
 
 - [Vikunja](https://github.com/go-vikunja/vikunja): overview of your tasks with links to them.
 - [Linkwarden](https://github.com/linkwarden/linkwarden): overview of your bookmarks with links to them.
-- [Cinemark Brazil](https://www.cinemark.com.br): overview of the movies in Cinemark theaters in your city (*only in Brazil*).
+- [Cinemark Brazil](https://www.cinemark.com.br): overview of the movies in Cinemark theaters in your city (_only in Brazil_).
 
 ![Image of the Vikunja (left), Linkwarden (middle), and Cinemark Brazil (right) iframes on a Homarr dashboard](./img/homarr-iframes-example.webp "Image of the Vikunja (left), Linkwarden (middle), and Cinemark Brazil (right) iframes on a Homarr dashboard")
 

apps/docs/docs/widgets/immich-album-carousel/index.mdx

@@ -1,39 +1,42 @@
 ---
-title: 'Immich Album Carousel'
-description: 'Shows a slideshow of pictures from an Immich album or your full library'
+title: "Immich Album Carousel"
+description: "Shows a slideshow of pictures from an Immich album or your full library"
 hide_title: true
 ---
 
-import { immichIntegration } from '../../integrations/immich';import {
-  AddingWidget
-} from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { immichAlbumCarouselWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { immichIntegration } from "../../integrations/immich";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { immichAlbumCarouselWidget } from ".";
 
-<WidgetHeader
-  widget={immichAlbumCarouselWidget}
-  categories={['Photos Service']}
-/>
+<WidgetHeader widget={immichAlbumCarouselWidget} categories={["Photos Service"]} />
 
 ### Screenshots
 
-import screen from './img/screen.png';
+import screen from "./img/screen.png";
 
 <img src={screen} height={256} alt="immich album size-big" />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: immichIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: immichIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
-
 ### Configuration
+
 <WidgetConfig configuration={immichAlbumCarouselWidget.configuration} />

apps/docs/docs/widgets/immich-server-stats/index.mdx

@@ -1,40 +1,42 @@
 ---
-title: 'Immich Server Stats'
-description: 'Information about your Immich instance'
+title: "Immich Server Stats"
+description: "Information about your Immich instance"
 hide_title: true
 ---
 
-import { immichIntegration } from '../../integrations/immich';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { immichServerStatsWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { immichIntegration } from "../../integrations/immich";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { immichServerStatsWidget } from ".";
 
-<WidgetHeader
-  widget={immichServerStatsWidget}
-  categories={['Photos server']}
-/>
+<WidgetHeader widget={immichServerStatsWidget} categories={["Photos server"]} />
 
 ### Screenshots
 
-import screen from './img/screen.png';
-
+import screen from "./img/screen.png";
 
 <img src={screen} height={256} alt="immich server stats size-big" />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: immichIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: immichIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
-
 ### Configuration
-<WidgetConfig configuration={immichServerStatsWidget.configuration} />
 
+<WidgetConfig configuration={immichServerStatsWidget.configuration} />

apps/docs/docs/widgets/indexer-manager/index.mdx

@@ -1,47 +1,50 @@
 ---
-title: 'Indexer manager status'
-description: 'View the status of your indexers.'
+title: "Indexer manager status"
+description: "View the status of your indexers."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { indexerManagerWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { indexerManagerWidget } from ".";
 
-<WidgetHeader
-  widget={indexerManagerWidget}
-  categories={['Indexer']}
-/>
+<WidgetHeader widget={indexerManagerWidget} categories={["Indexer"]} />
 
 ### Screenshots
 
-import bigItem from './img/big.png';
-import smallItem from './img/small.png';
-import { prowlarrIntegration } from '@site/docs/integrations/prowlarr';
+import bigItem from "./img/big.png";
+import smallItem from "./img/small.png";
+import { prowlarrIntegration } from "@site/docs/integrations/prowlarr";
 
-<div className='flex gap-1'>
+<div className="flex gap-1">
   <img src={bigItem} height={256} alt="indexer-manager size-big" />
   <img src={smallItem} height={128} alt="indexer-manager size-small" />
 </div>
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: prowlarrIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: prowlarrIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
 - Test all indexers by clicking on the test button.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
-
 ### Configuration
-<WidgetConfig configuration={indexerManagerWidget.configuration} />
 
+<WidgetConfig configuration={indexerManagerWidget.configuration} />

apps/docs/docs/widgets/media-missing/index.mdx

@@ -1,29 +1,28 @@
 ---
-title: 'Media Missing & Queue'
-description: 'Track missing media and active downloads from Radarr and Sonarr'
+title: "Media Missing & Queue"
+description: "Track missing media and active downloads from Radarr and Sonarr"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { mediaMissingWidget } from '.';
-import { radarrIntegration } from '@site/docs/integrations/radarr';
-import { sonarrIntegration } from '@site/docs/integrations/sonarr';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={mediaMissingWidget}
-  categories={['Media', 'Downloads']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { mediaMissingWidget } from ".";
+import { radarrIntegration } from "@site/docs/integrations/radarr";
+import { sonarrIntegration } from "@site/docs/integrations/sonarr";
+
+<WidgetHeader widget={mediaMissingWidget} categories={["Media", "Downloads"]} />
 
 Monitor which movies and episodes are missing from your library, and track what is currently being downloaded. The widget pulls data from Radarr and Sonarr and groups results by type in two tabs.
 
 ### Screenshots
 
-import widgetMissing from './img/missing.png';
-import widgetQueued from './img/queued.png';
-import widgetCompact from './img/compact.png';
+import widgetMissing from "./img/missing.png";
+import widgetQueued from "./img/queued.png";
+import widgetCompact from "./img/compact.png";
 
 <div className="flex gap-2 flex-wrap">
   <img src={widgetMissing} alt="media-missing widget showing missing movies and episodes in a grid" width={360} />
@@ -33,18 +32,23 @@ import widgetCompact from './img/compact.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: radarrIntegration,
-}, {
-  integration: sonarrIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: radarrIntegration,
+    },
+    {
+      integration: sonarrIntegration,
+    },
+  ]}
+/>
 
 ### Tabs
 
-| Tab | Description |
-|---|---|
+| Tab         | Description                                                                                           |
+| ----------- | ----------------------------------------------------------------------------------------------------- |
 | **Missing** | Lists movies (Radarr) and episodes (Sonarr) that are monitored but not yet available in your library. |
-| **Queued** | Shows items currently being downloaded with a progress bar and estimated time remaining. |
+| **Queued**  | Shows items currently being downloaded with a progress bar and estimated time remaining.              |
 
 ### Sizing
 
@@ -56,6 +60,8 @@ The widget adapts to its container size, so it looks good at any grid size:
 
 Each item shows its poster art (with the artwork bleeding softly behind the card), a type badge, and — on the queue — an animated progress bar with the estimated time remaining.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/media-releases/index.mdx

@@ -1,30 +1,28 @@
 ---
-title: 'Media releases'
-description: 'Display newly added medias or upcoming releases from different integrations'
+title: "Media releases"
+description: "Display newly added medias or upcoming releases from different integrations"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { mediaReleasesWidget } from '.';
-import { embyIntegration } from '@site/docs/integrations/emby';
-import { jellyfinIntegration } from '@site/docs/integrations/jellyfin';
-import { plexIntegration } from '@site/docs/integrations/plex';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { mediaReleasesWidget } from ".";
+import { embyIntegration } from "@site/docs/integrations/emby";
+import { jellyfinIntegration } from "@site/docs/integrations/jellyfin";
+import { plexIntegration } from "@site/docs/integrations/plex";
 
-<WidgetHeader
-  widget={mediaReleasesWidget}
-  categories={['Releases', 'Media']}
-/>
+<WidgetHeader widget={mediaReleasesWidget} categories={["Releases", "Media"]} />
 
 Provides a list of newly added media or upcoming releases from your media server.
 
 ### Screenshots
 
-import backdrop from './img/backdrop.png';
-import poster from './img/poster.png';
+import backdrop from "./img/backdrop.png";
+import poster from "./img/poster.png";
 
 <div className="flex gap-1">
   <img src={backdrop} alt="media-releases layout-backdrop" width={256} />
@@ -33,17 +31,26 @@ import poster from './img/poster.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: embyIntegration,
-}, {
-  integration: jellyfinIntegration,
-}, {
-  integration: plexIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: embyIntegration,
+    },
+    {
+      integration: jellyfinIntegration,
+    },
+    {
+      integration: plexIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={mediaReleasesWidget.configuration} />

apps/docs/docs/widgets/media-request-list/index.mdx

@@ -4,6 +4,8 @@ description: "See a list of all media requests from your integration"
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -45,6 +47,8 @@ import mediaRequestList from "./img/list.png";
 - Approve / decline a request by clicking on the thumbs up or down icon.
 - Hover over the widget to reveal a **search button** that opens Spotlight in media request search mode, scoped to the widget's integrations.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/media-request-stats/index.mdx

@@ -1,39 +1,42 @@
 ---
-title: 'Media Requests Stats'
-description: 'Statistics about your media requests'
+title: "Media Requests Stats"
+description: "Statistics about your media requests"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { mediaRequestStatsWidget } from '.';
-import { jellyseerrIntegration } from '@site/docs/integrations/jellyseerr';
-import { overseerrIntegration } from '@site/docs/integrations/overseerr';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { mediaRequestStatsWidget } from ".";
+import { jellyseerrIntegration } from "@site/docs/integrations/jellyseerr";
+import { overseerrIntegration } from "@site/docs/integrations/overseerr";
 
-
-<WidgetHeader
-  widget={mediaRequestStatsWidget}
-  categories={['Media requests']}
-/>
+<WidgetHeader widget={mediaRequestStatsWidget} categories={["Media requests"]} />
 
 Provide a statistics overview of your media requests, such as mount of requests, open requests, approvement and rejections.
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: jellyseerrIntegration,
-}, {
-  integration: overseerrIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: jellyseerrIntegration,
+    },
+    {
+      integration: overseerrIntegration,
+    },
+  ]}
+/>
 
 ### Screenshots
 
-import mediaRequestStats from './img/stats.png';
+import mediaRequestStats from "./img/stats.png";
 
 <img src={mediaRequestStats} alt="media-request-stats" width={256} height={256} />
 
@@ -41,6 +44,8 @@ import mediaRequestStats from './img/stats.png';
 
 - Hover over the widget to reveal a **search button** that opens Spotlight in media request search mode, scoped to the widget's integrations.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/media-server/index.mdx

@@ -1,56 +1,62 @@
 ---
-title: 'Media server streams'
-description: 'Show the current streams on your media servers'
+title: "Media server streams"
+description: "Show the current streams on your media servers"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { mediaServerWidget } from '.';
-import { embyIntegration } from '@site/docs/integrations/emby';
-import { jellyfinIntegration } from '@site/docs/integrations/jellyfin';
-import { navidromeIntegration } from '@site/docs/integrations/navidrome';
-import { plexIntegration } from '@site/docs/integrations/plex';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { mediaServerWidget } from ".";
+import { embyIntegration } from "@site/docs/integrations/emby";
+import { jellyfinIntegration } from "@site/docs/integrations/jellyfin";
+import { navidromeIntegration } from "@site/docs/integrations/navidrome";
+import { plexIntegration } from "@site/docs/integrations/plex";
 
+<WidgetHeader widget={mediaServerWidget} categories={["Media server"]} />
 
-<WidgetHeader
-  widget={mediaServerWidget}
-  categories={['Media server']}
-/>
-
-The media server widget enables you to watch and view current active sessions over all your media servers. 
+The media server widget enables you to watch and view current active sessions over all your media servers.
 It also displays useful information, that you can use when providing support to users or debugging a problem.
 
-
-
 ### Screenshots
 
-import mediaTable from './img/table.png';
+import mediaTable from "./img/table.png";
 
 <img src={mediaTable} alt="media-server-streams" width={128 * 3 * 1.5} height={128 * 1.5} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: embyIntegration,
-}, {
-  integration: jellyfinIntegration,
-}, {
-  integration: navidromeIntegration,
-  note: "Will always show only currently playing audio streams, not all active sessions."
-}, {
-  integration: plexIntegration,
-  note: "Will always show only currently playing streams, not all active sessions."
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: embyIntegration,
+    },
+    {
+      integration: jellyfinIntegration,
+    },
+    {
+      integration: navidromeIntegration,
+      note: "Will always show only currently playing audio streams, not all active sessions.",
+    },
+    {
+      integration: plexIntegration,
+      note: "Will always show only currently playing streams, not all active sessions.",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={mediaServerWidget.configuration} />

apps/docs/docs/widgets/media-transcoding/index.mdx

@@ -1,35 +1,31 @@
 ---
-title: 'Media transcoding'
-description: 'Statistics, current queue and worker status of your media transcoding'
+title: "Media transcoding"
+description: "Statistics, current queue and worker status of your media transcoding"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { mediaTranscodingWidget } from '.';
-import { tdarrIntegration } from '@site/docs/integrations/tdarr';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { mediaTranscodingWidget } from ".";
+import { tdarrIntegration } from "@site/docs/integrations/tdarr";
 
+<WidgetHeader widget={mediaTranscodingWidget} categories={["Media transcoding"]} />
 
-<WidgetHeader
-  widget={mediaTranscodingWidget}
-  categories={['Media transcoding']}
-/>
-
-The media transcoding widget provides you with an overview of your media transcoding status. 
+The media transcoding widget provides you with an overview of your media transcoding status.
 It shows you the current queue, worker status, and statistics about your transcoding jobs.
 
-
-
 ### Screenshots
 
-import queueCard from './img/queue.png';
-import workersCard from './img/workers.png';
-import statisticsCard from './img/statistics.png';
+import queueCard from "./img/queue.png";
+import workersCard from "./img/workers.png";
+import statisticsCard from "./img/statistics.png";
 
 <div className="flex gap-1 flex-wrap">
   <img src={workersCard} alt="media-transcoding workers-tab" width={128 * 3} />
@@ -39,13 +35,20 @@ import statisticsCard from './img/statistics.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: tdarrIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: tdarrIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={mediaTranscodingWidget.configuration} />

apps/docs/docs/widgets/minecraft-server-status/index.mdx

@@ -1,44 +1,45 @@
 ---
-title: 'Minecraft Server Status'
-description: 'Displays the status of a Minecraft server.'
+title: "Minecraft Server Status"
+description: "Displays the status of a Minecraft server."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import TabItem from '@theme/TabItem';
-import Tabs from '@theme/Tabs';
-import { minecraftServerStatusWidget } from '.';
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+import { minecraftServerStatusWidget } from ".";
 
-
-<WidgetHeader
-  widget={minecraftServerStatusWidget}
-  categories={['Gaming', 'Minecraft']}
-/>
+<WidgetHeader widget={minecraftServerStatusWidget} categories={["Gaming", "Minecraft"]} />
 
 Shows the status and amount of players on a Minecraft server. It supports both Java and Bedrock editions, however only public servers are supported which can be reached through the used api of [api.mcsrvstat.us](https://api.mcsrvstat.us).
 
 ### Screenshots
 
-import javaItem from './img/java.png';
-import bedrockItem from './img/bedrock.png';
+import javaItem from "./img/java.png";
+import bedrockItem from "./img/bedrock.png";
 
-<div className='flex gap-1'>
+<div className="flex gap-1">
   <img src={javaItem} alt="minecraft-server-status java-edition" width={128 * 1.5} height={128 * 1.5} />
   <img src={bedrockItem} alt="minecraft-server-status bedrock-editon" width={128 * 1.5} height={128 * 1.5} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={minecraftServerStatusWidget.configuration} />
 
 ### Data source
 
 We use the Minecraft Server Status API to fetch the server status.
-If you need to whitelist the api, please use the following URL: `hhttps://api.mcsrvstat.us`
+If you need to whitelist the api, please use the following URL: `hhttps://api.mcsrvstat.us`

apps/docs/docs/widgets/network-controller-status/index.mdx

@@ -1,44 +1,49 @@
 ---
-title: 'Network Status'
-description: 'Display connected devices on a network'
+title: "Network Status"
+description: "Display connected devices on a network"
 hide_title: true
 ---
 
-import { unifiControllerIntegration } from '@site/docs/integrations/unifi-controller';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { unifiControllerIntegration } from "@site/docs/integrations/unifi-controller";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import TabItem from '@theme/TabItem';
-import Tabs from '@theme/Tabs';
-import { networkControllerStatusWidget } from '.';
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+import { networkControllerStatusWidget } from ".";
 
-
-<WidgetHeader
-  widget={networkControllerStatusWidget}
-  categories={['Network controller']}
-/>
+<WidgetHeader widget={networkControllerStatusWidget} categories={["Network controller"]} />
 
 Shows connected users and connected guest devices on wired or wireless networks.
 
 ### Screenshots
 
-import wifiCard from './img/wifi.png';
-import wiredCard from './img/wired.png';
+import wifiCard from "./img/wifi.png";
+import wiredCard from "./img/wired.png";
 
 <img src={wifiCard} alt="network-controller-status wifi" width={128 * 1.5} height={128 * 1.5} />
 <img src={wiredCard} alt="network-controller-status wired" width={128 * 1.5} height={128 * 1.5} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: unifiControllerIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: unifiControllerIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={networkControllerStatusWidget.configuration} />

apps/docs/docs/widgets/network-controller-summary/index.mdx

@@ -1,38 +1,42 @@
 ---
-title: 'Network Controller Summary'
-description: 'Displays the summary of a Network Controller'
+title: "Network Controller Summary"
+description: "Displays the summary of a Network Controller"
 hide_title: true
 ---
 
-import { unifiControllerIntegration } from '@site/docs/integrations/unifi-controller';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { unifiControllerIntegration } from "@site/docs/integrations/unifi-controller";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import TabItem from '@theme/TabItem';
-import Tabs from '@theme/Tabs';
-import { networkControllerSummaryWidget } from '.';
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+import { networkControllerSummaryWidget } from ".";
 
-
-<WidgetHeader
-  widget={networkControllerSummaryWidget}
-  categories={['Network controller']}
-/>
+<WidgetHeader widget={networkControllerSummaryWidget} categories={["Network controller"]} />
 
 Shows information whether your WAN is connected, Wi-Fi is active and several other information.
 
 ### Screenshots
 
-import summaryCard from './img/summary.png';
+import summaryCard from "./img/summary.png";
 
 <img src={summaryCard} alt="network-controller-summary" width={128 * 1.5} height={128 * 1.5} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: unifiControllerIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: unifiControllerIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 

apps/docs/docs/widgets/notebook/index.mdx

@@ -4,6 +4,8 @@ description: "A simple notebook widget that supports markdown."
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetHeader } from "@site/src/components/widgets/header";
@@ -24,6 +26,8 @@ import editOn from "./img/edit.png";
   <img src={editOn} alt="notebook edit-on" width={128 * 3} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/notifications/index.mdx

@@ -1,44 +1,41 @@
 ---
-title: 'Notifications'
-description: 'Display notification history from an integration'
+title: "Notifications"
+description: "Display notification history from an integration"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { notificationsWidget } from '.';
-import { ntfyIntegration } from '@site/docs/integrations/ntfy';
-import { nextcloudIntegration } from '@site/docs/integrations/nextcloud';
-import { gotifyIntegration } from '@site/docs/integrations/gotify';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={notificationsWidget}
-  categories={['Notifications', "Messaging"]}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { IconAd } from "@tabler/icons-react";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { notificationsWidget } from ".";
+import { ntfyIntegration } from "@site/docs/integrations/ntfy";
+import { nextcloudIntegration } from "@site/docs/integrations/nextcloud";
+import { gotifyIntegration } from "@site/docs/integrations/gotify";
+
+<WidgetHeader widget={notificationsWidget} categories={["Notifications", "Messaging"]} />
 
 The notifications widget allows you to display notifications from various integrations in a unified view.
 
 ### Screenshots
 
-import notificationsScreenshot from './img/notifications.png';
+import notificationsScreenshot from "./img/notifications.png";
 
 <img src={notificationsScreenshot} alt="notifications" width={256} height={256} />
 
 ### Supported Integrations
 
 <WidgetIntegrations
-  items={[
-    { integration: ntfyIntegration },
-    { integration: nextcloudIntegration },
-    { integration: gotifyIntegration }
-  ]}
+  items={[{ integration: ntfyIntegration }, { integration: nextcloudIntegration }, { integration: gotifyIntegration }]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/paperless-ngx/index.mdx

@@ -1,34 +1,39 @@
 ---
-title: 'Paperless-ngx'
-description: 'Displays document management statistics including inbox ratio, document counts, and metadata.'
+title: "Paperless-ngx"
+description: "Displays document management statistics including inbox ratio, document counts, and metadata."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { paperlessNgxWidget } from '.';
-import { paperlessNgxIntegration } from '@site/docs/integrations/paperless-ngx';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { paperlessNgxWidget } from ".";
+import { paperlessNgxIntegration } from "@site/docs/integrations/paperless-ngx";
 
-<WidgetHeader
-  widget={paperlessNgxWidget}
-  categories={['Documents']}
-/>
+<WidgetHeader widget={paperlessNgxWidget} categories={["Documents"]} />
 
 This widget displays statistics from your Paperless-ngx instance, including an inbox ratio ring showing how many documents are in your inbox versus total, along with counts for correspondents, tags, and document types.
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: paperlessNgxIntegration,
-  note: "Displays document statistics and inbox ratio"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: paperlessNgxIntegration,
+      note: "Displays document statistics and inbox ratio",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={paperlessNgxWidget.configuration} />

apps/docs/docs/widgets/patchmon/index.mdx

@@ -1,21 +1,19 @@
 ---
-title: 'PatchMon'
-description: 'Displays host patch statistics from PatchMon including update and security counts.'
+title: "PatchMon"
+description: "Displays host patch statistics from PatchMon including update and security counts."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { patchmonWidget } from '.';
-import { patchmonIntegration } from '@site/docs/integrations/patchmon';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { patchmonWidget } from ".";
+import { patchmonIntegration } from "@site/docs/integrations/patchmon";
 
-<WidgetHeader
-  widget={patchmonWidget}
-  categories={['Health Monitoring']}
-/>
+<WidgetHeader widget={patchmonWidget} categories={["Health Monitoring"]} />
 
 This widget displays patch statistics from your PatchMon instance, including total hosts, hosts needing updates, and security update counts. Each stat is shown with a dedicated icon and severity-tinted card background for quick visual scanning.
 
@@ -39,13 +37,13 @@ In **1-column-wide** layouts (such as 1×1), the compliance hero switches to a r
 
 When **Enable threshold colors** is on (default), stat values and card backgrounds are colored for at-a-glance severity:
 
-| Stat | Green | Yellow | Red |
-|------|-------|--------|-----|
-| Needs Updates | 0 | 1–4 | 5+ |
-| Security Updates | 0 | 1–9 | 10+ |
-| Hosts with Security Updates | 0 | — | 1+ |
-| Up-to-Date Hosts | 100% of total | 90–99% | below 90% |
-| Outdated Packages | 0 | 1–49 | 50+ |
+| Stat                        | Green         | Yellow | Red       |
+| --------------------------- | ------------- | ------ | --------- |
+| Needs Updates               | 0             | 1–4    | 5+        |
+| Security Updates            | 0             | 1–9    | 10+       |
+| Hosts with Security Updates | 0             | —      | 1+        |
+| Up-to-Date Hosts            | 100% of total | 90–99% | below 90% |
+| Outdated Packages           | 0             | 1–49   | 50+       |
 
 Enable **Advanced thresholds** to override warning and critical values per stat, using either absolute counts or percentages of total hosts.
 
@@ -62,13 +60,13 @@ The OS distribution limit defaults to **All**. A widget size of **2×3** or larg
 
 The widget adapts its layout based on the available space:
 
-| Widget size | Layout |
-|-------------|--------|
-| **1×1** | Primary selected content: compliance ring (no label), compact OS distribution, or up to two enabled stats |
+| Widget size       | Layout                                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **1×1**           | Primary selected content: compliance ring (no label), compact OS distribution, or up to two enabled stats           |
 | **2×1** / **1×2** | Compact primary content; **2×1** shows compliance label and host ratio beside the ring; **1×2** uses ring-only hero |
-| **2×2** (default) | Compliance hero, stat grid with icons, and tinted cards |
-| **2×3** / **3×2** | Hero, stats, OS distribution, and "last updated" footer |
-| **3×3** or larger | Full layout with up to 4-column stat grid, donut chart, and optional OS legend |
+| **2×2** (default) | Compliance hero, stat grid with icons, and tinted cards                                                             |
+| **2×3** / **3×2** | Hero, stats, OS distribution, and "last updated" footer                                                             |
+| **3×3** or larger | Full layout with up to 4-column stat grid, donut chart, and optional OS legend                                      |
 
 ### Last updated
 
@@ -76,14 +74,21 @@ When the widget has enough space, a "last updated" timestamp appears at the bott
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: patchmonIntegration,
-  note: "Displays host patch and security update statistics"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: patchmonIntegration,
+      note: "Displays host patch and security update statistics",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={patchmonWidget.configuration} />

apps/docs/docs/widgets/releases/index.mdx

@@ -4,6 +4,8 @@ description: "Displays a list of the current version of the given repositories w
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetHeader } from "@site/src/components/widgets/header";
@@ -33,6 +35,8 @@ GitHub, Docker Hub, GitLab, NPM, Codeberg, GitHub Container Registry, Quay, and
 For GitHub Container Registry, use `owner/package` identifiers such as `homarr-labs/homarr`.
 Full image references such as `ghcr.io/homarr-labs/homarr:latest` are also accepted.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/rss-feed/index.mdx

@@ -1,37 +1,40 @@
 ---
-title: 'RSS Feed'
-description: 'Monitor and display one or more generic RSS, ATOM or JSON feeds.'
+title: "RSS Feed"
+description: "Monitor and display one or more generic RSS, ATOM or JSON feeds."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { rssFeedWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { rssFeedWidget } from ".";
 
-<WidgetHeader
-  widget={rssFeedWidget}
-  categories={['Feeds']}
-/>
+<WidgetHeader widget={rssFeedWidget} categories={["Feeds"]} />
 
 Using the RSS standard, you can integrate most News websites, applications and more on your dashboard.
 
 ### Screenshots
 
-import screenshot from './img/screenshot.png';
+import screenshot from "./img/screenshot.png";
 
 <img src={screenshot} alt="rss-feed noted-lol" width={128 * 4} />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={rssFeedWidget.configuration} />
 
 ### Examples
+
 Here's a small collection of examples, that you can use for testing or actual use (in no particular order):
+
 - https://noted.lol/rss/
 - https://blog.google/products/chrome/rss/
 - https://www.w3.org/blog/feed/
@@ -45,4 +48,4 @@ Here's a small collection of examples, that you can use for testing or actual us
 - http://feeds.foxnews.com/foxnews/latest
 
 There is a good list of feeds here:
-https://github.com/greysonp/rss-feeds/blob/master/feeds.json
+https://github.com/greysonp/rss-feeds/blob/master/feeds.json

apps/docs/docs/widgets/smart-home-entity-state/index.mdx

@@ -1,34 +1,32 @@
 ---
-title: 'Entity State'
-description: 'Display the state of an entity and toggle it optionally'
+title: "Entity State"
+description: "Display the state of an entity and toggle it optionally"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { smartHomeEntityStateWidget } from '.';
-import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { smartHomeEntityStateWidget } from ".";
+import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant";
 
-
-<WidgetHeader
-  widget={smartHomeEntityStateWidget}
-  categories={['Smart home']}
-/>
+<WidgetHeader widget={smartHomeEntityStateWidget} categories={["Smart home"]} />
 
 The entity state enables you to display the current state of an entity.
-This works with most entities and enables you display almost any data. 
+This works with most entities and enables you display almost any data.
 It is recommended that you transform data on the integration as much as possible since Homarr's capabilities in transformation are very limited.
 
 ### Screenshots
 
-import sun from './img/sun.png';
-import lightSwitch from './img/light-switch.png';
-import temperature from './img/temperature.png';
+import sun from "./img/sun.png";
+import lightSwitch from "./img/light-switch.png";
+import temperature from "./img/temperature.png";
 
 <img src={sun} alt="smart-home-entity-state sun" width={128 * 1.5} height={128 * 1.5} />
 <img src={lightSwitch} alt="smart-home-entity-state light-switch" width={128 * 1.5} height={128 * 1.5} />
@@ -36,32 +34,40 @@ import temperature from './img/temperature.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: homeAssistantIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: homeAssistantIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
 - Toggle entity state by clicking on the entity (only when clickable enabled).
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={smartHomeEntityStateWidget.configuration} />
 
 ### How to find the entity ID
 
 To find the entity ID in Home Assistant, follow these steps:
+
 1. Open Home Assistant and go to the **Developer Tools** section (usually found in the sidebar).
 2. Click on the **States** tab.
 3. In the list of entities, find the entity you want to use.
 4. The entity ID will be displayed in the format `domain.object_id` (e.g., `light.living_room_light`).
 5. Copy the entity ID and paste it into the widget configuration in Homarr. It will then show the State that is visible in Home Assistant.
 
-import retrieveEntityId from './img/retrieve-entity-id.png';
+import retrieveEntityId from "./img/retrieve-entity-id.png";
 
 <div>
   <img src={retrieveEntityId} alt="homeassistant retrieve-entity-id" width={256 * 2} />
-</div>
+</div>

apps/docs/docs/widgets/smart-home-execute-automation/index.mdx

@@ -1,50 +1,60 @@
 ---
-title: 'Execute Automation'
-description: 'Trigger an automation with one click'
+title: "Execute Automation"
+description: "Trigger an automation with one click"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
 import { IconAd } from "@tabler/icons-react";
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import { smartHomeExecuteAutomationWidget } from '.';
-import { homeAssistantIntegration } from '@site/docs/integrations/home-assistant';
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import { smartHomeExecuteAutomationWidget } from ".";
+import { homeAssistantIntegration } from "@site/docs/integrations/home-assistant";
 
-
-<WidgetHeader
-  widget={smartHomeExecuteAutomationWidget}
-  categories={['Automation']}
-/>
+<WidgetHeader widget={smartHomeExecuteAutomationWidget} categories={["Automation"]} />
 
 The execute automation widget allows you to trigger an automation with one click.
 
 ### Screenshots
 
-import empty from './img/empty.png';
-import withDisplayname from './img/with-displayname.png';
+import empty from "./img/empty.png";
+import withDisplayname from "./img/with-displayname.png";
 
 <div className="flex gap-1">
   <img src={empty} alt="smart-home-execute-automation empty" width={128 * 1.5} height={128 * 1.5} />
-  <img src={withDisplayname} alt="smart-home-execute-automation with-displayname" width={128 * 1.5} height={128 * 1.5} />
+  <img
+    src={withDisplayname}
+    alt="smart-home-execute-automation with-displayname"
+    width={128 * 1.5}
+    height={128 * 1.5}
+  />
 </div>
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: homeAssistantIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: homeAssistantIntegration,
+    },
+  ]}
+/>
 
 ### Interactions
 
 - Trigger the automation by clicking on the widget.
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={smartHomeExecuteAutomationWidget.configuration} />

apps/docs/docs/widgets/speedtest-tracker/index.mdx

@@ -1,39 +1,45 @@
 ---
-title: 'Speedtest Tracker'
-description: 'Displays speed test results from your Speedtest Tracker instance.'
+title: "Speedtest Tracker"
+description: "Displays speed test results from your Speedtest Tracker instance."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { speedtestTrackerWidget } from '.';
-import { speedtestTrackerIntegration } from '@site/docs/integrations/speedtest-tracker';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={speedtestTrackerWidget}
-  categories={['Speedtest']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { speedtestTrackerWidget } from ".";
+import { speedtestTrackerIntegration } from "@site/docs/integrations/speedtest-tracker";
+
+<WidgetHeader widget={speedtestTrackerWidget} categories={["Speedtest"]} />
 
 This widget displays internet speed test results from your [Speedtest Tracker](https://docs.speedtest-tracker.dev/) instance,
 including the latest result, historical averages, and a live chart of the last 12 hours.
 
 ### Screenshots
 
-import screenshot from './img/screenshot.png';
+import screenshot from "./img/screenshot.png";
 
 <img src={screenshot} alt="speedtest-tracker image" width={500} height={355} />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: speedtestTrackerIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: speedtestTrackerIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={speedtestTrackerWidget.configuration} />

apps/docs/docs/widgets/stock-price/index.mdx

@@ -1,28 +1,26 @@
 ---
-title: 'Stock Price'
-description: 'Displays the current stock price of a company.'
+title: "Stock Price"
+description: "Displays the current stock price of a company."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { stockPriceWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { stockPriceWidget } from ".";
 
-<WidgetHeader
-  widget={stockPriceWidget}
-  categories={['Finance', "Market"]}
-/>
+<WidgetHeader widget={stockPriceWidget} categories={["Finance", "Market"]} />
 
 Using the Stocks widget, you can show the current stock prices of your favorite companies on your dashboard.
 
 ### Screenshots
 
-import apple from './img/apple.png';
-import google from './img/google.png';
-import ethereum from './img/ethereum.png';
-import nvidia from './img/nvidia.png';
+import apple from "./img/apple.png";
+import google from "./img/google.png";
+import ethereum from "./img/ethereum.png";
+import nvidia from "./img/nvidia.png";
 
 <div className="flex gap-1">
   <div className="flex flex-col gap-1">
@@ -34,17 +32,21 @@ import nvidia from './img/nvidia.png';
   </div>
   <img src={nvidia} alt="stock-price nvidia" width={128 * 2 + 2} height={128 * 2 + 4} />
 </div>
-  
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={stockPriceWidget.configuration} />
 
 ### Examples
+
 Here's a small collection of examples, that you can use for testing or actual use (in no particular order):
+
 - AAPL
 - GOOGL
 - AMZN
@@ -59,4 +61,4 @@ Here's a small collection of examples, that you can use for testing or actual us
 ### Data source
 
 We use the Yahoo Finance API to fetch the stock prices.
-If you need to whitelist the api, please use the following URL: `https://query1.finance.yahoo.com`
+If you need to whitelist the api, please use the following URL: `https://query1.finance.yahoo.com`

apps/docs/docs/widgets/system-disks/index.mdx

@@ -4,6 +4,8 @@ description: "Disk usage of your system"
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -42,6 +44,8 @@ This widget displays filesystem and SMART disk usage for supported server and NA
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/system-disks/index.ts

@@ -19,7 +19,11 @@ export const systemDisksWidget: WidgetDefinition = {
         description: "How disk usage values are shown",
         values: {
           type: "select",
-          options: ["Percentage (e.g., 76%)", "Absolute values (e.g., 800GB / 1TB)", "Free space percentage (e.g., 24% free)"],
+          options: [
+            "Percentage (e.g., 76%)",
+            "Absolute values (e.g., 800GB / 1TB)",
+            "Free space percentage (e.g., 24% free)",
+          ],
         },
         defaultValue: "Percentage (e.g., 76%)",
       },

apps/docs/docs/widgets/system-resources/index.mdx

@@ -4,6 +4,8 @@ description: "Displays CPU, RAM and network of your host in real time"
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -65,6 +67,8 @@ import { synologyIntegration } from "@site/docs/integrations/synology";
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/timetable/index.mdx

@@ -4,6 +4,8 @@ description: "Displays departure times for a station."
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetHeader } from "@site/src/components/widgets/header";
@@ -19,18 +21,12 @@ import trainDepartures from "./img/train-departures.png";
 import streetDepartures from "./img/street-departures.png";
 
 <div className="flex gap-2">
-  <img
-    src={trainDepartures}
-    alt="timetable-widget-train-departures"
-    width={128 * 2}
-  />
-  <img
-    src={streetDepartures}
-    alt="timetable-widget-bus-and-tram-departures"
-    width={128 * 2}
-  />
+  <img src={trainDepartures} alt="timetable-widget-train-departures" width={128 * 2} />
+  <img src={streetDepartures} alt="timetable-widget-bus-and-tram-departures" width={128 * 2} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/tracearr/index.mdx

@@ -1,52 +1,57 @@
 ---
-title: 'Tracearr'
-description: 'Monitor media server streams, user activity, and policy violations.'
+title: "Tracearr"
+description: "Monitor media server streams, user activity, and policy violations."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { tracearrWidget } from '.';
-import { tracearrIntegration } from '@site/docs/integrations/tracearr';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { tracearrWidget } from ".";
+import { tracearrIntegration } from "@site/docs/integrations/tracearr";
 
-<WidgetHeader
-  widget={tracearrWidget}
-  categories={['Media Monitoring']}
-/>
+<WidgetHeader widget={tracearrWidget} categories={["Media Monitoring"]} />
 
 The Tracearr widget provides a real-time monitoring dashboard for your media server activity. It displays active streams, user statistics, recent watching history, and policy violations.
 
 ### Sections
 
-| Section | Description |
-|---|---|
-| **Stats Bar** | Displays Active Streams, Total Users, Transcode Count, and Total Bandwidth at a glance. |
-| **Active Streams** | Shows currently playing media with poster art, user info, progress bar, resolution, and transcoding status (Direct Play or Transcode). |
-| **Recent Activity** | A paginated list of watching history with user avatars and watched status. |
-| **Violations** | Alerts for policy violations (e.g., concurrent stream limits) with severity levels. |
+| Section             | Description                                                                                                                            |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **Stats Bar**       | Displays Active Streams, Total Users, Transcode Count, and Total Bandwidth at a glance.                                                |
+| **Active Streams**  | Shows currently playing media with poster art, user info, progress bar, resolution, and transcoding status (Direct Play or Transcode). |
+| **Recent Activity** | A paginated list of watching history with user avatars and watched status.                                                             |
+| **Violations**      | Alerts for policy violations (e.g., concurrent stream limits) with severity levels.                                                    |
 
 ### Screenshots
 
-import widgetOverview from './img/widget-overview.png';
-import streamsAndStats from './img/streams-and-stats.png';
+import widgetOverview from "./img/widget-overview.png";
+import streamsAndStats from "./img/streams-and-stats.png";
 
 <div className="flex flex-col gap-2">
   <img src={widgetOverview} alt="tracearr-widget-overview" width={128 * 4} />
   <img src={streamsAndStats} alt="tracearr-streams-and-stats" width={128 * 4} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: tracearrIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: tracearrIntegration,
+    },
+  ]}
+/>
 
 ### Configuration
+
 <WidgetConfig configuration={tracearrWidget.configuration} />

apps/docs/docs/widgets/traefik/index.mdx

@@ -4,6 +4,8 @@ description: "Displays Traefik router, service, middleware, and entry point coun
 hide_title: true
 ---
 
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
+
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
@@ -26,6 +28,8 @@ This widget displays a compact overview of your Traefik instance, including tota
   ]}
 />
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/umami/index.mdx

@@ -1,28 +1,33 @@
 ---
-title: 'Umami Analytics'
-description: 'Display visitor stats from your Umami analytics instance'
+title: "Umami Analytics"
+description: "Display visitor stats from your Umami analytics instance"
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { umamiWidget } from '.';
-import { umamiIntegration } from '@site/docs/integrations/umami';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={umamiWidget}
-  categories={['Analytics']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { umamiWidget } from ".";
+import { umamiIntegration } from "@site/docs/integrations/umami";
+
+<WidgetHeader widget={umamiWidget} categories={["Analytics"]} />
 
 The Umami Analytics widget displays key visitor metrics from a website tracked by your [Umami](https://umami.is) instance - pageviews, unique visitors, visits, bounce rate, avg. visit duration, and real-time active visitor count. The widget body can be switched between a visitor/event chart, a multi-event chart, and ranked top pages or referrers lists.
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: umamiIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: umamiIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
@@ -34,12 +39,12 @@ The Umami Analytics widget displays key visitor metrics from a website tracked b
 
 ### View modes
 
-| View | Description |
-|---|---|
-| **Chart** | Bar chart or sparkline of unique visitors over the selected time frame. Optionally overlay a single named event as a second series. |
-| **Events chart** | Multi-select one or more named events and chart each as its own colored series - no visitor baseline. Supports bar and sparkline. |
-| **Top pages** | Ranked list of URLs by pageview count for the selected time frame. |
-| **Top referrers** | Ranked list of referrer sources by session count. Direct traffic (no referrer) is labeled "Direct". |
+| View              | Description                                                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Chart**         | Bar chart or sparkline of unique visitors over the selected time frame. Optionally overlay a single named event as a second series. |
+| **Events chart**  | Multi-select one or more named events and chart each as its own colored series - no visitor baseline. Supports bar and sparkline.   |
+| **Top pages**     | Ranked list of URLs by pageview count for the selected time frame.                                                                  |
+| **Top referrers** | Ranked list of referrer sources by session count. Direct traffic (no referrer) is labeled "Direct".                                 |
 
 ### Notes
 

apps/docs/docs/widgets/ups/index.mdx

@@ -1,20 +1,19 @@
 ---
-title: 'UPS'
-description: 'Monitor the status of your UPS devices through a NUT server.'
+title: "UPS"
+description: "Monitor the status of your UPS devices through a NUT server."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { upsWidget } from '.';
-import { peaNutIntegration } from '@site/docs/integrations/peanut';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={upsWidget}
-  categories={['UPS']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { upsWidget } from ".";
+import { peaNutIntegration } from "@site/docs/integrations/peanut";
+
+<WidgetHeader widget={upsWidget} categories={["UPS"]} />
 
 This widget displays the status of the UPS devices reported by a Network UPS Tools (NUT) server. Each device shows its
 status (online, on battery, charging or low battery), battery charge and estimated runtime, output load, and input and
@@ -22,27 +21,34 @@ output voltage.
 
 ### Layouts
 
-import screenshotFull from './img/screenshot.png';
-import screenshotCompact from './img/screenshot-compact.png';
-import screenshotMini from './img/screenshot-mini.png';
+import screenshotFull from "./img/screenshot.png";
+import screenshotCompact from "./img/screenshot-compact.png";
+import screenshotMini from "./img/screenshot-mini.png";
 
 The widget adapts to the size of the tile, so it stays readable from a full dashboard panel down to a single cell. Multiple UPS devices scroll within the widget at any height.
 
-| Layout | Size | Preview |
-| --- | --- | --- |
-| Full | 3+ columns wide | <img src={screenshotFull} alt="UPS widget full layout" width={239} /> |
-| Compact | ~2 columns | <img src={screenshotCompact} alt="UPS widget compact layout" width={171} /> |
-| Mini | 1 column | <img src={screenshotMini} alt="UPS widget mini layout" width={90} /> |
+| Layout  | Size            | Preview                                                                     |
+| ------- | --------------- | --------------------------------------------------------------------------- |
+| Full    | 3+ columns wide | <img src={screenshotFull} alt="UPS widget full layout" width={239} />       |
+| Compact | ~2 columns      | <img src={screenshotCompact} alt="UPS widget compact layout" width={171} /> |
+| Mini    | 1 column        | <img src={screenshotMini} alt="UPS widget mini layout" width={90} />        |
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: peaNutIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: peaNutIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={upsWidget.configuration} />

apps/docs/docs/widgets/uptime-kuma/index.mdx

@@ -1,34 +1,39 @@
 ---
-title: 'Uptime Kuma'
-description: 'Displays monitor uptime statistics, average uptime percentage, and service status counts.'
+title: "Uptime Kuma"
+description: "Displays monitor uptime statistics, average uptime percentage, and service status counts."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { uptimeKumaWidget } from '.';
-import { uptimeKumaIntegration } from '@site/docs/integrations/uptime-kuma';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { uptimeKumaWidget } from ".";
+import { uptimeKumaIntegration } from "@site/docs/integrations/uptime-kuma";
 
-<WidgetHeader
-  widget={uptimeKumaWidget}
-  categories={['Monitoring']}
-/>
+<WidgetHeader widget={uptimeKumaWidget} categories={["Monitoring"]} />
 
 This widget displays uptime statistics from your Uptime Kuma status page, including a visual uptime ring, average uptime percentage, and per-status monitor counts.
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: uptimeKumaIntegration,
-  note: "Displays monitors from the configured status page"
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: uptimeKumaIntegration,
+      note: "Displays monitors from the configured status page",
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={uptimeKumaWidget.configuration} />

apps/docs/docs/widgets/video/index.mdx

@@ -1,19 +1,17 @@
 ---
-title: 'Video Stream'
-description: 'Embed a video stream or video from a camera or a website.'
+title: "Video Stream"
+description: "Embed a video stream or video from a camera or a website."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { videoWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { videoWidget } from ".";
 
-<WidgetHeader
-  widget={videoWidget}
-  categories={["Video", "Surveillance"]}
-/>
+<WidgetHeader widget={videoWidget} categories={["Video", "Surveillance"]} />
 
 Do you run surveilance cameras? Or maybe you have a favourite video?
 The video widget enables you to integrate both seamlessly into your dashboard.
@@ -22,7 +20,6 @@ This widget uses [video.js](https://videojs.com/) to play HLS or DASH video nati
 DRM content is not yet supported. More info here:
 https://videojs.com/guides/faqs/#q-what-is-videojs
 
-
 You can use the following URL to test:
 http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4
 
@@ -30,9 +27,12 @@ http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp
 
 ![video big-buck-bunny](./img/bunny.png)
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={videoWidget.configuration} />

apps/docs/docs/widgets/video/index.tsx

@@ -5,7 +5,7 @@ export const videoWidget: WidgetDefinition = {
   icon: IconDeviceCctv,
   name: "Video Stream",
   description: "Embed a video stream or video from a camera or a website.",
-  path: "../../widgets/stock-price",
+  path: "../../widgets/video",
   configuration: {
     items: [
       {

apps/docs/docs/widgets/vpn/index.mdx

@@ -1,19 +1,18 @@
 ---
-title: 'VPN'
-description: 'Monitor the status of your VPN integrations.'
+title: "VPN"
+description: "Monitor the status of your VPN integrations."
 hide_title: true
 ---
 
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetIntegrations } from '@site/src/components/widgets/integrations';
-import { vpnWidget } from '.';
-import { gluetunIntegration } from '@site/docs/integrations/gluetun';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
-<WidgetHeader
-  widget={vpnWidget}
-  categories={['Network', 'Security']}
-/>
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { vpnWidget } from ".";
+import { gluetunIntegration } from "@site/docs/integrations/gluetun";
+
+<WidgetHeader widget={vpnWidget} categories={["Network", "Security"]} />
 
 The VPN widget provides a compact overview of each configured VPN integration. It shows whether the tunnel and DNS
 services are up, the currently exposed public IP address, and the VPN provider and protocol being used.
@@ -23,7 +22,7 @@ current status at a glance.
 
 ### Screenshots
 
-import singleIntegrationImage from './img/single.png';
+import singleIntegrationImage from "./img/single.png";
 
 <div>
   <img src={singleIntegrationImage} alt="VPN widget showing a single integration" width={128 * 3} />
@@ -31,9 +30,15 @@ import singleIntegrationImage from './img/single.png';
 
 ### Supported Integrations
 
-<WidgetIntegrations items={[{
-  integration: gluetunIntegration,
-}]} />
+<WidgetIntegrations
+  items={[
+    {
+      integration: gluetunIntegration,
+    },
+  ]}
+/>
+
+<WidgetInteractionGuide />
 
 ### Adding the widget
 

apps/docs/docs/widgets/weather/index.mdx

@@ -1,40 +1,41 @@
 ---
-title: 'Weather'
-description: 'Displays the current weather information of a set location.'
+title: "Weather"
+description: "Displays the current weather information of a set location."
 hide_title: true
 ---
 
-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { weatherWidget } from '.';
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { weatherWidget } from ".";
 
-<WidgetHeader
-  widget={weatherWidget}
-  categories={["Weather"]}
-/>
+<WidgetHeader widget={weatherWidget} categories={["Weather"]} />
 
 The Weather Widget uses your location to display the current, highest and lowest temperature.
 
 ### Screenshots
 
-import forecastWeather from './img/forecast.png';
-import currentWeather from './img/current.png';
+import forecastWeather from "./img/forecast.png";
+import currentWeather from "./img/current.png";
 
 <div className="flex flex-col gap-1">
   <img src={forecastWeather} alt="weather forecast-5-days" width={128 * 4.5} />
   <img src={currentWeather} alt="weather current" width={128 * 3} />
 </div>
 
+<WidgetInteractionGuide />
+
 ### Adding the widget
 
 <AddingWidget />
 
 ### Configuration
+
 <WidgetConfig configuration={weatherWidget.configuration} />
 
 ### Data source
 
 We use the Open Meteo API to fetch the weather and locations.
-If you need to whitelist the api, please use the following URL: `https://open-meteo.com`
+If you need to whitelist the api, please use the following URL: `https://open-meteo.com`

apps/docs/src/components/widgets/interactions.tsx

@@ -0,0 +1,47 @@
+import { IconArrowsMaximize, 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.",
+  },
+  {
+    icon: IconMouse2,
+    title: "Widget actions",
+    description:
+      "Right-click for live query status, refresh, settings, quick options, and actions supported by the widget.",
+  },
+  {
+    icon: IconPlus,
+    title: "Place it precisely",
+    description:
+      "With board changes allowed, right-click or touch and hold empty grid space to add there. Keyboard users can press Shift + F10.",
+  },
+] as const;
+
+export const WidgetInteractionGuide = () => (
+  <details className="group my-6 overflow-hidden rounded-xl border border-solid border-[#e5e7eb] bg-slate-50/70 dark:border-[#333] dark:bg-gray-900/40">
+    <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-4 py-3 font-semibold marker:hidden">
+      <span>Power-user controls</span>
+      <span className="text-xs font-normal text-[#696969] group-open:hidden dark:text-[#999]">Show shortcuts</span>
+      <span className="hidden text-xs font-normal text-[#696969] group-open:inline dark:text-[#999]">
+        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]">
+      {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" />
+          <div className="font-semibold">{title}</div>
+          <p className="mb-0 mt-1 text-sm text-[#696969] dark:text-[#999]">{description}</p>
+        </div>
+      ))}
+    </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.
+    </p>
+  </details>
+);

apps/nextjs/src/app/[locale]/_client-providers/trpc.tsx

@@ -2,7 +2,6 @@
 
 import type { PropsWithChildren } from "react";
 import { useState } from "react";
-import type { QueryKey } from "@tanstack/react-query";
 import { QueryClient } from "@tanstack/react-query";
 import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 import { ReactQueryStreamedHydration } from "@tanstack/react-query-next-experimental";
@@ -34,6 +33,7 @@ import {
 import { createHeadersCallbackForSource, getTrpcUrl } from "@homarr/api/shared";
 import { env } from "@homarr/common/env";
 import { showWarningNotification } from "@homarr/notifications";
+import type { WidgetDefinition } from "@homarr/widgets";
 import { widgetImports } from "@homarr/widgets";
 
 import { createWidgetQueryPersister } from "./query-cache-persister";
@@ -93,11 +93,11 @@ export function TRPCReactProvider(props: PropsWithChildren) {
     });
     client.setQueryDefaults([["widget"]], { refetchInterval: queryCacheDefaultRefetchIntervalMs });
     for (const { definition } of Object.values(widgetImports)) {
-      const def = definition as { refetchInterval?: number | null; queryKey?: QueryKey; kind: string };
+      const def = definition as WidgetDefinition & { kind: string };
       if (def.refetchInterval === undefined) continue;
-      const key = def.queryKey ?? [["widget", def.kind]];
       const interval = def.refetchInterval === null ? false : def.refetchInterval * 1000;
-      client.setQueryDefaults(key, { refetchInterval: interval });
+      const primaryQueryKey = def.queryKey ?? [["widget", def.kind]];
+      client.setQueryDefaults(primaryQueryKey, { refetchInterval: interval });
     }
     return client;
   });

apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx

@@ -4,6 +4,7 @@ import { Box, Stack } from "@mantine/core";
 
 import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
 
+import { BoardAdvancedFocusProvider } from "~/components/board/advanced-focus/context";
 import { BoardCategorySection } from "~/components/board/sections/category-section";
 import { BoardEmptySection } from "~/components/board/sections/empty-section";
 import { BoardBackgroundVideo } from "~/components/layout/background";
@@ -17,17 +18,19 @@ export const ClientBoard = () => {
     .sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset);
 
   return (
-    <Box h="100%" pos="relative">
-      <BoardBackgroundVideo />
-      <Stack h="100%">
-        {fullWidthSortedSections.map((section) =>
-          section.kind === "empty" ? (
-            <BoardEmptySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ) : (
-            <BoardCategorySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ),
-        )}
-      </Stack>
-    </Box>
+    <BoardAdvancedFocusProvider>
+      <Box h="100%" pos="relative">
+        <BoardBackgroundVideo />
+        <Stack h="100%">
+          {fullWidthSortedSections.map((section) =>
+            section.kind === "empty" ? (
+              <BoardEmptySection key={`${currentLayoutId}-${section.id}`} section={section} />
+            ) : (
+              <BoardCategorySection key={`${currentLayoutId}-${section.id}`} section={section} />
+            ),
+          )}
+        </Stack>
+      </Box>
+    </BoardAdvancedFocusProvider>
   );
 };

apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx

@@ -70,6 +70,7 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
 };
 
 const AddMenu = () => {
+  const board = useRequiredBoard();
   const { data: session } = useSession();
   const { openModal: openCategoryEditModal } = useModalAction(CategoryEditModal);
   const { openModal: openItemSelectModal } = useModalAction(ItemSelectModal);
@@ -101,8 +102,8 @@ const AddMenu = () => {
   );
 
   const handleSelectItem = useCallback(() => {
-    openItemSelectModal();
-  }, [openItemSelectModal]);
+    openItemSelectModal({ board, persistImmediately: false });
+  }, [board, openItemSelectModal]);
 
   const handleSelectApp = useCallback(() => {
     openAppSelectModal({

apps/nextjs/src/app/[locale]/manage/custom-widgets/_custom-widget-preview.tsx

@@ -123,7 +123,7 @@ export function CustomWidgetPreview({
                     type: "application/json",
                   });
                   const blobUrl = URL.createObjectURL(blob);
-                  window.open(blobUrl);
+                  window.open(blobUrl, "_blank", "noopener,noreferrer");
                   setTimeout(() => URL.revokeObjectURL(blobUrl), 60_000);
                 }}
               >
@@ -167,7 +167,7 @@ function PreviewDisplay({ data }: { data: unknown }) {
 
   const Component = dataType ? displayComponents[dataType] : undefined;
   if (Component) {
-    return <Component data={typed} />;
+    return <Component data={typed} displayMode="advanced" width={320} height={240} />;
   }
 
   return (

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,
+  };
+};

apps/nextjs/src/components/board/items/actions/create-item.ts

@@ -3,35 +3,48 @@ import { createId } from "@homarr/common";
 import type { Modify } from "@homarr/common/types";
 import type { WidgetKind } from "@homarr/definitions";
 import { widgetDefaultSizes } from "@homarr/definitions";
+import type { BoardItemAdvancedOptions } from "@homarr/validation/shared";
 
 import type { Board, EmptySection, Item, ItemLayout } from "~/app/[locale]/boards/_types";
-import { getFirstEmptyPosition } from "./empty-position";
+import { getFirstEmptyPosition, getNearestEmptyPosition } from "./empty-position";
 import { getSectionElements } from "./section-elements";
 
+export interface BoardPlacementHint {
+  sectionId: string;
+  layoutId: string;
+  xOffset: number;
+  yOffset: number;
+}
+
 export interface CreateItemInput {
   id?: string;
   kind: WidgetKind;
   options?: Record<string, unknown>;
   integrationIds?: string[];
+  advancedOptions?: BoardItemAdvancedOptions;
+  placement?: BoardPlacementHint;
 }
 
 export const createItemCallback =
-  ({ id, kind, options = {}, integrationIds = [] }: CreateItemInput) =>
+  ({ id, kind, options = {}, integrationIds = [], advancedOptions, placement }: CreateItemInput) =>
   (previous: Board): Board => {
     const firstSection = previous.sections
       .filter((section): section is EmptySection => section.kind === "empty")
       .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
       .at(0);
 
-    if (!firstSection) return previous;
+    if (!firstSection && !placement) return previous;
+
+    const defaultSectionId = firstSection?.id ?? placement?.sectionId;
+    if (!defaultSectionId) return previous;
 
     const widget = {
       id: id ?? createId(),
       kind,
       options,
-      layouts: createItemLayouts(previous, firstSection, kind),
+      layouts: createItemLayouts(previous, defaultSectionId, kind, placement),
       integrationIds,
-      advancedOptions: {
+      advancedOptions: advancedOptions ?? {
         title: null,
         customCssClasses: [],
         borderColor: "",
@@ -53,16 +66,31 @@ const defaultItemSize = { width: 1, height: 1 };
 
 const getWidgetItemSize = (kind: WidgetKind) => widgetDefaultSizes[kind] ?? defaultItemSize;
 
-const createItemLayouts = (board: Board, currentSection: EmptySection, kind: WidgetKind): ItemLayout[] => {
+const createItemLayouts = (
+  board: Board,
+  defaultSectionId: string,
+  kind: WidgetKind,
+  placement?: BoardPlacementHint,
+): ItemLayout[] => {
   const layouts = getBoardLayouts(board);
   const itemSize = getWidgetItemSize(kind);
 
   return layouts.map((layoutId) => {
     const boardLayout = board.layouts.find((layout) => layout.id === layoutId);
-    const elements = getSectionElements(board, { sectionId: currentSection.id, layoutId });
+    const targetSectionId = placement?.layoutId === layoutId ? placement.sectionId : defaultSectionId;
+    const elements = getSectionElements(board, { sectionId: targetSectionId, layoutId });
 
+    const targetSection = board.sections.find((section) => section.id === targetSectionId);
+    const dynamicLayout =
+      targetSection?.kind === "dynamic"
+        ? targetSection.layouts.find((layout) => layout.layoutId === layoutId)
+        : undefined;
+    const columnCount = dynamicLayout?.width ?? boardLayout?.columnCount ?? 1;
+    const rowCount = dynamicLayout?.height ?? 9999;
     const emptyPosition = boardLayout
-      ? getFirstEmptyPosition(elements, boardLayout.columnCount, 9999, itemSize)
+      ? placement?.layoutId === layoutId
+        ? getNearestEmptyPosition(elements, columnCount, rowCount, placement, itemSize)
+        : getFirstEmptyPosition(elements, columnCount, rowCount, itemSize)
       : { xOffset: 0, yOffset: 0 };
 
     if (!emptyPosition) {
@@ -73,7 +101,7 @@ const createItemLayouts = (board: Board, currentSection: EmptySection, kind: Wid
       width: itemSize.width,
       height: itemSize.height,
       ...emptyPosition,
-      sectionId: currentSection.id,
+      sectionId: targetSectionId,
       layoutId,
     };
   });

apps/nextjs/src/components/board/items/actions/empty-position.ts

@@ -7,19 +7,56 @@ export const getFirstEmptyPosition = (
   size: { width: number; height: number } = { width: 1, height: 1 },
 ) => {
   for (let yOffset = 0; yOffset < rowCount + 1 - size.height; yOffset++) {
-    for (let xOffset = 0; xOffset < columnCount; xOffset++) {
-      const isOccupied = elements.some(
-        (element) =>
-          element.yOffset < yOffset + size.height &&
-          element.yOffset + element.height > yOffset &&
-          element.xOffset < xOffset + size.width &&
-          element.xOffset + element.width > xOffset,
-      );
-
-      if (!isOccupied) {
+    for (let xOffset = 0; xOffset < columnCount + 1 - size.width; xOffset++) {
+      if (isPositionEmpty(elements, { xOffset, yOffset }, size)) {
         return { xOffset, yOffset };
       }
     }
   }
   return undefined;
 };
+
+export const getNearestEmptyPosition = (
+  elements: Pick<SectionItem, "yOffset" | "xOffset" | "width" | "height">[],
+  columnCount: number,
+  rowCount: number,
+  preferred: { xOffset: number; yOffset: number },
+  size: { width: number; height: number },
+) => {
+  const maxX = columnCount - size.width;
+  const maxY = rowCount - size.height;
+  if (maxX < 0 || maxY < 0) return undefined;
+
+  const clamped = {
+    xOffset: Math.min(Math.max(0, preferred.xOffset), maxX),
+    yOffset: Math.min(Math.max(0, preferred.yOffset), maxY),
+  };
+  if (isPositionEmpty(elements, clamped, size)) return clamped;
+
+  const lastOccupiedRow = elements.reduce((maximum, element) => Math.max(maximum, element.yOffset + element.height), 0);
+  const searchMaxY = Math.min(maxY, Math.max(clamped.yOffset + 20, lastOccupiedRow + size.height));
+  let best: { xOffset: number; yOffset: number; distance: number } | undefined;
+
+  for (let yOffset = 0; yOffset <= searchMaxY; yOffset++) {
+    for (let xOffset = 0; xOffset <= maxX; xOffset++) {
+      if (!isPositionEmpty(elements, { xOffset, yOffset }, size)) continue;
+      const distance = Math.abs(xOffset - clamped.xOffset) + Math.abs(yOffset - clamped.yOffset);
+      if (!best || distance < best.distance) best = { xOffset, yOffset, distance };
+    }
+  }
+
+  return best && { xOffset: best.xOffset, yOffset: best.yOffset };
+};
+
+const isPositionEmpty = (
+  elements: Pick<SectionItem, "yOffset" | "xOffset" | "width" | "height">[],
+  position: { xOffset: number; yOffset: number },
+  size: { width: number; height: number },
+) =>
+  !elements.some(
+    (element) =>
+      element.yOffset < position.yOffset + size.height &&
+      element.yOffset + element.height > position.yOffset &&
+      element.xOffset < position.xOffset + size.width &&
+      element.xOffset + element.width > position.xOffset,
+  );

apps/nextjs/src/components/board/items/actions/test/create-item.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 
 import * as boardContext from "@homarr/boards/context";
 
@@ -10,6 +10,10 @@ import { ItemMockBuilder } from "./mocks/item-mock";
 import { LayoutMockBuilder } from "./mocks/layout-mock";
 
 describe("item actions create-item", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test("should add it to first section", () => {
     // Arrange
     const itemKind = "clock";
@@ -108,4 +112,58 @@ describe("item actions create-item", () => {
       { height: 1, width: 1 },
     );
   });
+
+  test("uses the clicked section and nearest cell for the active layout", () => {
+    const activeLayoutId = "desktop";
+    const secondaryLayoutId = "mobile";
+    const rootSectionId = "root";
+    const targetSectionId = "target";
+    const activeLayout = new LayoutMockBuilder({ id: activeLayoutId, columnCount: 12 }).build();
+    const secondaryLayout = new LayoutMockBuilder({ id: secondaryLayoutId, columnCount: 4 }).build();
+    const targetSection = new DynamicSectionMockBuilder({ id: targetSectionId })
+      .addLayout({
+        layoutId: activeLayoutId,
+        parentSectionId: rootSectionId,
+        width: 4,
+        height: 3,
+      })
+      .build();
+    const board = new BoardMockBuilder()
+      .addLayout(activeLayout)
+      .addLayout(secondaryLayout)
+      .addEmptySection({ id: rootSectionId, yOffset: 0 })
+      .addSection(targetSection)
+      .build();
+
+    vi.spyOn(boardContext, "getBoardLayouts").mockReturnValue([activeLayoutId, secondaryLayoutId]);
+
+    const result = createItemCallback({
+      kind: "clock",
+      placement: {
+        sectionId: targetSectionId,
+        layoutId: activeLayoutId,
+        xOffset: 2,
+        yOffset: 1,
+      },
+    })(board);
+
+    expect(result.items.at(0)?.layouts).toEqual([
+      {
+        layoutId: activeLayoutId,
+        sectionId: targetSectionId,
+        xOffset: 2,
+        yOffset: 1,
+        width: 1,
+        height: 1,
+      },
+      {
+        layoutId: secondaryLayoutId,
+        sectionId: rootSectionId,
+        xOffset: 0,
+        yOffset: 0,
+        width: 1,
+        height: 1,
+      },
+    ]);
+  });
 });

apps/nextjs/src/components/board/items/actions/test/empty-position.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "vitest";
 
 import type { Item } from "~/app/[locale]/boards/_types";
-import { getFirstEmptyPosition } from "../empty-position";
+import { getFirstEmptyPosition, getNearestEmptyPosition } from "../empty-position";
 
 describe("get first empty position", () => {
   test.each([
@@ -106,6 +106,37 @@ describe("get first empty position", () => {
 
     expect(result).toEqual(expectedX !== undefined ? { xOffset: expectedX, yOffset: expectedY } : undefined);
   });
+
+  test("does not place a wide item beyond the right edge", () => {
+    const elements = createElementsFromLayout([["a", "a", "a", " "]]);
+
+    expect(getFirstEmptyPosition(elements, 4, undefined, { width: 2, height: 1 })).toEqual({
+      xOffset: 0,
+      yOffset: 1,
+    });
+  });
+});
+
+describe("get nearest empty position", () => {
+  test("keeps the preferred cell when it fits", () => {
+    expect(getNearestEmptyPosition([], 4, 4, { xOffset: 2, yOffset: 1 }, { width: 1, height: 1 })).toEqual({
+      xOffset: 2,
+      yOffset: 1,
+    });
+  });
+
+  test("chooses the nearest available cell when the preferred cell is occupied", () => {
+    const elements = [{ xOffset: 2, yOffset: 1, width: 1, height: 1 }];
+
+    expect(getNearestEmptyPosition(elements, 4, 4, { xOffset: 2, yOffset: 1 }, { width: 1, height: 1 })).toEqual({
+      xOffset: 2,
+      yOffset: 0,
+    });
+  });
+
+  test("returns undefined when the item cannot fit within a bounded section", () => {
+    expect(getNearestEmptyPosition([], 1, 1, { xOffset: 0, yOffset: 0 }, { width: 2, height: 1 })).toBeUndefined();
+  });
 });
 
 const createElementsFromLayout = (layout: string[][]) => {

apps/nextjs/src/components/board/items/item-actions.tsx

@@ -3,6 +3,7 @@ import { useCallback } from "react";
 import { useUpdateBoard } from "@homarr/boards/updater";
 import type { BoardItemAdvancedOptions } from "@homarr/validation/shared";
 
+import type { Board } from "~/app/[locale]/boards/_types";
 import type { CreateItemInput } from "./actions/create-item";
 import { createItemCallback } from "./actions/create-item";
 import type { DuplicateItemInput } from "./actions/duplicate-item";
@@ -34,7 +35,12 @@ export const useItemActions = () => {
 
   const createItem = useCallback(
     (input: CreateItemInput) => {
-      updateBoard(createItemCallback(input));
+      let nextBoard: Board | undefined;
+      updateBoard((previous) => {
+        nextBoard = createItemCallback(input)(previous);
+        return nextBoard;
+      });
+      return nextBoard;
     },
     [updateBoard],
   );

apps/nextjs/src/components/board/items/item-content.tsx

@@ -1,7 +1,8 @@
-import type { MutableRefObject } from "react";
-import { useRef } from "react";
-import { Badge, Card } from "@mantine/core";
-import { useElementSize } from "@mantine/hooks";
+import type { CSSProperties, KeyboardEvent, MutableRefObject, PointerEvent } from "react";
+import { useEffect, useRef } from "react";
+import { ActionIcon, Badge, Box, Card, FocusTrap } from "@mantine/core";
+import { useElementSize, useMergedRef, useViewportSize } from "@mantine/hooks";
+import { IconMaximize, IconPin, IconX } from "@tabler/icons-react";
 import { QueryErrorResetBoundary, useQueryClient } from "@tanstack/react-query";
 import combineClasses from "clsx";
 import { NoIntegrationSelectedError } from "@homarr/widgets/errors/classes";
@@ -10,10 +11,14 @@ import { ErrorBoundary } from "react-error-boundary";
 import { useRequiredBoard } from "@homarr/boards/context";
 import { useEditMode } from "@homarr/boards/edit-mode";
 import { useSettings } from "@homarr/settings";
+import { useI18n } from "@homarr/translation/client";
 import { loadWidgetDynamic, reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
 import { WidgetError } from "@homarr/widgets/errors";
 
 import type { SectionItem } from "~/app/[locale]/boards/_types";
+import advancedFocusClasses from "../advanced-focus/advanced-focus.module.css";
+import { useAdvancedFocus } from "../advanced-focus/context";
+import { getAdvancedFocusRect } from "../advanced-focus/geometry";
 import classes from "../sections/item.module.css";
 import { useItemActions } from "./item-actions";
 import itemContentClasses from "./item-content.module.css";
@@ -33,35 +38,160 @@ const getOverflowFromKind = (kind: SectionItem["kind"]) => {
 
 export const BoardItemContent = ({ item }: BoardItemContentProps) => {
   const { ref, width, height } = useElementSize<HTMLDivElement>();
+  const sourceRef = useRef<HTMLDivElement>(null);
+  const mergedRef = useMergedRef(ref, sourceRef);
+  const { width: viewportWidth, height: viewportHeight } = useViewportSize();
   const board = useRequiredBoard();
+  const t = useI18n();
+  const [isEditMode] = useEditMode();
   const widgetStateRef = useRef<Record<string, unknown> | null>(null);
+  const { active, open, close, dismiss, pin, hover, leave } = useAdvancedFocus();
+  const activeFocus = active?.itemId === item.id ? active : null;
+  const isAdvanced = activeFocus !== null;
+  const advancedRect = activeFocus
+    ? getAdvancedFocusRect(activeFocus.sourceRect, { width: viewportWidth, height: viewportHeight })
+    : null;
+
+  // Responsive layout changes remount grid items. Never leave their focus backdrop orphaned.
+  useEffect(() => () => dismiss(item.id), [dismiss, item.id]);
+
+  const openPinned = () => {
+    if (sourceRef.current) open(item.id, sourceRef.current, true);
+  };
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.currentTarget !== event.target || event.key !== "Enter" || !event.shiftKey || isEditMode) return;
+    event.preventDefault();
+    openPinned();
+  };
+  const handleSurfacePointerDown = (event: PointerEvent<HTMLDivElement>) => {
+    if (!activeFocus || activeFocus.pinned) return;
+
+    const target =
+      event.target instanceof Element
+        ? event.target.closest<HTMLElement>(
+            "a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), iframe, [tabindex]:not([tabindex='-1']), [contenteditable='true']",
+          )
+        : null;
+    const alreadyAutofocused = target?.hasAttribute("data-autofocus") ?? false;
+    if (target && !alreadyAutofocused) target.setAttribute("data-autofocus", "true");
+    pin(false);
+    if (target && !alreadyAutofocused) {
+      window.setTimeout(() => target.removeAttribute("data-autofocus"), 250);
+    }
+  };
 
   return (
     <>
-      <WidgetContextMenu item={item} widgetStateRef={widgetStateRef}>
-        <Card
-          ref={ref}
-          className={combineClasses(
-            classes.itemCard,
-            `${item.kind}-wrapper`,
-            "grid-stack-item-content",
-            item.advancedOptions.customCssClasses.join(" "),
-          )}
-          radius={board.itemRadius}
-          styles={{
-            root: {
-              "--opacity": board.opacity / 100,
-              containerType: "size",
-              overflow: getOverflowFromKind(item.kind),
-              "--border-color": item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
-            },
-          }}
-          p={0}
+      <WidgetContextMenu item={item} widgetStateRef={widgetStateRef} sourceRef={sourceRef}>
+        <Box
+          ref={mergedRef}
+          tabIndex={isEditMode ? undefined : 0}
+          aria-haspopup="dialog"
+          aria-expanded={isAdvanced}
+          aria-keyshortcuts="Shift+Enter"
+          onKeyDown={handleKeyDown}
+          onPointerEnter={() => sourceRef.current && hover(item.id, sourceRef.current)}
+          onPointerLeave={() => leave(item.id)}
+          className={combineClasses("grid-stack-item-content", isAdvanced && advancedFocusClasses.sourcePlaceholder)}
         >
-          <InnerContent item={item} width={width} height={height} widgetStateRef={widgetStateRef} />
-        </Card>
+          <div
+            className={combineClasses(
+              advancedFocusClasses.surfaceHost,
+              isAdvanced && advancedFocusClasses.surfaceHostAdvanced,
+            )}
+          >
+            <FocusTrap active={Boolean(activeFocus?.pinned)}>
+              <Card
+                role={isAdvanced ? "dialog" : undefined}
+                aria-modal={activeFocus?.pinned || undefined}
+                aria-label={
+                  isAdvanced ? t("item.advancedFocus.dialog", { widget: t(`widget.${item.kind}.name`) }) : undefined
+                }
+                radius={board.itemRadius}
+                p={0}
+                h={isAdvanced ? undefined : "100%"}
+                w={isAdvanced ? undefined : "100%"}
+                className={combineClasses(
+                  classes.itemCard,
+                  `${item.kind}-wrapper`,
+                  isAdvanced && advancedFocusClasses.surface,
+                  activeFocus?.phase === "closing" && advancedFocusClasses.surfaceClosing,
+                  item.advancedOptions.customCssClasses.join(" "),
+                )}
+                onPointerDownCapture={isAdvanced ? handleSurfacePointerDown : undefined}
+                styles={{
+                  root: {
+                    "--opacity": isAdvanced ? 0.98 : board.opacity / 100,
+                    containerType: "size",
+                    overflow: getOverflowFromKind(item.kind),
+                    "--border-color":
+                      item.advancedOptions.borderColor !== "" ? item.advancedOptions.borderColor : undefined,
+                  },
+                }}
+                style={
+                  activeFocus && advancedRect
+                    ? ({
+                        left: advancedRect.left,
+                        top: advancedRect.top,
+                        width: advancedRect.width,
+                        height: advancedRect.height,
+                        "--focus-translate-x": `${activeFocus.sourceRect.left - advancedRect.left}px`,
+                        "--focus-translate-y": `${activeFocus.sourceRect.top - advancedRect.top}px`,
+                        "--focus-scale-x": activeFocus.sourceRect.width / advancedRect.width,
+                        "--focus-scale-y": activeFocus.sourceRect.height / advancedRect.height,
+                      } as CSSProperties)
+                    : undefined
+                }
+              >
+                <div className={advancedFocusClasses.surfaceControls}>
+                  {isAdvanced && (
+                    <ActionIcon
+                      data-autofocus={activeFocus.pinned && activeFocus.autofocusClose ? true : undefined}
+                      className={advancedFocusClasses.closeButton}
+                      variant="default"
+                      size="lg"
+                      aria-label={t("item.advancedFocus.close")}
+                      onClick={() => close()}
+                    >
+                      <IconX size={18} />
+                    </ActionIcon>
+                  )}
+                  {isAdvanced && (
+                    <ActionIcon
+                      className={advancedFocusClasses.pinButton}
+                      variant={activeFocus.pinned ? "filled" : "default"}
+                      aria-label={activeFocus.pinned ? t("item.advancedFocus.pinned") : t("item.advancedFocus.pin")}
+                      aria-pressed={activeFocus.pinned}
+                      onClick={(event) => pin(event.detail === 0)}
+                    >
+                      <IconPin size={18} />
+                    </ActionIcon>
+                  )}
+                  {!isEditMode && !isAdvanced && (
+                    <ActionIcon
+                      className={advancedFocusClasses.touchButton}
+                      variant="default"
+                      size="lg"
+                      aria-label={t("item.advancedFocus.open")}
+                      onClick={openPinned}
+                    >
+                      <IconMaximize size={18} />
+                    </ActionIcon>
+                  )}
+                </div>
+                <InnerContent
+                  item={item}
+                  width={advancedRect?.width ?? width}
+                  height={advancedRect?.height ?? height}
+                  widgetStateRef={widgetStateRef}
+                  displayMode={isAdvanced ? "advanced" : "compact"}
+                />
+              </Card>
+            </FocusTrap>
+          </div>
+        </Box>
       </WidgetContextMenu>
-      {item.advancedOptions.title?.trim() && (
+      {!isAdvanced && item.advancedOptions.title?.trim() && (
         <Badge
           pos="absolute"
           // It's 4 because of the mantine-react-table that has z-index 3
@@ -91,6 +221,7 @@ interface InnerContentProps {
   width: number;
   height: number;
   widgetStateRef: MutableRefObject<Record<string, unknown> | null>;
+  displayMode: "compact" | "advanced";
 }
 
 const InnerContent = ({ item, ...dimensions }: InnerContentProps) => {

apps/nextjs/src/components/board/items/item-select-modal.module.css

@@ -0,0 +1,25 @@
+.selectionCard {
+  overflow: hidden;
+}
+
+.selectionActions {
+  opacity: 1;
+  transition: opacity 150ms ease;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .selectionActions {
+    opacity: 0;
+  }
+
+  .selectionCard:hover .selectionActions,
+  .selectionCard:focus-within .selectionActions {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .selectionActions {
+    transition: none;
+  }
+}

apps/nextjs/src/components/board/items/item-select-modal.tsx

@@ -3,10 +3,12 @@ import { Avatar, Box, Button, Card, Center, Divider, Group, Image, Stack, Text,
 import { IconApi } from "@tabler/icons-react";
 
 import { clientApi } from "@homarr/api/client";
+import { usePersistBoard } from "@homarr/boards/updater";
 import { createId, objectEntries } from "@homarr/common";
 import { getIconUrl, getIntegrationName } from "@homarr/definitions";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
 import { createModal, modalSizeSelect, useModalAction } from "@homarr/modals";
+import { showErrorNotification } from "@homarr/notifications";
 import { useSettings } from "@homarr/settings";
 import { useI18n } from "@homarr/translation/client";
 import { SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
@@ -15,15 +17,47 @@ import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/wid
 import { WidgetEditModal } from "@homarr/widgets/modals";
 
 import { useItemActions } from "./item-actions";
+import type { BoardPlacementHint, CreateItemInput } from "./actions/create-item";
+import { createItemCallback } from "./actions/create-item";
+import classes from "./item-select-modal.module.css";
 
-export const ItemSelectModal = createModal<void>(({ actions }) => {
+interface ItemSelectModalProps {
+  placement?: BoardPlacementHint;
+  board: { id: string; name: string };
+  persistImmediately: boolean;
+}
+
+export const ItemSelectModal = createModal<ItemSelectModalProps>(({ actions, innerProps }) => {
   const [search, setSearch] = useState("");
   const t = useI18n();
-  const { createItem, updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations } = useItemActions();
+  const { createItem } = useItemActions();
   const { openModal: openEditModal } = useModalAction(WidgetEditModal);
   const { data: integrationData } = clientApi.integration.all.useQuery();
   const { data: customWidgetDefs } = clientApi.customWidget.all.useQuery();
   const settings = useSettings();
+  const { updateAndPersistBoard } = usePersistBoard(innerProps.board);
+
+  const createAndPersist = (input: CreateItemInput) => {
+    try {
+      if (!innerProps.persistImmediately) {
+        createItem(input);
+        return;
+      }
+      updateAndPersistBoard(createItemCallback(input), {
+        onError: () => {
+          showErrorNotification({
+            title: t("item.create.notification.error.title"),
+            message: t("item.create.notification.error.message"),
+          });
+        },
+      });
+    } catch {
+      showErrorNotification({
+        title: t("item.create.notification.error.title"),
+        message: t("item.create.notification.error.message"),
+      });
+    }
+  };
 
   const availableKinds = useMemo(() => new Set((integrationData ?? []).map((i) => i.kind)), [integrationData]);
 
@@ -69,8 +103,13 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
   const handleAddCustomWidget = (definitionId: string) => {
     const itemId = createId();
     const defaultOptions = reduceWidgetOptionsWithDefaultValues("customApi", settings);
-    createItem({ id: itemId, kind: "customApi", integrationIds: [] });
-    updateItemOptions({ itemId, newOptions: { ...defaultOptions, definitionId } });
+    createAndPersist({
+      id: itemId,
+      kind: "customApi",
+      integrationIds: [],
+      options: { ...defaultOptions, definitionId },
+      placement: innerProps.placement,
+    });
     actions.closeModal();
   };
 
@@ -88,7 +127,6 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
     const itemId = createId();
     const defaultOptions = reduceWidgetOptionsWithDefaultValues(kind, settings);
 
-    createItem({ id: itemId, kind, integrationIds });
     actions.closeModal();
 
     openEditModal(
@@ -100,13 +138,19 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
           integrationIds,
         },
         onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
-          updateItemOptions({ itemId, newOptions: options });
-          updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
-          updateItemIntegrations({ itemId, newIntegrations: newIntegrationIds });
+          createAndPersist({
+            id: itemId,
+            kind,
+            options,
+            integrationIds: newIntegrationIds,
+            advancedOptions,
+            placement: innerProps.placement,
+          });
         },
         integrationData: matchingIntegrations,
         integrationSupport: hasIntegrationSupport,
         settings,
+        boardId: innerProps.board.id,
       },
       {
         title: (titleT) => `${titleT("item.edit.title")} - ${titleT(`widget.${kind}.name`)}`,
@@ -144,19 +188,18 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
             style={{ gridColumn: "1 / -1" }}
           />
           {filteredCustomWidgets.map((def) => (
-            <Card
-              key={def.id}
-              h={selectGridCardHeight}
-              withBorder
-              pos="relative"
-              style={{ overflow: "hidden", "--_hover-opacity": "0" }}
-              onMouseEnter={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "1")}
-              onMouseLeave={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "0")}
-            >
+            <Card key={def.id} h={selectGridCardHeight} withBorder pos="relative" className={classes.selectionCard}>
               <Stack h="100%" gap="xs">
                 <Group gap="sm" wrap="nowrap" align="flex-start">
                   {def.iconUrl ? (
-                    <Image src={def.iconUrl} w={22} h={22} fit="contain" style={{ flexShrink: 0, marginTop: 2 }} />
+                    <Image
+                      src={def.iconUrl}
+                      alt=""
+                      w={22}
+                      h={22}
+                      fit="contain"
+                      style={{ flexShrink: 0, marginTop: 2 }}
+                    />
                   ) : (
                     <IconApi size={22} style={{ flexShrink: 0, marginTop: 2 }} />
                   )}
@@ -174,9 +217,8 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
                 left={0}
                 right={0}
                 p="xs"
+                className={classes.selectionActions}
                 style={{
-                  opacity: "var(--_hover-opacity)",
-                  transition: "opacity 150ms ease",
                   background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
                 }}
               >
@@ -223,14 +265,11 @@ const WidgetItem = ({
       h={selectGridCardHeight}
       withBorder
       pos="relative"
+      className={classes.selectionCard}
       style={{
-        overflow: "hidden",
-        "--_hover-opacity": "0",
         borderColor: hasMatchingIntegration ? "var(--mantine-color-blue-6)" : undefined,
         borderWidth: hasMatchingIntegration ? 2 : undefined,
       }}
-      onMouseEnter={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "1")}
-      onMouseLeave={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "0")}
     >
       <Stack h="100%" gap="xs">
         <Group gap="sm" wrap="nowrap" align="flex-start">
@@ -244,6 +283,11 @@ const WidgetItem = ({
             {item.description}
           </Text>
         </Tooltip>
+        {hasMatchingIntegration && (
+          <Text size="10px" c="blue.6" fw={600}>
+            {t("item.create.integrationAvailable")}
+          </Text>
+        )}
         <SupportedIntegrations integrations={item.supportedIntegrations} />
       </Stack>
       <Box
@@ -252,9 +296,8 @@ const WidgetItem = ({
         left={0}
         right={0}
         p="xs"
+        className={classes.selectionActions}
         style={{
-          opacity: "var(--_hover-opacity)",
-          transition: "opacity 150ms ease",
           background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
         }}
       >

apps/nextjs/src/components/board/items/widget-context-menu.tsx

@@ -1,35 +1,40 @@
 "use client";
 
-import type { MutableRefObject, ReactNode } from "react";
-import { useCallback, useMemo } from "react";
+import type { MutableRefObject, ReactNode, RefObject } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { Group, Loader, Menu, Switch, Text, Tooltip } from "@mantine/core";
 import {
   IconAlertTriangle,
   IconCircleCheck,
   IconCopy,
   IconLayoutKanban,
+  IconMaximize,
   IconRefresh,
   IconSettings,
   IconTrash,
 } from "@tabler/icons-react";
 import type { QueryClient, QueryKey } from "@tanstack/react-query";
-import { useIsFetching, useQueryClient } from "@tanstack/react-query";
+import { partialMatchKey, useIsFetching, useQueryClient } from "@tanstack/react-query";
 
 import { clientApi } from "@homarr/api/client";
-import { useSession } from "@homarr/auth/client";
+import { useIntegrationsWithInteractAccess, useSession } from "@homarr/auth/client";
 import { useRequiredBoard } from "@homarr/boards/context";
 import { useEditMode } from "@homarr/boards/edit-mode";
+import { usePersistBoard } from "@homarr/boards/updater";
 import { useTimeAgo } from "@homarr/common";
 import { useConfirmModal, useModalAction } from "@homarr/modals";
+import { showErrorNotification } from "@homarr/notifications";
 import { useSettings } from "@homarr/settings";
 import { translateIfNecessary } from "@homarr/translation";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";
 import type { TranslationFunction } from "@homarr/translation";
 import type { WidgetContextMenuAction } from "@homarr/widgets";
-import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
+import { getWidgetQueryKeys, reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
 import { WidgetEditModal } from "@homarr/widgets/modals";
 
 import type { SectionItem } from "~/app/[locale]/boards/_types";
+import { useAdvancedFocus } from "../advanced-focus/context";
+import { useBoardPermissions } from "../permissions/client";
 import { useSectionContext } from "../sections/section-context";
 import { useItemActions } from "./item-actions";
 import { ItemMoveModal } from "./item-move-modal";
@@ -37,13 +42,16 @@ import { ItemMoveModal } from "./item-move-modal";
 interface WidgetContextMenuProps {
   item: SectionItem;
   widgetStateRef: MutableRefObject<Record<string, unknown> | null>;
+  sourceRef: RefObject<HTMLElement | null>;
   children: ReactNode;
 }
 
-export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetContextMenuProps) => {
+export const WidgetContextMenu = ({ item, widgetStateRef, sourceRef, children }: WidgetContextMenuProps) => {
   const { data: session } = useSession();
   const [isEditMode] = useEditMode();
   const board = useRequiredBoard();
+  const { hasChangeAccess } = useBoardPermissions(board);
+  const { updateAndPersistBoard } = usePersistBoard(board);
   const tItem = useScopedI18n("item");
   const tMenu = useScopedI18n("item.menu.label");
   const t = useI18n();
@@ -55,19 +63,34 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
   const { updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations, duplicateItem, removeItem } =
     useItemActions();
   const { data: integrationData, isPending } = clientApi.integration.all.useQuery();
-  const { mutate: saveBoard } = clientApi.board.saveBoard.useMutation();
   const currentDefinition = useMemo(() => widgetImports[item.kind].definition, [item.kind]);
   const { gridstack } = useSectionContext().refs;
   const queryClient = useQueryClient();
+  const { open: openAdvancedFocus } = useAdvancedFocus();
+  const integrationsWithInteractAccess = useIntegrationsWithInteractAccess();
+  const [menuOpened, setMenuOpened] = useState(false);
 
-  const widgetQueryKey = useMemo(
-    () => ("queryKey" in currentDefinition ? (currentDefinition.queryKey as QueryKey) : [["widget", item.kind]]),
-    [currentDefinition, item.kind],
+  const widgetQueryKeys = useMemo(
+    () => getWidgetQueryKeys(currentDefinition as Parameters<typeof getWidgetQueryKeys>[0]),
+    [currentDefinition],
   );
-  const isWidgetFetching = useIsFetching({ queryKey: widgetQueryKey }) > 0;
+  const matchesWidgetQuery = useCallback(
+    (queryKey: QueryKey) => widgetQueryKeys.some((candidate) => partialMatchKey(queryKey, candidate)),
+    [widgetQueryKeys],
+  );
+  const isWidgetFetching =
+    useIsFetching({
+      type: "active",
+      predicate: (query) => matchesWidgetQuery(query.queryKey),
+    }) > 0;
   const handleRefetch = useCallback(() => {
-    void queryClient.refetchQueries({ queryKey: widgetQueryKey, type: "all" });
-  }, [queryClient, widgetQueryKey]);
+    void Promise.all(widgetQueryKeys.map((queryKey) => queryClient.refetchQueries({ queryKey, type: "active" })));
+  }, [queryClient, widgetQueryKeys]);
+
+  const canInteractWithSelectedIntegrations = useMemo(() => {
+    const allowedIds = new Set(integrationsWithInteractAccess.map(({ id }) => id));
+    return item.integrationIds.length > 0 && item.integrationIds.every((id) => allowedIds.has(id));
+  }, [integrationsWithInteractAccess, item.integrationIds]);
 
   const options = useMemo(
     () => reduceWidgetOptionsWithDefaultValues(item.kind, settings, item.options) as Record<string, unknown>,
@@ -76,11 +99,12 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
 
   type OptionDef = { type: string; skipContextMenu?: boolean };
   const toggleOptions = useMemo(() => {
+    if (!hasChangeAccess) return [];
     const rawOptions = currentDefinition.createOptions(settings) as unknown as Record<string, OptionDef>;
     return Object.entries(rawOptions).filter(([, def]) => def.type === "switch" && !def.skipContextMenu);
-  }, [currentDefinition, settings]);
+  }, [currentDefinition, hasChangeAccess, settings]);
 
-  const widgetContextActions = useMemo(() => {
+  const widgetContextActions = (() => {
     const def = currentDefinition as Record<string, unknown>;
     if (typeof def.contextActions !== "function") return [];
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -90,17 +114,29 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
         updateItemOptions({ itemId: item.id, newOptions: { ...options, ...partial } });
       },
       integrationIds: item.integrationIds,
-      context: { isEditMode, boardId: board.id, itemId: item.id },
+      context: {
+        isEditMode,
+        boardId: board.id,
+        itemId: item.id,
+        canInteractWithSelectedIntegrations,
+      },
       widgetStateRef,
     });
     return (Array.isArray(actions) ? actions : []) as WidgetContextMenuAction[];
-  }, [currentDefinition, options, item, updateItemOptions, isEditMode, board.id, widgetStateRef]);
+  })();
 
   const persistBoard = useCallback(
-    (updatedItems: typeof board.items) => {
-      saveBoard({ ...board, items: updatedItems });
+    (updater: (previous: typeof board) => typeof board) => {
+      updateAndPersistBoard(updater, {
+        onError: () => {
+          showErrorNotification({
+            title: t("item.menu.notification.saveError.title"),
+            message: t("item.menu.notification.saveError.message"),
+          });
+        },
+      });
     },
-    [board, saveBoard],
+    [t, updateAndPersistBoard],
   );
 
   const openEditModal = useCallback(() => {
@@ -113,12 +149,14 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
           integrationIds: item.integrationIds,
         },
         onSuccessfulEdit: (editResult) => {
-          updateItemOptions({ itemId: item.id, newOptions: editResult.options });
-          updateItemAdvancedOptions({ itemId: item.id, newAdvancedOptions: editResult.advancedOptions });
-          updateItemIntegrations({ itemId: item.id, newIntegrations: editResult.integrationIds });
-          if (!isEditMode) {
-            persistBoard(
-              board.items.map((boardItem) =>
+          if (isEditMode) {
+            updateItemOptions({ itemId: item.id, newOptions: editResult.options });
+            updateItemAdvancedOptions({ itemId: item.id, newAdvancedOptions: editResult.advancedOptions });
+            updateItemIntegrations({ itemId: item.id, newIntegrations: editResult.integrationIds });
+          } else {
+            persistBoard((previous) => ({
+              ...previous,
+              items: previous.items.map((boardItem) =>
                 boardItem.id !== item.id
                   ? boardItem
                   : {
@@ -128,7 +166,7 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
                       integrationIds: editResult.integrationIds,
                     },
               ),
-            );
+            }));
           }
         },
         integrationData: (integrationData ?? []).filter(
@@ -154,18 +192,22 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
     settings,
     isEditMode,
     persistBoard,
-    board,
   ]);
 
   const handleToggle = useCallback(
     (key: string) => (checked: boolean) => {
-      const newOptions = { ...options, [key]: checked };
-      updateItemOptions({ itemId: item.id, newOptions });
-      persistBoard(
-        board.items.map((boardItem) => (boardItem.id !== item.id ? boardItem : { ...boardItem, options: newOptions })),
-      );
+      if (isEditMode) {
+        updateItemOptions({ itemId: item.id, newOptions: { ...options, [key]: checked } });
+      } else {
+        persistBoard((previous) => ({
+          ...previous,
+          items: previous.items.map((boardItem) =>
+            boardItem.id !== item.id ? boardItem : { ...boardItem, options: { ...boardItem.options, [key]: checked } },
+          ),
+        }));
+      }
     },
-    [options, item.id, updateItemOptions, persistBoard, board],
+    [options, item.id, updateItemOptions, isEditMode, persistBoard],
   );
 
   if (!session) return <>{children}</>;
@@ -174,9 +216,28 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
   const visibleWidgetActions = widgetContextActions.filter((a) => !a.hidden);
 
   return (
-    <Menu shadow="md" width={300} closeOnItemClick={false} position="right-start" offset={4}>
+    <Menu
+      shadow="md"
+      width={300}
+      closeOnItemClick={false}
+      position="right-start"
+      offset={4}
+      opened={menuOpened}
+      onChange={setMenuOpened}
+    >
       <Menu.ContextMenu>{children}</Menu.ContextMenu>
       <Menu.Dropdown>
+        <Menu.Item
+          closeMenuOnClick
+          leftSection={<IconMaximize size={16} />}
+          onClick={() => {
+            if (sourceRef.current) openAdvancedFocus(item.id, sourceRef.current, true);
+          }}
+          disabled={isEditMode}
+        >
+          {t("item.advancedFocus.open")}
+        </Menu.Item>
+        <Menu.Divider />
         {toggleOptions.length > 0 && (
           <>
             <Menu.Label>{tMenu("options")}</Menu.Label>
@@ -248,20 +309,22 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
               {tMenu("refresh")}
               <WidgetQueryStatus
                 queryClient={queryClient}
-                queryKey={widgetQueryKey}
+                queryKeys={widgetQueryKeys}
                 isFetching={isWidgetFetching}
                 t={t}
               />
             </Group>
           </Menu.Item>
-          <Menu.Item
-            closeMenuOnClick
-            leftSection={<IconSettings size={16} />}
-            onClick={openEditModal}
-            disabled={isPending}
-          >
-            {tMenu("settings")}
-          </Menu.Item>
+          {hasChangeAccess && (
+            <Menu.Item
+              closeMenuOnClick
+              leftSection={<IconSettings size={16} />}
+              onClick={openEditModal}
+              disabled={isPending}
+            >
+              {tMenu("settings")}
+            </Menu.Item>
+          )}
         </>
 
         {isEditMode && (
@@ -290,16 +353,20 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
 
 interface WidgetQueryStatusProps {
   queryClient: QueryClient;
-  queryKey: QueryKey;
+  queryKeys: readonly QueryKey[];
   isFetching: boolean;
   t: TranslationFunction;
 }
 
-const WidgetQueryStatus = ({ queryClient, queryKey, isFetching, t }: WidgetQueryStatusProps) => {
-  const queries = queryClient.getQueryCache().findAll({ queryKey });
+const WidgetQueryStatus = ({ queryClient, queryKeys, isFetching, t }: WidgetQueryStatusProps) => {
+  const queries = queryClient.getQueryCache().findAll({
+    type: "active",
+    predicate: (query) => queryKeys.some((queryKey) => partialMatchKey(query.queryKey, queryKey)),
+  });
   const timestamps = queries.map((query) => query.state.dataUpdatedAt).filter(Boolean);
   const latest = timestamps.length > 0 ? Math.max(...timestamps) : 0;
-  const ageLabel = useTimeAgo(new Date(latest));
+  const ageLabel = useTimeAgo(new Date(latest || Date.now()));
+  const ageSuffix = latest > 0 ? ` · ${ageLabel}` : "";
 
   if (isFetching) {
     return (
@@ -334,7 +401,8 @@ const WidgetQueryStatus = ({ queryClient, queryKey, isFetching, t }: WidgetQuery
         <Group gap={4} wrap="nowrap">
           <IconAlertTriangle size={12} color="var(--mantine-color-red-6)" />
           <Text size="xs" c="red.6">
-            {t("item.menu.status.error")} · {ageLabel}
+            {t("item.menu.status.error")}
+            {ageSuffix}
           </Text>
         </Group>
       </Tooltip>
@@ -345,7 +413,8 @@ const WidgetQueryStatus = ({ queryClient, queryKey, isFetching, t }: WidgetQuery
     <Group gap={4} wrap="nowrap">
       <IconCircleCheck size={12} color="var(--mantine-color-green-6)" />
       <Text size="xs" c="dimmed">
-        {t("item.menu.status.success")} · {ageLabel}
+        {t("item.menu.status.success")}
+        {ageSuffix}
       </Text>
     </Group>
   );

apps/nextjs/src/components/board/items/widget-hover-overlay.module.css

@@ -13,10 +13,8 @@
     transform 150ms ease;
 }
 
-:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):hover)
-  .wrapper,
-:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):focus-within)
-  .wrapper {
+:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):hover) .wrapper,
+:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):focus-within) .wrapper {
   opacity: 1;
   transform: translateY(0);
 }

apps/nextjs/src/components/board/sections/gridstack/board-empty-space-context-menu.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import type { KeyboardEvent, MouseEvent, PointerEvent, PropsWithChildren } from "react";
+import { useEffect, useRef, useState } from "react";
+import type { BoxProps } from "@mantine/core";
+import { Box, Menu } from "@mantine/core";
+import { IconPlus } from "@tabler/icons-react";
+
+import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { useModalAction } from "@homarr/modals";
+import { useSettings } from "@homarr/settings";
+import { useI18n } from "@homarr/translation/client";
+
+import type { DynamicSectionItem, Section } from "~/app/[locale]/boards/_types";
+import { ItemSelectModal } from "../../items/item-select-modal";
+import { useBoardPermissions } from "../../permissions/client";
+import type { BoardPlacementHint } from "../../items/actions/create-item";
+import type { UseGridstackRefs } from "./use-gridstack";
+
+interface MenuState {
+  x: number;
+  y: number;
+  placement: BoardPlacementHint;
+}
+
+interface Props extends BoxProps {
+  section: Exclude<Section, { kind: "dynamic" }> | DynamicSectionItem;
+  refs: UseGridstackRefs;
+}
+
+export const BoardEmptySpaceContextMenu = ({ section, refs, children, ...boxProps }: PropsWithChildren<Props>) => {
+  const board = useRequiredBoard();
+  const currentLayoutId = useCurrentLayout();
+  const settings = useSettings();
+  const t = useI18n();
+  const { hasChangeAccess } = useBoardPermissions(board);
+  const { openModal } = useModalAction(ItemSelectModal);
+  const [isEditMode] = useEditMode();
+  const [menu, setMenu] = useState<MenuState | null>(null);
+  const longPressTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const returnFocusRef = useRef<HTMLElement | null>(null);
+
+  const enabled = hasChangeAccess && settings.enableRightClickOnWidgets;
+  const clearLongPress = () => {
+    if (longPressTimer.current === null) return;
+    clearTimeout(longPressTimer.current);
+    longPressTimer.current = null;
+  };
+
+  useEffect(
+    () => () => {
+      if (longPressTimer.current !== null) clearTimeout(longPressTimer.current);
+    },
+    [],
+  );
+  const resolvePlacement = (target: EventTarget | null, pageX: number, pageY: number) => {
+    const wrapper = refs.wrapperElement.current;
+    const gridstack = refs.gridstack.current;
+    if (!(target instanceof Element) || !wrapper || !gridstack) return null;
+    if (target.closest(".grid-stack") !== wrapper || target.closest(".grid-stack-item")) return null;
+
+    const cell = gridstack.getCellFromPixel({ left: pageX, top: pageY }, true);
+    const rowLimit = section.kind === "dynamic" ? section.height : undefined;
+    if (
+      cell.x < 0 ||
+      cell.y < 0 ||
+      cell.x >= gridstack.getColumn() ||
+      (rowLimit !== undefined && cell.y >= rowLimit) ||
+      !gridstack.isAreaEmpty(cell.x, cell.y, 1, 1)
+    ) {
+      return null;
+    }
+
+    return { sectionId: section.id, layoutId: currentLayoutId, xOffset: cell.x, yOffset: cell.y };
+  };
+
+  const handleContextMenu = (event: MouseEvent<HTMLDivElement>) => {
+    if (!enabled) return;
+    const placement = resolvePlacement(event.target, event.pageX, event.pageY);
+    if (!placement) return;
+    event.preventDefault();
+    event.stopPropagation();
+    setMenu({ x: event.clientX, y: event.clientY, placement });
+  };
+
+  const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
+    if (!enabled || event.pointerType !== "touch") return;
+    const placement = resolvePlacement(event.target, event.pageX, event.pageY);
+    if (!placement) return;
+    clearLongPress();
+    longPressTimer.current = setTimeout(() => {
+      setMenu({ x: event.clientX, y: event.clientY, placement });
+      navigator.vibrate?.(20);
+    }, 500);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (
+      !enabled ||
+      event.currentTarget !== event.target ||
+      (event.key !== "ContextMenu" && !(event.shiftKey && event.key === "F10"))
+    ) {
+      return;
+    }
+    const wrapper = event.currentTarget;
+    const gridstack = refs.gridstack.current;
+    if (!gridstack) return;
+
+    const rowCount = Math.max(1, section.kind === "dynamic" ? section.height : gridstack.getRow() + 1);
+    for (let yOffset = 0; yOffset < rowCount; yOffset++) {
+      for (let xOffset = 0; xOffset < gridstack.getColumn(); xOffset++) {
+        if (!gridstack.isAreaEmpty(xOffset, yOffset, 1, 1)) continue;
+        const rect = wrapper.getBoundingClientRect();
+        event.preventDefault();
+        returnFocusRef.current = wrapper;
+        setMenu({
+          x: rect.left + 24,
+          y: rect.top + 24,
+          placement: { sectionId: section.id, layoutId: currentLayoutId, xOffset, yOffset },
+        });
+        return;
+      }
+    }
+  };
+
+  return (
+    <>
+      <Box
+        {...boxProps}
+        ref={refs.wrapper}
+        tabIndex={enabled ? 0 : undefined}
+        aria-label={enabled ? t("item.create.addAtPosition") : undefined}
+        onContextMenu={handleContextMenu}
+        onKeyDown={handleKeyDown}
+        onPointerDown={handlePointerDown}
+        onPointerMove={clearLongPress}
+        onPointerUp={clearLongPress}
+        onPointerCancel={clearLongPress}
+        onPointerLeave={clearLongPress}
+      >
+        {children}
+      </Box>
+      <Menu
+        opened={menu !== null}
+        onChange={(opened) => {
+          if (!opened) {
+            setMenu(null);
+            const returnFocus = returnFocusRef.current;
+            returnFocusRef.current = null;
+            requestAnimationFrame(() => returnFocus?.focus());
+          }
+        }}
+        withinPortal
+        position="bottom-start"
+      >
+        <Menu.Target>
+          <Box pos="fixed" left={menu?.x ?? 0} top={menu?.y ?? 0} w={1} h={1} style={{ pointerEvents: "none" }} />
+        </Menu.Target>
+        <Menu.Dropdown>
+          <Menu.Item
+            leftSection={<IconPlus size={18} />}
+            onClick={() => {
+              returnFocusRef.current = null;
+              if (menu) {
+                openModal({ placement: menu.placement, board, persistImmediately: !isEditMode });
+              }
+              setMenu(null);
+            }}
+          >
+            {t("item.create.addAtPosition")}
+          </Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+    </>
+  );
+};

apps/nextjs/src/components/board/sections/gridstack/gridstack.tsx

@@ -1,13 +1,13 @@
 "use client";
 
 import type { BoxProps } from "@mantine/core";
-import { Box } from "@mantine/core";
 import combineClasses from "clsx";
 
 import type { DynamicSectionItem, Section } from "~/app/[locale]/boards/_types";
 import { SectionContent } from "../content";
 import { SectionProvider } from "../section-context";
 import { useSectionItems } from "../use-section-items";
+import { BoardEmptySpaceContextMenu } from "./board-empty-space-context-menu";
 import { useGridstack } from "./use-gridstack";
 
 interface Props extends BoxProps {
@@ -22,15 +22,16 @@ export const GridStack = ({ section, ...props }: Props) => {
 
   return (
     <SectionProvider value={{ section, items, innerSections, refs }}>
-      <Box
+      <BoardEmptySpaceContextMenu
         {...props}
+        section={section}
+        refs={refs}
         data-kind={section.kind}
         data-section-id={section.id}
         className={combineClasses(`grid-stack grid-stack-${section.kind}`, props.className)}
-        ref={refs.wrapper}
       >
         <SectionContent />
-      </Box>
+      </BoardEmptySpaceContextMenu>
     </SectionProvider>
   );
 };

apps/nextjs/src/components/board/sections/gridstack/use-gridstack.ts

@@ -14,6 +14,7 @@ import { initializeGridstack } from "./init-gridstack";
 
 export interface UseGridstackRefs {
   wrapper: Ref<HTMLDivElement | null>;
+  wrapperElement: RefObject<HTMLDivElement | null>;
   items: RefObject<Record<string, RefObject<GridItemHTMLElement | null>>>;
   gridstack: RefObject<GridStack | null>;
 }
@@ -287,6 +288,7 @@ export const useGridstack = (section: Omit<Section, "items">, itemIds: string[])
     refs: {
       items: itemRefs,
       wrapper: wrapperRef,
+      wrapperElement: wrapperElementRef,
       gridstack: gridRef,
     },
   };

apps/nextjs/src/components/layout/constants.ts

@@ -0,0 +1 @@
+export const appShellHeaderHeight = 60;

apps/nextjs/src/components/layout/shell.tsx

@@ -5,6 +5,7 @@ import { AppShell } from "@mantine/core";
 import { useAtomValue } from "jotai";
 
 import { useOptionalBackgroundProps } from "./background";
+import { appShellHeaderHeight } from "./constants";
 import { navigationCollapsedAtom } from "./header/burger";
 
 interface ClientShellProps {
@@ -23,7 +24,7 @@ export const ClientShell = ({
   return (
     <AppShell
       {...backgroundProps}
-      header={hasHeader ? { height: 60 } : undefined}
+      header={hasHeader ? { height: appShellHeaderHeight } : undefined}
       navbar={
         hasNavigation
           ? {

e2e/board-advanced-interactions.spec.ts

@@ -0,0 +1,364 @@
+import type { Browser, BrowserContext, Locator, Page } from "@playwright/test";
+import { chromium, expect } from "@playwright/test";
+import { createId } from "@paralleldrive/cuid2";
+import { eq } from "drizzle-orm";
+import { stringify } from "superjson";
+import { afterAll, beforeAll, describe, test } from "vitest";
+
+import { hashPasswordAsync } from "../packages/auth/security";
+import {
+  boardUserPermissions,
+  boards,
+  itemLayouts,
+  items,
+  layouts,
+  sections,
+  users,
+} from "../packages/db/schema/sqlite";
+import type { SqliteDatabase } from "./shared/e2e-db";
+import { createSqliteDbFileAsync } from "./shared/e2e-db";
+import { createHomarrContainer } from "./shared/create-homarr-container";
+import { seedAdminUserAsync } from "./shared/seed-admin-user";
+
+const ownerCredentials = { username: "owner", password: "Comp(exP4sswOrd" };
+const disabledModifierCredentials = { username: "modifier", password: "Comp(exP4sswOrd" };
+const viewerCredentials = { username: "viewer", password: "Comp(exP4sswOrd" };
+const boardName = "advanced-interactions-e2e";
+
+describe("Board advanced interactions", () => {
+  let browser: Browser;
+  let baseUrl: string;
+  let stopContainerAsync: (() => Promise<void>) | undefined;
+
+  beforeAll(async () => {
+    const { db, localMountPath } = await createSqliteDbFileAsync();
+    const { userId: ownerId } = await seedAdminUserAsync(db, ownerCredentials);
+    await seedInteractionBoardAsync(db, ownerId);
+    await seedCredentialsUserAsync(db, {
+      ...disabledModifierCredentials,
+      enableRightClickOnWidgets: false,
+      boardPermission: "modify",
+    });
+    await seedCredentialsUserAsync(db, {
+      ...viewerCredentials,
+      enableRightClickOnWidgets: true,
+      boardPermission: "view",
+    });
+
+    const homarrContainer = await createHomarrContainer({
+      environment: { AUTH_PROVIDERS: "credentials" },
+      mounts: { "/appdata": localMountPath },
+    }).start();
+    stopContainerAsync = async () => {
+      await homarrContainer.stop();
+    };
+    baseUrl = `http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`;
+    browser = await chromium.launch();
+  }, 120_000);
+
+  afterAll(async () => {
+    await browser?.close();
+    await stopContainerAsync?.();
+  });
+
+  test("opens advanced view from Shift-hover, keyboard, and the widget context menu", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, ownerCredentials);
+
+    try {
+      const widget = page.locator(".grid-stack-item[data-kind='clock'] > .grid-stack-item-content").first();
+      const compactSurface = widget.locator(".clock-wrapper");
+      const advancedDialog = page.getByRole("dialog", { name: "Date and time advanced view" });
+
+      await compactSurface.evaluate((element) => {
+        element.setAttribute("data-lifecycle-probe", "same-instance");
+      });
+      await widget.focus();
+      await page.keyboard.down("Shift");
+      await widget.hover();
+      await expect(advancedDialog).toBeVisible({ timeout: 2_000 });
+      await expect(advancedDialog).toHaveAttribute("data-lifecycle-probe", "same-instance");
+      await expect(widget).toBeFocused();
+      await page.keyboard.up("Shift");
+      await expect(advancedDialog).toBeHidden();
+      await expect(compactSurface).toHaveAttribute("data-lifecycle-probe", "same-instance");
+      await expect(widget).toBeFocused();
+
+      await page.keyboard.down("Shift");
+      await widget.hover();
+      await expect(advancedDialog).toBeVisible({ timeout: 2_000 });
+      await page.getByRole("button", { name: "Keep advanced view open" }).click();
+      const pinnedButton = page.getByRole("button", { name: "Advanced view is pinned" });
+      await expect(pinnedButton).toBeFocused();
+      await page.keyboard.up("Shift");
+      await expect(advancedDialog).toBeVisible();
+      await page.keyboard.press("Shift+Tab");
+      await expect(advancedDialog).toBeVisible();
+      await expect(page.getByRole("button", { name: "Close advanced view" })).toBeFocused();
+      await page.keyboard.press("Escape");
+      await expect(advancedDialog).toBeHidden();
+      await expect(widget).toBeFocused();
+
+      await page.keyboard.press("Shift+Enter");
+      await expect(advancedDialog).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(advancedDialog).toBeHidden();
+      await expect(widget).toBeFocused();
+
+      await widget.click({ button: "right" });
+      await page.getByRole("menuitem", { name: "Open advanced view" }).click();
+      await expect(advancedDialog).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(advancedDialog).toBeHidden();
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+
+  test("preserves iframe browsing state and dismisses focus when a responsive layout remounts", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, ownerCredentials);
+
+    try {
+      const iframeSlot = page.locator(".grid-stack-item[data-kind='iframe'] > .grid-stack-item-content").first();
+      const iframe = iframeSlot.locator("iframe");
+      await iframe.evaluate((element) => {
+        element.srcdoc = '<label>State <input id="state" value="initial"></label>';
+      });
+      const frame = page.frameLocator(".grid-stack-item[data-kind='iframe'] iframe");
+      await frame.locator("#state").fill("changed");
+
+      await iframeSlot.focus();
+      await page.keyboard.press("Shift+Enter");
+      await expect(page.getByRole("dialog", { name: "iFrame advanced view" })).toBeVisible();
+      await expect(frame.locator("#state")).toHaveValue("changed");
+      await page.keyboard.press("Escape");
+      await expect(frame.locator("#state")).toHaveValue("changed");
+
+      await iframeSlot.focus();
+      await page.keyboard.press("Shift+Enter");
+      await page.setViewportSize({ width: 800, height: 900 });
+      await expect(page.getByRole("dialog", { name: "iFrame advanced view" })).toBeHidden();
+      await expect(page.locator(".grid-stack-item[data-kind='iframe'] iframe")).toBeVisible();
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+
+  test("keeps advanced controls below the fixed header on short screens", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, ownerCredentials, { width: 1366, height: 768 });
+
+    try {
+      const widget = page.locator(".grid-stack-item[data-kind='clock'] > .grid-stack-item-content").first();
+      await widget.focus();
+      await page.keyboard.press("Shift+Enter");
+      const closeButton = page.getByRole("button", { name: "Close advanced view" });
+      const bounds = await closeButton.boundingBox();
+      expect(bounds).not.toBeNull();
+      if (!bounds) return;
+      expect(bounds.x).toBeGreaterThanOrEqual(0);
+      expect(bounds.y).toBeGreaterThanOrEqual(60);
+      expect(bounds.x + bounds.width).toBeLessThanOrEqual(1366);
+      expect(bounds.y + bounds.height).toBeLessThanOrEqual(768);
+      await closeButton.click();
+      await expect(page.getByRole("dialog", { name: "Date and time advanced view" })).toBeHidden();
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+
+  test("opens the add-at-position chooser only when right click and change access are enabled", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, ownerCredentials);
+
+    try {
+      const grid = page.locator(".grid-stack[data-kind='empty']");
+      const addHereMenuItem = page.getByRole("menuitem", { name: "Add item here" });
+      await expect(grid).toHaveAttribute("aria-label", "Add item here");
+
+      await grid.focus();
+      await page.keyboard.press("Shift+F10");
+      await expect(addHereMenuItem).toBeVisible();
+      await page.keyboard.press("Escape");
+      await expect(addHereMenuItem).toBeHidden();
+      await expect(grid).toBeFocused();
+
+      await touchAndHoldEmptyGridSpaceAsync(grid);
+      await expect(addHereMenuItem).toBeVisible({ timeout: 1_000 });
+      await page.keyboard.press("Escape");
+
+      await rightClickEmptyGridSpaceAsync(grid);
+      await addHereMenuItem.click();
+      await expect(page.getByRole("dialog").filter({ hasText: "Choose item to add" })).toBeVisible();
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+
+  test("honors the user setting gate even when the user can modify the board", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, disabledModifierCredentials);
+
+    try {
+      const widget = page.locator(".grid-stack-item[data-kind='clock'] > .grid-stack-item-content").first();
+      const grid = page.locator(".grid-stack[data-kind='empty']");
+
+      await widget.click({ button: "right" });
+      await expect(page.getByRole("menuitem", { name: "Open advanced view" })).toHaveCount(0);
+      await expect(grid).not.toHaveAttribute("aria-label", "Add item here");
+      await rightClickEmptyGridSpaceAsync(grid);
+      await expect(page.getByRole("menuitem", { name: "Add item here" })).toHaveCount(0);
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+
+  test("keeps read-only advanced viewing but blocks add-at-position without change access", async () => {
+    const { context, page } = await openBoardAsync(browser, baseUrl, viewerCredentials);
+
+    try {
+      const widget = page.locator(".grid-stack-item[data-kind='clock'] > .grid-stack-item-content").first();
+      const grid = page.locator(".grid-stack[data-kind='empty']");
+
+      await widget.click({ button: "right" });
+      await page.getByRole("menuitem", { name: "Open advanced view" }).click();
+      await expect(page.getByRole("dialog", { name: "Date and time advanced view" })).toBeVisible();
+      await page.keyboard.press("Escape");
+
+      await expect(grid).not.toHaveAttribute("aria-label", "Add item here");
+      await rightClickEmptyGridSpaceAsync(grid);
+      await expect(page.getByRole("menuitem", { name: "Add item here" })).toHaveCount(0);
+    } finally {
+      await context.close();
+    }
+  }, 60_000);
+});
+
+const openBoardAsync = async (
+  browser: Browser,
+  baseUrl: string,
+  credentials: { username: string; password: string },
+  viewport = { width: 1280, height: 900 },
+): Promise<{ context: BrowserContext; page: Page }> => {
+  const context = await browser.newContext({ reducedMotion: "reduce", viewport });
+  const page = await context.newPage();
+
+  await page.goto(`${baseUrl}/auth/login`);
+  await page.getByLabel("Username").fill(credentials.username);
+  await page.locator("#password").fill(credentials.password);
+  await page.locator("css=button[type='submit']").click();
+  await page.waitForURL(baseUrl, { timeout: 15_000 });
+  await page.goto(`${baseUrl}/boards/${boardName}`);
+  await expect(page.locator(".grid-stack-item[data-kind='clock'] .clock-wrapper").first()).toBeVisible({
+    timeout: 15_000,
+  });
+
+  return { context, page };
+};
+
+const rightClickEmptyGridSpaceAsync = async (grid: Locator) => {
+  const bounds = await grid.boundingBox();
+  expect(bounds).not.toBeNull();
+  if (!bounds) return;
+
+  await grid.click({
+    button: "right",
+    position: { x: bounds.width - 16, y: Math.min(24, bounds.height / 2) },
+  });
+};
+
+const touchAndHoldEmptyGridSpaceAsync = async (grid: Locator) => {
+  const bounds = await grid.boundingBox();
+  expect(bounds).not.toBeNull();
+  if (!bounds) return;
+
+  const clientX = bounds.x + bounds.width - 16;
+  const clientY = bounds.y + Math.min(24, bounds.height / 2);
+  await grid.dispatchEvent("pointerdown", { pointerType: "touch", clientX, clientY });
+  await new Promise((resolve) => setTimeout(resolve, 550));
+  await grid.dispatchEvent("pointerup", { pointerType: "touch", clientX, clientY });
+};
+
+const seedInteractionBoardAsync = async (db: SqliteDatabase, ownerId: string) => {
+  const boardId = createId();
+  const baseLayoutId = createId();
+  const desktopLayoutId = createId();
+  const sectionId = createId();
+  const clockItemId = createId();
+  const iframeItemId = createId();
+
+  await db.insert(boards).values({ id: boardId, name: boardName, creatorId: ownerId, isPublic: false });
+  await db.insert(layouts).values([
+    { id: baseLayoutId, name: "Base", columnCount: 12, breakpoint: 0, boardId },
+    { id: desktopLayoutId, name: "Desktop", columnCount: 12, breakpoint: 1000, boardId },
+  ]);
+  await db.insert(sections).values({ id: sectionId, kind: "empty", xOffset: 0, yOffset: 0, boardId });
+  await db.insert(items).values([
+    {
+      id: clockItemId,
+      kind: "clock",
+      boardId,
+      options: stringify({ is24HourFormat: true, showSeconds: false, showDate: true }),
+      advancedOptions: stringify({ title: null, customCssClasses: [], borderColor: "" }),
+    },
+    {
+      id: iframeItemId,
+      kind: "iframe",
+      boardId,
+      options: stringify({ embedUrl: "https://example.com", allowScrolling: true }),
+      advancedOptions: stringify({ title: null, customCssClasses: [], borderColor: "" }),
+    },
+  ]);
+  await db.insert(itemLayouts).values(
+    [baseLayoutId, desktopLayoutId].flatMap((layoutId) => [
+      {
+        itemId: clockItemId,
+        sectionId,
+        layoutId,
+        xOffset: 0,
+        yOffset: 0,
+        width: 4,
+        height: 3,
+      },
+      {
+        itemId: iframeItemId,
+        sectionId,
+        layoutId,
+        xOffset: 4,
+        yOffset: 0,
+        width: 4,
+        height: 3,
+      },
+    ]),
+  );
+  await db
+    .update(users)
+    .set({ homeBoardId: boardId, completedBoardTour: true, completedManageTour: true })
+    .where(eq(users.id, ownerId));
+};
+
+const seedCredentialsUserAsync = async (
+  db: SqliteDatabase,
+  input: {
+    username: string;
+    password: string;
+    enableRightClickOnWidgets: boolean;
+    boardPermission: "view" | "modify";
+  },
+) => {
+  const userId = createId();
+  const board = await db.query.boards.findFirst({ where: eq(boards.name, boardName) });
+  if (!board) throw new Error("Interaction board was not seeded");
+
+  await db.insert(users).values({
+    id: userId,
+    name: input.username,
+    provider: "credentials",
+    password: await hashPasswordAsync(input.password),
+    enableRightClickOnWidgets: input.enableRightClickOnWidgets,
+    homeBoardId: board.id,
+    completedBoardTour: true,
+    completedManageTour: true,
+  });
+  await db.insert(boardUserPermissions).values({
+    boardId: board.id,
+    userId,
+    permission: input.boardPermission,
+  });
+};

packages/api/src/router/test/widgets/patchmon.spec.ts

@@ -101,9 +101,7 @@ describe("patchmonRouter.getStats access control", () => {
     });
     const caller = createCaller(db, null);
 
-    await expect(caller.getStats({ integrationId })).rejects.toThrow(
-      new TRPCError({ code: "UNAUTHORIZED" }),
-    );
+    await expect(caller.getStats({ integrationId })).rejects.toThrow(new TRPCError({ code: "UNAUTHORIZED" }));
   });
 
   test("should throw FORBIDDEN for authenticated users without board or integration access", async () => {

packages/api/src/router/test/widgets/timetable.spec.ts

@@ -0,0 +1,114 @@
+import { stringify } from "superjson";
+import { describe, expect, it, vi } from "vitest";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import type { Database } from "@homarr/db";
+import { boards, items, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { timetableRouter } from "../../widgets/timetable";
+
+const mocks = vi.hoisted(() => ({ getTimetable: vi.fn(), searchStations: vi.fn() }));
+
+vi.mock("@homarr/request-handler/timetable", () => ({
+  timetableGetTimetableRequestHandler: {
+    handler: (input: unknown) => ({
+      getDataAsync: async () => {
+        mocks.getTimetable(input);
+        return { data: { stationId: "station", timestamp: new Date(0), entries: [] } };
+      },
+    }),
+  },
+  timetableSearchStationsRequestHandler: {
+    handler: (input: unknown) => ({
+      getDataAsync: async () => {
+        mocks.searchStations(input);
+        return { data: [] };
+      },
+    }),
+  },
+}));
+
+const createSession = (userId: string): Session => ({
+  user: { id: userId, permissions: [], colorScheme: "light" },
+  expires: new Date().toISOString(),
+});
+
+const createCaller = (db: Database, session: Session | null) =>
+  timetableRouter.createCaller({ db, deviceType: undefined, session });
+
+const createTimetableItemAsync = async (
+  db: Database,
+  { baseUrl, isPublic = true }: { baseUrl: string; isPublic?: boolean },
+) => {
+  const ownerId = createId();
+  const boardId = createId();
+  const itemId = createId();
+  await db.insert(users).values({ id: ownerId });
+  await db.insert(boards).values({ id: boardId, name: `board-${boardId}`, creatorId: ownerId, isPublic });
+  await db.insert(items).values({
+    id: itemId,
+    boardId,
+    kind: "timetable",
+    options: stringify({ baseUrl }),
+  });
+  return { boardId, itemId, ownerId };
+};
+
+describe("timetableRouter source authorization", () => {
+  it("allows itemless setup only for the fixed default provider", async () => {
+    const caller = createCaller(createDb(), null);
+
+    await expect(caller.searchStations({ baseUrl: "https://search.ch", query: "Bern" })).resolves.toEqual([]);
+    await expect(caller.searchStations({ baseUrl: "http://127.0.0.1:8080", query: "Bern" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  it("loads a persisted private endpoint only through a viewable timetable item", async () => {
+    const db = createDb();
+    const baseUrl = "http://timetable.internal:8080";
+    const { itemId } = await createTimetableItemAsync(db, { baseUrl });
+    const caller = createCaller(db, null);
+
+    await caller.getTimetable({ baseUrl, itemId, stationId: "station", limit: 10 });
+    expect(mocks.getTimetable).toHaveBeenLastCalledWith(expect.objectContaining({ baseUrl }));
+    await expect(
+      caller.getTimetable({ baseUrl: "http://127.0.0.1:8080", itemId, stationId: "station", limit: 10 }),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+
+  it("rejects a persisted endpoint when its board is not viewable", async () => {
+    const db = createDb();
+    const baseUrl = "http://timetable.internal:8080";
+    const { itemId } = await createTimetableItemAsync(db, { baseUrl, isPublic: false });
+
+    await expect(
+      createCaller(db, null).getTimetable({ baseUrl, itemId, stationId: "station", limit: 10 }),
+    ).rejects.toMatchObject({ code: "NOT_FOUND" });
+  });
+
+  it("allows board modifiers to search an unsaved self-hosted endpoint", async () => {
+    const db = createDb();
+    const baseUrl = "http://timetable.internal:8080";
+    const { boardId, ownerId } = await createTimetableItemAsync(db, { baseUrl: "https://search.ch", isPublic: false });
+    const caller = createCaller(db, createSession(ownerId));
+
+    await caller.searchStations({ baseUrl, boardId, query: "Bern" });
+    expect(mocks.searchStations).toHaveBeenLastCalledWith(expect.objectContaining({ baseUrl }));
+  });
+
+  it("does not treat public board view access as configuration access", async () => {
+    const db = createDb();
+    const baseUrl = "http://timetable.internal:8080";
+    const { boardId, itemId } = await createTimetableItemAsync(db, { baseUrl });
+
+    await expect(createCaller(db, null).searchStations({ baseUrl, boardId, query: "Bern" })).rejects.toMatchObject({
+      code: "NOT_FOUND",
+    });
+    await expect(createCaller(db, null).searchStations({ baseUrl, itemId, query: "Bern" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+});

packages/api/src/router/widgets/__tests__/beszel-failures.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+
+import { everyBeszelIntegrationFailed } from "../beszel-failures";
+
+describe("everyBeszelIntegrationFailed", () => {
+  it("keeps partial successes", () => {
+    expect(everyBeszelIntegrationFailed([{ error: "offline" }, {}])).toBe(false);
+  });
+
+  it("detects when every integration failed", () => {
+    expect(everyBeszelIntegrationFailed([{ error: "offline" }, { error: "timeout" }])).toBe(true);
+  });
+
+  it("allows an empty integration selection", () => {
+    expect(everyBeszelIntegrationFailed([])).toBe(false);
+  });
+});

packages/api/src/router/widgets/__tests__/custom-api-security.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+
+import { readBoundedJsonResponseAsync, validateCustomApiUrl } from "../custom-api-security";
+
+describe("custom API request hardening", () => {
+  it("accepts HTTP endpoints without embedded credentials", () => {
+    expect(validateCustomApiUrl("https://api.example.com/v1/data").hostname).toBe("api.example.com");
+  });
+
+  it.each(["file:///etc/passwd", "https://user:secret@example.com/data"])("rejects unsafe URL %s", (url) => {
+    expect(() => validateCustomApiUrl(url)).toThrow();
+  });
+
+  it("rejects a response once its byte budget is exceeded", async () => {
+    const response = new Response(JSON.stringify({ value: "x".repeat(100) }));
+    await expect(readBoundedJsonResponseAsync(response, 32)).rejects.toThrow("exceeds 32 bytes");
+  });
+});

packages/api/src/router/widgets/beszel-failures.ts

@@ -0,0 +1,5 @@
+export const everyBeszelIntegrationFailed = (results: readonly unknown[]) =>
+  results.length > 0 &&
+  results.every(
+    (result) => typeof result === "object" && result !== null && "error" in result && result.error !== undefined,
+  );

packages/api/src/router/widgets/beszel.ts

@@ -13,6 +13,7 @@ import {
 import { settleIntegrationQueries } from "../../settle-integrations";
 import { createManyIntegrationMiddleware } from "../../middlewares/integration";
 import { createTRPCRouter, publicProcedure } from "../../trpc";
+import { everyBeszelIntegrationFailed } from "./beszel-failures";
 import { BoundedAsyncQueue } from "./bounded-async-queue";
 
 const logger = createLogger({ module: "beszelRouter" });
@@ -20,6 +21,20 @@ const MAX_PENDING_LIVE_EVENTS = 4;
 
 const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
 
+function throwIfEveryBeszelIntegrationFailed(results: readonly unknown[], operation: string) {
+  if (everyBeszelIntegrationFailed(results)) {
+    const firstError = results[0];
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: `Every Beszel integration failed while loading ${operation}: ${
+        typeof firstError === "object" && firstError !== null && "error" in firstError
+          ? String(firstError.error)
+          : "unknown error"
+      }`,
+    });
+  }
+}
+
 export const beszelRouter = createTRPCRouter({
   getSystems: publicProcedure
     .meta({
@@ -63,6 +78,7 @@ export const beszelRouter = createTRPCRouter({
         resultCount: results.length,
         errorCount: results.filter((r) => "error" in r).length,
       });
+      throwIfEveryBeszelIntegrationFailed(results, "systems");
       return results;
     }),
 
@@ -136,6 +152,7 @@ export const beszelRouter = createTRPCRouter({
         resultCount: results.length,
         errorCount: results.filter((r) => "error" in r).length,
       });
+      throwIfEveryBeszelIntegrationFailed(results, "alerts");
       return results;
     }),
 

packages/api/src/router/widgets/calendar.ts

@@ -1,16 +1,13 @@
 import { z } from "zod/v4";
 
-import { createLogger } from "@homarr/core/infrastructure/logs";
-import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
 import { getIntegrationKindsByCategory } from "@homarr/definitions";
 import { radarrReleaseTypes } from "@homarr/integrations/types";
 import { calendarMonthRequestHandler } from "@homarr/request-handler/calendar";
 
 import { createManyIntegrationMiddleware } from "../../middlewares/integration";
+import { settleIntegrationQueries } from "../../settle-integrations";
 import { createTRPCRouter, publicProcedure } from "../../trpc";
 
-const logger = createLogger({ module: "calendarRouter" });
-
 export const calendarRouter = createTRPCRouter({
   findAllEvents: publicProcedure
     .meta({
@@ -30,39 +27,19 @@ export const calendarRouter = createTRPCRouter({
     )
     .concat(createManyIntegrationMiddleware("query", ...getIntegrationKindsByCategory("calendar")))
     .query(async ({ ctx, input }) => {
-      const settled = await Promise.allSettled(
-        ctx.integrations.map(async (integration) => {
-          const { integrationIds: _integrationIds, ...handlerInput } = input;
-          const innerHandler = calendarMonthRequestHandler.handler(integration, handlerInput);
-          const { data } = await innerHandler.getDataAsync();
+      return await settleIntegrationQueries(ctx.integrations, async (integration) => {
+        const { integrationIds: _integrationIds, ...handlerInput } = input;
+        const innerHandler = calendarMonthRequestHandler.handler(integration, handlerInput);
+        const { data } = await innerHandler.getDataAsync();
 
-          return {
-            events: data,
-            integration: {
-              id: integration.id,
-              name: integration.name,
-              kind: integration.kind,
-            },
-          };
-        }),
-      );
-
-      return settled.flatMap((result, index) => {
-        if (result.status === "fulfilled") {
-          return [result.value];
-        }
-        const integration = ctx.integrations[index];
-        logger.warn(
-          new ErrorWithMetadata(
-            "Calendar integration request failed; skipping events for this integration",
-            {
-              integrationId: integration?.id,
-              integrationKind: integration?.kind,
-            },
-            { cause: result.reason },
-          ),
-        );
-        return [];
+        return {
+          events: data,
+          integration: {
+            id: integration.id,
+            name: integration.name,
+            kind: integration.kind,
+          },
+        };
       });
     }),
 });

packages/api/src/router/widgets/custom-api-security.ts

@@ -0,0 +1,21 @@
+import { readBoundedJsonResponseAsync as readBoundedJsonResponse } from "@homarr/common/server";
+
+export const MAX_CUSTOM_API_RESPONSE_BYTES = 2 * 1024 * 1024;
+
+export function validateCustomApiUrl(urlString: string): URL {
+  if (urlString.length > 2_048) throw new Error("Custom API URL is too long");
+
+  const url = new URL(urlString);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Custom API URL must use HTTP or HTTPS");
+  }
+  if (url.username || url.password) throw new Error("Custom API URL must not contain credentials");
+  return url;
+}
+
+export async function readBoundedJsonResponseAsync(
+  response: Response,
+  maxBytes = MAX_CUSTOM_API_RESPONSE_BYTES,
+): Promise<unknown> {
+  return await readBoundedJsonResponse(response, maxBytes, "Custom API response");
+}

packages/api/src/router/widgets/custom-api.ts

@@ -9,13 +9,12 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
 import { createTRPCRouter, protectedProcedure } from "../../trpc";
 import { applyAuth } from "../custom-widget/auth";
 import { extractActionButtonDisplay, extractDisplayDataWithFallback } from "../custom-widget/display-data";
+import { readBoundedJsonResponseAsync, validateCustomApiUrl } from "./custom-api-security";
 
 const logger = createLogger({ module: "widget:customApi" });
 
 const FETCH_TIMEOUT_MS = 10_000;
 
-const validateUrl = (urlString: string): URL => new URL(urlString);
-
 export const customApiRouter = createTRPCRouter({
   getData: protectedProcedure.input(z.object({ definitionId: z.string() })).query(async ({ ctx, input }) => {
     const definition = await ctx.db.query.customWidgetDefinitions.findFirst({
@@ -47,7 +46,7 @@ export const customApiRouter = createTRPCRouter({
       value: decryptSecret(s.value),
     }));
 
-    const url = validateUrl(definition.url);
+    const url = validateCustomApiUrl(definition.url);
     const headers = new Headers({ Accept: "application/json" });
 
     if (definition.method !== "GET" && definition.requestBody) {
@@ -64,7 +63,7 @@ export const customApiRouter = createTRPCRouter({
         method: definition.method,
         headers,
         body: definition.method !== "GET" ? definition.requestBody : undefined,
-        redirect: "follow",
+        redirect: "error",
         signal: controller.signal,
       });
 
@@ -75,7 +74,7 @@ export const customApiRouter = createTRPCRouter({
         });
       }
 
-      const json: unknown = await response.json();
+      const json = await readBoundedJsonResponseAsync(response);
       return extractDisplayDataWithFallback(json, definition.displayType, displayConfig);
     } catch (error) {
       if (error instanceof TRPCError) throw error;

packages/api/src/router/widgets/firewall.ts

@@ -18,20 +18,33 @@ const queryFirewall = <
   },
 >(
   handler: THandler,
+  createFallback: () => Awaited<ReturnType<ReturnType<THandler["handler"]>["getDataAsync"]>>["data"],
 ) =>
   publicProcedure.concat(firewallMiddleware).query(async ({ ctx }) =>
-    settleIntegrationQueries(ctx.integrations, async (integration) => {
-      const { data, timestamp } = await handler.handler(integration, {}).getDataAsync();
-      return {
-        integration: { id: integration.id, name: integration.name, kind: integration.kind, updatedAt: timestamp },
-        summary: data as Awaited<ReturnType<ReturnType<THandler["handler"]>["getDataAsync"]>>["data"],
-      };
-    }),
+    settleIntegrationQueries(
+      ctx.integrations,
+      async (integration) => {
+        const { data, timestamp } = await handler.handler(integration, {}).getDataAsync();
+        return {
+          integration: { id: integration.id, name: integration.name, kind: integration.kind, updatedAt: timestamp },
+          summary: data as Awaited<ReturnType<ReturnType<THandler["handler"]>["getDataAsync"]>>["data"],
+          error: undefined as string | undefined,
+        };
+      },
+      {
+        fallback: (integration, error) => ({
+          integration: { id: integration.id, name: integration.name, kind: integration.kind, updatedAt: new Date(0) },
+          summary: createFallback(),
+          error: error instanceof Error ? error.message : "Integration request failed",
+        }),
+        throwOnAllFailures: true,
+      },
+    ),
   );
 
 export const firewallRouter = createTRPCRouter({
-  getFirewallCpuStatus: queryFirewall(firewallCpuRequestHandler),
-  getFirewallInterfacesStatus: queryFirewall(firewallInterfacesRequestHandler),
-  getFirewallVersionStatus: queryFirewall(firewallVersionRequestHandler),
-  getFirewallMemoryStatus: queryFirewall(firewallMemoryRequestHandler),
+  getFirewallCpuStatus: queryFirewall(firewallCpuRequestHandler, () => ({ total: 0 })),
+  getFirewallInterfacesStatus: queryFirewall(firewallInterfacesRequestHandler, () => []),
+  getFirewallVersionStatus: queryFirewall(firewallVersionRequestHandler, () => ({ version: "Unknown" })),
+  getFirewallMemoryStatus: queryFirewall(firewallMemoryRequestHandler, () => ({ used: 0, total: 0, percent: 0 })),
 });

packages/api/src/router/widgets/indexer-manager.ts

@@ -16,15 +16,29 @@ export const indexerManagerRouter = createTRPCRouter({
   getIndexersStatus: publicProcedure
     .concat(createIndexerManagerIntegrationMiddleware("query"))
     .query(async ({ ctx }) => {
-      return await settleIntegrationQueries(ctx.integrations, async (integration) => {
-        const innerHandler = indexerManagerRequestHandler.handler(integration, {});
-        const { data: indexers } = await innerHandler.getDataAsync();
+      return await settleIntegrationQueries(
+        ctx.integrations,
+        async (integration) => {
+          const innerHandler = indexerManagerRequestHandler.handler(integration, {});
+          const { data: indexers } = await innerHandler.getDataAsync();
 
-        return {
-          integrationId: integration.id,
-          indexers,
-        };
-      });
+          return {
+            integrationId: integration.id,
+            integrationName: integration.name,
+            indexers,
+            error: undefined as string | undefined,
+          };
+        },
+        {
+          fallback: (integration, error) => ({
+            integrationId: integration.id,
+            integrationName: integration.name,
+            indexers: [],
+            error: error instanceof Error ? error.message : String(error),
+          }),
+          throwOnAllFailures: true,
+        },
+      );
     }),
   testAllIndexers: protectedProcedure
     .concat(createIndexerManagerIntegrationMiddleware("interact"))

packages/api/src/router/widgets/media-organizer.ts

@@ -4,6 +4,7 @@ import { getIntegrationKindsByCategory } from "@homarr/definitions";
 import { mediaOrganizerRequestHandler } from "@homarr/request-handler/media-organizer";
 
 import { createManyIntegrationMiddleware } from "../../middlewares/integration";
+import { settleIntegrationQueries } from "../../settle-integrations";
 import { createTRPCRouter, publicProcedure } from "../../trpc";
 
 export const mediaOrganizerRouter = createTRPCRouter({
@@ -18,16 +19,30 @@ export const mediaOrganizerRouter = createTRPCRouter({
     .concat(createManyIntegrationMiddleware("query", ...getIntegrationKindsByCategory("mediaOrganizer")))
     .input(z.object({ pageSize: z.number().min(1).max(50).default(10) }))
     .query(async ({ ctx, input }) => {
-      const results = await Promise.all(
-        ctx.integrations.map(async (integration) => {
+      return await settleIntegrationQueries(
+        ctx.integrations,
+        async (integration) => {
           const innerHandler = mediaOrganizerRequestHandler.handler(integration, { pageSize: input.pageSize });
           const { data } = await innerHandler.getDataAsync();
           return {
             integrationId: integration.id,
+            integrationName: integration.name,
             ...data,
+            error: undefined as string | undefined,
           };
-        }),
+        },
+        {
+          fallback: (integration, error) => ({
+            integrationId: integration.id,
+            integrationName: integration.name,
+            missing: [],
+            missingCount: 0,
+            queued: [],
+            queuedCount: 0,
+            error: error instanceof Error ? error.message : String(error),
+          }),
+          throwOnAllFailures: true,
+        },
       );
-      return results;
     }),
 });