@cesdk/cesdk-js 1.7.0-alpha.3 → 1.7.0-alpha.4

package/index.d.ts

@@ -11,11 +11,118 @@ declare type A11y = {
 
 /** @public */
 export declare class API {
+    asset: AssetAPI;
     block: BlockAPI;
-    scene: SceneAPI;
+    editor: EditorAPI;
     event: EventAPI;
+    scene: SceneAPI;
     variable: VariableAPI;
-    editor: EditorAPI;
+}
+
+/**
+ * Generic asset information
+ * @public
+ */
+declare interface Asset {
+    /**
+     *  Is a combination of source id, extension pack id (optional), type and asset id
+     *  e.g. "extension://ly.img.cesdk.images.samples/ly.img.image/sample.1"
+     */
+    id: string;
+    /**   E.g. `ly.img.image` */
+    /**  Groups of the asset.  */
+    groups?: Groups;
+    /** URI to a thumbnail of the asset used e.g. in the content library UI */
+    thumbUri: string;
+
+    /** Asset-specific and custom meta information */
+    meta?: {
+        uri?: string;
+        filename?: string;
+        vectorPath?: string;
+    } & Record<string, unknown>;
+}
+
+/**
+ * @public
+ */
+export declare class AssetAPI {
+    #private;
+
+    /**
+     * Adds a custom asset source. Its ID has to be unique.
+     * @param source - The asset source.
+     */
+    addSource(source: AssetSource_2): 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 assets of a given type in a specific asset source.
+     * @param sourceId - The ID of the asset source.
+     * @param query - All the options to filter the search results by.
+     * @returns The search results.
+     */
+    findAssets(sourceId: string, query: AssetQueryData): Promise<AssetsQueryResult_2>;
+    /**
+     * Queries the asset source's groups for a certain asset type.
+     * @param id - The ID of the asset source.
+     * @returns The asset groups.
+     */
+    getGroups(id: string): Promise<string[]>;
+    /**
+     * Queries the asset source's credits info.
+     * @param sourceId - The ID of the asset source.
+     * @returns The asset source's credits info consisting of a name and an optional URL.
+     */
+    getCredits(sourceId: string): {
+        name: string;
+        url: string | undefined;
+    } | undefined;
+    /**
+     * Queries the asset source's license info.
+     * @param sourceId - The ID of the asset source.
+     * @returns The asset source's license info consisting of a name and an optional URL.
+     */
+    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_2): Promise<void>;
+}
+
+/**
+ * Definition of an assets used if an asset is added to an asset source.
+ * @public
+ */
+declare interface AssetDefinition extends Asset {
+    /**
+     * Label used to display in aria-label and as a tooltip.
+     * Will be also searched in a query and should be localized
+     */
+    label?: Record<Locale, string>;
+    /**
+     * Tags for this asset. Can be used for filtering, but is also useful for
+     * free-text search. Since the label is searched as well as used for tooltips
+     * you do not want to overdo it, but still add things which are searched.
+     * Thus, it should be localized similar to the `label`.
+     */
+    tags?: Record<Locale, string[]>;
 }
 
 /** @public */
@@ -26,6 +133,94 @@ export declare interface _AssetElement {
     thumbUri: string;
 }
 
