@serenity-js/web 3.0.0-rc.0

package/lib/screenplay/interactions/Press.js

@@ -0,0 +1,171 @@
+"use strict";
+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 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.
+ *
+ *  *Please 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`
+ *
+ * @example <caption>Example widget</caption>
+ *  <form>
+ *    <input type="text" name="example" id="example" />
+ *  </form>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *  }
+ *
+ * @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';
+ *
+ *  actorCalled('Priyanka')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput),
+ *          Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
+ *      );
+ *
+ * @see {@link Key}
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ *
+ * @extends {ElementInteraction}
+ */
+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}.
+     *
+     * @param {...keys: Array<Answerable<Key | string | Key[] | string[]>>} keys
+     *  A sequence of one or more keys to press
+     *
+     * @returns {PressBuilder}
+     */
+    static the(...keys) {
+        return new Press(KeySequence.of(keys));
+    }
+    in(field /* | Question<AlertPromise> | AlertPromise */) {
+        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}
+     */
+    async performAs(actor) {
+        const keys = await actor.answer(this.keys);
+        return abilities_1.BrowseTheWeb.as(actor).sendKeys(keys);
+    }
+}
+exports.Press = Press;
+class PressKeyInField extends PageElementInteraction_1.PageElementInteraction {
+    /**
+     * @param {Answerable<Array<Key | string>>} keys
+     *  A sequence of one or more keys to press
+     *
+     * @param {Answerable<PageElement>} field
+     *  Web element to send the keys to
+     */
+    constructor(keys, field /* todo | Question<AlertPromise> | AlertPromise */) {
+        super((0, io_1.formatted) `#actor presses ${keys} in ${field}`);
+        this.keys = keys;
+        this.field = field;
+    }
+    async performAs(actor) {
+        const field = await this.resolve(actor, this.field);
+        const keys = await actor.answer(this.keys);
+        // fix for protractor
+        // todo: should this wait on focus to occur?
+        await abilities_1.BrowseTheWeb.as(actor).executeScript(
+        /* istanbul ignore next */
+        function focus(element) {
+            element.focus();
+        }, await field.nativeElement());
+        return abilities_1.BrowseTheWeb.as(actor).sendKeys(keys);
+    }
+}
+/**
+ * @package
+ */
+class KeySequence extends core_1.Question {
+    constructor(keys) {
+        super();
+        this.keys = keys;
+        this.subject = KeySequence.describe(keys);
+    }
+    static of(keys) {
+        return new KeySequence(keys);
+    }
+    answeredBy(actor) {
+        return Promise.all(this.keys.map(part => actor.answer(part))).then(keys => {
+            return keys.flat().filter(key => !!key);
+        });
+    }
+    /**
+     * @desc
+     *  Changes the description of this question's subject.
+     *
+     * @param {string} subject
+     * @returns {Question<T>}
+     */
+    describedAs(subject) {
+        this.subject = subject;
+        return this;
+    }
+    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
+                ? '-'
+                : acc.separator;
+            return {
+                description: index === 0
+                    ? `${key}`
+                    : `${acc.description}${acc.separator}${key}`,
+                separator,
+            };
+        }, { description: '', separator: ', ' }).description;
+        return `${prefix} ${description}`;
+    }
+}
+//# sourceMappingURL=Press.js.map

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

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

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

@@ -0,0 +1,26 @@
+import { Answerable } from '@serenity-js/core';
+import { Interaction } from '@serenity-js/core/lib/screenplay';
+import { PageElement } from '../models';
+/**
+ * @desc
+ *  Fluent interface to make the instantiation of
+ *  the {@link @serenity-js/core/lib/screenplay~Interaction}
+ *  to {@link Press} more readable.
+ *
+ * @see {@link Press}
+ *
+ * @interface
+ */
+export interface PressBuilder {
+    /**
+     * @desc
+     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  to {@link Press}.
+     *
+     * @param {Answerable<PageElement>} field
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link Target}
+     */
+    in: (field: Answerable<PageElement>) => Interaction;
+}

package/lib/screenplay/interactions/PressBuilder.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PressBuilder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PressBuilder.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/PressBuilder.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,89 @@
+import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+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.
+ *
+ *  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;" />
+ *
+ *    <div id="context-menu" style="display:none">
+ *      Custom context menu
+ *    </div>
+ *  </form>
+ *
+ *  <script>
+ *    function showMenu() {
+ *      document.getElementById("context-menu").style.display = 'block';
+ *    }
+ *  </script>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *      static exampleContextMenu = Target.the('example context menu')
+ *          .located(by.id('context-menu'));
+ *  }
+ *
+ * @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';
+ *
+ *  actorCalled('Chloé')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          RightClick.on(Form.exampleInput),
+ *          Ensure.that(Form.exampleContextMenu, isVisible()),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link isVisible}
+ *
+ * @extends {ElementInteraction}
+ */
+export declare class RightClick extends PageElementInteraction {
+    private readonly target;
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be right-clicked on
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static on(target: Answerable<PageElement>): Interaction;
+    /**
+     * @param {Answerable<PageElement>} target
+     *  The element to be right-clicked on
+     */
+    constructor(target: 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}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}

