@serenity-js/web 3.0.0-rc.8 → 3.0.0

package/lib/screenplay/interactions/Press.js

@@ -3,95 +3,101 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Press = void 0;
 const core_1 = require("@serenity-js/core");
 const io_1 = require("@serenity-js/core/lib/io");
-const input_1 = require("../../input");
 const abilities_1 = require("../abilities");
+const models_1 = require("../models");
 const PageElementInteraction_1 = require("./PageElementInteraction");
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  send a key press or a sequence of keys to a Web element.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to send a key press or a sequence of keys to a Web element.
  *
- *  *Please note*: On macOS, some keyboard shortcuts might not work with the [`devtools` protocol](https://webdriver.io/docs/automationProtocols/#devtools-protocol).
+ * **Note:** On macOS, some keyboard shortcuts might not work
+ * with the [`devtools` protocol](https://webdriver.io/docs/automationProtocols/#devtools-protocol).
  *
  *  For example:
- *  - to *copy*, instead of `Meta+C`, use `Control+Insert`
- *  - to *cut*, instead of `Meta+X`, use `Control+Delete`
- *  - to *paste*, instead of `Meta+V`, use `Shift+Insert`
+ *  - to *copy*, instead of {@apilink Key.Meta}+`C`, use {@apilink Key.Control}+{@apilink Key.Insert}
+ *  - to *cut*, instead of {@apilink Key.Meta}+`X`, use {@apilink Key.Control}+{@apilink Key.Delete}
+ *  - to *paste*, instead of {@apilink Key.Meta}+`V`, use {@apilink Key.Shift}+{@apilink Key.Insert}
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" name="example" id="example" />
- *  </form>
+ * ## Example widget
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ```html
+ * <form>
+ *   <input type="text" name="example" id="example" />
+ * </form>
+ * ```
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *  }
+ * ## Lean Page Object describing the widget
  *
- * @example <caption>Pressing keys</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Key, Press, Value } from '@serenity-js/webdriverio';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
  *
- *  actorCalled('Priyanka')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput),
- *          Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
- *      );
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
+ * }
+ * ```
  *
- * @see {@link Key}
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * ## Pressing keys
  *
- * @extends {ElementInteraction}
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Key, Press, Value } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Priyanka')
+ *   .attemptsTo(
+ *     Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink Key}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
+ *
+ * @group Activities
  */
 class Press extends PageElementInteraction_1.PageElementInteraction {
     /**
-     * @param {Answerable<Array<Key | string>>} keys
-     *  A sequence of one or more keys to press
-     */
-    constructor(keys) {
-        super((0, io_1.formatted) `#actor presses ${keys}`);
-        this.keys = keys;
-    }
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     * Instantiates an {@apilink Interaction|interaction}
+     * that instructs the {@apilink Actor|actor}
+     * to press a sequence of {@apilink Key|keys},
      *
-     * @param {...keys: Array<Answerable<Key | string | Key[] | string[]>>} keys
-     *  A sequence of one or more keys to press
+     * When no `field` is specified, the key sequence will be sent to the currently focused element,
+     * and if no element is focused - to the `document.body` to handle.
      *
-     * @returns {PressBuilder}
+     * @param keys
+     *  A sequence of one or more keys to press
      */
     static the(...keys) {
         return new Press(KeySequence.of(keys));
     }
-    in(field /* | Question<AlertPromise> | AlertPromise */) {
+    /**
+     * Send the key sequence to a specific element.
+     *
+     * @param field
+     */
+    in(field) {
         return new PressKeyInField(this.keys, field);
     }
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @param keys
+     *  A sequence of one or more keys to press
+     */
+    constructor(keys) {
+        super((0, core_1.d) `#actor presses ${keys}`);
+        this.keys = keys;
+    }
+    /**
+     * @inheritDoc
      */
     async performAs(actor) {
         const keys = await actor.answer(this.keys);
-        return abilities_1.BrowseTheWeb.as(actor).sendKeys(keys);
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+        return page.sendKeys(keys);
     }
 }
 exports.Press = Press;
