@unofficialbox/box-open-elements 0.6.0 → 0.7.0

package/README.md

@@ -10,96 +10,49 @@
 
 > **Community project — not affiliated with, authorized, or endorsed by Box, Inc.** “Box” is a trademark of Box, Inc. This library tracks Box’s public design language for interoperability; it ships no Box code.
 
-The library is organized around three layers:
+Browse the full catalog on the **[live docs site](https://unofficialbox.github.io/box-open-elements)** — live previews, an events/properties inspector, per-framework code snippets (React / Angular / Vue / Svelte / HTML), and the foundations pages.
+
+The library is organized around three layers (see [docs/taxonomy.md](./docs/taxonomy.md) for the canonical model):
 
 - **Foundations** — design decisions as data: tokens, color, typography, iconography, accessibility, theming
 - **Components** — accessible Web Components for single controls, organized by category
 - **Patterns** — combinations of components that address user objectives with sequences and flows: headless controllers, transport contracts, and composed workflow surfaces, grouped by Box noun
 
-See [docs/taxonomy.md](./docs/taxonomy.md) for the canonical model.
-
 Core implementation principles:
 
-- plain TypeScript modules, no React requirement in the core package
+- plain TypeScript modules, no React requirement in the core package — zero runtime dependencies
 - state and business logic separate from rendering: controllers and stores, not framework components
 - standard DOM events where a UI layer needs them
 - accessibility semantics and keyboard support as part of the component contract
 - injected transport contracts instead of SDK coupling
 
-## Preview
-
-[![The box-open-elements documentation site](https://raw.githubusercontent.com/unofficialbox/box-open-elements/main/docs/screenshots/docs-site/home.png)](https://unofficialbox.github.io/box-open-elements)
-
-The **[live docs site](https://unofficialbox.github.io/box-open-elements)** browses the full catalog with live previews, an events/properties inspector, per-framework code snippets (React / Angular / Vue / Svelte / HTML), and the foundations pages.
-
-Components track Box’s design language out of the box — tokens-driven, light and dark, keyboard-accessible:
-
-![A selection of form components — text field, search, select, checkboxes, radios, and a pill-selector dropdown](https://raw.githubusercontent.com/unofficialbox/box-open-elements/main/docs/screenshots/gallery/forms.png)
-
-## Setup
-
-This package uses Bun as its package manager and task runner.
+## Install
 
 ```bash
-bun install
+npm install @unofficialbox/box-open-elements
 ```
 
-## Common commands
+Importing the root registers the full `box-*` catalog; flat entrypoints register only the imported component:
 
-```bash
-bun run typecheck
-bun run test
-bun run test:coverage
-bun run build
-bun run verify
-bun run docs
+```ts
+import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
+import { TextField } from "@unofficialbox/box-open-elements/text-field";
 ```
 
-`bun run docs` builds the library and serves the component-documentation site at `http://localhost:4600` — browse the full catalog with live previews, events/properties inspectors, and foundations pages.
-
-`bun run verify` is the main safety check and runs typecheck, **coverage-gated** tests (`test:coverage`), and build in sequence.
-
-## Current state
-
-Full catalog parity with the reference repo, plus every scoped gap the research surfaced:
-
-- `src/core` — typed event emitter, controller base class, `BaseElement` (in-place shadow DOM render contract), and `FormAssociatedElement` (native form participation + invalid state)
-- `src/foundations/tokens` — the design-system registry (tokens, icons, illustrations), the Box default bundle, and the Box dark bundle, retoned to Box's modernized Blueprint palette with an Inter typography baseline; shared interaction helpers (`interaction.ts`) for focus/hover/active/disabled
-- `src/foundations/motion` — shared duration/easing vocabulary and reduced-motion CSS helper
-- `src/foundations/profiles` — typed runtime profiles for density, geometry, typography, elevation, and motion
-- `src/foundations/icons` — the generated Box iconography manifest and alias layer
-- `tools/style-bridge` — CSS/SCSS → BOE token/selector bridge (`bun run style-bridge`; BUE explorer: `bun run style-bridge:bue-explorer`)
-- `src/components` — 78 components across all ten categories, including the Phase 5 gap fills (`box-chip`, `box-divider`, `box-calendar`, `box-tag-input`, `box-nav-sidebar`, `box-sidebar-toggle-button`, `box-grid-view`, `box-fieldset`, `box-section`, `box-error-mask`, `box-draggable-list`, `box-nudge`, `box-pill-cloud`, `box-pill-selector-dropdown`, `box-datalist-item`, `box-contact-datalist-item`, `box-category-selector`)
-- `src/patterns/content-explorer` — the full headless explorer stack (collection, navigation, selection, actions, facade controller, data-source contracts, Box transport, wire schemas) plus the `box-explorer-*` presentation adapters and the composed `box-content-explorer` surface
-- `src/patterns/{search,item,metadata,share,preview,file-request,task,governance,insights}` — all nine composition/workflow areas, including contracts and wire schemas for metadata and share, the provider-neutral preview adapter stack, the pluggable `box-preview-element`, and the share workflows (`box-presence`, `box-invite-collaborators-modal`, `box-unified-share-modal`, `box-access-stats`, `box-collaborator-avatars`)
-- `packages/box-server` — a dependency-free server-side adapter: CCG auth + REST client, Box-backed explorer/share/metadata data sources, DTO mappers, and framework-neutral route handlers (see [docs/integration/box-server.md](./docs/integration/box-server.md))
-- `packages/{react,angular,vue,svelte}` — lockstep `0.1.0` framework adapters for `Button`, `TextField`, `Select`, `Dialog`, and explorer selection composition. Progress is tracked in [docs/integration/framework-adapters.md](./docs/integration/framework-adapters.md).
-- `storybook/` — a Bun-native workshop: typed stories → identity-guarded extracted JSON → a self-contained, separately-deployable static site, with no Storybook/Vite runtime or consumer dependency (see [storybook/README.md](./storybook/README.md))
-- Docs site + CI — live GitHub Pages deploy, Storybook-backed variant dropdown, and a strict pixel-diff visual-regression gate in CI
-
-**Fidelity program**: complete — Batches 0–7, the medium/low audit nits, and the design-heavy leftovers have shipped.
-
-Everything in the [components catalog](./docs/components/catalog.md) and [patterns catalog](./docs/patterns/catalog.md) that carries a **built** marker is implemented here with dedicated tests. Remaining catalog entries are intentional generic-component gaps whose current implementations are explorer-bound; future additions are gap-driven rather than phase-gated ports.
+```html
+<box-button label="Save" tone="primary"></box-button>
+```
 
-## Example: foundations + components
+Components consume foundation tokens (`--boe-token-*`) with safe fallbacks, so they render sensibly with no design system registered and restyle automatically when one is active:
 
 ```ts
-import {
-  createThemeController,
-} from "@unofficialbox/box-open-elements/foundations/theming";
-import { Button } from "@unofficialbox/box-open-elements";
+import { createThemeController } from "@unofficialbox/box-open-elements/foundations/theming";
 
 const theme = createThemeController();
 theme.start();
 ```
 
-```html
-<box-button label="Save" tone="primary"></box-button>
-```
-
-Components consume foundation tokens (`--boe-token-*`) with safe fallbacks, so they render sensibly with no design system registered and restyle automatically when one is active.
-
-## Example: headless patterns
+Workflow patterns begin as headless behavior and gain presentation adapters, so custom React components, Angular templates, Vue SFCs, Svelte components, Web Components, and plain DOM can all consume the same state:
 
 ```ts
 import { ExplorerSelectionController } from "@unofficialbox/box-open-elements/patterns/content-explorer/selection";
@@ -114,8 +67,6 @@ selection.setItems([{ id: "1" }, { id: "2" }]);
 selection.toggleSelection("1");
 ```
 
-Workflow patterns begin as headless behavior and gain presentation adapters, so custom React components, Angular templates, Vue SFCs, Svelte components, Web Components, and plain DOM can all consume the same state.
-
 ## Import contract
 
 - root exports: `@unofficialbox/box-open-elements`
@@ -124,15 +75,17 @@ Workflow patterns begin as headless behavior and gain presentation adapters, so
 - optimized component entrypoints: `@unofficialbox/box-open-elements/<name>`
 - patterns: `@unofficialbox/box-open-elements/patterns/<area>` and `@unofficialbox/box-open-elements/patterns/<area>/<module>`
 
-The root entrypoint is the concise convenience API and registers the full
-catalog. Flat component entrypoints register only the imported component:
+See [docs/api-guidelines.md](./docs/api-guidelines.md).
 
-```ts
-import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
-import { TextField } from "@unofficialbox/box-open-elements/text-field";
-```
+## Developing
 
-See [docs/api-guidelines.md](./docs/api-guidelines.md).
+This repo uses Bun as its package manager and task runner.
+
+```bash
+bun install
+bun run verify   # the main safety gate: typecheck, coverage-gated tests, build
+bun run docs     # build + serve the docs site at http://localhost:4600
+```
 
 ## Documentation
 
@@ -141,6 +94,7 @@ The docs index is at [docs/README.md](./docs/README.md). The most important entr
 - [Taxonomy](./docs/taxonomy.md)
 - [Architecture](./docs/architecture.md)
 - [API Guidelines](./docs/api-guidelines.md)
+- [Components catalog](./docs/components/catalog.md) and [patterns catalog](./docs/patterns/catalog.md)
 - [Using with React, Angular, Vue, and Svelte](./docs/integration/frameworks.md)
 - [Design Tokens](./docs/foundations/tokens.md)
 - [Content Explorer](./docs/patterns/content-explorer.md)

package/dist/components/collections/table.d.ts

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import type { RowWindow } from "../../core/index.js";
 export interface TableColumn {
     key: string;
     label: string;
@@ -60,9 +61,21 @@ export declare class Table extends BaseElement {
     static get observedAttributes(): string[];
     private bodyEl;
     private headEl;
+    private shellEl;
     private selected;
     private anchorIndex;
     private readonly expandedIds;
+    private lastWindow;
+    /**
+     * Whether the last render actually windowed. Not the same as `virtualize`:
+     * the flag is suppressed for a collection the fixed-height window cannot
+     * describe (see `update`). Cached at render time so the scroll handler does
+     * not re-parse `rows` on every frame to answer the question.
+     */
+    private windowing;
+    private scrollFrame;
+    private measuredRowHeight;
+    private measureFrame;
     /** True while rows are being fetched: the body states "Loading rows…". */
     get loading(): boolean;
     set loading(value: boolean);
@@ -72,6 +85,42 @@ export declare class Table extends BaseElement {
     /** Non-empty puts the table in an error state stating this text. */
     get errorText(): string;
     set errorText(value: string);
+    /**
+     * Render only the rows near the viewport. Opt-in: a windowed table needs a
+     * bounded height to scroll within, and silently windowing an unbounded table
+     * would render nothing.
+     *
+     * A request, not a guarantee. The window arithmetic is fixed-height, so it is
+     * suppressed for a collection whose rows can change height — today that means
+     * any collection where a row declares `detail`. Read `renderedWindow` to see
+     * whether a render actually windowed.
+     */
+    get virtualize(): boolean;
+    set virtualize(value: boolean);
+    /**
+     * Row height in pixels for the window arithmetic — a starting estimate, not
+     * a contract. The real height depends on density, font, and zoom, and a
+     * declared value that is off by a fraction of a pixel makes the scroll range
+     * drift as you scroll (a 10k-row table measured ~55px of wobble at 37px
+     * declared). After the first paint the element measures a rendered row and
+     * uses that instead, so the estimate only has to be close enough to pick a
+     * sane first window.
+     */
+    get rowHeight(): number;
+    private get declaredRowHeight();
+    set rowHeight(value: number);
+    /**
+     * Adopt the real rendered row height, once, when it differs from the value
+     * the last window was computed with. Re-rendering with the measured height
+     * settles immediately: the next measurement matches, so this cannot loop.
+     */
+    private measureRowHeight;
+    /**
+     * The window the last render used, or null when it rendered every row — for
+     * tests and hosts. Null despite `virtualize` means the collection is one the
+     * fixed-height window cannot describe and windowing was suppressed.
+     */
+    get renderedWindow(): RowWindow | null;
     /** Ids of the rows whose detail is expanded (host-readable). */
     get expandedRows(): string[];
     get columns(): TableColumn[];
@@ -97,11 +146,18 @@ export declare class Table extends BaseElement {
     private rowElements;
     private toggleRowDetail;
     private onBodyKeydown;
+    /**
+     * Focus a row by its absolute index, bringing it into the window first when
+     * virtualizing — keyboard navigation must be able to reach a row that is not
+     * currently rendered, or Home/End stop at the edge of the window.
+     */
+    private focusRowByIndex;
     private toggleSort;
     private activateRow;
     private selectRange;
     private selectAll;
     private setSelection;
     private applySelectionState;
+    private currentWindow;
     protected update(): void;
 }

package/dist/components/collections/table.js

@@ -1,4 +1,4 @@
-import { BaseElement } from "../../core/index.js";
+import { BaseElement, resolveRowWindow, sameRowWindow } from "../../core/index.js";
 import { boePanel, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { isSafeHref } from "../../patterns/internal/safe-href.js";
 const DEFAULT_TAG_NAME = "box-table";
@@ -113,6 +113,19 @@ const tableStyles = `
     box-shadow: inset 0 0 0 2px var(--boe-token-surface-surface-brand, #0061d5);
   }
 
+  /* Windowing needs a bounded viewport to scroll within: --boe-table-height is
+     the host's knob, defaulting to a sensible page-sized band. Sticky headers
+     already work inside this scroller. */
+  :host([virtualize]) [part="shell"] {
+    max-block-size: var(--boe-table-height, 26rem);
+    overflow-y: auto;
+  }
+
+  tr[part="spacer"] td {
+    border: 0;
+    padding: 0;
+  }
+
   [part="cell-badge"] {
     display: inline-block;
     padding: 0.08rem 0.5rem;
@@ -270,13 +283,27 @@ export class Table extends BaseElement {
             "sort-direction",
             "sort-key",
             "stacked",
+            "virtualize",
+            "row-height",
         ];
     }
     bodyEl;
     headEl;
+    shellEl;
     selected = new Set();
     anchorIndex = -1;
     expandedIds = new Set();
+    lastWindow = null;
+    /**
+     * Whether the last render actually windowed. Not the same as `virtualize`:
+     * the flag is suppressed for a collection the fixed-height window cannot
+     * describe (see `update`). Cached at render time so the scroll handler does
+     * not re-parse `rows` on every frame to answer the question.
+     */
+    windowing = false;
+    scrollFrame = 0;
+    measuredRowHeight = 0;
+    measureFrame = 0;
     /** True while rows are being fetched: the body states "Loading rows…". */
     get loading() {
         return this.hasAttribute("loading");
@@ -303,6 +330,73 @@ export class Table extends BaseElement {
             this.removeAttribute("error-text");
         }
     }
+    /**
+     * Render only the rows near the viewport. Opt-in: a windowed table needs a
+     * bounded height to scroll within, and silently windowing an unbounded table
+     * would render nothing.
+     *
+     * A request, not a guarantee. The window arithmetic is fixed-height, so it is
+     * suppressed for a collection whose rows can change height — today that means
+     * any collection where a row declares `detail`. Read `renderedWindow` to see
+     * whether a render actually windowed.
+     */
+    get virtualize() {
+        return this.hasAttribute("virtualize");
+    }
+    set virtualize(value) {
+        this.toggleAttribute("virtualize", Boolean(value));
+    }
+    /**
+     * Row height in pixels for the window arithmetic — a starting estimate, not
+     * a contract. The real height depends on density, font, and zoom, and a
+     * declared value that is off by a fraction of a pixel makes the scroll range
+     * drift as you scroll (a 10k-row table measured ~55px of wobble at 37px
+     * declared). After the first paint the element measures a rendered row and
+     * uses that instead, so the estimate only has to be close enough to pick a
+     * sane first window.
+     */
+    get rowHeight() {
+        if (this.measuredRowHeight > 0) {
+            return this.measuredRowHeight;
+        }
+        return this.declaredRowHeight;
+    }
+    get declaredRowHeight() {
+        const raw = Number(this.getAttribute("row-height"));
+        return Number.isFinite(raw) && raw > 0 ? raw : 37;
+    }
+    set rowHeight(value) {
+        // A new declaration supersedes the old measurement; the next paint
+        // measures again.
+        this.measuredRowHeight = 0;
+        this.setAttribute("row-height", String(value));
+    }
+    /**
+     * Adopt the real rendered row height, once, when it differs from the value
+     * the last window was computed with. Re-rendering with the measured height
+     * settles immediately: the next measurement matches, so this cannot loop.
+     */
+    measureRowHeight() {
+        if (!this.windowing || this.measureFrame)
+            return;
+        const row = this.bodyEl.querySelector('[part="row"]');
+        const height = row?.getBoundingClientRect().height ?? 0;
+        if (height <= 0 || Math.abs(height - this.rowHeight) < 0.5)
+            return;
+        this.measuredRowHeight = height;
+        this.measureFrame = requestAnimationFrame(() => {
+            this.measureFrame = 0;
+            this.update();
+        });
+    }
+    /**
+     * The window the last render used, or null when it rendered every row — for
+     * tests and hosts. Null despite `virtualize` means the collection is one the
+     * fixed-height window cannot describe and windowing was suppressed.
+     */
+    get renderedWindow() {
+        return this.windowing ? this.lastWindow : null;
+    }
     /** Ids of the rows whose detail is expanded (host-readable). */
     get expandedRows() {
         return [...this.expandedIds];
@@ -396,8 +490,23 @@ export class Table extends BaseElement {
     `;
         this.headEl = this.shadowRoot.querySelector('[part="header-row"]');
         this.bodyEl = this.shadowRoot.querySelector('[part="body"]');
+        this.shellEl = this.shadowRoot.querySelector('[part="shell"]');
     }
     setupListeners() {
+        // 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 rows already rendered.
+        this.shellEl.addEventListener("scroll", () => {
+            if (!this.windowing || this.scrollFrame)
+                return;
+            this.scrollFrame = requestAnimationFrame(() => {
+                this.scrollFrame = 0;
+                const next = this.currentWindow();
+                if (this.lastWindow && sameRowWindow(this.lastWindow, next))
+                    return;
+                this.update();
+            });
+        }, { passive: true });
         this.headEl.addEventListener("click", event => {
             const th = event.target.closest('th[part="sortable"]');
             if (!th)
@@ -448,8 +557,7 @@ export class Table extends BaseElement {
         // must not double as row selection.
         if (event.target.closest('[part="expander"]'))
             return;
-        const rows = this.rowElements();
-        if (rows.length === 0)
+        if (this.rowElements().length === 0)
             return;
         const currentRow = event.target.closest('[part="row"]');
         const index = currentRow ? Number(currentRow.dataset.index) : -1;
@@ -472,24 +580,46 @@ export class Table extends BaseElement {
             this.activateRow(index, { toggle: this.selectionMode === "multiple" });
             return;
         }
+        // Bounds come from the data, not the DOM: when windowing, the rendered
+        // rows are a slice and `rows.length` would stop End at the bottom of the
+        // window instead of the bottom of the collection.
+        const lastIndex = this.rows.length - 1;
         let nextIndex = index;
         if (event.key === "ArrowDown")
-            nextIndex = Math.min(index + 1, rows.length - 1);
+            nextIndex = Math.min(index + 1, lastIndex);
         else if (event.key === "ArrowUp")
             nextIndex = Math.max(index - 1, 0);
         else if (event.key === "Home")
             nextIndex = 0;
         else if (event.key === "End")
-            nextIndex = rows.length - 1;
+            nextIndex = lastIndex;
         else
             return;
         event.preventDefault();
-        rows[nextIndex]?.focus();
+        this.focusRowByIndex(nextIndex);
         // Shift+Arrow extends the selection from the anchor.
         if (event.shiftKey && this.selectionMode === "multiple") {
             this.selectRange(this.anchorIndex < 0 ? index : this.anchorIndex, nextIndex);
         }
     }
+    /**
+     * Focus a row by its absolute index, bringing it into the window first when
+     * virtualizing — keyboard navigation must be able to reach a row that is not
+     * currently rendered, or Home/End stop at the edge of the window.
+     */
+    focusRowByIndex(index) {
+        const find = () => this.bodyEl.querySelector(`[part="row"][data-index="${String(index)}"]`);
+        let target = find();
+        if (!target && this.windowing && this.shellEl) {
+            // Scroll the row to the top of the viewport, then re-render the window
+            // synchronously: the scroll event's own re-render lands a frame later,
+            // and focus cannot wait for it.
+            this.shellEl.scrollTop = index * this.rowHeight;
+            this.update();
+            target = find();
+        }
+        target?.focus();
+    }
     toggleSort(key) {
         const currentKey = this.getAttribute("sort-key");
         const currentDir = this.getAttribute("sort-direction");
@@ -548,6 +678,14 @@ export class Table extends BaseElement {
             row.setAttribute("aria-selected", String(this.selected.has(id)));
         }
     }
+    currentWindow() {
+        return resolveRowWindow({
+            totalRows: this.rows.length,
+            rowHeight: this.rowHeight,
+            viewportHeight: this.shellEl?.clientHeight ?? 0,
+            scrollTop: this.shellEl?.scrollTop ?? 0,
+        });
+    }
     update() {
         if (!this.bodyEl || !this.headEl)
             return;
@@ -587,6 +725,11 @@ export class Table extends BaseElement {
                     return `<th scope="col"${align}>${escapeHtml(column.label)}</th>`;
                 })
                     .join("");
+        // A state row is never windowed. Cleared up front so a table that drops
+        // into loading/error/empty does not leave the previous window's flag
+        // standing — the scroll handler and `renderedWindow` both read it.
+        this.windowing = false;
+        this.lastWindow = null;
         // Loading, error, and empty are stated in words in the body — a blank
         // grid reads as broken. Loading wins; a stale error must not outlive a
         // retry that is visibly in flight.
@@ -602,35 +745,76 @@ export class Table extends BaseElement {
             this.bodyEl.innerHTML = `<tr part="state-row" data-state="empty" role="row"><td role="${selectable ? "gridcell" : "cell"}" colspan="${String(columnCount)}">${escapeHtml(this.emptyText)}</td></tr>`;
             return;
         }
-        this.bodyEl.innerHTML = rows
-            .map((row, index) => {
-            const selected = this.selected.has(row.id);
-            const cellRole = selectable ? ' role="gridcell"' : ' role="cell"';
-            const rowAttrs = selectable
-                ? ` part="row" role="row" tabindex="${index === 0 ? "0" : "-1"}" aria-selected="${selected}"`
-                : ' part="row" role="row"';
-            const expanded = this.expandedIds.has(row.id);
-            const expanderCell = expandable
-                ? `<td${cellRole} part="expander-cell">${typeof row.detail === "string"
-                    ? `<button type="button" part="expander" data-row-id="${escapeHtml(row.id)}" aria-expanded="${String(expanded)}" aria-label="${expanded ? "Hide" : "Show"} details for row ${escapeHtml(row.id)}"></button>`
-                    : ""}</td>`
-                : "";
-            const cells = columns
-                .map((column, columnIndex) => {
-                const align = alignAttr(column.align);
-                const value = this.cellValue(row, column, columnIndex);
-                return `<td${align}${cellRole} data-label="${escapeHtml(column.label)}">${this.cellMarkup(value)}</td>`;
-            })
-                .join("");
-            const rowMarkup = `<tr${rowAttrs} data-index="${index}" data-id="${escapeHtml(row.id)}">${expanderCell}${cells}</tr>`;
-            // The detail row renders only while expanded, keeping the roving
-            // tabindex and shift-range math on visible [part="row"] rows only.
-            const detailRow = typeof row.detail === "string" && expanded
-                ? `<tr part="detail-row" role="row" data-for="${escapeHtml(row.id)}"><td${cellRole} colspan="${String(columnCount)}">${escapeHtml(row.detail)}<slot name="detail-${escapeHtml(row.id)}"></slot></td></tr>`
-                : "";
-            return rowMarkup + detailRow;
-        })
-            .join("");
+        // Windowing renders only the rows near the viewport, padded with spacer
+        // rows so the scrollbar still describes the whole collection. Indices stay
+        // ABSOLUTE: selection, shift-range, and activateRow all address `rows`, and
+        // renumbering the slice would select the wrong record.
+        //
+        // `virtualize` is a request, not a guarantee. `resolveRowWindow` derives
+        // the whole scroll range from `rows.length * rowHeight`, so it can only
+        // describe a collection of uniform, fixed-height rows. An expanded row
+        // renders a second `<tr part="detail-row">` the arithmetic knows nothing
+        // about: the real content grows taller than the spacers claim, the scroll
+        // range no longer matches the scrollbar, and scrollTop stops mapping to the
+        // right absolute index — so a windowed table with expandable rows would
+        // scroll to the wrong record. Variable heights are a different algorithm (a
+        // cumulative offset index), not a flag on this one, so windowing is
+        // suppressed rather than approximated.
+        //
+        // The test is `expandable`, not "is anything expanded right now": deciding
+        // from transient UI state would flip windowing on and off mid-scroll, which
+        // jumps the viewport under the pointer. A collection that can expand never
+        // windows; `renderedWindow` returns null so a host can see that it didn't.
+        const virtualizing = this.virtualize && !expandable;
+        const rowWindow = virtualizing ? this.currentWindow() : null;
+        this.windowing = virtualizing;
+        this.lastWindow = rowWindow;
+        const visibleRows = rowWindow
+            ? rows.slice(rowWindow.startIndex, rowWindow.endIndex)
+            : rows;
+        const indexOffset = rowWindow?.startIndex ?? 0;
+        // The tab stop belongs to the first row that is actually rendered; row 0
+        // may be scrolled far out of the window.
+        const tabbableIndex = indexOffset;
+        const spacer = (height, position) => height > 0
+            ? `<tr part="spacer" data-position="${position}" aria-hidden="true"><td colspan="${String(columnCount)}" style="height:${String(height)}px;padding:0;border:0;"></td></tr>`
+            : "";
+        this.bodyEl.innerHTML =
+            (rowWindow ? spacer(rowWindow.paddingTop, "top") : "") +
+                visibleRows
+                    .map((row, offset) => {
+                    const index = offset + indexOffset;
+                    const selected = this.selected.has(row.id);
+                    const cellRole = selectable ? ' role="gridcell"' : ' role="cell"';
+                    const rowAttrs = selectable
+                        ? ` part="row" role="row" tabindex="${index === tabbableIndex ? "0" : "-1"}" aria-selected="${selected}"`
+                        : ' part="row" role="row"';
+                    const expanded = this.expandedIds.has(row.id);
+                    const expanderCell = expandable
+                        ? `<td${cellRole} part="expander-cell">${typeof row.detail === "string"
+                            ? `<button type="button" part="expander" data-row-id="${escapeHtml(row.id)}" aria-expanded="${String(expanded)}" aria-label="${expanded ? "Hide" : "Show"} details for row ${escapeHtml(row.id)}"></button>`
+                            : ""}</td>`
+                        : "";
+                    const cells = columns
+                        .map((column, columnIndex) => {
+                        const align = alignAttr(column.align);
+                        const value = this.cellValue(row, column, columnIndex);
+                        return `<td${align}${cellRole} data-label="${escapeHtml(column.label)}">${this.cellMarkup(value)}</td>`;
+                    })
+                        .join("");
+                    const rowMarkup = `<tr${rowAttrs} data-index="${index}" data-id="${escapeHtml(row.id)}">${expanderCell}${cells}</tr>`;
+                    // The detail row renders only while expanded, keeping the roving
+                    // tabindex and shift-range math on visible [part="row"] rows only.
+                    const detailRow = typeof row.detail === "string" && expanded
+                        ? `<tr part="detail-row" role="row" data-for="${escapeHtml(row.id)}"><td${cellRole} colspan="${String(columnCount)}">${escapeHtml(row.detail)}<slot name="detail-${escapeHtml(row.id)}"></slot></td></tr>`
+                        : "";
+                    return rowMarkup + detailRow;
+                })
+                    .join("") +
+                (rowWindow ? spacer(rowWindow.paddingBottom, "bottom") : "");
+        if (virtualizing) {
+            this.measureRowHeight();
+        }
     }
 }
 Table.register();

package/dist/core/index.d.ts

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

package/dist/core/index.js

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