@imgly/plugin-ai-image-generation-web 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 ## [Unreleased]
 
+## [0.2.4] - 2025-08-07
+
+### New Features
+
+-   [all] **Provider Label Translations**: Added support for provider label translations
+-   [all] **Extended Provider Configuration**: Added support for `history` and `supportedQuickActions` configuration fields in `CommonProviderConfiguration`, allowing customers to:
+    -   Override provider's default history asset source (`history` field) - can be set to `false` to disable history, `'@imgly/local'` for temporary storage, `'@imgly/indexedDB'` for persistent browser storage, or any custom asset source ID
+    -   Configure supported quick actions (`supportedQuickActions` field) - can disable quick actions by setting to `false`/`null`, keep defaults with `true`, or override with custom mappings and configurations
+    -   Both fields are optional and maintain backward compatibility with existing provider configurations
+-   [generation-web] **Utility Function**: Added `mergeQuickActionsConfig` utility function for merging provider defaults with user configuration overrides, exported from `@imgly/plugin-ai-generation-web` with comprehensive Jest test coverage
+
 ## [0.2.3] - 2025-07-23
 
 -   [all] **Automatic History Asset Library Entries**: Composite history asset sources now automatically have corresponding asset library entries created with the same IDs (e.g., `ly.img.ai.image-generation.history`)
 -   [all] **Provider Selection in Expanded Quick Actions**: When a quick action is expanded, users can now switch between all providers that support that specific quick action, enhancing flexibility in provider selection
 -   [all] **Quick Action Can Disable Lock**: Some quick actions can now decide to not lock the block when operating on a block. Examples are `CreateVariant` and `CombineImages`.
+-   [image-generation] **Ideogram V3**: Added support for Ideogram V3 provider for image generation, which supports text-to-image and image-to-image generation
 
 ## [0.2.2] - 2025-07-16
 

package/README.md

@@ -173,6 +173,19 @@ Key features:
 - Adjustable quality settings
 - Custom headers support for API requests
 
+**Custom Translations:**
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.prompt': 'Your image description',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.style': 'Art Style',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.style.realistic_image': 'Photorealistic',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.style.illustration': 'Illustration',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.image_size': 'Canvas Size'
+  }
+});
+```
+
 #### 2. Recraft20b (Text-to-Image)
 
 An enhanced text-to-image model from fal.ai with additional icon style support:
@@ -193,6 +206,19 @@ Key features:
 - Three-way style selection (image/vector/icon)
 - Same image size presets and custom dimensions support
 - Cost-effective alternative to RecraftV3
+
+**Custom Translations:**
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft/v2/text-to-image.property.prompt': 'Icon description',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft/v2/text-to-image.property.style': 'Icon Style',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft/v2/text-to-image.property.style.icon': 'Standard Icon',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft/v2/text-to-image.property.style.logo': 'Logo Icon',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft/v2/text-to-image.property.n_colors': 'Number of Colors'
+  }
+});
+```
 - Custom headers support for API requests
 
 #### 3. GptImage1.Text2Image (Text-to-Image)
@@ -237,6 +263,16 @@ Key features:
 - Includes style presets and artist-specific transformations
 - Custom headers support for API requests
 
