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

package/lib/screenplay/interactions/ExecuteScript.js

@@ -6,204 +6,203 @@ const io_1 = require("@serenity-js/core/lib/io");
 const model_1 = require("@serenity-js/core/lib/model");
 const abilities_1 = require("../abilities");
 /**
- * @desc
- *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
- *  execute a script within the context of the current browser window.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to execute a script within the context of the current browser tab.
  *
- *  Please see the tests below for usage examples.
+ * ## Learn more
  *
- * @see {@link LastScriptExecution.result}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink LastScriptExecution.result}
+ *
+ * @group Activities
  */
 class ExecuteScript {
     /**
-     * @desc
-     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
-     *  configured to load a script from `sourceUrl`.
+     * Instantiates a version of this {@apilink Interaction}
+     * configured to load a script from `sourceUrl`.
      *
-     * @param {string} sourceUrl
+     * @param sourceUrl
      *  The URL to load the script from
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
      */
     static from(sourceUrl) {
         return new ExecuteScriptFromUrl(sourceUrl);
     }
     /**
-     * @desc
-     *  Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.
-     *  The script fragment will be executed as the body of an anonymous function.
-     *  If the script is provided as a function object, that function will be converted to a string for injection
-     *  into the target window.
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to execute an asynchronous script within the context of the current browser tab.
      *
-     *  Any arguments provided in addition to the script will be included as script arguments and may be referenced
-     *  using the `arguments` object. Arguments may be a `boolean`, `number`, `string`
-     *  or {@link Target} (`Answerable<Element>`).
-     *  Arrays and objects may also be used as script arguments as long as each item adheres
-     *  to the types previously mentioned.
+     * The script fragment will be executed as the body of an anonymous function.
+     * If the script is provided as a function object, that function will be converted to a string for injection
+     * into the target window.
      *
-     *  Unlike executing synchronous JavaScript with {@link ExecuteScript#sync},
-     *  scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
+     * Any arguments provided in addition to the script will be included as script arguments and may be referenced
+     * using the `arguments` object. Arguments may be a `boolean`, `number`, `string`
+     * or {@apilink PageElement}.
+     * Arrays and objects may also be used as script arguments as long as each item adheres
+     * to the types previously mentioned.
      *
-     *  This callback will always be injected into the executed function as the last argument,
-     *  and thus may be referenced with `arguments[arguments.length - 1]`.
+     * Unlike executing synchronous JavaScript with {@apilink ExecuteScript.sync},
+     * scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
      *
-     *  If the script invokes the `callback` with a return value, this will be made available
-     *  via the {@link LastScriptExecution.result}.
+     * This callback will always be injected into the executed function as the last argument,
+     * and thus may be referenced with `arguments[arguments.length - 1]`.
      *
-     *  **Please note** that in order to signal an error in the `script` you need to throw an {@link Error}
-     *  instead of passing it to the callback function.
+     * If the script invokes the `callback` with a return value, this will be made available
+     * via the {@apilink LastScriptExecution.result}.
      *
-     * @example <caption>Executing an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * **Please note** that in order to signal an error in the `script` you need to throw an {@apilink Error}
+     * instead of passing it to the callback function.
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var callback = arguments[arguments.length - 1];
+     * #### Executing an async script
      *
-     *          // do stuff
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     *          callback(result)
-     *      `)
-     *  );
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var callback = arguments[arguments.length - 1]
      *
-     * @example <caption>Passing arguments to an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     *     // do stuff
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var name = arguments[0];
-     *          var age = arguments[1];
-     *          var callback = arguments[arguments.length - 1];
+     *     callback(result)
+     *   `)
+     * )
+     * ```
      *
-     *          // do stuff
+     * #### Passing arguments to an async script
      *
-     *          callback(result)
-     *      `).withArguments('Bob', 24)
-     *  );
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     * @example <caption>Passing Target arguments to an async script</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var name = arguments[0];
+     *     var age = arguments[1];
+     *     var callback = arguments[arguments.length - 1]
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(`
-     *          var header = arguments[0];    // Target gets converted to a WebElement
-     *          var callback = arguments[arguments.length - 1];
+     *     // do stuff
      *
-     *          callback(header.innerText)
-     *      `).withArguments(Target.the('header').located(by.css('h1')))
-     *  );
+     *     callback(result)
+     *   `).withArguments('Bob', 24)
+     * )
+     * ```
      *
-     * @example <caption>Executing async script as function</caption>
-     *  import { ExecuteScript } from '@serenity-js/webdriverio';
+     * #### Passing Target arguments to an async script
      *
-     *  actor.attemptsTo(
-     *      ExecuteScript.async(function getText(header, callback) {
-     *          callback(header.innerText)
-     *      }).withArguments(Target.the('header').located(by.css('h1')))
-     *  );
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     * @param {string | Function} script
-     *  The script to be executed
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(`
+     *     var header = arguments[0]        // PageElement object gets converted to a WebElement
+     *     var callback = arguments[arguments.length - 1]
+     *
+     *     callback(header.innerText)
+     *   `).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     * )
+     * ```
+     *
+     * #### Executing async script as function
      *
-     * @returns {ExecuteScriptWithArguments}
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
      *
-     * @see {@link LastScriptExecution.result}
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getText(header, callback) {
+     *     callback(header.innerText)
+     *   }).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink LastScriptExecution.result}
+     *
+     * @param script
+     *  The script to be executed
      */
     static async(script) {
-        return new ExecuteAsynchronousScript(script);
+        return new ExecuteAsynchronousScript(`#actor executes an asynchronous script`, script);
     }
     /**
-     * @desc
-     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
-     *  execute a synchronous script in the context of the currently selected frame or window.
-     *
-     *  If the script returns a value, it will be made available via {@link LastScriptExecution.result}.
-     *
-     * @example <caption>Executing a sync script as string and reading the result</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { BrowseTheWeb, ExecuteScript, LastScriptExecution } from '@serenity-js/webdriverio';
-     *  import { Ensure, includes } from '@serenity-js/assertions';
-     *
-     *  actorCalled('Joseph')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          ExecuteScript.sync('return navigator.userAgent'),
-     *          Ensure.that(LastScriptExecution.result<string>(), includes('Chrome')),
-     *      );
-     *
-     * @example <caption>Executing a sync script as function and reading the result</caption>
-     *  import { actorCalled } from '@serenity-js/core';
-     *  import { by, BrowseTheWeb, Enter, ExecuteScript, LastScriptExecution, Target } from '@serenity-js/webdriverio';
-     *
-     *  const someOfferField      = Target.the('offer code').located(by.id('offer-code'));
-     *  const applyOfferCodeField = Target.the('apply offer field').located(by.id('apply-offer-code'));
-     *
-     *  actorCalled('Joseph')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          // inject JavaScript to read some property of an element
-     *          ExecuteScript.sync(function getValue(element) {
-     *              return element.value;
-     *          }).withArguments(someOfferField),
-     *
-     *          // use LastScriptExecution.result() to read the value
-     *          // returned from the injected script
-     *          // and pass it to another interaction
-     *          Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
-     *      );
-     *
-     * @param {string | Function} script
-     *  The script to be executed
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to execute a synchronous script within the context of the current browser tab.
+     *
+     * If the script returns a value, it will be made available via {@apilink LastScriptExecution.result}.
+     *
+     * #### Executing a sync script as string and reading the result
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, LastScriptExecution } from '@serenity-js/web'
+     * import { Ensure, includes } from '@serenity-js/assertions'
+     *
+     * await actorCalled('Joseph')
+     *   .attemptsTo(
+     *     ExecuteScript.sync('return navigator.userAgent'),
+     *     Ensure.that(LastScriptExecution.result<string>(), includes('Chrome')),
+     *   )
+     * ```
+     *
+     * #### Executing a sync script as function and reading the result
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { By, Enter, ExecuteScript, LastScriptExecution, PageElement } from '@serenity-js/web'
+     *
+     * const someOfferField = () =>
+     *   PageElement.located(By.id('offer-code'))
+     *     .describedAs('offer code')
+     *
+     * const applyOfferCodeField = () =>
+     *   PageElement.located(By.id('apply-offer-code'))
+     *     .describedAs('apply offer field')
+     *
+     * await actorCalled('Joseph')
+     *   .attemptsTo(
+     *     // inject JavaScript to read some property of an element
+     *     ExecuteScript.sync(function getValue(element) {
+     *         return element.value;
+     *     }).withArguments(someOfferField),
+     *
+     *     // use LastScriptExecution.result() to read the value
+     *     // returned from the injected script
+     *     // and pass it to another interaction
+     *     Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
+     *   )
+     * ```
      *
-     * @returns {ExecuteScriptWithArguments}
+     * #### Learn more
+     * - {@apilink LastScriptExecution.result}
      *
-     * @see {@link LastScriptExecution.result}
+     * @param script
+     *  The script to be executed
      */
     static sync(script) {
-        return new ExecuteSynchronousScript(script);
+        return new ExecuteSynchronousScript(`#actor executes a synchronous script`, script);
     }
 }
 exports.ExecuteScript = ExecuteScript;
 /**
- * @desc
- *  Allows for a script to be executed to be parametrised.
- *
- *  **Please note** that the arguments can be both synchronous and asynchronous {@link @serenity-js/core/lib/screenplay~Question}s
- *  as well as regular static values.
- *
- * @abstract
+ * Allows for a script to be executed to be parametrised.
  *
- * @see {@link ExecuteScript}
+ * ## Learn more
+ * -  {@apilink ExecuteScript}
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * @group Activities
  */
 class ExecuteScriptWithArguments extends core_1.Interaction {
-    /**
-     * @param {string | Function} script
-     *  The script to be executed
-     *
-     * @param {Array<Answerable<any>>} args
-     *  Arguments to parametrise the script with
-     */
-    constructor(script, // eslint-disable-line @typescript-eslint/ban-types
+    constructor(description, script, // eslint-disable-line @typescript-eslint/ban-types
     args = []) {
-        super();
+        super(description, core_1.Interaction.callerLocation(5));
         this.script = script;
         this.args = args;
     }
     /**
-     * @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 args = await (0, io_1.asyncMap)(this.args, arg => actor.answer(arg));
@@ -220,15 +219,13 @@ exports.ExecuteScriptWithArguments = ExecuteScriptWithArguments;
  */
 class ExecuteAsynchronousScript extends ExecuteScriptWithArguments {
     withArguments(...args) {
-        return new ExecuteAsynchronousScript(this.script, args);
+        return new ExecuteAsynchronousScript(args.length > 0
+            ? (0, core_1.f) `#actor executes an asynchronous script with arguments: ${args}`
+            : this.toString(), this.script, args);
     }
-    executeAs(actor, args) {
-        return abilities_1.BrowseTheWeb.as(actor).executeAsyncScript(this.script, ...args); // todo: fix types
-    }
-    toString() {
-        return this.args.length > 0
-            ? (0, io_1.formatted) `#actor executes an asynchronous script with arguments: ${this.args}`
-            : `#actor executes an asynchronous script`;
+    async executeAs(actor, args) {
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+        return page.executeAsyncScript(this.script, ...args); // todo: fix types
     }
 }
 /**
@@ -239,24 +236,16 @@ class ExecuteAsynchronousScript extends ExecuteScriptWithArguments {
  */
 class ExecuteScriptFromUrl extends core_1.Interaction {
     constructor(sourceUrl) {
-        super();
+        super((0, core_1.f) `#actor executes a script from ${sourceUrl}`);
         this.sourceUrl = sourceUrl;
     }
     /**
-     * @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
-     * @returns {Promise<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) {
-        return abilities_1.BrowseTheWeb.as(actor)
-            .executeAsyncScript(
+    async performAs(actor) {
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+        const sourceUrl = await actor.answer(this.sourceUrl);
+        return page.executeAsyncScript(
         /* istanbul ignore next */
         function executeScriptFromUrl(sourceUrl, callback) {
             const alreadyLoadedScripts = Array.prototype.slice
@@ -270,42 +259,31 @@ class ExecuteScriptFromUrl extends core_1.Interaction {
                 callback();
             });
             script.addEventListener('error', function () {
-                return callback('Couldn\'t load script from ' + sourceUrl);
+                return callback(`Couldn't load script from ${sourceUrl}`);
             });
             script.src = sourceUrl;
             script.async = true;
             document.head.append(script);
-        }, this.sourceUrl)
+        }, sourceUrl)
             .then(errorMessage => {
             if (errorMessage) {
                 throw new core_1.LogicError(errorMessage);
             }
         });
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return `#actor executes a script from ${this.sourceUrl}`;
-    }
 }
 /**
  * @package
  */
 class ExecuteSynchronousScript extends ExecuteScriptWithArguments {
     withArguments(...args) {
-        return new ExecuteSynchronousScript(this.script, args);
-    }
-    executeAs(actor, args) {
-        return abilities_1.BrowseTheWeb.as(actor).executeScript(this.script, ...args); // todo fix type
+        return new ExecuteSynchronousScript(args.length > 0
+            ? (0, core_1.f) `#actor executes a synchronous script with arguments: ${args}`
+            : this.toString(), this.script, args);
     }
-    toString() {
-        return this.args.length > 0
-            ? (0, io_1.formatted) `#actor executes a synchronous script with arguments: ${this.args}`
-            : `#actor executes a synchronous script`;
+    async executeAs(actor, args) {
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+        return page.executeScript(this.script, ...args); // todo fix type
     }
 }
 //# sourceMappingURL=ExecuteScript.js.map

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

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

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

@@ -2,77 +2,67 @@ 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
- *  hover the mouse pointer over a given Web element.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to hover the mouse pointer over a given {@apilink PageElement}.
  *
- * @example <caption>Example widget</caption>
+ * ## Example widget
+ * ```html
  *  <a data-test="example-link"
  *      class="off"
  *      onmouseover="this.className='on';"
  *      onmouseout="this.className='off';"
  *      href="/">hover over me</a>
+ * ```
  *
- * @example <caption>Lean Page Object describing the widget</caption>
- *  import { by, Target } from '@serenity-js/webdriverio';
+ * ## Lean Page Object describing the widget
  *
- *  class Example {
- *      static link = Target.the('example link')
- *          .located(by.css('[data-test="example-link"]'));
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Example {
+ *   static link = () =>
+ *     PageElement.located(By.css('[data-test="example-link"]'))
+ *       .describedAs('example link')
  *  }
+ * ```
+ *
+ * ## Hovering over an element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Hover, CssClasses } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
  *
- * @example <caption>Hovering over an element</caption>
- *  import { actorCalled } from '@serenity-js/core';
- *  import { BrowseTheWeb, Hover, CssClasses } from '@serenity-js/webdriverio';
- *  import { Ensure, equals } from '@serenity-js/assertions';
+ * await actorCalled('Hank')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *      Ensure.that(CssClasses.of(Example.link()), equals([ 'off' ])),
  *
- *  actorCalled('Hank')
- *      .whoCan(BrowseTheWeb.using(browser))
- *      .attemptsTo(
- *          Ensure.that(CssClasses.of(Example.link), equals([ 'off' ])),
+ *     Hover.over(Example.link),
+ *     Ensure.that(CssClasses.of(Example.link()), equals([ 'on' ])),
+ *   )
+ * ```
  *
- *          Hover.over(Example.link),
- *          Ensure.that(CssClasses.of(Example.link), equals([ 'on' ])),
- *      );
+ * ## Learn more
  *
- * @see {@link BrowseTheWeb}
- * @see {@link Target}
- * @see {@link CssClasses}
- * @see {@link @serenity-js/assertions~Ensure}
- * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * - {@apilink BrowseTheWeb}
+ * - {@apilink PageElement}
  *
- * @extends {ElementInteraction}
+ * @group Activities
  */
 export declare class Hover extends PageElementInteraction {
-    private readonly target;
+    private readonly element;
     /**
-     * @desc
-     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
-     *
-     * @param {Answerable<PageElement>} target
-     *  The element to be hovered over
+     * Instantiates this {@apilink Interaction}
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
-     */
-    static over(target: Answerable<PageElement>): Interaction;
-    /**
-     * @param {Answerable<PageElement>} target
+     * @param pageElement
      *  The element to be hovered over
      */
-    constructor(target: Answerable<PageElement>);
+    static over(pageElement: Answerable<PageElement>): Interaction;
+    protected constructor(element: 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=Hover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Hover.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Hover.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,KAAM,SAAQ,sBAAsB;IAYvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV9C;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW;IAI9D,SAAS,aAA8B,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC;IAIvE;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1E"}