ng-hub-ui-utils 22.18.0 → 22.19.0

package/README.md

@@ -539,6 +539,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

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.
  *
@@ -4530,5 +4651,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