@contrail/documents 1.20.0-alpha.25ac790 → 1.20.0-alpha.d5bd4fa

package/CHANGELOG.md

@@ -10,8 +10,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### 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.
+- `@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`, and the mask-rect/percent conversions, 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, an SVG composite in a service.
 - `getMaskBakeGeometry`, `getMaskBakeLayout` and `maskShapeSegmentsToSvgPath` — the bake inputs a consumer needs to flatten a mask into a bitmap, and an SVG serializer for renderers that go through SVG rather than a canvas path. The layout scales to the source bitmap's own resolution rather than the element's on-board size, so a shrunk image does not bake at reduced detail, and re-bases a rotated mask onto its own bounding box. Only the rasterizer stays per-consumer: `Path2D` in a browser, an SVG composite in a service.
+- `hasShapeMask` is a type guard and the complete discriminator: it requires a shape key the renderer knows and all four crop percents, so an origin of `0` passes while a missing origin (previously multiplied into `NaN` by `cropDefinitionToMaskRect`) and an unknown shape (previously thrown on by `getMaskShapeSegments`) are rejected up front. The true branch narrows the percents to numbers.
 
 ## [1.18.0] - 2026-09-10
 

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

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

package/lib/util/mask/index.js

@@ -17,5 +17,4 @@ 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);
 __exportStar(require("./mask-bake-layout"), exports);

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

@@ -1,6 +1,13 @@
-import { CropDefinition, DocumentElement, SizeDefinition } from '../../types';
+import { CropDefinition, DocumentElement, MaskDefinition, SizeDefinition } from '../../types';
 import { MaskRect, MaskShapeKey } from './mask-shape-geometry';
-export declare function hasShapeMask(element: DocumentElement): boolean;
+export type MaskCropDefinition = CropDefinition & Required<Pick<CropDefinition, 'x1Percent' | 'y1Percent' | 'widthPercent' | 'heightPercent'>>;
+export type ShapeMaskedElement = DocumentElement & {
+    maskDefinition: MaskDefinition & {
+        shape: MaskShapeKey;
+    };
+    cropDefinition: MaskCropDefinition;
+};
+export declare function hasShapeMask(element: DocumentElement): element is ShapeMaskedElement;
 export declare function getShapeMaskKey(element: DocumentElement): MaskShapeKey | null;
 export declare function getShapeMaskRotation(element: DocumentElement): number;
 export declare function normalizeMaskRotation(rotation: number): number;

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

@@ -9,10 +9,19 @@ exports.isShapeMaskable = isShapeMaskable;
 exports.getDefaultShapeMaskCrop = getDefaultShapeMaskCrop;
 exports.cropDefinitionToMaskRect = cropDefinitionToMaskRect;
 exports.maskRectToCropDefinition = maskRectToCropDefinition;
+const mask_shape_geometry_1 = require("./mask-shape-geometry");
 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));
+    var _a;
+    const shape = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.shape;
+    if (!shape || !mask_shape_geometry_1.MASK_SHAPE_KEYS.includes(shape)) {
+        return false;
+    }
+    const crop = element === null || element === void 0 ? void 0 : element.cropDefinition;
+    return (Number.isFinite(crop === null || crop === void 0 ? void 0 : crop.x1Percent) &&
+        Number.isFinite(crop === null || crop === void 0 ? void 0 : crop.y1Percent) &&
+        crop.widthPercent > 0 &&
+        crop.heightPercent > 0);
 }
 function getShapeMaskKey(element) {
     var _a, _b;

package/package.json

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

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;
-}