@unofficialbox/box-open-elements 0.5.0 → 0.6.0

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

@@ -0,0 +1,259 @@
+/**
+ * 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 const COMMAND_UNGROUPED_KEY = "";
+export const COMMAND_UNGROUPED_LABEL = "Other";
+/** Scoring weights. Tuned so an exact prefix always beats a scattered subsequence. */
+const SCORE_EXACT = 1000;
+const SCORE_PREFIX = 500;
+const SCORE_WORD_START = 250;
+const SCORE_SUBSTRING = 120;
+const SCORE_CONSECUTIVE = 8;
+const SCORE_KEYWORD = 40;
+const PENALTY_DISTANCE = 1;
+const isWordBoundary = (text, index) => index === 0 || /[\s\-_/.]/.test(text[index - 1]);
+/**
+ * Subsequence match: every query character must appear in order. Returns the
+ * matched indices, preferring word starts and consecutive runs — so "cl" hits
+ * "**Cl**ause" ahead of "Can**c**e**l**".
+ */
+const subsequence = (haystack, needle) => {
+    const ranges = [];
+    let score = 0;
+    let cursor = 0;
+    let previous = -1;
+    for (const character of needle) {
+        let index = haystack.indexOf(character, cursor);
+        if (index === -1) {
+            return null;
+        }
+        // Prefer a later occurrence if it starts a word — matching initials reads
+        // far better than matching the middle of the first word.
+        let candidate = index;
+        while (candidate !== -1 && !isWordBoundary(haystack, candidate)) {
+            const next = haystack.indexOf(character, candidate + 1);
+            if (next === -1) {
+                break;
+            }
+            if (isWordBoundary(haystack, next)) {
+                candidate = next;
+                break;
+            }
+            candidate = next;
+        }
+        if (candidate !== -1 && isWordBoundary(haystack, candidate)) {
+            index = candidate;
+        }
+        ranges.push(index);
+        if (isWordBoundary(haystack, index)) {
+            score += SCORE_WORD_START;
+        }
+        if (previous !== -1 && index === previous + 1) {
+            score += SCORE_CONSECUTIVE;
+        }
+        score -= Math.min(index - cursor, 20) * PENALTY_DISTANCE;
+        previous = index;
+        cursor = index + 1;
+    }
+    return { score, ranges };
+};
+const scoreCommand = (command, query) => {
+    const label = command.label.toLowerCase();
+    if (label === query) {
+        return { score: SCORE_EXACT, ranges: [...label].map((_, index) => index) };
+    }
+    const substringIndex = label.indexOf(query);
+    if (substringIndex === 0) {
+        return {
+            score: SCORE_PREFIX,
+            ranges: Array.from({ length: query.length }, (_, index) => index),
+        };
+    }
+    if (substringIndex > 0) {
+        return {
+            score: SCORE_SUBSTRING + (isWordBoundary(label, substringIndex) ? SCORE_WORD_START : 0),
+            ranges: Array.from({ length: query.length }, (_, index) => substringIndex + index),
+        };
+    }
+    const bySubsequence = subsequence(label, query);
+    if (bySubsequence) {
+        return bySubsequence;
+    }
+    // Keywords match but never highlight — they are not on screen.
+    for (const keyword of command.keywords ?? []) {
+        if (keyword.toLowerCase().includes(query)) {
+            return { score: SCORE_KEYWORD, ranges: [] };
+        }
+    }
+    return null;
+};
+/**
+ * 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 const matchCommands = (commands, query, options = {}) => {
+    const recent = options.recentIds ?? [];
+    const recentRank = new Map(recent.map((id, index) => [id, recent.length - index]));
+    const normalized = query.trim().toLowerCase();
+    const pool = options.hideDisabled ? commands.filter(command => !command.disabled) : commands;
+    if (!normalized) {
+        return [...pool]
+            .map(command => ({
+            command,
+            score: (recentRank.get(command.id) ?? 0) * 10,
+            ranges: [],
+        }))
+            .sort((left, right) => right.score - left.score);
+    }
+    const matches = [];
+    for (const command of pool) {
+        const scored = scoreCommand(command, normalized);
+        if (!scored) {
+            continue;
+        }
+        matches.push({
+            command,
+            // A disabled command still matches, but never outranks a usable one.
+            score: scored.score + (recentRank.get(command.id) ?? 0) - (command.disabled ? SCORE_EXACT : 0),
+            ranges: scored.ranges,
+        });
+    }
+    return matches.sort((left, right) => right.score - left.score);
+};
+/**
+ * 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 const groupCommandMatches = (matches) => {
+    const groups = new Map();
+    for (const match of matches) {
+        const key = match.command.group ?? COMMAND_UNGROUPED_KEY;
+        let group = groups.get(key);
+        if (!group) {
+            group = { key, label: key || COMMAND_UNGROUPED_LABEL, matches: [] };
+            groups.set(key, group);
+        }
+        group.matches.push(match);
+    }
+    const ordered = [...groups.values()];
+    const trailing = groups.get(COMMAND_UNGROUPED_KEY);
+    if (!trailing) {
+        return ordered;
+    }
+    return [...ordered.filter(group => group.key !== COMMAND_UNGROUPED_KEY), trailing];
+};
+/**
+ * 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 const groupShortcutCommands = (commands) => {
+    const groups = new Map();
+    for (const command of commands) {
+        if (!command.shortcut) {
+            continue;
+        }
+        const key = command.group ?? COMMAND_UNGROUPED_KEY;
+        let group = groups.get(key);
+        if (!group) {
+            group = { key, label: key || COMMAND_UNGROUPED_LABEL, commands: [] };
+            groups.set(key, group);
+        }
+        group.commands.push(command);
+    }
+    const ordered = [...groups.values()];
+    const trailing = groups.get(COMMAND_UNGROUPED_KEY);
+    if (!trailing) {
+        return ordered;
+    }
+    return [...ordered.filter(group => group.key !== COMMAND_UNGROUPED_KEY), trailing];
+};
+/**
+ * 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 const splitShortcutKeys = (shortcut) => {
+    const keys = [];
+    let buffer = "";
+    const flush = () => {
+        const key = buffer.trim();
+        if (key) {
+            keys.push(key);
+        }
+        buffer = "";
+    };
+    for (const character of shortcut) {
+        if (character !== "+") {
+            buffer += character;
+            continue;
+        }
+        if (!buffer.trim()) {
+            buffer = "+";
+        }
+        flush();
+    }
+    flush();
+    return keys;
+};
+/** Split a label into highlighted and plain runs for rendering. */
+export const splitCommandLabel = (label, ranges) => {
+    if (ranges.length === 0) {
+        return [{ text: label, match: false }];
+    }
+    const flags = new Set(ranges);
+    const parts = [];
+    let buffer = "";
+    let bufferMatch = flags.has(0);
+    for (let index = 0; index < label.length; index += 1) {
+        const isMatch = flags.has(index);
+        if (isMatch !== bufferMatch && buffer) {
+            parts.push({ text: buffer, match: bufferMatch });
+            buffer = "";
+        }
+        bufferMatch = isMatch;
+        buffer += label[index];
+    }
+    if (buffer) {
+        parts.push({ text: buffer, match: bufferMatch });
+    }
+    return parts;
+};
+/** Attribute payloads are author input — validate every record. */
+export const isCommandDescriptorRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const command = value;
+    if (typeof command.id !== "string" || command.id.length === 0) {
+        return false;
+    }
+    if (typeof command.label !== "string" || command.label.length === 0) {
+        return false;
+    }
+    if (command.keywords !== undefined) {
+        if (!Array.isArray(command.keywords)) {
+            return false;
+        }
+        if (command.keywords.some(keyword => typeof keyword !== "string")) {
+            return false;
+        }
+    }
+    return true;
+};

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

