Merge branch 'dev' into feat/widget-overlay

Apply full border-radius to hover overlay panel instead of bottom-only,
and add media query to hide the overlay on screens <= 768px since hover
is not available on touch devices.

apps/nextjs/src/components/board/items/widget-hover-metadata.ts

@@ -0,0 +1,155 @@
+import { objectEntries } from "@homarr/common";
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import type { SettingsContextProps } from "@homarr/settings/creator";
+import type { WidgetOptionDefinition, WidgetOptionType } from "@homarr/widgets";
+import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
+
+import type { SectionItem } from "~/app/[locale]/boards/_types";
+
+export type Translator = {
+  (key: string): string;
+};
+
+export interface HoverMetadataItem {
+  label: string;
+  value: string;
+}
+
+const maxMetadataItems = 3;
+
+const skippedOptionTypes: Partial<Record<WidgetOptionType, true>> = {
+  app: true,
+  anchorNote: true,
+  dynamicSelect: true,
+  sortableItemList: true,
+  multiReleasesRepositories: true,
+  umamiEventName: true,
+  umamiEventNames: true,
+  umamiWebsite: true,
+};
+
+const isEqualValue = (left: unknown, right: unknown) => JSON.stringify(left) === JSON.stringify(right);
+
+type OptionDefinitionWithRules = WidgetOptionDefinition & {
+  shouldHide?: (options: never, integrationKinds: IntegrationKind[]) => boolean;
+  options?: readonly { value: unknown; label: unknown }[];
+};
+
+type OptionFormatter = (value: unknown, definition: OptionDefinitionWithRules, t: Translator) => string | null;
+
+const resolveSelectLabel = (value: unknown, definition: OptionDefinitionWithRules, t: Translator) => {
+  const match = definition.options?.find((option) => option.value === value);
+  const label = match?.label;
+  const fallbackLabel = () => String(value);
+  const labelResolvers: Record<string, () => string> = {
+    function: () => (label as (translator: Translator) => string)(t),
+    string: () => label as string,
+    missing: fallbackLabel,
+  };
+  const labelType = typeof label;
+  const resolveLabel: () => string = labelResolvers[labelType] ?? fallbackLabel;
+  return resolveLabel();
+};
+
+const optionTypeFormatters: Partial<Record<WidgetOptionType, OptionFormatter>> = {
+  switch: (value, _, t) => {
+    const switchLabels: Record<string, string> = {
+      true: t("common.action.show"),
+      false: t("common.action.hide"),
+    };
+    return switchLabels[String(Boolean(value))] ?? null;
+  },
+  text: (value) => {
+    const text = String(value).trim();
+    return text.length > 0 ? text : null;
+  },
+  number: (value) => String(value),
+  slider: (value) => String(value),
+  select: (value, definition, t) => resolveSelectLabel(value, definition, t),
+  multiSelect: (value) => {
+    const items = value as unknown[];
+    return items.length > 0 ? String(items.length) : null;
+  },
+  multiText: (value) => {
+    const items = (value as string[]).filter((entry) => entry.trim().length > 0);
+    return items.length > 0 ? items.join(", ") : null;
+  },
+  location: (value) => {
+    const location = value as { name?: string };
+    const name = location.name?.trim() ?? "";
+    return name.length > 0 ? name : null;
+  },
+};
+
+const formatOptionValue = (
+  type: WidgetOptionType,
+  value: unknown,
+  definition: OptionDefinitionWithRules,
+  t: Translator,
+) => {
+  const formatter = optionTypeFormatters[type];
+  return formatter?.(value, definition, t) ?? null;
+};
+
+const getOptionLabel = (kind: WidgetKind, key: string, t: Translator) => {
+  const labelKey = `widget.${kind}.option.${key}.label`;
+  const translated = t(labelKey);
+  return translated === labelKey ? key : translated;
+};
+
+export const collectWidgetHoverMetadata = (
+  item: SectionItem,
+  settings: Pick<SettingsContextProps, "enableStatusByDefault" | "forceDisableStatus">,
+  integrationKinds: IntegrationKind[],
+  t: Translator,
+): HoverMetadataItem[] => {
+  const { definition } = widgetImports[item.kind];
+  const optionDefinitions = definition.createOptions(settings) as Record<string, OptionDefinitionWithRules>;
+  const resolvedOptions = reduceWidgetOptionsWithDefaultValues(item.kind, settings, item.options);
+
+  return objectEntries(optionDefinitions)
+    .filter(([key, optionDefinition]) => {
+      const skip = skippedOptionTypes[optionDefinition.type];
+      const hidden = optionDefinition.shouldHide?.(resolvedOptions as never, integrationKinds);
+      const unchanged = isEqualValue(resolvedOptions[key], optionDefinition.defaultValue);
+      return !skip && !hidden && !unchanged;
+    })
+    .map(([key, optionDefinition]) => {
+      const formattedValue = formatOptionValue(optionDefinition.type, resolvedOptions[key], optionDefinition, t);
+      return {
+        label: getOptionLabel(item.kind, key, t),
+        value: formattedValue ?? "",
+      };
+    })
+    .filter((entry) => entry.value.length > 0)
+    .slice(0, maxMetadataItems);
+};
+
+interface DisplayNameSource {
+  matches: (item: SectionItem, options: Record<string, unknown>) => boolean;
+  resolve: (item: SectionItem, options: Record<string, unknown>) => string;
+}
+
+const displayNameSources: DisplayNameSource[] = [
+  {
+    matches: (item) => Boolean(item.advancedOptions.title?.trim()),
+    resolve: (item) => item.advancedOptions.title?.trim() ?? "",
+  },
+  {
+    matches: (item, options) =>
+      item.kind === "clock" &&
+      Boolean(options.customTitleToggle) &&
+      String(options.customTitle ?? "").trim().length > 0,
+    resolve: (_, options) => String(options.customTitle).trim(),
+  },
+];
+
+export const resolveWidgetDisplayName = (
+  item: SectionItem,
+  settings: Pick<SettingsContextProps, "enableStatusByDefault" | "forceDisableStatus">,
+  t: Translator,
+) => {
+  const resolvedOptions = reduceWidgetOptionsWithDefaultValues(item.kind, settings, item.options);
+  const source = displayNameSources.find((entry) => entry.matches(item, resolvedOptions));
+  return source?.resolve(item, resolvedOptions) ?? t(`widget.${item.kind}.name`);
+};

