feat(preferences): add enableRightClickOnWidgets user preference (#6298)

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_general-settings-form.tsx

@@ -31,6 +31,7 @@ import {
   userChangeHomeBoardsSchema,
   userChangeSearchPreferencesSchema,
   userEditProfileSchema,
+  userEnableRightClickOnWidgetsSchema,
   userFirstDayOfWeekSchema,
   userPingIconsEnabledSchema,
 } from "@homarr/validation/user";
@@ -51,6 +52,7 @@ const userGeneralSettingsSchema = z.object({
   ddgBangsEnabled: userChangeSearchPreferencesSchema.shape.ddgBangsEnabled,
   firstDayOfWeek: userFirstDayOfWeekSchema.shape.firstDayOfWeek,
   pingIconsEnabled: userPingIconsEnabledSchema.shape.pingIconsEnabled,
+  enableRightClickOnWidgets: userEnableRightClickOnWidgetsSchema.shape.enableRightClickOnWidgets,
 });
 
 type FormValues = z.infer<typeof userGeneralSettingsSchema>;
@@ -78,6 +80,7 @@ const buildInitialValues = (user: RouterOutputs["user"]["getById"]): FormValues
   ddgBangsEnabled: user.ddgBangs,
   firstDayOfWeek: user.firstDayOfWeek as DayOfWeek,
   pingIconsEnabled: user.pingIconsEnabled,
+  enableRightClickOnWidgets: user.enableRightClickOnWidgets,
 });
 
 export const UserGeneralSettingsForm = ({
@@ -95,6 +98,7 @@ export const UserGeneralSettingsForm = ({
   const changeSearchPreferencesMutation = clientApi.user.changeSearchPreferences.useMutation();
   const changeFirstDayOfWeekMutation = clientApi.user.changeFirstDayOfWeek.useMutation();
   const changePingIconsEnabledMutation = clientApi.user.changePingIconsEnabled.useMutation();
+  const changeEnableRightClickOnWidgetsMutation = clientApi.user.changeEnableRightClickOnWidgets.useMutation();
 
   const initialValues = buildInitialValues(user);
   const initialValuesRef = useRef(initialValues);
@@ -114,6 +118,7 @@ export const UserGeneralSettingsForm = ({
     changeSearchPreferencesMutation,
     changeFirstDayOfWeekMutation,
     changePingIconsEnabledMutation,
+    changeEnableRightClickOnWidgetsMutation,
   ];
   const isPending = mutations.some((m) => m.isPending);
 
@@ -169,6 +174,14 @@ export const UserGeneralSettingsForm = ({
         action: () =>
           changePingIconsEnabledMutation.mutateAsync({ id: user.id, pingIconsEnabled: parsed.data.pingIconsEnabled }),
       },
+      {
+        when: changed("enableRightClickOnWidgets"),
+        action: () =>
+          changeEnableRightClickOnWidgetsMutation.mutateAsync({
+            id: user.id,
+            enableRightClickOnWidgets: parsed.data.enableRightClickOnWidgets,
+          }),
+      },
     ];
 
     const promises = saveActions.filter((s) => s.when).map((s) => s.action());
@@ -305,6 +318,11 @@ export const UserGeneralSettingsForm = ({
                 label={t("user.field.pingIconsEnabled.label")}
                 {...form.getInputProps("pingIconsEnabled", { type: "checkbox" })}
               />
+              <Switch
+                label={t("user.field.enableRightClickOnWidgets.label")}
+                description={t("user.field.enableRightClickOnWidgets.description")}
+                {...form.getInputProps("enableRightClickOnWidgets", { type: "checkbox" })}
+              />
             </Stack>
           </Card>
         </SimpleGrid>

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

@@ -48,6 +48,7 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
   const tMenu = useScopedI18n("item.menu.label");
   const t = useI18n();
   const settings = useSettings();
+  const isRightClickEnabled = settings.enableRightClickOnWidgets;
   const { openModal } = useModalAction(WidgetEditModal);
   const { openModal: openMoveModal } = useModalAction(ItemMoveModal);
   const { openConfirmModal } = useConfirmModal();
@@ -168,6 +169,7 @@ export const WidgetContextMenu = ({ item, widgetStateRef, children }: WidgetCont
   );
 
   if (!session) return <>{children}</>;
+  if (!isRightClickEnabled) return <>{children}</>;
 
   const visibleWidgetActions = widgetContextActions.filter((a) => !a.hidden);
 

packages/api/src/router/test/user.spec.ts

@@ -357,6 +357,83 @@ describe("delete should delete user", () => {
   });
 });
 
+describe("changeEnableRightClickOnWidgets should toggle the right-click preference", () => {
+  test("non-admin can toggle their own preference", async () => {
+    const db = createDb();
+    const caller = userRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    await db.insert(users).values({
+      id: defaultOwnerId,
+      name: "owner",
+    });
+
+    await caller.changeEnableRightClickOnWidgets({ id: defaultOwnerId, enableRightClickOnWidgets: false });
+
+    const updated = await db.query.users.findFirst({
+      where: eq(users.id, defaultOwnerId),
+      columns: { enableRightClickOnWidgets: true },
+    });
+    expect(updated?.enableRightClickOnWidgets).toBe(false);
+
+    await caller.changeEnableRightClickOnWidgets({ id: defaultOwnerId, enableRightClickOnWidgets: true });
+
+    const restored = await db.query.users.findFirst({
+      where: eq(users.id, defaultOwnerId),
+      columns: { enableRightClickOnWidgets: true },
+    });
+    expect(restored?.enableRightClickOnWidgets).toBe(true);
+  });
+
+  test("non-admin cannot toggle another user's preference", async () => {
+    const db = createDb();
+    const caller = userRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    const otherUserId = createId();
+    await db.insert(users).values({ id: defaultOwnerId });
+    await db.insert(users).values({ id: otherUserId, name: "other" });
+
+    await expect(
+      caller.changeEnableRightClickOnWidgets({ id: otherUserId, enableRightClickOnWidgets: false }),
+    ).rejects.toThrow("User not found");
+
+    const other = await db.query.users.findFirst({
+      where: eq(users.id, otherUserId),
+      columns: { enableRightClickOnWidgets: true },
+    });
+    expect(other?.enableRightClickOnWidgets).toBe(true);
+  });
+
+  test("admin can toggle another user's preference", async () => {
+    const db = createDb();
+    const adminSession = createSession(["admin"]);
+    const caller = userRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: adminSession,
+    });
+
+    const targetUserId = createId();
+    await db.insert(users).values({ id: defaultOwnerId });
+    await db.insert(users).values({ id: targetUserId, name: "target" });
+
+    await caller.changeEnableRightClickOnWidgets({ id: targetUserId, enableRightClickOnWidgets: false });
+
+    const target = await db.query.users.findFirst({
+      where: eq(users.id, targetUserId),
+      columns: { enableRightClickOnWidgets: true },
+    });
+    expect(target?.enableRightClickOnWidgets).toBe(false);
+  });
+});
+
 const createOnboardingStepAsync = async (db: Database, step: OnboardingStep) => {
   await db.insert(onboarding).values({
     id: createId(),

packages/api/src/router/user.ts

@@ -23,6 +23,7 @@ import {
   userCreateSchema,
   userDdgBangsSchema,
   userEditProfileSchema,
+  userEnableRightClickOnWidgetsSchema,
   userFirstDayOfWeekSchema,
   userInitSchema,
   userPingIconsEnabledSchema,
@@ -345,6 +346,7 @@ export const userRouter = createTRPCRouter({
         mobileHomeBoardId: true,
         firstDayOfWeek: true,
         pingIconsEnabled: true,
+        enableRightClickOnWidgets: true,
         defaultSearchEngineId: true,
         openSearchInNewTab: true,
         ddgBangs: true,
@@ -381,6 +383,7 @@ export const userRouter = createTRPCRouter({
           mobileHomeBoardId: true,
           firstDayOfWeek: true,
           pingIconsEnabled: true,
+          enableRightClickOnWidgets: true,
           defaultSearchEngineId: true,
           openSearchInNewTab: true,
           ddgBangs: true,
@@ -651,6 +654,32 @@ export const userRouter = createTRPCRouter({
         })
         .where(eq(users.id, ctx.session.user.id));
     }),
+  changeEnableRightClickOnWidgets: protectedProcedure
+    .meta({
+      openapi: {
+        method: "PATCH",
+        path: "/api/users/right-click-widgets",
+        tags: ["users"],
+        protect: true,
+      },
+    })
+    .input(convertIntersectionToZodObject(userEnableRightClickOnWidgetsSchema.and(byIdSchema)))
+    .output(z.void())
+    .mutation(async ({ input, ctx }) => {
+      if (!ctx.session.user.permissions.includes("admin") && ctx.session.user.id !== input.id) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "User not found",
+        });
+      }
+
+      await ctx.db
+        .update(users)
+        .set({
+          enableRightClickOnWidgets: input.enableRightClickOnWidgets,
+        })
+        .where(eq(users.id, input.id));
+    }),
   changePingIconsEnabled: protectedProcedure
     .input(userPingIconsEnabledSchema.and(byIdSchema))
     .mutation(async ({ input, ctx }) => {

packages/db/migrations/mysql/0043_add_right_click_preference.sql

@@ -0,0 +1 @@
+ALTER TABLE `user` ADD `enable_right_click_on_widgets` boolean DEFAULT true NOT NULL;

packages/db/migrations/mysql/meta/_journal.json

@@ -302,6 +302,13 @@
       "when": 1783176100870,
       "tag": "0042_add_widget_secret",
       "breakpoints": true
+    },
+    {
+      "idx": 43,
+      "version": "5",
+      "when": 1783852800000,
+      "tag": "0043_add_right_click_preference",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/migrations/postgresql/0009_add_right_click_preference.sql

@@ -0,0 +1 @@
+ALTER TABLE "user" ADD COLUMN "enable_right_click_on_widgets" boolean DEFAULT true NOT NULL;

packages/db/migrations/postgresql/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1783176100870,
       "tag": "0008_add_widget_secret",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1783786677702,
+      "tag": "0009_add_right_click_preference",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/migrations/sqlite/0041_add_right_click_preference.sql

@@ -0,0 +1 @@
+ALTER TABLE `user` ADD `enable_right_click_on_widgets` integer DEFAULT true NOT NULL;

packages/db/migrations/sqlite/meta/_journal.json

@@ -288,6 +288,13 @@
       "when": 1783176100870,
       "tag": "0040_add_widget_secret",
       "breakpoints": true
+    },
+    {
+      "idx": 41,
+      "version": "6",
+      "when": 1783786658943,
+      "tag": "0041_add_right_click_preference",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/schema/mysql.ts

@@ -86,6 +86,7 @@ export const users = mysqlTable("user", {
   colorScheme: varchar({ length: 5 }).$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: tinyint().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: boolean().default(false).notNull(),
+  enableRightClickOnWidgets: boolean().default(true).notNull(),
   completedManageTour: boolean().default(false).notNull(),
   completedBoardTour: boolean().default(false).notNull(),
 });

packages/db/schema/postgresql.ts

@@ -85,6 +85,7 @@ export const users = pgTable("user", {
   colorScheme: varchar({ length: 5 }).$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: smallint().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: boolean().default(false).notNull(),
+  enableRightClickOnWidgets: boolean().default(true).notNull(),
   completedManageTour: boolean().default(false).notNull(),
   completedBoardTour: boolean().default(false).notNull(),
 });

packages/db/schema/sqlite.ts

@@ -68,6 +68,7 @@ export const users = sqliteTable("user", {
   colorScheme: text().$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: int().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: int({ mode: "boolean" }).default(false).notNull(),
+  enableRightClickOnWidgets: int({ mode: "boolean" }).default(true).notNull(),
   completedManageTour: int({ mode: "boolean" }).default(false).notNull(),
   completedBoardTour: int({ mode: "boolean" }).default(false).notNull(),
 });

packages/settings/src/creator.ts

@@ -10,6 +10,7 @@ export type SettingsContextProps = Pick<
   | "openSearchInNewTab"
   | "ddgBangs"
   | "pingIconsEnabled"
+  | "enableRightClickOnWidgets"
 > &
   Pick<ServerSettings["board"], "enableStatusByDefault" | "forceDisableStatus"> &
   Pick<ServerSettings["user"], "enableGravatar">;
@@ -32,6 +33,7 @@ export type UserSettings = Pick<
   | "openSearchInNewTab"
   | "ddgBangs"
   | "pingIconsEnabled"
+  | "enableRightClickOnWidgets"
 >;
 
 export const createSettings = ({
@@ -48,6 +50,7 @@ export const createSettings = ({
   homeBoardId: user?.homeBoardId ?? serverSettings.board.homeBoardId,
   mobileHomeBoardId: user?.mobileHomeBoardId ?? serverSettings.board.mobileHomeBoardId,
   pingIconsEnabled: user?.pingIconsEnabled ?? false,
+  enableRightClickOnWidgets: user?.enableRightClickOnWidgets ?? true,
   enableStatusByDefault: serverSettings.board.enableStatusByDefault,
   forceDisableStatus: serverSettings.board.forceDisableStatus,
   enableGravatar: serverSettings.user.enableGravatar,

packages/settings/src/preferences/definitions.ts

@@ -56,6 +56,13 @@ export const userPreferenceDefinitions = [
     mutationGroup: "pingIconsEnabled",
     aliases: ["ping", "icon", "status"],
   },
+  {
+    key: "enableRightClickOnWidgets",
+    kind: "boolean",
+    guest: false,
+    mutationGroup: "enableRightClickOnWidgets",
+    aliases: ["right click", "context menu", "tile", "widget menu"],
+  },
   {
     key: "fullPreferencesPage",
     kind: "link",

packages/spotlight/src/preferences/preference-registry.tsx

@@ -3,6 +3,7 @@
 import {
   IconActivity,
   IconCalendarWeek,
+  IconClick,
   IconDeviceDesktop,
   IconExternalLink,
   IconHome,
@@ -46,6 +47,7 @@ export const preferenceIcons: Record<UserPreferenceKey, TablerIcon> = {
   homeBoardId: IconHome,
   mobileHomeBoardId: IconLayoutBoard,
   pingIconsEnabled: IconActivity,
+  enableRightClickOnWidgets: IconClick,
   fullPreferencesPage: IconSettings,
 };
 

packages/spotlight/src/preferences/use-user-preference.ts

@@ -93,6 +93,7 @@ export const useUserPreferences = () => {
   const homeBoardsMutation = clientApi.user.changeHomeBoards.useMutation({ onSuccess: refresh });
   const firstDayMutation = clientApi.user.changeFirstDayOfWeek.useMutation({ onSuccess: refresh });
   const pingMutation = clientApi.user.changePingIconsEnabled.useMutation({ onSuccess: refresh });
+  const rightClickMutation = clientApi.user.changeEnableRightClickOnWidgets.useMutation({ onSuccess: refresh });
 
   const getEffective = (key: UserPreferenceKey): unknown =>
     key in optimisticRef.current ? optimisticRef.current[key] : settingsRef.current[key as keyof SettingsContextProps];
@@ -116,6 +117,8 @@ export const useUserPreferences = () => {
       }),
     firstDayOfWeek: (uid, _key, value) => firstDayMutation.mutateAsync({ id: uid, firstDayOfWeek: value as DayOfWeek }),
     pingIconsEnabled: (uid, _key, value) => pingMutation.mutateAsync({ id: uid, pingIconsEnabled: value as boolean }),
+    enableRightClickOnWidgets: (uid, _key, value) =>
+      rightClickMutation.mutateAsync({ id: uid, enableRightClickOnWidgets: value as boolean }),
   };
 
   const groupPending: Record<string, boolean> = {
@@ -123,6 +126,7 @@ export const useUserPreferences = () => {
     homeBoards: homeBoardsMutation.isPending,
     firstDayOfWeek: firstDayMutation.isPending,
     pingIconsEnabled: pingMutation.isPending,
+    enableRightClickOnWidgets: rightClickMutation.isPending,
   };
 
   const persistedValues = useMemo<Record<UserPreferenceKey, unknown>>(() => {

packages/translation/src/lang/en.json

@@ -198,6 +198,10 @@
       "pingIconsEnabled": {
         "label": "Use icons for pings"
       },
+      "enableRightClickOnWidgets": {
+        "label": "Enable right-click on widgets",
+        "description": "Show Homarr's context menu when right-clicking a widget. Disable to use the browser's default menu (e.g. \"Open link in new tab\")."
+      },
       "defaultSearchEngine": {
         "label": "Default search engine"
       },
@@ -5953,6 +5957,14 @@
                   }
                 }
               },
+              "enableRightClickOnWidgets": {
+                "label": "Enable right-click on widgets",
+                "children": {
+                  "detail": {
+                    "title": "Enable right-click on widgets"
+                  }
+                }
+              },
               "fullPreferencesPage": {
                 "label": "Open full preferences page"
               }

packages/validation/src/user.ts

@@ -130,6 +130,10 @@ export const userPingIconsEnabledSchema = z.object({
   pingIconsEnabled: z.boolean(),
 });
 
+export const userEnableRightClickOnWidgetsSchema = z.object({
+  enableRightClickOnWidgets: z.boolean(),
+});
+
 export const userDdgBangsSchema = z.object({
   ddgBangs: z.boolean(),
 });