@unofficialbox/box-open-elements 0.3.0 → 0.4.0

package/dist/components/forms/dropdown.js

@@ -3,6 +3,7 @@ import { boeControl, boeOverlay, boeRadius, boeSpace } from "../../foundations/g
 import { FocusRestore, applyRovingTabindex, focusRovingItem, nextRovingIndex, } from "../../foundations/a11y/index.js";
 import { boeFocusVisibleStyles, 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-dropdown";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
@@ -70,12 +71,14 @@ const dropdownStyles = `
     box-shadow: none;
   }
 
+  /* Positioned by JS (foundations/overlay) as position: fixed, so the menu
+     escapes ancestor overflow and flips/shifts to stay in the viewport. */
   [part="menu"] {
-    position: absolute;
-    inset-block-start: calc(100% + ${boeSpace[1]});
+    position: fixed;
+    inset-block-start: 0;
     inset-inline-start: 0;
     z-index: 20;
-    min-inline-size: max(100%, 200px);
+    min-inline-size: 200px;
     display: grid;
     gap: 0;
     padding: ${boeOverlay.padding};
@@ -139,6 +142,7 @@ export class BoxDropdownElement extends FormAssociatedElement {
             "disabled",
             "items",
             "label",
+            "placement",
             "value",
         ];
     }
@@ -148,6 +152,7 @@ export class BoxDropdownElement extends FormAssociatedElement {
     triggerEl;
     errorEl;
     menuEl = null;
+    positionCleanup = null;
     focusRestore = new FocusRestore();
     onDocumentPointerDown = (event) => {
         const path = event.composedPath();
@@ -173,6 +178,15 @@ export class BoxDropdownElement extends FormAssociatedElement {
     set label(value) {
         this.setAttribute("label", 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 items() {
         const raw = this.getAttribute("items");
         if (!raw) {
@@ -220,6 +234,7 @@ export class BoxDropdownElement extends FormAssociatedElement {
     }
     disconnectedCallback() {
         document.removeEventListener("pointerdown", this.onDocumentPointerDown);
+        this.stopTracking();
         super.disconnectedCallback();
     }
     openMenu() {
@@ -387,13 +402,27 @@ export class BoxDropdownElement extends FormAssociatedElement {
             const items = this.menuItems();
             const selectedIndex = Math.max(0, items.findIndex(button => button.getAttribute("data-item-id") === this.valueInternal));
             applyRovingTabindex(items, selectedIndex);
+            // Match the trigger width, then position as a fixed overlay. Track once
+            // per open so repeated updates (e.g. value change) don't stack listeners.
+            this.menuEl.style.minInlineSize = `${Math.max(this.triggerEl.offsetWidth, 200)}px`;
+            if (!this.positionCleanup) {
+                this.positionCleanup = trackAnchor(this.triggerEl, this.menuEl, {
+                    placement: this.resolvedPlacement(),
+                    offset: 4,
+                });
+            }
         }
         else if (this.menuEl) {
+            this.stopTracking();
             this.menuEl.remove();
             this.menuEl = null;
         }
         this.applyInvalidState(this.triggerEl, this.errorEl);
     }
+    stopTracking() {
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+    }
 }
 export const defineBoxDropdownElement = (tagName = DEFAULT_TAG_NAME) => {
     const existingElement = customElements.get(tagName);

package/dist/components/forms/radio-group.d.ts

@@ -1,5 +1,11 @@
 import { FormAssociatedElement } from "../../core/index.js";
 import type { FormValue } from "../../core/index.js";
+type RadioOption = {
+    label: string;
+    value: string;
+    description?: string;
+    disabled?: boolean;
+};
 export declare class BoxRadioGroupElement extends FormAssociatedElement {
     static get observedAttributes(): string[];
     private valueInternal;
@@ -14,14 +20,8 @@ export declare class BoxRadioGroupElement extends FormAssociatedElement {
     set disabled(value: boolean);
     get label(): string;
     set label(value: string);
-    get options(): Array<{
-        label: string;
-        value: string;
-    }>;
-    set options(value: Array<{
-        label: string;
-        value: string;
-    }>);
+    get options(): RadioOption[];
+    set options(value: RadioOption[]);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected getFormValue(): FormValue;
     protected restoreFormValue(value: FormValue): void;
@@ -30,3 +30,4 @@ export declare class BoxRadioGroupElement extends FormAssociatedElement {
     protected update(): void;
 }
 export declare const defineBoxRadioGroupElement: (tagName?: string) => typeof BoxRadioGroupElement;
+export {};

package/dist/components/forms/radio-group.js

@@ -100,11 +100,34 @@ const radioGroupStyles = `
 
   ${boeFocusVisibleStyles('[part="input"]')}
 
+  [part="option-text"] {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-inline-size: 0;
+  }
+
   [part="option-label"] {
     font-weight: 500;
     color: var(--boe-token-text-text, #222222);
   }
 
+  /* Per-option supporting text below the label. */
+  [part="option-description"] {
+    font-size: 0.78rem;
+    font-weight: 400;
+    line-height: 1.4;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part~="option"][data-has-description="true"] {
+    align-items: start;
+  }
+
+  [part~="option"][data-has-description="true"] [part="input"] {
+    margin-block-start: 2px;
+  }
+
   ${boeFormFieldErrorStyles}
 `;
 export class BoxRadioGroupElement extends FormAssociatedElement {
@@ -209,12 +232,22 @@ export class BoxRadioGroupElement extends FormAssociatedElement {
         const radioGroupName = this.getRadioGroupName();
         if (currentOptionsJson !== this.lastOptionsJson) {
             this.optionsContainerEl.innerHTML = this.options
-                .map(option => `
-            <label part="option" data-value="${escapeHtml(option.value)}">
-              <input type="radio" part="input" name="${escapeHtml(radioGroupName)}" value="${escapeHtml(option.value)}" />
-              <span part="option-label">${escapeHtml(option.label)}</span>
+                .map(option => {
+                const description = option.description
+                    ? `<span part="option-description">${escapeHtml(option.description)}</span>`
+                    : "";
+                const hasDescription = option.description ? "true" : "false";
+                const disabledAttr = option.disabled ? " disabled" : "";
+                return `
+            <label part="option" data-value="${escapeHtml(option.value)}" data-has-description="${hasDescription}">
+              <input type="radio" part="input" name="${escapeHtml(radioGroupName)}" value="${escapeHtml(option.value)}"${disabledAttr} />
+              <span part="option-text">
+                <span part="option-label">${escapeHtml(option.label)}</span>
+                ${description}
+              </span>
             </label>
-          `)
+          `;
+            })
                 .join("");
             this.lastOptionsJson = currentOptionsJson;
             this.optionsContainerEl.querySelectorAll('[part="input"]').forEach(node => {
@@ -242,16 +275,20 @@ export class BoxRadioGroupElement extends FormAssociatedElement {
                 }
             });
         }
+        const disabledByValue = new Map(this.options.map(option => [option.value, Boolean(option.disabled)]));
         this.optionsContainerEl.querySelectorAll('[part~="option"]').forEach(labelNode => {
             const label = labelNode;
             const val = label.dataset.value;
             const isSelected = val === this.valueInternal;
             label.dataset.selected = String(isSelected);
+            // part= is overwritten to toggle the selected token; data-has-description
+            // is a separate attribute and survives.
             label.setAttribute("part", `option${isSelected ? " option-selected" : ""}`);
             const input = label.querySelector('[part="input"]');
             if (input) {
                 input.checked = isSelected;
-                if (this.disabled) {
+                // Disabled if the whole group is disabled or this option is disabled.
+                if (this.disabled || disabledByValue.get(val ?? "")) {
                     input.setAttribute("disabled", "");
                 }
                 else {

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

@@ -2,6 +2,9 @@ import { FormAssociatedElement } from "../../core/index.js";
 import type { FormValue } from "../../core/index.js";
 export declare class BoxSearchFieldElement extends FormAssociatedElement {
     static get observedAttributes(): string[];
+    /** Shows a spinner in the submit button while a search runs asynchronously. */
+    get loading(): boolean;
+    set loading(value: boolean);
     private valueInternal;
     private inputEl;
     private labelEl;
@@ -23,6 +26,11 @@ export declare class BoxSearchFieldElement extends FormAssociatedElement {
     protected restoreFormValue(value: FormValue): void;
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    /**
+     * Emit `search` and, when placed inside a form, request its submission — so a
+     * search field behaves like a native search input on Enter / submit-click.
+     */
+    private submitSearch;
     protected update(): void;
 }
 export declare const defineBoxSearchFieldElement: (tagName?: string) => typeof BoxSearchFieldElement;

package/dist/components/forms/search-field.js

@@ -1,7 +1,8 @@
 import { FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDescriptionMarkup, formErrorMessageMarkup, } from "../../core/index.js";
-import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { boeMotionDuration, boeMotionEasing, boeReducedMotionStyles, } from "../../foundations/motion/index.js";
 import { boeRadius } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-search-field";
+const searchSpinnerMarkup = '<span part="spinner" aria-hidden="true"></span>';
 const searchFieldStyles = `
   :host {
     display: block;
@@ -121,6 +122,22 @@ const searchFieldStyles = `
     cursor: not-allowed;
   }
 
+  [part="submit"] [part="spinner"] {
+    display: inline-block;
+    inline-size: 0.95rem;
+    block-size: 0.95rem;
+    border-radius: 999px;
+    border: 2px solid color-mix(in srgb, currentColor 35%, transparent);
+    border-top-color: currentColor;
+    animation: boe-search-spin ${boeMotionDuration.spin} ${boeMotionEasing.linear} infinite;
+  }
+
+  @keyframes boe-search-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  ${boeReducedMotionStyles('[part="submit"] [part="spinner"]', "animation-duration: 1.6s;")}
+
   ${boeFormFieldErrorStyles}
   ${boeFormFieldSupportStyles}
 `;
@@ -131,9 +148,17 @@ export class BoxSearchFieldElement extends FormAssociatedElement {
             "disabled",
             "label",
             "placeholder",
+            "loading",
             "value",
         ];
     }
+    /** Shows a spinner in the submit button while a search runs asynchronously. */
+    get loading() {
+        return this.hasAttribute("loading");
+    }
+    set loading(value) {
+        this.toggleAttribute("loading", Boolean(value));
+    }
     valueInternal = "";
     inputEl;
     labelEl;
@@ -245,27 +270,32 @@ export class BoxSearchFieldElement extends FormAssociatedElement {
                 return;
             }
             if (event.key === "Enter") {
-                this.dispatchEvent(new CustomEvent("search", {
-                    bubbles: true,
-                    composed: true,
-                    detail: { value: this.valueInternal },
-                }));
+                this.submitSearch();
             }
         });
         this.submitEl.addEventListener("click", () => {
             if (this.disabled) {
                 return;
             }
-            this.dispatchEvent(new CustomEvent("search", {
-                bubbles: true,
-                composed: true,
-                detail: { value: this.valueInternal },
-            }));
+            this.submitSearch();
         });
         this.clearEl.addEventListener("click", () => {
             this.clear();
         });
     }
