@imgly/plugin-ai-generation-web 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [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
 
 -   [ai-apps] Fix issue with undefined `cesdk` instance

package/README.md

@@ -202,9 +202,89 @@ interface CommonProviderConfiguration<I, O extends Output> {
     
     // Custom headers to include in all API requests
     headers?: Record<string, string>;
+    
+    // Override provider's default history asset source
+    history?: false | '@imgly/local' | '@imgly/indexedDB' | (string & {});
+    
+    // Configure supported quick actions
+    supportedQuickActions?: {
+        [quickActionId: string]: Partial<QuickActionSupport<I>> | false | null;
+    };
 }
 ```
 
+### Extended Configuration Options
+
+#### History Configuration
+
+The `history` field allows you to override the provider's default history storage behavior:
+
+```typescript
+const provider = createMyImageProvider({
+    proxyUrl: 'https://proxy.example.com',
+    
+    // Disable history storage entirely
+    history: false,
+    
+    // Or use temporary local storage (not persistent)
+    // history: '@imgly/local',
+    
+    // Or use persistent browser storage (default for most providers)
+    // history: '@imgly/indexedDB',
+    
+    // Or use a custom asset source ID
+    // history: 'my-custom-asset-source'
+});
+```
+
+**Available Options:**
+- `false`: Disable history storage entirely
+- `'@imgly/local'`: Use temporary local storage (not persistent across sessions)
+- `'@imgly/indexedDB'`: Use browser IndexedDB storage (persistent across sessions)
+- `string`: Use your own custom asset source ID
+
+#### Quick Actions Configuration
+
+The `supportedQuickActions` field allows you to customize which quick actions are supported and how they behave:
+
+```typescript
+const provider = createMyImageProvider({
+    proxyUrl: 'https://proxy.example.com',
+    
+    // Configure quick actions
+    supportedQuickActions: {
+        // Remove an unwanted quick action
+        'ly.img.editImage': false,
+        
+        // Override with custom mapping
+        'ly.img.swapBackground': {
+            mapInput: (input) => ({
+                prompt: input.prompt,
+                image_url: input.uri,
+                strength: 0.9, // Custom strength
+                style: 'REALISTIC' // Force realistic style
+            })
+        },
+        
+        // Add support for new quick action
+        'ly.img.customAction': {
+            mapInput: (input) => ({
+                prompt: `Custom prefix: ${input.text}`,
+                image_url: input.imageUrl
+            })
+        }
+    }
+});
+```
+
+**Configuration Values:**
+- `false` or `null`: Remove the quick action entirely
+- `true`: Keep the provider's default implementation
+- Object with `mapInput`: Override the quick action with custom input mapping
+- Object with other properties: Override with custom configuration
+
+### Headers Configuration
+
 The `headers` property allows you to include custom HTTP headers in all API requests made by your provider. This is useful for:
 - Adding custom client identification headers
 - Including version information
@@ -657,6 +737,91 @@ render: ({ builder, isExpanded, toggleExpand }) => {
 }
 ```
 
+## Customizing Labels and Text
+
+You can customize all labels and text in the AI generation interface using the translation system. This allows you to provide better labels for your users in any language.
+
+### Translation Priority
+
+The system checks for translations in this order (highest to lowest priority):
+
+1. **Provider & Kind-specific**: `ly.img.plugin-ai-${kind}-generation-web.${provider}.property.${field}` - Override labels for a specific AI provider and generation type
+2. **Generic**: `ly.img.plugin-ai-generation-web.property.${field}` - Override labels for all AI plugins 
+
+Where `${kind}` can be:
+- `image` for image generation plugins
+- `video` for video generation plugins  
+- `audio` for audio generation plugins
+- `text` for text generation plugins
+
+### Basic Example
+
+```typescript
+// Customize labels for your AI 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',
+    'ly.img.plugin-ai-generation-web.property.duration': 'Video Length',
+
+    // Provider-specific for images (highest priority)
+    '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',
+
+    // Provider-specific for videos (highest priority)
+    'ly.img.plugin-ai-video-generation-web.fal-ai/veo3.property.prompt': 'Describe your video scene',
+    'ly.img.plugin-ai-video-generation-web.fal-ai/veo3.property.duration': 'Video Duration'
+  }
+});
+```
+
+### Dropdown Options
+
+For dropdown menus, add the option value to the translation key:
+
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    // Image generation dropdown options
+    '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)',
+
+    // Video generation dropdown options
+    'ly.img.plugin-ai-video-generation-web.fal-ai/veo3.property.duration.5': '5 seconds',
+    'ly.img.plugin-ai-video-generation-web.fal-ai/veo3.property.duration.10': '10 seconds'
+  }
+});
+```
+
+### QuickAction Translations
+
+QuickActions (like "Edit Image", "Style Transfer", etc.) use their own translation keys:
+
+```typescript
+cesdk.i18n.setTranslations({
+  en: {
+    // Image generation QuickActions
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage': 'Edit Image...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage.prompt': 'Edit Image...',
+    'ly.img.plugin-ai-image-generation-web.quickAction.editImage.apply': 'Change',
+
+    // Text generation QuickActions  
+    'ly.img.plugin-ai-text-generation-web.quickAction.improve': 'Improve Text',
+    'ly.img.plugin-ai-text-generation-web.quickAction.translate': 'Translate Text',
+
+    // Video generation QuickActions
+    'ly.img.plugin-ai-video-generation-web.quickAction.createVideo': 'Create Video'
+  }
+});
+```
+
+**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
+
 ## Using Your Provider
 
 Once you've created your provider, you need to initialize it with CreativeEditor SDK and integrate it into the UI.
@@ -700,12 +865,12 @@ function setupMyProvider(cesdk) {
 When a provider is initialized, it automatically registers panels with specific IDs:
 
 ```
