@contrail/documents 1.15.0-alpha.8841401 → 1.15.0-alpha.a213e4a

package/CHANGELOG.md

@@ -5,12 +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-20
+## [1.15.0] - 2026-08-21
 
 ### Added
 
-- `MaskDefinition` and `MaskShapeKey` on `DocumentElement` — `maskDefinition` records that an image is masked into one of nine preset shapes, with an optional clockwise `rotation`. Its presence changes how `cropDefinition`'s percents are read: element-space (the mask window within the element) instead of the source-image crop they otherwise mean. Anything deriving image geometry must check `hasShapeMask` before treating a crop as a source crop — reading one as the other samples the wrong region of the bitmap.
-- `@contrail/documents/util/mask` — the shared mask model, exported from the package root: the nine shapes as renderer-agnostic cubic path segments (`getMaskShapeSegments`), `rotatedRectAABB` for the bounds a tilted shape actually occupies, `rotatePoint`, the mask-rect/percent conversions, and `MASK_SHAPE_PRESET_GEOMETRY` mapping each shape to its OOXML preset so exporters and the canvas cannot drift apart. Segments are cubic-only because cubics survive affine maps exactly, letting each consumer render them however it draws — `Path2D` in a browser, preset geometry in pptx.
+- `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`. `DocumentSortMode` and `DOCUMENT_SORT_MODES` are now derived from it, so the mode values are declared in exactly one place. `DOCUMENT_SORT_MODES` is now `readonly DocumentSortMode[]` rather than a literal tuple; it stays exported because it is the runtime list behind the entity's `@IsIn` validation.
 
 ## [1.14.0] - 2026-07-29
 

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';
@@ -11,5 +12,4 @@ export * from './document-element-constants';
 export * from './util/curved-line/point';
 export * from './util/curved-line/curved-line';
 export * from './util/callout/callout';
-export * from './util/mask';
 export * from './document-frame.service';

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);
@@ -27,5 +28,4 @@ __exportStar(require("./document-element-constants"), exports);
 __exportStar(require("./util/curved-line/point"), exports);
 __exportStar(require("./util/curved-line/curved-line"), exports);
 __exportStar(require("./util/callout/callout"), exports);
-__exportStar(require("./util/mask"), exports);
 __exportStar(require("./document-frame.service"), exports);

package/lib/types/common.d.ts

@@ -74,11 +74,6 @@ export interface LineDefinition {
     markerEnd?: string;
     lineType?: LineType;
 }
