@twobirds/microcomponents 0.1.21 → 0.2.0

package/dist/core/elements.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @module Web Components
+ *
+ * Defines micro component integration with native web components and the CustomElementRegistry.
+ *
+ * This module provides utilities for defining custom HTML elements using the native Web Components API.
+ *
+ * ---
+ *
+ * The {@link defineCE} function handles registration of custom elements with the CustomElementRegistry,
+ * automatically attaching the provided class as a DC instance ( micro component ) to the native web component created.
+ * This class and any DC instances added to the web component later will receive all web component native events.
+ * Only the class that defines the WC also defines its observed attributes, but all inner DCs get the changed event.
+ *
+ * The {@link getCE} function is just a wrapper for customElements.get()
+ *
+ * @example
+ *
+ * code:
+ * ```javascript
+ * // create a custom micro component class
+ * class MyComponent extends DC{
+ *
+ * 	constructor( target ){
+ * 		super( target );
+ * 	}
+ *
+ * }
+ *
+ * defineCE( 'my-component', MyComponent );
+ * ```
+ *
+ * afterwards you can use ...
+ * ```HTML
+ * <my-component></my-component>
+ * ```
+ * ... in your template.
+ *
+ * Or you can construct it programmatically:
+ * ```javascript
+ * const myComponentClass = getCE('my-component');
+ * const body = document.body;
+ * body.append( new myComponentClass() );
+ * ```
+ * ---
+ */
+import { type McHost } from './MC.js';
+/**
+Resolves the host element type for a given `extend` tag: the matching built-in
+element type when extending one (e.g. `'button'` → `HTMLButtonElement`),
+plain `HTMLElement` otherwise.
+
+@example
+```ts
+type Btn = TargetOf<'button'>; // HTMLButtonElement
+type Plain = TargetOf<'div'>;   // HTMLElement
+```
+*/
+export type TargetOf<E> = E extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[E] : HTMLElement;
+/**
+The type-level mirror of `kebabToPascal()` in helpers.ts: `'user-card'` →
+`'UserCard'`. Lets {@link defineCE} type the `_mc` registry entry under the
+exact key the runtime stores it at.
+*/
+export type McPascalCase<S extends string> = S extends `${infer Head}-${infer Rest}` ? `${Capitalize<Head>}${McPascalCase<Rest>}` : Capitalize<S>;
+/**
+The custom element constructor returned by {@link defineCE}. Constructing it
+programmatically accepts an optional `data` payload, forwarded as the second
+argument to the microcomponent class. The resulting element exposes its
+microcomponent instance via `._mc`, keyed by the PascalCase form of the tag
+name (`N`); with the default `N = string` no entry is claimed.
+
+@template T - The microcomponent class hosted by the element.
+@template D - The optional construction payload accepted by `new`.
+@template E - The built-in tag being extended, if any (customized built-in elements).
+@template N - The literal PascalCase registry key; `defineCE` fills in `McPascalCase<Tag>`.
+*/
+export type McElementConstructor<T extends object = object, D = unknown, E extends keyof HTMLElementTagNameMap | undefined = undefined, N extends string = string> = new (data?: D) => McHost<TargetOf<E>, string extends N ? Record<never, never> : Record<N, T>>;
+declare global {
+    /**
+    Tag-name → constructor map for microcomponent custom elements — the Mc
+    analogue of `HTMLElementTagNameMap`. Empty by default; register an element
+    once, app-wide, via declaration merging and `getCE()` returns the typed
+    constructor for that tag string:
+
+    @example
+    ```ts
+    class UserCard extends DC {}
+    defineCE('user-card', UserCard);
+
+    declare global {
+        interface McElementTagNameMap {
+            'user-card': McElementConstructor<UserCard, { initial: number }, undefined, 'UserCard'>;
+        }
+    }
+
+    const Ctor = getCE('user-card'); // typed — no cast
+    if (Ctor) {
+        const card = new Ctor({ initial: 1 }); // payload checked
+        card._mc.UserCard;                     // UserCard
+    }
+    ```
+    */
+    interface McElementTagNameMap {
+    }
+}
+/**
+Defines a custom HTML element with optional observed attributes and micro component integration.
+The class provided in DefinitionClass will be added to the ._mc hash object appended to the custom element instance.
+Automatically assigns a "PascalCase" class name derived from the <kebab-case> tagName.
+If the provided definition class extends McBase (indicating a DC or MC class extension), it wraps the constructor to register
+the element instance with DC (DomComponent).
+
+@param tagName - The HTML tag name for the custom element (must contain at least one hyphen, enforced at compile time).
+@param DefinitionClass - The constructor function or class that defines the element's behavior. Its `target` parameter type follows `extend`; an optional second `data` parameter receives the payload passed on programmatic construction.
+@param observedAttributes - An optional array of attribute names to observe for changes.
+@param extend - An optional built-in HTML element tag name to extend, enabling customized built-in elements.
+@returns The registered custom element constructor, typed to accept the `data` payload
+    and exposing the `_mc` entry under the PascalCase tag name — or `undefined` if the
+    tag name was already defined. Feed it (or an equivalent `McElementConstructor`) to
+    the global {@link McElementTagNameMap} to make `getCE()` return it typed by string.
+
+@example define a custom component
+
+---
+
+javascript:
+```javascript
+class MyElement extends DC {
+
+    constructor( target ){
+        super(target);
+    }
+
+    // DOM web component event handler
+    onConnected() {
+        this.innerHTML = '<p>Hi!</p>';
+    }
+    
+    // DOM standard event handler
+    onClick(){
+        this.trigger('something', { data: 'do something' } );
+    }
+    
+    // DOM custom event handler
+    oneSomething(ev){
+        // do only once! Subsequent clicks will not trigger this handler
+        console.log('something happens here:', ev.detail.data );
+    }
+}
+
+defineCE( 'my-element', MyElement );
+```
+
+afterwards you can use ...
+html:
+```HTML
+<my-element></my-element>
+```
+... in your template.
+
+Or you can construct it programmatically using {@link getCE}:
+javascript:
+```javascript
+const MyElementClass = getCE('my-element');
+const body = document.body;
+body.append( new MyElementClass() );
+```
+
+@example Extending a built-in element (customized built-in element)
+
+---
+
+javascript:
+```javascript
+class MyButton extends DC {
+    constructor(target) {
+        super(target);
+    }
+    onConnected() {
+        this.textContent = 'Click me!';
+    }
+}
+
+defineCE('my-button', MyButton, [], 'button');
+```
+
+afterwards you can use it in your template with the `is` attribute:
+```HTML
+<button is="my-button"></button>
+```
+
+
+Or you can construct it programmatically using {@link getCE}:
+javascript:
+```javascript
+const MyButtonClass = getCE('my-button');
+const body = document.body;
+body.append( new MyButtonClass() );
+```
+
+Hints:
+- Your micro component must extend DC, since it is a DOM element
+- method names that look like event handlers are DOM - or custom event handlers ( 'onClick()', 'oneSomething()' )
+- event handlers defined as methods will be assigned to the DOM automatically
+*/
+export declare function defineCE<Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data?: D) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, D, E, McPascalCase<Tag>> | undefined;
+export declare function defineCE<Tag extends `${string}-${string}`, T extends object, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, undefined, E, McPascalCase<Tag>> | undefined;
+export declare function defineCE<Tag extends `${string}-${string}`, T extends object, D, E extends keyof HTMLElementTagNameMap | undefined = undefined>(tagName: Tag, DefinitionClass: new (target: TargetOf<E>, data: D) => T, observedAttributes?: string[], extend?: E): McElementConstructor<T, D, E, McPascalCase<Tag>> | undefined;
+/**
+Retrieves a custom element constructor by tag name.
+
+Tags registered on the global {@link McElementTagNameMap} (via declaration
+merging) come back as their declared constructor type — payload and `_mc`
+entry included; any other string falls back to the plain
+`CustomElementConstructor`.
+
+@example
+
+```ts
+const MyElementClass = getCE('my-element');
+if (MyElementClass) {
+    document.body.append(new MyElementClass());
+}
+```
+
+@param tagName - The HTML tag name to look up.
+@returns The constructor if defined, or undefined if not found.
+*/
+export declare function getCE<K extends keyof McElementTagNameMap & string>(tagName: K): McElementTagNameMap[K] | undefined;
+export declare function getCE(tagName: string): CustomElementConstructor | undefined;
+//# sourceMappingURL=elements.d.ts.map

