@cesdk/node 1.11.0-preview.1 → 1.11.0-rc.0

package/example.js

@@ -5,7 +5,8 @@ const CreativeEngine = require('./index.js');
 
 const { DesignBlockType, MimeType } = CreativeEngine;
 
-CreativeEngine.init().then((engine) => {
+CreativeEngine.init().then(async (engine) => {
+  await engine.addDefaultAssetSources();
   console.log('Loading scene');
   engine.scene
     .loadFromURL(`file://${__dirname}/demo.scene`)

package/index.d.ts

@@ -1619,6 +1619,51 @@ export declare class BlockAPI {
      * @returns The drop shadow's clipping.
      */
     getDropShadowClip(id: DesignBlockId): boolean;
+    /**
+     * Create a Cutout block.
+     * @param blocks - The blocks whose shape will serve as the basis for the cutout's path.
+     * @returns The handle of the created Cutout.
+     */
+    createCutoutFromBlocks(ids: DesignBlockId[]): DesignBlockId;
+    /**
+     * Create a Cutout block.
+     * @param path - An SVG string describing a path.
+     * @returns The handle of the created Cutout.
+     */
+    createCutoutFromPath(path: string): DesignBlockId;
+    /**
+     * Set the cutout's offset from the underlying path.
+     * @param block - The block whose offset should be set.
+     * @param offset - The offset to be set.
+     */
+    setCutoutOffset(id: DesignBlockId, offset: number): void;
+    /**
+     * Get the cutout's offset from the underlying path.
+     * @param block - The block whose offset should be queried.
+     * @returns The cutout's offset.
+     */
+    getCutoutOffset(id: DesignBlockId): number;
+    /**
+     * Set the cutout's type.
+     * @param block - The block whose type should be set.
+     * @param type - The type to be set.
+     */
+    setCutoutType(id: DesignBlockId, type: CutoutType): void;
+    /**
+     * Get the cutout's type.
+     * @param block - The block whose type should be queried.
+     * @returns The cutout's type.
+     */
+    getCutoutType(id: DesignBlockId): CutoutType;
+    /** Perform a boolean operation on the given Cutout blocks.
+     * The cutout offset of the new block is 0.
+     * The cutout type of the new block is that of the first block.
+     * When performing a `Difference` operation, the first block is the block subtracted from.
+     * @param blocks - The blocks with which to perform to the operation.
+     * @param op - The boolean operation to perform.
+     * @returns The newly created block or an error.
+     */
+    createCutoutFromOperation(ids: DesignBlockId[], op: CutoutOperation): DesignBlockId;
     /**
      * Inserts the given text into the selected range of the text block.
      * @param block - The text block into which to insert the given text.
@@ -1655,9 +1700,11 @@ export declare class BlockAPI {
      * Returns the ordered unique list of colors of the text in the selected range.
      * @param block - The text block whose colors should be returned.
      * @param from - The start index of the UTF-16 range whose colors should be returned.
-     * If the value is negative, this will fall back to the start of the entire text range.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
      * @param to - The UTF-16 index after the last grapheme whose colors should be returned.
-     * If the value is negative, this will fall back to the end of the entire text range.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
      */
     getTextColors(id: DesignBlockId, from?: number, to?: number): Array<RGBAColor | SpotColor>;
     /**
@@ -1682,6 +1729,29 @@ export declare class BlockAPI {
      *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
      */
     getTextFontStyles(id: DesignBlockId, from?: number, to?: number): FontStyle[];
+    /**
+     * Returns the ordered list of text cases of the text in the selected range.
+     * @param block - The text block whose text cases should be returned.
+     * @param from - The start index of the UTF-16 range whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    getTextCases(id: DesignBlockId, from?: number, to?: number): TextCase[];
+    /**
+     * Sets the given text case for the selected range of text.
+     * @param id - The text block whose text case should be changed.
+     * @param textCase - The new text case value.
+     * @param from - The start index of the UTF-16 range whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose text cases should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    setTextCase(id: DesignBlockId, textCase: TextCase, from?: number, to?: number): void;
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -2179,26 +2249,32 @@ export declare interface CMYKColor {
 }
 
 /**
- * A color definition for the custom color palette.
- * The RGB and CMYK components must all be specified in the range [0-1].
+ * @deprecated This type definition has been removed.
+ * Instead of `ConfigTypes.Color`, this can be imported directly as `PaletteColor`.
  * @public
  */
-declare type Color_2 = HexColorString | RGBColor | RGBAColor | SpotColor;
+declare type Color_2 = PaletteColor;
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type ColorDefinition = Preset & {
     value: Color_2;
 };
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type ColorPaletteDefinition = Preset & {
     entries: Color_2[];
 };
 
 declare namespace ConfigTypes {
     export {
-        HexColorString,
         Color_2 as Color,
+        HexColorString_2 as HexColorString,
         AssetSources,
         AssetSource_2 as AssetSource,
         AssetResult_2 as AssetResult,
@@ -2306,9 +2382,70 @@ declare class CreativeEngine {
      * @returns An engine instance.
      */
     static init(config?: Partial<Configuration> & OldConfiguration): Promise<CreativeEngine>;
+    /**
+     * Convenience function that registers a set of asset sources containing our
+     * default assets. These are
+     *
+     * - `'ly.img.sticker'` - Various stickers
+     * - `'ly.img.vectorpath'` - Shapes and arrows
+     * - `'ly.img.filter.lut'` - LUT effects of various kinds.
+     * - `'ly.img.filter.duotone'` - LUT 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'.
+     * 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'`. */
+        baseURL?: string;
+        /** A list of IDs, that will be ignored during load. */
+        excludeAssetSourceIds?: DefaultAssetSourceId[];
+    }): Promise<void>;
+    /**
+     * Convenience function that registers a set of demo asset sources containing our
+     * example assets. These are not to meant to be used in your production code.
+     *
+     * These are
+     *
+     * - `'ly.img.image'` - Sample images
+     * - `'ly.img.image.upload'` - Demo source to upload image assets
+     * - `'ly.img.audio'` - Sample audios
+     * - `'ly.img.audio.upload'` - Demo source to upload audio assets
+     * - `'ly.img.video'` - Sample videos
+     * - `'ly.img.video.upload'` - Demo source to upload video assets
+     */
+    addDemoAssetSources({ excludeAssetSourceIds, sceneMode, withUploadAssetSources }?: {
+        /** A list of IDs, that will be ignored during load */
+        excludeAssetSourceIds?: DemoAssetSourceId[];
+        /** If 'Video' video specific demo asset sources will be loaded as well (default 'Design') */
+        sceneMode?: SceneMode;
+        /** If 'true' asset sources for uploads are added (default false) */
+        withUploadAssetSources?: boolean;
+    }): Promise<void>;
 }
 export default CreativeEngine;
 
+/**
+ * @public
+ */
+export declare type CutoutOperation = 'Difference' | 'Intersection' | 'Union' | 'XOR';
+
+/**
+ * @public
+ */
+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';
+
+/**
+ * @public
+ */
+export declare type DemoAssetSourceId = 'ly.img.image.upload' | 'ly.img.video.upload' | 'ly.img.audio.upload' | 'ly.img.image' | 'ly.img.video' | 'ly.img.audio';
+
 /**
  * A numerical identifier for a design block
  * @public
@@ -2326,6 +2463,7 @@ export declare enum DesignBlockType {
     Image = "//ly.img.ubq/image",
     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",
@@ -2335,7 +2473,8 @@ export declare enum DesignBlockType {
     StarShape = "//ly.img.ubq/shapes/star",
     PolygonShape = "//ly.img.ubq/shapes/polygon",
     EllipseShape = "//ly.img.ubq/shapes/ellipse",
-    Group = "//ly.img.ubq/group"
+    Group = "//ly.img.ubq/group",
+    Cutout = "//ly.img.ubq/cutout"
 }
 
 /**
@@ -2601,6 +2740,19 @@ export declare class EditorAPI {
      * @returns An empty result on success, an error otherwise.
      */
     removeSpotColor(name: string): void;
+    /**
+     * Set the spot color assign to a cutout type.
+     * All cutout blocks of the given type will be immediately assigned that spot color.
+     * @param type - The cutout type.
+     * @param name - The spot color name to assign.
+     */
+    setSpotColorForCutoutType(type: CutoutType, color: string): void;
+    /**
+     * Get the name of the spot color assigned to a cutout type.
+     * @param type - The cutout type.
+     * @returns The color spot name.
+     */
+    getSpotColorForCutoutType(type: CutoutType): string;
 }
 
 /**
@@ -2751,7 +2903,14 @@ declare type Groups = string[];
  * @example #6686FF or #6686FFFF
  * @public
  */
-declare type HexColorString = string;
+export declare type HexColorString = string;
+
+/**
+ * @deprecated This type definition has been moved
+ * It can instead be imported directly as `HexColorString`
+ * @public
+ */
+declare type HexColorString_2 = HexColorString;
 
 /**
  * A numerical identifier for a history stack
@@ -2790,6 +2949,7 @@ declare enum MimeType_2 {
     Jpeg = "image/jpeg",
     Tga = "image/x-tga",
     Mp4 = "video/mp4",
+    QuickTime = "video/quicktime",
     Binary = "application/octet-stream",
     Pdf = "application/pdf",
     Zip = "application/zip"
@@ -2861,14 +3021,28 @@ export declare interface PageDuration {
     end: number;
 }
 
-/** @public */
+/**
+ * @deprecated This type definition is unused and will be removed
+ * @public
+ */
 declare type PageFormatDefinition = Preset & {
     width: number;
     height: number;
-    unit: 'px' | 'mm' | 'in';
+    /** @deprecated This property is unused and will be removed  */
+    dpi?: number;
+    /** @deprecated This property is unused and will be removed  */
+    bleedMargin?: number;
+    unit: 'px' | 'mm' | 'in' | DesignUnit;
     fixedOrientation?: boolean;
 };
 
+/**
+ * A color definition for the custom color palette.
+ * The RGB and CMYK components must all be specified in the range [0-1].
+ * @public
+ */
+export declare type PaletteColor = HexColorString | RGBColor | RGBAColor | SpotColor;
+
 /**
  * - Absolute: Position in absolute design units.
  * - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%.
@@ -2878,7 +3052,10 @@ declare type PageFormatDefinition = Preset & {
  */
 export declare type PositionMode = 'Absolute' | 'Percent' | 'Auto';
 
-/** @public */
+/**
+ * @deprecated This type definition is not used anymore and will be removed.
+ * @public
+ */
 declare type Preset = {
     meta?: {
         default?: boolean;
@@ -2887,20 +3064,28 @@ declare type Preset = {
     };
 };
 
-/** @public */
+/**
+ * @deprecated This type definition will be removed.
+ * If you need to reference this type in your code,
+ * use `Configuration['presets']` instead of `ConfigTypes.Presets`.
+ * @public
+ */
 declare type Presets = {
+    /**
+     * @deprecated The configuration option `presets.colors` does not exist anymore.
+     */
     colors?: {
-        [id: string]: ColorDefinition;
+        [id: string]: Color_2;
     };
     typefaces?: {
         [id: string]: TypefaceDefinition;
     };
-    pageFormats?: {
-        [id: string]: PageFormatDefinition;
-    };
     colorPalettes?: {
         [id: string]: ColorPaletteDefinition;
     };
+    pageFormats?: {
+        [id: string]: PageFormatDefinition;
+    };
     templates?: {
         [id: string]: TemplateDefinition;
     };
@@ -3232,14 +3417,23 @@ export declare type StrokeStyle = 'Dashed' | 'DashedRound' | 'Dotted' | 'LongDas
 declare type Subscription = number;
 
 /** @public */
-declare type TemplateDefinition = Preset & {
+declare type TemplateDefinition = {
+    /** @deprecated The meta field is not used anymore */
+    meta?: Preset['meta'];
     label: string;
     scene: string | URL | (() => Promise<string>);
     thumbnailURL?: string | URL;
 };
 
+/**
+ * @public
+ */
+export declare type TextCase = 'Normal' | 'Uppercase' | 'Lowercase' | 'Titlecase';
+
 /** @public */
-declare type TypefaceDefinition = Preset & {
+declare type TypefaceDefinition = {
+    /** @deprecated The meta field is not used anymore */
+    meta?: Preset['meta'];
     family: string;
     fonts: {
         fontURL: string;