feat: add automatic mobile board layout

apps/docs/docs/management/boards/index.mdx

@@ -12,8 +12,6 @@ tags:
 import iconColorImage from './img/icon-color.png'
 import itemRadiusImage from './img/item-radius.png'
 import layoutLargeImage from './img/layout-large.png'
-import layoutMediumImage from './img/layout-medium.png'
-import layoutSmallImage from './img/layout-small.png'
 
 Each dashboard is called a "board".
 You can create as many boards as you want.
@@ -76,32 +74,18 @@ Homarr will fall back to the Homarr logo if nothing is set.
 
 ### Layout
 
-In this section you can configure the different responsive layouts. Depending on your screens width the layout will change.
+In this section you can configure the number of columns in the desktop layout.
 
-![](./img/layout-settings.png)
+Items and sections can be moved and resized on desktop while the board is in edit mode.
+Changing the column count automatically adjusts item positions and sizes to fit the new grid.
 
-On each element the position and size of items can be changed seperately.
-When adding a new layout the position and sizes will automatically be generated depending on the column count.
-When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position.
+<img src={layoutLargeImage} height={256} />
 
-#### Name
+#### Mobile layout
 
-The name of the layout can be choosen freely. It is only used for the management and will not be visible on the board.
+Mobile boards use an automatic, read-only layout with two columns. Items follow the visual order of the desktop layout and are limited to two columns wide and three rows high.
 
-#### Column count
-
-Amount of columns for this layout. Defines how many items can be placed in a row. When changed it will automatically adjust the position and size of the items.
-
-#### Breakpoint
-
-Minimum width of the screen where the layout will be used. 
-Once the minmum of the next layout is reached the layout will change.
-
-#### Preview
-
-<img src={layoutSmallImage}  height={256} />
-<img src={layoutMediumImage}  height={256} />
-<img src={layoutLargeImage}  height={256} />
+Categories and dynamic sections are not displayed as containers on mobile. Their items are included directly in the automatic grid, even when a category is collapsed on desktop. To rearrange, add, remove, or resize board items, open the board on a larger screen.
 
 ### Background
 #### Background image URL
@@ -255,4 +239,4 @@ For the global home board you can only select boards that are public.
 ### Mobile home board
 
 Same as the home board, you can also set a mobile home board.
-It will be used for devices that are detected as mobile devices. (Using User-Agent header)
+It will be used for devices that are detected as mobile devices. (Using User-Agent header)

apps/nextjs/src/app/[locale]/boards/(content)/_client.tsx

@@ -4,30 +4,37 @@ import { Box, Stack } from "@mantine/core";
 
 import { useCurrentLayout, useRequiredBoard } from "@homarr/boards/context";
 
+import { MobileBoard } from "~/components/board/mobile/mobile-board";
 import { BoardCategorySection } from "~/components/board/sections/category-section";
 import { BoardEmptySection } from "~/components/board/sections/empty-section";
+import { useIsMobileBoard } from "~/components/board/use-mobile-board";
 import { BoardBackgroundVideo } from "~/components/layout/background";
 
 export const ClientBoard = () => {
   const board = useRequiredBoard();
   const currentLayoutId = useCurrentLayout();
+  const isMobile = useIsMobileBoard();
 
   const fullWidthSortedSections = board.sections
     .filter((section) => section.kind === "empty" || section.kind === "category")
-    .sort((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset);
+    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset);
 
   return (
     <Box h="100%" pos="relative">
       <BoardBackgroundVideo />
-      <Stack h="100%">
-        {fullWidthSortedSections.map((section) =>
-          section.kind === "empty" ? (
-            <BoardEmptySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ) : (
-            <BoardCategorySection key={`${currentLayoutId}-${section.id}`} section={section} />
-          ),
-        )}
-      </Stack>
+      {isMobile ? (
+        <MobileBoard />
+      ) : (
+        <Stack h="100%">
+          {fullWidthSortedSections.map((section) =>
+            section.kind === "empty" ? (
+              <BoardEmptySection key={`${currentLayoutId}-${section.id}`} section={section} />
+            ) : (
+              <BoardCategorySection key={`${currentLayoutId}-${section.id}`} section={section} />
+            ),
+          )}
+        </Stack>
+      )}
     </Box>
   );
 };

apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx

@@ -38,6 +38,7 @@ import { useBoardPermissions } from "~/components/board/permissions/client";
 import { useCategoryActions } from "~/components/board/sections/category/category-actions";
 import { CategoryEditModal } from "~/components/board/sections/category/category-edit-modal";
 import { useDynamicSectionActions } from "~/components/board/sections/dynamic/dynamic-actions";
+import { useIsMobileBoard } from "~/components/board/use-mobile-board";
 import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
 import { HeaderButton } from "~/components/layout/header/button";
 
@@ -45,6 +46,7 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
   const [isEditMode] = useEditMode();
   const board = useRequiredBoard();
   const { hasChangeAccess } = useBoardPermissions(board);
