ng-hub-ui-utils 22.3.2 → 22.5.0

package/README.md

@@ -364,6 +364,14 @@ import { TooltipDirective } from 'ng-hub-ui-utils';
 export class ExampleComponent {}
 ```
 
+> **Styles (required since 22.4.0).** The tooltip no longer injects its CSS at
+> runtime — import its stylesheet once in your app (e.g. `styles.scss`), the same
+> way as `overlay`:
+>
+> ```scss
+> @use 'ng-hub-ui-utils/styles/tooltip';
+> ```
+
 Inputs: `tooltip` (text), `placement` (`top` | `bottom` | `left` | `right`, default `top`),
 `delay` (fade ms, default `150`), `offset` (px, default `8`).
 
@@ -380,7 +388,7 @@ Theme it from any scope with `--hub-tooltip-*` variables:
 
 Available tokens: `--hub-tooltip-bg`, `--hub-tooltip-color`, `--hub-tooltip-opacity`,
 `--hub-tooltip-padding-x`, `--hub-tooltip-padding-y`, `--hub-tooltip-border-radius`,
-`--hub-tooltip-font-size`, `--hub-tooltip-max-width`, `--hub-tooltip-z-index`,
+`--hub-tooltip-font-size`, `--hub-tooltip-max-width`, `--hub-tooltip-zindex`,
 `--hub-tooltip-transition-duration`, `--hub-tooltip-shadow`, `--hub-tooltip-font-family`.
 
 ## 🚀 Installation

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, ElementRef, TemplateRef, createComponent, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, NgZone, input, Renderer2, RendererStyleFlags2, HostListener, Directive } from '@angular/core';
+import { signal, computed, Injectable, effect, InjectionToken, inject, makeEnvironmentProviders, ElementRef, TemplateRef, createComponent, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, NgZone, input, Directive } 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';
@@ -1778,8 +1778,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.1", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 
-/** Id of the singleton stylesheet injected into the document head. */
-const TOOLTIP_STYLE_ID = 'hub-tooltip-styles';
 /**
  * Themeable custom properties forwarded from the host to the tooltip element.
  *
@@ -1799,121 +1797,124 @@ const TOOLTIP_THEME_VARS = [
     '--hub-tooltip-font-weight',
     '--hub-tooltip-line-height',
     '--hub-tooltip-max-width',
-    '--hub-tooltip-z-index',
+    '--hub-tooltip-zindex',
     '--hub-tooltip-transition-duration',
     '--hub-tooltip-shadow',
     '--hub-tooltip-font-family'
 ];
 /**
- * Base tooltip styles, injected once per document.
+ * Framework-agnostic tooltip engine.
  *
- * Every visual property is driven by a `--hub-tooltip-*` custom property with a
- * sensible fallback, so consuming apps can theme tooltips from any scope without
- * touching this directive.
- */
-const TOOLTIP_STYLES = `
-.hub-tooltip {
-  position: absolute;
-  z-index: var(--hub-tooltip-z-index, 1070);
-  display: block;
-  margin: 0;
-  max-width: var(--hub-tooltip-max-width, 200px);
-  padding: var(--hub-tooltip-padding-y, 0.25rem) var(--hub-tooltip-padding-x, 0.5rem);
-  font-family: var(--hub-tooltip-font-family, var(--hub-ref-font-family, inherit));
-  font-size: var(--hub-tooltip-font-size, 0.875rem);
-  font-weight: var(--hub-tooltip-font-weight, 400);
-  line-height: var(--hub-tooltip-line-height, 1.5);
-  text-align: center;
-  word-wrap: break-word;
-  white-space: normal;
-  color: var(--hub-tooltip-color, #fff);
-  background-color: var(--hub-tooltip-bg, #000);
-  border-radius: var(--hub-tooltip-border-radius, 0.375rem);
-  box-shadow: var(--hub-tooltip-shadow, none);
-  opacity: 0;
-  pointer-events: none;
-  transition: opacity var(--hub-tooltip-transition-duration, 0.15s) ease-in-out;
-}
-.hub-tooltip--show { opacity: var(--hub-tooltip-opacity, 0.9); }
-`;
-/**
- * Lightweight, dependency-free tooltip directive.
+ * Binds hover/focus listeners to a host element and renders a body-portaled,
+ * `--hub-tooltip-*`-themeable label on demand. It owns no Angular dependency, so
+ * it can be reused both by the `[tooltip]` directive and by other primitives
+ * (e.g. a badge overflow tooltip) that want the exact same visual contract
+ * without re-implementing the DOM logic.
  *
- * Apply `[tooltip]` to any element to show a positioned label on hover/focus.
- * The tooltip element is appended to `<body>` so it is never clipped by an
- * overflow container, and every visual aspect is themeable through
- * `--hub-tooltip-*` CSS variables.
+ * Styles ship in `styles/tooltip.scss`. Import once in your app:
+ * `@use 'ng-hub-ui-utils/styles/tooltip';`.
  */
-class TooltipDirective {
-    /** Tooltip text content. */
-    tooltipTitle = input.required({ ...(ngDevMode ? { debugName: "tooltipTitle" } : /* istanbul ignore next */ {}), alias: 'tooltip' });
-    /** Placement of the tooltip relative to the host. */
-    placement = input('top', /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "placement" }] : /* istanbul ignore next */ []));
-    /** Fade duration in milliseconds, also used as the removal delay on hide. */
-    delay = input(150, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "delay" }] : /* istanbul ignore next */ []));
-    /** Gap in pixels between the host and the tooltip. */
-    offset = input(8, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "offset" }] : /* istanbul ignore next */ []));
+class HubTooltipController {
+    host;
     tooltipEl = null;
     hideTimeout = null;
-    host = inject(ElementRef);
-    renderer = inject(Renderer2);
-    document = inject(DOCUMENT);
-    constructor() {
-        this.ensureStyles();
-    }
-    ngOnDestroy() {
-        this.destroyTooltip();
-    }
-    onShow() {
-        this.show();
+    text = '';
+    placement = 'top';
+    delay = 150;
+    offset = 8;
+    doc;
+    view;
+    onShow = () => this.show();
+    onHide = () => this.hide();
+    /**
+     * @param host    Element the tooltip is anchored to and whose pointer/focus
+     *                events trigger the tooltip.
+     * @param options Initial placement, delay and offset.
+     */
+    constructor(host, options) {
+        this.host = host;
+        this.doc = host.ownerDocument;
+        this.view = this.doc.defaultView;
+        this.setOptions(options);
+        this.host.addEventListener('mouseenter', this.onShow);
+        this.host.addEventListener('focus', this.onShow);
+        this.host.addEventListener('mouseleave', this.onHide);
+        this.host.addEventListener('blur', this.onHide);
+        this.host.addEventListener('click', this.onHide);
     }
-    onHide() {
-        this.hide();
+    /**
+     * Updates the tooltip label. An empty value disables the tooltip and hides any
+     * currently visible instance.
+     * @param text New tooltip content.
+     */
+    setText(text) {
+        this.text = text ?? '';
+        if (!this.text) {
+            this.hide();
+            return;
+        }
+        if (this.tooltipEl) {
+            this.tooltipEl.textContent = this.text;
+            this.position();
+        }
     }
-    /** Injects the shared stylesheet into `<head>` once per document. */
-    ensureStyles() {
-        if (this.document.getElementById(TOOLTIP_STYLE_ID)) {
+    /**
+     * Updates placement/delay/offset. Only provided keys are overwritten.
+     * @param options Partial tooltip options.
+     */
+    setOptions(options) {
+        if (!options) {
             return;
         }
-        const style = this.renderer.createElement('style');
-        style.id = TOOLTIP_STYLE_ID;
-        style.textContent = TOOLTIP_STYLES;
-        this.renderer.appendChild(this.document.head, style);
+        if (options.placement) {
+            this.placement = options.placement;
+        }
+        if (options.delay != null) {
+            this.delay = options.delay;
+        }
+        if (options.offset != null) {
+            this.offset = options.offset;
+        }
+    }
+    /** Detaches listeners and removes any live tooltip element. */
+    destroy() {
+        this.host.removeEventListener('mouseenter', this.onShow);
+        this.host.removeEventListener('focus', this.onShow);
+        this.host.removeEventListener('mouseleave', this.onHide);
+        this.host.removeEventListener('blur', this.onHide);
+        this.host.removeEventListener('click', this.onHide);
+        this.removeElement();
     }
     /** Creates, positions and reveals the tooltip element. */
     show() {
-        if (this.tooltipEl || !this.tooltipTitle()) {
+        if (this.tooltipEl || !this.text) {
             return;
         }
         this.clearHideTimeout();
-        const el = this.renderer.createElement('span');
-        this.renderer.appendChild(el, this.renderer.createText(this.tooltipTitle()));
-        this.renderer.addClass(el, 'hub-tooltip');
-        this.renderer.addClass(el, `hub-tooltip--${this.placement()}`);
-        this.renderer.setStyle(el, 'transition-duration', `${this.delay()}ms`);
+        const el = this.doc.createElement('span');
+        el.textContent = this.text;
+        el.classList.add('hub-tooltip', `hub-tooltip--${this.placement}`);
+        el.style.transitionDuration = `${this.delay}ms`;
         this.forwardThemeVars(el);
-        this.renderer.appendChild(this.document.body, el);
+        this.doc.body.appendChild(el);
         this.tooltipEl = el;
         this.position();
-        this.renderer.addClass(el, 'hub-tooltip--show');
+        el.classList.add('hub-tooltip--show');
     }
     /** Fades the tooltip out and removes it after the fade completes. */
     hide() {
         if (!this.tooltipEl) {
             return;
         }
-        this.renderer.removeClass(this.tooltipEl, 'hub-tooltip--show');
+        this.tooltipEl.classList.remove('hub-tooltip--show');
         this.clearHideTimeout();
-        this.hideTimeout = setTimeout(() => this.destroyTooltip(), this.delay());
+        this.hideTimeout = setTimeout(() => this.removeElement(), this.delay);
     }
     /** Removes the tooltip element immediately. */
-    destroyTooltip() {
+    removeElement() {
         this.clearHideTimeout();
         if (this.tooltipEl) {
-            this.renderer.removeChild(this.document.body, this.tooltipEl);
+            this.tooltipEl.remove();
             this.tooltipEl = null;
         }
     }
@@ -1922,15 +1923,14 @@ class TooltipDirective {
      * the body-portaled tooltip, so scoped theming applies despite the portal.
      */
     forwardThemeVars(el) {
-        const view = this.document.defaultView;
-        if (!view) {
+        if (!this.view) {
             return;
         }
-        const hostStyles = view.getComputedStyle(this.host.nativeElement);
+        const hostStyles = this.view.getComputedStyle(this.host);
         for (const name of TOOLTIP_THEME_VARS) {
             const value = hostStyles.getPropertyValue(name).trim();
             if (value) {
-                this.renderer.setStyle(el, name, value, RendererStyleFlags2.DashCase);
+                el.style.setProperty(name, value);
             }
         }
     }
@@ -1940,19 +1940,19 @@ class TooltipDirective {
             this.hideTimeout = null;
         }
     }
-    /** Positions the tooltip around the host according to `placement`. */
+    /** Positions the tooltip around the host according to the current placement. */
     position() {
         if (!this.tooltipEl) {
             return;
         }
-        const hostRect = this.host.nativeElement.getBoundingClientRect();
+        const hostRect = this.host.getBoundingClientRect();
         const tipRect = this.tooltipEl.getBoundingClientRect();
-        const scrollY = this.document.defaultView?.scrollY ?? 0;
-        const scrollX = this.document.defaultView?.scrollX ?? 0;
-        const offset = this.offset();
+        const scrollY = this.view?.scrollY ?? 0;
+        const scrollX = this.view?.scrollX ?? 0;
+        const offset = this.offset;
         let top = 0;
         let left = 0;
-        switch (this.placement()) {
+        switch (this.placement) {
             case 'bottom':
                 top = hostRect.bottom + offset;
                 left = hostRect.left + (hostRect.width - tipRect.width) / 2;
@@ -1971,33 +1971,79 @@ class TooltipDirective {
                 left = hostRect.left + (hostRect.width - tipRect.width) / 2;
                 break;
         }
-        this.renderer.setStyle(this.tooltipEl, 'top', `${top + scrollY}px`);
-        this.renderer.setStyle(this.tooltipEl, 'left', `${left + scrollX}px`);
+        this.tooltipEl.style.top = `${top + scrollY}px`;
+        this.tooltipEl.style.left = `${left + scrollX}px`;
+    }
+}
+
+/**
+ * Ready-made {@link HubTooltipAdapter} backed by {@link HubTooltipController}.
+ *
+ * Wire it into any ng-hub-ui primitive that exposes an optional tooltip token,
+ * e.g. `provideHubBadgeTooltip(hubTooltipAdapter)`.
+ */
+const hubTooltipAdapter = {
+    attach(host, text, options) {
+        const controller = new HubTooltipController(host, options);
+        controller.setText(text);
+        return {
+            update: (next) => controller.setText(next),
+            destroy: () => controller.destroy()
+        };
+    }
+};
+
+/**
+ * Lightweight tooltip directive.
+ *
+ * Apply `[tooltip]` to any element to show a positioned label on hover/focus.
+ * The tooltip element is appended to `<body>` so it is never clipped by an
+ * overflow container, and every visual aspect is themeable through
+ * `--hub-tooltip-*` CSS variables.
+ *
+ * All DOM work is delegated to {@link HubTooltipController}, so the directive and
+ * any imperative consumer (e.g. a badge overflow tooltip) share the exact same
+ * behaviour and styling.
+ *
+ * Styles ship in `styles/tooltip.scss` (mirroring `styles/overlay.scss`). Import
+ * it once in your app: `@use 'ng-hub-ui-utils/styles/tooltip';`.
+ */
+class TooltipDirective {
+    /** Tooltip text content. */
+    tooltipTitle = input.required({ ...(ngDevMode ? { debugName: "tooltipTitle" } : /* istanbul ignore next */ {}), alias: 'tooltip' });
+    /** Placement of the tooltip relative to the host. */
+    placement = input('top', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "placement" }] : /* istanbul ignore next */ []));
+    /** Fade duration in milliseconds, also used as the removal delay on hide. */
+    delay = input(150, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "delay" }] : /* istanbul ignore next */ []));
+    /** Gap in pixels between the host and the tooltip. */
+    offset = input(8, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "offset" }] : /* istanbul ignore next */ []));
+    host = inject(ElementRef);
+    controller = new HubTooltipController(this.host.nativeElement);
+    constructor() {
+        effect(() => {
+            this.controller.setOptions({
+                placement: this.placement(),
+                delay: this.delay(),
+                offset: this.offset()
+            });
+            this.controller.setText(this.tooltipTitle());
+        });
+    }
+    ngOnDestroy() {
+        this.controller.destroy();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.1", ngImport: i0, type: TooltipDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.1", type: TooltipDirective, isStandalone: true, selector: "[tooltip]", inputs: { tooltipTitle: { classPropertyName: "tooltipTitle", publicName: "tooltip", isSignal: true, isRequired: true, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "placement", isSignal: true, isRequired: false, transformFunction: null }, delay: { classPropertyName: "delay", publicName: "delay", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "offset", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "mouseenter": "onShow()", "focus": "onShow()", "mouseleave": "onHide()", "blur": "onHide()", "click": "onHide()" } }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.1", type: TooltipDirective, isStandalone: true, selector: "[tooltip]", inputs: { tooltipTitle: { classPropertyName: "tooltipTitle", publicName: "tooltip", isSignal: true, isRequired: true, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "placement", isSignal: true, isRequired: false, transformFunction: null }, delay: { classPropertyName: "delay", publicName: "delay", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "offset", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.1", ngImport: i0, type: TooltipDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: '[tooltip]'
                 }]
-        }], ctorParameters: () => [], propDecorators: { tooltipTitle: [{ type: i0.Input, args: [{ isSignal: true, alias: "tooltip", required: true }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "placement", required: false }] }], delay: [{ type: i0.Input, args: [{ isSignal: true, alias: "delay", required: false }] }], offset: [{ type: i0.Input, args: [{ isSignal: true, alias: "offset", required: false }] }], onShow: [{
-                type: HostListener,
-                args: ['mouseenter']
-            }, {
-                type: HostListener,
-                args: ['focus']
-            }], onHide: [{
-                type: HostListener,
-                args: ['mouseleave']
-            }, {
-                type: HostListener,
-                args: ['blur']
-            }, {
-                type: HostListener,
-                args: ['click']
-            }] } });
+        }], ctorParameters: () => [], propDecorators: { tooltipTitle: [{ type: i0.Input, args: [{ isSignal: true, alias: "tooltip", required: true }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "placement", required: false }] }], delay: [{ type: i0.Input, args: [{ isSignal: true, alias: "delay", required: false }] }], offset: [{ type: i0.Input, args: [{ isSignal: true, alias: "offset", required: false }] }] } });
 
 /*
  * Public API Surface of utils
@@ -2007,5 +2053,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.1", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_TRANSLATION_CONFIG, HubDragDropService, 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, interpolateString, isDefined, isInteger, isNumber, isObject, isPromise, isString, mergeDeep, moveItemInArray, padNumber, provideHubTranslation, reflow, regExpEscape, removeAccents, resolveDropPosition, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
+export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_TRANSLATION_CONFIG, HubDragDropService, HubTooltipController, 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, provideHubTranslation, reflow, regExpEscape, removeAccents, resolveDropPosition, runInZone, toAbsoluteIndex, toInteger, toString, transferArrayItem };
 //# sourceMappingURL=ng-hub-ui-utils.mjs.map