Add position to page layout widgets (#17643)

## Context Introducing a new position column in PageLayoutWidget. This is because we already have gridPosition but all widgets are not supposed to fit in a grid (see pageLayoutTab layoutMode (GRID, VERTICAL_LIST, CANVAS...), position will now support the different layoutMode ## Implementation - Adding the new column (not renaming to avoid breaking changes in the dashboards) - Add proper validation for each layout mode - Update standard page layout to not always use GRID but rely on the tab layout mode <details> <summary>Graphql Query</summary> ```graphql { "data": { "getPageLayouts": [ { "tabs": [ { "title": "Tab 1", "layoutMode": "GRID", "widgets": [ { "title": "Untitled Rich Text", "position": { "column": 0, "columnSpan": 6, "layoutMode": "GRID", "row": 0, "rowSpan": 6 } }, { "title": "Deals by Company", "position": { "column": 6, "columnSpan": 6, "layoutMode": "GRID", "row": 0, "rowSpan": 6 } }, { "title": "Pipeline Value by Stage", "position": { "column": 0, "columnSpan": 6, "layoutMode": "GRID", "row": 6, "rowSpan": 6 } }, { "title": "Revenue Timeline", "position": { "column": 6, "columnSpan": 6, "layoutMode": "GRID", "row": 6, "rowSpan": 6 } }, { "title": "Opportunities by Owner", "position": { "column": 0, "columnSpan": 6, "layoutMode": "GRID", "row": 12, "rowSpan": 6 } }, { "title": "Stock market (Iframe)", "position": { "column": 6, "columnSpan": 6, "layoutMode": "GRID", "row": 12, "rowSpan": 8 } }, { "title": "Deals created this month", "position": { "column": 0, "columnSpan": 3, "layoutMode": "GRID", "row": 18, "rowSpan": 2 } }, { "title": "Deal value created this month", "position": { "column": 3, "columnSpan": 3, "layoutMode": "GRID", "row": 18, "rowSpan": 2 } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } } ] }, { "title": "Timeline", "layoutMode": "CANVAS", "widgets": [ { "title": "Timeline", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Tasks", "layoutMode": "CANVAS", "widgets": [ { "title": "Tasks", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Notes", "layoutMode": "CANVAS", "widgets": [ { "title": "Notes", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Files", "layoutMode": "CANVAS", "widgets": [ { "title": "Files", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Emails", "layoutMode": "CANVAS", "widgets": [ { "title": "Emails", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Calendar", "layoutMode": "CANVAS", "widgets": [ { "title": "Calendar", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } } ] }, { "title": "Timeline", "layoutMode": "CANVAS", "widgets": [ { "title": "Timeline", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Tasks", "layoutMode": "CANVAS", "widgets": [ { "title": "Tasks", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Notes", "layoutMode": "CANVAS", "widgets": [ { "title": "Notes", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Files", "layoutMode": "CANVAS", "widgets": [ { "title": "Files", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Emails", "layoutMode": "CANVAS", "widgets": [ { "title": "Emails", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Calendar", "layoutMode": "CANVAS", "widgets": [ { "title": "Calendar", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } } ] }, { "title": "Timeline", "layoutMode": "CANVAS", "widgets": [ { "title": "Timeline", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Tasks", "layoutMode": "CANVAS", "widgets": [ { "title": "Tasks", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Notes", "layoutMode": "CANVAS", "widgets": [ { "title": "Notes", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Files", "layoutMode": "CANVAS", "widgets": [ { "title": "Files", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Emails", "layoutMode": "CANVAS", "widgets": [ { "title": "Emails", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Calendar", "layoutMode": "CANVAS", "widgets": [ { "title": "Calendar", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } }, { "title": "Note", "position": { "layoutMode": "VERTICAL_LIST", "index": 1 } } ] }, { "title": "Note", "layoutMode": "CANVAS", "widgets": [ { "title": "Note", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Timeline", "layoutMode": "CANVAS", "widgets": [ { "title": "Timeline", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Files", "layoutMode": "CANVAS", "widgets": [ { "title": "Files", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } }, { "title": "Note", "position": { "layoutMode": "VERTICAL_LIST", "index": 1 } } ] }, { "title": "Note", "layoutMode": "CANVAS", "widgets": [ { "title": "Note", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Timeline", "layoutMode": "CANVAS", "widgets": [ { "title": "Timeline", "position": { "layoutMode": "CANVAS" } } ] }, { "title": "Files", "layoutMode": "CANVAS", "widgets": [ { "title": "Files", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Flow", "layoutMode": "CANVAS", "widgets": [ { "title": "Flow", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } } ] }, { "title": "Flow", "layoutMode": "CANVAS", "widgets": [ { "title": "Flow", "position": { "layoutMode": "CANVAS" } } ] } ] }, { "tabs": [ { "title": "Home", "layoutMode": "VERTICAL_LIST", "widgets": [ { "title": "Fields", "position": { "layoutMode": "VERTICAL_LIST", "index": 0 } } ] }, { "title": "Flow", "layoutMode": "CANVAS", "widgets": [ { "title": "Flow", "position": { "layoutMode": "CANVAS" } } ] } ] } ] } } ``` </details>
2026-02-03 16:54:01 +01:00
parent f009913cbe
commit 5c91a96e84
31 changed files with 577 additions and 28 deletions
@@ -5,5 +5,6 @@ export const FLAT_PAGE_LAYOUT_WIDGET_EDITABLE_PROPERTIES = [
  'type',
  'objectMetadataId',
  'gridPosition',
+  'position',
  'configuration',
 ] as const satisfies (keyof FlatPageLayoutWidget)[];
@@ -42,6 +42,7 @@ export const fromCreatePageLayoutWidgetInputToFlatPageLayoutWidgetToCreate = ({
    type: createPageLayoutWidgetInput.type,
    objectMetadataId: createPageLayoutWidgetInput.objectMetadataId ?? null,
    gridPosition: createPageLayoutWidgetInput.gridPosition,
+    position: createPageLayoutWidgetInput.position ?? null,
    configuration: createPageLayoutWidgetInput.configuration,
    applicationId: workspaceCustomApplicationId,
    conditionalDisplay: null,
@@ -11,6 +11,7 @@ import {
  ValidateNested,
 } from 'class-validator';
 import { GraphQLJSON } from 'graphql-type-json';
+import { PageLayoutWidgetPosition } from 'twenty-shared/types';

 import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
 import { GridPositionInput } from 'src/engine/metadata-modules/page-layout-widget/dtos/inputs/grid-position.input';
@@ -43,6 +44,11 @@ export class CreatePageLayoutWidgetInput {
  @Type(() => GridPositionInput)
  gridPosition: GridPositionInput;

+  @Field(() => GraphQLJSON, { nullable: true })
+  @IsObject()
+  @IsOptional()
+  position?: PageLayoutWidgetPosition;
+
  @Field(() => GraphQLJSON, { nullable: false })
  @IsObject()
  @IsOptional()
@@ -11,6 +11,7 @@ import {
  ValidateNested,
 } from 'class-validator';
 import { GraphQLJSON } from 'graphql-type-json';
+import { PageLayoutWidgetPosition } from 'twenty-shared/types';

 import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
 import { GridPositionInput } from 'src/engine/metadata-modules/page-layout-widget/dtos/inputs/grid-position.input';
@@ -50,6 +51,11 @@ export class UpdatePageLayoutWidgetWithIdInput {
  @IsNotEmpty()
  gridPosition: GridPositionInput;

+  @Field(() => GraphQLJSON, { nullable: true })
+  @IsObject()
+  @IsOptional()
+  position?: PageLayoutWidgetPosition;
+
  @Field(() => GraphQLJSON, { nullable: true })
  @IsObject()
  @IsOptional()
@@ -10,6 +10,7 @@ import {
  ValidateNested,
 } from 'class-validator';
 import { GraphQLJSON } from 'graphql-type-json';
+import { PageLayoutWidgetPosition } from 'twenty-shared/types';

 import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
 import { GridPositionInput } from 'src/engine/metadata-modules/page-layout-widget/dtos/inputs/grid-position.input';
@@ -39,6 +40,11 @@ export class UpdatePageLayoutWidgetInput {
  @IsOptional()
  gridPosition?: GridPositionInput;

+  @Field(() => GraphQLJSON, { nullable: true })
+  @IsObject()
+  @IsOptional()
+  position?: PageLayoutWidgetPosition;
+
  @Field(() => GraphQLJSON, { nullable: true })
  @IsObject()
  @IsOptional()
@@ -0,0 +1,12 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { IsIn, IsNotEmpty } from 'class-validator';
+import { PageLayoutTabLayoutMode } from 'twenty-shared/types';
+
+@ObjectType('PageLayoutWidgetCanvasPosition')
+export class PageLayoutWidgetCanvasPositionDTO {
+  @Field(() => PageLayoutTabLayoutMode)
+  @IsIn([PageLayoutTabLayoutMode.CANVAS])
+  @IsNotEmpty()
+  layoutMode: PageLayoutTabLayoutMode.CANVAS;
+}
@@ -0,0 +1,36 @@
+import { Field, Int, ObjectType } from '@nestjs/graphql';
+
+import { IsIn, IsInt, IsNotEmpty, Min } from 'class-validator';
+import { PageLayoutTabLayoutMode } from 'twenty-shared/types';
+
+@ObjectType('PageLayoutWidgetGridPosition')
+export class PageLayoutWidgetGridPositionDTO {
+  @Field(() => PageLayoutTabLayoutMode)
+  @IsIn([PageLayoutTabLayoutMode.GRID])
+  @IsNotEmpty()
+  layoutMode: PageLayoutTabLayoutMode.GRID;
+
+  @Field(() => Int)
+  @IsInt()
+  @Min(0)
+  @IsNotEmpty()
+  row: number;
+
+  @Field(() => Int)
+  @IsInt()
+  @Min(0)
+  @IsNotEmpty()
+  column: number;
+
+  @Field(() => Int)
+  @IsInt()
+  @Min(1)
+  @IsNotEmpty()
+  rowSpan: number;
+
+  @Field(() => Int)
+  @IsInt()
+  @Min(1)
+  @IsNotEmpty()
+  columnSpan: number;
+}
@@ -0,0 +1,29 @@
+import { createUnionType } from '@nestjs/graphql';
+
+import {
+  PageLayoutTabLayoutMode,
+  type PageLayoutWidgetPosition,
+} from 'twenty-shared/types';
+
+import { PageLayoutWidgetCanvasPositionDTO } from './page-layout-widget-canvas-position.dto';
+import { PageLayoutWidgetGridPositionDTO } from './page-layout-widget-grid-position.dto';
+import { PageLayoutWidgetVerticalListPositionDTO } from './page-layout-widget-vertical-list-position.dto';
+
+export const PageLayoutWidgetPositionUnion = createUnionType({
+  name: 'PageLayoutWidgetPosition',
+  types: () => [
+    PageLayoutWidgetGridPositionDTO,
+    PageLayoutWidgetVerticalListPositionDTO,
+    PageLayoutWidgetCanvasPositionDTO,
+  ],
+  resolveType({ layoutMode }: PageLayoutWidgetPosition) {
+    switch (layoutMode) {
+      case PageLayoutTabLayoutMode.GRID:
+        return PageLayoutWidgetGridPositionDTO;
+      case PageLayoutTabLayoutMode.VERTICAL_LIST:
+        return PageLayoutWidgetVerticalListPositionDTO;
+      case PageLayoutTabLayoutMode.CANVAS:
+        return PageLayoutWidgetCanvasPositionDTO;
+    }
+  },
+});
@@ -0,0 +1,18 @@
+import { Field, Int, ObjectType } from '@nestjs/graphql';
+
+import { IsIn, IsInt, IsNotEmpty, Min } from 'class-validator';
+import { PageLayoutTabLayoutMode } from 'twenty-shared/types';
+
+@ObjectType('PageLayoutWidgetVerticalListPosition')
+export class PageLayoutWidgetVerticalListPositionDTO {
+  @Field(() => PageLayoutTabLayoutMode)
+  @IsIn([PageLayoutTabLayoutMode.VERTICAL_LIST])
+  @IsNotEmpty()
+  layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST;
+
+  @Field(() => Int)
+  @IsInt()
+  @Min(0)
+  @IsNotEmpty()
+  index: number;
+}
@@ -2,9 +2,13 @@ import { Field, ObjectType, registerEnumType } from '@nestjs/graphql';

 import { IDField } from '@ptc-org/nestjs-query-graphql';
 import GraphQLJSON from 'graphql-type-json';
-import { PageLayoutWidgetConditionalDisplay } from 'twenty-shared/types';
+import {
+  PageLayoutWidgetConditionalDisplay,
+  PageLayoutWidgetPosition,
+} from 'twenty-shared/types';

 import { UUIDScalarType } from 'src/engine/api/graphql/workspace-schema-builder/graphql-types/scalars';
+import { PageLayoutWidgetPositionUnion } from 'src/engine/metadata-modules/page-layout-widget/dtos/page-layout-widget-position.union';
 import { WidgetConfiguration } from 'src/engine/metadata-modules/page-layout-widget/dtos/widget-configuration.interface';
 import { WidgetType } from 'src/engine/metadata-modules/page-layout-widget/enums/widget-type.enum';
 import { AllPageLayoutWidgetConfiguration } from 'src/engine/metadata-modules/page-layout-widget/types/all-page-layout-widget-configuration.type';
@@ -46,6 +50,9 @@ export class PageLayoutWidgetDTO {
  @Field(() => GridPositionDTO, { nullable: false })
  gridPosition: GridPositionDTO;

+  @Field(() => PageLayoutWidgetPositionUnion, { nullable: true })
+  position?: PageLayoutWidgetPosition | null;
+
  @Field(() => WidgetConfiguration, { nullable: false })
  configuration: AllPageLayoutWidgetConfiguration;

@@ -1,6 +1,9 @@
 import { ObjectType } from '@nestjs/graphql';

-import { PageLayoutWidgetConditionalDisplay } from 'twenty-shared/types';
+import {
+  PageLayoutWidgetConditionalDisplay,
+  PageLayoutWidgetPosition,
+} from 'twenty-shared/types';
 import {
  Column,
  CreateDateColumn,
@@ -77,6 +80,9 @@ export class PageLayoutWidgetEntity<
  @Column({ type: 'jsonb', nullable: false })
  gridPosition: JsonbProperty<GridPosition>;

+  @Column({ type: 'jsonb', nullable: true })
+  position: JsonbProperty<PageLayoutWidgetPosition | null>;
+
  @Column({ type: 'jsonb', nullable: false })
  configuration: JsonbProperty<
    PageLayoutWidgetConfigurationTypeSettings<TWidgetConfigurationType>
@@ -16,7 +16,7 @@ export enum PageLayoutWidgetExceptionMessageKey {
  PAGE_LAYOUT_TAB_NOT_FOUND = 'PAGE_LAYOUT_TAB_NOT_FOUND',
  PAGE_LAYOUT_WIDGET_NOT_DELETED = 'PAGE_LAYOUT_WIDGET_NOT_DELETED',
  GRID_POSITION_REQUIRED = 'GRID_POSITION_REQUIRED',
-  INVALID_WIDGET_GRID_POSITION = 'INVALID_WIDGET_GRID_POSITION',
+  INVALID_WIDGET_POSITION = 'INVALID_WIDGET_POSITION',
  INVALID_WIDGET_CONFIGURATION = 'INVALID_WIDGET_CONFIGURATION',
 }

@@ -66,15 +66,15 @@ export const generatePageLayoutWidgetExceptionMessage = (
      return 'Page layout widget is not deleted and cannot be restored';
    case PageLayoutWidgetExceptionMessageKey.GRID_POSITION_REQUIRED:
      return 'Grid position is required';
-    case PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_GRID_POSITION:
+    case PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION:
      if (widgetTitle && detailedError) {
-        return `Invalid grid position for widget "${widgetTitle}": ${detailedError}`;
+        return `Invalid widget position for widget "${widgetTitle}": ${detailedError}`;
      }
      if (detailedError) {
-        return `Invalid grid position: ${detailedError}`;
+        return `Invalid widget position: ${detailedError}`;
      }

-      return 'Invalid widget grid position';
+      return 'Invalid widget position';
    case PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_CONFIGURATION:
      if (widgetTitle && widgetType && detailedError) {
        return `Invalid configuration for widget "${widgetTitle}" of type ${widgetType}: ${detailedError}`;
@@ -23,7 +23,6 @@ import {
  generatePageLayoutWidgetExceptionMessage,
 } from 'src/engine/metadata-modules/page-layout-widget/exceptions/page-layout-widget.exception';
 import { fromFlatPageLayoutWidgetToPageLayoutWidgetDto } from 'src/engine/metadata-modules/page-layout-widget/utils/from-flat-page-layout-widget-to-page-layout-widget-dto.util';
-import { validateWidgetGridPosition } from 'src/engine/metadata-modules/page-layout-widget/utils/validate-widget-grid-position.util';
 import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
 import { WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';
 import { DashboardSyncService } from 'src/modules/dashboard-sync/services/dashboard-sync.service';
@@ -200,16 +199,7 @@ export class PageLayoutWidgetService {
    const existingFlatPageLayoutWidgetMaps =
      await this.getFlatPageLayoutWidgetMaps(workspaceId);

-    const existingWidget = this.getExistingWidgetOrThrow(
-      id,
-      existingFlatPageLayoutWidgetMaps,
-    );
-
-    if (updateData.gridPosition) {
-      const titleForValidation = updateData.title ?? existingWidget.title;
-
-      validateWidgetGridPosition(updateData.gridPosition, titleForValidation);
-    }
+    this.getExistingWidgetOrThrow(id, existingFlatPageLayoutWidgetMaps);

    const updatePageLayoutWidgetInput: UpdatePageLayoutWidgetInputWithId = {
      id,
@@ -0,0 +1,74 @@
+import { msg } from '@lingui/core/macro';
+import { type PageLayoutWidgetGridPosition } from 'twenty-shared/types';
+
+import { WIDGET_GRID_MAX_COLUMNS } from 'src/engine/metadata-modules/page-layout-widget/constants/widget-grid-max-columns.constant';
+import { WIDGET_GRID_MAX_ROWS } from 'src/engine/metadata-modules/page-layout-widget/constants/widget-grid-max-rows.constant';
+import {
+  PageLayoutWidgetExceptionCode,
+  PageLayoutWidgetExceptionMessageKey,
+  generatePageLayoutWidgetExceptionMessage,
+} from 'src/engine/metadata-modules/page-layout-widget/exceptions/page-layout-widget.exception';
+import { type FlatEntityValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/types/failed-flat-entity-validation.type';
+
+export const validatePageLayoutWidgetGridPosition = (
+  position: PageLayoutWidgetGridPosition,
+  widgetTitle: string,
+): FlatEntityValidationError[] => {
+  const errors: FlatEntityValidationError[] = [];
+
+  const { row, column, rowSpan, columnSpan } = position;
+
+  if (column >= WIDGET_GRID_MAX_COLUMNS) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `column ${column} exceeds grid width (max column is ${WIDGET_GRID_MAX_COLUMNS - 1})`,
+      ),
+      userFriendlyMessage: msg`Widget extends beyond grid width`,
+    });
+  }
+
+  if (column + columnSpan > WIDGET_GRID_MAX_COLUMNS) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `widget extends beyond grid width (column ${column} + columnSpan ${columnSpan} > ${WIDGET_GRID_MAX_COLUMNS})`,
+      ),
+      userFriendlyMessage: msg`Widget extends beyond grid width`,
+    });
+  }
+
+  if (row >= WIDGET_GRID_MAX_ROWS) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `row ${row} exceeds maximum allowed rows (${WIDGET_GRID_MAX_ROWS})`,
+      ),
+      userFriendlyMessage: msg`Widget row exceeds grid height`,
+    });
+  }
+
+  if (row + rowSpan > WIDGET_GRID_MAX_ROWS) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `widget extends beyond grid height (row ${row} + rowSpan ${rowSpan} > ${WIDGET_GRID_MAX_ROWS})`,
+      ),
+      userFriendlyMessage: msg`Widget extends beyond grid height`,
+    });
+  }
+
+  return errors;
+};
@@ -0,0 +1,44 @@
+import { msg } from '@lingui/core/macro';
+import { type PageLayoutWidgetVerticalListPosition } from 'twenty-shared/types';
+
+import {
+  PageLayoutWidgetExceptionCode,
+  PageLayoutWidgetExceptionMessageKey,
+  generatePageLayoutWidgetExceptionMessage,
+} from 'src/engine/metadata-modules/page-layout-widget/exceptions/page-layout-widget.exception';
+import { type FlatEntityValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/types/failed-flat-entity-validation.type';
+
+export const validatePageLayoutWidgetVerticalListPosition = (
+  position: PageLayoutWidgetVerticalListPosition,
+  widgetTitle: string,
+): FlatEntityValidationError[] => {
+  const errors: FlatEntityValidationError[] = [];
+
+  if (position.index < 0) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `index ${position.index} must be a non-negative integer`,
+      ),
+      userFriendlyMessage: msg`Widget index must be a non-negative integer`,
+    });
+  }
+
+  if (!Number.isInteger(position.index)) {
+    errors.push({
+      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
+      message: generatePageLayoutWidgetExceptionMessage(
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
+        widgetTitle,
+        undefined,
+        `index ${position.index} must be an integer`,
+      ),
+      userFriendlyMessage: msg`Widget index must be an integer`,
+    });
+  }
+
+  return errors;
+};
@@ -16,6 +16,7 @@ type GridPosition = {
  columnSpan: number;
 };

