@contrail/documents 1.15.0-alpha.567dcf0 → 1.15.0-alpha.a6bee29

package/CHANGELOG.md

@@ -5,15 +5,12 @@ 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.15.0] - 2026-08-18
+## [1.15.0] - 2026-08-21
 
 ### Added
 
-- `isValidSortIndex` — whether a value is a usable fractional-indexing key. `fractional-indexing` keeps its own `validateOrderKey` private, so callers that need to check a key before storing it had no way to do so beyond a non-empty-string test. A key that passes that test but breaks the grammar still sorts, so ordering looks fine; the failure surfaces later, when the next insert beside it calls `generateKeyBetween` and throws. One point is stricter than the library: every character must be in the base-62 digit set, since a key holding anything else can sort below the integer part it claims.
-
-### Changed
-
-- `SortOrderErrorMessage.SORT_INDEX_NOT_USABLE` now reads "sortIndex must be a valid fractional-indexing key". The code is unchanged; the old text described only the non-empty-string half of the condition a caller can now check with `isValidSortIndex`.
+- `sortElementsByArrayOrder(elements, sortOrder)` and `assignSortIndexes(orderedElements)` — the two ordering transforms that convert, restore and the document read path had each grown their own copy of. `sortElementsByArrayOrder` puts elements missing from the array last, keeping their relative order.
+- `SORT_MODE` — the named constants for `DocumentSortMode`, alongside the existing `DOCUMENT_SORT_MODES` tuple.
 
 ## [1.14.0] - 2026-07-29
 

package/lib/document-element-factory.js