package/dist/core/elements.d.ts.map

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

package/dist/core/elements.js

@@ -0,0 +1,123 @@
+/**
+ * @module Web Components
+ *
+ * Defines micro component integration with native web components and the CustomElementRegistry.
+ *
+ * This module provides utilities for defining custom HTML elements using the native Web Components API.
+ *
+ * ---
+ *
+ * The {@link defineCE} function handles registration of custom elements with the CustomElementRegistry,
+ * automatically attaching the provided class as a DC instance ( micro component ) to the native web component created.
+ * This class and any DC instances added to the web component later will receive all web component native events.
+ * Only the class that defines the WC also defines its observed attributes, but all inner DCs get the changed event.
+ *
+ * The {@link getCE} function is just a wrapper for customElements.get()
+ *
+ * @example
+ *
+ * code:
+ * ```javascript
+ * // create a custom micro component class
+ * class MyComponent extends DC{
+ *
+ * 	constructor( target ){
+ * 		super( target );
+ * 	}
+ *
+ * }
+ *
+ * defineCE( 'my-component', MyComponent );
+ * ```
+ *
+ * afterwards you can use ...
+ * ```HTML
+ * <my-component></my-component>
+ * ```
+ * ... in your template.
+ *
+ * Or you can construct it programmatically:
+ * ```javascript
+ * const myComponentClass = getCE('my-component');
+ * const body = document.body;
+ * body.append( new myComponentClass() );
+ * ```
+ * ---
+ */
+import { kebabToPascal } from '../utils/helpers.js';
+import { McBase, DC } from './MC.js';
+/**
+Creates a named class constructor with the specified name.
+@param name - The desired name for the class.
+@param targetClass - The class constructor to which the name will be assigned.
+@returns The class constructor with the name property set.
+
+@example
+```ts
+const MyNamedClass = createNamedClass('MyNamedClass', class { });
+console.log(MyNamedClass.name); // 'MyNamedClass'
+```
+*/
+function createNamedClass(name, targetClass) {
+    return Object.defineProperty(targetClass, 'name', { value: name });
+}
+function Base(ElementClass) {
+    return class extends ElementClass {
+        constructor(...args) {
+            super(...args);
+        }
+    };
+}
+// Implementation signature (not directly callable)
+export function defineCE(tagName, DefinitionClass, observedAttributes = [], extend) {
+    if (customElements.get(tagName)) {
+        console.warn(`IGNORED: Custom element "${tagName}" is already defined!`);
+        return;
+    }
+    if (!tagName.includes('-')) {
+        throw new Error('createCustomElement: tagName must contain at least one hyphen ("-").');
+    }
+    let extendClass = HTMLElement;
+    if (extend) {
+        extendClass = document.createElement(extend).constructor;
+    }
+    const pascalCaseName = kebabToPascal(tagName);
+    // a class, but not a MC — the class itself is the element; no `._mc` is attached
+    if (!(DefinitionClass.prototype instanceof McBase)) {
+        customElements.define(tagName, DefinitionClass);
+        return DefinitionClass;
+    }
+    // a MC
+    const McElementClass = createNamedClass(pascalCaseName, class extends Base(extendClass) {
+        constructor(data) {
+            super();
+            DC.add(this, pascalCaseName, new DefinitionClass(this, data));
+        }
+        connectedCallback() {
+            this.dispatchEvent(new CustomEvent('_mcConnected'));
+        }
+        connectedMoveCallback() {
+            this.dispatchEvent(new CustomEvent('_mcConnectedMove'));
+        }
+        disconnectedCallback() {
+            this.dispatchEvent(new CustomEvent('_mcDisconnected'));
+        }
+        adoptedCallback() {
+            this.dispatchEvent(new CustomEvent('_mcAdopted'));
+        }
+        attributeChangedCallback(name, oldValue, newValue) {
+            this.dispatchEvent(new CustomEvent('_mcAttributeChanged', { detail: { name, oldValue, newValue } }));
+        }
+        formResetCallback() {
+            this.dispatchEvent(new CustomEvent('_mcFormReset'));
+        }
+        static get observedAttributes() {
+            return [...observedAttributes];
+        }
+    });
+    customElements.define(tagName, McElementClass, { extends: extend });
+    return McElementClass;
+}
+export function getCE(tagName) {
+    return customElements.get(tagName);
+}

