@imgly/plugin-ai-generation-web 0.1.3 → 0.1.4

package/README.md

@@ -485,6 +485,159 @@ quickActions: {
 }
 ```
 
+### Quick Action Helper Components
+
+The package provides several helper components for common quick action patterns:
+
+#### 1. QuickActionBaseButton
+
+A simple button that triggers an action when clicked:
+
+```typescript
+import { QuickActionBaseButton } from '@imgly/plugin-ai-generation-web';
+
+const quickAction = QuickActionBaseButton<MyInput, ImageOutput>({
+  quickAction: {
+    id: 'enhanceImage',
+    version: '1',
+    enable: true
+  },
+  buttonOptions: {
+    icon: '@imgly/MagicWand'
+  },
+  onClick: async (context) => {
+    await context.generate({
+      prompt: 'Enhance this image and improve quality'
+    });
+  }
+});
+```
+
+#### 2. QuickActionBasePrompt
+
+A button that expands to show a text prompt input:
+
+```typescript
+import { QuickActionBasePrompt } from '@imgly/plugin-ai-generation-web';
+
+const quickAction = QuickActionBasePrompt<MyInput, ImageOutput>({
+  quickAction: {
+    id: 'changeImage',
+    version: '1',
+    enable: true,
+    confirmation: true
+  },
+  buttonOptions: {
+    icon: '@imgly/Edit'
+  },
+  textAreaOptions: {
+    placeholder: 'Describe the changes you want...'
+  },
+  onApply: async (prompt, context) => {
+    return context.generate({
+      prompt: prompt,
+      // other parameters
+    });
+  }
+});
+```
+
+#### 3. QuickActionBaseSelect
+
+A button that opens a menu with selectable options:
+
+```typescript
+import { QuickActionBaseSelect } from '@imgly/plugin-ai-generation-web';
+
+const quickAction = QuickActionBaseSelect<MyInput, ImageOutput>({
+  cesdk: cesdk,
+  quickAction: {
+    id: 'styleTransfer',
+    version: '1',
+    enable: true,
+    confirmation: true
+  },
+  buttonOptions: {
+    icon: '@imgly/Appearance'
+  },
+  items: [
+    {
+      id: 'water',
+      label: 'Watercolor Painting',
+      prompt: 'Convert to watercolor painting.'
+    },
+    {
+      id: 'oil',
+      label: 'Oil Painting',
+      prompt: 'Render in oil painting style.'
+    }
+  ],
+  mapInput: (input) => ({
+    prompt: input.item.prompt,
+    image_url: input.uri
+  })
+});
+```
+
+### Ready-to-Use Image Quick Actions
+
+The package includes several ready-to-use quick actions for common image manipulation tasks:
+
+#### 1. QuickActionChangeImage
+
+Changes an image based on a text prompt:
+
+```typescript
+import { QuickActionChangeImage } from '@imgly/plugin-ai-generation-web';
+
+const changeImageAction = QuickActionChangeImage<MyInput, ImageOutput>({
+  cesdk: cesdk,
+  mapInput: (input) => ({
+    prompt: input.prompt,
+    image_url: input.uri
+  })
+});
+```
+
+#### 2. QuickActionSwapImageBackground
+
+Changes just the background of an image:
+
+```typescript
+import { QuickActionSwapImageBackground } from '@imgly/plugin-ai-generation-web';
+
+const swapBackgroundAction = QuickActionSwapImageBackground<MyInput, ImageOutput>({
+  cesdk: cesdk,
+  mapInput: (input) => ({
+    prompt: input.prompt,
+    image_url: input.uri
+  })
+});
+```
+
+#### 3. QuickActionImageVariant
+
+Creates a variant of an image by duplicating it first:
+
+```typescript
+import { QuickActionImageVariant } from '@imgly/plugin-ai-generation-web';
+
+const imageVariantAction = QuickActionImageVariant<MyInput, ImageOutput>({
+  cesdk: cesdk,
+  onApply: async ({ prompt, uri, duplicatedBlockId }, context) => {
+    return context.generate(
+      {
+        prompt,
+        image_url: uri
+      },
+      {
+        blockIds: [duplicatedBlockId]
+      }
+    );
+  }
+});
+```
+
 ### Simple Quick Action Example
 
 ```typescript

package/dist/generation/middleware/dryRunMiddleware.d.ts

