@cesdk/engine 1.15.0-rc.1 → 1.16.0-rc.0

package/assets/default/ly.img.colors.defaultPalette/content.json

@@ -0,0 +1,110 @@
+{
+  "version": "1.0.0",
+  "id": "ly.img.colors.defaultPalette",
+  "assets": [
+    {
+      "id": "ly.img.colors.defaultPalette-white",
+      "label": { "en": "#FFFFFF" },
+      "tags": { "en": ["white"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 1,
+          "g": 1,
+          "b": 1
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-black",
+      "label": { "en": "#000000" },
+      "tags": { "en": ["black"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0,
+          "g": 0,
+          "b": 0
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-cornflower-blue",
+      "label": { "en": "#6686FF" },
+      "tags": { "en": ["cornflower blue"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0.4,
+          "g": 0.5254901961,
+          "b": 1
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-light-blue",
+      "label": { "en": "#66CCFF" },
+      "tags": { "en": ["light blue"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0.4,
+          "g": 0.8,
+          "b": 1
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-turquoise",
+      "label": { "en": "#54FFEA" },
+      "tags": { "en": ["turquoise"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0.3294117647,
+          "g": 1,
+          "b": 0.9176470588
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-indian-red",
+      "label": { "en": "#E75050" },
+      "tags": { "en": ["indian red"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0.9058823529,
+          "g": 0.3137254902,
+          "b": 0.3137254902
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-coral",
+      "label": { "en": "#F28855" },
+      "tags": { "en": ["coral"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 0.9490196078,
+          "g": 0.5333333333,
+          "b": 0.3333333333
+        }
+      }
+    },
+    {
+      "id": "ly.img.colors.defaultPalette-khaki",
+      "label": { "en": "#FFF763" },
+      "tags": { "en": ["khaki"] },
+      "payload": {
+        "color": {
+          "colorSpace": "sRGB",
+          "r": 1,
+          "g": 0.968627451,
+          "b": 0.3882352941
+        }
+      }
+    }
+  ]
+}

package/index.d.ts

@@ -14,23 +14,9 @@ export declare interface Asset {
     /**  Groups of the asset.  */
     groups?: AssetGroups;
     /** Asset-specific and custom meta information */
-    meta?: {
-        /** The mime type of this asset or the data behind the asset's uri. */
-        mimeType?: string;
-        /** The type id of the design block that should be created from this asset. */
-        blockType?: string;
-        fillType?: string;
-        shapeType?: string;
-        kind?: string;
-        uri?: string;
-        thumbUri?: string;
-        previewUri?: string;
-        filename?: string;
-        vectorPath?: string;
-        width?: number;
-        height?: number;
-        duration?: string;
-    } & Record<string, unknown>;
+    meta?: AssetMetaData;
+    /** Structured asset-specific data */
+    payload?: AssetPayload;
 }
 
 /**
@@ -156,6 +142,24 @@ export declare class AssetAPI {
 
 }
 
+/**
+ * Asset Color payload CMYK representation
+ * @public
+ */
+export declare interface AssetCMYKColor {
+    colorSpace: 'CMYK';
+    c: number;
+    m: number;
+    y: number;
+    k: number;
+}
+
+/**
+ * Asset Color payload
+ * @public
+ */
+export declare type AssetColor = AssetRGBColor | AssetCMYKColor | AssetSpotColor;
+
 /**
  * Definition of an asset used if an asset is added to an asset source.
  * @public
@@ -186,6 +190,36 @@ export declare interface AssetDefinition extends Asset {
  */
 export declare type AssetGroups = string[];
 
+/**
+ * AssetColor Meta information
+ * @public
+ */
+export declare type AssetMetaData = {
+    /** The mime type of this asset or the data behind the asset's uri. */
+    mimeType?: string;
+    /** The type id of the design block that should be created from this asset. */
+    blockType?: string;
+    fillType?: string;
+    shapeType?: string;
+    kind?: string;
+    uri?: string;
+    thumbUri?: string;
+    previewUri?: string;
+    filename?: string;
+    vectorPath?: string;
+    width?: number;
+    height?: number;
+    duration?: string;
+} & Record<string, unknown>;
+
+/**
+ * Asset payload
+ * @public
+ */
+export declare interface AssetPayload {
+    color?: AssetColor;
+}
+
 /**
  * Defines a request for querying assets
  * @public
@@ -269,6 +303,17 @@ declare interface AssetResultUtm {
     medium: string;
 }
 
+/**
+ * Asset Color payload RGB representation
+ * @public
+ */
+export declare interface AssetRGBColor {
+    colorSpace: 'sRGB';
+    r: number;
+    g: number;
+    b: number;
+}
+
 /**
  * A source of assets
  * @public
@@ -328,6 +373,17 @@ export declare interface AssetSource {
 
 declare type _AssetSource = AssetSource;
 
+/**
+ * Asset Color payload SpotColor representation
+ * @public
+ */
+export declare interface AssetSpotColor {
+    colorSpace: 'SpotColor';
+    name: string;
+    externalReference: string;
+    representation: AssetRGBColor | AssetCMYKColor;
+}
+
 /**
  * Return type of a `findAssets` query.
  * @public
@@ -527,10 +583,10 @@ export declare class BlockAPI {
     findByType(type: DesignBlockType): DesignBlockId[];
     /**
      * Finds all blocks with the given kind.
-     * @param type - The kind to search for.
+     * @param kind - The kind to search for.
      * @returns A list of block ids.
      */
-    findByKind(kind: DesignBlockType): DesignBlockId[];
+    findByKind(kind: string): DesignBlockId[];
     /**
      * Return all blocks currently known to the engine.
      * @returns A list of block ids.
@@ -1054,6 +1110,20 @@ export declare class BlockAPI {
      * @returns The value of the property.
      */
     getString(id: DesignBlockId, property: string): string;
+    /**
+     * Set a color property of the given design block to the given value.
+     * @param id - The block whose property should be set.
+     * @param property - The name of the property to set.
+     * @param value - The value to set.
+     */
+    setColor(id: DesignBlockId, property: string, value: Color): void;
+    /**
+     * Get the value of a color property of the given design block.
+     * @param id - The block whose property should be queried.
+     * @param property - The name of the property to query.
+     * @returns The value of the property.
+     */
+    getColor(id: DesignBlockId, property: string): Color;
     /**
      * Set a color property of the given design block to the given value.
      * @param id - The block whose property should be set.
@@ -1062,6 +1132,7 @@ export declare class BlockAPI {
      * @param g - The green color component in the range of 0 to 1.
      * @param b - The blue color component in the range of 0 to 1.
      * @param a - The alpha color component in the range of 0 to 1.
+     * @deprecated Use setColor() instead.
      */
     setColorRGBA(id: DesignBlockId, property: string, r: number, g: number, b: number, a?: number): void;
     /**
@@ -1069,6 +1140,7 @@ export declare class BlockAPI {
      * @param id - The block whose property should be queried.
      * @param property - The name of the property to query.
      * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
+     * @deprecated Use getColor() instead.
      */
     getColorRGBA(id: DesignBlockId, property: string): RGBA;
     /**
@@ -1077,6 +1149,7 @@ export declare class BlockAPI {
      * @param property - The name of the property to set.
      * @param name - The name of the spot color.
      * @param tint - The tint factor in the range of 0 to 1.
+     * @deprecated Use setColor() instead.
      */
     setColorSpot(id: DesignBlockId, property: string, name: string, tint?: number): void;
     /**
@@ -1084,6 +1157,7 @@ export declare class BlockAPI {
      * @param id - The block whose property should be queried.
      * @param property - The name of the property to query.
      * @returns The name of the spot color.
+     * @deprecated Use getColor() instead.
      */
     getColorSpotName(id: DesignBlockId, property: string): string;
     /**
@@ -1091,6 +1165,7 @@ export declare class BlockAPI {
      * @param id - The block whose property should be queried.
      * @param property - The name of the property to query.
      * @returns The tint factor of the spot color.
+     * @deprecated Use getColor() instead.
      */
     getColorSpotTint(id: DesignBlockId, property: string): number;
     /**
@@ -1659,7 +1734,7 @@ export declare class BlockAPI {
      *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
      *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
      */
-    setTextColor(id: DesignBlockId, color: RGBAColor | SpotColor, from?: number, to?: number): void;
+    setTextColor(id: DesignBlockId, color: Color, from?: number, to?: number): void;
     /**
      * Returns the ordered unique list of colors of the text in the selected range.
      * @param block - The text block whose colors should be returned.
@@ -1670,7 +1745,7 @@ export declare class BlockAPI {
      *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
      *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
      */
-    getTextColors(id: DesignBlockId, from?: number, to?: number): Array<RGBAColor | SpotColor>;
+    getTextColors(id: DesignBlockId, from?: number, to?: number): Array<Color>;
     /**
      * Returns the ordered unique list of font weights of the text in the selected range.
      * @param block - The text block whose font weights should be returned.
@@ -2294,17 +2369,39 @@ declare interface ChannelSync<Out, In = Out> extends Channel<Out, In> {
     value: () => Out;
 }
 
+/**
+ * @public
+ */
+export declare type CMYK = [c: number, m: number, y: number, k: number];
+
 /**
  * All components between 0 and 1
  * @public
  */
 export declare interface CMYKColor {
+    /** Cyan */
     c: number;
+    /** Magenta */
     m: number;
+    /** Yellow */
     y: number;
+    /** Black */
     k: number;
+    /** The tint factor */
+    tint: number;
 }
 
+/**
+ * A type alias for all color types supported by the engine.
+ * @public
+ */
+export declare type Color = RGBAColor | CMYKColor | SpotColor;
+
+/**
+ * @public
+ */
+export declare type ColorSpace = 'sRGB' | 'CMYK' | 'SpotColor';
+
 /**
  * Asset results that are returned from the engine.
  *
@@ -2728,7 +2825,7 @@ export declare type CutoutType = 'Solid' | 'Dashed';
 /**
  * @public
  */
-export declare type DefaultAssetSourceId = 'ly.img.sticker' | 'ly.img.vectorpath' | 'ly.img.filter.lut' | 'ly.img.filter.duotone';
+export declare type DefaultAssetSourceId = 'ly.img.sticker' | 'ly.img.vectorpath' | 'ly.img.filter.lut' | 'ly.img.filter.duotone' | 'ly.img.colors.defaultPalette';
 
 /**
  * @public
@@ -3032,6 +3129,13 @@ export declare class EditorAPI {
      * @returns A result holding a float array of the four color components.
      */
     getSpotColorRGBA(name: string): RGBA;
+    /**
+     * Queries the CMYK representation set for a spot color.
+     * If the value of the queried spot color has not been set yet, returns the default CMYK representation (of magenta).
+     * @param name - The name of a spot color.
+     * @returns A result holding a float array of the four color components.
+     */
+    getSpotColorCMYK(name: string): CMYK;
     /**
      * Sets the RGB representation of a spot color.
      * Use this function to both create a new spot color or update an existing spot color.
@@ -3041,6 +3145,16 @@ export declare class EditorAPI {
      * @param b - The blue color component in the range of 0 to 1.
      */
     setSpotColorRGB(name: string, r: number, g: number, b: number): void;
+    /**
+     * Sets the CMYK representation of a spot color.
+     * Use this function to both create a new spot color or update an existing spot color.
+     * @param name - The name of a spot color.
+     * @param c - The cyan color component in the range of 0 to 1.
+     * @param m - The magenta color component in the range of 0 to 1.
+     * @param y - The yellow color component in the range of 0 to 1.
+     * @param k - The key color component in the range of 0 to 1.
+     */
+    setSpotColorCMYK(name: string, c: number, m: number, y: number, k: number): void;
     /**
      * Removes a spot color from the list of set spot colors.
      * @param name - The name of a spot color.
@@ -3060,6 +3174,15 @@ export declare class EditorAPI {
      * @returns The color spot name.
      */
     getSpotColorForCutoutType(type: CutoutType): string;
+    /**
+     * Converts a color to the given color space.
+     * @param color - The color to convert.
+     * @param colorSpace - The color space to convert to.
+     * @returns The converted color.
+     */
+    convertColorToColorSpace(color: Color, colorSpace: 'sRGB'): RGBAColor;
+    convertColorToColorSpace(color: Color, colorSpace: 'CMYK'): CMYKColor;
+    convertColorToColorSpace(color: Color, colorSpace: ColorSpace): never;
 }
 
 /**
@@ -3170,7 +3293,7 @@ export declare type FontWeight = 'thin' | 'extraLight' | 'Light' | 'normal' | 'm
 /** @public */
 export declare interface GradientColorStop {
     /** A color value within a gradient. */
-    color: RGBAColor | SpotColor;
+    color: Color;
     /** The relative position of the color within the gradient in the range [0, 1]. */
     stop: number;
 }
@@ -3407,9 +3530,13 @@ export declare type RGBA = [r: number, g: number, b: number, a: number];
  * @public
  */
 export declare interface RGBAColor {
+    /** Red */
     r: number;
+    /** Green */
     g: number;
+    /** Blue */
     b: number;
+    /** Alpha */
     a: number;
 }
 
@@ -3418,8 +3545,11 @@ export declare interface RGBAColor {
  * @public
  */
 export declare interface RGBColor {
+    /** Red */
     r: number;
+    /** Green */
     g: number;
+    /** Blue */
     b: number;
 }
 
@@ -3532,20 +3662,22 @@ export declare class SceneAPI {
      */
     getPages(): DesignBlockId[];
     /**
-     * Sets the zoom level of the active scene.
-     * Only has an effect if the zoom level is not handled by the UI.
+     * Set the zoom level of the scene, e.g., for headless versions.
+     * This only shows an effect if the zoom level is not handled/overwritten by the UI.
+     * Setting a zoom level of 2.0f results in one dot in the design to be two pixels on the screen.
      *
      * @param zoomLevel - The new zoom level.
      */
     setZoomLevel(zoomLevel?: number): void;
     /**
-     * Query a camera zoom level of the active scene.
+     * Get the zoom level of the scene or for a camera in the scene in unit `dpx/dot`. A zoom level of 2.0 results in one pixel in the design to be two pixels
+     * on the screen.
      * @returns The zoom level of the block's camera.
      */
     getZoomLevel(): number;
     /**
      * Sets the zoom and focus to show a block.
-     * Only has an effect if the zoom level is not handled by the UI.
+     * This only shows an effect if the zoom level is not handled/overwritten by the UI.
      * Without padding, this results in a tight view on the block.
      *
      * @param id - The block that should be focused on.
@@ -3558,7 +3690,7 @@ export declare class SceneAPI {
     zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>;
     /**
      * Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box.
-     * Only has an effect if the zoom level is not handled by the UI.
+     * This only shows an effect if the zoom level is not handled/overwritten by the UI.
      * Without padding, this results in a tight view on the block.
      * No more than one block per scene can have zoom auto-fit enabled.
      * Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment.
@@ -3571,7 +3703,7 @@ export declare class SceneAPI {
     enableZoomAutoFit(id: DesignBlockId, axis: 'Horizontal' | 'Vertical', paddingBefore?: number, paddingAfter?: number): void;
     /**
      * Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box.
-     * Only has an effect if the zoom level is not handled by the UI.
+     * This only shows an effect if the zoom level is not handled/overwritten by the UI.
      * Without padding, this results in a tight view on the block.
      * Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment.
      *
@@ -3586,17 +3718,69 @@ export declare class SceneAPI {
     /**
      *  Disables any previously set zoom auto-fit.
      *
-     * @param blockOrScene - The scene or a block in the scene for which to disable a zoom auto-fit.
+     * @param blockOrScene - The scene or a block in the scene for which to disable zoom auto-fit.
      */
     disableZoomAutoFit(blockOrScene: DesignBlockId): void;
     /**
      *  Queries whether zoom auto-fit is enabled.
      *
-     * @param blockOrScene - The scene or a block in the scene for which to disable a zoom auto-fit.
+     * @param blockOrScene - The scene or a block in the scene for which to query the zoom auto-fit.
      * @returns True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false
      * otherwise.
      */
     isZoomAutoFitEnabled(blockOrScene: DesignBlockId): boolean;
+    /**
+     * Continually ensures the camera position to be within the width and height of a block's axis-aligned bounding box.
+     * Without padding, this results in a tight clamp on the block. With padding, the padded part of the
+     * block is ensured to be visible. No more than one block per scene can have camera position clamping enabled.
+     *
+     * @param id - The block for which the camera position is adjusted to, usually, the scene or a page.
+     * @param paddingLeft - Optional padding in screen pixels to the left of the block.
+     * @param paddingTop - Optional padding in screen pixels to the top of the block.
+     * @param paddingRight - Optional padding in screen pixels to the right of the block.
+     * @param paddingBottom - Optional padding in screen pixels to the bottom of the block.
+     * @param scaledPaddingLeft - Optional padding in pixels to the left of the block that scales with the zoom level.
+     * @param scaledPaddingTop - Optional padding in pixels to the top of the block that scales with the zoom level.
+     * @param scaledPaddingRight - Optional padding in pixels to the right of the block that scales with the zoom level.
+     * @param scaledPaddingBottom - Optional padding in pixels to the bottom of the block that scales with the zoom level.
+     */
+    unstable_enableCameraPositionClamping(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number, scaledPaddingLeft?: number, scaledPaddingTop?: number, scaledPaddingRight?: number, scaledPaddingBottom?: number): void;
+    /**
+     *  Disables any previously set position clamping for the current scene.
+     */
+    unstable_disableCameraPositionClamping(): void;
+    /**
+     *  Queries whether position clamping is enabled.
+     *
+     * @param blockOrScene - Optionally, the scene or a block in the scene for which to query the position clamping.
+     * @returns True if the given block has position clamping set or the scene contains a block for which position clamping is set, false
+     * otherwise.
+     */
+    unstable_isCameraPositionClampingEnabled(blockOrScene?: number | null): boolean;
+    /**
+     * Continually ensures the zoom level of the camera in the active scene to be in the given range.
+     *
+     * @param id - The block for which the camera zoom limits are adjusted to, usually, the scene or a page.
+     * @param minZoomLimit - The minimum zoom level limit when zooming out, unlimited when negative.
+     * @param maxZoomLimit - The maximum zoom level limit when zooming in, unlimited when negative.
+     * @param paddingLeft - Optional padding in screen pixels to the left of the block. Only applied when the block is not a camera.
+     * @param paddingTop - Optional padding in screen pixels to the top of the block. Only applied when the block is not a camera.
+     * @param paddingRight - Optional padding in screen pixels to the right of the block. Only applied when the block is not a camera.
+     * @param paddingBottom - Optional padding in screen pixels to the bottom of the block. Only applied when the block is not a camera.
+     *
+     */
+    unstable_enableCameraZoomClamping(id: DesignBlockId, minZoomLimit?: number, maxZoomLimit?: number, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void;
+    /**
+     * Disables any previously set zoom clamping for the current scene.
+     */
+    unstable_disableCameraZoomClamping(): void;
+    /**
+     * Queries whether zoom clamping is enabled.
+     *
+     * @param blockOrScene - Optionally, the scene or a block for which to query the zoom clamping.
+     * @returns True if the given block has zoom clamping set or the scene contains a block for which zoom clamping is set, false otherwise.
+     */
+    unstable_isCameraZoomClampingEnabled(blockOrScene?: number | null): boolean;
     /**
      * Subscribe to changes to the zoom level.
      * @param callback - This function is called at the end of the engine update, if the zoom level has changed.
@@ -3634,6 +3818,8 @@ export declare type SettingsColorRGBA = 'clearColor' | 'errorStateColor' | 'high
 export declare type SettingsEnum = {
     role: RoleString;
     doubleClickSelectionMode: 'Direct' | 'Hierarchical';
+    'touch/pinchAction': 'None' | 'Zoom' | 'Scale';
+    'touch/rotateAction': 'None' | 'Rotate';
     [key: ArbitraryString]: string;
 };
 
@@ -3675,10 +3861,8 @@ declare type Source<T> = (handler: Handler<T>) => UnsubscribeFn;
 /** @public */
 export declare interface SpotColor {
     name: string;
-}
-
-declare interface SpotColorLookup {
-    getSpotColorRGBA(name: string): [r: number, g: number, b: number, a: number];
+    tint: number;
+    externalReference: string;
 }
 
 /** @public */