Merge origin/release/v2 into feat/fix-v2-stack-review-findings

packages/ui/src/components/beta-badge.tsx

@@ -3,17 +3,17 @@
 import type { BadgeProps } from "@mantine/core";
 import { Badge } from "@mantine/core";
 
-import { useTranslations } from "@homarr/translation/client";
+import { useI18n } from "@homarr/translation/client";
 
 interface BetaBadgeProps {
   size: BadgeProps["size"];
 }
 
 export const BetaBadge = ({ size }: BetaBadgeProps) => {
-  const t = useTranslations();
+  const t = useI18n("common");
   return (
     <Badge size={size} color="green" variant="outline">
-      {t("common.beta")}
+      {t("beta")}
     </Badge>
   );
 };

packages/ui/src/components/color-scheme-combobox.tsx

@@ -6,7 +6,7 @@ import { IconCheck, IconDeviceDesktop, IconMoon, IconSun } from "@tabler/icons-r
 
 import type { ColorScheme } from "@homarr/definitions";
 import { colorSchemes } from "@homarr/definitions";
-import { useScopedI18n } from "@homarr/translation/client";
+import { useI18n } from "@homarr/translation/client";
 
 const schemeIcons: Record<ColorScheme, React.ElementType> = {
   auto: IconDeviceDesktop,
@@ -22,7 +22,7 @@ interface ColorSchemeComboboxProps {
 }
 
 export const ColorSchemeCombobox = ({ label, value, onChange, width }: ColorSchemeComboboxProps) => {
-  const tOptions = useScopedI18n("common.colorScheme.options");
+  const tOptions = useI18n("common.colorScheme.options");
   const combobox = useCombobox({ onDropdownClose: () => combobox.resetSelectedOption() });
 
   return (

packages/ui/src/components/floating-tip/floating-tip.module.css

@@ -0,0 +1,17 @@
+.root {
+  position: fixed;
+  inset-inline: var(--mantine-spacing-md);
+  bottom: var(--floating-tip-bottom);
+  z-index: var(--floating-tip-z-index);
+  display: flex;
+  justify-content: center;
+  pointer-events: none;
+}
+
+.alert {
+  width: fit-content;
+  max-width: min(var(--floating-tip-max-width), calc(100vw - 2 * var(--mantine-spacing-md)));
+  pointer-events: auto;
+  box-shadow: var(--mantine-shadow-xl);
+  backdrop-filter: blur(12px);
+}

packages/ui/src/components/floating-tip/floating-tip.module.d.css.ts

@@ -0,0 +1,5 @@
+declare const classes: {
+  readonly root: string;
+  readonly alert: string;
+};
+export default classes;

packages/ui/src/components/floating-tip/floating-tip.spec.tsx

@@ -0,0 +1,96 @@
+// @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 { FloatingTip } from "./floating-tip";
+
+let root: Root;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  window.localStorage.clear();
+  (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(),
+  }));
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+  document.body.querySelectorAll("[data-portal]").forEach((portal) => portal.remove());
+  vi.useRealTimers();
+});
+
+describe("FloatingTip", () => {
+  it("shows after the configured delay and auto-dismisses", async () => {
+    await act(async () =>
+      root.render(
+        <MantineProvider>
+          <FloatingTip opened showDelay={2_000} dismissAfter={3_000} transitionDuration={0}>
+            Select several apps
+          </FloatingTip>
+        </MantineProvider>,
+      ),
+    );
+
+    expect(document.body.textContent).not.toContain("Select several apps");
+
+    await act(async () => vi.advanceTimersByTime(2_000));
+    expect(document.body.textContent).toContain("Select several apps");
+
+    await act(async () => vi.advanceTimersByTime(3_000));
+    expect(document.body.textContent).not.toContain("Select several apps");
+  });
+
+  it("provides an accessible close button and remembers dismissal", async () => {
+    const onDismiss = vi.fn();
+    const renderTip = (opened: boolean) =>
+      root.render(
+        <MantineProvider>
+          <FloatingTip
+            opened={opened}
+            showDelay={0}
+            transitionDuration={0}
+            closable
+            closeButtonLabel="Dismiss tip"
+            rememberDismissal
+            storageKey="selection"
+            onDismiss={onDismiss}
+          >
+            Select several apps
+          </FloatingTip>
+        </MantineProvider>,
+      );
+
+    await act(async () => renderTip(true));
+    await act(async () => vi.advanceTimersByTime(0));
+
+    const closeButton = document.body.querySelector<HTMLButtonElement>('button[aria-label="Dismiss tip"]');
+    expect(closeButton).not.toBeNull();
+    await act(async () => closeButton?.click());
+
+    expect(onDismiss).toHaveBeenCalledOnce();
+    expect(window.localStorage.getItem("homarr:floating-tip:selection")).toBe("dismissed");
+
+    await act(async () => renderTip(false));
+    await act(async () => renderTip(true));
+    await act(async () => vi.advanceTimersByTime(0));
+    expect(document.body.textContent).not.toContain("Select several apps");
+  });
+});

