feat(custom-widgets): add extensible widget platform

2026-09-12 13:54:05 +02:00
1 parent 6cca757493
commit 8f152f1929
@@ -0,0 +1,95 @@
+.homarr-data-table,
+.homarr-data-table .mantine-datatable-table,
+.homarr-data-table .mantine-datatable-table thead,
+.homarr-data-table .mantine-datatable-table tbody,
+.homarr-data-table .mantine-datatable-table tfoot,
+.homarr-data-table th,
+.homarr-data-table td {
+  background-color: transparent !important;
+}
+
+.homarr-data-table .mantine-datatable-table tr {
+  background-color: transparent;
+}
+
+.homarr-data-table .mantine-datatable-table {
+  width: 100% !important;
+  max-width: 100%;
+  table-layout: fixed !important;
+}
+
+.homarr-data-table .mantine-datatable-table tbody tr:hover {
+  background-color: color-mix(in srgb, var(--mantine-color-default-hover) 40%, transparent) !important;
+}
+
+.homarr-data-table .mantine-datatable-scroll-area-scrollbar[data-state="visible"]:hover {
+  @mixin light {
+    background-color: var(--mantine-color-gray-0);
+  }
+
+  @mixin dark {
+    background-color: var(--mantine-color-dark-8);
+  }
+}
+
+.homarr-data-table th {
+  padding: 0;
+  white-space: nowrap;
+  background-color: color-mix(in srgb, var(--mantine-color-body) 60%, transparent) !important;
+  backdrop-filter: blur(8px);
+}
+
+.homarr-data-table td {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Lets a cell's content (e.g. an oversized action icon) visually overflow its own box without
+   growing it - used to make a per-row icon look bigger without inflating row height, since the
+   icon is pulled out of flow via absolute positioning rather than actually being a bigger cell. */
+.homarr-data-table td.docker-actions-cell {
+  overflow: visible;
+}
+
+.homarr-data-table td .mantine-Text-root,
+.homarr-data-table td .mantine-Group-root {
+  white-space: nowrap;
+  flex-wrap: nowrap;
+}
+
+.homarr-data-table .mantine-datatable-header-cell-sortable-icon,
+.homarr-data-table .mantine-datatable-header-cell-draggable-action-icon {
+  opacity: 0;
+  transition: opacity 150ms ease-out;
+}
+
+.homarr-data-table .mantine-datatable-header-cell-sortable-group {
+  gap: 0;
+}
+
+.homarr-data-table .mantine-datatable-header-cell-draggable-action-icon {
+  margin: 0;
+}
+
+.homarr-data-table .mantine-datatable-header-cell-sortable-unsorted-icon {
+  display: none;
+}
+
+.homarr-data-table .mantine-datatable-header-cell-draggable-action-icon svg,
+.homarr-data-table .mantine-datatable-header-cell-sortable-text svg,
+.homarr-data-table .mantine-datatable-header-cell-sortable-icon svg {
+  width: var(--mantine-font-size-md);
+  height: var(--mantine-font-size-md);
+}
+
+.homarr-data-table th:hover .mantine-datatable-header-cell-sortable-icon,
+.homarr-data-table th:hover .mantine-datatable-header-cell-draggable-action-icon,
+.homarr-data-table .mantine-datatable-header-cell-draggable-action-icon:focus-visible,
+.homarr-data-table .mantine-datatable-header-cell-drag-over .mantine-datatable-header-cell-draggable-action-icon {
+  opacity: 1;
+}
+
+.homarr-data-table-row-cursor-default .mantine-datatable-context-menu-cursor {
+  cursor: default;
+}
@@ -0,0 +1,2 @@
+declare const stylesheet: string;
+export default stylesheet;
@@ -0,0 +1,163 @@
+"use client";
+
+// Shared CSS is required by both native and package table consumers.
+// eslint-disable-next-line import/no-unassigned-import
+import "./homarr-data-table.css";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { DataTableColumn, DataTableProps } from "mantine-datatable";
+import { DataTable } from "mantine-datatable";
+
+import { scrollAreaDefaultProps } from "../ui-settings";
+
+const fallbackColumnWidth = 60;
+
+const getColumnWidth = (width: string | number | undefined): number => {
+  if (typeof width === "number" && Number.isFinite(width) && width > 0) return width;
+  if (typeof width === "string") {
+    const parsedWidth = Number.parseFloat(width);
+    if (Number.isFinite(parsedWidth) && parsedWidth > 0) return parsedWidth;
+  }
+  return fallbackColumnWidth;
+};
+
+type HomarrDataTableProps<T> = DataTableProps<T> & {
+  columns: DataTableColumn<T>[];
+  groups?: never;
+  isEditMode: boolean;
+  cellPadding: string;
+  rowCursor?: "auto" | "default";
+};
+
+export function HomarrDataTable<T>({
+  isEditMode,
+  cellPadding,
+  rowCursor = "auto",
+  className,
+  columns,
+  defaultColumnProps,
+  onMouseDownCapture,
+  scrollAreaProps,
+  style,
+  ...props
+}: HomarrDataTableProps<T>) {
+  const [resizePreviewWidths, setResizePreviewWidths] = useState<Record<string, number>>();
+  const removeResizeListeners = useRef<() => void>(() => undefined);
+  useEffect(() => () => removeResizeListeners.current(), []);
+
+  const handleMouseDownCapture = useCallback(
+    (event: React.MouseEvent<HTMLTableElement>) => {
+      onMouseDownCapture?.(event);
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      const handle = target.closest(".mantine-datatable-header-resizable-handle");
+      const currentCell = handle?.closest<HTMLTableCellElement>("th[data-accessor]");
+      const headerRow = currentCell?.parentElement;
+      if (!currentCell || !headerRow) return;
+
+      const cells = Array.from(headerRow.querySelectorAll<HTMLTableCellElement>("th[data-accessor]"));
+      const currentIndex = cells.indexOf(currentCell);
+      const nextCell = cells[currentIndex + 1];
+      const currentAccessor = currentCell.dataset.accessor;
+      const nextAccessor = nextCell?.dataset.accessor;
+      if (!nextCell || !currentAccessor || !nextAccessor) return;
+
+      const widths = Object.fromEntries(
+        cells.flatMap((cell) => {
+          const accessor = cell.dataset.accessor;
+          if (!accessor) return [];
+          return [[accessor, cell.getBoundingClientRect().width]];
+        }),
+      );
+      const currentWidth = widths[currentAccessor];
+      const nextWidth = widths[nextAccessor];
+      if (currentWidth === undefined || nextWidth === undefined) return;
+
+      const visualScale = currentCell.getBoundingClientRect().width / currentCell.offsetWidth;
+      const minimumWidth = fallbackColumnWidth * visualScale;
+      const startX = event.clientX;
+
+      removeResizeListeners.current();
+      const handleMouseMove = (moveEvent: MouseEvent) => {
+        const delta = Math.min(
+          nextWidth - minimumWidth,
+          Math.max(minimumWidth - currentWidth, moveEvent.clientX - startX),
+        );
+        setResizePreviewWidths({
+          ...widths,
+          [currentAccessor]: currentWidth + delta,
+          [nextAccessor]: nextWidth - delta,
+        });
+      };
+      const handleResizeEnd = () => {
+        removeResizeListeners.current();
+        requestAnimationFrame(() => requestAnimationFrame(() => setResizePreviewWidths(undefined)));
+      };
+      removeResizeListeners.current = () => {
+        window.removeEventListener("mousemove", handleMouseMove);
+        window.removeEventListener("mouseup", handleResizeEnd);
+        window.removeEventListener("blur", handleResizeEnd);
+      };
+      window.addEventListener("mousemove", handleMouseMove);
+      window.addEventListener("mouseup", handleResizeEnd);
+      window.addEventListener("blur", handleResizeEnd);
+    },
+    [onMouseDownCapture],
+  );
+
+  const mergedClassName = [
+    "homarr-data-table",
+    rowCursor === "default" ? "homarr-data-table-row-cursor-default" : undefined,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const fittedColumns = useMemo(() => {
+    const visibleColumns = columns.filter(({ hidden }) => !hidden);
+    const getRenderedWidth = (column: DataTableColumn<T>) =>
+      resizePreviewWidths?.[String(column.accessor)] ?? getColumnWidth(column.width);
+    const totalWidth = visibleColumns.reduce((total, column) => total + getRenderedWidth(column), 0);
+    if (totalWidth <= 0) return columns;
+
+    return columns.map((column) => {
+      if (column.hidden) return column;
+
+      const width = `${(getRenderedWidth(column) / totalWidth) * 100}%`;
+      const fittedWidth = { width, minWidth: width, maxWidth: width };
+      const cellsStyle = column.cellsStyle ?? defaultColumnProps?.cellsStyle;
+      return {
+        ...column,
+        titleStyle: [column.titleStyle, fittedWidth],
+        cellsStyle: (record: T, index: number) => [cellsStyle?.(record, index), fittedWidth, { padding: cellPadding }],
+      };
+    });
+  }, [cellPadding, columns, defaultColumnProps?.cellsStyle, resizePreviewWidths]);
+
+  return (
+    <DataTable<T>
+      withTableBorder={false}
+      borderRadius={0}
+      highlightOnHover
+      highlightOnHoverColor={{ dark: "dark.5", light: "gray.1" }}
+      verticalAlign="center"
+      loaderBackgroundBlur={2}
+      textSelectionDisabled
+      height="100%"
+      {...props}
+      striped={false}
+      columns={fittedColumns}
+      onMouseDownCapture={handleMouseDownCapture}
+      className={mergedClassName}
+      style={[{ pointerEvents: isEditMode ? "none" : undefined }, style]}
+      defaultColumnProps={{
+        ...defaultColumnProps,
+        noWrap: defaultColumnProps?.noWrap ?? true,
+        draggable: true,
+        resizable: true,
+        cellsStyle: defaultColumnProps?.cellsStyle ?? (() => ({ padding: cellPadding })),
+      }}
+      scrollAreaProps={{ ...scrollAreaDefaultProps, ...scrollAreaProps }}
+    />
+  );
+}
@@ -0,0 +1,235 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { DataTableColumn } from "mantine-datatable";
+import { useDataTableColumns } from "mantine-datatable";
+
+import { isRecord } from "@homarr/common";
+
+interface TableLayoutOptions extends Record<string, unknown> {
+  columnOrder?: string;
+  columnWidths?: string;
+}
+
+interface PendingTableLayout {
+  layout: TableLayoutOptions;
+  onLayoutChange: (layout: TableLayoutOptions) => void;
+  storeKey: string;
+}
+
+interface UseTableLayoutPersistenceProps {
+  boardId: string | undefined;
+  hasChangeAccess: boolean;
+  itemId: string | undefined;
+  saveItemOptions: (input: { boardId: string; itemId: string; newOptions: TableLayoutOptions }) => void;
+  setOptions: (input: { newOptions: TableLayoutOptions }) => void;
+}
+
+interface UsePersistedTableLayoutProps<T> {
+  columns: DataTableColumn<T>[];
+  columnAccessors: readonly string[];
+  columnOrder: string;
+  columnWidths: string;
+  itemId: string | undefined;
+  storeKeyPrefix: string;
+  onLayoutChange: (layout: TableLayoutOptions) => void;
+}
+
+const layoutSaveDelay = 350;
+
+export const useTableLayoutPersistence = ({
+  boardId,
+  hasChangeAccess,
+  itemId,
+  saveItemOptions,
+  setOptions,
+}: UseTableLayoutPersistenceProps) =>
+  useCallback(
+    (newOptions: TableLayoutOptions) => {
+      setOptions({ newOptions });
+      if (hasChangeAccess && boardId && itemId) saveItemOptions({ boardId, itemId, newOptions });
+    },
+    [boardId, hasChangeAccess, itemId, saveItemOptions, setOptions],
+  );
+
+const toPixelWidth = (width: string | number): number | undefined => {
+  if (typeof width === "number" && Number.isFinite(width) && width > 0) return width;
+  if (typeof width !== "string" || !width.endsWith("px")) return undefined;
+
+  const parsedWidth = Number.parseInt(width, 10);
+  return Number.isFinite(parsedWidth) && parsedWidth > 0 ? parsedWidth : undefined;
+};
+
+const getColumnWidthMap = (
+  columnsWidth: Record<string, string | number>[],
+  visibleAccessorSet: ReadonlySet<string>,
+): Record<string, number> => {
+  const widths: Record<string, number> = {};
+  for (const entry of columnsWidth) {
+    for (const [accessor, width] of Object.entries(entry)) {
+      if (!visibleAccessorSet.has(accessor)) continue;
+      const pixelWidth = toPixelWidth(width);
+      if (pixelWidth !== undefined) widths[accessor] = pixelWidth;
+    }
+  }
+  return widths;
+};
+
+export const parseColumnOrder = (value: string, columnAccessors: readonly string[]): string[] => {
+  if (!value) return [];
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed)) return [];
+
+    const allowed = new Set(columnAccessors);
+    return parsed.filter(
+      (accessor, index): accessor is string =>
+        typeof accessor === "string" && allowed.has(accessor) && parsed.indexOf(accessor) === index,
+    );
+  } catch {
+    return [];
+  }
+};
+
+export const parseColumnWidths = (value: string, columnAccessors: readonly string[]): Record<string, number> => {
+  if (!value) return {};
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!isRecord(parsed)) return {};
+
+    const allowed = new Set(columnAccessors);
+    return Object.fromEntries(
+      Object.entries(parsed).filter(
+        (entry): entry is [string, number] =>
+          allowed.has(entry[0]) && typeof entry[1] === "number" && Number.isFinite(entry[1]) && entry[1] > 0,
+      ),
+    );
+  } catch {
+    return {};
+  }
+};
+
+export const usePersistedTableLayout = <T>({
+  columns,
+  columnAccessors,
+  columnOrder,
+  columnWidths,
+  itemId,
+  storeKeyPrefix,
+  onLayoutChange,
+}: UsePersistedTableLayoutProps<T>) => {
+  const savedOrder = useMemo(() => parseColumnOrder(columnOrder, columnAccessors), [columnAccessors, columnOrder]);
+  const savedWidths = useMemo(() => parseColumnWidths(columnWidths, columnAccessors), [columnAccessors, columnWidths]);
+  const visibleAccessors = useMemo(() => columns.map(({ accessor }) => String(accessor)), [columns]);
+  const visibleAccessorSet = useMemo(() => new Set(visibleAccessors), [visibleAccessors]);
+  const restoredOrder = useMemo(
+    () => [
+      ...savedOrder.filter((accessor) => visibleAccessorSet.has(accessor)),
+      ...visibleAccessors.filter((accessor) => !savedOrder.includes(accessor)),
+    ],
+    [savedOrder, visibleAccessors, visibleAccessorSet],
+  );
+  const storeKey = `${storeKeyPrefix}-${itemId ?? "preview"}-${[...visibleAccessors].toSorted().join(",")}`;
+  const { effectiveColumns, columnsOrder, columnsWidth, setColumnsOrder, setMultipleColumnWidths } =
+    useDataTableColumns<T>({
+      key: storeKey,
+      columns,
+    });
+
+  const lastStoreKey = useRef(storeKey);
+  const hydrated = useRef(false);
+  const previousOrder = useRef(columnsOrder);
+  const previousWidths = useRef(columnsWidth);
+  useEffect(() => {
+    if (lastStoreKey.current !== storeKey) {
+      lastStoreKey.current = storeKey;
+      hydrated.current = false;
+    }
+    if (hydrated.current) return;
+
+    const orderMatches =
+      columnsOrder.length === restoredOrder.length &&
+      columnsOrder.every((accessor, index) => accessor === restoredOrder[index]);
+    const currentWidths = getColumnWidthMap(columnsWidth, visibleAccessorSet);
+    const visibleWidths = Object.entries(savedWidths).filter(([accessor]) => visibleAccessorSet.has(accessor));
+    const widthsMatch = visibleWidths.every(([accessor, width]) => currentWidths[accessor] === width);
+
+    if (orderMatches && widthsMatch) {
+      previousOrder.current = columnsOrder;
+      previousWidths.current = columnsWidth;
+      hydrated.current = true;
+      return;
+    }
+
+    if (!orderMatches) setColumnsOrder(restoredOrder);
+    if (!widthsMatch) {
+      setMultipleColumnWidths(visibleWidths.map(([accessor, width]) => ({ accessor, width })));
+    }
+  }, [
+    columnsOrder,
+    columnsWidth,
+    restoredOrder,
+    savedWidths,
+    setColumnsOrder,
+    setMultipleColumnWidths,
+    storeKey,
+    visibleAccessorSet,
+  ]);
+
+  const pendingLayout = useRef<PendingTableLayout | undefined>(undefined);
+  const saveTimeout = useRef<number | undefined>(undefined);
+  const flushPendingLayout = useCallback(() => {
+    const pending = pendingLayout.current;
+    pendingLayout.current = undefined;
+    window.clearTimeout(saveTimeout.current);
+    saveTimeout.current = undefined;
+    if (pending) pending.onLayoutChange(pending.layout);
+  }, []);
+  useEffect(() => {
+    if (pendingLayout.current && pendingLayout.current.storeKey !== storeKey) flushPendingLayout();
+  }, [flushPendingLayout, storeKey]);
+  useEffect(() => () => flushPendingLayout(), [flushPendingLayout]);
+  useEffect(() => {
+    if (!hydrated.current) return;
+
+    const orderChanged = JSON.stringify(columnsOrder) !== JSON.stringify(previousOrder.current);
+    const widthsChanged = JSON.stringify(columnsWidth) !== JSON.stringify(previousWidths.current);
+    previousOrder.current = columnsOrder;
+    previousWidths.current = columnsWidth;
+    if (!orderChanged && !widthsChanged) return;
+
+    const newLayout: TableLayoutOptions = {};
+    if (orderChanged) {
+      const fullOrder = [...savedOrder, ...columnAccessors.filter((accessor) => !savedOrder.includes(accessor))];
+      const reorderedVisibleColumns = [...columnsOrder];
+      const mergedOrder = fullOrder.map((accessor) =>
+        visibleAccessorSet.has(accessor) ? (reorderedVisibleColumns.shift() ?? accessor) : accessor,
+      );
+      newLayout.columnOrder = JSON.stringify(mergedOrder);
+    }
+    if (widthsChanged) {
+      const widthMap: Record<string, number> = { ...savedWidths };
+      Object.assign(widthMap, getColumnWidthMap(columnsWidth, visibleAccessorSet));
+      newLayout.columnWidths = JSON.stringify(widthMap);
+    }
+
+    if (pendingLayout.current && pendingLayout.current.storeKey !== storeKey) flushPendingLayout();
+    pendingLayout.current = pendingLayout.current
+      ? { ...pendingLayout.current, layout: { ...pendingLayout.current.layout, ...newLayout } }
+      : { layout: newLayout, onLayoutChange, storeKey };
+    window.clearTimeout(saveTimeout.current);
+    saveTimeout.current = window.setTimeout(flushPendingLayout, layoutSaveDelay);
+  }, [
+    columnAccessors,
+    columnsOrder,
+    columnsWidth,
+    flushPendingLayout,
+    onLayoutChange,
+    savedOrder,
+    savedWidths,
+    storeKey,
+    visibleAccessorSet,
+  ]);
+
+  return { effectiveColumns, storeKey };
+};
@@ -0,0 +1,27 @@
+"use client";
+
+import { useParams } from "next/navigation";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import type { MRT_RowData, MRT_TableOptions } from "mantine-react-table";
+import { useMantineReactTable } from "mantine-react-table";
+
+import type { SupportedLanguage } from "@homarr/translation";
+import { localeConfigurations } from "@homarr/translation";
+
+export const useTranslatedMantineReactTable = <TData extends MRT_RowData>(
+  tableOptions: Omit<MRT_TableOptions<TData>, "localization">,
+) => {
+  const { locale } = useParams<{ locale: SupportedLanguage }>();
+  const { data: mantineReactTable } = useSuspenseQuery({
+    queryKey: ["mantine-react-table-locale", locale],
+    // eslint-disable-next-line no-restricted-syntax
+    queryFn: async () => {
+      return await localeConfigurations[locale].importMrtLocalization();
+    },
+  });
+
+  return useMantineReactTable<TData>({
+    ...tableOptions,
+    localization: mantineReactTable,
+  });
+};