@webflow/designer-extension-typings 2.0.31 → 2.0.34

package/elements.d.ts

@@ -14,6 +14,11 @@ type FormState = 'normal' | 'success' | 'error';
 
 type FormMethod = 'get' | 'post';
 
+/**
+ * @deprecated Use `element.getSettings()` (returns `ElementSettingSummaries`) or
+ * `element.searchSettings()` (returns `Record<string, ElementSetting>`) instead.
+ * These generic APIs return the same form fields plus all other applicable settings.
+ */
 type FormSettings = {
   state: FormState;
   name: string;

package/instance-props.d.ts

@@ -1,25 +1,60 @@
 // Instance Props types
 
-interface LinkResolvedValue {
-  mode:
-    | 'url'
-    | 'page'
-    | 'pageSection'
-    | 'email'
-    | 'phone'
-    | 'file'
-    | 'collectionPage';
-  to?:
-    | string
-    | {pageId: string}
-    | {assetId: string}
-    | {fullElementId: {element: string; component: string}}
-    | {pageSlug: string};
+/** All public-facing link mode identifiers. */
+type LinkMode =
+  | 'url'
+  | 'page'
+  | 'pageSection'
+  | 'email'
+  | 'phone'
+  | 'file'
+  | 'collectionPage';
+
+interface LinkResolvedValueBase {
+  mode: LinkMode;
   openInNewTab?: boolean;
+  rel?: 'none' | 'preload' | 'prefetch' | 'prerender';
+}
+
+interface PageLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'page';
+  to?: {pageId: string};
+}
+
+interface PageSectionLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'pageSection';
+  to?: {fullElementId: FullElementId};
+}
+
+interface CollectionPageLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'collectionPage';
+  to?: {pageSlug: string};
+}
+
+interface EmailLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'email';
+  to?: string;
   emailSubject?: string;
-  rel?: string;
 }
 