+**Custom Translations:**
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    'ly.img.plugin-ai-image-generation-web.fal-ai/gemini-flash-edit.property.prompt': 'Transformation instructions',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/gemini-flash-edit.property.image_url': 'Source Image'
+  }
+});
+```
+
 #### 5. GptImage1.Image2Image (Image-to-Image)
 
 OpenAI's GPT-4 Vision based image editing model that can transform existing images:
@@ -258,7 +294,46 @@ Key features:
 - Can be used as a direct alternative to GeminiFlashEdit
 - Custom headers support for API requests
 
-#### 5. FluxProKontextEdit (Image-to-Image)
+#### 5. IdeogramV3 (Text-to-Image)
+
+A high-quality text-to-image model from fal.ai featuring advanced generation capabilities:
+
+```typescript
+text2image: FalAiImage.IdeogramV3({
+  proxyUrl: 'http://your-proxy-server.com/api/proxy',
+  headers: {
+    'x-custom-header': 'value',
+    'x-client-version': '1.0.0'
+  }
+})
+```
+
+Key features:
+- Four distinct style modes: AUTO, GENERAL, REALISTIC, and DESIGN
+- Multiple image size presets: square HD, square, portrait 4:3/16:9, landscape 4:3/16:9
+- Custom dimensions support (64x64 to 14142x14142 pixels)
+
+#### 6. IdeogramV3Remix (Image-to-Image)
+
+A powerful image remixing model from fal.ai that transforms existing images while preserving core elements:
+
+```typescript
+image2image: FalAiImage.IdeogramV3Remix({
+  proxyUrl: 'http://your-proxy-server.com/api/proxy',
+  headers: {
+    'x-custom-header': 'value',
+    'x-client-version': '1.0.0'
+  }
+})
+```
+
+Key features:
+- **Remix existing images** with text prompts while maintaining core characteristics
+- Four distinct style modes: AUTO, GENERAL, REALISTIC, and DESIGN
+- Multiple image size presets: square HD, square, portrait 4:3/16:9, landscape 4:3/16:9
+- Custom dimensions support (64x64 to 14142x14142 pixels)
+
+#### 7. FluxProKontextEdit (Image-to-Image)
 
 A versatile image editing model that applies stylistic changes and transformations:
 
@@ -273,7 +348,7 @@ Key features:
 - Built-in quick actions for style transfer, artist styles, background swapping, and variants
 - Keeps original image dimensions
 
-#### 6. FluxProKontextMaxEdit (Image-to-Image)
+#### 8. FluxProKontextMaxEdit (Image-to-Image)
 
 A high-quality variant of FluxProKontext offering more detailed results:
 
@@ -289,6 +364,72 @@ Key features:
 - Maintains original dimensions
 - Canvas quick-action integration
 
+### Customizing Labels and Translations
+
+You can customize all labels and text in the AI image generation interface using the translation system. This allows you to provide better labels for your users in any language.
+
+#### Translation Key Structure
+
+The system checks for translations in this order (highest to lowest priority):
+
+1. **Provider-specific**: `ly.img.plugin-ai-image-generation-web.${provider}.property.${field}` - Override labels for a specific AI provider
+2. **Generic**: `ly.img.plugin-ai-generation-web.property.${field}` - Override labels for all AI plugins
+
+#### Basic Example
+
+```typescript
+// Customize labels for your AI image generation interface
+cesdk.i18n.setTranslations({
+  en: {
+    // Generic labels (applies to ALL AI plugins)
+    'ly.img.plugin-ai-generation-web.property.prompt': 'Describe what you want to create',
+    'ly.img.plugin-ai-generation-web.property.image_size': 'Image Dimensions',
+
+    // Provider-specific for RecraftV3
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.prompt': 'Describe your Recraft image',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.image_size': 'Canvas Size',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.image_size.square_hd': 'Square HD (1024×1024)',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3.property.image_size.portrait_4_3': 'Portrait 4:3 (768×1024)',
+
+    // Provider-specific for IdeogramV3
+    'ly.img.plugin-ai-image-generation-web.fal-ai/ideogram/v3.property.prompt': 'Describe your Ideogram image',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/ideogram/v3.property.style_mode': 'Style Mode',
+    'ly.img.plugin-ai-image-generation-web.fal-ai/ideogram/v3.property.style_mode.REALISTIC': 'Photorealistic'
+  }
+});
+```
+
+#### QuickAction Translations
+
+QuickActions (like "Edit Image", "Style Transfer", etc.) use their own translation keys:
+
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    // QuickAction button labels
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage': 'Edit Image...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.swapBackground': 'Swap Background...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.styleTransfer': 'Style Transfer...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.createVariant': 'Create Variant...',
+    
+    // QuickAction input fields and buttons
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage.prompt': 'Edit Image...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage.prompt.placeholder': 'e.g. "Add a sunset"',
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage.apply': 'Change',
+    
+    'ly.img.plugin-ai-image-generation-web.quickAction.swapBackground.prompt': 'Swap Background...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.swapBackground.prompt.placeholder': 'e.g. "Beach at sunset"',
+    'ly.img.plugin-ai-image-generation-web.quickAction.swapBackground.apply': 'Swap'
+  }
+});
+```
+
+**QuickAction Translation Structure:**
+- Base key (e.g., `.quickAction.editImage`): Button text when QuickAction is collapsed
+- `.prompt`: Label for input field when expanded
+- `.prompt.placeholder`: Placeholder text for input field
+- `.apply`: Text for action/submit button
+
 ### Configuration Options
 
 The plugin accepts the following configuration options:
