@wix/editor 1.437.0 → 1.439.0

package/dist/esm/index.js

@@ -531,6 +531,19 @@ class ElementSDKShape extends BaseSDKShape {
     this.overriddenApplicationContext = overriddenApplicationContext;
     this.childPath = childPath;
   }
+  /**
+   * Retrieves the style definitions declared in the component's manifest,
+   * including `cssProperties` and `cssCustomProperties`.
+   *
+   * @returns Style definitions for the component.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const defs = await element.getStyleDefinitions();
+   * ```
+   */
   async getStyleDefinitions() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -539,6 +552,19 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Retrieves the current style values for the component.
+   *
+   * @returns Current `cssProperties` and `cssCustomProperties` values.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const styles = await element.getStyles();
+   * const bgColor = styles.cssProperties.backgroundColor;
+   * ```
+   */
   async getStyles() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -548,9 +574,11 @@ class ElementSDKShape extends BaseSDKShape {
     );
   }
   /**
-   * Sets style values for the element.
+   * Sets style values for the component.
    *
    * @example
+   * ```ts
+   * import { element } from '@wix/editor';
    * import { CssPropertyType } from '@wix/public-editor-platform-sdk';
    *
    * // Using enum (recommended):
@@ -562,6 +590,7 @@ class ElementSDKShape extends BaseSDKShape {
    * await element.setStyles({
    *   cssProperties: { 'color': '#fff' }
    * });
+   * ```
    */
   async setStyles(values = {}) {
     const privateAPI = await this.getPlatformPrivateAPI();
@@ -573,9 +602,11 @@ class ElementSDKShape extends BaseSDKShape {
     );
   }
   /**
-   * Removes style values from the element.
+   * Removes style values from the component.
    *
    * @example
+   * ```ts
+   * import { element } from '@wix/editor';
    * import { CssPropertyType } from '@wix/public-editor-platform-sdk';
    *
    * // Using enum (recommended):
@@ -587,6 +618,7 @@ class ElementSDKShape extends BaseSDKShape {
    * await element.removeStyles({
    *   cssPropertiesKeys: ['color']
    * });
+   * ```
    */
   async removeStyles(values = {}) {
     const privateAPI = await this.getPlatformPrivateAPI();
@@ -597,6 +629,18 @@ class ElementSDKShape extends BaseSDKShape {
       values
     );
   }
+  /**
+   * Retrieves the data item definitions declared in the component's manifest.
+   *
+   * @returns Data item definitions keyed by data item key.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const defs = await element.getDataDefinitions();
+   * ```
+   */
   async getDataDefinitions() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -605,6 +649,19 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Retrieves the current data values for the component.
+   *
+   * @typeParam T - Optional type parameter to define the expected structure of the returned data.
+   * @returns Current data values for the component.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const data = await element.getData();
+   * ```
+   */
   async getData() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -613,6 +670,24 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Retrieves the resolved value of a specific data item.
+   *
+   * Unlike {@link getData}, this method returns the fully resolved value
+   * for a single data item.
+   *
+   * @param options - Object containing the `dataItemKey` to resolve.
+   * @returns Resolved value for the specified data item.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const resolved = await element.getResolvedData({
+   *   dataItemKey: 'heroImage',
+   * });
+   * ```
+   */
   async getResolvedData({ dataItemKey }) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -624,6 +699,20 @@ class ElementSDKShape extends BaseSDKShape {
       }
     );
   }
+  /**
+   * Updates data values for the component. Only the specified data items
+   * are updated; other data items remain unchanged.
+   *
+   * @typeParam T - Optional type parameter to define the expected structure of the input data.
+   * @param values - Data item keys and their new values.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * await element.setData({ title: 'New Title', showButton: false });
+   * ```
+   */
   async setData(values) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -633,6 +722,18 @@ class ElementSDKShape extends BaseSDKShape {
       values
     );
   }
+  /**
+   * Retrieves the preset definitions declared in the component's manifest.
+   *
+   * @returns Preset definitions keyed by preset key.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const presets = await element.getPresetDefinitions();
+   * ```
+   */
   async getPresetDefinitions() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -641,6 +742,18 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Retrieves the currently applied preset for the component.