@@ -90,7 +90,7 @@ class DocumentElementFactory {
         return element;
     }
     static copyElements(elements, documentId, commonOptions = {}, positionOffset, lastFrameNumber) {
-        var _a, _b;
+        var _a, _b, _c;
         const oldIdToNewId = new Map();
         const newElements = [];
         const groupElements = [];
@@ -118,11 +118,10 @@ class DocumentElementFactory {
                 const oldChildElements = elements.filter((e) => e.tableId === element.id && ['cell', 'column', 'row'].indexOf(e.type) !== -1);
                 let newTableElement, newChildElements = [];
                 try {
-                    [newTableElement, ...newChildElements] = document_table_1.TableCopyService.copy(newElement, oldChildElements);
+                    [newTableElement, ...newChildElements] = document_table_1.TableCopyService.copy(element, oldChildElements);
                 }
-                catch (e) { }
-                if (oldChildElements.length > newChildElements.length || oldChildElements.length === 0) {
-                    telemetry_1.logger.warn({ newElement, oldChildElements, newChildElements }, 'Invalid table element to copy');
+                catch (e) {
+                    telemetry_1.logger.warn({ element, oldChildElements, newChildElements }, (_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : 'Invalid table element to copy');
                     continue;
                 }
                 newElement = newTableElement;
@@ -159,7 +158,7 @@ class DocumentElementFactory {
                     newElement.position.x = newElement.position.x + positionOffset.x;
                     newElement.position.y = newElement.position.y + positionOffset.y;
                 }
-                if (['line', 'callout'].includes(newElement.type) && ((_b = newElement.points) === null || _b === void 0 ? void 0 : _b.length) > 0) {
+                if (['line', 'callout'].includes(newElement.type) && ((_c = newElement.points) === null || _c === void 0 ? void 0 : _c.length) > 0) {
                     newElement.points = newElement.points.map(([x, y]) => [x + positionOffset.x, y + positionOffset.y]);
                 }
             }

package/lib/element-order.d.ts

@@ -0,0 +1,6 @@
+export interface OrderableElement {
+    id?: string;
+    sortIndex?: string;
+}
+export declare function sortElementsByArrayOrder<T extends OrderableElement>(elements: T[], sortOrder?: string[]): T[];
+export declare function assignSortIndexes<T extends OrderableElement>(orderedElements: T[]): T[];

package/lib/element-order.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortElementsByArrayOrder = sortElementsByArrayOrder;
+exports.assignSortIndexes = assignSortIndexes;
+const sort_index_1 = require("./sort-index");
+function sortElementsByArrayOrder(elements, sortOrder) {
+    if (!(sortOrder === null || sortOrder === void 0 ? void 0 : sortOrder.length)) {
+        return [...elements];
+    }
+    const positionById = new Map(sortOrder.map((id, index) => [id, index]));
+    const unorderedPosition = sortOrder.length;
+    return [...elements].sort((a, b) => { var _a, _b; return ((_a = positionById.get(a.id)) !== null && _a !== void 0 ? _a : unorderedPosition) - ((_b = positionById.get(b.id)) !== null && _b !== void 0 ? _b : unorderedPosition); });
+}
+function assignSortIndexes(orderedElements) {
+    const sortIndexes = (0, sort_index_1.buildNKeysBetween)(null, null, orderedElements.length);
+    return orderedElements.map((element, index) => (Object.assign(Object.assign({}, element), { sortIndex: sortIndexes[index] })));
+}

package/lib/index.d.ts

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

package/lib/index.js

@@ -16,6 +16,7 @@ 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("./element-order"), exports);
 __exportStar(require("./sort-order-errors"), exports);
 __exportStar(require("./components"), exports);
 __exportStar(require("./document-element-factory"), exports);

package/lib/sort-index.d.ts

@@ -1,6 +1,5 @@
 import { DocumentElement } from './types';
 export declare function allElementsHaveSortIndex(elements: unknown[]): boolean;
-export declare function isValidSortIndex(sortIndex: unknown): sortIndex is string;
 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

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allElementsHaveSortIndex = allElementsHaveSortIndex;
-exports.isValidSortIndex = isValidSortIndex;
 exports.buildKeyBetween = buildKeyBetween;
 exports.buildNKeysBetween = buildNKeysBetween;
 exports.compareSortIndex = compareSortIndex;
@@ -10,26 +9,6 @@ function allElementsHaveSortIndex(elements) {
     return elements.every((element) => typeof element.sortIndex === 'string' &&
         element.sortIndex.length > 0);
 }
-const SMALLEST_INTEGER = 'A00000000000000000000000000';
-function getIntegerPartLength(head) {
-    if (head >= 'a' && head <= 'z')
-        return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2;
-    if (head >= 'A' && head <= 'Z')
-        return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2;
-    return null;
-}
-function isValidSortIndex(sortIndex) {
-    if (typeof sortIndex !== 'string' || sortIndex.length === 0)
-        return false;
-    if (sortIndex === SMALLEST_INTEGER)
-        return false;
-    if (![...sortIndex].every((character) => fractional_indexing_1.BASE_62_DIGITS.includes(character)))
-        return false;
-    const integerPartLength = getIntegerPartLength(sortIndex[0]);
-    if (integerPartLength === null || integerPartLength > sortIndex.length)
-        return false;
-    return !sortIndex.slice(integerPartLength).endsWith('0');
-}
 function buildKeyBetween(a, b) {
     return (0, fractional_indexing_1.generateKeyBetween)(a, b);
 }

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

@@ -6,5 +6,5 @@ export declare enum SortOrderErrorCode {
 export declare enum SortOrderErrorMessage {
     SORT_MIGRATION_IN_PROGRESS = "Sort order is being migrated for this document; editing is briefly locked",
     SORT_MODE_MISMATCH = "Ordering write does not match the document's sort mode",
-    SORT_INDEX_NOT_USABLE = "sortIndex must be a valid fractional-indexing key"
+    SORT_INDEX_NOT_USABLE = "sortIndex must be a non-empty string"
 }

package/lib/sort-order-errors.js

@@ -11,5 +11,5 @@ var SortOrderErrorMessage;
 (function (SortOrderErrorMessage) {
     SortOrderErrorMessage["SORT_MIGRATION_IN_PROGRESS"] = "Sort order is being migrated for this document; editing is briefly locked";
     SortOrderErrorMessage["SORT_MODE_MISMATCH"] = "Ordering write does not match the document's sort mode";
-    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a valid fractional-indexing key";
+    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a non-empty string";
 })(SortOrderErrorMessage || (exports.SortOrderErrorMessage = SortOrderErrorMessage = {}));

package/lib/types/document.d.ts

@@ -7,6 +7,11 @@ export interface ImportReferenceDetail {
 export type DocumentWriteMode = 'transactional' | 'legacy';
 export declare const DOCUMENT_SORT_MODES: readonly ["array", "elementIndexing", "migrating"];
 export type DocumentSortMode = (typeof DOCUMENT_SORT_MODES)[number];
+export declare const SORT_MODE: {
+    readonly ARRAY: "array";
+    readonly ELEMENT_INDEXING: "elementIndexing";
+    readonly MIGRATING: "migrating";
+};
 export interface Document {
     id?: string;
     name?: string;

package/lib/types/document.js

@@ -1,4 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DOCUMENT_SORT_MODES = void 0;
+exports.SORT_MODE = exports.DOCUMENT_SORT_MODES = void 0;
 exports.DOCUMENT_SORT_MODES = ['array', 'elementIndexing', 'migrating'];
+exports.SORT_MODE = {
+    ARRAY: 'array',
+    ELEMENT_INDEXING: 'elementIndexing',
+    MIGRATING: 'migrating',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "1.15.0-alpha.567dcf0",
+  "version": "1.15.0-alpha.a6bee29",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@contrail/actions": "^1.0.18",
-    "@contrail/document-table": "^1.1.0",
+    "@contrail/document-table": "^1.2.3",
     "@contrail/document-util": "^1.2.0",
     "@contrail/types": "^3.4.0",
     "fractional-indexing": "^2.1.0",