@unofficialbox/box-open-elements 0.2.1 → 0.3.0

package/dist/components/overlays/context-menu.js

@@ -0,0 +1,260 @@
+import { BaseElement } from "../../core/index.js";
+import { FocusRestore, nextRovingIndex } from "../../foundations/a11y/index.js";
+import { boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
+import { resolvePosition } from "../../foundations/overlay/index.js";
+const DEFAULT_TAG_NAME = "box-context-menu";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+const contextMenuStyles = `
+  :host {
+    display: inline-block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="target"] {
+    display: contents;
+  }
+
+  [part="surface"] {
+    position: fixed;
+    z-index: 40;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    min-width: 180px;
+    max-width: min(320px, 90vw);
+    margin: 0;
+    padding: ${boeSpace[1]};
+    border: ${boeOverlay.border};
+    border-radius: ${boeOverlay.radius};
+    background: var(--boe-token-surface-surface, #ffffff);
+    box-shadow: ${boeOverlay.shadow};
+    display: grid;
+    gap: 1px;
+  }
+
+  [part="surface"][hidden] {
+    display: none;
+  }
+
+  [part="item"] {
+    appearance: none;
+    border: none;
+    background: none;
+    font: inherit;
+    text-align: start;
+    width: 100%;
+    min-height: ${boeOverlay.itemMinHeight};
+    padding: ${boeSpace[1]} ${boeSpace[3]};
+    border-radius: ${boeOverlay.itemRadius};
+    color: var(--boe-token-text-text, #222222);
+    cursor: pointer;
+  }
+
+  [part="item"]:hover:not(:disabled),
+  [part="item"]:focus-visible {
+    background: var(--boe-token-surface-surface-secondary, #f4f4f4);
+    outline: none;
+  }
+
+  [part="item"]:focus-visible {
+    box-shadow: inset 0 0 0 2px var(--boe-token-surface-surface-brand, #0061d5);
+  }
+
+  [part="item"]:disabled {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  [part="divider"] {
+    height: 1px;
+    margin: ${boeSpace[1]} 0;
+    background: var(--boe-token-stroke-stroke, #e8e8e8);
+    border-radius: ${boeRadius.size};
+  }
+`;
+/**
+ * Right-click context menu — box-ui-elements `ContextMenu`. The default slot is
+ * the target area; right-clicking (or Shift+F10 / the ContextMenu key) opens a
+ * menu at the pointer, positioned with `foundations/overlay` so it stays in the
+ * viewport. Full keyboard menu: arrows, Home/End, Enter/Space, Escape.
+ */
+export class BoxContextMenuElement extends BaseElement {
+    static get observedAttributes() {
+        return ["items", "disabled"];
+    }
+    openValue = false;
+    targetEl;
+    surfaceEl;
+    focusRestore = new FocusRestore();
+    documentBound = false;
+    onOutside = (event) => {
+        if (!this.openValue)
+            return;
+        const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+        if (!path.some(node => node === this.surfaceEl))
+            this.close();
+    };
+    onReposition = () => {
+        if (this.openValue)
+            this.close();
+    };
+    get items() {
+        const raw = this.getAttribute("items");
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set items(value) {
+        this.setAttribute("items", JSON.stringify(value));
+    }
+    get disabled() {
+        return this.hasAttribute("disabled");
+    }
+    set disabled(value) {
+        this.toggleAttribute("disabled", Boolean(value));
+    }
+    get open() {
+        return this.openValue;
+    }
+    disconnectedCallback() {
+        this.unbindDocument();
+    }
+    renderTemplate() {
+        if (!this.shadowRoot)
+            return;
+        this.shadowRoot.innerHTML = `
+      <style>${contextMenuStyles}</style>
+      <div part="target"><slot></slot></div>
+      <div part="surface" role="menu" hidden></div>
+    `;
+        this.targetEl = this.shadowRoot.querySelector('[part="target"]');
+        this.surfaceEl = this.shadowRoot.querySelector('[part="surface"]');
+    }
+    setupListeners() {
+        this.addEventListener("contextmenu", event => {
+            if (this.disabled || this.items.length === 0)
+                return;
+            event.preventDefault();
+            this.openAt(event.clientX, event.clientY);
+        });
+        // Keyboard opener: Shift+F10 or the ContextMenu key on the focused target.
+        this.addEventListener("keydown", event => {
+            if (this.disabled)
+                return;
+            const isOpener = event.key === "ContextMenu" || (event.shiftKey && event.key === "F10");
+            if (isOpener && this.items.length) {
+                event.preventDefault();
+                const rect = this.getBoundingClientRect();
+                this.openAt(rect.left, rect.bottom);
+            }
+        });
+        this.surfaceEl.addEventListener("click", event => {
+            const item = event.target.closest('[part="item"]');
+            if (!item || item.disabled)
+                return;
+            this.selectItem(item.dataset.id ?? "");
+        });
+        this.surfaceEl.addEventListener("keydown", event => this.onMenuKeydown(event));
+    }
+    enabledItems() {
+        return Array.from(this.surfaceEl.querySelectorAll('[part="item"]:not(:disabled)'));
+    }
+    onMenuKeydown(event) {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            this.close();
+            return;
+        }
+        const items = this.enabledItems();
+        if (items.length === 0)
+            return;
+        const current = items.indexOf(event.target);
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            event.target.click();
+            return;
+        }
+        const next = nextRovingIndex(event.key, Math.max(current, 0), items.length, { orientation: "vertical" });
+        if (next !== null && next !== current) {
+            event.preventDefault();
+            items[next].focus();
+        }
+    }
+    openAt(clientX, clientY) {
+        this.renderItems();
+        this.surfaceEl.hidden = false;
+        const { width, height } = this.surfaceEl.getBoundingClientRect();
+        const { x, y } = resolvePosition({ top: clientY, left: clientX, width: 0, height: 0 }, { width, height }, { width: window.innerWidth, height: window.innerHeight }, { placement: { side: "bottom", align: "start" }, offset: 0 });
+        this.surfaceEl.style.left = `${Math.round(x)}px`;
+        this.surfaceEl.style.top = `${Math.round(y)}px`;
+        this.openValue = true;
+        this.bindDocument();
+        this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: true } }));
+        this.focusRestore.capture(document.activeElement);
+        queueMicrotask(() => this.enabledItems()[0]?.focus());
+    }
+    close() {
+        if (!this.openValue)
+            return;
+        this.openValue = false;
+        this.surfaceEl.hidden = true;
+        this.unbindDocument();
+        this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: false } }));
+        this.focusRestore.restore();
+    }
+    selectItem(id) {
+        const item = this.items.find(entry => entry.id === id);
+        if (!item || item.disabled)
+            return;
+        this.dispatchEvent(new CustomEvent("item-selected", { bubbles: true, composed: true, detail: item }));
+        this.close();
+    }
+    renderItems() {
+        this.surfaceEl.innerHTML = this.items
+            .map(item => {
+            const divider = item.separator ? `<div part="divider" role="separator"></div>` : "";
+            const disabled = item.disabled ? " disabled" : "";
+            return `${divider}<button type="button" part="item" role="menuitem" data-id="${escapeHtml(item.id)}"${disabled}>${escapeHtml(item.label)}</button>`;
+        })
+            .join("");
+    }
+    bindDocument() {
+        if (this.documentBound)
+            return;
+        document.addEventListener("pointerdown", this.onOutside, true);
+        document.addEventListener("scroll", this.onReposition, true);
+        window.addEventListener("resize", this.onReposition);
+        this.documentBound = true;
+    }
+    unbindDocument() {
+        if (!this.documentBound)
+            return;
+        document.removeEventListener("pointerdown", this.onOutside, true);
+        document.removeEventListener("scroll", this.onReposition, true);
+        window.removeEventListener("resize", this.onReposition);
+        this.documentBound = false;
+    }
+    update() {
+        // The menu content is rendered on open; nothing to sync while closed.
+        if (this.openValue)
+            this.renderItems();
+    }
+}
+export const defineBoxContextMenuElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxContextMenuElement);
+    return BoxContextMenuElement;
+};

