@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@
 
 > **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.
 
-It is a ground-up rebuild of [`box-open-web-components`](https://github.com/unofficialbox/box-open-web-components), carrying forward that repo's validated architecture, docs, and research — without its accumulated baggage — under a new industry-standard taxonomy:
+The library is organized around three layers:
 
 - **Foundations** — design decisions as data: tokens, color, typography, iconography, accessibility, theming
 - **Components** — accessible Web Components for single controls, organized by category
@@ -18,7 +18,7 @@ It is a ground-up rebuild of [`box-open-web-components`](https://github.com/unof
 
 See [docs/taxonomy.md](./docs/taxonomy.md) for the canonical model.
 
-The guiding idea is unchanged: predictable, extensible building blocks that are easy for both human developers and AI coding assistants to compose.
+Core implementation principles:
 
 - plain TypeScript modules, no React requirement in the core package
 - state and business logic separate from rendering: controllers and stores, not framework components
@@ -73,7 +73,7 @@ Full catalog parity with the reference repo, plus every scoped gap the research
 - `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` — optional React wrappers (`@box-open-elements/react`); the validated surface ships `Button`, `TextField`, and `Select`. React, Angular, Vue, and Svelte progress is tracked in [docs/integration/framework-adapters.md](./docs/integration/framework-adapters.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
 

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

@@ -7,12 +7,47 @@ export interface TableColumn {
     /** Mark the column sortable — clicking its header emits `sort`. */
     sortable?: boolean;
 }
+export type TableCellTone = "neutral" | "brand" | "success" | "warning" | "error";
+/**
+ * Declarative cell content beyond plain text. Deliberately a descriptor the
+ * table renders itself, never an HTML string or a render callback: cell data
+ * is server-supplied and stays escaped — a string renderer would reopen the
+ * injection hole the escaping exists to close.
+ */
+export interface TableCellDescriptor {
+    kind: "text" | "badge" | "link";
+    text: string;
+    /** Badge colour; the text still carries the meaning. */
+    tone?: TableCellTone;
+    /** Link target; non-http(s) schemes render as plain text. */
+    href?: string;
+}
+export type TableCellValue = string | TableCellDescriptor;
 export interface TableRow {
     id: string;
-    /** Cell text keyed by column key, or positional strings matching `columns`. */
-    cells: Record<string, string> | string[];
+    /** Cell values keyed by column key, or positional, matching `columns`. */
+    cells: Record<string, TableCellValue> | TableCellValue[];
+    /**
+     * Expandable detail. Renders a per-row toggle and a full-width detail row
+     * holding this text plus a `detail-<id>` slot for rich host content.
+     */
+    detail?: string;
 }
 export type TableSelectionMode = "none" | "single" | "multiple";
+/** Detail of the `sort` event, for typed listeners. */
+export interface TableSortDetail {
+    key: string;
+    direction: "ascending" | "descending";
+}
+/** Detail of the `selection-changed` event, for typed listeners. */
+export interface TableSelectionChangedDetail {
+    selectedIds: string[];
+}
+/** Detail of the `row-toggled` event, for typed listeners. */
+export interface TableRowToggledDetail {
+    rowId: string;
+    expanded: boolean;
+}
 /**
  * A semantic, selectable data table — box-ui-elements `Table` + `makeSelectable`.
  * Rows and columns come from JSON. Selection supports single / Ctrl-click toggle
@@ -27,6 +62,18 @@ export declare class Table extends BaseElement {
     private headEl;
     private selected;
     private anchorIndex;
+    private readonly expandedIds;
+    /** True while rows are being fetched: the body states "Loading rows…". */
+    get loading(): boolean;
+    set loading(value: boolean);
+    /** What the body says when there are no rows and nothing is loading. */
+    get emptyText(): string;
+    set emptyText(value: string);
+    /** Non-empty puts the table in an error state stating this text. */
+    get errorText(): string;
+    set errorText(value: string);
+    /** Ids of the rows whose detail is expanded (host-readable). */
+    get expandedRows(): string[];
     get columns(): TableColumn[];
     set columns(value: TableColumn[]);
     get rows(): TableRow[];
@@ -38,10 +85,17 @@ export declare class Table extends BaseElement {
     get label(): string;
     set label(value: string);
     private parseJson;
-    private cellText;
+    private cellValue;
+    /**
+     * Descriptor rendering. Everything is escaped; a link with a non-http(s)
+     * href renders as plain text; a badge's tone colours a word that already
+     * carries the meaning.
+     */
+    private cellMarkup;
     protected renderTemplate(): void;
     protected setupListeners(): void;
     private rowElements;
+    private toggleRowDetail;
     private onBodyKeydown;
     private toggleSort;
     private activateRow;

package/dist/components/collections/table.js

@@ -1,6 +1,15 @@
 import { BaseElement } 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";
+const CELL_TONES = new Set(["neutral", "brand", "success", "warning", "error"]);
+const CELL_ALIGNS = new Set(["start", "end", "center"]);
+/** `align` is author input from a JSON attribute like everything else — an
+ * unvalidated value would close the attribute and inject markup. */
+const alignAttr = (align) => align && CELL_ALIGNS.has(align) ? ` data-align="${align}"` : "";
+const isCellDescriptor = (value) => typeof value === "object" && value !== null && typeof value.text === "string";
+/** Escape a value for use inside a double-quoted attribute selector. */
+const cssAttrValue = (value) => value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
     .replaceAll("<", "&lt;")
@@ -47,8 +56,35 @@ const tableStyles = `
   th[part="sortable"] {
     cursor: pointer;
     user-select: none;
+    /* The button carries the padding so its hit area fills the cell. */
+    padding: 0;
   }
   th[part="sortable"]:hover { color: var(--boe-token-text-text, #222222); }
+
+  /* A real button, so sorting is reachable by keyboard: focus, Enter and
+     Space come from the platform instead of a keydown reimplementation. */
+  [part="sort-button"] {
+    appearance: none;
+    display: block;
+    width: 100%;
+    padding: ${boeSpace[2]} ${boeSpace[3]};
+    border: 0;
+    background: transparent;
+    font: inherit;
+    letter-spacing: inherit;
+    text-transform: inherit;
+    text-align: inherit;
+    color: inherit;
+    cursor: pointer;
+  }
+
+  th[data-align="end"] [part="sort-button"] { text-align: end; }
+  th[data-align="center"] [part="sort-button"] { text-align: center; }
+
+  [part="sort-button"]:focus-visible {
+    outline: none;
+    box-shadow: inset 0 0 0 2px var(--boe-token-surface-surface-brand, #0061d5);
+  }
   th[aria-sort] .boe-sort-arrow::after { content: " ↕"; opacity: 0.5; }
   th[aria-sort="ascending"] .boe-sort-arrow::after { content: " ↑"; opacity: 1; }
   th[aria-sort="descending"] .boe-sort-arrow::after { content: " ↓"; opacity: 1; }
@@ -76,7 +112,143 @@ const tableStyles = `
   tbody tr[part="row"]:focus-visible td {
     box-shadow: inset 0 0 0 2px var(--boe-token-surface-surface-brand, #0061d5);
   }
+
+  [part="cell-badge"] {
+    display: inline-block;
+    padding: 0.08rem 0.5rem;
+    border-radius: 999px;
+    font-size: 0.74rem;
+    font-weight: 700;
+    color: color-mix(in srgb, var(--cell-tone, var(--boe-token-text-text-secondary, #6f6f6f)) 76%, black 24%);
+    background: color-mix(in srgb, var(--cell-tone, var(--boe-token-text-text-secondary, #6f6f6f)) 14%, transparent);
+    border: 1px solid color-mix(in srgb, var(--cell-tone, var(--boe-token-text-text-secondary, #6f6f6f)) 30%, transparent);
+  }
+
+  [part="cell-link"] {
+    color: var(--boe-token-surface-surface-brand, #0061d5);
+    text-decoration: none;
+  }
+
+  [part="cell-link"]:hover {
+    text-decoration: underline;
+  }
+
+  [part="expander"] {
+    appearance: none;
+    display: inline-grid;
+    place-items: center;
+    inline-size: 1.4rem;
+    block-size: 1.4rem;
+    border: 0;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    font: inherit;
+    font-size: 0.72rem;
+    cursor: pointer;
+  }
+
+  [part="expander"]:hover {
+    background: var(--boe-token-surface-surface-hover, #f4f4f4);
+  }
+
+  [part="expander"]:focus-visible {
+    outline: 2px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 34%, transparent);
+    outline-offset: 1px;
+  }
+
+  [part="expander"]::before {
+    content: "▸";
+    transition: transform 120ms ease;
+  }
+
+  [part="expander"][aria-expanded="true"]::before {
+    transform: rotate(90deg);
+  }
+
+  tr[part="detail-row"] td {
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 80%, transparent);
+    font-size: 0.84rem;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  tr[part="state-row"] td {
+    padding: 1.1rem ${boeSpace[3]};
+    text-align: center;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  tr[part="state-row"][data-state="error"] td {
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+  }
+
+  [part="state-spinner"] {
+    display: inline-block;
+    vertical-align: -0.15rem;
+    margin-inline-end: 0.45rem;
+    inline-size: 0.95rem;
+    block-size: 0.95rem;
+    border-radius: 999px;
+    border: 2px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 20%, transparent);
+    border-top-color: var(--boe-token-surface-surface-brand, #0061d5);
+    animation: boe-table-spin 0.9s linear infinite;
+  }
+
+  @keyframes boe-table-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part="state-spinner"] { animation-duration: 1.6s; }
+  }
+
+  /* Stacked rows: each row becomes a card, each cell states its column via
+     data-label. Roles are explicit on rows and cells, so the grid semantics
+     survive the display change. stacked="always" forces it; stacked="auto"
+     stacks when the host container narrows. */
+  :host {
+    container-type: inline-size;
+  }
+` +
+    (() => {
+        const rules = (scope) => `
+  ${scope} thead { display: none; }
+  ${scope} tr[part="row"] {
+    display: block;
+    padding: ${boeSpace[2]} 0;
+  }
+  ${scope} tbody td {
+    display: grid;
+    grid-template-columns: minmax(7.5rem, 9rem) 1fr;
+    gap: 0.5rem;
+    border-bottom: none;
+    padding-block: 0.18rem;
+    text-align: start;
+  }
+  ${scope} tbody td[data-label]::before {
+    content: attr(data-label);
+    font-size: 0.74rem;
+    font-weight: 700;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    align-self: center;
+  }
+  ${scope} tr[part="row"]:not(:last-child) {
+    border-bottom: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+  }
+  ${scope} tr[part="detail-row"] td,
+  ${scope} tr[part="state-row"] td {
+    display: block;
+  }
 `;
+        return `
+  ${rules(':host([stacked]:not([stacked="auto"]))')}
+  @container (max-width: 560px) {
+    ${rules(':host([stacked="auto"])')}
+  }
+`;
+    })();
 /**
  * A semantic, selectable data table — box-ui-elements `Table` + `makeSelectable`.
  * Rows and columns come from JSON. Selection supports single / Ctrl-click toggle
@@ -87,12 +259,54 @@ const tableStyles = `
 export class Table extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["columns", "rows", "selection-mode", "label", "sort-key", "sort-direction"];
+        return [
+            "columns",
+            "empty-text",
+            "error-text",
+            "label",
+            "loading",
+            "rows",
+            "selection-mode",
+            "sort-direction",
+            "sort-key",
+            "stacked",
+        ];
     }
     bodyEl;
     headEl;
     selected = new Set();
     anchorIndex = -1;
+    expandedIds = new Set();
+    /** True while rows are being fetched: the body states "Loading rows…". */
+    get loading() {
+        return this.hasAttribute("loading");
+    }
+    set loading(value) {
+        this.toggleAttribute("loading", Boolean(value));
+    }
+    /** What the body says when there are no rows and nothing is loading. */
+    get emptyText() {
+        return this.getAttribute("empty-text") ?? "No rows";
+    }
+    set emptyText(value) {
+        this.setAttribute("empty-text", value);
+    }
+    /** Non-empty puts the table in an error state stating this text. */
+    get errorText() {
+        return this.getAttribute("error-text") ?? "";
+    }
+    set errorText(value) {
+        if (value) {
+            this.setAttribute("error-text", value);
+        }
+        else {
+            this.removeAttribute("error-text");
+        }
+    }
+    /** Ids of the rows whose detail is expanded (host-readable). */
+    get expandedRows() {
+        return [...this.expandedIds];
+    }
     get columns() {
         return this.parseJson("columns", []);
     }
@@ -139,12 +353,35 @@ export class Table extends BaseElement {
             return fallback;
         }
     }
-    cellText(row, column, index) {
+    cellValue(row, column, index) {
         if (Array.isArray(row.cells)) {
             return row.cells[index] ?? "";
         }
         return row.cells[column.key] ?? "";
     }
+    /**
+     * Descriptor rendering. Everything is escaped; a link with a non-http(s)
+     * href renders as plain text; a badge's tone colours a word that already
+     * carries the meaning.
+     */
+    cellMarkup(value) {
+        if (!isCellDescriptor(value)) {
+            return escapeHtml(typeof value === "string" ? value : "");
+        }
+        if (value.kind === "badge") {
+            const tone = value.tone && CELL_TONES.has(value.tone) ? value.tone : "neutral";
+            const toneVar = tone === "neutral"
+                ? "var(--boe-token-text-text-secondary, #6f6f6f)"
+                : tone === "brand"
+                    ? "var(--boe-token-surface-surface-brand, #0061d5)"
+                    : `var(--boe-token-surface-status-surface-${tone}, #6f6f6f)`;
+            return `<span part="cell-badge" style="--cell-tone:${toneVar};">${escapeHtml(value.text)}</span>`;
+        }
+        if (value.kind === "link" && value.href && isSafeHref(value.href)) {
+            return `<a part="cell-link" href="${escapeHtml(value.href)}">${escapeHtml(value.text)}</a>`;
+        }
+        return escapeHtml(value.text);
+    }
     renderTemplate() {
         if (!this.shadowRoot)
             return;
@@ -168,6 +405,11 @@ export class Table extends BaseElement {
             this.toggleSort(th.dataset.key ?? "");
         });
         this.bodyEl.addEventListener("click", event => {
+            const expander = event.target.closest('[part="expander"]');
+            if (expander) {
+                this.toggleRowDetail(expander.dataset.rowId ?? "");
+                return; // expanding is not selecting
+            }
             const row = event.target.closest('[part="row"]');
             if (!row)
                 return;
@@ -179,7 +421,33 @@ export class Table extends BaseElement {
     rowElements() {
         return Array.from(this.bodyEl.querySelectorAll('[part="row"]'));
     }
+    toggleRowDetail(rowId) {
+        if (!rowId)
+            return;
+        const expanded = !this.expandedIds.has(rowId);
+        if (expanded) {
+            this.expandedIds.add(rowId);
+        }
+        else {
+            this.expandedIds.delete(rowId);
+        }
+        this.dispatchEvent(new CustomEvent("row-toggled", {
+            bubbles: true,
+            composed: true,
+            detail: { rowId, expanded },
+        }));
+        this.update();
+        // update() rewrote the body, destroying the button that was activated;
+        // put focus on its replacement so a keyboard user is not dropped.
+        this.bodyEl
+            .querySelector(`[part="expander"][data-row-id="${cssAttrValue(rowId)}"]`)
+            ?.focus();
+    }
     onBodyKeydown(event) {
+        // Keys aimed at the expander button (Enter/Space activate it natively)
+        // must not double as row selection.
+        if (event.target.closest('[part="expander"]'))
+            return;
         const rows = this.rowElements();
         if (rows.length === 0)
             return;
@@ -226,7 +494,11 @@ export class Table extends BaseElement {
         const currentKey = this.getAttribute("sort-key");
         const currentDir = this.getAttribute("sort-direction");
         const direction = currentKey === key && currentDir === "ascending" ? "descending" : "ascending";
-        this.dispatchEvent(new CustomEvent("sort", { bubbles: true, composed: true, detail: { key, direction } }));
+        this.dispatchEvent(new CustomEvent("sort", {
+            bubbles: true,
+            composed: true,
+            detail: { key, direction },
+        }));
     }
     activateRow(index, options = {}) {
         const rows = this.rows;
@@ -284,32 +556,79 @@ export class Table extends BaseElement {
         const selectable = this.selectionMode !== "none";
         const sortKey = this.getAttribute("sort-key");
         const sortDir = this.getAttribute("sort-direction");
-        this.shadowRoot?.querySelector('[part="table"]')?.setAttribute("aria-label", this.label);
-        this.shadowRoot?.querySelector('[part="table"]')?.setAttribute("role", selectable ? "grid" : "table");
-        this.headEl.innerHTML = columns
-            .map(column => {
-            const align = column.align ? ` data-align="${column.align}"` : "";
-            if (column.sortable) {
-                const sort = sortKey === column.key ? ` aria-sort="${sortDir === "descending" ? "descending" : "ascending"}"` : ' aria-sort="none"';
-                return `<th part="sortable" scope="col" data-key="${escapeHtml(column.key)}"${align}${sort}>${escapeHtml(column.label)}<span class="boe-sort-arrow" aria-hidden="true"></span></th>`;
-            }
-            return `<th scope="col"${align}>${escapeHtml(column.label)}</th>`;
-        })
-            .join("");
+        // A non-string detail is malformed input, not a crash: it gets no expander.
+        const expandable = rows.some(row => typeof row.detail === "string");
+        const columnCount = columns.length + (expandable ? 1 : 0);
+        const tableEl = this.shadowRoot?.querySelector('[part="table"]');
+        tableEl?.setAttribute("aria-label", this.label);
+        tableEl?.setAttribute("role", selectable ? "grid" : "table");
+        if (this.loading) {
+            tableEl?.setAttribute("aria-busy", "true");
+        }
+        else {
+            tableEl?.removeAttribute("aria-busy");
+        }
+        this.headEl.innerHTML =
+            (expandable ? `<th scope="col" aria-label="Row details"></th>` : "") +
+                columns
+                    .map(column => {
+                    const align = alignAttr(column.align);
+                    if (column.sortable) {
+                        const sorted = sortKey === column.key;
+                        const sort = sorted
+                            ? ` aria-sort="${sortDir === "descending" ? "descending" : "ascending"}"`
+                            : ' aria-sort="none"';
+                        // The state, in words as well as the arrow glyph.
+                        const stateLabel = sorted
+                            ? `, sorted ${sortDir === "descending" ? "descending" : "ascending"}`
+                            : ", not sorted";
+                        return `<th part="sortable" scope="col" data-key="${escapeHtml(column.key)}"${align}${sort}><button type="button" part="sort-button" aria-label="Sort by ${escapeHtml(column.label)}${stateLabel}">${escapeHtml(column.label)}<span class="boe-sort-arrow" aria-hidden="true"></span></button></th>`;
+                    }
+                    return `<th scope="col"${align}>${escapeHtml(column.label)}</th>`;
+                })
+                    .join("");
+        // 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.
+        if (this.loading) {
+            this.bodyEl.innerHTML = `<tr part="state-row" data-state="loading" role="row"><td role="${selectable ? "gridcell" : "cell"}" colspan="${String(columnCount)}"><span part="state-spinner" aria-hidden="true"></span>Loading rows…</td></tr>`;
+            return;
+        }
+        if (this.errorText) {
+            this.bodyEl.innerHTML = `<tr part="state-row" data-state="error" role="row"><td role="${selectable ? "gridcell" : "cell"}" colspan="${String(columnCount)}">${escapeHtml(this.errorText)}</td></tr>`;
+            return;
+        }
+        if (rows.length === 0) {
+            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 => {
-                const align = column.align ? ` data-align="${column.align}"` : "";
-                const role = selectable ? ' role="gridcell"' : ' role="cell"';
-                return `<td${align}${role}>${escapeHtml(this.cellText(row, column, columns.indexOf(column)))}</td>`;
+                .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("");
-            return `<tr${rowAttrs} data-index="${index}" data-id="${escapeHtml(row.id)}">${cells}</tr>`;
+            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("");
     }

package/dist/components/feedback/due-badge.d.ts

@@ -0,0 +1,38 @@
+import type { DueBucket } from "./due-types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * SLA / aging urgency for a due date — the badge the work-queue rows and
+ * record headers were specified to share.
+ *
+ * The label states the urgency in words ("Overdue by 3 days"), so colour is
+ * never the only signal, and the day count answers the question a due badge
+ * exists for: *how late is this?* A bare date makes the reader do that
+ * arithmetic themselves.
+ *
+ * `reference-time` pins "now" so rendering is deterministic — the same
+ * inputs always produce the same badge, in tests and in screenshots.
+ */
+export declare class DueBadge extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private badgeEl;
+    private textEl;
+    /** ISO timestamp the badge describes. Absent renders the no-due-date state. */
+    get dueAt(): string;
+    set dueAt(value: string);
+    /** Overrides the derived wording; the bucket still drives the tone. */
+    get label(): string;
+    set label(value: string);
+    get compact(): boolean;
+    set compact(value: boolean);
+    get referenceTime(): string;
+    set referenceTime(value: string);
+    private now;
+    /** The urgency bucket currently rendered. */
+    get bucket(): DueBucket;
+    /** The rendered wording, derived unless `label` overrides it. */
+    get resolvedLabel(): string;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}