@unofficialbox/box-open-elements 0.2.1 → 0.4.0

package/dist/components/forms/checkbox.js

@@ -42,10 +42,38 @@ const checkboxStyles = `
 
   ${boeFocusVisibleStyles('[part="input"]')}
 
+  [part="text"] {
+    display: inline-flex;
+    flex-direction: column;
+    gap: 2px;
+    min-inline-size: 0;
+  }
+
   [part="label"] {
     font-weight: 400;
   }
 
+  /* Supporting subsection below the label (BUE checkbox description). */
+  [part="description"] {
+    font-size: 0.82rem;
+    font-weight: 400;
+    line-height: 1.4;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="description"][hidden] {
+    display: none;
+  }
+
+  /* Top-align the box against multi-line content only when a description shows. */
+  [part="field"][data-has-description="true"] {
+    align-items: start;
+  }
+
+  [part="field"][data-has-description="true"] [part="input"] {
+    margin-block-start: 1px;
+  }
+
   :host([disabled]) [part="field"] {
     opacity: ${boeControl.disabledOpacity};
     cursor: not-allowed;
@@ -58,6 +86,7 @@ export class BoxCheckboxElement extends FormAssociatedElement {
         return [
             ...FormAssociatedElement.formObservedAttributes,
             "checked",
+            "description",
             "disabled",
             "indeterminate",
             "label",
@@ -69,7 +98,17 @@ export class BoxCheckboxElement extends FormAssociatedElement {
     valueInternal = DEFAULT_VALUE;
     inputEl;
     labelEl;
+    descriptionEl;
+    fieldEl;
     errorEl;
+    descriptionId = `box-checkbox-desc-${Math.random().toString(36).slice(2, 10)}`;
+    /** Supporting text shown as an indented subsection below the label. */
+    get description() {
+        return this.getAttribute("description") ?? "";
+    }
+    set description(value) {
+        this.setAttribute("description", value);
+    }
     get checked() {
         return this.checkedInternal;
     }
@@ -180,12 +219,17 @@ export class BoxCheckboxElement extends FormAssociatedElement {
           type="checkbox"
           part="input"
         />
-        <span part="label"></span>
+        <span part="text">
+          <span part="label"></span>
+          <span part="description" id="${this.descriptionId}" hidden></span>
+        </span>
       </label>
       ${formErrorMessageMarkup()}
     `;
         this.inputEl = this.shadowRoot.querySelector('[part="input"]');
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
+        this.descriptionEl = this.shadowRoot.querySelector('[part="description"]');
+        this.fieldEl = this.shadowRoot.querySelector('[part="field"]');
         this.errorEl = this.shadowRoot.querySelector('[part="error-message"]');
     }
     setupListeners() {
@@ -237,6 +281,19 @@ export class BoxCheckboxElement extends FormAssociatedElement {
         }
         this.inputEl.setAttribute("aria-label", this.label);
         this.labelEl.textContent = this.label;
+        const description = this.description;
+        if (description) {
+            this.descriptionEl.hidden = false;
+            this.descriptionEl.textContent = description;
+            this.inputEl.setAttribute("aria-describedby", this.descriptionId);
+            this.fieldEl.dataset.hasDescription = "true";
+        }
+        else {
+            this.descriptionEl.hidden = true;
+            this.descriptionEl.textContent = "";
+            this.inputEl.removeAttribute("aria-describedby");
+            this.fieldEl.removeAttribute("data-has-description");
+        }
         this.applyInvalidState(this.inputEl, this.errorEl);
     }
 }

package/dist/components/forms/combobox.d.ts