@@ -1,4 +1,8 @@
 import { BaseElement } from "../../core/index.js";
+/** Detail of the cancelable `dismiss` event: what asked the drawer to close. */
+export interface DrawerDismissDetail {
+    source: "close-button" | "backdrop" | "escape";
+}
 export declare class Drawer extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
@@ -18,6 +22,12 @@ export declare class Drawer extends BaseElement {
     set open(value: boolean);
     get position(): string;
     set position(value: string);
+    /** Width preset for side drawers, height for the bottom sheet. */
+    get size(): string;
+    set size(value: string);
+    /** Busy: a saving/loading veil over the body; Close stays reachable. */
+    get busy(): boolean;
+    set busy(value: boolean);
     get heading(): string;
     set heading(value: string);
     connectedCallback(): void;
@@ -27,6 +37,14 @@ export declare class Drawer extends BaseElement {
     private portalToBody;
     private restoreFromPortal;
     protected renderTemplate(): void;
+    /**
+     * The unsaved-changes guard, host-owned: `dismiss` is cancelable, and a
+     * host that calls `preventDefault()` keeps the drawer open — the drawer
+     * learns nothing about forms. Programmatic `close()` is not guarded; the
+     * host asked for it.
+     */
+    private requestDismiss;
     protected setupListeners(): void;
     protected update(): void;
+    private syncFooter;
 }

package/dist/components/overlays/drawer.js

@@ -18,16 +18,23 @@ const drawerStyles = `
   }
 
   [part="drawer"] {
-    width: min(${boePanel.drawerWidth}, calc(100vw - 2rem));
+    width: min(var(--drawer-size, ${boePanel.drawerWidth}), calc(100vw - 2rem));
     height: 100%;
     display: grid;
-    grid-template-rows: auto minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr) auto;
     background: ${boePanel.background};
     color: var(--boe-token-text-text, #222222);
     border: ${boePanel.border};
     box-shadow: ${boeOverlay.modalShadow};
   }
 
+  /* Size presets scale the travel axis: width for side drawers, height for
+     the bottom sheet. */
+  [part="drawer"][data-size="small"] { --drawer-size: 320px; --drawer-block-size: 220px; }
+  [part="drawer"][data-size="medium"] { --drawer-size: ${boePanel.drawerWidth}; --drawer-block-size: 320px; }
+  [part="drawer"][data-size="large"] { --drawer-size: 640px; --drawer-block-size: 480px; }
+  [part="drawer"][data-size="full"] { --drawer-size: 100vw; --drawer-block-size: calc(100vh - 3rem); }
+
   [part="drawer"][data-position="left"] {
     border-left: 0;
     border-top-right-radius: ${boeOverlay.modalRadius};
@@ -43,7 +50,7 @@ const drawerStyles = `
   [part="drawer"][data-position="bottom"] {
     width: 100%;
     max-width: none;
-    height: min(320px, calc(100vh - 3rem));
+    height: min(var(--drawer-block-size, 320px), calc(100vh - 3rem));
     border-left: 0;
     border-right: 0;
     border-bottom: 0;
@@ -51,6 +58,19 @@ const drawerStyles = `
     border-top-right-radius: ${boeOverlay.modalRadius};
   }
 
+  /* On a phone every drawer is the screen: partial overlays waste the one
+     dimension the device is short of. */
+  @media (max-width: 640px) {
+    [part="drawer"],
+    [part="drawer"][data-position="bottom"] {
+      width: 100vw;
+      max-width: none;
+      height: 100%;
+      border: 0;
+      border-radius: 0;
+    }
+  }
+
   [part="header"] {
     display: flex;
     align-items: start;
@@ -104,14 +124,56 @@ const drawerStyles = `
   ${boeNeutralInteractiveStyles('[part="close"]')}
 
   [part="body"] {
+    position: relative;
     padding: ${boeSpace[4]};
     overflow: auto;
   }
+
+  /* Footer is the third grid row: it stays put while the body scrolls. */
+  [part="footer"] {
+    padding: ${boeSpace[3]} ${boeSpace[4]};
+    border-top: 1px solid var(--boe-token-stroke-stroke, #e8e8e8);
+    background: ${boePanel.background};
+  }
+
+  [part="footer"][hidden] {
+    display: none;
+  }
+
+  [part="busy"] {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    background: color-mix(in srgb, var(--boe-token-surface-surface, #ffffff) 65%, transparent);
+  }
+
+  [part="busy"][hidden] {
+    display: none;
+  }
+
+  [part="busy-spinner"] {
+    inline-size: 1.6rem;
+    block-size: 1.6rem;
+    border-radius: 999px;
+    border: 3px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 20%, transparent);
+    border-top-color: var(--boe-token-surface-surface-brand, #0061d5);
+    animation: boe-drawer-spin 0.9s linear infinite;
+  }
+
+  @keyframes boe-drawer-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [part="busy-spinner"] { animation-duration: 1.6s; }
+  }
 `;
+const DRAWER_SIZES = new Set(["small", "medium", "large", "full"]);
 export class Drawer extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["description", "heading", "open", "position"];
+        return ["busy", "description", "heading", "open", "position", "size"];
     }
     openValue = false;
     wasOpen = false;
@@ -152,6 +214,21 @@ export class Drawer extends BaseElement {
     set position(value) {
         this.setAttribute("position", value);
     }
+    /** Width preset for side drawers, height for the bottom sheet. */
+    get size() {
+        const value = this.getAttribute("size");
+        return value && DRAWER_SIZES.has(value) ? value : "medium";
+    }
+    set size(value) {
+        this.setAttribute("size", value);
+    }
+    /** Busy: a saving/loading veil over the body; Close stays reachable. */
+    get busy() {
+        return this.hasAttribute("busy");
+    }
+    set busy(value) {
+        this.toggleAttribute("busy", Boolean(value));
+    }
     get heading() {
         return this.getAttribute("heading") ?? "Drawer";
     }
@@ -213,6 +290,23 @@ export class Drawer extends BaseElement {
         this.shadowRoot.innerHTML = `<div part="host"></div>`;
         this.hostEl = this.shadowRoot.querySelector('[part="host"]');
     }
+    /**
+     * The unsaved-changes guard, host-owned: `dismiss` is cancelable, and a
+     * host that calls `preventDefault()` keeps the drawer open — the drawer
+     * learns nothing about forms. Programmatic `close()` is not guarded; the
+     * host asked for it.
+     */
+    requestDismiss(source) {
+        const proceed = this.dispatchEvent(new CustomEvent("dismiss", {
+            bubbles: true,
+            composed: true,
+            cancelable: true,
+            detail: { source },
+        }));
+        if (proceed) {
+            this.close();
+        }
+    }
     setupListeners() {
         this.hostEl.addEventListener("click", event => {
             const target = event.target;
@@ -220,12 +314,11 @@ export class Drawer extends BaseElement {
                 return;
             }
             if (target.getAttribute("part") === "backdrop") {
-                this.close();
+                this.requestDismiss("backdrop");
                 return;
             }
             if (target.closest('[part="close"]')) {
-                this.dispatchEvent(new CustomEvent("dismiss", { bubbles: true, composed: true }));
-                this.close();
+                this.requestDismiss("close-button");
             }
         });
         this.hostEl.addEventListener("keydown", event => {
@@ -236,8 +329,7 @@ export class Drawer extends BaseElement {
             }
             if (keyboardEvent.key === "Escape") {
                 keyboardEvent.preventDefault();
-                this.dispatchEvent(new CustomEvent("dismiss", { bubbles: true, composed: true }));
-                this.close();
+                this.requestDismiss("escape");
                 return;
             }
             if (keyboardEvent.key === "Tab") {
@@ -276,15 +368,26 @@ export class Drawer extends BaseElement {
               <div part="meta">
                 <h2 id="drawer-title"></h2>
                 <p part="description" hidden></p>
+                <slot name="header"></slot>
               </div>
               <button type="button" part="close" aria-label="Close drawer">Close</button>
             </header>
             <div part="body">
               <slot></slot>
+              <div part="busy" hidden><span part="busy-spinner" aria-hidden="true"></span></div>
             </div>
+            <footer part="footer" hidden>
+              <slot name="footer"></slot>
+            </footer>
           </aside>
         </div>
       `;
+            // The footer row only exists when the host slots one: an empty sticky
+            // bar would just eat drawer height.
+            const footerSlot = this.hostEl.querySelector('slot[name="footer"]');
+            footerSlot?.addEventListener("slotchange", () => {
+                this.syncFooter();
+            });
         }
         this.backdropEl = this.hostEl.querySelector('[part="backdrop"]');
         this.drawerEl = this.hostEl.querySelector('[part="drawer"]');
@@ -298,7 +401,23 @@ export class Drawer extends BaseElement {
         }
         if (this.drawerEl) {
             this.drawerEl.dataset.position = this.position;
+            this.drawerEl.dataset.size = this.size;
+            if (this.busy) {
+                this.drawerEl.setAttribute("aria-busy", "true");
+            }
+            else {
+                this.drawerEl.removeAttribute("aria-busy");
+            }
+        }
+        const busyEl = this.hostEl.querySelector('[part="busy"]');
+        if (busyEl) {
+            busyEl.hidden = !this.busy;
         }
+        // The veil blocks the pointer; inert blocks the keyboard. Both or the
+        // busy state is a suggestion. Close (header) and footer actions stay out.
+        const bodyEl = this.hostEl.querySelector('[part="body"]');
+        bodyEl?.toggleAttribute("inert", this.busy);
+        this.syncFooter();
         if (this.titleEl) {
             this.titleEl.textContent = this.heading;
         }
@@ -313,5 +432,12 @@ export class Drawer extends BaseElement {
             });
         }
     }
+    syncFooter() {
+        const footerEl = this.hostEl.querySelector('[part="footer"]');
+        const footerSlot = this.hostEl.querySelector('slot[name="footer"]');
+        if (footerEl && footerSlot) {
+            footerEl.hidden = footerSlot.assignedNodes({ flatten: true }).length === 0;
+        }
+    }
 }
 Drawer.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;
+}