ng-hub-ui-utils 22.12.1 → 22.13.0

package/README.md

@@ -400,6 +400,22 @@ Show the label **only while the host is truncated** with `HubOverflowTooltipDire
 <span class="label" [hubOverflowTooltip]="item.label">{{ item.label }}</span>
 ```
 
+The element that is **hovered** and the element that is **measured** need not be the same.
+By default they are, but a control whose text is clipped by a box inside it wants them apart:
+the hover area is the whole control, while the only box that can report truncation is the
+inner one — a child that clips its own text never lets the overflow reach its parent, so
+measuring the parent reports none and the tooltip goes quiet. Point
+`hubOverflowTooltipMeasure` at the inner box with a CSS selector, resolved inside the host:
+
+```html
+<div class="chip" [hubOverflowTooltip]="item.label" hubOverflowTooltipMeasure=".chip__title">
+	<span class="chip__icon"></span>
+	<span class="chip__title">{{ item.label }}</span>
+</div>
+```
+
+Unset — or pointing at nothing — the host measures itself, exactly as before.
+
 Theme it from any scope with `--hub-tooltip-*` variables:
 
 ```css
@@ -710,7 +726,7 @@ library, because their selectors and data models differ.
 ### Directives
 
 -   `HubTooltipDirective` (`[hubTooltip]`) - Tooltip on hover/focus. Inputs: `hubTooltip`, `hubTooltipPlacement`, `hubTooltipDelay`, `hubTooltipOffset`
--   `HubOverflowTooltipDirective` (`[hubOverflowTooltip]`) - Tooltip shown only while the host label is truncated. Inputs: `hubOverflowTooltip`, `placement`
+-   `HubOverflowTooltipDirective` (`[hubOverflowTooltip]`) - Tooltip shown only while the label is truncated. Inputs: `hubOverflowTooltip`, `placement`, `hubOverflowTooltipMeasure` (CSS selector, resolved inside the host, naming the box whose truncation decides it; defaults to the host)
 -   `TooltipDirective` (`[tooltip]`) - **Deprecated since 22.9.0**, kept working. Inputs: `tooltip`, `placement`, `delay`, `offset`
 -   `provideHubTooltip(adapter: HubTooltipAdapter)` and `HUB_TOOLTIP_ADAPTER` - Swap the implementation behind `[hubOverflowTooltip]`, app-wide or per subtree; defaults to `hubTooltipAdapter`
 
@@ -788,6 +804,8 @@ class OverlayRef {
 }
 
 class OverlayPosition {
+  // The element the panel is anchored to. The overlay watches it and follows it when it moves.
+  readonly origin: HTMLElement | null;
   flexibleConnectedTo(origin: ElementRef | HTMLElement): this;
   withPositions(positions: ConnectionPosition[]): this;
   // `start` / `end` are logical and read from the origin element; this overrides that.

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

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { signal, computed, Injectable, effect, InjectionToken, inject, makeEnvironmentProviders, provideAppInitializer, DestroyRef, ElementRef, TemplateRef, createComponent, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, NgZone, input, Directive, afterNextRender } from '@angular/core';
+import { signal, computed, Injectable, effect, InjectionToken, inject, makeEnvironmentProviders, provideAppInitializer, DestroyRef, ElementRef, TemplateRef, createComponent, NgZone, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, input, Directive, afterNextRender } from '@angular/core';
 import { fromEvent, Observable, Subject, isObservable, EMPTY, of, timer, race } from 'rxjs';
 import { takeUntil, map, filter, withLatestFrom, endWith, take, mergeMap, tap } from 'rxjs/operators';
 import { DOCUMENT } from '@angular/common';
@@ -1729,6 +1729,20 @@ class OverlayPosition {
         this._origin = origin;
         return this;
     }
+    /**
+     * The element this overlay is anchored to, resolved to a plain node.
+     *
+     * Exposed because the strategy is the only place that knows what the panel is connected to,
+     * and the overlay has to watch that element to keep up with it when it moves.
+     *
+     * @returns The origin element, or `null` while none has been set.
+     */
+    get origin() {
+        if (!this._origin) {
+            return null;
+        }
+        return this._origin instanceof ElementRef ? this._origin.nativeElement : this._origin;
+    }
     /**
      * Sets the preferred positions for the overlay.
      * The order of the array determines the fallback priority.
@@ -1914,6 +1928,8 @@ class OverlayRef {
     _isAttached = false;
     _repositionHandler;
     _repositionFrame = 0;
+    _originFrame = 0;
+    _originBox = null;
     _keydownCallback;
     _unregisterKeydown;
     _backdropClickCallback;
@@ -2042,8 +2058,79 @@ class OverlayRef {
         };
         window.addEventListener('scroll', this._repositionHandler, { capture: true, passive: true });
         window.addEventListener('resize', this._repositionHandler, { passive: true });
+        this._followOrigin();
+    }
+    /**
+     * Follows the origin while it moves for a reason no event announces.
+     *
+     * Scroll and resize both describe the page moving under an origin that stays put. Neither says
+     * anything about the origin itself moving inside a page nobody scrolled — a sibling collapsing
+     * above it, an image landing, an accordion animating shut — and the panel is then left hanging
+     * where its trigger used to be. Since that collapse is animated, one re-measure when it starts
+     * would only move the panel to a place the trigger is still on its way out of: the trigger has
+     * to be followed for as long as it slides.
+     *
+     * The origin's box is read every frame, but the position is re-applied only when it actually
+     * changed, so an overlay whose trigger sits still never touches the DOM. Scheduled outside
+     * Angular's zone, or a zone-based application would run change detection on every frame an
+     * overlay is open.
+     */
+    _followOrigin() {
+        if (!this._config.positionStrategy || typeof requestAnimationFrame !== 'function') {
+            return;
+        }
+        this._originBox = this._measureOrigin();
+        const track = () => {
+            if (!this._isAttached) {
+                this._originFrame = 0;
+                return;
+            }
+            this._originFrame = requestAnimationFrame(track);
+            // Read again rather than captured once: a consumer is free to re-anchor a live overlay,
+            // and the panel has to end up following whatever it is connected to now.
+            const box = this._measureOrigin();
+            const previous = this._originBox;
+            if (!box) {
+                return;
+            }
+            if (previous &&
+                previous.top === box.top &&
+                previous.left === box.left &&
+                previous.width === box.width &&
+                previous.height === box.height) {
+                return;
+            }
+            this._originBox = box;
+            this.updatePosition();
+        };
+        const start = () => {
+            this._originFrame = requestAnimationFrame(track);
+        };
+        // Resolved through the injector rather than taken in the constructor, so the shape of a
+        // class consumers can instantiate does not change for a private scheduling detail.
+        const zone = this._appRef.injector.get(NgZone, null);
+        if (zone) {
+            zone.runOutsideAngular(start);
+            return;
+        }
+        start();
     }
-    /** Removes the listeners registered by {@link _listenForReposition}. */
+    /**
+     * Reads the origin's box, reduced to the four numbers a move can change.
+     *
+     * @returns The box, or `null` when there is no origin or it has left the document — an element
+     * out of the document reports zeros for everything, and following that would fling the panel
+     * into the corner rather than leave it where it was.
+     */
+    _measureOrigin() {
+        const origin = this._config.positionStrategy?.origin;
+        if (!origin || !origin.isConnected) {
+            return null;
+        }
+        const rect = origin.getBoundingClientRect();
+        return { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
+    }
+    /** Releases everything {@link _listenForReposition} started, the origin follow included. */
     _stopListeningForReposition() {
         if (!this._repositionHandler || typeof window === 'undefined') {
             return;
@@ -2055,6 +2142,11 @@ class OverlayRef {
             cancelAnimationFrame(this._repositionFrame);
             this._repositionFrame = 0;
         }
+        if (this._originFrame) {
+            cancelAnimationFrame(this._originFrame);
+            this._originFrame = 0;
+        }
+        this._originBox = null;
     }
     /**
      * Disposes the overlay and cleans up all allocated resources.
@@ -3175,13 +3267,27 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * {@link HUB_TOOLTIP_ADAPTER} token, which defaults to the built-in hub-ui
  * tooltip. Swap it app-wide (or per subtree) with `provideHubTooltip(...)`.
  *
+ * The element that is MEASURED and the element that is HOVERED need not be the same. By
+ * default they are — the host does both — but a control whose text is clipped by a box
+ * inside it wants them apart: the hover area is the whole control, while the only box that
+ * can report truncation is the inner one. Point `hubOverflowTooltipMeasure` at that box and
+ * the tooltip covers the control while answering to the text.
+ *
  * Requires the tooltip styles once in your app:
  * `@use 'ng-hub-ui-utils/styles/tooltip';`.
  *
- * @example
+ * @example Host measures itself
  * ```html
  * <span class="label" [hubOverflowTooltip]="item.label">{{ item.label }}</span>
  * ```
+ *
+ * @example Hover the whole chip, measure the title inside it
+ * ```html
+ * <div class="chip" [hubOverflowTooltip]="item.label" hubOverflowTooltipMeasure=".chip__title">
+ *   <span class="chip__icon"></span>
+ *   <span class="chip__title">{{ item.label }}</span>
+ * </div>
+ * ```
  */
 class HubOverflowTooltipDirective {
     /** Tooltip text; shown only while the host overflows. */
@@ -3189,6 +3295,15 @@ class HubOverflowTooltipDirective {
     /** Placement of the tooltip relative to the host. */
     placement = input('top', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placement" }] : /* istanbul ignore next */ []));
+    /**
+     * CSS selector, resolved inside the host, naming the element whose truncation decides
+     * whether the tooltip speaks. The tooltip still belongs to the host, so the hover area is
+     * unchanged; only the measurement moves.
+     *
+     * Left unset — or pointing at nothing — the host measures itself, which is what this
+     * directive has always done.
+     */
+    measureTarget = input(undefined, { ...(ngDevMode ? { debugName: "measureTarget" } : /* istanbul ignore next */ {}), alias: 'hubOverflowTooltipMeasure' });
     host = inject(ElementRef);
     adapter = inject(HUB_TOOLTIP_ADAPTER);
     handle = null;
@@ -3200,6 +3315,14 @@ class HubOverflowTooltipDirective {
     ...(ngDevMode ? [{ debugName: "ready" }] : /* istanbul ignore next */ []));
     constructor() {
         afterNextRender(() => this.init());
+        // A selector changed after the fact points at a different box, so the observers and
+        // the truncation state both have to be taken again.
+        effect(() => {
+            this.measureTarget();
+            if (this.ready()) {
+                this.observe();
+            }
+        });
         effect(() => {
             if (!this.ready() || !this.handle) {
                 return;
@@ -3216,32 +3339,63 @@ class HubOverflowTooltipDirective {
     /** Wires the tooltip handle and the browser-only truncation observers. */
     init() {
         const el = this.host.nativeElement;
-        // Attach with no text; the effect feeds the label only while truncated.
+        // The tooltip belongs to the HOST whatever is measured: it is the control the pointer
+        // is over, and the box that reports truncation may be a fraction of it.
         this.handle = this.adapter.attach(el, '', { placement: this.placement() });
-        this.measure(el);
         if (typeof ResizeObserver !== 'undefined') {
-            this.resizeObserver = new ResizeObserver(() => this.measure(el));
-            this.resizeObserver.observe(el);
+            // Re-resolving on every callback rather than closing over the element: content
+            // rendered after this point can bring the measured box with it.
+            this.resizeObserver = new ResizeObserver(() => this.measure());
         }
         if (typeof MutationObserver !== 'undefined') {
-            this.mutationObserver = new MutationObserver(() => this.measure(el));
+            // A mutation can replace the measured box, so the observers are re-pointed rather
+            // than merely re-read.
+            this.mutationObserver = new MutationObserver(() => this.observe());
             this.mutationObserver.observe(el, { childList: true, characterData: true, subtree: true });
         }
+        this.observe();
         this.ready.set(true);
     }
-    /** Updates the truncation state from the host's layout. */
-    measure(el) {
+    /**
+     * Points the resize observer at the boxes that can change the answer — the host, whose
+     * width bounds everything, and the measured box when it is a different element — and
+     * takes the measurement again.
+     */
+    observe() {
+        const host = this.host.nativeElement;
+        const target = this.resolveTarget();
+        if (this.resizeObserver) {
+            this.resizeObserver.disconnect();
+            this.resizeObserver.observe(host);
+            if (target !== host) {
+                this.resizeObserver.observe(target);
+            }
+        }
+        this.measure();
+    }
+    /**
+     * The element whose overflow is the question. Falls back to the host, so a selector that
+     * matches nothing behaves exactly as no selector at all rather than silently going quiet.
+     */
+    resolveTarget() {
+        const host = this.host.nativeElement;
+        const selector = this.measureTarget();
+        return (selector ? host.querySelector(selector) : null) ?? host;
+    }
+    /** Updates the truncation state from the measured box's layout. */
+    measure() {
+        const el = this.resolveTarget();
         this.overflowing.set(el.scrollWidth > el.clientWidth + 1);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HubOverflowTooltipDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.8", type: HubOverflowTooltipDirective, isStandalone: true, selector: "[hubOverflowTooltip]", inputs: { text: { classPropertyName: "text", publicName: "hubOverflowTooltip", isSignal: true, isRequired: false, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "placement", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.8", type: HubOverflowTooltipDirective, isStandalone: true, selector: "[hubOverflowTooltip]", inputs: { text: { classPropertyName: "text", publicName: "hubOverflowTooltip", isSignal: true, isRequired: false, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "placement", isSignal: true, isRequired: false, transformFunction: null }, measureTarget: { classPropertyName: "measureTarget", publicName: "hubOverflowTooltipMeasure", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HubOverflowTooltipDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hubOverflowTooltip]'
                 }]
-        }], ctorParameters: () => [], propDecorators: { text: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubOverflowTooltip", required: false }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "placement", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { text: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubOverflowTooltip", required: false }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "placement", required: false }] }], measureTarget: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubOverflowTooltipMeasure", required: false }] }] } });
 
 /*
  * Public API Surface of utils