packages/ui/src/components/floating-tip/floating-tip.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Alert, Box, createVarsResolver, factory, Portal, rem, Transition, useProps, useStyles } from "@mantine/core";
+import type { AlertProps, BoxProps, ElementProps, Factory, MantineTransition, StylesApiProps } from "@mantine/core";
+
+import classes from "./floating-tip.module.css";
+
+export type FloatingTipStylesNames = "root" | "alert";
+export type FloatingTipCssVariables = {
+  root: "--floating-tip-bottom" | "--floating-tip-max-width" | "--floating-tip-z-index";
+};
+
+interface FloatingTipBaseProps
+  extends BoxProps, StylesApiProps<FloatingTipFactory>, Omit<ElementProps<"div">, "title"> {
+  /** Controls whether this tip cycle should run. */
+  opened: boolean;
+  /** Delay before the tip appears, in milliseconds. */
+  showDelay?: number;
+  /** Time the tip remains visible, in milliseconds. Set to `null` to keep it open. */
+  dismissAfter?: number | null;
+  /** Enter and exit animation duration, in milliseconds. */
+  transitionDuration?: number;
+  /** Mantine transition used to show and hide the tip. */
+  transition?: MantineTransition;
+  /** Distance from the bottom edge of the viewport. */
+  bottomOffset?: number | string;
+  /** Maximum width of the alert. */
+  maxWidth?: number | string;
+  /** Stack order of the floating tip. */
+  zIndex?: number;
+  /** Props forwarded to the underlying Mantine Alert. */
+  alertProps?: Omit<
+    AlertProps,
+    "children" | "classNames" | "closeButtonLabel" | "onClose" | "styles" | "withCloseButton"
+  >;
+  /** Called when the user closes the tip. */
+  onDismiss?: () => void;
+}
+
+type FloatingTipCloseProps =
+  | { closable: true; closeButtonLabel: string }
+  | { closable?: false; closeButtonLabel?: never };
+
+type FloatingTipPersistenceProps =
+  | { rememberDismissal: true; storageKey: string }
+  | { rememberDismissal?: false; storageKey?: never };
+
+export type FloatingTipProps = FloatingTipBaseProps & FloatingTipCloseProps & FloatingTipPersistenceProps;
+
+export type FloatingTipFactory = Factory<{
+  props: FloatingTipProps;
+  ref: HTMLDivElement;
+  stylesNames: FloatingTipStylesNames;
+  vars: FloatingTipCssVariables;
+}>;
+
+const defaultProps = {
+  showDelay: 0,
+  dismissAfter: null,
+  transitionDuration: 200,
+  transition: "slide-up",
+  bottomOffset: 24,
+  maxWidth: 520,
+  zIndex: 1000,
+  closable: false,
+  rememberDismissal: false,
+} satisfies Partial<FloatingTipProps>;
+
+const toCssSize = (value: number | string | undefined) => (typeof value === "number" ? rem(value) : value);
+
+const varsResolver = createVarsResolver<FloatingTipFactory>((_theme, { bottomOffset, maxWidth, zIndex }) => ({
+  root: {
+    "--floating-tip-bottom": toCssSize(bottomOffset),
+    "--floating-tip-max-width": toCssSize(maxWidth),
+    "--floating-tip-z-index": zIndex?.toString(),
+  },
+}));
+
+const getDismissalStorageKey = (storageKey: string) => `homarr:floating-tip:${storageKey}`;
+
+export const FloatingTip = factory<FloatingTipFactory>((_props) => {
+  const props = useProps("FloatingTip", defaultProps, _props);
+  const {
+    ref,
+    classNames,
+    className,
+    style,
+    styles,
+    unstyled,
+    vars,
+    attributes,
+    opened,
+    showDelay,
+    dismissAfter,
+    transitionDuration,
+    transition,
+    bottomOffset: _bottomOffset,
+    maxWidth: _maxWidth,
+    zIndex: _zIndex,
+    closable,
+    closeButtonLabel,
+    rememberDismissal,
+    storageKey,
+    alertProps,
+    onDismiss,
+    children,
+    ...others
+  } = props;
+  const [visible, setVisible] = useState(false);
+  const showTimerRef = useRef<number | null>(null);
+  const dismissTimerRef = useRef<number | null>(null);
+
+  const clearTimers = useCallback(() => {
+    if (showTimerRef.current !== null) window.clearTimeout(showTimerRef.current);
+    if (dismissTimerRef.current !== null) window.clearTimeout(dismissTimerRef.current);
+    showTimerRef.current = null;
+    dismissTimerRef.current = null;
+  }, []);
+
+  useEffect(() => {
+    clearTimers();
+    setVisible(false);
+
+    if (!opened) return;
+
+    if (rememberDismissal) {
+      try {
+        if (window.localStorage.getItem(getDismissalStorageKey(storageKey)) === "dismissed") return;
+      } catch {
+        // Storage can be unavailable in private browsing or hardened environments.
+      }
+    }
+
+    showTimerRef.current = window.setTimeout(() => {
+      setVisible(true);
+      showTimerRef.current = null;
+
+      if (dismissAfter !== null) {
+        dismissTimerRef.current = window.setTimeout(() => {
+          setVisible(false);
+          dismissTimerRef.current = null;
+        }, dismissAfter);
+      }
+    }, showDelay);
+
+    return clearTimers;
+  }, [clearTimers, dismissAfter, opened, rememberDismissal, showDelay, storageKey]);
+
+  const handleDismiss = () => {
+    clearTimers();
+    setVisible(false);
+
+    if (rememberDismissal) {
+      try {
+        window.localStorage.setItem(getDismissalStorageKey(storageKey), "dismissed");
+      } catch {
+        // The tip still closes for this render even when persistence is unavailable.
+      }
+    }
+
+    onDismiss?.();
+  };
+
+  const getStyles = useStyles<FloatingTipFactory>({
+    name: "FloatingTip",
+    classes,
+    props,
+    className,
+    style,
+    classNames,
+    styles,
+    unstyled,
+    vars,
+    attributes,
+    varsResolver,
+  });
+
+  return (
+    <Portal>
+      <Transition mounted={visible} transition={transition} duration={transitionDuration} timingFunction="ease">
+        {(transitionStyle) => {
+          const rootStyles = getStyles("root");
+
+          return (
+            <Box ref={ref} {...others} {...rootStyles} style={[rootStyles.style, transitionStyle]}>
+              <Alert
+                {...alertProps}
+                {...getStyles("alert")}
+                withCloseButton={closable}
+                closeButtonLabel={closeButtonLabel}
+                onClose={handleDismiss}
+              >
+                {children}
+              </Alert>
+            </Box>
+          );
+        }}
+      </Transition>
+    </Portal>
+  );
+});
+
+FloatingTip.displayName = "@homarr/ui/FloatingTip";
+FloatingTip.classes = classes;