-ly.img.ai.{provider-id}
+ly.img.plugin-ai-{kind}-generation-web.{provider-id}
 ```
 
 For example:
-- A provider with ID `my-image-provider` registers a panel with ID `ly.img.ai.my-image-provider`
-- A provider with ID `fal-ai/recraft-v3` registers a panel with ID `ly.img.ai.fal-ai/recraft-v3`
+- A provider with ID `my-image-provider` for images registers a panel with ID `ly.img.plugin-ai-image-generation-web.my-image-provider`
+- A provider with ID `fal-ai/recraft-v3` for images registers a panel with ID `ly.img.plugin-ai-image-generation-web.fal-ai/recraft-v3`
 
 You can programmatically get a panel ID using the `getPanelId` function:
 
@@ -724,14 +889,14 @@ cesdk.ui.openPanel(panelId);
 Quick actions are automatically registered in canvas menus with these IDs:
 
 ```
-ly.img.ai.{kind}.canvasMenu
+ly.img.plugin-ai-{kind}-generation-web.canvasMenu
 ```
 
 For example:
-- Image quick actions: `ly.img.ai.image.canvasMenu`
-- Video quick actions: `ly.img.ai.video.canvasMenu`
-- Audio quick actions: `ly.img.ai.audio.canvasMenu`
-- Text quick actions: `ly.img.ai.text.canvasMenu`
+- Image quick actions: `ly.img.plugin-ai-image-generation-web.canvasMenu`
+- Video quick actions: `ly.img.plugin-ai-video-generation-web.canvasMenu`
+- Audio quick actions: `ly.img.plugin-ai-audio-generation-web.canvasMenu`
+- Text quick actions: `ly.img.plugin-ai-text-generation-web.canvasMenu`
 
 ### Using with Existing AI Generation Plugins
 
@@ -777,8 +942,8 @@ CreativeEditorSDK.create(domElement, {
 
     // Add quick action menus to canvas
     cesdk.ui.setCanvasMenuOrder([
-        'ly.img.ai.image.canvasMenu',
-        'ly.img.ai.video.canvasMenu',
+        'ly.img.plugin-ai-image-generation-web.canvasMenu',
+        'ly.img.plugin-ai-video-generation-web.canvasMenu',
         ...cesdk.ui.getCanvasMenuOrder()
     ]);
 });
@@ -904,9 +1069,44 @@ export { initializeProvider, initializeProviders } from './providers/';
 export { loggingMiddleware, rateLimitMiddleware, uploadMiddleware } from './middleware/';
 
 // Utilities
-export { getPanelId, enableQuickActionForImageFill } from './utils/';
+export { getPanelId, enableQuickActionForImageFill, mergeQuickActionsConfig } from './utils/';
 ```
 
