Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

20.3 KB
Raw Blame
"use client";

import type { CSSProperties } from "react";
import { useCallback, useEffect, useRef, useState } from "react";
import {
  ActionIcon,
  Avatar,
  Button,
  Checkbox,
  Group,
  Popover,
  ScrollArea,
  Stack,
  Switch,
  Text,
  Tooltip,
} from "@mantine/core";
import { IconArrowDown, IconArrowUp, IconRefresh, IconAdjustments } from "@tabler/icons-react";

import { useRequiredBoard } from "@homarr/boards/context";
import { clientApi } from "@homarr/api/client";
import { useI18n } from "@homarr/translation/client";

import type { WidgetComponentProps } from "../definition";
import { useDemoReadOnly } from "../demo-read-only";
import { useWidgetRuntimeActions } from "../runtime-hooks";
import { statsEntriesSchema } from "./config";
import { StatsTable } from "./table";
import type { StatsTableRow } from "./table";
import { StatsDetails } from "./details";
import { formatStatsValue } from "./format";
import { StatsLoading } from "./loading";
import classes from "./stats.module.css";

export default function StatsWidget({
  integrationIds,
  widgetRuntimeRef,
  isEditMode,
  options,
  width,
  displayMode,
  displayScale = 1,
}: WidgetComponentProps<"stats">) {
  const board = useRequiredBoard();
  const demoReadOnly = useDemoReadOnly();
  const advanced = displayMode === "advanced";
  const t = useI18n("widget.stats");
  const utils = clientApi.useUtils();
  const [refreshing, setRefreshing] = useState(0);
  const refreshErrors = useRef(new Map<string, number | null>());
  const [localTable, setLocalTable] = useState<boolean>();
  const table = advanced || (localTable ?? options.table);
  const [localRows, setLocalRows] = useState<boolean>();
  const [localPlain, setPlain] = useState<boolean>();
  const [compact, setCompact] = useState<boolean>();
  const [hidden, setHidden] = useState<string[]>([]);
  const [order, setOrder] = useState<string[]>([]);
  const [settingsOpen, setSettingsOpen] = useState(false);
  const [detailsId, setDetailsId] = useState<string | null>(null);
  const rows = localRows ?? options.rows;
  const plain = localPlain ?? options.plain;
  const pending = useRef(new Set<string>());
  const retry = useRef(new Map<string, number>());
  const entries = statsEntriesSchema.safeParse(options.entries).data ?? [];
  const orderedEntries = entries.toSorted((a, b) => {
    const position = (id: string) => {
      const index = order.indexOf(id);
      if (index >= 0) return index;
      return order.length + entries.findIndex((entry) => entry.id === id);
    };
    return position(a.id) - position(b.id);
  });
  const visibleEntries = orderedEntries.filter((entry) => !entry.hidden && !hidden.includes(entry.id));
  const ids = [...new Set(integrationIds)];
  // Queries are per integration instance, never per metric. Click and advanced details reuse these snapshots.
  const visibleIds = ids.filter((id) => advanced || visibleEntries.some((entry) => entry.integrationId === id));
  const catalogs = clientApi.useQueries((api) =>
    ids.map((integrationId) => api.widget.stats.catalog({ integrationId }, { staleTime: 60_000, retry: false })),
  );
  const snapshots = clientApi.useQueries((api) =>
    visibleIds.map((integrationId) =>
      api.widget.stats.snapshot(
        { integrationId },
        {
          staleTime: 30_000,
          refetchInterval: demoReadOnly ? false : 60_000,
          refetchOnWindowFocus: !demoReadOnly,
          refetchIntervalInBackground: false,
          retry: false,
        },
      ),
    ),
  );

  const hasRefreshError = (integrationId: string) => {
    const failedSnapshotAt = refreshErrors.current.get(integrationId);
    if (failedSnapshotAt === undefined) return false;
    const updatedAt = utils.widget.stats.snapshot.getData({ integrationId })?.updatedAt;
    if (updatedAt == null) return true;
    // A different widget or browser may have recovered this shared source after our transport failure.
    if (failedSnapshotAt === null) return false;
    return updatedAt <= failedSnapshotAt;
  };

  const refresh = useCallback(
    async (integrationId: string, force: boolean) => {
      if (pending.current.has(integrationId)) return;
      if (!force && (retry.current.get(integrationId) ?? 0) > Date.now()) return;
      const previousUpdatedAt = utils.widget.stats.snapshot.getData({ integrationId })?.updatedAt ?? null;
      pending.current.add(integrationId);
      refreshErrors.current.delete(integrationId);
      setRefreshing((value) => value + 1);
      try {
        const result = await utils.client.widget.stats.refresh.mutate({ integrationId, force });
        await utils.widget.stats.snapshot.cancel({ integrationId });
        utils.widget.stats.snapshot.setData({ integrationId }, result);
        retry.current.set(integrationId, Date.now() + 60_000);
      } catch {
        refreshErrors.current.set(integrationId, previousUpdatedAt);
        retry.current.set(integrationId, Date.now() + 60_000);
        await utils.widget.stats.snapshot.invalidate({ integrationId });
      } finally {
        pending.current.delete(integrationId);
        setRefreshing((value) => value - 1);
      }
    },
    [utils],
  );

  const refreshSources = async () => {
    await Promise.all(visibleIds.map((id) => refresh(id, true)));
  };
  useWidgetRuntimeActions(widgetRuntimeRef, {
    refresh: refreshSources,
    getDataStatus: () => {
      // Read the cache at invocation time: the menu can finish refreshing before React commits our next render.
      const currentSnapshots = visibleIds.map((integrationId) =>
        utils.widget.stats.snapshot.getData({ integrationId }),
      );
      const timestamps = currentSnapshots.flatMap((snapshot) => {
        if (snapshot?.updatedAt == null) return [];
        return [snapshot.updatedAt];
      });
      let updatedAt: number | null = null;
      if (timestamps.length > 0) updatedAt = Math.min(...timestamps);
      return {
        updatedAt,
        hasError:
          visibleIds.some(hasRefreshError) ||
          currentSnapshots.some((snapshot) => !!snapshot?.error) ||
          snapshots.some((snapshot) => !!snapshot.error),
        isRefreshing: pending.current.size > 0,
      };
    },
  });

  useEffect(() => {
    if (demoReadOnly || document.hidden) return;
    for (const [index, integrationId] of visibleIds.entries()) {
      const snapshot = snapshots[index];
      if (!snapshot?.data || snapshot.error) continue;
      if (snapshot.data.updatedAt === null && snapshot.data.retryAt <= Date.now()) void refresh(integrationId, false);
    }
  }, [demoReadOnly, visibleIds, snapshots, refresh]);

  const tableEntries = advanced
    ? ids.flatMap((id) => {
        const catalog = catalogs[ids.indexOf(id)]?.data;
        if (!catalog) return [{ id, integrationId: id, metric: "", label: "", compact: false }];
        return catalog.metrics.map((metric) => ({
          id: `${id}:${metric.key}`,
          integrationId: id,
          metric: metric.key,
          label: metric.label,
          compact: false,
        }));
      })
    : visibleEntries;
  const tableRecords: StatsTableRow[] = tableEntries.map((entry) => {
    const catalog = catalogs[ids.indexOf(entry.integrationId)];
    const snapshot = snapshots[visibleIds.indexOf(entry.integrationId)];
    const metric = catalog?.data?.metrics.find((item) => item.key === entry.metric);
    const refreshFailed = !!snapshot?.error || hasRefreshError(entry.integrationId);
    const unavailable =
      !ids.includes(entry.integrationId) ||
      (!!catalog?.error && !catalog.data) ||
      (!!snapshot?.error && !snapshot.data) ||
      (!!catalog?.data && !metric);
    const loading =
      !unavailable && !refreshFailed && !snapshot?.data?.error && (snapshot?.data?.updatedAt == null || !metric);
    let value = "—";
    let status = "";
    if (snapshot?.data && metric)
      value = formatStatsValue(snapshot.data.values[entry.metric], metric.unit, compact ?? entry.compact);
    if (refreshFailed) status = t("refreshFailed");
    if (snapshot?.data?.error) status = t("refreshFailed");
    if ((refreshFailed || snapshot?.data?.error) && snapshot?.data?.updatedAt == null) status = t("fetchFailed");
    if (unavailable) {
      value = t("unavailable");
      status = t("unavailable");
    }
    return {
      id: entry.id,
      integrationId: entry.integrationId,
      source: catalog?.data?.name ?? "",
      iconUrl: catalog?.data?.iconUrl,
      metric: entry.label || metric?.label || entry.metric,
      value,
      status,
      loading,
    };
  });

  let physicalWidth = width;
  if (!advanced && Number.isFinite(displayScale) && displayScale > 0) physicalWidth *= displayScale;
  let minimumWidth = 150;
  if (rows) minimumWidth = 200;
  if (advanced) minimumWidth = 280;
  let itemCount = visibleEntries.length;
  if (advanced) itemCount = ids.length;
  const columns = Math.max(1, Math.min(itemCount, Math.floor(physicalWidth / minimumWidth)));
  let gap = 8;
  if (options.spacing === "sm") gap = 12;
  if (options.spacing === "md") gap = 16;
  const rootStyle = { "--stats-radius": `var(--mantine-radius-${board.itemRadius})` } as CSSProperties;
  if (!advanced && displayScale > 1) {
    Object.assign(rootStyle, { "--mantine-scale": 1 / displayScale, "--board-canvas-ui-scale": 1 / displayScale });
  }

  return (
    <div
      className={classes.root}
      data-advanced={advanced || undefined}
      data-table={table || undefined}
      data-rows={rows || undefined}
      data-plain={plain || undefined}
      style={rootStyle}
    >
      <div className={classes.toolbar}>
        <Popover opened={settingsOpen} onChange={setSettingsOpen} position="top-end" width={300} withinPortal trapFocus>
          <Popover.Target>
            <ActionIcon
              variant="default"
              size="sm"
              radius="xl"
              aria-label={t("viewOptions")}
              onClick={() => setSettingsOpen((value) => !value)}
            >
              <IconAdjustments size={13} />
            </ActionIcon>
          </Popover.Target>
          <Popover.Dropdown>
            <Stack gap="sm">
              <Text size="sm" fw={600}>
                {t("viewOptions")}
              </Text>
              <Text size="xs" c="dimmed">
                {t("localHelp")}
              </Text>
              {!advanced && (
                <Switch
                  label={t("option.table.label")}
                  checked={table}
                  onChange={(event) => setLocalTable(event.currentTarget.checked)}
                />
              )}
              <Switch
                disabled={table}
                label={t("option.rows.label")}
                checked={rows}
                onChange={(event) => setLocalRows(event.currentTarget.checked)}
              />
              <Switch
                disabled={table}
                label={t("plain")}
                checked={plain}
                onChange={(event) => setPlain(event.currentTarget.checked)}
              />
              <Switch
                label={t("compact")}
                checked={compact ?? (!advanced && entries.every((entry) => entry.compact))}
                onChange={(event) => setCompact(event.currentTarget.checked)}
              />
              {!advanced && (
                <ScrollArea.Autosize mah={240}>
                  <Stack gap={8}>
                    {orderedEntries
                      .filter((entry) => !entry.hidden)
                      .map((entry, index, displayed) => {
                        const catalog = catalogs[ids.indexOf(entry.integrationId)]?.data;
                        const label =
                          entry.label ||
                          catalog?.metrics.find((item) => item.key === entry.metric)?.label ||
                          entry.metric;
                        const move = (delta: number) => {
                          const next = [...orderedEntries];
                          const currentIndex = next.findIndex((item) => item.id === entry.id);
                          const neighbor = displayed[index + delta];
                          if (!neighbor) return;
                          const targetIndex = next.findIndex((item) => item.id === neighbor.id);
                          next.splice(currentIndex, 1);
                          next.splice(targetIndex, 0, entry);
                          setOrder(next.map((item) => item.id));
                        };
                        return (
                          <Group key={entry.id} gap={6} wrap="nowrap">
                            <Checkbox
                              style={{ flex: 1 }}
                              size="xs"
                              label={label}
                              checked={!hidden.includes(entry.id)}
                              onChange={(event) => {
                                if (event.currentTarget.checked)
                                  setHidden((values) => values.filter((id) => id !== entry.id));
                                else setHidden((values) => [...values, entry.id]);
                              }}
                            />
                            <ActionIcon
                              variant="subtle"
                              size="xs"
                              aria-label={`${t("moveUp")}: ${label}`}
                              disabled={index === 0}
                              onClick={() => move(-1)}
                            >
                              <IconArrowUp size={12} />
                            </ActionIcon>
                            <ActionIcon
                              variant="subtle"
                              size="xs"
                              aria-label={`${t("moveDown")}: ${label}`}
                              disabled={index === displayed.length - 1}
                              onClick={() => move(1)}
                            >
                              <IconArrowDown size={12} />
                            </ActionIcon>
                          </Group>
                        );
                      })}
                  </Stack>
                </ScrollArea.Autosize>
              )}
              <Button
                variant="subtle"
                size="xs"
                onClick={() => {
                  setLocalTable(undefined);
                  setLocalRows(undefined);
                  setPlain(undefined);
                  setCompact(undefined);
                  setHidden([]);
                  setOrder([]);
                }}
              >
                {t("resetView")}
              </Button>
            </Stack>
          </Popover.Dropdown>
        </Popover>
        <Tooltip label={t("refresh")} events={{ hover: true, focus: true, touch: true }}>
          <ActionIcon
            variant="default"
            size="sm"
            radius="xl"
            aria-label={t("refresh")}
            loading={refreshing > 0}
            onClick={() => void refreshSources()}
          >
            <IconRefresh size={13} />
          </ActionIcon>
        </Tooltip>
      </div>
      {!table && visibleEntries.length === 0 && (
        <Text size="xs" c="dimmed" ta="center" p="md">
          {entries.length > 0 ? t("allHidden") : t("empty")}
        </Text>
      )}
      {table && <StatsTable records={tableRecords} showIcon={options.showIcon} isEditMode={isEditMode} />}
      {!table && (
        <ScrollArea h="100%" type="hover" offsetScrollbars>
          <div className={classes.grid} style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gap }}>
            {!advanced &&
              visibleEntries.map((entry) => {
                const catalog = catalogs[ids.indexOf(entry.integrationId)];
                const snapshot = snapshots[visibleIds.indexOf(entry.integrationId)];
                const metric = catalog?.data?.metrics.find((item) => item.key === entry.metric);
                const refreshFailed = !!snapshot?.error || hasRefreshError(entry.integrationId);
                const unavailable =
                  !ids.includes(entry.integrationId) ||
                  (!!catalog?.error && !catalog.data) ||
                  (!!snapshot?.error && !snapshot.data);
                const loading =
                  !unavailable &&
                  !(catalog?.data && !metric) &&
                  !refreshFailed &&
                  !snapshot?.data?.error &&
                  (snapshot?.data?.updatedAt == null || !metric);
                let value = "—";
                if (unavailable || (catalog?.data && !metric)) value = t("unavailable");
                else if (snapshot?.data && metric)
                  value = formatStatsValue(snapshot.data.values[entry.metric], metric.unit, compact ?? entry.compact);
                const label = entry.label || metric?.label || entry.metric;
                const sourceName = catalog?.data?.name ?? "";
                let accessibleValue = value;
                if (loading) accessibleValue = t("loading");
                let loaderSize = 26;
                if (rows) loaderSize = 18;
                let loaderIcon: string | undefined;
                if (options.showIcon) loaderIcon = catalog?.data?.iconUrl;
                let status = "";
                if (refreshFailed) status = t("refreshFailed");
                if (snapshot?.data?.error) status = t("refreshFailed");
                if ((refreshFailed || snapshot?.data?.error) && snapshot?.data?.updatedAt == null)
                  status = t("fetchFailed");
                if (unavailable) status = t("unavailable");
                return (
                  <Popover
                    key={entry.id}
                    opened={detailsId === entry.id}
                    onChange={(opened) => {
                      if (!opened) setDetailsId(null);
                    }}
                    withArrow
                    width="min(360px, calc(100vw - 32px))"
                    withinPortal
                    trapFocus
                  >
                    <Popover.Target>
                      <button
                        type="button"
                        className={classes.card}
                        onClick={(event) => {
                          event.stopPropagation();
                          setDetailsId((current) => {
                            if (current === entry.id) return null;
                            return entry.id;
                          });
                        }}
                        aria-label={`${label}: ${accessibleValue}. ${sourceName}. ${status}`}
                        aria-busy={loading}
                      >
                        {options.showIcon && catalog?.data && !loading && (
                          <Avatar
                            className={classes.icon}
                            src={catalog.data.iconUrl}
                            size={12}
                            radius={3}
                            alt={sourceName}
                            name={sourceName}
                            imageProps={{ referrerPolicy: "no-referrer" }}
                            styles={{ image: { objectFit: "contain" } }}
                          />
                        )}
                        <div className={classes.main}>
                          <Text component="div" className={classes.value}>
                            {loading && <StatsLoading iconUrl={loaderIcon} source={sourceName} size={loaderSize} />}
                            {!loading && value}
                          </Text>
                          <Text className={classes.label} lineClamp={2}>
                            {label}
                          </Text>
                        </div>
                      </button>
                    </Popover.Target>
                    <Popover.Dropdown className={classes.details} onClick={(event) => event.stopPropagation()}>
                      {catalog?.data && (
                        <StatsDetails
                          catalog={catalog.data}
                          snapshot={snapshot?.data}
                          selected={entry.metric}
                          showIcon={options.showIcon}
                          unavailable={unavailable}
                          refreshFailed={refreshFailed}
                        />
                      )}
                      {!catalog?.data && unavailable && t("unavailable")}
                      {!catalog?.data && !unavailable && <StatsLoading />}
                    </Popover.Dropdown>
                  </Popover>
                );
              })}
          </div>
        </ScrollArea>
      )}
    </div>
  );
}