@unofficialbox/box-open-elements 0.14.0 → 0.16.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-duration.d.ts

@@ -0,0 +1,55 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * How long something takes or lasts, in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-duration value="5400"></box-formatted-duration>
+ * ```
+ *
+ * `value` is a count of seconds or an ISO 8601 duration (`PT1H30M`), because
+ * hosts have both: an API field is usually a number, while `<time datetime>`
+ * wants the ISO form. Whichever comes in, the ISO form goes back out in
+ * `datetime`, so the exact quantity survives for anything reading the document
+ * rather than looking at it.
+ *
+ * Not to be confused with `box-relative-time`, which renders *when* something
+ * happened relative to now ("3 days ago"). This renders *how long* — a
+ * retention period, an SLA, a processing time — and carries no direction.
+ *
+ * `Intl.DurationFormat` does the rendering where the browser has it. Where it
+ * does not, the same output is composed from `Intl.NumberFormat`'s unit style
+ * and `Intl.ListFormat`, both long supported; the two paths were compared
+ * across styles and locales and agree.
+ */
+export declare class FormattedDuration extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    /** Seconds, or an ISO 8601 duration such as `PT1H30M`. */
+    get value(): string;
+    set value(next: string);
+    /**
+     * `short` (default, `1 hr, 30 min`), `long` (`1 hour, 30 minutes`) or
+     * `narrow` (`1h 30m`).
+     *
+     * Named `format-style` rather than `style` because `style` is a global HTML
+     * attribute: naming it after the `Intl` option would put CSS on the host and
+     * be silently ignored as a formatting instruction.
+     */
+    get formatStyle(): string;
+    set formatStyle(next: string);
+    /**
+     * How many units to show, default 2.
+     *
+     * A duration carries more precision than a reader wants: 1 day, 3 hours, 12
+     * minutes and 8 seconds is a number to scan past, not to read. Two units is
+     * enough to convey magnitude.
+     */
+    get maxUnits(): number;
+    set maxUnits(next: number);
+    protected usesTimeElement(): boolean;
+    protected formatted(): {
+        machine?: string;
+        text: string;
+    } | null;
+    private render;
+}

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

@@ -0,0 +1,131 @@
+import { FormattedValue } from "./formatted-value.js";
+import { parseDuration, resolveDurationParts, toIsoDuration, } from "../../foundations/format/index.js";
+const DEFAULT_TAG_NAME = "box-formatted-duration";
+/** Whether the split came out as a plain zero, which `Intl` renders as nothing. */
+const isZero = (parts) => Object.values(parts).every(amount => amount === 0);
+const DURATION_STYLES = new Set(["long", "short", "narrow"]);
+/** `Intl` names duration fields in the plural; the parts are singular. */
+const INTL_FIELD = {
+    day: "days",
+    hour: "hours",
+    minute: "minutes",
+    second: "seconds",
+};
+/** The unit identifiers `Intl.NumberFormat` uses, for the fallback path. */
+const NUMBER_UNIT = {
+    day: "day",
+    hour: "hour",
+    minute: "minute",
+    second: "second",
+};
+/**
+ * How long something takes or lasts, in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-duration value="5400"></box-formatted-duration>
+ * ```
+ *
+ * `value` is a count of seconds or an ISO 8601 duration (`PT1H30M`), because
+ * hosts have both: an API field is usually a number, while `<time datetime>`
+ * wants the ISO form. Whichever comes in, the ISO form goes back out in
+ * `datetime`, so the exact quantity survives for anything reading the document
+ * rather than looking at it.
+ *
+ * Not to be confused with `box-relative-time`, which renders *when* something
+ * happened relative to now ("3 days ago"). This renders *how long* — a
+ * retention period, an SLA, a processing time — and carries no direction.
+ *
+ * `Intl.DurationFormat` does the rendering where the browser has it. Where it
+ * does not, the same output is composed from `Intl.NumberFormat`'s unit style
+ * and `Intl.ListFormat`, both long supported; the two paths were compared
+ * across styles and locales and agree.
+ */
+export class FormattedDuration extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["format-style", "locale", "max-units", "value"];
+    }
+    /** Seconds, or an ISO 8601 duration such as `PT1H30M`. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /**
+     * `short` (default, `1 hr, 30 min`), `long` (`1 hour, 30 minutes`) or
+     * `narrow` (`1h 30m`).
+     *
+     * Named `format-style` rather than `style` because `style` is a global HTML
+     * attribute: naming it after the `Intl` option would put CSS on the host and
+     * be silently ignored as a formatting instruction.
+     */
+    get formatStyle() {
+        const raw = this.getAttribute("format-style");
+        return raw && DURATION_STYLES.has(raw) ? raw : "short";
+    }
+    set formatStyle(next) {
+        this.setAttribute("format-style", next);
+    }
+    /**
+     * How many units to show, default 2.
+     *
+     * A duration carries more precision than a reader wants: 1 day, 3 hours, 12
+     * minutes and 8 seconds is a number to scan past, not to read. Two units is
+     * enough to convey magnitude.
+     */
+    get maxUnits() {
+        const raw = Number(this.getAttribute("max-units"));
+        return Number.isFinite(raw) && raw >= 1 ? Math.trunc(raw) : 2;
+    }
+    set maxUnits(next) {
+        this.setAttribute("max-units", String(next));
+    }
+    usesTimeElement() {
+        // A duration is a valid `datetime` value, so `<time>` is honest here.
+        return true;
+    }
+    formatted() {
+        const seconds = parseDuration(this.value);
+        if (seconds === null) {
+            return null;
+        }
+        const parts = resolveDurationParts(seconds, this.maxUnits);
+        const machine = toIsoDuration(parts);
+        const style = this.formatStyle;
+        try {
+            return { machine, text: this.render(parts, style) };
+        }
+        catch {
+            // A locale Intl rejects, or a runtime missing both paths. The duration is
+            // real, so fall back to the machine form rather than losing it.
+            return { machine, text: machine };
+        }
+    }
+    render(parts, style) {
+        const durationFormat = Intl.DurationFormat;
+        if (durationFormat) {
+            const input = Object.fromEntries(Object.entries(parts).map(([unit, amount]) => [INTL_FIELD[unit], amount]));
+            // A zero duration otherwise formats to the empty string, leaving a visible
+            // element with no text in it — zero is a real answer. Scoped to that case:
+            // asking for it always appends "0 sec" to every other duration in
+            // browsers that honour the option, which Node's Intl quietly does not.
+            const options = isZero(parts)
+                ? { secondsDisplay: "always", style }
+                : { style };
+            return new durationFormat(this.locale, options).format(input);
+        }
+        const unitDisplay = style === "long" ? "long" : style === "narrow" ? "narrow" : "short";
+        const pieces = Object.entries(parts).map(([unit, amount]) => new Intl.NumberFormat(this.locale, {
+            style: "unit",
+            unit: NUMBER_UNIT[unit],
+            unitDisplay,
+        }).format(amount));
+        // `narrow` runs the units together (`1h 30m`); the wider styles take the
+        // locale's own unit-list joiner, which is what DurationFormat uses too.
+        return style === "narrow"
+            ? pieces.join(" ")
+            : new Intl.ListFormat(this.locale, { style: "long", type: "unit" }).format(pieces);
+    }
+}
+FormattedDuration.register();

