@cesdk/cesdk-js 1.77.0-rc.3 → 1.77.0

package/index.d.ts

@@ -362,7 +362,7 @@ export { AssetDefinition }
  * Asset library entry IDs that can be used with asset library APIs.
  * Includes built-in entry IDs registered by the SDK, and allows custom entry IDs.
  */
-export declare type AssetEntryId = 'ly.img.templates' | 'ly.img.upload' | 'ly.img.image' | 'ly.img.video' | 'ly.img.audio' | 'ly.img.text' | 'ly.img.vector.shape' | 'ly.img.sticker' | 'ly.img.colors' | 'ly.img.typefaces' | 'ly.img.pagePresets' | 'ly.img.cropPresets' | 'ly.img.library.captionPresets' | 'ly.img.text.presets' | 'ly.img.animations' | 'ly.img.textAnimations' | (string & {});
+export declare type AssetEntryId = 'ly.img.templates' | 'ly.img.upload' | 'ly.img.image' | 'ly.img.video' | 'ly.img.audio' | 'ly.img.text' | 'ly.img.vector.shape' | 'ly.img.sticker' | 'ly.img.colors' | 'ly.img.typefaces' | 'ly.img.pagePresets' | 'ly.img.cropPresets' | 'ly.img.library.captionPresets' | 'ly.img.animations' | 'ly.img.textAnimations' | (string & {});
 
 /**
  * @public
@@ -507,6 +507,19 @@ declare interface AssetLibraryEntryData {
     canRemove?: boolean | ((sourceId: string) => boolean);
 }
 
+/**
+ * @public
+ * A reference to an asset library entry to display. Either an entry ID, or an object that names the
+ * entry plus source IDs to hide for this display only — for example a replace panel that shows a
+ * library with a non-applicable source hidden (the text "Styles" panel shows `ly.img.text` but
+ * hides its text-combinations source). This per-display `excludeSourceIds` is distinct from the
+ * entry's own `includeGroups`/`excludeGroups`, which apply wherever the entry is shown.
+ */
+export declare type AssetLibraryEntryInput = AssetEntryId | {
+    entry: AssetEntryId;
+    excludeSourceIds?: string[];
+};
+
 /**
  * @public
  * Interface representing the view configuration for an asset library entry.
@@ -1623,12 +1636,11 @@ export declare interface BuiltinTranslations {
     'libraries.ly.img.crop.presets.label': string;
     'libraries.ly.img.image.label': string;
     'libraries.ly.img.image.upload.label': string;
-    'libraries.ly.img.text.presets.label': string;
-    'libraries.ly.img.text.presets.textStyles.label': string;
-    'libraries.ly.img.text.presets.paragraphDefault.label': string;
-    'libraries.ly.img.text.presets.paragraphElegant.label': string;
-    'libraries.ly.img.text.presets.paragraphModernTech.label': string;
-    'libraries.ly.img.text.presets.curves.label': string;
+    'libraries.ly.img.text.default.label': string;
+    'libraries.ly.img.text.elegant.label': string;
+    'libraries.ly.img.text.modernTech.label': string;
+    'libraries.ly.img.text.styles.label': string;
+    'libraries.ly.img.text.curves.label': string;
     'libraries.ly.img.local.label': string;
     'libraries.ly.img.page.presets.facebook.label': string;
     'libraries.ly.img.page.presets.hd-video.label': string;
@@ -1668,10 +1680,8 @@ export declare interface BuiltinTranslations {
     'libraries.ly.img.templates.premium.professional.label': string;
     'libraries.ly.img.templates.premium.socials.label': string;
     'libraries.ly.img.text.components.label': string;
-    'libraries.ly.img.text.headline.label': string;
     'libraries.ly.img.text.label': string;
-    'libraries.ly.img.text.paragraph.label': string;
-    'libraries.ly.img.text.title.label': string;
+    'libraries.ly.img.text.plain.label': string;
     'libraries.ly.img.textAnimations.ly.img.animations.in.label': string;
     'libraries.ly.img.textAnimations.ly.img.animations.label': string;
     'libraries.ly.img.textAnimations.ly.img.animations.loop.label': string;
@@ -3850,6 +3860,20 @@ export { EngineErrorArg }
 
 export { EngineErrorCode }
 
+/**
+ * Customer-facing copy resolved from a thrown engine error.
+ *
+ * `message` is the short headline (only set for a structured {@link EngineError});
+ * `description` is the longer body. Either may be absent — callers fall back to
+ * their own contextual copy for whichever half is missing.
+ */
+export declare interface EngineErrorMessage {
+    /** Short headline. Set only for a {@link EngineError} with a catalog code. */
+    message?: string;
+    /** Longer body: the engine `hint` for catalog errors, else the raw message. */
+    description?: string;
+}
+
 export { EngineExportOptions }
 
 export { EnginePlugin }
