@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/components/overlays/popover.js

@@ -71,7 +71,8 @@ const popoverStyles = `
     display: none;
   }
 `;
-export class BoxPopoverElement extends BaseElement {
+export class Popover extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["disabled", "label", "open", "placement"];
     }
@@ -322,11 +323,4 @@ export class BoxPopoverElement extends BaseElement {
         this.surfaceEl.style.margin = "";
     }
 }
-export const defineBoxPopoverElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxPopoverElement);
-    return BoxPopoverElement;
-};
+Popover.register();

package/dist/components/overlays/shortcuts-overlay.d.ts

@@ -0,0 +1,48 @@
+import type { CommandDescriptor } from "./command-types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The keyboard shortcuts sheet that makes keyboard-first real — the pair to
+ * `box-command-palette`.
+ *
+ * It reads the *same* `CommandDescriptor[]` the palette does and lists only
+ * the commands that declare a `shortcut`. One catalogue driving both surfaces
+ * is the point: a shortcut cannot end up documented but unreachable, or
+ * reachable but undocumented, because there is only one place to add it.
+ *
+ * Keys render as `<kbd>` elements rather than a run of text, so the markup
+ * says what it means.
+ */
+export declare class ShortcutsOverlay extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private hostEl;
+    private readonly focusRestore;
+    private wasOpen;
+    private commandsRaw;
+    private commandsCache;
+    private readonly onDocumentKeydown;
+    get open(): boolean;
+    set open(value: boolean);
+    get heading(): string;
+    set heading(value: string);
+    /**
+     * Character that opens the sheet. Defaults to `?`, the convention. Matched
+     * against the produced character, so the Shift needed to type it is already
+     * accounted for. Set empty to let the host own the trigger.
+     */
+    get hotkey(): string;
+    set hotkey(value: string);
+    /** The same catalogue `box-command-palette` takes; validated per record. */
+    get commands(): CommandDescriptor[];
+    set commands(value: CommandDescriptor[]);
+    /** Only the commands that declare a shortcut, in catalogue order. */
+    get documentedCommands(): CommandDescriptor[];
+    show(): void;
+    hide(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private dismiss;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/components/overlays/shortcuts-overlay.js

@@ -0,0 +1,385 @@
+import { groupShortcutCommands, isCommandDescriptorRecord, splitShortcutKeys, } from "./command-types.js";
+import { BaseElement } from "../../core/index.js";
+import { FocusRestore, trapTabKey } from "../../foundations/a11y/index.js";
+import { boeOverlay, boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-shortcuts-overlay";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** Editable targets where a bare-character hotkey must never fire. */
+const isTypingTarget = (target) => {
+    const element = target;
+    if (!element || typeof element.tagName !== "string") {
+        return false;
+    }
+    if (element.isContentEditable) {
+        return true;
+    }
+    const tag = element.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT";
+};
+/**
+ * The element the key was actually typed into. `event.target` is retargeted to
+ * the shadow host once an event crosses a shadow boundary, and this library
+ * wraps native controls in shadow DOM — so reading `target` on a document
+ * listener sees `box-text-field`, not the `input` inside it.
+ */
+const keyOrigin = (event) => event.composedPath()[0] ?? event.target;
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: contents;
+        }
+
+        [part="backdrop"] {
+          position: fixed;
+          inset: 0;
+          display: flex;
+          justify-content: center;
+          align-items: center;
+          padding: 1rem;
+          background: ${boeOverlay.modalBackdrop};
+          z-index: 1000;
+        }
+
+        [part="sheet"] {
+          inline-size: min(34rem, 100%);
+          max-block-size: 80vh;
+          display: grid;
+          grid-template-rows: auto 1fr;
+          border-radius: ${boeOverlay.modalRadius};
+          border: ${boePanel.border};
+          background: ${boePanel.background};
+          box-shadow: ${boeOverlay.shadow};
+          overflow: hidden;
+        }
+
+        [part="header"] {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          padding: 0.85rem 1rem;
+          border-block-end: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+        }
+
+        [part="title"] {
+          margin: 0;
+          font: inherit;
+          font-size: 1rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="close"] {
+          margin-inline-start: auto;
+          appearance: none;
+          font: inherit;
+          font-size: 0.8rem;
+          padding: 0.25rem 0.55rem;
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          border-radius: ${boeRadius.control};
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: var(--boe-token-text-text, #222222);
+          cursor: pointer;
+        }
+
+        [part="close"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="groups"] {
+          margin: 0;
+          padding: 0.6rem 1rem 1rem;
+          list-style: none;
+          overflow-y: auto;
+        }
+
+        [part="group-label"] {
+          display: block;
+          padding-block: 0.7rem 0.3rem;
+          font-size: 0.7rem;
+          font-weight: 700;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="rows"] {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+          display: grid;
+        }
+
+        [part="row"] {
+          display: flex;
+          align-items: baseline;
+          gap: 0.75rem;
+          padding: 0.35rem 0;
+        }
+
+        [part="row-label"] {
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="keys"] {
+          margin-inline-start: auto;
+          display: inline-flex;
+          align-items: center;
+          gap: 0.2rem;
+          white-space: nowrap;
+        }
+
+        [part="key"] {
+          min-inline-size: 1.4rem;
+          padding: 0.1rem 0.35rem;
+          border: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+          border-block-end-width: 2px;
+          border-radius: ${boeRadius.size};
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+          font-family: ui-monospace, monospace;
+          font-size: 0.72rem;
+          text-align: center;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="key-separator"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.7rem;
+        }
+
+        [part="empty"] {
+          padding: 1.4rem 1rem;
+          text-align: center;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="close"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+      `;
+/**
+ * The keyboard shortcuts sheet that makes keyboard-first real — the pair to
+ * `box-command-palette`.
+ *
+ * It reads the *same* `CommandDescriptor[]` the palette does and lists only
+ * the commands that declare a `shortcut`. One catalogue driving both surfaces
+ * is the point: a shortcut cannot end up documented but unreachable, or
+ * reachable but undocumented, because there is only one place to add it.
+ *
+ * Keys render as `<kbd>` elements rather than a run of text, so the markup
+ * says what it means.
+ */
+export class ShortcutsOverlay extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["commands", "heading", "hotkey", "open"];
+    }
+    hostEl;
+    focusRestore = new FocusRestore();
+    wasOpen = false;
+    commandsRaw = null;
+    commandsCache = [];
+    onDocumentKeydown = (event) => {
+        if (this.open) {
+            // Escape closes from anywhere. Focus can end up outside the sheet — the
+            // browser chrome, a host that moves it — and a modal that only closes
+            // while it still holds focus is a trap. The sheet's own handler runs
+            // first and clears `open`, so this never dismisses twice.
+            if (event.key === "Escape") {
+                event.preventDefault();
+                this.dismiss();
+            }
+            return;
+        }
+        const hotkey = this.hotkey;
+        if (!hotkey) {
+            return;
+        }
+        // A bare-character hotkey must never fire while someone is typing —
+        // "?" is a legitimate character in every text field on the page.
+        if (isTypingTarget(keyOrigin(event))) {
+            return;
+        }
+        if (event.metaKey || event.ctrlKey || event.altKey) {
+            return;
+        }
+        if (event.key === hotkey) {
+            event.preventDefault();
+            this.open = true;
+        }
+    };
+    get open() {
+        return this.hasAttribute("open");
+    }
+    set open(value) {
+        this.toggleAttribute("open", value);
+    }
+    get heading() {
+        return this.getAttribute("heading") ?? "Keyboard shortcuts";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /**
+     * Character that opens the sheet. Defaults to `?`, the convention. Matched
+     * against the produced character, so the Shift needed to type it is already
+     * accounted for. Set empty to let the host own the trigger.
+     */
+    get hotkey() {
+        const raw = this.getAttribute("hotkey");
+        return raw === null ? "?" : raw;
+    }
+    set hotkey(value) {
+        this.setAttribute("hotkey", value);
+    }
+    /** The same catalogue `box-command-palette` takes; validated per record. */
+    get commands() {
+        const raw = this.getAttribute("commands");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.commandsRaw) {
+            this.commandsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.commandsCache =
+                    Array.isArray(parsed) && parsed.every(isCommandDescriptorRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.commandsCache = [];
+            }
+        }
+        return [...this.commandsCache];
+    }
+    set commands(value) {
+        if (value.length) {
+            this.setAttribute("commands", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("commands");
+    }
+    /** Only the commands that declare a shortcut, in catalogue order. */
+    get documentedCommands() {
+        return groupShortcutCommands(this.commands).flatMap(group => group.commands);
+    }
+    show() {
+        this.open = true;
+    }
+    hide() {
+        this.open = false;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.addEventListener("keydown", this.onDocumentKeydown);
+    }
+    disconnectedCallback() {
+        document.removeEventListener("keydown", this.onDocumentKeydown);
+    }
+    dismiss() {
+        this.dispatchEvent(new CustomEvent("dismissed", { bubbles: true, composed: true }));
+        this.open = false;
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><div part="host"></div>`;
+        this.hostEl = this.shadowRoot.querySelector('[part="host"]');
+    }
+    setupListeners() {
+        this.hostEl.addEventListener("pointerdown", event => {
+            const target = event.target;
+            if (target.closest('[part="sheet"]')) {
+                return;
+            }
+            if (target.closest('[part="backdrop"]')) {
+                this.dismiss();
+            }
+        });
+        this.hostEl.addEventListener("click", event => {
+            if (event.target.closest('[part="close"]')) {
+                this.dismiss();
+            }
+        });
+        this.hostEl.addEventListener("keydown", event => {
+            const keyboardEvent = event;
+            const sheet = this.hostEl.querySelector('[part="sheet"]');
+            if (!sheet) {
+                return;
+            }
+            if (keyboardEvent.key === "Escape") {
+                keyboardEvent.preventDefault();
+                this.dismiss();
+                return;
+            }
+            if (keyboardEvent.key === "Tab") {
+                trapTabKey(keyboardEvent, sheet);
+            }
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        if (!this.open) {
+            const wasOpen = this.wasOpen;
+            this.hostEl.innerHTML = "";
+            this.wasOpen = false;
+            if (wasOpen) {
+                this.focusRestore.restore();
+            }
+            return;
+        }
+        const justOpened = !this.wasOpen;
+        this.wasOpen = true;
+        if (justOpened) {
+            this.focusRestore.capture();
+        }
+        const groups = groupShortcutCommands(this.commands);
+        const sections = groups
+            .map(group => {
+            const rows = group.commands
+                .map(command => {
+                const keys = splitShortcutKeys(command.shortcut ?? "")
+                    .map(key => `<kbd part="key">${escapeHtml(key)}</kbd>`)
+                    .join(`<span part="key-separator" aria-hidden="true">+</span>`);
+                return `
+              <li part="row" data-command-id="${escapeHtml(command.id)}">
+                <span part="row-label">${escapeHtml(command.label)}</span>
+                <span part="keys" aria-label="${escapeHtml(command.shortcut ?? "")}">${keys}</span>
+              </li>
+            `;
+            })
+                .join("");
+            return `<li part="group" data-group-key="${escapeHtml(group.key)}"><span part="group-label">${escapeHtml(group.label)}</span><ul part="rows" role="list">${rows}</ul></li>`;
+        })
+            .join("");
+        this.hostEl.innerHTML = `
+      <div part="backdrop">
+        <div part="sheet" role="dialog" aria-modal="true" aria-label="${escapeHtml(this.heading)}">
+          <div part="header">
+            <h2 part="title">${escapeHtml(this.heading)}</h2>
+            <button type="button" part="close">Close</button>
+          </div>
+          ${groups.length
+            ? `<ul part="groups" role="list">${sections}</ul>`
+            : `<div part="empty">No keyboard shortcuts are defined.</div>`}
+        </div>
+      </div>
+    `;
+        if (justOpened) {
+            this.hostEl.querySelector('[part="close"]')?.focus();
+        }
+    }
+}
+ShortcutsOverlay.register();

package/dist/components/overlays/tooltip.d.ts

@@ -1,6 +1,7 @@
 import { BaseElement } from "../../core/index.js";
 export type TooltipTheme = "default" | "error" | "callout";
-export declare class BoxTooltipElement extends BaseElement {
+export declare class Tooltip extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private positionCleanup;
     private openValue;
@@ -33,4 +34,3 @@ export declare class BoxTooltipElement extends BaseElement {
     private stopTracking;
     disconnectedCallback(): void;
 }
-export declare const defineBoxTooltipElement: (tagName?: string) => typeof BoxTooltipElement;

package/dist/components/overlays/tooltip.js

@@ -51,7 +51,7 @@ const tooltipStyles = `
     border-radius: ${boeRadius.xlarge};
     border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, rgba(255, 255, 255, 0.08));
     background: var(--boe-token-surface-tooltip-surface, #4e4e4e);
-    color: rgba(255, 255, 255, 0.94);
+    color: #ffffff;
     box-shadow: 0 16px 28px rgba(16, 24, 32, 0.18);
     line-height: 1.45;
   }
@@ -80,7 +80,8 @@ const tooltipStyles = `
     display: none;
   }
 `;
-export class BoxTooltipElement extends BaseElement {
+export class Tooltip extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["label", "open", "trigger-label", "placement", "theme"];
     }
@@ -257,11 +258,4 @@ export class BoxTooltipElement extends BaseElement {
         super.disconnectedCallback?.();
     }
 }
-export const defineBoxTooltipElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxTooltipElement);
-    return BoxTooltipElement;
-};
+Tooltip.register();

package/dist/components/visuals/illustration.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxIllustrationElement extends BaseElement {
+export declare class Illustration extends BaseElement {
+    static readonly tagName: string;
     private readonly handleDesignSystemChange;
     static get observedAttributes(): string[];
     private figureEl;
@@ -23,4 +24,3 @@ export declare class BoxIllustrationElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxIllustrationElement: (tagName?: string) => typeof BoxIllustrationElement;

package/dist/components/visuals/illustration.js

@@ -188,7 +188,8 @@ const illustrationStyles = `
     display: none;
   }
 `;
-export class BoxIllustrationElement extends BaseElement {
+export class Illustration extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     handleDesignSystemChange = () => {
         this.update();
     };
@@ -309,11 +310,4 @@ export class BoxIllustrationElement extends BaseElement {
         }
     }
 }
-export const defineBoxIllustrationElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxIllustrationElement);
-    return BoxIllustrationElement;
-};
+Illustration.register();

package/dist/core/element.d.ts

@@ -1,4 +1,7 @@
-export declare abstract class BaseElement extends HTMLElement {
+declare const HTMLElementBase: typeof HTMLElement;
+export declare abstract class BaseElement extends HTMLElementBase {
+    static readonly tagName: string;
+    static register<T extends typeof BaseElement>(this: T, tagName?: string): T;
     protected isRendered: boolean;
     constructor();
     connectedCallback(): void;
@@ -20,3 +23,4 @@ export declare abstract class BaseElement extends HTMLElement {
      */
     protected abstract update(): void;
 }
+export {};

package/dist/core/element.js

@@ -1,4 +1,32 @@
-export class BaseElement extends HTMLElement {
+const HTMLElementBase = (typeof globalThis.HTMLElement === "undefined" ? class {
+} : globalThis.HTMLElement);
+/**
+ * Registers a custom element when a browser registry is available.
+ *
+ * Component modules call this at import time. The browser guard keeps those
+ * modules safe to evaluate during SSR, while the existing-definition check
+ * makes repeated root and per-component imports idempotent.
+ */
+const registerCustomElement = (tagName, constructor) => {
+    const registry = globalThis.customElements;
+    if (!registry) {
+        return constructor;
+    }
+    const existing = registry.get(tagName);
+    if (existing) {
+        return existing;
+    }
+    registry.define(tagName, constructor);
+    return constructor;
+};
+export class BaseElement extends HTMLElementBase {
+    static tagName = "";
+    static register(tagName = this.tagName) {
+        if (!tagName) {
+            throw new TypeError("Custom element classes must declare a tagName.");
+        }
+        return registerCustomElement(tagName, this);
+    }
     isRendered = false;
     constructor() {
         super();