@webflow/designer-extension-typings 2.0.29 → 2.0.31

package/api.d.ts

@@ -8,10 +8,20 @@
 /// <reference path="./variables.d.ts" />
 /// <reference path="./app-subscription.d.ts" />
 /// <reference path="./assets.d.ts" />
+/// <reference path="./element-settings-generated.d.ts" />
+/// <reference path="./element-settings.d.ts" />
+/// <reference path="./instance-props.d.ts" />
 /// <reference path="./app-modes-generated.d.ts" />
 /// <reference path="./app-connections.d.ts" />
 
-interface WebflowApi {
+type AppModeName = 'design' | 'build' | 'preview' | 'edit' | 'comment';
+
+interface AppModeChangeEvent {
+  mode: AppModeName | null;
+  appModes: {[key in AppMode]: boolean};
+}
+
+interface SharedApi {
   /**
    * Get metadata about the current Site.
    * @returns A Promise that resolves to a record containing information about the site that is open in the
@@ -52,50 +62,6 @@ interface WebflowApi {
       stage: 'staging' | 'production';
     }>;
   }>;
-  /**
-   * Get the currently selected element in the Webflow Designer.
-   * @returns A promise that resolves to one of the following:
-   * - null: If no element is currently selected in the Designer
-   * - AnyElement: an object representing the selected element, which can be of any type.
-   * @example
-   * ```ts
-   * const selectedElement = await webflow.getSelectedElement();
-   * if (selectedElement) {
-   *   // Handle the selected element
-   * } else {
-   *   // No element is currently selected
-   * }
-   * ```
-   */
-  getSelectedElement(): Promise<null | AnyElement>;
-  /**
-   * Sets the currently selected element in the Webflow Designer.
-   * @returns A promise that resolves to one of the following:
-   * - null: If no element is able to be currently selected in the Designer
-   * - AnyElement: an object representing the selected element, which can be of any type.
-   * @example
-   * ```ts
-   * await webflow.setSelectedElement(element);
-   * ```
-   */
-  setSelectedElement(element: AnyElement): Promise<null | AnyElement>;
-
-  /**
-   * Captures a screenshot of the specified element.
-   * @returns A promise that resolves to a base64 string representing the screenshot of the element.
-   * @example
-   * ```ts
-   * const selectedElement = await webflow.getSelectedElement();
-   * if (selectedElement) {
-   *   const screenshot = await webflow.getElementSnapshot(selectedElement);
-   *   console.log('Screenshot:', screenshot);
-   * }else{
-   *   console.log('No element selected');
-   * }
-   * ```
-   */
-  getElementSnapshot(element: AnyElement): Promise<null | string>;
-
   /**
    * Renders the specified element to WHTML format.
    * @param element - The element to render
@@ -149,34 +115,12 @@ interface WebflowApi {
     position?: 'before' | 'after' | 'append' | 'prepend' | 'replace'
   ): Promise<AnyElement>;
 
-  /**
-   * Get the current media query breakpoint ID.
-   * @returns A Promise that resolves to a BreakpointId which is a string representing the current media query
-   * breakpoint. A BreakpointId is one of 'tiny', 'small', 'medium', 'main', 'large', 'xl', 'xxl'.
-   * @example
-   * ```ts
-   * const breakpoint = await webflow.getMediaQuery();
-   * console.log('Current Media Query:', breakpoint);
-   * ```
-   */
-  getMediaQuery(): Promise<BreakpointId>;
-
-  /**
-   * Get the current pseudo mode.
-   * @returns A Promise that resolves to a PseudoStateKey which is a string representing the current pseudo mode.
-   * @example
-   * ```ts
-   * const pseudoMode = await webflow.getPseudoMode();
-   * console.log('Current Pseudo Mode:', pseudoMode);
-   * ```
-   */
-  getPseudoMode(): Promise<null | PseudoStateKey>;
-
   /**
    * Create a component by promoting a Root Element.
    * @param name - The name of the component.
    * @param root - An Element that will become the Root Element of the Component.
    * @returns A Promise resolving to an object containing the newly created Component - with the id property.
+   * @deprecated Use `registerComponent(options, root)` instead to provide richer metadata.
    * @example
    * ```ts
    * const element = webflow.createDOM('div')
@@ -207,6 +151,50 @@ interface WebflowApi {
    * ```
    */
   registerComponent(options: ComponentOptions): Promise<Component>;
+  /**
+   * Duplicate an existing component.
+   * @param options - Options for the new component, including a required name.
+   * @param source - The existing Component to duplicate.
+   * @returns A Promise resolving to the newly created Component.
+   * @example
+   * ```ts
+   * const [original] = await webflow.getAllComponents()
+   * const copy = await webflow.registerComponent({name: 'Hero Copy'}, original)
+   * ```
+   */
+  registerComponent(
+    options: ComponentOptions,
+    source: Component
+  ): Promise<Component>;
+  /**
+   * Convert an element or element preset into a component. Equivalent to the
+   * "Convert selection" action in the Designer's "New component" menu.
+   * Elements do not need to be on the page. You can build the tree with
+   * `createDOM` first and pass it directly.
+   *
+   * When `root` is a canvas `AnyElement`, the source element is replaced
+   * in-place by a new component instance by default. Pass `replace: false`
+   * in `options` to skip this substitution and keep the original element.
+   * @param options - Options for the new component. `name` is required;
+   *   `group`, `description`, and `replace` are optional.
+   * @param root - The element, element preset, or builder element that becomes the component root.
+   * @returns A Promise resolving to the newly created Component.
+   * @example
+   * ```ts
+   * // Convert a canvas element and replace it with a component instance (default)
+   * const el = await webflow.getSelectedElement()
+   * const card = await webflow.registerComponent({name: 'Card', group: 'UI'}, el)
+   *
+   * // Convert without replacing the original element in the canvas
+   * const card2 = await webflow.registerComponent(
+   *   {name: 'Card 2', replace: false},
+   *   el
+   * )
+   */
+  registerComponent(
+    options: ComponentOptions,
+    root: AnyElement | ElementPreset<AnyElement> | BuilderElement
+  ): Promise<Component>;
   /**
    * Delete a component from the Designer. If there are any instances of the Component within the site, they will
    * be converted to regular Elements.
@@ -237,6 +225,76 @@ interface WebflowApi {
    * ```
    */
   getAllComponents(): Promise<Array<Component>>;
+  /**
+   * Search site components with optional fuzzy filtering.
+   * Returns a flat array of {@link ComponentSearchResult} objects in the same order as the
+   * Components panel (insertion order). When `options.q` is provided, results are filtered
+   * using FlexSearch (`tokenize: 'full'`) — the same algorithm used by the Components panel.
+   *
+   * @param options - Optional search options.
+   * @param options.q - Search query string. Omit or leave empty to return all components.
+   * @returns A Promise resolving to an array of {@link ComponentSearchResult} objects.
+   *
+   * @example
+   * ```ts
+   * // Get all components
+   * const all = await webflow.searchComponents();
+   *
+   * // Filter by name
+   * const heroes = await webflow.searchComponents({ q: 'Hero' });
+   * heroes.forEach(c => {
+   *   console.log(c.name, c.instances, c.canEdit, c.library);
+   * });
+   * ```
+   */
+  searchComponents(
+    options?: SearchComponentsOptions
+  ): Promise<ComponentSearchResult[]>;
+  /**
+   * Returns a component reference when the user is editing in-context or on the component canvas, or null if no component is being edited.
+   * @returns A Promise that resolves to a Component reference or null.
+   * @example
+   * ```ts
+   * const component = await webflow.getCurrentComponent();
+   * if (component) {
+   *   const name = await component.getName();
+   *   console.log(`Currently editing: ${name}`);
+   * }
+   * ```
+   */
+  getCurrentComponent(): Promise<Component | null>;
+  /**
+   * Get a Component by its unique identifier.
+   * @param id - The unique identifier of the component.
+   * @returns A Promise that resolves to the Component with the given id.
+   * @example
+   * ```ts
+   * const componentId = '4a669354-353a-97eb-795c-4471b406e043';
+   * const component = await webflow.getComponent(componentId);
+   * ```
+   */
+  getComponent(id: ComponentId): Promise<Component>;
+  /**
+   * Get a Component by its display name. Only returns native site components.
+   * Throws if the matching component is a code component.
+   * @param name - The display name of the component.
+   * @example
+   * ```ts
+   * const component = await webflow.getComponentByName('Hero');
+   * ```
+   */
+  getComponentByName(name: string): Promise<Component>;
+  /**
+   * Get a Component by its group and display name. Only returns native site components.
+   * Throws if the matching component is a code component.
+   * @param group - The group name the component belongs to.
+   * @param name - The display name of the component.
+   * @example
+   * ```ts
+   * const component = await webflow.getComponentByName('Marketing', 'Hero');
+   * ```
+   */
+  getComponentByName(group: string, name: string): Promise<Component>;
   /**
    * Focus the designer on a Component. When a component is in focus, all Globals pertain specifically to that
    * Component, not the entire Site.
@@ -258,6 +316,38 @@ interface WebflowApi {
    * ```
    */
   exitComponent(): Promise<null>;
+  /**
+   * Navigate the Designer to a component canvas or page.
+   * @param options - An object with either pageId or componentId.
+   * @returns A Promise that resolves when the navigation is complete.
+   * @example
+   * ```ts
+   * // Open a component canvas by component id
+   * await webflow.openCanvas({componentId: '4a669354-353a-97eb-795c-4471b406e043'});
+   *
+   * // Open a component canvas by page id
+   * await webflow.openCanvas({pageId: '123'});
+   * ```
+   */
+  openCanvas(
+    options: OpenCanvasByComponentId | OpenCanvasByPageId
+  ): Promise<void>;
+  /**
+   * Navigate the Designer to a component canvas or page using a reference.
+   * @param reference - A Component, ComponentElement, or Page reference.
+   * @returns A Promise that resolves when the navigation is complete.
+   * @example
+   * ```ts
+   * // Open a component canvas by component
+   * const heroComponent = await webflow.getComponent('4a669354-353a-97eb-795c-4471b406e043');
+   * await webflow.openCanvas(heroComponent);
+   *
+   * // Open a component canvas by page
+   * const myPage = await webflow.getPage('123');
+   * await webflow.openCanvas(myPage);
+   * ```
+   */
+  openCanvas(reference: Component | ComponentElement | Page): Promise<void>;
   /**
    * Get Root element. When the designer is focused or "entered" into a Component, this method will get the
    * outermost element in the Component.
@@ -349,16 +439,6 @@ interface WebflowApi {
    * ```
    */
   getAllStyles(): Promise<Array<Style>>;
-  /**
-   * Fetch the currently active page in the Webflow designer.
-   * @returns A Promise that resolves to a Page object representing the current page open in the Designer.
-   * @example
-   * ```ts
-   * const currentPage = await webflow.getCurrentPage();
-   * console.log('Current Page:', currentPage);
-   * ```
-   */
-  getCurrentPage(): Promise<Page>;
   /**
    * Fetch an array of all pages and folders in the Webflow project.
    * @returns A Promise that resolves to an array of Page and Folder objects representing all the pages
@@ -393,17 +473,6 @@ interface WebflowApi {
    * ```
    */
   createPage(): Promise<Page>;
-  /**
-   * @param page - The Page object representing the target page to switch to.
-   * @returns A Promise that resolves when the page switch is successful.
-   * @example
-   * ```ts
-   * const targetPage = <Get the target page>;
-   * await webflow.switchPage(targetPage);
-   * // Page switched successfully
-   * ```
-   */
-  switchPage(page: Page): Promise<null>;
   /**
    * Access the default variable collection.
    * @returns A Promise that resolves into a Collection.
@@ -459,6 +528,160 @@ interface WebflowApi {
    */
   removeVariableCollection(id: VariableCollectionId): Promise<boolean>;
 
+  getIdToken(): Promise<string>;
+  getAppSubscriptions(): Promise<Array<AppSubscription>>;
+  elementPresets: ElementPresets;
+  /**
+   * Removes the Style from the site.
+   * @example
+   * ```ts
+   * await webflow.removeStyle(style);
+   * ```
+   */
+  removeStyle(style: Style): Promise<null>;
+
+  /**
+   * Create a new asset, associated with the site
+   * @example
+   * ```ts
+   * const fileBlob = new File([blob], 'cat.png', { type: 'image/png' });
+   * const asset = await webflow.createAsset(fileBlob);
+   * ```
+   */
+  createAsset(fileBlob: File): Promise<Asset>;
+
+  /**
+   * Gets an asset by its id
+   * @example
+   * ```ts
+   * const asset = await webflow.getAssetById('1234');
+   * ```
+   * @param id
+   */
+  getAssetById(id: AssetId): Promise<null | Asset>;
+
+  /**
+   * Gets all assets for the site
+   * @example
+   * ```ts
+   * const assets = await webflow.getAllAssets();
+   * ```
+   */
+  getAllAssets(): Promise<Array<Asset>>;
+
+  /**
+   * Gets all asset folders for the site
+   * @example
+   * ```ts
+   * const assetFolders = await webflow.getAssetFolders();
+   * console.log('Asset folders:', assetFolders);
+   * ```
+   * @returns A Promise that resolves to an array of AssetFolder objects
+   */
+  getAllAssetFolders(): Promise<Array<AssetFolder>>;
+
+  /**
+   * Creates a new asset folder within a given site
+   * @param name - The name of the new asset folder.
+   * @param parentFolderId - Optional. The ID of the parent folder. If not provided, the folder will be created at the root level.
+   * @returns A Promise that resolves to the newly created AssetFolder object.
+   * @example
+   * ```ts
+   * const newFolder = await webflow.createAssetFolder('My New Folder');
+   * console.log('New folder created:', newFolder.id);
+   * ```
+   */
+  createAssetFolder(
+    name: string,
+    parentFolderId?: string
+  ): Promise<AssetFolder>;
+}
+
+interface DesignerOnlyApi {
+  /**
+   * Get the currently selected element in the Webflow Designer.
+   * @returns A promise that resolves to one of the following:
+   * - null: If no element is currently selected in the Designer
+   * - AnyElement: an object representing the selected element, which can be of any type.
+   * @example
+   * ```ts
+   * const selectedElement = await webflow.getSelectedElement();
+   * if (selectedElement) {
+   *   // Handle the selected element
+   * } else {
+   *   // No element is currently selected
+   * }
+   * ```
+   */
+  getSelectedElement(): Promise<null | AnyElement>;
+  /**
+   * Sets the currently selected element in the Webflow Designer.
+   * @returns A promise that resolves to one of the following:
+   * - null: If no element is able to be currently selected in the Designer
+   * - AnyElement: an object representing the selected element, which can be of any type.
+   * @example
+   * ```ts
+   * await webflow.setSelectedElement(element);
+   * ```
+   */
+  setSelectedElement(element: AnyElement): Promise<null | AnyElement>;
+  /**
+   * Captures a screenshot of the specified element.
+   * @returns A promise that resolves to a base64 string representing the screenshot of the element.
+   * @example
+   * ```ts
+   * const selectedElement = await webflow.getSelectedElement();
+   * if (selectedElement) {
+   *   const screenshot = await webflow.getElementSnapshot(selectedElement);
+   *   console.log('Screenshot:', screenshot);
+   * }else{
+   *   console.log('No element selected');
+   * }
+   * ```
+   */
+  getElementSnapshot(element: AnyElement): Promise<null | string>;
+  /**
+   * Get the current media query breakpoint ID.
+   * @returns A Promise that resolves to a BreakpointId which is a string representing the current media query
+   * breakpoint. A BreakpointId is one of 'tiny', 'small', 'medium', 'main', 'large', 'xl', 'xxl'.
+   * @example
+   * ```ts
+   * const breakpoint = await webflow.getMediaQuery();
+   * console.log('Current Media Query:', breakpoint);
+   * ```
+   */
+  getMediaQuery(): Promise<BreakpointId>;
+  /**
+   * Get the current pseudo mode.
+   * @returns A Promise that resolves to a PseudoStateKey which is a string representing the current pseudo mode.
+   * @example
+   * ```ts
+   * const pseudoMode = await webflow.getPseudoMode();
+   * console.log('Current Pseudo Mode:', pseudoMode);
+   * ```
+   */
+  getPseudoMode(): Promise<null | PseudoStateKey>;
+  /**
+   * Fetch the currently active page in the Webflow designer.
+   * @returns A Promise that resolves to a Page object representing the current page open in the Designer.
+   * @example
+   * ```ts
+   * const currentPage = await webflow.getCurrentPage();
+   * console.log('Current Page:', currentPage);
+   * ```
+   */
+  getCurrentPage(): Promise<Page>;
+  /**
+   * @param page - The Page object representing the target page to switch to.
+   * @returns A Promise that resolves when the page switch is successful.
+   * @example
+   * ```ts
+   * const targetPage = <Get the target page>;
+   * await webflow.switchPage(targetPage);
+   * // Page switched successfully
+   * ```
+   */
+  switchPage(page: Page): Promise<null>;
   /**
    * Sets the extension size to one of predefined sizes or a custom size. If the specified custom size is larger than
    * the user's viewport size, the extension will default to the width/height of the browser's viewport.
@@ -593,88 +816,25 @@ interface WebflowApi {
     event: 'currentcmsitem',
     callback: (cmsItemId: null | string) => void
   ): Unsubscribe;
-
-  subscribe(event: 'currentappmode', callback: () => void): Unsubscribe;
-
+  /**
+   * Subscribe to app mode changes. The callback receives the current mode
+   * and the full appModes capability map.
+   * @param event - The name of the event to subscribe to, specifically 'currentappmode'.
+   * @param callback - A callback function receiving the current AppModeChangeEvent.
+   */
+  subscribe(
+    event: 'currentappmode',
+    callback: (event: AppModeChangeEvent) => void
+  ): Unsubscribe;
   subscribe(
     event: 'pseudomode',
     callback: (pseudoMode: null | PseudoStateKey) => void
   ): Unsubscribe;
-
-  getIdToken(): Promise<string>;
-  getAppSubscriptions(): Promise<Array<AppSubscription>>;
-  elementPresets: ElementPresets;
-  /**
-   * Removes the Style from the site.
-   * @example
-   * ```ts
-   * await webflow.removeStyle(style);
-   * ```
-   */
-  removeStyle(style: Style): Promise<null>;
-
-  /**
-   * Create a new asset, associated with the site
-   * @example
-   * ```ts
-   * const fileBlob = new File([blob], 'cat.png', { type: 'image/png' });
-   * const asset = await webflow.createAsset(fileBlob);
-   * ```
-   */
-  createAsset(fileBlob: File): Promise<Asset>;
-
-  /**
-   * Gets an asset by its id
-   * @example
-   * ```ts
-   * const asset = await webflow.getAssetById('1234');
-   * ```
-   * @param id
-   */
-  getAssetById(id: AssetId): Promise<null | Asset>;
-
-  /**
-   * Gets all assets for the site
-   * @example
-   * ```ts
-   * const assets = await webflow.getAllAssets();
-   * ```
-   */
-  getAllAssets(): Promise<Array<Asset>>;
-
-  /**
-   * Gets all asset folders for the site
-   * @example
-   * ```ts
-   * const assetFolders = await webflow.getAssetFolders();
-   * console.log('Asset folders:', assetFolders);
-   * ```
-   * @returns A Promise that resolves to an array of AssetFolder objects
-   */
-  getAllAssetFolders(): Promise<Array<AssetFolder>>;
-
-  /**
-   * Creates a new asset folder within a given site
-   * @param name - The name of the new asset folder.
-   * @param parentFolderId - Optional. The ID of the parent folder. If not provided, the folder will be created at the root level.
-   * @returns A Promise that resolves to the newly created AssetFolder object.
-   * @example
-   * ```ts
-   * const newFolder = await webflow.createAssetFolder('My New Folder');
-   * console.log('New folder created:', newFolder.id);
-   * ```
-   */
-  createAssetFolder(
-    name: string,
-    parentFolderId?: string
-  ): Promise<AssetFolder>;
-
   /**
    * Checks if the user has the ability to perform the given App Mode
    * @param appModes
    */
   canForAppMode(appModes: Array<AppMode>): Promise<{[key in AppMode]: boolean}>;
-
   /**
    * The list of App Modes that are available to be queried
    * ```ts
@@ -682,7 +842,17 @@ interface WebflowApi {
    * ```
    */
   appModes: {[key in AppMode]: AppMode};
-
+  /**
+   * Checks if the current Designer mode matches the given mode name.
+   * @param mode - The mode name to check against (e.g., 'design', 'build', 'preview')
+   * @returns True if the Designer is currently in the specified mode
+   */
+  isMode(mode: AppModeName): Promise<boolean>;
+  /**
+   * Gets the current Designer mode name.
+   * @returns The current mode name, or null if the mode cannot be determined
+   */
+  getCurrentMode(): Promise<AppModeName | null>;
   /**
    * Closes the extension
    * ```ts
@@ -690,7 +860,6 @@ interface WebflowApi {
    * ```
    */
   closeExtension(): Promise<null>;
-
   /**
    * Gets the current App connection
    * ```ts
@@ -698,7 +867,6 @@ interface WebflowApi {
    * ```
    */
   getCurrentAppConnection(): Promise<null | string>;
-
   /**
    * Gets the current App connection resource
    * ```ts
@@ -706,7 +874,6 @@ interface WebflowApi {
    * ```
    */
   getCurrentAppConnectionResource(): Promise<null | AppConnectionResource>;
-
   /**
    * Gets the current App launch context (i.e how the app was launched)
    * ```ts
@@ -716,4 +883,27 @@ interface WebflowApi {
   getLaunchContext(): Promise<null | LaunchContext>;
 }
 
+interface WebflowApi extends SharedApi, DesignerOnlyApi {}
+
+interface WebflowPageApi extends SharedApi {}
+
+/**
+ * Thrown when an API call fails because the Designer is in the wrong mode.
+ * Use `err.cause.tag` to identify the error programmatically.
+ * Use `err.message` for the human-readable description of what went wrong.
+ */
+interface AppModeForbiddenError extends Error {
+  cause: {
+    tag: 'ModeForbidden';
+  };
+}
+
 type Unsubscribe = () => void;
+
+interface OpenCanvasByComponentId {
+  componentId: string;
+}
+
+interface OpenCanvasByPageId {
+  pageId: string;
+}