@unofficialbox/box-open-elements 0.11.0 → 0.13.0

package/dist/components/output/code-block.js

@@ -0,0 +1,236 @@
+import { BaseElement } from "../../core/index.js";
+import { boeRadius } from "../../foundations/geometry/index.js";
+import { boeFocusVisibleStyles } from "../../foundations/tokens/index.js";
+const DEFAULT_TAG_NAME = "box-code-block";
+const COPY_ICON = `<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" focusable="false"><rect x="5.5" y="5.5" width="8" height="8" rx="1.5"/><path d="M10.5 3.5v-1a1 1 0 00-1-1h-7a1 1 0 00-1 1v7a1 1 0 001 1h1"/></svg>`;
+const COPIED_ICON = `<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" focusable="false"><path d="M3 8.5l3.2 3.2L13 5"/></svg>`;
+/** How long the button stays in its confirmed state. */
+const COPIED_RESET_MS = 1600;
+const codeStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  [part="block"] {
+    position: relative;
+    border-radius: ${boeRadius.large};
+    background: var(--boe-token-surface-surface-secondary, #f4f4f4);
+    color: var(--boe-token-text-text, #222222);
+  }
+
+  [part="pre"] {
+    margin: 0;
+    padding: 0.85rem 3rem 0.85rem 0.95rem;
+    overflow-x: auto;
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+    font-size: 0.82rem;
+    line-height: 1.55;
+    /* Code is read as written: wrapping a long line silently changes what the
+       reader believes the source says, so it scrolls instead. The container is
+       what scrolls, never the page. */
+    white-space: pre;
+    tab-size: 2;
+  }
+
+  /* Opt-in wrapping for prose-like content — a long URL or a shell command that
+     has no meaningful column structure. */
+  :host([wrap]) [part="pre"] {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+
+  :host([inline]) {
+    display: inline-block;
+  }
+
+  :host([inline]) [part="pre"] {
+    padding: 0.1rem 0.4rem;
+  }
+
+  :host([inline]) [part="copy"] {
+    display: none;
+  }
+
+  [part="copy"] {
+    appearance: none;
+    position: absolute;
+    inset-block-start: 0.45rem;
+    inset-inline-end: 0.45rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1.75rem;
+    block-size: 1.75rem;
+    padding: 0.35rem;
+    border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+    border-radius: ${boeRadius.med};
+    background: var(--boe-token-surface-surface, #ffffff);
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    cursor: pointer;
+  }
+
+  [part="copy"] svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  [part="copy"]:hover:not(:disabled) {
+    background: var(--boe-token-surface-surface-hover, #f4f4f4);
+  }
+
+  [part="copy"][data-copied="true"] {
+    color: var(--boe-token-surface-status-surface-success, #26c281);
+  }
+
+  ${boeFocusVisibleStyles('[part="copy"]')}
+`;
+/**
+ * A block of code, rendered as written.
+ *
+ * ```html
+ * <box-code-block code="npm i @unofficialbox/box-open-elements"></box-code-block>
+ * ```
+ *
+ * The code is set as `textContent`, never as markup — a snippet is the most
+ * likely string on any page to contain angle brackets, and rendering it as HTML
+ * would both corrupt what the reader sees and hand an injection point to
+ * whatever produced the snippet.
+ *
+ * There is no syntax highlighting, deliberately. Doing it properly means
+ * shipping a grammar per language, and doing it improperly means mis-colouring
+ * code that a reader is trying to trust. A host that needs highlighting can
+ * slot pre-rendered markup into the default slot instead.
+ *
+ * Long lines scroll rather than wrap: a wrapped line silently changes what the
+ * reader believes the source says. `wrap` opts into wrapping where the content
+ * has no meaningful column structure.
+ */
+export class CodeBlock extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["code", "copy-label", "language"];
+    }
+    preEl;
+    codeEl;
+    copyEl;
+    slotEl;
+    resetTimer = null;
+    /** The source to render. */
+    get code() {
+        return this.getAttribute("code") ?? "";
+    }
+    set code(value) {
+        this.setAttribute("code", value);
+    }
+    /**
+     * The language, surfaced as a `data-language` hook and in the code element's
+     * class the way `highlight.js` and friends expect. Nothing here reads it.
+     */
+    get language() {
+        return this.getAttribute("language") ?? "";
+    }
+    set language(value) {
+        this.setAttribute("language", value);
+    }
+    /** Accessible name for the copy button. */
+    get copyLabel() {
+        return this.getAttribute("copy-label") ?? "Copy code";
+    }
+    set copyLabel(value) {
+        this.setAttribute("copy-label", value);
+    }
+    async copy() {
+        const text = this.code || this.textContent?.trim() || "";
+        if (!text) {
+            return;
+        }
+        try {
+            await navigator.clipboard.writeText(text);
+            this.markCopied(true);
+        }
+        catch {
+            // Clipboard access is refused in plenty of ordinary situations — an
+            // insecure origin, a denied permission, a browser that gates it behind a
+            // user gesture it did not see. The button reports failure by simply not
+            // confirming, rather than throwing into the host's console.
+            this.markCopied(false);
+        }
+    }
+    markCopied(copied) {
+        this.copyEl.dataset.copied = copied ? "true" : "false";
+        this.copyEl.innerHTML = copied ? COPIED_ICON : COPY_ICON;
+        this.dispatchEvent(new CustomEvent("code-copied", { bubbles: true, composed: true, detail: { copied } }));
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = null;
+        }
+        if (copied) {
+            this.resetTimer = setTimeout(() => {
+                this.copyEl.dataset.copied = "false";
+                this.copyEl.innerHTML = COPY_ICON;
+                this.resetTimer = null;
+            }, COPIED_RESET_MS);
+        }
+    }
+    disconnectedCallback() {
+        if (this.resetTimer) {
+            clearTimeout(this.resetTimer);
+            this.resetTimer = null;
+        }
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${codeStyles}</style>
+      <div part="block">
+        <pre part="pre"><code part="code"><slot></slot></code></pre>
+        <button type="button" part="copy" data-copied="false"></button>
+      </div>
+    `;
+        this.preEl = this.shadowRoot.querySelector('[part="pre"]');
+        this.codeEl = this.shadowRoot.querySelector('[part="code"]');
+        this.copyEl = this.shadowRoot.querySelector('[part="copy"]');
+        this.slotEl = this.shadowRoot.querySelector("slot");
+        this.copyEl.innerHTML = COPY_ICON;
+    }
+    setupListeners() {
+        this.copyEl.addEventListener("click", () => {
+            void this.copy();
+        });
+    }
+    update() {
+        if (!this.preEl) {
+            return;
+        }
+        const code = this.code;
+        if (code) {
+            // textContent, never innerHTML: a snippet is the string most likely on
+            // any page to contain angle brackets.
+            this.slotEl.textContent = code;
+        }
+        else {
+            this.slotEl.textContent = "";
+        }
+        const language = this.language;
+        if (language) {
+            this.codeEl.setAttribute("data-language", language);
+            this.codeEl.setAttribute("class", `language-${language}`);
+        }
+        else {
+            this.codeEl.removeAttribute("data-language");
+            this.codeEl.removeAttribute("class");
+        }
+        this.copyEl.setAttribute("aria-label", this.copyLabel);
+        this.copyEl.title = this.copyLabel;
+    }
+}
+CodeBlock.register();

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

@@ -0,0 +1,38 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * A date or time, rendered in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-date value="2026-08-25T14:30:00Z" date-style="medium" time-style="short"></box-formatted-date>
+ * ```
+ *
+ * Renders into `<time datetime="…">`, so the exact instant stays available to
+ * anything reading the document rather than looking at it — a crawler, a
+ * calendar extension, a screen reader offering "copy date". The visible text is
+ * the reader's format; the attribute is always ISO 8601.
+ *
+ * With neither `date-style` nor `time-style` set, the date alone is shown at
+ * medium width. That is the common case in a file list, and defaulting to a
+ * timestamp would put a time nobody asked for beside every filename.
+ */
+export declare class FormattedDate extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    protected usesTimeElement(): boolean;
+    /** The instant, as ISO 8601 or epoch milliseconds. */
+    get value(): string;
+    set value(next: string);
+    /** Date width, mirroring `Intl.DateTimeFormat`'s `dateStyle`. */
+    get dateStyle(): string;
+    set dateStyle(next: string);
+    /** Time width. Absent renders no time at all. */
+    get timeStyle(): string;
+    set timeStyle(next: string);
+    /** IANA zone, e.g. `America/New_York`. Absent uses the host's. */
+    get timeZone(): string;
+    set timeZone(next: string);
+    protected formatted(): {
+        machine: string;
+        text: string;
+    } | null;
+}

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

@@ -0,0 +1,90 @@
+import { FormattedValue } from "./formatted-value.js";
+import { parseInstant, resolveDateStyle } from "../../foundations/format/index.js";
+const DEFAULT_TAG_NAME = "box-formatted-date";
+/**
+ * A date or time, rendered in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-date value="2026-08-25T14:30:00Z" date-style="medium" time-style="short"></box-formatted-date>
+ * ```
+ *
+ * Renders into `<time datetime="…">`, so the exact instant stays available to
+ * anything reading the document rather than looking at it — a crawler, a
+ * calendar extension, a screen reader offering "copy date". The visible text is
+ * the reader's format; the attribute is always ISO 8601.
+ *
+ * With neither `date-style` nor `time-style` set, the date alone is shown at
+ * medium width. That is the common case in a file list, and defaulting to a
+ * timestamp would put a time nobody asked for beside every filename.
+ */
+export class FormattedDate extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["date-style", "locale", "time-style", "time-zone", "value"];
+    }
+    usesTimeElement() {
+        return true;
+    }
+    /** The instant, as ISO 8601 or epoch milliseconds. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /** Date width, mirroring `Intl.DateTimeFormat`'s `dateStyle`. */
+    get dateStyle() {
+        return this.getAttribute("date-style") ?? "";
+    }
+    set dateStyle(next) {
+        this.setAttribute("date-style", next);
+    }
+    /** Time width. Absent renders no time at all. */
+    get timeStyle() {
+        return this.getAttribute("time-style") ?? "";
+    }
+    set timeStyle(next) {
+        this.setAttribute("time-style", next);
+    }
+    /** IANA zone, e.g. `America/New_York`. Absent uses the host's. */
+    get timeZone() {
+        return this.getAttribute("time-zone") ?? "";
+    }
+    set timeZone(next) {
+        this.setAttribute("time-zone", next);
+    }
+    formatted() {
+        const instant = parseInstant(this.value);
+        if (!instant) {
+            return null;
+        }
+        const dateStyle = resolveDateStyle(this.dateStyle);
+        const timeStyle = resolveDateStyle(this.timeStyle);
+        const options = {};
+        // Only one of the two being absent is normal; both absent means the caller
+        // wants a plain date, so medium is supplied rather than leaving Intl to
+        // fall back to a bare numeric date.
+        if (dateStyle || !timeStyle) {
+            options.dateStyle = dateStyle ?? "medium";
+        }
+        if (timeStyle) {
+            options.timeStyle = timeStyle;
+        }
+        if (this.timeZone) {
+            options.timeZone = this.timeZone;
+        }
+        try {
+            return {
+                machine: instant.toISOString(),
+                text: new Intl.DateTimeFormat(this.locale, options).format(instant),
+            };
+        }
+        catch {
+            // An unknown locale or time zone throws a RangeError. The instant is
+            // still good, so fall back to ISO rather than hiding a real value over a
+            // bad option.
+            return { machine: instant.toISOString(), text: instant.toISOString() };
+        }
+    }
+}
+FormattedDate.register();

package/dist/components/output/formatted-file-size.d.ts

@@ -0,0 +1,31 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * A byte count, rendered as a readable size.
+ *
+ * ```html
+ * <box-formatted-file-size value="2517630"></box-formatted-file-size>
+ * ```
+ *
+ * The magnitude goes through `Intl.NumberFormat`, so a German reader sees
+ * "2,52 MB" rather than "2.52 MB". That is the reason this exists as a
+ * component rather than a `toFixed` call in each consumer: the decimal
+ * separator is not the same everywhere, and a file size is one of the most
+ * frequently rendered values in a content platform.
+ *
+ * Defaults to decimal units (powers of 1000, `kB`/`MB`), matching what the Box
+ * product reports. `units="binary"` switches to powers of 1024 with IEC names
+ * (`KiB`/`MiB`) for hosts that need to agree with a filesystem instead.
+ */
+export declare class FormattedFileSize extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    /** The size in bytes. */
+    get value(): string;
+    set value(next: string);
+    /** `decimal` (default) or `binary`. */
+    get units(): string;
+    set units(next: string);
+    protected formatted(): {
+        text: string;
+    } | null;
+}

package/dist/components/output/formatted-file-size.js

@@ -0,0 +1,61 @@
+import { FormattedValue } from "./formatted-value.js";
+import { parseNumber, resolveByteUnits, resolveFileSizeParts, } from "../../foundations/format/index.js";
+const DEFAULT_TAG_NAME = "box-formatted-file-size";
+/**
+ * A byte count, rendered as a readable size.
+ *
+ * ```html
+ * <box-formatted-file-size value="2517630"></box-formatted-file-size>
+ * ```
+ *
+ * The magnitude goes through `Intl.NumberFormat`, so a German reader sees
+ * "2,52 MB" rather than "2.52 MB". That is the reason this exists as a
+ * component rather than a `toFixed` call in each consumer: the decimal
+ * separator is not the same everywhere, and a file size is one of the most
+ * frequently rendered values in a content platform.
+ *
+ * Defaults to decimal units (powers of 1000, `kB`/`MB`), matching what the Box
+ * product reports. `units="binary"` switches to powers of 1024 with IEC names
+ * (`KiB`/`MiB`) for hosts that need to agree with a filesystem instead.
+ */
+export class FormattedFileSize extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["locale", "maximum-fraction-digits", "units", "value"];
+    }
+    /** The size in bytes. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /** `decimal` (default) or `binary`. */
+    get units() {
+        return resolveByteUnits(this.getAttribute("units"));
+    }
+    set units(next) {
+        this.setAttribute("units", next);
+    }
+    formatted() {
+        const bytes = parseNumber(this.value);
+        if (bytes === null) {
+            return null;
+        }
+        const { suffix, value } = resolveFileSizeParts(bytes, resolveByteUnits(this.units));
+        const requested = parseNumber(this.getAttribute("maximum-fraction-digits"));
+        // Whole bytes have no fractional part worth showing; above that, one
+        // decimal is the convention every file browser uses — "2.5 MB", not
+        // "2.517 MB", which is precision no reader asked for.
+        const maximumFractionDigits = requested ?? (suffix === "B" ? 0 : 1);
+        try {
+            return {
+                text: `${new Intl.NumberFormat(this.locale, { maximumFractionDigits }).format(value)} ${suffix}`,
+            };
+        }
+        catch {
+            return { text: `${String(value)} ${suffix}` };
+        }
+    }
+}
+FormattedFileSize.register();

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

