feat: size widgets before adding

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -203,6 +203,8 @@ In the modal you can edit the app that you want to display:
   </figcaption>
 </figure>
 
+When adding a widget, set its initial grid width and height directly in the preview. These size controls are only shown before the widget is added.
+
 As soon as you save your changes, the tile on the board will refresh and display your app.
 Resize from any visible edge or corner handle. For a Container, activate its top-left grip before using its resize handles.
 Press and hold a handle, move the pointer, and release it when the tile has the size you want.

apps/nextjs/src/components/board/items/item-select-modal.tsx

@@ -30,6 +30,7 @@ import {
   getIntegrationName,
   getWidgetName,
   getRootSectionLane,
+  widgetDefaultSizes,
   widgetIntegrationSupport,
   widgetKinds,
   widgetKindsWithOptionalIntegrations,
@@ -47,6 +48,7 @@ import { loadWidgetDefinition, reduceWidgetOptionsWithDefinition } from "@homarr
 import type { EmptySection } from "~/app/[locale]/boards/_types";
 import { useSetupAnalytics } from "~/components/create/setup-analytics";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
+import { getSectionGridColumnCount } from "../sections/grid/section-grid-placements";
 import { useItemActions } from "./item-actions";
 import type { WidgetConnectionStatus } from "./item-select-data";
 import {
@@ -76,6 +78,8 @@ export interface WidgetItemData {
 }
 
 const selectGridCols = { base: 1, xs: 2, sm: 2, md: 3, lg: 4 };
+const defaultWidgetSize = { width: 1, height: 1 };
+const maximumWidgetHeight = 64;
 
 const ItemSelectModalContent = ({
   actions,
@@ -124,6 +128,13 @@ const ItemSelectModalContent = ({
   const effectiveSectionId = placementOptions.some(({ value }) => value === targetSectionId)
     ? targetSectionId
     : (placementOptions[0]?.value ?? null);
+  const maximumWidgetSize = useMemo(() => {
+    if (!effectiveSectionId) return defaultWidgetSize;
+    return {
+      width: Math.max(1, getSectionGridColumnCount(board, currentLayoutId, effectiveSectionId) ?? 1),
+      height: maximumWidgetHeight,
+    };
+  }, [board, currentLayoutId, effectiveSectionId]);
 
   const [loadingSelection, setLoadingSelection] = useState<string | null>(null);
   const selectionLock = useRef(false);
@@ -246,6 +257,7 @@ const ItemSelectModalContent = ({
     try {
       const definition = await loadWidgetDefinition("customApi");
       const itemId = createId();
+      const initialSize = widgetDefaultSizes.customApi ?? defaultWidgetSize;
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
       const options = {
         ...defaultOptions,
@@ -263,7 +275,7 @@ const ItemSelectModalContent = ({
             options,
             integrationIds: [],
           },
-          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }) => {
+          onSuccessfulEdit: ({ options: configuredOptions, advancedOptions }, selectedSize) => {
             const updatedBoard = createItem({
               id: itemId,
               kind: "customApi",
@@ -271,12 +283,14 @@ const ItemSelectModalContent = ({
               options: configuredOptions,
               targetSectionId: effectiveSectionId ?? undefined,
               advancedOptions,
+              size: selectedSize ?? initialSize,
             });
             notifyCreated(updatedBoard, itemId, customWidgetDefinition.name);
           },
           integrationData: [],
           integrationSupport: false,
           settings,
+          previewResize: { initialSize, maximumSize: maximumWidgetSize },
         },
         {
           title: (titleT) => `${titleT("item.edit.title")} - ${customWidgetDefinition.name}`,
@@ -311,6 +325,7 @@ const ItemSelectModalContent = ({
       const matchingIntegrationCount = Math.min(matchingIntegrations.length, maxIntegrations);
       const itemId = createId();
       const defaultOptions = reduceWidgetOptionsWithDefinition(definition, settings);
+      const initialSize = widgetDefaultSizes[kind] ?? defaultWidgetSize;
       const openEditor = (
         availableIntegrations: { id: string; name: string; url: string; kind: IntegrationKind }[],
       ) => {
@@ -326,7 +341,7 @@ const ItemSelectModalContent = ({
               options: defaultOptions,
               integrationIds: selectedIntegrationIds,
             },
-            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }) => {
+            onSuccessfulEdit: ({ options, integrationIds: newIntegrationIds, advancedOptions }, selectedSize) => {
               const updatedBoard = createItem({
                 id: itemId,
                 kind,
@@ -334,6 +349,7 @@ const ItemSelectModalContent = ({
                 integrationIds: newIntegrationIds,
                 targetSectionId: effectiveSectionId ?? undefined,
                 advancedOptions,
+                size: selectedSize ?? initialSize,
               });
               if (!notifyCreated(updatedBoard, itemId, getWidgetName(kind, t))) return;
               trackSetup("widget-completed", {
@@ -346,6 +362,7 @@ const ItemSelectModalContent = ({
             integrationData: availableIntegrations,
             integrationSupport: hasIntegrationSupport,
             settings,
+            previewResize: { initialSize, maximumSize: maximumWidgetSize },
           },
           {
             title: (titleT) => `${titleT("item.edit.title")} - ${getWidgetName(kind, titleT)}`,

apps/nextjs/src/components/board/items/lazy-widget-edit-modal.tsx

@@ -12,7 +12,7 @@ import { widgetDefaultSizes } from "@homarr/definitions";
 import { createModal, useModalAction } from "@homarr/modals";
 import { WidgetError } from "@homarr/widgets/errors";
 import type * as WidgetModalsModule from "@homarr/widgets/modals";
-import type { WidgetEditModalProps } from "@homarr/widgets/modals";
+import type { WidgetEditModalProps, WidgetEditModalSize } from "@homarr/widgets/modals";
 import { loadWidgetComponent } from "@homarr/widgets/manifest";
 import type { IntegrationSelectOption } from "@homarr/widgets/widget-integration-select";
 
@@ -26,6 +26,10 @@ const defaultWidgetSize = { width: 1, height: 1 };
 const ignoreAssistantAction = () => undefined;
 const ignoreAssistantPrompt = () => false;
 const ignoreAssistantRefresh = () => Promise.resolve();
+const getPreviewDimensions = (size: WidgetEditModalSize) => ({
+  width: getLogicalTrackSize(size.width),
+  height: getLogicalTrackSize(size.height),
+});
 
 const PreviewRuntimeWrapper = ({ children }: PropsWithChildren) => {
   const assistant = useOptionalHomarrAssistant();
@@ -153,6 +157,10 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
       height: getLogicalTrackSize(size.height),
     };
   }, [props.innerProps.kind, props.innerProps.previewDimensions]);
+  let previewResize = props.innerProps.previewResize;
+  if (previewResize) {
+    previewResize = { ...previewResize, getDimensions: getPreviewDimensions };
+  }
 
   return (
     <Component
@@ -163,6 +171,7 @@ const LazyWidgetEditModalContent = (props: LazyWidgetEditModalContentProps) => {
         integrationEditForm: LazyIntegrationEditForm,
         previewComponent: PreviewComponent,
         previewDimensions,
+        previewResize,
         previewWrapper: PreviewRuntimeWrapper,
         onOpenNewIntegration: supportedKinds.length > 0 ? handleOpenNewIntegration : undefined,
       }}