packages/ui/src/components/floating-tip/index.ts

@@ -0,0 +1,7 @@
+export { FloatingTip } from "./floating-tip";
+export type {
+  FloatingTipCssVariables,
+  FloatingTipFactory,
+  FloatingTipProps,
+  FloatingTipStylesNames,
+} from "./floating-tip";

packages/ui/src/components/index.tsx

@@ -13,6 +13,14 @@ export { CustomPasswordInput } from "./password-input/password-input";
 export { IntegrationAvatar } from "./integration-avatar";
 export { BetaBadge } from "./beta-badge";
 export { CatalogItem } from "./catalog-item";
+export { SelectableCard } from "./selectable-card";
+export type {
+  SelectableCardProps,
+  SelectableCardStylesNames,
+  SelectableCardCssVariables,
+  SelectableCardFactory,
+} from "./selectable-card";
+export * from "./floating-tip";
 export { MaskedImage } from "./masked-image";
 export { MaskedOrNormalImage } from "./masked-or-normal-image";
 export { LanguageIcon } from "./language-icon";

packages/ui/src/components/password-input/password-requirements-popover.tsx

@@ -2,7 +2,7 @@ import type { PropsWithChildren } from "react";
 import { useState } from "react";
 import { Popover, Progress, Text } from "@mantine/core";
 
-import { useScopedI18n } from "@homarr/translation/client";
+import { useI18n } from "@homarr/translation/client";
 import { passwordRequirements } from "@homarr/validation/user";
 
 import { PasswordRequirement } from "./password-requirement";
