@webflow/designer-extension-typings 2.0.31 → 2.0.34

package/api.d.ts

@@ -29,6 +29,7 @@ interface SharedApi {
    * - siteId: the unique ID of the current Webflow site.
    * - siteName: the name of the current Webflow site.
    * - shortName: a shortened reference to the name of the current Webflow site.
+   * - kind: the type of site ('site' for standard Webflow sites).
    * - isPasswordProtected: whether the site is password protected.
    * - isPrivateStaging: whether the site has private staging turned on or not.
    * - domains: an array of objects representing the domains associated with the site, each containing the following properties:
@@ -42,6 +43,7 @@ interface SharedApi {
    * console.log('Site ID:', siteInfo.siteId);
    * console.log('Site Name:', siteInfo.siteName);
    * console.log('Shortened Site Name:', siteInfo.shortName);
+   * console.log('Site Kind:', siteInfo.kind);
    * console.log('Domains:', siteInfo.domains);
    * console.log('Workspace ID:', siteInfo.workspaceId);
    * console.log('Workspace Slug:', siteInfo.workspaceSlug);
@@ -51,6 +53,7 @@ interface SharedApi {
     siteId: string;
     siteName: string;
     shortName: string;
+    kind: 'site';
     isPasswordProtected: boolean;
     isPrivateStaging: boolean;
     workspaceId: string;
@@ -342,7 +345,13 @@ interface SharedApi {
    * const heroComponent = await webflow.getComponent('4a669354-353a-97eb-795c-4471b406e043');
    * await webflow.openCanvas(heroComponent);
    *
-   * // Open a component canvas by page
+   * // Open a component canvas by component instance (ComponentElement)
+   * const selectedElement = await webflow.getSelectedElement();
+   * if (selectedElement?.type === 'ComponentInstance') {
+   *   await webflow.openCanvas(selectedElement);
+   * }
+   *
+   * // Open a page canvas by page
    * const myPage = await webflow.getPage('123');
    * await webflow.openCanvas(myPage);
    * ```
@@ -830,6 +839,27 @@ interface DesignerOnlyApi {
     event: 'pseudomode',
     callback: (pseudoMode: null | PseudoStateKey) => void
   ): Unsubscribe;
+  /**
+   * Subscribe to variant selection changes. The callback fires whenever the selected
+   * variant changes on the component canvas.
+   * @param event - The name of the event to subscribe to, specifically 'selectedvariant'.
+   * @param callback - A callback function receiving the newly selected Variant.
+   * @returns An Unsubscribe function that can be used to stop receiving notifications.
+   * @example
+   * ```ts
+   * const unsub = webflow.subscribe('selectedvariant', (variant) => {
+   *   console.log('Variant changed:', variant.name);
+   *   console.log('Variant ID:', variant.id);
+   * });
+   *
+   * // Later, to stop listening:
+   * unsub();
+   * ```
+   */
+  subscribe(
+    event: 'selectedvariant',
+    callback: (variant: Variant) => void
+  ): Unsubscribe;
   /**
    * Checks if the user has the ability to perform the given App Mode
    * @param appModes

package/components.d.ts

@@ -132,6 +132,88 @@ interface Component {
     options: SetSelectedVariantOptions | string
   ): Promise<null>;
 
+  /**
+   * Reorder variants on this component by specifying an array of variant IDs
+   * in the desired order. Accepts variant IDs or `'base'`.
+   *
+   * When a partial list is provided, the listed variants are repositioned
+   * relative to the first item in the list while unlisted variants keep their
+   * existing relative order.
+   *
+   * @param variantIds - Array of variant IDs (or `'base'`) in the desired order.
+   * @returns A Promise that resolves when the reorder is complete.
+   * @example
+   * ```ts
+   * // Full reorder
+   * await component.reorderVariants(['base', 'variant-2', 'variant-1', 'variant-3']);
+   *
+   * // Partial reorder — move variant-1 and variant-3 together
+   * // Before: base, variant-1, variant-2, variant-3
+   * await component.reorderVariants(['variant-1', 'variant-3']);
+   * // After: base, variant-1, variant-3, variant-2
+   * ```
+   */
+  reorderVariants(variantIds: string[]): Promise<null>;
+
+  /**
+   * Delete a variant from this component by ID.
+   * The base variant cannot be deleted.
+   *
+   * @param options - An object containing the `id` of the variant to delete.
+   * @returns A promise that resolves when the variant has been deleted.
+   * @example
+   * ```ts
+   * await heroComponent.deleteVariant({ id: 'variant-456' });
+   * ```
+   */
+  deleteVariant(options: DeleteVariantOptions): Promise<null>;
+  /**
+   * Get a single variant by ID.
+   * Use `'base'` to retrieve the base variant.
+   * @param variantId - The variant ID, or `'base'` for the base variant
+   * @returns A Promise resolving to the Variant object.
+   * @example
+   * ```ts
+   * const variant = await component.getVariant('variant-123');
+   * console.log(variant.name); // "Dark Mode"
+   *
+   * const base = await component.getVariant('base');
+   * console.log(base.name); // "Primary"
+   * ```
+   */
+  getVariant(variantId: string): Promise<Variant>;
+
+  /**
+   * Update settings on a variant. Currently only `name` is supported.
+   * Use `'base'` as the variant ID to rename the base variant.
+   *
+   * @param variantId - The variant ID, or `'base'` for the base variant
+   * @param settings - An object with the properties to update
+   * @returns A Promise resolving to the updated Variant object.
+   * @example
+   * ```ts
+   * // Two-argument form
+   * const updated = await component.setVariant('variant-123', { name: 'Foo' });
+   *
+   * // Rename the base variant
+   * const base = await component.setVariant('base', { name: 'Default' });
+   * ```
+   */
+  setVariant(variantId: string, settings: {name: string}): Promise<Variant>;
+
+  /**
+   * Update settings on a variant using an options object.
+   * Currently only `name` is supported.
+   *
+   * @param options - An object containing the variant `id` and properties to update
+   * @returns A Promise resolving to the updated Variant object.
+   * @example
+   * ```ts
+   * const updated = await component.setVariant({ id: 'variant-123', name: 'Foo' });
+   * ```
+   */
+  setVariant(options: SetVariantOptions): Promise<Variant>;
+
   /**
    * Get the settings (name, group, description) of a component.
    * @returns A Promise resolving to the component's settings.
@@ -157,6 +239,83 @@ interface Component {
    * ```
    */
   setSettings(settings: Partial<ComponentSettings>): Promise<null>;
+
+  /**
+   * Get all prop definitions on this component.
+   * Returns all prop types including variant, visibility, filter, sort, selectedItems,
+   * and booleanFilter — not only the creatable types.
+   * Props are returned in panel display order: ungrouped first, then grouped.
+   * @returns A Promise resolving to an array of prop definitions.
+   */
+  getProps(): Promise<Prop[]>;
+
+  /**
+   * * Get a single prop definition by its ID.
+   * @param propId - The unique ID of the prop.
+   * @returns A Promise resolving to the prop definition.
+   */
+  getProp(propId: string): Promise<Prop>;
+
+  /**
+   * Get a prop definition by its display name.
+   * Matches only ungrouped props.
+   * Use the `groupName` overload for grouped props.
+   * @param name - The display name of the prop.
+   * @returns A Promise resolving to the prop definition.
+   */
+  getPropByName(name: string): Promise<Prop>;
+
+  /**
+   * Get a prop definition by its group and display name.
+   * @param groupName - The group the prop belongs to.
+   * @param name - The display name of the prop within that group.
+   * @returns A Promise resolving to the prop definition.
+   */
+  getPropByName(groupName: string, name: string): Promise<Prop>;
+
+  /**
+   * Create a new prop on this component.
+   *
+   * Supports all 10 creatable prop types. Name conflicts within the same group
+   * are auto-incremented (e.g., "Heading" → "Heading 2"). The returned `Prop`
+   * includes computed fields (`id`, `valueType`, `bindableTo`) so callers don't
+   * need a follow-up `getProps()` call.
+   *
+   * @param options - The prop definition including type, name, and optional settings.
+   * @returns A Promise resolving to the created prop with computed binding metadata.
+   *
+   * @example
+   * ```ts
+   * const prop = await component.createProp({
+   *   type: 'textContent',
+   *   name: 'Heading',
+   *   group: 'Content',
+   *   defaultValue: 'Welcome',
+   * });
+   * ```
+   */
+  createProp(options: CreatePropOptions): Promise<Prop>;
+
+  /**
+   * Create multiple props on this component in a single transaction.
+   * If any prop fails validation, no props are created.
+   * @param options - An array of prop definitions, each using the same shape as createProp.
+   * @returns A Promise resolving to an array of created props, in the same order as the input.
+   */
+  createProps(options: CreatePropOptions[]): Promise<Prop[]>;
+
+  /**
+   * Remove a prop from this component.
+   * @param propId - The ID of the prop to remove.
+   * @returns A Promise that resolves when the prop has been removed.
+   * @example
+   * ```ts
+   * const props = await component.getProps();
+   * const unused = props.find(p => p.name === 'Old Heading');
+   * await component.removeProp(unused.id);
+   * ```
+   */
+  removeProp(propId: string): Promise<null>;
 }
 
 /**
@@ -184,6 +343,19 @@ type SetSelectedVariantOptions =
   | SetSelectedVariantByName
   | SetSelectedVariantById;
 
+/** Options for deleting a variant by ID. */
+interface DeleteVariantOptions {
+  /** The ID of the variant to delete. The base variant ('base') cannot be deleted. */
+  id: string;
+}
+/** Options for setVariant — update variant settings by ID. */
+interface SetVariantOptions {
+  /** The variant ID, or `'base'` for the base variant. */
+  id: string;
+  /** The new display name for the variant. */
+  name: string;
+}
+
 interface Variant {
   /** The variant ID. The base variant always has id 'base'. */
   readonly id: string;
@@ -198,6 +370,170 @@ interface Variant {
   readonly isSelected: boolean;
 }
 
+/**
+ * A prop definition on a component.
+ *
+ * `type` and `valueType` describe the same prop from two different angles:
+ * - `type` is the prop's structural category in the component definition
+ *   (e.g. `'image'` for image asset props).
+ * - `valueType` is the data-binding value type used when binding a CMS field
+ *   or variable to this prop (e.g. `'imageAsset'` for the same image prop).
+ * For most prop types these are identical. The only current exception is image
+ * asset props, where `type === 'image'` and `valueType === 'imageAsset'`.
+ */
+interface Prop {
+  /** The field ID from the component's WFDL data type. */
+  readonly id: string;
+  /**
+   * The prop's structural category (e.g. `'string'`, `'boolean'`, `'image'`,
+   * `'variant'`, `'slot'`). Use this to determine which optional fields
+   * (`min`/`max`/`decimals`, `trueLabel`/`falseLabel`, `multiline`) are present.
+   */
+  readonly type: PropType;
+  /**
+   * The data-binding value type for this prop (e.g. `'string'`, `'boolean'`,
+   * `'imageAsset'`, `'variant'`). Use this when filtering which CMS fields or
+   * variables are compatible with this prop via `bindableTo`.
+   * Identical to `type` for all prop types except image asset props
+   * (`type: 'image'`, `valueType: 'imageAsset'`).
+   */
+  readonly valueType: BindableValueType;
+  /** The data-binding target types this prop can accept. */
+  readonly bindableTo: readonly BindableValueType[];
+  /** The display name for this prop (derived from its label). */
+  name: string;
+  /** The group name this prop belongs to, or null if ungrouped. */
+  group: string | null;
+  /** A tooltip description for this prop, or null if not set. */
+  tooltip: string | null;
+  /**
+   * The default value for this prop, or null if not set or not applicable.
+   *
+   * The shape depends on `valueType`:
+   * - `'string'` | `'number'` | `'id'` | `'altText'` → the raw primitive value
+   * - `'boolean'` → `true` or `false`
+   * - `'imageAsset'` → the asset ID string
+   * - `'link'` → `{ mode: string; to?: string | object; openInNewTab?: boolean; rel?: string }`
+   * - `'video'` → `{ src?: string; title?: string }`
+   * - `'textContent'` → the plain-text string extracted from the default children
+   * - `'richText'` → `{ innerText: string }`
+   * - `'variant'` | `'visibility'` | `'filter'` | `'sort'` | `'selectedItems'`
+   *   → always `null`
+   */
+  readonly defaultValue: ResolvedValue | null;
+  /** Whether the text input allows multiple lines. Present on string and textContent props. */
+  multiline?: boolean;
+  /** The minimum allowed value. Present on number props. */
+  min?: number;
+  /** The maximum allowed value. Present on number props. */
+  max?: number;
+  /** The number of decimal places (precision) allowed. Present on number props. */
+  decimals?: number;
+  /** The label shown when the boolean is true. Present on boolean props. */
+  trueLabel?: string;
+  /** The label shown when the boolean is false. Present on boolean props. */
+  falseLabel?: string;
+}
+
+// ---------------------------------------------------------------------------
+// createProp input types (discriminated union on `type`)
+// ---------------------------------------------------------------------------
+
+/** Common fields shared by all prop types. */
+interface CreatePropCommon {
+  /** Display name for the prop. Auto-incremented on conflicts within the same group. */
+  name: string;
+  /** Group/folder name. Props with the same group appear together in the props panel. */
+  group?: string;
+  /** Tooltip text shown on hover in the props panel. */
+  tooltip?: string;
+  /** The default value for this prop, or null if not set or not applicable. */
+  defaultValue?: ResolvedValue | null;
+}
+
+interface TextContentPropInput extends CreatePropCommon {
+  type: 'textContent';
+  /** Whether the text input supports multiple lines. */
+  multiline?: boolean;
+  defaultValue?: string;
+}
+
+interface StringPropInput extends CreatePropCommon {
+  type: 'string';
+  defaultValue?: string;
+}
+
+interface RichTextPropInput extends CreatePropCommon {
+  type: 'richText';
+  defaultValue?: RichTextResolvedValue;
+}
+
+interface ImagePropInput extends CreatePropCommon {
+  type: 'image';
+  /** Default asset ID. */
+  defaultValue?: string;
+}
+
+interface LinkPropInput extends CreatePropCommon {
+  type: 'link';
+  defaultValue?: LinkResolvedValue;
+}
+
+interface VideoPropInput extends CreatePropCommon {
+  type: 'video';
+  defaultValue?: VideoResolvedValue;
+}
+
+interface NumberPropInput extends CreatePropCommon {
+  type: 'number';
+  min?: number;
+  max?: number;
+  /** Number of decimal places allowed. */
+  decimals?: number;
+  defaultValue?: number;
+}
+
+interface BooleanPropInput extends CreatePropCommon {
+  type: 'boolean';
+  /** Label shown when the value is true (e.g., "Visible"). */
+  trueLabel?: string;
+  /** Label shown when the value is false (e.g., "Hidden"). */
+  falseLabel?: string;
+  defaultValue?: boolean;
+}
+
+interface IdPropInput extends CreatePropCommon {
+  type: 'id';
+  /**
+   * Default ID value. Normalized on the host side — invalid characters are
+   * stripped, spaces become hyphens, result is lowercased. The response returns
+   * the normalized value. Error if normalization produces an empty string.
+   */
+  defaultValue?: string;
+}
+
+interface AltTextPropInput extends CreatePropCommon {
+  type: 'altText';
+  /**
+   * Default alt text value. The special strings `"decorative"` (marks image as
+   * decorative) and `"inherit"` (inherit from asset) have semantic meaning.
+   */
+  defaultValue?: string | null;
+}
+
+/** Options for creating a new prop on a component. Discriminated on `type`. */
+type CreatePropOptions =
+  | TextContentPropInput
+  | StringPropInput
+  | RichTextPropInput
+  | ImagePropInput
+  | LinkPropInput
+  | VideoPropInput
+  | NumberPropInput
+  | BooleanPropInput
+  | IdPropInput
+  | AltTextPropInput;
+
 /**
  * Settings for a component, including name, group, and description.
  */

package/element-settings-generated.d.ts

@@ -31,7 +31,8 @@ type BindableValueType =
   | 'visibility'
   | 'booleanFilter'
   | 'altText'
-  | 'id';
+  | 'id'
+  | 'headingTag';
 
 type PropType =
   | 'textContent'
@@ -50,7 +51,8 @@ type PropType =
   | 'visibility'
   | 'filter'
   | 'sort'
-  | 'selectedItems';
+  | 'selectedItems'
+  | 'headingTag';
 
 type CmsFieldType =
   | 'plainText'
@@ -63,6 +65,7 @@ type CmsFieldType =
   | 'color'
   | 'boolean'
   | 'image'
+  | 'multiImage'
   | 'file'
   | 'video'
   | 'richText';

package/element-settings.d.ts

@@ -52,9 +52,88 @@ type BindableSource =
   | LocaleBindableSource
   | LocaleItemBindableSource;
 
+interface ElementSetting {
+  valueType: BindableValueType;
+  canBind: boolean;
+  value: SettingValue;
+  resolvedValue: ResolvedValue | null;
+  display: SettingDisplay;
+}
+
+interface SearchSettingsOptions {
+  /** Filter to settings that produce a specific value type (e.g., "string", "image") */
+  valueType?: BindableValueType;
+  /** Filter to a specific setting by key (e.g., "domId", "assetId") */
+  key?: string;
+}
+
 interface SearchBindableSourcesOptions {
   /** Filter to sources compatible with a specific element setting key (e.g., "altText", "src", "domId") */
   settingKey?: string;
   /** Filter to sources that produce a specific value type (e.g., "string", "imageAsset") */
   valueType?: BindableValueType;
 }
+
+/** An attribute on an element, as returned by `getSettings()`. */
+interface ElementAttribute {
+  /** The attribute name — a plain string, or binding metadata if bound to a data source. Null when the underlying binding can't be resolved. */
+  name: string | BindingValue | null;
+  /** The attribute's value — a plain string, or binding metadata if bound to a data source. Null when the underlying binding can't be resolved. */
+  value: string | BindingValue | null;
+}
+
+/** An attribute on an element, as returned by `getResolvedSettings()`. */
+interface ResolvedElementAttribute {
+  /** The evaluated string name. Null when a binding can't be resolved at design time. */
+  name: string | null;
+  /** The evaluated string value. Null when a binding can't be resolved at design time. */
+  value: string | null;
+}
+
+/** An attribute to set on an element via `setSettings()`. */
+interface SetElementAttribute {
+  /** A plain string name, or a binding descriptor. Name bindings are only supported on DOM elements. */
+  name: string | BindingInput;
+  /** A plain string value, or a binding descriptor to bind to a data source. */
+  value: string | BindingInput;
+}
+
+/**
+ * Input to `element.setSettings()`.
+ *
+ * Each key is a setting (e.g., `domId`, `tag`, `assetId`). Values can be a
+ * static value, a binding descriptor, or `null` to reset to default.
+ *
+ * The `attributes` key is special: it takes a `SetElementAttribute[]` that
+ * replaces all attributes on the element (pass an empty array to remove
+ * them all). Only `attributes` accepts `SetElementAttribute[]` — other
+ * setting keys expect a value, binding descriptor, or `null`.
+ */
+interface SetSettingsInput {
+  [key: string]: ResolvedValue | BindingInput | SetElementAttribute[] | null;
+}
+
+/**
+ * Return type for `element.getSettings()`.
+ *
+ * Each key is a setting (e.g., `domId`, `tag`, `visibility`). Static values
+ * are returned as-is. Bound values include binding metadata. Null means the
+ * setting has no value and no default.
+ *
+ * `attributes` (when present) is the element's full attribute list.
+ */
+interface ElementSettingSummaries {
+  [key: string]: ResolvedValue | BindingValue | ElementAttribute[] | null;
+}
+
+/**
+ * Return type for `element.getResolvedSettings()`.
+ *
+ * Same keys as `getSettings()`, but every value is fully evaluated.
+ * Bindings that can't be resolved at design time are null.
+ *
+ * `attributes` (when present) contains the resolved attribute values.
+ */
+interface ResolvedElementSettings {
+  [key: string]: ResolvedValue | ResolvedElementAttribute[] | null;
+}