@unofficialbox/box-open-elements 0.5.0 → 0.7.0

package/dist/patterns/audit/activity-density.js

@@ -0,0 +1,428 @@
+import { computeActivityDensity, formatUtcDay, formatUtcMonth, resolveAuditDay, } from "./types.js";
+import { escapeHtml, resolveReferenceTime } from "./shared.js";
+import { isTimelineEventRecord } from "../timeline/types.js";
+import { BaseElement } from "../../core/index.js";
+import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-activity-density";
+const WEEKDAY_LABELS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: block;
+          color: inherit;
+          font: inherit;
+        }
+
+        [part="panel"] {
+          display: grid;
+          gap: ${boePanel.gap};
+          padding: ${boePanel.padding};
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 82%, transparent);
+          border-radius: ${boePanel.radius};
+          background: ${boePanel.background};
+        }
+
+        [part="title"] {
+          margin: 0;
+          font: inherit;
+          font-size: 1.1rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="scroller"] {
+          overflow-x: auto;
+        }
+
+        [part="grid"] {
+          border-collapse: separate;
+          border-spacing: 3px;
+        }
+
+        [part="caption"] {
+          caption-side: top;
+          text-align: start;
+          padding-block-end: 0.35rem;
+          font-size: 0.8rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="weekday"],
+        [part="month"] {
+          font-size: 0.66rem;
+          font-weight: 600;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          text-align: end;
+          padding-inline-end: 0.25rem;
+          white-space: nowrap;
+        }
+
+        [part="month"] {
+          text-align: start;
+          padding: 0;
+        }
+
+        [part="cell"] {
+          inline-size: 0.85rem;
+          block-size: 0.85rem;
+          padding: 0;
+          border-radius: ${boeRadius.size};
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="cell"][data-level="1"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 28%, transparent);
+        }
+
+        [part="cell"][data-level="2"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 50%, transparent);
+        }
+
+        [part="cell"][data-level="3"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 74%, transparent);
+        }
+
+        [part="cell"][data-level="4"] {
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="cell-button"] {
+          appearance: none;
+          display: block;
+          inline-size: 100%;
+          block-size: 100%;
+          min-block-size: 0.85rem;
+          padding: 0;
+          border: none;
+          border-radius: inherit;
+          background: none;
+          cursor: pointer;
+        }
+
+        [part="cell-button"]:focus-visible {
+          outline: 2px solid var(--boe-token-surface-surface-brand, #0061d5);
+          outline-offset: 2px;
+        }
+
+        [part="legend"] {
+          display: flex;
+          align-items: center;
+          gap: 0.3rem;
+          font-size: 0.72rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="legend-swatch"] {
+          inline-size: 0.7rem;
+          block-size: 0.7rem;
+          border-radius: ${boeRadius.size};
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="legend-swatch"][data-level="1"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 28%, transparent);
+        }
+
+        [part="legend-swatch"][data-level="2"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 50%, transparent);
+        }
+
+        [part="legend-swatch"][data-level="3"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 74%, transparent);
+        }
+
+        [part="legend-swatch"][data-level="4"] {
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+      `;
+/**
+ * The managerial companion to `box-audit-log`: a calendar heatmap of event
+ * volume per UTC day over a trailing window, for spotting throughput and
+ * quiet periods at a glance.
+ *
+ * Days with activity are buttons in a roving-tabindex grid (arrow keys move
+ * by day and by week, Home/End jump to the ends of the window), each labelled
+ * with its own count and date so the surface is understandable without the
+ * colour. Selecting one emits `day-selected` with that day's events — the
+ * drill-down into the log.
+ */
+export class ActivityDensityStrip extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["events", "heading", "reference-time", "weeks"];
+    }
+    titleEl;
+    gridEl;
+    captionEl;
+    monthsRowEl;
+    rowsEl;
+    signature = "";
+    /** Roving focus position, `week:weekday`. Null until the first render. */
+    activeKey = null;
+    renderedWeeks = 0;
+    /** Raw `events` attribute the parse cache was built from. */
+    eventsRaw = null;
+    eventsCache = [];
+    get heading() {
+        return this.getAttribute("heading") ?? "Activity density";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /**
+     * Memoized on the raw attribute for the same reason as `box-audit-log`:
+     * `density`, `eventsOn`, and `update` each read it, and an arrow keypress
+     * must not re-parse the payload. Returns a copy.
+     */
+    get events() {
+        const raw = this.getAttribute("events");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.eventsRaw) {
+            this.eventsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.eventsCache =
+                    Array.isArray(parsed) && parsed.every(isTimelineEventRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.eventsCache = [];
+            }
+        }
+        return [...this.eventsCache];
+    }
+    set events(value) {
+        if (value.length) {
+            this.setAttribute("events", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("events");
+    }
+    get weeks() {
+        const raw = Number.parseInt(this.getAttribute("weeks") ?? "", 10);
+        return Number.isFinite(raw) ? raw : 12;
+    }
+    set weeks(value) {
+        this.setAttribute("weeks", String(value));
+    }
+    get referenceTime() {
+        return this.getAttribute("reference-time") ?? "";
+    }
+    set referenceTime(value) {
+        this.setAttribute("reference-time", value);
+    }
+    /** The computed window — cells, totals, and the busiest day's count. */
+    get density() {
+        return computeActivityDensity(this.events, {
+            now: resolveReferenceTime(this.getAttribute("reference-time")),
+            weeks: this.weeks,
+        });
+    }
+    /** Every event on the given UTC day, in input order. */
+    eventsOn(date) {
+        return this.events.filter(event => resolveAuditDay(event) === date);
+    }
+    emitDaySelected(date, count) {
+        this.dispatchEvent(new CustomEvent("day-selected", {
+            bubbles: true,
+            composed: true,
+            detail: { date, count, events: this.eventsOn(date) },
+        }));
+    }
+    buttons() {
+        return Array.from(this.gridEl.querySelectorAll('[part="cell-button"]'));
+    }
+    /**
+     * Buttons oldest → newest. DOM order is weekday-major (the grid renders one
+     * row per weekday), so it is *not* chronological — anything that means
+     * "first" or "last day in the window" has to sort by date.
+     */
+    buttonsByDate() {
+        return this.buttons().sort((left, right) => (left.getAttribute("data-date") ?? "").localeCompare(right.getAttribute("data-date") ?? ""));
+    }
+    buttonAt(week, weekday) {
+        return this.gridEl.querySelector(`[part="cell-button"][data-week="${String(week)}"][data-weekday="${String(weekday)}"]`);
+    }
+    /** Walk in one grid direction until a day with activity is found. */
+    step(week, weekday, deltaWeek, deltaWeekday) {
+        // The rendered column count, not a recomputed window: a keypress must not
+        // re-parse the whole event payload.
+        const total = this.renderedWeeks;
+        let nextWeek = week + deltaWeek;
+        let nextWeekday = weekday + deltaWeekday;
+        while (nextWeek >= 0 && nextWeek < total && nextWeekday >= 0 && nextWeekday < 7) {
+            const button = this.buttonAt(nextWeek, nextWeekday);
+            if (button) {
+                return button;
+            }
+            nextWeek += deltaWeek;
+            nextWeekday += deltaWeekday;
+        }
+        return null;
+    }
+    focusButton(button) {
+        this.activeKey = `${button.getAttribute("data-week") ?? ""}:${button.getAttribute("data-weekday") ?? ""}`;
+        for (const candidate of this.buttons()) {
+            candidate.tabIndex = candidate === button ? 0 : -1;
+        }
+        button.focus();
+    }
+    /**
+     * A day with activity is a labelled button — that label is the accessible
+     * contract, since colour alone carries no meaning. A quiet day is an inert
+     * cell with a hover title: nothing to drill into, and no extra tab stop.
+     */
+    cellHtml(cell) {
+        const date = escapeHtml(cell.date);
+        const label = escapeHtml(`${String(cell.count)} ${cell.count === 1 ? "event" : "events"} on ${formatUtcDay(cell.date)}`);
+        const body = cell.count > 0
+            ? `<button type="button" part="cell-button" tabindex="-1" data-date="${date}" data-week="${String(cell.week)}" data-weekday="${String(cell.weekday)}" data-count="${String(cell.count)}" aria-label="${label}"></button>`
+            : "";
+        return `<td part="cell" data-level="${String(cell.level)}" data-date="${date}" data-count="${String(cell.count)}" title="${label}">${body}</td>`;
+    }
+    rebuild(density) {
+        this.renderedWeeks = density.weeks;
+        const byWeekday = new Map();
+        for (const cell of density.cells) {
+            const row = byWeekday.get(cell.weekday) ?? [];
+            row.push(cell);
+            byWeekday.set(cell.weekday, row);
+        }
+        // Column headers carry the month, printed once where it changes — the
+        // same sparse labelling a git contribution graph uses.
+        const firstRow = byWeekday.get(0) ?? [];
+        let lastMonth = "";
+        const monthCells = firstRow.map(cell => {
+            const month = cell.date.slice(0, 7);
+            const label = month === lastMonth ? "" : formatUtcMonth(cell.date);
+            lastMonth = month;
+            return `<th scope="col" part="month">${label}</th>`;
+        });
+        // Only the header row and the body are re-minted — the caption is part of
+        // the stable shell, so rebuilding the grid never drops it.
+        this.monthsRowEl.innerHTML = `<td></td>${monthCells.join("")}`;
+        this.rowsEl.innerHTML = WEEKDAY_LABELS.map((label, weekday) => {
+            const cells = (byWeekday.get(weekday) ?? []).map(cell => this.cellHtml(cell)).join("");
+            return `<tr><th scope="row" part="weekday">${label}</th>${cells}</tr>`;
+        }).join("");
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <section part="panel">
+        <h2 part="title"></h2>
+        <div part="scroller">
+          <table part="grid">
+            <caption part="caption"></caption>
+            <thead><tr part="months-row"></tr></thead>
+            <tbody part="rows"></tbody>
+          </table>
+        </div>
+        <div part="legend">
+          <span>Less</span>
+          ${[0, 1, 2, 3, 4]
+            .map(level => `<span part="legend-swatch" data-level="${String(level)}"></span>`)
+            .join("")}
+          <span>More</span>
+        </div>
+      </section>
+    `;
+        this.titleEl = this.shadowRoot.querySelector('[part="title"]');
+        this.gridEl = this.shadowRoot.querySelector('[part="grid"]');
+        this.captionEl = this.shadowRoot.querySelector('[part="caption"]');
+        this.monthsRowEl = this.shadowRoot.querySelector('[part="months-row"]');
+        this.rowsEl = this.shadowRoot.querySelector('[part="rows"]');
+    }
+    setupListeners() {
+        this.gridEl.addEventListener("click", event => {
+            const button = event.target.closest('[part="cell-button"]');
+            if (!button || !this.gridEl.contains(button)) {
+                return;
+            }
+            this.focusButton(button);
+            this.emitDaySelected(button.getAttribute("data-date") ?? "", Number(button.getAttribute("data-count") ?? "0"));
+        });
+        this.gridEl.addEventListener("keydown", event => {
+            const button = event.target.closest('[part="cell-button"]');
+            if (!button || !this.gridEl.contains(button)) {
+                return;
+            }
+            const week = Number(button.getAttribute("data-week") ?? "0");
+            const weekday = Number(button.getAttribute("data-weekday") ?? "0");
+            // Home/End mean the ends of the *window*, not the ends of the DOM.
+            const byDate = this.buttonsByDate();
+            let next = null;
+            switch (event.key) {
+                case "ArrowLeft":
+                    next = this.step(week, weekday, -1, 0);
+                    break;
+                case "ArrowRight":
+                    next = this.step(week, weekday, 1, 0);
+                    break;
+                case "ArrowUp":
+                    next = this.step(week, weekday, 0, -1);
+                    break;
+                case "ArrowDown":
+                    next = this.step(week, weekday, 0, 1);
+                    break;
+                case "Home":
+                    next = byDate[0] ?? null;
+                    break;
+                case "End":
+                    next = byDate[byDate.length - 1] ?? null;
+                    break;
+                default:
+                    return;
+            }
+            if (next) {
+                event.preventDefault();
+                this.focusButton(next);
+            }
+        });
+    }
+    update() {
+        if (!this.gridEl) {
+            return;
+        }
+        this.titleEl.textContent = this.heading;
+        const density = this.density;
+        const signature = JSON.stringify([
+            this.getAttribute("events") ?? "",
+            this.weeks,
+            this.referenceTime,
+        ]);
+        if (signature !== this.signature) {
+            this.signature = signature;
+            this.rebuild(density);
+            // Cells are re-minted, so the previous roving position may be gone.
+            this.activeKey = null;
+        }
+        this.captionEl.textContent = `${String(density.total)} ${density.total === 1 ? "event" : "events"} from ${formatUtcDay(density.start)} to ${formatUtcDay(density.end)}`;
+        this.gridEl.setAttribute("aria-label", this.heading);
+        const all = this.buttons();
+        const byDate = this.buttonsByDate();
+        const active = (this.activeKey
+            ? all.find(button => `${button.getAttribute("data-week") ?? ""}:${button.getAttribute("data-weekday") ?? ""}` ===
+                this.activeKey)
+            : undefined) ??
+            // Default the tab stop to the most recent day with activity — the last
+            // by date, not the last in the weekday-major DOM order.
+            byDate[byDate.length - 1];
+        for (const button of all) {
+            button.tabIndex = button === active ? 0 : -1;
+        }
+        if (active) {
+            this.activeKey = `${active.getAttribute("data-week") ?? ""}:${active.getAttribute("data-weekday") ?? ""}`;
+        }
+    }
+}
+ActivityDensityStrip.register();

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

