@unofficialbox/box-open-elements 0.13.0 → 0.15.0

package/dist/components/actions/toolbar.d.ts

@@ -0,0 +1,39 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * A row of independent controls, with the keyboard behaviour a toolbar owes.
+ *
+ * ```html
+ * <box-toolbar label="Document actions">
+ *   <button type="button">Share</button>
+ *   <button type="button">Download</button>
+ * </box-toolbar>
+ * ```
+ *
+ * The controls are yours — this contributes `role="toolbar"`, the accessible
+ * name, and roving tabindex, so the group is one tab stop and the arrow keys
+ * move within it.
+ *
+ * Not to be confused with `box-button-group`, which is a `radiogroup`: that one
+ * is for picking exactly one of a set, and its children answer to a shared
+ * value. A toolbar's controls are independent of each other.
+ */
+export declare class Toolbar extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private listenersBound;
+    private controlObserver;
+    /** Accessible name for the group, announced before its controls. */
+    get label(): string;
+    set label(next: string);
+    /** `horizontal` (default) or `vertical`; picks which arrow keys navigate. */
+    get orientation(): string;
+    set orientation(next: string);
+    /** The controls this toolbar is managing, in document order. */
+    get controls(): HTMLElement[];
+    /** Every focusable control, disabled ones included. */
+    private focusableElements;
+    disconnectedCallback(): void;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/components/actions/toolbar.js

@@ -0,0 +1,170 @@
+import { BaseElement } from "../../core/index.js";
+import { applyRovingTabindex, handleRovingKeydown } from "../../foundations/a11y/index.js";
+import { boePanel } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-toolbar";
+const ORIENTATIONS = new Set(["horizontal", "vertical"]);
+/**
+ * Controls a toolbar will manage. Deliberately the natively focusable ones:
+ * roving tabindex works by moving `tabindex` between elements, which only
+ * focuses what the browser already considers focusable. A custom element host
+ * is not focusable unless it says so, so wrapping one in a toolbar requires it
+ * to carry its own `tabindex`.
+ */
+const FOCUSABLE = "button, a[href], input, select, textarea, [tabindex]";
+const toolbarStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="toolbar"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: ${boePanel.gap};
+  }
+
+  :host([orientation="vertical"]) [part="toolbar"] {
+    flex-direction: column;
+    align-items: stretch;
+    flex-wrap: nowrap;
+  }
+`;
+/**
+ * A row of independent controls, with the keyboard behaviour a toolbar owes.
+ *
+ * ```html
+ * <box-toolbar label="Document actions">
+ *   <button type="button">Share</button>
+ *   <button type="button">Download</button>
+ * </box-toolbar>
+ * ```
+ *
+ * The controls are yours — this contributes `role="toolbar"`, the accessible
+ * name, and roving tabindex, so the group is one tab stop and the arrow keys
+ * move within it.
+ *
+ * Not to be confused with `box-button-group`, which is a `radiogroup`: that one
+ * is for picking exactly one of a set, and its children answer to a shared
+ * value. A toolbar's controls are independent of each other.
+ */
+export class Toolbar extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["label", "orientation"];
+    }
+    listenersBound = false;
+    controlObserver = null;
+    /** Accessible name for the group, announced before its controls. */
+    get label() {
+        return this.getAttribute("label") ?? "";
+    }
+    set label(next) {
+        this.setAttribute("label", next);
+    }
+    /** `horizontal` (default) or `vertical`; picks which arrow keys navigate. */
+    get orientation() {
+        const raw = this.getAttribute("orientation");
+        return raw && ORIENTATIONS.has(raw) ? raw : "horizontal";
+    }
+    set orientation(next) {
+        this.setAttribute("orientation", next);
+    }
+    /** The controls this toolbar is managing, in document order. */
+    get controls() {
+        return this.focusableElements().filter(element => !element.hasAttribute("disabled"));
+    }
+    /** Every focusable control, disabled ones included. */
+    focusableElements() {
+        const slot = this.shadowRoot?.querySelector("slot");
+        if (!slot) {
+            return [];
+        }
+        return slot
+            .assignedElements()
+            .flatMap(element => element.matches(FOCUSABLE)
+            ? [element]
+            : Array.from(element.querySelectorAll(FOCUSABLE)));
+    }
+    disconnectedCallback() {
+        this.controlObserver?.disconnect();
+        this.controlObserver = null;
+        this.listenersBound = false;
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${toolbarStyles}</style>
+      <div part="toolbar" role="toolbar"><slot></slot></div>
+    `;
+        this.listenersBound = false;
+    }
+    setupListeners() {
+        if (!this.shadowRoot || this.listenersBound) {
+            return;
+        }
+        this.listenersBound = true;
+        // A toolbar's controls are the host's children, so the set changes without
+        // this element re-rendering. Without this the tab stops describe whatever
+        // was there when it first rendered.
+        this.shadowRoot.querySelector("slot")?.addEventListener("slotchange", () => {
+            this.update();
+        });
+        // `slotchange` covers assigned children being swapped, but not a control
+        // deep in a wrapper, and not `disabled` toggling — the two ways a host
+        // routinely changes which controls are live.
+        this.controlObserver ??= new MutationObserver(() => {
+            this.update();
+        });
+        this.controlObserver.observe(this, {
+            attributeFilter: ["disabled"],
+            attributes: true,
+            childList: true,
+            subtree: true,
+        });
+        this.shadowRoot.querySelector('[part="toolbar"]')?.addEventListener("keydown", event => {
+            handleRovingKeydown(event, this.controls, {
+                orientation: this.orientation,
+            });
+        });
+        // Clicking a control makes it the tab stop, so returning by Tab lands where
+        // the reader last was rather than back at the first control.
+        this.addEventListener("focusin", event => {
+            const index = this.controls.indexOf(event.target);
+            if (index >= 0) {
+                applyRovingTabindex(this.controls, index);
+            }
+        });
+    }
+    update() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const toolbar = this.shadowRoot.querySelector('[part="toolbar"]');
+        toolbar?.setAttribute("aria-orientation", this.orientation);
+        if (this.label) {
+            toolbar?.setAttribute("aria-label", this.label);
+        }
+        else {
+            toolbar?.removeAttribute("aria-label");
+        }
+        const controls = this.controls;
+        // Keep whichever control already holds the tab stop, so a re-render for an
+        // unrelated reason does not send focus back to the start.
+        const active = controls.findIndex(control => control.tabIndex === 0);
+        // Disabled controls are excluded from the rotation, so roving tabindex
+        // never touches them — and a button's default tabIndex is 0. Left alone,
+        // one re-enabled at runtime (which is the norm: a Clear Selection that
+        // wakes when something is selected) becomes a second tab stop the arrow
+        // keys cannot reach. Claim every focusable control first, then hand the
+        // stop to one.
+        for (const element of this.focusableElements()) {
+            element.tabIndex = -1;
+        }
+        applyRovingTabindex(controls, active >= 0 ? active : 0);
+    }
+}
+Toolbar.register();

