feat: add widget server loader (#16)

* wip: Add gridstack board

* wip: Centralize board pages, Add board settings page

* fix: remove cyclic dependency and rename widget-sort to kind

* improve: Add header actions as parallel route

* feat: add item select modal, add category edit modal,

* feat: add edit item modal

* feat: add remove item modal

* wip: add category actions

* feat: add saving of board, wip: add app widget

* Merge branch 'main' into add-board

* chore: update turbo dependencies

* chore: update mantine dependencies

* chore: fix typescript errors, lint and format

* feat: add confirm modal to category removal, move items of removed category to above wrapper

* feat: remove app widget to continue in another branch

* feat: add loading spinner until board is initialized

* fix: issue with cellheight of gridstack items

* feat: add translations for board

* fix: issue with translation for settings page

* feat: add widget server loader

* fix: typing issue

* chore: address pull request feedback

* fix: formatting

apps/nextjs/src/app/[locale]/boards/_creator.tsx

@@ -13,6 +13,8 @@ import type { Board } from "./_types";
 // This is placed here because it's used in the layout and the page and because it's here it's not needed to load it everywhere
 import "../../../styles/gridstack.scss";
 
+import { GlobalItemServerDataRunner } from "@homarr/widgets";
+
 type Params = Record<string, unknown>;
 
 interface Props<TParams extends Params> {
@@ -31,16 +33,18 @@ export const createBoardPage = <TParams extends Record<string, unknown>>({
       const initialBoard = await getInitialBoard(params);
 
       return (
-        <BoardProvider initialBoard={initialBoard}>
+        <GlobalItemServerDataRunner board={initialBoard}>
-          <ClientShell hasNavigation={false}>
+          <BoardProvider initialBoard={initialBoard}>
-            <MainHeader
+            <ClientShell hasNavigation={false}>
-              logo={<BoardLogoWithTitle size="md" />}
+              <MainHeader
-              actions={headeractions}
+                logo={<BoardLogoWithTitle size="md" />}
-              hasNavigation={false}
+                actions={headeractions}
-            />
+                hasNavigation={false}
-            <AppShellMain>{children}</AppShellMain>
+              />
-          </ClientShell>
+              <AppShellMain>{children}</AppShellMain>
-        </BoardProvider>
+            </ClientShell>
+          </BoardProvider>
+        </GlobalItemServerDataRunner>
       );
     },
     page: () => {

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

@@ -17,6 +17,7 @@ import {
 import {
   loadWidgetDynamic,
   reduceWidgetOptionsWithDefaultValues,
+  useServerDataFor,
 } from "@homarr/widgets";
 
 import type { Item } from "~/app/[locale]/boards/_types";
@@ -62,13 +63,21 @@ interface ItemProps {
 }
 
 const BoardItem = ({ item }: ItemProps) => {
+  const serverData = useServerDataFor(item.id);
   const Comp = loadWidgetDynamic(item.kind);
   const options = reduceWidgetOptionsWithDefaultValues(item.kind, item.options);
   const newItem = { ...item, options };
+
+  if (!serverData?.isReady) return null;
+
   return (
     <>
       <ItemMenu offset={8} item={newItem} />
-      <Comp options={options as never} integrations={item.integrations} />
+      <Comp
+        options={options as never}
+        integrations={item.integrations}
+        serverData={serverData?.data as never}
+      />
     </>
   );
 };

packages/widgets/src/clock/component.tsx

@@ -3,6 +3,7 @@ import type { WidgetComponentProps } from "../definition";
 export default function ClockWidget({
   options: _options,
   integrations: _integrations,
+  serverData: _serverData,
 }: WidgetComponentProps<"clock">) {
   return <div>CLOCK</div>;
 }

packages/widgets/src/clock/index.ts

@@ -1,27 +1,30 @@
 import { IconClock } from "@homarr/ui";
 
 import { createWidgetDefinition } from "../definition";
-import { opt } from "../options";
+import { optionsBuilder } from "../options";
 
-export const { definition, componentLoader } = createWidgetDefinition("clock", {
+export const { definition, componentLoader, serverDataLoader } =
-  icon: IconClock,
+  createWidgetDefinition("clock", {
-  supportedIntegrations: ["adGuardHome", "piHole"],
+    icon: IconClock,
-  options: opt.from(
+    supportedIntegrations: ["adGuardHome", "piHole"],
-    (fac) => ({
+    options: optionsBuilder.from(
-      is24HourFormat: fac.switch({
+      (factory) => ({
-        defaultValue: true,
+        is24HourFormat: factory.switch({
-        withDescription: true,
+          defaultValue: true,
+          withDescription: true,
+        }),
+        isLocaleTime: factory.switch({ defaultValue: true }),
+        timezone: factory.select({
+          options: ["Europe/Berlin", "Europe/London", "Europe/Moscow"] as const,
+          defaultValue: "Europe/Berlin",
+        }),
       }),
-      isLocaleTime: fac.switch({ defaultValue: true }),
+      {
-      timezone: fac.select({
+        timezone: {
-        options: ["Europe/Berlin", "Europe/London", "Europe/Moscow"] as const,
+          shouldHide: (options) => options.isLocaleTime,
-        defaultValue: "Europe/Berlin",
+        },
-      }),
-    }),
-    {
-      timezone: {
-        shouldHide: (options) => options.isLocaleTime,
       },
-    },
+    ),
-  ),
+  })
-}).withDynamicImport(() => import("./component"));
+    .withServerData(() => import("./serverData"))
+    .withDynamicImport(() => import("./component"));

packages/widgets/src/clock/serverData.ts

@@ -0,0 +1,10 @@
+"use server";
+
+import { db } from "../../../db";
+import type { WidgetProps } from "../definition";
+
+export default async function getServerData(_item: WidgetProps<"clock">) {
+  const randomUuid = crypto.randomUUID();
+  const data = await db.query.items.findMany();
+  return { data, count: data.length, randomUuid };
+}

packages/widgets/src/definition.ts

@@ -10,6 +10,62 @@ import type {
 } from "./options";
 import type { IntegrationSelectOption } from "./widget-integration-select";
 
+type ServerDataLoader<TKind extends WidgetKind> = () => Promise<{
+  default: (props: WidgetProps<TKind>) => Promise<Record<string, unknown>>;
+}>;
+
+const createWithDynamicImport =
+  <
+    TKind extends WidgetKind,
+    TDefinition extends WidgetDefinition,
+    TServerDataLoader extends ServerDataLoader<TKind> | undefined,
+  >(
+    kind: TKind,
+    definition: TDefinition,
+    serverDataLoader: TServerDataLoader,
+  ) =>
+  (
+    componentLoader: () => LoaderComponent<
+      WidgetComponentProps<TKind> &
+        (TServerDataLoader extends ServerDataLoader<TKind>
+          ? {
+              serverData: Awaited<
+                ReturnType<Awaited<ReturnType<TServerDataLoader>>["default"]>
+              >;
+            }
+          : never)
+    >,
+  ) => ({
+    definition: {
+      ...definition,
+      kind,
+    },
+    kind,
+    serverDataLoader,
+    componentLoader,
+  });
+
+const createWithServerData =
+  <TKind extends WidgetKind, TDefinition extends WidgetDefinition>(
+    kind: TKind,
+    definition: TDefinition,
+  ) =>
+  <TServerDataLoader extends ServerDataLoader<TKind>>(
+    serverDataLoader: TServerDataLoader,
+  ) => ({
+    definition: {
+      ...definition,
+      kind,
+    },
+    kind,
+    serverDataLoader,
+    withDynamicImport: createWithDynamicImport(
+      kind,
+      definition,
+      serverDataLoader,
+    ),
+  });
+
 export const createWidgetDefinition = <
   TKind extends WidgetKind,
   TDefinition extends WidgetDefinition,
@@ -17,15 +73,8 @@ export const createWidgetDefinition = <
   kind: TKind,
   definition: TDefinition,
 ) => ({
-  withDynamicImport: (
+  withServerData: createWithServerData(kind, definition),
-    componentLoader: () => LoaderComponent<WidgetComponentProps<TKind>>,
+  withDynamicImport: createWithDynamicImport(kind, definition, undefined),
-  ) => ({
-    definition: {
-      kind,
-      ...definition,
-    },
-    componentLoader,
-  }),
 });
 
 export interface WidgetDefinition {
@@ -34,13 +83,29 @@ export interface WidgetDefinition {
   options: WidgetOptionsRecord;
 }
 
-export interface WidgetComponentProps<TKind extends WidgetKind> {
+export interface WidgetProps<TKind extends WidgetKind> {
   options: inferOptionsFromDefinition<WidgetOptionsRecordOf<TKind>>;
   integrations: inferIntegrationsFromDefinition<
     WidgetImports[TKind]["definition"]
   >;
 }
 
+type inferServerDataForKind<TKind extends WidgetKind> =
+  WidgetImports[TKind] extends { serverDataLoader: ServerDataLoader<TKind> }
+    ? Awaited<
+        ReturnType<
+          Awaited<
+            ReturnType<WidgetImports[TKind]["serverDataLoader"]>
+          >["default"]
+        >
+      >
+    : undefined;
+
+export type WidgetComponentProps<TKind extends WidgetKind> =
+  WidgetProps<TKind> & {
+    serverData?: inferServerDataForKind<TKind>;
+  };
+
 type inferIntegrationsFromDefinition<TDefinition extends WidgetDefinition> =
   TDefinition extends {
     supportedIntegrations: infer TSupportedIntegrations;

packages/widgets/src/index.tsx

@@ -13,6 +13,8 @@ import * as weather from "./weather";
 export { reduceWidgetOptionsWithDefaultValues } from "./options";
 
 export { WidgetEditModal } from "./modals/widget-edit-modal";
+export { GlobalItemServerDataRunner } from "./server/runner";
+export { useServerDataFor } from "./server/provider";
 
 export const widgetImports = {
   clock,

packages/widgets/src/options.ts

@@ -141,7 +141,7 @@ const createOptions = <TOptions extends WidgetOptionsRecord>(
   };
 };
 
-export const opt = {
+export const optionsBuilder = {
   from: createOptions,
 };
 

packages/widgets/src/server/client.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import { useServerDataInitializer } from "./provider";
+
+interface Props {
+  id: string;
+  serverData: Record<string, unknown> | undefined;
+}
+
+export const ClientServerDataInitalizer = ({ id, serverData }: Props) => {
+  useServerDataInitializer(id, serverData);
+  return null;
+};

packages/widgets/src/server/provider.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { createContext, useContext, useEffect, useState } from "react";
+
+type Data = Record<
+  string,
+  {
+    data: Record<string, unknown> | undefined;
+    isReady: boolean;
+  }
+>;
+
+interface GlobalItemServerDataContext {
+  setItemServerData: (
+    id: string,
+    data: Record<string, unknown> | undefined,
+  ) => void;
+  data: Data;
+  initalItemIds: string[];
+}
+
+const GlobalItemServerDataContext =
+  createContext<GlobalItemServerDataContext | null>(null);
+
+interface Props {
+  initalItemIds: string[];
+}
+
+export const GlobalItemServerDataProvider = ({
+  children,
+  initalItemIds,
+}: PropsWithChildren<Props>) => {
+  const [data, setData] = useState<Data>({});
+
+  const setItemServerData = (
+    id: string,
+    itemData: Record<string, unknown> | undefined,
+  ) => {
+    setData((prev) => ({
+      ...prev,
+      [id]: {
+        data: itemData,
+        isReady: true,
+      },
+    }));
+  };
+
+  return (
+    <GlobalItemServerDataContext.Provider
+      value={{ setItemServerData, data, initalItemIds }}
+    >
+      {children}
+    </GlobalItemServerDataContext.Provider>
+  );
+};
+
+export const useServerDataFor = (id: string) => {
+  const context = useContext(GlobalItemServerDataContext);
+
+  if (!context) {
+    throw new Error("GlobalItemServerDataProvider is required");
+  }
+
+  // When the item is not in the initial list, it means the data can not come from the server
+  if (!context.initalItemIds.includes(id)) {
+    return {
+      data: undefined,
+      isReady: true,
+    };
+  }
+
+  return context.data[id];
+};
+
+export const useServerDataInitializer = (
+  id: string,
+  serverData: Record<string, unknown> | undefined,
+) => {
+  const context = useContext(GlobalItemServerDataContext);
+
+  if (!context) {
+    throw new Error("GlobalItemServerDataProvider is required");
+  }
+
+  useEffect(() => {
+    context.setItemServerData(id, serverData);
+  }, []);
+};

packages/widgets/src/server/runner.tsx

@@ -0,0 +1,43 @@
+import type { PropsWithChildren } from "react";
+import { Suspense } from "react";
+
+import type { RouterOutputs } from "@homarr/api";
+
+import { widgetImports } from "..";
+import { ClientServerDataInitalizer } from "./client";
+import { GlobalItemServerDataProvider } from "./provider";
+
+type Board = RouterOutputs["board"]["default"];
+
+type Props = PropsWithChildren<{
+  board: Board;
+}>;
+
+export const GlobalItemServerDataRunner = ({ board, children }: Props) => {
+  const allItems = board.sections.flatMap((section) => section.items);
+
+  return (
+    <GlobalItemServerDataProvider initalItemIds={allItems.map(({ id }) => id)}>
+      {allItems.map((item) => (
+        <Suspense key={item.id}>
+          <ItemDataLoader item={item} />
+        </Suspense>
+      ))}
+      {children}
+    </GlobalItemServerDataProvider>
+  );
+};
+
+interface ItemDataLoaderProps {
+  item: Board["sections"][number]["items"][number];
+}
+
+const ItemDataLoader = async ({ item }: ItemDataLoaderProps) => {
+  const widgetImport = widgetImports[item.kind];
+  if (!("serverDataLoader" in widgetImport)) {
+    return <ClientServerDataInitalizer id={item.id} serverData={undefined} />;
+  }
+  const loader = await widgetImport.serverDataLoader();
+  const data = await loader.default(item as never);
+  return <ClientServerDataInitalizer id={item.id} serverData={data} />;
+};

packages/widgets/src/weather/index.ts

@@ -1,15 +1,15 @@
 import { IconCloud } from "@homarr/ui";
 
 import { createWidgetDefinition } from "../definition";
-import { opt } from "../options";
+import { optionsBuilder } from "../options";
 
 export const { definition, componentLoader } = createWidgetDefinition(
   "weather",
   {
     icon: IconCloud,
-    options: opt.from((fac) => ({
+    options: optionsBuilder.from((factory) => ({
-      location: fac.location(),
+      location: factory.location(),
-      showCity: fac.switch(),
+      showCity: factory.switch(),
     })),
   },
 ).withDynamicImport(() => import("./component"));