@wix/editor 1.438.0 → 1.440.0

package/dist/cjs/index.js

@@ -533,6 +533,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();
@@ -541,6 +554,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();
@@ -550,9 +576,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):
@@ -564,6 +592,7 @@ class ElementSDKShape extends BaseSDKShape {
    * await element.setStyles({
    *   cssProperties: { 'color': '#fff' }
    * });
+   * ```
    */
   async setStyles(values = {}) {
     const privateAPI = await this.getPlatformPrivateAPI();
@@ -575,9 +604,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):
@@ -589,6 +620,7 @@ class ElementSDKShape extends BaseSDKShape {
    * await element.removeStyles({
    *   cssPropertiesKeys: ['color']
    * });
+   * ```
    */
   async removeStyles(values = {}) {
     const privateAPI = await this.getPlatformPrivateAPI();
@@ -599,6 +631,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();
@@ -607,6 +651,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();
@@ -615,6 +672,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();
@@ -626,6 +701,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();
@@ -635,6 +724,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();
@@ -643,6 +744,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();
@@ -651,6 +764,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();
@@ -660,6 +786,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();
@@ -670,6 +813,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();
@@ -678,6 +833,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();
@@ -686,6 +853,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();
@@ -695,6 +877,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();
@@ -703,19 +897,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();
@@ -732,6 +965,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();
@@ -748,6 +1001,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();
@@ -757,6 +1032,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();
@@ -766,6 +1062,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 {
@@ -779,6 +1099,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();
@@ -788,6 +1125,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();
@@ -799,6 +1161,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();
@@ -807,6 +1187,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();
@@ -816,6 +1210,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();
@@ -825,6 +1232,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();
@@ -834,6 +1254,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();