tyrell-components 1.0.0-RC6

package/lib/utils/positioning.js

@@ -0,0 +1,308 @@
+/**
+ * Core positioning engine for floating elements
+ * Adapted from ty.positioning ClojureScript implementation
+ *
+ * Handles smart positioning of tooltips, dropdowns, popups, and other
+ * floating elements relative to anchor elements with automatic overflow
+ * detection and placement fallback.
+ */
+// ============================================================================
+// Placement Definitions
+// ============================================================================
+/**
+ * Map of all placement configurations
+ */
+export const placements = {
+    'top-start': {
+        vertical: 'top',
+        horizontal: 'start',
+    },
+    'top': {
+        vertical: 'top',
+        horizontal: 'center',
+    },
+    'top-end': {
+        vertical: 'top',
+        horizontal: 'end',
+    },
+    'right-start': {
+        vertical: 'center',
+        horizontal: 'end',
+        orientation: 'vertical',
+    },
+    'right': {
+        vertical: 'center',
+        horizontal: 'end',
+        orientation: 'vertical',
+    },
+    'right-end': {
+        vertical: 'end',
+        horizontal: 'end',
+        orientation: 'vertical',
+    },
+    'bottom-start': {
+        vertical: 'bottom',
+        horizontal: 'start',
+    },
+    'bottom': {
+        vertical: 'bottom',
+        horizontal: 'center',
+    },
+    'bottom-end': {
+        vertical: 'bottom',
+        horizontal: 'end',
+    },
+    'left-start': {
+        vertical: 'center',
+        horizontal: 'start',
+        orientation: 'vertical',
+    },
+    'left': {
+        vertical: 'center',
+        horizontal: 'start',
+        orientation: 'vertical',
+    },
+    'left-end': {
+        vertical: 'end',
+        horizontal: 'start',
+        orientation: 'vertical',
+    },
+};
+/**
+ * Default placement preference lists for different use cases
+ */
+export const placementPreferences = {
+    default: [
+        'bottom-start', 'bottom-end', 'top-start', 'top-end',
+        'bottom', 'top', 'left', 'right'
+    ],
+    tooltip: [
+        'top', 'bottom', 'left', 'right',
+        'top-start', 'top-end', 'bottom-start', 'bottom-end'
+    ],
+    dropdown: [
+        'bottom-start', 'bottom-end', 'top-start', 'top-end',
+        'bottom', 'top', 'right', 'left'
+    ],
+};
+// ============================================================================
+// DOM Measurement Helpers
+// ============================================================================
+/**
+ * Get element dimensions relative to viewport with calculated center points
+ */
+export function getElementRect(el) {
+    const rect = el.getBoundingClientRect();
+    return {
+        top: rect.top,
+        left: rect.left,
+        right: rect.right,
+        bottom: rect.bottom,
+        width: rect.width,
+        height: rect.height,
+        centerX: rect.left + rect.width / 2,
+        centerY: rect.top + rect.height / 2,
+    };
+}
+/**
+ * Get viewport dimensions and scroll position
+ */
+export function getViewportRect() {
+    return {
+        width: window.innerWidth,
+        height: window.innerHeight,
+        scrollX: window.scrollX,
+        scrollY: window.scrollY,
+    };
+}
+// ============================================================================
+// Position Calculation
+// ============================================================================
+/**
+ * Calculate position for a specific placement
+ * Returns x, y coordinates and overflow information
+ */
+export function calculatePlacement(options) {
+    const { targetRect, floatingRect, placement, offset, padding, scrollbarWidth, containerPadding, } = options;
+    const config = placements[placement];
+    const { vertical, horizontal, orientation } = config;
+    const viewport = getViewportRect();
+    // Calculate X position
+    let x;
+    if (orientation === 'vertical') {
+        // Left/right placements
+        if (horizontal === 'start') {
+            x = targetRect.left - floatingRect.width - offset + containerPadding;
+        }
+        else {
+            x = targetRect.right + offset - containerPadding;
+        }
+    }
+    else {
+        // Top/bottom placements
+        if (horizontal === 'start') {
+            x = targetRect.left;
+        }
+        else if (horizontal === 'center') {
+            x = targetRect.centerX - floatingRect.width / 2;
+        }
+        else {
+            x = targetRect.right - floatingRect.width;
+        }
+    }
+    // Calculate Y position
+    let y;
+    if (orientation === 'vertical') {
+        // Left/right placements
+        if (vertical === 'center') {
+            y = targetRect.centerY - floatingRect.height / 2;
+        }
+        else if (vertical === 'end') {
+            y = targetRect.bottom - floatingRect.height - containerPadding;
+        }
+        else {
+            y = targetRect.top;
+        }
+    }
+    else {
+        // Top/bottom placements
+        if (vertical === 'top') {
+            y = targetRect.top - floatingRect.height - offset + containerPadding;
+        }
+        else {
+            y = targetRect.bottom + offset - containerPadding;
+        }
+    }
+    // Calculate overflow for each edge
+    const overflow = {
+        top: Math.min(0, y - padding),
+        left: Math.min(0, x - padding),
+        bottom: Math.min(0, viewport.height - (y + floatingRect.height + padding)),
+        right: Math.min(0, viewport.width - (x + floatingRect.width + padding + scrollbarWidth)),
+    };
+    // Sum of absolute overflow values
+    const overflowAmount = Object.values(overflow).reduce((sum, val) => sum + Math.abs(val), 0);
+    return {
+        x: Math.round(x),
+        y: Math.round(y),
+        placement,
+        overflow,
+        overflowAmount,
+        fits: overflowAmount === 0,
+    };
+}
+/**
+ * Find the best position for the floating element
+ * Tries all preference placements and returns the one that fits best
+ */
+export function findBestPosition(options) {
+    const { targetEl, floatingEl, preferences = placementPreferences.default, offset = 8, padding = 8, containerPadding = 0, } = options;
+    const targetRect = getElementRect(targetEl);
+    const floatingRect = getElementRect(floatingEl);
+    const scrollbarWidth = 15;
+    // Calculate all candidate positions
+    const candidates = preferences.map(placement => calculatePlacement({
+        targetRect,
+        floatingRect,
+        placement,
+        offset,
+        padding,
+        containerPadding,
+        scrollbarWidth,
+    }));
+    // Find first that fits, or one with least overflow
+    const bestPosition = candidates.find(c => c.fits) ||
+        candidates.reduce((best, current) => current.overflowAmount < best.overflowAmount ? current : best);
+    // Adjust for scrollbar if needed
+    if (bestPosition.overflow.right < 0) {
+        bestPosition.x += bestPosition.overflow.right;
+    }
+    return bestPosition;
+}
+// ============================================================================
+// Auto-Update Functionality
+// ============================================================================
+/**
+ * Create auto-update system for position tracking
+ * Continuously monitors and updates position when target or floating element changes
+ *
+ * @param targetEl - The anchor element to position relative to
+ * @param floatingEl - The floating element to position
+ * @param updateFn - Callback function that receives new position data
+ * @param config - Position options (same as findBestPosition)
+ * @returns Cleanup function to stop auto-updating
+ */
+export function autoUpdate(targetEl, floatingEl, updateFn, config) {
+    let active = true;
+    let scrollRafId = null;
+    let resizeTimeout = null;
+    let resizeObserver = null;
+    let mutationObserver = null;
+    // Update function that recalculates position
+    const update = () => {
+        if (!active)
+            return;
+        const position = findBestPosition({
+            targetEl,
+            floatingEl,
+            ...config,
+        });
+        updateFn(position);
+    };
+    // Initial update
+    update();
+    // Debounced update for resize events
+    const debouncedUpdate = () => {
+        if (resizeTimeout !== null) {
+            clearTimeout(resizeTimeout);
+        }
+        resizeTimeout = window.setTimeout(() => {
+            resizeTimeout = null;
+            update();
+        }, 10);
+    };
+    // RAF-based scroll handler for smooth updates
+    const handleScroll = () => {
+        if (!active)
+            return;
+        if (scrollRafId === null) {
+            scrollRafId = requestAnimationFrame(() => {
+                scrollRafId = null;
+                update();
+            });
+        }
+    };
+    // Observe size changes on target, floating element, and body
+    resizeObserver = new ResizeObserver(debouncedUpdate);
+    resizeObserver.observe(targetEl);
+    resizeObserver.observe(floatingEl);
+    resizeObserver.observe(document.body);
+    // Observe DOM attribute changes on target
+    mutationObserver = new MutationObserver(update);
+    mutationObserver.observe(targetEl, {
+        attributes: true,
+        attributeFilter: ['class', 'style'],
+    });
+    // Listen for scroll events (capture phase for better performance)
+    window.addEventListener('scroll', handleScroll, true);
+    window.addEventListener('resize', debouncedUpdate);
+    // Return cleanup function
+    return () => {
+        active = false;
+        if (scrollRafId !== null) {
+            cancelAnimationFrame(scrollRafId);
+        }
+        if (resizeTimeout !== null) {
+            clearTimeout(resizeTimeout);
+        }
+        if (resizeObserver) {
+            resizeObserver.disconnect();
+        }
+        if (mutationObserver) {
+            mutationObserver.disconnect();
+        }
+        window.removeEventListener('scroll', handleScroll, true);
+        window.removeEventListener('resize', debouncedUpdate);
+    };
+}
+//# sourceMappingURL=positioning.js.map

