pixi-watchface-engine 0.1.8 → 0.2.0

package/API.md

@@ -9,6 +9,7 @@
 5. [Plugins](#plugins)
 6. [Events](#events)
 7. [Types](#types)
+8. [Display Geometry](#display-geometry)
 
 ---
 
@@ -734,6 +735,34 @@ interface Bounds {
 
 ---
 
+## Display Geometry
+
+Display geometry describes the face's logical shape and dimensions separately
+from the editor's pixel dimensions. The geometry helpers are device-independent;
+they accept circular and rectangular profiles without inferring a shape.
+
+```typescript
+const geometry = { shape: 'rectangle', width: 448, height: 486 } as const;
+const fitted = fitDisplayGeometry(geometry, {
+  x: 0, y: 0, width: 600, height: 600, // editor bounds, not logical face size
+});
+const editorPoint = displayToViewportPoint(
+  { x: 224, y: 243 }, geometry, fitted,
+);
+const hit = isPointInDisplay({ x: 0, y: 0 }, geometry); // true for rectangles
+```
+
+`fitDisplayGeometry` centers the logical display in editor bounds and uses one
+uniform scale. `displayToViewportPoint` and `viewportToDisplayPoint` convert
+coordinates while preserving either the default `top-left` or `center` origin.
+`isPointInDisplay` uses rectangular bounds or the circular visible boundary.
+`createDisplayMask` creates a Pixi `Graphics` mask for the same shape;
+`applyDisplayMask` attaches one to a container and returns it for cleanup.
+Circular profiles must have equal positive width and height. Invalid dimensions
+and unknown shapes throw instead of silently selecting a default.
+
+---
+
 ## Complete Example
 
 ```typescript

package/dist/elements/TextElement.d.ts

@@ -7,17 +7,34 @@ export interface TextElementStyle {
     fontWeight?: TextStyleFontWeight;
     align?: TextStyleAlign;
     color?: number;
+    lineHeight?: number | null;
+    letterSpacing?: number;
+    boxWidth?: number | null;
+    breakWords?: boolean;
+    textTransform?: TextTransform;
+    maxLines?: number | null;
+    truncationCharacter?: string;
 }
 type TextStyleAlign = 'left' | 'center' | 'right';
+type TextTransform = 'none' | 'uppercase' | 'lowercase' | 'capitalize';
 export declare class TextElement extends BaseElement {
     private pixiText;
     private charSprites;
+    private boxProxy;
+    private _boxWidth;
+    private _boxHeight;
     private _text;
     private _fontFamily;
     private _fontSize;
     private _fontWeight;
     private _align;
     private _color;
+    private _lineHeight;
+    private _letterSpacing;
+    private _breakWords;
+    private _textTransform;
+    private _maxLines;
+    private _truncationCharacter;
     private _arcPath;
     constructor(text: string, x: number, y: number, style?: TextElementStyle);
     get arcPath(): ArcPath | null;
@@ -34,13 +51,30 @@ export declare class TextElement extends BaseElement {
     set align(value: TextStyleAlign);
     get color(): number;
     set color(value: number);
+    get lineHeight(): number | null;
+    set lineHeight(value: number | null);
+    get letterSpacing(): number;
+    set letterSpacing(value: number);
+    get boxWidth(): number | null;
+    set boxWidth(value: number | null);
+    get breakWords(): boolean;
+    set breakWords(value: boolean);
+    get textTransform(): TextTransform;
+    set textTransform(value: TextTransform);
+    get maxLines(): number | null;
+    set maxLines(value: number | null);
+    get truncationCharacter(): string;
+    set truncationCharacter(value: string);
     get width(): number;
-    set width(_value: number);
+    set width(value: number);
     get height(): number;
-    set height(_value: number);
+    set height(value: number);
     protected redraw(): void;
     private drawNormalText;
     private drawArcText;
+    private displayText;
+    private transformText;
+    private makeTextStyle;
     private makeText;
     private applyStyleToAll;
     toJSON(): SerializedElement;

package/dist/elements/TextElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextElement.d.ts","sourceRoot":"","sources":["../../src/elements/TextElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElD,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAc;IAEjC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAwB;gBAE5B,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB;IAkBxE,IAAI,OAAO,IAAI,OAAO,GAAG,IAAI,CAA0B;IACvD,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAKhC;IAID,IAAI,IAAI,IAAI,MAAM,CAAuB;IACzC,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAMrB;IAED,IAAI,UAAU,IAAI,MAAM,CAA6B;IACrD,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,EAM3B;IAED,IAAI,QAAQ,IAAI,MAAM,CAA2B;IACjD,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAMzB;IAED,IAAI,UAAU,IAAI,mBAAmB,CAA6B;IAClE,IAAI,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAMxC;IAED,IAAI,KAAK,IAAI,cAAc,CAAwB;IACnD,IAAI,KAAK,CAAC,KAAK,EAAE,cAAc,EAM9B;IAED,IAAI,KAAK,IAAI,MAAM,CAAwB;IAC3C,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAMtB;IAED,IAAa,KAAK,IAAI,MAAM,CAG3B;IACD,IAAa,KAAK,CAAC,MAAM,EAAE,MAAM,EAEhC;IAED,IAAa,MAAM,IAAI,MAAM,CAG5B;IACD,IAAa,MAAM,CAAC,MAAM,EAAE,MAAM,EAEjC;cAEkB,MAAM,IAAI,IAAI;IAQjC,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,WAAW;IAsDnB,OAAO,CAAC,QAAQ;IAmBhB,OAAO,CAAC,eAAe;IAKd,MAAM,IAAI,iBAAiB;IAa3B,SAAS,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAiBjD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW;CAgBtD"}
+{"version":3,"file":"TextElement.d.ts","sourceRoot":"","sources":["../../src/elements/TextElement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,KAAK,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAClD,KAAK,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,CAAC;AAEvE,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAAuB;IAEzC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAwB;gBAE5B,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB;IA4BxE,IAAI,OAAO,IAAI,OAAO,GAAG,IAAI,CAA0B;IACvD,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAKhC;IAID,IAAI,IAAI,IAAI,MAAM,CAAuB;IACzC,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAMrB;IAED,IAAI,UAAU,IAAI,MAAM,CAA6B;IACrD,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,EAM3B;IAED,IAAI,QAAQ,IAAI,MAAM,CAA2B;IACjD,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,EAMzB;IAED,IAAI,UAAU,IAAI,mBAAmB,CAA6B;IAClE,IAAI,UAAU,CAAC,KAAK,EAAE,mBAAmB,EAMxC;IAED,IAAI,KAAK,IAAI,cAAc,CAAwB;IACnD,IAAI,KAAK,CAAC,KAAK,EAAE,cAAc,EAO9B;IAED,IAAI,KAAK,IAAI,MAAM,CAAwB;IAC3C,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAMtB;IAED,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAA6B;IAC5D,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAOlC;IAED,IAAI,aAAa,IAAI,MAAM,CAAgC;IAC3D,IAAI,aAAa,CAAC,KAAK,EAAE,MAAM,EAM9B;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAA2B;IACxD,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAShC;IAED,IAAI,UAAU,IAAI,OAAO,CAA6B;IACtD,IAAI,UAAU,CAAC,KAAK,EAAE,OAAO,EAM5B;IAED,IAAI,aAAa,IAAI,aAAa,CAAgC;IAClE,IAAI,aAAa,CAAC,KAAK,EAAE,aAAa,EAMrC;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAA2B;IACxD,IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAMhC;IAED,IAAI,mBAAmB,IAAI,MAAM,CAAsC;IACvE,IAAI,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAMpC;IAED,IAAa,KAAK,IAAI,MAAM,CAG3B;IACD,IAAa,KAAK,CAAC,KAAK,EAAE,MAAM,EAO/B;IAED,IAAa,MAAM,IAAI,MAAM,CAG5B;IACD,IAAa,MAAM,CAAC,KAAK,EAAE,MAAM,EAOhC;cAEkB,MAAM,IAAI,IAAI;IAQjC,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,WAAW;IAuDnB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,eAAe;IAKd,MAAM,IAAI,iBAAiB;IAoB3B,SAAS,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IA0BjD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW;CAyBtD"}

package/dist/geometry/DisplayGeometry.d.ts

@@ -0,0 +1,46 @@
+import { Container, Graphics } from 'pixi.js';
+import type { Bounds, CoordinateOrigin } from '../types.ts';
+/** Display shape supported by watch-face geometry. */
+export type DisplayShape = 'circle' | 'rectangle';
+/** Logical display dimensions, independent of an editor's pixel dimensions. */
+export interface DisplayGeometry {
+    shape: DisplayShape;
+    width: number;
+    height: number;
+}
+export interface DisplayPoint {
+    x: number;
+    y: number;
+}
+/** A display's fitted rectangle in the editor, plus its uniform scale. */
+export interface DisplayViewport extends Bounds {
+    scale: number;
+}
+/**
+ * Check and narrow geometry received from saved data or device integrations.
+ * Circular displays use a square logical coordinate space.
+ */
+export declare function validateDisplayGeometry(value: unknown): asserts value is DisplayGeometry;
+/** Return logical display bounds for the requested coordinate origin. */
+export declare function getDisplayBounds(geometry: DisplayGeometry, coordinateOrigin?: CoordinateOrigin): Bounds;
+/**
+ * Fit a logical display inside an editor-space rectangle without distortion.
+ * The returned bounds are centered in the editor rectangle; the editor
+ * rectangle is never interpreted as the face's logical dimensions.
+ */
+export declare function fitDisplayGeometry(geometry: DisplayGeometry, editorBounds: Bounds): DisplayViewport;
+/** Convert a logical face coordinate to the fitted editor viewport. */
+export declare function displayToViewportPoint(point: DisplayPoint, geometry: DisplayGeometry, viewport: DisplayViewport, coordinateOrigin?: CoordinateOrigin): DisplayPoint;
+/** Convert a fitted editor-space point to logical face coordinates. */
+export declare function viewportToDisplayPoint(point: DisplayPoint, geometry: DisplayGeometry, viewport: DisplayViewport, coordinateOrigin?: CoordinateOrigin): DisplayPoint;
+/** Test whether a logical coordinate falls inside the visible display shape. */
+export declare function isPointInDisplay(point: DisplayPoint, geometry: DisplayGeometry, coordinateOrigin?: CoordinateOrigin): boolean;
+/**
+ * Create a Pixi mask matching the visible display shape. Add the returned
+ * Graphics to the masked container (or a sibling in the same coordinate
+ * space) and assign it as that container's mask.
+ */
+export declare function createDisplayMask(geometry: DisplayGeometry, coordinateOrigin?: CoordinateOrigin): Graphics;
+/** Attach a shape-aware Pixi mask and return it for later removal/destruction. */
+export declare function applyDisplayMask(target: Container, geometry: DisplayGeometry, coordinateOrigin?: CoordinateOrigin): Graphics;
+//# sourceMappingURL=DisplayGeometry.d.ts.map

package/dist/geometry/DisplayGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DisplayGeometry.d.ts","sourceRoot":"","sources":["../../src/geometry/DisplayGeometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE5D,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAgB,SAAQ,MAAM;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAkBxF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,eAAe,EACzB,YAAY,EAAE,MAAM,GACnB,eAAe,CAcjB;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,YAAY,CASd;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,YAAY,CASd;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,OAAO,CAcT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,QAAQ,CAUV;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe,EACzB,gBAAgB,GAAE,gBAA6B,GAC9C,QAAQ,CAKV"}

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export { ZOrderManager } from "./managers/ZOrderManager.ts";
 export { SelectionManager } from "./selection/SelectionManager.ts";
 export { SerializationManager } from "./managers/SerializationManager.ts";
 export type { FillDirection, ShapeType, LineCap, ArcPath, ElementType, CoordinateOrigin, SerializedElement, WatchfaceState, UndoableAction, HandleConfig, Bounds, } from "./types.ts";
+export { applyDisplayMask, createDisplayMask, displayToViewportPoint, fitDisplayGeometry, getDisplayBounds, isPointInDisplay, validateDisplayGeometry, viewportToDisplayPoint, } from "./geometry/DisplayGeometry.ts";
+export type { DisplayGeometry, DisplayPoint, DisplayShape, DisplayViewport, } from "./geometry/DisplayGeometry.ts";
 export { EventBus } from "./EventBus.ts";
 export type { EngineEventMap } from "./EventBus.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE,YAAY,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAGvF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAG1E,YAAY,EACV,aAAa,EACb,SAAS,EACT,OAAO,EACP,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE,YAAY,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,YAAY,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAGvF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAG1E,YAAY,EACV,aAAa,EACb,SAAS,EACT,OAAO,EACP,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,YAAY,EACZ,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -30734,6 +30734,7 @@ init_textureFrom();
 init_Container();
 init_Graphics();
 init_Sprite();
+init_CanvasTextMetrics();
 init_TextStyle();
 init_Ticker();
 init_eventemitter3();
@@ -31101,12 +31102,21 @@ class BaseElement {
 class TextElement extends BaseElement {
   pixiText;
   charSprites = [];
+  boxProxy;
+  _boxWidth = null;
+  _boxHeight = null;
   _text;
   _fontFamily;
   _fontSize;
   _fontWeight;
   _align;
   _color;
+  _lineHeight;
+  _letterSpacing;
+  _breakWords;
+  _textTransform;
+  _maxLines;
+  _truncationCharacter;
   _arcPath = null;
   constructor(text, x2, y2, style) {
     super("text");
@@ -31116,10 +31126,20 @@ class TextElement extends BaseElement {
     this._fontWeight = style?.fontWeight ?? "normal";
     this._align = style?.align ?? "left";
     this._color = style?.color ?? 16777215;
-    this.pixiText = this.makeText(this._text);
+    this._lineHeight = style?.lineHeight ?? null;
+    this._letterSpacing = style?.letterSpacing ?? 0;
+    this._boxWidth = style?.boxWidth ?? null;
+    this._breakWords = style?.breakWords ?? false;
+    this._textTransform = style?.textTransform ?? "none";
+    this._maxLines = style?.maxLines ?? null;
+    this._truncationCharacter = style?.truncationCharacter ?? "…";
+    this.pixiText = this.makeText(this.displayText(this._text));
     this.container.addChild(this.pixiText);
+    this.boxProxy = new Graphics;
+    this.container.addChild(this.boxProxy);
     this.x = x2;
     this.y = y2;
+    this.redraw();
   }
   get arcPath() {
     return this._arcPath;
@@ -31190,6 +31210,7 @@ class TextElement extends BaseElement {
     this._align = value;
     if (this.pixiText)
       this.pixiText.style.align = value;
+    this.redraw();
     this.emitChange("align", old, value);
   }
   get color() {
@@ -31205,18 +31226,124 @@ class TextElement extends BaseElement {
     });
     this.emitChange("color", old, value);
   }
+  get lineHeight() {
+    return this._lineHeight;
+  }
+  set lineHeight(value) {
+    const old = this._lineHeight;
+    if (old === value)
+      return;
+    this._lineHeight = value;
+    this.applyStyleToAll((s2) => {
+      if (value != null)
+        s2.lineHeight = value;
+    });
+    this.redraw();
+    this.emitChange("lineHeight", old, value);
+  }
+  get letterSpacing() {
+    return this._letterSpacing;
+  }
+  set letterSpacing(value) {
+    const old = this._letterSpacing;
+    if (old === value)
+      return;
+    this._letterSpacing = value;
+    this.applyStyleToAll((s2) => {
+      s2.letterSpacing = value;
+    });
+    this.emitChange("letterSpacing", old, value);
+  }
+  get boxWidth() {
+    return this._boxWidth;
+  }
+  set boxWidth(value) {
+    const old = this._boxWidth;
+    if (old === value)
+      return;
+    this._boxWidth = value;
+    this.applyStyleToAll((s2) => {
+      s2.wordWrap = value != null;
+      s2.wordWrapWidth = value ?? 100;
+    });
+    this.emitChange("boxWidth", old, value);
+  }
+  get breakWords() {
+    return this._breakWords;
+  }
+  set breakWords(value) {
+    const old = this._breakWords;
+    if (old === value)
+      return;
+    this._breakWords = value;
+    this.applyStyleToAll((s2) => {
+      s2.breakWords = value;
+    });
+    this.emitChange("breakWords", old, value);
+  }
+  get textTransform() {
+    return this._textTransform;
+  }
+  set textTransform(value) {
+    const old = this._textTransform;
+    if (old === value)
+      return;
+    this._textTransform = value;
+    this.redraw();
+    this.emitChange("textTransform", old, value);
+  }
+  get maxLines() {
+    return this._maxLines;
+  }
+  set maxLines(value) {
+    const old = this._maxLines;
+    if (old === value)
+      return;
+    this._maxLines = value;
+    this.redraw();
+    this.emitChange("maxLines", old, value);
+  }
+  get truncationCharacter() {
+    return this._truncationCharacter;
+  }
+  set truncationCharacter(value) {
+    const old = this._truncationCharacter;
+    if (old === value)
+      return;
+    this._truncationCharacter = value;
+    this.redraw();
+    this.emitChange("truncationCharacter", old, value);
+  }
   get width() {
     if (this._arcPath)
       return this._arcPath.radius * 2;
-    return this.pixiText?.width ?? 0;
+    return this._boxWidth ?? this.pixiText?.width ?? 0;
+  }
+  set width(value) {
+    if (this._arcPath)
+      return;
+    const old = this.width;
+    if (old === value)
+      return;
+    this._boxWidth = value;
+    this.redraw();
+    this.emitChange("width", old, value);
   }
-  set width(_value) {}
   get height() {
     if (this._arcPath)
       return this._arcPath.radius * 2;
-    return this.pixiText?.height ?? 0;
+    return this._boxHeight ?? this.pixiText?.height ?? 0;
+  }
+  set height(value) {
+    if (this._arcPath)
+      return;
+    const old = this.height;
+    if (old === value)
+      return;
+    this._boxHeight = value;
+    this.redraw();
+    this.emitChange("height", old, value);
   }
-  set height(_value) {}
   redraw() {
     if (this._arcPath) {
       this.drawArcText();
@@ -31231,15 +31358,25 @@ class TextElement extends BaseElement {
     }
     this.charSprites = [];
     if (!this.pixiText) {
-      this.pixiText = this.makeText(this._text);
+      this.pixiText = this.makeText(this.displayText(this._text));
       this.container.addChild(this.pixiText);
     } else {
-      this.pixiText.text = this._text;
+      this.pixiText.text = this.displayText(this._text);
       this.pixiText.visible = true;
     }
+    const text = this.pixiText;
+    const bw = this._boxWidth ?? text.width;
+    const bh = this._boxHeight ?? text.height;
+    this.boxProxy.clear();
+    this.boxProxy.rect(0, 0, bw, bh);
+    this.boxProxy.fill({ color: 16777215, alpha: 0 });
+    text.position.y = bh / 2;
+    const tw = text.width;
+    text.position.x = this._align === "left" ? tw / 2 : this._align === "right" ? bw - tw / 2 : bw / 2;
   }
   drawArcText() {
     const arc = this._arcPath;
+    this.boxProxy.clear();
     if (this.pixiText) {
       this.pixiText.visible = false;
     }
@@ -31271,17 +31408,61 @@ class TextElement extends BaseElement {
       angle += halfAngular * Math.sign(span);
     }
   }
+  displayText(value) {
+    const transformed = this.transformText(value);
+    if (!this._maxLines || this._maxLines <= 0)
+      return transformed;
+    const style = this.makeTextStyle();
+    const lines = CanvasTextMetrics.measureText(transformed, style).lines;
+    const maxLines = Math.floor(this._maxLines);
+    if (lines.length <= maxLines)
+      return transformed;
+    const visibleLines = lines.slice(0, maxLines);
+    let lastLine = visibleLines[visibleLines.length - 1]?.replace(/\s+$/, "") ?? "";
+    if (this._boxWidth != null) {
+      while (lastLine && CanvasTextMetrics.measureText(`${lastLine}${this._truncationCharacter}`, style, undefined, false).width > this._boxWidth) {
+        lastLine = lastLine.slice(0, -1);
+      }
+    }
+    visibleLines[visibleLines.length - 1] = `${lastLine}${this._truncationCharacter}`;
+    return visibleLines.join(`
+`);
+  }
+  transformText(value) {
+    if (this._textTransform === "uppercase")
+      return value.toUpperCase();
+    if (this._textTransform === "lowercase")
+      return value.toLowerCase();
+    if (this._textTransform === "capitalize") {
+      return value.replace(/\p{L}[\p{L}\p{M}'’-]*/gu, (word) => {
+        const first = word[0];
+        return first ? first.toUpperCase() + word.slice(1).toLowerCase() : word;
+      });
+    }
+    return value;
+  }
+  makeTextStyle() {
+    const style = new TextStyle({
+      fontFamily: this._fontFamily,
+      fontSize: this._fontSize,
+      fontWeight: this._fontWeight,
+      fill: this._color,
+      align: this._align,
+      letterSpacing: this._letterSpacing,
+      wordWrap: this._boxWidth != null,
+      wordWrapWidth: this._boxWidth ?? 100,
+      breakWords: this._breakWords
+    });
+    if (this._lineHeight != null)
+      style.lineHeight = this._lineHeight;
+    return style;
+  }
   makeText(content) {
+    const style = this.makeTextStyle();
     return new Text({
       text: content,
       anchor: 0.5,
-      style: new TextStyle({
-        fontFamily: this._fontFamily,
-        fontSize: this._fontSize,
-        fontWeight: this._fontWeight,
-        fill: this._color,
-        align: this._align
-      })
+      style
     });
   }
   applyStyleToAll(mutate) {
@@ -31299,6 +31480,13 @@ class TextElement extends BaseElement {
       fontWeight: this._fontWeight,
       align: this._align,
       color: this._color,
+      lineHeight: this._lineHeight,
+      letterSpacing: this._letterSpacing,
+      boxWidth: this._boxWidth,
+      breakWords: this._breakWords,
+      textTransform: this._textTransform,
+      maxLines: this._maxLines,
+      truncationCharacter: this._truncationCharacter,
       arcPath: this._arcPath ?? undefined
     };
   }
@@ -31315,8 +31503,26 @@ class TextElement extends BaseElement {
       this.align = data.align;
     if (data.color !== undefined)
       this.color = data.color;
+    if (data.lineHeight !== undefined)
+      this.lineHeight = data.lineHeight;
+    if (data.letterSpacing !== undefined)
+      this.letterSpacing = data.letterSpacing;
+    if (data.boxWidth !== undefined)
+      this.boxWidth = data.boxWidth;
+    if (data.breakWords !== undefined)
+      this.breakWords = data.breakWords;
+    if (data.textTransform !== undefined)
+      this.textTransform = data.textTransform;
+    if (data.maxLines !== undefined)
+      this.maxLines = data.maxLines;
+    if (data.truncationCharacter !== undefined)
+      this.truncationCharacter = data.truncationCharacter;
     if ("arcPath" in data)
       this.arcPath = data.arcPath ?? null;
+    if (data.width !== undefined)
+      this.width = data.width;
+    if (data.height !== undefined)
+      this.height = data.height;
     this.x = data.x;
     this.y = data.y;
     this.rotation = data.rotation;
@@ -31331,10 +31537,21 @@ class TextElement extends BaseElement {
       fontSize: data.fontSize,
       fontWeight: data.fontWeight,
       align: data.align,
-      color: data.color
+      color: data.color,
+      lineHeight: data.lineHeight,
+      letterSpacing: data.letterSpacing,
+      boxWidth: data.boxWidth,
+      breakWords: data.breakWords,
+      textTransform: data.textTransform,
+      maxLines: data.maxLines,
+      truncationCharacter: data.truncationCharacter
     });
     if (data.arcPath)
       el.arcPath = data.arcPath;
+    if (data.width !== undefined)
+      el.width = data.width;
+    if (data.height !== undefined)
+      el.height = data.height;
     el.rotation = data.rotation;
     el.zIndex = data.zIndex;
     el.visible = data.visible;
@@ -34579,7 +34796,131 @@ class AlignmentGuidesPlugin {
     this.graphics.destroy();
   }
 }
+// src/geometry/DisplayGeometry.ts
+function validateDisplayGeometry(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError("Display geometry must be an object.");
+  }
+  const geometry = value;
+  if (geometry.shape !== "circle" && geometry.shape !== "rectangle") {
+    throw new TypeError(`Unsupported display shape: ${String(geometry.shape)}.`);
+  }
+  if (typeof geometry.width !== "number" || !Number.isFinite(geometry.width) || geometry.width <= 0) {
+    throw new RangeError("Display geometry width must be a positive finite number.");
+  }
+  if (typeof geometry.height !== "number" || !Number.isFinite(geometry.height) || geometry.height <= 0) {
+    throw new RangeError("Display geometry height must be a positive finite number.");
+  }
+  if (geometry.shape === "circle" && geometry.width !== geometry.height) {
+    throw new RangeError("Circular display geometry must have equal width and height.");
+  }
+}
+function getDisplayBounds(geometry, coordinateOrigin = "top-left") {
+  validateDisplayGeometry(geometry);
+  validateCoordinateOrigin(coordinateOrigin);
+  return {
+    x: coordinateOrigin === "center" ? -geometry.width / 2 : 0,
+    y: coordinateOrigin === "center" ? -geometry.height / 2 : 0,
+    width: geometry.width,
+    height: geometry.height
+  };
+}
+function fitDisplayGeometry(geometry, editorBounds) {
+  validateDisplayGeometry(geometry);
+  validateBounds(editorBounds, "Editor bounds");
+  const scale = Math.min(editorBounds.width / geometry.width, editorBounds.height / geometry.height);
+  const width = geometry.width * scale;
+  const height = geometry.height * scale;
+  return {
+    x: editorBounds.x + (editorBounds.width - width) / 2,
+    y: editorBounds.y + (editorBounds.height - height) / 2,
+    width,
+    height,
+    scale
+  };
+}
+function displayToViewportPoint(point, geometry, viewport, coordinateOrigin = "top-left") {
+  validateDisplayGeometry(geometry);
+  validateViewport(viewport);
+  validatePoint(point, "Display point");
+  const bounds = getDisplayBounds(geometry, coordinateOrigin);
+  return {
+    x: viewport.x + (point.x - bounds.x) * viewport.scale,
+    y: viewport.y + (point.y - bounds.y) * viewport.scale
+  };
+}
+function viewportToDisplayPoint(point, geometry, viewport, coordinateOrigin = "top-left") {
+  validateDisplayGeometry(geometry);
+  validateViewport(viewport);
+  validatePoint(point, "Viewport point");
+  const bounds = getDisplayBounds(geometry, coordinateOrigin);
+  return {
+    x: bounds.x + (point.x - viewport.x) / viewport.scale,
+    y: bounds.y + (point.y - viewport.y) / viewport.scale
+  };
+}
+function isPointInDisplay(point, geometry, coordinateOrigin = "top-left") {
+  validateDisplayGeometry(geometry);
+  validatePoint(point, "Display point");
+  const bounds = getDisplayBounds(geometry, coordinateOrigin);
+  if (geometry.shape === "rectangle") {
+    return point.x >= bounds.x && point.x <= bounds.x + bounds.width && point.y >= bounds.y && point.y <= bounds.y + bounds.height;
+  }
+  const centerX = bounds.x + bounds.width / 2;
+  const centerY = bounds.y + bounds.height / 2;
+  const radius = geometry.width / 2;
+  return (point.x - centerX) ** 2 + (point.y - centerY) ** 2 <= radius ** 2;
+}
+function createDisplayMask(geometry, coordinateOrigin = "top-left") {
+  const bounds = getDisplayBounds(geometry, coordinateOrigin);
+  const mask = new Graphics;
+  if (geometry.shape === "circle") {
+    mask.circle(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2, bounds.width / 2);
+  } else {
+    mask.rect(bounds.x, bounds.y, bounds.width, bounds.height);
+  }
+  mask.fill({ color: 16777215 });
+  return mask;
+}
+function applyDisplayMask(target, geometry, coordinateOrigin = "top-left") {
+  const mask = createDisplayMask(geometry, coordinateOrigin);
+  target.addChild(mask);
+  target.mask = mask;
+  return mask;
+}
+function validateCoordinateOrigin(value) {
+  if (value !== "top-left" && value !== "center") {
+    throw new TypeError(`Unsupported coordinate origin: ${String(value)}.`);
+  }
+}
+function validatePoint(point, label) {
+  if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+    throw new RangeError(`${label} coordinates must be finite numbers.`);
+  }
+}
+function validateBounds(bounds, label) {
+  if (!Number.isFinite(bounds.x) || !Number.isFinite(bounds.y)) {
+    throw new RangeError(`${label} position must use finite numbers.`);
+  }
+  if (!Number.isFinite(bounds.width) || bounds.width <= 0 || !Number.isFinite(bounds.height) || bounds.height <= 0) {
+    throw new RangeError(`${label} width and height must be positive finite numbers.`);
+  }
+}
+function validateViewport(viewport) {
+  validateBounds(viewport, "Viewport bounds");
+  if (!Number.isFinite(viewport.scale) || viewport.scale <= 0) {
+    throw new RangeError("Viewport scale must be a positive finite number.");
+  }
+}
 export {
+  viewportToDisplayPoint,
+  validateDisplayGeometry,
+  isPointInDisplay,
+  getDisplayBounds,
+  fitDisplayGeometry,
+  displayToViewportPoint,
+  createDisplayMask,
+  applyDisplayMask,
   ZOrderManager,
   WatchfaceEngine,
   ViewportPlugin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixi-watchface-engine",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "A PixiJS v8 watchface editor engine with visual editor, plugin system, and intuitive API",
   "author": "Eric Schmar (ericschmar@gmail.com)",
   "type": "module",
@@ -20,6 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "test": "bun test",
     "typecheck": "tsc --noEmit",
     "build": "bun build src/index.ts --outdir dist --target browser && tsc --emitDeclarationOnly --declaration",
     "prepublishOnly": "bun run typecheck && bun run build"