@wix/editor 1.438.0 → 1.439.0

package/dist/types/index.d.ts

@@ -133,31 +133,88 @@ declare class ModalsSDKShape extends BaseSDKShape {
 }
 declare const _default$6: ModalsSDKShape & _wix_sdk_types.HostModule<ModalsSDKShape, _wix_sdk_types.Host>;
 
+/** Represents a font family and its weight. */
 interface IFontFamily {
+    /** The font family name. For example, 'Arial' or 'Helvetica Neue'. */
     family: string;
+    /** The font weight. For example, '400' or 'bold'. */
     weight: string;
 }
+/** Represents a font weight value. */
 interface IFontWeight {
+    /** The font weight. For example, '400' or 'bold'. */
     weight: string;
 }
+/** Combination of font family and weight properties. */
 type IFontFamilyAndWeight = IFontFamily & IFontWeight;
 type ISelectLinkSharedOptions = {
+    /** Identifier for the origin of the link selection (used for BI tracking). */
     origin?: string;
 };
+/** Options for positioning a picker panel relative to a target element. */
 type IPanelOptions = {
+    /** Where to place the picker panel relative to the target element. */
     placement?: 'top' | 'bottom' | 'top-start' | 'bottom-start' | 'top-end' | 'bottom-end';
+    /** Vertical offset in pixels to shift the panel from its computed position. */
     YShift?: number;
 };