@@ -3,19 +3,34 @@ import type { FormValue } from "../../core/index.js";
 type BoxComboboxOption = {
     label: string;
     value: string;
+    /** Secondary line rendered under the label (lightweight custom render). */
+    description?: string;
+    /** Options sharing a group render under a divider header. */
+    group?: string;
+    disabled?: boolean;
 };
 export declare class BoxComboboxElement extends FormAssociatedElement {
     static get observedAttributes(): string[];
     private valueInternal;
+    private open;
+    private activeId;
+    private filterText;
+    private positionCleanup;
+    private listboxId;
     private inputEl;
     private labelEl;
-    private datalistEl;
+    private controlEl;
+    private listboxEl;
     private errorEl;
+    private readonly onDocumentPointerDown;
     private findOptionByLabel;
     private findOptionByValue;
     private getDisplayValue;
+    /** Resolve typed text to an option value when it matches a label (free-text otherwise). */
     private resolveInputValue;
     private commitInputValue;
+    /** Options visible for the current filter text (null = show all). */
+    private visibleOptions;
     get disabled(): boolean;
     set disabled(value: boolean);
     get label(): string;
@@ -24,13 +39,27 @@ export declare class BoxComboboxElement extends FormAssociatedElement {
     set options(value: BoxComboboxOption[]);
     get placeholder(): string;
     set placeholder(value: string);
+    get placement(): string;
+    set placement(value: string);
+    private resolvedPlacement;
     get value(): string;
     set value(nextValue: string);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected getFormValue(): FormValue;
     protected restoreFormValue(value: FormValue): void;
+    disconnectedCallback(): void;
+    private stopTracking;
+    private commitValue;
+    private optionId;
+    private openListbox;
+    private closeListbox;
+    private optionEls;
+    private setActive;
+    private moveActive;
+    private selectActive;
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    private renderOptions;
     protected update(): void;
 }
 export declare const defineBoxComboboxElement: (tagName?: string) => typeof BoxComboboxElement;

package/dist/components/forms/combobox.js

@@ -1,7 +1,8 @@
 import { FormAssociatedElement, boeFormFieldErrorStyles, formErrorMessageMarkup, } from "../../core/index.js";
 import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
-import { boeRadius } from "../../foundations/geometry/index.js";
+import { boeOverlay, boeRadius } from "../../foundations/geometry/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
 const DEFAULT_TAG_NAME = "box-combobox";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
@@ -29,8 +30,15 @@ const comboboxStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
   }
 
