@unofficialbox/box-open-elements 0.5.0 → 0.7.0

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./audit-log.js";
+export * from "./activity-density.js";

package/dist/patterns/audit/index.js

@@ -0,0 +1,7 @@
+// Aggregation model over the timeline event contract: grouping, faceting,
+// CSV export, and the calendar-density window — all pure and DOM-free.
+export * from "./types.js";
+// Grouped, faceted, drillable audit surface
+export * from "./audit-log.js";
+// Managerial throughput heatmap
+export * from "./activity-density.js";

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

@@ -0,0 +1,10 @@
+export declare const escapeHtml: (value: string) => string;
+export declare const auditToneColor: (tone: string) => string;
+/**
+ * Format an event instant for a row. Rendered in UTC to match the UTC day
+ * grouping — a row must never appear to sit outside the day section holding
+ * it, which is exactly what a locale-local time would produce near midnight.
+ */
+export declare const formatAuditTimestamp: (value: string | undefined) => string;
+/** Reference time for deterministic day labels; falls back to the wall clock. */
+export declare const resolveReferenceTime: (raw: string | null) => Date;

package/dist/patterns/audit/shared.js

@@ -0,0 +1,50 @@
+import { formatUtcDay } from "./types.js";
+// Internal helpers shared by the two audit projections. Kept in one place so
+// escaping and formatting can never drift between the log and the density
+// strip — they render the same records.
+export const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+export const auditToneColor = (tone) => {
+    switch (tone) {
+        case "brand":
+            return "var(--boe-token-surface-surface-brand, #0061d5)";
+        case "success":
+            return "var(--boe-token-surface-status-surface-success, #26a27b)";
+        case "warning":
+            return "var(--boe-token-surface-status-surface-warning, #f5b31b)";
+        case "error":
+            return "var(--boe-token-surface-status-surface-error, #ed3757)";
+        default:
+            return "var(--boe-token-text-text-secondary, #6f6f6f)";
+    }
+};
+const pad = (value) => String(value).padStart(2, "0");
+/**
+ * Format an event instant for a row. Rendered in UTC to match the UTC day
+ * grouping — a row must never appear to sit outside the day section holding
+ * it, which is exactly what a locale-local time would produce near midnight.
+ */
+export const formatAuditTimestamp = (value) => {
+    if (!value) {
+        return "";
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return "";
+    }
+    return `${formatUtcDay(date)}, ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())} UTC`;
+};
+/** Reference time for deterministic day labels; falls back to the wall clock. */
+export const resolveReferenceTime = (raw) => {
+    if (raw) {
+        const parsed = new Date(raw);
+        if (!Number.isNaN(parsed.getTime())) {
+            return parsed;
+        }
+    }
+    return new Date();
+};

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