+// TODO: remove in favor of validatePageLayoutWidgetGridPosition once gridPosition is deprecated
 export const validateWidgetGridPosition = (
  gridPosition: GridPosition,
  widgetTitle: string,
@@ -28,7 +29,7 @@ export const validateWidgetGridPosition = (
    errors.push({
      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
      message: generatePageLayoutWidgetExceptionMessage(
-        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_GRID_POSITION,
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
        widgetTitle,
        undefined,
        `column ${column} exceeds grid width (max column is ${WIDGET_GRID_MAX_COLUMNS - 1})`,
@@ -41,7 +42,7 @@ export const validateWidgetGridPosition = (
    errors.push({
      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
      message: generatePageLayoutWidgetExceptionMessage(
-        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_GRID_POSITION,
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
        widgetTitle,
        undefined,
        `widget extends beyond grid width (column ${column} + columnSpan ${columnSpan} > ${WIDGET_GRID_MAX_COLUMNS})`,
@@ -54,7 +55,7 @@ export const validateWidgetGridPosition = (
    errors.push({
      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
      message: generatePageLayoutWidgetExceptionMessage(
-        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_GRID_POSITION,
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
        widgetTitle,
        undefined,
        `row ${row} exceeds maximum allowed rows (${WIDGET_GRID_MAX_ROWS})`,
@@ -67,7 +68,7 @@ export const validateWidgetGridPosition = (
    errors.push({
      code: PageLayoutWidgetExceptionCode.INVALID_PAGE_LAYOUT_WIDGET_DATA,
      message: generatePageLayoutWidgetExceptionMessage(
-        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_GRID_POSITION,
+        PageLayoutWidgetExceptionMessageKey.INVALID_WIDGET_POSITION,
        widgetTitle,
        undefined,
        `widget extends beyond grid height (row ${row} + rowSpan ${rowSpan} > ${WIDGET_GRID_MAX_ROWS})`,
@@ -390,6 +390,7 @@ export class PageLayoutUpdateService {
          type: widgetInput.type,
          objectMetadataId: widgetInput.objectMetadataId ?? null,
          gridPosition: widgetInput.gridPosition,
+          position: widgetInput.position ?? null,
          configuration: widgetInput.configuration ?? null,
          workspaceId,
          createdAt: now.toISOString(),
@@ -416,6 +417,7 @@ export class PageLayoutUpdateService {
          type: widgetInput.type,
          objectMetadataId: widgetInput.objectMetadataId ?? null,
          gridPosition: widgetInput.gridPosition,
+          position: widgetInput.position ?? null,
          configuration: widgetInput.configuration ?? null,
          updatedAt: now.toISOString(),
        };
@@ -436,6 +438,7 @@ export class PageLayoutUpdateService {
          type: widgetInput.type,
          objectMetadataId: widgetInput.objectMetadataId ?? null,
          gridPosition: widgetInput.gridPosition,
+          position: widgetInput.position ?? null,
          configuration: widgetInput.configuration ?? null,
          deletedAt: null,
          updatedAt: now.toISOString(),