@wix/editor 1.438.0 → 1.440.0

package/dist/statics/index.js

@@ -531,6 +531,19 @@
       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 @@
         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 @@
       );
     }
     /**
-     * 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 @@
      * await element.setStyles({
      *   cssProperties: { 'color': '#fff' }
      * });
+     * ```
      */
     async setStyles(values = {}) {
       const privateAPI = await this.getPlatformPrivateAPI();
@@ -573,9 +602,11 @@
       );
     }
     /**
-     * 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 @@
      * await element.removeStyles({
      *   cssPropertiesKeys: ['color']
      * });
+     * ```
      */
     async removeStyles(values = {}) {
       const privateAPI = await this.getPlatformPrivateAPI();
@@ -597,6 +629,18 @@
         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 @@
         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 @@
         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 @@
         }
       );
     }
+    /**
+     * 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 @@
         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 @@
         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 @@
         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 @@
         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 @@
         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 @@
         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 @@
         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 @@
         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 @@
         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 @@
       } 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 @@
       } 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 @@
         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 @@
         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 @@
       } 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 @@
         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 @@
         )
       };
     }
+    /**
+     * 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 @@
         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 @@
         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 @@
         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 @@
         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();