@unofficialbox/box-open-elements 0.2.1 → 0.4.0

package/dist/components/feedback/error-mask.js

@@ -57,6 +57,17 @@ const errorMaskStyles = `
     display: none;
   }
 
+  /* Optional rich body — slotted markup below the message.
+     Hidden (no column gap) until content is assigned. */
+  [part="body"] {
+    display: block;
+    max-width: 32rem;
+  }
+
+  [part="body"]:not(.has-content) {
+    display: none;
+  }
+
   [part="action"] {
     appearance: none;
     box-sizing: border-box;
@@ -100,6 +111,7 @@ export class BoxErrorMaskElement extends BaseElement {
     }
     titleEl;
     messageEl;
+    bodySlot;
     actionEl = null;
     get heading() {
         return this.getAttribute("heading") ?? "Something went wrong";
@@ -141,10 +153,19 @@ export class BoxErrorMaskElement extends BaseElement {
         </span>
         <h2 part="title"></h2>
         <span part="message description" hidden></span>
+        <slot part="body"></slot>
       </section>
     `;
         this.titleEl = this.shadowRoot.querySelector('[part="title"]');
         this.messageEl = this.shadowRoot.querySelector('[part~="message"]');
+        this.bodySlot = this.shadowRoot.querySelector('slot[part="body"]');
+    }
+    setupListeners() {
+        this.bodySlot.addEventListener("slotchange", () => {
+            if (this.isRendered) {
+                this.update();
+            }
+        });
     }
     syncActionButton() {
         const section = this.shadowRoot?.querySelector('[part="error-mask"]');
@@ -178,6 +199,8 @@ export class BoxErrorMaskElement extends BaseElement {
             return;
         }
         this.titleEl.textContent = this.heading;
+        const hasBody = this.bodySlot.assignedNodes({ flatten: true }).length > 0;
+        this.bodySlot.classList.toggle("has-content", hasBody);
         if (this.message) {
             this.messageEl.hidden = false;
             this.messageEl.textContent = this.message;

package/dist/components/feedback/help-text.js

@@ -152,6 +152,13 @@ export class BoxHelpTextElement extends BaseElement {
                 : "info";
         const iconMarkup = resolveDesignIcon(iconName) ?? "i";
         this.helpTextEl.dataset.tone = this.tone;
+        // Error help text is an inline validation error: announce it assertively.
+        if (this.tone === "error") {
+            this.helpTextEl.setAttribute("role", "alert");
+        }
+        else {
+            this.helpTextEl.setAttribute("role", "note");
+        }
         this.helpTextEl.setAttribute("aria-label", this.label || "Help text");
         this.iconEl.setAttribute("data-icon-source", iconMarkup === "i" ? "text" : "design-system");
         this.iconEl.innerHTML = iconMarkup;

package/dist/components/feedback/spinner.d.ts

@@ -2,8 +2,12 @@ import { BaseElement } from "../../core/index.js";
 export declare class BoxSpinnerElement extends BaseElement {
     static get observedAttributes(): string[];
     private labelEl;
+    private indicatorEl;
     get label(): string;
     set label(value: string);
+    /** Indicator size: `small`, `medium` (default), or `large`. */
+    get size(): string;
+    set size(value: string);
     protected renderTemplate(): void;
     protected update(): void;
 }

package/dist/components/feedback/spinner.js

@@ -25,6 +25,18 @@ const spinnerStyles = `
     animation: boe-spinner-rotate ${boeMotionDuration.spin} ${boeMotionEasing.linear} infinite;
   }
 
+  [part="indicator"][data-size="small"] {
+    width: 0.85rem;
+    height: 0.85rem;
+    border-width: 2px;
+  }
+
+  [part="indicator"][data-size="large"] {
+    width: 1.6rem;
+    height: 1.6rem;
+    border-width: 3px;
+  }
+
   @keyframes boe-spinner-rotate {
     to {
       transform: rotate(360deg);
@@ -41,15 +53,24 @@ const spinnerStyles = `
 `;
 export class BoxSpinnerElement extends BaseElement {
     static get observedAttributes() {
-        return ["label"];
+        return ["label", "size"];
     }
     labelEl;
+    indicatorEl;
     get label() {
         return this.getAttribute("label") ?? "Loading";
     }
     set label(value) {
         this.setAttribute("label", value);
     }
+    /** Indicator size: `small`, `medium` (default), or `large`. */
+    get size() {
+        const value = this.getAttribute("size");
+        return value === "small" || value === "large" ? value : "medium";
+    }
+    set size(value) {
+        this.setAttribute("size", value);
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
@@ -62,12 +83,19 @@ export class BoxSpinnerElement extends BaseElement {
       </div>
     `;
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
+        this.indicatorEl = this.shadowRoot.querySelector('[part="indicator"]');
     }
     update() {
-        if (!this.labelEl) {
+        if (!this.labelEl || !this.indicatorEl) {
             return;
         }
         this.labelEl.textContent = this.label;
+        if (this.size === "medium") {
+            this.indicatorEl.removeAttribute("data-size");
+        }
+        else {
+            this.indicatorEl.dataset.size = this.size;
+        }
     }
 }
 export const defineBoxSpinnerElement = (tagName = DEFAULT_TAG_NAME) => {

package/dist/components/feedback/toast.d.ts

@@ -5,9 +5,14 @@ export declare class BoxToastElement extends BaseElement {
     private timeoutId;
     private toastEl;
     private messageEl;
+    private actionSlot;
     private dismissEl;
+    /** Auto-dismiss delay in ms for the declarative `open` path. 0 = sticky. */
+    get duration(): number;
+    set duration(value: number);
     get open(): boolean;
     set open(value: boolean);
+    private scheduleAutoDismiss;
     get message(): string;
     set message(value: string);
     get tone(): string;

package/dist/components/feedback/toast.js

@@ -53,6 +53,28 @@ const toastStyles = `
     font-size: 15px;
     font-weight: 700;
     line-height: 1.35;
+    /* Long unbroken tokens (URLs, filenames) wrap instead of overflowing. */
+    overflow-wrap: anywhere;
+  }
+
+  /* Optional action affordance (e.g. "Undo") before the dismiss button.
+     Hidden — taking no flex gap — until content is assigned. */
+  [part="action"] {
+    display: inline-flex;
+    align-items: center;
+    flex: none;
+  }
+
+  [part="action"]:not(.has-content) {
+    display: none;
+  }
+
+  [part="action"]::slotted(*) {
+    font: inherit;
+    font-size: 13px;
+    font-weight: 700;
+    color: var(--boe-token-surface-surface-brand, #0061d5);
+    cursor: pointer;
   }
 
   [part="dismiss"] {
@@ -88,13 +110,22 @@ const toastStyles = `
 `;
 export class BoxToastElement extends BaseElement {
     static get observedAttributes() {
-        return ["message", "open", "tone"];
+        return ["message", "open", "tone", "duration"];
     }
     openValue = false;
     timeoutId = null;
     toastEl;
     messageEl;
+    actionSlot;
     dismissEl;
+    /** Auto-dismiss delay in ms for the declarative `open` path. 0 = sticky. */
+    get duration() {
+        const raw = Number(this.getAttribute("duration"));
+        return Number.isFinite(raw) && raw >= 0 ? raw : 0;
+    }
+    set duration(value) {
+        this.setAttribute("duration", String(value));
+    }
     get open() {
         return this.openValue;
     }
@@ -110,11 +141,29 @@ export class BoxToastElement extends BaseElement {
         else {
             this.removeAttribute("open");
         }
+        if (nextOpen) {
+            // Declarative open (attribute/property) auto-dismisses per `duration`;
+            // show() reschedules afterwards with its own option when provided.
+            this.scheduleAutoDismiss(this.duration);
+        }
+        else if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
         this.dispatchEvent(new CustomEvent("open-changed", { bubbles: true, composed: true, detail: { open: nextOpen } }));
         if (this.isRendered) {
             this.update();
         }
     }
+    scheduleAutoDismiss(duration) {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        if (duration > 0) {
+            this.timeoutId = setTimeout(() => this.hide(), duration);
+        }
+    }
     get message() {
         return this.getAttribute("message") ?? "";
     }
@@ -147,16 +196,9 @@ export class BoxToastElement extends BaseElement {
             this.tone = options.tone;
         }
         this.open = true;
-        if (this.timeoutId) {
-            clearTimeout(this.timeoutId);
-            this.timeoutId = null;
-        }
-        const duration = options?.duration ?? 2500;
-        if (duration > 0) {
-            this.timeoutId = setTimeout(() => {
-                this.hide();
-            }, duration);
-        }
+        // options.duration wins; else a declarative `duration` attribute; else 2500.
+        const duration = options?.duration ?? (this.duration || 2500);
+        this.scheduleAutoDismiss(duration);
     }
     hide() {
         this.open = false;
@@ -169,11 +211,13 @@ export class BoxToastElement extends BaseElement {
       <style>${toastStyles}</style>
       <div part="toast" role="status" aria-live="polite">
         <span part="message"></span>
+        <slot name="action" part="action"></slot>
         <button type="button" part="dismiss">Dismiss</button>
       </div>
     `;
         this.toastEl = this.shadowRoot.querySelector('[part="toast"]');
         this.messageEl = this.shadowRoot.querySelector('[part="message"]');
+        this.actionSlot = this.shadowRoot.querySelector('slot[name="action"]');
         this.dismissEl = this.shadowRoot.querySelector('[part="dismiss"]');
     }
     setupListeners() {
@@ -181,6 +225,10 @@ export class BoxToastElement extends BaseElement {
             this.dispatchEvent(new CustomEvent("dismiss", { bubbles: true, composed: true }));
             this.hide();
         });
+        this.actionSlot.addEventListener("slotchange", () => {
+            const hasContent = this.actionSlot.assignedNodes({ flatten: true }).length > 0;
+            this.actionSlot.classList.toggle("has-content", hasContent);
+        });
     }
     update() {
         if (!this.toastEl) {

package/dist/components/forms/category-selector.d.ts

@@ -17,6 +17,12 @@ export declare class BoxCategorySelectorElement extends BaseElement {
     private lastOptionsJson;
     private hadFocus;
     private rootEl;
+    private moreOpen;
+    private positionCleanup;
+    private readonly onDocumentPointerDown;
+    /** Max inline categories before the rest collapse into a "More" menu (0 = no limit). */
+    get maxLinks(): number;
+    set maxLinks(value: number);
     get label(): string;
     set label(value: string);
     get options(): CategoryOption[];
@@ -25,9 +31,14 @@ export declare class BoxCategorySelectorElement extends BaseElement {
     set value(nextValue: string);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private selectableOptions;
+    private splitOptions;
     private select;
     private moveSelection;
     protected renderTemplate(): void;
+    private resolvedPlacement;
+    private openMore;
+    private closeMore;
+    disconnectedCallback(): void;
     protected setupListeners(): void;
     protected update(): void;
 }

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 —
@@ -69,12 +116,28 @@ const categorySelectorStyles = `
  */
 export class BoxCategorySelectorElement extends BaseElement {
     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 +179,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 +229,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 +380,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 +430,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();

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

@@ -7,7 +7,13 @@ export declare class BoxCheckboxElement extends FormAssociatedElement {
     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;