feat: rebuild onboarding experience

packages/ui/src/components/search-input.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import type { ChangeEvent } from "react";
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { usePathname, useRouter, useSearchParams } from "next/navigation";
 import { Loader, TextInput } from "@mantine/core";
 import { useDebouncedCallback } from "@mantine/hooks";
@@ -10,25 +10,38 @@ import { IconSearch } from "@tabler/icons-react";
 interface SearchInputProps {
   defaultValue?: string;
   placeholder: string;
+  ariaLabel: string;
   flexExpand?: boolean;
 }
 
-export const SearchInput = ({ placeholder, defaultValue, flexExpand = false }: SearchInputProps) => {
+export const SearchInput = ({ placeholder, ariaLabel, defaultValue, flexExpand = false }: SearchInputProps) => {
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const { replace } = useRouter();
   const pathName = usePathname();
   const searchParams = useSearchParams();
   const [loading, setLoading] = useState(false);
+  const [value, setValue] = useState(defaultValue ?? "");
+  useEffect(() => {
+    setValue(defaultValue ?? "");
+    setLoading(false);
+  }, [defaultValue]);
   const handleSearchDebounced = useDebouncedCallback((value: string) => {
     const params = new URLSearchParams(searchParams);
-    params.set("search", value.toString());
+    const normalizedValue = value.trim();
+    if (normalizedValue.length === 0) {
+      params.delete("search");
+    } else {
+      params.set("search", normalizedValue);
+    }
     if (params.has("page")) params.set("page", "1"); // Reset page to 1
-    replace(`${pathName}?${params.toString()}`);
+    const query = params.toString();
+    replace(query ? `${pathName}?${query}` : pathName);
     setLoading(false);
   }, 250);
 
   const handleSearch = useCallback(
     (event: ChangeEvent<HTMLInputElement>) => {
+      setValue(event.currentTarget.value);
       setLoading(true);
       handleSearchDebounced(event.currentTarget.value);
     },
@@ -38,9 +51,10 @@ export const SearchInput = ({ placeholder, defaultValue, flexExpand = false }: S
   return (
     <TextInput
       leftSection={<LeftSection loading={loading} />}
-      defaultValue={defaultValue}
+      value={value}
       onChange={handleSearch}
       placeholder={placeholder}
+      aria-label={ariaLabel}
       style={{ flex: flexExpand ? "1" : undefined }}
     />
   );

packages/ui/src/integration-select-grid/index.ts

@@ -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";

packages/ui/src/integration-select-grid/integration-grid-shared.spec.ts

@@ -0,0 +1,14 @@
+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.length - 1);
+    expect(kinds).not.toContain("mock");
+  });
+});

packages/ui/src/integration-select-grid/integration-grid-shared.ts

@@ -0,0 +1,77 @@
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import {
+  featuredIntegrations,
+  getIntegrationName,
+  getWidgetKindsForIntegration,
+  hiddenFromOnboarding,
+  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 } = {},
+): IntegrationGridItem[] =>
+  integrationKinds
+    .filter((kind) => {
+      if (options.onboarding && hiddenFromOnboarding.has(kind)) 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 leftIndex = featuredIntegrations.indexOf(left.kind);
+      const rightIndex = featuredIntegrations.indexOf(right.kind);
+      if (leftIndex !== -1 && rightIndex !== -1) return leftIndex - rightIndex;
+      if (leftIndex !== -1) return -1;
+      if (rightIndex !== -1) 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));
+};

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

@@ -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 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")}
+      disableScroll={onboarding}
+      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-color-blue-6)" : 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-color-blue-6)" />}
+                </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">
+                              {t(`widget.${widgetKind}.name`)}
+                            </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>
+  );
+};

packages/ui/src/integration-select-grid/integration-select-grid.module.css

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

packages/ui/src/integration-select-grid/integration-select-grid.module.d.css.ts

@@ -0,0 +1,2 @@
+declare const classes: Record<string, string>;
+export default classes;

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

@@ -0,0 +1,98 @@
+"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 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 IntegrationSelectGridProps {
+  onSelect: (kind: IntegrationKind) => void;
+  enableMockIntegration?: boolean;
+}
+
+export const IntegrationSelectGrid = ({ onSelect, enableMockIntegration = false }: IntegrationSelectGridProps) => {
+  const [search, setSearch] = useState("");
+  const t = useI18n();
+  const integrations = useMemo(() => buildSortedIntegrations({ enableMockIntegration }), [enableMockIntegration]);
+  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>
+          }
+        >
+          <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>
+  );
+};

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

@@ -4,7 +4,7 @@ import type { KeyboardEvent, ReactNode } from "react";
 import { Input, ScrollArea, SimpleGrid, Stack } from "@mantine/core";
 import { IconSearch } from "@tabler/icons-react";
 
-export const selectGridCols = { base: 2, xs: 3, sm: 4, md: 5 };
+export const selectGridCols = { base: 1, xs: 2, sm: 3, md: 4, lg: 5 };
 export const selectGridCardHeight = 140;
 export const selectGridScrollMaxHeight = "70vh";
 
@@ -12,6 +12,7 @@ interface SelectGridLayoutProps {
   search: string;
   onSearchChange: (value: string) => void;
   placeholder: string;
+  ariaLabel: string;
   onSearchKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
   disableScroll?: boolean;
   disableAutoFocus?: boolean;
@@ -22,6 +23,7 @@ export const SelectGridLayout = ({
   search,
   onSearchChange,
   placeholder,
+  ariaLabel,
   onSearchKeyDown,
   disableScroll = false,
   disableAutoFocus = false,
@@ -40,6 +42,7 @@ export const SelectGridLayout = ({
         onChange={(event) => onSearchChange(event.currentTarget.value)}
         leftSection={<IconSearch />}
         placeholder={placeholder}
+        aria-label={ariaLabel}
         data-autofocus={disableAutoFocus ? undefined : true}
         onKeyDown={onSearchKeyDown}
       />