@@ -14,7 +14,7 @@ const strengthColorMap = [
 ] as const;
 
 export const PasswordRequirementsPopover = ({ password, children }: PropsWithChildren<{ password: string }>) => {
-  const tPassword = useScopedI18n("user.field.password");
+  const tPassword = useI18n("user.field.password");
   const requirements = useRequirements();
   const strength = useStrength(password);
   const [popoverOpened, setPopoverOpened] = useState(false);
@@ -46,7 +46,7 @@ export const PasswordRequirementsPopover = ({ password, children }: PropsWithChi
 };
 
 const useRequirements = () => {
-  const t = useScopedI18n("user.field.password.suggestion");
+  const t = useI18n("user.field.password.suggestion");
 
   return passwordRequirements.map(({ check, value }) => ({ check, label: t(value) }));
 };

packages/ui/src/components/selectable-card/index.ts

@@ -0,0 +1,7 @@
+export { SelectableCard } from "./selectable-card";
+export type {
+  SelectableCardProps,
+  SelectableCardStylesNames,
+  SelectableCardCssVariables,
+  SelectableCardFactory,
+} from "./selectable-card";

packages/ui/src/components/selectable-card/selectable-card.module.css

@@ -0,0 +1,79 @@
+.root {
+  cursor: pointer;
+  text-align: start;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  width: 100%;
+  min-height: 175px;
+  height: 100%;
+  padding: var(--mantine-spacing-sm);
+  border-radius: var(--selectable-card-radius, var(--mantine-radius-md));
+  background-color: light-dark(var(--mantine-color-white), var(--mantine-color-dark-7));
+  border: 1px solid var(--mantine-color-default-border);
+  box-shadow: var(--mantine-shadow-xs);
+  transition:
+    transform 150ms ease,
+    box-shadow 150ms ease,
+    border-color 150ms ease;
+  overflow: hidden;
+  font-family: inherit;
+  color: inherit;
+  text-decoration: none;
+}
+
+.root:hover:not(:disabled) {
+  transform: translateY(-2px);
+  box-shadow: var(--mantine-shadow-sm);
+  border-color: var(--mantine-primary-color-filled);
+}
+
+.root:focus-visible {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
+}
+
+.root[data-selected] {
+  border-color: var(--mantine-primary-color-filled);
+  box-shadow: 0 0 0 1px var(--mantine-primary-color-filled);
+}
+
+.root:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.header {
+  border-bottom: 1px solid var(--mantine-color-default-border);
+  background-color: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-8));
+  padding-top: var(--mantine-spacing-xs);
+  padding-bottom: var(--mantine-spacing-xs);
+  margin: calc(var(--mantine-spacing-sm) * -1);
+  margin-bottom: 0;
+  padding-left: var(--mantine-spacing-sm);
+  padding-right: var(--mantine-spacing-sm);
+}
+
+.body {
+  flex: 1 1 auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--mantine-spacing-xs);
+  margin-top: var(--mantine-spacing-xs);
+  margin-bottom: var(--mantine-spacing-xs);
+  min-height: 0;
+}
+
+.footer {
+  border-top: 1px dashed var(--mantine-color-default-border);
+  background-color: light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-8));
+  padding-top: var(--mantine-spacing-xs);
+  padding-bottom: var(--mantine-spacing-xs);
+  margin: calc(var(--mantine-spacing-sm) * -1);
+  margin-top: auto;
+  padding-left: var(--mantine-spacing-sm);
+  padding-right: var(--mantine-spacing-sm);
+  min-height: 40px;
+  display: flex;
+  align-items: center;
+}

packages/ui/src/components/selectable-card/selectable-card.module.d.css.ts

@@ -0,0 +1,7 @@
+declare const classes: {
+  readonly root: string;
+  readonly header: string;
+  readonly body: string;
+  readonly footer: string;
+};
+export default classes;

packages/ui/src/components/selectable-card/selectable-card.spec.tsx