+interface FileLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'file';
+  to?: {assetId: string};
+}
+
+interface GenericLinkResolvedValue extends LinkResolvedValueBase {
+  mode: 'url' | 'phone';
+  to?: string;
+}
+
+type LinkResolvedValue =
+  | PageLinkResolvedValue
+  | PageSectionLinkResolvedValue
+  | CollectionPageLinkResolvedValue
+  | EmailLinkResolvedValue
+  | FileLinkResolvedValue
+  | GenericLinkResolvedValue;
+
 interface VideoResolvedValue {
   src?: string;
   title?: string;
@@ -43,7 +78,7 @@ interface StaticPropValue {
   value: ResolvedValue | null;
 }
 
-type BindingPropValue =
+type BindingValue =
   | {
       sourceType: 'prop';
       propId: string;
@@ -79,31 +114,38 @@ type BindingPropValue =
   | {sourceType: 'conditional'}
   | {sourceType: 'legacy'};
 
-type InstancePropValue = StaticPropValue | BindingPropValue;
+type SettingValue = StaticPropValue | BindingValue;
 
-interface InstancePropDisplay {
+interface SettingDisplay {
   label: string;
   group: string | null;
   trueLabel?: string;
   falseLabel?: string;
+  /** Available choices for variant props. Each entry is a variant the component author defined. */
+  options?: Array<Pick<Variant, 'id' | 'name'>>;
 }
 
 interface InstanceProp {
   propId: string;
   valueType: BindableValueType;
   hasOverride: boolean;
-  value: InstancePropValue;
+  value: SettingValue;
   resolvedValue: ResolvedValue | null;
   defaultValue: ResolvedValue | null;
-  display: InstancePropDisplay;
+  display: SettingDisplay;
 }
 
 interface InstancePropSummary {
   propId: string;
-  value: ResolvedValue | BindingPropValue | null;
+  value: ResolvedValue | BindingValue | null;
   hasOverride: boolean;
 }
 
+interface ResolvedInstanceProp {
+  propId: string;
+  value: ResolvedValue | null;
+}
+
 interface SearchInstancePropsOptions {
   /** Filter to props that produce a specific value type (e.g., "string", "boolean") */
   valueType?: BindableValueType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webflow/designer-extension-typings",
-  "version": "2.0.31",
+  "version": "2.0.34",
   "license": "MIT",
   "description": "Typings for the Webflow Designer Extension API",
   "main": "",

package/styles.d.ts

@@ -14,69 +14,139 @@ interface Style {
   getName(): Promise<string>;
   /**
    * Retrieve the properties of the style.
-   * @param options - Options to filter properties based on breakpoints and pseudo classes / states.
-   * @returns CSS properties and their values for the given breakpoint and pseudo-state.
+   * @param options - Options to filter properties based on breakpoints, pseudo states, and component variants.
+   * @returns CSS properties and their values for the given options.
    * @example
    * ```ts
-   * let styleProperties = myStyle.getProperties();
-   * console.log("Style Properties:", styleProperties);
+   * // Get base properties
+   * let baseProperties = await myStyle.getProperties();
+   *
+   * // Get properties for a specific breakpoint and pseudo state
+   * let hoverProperties = await myStyle.getProperties({ breakpoint: 'medium', pseudo: 'hover' });
+   *
+   * // Get properties for a component variant
+   * let variantProperties = await myStyle.getProperties({ variantId: 'variant-dark' });
+   *
+   * // Combine variant with breakpoint and pseudo
+   * let combinedProperties = await myStyle.getProperties({
+   *   variantId: 'variant-dark',
+   *   breakpoint: 'medium',
+   *   pseudo: 'hover',
+   * });
    * ```
    */
-  getProperties(options?: BreakpointAndPseudo): Promise<PropertyMap>;
+  getProperties(options?: StyleOptions): Promise<PropertyMap>;
   /**
-   * Sets CSS properties for the Style at the given breakpoint and pseudo-state.
+   * Sets CSS properties for the Style.
    * @param props - The new properties to set for the style. You can use variables here as well.
-   * @param options - Options to filter properties based on breakpoints and pseudo classes / states.
+   * @param options - Options to target specific breakpoints, pseudo states, and component variants.
    * @example
    * ```ts
-   * myStyle.setProperties({ color: 'red', 'font-size': '16px' }, { breakpoint: 'main', pseudo: 'hover' });
+   * // Set base properties
+   * await myStyle.setProperties({ color: 'red', 'font-size': '16px' });
+   *
+   * // Set properties for breakpoint and pseudo state
+   * await myStyle.setProperties(
+   *   { color: 'blue', 'font-size': '18px' },
+   *   { breakpoint: 'medium', pseudo: 'hover' }
+   * );
+   *
+   * // Set properties for a component variant
+   * await myStyle.setProperties(
+   *   { color: 'white', 'background-color': 'black' },
+   *   { variantId: 'variant-dark' }
+   * );
+   *
+   * // Target variant by name instead of ID
+   * await myStyle.setProperties(
+   *   { 'font-weight': 'bold' },
+   *   { variantName: 'Dark Mode' }
+   * );
+   * ```
+   */
+  setProperties(props: PropertyMap, options?: StyleOptions): Promise<null>;
+  /**
+   * Removes multiple CSS properties from the Style.
+   * @param props - Array of property names to remove.
+   * @param options - Options to target specific breakpoints, pseudo states, and component variants.
+   * @example
+   * ```ts
+   * // Remove properties from base styles
+   * await myStyle.removeProperties(['color', 'font-size']);
+   *
+   * // Remove properties from a variant
+   * await myStyle.removeProperties(['color', 'background-color'], { variantId: 'variant-dark' });
    * ```
    */
-  setProperties(
-    props: PropertyMap,
-    options?: BreakpointAndPseudo
-  ): Promise<null>;
   removeProperties(
     props: Array<StyleProperty>,
-    options?: BreakpointAndPseudo
+    options?: StyleOptions
   ): Promise<null>;
   /**
    * Retrieve the value of a specific property of the style.
    * @param prop - The name of the property to retrieve.
-   * @param options - Options to get property based on breakpoints and pseudo classes / states.
-   * @returns Returns the value of a specific CSS property for the given breakpoint and pseudo-state, or null if the property does not exist.
+   * @param options - Options to target specific breakpoints, pseudo states, and component variants.
+   * @returns Returns the value of the CSS property, or null if not set.
    * @example
    * ```ts
-   * let color = myStyle.getProperty('color', { breakpoint: 'main', pseudo: 'hover' });
-   * let fontSize = myStyle.getProperty("fontSize");
-   * console.log("Font Size:", fontSize);
+   * // Get base property
+   * let color = await myStyle.getProperty('color');
+   *
+   * // Get property for breakpoint and pseudo state
+   * let hoverColor = await myStyle.getProperty('color', { breakpoint: 'medium', pseudo: 'hover' });
+   *
+   * // Get property for a component variant
+   * let variantColor = await myStyle.getProperty('color', { variantId: 'variant-dark' });
+   *
+   * // Get property from variant by name
+   * let namedVariantColor = await myStyle.getProperty('color', { variantName: 'Dark Mode' });
    * ```
    */
   getProperty<p extends StyleProperty>(
     prop: p,
-    options?: BreakpointAndPseudo
+    options?: StyleOptions
   ): Promise<null | PropertyMap[p]>;
   /**
-   * Sets a specific CSS property for the Style at the given breakpoint and pseudo-state.
+   * Sets a specific CSS property for the Style.
    * @param prop - The name of the property to set.
    * @param value - The new value to set for the property.
-   * @param options - Options to set property based on breakpoints and pseudo classes / states.
+   * @param options - Options to target specific breakpoints, pseudo states, and component variants.
    * @example
    * ```ts
-   * myStyle.setProperty('color', 'blue', { breakpoint: 'main', pseudo: 'hover' });
+   * // Set base property
+   * await myStyle.setProperty('color', 'red');
+   *
+   * // Set property for breakpoint and pseudo state
+   * await myStyle.setProperty('color', 'blue', { breakpoint: 'medium', pseudo: 'hover' });
+   *
+   * // Set property for a component variant
+   * await myStyle.setProperty('color', 'white', { variantId: 'variant-dark' });
+   *
+   * // Set property on variant by name
+   * await myStyle.setProperty('font-weight', 'bold', { variantName: 'Dark Mode' });
    * ```
    */
   setProperty<p extends StyleProperty>(
     prop: p,
     value: NonNullable<PropertyMap[p]>,
-    options?: BreakpointAndPseudo
-  ): Promise<null>;
-  removeProperty(
-    prop: StyleProperty,
-    options?: BreakpointAndPseudo
+    options?: StyleOptions
   ): Promise<null>;
   /**
-   * Removes all CSS properties from the Style.
+   * Removes a specific CSS property from the Style.
+   * @param prop - The name of the property to remove.
+   * @param options - Options to target specific breakpoints, pseudo states, and component variants.
+   * @example
+   * ```ts
+   * // Remove property from base styles
+   * await myStyle.removeProperty('color');
+   *
+   * // Remove property from a variant
+   * await myStyle.removeProperty('color', { variantId: 'variant-dark' });
+   * ```
+   */
+  removeProperty(prop: StyleProperty, options?: StyleOptions): Promise<null>;
+  /**
+   * Removes all CSS properties from the Style, including base styles and all variant styles.
    * @example
    * ```ts
    * await myStyle.removeAllProperties();
@@ -206,6 +276,20 @@ type BreakpointAndPseudo = {
   pseudo?: PseudoStateKey;
 };
 
+/**
+ * Options for targeting style properties by breakpoint, pseudo state, and component variant.
+ *
+ * When no options are provided, the base styles are targeted (main breakpoint, no pseudo, no variant).
+ * Specify variantId to target component variant styles.
+ */
+type StyleOptions = BreakpointAndPseudo & {
+  /**
+   * Component variant ID to target.
+   * Cannot be 'base' (omit options entirely for base styles).
+   */
+  variantId?: string;
+};
+
 type BreakpointId =
   | 'xxl'
   | 'xl'