package/lib/utils/positioning.js.map

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

package/lib/utils/property-capture.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Property Capture Utility
+ *
+ * Solves the problem of frameworks (React, Reagent, etc.) setting properties
+ * on custom elements BEFORE connectedCallback runs.
+ *
+ * PROBLEM:
+ * 1. Framework creates element: document.createElement('ty-dropdown')
+ * 2. Framework sets properties: element.value = "foo"
+ * 3. Constructor runs and defines getters/setters
+ * 4. BUT properties were already set, creating instance properties
+ * 5. Instance properties shadow the class getters/setters
+ * 6. connectedCallback runs - too late!
+ *
+ * SOLUTION:
+ * In connectedCallback, capture any pre-set properties and apply them properly.
+ *
+ * @example
+ * ```typescript
+ * connectedCallback(): void {
+ *   const preSetProps = capturePreSetProperties(this, [
+ *     'value', 'clearable', 'disabled'
+ *   ])
+ *
+ *   if (preSetProps.value !== undefined) {
+ *     this._value = preSetProps.value
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Captured property data
+ */
+export interface CapturedProperty<T = any> {
+    name: string;
+    value: T;
+    hadProperty: boolean;
+}
+/**
+ * Options for property capture
+ */
+export interface PropertyCaptureOptions {
+    /**
+     * Whether to delete instance properties after capture (default: true)
+     * This ensures the class getter/setter will work going forward
+     */
+    cleanup?: boolean;
+}
+/**
+ * Capture properties that were set before connectedCallback
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param options - Capture options
+ * @returns Record of captured properties with metadata
+ *
+ * @example
+ * ```typescript
+ * const captured = capturePreSetProperties(this, ['value', 'disabled'])
+ * // {
+ * //   value: { name: 'value', value: 'foo', hadProperty: true },
+ * //   disabled: { name: 'disabled', value: undefined, hadProperty: false }
+ * // }
+ * ```
+ */
+export declare function capturePreSetProperties(element: HTMLElement, propertyNames: string[], options?: PropertyCaptureOptions): Record<string, CapturedProperty>;
+/**
+ * Simpler API - just get the values that were pre-set
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param options - Capture options
+ * @returns Record of property names to values (only includes properties that were set)
+ *
+ * @example
+ * ```typescript
+ * const values = getCapturedValues(this, ['value', 'disabled'])
+ * if (values.value !== undefined) {
+ *   this._value = values.value
+ * }
+ * ```
+ */
+export declare function getCapturedValues(element: HTMLElement, propertyNames: string[], options?: PropertyCaptureOptions): Record<string, any>;
+/**
+ * Mapping of public property names to private field names
+ */
+export type PropertyMap = Record<string, string>;
+/**
+ * Automatically apply pre-set properties to private fields
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param propertyMap - Optional mapping of public names to private field names
+ *                      Default: adds underscore prefix (e.g., 'value' -> '_value')
+ * @param options - Capture options
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (uses _propertyName convention)
+ * applyPreSetProperties(this, ['value', 'disabled'])
+ * // Sets this._value and this._disabled
+ *
+ * // Custom mapping
+ * applyPreSetProperties(this, ['value'], { value: 'internalValue' })
+ * // Sets this.internalValue
+ * ```
+ */
+export declare function applyPreSetProperties(element: any, propertyNames: string[], propertyMap?: PropertyMap, options?: PropertyCaptureOptions): void;
+/**
+ * Helper for components with standard _propertyName pattern
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param transformer - Optional function to transform values before setting
+ * @param options - Capture options
+ *
+ * @example
+ * ```typescript
+ * connectedCallback(): void {
+ *   // Basic usage
+ *   captureAndApplyProperties(this, ['value', 'disabled', 'required'])
+ *
+ *   // With transformation
+ *   captureAndApplyProperties(this, ['value'], (name, value) => {
+ *     if (name === 'value') return this.parseValue(value)
+ *     return value
+ *   })
+ * }
+ * ```
+ */
+export declare function captureAndApplyProperties(element: any, propertyNames: string[], transformer?: (name: string, value: any) => any, options?: PropertyCaptureOptions): void;
+//# sourceMappingURL=property-capture.d.ts.map

