@unofficialbox/box-open-elements 0.5.0 → 0.7.0

package/dist/components/overlays/shortcuts-overlay.js

@@ -0,0 +1,385 @@
+import { groupShortcutCommands, isCommandDescriptorRecord, splitShortcutKeys, } from "./command-types.js";
+import { BaseElement } from "../../core/index.js";
+import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
+import { boeOverlay, boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-shortcuts-overlay";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** Editable targets where a bare-character hotkey must never fire. */
+const isTypingTarget = (target) => {
+    const element = target;
+    if (!element || typeof element.tagName !== "string") {
+        return false;
+    }
+    if (element.isContentEditable) {
+        return true;
+    }
+    const tag = element.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+};
+/**
+ * The element the key was actually typed into. `event.target` is retargeted to
+ * the shadow host once an event crosses a shadow boundary, and this library
+ * wraps native controls in shadow DOM — so reading `target` on a document
+ * listener sees `box-text-field`, not the `input` inside it.
+ */
+const keyOrigin = (event) => event.composedPath()[0] ?? event.target;
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: contents;
+        }
+
+        [part="backdrop"] {
+          position: fixed;
+          inset: 0;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          padding: 1rem;
+          background: ${boeOverlay.modalBackdrop};
+          z-index: 1000;
+        }
+
+        [part="sheet"] {
+          inline-size: min(34rem, 100%);
+          max-block-size: 80vh;
+          display: grid;
+          grid-template-rows: auto 1fr;
+          border-radius: ${boeOverlay.modalRadius};
+          border: ${boePanel.border};
+          background: ${boePanel.background};
+          box-shadow: ${boeOverlay.shadow};
+          overflow: hidden;
+        }
+
+        [part="header"] {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          padding: 0.85rem 1rem;
+          border-block-end: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+        }
+
+        [part="title"] {
+          margin: 0;
+          font: inherit;
+          font-size: 1rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="close"] {
+          margin-inline-start: auto;
+          appearance: none;
+          font: inherit;
+          font-size: 0.8rem;
+          padding: 0.25rem 0.55rem;
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          border-radius: ${boeRadius.control};
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: var(--boe-token-text-text, #222222);
+          cursor: pointer;
+        }
+
+        [part="close"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="groups"] {
+          margin: 0;
+          padding: 0.6rem 1rem 1rem;
+          list-style: none;
+          overflow-y: auto;
+        }
+
+        [part="group-label"] {
+          display: block;
+          padding-block: 0.7rem 0.3rem;
+          font-size: 0.7rem;
+          font-weight: 700;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="rows"] {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+          display: grid;
+        }
+
+        [part="row"] {
+          display: flex;
+          align-items: baseline;
+          gap: 0.75rem;
+          padding: 0.35rem 0;
+        }
+
+        [part="row-label"] {
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="keys"] {
+          margin-inline-start: auto;
+          display: inline-flex;
+          align-items: center;
+          gap: 0.2rem;
+          white-space: nowrap;
+        }
+
+        [part="key"] {
+          min-inline-size: 1.4rem;
+          padding: 0.1rem 0.35rem;
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          border-block-end-width: 2px;
+          border-radius: ${boeRadius.size};
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+          font-family: ui-monospace, monospace;
+          font-size: 0.72rem;
+          text-align: center;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="key-separator"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.7rem;
+        }
+
+        [part="empty"] {
+          padding: 1.4rem 1rem;
+          text-align: center;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="close"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+      `;
+/**
+ * The keyboard shortcuts sheet that makes keyboard-first real — the pair to
+ * `box-command-palette`.
+ *
+ * It reads the *same* `CommandDescriptor[]` the palette does and lists only
+ * the commands that declare a `shortcut`. One catalogue driving both surfaces
+ * is the point: a shortcut cannot end up documented but unreachable, or
+ * reachable but undocumented, because there is only one place to add it.
+ *
+ * Keys render as `<kbd>` elements rather than a run of text, so the markup
+ * says what it means.
+ */
+export class ShortcutsOverlay extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["commands", "heading", "hotkey", "open"];
+    }
+    hostEl;
+    focusRestore = new FocusRestore();
+    wasOpen = false;
+    commandsRaw = null;
+    commandsCache = [];
+    onDocumentKeydown = (event) => {
+        if (this.open) {
+            // Escape closes from anywhere. Focus can end up outside the sheet — the
+            // browser chrome, a host that moves it — and a modal that only closes
+            // while it still holds focus is a trap. The sheet's own handler runs
+            // first and clears `open`, so this never dismisses twice.
+            if (event.key === "Escape") {
+                event.preventDefault();
+                this.dismiss();
+            }
+            return;
+        }
+        const hotkey = this.hotkey;
+        if (!hotkey) {
+            return;
+        }
+        // A bare-character hotkey must never fire while someone is typing —
+        // "?" is a legitimate character in every text field on the page.
+        if (isTypingTarget(keyOrigin(event))) {
+            return;
+        }
+        if (event.metaKey || event.ctrlKey || event.altKey) {
+            return;
+        }
+        if (event.key === hotkey) {
+            event.preventDefault();
+            this.open = true;
+        }
+    };
+    get open() {
+        return this.hasAttribute("open");
+    }
+    set open(value) {
+        this.toggleAttribute("open", value);
+    }
+    get heading() {
+        return this.getAttribute("heading") ?? "Keyboard shortcuts";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /**
+     * Character that opens the sheet. Defaults to `?`, the convention. Matched
+     * against the produced character, so the Shift needed to type it is already
+     * accounted for. Set empty to let the host own the trigger.
+     */
+    get hotkey() {
+        const raw = this.getAttribute("hotkey");
+        return raw === null ? "?" : raw;
+    }
+    set hotkey(value) {
+        this.setAttribute("hotkey", value);
+    }
+    /** The same catalogue `box-command-palette` takes; validated per record. */
+    get commands() {
+        const raw = this.getAttribute("commands");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.commandsRaw) {
+            this.commandsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.commandsCache =
+                    Array.isArray(parsed) && parsed.every(isCommandDescriptorRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.commandsCache = [];
+            }
+        }
+        return [...this.commandsCache];
+    }
+    set commands(value) {
+        if (value.length) {
+            this.setAttribute("commands", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("commands");
+    }
+    /** Only the commands that declare a shortcut, in catalogue order. */
+    get documentedCommands() {
+        return groupShortcutCommands(this.commands).flatMap(group => group.commands);
+    }
+    show() {
+        this.open = true;
+    }
+    hide() {
+        this.open = false;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.addEventListener("keydown", this.onDocumentKeydown);
+    }
+    disconnectedCallback() {
+        document.removeEventListener("keydown", this.onDocumentKeydown);
+    }
+    dismiss() {
+        this.dispatchEvent(new CustomEvent("dismissed", { bubbles: true, composed: true }));
+        this.open = false;
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><div part="host"></div>`;
+        this.hostEl = this.shadowRoot.querySelector('[part="host"]');
+    }
+    setupListeners() {
+        this.hostEl.addEventListener("pointerdown", event => {
+            const target = event.target;
+            if (target.closest('[part="sheet"]')) {
+                return;
+            }
+            if (target.closest('[part="backdrop"]')) {
+                this.dismiss();
+            }
+        });
+        this.hostEl.addEventListener("click", event => {
+            if (event.target.closest('[part="close"]')) {
+                this.dismiss();
+            }
+        });
+        this.hostEl.addEventListener("keydown", event => {
+            const keyboardEvent = event;
+            const sheet = this.hostEl.querySelector('[part="sheet"]');
+            if (!sheet) {
+                return;
+            }
+            if (keyboardEvent.key === "Escape") {
+                keyboardEvent.preventDefault();
+                this.dismiss();
+                return;
+            }
+            if (keyboardEvent.key === "Tab") {
+                trapTabKey(keyboardEvent, sheet);
+            }
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        if (!this.open) {
+            const wasOpen = this.wasOpen;
+            this.hostEl.innerHTML = "";
+            this.wasOpen = false;
+            if (wasOpen) {
+                this.focusRestore.restore();
+            }
+            return;
+        }
+        const justOpened = !this.wasOpen;
+        this.wasOpen = true;
+        if (justOpened) {
+            this.focusRestore.capture();
+        }
+        const groups = groupShortcutCommands(this.commands);
+        const sections = groups
+            .map(group => {
+            const rows = group.commands
+                .map(command => {
+                const keys = splitShortcutKeys(command.shortcut ?? "")
+                    .map(key => `<kbd part="key">${escapeHtml(key)}</kbd>`)
+                    .join(`<span part="key-separator" aria-hidden="true">+</span>`);
+                return `
+              <li part="row" data-command-id="${escapeHtml(command.id)}">
+                <span part="row-label">${escapeHtml(command.label)}</span>
+                <span part="keys" aria-label="${escapeHtml(command.shortcut ?? "")}">${keys}</span>
+              </li>
+            `;
+            })
+                .join("");
+            return `<li part="group" data-group-key="${escapeHtml(group.key)}"><span part="group-label">${escapeHtml(group.label)}</span><ul part="rows" role="list">${rows}</ul></li>`;
+        })
+            .join("");
+        this.hostEl.innerHTML = `
+      <div part="backdrop">
+        <div part="sheet" role="dialog" aria-modal="true" aria-label="${escapeHtml(this.heading)}">
+          <div part="header">
+            <h2 part="title">${escapeHtml(this.heading)}</h2>
+            <button type="button" part="close">Close</button>
+          </div>
+          ${groups.length
+            ? `<ul part="groups" role="list">${sections}</ul>`
+            : `<div part="empty">No keyboard shortcuts are defined.</div>`}
+        </div>
+      </div>
+    `;
+        if (justOpened) {
+            this.hostEl.querySelector('[part="close"]')?.focus();
+        }
+    }
+}
+ShortcutsOverlay.register();

package/dist/components/overlays/tooltip.js

@@ -51,7 +51,7 @@ const tooltipStyles = `
     border-radius: ${boeRadius.xlarge};
     border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, rgba(255, 255, 255, 0.08));
     background: var(--boe-token-surface-tooltip-surface, #4e4e4e);
-    color: rgba(255, 255, 255, 0.94);
+    color: #ffffff;
     box-shadow: 0 16px 28px rgba(16, 24, 32, 0.18);
     line-height: 1.45;
   }

package/dist/core/index.d.ts

@@ -4,3 +4,7 @@ export type { EventMap, Unsubscribe } from "./event-emitter.js";
 export { BaseElement } from "./element.js";
 export { FORM_DESCRIPTION_ID, FORM_ERROR_MESSAGE_ID, FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDataFromNamedValues, formDataFromRange, formDescriptionMarkup, formErrorMessageMarkup, getMirroredFormValue, rangeFromFormValue, stringValuesFromFormValue, } from "./form-associated.js";
 export type { FormValue } from "./form-associated.js";
+export { resolveRowWindow, sameRowWindow } from "./virtualize.js";
+export type { RowWindow, WindowMetrics } from "./virtualize.js";
+export { buildOffsetIndex, offsetOfItem, resolveOffsetWindow } from "./offset-window.js";
+export type { OffsetIndex, OffsetWindowMetrics } from "./offset-window.js";

package/dist/core/index.js

@@ -2,3 +2,5 @@ export { Controller } from "./controller.js";
 export { TypedEventEmitter } from "./event-emitter.js";
 export { BaseElement } from "./element.js";
 export { FORM_DESCRIPTION_ID, FORM_ERROR_MESSAGE_ID, FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDataFromNamedValues, formDataFromRange, formDescriptionMarkup, formErrorMessageMarkup, getMirroredFormValue, rangeFromFormValue, stringValuesFromFormValue, } from "./form-associated.js";
+export { resolveRowWindow, sameRowWindow } from "./virtualize.js";
+export { buildOffsetIndex, offsetOfItem, resolveOffsetWindow } from "./offset-window.js";

package/dist/core/offset-window.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Row windowing for lists whose rows are *not* all the same height.
+ *
+ * `resolveRowWindow` (./virtualize.ts) multiplies a row count by one row
+ * height. That is exact and O(1), and it is the right answer for a flat table
+ * of uniform rows — but it cannot describe a surface where the items differ:
+ * a grouped audit log alternates short headings with taller event rows, a
+ * collapsed group contributes only its heading, and an expanded detail row adds
+ * height the count knows nothing about. Feeding those to the fixed-height
+ * engine does not degrade gracefully; the spacers under-report the real height,
+ * the scroll range stops matching the scrollbar, and `scrollTop` maps to the
+ * wrong item. That is why `box-table` refuses to window expandable rows rather
+ * than approximating them.
+ *
+ * The general answer is a cumulative offset index: the running pixel offset of
+ * every item, built once, then binary-searched per scroll. Building is O(n) and
+ * searching is O(log n), which is the right split — heights change when the
+ * data or the collapse state changes, not on every scroll event.
+ *
+ * Heights are still *estimates* until something measures them. This engine
+ * takes whatever heights it is given and is exact with respect to them; keeping
+ * them honest is the caller's job, the same bargain `row-height` strikes.
+ */
+import type { RowWindow } from "./virtualize.js";
+export interface OffsetIndex {
+    /**
+     * Running offsets, length `count + 1`. `offsets[i]` is the top of item `i`;
+     * `offsets[count]` is the total height, so the height of item `i` is
+     * `offsets[i + 1] - offsets[i]` with no special case for the last one.
+     */
+    readonly offsets: readonly number[];
+    readonly count: number;
+    readonly totalHeight: number;
+}
+export interface OffsetWindowMetrics {
+    /** Height of the scrolling viewport, in pixels. */
+    viewportHeight: number;
+    /** Current scroll offset of the viewport, in pixels. */
+    scrollTop: number;
+    /** Extra items rendered above and below the visible band. Default 4. */
+    overscan?: number;
+}
+/**
+ * The cumulative offset index for a list of item heights.
+ *
+ * A non-finite or negative height contributes zero rather than poisoning every
+ * subsequent offset with `NaN`. Heights arrive from measurement and from host
+ * estimates; one bad value should cost that item its space, not break the
+ * scrollbar for the whole collection.
+ */
+export declare const buildOffsetIndex: (heights: readonly number[]) => OffsetIndex;
+/**
+ * The rendered slice for a scroll position, plus the spacer heights.
+ *
+ * Same contract as `resolveRowWindow`, so the two engines are interchangeable
+ * from a component's point of view:
+ * - `paddingTop + (height of the rendered items) + paddingBottom` always equals
+ *   `totalHeight`, so the scroll range never drifts as items scroll by.
+ * - The window always covers the visible band; overscan only ever adds items.
+ * - Degenerate geometry yields an empty window rather than a guess.
+ */
+export declare const resolveOffsetWindow: (index: OffsetIndex, metrics: OffsetWindowMetrics) => RowWindow;
+/**
+ * The pixel offset of an item, for scrolling it into view.
+ *
+ * Out-of-range indices clamp to the ends rather than returning `undefined`:
+ * callers are keyboard handlers reaching for "the last one", and a clamp is
+ * what they would write anyway.
+ */
+export declare const offsetOfItem: (index: OffsetIndex, item: number) => number;

package/dist/core/offset-window.js

@@ -0,0 +1,134 @@
+/**
+ * Row windowing for lists whose rows are *not* all the same height.
+ *
+ * `resolveRowWindow` (./virtualize.ts) multiplies a row count by one row
+ * height. That is exact and O(1), and it is the right answer for a flat table
+ * of uniform rows — but it cannot describe a surface where the items differ:
+ * a grouped audit log alternates short headings with taller event rows, a
+ * collapsed group contributes only its heading, and an expanded detail row adds
+ * height the count knows nothing about. Feeding those to the fixed-height
+ * engine does not degrade gracefully; the spacers under-report the real height,
+ * the scroll range stops matching the scrollbar, and `scrollTop` maps to the
+ * wrong item. That is why `box-table` refuses to window expandable rows rather
+ * than approximating them.
+ *
+ * The general answer is a cumulative offset index: the running pixel offset of
+ * every item, built once, then binary-searched per scroll. Building is O(n) and
+ * searching is O(log n), which is the right split — heights change when the
+ * data or the collapse state changes, not on every scroll event.
+ *
+ * Heights are still *estimates* until something measures them. This engine
+ * takes whatever heights it is given and is exact with respect to them; keeping
+ * them honest is the caller's job, the same bargain `row-height` strikes.
+ */
+const DEFAULT_OVERSCAN = 4;
+const EMPTY_INDEX = { offsets: [0], count: 0, totalHeight: 0 };
+/**
+ * The cumulative offset index for a list of item heights.
+ *
+ * A non-finite or negative height contributes zero rather than poisoning every
+ * subsequent offset with `NaN`. Heights arrive from measurement and from host
+ * estimates; one bad value should cost that item its space, not break the
+ * scrollbar for the whole collection.
+ */
+export const buildOffsetIndex = (heights) => {
+    if (heights.length === 0)
+        return EMPTY_INDEX;
+    const offsets = new Array(heights.length + 1);
+    offsets[0] = 0;
+    let running = 0;
+    for (let index = 0; index < heights.length; index++) {
+        const height = heights[index] ?? 0;
+        running += Number.isFinite(height) && height > 0 ? height : 0;
+        offsets[index + 1] = running;
+    }
+    return { offsets, count: heights.length, totalHeight: running };
+};
+/**
+ * The index of the last item whose top is at or before `offset`.
+ *
+ * Binary search rather than a scan: this runs per scroll frame, and a linear
+ * walk over ten thousand offsets is the cost windowing exists to avoid.
+ * Zero-height items make offsets non-strictly-increasing, so ties resolve to
+ * the *first* of a run — the alternative is a window that starts inside a
+ * cluster of collapsed items and leaves the one above it unrendered.
+ */
+const findItemAt = (offsets, count, offset) => {
+    let low = 0;
+    let high = count - 1;
+    let found = 0;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        if ((offsets[mid] ?? 0) <= offset) {
+            found = mid;
+            low = mid + 1;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    // Walk back over a run of equal offsets (zero-height items) so the window
+    // starts at the first item sharing this offset, not an arbitrary one.
+    const at = offsets[found] ?? 0;
+    while (found > 0 && (offsets[found - 1] ?? 0) === at)
+        found--;
+    return found;
+};
+/**
+ * The rendered slice for a scroll position, plus the spacer heights.
+ *
+ * Same contract as `resolveRowWindow`, so the two engines are interchangeable
+ * from a component's point of view:
+ * - `paddingTop + (height of the rendered items) + paddingBottom` always equals
+ *   `totalHeight`, so the scroll range never drifts as items scroll by.
+ * - The window always covers the visible band; overscan only ever adds items.
+ * - Degenerate geometry yields an empty window rather than a guess.
+ */
+export const resolveOffsetWindow = (index, metrics) => {
+    const { offsets, count, totalHeight } = index;
+    const overscan = Math.max(0, Math.floor(metrics.overscan ?? DEFAULT_OVERSCAN));
+    if (count <= 0 || totalHeight <= 0) {
+        return { startIndex: 0, endIndex: 0, paddingTop: 0, paddingBottom: 0, totalHeight };
+    }
+    if (metrics.viewportHeight <= 0) {
+        // An unmeasured viewport is the normal state during first paint and under
+        // jsdom. Rendering everything there would defeat the purpose exactly when
+        // it matters most.
+        return { startIndex: 0, endIndex: 0, paddingTop: 0, paddingBottom: totalHeight, totalHeight };
+    }
+    // Clamp a bounced or past-the-end scrollTop: rubber-banding reports both, and
+    // neither may produce a window outside the collection.
+    const maxScroll = Math.max(0, totalHeight - metrics.viewportHeight);
+    const top = Math.min(Math.max(0, metrics.scrollTop), maxScroll);
+    const bottom = top + metrics.viewportHeight;
+    const firstVisible = findItemAt(offsets, count, top);
+    // Last item that starts before the viewport's bottom edge. Scanning forward
+    // from firstVisible is bounded by what fits on screen plus overscan, which is
+    // the point of windowing — no walk over the whole collection.
+    let lastVisible = firstVisible;
+    while (lastVisible + 1 < count && (offsets[lastVisible + 1] ?? 0) < bottom) {
+        lastVisible++;
+    }
+    const startIndex = Math.max(0, firstVisible - overscan);
+    const endIndex = Math.min(count, lastVisible + 1 + overscan);
+    return {
+        startIndex,
+        endIndex,
+        paddingTop: offsets[startIndex] ?? 0,
+        paddingBottom: totalHeight - (offsets[endIndex] ?? totalHeight),
+        totalHeight,
+    };
+};
+/**
+ * The pixel offset of an item, for scrolling it into view.
+ *
+ * Out-of-range indices clamp to the ends rather than returning `undefined`:
+ * callers are keyboard handlers reaching for "the last one", and a clamp is
+ * what they would write anyway.
+ */
+export const offsetOfItem = (index, item) => {
+    if (index.count <= 0)
+        return 0;
+    const clamped = Math.min(Math.max(0, Math.floor(item)), index.count);
+    return index.offsets[clamped] ?? 0;
+};

package/dist/core/virtualize.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Row windowing for long lists.
+ *
+ * A ten-thousand-row audit log rendered whole is ten thousand DOM rows: the
+ * first paint stalls, every subsequent patch walks the lot, and the browser
+ * holds layout boxes nobody will ever scroll to. Windowing renders only the
+ * rows near the viewport and pads the rest with spacer height, so the scrollbar
+ * still describes the whole collection.
+ *
+ * The arithmetic lives here, pure, for the usual reason: jsdom has no layout,
+ * so a DOM-level test of a windowed surface can only ever observe zeroes. It is
+ * shared rather than per-component so `box-table`, `box-audit-log`, and
+ * `box-tree-grid` cannot drift into three different definitions of "near".
+ *
+ * Fixed row height only. Measured/variable heights are a different algorithm
+ * (a cumulative offset index that reflows as rows are measured); pretending one
+ * function covers both is how windowing engines end up subtly wrong at the
+ * boundaries.
+ */
+export interface WindowMetrics {
+    /** Total rows in the collection, not the rendered subset. */
+    totalRows: number;
+    /** Fixed height of one row, in pixels. */
+    rowHeight: number;
+    /** Height of the scrolling viewport, in pixels. */
+    viewportHeight: number;
+    /** Current scroll offset of the viewport, in pixels. */
+    scrollTop: number;
+    /**
+     * Extra rows rendered above and below the visible band, so a fast scroll
+     * does not expose blank space before the next frame. Default 4.
+     */
+    overscan?: number;
+}
+export interface RowWindow {
+    /** First rendered row index, inclusive. */
+    startIndex: number;
+    /** Last rendered row index, exclusive — safe for `slice(startIndex, endIndex)`. */
+    endIndex: number;
+    /** Spacer height above the rendered rows, in pixels. */
+    paddingTop: number;
+    /** Spacer height below the rendered rows, in pixels. */
+    paddingBottom: number;
+    /** Height of the whole collection, for the scroll range. */
+    totalHeight: number;
+}
+/**
+ * The rendered slice for a scroll position, plus the spacer heights that keep
+ * the scrollbar honest.
+ *
+ * Guarantees callers can rely on:
+ * - `paddingTop + (endIndex - startIndex) * rowHeight + paddingBottom` always
+ *   equals `totalHeight`, so the scroll range never drifts as rows scroll by —
+ *   a windowed list whose height wobbles makes the scrollbar jump under the
+ *   pointer.
+ * - The window always covers the visible band; overscan only ever adds rows.
+ * - Degenerate geometry (no rows, unmeasured viewport, non-positive row height)
+ *   yields an empty window rather than a guess. An unmeasured viewport is the
+ *   normal state during first paint and under jsdom, and rendering *everything*
+ *   there would defeat the purpose at exactly the moment it matters most.
+ */
+export declare const resolveRowWindow: (metrics: WindowMetrics) => RowWindow;
+/**
+ * Whether a scroll moved far enough to need a re-render.
+ *
+ * Scroll fires continuously; re-rendering on every event would rebuild the row
+ * markup dozens of times per second to show the same rows. Comparing the
+ * resolved window is cheaper and exact — the render is needed precisely when
+ * the slice changes.
+ */
+export declare const sameRowWindow: (a: RowWindow, b: RowWindow) => boolean;