@cesdk/engine 1.7.0-alpha.3 → 1.7.0-rc.0

package/index.d.ts

@@ -11,7 +11,6 @@ export declare interface Asset {
      */
     id: string;
     /**   E.g. `ly.img.image` */
-    type: string;
     /**  Groups of the asset.  */
     groups?: Groups;
     /** URI to a thumbnail of the asset used e.g. in the content library UI */
@@ -21,6 +20,7 @@ export declare interface Asset {
     meta?: {
         uri?: string;
         filename?: string;
+        vectorPath?: string;
     } & Record<string, unknown>;
 }
 
@@ -45,57 +45,46 @@ export declare class AssetAPI {
      * @returns A list with the IDs of all registered asset sources.
      */
     findAllSources(): string[];
-    /**
-     * Finds all asset sources which support the given asset type.
-     * @returns A list of the IDs of the supported asset sources.
-     */
-    findSourcesByType(type: string): string[];
     /**
      * Finds assets of a given type in a specific asset source.
-     * @param id - The ID of the asset source.
-     * @param type - The asset type to look for.
+     * @param sourceId - The ID of the asset source.
      * @param query - All the options to filter the search results by.
      * @returns The search results.
      */
-    findAssetsInSource(id: string, type: string, query: AssetQueryData): Promise<AssetsQueryResult>;
+    findAssets(sourceId: string, query: AssetQueryData): Promise<AssetsQueryResult>;
     /**
      * Queries the asset source's groups for a certain asset type.
      * @param id - The ID of the asset source.
-     * @param type - The asset type to filter by.
      * @returns The asset groups.
      */
-    getGroupsInSource(id: string, type: string): Promise<string[]>;
-    /**
-     * Queries the asset source's supported asset types.
-     * @param id - The ID of the asset source.
-     * @returns A list of the asset source's supported types.
-     */
-    getTypesInSource(id: string): string[];
-    /**
-     * Checks whether the asset source supports the given asset type.
-     * @param id - The ID of the asset source.
-     * @param type - The asset type to check.
-     * @returns A boolean indicating whether the type is supported.
-     */
-    hasTypeInSource(id: string, type: string): boolean;
+    getGroups(id: string): Promise<string[]>;
     /**
      * Queries the asset source's credits info.
-     * @param id - The ID of the asset source.
+     * @param sourceId - The ID of the asset source.
      * @returns The asset source's credits info consisting of a name and an optional URL.
      */
-    getSourceCredits(id: string): {
+    getCredits(sourceId: string): {
         name: string;
         url: string | undefined;
     } | undefined;
     /**
      * Queries the asset source's license info.
-     * @param id - The ID of the asset source.
+     * @param sourceId - The ID of the asset source.
      * @returns The asset source's license info consisting of a name and an optional URL.
      */
-    getSourceLicense(id: string): {
+    getLicense(sourceId: string): {
         name: string;
         url: string | undefined;
     } | undefined;
+    canManageAssets(sourceId: string): boolean;
+    /**
+     * Apply an asset result to the active scene.
+     * The default behavior will instantiate a block and configure it according to the asset's properties.
+     * Note that this can be overridden by providing an `applyAsset` function when adding the asset source.
+     * @param sourceId - The ID of the asset source.
+     * @param assetResult - A single assetResult of a `findAssets` query.
+     */
+    apply(sourceId: string, assetResult: AssetResult): Promise<void>;
 }
 
 /**
@@ -183,8 +172,6 @@ export declare interface AssetResult extends Asset {
 declare interface AssetResult_2 {
     /** A unique id of this asset */
     id: string;
-    /**  E.g. `ly.img.image` */
-    type: string;
     /** URI to a thumbnail of the asset used e.g. in the content library UI */
     thumbUri: string;
     /** Original size of the asset. */
@@ -224,21 +211,6 @@ declare interface AssetResultContext {
     createdByRole: string;
 }
 
-declare interface AssetResultCredits {
-    name: string;
-    url: string;
-}
-
-declare interface AssetResultLicense {
-    name: string;
-    url: string;
-}
-
-declare interface AssetResultUtm {
-    source: string;
-    medium: string;
-}
-
 /**
  * A source of assets
  * @public
@@ -247,13 +219,9 @@ export declare interface AssetSource {
     /** The unique id of the API */
     id: string;
     /** Find all asset for the given type and the provided query data.  */
-    findAssets(type: string, queryData: AssetQueryData): Promise<AssetsQueryResult>;
-    /** For a given type return every available group */
-    getGroups: (type: string) => Promise<string[]>;
-    /** Return all registered/available types */
-    getTypes: () => string[];
-    /** The given type is registered. */
-    hasType: (type: string) => boolean;
+    findAssets(queryData: AssetQueryData): Promise<AssetsQueryResult>;
+    /** Return every available group */
+    getGroups: () => Promise<string[]>;
     /** Credits for the source/api */
     credits?: {
         name: string;
@@ -282,13 +250,18 @@ export declare interface AssetSource {
      * error.
      */
     canManageAssets?: boolean;
+    /**
+     * Apply the given asset result to the active scene.
+     * You can override this with custom behavior.
+     */
+    applyAsset?: (asset: AssetResult) => Promise<void>;
     /**
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
      *
      * @returns the id of the added asset
      */
-    addAsset(type: string, asset: AssetDefinition): Promise<string>;
+    addAsset(asset: AssetDefinition): Promise<string>;
     /**
      * Updates the asset of this source. Throws an error if `canManageAssets`
      * is `false` or no asset with the given id could not be found.
@@ -309,10 +282,15 @@ export declare interface AssetSource {
  * @public
  */
 declare interface AssetSource_2 {
-    /** The asset types returned by this source. Will default to ['ly.img.image'].  */
-    types?: string[];
     /** Find all asset for the given type and the provided query data.  */
-    findAssets(type: string, queryData?: QueryData): Promise<AssetsQueryResult_2 | undefined>;
+    findAssets(queryData?: QueryData): Promise<AssetsQueryResult_2 | undefined>;
+    /**
+     * Apply the given asset result to the active scene.
+     * You can override this with custom behavior.
+     */
+    applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    /** Return every available group */
+    getGroups?: () => Promise<string[]>;
     /**
      * Indicates if the asset shall be downloaded to handle the raw data instead
      * of an URL reference. Do this if you do not want to depend on
@@ -412,6 +390,12 @@ export declare class BlockAPI {
      * @returns The created blocks handle.
      */
     create(type: DesignBlockType): DesignBlockId;
+    /**
+     * Create a new fill, fails if type is unknown.
+     * @param type - The type of the fill object that shall be created.
+     * @returns The created fill's handle.
+     */
+    createFill(type: string): DesignBlockId;
 
     /**
      * Get the type of the given block, fails if the block is invalid.
@@ -616,12 +600,6 @@ export declare class BlockAPI {
      * @returns true, if the block has a content fill mode.
      */
     hasContentFillMode(id: DesignBlockId): boolean;
-    /**
-     * Query if the given block shows placeholder content.
-     * @param id - The block to query.
-     * @returns true, if the block shows placeholder content.
-     */
-    hasPlaceholderContent(id: DesignBlockId): boolean;
     /**
      * Query a block's width.
      * @param id - The block to query.
@@ -918,6 +896,12 @@ export declare class BlockAPI {
      * @param rotation - The rotation in radians.
      */
     setCropRotation(id: DesignBlockId, rotation: number): void;
+    /**
+     * Set the crop scale ratio of the given design block.
+     * @param id - The block whose crop should be set.
+     * @param scaleRatio - The crop scale ratio.
+     */
+    setCropScaleRatio(id: DesignBlockId, scaleRatio: number): void;
     /**
      * Set the crop translation in x direction of the given design block.
      * @param id - The block whose crop should be set.
@@ -954,6 +938,12 @@ export declare class BlockAPI {
      * @returns The crop rotation.
      */
     getCropRotation(id: DesignBlockId): number;
+    /**
+     * Get the crop scale ratio of the given design block.
+     * @param id - The block whose crop scale ratio should be queried.
+     * @returns The crop scale ratio.
+     */
+    getCropScaleRatio(id: DesignBlockId): number;
     /**
      * Get the crop translation on the x axis of the given design block.
      * @param id - The block whose translation should be queried.
@@ -966,6 +956,12 @@ export declare class BlockAPI {
      * @returns The translation on the y axis.
      */
     getCropTranslationY(id: DesignBlockId): number;
+    /**
+     * Adjust the crop position/scale to at least fill the crop frame.
+     * @param id - The block whose crop scale ratio should be queried.
+     * @param minScaleRatio - The minimal crop scale ratio to go down to.
+     */
+    adjustCropToFillFrame(id: DesignBlockId, minScaleRatio: number): number;
     /**
      * Query if the given block has an opacity.
      * @param id - The block to query.
@@ -1037,6 +1033,99 @@ export declare class BlockAPI {
      * @returns True, if fill is enabled.
      */
     isFillColorEnabled(id: DesignBlockId): boolean;
+    /**
+     * Create a new effect block, fails if type is unknown or not a valid effect block type.
+     * @param type - The type id of the effect.
+     * @returns The created effects handle.
+     */
+    createEffect(type: string): DesignBlockId;
+    /**
+     * Queries whether the block supports effects.
+     * @param id - The block to query.
+     * @returns True, if the block can render effects, false otherwise.
+     */
+    hasEffects(id: DesignBlockId): boolean;
+    /**
+     * Get a list of all effects attached to this block
+     * @param id - The block to query.
+     * @returns A list of effects or an error, if the block doesn't support effects.
+     */
+    getEffects(id: DesignBlockId): DesignBlockId[];
+    /**
+     * Inserts an effect at the given index into the list of effects of the given block.
+     * The same effect can appear multiple times in the list and won't be removed if appended again.
+     * @param id - The block to update.
+     * @param effectId - The effect to insert
+     * @param index - The index at which the effect shall be inserted.
+     */
+    insertEffect(id: DesignBlockId, effectId: DesignBlockId, index: number): void;
+    /**
+     * Inserts an effect at the end of the list of effects
+     * The same effect can appear multiple times in the list and won't be removed if appended again.
+     * @param id - The block to append the effect to.
+     * @param effectId - The effect to append.
+     */
+    appendEffect(id: DesignBlockId, effectId: DesignBlockId): void;
+    /**
+     * Removes the effect at the given index.
+     * @param id - The block to remove the effect from.
+     * @param index - The index where the effect is stored.
+     */
+    removeEffect(id: DesignBlockId, index: number): void;
+    /**
+     * Checks whether an 'effect' block may be enabled and disabled.
+     * @param effectId - The 'effect' block to query.
+     * @returns True, if the block supports enabling and disabling, false otherwise.
+     */
+    hasEffectEnabled(effectId: DesignBlockId): boolean;
+    /**
+     * Sets the enabled state of an 'effect' block.
+     * @param effectId - The 'effect' block to update.
+     * @param enabled - The new state.
+     */
+    setEffectEnabled(effectId: DesignBlockId, enabled: boolean): void;
+    /**
+     * Queries whether an 'effect' block is enabled and therefore applies its effect.
+     * @param effectId - The 'effect' block to query.
+     * @returns True, if the effect is enabled. False otherwise.
+     */
+    isEffectEnabled(effectId: DesignBlockId): boolean;
+    /**
+     * Create a new blur, fails if type is unknown or not a valid blur type.
+     * @param type - The type id of the block.
+     * @returns The handle of the newly created blur.
+     */
+    createBlur(type: string): DesignBlockId;
+    /**
+     * Checks whether the block supports blur.
+     * @param id - The block to query.
+     * @returns True, if the block supports blur.
+     */
+    hasBlur(id: DesignBlockId): boolean;
+    /**
+     * Connects `block`'s blur to the given `blur` block.
+     * @param id - The block to update.
+     * @param blurId - A 'blur' block.
+     */
+    setBlur(id: DesignBlockId, blurId: DesignBlockId): void;
+    /**
+     * Get the 'blur' block of the given design block.
+     * @param id - The block to query.
+     * @returns The 'blur' block.
+     */
+    getBlur(id: DesignBlockId): DesignBlockId;
+    /**
+     * Enable or disable the blur of the given design block.
+     * @param id - The block to update.
+     * @param enabled - The new enabled value.
+     */
+    setBlurEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query if blur is enabled for the given block.
+     * @param id - The block to query.
+     * @returns True, if the blur is enabled. False otherwise.
+     */
+    isBlurEnabled(id: DesignBlockId): boolean;
     /**
      * Query if the given block has background color properties.
      * @param id - The block to query.
@@ -1242,51 +1331,51 @@ export declare class BlockAPI {
     /**
      * Set the drop shadow's X offset of the given design block.
      * @param id - The block whose drop shadow's X offset should be set.
-     * @param xOffset - The X offset to be set.
+     * @param offsetX - The X offset to be set.
      */
-    setDropShadowXOffset(id: DesignBlockId, xOffset: number): void;
+    setDropShadowOffsetX(id: DesignBlockId, offsetX: number): void;
     /**
      * Get the drop shadow's X offset of the given design block.
      * @param id - The block whose drop shadow's X offset should be queried.
      * @returns The offset.
      */
-    getDropShadowXOffset(id: DesignBlockId): number;
+    getDropShadowOffsetX(id: DesignBlockId): number;
     /**
      * Set the drop shadow's Y offset of the given design block.
      * @param id - The block whose drop shadow's Y offset should be set.
-     * @param yOffset - The X offset to be set.
+     * @param offsetY - The X offset to be set.
      */
-    setDropShadowYOffset(id: DesignBlockId, yOffset: number): void;
+    setDropShadowOffsetY(id: DesignBlockId, offsetY: number): void;
     /**
      * Get the drop shadow's Y offset of the given design block.
      * @param id - The block whose drop shadow's Y offset should be queried.
      * @returns The offset.
      */
-    getDropShadowYOffset(id: DesignBlockId): number;
+    getDropShadowOffsetY(id: DesignBlockId): number;
     /**
      * Set the drop shadow's blur radius on the X axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be set.
-     * @param xBlurRadius - The blur radius to be set.
+     * @param blurRadiusX - The blur radius to be set.
      */
-    setDropShadowXBlurRadius(id: DesignBlockId, xBlurRadius: number): void;
+    setDropShadowBlurRadiusX(id: DesignBlockId, blurRadiusX: number): void;
     /**
      * Get the drop shadow's blur radius on the X axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be queried.
      * @returns The blur radius.
      */
-    getDropShadowXBlurRadius(id: DesignBlockId): number;
+    getDropShadowBlurRadiusX(id: DesignBlockId): number;
     /**
      * Set the drop shadow's blur radius on the Y axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be set.
-     * @param yBlurRadius - The blur radius to be set.
+     * @param blurRadiusY - The blur radius to be set.
      */
-    setDropShadowYBlurRadius(id: DesignBlockId, yBlurRadius: number): void;
+    setDropShadowBlurRadiusY(id: DesignBlockId, blurRadiusY: number): void;
     /**
      * Get the drop shadow's blur radius on the Y axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be queried.
      * @returns The blur radius.
      */
-    getDropShadowYBlurRadius(id: DesignBlockId): number;
+    getDropShadowBlurRadiusY(id: DesignBlockId): number;
     /**
      * Set the drop shadow's clipping of the given design block. (Only applies to shapes.)
      * @param id - The block whose drop shadow's clip should be set.
@@ -1324,6 +1413,13 @@ export declare class BlockAPI {
      * @returns The block that currently defines the given block's fill.
      */
     getFill(id: DesignBlockId): DesignBlockId;
+    /**
+     * Sets the block containing the fill properties of the given block.
+     * Note that the previous fill block is not destroyed automatically.
+     * @param id - The block whose fill should be changed.
+     * @param fill - The new fill.
+     */
+    setFill(id: DesignBlockId, fill: DesignBlockId): void;
     /**
      * Set the fill type of the given design block.
      * @param id - The block whose fill type should be set.
@@ -1436,10 +1532,28 @@ export declare class BlockAPI {
      * @returns the gradient's radius, an error otherwise.
      */
     getFillGradientRadius(id: DesignBlockId): number;
+    /**
+     * Enable or disable the placeholder function for a block.
+     * @param id - The block whose placeholder function should be enabled or disabled.
+     * @param enabled - Whether the function should be enabled or disabled.
+     */
+    setPlaceholderEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query whether the placeholder function for a block is enabled.
+     * @param id - The block whose placeholder function state should be queried.
+     * @returns the enabled state of the placeholder function.
+     */
+    isPlaceholderEnabled(id: DesignBlockId): boolean;
+    /**
+     * Query if the given block shows placeholder content.
+     * @param id - The block to query.
+     * @returns true, if the block shows placeholder content.
+     */
+    showsPlaceholderContent(id: DesignBlockId): boolean;
     /**
      * Set a metadata value of a block identified by a key.
      * If the key does not exist, yet, it will be added.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @param value - The value to set.
      */
@@ -1447,14 +1561,14 @@ export declare class BlockAPI {
     /**
      * Get a metadata value of a block identified by a key.
      * If the key does not exist, yet, this method will fail.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @returns the value associated with the key.
      */
     getMetadata(id: DesignBlockId, key: string): string;
     /**
      * Check if the block has metadata associated with the key.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @returns whether the key exists.
      */
@@ -1462,10 +1576,31 @@ export declare class BlockAPI {
     /**
      * Remove metadata associated with the key from the given block.
      * If the key does not exist, this method will fail.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      */
     removeMetadata(id: DesignBlockId, key: string): void;
+    /**
+     * Enable or disable a scope for a given block.
+     * @param id - The block whose scope should be enabled or disabled.
+     * @param key - The scope to enable or disable.
+     * @param enabled - Whether the scope should be enabled or disabled.
+     */
+    setScopeEnabled(id: DesignBlockId, key: string, enabled: boolean): void;
+    /**
+     * Query whether a scope is enabled for a given block.
+     * @param id - The block whose scope state should be queried.
+     * @param key - The scope to query.
+     * @returns the enabled state of the scope for the given block.
+     */
+    isScopeEnabled(id: DesignBlockId, key: string): boolean;
+    /**
+     * Check if a scope is allowed for a given block.
+     * @param id - The block to check.
+     * @param key - The scope to check.
+     * @returns whether the scope is allowed for the given block.
+     */
+    isAllowedByScope(id: DesignBlockId, key: string): boolean;
 }
 
 /**
@@ -1482,6 +1617,19 @@ declare interface BlockEvent_2 {
     type: 'Created' | 'Updated' | 'Destroyed';
 }
 
+/**
+ * Dispatched on the engine canvas when the text input has been blurred.
+ * Call `preventDefault()` to disallow this and refocus the engine text input.
+ * @public
+ */
+export declare interface BlurEvent extends CustomEvent<EventTarget | null> {
+    readonly type: 'cesdk-blur';
+    /** Contains the element that has received focus during the blur, or null */
+    readonly detail: EventTarget | null;
+    /** Force focus back to the engine input */
+    preventDefault(): void;
+}
+
 /** @public */
 declare type Callbacks = {
     log?: Logger;
@@ -1589,12 +1737,12 @@ declare type Core = {
  */
 declare class CreativeEngine {
     #private;
+    asset: AssetAPI;
     block: BlockAPI;
-    scene: SceneAPI;
-    variable: VariableAPI;
     editor: EditorAPI;
-    asset: AssetAPI;
     event: EventAPI;
+    scene: SceneAPI;
+    variable: VariableAPI;
 
     /**
      * Dispose the engine.
@@ -1710,6 +1858,12 @@ export declare class EditorAPI {
      * @returns True if a redo step is available.
      */
     canRedo(): boolean;
+    /**
+     * Subscribe to changes to the editor settings.
+     * @param callback - This function is called at the end of the engine update, if the editor settings have changed.
+     * @returns A method to unsubscribe.
+     */
+    onSettingsChanged(callback: () => void): () => void;
     /**
      * Set a boolean setting.
      * @param keypath - The settings keypath, e.g. `ubq://doubleClickToCropEnabled`
@@ -1806,6 +1960,18 @@ export declare class EditorAPI {
      * @returns The resolved absolute uri or an error if an invalid path was given.
      */
     getAbsoluteURI(relativePath: string): string;
+    /**
+     * Set a scope to be globally allowed, denied, or deferred to the block-level.
+     * @param key - The scope to set.
+     * @param value - `Allow` will always allow the scope, `Deny` will always deny the scope, and `Defer` will defer to the block-level.
+     */
+    setGlobalScope(key: string, value: 'Allow' | 'Deny' | 'Defer'): void;
+    /**
+     * Query the state of a global scope.
+     * @param key - The scope to query.
+     * @returns `Allow` if the scope is allowed, `Deny` if it is disallowed, and `Defer` if it is deferred to the block-level.
+     */
+    getGlobalScope(key: string): 'Allow' | 'Deny' | 'Defer';
 }
 
 /**
@@ -1889,23 +2055,7 @@ declare type Extensions = {
  */
 export declare type FillType = 'Solid' | 'Gradient';
 
-declare interface FindAssetResult {
-    id: string;
-    type: string;
-    groups: Vector<string>;
-    thumbUri: string;
-    width: number;
-    height: number;
-    meta: UnorderedMap<string, string>;
-    locale: string;
-    label: string;
-    tags: Vector<string>;
-    context: AssetResultContext;
-    credits: AssetResultCredits;
-    license: AssetResultLicense;
-    utm: AssetResultUtm;
-}
-
+/** @public */
 declare interface FindAssetsQuery {
     perPage: number;
     page: number;
@@ -1916,23 +2066,6 @@ declare interface FindAssetsQuery {
     locale: string;
 }
 
-declare interface FindAssetsQueryCpp {
-    perPage: number;
-    page: number;
-    query: string;
-    tags: Vector<string>;
-    groups: Vector<string>;
-    excludeGroups: Vector<string>;
-    locale: string;
-}
-
-declare interface FindAssetsResult {
-    assets: Vector<FindAssetResult>;
-    currentPage: number;
-    nextPage: number;
-    total: number;
-}
-
 /** @public */
 declare interface Flip {
     horizontal: boolean;
@@ -2109,6 +2242,19 @@ declare interface QueryData {
     page: number;
 }
 
+/**
+ * Dispatched on the engine canvas right before the engine will refocus its text
+ * input after a blur. Call `preventDefault()` to prevent the refocusing.
+ * @public
+ */
+export declare interface RefocusEvent extends CustomEvent<EventTarget | null> {
+    readonly type: 'cesdk-refocus';
+    /** Contains the element that has received focus during the blur, or null */
+    readonly detail: EventTarget | null;
+    /** Prevent refocusing the engine input */
+    preventDefault(): void;
+}
+
 /**
  * @public
  */
@@ -2250,7 +2396,7 @@ export declare class SceneAPI {
      * Only has an effect if the zoom level is not handled by the UI.
      * Without padding, this results in a tight view on the block.
      *
-     * @param id - The block that should be focussed on.
+     * @param id - The block that should be focused on.
      * @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.
@@ -2321,13 +2467,6 @@ declare type TypefaceDefinition = Preset & {
     }[];
 };
 
-declare interface UnorderedMap<K, V> {
-    size: () => number;
-    get: (key: K) => V;
-    set: (key: K, value: V) => void;
-    keys: () => Vector<K>;
-}
-
 /**
  * @public
  */