@@ -0,0 +1,370 @@
+// @vitest-environment jsdom
+
+import { act, createRef } from "react";
+import { createRoot } from "react-dom/client";
+import type { Root } from "react-dom/client";
+import { Badge, MantineProvider } from "@mantine/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { SelectableCard } from "./selectable-card";
+import classes from "./selectable-card.module.css";
+
+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(),
+  }));
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+
+afterEach(async () => {
+  await act(async () => root.unmount());
+  host.remove();
+});
+
+describe("SelectableCard", () => {
+  describe("rendering slots", () => {
+    it("renders as a native button with default button type and accessible slots", async () => {
+      const onClick = vi.fn();
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              aria-label="Sonarr Card"
+              icon={<span data-testid="card-icon">Icon</span>}
+              title="Sonarr"
+              topRight={<Badge data-testid="card-topright">Media</Badge>}
+              description="Manage TV series downloads"
+              footerLeft={<span data-testid="card-footer-left">Left Meta</span>}
+              footerRight={<span data-testid="card-footer-right">Right Meta</span>}
+              onClick={onClick}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button).not.toBeNull();
+      expect(button?.type).toBe("button");
+      expect(button?.getAttribute("aria-label")).toBe("Sonarr Card");
+      expect(host.querySelector("[data-testid='card-icon']")).not.toBeNull();
+      expect(host.textContent).toContain("Sonarr");
+      expect(host.querySelector("[data-testid='card-topright']")).not.toBeNull();
+      expect(host.textContent).toContain("Manage TV series downloads");
+      expect(host.querySelector("[data-testid='card-footer-left']")).not.toBeNull();
+      expect(host.querySelector("[data-testid='card-footer-right']")).not.toBeNull();
+
+      await act(async () => button?.click());
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+
+    it("renders only header when only header slots (icon, title, topRight) are provided", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              icon={<span data-testid="only-icon">I</span>}
+              title="Only Header"
+              topRight={<span data-testid="only-topright">TR</span>}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.querySelector(`.${classes.header}`)).not.toBeNull();
+      expect(button?.querySelector(`.${classes.body}`)).toBeNull();
+      expect(button?.querySelector(`.${classes.footer}`)).toBeNull();
+      expect(host.querySelector("[data-testid='only-icon']")).not.toBeNull();
+      expect(host.querySelector("[data-testid='only-topright']")).not.toBeNull();
+    });
+
+    it("renders footer when only footerLeft or only footerRight is provided", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Test" footerLeft={<span data-testid="left-only">Left</span>} />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(host.querySelector(`.${classes.footer}`)).not.toBeNull();
+      expect(host.querySelector("[data-testid='left-only']")).not.toBeNull();
+
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Test" footerRight={<span data-testid="right-only">Right</span>} />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(host.querySelector(`.${classes.footer}`)).not.toBeNull();
+      expect(host.querySelector("[data-testid='right-only']")).not.toBeNull();
+    });
+
+    it("applies Styles API classes for root, header, body, and footer", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              title="Plex"
+              description="Media Server"
+              footerLeft={<span>Footer</span>}
+              classNames={{
+                root: "custom-root",
+                header: "custom-header",
+                body: "custom-body",
+                footer: "custom-footer",
+              }}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.classList.contains(classes.root)).toBe(true);
+      expect(button?.classList.contains("custom-root")).toBe(true);
+
+      const header = button?.querySelector(`.${classes.header}`);
+      expect(header).not.toBeNull();
+      expect(header?.classList.contains("custom-header")).toBe(true);
+
+      const body = button?.querySelector(`.${classes.body}`);
+      expect(body).not.toBeNull();
+      expect(body?.classList.contains("custom-body")).toBe(true);
+
+      const footer = button?.querySelector(`.${classes.footer}`);
+      expect(footer).not.toBeNull();
+      expect(footer?.classList.contains("custom-footer")).toBe(true);
+    });
+
+    it("prioritizes title without wrapping and constrains topRight badge with ellipsis", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              title="Very Long Title Name That Should Not Wrap"
+              topRight={<Badge>Category Badge</Badge>}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      const header = button?.querySelector(`.${classes.header}`);
+      expect(header).not.toBeNull();
+
+      const titleText = header?.querySelector("p, span, div");
+      expect(titleText?.textContent).toContain("Very Long Title Name That Should Not Wrap");
+
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              title={<span data-testid="custom-title-node">Custom Title Element</span>}
+              topRight={<span data-testid="custom-top-right">Top Right</span>}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(host.querySelector("[data-testid='custom-title-node']")).not.toBeNull();
+      expect(host.querySelector("[data-testid='custom-top-right']")).not.toBeNull();
+    });
+
+    it("renders custom children in the body slot over description", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Test" description="This should not appear">
+              <div data-testid="custom-body-children">Custom Child Content</div>
+            </SelectableCard>
+          </MantineProvider>,
+        ),
+      );
+
+      expect(host.querySelector("[data-testid='custom-body-children']")).not.toBeNull();
+      expect(host.textContent).toContain("Custom Child Content");
+      expect(host.textContent).not.toContain("This should not appear");
+    });
+
+    it("renders an empty description without fallback copy", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="No Desc Item" description="" />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(host.textContent).toContain("No Desc Item");
+      expect(host.textContent).not.toContain("No description provided");
+    });
+
+    it("omits header, body, or footer when corresponding props are omitted", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.querySelector(`.${classes.header}`)).toBeNull();
+      expect(button?.querySelector(`.${classes.body}`)).toBeNull();
+      expect(button?.querySelector(`.${classes.footer}`)).toBeNull();
+    });
+  });
+
+  describe("states", () => {
+    it("handles selected state via data-selected attribute", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Selected Item" selected />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.getAttribute("data-selected")).toBe("true");
+
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Unselected Item" selected={false} />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(button?.hasAttribute("data-selected")).toBe(false);
+    });
+
+    it("handles disabled state and prevents click handlers", async () => {
+      const onClick = vi.fn();
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Disabled Item" disabled onClick={onClick} />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.disabled).toBe(true);
+
+      await act(async () => button?.click());
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it("handles loading state by disabling the button and showing LoadingOverlay", async () => {
+      const onClick = vi.fn();
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Loading Item" loading onClick={onClick} />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.disabled).toBe(true);
+
+      await act(async () => button?.click());
+      expect(onClick).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("interactions and accessibility", () => {
+    it("supports focus and click activation", async () => {
+      const onClick = vi.fn();
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Interactive Card" onClick={onClick} />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      button?.focus();
+      expect(document.activeElement).toBe(button);
+
+      await act(async () => {
+        button?.click();
+      });
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+
+    it("forwards ref to the underlying HTMLButtonElement", async () => {
+      const ref = createRef<HTMLButtonElement>();
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard ref={ref} title="Ref Card" />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+      expect(ref.current?.tagName).toBe("BUTTON");
+    });
+
+    it("resolves radius CSS variables via varsResolver", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Radius Card" radius="lg" />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.style.getPropertyValue("--selectable-card-radius")).toBe("var(--mantine-radius-lg)");
+
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard title="Radius Card Sm" radius="sm" />
+          </MantineProvider>,
+        ),
+      );
+
+      expect(button?.style.getPropertyValue("--selectable-card-radius")).toBe("var(--mantine-radius-sm)");
+    });
+
+    it("passes arbitrary HTML attributes down to the button element", async () => {
+      await act(async () =>
+        root.render(
+          <MantineProvider>
+            <SelectableCard
+              title="Custom Props Card"
+              data-testid="my-selectable-card"
+              data-custom="custom-value"
+              tabIndex={0}
+            />
+          </MantineProvider>,
+        ),
+      );
+
+      const button = host.querySelector("button");
+      expect(button?.getAttribute("data-testid")).toBe("my-selectable-card");
+      expect(button?.getAttribute("data-custom")).toBe("custom-value");
+      expect(button?.tabIndex).toBe(0);
+    });
+  });
+});

packages/ui/src/components/selectable-card/selectable-card.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+  Box,
+  createVarsResolver,
+  factory,
+  Group,
+  LoadingOverlay,
+  Text,
+  Tooltip,
+  useProps,
+  useStyles,
+} from "@mantine/core";
+import type { BoxProps, ElementProps, Factory, MantineRadius, StylesApiProps } from "@mantine/core";
+
+import classes from "./selectable-card.module.css";
+
+export type SelectableCardStylesNames = "root" | "header" | "body" | "footer";
+export type SelectableCardCssVariables = {
+  root: "--selectable-card-radius";
+};
+
+export interface SelectableCardProps
+  extends BoxProps, StylesApiProps<SelectableCardFactory>, Omit<ElementProps<"button">, "title"> {
+  icon?: ReactNode;
+  title?: ReactNode;
+  topRight?: ReactNode;
+  description?: string | null;
+  footerLeft?: ReactNode;
+  footerRight?: ReactNode;
+  selected?: boolean;
+  loading?: boolean;
+  disabled?: boolean;
+  radius?: MantineRadius;
+  children?: ReactNode;
+}
+
+export type SelectableCardFactory = Factory<{
+  props: SelectableCardProps;
+  ref: HTMLButtonElement;
+  stylesNames: SelectableCardStylesNames;
+  vars: SelectableCardCssVariables;
+}>;
+
+const defaultProps: Partial<SelectableCardProps> = {
+  type: "button",
+};
+
+const varsResolver = createVarsResolver<SelectableCardFactory>((_theme, { radius }) => ({
+  root: {
+    "--selectable-card-radius": radius ? `var(--mantine-radius-${radius})` : undefined,
+  },
+}));
+
+export const SelectableCard = factory<SelectableCardFactory>((_props) => {
+  const props = useProps("SelectableCard", defaultProps, _props);
+  const {
+    ref,
+    classNames,
+    className,
+    style,
+    styles,
+    unstyled,
+    vars,
+    attributes,
+    icon,
+    title,
+    topRight,
+    description,
+    footerLeft,
+    footerRight,
+    selected,
+    loading = false,
+    disabled = false,
+    children,
+    type = "button",
+    ...others
+  } = props;
+
+  const getStyles = useStyles<SelectableCardFactory>({
+    name: "SelectableCard",
+    classes,
+    props,
+    className,
+    style,
+    classNames,
+    styles,
+    unstyled,
+    vars,
+    attributes,
+    varsResolver,
+  });
+
+  return (
+    <Box
+      component="button"
+      {...others}
+      type={type}
+      ref={ref}
+      disabled={disabled || loading}
+      data-selected={selected || undefined}
+      aria-pressed={selected !== undefined ? selected : undefined}
+      {...getStyles("root")}
+    >
+      <LoadingOverlay visible={loading} loaderProps={{ size: "sm" }} />
+
+      {/* Header Section: Inset background with Title that never elides before the category */}
+      {(icon || title || topRight) && (
+        <Box {...getStyles("header")}>
+          <Group
+            justify="space-between"
+            align="center"
+            wrap="nowrap"
+            gap="xs"
+            style={{ width: "100%", overflow: "hidden" }}
+          >
+            <Group gap="xs" wrap="nowrap" style={{ flex: "1 1 auto", minWidth: 0, overflow: "hidden" }}>
+              {icon}
+              {typeof title === "string" ? (
+                <Text
+                  fw={700}
+                  size="md"
+                  style={{
+                    overflow: "hidden",
+                    textOverflow: "ellipsis",
+                    whiteSpace: "nowrap",
+                  }}
+                >
+                  {title}
+                </Text>
+              ) : (
+                title
+              )}
+            </Group>
+            {topRight && (
+              <Box
+                style={{
+                  minWidth: 0,
+                  flexShrink: 0,
+                }}
+              >
+                {topRight}
+              </Box>
+            )}
+          </Group>
+        </Box>
+      )}
+
+      {/* Body: Custom Children or Default Description */}
+      {children ? (
+        <Box {...getStyles("body")}>{children}</Box>
+      ) : description !== undefined ? (
+        <Box {...getStyles("body")}>
+          <Tooltip label={description} multiline w={260} disabled={!description}>
+            <Text size="sm" c="dimmed" lineClamp={2} lh={1.35}>
+              {description}
+            </Text>
+          </Tooltip>
+        </Box>
+      ) : null}
+
+      {/* Footer Section: Inset Dashed Bottom Meta */}
+      {(footerLeft || footerRight) && (
+        <Box {...getStyles("footer")}>
+          <Group justify="space-between" align="center" wrap="nowrap" gap="xs" style={{ width: "100%" }}>
+            <Box style={{ minWidth: 0, flexShrink: 1 }}>{footerLeft}</Box>
+            <Box style={{ minWidth: 0, flexShrink: 0 }}>{footerRight}</Box>
+          </Group>
+        </Box>
+      )}
+    </Box>
+  );
+});
+
+SelectableCard.displayName = "@homarr/ui/SelectableCard";
+SelectableCard.classes = classes;

packages/ui/src/integration-select-grid/integration-multi-select-grid.tsx

@@ -4,6 +4,7 @@ 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";
 
@@ -109,7 +110,7 @@ export const IntegrationMultiSelectGrid = ({
                         <Stack gap={4}>
                           {integration.widgets.map((widgetKind) => (
                             <Text key={widgetKind} size="xs">
-                              {t(`widget.${widgetKind}.name`)}
+                              {getWidgetName(widgetKind, t)}
                             </Text>
                           ))}
                         </Stack>

packages/ui/src/integration-select-grid/integration-select-grid.spec.tsx

@@ -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();
+  });
+});