+/**
+ * Methods for interacting with a component from a custom panel.
+ *
+ * Import `element` from `@wix/editor` to read and update styles, data,
+ * presets, and states, and to open editor pickers.
+ *
+ * @example
+ * ```tsx
+ * import { element } from '@wix/editor';
+ *
+ * export default function MyPanel() {
+ *   const handleClick = async () => {
+ *     const data = await element.getData();
+ *     await element.setData({ title: 'Updated!' });
+ *   };
+ *   return <button onClick={handleClick}>Update Title</button>;
+ * }
+ * ```
+ */
 declare class ElementSDKShape extends BaseSDKShape {
     protected overriddenApplicationContext: Promise<ApplicationContext> | null;
     private childPath;
     constructor(overriddenApplicationContext?: Promise<ApplicationContext> | null, childPath?: number[]);
+    /**
+     * 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();
+     * ```
+     */
     getStyleDefinitions(): Promise<ElementStyleDefinitions>;
+    /**
+     * 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;
+     * ```
+     */
     getStyles(): Promise<ElementStyles>;
     /**
-     * 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):
@@ -169,12 +226,15 @@ declare class ElementSDKShape extends BaseSDKShape {
      * await element.setStyles({
      *   cssProperties: { 'color': '#fff' }
      * });
+     * ```
      */
     setStyles(values?: ElementStylesUpdate): Promise<void>;
     /**
-     * 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):
@@ -186,36 +246,236 @@ declare class ElementSDKShape extends BaseSDKShape {
      * await element.removeStyles({
      *   cssPropertiesKeys: ['color']
      * });
+     * ```
      */
     removeStyles(values?: ElementStylesRemoval): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
     getDataDefinitions(): Promise<ElementDataDefinitions>;
+    /**
+     * 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();
+     * ```
+     */
     getData<T extends ElementData = ElementData>(): Promise<T>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
     getResolvedData({ dataItemKey }: {
         dataItemKey: string;
     }): Promise<any>;
+    /**
+     * 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 });
+     * ```
+     */
     setData<T extends ElementData = ElementData>(values: ElementDataInput<T>): Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
     getPresetDefinitions(): Promise<ElementPresetDefinitions>;
+    /**
+     * 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();
+     * ```
+     */
     getAppliedPreset(): Promise<any>;
+    /**
+     * 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' });
+     * ```
+     */
     applyPreset(options: {
         key: string;
     }): Promise<any>;
+    /**
+     * 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' },
+     * });
+     * ```
+     */
     getDisplayGroupDefinitions(options?: {
         filter?: {
             groupType?: string;
         };
     }): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     getDisplayName(): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     getState(): Promise<any>;
+    /**
+     * 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);
+     * ```
+     */
     setState(stateKey: string | null): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     getStateDefinitions(): Promise<ElementStateDefinitions>;
     /**
-     * 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();
+     * ```
      */
-    onChange(cb: (patch: {
+    onChange(callback: (patch: {
         type: 'styles' | 'data' | 'state' | 'preset' | 'props' | 'manifest';
         value: unknown;
     }) => void): Promise<() => {}>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
     selectFont(params: {
         styleItemKey: string;
     } | {
@@ -225,6 +485,26 @@ declare class ElementSDKShape extends BaseSDKShape {
         onChange?: (value: IFontFamilyAndWeight) => void;
         onPreview?: (value: IFontFamilyAndWeight) => void;
     }): Promise<any>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
     selectFontFamily(params: {
         styleItemKey: string;
     } | {
@@ -234,12 +514,55 @@ declare class ElementSDKShape extends BaseSDKShape {
         onChange?: (value: IFontFamily) => void;
         onPreview?: (value: IFontFamily) => void;
     }): Promise<any>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
     selectMedia(params: {
         dataItemKey: string;
     } | {
         isMultiSelect?: boolean;
         category?: string;
     }): Promise<any>;
+    /**
+     * 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'] },
+     * });
+     * ```
+     */
     selectLink(params: {
         dataItemKey: string;
         options?: ISelectLinkSharedOptions;
@@ -249,6 +572,30 @@ declare class ElementSDKShape extends BaseSDKShape {
             linkTypes?: string[];
         };
     }): Promise<ElementLink | null | undefined>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
     selectColor(params: {
         styleItemKey: string;
     } | {
@@ -270,7 +617,49 @@ declare class ElementSDKShape extends BaseSDKShape {
         onClose?: () => void;
         onCancel?: () => void;
     }): Promise<any>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
     selectBackground(options: BackgroundPickerOptions): Promise<any>;
+    /**
+     * 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),
+     * });
+     * ```
+     */
     selectFontWeight(params: {
         fontFamilyStyleItemKey: string;
         fontWeightStyleItemKey: string;
@@ -281,6 +670,24 @@ declare class ElementSDKShape extends BaseSDKShape {
         target?: HTMLElement;
         onChange?: (value: IFontWeight) => void;
     }): Promise<IFontWeight>;
+    /**
+     * 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' },
+     * });
+     * ```
+     */
     selectTextTheme(params: {
         target?: HTMLElement;
         initialValue?: {
@@ -288,16 +695,68 @@ declare class ElementSDKShape extends BaseSDKShape {
             color?: string;
         };
     }): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     getArrayItemsSelectedIndex(options?: {
         arrayItemsDisplayGroupKey?: string;
     }): Promise<any>;
+    /**
+     * 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 });
+     * ```
+     */
     setArrayItemsSelectedIndex(options: {
         index: number;
         arrayItemsDisplayGroupKey?: string;
     }): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     resetArrayItemsSelectedIndex(options?: {
         arrayItemsDisplayGroupKey?: string;
     }): Promise<any>;
+    /**
+     * 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();
+     * ```
+     */
     getBiToken(): Promise<string>;
 }
 declare const _default$5: ElementSDKShape & _wix_sdk_types.HostModule<ElementSDKShape, _wix_sdk_types.Host>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/editor",
-  "version": "1.438.0",
+  "version": "1.439.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Editor Platform <editor-platform-dev@wix.com>",
@@ -20,11 +20,12 @@
   "unpkg": true,
   "scripts": {
     "start": "exit 0",
-    "build": "yarn typecheck && rollup -c",
+    "build": "yarn typecheck && rollup -c && yarn docs",
     "test": "jest test",
     "lint": "prettier --check ./src",
     "lint:fix": "prettier --write ./src",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "docs": "docs-ts-model --entryPoint src/element/index.ts"
   },
   "lint-staged": {
     "*.{js,ts}": "yarn lint"
@@ -41,6 +42,7 @@
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.3.1",
+    "@wix/docs-ts-model": "^1.54.0",
     "@wix/editor-platform-host-integration-apis": "^1.0.0",
     "esbuild": "^0.25.5",
     "eslint": "^8.57.1",
@@ -55,7 +57,11 @@
   "wix": {
     "artifact": {
       "groupId": "com.wixpress",
-      "artifactId": "editor-platform-sdk"
+      "artifactId": "editor-platform-sdk",
+      "targets": {
+        "static": true,
+        "build-docs": true
+      }
     },
     "validations": {
       "postDependenciesBuild": [
@@ -63,5 +69,5 @@
       ]
     }
   },
-  "falconPackageHash": "fa1392f4042f30c975437b45c89c9a2142d6e0698b9b32231753580d"
+  "falconPackageHash": "c6d3df8731765afd56fc97de9f4b297519474d9ec572f91f230f50af"
 }