enhance release v2 experience

2026-08-14 02:18:46 +02:00
1 parent 9b4970583e
commit ef2ed6c602
@@ -4,8 +4,9 @@ import type { Modify } from "@homarr/common/types";
 import { getRootSectionLane } from "@homarr/definitions";
 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 type { Board, ContainerSection, EmptySection, Item, ItemLayout } from "~/app/[locale]/boards/_types";
 import { getBoardLaneColumnCount } from "~/components/board/layout";
 import { getFirstEmptyPosition } from "./empty-position";
 import { getSectionElements } from "./section-elements";
@@ -15,33 +16,38 @@ export interface CreateItemInput {
  kind: WidgetKind;
  options?: Record<string, unknown>;
  integrationIds?: string[];
+  targetSectionId?: string;
+  advancedOptions?: BoardItemAdvancedOptions;
 }

 export const createItemCallback =
-  ({ id, kind, options = {}, integrationIds = [] }: CreateItemInput) =>
+  ({ id, kind, options = {}, integrationIds = [], targetSectionId, advancedOptions }: CreateItemInput) =>
  (previous: Board): Board => {
-    const firstSection = previous.sections
+    const firstCanvasSection = previous.sections
      .filter(
        (section): section is EmptySection =>
          section.kind === "empty" && getRootSectionLane(section.xOffset) === "main",
      )
      .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
      .at(0);
+    const requestedSection = targetSectionId
+      ? previous.sections.find(
+          (section): section is EmptySection | ContainerSection =>
+            section.id === targetSectionId && (section.kind === "empty" || section.kind === "container"),
+        )
+      : undefined;
+    const targetSection = requestedSection ?? firstCanvasSection;

-    if (!firstSection) return previous;
+    if (!targetSection) return previous;

-    const itemLayouts = createItemLayouts(previous, firstSection, kind);
+    const itemLayouts = createItemLayouts(previous, targetSection, kind);
    const widget = {
      id: id ?? createId(),
      kind,
      options,
      layouts: itemLayouts,
      integrationIds,
-      advancedOptions: {
-        title: null,
-        customCssClasses: [],
-        borderColor: "",
-      },
+      advancedOptions: advancedOptions ?? { title: null, customCssClasses: [], borderColor: "" },
    } satisfies Modify<
      Item,
      {
@@ -59,14 +65,23 @@ 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,
+  currentSection: EmptySection | ContainerSection,
+  kind: WidgetKind,
+): 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 columnCount = boardLayout ? getBoardLaneColumnCount(boardLayout, "main") : itemSize.width;
+    const containerLayout =
+      currentSection.kind === "container"
+        ? currentSection.layouts.find((layout) => layout.layoutId === layoutId)
+        : undefined;
+    const columnCount =
+      containerLayout?.width ?? (boardLayout ? getBoardLaneColumnCount(boardLayout, "main") : itemSize.width);
    const size = {
      width: Math.min(itemSize.width, columnCount),
      height: itemSize.height,
@@ -149,6 +149,48 @@ describe("item actions create-item", () => {
    });
  });