package/dist/components/output/formatted-number.d.ts

@@ -28,9 +28,25 @@ export declare class FormattedNumber extends FormattedValue {
     /** ISO 4217 code, required by `Intl` when the style is `currency`. */
     get currency(): string;
     set currency(next: string);
-    /** A sanctioned unit identifier, e.g. `megabyte`, when the style is `unit`. */
+    /**
+     * A sanctioned unit identifier, e.g. `megabyte`, when the style is `unit`.
+     *
+     * `Intl` accepts a closed list and throws on anything else, so this is not a
+     * free-text label — "widgets" will not work, and the component falls back to
+     * a plain number rather than losing the value over it.
+     */
     get unit(): string;
     set unit(next: string);
+    /**
+     * How wide to write the unit: `short` (2.5 MB), `narrow` (2.5MB) or `long`
+     * (2.5 megabytes).
+     *
+     * `Intl` defaults to `short`, which is what a table wants. `long` is for
+     * prose, where an abbreviation a reader has to expand in their head is worse
+     * than the words.
+     */
+    get unitDisplay(): string;
+    set unitDisplay(next: string);
     protected formatted(): {
         text: string;
     } | null;

package/dist/components/output/formatted-number.js

@@ -2,6 +2,7 @@ import { FormattedValue } from "./formatted-value.js";
 import { parseNumber } from "../../foundations/format/index.js";
 const DEFAULT_TAG_NAME = "box-formatted-number";
 const NUMBER_STYLES = new Set(["decimal", "currency", "percent", "unit"]);
+const UNIT_DISPLAYS = new Set(["short", "narrow", "long"]);
 /**
  * A number, rendered in the reader's locale.
  *
@@ -29,6 +30,7 @@ export class FormattedNumber extends FormattedValue {
             "maximum-fraction-digits",
             "minimum-fraction-digits",
             "unit",
+            "unit-display",
             "value",
         ];
     }
@@ -54,13 +56,34 @@ export class FormattedNumber extends FormattedValue {
     set currency(next) {
         this.setAttribute("currency", next);
     }
-    /** A sanctioned unit identifier, e.g. `megabyte`, when the style is `unit`. */
+    /**
+     * A sanctioned unit identifier, e.g. `megabyte`, when the style is `unit`.
+     *
+     * `Intl` accepts a closed list and throws on anything else, so this is not a
+     * free-text label — "widgets" will not work, and the component falls back to
+     * a plain number rather than losing the value over it.
+     */
     get unit() {
         return this.getAttribute("unit") ?? "";
     }
     set unit(next) {
         this.setAttribute("unit", next);
     }
+    /**
+     * How wide to write the unit: `short` (2.5 MB), `narrow` (2.5MB) or `long`
+     * (2.5 megabytes).
+     *
+     * `Intl` defaults to `short`, which is what a table wants. `long` is for
+     * prose, where an abbreviation a reader has to expand in their head is worse
+     * than the words.
+     */
+    get unitDisplay() {
+        const raw = this.getAttribute("unit-display");
+        return raw && UNIT_DISPLAYS.has(raw) ? raw : "short";
+    }
+    set unitDisplay(next) {
+        this.setAttribute("unit-display", next);
+    }
     formatted() {
         const numeric = parseNumber(this.value);
         if (numeric === null) {
@@ -83,6 +106,7 @@ export class FormattedNumber extends FormattedValue {
             }
             else {
                 options.unit = this.unit;
+                options.unitDisplay = this.unitDisplay;
             }
         }
         const min = parseNumber(this.getAttribute("minimum-fraction-digits"));

package/dist/entries/toolbar.d.ts

@@ -0,0 +1 @@
+export * from "../components/actions/toolbar.js";

package/dist/entries/toolbar.js

@@ -0,0 +1 @@
+export * from "../components/actions/toolbar.js";

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./components/actions/link-button.js";
 export * from "./components/actions/menu.js";
 export * from "./components/actions/segmented-control.js";
 export * from "./components/actions/menu-item.js";
+export * from "./components/actions/toolbar.js";
 export * from "./components/collections/card.js";
 export * from "./components/collections/carousel.js";
 export * from "./components/collections/datalist-item.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./components/actions/link-button.js";
 export * from "./components/actions/menu.js";
 export * from "./components/actions/segmented-control.js";
 export * from "./components/actions/menu-item.js";
+export * from "./components/actions/toolbar.js";
 // Components: collections
 export * from "./components/collections/card.js";
 export * from "./components/collections/carousel.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",