@@ -0,0 +1,143 @@
+import type { TimelineEvent } from "../timeline/types.js";
+/**
+ * The audit layer reads the same append-only event contract `box-timeline`
+ * renders. The timeline is the flat feed; this pattern is the aggregation,
+ * faceting, drill-down, and export layer over identical records, so a host
+ * feeds both surfaces from one source without a second model.
+ */
+export type AuditEvent = TimelineEvent;
+/** The dimension sections are grouped by. */
+export type AuditGroupBy = "day" | "actor" | "action";
+export declare const AUDIT_GROUP_BY_VALUES: readonly AuditGroupBy[];
+export declare const AUDIT_GROUP_BY_LABELS: Record<AuditGroupBy, string>;
+export declare const resolveAuditGroupBy: (value: string | null | undefined) => AuditGroupBy;
+/**
+ * Facet selection. Every facet is an exact match except `from`/`to`, which
+ * bound the event instant inclusively.
+ */
+export interface AuditFacets {
+    /** Matches `actor.name` exactly. */
+    actor?: string;
+    /** Matches `action` exactly. */
+    action?: string;
+    /** The workflow-run drill-down. */
+    correlationId?: string;
+    /** Inclusive ISO lower bound. */
+    from?: string;
+    /** Inclusive ISO upper bound. */
+    to?: string;
+}
+export interface AuditGroup {
+    /** Stable identity for the section — the collapse state is keyed by it. */
+    key: string;
+    label: string;
+    events: AuditEvent[];
+    count: number;
+    /** Distinct attributed actors in the group; 0 when every event is unattributed. */
+    actorCount: number;
+}
+export interface AuditFacetValue {
+    value: string;
+    label: string;
+    count: number;
+}
+export interface AuditFacetSummary {
+    actors: AuditFacetValue[];
+    actions: AuditFacetValue[];
+}
+export declare const AUDIT_UNDATED_KEY = "undated";
+export declare const AUDIT_UNATTRIBUTED_KEY = "";
+/**
+ * The event's instant in epoch milliseconds, or `null` when it carries no
+ * usable timestamp. Undated events are a real case in imported audit data —
+ * they sort last rather than being dropped.
+ */
+export declare const auditEventInstant: (event: AuditEvent) => number | null;
+/**
+ * The UTC calendar day (`YYYY-MM-DD`) an event belongs to, or `null` when it
+ * is undated. Day keys and day labels are both derived in UTC so a viewer's
+ * timezone can never split one audit day across two sections. A host that
+ * wants local-day semantics offsets the timestamps it supplies.
+ */
+export declare const resolveAuditDay: (event: AuditEvent) => string | null;
+/**
+ * The one absolute-day formatter — `Aug 13, 2026`, always in UTC. Accepts a
+ * `YYYY-MM-DD` key or an instant. Every audit surface formats days through
+ * this, so a rendered date can never disagree with the UTC day key that
+ * grouped it. An unparseable key is returned unchanged.
+ */
+export declare const formatUtcDay: (value: Date | string) => string;
+/** The short UTC month name — `Aug` — for sparse calendar column headers. */
+export declare const formatUtcMonth: (value: Date | string) => string;
+/**
+ * Label a `YYYY-MM-DD` day key, with Today/Yesterday relative labels resolved
+ * against the caller's reference time so the output is deterministic rather
+ * than clock-dependent.
+ */
+export declare const formatAuditDay: (day: string, now?: Date) => string;
+/**
+ * Apply the facet selection. An empty string is "not selected" rather than a
+ * match on empty — the same meaning `""` carries as an unset attribute and as
+ * a select's all-values option, so the DOM and the engine never disagree.
+ *
+ * A date bound excludes undated events: an event with no timestamp cannot be
+ * shown to fall inside the window, and an audit surface must not imply it does.
+ */
+export declare const filterAuditEvents: (events: readonly AuditEvent[], facets: AuditFacets) => AuditEvent[];
+/** True when any facet narrows the set — drives the Clear-filters affordance. */
+export declare const hasAuditFacets: (facets: AuditFacets) => boolean;
+/**
+ * Group events into collapsible sections.
+ *
+ * Day sections run newest first with undated events in a trailing section;
+ * actor and action sections run by descending count, ties broken by label so
+ * the order never depends on input order. Events inside every section are
+ * newest first.
+ */
+export declare const groupAuditEvents: (events: readonly AuditEvent[], groupBy: AuditGroupBy, now?: Date) => AuditGroup[];
+/**
+ * Available facet values with counts, derived from the *unfiltered* set so
+ * selecting one facet never removes the options for another — a filter UI
+ * that can dead-end is worse than no counts.
+ */
+export declare const summarizeAuditFacets: (events: readonly AuditEvent[]) => AuditFacetSummary;
+export declare const AUDIT_CSV_COLUMNS: readonly ["id", "timestamp", "actor", "action", "summary", "badge", "correlationId", "evidence"];
+/**
+ * Render events as RFC 4180 CSV for the export toolbar. Every field is
+ * quoted, embedded quotes are doubled, and a value that would otherwise be
+ * read as a spreadsheet formula is prefixed so it stays text.
+ */
+export declare const toAuditCsv: (events: readonly AuditEvent[]) => string;
+export interface ActivityDensityCell {
+    /** UTC calendar day, `YYYY-MM-DD`. */
+    date: string;
+    count: number;
+    /** 0 for an empty day, otherwise 1–4 scaled against the busiest day in the window. */
+    level: number;
+    /** Column index, oldest week first. */
+    week: number;
+    /** Row index, 0 = Sunday. */
+    weekday: number;
+}
+export interface ActivityDensity {
+    cells: ActivityDensityCell[];
+    weeks: number;
+    total: number;
+    max: number;
+    /** First day in the window (the Sunday that opens the oldest column). */
+    start: string;
+    /** Last day in the window — the reference day. */
+    end: string;
+}
+export interface ActivityDensityOptions {
+    /** Reference day; the window ends on it. */
+    now: Date;
+    /** Number of week columns, clamped to 1–53. Defaults to 12. */
+    weeks?: number;
+}
+/**
+ * Build the calendar heatmap window: whole week columns ending on the
+ * reference day's week, rows Sunday → Saturday. Pure and UTC-based, so the
+ * same events and reference time always produce the same grid.
+ */
+export declare const computeActivityDensity: (events: readonly AuditEvent[], options: ActivityDensityOptions) => ActivityDensity;

