ng-hub-ui-utils 22.19.0 → 22.21.0

package/README.md

@@ -385,7 +385,8 @@ export class ExampleComponent {}
 > ```
 
 Inputs: `hubTooltip` (text), `hubTooltipPlacement` (`top` | `bottom` | `left` | `right`,
-default `top`), `hubTooltipDelay` (fade ms, default `150`), `hubTooltipOffset` (px, default `8`).
+default `top`), `hubTooltipDelay` (fade ms, default `150`), `hubTooltipShowDelay` (ms a hover has to last before
+the tooltip opens, default `0`; keyboard focus always opens it at once), `hubTooltipOffset` (px, default `8`).
 
 **The placement is a preference, not an instruction (since 22.16.0).** A tooltip that would open
 off the edge of the window opens on the opposite side instead, at all four edges, and one centred
@@ -814,9 +815,14 @@ library, because their selectors and data models differ.
 - `createPointerDragSession(config: PointerDragSessionConfig): PointerDragSession` - Pointer Events fallback for touch, where native drag events are not delivered
 - Types: `DropPosition`, `DragPointerMode`, `DragContainerRef<T>`, `ActiveDrag<T>`, `DragTarget<T>`, `DragRegistration`
 
+### Form Field Feedback
+
+- `HUB_FIELD_FEEDBACK: InjectionToken<Signal<HubFieldFeedbackPlacement>>` - Lets a container decide where the form fields inside it show their validation message: `'bottom'`, under the control as in a form, or `'tooltip'`, where the field is ringed in the danger colour and the message opens on hover. A container that lays fields out as cells provides it, because a message under the control makes the row taller. It lives here so the paginable table and the spreadsheet can ask for it without depending on `ng-hub-ui-forms`, which is the library that honours it
+- Types: `HubFieldFeedbackPlacement` (`'bottom' | 'tooltip'`)
+
 ### Directives
 
-- `HubTooltipDirective` (`[hubTooltip]`) - Tooltip on hover/focus, flipped away from the window edges. Inputs: `hubTooltip`, `hubTooltipPlacement`, `hubTooltipDelay`, `hubTooltipOffset`
+- `HubTooltipDirective` (`[hubTooltip]`) - Tooltip on hover/focus, flipped away from the window edges. Inputs: `hubTooltip`, `hubTooltipPlacement`, `hubTooltipDelay`, `hubTooltipShowDelay`, `hubTooltipOffset`
 - `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)
 - `provideHubTooltip(adapter: HubTooltipAdapter)` and `HUB_TOOLTIP_ADAPTER` - Swap the implementation behind `[hubOverflowTooltip]`, app-wide or per subtree; defaults to `hubTooltipAdapter`
 

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, NgZone, ApplicationRef, Pipe, ChangeDetectorRef, Injector, ViewContainerRef, input, Directive, afterNextRender } from '@angular/core';
+import { signal, computed, Injectable, InjectionToken, effect, 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';
@@ -1361,6 +1361,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
  * selectors and data models differ.
  */
 
+/**
+ * Lets a container decide where the form fields inside it show their validation messages.
+ *
+ * Under the control is right in a form and wrong in a grid: in a table cell the message makes
+ * the row taller and pushes every row below it. A container that lays fields out as cells
+ * provides `'tooltip'`, and each field then marks itself in the danger colour and keeps the
+ * message for a tooltip on hover.
+ *
+ * It lives here, and not in `ng-hub-ui-forms`, so a library that hosts fields (the paginable
+ * table) can ask for it without depending on the forms library. A signal, because the
+ * container's own setting can change at runtime.
+ */
+const HUB_FIELD_FEEDBACK = new InjectionToken('HUB_FIELD_FEEDBACK');
+
 const FOCUSABLE_ELEMENTS_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
@@ -4068,11 +4082,13 @@ let nextTooltipId = 0;
 class HubTooltipController {
     host;
     tooltipEl = null;
+    showTimeout = null;
     hideTimeout = null;
     leaveTimeout = null;
     text = '';
     placement = 'top';
     delay = 150;
+    showDelay = 0;
     offset = 8;
     /**
      * Side the bubble is actually on, which is the requested placement until the window says
@@ -4085,6 +4101,7 @@ class HubTooltipController {
     /** Id of this controller's bubble, minted once so the host can be described by it. */
     tooltipId = `hub-tooltip-${++nextTooltipId}`;
     onShow = () => this.show();
+    onPointerEnter = () => this.scheduleShow();
     onHide = () => this.hide();
     onPointerLeave = () => this.scheduleHide();
     onTooltipEnter = () => this.retain();
@@ -4115,7 +4132,7 @@ class HubTooltipController {
         this.doc = host.ownerDocument;
         this.view = this.doc.defaultView;
         this.setOptions(options);
-        this.host.addEventListener('mouseenter', this.onShow);
+        this.host.addEventListener('mouseenter', this.onPointerEnter);
         this.host.addEventListener('focus', this.onShow);
         this.host.addEventListener('mouseleave', this.onPointerLeave);
         this.host.addEventListener('blur', this.onHide);
@@ -4151,21 +4168,34 @@ class HubTooltipController {
         if (options.delay != null) {
             this.delay = options.delay;
         }
+        if (options.showDelay != null) {
+            this.showDelay = Math.max(0, options.showDelay);
+        }
         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('mouseenter', this.onPointerEnter);
         this.host.removeEventListener('focus', this.onShow);
         this.host.removeEventListener('mouseleave', this.onPointerLeave);
         this.host.removeEventListener('blur', this.onHide);
         this.host.removeEventListener('click', this.onHide);
         this.removeElement();
     }
+    /** Waits for a sustained hover before opening, while retaining an already visible bubble. */
+    scheduleShow() {
+        this.clearShowTimeout();
+        if (this.tooltipEl || this.showDelay === 0) {
+            this.show();
+            return;
+        }
+        this.showTimeout = setTimeout(() => this.show(), this.showDelay);
+    }
     /** Creates, positions and reveals the tooltip element. */
     show() {
+        this.clearShowTimeout();
         if (!this.text) {
             return;
         }
@@ -4218,6 +4248,7 @@ class HubTooltipController {
      * offset opens between host and bubble without the label vanishing on the way.
      */
     scheduleHide() {
+        this.clearShowTimeout();
         if (!this.tooltipEl) {
             return;
         }
@@ -4235,6 +4266,7 @@ class HubTooltipController {
     }
     /** Fades the tooltip out and removes it after the fade completes. */
     hide() {
+        this.clearShowTimeout();
         this.clearLeaveTimeout();
         if (!this.tooltipEl) {
             return;
@@ -4248,6 +4280,7 @@ class HubTooltipController {
     }
     /** Removes the tooltip element immediately. */
     removeElement() {
+        this.clearShowTimeout();
         this.clearHideTimeout();
         this.clearLeaveTimeout();
         if (this.tooltipEl) {
@@ -4304,6 +4337,13 @@ class HubTooltipController {
             }
         }
     }
+    /** Cancels hover work when the pointer leaves or the host is destroyed. */
+    clearShowTimeout() {
+        if (this.showTimeout !== null) {
+            clearTimeout(this.showTimeout);
+            this.showTimeout = null;
+        }
+    }
     clearHideTimeout() {
         if (this.hideTimeout !== null) {
             clearTimeout(this.hideTimeout);
@@ -4471,6 +4511,8 @@ class HubTooltipDirective {
     placement = input('top', { ...(ngDevMode ? { debugName: "placement" } : /* istanbul ignore next */ {}), alias: 'hubTooltipPlacement' });
     /** Fade duration in milliseconds, also used as the removal delay on hide. */
     delay = input(150, { ...(ngDevMode ? { debugName: "delay" } : /* istanbul ignore next */ {}), alias: 'hubTooltipDelay' });
+    /** Pointer hover wait in milliseconds; keyboard focus remains immediate. */
+    showDelay = input(0, { ...(ngDevMode ? { debugName: "showDelay" } : /* istanbul ignore next */ {}), alias: 'hubTooltipShowDelay' });
     /** Gap in pixels between the host and the tooltip. */
     offset = input(8, { ...(ngDevMode ? { debugName: "offset" } : /* istanbul ignore next */ {}), alias: 'hubTooltipOffset' });
     host = inject(ElementRef);
@@ -4480,6 +4522,7 @@ class HubTooltipDirective {
             this.controller.setOptions({
                 placement: this.placement(),
                 delay: this.delay(),
+                showDelay: this.showDelay(),
                 offset: this.offset()
             });
             this.controller.setText(this.text());
@@ -4490,14 +4533,14 @@ class HubTooltipDirective {
         this.controller.destroy();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HubTooltipDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.8", type: HubTooltipDirective, isStandalone: true, selector: "[hubTooltip]", inputs: { text: { classPropertyName: "text", publicName: "hubTooltip", isSignal: true, isRequired: true, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "hubTooltipPlacement", isSignal: true, isRequired: false, transformFunction: null }, delay: { classPropertyName: "delay", publicName: "hubTooltipDelay", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "hubTooltipOffset", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.8", type: HubTooltipDirective, isStandalone: true, selector: "[hubTooltip]", inputs: { text: { classPropertyName: "text", publicName: "hubTooltip", isSignal: true, isRequired: true, transformFunction: null }, placement: { classPropertyName: "placement", publicName: "hubTooltipPlacement", isSignal: true, isRequired: false, transformFunction: null }, delay: { classPropertyName: "delay", publicName: "hubTooltipDelay", isSignal: true, isRequired: false, transformFunction: null }, showDelay: { classPropertyName: "showDelay", publicName: "hubTooltipShowDelay", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "hubTooltipOffset", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HubTooltipDirective, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hubTooltip]'
                 }]
-        }], ctorParameters: () => [], propDecorators: { text: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltip", required: true }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipPlacement", required: false }] }], delay: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipDelay", required: false }] }], offset: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipOffset", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { text: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltip", required: true }] }], placement: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipPlacement", required: false }] }], delay: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipDelay", required: false }] }], showDelay: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipShowDelay", required: false }] }], offset: [{ type: i0.Input, args: [{ isSignal: true, alias: "hubTooltipOffset", required: false }] }] } });
 
 /**
  * Shows a tooltip with the given text **only while the host element is truncated**
@@ -4651,5 +4694,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_DROPDOWN_POSITIONS, HUB_INK_LIGHTNESS_THRESHOLD, HUB_MAX_HUE_SHIFT, HUB_MAX_NEUTRAL_CHROMA, HUB_NAMED_COLORS, HUB_NEUTRAL_ANCHORS, HUB_SEMANTIC_ANCHORS, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubGetPipe, HubIsObjectPipe, HubIsObservablePipe, HubIsStringPipe, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslatePipe, HubTranslationService, HubUnwrapAsyncPipe, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, addGridRange, anchorOf, buildSpanMap, clamp$1 as clamp, clampGridRange, clampGridSelection, clampToSrgbGamut, closest, compositeOver, computeTargetIndex, containsNode, contrastAPCA, contrastRatio, copyArrayItem, coversRange, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, gridCellTabIndex, gridRangeBetween, gridRangeCells, gridRangeSize, gridSelectionBounds, gridSelectionCells, gridSelectionSize, gridSelectionTable, gridWindow, growWindowToSpans, harmoniseSemantics, hubAnchorToViewport, hubClampToViewport, hubCompleteTransition, hubFitsInViewport, hubFocusTrap, hubOppositeSide, hubRunTransition, hubToAnchorSide, hubToPhysicalSide, hubTooltipAdapter, hubViewportOf, interpolateString, isCovered, isDefined, isInSrgbGamut, isInteger, isNumber, isObject, isPromise, isString, isValidColor, isWithinGridRange, isWithinGridSelection, maxSrgbChroma, mergeDeep, moveGridFocus, moveItemInArray, oklchToRgb, padNumber, parseColor, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, readableOn, reflow, regExpEscape, registerOverlayKeydown, relativeLuminance, removeAccents, resolveDropPosition, resolveGridEdge, resolveGridIntent, resolveHubAccent, rgbToOklch, runInZone, spanAt, tintNeutrals, toAbsoluteIndex, toHex, toInteger, toRgb, toString, transferArrayItem };
+export { ContentRef, FOCUSABLE_ELEMENTS_SELECTOR, GetPipe, HUB_DROPDOWN_POSITIONS, HUB_FIELD_FEEDBACK, HUB_INK_LIGHTNESS_THRESHOLD, HUB_MAX_HUE_SHIFT, HUB_MAX_NEUTRAL_CHROMA, HUB_NAMED_COLORS, HUB_NEUTRAL_ANCHORS, HUB_SEMANTIC_ANCHORS, HUB_TOOLTIP_ADAPTER, HUB_TRANSLATION_CONFIG, HUB_TRANSLATION_PREFIX, HUB_TRANSLATION_SOURCE, HubDragDropService, HubGetPipe, HubIsObjectPipe, HubIsObservablePipe, HubIsStringPipe, HubOverflowTooltipDirective, HubTooltipController, HubTooltipDirective, HubTranslatePipe, HubTranslationService, HubUnwrapAsyncPipe, IsObjectPipe, IsObservablePipe, IsStringPipe, OverlayPosition, OverlayRef, OverlayService, PopupService, ScrollBar, TranslatePipe, UcfirstPipe, UnwrapAsyncPipe, addGridRange, anchorOf, buildSpanMap, clamp$1 as clamp, clampGridRange, clampGridSelection, clampToSrgbGamut, closest, compositeOver, computeTargetIndex, containsNode, contrastAPCA, contrastRatio, copyArrayItem, coversRange, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, gridCellTabIndex, gridRangeBetween, gridRangeCells, gridRangeSize, gridSelectionBounds, gridSelectionCells, gridSelectionSize, gridSelectionTable, gridWindow, growWindowToSpans, harmoniseSemantics, hubAnchorToViewport, hubClampToViewport, hubCompleteTransition, hubFitsInViewport, hubFocusTrap, hubOppositeSide, hubRunTransition, hubToAnchorSide, hubToPhysicalSide, hubTooltipAdapter, hubViewportOf, interpolateString, isCovered, isDefined, isInSrgbGamut, isInteger, isNumber, isObject, isPromise, isString, isValidColor, isWithinGridRange, isWithinGridSelection, maxSrgbChroma, mergeDeep, moveGridFocus, moveItemInArray, oklchToRgb, padNumber, parseColor, provideHubTooltip, provideHubTranslation, provideHubTranslationAdapter, readableOn, reflow, regExpEscape, registerOverlayKeydown, relativeLuminance, removeAccents, resolveDropPosition, resolveGridEdge, resolveGridIntent, resolveHubAccent, rgbToOklch, runInZone, spanAt, tintNeutrals, toAbsoluteIndex, toHex, toInteger, toRgb, toString, transferArrayItem };
 //# sourceMappingURL=ng-hub-ui-utils.mjs.map