feat(widgets): add right-click context menu with auto-generated toggle actions

- Add WidgetContextMenu component using Mantine 9.3 Menu.ContextMenu
- Extend WidgetDefinition with contextActions API for widget-specific actions
- Auto-generate context menu toggle items for switch-type widget options
- Add 'Search' context action to media-requests widgets (list + stats)
- Keep existing dots-button menu for discoverability in edit mode
- Add widgetStateRef to WidgetComponentProps for client-side-only state
- Add skipContextMenu opt-out on switch option definitions

packages/widgets/src/definition.ts

@@ -1,3 +1,4 @@
+import type React from "react";
 import type { LoaderComponent } from "next/dynamic";
 import type { QueryClient } from "@tanstack/react-query";
 import type { DefaultErrorData } from "@trpc/server/unstable-core-do-not-import";
@@ -9,7 +10,35 @@ import type { stringOrTranslation } from "@homarr/translation";
 import type { TablerIcon } from "@homarr/ui";
 
 import type { WidgetImports } from ".";
-import type { inferOptionsFromCreator, WidgetOptionsRecord } from "./options";
+import type { inferOptionsFromCreator, inferOptionsFromDefinition, WidgetOptionsRecord } from "./options";
+
+export interface WidgetContextMenuAction {
+  key: string;
+  label: stringOrTranslation;
+  icon?: TablerIcon;
+  onClick: () => void;
+  hidden?: boolean;
+  disabled?: boolean;
+  color?: string;
+}
+
+export interface WidgetContextMenuContext {
+  isEditMode: boolean;
+  boardId: string | undefined;
+  itemId: string | undefined;
+}
+
+export interface WidgetContextActionProps<
+  TKind extends WidgetKind,
+  TOptions extends WidgetOptionsRecord = WidgetOptionsRecord,
+> {
+  kind: TKind;
+  options: inferOptionsFromDefinition<TOptions>;
+  setOptions: (partial: Partial<inferOptionsFromDefinition<TOptions>>) => void;
+  integrationIds: string[];
+  context: WidgetContextMenuContext;
+  widgetStateRef: React.MutableRefObject<Record<string, unknown> | null>;
+}
 
 const createWithDynamicImport =
   <TKind extends WidgetKind, TDefinition extends WidgetDefinition>(kind: TKind, definition: TDefinition) =>
@@ -56,6 +85,9 @@ export interface WidgetDefinition {
       }
     >
   >;
+  contextActions?: (
+    props: Omit<WidgetContextActionProps<WidgetKind>, "kind">,
+  ) => WidgetContextMenuAction[];
 }
 
 export interface WidgetProps<TKind extends WidgetKind> {
@@ -70,6 +102,7 @@ export type WidgetComponentProps<TKind extends WidgetKind> = WidgetProps<TKind>
   setOptions: ({ newOptions }: { newOptions: Partial<inferOptionsFromCreator<WidgetOptionsRecordOf<TKind>>> }) => void;
   width: number;
   height: number;
+  widgetStateRef?: React.MutableRefObject<Record<string, unknown> | null>;
 };
 
 export type WidgetOptionsRecordOf<TKind extends WidgetKind> = WidgetImports[TKind]["definition"]["createOptions"];

packages/widgets/src/index.tsx

@@ -61,7 +61,7 @@ import * as video from "./video";
 import * as weather from "./weather";
 import * as customApi from "./custom-api";
 
-export type { WidgetDefinition, WidgetOptionsSettings } from "./definition";
+export type { WidgetDefinition, WidgetContextMenuAction, WidgetContextActionProps, WidgetOptionsSettings } from "./definition";
 export type { WidgetComponentProps };
 export type { WidgetOptionDefinition, WidgetOptionType } from "./options";
 

packages/widgets/src/media-requests/list/index.ts

@@ -1,6 +1,7 @@
-import { IconZoomQuestion } from "@tabler/icons-react";
+import { IconSearch, IconZoomQuestion } from "@tabler/icons-react";
 
 import { getIntegrationKindsByCategory } from "@homarr/definitions";
+import { openMediaRequestSearch } from "@homarr/spotlight";
 
 import { createWidgetDefinition } from "../../definition";
 import { optionsBuilder } from "../../options";
@@ -14,5 +15,15 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaRequ
       }),
     }));
   },
+  contextActions: ({ integrationIds }) => [
+    {
+      key: "search",
+      label: (t) => t("search.mode.media.action.search.label"),
+      icon: IconSearch,
+      onClick: () => {
+        openMediaRequestSearch({ integrationIds });
+      },
+    },
+  ],
   supportedIntegrations: getIntegrationKindsByCategory("mediaRequest"),
 }).withDynamicImport(() => import("./component"));

packages/widgets/src/media-requests/stats/index.ts

@@ -1,6 +1,7 @@
-import { IconChartBar } from "@tabler/icons-react";
+import { IconChartBar, IconSearch } from "@tabler/icons-react";
 
 import { getIntegrationKindsByCategory } from "@homarr/definitions";
+import { openMediaRequestSearch } from "@homarr/spotlight";
 
 import { createWidgetDefinition } from "../../definition";
 
@@ -9,5 +10,15 @@ export const { componentLoader, definition } = createWidgetDefinition("mediaRequ
   createOptions() {
     return {};
   },
+  contextActions: ({ integrationIds }) => [
+    {
+      key: "search",
+      label: (t) => t("search.mode.media.action.search.label"),
+      icon: IconSearch,
+      onClick: () => {
+        openMediaRequestSearch({ integrationIds });
+      },
+    },
+  ],
   supportedIntegrations: getIntegrationKindsByCategory("mediaRequest"),
 }).withDynamicImport(() => import("./component"));

packages/widgets/src/options.ts

@@ -13,6 +13,7 @@ import type { ReleasesRepository } from "./releases/releases-repository";
 interface CommonInput<TType> {
   defaultValue?: TType;
   withDescription?: boolean;
+  skipContextMenu?: boolean;
 }
 
 interface TextInput extends CommonInput<string> {