ng-hub-ui-utils 22.9.3 → 22.11.0

package/fesm2022/ng-hub-ui-utils.mjs

@@ -610,8 +610,7 @@ const hubFocusTrap = (zone, element, stopFocusTrap$, refocusOnClick = false) =>
             .pipe(takeUntil(stopFocusTrap$), filter((e) => e.key === 'Tab'), withLatestFrom(lastFocusedElement$))
             .subscribe(([tabEvent, focusedElement]) => {
             const [first, last] = getFocusableBoundaryElements(element);
-            if ((focusedElement === first || focusedElement === element) &&
-                tabEvent.shiftKey) {
+            if ((focusedElement === first || focusedElement === element) && tabEvent.shiftKey) {
                 last.focus();
                 tabEvent.preventDefault();
             }
@@ -653,9 +652,7 @@ function isNumber(value) {
     return !isNaN(toInteger(value));
 }
 function isInteger(value) {
-    return (typeof value === 'number' &&
-        isFinite(value) &&
-        Math.floor(value) === value);
+    return typeof value === 'number' && isFinite(value) && Math.floor(value) === value;
 }
 function isDefined(value) {
     return value !== undefined && value !== null;
@@ -826,9 +823,7 @@ function getValue(target, key) {
     key = '';
     do {
         key += keys.shift();
-        if (isDefined(target) &&
-            isDefined(target[key]) &&
-            (typeof target[key] === 'object' || !keys.length)) {
+        if (isDefined(target) && isDefined(target[key]) && (typeof target[key] === 'object' || !keys.length)) {
             target = target[key];
             key = '';
         }
@@ -925,9 +920,7 @@ function getActiveElement(root = document) {
     if (!activeEl) {
         return null;
     }
-    return activeEl.shadowRoot
-        ? getActiveElement(activeEl.shadowRoot)
-        : activeEl;
+    return activeEl.shadowRoot ? getActiveElement(activeEl.shadowRoot) : activeEl;
 }
 
 const HUB_TRANSLATION_CONFIG = new InjectionToken('HUB_TRANSLATION_CONFIG');
@@ -1084,6 +1077,21 @@ function provideHubTranslationAdapter(factory) {
 class OverlayPosition {
     _origin = null;
     _positions = [];
+    _direction = null;
+    /**
+     * Forces the writing direction used to resolve `start` and `end`.
+     *
+     * Rarely needed: left unset, the direction is read from the origin element itself, which is
+     * what a field inside an RTL container reports. Set it only when the overlay must follow a
+     * direction its origin does not have.
+     *
+     * @param direction Writing direction, or `null` to go back to reading the origin's.
+     * @returns This position instance for chaining.
+     */
+    withDirection(direction) {
+        this._direction = direction;
+        return this;
+    }
     /**
      * Sets the origin element used to position the overlay.
      *
@@ -1116,9 +1124,13 @@ class OverlayPosition {
         }
         const originElement = this._origin instanceof ElementRef ? this._origin.nativeElement : this._origin;
         const originRect = originElement.getBoundingClientRect();
+        // `start` and `end` are logical: under RTL they name the right and the left edge. Read from
+        // the origin rather than from the document, so a field inside an RTL island is positioned by
+        // the direction it is actually laid out in.
+        const isRtl = this._direction === 'rtl' || (this._direction === null && getComputedStyle(originElement).direction === 'rtl');
         // Try each position until we find one that fits in the viewport
         for (const position of this._positions) {
-            const coords = this._calculatePosition(originRect, overlayElement, position);
+            const coords = this._calculatePosition(originRect, overlayElement, position, isRtl);
             if (this._fitsInViewport(coords, overlayElement)) {
                 this._applyPosition(overlayElement, coords);
                 return;
@@ -1126,7 +1138,7 @@ class OverlayPosition {
         }
         // If no position fits perfectly, use the first one
         if (this._positions.length > 0) {
-            const coords = this._calculatePosition(originRect, overlayElement, this._positions[0]);
+            const coords = this._calculatePosition(originRect, overlayElement, this._positions[0], isRtl);
             this._applyPosition(overlayElement, coords);
         }
     }
@@ -1138,13 +1150,13 @@ class OverlayPosition {
      * @param position Position configuration.
      * @returns Calculated x and y coordinates.
      */
-    _calculatePosition(originRect, overlayElement, position) {
+    _calculatePosition(originRect, overlayElement, position, isRtl) {
         const overlayRect = overlayElement.getBoundingClientRect();
         // Calculate origin point
-        let x = this._getOriginX(originRect, position.originX);
+        let x = this._getOriginX(originRect, position.originX, isRtl);
         let y = this._getOriginY(originRect, position.originY);
         // Adjust for overlay alignment
-        x -= this._getOverlayX(overlayRect, position.overlayX);
+        x -= this._getOverlayX(overlayRect, position.overlayX, isRtl);
         y -= this._getOverlayY(overlayRect, position.overlayY);
         // Apply offsets
         if (position.offsetX) {
@@ -1158,14 +1170,14 @@ class OverlayPosition {
     /**
      * Gets the X coordinate for the origin point.
      */
-    _getOriginX(rect, position) {
+    _getOriginX(rect, position, isRtl) {
         switch (position) {
             case 'start':
-                return rect.left;
+                return isRtl ? rect.right : rect.left;
             case 'center':
                 return rect.left + rect.width / 2;
             case 'end':
-                return rect.right;
+                return isRtl ? rect.left : rect.right;
         }
     }
     /**
@@ -1184,14 +1196,14 @@ class OverlayPosition {
     /**
      * Gets the X offset for the overlay alignment.
      */
-    _getOverlayX(rect, position) {
+    _getOverlayX(rect, position, isRtl) {
         switch (position) {
             case 'start':
-                return 0;
+                return isRtl ? rect.width : 0;
             case 'center':
                 return rect.width / 2;
             case 'end':
-                return rect.width;
+                return isRtl ? 0 : rect.width;
         }
     }
     /**
@@ -1228,6 +1240,37 @@ class OverlayPosition {
     }
 }
 
+const stack = [];
+let cleanup = null;
+function dispatch(event) {
+    stack[stack.length - 1]?.handler(event);
+}
+/**
+ * Adds an overlay to the top of the stack.
+ *
+ * @param handler Called with every keydown while this overlay is the topmost one.
+ * @returns A function that removes it again; safe to call more than once.
+ */
+function registerOverlayKeydown(handler) {
+    const entry = { handler };
+    stack.push(entry);
+    if (!cleanup && typeof document !== 'undefined') {
+        document.addEventListener('keydown', dispatch);
+        cleanup = () => document.removeEventListener('keydown', dispatch);
+    }
+    return () => {
+        const index = stack.indexOf(entry);
+        if (index === -1) {
+            return;
+        }
+        stack.splice(index, 1);
+        if (!stack.length) {
+            cleanup?.();
+            cleanup = null;
+        }
+    };
+}
+
 /**
  * Manages a single overlay instance created by {@link OverlayService}.
  * Creates a container and optional backdrop in `document.body` and attaches
@@ -1242,6 +1285,10 @@ class OverlayRef {
     _viewRef = null;
     _componentRef = null;
     _isAttached = false;
+    _repositionHandler;
+    _repositionFrame = 0;
+    _keydownCallback;
+    _unregisterKeydown;
     _backdropClickCallback;
     _backdropClickHandler;
     constructor(_config, _appRef) {
@@ -1290,8 +1337,7 @@ class OverlayRef {
                 environmentInjector: this._appRef.injector
             });
             this._appRef.attachView(this._componentRef.hostView);
-            contentElement = this._componentRef.hostView
-                .rootNodes[0];
+            contentElement = this._componentRef.hostView.rootNodes[0];
         }
         this._contentElement = contentElement;
         // Only append if not already in container
@@ -1302,7 +1348,9 @@ class OverlayRef {
         // Apply position strategy
         if (this._config.positionStrategy) {
             this._config.positionStrategy.apply(this._containerElement);
+            this._listenForReposition();
         }
+        this._listenForKeys();
         return contentElement;
     }
     /**
@@ -1312,11 +1360,75 @@ class OverlayRef {
         if (!this._isAttached) {
             return;
         }
+        this._stopListeningForReposition();
+        this._unregisterKeydown?.();
+        this._unregisterKeydown = undefined;
         if (this._contentElement && this._containerElement) {
-            this._containerElement.removeChild(this._contentElement);
+            this._contentElement?.remove();
         }
         this._isAttached = false;
     }
+    /**
+     * Registers a handler for keys pressed while this overlay is the topmost open one.
+     *
+     * Needed because an overlay rarely holds focus: opened from a click it leaves focus where it
+     * was, so a component listening on its own host never hears Escape. Set it before `attach()`,
+     * or right after — the listener is registered on attach and released on detach.
+     *
+     * @param callback Invoked with each keydown; decide there what to act on.
+     */
+    onKeydown(callback) {
+        this._keydownCallback = callback;
+        if (this._isAttached && !this._unregisterKeydown) {
+            this._listenForKeys();
+        }
+    }
+    /** Puts this overlay on top of the keyboard stack for as long as it is attached. */
+    _listenForKeys() {
+        if (!this._keydownCallback || this._unregisterKeydown) {
+            return;
+        }
+        const callback = this._keydownCallback;
+        this._unregisterKeydown = registerOverlayKeydown((event) => callback(event));
+    }
+    /**
+     * Keeps the overlay glued to its origin while the page moves under it.
+     *
+     * Registered on `window` in the CAPTURE phase, which is the whole point: a `scroll` event on an
+     * element does not bubble, so a listener on `document` never hears an application that scrolls
+     * an inner container rather than the page. Capture sees both.
+     *
+     * Coalesced into an animation frame, because a scroll fires far more often than a paint.
+     */
+    _listenForReposition() {
+        if (this._repositionHandler || typeof window === 'undefined') {
+            return;
+        }
+        this._repositionHandler = () => {
+            if (this._repositionFrame) {
+                return;
+            }
+            this._repositionFrame = requestAnimationFrame(() => {
+                this._repositionFrame = 0;
+                this.updatePosition();
+            });
+        };
+        window.addEventListener('scroll', this._repositionHandler, { capture: true, passive: true });
+        window.addEventListener('resize', this._repositionHandler, { passive: true });
+    }
+    /** Removes the listeners registered by {@link _listenForReposition}. */
+    _stopListeningForReposition() {
+        if (!this._repositionHandler || typeof window === 'undefined') {
+            return;
+        }
+        window.removeEventListener('scroll', this._repositionHandler, { capture: true });
+        window.removeEventListener('resize', this._repositionHandler);
+        this._repositionHandler = undefined;
+        if (this._repositionFrame) {
+            cancelAnimationFrame(this._repositionFrame);
+            this._repositionFrame = 0;
+        }
+    }
     /**
      * Disposes the overlay and cleans up all allocated resources.
      */
@@ -1333,7 +1445,7 @@ class OverlayRef {
             this._componentRef = null;
         }
         if (this._containerElement) {
-            document.body.removeChild(this._containerElement);
+            this._containerElement?.remove();
             this._containerElement = null;
         }
         if (this._backdropElement) {
@@ -1342,7 +1454,7 @@ class OverlayRef {
                 this._backdropElement.removeEventListener('click', this._backdropClickHandler);
                 this._backdropClickHandler = undefined;
             }
-            document.body.removeChild(this._backdropElement);
+            this._backdropElement?.remove();
             this._backdropElement = null;
         }
         this._contentElement = null;
@@ -1381,22 +1493,16 @@ class OverlayRef {
         this._containerElement = document.createElement('div');
         this._containerElement.classList.add('hub-overlay-container');
         if (this._config.panelClass) {
-            const classes = Array.isArray(this._config.panelClass)
-                ? this._config.panelClass
-                : [this._config.panelClass];
+            const classes = Array.isArray(this._config.panelClass) ? this._config.panelClass : [this._config.panelClass];
             classes.forEach((cls) => this._containerElement.classList.add(cls));
         }
         if (this._config.width) {
             this._containerElement.style.width =
-                typeof this._config.width === 'number'
-                    ? `${this._config.width}px`
-                    : this._config.width;
+                typeof this._config.width === 'number' ? `${this._config.width}px` : this._config.width;
         }
         if (this._config.height) {
             this._containerElement.style.height =
-                typeof this._config.height === 'number'
-                    ? `${this._config.height}px`
-                    : this._config.height;
+                typeof this._config.height === 'number' ? `${this._config.height}px` : this._config.height;
         }
         // A content-sized overlay must never clip: with no configured size the
         // container computes to 0x0 whenever its content is absolutely positioned
@@ -1411,9 +1517,7 @@ class OverlayRef {
         // overlay (e.g. above a modal) without `!important`; the literal fallback
         // keeps today's behavior when the overlay stylesheet is not imported.
         this._containerElement.style.zIndex =
-            this._config.zIndex != null
-                ? String(this._config.zIndex)
-                : 'var(--hub-overlay-zindex, 1000)';
+            this._config.zIndex != null ? String(this._config.zIndex) : 'var(--hub-overlay-zindex, 1000)';
         document.body.appendChild(this._containerElement);
     }
     /**
@@ -1477,6 +1581,21 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
                 }]
         }] });
 
+/**
+ * The fallback chain a dropdown wants: below the origin, aligned to its start edge, flipping above
+ * it when there is no room, then trying the end edge for the same pair.
+ *
+ * `start` and `end` are logical, so this list mirrors itself under RTL without a second copy.
+ * Matches the order Angular Material's own connected overlay defaults to, because a reader who
+ * knows one should not have to learn the other.
+ */
+const HUB_DROPDOWN_POSITIONS = [
+    { originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'top' },
+    { originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'bottom' },
+    { originX: 'end', originY: 'top', overlayX: 'end', overlayY: 'bottom' },
+    { originX: 'end', originY: 'bottom', overlayX: 'end', overlayY: 'top' }
+];
+
 class GetPipe {
     /**
      * @param value The object to retrieve the property from.
@@ -1489,9 +1608,7 @@ class GetPipe {
         }
         return path
             .split('.')
-            .reduce((a, c) => a && a[c] !== null && a[c] !== undefined
-            ? a[c]
-            : defaultValue || null, value);
+            .reduce((a, c) => (a && a[c] !== null && a[c] !== undefined ? a[c] : defaultValue || null), value);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: GetPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
     static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "22.0.8", ngImport: i0, type: GetPipe, isStandalone: true, name: "get" });
@@ -1761,8 +1878,7 @@ const hubRunTransition = (zone, element, startFn, options) => {
     // If animations are disabled, we have to emit a value and complete the observable
     // In this case we have to call the end function, but can finish immediately by emitting a value,
     // completing the observable and executing end functions synchronously.
-    if (!options.animation ||
-        window.getComputedStyle(element).transitionProperty === 'none') {
+    if (!options.animation || window.getComputedStyle(element).transitionProperty === 'none') {
         zone.run(() => endFn());
         return of(undefined).pipe(runInZone(zone));
     }
@@ -1863,9 +1979,7 @@ class PopupService {
             return new ContentRef([viewRef.rootNodes], viewRef);
         }
         else {
-            return new ContentRef([
-                [this._document.createTextNode(`${content}`)]
-            ]);
+            return new ContentRef([[this._document.createTextNode(`${content}`)]]);
         }
     }
 }
@@ -1933,7 +2047,14 @@ const TOOLTIP_THEME_VARS = [
     '--hub-tooltip-zindex',
     '--hub-tooltip-transition-duration',
     '--hub-tooltip-shadow',
-    '--hub-tooltip-font-family'
+    '--hub-tooltip-font-family',
+    // How the label breaks and sits. Forwarded like the rest so a tooltip that carries a
+    // sentence or two — a field's explanation rather than its name — can be asked for from
+    // the host, which is the only element a consumer can reach: the tooltip itself is on
+    // `<body>`, outside any component's styles. Without them the only way to widen one
+    // tooltip was a global rule that widened every tooltip in the product.
+    '--hub-tooltip-white-space',
+    '--hub-tooltip-text-align'
 ];
 /**
  * Framework-agnostic tooltip engine.
@@ -2397,5 +2518,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, clamp, closest, computeTargetIndex, containsNode, copyArrayItem, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, hubTooltipAdapter, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, moveItemInArray, padNumber, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, reflow, regExpEscape, removeAccents, resolveDropPosition, resolveHubAccent, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
+export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_DROPDOWN_POSITIONS, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslationService, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TooltipDirective, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, clamp, closest, computeTargetIndex, containsNode, copyArrayItem, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, hubCompleteTransition, hubFocusTrap, hubRunTransition, hubTooltipAdapter, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, moveItemInArray, padNumber, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, reflow, regExpEscape, registerOverlayKeydown, removeAccents, resolveDropPosition, resolveHubAccent, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
 //# sourceMappingURL=ng-hub-ui-utils.mjs.map