packages/ui/src/integration-select-grid/integration-select-grid.tsx

@@ -1,27 +1,69 @@
 "use client";
 
 import { useMemo, useState } from "react";
-import { Badge, Card, Center, Group, Stack, Text, Tooltip, UnstyledButton } from "@mantine/core";
-import { IconPuzzle } from "@tabler/icons-react";
+import { Badge, Center, Group, Input, ScrollArea, SimpleGrid, Stack, Text } from "@mantine/core";
+import {
+  IconAd,
+  IconApps,
+  IconBinaryTree,
+  IconBookmark,
+  IconBrandDocker,
+  IconBrandMinecraft,
+  IconBrowser,
+  IconBuildingBank,
+  IconBusStop,
+  IconCalendar,
+  IconChartBar,
+  IconClock,
+  IconClockPlay,
+  IconCloud,
+  IconDeviceCctv,
+  IconDeviceGamepad,
+  IconDownload,
+  IconGraphFilled,
+  IconHeartRateMonitor,
+  IconHourglass,
+  IconMessage,
+  IconMovie,
+  IconNotes,
+  IconPuzzle,
+  IconReportSearch,
+  IconRobot,
+  IconRocket,
+  IconRss,
+  IconSearch,
+  IconServer2,
+  IconTicket,
+  IconTopologyFull,
+  IconTransform,
+  IconVideo,
+  IconWall,
+  IconWind,
+  IconZoomQuestion,
+} from "@tabler/icons-react";
 
