feat: rebuild onboarding experience

This commit is contained in:
Thomas Camlong authored and ajnart committed 2026-08-14 11:32:11 +02:00
1 parent d091362db2
commit e41605640b
249 files changed
+8216 -14060

No files matched your search

+215
View File
@@ -0,0 +1,215 @@
import { describe, expect, test } from "vitest";
import type { BoardPreviewData, BoardPreviewLayout } from "./layout-preview";
import { getRepresentativeLayoutWidth, projectBoardLayout } from "./layout-preview";
const mobile = {
id: "mobile",
columnCount: 3,
leftGutterColumnCount: 0,
rightGutterColumnCount: 0,
breakpoint: 0,
role: "mobile",
} satisfies BoardPreviewLayout;
const custom = {
id: "tablet",
columnCount: 6,
leftGutterColumnCount: 0,
rightGutterColumnCount: 0,
breakpoint: 480,
role: "custom",
} satisfies BoardPreviewLayout;
const base = {
id: "base",
columnCount: 12,
leftGutterColumnCount: 0,
rightGutterColumnCount: 0,
breakpoint: 768,
role: "base",
} satisfies BoardPreviewLayout;
const root = { id: "root", kind: "empty" as const, xOffset: 0, layouts: [] };
describe("layout representative widths", () => {
test("uses phone, activation midpoint, and desktop widths", () => {
const layouts = [mobile, custom, base];
expect(getRepresentativeLayoutWidth(mobile, layouts)).toBe(390);
expect(getRepresentativeLayoutWidth(custom, layouts)).toBe(624);
expect(getRepresentativeLayoutWidth(base, layouts)).toBe(1280);
});
});
describe("projectBoardLayout", () => {
test("keeps exact saved positions for the active layout", () => {
const board = {
layouts: [mobile],
sections: [
root,
{
id: "container",
kind: "container",
xOffset: null,
layouts: [
{
layoutId: mobile.id,
parentSectionId: root.id,
width: 3,
height: 2,
xOffset: 0,
yOffset: 0,
},
],
},
],
items: [],
} satisfies BoardPreviewData;
expect(projectBoardLayout(board, mobile, mobile)).toEqual([
expect.objectContaining({ id: "container", sectionId: root.id, width: 3, height: 2 }),
]);
});
test("reflows root items and containers while retaining nested items", () => {
const board = {
layouts: [mobile, base],
sections: [
root,
{
id: "container",
kind: "container",
xOffset: null,
layouts: [
{
layoutId: base.id,
parentSectionId: root.id,
width: 6,
height: 3,
xOffset: 6,
yOffset: 0,
},
],
},
],
items: [
{
id: "root-item",
layouts: [
{
layoutId: base.id,
sectionId: root.id,
width: 5,
height: 2,
xOffset: 0,
yOffset: 0,
},
],
},
{
id: "nested-item",
layouts: [
{
layoutId: base.id,
sectionId: "container",
width: 4,
height: 1,
xOffset: 0,
yOffset: 0,
},
],
},
],
} satisfies BoardPreviewData;
const projected = projectBoardLayout(board, base, mobile);
expect(projected.find((element) => element.id === "root-item")).toMatchObject({
type: "item",
width: 3,
height: 2,
xOffset: 0,
yOffset: 0,
sectionId: root.id,
});
expect(projected.find((element) => element.id === "container")).toMatchObject({
type: "section",
width: 3,
xOffset: 0,
yOffset: 2,
sectionId: root.id,
});
expect(projected.find((element) => element.id === "nested-item")).toMatchObject({
type: "item",
width: 3,
sectionId: "container",
});
});
test("ignores missing positions and supports empty boards", () => {
const board = {
layouts: [mobile],
sections: [root],
items: [{ id: "missing", layouts: [] }],
} satisfies BoardPreviewData;
expect(projectBoardLayout(board, base, mobile)).toEqual([]);
});
test("moves fixed-rail items into the mobile canvas without overlap", () => {
const baseWithRails = {
...base,
leftGutterColumnCount: 2,
rightGutterColumnCount: 2,
};
const roots = [
{ id: "left", kind: "empty" as const, xOffset: -1, layouts: [] },
root,
{ id: "right", kind: "empty" as const, xOffset: 1, layouts: [] },
];
const board = {
layouts: [mobile, baseWithRails],
sections: roots,
items: roots.map((section, index) => ({
id: `item-${section.id}`,
layouts: [
{
layoutId: base.id,
sectionId: section.id,
width: 2,
height: 1,
xOffset: 0,
yOffset: index,
},
],
})),
} satisfies BoardPreviewData;
const projected = projectBoardLayout(board, baseWithRails, mobile);
expect(projected).toHaveLength(3);
expect(projected.every((element) => element.sectionId === root.id)).toBe(true);
expect(projected.every((element) => element.xOffset >= 0 && element.xOffset + element.width <= 3)).toBe(true);
for (const [index, element] of projected.entries()) {
expect(
projected
.slice(index + 1)
.some(
(other) =>
element.xOffset < other.xOffset + other.width &&
element.xOffset + element.width > other.xOffset &&
element.yOffset < other.yOffset + other.height &&
element.yOffset + element.height > other.yOffset,
),
).toBe(false);
}
});
test("returns an empty preview when malformed data has no main root", () => {
const board = {
layouts: [mobile, base],
sections: [{ id: "left", kind: "empty", xOffset: -1, layouts: [] }],
items: [],
} satisfies BoardPreviewData;
expect(projectBoardLayout(board, base, mobile)).toEqual([]);
});
});
+176
View File
@@ -0,0 +1,176 @@
import { generateResponsiveGridFor } from "@homarr/common";
import type { GridAlgorithmItem } from "@homarr/common";
import type { BoardLane, LayoutRole } from "@homarr/definitions";
import { boardLanes, getBoardLaneColumnCount, getRootSectionLane } from "@homarr/definitions";
export interface BoardPreviewLayout {
id: string;
columnCount: number;
leftGutterColumnCount: number;
rightGutterColumnCount: number;
breakpoint: number;
role: LayoutRole;
}
interface BoardPreviewItemLayout {
layoutId: string;
sectionId: string;
xOffset: number;
yOffset: number;
width: number;
height: number;
}
interface BoardPreviewSectionLayout {
layoutId: string;
parentSectionId: string | null;
xOffset: number;
yOffset: number;
width: number;
height: number;
}
export interface BoardPreviewData {
layouts: readonly BoardPreviewLayout[];
sections: readonly BoardPreviewSection[];
items: readonly {
id: string;
layouts: readonly BoardPreviewItemLayout[];
}[];
}
type BoardPreviewSection =
| {
id: string;
kind: "empty";
xOffset: number | null;
layouts?: readonly BoardPreviewSectionLayout[];
}
| {
id: string;
kind: "container";
xOffset?: number | null;
layouts: readonly BoardPreviewSectionLayout[];
};
type LayoutGeometry = Pick<
BoardPreviewLayout,
"id" | "columnCount" | "leftGutterColumnCount" | "rightGutterColumnCount"
>;
export const getRepresentativeLayoutWidth = (layout: BoardPreviewLayout, allLayouts: readonly BoardPreviewLayout[]) => {
if (layout.role === "mobile") return 390;
if (layout.role === "base") return Math.max(1280, layout.breakpoint);
const nextLayout = allLayouts
.filter((candidate) => candidate.breakpoint > layout.breakpoint)
.toSorted((layoutA, layoutB) => layoutA.breakpoint - layoutB.breakpoint)
.at(0);
return nextLayout ? Math.round((layout.breakpoint + nextLayout.breakpoint) / 2) : Math.max(1280, layout.breakpoint);
};
export const projectBoardLayout = (
board: BoardPreviewData,
sourceLayout: LayoutGeometry,
targetLayout: LayoutGeometry,
) => {
const elements = getElementsForLayout(board, sourceLayout.id);
if (
sourceLayout.id === targetLayout.id &&
sourceLayout.columnCount === targetLayout.columnCount &&
sourceLayout.leftGutterColumnCount === targetLayout.leftGutterColumnCount &&
sourceLayout.rightGutterColumnCount === targetLayout.rightGutterColumnCount
) {
return elements;
}
const emptyRoots = board.sections
.filter((section) => section.kind === "empty")
.toSorted((first, second) => (first.xOffset ?? 0) - (second.xOffset ?? 0) || first.id.localeCompare(second.id));
const rootByLane = new Map<BoardLane, (typeof emptyRoots)[number]>();
for (const root of emptyRoots) {
const lane = getRootSectionLane(root.xOffset);
if (!rootByLane.has(lane)) rootByLane.set(lane, root);
}
const mainRoot = rootByLane.get("main");
if (!mainRoot) return [];
const sourceRootById = new Map(
emptyRoots.map((section) => [section.id, getRootSectionLane(section.xOffset)] as const),
);
const targetLaneBySourceLane = new Map<BoardLane, BoardLane>(
boardLanes.map((lane) => [
lane,
lane !== "main" && getBoardLaneColumnCount(targetLayout, lane) === 0 ? "main" : lane,
]),
);
const remappedElements = elements.map((element) => {
const sourceLane = sourceRootById.get(element.sectionId);
if (!sourceLane) return element;
const targetLane = targetLaneBySourceLane.get(sourceLane) ?? "main";
return { ...element, sectionId: (rootByLane.get(targetLane) ?? mainRoot).id };
});
return boardLanes.flatMap((lane) => {
const root = rootByLane.get(lane);
const width = getBoardLaneColumnCount(targetLayout, lane);
if (!root || width === 0) return [];
const sourceLanes = boardLanes.filter(
(sourceLane) =>
rootByLane.has(sourceLane) &&
getBoardLaneColumnCount(sourceLayout, sourceLane) > 0 &&
targetLaneBySourceLane.get(sourceLane) === lane,
);
const previousWidth =
sourceLanes.length === 1
? getBoardLaneColumnCount(sourceLayout, sourceLanes[0] ?? "main")
: Number.MAX_SAFE_INTEGER;
return generateResponsiveGridFor({
items: remappedElements,
previousWidth,
width,
sectionId: root.id,
}).items;
});
};
const getElementsForLayout = (board: BoardPreviewData, layoutId: string): GridAlgorithmItem[] => [
...board.items.flatMap((item) => {
const layout = item.layouts.find((candidate) => candidate.layoutId === layoutId);
return layout
? [
{
id: item.id,
type: "item" as const,
height: layout.height,
width: layout.width,
xOffset: layout.xOffset,
yOffset: layout.yOffset,
sectionId: layout.sectionId,
},
]
: [];
}),
...board.sections.flatMap((section) => {
if (section.kind !== "container") return [];
const layout = section.layouts.find((candidate) => candidate.layoutId === layoutId);
return layout?.parentSectionId
? [
{
id: section.id,
type: "section" as const,
height: layout.height,
width: layout.width,
xOffset: layout.xOffset,
yOffset: layout.yOffset,
sectionId: layout.parentSectionId,
},
]
: [];
}),
];