@unofficialbox/box-open-elements 0.12.0 → 0.13.0

package/dist/components/forms/tile-group.js

@@ -0,0 +1,280 @@
+import { BaseElement } from "../../core/index.js";
+import { boeRadius } from "../../foundations/geometry/index.js";
+import { boeFocusRingShadow } from "../../foundations/tokens/index.js";
+const DEFAULT_TAG_NAME = "box-tile-group";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** Attribute payloads are author input — validate every record. */
+export const isTileOptionRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const item = value;
+    return typeof item.id === "string" && typeof item.label === "string";
+};
+const tileStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  [part="group"] {
+    display: grid;
+    /* Tiles carry a label and often a description, so they need width to be
+       worth choosing over radios. Below the minimum they stack rather than
+       squeeze. */
+    grid-template-columns: repeat(auto-fit, minmax(min(14rem, 100%), 1fr));
+    gap: 0.6rem;
+    margin: 0;
+    padding: 0;
+    border: 0;
+  }
+
+  [part="legend"] {
+    padding: 0 0 0.5rem;
+    font-weight: 700;
+    color: var(--boe-token-text-text, #222222);
+  }
+
+  [part="legend"]:empty {
+    display: none;
+  }
+
+  [part="tile"] {
+    position: relative;
+    display: grid;
+    gap: 0.2rem;
+    padding: 0.75rem 0.85rem;
+    border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 85%, transparent);
+    border-radius: ${boeRadius.large};
+    background: var(--boe-token-surface-surface, #ffffff);
+    cursor: pointer;
+  }
+
+  [part="tile"]:hover:not([data-disabled="true"]) {
+    background: var(--boe-token-surface-surface-hover, #f4f4f4);
+  }
+
+  [part="tile"][data-selected="true"] {
+    border-color: var(--boe-token-surface-surface-brand, #0061d5);
+    background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+  }
+
+  [part="tile"][data-disabled="true"] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
+  /* The ring is drawn on the tile the native control sits inside, because the
+     control itself is visually hidden — without this, keyboard focus would be
+     invisible. */
+  [part="tile"]:has(input:focus-visible) {
+    box-shadow: ${boeFocusRingShadow};
+  }
+
+  /* Hidden from sight, not from the accessibility tree or the tab order: the
+     tile is a real radio or checkbox, so grouping, arrow-key behaviour and
+     form participation are the platform's rather than reimplemented. */
+  [part="control"] {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  [part="tile-label"] {
+    font-weight: 600;
+    color: var(--boe-token-text-text, #222222);
+  }
+
+  [part="tile-description"] {
+    font-size: 0.82rem;
+    line-height: 1.45;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="tile-description"]:empty {
+    display: none;
+  }
+`;
+/**
+ * Choose one option, or several, as cards rather than radios.
+ *
+ * ```html
+ * <box-tile-group name="plan" options='[{"id":"team","label":"Team"}]'></box-tile-group>
+ * ```
+ *
+ * Each tile wraps a real `<input type="radio">` or `<input type="checkbox">`,
+ * visually hidden but present in the tab order and the accessibility tree. That
+ * is the whole design: grouping, arrow-key navigation between radios, the
+ * roving focus rules, and form participation all come from the platform rather
+ * than being reimplemented on `<div>`s and then subtly diverging from what a
+ * screen reader user expects.
+ *
+ * Use it where the choice deserves explaining — a plan, a permission level, a
+ * retention policy — and a bare radio label would not have room. Where the
+ * options are one word each, radios are smaller and better.
+ */
+export class TileGroup extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["legend", "multiple", "name", "options", "value"];
+    }
+    groupEl;
+    legendEl;
+    optionsSignature = "";
+    /** The choices, as JSON. */
+    get options() {
+        const raw = this.getAttribute("options");
+        if (!raw) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) && parsed.every(isTileOptionRecord)
+                ? parsed
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set options(value) {
+        this.setAttribute("options", JSON.stringify(value));
+    }
+    /** Several selections rather than one. Switches radios for checkboxes. */
+    get multiple() {
+        return this.hasAttribute("multiple");
+    }
+    set multiple(value) {
+        this.toggleAttribute("multiple", value);
+    }
+    /** The radio group name. Required for radios to behave as one group. */
+    get name() {
+        return this.getAttribute("name") ?? "tile-group";
+    }
+    set name(value) {
+        this.setAttribute("name", value);
+    }
+    /** Selected ids, comma-separated. A single id when not `multiple`. */
+    get value() {
+        return this.getAttribute("value") ?? "";
+    }
+    set value(next) {
+        if (!next) {
+            this.removeAttribute("value");
+            return;
+        }
+        this.setAttribute("value", next);
+    }
+    /** Selected ids as an array, which is what a host actually wants. */
+    get selected() {
+        return this.value
+            .split(",")
+            .map(part => part.trim())
+            .filter(Boolean);
+    }
+    get legend() {
+        return this.getAttribute("legend") ?? "";
+    }
+    set legend(value) {
+        this.setAttribute("legend", value);
+    }
+    optionsKey() {
+        return `${this.getAttribute("options") ?? ""}|${String(this.multiple)}|${this.name}`;
+    }
+    rebuild() {
+        const type = this.multiple ? "checkbox" : "radio";
+        this.groupEl.innerHTML = this.options
+            .map(option => {
+            const id = escapeHtml(option.id);
+            return `
+          <label part="tile" data-option-id="${id}" data-selected="false" data-disabled="${option.disabled ? "true" : "false"}">
+            <input
+              part="control"
+              type="${type}"
+              name="${escapeHtml(this.name)}"
+              value="${id}"
+              ${option.disabled ? "disabled" : ""}
+            />
+            <span part="tile-label">${escapeHtml(option.label)}</span>
+            <span part="tile-description">${escapeHtml(option.description ?? "")}</span>
+          </label>
+        `;
+        })
+            .join("");
+    }
+    syncSelection() {
+        const selected = new Set(this.selected);
+        this.groupEl.querySelectorAll('[part="tile"]').forEach(tile => {
+            const id = tile.dataset.optionId ?? "";
+            const isSelected = selected.has(id);
+            tile.dataset.selected = isSelected ? "true" : "false";
+            const control = tile.querySelector('[part="control"]');
+            if (control) {
+                control.checked = isSelected;
+            }
+        });
+    }
+    readSelection() {
+        return Array.from(this.groupEl.querySelectorAll('[part="control"]'))
+            .filter(input => input.checked)
+            .map(input => input.value);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${tileStyles}</style>
+      <fieldset part="group">
+        <legend part="legend"></legend>
+      </fieldset>
+    `;
+        this.groupEl = this.shadowRoot.querySelector('[part="group"]');
+        this.legendEl = this.shadowRoot.querySelector('[part="legend"]');
+    }
+    setupListeners() {
+        this.groupEl.addEventListener("change", () => {
+            const next = this.readSelection();
+            this.value = next.join(",");
+            this.dispatchEvent(new CustomEvent("tile-change", {
+                bubbles: true,
+                composed: true,
+                detail: { selected: next },
+            }));
+        });
+    }
+    update() {
+        if (!this.groupEl) {
+            return;
+        }
+        const nextKey = this.optionsKey();
+        if (nextKey !== this.optionsSignature) {
+            this.optionsSignature = nextKey;
+            // The legend lives inside the fieldset and is wiped by the rebuild, so it
+            // is re-created rather than queried once at render time.
+            this.rebuild();
+            const legend = document.createElement("legend");
+            legend.setAttribute("part", "legend");
+            this.groupEl.prepend(legend);
+            this.legendEl = legend;
+        }
+        this.legendEl.textContent = this.legend;
+        this.syncSelection();
+    }
+}
+TileGroup.register();

package/dist/components/output/code-block.d.ts

@@ -0,0 +1,49 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * 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 declare class CodeBlock extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private preEl;
+    private codeEl;
+    private copyEl;
+    private slotEl;
+    private resetTimer;
+    /** The source to render. */
+    get code(): string;
+    set code(value: string);
+    /**
+     * 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(): string;
+    set language(value: string);
+    /** Accessible name for the copy button. */
+    get copyLabel(): string;
+    set copyLabel(value: string);
+    private copy;
+    private markCopied;
+    disconnectedCallback(): void;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

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();