+    /**
+     * Emit `search` and, when placed inside a form, request its submission — so a
+     * search field behaves like a native search input on Enter / submit-click.
+     */
+    submitSearch() {
+        this.dispatchEvent(new CustomEvent("search", {
+            bubbles: true,
+            composed: true,
+            detail: { value: this.valueInternal },
+        }));
+        const form = this.internals.form ?? this.closest("form");
+        form?.requestSubmit();
+    }
     update() {
         if (!this.inputEl || !this.labelEl || !this.submitEl || !this.clearEl || !this.errorEl) {
             return;
@@ -277,11 +307,23 @@ export class BoxSearchFieldElement extends FormAssociatedElement {
         }
         if (this.disabled) {
             this.inputEl.setAttribute("disabled", "");
-            this.submitEl.setAttribute("disabled", "");
         }
         else {
             this.inputEl.removeAttribute("disabled");
-            this.submitEl.removeAttribute("disabled");
+        }
+        // Loading: show a spinner in the submit button and disable it; else the
+        // submit label, disabled only when the whole field is disabled.
+        if (this.loading) {
+            this.submitEl.innerHTML = searchSpinnerMarkup;
+            this.submitEl.setAttribute("aria-label", "Searching");
+            this.submitEl.setAttribute("aria-busy", "true");
+            this.submitEl.disabled = true;
+        }
+        else {
+            this.submitEl.textContent = "Search";
+            this.submitEl.removeAttribute("aria-label");
+            this.submitEl.removeAttribute("aria-busy");
+            this.submitEl.disabled = this.disabled;
         }
         this.clearEl.disabled = this.disabled || this.valueInternal.length === 0;
         this.applyFieldSupport(this.labelEl, this.inputEl, this.descriptionEl);

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

@@ -1,31 +1,41 @@
 import { FormAssociatedElement } from "../../core/index.js";
 import type { FormValue } from "../../core/index.js";
+type SelectOption = {
+    label: string;
+    value: string;
+    disabled?: boolean;
+    group?: string;
+};
 export declare class BoxSelectElement extends FormAssociatedElement {
     static get observedAttributes(): string[];
     private valueInternal;
+    private valuesInternal;
     private selectEl;
     private labelEl;
     private descriptionEl;
     private errorEl;
+    /** Allow selecting several options (native multi-select list box). */
+    get multiple(): boolean;
+    set multiple(value: boolean);
     get value(): string;
     set value(nextValue: string);
+    /** Selected values (canonical when `multiple`; single-element otherwise). */
+    get values(): string[];
+    set values(next: string[]);
     get disabled(): boolean;
     set disabled(value: boolean);
     get label(): string;
     set label(value: string);
-    get options(): Array<{
-        label: string;
-        value: string;
-    }>;
-    set options(value: Array<{
-        label: string;
-        value: string;
-    }>);
+    get options(): SelectOption[];
+    set options(value: SelectOption[]);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected getFormValue(): FormValue;
     protected restoreFormValue(value: FormValue): void;
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    /** Build `<option>`/`<optgroup>` markup, grouping options that carry `group`. */
+    private optionsMarkup;
     protected update(): void;
 }
 export declare const defineBoxSelectElement: (tagName?: string) => typeof BoxSelectElement;
+export {};

package/dist/components/forms/select.js

@@ -1,4 +1,4 @@
-import { FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDescriptionMarkup, formErrorMessageMarkup, } from "../../core/index.js";
+import { FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDataFromNamedValues, formDescriptionMarkup, formErrorMessageMarkup, stringValuesFromFormValue, } from "../../core/index.js";
 import { boeControl, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-select";
 const escapeHtml = (value) => value
@@ -63,6 +63,20 @@ const selectStyles = `
     cursor: not-allowed;
   }
 
+  /* Multi-select renders as a native list box: drop the single-select chevron
+     and fixed height, let it show several rows. */
+  [part="select"][multiple] {
+    min-height: auto;
+    padding: 4px;
+    background-image: none;
+    cursor: default;
+  }
+
+  [part="select"][multiple] option {
+    padding: 3px 6px;
+    border-radius: ${boeRadius.size};
+  }
+
   ${boeFormFieldErrorStyles}
   ${boeFormFieldSupportStyles}
 `;
@@ -72,25 +86,48 @@ export class BoxSelectElement extends FormAssociatedElement {
             ...FormAssociatedElement.fieldObservedAttributes,
             "disabled",
             "label",
+            "multiple",
             "options",
             "value",
         ];
     }
     valueInternal = "";
+    valuesInternal = [];
     selectEl;
     labelEl;
     descriptionEl;
     errorEl;
+    /** Allow selecting several options (native multi-select list box). */
+    get multiple() {
+        return this.hasAttribute("multiple");
+    }
+    set multiple(value) {
+        this.toggleAttribute("multiple", Boolean(value));
+    }
     get value() {
         return this.valueInternal;
     }
     set value(nextValue) {
         this.valueInternal = nextValue;
+        this.valuesInternal = nextValue ? [nextValue] : [];
         this.setAttribute("value", nextValue);
         if (this.isRendered) {
             this.update();
         }
     }
+    /** Selected values (canonical when `multiple`; single-element otherwise). */
+    get values() {
+        return [...this.valuesInternal];
+    }
+    set values(next) {
+        this.valuesInternal = Array.isArray(next) ? [...next] : [];
+        this.valueInternal = this.valuesInternal[0] ?? "";
+        this.setAttribute("value", this.valueInternal);
+        this.syncFormAssociation();
+        if (this.isRendered) {
+            this.update();
+        }
+    }
     get disabled() {
         return this.hasAttribute("disabled");
     }
@@ -127,16 +164,30 @@ export class BoxSelectElement extends FormAssociatedElement {
     attributeChangedCallback(name, oldValue, newValue) {
         if (name === "value") {
             this.valueInternal = this.getAttribute("value") ?? "";
+            if (!this.multiple) {
+                this.valuesInternal = this.valueInternal ? [this.valueInternal] : [];
+            }
         }
         super.attributeChangedCallback(name, oldValue, newValue);
     }
     getFormValue() {
+        if (this.multiple) {
+            return formDataFromNamedValues(this.name, this.valuesInternal);
+        }
         return this.valueInternal;
     }
     restoreFormValue(value) {
-        const next = typeof value === "string" ? value : "";
-        this.valueInternal = next;
-        this.setAttribute("value", next);
+        if (this.multiple) {
+            this.valuesInternal = stringValuesFromFormValue(value, this.name);
+            this.valueInternal = this.valuesInternal[0] ?? "";
+            this.setAttribute("value", this.valueInternal);
+        }
+        else {
+            const next = typeof value === "string" ? value : "";
+            this.valueInternal = next;
+            this.valuesInternal = next ? [next] : [];
+            this.setAttribute("value", next);
+        }
         if (this.isRendered) {
             this.update();
         }
@@ -161,28 +212,67 @@ export class BoxSelectElement extends FormAssociatedElement {
     }
     setupListeners() {
         this.selectEl.addEventListener("change", event => {
-            const nextValue = event.currentTarget.value;
-            this.valueInternal = nextValue;
-            this.setAttribute("value", nextValue);
+            const select = event.currentTarget;
+            if (this.multiple) {
+                this.valuesInternal = Array.from(select.selectedOptions).map(option => option.value);
+                this.valueInternal = this.valuesInternal[0] ?? "";
+            }
+            else {
+                this.valueInternal = select.value;
+                this.valuesInternal = this.valueInternal ? [this.valueInternal] : [];
+            }
+            this.setAttribute("value", this.valueInternal);
             this.syncFormAssociation();
             this.dispatchEvent(new CustomEvent("value-changed", {
                 bubbles: true,
                 composed: true,
-                detail: { value: nextValue },
+                detail: this.multiple
+                    ? { value: this.valueInternal, values: this.values }
+                    : { value: this.valueInternal },
             }));
         });
     }
+    /** Build `<option>`/`<optgroup>` markup, grouping options that carry `group`. */
+    optionsMarkup() {
+        const renderOption = (option) => `<option value="${escapeHtml(option.value)}"${option.disabled ? " disabled" : ""}>${escapeHtml(option.label)}</option>`;
+        const options = this.options;
+        let markup = "";
+        let index = 0;
+        while (index < options.length) {
+            const group = options[index].group;
+            if (!group) {
+                markup += renderOption(options[index]);
+                index += 1;
+                continue;
+            }
+            // Consume the contiguous run sharing this group label into one optgroup.
+            let run = "";
+            while (index < options.length && options[index].group === group) {
+                run += renderOption(options[index]);
+                index += 1;
+            }
+            markup += `<optgroup label="${escapeHtml(group)}">${run}</optgroup>`;
+        }
+        return markup;
+    }
     update() {
         if (!this.selectEl || !this.labelEl || !this.errorEl) {
             return;
         }
         this.labelEl.textContent = this.label;
-        // Rebuild options (the list itself may change)
-        this.selectEl.innerHTML = this.options
-            .map(option => `<option value="${escapeHtml(option.value)}">${escapeHtml(option.label)}</option>`)
-            .join("");
-        // Patch selected value and disabled after rebuilding options
-        this.selectEl.value = this.valueInternal;
+        // Rebuild options (the list itself may change), grouping by `group`.
+        this.selectEl.multiple = this.multiple;
+        this.selectEl.innerHTML = this.optionsMarkup();
+        // Patch selected value(s) and disabled after rebuilding options.
+        if (this.multiple) {
+            const selected = new Set(this.valuesInternal);
+            Array.from(this.selectEl.options).forEach(option => {
+                option.selected = selected.has(option.value);
+            });
+        }
+        else {
+            this.selectEl.value = this.valueInternal;
+        }
         if (this.disabled) {
             this.selectEl.setAttribute("disabled", "");
         }

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

@@ -7,6 +7,18 @@ export declare class BoxTextFieldElement extends FormAssociatedElement {
     private labelEl;
     private descriptionEl;
     private errorEl;
+    private controlEl;
+    private iconSlot;
+    private statusEl;
+    /** Input type passthrough (text/email/tel/url/password/search/number). */
+    get type(): string;
+    set type(value: string);
+    /** Shows a trailing spinner (e.g. while validating/looking up asynchronously). */
+    get loading(): boolean;
+    set loading(value: boolean);
+    /** Shows a trailing success check (explicit valid affirmation). */
+    get valid(): boolean;
+    set valid(value: boolean);
     get value(): string;
     set value(nextValue: string);
     get disabled(): boolean;
@@ -20,6 +32,7 @@ export declare class BoxTextFieldElement extends FormAssociatedElement {
     protected restoreFormValue(value: FormValue): void;
     protected renderTemplate(): void;
     protected setupListeners(): void;
+    private syncIconSlot;
     protected update(): void;
 }
 export declare const defineBoxTextFieldElement: (tagName?: string) => typeof BoxTextFieldElement;