@bitrix24/b24jssdk/dist/esm/frame/placement.mjs

Bitrix24 REST API JavaScript SDK

/**
 * @package @bitrix24/b24jssdk
 * @version 3.0.0
 * @copyright (c) 2026 Bitrix24
 * @license MIT
 * @see https://github.com/bitrix24/b24jssdk
 * @see https://bitrix24.github.io/b24jssdk/
 */
import { normalisePlacementOptions } from './_placement-options.mjs';
import { Type } from '../tools/type.mjs';
import { MessageCommands } from './message/commands.mjs';

var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
class PlacementManager {
  static {
    __name(this, "PlacementManager");
  }
  #messageManager;
  #placement = "";
  #options = Object.freeze({});
  constructor(messageManager) {
    this.#messageManager = messageManager;
  }
  /**
   * Initializes the data received from the parent window message.
   * @param data
   */
  initData(data) {
    this.#placement = data.PLACEMENT || "DEFAULT";
    this.#options = normalisePlacementOptions(data.PLACEMENT_OPTIONS);
    return this;
  }
  /**
   * Symlink on `placement`
   * For backward compatibility
   */
  get title() {
    return this.#placement;
  }
  get placement() {
    return this.#placement;
  }
  get isDefault() {
    return this.placement === "DEFAULT";
  }
  /**
   * The parameters this frame was opened with, always as a frozen object.
   *
   * Values are `unknown`, so read one by narrowing it rather than by trusting
   * it. That is the whole point of the type: this data crosses a `postMessage`
   * boundary from the portal, and the previous `any` switched off every check on
   * it — `options.payload.id` compiled and was `undefined` at run time (#485).
   *
   * ```ts
   * const place = $b24.placement.options['place']
   * if ('string' === typeof place) {
   *   route(place)
   * }
   * ```
   *
   * **Key case is the portal's choice, not a convention.** For the default
   * placement the object *is* the frame URL's query string, so the keys are
   * whatever the opener wrote; for a registered placement they are whatever the
   * application stored at bind time. Do not assume either case.
   *
   * Three shapes arrive on the wire — an object, a JSON string, and `''` when
   * nothing was supplied — and all three are normalised before they get here, so
   * this is never `undefined` and needs no `?.`. See `_placement-options.ts` for
   * where each one comes from.
   */
  get options() {
    return this.#options;
  }
  /**
   * Whether the frame is running as a slider.
   *
   * Reads `IFRAME` out of {@link options}, and compares against the **string**
   * `'Y'` rather than a boolean because on the default-placement path that value
   * came from the frame URL's query string (`marketplace.js` opens the frame with
   * `IFRAME=Y`).
   *
   * **Do not use it to decide whether placement data arrived at all.** It is
   * computed from the very data whose absence you would be diagnosing, so it goes
   * quiet exactly when you need it.
   */
  get isSliderMode() {
    return this.#options["IFRAME"] === "Y";
  }
  /**
   * Get Information About the JS Interface of the Current Embedding Location
   *
   * @return {Promise<any>}
   *
   * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-get-interface.html
   */
  async getInterface() {
    return this.#messageManager.send(
      MessageCommands.getInterface,
      {
        isSafely: true
      }
    );
  }
  /**
   * Set Up the Interface Event Handler
   * @param {string} eventName
   * @param {(...args: any[]) => void} callBack
   * @return {Promise<any>}
   *
   * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-bind-event.html
   */
  async bindEvent(eventName, callBack) {
    return this.#messageManager.send(
      MessageCommands.placementBindEvent,
      {
        event: eventName,
        callBack,
        isSafely: true
      }
    );
  }
  async call(command, parameters = {}) {
    if (command === "setValue" && !Type.isString(parameters?.["value"])) {
      throw new TypeError(
        "placement.call('setValue', { value }) expects `value` to be a JSON-serialized string. Use placement.setValue(value) to serialize automatically, or call JSON.stringify yourself."
      );
    }
    return this.#messageManager.send(
      command,
      {
        ...parameters,
        isSafely: true,
        isRawValue: ["setValue"].includes(command)
      }
    );
  }
  /**
   * Set Value for the Current Embedding Location
   *
   * Convenience wrapper around `placement.call('setValue', ...)` that handles
   * JSON serialization. Pass any value (string, number, boolean, object, array)
   * — it will be serialized via `JSON.stringify` before being sent to the
   * parent window, which performs `JSON.parse` on receipt.
   *
   * @param { unknown } value Any JSON-serializable value
   * @return { Promise<any> }
   *
   * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-call.html
   *
   * @example
   * await b24.placement.setValue('test')
   * await b24.placement.setValue({ id: 1, title: 'demo' })
   */
  async setValue(value) {
    return this.#messageManager.send(
      "setValue",
      {
        value: JSON.stringify(value),
        isSafely: true,
        isRawValue: true
      }
    );
  }
  /**
   * Set Up the Interface Event Handler
   * @param {string} command
   * @param {null | string | Record<string, any>} parameters
   * @param {(...args: any[]) => void} callBack
   *
   * @return {Promise<any>}
   */
  async callCustomBind(command, parameters = null, callBack) {
    let options = {};
    if (Type.isString(parameters)) {
      options["singleOption"] = parameters;
    } else if (Type.isObjectLike(parameters)) {
      options = { ...parameters };
    }
    return this.#messageManager.send(
      command,
      {
        ...options,
        callBack,
        isSafely: true
      }
    );
  }
}

export { PlacementManager };
//# sourceMappingURL=placement.mjs.map