package/dist/entries/formatted-duration.d.ts

@@ -0,0 +1 @@
+export * from "../components/output/formatted-duration.js";

package/dist/entries/formatted-duration.js

@@ -0,0 +1 @@
+export * from "../components/output/formatted-duration.js";

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/foundations/format/format.d.ts

@@ -80,3 +80,37 @@ export interface BoeFileSizeParts {
  * is reported whole.
  */
 export declare const resolveFileSizeParts: (bytes: number, units?: BoeByteUnits) => BoeFileSizeParts;
+/** The duration units a formatted duration can be broken into, largest first. */
+export type BoeDurationUnit = "day" | "hour" | "minute" | "second";
+/** A duration split into whole units, ready for `Intl` to render. */
+export type BoeDurationParts = Partial<Record<BoeDurationUnit, number>>;
+/**
+ * Parse a duration to whole seconds.
+ *
+ * Accepts a count of seconds (a number, or a numeric string) or an ISO 8601
+ * duration such as `PT1H30M`, because hosts have both: an API field is usually
+ * a number, while `<time datetime>` wants the ISO form. Weeks, months and years
+ * are deliberately not accepted — `P1M` is ambiguous between a month and a
+ * minute in the calendar sense, and a month is not a fixed number of seconds,
+ * so rendering one as though it were would be a lie about how long the duration
+ * actually is.
+ *
+ * Negative and unparseable input is `null`. A duration is an elapsed quantity,
+ * so a negative one is a host bug rather than a direction — `box-relative-time`
+ * is the component that expresses "ago".
+ */
+export declare const parseDuration: (value: string | number | null | undefined) => number | null;
+/**
+ * Split whole seconds into at most `maxUnits` consecutive units.
+ *
+ * Consecutive, not merely the largest: 90061 seconds is "1 day, 1 hour" rather
+ * than "1 day, 1 minute", because a reader scanning a duration wants its
+ * magnitude, and skipping an empty unit to reach a smaller non-empty one
+ * overstates the precision.
+ *
+ * A duration of zero returns whole seconds rather than nothing, so "0 sec"
+ * renders instead of the element disappearing — zero is a real answer.
+ */
+export declare const resolveDurationParts: (totalSeconds: number, maxUnits?: number) => BoeDurationParts;
+/** Render a parts object back to an ISO 8601 duration, for `<time datetime>`. */
+export declare const toIsoDuration: (parts: BoeDurationParts) => string;

package/dist/foundations/format/format.js

@@ -120,3 +120,102 @@ export const resolveFileSizeParts = (bytes, units = "decimal") => {
     const exponent = Math.min(Math.floor(Math.log(magnitude) / Math.log(base)), suffixes.length - 1);
     return { suffix: suffixes[exponent], value: bytes / base ** exponent };
 };
+const ISO_DURATION = /^P(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+const SECONDS_PER = {
+    day: 86_400,
+    hour: 3_600,
+    minute: 60,
+    second: 1,
+};
+const DURATION_ORDER = ["day", "hour", "minute", "second"];
+/**
+ * Parse a duration to whole seconds.
+ *
+ * Accepts a count of seconds (a number, or a numeric string) or an ISO 8601
+ * duration such as `PT1H30M`, because hosts have both: an API field is usually
+ * a number, while `<time datetime>` wants the ISO form. Weeks, months and years
+ * are deliberately not accepted — `P1M` is ambiguous between a month and a
+ * minute in the calendar sense, and a month is not a fixed number of seconds,
+ * so rendering one as though it were would be a lie about how long the duration
+ * actually is.
+ *
+ * Negative and unparseable input is `null`. A duration is an elapsed quantity,
+ * so a negative one is a host bug rather than a direction — `box-relative-time`
+ * is the component that expresses "ago".
+ */
+export const parseDuration = (value) => {
+    if (value == null || value === "") {
+        return null;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value >= 0 ? Math.round(value) : null;
+    }
+    const trimmed = value.trim();
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        return Math.round(Number(trimmed));
+    }
+    const match = ISO_DURATION.exec(trimmed);
+    if (!match || trimmed === "P" || trimmed === "PT") {
+        return null;
+    }
+    const [, days, hours, minutes, seconds] = match;
+    const total = Number(days ?? 0) * SECONDS_PER.day +
+        Number(hours ?? 0) * SECONDS_PER.hour +
+        Number(minutes ?? 0) * SECONDS_PER.minute +
+        Number(seconds ?? 0);
+    return Number.isFinite(total) ? Math.round(total) : null;
+};
+/**
+ * Split whole seconds into at most `maxUnits` consecutive units.
+ *
+ * Consecutive, not merely the largest: 90061 seconds is "1 day, 1 hour" rather
+ * than "1 day, 1 minute", because a reader scanning a duration wants its
+ * magnitude, and skipping an empty unit to reach a smaller non-empty one
+ * overstates the precision.
+ *
+ * A duration of zero returns whole seconds rather than nothing, so "0 sec"
+ * renders instead of the element disappearing — zero is a real answer.
+ */
+export const resolveDurationParts = (totalSeconds, maxUnits = 2) => {
+    const limit = Math.max(1, Math.trunc(maxUnits));
+    if (totalSeconds <= 0) {
+        return { second: 0 };
+    }
+    const collected = [];
+    let remaining = Math.round(totalSeconds);
+    let started = false;
+    for (const unit of DURATION_ORDER) {
+        const size = SECONDS_PER[unit];
+        const amount = Math.floor(remaining / size);
+        if (!started && amount === 0) {
+            continue;
+        }
+        started = true;
+        collected.push([unit, amount]);
+        remaining -= amount * size;
+        if (collected.length === limit) {
+            break;
+        }
+    }
+    // Trailing zeroes are noise: an exact hour is "1 hr", not "1 hr, 0 min". Only
+    // trailing ones go — an interior zero is load-bearing, since "1 day, 0 hr" as
+    // the first two units of 1d 0h 5m would otherwise become "1 day, 5 min" and
+    // claim a precision the split does not have.
+    while (collected.length > 1 && collected[collected.length - 1][1] === 0) {
+        collected.pop();
+    }
+    return Object.fromEntries(collected);
+};
+/** Render a parts object back to an ISO 8601 duration, for `<time datetime>`. */
+export const toIsoDuration = (parts) => {
+    const date = parts.day ? `${parts.day}D` : "";
+    const time = [
+        parts.hour ? `${parts.hour}H` : "",
+        parts.minute ? `${parts.minute}M` : "",
+        parts.second ? `${parts.second}S` : "",
+    ].join("");
+    if (!date && !time) {
+        return "PT0S";
+    }
+    return `P${date}${time ? `T${time}` : ""}`;
+};

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";
@@ -88,6 +89,7 @@ export * from "./components/output/code-block.js";
 export * from "./components/output/formatted-date.js";
 export * from "./components/output/relative-time.js";
 export * from "./components/output/formatted-number.js";
+export * from "./components/output/formatted-duration.js";
 export * from "./components/output/formatted-file-size.js";
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.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";
@@ -96,6 +97,7 @@ export * from "./components/output/code-block.js";
 export * from "./components/output/formatted-date.js";
 export * from "./components/output/relative-time.js";
 export * from "./components/output/formatted-number.js";
+export * from "./components/output/formatted-duration.js";
 export * from "./components/output/formatted-file-size.js";
 // Components: layout
 export * from "./components/layout/app-shell.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.14.0",
+  "version": "0.16.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",