@unofficialbox/box-open-elements 0.9.0 → 0.11.0

package/dist/components/overlays/shortcuts-overlay.js

@@ -1,5 +1,6 @@
 import { groupShortcutCommands, isCommandDescriptorRecord, splitShortcutKeys, } from "./command-types.js";
 import { BaseElement } from "../../core/index.js";
+import { dismissModal, promoteModal } from "../../foundations/overlay/index.js";
 import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
 import { boeOverlay, boePanel, boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-shortcuts-overlay";
@@ -37,6 +38,10 @@ const elementStyles = `
           display: contents;
         }
 
+        /* A <dialog> promoted with showModal() — see
+           foundations/overlay/top-layer.ts. The top layer keeps the scrim above
+           the page without moving the host node. UA border/margin/max-* reset
+           because this is the full-viewport scrim, not a centred card. */
         [part="backdrop"] {
           position: fixed;
           inset: 0;
@@ -46,6 +51,24 @@ const elementStyles = `
           padding: 1rem;
           background: ${boeOverlay.modalBackdrop};
           z-index: 1000;
+          border: 0;
+          margin: 0;
+          max-width: none;
+          max-height: none;
+          width: auto;
+          height: auto;
+          color: inherit;
+        }
+
+        /* The scrim paints itself; the UA pseudo must not double it up. */
+        [part="backdrop"]::backdrop {
+          background: transparent;
+        }
+
+        /* Without showModal support the element stays hidden, which is the
+           correct closed state anyway. */
+        [part="backdrop"]:not([open]) {
+          display: none;
         }
 
         [part="sheet"] {
@@ -183,6 +206,7 @@ export class ShortcutsOverlay extends BaseElement {
         return ["commands", "heading", "hotkey", "open"];
     }
     hostEl;
+    backdropEl = null;
     focusRestore = new FocusRestore();
     wasOpen = false;
     commandsRaw = null;
@@ -333,6 +357,9 @@ export class ShortcutsOverlay extends BaseElement {
         }
         if (!this.open) {
             const wasOpen = this.wasOpen;
+            // Leave the top layer before the element is discarded, not after.
+            dismissModal(this.backdropEl);
+            this.backdropEl = null;
             this.hostEl.innerHTML = "";
             this.wasOpen = false;
             if (wasOpen) {
@@ -365,8 +392,8 @@ export class ShortcutsOverlay extends BaseElement {
         })
             .join("");
         this.hostEl.innerHTML = `
-      <div part="backdrop">
-        <div part="sheet" role="dialog" aria-modal="true" aria-label="${escapeHtml(this.heading)}">
+      <dialog part="backdrop" aria-label="Keyboard shortcuts">
+        <div part="sheet">
           <div part="header">
             <h2 part="title">${escapeHtml(this.heading)}</h2>
             <button type="button" part="close">Close</button>
@@ -375,8 +402,18 @@ export class ShortcutsOverlay extends BaseElement {
             ? `<ul part="groups" role="list">${sections}</ul>`
             : `<div part="empty">No keyboard shortcuts are defined.</div>`}
         </div>
-      </div>
+      </dialog>
     `;
+        this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
+        if (this.backdropEl) {
+            // A modal dialog closes itself on Escape and fires `cancel`; route it
+            // through the component's own dismissal so state stays in sync.
+            this.backdropEl.addEventListener("cancel", event => {
+                event.preventDefault();
+                this.dismiss();
+            });
+        }
+        promoteModal(this.backdropEl);
         if (justOpened) {
             this.hostEl.querySelector('[part="close"]')?.focus();
         }

package/dist/components/overlays/tooltip.js

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import { dismissPopover, promotePopover } from "../../foundations/overlay/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
@@ -40,7 +41,12 @@ const tooltipStyles = `
 
   /* Positioned by JS (foundations/overlay) as position: fixed, so it escapes
      ancestor overflow and flips/shifts to stay in the viewport. */
+  /* display is stated explicitly because the element carries
+     popover="manual": the UA sheet hides a popover that is not open, and an
+     author declaration outranks it. If showPopover() is unavailable or fails,
+     this still renders as before and only the top layer is lost. */
   [part="tooltip"] {
+    display: block;
     position: fixed;
     inset-block-start: 0;
     inset-inline-start: 0;
@@ -180,7 +186,7 @@ export class Tooltip extends BaseElement {
         <span part="trigger-host">
           <slot><button type="button" part="trigger">?</button></slot>
         </span>
-        <div id="${this.tooltipId}" part="tooltip" role="tooltip" hidden><span part="label"></span><slot name="content"></slot></div>
+        <div id="${this.tooltipId}" part="tooltip" popover="manual" role="tooltip" hidden><span part="label"></span><slot name="content"></slot></div>
       </span>
     `;
         this.triggerHostEl = this.shadowRoot.querySelector('[part="trigger-host"]');
@@ -232,6 +238,14 @@ export class Tooltip extends BaseElement {
             this.tooltipEl.setAttribute("data-theme", theme);
         }
         this.tooltipEl.hidden = !this.openValue;
+        // Top layer keeps it above the page even inside an ancestor with a
+        // transform/filter/contain, which position:fixed alone cannot escape.
+        if (this.openValue) {
+            promotePopover(this.tooltipEl);
+        }
+        else {
+            dismissPopover(this.tooltipEl);
+        }
         const trigger = this.resolveDescribedTrigger();
         if (trigger === this.fallbackTriggerEl) {
             this.fallbackTriggerEl.setAttribute("aria-label", this.triggerLabel);

package/dist/element-maps.d.ts

@@ -48,6 +48,7 @@ import type { DateField } from "./components/forms/date-field.js";
 import type { Dialog } from "./components/overlays/dialog.js";
 import type { DiffViewer } from "./patterns/diff/diff-viewer.js";
 import type { Divider } from "./components/layout/divider.js";
+import type { Grid } from "./components/layout/grid.js";
 import type { DonutChart } from "./patterns/insights/donut-chart.js";
 import type { DraggableList } from "./components/collections/draggable-list.js";
 import type { Drawer } from "./components/overlays/drawer.js";
@@ -124,7 +125,7 @@ import type { Slider } from "./components/forms/slider.js";
 import type { SpinButton } from "./components/forms/spin-button.js";
 import type { Spinner } from "./components/feedback/spinner.js";
 import type { SplitView } from "./components/layout/split-view.js";
-import type { StagePath } from "./components/feedback/stage-path.js";
+import type { Path } from "./components/feedback/path.js";
 import type { Switch } from "./components/forms/switch.js";
 import type { Table } from "./components/collections/table.js";
 import type { Tabs } from "./components/navigation/tabs.js";
@@ -189,6 +190,7 @@ declare global {
         "box-dialog": Dialog;
         "box-diff-viewer": DiffViewer;
         "box-divider": Divider;
+        "box-grid": Grid;
         "box-donut-chart": DonutChart;
         "box-draggable-list": DraggableList;
         "box-drawer": Drawer;
@@ -265,7 +267,7 @@ declare global {
         "box-spin-button": SpinButton;
         "box-spinner": Spinner;
         "box-split-view": SplitView;
-        "box-stage-path": StagePath;
+        "box-path": Path;
         "box-switch": Switch;
         "box-table": Table;
         "box-tabs": Tabs;
@@ -289,4 +291,4 @@ declare global {
     }
 }
 /** Every element tag the library registers, for host-side narrowing. */
-export type BoxElementTagName = "box-access-stats" | "box-accordion" | "box-activity-density" | "box-agent-chat" | "box-alert" | "box-annotation-inspector" | "box-annotation-thread" | "box-annotation-toolbar" | "box-app-shell" | "box-audit-log" | "box-avatar" | "box-badge" | "box-badgeable" | "box-bar-chart" | "box-breadcrumb" | "box-bulk-action-bar" | "box-button" | "box-button-group" | "box-calendar" | "box-card" | "box-carousel" | "box-category-selector" | "box-chart-panel" | "box-checkbox" | "box-checkbox-group" | "box-chip" | "box-collaborator-avatars" | "box-color-picker" | "box-combobox" | "box-command-palette" | "box-compare-view" | "box-contact-datalist-item" | "box-content-explorer" | "box-content-picker" | "box-content-sidebar" | "box-content-uploader" | "box-context-menu" | "box-datalist-item" | "box-date-field" | "box-dialog" | "box-diff-viewer" | "box-divider" | "box-donut-chart" | "box-draggable-list" | "box-drawer" | "box-drop-zone" | "box-dropdown" | "box-dual-listbox" | "box-due-badge" | "box-empty-state" | "box-error-mask" | "box-explorer-action-menu" | "box-explorer-breadcrumbs" | "box-explorer-items" | "box-explorer-list" | "box-explorer-table" | "box-explorer-toolbar" | "box-fieldset" | "box-file-request-builder" | "box-filter-bar" | "box-form-wizard" | "box-governance-panel" | "box-grid-view" | "box-guide-tooltip" | "box-help-text" | "box-icon-button" | "box-illustration" | "box-invite-collaborators-modal" | "box-item-details-panel" | "box-item-form" | "box-line-chart" | "box-lineage-graph" | "box-link-button" | "box-menu" | "box-menu-item" | "box-metadata-filter-builder" | "box-metadata-inspector" | "box-metric-card" | "box-multi-select" | "box-nav-sidebar" | "box-notification-bell" | "box-notification-inbox" | "box-nudge" | "box-number-input" | "box-pagination" | "box-permission-matrix" | "box-persona" | "box-pill-cloud" | "box-pill-selector-dropdown" | "box-popover" | "box-presence" | "box-preview-element" | "box-preview-header" | "box-progress-bar" | "box-progress-ring" | "box-progress-steps" | "box-provenance-strip" | "box-radio-group" | "box-range-slider" | "box-rating" | "box-review-queue-item" | "box-rich-text-input" | "box-run-trace" | "box-saved-view-picker" | "box-search-field" | "box-search-results-header" | "box-section" | "box-segmented-control" | "box-select" | "box-share-panel" | "box-shortcuts-overlay" | "box-sidebar-toggle-button" | "box-signature-ceremony" | "box-skeleton" | "box-slider" | "box-spin-button" | "box-spinner" | "box-split-view" | "box-stage-path" | "box-switch" | "box-table" | "box-tabs" | "box-tag-input" | "box-task-assignment-panel" | "box-text-area" | "box-text-field" | "box-thumbnail-card" | "box-time-field" | "box-timeline" | "box-toast" | "box-tooltip" | "box-tree" | "box-tree-grid" | "box-unified-share-modal" | "box-version-graph" | "box-version-list" | "box-wizard-summary" | "box-work-queue" | "box-workload-board";
+export type BoxElementTagName = "box-access-stats" | "box-accordion" | "box-activity-density" | "box-agent-chat" | "box-alert" | "box-annotation-inspector" | "box-annotation-thread" | "box-annotation-toolbar" | "box-app-shell" | "box-audit-log" | "box-avatar" | "box-badge" | "box-badgeable" | "box-bar-chart" | "box-breadcrumb" | "box-bulk-action-bar" | "box-button" | "box-button-group" | "box-calendar" | "box-card" | "box-carousel" | "box-category-selector" | "box-chart-panel" | "box-checkbox" | "box-checkbox-group" | "box-chip" | "box-collaborator-avatars" | "box-color-picker" | "box-combobox" | "box-command-palette" | "box-compare-view" | "box-contact-datalist-item" | "box-content-explorer" | "box-content-picker" | "box-content-sidebar" | "box-content-uploader" | "box-context-menu" | "box-datalist-item" | "box-date-field" | "box-dialog" | "box-diff-viewer" | "box-divider" | "box-grid" | "box-donut-chart" | "box-draggable-list" | "box-drawer" | "box-drop-zone" | "box-dropdown" | "box-dual-listbox" | "box-due-badge" | "box-empty-state" | "box-error-mask" | "box-explorer-action-menu" | "box-explorer-breadcrumbs" | "box-explorer-items" | "box-explorer-list" | "box-explorer-table" | "box-explorer-toolbar" | "box-fieldset" | "box-file-request-builder" | "box-filter-bar" | "box-form-wizard" | "box-governance-panel" | "box-grid-view" | "box-guide-tooltip" | "box-help-text" | "box-icon-button" | "box-illustration" | "box-invite-collaborators-modal" | "box-item-details-panel" | "box-item-form" | "box-line-chart" | "box-lineage-graph" | "box-link-button" | "box-menu" | "box-menu-item" | "box-metadata-filter-builder" | "box-metadata-inspector" | "box-metric-card" | "box-multi-select" | "box-nav-sidebar" | "box-notification-bell" | "box-notification-inbox" | "box-nudge" | "box-number-input" | "box-pagination" | "box-permission-matrix" | "box-persona" | "box-pill-cloud" | "box-pill-selector-dropdown" | "box-popover" | "box-presence" | "box-preview-element" | "box-preview-header" | "box-progress-bar" | "box-progress-ring" | "box-progress-steps" | "box-provenance-strip" | "box-radio-group" | "box-range-slider" | "box-rating" | "box-review-queue-item" | "box-rich-text-input" | "box-run-trace" | "box-saved-view-picker" | "box-search-field" | "box-search-results-header" | "box-section" | "box-segmented-control" | "box-select" | "box-share-panel" | "box-shortcuts-overlay" | "box-sidebar-toggle-button" | "box-signature-ceremony" | "box-skeleton" | "box-slider" | "box-spin-button" | "box-spinner" | "box-split-view" | "box-path" | "box-switch" | "box-table" | "box-tabs" | "box-tag-input" | "box-task-assignment-panel" | "box-text-area" | "box-text-field" | "box-thumbnail-card" | "box-time-field" | "box-timeline" | "box-toast" | "box-tooltip" | "box-tree" | "box-tree-grid" | "box-unified-share-modal" | "box-version-graph" | "box-version-list" | "box-wizard-summary" | "box-work-queue" | "box-workload-board";

package/dist/entries/grid.d.ts

@@ -0,0 +1 @@
+export * from "../components/layout/grid.js";

package/dist/entries/grid.js

@@ -0,0 +1 @@
+export * from "../components/layout/grid.js";

package/dist/entries/path.d.ts

@@ -0,0 +1 @@
+export * from "../components/feedback/path.js";

package/dist/entries/path.js

@@ -0,0 +1 @@
+export * from "../components/feedback/path.js";

package/dist/foundations/layout/grid.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Adobe Spectrum's responsive grid, as a foundation.
+ *
+ * Two surfaces build on this: `box-grid`, which lays out slotted content, and
+ * `box-skeleton`'s grid variant, which fills the same regions with shimmer
+ * bars. They must agree on what a column is worth and how wide a gutter is at
+ * a given viewport, so the model lives here rather than in either of them.
+ */
+/**
+ * Columns in the grid.
+ *
+ * Twelve divides by 2, 3, 4 and 6, so halves, thirds, quarters and
+ * sidebar-plus-content all land on whole columns.
+ */
+export declare const BOE_GRID_COLUMNS = 12;
+/**
+ * Spectrum's breakpoints and their gutters.
+ *
+ * Breakpoints are min-widths, so a viewport between two of them inherits the
+ * smaller one's dimensions. Gutters are fixed values per breakpoint rather
+ * than a proportion of the grid — that is Spectrum's rule, and it is why the
+ * gutter cannot simply be a percentage.
+ */
+export declare const BOE_GRID_BREAKPOINTS: readonly {
+    minWidth: number;
+    gutter: number;
+}[];
+/** The custom property every grid surface reads its gutter from. */
+export declare const BOE_GRID_GUTTER_PROPERTY = "--boe-grid-gutter";
+/**
+ * The gutter scale as CSS, scoped to a selector.
+ *
+ * Emitted rather than hand-written in each component so the two cannot drift,
+ * and so adding a breakpoint is one edit. A consumer overriding the property
+ * replaces the whole scale in one declaration.
+ */
+export declare const boeGridGutterStyles: (selector?: string) => string;
+/**
+ * One region of the grid: a block spanning some columns and rows, optionally
+ * pushed right by an offset. Spectrum calls these layout regions.
+ */
+export interface BoeGridPlacement {
+    /** Columns to span. Clamped to what is left after `offset`. */
+    span?: number;
+    /** Rows to span. Clamped to the grid's `rows`, so a region cannot exceed it. */
+    rowSpan?: number;
+    /** Empty columns before this region. Clamped to leave room for one column. */
+    offset?: number;
+}
+/** A resolved region: every field present, every value in range. */
+export interface ResolvedBoeGridPlacement {
+    span: number;
+    rowSpan: number;
+    offset: number;
+}
+/** Attribute payloads are author input — validate every record. */
+export declare const isBoeGridPlacementRecord: (value: unknown) => value is BoeGridPlacement;
+/**
+ * Fit a region to the grid.
+ *
+ * Every value is clamped rather than rejected. A layout that renders slightly
+ * wrong is recoverable; one that vanishes because a number was out of range is
+ * not, and the caller usually cannot tell which region was dropped. The clamps
+ * are what confine a region to the totals the author declared: a span of 9 in a
+ * three-column grid becomes 3, and a `rowSpan` of 5 in a three-row grid
+ * becomes 3.
+ */
+export declare const resolveBoeGridPlacement: (item: BoeGridPlacement, columns: number, rows: number) => ResolvedBoeGridPlacement;
+/** Parse a positive integer attribute, falling back when it is absent or junk. */
+export declare const resolveGridCount: (raw: string | null, fallback: number) => number;

package/dist/foundations/layout/grid.js

@@ -0,0 +1,84 @@
+/**
+ * Adobe Spectrum's responsive grid, as a foundation.
+ *
+ * Two surfaces build on this: `box-grid`, which lays out slotted content, and
+ * `box-skeleton`'s grid variant, which fills the same regions with shimmer
+ * bars. They must agree on what a column is worth and how wide a gutter is at
+ * a given viewport, so the model lives here rather than in either of them.
+ */
+/**
+ * Columns in the grid.
+ *
+ * Twelve divides by 2, 3, 4 and 6, so halves, thirds, quarters and
+ * sidebar-plus-content all land on whole columns.
+ */
+export const BOE_GRID_COLUMNS = 12;
+/**
+ * Spectrum's breakpoints and their gutters.
+ *
+ * Breakpoints are min-widths, so a viewport between two of them inherits the
+ * smaller one's dimensions. Gutters are fixed values per breakpoint rather
+ * than a proportion of the grid — that is Spectrum's rule, and it is why the
+ * gutter cannot simply be a percentage.
+ */
+export const BOE_GRID_BREAKPOINTS = [
+    { minWidth: 0, gutter: 16 },
+    { minWidth: 768, gutter: 24 },
+    { minWidth: 1280, gutter: 32 },
+    { minWidth: 1768, gutter: 40 },
+    { minWidth: 2160, gutter: 48 },
+];
+/** The custom property every grid surface reads its gutter from. */
+export const BOE_GRID_GUTTER_PROPERTY = "--boe-grid-gutter";
+/**
+ * The gutter scale as CSS, scoped to a selector.
+ *
+ * Emitted rather than hand-written in each component so the two cannot drift,
+ * and so adding a breakpoint is one edit. A consumer overriding the property
+ * replaces the whole scale in one declaration.
+ */
+export const boeGridGutterStyles = (selector = ":host") => BOE_GRID_BREAKPOINTS.map(({ minWidth, gutter }) => {
+    const declaration = `${selector} {\n    ${BOE_GRID_GUTTER_PROPERTY}: ${gutter}px;\n  }`;
+    return minWidth === 0
+        ? `  ${declaration}`
+        : `  @media (min-width: ${minWidth}px) {\n  ${declaration}\n  }`;
+}).join("\n\n");
+/** Attribute payloads are author input — validate every record. */
+export const isBoeGridPlacementRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const item = value;
+    // Absent is fine — each field has a default. Present-but-not-a-number is not:
+    // it means the host built the payload wrong, and silently substituting a
+    // default would hide that.
+    return ["span", "rowSpan", "offset"].every(key => {
+        const raw = item[key];
+        return raw === undefined || (typeof raw === "number" && Number.isFinite(raw));
+    });
+};
+const clamp = (value, min, max) => Math.min(Math.max(Math.trunc(value), min), max);
+/**
+ * Fit a region to the grid.
+ *
+ * Every value is clamped rather than rejected. A layout that renders slightly
+ * wrong is recoverable; one that vanishes because a number was out of range is
+ * not, and the caller usually cannot tell which region was dropped. The clamps
+ * are what confine a region to the totals the author declared: a span of 9 in a
+ * three-column grid becomes 3, and a `rowSpan` of 5 in a three-row grid
+ * becomes 3.
+ */
+export const resolveBoeGridPlacement = (item, columns, rows) => {
+    // Leave at least one column for the region itself.
+    const offset = clamp(item.offset ?? 0, 0, Math.max(columns - 1, 0));
+    return {
+        offset,
+        span: clamp(item.span ?? 1, 1, Math.max(columns - offset, 1)),
+        rowSpan: clamp(item.rowSpan ?? 1, 1, Math.max(rows, 1)),
+    };
+};
+/** Parse a positive integer attribute, falling back when it is absent or junk. */
+export const resolveGridCount = (raw, fallback) => {
+    const parsed = Number.parseInt(raw ?? "", 10);
+    return Number.isFinite(parsed) ? Math.max(parsed, 1) : fallback;
+};

package/dist/foundations/layout/index.d.ts

@@ -0,0 +1 @@
+export * from "./grid.js";

package/dist/foundations/layout/index.js

@@ -0,0 +1,3 @@
+// Adobe Spectrum's responsive grid: columns, breakpoint gutters, and the
+// clamping that confines a region to the totals its host declared.
+export * from "./grid.js";

package/dist/foundations/overlay/index.d.ts

@@ -1,2 +1,3 @@
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./positioning.js";
+export { dismissModal, dismissPopover, promoteModal, promotePopover, } from "./top-layer.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, Rect, Size, } from "./positioning.js";

package/dist/foundations/overlay/index.js

@@ -1 +1,2 @@
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./positioning.js";
+export { dismissModal, dismissPopover, promoteModal, promotePopover, } from "./top-layer.js";

package/dist/foundations/overlay/top-layer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Top-layer promotion for overlays.
+ *
+ * An overlay has to paint above the page, and `position: fixed` alone cannot
+ * promise that: an ancestor with a `transform`, `filter`, `perspective`,
+ * `contain`, or `will-change` becomes the containing block, and the overlay is
+ * positioned — and clipped — against that ancestor instead of the viewport.
+ *
+ * The old answer was to move the overlay's host node to `document.body`.
+ * `box-drawer` did exactly that and it broke every framework that owns the
+ * node: React unmounting a tree containing an open drawer threw
+ * `NotFoundError`, because the node it tried to remove was no longer its child.
+ *
+ * The top layer solves the same problem without touching the DOM tree. It is a
+ * rendering concern, so the host stays exactly where its framework put it.
+ *
+ * Two primitives, and the difference is modality rather than taste:
+ *
+ * - `showModal()` on a `<dialog>` — for overlays that own the screen while they
+ *   are up, with a scrim, a focus trap, and the rest of the page inert.
+ * - `showPopover()` on a `[popover]` element — for anchored, non-modal surfaces
+ *   (tooltips, menus, popovers) that must **not** trap focus or block the page.
+ *
+ * Using the modal primitive for an anchored surface would be a behaviour
+ * regression, not just an overreach, which is why these are separate calls.
+ *
+ * Every entry point is guarded rather than assumed. jsdom implements neither
+ * API, so the unit suite exercises everything around the promotion and the
+ * promotion itself is verified in a browser; and a detached or hidden element
+ * throws rather than opening, which is a normal state during teardown.
+ */
+/** An element that may be promotable as a modal dialog. */
+type MaybeDialog = HTMLElement & {
+    showModal?: () => void;
+    close?: () => void;
+    open?: boolean;
+};
+/** An element that may be promotable as a popover. */
+type MaybePopover = HTMLElement & {
+    showPopover?: () => void;
+    hidePopover?: () => void;
+};
+/**
+ * Promote a `<dialog>` into the top layer as a modal.
+ *
+ * Returns whether the promotion happened, so a caller can tell "not supported
+ * here" from "already open" if it needs to — most do not.
+ */
+export declare const promoteModal: (element: MaybeDialog | null) => boolean;
+/** Close a modal `<dialog>`, leaving the top layer. */
+export declare const dismissModal: (element: MaybeDialog | null) => void;
+/**
+ * Promote an element into the top layer as a **non-modal** popover.
+ *
+ * Callers are expected to set `popover="manual"` on the element: `auto`
+ * popovers light-dismiss and close each other, which fights components that
+ * already own their own dismissal rules.
+ */
+export declare const promotePopover: (element: MaybePopover | null) => boolean;
+/** Hide a popover, leaving the top layer. */
+export declare const dismissPopover: (element: MaybePopover | null) => void;
+export {};

package/dist/foundations/overlay/top-layer.js

@@ -0,0 +1,95 @@
+/**
+ * Top-layer promotion for overlays.
+ *
+ * An overlay has to paint above the page, and `position: fixed` alone cannot
+ * promise that: an ancestor with a `transform`, `filter`, `perspective`,
+ * `contain`, or `will-change` becomes the containing block, and the overlay is
+ * positioned — and clipped — against that ancestor instead of the viewport.
+ *
+ * The old answer was to move the overlay's host node to `document.body`.
+ * `box-drawer` did exactly that and it broke every framework that owns the
+ * node: React unmounting a tree containing an open drawer threw
+ * `NotFoundError`, because the node it tried to remove was no longer its child.
+ *
+ * The top layer solves the same problem without touching the DOM tree. It is a
+ * rendering concern, so the host stays exactly where its framework put it.
+ *
+ * Two primitives, and the difference is modality rather than taste:
+ *
+ * - `showModal()` on a `<dialog>` — for overlays that own the screen while they
+ *   are up, with a scrim, a focus trap, and the rest of the page inert.
+ * - `showPopover()` on a `[popover]` element — for anchored, non-modal surfaces
+ *   (tooltips, menus, popovers) that must **not** trap focus or block the page.
+ *
+ * Using the modal primitive for an anchored surface would be a behaviour
+ * regression, not just an overreach, which is why these are separate calls.
+ *
+ * Every entry point is guarded rather than assumed. jsdom implements neither
+ * API, so the unit suite exercises everything around the promotion and the
+ * promotion itself is verified in a browser; and a detached or hidden element
+ * throws rather than opening, which is a normal state during teardown.
+ */
+/**
+ * Promote a `<dialog>` into the top layer as a modal.
+ *
+ * Returns whether the promotion happened, so a caller can tell "not supported
+ * here" from "already open" if it needs to — most do not.
+ */
+export const promoteModal = (element) => {
+    if (!element || typeof element.showModal !== "function" || element.open) {
+        return false;
+    }
+    try {
+        element.showModal();
+        return true;
+    }
+    catch {
+        // Detached, hidden, or already promoted by another path. The overlay still
+        // renders and behaves; it simply does not get the top layer.
+        return false;
+    }
+};
+/** Close a modal `<dialog>`, leaving the top layer. */
+export const dismissModal = (element) => {
+    if (!element || typeof element.close !== "function" || !element.open) {
+        return;
+    }
+    try {
+        element.close();
+    }
+    catch {
+        // Already closed or detached; nothing to undo.
+    }
+};
+/**
+ * Promote an element into the top layer as a **non-modal** popover.
+ *
+ * Callers are expected to set `popover="manual"` on the element: `auto`
+ * popovers light-dismiss and close each other, which fights components that
+ * already own their own dismissal rules.
+ */
+export const promotePopover = (element) => {
+    if (!element || typeof element.showPopover !== "function") {
+        return false;
+    }
+    try {
+        element.showPopover();
+        return true;
+    }
+    catch {
+        // Throws if already showing, or if the element is not connected.
+        return false;
+    }
+};
+/** Hide a popover, leaving the top layer. */
+export const dismissPopover = (element) => {
+    if (!element || typeof element.hidePopover !== "function") {
+        return;
+    }
+    try {
+        element.hidePopover();
+    }
+    catch {
+        // Not currently showing; nothing to undo.
+    }
+};

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { ResolvedTheme, ThemeChangeDetail, ThemeController, ThemeController
 export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_PROFILE_STORAGE_KEY, applyDesignProfile, boxDefaultDesignProfile, compactNeutralDesignProfile, createDesignProfileController, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerBuiltInDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./foundations/profiles/index.js";
 export type { ApplyDesignProfileOptions, DesignProfileChangeDetail, DesignProfileController, DesignProfileControllerOptions, DesignProfileDefinition, DesignProfileDensity, DesignProfileElevation, DesignProfileMotion, DesignProfileRadius, DesignProfileSpacing, DesignProfileTypography, } from "./foundations/profiles/index.js";
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
+export * from "./foundations/layout/index.js";
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, } from "./foundations/overlay/index.js";
 export * from "./components/actions/button.js";
@@ -42,10 +43,11 @@ export * from "./components/feedback/progress-ring.js";
 export * from "./components/feedback/progress-steps.js";
 export * from "./components/feedback/skeleton.js";
 export * from "./components/feedback/spinner.js";
-export * from "./components/feedback/stage-path.js";
+export * from "./components/feedback/path.js";
 export * from "./components/feedback/toast.js";
 export * from "./components/files/drop-zone.js";
 export * from "./components/identity/avatar.js";
+export * from "./components/identity/contact-datalist-item.js";
 export * from "./components/identity/persona.js";
 export * from "./components/navigation/accordion.js";
 export * from "./components/navigation/breadcrumb.js";
@@ -80,6 +82,7 @@ export * from "./components/forms/text-area.js";
 export * from "./components/forms/text-field.js";
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";
+export * from "./components/layout/grid.js";
 export * from "./components/layout/nav-sidebar.js";
 export * from "./components/layout/section.js";
 export * from "./components/layout/sidebar-toggle-button.js";

package/dist/index.js

@@ -5,6 +5,8 @@ export { DESIGN_SYSTEM_CHANGE_EVENT, SEMANTIC_TOKEN_ALIASES, applyDesignTokens,
 export { DARK_MODE_MEDIA_QUERY, DEFAULT_THEME_STORAGE_KEY, THEME_CHANGE_EVENT, createThemeController, createThemeInitializationScript, } from "./foundations/theming/index.js";
 export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_PROFILE_STORAGE_KEY, applyDesignProfile, boxDefaultDesignProfile, compactNeutralDesignProfile, createDesignProfileController, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerBuiltInDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./foundations/profiles/index.js";
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
+// Foundations: Adobe Spectrum's responsive grid (shared by box-grid and box-skeleton)
+export * from "./foundations/layout/index.js";
 // Foundations: viewport-aware overlay positioning (for building custom overlays)
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 // Components: actions
@@ -42,12 +44,13 @@ export * from "./components/feedback/progress-ring.js";
 export * from "./components/feedback/progress-steps.js";
 export * from "./components/feedback/skeleton.js";
 export * from "./components/feedback/spinner.js";
-export * from "./components/feedback/stage-path.js";
+export * from "./components/feedback/path.js";
 export * from "./components/feedback/toast.js";
 // Components: files
 export * from "./components/files/drop-zone.js";
 // Components: identity
 export * from "./components/identity/avatar.js";
+export * from "./components/identity/contact-datalist-item.js";
 export * from "./components/identity/persona.js";
 // Components: navigation
 export * from "./components/navigation/accordion.js";
@@ -86,6 +89,7 @@ export * from "./components/forms/text-field.js";
 // Components: layout
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";
+export * from "./components/layout/grid.js";
 export * from "./components/layout/nav-sidebar.js";
 export * from "./components/layout/section.js";
 export * from "./components/layout/sidebar-toggle-button.js";

package/dist/patterns/audit/audit-log.js

@@ -221,7 +221,6 @@ const elementStyles = `
           gap: 0.25rem;
           padding: 0.5rem 0.65rem;
           border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 55%, transparent);
-          border-left: 3px solid var(--audit-tone, transparent);
         }
 
         [part="event-topline"] {

package/dist/patterns/lineage/lineage-graph.d.ts

@@ -1,4 +1,5 @@
 import type { LineageNode } from "./types.js";
+import type { GraphArrows } from "../versions/graph-arrows.js";
 import { BaseElement } from "../../core/index.js";
 /**
  * Provenance DAG for clause lineage (opportunity 2): source clause →
@@ -13,6 +14,12 @@ import { BaseElement } from "../../core/index.js";
 export declare class LineageGraph extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
+    /**
+     * Which ends of each edge carry an arrowhead. Defaults to `end`, the head on
+     * the derived node, because the layout builds edges source → derived.
+     */
+    get arrows(): GraphArrows;
+    set arrows(value: GraphArrows);
     private nodesValue;
     private rovingId;
     private hostEl;