+  const isMobile = useIsMobileBoard();
 
   if (!hasChangeAccess) {
     return <SelectBoardsMenu />;
@@ -52,9 +54,9 @@ export const BoardContentHeaderActions = ({ demoReadOnly }: { demoReadOnly: bool
 
   return (
     <>
-      {isEditMode && <AddMenu />}
+      {isEditMode && !isMobile && <AddMenu />}
 
-      <EditModeMenu demoReadOnly={demoReadOnly} />
+      <EditModeMenu demoReadOnly={demoReadOnly} hidden={isMobile} />
 
       {!demoReadOnly && (
         <OnboardingTour.Target id="board-settings">
@@ -157,7 +159,7 @@ const AddMenu = () => {
   );
 };
 
-const EditModeMenu = ({ demoReadOnly }: { demoReadOnly: boolean }) => {
+const EditModeMenu = ({ demoReadOnly, hidden }: { demoReadOnly: boolean; hidden: boolean }) => {
   const [isEditMode, { open, close }] = useEditMode();
   const board = useRequiredBoard();
   const utils = clientApi.useUtils();
@@ -186,16 +188,19 @@ const EditModeMenu = ({ demoReadOnly }: { demoReadOnly: boolean }) => {
   }, [utils, board.name, close]);
 
   const toggle = useCallback(() => {
+    if (hidden) return;
     if (isEditMode) {
       if (demoReadOnly) return discardDemoChanges();
       return saveBoard(board);
     }
     open();
-  }, [board, isEditMode, demoReadOnly, saveBoard, open, discardDemoChanges]);
+  }, [board, isEditMode, demoReadOnly, saveBoard, open, discardDemoChanges, hidden]);
 
   useHotkeys([[hotkeys.toggleBoardEdit, toggle]]);
   usePreventLeaveWithDirty(isEditMode);
 
+  if (hidden) return null;
+
   return (
     <OnboardingTour.Target id="board-edit-mode">
       <HeaderButton onClick={toggle} loading={isPending}>

apps/nextjs/src/app/[locale]/boards/[name]/settings/_layout.tsx

@@ -1,12 +1,12 @@
 "use client";
 
-import { Button, Fieldset, Grid, Group, Input, NumberInput, Slider, Stack, Text, TextInput } from "@mantine/core";
+import { Button, Fieldset, Group, Input, Slider, Stack, Text } from "@mantine/core";
 
 import { clientApi } from "@homarr/api/client";
-import { createId } from "@homarr/common";
+import { getDesktopLayout } from "@homarr/boards/context";
 import { useZodForm } from "@homarr/form";
 import { useI18n } from "@homarr/translation/client";
-import { boardSaveLayoutsSchema } from "@homarr/validation/board";
+import { boardSaveLayoutSchema } from "@homarr/validation/board";
 
 import type { Board } from "../../_types";
 
@@ -16,93 +16,43 @@ interface Props {
 export const LayoutSettingsContent = ({ board }: Props) => {
   const t = useI18n();
   const utils = clientApi.useUtils();
-  const { mutate: saveLayouts, isPending } = clientApi.board.saveLayouts.useMutation({
+  const desktopLayout = getDesktopLayout(board);
+  const { mutate: saveLayout, isPending } = clientApi.board.saveLayout.useMutation({
     onSettled() {
       void utils.board.getBoardByName.invalidate({ name: board.name });
       void utils.board.getHomeBoard.invalidate();
     },
   });
-  const form = useZodForm(boardSaveLayoutsSchema.omit({ id: true }).required(), {
+  const form = useZodForm(boardSaveLayoutSchema.omit({ id: true }).required(), {
     initialValues: {
-      layouts: board.layouts,
+      columnCount: desktopLayout.columnCount,
     },
   });
 
   return (
     <form
       onSubmit={form.onSubmit((values) => {
-        saveLayouts({
+        saveLayout({
           id: board.id,
           ...values,
         });
       })}
     >
       <Stack>
-        <Stack gap="sm">
-          <Group justify="space-between" align="center">
-            <Text fw={500}>{t("board.setting.section.layout.responsive.title")}</Text>
-            <Button
-              variant="subtle"
-              onClick={() => {
-                form.setValues({
-                  layouts: [
-                    ...form.values.layouts,
-                    {
-                      id: createId(),
-                      name: "",
-                      columnCount: 10,
-                      breakpoint: 0,
-                    },
-                  ],
-                });
-              }}
-            >
-              {t("board.setting.section.layout.responsive.action.add")}
-            </Button>
-          </Group>
+        <Fieldset legend={t("board.setting.section.layout.desktop.title")} bg="transparent">
+          <Stack gap="sm">
+            <Text c="dimmed" size="sm">
+              {t("board.setting.section.layout.desktop.description")}
+            </Text>
+            <Input.Wrapper label={t("layout.field.columnCount.label")}>
+              <Slider mt="xs" min={1} max={24} step={1} {...form.getInputProps("columnCount")} />
+            </Input.Wrapper>
+          </Stack>
+        </Fieldset>
 
-          {form.values.layouts.map((layout, index) => (
-            <Fieldset key={layout.id} legend={layout.name} bg="transparent">
-              <Grid>
-                <Grid.Col span={{ sm: 12, md: 6 }}>
-                  <TextInput {...form.getInputProps(`layouts.${index}.name`)} label={t("layout.field.name.label")} />
-                </Grid.Col>
-
-                <Grid.Col span={{ sm: 12, md: 6 }}>
-                  <Input.Wrapper label={t("layout.field.columnCount.label")}>
-                    <Slider mt="xs" min={1} max={24} step={1} {...form.getInputProps(`layouts.${index}.columnCount`)} />
-                  </Input.Wrapper>
-                </Grid.Col>
-
-                <Grid.Col span={{ sm: 12, md: 6 }}>
-                  <NumberInput
-                    {...form.getInputProps(`layouts.${index}.breakpoint`)}
-                    label={t("layout.field.breakpoint.label")}
-                    description={t("layout.field.breakpoint.description")}
-                  />
-                </Grid.Col>
-              </Grid>
-              {form.values.layouts.length >= 2 && (
-                <Group justify="end">
-                  <Button
-                    variant="subtle"
-                    onClick={() => {
-                      form.setValues((previous) =>
-                        previous.layouts !== undefined && previous.layouts.length >= 2
-                          ? {
-                              layouts: form.values.layouts.filter((filteredLayout) => filteredLayout.id !== layout.id),
-                            }
-                          : previous,
-                      );
-                    }}
-                  >
-                    {t("common.action.remove")}
-                  </Button>
-                </Group>
-              )}
-            </Fieldset>
-          ))}
-        </Stack>
+        <Text c="dimmed" size="sm">
+          {t("board.setting.section.layout.mobile.description")}
+        </Text>
 
         <Group justify="end">
           <Button type="submit" loading={isPending}>

apps/nextjs/src/components/board/mobile/mobile-board.module.css

@@ -0,0 +1,20 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-auto-flow: row;
+  grid-auto-rows: min(calc((100vw - 42px) / 2), 12rem);
+  gap: 10px;
+  padding-bottom: 10px;
+}
+
+.item {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+}
+
+.item > :global(.grid-stack-item-content) {
+  width: 100%;
+  height: 100%;
+  overflow-y: auto;
+}

apps/nextjs/src/components/board/mobile/mobile-board.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import type { RefObject } from "react";
+import { useMemo, useRef } from "react";
+import { Box } from "@mantine/core";
+
+import { getDesktopLayout, useRequiredBoard } from "@homarr/boards/context";
+import { ReadOnlyEditModeProvider } from "@homarr/boards/edit-mode";
+import type { GridItemHTMLElement, GridStack as GridStackInstance } from "@homarr/gridstack";
+
+import { BoardItemContent } from "../items/item-content";
+import { SectionProvider } from "../sections/section-context";
+import classes from "./mobile-board.module.css";
+import { createMobileBoardItems } from "./mobile-layout";
+
+export const MobileBoard = () => {
+  const board = useRequiredBoard();
+  const desktopLayout = getDesktopLayout(board);
+  const items = useMemo(() => createMobileBoardItems(board, desktopLayout.id), [board, desktopLayout.id]);
+  const rootSection = board.sections.find((section) => section.kind !== "dynamic");
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  const itemRefs = useRef<Record<string, RefObject<GridItemHTMLElement | null>>>({});
+  const gridstackRef = useRef<GridStackInstance | null>(null);
+
+  if (!rootSection) return null;
+
+  return (
+    <ReadOnlyEditModeProvider>
+      <SectionProvider
+        value={{
+          section: rootSection,
+          items,
+          innerSections: [],
+          refs: { wrapper: wrapperRef, items: itemRefs, gridstack: gridstackRef },
+        }}
+      >
+        <Box className={classes.grid} data-mobile-board>
+          {items.map((item) => (
+            <Box
+              key={item.id}
+              className={classes.item}
+              style={{ gridColumn: `span ${item.width}`, gridRow: `span ${item.height}` }}
+              data-mobile-board-item={item.id}
+            >
+              <BoardItemContent item={item} />
+            </Box>
+          ))}
+        </Box>
+      </SectionProvider>
+    </ReadOnlyEditModeProvider>
+  );
+};

apps/nextjs/src/components/board/mobile/mobile-layout.spec.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "vitest";
+
+import { CategorySectionMockBuilder } from "../items/actions/test/mocks/category-section-mock";
+import { BoardMockBuilder } from "../items/actions/test/mocks/board-mock";
+import { DynamicSectionMockBuilder } from "../items/actions/test/mocks/dynamic-section-mock";
+import { EmptySectionMockBuilder } from "../items/actions/test/mocks/empty-section-mock";
+import { ItemMockBuilder } from "../items/actions/test/mocks/item-mock";
+import { createMobileBoardItems } from "./mobile-layout";
+
+describe("createMobileBoardItems", () => {
+  test("flattens categories and dynamic sections in visual order", () => {
+    const board = new BoardMockBuilder().build();
+    const desktopLayoutId = board.layouts.at(0)?.id;
+    if (!desktopLayoutId) throw new Error("Expected a desktop layout");
+    const rootSection = new EmptySectionMockBuilder({ id: "root", yOffset: 0 }).build();
+    const category = new CategorySectionMockBuilder({ id: "category", yOffset: 1, collapsed: true }).build();
+    const dynamicSection = new DynamicSectionMockBuilder({ id: "dynamic" })
+      .addLayout({ layoutId: desktopLayoutId, parentSectionId: rootSection.id, xOffset: 0, yOffset: 1 })
+      .build();
+    const nestedDynamicSection = new DynamicSectionMockBuilder({ id: "nested-dynamic" })
+      .addLayout({ layoutId: desktopLayoutId, parentSectionId: dynamicSection.id, xOffset: 0, yOffset: 1 })
+      .build();
+
+    board.sections.push(rootSection, category, dynamicSection, nestedDynamicSection);
+    board.items.push(
+      new ItemMockBuilder({ id: "second" })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: rootSection.id, xOffset: 1, yOffset: 0 })
+        .build(),
+      new ItemMockBuilder({ id: "first" })
+        .addLayout({
+          layoutId: desktopLayoutId,
+          sectionId: rootSection.id,
+          xOffset: 0,
+          yOffset: 0,
+          width: 8,
+          height: 6,
+        })
+        .build(),
+      new ItemMockBuilder({ id: "inside-dynamic" })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: dynamicSection.id })
+        .build(),
+      new ItemMockBuilder({ id: "inside-nested-dynamic" })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: nestedDynamicSection.id })
+        .build(),
+      new ItemMockBuilder({ id: "inside-collapsed-category" })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: category.id })
+        .build(),
+    );
+
+    const result = createMobileBoardItems(board, desktopLayoutId);
+
+    expect(result.map((item) => item.id)).toEqual([
+      "first",
+      "second",
+      "inside-dynamic",
+      "inside-nested-dynamic",
+      "inside-collapsed-category",
+    ]);
+    expect(result[0]).toMatchObject({ width: 2, height: 3, xOffset: 0, yOffset: 0 });
+  });
+
+  test("uses the desktop layout and keeps orphaned items", () => {
+    const board = new BoardMockBuilder().build();
+    const legacyLayoutId = board.layouts.at(0)?.id;
+    if (!legacyLayoutId) throw new Error("Expected a legacy layout");
+    const desktopLayoutId = "desktop";
+    board.layouts.push({ id: desktopLayoutId, name: "Large", columnCount: 16, breakpoint: 1200 });
+    board.sections.push(new EmptySectionMockBuilder({ id: "root" }).build());
+    board.items.push(
+      new ItemMockBuilder({ id: "first" })
+        .addLayout({ layoutId: legacyLayoutId, sectionId: "root", yOffset: 2 })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: "missing-section", yOffset: 0, width: 0, height: 0 })
+        .build(),
+      new ItemMockBuilder({ id: "second" })
+        .addLayout({ layoutId: legacyLayoutId, sectionId: "root", yOffset: 0 })
+        .addLayout({ layoutId: desktopLayoutId, sectionId: "root", yOffset: 1 })
+        .build(),
+    );
+
+    const result = createMobileBoardItems(board, desktopLayoutId);
+
+    expect(result.map((item) => item.id)).toEqual(["second", "first"]);
+    expect(result[1]).toMatchObject({ width: 1, height: 1 });
+  });
+});

apps/nextjs/src/components/board/mobile/mobile-layout.ts

@@ -0,0 +1,106 @@
+import type { Board, DynamicSectionItem, ItemLayout, SectionItem } from "~/app/[locale]/boards/_types";
+
+const mobileColumnCount = 2;
+const mobileMaxHeight = 3;
+
+type PositionedElement = DynamicSectionItem | SectionItem;
+type PositionedLayout = {
+  layoutId: string;
+  xOffset: number;
+  yOffset: number;
+  width: number;
+  height: number;
+};
+
+const comparePosition = (elementA: PositionedElement, elementB: PositionedElement) =>
+  elementA.yOffset - elementB.yOffset || elementA.xOffset - elementB.xOffset;
+
+const getLayout = <TLayout extends PositionedLayout>(
+  layouts: TLayout[],
+  desktopLayoutId: string,
+  layoutPriority: Map<string, number>,
+) =>
+  layouts.find((layout) => layout.layoutId === desktopLayoutId) ??
+  layouts.toSorted(
+    (layoutA, layoutB) => (layoutPriority.get(layoutB.layoutId) ?? -1) - (layoutPriority.get(layoutA.layoutId) ?? -1),
+  )[0];
+
+export const createMobileBoardItems = (board: Board, desktopLayoutId: string): SectionItem[] => {
+  const rootSections = board.sections
+    .filter((section) => section.kind !== "dynamic")
+    .toSorted((sectionA, sectionB) => sectionA.yOffset - sectionB.yOffset || sectionA.xOffset - sectionB.xOffset);
+  const defaultSectionId = rootSections[0]?.id ?? "mobile";
+  const layoutPriority = new Map(
+    board.layouts
+      .toSorted(
+        (layoutA, layoutB) => layoutA.breakpoint - layoutB.breakpoint || layoutA.columnCount - layoutB.columnCount,
+      )
+      .map((layout, index) => [layout.id, index]),
+  );
+
+  const items = board.items.map(({ layouts, ...item }, index): SectionItem => {
+    const layout =
+      getLayout(layouts, desktopLayoutId, layoutPriority) ??
+      ({
+        layoutId: desktopLayoutId,
+        xOffset: 0,
+        yOffset: index,
+        width: 1,
+        height: 1,
+        sectionId: defaultSectionId,
+      } satisfies ItemLayout);
+
+    return { ...item, ...layout, type: "item" };
+  });
+
+  const dynamicSections = board.sections
+    .filter((section) => section.kind === "dynamic")
+    .map(({ layouts, ...section }): DynamicSectionItem | null => {
+      const layout = getLayout(layouts, desktopLayoutId, layoutPriority);
+      return layout ? { ...section, ...layout, type: "section" } : null;
+    })
+    .filter((section) => section !== null);
+
+  const elementsBySection = new Map<string, PositionedElement[]>();
+  for (const element of [...items, ...dynamicSections]) {
+    const parentSectionId = element.type === "item" ? element.sectionId : element.parentSectionId;
+    const elements = elementsBySection.get(parentSectionId) ?? [];
+    elements.push(element);
+    elementsBySection.set(parentSectionId, elements);
+  }
+
+  const result: SectionItem[] = [];
+  const visitedItems = new Set<string>();
+  const visitedSections = new Set<string>();
+
+  const appendSectionItems = (sectionId: string) => {
+    if (visitedSections.has(sectionId)) return;
+    visitedSections.add(sectionId);
+
+    for (const element of (elementsBySection.get(sectionId) ?? []).toSorted(comparePosition)) {
+      if (element.type === "section") {
+        appendSectionItems(element.id);
+        continue;
+      }
+
+      if (!visitedItems.has(element.id)) {
+        visitedItems.add(element.id);
+        result.push(element);
+      }
+    }
+  };
+
+  rootSections.forEach((section) => appendSectionItems(section.id));
+  dynamicSections.toSorted(comparePosition).forEach((section) => appendSectionItems(section.id));
+  items.toSorted(comparePosition).forEach((item) => {
+    if (!visitedItems.has(item.id)) result.push(item);
+  });
+
+  return result.map((item, index) => ({
+    ...item,
+    xOffset: 0,
+    yOffset: index,
+    width: Math.max(1, Math.min(item.width, mobileColumnCount)),
+    height: Math.max(1, Math.min(item.height, mobileMaxHeight)),
+  }));
+};

apps/nextjs/src/components/board/use-mobile-board.ts

@@ -0,0 +1,7 @@
+"use client";
+
+import { useMediaQuery } from "@mantine/hooks";
+
+export const mobileBoardMediaQuery = "(max-width: 48em)";
+
+export const useIsMobileBoard = () => useMediaQuery(mobileBoardMediaQuery);

packages/api/src/router/board.ts

@@ -48,7 +48,7 @@ import {
   boardCreateSchema,
   boardDuplicateSchema,
   boardRenameSchema,
-  boardSaveLayoutsSchema,
+  boardSaveLayoutSchema,
   boardSavePartialSettingsSchema,
   boardSavePermissionsSchema,
   boardSaveSchema,
@@ -682,130 +682,72 @@ export const boardRouter = createTRPCRouter({
 
     return await getFullBoardWithWhereAsync(ctx.db, boardWhere, ctx.session?.user.id ?? null);
   }),
-  saveLayouts: protectedProcedure.input(boardSaveLayoutsSchema).mutation(async ({ ctx, input }) => {
+  saveLayout: protectedProcedure.input(boardSaveLayoutSchema).mutation(async ({ ctx, input }) => {
     await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "modify");
 
     const board = await getFullBoardWithWhereAsync(ctx.db, eq(boards.id, input.id), ctx.session.user.id);
+    const desktopLayout = board.layouts
+      .toSorted(
+        (layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint || layoutB.columnCount - layoutA.columnCount,
+      )
+      .at(0);
 
-    const addedLayouts = filterAddedItems(input.layouts, board.layouts);
-
-    const layoutsToInsert: InferInsertModel<typeof layouts>[] = [];
-    const itemSectionLayoutsToInsert: InferInsertModel<typeof itemLayouts>[] = [];
-    const sectionLayoutsToInsert: InferInsertModel<typeof sectionLayouts>[] = [];
-
-    for (const addedLayout of addedLayouts) {
-      const layoutId = createId();
-
-      layoutsToInsert.push({
-        id: layoutId,
-        name: addedLayout.name,
-        columnCount: addedLayout.columnCount,
-        breakpoint: addedLayout.breakpoint,
-        boardId: board.id,
-      });
-
-      const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutA.columnCount - layoutB.columnCount);
-      // Fallback to biggest if none exists with columnCount bigger than addedLayout.columnCount
-      const layoutToClone =
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        sortedLayouts.find((layout) => layout.columnCount >= addedLayout.columnCount) ?? sortedLayouts.at(-1)!;
+    if (!desktopLayout) {
+      throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "Board must have a layout" });
+    }
 
+    if (desktopLayout.columnCount !== input.columnCount) {
       const updatedBoardLayout = getUpdatedBoardLayout(board, {
         previous: {
-          layoutId: layoutToClone.id,
-          columnCount: layoutToClone.columnCount,
+          layoutId: desktopLayout.id,
+          columnCount: desktopLayout.columnCount,
         },
         current: {
-          layoutId,
-          columnCount: addedLayout.columnCount,
+          layoutId: desktopLayout.id,
+          columnCount: input.columnCount,
         },
       });
 
-      itemSectionLayoutsToInsert.push(...updatedBoardLayout.itemSectionLayouts);
-      sectionLayoutsToInsert.push(...updatedBoardLayout.sectionLayouts);
-    }
-
-    if (layoutsToInsert.length > 0) {
-      await ctx.db.insert(layouts).values(layoutsToInsert);
-    }
-
-    if (itemSectionLayoutsToInsert.length > 0) {
-      await ctx.db.insert(itemLayouts).values(itemSectionLayoutsToInsert);
-    }
-
-    if (sectionLayoutsToInsert.length > 0) {
-      await ctx.db.insert(sectionLayouts).values(sectionLayoutsToInsert);
-    }
-
-    const updatedLayouts = filterUpdatedItems(input.layouts, board.layouts);
-    for (const updatedLayout of updatedLayouts) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const dbLayout = board.layouts.find((layout) => layout.id === updatedLayout.id)!;
-
-      if (dbLayout.columnCount !== updatedLayout.columnCount) {
-        const updatedBoardLayout = getUpdatedBoardLayout(board, {
-          previous: {
-            layoutId: dbLayout.id,
-            columnCount: dbLayout.columnCount,
-          },
-          current: {
-            layoutId: dbLayout.id,
-            columnCount: updatedLayout.columnCount,
-          },
-        });
-
-        for (const itemSectionLayout of updatedBoardLayout.itemSectionLayouts) {
-          await ctx.db
-            .update(itemLayouts)
-            .set({
-              height: itemSectionLayout.height,
-              width: itemSectionLayout.width,
-              xOffset: itemSectionLayout.xOffset,
-              yOffset: itemSectionLayout.yOffset,
-              sectionId: itemSectionLayout.sectionId,
-            })
-            .where(
-              and(
-                eq(itemLayouts.itemId, itemSectionLayout.itemId),
-                eq(itemLayouts.layoutId, itemSectionLayout.layoutId),
-              ),
-            );
-        }
-
-        for (const sectionLayout of updatedBoardLayout.sectionLayouts) {
-          await ctx.db
-            .update(sectionLayouts)
-            .set({
-              height: sectionLayout.height,
-              width: sectionLayout.width,
-              xOffset: sectionLayout.xOffset,
-              yOffset: sectionLayout.yOffset,
-              parentSectionId: sectionLayout.parentSectionId,
-            })
-            .where(
-              and(
-                eq(sectionLayouts.sectionId, sectionLayout.sectionId),
-                eq(sectionLayouts.layoutId, sectionLayout.layoutId),
-              ),
-            );
-        }
+      for (const itemSectionLayout of updatedBoardLayout.itemSectionLayouts) {
+        await ctx.db
+          .update(itemLayouts)
+          .set({
+            height: itemSectionLayout.height,
+            width: itemSectionLayout.width,
+            xOffset: itemSectionLayout.xOffset,
+            yOffset: itemSectionLayout.yOffset,
+            sectionId: itemSectionLayout.sectionId,
+          })
+          .where(
+            and(eq(itemLayouts.itemId, itemSectionLayout.itemId), eq(itemLayouts.layoutId, itemSectionLayout.layoutId)),
+          );
       }
 
-      await ctx.db
-        .update(layouts)
-        .set({
-          name: updatedLayout.name,
-          columnCount: updatedLayout.columnCount,
-          breakpoint: updatedLayout.breakpoint,
-        })
-        .where(eq(layouts.id, updatedLayout.id));
+      for (const sectionLayout of updatedBoardLayout.sectionLayouts) {
+        await ctx.db
+          .update(sectionLayouts)
+          .set({
+            height: sectionLayout.height,
+            width: sectionLayout.width,
+            xOffset: sectionLayout.xOffset,
+            yOffset: sectionLayout.yOffset,
+            parentSectionId: sectionLayout.parentSectionId,
+          })
+          .where(
+            and(
+              eq(sectionLayouts.sectionId, sectionLayout.sectionId),
+              eq(sectionLayouts.layoutId, sectionLayout.layoutId),
+            ),
+          );
+      }
     }
 
-    const removedLayouts = filterRemovedItems(input.layouts, board.layouts);
-    const removedLayoutIds = removedLayouts.map((layout) => layout.id);
-    if (removedLayoutIds.length > 0) {
-      await ctx.db.delete(layouts).where(inArray(layouts.id, removedLayoutIds));
-    }
+    await ctx.db
+      .update(layouts)
+      .set({ name: "Base", columnCount: input.columnCount, breakpoint: 0 })
+      .where(eq(layouts.id, desktopLayout.id));
+
+    await ctx.db.delete(layouts).where(and(eq(layouts.boardId, board.id), not(eq(layouts.id, desktopLayout.id))));
   }),
   savePartialBoardSettings: protectedProcedure
     .meta({

packages/api/src/router/test/board.spec.ts

@@ -4,7 +4,7 @@ import { describe, expect, it, test, vi } from "vitest";
 import type { Session } from "@homarr/auth";
 import { createId } from "@homarr/common";
 import type { Database, InferInsertModel } from "@homarr/db";
-import { and, eq, not } from "@homarr/db";
+import { and, eq } from "@homarr/db";
 import {
   boardGroupPermissions,
   boards,
@@ -1324,100 +1324,7 @@ describe("saveGroupBoardPermissions should save group board permissions", () =>
   );
 });
 
-const createExistingLayout = (id: string) => ({
-  id,
-  name: "Base",
-  columnCount: 10,
-  breakpoint: 0,
-});
-const createNewLayout = (columnCount: number) => ({
-  id: createId(),
-  name: "New layout",
-  columnCount,
-  breakpoint: 1400,
-});
-describe("saveLayouts should save layout changes", () => {
-  test("should add layout when not present in database", async () => {
-    // Arrange
-    const db = createDb();
-    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
-
-    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
-    const newLayout = createNewLayout(12);
-
-    // Act
-    await caller.saveLayouts({
-      id: boardId,
-      layouts: [createExistingLayout(layoutId), newLayout],
-    });
-
-    // Assert
-    const layout = await db.query.layouts.findFirst({
-      where: not(eq(layouts.id, layoutId)),
-    });
-
-    const definedLayout = expectToBeDefined(layout);
-    expect(definedLayout.name).toBe(newLayout.name);
-    expect(definedLayout.columnCount).toBe(newLayout.columnCount);
-    expect(definedLayout.breakpoint).toBe(newLayout.breakpoint);
-  });
-  test("should add items and dynamic sections generated from grid-algorithm when new layout is added", async () => {
-    // Arrange
-    const db = createDb();
-    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
-
-    const { boardId, layoutId, sectionId, itemId } = await createFullBoardAsync(db, "default");
-    const assignments = await createItemsAndSectionsAsync(db, {
-      boardId,
-      layoutId,
-      sectionId,
-    });
-    const newLayout = createNewLayout(3);
-
-    // Act
-    await caller.saveLayouts({
-      id: boardId,
-      layouts: [createExistingLayout(layoutId), newLayout],
-    });
-
-    // Assert
-    const layout = await db.query.layouts.findFirst({
-      where: not(eq(layouts.id, layoutId)),
-    });
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    await expectLayoutForRootLayoutAsync(db, sectionId, layout!.id, {
-      ...assignments.inRoot,
-      a: itemId,
-    });
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layout!.id, assignments.inDynamicSection);
-  });
-  test("should update layout when present in input", async () => {
-    // Arrange
-    const db = createDb();
-    const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
-
-    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
-    const updatedLayout = createExistingLayout(layoutId);
-    updatedLayout.breakpoint = 1400;
-    updatedLayout.name = "Updated layout";
-
-    // Act
-    await caller.saveLayouts({
-      id: boardId,
-      layouts: [updatedLayout],
-    });
-
-    // Assert
-    const layout = await db.query.layouts.findFirst({
-      where: eq(layouts.id, layoutId),
-    });
-
-    const definedLayout = expectToBeDefined(layout);
-    expect(definedLayout.name).toBe(updatedLayout.name);
-    expect(definedLayout.columnCount).toBe(updatedLayout.columnCount);
-    expect(definedLayout.breakpoint).toBe(updatedLayout.breakpoint);
-  });
+describe("saveLayout should save the desktop layout", () => {
   test("should update position of items when column count changes", async () => {
     // Arrange
     const db = createDb();
@@ -1429,13 +1336,10 @@ describe("saveLayouts should save layout changes", () => {
       layoutId,
       sectionId,
     });
-    const updatedLayout = createExistingLayout(layoutId);
-    updatedLayout.columnCount = 3;
-
     // Act
-    await caller.saveLayouts({
+    await caller.saveLayout({
       id: boardId,
-      layouts: [updatedLayout],
+      columnCount: 3,
     });
 
     // Assert
@@ -1445,37 +1349,55 @@ describe("saveLayouts should save layout changes", () => {
     });
     await expectLayoutForDynamicSectionAsync(db, assignments.inRoot.f, layoutId, assignments.inDynamicSection);
   });
-  test("should remove layout when not present in input", async () => {
+  test("should keep the desktop layout and remove legacy responsive layouts", async () => {
     // Arrange
     const db = createDb();
     const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
 
-    const { boardId, layoutId } = await createFullBoardAsync(db, "default");
+    const { boardId, layoutId, itemId, sectionId } = await createFullBoardAsync(db, "default");
+    const desktopLayoutId = createId();
+    await db.insert(layouts).values({
+      id: desktopLayoutId,
+      boardId,
+      name: "Large",
+      columnCount: 16,
+      breakpoint: 1200,
+    });
+    await db.insert(itemLayouts).values({
+      itemId,
+      sectionId,
+      layoutId: desktopLayoutId,
+      xOffset: 0,
+      yOffset: 0,
+      width: 1,
+      height: 1,
+    });
 
     // Act
-    await caller.saveLayouts({
+    await caller.saveLayout({
       id: boardId,
-      layouts: [createNewLayout(12)],
+      columnCount: 16,
     });
 
     // Assert
-    const layout = await db.query.layouts.findFirst({
-      where: eq(layouts.id, layoutId),
-    });
-    expect(layout).toBeUndefined();
+    const savedLayouts = await db.query.layouts.findMany({ where: eq(layouts.boardId, boardId) });
+    expect(savedLayouts).toEqual([
+      expect.objectContaining({ id: desktopLayoutId, name: "Base", columnCount: 16, breakpoint: 0 }),
+    ]);
+    expect(savedLayouts.some((layout) => layout.id === layoutId)).toBe(false);
   });
   test("should fail when board not found", async () => {
     // Arrange
     const db = createDb();
     const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
 
-    const { layoutId } = await createFullBoardAsync(db, "default");
+    await createFullBoardAsync(db, "default");
 
     // Act
     const actAsync = async () =>
-      await caller.saveLayouts({
+      await caller.saveLayout({
         id: createId(),
-        layouts: [createExistingLayout(layoutId)],
+        columnCount: 12,
       });
 
     // Assert

packages/boards/src/context.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import type { PropsWithChildren } from "react";
-import { createContext, useCallback, useContext, useEffect, useState } from "react";
+import { createContext, useContext, useEffect } from "react";
 import { usePathname } from "next/navigation";
 
 import type { RouterOutputs } from "@homarr/api";
@@ -74,38 +74,26 @@ export const useOptionalBoard = () => {
 };
 
 export const getCurrentLayout = (board: RouterOutputs["board"]["getBoardByName"]) => {
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  if (typeof window === "undefined") return board.layouts.at(0)!.id;
-
-  const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint);
-
-  // Fallback to smallest if none exists with breakpoint smaller than window width
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  return sortedLayouts.find((layout) => layout.breakpoint <= window.innerWidth)?.id ?? sortedLayouts.at(0)!.id;
+  return getDesktopLayout(board).id;
 };
 
-export const useCurrentLayout = () => {
-  const board = useRequiredBoard();
-  const [currentLayout, setCurrentLayout] = useState(getCurrentLayout(board));
+export const getDesktopLayout = (board: RouterOutputs["board"]["getBoardByName"]) => {
+  const layout = board.layouts
+    .toSorted(
+      (layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint || layoutB.columnCount - layoutA.columnCount,
+    )
+    .at(0);
 
-  const onResize = useCallback(() => {
-    setCurrentLayout(getCurrentLayout(board));
-  }, [board]);
+  if (!layout) {
+    throw new Error("Board must have a layout");
+  }
 
-  useEffect(() => {
-    if (typeof window === "undefined") return;
-    window.addEventListener("resize", onResize);
-
-    return () => {
-      window.removeEventListener("resize", onResize);
-    };
-  }, [onResize]);
-
-  return currentLayout;
+  return layout;
 };
 
-export const getBoardLayouts = (board: RouterOutputs["board"]["getBoardByName"]) =>
-  board.layouts.map((layout) => layout.id);
+export const useCurrentLayout = () => getCurrentLayout(useRequiredBoard());
+
+export const getBoardLayouts = (board: RouterOutputs["board"]["getBoardByName"]) => [getCurrentLayout(board)];
 
 export const useLayouts = () => {
   const board = useRequiredBoard();

packages/boards/src/edit-mode.tsx

@@ -6,12 +6,21 @@ import { useDisclosure } from "@mantine/hooks";
 
 const EditModeContext = createContext<ReturnType<typeof useDisclosure> | null>(null);
 
+const noop = () => undefined;
+const readOnlyEditMode = [false, { open: noop, close: noop, toggle: noop, set: noop }] satisfies ReturnType<
+  typeof useDisclosure
+>;
+
 export const EditModeProvider = ({ children }: PropsWithChildren) => {
   const editModeDisclosure = useDisclosure(false);
 
   return <EditModeContext.Provider value={editModeDisclosure}>{children}</EditModeContext.Provider>;
 };
 
+export const ReadOnlyEditModeProvider = ({ children }: PropsWithChildren) => (
+  <EditModeContext.Provider value={readOnlyEditMode}>{children}</EditModeContext.Provider>
+);
+
 export const useEditMode = () => {
   const context = useContext(EditModeContext);
 

packages/translation/src/lang/en.json

@@ -4359,11 +4359,12 @@
         },
         "layout": {
           "title": "Layout",
-          "responsive": {
-            "title": "Responsive layouts",
-            "action": {
-              "add": "Add layout"
-            }
+          "desktop": {
+            "title": "Desktop layout",
+            "description": "Configure the layout used on desktop and larger screens."
+          },
+          "mobile": {
+            "description": "On mobile, items are automatically arranged in two columns and cannot be moved or resized. Categories and dynamic sections are flattened into the item list."
           }
         },
         "background": {

packages/validation/src/board.ts

@@ -70,16 +70,9 @@ export const boardSavePartialSettingsSchema = z
   })
   .partial();
 
-export const boardSaveLayoutsSchema = z.object({
+export const boardSaveLayoutSchema = z.object({
   id: z.string(),
-  layouts: z.array(
-    z.object({
-      id: z.string(),
-      name: z.string().trim().nonempty().max(32),
-      columnCount: boardColumnCountSchema,
-      breakpoint: z.number().min(0).max(32767),
-    }),
-  ),
+  columnCount: boardColumnCountSchema,
 });
 
 export const boardSaveSchema = z.object({