ng-hub-ui-utils 22.18.0 → 22.20.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
@@ -539,6 +540,11 @@ Also exported: `resolveGridEdge`, `isWithinGridRange`, `gridRangeCells`, `gridRa
 `HubGridCoords`, `HubGridBounds`, `HubGridRange`, `HubGridSpan`, `HubGridSpanMap`, `HubGridWrap`,
 `HubGridEdge`, `HubGridIntent`, `HubGridWindow` and `HubGridTrackSizes`.
 
+Also exported for a selection of several rectangles: `isWithinGridSelection`, `addGridRange`,
+`gridSelectionCells`, `gridSelectionSize`, `gridSelectionBounds`, `clampGridSelection` and
+`gridSelectionTable` — the last of which decides whether a disjoint selection can be copied at all
+(it can when the rectangles line up, and returns `null` when there is no honest table to write).
+
 ## 🚀 Installation
 
 ```bash
@@ -811,7 +817,7 @@ library, because their selectors and data models differ.
 
 ### 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

@@ -2183,6 +2183,127 @@ function between(value, length) {
     return Math.max(0, Math.min(length - 1, Math.trunc(value)));
 }
 
+/**
+ * A selection made of several rectangles, which is what a grid has the moment somebody holds
+ * `Ctrl` and clicks a second block.
+ *
+ * Kept as a list of rectangles rather than as a set of cells, for the same reason one rectangle is
+ * kept as two corners: a reader picking four blocks of a thousand rows has picked four rectangles,
+ * and turning that into four thousand coordinates to answer "is this cell selected" is how a sheet
+ * starts feeling slow.
+ *
+ * The one rule worth knowing before reading the rest: **a disjoint selection cannot always be
+ * copied.** Two blocks side by side make a table; two blocks that overlap nothing and line up with
+ * nothing make no table at all, and a spreadsheet says so rather than inventing one. That is what
+ * {@link gridSelectionTable} decides, and it is the same rule Excel applies when it refuses with
+ * "that command cannot be used on multiple selections".
+ */
+/** Whether a cell falls inside any rectangle of the selection. */
+function isWithinGridSelection(coords, ranges) {
+    return ranges.some((range) => isWithinGridRange(coords, range));
+}
+/** Whether one rectangle holds another whole. */
+function contains(outer, inner) {
+    return inner.top >= outer.top && inner.bottom <= outer.bottom && inner.left >= outer.left && inner.right <= outer.right;
+}
+/**
+ * Adds a rectangle to a selection.
+ *
+ * Rectangles already swallowed by the newcomer are dropped, and a newcomer already inside one is
+ * not added: without that, clicking about with `Ctrl` held quietly grows a list of rectangles that
+ * all say the same thing, and every later answer — the cell count, the clipboard, the clearing —
+ * has to de-duplicate what should never have been stored twice. Overlaps that are *partial* are
+ * kept as they are, because they are two decisions the reader made and neither contains the other.
+ */
+function addGridRange(ranges, range) {
+    if (ranges.some((existing) => contains(existing, range))) {
+        return [...ranges];
+    }
+    return [...ranges.filter((existing) => !contains(range, existing)), range];
+}
+/** Every rectangle trimmed to the grid, with the ones that no longer land anywhere dropped. */
+function clampGridSelection(ranges, bounds) {
+    return ranges.map((range) => clampGridRange(range, bounds)).filter((range) => !!range);
+}
+/**
+ * Every cell of the selection, each one once, row by row and left to right.
+ *
+ * The order matters as much as it does for a single rectangle: it is the order a paste reads and the
+ * order a clearing reports, so a host can walk it without sorting anything.
+ */
+function gridSelectionCells(ranges) {
+    const seen = new Set();
+    const cells = [];
+    for (const range of ranges) {
+        for (const cell of gridRangeCells(range)) {
+            const key = `${cell.row}\t${cell.col}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                cells.push(cell);
+            }
+        }
+    }
+    return cells.sort((a, b) => a.row - b.row || a.col - b.col);
+}
+/** How many cells the selection covers, counting a cell in two rectangles once. */
+function gridSelectionSize(ranges) {
+    return gridSelectionCells(ranges).length;
+}
+/** The smallest rectangle holding every rectangle of the selection. */
+function gridSelectionBounds(ranges) {
+    if (!ranges.length) {
+        return null;
+    }
+    return ranges.reduce((all, range) => ({
+        top: Math.min(all.top, range.top),
+        bottom: Math.max(all.bottom, range.bottom),
+        left: Math.min(all.left, range.left),
+        right: Math.max(all.right, range.right)
+    }));
+}
+/**
+ * The rows and columns a copy of this selection would write, or null when it cannot be copied.
+ *
+ * A selection of one rectangle is always copyable. Several are copyable only when they line up: all
+ * of them covering the same columns, so they stack into one table, or all of them covering the same
+ * rows, so they sit side by side. Anything else has no rectangle to write — the blocks would have to
+ * be squashed together and the reader would get a table whose shape they never chose.
+ *
+ * @returns The row indices and the column indices of the table, in the order they go out, or null
+ *          when the selection has no honest table.
+ */
+function gridSelectionTable(ranges) {
+    if (!ranges.length) {
+        return null;
+    }
+    const sequence = (from, to) => Array.from({ length: to - from + 1 }, (_, index) => from + index);
+    if (ranges.length === 1) {
+        return { rows: sequence(ranges[0].top, ranges[0].bottom), cols: sequence(ranges[0].left, ranges[0].right) };
+    }
+    const [first] = ranges;
+    const sameColumns = ranges.every((range) => range.left === first.left && range.right === first.right);
+    if (sameColumns) {
+        const stacked = [...ranges].sort((a, b) => a.top - b.top);
+        return {
+            rows: unique(stacked.flatMap((range) => sequence(range.top, range.bottom))),
+            cols: sequence(first.left, first.right)
+        };
+    }
+    const sameRows = ranges.every((range) => range.top === first.top && range.bottom === first.bottom);
+    if (sameRows) {
+        const beside = [...ranges].sort((a, b) => a.left - b.left);
+        return {
+            rows: sequence(first.top, first.bottom),
+            cols: unique(beside.flatMap((range) => sequence(range.left, range.right)))
+        };
+    }
+    return null;
+}
+/** Keeps the first occurrence of each index, so overlapping rectangles do not repeat a row. */
+function unique(values) {
+    return [...new Set(values)];
+}
+
 /**
  * Merged blocks, and what the rest of the grid has to know about them.
  *
@@ -3947,11 +4068,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
@@ -3964,6 +4087,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();
@@ -3994,7 +4118,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);
@@ -4030,21 +4154,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;
         }
@@ -4097,6 +4234,7 @@ class HubTooltipController {
      * offset opens between host and bubble without the label vanishing on the way.
      */
     scheduleHide() {
+        this.clearShowTimeout();
         if (!this.tooltipEl) {
             return;
         }
@@ -4114,6 +4252,7 @@ class HubTooltipController {
     }
     /** Fades the tooltip out and removes it after the fade completes. */
     hide() {
+        this.clearShowTimeout();
         this.clearLeaveTimeout();
         if (!this.tooltipEl) {
             return;
@@ -4127,6 +4266,7 @@ class HubTooltipController {
     }
     /** Removes the tooltip element immediately. */
     removeElement() {
+        this.clearShowTimeout();
         this.clearHideTimeout();
         this.clearLeaveTimeout();
         if (this.tooltipEl) {
@@ -4183,6 +4323,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);
@@ -4350,6 +4497,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);
@@ -4359,6 +4508,7 @@ class HubTooltipDirective {
             this.controller.setOptions({
                 placement: this.placement(),
                 delay: this.delay(),
+                showDelay: this.showDelay(),
                 offset: this.offset()
             });
             this.controller.setText(this.text());
@@ -4369,14 +4519,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**
@@ -4530,5 +4680,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, anchorOf, buildSpanMap, clamp$1 as clamp, clampGridRange, clampToSrgbGamut, closest, compositeOver, computeTargetIndex, containsNode, contrastAPCA, contrastRatio, copyArrayItem, coversRange, createNativeDragImage, createPointerDragSession, debouncedSignal, equals, generateUniqueId, getActiveElement, getFocusableBoundaryElements, getValue, getValueInRange, gridCellTabIndex, gridRangeBetween, gridRangeCells, gridRangeSize, 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, 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_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