-import type { IntegrationKind } from "@homarr/definitions";
+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 { SelectGridLayout, selectGridCardHeight } from "../select-grid-layout";
+import { SelectableCard } from "../components/selectable-card";
+import { selectGridCols } from "../select-grid-layout";
 import { buildSortedIntegrations, categoryTranslationKeys, filterIntegrations } from "./integration-grid-shared";
-import classes from "./integration-select-grid.module.css";
+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();
@@ -32,75 +74,182 @@ export const IntegrationSelectGrid = ({
   const filtered = useMemo(() => filterIntegrations(integrations, search), [integrations, search]);
 
   return (
-    <SelectGridLayout
-      search={search}
-      onSearchChange={setSearch}
-      placeholder={`${t("integration.page.list.search")}...`}
-      ariaLabel={t("integration.page.list.search")}
-    >
-      {filtered.map((integration) => (
-        <UnstyledButton
-          className={classes.choice}
-          key={integration.kind}
-          onClick={() => onSelect(integration.kind)}
-          aria-label={integration.name}
-        >
-          <Card h={selectGridCardHeight} className={classes.card} 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}>
-                  {integration.name}
-                </Text>
-              </Group>
-              <IntegrationGridMeta integration={integration} />
-            </Stack>
-          </Card>
-        </UnstyledButton>
-      ))}
-      {filtered.length === 0 && (
-        <Center p="xl" style={{ gridColumn: "1 / -1" }}>
-          <Text c="dimmed">{t("common.noResults")}</Text>
-        </Center>
-      )}
-    </SelectGridLayout>
-  );
-};
-
-const IntegrationGridMeta = ({ integration }: { integration: ReturnType<typeof buildSortedIntegrations>[number] }) => {
-  const t = useI18n();
-  return (
-    <Stack gap={4} mt="auto">
-      <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">
-                  {t(`widget.${widgetKind}.name`)}
-                </Text>
-              ))}
-            </Stack>
+    <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);
           }