+   *
+   * @returns Key of the applied preset, or `null` if no preset is applied.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const preset = await element.getAppliedPreset();
+   * ```
+   */
   async getAppliedPreset() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -649,6 +762,19 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Applies a preset to the component. Applying a preset updates the component's
+   * styles and data to match the preset's defined defaults.
+   *
+   * @param options - Object containing the `key` of the preset to apply.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * await element.applyPreset({ key: 'minimal' });
+   * ```
+   */
   async applyPreset(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -658,6 +784,23 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Retrieves the display group definitions declared in the component's manifest.
+   *
+   * @param options - Optional filter by `groupType`.
+   * @returns Display group definitions for the component.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const groups = await element.getDisplayGroupDefinitions();
+   *
+   * const cssGroups = await element.getDisplayGroupDefinitions({
+   *   filter: { groupType: 'cssDataType' },
+   * });
+   * ```
+   */
   // TODO: group type should come from builder enum
   async getDisplayGroupDefinitions(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
@@ -668,6 +811,18 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Retrieves the display name of the component as defined in the manifest.
+   *
+   * @returns Component display name.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const name = await element.getDisplayName();
+   * ```
+   */
   async getDisplayName() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -676,6 +831,18 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Retrieves the currently active state for the component.
+   *
+   * @returns Key of the active state, or `null` if the default state is active.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const state = await element.getState();
+   * ```
+   */
   async getState() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -684,6 +851,21 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  /**
+   * Sets the active state for the component. Pass `null` to return to the
+   * default state.
+   *
+   * @param stateKey - State key to activate, or `null` for the default state.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * await element.setState('hover');
+   *
+   * await element.setState(null);
+   * ```
+   */
   async setState(stateKey) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -693,6 +875,18 @@ class ElementSDKShape extends BaseSDKShape {
       stateKey
     );
   }
+  /**
+   * Retrieves the state definitions declared in the component's manifest.
+   *
+   * @returns State definitions keyed by state key.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const states = await element.getStateDefinitions();
+   * ```
+   */
   async getStateDefinitions() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -701,19 +895,58 @@ class ElementSDKShape extends BaseSDKShape {
       this.childPath
     );
   }
+  // TODO: use type from the ManifestChangeDetection,
+  // but type should be moved to editor-platform-public-interfaces
   /**
-   * TODO: use type from the ManifestChangeDetection,
-   * but type should be moved to editor-platform-public-interfaces
+   * Subscribes to changes on the component. The callback is invoked whenever
+   * styles, data, state, preset, props, or manifest values change.
+   *
+   * @param callback - Callback that receives a patch with `type` and `value`.
+   * @returns Unsubscribe method.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const unsubscribe = await element.onChange((patch) => {
+   *   if (patch.type === 'data') {
+   *     console.log('Data changed:', patch.value);
+   *   }
+   * });
+   *
+   * unsubscribe();
+   * ```
    */
-  async onChange(cb) {
+  async onChange(callback) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
     return privateAPI.builderComponent.onChange(
       manifestContextId,
       this.childPath,
-      cb
+      callback
     );
   }
+  /**
+   * Opens the font picker for selecting a font family and weight.
+   *
+   * Pass `styleItemKey` to bind the picker to a manifest style item,
+   * or pass manual options to handle the selection via callbacks.
+   *
+   * @param params - `styleItemKey` for manifest binding, or manual picker options.
+   * @returns Selected font family and weight, or `undefined` if dismissed.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const font = await element.selectFont({ styleItemKey: 'headingFont' });
+   *
+   * const font = await element.selectFont({
+   *   selectedFontFamily: { family: 'Arial', weight: '400' },
+   *   onChange: (value) => console.log('Selected:', value),
+   * });
+   * ```
+   */
   async selectFont(params) {
     try {
       const privateAPI = await this.getPlatformPrivateAPI();
@@ -730,6 +963,26 @@ class ElementSDKShape extends BaseSDKShape {
     } catch (error) {
     }
   }
+  /**
+   * Opens the font family picker for selecting a font family without
+   * weight options. Works the same as {@link selectFont} but without
+   * the weight selector.
+   *
+   * @param params - `styleItemKey` for manifest binding, or manual picker options.
+   * @returns Selected font family, or `undefined` if dismissed.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const font = await element.selectFontFamily({ styleItemKey: 'bodyFont' });
+   *
+   * const font = await element.selectFontFamily({
+   *   selectedFontFamily: { family: 'Helvetica', weight: '400' },
+   *   onChange: (value) => console.log('Selected:', value.family),
+   * });
+   * ```
+   */
   async selectFontFamily(params) {
     try {
       const privateAPI = await this.getPlatformPrivateAPI();
@@ -746,6 +999,28 @@ class ElementSDKShape extends BaseSDKShape {
     } catch (error) {
     }
   }
+  /**
+   * Opens the media picker for selecting images, videos, or other media
+   * from the Wix Media Manager.
+   *
+   * Pass `dataItemKey` to bind the picker to a manifest data item,
+   * or pass manual options to configure the picker.
+   *
+   * @param params - `dataItemKey` for manifest binding, or manual picker options.
+   * @returns Selected media items.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const media = await element.selectMedia({ dataItemKey: 'heroImage' });
+   *
+   * const media = await element.selectMedia({
+   *   isMultiSelect: true,
+   *   category: 'image',
+   * });
+   * ```
+   */
   async selectMedia(params) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -755,6 +1030,27 @@ class ElementSDKShape extends BaseSDKShape {
       params
     );
   }
+  /**
+   * Opens the link picker for creating or editing a link.
+   *
+   * Pass `dataItemKey` to bind the picker to a manifest data item,
+   * or pass a `value` and optional `linkTypes` to configure manually.
+   *
+   * @param params - `dataItemKey` for manifest binding, or manual picker options.
+   * @returns Selected link, or `null`/`undefined` if dismissed.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const link = await element.selectLink({ dataItemKey: 'buttonLink' });
+   *
+   * const link = await element.selectLink({
+   *   value: currentLink,
+   *   options: { linkTypes: ['ExternalLink', 'PageLink'] },
+   * });
+   * ```
+   */
   async selectLink(params) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -764,6 +1060,30 @@ class ElementSDKShape extends BaseSDKShape {
       params
     );
   }
