Merge advanced widget opt-in into mobile boards

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

@@ -18,7 +18,7 @@ Temporary inputs exist only while the tile is mounted. Homarr encrypts source cr
 
 Homarr does not send these credentials to the browser. Homarr does not include them in an export.
 
-<WidgetInteractionGuide />
+<WidgetInteractionGuide advancedView={false} />
 
 ### Adding the widget
 

packages/api/src/router/test/widgets/custom-api-v2.spec.ts

@@ -84,7 +84,11 @@ const createSession = (userId: string): Session => ({
   expires: new Date(Date.now() + 60_000).toISOString(),
 });
 
-async function setup(isPublic = true) {
+async function setup(
+  isPublic = true,
+  customDefinition: HomarrCustomWidgetV2 = definition,
+  configuration: Record<string, unknown> = {},
+) {
   const db = createDb();
   const ownerId = createId();
   const boardId = createId();
@@ -94,14 +98,14 @@ async function setup(isPublic = true) {
   await db.insert(boards).values({ id: boardId, name: createId(), creatorId: ownerId, isPublic });
   await db.insert(customWidgetDefinitions).values({
     id: definitionId,
-    ...serializeCustomWidgetDefinition(definition),
+    ...serializeCustomWidgetDefinition(customDefinition),
     creatorId: ownerId,
   });
   await db.insert(items).values({
     id: itemId,
     boardId,
     kind: "customApi",
-    options: stringifySuperJson({ definitionId, configuration: {}, configurationVersion: 1 }),
+    options: stringifySuperJson({ definitionId, configuration, configurationVersion: 1 }),
   });
   return { db, ownerId, boardId, itemId, definitionId };
 }
@@ -122,6 +126,20 @@ describe("Custom JSX v2 board router", () => {
     expect(mocks.executeRequest).toHaveBeenCalledOnce();
   });
 
+  test("uses current defaults when an updated option no longer accepts the stored value", async () => {
+    const updatedDefinition: HomarrCustomWidgetV2 = {
+      ...definition,
+      options: {
+        limit: { label: "Limit", control: "slider", default: 5, min: 1, max: 10 },
+      },
+      template: "<Text>{options.limit}</Text>",
+    };
+    const { db, itemId } = await setup(true, updatedDefinition, { limit: "5", removed: true });
+    const caller = customApiRouter.createCaller({ db, deviceType: undefined, session: null });
+
+    await expect(caller.getData({ itemId })).resolves.toMatchObject({ options: { limit: 5 } });
+  });
+
   test("hides private boards and disabled definitions before executing a request", async () => {
     const privateSetup = await setup(false);
     const anonymous = customApiRouter.createCaller({

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

@@ -9,6 +9,7 @@ import type { BoardPermission } from "@homarr/definitions";
 import {
   getCustomWidgetConfirmation,
   getCustomWidgetDefaultOptions,
+  normalizeCustomWidgetOptions,
   validateCustomWidgetOptions,
 } from "@homarr/custom-widgets/core";
 import type { CustomJsxRequest, CustomWidgetSource } from "@homarr/custom-widgets/core";
@@ -96,7 +97,10 @@ async function resolvePlacedDefinitionAsync(ctx: RouterContext, itemId: string)
   if (!stored.enabled) throw new TRPCError({ code: "FORBIDDEN", message: "Widget is disabled" });
 
   const definition = parseStoredCustomWidgetDefinition(stored);
-  const configuration = { ...getCustomWidgetDefaultOptions(definition.options), ...itemOptions.configuration };
+  const configuration =
+    itemOptions.configurationVersion === stored.updatedAt.getTime()
+      ? { ...getCustomWidgetDefaultOptions(definition.options), ...itemOptions.configuration }
+      : normalizeCustomWidgetOptions(definition.options, itemOptions.configuration);
   const issues = validateCustomWidgetOptions(definition.options, configuration);
   if (issues.length > 0) {
     throw new TRPCError({

packages/custom-widgets/src/core/options.ts

@@ -12,6 +12,18 @@ export function getCustomWidgetDefaultOptions(
   return Object.fromEntries(Object.entries(options).map(([name, option]) => [name, option.default]));
 }
 
+export function normalizeCustomWidgetOptions(
+  options: CustomWidgetOptions,
+  value: Record<string, unknown>,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(options).map(([name, option]) => [
+      name,
+      getCustomWidgetOptionValueIssue(option, value[name]) ? option.default : value[name],
+    ]),
+  );
+}
+
 export function validateCustomWidgetOptions(
   options: CustomWidgetOptions,
   value: Record<string, unknown>,

packages/custom-widgets/src/test/options.spec.ts

@@ -5,6 +5,7 @@ import {
   customWidgetOptionControls,
   customWidgetOptionSchema,
   getCustomWidgetDefaultOptions,
+  normalizeCustomWidgetOptions,
   validateCustomWidgetOptions,
 } from "../core";
 
@@ -69,6 +70,29 @@ describe("lean Custom Widget options", () => {
     expect(validateCustomWidgetOptions(options, configuration)).toEqual([]);
   });
 
+  it("replaces stale values with current defaults", () => {
+    const options = customWidgetDefinitionSchema.parse({
+      $schema: "homarr-custom-widget-v2",
+      name: "Updated options",
+      sources: {},
+      requests: {},
+      options: {
+        limit: { label: "Limit", control: "slider", default: 5, min: 1, max: 10 },
+        label: { label: "Label", control: "text", default: "Default" },
+      },
+      template: "<Text>{options.limit}</Text>",
+    }).options;
+
+    const normalized = normalizeCustomWidgetOptions(options, {
+      limit: "5",
+      label: "Custom",
+      removed: true,
+    });
+
+    expect(normalized).toEqual({ limit: 5, label: "Custom" });
+    expect(validateCustomWidgetOptions(options, normalized)).toEqual([]);
+  });
+
   it("rejects duplicate static choice values", () => {
     expect(
       customWidgetOptionSchema.safeParse({

packages/widgets/src/_inputs/widget-custom-widget-configuration-input.tsx

@@ -21,7 +21,7 @@ import { IconAlertTriangle } from "@tabler/icons-react";
 import { clientApi } from "@homarr/api/client";
 import { useOptionalBoard } from "@homarr/boards/context";
 import type { CustomWidgetOption } from "@homarr/custom-widgets/core";
-import { validateCustomWidgetOptions } from "@homarr/custom-widgets/core";
+import { normalizeCustomWidgetOptions, validateCustomWidgetOptions } from "@homarr/custom-widgets/core";
 import { CustomWidgetCodeEditor } from "@homarr/custom-widgets/workbench";
 import type { CustomWidgetEditorMessages } from "@homarr/custom-widgets/workbench";
 import { IconPicker } from "@homarr/forms-collection";
@@ -45,10 +45,23 @@ export const WidgetCustomWidgetConfigurationInput = ({
   );
   const definition = available.data?.find((candidate) => candidate.id === definitionId);
   const options = isRecord(definition?.options) ? (definition.options as Record<string, CustomWidgetOption>) : null;
-  const issues = useMemo(
-    () => (options ? validateCustomWidgetOptions(options, configuration) : []),
-    [configuration, options],
+  const definitionVersion = definition?.updatedAt instanceof Date ? definition.updatedAt.getTime() : undefined;
+  const configurationVersion = form.values.options.configurationVersion;
+  const needsDefinitionRepair = definitionVersion !== undefined && configurationVersion !== definitionVersion;
+  const effectiveConfiguration = useMemo(
+    () => (options && needsDefinitionRepair ? normalizeCustomWidgetOptions(options, configuration) : configuration),
+    [configuration, needsDefinitionRepair, options],
   );
+  const issues = useMemo(
+    () => (options ? validateCustomWidgetOptions(options, effectiveConfiguration) : []),
+    [effectiveConfiguration, options],
+  );
+
+  useEffect(() => {
+    if (!needsDefinitionRepair || definitionVersion === undefined) return;
+    form.setFieldValue(`options.${property}`, effectiveConfiguration);
+    form.setFieldValue("options.configurationVersion", definitionVersion);
+  }, [definitionVersion, effectiveConfiguration, form, needsDefinitionRepair, property]);
 
   useEffect(() => {
     const path = `options.${property}`;
@@ -72,7 +85,7 @@ export const WidgetCustomWidgetConfigurationInput = ({
           key={`${definitionId}:${name}`}
           option={option}
           path={`options.${property}.${name}`}
-          configuration={configuration}
+          configuration={effectiveConfiguration}
           definitionId={definitionId}
         />
       ))}
@@ -87,7 +100,7 @@ export const WidgetCustomWidgetConfigurationInput = ({
                     key={`${definitionId}:${name}`}
                     option={option}
                     path={`options.${property}.${name}`}
-                    configuration={configuration}
+                    configuration={effectiveConfiguration}
                     definitionId={definitionId}
                   />
                 ))}

packages/widgets/src/advanced-focus-support.spec.ts

@@ -3,41 +3,44 @@ import { describe, expect, test } from "vitest";
 import { supportsAdvancedFocus } from "./definition";
 import { widgetImports } from ".";
 
-const compactOnlyWidgetKinds = [
-  "app",
-  "bazarr",
-  "beszelAlerts",
-  "beszelSystemGrid",
-  "beszelSystemStats",
-  "beszelSystemTable",
-  "coolify",
-  "dnsHoleControls",
-  "dnsHoleSummary",
-  "iframe",
-  "indexerManager",
-  "mediaRequests-requestList",
-  "mediaRequests-requestStats",
-  "minecraftServerStatus",
-  "networkControllerSummary",
-  "notebook",
-  "notifications",
-  "paperlessNgx",
-  "patchmon",
-  "releases",
-  "rssFeed",
-  "stockPrice",
-  "systemDisks",
-  "video",
-  "vpn",
+const advancedFocusWidgetKinds = [
+  "anchorNote",
+  "archiveTeamWarrior",
+  "audioStats",
+  "bookmarks",
+  "calendar",
+  "clock",
+  "dockerContainers",
+  "downloads",
+  "firewall",
+  "healthMonitoring",
+  "immich-albumCarousel",
+  "immich-serverStats",
+  "mediaMissing",
+  "mediaReleases",
+  "mediaServer",
+  "mediaTranscoding",
+  "networkControllerStatus",
+  "smartHome-entityState",
+  "smartHome-executeAutomation",
+  "speedtestTracker",
+  "systemResources",
+  "timetable",
+  "tracearr",
+  "traefik",
+  "umami",
+  "ups",
+  "uptimeKuma",
+  "weather",
 ] as const;
 
 describe("advanced focus support", () => {
   test("is reserved for widgets with a distinct advanced experience", () => {
-    const actualCompactOnlyKinds = Object.entries(widgetImports)
-      .filter(([, widgetImport]) => !supportsAdvancedFocus(widgetImport.definition))
+    const actualAdvancedFocusKinds = Object.entries(widgetImports)
+      .filter(([, widgetImport]) => supportsAdvancedFocus(widgetImport.definition))
       .map(([kind]) => kind)
       .toSorted();
 
-    expect(actualCompactOnlyKinds).toEqual([...compactOnlyWidgetKinds].toSorted());
+    expect(actualAdvancedFocusKinds).toEqual([...advancedFocusWidgetKinds].toSorted());
   });
 });

packages/widgets/src/anchor-note/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("anchorNote", {
   icon: IconNotes,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "anchorNotes"]],
   maxIntegrations: 1,
   supportedIntegrations: ["anchor"],

packages/widgets/src/archive-team-warrior/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("archiveTeamWarrior", {
   icon: IconArchive,
+  supportsAdvancedFocus: true,
   maxIntegrations: 1,
   createOptions() {
     return optionsBuilder.from((factory) => ({

packages/widgets/src/audio-stats/index.ts

@@ -13,6 +13,7 @@ const hideUnlessAudiobookshelf = {
 
 export const { definition, componentLoader } = createWidgetDefinition("audioStats", {
   icon: IconHeadphones,
+  supportsAdvancedFocus: true,
   queryKeys: [[["widget", "audioStats", "getStats"]], [["widget", "mediaServer", "getCurrentStreams"]]],
   queryMatcher: matchesWidgetRuntimeQuery,
   supportedIntegrations: ["navidrome", "audiobookshelf"],

packages/widgets/src/bookmarks/index.tsx

@@ -10,6 +10,7 @@ import { BookmarkAddButton } from "./add-button";
 
 export const { definition, componentLoader } = createWidgetDefinition("bookmarks", {
   icon: IconBookmark,
+  supportsAdvancedFocus: true,
   queryKey: [["app", "byIds"]],
   createOptions() {
     return optionsBuilder.from((factory) => ({

packages/widgets/src/calendar/index.ts

@@ -9,6 +9,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("calendar", {
   icon: IconCalendar,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "calendar", "findAllEvents"]],
   queryMatcher: matchesWidgetRuntimeQuery,
   createOptions() {

packages/widgets/src/clock/index.ts

@@ -6,6 +6,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("clock", {
   icon: IconClock,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "weather", "atLocation"]],
   queryMatcher: ({ input }, scope) => {
     const location = scope.options.weatherLocation;

packages/widgets/src/definition.spec.ts

@@ -2,7 +2,9 @@ import { describe, expect, test } from "vitest";
 import { definition as appDefinition } from "./app";
 import { definition as beszelSystemGridDefinition } from "./beszel-system-grid";
 import { definition as beszelSystemTableDefinition } from "./beszel-system-table";
+import { definition as customApiDefinition } from "./custom-api";
 import { getWidgetQueryKeys, supportsAdvancedFocus } from "./definition";
+import { definition as downloadsDefinition } from "./downloads";
 
 describe("getWidgetQueryKeys", () => {
   test("falls back to the widget router namespace", () => {
@@ -24,10 +26,15 @@ describe("getWidgetQueryKeys", () => {
 });
 
 describe("supportsAdvancedFocus", () => {
-  test.each([appDefinition, beszelSystemGridDefinition, beszelSystemTableDefinition])(
+  test.each([appDefinition, beszelSystemGridDefinition, beszelSystemTableDefinition, customApiDefinition])(
     "keeps non-enhanced widgets compact",
     (widgetDefinition) => {
       expect(supportsAdvancedFocus(widgetDefinition)).toBe(false);
     },
   );
+
+  test("requires an explicit opt-in", () => {
+    expect(supportsAdvancedFocus({})).toBe(false);
+    expect(supportsAdvancedFocus(downloadsDefinition)).toBe(true);
+  });
 });

packages/widgets/src/definition.ts

@@ -127,7 +127,7 @@ export interface WidgetDefinition {
 }
 
 export const supportsAdvancedFocus = (definition: object) =>
-  !("supportsAdvancedFocus" in definition) || definition.supportsAdvancedFocus !== false;
+  "supportsAdvancedFocus" in definition && definition.supportsAdvancedFocus === true;
 
 export const getWidgetQueryKeys = (
   definition: {

packages/widgets/src/docker/index.ts

@@ -25,6 +25,7 @@ const columnTranslationKeyMap = {
 
 export const { definition, componentLoader } = createWidgetDefinition("dockerContainers", {
   icon: IconBrandDocker,
+  supportsAdvancedFocus: true,
   queryKey: [["docker", "getContainers"]],
   refetchInterval: 30,
   createOptions() {

packages/widgets/src/downloads/index.ts

@@ -42,6 +42,7 @@ const sortColumns = [
 
 export const { definition, componentLoader } = createWidgetDefinition("downloads", {
   icon: IconDownload,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "downloads", "getJobsAndStatuses"]],
   queryMatcher: ({ input }, scope) =>
     widgetQueryInputMatches(input, {

packages/widgets/src/firewall/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("firewall", {
   icon: IconWall,
+  supportsAdvancedFocus: true,
   refetchInterval: 5,
   createOptions() {
     return optionsBuilder.from(() => ({}));

packages/widgets/src/health-monitoring/index.ts

@@ -8,6 +8,7 @@ import { createStorageVolumeMultiSelectOptions } from "../storage-volume-options
 
 export const { definition, componentLoader } = createWidgetDefinition("healthMonitoring", {
   icon: IconHeartRateMonitor,
+  supportsAdvancedFocus: true,
   queryKeys: [[["integration", "byIds"]], [["widget", "healthMonitoring"]]],
   refetchInterval: 5,
   createOptions() {

packages/widgets/src/immich/album-carousel/index.ts

@@ -51,6 +51,7 @@ const createOptions = () =>
 
 export const { definition, componentLoader } = createWidgetDefinition("immich-albumCarousel", {
   icon: IconPhoto,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "immich", "getAlbum"]],
   queryMatcher: ({ input }, scope) =>
     widgetQueryInputMatches(input, {

packages/widgets/src/immich/server-stats/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("immich-serverStats", {
   icon: IconGraphFilled,
+  supportsAdvancedFocus: true,
   queryKeys: [[["widget", "immich", "getServerStats"]], [["widget", "immich", "getAlbums"]]],
   queryMatcher: matchesWidgetRuntimeQuery,
   refetchInterval: null,

packages/widgets/src/media-missing/index.ts

@@ -9,6 +9,7 @@ const pageSizeOptions = ["10", "20", "30", "50"] as const;
 
 export const { componentLoader, definition } = createWidgetDefinition("mediaMissing", {
   icon: IconMovie,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "mediaOrganizer", "getData"]],
   queryMatcher: matchesWidgetRuntimeQuery,
   createOptions() {

packages/widgets/src/media-releases/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("mediaReleases", {
   icon: IconTicket,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "mediaRelease"]],
   refetchInterval: null,
   createOptions() {

packages/widgets/src/media-server/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../options";
 
 export const { componentLoader, definition } = createWidgetDefinition("mediaServer", {
   icon: IconVideo,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "mediaServer", "getCurrentStreams"]],
   queryMatcher: ({ input }, scope) =>
     widgetQueryInputMatches(input, {

packages/widgets/src/media-transcoding/index.ts

@@ -11,6 +11,7 @@ export const views = ["workers", "queue", "statistics"] as const;
 
 export const { componentLoader, definition } = createWidgetDefinition("mediaTranscoding", {
   icon: IconTransform,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "mediaTranscoding", "getDataAsync"]],
   queryMatcher: matchesWidgetRuntimeQuery,
   maxIntegrations: 1,

packages/widgets/src/network-controller/network-status/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("networkControllerStatus", {
   icon: IconTopologyFull,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "networkController"]],
   refetchInterval: null,
   createOptions() {

packages/widgets/src/smart-home/entity-state/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("smartHome-entityState", {
   icon: IconBinaryTree,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "smartHome"]],
   maxIntegrations: 1,
   createOptions() {

packages/widgets/src/smart-home/execute-automation/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("smartHome-executeAutomation", {
   icon: IconBinaryTree,
+  supportsAdvancedFocus: true,
   maxIntegrations: 1,
   createOptions() {
     return optionsBuilder.from((factory) => ({

packages/widgets/src/speedtest-tracker/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("speedtestTracker", {
   icon: IconSpeedboat,
+  supportsAdvancedFocus: true,
   refetchInterval: null,
   createOptions() {
     return optionsBuilder.from(

packages/widgets/src/system-resources/index.ts

@@ -14,6 +14,7 @@ const labelDisplayModeOptions = {
 
 export const { definition, componentLoader } = createWidgetDefinition("systemResources", {
   icon: IconGraphFilled,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "healthMonitoring"]],
   refetchInterval: 5,
   supportedIntegrations: ["dashDot", "openmediavault", "truenas", "unraid", "glances", "synology"],

packages/widgets/src/timetable/index.ts

@@ -9,6 +9,7 @@ import { optionsBuilder } from "../options";
 
 export const { componentLoader, definition } = createWidgetDefinition("timetable", {
   icon: IconBusStop,
+  supportsAdvancedFocus: true,
   errors: {
     BAD_REQUEST: {
       icon: IconWorldOff,

packages/widgets/src/tracearr/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("tracearr", {
   icon: IconActivityHeartbeat,
+  supportsAdvancedFocus: true,
   refetchInterval: 5,
   createOptions() {
     return optionsBuilder.from((factory) => ({

packages/widgets/src/traefik/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("traefik", {
   icon: IconRoute,
+  supportsAdvancedFocus: true,
   createOptions() {
     return optionsBuilder.from((factory) => ({
       showTcp: factory.switch({

packages/widgets/src/umami/index.ts

@@ -8,6 +8,7 @@ export const timeFrameValues = ["today", "24h", "7d", "30d", "month", "lastMonth
 
 export const { definition, componentLoader } = createWidgetDefinition("umami", {
   icon: IconChartBar,
+  supportsAdvancedFocus: true,
   queryKeys: [
     [["widget", "umami", "getVisitorStats"]],
     [["widget", "umami", "getActiveVisitors"]],

packages/widgets/src/ups/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("ups", {
   icon: IconBatteryCharging,
+  supportsAdvancedFocus: true,
   createOptions() {
     return optionsBuilder.from((factory) => ({
       showBattery: factory.switch({

packages/widgets/src/uptime-kuma/index.ts

@@ -5,6 +5,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("uptimeKuma", {
   icon: IconHeartbeat,
+  supportsAdvancedFocus: true,
   createOptions() {
     return optionsBuilder.from((factory) => ({
       showAverageUptime: factory.switch({

packages/widgets/src/weather/index.ts

@@ -7,6 +7,7 @@ import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition("weather", {
   icon: IconCloud,
+  supportsAdvancedFocus: true,
   queryKey: [["widget", "weather", "atLocation"]],
   queryMatcher: ({ input }, scope) => {
     const location = scope.options.location;