+### Initialization Functions
+
+#### initializeProviders
+
+The `initializeProviders` function is used to initialize multiple providers at once. It creates a composite history asset source and library entry for all providers of the same kind.
+
+```typescript
+const result = await initializeProviders(
+    providers,
+    { engine, cesdk },
+    config
+);
+
+// Return value structure:
+{
+    panel: {
+        builderRenderFunction: Function // UI builder function for provider selection
+    },
+    history: {
+        assetSourceId: string,         // ID of the composite history asset source
+        assetLibraryEntryId: string    // ID of the automatically created asset library entry
+    },
+    providerInitializationResults: Array<{
+        provider: Provider,
+        result: ProviderInitializationResult
+    }>
+}
+```
+
+**Key Points:**
+- Creates a composite history asset source with ID format: `ly.img.plugin-ai-{kind}-generation-web.history`
+- Automatically creates an asset library entry with the same ID as the asset source
+- The library entry is configured with appropriate settings (sortBy: insertedAt descending, canRemove: true, etc.)
+- Returns both the asset source ID and library entry ID for reference
+
 ### Common Types
 
 ```typescript
@@ -916,6 +1116,10 @@ interface CommonProviderConfiguration<I, O extends Output> {
     debug?: boolean;
     middleware?: Middleware<I, O>[];
     headers?: Record<string, string>;
+    history?: false | '@imgly/local' | '@imgly/indexedDB' | (string & {});
+    supportedQuickActions?: {
+        [quickActionId: string]: Partial<QuickActionSupport<I>> | false | null;
+    };
 }
 
 // Quick action definition
@@ -928,3 +1132,7 @@ interface QuickActionDefinition<Q extends Record<string, any>> {
     render: (context: QuickActionRenderContext<Q>) => void;
 }
 ```
+
+## Translations
+
+For customization and localization, see the [translations.json](https://github.com/imgly/plugins/tree/main/packages/plugin-ai-generation-web/translations.json) file which contains base translation keys that can be overridden for all AI plugins.

package/dist/__tests__/mergeQuickActionsConfig.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { ProviderRegistry } from './core/ProviderRegistry';
 export { composeMiddlewares, type Middleware } from './middleware/middleware';
 export { default as loggingMiddleware } from './middleware/loggingMiddleware';
 export { default as uploadMiddleware } from './middleware/uploadMiddleware';
+export { mergeQuickActionsConfig } from './utils/mergeQuickActionsConfig';
 export { default as rateLimitMiddleware, type RateLimitOptions } from './middleware/rateLimitMiddleware';
 export { getPanelId, getDurationForVideo, getThumbnailForVideo, getLabelFromId, isAsyncGenerator, addIconSetOnce } from './utils/utils';
 export { checkAiPluginVersion } from './utils/checkAiPluginVersion';
@@ -23,4 +24,5 @@ export { isGeneratingStateKey, abortGenerationStateKey } from './ui/components/r
 export { default as initializeProviders } from './providers/initializeProviders';
 export { default as initializeProvider } from './providers/initializeProvider';
 export { default as initializeQuickActionComponents } from './ui/quickActions/initializeQuickActionComponents';
+export { extractAndSetSchemaTranslations } from './openapi/extractSchemaTranslations';
 export { AI_EDIT_MODE, AI_METADATA_KEY } from './ui/quickActions/utils';