@contrail/documents 1.11.0 → 1.12.0-alpha.aad6f60

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to `@contrail/documents` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.0] - 2026-07-21
+
+### Added
+
+- Reliable sort-order surface (PLAT-1270): `Document.sortMode` (`'array' | 'elementIndexing' | 'migrating'`, `undefined` = `array`; `'migrating'` is the transient mid-convert state where ordering edits are rejected); `DocumentElement.sortIndex` (fractional-indexing key).
+- Sort utilities: `buildKeyBetween` / `buildNKeysBetween` (generate index key(s) between two neighbours), `compareSortIndex` (`(sortIndex, id)` comparator), and `allElementsHaveSortIndex`.
+- `SortOrderErrorCode` / `SortOrderErrorMessage` — structured code for the mid-convert freeze (`SORT_MIGRATION_IN_PROGRESS`).
+
 ## [1.11.0] - 2026-06-29
 
 ### Added

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 export * from './types';
+export * from './sort-index';
+export * from './sort-order-errors';
 export * from './components';
 export * from './document-element-factory';
 export * from './document-element-property-binding-handler';

package/lib/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
+__exportStar(require("./sort-index"), exports);
+__exportStar(require("./sort-order-errors"), exports);
 __exportStar(require("./components"), exports);
 __exportStar(require("./document-element-factory"), exports);
 __exportStar(require("./document-element-property-binding-handler"), exports);

package/lib/sort-index.d.ts

@@ -0,0 +1,5 @@
+import { DocumentElement } from './types';
+export declare function allElementsHaveSortIndex(elements: unknown[]): boolean;
+export declare function buildKeyBetween(a: string | null, b: string | null): string;
+export declare function buildNKeysBetween(a: string | null, b: string | null, n: number): string[];
+export declare function compareSortIndex(a: DocumentElement, b: DocumentElement): number;

package/lib/sort-index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allElementsHaveSortIndex = allElementsHaveSortIndex;
+exports.buildKeyBetween = buildKeyBetween;
+exports.buildNKeysBetween = buildNKeysBetween;
+exports.compareSortIndex = compareSortIndex;
+const fractional_indexing_1 = require("fractional-indexing");
+function allElementsHaveSortIndex(elements) {
+    return elements.every((element) => typeof element.sortIndex === 'string' &&
+        element.sortIndex.length > 0);
+}
+function buildKeyBetween(a, b) {
+    return (0, fractional_indexing_1.generateKeyBetween)(a, b);
+}
+function buildNKeysBetween(a, b, n) {
+    return (0, fractional_indexing_1.generateNKeysBetween)(a, b, n);
+}
+function compareSortIndex(a, b) {
+    var _a, _b, _c, _d;
+    const ai = (_a = a.sortIndex) !== null && _a !== void 0 ? _a : '';
+    const bi = (_b = b.sortIndex) !== null && _b !== void 0 ? _b : '';
+    if (ai !== bi)
+        return ai < bi ? -1 : 1;
+    const aid = (_c = a.id) !== null && _c !== void 0 ? _c : '';
+    const bid = (_d = b.id) !== null && _d !== void 0 ? _d : '';
+    return aid === bid ? 0 : aid < bid ? -1 : 1;
+}

package/lib/sort-order-errors.d.ts

@@ -0,0 +1,6 @@
+export declare enum SortOrderErrorCode {
+    SORT_MIGRATION_IN_PROGRESS = "SORT_MIGRATION_IN_PROGRESS"
+}
+export declare enum SortOrderErrorMessage {
+    SORT_MIGRATION_IN_PROGRESS = "Sort order is being migrated for this document; editing is briefly locked"
+}

package/lib/sort-order-errors.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SortOrderErrorMessage = exports.SortOrderErrorCode = void 0;
+var SortOrderErrorCode;
+(function (SortOrderErrorCode) {
+    SortOrderErrorCode["SORT_MIGRATION_IN_PROGRESS"] = "SORT_MIGRATION_IN_PROGRESS";
+})(SortOrderErrorCode || (exports.SortOrderErrorCode = SortOrderErrorCode = {}));
+var SortOrderErrorMessage;
+(function (SortOrderErrorMessage) {
+    SortOrderErrorMessage["SORT_MIGRATION_IN_PROGRESS"] = "Sort order is being migrated for this document; editing is briefly locked";
+})(SortOrderErrorMessage || (exports.SortOrderErrorMessage = SortOrderErrorMessage = {}));

package/lib/types/document-element.d.ts

@@ -17,6 +17,7 @@ export interface DocumentElement extends Document {
     id?: string;
     specifiedId?: string;
     documentId?: string;
+    sortIndex?: string;
     type?: string;
     rotate?: RotationDefinition;
     scale?: ScaleTransformation;

package/lib/types/document.d.ts

@@ -5,6 +5,7 @@ export interface ImportReferenceDetail {
     importedFileReference?: string;
 }
 export type DocumentWriteMode = 'transactional' | 'legacy';
+export type DocumentSortMode = 'array' | 'elementIndexing' | 'migrating';
 export interface Document {
     id?: string;
     name?: string;
@@ -25,4 +26,5 @@ export interface Document {
     ownedByReference?: string;
     writeMode?: DocumentWriteMode;
     lastSequenceNumber?: number;
+    sortMode?: DocumentSortMode;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "1.11.0",
+  "version": "1.12.0-alpha.aad6f60",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -43,6 +43,7 @@
     "@contrail/document-table": "^1.1.0",
     "@contrail/document-util": "^1.2.0",
     "@contrail/types": "^3.4.0",
+    "fractional-indexing": "^2.1.0",
     "reflect-metadata": "^0.1.13"
   },
   "peerDependencies": {