@cesdk/engine 1.18.1 → 1.19.0

package/index.d.ts

@@ -1,7 +1,3 @@
-declare type ArbitraryString = string & {
-    arbitrary?: any;
-};
-
 /**
  * Generic asset information
  * @public
@@ -210,6 +206,8 @@ export declare type AssetMetaData = {
     width?: number;
     height?: number;
     duration?: string;
+    effectType?: EffectType;
+    blurType?: BlurType;
 } & Record<string, unknown>;
 
 /**
@@ -280,11 +278,6 @@ export declare interface AssetResult extends Asset {
 
 declare type _AssetResult = AssetResult;
 
-/** @public */
-declare interface AssetResultContext {
-    sourceId: string;
-}
-
 /** @public */
 declare interface AssetResultCredits {
     name: string;
@@ -297,12 +290,6 @@ declare interface AssetResultLicense {
     url: string;
 }
 
-/** @public */
-declare interface AssetResultUtm {
-    source: string;
-    medium: string;
-}
-
 /**
  * Asset Color payload RGB representation
  * @public
@@ -469,13 +456,13 @@ export declare class BlockAPI {
      * @param type - The type of the fill object that shall be created.
      * @returns The created fill's handle.
      */
-    createFill(type: string): DesignBlockId;
+    createFill(type: FillType): DesignBlockId;
     /**
      * Get the type of the given block, fails if the block is invalid.
      * @param id - The block to query.
      * @returns The blocks type.
      */
-    getType(id: DesignBlockId): DesignBlockType;
+    getType(id: DesignBlockId): ObjectTypeLonghand;
     /**
      * Get the kind of the given block, fails if the block is invalid.
      * @param id - The block to query.
@@ -580,7 +567,7 @@ export declare class BlockAPI {
      * @param type - The type to search for.
      * @returns A list of block ids.
      */
-    findByType(type: DesignBlockType): DesignBlockId[];
+    findByType(type: ObjectType): DesignBlockId[];
     /**
      * Finds all blocks with the given kind.
      * @param kind - The kind to search for.
@@ -602,7 +589,7 @@ export declare class BlockAPI {
      * @param type - The type of the shape object that shall be created.
      * @returns The created shape's handle.
      */
-    createShape(type: string): DesignBlockId;
+    createShape(type: ShapeType): DesignBlockId;
     /**
      * Query if the given block has a shape property.
      * @param id - The block to query.
@@ -648,6 +635,18 @@ export declare class BlockAPI {
      * @param clipped - Whether the block should clips its contents to its frame.
      */
     setClipped(id: DesignBlockId, clipped: boolean): void;
+    /**
+     * Query a block's transform locked state. If true, the block's transform can't be changed.
+     * @param id - The block to query.
+     * @returns True if transform locked, false otherwise.
+     */
+    isTransformLocked(id: DesignBlockId): boolean;
+    /**
+     * Update a block's transform locked state.
+     * @param id - The block to update.
+     * @param locked - Whether the block's transform should be locked.
+     */
+    setTransformLocked(id: DesignBlockId, locked: boolean): void;
     /**
      * Query a block's x position.
      * @param id - The block to query.
@@ -1362,6 +1361,18 @@ export declare class BlockAPI {
      * @deprecated Query the fills type using getFill() and getType() instead.
      */
     hasFillColor(id: DesignBlockId): boolean;
+    /**
+     * Query if the given block is included on the exported result.
+     * @param id - The block to query.
+     * @returns true, if the block is included on the exported result, false otherwise
+     */
+    isIncludedInExport(id: DesignBlockId): boolean;
+    /**
+     * Set if you want the given design block to be included in exported result.
+     * @param id - The block whose exportable state should be set.
+     * @param enabled - If true, the block will be included on the exported result.
+     */
+    setIncludedInExport(id: DesignBlockId, enabled: boolean): void;
     /**
      * Set the fill color of the given design block.
      * @param id - The block whose fill color should be set.
@@ -1399,7 +1410,7 @@ export declare class BlockAPI {
      * @param type - The type id of the effect.
      * @returns The created effects handle.
      */
-    createEffect(type: string): DesignBlockId;
+    createEffect(type: EffectType): DesignBlockId;
     /**
      * Queries whether the block supports effects.
      * @param id - The block to query.
@@ -1456,7 +1467,7 @@ export declare class BlockAPI {
      * @param type - The type id of the block.
      * @returns The handle of the newly created blur.
      */
-    createBlur(type: string): DesignBlockId;
+    createBlur(type: BlurType): DesignBlockId;
     /**
      * Checks whether the block supports blur.
      * @param id - The block to query.
@@ -2276,6 +2287,27 @@ export declare interface BlurEvent extends CustomEvent<EventTarget | null> {
     preventDefault(): void;
 }
 
+/**
+ * The block type IDs for the blur blocks. These are the IDs used to create new blurs
+ * using `cesdk.engine.editor.createBlur(id)`.
+ * @public
+ */
+export declare type BlurType = BlurTypeShorthand | BlurTypeLonghand;
+
+/**
+ * The longhand block type IDs for the blur blocks. These are the IDs used to create new blurs
+ * using `cesdk.engine.editor.createBlur(id)`.
+ * @public
+ */
+export declare type BlurTypeLonghand = `//ly.img.ubq/blur/${BlurTypeShorthand}`;
+
+/**
+ * The shorthand block type IDs for the blur blocks. These are the IDs used to create new blurs
+ * using `cesdk.engine.editor.createBlur(id)`.
+ * @public
+ */
+export declare type BlurTypeShorthand = 'uniform' | 'linear' | 'mirrored' | 'radial';
+
 declare type CameraSettings = {
     /** Horizontal resolution in physical pixels */
     width: number;
@@ -2583,7 +2615,8 @@ export declare namespace ConfigTypes {
 /** @public */
 export declare interface Configuration {
     baseURL: string;
-    license?: string;
+    license: string;
+    userId?: string;
     core: {
         baseURL: string;
     };
@@ -2712,6 +2745,17 @@ declare class CreativeEngine {
      */
     unstable_setVideoExportInactivityTimeout(timeout: number): void;
 
+    /**
+     * Install the mousewheel event handler for the CreativeEngine on a different
+     * element than the canvas.
+     *
+     * This can be useful if you are rendering HTML elements on top of the canvas
+     * and want to scroll the canvas when the mouse is over those elements.
+     *
+     * @returns A function that removes the event handler from the target again
+     *          and adds it back to the canvas.
+     */
+    setWheelEventTarget(target: HTMLElement): () => void;
     get element(): HTMLCreativeEngineCanvasElement | undefined;
     /**
      * Dispose the engine.
@@ -2739,12 +2783,12 @@ declare class CreativeEngine {
      * - `'ly.img.filter.duotone'` - Color effects of various kinds.
      *
      * These assets are parsed from the IMG.LY CDN at \{\{base_url\}\}/<id>/content.json, where
-     * `base_url` defaults to 'https://cdn.img.ly/assets/v1'.
+     * `base_url` defaults to 'https://cdn.img.ly/assets/v2'.
      * 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.
      */
     addDefaultAssetSources({ baseURL, excludeAssetSourceIds }?: {
-        /** The source of the asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/v1'`. */
+        /** The source of the asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/v2'`. */
         baseURL?: string;
         /** A list of IDs, that will be ignored during load. */
         excludeAssetSourceIds?: DefaultAssetSourceId[];
@@ -2763,7 +2807,7 @@ declare class CreativeEngine {
      * - `'ly.img.video.upload'` - Demo source to upload video assets
      */
     addDemoAssetSources({ baseURL, excludeAssetSourceIds, sceneMode, withUploadAssetSources }?: {
-        /** The source of the demo asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/demo/v1'`. */
+        /** The source of the demo asset definitions, must be absolute. Defaults to `'https://cdn.img.ly/assets/demo/v2'`. */
         baseURL?: string;
         /** A list of IDs, that will be ignored during load */
         excludeAssetSourceIds?: DemoAssetSourceId[];
@@ -2804,7 +2848,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' | 'ly.img.colors.defaultPalette';
+export declare type DefaultAssetSourceId = 'ly.img.sticker' | 'ly.img.vectorpath' | 'ly.img.colors.defaultPalette' | 'ly.img.filter.lut' | 'ly.img.filter.duotone' | 'ly.img.effect' | 'ly.img.blur';
 
 /**
  * @public
@@ -2818,34 +2862,25 @@ export declare type DemoAssetSourceId = 'ly.img.template' | 'ly.img.image.upload
 export declare type DesignBlockId = number;
 
 /**
+ * The block type IDs for the top-level design blocks. These are the IDs used to create new blocks
+ * using `cesdk.engine.editor.cerate(id)`.
  * @public
  */
-export declare enum DesignBlockType {
-    Scene = "//ly.img.ubq/scene",
-    Stack = "//ly.img.ubq/stack",
-    Camera = "//ly.img.ubq/camera",
-    Page = "//ly.img.ubq/page",
-    Image = "//ly.img.ubq/image",
-    Graphic = "//ly.img.ubq/graphic",
-    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",
-    VectorPath = "//ly.img.ubq/vector_path",
-    RectShape = "//ly.img.ubq/shapes/rect",
-    LineShape = "//ly.img.ubq/shapes/line",
-    StarShape = "//ly.img.ubq/shapes/star",
-    PolygonShape = "//ly.img.ubq/shapes/polygon",
-    EllipseShape = "//ly.img.ubq/shapes/ellipse",
-    Group = "//ly.img.ubq/group",
-    Cutout = "//ly.img.ubq/cutout",
-    ColorFill = "//ly.img.ubq/fill/color",
-    LinearGradientFill = "//ly.img.ubq/fill/gradient/linear",
-    RadialGradientFill = "//ly.img.ubq/fill/gradient/radial",
-    ConicalGradientFill = "//ly.img.ubq/fill/gradient/conical"
-}
+export declare type DesignBlockType = DesignBlockTypeShorthand | DesignBlockTypeLonghand;
+
+/**
+ * The longhand block type IDs for the top-level design blocks. These are the IDs used to create new blocks
+ * using `cesdk.engine.editor.cerate(id)`.
+ * @public
+ */
+export declare type DesignBlockTypeLonghand = `//ly.img.ubq/${DesignBlockTypeShorthand}`;
+
+/**
+ * The shorthand block type IDs for the top-level design blocks. These are the IDs used to create new blocks
+ * using `cesdk.engine.editor.cerate(id)`.
+ * @public
+ */
+export declare type DesignBlockTypeShorthand = 'scene' | 'stack' | 'camera' | 'page' | 'graphic' | 'audio' | 'text' | 'group' | 'cutout';
 
 /**
  * The unit type in which the page values (size, distances, etc.) are defined.
@@ -2859,6 +2894,8 @@ export declare type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
 export declare class EditorAPI {
     #private;
 
+
+
     /**
      * Subscribe to changes to the editor state.
      * @param callback - This function is called at the end of the engine update, if the editor state has changed.
@@ -2964,12 +3001,18 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingBool(keypath: SettingsBool, value: boolean): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingBool(keypath: `ubq://${SettingsBool}`, value: boolean): void;
+
     /**
      * Get a boolean setting.
      * @param keypath - The settings keypath, e.g. `doubleClickToCropEnabled`
      * @throws An error, if the keypath is invalid.
      */
     getSettingBool(keypath: SettingsBool): boolean;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingBool(keypath: `ubq://${SettingsBool}`): boolean;
+
     /**
      * Set an integer setting.
      * @param keypath - The settings keypath.
@@ -2990,12 +3033,16 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingFloat(keypath: SettingsFloat, value: number): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingFloat(keypath: `ubq://${SettingsFloat}`, value: number): void;
     /**
      * Get a float setting.
      * @param keypath - The settings keypath, e.g. `positionSnappingThreshold`
      * @throws An error, if the keypath is invalid.
      */
     getSettingFloat(keypath: SettingsFloat): number;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingFloat(keypath: `ubq://${SettingsFloat}`): number;
     /**
      * Set a string setting.
      * @param keypath - The settings keypath, e.g. `license`
@@ -3003,24 +3050,32 @@ export declare class EditorAPI {
      * @throws An error, if the keypath is invalid.
      */
     setSettingString(keypath: SettingsString, value: string): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingString(keypath: `ubq://${SettingsString}`, value: string): void;
     /**
      * Get a string setting.
      * @param keypath - The settings keypath, e.g. `license`
      * @throws An error, if the keypath is invalid.
      */
     getSettingString(keypath: SettingsString): string;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingString(keypath: `ubq://${SettingsString}`): string;
     /**
      * Set a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @param value - The The value to set.
      */
     setSettingColor(keypath: SettingsColor, value: Color): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingColor(keypath: `ubq://${SettingsColor}`, value: Color): void;
     /**
      * Get a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @throws An error, if the keypath is invalid.
      */
     getSettingColor(keypath: SettingsColor): Color;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingColor(keypath: `ubq://${SettingsColor}`): Color;
     /**
      * Set a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
@@ -3030,32 +3085,38 @@ export declare class EditorAPI {
      * @param a - The alpha color component in the range of 0 to 1.
      * @deprecated Use setSettingColor() instead.
      */
-    setSettingColorRGBA(keypath: SettingsColorRGBA, r: number, g: number, b: number, a?: number): void;
+    setSettingColorRGBA(keypath: SettingsColorRGBA | `ubq://${SettingsColorRGBA}`, r: number, g: number, b: number, a?: number): void;
     /**
      * Get a color setting.
      * @param keypath - The settings keypath, e.g. `highlightColor`.
      * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
      * @deprecated Use getSettingColor() instead.
      */
-    getSettingColorRGBA(keypath: SettingsColorRGBA): RGBA;
+    getSettingColorRGBA(keypath: SettingsColorRGBA | `ubq://${SettingsColorRGBA}`): RGBA;
     /**
      * Set an enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @param value - The enum value as string.
      */
     setSettingEnum<T extends keyof SettingsEnum>(keypath: T, value: SettingsEnum[T]): void;
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    setSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`, value: SettingsEnum[T]): void;
     /**
      * Get an enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @returns The value as string.
      */
     getSettingEnum<T extends keyof SettingsEnum>(keypath: T): SettingsEnum[T];
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingEnum<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): SettingsEnum[T];
     /**
      * Get the possible enum options for a given enum setting.
      * @param keypath - The settings keypath, e.g. `role`.
      * @returns The possible enum options as strings.
      */
     getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: T): string[];
+    /** @deprecated Support for `ubq://` prefixed keypaths will be removed in a future release. */
+    getSettingEnumOptions<T extends keyof SettingsEnum>(keypath: `ubq://${T}`): string[];
     /**
      * Returns a list of all the settings available.
      * @returns A list of settings keypaths.
@@ -3182,6 +3243,27 @@ export declare class EditorAPI {
     convertColorToColorSpace(color: Color, colorSpace: ColorSpace): never;
 }
 
+/**
+ * The block type IDs for the effect blocks. These are the IDs used to create new effects
+ * using `cesdk.engine.editor.createEffect(id)`.
+ * @public
+ */
+export declare type EffectType = EffectTypeShorthand | EffectTypeLonghand;
+
+/**
+ * The longhand block type IDs for the effect blocks. These are the IDs used to create new effects
+ * using `cesdk.engine.editor.createEffect(id)`.
+ * @public
+ */
+export declare type EffectTypeLonghand = `//ly.img.ubq/effect/${EffectTypeShorthand}`;
+
+/**
+ * The shorthand block type IDs for the effect blocks. These are the IDs used to create new effects
+ * using `cesdk.engine.editor.createEffect(id)`.
+ * @public
+ */
+export declare type EffectTypeShorthand = 'adjustments' | 'cross_cut' | 'dot_pattern' | 'duotone_filter' | 'extrude_blur' | 'glow' | 'half_tone' | 'linocut' | 'liquid' | 'lut_filter' | 'mirror' | 'outliner' | 'pixelize' | 'posterize' | 'radial_pixel' | 'sharpie' | 'shifter' | 'tilt_shift' | 'tv_glitch' | 'vignette';
+
 /**
  * @public
  */
@@ -3266,6 +3348,27 @@ declare interface ExportVideoOptions {
     targetHeight: number;
 }
 
+/**
+ * The block type IDs for the fill blocks. These are the IDs used to create new fills
+ * using `cesdk.engine.editor.createFill(id)`.
+ * @public
+ */
+export declare type FillType = FillTypeShorthand | FillTypeLonghand;
+
+/**
+ * The longhand block type IDs for the fill blocks. These are the IDs used to create new fills
+ * using `cesdk.engine.editor.createFill(id)`.
+ * @public
+ */
+export declare type FillTypeLonghand = `//ly.img.ubq/fill/${FillTypeShorthand}`;
+
+/**
+ * The shorthand block type IDs for the fill blocks. These are the IDs used to create new fills
+ * using `cesdk.engine.editor.createFill(id)`.
+ * @public
+ */
+export declare type FillTypeShorthand = 'color' | 'gradient/linear' | 'gradient/radial' | 'gradient/conical' | 'image' | 'video' | 'pixelStream';
+
 /** @public */
 declare interface FindAssetsQuery {
     perPage: number;
@@ -3410,6 +3513,27 @@ declare enum MimeType_2 {
 }
 export { MimeType_2 as MimeType }
 
+/**
+ * The block type IDs for all blocks types in the Creative Engine. Those are the types that can be
+ * passed to `cesdk.engine.block.findByType(type)` for example.
+ * @public
+ */
+export declare type ObjectType = ObjectTypeShorthand | ObjectTypeLonghand;
+
+/**
+ * The longhand block type IDs for all blocks types in the Creative Engine. Those are the Types returned by the
+ * engine when calling `cesdk.engine.block.getType(blockId)` for example.
+ * @public
+ */
+export declare type ObjectTypeLonghand = DesignBlockTypeLonghand | ShapeTypeLonghand | FillTypeLonghand | EffectTypeLonghand | BlurTypeLonghand;
+
+/**
+ * The shorthand block type IDs for all blocks types in the Creative Engine. Those are the types that can be
+ * passed to `cesdk.engine.block.findByType(type)` for example.
+ * @public
+ */
+export declare type ObjectTypeShorthand = DesignBlockTypeShorthand | `shape/${ShapeTypeShorthand}` | `fill/${FillTypeShorthand}` | `effect/${EffectTypeShorthand}` | `blur/${BlurTypeShorthand}`;
+
 /**
  * A simplified placeholder type for `OffscreenCanvas`, to avoid a dependency on `@types/offscreencanvas`
  * @public
@@ -3818,11 +3942,11 @@ export declare type SceneLayout = 'Free' | 'VerticalStack' | 'HorizontalStack' |
 export declare type SceneMode = 'Design' | 'Video';
 
 /** @public */
-export declare type SettingsBool = 'doubleClickToCropEnabled' | 'features/effectsEnabled' | 'features/hspSelectiveAdjustmentsEnabled' | 'features/layerListEnabled' | 'features/singlePageModeEnabled' | 'features/templatingEnabled' | 'page/dimOutOfPageAreas' | 'page/title/show' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning' | ArbitraryString;
+export declare type SettingsBool = 'doubleClickToCropEnabled' | 'features/singlePageModeEnabled' | 'mouse/enableZoom' | 'mouse/enableScroll' | 'page/dimOutOfPageAreas' | 'page/title/show' | 'placeholderControls/showButton' | 'placeholderControls/showOverlay' | 'showBuildVersion' | 'touch/dragStartCanSelect' | 'touch/singlePointPanning';
 
 /** @public
  */
-declare type SettingsColor = 'clearColor' | 'errorStateColor' | 'highlightColor' | 'page/title/color' | 'placeholderHighlightColor' | 'progressColor' | ArbitraryString;
+declare type SettingsColor = 'clearColor' | 'errorStateColor' | 'highlightColor' | 'page/title/color' | 'placeholderHighlightColor' | 'progressColor';
 
 /** @public
  * @deprecated Use SettingsColor instead.
@@ -3835,18 +3959,38 @@ export declare type SettingsEnum = {
     doubleClickSelectionMode: 'Direct' | 'Hierarchical';
     'touch/pinchAction': 'None' | 'Zoom' | 'Scale';
     'touch/rotateAction': 'None' | 'Rotate';
-    [key: ArbitraryString]: string;
 };
 
 /** @public */
-export declare type SettingsFloat = 'positionSnappingThreshold' | ArbitraryString;
+export declare type SettingsFloat = 'positionSnappingThreshold';
 
 /** @public */
-export declare type SettingsString = 'basePath' | 'license' | 'page/title/fontFileUri' | ArbitraryString;
+export declare type SettingsString = 'basePath' | 'license' | 'page/title/fontFileUri' | 'defaultEmojiFontFileUri';
 
 /** @public */
 export declare type SettingType = 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum';
 
+/**
+ * The block type IDs for the shape blocks. These are the IDs used to create new shapes
+ * using `cesdk.engine.editor.createShape(id)`.
+ * @public
+ */
+export declare type ShapeType = ShapeTypeShorthand | ShapeTypeLonghand;
+
+/**
+ * The longhand block type IDs for the blocks. These are the IDs used to create new shapes
+ * using `cesdk.engine.editor.createShape(id)`.
+ * @public
+ */
+export declare type ShapeTypeLonghand = `//ly.img.ubq/shape/${ShapeTypeShorthand}`;
+
+/**
+ * The shorthand block type IDs for the shape blocks. These are the IDs used to create new shapes
+ * using `cesdk.engine.editor.createShape(id)`.
+ * @public
+ */
+export declare type ShapeTypeShorthand = 'rect' | 'line' | 'ellipse' | 'polygon' | 'star' | 'vector_path';
+
 /** @public */
 export declare interface Size2 {
     width: number;