@unofficialbox/box-open-elements 0.6.0 → 0.8.0

package/dist/patterns/audit/audit-log.js

@@ -2,9 +2,16 @@ import { AUDIT_GROUP_BY_LABELS, AUDIT_GROUP_BY_VALUES, filterAuditEvents, groupA
 import { auditToneColor, escapeHtml, formatAuditTimestamp, resolveReferenceTime, } from "./shared.js";
 import { isSafeHref } from "../internal/safe-href.js";
 import { isTimelineEventRecord, resolveTimelineTone } from "../timeline/types.js";
-import { BaseElement } from "../../core/index.js";
+import { BaseElement, sameRowWindow } from "../../core/index.js";
+import { buildAuditIndex, flattenAuditRows, planAuditWindow } from "./window.js";
 import { boeInputControlStyles, boePanel, boeRadius } from "../../foundations/geometry/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+/**
+ * How many times the element will adopt a fresh height measurement for one row
+ * set. A hard stop, not a tuning knob: without it a non-uniform list can adopt,
+ * re-window, re-measure and adopt again on every animation frame forever.
+ */
+const MAX_HEIGHT_ADOPTIONS = 3;
 const DEFAULT_TAG_NAME = "box-audit-log";
 /** Facet attribute ↔ `AuditFacets` key. One row per facet, no other mapping. */
 const FACET_ATTRIBUTES = [
@@ -144,6 +151,20 @@ const elementStyles = `
           gap: 0.5rem;
         }
 
+        /* Windowing needs a bounded viewport to scroll within:
+           --boe-audit-height is the host's knob, defaulting to a page-sized
+           band. */
+        :host([virtualize]) [part="groups"] {
+          max-block-size: var(--boe-audit-height, 32rem);
+          overflow-y: auto;
+        }
+
+        [part="spacer"] {
+          /* The grid gap must not apply to the spacers, or the scroll range
+             gains a gap's height at each end and the content drifts. */
+          margin-block: calc(-0.25rem);
+        }
+
         [part="group"] {
           border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
           border-radius: ${boeRadius.med};
@@ -321,8 +342,9 @@ const elementStyles = `
  * sections with counts, narrowed by facets and a date range, drillable to one
  * workflow run by correlation id, and exportable as CSV.
  *
- * Aggregation is client-side and pure. Server-side paging and row
- * virtualization for production-scale logs are tracked depth limitations.
+ * Aggregation is client-side and pure. `virtualize` windows the log for
+ * production-scale volumes; server-side paging remains a tracked depth
+ * limitation.
  */
 export class AuditLog extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
@@ -338,6 +360,9 @@ export class AuditLog extends BaseElement {
             "group-by",
             "heading",
             "reference-time",
+            "virtualize",
+            "row-height",
+            "heading-height",
         ];
     }
     toolbarEl;
@@ -356,6 +381,15 @@ export class AuditLog extends BaseElement {
     titleEl;
     /** Section keys the reader has collapsed. Absent means expanded. */
     collapsedGroups = new Set();
+    /** The row window the last render used; null when it rendered everything. */
+    lastWindow = null;
+    scrollFrame = 0;
+    measuredHeights = null;
+    measureFrame = 0;
+    /** Row set the adoption budget below is counted against. */
+    adoptedFor = null;
+    adoptionCount = 0;
+    viewportObserver = null;
     contentSignature = "";
     optionsSignature = "";
     /** Raw `events` attribute the parse cache was built from. */
@@ -447,6 +481,16 @@ export class AuditLog extends BaseElement {
     get visibleEvents() {
         return filterAuditEvents(this.events, this.facets);
     }
+    /**
+     * The sections the current facets and grouping produce.
+     *
+     * Public because windowing takes away the alternative: a host used to be
+     * able to read the sections off the DOM, and once only a slice is rendered,
+     * that stops being the whole picture.
+     */
+    get groups() {
+        return this.currentGroups();
+    }
     toggleGroup(key, expanded) {
         const next = expanded ?? this.collapsedGroups.has(key);
         if (next) {
@@ -494,6 +538,48 @@ export class AuditLog extends BaseElement {
         }));
         return csv;
     }
+    /**
+     * Watch the scroller so a measurable — or resized — viewport re-plans.
+     *
+     * Separate from `setupListeners` because that runs *once*, on the element's
+     * first connection, while `disconnectedCallback` tears the observer down
+     * every time. A log removed and re-inserted would otherwise come back with
+     * its listeners intact and its observer gone, so resizing its container
+     * would silently stop re-planning. Idempotent, so both callers are safe.
+     */
+    observeViewport() {
+        if (this.viewportObserver || typeof ResizeObserver === "undefined")
+            return;
+        this.viewportObserver = new ResizeObserver(() => {
+            if (!this.virtualize)
+                return;
+            const next = this.currentPlan().window;
+            if (this.lastWindow && sameRowWindow(this.lastWindow, next))
+                return;
+            this.update();
+        });
+        this.viewportObserver.observe(this.groupsEl);
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Re-arm after a disconnect; no-op on the first connection, where
+        // setupListeners has already done it.
+        this.observeViewport();
+    }
+    disconnectedCallback() {
+        // The observer holds a reference to the scroller and the pending frames
+        // hold one to the element; a log removed mid-scroll should not keep either
+        // alive, or re-render into a shadow root nobody is looking at.
+        this.viewportObserver?.disconnect();
+        this.viewportObserver = null;
+        if (this.scrollFrame)
+            cancelAnimationFrame(this.scrollFrame);
+        if (this.measureFrame)
+            cancelAnimationFrame(this.measureFrame);
+        this.scrollFrame = 0;
+        this.measureFrame = 0;
+        super.disconnectedCallback?.();
+    }
     attributeChangedCallback(name, oldValue, newValue) {
         // A different grouping dimension mints different section keys, so the
         // collapse state from the old dimension cannot be carried over.
@@ -502,11 +588,160 @@ export class AuditLog extends BaseElement {
         }
         super.attributeChangedCallback(name, oldValue, newValue);
     }
+    /**
+     * Render only the sections near the viewport. Opt-in for the same reason
+     * `box-table`'s is: a windowed surface needs a bounded height to scroll
+     * within, and silently windowing an unbounded one would render nothing.
+     *
+     * Unlike the table, this *can* window a grouped, variable-height surface —
+     * it plans over a cumulative offset index rather than a row count times a
+     * row height. Grouping is the whole point of an audit log, so refusing to
+     * window it would mean refusing the only shape it comes in.
+     */
+    get virtualize() {
+        return this.hasAttribute("virtualize");
+    }
+    set virtualize(value) {
+        this.toggleAttribute("virtualize", Boolean(value));
+    }
+    /**
+     * Starting height estimates, in pixels — not contracts. The real heights
+     * depend on density, font, and how much an event's summary wraps; after the
+     * first paint the element measures one of each and uses that instead.
+     */
+    get rowHeight() {
+        return this.measuredHeights?.event ?? this.declaredHeight("row-height", 76);
+    }
+    get headingHeight() {
+        return this.measuredHeights?.heading ?? this.declaredHeight("heading-height", 40);
+    }
+    set rowHeight(value) {
+        this.measuredHeights = null;
+        this.setAttribute("row-height", String(value));
+    }
+    set headingHeight(value) {
+        this.measuredHeights = null;
+        this.setAttribute("heading-height", String(value));
+    }
+    declaredHeight(attribute, fallback) {
+        const raw = Number(this.getAttribute(attribute));
+        return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+    }
+    /** The window the last render used, or null when it rendered every section. */
+    get renderedWindow() {
+        return this.virtualize ? this.lastWindow : null;
+    }
+    /**
+     * Adopt the real rendered heights, once, when they differ from the ones the
+     * last plan used. Re-planning with the measured heights settles immediately —
+     * the next measurement matches — so this cannot loop.
+     */
+    /** Mean rendered height of the elements matching a part, or 0 if none. */
+    meanHeight(part) {
+        const nodes = Array.from(this.groupsEl.querySelectorAll(`[part="${part}"]`));
+        if (nodes.length === 0)
+            return 0;
+        const total = nodes.reduce((sum, node) => sum + node.getBoundingClientRect().height, 0);
+        return total / nodes.length;
+    }
+    /**
+     * Adopt the real rendered heights when they differ from the ones in use.
+     *
+     * Two things here exist because the obvious version ran away. Sampling *one*
+     * event row and adopting its height looks fine and is not: event rows are not
+     * uniform — `summary`, `evidence` and `correlationId` are each optional — so
+     * adopting the first rendered row's height moves the window, which renders a
+     * different first row, which measures differently, which moves the window.
+     * Measured in Chromium with every third event several lines taller: **55 full
+     * rebuilds in 0.9 seconds while nothing was scrolling**, the sampled height
+     * flipping between 33px and 166.5px.
+     *
+     * So: average across every rendered row rather than sampling one, which makes
+     * the estimate both more representative and far less sensitive to which rows
+     * happen to be on screen. And bound the adoptions per row set anyway, because
+     * "the average is stable" is an argument about typical data, and this is the
+     * code path where being wrong costs a frame-rate collapse rather than a
+     * slightly wrong scrollbar.
+     */
+    measureRowHeights() {
+        if (!this.virtualize || this.measureFrame)
+            return;
+        const signature = this.heightSignature();
+        if (signature !== this.adoptedFor) {
+            this.adoptedFor = signature;
+            this.adoptionCount = 0;
+        }
+        if (this.adoptionCount >= MAX_HEIGHT_ADOPTIONS)
+            return;
+        const headingHeight = this.meanHeight("group-heading");
+        const eventHeight = this.meanHeight("event");
+        if (headingHeight <= 0 || eventHeight <= 0)
+            return;
+        if (Math.abs(headingHeight - this.headingHeight) < 1 &&
+            Math.abs(eventHeight - this.rowHeight) < 1) {
+            return;
+        }
+        this.adoptionCount++;
+        this.measuredHeights = { heading: headingHeight, event: eventHeight };
+        this.measureFrame = requestAnimationFrame(() => {
+            this.measureFrame = 0;
+            this.update();
+        });
+    }
+    /**
+     * What counts as "the same row set" for the adoption budget: change the data,
+     * the grouping, the filters or the collapse state and the rows genuinely
+     * differ, so measuring again is warranted.
+     */
+    heightSignature() {
+        return JSON.stringify([
+            this.getAttribute("events") ?? "",
+            this.groupBy,
+            this.facets,
+            [...this.collapsedGroups].sort(),
+        ]);
+    }
+    currentPlan() {
+        const { rows, index } = this.cachedRows();
+        return planAuditWindow(rows, { heading: this.headingHeight, event: this.rowHeight }, {
+            viewportHeight: this.groupsEl.clientHeight,
+            scrollTop: this.groupsEl.scrollTop,
+            contentHeight: this.groupsEl.scrollHeight,
+        }, index);
+    }
     now() {
         return resolveReferenceTime(this.getAttribute("reference-time"));
     }
+    /**
+     * Grouping, flattening and indexing for the current data, computed once and
+     * reused until something that affects them changes.
+     *
+     * The scroll path asks "did the window move?" on every frame that is not
+     * skipped, and answering it used to re-parse the whole `events` attribute,
+     * re-filter, re-group, re-flatten and rebuild the offset array — then
+     * `update()` did all of it again. That is O(n) twice per frame on a surface
+     * whose entire purpose is not being O(n) at scale.
+     */
+    rowCache = null;
+    cachedRows() {
+        const heights = { heading: this.headingHeight, event: this.rowHeight };
+        const signature = JSON.stringify([
+            this.getAttribute("events") ?? "",
+            this.groupBy,
+            this.facets,
+            this.referenceTime,
+            [...this.collapsedGroups].sort(),
+            heights,
+        ]);
+        if (this.rowCache?.signature === signature)
+            return this.rowCache;
+        const groups = groupAuditEvents(this.visibleEvents, this.groupBy, this.now());
+        const rows = flattenAuditRows(groups, this.collapsedGroups);
+        this.rowCache = { signature, groups, rows, index: buildAuditIndex(rows, heights) };
+        return this.rowCache;
+    }
     currentGroups() {
-        return groupAuditEvents(this.visibleEvents, this.groupBy, this.now());
+        return this.cachedRows().groups;
     }
     patchFacets(patch) {
         this.facets = { ...this.facets, ...patch };
@@ -545,9 +780,14 @@ export class AuditLog extends BaseElement {
       </li>
     `;
     }
-    groupHtml(group, index) {
+    groupHtml(group, index, slice) {
         const toggleId = `audit-group-toggle-${String(index)}`;
         const bodyId = `audit-group-body-${String(index)}`;
+        // Windowed: only the events inside the window. The heading always renders
+        // for an intersecting section — [part="group-body"] is aria-labelledby the
+        // toggle inside it, so a section without its heading is both unlabelled and
+        // impossible to collapse.
+        const events = slice ? group.events.slice(slice.start, slice.end) : group.events;
         const actors = group.actorCount
             ? ` · ${String(group.actorCount)} ${group.actorCount === 1 ? "actor" : "actors"}`
             : "";
@@ -560,7 +800,7 @@ export class AuditLog extends BaseElement {
           </button>
         </h3>
         <div part="group-body" id="${bodyId}" role="region" aria-labelledby="${toggleId}">
-          <ol part="events" role="list">${group.events.map(event => this.eventHtml(event)).join("")}</ol>
+          <ol part="events" role="list"${slice && slice.start > 0 ? ` start="${String(slice.start + 1)}"` : ""}>${events.map(event => this.eventHtml(event)).join("")}</ol>
         </div>
       </section>
     `;
@@ -621,6 +861,27 @@ export class AuditLog extends BaseElement {
         this.emptyEl = root.querySelector('[part="empty"]');
     }
     setupListeners() {
+        // A windowed surface cannot bootstrap itself from an unmeasured viewport:
+        // an empty scroller is zero pixels tall, a zero-height viewport plans an
+        // empty window, and an empty window renders nothing to measure. Left alone
+        // the log stays blank until something else happens to trigger a render.
+        // The observer breaks that circle on the first layout, and keeps earning
+        // its place afterwards — a resized container changes how much fits.
+        this.observeViewport();
+        // Scroll fires continuously; coalesce to one re-render per frame, and skip
+        // entirely while the resolved slice is unchanged — most scroll events move
+        // the viewport within the sections already rendered.
+        this.groupsEl.addEventListener("scroll", () => {
+            if (!this.virtualize || this.scrollFrame)
+                return;
+            this.scrollFrame = requestAnimationFrame(() => {
+                this.scrollFrame = 0;
+                const next = this.currentPlan().window;
+                if (this.lastWindow && sameRowWindow(this.lastWindow, next))
+                    return;
+                this.update();
+            });
+        }, { passive: true });
         // The toolbar is built once and patched in place, so a select stays open
         // and a half-typed date survives every re-render of the sections below.
         this.toolbarEl.addEventListener("click", event => {
@@ -755,11 +1016,23 @@ export class AuditLog extends BaseElement {
                 : `Showing ${String(visible.length)} of ${String(all.length)} events in ${String(groups.length)} ${groups.length === 1 ? "group" : "groups"}`;
         // The section markup depends on content only. Collapse state is applied
         // separately below, so expanding a section never rebuilds the log.
+        // Windowed renders depend on the scroll position too, so the resolved
+        // slice joins the signature — otherwise scrolling would keep the sections
+        // that were already on screen and never draw the ones scrolled into view.
+        const plan = this.virtualize ? this.currentPlan() : null;
+        this.lastWindow = plan?.window ?? null;
         const contentSignature = JSON.stringify([
             this.getAttribute("events") ?? "",
             groupBy,
             facets,
             this.referenceTime,
+            // The whole rendered geometry, not just the slice: collapsing a section
+            // *below* the window leaves the slice and the top spacer untouched while
+            // making the log shorter, and a stale bottom spacer outlives the content
+            // it described.
+            plan
+                ? [plan.window.startIndex, plan.window.endIndex, plan.paddingTop, plan.paddingBottom]
+                : null,
         ]);
         if (contentSignature !== this.contentSignature) {
             this.contentSignature = contentSignature;
@@ -771,7 +1044,19 @@ export class AuditLog extends BaseElement {
                     eventId: active.getAttribute("data-event-id"),
                 }
                 : null;
-            this.groupsEl.innerHTML = groups.map((group, index) => this.groupHtml(group, index)).join("");
+            const spacer = (height, position) => height > 0
+                ? `<div part="spacer" data-position="${position}" aria-hidden="true" style="block-size:${String(height)}px;"></div>`
+                : "";
+            this.groupsEl.innerHTML = plan
+                ? spacer(plan.paddingTop, "top") +
+                    plan.groups
+                        .map(planned => this.groupHtml(groups[planned.groupIndex], planned.groupIndex, {
+                        start: planned.eventStart,
+                        end: planned.eventEnd,
+                    }))
+                        .join("") +
+                    spacer(plan.paddingBottom, "bottom")
+                : groups.map((group, index) => this.groupHtml(group, index)).join("");
             if (focusKey?.part) {
                 const restored = Array.from(this.groupsEl.querySelectorAll(`[part="${focusKey.part}"]`)).find(node => node.getAttribute("data-group-key") === focusKey.groupKey &&
                     node.getAttribute("data-event-id") === focusKey.eventId);
@@ -789,6 +1074,9 @@ export class AuditLog extends BaseElement {
         }
         this.groupsEl.hidden = groups.length === 0;
         this.emptyEl.hidden = groups.length > 0;
+        if (this.virtualize) {
+            this.measureRowHeights();
+        }
     }
 }
 AuditLog.register();

package/dist/patterns/audit/window.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Windowing plan for the grouped audit log.
+ *
+ * `box-table` can refuse to window expandable rows because a flat table has an
+ * alternative: render everything. A ten-thousand-event audit log does not —
+ * grouping is the whole point of the surface, and grouped rows are exactly what
+ * fixed-height windowing cannot describe. So this is the case that needs the
+ * cumulative-offset engine (`src/core/offset-window.ts`) rather than an excuse.
+ *
+ * The log is windowed as one flat sequence of rows — each group contributes a
+ * heading row, then one row per event while it is expanded — because a single
+ * day's section can hold thousands of events on its own. Windowing whole groups
+ * would leave that case exactly as slow as it is now.
+ *
+ * The rendered DOM is still nested, so the flat window has to be turned back
+ * into sections. That is what `planAuditWindow` does, and the reason it exists
+ * as a pure function is the usual one: jsdom has no layout, so a DOM-level test
+ * of a windowed surface can only ever observe zeroes.
+ *
+ * ## The straddling group
+ *
+ * A group whose heading has scrolled above the viewport still needs its heading
+ * rendered: `[part="group-body"]` is `aria-labelledby` its toggle, and a
+ * section that arrives without its own heading is both unlabelled and
+ * impossible to collapse. So an intersecting group always renders its heading —
+ * which means rendering one heading the offset index has already accounted for
+ * in `paddingTop`.
+ *
+ * At most one group can straddle the top edge, so that is a single correction:
+ * take the heading's height back out of the top spacer. The events below then
+ * land where the scrollbar says they should, and the reclaimed heading sits
+ * directly above them.
+ */
+import type { OffsetIndex } from "../../core/offset-window.js";
+import type { RowWindow } from "../../core/virtualize.js";
+import type { AuditGroup } from "./types.js";
+/** One row of the flattened log: a section heading, or an event inside one. */
+export interface AuditRow {
+    kind: "heading" | "event";
+    /** Index into the groups array. */
+    groupIndex: number;
+    /** Index within that group's events; absent on a heading row. */
+    eventIndex?: number;
+}
+export interface AuditRowHeights {
+    heading: number;
+    event: number;
+}
+/** What to render for one group intersecting the window. */
+export interface PlannedGroup {
+    groupIndex: number;
+    /** First event of this group to render, inclusive. */
+    eventStart: number;
+    /** Last event of this group to render, exclusive. */
+    eventEnd: number;
+    /**
+     * True when this group's own heading row is inside the window. False means
+     * the heading scrolled above the viewport and is being rendered anyway —
+     * `paddingTop` has already been corrected for it.
+     */
+    headingInWindow: boolean;
+}
+export interface AuditWindowPlan {
+    groups: PlannedGroup[];
+    paddingTop: number;
+    paddingBottom: number;
+    totalHeight: number;
+    /** The underlying row window, for cheap "did the slice change?" comparisons. */
+    window: RowWindow;
+}
+/**
+ * The log as a flat row sequence. A collapsed group contributes its heading
+ * only — which is exactly why the heights vary and the fixed-height engine
+ * cannot describe this surface.
+ */
+export declare const flattenAuditRows: (groups: readonly AuditGroup[], collapsedKeys: ReadonlySet<string>) => AuditRow[];
+export declare const auditRowHeights: (rows: readonly AuditRow[], heights: AuditRowHeights) => number[];
+/**
+ * The offset index for a row set, so a caller can build it once and reuse it
+ * across scroll frames. The index only changes when the rows or the heights do.
+ */
+export declare const buildAuditIndex: (rows: readonly AuditRow[], heights: AuditRowHeights) => OffsetIndex;
+/**
+ * Which sections to render, and the spacer heights around them.
+ *
+ * Returns an empty plan for an empty window rather than a plan with no groups
+ * and stale padding, so a caller can treat "nothing to render" uniformly.
+ */
+export declare const planAuditWindow: (rows: readonly AuditRow[], heights: AuditRowHeights, viewport: {
+    viewportHeight: number;
+    scrollTop: number;
+    overscan?: number;
+    /**
+     * The scroller's real `scrollHeight`, when the caller can measure it.
+     *
+     * Two heights per row kind is an estimate, and over thousands of rows the
+     * estimate and the rendered reality drift apart — measured at ~0.9% on a
+     * 2,000-event log, which sounds harmless and is not: if the estimate runs
+     * *long*, scrolling to the real bottom leaves the plan believing there is
+     * still a screenful below, and the last rows can never be reached. Content
+     * you cannot scroll to is worse than a slightly wrong scrollbar.
+     *
+     * Given the real height, the scroll position is read as a fraction of the
+     * real range and applied to the estimated one, so both ends line up: at the
+     * bottom of the scroller the plan is at the bottom of the log.
+     */
+    contentHeight?: number;
+}, 
+/**
+ * A prebuilt index for these rows and heights, from `buildAuditIndex`.
+ *
+ * Optional purely for callers that plan once. The scroll path should pass one:
+ * building the index is O(n), and rebuilding it per frame would put the O(n)
+ * back that the binary search exists to remove.
+ */
+prebuilt?: OffsetIndex) => AuditWindowPlan;

package/dist/patterns/audit/window.js

@@ -0,0 +1,132 @@
+/**
+ * Windowing plan for the grouped audit log.
+ *
+ * `box-table` can refuse to window expandable rows because a flat table has an
+ * alternative: render everything. A ten-thousand-event audit log does not —
+ * grouping is the whole point of the surface, and grouped rows are exactly what
+ * fixed-height windowing cannot describe. So this is the case that needs the
+ * cumulative-offset engine (`src/core/offset-window.ts`) rather than an excuse.
+ *
+ * The log is windowed as one flat sequence of rows — each group contributes a
+ * heading row, then one row per event while it is expanded — because a single
+ * day's section can hold thousands of events on its own. Windowing whole groups
+ * would leave that case exactly as slow as it is now.
+ *
+ * The rendered DOM is still nested, so the flat window has to be turned back
+ * into sections. That is what `planAuditWindow` does, and the reason it exists
+ * as a pure function is the usual one: jsdom has no layout, so a DOM-level test
+ * of a windowed surface can only ever observe zeroes.
+ *
+ * ## The straddling group
+ *
+ * A group whose heading has scrolled above the viewport still needs its heading
+ * rendered: `[part="group-body"]` is `aria-labelledby` its toggle, and a
+ * section that arrives without its own heading is both unlabelled and
+ * impossible to collapse. So an intersecting group always renders its heading —
+ * which means rendering one heading the offset index has already accounted for
+ * in `paddingTop`.
+ *
+ * At most one group can straddle the top edge, so that is a single correction:
+ * take the heading's height back out of the top spacer. The events below then
+ * land where the scrollbar says they should, and the reclaimed heading sits
+ * directly above them.
+ */
+import { buildOffsetIndex, resolveOffsetWindow } from "../../core/offset-window.js";
+/**
+ * The log as a flat row sequence. A collapsed group contributes its heading
+ * only — which is exactly why the heights vary and the fixed-height engine
+ * cannot describe this surface.
+ */
+export const flattenAuditRows = (groups, collapsedKeys) => {
+    const rows = [];
+    for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+        const group = groups[groupIndex];
+        rows.push({ kind: "heading", groupIndex });
+        if (collapsedKeys.has(group.key))
+            continue;
+        for (let eventIndex = 0; eventIndex < group.events.length; eventIndex++) {
+            rows.push({ kind: "event", groupIndex, eventIndex });
+        }
+    }
+    return rows;
+};
+export const auditRowHeights = (rows, heights) => rows.map(row => (row.kind === "heading" ? heights.heading : heights.event));
+/**
+ * The scroll offset to plan at, given where the scroller actually is.
+ *
+ * Without a measured `contentHeight` this is the raw offset. With one, it is
+ * the same *fraction* of the estimated range as the reader is through the real
+ * one — which is what makes the two ends agree.
+ */
+const mapScrollToEstimate = (viewport, totalHeight) => {
+    const { contentHeight, scrollTop, viewportHeight } = viewport;
+    if (contentHeight === undefined || !Number.isFinite(contentHeight))
+        return scrollTop;
+    const realRange = contentHeight - viewportHeight;
+    const estimatedRange = totalHeight - viewportHeight;
+    // Nothing scrolls, or the estimate already agrees closely enough that the
+    // mapping would only add rounding noise.
+    if (realRange <= 0 || estimatedRange <= 0)
+        return scrollTop;
+    const fraction = Math.min(Math.max(0, scrollTop / realRange), 1);
+    return fraction * estimatedRange;
+};
+/**
+ * The offset index for a row set, so a caller can build it once and reuse it
+ * across scroll frames. The index only changes when the rows or the heights do.
+ */
+export const buildAuditIndex = (rows, heights) => buildOffsetIndex(auditRowHeights(rows, heights));
+/**
+ * Which sections to render, and the spacer heights around them.
+ *
+ * Returns an empty plan for an empty window rather than a plan with no groups
+ * and stale padding, so a caller can treat "nothing to render" uniformly.
+ */
+export const planAuditWindow = (rows, heights, viewport, 
+/**
+ * A prebuilt index for these rows and heights, from `buildAuditIndex`.
+ *
+ * Optional purely for callers that plan once. The scroll path should pass one:
+ * building the index is O(n), and rebuilding it per frame would put the O(n)
+ * back that the binary search exists to remove.
+ */
+prebuilt) => {
+    const index = prebuilt ?? buildAuditIndex(rows, heights);
+    const window = resolveOffsetWindow(index, {
+        ...viewport,
+        scrollTop: mapScrollToEstimate(viewport, index.totalHeight),
+    });
+    const plan = {
+        groups: [],
+        paddingTop: window.paddingTop,
+        paddingBottom: window.paddingBottom,
+        totalHeight: window.totalHeight,
+        window,
+    };
+    if (window.endIndex <= window.startIndex)
+        return plan;
+    let current = null;
+    for (let rowIndex = window.startIndex; rowIndex < window.endIndex; rowIndex++) {
+        const row = rows[rowIndex];
+        if (!current || current.groupIndex !== row.groupIndex) {
+            current = {
+                groupIndex: row.groupIndex,
+                eventStart: row.kind === "event" ? row.eventIndex : 0,
+                eventEnd: row.kind === "event" ? row.eventIndex : 0,
+                headingInWindow: row.kind === "heading",
+            };
+            plan.groups.push(current);
+        }
+        if (row.kind === "event") {
+            current.eventEnd = row.eventIndex + 1;
+        }
+    }
+    // The straddling group: its heading is above the window but will be rendered,
+    // so give its height back from the top spacer. Only the first planned group
+    // can be in this position — every later one starts at its own heading.
+    const first = plan.groups[0];
+    if (first && !first.headingInWindow) {
+        plan.paddingTop = Math.max(0, plan.paddingTop - heights.heading);
+    }
+    return plan;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",