+  test("places a new item directly in the requested container", () => {
+    const board = new BoardMockBuilder()
+      .addEmptySection({ id: "canvas" })
+      .addSection(
+        new ContainerSectionMockBuilder({ id: "media" })
+          .addLayout({ layoutId: "layout", parentSectionId: "canvas", width: 4, height: 3 })
+          .build(),
+      )
+      .build();
+    const layout = board.layouts.at(0);
+    if (!layout) throw new Error("Expected a board layout");
+    layout.id = "layout";
+
+    const result = createItemCallback({ id: "calendar", kind: "mediaMissing", targetSectionId: "media" })(board);
+
+    expect(result.items.find((item) => item.id === "calendar")?.layouts).toEqual([
+      expect.objectContaining({ layoutId: "layout", sectionId: "media", width: 4 }),
+    ]);
+  });
+
+  test("falls back to the main canvas when a requested destination no longer exists", () => {
+    const board = new BoardMockBuilder().addEmptySection({ id: "canvas" }).build();
+    const layout = board.layouts.at(0);
+    if (!layout) throw new Error("Expected a board layout");
+    layout.id = "layout";
+
+    const result = createItemCallback({ id: "clock", kind: "clock", targetSectionId: "removed" })(board);
+
+    expect(result.items.find((item) => item.id === "clock")?.layouts).toEqual([
+      expect.objectContaining({ layoutId: "layout", sectionId: "canvas" }),
+    ]);
+  });
+
+  test("commits configured advanced options in the creation transaction", () => {
+    const board = new BoardMockBuilder().addEmptySection({ id: "canvas" }).build();
+    const advancedOptions = { title: "Kitchen", customCssClasses: ["compact"], borderColor: "#abc" };
+
+    const result = createItemCallback({ id: "clock", kind: "clock", advancedOptions })(board);
+
+    expect(result.items.find((item) => item.id === "clock")?.advancedOptions).toEqual(advancedOptions);
+  });
+
  test("clamps wide defaults and places below a full automatic canvas", () => {
    const board = new BoardMockBuilder().addEmptySection({ id: "canvas", yOffset: 0 }).build();
    const layout = board.layouts[0];
@@ -0,0 +1,73 @@
+import { describe, expect, test } from "vitest";
+
+import { getBoardRecipeDismissalKey, getBoardRecipeRecommendations } from "./board-recipe-recommendations";
+
+test("recipe dismissal is scoped to both the board and integration kind", () => {
+  expect(getBoardRecipeDismissalKey("board-a", "piHole")).not.toBe(getBoardRecipeDismissalKey("board-b", "piHole"));
+  expect(getBoardRecipeDismissalKey("board-a", "piHole")).not.toBe(getBoardRecipeDismissalKey("board-a", "jellyfin"));
+});
+
+describe("getBoardRecipeRecommendations", () => {
+  test("prioritizes widgets unlocked by the newly connected service", () => {
+    const recommendations = getBoardRecipeRecommendations({
+      configuredIntegrationKinds: ["piHole", "jellyfin"],
+      existingItemKinds: [],
+      preferredIntegrationKind: "jellyfin",
+    });
+
+    expect(recommendations).toHaveLength(3);
+    expect(recommendations.slice(0, 2).every(({ isNewlyAvailable }) => isNewlyAvailable)).toBe(true);
+    expect(recommendations.at(2)).toEqual(
+      expect.objectContaining({ integrationKind: "piHole", isNewlyAvailable: false }),
+    );
+  });
+
+  test("does not recommend widget kinds already present on the board", () => {
+    const recommendations = getBoardRecipeRecommendations({
+      configuredIntegrationKinds: ["piHole"],
+      existingItemKinds: ["dnsHoleSummary"],
+      preferredIntegrationKind: "piHole",
+    });
+
+    expect(recommendations.map(({ widgetKind }) => widgetKind)).toEqual(["dnsHoleControls"]);
+  });
+
+  test("deduplicates configured kinds and emitted widget capabilities", () => {
+    const recommendations = getBoardRecipeRecommendations({
+      configuredIntegrationKinds: ["piHole", "piHole"],
+      existingItemKinds: [],
+      limit: 10,
+    });
+
+    expect(recommendations.map(({ widgetKind }) => widgetKind)).toEqual(["dnsHoleControls", "dnsHoleSummary"]);
+  });
+
+  test("falls back to other configured integrations when the new service has no missing widgets", () => {
+    const recommendations = getBoardRecipeRecommendations({
+      configuredIntegrationKinds: ["piHole", "jellyfin"],
+      existingItemKinds: ["dnsHoleSummary", "dnsHoleControls"],
+      preferredIntegrationKind: "piHole",
+      limit: 1,
+    });
+
+    expect(recommendations).toEqual([
+      expect.objectContaining({ integrationKind: "jellyfin", isNewlyAvailable: false }),
+    ]);
+  });
+
+  test("returns no recipes without a usable connection or capacity", () => {
+    expect(
+      getBoardRecipeRecommendations({
+        configuredIntegrationKinds: [],
+        existingItemKinds: [],
+      }),
+    ).toEqual([]);
+    expect(
+      getBoardRecipeRecommendations({
+        configuredIntegrationKinds: ["piHole"],
+        existingItemKinds: [],
+        limit: 0,
+      }),
+    ).toEqual([]);
+  });
+});
@@ -0,0 +1,60 @@
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import { nativeFeatureCapabilities, widgetKinds } from "@homarr/definitions";
+
+export interface BoardRecipeRecommendation {
+  widgetKind: WidgetKind;
+  integrationKind: IntegrationKind;
+  isNewlyAvailable: boolean;
+  score: number;
+}
+
+export const getBoardRecipeDismissalKey = (boardId: string, integrationKind: IntegrationKind) =>
+  `homarr-board-recipes-${boardId}-${integrationKind}`;
+
+interface BoardRecipeRecommendationInput {
+  configuredIntegrationKinds: readonly IntegrationKind[];
+  existingItemKinds: readonly WidgetKind[];
+  preferredIntegrationKind?: IntegrationKind;
+  limit?: number;
+}
+
+/**
+ * Suggests missing widgets that can use an existing connection. The newly
+ * connected service ranks first, followed by specific capabilities with fewer
+ * unrelated provider matches. Inputs and outputs are deduplicated so this can
+ * remain a small, explainable client-side recommendation layer.
+ */
+export const getBoardRecipeRecommendations = ({
+  configuredIntegrationKinds,
+  existingItemKinds,
+  preferredIntegrationKind,
+  limit = 3,
+}: BoardRecipeRecommendationInput): BoardRecipeRecommendation[] => {
+  const availableKinds = new Set(configuredIntegrationKinds);
+  const existingKinds = new Set(existingItemKinds);
+
+  return widgetKinds
+    .filter((widgetKind) => !existingKinds.has(widgetKind))
+    .flatMap((widgetKind) => {
+      const capability = nativeFeatureCapabilities[widgetKind as keyof typeof nativeFeatureCapabilities];
+      if (!capability) return [];
+
+      const matches = capability.integrations.filter((integrationKind) => availableKinds.has(integrationKind));
+      if (matches.length === 0) return [];
+
+      const preferredMatch = preferredIntegrationKind && matches.includes(preferredIntegrationKind);
+      const integrationKind = preferredMatch ? preferredIntegrationKind : matches[0];
+      if (!integrationKind) return [];
+
+      return [
+        {
+          widgetKind,
+          integrationKind,
+          isNewlyAvailable: Boolean(preferredMatch),
+          score: (preferredMatch ? 1_000 : 0) + matches.length * 10 - capability.integrations.length,
+        },
+      ];
+    })
+    .toSorted((left, right) => right.score - left.score || left.widgetKind.localeCompare(right.widgetKind))
+    .slice(0, Math.max(0, limit));
+};
@@ -1,6 +1,44 @@
 import { describe, expect, it, vi } from "vitest";

-import { resolveMatchingIntegrationsAsync, tryLockSelection, unlockSelection } from "./item-select-data";
+import {
+  getWidgetConnectionStatus,
+  resolveMatchingIntegrationsAsync,
+  tryLockSelection,
+  unlockSelection,
+} from "./item-select-data";
+
+describe("getWidgetConnectionStatus", () => {
+  const availableKinds = new Set(["sonarr" as const]);
+
+  it("reports widgets with a configured compatible integration as ready", () => {
+    expect(
+      getWidgetConnectionStatus({
+        supportedIntegrations: ["sonarr", "radarr"],
+        availableKinds,
+        connectionOptional: false,
+      }),
+    ).toBe("ready");
+  });
+
+  it("reports required integrations that are not configured as needing setup", () => {
+    expect(
+      getWidgetConnectionStatus({
+        supportedIntegrations: ["radarr"],
+        availableKinds,
+        connectionOptional: false,
+      }),
+    ).toBe("needsSetup");
+  });
+
+  it.each([
+    { supportedIntegrations: [], connectionOptional: false },
+    { supportedIntegrations: ["radarr" as const], connectionOptional: true },
+  ])("reports a widget without a required connection", ({ supportedIntegrations, connectionOptional }) => {
+    expect(getWidgetConnectionStatus({ supportedIntegrations, availableKinds, connectionOptional })).toBe(
+      "noConnectionRequired",
+    );
+  });
+});

 describe("widget selection lock", () => {
  it("rejects repeated selection synchronously until the active selection finishes", () => {
@@ -1,5 +1,21 @@
 import type { IntegrationKind } from "@homarr/definitions";

+export type WidgetConnectionStatus = "ready" | "needsSetup" | "noConnectionRequired";
+
+export const getWidgetConnectionStatus = ({
+  supportedIntegrations,
+  availableKinds,
+  connectionOptional,
+}: {
+  supportedIntegrations: readonly IntegrationKind[];
+  availableKinds: ReadonlySet<IntegrationKind>;
+  connectionOptional: boolean;
+}): WidgetConnectionStatus => {
+  if (supportedIntegrations.some((kind) => availableKinds.has(kind))) return "ready";
+  if (supportedIntegrations.length === 0 || connectionOptional) return "noConnectionRequired";
+  return "needsSetup";
+};
+
 export const tryLockSelection = (lock: { current: boolean }) => {
  if (lock.current) return false;
  lock.current = true;
@@ -1,27 +1,43 @@
 import { useMemo, useRef, useState } from "react";
-import { Avatar, Box, Button, Card, Center, Divider, Group, Image, Stack, Text, Tooltip } from "@mantine/core";
+import { Avatar, Badge, Box, Button, Center, Divider, Group, Image, Select, Stack, Text, Tooltip } from "@mantine/core";
 import { IconApi } from "@tabler/icons-react";

 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
+import { useRequiredBoard } from "@homarr/boards/context";
 import { createId } from "@homarr/common";
-import { getIconUrl, getIntegrationName, widgetIntegrationSupport, widgetKinds } from "@homarr/definitions";
+import {
+  getIconUrl,
+  getIntegrationName,
+  getRootSectionLane,
+  widgetIntegrationSupport,
+  widgetKinds,
+  widgetKindsWithOptionalIntegrations,
+} from "@homarr/definitions";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
 import { createModal, modalSizeSelect, useModalAction } from "@homarr/modals";
-import { showErrorNotification } from "@homarr/notifications";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useSettings } from "@homarr/settings";
 import { useI18n } from "@homarr/translation/client";
-import { SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
+import { CatalogItem, SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
 import type { TablerIcon } from "@homarr/ui";
 import { widgetCatalogIcons } from "@homarr/widgets/catalog";
 import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr/widgets/manifest";

 import { WorkshopInstallButton } from "~/components/workshop/workshop-install-button";
+import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { useSetupAnalytics } from "~/components/create/setup-analytics";
+import type { EmptySection } from "~/app/[locale]/boards/_types";
 import { useItemActions } from "./item-actions";
-import { resolveMatchingIntegrationsAsync, tryLockSelection, unlockSelection } from "./item-select-data";
+import type { WidgetConnectionStatus } from "./item-select-data";
+import {
+  getWidgetConnectionStatus,
+  resolveMatchingIntegrationsAsync,
+  tryLockSelection,
+  unlockSelection,
+} from "./item-select-data";
 import { LazyWidgetEditModal, preloadWidgetEditModal } from "./lazy-widget-edit-modal";
-import classes from "./item-select-modal.module.css";

 interface ItemSelectModalContentProps {
  actions: { closeModal: () => void };
@@ -29,6 +45,8 @@ interface ItemSelectModalContentProps {
  customWidgetDefs: RouterOutputs["customWidget"]["available"] | undefined;
  ensureIntegrationDataAsync: () => Promise<RouterOutputs["integration"]["all"]>;
  isAdmin: boolean;
+  canCreateIntegration: boolean;
+  initialSearch?: string;
 }

 const ItemSelectModalContent = ({
@@ -37,14 +55,50 @@ const ItemSelectModalContent = ({
  customWidgetDefs,
  ensureIntegrationDataAsync,
  isAdmin,
+  canCreateIntegration,
+  initialSearch = "",
 }: ItemSelectModalContentProps) => {
-  const [search, setSearch] = useState("");
+  const [search, setSearch] = useState(initialSearch);
+  const t = useI18n();
+  const board = useRequiredBoard();
+  const mainCanvasSection = board.sections
+    .filter(
+      (section): section is EmptySection => section.kind === "empty" && getRootSectionLane(section.xOffset) === "main",
+    )
+    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset)
+    .at(0);
+  const placementOptions = useMemo(
+    () => [
+      ...(mainCanvasSection ? [{ value: mainCanvasSection.id, label: t("item.create.destination.mainCanvas") }] : []),
+      ...board.sections.flatMap((section) => {
+        if (section.kind !== "empty") return [];
+        const lane = getRootSectionLane(section.xOffset);
+        if (lane === "main") return [];
+        return [
+          {
+            value: section.id,
+            label: t(`item.create.destination.${lane === "left" ? "leftRail" : "rightRail"}`),
+          },
+        ];
+      }),
+      ...board.sections
+        .filter((section) => section.kind === "container")
+        .map((section) => ({
+          value: section.id,
+          label: section.options.title.trim() || t("section.container.untitled"),
+        })),
+    ],
+    [board.sections, mainCanvasSection, t],
+  );
+  const [targetSectionId, setTargetSectionId] = useState<string | null>(mainCanvasSection?.id ?? null);
  const [loadingSelection, setLoadingSelection] = useState<string | null>(null);
  const selectionLock = useRef(false);
-  const t = useI18n();
-  const { createItem, updateItemOptions, updateItemAdvancedOptions, updateItemIntegrations } = useItemActions();
+  const { createItem, removeItem } = useItemActions();
  const { openModal: openEditModal } = useModalAction(LazyWidgetEditModal);
+  const { openModal: openIntegrationModal } = useModalAction(IntegrationSelectModal);
  const settings = useSettings();
+  const trackSetup = useSetupAnalytics();
+  const flowStartedAt = useRef<number | null>(null);

  const availableKinds = useMemo(() => new Set((integrationData ?? []).map((i) => i.kind)), [integrationData]);

@@ -94,6 +148,21 @@ const ItemSelectModalContent = ({
    });
  };

+  const notifyCreated = (itemId: string, name: string) => {
+    showSuccessNotification({
+      title: t("item.create.notification.success.title"),
+      message: (
+        <Group justify="space-between" wrap="nowrap">
+          <Text size="sm">{t("item.create.notification.success.message", { name })}</Text>
+          <Button variant="subtle" size="compact-xs" onClick={() => removeItem({ itemId })}>
+            {t("common.action.undo")}
+          </Button>
+        </Group>
+      ),
+      autoClose: 10_000,
+    });
+  };
+
  const handleAddCustomWidget = async (customWidgetDefinition: NonNullable<typeof customWidgetDefs>[number]) => {
    if (!tryLockSelection(selectionLock)) return;
    setLoadingSelection(`custom:${customWidgetDefinition.id}`);
@@ -119,9 +188,15 @@ const ItemSelectModalContent = ({
            integrationIds: [],
          },
          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
-            createItem({ id: itemId, kind: "customApi", integrationIds: [] });
-            updateItemOptions({ itemId, newOptions: configuredOptions });
-            updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
+            createItem({
+              id: itemId,
+              kind: "customApi",
+              integrationIds: [],
+              options: configuredOptions,
+              targetSectionId: targetSectionId ?? undefined,
+              advancedOptions,
+            });
+            notifyCreated(itemId, customWidgetDefinition.name);
          },
          integrationData: [],
          integrationSupport: false,
@@ -141,6 +216,8 @@ const ItemSelectModalContent = ({

  const handleAdd = async (kind: WidgetKind) => {
    if (!tryLockSelection(selectionLock)) return;
+    flowStartedAt.current = performance.now();
+    trackSetup("widget-started", { entryPoint: "board", intent: kind });
    setLoadingSelection(kind);
    preloadWidgetEditModal();
    try {
@@ -157,32 +234,83 @@ const ItemSelectModalContent = ({
      const integrationIds = matchingIntegrations.map((i) => i.id);
      const itemId = createId();
      const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+      const openEditor = (
+        availableIntegrations: { id: string; name: string; url: string; kind: IntegrationKind }[],
+      ) => {
+        const selectedIntegrationIds = availableIntegrations.map((integration) => integration.id);
+        openEditModal(
+          {
+            kind,
+            definition,
+            value: {
+              advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
+              options: defaultOptions,
+              integrationIds: selectedIntegrationIds,
+            },
+            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
+              createItem({
+                id: itemId,
+                kind,
+                options,
+                integrationIds: newIntegrationIds,
+                targetSectionId: targetSectionId ?? undefined,
+                advancedOptions,
+              });
+              notifyCreated(itemId, t(`widget.${kind}.name`));
+              trackSetup("widget-completed", {
+                entryPoint: "board",
+                intent: kind,
+                outcome: "completed",
+                elapsedMs: flowStartedAt.current ? Math.round(performance.now() - flowStartedAt.current) : undefined,
+              });
+            },
+            integrationData: availableIntegrations,
+            integrationSupport: hasIntegrationSupport,
+            settings,
+          },
+          {
+            title: (titleT) => `${titleT("item.edit.title")} - ${titleT(`widget.${kind}.name`)}`,
+          },
+        );
+      };
+      const integrationsRequired =
+        hasIntegrationSupport && (!("integrationsRequired" in definition) || definition.integrationsRequired !== false);
+
+      if (integrationsRequired && integrationIds.length === 0) {
+        trackSetup("dependency-blocked", {
+          entryPoint: "board",
+          intent: kind,
+          outcome: "blocked",
+          canResolveInline: canCreateIntegration,
+        });
+        if (!canCreateIntegration) {
+          showErrorNotification({
+            title: t("item.create.missingIntegration.title"),
+            message: t("item.create.missingIntegration.noPermission"),
+          });
+          return;
+        }
+
+        actions.closeModal();
+        openIntegrationModal({
+          allowedKinds: (definition.supportedIntegrations ?? []).filter((integration) => integration !== "mock"),
+          onSuccess: (result) => {
+            if (result) {
+              trackSetup("dependency-resolved-inline", {
+                entryPoint: "board",
+                intent: kind,
+                outcome: "continued",
+                canResolveInline: true,
+              });
+              openEditor([result.integration]);
+            }
+          },
+        });
+        return;
+      }

-      createItem({ id: itemId, kind, integrationIds });
      actions.closeModal();
-
-      openEditModal(
-        {
-          kind,
-          definition,
-          value: {
-            advancedOptions: { title: null, customCssClasses: [], borderColor: "" },
-            options: defaultOptions,
-            integrationIds,
-          },
-          onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
-            updateItemOptions({ itemId, newOptions: options });
-            updateItemAdvancedOptions({ itemId, newAdvancedOptions: advancedOptions });
-            updateItemIntegrations({ itemId, newIntegrations: newIntegrationIds });
-          },
-          integrationData: matchingIntegrations,
-          integrationSupport: hasIntegrationSupport,
-          settings,
-        },
-        {
-          title: (titleT) => `${titleT("item.edit.title")} - ${titleT(`widget.${kind}.name`)}`,
-        },
-      );
+      openEditor(matchingIntegrations);
    } catch (error) {
      notifyDefinitionLoadError(error);
    } finally {
@@ -204,6 +332,18 @@ const ItemSelectModalContent = ({
        }
      }}
    >
+      {placementOptions.length > 1 && (
+        <Box style={{ gridColumn: "1 / -1" }}>
+          <Select
+            label={t("item.create.destination.label")}
+            description={t("item.create.destination.description")}
+            data={placementOptions}
+            value={targetSectionId}
+            onChange={setTargetSectionId}
+            allowDeselect={false}
+          />
+        </Box>
+      )}
      {filteredItems.map((item) => (
        <WidgetItem
          key={item.kind}
@@ -215,7 +355,11 @@ const ItemSelectModalContent = ({
          }}
          disabled={loadingSelection !== null}
          loading={loadingSelection === item.kind}
-          hasMatchingIntegration={item.supportedIntegrations.some((kind) => availableKinds.has(kind))}
+          connectionStatus={getWidgetConnectionStatus({
+            supportedIntegrations: item.supportedIntegrations,
+            availableKinds,
+            connectionOptional: widgetKindsWithOptionalIntegrations.has(item.kind),
+          })}
        />
      ))}

@@ -228,13 +372,15 @@ const ItemSelectModalContent = ({
            style={{ gridColumn: "1 / -1" }}
          />
          {filteredCustomWidgets.map((def) => (
-            <Card
+            <CatalogItem
              key={def.id}
-              className={classes.card}
-              h={selectGridCardHeight}
-              withBorder
-              pos="relative"
-              style={{ overflow: "hidden" }}
+              height={selectGridCardHeight}
+              label={def.name}
+              status={t("item.create.connectionStatus.noConnectionRequired")}
+              disabled={loadingSelection !== null}
+              busy={loadingSelection === `custom:${def.id}`}
+              onSelect={() => void handleAddCustomWidget(def)}
+              onFocus={() => void loadWidgetDefinition("customApi").catch(() => undefined)}
              onPointerEnter={() => void loadWidgetDefinition("customApi").catch(() => undefined)}
            >
              <Stack h="100%" gap="xs">
@@ -251,30 +397,9 @@ const ItemSelectModalContent = ({
                <Text lh={1.2} style={{ whiteSpace: "normal" }} size="xs" c="dimmed" lineClamp={1}>
                  {def.description ?? ""}
                </Text>
+                <ConnectionStatusBadge status="noConnectionRequired" />
              </Stack>
-              <Box
-                className={classes.action}
-                pos="absolute"
-                bottom={0}
-                left={0}
-                right={0}
-                p="xs"
-                style={{
-                  background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
-                }}
-              >
-                <Button
-                  onClick={() => void handleAddCustomWidget(def)}
-                  variant="light"
-                  size="xs"
-                  fullWidth
-                  disabled={loadingSelection !== null}
-                  loading={loadingSelection === `custom:${def.id}`}
-                >
-                  {t("item.create.addToBoard")}
-                </Button>
-              </Box>
-            </Card>
+            </CatalogItem>
          ))}

          <Box style={{ gridColumn: "1 / -1" }}>
@@ -296,11 +421,13 @@ const ItemSelectModalFrame = ({
  innerProps,
 }: {
  actions: { closeModal: () => void };
-  innerProps: { boardId: string };
+  innerProps: { boardId: string; initialIntegrationKind?: IntegrationKind; initialWidgetKind?: WidgetKind };
 }) => {
  const utils = clientApi.useUtils();
  const { data: session } = useSession();
  const isAdmin = session?.user.permissions.includes("admin") ?? false;
+  const canCreateIntegration = session?.user.permissions.includes("integration-create") ?? false;
+  const t = useI18n();
  const { data: integrationData } = clientApi.integration.all.useQuery();
  const { data: customWidgetDefs } = clientApi.customWidget.available.useQuery(
    { boardId: innerProps.boardId },
@@ -314,13 +441,23 @@ const ItemSelectModalFrame = ({
      customWidgetDefs={customWidgetDefs}
      ensureIntegrationDataAsync={() => utils.integration.all.ensureData()}
      isAdmin={isAdmin}
+      canCreateIntegration={canCreateIntegration}
+      initialSearch={
+        innerProps.initialWidgetKind
+          ? t(`widget.${innerProps.initialWidgetKind}.name`)
+          : innerProps.initialIntegrationKind
+            ? getIntegrationName(innerProps.initialIntegrationKind)
+            : undefined
+      }
    />
  );
 };

-export const ItemSelectModal = createModal<{ boardId: string }>((props) => (
-  <ItemSelectModalFrame {...props} />
-)).withOptions({
+export const ItemSelectModal = createModal<{
+  boardId: string;
+  initialIntegrationKind?: IntegrationKind;
+  initialWidgetKind?: WidgetKind;
+}>((props) => <ItemSelectModalFrame {...props} />).withOptions({
  defaultTitle: (t) => t("item.create.title"),
  size: modalSizeSelect,
 });
@@ -331,7 +468,7 @@ const WidgetItem = ({
  onIntent,
  disabled,
  loading,
-  hasMatchingIntegration,
+  connectionStatus,
 }: {
  item: {
    kind: WidgetKind;
@@ -344,24 +481,21 @@ const WidgetItem = ({
  onIntent: () => void;
  disabled: boolean;
  loading: boolean;
-  hasMatchingIntegration: boolean;
+  connectionStatus: WidgetConnectionStatus;
 }) => {
  const t = useI18n();
+  const statusLabel = t(`item.create.connectionStatus.${connectionStatus}`);

  return (
-    <Card
-      className={classes.card}
-      h={selectGridCardHeight}
-      withBorder
-      pos="relative"
-      style={{
-        overflow: "hidden",
-        borderColor: hasMatchingIntegration ? "var(--mantine-color-blue-6)" : undefined,
-        borderWidth: hasMatchingIntegration ? 2 : undefined,
-      }}
+    <CatalogItem
+      height={selectGridCardHeight}
+      label={item.name}
+      status={statusLabel}
      onFocus={onIntent}
      onPointerEnter={onIntent}
-      aria-busy={loading || undefined}
+      onSelect={onSelect}
+      disabled={disabled}
+      busy={loading}
    >
      <Stack h="100%" gap="xs">
        <Group gap="sm" wrap="nowrap" align="flex-start">
@@ -375,24 +509,21 @@ const WidgetItem = ({
            {item.description}
          </Text>
        </Tooltip>
+        <ConnectionStatusBadge status={connectionStatus} />
        <SupportedIntegrations integrations={item.supportedIntegrations} />
      </Stack>
-      <Box
-        className={classes.action}
-        pos="absolute"
-        bottom={0}
-        left={0}
-        right={0}
-        p="xs"
-        style={{
-          background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
-        }}
-      >
-        <Button onClick={onSelect} variant="light" size="xs" fullWidth disabled={disabled} loading={loading}>
-          {t(`item.create.addToBoard`)}
-        </Button>
-      </Box>
-    </Card>
+    </CatalogItem>
+  );
+};
+
+const ConnectionStatusBadge = ({ status }: { status: WidgetConnectionStatus }) => {
+  const t = useI18n();
+  const color = status === "ready" ? "green" : status === "needsSetup" ? "yellow" : "gray";
+
+  return (
+    <Badge variant="light" color={color} size="xs" tt="none" w="fit-content" maw="100%">
+      {t(`item.create.connectionStatus.${status}`)}
+    </Badge>
  );
 };

@@ -405,7 +536,7 @@ const SupportedIntegrations = ({ integrations }: { integrations: IntegrationKind
  const moreCount = integrations.length - countToShow;

  return (
-    <Group gap={2} mt="auto">
+    <Group gap={2}>
      <Tooltip.Group closeDelay={100}>
        <Group gap={2}>
          {integrations.slice(0, countToShow).map((integration) => (
@@ -65,4 +65,6 @@ export const LazyWidgetEditModal = createModal<WidgetEditModalProps<WidgetKind>>
    return t("item.edit.title");
  },
  size: modalSizeForm,
+  presentation: "inspector",
+  closeOnClickOutside: false,
 });