+declare type AssetLibraryEntries = AssetLibraryEntry[] | ((currentAssetLibraryEntries: AssetLibraryEntry[]) => AssetLibraryEntry[]);
+
+declare interface AssetLibraryEntry extends AssetLibraryEntryData, AssetLibraryEntryView {
+}
+
+declare interface AssetLibraryEntryData {
+    id: string;
+    sourceIds: string[];
+    excludeGroups?: string[];
+    includeGroups?: string[];
+    title?: (options?: {
+        group?: string;
+    }) => string;
+    managed?: boolean;
+}
+
+declare interface AssetLibraryEntryView {
+    showGroupOverview?: boolean;
+    /**
+     * Determines how many asset results will be show in an overview or
+     * section overview.
+     */
+    previewLength?: number;
+    /**
+     * Determines if the thumbUri is set as a background that will be
+     * contained or covered by the card in an overview or section overview.
+     */
+    previewBackgroundType?: 'cover' | 'contain';
+    /**
+     * Determines if the thumbUri is set as a background that will be
+     * contained or covered by the card in the grid view
+     */
+    gridBackgroundType?: 'cover' | 'contain';
+    /**
+     * Number of columns in the grid view
+     */
+    gridColumns?: number;
+    /**
+     * Determines the height of an item in the grid view.
+     *
+     * - `auto` automatically determine height yielding a masonry-like grid view
+     * - `square` every card will have the same square size
+     */
+    gridItemHeight?: 'auto' | 'square';
+    /**
+     * Overwrite the label of a card for a specific asset result
+     */
+    cardLabel?: (assetResult: AssetResult_2) => string | undefined;
+    /**
+     * Add custom styles to a card for a specific asset result
+     */
+    cardStyle?: (assetResult: AssetResult_2) => Record<string, string | undefined>;
+    /**
+     * Add custom styles to a label for a specific asset result
+     */
+    cardLabelStyle?: (assetResult: AssetResult_2) => Record<string, string | undefined>;
+}
+
+/**
+ * Defines a request for querying assets
+ * @public
+ */
+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)
+     * this query parameter should be used.
+     */
+    tags?: string | string[];
+    /** Query only these groups */
+    groups?: Groups;
+    /** Filter out assets with this groups */
+    excludeGroups?: Groups;
+    /** Choose the locale of the labels and tags for localized search and filtering */
+    locale?: Locale;
+    /**
+     * The number of results queried. How many assets shall be returned regardless
+     * of the total number of assets available.
+     *
+     * Together with `page` this can be used for pagination.
+     */
+    perPage: number;
+}
+
 /**
  * Single asset result of a query from the engine.
  * @public
@@ -33,8 +228,6 @@ export declare interface _AssetElement {
 declare interface AssetResult {
     /** 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. */
@@ -68,36 +261,53 @@ declare interface AssetResult {
     };
 }
 
+/**
+ * Single asset result of a query from the engine.
+ * @public
+ */
+declare interface AssetResult_2 extends Asset {
+    /** The locale of the label and tags */
+    locale?: Locale;
+    /** The label of the result. Used for description and tooltips. */
+    label?: string;
+    /** The tags of this asset. Used for filtering and free-text searching. */
+    tags?: string[];
+
+    /** Credits for the artist of the asset */
+    credits?: {
+        name: string;
+        url?: string;
+    };
+    /** License for this asset. Overwrites the source license if present */
+    license?: {
+        name: string;
+        url?: string;
+    };
+    /** UTM parameters for the links inside the credits */
+    utm?: {
+        source?: string;
+        medium?: string;
+    };
+}
+
 /** @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;
-}
-
 /**
  * API to query for assets
  * @public
  */
 declare interface AssetSource {
-    /** 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 | undefined>;
+    findAssets(queryData?: QueryData): Promise<AssetsQueryResult | undefined>;
+    /**
+     * Apply the given asset result to the active scene.
+     * You can override this with custom behavior.
+     */
+    applyAsset?: (asset: AssetResult) => 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
@@ -118,6 +328,72 @@ declare interface AssetSource {
     };
 }
 
