@contrail/documents 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [2.2.0] - 2026-09-15
+
+### Added
+
+- `ItemComponentService.isAnnotationRowEmpty(annotationElement, annotations)` — whether an item card's annotation row will render nothing, because the row is hidden or the item has no `category === 'property'` annotations. The single predicate behind the reservation, so the layout service and the canvas renderers cannot drift apart on the question. A missing row element is not treated as hidden: renderers supply a default row for item components that have none stored, so only the annotation data decides there.
+- `ItemComponentService.getAnnotationRowHeight(annotationElement, annotations, width)` — the row's reserved height, wrapping onto further rows when the badges do not fit `width`, and `0` when the row is empty. Every creation path must size the row through here so a card laid out by the Item Chooser and one laid out by board generation agree.
+
+### Fixed
+
+- `updateSizeAndPosition` no longer reserves space above the thumbnail for an annotation row that renders nothing. `calculateAnnotationHeight` returned a flat `fontSize + ANNOTATION_PADDING_Y` minimum even when the row was hidden or the item had no annotations, pushing the thumbnail down ~8px on every such card (DESIGN-150). It now returns `0` in those cases and the thumbnail sits at the card origin. Cards whose row does show a badge are unchanged.
+
 ## [1.19.0] - 2026-09-11
 
 ### Added

package/lib/components/item-component.service.d.ts