@@ -4952,6 +4976,7 @@ export declare class InternationalizationAPI {
      *
      * @category Localization
      * @param key - A translation key string or an array of translation keys to try in order.
+     * @param options - Optional interpolation values for `{{placeholder}}` tokens in the resolved string.
      * @returns The translated string for the key in the current locale, or the key itself if no translation is found.
      *
      * @example
@@ -4964,9 +4989,42 @@ export declare class InternationalizationAPI {
      * const translation = cesdk.i18n.translate(['specific.save', 'common.save']);
      * // Tries 'specific.save' first, then 'common.save'
      * // Returns the first found translation or "common.save" if neither exists
+     *
+     * // With interpolation values
+     * const translation = cesdk.i18n.translate('error.fileTooLarge', { maxSize: '10MB' });
      * ```
      */
-    translate(key: string | string[]): string;
+    translate(key: string | string[], options?: Record<string, unknown>): string;
+    /**
+     * Resolves a thrown engine error into the customer-facing copy the editor's
+     * built-in error dialogs display.
+     *
+     * Use this in your own error handling—a custom `onError`, a toast, or a
+     * headless flow—to show the same localized text without reimplementing the
+     * lookup. For a {@link @cesdk/engine#EngineError} with a catalog
+     * `code` it returns your authored `error.<code>` / `error.<code>.description`
+     * override (registered via {@link setTranslations}), falling back to the
+     * engine's English message and hint when no copy is authored—so the result is
+     * never blank or a raw code. Plain `Error`s return only a `description` (their
+     * message); branch on the structured `code` rather than the message string for
+     * stable handling.
+     *
+     * @category Localization
+     * @param error - The thrown error, typically caught from an engine operation.
+     * @returns The resolved `{ message, description }` copy, or `undefined` when
+     *   there is nothing to show.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await cesdk.engine.scene.loadFromURL(sceneUrl);
+     * } catch (error) {
+     *   const copy = cesdk.i18n.localizedEngineErrorMessage(error);
+     *   showToast(copy?.message ?? copy?.description ?? 'Something went wrong.');
+     * }
+     * ```
+     */
+    localizedEngineErrorMessage(error: unknown): EngineErrorMessage | undefined;
 }
 
 /**
@@ -5077,9 +5135,9 @@ export declare type KeyboardShortcutContext = {
  * `cesdk.shortcuts` — the editor-facing keyboard shortcut API.
  *
  * A thin wrapper over the engine's `engine.shortcuts` registry that translates
- * the editor-facing KeyboardShortcut (whose `when`/`run` receive
- * `{ cesdk }`) to/from the engine Shortcut (whose callbacks receive
- * `{ engine }`). The `cesdk` instance is closed over here so the engine layer
+ * the editor-facing KeyboardShortcut (whose `when`/`run` receive a context with
+ * `cesdk`) to/from the engine Shortcut (whose callbacks receive a context with
+ * `engine`). The `cesdk` instance is closed over here so the engine layer
  * never needs to know about it.
  *
  * @public
@@ -5100,13 +5158,13 @@ export declare class KeyboardShortcutsAPI {
      */
     set(shortcut: KeyboardShortcut | KeyboardShortcut[]): () => void;
     /**
-     * List the keyboard shortcuts matching `options` (`keys` AND `scopes`,
-     * glob-matched). Both fields are required and must be non-empty;
-     * `{ keys: '*', scopes: '*' }` lists everything. Throws on an empty field.
+     * List the keyboard shortcuts whose scope matches `options.scopes`
+     * (glob-matched). `scopes` is required and must be non-empty; `{ scopes: '*' }`
+     * lists everything. Throws on an empty `scopes`. To find a shortcut by chord
+     * use `get`/`has`.
      * @public
      */
     list(options: {
-        keys: string | string[];
         scopes: ShortcutScopeId | ShortcutScopeId[];
     }): KeyboardShortcut[];
     /**
@@ -5120,8 +5178,9 @@ export declare class KeyboardShortcutsAPI {
     }): KeyboardShortcut | undefined;
     /**
      * Remove every keyboard shortcut matching `options` (`keys` AND `scopes`).
-     * Both fields are required and must be non-empty; use `'*'` to match all
-     * (e.g. `{ keys: 'Mod+s', scopes: '*' }`). Throws on an empty field.
+     * Both fields are required and must be non-empty; use `'*'` to match all —
+     * for example, `keys: 'Mod+s'` with `scopes: '*'` removes that chord from
+     * every scope. Throws on an empty field.
      * @public
      */
     remove(options: {
@@ -5168,7 +5227,7 @@ export declare class KeyboardShortcutsAPI {
      * @returns A disposer that stops listening.
      * @public
      */
-    setRoot(target?: ShortcutRoot): () => void;
+    setRoot(target: ShortcutRoot): () => void;
 }
 
 /**
@@ -6006,7 +6065,8 @@ export declare interface RemoveResult<A extends UIArea = UIArea> {
 
 /**
  * @public
- * Provides context for replacing asset library entries, including selected blocks and default entry IDs.
+ * Provides context for replacing asset library entries, including the selected blocks and the
+ * default entries (each may carry per-entry source exclusions).
  */
 export declare interface ReplaceAssetLibraryEntriesContext {
     selectedBlocks: {
@@ -6015,7 +6075,7 @@ export declare interface ReplaceAssetLibraryEntriesContext {
         fillType?: FillTypeLonghand;
         supportsShape?: boolean;
     }[];
-    defaultEntryIds: string[];
+    defaultEntryIds: AssetLibraryEntryInput[];
     /**
      * The intent of the replacement operation.
      * - `'shape'`: User explicitly wants to replace the shape (e.g., from shape options panel)
@@ -8131,13 +8191,14 @@ export declare class UserInterfaceAPI {
     /**
      * Sets a function that determines which asset library entries to use for replacement operations.
      *
-     * The function receives context information (like selected blocks or default entry IDs)
-     * and returns the appropriate asset library entry IDs for replacement.
+     * The function receives context (selected blocks, the default entries, the replace intent) and
+     * returns the entries to show. Each entry is either an entry ID, or `{ entry, excludeSourceIds }`
+     * to show that entry with specific sources hidden for this replacement only.
      *
      * @category Asset Library
-     * @param replaceAssetLibraryEntries - Function that receives context and returns an array of asset library entry IDs for replacement.
+     * @param replaceAssetLibraryEntries - Function that receives context and returns the asset library entries (IDs, or `{ entry, excludeSourceIds }`) to show when replacing.
      */
-    setReplaceAssetLibraryEntries(replaceAssetLibraryEntries: (context: ReplaceAssetLibraryEntriesContext) => AssetEntryId[]): void;
+    setReplaceAssetLibraryEntries(replaceAssetLibraryEntries: (context: ReplaceAssetLibraryEntriesContext) => AssetLibraryEntryInput[]): void;
     /**
      * Gets the current view style of the editor interface.
      *
@@ -8269,6 +8330,7 @@ declare namespace UserInterfaceElements {
         AssetLibraryEntryData,
         AssetLibraryEntry,
         AssetLibraryEntries,
+        AssetLibraryEntryInput,
         ReplaceAssetLibraryEntriesContext,
         UserInterfaceElements_2 as UserInterfaceElements
     }