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"];