+/**
+ * A source of assets
+ * @public
+ */
+declare interface AssetSource_2 {
+    /** The unique id of the API */
+    id: string;
+    /** Find all asset for the given type and the provided query data.  */
+    findAssets(queryData: AssetQueryData): Promise<AssetsQueryResult_2>;
+    /** Return every available group */
+    getGroups: () => Promise<string[]>;
+    /** 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
+     * a service after adding the asset to the scene. If this is your own API
+     * with your own service, you do not need to set this and avoid downloading /
+     * re-uploading the assets.
+     */
+    downloadAssets?: (asset: AssetResult_2) => Promise<Blob>;
+    /**
+     * @returns the asset or undefined if no asset with the given id could be found
+     */
+    getAsset(id: string): Promise<AssetResult_2 | undefined>;
+    /**
+     * Can the source add, update and remove assets dynamically? If `false`
+     * methods like `addAsset` `updateAsset` and `removeAsset` will throw an
+     * error.
+     */
+    canManageAssets?: boolean;
+    /**
+     * Apply the given asset result to the active scene.
+     * You can override this with custom behavior.
+     */
+    applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    /**
+     * Adds the given asset to this source. Throws an error if `canManageAssets`
+     * is `false`.
+     *
+     * @returns the id of the added asset
+     */
+    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.
+     *
+     * @returns the id of the added asset
+     */
+    updateAsset(assetId: string, asset: AssetDefinition): Promise<void>;
+    /**
+     * Removes the given asset from this source.
+     *
+     * @returns true if asset was found and removed, and false otherwise
+     */
+    removeAsset(assetId: string): Promise<boolean>;
+}
+
 /** @public */
 declare type AssetSources = {
     [id: string]: AssetSource;
@@ -138,6 +414,21 @@ declare interface AssetsQueryResult {
     total: number;
 }
 
+/**
+ * Return type of a `findAssets` query.
+ * @public
+ */
+declare interface AssetsQueryResult_2 {
+    /** The assets in the requested page */
+    assets: AssetResult_2[];
+    /** The current, requested page */
+    currentPage: number;
+    /** The next page to query if it exists */
+    nextPage?: number;
+    /** How many assets are there in total for the current query regardless of the page */
+    total: number;
+}
+
 /**
  * Bleed margin configuration options for a single design unit type.
  * @public
@@ -1344,7 +1635,7 @@ export { ConfigTypes }
  * optional and what mandatory. This is Configuration, but `ui` is recursively
  * optional, and all other props are non-recursively optional
  */
-export declare type Configuration = Partial<_DeepOptional<_RequiredConfiguration, 'ui'>>;
+export declare type Configuration = Partial<_RequiredConfiguration>;
 
 /**
  * - Crop: Manual crop.
@@ -1450,6 +1741,7 @@ declare class CreativeEditorSDK {
     unstable_getPages(): Promise<number[]>;
     unstable_getActivePage(): Promise<number>;
     unstable_onActivePageChanged(callback: (id: number) => void): () => void;
+    unstable_focusPage(pageId: number): Promise<void>;
     /**
      * Disposes the editor and engine if no longer needed.
      */
@@ -1507,6 +1799,12 @@ export declare enum DesignBlockType {
 /** @public */
 export declare type DesignUnit = 'mm' | 'px' | 'in';
 
+declare interface DockGroup {
+    id: string;
+    showOverview?: boolean;
+    entryIds?: string[];
+}
+
 /**
  * @public
  */
@@ -1576,6 +1874,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`
@@ -1819,23 +2123,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;
@@ -1846,23 +2134,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;
@@ -1905,6 +2176,17 @@ a: number
  */
 export declare type GradientType = 'Linear' | 'Radial' | 'Conical';
 
+/**
+ * An asset can be member of multiple groups. Groups have a semantic meaning
+ * used to build and group UIs exploring the assets, e.g.sections in the
+ * content library, or for things like topics in Unsplash for instance.
+ *
+ * Tags in comparison have are more loosely hold meaning used for extended
+ * searching/filtering.
+ * @public
+ */
+declare type Groups = string[];
+
 /**
  * A hexadecimal color value (RGB or RGBA) that starts with a '#'
  * @example #6686FF or #6686FFFF
@@ -1939,6 +2221,12 @@ export declare interface _ImageElement extends _AssetElement {
     };
 }
 
+/**
+ * e.g. `en`, `de`, etc.
+ * @public
+ */
+declare type Locale = string;
+
 /** @public */
 export declare type Logger = (message: string, level: LogLevel) => void;
 
@@ -2234,7 +2522,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.
@@ -2319,18 +2607,11 @@ declare interface UIOptionsPerDesignUnit {
     in: UIOptionsForSingleDesignUnit;
 }
 
-declare interface UnorderedMap<K, V> {
-    size: () => number;
-    get: (key: K) => V;
-    set: (key: K, value: V) => void;
-    keys: () => Vector<K>;
-}
-
 /** @public */
 export declare interface UserInterface {
-    baseURL: string;
+    baseURL?: string;
     scale?: Scale;
-    elements: UserInterfaceElements_2;
+    elements?: UserInterfaceElements_2;
     stylesheets?: {
         disableShadowDOM?: boolean;
         disableTagInsertion?: boolean;
@@ -2375,6 +2656,11 @@ declare namespace UserInterfaceElements {
         UserInterfaceCustomActionIconName,
         UserInterfaceCustomAction,
         UserInterfaceNavigation,
+        DockGroup,
+        AssetLibraryEntryView,
+        AssetLibraryEntryData,
+        AssetLibraryEntry,
+        AssetLibraryEntries,
         UserInterfaceElements_2 as UserInterfaceElements
     }
 }
@@ -2382,11 +2668,7 @@ export { UserInterfaceElements }
 
 /** @public */
 declare interface UserInterfaceElements_2 {
-    view?: {
-        adopter?: {
-            style?: 'default' | 'advanced';
-        };
-    };
+    view?: 'default' | 'advanced';
     panels?: {
         inspector?: UserInterfaceInspector | boolean;
         settings?: UserInterfaceSettings | boolean;
@@ -2396,26 +2678,41 @@ declare interface UserInterfaceElements_2 {
     dock?: {
         iconSize?: Scale;
         hideLabels?: boolean;
+        /**
+         * If groups are used this group will contain all entries that are
+         * not included in other groups.
+         */
+        defaultGroupId?: string;
+        /**
+         * If set the entries will be grouped by these dock groups
+         */
+        groups?: DockGroup[];
     };
     libraries?: {
-        upload?: UserInterfaceElement | boolean;
-        template?: UserInterfaceElement | boolean;
-        image?: UserInterfaceElement | boolean;
-        text?: UserInterfaceElement | boolean;
-        element?: UserInterfaceElement | boolean;
-        panel: {
-            insert: {
+        insert?: {
+            entries: AssetLibraryEntries;
+        };
+        replace?: {
+            entries: AssetLibraryEntries;
+        };
+        /**
+         * TODO Group this under `insert` and `replace`
+         * We should probably group these together with the insert/replace key
+         * together with the entries, e.g. `libraries.insert.panel.autoClose` etc
+         */
+        panel?: {
+            insert?: {
                 autoClose?: boolean | (() => boolean);
                 floating?: boolean;
             };
-            replace: {
+            replace?: {
                 autoClose?: boolean | (() => boolean);
                 floating?: boolean;
             };
         };
     };
     blocks?: UserInterfaceInspectorBlocks;
-    navigation: UserInterfaceNavigation;
+    navigation?: UserInterfaceNavigation;
 }
 
 /** @public */
@@ -2445,8 +2742,8 @@ declare interface UserInterfaceInspectorBlockImage extends UserInterfaceInspecto
 declare interface UserInterfaceInspectorBlocks {
     opacity?: UserInterfaceElement | boolean;
     transform?: UserInterfaceElement | boolean;
-    '//ly.img.ubq/image': UserInterfaceInspectorBlockImage;
-    '//ly.img.ubq/text': UserInterfaceInspectorBlockText;
+    '//ly.img.ubq/image'?: UserInterfaceInspectorBlockImage;
+    '//ly.img.ubq/text'?: UserInterfaceInspectorBlockText;
 }
 
 /** @public */
@@ -2458,17 +2755,17 @@ declare interface UserInterfaceInspectorBlockText extends UserInterfaceInspector
 
 /** @public */
 declare interface UserInterfaceNavigation extends UserInterfaceElement {
-    position: NavigationPosition;
+    position?: NavigationPosition;
     title?: string | null;
     action?: {
-        close: UserInterfaceElement | boolean;
-        back: UserInterfaceElement | boolean;
-        save: UserInterfaceElement | boolean;
-        export: UserInterfaceExportAction | boolean;
-        share: UserInterfaceElement | boolean;
-        load: UserInterfaceElement | boolean;
-        download: UserInterfaceElement | boolean;
-        custom: UserInterfaceCustomAction[];
+        close?: UserInterfaceElement | boolean;
+        back?: UserInterfaceElement | boolean;
+        save?: UserInterfaceElement | boolean;
+        export?: UserInterfaceExportAction | boolean;
+        share?: UserInterfaceElement | boolean;
+        load?: UserInterfaceElement | boolean;
+        download?: UserInterfaceElement | boolean;
+        custom?: UserInterfaceCustomAction[];
     };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesdk/cesdk-js",
-  "version": "1.7.0-alpha.3",
+  "version": "1.7.0-alpha.4",
   "main": "./cesdk.umd.js",
   "types": "./index.d.ts",
   "homepage": "https://www.img.ly",