@webflow/designer-extension-typings 2.0.33 → 2.0.34

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

@@ -249,6 +249,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 +303,19 @@ interface Component {
    * @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>;
 }
 
 /**

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;
+}