package/dist/core/events.d.ts

@@ -0,0 +1,231 @@
+/**
+@module
+
+This module provides event utilities for interfacing **between microcomponents and external
+frameworks or native DOM/JS environments**. It is not intended for communication between
+frontend microcomponents themselves — for that purpose, use the inherited methods
+( `.on()`, `.one()`, `.off()`, `.trigger()`) that exist when you extend `DC`.
+
+Import this module when you need to exchange information with microcomponents from outside
+the microcomponent system (e.g., vanilla JS, React via `useRef()`, or other frameworks).
+
+The core feature is the ability to explicitly control event flow direction when using {@link trigger}:
+- upward propagation to ancestor components ('u')
+- local dispatch only ('l') [default]
+- downward propagation to descendant components ('d').
+
+@example
+html:
+```html
+<div class="grandparent">
+    <div class="parent">
+        <div class="child">
+        </div>
+    </div>
+</div>
+```
+
+javascript:
+```javascript
+import { on, one, trigger, off } from '@twobirds/microcomponents/events';
+
+// Attach listeners (querySelector may return null — guard first)
+const grandParent = document.querySelector('.grandparent');
+const parent = document.querySelector('.parent');
+const child = document.querySelector('.child');
+if (!grandParent || !parent || !child) throw new Error('example markup missing');
+
+const grandParentHandler = on(
+    grandParent,
+    'dataReady',
+    (ev) => console.log(ev.detail.data)
+);
+
+const parentHandler = on(
+    parent,
+    'dataReady',
+    (ev) => ev.detail.control.stop()
+);
+
+// this event bubbles toward root from the innermost div ..
+trigger( child, 'dataReady', { value: 42 }, 'u');
+// ...but the 'dataReady' handler on grandParent will never be reached !!!
+
+// Clean up handlers when done
+off( parent, 'dataReady', parentHandler );
+off( grandParent, 'dataReady', grandParentHandler );
+```
+*/
+import type { BubbleDirections, McBubbleController, McEventHandler } from '../types/mcTypes.js';
+/**
+ * Converts a standard event name to its microcomponent-prefixed variant.
+ *
+ * This utility is used internally to namespace custom events (e.g., 'Click' → '_mcClick').
+ *
+ * @param eventName - The original event name (e.g., 'click', 'update').
+ * @returns The microcomponent-prefixed event name.
+ *
+ * @example
+ * ```ts
+ * getMcEventName('update'); // '_mcUpdate'
+ * ```
+ */
+export declare function getMcEventName(eventName: string): string;
+/**
+ * A query selector string used to match one or more DOM elements.
+ *
+ * @example
+ * ```ts
+ * const selector: QuerySelectorString = '.my-component';
+ * ```
+ */
+export type QuerySelectorString = string;
+/**
+ * Represents the target of an event operation — either a concrete element,
+ * a CSS selector string, or `undefined` (which is silently ignored).
+ *
+ * @example
+ * ```ts
+ * // Pass an HTMLElement directly
+ * const el: TargetSelect = document.getElementById('root');
+ *
+ * // Or pass a selector string to match multiple elements
+ * const allCards: TargetSelect = '.card';
+ * ```
+ */
+export type TargetSelect = HTMLElement | QuerySelectorString | undefined | null;
+/**
+ * Removes a previously attached event handler from the DOM node. See {@link on} and {@link one}.
+ *
+ * Uses internal microcomponent-prefixed naming for event handlers.
+ * This is primarily used to interface with external frameworks or vanilla JS environments.
+ * For communication between frontend microcomponents, use the `DC.off()` method instead.
+ *
+ * @param target - The DOM element from which to remove the listener.
+ * @param eventName - The name of the event (e.g., 'click', 'update').
+ * @param handler - The listener function or object to detach.
+ *
+ * @example
+ * ```ts
+ * const handler = on(myElement, 'click', () => console.log('clicked'));
+ * off(myElement, 'click', handler); // removes the listener
+ * ```
+ */
+export declare function off<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>): void;
+export declare function off(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject): void;
+/**
+ * Attaches a persistent event listener that will fire every time the specified event occurs.
+ *
+ * This is primarily used to interface with external frameworks or vanilla JS environments.
+ * For communication between frontend microcomponents, use the `DC.on()` method instead.
+ *
+ * The handler receives a `CustomEvent<McDetail<D>>`: the payload sits under
+ * `ev.detail.data`, the bubble-control handle under `ev.detail.control`.
+ *
+ * @param target - The DOM element to attach the listener to.
+ * @param eventName - The name of the event (e.g., 'click', 'update').
+ * @param handler - The callback function or object to invoke on each event.
+ * @param once - If true, remove the listener after first invocation.
+ * @returns The attached handler reference. Useful for later deletion with {@link off}.
+ *
+ * @example
+ * ```ts
+ * const handler = on<{ value: number }>(myElement, 'update', (ev) => {
+ *     console.log(ev.detail.data.value); // number
+ * });
+ * // to remove: off(myElement, 'update', handler);
+ * ```
+ */
+export declare function on<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>, once?: boolean): McEventHandler<D>;
+export declare function on(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject, once?: boolean): EventListenerOrEventListenerObject;
+/**
+ * Attaches an event listener that will fire only once.
+ *
+ * Internally calls {@link on} with the `once` flag set to true. The handler
+ * is automatically removed after its first invocation.
+ * This is primarily used to interface with external frameworks or vanilla JS environments.
+ * For communication between frontend microcomponents, use the `DC.one()` method instead.
+ *
+ * @param target - The DOM element to attach the listener to.
+ * @param eventName - The name of the event (e.g., 'click', 'update').
+ * @param handler - The callback function or object to invoke once.
+ * @returns The attached one-time handler reference. Useful for later deletion with {@link off}.
+ *
+ * @example
+ * ```ts
+ * one<{ ready: boolean }>(myElement, 'dataReady', (ev) => console.log('received:', ev.detail.data));
+ * // fires only once then detaches automatically
+ * ```
+ */
+export declare function one<D = unknown>(target: TargetSelect, eventName: string, handler: McEventHandler<D>): McEventHandler<D>;
+export declare function one(target: TargetSelect, eventName: string, handler: EventListenerOrEventListenerObject): EventListenerOrEventListenerObject;
+/**
+ * @hidden
+ * A controller object used to manage and potentially abort event bubbling.
+ *
+ * The `trigger()` function internally creates instance of this class,
+ * allowing the an eventual handler to call `ev.detail.control.stop()` to
+ * prevent further propagation in either direction (up/down).
+ *
+ * This is only used internally.
+ * @example
+ * ```ts
+ * trigger(myElement, 'update', { value: 42 }, 'u');
+ *
+ * // inside a handler you can call ev.detail.control.stop() to halt propagation
+ * onUpdate(ev) {
+ *     ev.detail.control.stop();
+ * }
+ * ```
+ */
+export declare class BubbleController implements McBubbleController {
+    stopped: boolean;
+    constructor();
+    /**
+     * Signals that event bubbling should be halted.
+     *
+     * After calling this method, subsequent `trigger()` calls will abort
+     * before dispatching the event to any targets.
+     *
+     * @example
+     * ```ts
+     * trigger(myElement, 'update', { value: 42 }, 'u');
+     *
+     * // inside a handler you can call ev.detail.control.stop() to halt propagation
+     * onUpdate(ev) {
+     *     ev.detail.control.stop();
+     * }
+     * ```
+     */
+    stop(): void;
+}
+/**
+ * Creates and dispatches a custom event on the specified DOM node.
+ *
+ * The event is namespaced with an `_mc` prefix by default, unless already prefixed.
+ * Supports bidirectional bubbling (up/down the DOM tree) based on the `bubble` parameter:
+ * - 'l': local dispatch only
+ * - 'u': bubble up towards ancestors
+ * - 'd': bubble down to descendants
+ *
+ * The dispatched event is a `CustomEvent<McDetail<D>>`: handlers find the payload
+ * under `ev.detail.data` and can call `ev.detail.control.stop()` to cancel bubbling.
+ *
+ * @param target - The DOM element on which to trigger the event, or a querySelectorAll(selector) selector string.
+ * @param event - The name of the event (will be prefixed if needed).
+ * @param data - Additional data payload attached to `event.detail.data`.
+ * @param bubble - Bubbling direction ('l', 'u', 'd' or combinations).
+ * @param controller - Optional controller for managing bubbling behavior.
+ *
+ * @example
+ * ```ts
+ * // Trigger a local event with data
+ * trigger(myElement, 'update', { value: 42 }, 'l');
+ *
+ * // Bubble up to ancestors
+ * trigger(myElement, 'dataReady', { ready: true }, 'u');
+ * ```
+ */
+export declare function trigger<D = unknown>(target: HTMLElement | string | undefined | null, event: string, data?: D, bubble?: BubbleDirections, // direction of bubbling
+controller?: BubbleController): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAIF,OAAO,KAAK,EACX,gBAAgB,EAChB,kBAAkB,EAElB,cAAc,EACd,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,IAAI,CAAC;AACR,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,IAAI,CAAC;AA0BR;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,EAAE,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAE,OAAO,GACZ,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,EAC3C,IAAI,CAAC,EAAE,OAAO,GACZ,kCAAkC,CAAC;AA8BtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,GAAG,CAClB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kCAAkC,GACzC,kCAAkC,CAAC;AAsBtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,OAAO,UAAS;;IAEhB;;;;;;;;;;;;;;;OAeG;IACH,IAAI;CAGJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAClC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,CAAW,EACjB,MAAM,GAAE,gBAAsB,EAAE,wBAAwB;AACxD,UAAU,CAAC,EAAE,gBAAgB,QA+C7B"}