package/lib/screenplay/interactions/RightClick.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RightClick = void 0;
+const io_1 = require("@serenity-js/core/lib/io");
+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.
+ *
+ *  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;" />
+ *
+ *    <div id="context-menu" style="display:none">
+ *      Custom context menu
+ *    </div>
+ *  </form>
+ *
+ *  <script>
+ *    function showMenu() {
+ *      document.getElementById("context-menu").style.display = 'block';
+ *    }
+ *  </script>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *      static exampleContextMenu = Target.the('example context menu')
+ *          .located(by.id('context-menu'));
+ *  }
+ *
+ * @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';
+ *
+ *  actorCalled('Chloé')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          RightClick.on(Form.exampleInput),
+ *          Ensure.that(Form.exampleContextMenu, isVisible()),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link isVisible}
+ *
+ * @extends {ElementInteraction}
+ */
+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}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be right-clicked on
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static on(target) {
+        return new RightClick(target);
+    }
+    /**
+     * @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}
+     */
+    async performAs(actor) {
+        const element = await this.resolve(actor, this.target);
+        return element.rightClick();
+    }
+}
+exports.RightClick = RightClick;
+//# sourceMappingURL=RightClick.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,83 @@
+import { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+import { PageElement } from '../models';
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  scroll until a given Web element comes into view.
+ *
+ * @example <caption>Example widget</caption>
+ *  <!--
+ *      an element somewhere at the bottom of the page,
+ *      outside of the visible area
+ *  -->
+ *  <input type="submit" id="submit" />
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { Target } from '@serenity-js/protractor';
+ *  import { by } from 'protractor';
+ *
+ *  class Form {
+ *      static submitButton = Target.the('submit button')
+ *          .located(by.id('submit'));
+ *  }
+ *
+ * @example <caption>Scrolling to element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, Scroll, isVisible } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Sara')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Scroll.to(Form.submitButton),
+ *          Ensure.that(Form.submitButton, isVisible()),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link isVisible}
+ * @see {@link @serenity-js/assertions~Ensure}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+export declare class Scroll extends Interaction {
+    private readonly target;
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be scroll to
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static to(target: Answerable<PageElement>): Scroll;
+    /**
+     * @param {Answerable<PageElement>} target
+     *  The element to be scroll to
+     */
+    constructor(target: 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}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+}

package/lib/screenplay/interactions/Scroll.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scroll = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  scroll until a given Web element comes into view.
+ *
+ * @example <caption>Example widget</caption>
+ *  <!--
+ *      an element somewhere at the bottom of the page,
+ *      outside of the visible area
+ *  -->
+ *  <input type="submit" id="submit" />
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { Target } from '@serenity-js/protractor';
+ *  import { by } from 'protractor';
+ *
+ *  class Form {
+ *      static submitButton = Target.the('submit button')
+ *          .located(by.id('submit'));
+ *  }
+ *
+ * @example <caption>Scrolling to element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { Ensure } from '@serenity-js/assertions';
+ *  import { BrowseTheWeb, Scroll, isVisible } from '@serenity-js/protractor';
+ *  import { protractor } from 'protractor';
+ *
+ *  actorCalled('Sara')
+ *      .whoCan(BrowseTheWeb.using(protractor.browser))
+ *      .attemptsTo(
+ *          Scroll.to(Form.submitButton),
+ *          Ensure.that(Form.submitButton, isVisible()),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link isVisible}
+ * @see {@link @serenity-js/assertions~Ensure}
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+class Scroll extends core_1.Interaction {
+    /**
+     * @param {Answerable<PageElement>} target
+     *  The element to be scroll to
+     */
+    constructor(target) {
+        super();
+        this.target = target;
+    }
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be scroll to
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static to(target) {
+        return new Scroll(target);
+    }
+    /**
+     * @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}
+     */
+    async performAs(actor) {
+        const target = await actor.answer(this.target);
+        return target.scrollIntoView();
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return (0, io_1.formatted) `#actor scrolls to ${this.target}`;
+    }
+}
+exports.Scroll = Scroll;
+//# sourceMappingURL=Scroll.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Scroll.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Scroll.ts"],"names":[],"mappings":";;;AAAA,4CAA6F;AAC7F,iDAAqD;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAa,MAAO,SAAQ,kBAAW;IAenC;;;OAGG;IACH,YAA6B,MAA+B;QACxD,KAAK,EAAE,CAAC;QADiB,WAAM,GAAN,MAAM,CAAyB;IAE5D,CAAC;IAnBD;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,MAA+B;QACrC,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE/C,OAAO,MAAM,CAAC,cAAc,EAAE,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAA,cAAS,EAAC,qBAAsB,IAAI,CAAC,MAAO,EAAE,CAAC;IAC1D,CAAC;CACJ;AApDD,wBAoDC"}