apps/nextjs/src/components/board/items/widget-hover-overlay.module.css

@@ -0,0 +1,116 @@
+.wrapper {
+  position: absolute;
+  left: 10px;
+  right: 10px;
+  bottom: calc(100% - 10px);
+  margin-bottom: 1px;
+  z-index: 200;
+  pointer-events: auto;
+  opacity: 0;
+  transform: translateY(6px);
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease;
+}
+
+:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):hover) .wrapper,
+:global(.grid-stack-item[data-type="item"]:not([data-kind="app"]):focus-within) .wrapper {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.panel {
+  @mixin dark {
+    --background-color: rgb(from var(--mantine-color-dark-7) r g b / 0.96);
+    --border-color: rgb(from var(--mantine-color-dark-4) r g b / 0.9);
+  }
+  @mixin light {
+    --background-color: rgb(from var(--mantine-color-white) r g b / 0.96);
+    --border-color: rgb(from var(--mantine-color-gray-3) r g b / 0.9);
+  }
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 28px;
+  padding: 4px 8px;
+  border: 1px solid var(--border-color);
+  border-radius: var(--mantine-radius-md);
+  background-color: var(--background-color);
+  box-shadow: 0 4px 16px rgb(0 0 0 / 0.12);
+  backdrop-filter: blur(8px);
+  overflow: hidden;
+}
+
+.nameSection {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  flex-shrink: 0;
+}
+
+.widgetIcon {
+  flex-shrink: 0;
+  color: var(--mantine-color-dimmed);
+}
+
+.name {
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1.2;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.integrations {
+  flex-shrink: 0;
+}
+
+.integrationAvatar {
+  border: none;
+}
+
+.metadata {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  margin-left: auto;
+}
+
+.metadataItem {
+  @mixin dark {
+    --chip-background: rgb(from var(--mantine-color-dark-5) r g b / 0.9);
+  }
+  @mixin light {
+    --chip-background: rgb(from var(--mantine-color-gray-1) r g b / 0.95);
+  }
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 140px;
+  padding: 2px 6px;
+  border-radius: var(--mantine-radius-md);
+  background-color: var(--chip-background);
+  font-size: 10px;
+  line-height: 1.2;
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.metadataLabel {
+  color: var(--mantine-color-dimmed);
+  flex-shrink: 0;
+}
+
+.metadataValue {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+@media (max-width: 768px) {
+  .wrapper {
+    display: none;
+  }
+}

apps/nextjs/src/components/board/items/widget-hover-overlay.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { Avatar, Group, Text, Tooltip } from "@mantine/core";
+
+import type { RouterOutputs } from "@homarr/api";
+import { useEditMode } from "@homarr/boards/edit-mode";
+import { getIconUrl } from "@homarr/definitions";
+import { useSettings } from "@homarr/settings";
+import { useI18n } from "@homarr/translation/client";
+import { widgetImports } from "@homarr/widgets";
+
+import type { SectionItem } from "~/app/[locale]/boards/_types";
+import type { Translator } from "./widget-hover-metadata";
+import { collectWidgetHoverMetadata, resolveWidgetDisplayName } from "./widget-hover-metadata";
+import classes from "./widget-hover-overlay.module.css";
+
+interface WidgetHoverOverlayProps {
+  item: SectionItem;
+  integrations: RouterOutputs["integration"]["all"] | undefined;
+}
+
+export const WidgetHoverOverlay = ({ item, integrations }: WidgetHoverOverlayProps) => {
+  const [isEditMode] = useEditMode();
+  const settings = useSettings();
+  const t = useI18n();
+  const { definition } = widgetImports[item.kind];
+  const WidgetIcon = definition.icon;
+
+  const translate = ((key: string) => t(key as never)) as Translator;
+  const displayName = resolveWidgetDisplayName(item, settings, translate);
+
+  const connectedIntegrations = (integrations ?? []).filter((integration) =>
+    item.integrationIds.includes(integration.id),
+  );
+  const metadataItems = collectWidgetHoverMetadata(
+    item,
+    settings,
+    connectedIntegrations.map((integration) => integration.kind),
+    translate,
+  );
+  const hasIntegrations = connectedIntegrations.length > 0;
+  const hasMetadata = metadataItems.length > 0;
+
+  if (isEditMode) {
+    return null;
+  }
+
+  return (
+    <div className={classes.wrapper}>
+      <div className={classes.panel}>
+        <div className={classes.nameSection}>
+          <WidgetIcon size={14} stroke={1.75} className={classes.widgetIcon} />
+          <Text className={classes.name} title={displayName}>
+            {displayName}
+          </Text>
+        </div>
+
+        {hasIntegrations && (
+          <Avatar.Group spacing="xs" className={classes.integrations}>
+            {connectedIntegrations.map((integration) => (
+              <Tooltip key={integration.id} label={integration.name} withArrow position="top">
+                <Avatar
+                  src={getIconUrl(integration.kind)}
+                  size={20}
+                  radius="sm"
+                  className={classes.integrationAvatar}
+                />
+              </Tooltip>
+            ))}
+          </Avatar.Group>
+        )}
+
+        {hasMetadata && (
+          <Group className={classes.metadata} gap={4}>
+            {metadataItems.map((metadataItem) => (
+              <div key={`${metadataItem.label}-${metadataItem.value}`} className={classes.metadataItem}>
+                <span className={classes.metadataLabel}>{metadataItem.label}</span>
+                <span className={classes.metadataValue}>{metadataItem.value}</span>
+              </div>
+            ))}
+          </Group>
+        )}
+      </div>
+    </div>
+  );
+};

apps/nextjs/src/components/board/sections/content.tsx

@@ -2,8 +2,12 @@ import { useMemo } from "react";
 
 import type { GridItemHTMLElement } from "@homarr/gridstack";
 
+import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+
 import type { DynamicSectionItem, SectionItem } from "~/app/[locale]/boards/_types";
 import { BoardItemContent } from "../items/item-content";
+import { WidgetHoverOverlay } from "../items/widget-hover-overlay";
 import { BoardDynamicSection } from "./dynamic-section";
 import { GridStackItem } from "./gridstack/gridstack-item";
 import { useSectionContext } from "./section-context";
@@ -11,6 +15,7 @@ import { useSectionItems } from "./use-section-items";
 
 export const SectionContent = () => {
   const { innerSections, items, refs } = useSectionContext();
+  const { data: integrations } = clientApi.integration.all.useQuery();
 
   /**
    * IMPORTANT: THE ORDER OF THE BELOW ITEMS HAS TO MATCH THE ORDER OF
@@ -18,7 +23,7 @@ export const SectionContent = () => {
    * @see https://github.com/homarr-labs/homarr/pull/1770
    */
   const sortedItems = useMemo(() => {
-    return [...items, ...innerSections].sort((itemA, itemB) => {
+    return [...items, ...innerSections].toSorted((itemA, itemB) => {
       if (itemA.yOffset === itemB.yOffset) {
         return itemA.xOffset - itemB.xOffset;
       }
@@ -30,7 +35,7 @@ export const SectionContent = () => {
   return (
     <>
       {sortedItems.map((item) => (
-        <Item key={item.id} item={item} innerRef={refs.items.current[item.id]} />
+        <Item key={item.id} item={item} innerRef={refs.items.current[item.id]} integrations={integrations} />
       ))}
     </>
   );
@@ -39,12 +44,12 @@ export const SectionContent = () => {
 interface ItemProps {
   item: DynamicSectionItem | SectionItem;
   innerRef: React.RefObject<GridItemHTMLElement | null> | undefined;
+  integrations: RouterOutputs["integration"]["all"] | undefined;
 }
 
-const Item = ({ item, innerRef }: ItemProps) => {
+const Item = ({ item, innerRef, integrations }: ItemProps) => {
   const minWidth = useMinSize(item, "x");
   const minHeight = useMinSize(item, "y");
-
   return (
     <GridStackItem
       key={item.id}
@@ -59,6 +64,7 @@ const Item = ({ item, innerRef }: ItemProps) => {
       minWidth={minWidth}
       minHeight={minHeight}
     >
+      {item.type === "item" && item.kind !== "app" && <WidgetHoverOverlay item={item} integrations={integrations} />}
       {item.type === "item" ? <BoardItemContent item={item} /> : <BoardDynamicSection section={item} />}
     </GridStackItem>
   );

apps/nextjs/src/styles/gridstack.scss

@@ -102,6 +102,10 @@
   overflow-y: auto;
 }
 
+.grid-stack > .grid-stack-item[data-type="item"] {
+  overflow: visible;
+}
+
 .grid-stack.grid-stack-animate {
   transition: none;
 }

packages/widgets/src/index.tsx

@@ -53,6 +53,7 @@ import * as weather from "./weather";
 
 export type { WidgetDefinition, WidgetOptionsSettings } from "./definition";
 export type { WidgetComponentProps };
+export type { WidgetOptionDefinition, WidgetOptionType } from "./options";
 
 export const widgetImports = {
   clock,