refactor(board): modernize item and application select modals with SelectableCard (#6642)

Modernize board item, application, and integration selection flows with shared Mantine components, batch board actions, improved accessibility, and hardened persistence.
This commit is contained in:
Thomas authored and GitHub committed 2026-08-21 03:19:18 +02:00
1 parent bd4f6a92c6
commit f3014fe271
60 files changed
+3791 -1839

No files matched your search

@@ -0,0 +1,438 @@
// @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 { AppSelectModal } from "./app-select-modal";
const AppSelectModalComponent = AppSelectModal.component;
const sampleApps = [
{
id: "app-1",
name: "Sonarr",
description: "Manage TV series downloads",
iconUrl: "https://example.com/sonarr.png",
href: "http://sonarr.local",
},
{
id: "app-2",
name: "Radarr",
description: "Manage movie collections",
iconUrl: "https://example.com/radarr.png",
href: "http://radarr.local",
},
{
id: "app-3",
name: "Plex",
description: "Stream your media collection",
iconUrl: "https://example.com/plex.png",
href: "http://plex.local",
},
];
const mockUseQuery = vi.fn(() => ({
data: sampleApps,
isPending: false,
}));
const mockOpenQuickAddAppModal = vi.fn();
vi.mock("@homarr/api/client", () => ({
clientApi: {
app: {
selectable: {
useQuery: () => mockUseQuery(),
},
},
},
}));
vi.mock("@homarr/modals", async () => {
const actual = await vi.importActual<Record<string, unknown>>("@homarr/modals");
return {
...actual,
useModalAction: () => ({
openModal: mockOpenQuickAddAppModal,
}),
};
});
vi.mock("@homarr/translation/client", () => ({
useI18n: () => (key: string, values?: { count?: number }) => {
const count = values?.count ?? 0;
const translations: Record<string, string> = {
"app.action.select.search": "Search apps",
"app.action.select.title": "Select application",
"app.action.select.selected": "Selected",
"app.action.select.toggle": "Click to select",
"app.action.select.noResults": "No apps found",
"app.action.select.multiSelectTip": "Hold Ctrl or Command to select multiple apps",
"app.action.select.selectedCount": `${count} selected`,
"app.action.select.appsSelected": `${count} ${count === 1 ? "app" : "apps"} selected`,
"app.action.select.customApplication": "Custom application",
"app.action.select.application": "Application",
"app.action.create.title": "Add custom app",
"app.action.create.description": "Configure custom URL and icon",
"common.action.discard": "Discard",
"common.action.add": "Add",
};
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);
vi.clearAllMocks();
mockUseQuery.mockReturnValue({
data: sampleApps,
isPending: false,
});
});
afterEach(async () => {
await act(async () => root.unmount());
host.remove();
});
describe("AppSelectModal", () => {
describe("single selection mode", () => {
it("renders app cards with name, description, and icon", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
expect(host.textContent).toContain("Sonarr");
expect(host.textContent).toContain("Radarr");
expect(host.textContent).toContain("Plex");
expect(host.textContent).toContain("Manage TV series downloads");
});
it("selects an app and closes modal when card is clicked", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
const sonarrCard = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Sonarr"));
expect(sonarrCard).toBeDefined();
await act(async () => {
sonarrCard?.click();
});
expect(onSelect).toHaveBeenCalledWith(sampleApps[0]);
expect(closeModal).toHaveBeenCalledOnce();
});
});
describe("multi selection mode", () => {
it("toggles multiple app selections and submits batch on button click", async () => {
const closeModal = vi.fn();
const onSelectMany = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelectMany, withCreate: false }} />
</MantineProvider>,
),
);
const sonarrCard = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Sonarr"));
const radarrCard = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Radarr"));
// Select Sonarr
await act(async () => {
sonarrCard?.click();
});
// Modal stays open, 1 app selected
expect(closeModal).not.toHaveBeenCalled();
expect(host.textContent).toContain("1 app selected");
// Select Radarr
await act(async () => {
radarrCard?.click();
});
expect(host.textContent).toContain("2 apps selected");
// Submit multi select
const submitBtn = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Add (2)"));
expect(submitBtn).toBeDefined();
await act(async () => {
submitBtn?.click();
});
expect(onSelectMany).toHaveBeenCalledWith([sampleApps[0], sampleApps[1]]);
expect(closeModal).toHaveBeenCalledOnce();
});
it("unselects an app when clicked a second time", async () => {
const closeModal = vi.fn();
const onSelectMany = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelectMany, withCreate: false }} />
</MantineProvider>,
),
);
const sonarrCard = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Sonarr"));
// Select Sonarr
await act(async () => {
sonarrCard?.click();
});
expect(host.textContent).toContain("1 app selected");
// Unselect Sonarr
await act(async () => {
sonarrCard?.click();
});
expect(host.textContent).not.toContain("1 app selected");
});
it("clears selection when Discard button is clicked", async () => {
const closeModal = vi.fn();
const onSelectMany = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelectMany, withCreate: false }} />
</MantineProvider>,
),
);
const sonarrCard = Array.from(host.querySelectorAll("button")).find((btn) => btn.textContent?.includes("Sonarr"));
await act(async () => {
sonarrCard?.click();
});
expect(host.textContent).toContain("1 app selected");
const discardBtn = Array.from(host.querySelectorAll("button")).find((btn) =>
btn.textContent?.includes("Discard"),
);
await act(async () => {
discardBtn?.click();
});
expect(host.textContent).not.toContain("app selected");
});
});
describe("search and filtering", () => {
it("filters apps in real-time by search query (case-insensitive)", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
const searchInput = host.querySelector("input");
expect(searchInput).not.toBeNull();
// Type "plex"
await act(async () => {
if (searchInput) {
const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
window.HTMLInputElement.prototype,
"value",
)?.set;
nativeInputValueSetter?.call(searchInput, "plex");
searchInput.dispatchEvent(new Event("input", { bubbles: true }));
searchInput.dispatchEvent(new Event("change", { bubbles: true }));
}
});
expect(host.textContent).toContain("Plex");
expect(host.textContent).not.toContain("Sonarr");
expect(host.textContent).not.toContain("Radarr");
});
it("selects the single matching app when Enter key is pressed in search input", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
const searchInput = host.querySelector("input");
await act(async () => {
if (searchInput) {
const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
window.HTMLInputElement.prototype,
"value",
)?.set;
nativeInputValueSetter?.call(searchInput, "sonarr");
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(sampleApps[0]);
expect(closeModal).toHaveBeenCalledOnce();
});
it("displays empty state message when search yields no results", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
const searchInput = host.querySelector("input");
await act(async () => {
if (searchInput) {
const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
window.HTMLInputElement.prototype,
"value",
)?.set;
nativeInputValueSetter?.call(searchInput, "non-matching-query");
searchInput.dispatchEvent(new Event("input", { bubbles: true }));
searchInput.dispatchEvent(new Event("change", { bubbles: true }));
}
});
expect(host.textContent).toContain("No apps found");
});
});
describe("custom app creation card", () => {
it("renders custom app creation card when withCreate is true", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: true }} />
</MantineProvider>,
),
);
expect(host.textContent).toContain("Add custom app");
expect(host.textContent).toContain("Configure custom URL and icon");
});
it("omits custom app creation card when withCreate is false", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: false }} />
</MantineProvider>,
),
);
expect(host.textContent).not.toContain("Add custom app");
});
it("opens QuickAddAppModal when custom app creation card is clicked in single select mode", async () => {
const closeModal = vi.fn();
const onSelect = vi.fn();
await act(async () =>
root.render(
<MantineProvider>
<AppSelectModalComponent actions={{ closeModal }} innerProps={{ onSelect, withCreate: true }} />
</MantineProvider>,
),
);
const createCard = Array.from(host.querySelectorAll("button")).find((btn) =>
btn.textContent?.includes("Add custom app"),
);
expect(createCard).toBeDefined();
await act(async () => {
createCard?.click();
});
expect(mockOpenQuickAddAppModal).toHaveBeenCalledOnce();
// Trigger the onClose callback passed to QuickAddAppModal
const options = mockOpenQuickAddAppModal.mock.calls[0]?.[0] as { onClose: (app: (typeof sampleApps)[0]) => void };
const newCustomApp = {
id: "custom-app-1",
name: "Custom Home Assistant",
description: "Local instance",
iconUrl: "https://example.com/ha.png",
href: "http://ha.local",
};
await act(async () => {
options.onClose(newCustomApp);
});
expect(onSelect).toHaveBeenCalledWith(newCustomApp);
expect(closeModal).toHaveBeenCalledOnce();
});
});
});
@@ -1,12 +1,25 @@
import { useMemo, useState } from "react";
import { Button, Center, Group, Stack, Text, Tooltip } from "@mantine/core";
import { IconCheck, IconPlus, IconApps } from "@tabler/icons-react";
import {
Badge,
Button,
Center,
Group,
Image,
Input,
Paper,
ScrollArea,
SimpleGrid,
Stack,
Text,
ThemeIcon,
} from "@mantine/core";
import { IconPlus, IconSearch } from "@tabler/icons-react";
import type { RouterOutputs } from "@homarr/api";
import { clientApi } from "@homarr/api/client";
import { createModal, modalSizeSelect, useModalAction } from "@homarr/modals";
import { useI18n } from "@homarr/translation/client";
import { CatalogItem, SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
import { selectGridCols, SelectableCard } from "@homarr/ui";
import { QuickAddAppModal } from "./quick-add-app/quick-add-app-modal";
@@ -36,7 +49,15 @@ export const AppSelectModal = createModal<AppSelectModalProps>(({ actions, inner
const selectedApps = useMemo(() => apps.filter((app) => selectedAppIds.has(app.id)), [apps, selectedAppIds]);
const handleSelect = (app: SelectableApp) => {
const handleSelect = (app: SelectableApp, event?: React.MouseEvent) => {
const isModifierPressed = multiSelect && Boolean(event?.shiftKey || event?.ctrlKey || event?.metaKey);
if (innerProps.onSelect && !isModifierPressed && selectedAppIds.size === 0) {
innerProps.onSelect(app);
actions.closeModal();
return;
}
if (multiSelect) {
setSelectedAppIds((current) => {
const next = new Set(current);
@@ -44,22 +65,6 @@ export const AppSelectModal = createModal<AppSelectModalProps>(({ actions, inner
else next.add(app.id);
return next;
});
return;
}
innerProps.onSelect?.(app);
actions.closeModal();
};
const handleSubmit = () => {
if (multiSelect) {
innerProps.onSelectMany?.(selectedApps);
actions.closeModal();
return;
}
const [first] = filteredApps;
if (first) {
innerProps.onSelect?.(first);
actions.closeModal();
}
};
@@ -76,100 +81,145 @@ export const AppSelectModal = createModal<AppSelectModalProps>(({ actions, inner
});
};
const handleMultiSubmit = () => {
innerProps.onSelectMany?.(selectedApps);
actions.closeModal();
};
return (
<>
<SelectGridLayout
search={search}
onSearchChange={setSearch}
placeholder={`${t("app.action.select.search")}...`}
ariaLabel={t("app.action.select.search")}
onSearchKeyDown={(event) => {
if (event.key === "Enter" && filteredApps.length === 1 && filteredApps[0]) {
handleSelect(filteredApps[0]);
}
}}
>
{innerProps.withCreate && (
<CatalogItem
height={selectGridCardHeight}
label={t("app.action.create.title")}
status={t("app.action.create.action")}
onSelect={handleAddNewApp}
>
<Stack h="100%" gap="xs">
<Group gap="sm" wrap="nowrap" align="flex-start">
<IconPlus size={22} style={{ flexShrink: 0, marginTop: 2 }} />
<Text lh={1.2} style={{ whiteSpace: "normal" }} fw={500} size="sm" lineClamp={2}>
{t("app.action.create.title")}
</Text>
</Group>
<Text lh={1.2} style={{ whiteSpace: "normal" }} size="xs" c="dimmed" lineClamp={1}>
{t("app.action.create.description")}
</Text>
<Text size="xs" c="blue" fw={500} mt="auto">
{t("app.action.create.action")}
</Text>
</Stack>
</CatalogItem>
)}
{filteredApps.map((app) => (
<CatalogItem
key={app.id}
height={selectGridCardHeight}
label={app.name}
status={
multiSelect
? selectedAppIds.has(app.id)
? t("app.action.select.selected")
: t("app.action.select.toggle")
: t("app.action.select.action", { app: app.name })
<Stack gap="md">
{/* Top Search Input & Multi-Select Tip */}
<Stack gap={6}>
<Input
value={search}
onChange={(event) => setSearch(event.currentTarget.value)}
leftSection={<IconSearch size={16} />}
placeholder={`${t("app.action.select.search")}...`}
aria-label={t("app.action.select.search")}
data-autofocus
onKeyDown={(event) => {
if (event.key === "Enter" && filteredApps.length === 1 && filteredApps[0]) {
handleSelect(filteredApps[0]);
}
selected={multiSelect ? selectedAppIds.has(app.id) : undefined}
onSelect={() => handleSelect(app)}
>
<Stack h="100%" gap="xs">
<Group gap="sm" wrap="nowrap" align="flex-start">
<img src={app.iconUrl} alt={app.name} width={22} height={22} style={{ flexShrink: 0, marginTop: 2 }} />
<Text lh={1.2} style={{ whiteSpace: "normal" }} fw={500} size="sm" lineClamp={2}>
{app.name}
</Text>
{multiSelect && selectedAppIds.has(app.id) && (
<IconCheck size={18} color="var(--mantine-primary-color-filled)" />
)}
</Group>
<Tooltip label={app.description} multiline w={250} disabled={!app.description}>
<Text lh={1.2} style={{ whiteSpace: "normal" }} size="xs" c="dimmed" lineClamp={1}>
{app.description ?? ""}
</Text>
</Tooltip>
<Text size="xs" c="blue" fw={500} mt="auto">
{multiSelect
? selectedAppIds.has(app.id)
? t("app.action.select.selected")
: t("app.action.select.toggle")
: t("app.action.select.action", { app: app.name })}
</Text>
</Stack>
</CatalogItem>
))}
{filteredApps.length === 0 && !isPending && (
<Center p="xl">
<Text c="dimmed">{t("app.action.select.noResults")}</Text>
</Center>
}}
/>
{multiSelect && (
<Group justify="space-between" px={2}>
<Text size="xs" c="dimmed">
{t("app.action.select.multiSelectTip")}
</Text>
{selectedAppIds.size > 0 && (
<Badge variant="light" color="primaryColor" size="xs">
{t("app.action.select.selectedCount", { count: selectedAppIds.size })}
</Badge>
)}
</Group>
)}
</SelectGridLayout>
{multiSelect && (
<Group justify="flex-end" mt="md">
<Button leftSection={<IconApps size={16} />} disabled={selectedAppIds.size === 0} onClick={handleSubmit}>
{t("app.action.select.multiple", { count: String(selectedAppIds.size) })}
</Button>
</Group>
</Stack>
{/* Scrollable Container with App Cards */}
<ScrollArea.Autosize mah="70vh" offsetScrollbars>
<Stack gap="md" pt="xs" pr="xs" px={4}>
<SimpleGrid cols={selectGridCols} spacing="sm">
{innerProps.withCreate && (
<SelectableCard
onClick={handleAddNewApp}
style={{ borderStyle: "dashed" }}
icon={
<ThemeIcon variant="light" color="primaryColor" size={34} radius="md">
<IconPlus size={20} />
</ThemeIcon>
}
title={t("app.action.create.title")}
description={t("app.action.create.description")}
footerLeft={
<Text size="xs" c="dimmed">
{t("app.action.select.customApplication")}
</Text>
}
/>
)}
{filteredApps.map((app) => (
<AppCard
key={app.id}
app={app}
isSelected={selectedAppIds.has(app.id)}
multiSelect={multiSelect}
onSelect={handleSelect}
/>
))}
</SimpleGrid>
{filteredApps.length === 0 && !isPending && (
<Center p="xl">
<Text c="dimmed">{t("app.action.select.noResults")}</Text>
</Center>
)}
</Stack>
</ScrollArea.Autosize>
{/* Multi-Select Action Footer */}
{multiSelect && selectedApps.length > 0 && (
<Paper withBorder p="xs" radius="md" bg="light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-8))">
<Group justify="space-between" align="center">
<Text size="sm" fw={600}>
{t("app.action.select.appsSelected", { count: selectedApps.length })}
</Text>
<Group gap="xs">
<Button variant="default" size="xs" onClick={() => setSelectedAppIds(new Set())}>
{t("common.action.discard")}
</Button>
<Button color="primaryColor" size="xs" onClick={handleMultiSubmit}>
{t("common.action.add")} ({selectedApps.length})
</Button>
</Group>
</Group>
</Paper>
)}
</>
</Stack>
);
}).withOptions({
defaultTitle: (t) => t("app.action.select.title"),
size: modalSizeSelect,
});
// =========================================================================
// AppCard: Variant 3 (Dashboard Inset) with Medium Title & Large App Icon
// =========================================================================
const AppCard = ({
app,
isSelected,
multiSelect,
onSelect,
}: {
app: SelectableApp;
isSelected: boolean;
multiSelect: boolean;
onSelect: (app: SelectableApp, event?: React.MouseEvent) => void;
}) => {
const t = useI18n();
return (
<SelectableCard
onClick={(event) => onSelect(app, event)}
aria-label={app.name}
selected={isSelected}
icon={<Image src={app.iconUrl} alt={app.name} w={28} h={28} fit="contain" style={{ flexShrink: 0 }} />}
title={app.name}
topRight={
isSelected ? (
<Badge variant="dot" color="primaryColor" size="xs">
{t("app.action.select.selected")}
</Badge>
) : null
}
description={app.description}
footerLeft={
<Text size="xs" c="dimmed">
{multiSelect && isSelected ? t("app.action.select.selected") : t("app.action.select.application")}
</Text>
}
/>
);
};