@webflow/designer-extension-typings 2.0.33 → 2.0.35

package/api.d.ts

@@ -345,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);
    * ```

package/components.d.ts

@@ -69,6 +69,20 @@ interface Component {
    */
   getVariants(): Promise<Variant[]>;
 
+  /**
+   * Create a new variant for this component.
+   * @param name - The name for the new variant
+   * @returns A promise that resolves to the newly created Variant.
+   * @example
+   * ```ts
+   * const quickVariant = await heroComponent.createVariant("Dark Mode");
+   * const variant = await heroComponent.createVariant({ name: "Dark Mode" });
+   * console.log(quickVariant.name); // "Dark Mode"
+   * console.log(variant.name); // "Dark Mode"
+   * ```
+   */
+  createVariant(name: string): Promise<Variant>;
+
   /**
    * Create a new variant for this component.
    * @param options - The name for the new variant and optional selection behavior
@@ -249,6 +263,30 @@ interface Component {
    */
   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.
    *
@@ -279,6 +317,57 @@ interface Component {
    * @returns A Promise resolving to an array of created props, in the same order as the input.
    */
   createProps(options: CreatePropOptions[]): Promise<Prop[]>;
+
+  /**
+   * Update an existing prop's settings.
+   *
+   * Accepts a partial update object — only the fields being changed need to be
+   * provided. Cannot change a prop's `type` (immutable after creation).
+   * Name conflicts within the target group are auto-incremented. Setting a field
+   * to `null` clears it where applicable.
+   *
+   * @param propId - The ID of the prop to update.
+   * @param updates - A partial object with the fields to change.
+   * @returns A Promise resolving to the full updated prop.
+   *
+   * @example
+   * ```ts
+   * const updated = await component.setProp(prop.id, {
+   *   name: 'Hero Heading',
+   *   tooltip: 'The main headline for the hero section',
+   * });
+   * ```
+   */
+  setProp(propId: string, updates: SetPropOptions): Promise<Prop>;
+
+  /**
+   * Update an existing prop's settings.
+   *
+   * @param updates - A partial object with `id` and the fields to change.
+   * @returns A Promise resolving to the full updated prop.
+   *
+   * @example
+   * ```ts
+   * const updated = await component.setProp({
+   *   id: prop.id,
+   *   name: 'Hero Heading',
+   * });
+   * ```
+   */
+  setProp(updates: SetPropOptionsWithId): 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>;
 }
 
 /**
@@ -386,12 +475,12 @@ interface Prop {
   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 minimum allowed value. Present on number props, otherwise null when unset. */
+  min?: number | null;
+  /** The maximum allowed value. Present on number props, otherwise null when unset. */
+  max?: number | null;
+  /** The number of decimal places (precision) allowed. Present on number props, otherwise null when unset. */
+  decimals?: number | null;
   /** 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. */
@@ -402,16 +491,29 @@ interface Prop {
 // createProp input types (discriminated union on `type`)
 // ---------------------------------------------------------------------------
 
-/** Common fields shared by all prop types. */
-interface CreatePropCommon {
+/**
+ * Fields shared between creating and updating props.
+ * Used as the base interface for both {@link CreatePropCommon} and {@link SetPropOptions}.
+ */
+interface PropSettingsCommon {
+  /** Display name for the prop. */
+  name?: string;
+  /** Group/folder name. Props with the same group appear together. `null` to ungroup. */
+  group?: string | null;
+  /** Tooltip text shown on hover. `null` to remove. */
+  tooltip?: string | null;
+  /** The default value for this prop (shape depends on type). `null` to clear. */
+  defaultValue?: ResolvedValue | null;
+}
+
+/** Common fields shared by all prop types when creating. */
+interface CreatePropCommon extends PropSettingsCommon {
   /** 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 {
@@ -497,6 +599,37 @@ type CreatePropOptions =
   | IdPropInput
   | AltTextPropInput;
 
+// ---------------------------------------------------------------------------
+// setProp input types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for updating an existing prop on a component.
+ * All fields are optional — only the fields being changed need to be provided.
+ * Cannot change a prop's `type` (immutable after creation).
+ * Setting a field to `null` clears it where applicable.
+ */
+interface SetPropOptions extends PropSettingsCommon {
+  /** Whether the text input supports multiple lines. textContent only. */
+  multiline?: boolean;
+  /** Minimum allowed value. number only. `null` clears the constraint. */
+  min?: number | null;
+  /** Maximum allowed value. number only. `null` clears the constraint. */
+  max?: number | null;
+  /** Number of decimal places allowed. number only. `null` clears the constraint. */
+  decimals?: number | null;
+  /** Label shown when the value is true (e.g., "Visible"). boolean only. `null` clears. */
+  trueLabel?: string | null;
+  /** Label shown when the value is false (e.g., "Hidden"). boolean only. `null` clears. */
+  falseLabel?: string | null;
+}
+
+/** {@link SetPropOptions} with an inline `id` for the single-argument overload. */
+interface SetPropOptionsWithId extends SetPropOptions {
+  /** The ID of the prop to update. */
+  id: string;
+}
+
 /**
  * Settings for a component, including name, group, and description.
  */

package/element-settings.d.ts

@@ -74,32 +74,66 @@ interface SearchBindableSourcesOptions {
   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 key (e.g., 'domId', 'tag', 'assetId').
- * Values can be:
- * - A static value (string, number, boolean, or object depending on the setting type)
- * - A BindingInput to bind the setting to a data source
- * - null to reset the setting to its default / disconnect any binding
+ * 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`.
  */
-type SetSettingsInput = Record<string, ResolvedValue | BindingInput | null>;
+interface SetSettingsInput {
+  [key: string]: ResolvedValue | BindingInput | SetElementAttribute[] | null;
+}
 
 /**
- * Return type for element.getSettings().
- * Each key is a setting key (e.g., 'domId', 'tag', 'visibility').
- * Static values are bare (string, number, boolean, etc.).
- * Bound values include binding metadata (sourceType + source fields).
- * Settings with no value and no default are 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.
  */
-type ElementSettingSummaries = Record<
-  string,
-  ResolvedValue | BindingValue | null
->;
+interface ElementSettingSummaries {
+  [key: string]: ResolvedValue | BindingValue | ElementAttribute[] | null;
+}
 
 /**
- * Return type for element.getResolvedSettings().
- * Each key is a setting key (e.g., 'domId', 'tag', 'visibility').
- * Values are the resolved output — static values are bare, bindings
- * are evaluated to their current value, and unresolvable bindings are 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.
  */
-type ResolvedElementSettings = Record<string, ResolvedValue | null>;
+interface ResolvedElementSettings {
+  [key: string]: ResolvedValue | ResolvedElementAttribute[] | null;
+}