package/lib/utils/property-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-capture.d.ts","sourceRoot":"","sources":["../../src/utils/property-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,CAAC,CAAA;IACR,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,GAAE,sBAA0C,GAClD,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAmBlC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAWrB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,GAAG,EACZ,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,CAAC,EAAE,WAAW,EACzB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAUN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,GAAG,EACZ,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,EAC/C,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAUN"}

package/lib/utils/property-capture.js

@@ -0,0 +1,152 @@
+/**
+ * Property Capture Utility
+ *
+ * Solves the problem of frameworks (React, Reagent, etc.) setting properties
+ * on custom elements BEFORE connectedCallback runs.
+ *
+ * PROBLEM:
+ * 1. Framework creates element: document.createElement('ty-dropdown')
+ * 2. Framework sets properties: element.value = "foo"
+ * 3. Constructor runs and defines getters/setters
+ * 4. BUT properties were already set, creating instance properties
+ * 5. Instance properties shadow the class getters/setters
+ * 6. connectedCallback runs - too late!
+ *
+ * SOLUTION:
+ * In connectedCallback, capture any pre-set properties and apply them properly.
+ *
+ * @example
+ * ```typescript
+ * connectedCallback(): void {
+ *   const preSetProps = capturePreSetProperties(this, [
+ *     'value', 'clearable', 'disabled'
+ *   ])
+ *
+ *   if (preSetProps.value !== undefined) {
+ *     this._value = preSetProps.value
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Capture properties that were set before connectedCallback
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param options - Capture options
+ * @returns Record of captured properties with metadata
+ *
+ * @example
+ * ```typescript
+ * const captured = capturePreSetProperties(this, ['value', 'disabled'])
+ * // {
+ * //   value: { name: 'value', value: 'foo', hadProperty: true },
+ * //   disabled: { name: 'disabled', value: undefined, hadProperty: false }
+ * // }
+ * ```
+ */
+export function capturePreSetProperties(element, propertyNames, options = { cleanup: true }) {
+    const captured = {};
+    for (const name of propertyNames) {
+        const descriptor = Object.getOwnPropertyDescriptor(element, name);
+        captured[name] = {
+            name,
+            value: descriptor?.value,
+            hadProperty: descriptor !== undefined && descriptor.value !== undefined
+        };
+        // Clean up instance property so class getter/setter works
+        if (options.cleanup && captured[name].hadProperty) {
+            delete element[name];
+        }
+    }
+    return captured;
+}
+/**
+ * Simpler API - just get the values that were pre-set
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param options - Capture options
+ * @returns Record of property names to values (only includes properties that were set)
+ *
+ * @example
+ * ```typescript
+ * const values = getCapturedValues(this, ['value', 'disabled'])
+ * if (values.value !== undefined) {
+ *   this._value = values.value
+ * }
+ * ```
+ */
+export function getCapturedValues(element, propertyNames, options) {
+    const captured = capturePreSetProperties(element, propertyNames, options);
+    const values = {};
+    for (const [name, data] of Object.entries(captured)) {
+        if (data.hadProperty) {
+            values[name] = data.value;
+        }
+    }
+    return values;
+}
+/**
+ * Automatically apply pre-set properties to private fields
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param propertyMap - Optional mapping of public names to private field names
+ *                      Default: adds underscore prefix (e.g., 'value' -> '_value')
+ * @param options - Capture options
+ *
+ * @example
+ * ```typescript
+ * // Simple usage (uses _propertyName convention)
+ * applyPreSetProperties(this, ['value', 'disabled'])
+ * // Sets this._value and this._disabled
+ *
+ * // Custom mapping
+ * applyPreSetProperties(this, ['value'], { value: 'internalValue' })
+ * // Sets this.internalValue
+ * ```
+ */
+export function applyPreSetProperties(element, propertyNames, propertyMap, options) {
+    const captured = capturePreSetProperties(element, propertyNames, options);
+    for (const [name, data] of Object.entries(captured)) {
+        if (data.hadProperty) {
+            // Determine the private field name
+            const privateName = propertyMap?.[name] || `_${name}`;
+            element[privateName] = data.value;
+        }
+    }
+}
+/**
+ * Helper for components with standard _propertyName pattern
+ *
+ * @param element - The custom element instance
+ * @param propertyNames - Array of property names to check
+ * @param transformer - Optional function to transform values before setting
+ * @param options - Capture options
+ *
+ * @example
+ * ```typescript
+ * connectedCallback(): void {
+ *   // Basic usage
+ *   captureAndApplyProperties(this, ['value', 'disabled', 'required'])
+ *
+ *   // With transformation
+ *   captureAndApplyProperties(this, ['value'], (name, value) => {
+ *     if (name === 'value') return this.parseValue(value)
+ *     return value
+ *   })
+ * }
+ * ```
+ */
+export function captureAndApplyProperties(element, propertyNames, transformer, options) {
+    const captured = capturePreSetProperties(element, propertyNames, options);
+    for (const [name, data] of Object.entries(captured)) {
+        if (data.hadProperty) {
+            const privateName = `_${name}`;
+            const value = transformer ? transformer(name, data.value) : data.value;
+            element[privateName] = value;
+        }
+    }
+}
+//# sourceMappingURL=property-capture.js.map