package/dist/patterns/audit/types.js

@@ -0,0 +1,327 @@
+export const AUDIT_GROUP_BY_VALUES = ["day", "actor", "action"];
+export const AUDIT_GROUP_BY_LABELS = {
+    day: "Day",
+    actor: "Actor",
+    action: "Action",
+};
+export const resolveAuditGroupBy = (value) => value && AUDIT_GROUP_BY_VALUES.includes(value)
+    ? value
+    : "day";
+export const AUDIT_UNDATED_KEY = "undated";
+export const AUDIT_UNATTRIBUTED_KEY = "";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * The event's instant in epoch milliseconds, or `null` when it carries no
+ * usable timestamp. Undated events are a real case in imported audit data —
+ * they sort last rather than being dropped.
+ */
+export const auditEventInstant = (event) => {
+    if (!event.timestamp) {
+        return null;
+    }
+    const value = new Date(event.timestamp).getTime();
+    return Number.isNaN(value) ? null : value;
+};
+/** Newest first; undated events sink to the end without reordering among themselves. */
+const byNewestFirst = (left, right) => {
+    const a = auditEventInstant(left);
+    const b = auditEventInstant(right);
+    if (a === b) {
+        return 0;
+    }
+    if (a === null) {
+        return 1;
+    }
+    if (b === null) {
+        return -1;
+    }
+    return b - a;
+};
+/**
+ * The UTC calendar day (`YYYY-MM-DD`) an event belongs to, or `null` when it
+ * is undated. Day keys and day labels are both derived in UTC so a viewer's
+ * timezone can never split one audit day across two sections. A host that
+ * wants local-day semantics offsets the timestamps it supplies.
+ */
+export const resolveAuditDay = (event) => {
+    const instant = auditEventInstant(event);
+    if (instant === null) {
+        return null;
+    }
+    return new Date(instant).toISOString().slice(0, 10);
+};
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+/**
+ * The one absolute-day formatter — `Aug 13, 2026`, always in UTC. Accepts a
+ * `YYYY-MM-DD` key or an instant. Every audit surface formats days through
+ * this, so a rendered date can never disagree with the UTC day key that
+ * grouped it. An unparseable key is returned unchanged.
+ */
+export const formatUtcDay = (value) => {
+    const date = typeof value === "string" ? new Date(`${value}T00:00:00.000Z`) : value;
+    if (Number.isNaN(date.getTime())) {
+        return typeof value === "string" ? value : "";
+    }
+    return `${MONTHS[date.getUTCMonth()]} ${String(date.getUTCDate())}, ${String(date.getUTCFullYear())}`;
+};
+/** The short UTC month name — `Aug` — for sparse calendar column headers. */
+export const formatUtcMonth = (value) => {
+    const date = typeof value === "string" ? new Date(`${value}T00:00:00.000Z`) : value;
+    return Number.isNaN(date.getTime()) ? "" : MONTHS[date.getUTCMonth()];
+};
+/**
+ * Label a `YYYY-MM-DD` day key, with Today/Yesterday relative labels resolved
+ * against the caller's reference time so the output is deterministic rather
+ * than clock-dependent.
+ */
+export const formatAuditDay = (day, now) => {
+    const parsed = new Date(`${day}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return day;
+    }
+    if (now) {
+        const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+        const delta = today - parsed.getTime();
+        if (delta === 0) {
+            return "Today";
+        }
+        if (delta === DAY_MS) {
+            return "Yesterday";
+        }
+    }
+    return formatUtcDay(parsed);
+};
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Resolve a bound to an instant. A date-only bound (what `<input type="date">`
+ * produces) covers the whole UTC day, so `to: "2026-08-13"` includes
+ * everything that happened on the 13th rather than only its first
+ * millisecond. A full ISO instant is used verbatim.
+ */
+const resolveBound = (value, edge) => {
+    if (!value) {
+        return Number.NaN;
+    }
+    const resolved = DATE_ONLY.test(value)
+        ? `${value}${edge === "start" ? "T00:00:00.000Z" : "T23:59:59.999Z"}`
+        : value;
+    return new Date(resolved).getTime();
+};
+/**
+ * Apply the facet selection. An empty string is "not selected" rather than a
+ * match on empty — the same meaning `""` carries as an unset attribute and as
+ * a select's all-values option, so the DOM and the engine never disagree.
+ *
+ * A date bound excludes undated events: an event with no timestamp cannot be
+ * shown to fall inside the window, and an audit surface must not imply it does.
+ */
+export const filterAuditEvents = (events, facets) => {
+    const from = resolveBound(facets.from, "start");
+    const to = resolveBound(facets.to, "end");
+    const hasFrom = !Number.isNaN(from);
+    const hasTo = !Number.isNaN(to);
+    return events.filter(event => {
+        if (facets.actor && (event.actor?.name ?? "") !== facets.actor) {
+            return false;
+        }
+        if (facets.action && event.action !== facets.action) {
+            return false;
+        }
+        if (facets.correlationId && event.correlationId !== facets.correlationId) {
+            return false;
+        }
+        if (!hasFrom && !hasTo) {
+            return true;
+        }
+        const instant = auditEventInstant(event);
+        if (instant === null) {
+            return false;
+        }
+        return (!hasFrom || instant >= from) && (!hasTo || instant <= to);
+    });
+};
+/** True when any facet narrows the set — drives the Clear-filters affordance. */
+export const hasAuditFacets = (facets) => Object.values(facets).some(value => value !== undefined && value !== "");
+/**
+ * Group events into collapsible sections.
+ *
+ * Day sections run newest first with undated events in a trailing section;
+ * actor and action sections run by descending count, ties broken by label so
+ * the order never depends on input order. Events inside every section are
+ * newest first.
+ */
+export const groupAuditEvents = (events, groupBy, now) => {
+    const seeds = new Map();
+    const seedFor = (key, label) => {
+        let seed = seeds.get(key);
+        if (!seed) {
+            seed = { key, label, events: [] };
+            seeds.set(key, seed);
+        }
+        return seed;
+    };
+    for (const event of events) {
+        if (groupBy === "day") {
+            const day = resolveAuditDay(event);
+            seedFor(day ?? AUDIT_UNDATED_KEY, day ? formatAuditDay(day, now) : "Undated").events.push(event);
+        }
+        else if (groupBy === "actor") {
+            const name = event.actor?.name ?? "";
+            seedFor(name || AUDIT_UNATTRIBUTED_KEY, name || "Unattributed").events.push(event);
+        }
+        else {
+            seedFor(event.action, event.action).events.push(event);
+        }
+    }
+    const groups = [...seeds.values()].map(seed => {
+        const actors = new Set();
+        for (const event of seed.events) {
+            if (event.actor?.name) {
+                actors.add(event.actor.name);
+            }
+        }
+        return {
+            key: seed.key,
+            label: seed.label,
+            events: [...seed.events].sort(byNewestFirst),
+            count: seed.events.length,
+            actorCount: actors.size,
+        };
+    });
+    if (groupBy === "day") {
+        return groups.sort((left, right) => {
+            if (left.key === AUDIT_UNDATED_KEY || right.key === AUDIT_UNDATED_KEY) {
+                return left.key === right.key ? 0 : left.key === AUDIT_UNDATED_KEY ? 1 : -1;
+            }
+            return left.key < right.key ? 1 : left.key > right.key ? -1 : 0;
+        });
+    }
+    const trailingKey = groupBy === "actor" ? AUDIT_UNATTRIBUTED_KEY : null;
+    return groups.sort((left, right) => {
+        if (trailingKey !== null && (left.key === trailingKey || right.key === trailingKey)) {
+            return left.key === right.key ? 0 : left.key === trailingKey ? 1 : -1;
+        }
+        if (left.count !== right.count) {
+            return right.count - left.count;
+        }
+        return left.label < right.label ? -1 : left.label > right.label ? 1 : 0;
+    });
+};
+const summarize = (values) => {
+    const counts = new Map();
+    for (const value of values) {
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([value, count]) => ({ value, label: value || "Unattributed", count }))
+        .sort((left, right) => left.count !== right.count
+        ? right.count - left.count
+        : left.label < right.label
+            ? -1
+            : left.label > right.label
+                ? 1
+                : 0);
+};
+/**
+ * Available facet values with counts, derived from the *unfiltered* set so
+ * selecting one facet never removes the options for another — a filter UI
+ * that can dead-end is worse than no counts.
+ */
+export const summarizeAuditFacets = (events) => ({
+    actors: summarize(events.map(event => event.actor?.name ?? "")),
+    actions: summarize(events.map(event => event.action)),
+});
+/** Formulas are data in an audit export, never something a spreadsheet should run. */
+const FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"];
+const csvField = (value) => {
+    const neutralized = FORMULA_PREFIXES.some(prefix => value.startsWith(prefix))
+        ? `'${value}`
+        : value;
+    return `"${neutralized.replaceAll('"', '""')}"`;
+};
+export const AUDIT_CSV_COLUMNS = [
+    "id",
+    "timestamp",
+    "actor",
+    "action",
+    "summary",
+    "badge",
+    "correlationId",
+    "evidence",
+];
+/**
+ * Render events as RFC 4180 CSV for the export toolbar. Every field is
+ * quoted, embedded quotes are doubled, and a value that would otherwise be
+ * read as a spreadsheet formula is prefixed so it stays text.
+ */
+export const toAuditCsv = (events) => {
+    const rows = events.map(event => [
+        event.id,
+        event.timestamp ?? "",
+        event.actor?.name ?? "",
+        event.action,
+        event.summary ?? "",
+        event.badge ?? "",
+        event.correlationId ?? "",
+        (event.evidence ?? [])
+            .map(entry => (entry.href ? `${entry.label} (${entry.href})` : entry.label))
+            .join("; "),
+    ]
+        .map(csvField)
+        .join(","));
+    return [AUDIT_CSV_COLUMNS.map(csvField).join(","), ...rows].join("\r\n");
+};
+/**
+ * Build the calendar heatmap window: whole week columns ending on the
+ * reference day's week, rows Sunday → Saturday. Pure and UTC-based, so the
+ * same events and reference time always produce the same grid.
+ */
+export const computeActivityDensity = (events, options) => {
+    const weeks = Math.min(53, Math.max(1, Math.trunc(options.weeks ?? 12)));
+    const now = options.now;
+    const endDay = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const endWeekday = new Date(endDay).getUTCDay();
+    // Open on the Sunday of the oldest column so every column is a whole week.
+    const startDay = endDay - endWeekday * DAY_MS - (weeks - 1) * 7 * DAY_MS;
+    const counts = new Map();
+    for (const event of events) {
+        const day = resolveAuditDay(event);
+        if (day) {
+            counts.set(day, (counts.get(day) ?? 0) + 1);
+        }
+    }
+    const cells = [];
+    let total = 0;
+    let max = 0;
+    for (let offset = 0; startDay + offset * DAY_MS <= endDay; offset += 1) {
+        const date = new Date(startDay + offset * DAY_MS).toISOString().slice(0, 10);
+        const count = counts.get(date) ?? 0;
+        total += count;
+        max = Math.max(max, count);
+        cells.push({ date, count, level: 0, week: Math.floor(offset / 7), weekday: offset % 7 });
+    }
+    for (const cell of cells) {
+        cell.level = cell.count === 0 ? 0 : Math.min(4, Math.max(1, Math.ceil((cell.count / max) * 4)));
+    }
+    return {
+        cells,
+        weeks,
+        total,
+        max,
+        start: new Date(startDay).toISOString().slice(0, 10),
+        end: new Date(endDay).toISOString().slice(0, 10),
+    };
+};

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;