@cesdk/engine 1.11.0-preview.1 → 1.11.0-rc.0

package/index.d.ts

@@ -1621,6 +1621,51 @@ export declare class BlockAPI {
      * @returns The drop shadow's clipping.
      */
     getDropShadowClip(id: DesignBlockId): boolean;
+    /**
+     * Create a Cutout block.
+     * @param blocks - The blocks whose shape will serve as the basis for the cutout's path.
+     * @returns The handle of the created Cutout.
+     */
+    createCutoutFromBlocks(ids: DesignBlockId[]): DesignBlockId;
+    /**
+     * Create a Cutout block.
+     * @param path - An SVG string describing a path.
+     * @returns The handle of the created Cutout.
+     */
+    createCutoutFromPath(path: string): DesignBlockId;
+    /**
+     * Set the cutout's offset from the underlying path.
+     * @param block - The block whose offset should be set.
+     * @param offset - The offset to be set.
+     */
+    setCutoutOffset(id: DesignBlockId, offset: number): void;
+    /**
+     * Get the cutout's offset from the underlying path.
+     * @param block - The block whose offset should be queried.
+     * @returns The cutout's offset.
+     */
+    getCutoutOffset(id: DesignBlockId): number;
+    /**
+     * Set the cutout's type.
+     * @param block - The block whose type should be set.
+     * @param type - The type to be set.
+     */
+    setCutoutType(id: DesignBlockId, type: CutoutType): void;
+    /**
+     * Get the cutout's type.
+     * @param block - The block whose type should be queried.
+     * @returns The cutout's type.
+     */
+    getCutoutType(id: DesignBlockId): CutoutType;
+    /** Perform a boolean operation on the given Cutout blocks.
+     * The cutout offset of the new block is 0.
+     * The cutout type of the new block is that of the first block.
+     * When performing a `Difference` operation, the first block is the block subtracted from.
+     * @param blocks - The blocks with which to perform to the operation.
+     * @param op - The boolean operation to perform.
+     * @returns The newly created block or an error.
+     */
+    createCutoutFromOperation(ids: DesignBlockId[], op: CutoutOperation): DesignBlockId;
     /**
      * Inserts the given text into the selected range of the text block.
      * @param block - The text block into which to insert the given text.
@@ -1657,9 +1702,11 @@ export declare class BlockAPI {
      * Returns the ordered unique list of colors of the text in the selected range.
      * @param block - The text block whose colors should be returned.
      * @param from - The start index of the UTF-16 range whose colors should be returned.
-     * If the value is negative, this will fall back to the start of the entire text range.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start 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 start of the entire text range.
      * @param to - The UTF-16 index after the last grapheme whose colors should be returned.
-     * If the value is negative, this will fall back to the end of the entire text range.
+     *   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>;
     /**
@@ -1684,6 +1731,29 @@ export declare class BlockAPI {
      *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
      */
     getTextFontStyles(id: DesignBlockId, from?: number, to?: number): FontStyle[];
+    /**
+     * Returns the ordered list of text cases of the text in the selected range.
+     * @param block - The text block whose text cases should be returned.
+     * @param from - The start index of the UTF-16 range whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start 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 start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose text cases should be returned.
+     *   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.
+     */
+    getTextCases(id: DesignBlockId, from?: number, to?: number): TextCase[];
+    /**
+     * Sets the given text case for the selected range of text.
+     * @param id - The text block whose text case should be changed.
+     * @param textCase - The new text case value.
+     * @param from - The start index of the UTF-16 range whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start 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 start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose text cases should be returned.
+     *   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.
+     */
+    setTextCase(id: DesignBlockId, textCase: TextCase, from?: number, to?: number): void;
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -2229,26 +2299,32 @@ export declare interface CMYKColor {
 }
 
 /**
- * A color definition for the custom color palette.
- * The RGB and CMYK components must all be specified in the range [0-1].
+ * @deprecated This type definition has been removed.
+ * Instead of `ConfigTypes.Color`, this can be imported directly as `PaletteColor`.
  * @public
  */
-declare type Color_2 = HexColorString | RGBColor | RGBAColor | SpotColor;
+declare type Color_2 = PaletteColor;
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type ColorDefinition = Preset & {
     value: Color_2;
 };
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type ColorPaletteDefinition = Preset & {
     entries: Color_2[];
 };
 
 declare namespace ConfigTypes {
     export {
-        HexColorString,
         Color_2 as Color,
+        HexColorString_2 as HexColorString,
         AssetSources,
         AssetSource_2 as AssetSource,
         AssetResult_2 as AssetResult,
@@ -2372,12 +2448,11 @@ declare class CreativeEngine {
      * `base_url` defaults to 'https://cdn.img.ly/assets/v1'.
      * Each source is created via `addLocalSource` and populated with the parsed assets. To modify the available
      * assets, you may either exclude certain IDs via `excludeAssetSourceIds` or alter the sources after creation.
-     *
-     * @param baseURL - The source of the asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/v1'`.
-     * @param excludeAssetSourceIds - A list of IDs, that will be ignored during load.
      */
     addDefaultAssetSources({ baseURL, excludeAssetSourceIds }?: {
+        /** The source of the asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/v1'`. */
         baseURL?: string;
+        /** A list of IDs, that will be ignored during load. */
         excludeAssetSourceIds?: DefaultAssetSourceId[];
     }): Promise<void>;
     /**
@@ -2392,14 +2467,13 @@ declare class CreativeEngine {
      * - `'ly.img.audio.upload'` - Demo source to upload audio assets
      * - `'ly.img.video'` - Sample videos
      * - `'ly.img.video.upload'` - Demo source to upload video assets
-     *
-     * @param excludeAssetSourceIds - A list of IDs, that will be ignored during load.
-     * @param sceneMode - if 'Video' video specific demo asset sources will be loaded as well (default 'Design')
-     * @param withUploadAssetSources - if 'true' asset sources for uploads are added (default false)
      */
     addDemoAssetSources({ excludeAssetSourceIds, sceneMode, withUploadAssetSources }?: {
+        /** A list of IDs, that will be ignored during load */
         excludeAssetSourceIds?: DemoAssetSourceId[];
+        /** If 'Video' video specific demo asset sources will be loaded as well (default 'Design') */
         sceneMode?: SceneMode;
+        /** If 'true' asset sources for uploads are added (default false) */
         withUploadAssetSources?: boolean;
     }): Promise<void>;
 
@@ -2420,6 +2494,16 @@ export declare interface CursorEvent extends CustomEvent<string> {
     preventDefault(): void;
 }
 
+/**
+ * @public
+ */
+export declare type CutoutOperation = 'Difference' | 'Intersection' | 'Union' | 'XOR';
+
+/**
+ * @public
+ */
+export declare type CutoutType = 'Solid' | 'Dashed';
+
 /**
  * @public
  */
@@ -2447,6 +2531,7 @@ export declare enum DesignBlockType {
     Image = "//ly.img.ubq/image",
     Video = "//ly.img.ubq/video",
     VideoFill = "//ly.img.ubq/fill/video",
+    ImageFill = "//ly.img.ubq/fill/image",
     Audio = "//ly.img.ubq/audio",
     Text = "//ly.img.ubq/text",
     Sticker = "//ly.img.ubq/sticker",
@@ -2456,7 +2541,8 @@ export declare enum DesignBlockType {
     StarShape = "//ly.img.ubq/shapes/star",
     PolygonShape = "//ly.img.ubq/shapes/polygon",
     EllipseShape = "//ly.img.ubq/shapes/ellipse",
-    Group = "//ly.img.ubq/group"
+    Group = "//ly.img.ubq/group",
+    Cutout = "//ly.img.ubq/cutout"
 }
 
 /**
@@ -2722,6 +2808,19 @@ export declare class EditorAPI {
      * @returns An empty result on success, an error otherwise.
      */
     removeSpotColor(name: string): void;
+    /**
+     * Set the spot color assign to a cutout type.
+     * All cutout blocks of the given type will be immediately assigned that spot color.
+     * @param type - The cutout type.
+     * @param name - The spot color name to assign.
+     */
+    setSpotColorForCutoutType(type: CutoutType, color: string): void;
+    /**
+     * Get the name of the spot color assigned to a cutout type.
+     * @param type - The cutout type.
+     * @returns The color spot name.
+     */
+    getSpotColorForCutoutType(type: CutoutType): string;
 }
 
 /**
@@ -2878,7 +2977,14 @@ declare type Handler<T> = (v: T) => void;
  * @example #6686FF or #6686FFFF
  * @public
  */
-declare type HexColorString = string;
+export declare type HexColorString = string;
+
+/**
+ * @deprecated This type definition has been moved
+ * It can instead be imported directly as `HexColorString`
+ * @public
+ */
+declare type HexColorString_2 = HexColorString;
 
 /**
  * A numerical identifier for a history stack
@@ -2947,6 +3053,7 @@ declare enum MimeType_2 {
     Jpeg = "image/jpeg",
     Tga = "image/x-tga",
     Mp4 = "video/mp4",
+    QuickTime = "video/quicktime",
     Binary = "application/octet-stream",
     Pdf = "application/pdf",
     Zip = "application/zip"
@@ -3018,14 +3125,28 @@ export declare interface PageDuration {
     end: number;
 }
 
-/** @public */
+/**
+ * @deprecated This type definition is unused and will be removed
+ * @public
+ */
 declare type PageFormatDefinition = Preset & {
     width: number;
     height: number;
-    unit: 'px' | 'mm' | 'in';
+    /** @deprecated This property is unused and will be removed  */
+    dpi?: number;
+    /** @deprecated This property is unused and will be removed  */
+    bleedMargin?: number;
+    unit: 'px' | 'mm' | 'in' | DesignUnit;
     fixedOrientation?: boolean;
 };
 
+/**
+ * A color definition for the custom color palette.
+ * The RGB and CMYK components must all be specified in the range [0-1].
+ * @public
+ */
+export declare type PaletteColor = HexColorString | RGBColor | RGBAColor | SpotColor;
+
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -3035,7 +3156,10 @@ declare type PageFormatDefinition = Preset & {
  */
 export declare type PositionMode = 'Absolute' | 'Percent' | 'Auto';
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type Preset = {
     meta?: {
         default?: boolean;
@@ -3044,20 +3168,28 @@ declare type Preset = {
     };
 };
 
-/** @public */
+/**
+ * @deprecated This type definition will be removed.
+ * If you need to reference this type in your code,
+ * use `Configuration['presets']` instead of `ConfigTypes.Presets`.
+ * @public
+ */
 declare type Presets = {
+    /**
+     * @deprecated The configuration option `presets.colors` does not exist anymore.
+     */
     colors?: {
-        [id: string]: ColorDefinition;
+        [id: string]: Color_2;
     };
     typefaces?: {
         [id: string]: TypefaceDefinition;
     };
-    pageFormats?: {
-        [id: string]: PageFormatDefinition;
-    };
     colorPalettes?: {
         [id: string]: ColorPaletteDefinition;
     };
+    pageFormats?: {
+        [id: string]: PageFormatDefinition;
+    };
     templates?: {
         [id: string]: TemplateDefinition;
     };
@@ -3469,14 +3601,23 @@ export declare function supportsVideo(): boolean;
 export declare function supportsWasm(): boolean;
 
 /** @public */
-declare type TemplateDefinition = Preset & {
+declare type TemplateDefinition = {
+    /** @deprecated The meta field is not used anymore */
+    meta?: Preset['meta'];
     label: string;
     scene: string | URL | (() => Promise<string>);
     thumbnailURL?: string | URL;
 };
 
+/**
+ * @public
+ */
+export declare type TextCase = 'Normal' | 'Uppercase' | 'Lowercase' | 'Titlecase';
+
 /** @public */
-declare type TypefaceDefinition = Preset & {
+declare type TypefaceDefinition = {
+    /** @deprecated The meta field is not used anymore */
+    meta?: Preset['meta'];
     family: string;
     fonts: {
         fontURL: string;