-export type MaskShapeKey = 'circle' | 'square' | 'rounded' | 'triangle' | 'diamond' | 'parallelogram' | 'star' | 'heart' | 'cloud';
-export interface MaskDefinition {
-    shape: MaskShapeKey;
-    rotation?: number;
-}
 export interface CropDefinition {
     x1?: number;
     x2?: number;

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

@@ -1,5 +1,5 @@
 import { PropertyLevel } from '@contrail/types';
-import { CropDefinition, LineDefinition, MaskDefinition, PositionDefinition, RotationDefinition, SizeDefinition } from './common';
+import { CropDefinition, LineDefinition, PositionDefinition, RotationDefinition, SizeDefinition } from './common';
 import { Document } from './document';
 import { ScaleTransformation } from './element-transformation';
 export interface AlternateUrls {
@@ -32,7 +32,6 @@ export interface DocumentElement extends Document {
     annotations?: any;
     isLocked?: boolean;
     cropDefinition?: CropDefinition;
-    maskDefinition?: MaskDefinition;
     embedInfo?: any;
     isHidden?: boolean;
     elementIds?: Array<string>;

package/lib/types/document.d.ts

@@ -5,8 +5,13 @@ export interface ImportReferenceDetail {
     importedFileReference?: string;
 }
 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 type DocumentSortMode = (typeof SORT_MODE)[keyof typeof SORT_MODE];
+export declare const DOCUMENT_SORT_MODES: readonly DocumentSortMode[];
 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.DOCUMENT_SORT_MODES = ['array', 'elementIndexing', 'migrating'];
+exports.DOCUMENT_SORT_MODES = exports.SORT_MODE = void 0;
+exports.SORT_MODE = {
+    ARRAY: 'array',
+    ELEMENT_INDEXING: 'elementIndexing',
+    MIGRATING: 'migrating',
+};
+exports.DOCUMENT_SORT_MODES = Object.values(exports.SORT_MODE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "1.15.0-alpha.8841401",
+  "version": "1.15.0-alpha.a213e4a",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/lib/util/mask/index.d.ts

@@ -1,4 +0,0 @@
-export * from './mask-shape-geometry';
-export * from './rotation-math';
-export * from './shape-mask-element';
-export * from './mask-preset-geometry';

package/lib/util/mask/index.js

@@ -1,20 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./mask-shape-geometry"), exports);
-__exportStar(require("./rotation-math"), exports);
-__exportStar(require("./shape-mask-element"), exports);
-__exportStar(require("./mask-preset-geometry"), exports);

package/lib/util/mask/mask-preset-geometry.d.ts

@@ -1,3 +0,0 @@
-import { MaskShapeKey } from './mask-shape-geometry';
-export declare const MASK_SHAPE_PRESET_GEOMETRY: Record<MaskShapeKey, string>;
-export declare function getMaskPresetGeometry(shape: MaskShapeKey | null): string | null;

package/lib/util/mask/mask-preset-geometry.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MASK_SHAPE_PRESET_GEOMETRY = void 0;
-exports.getMaskPresetGeometry = getMaskPresetGeometry;
-exports.MASK_SHAPE_PRESET_GEOMETRY = {
-    circle: 'ellipse',
-    square: 'rect',
-    rounded: 'roundRect',
-    triangle: 'triangle',
-    diamond: 'diamond',
-    parallelogram: 'parallelogram',
-    star: 'star5',
-    heart: 'heart',
-    cloud: 'cloud',
-};
-function getMaskPresetGeometry(shape) {
-    var _a;
-    return shape ? (_a = exports.MASK_SHAPE_PRESET_GEOMETRY[shape]) !== null && _a !== void 0 ? _a : null : null;
-}

package/lib/util/mask/mask-shape-geometry.d.ts

@@ -1,26 +0,0 @@
-import { MaskShapeKey } from '../../types';
-export { MaskShapeKey };
-export declare const MASK_SHAPE_KEYS: readonly MaskShapeKey[];
-export interface MaskRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-export type PathSegment = {
-    op: 'move' | 'line';
-    x: number;
-    y: number;
-} | {
-    op: 'cubic';
-    c1x: number;
-    c1y: number;
-    c2x: number;
-    c2y: number;
-    x: number;
-    y: number;
-} | {
-    op: 'close';
-};
-export declare function getMaskShapeSegments(shape: MaskShapeKey, rect: MaskRect, rotationDeg?: number): PathSegment[];
-export declare function rotatedRectAABB(rect: MaskRect, rotationDeg: number): MaskRect;

package/lib/util/mask/mask-shape-geometry.js

@@ -1,154 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MASK_SHAPE_KEYS = void 0;
-exports.getMaskShapeSegments = getMaskShapeSegments;
-exports.rotatedRectAABB = rotatedRectAABB;
-const rotation_math_1 = require("./rotation-math");
-exports.MASK_SHAPE_KEYS = [
-    'circle',
-    'square',
-    'rounded',
-    'triangle',
-    'diamond',
-    'parallelogram',
-    'star',
-    'heart',
-    'cloud',
-];
-const K = 0.5522847498;
-function polygon(points) {
-    const [first, ...rest] = points;
-    return [
-        { op: 'move', x: first[0], y: first[1] },
-        ...rest.map(([x, y]) => ({ op: 'line', x, y })),
-        { op: 'close' },
-    ];
-}
-function ellipse(cx, cy, rx, ry) {
-    return [
-        { op: 'move', x: cx + rx, y: cy },
-        { op: 'cubic', c1x: cx + rx, c1y: cy + K * ry, c2x: cx + K * rx, c2y: cy + ry, x: cx, y: cy + ry },
-        { op: 'cubic', c1x: cx - K * rx, c1y: cy + ry, c2x: cx - rx, c2y: cy + K * ry, x: cx - rx, y: cy },
-        { op: 'cubic', c1x: cx - rx, c1y: cy - K * ry, c2x: cx - K * rx, c2y: cy - ry, x: cx, y: cy - ry },
-        { op: 'cubic', c1x: cx + K * rx, c1y: cy - ry, c2x: cx + rx, c2y: cy - K * ry, x: cx + rx, y: cy },
-        { op: 'close' },
-    ];
-}
-function roundedRect(x, y, w, h, r) {
-    const x2 = x + w;
-    const y2 = y + h;
-    return [
-        { op: 'move', x: x + r, y },
-        { op: 'line', x: x2 - r, y },
-        { op: 'cubic', c1x: x2 - r + K * r, c1y: y, c2x: x2, c2y: y + r - K * r, x: x2, y: y + r },
-        { op: 'line', x: x2, y: y2 - r },
-        { op: 'cubic', c1x: x2, c1y: y2 - r + K * r, c2x: x2 - r + K * r, c2y: y2, x: x2 - r, y: y2 },
-        { op: 'line', x: x + r, y: y2 },
-        { op: 'cubic', c1x: x + r - K * r, c1y: y2, c2x: x, c2y: y2 - r + K * r, x, y: y2 - r },
-        { op: 'line', x, y: y + r },
-        { op: 'cubic', c1x: x, c1y: y + r - K * r, c2x: x + r - K * r, c2y: y, x: x + r, y },
-        { op: 'close' },
-    ];
-}
-const UNIT_SEGMENTS = {
-    circle: ellipse(50, 50, 49, 49),
-    square: polygon([
-        [1, 1],
-        [99, 1],
-        [99, 99],
-        [1, 99],
-    ]),
-    rounded: roundedRect(1, 1, 98, 98, 16),
-    triangle: polygon([
-        [50, 3],
-        [97, 96],
-        [3, 96],
-    ]),
-    diamond: polygon([
-        [50, 2],
-        [98, 50],
-        [50, 98],
-        [2, 50],
-    ]),
-    parallelogram: polygon([
-        [27, 12],
-        [98, 12],
-        [73, 88],
-        [2, 88],
-    ]),
-    star: polygon([
-        [50, 3],
-        [61, 37],
-        [97, 37],
-        [68, 59],
-        [79, 95],
-        [50, 73],
-        [21, 95],
-        [32, 59],
-        [3, 37],
-        [39, 37],
-    ]),
-    heart: [
-        { op: 'move', x: 50, y: 90 },
-        { op: 'cubic', c1x: 6, c1y: 58, c2x: 10, c2y: 20, x: 32, y: 18 },
-        { op: 'cubic', c1x: 44, c1y: 17, c2x: 50, c2y: 27, x: 50, y: 34 },
-        { op: 'cubic', c1x: 50, c1y: 27, c2x: 56, c2y: 17, x: 68, y: 18 },
-        { op: 'cubic', c1x: 90, c1y: 20, c2x: 94, c2y: 58, x: 50, y: 90 },
-        { op: 'close' },
-    ],
-    cloud: [
-        { op: 'move', x: 30, y: 80 },
-        { op: 'cubic', c1x: 13, c1y: 80, c2x: 6, c2y: 66, x: 16, y: 56 },
-        { op: 'cubic', c1x: 11, c1y: 42, c2x: 27, c2y: 34, x: 37, y: 42 },
-        { op: 'cubic', c1x: 41, c1y: 24, c2x: 66, c2y: 24, x: 70, y: 42 },
-        { op: 'cubic', c1x: 86, c1y: 38, c2x: 96, c2y: 56, x: 84, y: 68 },
-        { op: 'cubic', c1x: 92, c1y: 78, c2x: 82, c2y: 88, x: 70, y: 84 },
-        { op: 'close' },
-    ],
-};
-function getMaskShapeSegments(shape, rect, rotationDeg = 0) {
-    const unit = UNIT_SEGMENTS[shape];
-    if (!unit) {
-        throw new Error(`Unknown mask shape: ${shape}`);
-    }
-    const sx = rect.width / 100;
-    const sy = rect.height / 100;
-    const tx = (x) => rect.x + x * sx;
-    const ty = (y) => rect.y + y * sy;
-    const cx = rect.x + rect.width * 0.5;
-    const cy = rect.y + rect.height * 0.5;
-    const rotate = (x, y) => rotationDeg ? (0, rotation_math_1.rotatePoint)({ x, y }, rotationDeg, { x: cx, y: cy }) : { x, y };
-    return unit.map((s) => {
-        if (s.op === 'close') {
-            return { op: 'close' };
-        }
-        if (s.op === 'cubic') {
-            const c1 = rotate(tx(s.c1x), ty(s.c1y));
-            const c2 = rotate(tx(s.c2x), ty(s.c2y));
-            const p = rotate(tx(s.x), ty(s.y));
-            return { op: 'cubic', c1x: c1.x, c1y: c1.y, c2x: c2.x, c2y: c2.y, x: p.x, y: p.y };
-        }
-        const p = rotate(tx(s.x), ty(s.y));
-        return { op: s.op, x: p.x, y: p.y };
-    });
-}
-function rotatedRectAABB(rect, rotationDeg) {
-    if (!rotationDeg) {
-        return Object.assign({}, rect);
-    }
-    const cx = rect.x + rect.width * 0.5;
-    const cy = rect.y + rect.height * 0.5;
-    const corners = [
-        { x: rect.x, y: rect.y },
-        { x: rect.x + rect.width, y: rect.y },
-        { x: rect.x + rect.width, y: rect.y + rect.height },
-        { x: rect.x, y: rect.y + rect.height },
-    ].map(p => (0, rotation_math_1.rotatePoint)(p, rotationDeg, { x: cx, y: cy }));
-    const xs = corners.map(p => p.x);
-    const ys = corners.map(p => p.y);
-    const minX = Math.min(...xs);
-    const maxX = Math.max(...xs);
-    const minY = Math.min(...ys);
-    const maxY = Math.max(...ys);
-    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
-}

package/lib/util/mask/rotation-math.d.ts

@@ -1,2 +0,0 @@
-import type { PositionDefinition } from '../../types';
-export declare function rotatePoint(point: PositionDefinition, angleDeg: number, pivot?: PositionDefinition): PositionDefinition;

package/lib/util/mask/rotation-math.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.rotatePoint = rotatePoint;
-function rotatePoint(point, angleDeg, pivot = { x: 0, y: 0 }) {
-    const theta = (angleDeg * Math.PI) / 180;
-    const cos = Math.cos(theta);
-    const sin = Math.sin(theta);
-    const dx = point.x - pivot.x;
-    const dy = point.y - pivot.y;
-    return {
-        x: dx * cos - dy * sin + pivot.x,
-        y: dx * sin + dy * cos + pivot.y,
-    };
-}

package/lib/util/mask/shape-mask-element.d.ts

@@ -1,16 +0,0 @@
-import { CropDefinition, DocumentElement, SizeDefinition } from '../../types';
-import { MaskRect, MaskShapeKey } from './mask-shape-geometry';
-export declare function hasShapeMask(element: DocumentElement): boolean;
-export declare function getShapeMaskKey(element: DocumentElement): MaskShapeKey | null;
-export declare function getShapeMaskRotation(element: DocumentElement): number;
-export declare function normalizeMaskRotation(rotation: number): number;
-export declare function isShapeMaskable(element: DocumentElement): boolean;
-export declare function getDefaultShapeMaskCrop(size: SizeDefinition): CropDefinition;
-export declare function cropDefinitionToMaskRect(crop: CropDefinition, size: SizeDefinition): MaskRect;
-export declare function maskRectToCropDefinition(rect: MaskRect, size: SizeDefinition): CropDefinition;
-export declare const SHAPE_MASK_CLEAR_FIELDS: {
-    readonly maskDefinition: any;
-    readonly cropDefinition: any;
-    readonly imageSize: any;
-    readonly imagePosition: any;
-};

package/lib/util/mask/shape-mask-element.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHAPE_MASK_CLEAR_FIELDS = void 0;
-exports.hasShapeMask = hasShapeMask;
-exports.getShapeMaskKey = getShapeMaskKey;
-exports.getShapeMaskRotation = getShapeMaskRotation;
-exports.normalizeMaskRotation = normalizeMaskRotation;
-exports.isShapeMaskable = isShapeMaskable;
-exports.getDefaultShapeMaskCrop = getDefaultShapeMaskCrop;
-exports.cropDefinitionToMaskRect = cropDefinitionToMaskRect;
-exports.maskRectToCropDefinition = maskRectToCropDefinition;
-const DEFAULT_MASK_FRACTION = 0.72;
-function hasShapeMask(element) {
-    var _a, _b;
-    return (!!getShapeMaskKey(element) && !!((_a = element === null || element === void 0 ? void 0 : element.cropDefinition) === null || _a === void 0 ? void 0 : _a.widthPercent) && !!((_b = element === null || element === void 0 ? void 0 : element.cropDefinition) === null || _b === void 0 ? void 0 : _b.heightPercent));
-}
-function getShapeMaskKey(element) {
-    var _a, _b;
-    return (_b = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.shape) !== null && _b !== void 0 ? _b : null;
-}
-function getShapeMaskRotation(element) {
-    var _a, _b;
-    return (_b = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.rotation) !== null && _b !== void 0 ? _b : 0;
-}
-function normalizeMaskRotation(rotation) {
-    return ((rotation % 360) + 360) % 360;
-}
-function isShapeMaskable(element) {
-    return (element === null || element === void 0 ? void 0 : element.type) === 'image';
-}
-function getDefaultShapeMaskCrop(size) {
-    const side = Math.min(size.width, size.height) * DEFAULT_MASK_FRACTION;
-    return {
-        x1Percent: ((size.width - side) * 0.5) / size.width,
-        y1Percent: ((size.height - side) * 0.5) / size.height,
-        widthPercent: side / size.width,
-        heightPercent: side / size.height,
-    };
-}
-function cropDefinitionToMaskRect(crop, size) {
-    return {
-        x: crop.x1Percent * size.width,
-        y: crop.y1Percent * size.height,
-        width: crop.widthPercent * size.width,
-        height: crop.heightPercent * size.height,
-    };
-}
-function maskRectToCropDefinition(rect, size) {
-    return {
-        x1Percent: rect.x / size.width,
-        y1Percent: rect.y / size.height,
-        widthPercent: rect.width / size.width,
-        heightPercent: rect.height / size.height,
-    };
-}
-exports.SHAPE_MASK_CLEAR_FIELDS = {
-    maskDefinition: null,
-    cropDefinition: null,
-    imageSize: null,
-    imagePosition: null,
-};