@unofficialbox/box-open-elements 0.11.0 → 0.13.0

package/dist/components/forms/calendar.js

@@ -172,6 +172,15 @@ const calendarStyles = `
     background: var(--boe-token-surface-surface-brand-hover, #006ae9);
   }
 
+  /* The span between the endpoints. A tint rather than the brand fill, so the
+     two chosen dates stay the things the eye lands on — the middle is context,
+     not a selection the reader made. */
+  [part~="day"][data-in-range="true"]:not([data-selected="true"]) {
+    background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+    border-color: transparent;
+    color: var(--boe-token-text-text, #222222);
+  }
+
   [part~="day"]:focus-visible {
     outline: none;
     box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 24%, transparent);
@@ -185,7 +194,7 @@ const calendarStyles = `
 export class Calendar extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["disabled", "max", "min", "month", "today", "value"];
+        return ["disabled", "end", "max", "min", "mode", "month", "start", "today", "value"];
     }
     /** The date the roving tabindex currently points at. */
     activeDate = null;
@@ -283,11 +292,83 @@ export class Calendar extends BaseElement {
         const next = new Date(Date.UTC(y, m - 1 + delta, 1));
         this.goToMonth(next.getUTCFullYear(), next.getUTCMonth() + 1);
     }
+    /**
+     * `single` (default) or `range`.
+     *
+     * Range mode uses `start`/`end` rather than overloading `value`: a single
+     * attribute holding two dates would have to invent a separator, and every
+     * host would then have to parse it back out.
+     */
+    get mode() {
+        return this.getAttribute("mode") === "range" ? "range" : "single";
+    }
+    set mode(next) {
+        this.setAttribute("mode", next);
+    }
+    /** First date of the range, ISO. */
+    get start() {
+        return this.getAttribute("start") ?? "";
+    }
+    set start(next) {
+        if (!next) {
+            this.removeAttribute("start");
+            return;
+        }
+        this.setAttribute("start", next);
+    }
+    /** Last date of the range, ISO. Empty while only one end has been picked. */
+    get end() {
+        return this.getAttribute("end") ?? "";
+    }
+    set end(next) {
+        if (!next) {
+            this.removeAttribute("end");
+            return;
+        }
+        this.setAttribute("end", next);
+    }
+    /**
+     * Advance the range by one click.
+     *
+     * Three states, cycling: nothing chosen picks a start; a start alone closes
+     * the range; a complete range starts over. Picking an earlier day as the
+     * second click swaps the ends rather than rejecting it — a reader dragging
+     * backwards through a calendar means the same thing as dragging forwards,
+     * and refusing it would be pedantry.
+     */
+    selectRange(iso) {
+        const start = this.start;
+        const end = this.end;
+        if (!start || end) {
+            this.start = iso;
+            this.end = "";
+        }
+        else if (iso < start) {
+            this.end = start;
+            this.start = iso;
+        }
+        else {
+            this.end = iso;
+        }
+        this.dispatchEvent(new CustomEvent("range-changed", {
+            bubbles: true,
+            composed: true,
+            detail: { end: this.end, start: this.start },
+        }));
+    }
     selectDate(date) {
         const iso = toISO(date);
         if (this.disabled || this.isOutOfRange(iso)) {
             return;
         }
+        if (this.mode === "range") {
+            this.selectRange(iso);
+            this.setAttribute("month", `${date.y}-${pad(date.m)}`);
+            this.activeDate = date;
+            this.update();
+            this.focusActive();
+            return;
+        }
         this.setAttribute("value", iso);
         // Keep the grid on the month of the chosen day.
         this.setAttribute("month", `${date.y}-${pad(date.m)}`);
@@ -446,6 +527,9 @@ export class Calendar extends BaseElement {
         }
         const { y, m } = this.displayedMonth();
         const selected = parseISO(this.value);
+        const isRange = this.mode === "range";
+        const rangeStart = isRange ? this.start : "";
+        const rangeEnd = isRange ? this.end : "";
         const active = this.resolveActiveDate();
         const activeIso = toISO({ y, m, d: clampDay(y, m, active.d) });
         const todayIso = toISO(this.resolveToday());
@@ -459,7 +543,14 @@ export class Calendar extends BaseElement {
         }
         for (let day = 1; day <= total; day += 1) {
             const iso = toISO({ y, m, d: day });
-            const isSelected = selected ? toISO(selected) === iso : false;
+            const isSelected = isRange
+                ? iso === rangeStart || iso === rangeEnd
+                : selected
+                    ? toISO(selected) === iso
+                    : false;
+            // Strictly between the ends: the endpoints are "selected", not "in range",
+            // so they keep the brand fill rather than the tint.
+            const inRange = isRange && rangeStart !== "" && rangeEnd !== "" && iso > rangeStart && iso < rangeEnd;
             const isToday = iso === todayIso;
             const isActive = iso === activeIso;
             const outOfRange = this.isOutOfRange(iso);
@@ -470,6 +561,7 @@ export class Calendar extends BaseElement {
           role="gridcell"
           data-date="${iso}"
           data-selected="${isSelected ? "true" : "false"}"
+          data-in-range="${inRange ? "true" : "false"}"
           data-today="${isToday ? "true" : "false"}"
           tabindex="${isActive && !disabled ? "0" : "-1"}"
           aria-selected="${isSelected ? "true" : "false"}"

package/dist/components/forms/tile-group.d.ts

@@ -0,0 +1,58 @@
+import { BaseElement } from "../../core/index.js";
+/** One choice. `description` is the second line; `disabled` greys it out. */
+export interface TileOption {
+    description?: string;
+    disabled?: boolean;
+    id: string;
+    label: string;
+}
+/** Attribute payloads are author input — validate every record. */
+export declare const isTileOptionRecord: (value: unknown) => value is TileOption;
+/**
+ * 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 declare class TileGroup extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private groupEl;
+    private legendEl;
+    private optionsSignature;
+    /** The choices, as JSON. */
+    get options(): TileOption[];
+    set options(value: TileOption[]);
+    /** Several selections rather than one. Switches radios for checkboxes. */
+    get multiple(): boolean;
+    set multiple(value: boolean);
+    /** The radio group name. Required for radios to behave as one group. */
+    get name(): string;
+    set name(value: string);
+    /** Selected ids, comma-separated. A single id when not `multiple`. */
+    get value(): string;
+    set value(next: string);
+    /** Selected ids as an array, which is what a host actually wants. */
+    get selected(): string[];
+    get legend(): string;
+    set legend(value: string);
+    private optionsKey;
+    private rebuild;
+    private syncSelection;
+    private readSelection;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

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;
+}