@@ -0,0 +1,9 @@
+import { type Output, type OutputKind, type GetBlockInputResult } from '../provider';
+import { Middleware } from './middleware';
+interface DryRunOptions<K extends OutputKind> {
+    kind: K;
+    blockInputs?: GetBlockInputResult<K>;
+    blockIds?: number[];
+}
+declare function dryRunMiddleware<I, K extends OutputKind, O extends Output>(options: DryRunOptions<K>): Middleware<I, O>;
+export default dryRunMiddleware;

package/dist/generation/provider.d.ts

@@ -22,7 +22,7 @@ interface Provider<K extends OutputKind, I, O extends Output, C = O> {
      * Initialize the provider when the plugin is loaded.
      * Can be used to initialize libraries, and register additional UI components.
      */
-    initialize: (options: {
+    initialize?: (options: {
         engine: CreativeEngine;
         /**
          * If undefined, this indicates that the plugin was loaded
@@ -345,6 +345,12 @@ export type QuickActionsInput<I, O extends Output> = {
 };
 export type QuickAction<I, O extends Output> = {
     id: string;
+    /**
+     * If set, the quick action is shown in the menu for this kind, instead
+     * of the kind of the provider. E.g. a video provider can add a quick action,
+     * to add a button in the image menu to generate a video from.
+     */
+    kind?: OutputKind;
     version: '1';
     /**
      * Defines if the quick action is enabled or not by using the

package/dist/generation/quickAction/common/QuickActionBaseButton.d.ts

@@ -0,0 +1,11 @@
+import { ButtonOptions } from '@cesdk/cesdk-js';
+import { Output, QuickAction, QuickActionContext } from '../../provider';
+/**
+ * Quick action base for quick actions to open a panel.
+ */
+declare function QuickActionBaseButton<I, O extends Output>(options: {
+    buttonOptions?: ButtonOptions;
+    quickAction: Omit<QuickAction<I, O>, 'render' | 'renderExpanded'>;
+    onClick: (context: QuickActionContext<I, O>) => Promise<void>;
+}): QuickAction<I, O>;
+export default QuickActionBaseButton;

package/dist/generation/quickAction/common/QuickActionBasePrompt.d.ts

@@ -0,0 +1,13 @@
+import { ButtonOptions, TextAreaOptions } from '@cesdk/cesdk-js';
+import { Output, QuickAction, QuickActionContext } from '../../provider';
+/**
+ * Quick action base for quick actions that require a prompt.
+ * Will render a text area for the prompt.
+ */
+declare function QuickActionBasePrompt<I, O extends Output>(options: {
+    buttonOptions?: ButtonOptions;
+    textAreaOptions?: TextAreaOptions;
+    quickAction: Omit<QuickAction<I, O>, 'render' | 'renderExpanded'>;
+    onApply: (prompt: string, context: QuickActionContext<I, O>) => Promise<O>;
+}): QuickAction<I, O>;
+export default QuickActionBasePrompt;

package/dist/generation/quickAction/common/QuickActionBaseSelect.d.ts

@@ -0,0 +1,28 @@
+import CreativeEditorSDK, { ButtonOptions } from '@cesdk/cesdk-js';
+import { Output, QuickAction, QuickActionContext } from '../../provider';
+interface QuickActionBaseSelectItem {
+    id: string;
+    label: string;
+    icon?: string;
+    prompt: string;
+}
+/**
+ * Quick action base for quick actions that require a selection of items.
+ */
+declare function QuickActionBaseSelect<I, O extends Output>(options: {
+    cesdk: CreativeEditorSDK;
+    items: QuickActionBaseSelectItem[];
+    buttonOptions?: ButtonOptions;
+    quickAction: Omit<QuickAction<I, O>, 'render' | 'renderExpanded'>;
+    mapInput?: (input: {
+        item: QuickActionBaseSelectItem;
+        uri: string;
+        blockId: number;
+    }) => I;
+    onApply?: (options: {
+        item: QuickActionBaseSelectItem;
+        uri: string;
+        blockId: number;
+    }, context: QuickActionContext<I, O>) => Promise<O>;
+}): QuickAction<I, O>;
+export default QuickActionBaseSelect;

package/dist/generation/quickAction/common/QuickActionChangeImage.d.ts

@@ -0,0 +1,17 @@
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+import { ImageOutput, QuickAction, QuickActionContext } from '../../provider';
+declare function QuickActionChangeImage<I, O extends ImageOutput>(options: {
+    id?: string;
+    cesdk: CreativeEditorSDK;
+    mapInput?: (input: {
+        prompt: string;
+        uri: string;
+        blockId: number;
+    }) => I;
+    onApply?: (options: {
+        prompt: string;
+        uri: string;
+        blockId: number;
+    }, context: QuickActionContext<I, O>) => Promise<O>;
+}): QuickAction<I, O>;
+export default QuickActionChangeImage;

package/dist/generation/quickAction/common/QuickActionImageVariant.d.ts

@@ -0,0 +1,17 @@
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+import { ImageOutput, QuickAction, QuickActionContext } from '../../provider';
+declare function QuickActionImageVariant<I, O extends ImageOutput>(options: {
+    id?: string;
+    mapInput?: (input: {
+        prompt: string;
+        uri: string;
+        duplicatedBlockId: number;
+    }) => I;
+    onApply?: (options: {
+        prompt: string;
+        uri: string;
+        duplicatedBlockId: number;
+    }, context: QuickActionContext<I, O>) => Promise<O>;
+    cesdk: CreativeEditorSDK;
+}): QuickAction<I, O>;
+export default QuickActionImageVariant;

package/dist/generation/quickAction/common/QuickActionSwapImageBackground.d.ts

@@ -0,0 +1,17 @@
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+import { ImageOutput, QuickAction, QuickActionContext } from '../../provider';
+declare function QuickActionChangeImage<I, O extends ImageOutput>(options: {
+    id?: string;
+    mapInput?: (input: {
+        prompt: string;
+        uri: string;
+        blockId: number;
+    }) => I;
+    onApply?: (options: {
+        prompt: string;
+        uri: string;
+        blockId: number;
+    }, context: QuickActionContext<I, O>) => Promise<O>;
+    cesdk: CreativeEditorSDK;
+}): QuickAction<I, O>;
+export default QuickActionChangeImage;

package/dist/generation/quickAction/common/enableImageFill.d.ts

@@ -0,0 +1,8 @@
+import type CreativeEngine from '@cesdk/engine';
+/**
+ * Enable function for a single image fill block selected.
+ */
+declare function enableImageFill(): ({ engine }: {
+    engine: CreativeEngine;
+}) => boolean;
+export default enableImageFill;

package/dist/generation/quickAction/generate.d.ts

@@ -0,0 +1,19 @@
+import CreativeEditorSDK from '@cesdk/cesdk-js';
+import { QuickActionMenu, ApplyCallbacks } from './types';
+import Provider, { Output, OutputKind, QuickAction } from '../provider';
+import { InitProviderConfiguration } from '../types';
+declare function generate<K extends OutputKind, I, O extends Output>(options: {
+    input: I;
+    blockIds: number[];
+    cesdk: CreativeEditorSDK;
+    quickAction: QuickAction<I, O>;
+    quickActionMenu: QuickActionMenu;
+    provider: Provider<K, I, O>;
+    abortSignal: AbortSignal;
+    confirmationComponentId: string;
+}, config: InitProviderConfiguration): Promise<{
+    dispose: () => void;
+    returnValue: O;
+    applyCallbacks?: ApplyCallbacks;
+}>;
+export default generate;

package/dist/index.d.ts

@@ -15,4 +15,11 @@ export { getPanelId, getDurationForVideo, getThumbnailForVideo, getLabelFromId }
 export { default as registerDockComponent } from './registerDockComponent';
 export { default as getQuickActionMenu } from './generation/quickAction/getQuickActionMenu';
 export { default as registerQuickActionMenuComponent } from './generation/quickAction/registerQuickActionMenuComponent';
+export { default as QuickActionBasePrompt } from './generation/quickAction/common/QuickActionBasePrompt';
+export { default as QuickActionBaseButton } from './generation/quickAction/common/QuickActionBaseButton';
+export { default as QuickActionBaseSelect } from './generation/quickAction/common/QuickActionBaseSelect';
+export { default as QuickActionChangeImage } from './generation/quickAction/common/QuickActionChangeImage';
+export { default as QuickActionImageVariant } from './generation/quickAction/common/QuickActionImageVariant';
+export { default as QuickActionSwapImageBackground } from './generation/quickAction/common/QuickActionSwapImageBackground';
+export { default as enableQuickActionForImageFill } from './generation/quickAction/common/enableImageFill';
 export { isGeneratingStateKey, abortGenerationStateKey } from './generation/renderGenerationComponents';