@@ -104,34 +110,38 @@ class PressKeyInField extends PageElementInteraction_1.PageElementInteraction {
      *  Web element to send the keys to
      */
     constructor(keys, field /* todo | Question<AlertPromise> | AlertPromise */) {
-        super((0, io_1.formatted) `#actor presses ${keys} in ${field}`);
+        super((0, core_1.d) `#actor presses ${keys} in ${field}`, core_1.Interaction.callerLocation(3));
         this.keys = keys;
         this.field = field;
     }
+    /**
+     * @inheritDoc
+     */
     async performAs(actor) {
         const field = await this.resolve(actor, this.field);
         const keys = await actor.answer(this.keys);
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
         // fix for protractor
-        await abilities_1.BrowseTheWeb.as(actor).executeScript(
+        await page.executeScript(
         /* istanbul ignore next */
         function focus(element) {
             element.focus();
         }, await field.nativeElement());
-        return abilities_1.BrowseTheWeb.as(actor).sendKeys(keys);
+        return page.sendKeys(keys);
     }
 }
 /**
  * @package
  */
 class KeySequence extends core_1.Question {
+    static of(keys) {
+        return new KeySequence(keys);
+    }
     constructor(keys) {
         super();
         this.keys = keys;
         this.subject = KeySequence.describe(keys);
     }
-    static of(keys) {
-        return new KeySequence(keys);
-    }
     async answeredBy(actor) {
         const keys = await (0, io_1.asyncMap)(this.keys, key => actor.answer(key));
         return keys
@@ -139,23 +149,24 @@ class KeySequence extends core_1.Question {
             .filter(key => !!key);
     }
     /**
-     * @desc
-     *  Changes the description of this question's subject.
+     * Changes the description of this question's subject.
      *
-     * @param {string} subject
-     * @returns {Question<T>}
+     * @param subject
      */
     describedAs(subject) {
         this.subject = subject;
         return this;
     }
+    /**
+     * @inheritDoc
+     */
     toString() {
         return this.subject;
     }
     static describe(keys) {
         const prefix = keys.length === 1 ? 'key' : 'keys';
         const description = keys.reduce((acc, key, index) => {
-            const separator = input_1.Key.isKey(key) && key.isModifier
+            const separator = models_1.Key.isKey(key) && key.isModifier
                 ? '-'
                 : acc.separator;
             return {

package/lib/screenplay/interactions/Press.js.map

@@ -1 +1 @@
-{"version":3,"file":"Press.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Press.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Press.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Press.ts"],"names":[],"mappings":"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"}

package/lib/screenplay/interactions/RightClick.d.ts

@@ -2,88 +2,82 @@ import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@seren
 import { PageElement } from '../models';
 import { PageElementInteraction } from './PageElementInteraction';
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  perfom a right click on a given Web element.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to perfom a right click on a given {@apilink PageElement}.
  *
- *  This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
- *  on a given Web element, since it's not possible to interact with the standard context menu offered by your browser
+ * This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
+ * on a given Web element, since it's not possible to interact with the standard context menu offered by your browser.
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" id="field"
- *      oncontextmenu="showMenu(); return false;" />
+ * ## Example widget
  *
- *    <div id="context-menu" style="display:none">
- *      Custom context menu
- *    </div>
- *  </form>
+ * ```html
+ * <form>
+ *   <input type="text" id="field"
+ *     oncontextmenu="showMenu(); return false;" />
  *
- *  <script>
- *    function showMenu() {
- *      document.getElementById("context-menu").style.display = 'block';
- *    }
- *  </script>
+ *   <div id="context-menu" style="display:none">
+ *     Custom context menu
+ *   </div>
+ * </form>
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * <script>
+ *   function showMenu() {
+ *     document.getElementById("context-menu").style.display = 'block';
+ *   }
+ * </script>
+ * ```
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *      static exampleContextMenu = Target.the('example context menu')
- *          .located(by.id('context-menu'));
- *  }
+ * ## Lean Page Object describing the widget
  *
- * @example <caption>Right-click on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, RightClick, isVisible } from '@serenity-js/webdriverio';
- *  import { Ensure } from '@serenity-js/assertions';
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
  *
- *  actorCalled('Chloé')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          RightClick.on(Form.exampleInput),
- *          Ensure.that(Form.exampleContextMenu, isVisible()),
- *      );
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
  *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link isVisible}
+ *   static exampleContextMenu = () =>
+ *     PageElement.located(By.id('context-menu'))
+ *       .describedAs('example context menu')
+ * }
+ * ```
  *
- * @extends {ElementInteraction}
+ * ## Right-click on an element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { RightClick, isVisible } from '@serenity-js/web'
+ * import { Ensure } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Chloé')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     RightClick.on(Form.exampleInput()),
+ *     Ensure.that(Form.exampleContextMenu(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
+ *
+ * @group Activities
  */
 export declare class RightClick extends PageElementInteraction {
-    private readonly target;
+    private readonly pageElement;
     /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<PageElement>} target
-     *  The element to be right-clicked on
+     * Instantiates this {@apilink Interaction}.
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static on(target: Answerable<PageElement>): Interaction;
-    /**
-     * @param {Answerable<PageElement>} target
+     * @param pageElement
      *  The element to be right-clicked on
      */
-    constructor(target: Answerable<PageElement>);
+    static on(pageElement: Answerable<PageElement>): Interaction;
+    protected constructor(pageElement: Answerable<PageElement>);
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
 }
+//# sourceMappingURL=RightClick.d.ts.map

package/lib/screenplay/interactions/RightClick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RightClick.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/RightClick.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAK,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEhG,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBAAa,UAAW,SAAQ,sBAAsB;IAW5B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAVlD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW;IAI5D,SAAS,aAA8B,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC;IAI3E;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1E"}

package/lib/screenplay/interactions/RightClick.js

@@ -1,98 +1,91 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RightClick = void 0;
-const io_1 = require("@serenity-js/core/lib/io");
+const core_1 = require("@serenity-js/core");
 const PageElementInteraction_1 = require("./PageElementInteraction");
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  perfom a right click on a given Web element.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to perfom a right click on a given {@apilink PageElement}.
  *
- *  This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
- *  on a given Web element, since it's not possible to interact with the standard context menu offered by your browser
+ * This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
+ * on a given Web element, since it's not possible to interact with the standard context menu offered by your browser.
  *
- * @example <caption>Example widget</caption>
- *  <form>
- *    <input type="text" id="field"
- *      oncontextmenu="showMenu(); return false;" />
+ * ## Example widget
  *
- *    <div id="context-menu" style="display:none">
- *      Custom context menu
- *    </div>
- *  </form>
+ * ```html
+ * <form>
+ *   <input type="text" id="field"
+ *     oncontextmenu="showMenu(); return false;" />
  *
- *  <script>
- *    function showMenu() {
- *      document.getElementById("context-menu").style.display = 'block';
- *    }
- *  </script>
+ *   <div id="context-menu" style="display:none">
+ *     Custom context menu
+ *   </div>
+ * </form>
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * <script>
+ *   function showMenu() {
+ *     document.getElementById("context-menu").style.display = 'block';
+ *   }
+ * </script>
+ * ```
  *
- *  class Form {
- *      static exampleInput = Target.the('example input')
- *          .located(by.id('example'));
- *      static exampleContextMenu = Target.the('example context menu')
- *          .located(by.id('context-menu'));
- *  }
+ * ## Lean Page Object describing the widget
  *
- * @example <caption>Right-click on an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, RightClick, isVisible } from '@serenity-js/webdriverio';
- *  import { Ensure } from '@serenity-js/assertions';
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
  *
- *  actorCalled('Chloé')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          RightClick.on(Form.exampleInput),
- *          Ensure.that(Form.exampleContextMenu, isVisible()),
- *      );
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
  *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link isVisible}
+ *   static exampleContextMenu = () =>
+ *     PageElement.located(By.id('context-menu'))
+ *       .describedAs('example context menu')
+ * }
+ * ```
  *
- * @extends {ElementInteraction}
+ * ## Right-click on an element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { RightClick, isVisible } from '@serenity-js/web'
+ * import { Ensure } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Chloé')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     RightClick.on(Form.exampleInput()),
+ *     Ensure.that(Form.exampleContextMenu(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
+ *
+ * @group Activities
  */
 class RightClick extends PageElementInteraction_1.PageElementInteraction {
     /**
-     * @param {Answerable<PageElement>} target
-     *  The element to be right-clicked on
-     */
-    constructor(target) {
-        super((0, io_1.formatted) `#actor right-clicks on ${target}`);
-        this.target = target;
-    }
-    /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     * Instantiates this {@apilink Interaction}.
      *
-     * @param {Answerable<PageElement>} target
+     * @param pageElement
      *  The element to be right-clicked on
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
      */
-    static on(target) {
-        return new RightClick(target);
+    static on(pageElement) {
+        return new RightClick(pageElement);
+    }
+    constructor(pageElement) {
+        super((0, core_1.d) `#actor right-clicks on ${pageElement}`);
+        this.pageElement = pageElement;
     }
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {UsesAbilities & AnswersQuestions} actor
-     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *
-     * @returns {PromiseLike<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     * @inheritDoc
      */
     async performAs(actor) {
-        const element = await this.resolve(actor, this.target);
+        const element = await this.resolve(actor, this.pageElement);
         return element.rightClick();
     }
 }

package/lib/screenplay/interactions/RightClick.js.map

@@ -1 +1 @@
-{"version":3,"file":"RightClick.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/RightClick.ts"],"names":[],"mappings":";;;AACA,iDAAqD;AAGrD,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAa,UAAW,SAAQ,+CAAsB;IAclD;;;OAGG;IACH,YAA6B,MAA+B;QACxD,KAAK,CAAC,IAAA,cAAS,EAAC,0BAA2B,MAAO,EAAE,CAAC,CAAC;QAD7B,WAAM,GAAN,MAAM,CAAyB;IAE5D,CAAC;IAnBD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,MAA+B;QACrC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,OAAO,CAAC,UAAU,EAAE,CAAC;IAChC,CAAC;CACJ;AAxCD,gCAwCC"}
+{"version":3,"file":"RightClick.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/RightClick.ts"],"names":[],"mappings":";;;AAAA,4CAAgG;AAGhG,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAa,UAAW,SAAQ,+CAAsB;IAClD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAoC;QAC1C,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED,YAAuC,WAAoC;QACvE,KAAK,CAAC,IAAA,QAAC,EAAC,0BAA2B,WAAY,EAAE,CAAC,CAAC;QADhB,gBAAW,GAAX,WAAW,CAAyB;IAE3E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5D,OAAO,OAAO,CAAC,UAAU,EAAE,CAAC;IAChC,CAAC;CACJ;AAtBD,gCAsBC"}