@unofficialbox/box-open-elements 0.3.0 → 0.5.0

package/dist/components/forms/category-selector.js

@@ -1,5 +1,8 @@
 import { BaseElement } from "../../core/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { boeOverlay, boeRadius } from "../../foundations/geometry/index.js";
+import { boeNeutralInteractiveStyles } from "../../foundations/tokens/index.js";
+import { parsePlacement, trackAnchor, } from "../../foundations/overlay/index.js";
 const DEFAULT_TAG_NAME = "box-category-selector";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
@@ -59,6 +62,50 @@ const categorySelectorStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
     font-size: 0.86rem;
   }
+
+  /* Overflow "More" menu (shown when options exceed max-links). */
+  [part="more-menu"] {
+    position: fixed;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    z-index: 40;
+    margin: 0;
+    padding: ${boeOverlay.padding};
+    list-style: none;
+    min-inline-size: 10rem;
+    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="more-menu"][hidden] {
+    display: none;
+  }
+
+  [part="more-item"] {
+    appearance: none;
+    display: block;
+    inline-size: 100%;
+    text-align: start;
+    border: 0;
+    background: transparent;
+    color: var(--boe-token-text-text, #222222);
+    font: inherit;
+    font-size: 0.84rem;
+    padding: 6px 10px;
+    border-radius: ${boeRadius.med};
+    cursor: pointer;
+  }
+
+  [part="more-item"][aria-checked="true"] {
+    color: var(--boe-token-surface-surface-brand, #0061d5);
+    font-weight: 700;
+  }
+
+  ${boeNeutralInteractiveStyles('[part="more-item"]')}
 `;
 /**
  * A single-select category picker rendered as a horizontal radiogroup of pills —
@@ -67,14 +114,31 @@ const categorySelectorStyles = `
  * `value` and announced with `value-changed`. Follows the radiogroup keyboard
  * pattern: arrow keys move selection with roving `tabindex`.
  */
-export class BoxCategorySelectorElement extends BaseElement {
+export class CategorySelector extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["label", "options", "value"];
+        return ["label", "options", "value", "max-links"];
     }
     valueInternal = "";
     lastOptionsJson = "";
     hadFocus = false;
     rootEl;
+    moreOpen = false;
+    positionCleanup = null;
+    onDocumentPointerDown = (event) => {
+        if (event.composedPath().includes(this)) {
+            return;
+        }
+        this.closeMore();
+    };
+    /** Max inline categories before the rest collapse into a "More" menu (0 = no limit). */
+    get maxLinks() {
+        const raw = Number(this.getAttribute("max-links"));
+        return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 0;
+    }
+    set maxLinks(value) {
+        this.setAttribute("max-links", String(value));
+    }
     get label() {
         return this.getAttribute("label") ?? "Categories";
     }
@@ -116,6 +180,14 @@ export class BoxCategorySelectorElement extends BaseElement {
     selectableOptions() {
         return this.options.filter(option => !option.disabled);
     }
+    splitOptions() {
+        const options = this.options;
+        const max = this.maxLinks;
+        if (max <= 0 || options.length <= max) {
+            return { visible: options, overflow: [] };
+        }
+        return { visible: options.slice(0, max), overflow: options.slice(max) };
+    }
     select(value) {
         if (!value || value === this.valueInternal) {
             return;
@@ -158,20 +230,108 @@ export class BoxCategorySelectorElement extends BaseElement {
     `;
         this.rootEl = this.shadowRoot.querySelector('[part="root"]');
     }
+    resolvedPlacement() {
+        return parsePlacement(this.getAttribute("placement")) ?? { side: "bottom", align: "end" };
+    }
+    openMore() {
+        const moreBtn = this.rootEl.querySelector('[data-more]');
+        const menu = this.rootEl.querySelector('[part="more-menu"]');
+        if (!moreBtn || !menu || this.moreOpen) {
+            return;
+        }
+        this.moreOpen = true;
+        menu.hidden = false;
+        moreBtn.setAttribute("aria-expanded", "true");
+        document.addEventListener("pointerdown", this.onDocumentPointerDown);
+        this.positionCleanup = trackAnchor(moreBtn, menu, {
+            placement: this.resolvedPlacement(),
+            offset: 4,
+        });
+        menu.querySelector('[part="more-item"]')?.focus();
+    }
+    closeMore(restoreFocus = false) {
+        if (!this.moreOpen) {
+            return;
+        }
+        this.moreOpen = false;
+        const moreBtn = this.rootEl.querySelector('[data-more]');
+        const menu = this.rootEl.querySelector('[part="more-menu"]');
+        if (menu) {
+            menu.hidden = true;
+        }
+        moreBtn?.setAttribute("aria-expanded", "false");
+        document.removeEventListener("pointerdown", this.onDocumentPointerDown);
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+        if (restoreFocus) {
+            moreBtn?.focus();
+        }
+    }
+    disconnectedCallback() {
+        document.removeEventListener("pointerdown", this.onDocumentPointerDown);
+        this.positionCleanup?.();
+        this.positionCleanup = null;
+        super.disconnectedCallback?.();
+    }
     setupListeners() {
         this.rootEl.addEventListener("click", event => {
-            const button = event.target.closest('[part~="pill"]');
+            const target = event.target;
+            const moreBtn = target.closest('[data-more]');
+            if (moreBtn && this.rootEl.contains(moreBtn)) {
+                if (this.moreOpen) {
+                    this.closeMore();
+                }
+                else {
+                    this.openMore();
+                }
+                return;
+            }
+            const menuItem = target.closest('[part="more-item"]');
+            if (menuItem && this.rootEl.contains(menuItem)) {
+                this.select(menuItem.dataset.value ?? "");
+                this.closeMore(true);
+                return;
+            }
+            const button = target.closest('[part~="pill"]');
             if (!button || !this.rootEl.contains(button)) {
                 return;
             }
             this.select(button.dataset.value ?? "");
         });
         this.rootEl.addEventListener("keydown", event => {
-            const button = event.target.closest('[part~="pill"]');
+            const keyboardEvent = event;
+            const target = event.target;
+            // Menu item keys: Escape closes and returns focus; Arrow moves within.
+            const menuItem = target.closest('[part="more-item"]');
+            if (menuItem && this.rootEl.contains(menuItem)) {
+                const items = Array.from(this.rootEl.querySelectorAll('[part="more-item"]:not(:disabled)'));
+                const index = items.indexOf(menuItem);
+                if (keyboardEvent.key === "Escape") {
+                    keyboardEvent.preventDefault();
+                    this.closeMore(true);
+                }
+                else if (keyboardEvent.key === "ArrowDown") {
+                    keyboardEvent.preventDefault();
+                    items[(index + 1) % items.length]?.focus();
+                }
+                else if (keyboardEvent.key === "ArrowUp") {
+                    keyboardEvent.preventDefault();
+                    items[(index - 1 + items.length) % items.length]?.focus();
+                }
+                return;
+            }
+            const button = target.closest('[part~="pill"]');
             if (!button || !this.rootEl.contains(button)) {
                 return;
             }
-            const keyboardEvent = event;
+            // "More" button: open the overflow menu.
+            if (button.dataset.more) {
+                if (["Enter", " ", "ArrowDown"].includes(keyboardEvent.key)) {
+                    keyboardEvent.preventDefault();
+                    this.openMore();
+                }
+                return;
+            }
             const value = button.dataset.value ?? "";
             switch (keyboardEvent.key) {
                 case "ArrowRight":
@@ -221,29 +381,48 @@ export class BoxCategorySelectorElement extends BaseElement {
             this.lastOptionsJson = "";
             return;
         }
-        const optionsJson = JSON.stringify(options);
-        if (optionsJson !== this.lastOptionsJson || !this.rootEl.querySelector('[part="group"]')) {
-            this.rootEl.innerHTML = `
-        <div part="group" role="radiogroup" aria-label="${escapeHtml(this.label)}">
-          ${options
-                .map(option => `
-                <button
+        const { visible, overflow } = this.splitOptions();
+        const selectedInOverflow = overflow.some(option => option.value === this.valueInternal);
+        const cacheKey = `${JSON.stringify(options)}|${this.maxLinks}`;
+        if (cacheKey !== this.lastOptionsJson || !this.rootEl.querySelector('[part="group"]')) {
+            const pillMarkup = (option) => `
+        <button
+          type="button"
+          part="pill"
+          role="radio"
+          data-value="${escapeHtml(option.value)}"
+          ${option.disabled ? "disabled" : ""}
+        >${escapeHtml(option.label)}</button>
+      `;
+            const moreButton = overflow.length
+                ? `<button type="button" part="pill more" data-more="true" aria-haspopup="menu" aria-expanded="false">More</button>`
+                : "";
+            const moreMenu = overflow.length
+                ? `<ul part="more-menu" role="menu" aria-label="More categories" hidden>${overflow
+                    .map(option => `
+                <li role="none"><button
                   type="button"
-                  part="pill"
-                  role="radio"
+                  part="more-item"
+                  role="menuitemradio"
                   data-value="${escapeHtml(option.value)}"
                   ${option.disabled ? "disabled" : ""}
-                >${escapeHtml(option.label)}</button>
+                >${escapeHtml(option.label)}</button></li>
               `)
-                .join("")}
+                    .join("")}</ul>`
+                : "";
+            this.rootEl.innerHTML = `
+        <div part="group" role="radiogroup" aria-label="${escapeHtml(this.label)}">
+          ${visible.map(pillMarkup).join("")}
+          ${moreButton}
         </div>
+        ${moreMenu}
       `;
-            this.lastOptionsJson = optionsJson;
+            this.lastOptionsJson = cacheKey;
         }
         const group = this.rootEl.querySelector('[part="group"]');
         group?.setAttribute("aria-label", this.label);
         const tabbableValue = this.valueInternal || this.selectableOptions()[0]?.value || "";
-        this.rootEl.querySelectorAll('[part~="pill"]').forEach(node => {
+        this.rootEl.querySelectorAll('[part~="pill"]:not([data-more])').forEach(node => {
             const button = node;
             const optionValue = button.dataset.value ?? "";
             const option = options.find(entry => entry.value === optionValue);
@@ -252,6 +431,22 @@ export class BoxCategorySelectorElement extends BaseElement {
             button.setAttribute("aria-checked", String(isChecked));
             button.tabIndex = optionValue === tabbableValue && !option?.disabled ? 0 : -1;
         });
+        // "More" reflects an active overflow selection and shows its label.
+        const moreBtn = this.rootEl.querySelector('[data-more]');
+        if (moreBtn) {
+            const selectedOption = overflow.find(option => option.value === this.valueInternal);
+            moreBtn.textContent = selectedOption ? selectedOption.label : "More";
+            moreBtn.setAttribute("part", selectedInOverflow ? "pill more pill-checked" : "pill more");
+            moreBtn.setAttribute("aria-expanded", this.moreOpen ? "true" : "false");
+            // Roving tabindex: the More button is the tabbable entry when it holds the
+            // active (overflow) selection; otherwise a visible pill is.
+            moreBtn.tabIndex = selectedInOverflow ? 0 : -1;
+        }
+        // Reflect the checked overflow option in the menu.
+        this.rootEl.querySelectorAll('[part="more-item"]').forEach(node => {
+            const button = node;
+            button.setAttribute("aria-checked", String(button.dataset.value === this.valueInternal));
+        });
         if (this.hadFocus && this.valueInternal) {
             const active = Array.from(this.rootEl.querySelectorAll('[part~="pill"]')).find(node => node.dataset.value === this.valueInternal);
             active?.focus();
@@ -259,11 +454,4 @@ export class BoxCategorySelectorElement extends BaseElement {
         }
     }
 }
-export const defineBoxCategorySelectorElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxCategorySelectorElement);
-    return BoxCategorySelectorElement;
-};
+CategorySelector.register();

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

@@ -5,7 +5,8 @@ type CheckboxGroupOption = {
     label: string;
     value: string;
 };
-export declare class BoxCheckboxGroupElement extends FormAssociatedElement {
+export declare class CheckboxGroup extends FormAssociatedElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private lastOptionsJson;
@@ -27,5 +28,4 @@ export declare class BoxCheckboxGroupElement extends FormAssociatedElement {
     protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxCheckboxGroupElement: (tagName?: string) => typeof BoxCheckboxGroupElement;
 export {};

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

@@ -96,7 +96,8 @@ const checkboxGroupStyles = `
 
   ${boeFormFieldErrorStyles}
 `;
-export class BoxCheckboxGroupElement extends FormAssociatedElement {
+export class CheckboxGroup extends FormAssociatedElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return [
             ...FormAssociatedElement.formObservedAttributes,
@@ -257,11 +258,4 @@ export class BoxCheckboxGroupElement extends FormAssociatedElement {
         this.applyInvalidStateToControls(Array.from(this.optionsContainerEl.querySelectorAll('[part="input"]')), this.errorEl);
     }
 }
-export const defineBoxCheckboxGroupElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxCheckboxGroupElement);
-    return BoxCheckboxGroupElement;
-};
+CheckboxGroup.register();

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

@@ -1,13 +1,20 @@
 import { FormAssociatedElement } from "../../core/index.js";
 import type { FormValue } from "../../core/index.js";
-export declare class BoxCheckboxElement extends FormAssociatedElement {
+export declare class Checkbox extends FormAssociatedElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private checkedInternal;
     private indeterminateInternal;
     private valueInternal;
     private inputEl;
     private labelEl;
+    private descriptionEl;
+    private fieldEl;
     private errorEl;
+    private descriptionId;
+    /** Supporting text shown as an indented subsection below the label. */
+    get description(): string;
+    set description(value: string);
     get checked(): boolean;
     set checked(value: boolean);
     get indeterminate(): boolean;
@@ -25,4 +32,3 @@ export declare class BoxCheckboxElement extends FormAssociatedElement {
     protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxCheckboxElement: (tagName?: string) => typeof BoxCheckboxElement;

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;
@@ -53,11 +81,13 @@ const checkboxStyles = `
 
   ${boeFormFieldErrorStyles}
 `;
-export class BoxCheckboxElement extends FormAssociatedElement {
+export class Checkbox extends FormAssociatedElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return [
             ...FormAssociatedElement.formObservedAttributes,
             "checked",
+            "description",
             "disabled",
             "indeterminate",
             "label",
@@ -69,7 +99,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 +220,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,14 +282,20 @@ 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);
     }
 }
-export const defineBoxCheckboxElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxCheckboxElement);
-    return BoxCheckboxElement;
-};
+Checkbox.register();

package/dist/components/forms/color-picker.d.ts

@@ -4,7 +4,8 @@ type BoxColorSwatch = {
     label?: string;
     value: string;
 };
-export declare class BoxColorPickerElement extends FormAssociatedElement {
+export declare class ColorPicker extends FormAssociatedElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private lastSwatchesJson;
@@ -30,5 +31,4 @@ export declare class BoxColorPickerElement extends FormAssociatedElement {
     protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxColorPickerElement: (tagName?: string) => typeof BoxColorPickerElement;
 export {};

package/dist/components/forms/color-picker.js

@@ -117,7 +117,8 @@ const colorPickerStyles = `
 
   ${boeFormFieldErrorStyles}
 `;
-export class BoxColorPickerElement extends FormAssociatedElement {
+export class ColorPicker extends FormAssociatedElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return [
             ...FormAssociatedElement.formObservedAttributes,
@@ -304,11 +305,4 @@ export class BoxColorPickerElement extends FormAssociatedElement {
         this.applyInvalidState(this.inputEl, this.errorEl);
     }
 }
-export const defineBoxColorPickerElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxColorPickerElement);
-    return BoxColorPickerElement;
-};
+ColorPicker.register();

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

@@ -3,19 +3,35 @@ 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 {
+export declare class Combobox extends FormAssociatedElement {
+    static readonly tagName: string;
     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,14 +40,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;
 export {};