@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/user-interface/customization/quick-start/add-action-buttons.md

@@ -1,531 +0,0 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
-
-**Navigation:** [Guides](./guides.md) > [User Interface](./user-interface.md) > [Customization](./user-interface/customization.md) > [Add Action Buttons](./user-interface/customization/quick-start/add-action-buttons.md)
-
----
-
-Add interactive save, export, and custom action buttons to your CE.SDK editor using built-in action components.
-
-![Add Action Buttons example showing a navigation bar with custom Save, Export, Share, and Download buttons](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-> **Reading time:** 8 minutes
->
-> **Resources:**
->
-> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
-> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-user-interface-customization-quick-start-add-action-buttons-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-user-interface-customization-quick-start-add-action-buttons-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-user-interface-customization-quick-start-add-action-buttons-browser/)
-
-CE.SDK provides built-in action button components that you can insert and configure inline without needing to register custom components. There are two main approaches:
-
-1. **Built-in action buttons** like `ly.img.saveScene.navigationBar` that integrate with the Actions API
-2. **Custom action buttons** using `ly.img.action.navigationBar` with your own `onClick` handlers
-
-```typescript file=@cesdk_web_examples/guides-user-interface-customization-quick-start-add-action-buttons-browser/browser.ts reference-only
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-
-import {
-  BlurAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { DesignEditorConfig } from './design-editor/plugin';
-import packageJson from './package.json';
-
-class Example implements EditorPlugin {
-  name = packageJson.name;
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-    await cesdk.addPlugin(new DesignEditorConfig());
-
-    // Add asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({ include: ['ly.img.image.upload'] })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.blank.*',
-          'ly.img.templates.presentation.*',
-          'ly.img.templates.print.*',
-          'ly.img.templates.social.*',
-          'ly.img.image.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(new PagePresetsAssetSource());
-    await cesdk.addPlugin(new StickerAssetSource());
-    await cesdk.addPlugin(new TextAssetSource());
-    await cesdk.addPlugin(new TextComponentAssetSource());
-    await cesdk.addPlugin(new TypefaceAssetSource());
-    await cesdk.addPlugin(new VectorShapeAssetSource());
-
-    await cesdk.actions.run('scene.create', {
-      page: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.print.iso.a6.landscape'
-      }
-    });
-
-    // Add a built-in save button that integrates with the Actions API
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', after: 'ly.img.spacer' },
-      { id: 'ly.img.saveScene.navigationBar' }
-    );
-
-    // Register the action handler for the save button
-    cesdk.actions.register('saveScene', async () => {
-      const sceneString = await cesdk.engine.scene.saveToString();
-      // eslint-disable-next-line no-console
-      console.log('Scene saved via Actions API! Length:', sceneString.length);
-      // In production: send sceneString to your backend
-      cesdk.ui.showNotification({
-        message: 'Scene saved successfully!'
-      });
-    });
-
-    // Add a custom action button with inline onClick handler
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'my-custom-action',
-        label: 'Custom',
-        icon: '@imgly/Settings',
-        onClick: async () => {
-          // eslint-disable-next-line no-console
-          console.log('Custom action clicked!');
-          // Your custom logic here
-        }
-      }
-    );
-
-    // Add an Export button with accent styling
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'my-export',
-        label: 'Export',
-        icon: '@imgly/Download',
-        color: 'accent',
-        onClick: async () => {
-          // Export to PNG using the utils API
-          const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
-          // eslint-disable-next-line no-console
-          console.log('Exported PNG! Size:', blobs[0].size);
-          // In production: download or upload the blob
-        }
-      }
-    );
-
-    // Create a dropdown menu with multiple export options
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar' },
-      {
-        id: 'ly.img.actions.navigationBar',
-        label: 'Download',
-        icon: '@imgly/Download',
-        children: [
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-png',
-            label: 'Download as PNG',
-            onClick: async () => {
-              const { blobs } = await cesdk.utils.export({
-                mimeType: 'image/png'
-              });
-              downloadBlob(blobs[0], 'design.png');
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-jpeg',
-            label: 'Download as JPEG',
-            onClick: async () => {
-              const { blobs } = await cesdk.utils.export({
-                mimeType: 'image/jpeg'
-              });
-              downloadBlob(blobs[0], 'design.jpg');
-            }
-          },
-          {
-            id: 'ly.img.action.navigationBar',
-            key: 'export-pdf',
-            label: 'Download as PDF',
-            onClick: async () => {
-              const { blobs } = await cesdk.utils.export({
-                mimeType: 'application/pdf'
-              });
-              downloadBlob(blobs[0], 'design.pdf');
-            }
-          }
-        ]
-      }
-    );
-
-    // Insert multiple buttons at once with a separator between them
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
-      [
-        {
-          id: 'ly.img.action.navigationBar',
-          key: 'share',
-          label: 'Share',
-          icon: '@imgly/Share',
-          onClick: () => {
-            // eslint-disable-next-line no-console
-            console.log('Share clicked!');
-          }
-        },
-        'ly.img.separator',
-        {
-          id: 'ly.img.action.navigationBar',
-          key: 'print',
-          label: 'Print',
-          icon: '@imgly/Print',
-          onClick: () => {
-            window.print();
-          }
-        }
-      ]
-    );
-
-    // Use the Utils API for export with built-in loading dialog
-    cesdk.ui.insertOrderComponent(
-      { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'utils-export',
-        label: 'Quick Export',
-        icon: '@imgly/Download',
-        color: 'accent',
-        onClick: async () => {
-          // cesdk.utils.export() shows a loading dialog automatically
-          const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
-          // Download the exported file to user's device
-          await cesdk.utils.downloadFile(blobs[0], 'image/png');
-        }
-      }
-    );
-
-    // eslint-disable-next-line no-console
-    console.log('Add Action Buttons example loaded successfully');
-  }
-}
-
-// Helper function to download a blob as a file
-function downloadBlob(blob: Blob, filename: string) {
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = filename;
-  document.body.appendChild(a);
-  a.click();
-  document.body.removeChild(a);
-  URL.revokeObjectURL(url);
-}
-
-export default Example;
-```
-
-This guide covers both approaches, along with button appearance configuration, dropdown menus, and the Utils API for export operations.
-
-## Use Built-in Action Buttons
-
-CE.SDK provides pre-configured action buttons for common operations like saving, exporting, and importing. These buttons have default labels and icons, and they automatically integrate with the Actions API.
-
-```typescript highlight=highlight-builtin-button
-// Add a built-in save button that integrates with the Actions API
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', after: 'ly.img.spacer' },
-  { id: 'ly.img.saveScene.navigationBar' }
-);
-
-// Register the action handler for the save button
-cesdk.actions.register('saveScene', async () => {
-  const sceneString = await cesdk.engine.scene.saveToString();
-  // eslint-disable-next-line no-console
-  console.log('Scene saved via Actions API! Length:', sceneString.length);
-  // In production: send sceneString to your backend
-  cesdk.ui.showNotification({
-    message: 'Scene saved successfully!'
-  });
-});
-```
-
-When you insert a built-in button like `ly.img.saveScene.navigationBar`, clicking it automatically calls the registered `saveScene` action. You provide the implementation by registering your handler with `cesdk.actions.register()`.
-
-> **Tip:** Built-in buttons use the Actions API under the hood. The button
-> `ly.img.saveScene.navigationBar` triggers `cesdk.actions.run('saveScene')`. See
-> the [Actions API guide](./actions.md) for all available actions.
-
-**Available built-in action buttons:**
-
-| Component ID                         | Triggers Action | Default Label   |
-| ------------------------------------ | --------------- | --------------- |
-| `ly.img.saveScene.navigationBar`     | `saveScene`     | Save            |
-| `ly.img.shareScene.navigationBar`    | `shareScene`    | Share           |
-| `ly.img.exportImage.navigationBar`   | `exportDesign`  | Export as Image |
-| `ly.img.exportPDF.navigationBar`     | `exportDesign`  | Export as PDF   |
-| `ly.img.exportVideo.navigationBar`   | `exportDesign`  | Export as Video |
-| `ly.img.exportScene.navigationBar`   | `exportScene`   | Export Scene    |
-| `ly.img.exportArchive.navigationBar` | `exportScene`   | Export Archive  |
-| `ly.img.importScene.navigationBar`   | `importScene`   | Import Scene    |
-| `ly.img.importArchive.navigationBar` | `importScene`   | Import Archive  |
-
-## Add a Custom Action Button
-
-When you need full control over button behavior, use `ly.img.action.navigationBar` with a custom `onClick` handler. The `key` property must be unique across all action buttons in the editor.
-
-```typescript highlight=highlight-single-action
-// Add a custom action button with inline onClick handler
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
-  {
-    id: 'ly.img.action.navigationBar',
-    key: 'my-custom-action',
-    label: 'Custom',
-    icon: '@imgly/Settings',
-    onClick: async () => {
-      // eslint-disable-next-line no-console
-      console.log('Custom action clicked!');
-      // Your custom logic here
-    }
-  }
-);
-```
-
-The `onClick` handler can be synchronous or asynchronous. In this example, we serialize the scene and log the result. In production, you would send this data to your backend.
-
-## Configure Button Appearance
-
-Action buttons support several configuration options to customize their appearance and behavior.
-
-```typescript highlight=highlight-button-config
-// Add an Export button with accent styling
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', after: 'ly.img.saveScene.navigationBar' },
-  {
-    id: 'ly.img.action.navigationBar',
-    key: 'my-export',
-    label: 'Export',
-    icon: '@imgly/Download',
-    color: 'accent',
-    onClick: async () => {
-      // Export to PNG using the utils API
-      const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
-      // eslint-disable-next-line no-console
-      console.log('Exported PNG! Size:', blobs[0].size);
-      // In production: download or upload the blob
-    }
-  }
-);
-```
-
-| Property     | Type                          | Description                                 |
-| ------------ | ----------------------------- | ------------------------------------------- |
-| `id`         | `string`                      | Must be `'ly.img.action.navigationBar'`     |
-| `key`        | `string`                      | Unique identifier (required)                |
-| `label`      | `string`                      | Button text label (required)                |
-| `onClick`    | `() => void \| Promise<void>` | Click handler function                      |
-| `icon`       | `string`                      | Icon identifier (e.g., `'@imgly/Download'`) |
-| `color`      | `'accent' \| 'danger'`        | Button color variant                        |
-| `variant`    | `'regular' \| 'plain'`        | Button style variant                        |
-| `isDisabled` | `boolean`                     | Whether button is disabled                  |
-| `isLoading`  | `boolean`                     | Whether to show loading state               |
-
-## Create a Dropdown Menu
-
-Use `ly.img.actions.navigationBar` with a `children` array to create a dropdown menu containing multiple actions. This is useful when you have related actions that should be grouped together.
-
-```typescript highlight=highlight-dropdown-menu
-// Create a dropdown menu with multiple export options
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar' },
-  {
-    id: 'ly.img.actions.navigationBar',
-    label: 'Download',
-    icon: '@imgly/Download',
-    children: [
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-png',
-        label: 'Download as PNG',
-        onClick: async () => {
-          const { blobs } = await cesdk.utils.export({
-            mimeType: 'image/png'
-          });
-          downloadBlob(blobs[0], 'design.png');
-        }
-      },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-jpeg',
-        label: 'Download as JPEG',
-        onClick: async () => {
-          const { blobs } = await cesdk.utils.export({
-            mimeType: 'image/jpeg'
-          });
-          downloadBlob(blobs[0], 'design.jpg');
-        }
-      },
-      {
-        id: 'ly.img.action.navigationBar',
-        key: 'export-pdf',
-        label: 'Download as PDF',
-        onClick: async () => {
-          const { blobs } = await cesdk.utils.export({
-            mimeType: 'application/pdf'
-          });
-          downloadBlob(blobs[0], 'design.pdf');
-        }
-      }
-    ]
-  }
-);
-```
-
-Each child in the `children` array follows the same configuration pattern as single action buttons. The dropdown automatically manages its open/close state and displays the children in a menu when clicked.
-
-## Add Multiple Buttons at Once
-
-You can insert multiple buttons in a single call by passing an array. This is more efficient than making multiple `insertOrderComponent()` calls and ensures the buttons appear together in the specified order.
-
-```typescript highlight=highlight-multiple-buttons
-// Insert multiple buttons at once with a separator between them
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
-  [
-    {
-      id: 'ly.img.action.navigationBar',
-      key: 'share',
-      label: 'Share',
-      icon: '@imgly/Share',
-      onClick: () => {
-        // eslint-disable-next-line no-console
-        console.log('Share clicked!');
-      }
-    },
-    'ly.img.separator',
-    {
-      id: 'ly.img.action.navigationBar',
-      key: 'print',
-      label: 'Print',
-      icon: '@imgly/Print',
-      onClick: () => {
-        window.print();
-      }
-    }
-  ]
-);
-```
-
-The array can contain both component objects and string component IDs (like `'ly.img.separator'`). This allows you to mix action buttons with layout components.
-
-## Available Icons
-
-Common icon identifiers for action buttons:
-
-- `@imgly/Download` - Download/export
-- `@imgly/Save` - Save
-- `@imgly/Share` - Share
-- `@imgly/Upload` - Upload/import
-- `@imgly/Copy` - Copy
-- `@imgly/Trash` - Delete
-- `@imgly/Settings` - Settings
-
-## Use Utils API for Export
-
-The Utils API (`cesdk.utils`) provides helper functions for common export and file operations. These are useful when implementing custom export buttons.
-
-```typescript highlight=highlight-utils-export
-// Use the Utils API for export with built-in loading dialog
-cesdk.ui.insertOrderComponent(
-  { in: 'ly.img.navigation.bar', before: 'ly.img.actions.navigationBar' },
-  {
-    id: 'ly.img.action.navigationBar',
-    key: 'utils-export',
-    label: 'Quick Export',
-    icon: '@imgly/Download',
-    color: 'accent',
-    onClick: async () => {
-      // cesdk.utils.export() shows a loading dialog automatically
-      const { blobs } = await cesdk.utils.export({ mimeType: 'image/png' });
-      // Download the exported file to user's device
-      await cesdk.utils.downloadFile(blobs[0], 'image/png');
-    }
-  }
-);
-```
-
-**Key Utils API methods:**
-
-| Method                                 | Purpose                                           |
-| -------------------------------------- | ------------------------------------------------- |
-| `cesdk.utils.export(options)`          | Export with automatic loading dialog and progress |
-| `cesdk.utils.downloadFile(blob, mime)` | Download a file to the user's device              |
-| `cesdk.utils.showLoadingDialog(opts)`  | Show a progress dialog for long operations        |
-| `cesdk.utils.loadFile(options)`        | Open a file picker to load user files             |
-
-The `export()` method automatically displays a loading dialog with progress tracking for video exports. For more control, use `cesdk.engine.block.export()` directly with a custom loading dialog.
-
-> **Note:** For comprehensive coverage of the Actions API and Utils API, see the [Actions API guide](./actions.md).
-
-## Troubleshooting
-
-**Button not appearing** - Ensure `key` is unique when using multiple `ly.img.action.navigationBar` components. Duplicate keys will cause only one button to appear.
-
-**onClick not firing** - Check for JavaScript errors in the console. Ensure the handler is a function, not a function call.
-
-**Icon not showing** - Verify the icon identifier is correct (case-sensitive). Icons use the `@imgly/` prefix.
-
-## API Reference
-
-| Method                              | Purpose                             |
-| ----------------------------------- | ----------------------------------- |
-| `cesdk.ui.insertOrderComponent()`   | Insert action buttons into UI areas |
-| `cesdk.actions.register()`          | Register custom action handlers     |
-| `cesdk.utils.export()`              | Export with built-in loading dialog |
-| `cesdk.utils.downloadFile()`        | Download file to user's device      |
-| `cesdk.engine.block.export()`       | Export blocks/scenes for download   |
-| `cesdk.engine.scene.saveToString()` | Serialize scene for saving          |
-
-## Next Steps
-
-[Actions API](./actions.md) - Learn about the Actions API and all available actions
-
-[Create Custom Components](./user-interface/customization/quick-start/create-custom-components.md) - Build fully custom buttons with the Builder API
-
-[Component Order API](./user-interface/customization/reference/component-order-api.md) - Full API reference for UI manipulation
-
-[Navigation Bar](./user-interface/customization/navigation-bar.md) - Area-specific configuration options
-
----
-
-## More Resources
-
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
-- **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
-- **[Web Documentation](./js.md)** - Interactive documentation with examples
-- **[Support](mailto:support@img.ly)** - Contact IMG.LY support