feat: add Uptime Kuma, Audiobookshelf, Paperless-ngx, and Navidrome integrations (#5910)

This commit is contained in:
Thomas authored and GitHub committed 2026-06-10 18:27:24 +02:00
1 parent a4db9cf0dc
commit d77c6f8d4e
46 files changed
+2994 -16

No files matched your search

@@ -0,0 +1,125 @@
"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 { AUDIO_STATS_TRANSLATION_SCOPE, getGridCols, getIconSize, getVisibleStats } 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;
}
export function AudioStatsContent({ backend, stats, options, width }: AudioStatsContentProps) {
const t = useScopedI18n(AUDIO_STATS_TRANSLATION_SCOPE);
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,94 @@
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,14 @@
"use client";
import { clientApi } from "@homarr/api/client";
import type { WidgetComponentProps } from "../definition";
import { AudioStatsContent } from "./audio-stats-content";
export default function AudioStatsWidget({ integrationIds, options, width }: WidgetComponentProps<"audioStats">) {
const [response] = clientApi.widget.audioStats.getStats.useSuspenseQuery({
integrationId: integrationIds[0] ?? "",
});
return <AudioStatsContent backend={response.kind} stats={response.data} options={options} width={width} />;
}
+62
View File
@@ -0,0 +1,62 @@
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,
maxIntegrations: 1,
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"));
+169
View File
@@ -0,0 +1,169 @@
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 AUDIO_STATS_TRANSLATION_SCOPE = "widget.audioStats" as const;