@unofficialbox/box-open-elements 0.6.0 → 0.7.0

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;

package/dist/core/virtualize.js

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+const DEFAULT_OVERSCAN = 4;
+/**
+ * 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 const resolveRowWindow = (metrics) => {
+    const { totalRows, rowHeight, viewportHeight, scrollTop } = metrics;
+    const overscan = Math.max(0, Math.floor(metrics.overscan ?? DEFAULT_OVERSCAN));
+    if (totalRows <= 0 || rowHeight <= 0) {
+        return { startIndex: 0, endIndex: 0, paddingTop: 0, paddingBottom: 0, totalHeight: 0 };
+    }
+    const totalHeight = totalRows * rowHeight;
+    if (viewportHeight <= 0) {
+        return { startIndex: 0, endIndex: 0, paddingTop: 0, paddingBottom: totalHeight, totalHeight };
+    }
+    // Clamp the scroll offset: a bounced/rubber-banded scrollTop (negative, or
+    // past the end) must not produce a window outside the collection.
+    const maxScroll = Math.max(0, totalHeight - viewportHeight);
+    const offset = Math.min(Math.max(0, scrollTop), maxScroll);
+    const firstVisible = Math.floor(offset / rowHeight);
+    // ceil of the band, +1 for the row straddling the bottom edge.
+    const visibleCount = Math.ceil(viewportHeight / rowHeight) + 1;
+    const startIndex = Math.max(0, firstVisible - overscan);
+    const endIndex = Math.min(totalRows, firstVisible + visibleCount + overscan);
+    const paddingTop = startIndex * rowHeight;
+    const paddingBottom = totalHeight - endIndex * rowHeight;
+    return { startIndex, endIndex, paddingTop, paddingBottom, totalHeight };
+};
+/**
+ * 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 const sameRowWindow = (a, b) => a.startIndex === b.startIndex && a.endIndex === b.endIndex;

package/dist/patterns/audit/audit-log.d.ts

@@ -1,5 +1,6 @@
-import type { AuditEvent, AuditFacets, AuditGroupBy } from "./types.js";
+import type { AuditEvent, AuditFacets, AuditGroup, AuditGroupBy } from "./types.js";
 import { BaseElement } from "../../core/index.js";
+import type { RowWindow } from "../../core/index.js";
 /**
  * The aggregation, faceting, and export layer over the `box-timeline` event
  * contract (opportunity 3 of `plans/component-opportunities.md`): the same
@@ -7,8 +8,9 @@ import { BaseElement } from "../../core/index.js";
  * 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 declare class AuditLog extends BaseElement {
     static readonly tagName: string;
@@ -29,6 +31,15 @@ export declare class AuditLog extends BaseElement {
     private titleEl;
     /** Section keys the reader has collapsed. Absent means expanded. */
     private collapsedGroups;
+    /** The row window the last render used; null when it rendered everything. */
+    private lastWindow;
+    private scrollFrame;
+    private measuredHeights;
+    private measureFrame;
+    /** Row set the adoption budget below is counted against. */
+    private adoptedFor;
+    private adoptionCount;
+    private viewportObserver;
     private contentSignature;
     private optionsSignature;
     /** Raw `events` attribute the parse cache was built from. */
@@ -58,6 +69,14 @@ export declare class AuditLog extends BaseElement {
     set referenceTime(value: string);
     /** The events currently on screen: the full set narrowed by the facets. */
     get visibleEvents(): AuditEvent[];
+    /**
+     * 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(): AuditGroup[];
     toggleGroup(key: string, expanded?: boolean): void;
     expandAll(): void;
     collapseAll(): void;
@@ -68,8 +87,90 @@ export declare class AuditLog extends BaseElement {
      * archive API).
      */
     exportCsv(): string;
+    /**
+     * 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.
+     */
+    private observeViewport;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * 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(): boolean;
+    set virtualize(value: boolean);
+    /**
+     * 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(): number;
+    get headingHeight(): number;
+    set rowHeight(value: number);
+    set headingHeight(value: number);
+    private declaredHeight;
+    /** The window the last render used, or null when it rendered every section. */
+    get renderedWindow(): RowWindow | 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. */
+    private meanHeight;
+    /**
+     * 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.
+     */
+    private measureRowHeights;
+    /**
+     * 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.
+     */
+    private heightSignature;
+    private currentPlan;
     private now;
+    /**
+     * 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.
+     */
+    private rowCache;
+    private cachedRows;
     private currentGroups;
     private patchFacets;
     private eventHtml;