@@ -466,6 +607,26 @@ FalAiImage.Recraft20b(config: {
 })
 ```
 
+#### IdeogramV3
+
+```typescript
+FalAiImage.IdeogramV3(config: {
+  proxyUrl: string;
+  headers?: Record<string, string>;
+  debug?: boolean;
+})
+```
+
+#### IdeogramV3Remix
+
+```typescript
+FalAiImage.IdeogramV3Remix(config: {
+  proxyUrl: string;
+  headers?: Record<string, string>;
+  debug?: boolean;
+})
+```
+
 #### GeminiFlashEdit
 
 ```typescript
@@ -601,6 +762,8 @@ const myImageProvider = {
 - Provider-specific panels:
   - RecraftV3: `ly.img.ai.fal-ai/recraft-v3`
   - Recraft20b: `ly.img.ai.fal-ai/recraft/v2/text-to-image`
+  - IdeogramV3: `ly.img.ai.fal-ai/ideogram/v3`
+  - IdeogramV3Remix: `ly.img.ai.fal-ai/ideogram/v3/remix`
   - GeminiFlashEdit: `ly.img.ai.fal-ai/gemini-flash-edit`
   - GptImage1.Text2Image: `ly.img.ai.open-ai/gpt-image-1/text2image`
   - GptImage1.Image2Image: `ly.img.ai.open-ai/gpt-image-1/image2image`
@@ -612,6 +775,8 @@ const myImageProvider = {
 Generated images are automatically stored in asset sources with the following IDs:
 - RecraftV3: `fal-ai/recraft-v3.history`
 - Recraft20b: `fal-ai/recraft/v2/text-to-image.history`
+- IdeogramV3: `fal-ai/ideogram/v3.history`
+- IdeogramV3Remix: `fal-ai/ideogram/v3/remix.history`
 - GeminiFlashEdit: `fal-ai/gemini-flash-edit.history`
 - GptImage1.Text2Image: `open-ai/gpt-image-1/text2image.history`
 - GptImage1.Image2Image: `open-ai/gpt-image-1/image2image.history`
@@ -635,6 +800,10 @@ currentOrder.splice(2, 0, 'ly.img.ai.image-generation.dock');
 cesdk.ui.setDockOrder(currentOrder);
 ```
 
+## Translations
+
+For customization and localization, see the [translations.json](https://github.com/imgly/plugins/tree/main/packages/plugin-ai-image-generation-web/translations.json) file which contains provider-specific translation keys for image generation interfaces.
+
 ## Related Packages
 
 - [@imgly/plugin-ai-generation-web](https://github.com/imgly/plugins/tree/main/packages/plugin-ai-generation-web) - Core utilities for AI generation

package/dist/fal-ai/IdeogramV3.constants.d.ts

@@ -0,0 +1,8 @@
+export declare const IMAGE_SIZE_MAP: Record<string, {
+    width: number;
+    height: number;
+}>;
+export declare function getImageDimensions(imageSize: string): {
+    width: number;
+    height: number;
+};

package/dist/fal-ai/IdeogramV3.d.ts

@@ -0,0 +1,22 @@
+import { CommonProviderConfiguration, type Provider } from '@imgly/plugin-ai-generation-web';
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+type IdeogramV3Input = {
+    prompt: string;
+    style?: 'AUTO' | 'GENERAL' | 'REALISTIC' | 'DESIGN';
+    image_size?: string | {
+        width: number;
+        height: number;
+    };
+    rendering_speed?: 'TURBO' | 'BALANCED' | 'QUALITY';
+};
+type IdeogramV3Output = {
+    kind: 'image';
+    url: string;
+};
+interface ProviderConfiguration extends CommonProviderConfiguration<IdeogramV3Input, IdeogramV3Output> {
+}
+export declare function IdeogramV3(config: ProviderConfiguration): (context: {
+    cesdk: CreativeEditorSDK;
+}) => Promise<Provider<'image', IdeogramV3Input, IdeogramV3Output>>;
+declare function getProvider(cesdk: CreativeEditorSDK, config: ProviderConfiguration): Provider<'image', IdeogramV3Input, IdeogramV3Output>;
+export default getProvider;

package/dist/fal-ai/IdeogramV3Remix.constants.d.ts

@@ -0,0 +1,8 @@
+export declare const IMAGE_SIZE_MAP: Record<string, {
+    width: number;
+    height: number;
+}>;
+export declare function getImageDimensions(imageSize: string): {
+    width: number;
+    height: number;
+};

package/dist/fal-ai/IdeogramV3Remix.d.ts

@@ -0,0 +1,23 @@
+import { CommonProviderConfiguration, type Provider } from '@imgly/plugin-ai-generation-web';
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+type IdeogramV3RemixUIInput = {
+    prompt: string;
+    image_url: string;
+    style?: 'AUTO' | 'GENERAL' | 'REALISTIC' | 'DESIGN';
+    image_size?: string | {
+        width: number;
+        height: number;
+    };
+    rendering_speed?: 'TURBO' | 'BALANCED' | 'QUALITY';
+    strength?: number;
+};
+type IdeogramV3RemixOutput = {
+    kind: 'image';
+    url: string;
+};
+interface ProviderConfiguration extends CommonProviderConfiguration<IdeogramV3RemixUIInput, IdeogramV3RemixOutput> {
+}
+export declare function IdeogramV3Remix(config: ProviderConfiguration): (context: {
+    cesdk: CreativeEditorSDK;
+}) => Promise<Provider<'image', IdeogramV3RemixUIInput, IdeogramV3RemixOutput>>;
+export {};

package/dist/fal-ai/createImageProvider.d.ts

@@ -10,6 +10,16 @@ type ImageProviderConfiguration = {
      * @deprecated Use `middlewares` instead.
      */
     middleware?: Middleware<any, any>[];
+    /**
+     * Override provider's default history asset source
+     */
+    history?: false | '@imgly/local' | '@imgly/indexedDB' | (string & {});
+    /**
+     * Configure supported quick actions
+     */
+    supportedQuickActions?: {
+        [quickActionId: string]: Partial<ImageQuickActionSupportMap<any>[string]> | false | null;
+    };
 };
 /**
  * Creates a base provider from schema. This should work out of the box

package/dist/fal-ai/index.d.ts

@@ -3,11 +3,15 @@ import { Recraft20b } from './Recraft20b';
 import { GeminiFlashEdit } from './GeminiFlashEdit';
 import { FluxProKontextEdit } from './FluxProKontextEdit';
 import { FluxProKontextMaxEdit } from './FluxProKontextMaxEdit';
+import { IdeogramV3 } from './IdeogramV3';
+import { IdeogramV3Remix } from './IdeogramV3Remix';
 declare const FalAi: {
-    RecraftV3: typeof RecraftV3;
-    Recraft20b: typeof Recraft20b;
-    GeminiFlashEdit: typeof GeminiFlashEdit;
     FluxProKontextEdit: typeof FluxProKontextEdit;
     FluxProKontextMaxEdit: typeof FluxProKontextMaxEdit;
+    GeminiFlashEdit: typeof GeminiFlashEdit;
+    IdeogramV3: typeof IdeogramV3;
+    IdeogramV3Remix: typeof IdeogramV3Remix;
+    Recraft20b: typeof Recraft20b;
+    RecraftV3: typeof RecraftV3;
 };
 export default FalAi;