🔢 Reorder and sort table columns

cypress/e2e/tables-table.cy.js

@@ -71,7 +71,7 @@ describe('Manage a table', () => {
 		// Updating the title is flaky, so skipping it for now
 		// cy.get('[data-cy="editTableModal"] [data-cy="editTableTitleInput"]').should('be.visible').should('be.enabled')
 		// cy.get('[data-cy="editTableModal"] [data-cy="editTableTitleInput"]').clear().type('ToDo list')
-		cy.get('.modal__content #description-editor .tiptap.ProseMirror').type('Updated ToDo List description')
+		cy.get('[data-cy="editTableModal"] #description-editor .tiptap.ProseMirror').type('Updated ToDo List description')
 		cy.get('[data-cy="editTableSaveBtn"]').should('be.enabled').click()
 
 		cy.wait(10).get('.toastify.toast-success').should('be.visible')

lib/Controller/ApiTablesController.php

@@ -130,12 +130,14 @@ public function showScheme(int $id): DataResponse {
 	 * @param string $description description
 	 * @param list<TablesColumn> $columns columns
 	 * @param list<TablesView> $views views
+	 * @param list<array{columnId: int, order: int, readonly: bool}> $columnOrder Default column order settings
+	 * @param list<array{columnId: int, mode: 'ASC'|'DESC'}> $sort Default sort rules
 	 * @return DataResponse<Http::STATUS_OK, TablesTable, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
 	 *
 	 * 200: Tables returned
 	 */
 	#[NoAdminRequired]
-	public function createFromScheme(string $title, string $emoji, string $description, array $columns, array $views): DataResponse {
+	public function createFromScheme(string $title, string $emoji, string $description, array $columns, array $views, array $columnOrder = [], array $sort = []): DataResponse {
 		try {
 			$this->db->beginTransaction();
 			$table = $this->service->create($title, 'custom', $emoji, $description);
@@ -175,6 +177,21 @@ public function createFromScheme(string $title, string $emoji, string $descripti
 				);
 				$colMap[$column['id']] = $col->getId();
 			}
+			if (!empty($columnOrder) || !empty($sort)) {
+				$remappedColumnOrder = !empty($columnOrder) ? array_map(static function (array $entry) use ($colMap): array {
+					if (isset($entry['columnId']) && $entry['columnId'] > 0) {
+						$entry['columnId'] = $colMap[$entry['columnId']] ?? $entry['columnId'];
+					}
+					return $entry;
+				}, $columnOrder) : null;
+				$remappedSort = !empty($sort) ? array_map(static function (array $entry) use ($colMap): array {
+					if (isset($entry['columnId']) && $entry['columnId'] > 0) {
+						$entry['columnId'] = $colMap[$entry['columnId']] ?? $entry['columnId'];
+					}
+					return $entry;
+				}, $sort) : null;
+				$table = $this->service->update($table->getId(), null, null, null, null, $this->userId, $remappedColumnOrder, $remappedSort);
+			}
 			foreach ($views as $view) {
 				$newView = $this->viewService->create(
 					$view['title'],
@@ -262,6 +279,8 @@ public function create(string $title, ?string $emoji, ?string $description, stri
 	 * @param string|null $emoji New table emoji
 	 * @param bool $archived whether the table is archived
 	 * @param string $description the tables description
+	 * @param list<array{columnId: int, order: int, readonly: bool}>|string|null $columnSettings Default column order settings (array or JSON string)
+	 * @param list<array{columnId: int, mode: 'ASC'|'DESC'}>|string|null $sort Default sort rules (array or JSON string)
 	 * @return DataResponse<Http::STATUS_OK, TablesTable, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
 	 *
 	 * 200: Tables returned
@@ -270,9 +289,15 @@ public function create(string $title, ?string $emoji, ?string $description, stri
 	 */
 	#[NoAdminRequired]
 	#[RequirePermission(permission: Application::PERMISSION_MANAGE, type: Application::NODE_TYPE_TABLE, idParam: 'id')]
-	public function update(int $id, ?string $title = null, ?string $emoji = null, ?string $description = null, ?bool $archived = null): DataResponse {
+	public function update(int $id, ?string $title = null, ?string $emoji = null, ?string $description = null, ?bool $archived = null, null|array|string $columnSettings = null, null|array|string $sort = null): DataResponse {
+		if (is_string($columnSettings)) {
+			$columnSettings = json_decode($columnSettings, true) ?? null;
+		}
+		if (is_string($sort)) {
+			$sort = json_decode($sort, true) ?? null;
+		}
 		try {
-			return new DataResponse($this->service->update($id, $title, $emoji, $description, $archived, $this->userId)->jsonSerialize());
+			return new DataResponse($this->service->update($id, $title, $emoji, $description, $archived, $this->userId, $columnSettings, $sort)->jsonSerialize());
 		} catch (PermissionError $e) {
 			return $this->handlePermissionError($e);
 		} catch (InternalError $e) {

lib/Controller/TableController.php

@@ -70,9 +70,15 @@ public function destroy(int $id): DataResponse {
 
 	#[NoAdminRequired]
 	#[RequirePermission(permission: Application::PERMISSION_MANAGE, type: Application::NODE_TYPE_TABLE, idParam: 'id')]
-	public function update(int $id, ?string $title = null, ?string $emoji = null, ?bool $archived = null): DataResponse {
-		return $this->handleError(function () use ($id, $title, $emoji, $archived) {
-			return $this->service->update($id, $title, $emoji, null, $archived, $this->userId);
+	public function update(int $id, ?string $title = null, ?string $emoji = null, ?bool $archived = null, null|array|string $columnSettings = null, null|array|string $sort = null): DataResponse {
+		if (is_string($columnSettings)) {
+			$columnSettings = json_decode($columnSettings, true) ?? null;
+		}
+		if (is_string($sort)) {
+			$sort = json_decode($sort, true) ?? null;
+		}
+		return $this->handleError(function () use ($id, $title, $emoji, $archived, $columnSettings, $sort) {
+			return $this->service->update($id, $title, $emoji, null, $archived, $this->userId, $columnSettings, $sort);
 		});
 	}
 }

lib/Db/Table.php

@@ -9,7 +9,9 @@
 
 use JsonSerializable;
 use OCA\Tables\Model\Permissions;
+use OCA\Tables\Model\SortRuleSet;
 use OCA\Tables\ResponseDefinitions;
+use OCA\Tables\Service\ValueObject\ViewColumnInformation;
 
 /**
  * @psalm-suppress PropertyNotSetInConstructor
@@ -46,6 +48,10 @@
  * @method setViews(array $views)
  * @method getColumns(): array
  * @method setColumns(array $columns)
+ * @method getColumnOrder(): ?string
+ * @method setColumnOrder(?string $columnOrder)
+ * @method getSort(): ?string
+ * @method setSort(?string $sort)
  * @method getCreatedBy(): string
  * @method setCreatedBy(string $createdBy)
  * @method getCreatedAt(): string
@@ -66,6 +72,9 @@ class Table extends EntitySuper implements JsonSerializable {
 	protected bool $archived = false;
 	protected ?string $description = null;
 
+	protected ?string $columnOrder = null; // json
+	protected ?string $sort = null; // json
+
 	// virtual properties
 	protected ?bool $isShared = null;
 	protected ?Permissions $onSharePermissions = null;
@@ -107,6 +116,8 @@ public function jsonSerialize(): array {
 			'columnsCount' => $this->columnsCount ?: 0,
 			'views' => $this->getViewsArray(),
 			'description' => $this->description ?:'',
+			'columnOrder' => $this->getColumnOrderSettingsArray(),
+			'sort' => $this->getSortArray(),
 		];
 	}
 
@@ -121,4 +132,53 @@ private function getSharePermissions(): ?Permissions {
 	private function getViewsArray(): array {
 		return $this->getViews() ?: [];
 	}
+
+	/**
+	 * @psalm-suppress MismatchingDocblockReturnType
+	 * @return int[]
+	 */
+	public function getColumnOrderArray(): array {
+		$columnSettings = $this->getColumnOrderSettingsArray();
+		usort($columnSettings, static function (ViewColumnInformation $a, ViewColumnInformation $b) {
+			return $a->getOrder() - $b->getOrder();
+		});
+		return array_map(static fn (ViewColumnInformation $vci): int => $vci->getId(), $columnSettings);
+	}
+
+	/**
+	 * @return array<ViewColumnInformation>
+	 */
+	public function getColumnOrderSettingsArray(): array {
+		$columns = $this->getArray($this->getColumnOrder());
+		if (empty($columns)) {
+			return [];
+		}
+
+		if (is_array(reset($columns))) {
+			return array_values(array_map(static fn (array $a): ViewColumnInformation => ViewColumnInformation::fromArray($a), $columns));
+		}
+
+		$result = [];
+		foreach ($columns as $index => $columnId) {
+			$result[] = new ViewColumnInformation($columnId, order: (int)$index + 1);
+		}
+		return $result;
+	}
+
+	/**
+	 * @psalm-suppress MismatchingDocblockReturnType
+	 * @return list<array{columnId: int, mode: 'ASC'|'DESC'}>
+	 */
+	public function getSortArray(): array {
+		$rawSortRules = $this->getArray($this->getSort());
+		return SortRuleSet::createFromInputArray($rawSortRules)->jsonSerialize();
+	}
+
+	private function getArray(?string $json): array {
+		if ($json !== '' && $json !== null && $json !== 'null') {
+			return \json_decode($json, true);
+		} else {
+			return [];
+		}
+	}
 }

lib/Migration/Version2010Date20260414000000.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Tables\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+use Override;
+
+class Version2010Date20260414000000 extends SimpleMigrationStep {
+
+	#[Override]
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+
+		if (!$schema->hasTable('tables_tables')) {
+			return null;
+		}
+
+		$tablesTables = $schema->getTable('tables_tables');
+
+		if (!$tablesTables->hasColumn('column_order')) {
+			$tablesTables->addColumn('column_order', Types::TEXT, [
+				'notnull' => false,
+				'default' => null,
+				'comment' => 'JSON array of ViewColumnInformation — default column order for the table',
+			]);
+		}
+
+		if (!$tablesTables->hasColumn('sort')) {
+			$tablesTables->addColumn('sort', Types::TEXT, [
+				'notnull' => false,
+				'default' => null,
+				'comment' => 'JSON array of sort rules — default row sort for the table',
+			]);
+		}
+
+		return $schema;
+	}
+}

lib/Model/TableScheme.php

@@ -23,14 +23,18 @@ class TableScheme implements JsonSerializable {
 	protected ?array $views = null;
 	protected ?string $description = null;
 	protected ?string $tablesVersion = null;
+	protected array $columnOrder = [];
+	protected array $sort = [];
 
-	public function __construct(string $title, string $emoji, array $columns, array $view, string $description, string $tablesVersion) {
+	public function __construct(string $title, string $emoji, array $columns, array $view, string $description, string $tablesVersion, array $columnOrder = [], array $sort = []) {
 		$this->tablesVersion = $tablesVersion;
 		$this->title = $title;
 		$this->emoji = $emoji;
 		$this->columns = $columns;
 		$this->description = $description;
 		$this->views = $view;
+		$this->columnOrder = $columnOrder;
+		$this->sort = $sort;
 	}
 
 	public function getTitle():string {
@@ -43,8 +47,10 @@ public function jsonSerialize(): array {
 			'emoji' => $this->emoji,
 			'columns' => $this->columns,
 			'views' => $this->views,
-			'description' => $this->description ?:'',
+			'description' => $this->description ?: '',
 			'tablesVersion' => $this->tablesVersion,
+			'columnOrder' => $this->columnOrder,
+			'sort' => $this->sort,
 		];
 	}
 

lib/Model/ViewUpdateInput.php

@@ -81,12 +81,12 @@ public static function fromInputArray(array $data): self {
 		}
 
 		return new self(
-			title: $data['title'] ? new Title($data['title']) : null,
+			title: ($data['title'] ?? null) ? new Title($data['title']) : null,
 			description: $data['description'] ?? null,
-			emoji: $data['emoji'] ? new Emoji($data['emoji']) : null,
-			columnSettings: $data['columnSettings'] ? ColumnSettings::createFromInputArray($data['columnSettings']) : null,
-			filterSet: $data['filter'] ? FilterSet::createFromInputArray($data['filter']) : null,
-			sortRuleSet: $data['sort'] ? SortRuleSet::createFromInputArray($data['sort']) : null,
+			emoji: ($data['emoji'] ?? null) ? new Emoji($data['emoji']) : null,
+			columnSettings: ($data['columnSettings'] ?? null) ? ColumnSettings::createFromInputArray($data['columnSettings']) : null,
+			filterSet: ($data['filter'] ?? null) ? FilterSet::createFromInputArray($data['filter']) : null,
+			sortRuleSet: ($data['sort'] ?? null) ? SortRuleSet::createFromInputArray($data['sort']) : null,
 		);
 	}
 

lib/ResponseDefinitions.php

@@ -66,6 +66,8 @@
  *  rowsCount: int,
  *  views: list<TablesView>,
  *  columnsCount: int,
+ *  columnOrder: list<array{columnId: int, order: int, readonly: bool}>,
+ *  sort: list<array{columnId: int, mode: 'ASC'|'DESC'}>,
  * }
  *
  * @psalm-type TablesIndex = array{

lib/Service/ColumnService.php

@@ -47,6 +47,9 @@ class ColumnService extends SuperService {
 
 	private ColumnDtoValidator $columnDtoValidator;
 
+	/** @var array<int, int[]> Per-request cache of sorted column-id order, keyed by tableId. */
+	private array $columnOrderCache = [];
+
 	public function __construct(
 		PermissionsService $permissionsService,
 		LoggerInterface $logger,
@@ -74,10 +77,40 @@ public function __construct(
 	 * @throws InternalError
 	 * @throws PermissionError
 	 */
-	public function findAllByTable(int $tableId, ?string $userId = null): array {
+	public function findAllByTable(int $tableId, ?string $userId = null, ?Table $table = null): array {
 		if ($this->permissionsService->canReadColumnsByTableId($tableId, $userId)) {
 			try {
-				return $this->enhanceColumns($this->mapper->findAllByTable($tableId));
+				$columns = $this->enhanceColumns($this->mapper->findAllByTable($tableId));
+
+				// Apply table-level default column order when set.
+				// Use a per-request cache to avoid a redundant DB fetch when the
+				// caller did not pass the Table entity and the TableMapper cache
+				// is cold (e.g. CLI/migration paths with $userId = '').
+				if (!array_key_exists($tableId, $this->columnOrderCache)) {
+					$entity = $table ?? $this->tableMapper->find($tableId);
+					$this->columnOrderCache[$tableId] = $entity->getColumnOrderArray();
+				}
+				$columnOrder = $this->columnOrderCache[$tableId];
+				if (!empty($columnOrder)) {
+					$indexed = [];
+					foreach ($columns as $column) {
+						$indexed[$column->getId()] = $column;
+					}
+					$ordered = [];
+					foreach ($columnOrder as $id) {
+						if (isset($indexed[$id])) {
+							$ordered[] = $indexed[$id];
+							unset($indexed[$id]);
+						}
+					}
+					// append any columns not listed in the order (e.g. newly added)
+					foreach ($indexed as $column) {
+						$ordered[] = $column;
+					}
+					return $ordered;
+				}
+
+				return $columns;
 			} catch (\OCP\DB\Exception $e) {
 				$this->logger->error($e->getMessage(), ['exception' => $e]);
 				throw new InternalError(get_class($this) . ' - ' . __FUNCTION__ . ': ' . $e->getMessage());

lib/Service/RowService.php

@@ -97,7 +97,10 @@ public function findAllByTable(int $tableId, string $userId, ?int $limit = null,
 				$tableColumns = $this->columnMapper->findAllByTable($tableId);
 				$showColumnIds = array_map(fn (Column $column) => $column->getId(), $tableColumns);
 
-				return $this->row2Mapper->findAll($showColumnIds, $tableId, $limit, $offset, null, null, $userId);
+				$table = $this->tableMapper->find($tableId);
+				$sort = $table->getSortArray() ?: null;
+
+				return $this->row2Mapper->findAll($showColumnIds, $tableId, $limit, $offset, null, $sort, $userId);
 			} else {
 				throw new PermissionError('no read access to table id = ' . $tableId);
 			}