+  /**
+   * Opens the color picker for selecting a color.
+   *
+   * Pass `styleItemKey` to bind the picker to a manifest style item,
+   * or pass manual options to configure the picker.
+   *
+   * @param params - `styleItemKey` for manifest binding, or manual picker options.
+   * @returns Selected color value, or `undefined` if dismissed.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const color = await element.selectColor({ styleItemKey: 'backgroundColor' });
+   *
+   * const color = await element.selectColor({
+   *   initialValue: '#ff0000',
+   *   mode: ['solid', 'gradient'],
+   *   showOpacity: true,
+   *   onChange: (color) => console.log('Preview:', color),
+   *   onApply: (color) => console.log('Applied:', color),
+   * });
+   * ```
+   */
   async selectColor(params) {
     const privateAPI = await this.getPlatformPrivateAPI();
     try {
@@ -777,6 +1097,23 @@ class ElementSDKShape extends BaseSDKShape {
     } catch (error) {
     }
   }
+  /**
+   * Opens the background picker for selecting a background fill
+   * (color, gradient, or image).
+   *
+   * @param options - Background picker configuration.
+   * @returns Selected background fill value.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const bg = await element.selectBackground({
+   *   initialValue: { backgroundColor: '#fff', backgroundImage: '' },
+   *   onChange: (value) => console.log('Preview:', value),
+   * });
+   * ```
+   */
   async selectBackground(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -786,6 +1123,31 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Opens the font weight picker for selecting a font weight for a specified
+   * font family.
+   *
+   * Pass manifest style item keys to bind the picker, or pass manual
+   * options to handle the selection via callbacks.
+   *
+   * @param params - Manifest style item keys, or manual picker options.
+   * @returns Selected font weight.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const weight = await element.selectFontWeight({
+   *   fontFamilyStyleItemKey: 'headingFontFamily',
+   *   fontWeightStyleItemKey: 'headingFontWeight',
+   * });
+   *
+   * const weight = await element.selectFontWeight({
+   *   fontFamily: { family: 'Arial', weight: '400' },
+   *   onChange: (value) => console.log('Selected weight:', value.weight),
+   * });
+   * ```
+   */
   async selectFontWeight(params) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -797,6 +1159,24 @@ class ElementSDKShape extends BaseSDKShape {
       )
     };
   }
+  /**
+   * Opens the text theme picker for selecting a predefined text theme
+   * (a combination of font and color from the site's theme).
+   *
+   * @param params - Text theme picker configuration.
+   * @param params.target - HTML element to anchor the picker to.
+   * @param params.initialValue - Initial font and color values.
+   * @returns Selected text theme.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const theme = await element.selectTextTheme({
+   *   initialValue: { font: 'Heading 1', color: '#333' },
+   * });
+   * ```
+   */
   async selectTextTheme(params) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -805,6 +1185,20 @@ class ElementSDKShape extends BaseSDKShape {
       params
     );
   }
+  /**
+   * Retrieves the currently selected index in an array items data group.
+   *
+   * @param options - Specify `arrayItemsDisplayGroupKey` if the component
+   *   has multiple array item groups.
+   * @returns Index of the currently selected array item.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const index = await element.getArrayItemsSelectedIndex();
+   * ```
+   */
   async getArrayItemsSelectedIndex(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -814,6 +1208,19 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Sets the selected index in an array items data group.
+   *
+   * @param options - Object containing the `index` to select, and optionally
+   *   `arrayItemsDisplayGroupKey` if there are multiple array item groups.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * await element.setArrayItemsSelectedIndex({ index: 2 });
+   * ```
+   */
   async setArrayItemsSelectedIndex(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -823,6 +1230,19 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Resets the selected index in an array items data group to the default.
+   *
+   * @param options - Specify `arrayItemsDisplayGroupKey` if the component
+   *   has multiple array item groups.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * await element.resetArrayItemsSelectedIndex();
+   * ```
+   */
   async resetArrayItemsSelectedIndex(options) {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();
@@ -832,6 +1252,18 @@ class ElementSDKShape extends BaseSDKShape {
       options
     );
   }
+  /**
+   * Retrieves the BI (Business Intelligence) token for the component.
+   *
+   * @returns BI token string.
+   *
+   * @example
+   * ```ts
+   * import { element } from '@wix/editor';
+   *
+   * const token = await element.getBiToken();
+   * ```
+   */
   async getBiToken() {
     const privateAPI = await this.getPlatformPrivateAPI();
     const manifestContextId = await this.getRequiredManifestContextId();