@cesdk/engine 1.7.0-alpha.2 → 1.7.0-alpha.5

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,13 @@ 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>;
     /**
      * 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
@@ -1206,6 +1182,99 @@ export declare class BlockAPI {
      * @deprecated Use `getStrokeWidth`.
      */
     getOutlineWidth(id: DesignBlockId): number;
+    /**
+     * Query if the given block has a drop shadow property.
+     * @param id - The block to query.
+     * @returns True if the block has a drop shadow property.
+     */
+    hasDropShadow(id: DesignBlockId): boolean;
+    /**
+     * Enable or disable the drop shadow of the given design block.
+     * @param id - The block whose drop shadow should be enabled or disabled.
+     * @param enabled - If true, the drop shadow will be enabled.
+     */
+    setDropShadowEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query if the drop shadow of the given design block is enabled.
+     * @param id - The block whose drop shadow state should be queried.
+     * @returns True if the block's drop shadow is enabled.
+     */
+    isDropShadowEnabled(id: DesignBlockId): boolean;
+    /**
+     * Set the drop shadow color of the given design block.
+     * @param id - The block whose drop shadow color should be set.
+     * @param r - The red color component in the range of 0 to 1.
+     * @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.
+     */
+    setDropShadowColorRGBA(id: DesignBlockId, r: number, g: number, b: number, a?: number): void;
+    /**
+     * Get the  drop shadow color of the given design block.
+     * @param id - The block whose background color should be queried.
+     * @returns The background color.
+     */
+    getDropShadowColorRGBA(id: DesignBlockId): RGBA;
+    /**
+     * 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.
+     */
+    setDropShadowXOffset(id: DesignBlockId, xOffset: 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;
+    /**
+     * 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.
+     */
+    setDropShadowYOffset(id: DesignBlockId, yOffset: 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;
+    /**
+     * 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.
+     */
+    setDropShadowXBlurRadius(id: DesignBlockId, xBlurRadius: 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;
+    /**
+     * 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.
+     */
+    setDropShadowYBlurRadius(id: DesignBlockId, yBlurRadius: 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;
+    /**
+     * 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.
+     * @param clip - The drop shadow's clip to be set.
+     */
+    setDropShadowClip(id: DesignBlockId, clip: boolean): void;
+    /**
+     * Get the drop shadow's clipping of the given design block.
+     * @param id - The block whose drop shadow's clipping should be queried.
+     * @returns The drop shadow's clipping.
+     */
+    getDropShadowClip(id: DesignBlockId): boolean;
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -1225,6 +1294,12 @@ export declare class BlockAPI {
      * @returns An empty result on success, an error otherwise.
      */
     setFillEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Returns the block containing the fill properties of the given block.
+     * @param id - The block whose fill block should be returned.
+     * @returns The block that currently defines the given block's fill.
+     */
+    getFill(id: DesignBlockId): DesignBlockId;
     /**
      * Set the fill type of the given design block.
      * @param id - The block whose fill type should be set.
@@ -1337,6 +1412,36 @@ export declare class BlockAPI {
      * @returns the gradient's radius, an error otherwise.
      */
     getFillGradientRadius(id: DesignBlockId): number;
+    /**
+     * 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 key - The key used to identify the desired piece of metadata.
+     * @param value - The value to set.
+     */
+    setMetadata(id: DesignBlockId, key: string, value: string): void;
+    /**
+     * 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 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 key - The key used to identify the desired piece of metadata.
+     * @returns whether the key exists.
+     */
+    hasMetadata(id: DesignBlockId, key: string): boolean;
+    /**
+     * 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 key - The key used to identify the desired piece of metadata.
+     */
+    removeMetadata(id: DesignBlockId, key: string): void;
 }
 
 /**
@@ -1353,6 +1458,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;
@@ -1460,12 +1578,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.
@@ -1557,16 +1675,6 @@ export declare class EditorAPI {
      * @returns The text cursor's y position in screen space.
      */
     getTextCursorPositionInScreenSpaceY(): number;
-    /**
-     * Sets the zoom level of the scene.
-     * @param zoomLevel - The new zoom level.
-     */
-    setZoomLevel(zoomLevel?: number): void;
-    /**
-     * Query a camera zoom level.
-     * @returns The zoom level of the block's (main) camera.
-     */
-    getZoomLevel(): number;
     /**
      * Adds a new history state to the stack, if undoable changes were made.
      */
@@ -1591,6 +1699,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`
@@ -1770,23 +1884,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;
@@ -1797,23 +1895,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;
@@ -1990,6 +2071,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
  */
@@ -2114,6 +2208,31 @@ export declare class SceneAPI {
      * @returns A Promise that resolves once the template was applied or rejects if there was an error.
      */
     applyTemplateFromURL(url: string): Promise<void>;
+    /**
+     * Sets the zoom level of the active scene.
+     * Only has an effect if the zoom level is not handled by the UI.
+     *
+     * @param zoomLevel - The new zoom level.
+     */
+    setZoomLevel(zoomLevel?: number): void;
+    /**
+     * Query a camera zoom level of the active scene.
+     * @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.
+     * Without padding, this results in a tight view on the block.
+     *
+     * @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.
+     * @param paddingBottom - Optional padding in screen pixels to the bottom of the block.
+     * @returns A promise that resolves once the zoom was set or rejects with an error otherwise.
+     */
+    zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>;
     /**
      * Converts all values of the current scene into the given design unit.
      * @param designUnit - The new design unit of the scene
@@ -2177,13 +2296,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
  */