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

package/index.d.ts

@@ -25,34 +25,77 @@ export declare interface Asset {
 }
 
 /**
- * API to query for assets.
- *
- * Could be remote or local.
- *
- * @typeParam QData - The shape of queries made against this API
  * @public
  */
-export declare interface AssetAPI<QData extends AssetQueryData> {
-    /** The unique id of the API */
-    id: string;
-    /** Find all asset for the given type and the provided query data.  */
-    findAssets(type: string, queryData?: QData): 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;
-    /** Credits for the source/api */
-    credits?: {
+export declare class AssetAPI {
+    #private;
+
+    /**
+     * Adds a custom asset source. Its ID has to be unique.
+     * @param source - The asset source.
+     */
+    addSource(source: AssetSource): void;
+    /**
+     * Removes an asset source with the given ID.
+     * @param id - The ID to refer to the asset source.
+     */
+    removeSource(id: string): void;
+    /**
+     * Finds all registered asset sources.
+     * @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 query - All the options to filter the search results by.
+     * @returns The search results.
+     */
+    findAssetsInSource(id: string, type: 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;
+    /**
+     * Queries the asset source's credits info.
+     * @param id - The ID of the asset source.
+     * @returns The asset source's credits info consisting of a name and an optional URL.
+     */
+    getSourceCredits(id: string): {
         name: string;
-        url?: string;
-    };
-    /** General license for all asset from this source */
-    license?: {
+        url: string | undefined;
+    } | undefined;
+    /**
+     * Queries the asset source's license info.
+     * @param id - The ID of the asset source.
+     * @returns The asset source's license info consisting of a name and an optional URL.
+     */
+    getSourceLicense(id: string): {
         name: string;
-        url?: string;
-    };
+        url: string | undefined;
+    } | undefined;
 }
 
 /**
@@ -81,6 +124,8 @@ export declare interface AssetDefinition extends Asset {
 export declare interface AssetQueryData {
     /** A query string used for (fuzzy) searching of labels and tags */
     query?: string;
+    /** The current page queried for paginated views. */
+    page: number;
     /**
      * Tags are searched with the query parameter, but this search is fuzzy.
      * If one needs to get assets with exactly the tag (from a tag cloud or filter)
@@ -102,21 +147,6 @@ export declare interface AssetQueryData {
     perPage: number;
 }
 
-/**
- * The registry of all available assets and sources registered in the engine.
- * @public
- */
-export declare interface AssetRegistry {
-    /** Returns all sources available in the engine */
-    getSources(type?: string): AssetSource[];
-    /** Returns a source with the given id or undefined if not found */
-    getSource(id: string): AssetSource | undefined;
-    /** Adds a source to this registry. */
-    addSource(source: AssetSource): void;
-    /** Removes a source from this registry. */
-    removeSource(id: string): void;
-}
-
 /**
  * Single asset result of a query from the engine.
  * @public
@@ -188,17 +218,52 @@ declare interface AssetResult_2 {
     };
 }
 
+/** @public */
+declare interface AssetResultContext {
+    sourceId: string;
+    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
  */
-export declare interface AssetSource extends AssetAPI<PaginatedAssetQueryData> {
-    /**
-     * Can the source add, update and remove assets dynamically? If `false`
-     * methods like `addAsset` `updateAsset` and `removeAsset` will throw and
-     * error.
-     */
-    canManageAssets?: boolean;
+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;
+    /** Credits for the source/api */
+    credits?: {
+        name: string;
+        url?: string;
+    };
+    /** General license for all asset from this source */
+    license?: {
+        name: string;
+        url?: 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
@@ -211,6 +276,12 @@ export declare interface AssetSource extends AssetAPI<PaginatedAssetQueryData> {
      * @returns the asset or undefined if no asset with the given id could be found
      */
     getAsset(id: string): Promise<AssetResult | undefined>;
+    /**
+     * Can the source add, update and remove assets dynamically? If `false`
+     * methods like `addAsset` `updateAsset` and `removeAsset` will throw an
+     * error.
+     */
+    canManageAssets?: boolean;
     /**
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
@@ -316,9 +387,10 @@ export declare class BlockAPI {
      * Performs an internal update to resolve the final layout for the blocks.
      * @param handle - The design block element to export.
      * @param mimeType - The mime type of the output file.
+     * @param options - The options for exporting the block type
      * @returns A promise that resolves with the exported image or is rejected with an error.
      */
-    export(handle: DesignBlockId, mimeType?: MimeType_2): Promise<Blob>;
+    export(handle: DesignBlockId, mimeType?: MimeType_2, options?: ExportOptions): Promise<Blob>;
 
     /**
      * Loads existing blocks from the given string.
@@ -1134,6 +1206,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.
@@ -1153,6 +1318,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.
@@ -1265,6 +1436,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;
 }
 
 /**
@@ -1392,7 +1593,7 @@ declare class CreativeEngine {
     scene: SceneAPI;
     variable: VariableAPI;
     editor: EditorAPI;
-
+    asset: AssetAPI;
     event: EventAPI;
 
     /**
@@ -1485,16 +1686,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.
      */
@@ -1598,6 +1789,23 @@ export declare class EditorAPI {
      * @returns The value as string.
      */
     getSettingEnum(keypath: string): string;
+    /**
+     * Sets a custom URI resolver.
+     * This function can be called more than once. Subsequent calls will overwrite previous calls.
+     * To remove a previously set resolver, pass the value `null`.
+     * The given function must return an absolute path with a scheme.
+     * @param resolver - Custom resolution function.
+     */
+    setURIResolver(resolver: (URI: string) => string): void;
+    /**
+     * Resolves the given path.
+     * If a custom resolver has been set with `setURIResolver`, it invokes it with the given path.
+     * Else, it resolves it as relative to the `ubq://basePath` setting.
+     * This performs NO validation of whether a file exists at the specified location.
+     * @param relativePath - A relative path string
+     * @returns The resolved absolute uri or an error if an invalid path was given.
+     */
+    getAbsoluteURI(relativePath: string): string;
 }
 
 /**
@@ -1615,8 +1823,44 @@ export declare class EventAPI {
     subscribe(blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void): () => void;
 }
 
+/**
+ * @public
+ */
+export declare type ExportOptions = {
+    /**
+     * The PNG compression level to use, when exporting to PNG.
+     *
+     * Valid values are 0 to 9, higher means smaller, but slower.
+     * Quality is not affected.
+     * Ignored for other encodings.
+     * @defaultValue 5.
+     */
+    pngCompressionLevel?: number;
+    /**
+     * The JPEG quality to use when encoding to JPEG.
+     *
+     * Valid values are (0-1], higher means better quality.
+     * Ignored for other encodings.
+     *
+     * @defaultValue 0.9
+     */
+    jpegQuality?: number;
+    /**
+     * An optional target width used in conjunction with target height.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetWidth?: number;
+    /**
+     * An optional target height used in conjunction with target width.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetHeight?: number;
+};
+
 /** @public */
-declare interface ExportOptions {
+declare interface ExportOptions_2 {
     jpegQuality: number;
     pngCompressionLevel: number;
     useTargetSize: boolean;
@@ -1645,6 +1889,50 @@ 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;
+}
+
+declare interface FindAssetsQuery {
+    perPage: number;
+    page: number;
+    query: string;
+    tags: string[];
+    groups: string[];
+    excludeGroups: string[];
+    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;
@@ -1763,12 +2051,6 @@ declare type PageFormatDefinition = Preset & {
     bleedMargin?: number;
 };
 
-/** @public */
-export declare interface PaginatedAssetQueryData extends AssetQueryData {
-    /** The current page queried for paginated views. */
-    page: number;
-}
-
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -1951,6 +2233,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 focussed 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
@@ -2014,6 +2321,13 @@ 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
  */