feat!: release v2 (#6545)

Co-authored-by: Artur <145776561+arturict@users.noreply.github.com> Co-authored-by: arturict <arturict@users.noreply.github.com> Co-authored-by: Thomas <thomas@ajnart.fr> Co-authored-by: Afonso Jorge Ramos <afonsojorgeramos@gmail.com> Co-authored-by: Danura30082 <danura30082+github@gmail.com> Co-authored-by: Kushie <122986913+kushiemoon-dev@users.noreply.github.com> Co-authored-by: ajnart <thomas@ajnart.fr> Co-authored-by: ajnart <thomas@ajnart.dev> Co-authored-by: chenjun <chenjun@foxmail.com> Co-authored-by: Wikibear <wikibear@users.noreply.github.com> Co-authored-by: Bergasha <bergasha@gmail.com> Co-authored-by: leafyelin <43306196+leafyelin@users.noreply.github.com> Co-authored-by: Lucas Araujo <lucas.lra@gmail.com> Co-authored-by: GreenMonito <86085570+GreenMonito@users.noreply.github.com> Co-authored-by: Nerdy-Technician <roffo@nerdy-technician.social> Co-authored-by: Jun <34545896+jcstrong@users.noreply.github.com> Co-authored-by: Edmond Abraham <54119952+gitedmond@users.noreply.github.com> Co-authored-by: thrawnx <tight.bulb9384@fastmail.com> Co-authored-by: Chris <58918656+nordada@users.noreply.github.com> Co-authored-by: yi111 <153097222+Yi-111-a@users.noreply.github.com> Co-authored-by: Yanis <naamaneyanis@gmail.com> Co-authored-by: Wikibear <me@sej.de> Co-authored-by: alessiottavo <93441886+alessiottavo@users.noreply.github.com>
2026-10-02 21:00:14 +02:00
1 parent 3a53bb77aa
commit fcd7c979df
@@ -0,0 +1,6 @@
+export { buildSortedIntegrations, categoryTranslationKeys, filterIntegrations } from "./integration-grid-shared";
+export type { IntegrationGridItem } from "./integration-grid-shared";
+export { IntegrationMultiSelectGrid } from "./integration-multi-select-grid";
+export type { IntegrationMultiSelectGridProps } from "./integration-multi-select-grid";
+export { IntegrationSelectGrid } from "./integration-select-grid";
+export type { IntegrationSelectGridProps } from "./integration-select-grid";
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { integrationKinds } from "@homarr/definitions";
+
+import { buildSortedIntegrations } from "./integration-grid-shared";
+
+describe("buildSortedIntegrations", () => {
+  it("keeps every real integration available during onboarding", () => {
+    const kinds = buildSortedIntegrations({ onboarding: true }).map((integration) => integration.kind);
+
+    expect(kinds).toHaveLength(integrationKinds.filter((kind) => kind !== "mock").length);
+    expect(kinds).not.toContain("mock");
+  });
+
+  it("limits the grid to the allowed integration kinds", () => {
+    const kinds = buildSortedIntegrations({ allowedKinds: ["jellyfin", "sonarr"] }).map(
+      (integration) => integration.kind,
+    );
+
+    expect(kinds).toEqual(expect.arrayContaining(["jellyfin", "sonarr"]));
+    expect(kinds).toHaveLength(2);
+  });
+});
@@ -0,0 +1,81 @@
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import {
+  getIntegrationName,
+  getIntegrationOnboardingMetadata,
+  getWidgetKindsForIntegration,
+  integrationDefs,
+  integrationKinds,
+} from "@homarr/definitions";
+
+export const categoryTranslationKeys: Record<string, string> = {
+  dnsHole: "integration.category.dnsHole",
+  mediaService: "integration.category.mediaService",
+  calendar: "integration.category.calendar",
+  mediaSearch: "integration.category.mediaSearch",
+  mediaRelease: "integration.category.mediaRelease",
+  mediaRequest: "integration.category.mediaRequest",
+  downloadClient: "integration.category.downloadClient",
+  usenet: "integration.category.usenet",
+  torrent: "integration.category.torrent",
+  miscellaneous: "integration.category.miscellaneous",
+  smartHomeServer: "integration.category.smartHomeServer",
+  indexerManager: "integration.category.indexerManager",
+  healthMonitoring: "integration.category.healthMonitoring",
+  beszel: "integration.category.beszel",
+  search: "integration.category.search",
+  mediaTranscoding: "integration.category.mediaTranscoding",
+  networkController: "integration.category.networkController",
+  notifications: "integration.category.notifications",
+  firewall: "integration.category.firewall",
+  photoService: "integration.category.photoService",
+  notes: "integration.category.notes",
+  mediaMonitoring: "integration.category.mediaMonitoring",
+  speedtest: "integration.category.speedtest",
+  analytics: "integration.category.analytics",
+  vpn: "integration.category.vpn",
+  documents: "integration.category.documents",
+  mediaLibrary: "integration.category.mediaLibrary",
+  uptimeMonitoring: "integration.category.uptimeMonitoring",
+};
+
+export interface IntegrationGridItem {
+  kind: IntegrationKind;
+  name: string;
+  categories: string[];
+  widgets: WidgetKind[];
+}
+
+export const buildSortedIntegrations = (
+  options: {
+    enableMockIntegration?: boolean;
+    onboarding?: boolean;
+    allowedKinds?: readonly IntegrationKind[];
+  } = {},
+): IntegrationGridItem[] =>
+  integrationKinds
+    .filter((kind) => {
+      if (options.allowedKinds && !options.allowedKinds.includes(kind)) return false;
+      if (options.onboarding && getIntegrationOnboardingMetadata(kind).hidden) return false;
+      if (!options.enableMockIntegration && kind === "mock") return false;
+      return true;
+    })
+    .map((kind) => ({
+      kind,
+      name: getIntegrationName(kind),
+      categories: [...new Set(integrationDefs[kind].category.flat())] as string[],
+      widgets: getWidgetKindsForIntegration(kind),
+    }))
+    .toSorted((left, right) => {
+      const leftFeaturedOrder = getIntegrationOnboardingMetadata(left.kind).featuredOrder;
+      const rightFeaturedOrder = getIntegrationOnboardingMetadata(right.kind).featuredOrder;
+      if (leftFeaturedOrder !== null && rightFeaturedOrder !== null) return leftFeaturedOrder - rightFeaturedOrder;
+      if (leftFeaturedOrder !== null) return -1;
+      if (rightFeaturedOrder !== null) return 1;
+      return right.widgets.length - left.widgets.length || left.name.localeCompare(right.name);
+    });
+
+export const filterIntegrations = (items: IntegrationGridItem[], search: string) => {
+  const query = search.toLocaleLowerCase().trim();
+  if (!query) return items;
+  return items.filter((item) => item.name.toLocaleLowerCase().includes(query));
+};
@@ -0,0 +1,141 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { Badge, Card, Center, Group, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
+import { IconBrandDocker, IconCheck, IconPuzzle } from "@tabler/icons-react";
+
+import { getWidgetName } from "@homarr/definitions";
+import type { IntegrationKind } from "@homarr/definitions";
+import { useI18n } from "@homarr/translation/client";
+
+import { IntegrationAvatar } from "../components/integration-avatar";
+import { SelectGridLayout, selectGridCardHeight } from "../select-grid-layout";
+import { buildSortedIntegrations, categoryTranslationKeys, filterIntegrations } from "./integration-grid-shared";
+import classes from "./integration-select-grid.module.css";
+
+export interface IntegrationMultiSelectGridProps {
+  selectedKinds: IntegrationKind[];
+  onSelectionChange: (kinds: IntegrationKind[]) => void;
+  enableMockIntegration?: boolean;
+  onboarding?: boolean;
+  detectedKinds?: Set<IntegrationKind>;
+}
+
+export const IntegrationMultiSelectGrid = ({
+  selectedKinds: selectedKindsArray,
+  onSelectionChange,
+  enableMockIntegration = false,
+  onboarding = false,
+  detectedKinds,
+}: IntegrationMultiSelectGridProps) => {
+  const [search, setSearch] = useState("");
+  const selectedKinds = useMemo(() => new Set(selectedKindsArray), [selectedKindsArray]);
+  const t = useI18n();
+  const toggleKind = useCallback(
+    (kind: IntegrationKind) => {
+      const current = new Set(selectedKindsArray);
+      if (current.has(kind)) current.delete(kind);
+      else current.add(kind);
+      onSelectionChange(Array.from(current));
+    },
+    [onSelectionChange, selectedKindsArray],
+  );
+  const integrations = useMemo(
+    () => buildSortedIntegrations({ enableMockIntegration, onboarding }),
+    [enableMockIntegration, onboarding],
+  );
+  const sorted = useMemo(() => {
+    if (!detectedKinds || detectedKinds.size === 0) return integrations;
+    return [
+      ...integrations.filter((integration) => detectedKinds.has(integration.kind)),
+      ...integrations.filter((integration) => !detectedKinds.has(integration.kind)),
+    ];
+  }, [detectedKinds, integrations]);
+  const filtered = useMemo(() => filterIntegrations(sorted, search), [search, sorted]);
+
+  return (
+    <SelectGridLayout
+      search={search}
+      onSearchChange={setSearch}
+      placeholder={`${t("integration.page.list.search")}...`}
+      ariaLabel={t("integration.page.list.search")}
+      disableAutoFocus={onboarding}
+    >
+      {filtered.map((integration) => {
+        const isSelected = selectedKinds.has(integration.kind);
+        const isDetected = detectedKinds?.has(integration.kind) ?? false;
+        return (
+          <UnstyledButton
+            className={classes.choice}
+            key={integration.kind}
+            onClick={() => toggleKind(integration.kind)}
+            aria-label={integration.name}
+            aria-pressed={isSelected}
+          >
+            <Card
+              h={selectGridCardHeight}
+              className={classes.card}
+              style={{
+                borderColor: isSelected ? "var(--mantine-primary-color-filled)" : undefined,
+                borderWidth: isSelected ? 2 : undefined,
+              }}
+              withBorder
+            >
+              <Stack justify="space-between" h="100%" gap="xs">
+                <Group gap="sm" wrap="nowrap" align="flex-start">
+                  <IntegrationAvatar kind={integration.kind} size="sm" />
+                  <Text fw={500} lh={1.2} size="sm" lineClamp={2} style={{ flex: 1 }}>
+                    {integration.name}
+                  </Text>
+                  {isSelected && <IconCheck size={18} color="var(--mantine-primary-color-filled)" />}
+                </Group>
+                <Stack gap={4} mt="auto">
+                  {isDetected && (
+                    <Badge variant="light" color="teal" size="xs" leftSection={<IconBrandDocker size={12} />}>
+                      {t("integration.grid.detected")}
+                    </Badge>
+                  )}
+                  <Group gap={4} wrap="wrap">
+                    {integration.categories.slice(0, 2).map((category) => (
+                      <Badge key={category} variant="light" size="xs">
+                        {categoryTranslationKeys[category] ? t(categoryTranslationKeys[category] as never) : category}
+                      </Badge>
+                    ))}
+                  </Group>
+                  {integration.widgets.length > 0 ? (
+                    <Tooltip
+                      multiline
+                      w={200}
+                      label={
+                        <Stack gap={4}>
+                          {integration.widgets.map((widgetKind) => (
+                            <Text key={widgetKind} size="xs">
+                              {getWidgetName(widgetKind, t)}
+                            </Text>
+                          ))}
+                        </Stack>
+                      }
+                    >
+                      <Badge variant="light" color="blue" size="sm" leftSection={<IconPuzzle size={12} />}>
+                        {t("integration.grid.widgetCount", { count: String(integration.widgets.length) })}
+                      </Badge>
+                    </Tooltip>
+                  ) : (
+                    <Badge variant="light" color="gray" size="sm">
+                      {t("integration.grid.noWidgets")}
+                    </Badge>
+                  )}
+                </Stack>
+              </Stack>
+            </Card>
+          </UnstyledButton>
+        );
+      })}
+      {filtered.length === 0 && (
+        <Center p="xl" style={{ gridColumn: "1 / -1" }}>
+          <Text c="dimmed">{t("common.noResults")}</Text>
+        </Center>
+      )}
+    </SelectGridLayout>
+  );
+};
@@ -0,0 +1,26 @@
+.choice {
+  width: 100%;
+  border-radius: var(--mantine-radius-lg);
+  text-align: start;
+}
+
+.choice:focus-visible {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
+}
+
+.card {
+  transition:
+    background-color 150ms ease-out,
+    border-color 150ms ease-out;
+}
+
+.choice:hover .card {
+  background-color: var(--mantine-color-default-hover);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+}
@@ -0,0 +1,2 @@
+declare const classes: Record<string, string>;
+export default classes;
@@ -0,0 +1,279 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import { MantineProvider } from "@mantine/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { IntegrationKind } from "@homarr/definitions";
+
+import { IntegrationSelectGrid } from "./integration-select-grid";
+
+vi.mock("@homarr/definitions", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@homarr/definitions")>();
+  return {
+    ...actual,
+    getWidgetKindsForIntegration: (kind: IntegrationKind) => {
+      if (kind === "wud") return [];
+      return actual.getWidgetKindsForIntegration(kind);
+    },
+  };
+});
+
+vi.mock("@homarr/translation/client", () => ({
+  useI18n: () => (key: string, values?: { count?: number }) => {
+    const translations: Record<string, string> = {
+      "integration.page.list.search": "Search integrations",
+      "common.noResults": "No results found",
+      "integration.grid.noWidgets": "No widgets tied to this service",
+      "integration.grid.tiedWidgets": "Tied Widgets",
+      "integration.grid.connected": `${values?.count ?? 0} connected`,
+      "integration.grid.more": `+${values?.count ?? 0} more`,
+      "widget.mediaServer.name": "Media Server",
+      "widget.calendar.name": "Calendar",
+      "widget.downloads.name": "Downloads",
+      "integration.category.mediaService": "Media Service",
+      "integration.category.downloadClient": "Download Client",
+      "integration.category.calendar": "Calendar",
+      "integration.category.smartHomeServer": "Smart Home",
+      "integration.category.usenet": "Usenet",
+      "integration.category.torrent": "Torrent",
+    };
+    return translations[key] ?? key;
+  },
+}));
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  window.matchMedia = vi.fn().mockImplementation(() => ({
+    matches: false,
+    media: "",
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }));
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+});
+
+describe("IntegrationSelectGrid", () => {
+  it("renders a 4-column responsive grid of selectable integration cards", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["jellyfin", "sonarr", "radarr", "sabNzbd"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    const cards = host.querySelectorAll("button");
+    expect(cards.length).toBe(4);
+    expect(host.textContent).toContain("Jellyfin");
+    expect(host.textContent).toContain("Sonarr");
+    expect(host.textContent).toContain("Radarr");
+    expect(host.textContent).toContain("SABnzbd");
+  });
+
+  it("renders tied widgets with icons and labels inside integration cards", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["jellyfin"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    expect(host.textContent).toContain("Tied Widgets");
+    // Jellyfin is tied to Media Server widget
+    expect(host.textContent).toContain("Media Server");
+  });
+
+  it("displays fallback message when integration has no tied widgets", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["wud"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    expect(host.querySelector("button")).not.toBeNull();
+    expect(host.textContent).toContain("No widgets tied to this service");
+  });
+
+  it("displays '{count} connected' in footerLeft when integration instances exist", async () => {
+    const onSelect = vi.fn();
+    const integrationData = [
+      { kind: "jellyfin" as IntegrationKind, name: "Home Jellyfin" },
+      { kind: "jellyfin" as IntegrationKind, name: "Remote Jellyfin" },
+      { kind: "sonarr" as IntegrationKind, name: "Sonarr Instance" },
+    ];
+
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid
+            onSelect={onSelect}
+            allowedKinds={["jellyfin", "radarr"]}
+            integrationData={integrationData}
+          />
+        </MantineProvider>,
+      ),
+    );
+
+    // Jellyfin has 2 connected
+    expect(host.textContent).toContain("2 connected");
+
+    // Radarr has 0 connected, so it doesn't show "0 connected"
+    expect(host.textContent).not.toContain("0 connected");
+  });
+
+  it("filters integrations dynamically by search input", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["jellyfin", "sonarr", "radarr", "plex"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    const searchInput = host.querySelector("input");
+    expect(searchInput).not.toBeNull();
+
+    // Type "jelly"
+    await act(async () => {
+      if (searchInput) {
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set;
+        nativeInputValueSetter?.call(searchInput, "jelly");
+        searchInput.dispatchEvent(new Event("input", { bubbles: true }));
+        searchInput.dispatchEvent(new Event("change", { bubbles: true }));
+      }
+    });
+
+    const cards = host.querySelectorAll("button");
+    expect(cards.length).toBe(1);
+    expect(host.textContent).toContain("Jellyfin");
+    expect(host.textContent).not.toContain("Sonarr");
+    expect(host.textContent).not.toContain("Radarr");
+  });
+
+  it("displays empty state when no integrations match search query", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["jellyfin", "sonarr"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    const searchInput = host.querySelector("input");
+    await act(async () => {
+      if (searchInput) {
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set;
+        nativeInputValueSetter?.call(searchInput, "nonexistent-integration-query");
+        searchInput.dispatchEvent(new Event("input", { bubbles: true }));
+        searchInput.dispatchEvent(new Event("change", { bubbles: true }));
+      }
+    });
+
+    expect(host.textContent).toContain("No results found");
+    expect(host.querySelectorAll("button").length).toBe(0);
+  });
+
+  it("calls onSelect when Enter is pressed with exactly 1 search match", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["jellyfin", "sonarr"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    const searchInput = host.querySelector("input");
+    await act(async () => {
+      if (searchInput) {
+        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value")?.set;
+        nativeInputValueSetter?.call(searchInput, "jelly");
+        searchInput.dispatchEvent(new Event("input", { bubbles: true }));
+        searchInput.dispatchEvent(new Event("change", { bubbles: true }));
+      }
+    });
+
+    await act(async () => {
+      searchInput?.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    });
+
+    expect(onSelect).toHaveBeenCalledWith("jellyfin");
+  });
+
+  it("calls onSelect when an integration card is clicked", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} allowedKinds={["sonarr"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    const cardButton = host.querySelector("button");
+    await act(async () => cardButton?.click());
+    expect(onSelect).toHaveBeenCalledWith("sonarr");
+  });
+
+  it("includes mock integration when enableMockIntegration is true", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} enableMockIntegration allowedKinds={["mock", "sonarr"]} />
+        </MantineProvider>,
+      ),
+    );
+
+    expect(host.textContent).toContain("Mock");
+    expect(host.textContent).toContain("Sonarr");
+  });
+
+  it("excludes mock integration when enableMockIntegration is false", async () => {
+    const onSelect = vi.fn();
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <IntegrationSelectGrid onSelect={onSelect} enableMockIntegration={false} />
+        </MantineProvider>,
+      ),
+    );
+
+    const buttons = Array.from(host.querySelectorAll("button"));
+    const mockButton = buttons.find((btn) => btn.getAttribute("aria-label")?.toLowerCase() === "mock");
+    expect(mockButton).toBeUndefined();
+  });
+});
@@ -0,0 +1,158 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { Badge, Center, Group, Input, ScrollArea, SimpleGrid, Stack, Text } from "@mantine/core";
+import { IconSearch } from "@tabler/icons-react";
+
+import { getWidgetName } from "@homarr/definitions";
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import { useI18n } from "@homarr/translation/client";
+
+import { IntegrationAvatar } from "../components/integration-avatar";
+import { SelectableCard } from "../components/selectable-card";
+import { selectGridCols } from "../select-grid-layout";
+import { widgetCatalogIcons } from "../widget-icons";
+import { buildSortedIntegrations, filterIntegrations } from "./integration-grid-shared";
+import type { IntegrationGridItem } from "./integration-grid-shared";
+
+export interface IntegrationSelectGridProps {
+  onSelect: (kind: IntegrationKind) => void;
+  enableMockIntegration?: boolean;
+  allowedKinds?: readonly IntegrationKind[];
+  integrationData?: { kind: IntegrationKind; name?: string }[];
+}
+
+export const IntegrationSelectGrid = ({
+  onSelect,
+  enableMockIntegration = false,
+  allowedKinds,
+  integrationData,
+}: IntegrationSelectGridProps) => {
+  const [search, setSearch] = useState("");
+  const t = useI18n();
+  const integrations = useMemo(
+    () => buildSortedIntegrations({ enableMockIntegration, allowedKinds }),
+    [allowedKinds, enableMockIntegration],
+  );
+  const filtered = useMemo(() => filterIntegrations(integrations, search), [integrations, search]);
+
+  return (
+    <Stack gap="md">
+      {/* Top Search Input */}
+      <Input
+        value={search}
+        onChange={(event) => setSearch(event.currentTarget.value)}
+        leftSection={<IconSearch size={16} />}
+        placeholder={`${t("integration.page.list.search")}...`}
+        aria-label={t("integration.page.list.search")}
+        data-autofocus
+        onKeyDown={(event) => {
+          if (event.key === "Enter" && filtered.length === 1 && filtered[0]) {
+            onSelect(filtered[0].kind);
+          }
+        }}
+      />
+
+      {/* Scrollable Container with Integration Cards */}
+      <ScrollArea.Autosize mah="70vh" offsetScrollbars>
+        <Stack gap="md" pt="xs" pr="xs" px={4}>
+          <SimpleGrid cols={selectGridCols} spacing="sm">
+            {filtered.map((integration) => (
+              <IntegrationCard
+                key={integration.kind}
+                integration={integration}
+                onSelect={onSelect}
+                connectedCount={(integrationData ?? []).filter((i) => i.kind === integration.kind).length}
+              />
+            ))}
+          </SimpleGrid>
+
+          {filtered.length === 0 && (
+            <Center p="xl">
+              <Text c="dimmed">{t("common.noResults")}</Text>
+            </Center>
+          )}
+        </Stack>
+      </ScrollArea.Autosize>
+    </Stack>
+  );
+};
+
+// =========================================================================
+// IntegrationCard: Shared Modular SelectableCard with Tied Widgets
+// =========================================================================
+const IntegrationCard = ({
+  integration,
+  onSelect,
+  connectedCount = 0,
+}: {
+  integration: IntegrationGridItem;
+  onSelect: (kind: IntegrationKind) => void;
+  connectedCount?: number;
+}) => {
+  const t = useI18n();
+
+  return (
+    <SelectableCard
+      onClick={() => onSelect(integration.kind)}
+      aria-label={integration.name}
+      icon={<IntegrationAvatar kind={integration.kind} size="sm" />}
+      title={
+        <Text fw={700} size="md" style={{ whiteSpace: "nowrap" }}>
+          {integration.name}
+        </Text>
+      }
+      footerLeft={
+        connectedCount > 0 ? (
+          <Badge variant="light" color="teal" size="xs" radius="xs">
+            {t("integration.grid.connected", { count: connectedCount })}
+          </Badge>
+        ) : null
+      }
+    >
+      <Text size="10px" tt="uppercase" fw={700} c="dimmed">
+        {t("integration.grid.tiedWidgets")}
+      </Text>
+      <IntegrationTiedWidgets widgets={integration.widgets} />
+    </SelectableCard>
+  );
+};
+
+const IntegrationTiedWidgets = ({ widgets, limit }: { widgets: WidgetKind[]; limit?: number }) => {
+  const t = useI18n();
+  if (widgets.length === 0) {
+    return (
+      <Text size="xs" c="dimmed" fs="italic">
+        {t("integration.grid.noWidgets")}
+      </Text>
+    );
+  }
+
+  const items = limit ? widgets.slice(0, limit) : widgets;
+  const moreCount = limit ? widgets.length - limit : 0;
+
+  return (
+    <Group gap={4} wrap="wrap">
+      {items.map((widgetKind) => {
+        const WidgetIcon = widgetCatalogIcons[widgetKind];
+        return (
+          <Badge
+            key={widgetKind}
+            variant="default"
+            radius="xs"
+            size="xs"
+            leftSection={<WidgetIcon size={12} />}
+            style={{ fontWeight: 500 }}
+          >
+            {getWidgetName(widgetKind, t)}
+          </Badge>
+        );
+      })}
+      {moreCount > 0 && (
+        <Badge variant="subtle" color="gray" size="xs" radius="xs">
+          {t("integration.grid.more", { count: moreCount })}
+        </Badge>
+      )}
+    </Group>
+  );
+};