+  [part="control"] {
+    position: relative;
+    display: block;
+  }
+
   [part="input"] {
     appearance: none;
+    inline-size: 100%;
+    box-sizing: border-box;
     font: inherit;
     color: var(--boe-token-text-text, #222222);
     padding: 0.45rem 0.7rem;
@@ -53,6 +61,76 @@ const comboboxStyles = `
     border-color: var(--boe-token-surface-surface-brand, #0061d5);
   }
 
+  /* Listbox popup — positioned as a viewport-fixed overlay via foundations/overlay. */
+  [part="listbox"] {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    z-index: 40;
+    margin: 0;
+    padding: ${boeOverlay.padding};
+    list-style: none;
+    min-inline-size: 200px;
+    max-block-size: 16rem;
+    overflow-y: auto;
+    border: ${boeOverlay.border};
+    border-radius: ${boeOverlay.radius};
+    background: var(--boe-token-surface-surface, #ffffff);
+    box-shadow: ${boeOverlay.shadow};
+  }
+
+  [part="listbox"][hidden] {
+    display: none;
+  }
+
+  [part="option"] {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-block-size: ${boeOverlay.itemMinHeight};
+    justify-content: center;
+    padding: 6px 10px;
+    border-radius: ${boeOverlay.itemRadius};
+    color: var(--boe-token-text-text, #222222);
+    cursor: pointer;
+  }
+
+  [part="option"][aria-disabled="true"] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  [part="option"].boe-active:not([aria-disabled="true"]) {
+    background: var(--boe-token-surface-surface-hover, #f4f4f4);
+  }
+
+  [part="option"][aria-selected="true"] {
+    color: var(--boe-token-surface-surface-brand, #0061d5);
+    font-weight: 700;
+  }
+
+  [part="option-description"] {
+    font-size: 0.78rem;
+    font-weight: 400;
+    line-height: 1.35;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="group-label"] {
+    padding: 6px 10px 2px;
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="empty"] {
+    padding: 8px 10px;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    font-size: 0.86rem;
+  }
+
   ${boeFormFieldErrorStyles}
 `;
 export class BoxComboboxElement extends FormAssociatedElement {
@@ -63,14 +141,27 @@ export class BoxComboboxElement extends FormAssociatedElement {
             "label",
             "options",
             "placeholder",
+            "placement",
             "value",
         ];
     }
     valueInternal = "";
+    open = false;
+    activeId = null;
+    filterText = null;
+    positionCleanup = null;
+    listboxId = `box-combobox-list-${Math.random().toString(36).slice(2, 10)}`;
     inputEl;
     labelEl;
-    datalistEl;
+    controlEl;
+    listboxEl;
     errorEl;
+    onDocumentPointerDown = (event) => {
+        if (event.composedPath().includes(this)) {
+            return;
+        }
+        this.closeListbox();
+    };
     findOptionByLabel(label) {
         return this.options.find(option => option.label === label);
     }
@@ -78,37 +169,35 @@ export class BoxComboboxElement extends FormAssociatedElement {
         return this.options.find(option => option.value === value);
     }
     getDisplayValue() {
-        const matched = this.findOptionByValue(this.valueInternal);
-        return matched?.label ?? this.valueInternal;
+        return this.findOptionByValue(this.valueInternal)?.label ?? this.valueInternal;
     }
+    /** Resolve typed text to an option value when it matches a label (free-text otherwise). */
     resolveInputValue(rawValue) {
-        const matched = this.findOptionByLabel(rawValue);
-        return matched?.value ?? rawValue;
+        return this.findOptionByLabel(rawValue)?.value ?? rawValue;
     }
     commitInputValue(rawValue) {
-        const resolvedValue = this.resolveInputValue(rawValue);
-        this.valueInternal = resolvedValue;
-        this.setAttribute("value", resolvedValue);
-        this.syncFormAssociation();
-        this.dispatchEvent(new CustomEvent("value-changed", {
-            bubbles: true,
-            composed: true,
-            detail: { value: resolvedValue },
-        }));
+        const resolved = this.resolveInputValue(rawValue);
+        if (resolved !== this.valueInternal) {
+            this.commitValue(resolved);
+        }
         if (this.shadowRoot?.activeElement !== this.inputEl) {
             this.inputEl.value = this.getDisplayValue();
         }
     }
+    /** Options visible for the current filter text (null = show all). */
+    visibleOptions() {
+        const filter = this.filterText;
+        if (filter == null || filter === "") {
+            return this.options;
+        }
+        const needle = filter.toLowerCase();
+        return this.options.filter(option => option.label.toLowerCase().includes(needle));
+    }
     get disabled() {
         return this.hasAttribute("disabled");
     }
     set disabled(value) {
-        if (value) {
-            this.setAttribute("disabled", "");
-        }
-        else {
-            this.removeAttribute("disabled");
-        }
+        this.toggleAttribute("disabled", Boolean(value));
     }
     get label() {
         return this.getAttribute("label") ?? "Combobox";
@@ -138,6 +227,15 @@ export class BoxComboboxElement extends FormAssociatedElement {
     set placeholder(value) {
         this.setAttribute("placeholder", value);
     }
+    get placement() {
+        return this.getAttribute("placement") ?? "bottom-start";
+    }
+    set placement(value) {
+        this.setAttribute("placement", value);
+    }
+    resolvedPlacement() {
+        return parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "start" };
+    }
     get value() {
         return this.valueInternal;
     }
@@ -165,54 +263,250 @@ export class BoxComboboxElement extends FormAssociatedElement {
             this.update();
         }
     }
+    disconnectedCallback() {
+        document.removeEventListener("pointerdown", this.onDocumentPointerDown);
+        this.stopTracking();
+        super.disconnectedCallback();
+    }
+    stopTracking() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+    }
+    commitValue(value) {
+        this.valueInternal = value;
+        this.setAttribute("value", value);
+        this.syncFormAssociation();
+        this.dispatchEvent(new CustomEvent("value-changed", {
+            bubbles: true,
+            composed: true,
+            detail: { value },
+        }));
+    }
+    optionId(index) {
+        return `${this.listboxId}-opt-${index}`;
+    }
+    openListbox() {
+        if (this.disabled || this.open) {
+            return;
+        }
+        this.open = true;
+        document.addEventListener("pointerdown", this.onDocumentPointerDown);
+        this.update();
+        this.positionCleanup = trackAnchor(this.controlEl, this.listboxEl, {
+            placement: this.resolvedPlacement(),
+            offset: 4,
+        });
+    }
+    closeListbox(restoreDisplay = true) {
+        if (!this.open) {
+            return;
+        }
+        this.open = false;
+        this.activeId = null;
+        this.filterText = null;
+        document.removeEventListener("pointerdown", this.onDocumentPointerDown);
+        this.stopTracking();
+        if (restoreDisplay && this.shadowRoot?.activeElement !== this.inputEl) {
+            this.inputEl.value = this.getDisplayValue();
+        }
+        this.update();
+    }
+    optionEls() {
+        return Array.from(this.listboxEl.querySelectorAll('[part="option"]:not([aria-disabled="true"])'));
+    }
+    setActive(id) {
+        this.activeId = id;
+        this.listboxEl.querySelectorAll('[part="option"]').forEach(node => {
+            node.classList.toggle("boe-active", node.id === id);
+        });
+        if (id) {
+            this.inputEl.setAttribute("aria-activedescendant", id);
+            const activeEl = this.listboxEl.querySelector(`#${id}`);
+            // scrollIntoView is absent in jsdom; guard so tests and SSR don't throw.
+            activeEl?.scrollIntoView?.({ block: "nearest" });
+        }
+        else {
+            this.inputEl.removeAttribute("aria-activedescendant");
+        }
+    }
+    moveActive(delta) {
+        const options = this.optionEls();
+        if (options.length === 0) {
+            return;
+        }
+        const currentIndex = options.findIndex(node => node.id === this.activeId);
+        let nextIndex = currentIndex + delta;
+        if (nextIndex < 0) {
+            nextIndex = options.length - 1;
+        }
+        else if (nextIndex >= options.length) {
+            nextIndex = 0;
+        }
+        this.setActive(options[nextIndex].id);
+    }
+    selectActive() {
+        if (!this.activeId) {
+            return;
+        }
+        const optionEl = this.listboxEl.querySelector(`#${this.activeId}`);
+        const value = optionEl?.dataset.value;
+        if (value == null) {
+            return;
+        }
+        this.commitValue(value);
+        this.inputEl.value = this.getDisplayValue();
+        // Keep focus on the input (Enter already has it; click was prevented from
+        // blurring) — do NOT call focus() here, which would retrigger open.
+        this.closeListbox(false);
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
         }
         this.shadowRoot.innerHTML = `
       <style>${comboboxStyles}</style>
-      <label part="field">
-        <span part="label"></span>
-        <input type="text" part="input" list="combobox-options" />
-        <datalist id="combobox-options"></datalist>
+      <div part="field">
+        <span part="label" id="${this.listboxId}-label"></span>
+        <div part="control">
+          <input
+            type="text"
+            part="input"
+            role="combobox"
+            autocomplete="off"
+            aria-autocomplete="list"
+            aria-expanded="false"
+            aria-controls="${this.listboxId}"
+          />
+        </div>
+        <ul part="listbox" id="${this.listboxId}" role="listbox" aria-labelledby="${this.listboxId}-label" hidden></ul>
         ${formErrorMessageMarkup()}
-      </label>
+      </div>
     `;
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
         this.inputEl = this.shadowRoot.querySelector('[part="input"]');
-        this.datalistEl = this.shadowRoot.querySelector("datalist");
+        this.controlEl = this.shadowRoot.querySelector('[part="control"]');
+        this.listboxEl = this.shadowRoot.querySelector('[part="listbox"]');
         this.errorEl = this.shadowRoot.querySelector('[part="error-message"]');
     }
     setupListeners() {
         this.inputEl.addEventListener("input", event => {
-            const rawValue = event.currentTarget.value;
-            this.commitInputValue(rawValue);
+            const raw = event.currentTarget.value;
+            this.filterText = raw;
+            // Preserve free-text behaviour: typed text commits (resolving label→value).
+            this.commitInputValue(raw);
+            this.openListbox();
+            this.update();
+            // Keep the first match active for quick Enter selection.
+            const first = this.optionEls()[0];
+            this.setActive(first?.id ?? null);
         });
-        this.inputEl.addEventListener("change", event => {
-            const rawValue = event.currentTarget.value;
-            this.commitInputValue(rawValue);
+        this.inputEl.addEventListener("keydown", event => {
+            const key = event.key;
+            if (key === "ArrowDown") {
+                event.preventDefault();
+                if (!this.open) {
+                    this.openListbox();
+                    const first = this.optionEls()[0];
+                    this.setActive(first?.id ?? null);
+                }
+                else {
+                    this.moveActive(1);
+                }
+            }
+            else if (key === "ArrowUp") {
+                event.preventDefault();
+                if (this.open) {
+                    this.moveActive(-1);
+                }
+            }
+            else if (key === "Home" && this.open) {
+                event.preventDefault();
+                const first = this.optionEls()[0];
+                this.setActive(first?.id ?? null);
+            }
+            else if (key === "End" && this.open) {
+                event.preventDefault();
+                const options = this.optionEls();
+                this.setActive(options[options.length - 1]?.id ?? null);
+            }
+            else if (key === "Enter") {
+                if (this.open && this.activeId) {
+                    event.preventDefault();
+                    this.selectActive();
+                }
+            }
+            else if (key === "Escape") {
+                if (this.open) {
+                    event.preventDefault();
+                    this.closeListbox();
+                }
+            }
         });
-        this.inputEl.addEventListener("blur", () => {
-            const rawValue = this.inputEl.value;
-            const resolvedValue = this.resolveInputValue(rawValue);
-            if (resolvedValue !== this.valueInternal) {
-                this.commitInputValue(rawValue);
+        this.inputEl.addEventListener("focus", () => {
+            if (!this.disabled) {
+                this.openListbox();
             }
-            else if (rawValue !== this.getDisplayValue()) {
-                this.inputEl.value = this.getDisplayValue();
+        });
+        this.listboxEl.addEventListener("pointerdown", event => {
+            // Prevent the input blur so selection completes before focus moves.
+            event.preventDefault();
+        });
+        this.listboxEl.addEventListener("click", event => {
+            const optionEl = event.target.closest('[part="option"]');
+            if (!optionEl || optionEl.getAttribute("aria-disabled") === "true") {
+                return;
+            }
+            this.setActive(optionEl.id);
+            this.selectActive();
+        });
+        this.inputEl.addEventListener("blur", () => {
+            // Resolve typed text (label→value) then close (pointerdown-on-option is
+            // prevented above so option clicks complete first).
+            this.commitInputValue(this.inputEl.value);
+            this.closeListbox();
+        });
+    }
+    renderOptions() {
+        const options = this.visibleOptions();
+        if (options.length === 0) {
+            this.listboxEl.innerHTML = `<li part="empty" role="presentation">No matches</li>`;
+            return;
+        }
+        let markup = "";
+        let lastGroup;
+        options.forEach((option, index) => {
+            if (option.group && option.group !== lastGroup) {
+                markup += `<li part="group-label" role="presentation">${escapeHtml(option.group)}</li>`;
             }
+            lastGroup = option.group;
+            const selected = option.value === this.valueInternal;
+            const description = option.description
+                ? `<span part="option-description">${escapeHtml(option.description)}</span>`
+                : "";
+            markup += `
+        <li
+          id="${this.optionId(index)}"
+          part="option"
+          role="option"
+          data-value="${escapeHtml(option.value)}"
+          aria-selected="${selected ? "true" : "false"}"
+          ${option.disabled ? 'aria-disabled="true"' : ""}
+        >
+          <span part="option-label">${escapeHtml(option.label)}</span>
+          ${description}
+        </li>
+      `;
         });
+        this.listboxEl.innerHTML = markup;
     }
     update() {
-        if (!this.inputEl || !this.labelEl || !this.datalistEl || !this.errorEl) {
+        if (!this.inputEl || !this.labelEl || !this.listboxEl || !this.errorEl) {
             return;
         }
         this.labelEl.textContent = this.label;
         this.inputEl.placeholder = this.placeholder;
-        this.datalistEl.innerHTML = this.options
-            .map(option => `<option value="${escapeHtml(option.label)}" data-option-value="${escapeHtml(option.value)}"></option>`)
-            .join("");
-        if (this.shadowRoot?.activeElement !== this.inputEl) {
+        this.inputEl.setAttribute("aria-label", this.label);
+        if (this.shadowRoot?.activeElement !== this.inputEl && this.filterText == null) {
             this.inputEl.value = this.getDisplayValue();
         }
         if (this.disabled) {
@@ -221,6 +515,16 @@ export class BoxComboboxElement extends FormAssociatedElement {
         else {
             this.inputEl.removeAttribute("disabled");
         }
+        this.listboxEl.hidden = !this.open;
+        this.inputEl.setAttribute("aria-expanded", this.open ? "true" : "false");
+        if (this.open) {
+            this.renderOptions();
+            // Reassert active highlight after a re-render.
+            this.setActive(this.activeId);
+        }
+        else {
+            this.inputEl.removeAttribute("aria-activedescendant");
+        }
         this.applyInvalidState(this.inputEl, this.errorEl);
     }
 }

package/dist/components/forms/date-field.d.ts

@@ -5,7 +5,13 @@ export declare class BoxDateFieldElement extends FormAssociatedElement {
     private valueInternal;
     private inputEl;
     private labelEl;
+    private descriptionEl;
     private errorEl;
+    private controlEl;
+    private clearEl;
+    /** Shows a clear button that resets the value when a date is set. */
+    get clearable(): boolean;
+    set clearable(value: boolean);
     get disabled(): boolean;
     set disabled(value: boolean);
     get label(): string;
@@ -22,6 +28,8 @@ export declare class BoxDateFieldElement extends FormAssociatedElement {
     private syncValue;
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    /** Reset the date to empty and emit value-changed. */
+    clear(): void;
     protected update(): void;
 }
 export declare const defineBoxDateFieldElement: (tagName?: string) => typeof BoxDateFieldElement;