package/dist/components/overlays/dialog.d.ts

@@ -3,6 +3,8 @@ export declare class BoxDialogElement extends BaseElement {
     static get observedAttributes(): string[];
     private openValue;
     private wasOpen;
+    private scrollLocked;
+    private previousBodyOverflow;
     private hostEl;
     private titleEl;
     private descriptionEl;
@@ -16,6 +18,12 @@ export declare class BoxDialogElement extends BaseElement {
     set description(value: string);
     get confirmLabel(): string;
     set confirmLabel(value: string);
+    /** Modal size — box-ui-elements Modal sizes. Default `medium`. */
+    get size(): "small" | "medium" | "large" | "fullscreen";
+    set size(value: "small" | "medium" | "large" | "fullscreen");
+    /** Lock/unlock background page scroll while the modal is open. */
+    private setScrollLock;
+    disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     show(): void;
     close(): void;

package/dist/components/overlays/dialog.js

@@ -31,6 +31,16 @@ const dialogStyles = `
     color: var(--boe-token-text-text, #222222);
   }
 
+  /* Size options — box-ui-elements Modal sizes. Default (medium) is the base. */
+  [part="dialog"][data-size="small"] { width: min(380px, calc(100vw - 3rem)); }
+  [part="dialog"][data-size="large"] { width: min(760px, calc(100vw - 3rem)); }
+  [part="dialog"][data-size="fullscreen"] {
+    width: calc(100vw - 2rem);
+    height: calc(100vh - 2rem);
+    max-width: none;
+    border-radius: ${boeRadius.large};
+  }
+
   [part="header"] h2 {
     margin: 0;
     font: inherit;
@@ -96,10 +106,12 @@ const dialogStyles = `
 `;
 export class BoxDialogElement extends BaseElement {
     static get observedAttributes() {
-        return ["confirm-label", "description", "heading", "open"];
+        return ["confirm-label", "description", "heading", "open", "size"];
     }
     openValue = false;
     wasOpen = false;
+    scrollLocked = false;
+    previousBodyOverflow = "";
     hostEl;
     titleEl = null;
     descriptionEl = null;
@@ -140,6 +152,31 @@ export class BoxDialogElement extends BaseElement {
     set confirmLabel(value) {
         this.setAttribute("confirm-label", value);
     }
+    /** Modal size — box-ui-elements Modal sizes. Default `medium`. */
+    get size() {
+        const size = this.getAttribute("size");
+        return size === "small" || size === "large" || size === "fullscreen" ? size : "medium";
+    }
+    set size(value) {
+        this.setAttribute("size", value);
+    }
+    /** Lock/unlock background page scroll while the modal is open. */
+    setScrollLock(locked) {
+        if (locked === this.scrollLocked) {
+            return;
+        }
+        this.scrollLocked = locked;
+        if (locked) {
+            this.previousBodyOverflow = document.body.style.overflow;
+            document.body.style.overflow = "hidden";
+        }
+        else {
+            document.body.style.overflow = this.previousBodyOverflow;
+        }
+    }
+    disconnectedCallback() {
+        this.setScrollLock(false);
+    }
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "open") {
             this.openValue = this.hasAttribute("open");
@@ -203,6 +240,7 @@ export class BoxDialogElement extends BaseElement {
         }
         if (!this.openValue) {
             const wasOpen = this.wasOpen;
+            this.setScrollLock(false);
             this.hostEl.innerHTML = "";
             this.titleEl = null;
             this.descriptionEl = null;
@@ -218,11 +256,12 @@ export class BoxDialogElement extends BaseElement {
         if (justOpened) {
             this.focusRestore.capture();
         }
+        this.setScrollLock(true);
         if (!this.hostEl.querySelector('[part="dialog"]')) {
             this.hostEl.innerHTML = `
         <style>${dialogStyles}</style>
         <div part="backdrop">
-          <section part="dialog" role="dialog" aria-modal="true" tabindex="-1" aria-labelledby="dialog-title">
+          <section part="dialog" role="dialog" aria-modal="true" tabindex="-1" aria-labelledby="dialog-title" data-size="${this.size}">
             <header part="header">
               <h2 id="dialog-title"></h2>
             </header>
@@ -239,6 +278,10 @@ export class BoxDialogElement extends BaseElement {
         this.titleEl = this.hostEl.querySelector("#dialog-title");
         this.descriptionEl = this.hostEl.querySelector('[part="description"]');
         this.confirmEl = this.hostEl.querySelector('[part="confirm"]');
+        const dialogEl = this.hostEl.querySelector('[part="dialog"]');
+        if (dialogEl) {
+            dialogEl.dataset.size = this.size;
+        }
         if (this.titleEl) {
             this.titleEl.textContent = this.heading;
         }

package/dist/components/overlays/popover.d.ts

@@ -1,5 +1,9 @@
 import { BaseElement } from "../../core/index.js";
-export type PopoverPlacement = "bottom" | "top" | "start" | "end";
+/**
+ * Any side (`top`/`bottom`/`left`/`right`) with optional `-start`/`-center`/`-end`
+ * alignment, plus the legacy names (`start` = left, `end` = right).
+ */
+export type PopoverPlacement = "top" | "bottom" | "left" | "right" | "start" | "end" | "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "left-start" | "left-center" | "left-end" | "right-start" | "right-center" | "right-end";
 export declare class BoxPopoverElement extends BaseElement {
     static get observedAttributes(): string[];
     private openValue;
@@ -7,6 +11,7 @@ export declare class BoxPopoverElement extends BaseElement {
     private documentListenersBound;
     private triggerEl;
     private surfaceEl;
+    private positionCleanup;
     private readonly focusRestore;
     private readonly onDocumentKeydown;
     private readonly onOutsidePointer;
@@ -31,5 +36,8 @@ export declare class BoxPopoverElement extends BaseElement {
     protected renderTemplate(): void;
     protected setupListeners(): void;
     protected update(): void;
+    /** Anchor the surface to the trigger and keep it positioned while open. */
+    private startPositioning;
+    private stopPositioning;
 }
 export declare const defineBoxPopoverElement: (tagName?: string) => typeof BoxPopoverElement;

package/dist/components/overlays/popover.js

@@ -1,15 +1,17 @@
 import { BaseElement } from "../../core/index.js";
 import { FocusRestore, getTabbableElements } from "../../foundations/a11y/index.js";
-import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
+import { boeControl, boeOverlay, boeRadius } from "../../foundations/geometry/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
 const DEFAULT_TAG_NAME = "box-popover";
+/** The attribute value if it names a valid placement, else `"bottom"`. */
 const resolvePlacement = (value) => {
-    if (value === "top" || value === "start" || value === "end" || value === "bottom") {
-        return value;
-    }
+    if (value && parsePlacement(value))
+        return value.trim().toLowerCase();
     return "bottom";
 };
+const OVERLAY_OFFSET = 4;
 const popoverStyles = `
   :host {
     display: inline-block;
@@ -46,10 +48,13 @@ const popoverStyles = `
 
   ${boeNeutralInteractiveStyles('[part="trigger"]')}
 
+  /* Positioned by JS (foundations/overlay) as position: fixed in viewport
+     coordinates — so it escapes ancestor overflow and flips/shifts to stay in
+     view, the job a portal does in box-ui-elements. */
   [part="surface"] {
-    position: absolute;
+    position: fixed;
     z-index: 30;
-    inset-block-start: calc(100% + ${boeSpace[1]});
+    inset-block-start: 0;
     inset-inline-start: 0;
     width: min(360px, calc(100vw - 5rem));
     min-width: 200px;
@@ -62,22 +67,6 @@ const popoverStyles = `
     line-height: 1.5;
   }
 
-  :host([placement="top"]) [part="surface"] {
-    inset-block-start: auto;
-    inset-block-end: calc(100% + ${boeSpace[1]});
-  }
-
-  :host([placement="start"]) [part="surface"] {
-    inset-block-start: 0;
-    inset-inline-start: auto;
-    inset-inline-end: calc(100% + ${boeSpace[1]});
-  }
-
-  :host([placement="end"]) [part="surface"] {
-    inset-block-start: 0;
-    inset-inline-start: calc(100% + ${boeSpace[1]});
-  }
-
   [part="surface"][hidden] {
     display: none;
   }
@@ -91,6 +80,7 @@ export class BoxPopoverElement extends BaseElement {
     documentListenersBound = false;
     triggerEl;
     surfaceEl;
+    positionCleanup = null;
     focusRestore = new FocusRestore();
     onDocumentKeydown = (event) => {
         if (!this.openValue || event.key !== "Escape") {
@@ -164,6 +154,7 @@ export class BoxPopoverElement extends BaseElement {
     }
     disconnectedCallback() {
         this.unbindDocumentListeners();
+        this.stopPositioning();
     }
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "open") {
@@ -297,6 +288,12 @@ export class BoxPopoverElement extends BaseElement {
         const justClosed = !this.openValue && this.wasOpen;
         this.surfaceEl.hidden = !this.openValue;
         this.syncDocumentListeners();
+        if (this.openValue) {
+            this.startPositioning();
+        }
+        else {
+            this.stopPositioning();
+        }
         if (justOpened) {
             this.focusRestore.capture(this.triggerEl);
             queueMicrotask(() => this.focusSurface());
@@ -306,6 +303,24 @@ export class BoxPopoverElement extends BaseElement {
         }
         this.wasOpen = this.openValue;
     }
+    /** Anchor the surface to the trigger and keep it positioned while open. */
+    startPositioning() {
+        if (this.positionCleanup) {
+            return;
+        }
+        const placement = parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "start" };
+        this.positionCleanup = trackAnchor(this.triggerEl, this.surfaceEl, {
+            placement,
+            offset: OVERLAY_OFFSET,
+        });
+    }
+    stopPositioning() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+        this.surfaceEl.style.left = "";
+        this.surfaceEl.style.top = "";
+        this.surfaceEl.style.margin = "";
+    }
 }
 export const defineBoxPopoverElement = (tagName = DEFAULT_TAG_NAME) => {
     const existingElement = customElements.get(tagName);

package/dist/core/form-associated.d.ts

@@ -29,10 +29,26 @@ export declare const rangeFromFormValue: (value: FormValue, name: string, fallba
 export declare const boeFormFieldErrorStyles = "\n  :host([invalid]) [part=\"input\"],\n  :host([invalid]) [part=\"textarea\"],\n  :host([invalid]) [part=\"select\"],\n  :host([invalid]) [part=\"control\"],\n  :host([invalid]) [part=\"editor\"] {\n    border-color: var(--boe-token-surface-status-surface-error, #ed3757);\n  }\n\n  :host([invalid]) [part=\"input\"]:focus-visible,\n  :host([invalid]) [part=\"textarea\"]:focus-visible,\n  :host([invalid]) [part=\"select\"]:focus-visible,\n  :host([invalid]) [part=\"control\"]:focus-visible {\n    border-color: var(--boe-token-surface-status-surface-error, #ed3757);\n    box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 22%, transparent);\n  }\n\n  [part=\"error-message\"] {\n    margin: 0;\n    color: var(--boe-token-surface-status-surface-error, #ed3757);\n    font-size: 0.82rem;\n    line-height: 1.35;\n  }\n\n  [part=\"error-message\"][hidden] {\n    display: none;\n  }\n";
 export declare const FORM_ERROR_MESSAGE_ID = "boe-field-error";
 export declare const formErrorMessageMarkup: () => string;
+export declare const FORM_DESCRIPTION_ID = "boe-field-description";
+/** Optional help text rendered under the label (shown only when `description` is set). */
+export declare const formDescriptionMarkup: () => string;
+/**
+ * Shared chrome for the field-feature set: help-text `description`, the
+ * `required` indicator, and the visually-hidden `hide-label` treatment.
+ * Include alongside `boeFormFieldErrorStyles` in a field's stylesheet.
+ */
+export declare const boeFormFieldSupportStyles = "\n  [part=\"description\"] {\n    margin: 0;\n    color: var(--boe-token-text-text-secondary, #6f6f6f);\n    font-size: 0.82rem;\n    line-height: 1.35;\n  }\n\n  [part=\"description\"][hidden] {\n    display: none;\n  }\n\n  [part=\"label\"] .boe-required-mark {\n    margin-inline-start: 2px;\n    color: var(--boe-token-surface-status-surface-error, #ed3757);\n  }\n\n  :host([hide-label]) [part=\"label\"] {\n    position: absolute;\n    width: 1px;\n    height: 1px;\n    padding: 0;\n    margin: -1px;\n    overflow: hidden;\n    clip: rect(0, 0, 0, 0);\n    white-space: nowrap;\n    border: 0;\n  }\n";
 export declare abstract class FormAssociatedElement extends BaseElement {
     static formAssociated: boolean;
     /** Attributes every form control should observe (merge into subclass lists). */
     static readonly formObservedAttributes: readonly ["name", "invalid", "error-message"];
+    /**
+     * `formObservedAttributes` plus the shared field-feature attributes
+     * (`required`, `description`, `hide-label`). A field that renders a label +
+     * `formDescriptionMarkup()` and calls `applyFieldSupport()` should observe
+     * these instead.
+     */
+    static readonly fieldObservedAttributes: readonly ["name", "invalid", "error-message", "required", "description", "hide-label"];
     /** ElementInternals for form association (public for tests / advanced hosts). */
     readonly internals: ElementInternals;
     private defaultFormValue;
@@ -44,6 +60,14 @@ export declare abstract class FormAssociatedElement extends BaseElement {
     set invalid(value: boolean);
     get errorMessage(): string;
     set errorMessage(value: string);
+    get required(): boolean;
+    set required(value: boolean);
+    /** Help text rendered under the label (empty string hides it). */
+    get description(): string;
+    set description(value: string);
+    /** Keep the label for assistive tech but hide it visually. */
+    get hideLabel(): boolean;
+    set hideLabel(value: boolean);
     /** Value reported to the owning form (`null` omits the control). */
     protected abstract getFormValue(): FormValue;
     /** Restore a value from form reset / autocomplete. */
@@ -60,4 +84,12 @@ export declare abstract class FormAssociatedElement extends BaseElement {
     protected applyInvalidState(control: HTMLElement | null | undefined, messageEl: HTMLElement | null | undefined): void;
     /** Apply invalid ARIA to every focusable control in a multi-option field. */
     protected applyInvalidStateToControls(controls: Iterable<HTMLElement | null | undefined>, messageEl: HTMLElement | null | undefined): void;
+    /**
+     * Apply the shared field features to a rendered field: the `required`
+     * indicator + `aria-required` on the control, the `description` help text +
+     * `aria-describedby`, and the `hide-label` visually-hidden treatment (handled
+     * in CSS via `:host([hide-label])`). Call after setting the label's text
+     * content each update, since setting `textContent` clears the appended mark.
+     */
+    protected applyFieldSupport(labelEl: HTMLElement | null | undefined, control: HTMLElement | null | undefined, descriptionEl: HTMLElement | null | undefined): void;
 }