@@ -0,0 +1,182 @@
+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
+ * records the flat feed renders, grouped into collapsible day/actor/action
+ * 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. `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;
+    static get observedAttributes(): string[];
+    private toolbarEl;
+    private groupByEl;
+    private actorSelectEl;
+    private actionSelectEl;
+    private fromInputEl;
+    private toInputEl;
+    private clearFiltersEl;
+    private exportEl;
+    private drilldownEl;
+    private drilldownIdEl;
+    private summaryEl;
+    private groupsEl;
+    private emptyEl;
+    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. */
+    private eventsRaw;
+    private eventsCache;
+    get heading(): string;
+    set heading(value: string);
+    /**
+     * Audit records; JSON payloads are validated per record before rendering.
+     *
+     * Memoized on the raw attribute so a single keystroke in the date field
+     * does not re-parse and re-validate the whole payload once per reader
+     * (`update`, `visibleEvents`, and each click-handler branch all read it).
+     * The cache invalidates itself when the attribute changes; the returned
+     * array is a copy, so a caller cannot mutate the log out from under it.
+     */
+    get events(): AuditEvent[];
+    set events(value: AuditEvent[]);
+    get groupBy(): AuditGroupBy;
+    set groupBy(value: AuditGroupBy);
+    get facets(): AuditFacets;
+    /** Replaces the whole selection — an omitted or empty facet is cleared. */
+    set facets(value: AuditFacets);
+    get exportable(): boolean;
+    set exportable(value: boolean);
+    get referenceTime(): string;
+    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;
+    /**
+     * Export what is on screen, not the whole set — an export that silently
+     * widens past the reader's filters is a compliance hazard. Returns the CSV
+     * and emits `export-requested` so the host owns delivery (download, mail,
+     * 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;
+    private groupHtml;
+    private renderOptions;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}