@@ -15,6 +15,8 @@ export interface ScaledItemCardResult {
 export declare class ItemComponentService {
     static isItemComponent(element: DocumentElement): boolean;
     static isThumbnailOnlyComponent(element: DocumentElement): boolean;
+    static isAnnotationRowEmpty(annotationElement: DocumentElement, annotations?: any[]): boolean;
+    static getAnnotationRowHeight(annotationElement: DocumentElement, annotations?: any[], width?: number): number;
     static updateSizeAndPosition(propertyElements: any[], componentElement: DocumentElement, annotatedElements?: any[]): any;
     private static getYMargin;
     private static calculateAnnotationHeight;

package/lib/components/item-component.service.js

@@ -17,6 +17,30 @@ class ItemComponentService {
         const imageElement = element.elements.find((e) => e.type == 'image');
         return (!annotationElement || annotationElement.isHidden) && imageElement && !imageElement.isHidden;
     }
+    static isAnnotationRowEmpty(annotationElement, annotations = []) {
+        if (annotationElement === null || annotationElement === void 0 ? void 0 : annotationElement.isHidden) {
+            return true;
+        }
+        return !(annotations === null || annotations === void 0 ? void 0 : annotations.some((annotation) => (annotation === null || annotation === void 0 ? void 0 : annotation.category) === 'property'));
+    }
+    static getAnnotationRowHeight(annotationElement, annotations = [], width = exports.DEFAULT_THUMBNAIL_WIDTH) {
+        var _a, _b;
+        if (this.isAnnotationRowEmpty(annotationElement, annotations)) {
+            return 0;
+        }
+        const annotationSize = ((_b = (_a = annotationElement === null || annotationElement === void 0 ? void 0 : annotationElement.style) === null || _a === void 0 ? void 0 : _a.font) === null || _b === void 0 ? void 0 : _b.size) || document_element_constants_1.ANNOTATION_IMG_SIZE;
+        const propertyAnnotations = annotations.filter((annotation) => (annotation === null || annotation === void 0 ? void 0 : annotation.category) === 'property');
+        let height = annotationSize + document_element_constants_1.ANNOTATION_PADDING_Y;
+        let count = 0;
+        propertyAnnotations.forEach(() => {
+            if ((count + 1) * annotationSize * 1.25 > width) {
+                count = 0;
+                height = height + annotationSize + document_element_constants_1.ANNOTATION_PADDING_Y;
+            }
+            count++;
+        });
+        return height;
+    }
     static updateSizeAndPosition(propertyElements, componentElement, annotatedElements = []) {
         var _a, _b, _c, _d;
         const newElements = [];
@@ -64,9 +88,11 @@ class ItemComponentService {
                     lastYPosition = element.position.y;
                 }
                 const annotationHeight = this.calculateAnnotationHeight(element, componentElement, width, annotatedElements);
-                lastYPosition = lastYPosition + annotationHeight;
                 if (annotationHeight === 0 && index === 0) {
-                    lastYPosition = lastYPosition + document_element_constants_1.ANNOTATION_IMG_SIZE;
+                    lastYPosition = 0;
+                }
+                else {
+                    lastYPosition = lastYPosition + annotationHeight;
                 }
             }
             element.size.width = width;
@@ -112,28 +138,8 @@ class ItemComponentService {
         return marginY;
     }
     static calculateAnnotationHeight(element, componentElement, width, annotatedElements = []) {
-        var _a, _b;
-        const annotationSize = ((_b = (_a = element.style) === null || _a === void 0 ? void 0 : _a.font) === null || _b === void 0 ? void 0 : _b.size) || document_element_constants_1.ANNOTATION_IMG_SIZE;
-        let height = annotationSize + document_element_constants_1.ANNOTATION_PADDING_Y;
-        let xPos = 0;
         const annotatedElement = annotatedElements.find((elem) => elem.id === componentElement.id);
-        if (!annotatedElement || element.isHidden) {
-            return height;
-        }
-        const annotations = annotatedElement.annotations.filter((annotation) => annotation.category === 'property');
-        if (annotations.length > 0) {
-            let count = 0;
-            annotations === null || annotations === void 0 ? void 0 : annotations.forEach((annotation) => {
-                if ((count + 1) * annotationSize * 1.25 > width) {
-                    count = 0;
-                    xPos = -width * 0.5;
-                    height = height + annotationSize + document_element_constants_1.ANNOTATION_PADDING_Y;
-                }
-                xPos = xPos + annotationSize * 1.25;
-                count++;
-            });
-        }
-        return height;
+        return this.getAnnotationRowHeight(element, annotatedElement === null || annotatedElement === void 0 ? void 0 : annotatedElement.annotations, width);
     }
     static getImageElement(element) {
         var _a;

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

@@ -1,5 +1,8 @@
 export declare const ANNOTATION_IMG_SIZE = 15;
 export declare const ANNOTATION_PADDING_Y = 8;
+export declare const COMPONENT_PADDING_X = 8;
+export declare const COMPONENT_PADDING_T = 18;
+export declare const COMPONENT_PADDING_B = 8;
 export declare const COLOR_PADDING = 5;
 export declare const COLOR_FONT_SIZE = 8;
 export declare const COLOR_WIDTH = 140;

package/lib/document-element-constants.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COLOR_WIDTH = exports.COLOR_FONT_SIZE = exports.COLOR_PADDING = exports.ANNOTATION_PADDING_Y = exports.ANNOTATION_IMG_SIZE = void 0;
+exports.COLOR_WIDTH = exports.COLOR_FONT_SIZE = exports.COLOR_PADDING = exports.COMPONENT_PADDING_B = exports.COMPONENT_PADDING_T = exports.COMPONENT_PADDING_X = exports.ANNOTATION_PADDING_Y = exports.ANNOTATION_IMG_SIZE = void 0;
 exports.ANNOTATION_IMG_SIZE = 15;
 exports.ANNOTATION_PADDING_Y = 8;
+exports.COMPONENT_PADDING_X = 8;
+exports.COMPONENT_PADDING_T = 18;
+exports.COMPONENT_PADDING_B = 8;
 exports.COLOR_PADDING = 5;
 exports.COLOR_FONT_SIZE = 8;
 exports.COLOR_WIDTH = 140;

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

@@ -16,7 +16,7 @@ export declare class DocumentElementFactory {
         newElements: DocumentElement[];
     };
     static isMask(element: DocumentElement): boolean;
-    static getBoundingClientRect(documentElement: DocumentElement, startElement?: DocumentElement, endElement?: DocumentElement): {
+    static getBoundingClientRect(documentElement: DocumentElement, startElement?: DocumentElement, endElement?: DocumentElement, annotations?: any[]): {
         x: any;
         y: any;
         width: any;
@@ -25,5 +25,6 @@ export declare class DocumentElementFactory {
     private static getPosition;
     private static getSize;
     private static getComponentSize;
+    private static getComponentPaddingTop;
     static getLineDefinition(documentElement: DocumentElement, startElement?: DocumentElement, endElement?: DocumentElement): LineDefinition;
 }

package/lib/document-element-factory.js

@@ -8,6 +8,7 @@ const components_1 = require("./components/components");
 const document_element_property_binding_handler_1 = require("./document-element-property-binding-handler");
 const document_table_1 = require("@contrail/document-table");
 const document_element_constants_1 = require("./document-element-constants");
+const item_component_service_1 = require("./components/item-component.service");
 const callout_1 = require("./util/callout/callout");
 class DocumentElementFactory {
     static initNewElement(type) {
@@ -206,9 +207,9 @@ class DocumentElementFactory {
         var _a;
         return ['rectangle', 'circle'].indexOf(element === null || element === void 0 ? void 0 : element.type) !== -1 && ((_a = element === null || element === void 0 ? void 0 : element.elementIds) === null || _a === void 0 ? void 0 : _a.length) > 0;
     }
-    static getBoundingClientRect(documentElement, startElement, endElement) {
+    static getBoundingClientRect(documentElement, startElement, endElement, annotations) {
         const { x, y } = this.getPosition(documentElement, startElement, endElement);
-        const { width, height } = this.getSize(documentElement, startElement, endElement);
+        const { width, height } = this.getSize(documentElement, startElement, endElement, annotations);
         return {
             x,
             y,
@@ -235,7 +236,7 @@ class DocumentElementFactory {
                 (documentElement.type === 'component' && ((_b = documentElement === null || documentElement === void 0 ? void 0 : documentElement.modelBindings) === null || _b === void 0 ? void 0 : _b.item) ? 18 : 0),
         };
     }
-    static getSize(documentElement, startElement, endElement) {
+    static getSize(documentElement, startElement, endElement, annotations) {
         if (documentElement.type === 'line' || documentElement.type === 'callout') {
             const lineDefinition = this.getLineDefinition(documentElement, startElement, endElement);
             if (!lineDefinition) {
@@ -246,10 +247,12 @@ class DocumentElementFactory {
                 height: Math.abs(lineDefinition.y1 - lineDefinition.y2),
             };
         }
-        return documentElement.type === 'component' ? this.getComponentSize(documentElement) : documentElement.size;
+        return documentElement.type === 'component'
+            ? this.getComponentSize(documentElement, annotations)
+            : documentElement.size;
     }
-    static getComponentSize(documentElement) {
-        var _a, _b, _c, _d, _e, _f;
+    static getComponentSize(documentElement, annotations) {
+        var _a, _b, _c, _d, _e;
         let width = 0, height = 0, lastY = null;
         for (let i = 0; i < ((_a = documentElement === null || documentElement === void 0 ? void 0 : documentElement.elements) === null || _a === void 0 ? void 0 : _a.length); i++) {
             const element = documentElement.elements[i];
@@ -263,11 +266,26 @@ class DocumentElementFactory {
                 lastY = y + renderedHeight;
             }
         }
+        if (!((_e = documentElement === null || documentElement === void 0 ? void 0 : documentElement.modelBindings) === null || _e === void 0 ? void 0 : _e.item)) {
+            return { width, height };
+        }
         return {
-            width: width + (((_e = documentElement === null || documentElement === void 0 ? void 0 : documentElement.modelBindings) === null || _e === void 0 ? void 0 : _e.item) ? 8 + 8 : 0),
-            height: height + (((_f = documentElement === null || documentElement === void 0 ? void 0 : documentElement.modelBindings) === null || _f === void 0 ? void 0 : _f.item) ? 18 + 8 : 0),
+            width: width + document_element_constants_1.COMPONENT_PADDING_X * 2,
+            height: height + this.getComponentPaddingTop(documentElement, annotations) + document_element_constants_1.COMPONENT_PADDING_B,
         };
     }
+    static getComponentPaddingTop(documentElement, annotations) {
+        var _a, _b, _c, _d, _e;
+        if (!annotations) {
+            return document_element_constants_1.COMPONENT_PADDING_T;
+        }
+        const annotationElement = (_a = documentElement === null || documentElement === void 0 ? void 0 : documentElement.elements) === null || _a === void 0 ? void 0 : _a.find((element) => element.type === 'annotation');
+        if (!item_component_service_1.ItemComponentService.isAnnotationRowEmpty(annotationElement, annotations)) {
+            return document_element_constants_1.COMPONENT_PADDING_T;
+        }
+        const contentOffsetY = (_e = (_d = (_c = (_b = documentElement === null || documentElement === void 0 ? void 0 : documentElement.elements) === null || _b === void 0 ? void 0 : _b.find((element) => element.type === 'image')) === null || _c === void 0 ? void 0 : _c.position) === null || _d === void 0 ? void 0 : _d.y) !== null && _e !== void 0 ? _e : 0;
+        return -contentOffsetY;
+    }
     static getLineDefinition(documentElement, startElement, endElement) {
         var _a, _b;
         if (documentElement.type === 'line')

package/package.json

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