ng-hub-ui-utils 22.3.2 → 22.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-utils",
-  "version": "22.3.2",
+  "version": "22.5.0",
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0"

package/src/lib/styles/overlay.scss

@@ -13,11 +13,11 @@
 	--hub-overlay-bg: var(--hub-sys-surface-elevated, #f8f9fa);
 	--hub-overlay-border-radius: var(--hub-sys-radius-sm, 0.25rem);
 	--hub-overlay-shadow: var(--hub-sys-shadow, 0 0.5rem 1rem rgba(0, 0, 0, 0.15));
-	--hub-overlay-z-index: var(--hub-sys-zindex-dropdown, 1000);
-	--hub-overlay-backdrop-z-index: calc(var(--hub-sys-zindex-dropdown, 1000) - 1);
+	--hub-overlay-zindex: var(--hub-sys-zindex-dropdown, 1000);
+	--hub-overlay-backdrop-zindex: calc(var(--hub-sys-zindex-dropdown, 1000) - 1);
 
 	position: absolute;
-	z-index: var(--hub-overlay-z-index);
+	z-index: var(--hub-overlay-zindex);
 	background: var(--hub-overlay-bg);
 	border-radius: var(--hub-overlay-border-radius);
 	box-shadow: var(--hub-overlay-shadow);
@@ -30,7 +30,7 @@
 	left: 0;
 	width: 100%;
 	height: 100%;
-	z-index: var(--hub-overlay-backdrop-z-index, calc(var(--hub-sys-zindex-dropdown, 1000) - 1));
+	z-index: var(--hub-overlay-backdrop-zindex, calc(var(--hub-sys-zindex-dropdown, 1000) - 1));
 }
 
 .hub-overlay-transparent-backdrop {

package/src/lib/styles/tooltip.scss

@@ -0,0 +1,56 @@
+/**
+ * Tooltip styles for the `[tooltip]` directive.
+ *
+ * The tooltip element is portaled to `<body>`, so it cannot inherit scoped
+ * variables from the host's ancestors — the directive forwards any host-resolved
+ * `--hub-tooltip-*` value onto the element inline. These rules provide the base
+ * appearance and the component-token defaults, each backed by a canonical
+ * `--hub-sys-*` / `--hub-ref-*` token, mirroring the `--hub-overlay-*` pattern in
+ * this library.
+ *
+ * Import once in your app styles:
+ *   @use 'ng-hub-ui-utils/styles/tooltip';
+ */
+
+.hub-tooltip {
+	/* Component tokens, each backed by a canonical token. */
+	--hub-tooltip-bg: var(--hub-ref-color-black, #000);
+	--hub-tooltip-color: var(--hub-ref-color-white, #fff);
+	--hub-tooltip-opacity: 0.9;
+	--hub-tooltip-padding-x: var(--hub-ref-space-2, 0.5rem);
+	--hub-tooltip-padding-y: var(--hub-ref-space-1, 0.25rem);
+	--hub-tooltip-border-radius: var(--hub-sys-radius-md, 0.375rem);
+	--hub-tooltip-font-size: var(--hub-ref-font-size-sm, 0.875rem);
+	--hub-tooltip-font-weight: var(--hub-ref-font-weight-base, 400);
+	--hub-tooltip-line-height: var(--hub-ref-line-height-base, 1.5);
+	--hub-tooltip-max-width: 200px;
+	--hub-tooltip-zindex: var(--hub-sys-zindex-tooltip, 1080);
+	--hub-tooltip-transition-duration: 0.15s;
+	--hub-tooltip-shadow: none;
+	--hub-tooltip-font-family: var(--hub-ref-font-family-base, inherit);
+
+	position: absolute;
+	z-index: var(--hub-tooltip-zindex);
+	display: block;
+	margin: 0;
+	max-width: var(--hub-tooltip-max-width);
+	padding: var(--hub-tooltip-padding-y) var(--hub-tooltip-padding-x);
+	font-family: var(--hub-tooltip-font-family);
+	font-size: var(--hub-tooltip-font-size);
+	font-weight: var(--hub-tooltip-font-weight);
+	line-height: var(--hub-tooltip-line-height);
+	text-align: center;
+	word-wrap: break-word;
+	white-space: normal;
+	color: var(--hub-tooltip-color);
+	background-color: var(--hub-tooltip-bg);
+	border-radius: var(--hub-tooltip-border-radius);
+	box-shadow: var(--hub-tooltip-shadow);
+	opacity: 0;
+	pointer-events: none;
+	transition: opacity var(--hub-tooltip-transition-duration) ease-in-out;
+}
+
+.hub-tooltip--show {
+	opacity: var(--hub-tooltip-opacity);
+}

package/types/ng-hub-ui-utils.d.ts

@@ -770,47 +770,137 @@ declare class ScrollBar {
 /** Supported tooltip placements relative to the host element. */
 type HubTooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
 /**
- * Lightweight, dependency-free 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.
+ * Imperative configuration shared by the tooltip directive and any consumer that
+ * drives a tooltip through `HubTooltipController`.
  */
-declare class TooltipDirective implements OnDestroy {
-    /** Tooltip text content. */
-    readonly tooltipTitle: i0.InputSignal<string>;
+interface HubTooltipOptions {
     /** Placement of the tooltip relative to the host. */
-    readonly placement: i0.InputSignal<HubTooltipPlacement>;
+    placement?: HubTooltipPlacement;
     /** Fade duration in milliseconds, also used as the removal delay on hide. */
-    readonly delay: i0.InputSignal<number>;
+    delay?: number;
     /** Gap in pixels between the host and the tooltip. */
-    readonly offset: i0.InputSignal<number>;
+    offset?: number;
+}
+/**
+ * Live handle returned by `HubTooltipAdapter.attach`, used to update or tear
+ * down a tooltip.
+ */
+interface HubTooltipHandle {
+    /** Updates the tooltip label (empty string disables it). */
+    update(text: string): void;
+    /** Detaches listeners and removes the tooltip. */
+    destroy(): void;
+}
+/**
+ * Minimal, framework-agnostic tooltip contract.
+ *
+ * It is deliberately defined by structure (not by import) so any primitive in
+ * the ecosystem — such as `ng-hub-ui-badges` — can accept this implementation
+ * through its own token without taking a hard dependency on this package.
+ */
+interface HubTooltipAdapter {
+    /**
+     * Attaches a hub-ui tooltip to `host` with the given initial `text`.
+     * @returns A handle to update or tear down the tooltip.
+     */
+    attach(host: HTMLElement, text: string, options?: HubTooltipOptions): HubTooltipHandle;
+}
+
+/**
+ * Framework-agnostic tooltip engine.
+ *
+ * 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.
+ *
+ * Styles ship in `styles/tooltip.scss`. Import once in your app:
+ * `@use 'ng-hub-ui-utils/styles/tooltip';`.
+ */
+declare class HubTooltipController {
+    private readonly host;
     private tooltipEl;
     private hideTimeout;
-    private readonly host;
-    private readonly renderer;
-    private readonly document;
-    constructor();
-    ngOnDestroy(): void;
-    protected onShow(): void;
-    protected onHide(): void;
-    /** Injects the shared stylesheet into `<head>` once per document. */
-    private ensureStyles;
+    private text;
+    private placement;
+    private delay;
+    private offset;
+    private readonly doc;
+    private readonly view;
+    private readonly onShow;
+    private readonly onHide;
+    /**
+     * @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: HTMLElement, options?: HubTooltipOptions);
+    /**
+     * Updates the tooltip label. An empty value disables the tooltip and hides any
+     * currently visible instance.
+     * @param text New tooltip content.
+     */
+    setText(text: string): void;
+    /**
+     * Updates placement/delay/offset. Only provided keys are overwritten.
+     * @param options Partial tooltip options.
+     */
+    setOptions(options?: HubTooltipOptions): void;
+    /** Detaches listeners and removes any live tooltip element. */
+    destroy(): void;
     /** Creates, positions and reveals the tooltip element. */
     private show;
     /** Fades the tooltip out and removes it after the fade completes. */
     private hide;
     /** Removes the tooltip element immediately. */
-    private destroyTooltip;
+    private removeElement;
     /**
      * Copies any `--hub-tooltip-*` value defined on the host (or its scope) onto
      * the body-portaled tooltip, so scoped theming applies despite the portal.
      */
     private forwardThemeVars;
     private clearHideTimeout;
-    /** Positions the tooltip around the host according to `placement`. */
+    /** Positions the tooltip around the host according to the current placement. */
     private position;
+}
+
+/**
+ * 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)`.
+ */
+declare const hubTooltipAdapter: HubTooltipAdapter;
+
+/**
+ * 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';`.
+ */
+declare class TooltipDirective implements OnDestroy {
+    /** Tooltip text content. */
+    readonly tooltipTitle: i0.InputSignal<string>;
+    /** Placement of the tooltip relative to the host. */
+    readonly placement: i0.InputSignal<HubTooltipPlacement>;
+    /** Fade duration in milliseconds, also used as the removal delay on hide. */
+    readonly delay: i0.InputSignal<number>;
+    /** Gap in pixels between the host and the tooltip. */
+    readonly offset: i0.InputSignal<number>;
+    private readonly host;
+    private readonly controller;
+    constructor();
+    ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<TooltipDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<TooltipDirective, "[tooltip]", never, { "tooltipTitle": { "alias": "tooltip"; "required": true; "isSignal": true; }; "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "delay": { "alias": "delay"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
@@ -955,5 +1045,5 @@ declare function debouncedSignal<T>(sourceSignal: Signal<T>, debounceDelay?: num
  */
 declare function getActiveElement(root?: Document | ShadowRoot): Element | null;
 
-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 type { ActiveDrag, ConnectionPosition, DragAxis, DragContainerRef, DragImageResult, DragPointerMode, DragRegistration, DragTarget, DropPosition, DropRect, HorizontalConnectionPos, HubTooltipPlacement, HubTranslationConfig, OverlayConfig, PointerDragSession, PointerDragSessionConfig, ScrollbarReverter, TransitionCtx, TransitionEndFn, TransitionOptions, TransitionStartFn, VerticalConnectionPos };
+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 };
+export type { ActiveDrag, ConnectionPosition, DragAxis, DragContainerRef, DragImageResult, DragPointerMode, DragRegistration, DragTarget, DropPosition, DropRect, HorizontalConnectionPos, HubTooltipAdapter, HubTooltipHandle, HubTooltipOptions, HubTooltipPlacement, HubTranslationConfig, OverlayConfig, PointerDragSession, PointerDragSessionConfig, ScrollbarReverter, TransitionCtx, TransitionEndFn, TransitionOptions, TransitionStartFn, VerticalConnectionPos };