@@ -0,0 +1,37 @@
+import { FormattedValue } from "./formatted-value.js";
+/**
+ * A number, rendered in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-number value="1234.5" format-style="currency" currency="USD"></box-formatted-number>
+ * ```
+ *
+ * The attribute is `format-style` rather than `style`, because `style` is a
+ * global HTML attribute: setting it would put CSS on the host and be silently
+ * ignored as a formatting instruction. Naming it after the `Intl` option would
+ * be tidier right up until the first host wrote `style="currency"` and watched
+ * nothing happen.
+ *
+ * `percent` follows `Intl`, which multiplies by 100: pass `0.42` to render
+ * "42%". That surprises people, so it is worth stating rather than quietly
+ * doubling the convention.
+ */
+export declare class FormattedNumber extends FormattedValue {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    /** The number to render. */
+    get value(): string;
+    set value(next: string);
+    /** `decimal` (default), `currency`, `percent` or `unit`. */
+    get formatStyle(): string;
+    set formatStyle(next: string);
+    /** 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`. */
+    get unit(): string;
+    set unit(next: string);
+    protected formatted(): {
+        text: string;
+    } | null;
+}

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

@@ -0,0 +1,106 @@
+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"]);
+/**
+ * A number, rendered in the reader's locale.
+ *
+ * ```html
+ * <box-formatted-number value="1234.5" format-style="currency" currency="USD"></box-formatted-number>
+ * ```
+ *
+ * The attribute is `format-style` rather than `style`, because `style` is a
+ * global HTML attribute: setting it would put CSS on the host and be silently
+ * ignored as a formatting instruction. Naming it after the `Intl` option would
+ * be tidier right up until the first host wrote `style="currency"` and watched
+ * nothing happen.
+ *
+ * `percent` follows `Intl`, which multiplies by 100: pass `0.42` to render
+ * "42%". That surprises people, so it is worth stating rather than quietly
+ * doubling the convention.
+ */
+export class FormattedNumber extends FormattedValue {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return [
+            "currency",
+            "format-style",
+            "locale",
+            "maximum-fraction-digits",
+            "minimum-fraction-digits",
+            "unit",
+            "value",
+        ];
+    }
+    /** The number to render. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        this.setAttribute("value", next);
+    }
+    /** `decimal` (default), `currency`, `percent` or `unit`. */
+    get formatStyle() {
+        const raw = this.getAttribute("format-style");
+        return raw && NUMBER_STYLES.has(raw) ? raw : "decimal";
+    }
+    set formatStyle(next) {
+        this.setAttribute("format-style", next);
+    }
+    /** ISO 4217 code, required by `Intl` when the style is `currency`. */
+    get currency() {
+        return this.getAttribute("currency") ?? "";
+    }
+    set currency(next) {
+        this.setAttribute("currency", next);
+    }
+    /** A sanctioned unit identifier, e.g. `megabyte`, when the style is `unit`. */
+    get unit() {
+        return this.getAttribute("unit") ?? "";
+    }
+    set unit(next) {
+        this.setAttribute("unit", next);
+    }
+    formatted() {
+        const numeric = parseNumber(this.value);
+        if (numeric === null) {
+            return null;
+        }
+        const options = { style: this.formatStyle };
+        if (this.formatStyle === "currency") {
+            if (!this.currency) {
+                // Intl throws without one. Falling back to a plain decimal keeps a real
+                // number on screen instead of hiding it over a missing attribute.
+                options.style = "decimal";
+            }
+            else {
+                options.currency = this.currency;
+            }
+        }
+        if (this.formatStyle === "unit") {
+            if (!this.unit) {
+                options.style = "decimal";
+            }
+            else {
+                options.unit = this.unit;
+            }
+        }
+        const min = parseNumber(this.getAttribute("minimum-fraction-digits"));
+        const max = parseNumber(this.getAttribute("maximum-fraction-digits"));
+        if (min !== null) {
+            options.minimumFractionDigits = min;
+        }
+        if (max !== null) {
+            options.maximumFractionDigits = max;
+        }
+        try {
+            return { text: new Intl.NumberFormat(this.locale, options).format(numeric) };
+        }
+        catch {
+            // A bad currency code, unit, or digit range throws. The number is real,
+            // so render it plainly rather than losing it.
+            return { text: String(numeric) };
+        }
+    }
+}
+FormattedNumber.register();

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

