@unofficialbox/box-open-elements 0.2.1 → 0.3.0

package/dist/components/forms/select.js

@@ -1,4 +1,4 @@
-import { FormAssociatedElement, boeFormFieldErrorStyles, formErrorMessageMarkup, } from "../../core/index.js";
+import { FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDescriptionMarkup, formErrorMessageMarkup, } from "../../core/index.js";
 import { boeControl, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-select";
 const escapeHtml = (value) => value
@@ -64,11 +64,12 @@ const selectStyles = `
   }
 
   ${boeFormFieldErrorStyles}
+  ${boeFormFieldSupportStyles}
 `;
 export class BoxSelectElement extends FormAssociatedElement {
     static get observedAttributes() {
         return [
-            ...FormAssociatedElement.formObservedAttributes,
+            ...FormAssociatedElement.fieldObservedAttributes,
             "disabled",
             "label",
             "options",
@@ -78,6 +79,7 @@ export class BoxSelectElement extends FormAssociatedElement {
     valueInternal = "";
     selectEl;
     labelEl;
+    descriptionEl;
     errorEl;
     get value() {
         return this.valueInternal;
@@ -147,11 +149,13 @@ export class BoxSelectElement extends FormAssociatedElement {
       <style>${selectStyles}</style>
       <label part="field">
         <span part="label"></span>
+        ${formDescriptionMarkup()}
         <select part="select"></select>
         ${formErrorMessageMarkup()}
       </label>
     `;
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
+        this.descriptionEl = this.shadowRoot.querySelector('[part="description"]');
         this.selectEl = this.shadowRoot.querySelector('[part="select"]');
         this.errorEl = this.shadowRoot.querySelector('[part="error-message"]');
     }
@@ -185,6 +189,7 @@ export class BoxSelectElement extends FormAssociatedElement {
         else {
             this.selectEl.removeAttribute("disabled");
         }
+        this.applyFieldSupport(this.labelEl, this.selectEl, this.descriptionEl);
         this.applyInvalidState(this.selectEl, this.errorEl);
     }
 }

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

@@ -5,6 +5,7 @@ export declare class BoxTextFieldElement extends FormAssociatedElement {
     private valueInternal;
     private inputEl;
     private labelEl;
+    private descriptionEl;
     private errorEl;
     get value(): string;
     set value(nextValue: string);

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

@@ -1,4 +1,4 @@
-import { FormAssociatedElement, boeFormFieldErrorStyles, formErrorMessageMarkup, } from "../../core/index.js";
+import { FormAssociatedElement, boeFormFieldErrorStyles, boeFormFieldSupportStyles, formDescriptionMarkup, formErrorMessageMarkup, } from "../../core/index.js";
 import { boeControl, boeInputControlStyles, boeSpace } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-text-field";
 /** Input chrome tracks BUE `@mixin box-inputs` (`src/styles/_inputs.scss`). */
@@ -34,11 +34,12 @@ const textFieldStyles = `
   }
 
   ${boeFormFieldErrorStyles}
+  ${boeFormFieldSupportStyles}
 `;
 export class BoxTextFieldElement extends FormAssociatedElement {
     static get observedAttributes() {
         return [
-            ...FormAssociatedElement.formObservedAttributes,
+            ...FormAssociatedElement.fieldObservedAttributes,
             "disabled",
             "label",
             "placeholder",
@@ -48,6 +49,7 @@ export class BoxTextFieldElement extends FormAssociatedElement {
     valueInternal = "";
     inputEl;
     labelEl;
+    descriptionEl;
     errorEl;
     get value() {
         return this.valueInternal;
@@ -102,11 +104,13 @@ export class BoxTextFieldElement extends FormAssociatedElement {
       <style>${textFieldStyles}</style>
       <label part="field">
         <span part="label"></span>
+        ${formDescriptionMarkup()}
         <input type="text" part="input" />
         ${formErrorMessageMarkup()}
       </label>
     `;
         this.labelEl = this.shadowRoot.querySelector('[part="label"]');
+        this.descriptionEl = this.shadowRoot.querySelector('[part="description"]');
         this.inputEl = this.shadowRoot.querySelector('[part="input"]');
         this.errorEl = this.shadowRoot.querySelector('[part="error-message"]');
     }
@@ -138,6 +142,8 @@ export class BoxTextFieldElement extends FormAssociatedElement {
         else {
             this.inputEl.removeAttribute("disabled");
         }
+        // After the label text is (re)set, since it clears the required mark.
+        this.applyFieldSupport(this.labelEl, this.inputEl, this.descriptionEl);
         this.applyInvalidState(this.inputEl, this.errorEl);
     }
 }

package/dist/components/navigation/breadcrumb.d.ts

@@ -0,0 +1,30 @@
+import { BaseElement } from "../../core/index.js";
+export interface BreadcrumbItem {
+    label: string;
+    /** Optional link target. Omit for a purely JS-driven crumb. */
+    href?: string;
+    /** Value reported on `navigate`; defaults to `href` or `label`. */
+    value?: string;
+}
+/**
+ * File-path breadcrumb trail with overflow collapse — box-ui-elements
+ * `Breadcrumb`. When the trail is longer than `max-items` the middle crumbs
+ * collapse into an ellipsis, always keeping the first crumb and the last two.
+ */
+export declare class BoxBreadcrumbElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private listEl;
+    get items(): BreadcrumbItem[];
+    set items(value: BreadcrumbItem[]);
+    get label(): string;
+    set label(value: string);
+    /** Max crumbs shown before the middle collapses to an ellipsis. 0 disables collapse. */
+    get maxItems(): number;
+    set maxItems(value: number);
+    /** Keep the first crumb + last two, collapsing the middle into an ellipsis. */
+    private collapse;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}
+export declare const defineBoxBreadcrumbElement: (tagName?: string) => typeof BoxBreadcrumbElement;

package/dist/components/navigation/breadcrumb.js

@@ -0,0 +1,190 @@
+import { BaseElement } from "../../core/index.js";
+import { boeRadius, boeSpace } from "../../foundations/geometry/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+const DEFAULT_TAG_NAME = "box-breadcrumb";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+const breadcrumbStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="list"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: ${boeSpace[1]};
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    font-size: 13px;
+  }
+
+  [part="crumb"] {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  [part="link"] {
+    appearance: none;
+    border: none;
+    background: none;
+    font: inherit;
+    padding: 2px 6px;
+    border-radius: ${boeRadius.med};
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    text-decoration: none;
+    cursor: pointer;
+    max-width: 22ch;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    transition:
+      color ${boeMotionDuration.interactive} ${boeMotionEasing.standard},
+      background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+  }
+
+  [part="link"]:hover {
+    color: var(--boe-token-text-text, #222222);
+    background: var(--boe-token-surface-surface-secondary, #f4f4f4);
+  }
+
+  [part="link"]:focus-visible {
+    outline: 2px solid var(--boe-token-surface-surface-brand, #0061d5);
+    outline-offset: 1px;
+  }
+
+  [part="link"][aria-current="page"] {
+    color: var(--boe-token-text-text, #222222);
+    font-weight: 600;
+    cursor: default;
+  }
+
+  [part="separator"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    user-select: none;
+  }
+
+  [part="ellipsis"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    padding: 0 2px;
+  }
+`;
+/** A collapsed marker inserted when the trail exceeds `max-items`. */
+const ELLIPSIS = Symbol("ellipsis");
+/**
+ * File-path breadcrumb trail with overflow collapse — box-ui-elements
+ * `Breadcrumb`. When the trail is longer than `max-items` the middle crumbs
+ * collapse into an ellipsis, always keeping the first crumb and the last two.
+ */
+export class BoxBreadcrumbElement extends BaseElement {
+    static get observedAttributes() {
+        return ["items", "label", "max-items"];
+    }
+    listEl;
+    get items() {
+        const raw = this.getAttribute("items");
+        if (!raw) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set items(value) {
+        this.setAttribute("items", JSON.stringify(value));
+    }
+    get label() {
+        return this.getAttribute("label") ?? "Breadcrumb";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    /** Max crumbs shown before the middle collapses to an ellipsis. 0 disables collapse. */
+    get maxItems() {
+        const raw = Number(this.getAttribute("max-items"));
+        return Number.isFinite(raw) && raw > 0 ? raw : 4;
+    }
+    set maxItems(value) {
+        this.setAttribute("max-items", String(value));
+    }
+    /** Keep the first crumb + last two, collapsing the middle into an ellipsis. */
+    collapse(items) {
+        const max = this.maxItems;
+        if (items.length <= max) {
+            return items;
+        }
+        return [items[0], ELLIPSIS, ...items.slice(-2)];
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${breadcrumbStyles}</style>
+      <nav part="nav">
+        <ol part="list"></ol>
+      </nav>
+    `;
+        this.listEl = this.shadowRoot.querySelector('[part="list"]');
+    }
+    setupListeners() {
+        this.listEl.addEventListener("click", event => {
+            const link = event.target.closest('[part="link"]');
+            if (!link || link.getAttribute("aria-current") === "page") {
+                return;
+            }
+            const value = link.dataset.value ?? "";
+            const href = link.getAttribute("href") ?? undefined;
+            // JS-only crumbs (no href) shouldn't navigate the browser.
+            if (!href) {
+                event.preventDefault();
+            }
+            this.dispatchEvent(new CustomEvent("navigate", {
+                bubbles: true,
+                composed: true,
+                detail: { value, href },
+            }));
+        });
+    }
+    update() {
+        if (!this.listEl) {
+            return;
+        }
+        this.shadowRoot?.querySelector('[part="nav"]')?.setAttribute("aria-label", this.label);
+        const crumbs = this.collapse(this.items);
+        const lastIndex = crumbs.length - 1;
+        this.listEl.innerHTML = crumbs
+            .map((crumb, index) => {
+            const separator = index < lastIndex ? `<span part="separator" aria-hidden="true">/</span>` : "";
+            if (crumb === ELLIPSIS) {
+                return `<li part="crumb"><span part="ellipsis" aria-label="Hidden path">…</span>${separator}</li>`;
+            }
+            const isLast = index === lastIndex;
+            const value = escapeHtml(crumb.value ?? crumb.href ?? crumb.label);
+            const tag = crumb.href && !isLast ? "a" : "button";
+            const hrefAttr = crumb.href && !isLast ? ` href="${escapeHtml(crumb.href)}"` : "";
+            const typeAttr = tag === "button" ? ' type="button"' : "";
+            const current = isLast ? ' aria-current="page"' : "";
+            return `<li part="crumb"><${tag} part="link" data-value="${value}"${hrefAttr}${typeAttr}${current}>${escapeHtml(crumb.label)}</${tag}>${separator}</li>`;
+        })
+            .join("");
+    }
+}
+export const defineBoxBreadcrumbElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxBreadcrumbElement);
+    return BoxBreadcrumbElement;
+};

package/dist/components/navigation/tabs.d.ts

@@ -8,6 +8,8 @@ export declare class BoxTabsElement extends BaseElement {
     private valueInternal;
     private lastOptionsJson;
     private tabsEl;
+    private panelsEl;
+    private readonly uid;
     get label(): string;
     set label(value: string);
     get layout(): "attached" | "separated";
@@ -19,6 +21,8 @@ export declare class BoxTabsElement extends BaseElement {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     private selectValue;
     private renderTabsMarkup;
+    /** One tabpanel per option, fed by a slot named for the option value. */
+    private renderPanelsMarkup;
     protected renderTemplate(): void;
     protected setupListeners(): void;
     protected update(): void;

package/dist/components/navigation/tabs.js

@@ -1,5 +1,5 @@
 import { BaseElement } from "../../core/index.js";
-import { boeControl, boeSpace } from "../../foundations/geometry/index.js";
+import { boeControl, boeRadius, boeSpace } from "../../foundations/geometry/index.js";
 import { boeFocusVisibleStyles, } from "../../foundations/tokens/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 const DEFAULT_TAG_NAME = "box-tabs";
@@ -88,6 +88,22 @@ const tabsStyles = `
     outline-offset: -2px;
     box-shadow: none;
   }
+
+  /* Panels carry no default padding — an empty panel is zero-height, and
+     consumers style their own slotted content. */
+  [part="panel"] {
+    outline: none;
+  }
+
+  [part="panel"][hidden] {
+    display: none;
+  }
+
+  [part="panel"]:focus-visible {
+    outline: 2px solid var(--boe-token-surface-surface-brand, #0061d5);
+    outline-offset: 2px;
+    border-radius: ${boeRadius.med};
+  }
 `;
 export class BoxTabsElement extends BaseElement {
     static get observedAttributes() {
@@ -96,6 +112,8 @@ export class BoxTabsElement extends BaseElement {
     valueInternal = "";
     lastOptionsJson = "";
     tabsEl;
+    panelsEl;
+    uid = `boe-tabs-${Math.random().toString(36).slice(2, 8)}`;
     get label() {
         return this.getAttribute("label") ?? "Tabs";
     }
@@ -169,17 +187,21 @@ export class BoxTabsElement extends BaseElement {
                     : index === options.length - 1
                         ? "last"
                         : "middle";
+            const selected = option.value === selectedValue;
+            const value = escapeHtml(option.value);
             return `
           <button
             type="button"
             part="tab"
             role="tab"
+            id="${this.uid}-tab-${value}"
+            aria-controls="${this.uid}-panel-${value}"
             data-layout="${this.layout}"
             data-position="${position}"
-            data-selected="${String(option.value === selectedValue)}"
-            data-value="${escapeHtml(option.value)}"
-            aria-selected="${String(option.value === selectedValue)}"
-            tabindex="${option.value === selectedValue ? "0" : "-1"}"
+            data-selected="${String(selected)}"
+            data-value="${value}"
+            aria-selected="${String(selected)}"
+            tabindex="${selected ? "0" : "-1"}"
           >
             ${escapeHtml(option.label)}
           </button>
@@ -187,6 +209,25 @@ export class BoxTabsElement extends BaseElement {
         })
             .join("");
     }
+    /** One tabpanel per option, fed by a slot named for the option value. */
+    renderPanelsMarkup(options, selectedValue) {
+        return options
+            .map(option => {
+            const value = escapeHtml(option.value);
+            const selected = option.value === selectedValue;
+            return `
+          <div
+            part="panel"
+            role="tabpanel"
+            id="${this.uid}-panel-${value}"
+            aria-labelledby="${this.uid}-tab-${value}"
+            tabindex="0"
+            ${selected ? "" : "hidden"}
+          ><slot name="${value}"></slot></div>
+        `;
+        })
+            .join("");
+    }
     renderTemplate() {
         if (!this.shadowRoot) {
             return;
@@ -194,8 +235,10 @@ export class BoxTabsElement extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${tabsStyles}</style>
       <div part="tabs" role="tablist"></div>
+      <div part="panels"></div>
     `;
         this.tabsEl = this.shadowRoot.querySelector('[part="tabs"]');
+        this.panelsEl = this.shadowRoot.querySelector('[part="panels"]');
     }
     setupListeners() {
         this.tabsEl.addEventListener("click", event => {
@@ -254,6 +297,7 @@ export class BoxTabsElement extends BaseElement {
         this.tabsEl.setAttribute("aria-label", this.label);
         if (optionsJson !== this.lastOptionsJson) {
             this.tabsEl.innerHTML = this.renderTabsMarkup(options, selectedValue);
+            this.panelsEl.innerHTML = this.renderPanelsMarkup(options, selectedValue);
             this.lastOptionsJson = optionsJson;
             return;
         }
@@ -277,6 +321,10 @@ export class BoxTabsElement extends BaseElement {
             tab.setAttribute("aria-selected", String(selected));
             tab.tabIndex = selected ? 0 : -1;
         });
+        // Show only the selected tab's panel.
+        this.panelsEl.querySelectorAll('[part="panel"]').forEach((panel, index) => {
+            panel.hidden = options[index]?.value !== selectedValue;
+        });
     }
 }
 export const defineBoxTabsElement = (tagName = DEFAULT_TAG_NAME) => {

package/dist/components/overlays/context-menu.d.ts

@@ -0,0 +1,42 @@
+import { BaseElement } from "../../core/index.js";
+export interface ContextMenuItem {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Render a divider *before* this item. */
+    separator?: boolean;
+}
+/**
+ * Right-click context menu — box-ui-elements `ContextMenu`. The default slot is
+ * the target area; right-clicking (or Shift+F10 / the ContextMenu key) opens a
+ * menu at the pointer, positioned with `foundations/overlay` so it stays in the
+ * viewport. Full keyboard menu: arrows, Home/End, Enter/Space, Escape.
+ */
+export declare class BoxContextMenuElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private openValue;
+    private targetEl;
+    private surfaceEl;
+    private readonly focusRestore;
+    private documentBound;
+    private readonly onOutside;
+    private readonly onReposition;
+    get items(): ContextMenuItem[];
+    set items(value: ContextMenuItem[]);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get open(): boolean;
+    disconnectedCallback(): void;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    private enabledItems;
+    private onMenuKeydown;
+    private openAt;
+    close(): void;
+    private selectItem;
+    private renderItems;
+    private bindDocument;
+    private unbindDocument;
+    protected update(): void;
+}
+export declare const defineBoxContextMenuElement: (tagName?: string) => typeof BoxContextMenuElement;