@contrail/documents 1.17.0-alpha.7002786 → 1.17.0-alpha.f7593e7

package/CHANGELOG.md

@@ -9,8 +9,8 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-- `DocumentChange.skipUndo?: boolean` — optional marker a producer sets on a forward
-  change definition to keep the action out of undo history.
+- `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.
 
 ## [1.16.0] - 2026-08-28
 

package/lib/index.d.ts

@@ -12,4 +12,5 @@ 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

@@ -28,4 +28,5 @@ __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,6 +74,11 @@ 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-change.d.ts

@@ -17,5 +17,4 @@ export interface DocumentChange {
     documentGenerationConfig?: any;
     backingAssortmentItemData?: any;
     targetSortIndex?: number;
-    skipUndo?: boolean;
 }

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

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

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,20 @@
+"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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,19 @@
+"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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,154 @@
+"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

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

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

@@ -0,0 +1,14 @@
+"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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,61 @@
+"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,
+};

package/package.json

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