@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/components/overlays/command-palette.js

@@ -0,0 +1,537 @@
+import { groupCommandMatches, isCommandDescriptorRecord, matchCommands, splitCommandLabel, } 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";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+const DEFAULT_TAG_NAME = "box-command-palette";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: contents;
+        }
+
+        [part="backdrop"] {
+          position: fixed;
+          inset: 0;
+          display: flex;
+          justify-content: center;
+          align-items: start;
+          padding-block-start: 12vh;
+          background: ${boeOverlay.modalBackdrop};
+          z-index: 1000;
+        }
+
+        [part="palette"] {
+          inline-size: min(40rem, calc(100vw - 2rem));
+          max-block-size: 70vh;
+          display: grid;
+          grid-template-rows: auto 1fr auto;
+          border-radius: ${boeOverlay.modalRadius};
+          border: ${boePanel.border};
+          background: ${boePanel.background};
+          box-shadow: ${boeOverlay.shadow};
+          overflow: hidden;
+        }
+
+        [part="search-row"] {
+          display: flex;
+          align-items: center;
+          gap: 0.5rem;
+          padding: 0.7rem 0.9rem;
+          border-block-end: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+        }
+
+        [part="search-icon"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="search"] {
+          flex: 1;
+          appearance: none;
+          border: none;
+          background: none;
+          font: inherit;
+          font-size: 1rem;
+          color: var(--boe-token-text-text, #1f1e1b);
+          outline: none;
+        }
+
+        [part="search"]::placeholder {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="results"] {
+          margin: 0;
+          padding: 0.35rem;
+          list-style: none;
+          overflow-y: auto;
+        }
+
+        [part="group-label"] {
+          padding: 0.45rem 0.6rem 0.25rem;
+          font-size: 0.7rem;
+          font-weight: 700;
+          letter-spacing: 0.08em;
+          text-transform: uppercase;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="option"] {
+          display: flex;
+          align-items: center;
+          gap: 0.6rem;
+          padding: 0.5rem 0.6rem;
+          border-radius: ${boeOverlay.itemRadius};
+          cursor: pointer;
+          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        [part="option"][aria-selected="true"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 12%, transparent);
+        }
+
+        [part="option"][aria-disabled="true"] {
+          opacity: 0.5;
+          cursor: not-allowed;
+        }
+
+        [part="option-text"] {
+          display: grid;
+          gap: 0.1rem;
+          min-inline-size: 0;
+        }
+
+        [part="option-label"] {
+          color: var(--boe-token-text-text, #1f1e1b);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+
+        [part="match"] {
+          font-weight: 700;
+          color: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="option-description"] {
+          font-size: 0.78rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+
+        [part="shortcut"] {
+          margin-inline-start: auto;
+          padding: 0.1rem 0.35rem;
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 90%, transparent);
+          border-radius: ${boeRadius.size};
+          font-family: ui-monospace, monospace;
+          font-size: 0.72rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          white-space: nowrap;
+        }
+
+        [part="empty"] {
+          padding: 1.4rem 0.9rem;
+          text-align: center;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="footer"] {
+          display: flex;
+          gap: 0.9rem;
+          padding: 0.45rem 0.9rem;
+          border-block-start: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+          font-size: 0.72rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="footer-key"] {
+          font-family: ui-monospace, monospace;
+          font-weight: 700;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+          [part="option"] {
+            transition: none;
+          }
+        }
+      `;
+/**
+ * Keyboard-first action launcher (CLM gap 4) over the existing overlay and
+ * listbox machinery.
+ *
+ * Follows the ARIA combobox-with-listbox pattern: focus never leaves the
+ * search input, so typing and navigating are the same gesture. The active
+ * option is communicated with `aria-activedescendant` rather than by moving
+ * focus, which is what lets Up/Down browse results while the query stays
+ * editable.
+ *
+ * The host owns what commands mean — the palette only reports the choice.
+ */
+export class CommandPalette extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["commands", "hide-disabled", "hotkey", "open", "placeholder"];
+    }
+    hostEl;
+    focusRestore = new FocusRestore();
+    openValue = false;
+    wasOpen = false;
+    query = "";
+    activeIndex = 0;
+    /** Flattened, ranked matches — the index space the keyboard walks. */
+    rankedMatches = [];
+    commandsRaw = null;
+    commandsCache = [];
+    recentIdsValue = [];
+    onDocumentKeydown = (event) => {
+        const hotkey = this.hotkey;
+        if (!hotkey || this.openValue) {
+            return;
+        }
+        // `mod` means Cmd on Apple platforms and Ctrl elsewhere — the same
+        // physical gesture, which is what "⌘K or Ctrl+K" actually means.
+        const parts = hotkey.toLowerCase().split("+").map(part => part.trim());
+        const key = parts[parts.length - 1] ?? "";
+        const wantsMod = parts.includes("mod");
+        const wantsShift = parts.includes("shift");
+        const wantsAlt = parts.includes("alt");
+        const modPressed = event.metaKey || event.ctrlKey;
+        if (event.key.toLowerCase() === key &&
+            (!wantsMod || modPressed) &&
+            (wantsMod || !modPressed) &&
+            wantsShift === event.shiftKey &&
+            wantsAlt === event.altKey) {
+            event.preventDefault();
+            this.open = true;
+        }
+    };
+    get open() {
+        return this.hasAttribute("open");
+    }
+    set open(value) {
+        this.toggleAttribute("open", value);
+    }
+    get placeholder() {
+        return this.getAttribute("placeholder") ?? "Type a command or search…";
+    }
+    set placeholder(value) {
+        this.setAttribute("placeholder", value);
+    }
+    /**
+     * Global shortcut that opens the palette, e.g. `mod+k`. `mod` resolves to
+     * Cmd or Ctrl per platform. Omit to let the host own the trigger.
+     */
+    get hotkey() {
+        return this.getAttribute("hotkey") ?? "";
+    }
+    set hotkey(value) {
+        this.setAttribute("hotkey", value);
+    }
+    get hideDisabled() {
+        return this.hasAttribute("hide-disabled");
+    }
+    set hideDisabled(value) {
+        this.toggleAttribute("hide-disabled", value);
+    }
+    /** Command catalogue; JSON payloads are 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");
+    }
+    /** Most recently run command ids, most recent first; boosts ranking. */
+    get recentIds() {
+        return [...this.recentIdsValue];
+    }
+    set recentIds(value) {
+        this.recentIdsValue = [...value];
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    /** The ranked matches currently on screen. */
+    get visibleCommands() {
+        return this.rankedMatches.map(match => match.command);
+    }
+    show() {
+        this.open = true;
+    }
+    hide() {
+        this.open = false;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.addEventListener("keydown", this.onDocumentKeydown);
+    }
+    disconnectedCallback() {
+        document.removeEventListener("keydown", this.onDocumentKeydown);
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "open" && oldValue !== newValue && this.hasAttribute("open")) {
+            // Every opening starts from a clean query — a palette that reopens
+            // holding the last search is a nuisance, not a convenience.
+            this.query = "";
+            this.activeIndex = 0;
+        }
+        super.attributeChangedCallback(name, oldValue, newValue);
+    }
+    runActive() {
+        const match = this.rankedMatches[this.activeIndex];
+        if (!match || match.command.disabled) {
+            return;
+        }
+        this.dispatchEvent(new CustomEvent("command-selected", {
+            bubbles: true,
+            composed: true,
+            detail: { command: match.command },
+        }));
+        this.open = false;
+    }
+    moveActive(delta) {
+        if (this.rankedMatches.length === 0) {
+            return;
+        }
+        // Wrap: from the last result, Down returns to the first. A palette is a
+        // short list, and dead-ending at the bottom just costs a keystroke.
+        const next = (this.activeIndex + delta + this.rankedMatches.length) % this.rankedMatches.length;
+        this.activeIndex = next;
+        this.update();
+        this.scrollActiveIntoView();
+    }
+    scrollActiveIntoView() {
+        const active = this.hostEl.querySelector('[part="option"][aria-selected="true"]');
+        // Not every DOM provides scrollIntoView (jsdom, SSR shims). Keeping the
+        // active option in view is an enhancement — never a reason to throw and
+        // take the whole keypress down with it.
+        active?.scrollIntoView?.({ block: "nearest" });
+    }
+    optionHtml(match, index) {
+        const { command } = match;
+        const label = splitCommandLabel(command.label, match.ranges)
+            .map(part => part.match
+            ? `<span part="match">${escapeHtml(part.text)}</span>`
+            : escapeHtml(part.text))
+            .join("");
+        return `
+      <li
+        part="option"
+        role="option"
+        id="command-option-${String(index)}"
+        data-command-id="${escapeHtml(command.id)}"
+        data-index="${String(index)}"
+        aria-selected="${index === this.activeIndex ? "true" : "false"}"
+        ${command.disabled ? 'aria-disabled="true"' : ""}
+      >
+        <span part="option-text">
+          <span part="option-label">${label}</span>
+          ${command.description ? `<span part="option-description">${escapeHtml(command.description)}</span>` : ""}
+        </span>
+        ${command.shortcut ? `<span part="shortcut">${escapeHtml(command.shortcut)}</span>` : ""}
+      </li>
+    `;
+    }
+    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="palette"]')) {
+                return;
+            }
+            if (target.closest('[part="backdrop"]')) {
+                this.dispatchEvent(new CustomEvent("dismissed", { bubbles: true, composed: true }));
+                this.open = false;
+            }
+        });
+        this.hostEl.addEventListener("click", event => {
+            const option = event.target.closest('[part="option"]');
+            if (!option || !this.hostEl.contains(option)) {
+                return;
+            }
+            this.activeIndex = Number(option.getAttribute("data-index") ?? "0");
+            this.runActive();
+        });
+        this.hostEl.addEventListener("input", event => {
+            const input = event.target;
+            if (input.getAttribute("part") !== "search") {
+                return;
+            }
+            this.query = input.value;
+            this.activeIndex = 0;
+            this.update();
+        });
+        this.hostEl.addEventListener("keydown", event => {
+            const keyboardEvent = event;
+            const palette = this.hostEl.querySelector('[part="palette"]');
+            if (!palette) {
+                return;
+            }
+            switch (keyboardEvent.key) {
+                case "Escape":
+                    keyboardEvent.preventDefault();
+                    this.dispatchEvent(new CustomEvent("dismissed", { bubbles: true, composed: true }));
+                    this.open = false;
+                    return;
+                case "ArrowDown":
+                    keyboardEvent.preventDefault();
+                    this.moveActive(1);
+                    return;
+                case "ArrowUp":
+                    keyboardEvent.preventDefault();
+                    this.moveActive(-1);
+                    return;
+                case "Home":
+                    keyboardEvent.preventDefault();
+                    this.activeIndex = 0;
+                    this.update();
+                    this.scrollActiveIntoView();
+                    return;
+                case "End":
+                    keyboardEvent.preventDefault();
+                    this.activeIndex = Math.max(0, this.rankedMatches.length - 1);
+                    this.update();
+                    this.scrollActiveIntoView();
+                    return;
+                case "Enter":
+                    keyboardEvent.preventDefault();
+                    this.runActive();
+                    return;
+                case "Tab":
+                    trapTabKey(keyboardEvent, palette);
+                    return;
+                default:
+            }
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        this.openValue = this.open;
+        if (!this.openValue) {
+            const wasOpen = this.wasOpen;
+            this.hostEl.innerHTML = "";
+            this.rankedMatches = [];
+            this.wasOpen = false;
+            if (wasOpen) {
+                this.focusRestore.restore();
+            }
+            return;
+        }
+        const justOpened = !this.wasOpen;
+        this.wasOpen = true;
+        if (justOpened) {
+            this.focusRestore.capture();
+        }
+        const groups = groupCommandMatches(matchCommands(this.commands, this.query, {
+            recentIds: this.recentIdsValue,
+            hideDisabled: this.hideDisabled,
+        }));
+        // Flatten in *rendered* order, not rank order. Grouping can reorder
+        // matches relative to their rank — the ungrouped section always trails —
+        // so indexing the keyboard off the rank order would highlight one option
+        // while Enter ran a different one.
+        this.rankedMatches = groups.flatMap(group => group.matches);
+        if (this.activeIndex >= this.rankedMatches.length) {
+            this.activeIndex = Math.max(0, this.rankedMatches.length - 1);
+        }
+        // One flat index space across groups, so Up/Down crosses section
+        // headings the way a reader expects.
+        let index = 0;
+        const sections = groups
+            .map(group => {
+            const options = group.matches.map(match => this.optionHtml(match, index++)).join("");
+            return `<li part="group" role="presentation"><span part="group-label" role="presentation">${escapeHtml(group.label)}</span><ul part="group-options" role="group" aria-label="${escapeHtml(group.label)}">${options}</ul></li>`;
+        })
+            .join("");
+        const activeId = this.rankedMatches.length > 0 ? `command-option-${String(this.activeIndex)}` : "";
+        if (justOpened || !this.hostEl.querySelector('[part="palette"]')) {
+            this.hostEl.innerHTML = `
+        <div part="backdrop">
+          <div part="palette" role="dialog" aria-modal="true" aria-label="Command palette">
+            <div part="search-row">
+              <span part="search-icon" aria-hidden="true">⌕</span>
+              <input
+                part="search"
+                type="text"
+                role="combobox"
+                aria-expanded="true"
+                aria-controls="command-results"
+                aria-autocomplete="list"
+                aria-label="${escapeHtml(this.placeholder)}"
+                placeholder="${escapeHtml(this.placeholder)}"
+                autocomplete="off"
+                spellcheck="false"
+              >
+            </div>
+            <ul part="results" id="command-results" role="listbox" aria-label="Commands"></ul>
+            <div part="empty" hidden>No matching commands.</div>
+            <div part="footer">
+              <span><span part="footer-key">↑↓</span> navigate</span>
+              <span><span part="footer-key">⏎</span> run</span>
+              <span><span part="footer-key">esc</span> close</span>
+            </div>
+          </div>
+        </div>
+      `;
+        }
+        const input = this.hostEl.querySelector('[part="search"]');
+        const results = this.hostEl.querySelector('[part="results"]');
+        const empty = this.hostEl.querySelector('[part="empty"]');
+        results.innerHTML = sections;
+        results.hidden = this.rankedMatches.length === 0;
+        empty.hidden = this.rankedMatches.length > 0;
+        if (input.value !== this.query) {
+            input.value = this.query;
+        }
+        if (activeId) {
+            input.setAttribute("aria-activedescendant", activeId);
+        }
+        else {
+            input.removeAttribute("aria-activedescendant");
+        }
+        if (justOpened) {
+            input.focus();
+        }
+    }
+}
+CommandPalette.register();

package/dist/components/overlays/command-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Command model and the pure match/rank/group engine behind
+ * `box-command-palette`. DOM-free and deterministic, so ranking can be
+ * tested and reused (a host can drive its own launcher from the same
+ * functions).
+ */
+export interface CommandDescriptor {
+    id: string;
+    label: string;
+    /** Secondary line: what the command does, or where it acts. */
+    description?: string;
+    /** Section heading. Commands without one land in a trailing group. */
+    group?: string;
+    /**
+     * Extra terms that should match but are not shown — synonyms, the old
+     * name for a renamed action, the entity a command acts on.
+     */
+    keywords?: string[];
+    /** Rendered hint such as `⌘K`; purely presentational. */
+    shortcut?: string;
+    disabled?: boolean;
+}
+export interface CommandMatch {
+    command: CommandDescriptor;
+    /** Higher is better. */
+    score: number;
+    /** Indices into `label` that matched, for highlighting. Empty on an unfiltered list. */
+    ranges: number[];
+}
+export interface CommandGroup {
+    /** Empty string for the ungrouped trailing section. */
+    key: string;
+    label: string;
+    matches: CommandMatch[];
+}
+export declare const COMMAND_UNGROUPED_KEY = "";
+export declare const COMMAND_UNGROUPED_LABEL = "Other";
+export interface MatchCommandsOptions {
+    /** Command ids used most recently, most recent first. Boosts ranking. */
+    recentIds?: readonly string[];
+    /** Drop disabled commands entirely instead of ranking them last. */
+    hideDisabled?: boolean;
+}
+/**
+ * Rank commands against a query.
+ *
+ * An empty query returns everything in recent-first then input order, which
+ * is what a palette should show when it opens. Ties are broken by input order
+ * (the sort is stable), never by object identity, so the same catalogue always
+ * renders the same way.
+ */
+export declare const matchCommands: (commands: readonly CommandDescriptor[], query: string, options?: MatchCommandsOptions) => CommandMatch[];
+/**
+ * Bucket ranked matches into sections, preserving rank order both between
+ * groups (a group leads where its best match ranks) and within them.
+ * Ungrouped commands trail.
+ */
+export declare const groupCommandMatches: (matches: readonly CommandMatch[]) => CommandGroup[];
+export interface ShortcutGroup {
+    key: string;
+    label: string;
+    commands: CommandDescriptor[];
+}
+/**
+ * The commands that declare a keyboard shortcut, grouped for a shortcuts
+ * sheet. Takes the same catalogue the palette does, so one list drives both
+ * surfaces and a shortcut can never be documented but unreachable — or
+ * reachable but undocumented.
+ *
+ * Groups keep catalogue order, with the ungrouped section trailing, matching
+ * how the palette sections its results.
+ */
+export declare const groupShortcutCommands: (commands: readonly CommandDescriptor[]) => ShortcutGroup[];
+/**
+ * Split a shortcut string into its keys: `mod+shift+k` → `["mod","shift","k"]`.
+ * Rendering each key separately is what lets a sheet show them as `<kbd>`
+ * elements rather than one opaque run of text.
+ *
+ * `+` is both the separator and a real key — `mod++` is how you write the zoom
+ * shortcut. A `+` with no key pending in front of it is the key itself, so
+ * `mod++` and `ctrl + +` both give `["mod", "+"]` rather than dropping it.
+ */
+export declare const splitShortcutKeys: (shortcut: string) => string[];
+/** Split a label into highlighted and plain runs for rendering. */
+export declare const splitCommandLabel: (label: string, ranges: readonly number[]) => Array<{
+    text: string;
+    match: boolean;
+}>;
+/** Attribute payloads are author input — validate every record. */
+export declare const isCommandDescriptorRecord: (value: unknown) => value is CommandDescriptor;