package/lib/utils/property-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-capture.js","sourceRoot":"","sources":["../../src/utils/property-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAsBH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAoB,EACpB,aAAuB,EACvB,UAAkC,EAAE,OAAO,EAAE,IAAI,EAAE;IAEnD,MAAM,QAAQ,GAAqC,EAAE,CAAA;IAErD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAEjE,QAAQ,CAAC,IAAI,CAAC,GAAG;YACf,IAAI;YACJ,KAAK,EAAE,UAAU,EAAE,KAAK;YACxB,WAAW,EAAE,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS;SACxE,CAAA;QAED,0DAA0D;QAC1D,IAAI,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YAClD,OAAQ,OAAe,CAAC,IAAI,CAAC,CAAA;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAoB,EACpB,aAAuB,EACvB,OAAgC;IAEhC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;IACzE,MAAM,MAAM,GAAwB,EAAE,CAAA;IAEtC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAY,EACZ,aAAuB,EACvB,WAAyB,EACzB,OAAgC;IAEhC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;IAEzE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,mCAAmC;YACnC,MAAM,WAAW,GAAG,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAA;YACrD,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,KAAK,CAAA;QACnC,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAY,EACZ,aAAuB,EACvB,WAA+C,EAC/C,OAAgC;IAEhC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;IAEzE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,WAAW,GAAG,IAAI,IAAI,EAAE,CAAA;YAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAA;YACtE,OAAO,CAAC,WAAW,CAAC,GAAG,KAAK,CAAA;QAC9B,CAAC;IACH,CAAC;AACH,CAAC"}