@@ -0,0 +1,44 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * Shared behaviour for the read-only `box-formatted-*` renderers.
+ *
+ * These components render a typed value and nothing else: no interaction, no
+ * state, no events. What they do share is the awkward part — resolving a
+ * locale, deciding what a broken value looks like, and keeping a
+ * machine-readable form beside the human one.
+ *
+ * **A value that cannot be formatted hides the element.** Not `Invalid Date`,
+ * not `NaN`, not the raw string echoed back. A malformed value is a host bug,
+ * and rendering its wreckage puts the bug in front of a reader who can do
+ * nothing about it. The host is left with an empty inline box, which is what a
+ * missing value should look like anyway.
+ */
+export declare abstract class FormattedValue extends BaseElement {
+    protected valueEl: HTMLElement;
+    /**
+     * The formatted text, plus an optional machine-readable form for the
+     * `datetime` attribute. `null` means the value could not be formatted.
+     */
+    protected abstract formatted(): {
+        machine?: string;
+        text: string;
+    } | null;
+    /**
+     * Whether to render into `<time>` rather than `<span>`.
+     *
+     * Only the instant-valued renderers should; `<time>` on a file size would be
+     * a lie to anything reading the document semantically.
+     */
+    protected usesTimeElement(): boolean;
+    /** Extra styles a subclass wants appended. */
+    protected valueStyles(): string;
+    /**
+     * The locale to format in. Absent means the host's own — deliberately
+     * `undefined` rather than a hardcoded tag.
+     */
+    get locale(): string | undefined;
+    set locale(value: string | undefined);
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}