feat: add Uptime Kuma, Audiobookshelf, Paperless-ngx, and Navidrome integrations

Add four new integrations with full widget support:

- Uptime Kuma: dashboard monitors, uptime percentage ring, status counts
- Audiobookshelf: library stats, audiobooks/podcasts counts, listening time
- Paperless-ngx: document stats, inbox ratio ring, correspondents/tags
- Navidrome: artist/album/song counts, now playing with track list

Also adds a unified "Audio Stats" widget that merges Navidrome and
Audiobookshelf into a single configurable widget with backend-specific
option visibility.

Includes Vitest specs for pagination, status mapping, and shared utils.
This commit is contained in:
Thomas Camlong committed 2026-06-09 18:09:22 +02:00
1 parent a447a9f615
commit c9f003dadd
53 files changed
+3370 -17

No files matched your search

@@ -0,0 +1,134 @@
"use client";
import type { CSSProperties } from "react";
import { Badge, Text } from "@mantine/core";
import { IconHeadphones } from "@tabler/icons-react";
import type { AudiobookshelfDashboardData, NavidromeDashboardData } from "@homarr/integrations/types";
import { useScopedI18n } from "@homarr/translation/client";
import classes from "./component.module.css";
import type { AudioStatsBackend, AudioStatsDisplayOptions } from "./shared";
import { getGridCols, getIconSize, getVisibleStats, translationScopeByBackend } from "./shared";
const rootClassByCompact = {
true: classes.rootCompact,
false: "",
} as const;
const gridClassByCompact = {
true: classes.gridCompact,
false: "",
} as const;
const statTileClassByCompact = {
true: classes.statTileCompact,
false: "",
} as const;
interface AudioStatsContentProps {
backend: AudioStatsBackend;
stats: NavidromeDashboardData | AudiobookshelfDashboardData;
options: AudioStatsDisplayOptions;
width: number;
translationScope?: keyof typeof translationScopeByBackend;
}
export function AudioStatsContent({
backend,
stats,
options,
width,
translationScope = "audioStats",
}: AudioStatsContentProps) {
const t = useScopedI18n(translationScopeByBackend[translationScope]);
const visibleStats = getVisibleStats(backend, options, stats);
const compactKey = String(options.compactMode ?? false) as keyof typeof rootClassByCompact;
const gridCols = getGridCols(width, visibleStats.length, options.compactMode ?? false);
const iconSize = getIconSize(width, options.compactMode ?? false);
const navidromeStatsByBackend: Record<AudioStatsBackend, NavidromeDashboardData | null> = {
navidrome: stats as NavidromeDashboardData,
audiobookshelf: null,
};
const navidromeStats = navidromeStatsByBackend[backend];
const showNowPlayingSection =
navidromeStats !== null && Boolean(options.showNowPlaying) && navidromeStats.nowPlaying.length > 0;
const nowPlayingLimitByListVisibility = {
true: options.maxNowPlayingItems ?? 3,
false: 0,
} as const;
const nowPlayingTracks =
navidromeStats?.nowPlaying.slice(
0,
nowPlayingLimitByListVisibility[String(options.showNowPlayingList) as keyof typeof nowPlayingLimitByListVisibility],
) ?? [];
const hasContent = visibleStats.length > 0 || showNowPlayingSection;
return (
<div className={`${classes.root} ${rootClassByCompact[compactKey]}`}>
{visibleStats.length > 0 && (
<div
className={`${classes.grid} ${gridClassByCompact[compactKey]}`}
style={{ "--stat-cols": gridCols } as CSSProperties}
>
{visibleStats.map(({ optionKey, statKey, value, Icon }) => (
<div
key={optionKey}
className={`${classes.statTile} ${statTileClassByCompact[compactKey]}`}
>
<Icon className={classes.statIcon} size={iconSize} stroke={1.5} />
<span className={classes.statValue}>{value}</span>
<span className={classes.statLabel}>{t(statKey as never)}</span>
</div>
))}
</div>
)}
{showNowPlayingSection && navidromeStats && (
<div className={classes.nowPlaying}>
<div className={classes.nowPlayingHeader}>
<IconHeadphones size={iconSize} stroke={1.5} />
<span className={classes.nowPlayingTitle}>{t("nowPlaying" as never)}</span>
{!options.showNowPlayingList && (
<Badge className={classes.nowPlayingCount} variant="light" size="sm">
{(t as unknown as (key: string, params?: { count: number }) => string)(
"nowPlayingCount",
{ count: navidromeStats.nowPlaying.length },
)}
</Badge>
)}
</div>
{options.showNowPlayingList && (
<div className={classes.nowPlayingList}>
{nowPlayingTracks.map((track, index) => (
<div key={`${track.username}-${track.title}-${index}`} className={classes.nowPlayingItem}>
<div className={classes.trackInfo}>
<span className={classes.trackTitle}>{track.title}</span>
<span className={classes.trackArtist}>
{[track.artist, track.album].filter(Boolean).join(" · ")}
</span>
</div>
<Badge className={classes.trackUser} variant="outline" size="xs">
{track.username || track.playerName}
</Badge>
</div>
))}
</div>
)}
</div>
)}
{!hasContent && (
<div className={classes.emptyState}>
<Text size="sm" c="dimmed">
—
</Text>
</div>
)}
</div>
);
}
@@ -0,0 +1,88 @@
import { describe, expect, test } from "vitest";
import type { AudiobookshelfDashboardData, NavidromeDashboardData } from "@homarr/integrations/types";
import { getGridCols, getIconSize, getVisibleStats } from "./shared";
describe("getGridCols", () => {
test("caps columns to visible stat count", () => {
expect(getGridCols(500, 2, false)).toBe(2);
});
test("returns max cols when many stats visible", () => {
expect(getGridCols(500, 10, false)).toBe(5);
});
test("compact mode uses smaller breakpoints", () => {
expect(getGridCols(290, 5, true)).toBe(5);
expect(getGridCols(290, 5, false)).toBe(2);
});
test("returns at least 1 col even with 0 visible stats", () => {
expect(getGridCols(500, 0, false)).toBe(1);
});
});
describe("getIconSize", () => {
test("returns large size for wide container", () => {
expect(getIconSize(400, false)).toBe(22);
});
test("returns compact size for narrow container in compact mode", () => {
expect(getIconSize(100, true)).toBe(14);
});
test("returns fallback for very narrow non-compact container", () => {
expect(getIconSize(50, false)).toBe(16);
});
});
describe("getVisibleStats", () => {
const navidromeStats: NavidromeDashboardData = {
artistCount: 100,
albumCount: 200,
songCount: 3000,
nowPlaying: [],
};
const audiobookshelfStats: AudiobookshelfDashboardData = {
libraryCount: 3,
totalAudiobooks: 150,
totalPodcasts: 20,
totalListeningTimeSeconds: 86400,
activeSessions: 2,
};
test("returns only enabled navidrome stats", () => {
const result = getVisibleStats("navidrome", { showArtists: true, showAlbums: false, showSongs: true }, navidromeStats);
expect(result).toHaveLength(2);
expect(result.map((s) => s.statKey)).toEqual(["artists", "songs"]);
expect(result[0]?.value).toBe(100);
expect(result[1]?.value).toBe(3000);
});
test("returns only enabled audiobookshelf stats", () => {
const result = getVisibleStats(
"audiobookshelf",
{ showLibraryCount: true, showAudiobooks: true, showPodcasts: false, showListeningTime: false, showActiveSessions: true },
audiobookshelfStats,
);
expect(result).toHaveLength(3);
expect(result.map((s) => s.statKey)).toEqual(["libraryCount", "audiobooks", "activeSessions"]);
});
test("returns empty array when all options disabled", () => {
const result = getVisibleStats("navidrome", {}, navidromeStats);
expect(result).toEqual([]);
});
test("formats listening time as duration string", () => {
const result = getVisibleStats(
"audiobookshelf",
{ showListeningTime: true },
audiobookshelfStats,
);
expect(result).toHaveLength(1);
expect(typeof result[0]?.value).toBe("string");
});
});
@@ -0,0 +1,185 @@
.root {
container-type: size;
display: flex;
flex-direction: column;
height: 100%;
min-height: 0;
padding: clamp(6px, 3cqi, 12px);
gap: clamp(4px, 2cqi, 8px);
overflow: hidden;
}
.rootCompact {
padding: clamp(4px, 2cqi, 8px);
gap: clamp(2px, 1cqi, 4px);
}
.grid {
display: grid;
flex: 1;
width: 100%;
min-height: 0;
gap: clamp(4px, 2cqi, 8px);
grid-template-columns: repeat(var(--stat-cols, 2), minmax(0, 1fr));
grid-auto-rows: 1fr;
align-content: stretch;
}
.gridCompact {
gap: clamp(2px, 1cqi, 4px);
}
.statTile {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
min-height: 0;
min-width: 0;
height: 100%;
gap: clamp(2px, 1.5cqi, 4px);
padding: clamp(4px, 2cqi, 8px);
border-radius: var(--mantine-radius-md);
background-color: light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-6));
overflow: hidden;
}
.statTileCompact {
gap: clamp(1px, 0.8cqi, 2px);
padding: clamp(2px, 1.2cqi, 5px);
border-radius: var(--mantine-radius-sm);
}
.statIcon {
color: var(--mantine-color-dimmed);
flex-shrink: 0;
line-height: 0;
}
.statLabel {
font-size: clamp(8px, 2.5cqi, 11px);
color: var(--mantine-color-dimmed);
line-height: 1.2;
text-align: center;
max-width: 100%;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.statTileCompact .statLabel {
font-size: clamp(7px, 2cqi, 9px);
}
.statValue {
font-size: clamp(13px, 5cqi, 20px);
font-weight: 700;
color: var(--mantine-primary-color-filled);
line-height: 1.1;
text-align: center;
max-width: 100%;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.statTileCompact .statValue {
font-size: clamp(11px, 4cqi, 16px);
}
.nowPlaying {
display: flex;
flex-direction: column;
gap: clamp(3px, 1.2cqi, 5px);
flex: 1;
min-height: 0;
overflow: hidden;
}
.nowPlayingHeader {
display: flex;
align-items: center;
gap: clamp(4px, 1.5cqi, 6px);
font-size: clamp(10px, 2.8cqi, 12px);
font-weight: 600;
flex-shrink: 0;
min-width: 0;
}
.nowPlayingTitle {
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.nowPlayingCount {
flex-shrink: 0;
margin-inline-start: auto;
}
.nowPlayingList {
display: flex;
flex-direction: column;
gap: clamp(2px, 0.8cqi, 4px);
flex: 1;
min-height: 0;
overflow: hidden;
}
.nowPlayingItem {
display: flex;
align-items: center;
justify-content: space-between;
gap: clamp(4px, 1.5cqi, 6px);
padding: clamp(3px, 1.2cqi, 6px) clamp(4px, 1.5cqi, 8px);
border-radius: var(--mantine-radius-sm);
background-color: light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-6));
min-width: 0;
flex-shrink: 0;
}
.trackInfo {
display: flex;
flex-direction: column;
gap: 1px;
min-width: 0;
flex: 1;
}
.trackTitle {
font-size: clamp(9px, 2.6cqi, 12px);
font-weight: 500;
line-height: 1.2;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.trackArtist {
font-size: clamp(8px, 2.2cqi, 10px);
color: var(--mantine-color-dimmed);
line-height: 1.2;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.trackUser {
flex-shrink: 0;
max-width: clamp(40px, 22cqi, 88px);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.emptyState {
display: flex;
flex: 1;
align-items: center;
justify-content: center;
min-height: 0;
color: var(--mantine-color-dimmed);
font-size: clamp(11px, 3cqi, 13px);
text-align: center;
}
@@ -0,0 +1,40 @@
"use client";
import { clientApi } from "@homarr/api/client";
import type { WidgetComponentProps } from "../definition";
import { AudioStatsContent } from "./audio-stats-content";
import type { AudioStatsDisplayOptions } from "./shared";
const defaultDisplayOptions: AudioStatsDisplayOptions = {
showArtists: true,
showAlbums: true,
showSongs: true,
showNowPlaying: true,
showNowPlayingList: true,
maxNowPlayingItems: 3,
showLibraryCount: true,
showAudiobooks: true,
showPodcasts: true,
showListeningTime: true,
showActiveSessions: true,
compactMode: false,
};
export default function AudioStatsWidget({ integrationIds, options, width }: WidgetComponentProps<"audioStats">) {
const [response] = clientApi.widget.audioStats.getStats.useSuspenseQuery({
integrationId: integrationIds[0] ?? "",
});
const displayOptions = { ...defaultDisplayOptions, ...options };
return (
<AudioStatsContent
backend={response.kind}
stats={response.data}
options={displayOptions}
width={width}
translationScope="audioStats"
/>
);
}
+61
View File
@@ -0,0 +1,61 @@
import { IconHeadphones, IconServerOff } from "@tabler/icons-react";
import { z } from "zod/v4";
import { createWidgetDefinition } from "../definition";
import { optionsBuilder } from "../options";
const hideUnlessNavidrome = {
shouldHide: (_: unknown, integrationKinds: string[]) => !integrationKinds.includes("navidrome"),
};
const hideUnlessAudiobookshelf = {
shouldHide: (_: unknown, integrationKinds: string[]) => !integrationKinds.includes("audiobookshelf"),
};
export const { definition, componentLoader } = createWidgetDefinition("audioStats", {
icon: IconHeadphones,
supportedIntegrations: ["navidrome", "audiobookshelf"],
integrationsRequired: true,
createOptions() {
return optionsBuilder.from(
(factory) => ({
showArtists: factory.switch({ defaultValue: true, withDescription: true }),
showAlbums: factory.switch({ defaultValue: true, withDescription: true }),
showSongs: factory.switch({ defaultValue: true, withDescription: true }),
showNowPlaying: factory.switch({ defaultValue: true, withDescription: true }),
showNowPlayingList: factory.switch({ defaultValue: true, withDescription: true }),
maxNowPlayingItems: factory.number({
defaultValue: 3,
validate: z.number().min(1).max(5),
step: 1,
withDescription: true,
}),
showLibraryCount: factory.switch({ defaultValue: true, withDescription: true }),
showAudiobooks: factory.switch({ defaultValue: true, withDescription: true }),
showPodcasts: factory.switch({ defaultValue: true, withDescription: true }),
showListeningTime: factory.switch({ defaultValue: true, withDescription: true }),
showActiveSessions: factory.switch({ defaultValue: true, withDescription: true }),
compactMode: factory.switch({ defaultValue: false, withDescription: true }),
}),
{
showArtists: hideUnlessNavidrome,
showAlbums: hideUnlessNavidrome,
showSongs: hideUnlessNavidrome,
showNowPlaying: hideUnlessNavidrome,
showNowPlayingList: hideUnlessNavidrome,
maxNowPlayingItems: hideUnlessNavidrome,
showLibraryCount: hideUnlessAudiobookshelf,
showAudiobooks: hideUnlessAudiobookshelf,
showPodcasts: hideUnlessAudiobookshelf,
showListeningTime: hideUnlessAudiobookshelf,
showActiveSessions: hideUnlessAudiobookshelf,
},
);
},
errors: {
INTERNAL_SERVER_ERROR: {
icon: IconServerOff,
message: (t) => t("widget.audioStats.error.internalServerError"),
},
},
}).withDynamicImport(() => import("./component"));
+173
View File
@@ -0,0 +1,173 @@
import type { TablerIcon } from "@tabler/icons-react";
import {
IconAlbum,
IconBook,
IconBooks,
IconDisc,
IconHeadphones,
IconMicrophone,
IconMicrophone2,
IconPlayerPlay,
} from "@tabler/icons-react";
import type { AudiobookshelfDashboardData, NavidromeDashboardData } from "@homarr/integrations/types";
import { formatDuration } from "@homarr/common";
export type AudioStatsBackend = "navidrome" | "audiobookshelf";
export interface NavidromeDisplayOptions {
showArtists: boolean;
showAlbums: boolean;
showSongs: boolean;
showNowPlaying: boolean;
showNowPlayingList: boolean;
maxNowPlayingItems: number;
compactMode?: boolean;
}
export interface AudiobookshelfDisplayOptions {
showLibraryCount: boolean;
showAudiobooks: boolean;
showPodcasts: boolean;
showListeningTime: boolean;
showActiveSessions: boolean;
compactMode: boolean;
}
export type AudioStatsDisplayOptions = Partial<NavidromeDisplayOptions & AudiobookshelfDisplayOptions>;
const navidromeStatVisibilityOptions = {
showArtists: "artists",
showAlbums: "albums",
showSongs: "songs",
} as const;
const audiobookshelfStatVisibilityOptions = {
showLibraryCount: "libraryCount",
showAudiobooks: "audiobooks",
showPodcasts: "podcasts",
showListeningTime: "listeningTime",
showActiveSessions: "activeSessions",
} as const;
const statVisibilityOptionsByBackend = {
navidrome: navidromeStatVisibilityOptions,
audiobookshelf: audiobookshelfStatVisibilityOptions,
} as const;
const navidromeStatIcons = {
artists: IconMicrophone2,
albums: IconAlbum,
songs: IconDisc,
} as const;
const audiobookshelfStatIcons = {
libraryCount: IconBooks,
audiobooks: IconBook,
podcasts: IconMicrophone,
listeningTime: IconHeadphones,
activeSessions: IconPlayerPlay,
} as const;
const statIconsByBackend = {
navidrome: navidromeStatIcons,
audiobookshelf: audiobookshelfStatIcons,
} as const;
const gridColsByCompact = {
true: [
{ minWidth: 280, cols: 5 },
{ minWidth: 180, cols: 3 },
{ minWidth: 110, cols: 2 },
{ minWidth: 0, cols: 1 },
],
false: [
{ minWidth: 420, cols: 5 },
{ minWidth: 300, cols: 3 },
{ minWidth: 180, cols: 2 },
{ minWidth: 0, cols: 1 },
],
} as const;
const iconSizeByCompact = {
true: [
{ minWidth: 260, size: 18 },
{ minWidth: 160, size: 16 },
{ minWidth: 0, size: 14 },
],
false: [
{ minWidth: 320, size: 22 },
{ minWidth: 200, size: 18 },
{ minWidth: 0, size: 16 },
],
} as const;
export interface VisibleStat {
optionKey: string;
statKey: string;
value: string | number;
Icon: TablerIcon;
}
const getNavidromeStatValues = (stats: NavidromeDashboardData) =>
({
artists: stats.artistCount,
albums: stats.albumCount,
songs: stats.songCount,
}) as const;
const getAudiobookshelfStatValues = (stats: AudiobookshelfDashboardData) =>
({
libraryCount: stats.libraryCount,
audiobooks: stats.totalAudiobooks,
podcasts: stats.totalPodcasts,
listeningTime: formatDuration(stats.totalListeningTimeSeconds * 1000),
activeSessions: stats.activeSessions,
}) as const;
const statValueGetterByBackend = {
navidrome: (stats: NavidromeDashboardData | AudiobookshelfDashboardData) =>
getNavidromeStatValues(stats as NavidromeDashboardData),
audiobookshelf: (stats: NavidromeDashboardData | AudiobookshelfDashboardData) =>
getAudiobookshelfStatValues(stats as AudiobookshelfDashboardData),
} as const;
export const getVisibleStats = (
backend: AudioStatsBackend,
options: AudioStatsDisplayOptions,
stats: NavidromeDashboardData | AudiobookshelfDashboardData,
): VisibleStat[] => {
const visibilityOptions = statVisibilityOptionsByBackend[backend];
const statIcons = statIconsByBackend[backend];
const statValues = statValueGetterByBackend[backend](stats);
return Object.entries(visibilityOptions)
.filter(([optionKey]) => Boolean(options[optionKey as keyof typeof visibilityOptions]))
.map(([optionKey, statKey]) => ({
optionKey,
statKey,
value: statValues[statKey as keyof typeof statValues],
Icon: statIcons[statKey as keyof typeof statIcons],
}));
};
export const getGridCols = (width: number, visibleCount: number, compact: boolean): number => {
const colsTable = gridColsByCompact[String(compact) as keyof typeof gridColsByCompact];
const match = colsTable.find(({ minWidth }) => width >= minWidth);
const maxCols = match?.cols ?? 1;
return Math.min(maxCols, Math.max(visibleCount, 1));
};
const fallbackIconSize = { true: 14, false: 16 } as const;
export const getIconSize = (width: number, compact: boolean): number => {
const sizeTable = iconSizeByCompact[String(compact) as keyof typeof iconSizeByCompact];
const match = sizeTable.find(({ minWidth }) => width >= minWidth);
return match?.size ?? fallbackIconSize[String(compact) as keyof typeof fallbackIconSize];
};
export const translationScopeByBackend = {
navidrome: "widget.navidrome",
audiobookshelf: "widget.audiobookshelf",
audioStats: "widget.audioStats",
} as const;