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

package/index.d.ts

@@ -23,25 +23,11 @@ export declare interface Asset {
      */
     id: string;
     /**  Groups of the asset.  */
-    groups?: Groups;
+    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;
 }
 
 /**
@@ -167,6 +153,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,17 @@ export declare interface AssetDefinition extends Asset {
     tags?: Record<Locale, string[]>;
 }
 
+/**
+ * An asset can be member of multiple groups. Groups have a semantic meaning
+ * used to build and group UIs exploring the assets, e.g.sections in the
+ * content library, or for things like topics in Unsplash for instance.
+ *
+ * Tags in comparison have are more loosely hold meaning used for extended
+ * searching/filtering.
+ * @public
+ */
+export declare type AssetGroups = string[];
+
 /** @public */
 declare type AssetLibraryEntries = AssetLibraryEntry[] | ((currentAssetLibraryEntries: AssetLibraryEntry[], context: {
     selectedBlocks: {
@@ -310,6 +325,10 @@ declare interface AssetLibraryEntryView {
      * Otherwise it will render nothing
      */
     cardBackgroundPreferences?: CardBackground[];
+    /**
+     * Draws a border around the card if set to true
+     */
+    cardBorder?: boolean;
     /**
      * Overwrite the label of a card for a specific asset result
      */
@@ -322,6 +341,40 @@ declare interface AssetLibraryEntryView {
      * Add custom styles to a label for a specific asset result
      */
     cardLabelStyle?: (assetResult: AssetResult) => Record<string, string | undefined>;
+    /**
+     * Position the label inside or below the card
+     */
+    cardLabelPosition?: (assetResult: AssetResult) => 'inside' | 'below';
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -340,9 +393,9 @@ export declare interface AssetQueryData {
      */
     tags?: string | string[];
     /** Query only these groups */
-    groups?: Groups;
+    groups?: AssetGroups;
     /** Filter out assets with this groups */
-    excludeGroups?: Groups;
+    excludeGroups?: AssetGroups;
     /** Choose the locale of the labels and tags for localized search and filtering */
     locale?: Locale;
     /**
@@ -407,6 +460,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
@@ -466,6 +530,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
@@ -681,10 +756,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.
@@ -1208,6 +1283,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.
@@ -1216,6 +1305,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;
     /**
@@ -1223,6 +1313,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;
     /**
@@ -1231,6 +1322,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;
     /**
@@ -1238,6 +1330,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;
     /**
@@ -1245,6 +1338,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;
     /**
@@ -1813,7 +1907,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.
@@ -1824,7 +1918,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.
@@ -2455,17 +2549,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
+ */
+declare type Color = RGBAColor | CMYKColor | SpotColor;
+
+/**
+ * @public
+ */
+export declare type ColorSpace = 'sRGB' | 'CMYK' | 'SpotColor';
+
 /**
  * Asset results that are returned from the engine.
  *
@@ -2837,7 +2953,7 @@ export declare type _DeepPartial<T> = {
 /**
  * @public
  */
-declare type DefaultAssetSourceId = 'ly.img.sticker' | 'ly.img.vectorpath' | 'ly.img.filter.lut' | 'ly.img.filter.duotone';
+declare type DefaultAssetSourceId = 'ly.img.sticker' | 'ly.img.vectorpath' | 'ly.img.filter.lut' | 'ly.img.filter.duotone' | 'ly.img.colors.defaultPalette';
 
 /**
  * @public
@@ -3148,6 +3264,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.
@@ -3157,6 +3280,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.
@@ -3176,6 +3309,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;
 }
 
 /**
@@ -3595,7 +3737,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;
 }
@@ -3621,17 +3763,6 @@ a: number
  */
 export declare type GradientType = 'Linear' | 'Radial' | 'Conical';
 
-/**
- * An asset can be member of multiple groups. Groups have a semantic meaning
- * used to build and group UIs exploring the assets, e.g.sections in the
- * content library, or for things like topics in Unsplash for instance.
- *
- * Tags in comparison have are more loosely hold meaning used for extended
- * searching/filtering.
- * @public
- */
-declare type Groups = string[];
-
 /**
  * Will be called by a stream whenever a new value is available.
  * @public
@@ -3896,7 +4027,7 @@ export declare interface _RequiredConfiguration extends Omit<_EngineConfiguratio
     defaultFont?: _EngineConfiguration['defaultFont'];
     presets: Omit<_EngineConfiguration['presets'], 'pageFormats' | 'colorPalettes'> & {
         /**
-         * @deprecated The configuration options `presets.colorPalettes` has been moved to `ui.colorPalette`.
+         * @deprecated The configuration options `presets.colorPalettes` has been deprecated. Please use `ui.colorLibraries` and asset sources instead.
          */
         colorPalettes?: {
             [id: string]: _EngineConfigTypes.ColorPaletteDefinition;
@@ -3934,9 +4065,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;
 }
 
@@ -3945,8 +4080,11 @@ export declare interface RGBAColor {
  * @public
  */
 export declare interface RGBColor {
+    /** Red */
     r: number;
+    /** Green */
     g: number;
+    /** Blue */
     b: number;
 }
 
@@ -4065,20 +4203,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.
@@ -4091,7 +4231,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.
@@ -4104,7 +4244,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.
      *
@@ -4119,17 +4259,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.
@@ -4167,6 +4359,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;
 };
 
@@ -4202,10 +4396,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 */
@@ -4301,7 +4493,11 @@ export declare interface UserInterface {
     };
     hide?: boolean;
     smallViewportOptimization?: boolean;
+    /**
+     * @deprecated The configuration options `ui.colorPalette` has been deprecated. Please use `ui.colorLibraries` and asset sources instead.
+     */
     colorPalette?: PaletteColor[];
+    colorLibraries?: string[];
     pageFormats?: {
         [id: string]: PageFormatDefinition;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesdk/cesdk-js",
-  "version": "1.15.0-rc.1",
+  "version": "1.16.0-rc.0",
   "main": "./cesdk.umd.js",
   "types": "./index.d.ts",
   "homepage": "https://www.img.ly",