-        >
-          <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>
-      )}
+        }}
+      />
+
+      {/* 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={integration.name}
+      topRight={<IntegrationCategoryBadges categories={integration.categories} limit={1} />}
+      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 widgetIconsMap: Partial<Record<WidgetKind, typeof IconPuzzle>> = {
+  clock: IconClock,
+  weather: IconCloud,
+  airQuality: IconWind,
+  countdown: IconHourglass,
+  timer: IconClockPlay,
+  app: IconApps,
+  assistant: IconRobot,
+  iframe: IconBrowser,
+  video: IconDeviceCctv,
+  notebook: IconNotes,
+  anchorNote: IconNotes,
+  dnsHoleSummary: IconAd,
+  dnsHoleControls: IconDeviceGamepad,
+  "smartHome-entityState": IconBinaryTree,
+  "smartHome-executeAutomation": IconBinaryTree,
+  stockPrice: IconBuildingBank,
+  mediaServer: IconVideo,
+  calendar: IconCalendar,
+  downloads: IconDownload,
+  "mediaRequests-requestList": IconZoomQuestion,
+  "mediaRequests-requestStats": IconChartBar,
+  mediaTranscoding: IconTransform,
+  mediaMissing: IconMovie,
+  minecraftServerStatus: IconBrandMinecraft,
+  networkControllerSummary: IconTopologyFull,
+  networkControllerStatus: IconTopologyFull,
+  rssFeed: IconRss,
+  bookmarks: IconBookmark,
+  indexerManager: IconReportSearch,
+  healthMonitoring: IconHeartRateMonitor,
+  releases: IconRocket,
+  mediaReleases: IconTicket,
+  dockerContainers: IconBrandDocker,
+  firewall: IconWall,
+  notifications: IconMessage,
+  systemResources: IconGraphFilled,
+  coolify: IconCloud,
+  systemDisks: IconServer2,
+  timetable: IconBusStop,
+};
+
+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 = widgetIconsMap[widgetKind] ?? IconPuzzle;
+        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>
+  );
+};
+
+const IntegrationCategoryBadges = ({
+  categories,
+  limit,
+}: {
+  categories: IntegrationGridItem["categories"];
+  limit?: number;
+}) => {
+  const t = useI18n();
+  const items = limit ? categories.slice(0, limit) : categories;
+
+  return (
+    <Group gap={4} wrap="wrap">
+      {items.map((category) => (
+        <Badge key={category} variant="light" size="xs" color="gray" radius="xs">
+          {categoryTranslationKeys[category] ? t(categoryTranslationKeys[category] as never) : category}
+        </Badge>
+      ))}
+    </Group>
+  );
+};